# ev.energy / Eve Documentation > Documentation for Eve (the ev.energy AI assistant) and the Connect (beta) driver surface, plus the Insight platform, agents, and developer/API reference. This file contains all documentation content in a single document following the llmstxt.org standard. ## Creating Agents > **Module:** `operations:agents` | **Role:** Any member | **Licence:** Pro+ Any workspace member can create custom agents via Eve using the `create_agent` tool. ## Required Fields | Field | Type | Description | |-------|------|-------------| | `agent_id` | string | Unique identifier (kebab-case, e.g., `grid-planning-assistant`) | | `name` | string | Display name | | `description` | string | What the agent does (shown in agent list) | | `prompt` | string | System prompt — defines personality, expertise, and constraints | ## Optional Fields | Field | Default | Description | |-------|---------|-------------| | `emoji` | `"robot"` | Display emoji | | `tool_groups` | `["all"]` | Which tool groups the agent can access | | `temperature` | 0.7 | LLM temperature (0.0-1.0) | | `model` | inherited | `"sonnet"`, `"opus"`, `"haiku"`, or null (inherit from parent) | | `pattern` | `"bespoke"` | LANES pattern — sets default objective/kr if not provided | | `objective` | `""` | What the agent aims to achieve | | `kr` | `""` | Key result — how success is measured | | `visibility` | `"workspace"` | `"workspace"` (all members) or `"restricted"` | | `visible_to` | `[]` | User IDs (only when visibility is `"restricted"`) | | `triggers` | `[]` | Autonomous execution triggers | | `module_id` | null | Module to associate with (enables dispatch tool) | | `mcp_connections` | `[]` | External MCP server connections — e.g. `["snowflake"]` (workspace must have these integrated; call `list_agent_tool_groups()` to see what's available) | ## External Integrations (MCP) Agents can call external services at dispatch time by declaring `mcp_connections`. Credentials are resolved from the workspace's connected integrations — the agent never handles secrets directly. | Integration | Scope | What it provides | |-------------|-------|-----------------| | `"holistics"` | Personal only | Query analytics and dashboards via Holistics MCP (API key per-person). Cannot be used in `mcp_connections` — it is user-only and would silently fail for other workspace members and scheduled triggers. | | `"snowflake"` | Workspace | Query Snowflake data via Cortex Agents MCP. | Use `list_agent_tool_groups()` to see which integrations are actively connected for the current workspace. Each entry includes a `can_be_stored_in_mcp_connections` flag — entries where this is `false` (user-scoped integrations like Holistics) cannot be used in `mcp_connections` and will be rejected at create/update time. Non-MCP integrations (e.g. Slack) cannot be used as `mcp_connections` either. ## Tool Groups Agents declare which tool groups they can access: | Group | Tools | Description | |-------|-------|-------------| | `simulation` | Scenario creation, analysis, comparison | Energy simulation tools | | `simulation_core` | Core simulation without location/hosting | Subset for constrained contexts | | `utility` | format_generic_chart, read_chart_data | Data visualization | | `policy` | All policy agent tools | Regulatory intelligence | | `websearch` | Web search | External information retrieval | | `all` | Everything above | Full access (default) | ## Triggers Add autonomous execution with optional delivery channels: ```json { "triggers": [ { "type": "cron", "schedule": "every monday at 06:00 UTC", "task_prompt": "Generate weekly regulatory digest", "delivery": ["slack_dm", "email"] } ] } ``` The schedule string is human-readable and always UTC. Accepted forms: `daily at HH:MM UTC`, `every at HH:MM UTC`, `every weekday at HH:MM UTC`. Raw crontab notation (`"0 6 * * 1"`) is no longer accepted — it was the source of a day-of-week ambiguity that shifted some agents' fire days by one. | Trigger Type | Required Fields | |-------------|----------------| | `cron` | `schedule` (human-readable UTC string), optional `task_prompt` | | `event` | `event` (event name) | | `webhook` | `webhook_path` | | `manual` | (none — triggered via Eve) | ### Delivery Channels When a triggered agent completes, its output can be pushed to the user who created the trigger (`scheduled_by`). Configure via the `delivery` list on any trigger: | Channel | Behavior | |---------|----------| | `slack_dm` | Sends output as a Slack DM via the workspace's connected Slack bot. Requires the workspace to have an active Slack integration and the user to have a linked Slack account. | | `email` | Sends output to the user's registered email address via Mailgun. | #### Specific targets Use colon syntax to send somewhere other than the trigger creator: | Target | Behavior | |---|---| | `slack:@handle` | DM a user by their Slack display name or username (e.g. `slack:@nick`). Fails if two humans share the same first name and neither has a unique display name. | | `slack:#channel` | Post to a channel by name (e.g. `slack:#policy`). The Eve bot must be invited to private channels. | | `slack:user@email.com` | DM a user by their registered email (e.g. `slack:nick.woolley@ev.energy`). Most reliable option — resolves via Slack's `users.lookupByEmail` endpoint and survives handle collisions. Bot needs the `users:read.email` scope. | | `email:user@example.com` | Send an email to any address. | Targets can be combined with commas: `slack:@nick,#policy`. Both top-level channels can be used together. If a channel fails (e.g., no Slack integration), the other channels still deliver. If no `delivery` is specified, agent output is logged but not pushed — the user would need to ask Eve for results. ## Agent Lifecycle 1. **Create** — Agent registered in workspace, dispatch tool auto-generated if `module_id` set 2. **Use** — Eve dispatches to agent via auto-generated tool (e.g., `ask_grid_planning_assistant`) 3. **Update** — Modify prompt, tools, triggers, visibility (workspace agents only) 4. **Delete** — Remove agent, dispatch tool, and team memberships ## Permissions | Operation | Who Can Do It | |-----------|--------------| | Create | Any workspace member | | Read/List | Any member (respecting visibility) | | Update | Creator only (for workspace agents) | | Delete | Creator only (for workspace agents) | | Modify builtin | Nobody (immutable) | | Promote/Demote | Platform admin only | --- ## Agent Platform > **Module:** `operations:agents` | **Role:** Any member (create), platform admin only (promote/demote) | **Licence:** Pro+ > **Tools:** `create_agent`, `update_agent`, `remove_agent`, `list_agents`, `view_agent`, `list_agent_tool_groups` The agent platform enables creation and deployment of specialized AI agents. Eve is the single orchestrator — users interact with Eve, who dispatches to specialized agents as needed. Agents never call each other directly. ## Key Concepts | Concept | Description | |---------|-------------| | **Agent** | A specialized AI with a prompt, tools, and optional triggers | | **Agent Team** | Organizational grouping of agents under a module with a shared mandate | | **Module** | Commercial feature gate that controls which tools and agents are available | | **Dispatch** | Eve calls an agent via a dispatch tool (e.g., `ask_policy_researcher`) | | **LANES** | Design vocabulary for agent roles (see below) | ## LANES Patterns Every agent follows one of six patterns that determine its role and default behavior: | Pattern | Role | Examples | |---------|------|---------| | **Librarian** | Store, index, retrieve knowledge | Policy Librarian (vault operations) | | **Analyst** | Read sources, create briefings/reports | Policy Analyst (digests, summaries) | | **Navigator** | Track work, flag risks, generate status | Policy Navigator (watchlist, deadlines) | | **Explorer** | Monitor external signals, surface what matters | Policy Explorer (regulatory scanning) | | **Steward** | Watch internal systems, detect deviations | Agent Steward (health monitoring) | | **Bespoke** | Unique function not fitting other patterns | Custom agents | LANES is not a class hierarchy — it provides prompt templates and tool defaults. ## Agent Origins | Origin | Created By | Modifiable | Visible To | |--------|-----------|------------|------------| | **Builtin** | Code (engineering) | No | All workspaces with module | | **Workspace** | Workspace members | Yes (by creator) | Current workspace only | | **Promoted** | Admin promotion | Admin only | All workspaces with module | ## Agent Modes | Mode | Behavior | |------|----------| | **Execute** | Takes action (creates scenarios, writes to vault, generates reports) | | **Track** | Monitors and reports (watchlist updates, status digests, alerts) | ## Scoping & Access Control The platform uses a **five-layer access model** (enforced by `check_agent_access()`): 1. **Module gate** — Is the required module enabled for this workspace? 2. **Workspace gate** — Does the agent belong to this workspace (or is it builtin/promoted)? 3. **Origin gate** — Is the agent's origin compatible with the operation? 4. **User visibility gate** — For restricted agents, is the user in `visible_to`? 5. **Conversation scope gate** — OAuth and signed-in sessions see private agents; shared connections see only shared agents ### Visibility - `workspace` (default): All workspace members can see and interact - `restricted`: Only users listed in `visible_to` can see and interact ## Triggers Agents can run autonomously on schedule or in response to events: | Type | Description | Example | |------|-------------|---------| | **Cron** | Scheduled execution | `"0 6 * * *"` (daily at 6 AM) | | **Event** | Triggered by system events | Module enabled, data refresh | | **Webhook** | External HTTP trigger | Partner API callback | | **Manual** | User-initiated via Eve | "Run the regulatory scan" | ### Delivery Channels Triggered agents can push their output directly to the user who created the trigger: | Channel | Description | |---------|-------------| | `slack_dm` | Direct message via the workspace's Slack bot | | `email` | Email to the user's registered address | Configure per-trigger: `"delivery": ["slack_dm", "email"]`. See [Creating Agents](creating-agents) for details. ## Related Documentation - [Creating Agents](creating-agents) — How to create custom agents - [Agent Teams](teams) — Grouping agents into deployable modules - [Workflow Examples](workflow-examples) — End-to-end team deployment walkthroughs - [Policy Intelligence Team](../policy/policy-team.md) — Built-in policy agent team - [Module Licensing](../workspace/modules) — What each module unlocks --- ## Agent Teams > **Module:** `operations:agents` | **Role:** Any member (create/manage), platform admin (deploy) | **Licence:** Pro+ > **Tools:** `create_agent_team`, `list_agent_teams`, `update_agent_team`, `view_agent_team` Agent teams group related agents under a module for organized deployment and shared context. ## Concepts | Concept | Description | |---------|-------------| | **Team** | Named group of agents with a shared mandate | | **Mandate** | Enduring objective injected into all member agent prompts | | **Shared Context** | Additional context available to all team members | | **Module** | Commercial gate — enable a module to deploy its agent team | ## Relationship ``` Module (e.g., "insight:policy") └── Agent Team (e.g., "Policy Intelligence") ├── Agent: Policy Researcher (Explorer) ├── Agent: Policy Librarian (Librarian) ├── Agent: Policy Navigator (Navigator) ├── Agent: Policy Analyst (Analyst) └── Agent: Policy Steward (Steward) ``` Enabling a module for a workspace makes all its team agents available via Eve dispatch. ## Managing Teams ### Create a Team ``` create_agent_team( name="Grid Planning", module_id="insight", mandate="Help analysts model grid capacity scenarios", agent_ids=["grid-analyst", "capacity-planner"] ) ``` ### Add/Remove Agents ``` update_agent_team( team_config_id="team_123", add_agents=["new-agent"], remove_agents=["old-agent"], ) ``` ### List Teams ``` list_agent_teams() # Returns all teams for current workspace ``` ## Default Teams Every workspace gets a default agent team automatically. Custom agents are added to this team unless explicitly assigned elsewhere. ## Deployment Platform admins can deploy module teams to workspaces: ``` update_workspace(workspace_id="ws_abc", enable_modules=["insight:policy"], confirm=True, confirm_token="...") ``` This enables the module for the target workspace, making all team agents available. It is confirm-then-apply: call it without `confirm` first to get a preview and a `confirm_token`. Disabling is the same tool with `disable_modules`. --- ## Workflow Examples > **Module:** `operations:agents` | **Role:** Any member | **Licence:** Pro+ Real-world examples of deploying agent teams via Eve. Each example follows the same loop: ``` 1. Identify the workflow problem 2. Design agent team (which LANES patterns, what tools, what schedule) 3. Create the team and agents via Eve chat 4. Agents run on schedule, deliver output to users 5. Iterate on prompts based on results ``` No code is written. Everything is created dynamically via `create_agent_team` and `create_agent`. --- ## Example 1: Content Pipeline **Problem:** The CEO needs a weekly blog but doesn't have time to scan industry news, pick a topic, and draft an outline from scratch every week. **Solution:** Three agents working as a pipeline — one scans, one drafts, one archives. ### Team Design | Agent | Pattern | Tools | Schedule | Delivery | |-------|---------|-------|----------|----------| | Scout | Explorer | `websearch` | Monday 7am | Slack DM + email | | Analyst | Analyst | `websearch` | Tuesday 9am | Slack DM + email | | Librarian | Librarian | auto-provisioned vault | Friday 10am | email | ### Deployment Steps **Step 1: Create the team** ``` Create an agent team called [team_id] with name "[Team Name]" and description "[what this team does]" ``` **Step 2: Create each agent** ``` Create an agent with these settings: agent_id: [id] name: [Name] pattern: [lanes_pattern] tool_groups: ["websearch"] triggers: [{"type": "cron", "schedule": "every monday at 07:00 UTC", "delivery": ["slack_dm", "email"]}] prompt: [your prompt here] ``` **Step 3: Add agents to the team** ``` Add [agent_1], [agent_2], and [agent_3] to the [team_id] agent team. ``` ### How It Works - **Monday:** Scout scans the web and delivers a ranked topic list via Slack DM and email - **Tuesday:** Analyst picks the best topic, drafts an outline, delivers via Slack DM and email - **Wednesday-Thursday:** Human drafts the blog using the outline (with Claude as copilot) - **Friday:** Librarian sends a weekly digest of everything stored in the vault The Librarian auto-provisions vault tools (query, store, delete) when created with `pattern: librarian`. Other agents or the user can store content in the vault via Eve. --- ## Example 2: Executive Meeting Support **Problem:** ExCo meetings lack structured agendas, decisions aren't tracked, and action items slip. **Solution:** Three agents — one preps agendas, one stores decisions, one chases overdue actions. ### Team Design | Agent | Pattern | Schedule | Delivery | Visibility | |-------|---------|----------|----------|------------| | Prep | Analyst | Thursday 8am | Slack DM + email | restricted (ExCo members) | | Librarian | Librarian | (no trigger) | — | restricted (ExCo members) | | Tracker | Steward | Wednesday 9am | Slack DM | restricted (ExCo members) | ### Key Design Decisions **Restricted visibility:** All agents use `visibility: restricted` with `visible_to` listing ExCo member user IDs. Only those users can see or interact with these agents. **No trigger on the Librarian:** It's written to after meetings by any ExCo member telling Eve "store these decisions in [librarian_id]". No automated schedule needed. **Tracker reads from Librarian:** The Tracker agent queries the Librarian's vault for open actions and flags anything overdue. The Steward pattern is designed for this — monitoring and accountability. ### How It Works - **Wednesday:** Tracker queries the Librarian for overdue actions, sends a status report via Slack DM - **Thursday:** Prep builds the agenda (decisions needed, blockers, updates), delivers via Slack DM + email - **Friday:** Meeting happens. Afterward, any ExCo member tells Eve to store decisions and actions in the Librarian - **Repeat** --- ## Example 3: Personal Knowledge Vault **Problem:** Important ideas, meeting notes, and strategic thinking get lost in email and chat. **Solution:** A single private Librarian agent that stores and retrieves anything on demand. ### Design | Agent | Pattern | Visibility | Trigger | |-------|---------|------------|---------| | Personal Librarian | Librarian | restricted (single user) | none | ### Deployment ``` Create an agent with these settings: agent_id: [your_id]_librarian name: [Your] Librarian pattern: librarian visibility: restricted prompt: [your storage/retrieval instructions] ``` No team needed — this is a standalone personal agent. When `visibility: restricted` is set without `visible_to`, it defaults to the creating user only. ### Usage - "Store this: [meeting notes, idea, decision]" — Eve dispatches to your Librarian - "What did I note about [topic]?" — Librarian searches the vault and returns matches - "What's in my vault tagged [type]?" — Librarian lists entries by tag --- ## Patterns to Note | Pattern | When to use | |---------|-------------| | **Pipeline** (Example 1) | Sequential workflow — each agent's output feeds the next | | **Hub-and-spoke** (Example 2) | Central Librarian, other agents read/write to it | | **Standalone** (Example 3) | Single agent, no team, personal use | ### Delivery Channel Reference | Channel | Requires | Behavior | |---------|----------|----------| | `slack_dm` | Workspace Slack integration + user's linked Slack account | DM via bot | | `email` | User's registered email address | Email via Mailgun | Both can be used together: `"delivery": ["slack_dm", "email"]`. If one fails, the other still delivers. ### Trigger Schedule Cheat Sheet All schedules are human-readable strings in UTC. Cron notation is no longer accepted — it was the source of a day-of-week ambiguity that shifted some agents' fire days by one. See [parse_schedule in ai/agents/base.py](https://github.com/ev-energy/ev.shapes/blob/master/ai/agents/base.py) for the format spec. | Schedule | Meaning | |---|---| | `every monday at 07:00 UTC` | Monday at 07:00 UTC | | `every tuesday at 09:00 UTC` | Tuesday at 09:00 UTC | | `every thursday at 08:00 UTC` | Thursday at 08:00 UTC | | `daily at 06:00 UTC` | Every day at 06:00 UTC | | `every friday at 10:00 UTC` | Friday at 10:00 UTC | | `daily at 04:00 UTC` | Every day at 04:00 UTC (background processing) | | `every weekday at 06:00 UTC` | Monday through Friday at 06:00 UTC | --- ## API authentication > **Module:** `insight` (always on) | **Role:** Any member | **Licence:** Free+ | **Auth:** Session cookie or MCP OAuth 2.1 ev.energy supports two credentials: 1. **The signed-in session** for the web app and the REST API. Sign in at `https://eve.ev.energy`; the browser sends the session cookie. A write also needs the `X-CSRF-Token` header and an `Origin` naming `eve.ev.energy`. 2. **MCP OAuth 2.1 + PKCE bearer tokens** for AI clients on the Workspace MCP at `https://eve.ev.energy/mcp`, acting for a signed-in user. Workspace API keys have been removed. OAuth with scoped keys for server-to-server access is planned. The driver-facing Connect MCP (`/connect/mcp`) uses a separate ev.energy OAuth bearer scoped to the `/connect` surface. See [Connect](/connect) and [connecting a client](/mcp/connecting). ## The signed-in session A request carrying the session cookie acts in your home workspace. A cookie request whose `Origin` names another site is refused with `403`. ## MCP OAuth 2.1 + PKCE For AI clients (Claude Code, Claude Desktop, Claude.ai, Cursor, etc.) use OAuth. There is no key to copy. Point the client at `https://eve.ev.energy/mcp` with no headers and the client runs the OAuth flow on first use: 1. The client discovers the authorization server via `GET /.well-known/oauth-authorization-server` and the protected resource via `GET /mcp/.well-known/oauth-protected-resource`. 2. The client calls `GET /oauth/authorize` with a PKCE `code_challenge`. **S256 is required** (the `plain` method is rejected). 3. A browser opens the provider-selection page (`/oauth/login`); the user signs in with ev.energy, Google, or Microsoft SSO — the same login as the website. 4. ev.energy returns a single-use authorization code (5-minute TTL) to the client's redirect URI. 5. The client exchanges it at `POST /oauth/token` (with the PKCE `code_verifier`) for an access + refresh token pair. You generally never construct the bearer header yourself — the client does. When present it looks like: ``` Authorization: Bearer ``` OAuth (browser SSO) connections run as **private** conversation scope, so a user's personal / restricted agents are visible too. ### Token lifetimes and refresh | Token | Lifetime | Notes | |---|---|---| | MCP access token | 60 minutes (configurable) | Stateless JWT, type `mcp_access`. | | MCP refresh token | 30 days (configurable) | JWT + DB record, type `mcp_refresh`. | Refresh happens automatically: the client calls `POST /oauth/token` with `grant_type=refresh_token`. **Token rotation** applies — each refresh issues a new pair and atomically revokes the old refresh token (a replayed refresh fails). MCP tokens are distinct from web sessions and cannot be used interchangeably. To revoke a token, the client calls `POST /oauth/revoke` (RFC 7009); it will re-OAuth on next use. ### OAuth endpoints | Method | Path | Purpose | |---|---|---| | GET | `/.well-known/oauth-authorization-server` | Authorization server metadata (RFC 8414) | | GET | `/mcp/.well-known/oauth-protected-resource` | Protected resource metadata | | POST | `/oauth/register` | Dynamic client registration (RFC 7591) | | GET | `/oauth/authorize` | Start the flow (redirects to `/oauth/login`) | | GET | `/oauth/login` | Provider selection page | | POST | `/oauth/token` | Exchange code or refresh token | | POST | `/oauth/revoke` | Revoke a token (RFC 7009) | ## Scopes OAuth connections run as **private** conversation scope, so a user's personal and restricted agents are visible. A connection with no valid credential returns `401` and an empty MCP tool list (no tool names are leaked). ## Rate limits Endpoints are rate-limited per IP, except the Gridbase API, which counts each workspace's requests together; exceeding a limit returns `429 Too Many Requests`. | Surface | Default limit | |---|---| | Chat (`POST /api/chat`) | 10 requests/minute | | Grid intelligence (`/api/maps/grid-intelligence/...`) | 60 requests/minute | | Gridbase API (`/api/gridbase/v1/...`) | 100 requests/minute per workspace (per IP for a request with no workspace); can be raised per workspace on request | | OAuth authorize | 30 requests/minute | | OAuth token exchange | 60 requests/minute | These are configurable defaults — your deployment's effective limits may differ. ## Error responses | Status | Meaning | |---|---| | `401 Unauthorized` | Missing, invalid, or revoked credential. | | `403 Forbidden` | Authenticated but lacking the required module / scope. | | `429 Too Many Requests` | Rate limit exceeded. | | `503 Service Unavailable` | Backend (e.g. auth DB) temporarily unreachable — distinct from a `401` so valid credentials aren't mistaken for invalid ones. | --- ## Map action frames > **Module:** `insight` | **Role:** Any member | **Licence:** Free+ | **Auth:** Session cookie Eve can ask a map the client shows to focus, select, change layers or highlight assets. She does this with four tools: `map_focus`, `map_select`, `map_layers` and `map_highlight`. Each call streams one `map_action` frame on `POST /api/v1/chat/stream`, beside the `chart_data` and `map_data` frames. A map action makes no map tile and stores nothing, so it has no `map_id`. The client decides what to do with a frame. It applies it to the map already on screen, shows an Undo cue, and never opens, closes or navigates a page because of one. Eve is told the action was requested, not done, so she says "I've asked the map to …" or nothing. ## Declaring map control Eve is offered the four tools only on a turn whose request body sets `map_control: true`, and a call on any other turn is refused without a frame. Leave it out, or send `false`, on any page without a map Eve may change. ```json { "messages": [{ "role": "user", "content": "Zoom to Elmsford" }], "map_control": true } ``` `map_control` is an interim field. The chat request's planned `context` field will carry it, and the top-level field will then be retired. ## Frame envelope Every frame is one SSE `data:` line: ```text data: {"type": "map_action", "data": {"action": "focus", "action_id": "…", …}} ``` | Field | Type | Meaning | |---|---|---| | `type` | `"map_action"` | The frame type. | | `data.action` | `"focus"` \| `"select"` \| `"layers"` \| `"highlight"` | Which change to make. | | `data.action_id` | string (UUID) | Unique per call. Use it to tie an Undo to the frame that caused it. | The other `data` fields depend on `action`. A tool call with bad arguments streams no frame. Eve gets the error instead. ## `focus` Frame a named place or a bounding box. Exactly one of `region` or `bbox` is present. | Field | Type | Meaning | |---|---|---| | `region` | string | A place as the user named it: a utility, state, county, ZIP or town. The client resolves it, for example with its own search. | | `bbox` | `[west, south, east, north]` | WGS84 degrees. `west < east` and `south < north`. | ## `select` Select a utility, or one substation in it, as if the user had clicked it. | Field | Type | Meaning | |---|---|---| | `utility_id` | string | Always present. The utility id `/api/gridbase/v1` returns, for example `coned`. | | `substation_id` | string | Optional. The id `GET /api/gridbase/v1/network/distribution/us/substations` returns: the utility's own id, else the HIFLD `substation_id`. | ## `layers` Turn layers on or off. Only the layers to change are listed. | Field | Type | Meaning | |---|---|---| | `layers` | object | Layer id → `true` (show) or `false` (hide). | The layer ids are fixed: `territories`, `transmission`, `substations`, `circuits`, `ev`, `solar`, `battery`, `thermostat`. Eve cannot send any other id. ## `highlight` Highlight feeders and substations. At least one of the two lists is non-empty, and each holds up to 50 ids. | Field | Type | Meaning | |---|---|---| | `feeder_ids` | string[] | Feeder ids, as `query_hosting_capacity` returns them. Always present, possibly empty. | | `substation_ids` | string[] | Substation ids, as for `select`. Always present, possibly empty. | | `utility_id` | string | Optional. The utility the ids belong to. | ## Fixtures Copy these as test fixtures. Each is the parsed JSON of one `data:` line. ```json {"type": "map_action", "data": {"action": "focus", "action_id": "6f1c1f9e-3b8a-4d0e-9a51-0c7f2f1d6a01", "region": "Elmsford, NY"}} ``` ```json {"type": "map_action", "data": {"action": "focus", "action_id": "6f1c1f9e-3b8a-4d0e-9a51-0c7f2f1d6a02", "bbox": [-73.83, 41.04, -73.80, 41.06]}} ``` ```json {"type": "map_action", "data": {"action": "select", "action_id": "6f1c1f9e-3b8a-4d0e-9a51-0c7f2f1d6a03", "utility_id": "coned"}} ``` ```json {"type": "map_action", "data": {"action": "select", "action_id": "6f1c1f9e-3b8a-4d0e-9a51-0c7f2f1d6a04", "utility_id": "coned", "substation_id": "HARRISON"}} ``` ```json {"type": "map_action", "data": {"action": "layers", "action_id": "6f1c1f9e-3b8a-4d0e-9a51-0c7f2f1d6a05", "layers": {"circuits": true, "ev": false}}} ``` ```json {"type": "map_action", "data": {"action": "highlight", "action_id": "6f1c1f9e-3b8a-4d0e-9a51-0c7f2f1d6a06", "feeder_ids": ["4A-12", "4A-13"], "substation_ids": [], "utility_id": "coned"}} ``` The `tool_result` frame that follows each call carries `result.success` and a `result.message` written for Eve, not for display. A client needs only the `map_action` frame. --- ## REST API overview > **Module:** `insight` (always on) | **Role:** Any member | **Licence:** Free+ | **Auth:** Session cookie or MCP OAuth 2.1 > **Base URL:** `https://eve.ev.energy` | **Auth:** session cookie (most endpoints) | **Module:** `insight` for grid data The platform exposes a set of HTTP endpoints alongside its two MCP surfaces. This page covers the REST endpoints; for the MCP tool surfaces see [Building on Eve](/developers/building-on-eve). Authentication is covered in [API authentication](/api/authentication). > The workspace MCP endpoint is `https://eve.ev.energy/mcp`. See the [MCP overview](/mcp/overview). ## Chat — `POST /api/chat` Send a conversation turn to Eve (or another ev.energy agent) and stream the response back as Server-Sent Events. - **Auth:** required — the signed-in session cookie, which sets the workspace context. Writes also need `X-CSRF-Token` and a same-host `Origin`. - **CSRF:** state-changing; fetch a token from `GET /auth/csrf` and send it back. CSRF is enforced on `POST /api/chat` and other cookie-authenticated writes. - **Rate limit:** chat requests are rate-limited per IP (default 10 requests/minute); over the limit returns `429`. See [authentication](/api/authentication). - **Response:** `text/event-stream` — the reply streams incrementally. Tool calls run inside the stream. **Request body (JSON):** | Field | Type | Description | |---|---|---| | `messages` | array | The conversation so far (role + content turns). | | `agent_id` | string | Which agent to talk to. Defaults to `eve`. | | `model` | string | Optional Claude model override. | | `max_tokens` | integer | Optional output cap. | | `format` | string | Output format — `raw` (default) or server-rendered HTML. | | `chat_id` | string | Optional conversation ID for history/audit. | The streaming chat endpoint, `POST /api/v1/chat/stream`, takes the same body plus `map_control`. When it is `true`, Eve may stream `map_action` frames that ask the client's map to change. See [Map action frames](/api/map-actions). A companion `GET /auth/csrf` endpoint (auth-required) returns `{ "csrf_token": "..." }` for use with the chat POST. ## Grid intelligence map data — `/api/maps/grid-intelligence/...` Backing data for Eve's integrated grid map. Authenticated, rate-limited (default 60 requests/minute), and gated by the `insight` module. Endpoints are read-only `GET`s, including: | Path | Returns | |---|---| | `GET /api/maps/grid-intelligence/layer-config` | Map layer configuration | | `GET /api/maps/grid-intelligence/network/lines/{utility}` | Distribution lines for a utility (bbox-queryable) | | `GET /api/maps/grid-intelligence/substations/{utility}` | Substations for a utility | | `GET /api/maps/grid-intelligence/hexbins/{utility_id}` | H3 hexbin aggregations | | `GET /api/maps/grid-intelligence/underground-networks/{utility}` | Underground network segments | | `GET /api/maps/grid-intelligence/utilities/territories` | Utility service-territory polygons | | `GET /api/maps/grid-intelligence/utilities/summary` | Per-utility coverage summary | | `GET /api/maps/grid-intelligence/national-assets` | National transmission assets | | `GET /api/maps/grid-intelligence/context` | Map context for a location | Vector tiles for circuits are served under the same prefix as `.pbf` tiles (`/api/maps/grid-intelligence/tiles/circuits/{utility}/{z}/{x}/{y}.pbf`) with tileset metadata at `.../tiles/circuits/{utility}/metadata.json`. ## Gridbase reference-data API — `/api/gridbase/v1/...` The structured energy-infrastructure data layer (utilities, distribution feeders, substations, EV registrations, boundaries). Authenticated and gated by the `insight` module. The API is versioned under `/api/gridbase/v1` and grouped: | Path prefix | Contents | |---|---| | `GET /api/gridbase/v1/meta/...` | Health, adapters, coverage (`/coverage`, `/coverage/{country}`), config, freshness | | `GET /api/gridbase/v1/utilities/...` | Utility directory and metadata | | `GET /api/gridbase/v1/network/...` | Distribution + transmission network — e.g. `GET /api/gridbase/v1/network/distribution/{country}/substations`, `.../lines`, `.../summary`, `.../query`, `.../underground-networks` | | `GET /api/gridbase/v1/ev/...` | EV registration data | | `GET /api/gridbase/v1/geo/...` | Geographic boundaries | | `GET /api/gridbase/v1/assets/...` | Infrastructure assets | For what each dataset contains and its sources, see the [Grid infrastructure data](/grid/overview) doc. ## Charts — `/api/charts/...` Charts produced by Eve's simulation and analysis tools are rendered and exported via the chart routes: | Path | Purpose | |---|---| | `GET /eve/charts/{chart_id}` | Rendered chart page (HTML) | | `GET /api/charts/data/{chart_id}` | Chart data (JSON: traces, layout, statistics) | | `GET /api/charts/scenario/{chart_id}` | Rendered scenario chart page (HTML) | | `GET /api/charts/scenario/{scenario_id}/runs` | A scenario's kept runs, oldest first (chart id, run number, created time) | | `GET /api/charts/export/{chart_id}.csv` | CSV export of the chart series | | `GET /api/charts/stats` | Chart storage statistics | Every chart endpoint requires you to be signed in to the web app (a workspace API key is not accepted). A chart is returned only if it was made in your workspace or in one of your own chats; any other chart is reported as not found. A shared chat shows its charts to anyone with the share link. Each scenario simulation is kept as its own chart, `{scenario_id}-run-{token}`, so earlier runs can be reopened and compared. The scenario id itself always loads the latest run. Runs expire like any other chart. ## Reports — `/api/reports/...` VPP / simulation reports (DOCX) generated from a chat session: | Path | Purpose | Auth | |---|---|---| | `POST /api/reports/generate/{chat_id}` | Generate a report from a conversation | authenticated | | `GET /api/reports/view/{report_id}` | View a generated report | authenticated; the report's chat must be yours | | `GET /api/reports/download/{report_id}` | Download the DOCX | authenticated; the report's chat must be yours | ## Authentication and errors - Most endpoints return `401 Unauthorized` without a valid session. - Grid endpoints additionally require the `insight` module on the workspace. - Rate-limited endpoints return `429 Too Many Requests`. Full detail — the session, OAuth bearer tokens, scopes, and rate limits — is in [API authentication](/api/authentication). --- ## How Eve Connect is put together # Eve Connect is one verb set reached through many surfaces > **Module:** `None` (driver-facing, no workspace module required) | **Role:** EV driver | **Licence:** Free+ | **Auth:** ev.energy account login (Clerk OAuth) > **Audience:** anyone who wants the map of how Eve Connect is put together: drivers, partners, and the ev.energy team. The driver-facing overview is [connect](../connect.md); the verb detail is [connect/verbs](./verbs.md). Eve Connect is **one set of verbs, over one backend, reached through several surfaces, reasoning about five kinds of information.** The axes are independent: any surface can use any verb about any kind of information, and a fact reaches every surface the same way. ## Rendering differs by surface, the facts do not ``` SURFACES chat · voice · your own AI client (MCP) · your own agent (A2A) · account page · the app │ one shared assistant + one verb set │ VERBS Read: my_account, discover Onboard: connect_device, join_program Change: update_account, update_device History: my_transactions Leave: remove_device, leave_program Share: refer_friend │ INFORMATION Programme · Device · Location · Account · Why │ FIELDS the details inside each record (see below) ``` Chat shows text and buttons, voice speaks and puts links on your screen, an AI client gets structured results. The content is identical, because it comes from the same verb reading the same source. The *verbs* are shared by construction. The *instructions* are not, and that decides where a rule belongs. Chat gets Eve's full prompt plus a lifecycle overlay. Voice gets the prompt plus a transport delta. An MCP client is *offered* the prompt as server instructions and may ignore it. **So anything that must be true on every surface has to live in the verb's result, not in prose.** That is why confirmation gates, the one-programme-at-a-time switch, and the "search near this postcode" lookup are all properties of the verb rather than instructions to a model. ## Every surface runs the same verbs against the same account | Surface | Where | What it is | |---|---|---| | Hosted chat | `eve.ev.energy/connect` | Type to Eve in the browser | | Voice | `/connect/voice` | Talk to Eve; links appear on your screen | | Your AI client (MCP) | `/connect/mcp` | Use Eve's verbs inside Claude, ChatGPT, Cursor | | Account page | `/connect/account` | Your referral QR, AI-client setup, and a summary of your cards (a charging card shows only its last four characters) with links to manage them | | Card pages | `/connect/rfid-cards`, `/connect/payment-cards` | Activate and manage the charging cards you tap; add the payment cards you pay with | | Notifications bell | beside your account chip on every signed-in page | What happened on your account, grouped Today / Yesterday / Earlier; a dot shows unread ones, opening it marks them read, and it updates as things happen | | The ev.energy app | app stores | The visual companion: live state, charts, and actions Eve hands off | You sign in once, with your ev.energy account. You reach the card pages from the account menu or from the Cards section of your account page. Eve manages the same cards through her four card verbs, and the pages and the verbs share one card layer, so they always agree on a card's status. Eve never takes a bank card number in conversation: adding a payment card always happens on the secure page. The organisation that issued a charging card can also pause or block it. Every other surface runs the same verbs against the same account, so what Eve knows does not depend on which one you use. How each surface takes a new driver from "stranger" to "signed in" is its own topic; see the internal channels design. ## Fifteen verbs cover everything Eve does They group by what you are trying to do. Full detail in [connect/verbs](./verbs.md). | Group | Verbs | For | |---|---|---| | **Read** | `my_account`, `discover` | See your account; browse programmes, tariffs, devices | | **Onboard** | `connect_device`, `join_program` | Add a car; join an earnings programme | | **Change** | `update_account`, `update_device` | Set your location, tariff, charge limit (payout method is set in the app) | | **History** | `my_transactions` | Your account over time: earned, spent, saved, energy and pending, with the items behind them | | **Leave** | `remove_device`, `leave_program` | Disconnect a device; leave a programme | | **Share** | `refer_friend` | Your referral link and QR | | **Cards** | `activate_charging_card`, `add_payment_card`, `update_card`, `remove_card` | Activate a charging card you hold; add a payment card on the secure page; make a card the default or pause it; remove a card or report one lost | | **Notifications** | `my_notifications` | What happened on your account (a charge, a declined card, a refund), in words written for you; showing them marks them read everywhere | `my_account` runs first on every turn. It is the read that grounds Eve's answer in your real account. ## Every driver question maps to one of five kinds of information | Kind | The question | Answered with | |---|---|---| | **Programme** | What can I join? What am I in? How do I earn? | `discover` (programmes available / mine), `join_program`, `leave_program` | | **Device** | Will my kit work? Is it connected? Change a setting? | `connect_device` (vehicles), `discover` (my devices), `update_device` | | **Location** | Available where I live? Which tariff? | `update_account`, `discover` (tariffs / suppliers) | | **Account** | Who am I? How am I paid? How am I doing? What happened? | `my_account`, `my_transactions`, `update_account`, `refer_friend`, `my_notifications` | | **Why** | Why ev.energy? How much could I save? | Eve's answer, cited to the public ev.energy site | ## You keep your tariff when you join a programme Supplier, tariff and programme get confused, so Eve keeps them apart. You can have all three at once. | | **Supplier** | **Tariff** | **Programme** | |---|---|---|---| | What it is | The company that sells you electricity | The named rate plan your supplier puts you on | An earnings or smart-charging scheme you **join** | | Example | Octopus Energy, OVO, E.ON Next | Octopus Go, Intelligent Octopus Go, OVO Charge Anytime | **Charge & Earn**, ev.energy UK | | How Eve handles it | Comes with your tariff | `update_account` (setting your tariff) | `join_program` / `leave_program` | | How many | One | One | **One at a time**: joining a new one leaves the current | **Charge & Earn is a programme, not a tariff.** You join it, and you keep whatever tariff you are on with your supplier. A tariff decides *what you pay per unit*; a programme decides *how you earn from being flexible*. They are independent axes, which is why the setup wizard asks for them as separate steps (Tariff, then Earnings). They touch in one place: some programmes exclude certain smart tariffs (Charge & Earn does not admit tariffs that already let your supplier control your charging), and that is stated in the programme's eligibility, not by making the tariff a programme. ## A programme record carries the same fields on every surface Each of these driver-facing fields reaches Eve identically everywhere: `name`, `description`, `benefits`, `eligibility_criteria`, `sponsor`, `country`, `sign-up link`, `FAQ link`, `support email`, `payment frequency / day`, and the joining links. Rich text (description, benefits, eligibility) is reduced to clean, readable text before Eve uses it, so it reads and speaks the same everywhere. ## Savings and earnings are two different things Eve keeps them apart: | | **Savings** | **Earnings** | |---|---|---| | What it is | Your bill going down from smart charging | Cash a programme pays you for being flexible | | Whose it is | Your **account**, and everyone who smart charges has them | Your **programme**, and only members of an earnings programme have them | | Where the number comes from | `my_transactions` → `saved`, from your charging history, plus the headline estimate | `my_transactions` → `earned`: per-session charging incentives plus rebates paid to the account. What a programme *advertises* it pays is on the programme record | Smart charging with ev.energy lowers your bill (savings). Joining an earnings **programme**, such as Charge & Earn, pays you on top (earnings). One is about your account and tariff; the other is about the programme you join. Your tariff is not a programme, and a programme is not a tariff, as the section above sets out. That split is easy to get wrong, so the two stay distinct measures on one statement. The headline figure (£450 / $575 / €500 per EV per year) is a **savings** baseline, so quoting it as earnings crosses the axes. `my_transactions` returns both, side by side: `saved` is your bill going down, `earned` is what a programme paid you (per-session charging incentives plus rebates paid to the account). The one money number still missing is **battery and solar earnings**: v2 has their device state but no payout ledger, so it is not on `my_transactions` rather than shown as a guessed total, tracked internally as a core data request. ## Every fact Eve states has a public home One rule holds the whole architecture together: > **Every fact Eve states about a programme, a device, a location or a number has a public home: the ev.energy API or a public web page. Eve never states a fact she cannot point you to.** If Eve cannot confirm something, she says so, rather than guessing. Numbers come from your account or a published figure with a source, never from memory. That is why what Eve tells you matches what you would find on the ev.energy site and in the app. --- ## Eve gets you enrolled, then keeps you earning > **Module:** `None` (driver-facing, no workspace module required) | **Role:** EV driver | **Licence:** Free+ | **Auth:** ev.energy account login (Clerk OAuth) > **Audience:** drivers and partners who want to know what Eve Connect does across a driver's whole relationship with ev.energy. The overview is [connect](../connect.md); the structural map is [connect/ia](./ia.md); the verb reference is [connect/verbs](./verbs.md). Eve has two jobs, in order: get a driver **enrolled**, then keep them **earning**. Those are the two lifecycles, and every driver question belongs to one of them. - **Enrollment** answers *"what can I get, and how do I get it?"* - **In-life** answers *"how am I doing, and how do I get more?"* **The boundary is whether setup is complete.** Eve reads your account on every turn, and `my_account` returns a five-item `setup` checklist plus the `next_step`. While any step is outstanding she is in enrollment mode. Once all five are ticked she stops running a wizard and becomes reactive. What changes between the phases is what Eve *says*. What never changes is where the facts come from: your ev.energy account, over the public v2 API, cited below for every claim on this page. --- ## Enrollment answers "what can I get, and how do I get it?" The journey from cold visitor to enrolled-and-earning: ``` Discover → Sign in → Onboard a device → Enrol → Earn → Earn more (ask Eve) (OAuth) (connect_device) (join) (live) (loop) ``` 1. **Discover.** Ask *"what could I earn near me?"* before connecting anything. Eve searches programmes by location: `GET /v2/programs?country_code=&postal_code=`. If no location is on file she asks for a postcode and searches near it without writing it to your profile. Unfiltered, that endpoint returns the global catalogue, so the location filter is what keeps a GB driver from being shown Connecticut programmes. 2. **Sign in.** One OAuth round-trip with your ev.energy account. Signing in and creating an account are the same step; there is no separate "register". 3. **Onboard a device.** `connect_device` onboards a **car**. Eve matches your free-text description against the vehicle catalogue (`GET /v2/vehicle_makes`, `GET /v2/vehicle_models`, `GET /v2/vehicle_trims`) and hands back an OEM authorisation link. Authorisation runs on ev.energy's `vehicle-authorization` endpoints, the same flow the ev.energy app uses, and the finished car then appears on `GET /v2/vehicles`. **Chargers, home batteries and solar are paired in the ev.energy app**, and Eve says so rather than offering a link she cannot produce. The charger catalogue (`GET /v2/evse_makes`, `GET /v2/evse_models`) is a read-only compatibility lookup that answers *"will my charger work?"*; it onboards nothing. 4. **Enrol.** `join_program` → `POST /v2/programs/{program_id}/join`. Programmes with no in-app tier (community and innovation trials) return the sponsor's own `external_url` instead, and Eve hands you there. 5. **Earn.** Savings and earnings start accruing; you are now in-life. 6. **Earn more.** Connect more devices, switch to a better-paying programme, refer friends. > Having a session is not the same as being a connected driver. Steps 3 and 4 are the real activation, not step 2. ### Five setup steps run in a fixed order One friendly ask per turn, each written to your account and then re-read so Eve never claims a step landed that did not. | # | Step | What it sets | Read / written as | |---|---|---|---| | 1 | **Account** | Your ev.energy login | Ticked from your signed-in session; profile at `GET /v2/users/{user_id}` | | 2 | **Device** | Car, charger, battery or solar | `GET /v2/vehicles`, `GET /v2/evses`, `GET /v2/solar_arrays` | | 3 | **Location** | The postcode Eve schedules and searches around | `PATCH /v2/users/{user_id}` with `default_location` (`address_1`, `postal_code`, `country_code`) | | 4 | **Tariff** | The rate plan your supplier has you on | Catalogue `GET /v2/tariffs?available_for_user_id=`; set via `default_location.tariff` on the same `PATCH` | | 5 | **Earnings** | The programme that pays you to flex | `GET /v2/programs`, then `POST /v2/programs/{program_id}/join` | **Tariff and Earnings are separate steps because a tariff is not a programme.** A **tariff** is the named rate plan your supplier puts you on, such as Octopus Go, Intelligent Octopus Go or OVO Charge Anytime, and it decides what you pay per unit. A **programme** is an earnings or demand-response scheme you **join**, such as Charge & Earn or ev.energy UK, and it decides how you are paid for being flexible. **Charge & Earn is a programme you join; Octopus Go is a tariff you are on. You have one of each, independently.** They live on different records and different endpoints: a tariff on your account's `default_location`, a programme on your membership record. See [You keep your tariff when you join a programme](./ia.md#you-keep-your-tariff-when-you-join-a-programme). **One programme at a time.** A driver holds at most one programme membership. `POST /v2/programs/{program_id}/join` leaves your current programme before joining the new one, so "earn more" between programmes is a *switch*, not a stack. Eve names the programme you would leave, and asks, before making the call. ### Eve shortlists programmes and says which one she would pick Every programme fact comes from `GET /v2/programs/{program_id}`: `name`, `description`, `benefits`, `eligibility_criteria`, `sponsor_name`, `country`, `external_url`, `sign_up_url`, `faqs_url`, `support_email`, `payment_frequency`, `payment_day_of_month`, `payment_weekday`, `logo`. Rich text is reduced to clean readable text first, so it reads and speaks the same on every surface. Asked what you could join, Eve reads `GET /v2/programs?country_code&postal_code` for where you are and puts **one to three** programmes in front of you with a recommendation and the reason for it, rather than a catalogue to sort. For each she names what the programme does, what it pays and what it asks of you in return, quoting the record's own `benefits` and `description`. She never invents a figure. ### Whether you can join is read from the programme, never assumed Conditions live in `eligibility_criteria` on the programme's own record, for example a smart-meter requirement or a smart tariff the programme excludes, and Eve quotes them as written rather than judging you against them. Whether your car qualifies is a separate check at `GET /v2/programs/{program_id}/vehicle_compatibility`. Where the record is silent, Eve says she cannot confirm it and offers the programme's `support_email` or `faqs_url`, which is the honest answer and a better one than a guess. ### Every later change is one ask, never the wizard again Setup runs once. Adding a second car, switching tariff, changing where you are paid or moving to another programme is a single ask and a single write after that, with no checklist to walk again. The join step is the one that needs care: a driver who already holds a membership and arrives back at it is **switching**, so Eve names the programme they would leave and confirms before calling `POST /v2/programs/{program_id}/join`. --- ## In-life answers "how am I doing, and how do I get more?" No wizard and no checklist. Eve refreshes your state with `my_account` at the start of every turn and answers in a line or two. Every in-life story, and what answers it: | You ask | Verb | Read from | |---|---|---| | *"Is it plugged in? What's the battery at? Is it charging? Will it be ready?"* | `my_account` | The `live` block on each car from `GET /v2/vehicles` plus its latest charging status: plug state, battery percentage, charging now, and the ready-by time when the car reports one | | *"What did I save last month? What did I spend? How much have I used?"* | `my_transactions` | `GET /v2/charging_sub_sessions` for home charging (energy and savings on each session) plus public charging on ev.energy cards. `saved`, `spent` and `energy.kwh` for the window, with the items behind them | | *"How much for public charging?"* | `my_transactions` | `spent` and the items whose `where` is a charging network: public charging paid through the ev.energy account. Home items say `"where": "Home"` | | *"How much have I earned overall?"* | `my_transactions` | `earned` = per-session charging incentives (`incentive_earned` on `GET /v2/charging_sub_sessions`) **plus** rebates paid to the account (`GET /v2/user_rebates`), each an item of kind `reward`. Kept apart from `saved`, never quoted as each other | | *"What did my battery or solar make me?"* | The app | Not on `my_transactions`: v2 has their device state (`GET /v2/home_batteries`, `GET /v2/solar_arrays`) but no settled payout ledger yet, so Eve hands you to the app rather than guessing a total. The named core ask below | | *"What programme am I in, and how do I earn on it?"* | `my_account` | `my_account().data.program` (singular, or null: you are in at most one): your membership from `GET /user-program-details/user/`, hydrated with `benefits`, `description` and `eligibility_criteria` from `GET /v2/programs/{program_id}`, so an enrolled driver gets the same detail a prospect does | | *"How do I actually get my rewards?"* | `my_account` | The same record, quoted as written. Charge & Earn rewards build up as a **balance you redeem in the ev.energy app when you choose**, so no payday is promised. A `payment_frequency`, `payment_day_of_month` or `payment_weekday` is quoted only when the record carries one | | *"What counts? Am I eligible? Why am I still pending?"* | `my_account` | `eligibility_criteria` on the programme record, plus the `verification_status` and field schema on your membership read, which is what tells Eve exactly which detail is outstanding and lets you supply it in the conversation | | *"How am I paid, and where do my rewards land?"* | `my_account`, then `update_account` | `my_account().data.payout_method` (`method`, `configured`) from `GET /v2/users/{user_id}/payout_method`; you set it (PayPal, Venmo or bill credit) in the ev.energy app, never through Eve or a connected AI, because it decides where your money goes | | *"What's my rate? Who's my supplier? Switch me."* | `my_account`, `discover`, `update_account` | `my_account().data.tariff` carries `name`, `currency`, `daily_prices`, `type` and `valid_from` / `valid_until` from `GET /v2/tariffs/{tariff_id}`; alternatives from `discover(scope="tariffs")`; the change is `update_account(tariff_id=…)`, confirmed first | | *"What have I got connected? Cap the charge. Take that one off."* | `my_account`, `update_device`, `remove_device` | `my_account().data.vehicles` and `my_account().data.chargers` (your own devices live on `my_account`, not `discover`); `maximum_charge_limit_percentage`, 50 to 100, via `PATCH /v2/vehicles/{vehicle_id}`; removal via `DELETE /v2/vehicles/{vehicle_id}` or `DELETE /v2/evses/{evse_id}`, confirmed first | | *"Will my car work? Will my charger work?"* | `discover` | `discover(scope="vehicle_makes")` returns the makes **supported for you** (`GET /v2/vehicle_makes?available_for_user_id=me`, fully paginated), so it names cars ev.energy actually supports rather than a partial list; then `vehicle_models` / `vehicle_trims` for detail. `discover(scope="charger_makes")` returns the charger catalogue (`GET /v2/evse_makes`) read-only. One honest caveat on chargers: the catalogue is **not exhaustive**, so a charger not listed can still be supported (myenergi/Zappi is, via its own integration, and many chargers work through the generic OCPP path); the real test is onboarding, and chargers, batteries and solar are paired in the ev.energy app | | *"How do I earn more?"* | `connect_device`, `join_program`, `update_account`, `refer_friend` | In rough order of size: connect another asset (a battery, solar or a second car moves the number most), move to a better-paying programme, set a payout method in the app so earnings have somewhere to land, refer a friend | | *"Move me to that other programme."* | `join_program` | `POST /v2/programs/{program_id}/join`. One programme at a time, so the join leaves your current one; Eve names it and asks first | | *"I want to leave my programme."* | `leave_program` | `PUT /user-program-details/user/leave/`, confirmation-gated. Earnings from that programme stop. Your smart-charging **savings** belong to your account, not the programme, so they carry on for as long as you keep smart charging | | *"What am I subscribed to?"* | `my_account` | `my_account().data.subscriptions` from `GET /v2/subscriptions/`: account offerings such as ev.energy Solar Lifetime. **Not** programme membership, which is the row three up | | *"Are there rebates I could get?"* | The app | US utility bill-credit rebates are discovered and claimed in the ev.energy app, gated to the schemes your utility runs. There is no `discover` scope for them: a rebate catalogue returns nothing for a GB driver. For *"what could I earn?"*, `discover(scope="programs")` shows the flexibility programmes near your saved location | | *"What's my referral link?"* | `refer_friend` | The referral code on your ev.energy account, returned as a code, a share link and a QR. It **sends nothing**, so Eve asks you to pass the link on yourself, and how many friends have joined is not readable here yet | | *"Boost it now. Pause the charge. Lock the charger."* | The app | There is no device-control write on this surface. Eve hands you to the ev.energy app rather than claiming to have acted | | *"How does this save me money? What is a time-of-use tariff? Are you safe with my data?"* | No tool call | Eve's own answer, cited to the public ev.energy site. Nothing here is about your account, so there is nothing to read | **Savings and earnings are two different things**, and Eve keeps them apart even though both now come back on one `my_transactions` statement. **Savings** are your bill going down from smart charging: an **account** fact, computed from your real charging history, never estimated at you. **Earnings** are cash a programme pays you for being flexible: per-session charging incentives plus rebates paid to the account. They sit side by side as `saved` and `earned`, and are never quoted as each other. Your **subscriptions** are a third axis again, and joining a programme never creates one. See [Savings and earnings](./ia.md#savings-and-earnings-are-two-different-things). --- ## Twelve stories cover what drivers actually ask for The canonical set, one line each, tagged by lifecycle. | # | Story | Lifecycle | |---|---|---| | **S1** | I have just bought an EV; sign me in and walk me through car, postcode, tariff and an earnings programme without five other tabs. | Enrollment | | **S2** | Tell me what I saved this month and what I earned, as two separate numbers. | In-life | | **S3** | I already have my EV connected; let me add a battery or a charger without restarting the wizard. | In-life | | **S4** | Answer "is my car plugged in?" or "what tariff am I on?" from my real account, in one line. | In-life | | **S5** | Tell me what I can join near my postcode, so I capture programmes I would otherwise miss. | Both | | **S6** | Let me point my own AI client at Connect, authorise once, and use these verbs from inside it. | Both | | **S7** | If Eve cannot do something yet, hand me cleanly to the ev.energy app rather than dead-ending. | In-life | | **S8** | Show me exactly what an AI client can see before I authorise it, and never ask for my password. | Enrollment | | **S9** | Get my country, currency and tariff names right the moment I sign in, not after I configure anything. | Both | | **S10** | Show me which AI clients I have connected, and let me revoke one cleanly. | In-life | | **S11** | Let me activate the charging card in my hand, make a card my default, pause it, report it lost, and add or remove a payment card. | In-life | | **S12** | Tell me what happened on my account, in words written for me, wherever I talk to Eve, and keep what I've seen seen everywhere. | In-life | --- ## Each of the 15 verbs does a different job in each lifecycle | Verb | Enrollment | In-life | |---|---|---| | **`my_account`** | Which of the five steps are done, and the next one to do (`setup`, `next_step`). S1. | Live state in one read: devices and their live charge state, location, tariff detail, payout method, and the enrolled programme with its own rules. S4, S9. | | **`discover`** | Browse the catalogues: car makes, models and trims, chargers for compatibility, programmes near you, tariffs, suppliers. S1, S5. | My devices, my programme, my subscriptions, rebates, the charger catalogue when new kit arrives; re-check what is newly available near me. S3, S5. | | **`connect_device`** | Step 2, the first car. Chargers, batteries and solar are paired in the ev.energy app. S1. | Every car after the first, one-shot, no wizard reset. S3, and the biggest earn-more lever. | | **`join_program`** | Step 5, the first earnings programme. S1, S5. | Switch programme; the join leaves the current one first, and Eve warns you by name. S5. | | **`update_account`** | Steps 3 and 4, home location then tariff. S1. | Moved house, switched supplier or tariff, changed where earnings are paid. S4, S7. | | **`update_device`** | *n/a*: not one of the five setup steps, and there is no device to configure until step 2 completes. | Set a vehicle's charge limit (`maximum_charge_limit_percentage`, 50 to 100). | | **`my_transactions`** | *n/a*: nothing to report before your first smart charge; Eve quotes real sessions, never an estimate dressed as history. | The driver's account over a window: earned, spent, saved, energy and pending, with the items behind them (home sessions and public charging on ev.energy cards). Battery and solar earnings are not on it yet. S2. | | **`remove_device`** | Undo a wrong match, such as the wrong trim or a car you no longer own, before it shapes your schedule. | Sold the car, replaced the charger. Re-pairing from scratch is needed afterwards, so Eve confirms first. | | **`leave_program`** | *n/a*: you hold no membership before the first join, and switching between programmes is handled by `join_program`. | Leave and stop earning; Eve says what stops and what carries on before doing it. | | **`refer_friend`** | Share your code as soon as you are signed in; it exists on your account from the start. | Referrals as a standing earn-more lever; both sides are credited when a friend signs up. | | **`my_notifications`** | *n/a*: nothing has happened on the account to tell you about yet. | What happened on your account (a public charge, a declined card, a refund), newest first; showing them marks them read on every surface. S12. | --- ## Every fact Eve states has a public home One rule holds this together, and it is the same in both lifecycles: > **Every fact Eve states about a programme, a device, a tariff or a number has a public home: the ev.energy API or a public web page. Eve never states a fact she cannot point you to.** | Fact | Source | |---|---| | Programmes available near me | `GET /v2/programs?country_code&postal_code` | | Programme detail, rules, eligibility, payment fields | `GET /v2/programs/{program_id}` | | Will my car qualify | `GET /v2/programs/{program_id}/vehicle_compatibility` | | Join a programme | `POST /v2/programs/{program_id}/join` | | The programme I am in, and my verification state | `GET /user-program-details/user/`, one active membership or none | | Leave my programme | `PUT /user-program-details/user/leave/` | | My subscriptions (**not** programme membership) | `GET /v2/subscriptions/` | | Tariffs I can be on | `GET /v2/tariffs?available_for_user_id` · detail at `GET /v2/tariffs/{tariff_id}` | | Suppliers | `GET /v2/suppliers` | | My account, address and tariff | `GET /v2/users/{user_id}` · `PATCH /v2/users/{user_id}` (`default_location`) | | Where my rewards land | `GET` / `PATCH /v2/users/{user_id}/payout_method` | | My notifications, and what I have seen | the eMSP's `GET /notifications` and `POST /notifications:seen`, as the driver | | My devices | `GET /v2/vehicles` · `GET /v2/evses` · `GET /v2/solar_arrays` | | Supported car makes for you | `GET /v2/vehicle_makes?available_for_user_id=me` (paginated); models/trims via `/v2/vehicle_models` · `/v2/vehicle_trims` | | Charger catalogue (compatibility, not exhaustive) | `GET /v2/evse_makes` · `GET /v2/evse_models` | | One device in detail, and its live state | `GET /v2/vehicles/{vehicle_id}` · `GET /v2/vehicles/{vehicle_id}/status_logs` · `GET /v2/evses/{evse_id}` | | Change a device setting | `PATCH /v2/vehicles/{vehicle_id}` | | Remove a device | `DELETE /v2/vehicles/{vehicle_id}` · `DELETE /v2/evses/{evse_id}` | | Charging history: savings, usage, cost, per-session incentives | `GET /v2/charging_sub_sessions` (carries `savings_cost`, `cost`, `energy`, `incentive_earned`, `vehicle`, `evse`, `mode`, `location`) · `GET /v2/charging_sub_sessions/{session_id}/energy_usage` | | Account-level rebate payouts (the second earnings stream) | `GET /v2/user_rebates` | | Battery / solar earnings | No settled payout ledger on v2 yet, so they are not on `my_transactions`. Device state only, at `GET /v2/home_batteries` · `GET /v2/solar_arrays`. The named core ask | | Rewards and rebates I could qualify for | `GET /v2/rebate_types` | | My referral code | The referral code on your ev.energy account profile. v2 exposes no referral endpoint, and Eve never mints a code of her own | | What a programme has paid me so far | `my_transactions` → `earned`: per-session charging incentives plus rebates paid to the account. Battery and solar earnings alone have no ledger yet | Two of these deliberately sit outside the `/v2` catalogue, because that is where the data honestly lives: programme **membership** (`/user-program-details/user/`) and the OEM **authorisation** hand-off used by `connect_device`. Everything else on this page is a public v2 endpoint. If Eve cannot confirm something from one of these, she says so rather than guessing, which is why what she tells you matches what you would find in the ev.energy app. --- ## Fifteen verbs run a driver's whole ev.energy account > **Module:** `None` (driver-facing, no workspace module required) | **Role:** EV driver | **Licence:** Free+ | **Auth:** ev.energy account login (Clerk OAuth) The Connect MCP server at `https://eve.ev.energy/connect/mcp` exposes exactly **15 enrollment verbs** for EV drivers. Every verb acts on the **OAuth'd driver's own ev.energy account**; there is no admin or multi-account surface. For the driver-facing overview see [Connect](/connect); to wire an AI client to this surface see [connecting a client](/mcp/connecting). All verbs take an optional `provider` parameter (string, defaults to `"ev.energy"`). Today only `ev.energy` is wired; other providers return a clear "not yet supported" error. When the driver isn't signed in, every verb returns a clean `requires_login` response rather than raising. **Returns.** Most verbs return a dict with `success` (boolean), `provider`, and either `data` (on success) or `error` (on failure). Verb-specific fields are noted below. **Confirmation gating.** Destructive verbs require a two-step confirm: the first call returns a `requires_confirmation` payload with a `user_message` to show the driver; the client retries with `confirmed=true` after an explicit yes. **Writes work, with two limits.** Account and device writes complete live against your account: `update_account` saves your home address and tariff, and `update_device` sets your car's charge limit. **What a connected AI can't change.** A confirmation that your own AI sets on your behalf isn't proof that you agreed, so some writes go to the ev.energy app instead. Those calls return `success: false`, `requires_app_action: true` and `error_type: "agent_write_refused"`, plus a line telling you where to make the change in the app. - **Payout method:** never set through Eve or any connected AI, because it decides where your earnings go. - **Over `/connect/mcp` and A2A:** changing your tariff or a charge limit, removing a vehicle or charger, joining, switching or leaving a programme, activating a charging card, and removing a card or reporting one lost. Eve in chat and on a call still does these, after asking you. > **Device control (boost / pause / lock / dispatch) is coming soon.** Acting on a device *right now*, whether that is boosting a charge, pausing it, locking a charger or dispatching a battery, is reserved for a future generalized `control` verb. It is not live yet: it's waiting on a device-control action that ev.energy is still building. Everything else below is live today. --- ## One verb covers your account and profile ### `update_account` saves your address and tariff Update account-wide settings: your home address and tariff. Your payout method and your phone number are set in the ev.energy app: neither is a parameter you can write here, and a call that sends one anyway changes nothing and gets the app hand-off. Over MCP or A2A a tariff change also hands off to the app. These are **live writes**, saving against your account immediately, no app round-trip. Charging-schedule fields (departure time, target SOC, day overrides) live on the device, not the account, and return a clear "not on this verb" message. | Parameter | Type | Required | Description | |---|---|---|---| | `home_location` | string | no | Free-text home address; parsed into street / city / postcode / country before saving. | | `tariff_id` | string | no | Tariff to set as the default. Changing it is confirmation-gated, and over MCP or A2A it hands off to the app. | | `phone` | string | no | Not written here. Any value hands off to the ev.energy app, the same shape as `payout_method`. | | `target_soc` | integer | no | Not on this verb. Charging targets are a per-device setting; use `update_device`. | | `departure_time` | string | no | Not on this verb; see `update_device`. | | `weekday_overrides` | object | no | Not on this verb; see `update_device`. | | `weekend_overrides` | object | no | Not on this verb; see `update_device`. | | `schedule` | object | no | Not on this verb; see `update_device`. | | `solar_mode` | string | no | Not on this verb. | | `confirmed` | boolean | no | Set `true` to confirm a tariff change after the confirmation prompt. | | `provider` | string | no | Defaults to `ev.energy`. | **Returns:** `success`, `fields_updated`, and `persisted_fields` (the fields the backend echoed back as saved). If a sent field isn't echoed, `success` demotes to `false` and `unpersisted_fields` lists it: the write is treated as not-persisted. A pure address update needs no confirmation; a tariff change does. --- ## Eve onboards, tunes and removes your devices ### `connect_device` onboards a vehicle from a free-text description It matches the description against the vehicle-make catalogue, walks make → model → trim to resolve the OEM provider, and returns an OEM auth URL the driver opens to authorise. The vehicle registers automatically once OEM auth completes. > **Vehicles only, today.** The wire path is the v1 `/vehicle-authorization/` flow over the legacy **car-make** catalogue, so a charger, home battery or solar inverter description has nothing to match against and returns `"Couldn't match … to a vehicle make."` Chargers, batteries and solar are paired in the ev.energy app; Eve should say so rather than offer a link she cannot produce. Removing an already-paired charger works (`remove_device` is polymorphic); it is only the *onboarding* side that is vehicle-only. | Parameter | Type | Required | Description | |---|---|---|---| | `description` | string | **yes** | Free-text vehicle description, e.g. `"a 2024 Tesla Model Y"`, `"Hyundai Ioniq 5"`. | | `provider` | string | no | Defaults to `ev.energy`. | **Returns:** `success` plus a `data` object with `matched_make`, `oem_provider`, `authorization_request_id`, `onboarding_url` (the OEM auth URL to send the driver), `instructions`, and a `ui_hint` for chat clients. On a near-miss it returns `error_type: "needs_clarification"` (asking for the model or trim) or `error_type: "transport_failure"` (asking the driver to retry). `onboarding_url` is the **only** source of an onboarding link. The catalogue rows returned by `discover(scope="vehicle_makes")` have their `onboarding_url` stripped deliberately: v2's prebuilt wizard URL 403s in a cross-origin popup from `askeve.energy` (the `V2_ONBOARDING_WAF_403` anti-pattern), so a URL taken from anywhere but this verb is a dead end. ### `update_device` sets your car's charge limit It updates settings on one device. Today the **only writable setting is the vehicle charge limit** (`maximum_charge_limit_percentage`, 50 to 100), reached via aliases like `target_soc` or `max_charge`. Charger (EVSE) settings aren't writable on the public API yet and are reported honestly. Confirmation-gated; over MCP or A2A it hands off to the app. | Parameter | Type | Required | Description | |---|---|---|---| | `device_id` | string | **yes** | The vehicle ID to update. | | `settings` | object | **yes** | e.g. `{"charge_limit": 80}` or `{"target_soc": 90}`. Unknown keys return a clear error. | | `confirmed` | boolean | no | Set `true` to apply after the confirmation prompt. | | `provider` | string | no | Defaults to `ev.energy`. | **Returns:** `success`, `device_id`, `device_type`, `fields_updated`. A 404 surfaces as a "couldn't find that car" message. ### `remove_device` takes a vehicle or charger off the account It is polymorphic, looking the device up first to decide vehicle vs. EVSE. Destructive, confirmation-gated (re-pairing from scratch is required to use it again); over MCP or A2A it hands off to the app. | Parameter | Type | Required | Description | |---|---|---|---| | `device_id` | string | **yes** | The device to remove. | | `confirmed` | boolean | no | Set `true` to confirm. | | `provider` | string | no | Defaults to `ev.energy`. | **Returns:** `success`, `device_id`, `device_type` (`vehicle` or `evse`). --- ## Four verbs manage your charging cards and payment cards A **charging card** is an ev.energy RFID card you tap at a public charger. A **payment card** is the bank card those charges are paid from. Cards are a separate thing from devices: `connect_device` stays cars only, and these four verbs cover the card lifecycle (activate or add, update, remove). They call the same card layer as the card pages at `/connect/rfid-cards` and `/connect/payment-cards`, so a verb and a page always agree on a card's status, what it allows, and the wording. **What an AI sees of a card.** Every card is named by a masked label ("Charging card ending AB12", "Visa ending 4242") and an opaque handle: `rfc_…` for a charging card, `pmc_…` for a payment card. A handle only works for the signed-in driver; another driver's handle and a made-up one both answer the same `card_not_found`. A charging card's chip uid never reaches the model, and the id printed on a card is never logged. **When the card verbs are listed.** Only while the card service is configured. When it isn't, the four verbs are absent from every surface's tool list and can't be called, so a client never sees a verb it can't use. ### `activate_charging_card` adds a charging card you are holding ev.energy charging cards are handed out unassigned, and the first account to activate one keeps it. The id printed on the card is the proof that you hold it. In Eve's own chat and voice, the first call reads the masked card back ("Charging card ending 9ZX2") with a reminder that every charge started with it is paid from your account; the card is activated on a second call with `confirmed=true` after you say yes. Over `/connect/mcp` and A2A nothing changes: the call returns `requires_app_action: true` and an absolute link to `/connect/rfid-cards/activate`, where you confirm the card is in your hand. | Parameter | Type | Required | Description | |---|---|---|---| | `printed_id` | string | **yes** | The id printed on the charging card (letters and numbers), exactly as read. Never a bank card number. | | `confirmed` | boolean | no | Set `true` to activate after the confirmation prompt. | | `provider` | string | no | Defaults to `ev.energy`. | **Returns:** `success`, a `message`, and `data.card` (the activated card, in the `my_account` shape below). A 13 to 19 digit, all-numeric value that passes the Luhn check is refused on every surface as a probable bank card number (`reason: "bank_card_number"`), before anything is sent or recorded; the hint points at `add_payment_card`. ### `add_payment_card` gives you the secure page to add a bank card It takes no card details, and none are ever taken in conversation: you type the card into the payment provider's own form on `/connect/payment-cards/add`. What comes back depends on the surface: - **Chat and web voice (a screen):** `data.url` plus a `ui_hint` of kind `account_link`, which the surface renders as an *Add a payment card* button. - **A phone call (no screen):** `data.spoken_route` only ("In the ev.energy app or at ev.energy on the web, open Account, then Payment cards, then Add a card."). No link is read out. - **`/connect/mcp` and A2A:** `data.url` as an absolute link. | Parameter | Type | Required | Description | |---|---|---|---| | `provider` | string | no | Defaults to `ev.energy`. | **Returns:** `success` and `data` (`url` and/or `spoken_route`, an `instruction`, and `ui_hint` on a first-party screen). A new card can take a moment to show in `my_account`. ### `update_card` makes a card the default, or freezes and unfreezes a charging card One change per call. `default=true` makes the card the one used first, for either kind. `frozen=true` pauses a charging card so it starts no charge, and `frozen=false` resumes it; payment cards can't be frozen. A card the driver's workspace or ev.energy froze is theirs to unfreeze: `frozen=false` on it is refused with reason `frozen_by_operator`. A driver's own change is reversible, so there is no confirmation step. It runs in Eve's own chat and voice, over `/connect/mcp` and over A2A. A request from any other caller is handed to the card page. | Parameter | Type | Required | Description | |---|---|---|---| | `card` | string | **yes** | The card's handle from `my_account().data.cards` (`rfc_…` or `pmc_…`). Never a number printed on a card. | | `default` | boolean | no | `true` to make this the default card. | | `frozen` | boolean | no | Charging cards only. `true` to freeze, `false` to unfreeze. | | `provider` | string | no | Defaults to `ev.energy`. | **Returns:** `success`, a `message`, and `data.card` with its new status. Sending neither or both of `default` and `frozen` returns `error_type: "invalid_arguments"`. A change the card's state doesn't allow is refused with `reason: "card_state"`; the card's `can` list says what it allows. ### `remove_card` removes a card, or reports a charging card lost `remove_card(card)` takes a charging or payment card off your account. `remove_card(card, lost=true)` reports a charging card lost or stolen and blocks it for good; it is for charging cards only. Both are destructive and confirmation-gated in Eve's own chat and voice: the first call reads the card and the consequence back, and the change happens on a retry with `confirmed=true`. Over `/connect/mcp` and A2A nothing changes: the call hands off to the card page. A payment card holding funds for a charge can't be removed until that charge settles. | Parameter | Type | Required | Description | |---|---|---|---| | `card` | string | **yes** | The card's handle from `my_account().data.cards`. | | `lost` | boolean | no | Charging cards only. `true` to report it lost and block it permanently. | | `confirmed` | boolean | no | Set `true` to confirm. | | `provider` | string | no | Defaults to `ev.energy`. | **Returns:** `success`, a `message`, and `data.card`. ### `my_account().data.cards` lists your cards The dashboard carries `cards = {available, charging_cards, payment_cards}`. Each card has: | Field | What it is | |---|---| | `card` | The opaque handle (`rfc_…` / `pmc_…`) the card verbs take. | | `kind` | `charging_card` or `payment_card`. | | `label` | The masked name, e.g. "Charging card ending AB12" or "Visa ending 4242". | | `status` | Charging cards only: the card page's status, `Active`, `Paused` or `Reported lost`. | | `default` | Whether this is the default card of its kind. | | `expires` | Payment cards only: the expiry date. | | `can` | What the card allows right now, from the pages' own action tables: any of `default`, `freeze`, `unfreeze`, `report_lost`, `remove`. | When cards can't be read, `available` is `false` with `reason` `unconfigured` (the card service isn't set up on this server; `note` says so in words to repeat) or `unreadable` (neither list could be read in time). If only one list could be read, the other is `null`, never `[]`: an empty list would claim you have no cards. On the account page alone (surface `page`), `my_account` also carries `public_charging = {available, sessions}`: the newest three public charging sessions, each in the `view="sessions"` row shape plus `paid_by` (`"you"`, or the name of the workspace that paid). Unread, it is `available: false` with `reason` `unconfigured` or `unreadable`, never an empty list. No agent surface reads it: Eve asks `my_transactions(view="sessions")` instead. --- ## One verb reads your notifications ### `my_notifications` tells you what happened on your account Your notifications, newest first: a public charge completed, a card declined, a refund, a hold released. Each one's `title` and `body` are written by the service that sent it, in your locale and time zone, ready to read out as they are. Notifications only inform: none of them changes anything on your account, and none asks you to act here. **Showing them marks them read.** Unless you pass `peek=true`, the notifications returned are marked read up to the newest one, everywhere you use Eve (chat, a call, a connected AI and the bell on the Connect pages share one read state), once every unread one has been returned (if there are more unread than one page holds, nothing is marked until you page back to them, so nothing is marked read unseen). If marking fails, they stay unread; the list is still returned. On a call, Eve also tells you when a new notification arrives while you are talking, once there is a pause. Telling you does not mark it read. | Parameter | Type | Required | Description | |---|---|---|---| | `unread_only` | boolean | no | Only notifications you have not seen yet. Default `false`. | | `limit` | integer | no | How many, 1 to 50. Default 20. | | `before` | string | no | The `next` a previous call returned, for older notifications. | | `peek` | boolean | no | Read without marking them read. Default `false`. | | `provider` | string | no | Defaults to `ev.energy`. | **Returns:** `success` and `data`, `{summary: {unread, marked}, items, next}`. Each item is `{id, type, occurred_at, title, body, reference, read, display}`: `display.when` is when it happened, already written in your time zone and locale (`Sun 4 Oct, 11:25`; `Sun, Oct 4, 11:25 AM` in en-US), the text to quote, while `occurred_at` is the exact instant (if `occurred_at` can't be read, `display` is empty and `occurred_at` is still there); `reference` is the charge's reference (`EVE-…`) when the notification is about a charge, the one to quote to support; `read` says whether it had already been seen when it was returned. `summary.unread` is how many are still unread after this call, and `summary.marked` whether the ones returned are now marked read (false with `peek`, when more are unread than this page shows, or when marking failed). `next` is `null` on the last page. `my_account` carries a summary too, `data.notifications = {available, unread, latest}` (the newest three), and reading it never marks anything. A `limit` outside 1 to 50 is clamped; a `limit` that is not a whole number, or a `before` that is not a `next` this verb returned, answers `error_type: "invalid_arguments"`. When notifications can't be read, the verb answers `success: false` with `error_type: "notifications_unavailable"` and a `reason`, and the summary reads `available: false` with the same `reason`. While notifications aren't set up on this server, the `reason` is `unconfigured` and the summary also carries a `note` saying so. --- ## Joining and leaving a programme are one verb each ### `join_program` joins a programme and leaves the one you were in It opts the driver into a smart-charging or demand-response programme, **or** finishes a join that still needs utility-account verification. **A driver is in one programme at a time**, so joining a new one automatically leaves the current one (enforced server-side): this is a *switch*, not a stack. Over MCP or A2A it hands off to the app. Eligibility and compatibility checks run server-side; errors surface verbatim. Programmes with no in-app default tier (community / innovation trials) return an `external_signup_url` instead, and Eve hands the driver to the sponsor's sign-up page. | Parameter | Type | Required | Description | |---|---|---|---| | `program_id` | string | **yes** | A programme ID from `discover(scope="programs")`. | | `verification_data` | object | no | Only to finish a `program_verification` deferred action: the collected fields keyed by each `required_inputs` `name`, e.g. `{"account_number": "…", "postal_code": "95405"}`. | | `verification_type` | string | no | `post_enrollment` or `user_verification`, taken from the deferred action's `resume.args_template`. Only sent alongside `verification_data`. | | `provider` | string | no | Defaults to `ev.energy`. | **Returns:** `success`, `program_id`, plus `previous_program_id` / `previous_program_name` naming whatever the join just left (both `null` when the driver was in nothing), so a switch is narratable and auditable after the fact. On an in-app join failure where the programme has one, `external_signup_url` carries the sponsor's sign-up page. **Verification is a sub-step of joining, not a separate verb.** Some US CCA schemes (Sonoma Clean Power, Clean Power Alliance, Marin Clean Energy) admit the driver on join but need proof of utility-account ownership before earnings switch on. That surfaces as a `program_verification` entry in `my_account().data.deferred_actions`; collecting the named fields and calling `join_program` again with `verification_data` finishes it in-conversation, with no website hand-off. A verification call that arrives *without* `verification_data` fails loudly rather than falling through to a re-join, which would silently leave and re-join the programme. ### `leave_program` leaves the one programme the driver is in A driver is in at most one programme, so this leaves whichever one they're in. Destructive, confirmation-gated (over MCP or A2A it hands off to the app): earnings from that programme stop and pending programme payments may be forfeited, and the confirmation message says so. Your smart-charging savings are a property of your account, not the programme, so they continue for as long as you keep smart charging. | Parameter | Type | Required | Description | |---|---|---|---| | `program_id` | string | **yes** | The enrolled programme to leave (a driver has at most one). | | `confirmed` | boolean | no | Set `true` to confirm. | | `provider` | string | no | Defaults to `ev.energy`. | **Returns:** `success`, `program_id`. > **Changing tariff or supplier** is handled by [`update_account`](#update_account-saves-your-address-and-tariff) via `update_account(tariff_id=…)`. There is no separate supplier verb. > **Device control (boost / lock / dispatch)** is not yet a verb on this surface. It is **coming soon** as a future generalized `control` verb, waiting on a device-control action ev.energy is still building. Rebates accrue automatically into `my_transactions`, so there is no `redeem_reward` verb (the evidence-required case surfaces as an in-app nudge). --- ## One verb hands the driver their referral link ### `refer_friend` returns the driver's own code, link and QR It returns the real code on their account, e.g. `NICK59`, plus its share link and QR URL. Non-destructive, so no confirmation gate. When a friend signs up with the code, ev.energy credits both of them. | Parameter | Type | Required | Description | |---|---|---|---| | `handle` | string | no | Email or ev.energy handle the driver wants to invite. See the note below: this does **not** send an email. | | `program_id` | string | no | Mint a **programme link**: whoever follows it is signed in, credited to this driver, and enrolled in that programme in one tap. Get the id from `discover(scope="programs")`. Omit for a plain link that lets the friend pick their own programme. | | `provider` | string | no | Defaults to `ev.energy`. | **Returns:** `success`, the referral code, its share link (`/connect/r/`) and `qr_url`, a `hint` in driver-words, and a `ui_hint` (`kind: referral_share`) that the chat surface renders as a scannable QR + link card. With `program_id`, the link carries the programme; the hint explains that a friend already on a different programme is asked first rather than switched. > **`handle` does not send anything.** Core has no "email an invite on the driver's behalf" endpoint, so passing `handle` echoes it back and rewrites the `hint` to *"Send \ your referral link below … (I can't send the invite directly from here.)"* Eve must relay that, never claim an invite was sent. This is the same phantom-endpoint discipline as `PROGRAM_JOIN_PHANTOM_ENDPOINT`: the verb refuses to fire at a path that has never existed. --- ## Three verbs read your account, the catalogues and your history ### `my_account` is the canonical first call in any conversation **Without `target`:** a composite dashboard snapshot covering vehicles, chargers, programmes, location, tariff, and the `next_step` the driver needs (e.g. `connect_a_car`, `set_home_location`, `join_a_program`). **With `target=device_id`:** full detail for one device. | Parameter | Type | Required | Description | |---|---|---|---| | `target` | string | no | A device ID for single-thing detail; omit for the dashboard. | | `provider` | string | no | Defaults to `ev.energy`. | **Returns:** `success`, `provider`, and a `data` object. The dashboard `data` carries exactly: | Field | What it is | |---|---| | `setup` | The checklist: `account`, `device`, `location`, `tariff`, `program`, `complete`. `complete` drives which prompt overlay Eve loads. | | `next_step` | One of `connect_a_car`, `connect_a_charger`, `set_home_location`, `set_tariff`, `join_a_program`, or `null`. | | `vehicles` | `id`, `make`, `model`, `trim`, `maximum_charge_limit_percentage`, and a `live` sub-object (plug state, SoC, charging) when the live read succeeded. | | `chargers` | `id`, `cpid`, `make`, `model`. **No live state**: plug-in / charging status is not exposed for chargers today. | | `program` | Your one enrolled programme (singular), or `null` — you are in at most one. Hydrated with the catalogue record (`benefits`, `description`, `eligibility_criteria`, `payment_*`) folded over your membership, so an enrolled driver gets the same detail a prospect does. Carries `joined_at`, the ISO 8601 moment **this driver joined this programme** — not their account signup date, and it resets on a tier change. Anything scoped to the programme measures from there. | | `subscriptions` | Account offerings, `{id, offering}`. Not programmes. | | `location`, `tariff` | Normalised summaries. Read these before falling back to raw `profile`. | | `deferred_actions` | Anything still needing a field from the driver (`program_verification`; `program_utility_signin` when a programme still needs the driver's utility sign-in, with a `signin_url` to it). | | `preferences`, `profile` | Raw pass-through, so a new upstream field surfaces with no code change. | | `cards` | Your charging cards and payment cards, `{available, charging_cards, payment_cards}`, each list in the same order on every surface: the default, then usable cards before paused, expired or lost ones, then newest first. See [`my_account().data.cards`](#my_accountdatacards-lists-your-cards). | | `account` | Your details as core holds them: `name`, `email`, `phone`, `home_address` (from `default_location`), `tariff` (its name), `programme` (its name) and `degraded`. Any of `name`/`email`/`home_address`/`tariff`/`programme` can read `null` because you have none on file, OR because the profile fetch failed — check `degraded`: `true` means "couldn't be read right now", never "empty". `phone` is read from the same call as `referral` (a separate read from the one `degraded` covers), so its own failure does not set `degraded`; a `null` phone means no phone on file or that read failing. `phone` reaches every surface, MCP and A2A included — approving a client's consent covers it, and the consent screen says so. `phone` is read-only here — `update_account(phone=…)` always hands off to the ev.energy app. | | `referral` | Your referral link for your own programme, the payload `refer_friend` returns: `code`, `short_link`, `qr_url`, `nfc_url`, `share_text`, `web_link`. `null` when core has no referral code for you. | | `notifications` | Your notifications summary, `{available, unread, latest}`: how many are unread and the newest three, as [`my_notifications`](#my_notifications-tells-you-what-happened-on-your-account) returns them. Reading it never marks them read. | | `connected_apps` | The apps you have let use Eve for you: `{id, name, connected_at}` each, nothing else. Over MCP or A2A this is always `null` — a third-party model is never shown the driver's OTHER connected clients, which is enumeration it has no legitimate use for. On a first-party surface, `null` means they could not be read just now, never "none". `name` is self-declared by the app at registration and is not verified; on chat and voice it is wrapped as explicit untrusted data (`untrusted, self-declared app name: "..."`) before Eve ever sees it, since the model reads this projection directly there. | | `ui_hint` | Reserved for an assisted utility handoff, which Eve does not currently offer. When present, the surface renders it, never model prose. | `my_account` does **not** return a transactions or savings snapshot, easy as that is to assume: use `my_transactions`. The driver's own things — devices, enrolled programme, subscriptions — are all on `my_account`, never on `discover`: `discover` is available catalogues only. ### `discover` reads any available catalogue by scope Paginated read of an **available** catalogue by `scope` — things the driver could add or join, never the driver's own things (those are on `my_account`). Same operation across scopes; the corpus changes. | Parameter | Type | Required | Description | |---|---|---|---| | `scope` | string | **yes** | What to list (see scopes below). | | `filters` | object | no | Scope-specific constraints, e.g. `{"make_id": "..."}` for `vehicle_models`. | | `provider` | string | no | Defaults to `ev.energy`. | **Scopes, the complete set of 8. Anything else returns an `Unknown scope` error:** - `vehicle_makes`, `vehicle_models` (filter `make_id`), `vehicle_trims` (filter `model_id`), `charger_makes`, `charger_models` (filter `make_id`), `programs`, `tariffs`, `suppliers`. The driver's OWN devices, enrolled programme and subscriptions are **not** `discover` scopes — they moved to `my_account` (`my_account().data.vehicles`, `my_account().data.chargers`, `my_account().data.program`, `my_account().data.subscriptions`). Asking `discover` for `my_devices`, `my_programs` or `subscriptions` is an `Unknown scope` error that points you at `my_account`. `charger_makes` and `charger_models` are a **read-only compatibility catalogue** ("will my charger work?"), not an onboarding path: chargers are still paired in the ev.energy app (see `connect_device`). The catalogue is deliberately not narrowed to your account, because it is not exhaustive (myenergi/Zappi integrates via its own API and the generic OCPP path is not listed), so a charger that is missing from it can still be supported. A **programme** (`discover(scope="programs")`, joined via `join_program`) is different from a **subscription** (an account offering read on `my_account`, with no programme link — `SUBSCRIPTIONS_NOT_PROGRAM_MEMBERSHIP`). `programs` and `tariffs` are narrowed to the driver's saved location, so a GB driver never sees Connecticut programmes. Pass an ad-hoc location in `filters`, either `{"postcode": "SW1A 1AA"}` or `{"zipcode": "06010", "country": "US"}`, to search *near there* without writing to the driver's profile. That is the "what could I earn near me?" lookup, and it works before any device is connected. **Returns:** `success`, `scope`, and `data` (a list). ### `my_transactions` is your account The driver's one account on ev.energy for a time window: what they earned, what they spent, what smart charging saved them, the energy they charged, what is still pending, and the items behind every figure. One call, one shape: ```json { "balance": null, "earned": {"value": 2600, "currency": "GBP"}, "spent": {"value": 1550, "currency": "GBP"}, "saved": {"value": 700, "currency": "GBP"}, "energy": {"kwh": 46.5}, "pending": {"earned": null, "spent": {"value": 4000, "currency": "GBP"}}, "items": [ {"date": "2026-09-20T18:00:00Z", "status": "settled", "kind": "session", "where": "Instavolt, Reading services", "kwh": 21.5, "amount": {"value": -940, "currency": "GBP"}, "funded_by": "card", "card": "Visa ending 4242", "charge": "EVE-01J9ZCF7Q1V8X3K2M4N6P8R0ST", "invoice": "EVEGB-0001043", "credit_notes": [], "invoice_url": "/connect/invoices/EVEGB-0001043"}, {"date": "2026-09-01T10:00:00Z", "status": "settled", "kind": "session", "where": "Home", "kwh": 9.0, "amount": null, "saved": {"value": 500, "currency": "GBP"}} ], "window": {"name": "last_30_days", "start": "...", "end": "...", "timezone": "Europe/London", "sessions": 12}, "notes": ["Your balance isn't available yet."], "locale": {"locale": "en-GB", "timezone": "Europe/London", "currency": "GBP", "country": "GB", "source": "profile"} } ``` **A public charging session you paid has its VAT invoice.** `invoice` is its number and `credit_notes` the numbers of any credit notes against it (a correction of the charge's price, VAT rate or energy: when the price falls, or when the invoice is credited whole and issued afresh; each note gives the date of the invoice it credits); `invoice_url` opens the invoice on your ev.energy account, to view and print or save as a PDF. A session your workspace paid has none: it says who paid (`paid_by`). **Money is one format everywhere:** `{value, currency}`, `value` an integer in minor units (pence, cents). The totals — `earned`, `spent`, `saved`, `pending.*` — are positive amounts. Only an item's `amount` carries a sign, like a bank statement: money in is `+`, money out is `-`. **`locale` is the driver's own** — their language (BCP 47), timezone (IANA) and home currency (ISO 4217), from the country on their ev.energy home address (the UK's when the country is unknown or unsupported). `my_account` returns the same object as `data.locale`. Write amounts and dates the way it says; an amount that names its own currency keeps it. - **`balance`** is `null` with the note "Your balance isn't available yet" until the earnings balance and payouts can be read. It is never a guessed figure. - **`earned`** is the rewards settled in the window: charging incentives plus rebates paid to the account. - **`spent`** is the public charging the driver paid for through their ev.energy account, settled in the window. Sessions their organisation paid for are items at `0` and never in `spent`. - **`saved`** is what smart charging saved at home against a standard tariff. - **`energy.kwh`** is home plus public charging. A public session whose kWh wasn't reported has `kwh: null`, is left out of the total (never counted as 0), and is counted in `energy.sessions_without_kwh`. - **`pending.earned`** is `null` when a reward is pending with no amount yet (a note says so) — different from having earned nothing. **`pending.spent`** is public charging still in progress. - **`items`** are the lines behind the figures, newest first: `date`, `status` (`settled` / `pending`), `kind` (`session` / `reward` / `payment` / `refund` / `written_off` / `adjustment` / `other`), `where` ("Home", the charging network and site, or "Public charging"), `kwh` on sessions, and `amount`. A home session's `amount` is `null` — it's paid to the driver's energy supplier, not this account — and it carries `saved` instead. A public item carries `funded_by` and the card by its masked name only ("Visa ending 4242"); a split payment is one item with its `parts` inside. A public charging item about a charge carries its `charge` (`EVE-…`), the reference to quote to support about it. Settled public lines fall in the window their session ended in. A `written_off` item is a debt ev.energy wrote off, never a payment the driver made, and its `note` says so; an `adjustment` reverses an earlier payment or write-off; an `other` item is an entry the account doesn't recognise yet, shown with a neutral `note` and never as a payment. **The account's only filter is the time window** (`view="sessions"` adds `state` and `after`; `view="invoices"` adds `after`). `window.sessions` counts every charging session in it; on a programme window `window.program` names the programme and `window.qualifying_sessions` says how many of those sessions qualify under its published rules, or `window.qualifying_note` says why it can't be counted. A part that can't be read — the charging history, rewards, or public charging — is `null` with a note in `notes`, never an error and never a `0`. | Parameter | Type | Required | Description | |---|---|---|---| | `window` | string | no | Friendly window, defaults to `last_30_days`. **Rolling spans:** `last_7_days`, `last_week`, `last_30_days`, `last_month` (30 days), `last_90_days`, `last_year`. **Named months:** `this_month`, `last_calendar_month` — use these for "in August" or "last month", which a rolling span answers over the wrong period. **Programme:** `current_program` (aliases `since_joining`, `this_program`) measures from the day the driver joined their current programme, and answers `window.available: false` when they are on none. `all_time` for whole-history questions (slower — reads every session). Bounds are resolved in the driver's own timezone (`locale.timezone`), so a named month is that month where they live, not the UTC month. | | `period` | string | no | A calendar month, `YYYY-MM`, instead of `window`. | | `start_date` | string | no | From this date, `YYYY-MM-DD`, instead of `window`. | | `end_date` | string | no | To this date inclusive, `YYYY-MM-DD`. | | `provider` | string | no | Defaults to `ev.energy`. | | `view` | string | no | `account` (the default), `sessions` or `invoices` (below). | | `state` | string | no | `view="sessions"` only: `authorised`, `started`, `completed`, `awaiting_bill`, `settled` or `released`. | | `after` | string | no | `view="sessions"` or `view="invoices"`: the `next` the previous page returned. | **Returns:** `success` and `data` (`{balance, earned, spent, saved, energy, pending, items, window, notes}`). **`view="sessions"` lists every public charging session instead**, on every account the driver has, newest opened first, one row per charge: its `id` (`EVE-…`), `state` (`authorised`, `started`, `completed`, `awaiting_bill`, `settled`, `released`) and `status` (`authorised`, `plugged_in`, `charging`, `no_recent_update`, `ended`, `billed`, `nothing_charged`), which `text.state` says in words ("Charging", "Plugged in. Latest information from the charger: 22:10", "Ended, waiting for the final price"), `held`, `opened_at` / `started_at` / `ended_at`, `where`, `payer` and `paid_from`, `price` (`net`, `vat`, `gross` and the VAT rate, `null` until priced), `collected`, `written_off` (what ev.energy wrote off on it) and `owed` (per currency), `place` (where it ran, as OCPI keys it: `country_code`, `party_id`, `location_id`, `evse_uid`, `connector_id`), `energy_kwh` (the kWh its bill states), `hold` (what is held for it, and its status; `null` when nothing was), `so_far` (while it is not priced, the kWh and cost the charge point has reported so far, never a price: said as "still running" while the session may run, and as "before its bill" once it has ended), `paid_by` (`you`, or the name of the workspace that paid, never its key), `invoice_url` when it has a VAT invoice, and `text` with each said in the driver's locale (`text.line` is the whole row in one line). The window bounds when each session opened; `state` narrows it and `after` pages it (`next`). A row never names the card's chip, the bill, the workspace's key or the partner. **Returns:** `data` (`{view, available, sessions, complete, next, as_of, window, locale}`), or `available: false` with a `note` when public charging can't be read. **`view="invoices"` lists the driver's VAT invoices and credit notes instead**, as one list, newest issued first: each has `kind` (`invoice` or `credit_note`), `number`, `issued_at`, `amount` and `display` (`amount`, `issued`, and for a credited invoice `total_after_credits`, in the driver's currency, locale and timezone). An invoice carries `invoice_url`, its credit notes and, once credited, `total_after_credits`; a credit note names the `invoice` it credits and that invoice's `invoice_url`. With no window it covers the last 30 days, like the account; `window="all_time"`, a `period` or dates widen it, and the window bounds each by its date of issue (after its start, up to and including its end). `count` (`invoices`, `credit_notes`, and `more` when `next` has further pages) counts each answer's own documents, and on the first answer `display.summary` ("2 invoices and 1 credit note", "at least 20 invoices") says how many; a window with none says so in `note`, offering to look further back, and one that could not be read in full says it can't say there are none. A document whose date can't be read is listed only under `all_time`; under any other window it is left out and `complete` is `false`. One `after` pages the whole list (`next`). `all_invoices_url` is `/connect/public-charging?payer=you`, Public charging on the account page showing the sessions you paid, and chat and web voice draw a "My invoices" button to it. **Returns:** `data` (`{view, available, documents, count, display, complete, next, all_invoices_url, window, locale}`), or `available: false` with a `note` when the invoices can't be read, never an empty list in its place. --- ## Every verb is live today except device control | Verb | Group | Write? | Status | |---|---|---|---| | `my_account` | Info | read | live | | `discover` | Info | read | live | | `my_transactions` | Info | read | live (earned, spent, saved, energy, pending and the items behind them, home and public charging on ev.energy cards; balance not available yet; `view="sessions"`, every public charging session and its status; `view="invoices"`, every VAT invoice and credit note) | | `connect_device` | Devices | write | live (OEM auth handoff, **vehicles only**) | | `update_device` | Devices | write | live (charge limit only) | | `remove_device` | Devices | write | live (vehicle or charger) | | `update_account` | Account | write | live (address + tariff + payout) | | `join_program` | Programmes | write | live (join + verification resume) | | `leave_program` | Programmes | write | live | | `refer_friend` | Referrals | read | live (returns a link, sends no email) | | `activate_charging_card` | Cards | write | live (in the call on first-party chat and voice; hands off to the activate page on MCP / A2A) | | `add_payment_card` | Cards | read | live (returns the secure add-card page; takes no card data) | | `update_card` | Cards | write | live (default for both kinds; freeze / unfreeze charging cards) | | `remove_card` | Cards | write | live (remove, or report a charging card lost; hands off on MCP / A2A) | | `my_notifications` | Notifications | write (marks read) | live (your notifications; showing them marks them read unless `peek`) | | _`control`_ | Charging control | write | _coming soon, waiting on an ev.energy device-control action_ | **The fifteen verbs reach every surface from one registry.** Hosted chat, voice and `/connect/mcp` all dispatch this same registry against the same backend, so a verb behaves identically everywhere. Two exceptions to the list itself: voice leaves out `update_device` and adds its own `offer_sign_in`, so a call sees 15 tools; and the four card verbs and `my_notifications` are listed only while the card service is configured. What differs is the *instructions* wrapped around it: chat loads Eve's full prompt plus a lifecycle overlay, voice loads the prompt plus a voice transport delta, and MCP publishes the prompt as server `instructions` (which a client may or may not honour). Any behaviour that must hold everywhere therefore belongs in the verb's own result, not in prose. --- ## Eve runs your devices so you save and earn > **Module:** `None` (driver-facing, no workspace module required) | **Role:** EV driver | **Licence:** Free+ | **Auth:** ev.energy account login (Clerk OAuth) > **Private trial:** Eve Connect is currently open to ev.energy staff only. Signing in with any other account is refused. > **Audience:** individual EV drivers (B2C). **Reach Eve** through hosted chat (`/connect`), voice (`/connect/voice`), your own AI client over MCP (`/connect/mcp`), or your account page (`/connect/account`). Same account, same verbs, same answers; only the rendering changes. The full map is in [connect/ia](./connect/ia.md). Eve helps you **save money on your bills** and **earn from the grid** by running your devices (EV, charger, home battery, solar) when energy is cheap and the grid needs help most. Sign in once with your ev.energy account; Eve does the rest. This page answers what Eve can do, how to reach her, what she sees about your account, and what's intentionally out of scope. If you're an ev.energy engineer or operator, the internal companion is at `docs/internal/features/connect/`. ## Eve sets up five things, then runs your devices for you | Step | What it sets up | Example | |---|---|---| | **Account** | Your ev.energy login | Click the sign-in button on the page. One round-trip to Clerk; you come back signed in. | | **Device** | Connect your car | *"Connect my Tesla"* → Eve hands back the OEM auth link, you confirm, you're paired. Chargers, home batteries and solar inverters are paired in the ev.energy app today; once they are on your account Eve reads them, and can disconnect them, but she cannot do the initial pairing. | | **Location** | The postcode Eve schedules around | *"My postcode is RH1 1JS"*, and Eve writes this to your account so the right programmes appear. | | **Tariff** | The energy plan you're on | *"I'm on Octopus Go"*, so Eve can pick cheap charging windows correctly. | | **Earnings programme** | The one programme that pays you to flex | *"What can I join?"*, and Eve lists eligible programmes for your postcode and enrols you in the one you pick. You're in **one earnings programme at a time**; joining a new one automatically leaves the last. | Once those five are set, Eve runs your devices automatically against the cheap windows and the programme rules. You can then ask her anything in plain English: - *"Is my car plugged in?"* gives live state from the car, no app needed. (Chargers report no live plug state today.) - *"How much have I saved this month?"* gives your bill cuts from cheap-window scheduling, in your account currency. - *"What tariff am I on?"* gives the name and price details, including off-peak / peak windows. - *"Boost charging now"* is a manual override. Today Eve routes you to the ev.energy app for execution; reads pick up the result on the next turn. See *"Eve hands you to the app for what she cannot do yet"*. - *"Add another car"* pairs a device without restarting the wizard. - *"What programmes pay near me?"* is local earnings discovery; Eve filters to ones you're eligible for. You can ask this **before** connecting anything: give Eve a postcode or ZIP and she searches near there without saving it to your account. - *"Share my referral link"* gives your permanent code, as a link and a QR. ## Use Eve in your browser, or inside your own AI client ### 1. Hosted chat runs in any browser at `/connect` Browser-based, mobile-friendly. Sign in, ask questions, get answers. The whole flow lives at `https://eve.ev.energy/connect`. No setup, no client install. Best if you don't already use Claude or another AI client. (The old `/connect/chat` link is gone: it now 404s. Everything lives at `/connect`.) - Mobile-first layout works on small screens, with safe-area-inset padding so iOS notches don't crop content. - The page is **stateless by design**: refresh and the chat resets. Nothing about a conversation is kept on your account; Eve only reads from the underlying ev.energy account state on each turn. - The chat reveals replies word-by-word for prose; structured content (lists, tables, headings) paints atomically so layout doesn't jump. - Tool calls show inline as a per-tool list with a green-disc tick on success or a red-disc X on failure, so you can see exactly what Eve did. - A mic in the composer lets you talk to Eve inline (the voice pill); the full voice page is at `/connect/voice`. ### 2. MCP puts Eve's verbs inside your own AI at `/connect/mcp` If you use **Claude Code**, **Claude Desktop**, **Claude.ai**, **ChatGPT** (with the MCP connector), **Cursor**, **Gemini**, or any other MCP-compatible AI client, point it at `https://eve.ev.energy/connect/mcp`: ```json { "mcpServers": { "ev-eve": { "url": "https://eve.ev.energy/connect/mcp" } } } ``` On first use the client opens a browser window for ev.energy sign-in, an ev.energy-branded page that never asks for your password. Sign in once; Eve's 15 enrollment verbs become available inside your AI client. Your conversation runs in *your* AI; Eve provides the tools, the data, and the underlying instructions (the SKILL prompt that teaches Eve how to talk about charging and earnings). The same OAuth carries forward: once you've authorised an MCP client, repeated sessions use refresh tokens automatically. Tokens are scoped to the `/connect` surface so a workspace cookie from `/eve` can't grant MCP access, and vice versa. ### Pick hosted chat if you have no AI client, MCP if you do Hosted chat is for drivers who don't already have an AI client they trust. MCP is for drivers who already live in Claude, ChatGPT or Cursor and want Eve's verbs available there. They share the same underlying ev.energy account state and the same enrollment verbs; the difference is where the conversation happens. ## Eve reads your ev.energy account and nothing else - Your **ev.energy account** is the only thing Eve reads: addresses on file, vehicles, chargers, charging history, the earnings programme you're in, savings figures. - Eve **never asks for your password**. Sign-in goes through ev.energy's OAuth (currently fronted by Clerk at `clerk.ev.energy`); Eve only ever sees the bearer token your browser passes through. - The token Eve sees is **scoped to your account only**. There is no admin, multi-account or "as another user" surface on `/connect`. - Conversations on `/connect` are **stateless by design**, with no permanent transcript on your account. What Eve knows on the next turn comes from the account, not from chat memory. - If you sign out, the session row in Eve's database is deleted and the browser cookie is cleared. Re-sign-in always starts a fresh session. ## Eve hands you to the app for what she cannot do yet **Real-time device control is coming soon.** Acting on a device *right now*, whether that is triggering a boost, pausing a charge, locking the charger or dispatching the battery, is reserved for a future generalised `control` verb, waiting on a device-control action ev.energy is still building. Ask for one of these today and Eve routes you to the ev.energy app rather than fake a confirmation: > *"I can't trigger that from chat yet. Open the ev.energy app to boost, lock, or dispatch."* No fake confirmations, no silent failures. **Everything else is live.** That covers reads (state, savings, your programme, tariff details, live charging) *and* writes: connect a car, remove any device, join or leave your earnings programme, and update your home address, tariff and payout method all complete against your account without an app round-trip. Three jobs still happen outside chat, and none of them is a failure: - **Pairing a charger, home battery or solar inverter** happens in the ev.energy app. Eve reads them once they're on your account and can disconnect them; she just can't do the first pairing. - **Programme earnings to date** aren't readable here yet. Eve will tell you what a programme pays, and what you've *saved* on your bills. A running earnings total is coming with the API that exposes it. - **Referral invites** are a link you send, not an email Eve sends. Ask for your link or QR and share it however you like. ## Eve talks in plain words and real numbers Friendly, direct, low-jargon. She won't say *"VPP"* or *"DR event"*. She says *"the grid asks for help"*. She talks about **savings** (cheaper bills from charging in cheap windows) and **earnings** (programme payments for flexing) as two different things, because they are: savings come from your tariff structure, earnings come from third-party programme payments. She names **real numbers from your account**. She never invents figures. If something fails (an API hiccup, a permission gap), she says so plainly and points you to the app. A handful of stylistic conventions she follows: one themed emoji per line at most (🚗🔌🏠⚡💰), single H3 headings, bold headline numbers, and a single `>` callout for the value-exchange punchline. Lists use proper bullets. Currency rendering matches your account locale. ## Eve picks your currency and wording from your address Eve picks **UK / US / EU** silently from your account's address. Currency (£ / $ / €), word choice (*tariff* / *rate plan*), example tariffs (Octopus Go vs PG&E EV-2A), and headline savings figures (£450 / $575 / €500 per EV per year) all switch automatically. You don't have to tell her where you live; the address on your ev.energy account does that. If your account is in a country without active programmes, Eve will tell you and surface a waitlist instead of pretending there's something to enrol in. ## Your referral code is permanent, and every signup traces back to you Every driver has a **permanent personal referral code**, a short URL like `https://eve.ev.energy/connect/r/` that you can share with a friend. Every signup through your link is tracked back to you. What that's *worth* depends on where you are: the default is tracked-not-paid, and reward groups (postcode, ambassador, employer schemes) layer credits on top where they're running. So Eve will share your link happily and won't promise you a figure per friend. Ask her about your account's activity for anything concrete. Ask Eve *"share my referral link"* or *"what's my QR code?"* and she'll surface a QR image you can show on screen or save to your phone. Eve never shares your link without you asking, and she can't email an invite on your behalf. The link is yours to send. You can also ask for a link to a **specific programme**: whoever follows it is signed in, credited to you, and put on that programme in the same tap (unless they're already on a different one, in which case they're asked first rather than switched). On Chrome for Android, the share page also lets you **write your referral URL to a blank NFC tag**. Hold the tag against the back of your phone and Eve writes the link to it. Friends can then tap that tag with their own phone (iPhone or Android) to open your referral page directly. Same code, same crediting, no app install needed. QR and link sharing still work everywhere else. ## Talk to Eve at `/connect/voice`. Alexa is still on the roadmap **Talk to Eve at `/connect/voice`.** It is the same Eve, the same account and the same verbs as the chat. She just speaks, and puts links on your screen instead of reading them aloud. Anything that needs a tap (signing in, connecting your car, connecting a utility account) appears on screen as a link or a button at the moment Eve offers it. The Alexa skill, voice-driven enrollment via "Alexa, ask Eve to connect my car", is still on the roadmap. Dictating into the hosted chat, or using your MCP client's own voice mode, works today too. ## Short answers to the questions drivers ask most **Does Eve store my chats?** No. `/connect` is stateless: refresh resets the conversation, and the chat content is never written to a permanent transcript on your account. Your MCP client may store its own transcript; that's between you and your AI tool. **Can I use Eve without an ev.energy account?** Not yet. Eve's data and verbs all flow through your ev.energy account; without one, there's nothing for her to read or write. You can sign up for ev.energy first, then come to `/connect`. **What if my AI client doesn't support MCP?** Use the hosted chat at `/connect`. It runs in any modern browser. **How do I disconnect an AI client?** Sign out of the MCP client (it'll forget the OAuth token), or use Eve to revoke the refresh token directly. The token-revocation flow goes through `/connect/oauth/revoke` per RFC 7009; your AI client will then need to re-OAuth on next use. **Is `/connect` the same as `/eve`?** No. `/eve` is the workspace surface for utilities and fleet operators, with a different principal (workspace member, not driver), different module-gated tools and a different licence model. `/connect` is the B2C surface for individual drivers. They share the underlying tooling architecture but the sessions, OAuth, and stored state are completely separate (driver state lives in tables prefixed `connect_*`; workspace state lives in the shared tables). **What languages does Eve speak?** English today (UK / US dialect by account locale). Additional languages follow the ev.energy app's roadmap. **Is there a mobile app?** Not yet for `/connect` specifically; the hosted chat works fine on mobile browsers. A native iOS/Android wrapper is on the roadmap. ## Start using Eve, or read about ev.energy itself - **`/connect` itself**, the live driver surface: - **MCP setup snippets**, copy-paste config for Claude Code, Claude Desktop, Claude.ai, ChatGPT, Cursor and the rest: on your account page at `/connect/account` - **ev.energy proper**, the company behind your account, devices, tariffs, and programmes: --- ## Building on Eve > **Module:** `None` (Connect) / `insight` (platform) | **Role:** EV driver (Connect) or Any member (platform) | **Licence:** Free+ | **Auth:** OAuth 2.1 or session — varies by surface (see below) ev.energy exposes three integration surfaces. Each has its own audience, authentication model, and tool/endpoint set. This page helps you pick the right one and points to the detailed reference for each. ## The three surfaces ### 1. Connect MCP — driver apps (B2C) **Endpoint:** `https://eve.ev.energy/connect/mcp` A Model Context Protocol server that gives an AI client the **15 driver enrollment verbs** — read your account (`my_account`), connect a vehicle or charger, join an earnings programme, check savings (`my_transactions`), manage charging and payment cards, refer friends, and more. Every call acts on the **OAuth'd driver's own ev.energy account**; there is no admin or multi-account surface here. Authentication is the driver's own **ev.energy OAuth bearer** (the sign-in page is fronted by Clerk; the MCP bearer is issued by ev.energy itself, scoped to the `/connect` surface). No ev.shapes workspace and no licence. Use this when you're building a driver-facing experience — a chat assistant, a voice agent, or any app where an individual driver brings their own AI client and you want Eve's enrollment verbs available inside it. → [Connect overview](/connect) · [the 15 verbs](/connect/verbs) · [connecting a client](/mcp/connecting) ### 2. Workspace (Platform) MCP — analytics and operations (B2B) **Endpoint:** `https://eve.ev.energy/mcp` A Model Context Protocol server that exposes Eve's **full workspace tool suite** — simulation, grid intelligence, hosting capacity, charts, reports, policy agents, and agent/skill management. Tools are **dynamically filtered by the workspace's enabled modules** (e.g. `insight`, `insight:policy`, `operations:agents`). Authentication is **OAuth 2.1 + PKCE** (browser SSO). Workspace API keys have been removed; OAuth with scoped keys for headless access is planned. The principal is a workspace member, not a driver. Use this when you're building analytics, modelling, or operations tooling for a utility or fleet operator — anything that reasons over grid data, runs simulations, or drives the workspace agent platform. → [MCP overview](/mcp/overview) · [connecting a client](/mcp/connecting) ### 3. REST API — direct HTTP **Base URL:** `https://eve.ev.energy` The platform's HTTP endpoints: the Eve chat endpoint (`POST /api/chat`), grid intelligence map data, the Gridbase reference-data API (`/api/gridbase/v1/...`), chart rendering, and report generation. Most endpoints require authentication (the signed-in session cookie) and the `insight` module for grid data. Use this when you need direct programmatic HTTP access — server-to-server calls, scripted data pulls, or embedding report output — rather than an MCP tool loop. Charts are viewed signed in to the web app. → [REST API overview](/api/overview) · [authentication](/api/authentication) ## Which one should I use? | If you want to… | Use | Auth | Reference | |---|---|---|---| | Build a driver-facing app or AI assistant that manages a driver's own car, charger, programmes, and savings | **Connect MCP** | Driver ev.energy OAuth bearer | [/connect/verbs](/connect/verbs) | | Let an individual driver use Eve inside their own Claude / ChatGPT / Cursor | **Connect MCP** | Driver ev.energy OAuth bearer | [/mcp/connecting](/mcp/connecting) | | Run grid simulations, hosting-capacity analysis, or policy research from an AI client | **Workspace MCP** | OAuth 2.1 | [/mcp/overview](/mcp/overview) | | Give analysts an MCP toolset filtered by the modules your workspace has enabled | **Workspace MCP** | OAuth 2.1 | [/mcp/overview](/mcp/overview) | | Pull Gridbase reference data (utilities, feeders, substations, EV registrations) over HTTP | **REST API** | Workspace auth + `insight` module | [/api/overview](/api/overview) | | Send a chat turn to Eve programmatically and stream the response | **REST API** (`POST /api/chat`) | Session | [/api/overview](/api/overview) | | Render or export a chart | **REST API** | Signed-in session, your workspace's charts | [/api/overview](/api/overview) | | Generate a VPP report | **REST API** | Unique-ID gated | [/api/overview](/api/overview) | ## A note on the two MCP surfaces The Connect MCP (`/connect/mcp`) and the Workspace MCP (`/mcp`) are **strictly separated**. Eve's workspace tools never appear on the driver surface, and the 15 enrollment verbs never appear on the workspace surface. The boundary is enforced by the token issuer (`iss`) claim — a `/connect` token cannot call `/mcp` tools and vice versa — so a driver's bearer can never reach workspace data, and a workspace credential can never act on a driver's personal account. → Continue to [the 15 Connect verbs](/connect/verbs), the [REST API overview](/api/overview), or the [client connection guide](/mcp/connecting). --- ## Using Eve > **Module:** `insight` (always on) | **Role:** Any member | **Licence:** Free+ | **Auth:** Web login, OAuth (MCP), or embed token (widget) Eve is the platform's AI assistant and orchestrator. She has access to simulation tools, grid data, regulatory intelligence, and agent dispatch — filtered by your workspace's enabled modules. ## What Eve Can Do | Capability | Module Required | Example | |------------|----------------|---------| | Build energy scenarios | `insight` (always on) | "Model 500 EVs with smart charging on a UK grid" | | Analyze load profiles | `insight` | "Show me the peak demand for 1000 homes in Arizona" | | Query hosting capacity | `insight` | "What's the available capacity on PG&E feeders near San Jose?" | | Calculate deferral value | `insight` | "How much could managed charging save in infrastructure costs?" | | Generate charts | `insight` | "Graph the base vs flexed profile" | | Search platform docs | `insight` | "How does the thermostat DR model work?" | | Research regulatory policy | `insight:policy` | "What's the latest on FERC 2222 in New York?" | | Search knowledge vault | `insight:policy` | "Find all findings related to VPP in California" | | Create custom agents | `operations:agents` | "Create an agent that monitors grid capacity weekly" | | Manage agent teams | `operations:agents` | "List all agents in my workspace" | ## How Eve Works 1. **You ask a question or describe a task** in natural language 2. **Eve selects relevant tools** from those available to your workspace 3. **Eve executes tools** (simulations, queries, searches) and streams results 4. **Charts, maps, and data** are rendered inline in the conversation 5. **For complex tasks**, Eve dispatches to specialized agents (e.g., Policy Researcher) ## Mood System Eve has a real-time grid mood based on carbon intensity and energy generation mix: - **Green moods** (good to charge): Ultra Green, Solar Surge, Wind Power - **Opportunity moods** (savings): Low Carbon, Off-Peak - **Caution moods** (high carbon/constrained): Grid Stress, Fossil Heavy - **Insight moods** (informational): Transition, Balanced Grid data refreshes every 5 minutes from UK Carbon Intensity, CAISO, NYISO, ISO-NE, and ENTSO-E. ## Chat Sharing Share conversations via public read-only links: - Click the share button on any conversation - Recipients can view the full conversation without logging in - Shared links have 96-bit entropy tokens (no expiration, no auth required) ## Tips - **Be specific about parameters** — "500 EVs at L2 smart charging with 80% compliance" gives better results than "simulate some EVs" - **Ask about assumptions** — Eve will explain what defaults she's using and why - **Iterate** — "Now try it with batteries" builds on the existing scenario - **Ask for comparisons** — "Compare unmanaged vs optimized charging" generates side-by-side analysis - **Request methodology** — "How does the Monte Carlo engine work?" fetches platform documentation ## Access - **Web chat**: Log in at eve.ev.energy - **MCP clients**: Connect Claude Code or Claude Desktop via `https://eve.ev.energy/mcp` (see [MCP Server](mcp/overview.md)) --- ## Hosting Capacity Data & Methodology > **Module:** `insight` (always on) | **Role:** Any member | **Licence:** Free+ > **Tools:** `query_hosting_capacity`, `analyze_hosting_capacity_constraints`, `calculate_hosting_capacity_deferral_benefit`, `set_scenario_capacity_limit` Grid hosting capacity data powers the platform's infrastructure analysis, showing where new DER (EVs, batteries, solar) can interconnect and where the grid is constrained. --- ### Data Sources Hosting capacity data is sourced from public utility Integration Capacity Analysis (ICA) maps: | Utility | Source | Coverage | Update Frequency | Status | |---------|--------|----------|-----------------|--------| | PG&E | Public API | Northern/Central California | Quarterly | Active | | SDG&E | Public API | San Diego County, CA | Quarterly | Active | | ConEd | Public API (hosting capacity maps) | Westchester County, NY | Quarterly | Active | | National Grid MA | Public API | Massachusetts | Quarterly | Active | | SCE | Requires authentication | Southern California | — | Not currently available | ### What the Data Includes - Feeder-level capacity ratings (MW) - Available headroom for new DER interconnection - Constraint types (thermal, voltage, protection) - Multi-year headroom projections (where available) --- ### Infrastructure Deferral Financial Assumptions Default financial parameters used in infrastructure deferral benefit calculations. #### DER Flexibility Cost - **Default: $350,000 per MW** ($0.35M/MW) - Represents annualized cost of deploying and operating DER flexibility programs - Includes: aggregation platform costs, customer incentives, program management - Based on industry estimates for managed EV charging and battery dispatch programs #### Traditional Upgrade Cost - **Default: $2,000,000 per MW** ($2M/MW) - Represents capital cost of traditional distribution infrastructure upgrades - Includes: conductor upgrades, transformer replacements, substation expansion - Range in practice: $1.5M-$4M/MW depending on location and scope #### Discount Rate - **Default: 5%** (nominal) - Used for NPV calculation of deferred capital expenditure - Represents weighted average cost of capital for regulated utilities #### Methodology ``` NPV of deferral = (deferred_capital) / (1 + discount_rate)^years_deferred Net benefit = NPV of deferral - DER flexibility cost ROI multiple = NPV of deferral / DER flexibility cost ``` --- ### Limitations - Data reflects utility planning models, not real-time grid conditions - Hosting capacity maps are updated quarterly — may lag recent interconnections - Projection accuracy degrades beyond 3-5 years - Does not capture all local constraints (e.g., secondary transformer limits) - Coverage limited to utilities with public ICA data - DER flexibility cost is a point estimate — actual costs vary by program type and scale - Single discount rate applied; real projects may use different rates for different components - Does not account for O&M cost differences between traditional and DER solutions - Does not model reliability or resilience benefits of distributed solutions --- ## Grid Infrastructure Data (Gridbase) > **Module:** `insight` (always on) | **Role:** Any member | **Licence:** Free+ Gridbase is the platform's energy infrastructure reference data layer. It normalizes and stores grid-level data from utility APIs, federal databases, and processed aggregations. ## What Gridbase Stores | Data Type | Description | Source | |-----------|-------------|--------| | **Hosting Capacity** | Per-feeder electric distribution capacity, headroom, constraints | Utility ICA/DRP portals | | **Substations** | Generation, demand, transformer ratings at distribution level | Utility APIs + HIFLD | | **Utility Boundaries** | Geographic service territory polygons | EIA Form 861 | | **Transmission Network** | Transmission lines and substations | HIFLD (DHS) | | **EV Registrations** | Electric vehicle registrations by geography | State DMV data | | **Political Boundaries** | State, county, municipal polygons | US Census | | **Hexbins** | H3 hexagon aggregations of circuits + EV data | Processed from above | ## Coverage 17 utility adapters covering 53,818 circuits and 4,249 substations across: - **California:** PG&E, SDG&E, SCE - **New York:** ConEd, NYSEG, RG&E, PSEG Long Island, Orange & Rockland, Central Hudson - **New England:** Eversource CT/MA/NH, United Illuminating - **Mid-Atlantic & Other:** National Grid MA, BGE, PEPCO, Xcel Energy See [Supported Utilities](utilities) for the full adapter registry and data completeness matrix. ## Key Design Principles - **All units normalized to MW** — adapters receiving kW convert on ingest - **All coordinates normalized to WGS84** — Web Mercator converted automatically - **All data files gzipped** — compressed storage for efficient loading - **Dynamic utility discovery** — derived from adapter registry + HIFLD fallback ## Services | Service | Description | |---------|-------------| | **Area Query** | Spatial queries for hosting capacity within geographic areas | | **Geocoding** | Address-to-coordinate resolution | | **Utility Resolver** | Coordinate-to-utility mapping (which utility services this location?) | | **Visualization** | Map generation for distribution data | ## Map Layers The grid intelligence map composes layers in three bands, bottom to top: 1. **Background** (DMV asset hexbins, transmission network) — context behind everything else. 2. **Network** (distribution circuits, substations, hosting-capacity hexbins) — the grid you'd plan VPP capacity against. 3. **Workspace data** (Known charging sites, future user-data layers) — the highest-prominence band, so your own evidence reads above the network context. "Known charging sites" appears when your workspace has the `platform:holistics` module enabled AND a user has connected their personal Holistics integration (Profile → Integrations). It renders dots for every location where one or more drivers in the connecting user's Holistics scope has at least one recorded charging session. Visible at city zoom and above. When you click a substation, the **asset bar** at the bottom is the single source of truth for customer-side counts (homes, EVs, solar, batteries, thermostats, public chargers). The values are pro-rated from utility totals to the substation's capacity share, with the methodology shown in the bar's note. The hover tooltip on the substation marker shows grid-intrinsic data only — voltage, capacity, available MW, demand, circuits — and never duplicates the asset bar. ## Related Documentation - [Hosting Capacity Data & Methodology](hosting-capacity) — ICA data sources, coverage, deferral financial assumptions - [Supported Utilities](utilities) — Full adapter registry, data completeness, field availability - [Integrations](../workspace/integrations) — Holistics setup for the "Known charging sites" layer --- ## Supported Utilities > **Module:** `insight` (always on) | **Role:** Any member | **Licence:** Free+ Gridbase includes 17 utility adapters that fetch hosting capacity data from public utility Integration Capacity Analysis (ICA) portals. ## Adapter Registry ### California | Utility | ID | Circuits | Substations | Voltage | Gen Data | Demand Data | |---------|-----|----------|-------------|---------|----------|-------------| | PG&E | `pge` | 3,025 | 715 | Yes | Yes | Yes | | SDG&E | `sdge` | 524 | 107 | Yes | Yes | Yes | | SCE | `sce` | 3,287 | 466 | Yes | Yes | No | ### New York | Utility | ID | Circuits | Substations | Voltage | Gen Data | Demand Data | |---------|-----|----------|-------------|---------|----------|-------------| | ConEd | `coned` | 1,026 | 30 | Yes | Yes | Yes | | NYSEG | `nyseg` | 578 | 373 | Yes | Yes | Yes | | RG&E | `rge` | 207 | 143 | Yes | Yes | Yes | | PSEG Long Island | `pseg_long_island` | 921 | 157 | Yes | Yes | No | | Orange & Rockland | `orange_rockland` | 271 | 80 | Yes | Yes | Yes | | Central Hudson | `central_hudson` | 135 | 69 | Yes | No | No | ### New England | Utility | ID | Circuits | Substations | Voltage | Gen Data | Demand Data | |---------|-----|----------|-------------|---------|----------|-------------| | Eversource CT | `eversource_ct` | 479 | 512 | Yes | Yes | No | | Eversource MA | `eversource_ma` | 316 | 92 | Partial | No | No | | Eversource NH | `eversource_nh` | 272 | 656 | Yes | Yes | No | | United Illuminating | `united_illuminating` | 248 | 29 | Yes | Yes | No | ### Mid-Atlantic & Other | Utility | ID | Circuits | Substations | Voltage | Gen Data | Demand Data | |---------|-----|----------|-------------|---------|----------|-------------| | National Grid MA | `national_grid_ma` | 967 | 242 | Yes | Yes | No | | BGE | `bge` | 37,704 (grid cells) | — | No | No | No | | PEPCO | `pepco` | 780 | 90 | Partial | No | No | | Xcel Energy | `xcel` | 3,078 | 488 | Yes | Yes | No | **Totals:** 53,818 circuits, 4,249 substations ## Data Fields Each feeder/circuit record includes (where available): | Field | Description | Coverage | |-------|-------------|----------| | Feeder ID / Name | Unique circuit identifier | All utilities | | Latitude / Longitude | WGS84 coordinates | All utilities | | Total Capacity (MW) | Feeder rated capacity | All utilities | | Available Capacity (MW) | Remaining headroom for new DER | All utilities | | Constraint Type | Thermal, voltage, or protection | Most utilities | | Utilization % | Current load as fraction of capacity | Most utilities | | Substation Name | Parent substation | Most utilities | | Voltage (kV) | Feeder voltage class | 11 utilities | | Existing DG (MW) | Distributed generation already connected | 10 utilities | | Peak Demand (MW) | Historical peak load | 8 utilities | ## Capacity Levels | Level | Threshold | Color | |-------|-----------|-------| | High | >= 2 MW available | Green | | Medium | 0.5-2 MW available | Amber | | Low | < 0.5 MW available | Red | | Unknown | No data | Gray | ## Refresh Frequency Utility ICA data is updated **quarterly** by utilities. Gridbase fetches are triggered manually or via scheduled jobs. HIFLD transmission data is updated annually. --- ## Connecting an AI client to Eve > **Module:** None (platform) | **Role:** Any member (Workspace) or EV driver (Connect) | **Licence:** Free+ | **Auth:** OAuth 2.1 Eve is reachable as a Model Context Protocol (MCP) server from any MCP-compatible client. There are **two surfaces**; pick the one that matches what you're building (see [Building on Eve](/developers/building-on-eve) and the [MCP overview](/mcp/overview)). | Surface | Endpoint | Audience | Auth | Tools | |---|---|---|---|---| | **Driver (Connect)** | `https://eve.ev.energy/connect/mcp` | EV drivers (B2C) | ev.energy OAuth (Clerk-fronted sign-in) | the [15 enrollment verbs](/connect/verbs) | | **Workspace (Platform)** | `https://eve.ev.energy/mcp` | Workspace members (B2B) | OAuth 2.1 / PKCE | full tool suite, filtered by enabled modules | --- ## Driver surface — `/connect/mcp` Gives a driver's AI client the 15 enrollment verbs acting on **their own ev.energy account**. ### Config block ```json { "mcpServers": { "ev-eve": { "url": "https://eve.ev.energy/connect/mcp" } } } ``` ### First-run OAuth On first use the client opens a browser window for ev.energy sign-in — an ev.energy-branded page that **never asks for your password through the AI client**; you authenticate with your ev.energy account directly. Once you authorise, the 15 verbs become available in your client. The MCP bearer is issued by ev.energy and scoped to the `/connect` surface. ### Token refresh The same authorisation carries forward — repeated sessions use refresh tokens automatically, so you don't re-sign-in every time. To disconnect, sign out of the client (it forgets the token) or revoke it via the `/connect/oauth/revoke` flow; the client then re-OAuths on next use. --- ## Workspace surface — `/mcp` Gives a workspace member the full Eve tool suite — simulation, grid intelligence, hosting capacity, charts, reports, policy agents, and agent/skill management — filtered by the workspace's enabled modules. ### Option 1 — OAuth (recommended) No key to copy. Point the client at the endpoint with no headers: ```json { "mcpServers": { "eve": { "url": "https://eve.ev.energy/mcp" } } } ``` On first use a browser window opens to the provider-selection page; choose ev.energy, Google, or Microsoft SSO. OAuth uses PKCE (S256). Access tokens last 60 minutes and refresh automatically for 30 days. OAuth connections run as **private** scope, so your personal / restricted agents are visible. Workspace API keys have been removed. OAuth with scoped keys for headless access is planned. Full credential detail is in [API authentication](/api/authentication). --- ## Client-specific setup The config blocks above are the same shape across clients; where they live differs. | Client | Where to add the config | Notes | |---|---|---| | **Claude Code (CLI)** | `~/.claude/settings.json` (user) or project `.mcp.json` | Fully supported — all tools, all operations. | | **Claude Code (VS Code / JetBrains)** | Same as the CLI | Same support as the CLI. | | **Claude Desktop** | Settings → Developer → Edit Config (the `claude_desktop_config.json` `mcpServers` block) | Supported; long operations (>30s) may time out. | | **Claude.ai (web)** | Settings → Connectors / Integrations → Add MCP server (enter the URL) | Tool calls work; very long operations may time out. | | **ChatGPT** | Add as an MCP connector (where supported by your plan) | Use the surface URL; OAuth on first use. | | **Cursor** | MCP settings → add server with the URL | OAuth on first use. | | **Gemini / other MCP clients** | Per the client's MCP server config | Point at the surface URL. | After sign-in on the driver surface, the `/connect/account` page offers copy-paste config snippets for these clients. --- ## How tools are filtered by enabled modules (Workspace surface) On the Workspace MCP, the tool list a client sees is **filtered per connection** by the workspace's enabled modules and the caller's scope: - `insight` (always on) — simulation, grid data, charts, hosting capacity, docs. - `insight:policy` — policy agent dispatch tools. - `operations:agents` — agent and skill management tools. - `programs:connect` — partner campaign tools (create/manage campaigns, contacts, tracked links, analytics). See [partner verbs](/programs/verbs). - `programs:affiliate` — partner code tools (referral/promo codes + redemptions). See [partner verbs](/programs/verbs). A tool never appears in `tools/list` for a connection that can't use it, and an unauthenticated connection sees an empty list (no tool names leaked). Enabling a module for the workspace makes its tools appear automatically. An OAuth connection always works in your own current workspace: if an admin moves you to another one, your client is asked to reconnect and then sees that workspace's tools. See the [MCP overview](/mcp/overview) for the per-module tool tables. --- ## Notes and limitations - **Synchronous transport.** Both surfaces use stateless HTTP — tool results return as a single response after the tool finishes. Dispatch tools (agent loops) take a few seconds; operations that take minutes (report generation, deep policy research) are better run from the web chat at `eve.ev.energy`. - **No streaming or progress for MCP tool calls** — this is a property of the stateless HTTP transport chosen for broad client compatibility. The web chat provides real-time streaming. - **Surface isolation.** A `/connect` token cannot call `/mcp` tools and vice versa; the boundary is enforced by the token issuer claim. → See also: [the 15 Connect verbs](/connect/verbs) · [MCP overview](/mcp/overview) · [API authentication](/api/authentication). --- ## MCP Server > **Module:** None (platform) | **Auth:** OAuth 2.1 | **Role:** Any member | **Licence:** Free+ Eve is accessible as an MCP (Model Context Protocol) server, allowing Claude Code, Claude Desktop, and other MCP clients to use Eve's tools directly. There are **two MCP surfaces**, each with its own audience and tool scope: | Surface | Endpoint | Audience | Tools | Auth | |---|---|---|---|---| | **Workspace Eve** | `https://eve.ev.energy/mcp` | Workspace members (B2B) — utility / fleet operators, analysts, engineers | All `insight` / `insight:policy` / `operations:agents` tools (filtered by enabled modules) | OAuth 2.1 | | **Driver Eve** | `https://eve.ev.energy/connect/mcp` | Individual EV drivers (B2C) | 15-verb enrollment surface only — `my_account`, `discover`, `connect_device`, `update_account`, `my_transactions`, `refer_friend`, the card verbs (`activate_charging_card`, `add_payment_card`, `update_card`, `remove_card`), `my_notifications`, etc. | ev.energy OAuth bearer (driver's own token) | The rest of this page documents **Workspace Eve**. For the driver-side surface, see [Connect — driver-facing Eve](../connect.md). **Endpoint:** `https://eve.ev.energy/mcp` ## Connection Setup ### OAuth Add to your MCP client configuration: ```json { "mcpServers": { "eve": { "url": "https://eve.ev.energy/mcp" } } } ``` On first use, a browser window opens showing a provider selection page. Choose your sign-in provider (ev.energy, Google, or Microsoft) to authenticate. Tokens auto-refresh for 30 days. **Claude Code:** Add to `~/.claude/settings.json` or project `.mcp.json`. **Claude.ai:** Settings > Integrations > Add MCP Server. Workspace API keys have been removed. OAuth with scoped keys for headless access is planned. ## Tools by Module Tools are dynamically filtered based on your workspace's enabled modules: | Module | Example Tools | Description | |--------|--------------|-------------| | `insight` (always on) | `create_scenario`, `add_evs_to_scenario`, `simulate_and_graph_scenario`, `analyze_load`, `show_region`, `query_hosting_capacity`, `get_platform_doc` | Simulation, grid data, charts, docs | | `insight:policy` | `ask_policy_researcher`, `ask_policy_librarian`, `ask_policy_navigator` | Policy agent dispatch tools | | `operations:agents` | `create_agent`, `update_agent`, `remove_agent`, `list_agents`, `create_skill`, `create_agent_team` | Agent and skill management | | `programs:connect` | `list_campaigns`, `view_campaign_performance`, `create_campaign`, `update_campaign`, `create_contacts`, `launch_campaign` | Partner campaigns — tracked links, contacts, clicks, performance ([verbs](/programs/verbs)) | | `programs:affiliate` | `list_codes`, `create_code`, `update_code` | Partner codes — redemptions + qualified, no amounts ([verbs](/programs/verbs)) | ### Hosting Capacity Tools (with `insight`) - `query_hosting_capacity` — Query grid capacity for a location - `set_scenario_capacity_limit` — Constrain simulation to grid capacity - `analyze_hosting_capacity_constraints` — Analyze capacity impact - `calculate_hosting_capacity_deferral_benefit` — Calculate deferral value ## Resources Platform documentation is available as MCP resources: ``` resource://docs/simulations/overview resource://docs/simulations/ev-charging resource://docs/grid/hosting-capacity resource://docs/agents/overview ... ``` Fetch any document on demand via the resource URI. ## Authentication Scopes | Auth Method | Scope | Private Agents | |-------------|-------|---------------| | OAuth (browser SSO) | Private | Yes — personal/restricted agents visible | ## Security - All requests require an OAuth Bearer token - PKCE required for OAuth (S256 only) - Single-use authorization codes (5-minute TTL) - Token rotation on refresh (old token revoked atomically) - MCP access tokens are 60-minute JWTs; refresh tokens last 30 days ## Client Compatibility | Client | Status | Notes | |--------|--------|-------| | Claude Code (CLI) | Fully supported | All tools, all operations | | Claude Code (VS Code / JetBrains) | Fully supported | Same as CLI | | Claude.ai (web) | Supported | Tool calls work; long operations (>30s) may timeout | | Claude Desktop (Windows/Mac) | Supported | Same as Claude.ai | **Note:** Dispatch tools (agent calls like `ask_policy_librarian`) run multi-turn agent loops that take 5-15 seconds. The MCP server uses synchronous HTTP transport for maximum client compatibility. For operations that take minutes (report generation, deep policy research), use the web chat at eve.ev.energy. ## Known Limitations - **No streaming for MCP tool calls** — results are returned as a single JSON response after the tool completes. The web chat interface at eve.ev.energy provides real-time streaming for long operations. - **No progress indicators** — MCP clients see no feedback during tool execution. This is a limitation of the stateless HTTP transport required for broad client compatibility. --- ## Public Charging (eMSP) > **Module:** `operations:emsp` | **Role:** Workspace Admin (manage), Member (read), Platform Admin (licence + enable) | **Licence:** Provisioned by ev.energy The eMSP (e-Mobility Service Provider) module lets your workspace authorise public-charging taps against your Charge & Earn balance. You register the RFID cards your drivers tap with, choose who pays for each card's charging, and see every authorisation as it happens. The card issuer (Paua for the trial) is set up once by ev.energy for every workspace. When a driver taps one of your cards at a charger, the issuer asks the eMSP and gets an instant approve or decline. ## Getting set up Two things happen before you can use the tools, and only the first needs anyone outside your workspace: 1. **A platform admin grants your workspace the `operations:emsp` licence.** This makes the module available to enable. (ev.energy does this for you as part of onboarding.) 2. **Enable the module for your workspace.** A workspace admin or owner turns `operations:emsp` on in workspace settings (a platform admin can also do it for you). **Enabling automatically links your organisation into the eMSP**: there are no keys or credentials for you to create or paste. Once it is on, the `operations:emsp` tools appear for your workspace. (If your organisation is not connected yet, enabling won't finish the link: the tools appear but report that the eMSP isn't set up. Ask ev.energy to confirm your organisation is connected, then turn the module off and on again.) That is the whole setup. From here everything is done from inside your workspace. ## Administering it from your workspace All of the actions below are workspace-admin actions. Every change is confirm-then-apply: Eve shows you exactly what will happen and waits for your confirmation before it does it. **Your card issuer** There is nothing to set up. ev.energy runs the card issuer for the whole platform (Paua for the trial) and holds its credential. Turning the module on links your organisation to it, and your drivers' taps through that issuer are then authorised against your balance. You never create, see or rotate an issuer credential, and there is no issuer to suspend from your workspace: the module switch is your only control (see below). **Manage the cards** - **Register RFID cards** you hold, in a batch of up to 500. Each card needs **both** its chip uid and the id printed on it: any charger can read a uid, so the printed id is the proof a card is in hand. A registered card is usable and belongs to no driver yet. - A driver activates a card (in the app or widget) by the id printed on it, which binds it to their account. - **Pause or resume a card** — reversible, for a driver who has mislaid one and may still find it. A pause you make stays until you or ev.energy lift it: the driver can't resume it, and pausing a card the driver already paused makes the pause yours. A card frozen at its issuer is treated the same way. - **Return a card to your pool** if the wrong person activated it, so the right driver can take it. This is the only way to recover a mis-issued card, and it is worth knowing about: the alternative below spends the card for good. - **Block a card** if it is lost or stolen, or **retire** one you no longer want. Both are permanent — the card can never be activated again by anyone, including its original holder, and your pool is one card smaller. Both act on a card a driver is holding: a card still sitting in your pool has nothing to block or retire, and asking is refused. **Choose who pays for a card: your organisation or the driver** Every card has one payer, and it is the card's, not the driver's. A new card is paid for by its driver, from their own ev.energy account, until you say otherwise. - **Make a card your organisation's to pay for**, and its charging goes on your organisation's account, up to the credit limit ev.energy sets for you. A driver must have activated the card first: a card still sitting in your pool cannot be made yours to pay for, and asking is refused. If your credit limit is still zero, the change is made but Eve warns you, because every tap you pay for is declined until ev.energy raises the limit. - **Hand a card back to its driver to pay for** when your organisation should stop paying, for example when the driver leaves. That is the step that stops the money. - Because the payer belongs to the card, one driver can hold a work card you pay for and a personal card they pay for themselves. - Blocking, retiring or returning a card to your pool hands it back to its driver to pay for, so the next person to activate it never charges on your account by accident. Pausing a card keeps its payer. - **List the cards your organisation pays for** at any time, or the ones its drivers pay for. **Keep an eye on it** - **View recent authorisations** to see the taps that were approved or declined, and why. - **View the lifecycle log** to see what was *done to* your organisation — cards frozen, blocked or returned to the pool; cards made yours to pay for or handed back to their driver — each with who did it, why, and when. A card handed back appearing here is worth knowing: it is the step that stops your organisation paying for it, and it is auditable. - The two answer different questions: authorisations are what a driver tried to do, the lifecycle log is what your team did. - Both look back **24 hours by default**, up to 90 days, and tell you when a period holds more than one page carries — if it does, narrow the window rather than expecting a second page. You can narrow the lifecycle log to a single card or driver. - Any member of your workspace can do both (see below). ## Who can do what | Action | Workspace Admin | Member | |---|:---:|:---:| | Register RFID cards | ✅ | — | | Pause, resume, return to pool, block or retire a card | ✅ | — | | Choose who pays for a card: your organisation or the driver | ✅ | — | | List RFID cards, and who pays for each | ✅ | ✅ | | View recent authorisations | ✅ | ✅ | | View the lifecycle log | ✅ | ✅ | In short: **anything that changes state is workspace-admin only; the read-only views are open to any member.** Granting the licence is a platform-admin step (above); after that, the module switch is the whole connection. Turning `operations:emsp` **on** connects your organisation to the eMSP; turning it **off** disconnects it — your issuer's taps stop being approved, and your team stops seeing the tools. There is no separate disconnect step. Turning it off is **not a pause**. Your issuer's taps stop being approved as soon as you switch it off, and every card registered to your organisation is **retired**: nobody can use those cards again, whoever holds them. Switching the module back on reconnects the same organisation, with its history, but the old cards stay retired and must be re-issued. To stop one card or one driver rather than everything, freeze the card or hand it back to its driver to pay for instead. --- ## Eve's Knowledge & Platform Docs > **Module:** `insight` (always on) for `get_platform_doc`; librarian agents for knowledge vaults | **Role:** Any member | **Licence:** Free+ (docs), Pro+ (knowledge vaults) Eve has two distinct knowledge systems: **platform documentation** (how the product works) and **knowledge vaults** (curated regulatory and domain intelligence managed by librarian agents). Both are queryable during a conversation. --- ## Platform Documentation Eve can look up how the platform works at any time using the `get_platform_doc` tool. This covers: - How to create and configure agents - What simulation capabilities are available - How the policy intelligence module works - How to connect external tools via MCP **Example questions Eve can answer:** - "How do I create a new agent?" - "What flexibility modes does the simulation engine support?" - "How does the policy librarian agent store regulatory notes?" Eve fetches the relevant documentation page on demand — it is not pre-loaded into every conversation, keeping responses fast and focused. --- ## Knowledge Vaults Knowledge vaults are curated collections of notes maintained by **librarian agents**. Each team has its own vaults, populated by its librarian agents over time. ### What's in a knowledge vault Notes are structured markdown with standard metadata: title, source, tags, last updated date, and relevance. Categories include: | Category | Contains | |---|---| | **Reports** | Company and market analysis | | **Positions** | Official stances and frameworks | | **Assumptions** | Model inputs and constraints | | **Regulatory** | Jurisdiction-specific regulatory intelligence | ### Querying knowledge Ask the relevant librarian agent in conversation: ``` "Ask the policy librarian about FERC Order 2222 in California" ``` Eve dispatches to the librarian, which searches its vault and returns matching notes with sources and metadata. Each librarian has a dispatch tool (e.g. `ask_policy_librarian`) listed in the Knowledge Pools index. ### Folder organisation Notes inside a vault are organised into folders using path-based IDs. You can ask a librarian to store something in a specific folder: ``` "Store the AI-First Playbook under references/ev.energy/" "File this report under published/ai-transformation/ dated 2026-04-14" ``` Librarian agents understand folder paths like `references/ev.energy/ai-first-playbook` and create the physical folder hierarchy automatically. The vault index groups notes by folder so you can browse by topic area. To **move** an existing note to a different folder, ask the librarian to: 1. Retrieve the note content 2. Delete the old entry 3. Store it again with the new folder path ### What knowledge is available to you The knowledge pools available in your conversation depend on: 1. **Your team's enabled modules** — the policy intelligence module must be active for policy librarian access. 2. **Agent visibility** — some librarians are restricted to specific team members. 3. **Conversation context** — restricted agents are not accessible in shared conversations. Eve's system prompt lists the knowledge pools available in your current session. If a pool you expect is not listed, contact your account manager about module access. --- ## How the two systems relate | System | Content | Updated by | Queried via | |---|---|---|---| | Platform docs | How the product works | Engineering (git) | `get_platform_doc` | | Knowledge vaults | Regulatory & domain intelligence | Librarian agents (nightly) | Librarian dispatch tools | Platform docs describe the platform itself. Knowledge vaults contain the intelligence your librarian agents have gathered about the world — regulatory developments, market data, and research relevant to your fleet strategy. --- ## Policy Intelligence Team > **Module:** `insight:policy` | **Role:** Any member | **Licence:** Pro+ > **Dispatch tools:** `ask_policy_explorer`, `ask_policy_librarian`, `ask_policy_navigator`, `ask_policy_analyst`, `ask_policy_steward` The Policy Intelligence team is a built-in agent team gated behind the `insight:policy` module. It provides five specialized agents for regulatory intelligence across US, UK, Canadian, and Dutch jurisdictions. ## Team Agents | Agent | Pattern | Role | Key Capabilities | |-------|---------|------|-----------------| | **Policy Explorer** | Explorer | Monitor external signals | Web search for regulatory developments, scan entity portals, fetch specific URLs | | **Policy Librarian** | Librarian | Store and retrieve knowledge | Manage the regulatory knowledge vault, store/update notes, search findings | | **Policy Navigator** | Navigator | Track and flag | Team interests, personal alert prefs, watchlist management, entity portal tracking | | **Policy Analyst** | Analyst | Synthesize and report | Generate digests, collect feedback, accept user-submitted findings, preview drafts | | **Policy Steward** | Steward | Watch and defend the vault | Mine team chat for coverage gaps, scan the vault for anomalies (dead URLs, new-source domains, duplicates), flag or remove unreliable findings, post a daily summary to `#policy` | ## Tools by Agent ### Policy Explorer (Researcher) | Tool | Description | Cost | |------|-------------|------| | `researcher_search` | Search the vault for existing findings | FREE | | `researcher_scan` | Systematic scan of entity portals and jurisdiction-specific sources | MODERATE | | `researcher_fetch` | Fetch and clean content from a specific URL | FREE | | `web_search` | Anthropic server-side web search | FREE | ### Policy Librarian | Tool | Description | Cost | |------|-------------|------| | `librarian_query` | Search and retrieve from the knowledge vault (by text, category, tags, or note_id). Call with no args for vault summary | FREE | | `librarian_store` | Store a verified finding in the vault (with dedup checking + jurisdiction-aware routing) | FREE | | `librarian_delete` | Remove a note by ID | FREE | | `librarian_index` | Fast snapshot of vault contents grouped by folder, with aggregate breakdowns by category, relevance, and top tags. No content bodies | FREE | | `librarian_update` | Patch metadata (tags, relevance, category, title, source, source_url) on an existing note without re-submitting content | FREE | ### Policy Navigator | Tool | Description | Cost | |------|-------------|------| | `policy_config` | Read/write team interests (jurisdictions, topics, cadence), personal alert prefs, entity portal tracking, chat mining toggle | FREE | | `tracker_add` | Add a specific item to the watchlist (proceeding, legislation, etc.). Also stores a vault note so the Librarian can find it | FREE | | `tracker_list` | List watchlist items, filter by status/jurisdiction/type | FREE | | `tracker_update` | Update priority, keywords, status, or close a watchlist item | FREE | ### Policy Analyst | Tool | Description | Cost | |------|-------------|------| | `analyst_digest` | Read latest digest, generate a fresh one, or preview the next draft | FREE (read/preview) / EXPENSIVE (generate) | | `digest_feedback` | Submit feedback signals on findings: relevant, irrelevant, outdated, misclassified, correction, mute_topic, mute_source | FREE | | `submit_finding` | Submit a policy news item for inclusion in the next digest. Queued, then merged into the next digest and stored in the vault permanently. | FREE | ### Policy Steward | Tool | Description | Cost | |------|-------------|------| | `steward_mine_signals` | Mine recent team chat messages for coverage gaps and regulatory topics | MODERATE | | `steward_query_signals` | Retrieve signals from the most recent chat mining run | FREE | | `steward_mine_vault_anomalies` | Scan the vault for anomalies (dead URLs, duplicates, future-dated events, new source domains). Flags or removes unreliable findings within a per-run rate limit; every mutation is git-audited | MODERATE | ## Knowledge Vault The Policy Librarian maintains a structured knowledge vault with: | Category | Contains | |----------|---------| | **Regulatory** | Per-jurisdiction frameworks, proceedings, findings (append-only ledgers) | | **Reports** | External research reports and industry studies | | **Positions** | ev.energy company positions on policy topics | | **Case Studies** | Utility program case studies | ### Querying Knowledge Ask the policy librarian in conversation: ``` "Ask the policy librarian about FERC Order 2222 in California" ``` Eve dispatches to the librarian, which searches the vault and returns matching notes with sources and metadata. ### Vault Gardening The Librarian can audit and maintain vault health using `librarian_index` and `librarian_update`: 1. Run `librarian_index` to get a snapshot of all notes with metadata quality indicators 2. Identify notes with missing tags, wrong relevance, stale categories, or no source URL 3. Use `librarian_update` to patch metadata without re-submitting the full note content 4. Use `librarian_delete` to remove duplicates or obsolete notes ## Workflows ### Nightly Regulatory Scan The Explorer runs nightly to scan for new regulatory developments, appending findings to jurisdiction-specific findings files with unique IDs (e.g., `CA-20260401-001`). ### On-Demand Research Ask Eve: "What's the latest on VPP policy in New York?" — Eve dispatches to the Explorer for web research and the Librarian for vault context. ### Regulatory Digests The Analyst generates periodic jurisdiction digests summarizing recent findings, upcoming deadlines, and recommended actions. Digests have four sections: - **Headlines** — breaking regulatory events this period - **Proceeding Updates** — new activity on tracked dockets - **Watch List** — upcoming implementation deadlines - **Tracked Items** — status of each watchlist item (update found or no activity) Digests enforce a freshness ceiling: items whose real-world event is older than the team's configured maximum age (default 30 days) are suppressed rather than re-surfaced, and the digest preamble reports how many were suppressed. Admins can tune this with `policy_config(max_finding_age_days=...)`. ### Preview Before Sending Use `analyst_digest(preview=true)` to see what the next digest would contain — vault findings, user submissions, and applied feedback — without generating or storing anything. ### Digest Feedback Users can improve future digests by providing feedback signals: | Signal | Use when... | Required field | |--------|------------|----------------| | `relevant` | A finding was useful | `finding_id` (optional) | | `irrelevant` | A finding wasn't relevant | `finding_id` (optional) | | `outdated` | A finding is stale (deadline passed, info old) | `finding_id` | | `misclassified` | Wrong jurisdiction, topic, or type | `finding_id` + correction fields | | `correction` | Factual error (wrong date, detail) | `finding_id` + correction fields | | `mute_topic` | Stop showing a topic | `topic` | | `mute_source` | Stop showing a source | `source` | Feedback is applied automatically: outdated/irrelevant findings are excluded, muted topics/sources are filtered, and corrections are passed to the Analyst for the next digest. ### Submit Missing Findings When the digest misses something, users can submit policy news directly: ``` "Add this to the next digest: CalChoice is launching DERMS for VPP support" ``` The finding is: 1. Queued in the submission table (status: pending) 2. Merged into the next digest generation automatically 3. Stored in the vault permanently so the Librarian can find it in future searches ### Watchlist Tracking The Navigator maintains a watchlist of proceedings and deadlines, flagging items that need attention. When a tracking item is added via `tracker_add`, it is: 1. Created in the tracking database (for nightly scan prioritization and digest reporting) 2. Stored as a vault note (so the Librarian can find it in knowledge searches) After adding a tracked item, the Navigator checks if its jurisdiction is in the team's scan scope and prompts to add it if not. ## Configuration Workspace admins configure the policy module via workspace settings: - **Jurisdictions**: Which states/countries to monitor - **Topics**: Filter for relevant policy areas (DR, VPP, DER, rate design, etc.) - **Digest delivery**: Recipients and frequency - **Personal alerts**: Per-user topic preferences (controls @-mentions in digests) - **Entity portals**: Custom URLs for the Explorer to check on each scan - **Chat mining**: Automatic weekly analysis of team chats to discover coverage gaps (default: on) - **Digest style**: Workspace-specific tone, section ordering, and phrasing preferences for the digest. The platform default applies unless an override is saved on the **Digest Style** tab. Hard rules — every finding must appear, no fabrication, no jurisdiction collapsed — are enforced in code and cannot be turned off via the override. ## Data Flow ``` User submits finding ──→ policy_user_findings (DB queue) │ Navigator: tracker_add ──→ tracking_items (DB) + vault note (git) │ Nightly: Explorer scans ──→ Librarian stores ──→ vault (git) │ ┌────────────────────┘ ▼ Analyst: collect_findings (vault) + pending submissions (DB) → exclude outdated/irrelevant (feedback) → merge user submissions → Claude synthesis → store digest (DB) + mark submissions included → store user submissions in vault (permanent) → deliver (in-app, email, Slack) ``` ## Module Requirement Requires `insight:policy` module. Available on Pro and Enterprise licence tiers. Contact your account manager for access. --- ## Partner campaign & affiliate verbs > **Modules:** `programs:connect` (campaigns) + `programs:affiliate` (codes) | **Endpoint:** Workspace MCP at `https://eve.ev.energy/mcp` | **Auth:** MCP OAuth | **Scope:** every verb is workspace-scoped — the workspace comes from the authenticated connection, never a parameter. The partner surface lets an organisation recruit EV drivers with tracked campaign links and referral/promo codes, and measure the result. It is split across two modules that a workspace enables independently: - **`programs:connect`** — campaigns: create and change them, get their tracked links, add and invite contacts, and read how they are doing. - **`programs:affiliate`** — codes: mint and manage the organisation's referral/promo codes and read their redemptions. Every verb here is also available on the **partner web pages** (Affiliate, Campaigns, Campaign detail, Codes) when the modules are enabled — the web and the MCP tools read the same data, so they can never disagree. To wire an AI client to this surface see [connecting a client](/mcp/connecting). --- ## The pipeline & what the figures mean The partner funnel is four figures, in order: **Campaigns → Clicks → Redemptions → Qualified** - **Campaign** — the unit of work. A campaign is a free-text **name** plus an optional **`landing_url`** (an ev.energy page a driver lands on) an optional **`referral_code`**, and optional **`forward_params`** (the link parameters it passes on to the landing page). There is **no programme catalogue** — `program_id` is a free-text label only. - **Clicks** — *ours*, counted in real time. Every follow of a campaign's tracked `/connect/j/{short_code}` share link is a click, attributed per campaign (and per contact when the link carries a contact tag). - **Redemptions** — *core's*. A driver who signs up using one of the organisation's codes is a redemption. This is core's per-code `redeemed_count`. - **Qualified** — the subset of redemptions that completed a **qualifying charge** — core's per-code `qualified_count`. Qualified is always at or below redemptions. Three honesty rules the whole surface follows: - **Redemptions and qualified read `TBC` until the workspace is linked to an ev.energy organisation** (and its codes can be read). Clicks are workspace-local, so they are always real. A figure that cannot be read is shown as TBC, never as `0`. - **Conversions are per-code, aggregate and anonymised** — never per-driver. There is no per-referee identity on this surface. - **No monetary amounts are shown.** Core does not report money yet, so any amount reads **TBC**. No amount is ever computed or returned by these verbs. --- ## `programs:connect` — campaign verbs Two reads and four writes. `list_campaigns` holds what you have (settings, links, contacts); `view_campaign_performance` holds how it is doing (the numbers). ### `list_campaigns` Without `campaign_id`: your campaigns, newest first, each with its settings and **link**, plus your workspace's own referral link. With `campaign_id`: that campaign's settings, link and a page of contacts (each with clicks and invite state). | Parameter | Type | Required | Description | |---|---|---|---| | `campaign_id` | string | no | Open one campaign. | | `status` | string | no | Only campaigns in this status: `draft`, `active`, `paused`, `completed`. | | `include_archived` | boolean | no | Include archived campaigns. Default false. | | `limit` / `offset` | integer | no | Paging (1–100 campaigns, 1–200 contacts, default 50). Page while `has_more` is true, or `contacts_has_more` when a `campaign_id` is given. | **Each link** carries `share_link`, an `example` with the forwarded parameters filled in, `credits` (the referral code, or `null` when it credits nobody), `forwards` (the parameters it passes on), and `you_can_add`: | Add to a link | Meaning | |---|---| | `?c=` | A per-contact link; the click counts against that contact. | | `?utm_source=` | The channel, e.g. `qr` or `linkedin`; `src` is a short alias. | | `?test=1` | Preview the destination without counting a click. | | `?=…` | Recorded on every click; passed to the landing page only if the campaign lists it in `forward_params`. | ### `view_campaign_performance` How your campaigns are doing. Without `campaign_id`: totals and a daily clicks-vs-redemptions series over a window (default the last 30 days). With `campaign_id`: its all-time `stats` and `referral_funnel`, plus `clicks_in_window`, the clicks in the window by channel and by each parameter in the campaign's `forward_params` (for example, scans per `printed_id`). Only `clicks_in_window` is windowed. A figure that cannot be read is `null`, never `0`. An active campaign closes itself once every contact has finished. | Parameter | Type | Required | Description | |---|---|---|---| | `campaign_id` | string | no | One campaign; omit for all. | | `since` / `until` | string | no | ISO dates for the window. | ### `create_campaign` Create a campaign in **draft** and get its link. | Parameter | Type | Required | Description | |---|---|---|---| | `name` | string | **yes** | Campaign name, e.g. `"Paua cards: referral"`. | | `landing_url` | string | no | Where the link sends people: an `https` ev.energy address. | | `referral_code` | string | no | The code the link credits, 2–16 letters/digits. Omit for a link that credits nobody, such as card activation. | | `forward_params` | array | no | Link parameters to pass to `landing_url`, e.g. `["printed_id"]`. A link to the card activation page always passes `printed_id`. | | `program_id` | string | no | Free-text programme label. | | `webhook_url` | string | no | Your server's `https` webhook for invite task updates. Not a driver redirect. | `promo_code`, `c`, `utm_source`, `src` and `test` belong to the link itself, so `forward_params` refuses them with an error that names the clash. So are keys a landing page may read as a referral code (`ref`, `code`, `coupon`, `promo`, `promocode`, `referral`, `referral_code`, `referred_by`): forwarding one would let anyone with the link credit their own code. ### `update_campaign` Change a campaign. Only the fields you pass change, and links already shared follow the new settings. | Parameter | Type | Required | Description | |---|---|---|---| | `campaign_id` | string | **yes** | Campaign to change. | | `name`, `landing_url`, `referral_code` | string | no | New values; `''` clears `landing_url` or `referral_code`. | | `forward_params` | array | no | Replaces the forwarded parameters; `[]` forwards none. | | `status` | string | no | `active`, `paused` or `completed`. `completed` is final and needs `confirmed: true`. | | `archived` | boolean | no | `true` hides the campaign (history kept); `false` restores it. | | `confirmed` | boolean | no | Set only after the user agrees to close the campaign. | ### `create_contacts` Add driver contacts so `launch_campaign` can invite them. Each needs an `email`; `name` and `phone` are optional. Duplicates and invalid emails are skipped and counted. ### `launch_campaign` Send a campaign's invites: an enrolment task and invite link for every contact not yet launched, and the campaign moves to active. Safe to call again after adding contacts. | Parameter | Type | Required | Description | |---|---|---|---| | `campaign_id` | string | **yes** | Campaign to launch. | | `base_url` | string | no | Origin for invite links, e.g. `https://eve.ev.energy`. | ### `enroll_user` Create a single A2A enrolment task to onboard one user into smart charging (EV, charger, home battery, or solar). Returns an auth URL to share; poll `get_enrollment_task_status` until it reaches a terminal state. The task **completes when the invited user accepts the invite** on Eve Connect (the invite only works for the email it was issued to). `completed` means *invite accepted*, not *enrolled in smart charging*: what the user does on Connect afterwards is theirs, and nothing about their account is reported back. An invite that expires unaccepted moves the task to `failed`. | Parameter | Type | Required | Description | |---|---|---|---| | `user_email` | string | no | User's email (a hint). | | `program_id` | string | no | Smart-charging programme ID. | | `message` | string | no | Free-text enrolment request. | **Returns:** `task_id` and the auth URL. ### `get_enrollment_task_status` Poll the status of a task created by `enroll_user` (or `launch_campaign`). | Parameter | Type | Required | Description | |---|---|---|---| | `task_id` | string | **yes** | Task ID returned by `enroll_user`. | **Returns:** the task `state` (`input_required`, `completed`, `failed` or `canceled`) and `invite_accepted` (true once the user has accepted the invite). --- ## `programs:affiliate` — code verbs Reads are open to any workspace member; **writes (`create_code`, `update_code`) are admin/owner only**. All three require the workspace to be **linked to an ev.energy organisation** — without the binding they return a clear "not linked" message rather than an empty account. **No verb ever returns a monetary amount.** ### `list_codes` Every code the organisation owns, active **and** disabled, each with **redemptions** (`redeemed_count`), how many **qualified** (`qualified_count`), its `share_link` and `qr_url`. With `redemptions: true` it returns individual redemptions instead: **one row per redemption, not per driver**, anonymised. No amounts. | Parameter | Type | Required | Description | |---|---|---|---| | `redemptions` | boolean | no | `true` for redemption rows instead of codes. | | `code` | string | no | With `redemptions`: one code, e.g. `"SUNRUNQ3"`. | | `since` | string | no | With `redemptions`: on or after this date (`YYYY-MM-DD`). | ### `create_code` Mint a new code owned by the organisation. Codes are **2–16 characters, letters and digits only** (no hyphens); the shape is checked before anything is sent. Admin/owner only. | Parameter | Type | Required | Description | |---|---|---|---| | `code` | string | **yes** | The public code drivers type, e.g. `"SUNRUNQ4"`. | | `label` | string | no | Internal name for your reference; not shown to drivers. | | `campaign_ref` | string | no | Optional tag for grouping codes in reporting. | **Returns:** the created code. ### `update_code` Rename, retag, or **disable** a code. The code string is immutable and a code is **never deleted**. Admin/owner only. | Parameter | Type | Required | Description | |---|---|---|---| | `code` | string | **yes** | Which code to change. | | `label` | string | no | New internal name. | | `campaign_ref` | string | no | New reporting tag. | | `status` | string | no | `inactive` disables the code — it stops attributing new sign-ups; its redemption history is kept. | **Returns:** the updated code. --- ## The full set at a glance | Verb | Module | Write? | Notes | |---|---|---|---| | `list_campaigns` | connect | read | your campaigns, settings, links; one campaign's contacts | | `view_campaign_performance` | connect | write | funnel, clicks by channel and forwarded parameter; closes a finished campaign | | `create_campaign` | connect | write | name, landing_url, referral_code, forward_params; returns the link | | `update_campaign` | connect | write | name, landing_url, referral_code, forward_params, status, archived; completed needs confirmation | | `create_contacts` | connect | write | bulk emails; duplicates and invalid skipped | | `launch_campaign` | connect | write | enrolment tasks and invite links | | `enroll_user` | connect | write | single enrolment task | | `get_enrollment_task_status` | connect | read | poll an enrolment task | | `list_codes` | affiliate | read | codes and their performance, or redemption rows | | `create_code` | affiliate | write | admin/owner; org-bound | | `update_code` | affiliate | write | rename/retag/disable; never deletes | Everything above is also on the partner web pages (Affiliate, Campaigns, Campaign detail, Codes) when the modules are enabled — the MCP verbs and the web read the same payloads. --- ## Battery Storage > **Module:** `insight` (always on) | **Role:** Any member | **Licence:** Free+ **Model:** Deterministic charge/discharge cycles with configurable scheduling or optimal dispatch. ## Default Specifications | Parameter | Value | Notes | |-----------|-------|-------| | Capacity | 12.5 kWh | Usable capacity | | Max charge/discharge rate | 5 kW | Symmetric | | Discharge duration | 2.5 hours | At max rate | | Charge duration | 2.75 hours | Longer due to efficiency losses | | Round-trip efficiency | 90% | AC-to-AC | | Min SoC | 10% | Reserve for backup | | Max SoC | 100% | Full charge allowed | | Initial SoC | 50% | Starting state of charge | **Source:** Values represent a median residential battery system in 2024-2025, informed by Tesla Powerwall (13.5 kWh), Enphase IQ (5/10/15 kWh), and BYD HVS (5.1-12.8 kWh). 90% round-trip efficiency is conservative; modern lithium-ion systems achieve 89-95%. ## Flexibility Modes ### Unmanaged (FIXED) Scheduled discharge/charge at fixed times: - `discharge_start`: default `"19:00"` (evening peak) - `charge_start`: default `"12:00"` (midday solar) ### Optimized (OPTIMIZED) Aggregated dispatch using a sliding-window algorithm: 1. Scans the scenario's `base_profile` to find the highest-load window (optimal discharge) 2. Scans for the lowest-load window (optimal charge) 3. Dispatches all batteries in the cohort to maximize peak reduction This mode is scenario-aware — it targets the actual load shape, not a fixed schedule. ## Limitations - Single battery model; does not capture multi-battery or hybrid configurations - Degradation over lifetime is not modeled (efficiency and capacity assumed constant) - Temperature effects on performance are not captured - Does not model partial state-of-charge constraints beyond min/max SoC --- ## Data Sources & Known Limitations > **Module:** `insight` (always on) | **Role:** Any member | **Licence:** Free+ This page consolidates the data provenance and known limitations for all simulation components. Each asset's dedicated page also notes its specific sources; this page serves as the comprehensive reference. --- ### Residential Load Profiles **UK:** - Elexon NHH Settlement Profile Classes (BSCP504) — PC1 (domestic unrestricted) and PC2 (Economy 7) - UK Household Electricity Survey (DECC/BEIS 2010-2011) - CREST Demand Model v2.0 (Loughborough University) - BEIS (now DESNZ) annual domestic consumption statistics **US:** - EIA Residential Energy Consumption Survey (RECS) 2020 - NREL End-Use Load Profiles (EULP) project — hourly and sub-hourly profiles for all US climate zones, calibrated against AMI data - NREL ResStock building stock model - ASHRAE Climate Zones (IECC 2021) — used for climate zone mapping ### Commercial Load Profiles - UK commercial profiles from Elexon NHH settlement classes (PC3-PC8) - Building type annual consumption from CIBSE benchmarks and BEIS non-domestic energy statistics ### Solar Generation - NREL PVWatts model for generation curves and regional irradiance - UK array sizes from MCS (Microgeneration Certification Scheme) certification data - US array sizes from SEIA/Wood Mackenzie residential market data - AU array sizes from CER (Clean Energy Regulator) STC data - UK irradiance from Sheffield Solar / PV_Live - AU irradiance from BOM (Bureau of Meteorology) solar exposure maps ### EV Charging - **Plug-in times and energy distributions:** ev.energy platform telemetry (anonymized aggregate, 2023-2025), validated against UK EVHS data and US DOE EERE residential charging studies. Also referenced: CREST model and industry estimates. - **Charging rates:** ev.energy platform data (charger-reported maximum rates). Market context from UK OZEV and US AFDC data. - **Connection duration:** ev.energy platform data (UK and US residential sessions, 2023-2025) - **Ready-by times:** Commute pattern estimates from DfT National Travel Survey (UK) and NHTS (US) ### Battery Storage - Default specifications informed by Tesla Powerwall (13.5 kWh), Enphase IQ (5/10/15 kWh), and BYD HVS (5.1-12.8 kWh) — representing a median 2024-2025 residential system - 90% round-trip efficiency is conservative; modern lithium-ion achieves 89-95% - Aggregated dispatch algorithm: ev.energy internal research ### Data Centres - PUE benchmarks from Uptime Institute Annual Survey and ASHRAE TC 9.9 - Load factor ranges from IEA Data Centres and Data Transmission Networks report ### Thermostat DR - Reduction magnitudes from Nest/Google DR program data and Pecan Street (2023) - Pre-charge/rebound factors from LBNL/OSTI research and Virtual Peaker - Compliance rates from Utility Dive/Resideo (2024) and ICF - HVAC availability based on UK ADMD and US central AC usage patterns - Industry benchmarks compiled from Ecobee, Nest, Honeywell published data - EPRI and LBNL demand response program evaluation reports ### Hosting Capacity - Public utility Integration Capacity Analysis (ICA) maps — ConEd, National Grid MA, SDG&E, PG&E - Financial deferral assumptions from industry estimates for DER flexibility programs and traditional distribution infrastructure upgrades - See [Hosting Capacity Data & Methodology](../grid/hosting-capacity) for full detail --- ## Known Limitations Each asset page documents its specific limitations. Key cross-cutting limitations: **Simulation engine:** - Single-day simulations don't capture week-level patterns (weekend vs weekday differences) - No grid constraints — simulations show energy flows, not voltage/frequency impacts - 15-minute resolution cannot capture sub-minute transients - All assets share the same fixed time grid; no adaptive time-stepping **Data coverage:** - Load profiles are typical/average — no individual household variability - EV distributions are UK/US-centric — patterns may differ in other markets - Solar uses synthetic seasonal curves, not location-specific irradiance - Public charging profile is synthetic — marked for replacement with platform data - Hosting capacity data reflects utility planning models, not real-time conditions See individual asset pages for detailed limitations: [EV Charging](ev-charging), [V2G](v2g), [Battery](battery), [Solar](solar), [Thermostat](thermostat), [Public Charging](public-charging), [Loads](loads), [Hosting Capacity](../grid/hosting-capacity). --- ## EV Smart Charging (V1G) > **Module:** `insight` (always on) | **Role:** Any member | **Licence:** Free+ **Model:** Monte Carlo simulation — each EV is individually sampled from probability distributions, then charging is scheduled according to the flexibility mode. All distributions are calibrated against ev.energy platform data (anonymized aggregate patterns from managed charging sessions, 2023-2025). --- ## Default Parameters | Parameter | Default | Distribution | |-----------|---------|-------------| | Plug-in probability | 3/7 (~43%) | Per-day probability of plugging in | | Charge rates | 7 kW (70%), 3 kW (20%), 11 kW (10%) | Discrete | | Plug-in time | Evening 19:00 (75%), Morning 07:00 (25%) | Bimodal Gaussian | | Connection duration | Mode ~14 hours | Log-normal | | Energy required | Mean 21 kWh | Normal | | Ready-by | 07:00 (40%), 08:00 (30%), flexible (30%) | Categorical | --- ## Monte Carlo Distributions ### Plug-In Times (Bimodal Gaussian) | Peak | Time | Weight | Std Dev | |------|------|--------|---------| | Evening | 19:00 | 75% | 2 hours | | Morning | 07:00 | 25% | 1 hour | **Source:** ev.energy platform telemetry (UK and US residential sessions). Validated against UK EVHS (Electric Vehicle Homecharge Scheme) data and US DOE EERE residential charging studies. The evening-dominant pattern reflects "come home from work, plug in" behavior. **Limitations:** Residential-only; commercial/fleet charging has different patterns (typically daytime). Weekend patterns differ from weekday but are not separately modeled. Geographic variation exists (e.g., earlier evening peaks in southern latitudes) but is not parameterized. ### Connection Duration (Log-Normal) - Mode: ~14 hours (typical overnight connection) - Maximum: 24 hours (hard cap) - sigma: 0.25 **Source:** ev.energy platform data (UK and US residential sessions, 2023-2025). Log-normal is appropriate because durations have a natural lower bound and right-skewed tail. The long average connection time is key to the managed charging value proposition — it provides significant scheduling flexibility. **Limitations:** Assumes residential, single-vehicle-per-charger pattern. Does not model multi-day connections (e.g., weekend non-use). Commercial/workplace charging typically has shorter, more uniform durations (4-8 hours). ### Energy Required (Normal) - Mean: 21 kWh (~60-70 miles of driving recharged per session) - Std Dev: 15 kWh - Maximum: 100 kWh (hard cap) - Minimum: 0 kWh (clipped) **Source:** ev.energy platform data (session-level energy delivery, 2023-2025). Consistent with average US daily driving distance (~30-40 miles) and typical EV efficiency (3-4 miles/kWh). High sigma reflects wide variation: some sessions are top-ups (5-10 kWh), others are full charges (40-60+ kWh). **Limitations:** Normal distribution can generate negative values (clipped to 0). Does not differentiate by vehicle type (BEV vs PHEV) or battery size. Seasonal variation (cold weather increases consumption) is not modeled. ### Charging Rates (Discrete) | Rate | Probability | Typical Hardware | |------|-------------|-----------------| | 7 kW | 70% | Standard UK home charger, US Level 2 (32A/240V) | | 3 kW | 20% | UK 3-pin plug, older/basic EVSE | | 11 kW | 10% | Three-phase home charger, newer premium installations | **Source:** ev.energy platform data (charger-reported maximum rates, 2023-2025). 7 kW dominance reflects UK single-phase 32A standard and US Level 2 market. **Limitations:** Does not model DC fast charging (50+ kW) — this is a residential-focused simulation. Actual charge rates may be limited by vehicle onboard charger, not just EVSE rating. ### Ready-By Times (Categorical) | Deadline | Probability | Persona | |----------|-------------|---------| | 07:00 | 40% | Early commuter | | 08:00 | 30% | Regular commuter | | Flexible (none) | 30% | No departure deadline | --- ## Flexibility Modes (Smart Charging Levels) | Mode | Level | Load Shaping | Behavior | |------|-------|-------------|----------| | `unmanaged` | L0 | NONE | Charge ASAP after plug-in | | `passive` | L1 | NONE | Pause during DR window, snap-back rebound on resume | | `active` | L2 | DIVERSIFY | Pause during DR, then spread charging across remaining window | | `optimized` | L3 | BALANCE | Place charging in lowest-load intervals against target profile | Key distinction: L1 and L2 both pause during DR. The difference is post-DR: L1 snaps back (creating a rebound spike), L2 diversifies (spreading charging to avoid the spike). ## DR Parameters - `dr_start`, `dr_finish`: DR event window (HH:MM format) - `dr_compliance`: Fraction of fleet that responds (0-1, default 0.8) - `ready_by`: Optional morning departure deadline constraint - `diversify`: Optional override to explicitly control post-DR behavior ## DR Compliance When `prob_compliance` < 1.0, non-compliant EVs ignore the DR window entirely. Compliant EVs use two-pass charging: first fill non-DR intervals, then overflow into DR if needed (energy conservation). BALANCE mode penalizes DR intervals rather than excluding them, so they become fallback slots. ## Energy Conservation Every EV receives its full required charge regardless of flexibility mode. Flexibility only changes WHEN charging occurs, never HOW MUCH. Quantized charging: `intervals = ceil(energy_required / charge_rate x 4)`. --- ## Load Components ## Load Components (Always FIXED) > **Module:** `insight` (always on) | **Role:** Any member | **Licence:** Free+ Load cohorts are always unmanaged — they represent "business as usual" consumption. All load profiles are **deterministic** (no randomness). EV charging is not included in load profiles; it is simulated separately as a flexible asset. --- ### Residential — UK (Elexon NHH Settlement Profile Classes) | Profile | Type | Annual kWh | Daily kWh | Peak Time | |---------|------|-----------|-----------|-----------| | **PC1** | Domestic Unrestricted | 2,900 | ~8 | Evening 18:00-20:00, morning 07:00-08:00 | | **PC2** | Domestic Economy 7 | 4,200 | ~11.5 | Overnight 00:00-07:00 (storage heating) | The default is PC1 (unrestricted domestic tariff). **Profile shape:** - Morning peak: 07:00-09:00 (breakfast, getting ready) - Evening peak: 17:00-21:00 (cooking, entertainment, heating) - Overnight trough: 00:00-06:00 - Seasonal variation: Winter consumption ~40-60% higher than summer **UK Seasonal Multipliers:** Winter 1.35x, Spring 0.95x, Summer 0.70x, Autumn 1.00x. **Source:** Elexon NHH Settlement Profile Classes (BSCP504), BEIS (now DESNZ) annual domestic consumption statistics. Half-hourly settlement data mapped to 15-minute simulation intervals. **Limitations:** Profile classes are statistical averages; individual households vary significantly. Assumes gas heating (typical UK); all-electric homes would have higher/different profiles. Profile Class data is periodically updated by Elexon; values should be refreshed annually. --- ### Residential — US (Climate-Based) | Profile | Regions | Annual kWh | Daily kWh | Peak Driver | |---------|---------|-----------|-----------|-------------| | **us_mixed** | TX, NC, VA, IL | 11,000 | ~30 | Afternoon AC + evening (DEFAULT) | | **us_hot_humid** | FL, LA, Gulf | 14,500 | ~40 | AC dominant, 30% overnight AC | | **us_hot_dry** | AZ, NV | 12,500 | ~34 | Extreme AC peak ~17:30, cool nights | | **us_cold** | NY, MA, MN | 9,000 | ~25 | Morning heating, dual peaks | | **us_mild** | Pacific NW, Coastal CA | 8,000 | ~22 | Flattest profile, minimal AC | **Profile shapes:** - Summer-peaking regions: Afternoon AC load creates sharp 14:00-18:00 peak - Winter-peaking regions: Morning (07:00-09:00) and evening (17:00-20:00) heating peaks - Baseload: ~0.5-1.0 kW continuous (refrigeration, standby, etc.) **US Seasonal Multipliers (vary by climate):** | Profile | Winter | Spring | Summer | Autumn | |---------|--------|--------|--------|--------| | us_hot_humid | 0.85x | 0.90x | **1.40x** | 0.85x | | us_hot_dry | 0.75x | 0.85x | **1.55x** | 0.85x | | us_mixed | 1.15x | 0.85x | 1.20x | 0.80x | | us_cold | **1.35x** | 0.90x | 0.95x | 0.80x | | us_mild | 1.20x | 0.95x | 0.90x | 0.95x | **Source:** EIA Residential Energy Consumption Survey (RECS 2020), NREL End-Use Load Profiles project (hourly, all climate zones). Climate zone mapping follows IECC/ASHRAE conventions. Geo-detection feature maps user location to nearest climate zone for automatic defaults. **Limitations:** Regional averages; individual homes vary widely by size, efficiency, occupancy. Electric heating assumptions affect winter profiles significantly. --- ### Commercial — UK (Elexon PC3-PC8) | PC | Type | Annual kWh | Pattern | |----|------|-----------|---------| | **PC3** | Small Commercial | 15,000 | 9am-5pm plateau | | **PC4** | Commercial Economy 7 | 25,000 | Business hours + overnight heating | | **PC5** | Max Demand 0-20% LF | 8,000 | Very peaky, intermittent | | **PC6** | Max Demand 20-30% LF | 20,000 | Extended hours | | **PC7** | Max Demand 30-40% LF | 40,000 | Near-continuous operation | | **PC8** | Max Demand >40% LF | 80,000 | 24/7 flat (supermarkets, industrial) | **Building presets:** small_office (PC3, 15k), retail_shop (PC3, 12k), medium_office (PC6, 80k), large_office (PC7, 250k), restaurant (PC6, 35k), warehouse (PC7, 30k), light_industrial (PC7, 100k), supermarket (PC8, 500k), hotel (PC8, 200k), school (PC5, 50k). **Source:** UK commercial profiles from Elexon NHH settlement classes (PC3-PC8). Building type annual consumption from CIBSE benchmarks and BEIS non-domestic energy statistics. --- ### Data Centres | Type | PUE | Load Factor | Pattern | |------|-----|-------------|---------| | **Hyperscale** | 1.15 | 85-95% | Flat 24/7 (AI/cloud workloads) | | **Enterprise** | 1.40 | 60-90% | +10% during business hours | | **Colocation** | 1.35 | 50-85% | +15% during business hours | Cooling overhead = (PUE - 1.0) fraction, with seasonal variation: Winter 0.6x, Spring 0.85x, Summer 1.2x, Autumn 0.85x. **Source:** PUE benchmarks from Uptime Institute Annual Survey and ASHRAE TC 9.9. Load factor ranges from IEA Data Centres and Data Transmission Networks report. --- ### Block Loads Constant power for a defined window. Parameters: `start_time` (HH:MM), `duration_hours` (max 24), `size_kw`. Use for modeling any fixed-schedule industrial or infrastructure load that doesn't fit the predefined categories. --- ## Simulation Engine Overview ## Simulation Methodology > **Module:** `insight` (always on) | **Role:** Any member | **Licence:** Free+ **Engine:** Monte Carlo simulation with 15-minute intervals (96 per day). ### Time Resolution | Constant | Value | Description | |----------|-------|-------------| | `INTERVALS_PER_HOUR` | 4 | 15-minute intervals | | `INTERVALS_PER_DAY` | 96 | 24 hours x 4 intervals | | `INTERVAL_DURATION_HOURS` | 0.25 | 15 minutes in hours | | `INTERVAL_DURATION_MINUTES` | 15 | 15 minutes | The 15-minute resolution aligns with: - Australian NEM (National Electricity Market) settlement periods - UK half-hourly settlement (Elexon) — maps cleanly to 2x 15-minute intervals - Standard smart meter data granularity in UK and US markets - Industry standard for energy trading intervals Times are specified as `HH:MM` strings and converted to interval indices (e.g. `"06:00"` → interval 24, `"14:30"` → interval 58). **Limitation:** 15-minute resolution cannot capture sub-minute transients (inrush currents, frequency response) or appliance-level events (kettle spikes, oven cycling). Grid stability studies requiring 1-second or faster resolution are out of scope. ### Approach - Each EV is individually sampled from probability distributions (plug-in time, connection duration, energy required, charge rate, ready-by deadline) - Quantized charging: energy = ceil(energy_required / charge_rate x 4) intervals - Every EV receives its full required charge — flexibility only changes WHEN, never HOW MUCH - Load profiles (households, commercial, data centres) are **deterministic** — no randomness. Only EV charging and thermostat DR use stochastic simulation. ### N+2 Day Simulation The engine internally simulates **N+2 days** and returns the middle N days: | Day | Purpose | |-----|---------| | Day 0 | Cold-start warm-up — allows EVs plugging in on day 0 to complete charging | | Days 1 to N | **Output days** — these are returned to the user | | Day N+1 | Cleanup/warm-down — allows EVs from day N to shift charge forward without losing energy at the boundary | When a display window offset is used (e.g. noon-to-noon), the engine extends to **N+3 internal days** to ensure complete coverage. ### Distributions Summary | Parameter | Distribution | Default Parameters | |-----------|-------------|-------------------| | Plug-in time | Bimodal Gaussian | Evening 19:00 (75%, sigma=2h), Morning 07:00 (25%, sigma=1h) | | Connection duration | Log-normal | Mode ~14h, sigma=0.25, max 24h | | Energy required | Normal | mu=21 kWh, sigma=15 kWh, max 100 kWh | | Charging rate | Discrete | 7 kW (70%), 3 kW (20%), 11 kW (10%) | | Ready-by time | Categorical | 07:00 (40%), 08:00 (30%), flexible (30%) | See the [EV Smart Charging](ev-charging) page for full distribution detail, sources, and limitations. ### Unified Scenario Model Each scenario contains both load cohorts and flexible asset cohorts. The simulation produces: - `base_profile`: all assets simulated at FIXED (unmanaged) behavior — the "do nothing" baseline - `flexed_profile`: assets simulated at their assigned flexibility_mode — what the grid actually sees - Component traces: individual contribution of each cohort ### Flexibility Modes (per-cohort) | FlexibilityMode | Display Name | Tool Aliases | Behavior | |-----------------|-------------|--------------|----------| | FIXED | Unmanaged | "unmanaged", "none", "baseline" | Natural behavior, no control | | MANAGED | Managed | "passive", "active", "dr", "curtail", "diversify" | Responds to DR signals or curtailment windows | | OPTIMIZED | Optimized | "optimized", "balance", "vpp", "aggregated" | Full load balancing against base_profile | For EV-specific load shaping modes (NONE/DIVERSIFY/BALANCE) and smart charging levels (L0-L3), see [EV Smart Charging](ev-charging). ### Performance Simulation scales linearly with vehicle count: - NONE mode: ~0.2s for 10,000 vehicles - BALANCE mode: ~0.4s for 10,000 vehicles The random seed controls reproducibility, but different seeds produce statistically similar results for large fleets (>100 vehicles). ### Sign Convention - Positive = consumption/import from grid (includes pre-charge/rebound for thermostat DR) - Negative = generation/export to grid or load reduction (includes thermostat DR reduction phase) ### Limitations - Single-day simulations do not capture week-level patterns (weekend vs weekday differences) - No grid constraints modeled — simulations show energy flows, not voltage/frequency impacts - Fixed 15-minute resolution — all assets share the same time grid with no adaptive time-stepping - The simulation models energy scheduling, not power quality or phase balance --- ## Public Charging > **Module:** `insight` (always on) | **Role:** Any member | **Licence:** Free+ **Model:** Deterministic load profile based on utilization patterns. ## Default Parameters | Parameter | Default | Notes | |-----------|---------|-------| | Charger power | 50 kW | DC fast chargers | | Utilization | 20% | Average daily utilization | | Load shape | Dual peak | Morning (8 AM commuters) + afternoon (4 PM pre-commute) | ## Flexibility Modes - `unmanaged` (FIXED): Natural load pattern - `passive` (MANAGED): Curtailable during specified window (`curtail_start`, `curtail_end`, `curtail_percent` 0-100) ## Limitations - Load profile is synthetic — marked for replacement with real ev.energy platform data - Does not model queue dynamics or individual session variation - Does not model variable charger power (50-350 kW range) --- ## Solar PV > **Module:** `insight` (always on) | **Role:** Any member | **Licence:** Free+ **Model:** Deterministic sinusoidal generation curve based on solar angle, with stochastic weather noise and per-house variation. ## Array Size Presets | Region | Default (Medium) | Small | Large | Source | |--------|-----------------|-------|-------|--------| | **UK** | 3.5 kW | 2 kW | 5.5 kW | Code default; MCS data shows 4 kWp typical UK installation | | **US** | 7 kW | 4 kW | 11 kW | SEIA/Wood Mackenzie residential market data | | **AU** | 6.6 kWp | — | — | CER (Clean Energy Regulator) STC data; inverter-limited sweet spot | Note: The UK code default (3.5 kW) is slightly below the MCS market average (4 kWp) to represent a conservative installed base including older systems. ## Seasonal Capacity Factors Internal simulation capacity factors (fraction of peak output on a typical day): | Season | Factor | Description | |--------|--------|-------------| | Summer | 85% | Long days, high sun angle, clear skies | | Spring | 65% | Moderate days, variable weather | | Autumn | 55% | Shorter days, more cloud cover | | Winter | 30% | Short days, low sun angle | For reference, real-world annual capacity factors by region: | Region | Summer | Winter | Annual Average | Source | |--------|--------|--------|----------------|--------| | UK | 15-18% | 5-8% | 10-12% | Sheffield Solar / PV_Live | | US Southwest | 25-30% | 15-20% | 20-25% | NREL PVWatts | | US Northeast | 18-22% | 8-12% | 14-17% | NREL PVWatts | | Australia | 12-16% (winter) | 22-28% (summer) | 16-20% | BOM solar exposure maps | ## Generation Profile - Sinusoidal curve based on solar angle for the season - Weather noise: Normal distribution, sigma=15% - Per-house variation: sigma=20% - Output is **negative** (generation/export reduces net consumption) ## Flexibility Modes - `unmanaged` (FIXED): Full output, no curtailment - `passive` (MANAGED): Curtailable — set `curtail_start`, `curtail_end`, `curtail_percent` (0-100) ## Limitations - Array sizes are rapidly increasing; presets should be reviewed annually - Actual generation depends on orientation, tilt, shading, and local irradiance (not modeled) - Does not model battery-paired solar differently from standalone - Capacity factors are location-specific; defaults are regional averages - Does not model degradation, soiling, or inverter clipping --- ## Thermostat DR Behavior Model > **Module:** `insight` (always on) | **Role:** Any member | **Licence:** Free+ Thermostat DR treats the building's thermal mass as a battery. The output is a **delta profile** (change vs normal HVAC operation), not an absolute load. **Source:** EPRI demand response studies, ev.energy engineering calibration against utility DR event data, Nest/Google and Ecobee published thermostat DR performance data. ### Three-Phase Model Each DR event runs three consecutive 1-hour phases (4 intervals each): | Phase | Power Delta (default) | Duration Range | Timing | Purpose | |-------|----------------------|---------------|--------|---------| | **Pre-charge** | +0.7 kW/home | 0.5-2 hours | Before dr_start | Over-condition building (pre-heat or pre-cool) | | **Reduction** | -1.0 kW/home | 1-4 hours | dr_start onwards | Curtail HVAC; thermal mass maintains comfort | | **Rebound** | +0.5 kW/home | 0.5-3 hours | After reduction | HVAC restores setpoint (snapback) | Energy roughly balances: positive energy (pre-charge + rebound) ≈ 1.2x negative energy. ~80% thermal round-trip efficiency. **Pre-conditioning detail:** Setpoint offset of -2°F / -1°C (range: 1-4°F), increasing load 20-40% above baseline depending on HVAC capacity. **Curtailment detail:** Setpoint offset of +4°F / +2°C (range: 2-6°F), reducing load 50-80% below baseline (0.5-1.5 kW per household). **Recovery detail:** Snapback ratio of 1.3x curtailed load (range: 1.1-1.5x), exponential decay returning to baseline over the recovery period. ### HVAC Types | Type | Reduction per Home | Best Season | Region | |------|-------------------|-------------|--------| | **heat_pump** | 1.0 kW | Winter | UK (default) | | **ac** | 0.9 kW | Summer | US | | **resistance** | 1.5 kW | Winter | UK | ### Seasonal HVAC Availability | Season | Heat Pump | AC | Resistance | |--------|-----------|-----|------------| | Winter | 100% | 0% | 100% | | Spring | 50% | 50% | 30% | | Summer | 20% | 100% | 0% | | Autumn | 70% | 30% | 60% | Effective homes = count x prob_compliance x seasonal_availability[hvac_type][season]. ### Default Parameters | Parameter | Default | Range | Notes | |-----------|---------|-------|-------| | `reduction_kw_per_home` | 1.0 kW | 0.5-1.5 | Based on Nest/Pecan Street data | | `precharge_factor` | 0.7 | 0.3-1.0 | Pre-charge as fraction of reduction | | `rebound_factor` | 0.5 | 0.3-0.8 | Rebound as fraction of reduction | | `prob_compliance` | 0.3 | 0.0-1.0 | **0.3 for recurring, 0.7 for single event** | | `hvac_type` | heat_pump | heat_pump/ac/resistance | Determines reduction kW and seasonal availability | | `season` | winter | winter/spring/summer/autumn | Affects HVAC availability | | `dr_start` | 17:00 | HH:MM | Start of reduction phase (unmanaged mode only) | ### Industry Compliance Benchmarks | Metric | Benchmark | Source | |--------|-----------|--------| | Event participation rate | 85-90% | Enrolled customers who remain opted-in during event | | Customer opt-out rate | 10-15% per event | Customers who override setpoint during event | | Average curtailment | 0.8-1.2 kW per home | AC cycling programs in cooling season | | Snapback peak | 1.2-1.5x curtailed load | Post-event recovery demand | | Event fatigue factor | -2% per event per month | Declining participation with frequent events | **Source:** Compiled from published utility DR program results, Ecobee/Nest/Honeywell published thermostat DR performance data, EPRI and LBNL demand response program evaluation reports. ### Compliance Guidance (`prob_compliance`) The fraction of enrolled homes that actually deliver a load reduction. Captures: enrollment x occupancy x HVAC availability x override rate x technical success. | Scenario | Recommended | Rationale | |----------|-------------|-----------| | **Default (recurring daily)** | **0.3** | Conservative for sustained operation | | Single well-designed event | 0.7 | Real-world best case (Nest/Ecobee data) | | Occasional (10-15/season) | 0.5-0.6 | Standard utility program | | Daily for 30+ days | 0.3-0.4 | Significant occupant fatigue | | Contractual/commercial | 0.8-0.9 | Financial penalties for non-compliance | **Key insight**: 0.7 is a single-event best case. Real programs run ~12 events/season, not daily. The default 0.3 is honest about what repeating=True actually delivers. ### Optimized Mode In optimized mode, each home's 3-hour unit profile is slid across all 96 daily positions. The algorithm picks the placement that minimizes variance of (target_load + unit). Large cohorts (>10,000 homes) batch to cap at 10,000 iterations. Homes naturally stagger to flatten peaks. ### Limitations - Building thermal mass varies enormously; single model cannot capture all building types - Customer behavior (opening windows, manual override) is not modeled - Multi-zone HVAC systems have more complex response patterns - Fixed phase durations (each phase is exactly 1 hour); real buildings have variable thermal time constants - Newer smart thermostat programs tend to outperform older direct load control - Climate and season heavily influence curtailment magnitude --- ## V2G (Vehicle-to-Grid) > **Module:** `insight` (always on) | **Role:** Any member | **Licence:** Free+ **Model:** Same Monte Carlo charging model as V1G, plus bidirectional export capability during DR events. ## Additional Parameters | Parameter | Default | Notes | |-----------|---------|-------| | Export rate | 5 kW | Rate of energy export during DR events | | Export compliance | 0.8 | Fraction of fleet that exports | | Export start/finish | HH:MM | Export window | During DR events, compliant V2G vehicles **export** energy at the configured rate. The exported energy is reimported later when charging resumes, ensuring the vehicle still receives its required energy. ## Flexibility Modes Same as V1G: `unmanaged`, `passive`, `active`, `optimized` — with the addition of export behavior during DR windows. See [EV Smart Charging](ev-charging) for full distribution detail. ## Limitations - V2X revenue projections assume battery degradation costs are manageable - Export rate is fixed (does not model variable export based on grid signal) - Does not model bidirectional charger hardware constraints --- ## Integrations > **Module:** None (core platform) | **Role:** Admin (workspace integrations), Any member (personal integrations) | **Licence:** Free+ Integrations connect external services so agents can access them as tools. There are two scopes: - **Workspace integrations** — connected by an admin, shared by all agents in the workspace - **Personal integrations** — connected by individual users in their profile, private to them ## Workspace Integrations Connected via **Settings → Integrations** by a workspace admin or owner. | Service | What agents get | Credential type | |---------|----------------|-----------------| | **Slack** | Send notifications to channels and DMs | Bot token (auto-connected) | | **Snowflake** | Query your Snowflake data via a Cortex Agents MCP server | Programmatic access token | Once connected, workspace agents declare which integrations they need via `mcp_connections`: ``` create_agent( name="Weekly Platform Update", mcp_connections=["snowflake"], triggers=[{type: "cron", schedule: "0 9 * * 1", delivery: ["slack_dm"]}] ) ``` The integration is resolved at dispatch time — agents reference the type name, never the credential directly. ## Personal Integrations Connected via **Profile → Integrations** by individual users. Personal integrations are private — not visible to workspace admins or other members. | Service | What it enables | How to connect | |---------|----------------|----------------| | **ev.energy** | Linked when you sign in via the ev.energy SSO option — gives Eve read access to your fleet account, charge sessions, and driver analytics | Sign in with **ev.energy** on the login page; auto-linked, no separate setup | | **Holistics** | Query the datasets your Holistics account can see; powers the "Known charging sites" map layer | API key | Personal integrations take priority over workspace integrations of the same type: Eve uses your own credential rather than any workspace-level one. ### Login-time health check Each time you sign in, the platform validates every personal integration in the background and updates its connection status. If something has expired or been revoked you'll land on a brief confirmation page (`/auth/connected`) with a **Reconnect** button next to the affected integration. When all integrations are healthy the page is skipped and you continue straight to the app. ### ev.energy Connecting ev.energy means signing in with the **ev.energy** option on the login page. Once you've done that, Eve sees your link to the ev.energy fleet platform and can answer questions about your fleet, charging sessions, and driver analytics. There's no separate "Connect" button — the link is the act of signing in. To unlink, sign out and pick a different provider on your next sign-in. ### Holistics Connect Holistics to give Eve and the map access to the datasets your Holistics account can query. This is **per-user only** — there is no shared workspace Holistics credential because every Holistics user has their own row-level filters, and a shared key would expose data the connecting user is entitled to to every other workspace member. What it powers: - **Map layer "Known charging sites"** — dots on the grid map showing every location where one or more drivers in your Holistics scope has at least one recorded charging session. Visible at city zoom and above. - **Eve queries against Holistics datasets** — Eve can run queries against the datasets your Holistics account can see. Dataset discovery is automatic. The first time you connect, the platform walks the Holistics catalog to find the home, charging, and EVSE datasets by name and field-name patterns. The result is cached for 24 hours, then re-discovered. If your dataset names or field names change, the next discovery picks up the new shape. If automatic discovery picks the wrong dataset, you can pin the correct one (Profile → Integrations → Holistics → Pin dataset). ## How Agents Use Integrations Agents with `mcp_connections` automatically receive the right credentials at run time: 1. If the requesting user has a personal integration of that type → use it 2. Otherwise, if the workspace has a shared integration → use it 3. If neither → the connection is omitted; the agent runs without it This means a workspace-level credential can act as a fallback while individual users override it with their own. ## Managing Connections | Action | Where | |--------|-------| | Connect/disconnect workspace integration | Settings → Integrations | | Test a workspace integration | Settings → Integrations → Test | | Connect personal Holistics | Profile → Integrations → Connect | | Revoke personal integration | Profile → Integrations → Disconnect | --- ## Module Licensing > **Module:** None (core platform) | **Role:** Admin (configure modules), Platform Admin (deploy modules) | **Licence:** Varies by module Modules are commercial feature gates that control which tools, agents, and capabilities are available to a workspace. Modules use colon notation for sub-modules (e.g., `sync:network`). ## Module Hierarchy | Module | Domain | Sub-Modules | |--------|--------|-------------| | `insight` | Understand | Base platform (always enabled) | | `insight:policy` | Understand | Policy intelligence agent team | | `sync` | Control | All sync sub-modules | | `sync:network` | Control | Network management | | `sync:load` | Control | Load management | | `sync:market` | Control | Market participation | | `sync:fleet` | Control | Fleet management | | `operations` | Manage | All operations sub-modules | | `operations:agents` | Manage | Agent CRUD, skill management, team management | | `operations:communications` | Manage | Campaign analytics (performance summaries, per-campaign metrics, CSV export) | | `operations:participants` | Manage | Participant CRM — roster search, growth KPIs, enrolment velocity, exports, QR posters | | `operations:hardware` | Manage | Hardware management — device estate reads, charger connectivity & maintenance status, OEM stats, support tickets, maintenance-mode writes; org-scoped warehouse figures where enabled | | `programs:connect` | Manage | Partner campaigns — tracked recruitment links, contacts, clicks, campaign analytics (optional A2A enrolment handoff) | | `programs:affiliate` | Manage | Partner codes — referral/promo codes, redemptions + qualified counts (no amounts) | | `operations:energy` | Manage | Energy operations | | `operations:financials` | Manage | Financial operations | | `platform:holistics` | Connect | Personal Holistics integration + map layers it powers | | `platform:slack` | Connect | Workspace Slack integration for notifications and DMs | | `platform:snowflake` | Connect | Personal Snowflake integration | Enabling a top-level module (e.g., `"sync"`) grants all its sub-modules. Modules in the `platform:` family are **enablement gates** — they make an integration *available* to connect, but the user still has to connect it themselves (Profile → Integrations). Default tiers include all `platform:` modules so any member can connect personal integrations without needing a licence change. ## What Each Module Unlocks ### `insight` (Always On) Every workspace gets this — it's the base platform: - Simulation tools (create scenarios, add assets, simulate, analyze) - Chart and visualization tools - Hosting capacity queries - Context tools - Platform documentation (`get_platform_doc`) - Knowledge vaults (via librarian dispatch tools) ### `insight:policy` Policy Intelligence agent team: - Policy Explorer (regulatory scanning) - Policy Librarian (knowledge vault management) - Policy Navigator (watchlist, deadline tracking) - Policy Analyst (digests, briefings) - Policy Steward (coverage monitoring) ### `operations:agents` Agent and skill management: - Create, update, delete custom agents - Create and manage agent teams - Create, update, delete skills - Agent team deployment ### `programs:connect` Partner campaigns — recruit drivers with tracked links and measure the result: - Create and manage campaigns (a free-text **name** + optional **`landing_url`** + optional **`referral_code`**; there is no programme catalogue) - Bulk-import driver contacts - Mint a campaign's tracked `/connect/j` share link (and per-contact links) - Manage status (active / paused / completed — completed is terminal) - Portfolio **analytics**: clicks (ours, real time) and redemptions + qualified (core's per-code counts) over time **Clicks** are counted by us the moment a link is followed. **Redemptions** and **qualified** come from core's per-code performance and read **TBC** until the workspace is linked to an ev.energy organisation. No monetary amounts are shown. A campaign can also **launch A2A enrolment tasks** (`launch_campaign` / `enroll_user`) — a per-driver invite URL over the agent-to-agent protocol, an alternative to sharing links. A task **completes when the invited driver accepts the invite** on Eve Connect; what they do on Connect afterwards is theirs. The hand-off is the invite and nothing else: no driver credential or account data reaches the recruiting workspace. Campaign stats count accepted invites as `invites_accepted`; there is no `enrolled` count. Full verb reference: [Partner campaign & affiliate verbs](/programs/verbs). ### `programs:affiliate` Partner codes — the organisation's referral/promo codes and how each performs: - List every code (active and disabled) with its **redemptions** and **qualified** counts, share link and QR (no amounts) - List individual redemptions (one row per redemption, anonymised) - Mint a code (admin/owner only) - Rename, retag, or disable a code (admin/owner only — codes are never deleted) All code reads and writes require the workspace to be **linked to an ev.energy organisation**; until then the codes screen and the redemptions/qualified figures read TBC. Reads are open to any member; writes are admin/owner only. Full verb reference: [Partner campaign & affiliate verbs](/programs/verbs). ### `operations:participants` Participant CRM for programs, fleets, and sites (terminology adapts by vertical — drivers / residents / participants): - Look up an enrolled participant by their exact email address (cycle 1 supports exact-email match only — the upstream system has no name or account-number search) - Growth KPIs (total acquired, total activated, activation rate) and monthly enrolment velocity — always computed server-side. Where the underlying source cannot report a figure, the dashboard shows a dash rather than a zero: an unknown and a real zero are different answers, and only one of them is a measurement - Roster export as a CSV download link - Enrolment QR posters Privacy by design: Eve only ever handles an opaque participant reference plus a minimised display label — never names, contact details, addresses, or account numbers. Full participant records are viewable only in the Participants pages of the operator console, and exports are delivered as secure download links rather than through chat. ### `operations:hardware` Hardware management for an organisation's device estate — vehicles, chargers, solar, and home batteries: - Device estate reads: list devices by type with a summary, look up specific devices of any type (up to 50 at once, by the id, serial number, OCPP id or VIN shown on screen), filter the list by status and brand as the results page does, and see OEM / manufacturer stats. The summary and the OEM stats cover every device type or the one the selected tab shows - Work queues: find the devices waiting to be set up, whose connection lapsed, that stopped reporting, or that report a fault. The summary gives each queue's exact size, counts what needs attention separately from the setup backlog, and says when a queue can't be measured for a device type yet - Charger connectivity and maintenance status, and support tickets (list, raise, re-prioritise, close) - Maintenance-mode writes: put a charger into or out of maintenance from the same conversation, with a confirmation step before anything is written. Maintenance mode pauses the charger in ev.energy's operator tools only; nothing changes at the charger, and drivers can still charge - Every read and write is tenancy-scoped server-side to the workspace's own organisation — the caller never supplies an organisation id **Warehouse figures (enabled per organisation).** For organisations on the warehouse tier, Eve can also answer estate counts, vehicle connectivity, and charger session quality from the data warehouse. These are **aggregates only** — never a device list or a per-person figure — and are switched on one organisation at a time after an internal data-protection review. This is not a plan limit and there is nothing to upgrade. ### `platform:*` (Integration Enablement) The `platform:` family unlocks the *option* to connect a third-party integration. They are licence-free by default — every workspace tier includes them — so any member can connect their own credentials in **Profile → Integrations** without an admin or licence change. | Module | Unlocks | |--------|---------| | `platform:holistics` | Personal Holistics API key. Enables the "Known charging sites" map layer and Eve queries against your Holistics datasets. | | `platform:slack` | Workspace Slack notifications (auto-connected via OAuth). | | `platform:snowflake` | Personal Snowflake integration for Eve queries. | Note: enabling the module makes the integration *connectable*; the user still has to complete the connection step. A licensed-but-not-connected integration is a no-op until credentials are provided. ## How Modules Affect Tool Visibility When Eve or an MCP client connects, the tool list is dynamically filtered: 1. Base tools from always-on modules (`insight`) are always included 2. Tools from enabled modules are added 3. Dispatch tools from registered agents are included (with four access gates: module, workspace, user visibility, conversation scope) 4. Locked modules show upsell hints (e.g., "Policy Intelligence is available on Pro plans") ## Checking Your Modules Ask Eve: "What modules are enabled for my workspace?" — Eve uses `get_current_context` to show your workspace's enabled modules and available tools. --- ## Workspace Management > **Module:** None (core platform) | **Role:** Member (view), Admin (manage members/integrations), Owner (billing/deletion) | **Licence:** Free+ A workspace is the purchasing and licence boundary on the platform. Each workspace has members, a licence tier, enabled modules, and configured integrations. ## Roles | Role | Capabilities | |------|-------------| | **Owner** | Full control — billing, licence changes, workspace deletion | | **Admin** | Manage members, integrations, module configuration | | **Member** | Use platform features, create agents, run simulations | ## Licence Tiers | Tier | Seats | Modules | Chats/mo | Reports/mo | |------|-------|---------|----------|------------| | Free | 1 | Insight | 50 | 1 | | Starter | 5 | Insight | 500 | 10 | | Pro | 10 | All | 2,500 | 50 | | Enterprise | Custom | Custom | Unlimited | Unlimited | ## Settings Workspace admins can manage: - **Members**: Invite, remove, change roles (seat limits enforced by licence) - **Integrations**: Slack, Snowflake (workspace-shared); Holistics (per-user, private) — see [Integrations](integrations.md) - **Policy Configuration**: Jurisdictions to monitor, digest recipients (requires `insight:policy` module) - **Usage Dashboard**: Chat and report quota consumption ## Quota Enforcement | Usage Level | Behavior | |-------------|----------| | 0-79% | Normal operation | | 80-99% | Warning banner displayed | | 100-119% | Degraded — rate-limited responses | | 120%+ | Read-only mode | Quotas reset monthly. Usage is tracked per workspace across all members. ## Programmatic access AI clients connect to the Workspace MCP with OAuth, signed in as a member. Workspace API keys have been removed. See [MCP Server](../mcp/overview.md).