eve 0.9.8 → 0.11.0

package/docs/getting-started.mdx

@@ -3,30 +3,48 @@ title: "Getting Started"
 description: "Install Eve, scaffold your first agent, give it a tool, and run it locally."
 ---
 
-Eve is a filesystem-first framework for durable agents: you write capabilities under `agent/`, and Eve runs the model loop, persists every session, and serves the agent over HTTP and platform channels. This guide gets a small app running locally and walks the current request loop end to end: build, run, message, stream, and follow up.
+Eve is a filesystem-first framework for durable agents. You write capabilities under `agent/`, and Eve runs the model loop, persists every session, and serves the agent over HTTP and platform channels. You'll scaffold an app, add a tool, run it locally, then create, stream, and continue a session over HTTP.
+
+Eve is currently in beta and subject to the [Vercel beta terms](https://vercel.com/docs/release-phases/public-beta-agreement). The framework, APIs, documentation, and behavior may change before general availability.
+
+## Prerequisites
+
+- Node 24 or newer
+- npm (bundled with Node)
+- A model credential (see below)
+
+The scaffold's default model is `anthropic/claude-sonnet-4.6`, which routes through the Vercel AI Gateway. Set one of these before you run the agent:
+
+- A gateway model id needs `AI_GATEWAY_API_KEY`, or a `VERCEL_OIDC_TOKEN` pulled with `vercel link`.
+- A direct provider id needs that provider's key, derived from the model prefix. For example, `anthropic/claude-...` needs `ANTHROPIC_API_KEY`.
+
+You are responsible for selecting a model, provider, and channel appropriate for your data and use case, and for complying with each provider's terms (as listed per model) and data-processing requirements.
+
+If you skip this, the dev TUI flags the missing credential and its `/model` command walks you through pasting a key or linking a project.
 
 ## Quick start
 
-Run `eve init` with `npx` before Eve is installed locally:
+`npx` runs `eve init` without installing Eve first:
 
 ```bash
 npx eve@latest init my-agent
 ```
 
-The command creates an npm-managed child directory, uses Eve's default model, installs dependencies, initializes Git, and starts the development server — the interactive [terminal UI](./guides/dev-tui) opens; type a message and watch the model loop run. Pass `--channel-web-nextjs` to add the Web Chat application; every app ships the built-in HTTP channel (`agent/channels/eve.ts`) regardless. Stop the server before editing the generated agent. The command does not create a Vercel project or deploy.
+The command:
 
-## Prerequisites
+- Creates an npm-managed child directory and uses Eve's default model
+- Installs dependencies and initializes Git
+- Starts the development server and opens the interactive [terminal UI](./guides/dev-tui)
 
-- Node `24.x`
-- npm (bundled with Node)
+Type a message and watch the model loop run. Pass `--channel-web-nextjs` to add the Web Chat application. Every app ships the built-in HTTP channel (`agent/channels/eve.ts`) regardless.
 
-You also need a model credential. Set the provider or gateway key your model string requires (gateway ids like `anthropic/claude-opus-4.8` route through the Vercel AI Gateway), or link a Vercel project that supplies one.
+`eve init` holds the terminal, so stop it with Ctrl+C to get your shell back before editing the generated agent. The command does not create a Vercel project or deploy.
 
-## Manual installation
+To add Eve to an existing project, run `eve init .` from a directory that already has a `package.json` and no `agent/` files yet. Eve adds the missing `eve`, `ai`, and `zod` dependencies without touching anything else the project owns. The Eve dependency and the Node engine come from the same release. Eve pins `engines.node` to the lowest major that release supports (for example `24.x`). It keeps an existing range only when every version that range allows stays within that major; otherwise it replaces the range and prints a warning.
 
-The quick start uses `eve init` for a guided scaffold. Run `npx eve@latest init <name>` from a parent directory, or create an empty directory first and run `eve init`, `eve init .`, or `eve init ./` inside it to run the same full scaffold there, including `package.json`. To add Eve to a non-empty existing app, use `npx eve@latest init .`: that add-agent flow requires a `package.json` and no existing `agent/` files yet, and Eve adds the missing `eve`, `ai`, and `zod` dependencies for you. Eve also ensures a compatible Node engine (for example `24.x`) is present; if an existing range is too narrow for the release, Eve updates it and warns you. Either way the final handoff runs the `eve dev` binary through the package manager, not the project’s own `dev` script.
+## Manual installation
 
-To wire Eve in by hand, declare a compatible Node runtime in `package.json`:
+To wire Eve into an existing app by hand instead of using `eve init`, first declare a compatible Node runtime in `package.json`:
 
 ```json
 {
@@ -36,10 +54,10 @@ To wire Eve in by hand, declare a compatible Node runtime in `package.json`:
 }
 ```
 
-Then install Eve and author the two files the runtime needs:
+Then install the dependencies and author the two files the runtime needs. The `eve init` scaffold adds `ai` and `zod` for you; by hand you install all three:
 
 ```bash
-npm install eve@latest
+npm install eve@latest ai zod
 ```
 
 ### Project files
@@ -62,18 +80,19 @@ export default defineAgent({
 });
 ```
 
+Before using real customer data, confirm the selected model provider's terms, routing path, and retention settings are appropriate for that data.
+
 Even at this size the agent can already do real work. The default harness gives it file, shell, web, and delegation tools out of the box. See [Default harness](./concepts/default-harness) for the full set and how to override or disable any of them.
 
 ### Add your first tool
 
-Whatever you name the file becomes the tool name the model sees. Create `agent/tools/get_weather.ts`:
+The filename becomes the tool name the model sees, and it must be snake_case ASCII. Create `agent/tools/get_weather.ts`:
 
 ```ts
 import { defineTool } from "eve/tools";
 import { z } from "zod";
 
-// The runtime tool name comes from the filename, so the model sees this as
-// `get_weather`. Tool filenames must be snake_case ASCII.
+// The model sees this tool as `get_weather`, from the filename.
 export default defineTool({
   description: "Get the current weather for a city.",
   inputSchema: z.object({ city: z.string().min(1) }),
@@ -87,29 +106,35 @@ Tools run in your app runtime with full `process.env`, not inside the [sandbox](
 
 ## Run the app
 
-From the app root:
+A scaffolded app has a `dev` script, so from the app root run:
 
 ```bash
 npm run dev
 ```
 
-Useful commands:
+The manual path authors no `dev` script. Run the binary through `npx` instead:
+
+```bash
+npx eve dev
+```
+
+Other commands the eve binary provides (prefix each with `npx`, or add a matching package.json script):
 
 - `eve info`: show the active routes and compiled artifacts
 - `eve build`: compile the agent into `.eve/` and build the host output
 - `eve start`: serve the built output
 - `eve dev`: start the local runtime and open the interactive [terminal UI](./guides/dev-tui)
 
-In the dev TUI, type a message and watch it happen in order: the `get_weather` call, its result, then the reply.
+In the dev TUI, type a message and watch it happen in order. First the `get_weather` call, then its result, then the reply.
 
-The same CLI can point at a deployment. `eve dev https://your-app.vercel.app` drives a deployed app, which is handy for preview and production smoke tests. See [Deployment](./guides/deployment).
+The same CLI can point at a deployment. `npx eve dev https://your-app.vercel.app` drives a deployed app, which is handy for preview and production smoke tests. See [Deployment](./guides/deployment).
 
 ## Send a message
 
 Every Eve app exposes the same stable HTTP API. Start a durable session:
 
 ```bash
-curl -X POST http://127.0.0.1:2000/eve/v1/session \
+curl -X POST http://127.0.0.1:3000/eve/v1/session \
   -H 'content-type: application/json' \
   -d '{"message":"What is the weather in Brooklyn?"}'
 ```
@@ -124,35 +149,49 @@ The response comes back with two things you'll reuse:
 Attach to the session stream:
 
 ```bash
-curl http://127.0.0.1:2000/eve/v1/session/<sessionId>/stream
+curl http://127.0.0.1:3000/eve/v1/session/<sessionId>/stream
 ```
 
-The stream is NDJSON, one lifecycle event per line. See [Sessions, runs & streaming](./concepts/sessions-runs-and-streaming) for the full list of events and what each one carries.
+The stream is NDJSON, served as `application/x-ndjson; charset=utf-8`. For this run you'll see a handful of lifecycle events:
+
+- `session.started`
+- `actions.requested` (the `get_weather` call)
+- `action.result`
+- `message.completed` (the reply)
+- `session.completed`
+
+`reasoning.appended` and `message.appended` are optional live-streaming events. Clients that can't surface incremental output can ignore them and rely on `reasoning.completed` and `message.completed`.
+
+Note: consider the privacy, confidentiality, and user-experience implications for displaying, storing, or transmitting reasoning events in your application.
+
+The full set covers more lifecycle, human-in-the-loop, and authorization events, including `input.requested`, `turn.failed`, `authorization.required`, and `authorization.completed`. See [Sessions, runs and streaming](./concepts/sessions-runs-and-streaming) for every event and its data shape.
 
 ## Send a follow-up message
 
 When the session is waiting for the next user message, post a follow-up with the token:
 
 ```bash
-curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId> \
+curl -X POST http://127.0.0.1:3000/eve/v1/session/<sessionId> \
   -H 'content-type: application/json' \
   -d '{"continuationToken":"<token>","message":"Now do Queens."}'
 ```
 
-See [Sessions, runs & streaming](./concepts/sessions-runs-and-streaming) for the full contract.
+See [Sessions, runs and streaming](./concepts/sessions-runs-and-streaming) for the full contract.
 
 ## Setting up with a coding agent
 
 If a coding agent (Claude Code, Cursor, and the like) is doing the setup, hand it this prompt:
 
-<CopyPrompt text="Set up an Eve agent for the user. Ask one question at a time. Use your prompt tools when available and do not guess. First ask what the agent should do. Then ask whether to create a new project or add it to an existing directory. For a new project, propose a name and ask the user to confirm it, then ask whether it should include Web Chat. Run `npx eve@latest init <target>`, adding `--channel-web-nextjs` if the user wants Web Chat. After scaffolding, read the relevant guide in `<project>/node_modules/eve/docs/`, replace the placeholder in `<project>/agent/instructions.md` with the purpose the user gave you, and do not start `eve dev` because it is interactive. Give the user the exact dev command printed by init.">
-  Set up an Eve agent by asking what it should do, whether to create a new project, scaffold the
-  current empty directory, or add Eve to an existing app, and whether a new project should include Web Chat, one question at a time.
-  Run `npx eve@latest init <target>`, read the bundled docs, fill in agent/instructions.md, and give
-  the user the dev command instead of starting the interactive server.
+<CopyPrompt text="Set up an Eve agent for the user. Eve is a filesystem-first TypeScript framework for durable agents, published as the npm package eve. Read its docs: once eve is installed they are bundled in the package at node_modules/eve/docs; before eve is installed, read the published Introduction and Getting Started pages. If the project has no Eve app, scaffold one with `npx eve@latest init <name>`; add `--channel-web-nextjs` only when the user wants Web Chat. The init command installs dependencies, initializes Git, and starts the dev server, so run it in a controllable process and stop it with Ctrl+C before editing. To add Eve to an existing app, run `eve init .`, or install the dependencies by hand with `npm install eve@latest ai zod` (init adds ai and zod; the by-hand path needs all three). Make sure agent/agent.ts and agent/instructions.md exist, then add a first typed tool at agent/tools/get_weather.ts using defineTool from eve/tools with a Zod inputSchema and an inline execute. Start the dev server again, then exercise the HTTP API: create a session with POST /eve/v1/session, attach to GET /eve/v1/session/:id/stream, and send a follow-up with the returned continuationToken. Verify with the project's typecheck, adapt model and provider choices to the project, and do not commit unless the user asks.">
+  Set up an Eve agent: read the Eve docs (bundled at node_modules/eve/docs once eve is
+  installed), scaffold with `npx eve@latest init <name>` (or `npm install eve@latest ai zod` in an existing app), add
+  a typed tool at agent/tools/get_weather.ts, run it with `npm run dev`, then create a session, stream
+  it, and send a follow-up.
 </CopyPrompt>
 
-Once `eve` is installed, the complete docs ship at `node_modules/eve/docs/`, so the agent can read them locally instead of fetching anything.
+Once `eve` is a dependency, the package bundles the full docs, so the agent can read them locally at `node_modules/eve/docs/` without fetching anything.
+
+To add a platform channel after setup, run `eve channels add slack` from an interactive terminal. The init flags are covered in [Quick start](#quick-start).
 
 ## What to read next
 
@@ -160,5 +199,5 @@ Once `eve` is installed, the complete docs ship at `node_modules/eve/docs/`, so
 - [Channels](./channels/overview): reach the agent from Slack, Discord, or a web UI
 - [Frontend](./guides/frontend/overview): browser chat with `useEveAgent`
 - [TypeScript SDK](./guides/client/overview): call the agent from scripts or server-side code
-- [Sessions, runs & streaming](./concepts/sessions-runs-and-streaming): the durable session model
+- [Sessions, runs and streaming](./concepts/sessions-runs-and-streaming): the durable session model
 - [Build an agent](./tutorial/first-agent): the full end-to-end walkthrough

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

@@ -3,21 +3,23 @@ title: "Auth & Route Protection"
 description: "Secure your agent's HTTP routes with an ordered auth walk, verifier helpers, and connection OAuth via Vercel Connect."
 ---
 
-Eve has two separate auth concerns, and this page covers both:
+Eve has two independent auth systems:
 
-- **Route auth** (inbound): who is allowed to reach your agent's HTTP routes. It runs at the channel layer.
-- **Tool and connection auth** (outbound): how your agent signs in to an external service it calls, like an OAuth MCP server.
+- **Route auth** (inbound) decides who can reach your agent's HTTP routes. It runs at the channel layer, gating the request before any model work runs.
+- **Tool and connection auth** (outbound) is how your agent signs in to an external service it calls, like an OAuth MCP server. It happens later, when a tool or connection actually reaches out.
 
-They are independent. Route auth gates the request before any model work runs; tool and connection auth happens later, when a tool or connection actually reaches out. Start with route auth.
+Start with route auth.
 
 ## Route auth
 
-Route auth runs at the channel layer. The 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 three routes:
 
 - `POST /eve/v1/session`
 - `POST /eve/v1/session/:sessionId`
 - `GET /eve/v1/session/:sessionId/stream`
 
+These routes are protected by the channel's auth policy. Eve fails closed by default: production browser traffic is rejected unless you configure an authenticator that accepts it, and anonymous access requires an explicit `none()`.
+
 `GET /eve/v1/health` is always public and skips the walk entirely, so load balancers and uptime monitors can probe it without credentials.
 
 ```ts title="agent/channels/eve.ts"
@@ -64,7 +66,7 @@ export default eveChannel({
 
 Put your own providers ahead of the catch-all helpers. Any entry that doesn't recognize the caller returns `null`, and the walk moves on.
 
-Want a precise status instead of a skip? Throw:
+To reject with a precise status instead of skipping, throw:
 
 ```ts
 import { ForbiddenError, UnauthenticatedError } from "eve/channels/auth";
@@ -76,7 +78,7 @@ throw new UnauthenticatedError({
 throw new ForbiddenError({ message: "Not allowed on this workspace." }); // 403
 ```
 
-Any other thrown error follows the normal channel failure path. Building a custom channel on `defineChannel`? Call `routeAuth(request, auth)` from `eve/channels/auth` to reuse the same walk semantics.
+Any other thrown error follows the normal channel failure path. When building a custom channel on `defineChannel`, call `routeAuth(request, auth)` from `eve/channels/auth` to reuse the same walk semantics.
 
 ## Verifier helpers
 
@@ -92,6 +94,8 @@ Any other thrown error follows the normal channel failure path. Building a custo
 | `jwtEcdsa(...)`  | You verify asymmetric JWTs minted by another system.                      |
 | `oidc(...)`      | You want Eve to verify OIDC-issued tokens from an arbitrary issuer.       |
 
+Exercise caution for agents that process non-public, sensitive, regulated, or production data unless you have implemented other access controls.
+
 ### `localDev()`
 
 Authenticates a synthetic `local-dev` principal, but only when the inbound request is addressed to a loopback hostname (`localhost`, `*.localhost`, `127.0.0.0/8`, or `::1`). The check keys off the request URL's hostname rather than the bare `process.env.VERCEL` flag, and that's deliberate: a deployment outside Vercel leaves `VERCEL` unset, so sniffing that flag alone would wave through all public traffic. There's one process-level exception. `vercel dev`, detected by `VERCEL=1` and `VERCEL_ENV=development` together, opens the local dev server even when it serves over a non-loopback host. Every other non-loopback request returns `null` and falls through.
@@ -106,7 +110,7 @@ Auth fails closed: routes reject unauthenticated traffic by default, and the OID
 
 #### `subjects` patterns and `vercelSubject(...)`
 
-Each `subjects` entry is matched against the token's `sub` claim, which Vercel shapes as `owner:<team>:project:<name>:environment:<env>`. Hand-writing that string is a footgun: a typo silently rejects every caller, and an over-broad `*` wildcard silently lets unrelated ones in. Build the pattern with `vercelSubject(...)` instead. It rejects malformed input at construction time and forces an explicit `environment` (defaulting to `"production"`):
+Each `subjects` entry is matched against the token's `sub` claim, which Vercel shapes as `owner:<team>:project:<name>:environment:<env>`. Hand-writing that string is a footgun: a typo silently rejects every caller, and an over-broad `*` wildcard silently lets unrelated ones in. Build the pattern with `vercelSubject(...)` instead. It rejects malformed input at construction time, and defaults `environment` to `"production"` when you omit it, so an unspecified environment cannot silently accept preview or development tokens:
 
 ```ts
 import { vercelOidc, vercelSubject } from "eve/channels/auth";
@@ -205,14 +209,16 @@ Inside runtime code, `ctx.session.auth` carries the result of the channel's rout
 
 - `auth.current`: the caller on the active inbound turn.
 - `auth.initiator`: the caller that started the durable session.
-- A follow-up message updates `auth.current` but leaves `auth.initiator` alone. So when a different caller follows up on the same session, `auth.current` tracks the new caller for that turn while `auth.initiator` stays pinned to whoever started it.
+- A follow-up message updates `auth.current` but leaves `auth.initiator` alone. When a different caller follows up on the same session, `auth.current` tracks the new caller for that turn while `auth.initiator` stays pinned to whoever started it.
 - Both are `null` only on internal runtime paths (subagents, for instance) that never went through an authored route. HTTP traffic always populates `auth.current`, since the walk either accepts with a `SessionAuthContext` or returns `401`.
 
-Use the principal on `auth.current` (or `auth.initiator`) to scope tools, resolve [dynamic capabilities](./dynamic-capabilities) per principal, or enforce tenant boundaries. There's no second per-session ownership ACL stacked on top of route auth: access is decided at the HTTP boundary, and the durable session just carries the caller snapshot forward into your runtime code.
+Use the principal on `auth.current` (or `auth.initiator`) to scope tools, resolve [dynamic capabilities](./dynamic-capabilities) per principal, or enforce tenant boundaries. There's no second per-session ownership ACL stacked on top of route auth. Access is decided at the HTTP boundary, and the durable session carries the caller snapshot forward into your runtime code.
+
+Route auth does not enforce session ownership. If multiple users or tenants can reach the same route, you must implement the per-user, per-tenant, or per-session authorization your application requires.
 
 ## Tool and connection auth
 
-Route auth decides who reaches your agent. Tool and connection auth is the flip side: how your agent reaches an external service that wants an interactive sign-in, like an OAuth MCP server. Both a connection and an individual tool can declare an `auth` strategy; Eve drives the sign-in, caches the token per step, and re-runs the call once the caller authorizes.
+Tool and connection auth is how your agent reaches an external service that wants an interactive sign-in, like an OAuth MCP server. Both a connection and an individual tool can declare an `auth` strategy; Eve drives the sign-in, caches the token per step, and re-runs the call once the caller authorizes.
 
 ### On a connection
 
@@ -263,7 +269,7 @@ Declaring `auth` adds two accessors to the tool's `ctx`:
 
 Throw `ConnectionAuthorizationRequiredError` anywhere in `execute` (directly, via `requireAuth()`, or implicitly from `getToken()`) and you trigger the consent flow, keyed by the tool's name. Calling either accessor on a tool that does not declare `auth` throws.
 
-By default the sign-in affordance title-cases the tool's path-derived name — a tool file named `sfdc_lookup.ts` renders "Sign in with Sfdc_lookup". Set `displayName` on the `auth` definition to control what users see instead: `auth: { ...connect("sfdc"), displayName: "Salesforce" }`. It is presentation-only; the tool's name still keys the authorization scope, token cache, and callback URL, and a definition-level `displayName` wins over one the strategy stamps on the challenge.
+By default the sign-in affordance title-cases the tool's path-derived name, so a tool file named `sfdc_lookup.ts` renders "Sign in with Sfdc_lookup". Set `displayName` on the `auth` definition to control what users see instead, for example `auth: { ...connect("sfdc"), displayName: "Salesforce" }`. It is presentation-only. The tool's name still keys the authorization scope, token cache, and callback URL, and a definition-level `displayName` wins over one the strategy stamps on the challenge.
 
 ## What to read next
 

package/docs/guides/client/continuations.mdx

@@ -3,12 +3,12 @@ title: "Continuations"
 description: "Persist and resume Eve client sessions with continuation tokens, session IDs, and stream cursors."
 ---
 
-Eve hands back two different handles, and mixing them up is the most common mistake. The TypeScript client tracks both for you:
+Every Eve client turn returns two handles, and mixing them up is a common mistake. The TypeScript client tracks both for you:
 
 - `continuationToken`: the resume handle. Use it to send the next user turn.
 - `sessionId`: the stream-and-inspect handle. Use it to attach to event history.
 
-`ClientSession` also tracks `streamIndex`, the count of events already consumed. Together those fields make a `SessionState`.
+`ClientSession` also tracks `streamIndex`, the count of events already consumed. Together these three fields make a `SessionState`.
 
 ## Read and persist state
 
@@ -75,7 +75,7 @@ if (result.status === "completed") {
 }
 ```
 
-This matches the runtime contract: only waiting sessions can accept the next user input.
+This matches the runtime contract, where only waiting sessions can accept the next user input.
 
 ## Multiple sessions
 
@@ -99,7 +99,7 @@ The shared `Client` only owns host, auth, headers, and reconnect settings. Conve
 
 ## Reconnect an existing stream
 
-If a session already has a `sessionId`, `stream()` attaches to that stream from the saved cursor:
+When a session already has a `sessionId`, `session.stream()` reattaches to its stream from the saved cursor. Resuming a saved `SessionState` after a restart is the common reason to do this:
 
 ```ts
 const session = client.session(savedState);
@@ -109,15 +109,7 @@ for await (const event of session.stream()) {
 }
 ```
 
-Override the cursor when you want to replay from an earlier point:
-
-```ts
-for await (const event of session.stream({ startIndex: 0 })) {
-  console.log(event.type);
-}
-```
-
-`stream()` is for attaching to an existing run. To send new user input, use `send()`.
+`stream()` attaches to an existing run; to send new user input, use `send()`. For overriding the cursor with `startIndex` and the full reconnection model, see [Streaming](./streaming#open-a-stream-manually).
 
 ## What to read next
 

package/docs/guides/client/messages.mdx

@@ -12,7 +12,7 @@ Pass a string to `send()` for plain text:
 ```ts
 import { Client } from "eve/client";
 
-const client = new Client({ host: "http://127.0.0.1:2000" });
+const client = new Client({ host: "http://127.0.0.1:3000" });
 const session = client.session();
 
 const response = await session.send("What is the weather in Brooklyn?");
@@ -34,7 +34,7 @@ console.log(result.status, result.message);
 | `sessionId` | Session ID for streaming and inspection.                                       |
 | `data`      | Structured output when the turn requested an [output schema](./output-schema). |
 
-Failed runtime turns don't throw just because the stream includes `session.failed`. They return `status: "failed"`. Transport and route errors throw `ClientError`.
+When the stream includes `session.failed`, the turn returns `status: "failed"` rather than throwing. Transport and route errors throw `ClientError`.
 
 ## Send a full turn payload
 

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

@@ -3,7 +3,7 @@ title: "Output Schema"
 description: "Request structured results from Eve client turns and read typed data from MessageResult."
 ---
 
-Pass `outputSchema` on a client turn when the caller needs structured data instead of only assistant text. The runtime makes the model satisfy the schema before the turn settles and emits the final payload as `result.completed`.
+Pass `outputSchema` on a client turn when the caller needs structured data instead of only assistant text. The runtime makes the model satisfy the schema before the turn settles, then emits the final payload as `result.completed`.
 
 ## JSON Schema
 
@@ -26,7 +26,7 @@ const outputSchema = {
   required: ["title", "count"],
 } as const;
 
-const client = new Client({ host: "http://127.0.0.1:2000" });
+const client = new Client({ host: "http://127.0.0.1:3000" });
 const session = client.session();
 
 const response = await session.send<Summary>({

package/docs/guides/client/overview.mdx

@@ -1,9 +1,9 @@
 ---
-title: "Overview"
+title: "TypeScript SDK Overview"
 description: "Call an Eve agent from TypeScript with Client, sessions, auth, and health checks."
 ---
 
-The `eve/client` entrypoint is the typed client for Eve's default HTTP API. Use it from scripts, server-to-server integrations, tests, evals, backend jobs, or custom UIs that want the session protocol without hand-writing the POST and NDJSON stream loop.
+The `eve/client` entrypoint is the typed client for Eve's default HTTP API. Use it from scripts, server-to-server integrations, tests, evals, backend jobs, or custom UIs that want the session protocol without hand-writing the POST and NDJSON (newline-delimited JSON) stream loop.
 
 For browser chat UIs, start with [`useEveAgent`](../frontend/overview). For wire-level details, read [Sessions, runs & streaming](../../concepts/sessions-runs-and-streaming). The client sits between those two: lower level than the frontend hooks, higher level than raw HTTP.
 
@@ -15,11 +15,11 @@ A `Client` binds one host, auth policy, header policy, and stream reconnection b
 import { Client } from "eve/client";
 
 const client = new Client({
-  host: "http://127.0.0.1:2000",
+  host: "http://127.0.0.1:3000",
 });
 ```
 
-`host` is the origin where the Eve routes are mounted. In a same-origin browser integration this is often `""`, but scripts and backend services usually name the full URL.
+`host` is the origin where the Eve routes are mounted. In a same-origin browser integration this is often `""`; scripts and backend services usually name the full URL.
 
 ## Check health
 

package/docs/guides/client/streaming.mdx

@@ -3,7 +3,7 @@ title: "Streaming"
 description: "Consume Eve client stream events live, reconnect by event index, and aggregate turn results."
 ---
 
-Every send starts with a POST and then reads the session's NDJSON event stream. `MessageResponse` gives you two ways to consume that stream: aggregate it with `result()` or iterate it live.
+Every `ClientSession.send()` call posts the turn, then reads the session's NDJSON (newline-delimited JSON) event stream. `MessageResponse` gives you two ways to consume that stream, aggregating it with `result()` or iterating it live.
 
 ## Aggregate a turn
 
@@ -42,7 +42,7 @@ for await (const event of response) {
 }
 ```
 
-`message.appended` and `reasoning.appended` are incremental events. The completed forms, `message.completed` and `reasoning.completed`, are the compatibility path for clients that don't render deltas.
+`message.appended` and `reasoning.appended` are incremental delta events. Their completed forms, `message.completed` and `reasoning.completed`, are the compatibility path for clients that don't render deltas.
 
 ## Handle event types
 
@@ -117,21 +117,22 @@ for await (const event of session.stream({ startIndex: 0 })) {
 
 ## Abort a request
 
-Pass an `AbortSignal` to cancel the POST or stream:
+Pass an `AbortSignal` to cancel the POST or stream. Arm the timeout before awaiting `send()` so it covers the POST as well as the stream:
 
 ```ts
 const controller = new AbortController();
+const timeout = setTimeout(() => controller.abort(), 10_000);
 
 const response = await session.send({
   message: "Run a long analysis.",
   signal: controller.signal,
 });
 
-setTimeout(() => controller.abort(), 10_000);
-
 for await (const event of response) {
   console.log(event.type);
 }
+
+clearTimeout(timeout);
 ```
 
 Once a response is aborted, create a new send for the next turn. Don't reuse the same `MessageResponse`.

package/docs/guides/deployment.md

@@ -1,9 +1,9 @@
 ---
 title: "Deployment"
-description: "A production checklist for shipping an Eve agent on Vercel: build output, env/secrets, sandbox backend, prewarm, auth, deploy, and verify."
+description: "A production checklist for shipping an Eve agent on Vercel, covering build output, env and secrets, sandbox backend, prewarm, auth, deploy, and verify."
 ---
 
-You've got an agent running under `eve dev` and now you want it live. Eve runs the same way locally and on Vercel, so the move to production is mostly mechanical. Work through this checklist in order.
+Eve runs the same way locally and on Vercel, so taking an agent from `eve dev` to production is mostly mechanical. Work through this checklist in order.
 
 ## 1. Build
 
@@ -13,16 +13,16 @@ You've got an agent running under `eve dev` and now you want it live. Eve runs t
 eve build
 ```
 
-On hosted Vercel builds you get the Vercel output bundle under `.vercel/output`. You also get Eve's compiled framework artifacts under `.eve/`: the discovery manifest, compiled manifest, diagnostics, and module map. Crack those open to see exactly which authored surface a deployment will load. For the artifact guide and what to do when `eve build` fails, see [instrumentation.ts](./instrumentation).
+When `VERCEL` is set (every hosted Vercel build sets it), `eve build` writes the Vercel output bundle under `.vercel/output`. A plain local `eve build` skips that bundle. Either way you get Eve's compiled framework artifacts under `.eve/`, including the discovery manifest, compiled manifest, diagnostics, and module map. Open those to see which authored surface a deployment will load. For the artifact guide and what to do when `eve build` fails, see [Observability](./instrumentation).
 
-## 2. Environment variables & secrets
+## 2. Environment variables and secrets
 
 Set these in your Vercel project's environment variables, never in source or compiled artifacts:
 
-- **A model credential.** Easiest is the Vercel AI Gateway: link a Vercel project and gateway model ids like `anthropic/claude-opus-4.8` authenticate through Vercel OIDC, with no provider keys to manage. To call a provider directly instead, set its key (for example `OPENAI_API_KEY`).
-- **Route-auth secrets**, for example `ROUTE_AUTH_BASIC_PASSWORD` and any JWT/OIDC signing keys referenced by your channel's `auth` (see [Auth & route protection](./auth-and-route-protection)).
+- **A model credential.** The lowest-setup option is the Vercel AI Gateway. Link a Vercel project, and gateway model ids like `anthropic/claude-opus-4.8` authenticate through Vercel OIDC, with no provider keys to manage. To call a provider directly instead, set its key (for example `OPENAI_API_KEY`).
+- **Route-auth secrets**, for example `ROUTE_AUTH_BASIC_PASSWORD` and any JWT/OIDC signing keys referenced by your channel's `auth` (see [Auth and route protection](./auth-and-route-protection)).
 
-Route-auth secrets never get serialized into the compiled discovery or module-map artifacts. The runtime re-materializes them from the authored channel definition instead. One caveat: if your deployment sits behind Vercel preview protection and you want to drive it with `eve dev`, set `VERCEL_AUTOMATION_BYPASS_SECRET` locally before launching.
+Route-auth secrets are never serialized into the compiled discovery or module-map artifacts. The runtime re-materializes them from the authored channel definition instead. If your deployment sits behind Vercel preview protection and you want to drive it with `eve dev`, set `VERCEL_AUTOMATION_BYPASS_SECRET` locally before launching.
 
 ## 3. Sandbox backend
 
@@ -41,7 +41,7 @@ Leave `backend` off and Eve falls back to `defaultBackend()`, which picks the Ve
 
 ## 4. Build-time sandbox prewarm
 
-During hosted builds, Eve prewarms reusable Vercel sandbox templates so the first session doesn't eat the cold-start cost. A few things worth knowing:
+During hosted builds, Eve prewarms reusable Vercel sandbox templates so the first session doesn't pay the cold-start cost:
 
 - Prewarm runs only when both `VERCEL` and `VERCEL_DEPLOYMENT_ID` are present.
 - A sandbox with no `bootstrap()` and no workspace seed files gets skipped.
@@ -53,7 +53,7 @@ During hosted builds, Eve prewarms reusable Vercel sandbox templates so the firs
 
 ## 5. Auth
 
-Swap any scaffolded `placeholderAuth()` for your real policy before the first production browser request hits the app. Both the framework default and the placeholder reject production browser traffic, so an unconfigured app fails closed rather than serving open routes. See [Auth & route protection](./auth-and-route-protection) for the full walk and the fail-closed guarantee.
+Swap any scaffolded `placeholderAuth()` for your real policy before the first production browser request hits the app. Both the framework default and the placeholder reject production browser traffic, so an unconfigured app fails closed rather than serving open routes. See [Auth and route protection](./auth-and-route-protection) for the ordered auth walk and the fail-closed guarantee.
 
 ## 6. Deploy on Vercel
 
@@ -65,10 +65,6 @@ vercel deploy
 
 The deployed app serves the same stable health, session, and stream routes you've been hitting locally.
 
-## How Eve sits behind a host framework
-
-You can deploy an Eve app on its own, or mount it inside a host web framework that owns the rest of the site (marketing pages, a dashboard, other API routes). The host keeps its own routing and serves Eve's routes through the framework integration. For mounting Eve in Next.js (`withEve`) and the other supported frameworks, see [Frontend](./frontend/nextjs). Either way, the agent surface and HTTP contract are identical.
-
 ## 7. Verify the deployment
 
 Smoke-test the live routes. Health first:
@@ -85,13 +81,13 @@ curl -X POST https://<your-app>/eve/v1/session \
   -d '{"message":"Hello from production"}'
 ```
 
-Attach to the returned stream:
+The POST returns a JSON body whose `sessionId` identifies the new session. Attach to that session's stream with it:
 
 ```bash
 curl https://<your-app>/eve/v1/session/<sessionId>/stream
 ```
 
-Or poke at the deployment interactively with the dev TUI, which is handy for preview and production smoke tests:
+Or drive the deployment interactively with the dev TUI, which is handy for preview and production smoke tests:
 
 ```bash
 eve dev https://<your-app>
@@ -103,20 +99,26 @@ eve dev https://<your-app>
 
 Once the agent is deployed, the platform auto-detects `eve` as the framework and surfaces an **Agent Runs** tab under your project's **Observability** view in the Vercel dashboard. From there you can browse sessions and drill into each conversation's trace.
 
-> The Agent Runs tab is currently gated: your Vercel team needs the feature enabled before it appears. If you don't see it, reach out to your Vercel contact to get your team enabled.
+> The Agent Runs tab is currently gated. Your Vercel team needs the feature enabled before it appears. If you don't see it, reach out to your Vercel contact to get your team enabled.
+
+Agent Runs is separate from the OpenTelemetry exporters configured in [Observability](./instrumentation). Those still work and are the recommended path if you want spans in Braintrust, Datadog, or another third-party backend.
+
+## How Eve sits behind a host framework
 
-Agent Runs is separate from the OpenTelemetry exporters configured in [`instrumentation.ts`](./instrumentation). Those still work and are the recommended path if you want spans in Braintrust, Datadog, or another third-party backend.
+You can deploy an Eve app on its own, or mount it inside a host web framework that owns the rest of the site (marketing pages, a dashboard, other API routes). The host keeps its own routing and serves Eve's routes through the framework integration. Either way, the agent surface and HTTP contract are identical. For mounting Eve in Next.js (`withEve`) and the other supported frameworks, see [Frontend](./frontend/nextjs).
 
 ## Checklist
 
-- [ ] `eve build` succeeds and writes `.vercel/output`.
+- [ ] `eve build` succeeds, and writes `.vercel/output` when `VERCEL` is set.
 - [ ] Provider keys and route-auth secrets are set in Vercel env vars.
 - [ ] The sandbox backend matches the environment (`vercel()` or `defaultBackend()`).
 - [ ] Build-time prewarm reused or built templates without failing.
 - [ ] `placeholderAuth()` is replaced with your real policy.
+- [ ] `vercel deploy` succeeds.
+- [ ] The health, session, and stream routes respond on the deployment URL.
 
 ## What to read next
 
-- [Auth & route protection](./auth-and-route-protection): secure the routes you deployed
-- [instrumentation.ts](./instrumentation): tracing, run tags, and the error catalog
+- [Auth and route protection](./auth-and-route-protection): secure the routes you deployed
+- [Observability](./instrumentation): tracing, run tags, and common failures
 - [Sandbox](../sandbox): backends, lifecycle, and credential brokering