eve 0.34.0 → 0.36.0

package/docs/concepts/context-control.md

@@ -1,92 +1,68 @@
 ---
 title: "Context Control"
-description: "Control what an eve agent's model sees and when, across instructions, skills, the workspace, and subagents."
+description: "Choose what an eve agent's model sees and when, across instructions, skills, tools, the workspace, and subagents."
 ---
 
-eve gives you a few levers for controlling what the model sees and when. `instructions.md` (or `instructions.ts`) is always on, `skills/` are available but loaded on demand, and the workspace and sandbox are visible through tools rather than pasted into the prompt.
+Control context by putting information in the narrowest surface that needs it. Keep permanent rules in instructions, load optional procedures as skills, let the model inspect runtime files through sandbox tools, and delegate specialist work to a subagent.
 
-## Base identity with `instructions.md`
-
-Use `instructions.md` for the core contract of the agent.
-
-```md
-You are a careful support assistant. Be concise, verify facts before replying, and explain when you
-used a tool.
-```
-
-Keep this file focused on stable behavior that should apply on every turn.
+## Recommended context layout
 
-## Compose instructions in TypeScript with `instructions.ts`
+| Need                                                 | Use                                                    | What the model sees                                                              |
+| ---------------------------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------- |
+| Permanent identity, rules, or constraints            | System-role [instructions](../instructions)            | System context on every model call                                               |
+| Durable application or retrieved context             | User-role [instructions](../instructions)              | A message added to conversation history at its lifecycle boundary                |
+| A procedure needed only for some tasks               | A [skill](../skills)                                   | Its description until the model loads the full skill                             |
+| A typed action or external operation                 | A [tool](../tools) or [connection](../connections)     | The callable schema and the result of each call                                  |
+| Files or command execution                           | The [sandbox workspace](../sandbox)                    | A workspace hint, then files and command output the model requests through tools |
+| A specialist with a separate prompt and capabilities | A [subagent](../subagents)                             | Only the subagent's final result in the parent context                           |
+| Instructions or capabilities that vary by caller     | A [dynamic capability](../guides/dynamic-capabilities) | The values resolved for the active session                                       |
 
-To build the instructions prompt from typed helpers, lib code, or environment-derived values, author it as a module instead of markdown.
+## Base identity with `instructions.md`
 
-```ts title="agent/instructions.ts"
-import { defineInstructions } from "eve/instructions";
-import { buildInstructionsPrompt } from "./lib/prompts";
+Use system-role instructions for stable behavior that should apply throughout a session, such as the agent's role, tone, and standing constraints. Markdown is the default. Keep instructions short enough to justify including them on every model call.
 
-export default defineInstructions({
-  markdown: buildInstructionsPrompt(),
-});
-```
+### Compose instructions in TypeScript with `instructions.ts`
 
-Module-backed instructions run once at build time. eve captures the resulting markdown into the compiled manifest, so the runtime serves the same prompt every session without re-running the module.
+Use `instructions.ts` when you need typed helpers, build-time composition, or a user-role message. User-role instructions become ordinary durable history rather than system context. See [Instructions](../instructions) for both formats, directory composition, and runtime resolution.
 
 ## Load procedures on demand with `skills/`
 
-Skills stay out of the always-on prompt by default, which keeps rich procedures available without bloating every turn. eve advertises the available skills and adds a framework-owned `load_skill` tool. When the request clearly matches a skill description, or the user names a skill explicitly, the model activates that skill, and eve appends the skill's markdown to the active instructions for later turn work.
+Use skills for optional procedures that would otherwise make the always-on prompt unnecessarily large. eve advertises each skill's description and loads the full instructions only when the model calls `load_skill`.
 
 ### Flat skill
 
-```md title="agent/skills/get-weather.md"
-Use the weather tool before answering forecast or temperature questions.
-```
+Use a markdown file for a self-contained procedure.
 
 ### Packaged skill
 
-```md title="agent/skills/research/SKILL.md"
----
-description: Research unfamiliar topics before answering with confidence.
----
-
-When the task is novel or ambiguous, gather evidence first, then answer with the key facts and the
-remaining uncertainty.
-```
-
-Packaged skills are useful when you also want sibling files such as `references/`, `assets/`, or `scripts/` under the same skill directory. Those files are available under the runtime skill root, normally `$HOME/.agents/skills/<skill>/`. Relative references inside a `SKILL.md` resolve from that specific skill directory, so `references/checklist.md` means `$HOME/.agents/skills/<skill>/references/checklist.md` unless eve has fallen back to `/workspace/skills/<skill>/`.
-
-See [Skills](../skills) for the full authoring model and install notes.
+Use a directory with `SKILL.md` when the procedure also needs references, assets, or scripts. See [Skills](../skills) for both formats, installation, runtime files, and dynamic skills.
 
 ## Put runtime files in the workspace, not the prompt
 
-eve does not inline the entire authored surface into the prompt. Instead, it gives the model a shallow workspace hint, a separate skill-root hint, and runtime tools to inspect deeper when needed. Skill package files are outside `/workspace` in the normal case, and the model inspects them with the shared `bash` tool, which keeps prompts smaller and makes file and command work explicit.
+Do not paste a file tree or large working dataset into the prompt. Seed files into the sandbox workspace and let the model inspect them through `bash`, `read_file`, `glob`, and the other sandbox-backed tools. Skill package files use a separate runtime skill directory.
 
-See [Sandbox](../sandbox) for the workspace and sandbox model.
+See [Sandbox](../sandbox) for workspace seeding, runtime access, backends, and lifecycle behavior.
 
 ## Delegate to a specialist with a subagent
 
-If a task deserves its own prompt and tool surface, use a local subagent instead of overloading the root agent. Subagents are a context-control lever too. They get their own `instructions.md`, tools, and sandbox, and they run inside their own delegated context instead of extending the root agent inline.
+Use a subagent when work needs its own instructions, tools, skills, state, or sandbox. The child runs in a separate context instead of adding its working history to the parent. The parent receives the result of the delegation.
 
-See [Subagents](../subagents).
+See [Subagents](../subagents) for the distinction between root-agent copies and declared specialists, including their isolation boundaries.
 
 ## Dynamic context with `defineDynamic`
 
-The levers above are static, authored once and the same on every session. When the right context depends on who is calling (their team, tenant, plan, or feature flags), resolve it at runtime instead. `defineDynamic` in `agent/instructions/` returns the per-session system prompt, and `defineDynamic` in `agent/skills/` returns the set of skills a caller can load. Both read `ctx.session.auth` or channel metadata, so a caller on the billing team gets the billing instructions and playbook while no one else sees them. See [Dynamic capabilities](../guides/dynamic-capabilities) for the resolver API and when each event fires.
+Use `defineDynamic` when instructions, skills, tools, subagents, or the model depend on the active principal, tenant, channel, or feature state. Dynamic resolvers can read session auth and channel metadata before returning the capabilities available to that session.
 
-## Recommended context layout
+See [Dynamic capabilities](../guides/dynamic-capabilities) for the resolver API, supported slots, and execution order.
 
-Pick the lever by what the context is for:
+## Compaction and clear
 
-- `instructions.md` for the agent's permanent identity. Keep it short and stable.
-- `instructions.ts` when you need to compose the prompt from typed helpers at build time.
-- `skills/` for optional procedures that should load only when needed. Move long procedures here instead of into the always-on prompt.
-- `tools/` to expose typed integrations.
-- a subagent when the task needs a different specialist surface; use one only for real specialization boundaries.
-- the workspace or sandbox when the model should inspect files or run commands instead of relying on pasted instructions.
+User-role instructions follow the normal history lifecycle. Compaction can summarize them, and clear removes them without rerunning their static definitions or dynamic resolvers. System-role instructions remain outside history and continue to apply after either operation.
 
 ## What to read next
 
-- [Tools](../tools): expose typed integrations the model can call.
-- [Skills](../skills): the full authoring model for on-demand procedures.
-- [Subagents](../subagents): delegate to a specialist with its own prompt and tools.
-- [Dynamic capabilities](../guides/dynamic-capabilities): resolve per-session instructions and skills with `defineDynamic`.
-- [Hooks](../guides/hooks): run code on session events to update the channel state that dynamic resolvers read.
+- [Instructions](../instructions): author the always-on system prompt.
+- [Skills](../skills): provide procedures that load on demand.
+- [Sandbox](../sandbox): give the model files and command execution.
+- [Subagents](../subagents): isolate specialist work.
+- [Dynamic capabilities](../guides/dynamic-capabilities): vary context and capabilities by session.

package/docs/concepts/default-harness.md

@@ -57,7 +57,7 @@ The model-facing file tools accept absolute paths and paths beginning with `$HOM
 
 Notes:
 
-- **`agent`** is available only in the root session. Its child uses the root's instructions, tools, connections, and sandbox, but starts with fresh conversation history and fresh [state](../guides/state). The child receives neither `agent` nor `Workflow`; declared subagents do not receive the built-in `agent` either. See [Subagents](../subagents).
+- **`agent`** is available only in the root session. Its child uses the root's instructions, tools, connections, and sandbox, but starts with fresh conversation history and fresh [state](./state). The child receives neither `agent` nor `Workflow`; declared subagents do not receive the built-in `agent` either. See [Subagents](../subagents).
 - **`load_skill`** only pulls instructions into context. It adds no new execution surface, because behavior still comes from the tools the agent already has.
 - **`connection_search`** surfaces a connection's tools by their qualified name (e.g. `linear__list_issues`), which the model can then call directly. It's registered only when the agent has connections.
 - **`web_search`** has no local executor; the provider runs it. AI Gateway models use Exa by default. To use Parallel instead, export `webSearch({ provider: "parallel" })` from `agent/tools/web_search.ts`. Direct provider models continue to use their native search implementation. To supply your own implementation, override it with `defineTool()`.
@@ -125,7 +125,7 @@ import { experimental_workflow } from "eve/tools";
 export default experimental_workflow({ maxSubagents: 100 });
 ```
 
-With it on, the model can orchestrate the agent's own subagents from model-authored JavaScript, all as one durable step. The tool is root-only — delegated subagent sessions never see it — and one program may dispatch at most the configured `maxSubagents` calls (default 100). See [Dynamic workflows](../guides/dynamic-workflows).
+With it on, the model can orchestrate the agent's own subagents from model-authored JavaScript, all as one durable step. The tool is root-only — delegated subagent sessions never see it — and one program may dispatch at most the configured `maxSubagents` calls (default 100). See [Workflow Tool](../subagents/workflow-tool).
 
 ## The opt-in `sleep` tool
 

package/docs/concepts/execution-model-and-durability.mdx

@@ -17,7 +17,7 @@ Every turn runs as a durable workflow, built on the open-source [Workflow SDK](h
 
 The Workflow SDK is not inherently tied to Vercel. In local development and in a self-deployed `eve start` process, eve uses the SDK's local world by default; that world persists workflow runs on disk under `.eve/.workflow-data` and dispatches through the same Nitro-hosted workflow routes. On Vercel, the same workflow code runs against Vercel Workflow instead, which adds platform features such as latest production deployment routing and dashboard run metadata.
 
-When a Vercel production deployment changes, the next model turn in an existing session uses that deployment's current instructions, model, and tools. The durable session keeps its conversation history and authored state, so identity-based channels such as Telegram private chats and Twilio phone-number conversations adopt agent updates without requiring a new session.
+When a Vercel production deployment changes, the next model turn in an existing session uses that deployment's current system-role instructions, model, and tools. Static user-role instructions stay pinned in the durable conversation history and are not seeded again. Identity-based channels such as Telegram private chats and Twilio phone-number conversations therefore adopt agent behavior updates without duplicating or rewriting their existing context.
 
 Nitro hosts the HTTP routes and workflow entrypoints. It does not supply the workflow state store or the sandbox runtime. Those are separate adapters: Workflow uses the active world implementation, and Sandbox uses the backend from `agent/sandbox` or `defaultBackend()`.
 
@@ -60,7 +60,7 @@ Crash the process, hit a timeout, or redeploy mid-turn, and the run picks up fro
 
 There's nothing to configure. eve owns the workflow lifecycle, and sessions are durable by default.
 
-You don't write workflow code directly. Workflow primitives (`start()`, `resumeHook()`, etc.) are an implementation detail of eve's runtime layer; channels, tools, and hooks never touch them. Two surfaces give your own code session data: tools read the current session's metadata (id, turn, auth, parent lineage) via `ctx.session`, and [`defineState`](../guides/state) reads or writes session-scoped durable state. See [State](../guides/state) for the read/write model.
+You don't write workflow code directly. Workflow primitives (`start()`, `resumeHook()`, etc.) are an implementation detail of eve's runtime layer; channels, tools, and hooks never touch them. Two surfaces give your own code session data: tools read the current session's metadata (id, turn, auth, parent lineage) via `ctx.session`, and [`defineState`](./state) reads or writes session-scoped durable state. See [State](./state) for the read/write model.
 
 ## Parked work
 
@@ -91,10 +91,10 @@ A turn can hand work off to a [subagent](../subagents). Each subagent gets its o
 
 ## How eve orders session history
 
-Conversation history within a session is append-only. Turns land in order, and the tool calls inside a turn (plus their results) keep their order too. Read a session back and you see events in the order they happened.
+Conversation history within a session is append-only. Static user-role instructions lead fresh-session history. Dynamic user-role instructions land at their session or turn boundary before the current delivery. Turns follow in order, and the tool calls inside a turn (plus their results) keep their order too. Read a session back and you see messages in the order they happened.
 
 ## What to read next
 
 - [Sessions and streaming](./sessions-runs-and-streaming): the handles you hold and the event stream you watch.
 - [Security model](./security-model): the trust boundaries the runtime enforces.
-- [State](../guides/state): durable per-session memory that persists across step boundaries.
+- [State](./state): durable per-session memory that persists across step boundaries.

package/docs/concepts/meta.json

@@ -1,8 +1,10 @@
 {
-  "title": "Concepts",
+  "title": "Core Concepts",
+  "defaultOpen": false,
   "pages": [
     "execution-model-and-durability",
     "sessions-runs-and-streaming",
+    "state",
     "default-harness",
     "context-control",
     "security-model"

package/docs/concepts/sessions-runs-and-streaming.md

@@ -14,7 +14,7 @@ or creates a replacement implicitly.
 Authored channels also have channel-local continuation tokens. A token addresses
 whichever session currently owns a platform conversation, such as a Slack thread.
 That identity stays behind the channel boundary and is never accepted or returned
-by the eve HTTP session API. See [Custom channels](../channels/custom#address-and-session-handles).
+by the eve HTTP session API. See [Custom channels](../channels/custom#channel-operations-and-session-handles).
 
 Sessions last 30 days by default; configure `limits.sessionTimeoutMs` in
 `agent.ts`, or set it to `false` to disable the deadline. At expiration, eve
@@ -45,8 +45,8 @@ The stream is newline-delimited JSON (NDJSON), one event per line:
 
 | Event                     | Meaning                                                                                                          |
 | ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `session.started`         | A durable session was created.                                                                                   |
-| `turn.started`            | A new turn began.                                                                                                |
+| `session.started`         | A durable session was created; carries `trace` when the runtime is traced.                                       |
+| `turn.started`            | A new turn began; carries the active `trace` when the runtime is traced.                                         |
 | `message.received`        | An inbound user message was accepted; carries flattened text plus structured text/file parts.                    |
 | `step.started`            | A model step began.                                                                                              |
 | `actions.requested`       | The model requested one or more actions, including tool calls; calls stream before execution.                    |
@@ -73,6 +73,8 @@ The stream is newline-delimited JSON (NDJSON), one event per line:
 | `session.failed`          | The session failed.                                                                                              |
 | `session.completed`       | The session reached a terminal end.                                                                              |
 
+The optional `data.trace` on session and turn starts contains eve-owned W3C trace coordinates: `traceId`, `spanId`, and `traceFlags`. Use it to correlate stream consumers such as eval reporters with an observability backend. An uninstrumented target omits it.
+
 `reasoning.appended` and `message.appended` stream incremental output as it arrives. When the durable stream writer is busy, eve may coalesce adjacent deltas of the same type; the text remains in source order, and any other event forms an ordering barrier. Each append carries both the new delta and the cumulative text for the current block. The finalized block shows up on `message.completed` and `reasoning.completed`, which is the compatibility path for clients that don't render incremental streaming.
 
 `action.partial` carries one complete preliminary output snapshot from an authored async-generator tool. A later partial for the same `callId` replaces it, and `action.result` is the final snapshot. When the durable writer is busy, eve may keep only the newest adjacent partial for a call. Treat partials as last-write-wins: a durable step can retry and replay overlapping event runs. Provider-executed tool progress and MCP progress notifications are not projected as `action.partial` events.
@@ -148,9 +150,17 @@ curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId> \
   -d '{"message":"Now send the short version."}'
 ```
 
-The follow-up reuses the same durable session: same history, same state. Message sends default to cancellation-backed `"steer"`; if a turn is active, eve buffers the follow-up, cancels that turn, and starts the message under a new turn ID. Channels and TypeScript `Session.send(...)` calls can select `turnPolicy: "queue"` when active work should finish first. Structured `inputResponses` never steer.
+The follow-up reuses the same durable session: same history, same state. A follow-up accepts exactly one of `message` or `inputResponses`. Use structured responses to answer one or more pending human-input requests by ID:
 
-If one pending batch is waiting on a human-in-the-loop approval, a matching text reply such as `approve` or `cancel` answers it. Unrelated text starts an ordinary turn immediately without denying the tool call; the approval stays pending and answerable. A later structured `inputResponses` answer keyed by its `requestId` still resumes the original tool call, even after intervening turns.
+```bash
+curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId> \
+  -H 'content-type: application/json' \
+  -d '{"inputResponses":[{"requestId":"req_A","optionId":"approve"}]}'
+```
+
+Message sends default to cancellation-backed `"steer"`; if a turn is active, eve buffers the follow-up, cancels that turn, and starts the message under a new turn ID. Channels and TypeScript `Session.send(...)` calls can select `turnPolicy: "queue"` when active work should finish first. Structured `inputResponses` never steer.
+
+If the session is waiting on a human-in-the-loop approval, respond with the channel’s Approve or Cancel controls. Text messages do not decide an approval; unrelated text starts an ordinary turn while the approval stays pending and answerable. A later structured `inputResponses` answer keyed by its `requestId` still resumes the original tool call, even after intervening turns.
 
 With one question-only batch, an exact option match or permitted freeform response answers `ask_question`. Any other follow-up marks the question unanswered and starts the new turn. With several approval or question batches pending, eve does not guess which batch plain text addresses: the message starts an ordinary turn and the batches stay open. Use structured responses to target requests unambiguously.
 
@@ -190,9 +200,11 @@ curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId>/reset \
   -d '{"reason":"Start over"}'
 ```
 
-Compaction summarizes context, clear removes model-message history in place,
-and reset terminally retires the session. A reset ID never becomes a new session;
-create another session explicitly for a fresh conversation.
+Compaction summarizes context without adding a user message. User-role instructions are ordinary history and may be represented by the summary; system-role instructions remain outside it. If a turn is active, eve queues the request until that turn settles. A successful compaction emits `compaction.requested` and `compaction.completed`, followed by `session.waiting`; if summarization fails, the session returns to waiting with its previous history.
+
+Clear removes model-message history in place, including static and dynamic user-role instructions, while preserving the session identity, system-role instructions, tools, skills, durable state, limits, and sandbox. It does not rerun instruction definitions or resolvers. It emits `context.cleared` followed by `session.waiting`.
+
+Reset terminally retires the exact session ID. A reset ID never becomes a new session; create another session explicitly for a fresh conversation. Compact, clear, and reset return `"no_active_session"` when the target is already inactive.
 
 ## Reconnect and rewind
 
@@ -227,11 +239,11 @@ The lookup is opt-in; requests without the parameter get no header. The TypeScri
 
 For scripts, server-to-server calls, tests, evals, and custom UIs, `eve/client` wraps these routes in a typed client so you don't hand-roll the POST and NDJSON stream loop.
 
-Start with the [TypeScript SDK](../guides/client/overview) guide. It covers basic usage, sending messages, session state, streaming, and per-turn `outputSchema` results.
+Start with the [Client SDK](../guides/client/overview) guide. It covers basic usage, sending messages, session state, streaming, and per-turn `outputSchema` results.
 
 ## Inspect the agent over HTTP
 
-`GET /eve/v1/info` returns a JSON inspection snapshot for the running agent: model, instructions, authored and framework tools, skills, channels, schedules, subagents, sandbox, connections, hooks, workflow, and workspace metadata. It uses the resolved `eveChannel()` route auth when `agent/channels/eve.ts` authors one; otherwise it falls back to the framework default of Vercel OIDC plus local development access.
+`GET /eve/v1/info` returns a JSON inspection snapshot for the running agent: model, static instructions, authored and framework tools, skills, channels, schedules, subagents, sandbox, connections, hooks, workflow, and workspace metadata. Static instructions are an ordered array whose entries expose `content` and `role`; dynamic resolver output is runtime context and is not included. The route uses the resolved `eveChannel()` auth when `agent/channels/eve.ts` authors one; otherwise it falls back to the framework default of Vercel OIDC plus local development access.
 
 ```bash
 curl http://127.0.0.1:2000/eve/v1/info
@@ -254,5 +266,5 @@ The order is structural, not incidental. By the time a resolver or hook reads ch
 
 - [Execution model & durability](./execution-model-and-durability): what makes a session durable and how parked work resumes.
 - [Channels](../channels/overview): how platform addresses map to durable sessions.
-- [TypeScript SDK](../guides/client/overview): call these routes from scripts and server-side code.
+- [Client SDK](../guides/client/overview): call these routes from scripts and server-side code.
 - [Frontend](../guides/frontend/overview): `useEveAgent` instead of raw routes.

package/docs/{guides → concepts}/state.md

@@ -46,7 +46,7 @@ export default defineTool({
 
 ## Reset state between turns
 
-State is durable by default and does not reset between turns. If you want a clean slate every turn, overwrite it from a lifecycle [hook](./hooks) on `turn.started`:
+State is durable by default and does not reset between turns. If you want a clean slate every turn, overwrite it from a lifecycle [hook](../guides/hooks) on `turn.started`:
 
 ```ts title="agent/hooks/reset-budget.ts"
 import { defineHook } from "eve/hooks";
@@ -73,7 +73,7 @@ Every [subagent](../subagents) starts with its own fresh state, whether it's a b
 
 ## What to read next
 
-- Read state inside dynamic resolvers → [Dynamic capabilities](./dynamic-capabilities)
+- Read state inside dynamic resolvers → [Dynamic capabilities](../guides/dynamic-capabilities)
 - How step durability works → [Execution model & durability](../concepts/execution-model-and-durability)
-- The `ctx` accessors available alongside state → [TypeScript API](../reference/typescript-api)
+- The `ctx` accessors available alongside state → [TypeScript API Reference](../reference/typescript-api)
 - Tenant-scoped long-term memory in your own store → [Multi-tenant memory](../patterns/multi-tenant-memory)

package/docs/connections/mcp.mdx

@@ -26,68 +26,13 @@ The `url` must speak Streamable HTTP or SSE. Write the `description` for the mod
 
 ## Use Vercel Connect for OAuth
 
-For OAuth-backed MCP servers, prefer [Vercel Connect](https://vercel.com/docs/connect). Connect owns the browser consent flow, encrypted token storage, refresh, and project access. The `connect()` helper from `@vercel/connect/eve` plugs that lifecycle into eve's connection auth, so credentials never land in model context or conversation history.
+For OAuth-backed MCP servers, use the shared [Vercel Connect flow](../connections#interactive-oauth-via-vercel-connect), then pass the returned connector UID to `connect()`. Keep the MCP runtime URL and Connect service identifier distinct. For example, Linear uses `https://mcp.linear.app/mcp` as the MCP endpoint and `mcp.linear.app` when creating the connector.
 
-From the Vercel project or agent app that will run the connection:
-
-```bash
-npm install @vercel/connect
-vercel link
-vercel connect create mcp.linear.app --name linear
-vercel connect attach <connector-uid> --yes
-vercel env pull
-```
-
-Use the connector UID returned by the CLI in `connect("<connector-uid>")`. For Linear, the MCP runtime endpoint is `https://mcp.linear.app/mcp`, while the managed Connect service identifier is `mcp.linear.app`; those are related but not interchangeable.
-
-By default, `connect("...")` is user-scoped. The first tool call for a new user emits an `authorization.required` event with a URL to visit, parks the turn, and resumes after the callback completes. The active eve session must already have a user principal from route auth or from a platform channel. If there is no authenticated user, the connection fails with `reason: "principal_required"`.
-
-If the MCP server should act as the agent itself instead of the signed-in user, make the connector app-scoped:
-
-```ts title="agent/connections/linear.ts"
-import { connect } from "@vercel/connect/eve";
-import { defineMcpClientConnection } from "eve/connections";
-
-export default defineMcpClientConnection({
-  url: "https://mcp.linear.app/mcp",
-  description: "Linear workspace: issues, projects, cycles, and comments.",
-  auth: connect({ connector: "mcp.linear.app/linear", principalType: "app" }),
-});
-```
-
-App-scoped Connect auth is non-interactive. eve asks Connect for one shared app token; if the connector is missing or cannot issue an app token, the tool call fails terminally so an operator can fix setup.
+`connect("...")` is user-scoped by default and requires an authenticated user on the active eve session. Use `connect({ connector, principalType: "app" })` when the server should act as the agent instead. The connections overview covers connector setup, session requirements, app and user scope, callback behavior, and troubleshooting.
 
 ## Static tokens and headers
 
-Use `auth.getToken` when you already have a bearer token, API key, service account token, or out-of-band OAuth flow. eve sends the returned token as `Authorization: Bearer <token>`.
-
-```ts title="agent/connections/linear.ts"
-import { defineMcpClientConnection } from "eve/connections";
-
-export default defineMcpClientConnection({
-  url: "https://mcp.linear.app/mcp",
-  description: "Linear workspace: issues, projects, cycles, and comments.",
-  auth: {
-    getToken: async () => ({ token: process.env.LINEAR_API_TOKEN! }),
-  },
-});
-```
-
-Use `headers` for non-Bearer auth schemes or extra server configuration:
-
-```ts title="agent/connections/private-docs.ts"
-import { defineMcpClientConnection } from "eve/connections";
-
-export default defineMcpClientConnection({
-  url: "https://docs.example.com/mcp",
-  description: "Internal docs: search pages, owners, and recent changes.",
-  headers: {
-    "X-Api-Key": process.env.DOCS_API_KEY!,
-  },
-});
-```
-
-`auth` and `headers` can also be functions that receive the active session context. Use that when credentials, tenants, or routing depend on the caller.
+MCP connections accept the shared connection `auth` and `headers` options. Use `auth.getToken` for a bearer token, `headers` for another scheme, and resolver functions when credentials or routing depend on the caller. See [Static-token auth](../connections#static-token-auth), [Headers](../connections#headers), and [Per-caller auth and headers](../connections#per-caller-auth-and-headers) for the canonical examples and token-lifecycle behavior.
 
 ## Application-provided tool arguments
 
@@ -119,18 +64,7 @@ eve treats configured keys as application-owned: it removes them from every remo
 
 ## No auth
 
-Omit `auth` and `headers` only for intentionally public or local-only servers:
-
-```ts title="agent/connections/local.ts"
-import { defineMcpClientConnection } from "eve/connections";
-
-export default defineMcpClientConnection({
-  url: "http://localhost:3001/mcp",
-  description: "Local dev MCP server.",
-});
-```
-
-Do not use a no-auth connection for sensitive third-party services unless another layer protects the endpoint.
+Omit `auth` and `headers` only for an intentionally public or loopback MCP server. See [No auth](../connections#no-auth) for the shared connection behavior and security boundary.
 
 ## Tool filters
 
@@ -152,24 +86,7 @@ Prefer `allow` for the smallest safe surface, especially when the server exposes
 
 ## Approval gates
 
-For MCP tools that can create, modify, delete, message, transmit, purchase, or access sensitive data, add a human approval gate:
-
-```ts title="agent/connections/linear.ts"
-import { connect } from "@vercel/connect/eve";
-import { defineMcpClientConnection } from "eve/connections";
-import { once } from "eve/tools/approval";
-
-export default defineMcpClientConnection({
-  url: "https://mcp.linear.app/mcp",
-  description: "Linear workspace.",
-  auth: connect("mcp.linear.app/linear"),
-  approval: once(),
-});
-```
-
-`once()` asks the first time in a session, `always()` asks on every tool call, and `never()` allows calls without approval. Authorization and approval work together: eve records approval before an OAuth park, then resumes without asking again for the same approved call.
-
-The `once()`, `always()`, and `never()` helpers from `eve/tools/approval` gate every tool the connection serves the same way. See [Connections](/docs/connections#per-connection-approval) for those, and [Human-in-the-loop](/docs/human-in-the-loop) for the full pause-and-resume contract.
+Use the shared `approval` option to gate every tool served by an MCP connection. The [connections overview](../connections#per-connection-approval) defines the `never()`, `once()`, and `always()` helpers; [Human-in-the-loop](../human-in-the-loop#approvals) defines the pause-and-resume contract.
 
 ### Gate specific tools by name or input
 
@@ -233,5 +150,5 @@ When a remote tool returns more data than the model needs, narrow the result at
 
 - [Connections](../connections): shared auth, headers, approval, and per-caller patterns.
 - [OpenAPI connections](./openapi): generate tools from OpenAPI operations.
-- [Auth & route protection](../guides/auth-and-route-protection): route auth and the full interactive OAuth lifecycle.
+- [Authentication](../guides/auth-and-route-protection): establish the caller identity required by user-scoped auth.
 - [Security model](../concepts/security-model): how connection credentials stay out of the model's reach.

package/docs/connections/meta.json

@@ -1,4 +1,5 @@
 {
   "title": "Connections",
+  "defaultOpen": false,
   "pages": ["overview", "mcp", "openapi"]
 }

package/docs/connections/openapi.mdx

@@ -48,19 +48,7 @@ export default defineOpenAPIConnection({
 
 ## Use Vercel Connect for OAuth
 
-For OAuth-backed APIs, prefer [Vercel Connect](https://vercel.com/docs/connect). Connect owns browser consent, encrypted token storage, refresh, and project access. The `connect()` helper from `@vercel/connect/eve` plugs that lifecycle into eve's connection auth, so tokens never reach model context or conversation history.
-
-Create or attach a connector for the API provider from the Vercel project or agent app that will run the connection:
-
-```bash
-npm install @vercel/connect
-vercel link
-vercel connect create github --name github
-vercel connect attach <connector-uid> --yes
-vercel env pull
-```
-
-Then use the connector UID returned by the CLI:
+For an OAuth-backed API, follow the shared [Vercel Connect setup](../connections#interactive-oauth-via-vercel-connect), then attach the returned connector UID to the OpenAPI connection:
 
 ```ts title="agent/connections/github.ts"
 import { connect } from "@vercel/connect/eve";
@@ -74,48 +62,11 @@ export default defineOpenAPIConnection({
 });
 ```
 
-By default, `connect("...")` is user-scoped. The active eve session must have a user principal from route auth or from a platform channel before the first operation call. If the API should act as the agent itself, make the connector app-scoped:
-
-```ts
-auth: connect({ connector: "github/github", principalType: "app" });
-```
-
-Use `tokenParams` on `connect(...)` when the provider requires explicit OAuth scopes, audiences, resource indicators, or authorization details.
+`connect("...")` is user-scoped by default and requires an authenticated user on the active session. Use `connect({ connector, principalType: "app" })` when the API should act as the agent instead. Configure provider-specific scopes, audiences, or authorization details through `tokenParams` on `connect(...)`.
 
 ## Static tokens and headers
 
-Use `auth.getToken` when you already have a bearer token, API key, service account token, or out-of-band OAuth flow. eve sends the returned token as `Authorization: Bearer <token>`.
-
-```ts title="agent/connections/crm.ts"
-import { defineOpenAPIConnection } from "eve/connections";
-
-export default defineOpenAPIConnection({
-  spec: "https://api.example.com/openapi.json",
-  baseUrl: "https://api.example.com",
-  description: "CRM accounts, contacts, and opportunities.",
-  auth: {
-    getToken: async () => ({ token: process.env.CRM_TOKEN! }),
-  },
-});
-```
-
-Use `headers` for non-Bearer auth schemes, version headers, or tenant routing:
-
-```ts title="agent/connections/notion.ts"
-import { defineOpenAPIConnection } from "eve/connections";
-
-export default defineOpenAPIConnection({
-  spec: "https://developers.notion.com/openapi.json",
-  baseUrl: "https://api.notion.com",
-  description: "Notion pages, databases, comments, and users.",
-  headers: {
-    Authorization: `Bearer ${process.env.NOTION_API_KEY!}`,
-    "Notion-Version": "2022-06-28",
-  },
-});
-```
-
-`auth` and `headers` can also be functions that receive the active session context. Use that when credentials, tenants, or routing depend on the caller.
+OpenAPI connections accept the shared connection `auth` and `headers` options. Use `auth.getToken` for a bearer token, `headers` for another scheme or API version, and resolver functions when credentials or routing depend on the caller. See [Static-token auth](../connections#static-token-auth), [Headers](../connections#headers), and [Per-caller auth and headers](../connections#per-caller-auth-and-headers) for the canonical examples and token-lifecycle behavior.
 
 ## Application-provided operation arguments
 
@@ -201,26 +152,11 @@ The parameter `name` must exactly match the placeholder inside the path. If the
 
 ## Approval gates
 
-Generated operation tools can mutate state just like authored tools. Add an approval gate when operations can create, modify, delete, message, transmit, purchase, or access sensitive data:
-
-```ts title="agent/connections/crm.ts"
-import { defineOpenAPIConnection } from "eve/connections";
-import { once } from "eve/tools/approval";
-
-export default defineOpenAPIConnection({
-  spec: "https://api.example.com/openapi.json",
-  baseUrl: "https://api.example.com",
-  description: "CRM accounts, contacts, and opportunities.",
-  auth: { getToken: async () => ({ token: process.env.CRM_TOKEN! }) },
-  approval: once(),
-});
-```
-
-Combine `approval` with `operations.allow` for the smallest practical surface.
+Generated operations can mutate state like authored tools. Use the shared connection `approval` option for human approval, and combine it with `operations.allow` for the smallest practical surface. See [Per-connection approval](../connections#per-connection-approval) for the helpers and [Human-in-the-loop](../human-in-the-loop#approvals) for policy behavior.
 
 ## What to read next
 
 - [Connections](../connections): shared auth, headers, approval, and per-caller patterns.
 - [MCP connections](./mcp): connect to remote MCP servers.
-- [Auth & route protection](../guides/auth-and-route-protection): route auth and the full interactive OAuth lifecycle.
+- [Authentication](../guides/auth-and-route-protection): establish the caller identity required by user-scoped auth.
 - [Security model](../concepts/security-model): how connection credentials stay out of the model's reach.

package/docs/connections/overview.mdx

@@ -22,7 +22,21 @@ Read [OpenAPI connections](/docs/connections/openapi) for `defineOpenAPIConnecti
 
 ## Static-token auth
 
-`getToken` returns a `TokenResult` (`{ token, expiresAt? }`), and eve sends it as `Authorization: Bearer <token>` on every request. Because it runs on each connection attempt, you can mint a fresh token from wherever you keep secrets, including an env var, a secrets manager, an internal vault, or your own OAuth exchange. If the token has a known TTL, set `expiresAt` (milliseconds since epoch) and eve refreshes ahead of time rather than waiting for a `401`.
+`getToken` returns a `TokenResult` (`{ token, expiresAt? }`), and eve sends it as `Authorization: Bearer <token>` on every request. Because it runs on each connection attempt, you can mint a fresh token from wherever you keep secrets, including an env var, a secrets manager, an internal vault, or your own OAuth exchange:
+
+```ts title="agent/connections/linear.ts"
+import { defineMcpClientConnection } from "eve/connections";
+
+export default defineMcpClientConnection({
+  url: "https://mcp.linear.app/mcp",
+  description: "Linear workspace.",
+  auth: {
+    getToken: async () => ({ token: process.env.LINEAR_API_TOKEN! }),
+  },
+});
+```
+
+If the token has a known TTL, set `expiresAt` (milliseconds since epoch) and eve refreshes ahead of time rather than waiting for a `401`.
 
 When `getToken` is the only auth, `principalType` defaults to `"app"`: one shared credential keyed across all sessions. Switch to `principalType: "user"` when each end-user carries their own token.
 
@@ -123,7 +137,19 @@ For connection tools that can create, modify, delete, transmit, purchase, messag
 
 ## Interactive OAuth via Vercel Connect
 
-When the server uses OAuth and you want each end-user to sign in through their own browser, turn on interactive authorization with [Vercel Connect](https://vercel.com/docs/connect). The `connect()` helper from `@vercel/connect/eve` handles consent, encrypted token storage, and refresh, then hooks all of that into eve's authorization flow:
+When the server uses OAuth and you want each end-user to sign in through their own browser, turn on interactive authorization with [Vercel Connect](https://vercel.com/docs/connect). The `connect()` helper from `@vercel/connect/eve` handles consent, encrypted token storage, and refresh, then hooks all of that into eve's authorization flow.
+
+Create and attach the connector from the Vercel project or agent app that will use it:
+
+```bash
+npm install @vercel/connect
+vercel link
+vercel connect create <service> --name <name>
+vercel connect attach <connector-uid> --yes
+vercel env pull
+```
+
+Use the connector UID returned by the CLI in `connect("<connector-uid>")`. The service identifier accepted by `vercel connect create` depends on the provider; it is not necessarily the same as an MCP runtime URL or OpenAPI base URL.
 
 ```ts title="agent/connections/linear.ts"
 import { connect } from "@vercel/connect/eve";
@@ -155,7 +181,7 @@ export default defineMcpClientConnection({
 });
 ```
 
-App-scoped Connect auth is non-interactive. eve asks Vercel Connect for an app token and does not emit a browser consent challenge; if the connector is not installed or cannot issue an app token, the tool call fails terminally so an operator can fix the connector setup. The full setup (Connect client provisioning, project linking, the runtime consent flow) lives in [Auth & route protection](/docs/guides/auth-and-route-protection).
+App-scoped Connect auth is non-interactive. eve asks Vercel Connect for an app token and does not emit a browser consent challenge; if the connector is not installed or cannot issue an app token, the tool call fails terminally so an operator can fix the connector setup. See [Authentication](/docs/guides/auth-and-route-protection) when a user-scoped connection needs your HTTP channel to establish the caller's identity.
 
 ### Troubleshooting Vercel Connect auth
 

package/docs/evals/meta.json

@@ -1,4 +1,5 @@
 {
   "title": "Evals",
+  "defaultOpen": false,
   "pages": ["overview", "cases", "assertions", "judge", "targets", "reporters", "running"]
 }