eve 0.34.0 → 0.35.0

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"]
 }

package/docs/evals/reporters.mdx

@@ -38,7 +38,7 @@ export default defineEval({
 });
 ```
 
-The reporter config takes an optional `projectName` and `experimentName`, plus a base experiment (by name or id) to diff against. Gate assertions log as binary scores under a `gate:` prefix so experiments diff gate regressions the same way they diff soft-score regressions. Repeated names use `#2`, `#3`, and later suffixes; use `.label(name)` to give them meaningful names. Failed assertion details are stored in the Braintrust metadata under `eveFailedAssertions`.
+The reporter config takes an optional `projectName` and `experimentName`, plus a base experiment (by name or id) to diff against. Gate assertions log as binary scores under a `gate:` prefix so experiments diff gate regressions the same way they diff soft-score regressions. Repeated names use `#2`, `#3`, and later suffixes; use `.label(name)` to give them meaningful names. Failed assertion details are stored in the Braintrust metadata under `eveFailedAssertions`; observed traces are stored under `eveTraceIds` and `eveTraceContexts`.
 
 A reporter instance observes the evals that reference it. Share one instance across several evals (the config, a `shared.ts` export, or every entry of a dataset array) and their results land in a single experiment. Listing the same config reporter on an eval too does not double-report it.
 
@@ -56,17 +56,27 @@ Each eval becomes one `<testcase>` named by its path-derived id; failed gates an
 
 ## Custom reporters
 
-A reporter implements the `EvalReporter` interface from `eve/evals/reporters` and receives the same structured results the built-ins do. The runner calls three lifecycle methods, each of which may return a promise for async work like a remote upload:
+A reporter implements the `EvalReporter` interface from `eve/evals/reporters` and receives the same structured results the built-ins do. Every callback may return a promise for async work like a remote upload:
 
 ```ts
 interface EvalReporter {
   onRunStart(evaluations: readonly EveEval[], target: EveEvalTarget): void | Promise<void>;
-  onEvalComplete(result: EveEvalResult): void | Promise<void>;
+  onEvalStart?(event: EveEvalStartEvent): void | Promise<void>;
+  onSessionStart?(event: EveEvalSessionStartEvent): void | Promise<void>;
+  onEvalComplete(result: EveEvalResult, context?: EveEvalCompleteContext): void | Promise<void>;
   onRunComplete(summary: EveEvalRunSummary): void | Promise<void>;
 }
 ```
 
-`onRunStart` fires once before any eval runs, `onEvalComplete` fires after each observed eval with its checks, scores, and verdict, and `onRunComplete` fires once with the aggregated summary. Reach for a custom reporter only when a destination isn't covered. The per-run artifacts under `.eve/evals/` already capture everything for ad-hoc inspection.
+`onRunStart` fires once before any eval runs, and `onRunComplete` fires once with the aggregated summary. Within that run:
+
+- `onEvalStart` fires when an eval is scheduled. It includes the eval definition, target, and start time.
+- `onSessionStart` fires once for each session after eve receives its first trace context. It includes `sessionId`, `primary`, and `traceContext` with `traceId`, `spanId`, and `traceFlags`.
+- `onEvalComplete` fires with the checks, scores, and verdict. The runner also supplies `context`, including every distinct trace context collected across the eval's sessions. The same list is available as `result.result.traceContexts`.
+
+An eval can create several sessions, and a long session can produce several traces, so completion exposes a list instead of a single trace id. `onEvalStart` does not include a trace because the agent session has not started yet. If the target has no tracing configured, `onSessionStart` does not fire and the completed trace list is empty.
+
+Reporter callbacks for an eval stay ordered—eval start, traced session starts, then completion—even when several evals run concurrently. Reach for a custom reporter only when a destination isn't covered. The per-run artifacts under `.eve/evals/` retain the trace contexts alongside the result for ad-hoc inspection.
 
 ## What to read next
 

package/docs/extensions.md

@@ -5,7 +5,7 @@ description: "Package reusable eve capabilities and mount them from npm or a mon
 
 Extensions package eve tools, connections, skills, instruction fragments, and hooks. An author builds an extension package; each agent that uses it declares the package as a dependency and mounts it. The package can be published to a package registry or kept private inside a monorepo workspace.
 
-Ready-made extensions can also be distributed through an eve integration registry. See [Install Integrations](./install-integrations) to discover and add one with `eve add`; this page explains how extension packages are authored, mounted, configured, and overridden.
+Ready-made extensions can also be distributed through an eve integration registry. See [Add Integrations](./install-integrations) to discover and add one with `eve add`; this page explains how extension packages are authored, mounted, configured, and overridden.
 
 This enables sharing many different capability sets. A browser extension might include several tools for navigating a site. A memory extension could use hooks to capture context and tools to recall it. A self-improving extension could pair hooks with dynamic instructions.
 

package/docs/getting-started.mdx

@@ -1,23 +1,185 @@
 ---
 title: "Getting Started"
-description: "Create an eve project, learn its filesystem layout, and start adding capabilities."
-contentType: "Landing"
+description: "Create an eve project, configure a model, understand its filesystem layout, and run your first agent."
+contentType: "How-to"
 ---
 
-eve agents are TypeScript projects. You describe an agent with files under `agent/`, then eve runs it as a durable service.
+## Prerequisites
 
-## Start in order
-
-1. [Install eve](/docs/installation): create a project, configure a model credential, and run it locally
-2. [Learn the project structure](/docs/project-structure): see which files eve discovers and where each capability belongs
-3. [Build your first agent](/docs/tutorial/first-agent): add tools, state, and an interface for a useful workflow
-
-## What you need
+You need:
 
 - Node.js 24 or newer
 - npm, which Node.js includes
-- A model credential for the model your agent uses
+- A credential for the model your agent uses
+
+The default scaffolded model routes through the Vercel AI Gateway. Set `AI_GATEWAY_API_KEY`, or link a Vercel project to use `VERCEL_OIDC_TOKEN`. To use a model provider directly, install its AI SDK provider package and set the provider's API key.
+
+Choose a model, provider, and channel that meet your data-processing and compliance requirements.
+
+## Create a project
+
+Run `eve init` with a project name:
+
+```bash
+npx eve@latest init my-agent
+```
+
+The command creates the project, installs dependencies, and initializes Git. If a supported coding-agent REPL is available, eve offers to start the development server, open the REPL, or exit after scaffolding.
+
+Pass an AI Gateway model ID or reasoning effort when you do not want the defaults:
+
+```bash
+npx eve@latest init my-agent --model openai/gpt-5.5 --reasoning high
+```
+
+To add eve to a project that already has a `package.json`, run this command from its root before you create any `agent/` files:
+
+```bash
+npx eve@latest init .
+```
+
+eve adds the missing `eve`, `ai`, and `zod` dependencies without changing files the project already owns.
+
+## Run the agent
+
+If the development server is not already running, start it from the project root:
+
+```bash
+npm run dev
+```
+
+The TUI sends messages to your agent. Stop the server with `Ctrl+C` when you need your shell for another command.
+
+## Project layout
+
+eve builds an agent by walking the filesystem under `agent/`. Each directory is an authored slot, and the slot a file lands in determines how eve loads it.
+
+### Naming from paths
+
+Identity comes from the path. You never write a `name` or `id` field on a `define*` call.
+
+| Path                                  | Resolves to           |
+| ------------------------------------- | --------------------- |
+| `agent/tools/get_weather.ts`          | tool `get_weather`    |
+| `agent/connections/linear.ts`         | connection `linear`   |
+| `agent/skills/summarize.md`           | skill `summarize`     |
+| `agent/subagents/researcher/agent.ts` | subagent `researcher` |
+
+The root agent takes its name from the enclosing `package.json` `name`, falling back to the app-root directory name when `package.json` has no `name`. A subagent takes its name from its directory.
+
+### Recommended layout
+
+A minimal agent needs `instructions.md`; `agent.ts` is optional when the defaults are sufficient. Add other slots as the agent needs them:
+
+```text
+my-agent/
+├── package.json
+├── tsconfig.json
+├── agent/
+│   ├── agent.ts
+│   ├── instructions.md
+│   ├── instrumentation.ts
+│   ├── channels/
+│   ├── connections/
+│   ├── hooks/
+│   ├── skills/
+│   ├── lib/
+│   ├── sandbox/
+│   ├── tools/
+│   ├── schedules/
+│   └── subagents/
+└── evals/
+```
+
+Evals live beside `agent/`, not inside it.
+
+### Authored slots
+
+The Subagents column states whether a local subagent (`subagents/<id>/`) can author the slot. A declared subagent inherits nothing from the root; it discovers its own slots.
+
+| Path                                                    | Description                               | Subagents | Notes                                                                                                                                                                             |
+| ------------------------------------------------------- | ----------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agent.ts`                                              | Runtime config                            | Yes       | Model, model options, compaction, build, and experimental settings. See [Agents](./agent-config).                                                                                 |
+| `instructions.md` / `instructions.ts` / `instructions/` | Base system prompt                        | Optional  | A flat file or directory of `.md` and `.ts` files. Static sources compose at build time. Dynamic sources resolve at runtime. Required on the root, optional on subagents.         |
+| `instrumentation.ts`                                    | Telemetry config                          | No        | OTel exporter and AI SDK span settings, auto-discovered and run before agent code. Root-only.                                                                                     |
+| `channels/`                                             | HTTP and messaging entry points           | No        | Root-only.                                                                                                                                                                        |
+| `connections/`                                          | External MCP and OpenAPI services         | Yes       | One connection per file; its name comes from the filename.                                                                                                                        |
+| `hooks/`                                                | Lifecycle and stream-event subscribers    | Yes       | Module-backed only. Recursive directories are supported.                                                                                                                          |
+| `skills/`                                               | On-demand procedures and capability packs | Yes       | Flat markdown, module-backed skills, or packaged skills. Runtime files are seeded under `$HOME/.agents/skills/`, with `/workspace/skills/` as a fallback.                         |
+| `lib/`                                                  | Shared authored helper code               | Yes       | Import-only; not mounted into the workspace.                                                                                                                                      |
+| `sandbox.ts` or `sandbox/sandbox.ts`                    | The agent's single sandbox                | Yes       | Use `sandbox.ts` for a definition-only override; use `sandbox/sandbox.ts` with `sandbox/workspace/**` to also seed files. The framework default applies when neither is authored. |
+| `sandbox/workspace/**`                                  | Files seeded into the sandbox             | Yes       | Mirrored into `/workspace/` when a session starts.                                                                                                                                |
+| `tools/`                                                | Typed executable integrations             | Yes       | Module-backed only.                                                                                                                                                               |
+| `schedules/`                                            | Recurring jobs                            | No        | Each schedule is a default-exported `defineSchedule` module or a markdown prompt with `cron` frontmatter. Recursive nesting is supported. Root-only.                              |
+| `subagents/`                                            | Specialist child agents                   | Yes       | Each child is a local package under `subagents/<id>/`. Nested subagents are supported.                                                                                            |
+
+### Runtime files and source files
+
+eve does not mount the whole authored tree into the runtime sandbox. Files under `agent/sandbox/workspace/**` land in `/workspace/` when a session starts.
+
+Skill package files land outside the workspace under `$HOME/.agents/skills/`, with `/workspace/skills/` as a fallback when `$HOME` is unavailable. Everything in `lib/` remains import-only source code.
+
+### Local subagents
+
+A local subagent uses the same `agent.ts` shape as the root:
+
+```text
+agent/subagents/researcher/
+├── agent.ts
+├── instructions.md
+├── connections/
+├── hooks/
+├── skills/
+├── lib/
+├── sandbox/
+├── tools/
+└── subagents/
+```
+
+A subagent's `agent.ts` is required and must provide a description, while its instructions are optional. Connections, hooks, skills, shared code, sandboxes, tools, and nested subagents are supported. Channels and schedules remain root-only. See [Subagents](./subagents) for inheritance and isolation behavior.
+
+### Flat layout
+
+When the app root is also the agent root, eve supports this layout:
+
+```text
+my-agent/
+├── package.json
+├── agent.ts
+├── instructions.md
+├── tools/
+└── skills/
+```
+
+Prefer the nested layout because it keeps application files separate from the authored agent surface.
+
+### Debug file discovery
+
+Run `eve info` when eve does not discover a file. It lists the discovered surface and diagnostics so you can check the authored slot and root-versus-subagent boundary. eve also writes inspectable artifacts under `.eve/`; see [Observability](./guides/instrumentation) and the [CLI](./reference/cli) reference.
+
+## Install manually
+
+If you do not want to use the scaffold, install the runtime dependencies:
+
+```bash
+npm install eve@latest ai zod
+```
+
+Declare Node.js 24 in `package.json`, then create `agent/instructions.md` and, when you need runtime configuration, `agent/agent.ts`.
+
+## Continue with the tutorial
+
+The [Tutorial](/docs/tutorial/first-agent) builds a data analytics agent step by step. It adds tools, state, sandboxed analysis, reusable skills, and human approval before deploying the result.
+
+After the tutorial, continue with the task you need:
 
-## Choose your next step
+| Goal                                                    | Read                                                                                                          |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| Give the model an action it can call                    | [Tools](/docs/tools)                                                                                          |
+| Connect an MCP server or OpenAPI service                | [Connections](/docs/connections)                                                                              |
+| Reach users through Slack, Discord, or another platform | [Channels](/docs/channels/overview)                                                                           |
+| Build a browser interface                               | [Frontend Frameworks](/docs/guides/frontend/overview)                                                         |
+| Test agent behavior                                     | [Evals](/docs/evals/overview)                                                                                 |
+| Secure and deploy the agent                             | [Authentication](/docs/guides/auth-and-route-protection), then [Deployment](/docs/guides/deployment/overview) |
 
-Start with [Installation](/docs/installation) when you need a new project. Read [Project structure](/docs/project-structure) when you already have an eve project or want to add a capability.
+Read [Execution Model and Durability](/docs/concepts/execution-model-and-durability) for the mental model behind sessions, turns, durable steps, and parked work.

package/docs/guides/auth-and-route-protection.md

@@ -1,5 +1,5 @@
 ---
-title: "Auth & Route Protection"
+title: "Authentication"
 description: "Secure your agent's HTTP routes with an ordered auth walk, verifier helpers, and connection OAuth via Vercel Connect."
 ---
 
@@ -12,7 +12,7 @@ Start with route auth.
 
 ## Route auth
 
-The route-auth policy lives on the HTTP channel factory (`agent/channels/eve.ts`) and guards three routes:
+The route-auth policy lives on the HTTP channel factory (`agent/channels/eve.ts`) and guards these route groups:
 
 - `POST /eve/v1/session`
 - `POST /eve/v1/session/:sessionId`
@@ -307,22 +307,7 @@ Built-in platform channels that identify a human sender, such as Slack, Discord,
 
 ### On a connection
 
-Attach `connect()` from `@vercel/connect/eve` to the connection:
-
-```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: project management, issue tracking, and team workflows.",
-  auth: connect("linear/myagent"),
-  approval: once(),
-});
-```
-
-The first call that needs a user-scoped connection kicks off an OAuth sign-in, surfaced as an authorization challenge (a URL the caller visits). [Vercel Connect](https://vercel.com/docs/connect) brokers the flow and holds the credentials, which are resolved and cached per workflow step, never serialized into history, and never shown to the model. For non-interactive connections, pass a static token or `connect({ connector, principalType: "app" })` in place of user-scoped `connect()`. [Connections](../connections) covers both shapes.
+Set `auth` on an MCP or OpenAPI connection when the external service supplies a family of remote tools. The [connections overview](../connections) owns the shared `connect()` setup, static-token providers, app and user scope, approval interaction, and self-hosted OAuth flow.
 
 ### On a single tool
 

package/docs/guides/client/meta.json

@@ -1,4 +1,5 @@
 {
-  "title": "TypeScript SDK",
+  "title": "Client SDK",
+  "defaultOpen": false,
   "pages": ["overview", "messages", "continuations", "streaming", "output-schema"]
 }

package/docs/guides/client/output-schema.mdx

@@ -119,10 +119,10 @@ const followUp = await followUpResponse.result();
 console.log(followUp.data); // undefined unless this turn also requested a schema
 ```
 
-For task-mode output that belongs to the agent or subagent definition itself, see [`agent.ts`](../../agent-config#outputschema) and [Subagents](../../subagents).
+For task-mode output that belongs to the agent or subagent definition itself, see [`agent.ts`](../../agent-config#other-defineagent-fields) and [Subagents](../../subagents).
 
 ## What to read next
 
 - [Messages](./messages): send turns with `send()`
 - [Streaming](./streaming): handle `result.completed` live
-- [`agent.ts`](../../agent-config#outputschema): configured task-mode output
+- [`agent.ts`](../../agent-config#other-defineagent-fields): configured task-mode output

package/docs/guides/client/overview.mdx

@@ -1,5 +1,5 @@
 ---
-title: "TypeScript SDK Overview"
+title: "Client SDK"
 description: "Call an eve agent from TypeScript with Client, sessions, auth, and health checks."
 ---
 

package/docs/guides/deployment/meta.json

@@ -1,4 +1,5 @@
 {
   "title": "Deployment",
+  "defaultOpen": false,
   "pages": ["overview", "vercel", "self-hosting"]
 }