eve 0.27.5 → 0.27.7

package/docs/concepts/{execution-model-and-durability.md → execution-model-and-durability.mdx}

@@ -38,6 +38,22 @@ export default defineAgent({
 
 The world package backs workflow state, queues, hooks, and streams. Keep secrets and deployment-specific options in runtime environment variables read by that package, not in `agent.ts`. Custom worlds must implement the runtime protocol expected by eve's vendored `@workflow/*` packages (currently the `5.0.0-beta` line); the Workflow SDK rejects incompatible protocol versions during initialization. See [Self-host eve](../guides/deployment/self-hosting#persist-workflow-state), [agent.ts](../agent-config#workflow-world), and [Workflow Worlds](https://workflow-sdk.dev/worlds).
 
+## Agent loop and sandbox
+
+An eve agent spans two execution environments with different responsibilities:
+
+<AgentRuntimeDiagram />
+
+The agent loop runs as a durable workflow in the app runtime. Model calls, tool executors, hooks, instrumentation, and connection clients also run there with full Node.js access.
+
+App-side code reaches the sandbox through `ctx.getSandbox()`. The built-in `bash`, `read_file`, `write_file`, `glob`, and `grep` tools use it, and authored tools can use it when they need isolated filesystem or process access.
+
+The [sandbox](../sandbox) owns the per-session filesystem and processes. Authored skills are materialized under `$HOME/.agents/skills`, and `agent/sandbox/workspace/**` seeds `/workspace`. The loop and sandbox have decoupled lifetimes: the durable workflow can park or restart independently, while the app runtime opens or reuses sandbox compute only when code needs it.
+
+This split gives the agent a real filesystem and process environment without putting credentials or trusted integration code in model-controlled compute. The workflow can park without holding sandbox compute, while sandbox capacity and backends can change independently of durable orchestration. Because access flows through app-side tools, sandbox work gets the same approval and instrumentation path as any other tool call.
+
+Provider keys, tool secrets, and MCP, OpenAPI, and connection credentials stay in the app runtime. When a sandbox process needs authenticated network access, [credential brokering](./security-model#credential-brokering) handles the request without exposing the credential to the process.
+
 ## Resuming after a crash
 
 Crash the process, hit a timeout, or redeploy mid-turn, and the run picks up from the last completed step rather than replaying the whole turn. Completed steps never re-run; eve replays the recorded result. A step interrupted mid-execution re-runs, so make non-idempotent side effects like charges or emails idempotent, or gate them with approval.

package/docs/concepts/security-model.md

@@ -20,6 +20,8 @@ The sandbox is the isolated side. The model runs shell commands there through th
 
 A concrete trace makes the boundary clear. When the model calls a custom `charge_card` tool, its `execute` runs in the app runtime, reads `process.env.STRIPE_KEY`, calls Stripe, and returns `{ ok: true }`. The model sees only `{ ok: true }`: the key never leaves the app runtime, and nothing about the call touches the sandbox. The built-in `write_file` is the mirror image, running in the app runtime and proxying the write into the sandbox `/workspace`. Either way the model drives the work through tool calls and their results, never by holding a credential or reaching the runtime directly.
 
+See [Agent loop and sandbox](./execution-model-and-durability#agent-loop-and-sandbox) for how eve connects these contexts while keeping their state and lifetimes separate.
+
 ## Data flow at a glance
 
 ```mermaid

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

@@ -124,6 +124,15 @@ curl "http://127.0.0.1:2000/eve/v1/session/<sessionId>/stream?startIndex=-1"
 
 This gives a consumer that only persisted `sessionId` a lightweight way to recover the current `continuationToken`. Because a tail-relative position does not resolve to an absolute consumed-event count, client tail reads do not automatically reconnect or advance the stored cursor.
 
+For a catch-up read that stops instead of following the live stream, pass `includeTailIndex=1`. The response then carries the `x-eve-stream-tail-index` header: the zero-based index of the last durably recorded event, or `-1` before the first. Read from your cursor until it passes that tail, then disconnect — reconnecting from the updated cursor if the connection drops first:
+
+```bash
+curl -i "http://127.0.0.1:2000/eve/v1/session/<sessionId>/stream?startIndex=<count>&includeTailIndex=1"
+# x-eve-stream-tail-index: <tail>
+```
+
+The lookup is opt-in; requests without the parameter get no header. The TypeScript client wraps this into `stream({ follow: false })`.
+
 ## Use the client from TypeScript
 
 For scripts, server-to-server calls, tests, evals, and custom UIs, `eve/client` wraps these routes in a typed client so you don't hand-roll the POST and NDJSON stream loop.

package/docs/getting-started.mdx

@@ -1,206 +1,23 @@
 ---
 title: "Getting Started"
-description: "Install eve, scaffold your first agent, give it a tool, and run it locally."
+description: "Create an eve project, learn its filesystem layout, and start adding capabilities."
+contentType: "Landing"
 ---
 
-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 agents are TypeScript projects. You describe an agent with files under `agent/`, then eve runs it as a durable service.
 
-## Prerequisites
+## Start in order
 
-- Node 24 or newer
-- npm (bundled with Node)
-- A model credential (see below)
+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
 
-The scaffold's default model is `anthropic/claude-sonnet-5`, which routes through the Vercel AI Gateway. Set one of these before you run the agent:
+## What you need
 
-- A gateway model id needs `AI_GATEWAY_API_KEY`, or a `VERCEL_OIDC_TOKEN` pulled with `vercel link`.
-- A direct provider model uses that provider's AI SDK package and API key. For example, `anthropic("claude-...")` from `@ai-sdk/anthropic` needs `ANTHROPIC_API_KEY`.
+- Node.js 24 or newer
+- npm, which Node.js includes
+- A model credential for the model your agent uses
 
-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.
+## Choose your next step
 
-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
-
-`npx` runs `eve init` without installing eve first:
-
-```bash
-npx eve@latest init my-agent
-```
-
-The command:
-
-- Creates a child directory using the current workspace or launcher package manager, and uses eve's default model
-- Installs dependencies and initializes Git
-- When a supported coding-agent REPL (Claude Code, Codex, Cursor, Droid, Gemini CLI, opencode, or Pi) is on `PATH`, asks whether to open an available REPL or start the development server; otherwise starts the server and opens the interactive [terminal UI](./guides/dev-tui)
-
-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.
-
-When you choose one of those REPLs, eve starts it with a project-specific
-prompt that guides the setup. The prompt distinguishes `eve dev`, which starts
-eve's HMR server and the agent's terminal REPL, from `eve dev --no-ui`, which is
-the controllable background mode for verification.
-
-`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.
-
-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.
-
-## Manual installation
-
-To wire eve into an existing app by hand instead of using `eve init`, first declare a compatible Node runtime in `package.json`:
-
-```json
-{
-  "engines": {
-    "node": "24.x"
-  }
-}
-```
-
-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 ai zod
-```
-
-### Project files
-
-A minimal agent is two files; you add tools as you need them.
-
-`agent/instructions.md` is the always-on system prompt:
-
-```md
-You are a concise assistant. Use tools when they are available.
-```
-
-`agent/agent.ts` holds runtime config:
-
-```ts
-import { defineAgent } from "eve";
-
-export default defineAgent({
-  model: "anthropic/claude-sonnet-5",
-});
-```
-
-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
-
-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 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) }),
-  async execute({ city }) {
-    return { city, condition: "Sunny", temperatureF: 72 };
-  },
-});
-```
-
-Tools run in your app runtime with full `process.env`, not inside the [sandbox](./sandbox). More in [Tools](./tools).
-
-## Run the app
-
-A scaffolded app has a `dev` script, so from the app root run:
-
-```bash
-npm run dev
-```
-
-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. First the `get_weather` call, then its result, then the reply.
-
-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/overview).
-
-## 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 \
-  -H 'content-type: application/json' \
-  -d '{"message":"What is the weather in Brooklyn?"}'
-```
-
-The response comes back with two things you'll reuse:
-
-- a `continuationToken` in the JSON body, to resume this conversation
-- an `x-eve-session-id` header that identifies the run to stream
-
-## Stream the session
-
-Attach to the session stream:
-
-```bash
-curl http://127.0.0.1:2000/eve/v1/session/<sessionId>/stream
-```
-
-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> \
-  -H 'content-type: application/json' \
-  -d '{"continuationToken":"<token>","message":"Now do Queens."}'
-```
-
-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. 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. In a coding-agent launch, init installs dependencies and prints the project-specific dev command instead of starting the interactive terminal UI. A fresh project also initializes Git; an existing app keeps its repository and scripts. 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 eve in a controllable background process with `npx eve dev --no-ui`, wait for the server URL, 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. Stop the dev process after verification. 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 `npx eve dev --no-ui`, then create a session, stream
-  it, and send a follow-up.
-</CopyPrompt>
-
-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
-
-- [Instructions](./instructions) and [Tools](./tools): the core building blocks
-- [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 and streaming](./concepts/sessions-runs-and-streaming): the durable session model
-- [Build an agent](./tutorial/first-agent): the full end-to-end walkthrough
+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.

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

@@ -220,6 +220,26 @@ You do not have to keep `vercelOidc()` in the final policy. For a self-hosted ap
 
 Keep secret values (`ROUTE_AUTH_BASIC_PASSWORD`, signing keys) in environment variables. Route-auth secrets never land in compiled artifacts. The runtime re-materializes them from the authored channel definition at boot.
 
+## Accepting forwarded identity from another deployment
+
+A `defineRemoteAgent({ forwardPrincipal: true })` caller (see [Remote agents](./remote-agents#forwarding-the-caller-identity)) asserts its end user's principal on the create-session request as a `forwardedPrincipal` body field. By default every such assertion is rejected with `403` — accepting someone else's word for who the user is requires naming exactly which forwarders you trust. Do that with `trustedForwarders` on `eveChannel`:
+
+```ts title="agent/channels/eve.ts"
+import { eveChannel } from "eve/channels/eve";
+import { vercelOidc, vercelSubject } from "eve/channels/auth";
+
+export default eveChannel({
+  auth: [vercelOidc()],
+  // Only the router deployment may assert a forwarded principal.
+  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`.
+
+When the predicate accepts, the forwarded principal replaces the session principal: `ctx.session.auth.current` and `.initiator` carry the forwarded user exactly as if they had called your deployment directly, so user-scoped connections, local subagents, and further `forwardPrincipal` hops all see that user. The forwarder is recorded on the 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.
+
 ## What reaches `ctx.session.auth`
 
 Inside runtime code, `ctx.session.auth` carries the result of the channel's route auth (the walk above) forward as the caller snapshot:

package/docs/guides/client/overview.mdx

@@ -108,6 +108,8 @@ const response = await session.send({
 await response.result();
 ```
 
+Per-request headers override client-level values with the same name. For example, a turn can set its application user's `Authorization` header while `vercelOidc` continues to send the deployment-protection credential in `x-vercel-trusted-oidc-idp-token`.
+
 ## Sessions
 
 Create a `ClientSession` for each conversation:

package/docs/guides/client/streaming.mdx

@@ -157,6 +157,21 @@ for await (const event of session.stream({ startIndex: -1 })) {
 
 Tail-relative attachments do not automatically reconnect or advance the session's stored absolute `streamIndex`. Break after the event you need when using one as a tail lookup.
 
+## Bounded catch-up reads
+
+Pass `follow: false` to read from the cursor to the durable tail and then stop, instead of following the live stream (the default):
+
+```ts
+for await (const event of session.stream({ follow: false })) {
+  console.log(event.type);
+}
+// Returns once every event recorded before the stream opened is consumed.
+```
+
+The first connection pins the bound to the tail the server reports at open time; events recorded afterward are not part of the read. Reconnects during the read keep that original bound, and the session's stored `streamIndex` still advances past the consumed events, so a follow-up `stream()` or `send()` picks up exactly where the bounded read ended. When the cursor is already at or past the tail, the iterator returns immediately without yielding.
+
+Because a tail-relative cursor cannot be bounded, `follow: false` throws when combined with a negative `startIndex`. It also fails if the server does not report the durable tail (an agent running an older eve version).
+
 `stream()` throws if the session has no `sessionId`, because there's no stream to attach to before the first send.
 
 ## Abort a request

package/docs/guides/remote-agents.md

@@ -20,14 +20,15 @@ export default defineRemoteAgent({
 
 `defineRemoteAgent` accepts:
 
-| Parameter      | Type                                          | Required | Default           | Description                                                                                                                                              |
-| -------------- | --------------------------------------------- | -------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `url`          | `string \| (() => string \| Promise<string>)` | Yes      | n/a               | Base URL of the remote eve deployment to call. A string is baked at compile time; a function is resolved at runtime (see [Runtime URLs](#runtime-urls)). |
-| `description`  | `string`                                      | Yes      | n/a               | Model-visible delegation description.                                                                                                                    |
-| `auth`         | `OutboundAuthFn`                              | No       | none              | Outbound auth hook from `eve/agents/auth`.                                                                                                               |
-| `headers`      | `HeadersValue`                                | No       | none              | Static or lazily resolved request headers.                                                                                                               |
-| `path`         | `string`                                      | No       | `/eve/v1/session` | Route appended to `url` for the create-session request.                                                                                                  |
-| `outputSchema` | `StandardSchema \| JSON Schema`               | No       | none              | Structured return type the caller requires. Lowered to JSON Schema at compile time and enforced by the remote like any task-mode output schema.          |
+| Parameter          | Type                                          | Required | Default           | Description                                                                                                                                              |
+| ------------------ | --------------------------------------------- | -------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `url`              | `string \| (() => string \| Promise<string>)` | Yes      | n/a               | Base URL of the remote eve deployment to call. A string is baked at compile time; a function is resolved at runtime (see [Runtime URLs](#runtime-urls)). |
+| `description`      | `string`                                      | Yes      | n/a               | Model-visible delegation description.                                                                                                                    |
+| `auth`             | `OutboundAuthFn`                              | No       | none              | Outbound auth hook from `eve/agents/auth`.                                                                                                               |
+| `forwardPrincipal` | `boolean`                                     | No       | `false`           | Forward the dispatching turn's session principal to the remote deployment (see [Forwarding the caller identity](#forwarding-the-caller-identity)).       |
+| `headers`          | `HeadersValue`                                | No       | none              | Static or lazily resolved request headers.                                                                                                               |
+| `path`             | `string`                                      | No       | `/eve/v1/session` | Route appended to `url` for the create-session request.                                                                                                  |
+| `outputSchema`     | `StandardSchema \| JSON Schema`               | No       | none              | Structured return type the caller requires. Lowered to JSON Schema at compile time and enforced by the remote like any task-mode output schema.          |
 
 ## Runtime URLs
 
@@ -60,6 +61,28 @@ A remote agent lowers to the same `{ message, outputSchema? }` tool shape as a l
 
 If you are calling another Vercel-deployed eve agent, reach for `vercelOidc()`. The remote verifies the OIDC token to authorize the caller. See [Auth & route protection](./auth-and-route-protection) for the receiving side.
 
+## Forwarding the caller identity
+
+Outbound auth authenticates your _deployment_ to the remote, so by default the remote session runs as your calling app — not as the end user who is talking to your agent. That breaks per-user workloads on the remote deployment, most directly per-user [Vercel Connect](./auth-and-route-protection#tool-and-connection-auth), which requires an authenticated `user` principal on the session.
+
+Set `forwardPrincipal: true` to forward the dispatching turn's session principal across the hop:
+
+```ts title="agent/subagents/site-ops.ts"
+import { defineRemoteAgent } from "eve";
+import { vercelOidc } from "eve/agents/auth";
+
+export default defineRemoteAgent({
+  url: "https://site-ops.example.com",
+  description: "Executes site operations as the requesting user.",
+  auth: vercelOidc(), // transport trust: authenticates *this* deployment
+  forwardPrincipal: true, // identity: asserts the current session principal
+});
+```
+
+The create-session request then carries the parent turn's `session.auth.current` and `session.auth.initiator` as a `forwardedPrincipal` body field (`initiator` is optional on the wire; when absent, the receiver seeds both from `current`). Only principal metadata crosses the wire — never tokens or credentials. The receiving deployment mints its own per-user credentials through its own connections.
+
+Forwarding is explicit on both sides. The receiver names which forwarders it trusts with `eveChannel({ trustedForwarders })` (see [Auth & route protection](./auth-and-route-protection#accepting-forwarded-identity-from-another-deployment)); a receiver that refuses the forwarder — or has no `trustedForwarders` at all — rejects with a 403 and the dispatch fails. One caveat: a receiver on an eve version that predates principal forwarding drops the unknown field and runs the session as your app's service identity (per-user connections there fail with `principal_required`), so upgrade both deployments together when enabling forwarding. When the dispatching turn has no auth at all, the field is omitted and the call proceeds on transport trust alone.
+
 ## How remote dispatch and callbacks work
 
 A local subagent runs inline. A remote one runs in its own deployment, so dispatch is asynchronous:

package/docs/installation.mdx

@@ -0,0 +1,60 @@
+---
+title: "Installation"
+description: "Create an eve project, configure a model credential, and run it locally."
+contentType: "How-to"
+---
+
+Create an eve project with `eve init`. The scaffold installs dependencies, creates the agent files, and starts the local development server.
+
+## Configure a model credential
+
+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`.
+
+You can also use a direct provider model. Install its AI SDK provider package and set that provider's API key before you run the agent.
+
+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 `my-agent/`, installs dependencies, initializes Git, and starts eve's development server. If a supported coding-agent REPL is available, eve offers to open it instead.
+
+## Run the agent
+
+From the project root, run the generated development command:
+
+```bash
+cd my-agent
+npm run dev
+```
+
+The terminal UI sends messages to your agent. Stop the server with Ctrl+C when you need your shell for another command.
+
+## Add eve to an existing project
+
+Run `eve init .` from a project with a `package.json` and no existing `agent/` files:
+
+```bash
+npx eve@latest init .
+```
+
+eve adds the missing `eve`, `ai`, and `zod` dependencies without changing files the project already owns.
+
+## Install manually
+
+Install the runtime dependencies when you do not want to use the scaffold:
+
+```bash
+npm install eve@latest ai zod
+```
+
+Declare Node.js 24 in `package.json`, then create `agent/agent.ts` and `agent/instructions.md`. [Project structure](/docs/project-structure) shows the required layout, and [`agent.ts`](./agent-config) documents the runtime configuration.
+
+## Continue building
+
+Read [Project structure](/docs/project-structure) before adding instructions, tools, connections, or channels.

package/docs/meta.json

@@ -1,8 +1,10 @@
 {
   "pages": [
-    "introduction",
+    "---Getting Started---",
     "getting-started",
-    "---",
+    "installation",
+    "project-structure",
+    "---Build Your Agent---",
     "agent-config",
     "instructions",
     "tools",
@@ -14,12 +16,11 @@
     "subagents",
     "schedules",
     "evals",
-    "---",
+    "---Learn More---",
+    "tutorial",
     "guides",
     "concepts",
     "patterns",
-    "---",
-    "reference",
-    "tutorial"
+    "reference"
   ]
 }

package/docs/project-structure.mdx

@@ -0,0 +1,53 @@
+---
+title: "Project Structure"
+description: "Learn the files eve discovers and how their paths define agent capabilities."
+contentType: "Conceptual"
+---
+
+eve builds an agent from files under `agent/`. A file's location determines what eve loads, and most paths also determine the capability's name.
+
+## Start with two files
+
+A minimal agent needs an instructions file and optional runtime configuration:
+
+```text
+my-agent/
+├── package.json
+├── agent/
+│   ├── agent.ts
+│   └── instructions.md
+└── evals/
+```
+
+`agent/instructions.md` is the agent's always-on system prompt. `agent/agent.ts` selects the model and configures runtime behavior. Omit `agent.ts` when the defaults are sufficient.
+
+## Add capabilities as directories
+
+Add a directory when the agent needs that capability:
+
+| Path                                | Purpose                                       |
+| ----------------------------------- | --------------------------------------------- |
+| [`tools/`](./tools)                 | Typed functions the model can call            |
+| [`skills/`](./skills)               | Procedures the model loads when useful        |
+| [`channels/`](./channels/overview)  | HTTP and messaging entry points               |
+| [`connections/`](/docs/connections) | MCP and OpenAPI services                      |
+| [`sandbox/`](./sandbox)             | Controlled workspace files and commands       |
+| [`subagents/`](./subagents)         | Specialist agents the root agent delegates to |
+| [`schedules/`](./schedules)         | Recurring work                                |
+| `lib/`                              | Shared code imported by agent files           |
+
+The `evals/` directory sits beside `agent/`. It holds the checks that measure whether the agent completes its tasks. See [Evals](./evals/overview).
+
+## Let paths name capabilities
+
+The path supplies the name. This tool file becomes the `get_weather` tool:
+
+```text
+agent/tools/get_weather.ts
+```
+
+The same rule applies to connections, skills, and subagents. You do not add a duplicate `name` or `id` field to the definition.
+
+## Use the full layout reference
+
+[Project layout](./reference/project-layout) lists every supported slot, the root and subagent boundaries, and the file-discovery rules.

package/docs/reference/cli.md

@@ -240,7 +240,7 @@ See [Evals](../evals/overview) for authoring evals.
 eve channels add [kind] [-f] [-y]
 ```
 
-Scaffolds a channel into `agent/channels/`. With no `kind` it prompts interactively; pass a `kind` (`slack` \| `web`) to scaffold one directly.
+Scaffolds a channel into `agent/channels/`. With no `kind` it prompts interactively; pass a `kind` (`slack` \| `web`) to scaffold one directly. When the Vercel CLI has an authenticated session, eve scaffolds the Vercel-integrated variant and asks whether to deploy after setup. Without one, Slack setup asks whether to set up Vercel Connect or use portable credentials. The portable variant reads `SLACK_BOT_TOKEN` and `SLACK_SIGNING_SECRET` and adds both names to `.env.example`.
 
 | Flag          | Type | Default | Description                                               |
 | ------------- | ---- | ------- | --------------------------------------------------------- |

package/docs/tutorial/meta.json

@@ -1,5 +1,5 @@
 {
-  "title": "Build an Agent",
+  "title": "Tutorial",
   "pages": [
     "first-agent",
     "how-it-runs",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve",
-  "version": "0.27.5",
+  "version": "0.27.7",
   "private": false,
   "description": "Filesystem-first framework for durable backend AI agents that run anywhere.",
   "keywords": [