eve 0.57.0 → 0.58.1

package/docs/channels/teams.mdx

@@ -14,6 +14,35 @@ import { teamsChannel } from "eve/channels/teams";
 export default teamsChannel();
 ```
 
+### Vercel Connect
+
+For a managed Teams bot on Vercel, run:
+
+```bash
+eve add channel/teams
+```
+
+The guided flow runs the Vercel Connect CLI, which takes you through managed
+Microsoft Teams app creation and installation. It routes verified Activities to
+`/eve/v1/teams` and writes:
+
+```ts title="agent/channels/teams.ts"
+import { connectTeamsCredentials } from "@vercel/connect/eve";
+import { teamsChannel } from "eve/channels/teams";
+
+export default teamsChannel({
+  credentials: connectTeamsCredentials("microsoft-teams/my-agent"),
+});
+```
+
+Vercel Connect owns the Microsoft administrator consent and app installation
+flow. After deployment, mention the bot in a channel or send it a personal
+message.
+
+### Portable credentials
+
+To manage the bot registration and credentials yourself, configure:
+
 ```bash
 MICROSOFT_APP_ID=...
 MICROSOFT_APP_PASSWORD=...

package/docs/concepts/meta.json

@@ -2,6 +2,7 @@
   "title": "Core Concepts",
   "defaultOpen": false,
   "pages": [
+    "project-structure",
     "execution-model-and-durability",
     "sessions-runs-and-streaming",
     "state",

package/docs/concepts/project-structure.mdx

@@ -0,0 +1,111 @@
+---
+title: "Project Structure"
+description: "Start with one agent, keep application code beside it, and split into a workspace only when you need separately addressable agents."
+---
+
+Start with one root agent in `agent/`. A root agent accepts requests through its own HTTP API or channels; it can have many tools, skills, and subagents. Keep browser application files outside `agent/`.
+
+| When you need…                                                         | Structure                                        |
+| ---------------------------------------------------------------------- | ------------------------------------------------ |
+| One agent, with or without a browser app                               | `agent/` beside your application code            |
+| A specialist that an agent delegates to                                | `agent/subagents/<name>/` inside that agent      |
+| Several separately addressable agents sharing a package and deployment | `agents/<name>/agent/` in an eve agent workspace |
+| Separate dependencies, versions, or release schedules                  | Separate agent packages or projects              |
+
+Every root agent can have [declared subagents](/docs/subagents#declared-subagents) with their own prompts, tools, and sandboxes. These specialists have no separate channel endpoint and do not inherit the parent's authored capabilities. Use a [skill](/docs/skills) instead when you only need an optional procedure.
+
+## One agent
+
+Use this layout for a standalone agent or an agent inside a web application:
+
+```text
+project/
+├── package.json
+├── agent/
+│   ├── instructions.md
+│   ├── tools/
+│   └── subagents/
+├── evals/
+├── app/                    # optional Next.js browser application
+└── next.config.ts          # optional Next.js integration
+```
+
+Create the agent with [Getting Started](/docs/getting-started). The [Agent Files reference](/docs/reference/agent-files) lists supported paths. Keep agent-only helpers in `agent/lib/`; share reusable capabilities through [extensions](/docs/extensions).
+
+For a generated Next.js chat UI, run `eve add channel/web` from the project root. For an existing browser app, follow your [framework integration guide](/docs/guides/frontend/overview#per-framework-integration).
+
+## Several root agents
+
+Use an eve agent workspace when, for example, clients need to address support and research separately:
+
+```text
+project/
+├── package.json
+├── agents/
+│   ├── support/
+│   │   ├── agent/
+│   │   └── evals/
+│   └── research/
+│       ├── agent/
+│       └── evals/
+└── apps/                   # optional peer applications, not eve workspace members
+    └── web/
+```
+
+Members share the root package, dependencies, scripts, and Vercel deployment. Their directory names identify them in the CLI and public routes. Members have no `package.json` of their own: adding one excludes that directory from eve workspace discovery. Unlike a package-manager workspace, this layout does not give members separate dependency or version boundaries.
+
+Create a workspace, then select an agent to run:
+
+```bash
+npx eve@latest init operations --agents support,research
+cd operations
+npx eve dev --agent support
+```
+
+Run agent commands such as `dev`, `info`, and `eval` from `agents/<name>/`, or pass `--agent <name>` from the workspace root. `eve dev --agent support` runs the selected agent, not peer applications. Start other agents separately when needed; local [workspace-peer calls](/docs/subagents#vercel-workspace-peers) require an explicit transport.
+
+On Vercel, run `eve link` and `eve deploy` from the root; deployment includes all members. No frontend is required. For self-hosting, [build and run each member separately](/docs/guides/deployment/self-hosting#run-workspace-members).
+
+## Independent releases
+
+Use separate packages or projects when agents need independent dependencies or releases, even within the same monorepo. These are not eve agent-workspace members. Share capabilities through [workspace extensions](/docs/extensions#use-an-extension-in-a-workspace); delegate across deployments with [remote agents](/docs/guides/remote-agents).
+
+## Configure a web deployment
+
+Choose how the frontend and agents run together independently of how many agents you have:
+
+- **Add agents to a Next.js application:** use [`eve/next`](/docs/guides/frontend/nextjs) in `next.config.ts`. Next.js owns the application lifecycle; the integration starts agent processes and proxies requests locally, and contributes separate agent services on Vercel. A root Next.js app can sit beside either `agent/` or `agents/`; workspace members are discovered automatically.
+- **Add a frontend to an agent workspace:** keep the frontend as a peer application, for example under `apps/web/`. On Vercel, use [`eve/vercel` in root `vercel.ts`](/docs/guides/deployment/vercel#compose-agents-with-other-vercel-services) to contribute the agents alongside the frontend service. For [self-hosting](/docs/guides/deployment/self-hosting#run-workspace-members), run the services with your process manager and configure a reverse proxy. The frontend does not need `eve/next`.
+
+`apps/web/` is an organizational convention, not an eve filesystem slot. Deployment configuration owns peer services; eve discovers only the agents. Both Vercel integrations deploy the services together, not as independent releases.
+
+The generated Web Chat installer does not support agent workspaces. Create the frontend and its agent-selection UI yourself, using the [React chat example](/docs/guides/frontend/overview#basic-chat-react). Develop a peer Next.js frontend with `next dev` separately from the agents. For an authored Vercel service graph, use `vercel dev --local` to run the composition without linking a Vercel project.
+
+For a single `agent/` project, `eve add channel/web` currently generates a root Next.js app using `eve/next`. `eve/vercel` currently requires an `agents/` workspace; it cannot compose a standalone root `agent/`.
+
+## Add a second root agent
+
+To convert a single-agent project into a workspace, move the original agent from the project root:
+
+```bash
+mkdir -p agents/support
+mv agent agents/support/agent
+```
+
+Move its `evals/` directory, if present, to `agents/support/evals/`. Keep `package.json`, dependencies, environment files, and any browser application at the project root. Do not leave a root `agent/` directory: eve treats a project with `agent/` as single-agent even when `agents/` also exists.
+
+Before adding the next agent:
+
+- Update `tsconfig.json` to include `agents/**/*.ts`, preserving any application includes. Update moved-file imports and path aliases, including scaffolded `package.json#imports` entries that point at `./agent/*` or `./evals/*`.
+- Update scripts that assume one agent. Use `--agent support` for agent-scoped commands; build an agent-only Vercel workspace with root `eve build`. For a Next.js app, keep the framework scripts and follow its [build instructions](/docs/guides/frontend/nextjs#dev-vs-deploy-topology).
+- Update HTTP clients and webhook registrations for the named agent's public routes. In a root Next.js app, remove a single-agent `eveRoot` override to enable workspace discovery, and select `support` in the client hook. Store the agent name alongside durable-session links.
+
+Then add the second agent and check discovery:
+
+```bash
+npx eve init research
+npx eve info --agent support
+npx eve info --agent research
+```
+
+Run the moved agent's evals with `npx eve eval --agent support`. Add later agents with `npx eve init <name>` from the workspace root.

package/docs/getting-started.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Getting Started"
-description: "Create an eve project, configure a model, understand its filesystem layout, and run your first agent."
+description: "Create an eve project, configure model credentials, and run your first agent."
 contentType: "How-to"
 ---
 
@@ -18,6 +18,8 @@ Choose a model, provider, and channel that meet your data-processing and complia
 
 ## Create a project
 
+Start with one agent in `agent/`.
+
 Run `eve init` with a project name:
 
 ```bash
@@ -48,119 +50,29 @@ npx eve@latest init my-agent --model openai/gpt-5.6-terra --reasoning high
 
 ## Run the agent
 
-The terminal UI opens after interactive initialization. To return later, run this from the project root:
+The terminal UI opens after interactive initialization. To return later, enter the project and run:
 
 ```bash
+cd my-agent
 npm run dev
 ```
 
-This starts an interactive session where you can send messages to your agent.
-
-## 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
-
-eve derives names from file paths, so you do not configure them separately.
-
-| 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 uses its `package.json` `name`, or its app directory name if none is set. A subagent uses its directory name.
-
-### Recommended layout
-
-A minimal agent needs `instructions.md`; `agent.ts` is optional when the default config is sufficient. Framework defaults occupy ordinary agent slots, so authoring the same path replaces the default before eve compiles the agent. Add other slots as the agent needs them:
-
-```text
-my-agent/
-├── README.md
-├── 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.
-
-### Agent files and directories
-
-Each path under `agent/` has a specific purpose. Root agents can use every path below. A subagent has its own files and can use only the paths marked **Yes**.
-
-| Path                                                    | Use                                       | Available to 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                    | Static files define one path-named connection. Dynamic files can resolve a caller-specific connection set at runtime.                                                             |
-| `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.                                                                                            |
-
-### Files available in the sandbox
-
-Files under `agent/` define your agent; only files in `agent/sandbox/workspace/` are copied to `/workspace/` when a session starts.
-
-### 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/
-```
+This starts an interactive session where you can send messages to your agent. Edit `agent/instructions.md` to change its behavior and `agent/agent.ts` to configure its model. eve reloads your changes as you work.
 
-Prefer the nested layout because it keeps application files separate from the authored agent surface.
+<span id="project-layout" />
+<span id="agent-directory-layout" />
+<span id="naming-from-paths" />
+<span id="recommended-layout" />
+<span id="nested-layout" />
+<span id="agent-files-and-directories" />
+<span id="files-available-in-the-sandbox" />
+<span id="local-subagents" />
+<span id="flat-layout" />
+<span id="debug-file-discovery" />
 
-### Debug file discovery
+## Organize your project
 
-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 [Instrumentation](./observability/instrumentation) and the [CLI](./reference/cli) reference.
+See [Project Structure](/docs/concepts/project-structure) when adding another root agent or deciding where a frontend belongs. The [Agent Files reference](/docs/reference/agent-files) lists supported files and discovery rules.
 
 ## Install manually
 

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

@@ -231,19 +231,23 @@ import { vercelOidc, vercelSubject } from "eve/channels/auth";
 
 export default eveChannel({
   auth: [vercelOidc()],
-  // Only the router deployment may assert a forwarded principal.
+  // Only the router deployment may forward eve delegation context.
   trustedForwarders: (forwarder) =>
     forwarder.subject === vercelSubject({ teamSlug: "acme", projectName: "router" }),
 });
 ```
 
-The predicate authorizes the _forwarder_ (the verified route-auth principal — who is asserting), not the forwarded principal (what is asserted). Match it precisely: a permissive predicate like `() => true` lets any caller that passes route auth assert any principal, including preview deployments of your own project when `vercelOidc()` is in the walk. `trustedForwarders` exists only on your authored channel — the framework default channel never accepts a forwarded principal, so a receiving deployment must author `agent/channels/eve.ts`.
+`trustedForwarders` authorizes the verified forwarder to supply eve delegation context: principal identity, parent session lineage, and, with principal forwarding, trace-content constraints. Match it precisely: `() => true` grants this authority to every caller that passes route auth, including preview deployments accepted by `vercelOidc()`. The framework default channel rejects forwarded principals and ignores the other context.
 
 When the predicate accepts a create request, `ctx.session.auth.current` and `.initiator` carry the forwarded user exactly as if they had called your deployment directly. On continuation, only `auth.current` is replaced; `auth.initiator` remains the session creator. User-scoped connections, local subagents, and further `forwardPrincipal` hops therefore see the active turn's caller.
 
-The forwarder is recorded on accepted contexts as the `eve:forwarded-by` attribute (always overwritten by the receiver, so a forwarder cannot falsify it). Rejections fail loud: a forwarded body without `trustedForwarders` configured or with a forwarder the predicate refuses is a `403`, and a malformed payload is a `400`. Only principal metadata is ever accepted — tokens and credentials never cross the hop.
+The forwarder is recorded on accepted contexts as the `eve:forwarded-by` attribute (always overwritten by the receiver, so a forwarder cannot falsify it). Forwarded identity rejections fail loud: a forwarded body without `trustedForwarders` configured or with a forwarder the predicate refuses is a `403`, and a malformed payload is a `400`. Only principal metadata is ever accepted — tokens and credentials never cross the hop.
 
-For requests marked as remote delegations by a callback body and valid sampled `traceparent`, the same accepted `trustedForwarders` result may admit an origin audience and directional content ceiling from one W3C Baggage member. The assertion is not an authorization grant: the receiver's trace policy independently decides against the immutable origin audience, and the two decisions are intersected. Every later hop forwards only that narrowed result. Malformed, partial, unsampled, or mixed-version assertions become metadata-only. The callback and headers are caller-supplied—the verified transport principal and `trustedForwarders` are the trust boundary. See [Preserving trace content](./remote-agents#preserving-trace-content).
+Trusted parent session lineage populates `ctx.session.parent` and preserves the root session across the delegation chain. Untrusted lineage is ignored, and accepted lineage does not remove the normal root-session token cap.
+
+For requests marked as remote delegations by a callback body and valid sampled `traceparent`, the same accepted `trustedForwarders` result may admit an origin audience and directional content ceiling from one W3C Baggage member. The assertion is not an authorization grant: the receiver's trace policy independently decides against the immutable origin audience, and the two decisions are intersected. Every later hop forwards only that narrowed result. Malformed, partial, unsampled, or mixed-version assertions become metadata-only. The callback and headers are caller-supplied; the verified transport principal and `trustedForwarders` are the trust boundary. See [Preserving trace content](./remote-agents#preserving-trace-content).
+
+W3C `traceparent`, `tracestate`, and the forwarded conversation ID are correlation metadata. They do not require `trustedForwarders`, establish session lineage, or grant session access.
 
 > ⚠️ Both deployments must support continuation forwarding before you resume persistent remote sessions. A create-only receiver rejects a forwarded continuation with HTTP 400; the sender does not fall back to service authority. See [Forwarding the caller identity](./remote-agents#forwarding-the-caller-identity) for the upgrade behavior.
 

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

@@ -61,6 +61,46 @@ Forward both runtime route prefixes through your reverse proxy or ingress:
 
 A proxy restricted to `/eve/` lets a session start, but the run stalls when its callback can’t reach eve. Preserve both prefixes without rewriting their paths.
 
+## Run workspace members
+
+An [agent workspace](../../concepts/project-structure#several-root-agents) does not require Vercel or a frontend at runtime. Build each member from its own directory: root `eve build` produces a Vercel workspace deployment, not a group of self-hosted Node servers.
+
+For a workspace containing `support` and `research`, run these from the workspace root, outside a Vercel build environment:
+
+```bash
+(cd agents/support && npx eve build)
+(cd agents/research && npx eve build)
+```
+
+Start each built agent in a separate terminal, or configure these commands in your process manager:
+
+```bash
+(cd agents/support && npx eve start --host 127.0.0.1 --port 3001)
+(cd agents/research && npx eve start --host 127.0.0.1 --port 3002)
+```
+
+For example, this Caddy configuration gives each agent its own origin and forwards both `/eve/` and `/.well-known/workflow/` without changing their paths. Point the example hostnames at your server and run Caddy on the same machine:
+
+```text
+support.example.com {
+    reverse_proxy 127.0.0.1:3001
+}
+
+research.example.com {
+    reverse_proxy 127.0.0.1:3002
+}
+```
+
+Apply the authentication, persistent storage, and sandbox configuration above to each member. With the default local Workflow world, persist each member's own `.eve/.workflow-data` directory. If agents delegate to one another, configure an explicit [workspace-peer transport](../../subagents#vercel-workspace-peers) with the peer's URL and credentials; the default transport requires Vercel. Ensure callback URLs are reachable from the services that call them.
+
+### Add a peer frontend
+
+A frontend under `apps/web/` is another service managed by your host, not by `eve start`. Build and start it using its framework commands. A browser client can use `useEveAgent({ host: "https://support.example.com" })`; configure [CORS](../../channels/eve#cors) and browser credentials for that deployment. Alternatively, mount each agent on the frontend's origin through your reverse proxy.
+
+For path-based mounts, strip the public prefix before forwarding requests to the agent and set `EVE_PUBLIC_ROUTE_PREFIX` in that agent's build and runtime environments. Forward its workflow callback routes as well as its eve routes. Keep the browser client, callback URLs, and peer transports consistent with the public mounts.
+
+You can instead use [`eve/next`](../frontend/nextjs#dev-vs-deploy-topology) if you want Next.js to start built agent processes and provide the browser-facing proxy routes. That integration is optional; `eve/vercel` configuration is not used by a self-hosted process manager.
+
 ## Run schedules
 
 The standard `eve build && eve start` path starts Nitro’s schedule runner. If you adapt the output to a custom HTTP-only host or preset, run Nitro scheduled tasks or invoke the same work from your scheduler.

package/docs/guides/deployment/vercel.mdx

@@ -7,7 +7,7 @@ Deploy eve to Vercel when you want the framework’s managed build and runtime i
 
 ## Prepare the Vercel project
 
-Link the agent directory to a Vercel project:
+Run this from the project root to link it to a Vercel project. For an eve agent workspace, use the workspace root, not a member directory:
 
 ```bash
 eve link
@@ -51,27 +51,17 @@ See [Sandbox](../../sandbox) for resource limits, network policy, and lifecycle
 
 ## Deploy the agent
 
-A project containing only several independently addressed root agents can use eve's hostless workspace layout:
+For a single-agent project without a frontend, use `eve build`. For an agent-only workspace, run it from the workspace root: eve generates a separately built service and a `/<name>/eve/v1/*` transport route for each member. All members deploy together in one Vercel project. See [Project Structure](../../concepts/project-structure) for workspace membership and layout rules.
 
-```text
-my-project/
-├── package.json
-└── agents/
-    ├── support/
-    │   └── agent/
-    └── research/
-        └── agent/
-```
-
-In an eve workspace, eve discovers direct `agents/<name>/` children that contain nested or flat agent files and do not have their own `package.json`. Their directory names become their public identities, exposed at `/<name>/eve/v1/*`. A child with its own `package.json` is a separate package rather than a member of the parent eve workspace. Run an agent-specific command from a member directory or pass `--agent <name>` at the workspace root; interactive commands open a picker when the name is omitted. Run project-level build, link, and deploy commands from the workspace root. Workspace members share the root package, dependencies, and build scripts.
+A Next.js-centered project uses [`withEve` in `next.config.ts`](../frontend/nextjs) and its Next.js build command. If you author the project's broader service graph in `vercel.ts`, use the configuration below instead.
 
-Create this layout with `eve init my-project --agents support,research`, or add one agent to an existing workspace with `eve init billing`.
+### Compose agents with other Vercel services
 
-For an agent-only workspace, run `eve build`. eve owns the Vercel Build Output and generates one independently built service and a `/<name>/eve/v1/*` transport route for each workspace member.
+Use `withEve` from `eve/vercel` when the agents and other applications are peer services. The helper contributes workspace agents to a Vercel service graph; it does not manage or require a particular frontend framework. Unlike `eve/next`, this keeps the project lifecycle separate from Next.js. Both integrations deploy the agent services together in one Vercel project.
 
-### Compose agents with other Vercel services
+`eve/vercel` currently requires an `agents/` workspace, even if it has only one member. It does not support a standalone root `agent/`.
 
-Use Vercel's programmatic configuration when a workspace also deploys a frontend, private API, or another non-eve service. Replace `vercel.json` with a root `vercel.ts` and compose the authored graph with `withEve`:
+For a workspace with a peer Next.js frontend under `apps/web/`, replace `vercel.json` with a root `vercel.ts`. The frontend uses an ordinary Next.js config without `eve/next`:
 
 ```typescript title="vercel.ts"
 import { withEve } from "eve/vercel";
@@ -92,7 +82,11 @@ export default await withEve({
 });
 ```
 
-Vercel evaluates `vercel.ts` before resolving the service graph. `withEve` discovers direct workspace members, adds their services and transport routes, and returns a plain Vercel configuration. Vercel can then build `web` and every eve agent independently. The frontend does not need `withEve` in its framework configuration or a build script that builds the agents.
+Vercel evaluates `vercel.ts` before resolving the service graph. `withEve` adds the root agent, or every direct workspace member, as an independently built service and returns a plain Vercel configuration. Named workspace agents mount at `/eve/<name>/v1/*`; a root agent mounts at `/eve/v1/*`. Vercel then builds the frontend and each eve agent separately. The frontend does not need `withEve` in its framework configuration or a build script that builds the agents.
+
+The Web Chat installer does not support agent workspaces. Create the frontend using the [React chat example](../frontend/overview#basic-chat-react), and configure authentication for every exposed agent. To self-host the same source layout, replace Vercel composition with your own [process and proxy configuration](./self-hosting#run-workspace-members).
+
+Run Vercel CLI 59.16.0 or newer with `vercel dev --local` to start the complete service graph locally. Named agents use the same `/eve/<name>/v1/*` routes in development, and default `defineWorkspaceAgent` transports can call peers without deployment credentials. Run `eve dev` instead when you only need one agent and the eve terminal UI.
 
 Generated transport routes are inserted before a filesystem handler or, when no filesystem handler exists, before authored routes. `withEve` throws instead of overwriting an authored service key or exact transport route that belongs to a generated agent. Remove the authored route, and remove or rename the authored service; `withEve` adds both automatically. Names in the array form of `services` must also be unique. Other service names, routes, bindings, and Cron Jobs remain authored in `vercel.ts`.
 
@@ -120,9 +114,11 @@ export default await withEve({
 
 A Vercel project can use only one configuration source, so remove `vercel.json` when adopting `vercel.ts`. Keep `eve` in the root package dependencies so Vercel can import `eve/vercel` while evaluating the configuration. `withEve` discovers the workspace containing its evaluation directory, including Vercel's temporary `.vercel` configuration directory. Pass `{ root: "/absolute/workspace/path" }` as the second argument only when you need to select a specific workspace root.
 
-An authored eve service routed at `/eve/v1` already uses the protocol path; callbacks remain at `/eve/v1/callback/*`. A named mount such as `/support` adds that mount before the protocol path, giving `/support/eve/v1/callback/*`.
+An authored eve service routed at `/eve/v1` already uses the protocol path; callbacks remain at `/eve/v1/callback/*`. A named mount such as `/eve/support` adds that mount before the protocol path, giving `/eve/support/v1/callback/*`.
 
-Deploy the linked project to production:
+### Deploy the project
+
+Deploy the linked project to production from its root:
 
 ```bash
 eve deploy
@@ -145,11 +141,18 @@ Vercel uses the generated output to configure these services:
 
 ## Verify the deployment
 
-Check the health route and connect the development TUI:
+For a single unnamed agent, check the health route and connect the development TUI:
+
+```bash
+curl https://your_agent.vercel.app/eve/v1/health
+eve dev https://your_agent.vercel.app
+```
+
+For a workspace agent, include its public `/eve/<name>` mount. For example:
 
 ```bash
-curl https://your_agent.vercel.app/support/eve/v1/health
-eve dev https://your_agent.vercel.app/support
+curl https://your_agent.vercel.app/eve/support/v1/health
+eve dev https://your_agent.vercel.app/eve/support
 ```
 
 Set `VERCEL_AUTOMATION_BYPASS_SECRET` locally before connecting if the deployment uses Deployment Protection.

package/docs/guides/dynamic-capabilities.md

@@ -333,6 +333,10 @@ A dynamic connection, tool, or skill whose name matches an **authored** one **ov
 
 ¹ Workflow recovery can redeliver a resolver event, so keep resolvers idempotent. Replaying a parked callback does not depend on running the resolver again — except for the one-shot rebind described under [Identity and redeploys](#identity-and-redeploys).
 
+At `turn.started`, model, tool, skill, and subagent resolvers receive the visible conversation history and incoming message in `ctx.messages`, oldest first. Request context is included, and history projection still applies. Read these messages from the handler's second argument; the event itself contains turn metadata. Instruction resolvers use the separate snapshot described under [Dynamic instructions](#dynamic-instructions).
+
+This also applies while a session-limit prompt keeps the incoming message queued and when authorization completes. Authorization callbacks without new or queued input receive the visible history. When memory recall runs, its results appear in the projected snapshot before incoming input.
+
 ### Execution order
 
 When a stream event fires, three things happen in order.

package/docs/guides/evaluate.md

@@ -0,0 +1,118 @@
+---
+title: Automatic Model Selection
+description: "Choose an agent model from the current request with an AI SDK evaluation model."
+---
+
+Use `autoModel` to choose an agent model from an allowlist before inference begins.
+It uses the [AI SDK evaluation API](https://ai-sdk.dev/docs/ai-sdk-core/evaluation),
+so the evaluator can be a Vercel AI Gateway model ID or an evaluation model from
+an installed provider.
+
+`eve/experimental/evaluate` is experimental. Its API can change between eve
+releases, and the AI SDK evaluation model specification can change in patch
+releases.
+
+## Choose from Gateway models
+
+By default, `autoModel` evaluates with `typesafe-ai/jev`. Like other AI SDK
+model strings, it uses Vercel AI Gateway unless the application has configured a
+different global default provider.
+
+```ts title="agent/agent.ts"
+import { defineAgent } from "eve";
+import { autoModel } from "eve/experimental/evaluate";
+
+export default defineAgent({
+  model: autoModel({
+    options: {
+      "openai/gpt-5.6-sol": "Difficult reasoning and engineering tasks",
+      "openai/gpt-5.6-luna": "Routine tasks where fast completion matters",
+    },
+  }),
+});
+```
+
+Configure Gateway authentication as you would for any other AI SDK model. eve
+does not add a TypeSafe credential or transport layer. During `eve dev`, a
+Gateway evaluator uses the same connection selected through `/login` as Gateway
+language models. A configured AI SDK default provider still owns string model
+resolution during development. The TUI footer displays `dynamic model` when the
+agent uses `autoModel`.
+
+## Use a provider directly
+
+Install the provider package yourself and pass its evaluation model. The provider
+owns its credentials and settings.
+
+```sh
+pnpm add @ai-sdk/typesafe-ai
+```
+
+```ts title="agent/agent.ts"
+import { typeSafeAi } from "@ai-sdk/typesafe-ai";
+import { defineAgent } from "eve";
+import { autoModel } from "eve/experimental/evaluate";
+
+export default defineAgent({
+  model: autoModel({
+    model: typeSafeAi.evaluationModel("jev-latest"),
+    options: {
+      "openai/gpt-5.6-sol": "Difficult reasoning and engineering tasks",
+      "openai/gpt-5.6-luna": "Routine tasks where fast completion matters",
+    },
+  }),
+});
+```
+
+Any provider that implements the AI SDK `Experimental_EvaluationModel` contract
+works here.
+
+## Route to provider models and set reasoning
+
+An option's key is the value shown to the evaluator. A string value describes a
+Gateway model whose ID is the key. Use the object form when the selected model is
+a provider instance, an alias, or needs a reasoning override.
+
+```ts title="agent/agent.ts"
+import { anthropic } from "@ai-sdk/anthropic";
+import { defineAgent } from "eve";
+import { autoModel } from "eve/experimental/evaluate";
+
+export default defineAgent({
+  reasoning: "medium",
+  model: autoModel({
+    options: {
+      "openai/gpt-5.6-sol": "Hard problems",
+      my_secret_model: {
+        model: anthropic("sonnet-5"),
+        description: "Routine work that can use the direct Anthropic provider",
+        reasoning: "low",
+      },
+    },
+  }),
+});
+```
+
+The evaluator sees option keys, descriptions, and recent text messages. It never
+receives provider credentials or serialized language model instances. When it
+selects `my_secret_model`, eve resolves the key back to the authored Anthropic
+model.
+
+Supported reasoning values are `"provider-default"`, `"none"`, `"minimal"`,
+`"low"`, `"medium"`, `"high"`, and `"xhigh"`. An omitted value inherits the
+agent's reasoning setting.
+
+## Runtime behavior
+
+`autoModel` evaluates at the first `step.started` event, after the incoming prompt
+is available and before the selected language model runs. It reuses that choice
+for later tool-loop steps in the same turn. A new turn makes a new choice, and
+child sessions route from their own prompts.
+
+The evaluator receives up to eight recent user and assistant text messages,
+capped at 16,000 characters. Requests without user text and latest messages over
+the limit fail before provider I/O.
+
+Evaluation validation, retries, provider errors, and model resolution follow AI
+SDK semantics. Cancelling the active turn aborts evaluation and prevents the
+choice from being retained.