eve 0.34.0 → 0.36.0

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.6-terra --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/messages.mdx

@@ -96,7 +96,9 @@ await response.result();
 
 The stream confirms the turn with `message.received`. Its `data.message` remains the flattened
 summary for compatibility, and `data.parts` contains structured text and file metadata for clients
-that render attachments. File parts never include raw bytes or internal sandbox paths.
+that render attachments. File parts never include raw bytes or internal sandbox paths. See [Inbound
+attachments](../../sandbox#inbound-attachments) for how eve stages byte-backed files in the session
+sandbox and prepares them for each model call.
 
 ## Answer human input requests
 

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

package/docs/guides/deployment/overview.md

@@ -34,7 +34,7 @@ Keep credentials in your deployment environment or secret manager. Don’t inclu
 
 Your model configuration determines the required credential. A string model ID uses the [Vercel AI Gateway](https://vercel.com/docs/ai-gateway) and requires Vercel project OpenID Connect (OIDC) or `AI_GATEWAY_API_KEY`. A provider-authored model uses that provider’s package and API key. See [Agent configuration](../../agent-config#set-the-model) for both forms.
 
-Configure production route authentication separately from model access. The default policy rejects browser traffic in production. See [Auth and route protection](../auth-and-route-protection) for the available policies and secret requirements.
+Configure production route authentication separately from model access. The default policy rejects browser traffic in production. See [Authentication](../auth-and-route-protection) for the available policies and secret requirements.
 
 ## Verify the deployment
 

package/docs/guides/deployment/self-hosting.md

@@ -1,5 +1,5 @@
 ---
-title: "Self-host eve"
+title: "Self-Host eve"
 description: "Run an eve agent as a Node service with your own workflow storage, sandbox backend, and routing."
 ---
 
@@ -22,7 +22,7 @@ Run this process under the same process manager or container platform you use fo
 
 Set `AI_GATEWAY_API_KEY` to use a string model ID through the Vercel AI Gateway from a non-Vercel host. To call a provider directly, install its [AI SDK provider package](https://ai-sdk.dev/docs/foundations/providers-and-models). Then pass its model object in `agent.ts` and set its API key. See [Agent configuration](../../agent-config#set-the-model) for examples.
 
-Don’t rely on `vercelOidc()` as the only production authenticator outside Vercel. Configure Basic auth, JSON Web Token (JWT) verification, generic OpenID Connect (OIDC), or a custom verifier that your host can validate. See [Auth and route protection](../auth-and-route-protection).
+Don’t rely on `vercelOidc()` as the only production authenticator outside Vercel. Configure Basic auth, JSON Web Token (JWT) verification, generic OpenID Connect (OIDC), or a custom verifier that your host can validate. See [Authentication](../auth-and-route-protection).
 
 ## Persist workflow state
 
@@ -83,6 +83,6 @@ eve dev https://your_agent.example.com
 
 Use these guides to secure and observe the deployed agent:
 
-- [Auth and route protection](../auth-and-route-protection): configure the host’s route policy
+- [Authentication](../auth-and-route-protection): configure the host’s route policy
 - [Observability](../instrumentation): export traces and diagnose runtime failures
 - [Sandbox](../../sandbox): select and secure a sandbox backend

package/docs/guides/deployment/vercel.mdx

@@ -85,6 +85,6 @@ The Agent Runs tab requires enablement for your Vercel team. Contact your Vercel
 
 Use these guides to secure and observe the deployed agent:
 
-- [Auth and route protection](../auth-and-route-protection): configure who can call the deployed agent
+- [Authentication](../auth-and-route-protection): configure who can call the deployed agent
 - [Observability](../instrumentation): export traces and diagnose runtime failures
 - [Sandbox](../../sandbox): configure resources, isolation, and network access

package/docs/guides/dev-tui.md

@@ -1,5 +1,5 @@
 ---
-title: "Dev TUI"
+title: "Terminal UI"
 description: "Use eve locally or connect to a deployed agent from an interactive terminal UI."
 ---
 
@@ -57,23 +57,13 @@ Use `/traces` to inspect traces recorded during local development. See [Instrume
 
 ## Display options
 
-Use `eve dev` flags to control how much detail the UI renders:
+Use `eve dev` flags to control tool calls, reasoning, subagents, connection authorization, response statistics, context usage, and logs:
 
 ```bash
 eve dev --tools full --reasoning collapsed --logs all
 ```
 
-| Flag                         | Values                                          | Description                                        |
-| ---------------------------- | ----------------------------------------------- | -------------------------------------------------- |
-| `--tools`                    | `full`, `collapsed`, `auto-collapsed`, `hidden` | Tool-call display.                                 |
-| `--reasoning`                | `full`, `collapsed`, `auto-collapsed`, `hidden` | Reasoning display.                                 |
-| `--subagents`                | `full`, `collapsed`, `auto-collapsed`, `hidden` | Subagent display.                                  |
-| `--connection-auth`          | `full`, `collapsed`, `auto-collapsed`, `hidden` | Connection-authorization display.                  |
-| `--assistant-response-stats` | `tokens`, `tokensPerSecond`                     | Assistant response statistic.                      |
-| `--context-size`             | Token count                                     | Model context-window size for the usage indicator. |
-| `--logs`                     | `all`, `stderr`, `sandbox`, `none`              | Initial log display mode.                          |
-
-Use `--host` and `--port` to bind the local server, or `--no-ui` to run without the terminal UI. See the [CLI reference](../reference/cli#eve-dev) for all options.
+Use `--host` and `--port` to bind the local server, or `--no-ui` to run without the terminal UI. See the [`eve dev` CLI reference](../reference/cli#eve-dev) for the complete option list, accepted values, and defaults.
 
 ## Connect to a deployment
 

package/docs/guides/dynamic-capabilities.md

@@ -21,6 +21,44 @@ resolver first selects a model, eve normalizes the selection and resolves any
 omitted context-window metadata from the AI Gateway catalog. Dynamic tools,
 skills, instructions, and subagents may return `null` to omit a capability.
 
+### Route image inputs to a vision model
+
+Use `step.started` when model choice depends on the current messages. This
+keeps GLM for text and switches to Gemini Flash when user history contains an
+image:
+
+```ts title="agent/agent.ts"
+import { defineAgent, defineDynamic } from "eve";
+
+export default defineAgent({
+  model: defineDynamic({
+    events: {
+      "step.started": (_event, ctx) => {
+        const hasImage = ctx.messages.some(
+          (message) =>
+            message.role === "user" &&
+            Array.isArray(message.content) &&
+            message.content.some(
+              (part) =>
+                part.type === "image" ||
+                (part.type === "file" &&
+                  (part.mediaType === "image" || part.mediaType.startsWith("image/"))),
+            ),
+        );
+
+        return hasImage ? "google/gemini-3.5-flash" : "zai/glm-5.2";
+      },
+    },
+  }),
+});
+```
+
+eve stages byte-backed `file` parts under `/workspace/attachments` before
+`step.started`, but keeps their media type in `ctx.messages`. When an image
+reaches the provider, vision models can process it and non-vision models reject
+it. eve does not reroute automatically. See [Inbound
+attachments](../sandbox#inbound-attachments).
+
 ## Dynamic subagents
 
 Wrap a declared subagent's own `agent.ts` in `defineDynamic` when its
@@ -212,7 +250,7 @@ Skills follow the same naming rule as tools: a single `defineSkill(...)` is name
 
 ## Dynamic instructions
 
-A dynamic instructions file resolves the per-session system prompt the same way, returning `defineInstructions(...)` built from the principal, tenant, or external data:
+A dynamic instructions file returns `defineInstructions({ content, role? })` built from the principal, tenant, channel, or external data. Omit `role` for system context:
 
 ```ts title="agent/instructions/persona.ts"
 import { defineDynamic, defineInstructions } from "eve/instructions";
@@ -222,14 +260,36 @@ export default defineDynamic({
     "session.started": (_event, ctx) => {
       const plan = ctx.session.auth.current?.attributes.plan ?? "free";
       return defineInstructions({
-        markdown: `The caller is on the ${plan} plan. Match the depth of your answers to it.`,
+        content: `The caller is on the ${plan} plan. Match the depth of your answers to it.`,
       });
     },
   },
 });
 ```
 
-Both resolve before the prompt is assembled, so the model sees the right instructions and skill set for whoever is calling, without that context reaching anyone else.
+Use `role: "user"` when the resolved value is application or user context that should become part of durable history:
+
+```ts title="agent/instructions/brief.ts"
+import { defineDynamic, defineInstructions } from "eve/instructions";
+import { loadBrief } from "../lib/briefs";
+
+export default defineDynamic({
+  events: {
+    "turn.started": async (_event, ctx) => {
+      const brief = await loadBrief(ctx.session.auth.current);
+      return brief ? defineInstructions({ content: brief, role: "user" }) : null;
+    },
+  },
+});
+```
+
+Instruction resolvers support `session.started` and `turn.started` only. A system result lives in that scope and stays outside history. A user result is appended to history at the lifecycle boundary, with session results before turn results and both before the current delivery. There is no automatic deduplication: returning the same user content on a later turn intentionally appends another message.
+
+Resolver snapshots reflect that order. At `session.started`, `ctx.messages` includes static user-role instructions. At `turn.started`, it also includes user-role results from `session.started`. These augmented snapshots are specific to instruction resolvers; tools, skills, models, and subagents keep their existing message snapshots.
+
+Returning `null` or blank content contributes nothing. A throwing or invalid session resolver leaves any wider valid system selection in place. Every turn starts with fresh turn-scoped system instructions, so a failed or empty turn result cannot leak the previous turn's value. Completed lifecycle steps are replay-safe: parking, resuming, or replaying them does not duplicate user-role messages.
+
+Dynamic system content that changes frequently can reduce provider prompt-cache reuse. Prefer session scope for stable values and use turn scope only when the context must be refreshed. Cache behavior remains provider-specific.
 
 ## What to read next
 
@@ -237,4 +297,4 @@ Both resolve before the prompt is assembled, so the model sees the right instruc
 - The static tool basics this builds on → [Tools](../tools)
 - The built-in tools and how to override them → [Default harness](../concepts/default-harness)
 - Authenticate a tool or connection to an external service → [Auth & route protection](./auth-and-route-protection)
-- Durable per-session memory for resolvers to read → [State](./state)
+- Durable per-session memory for resolvers to read → [State](../concepts/state)

package/docs/guides/frontend/meta.json

@@ -1,4 +1,5 @@
 {
-  "title": "Frontend",
+  "title": "Frontend Frameworks",
+  "defaultOpen": false,
   "pages": ["overview", "nextjs", "nuxt", "sveltekit", "use-eve-agent-vue", "use-eve-agent-svelte"]
 }

package/docs/guides/frontend/nextjs.mdx

@@ -88,16 +88,7 @@ const agent = useEveAgent({
 });
 ```
 
-The default eve channel is fail-closed. With no `agent/channels/eve.ts` authored, eve registers `eveChannel({ auth: [vercelOidc(), localDev(), placeholderAuth()] })`: `vercelOidc()` gets the first chance to resolve a Vercel caller, `localDev()` authenticates while the process is an `eve dev` or `vercel dev` server, and everything else gets a `401`. To run your app's own auth policy, add `agent/channels/eve.ts`:
-
-```ts title="agent/channels/eve.ts"
-import { eveChannel } from "eve/channels/eve";
-import { localDev, vercelOidc } from "eve/channels/auth";
-
-export default eveChannel({ auth: [vercelOidc(), localDev()] });
-```
-
-For a public demo, use `none()` (also from `eve/channels/auth`) to skip authentication. See [Channels](../../channels/overview) and [Auth & route protection](../auth-and-route-protection).
+The browser still needs a production authentication policy. See [Authenticate browser requests](./overview#authenticate-browser-requests) for the default fail-closed behavior and channel configuration.
 
 ## Dev vs deploy topology
 

package/docs/guides/frontend/nuxt.mdx

@@ -60,16 +60,7 @@ async function handleSubmit() {
 </template>
 ```
 
-The default eve channel is fail-closed. With no `agent/channels/eve.ts` authored, eve registers `eveChannel({ auth: [vercelOidc(), localDev(), placeholderAuth()] })`: `vercelOidc()` gets the first chance to resolve a Vercel caller, `localDev()` authenticates while the process is an `eve dev` or `vercel dev` server, and everything else gets a `401`. To run your own auth policy, add `agent/channels/eve.ts`:
-
-```ts title="agent/channels/eve.ts"
-import { eveChannel } from "eve/channels/eve";
-import { localDev, vercelOidc } from "eve/channels/auth";
-
-export default eveChannel({ auth: [vercelOidc(), localDev()] });
-```
-
-For a public demo, use `none()` (also from `eve/channels/auth`) to skip authentication. See [Channels](../../channels/overview) and [Auth & route protection](../auth-and-route-protection).
+The browser still needs a production authentication policy. See [Authenticate browser requests](./overview#authenticate-browser-requests) for the default fail-closed behavior and channel configuration.
 
 ## Dev vs deploy topology
 

package/docs/guides/frontend/overview.mdx

@@ -14,7 +14,15 @@ A browser UI is a client of the agent's HTTP routes (the [eve channel](../../cha
 
 The per-framework pages below walk through the wiring step by step: [Next.js](./nextjs), [Nuxt](./nuxt), and [SvelteKit](./sveltekit).
 
-For scripts, server-to-server calls, evals, tests, or custom clients that do not need framework UI state, use the [TypeScript SDK](../client/overview) directly.
+For scripts, server-to-server calls, evals, tests, or custom clients that do not need framework UI state, use the [Client SDK](../client/overview) directly.
+
+## Authenticate browser requests
+
+A same-origin framework integration sends your application cookies with every eve request. For bearer tokens or another non-cookie scheme, pass `auth` or `headers` to `useEveAgent`.
+
+The default eve channel fails closed. Without an authored `agent/channels/eve.ts`, production browser traffic receives `401` from the default `[vercelOidc(), localDev(), placeholderAuth()]` policy. Add the channel file with an `AuthFn` that verifies your application session or token.
+
+For a public demo, use `none()` from `eve/channels/auth` to admit anonymous requests explicitly. Do not use `none()` for an agent that handles private or production data. See [Authentication](../auth-and-route-protection) for application-session examples, token verifiers, and the default policy.
 
 ## Basic chat (React)
 
@@ -204,11 +212,12 @@ const agent = useEveAgent({
 
 ## Lifecycle callbacks
 
-On top of `onSessionChange`, the hook takes a few per-turn callbacks:
+The hook accepts these lifecycle callbacks:
 
 - `onEvent(event)`: fires for each eve stream event as it arrives.
 - `onError(error)`: fires with the last `Error` when a turn fails.
 - `onFinish(snapshot)`: fires with the final `{ data, status, session, ... }` snapshot once a turn settles.
+- `onSessionChange(session)`: fires when the session cursor advances. Persist it to resume across reloads.
 
 ```tsx
 const agent = useEveAgent({
@@ -320,5 +329,5 @@ const support = useEveAgent({ agent: "support" });
 
 - [Sessions, runs & streaming](../../concepts/sessions-runs-and-streaming): the event stream and session cursor
 - [Channels](../../channels/overview): the HTTP routes the hook talks to
-- [TypeScript SDK](../client/overview): the lower-level client underneath the frontend hooks
+- [Client SDK](../client/overview): the lower-level client underneath the frontend hooks
 - [Next.js](./nextjs): step-by-step setup for wiring eve into a Next.js app