eve 0.10.0 → 0.11.0

package/docs/guides/remote-agents.md

@@ -3,9 +3,9 @@ title: "Remote Agents"
 description: "Call another Eve deployment as a subagent with defineRemoteAgent: same lowered tool shape, outbound auth, durable callback dispatch."
 ---
 
-Sometimes the specialist you want to delegate to isn't a directory in your repo, it's a separately owned agent living behind its own URL. `defineRemoteAgent` lets you call another Eve deployment as if it were a local subagent.
+`defineRemoteAgent` calls a separately deployed Eve agent as if it were a local subagent. Reach for it when the specialist you delegate to is a separately owned agent behind its own URL rather than a directory in your repo.
 
-The file lives under `agent/subagents/`, so its tool name is still derived from the path. There's no `name` field.
+The file lives under `agent/subagents/`, so its tool name is derived from the path. There's no `name` field.
 
 ```ts title="agent/subagents/weather.ts"
 import { defineRemoteAgent } from "eve";
@@ -20,20 +20,22 @@ export default defineRemoteAgent({
 
 `defineRemoteAgent` accepts:
 
-- `url`: the remote Eve deployment root. Required.
-- `description`: the model-visible delegation description. Required.
-- `auth`: optional outbound auth hook from `eve/agents/auth`.
-- `headers`: optional static or lazy request headers.
-- `path`: optional session-create path; defaults to `/eve/v1/session`.
-- `outputSchema`: optional 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`                        | Yes      | n/a               | Base URL of the remote Eve deployment to call.                                                                                                  |
+| `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. |
 
 ## The lowered tool
 
-A remote agent lowers to the same `{ message, outputSchema? }` tool shape as a local subagent. The parent packs everything the remote needs into `message`; the remote never sees the parent's history. Set `outputSchema` (here or per call) and the remote runs in task mode, returning structured output as the tool result.
+A remote agent lowers to the same `{ message, outputSchema? }` tool shape as a local subagent. The parent packs everything the remote needs into `message`. The remote never sees the parent's history. Set `outputSchema` (here or per call) and the remote runs in task mode (a single-shot delegation that returns one structured result instead of an open conversation; see [Subagents](../subagents)), returning structured output as the tool result.
 
 ## Outbound auth
 
-`auth` is an `OutboundAuthFn` from `eve/agents/auth`. It attaches request headers to the outbound dispatch:
+`auth` is an `OutboundAuthFn` from `eve/agents/auth` that attaches request headers to the outbound dispatch:
 
 | Helper                          | Header                                                                       |
 | ------------------------------- | ---------------------------------------------------------------------------- |
@@ -41,17 +43,19 @@ A remote agent lowers to the same `{ message, outputSchema? }` tool shape as a l
 | `bearer(token)`                 | `Authorization: Bearer <token>` (static or lazily resolved)                  |
 | `basic({ username, password })` | `Authorization: Basic …`                                                     |
 
-If you're 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.
+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.
 
-## Callback / park dispatch
+## How remote dispatch and callbacks work
 
-A local subagent runs inline. A remote one runs in its own deployment, so dispatch has to be asynchronous:
+A local subagent runs inline. A remote one runs in its own deployment, so dispatch is asynchronous:
 
 1. The parent starts a task-mode session on the remote's `POST /eve/v1/session`, passing a framework callback URL.
-2. The parent turn parks durably until the remote posts a terminal callback, holding no compute while it waits.
+2. The parent turn parks (suspends durably without holding compute; see [Execution model & durability](../concepts/execution-model-and-durability)) until the remote posts a terminal callback.
 3. When the callback arrives, the parent resumes and surfaces the result.
 
-The parent stream carries the same `subagent.called`, `action.result`, and `subagent.completed` events as local delegation. For a remote call, `subagent.called.data.remote.url` records the target. A failed _start_ comes back as a failed tool result, so the caller can explain or recover within the same session. Terminal callback delivery runs as a durable Workflow step on the callee: a failed callback POST is rethrown rather than marking the task complete, which puts redelivery under Workflow retry policy.
+The parent stream carries the same `subagent.called`, `action.result`, and `subagent.completed` events as local delegation. For a remote call, `subagent.called.data.remote.url` records the target.
+
+Both failure paths surface to the parent as a failed tool result, so the caller can explain or recover within the same session. A failed _start_ returns the error inline. A remote that starts and then fails posts a terminal failure callback, which the parent receives as an errored subagent result carrying the remote's error (or `REMOTE_AGENT_FAILED` when none is supplied). Terminal callback delivery runs as a durable step on the underlying workflow engine (see [Execution model & durability](../concepts/execution-model-and-durability)). A failed callback POST is rethrown rather than marking the task complete, so the engine retries it.
 
 ## What to read next
 

package/docs/guides/session-context.md

@@ -10,11 +10,11 @@ Eve exposes runtime state through the `ctx` parameter passed to tool `execute`,
 - `ctx.getSkill(identifier)`: handle for a named skill visible to the current agent
 - `defineState(name, initial)`: typed durable state with `get()` and `update()` (imported from `eve/context`)
 
-These APIs work only inside active authored runtime execution such as tools, channel event handlers, and authored hooks. They throw when called outside a managed context.
+These APIs work only inside active authored runtime execution, including tools, channel event handlers, and authored hooks. They throw when called outside a managed context.
 
 ## `ctx.session`
 
-Use `ctx.session` when you need durable runtime metadata about the current execution.
+`ctx.session` exposes durable runtime metadata about the current execution.
 
 ```ts title="agent/tools/who_called_me.ts"
 import { defineTool } from "eve/tools";
@@ -46,7 +46,7 @@ Public session fields:
 - `turn.sequence`
 - optional `parent`
 
-Important behavior:
+Behavior:
 
 - `auth.current` is the caller for the active inbound turn.
 - `auth.initiator` is the caller that started the durable session.
@@ -63,14 +63,14 @@ const sandbox = await ctx.getSandbox();
 const result = await sandbox.run({ command: "npm test" });
 ```
 
-Important behavior:
+Behavior:
 
-- It takes no arguments: each agent has exactly one sandbox.
+- It takes no arguments. Each agent has exactly one sandbox.
 - It is async because Eve binds or restores sandbox state lazily.
 - It only works when sandbox access is attached to the active runtime path.
-- Visibility is node-local: a subagent sees its own sandbox, not the parent's.
+- Visibility is node-local. A subagent sees its own sandbox, not the parent's.
 
-`SandboxSession` also exposes `resolvePath(path)` for cases where authored code needs the live backend-native path for a logical `/workspace/...` location before passing it to shell code or a child process.
+`SandboxSession` also exposes `resolvePath(path)`, which returns the live backend-native path for a logical `/workspace/...` location. Use it when authored code needs that path before passing it to shell code or a child process.
 
 See [Sandbox](../sandbox) for lifecycle details.
 
@@ -83,20 +83,20 @@ const skill = ctx.getSkill("research");
 const notes = await skill.file("references/checklist.md").text();
 ```
 
-Important behavior:
+Behavior:
 
-- It is synchronous; file content is read lazily from the active sandbox.
+- It is synchronous. File content is read lazily from the active sandbox.
 - It only works when sandbox access is attached to the active runtime path.
 - `identifier` is the path-derived skill id.
 - Visibility follows the current agent's sandbox.
-- Missing skills surface when a file accessor reads a missing sandbox path.
+- A missing skill surfaces when a file accessor reads a missing sandbox path.
 - The returned handle exposes `name` and `file(relativePath)`.
 
 See [Skills](../skills) for the full authoring model.
 
 ## Custom state with `defineState`
 
-Use `defineState` when your agent needs durable typed state that tools, hooks, and channel handlers can share. State survives across workflow step boundaries. Declare the handle at module scope so every importer shares it:
+Use `defineState` when your agent needs durable typed state that tools, hooks, and channel handlers can share. State survives workflow step boundaries. Declare the handle at module scope so every importer shares it:
 
 ```ts title="agent/lib/budget.ts"
 import { defineState } from "eve/context";
@@ -139,7 +139,7 @@ The framework sets up a context container before invoking authored code:
 3. Authored code runs inside the managed scope, so `ctx` and `defineState` accessors resolve automatically.
 4. After the step, the framework commits mutable state (for example sandbox changes) back to the durable session.
 
-This lifecycle is fully managed by the framework. Authored code only needs to use `ctx` and the public accessors.
+The framework manages this lifecycle. Authored code only uses `ctx` and the public accessors.
 
 ## What to read next
 

package/docs/guides/state.md

@@ -3,7 +3,7 @@ title: "State"
 description: "Durable per-session memory with defineState: get() and update(), persisted across step boundaries."
 ---
 
-`defineState` is a typed, named slot of durable per-session memory for an agent. Use it when the agent has to remember something between the turns of a conversation (a running budget, a glossary, a checklist) and you don't want to stand up an external store for it. The values survive workflow step boundaries, so they outlast crashes, redeploys, and days-long sessions.
+`defineState` is a typed, named slot of durable per-session memory for an agent. Use it when the agent has to remember something between conversation turns (a running budget, a glossary, a checklist) and you don't want to stand up an external store for it. The values survive workflow step boundaries, so they outlast crashes, redeploys, and days-long sessions.
 
 ```ts
 import { defineState } from "eve/context";
@@ -16,14 +16,19 @@ Pass `defineState(name, initial)` a stable string `name` (namespace it to your a
 - `get()`: read the current value. Returns `initial()` on first access within a context.
 - `update(fn)`: replace the value with `fn(current)`.
 
-Use the handle from inside a tool, hook, or other framework-managed runtime code:
+Declare the handle once at module scope and import it wherever you read or write the slot. Use it from inside a tool, hook, or other framework-managed runtime code:
 
-```ts title="agent/tools/spend.ts"
+```ts title="agent/lib/budget.ts"
 import { defineState } from "eve/context";
+
+export const budget = defineState("my-agent.budget", () => ({ count: 0, cap: 25 }));
+```
+
+```ts title="agent/tools/spend.ts"
 import { defineTool } from "eve/tools";
 import { z } from "zod";
-
-const budget = defineState("my-agent.budget", () => ({ count: 0, cap: 25 }));
+import { budget } from "../lib/budget.js";
+import { runQuery } from "../lib/warehouse.js";
 
 export default defineTool({
   description: "Run a query, counting it against the session budget.",
@@ -43,20 +48,31 @@ export default defineTool({
 
 State is durable by default and does not reset between turns. If you want a clean slate every turn, overwrite it from a lifecycle [hook](./hooks) on `turn.started`:
 
-```ts
-budget.update(() => ({ count: 0, cap: 25 }));
+```ts title="agent/hooks/reset-budget.ts"
+import { defineHook } from "eve/hooks";
+import { budget } from "../lib/budget.js";
+
+export default defineHook({
+  events: {
+    async "turn.started"() {
+      budget.update(() => ({ count: 0, cap: 25 }));
+    },
+  },
+});
 ```
 
+The hook imports the same module-scope `budget` handle as the tool, so both read and write the same slot.
+
 ## State is never shared with subagents
 
 Every [subagent](../subagents) starts with its own fresh state, whether it's a built-in `agent` copy or a declared specialist. `defineState` values never cross the parent/child boundary, even when the child is a copy of the same agent.
 
 ## State vs. connection-side storage
 
-`defineState` is for conversation-scoped working memory that lives and dies with the session: counters, the current plan, what the user has told you this conversation. Anything that has to outlive the session, be shared across sessions or users, or be queried independently of a turn belongs in an external store, either a [connection](../connections) or your own database. State is not a database. It's the agent's short-term memory, persisted durably for the life of the session.
+`defineState` holds conversation-scoped working memory that lives and dies with the session, including counters, the current plan, and what the user has told you this conversation. It is the agent's short-term memory, persisted durably for the life of the session. Anything that has to outlive the session, be shared across sessions or users, or be queried independently of a turn belongs in an external store, either a [connection](../connections) or your own database.
 
 ## What to read next
 
 - Read state inside dynamic resolvers → [Dynamic capabilities](./dynamic-capabilities)
 - How step durability works → [Execution model & durability](../concepts/execution-model-and-durability)
-- The `ctx` accessors available alongside state → [Tools](../tools)
+- The `ctx` accessors available alongside state → [TypeScript API](../reference/typescript-api)

package/docs/instructions.mdx

@@ -3,19 +3,17 @@ title: "Instructions"
 description: "Author the agent's always-on system prompt with instructions.md or instructions.ts."
 ---
 
-Instructions are the always-on system prompt. Use them for whatever should hold on every turn: a rule, a persona, a constraint. This is the agent's permanent identity, not a procedure it pulls in when the moment calls for it.
-
-Eve prepends the instructions to every model call in the session.
+Instructions are the always-on system prompt, the agent's permanent identity rather than a procedure it pulls in when the moment calls for it. Use them for anything that should hold on every turn, such as a rule, a persona, or a constraint. Eve prepends the instructions to every model call in the session.
 
 ## Author instructions
 
-In the simplest case, instructions are a markdown file at the agent root. Whatever you write is the prompt.
+At minimum, instructions are a markdown file at the agent root. Whatever you write is the prompt:
 
 ```md title="agent/instructions.md"
 You are a concise assistant. Use tools when they are available.
 ```
 
-Keep this file to stable behavior that applies on every turn: identity, tone, standing rules.
+Keep this file to stable behavior such as identity, tone, and standing rules.
 
 ## Markdown vs TypeScript
 
@@ -30,11 +28,15 @@ export default defineInstructions({
 });
 ```
 
-`defineInstructions` takes one field, `markdown`, which is the resolved prompt text. A module-backed prompt runs once at build time. Eve captures the resulting markdown into the compiled manifest, so the runtime serves the same prompt every session and never re-runs the module.
+`defineInstructions` takes one field, `markdown`, the resolved prompt text. A module-backed prompt runs once at build time. Eve captures the resulting markdown into the compiled manifest, so the runtime serves the same prompt every session and never re-runs the module.
+
+## Split instructions across a directory
+
+For more than one file, add an `agent/instructions/` directory. Eve reads its entries non-recursively and accepts both `.md` files and `.ts` modules (a `.ts` file can wrap `defineInstructions` or `defineDynamic`). Entries combine in alphabetical order by filename (`localeCompare`).
 
-Got more than one file? An `agent/instructions/` directory works too. Use either `instructions.md` or `instructions.ts` at the agent root, not both.
+A flat `agent/instructions.md` (or `.ts`) at the agent root and the directory can coexist. The root file's content comes first, then the sorted directory entries. You cannot author both `instructions.md` and `instructions.ts` at the root; that pairing is a build error.
 
-## How it differs from skills
+## Instructions vs skills
 
 Instructions and [skills](./skills) both feed text into the model's context. The difference is timing:
 
@@ -43,13 +45,19 @@ Instructions and [skills](./skills) both feed text into the model's context. The
 | `instructions.md` / `.ts` | Always on, every turn                        | Permanent identity and standing rules                |
 | `agent/skills/*`          | On demand, when the model calls `load_skill` | Optional procedures that should not bloat every turn |
 
-Keep instructions short and stable. Long or situational procedures belong in skills, where they only enter context when the request calls for them. See [Skills](./skills).
+Keep instructions short and stable. Long or situational procedures belong in [skills](./skills), where they only enter context when the request calls for them.
 
 Instructions never run code. When you need typed executable behavior, reach for a [tool](./tools).
 
 ## Dynamic instructions
 
-Need the prompt resolved at runtime from session context (auth, tenant, channel)? Wrap `defineInstructions` in a `defineDynamic` resolver. See [Dynamic capabilities](./guides/dynamic-capabilities).
+To resolve the prompt at runtime from session context (auth, tenant, or channel), wrap `defineInstructions` in a `defineDynamic` resolver. See [Dynamic capabilities](./guides/dynamic-capabilities).
+
+## Disclaimer
+
+As the deployer, it is your responsibility to ensure your agent complies with applicable laws.
+
+Where an Eve agent communicates with people, you may be required to disclose that they are interacting with an automated AI system where law requires it. Eve does not add this disclosure automatically; configure it in your instructions and/or channel responses.
 
 ## What to read next
 

package/docs/introduction.md

@@ -5,7 +5,9 @@ description: "How an Eve agent is laid out as files, what runs when a message ar
 
 Eve is a framework for building durable agents as ordinary files in a TypeScript project.
 
-Instead of describing your whole agent in one large configuration object, you give each part a clear home: instructions go in one file, tools in one folder, channels in another. Eve discovers that structure and turns it into an agent that runs locally, serves HTTP, connects to other platforms, and keeps working across many turns.
+Instead of one large configuration object, each part of your agent gets a clear home. Instructions go in one file, tools in one folder, channels in another. Eve discovers that structure and turns it into an agent that runs locally, serves HTTP, connects to other platforms, and keeps working across many turns.
+
+Eve is currently in beta and subject to the [Vercel beta terms](https://vercel.com/docs/release-phases/public-beta-agreement). The framework, APIs, documentation, and behavior may change before general availability.
 
 ## An Eve project at a glance
 
@@ -37,9 +39,7 @@ Start with only `instructions.md` and `agent.ts`. Add the other folders when the
 
 ## The files are the interface
 
-Eve is [filesystem-first](./reference/project-layout): a file's location says what it does, and its path usually gives it a name.
-
-For example, this file:
+Eve is [filesystem-first](./reference/project-layout). A file's location says what it does, and its path usually gives it a name. For example, this file:
 
 ```text
 agent/tools/get_weather.ts
@@ -64,7 +64,7 @@ There is no separate registry to keep in sync. Add the file and Eve discovers it
 
 ## What happens when a message arrives
 
-Whether a message comes from a web app, the terminal, or Slack, the same flow runs. Eve turns the platform input into a message, gives the model its instructions, skills, tools, and conversation history, runs the work (calling tools and subagents as needed), saves the session and streams events, then delivers the result back in the form the platform expects.
+The same flow runs whether a message comes from a web app, the terminal, or Slack. Eve turns the platform input into a message, gives the model its instructions, skills, tools, and conversation history, runs the work (calling tools and subagents as needed), saves the session and streams events, then delivers the result back in the form the platform expects.
 
 That keeps agent behavior portable. Your weather tool does not need to know whether the question came from a browser or from Slack.
 
@@ -72,13 +72,13 @@ That keeps agent behavior portable. Your weather tool does not need to know whet
 
 An Eve session is more than one request and one response. It can:
 
-- stream progress while work is happening
-- call tools and subagents
-- pause for [approval or a human answer](./tools)
-- resume after that answer arrives
-- keep durable state across turns
+- Stream progress while work is happening
+- Call tools and subagents
+- Pause for [approval or a human answer](./tools)
+- Resume after that answer arrives
+- Keep durable state across turns
 
-Under the hood, Eve uses the open-source [Workflow SDK](https://workflow-sdk.dev) to make sessions durable, resumable, and crash-safe. Eve handles that machinery so your tools can focus on the work itself.
+Under the hood, Eve uses the open-source [Workflow SDK](https://workflow-sdk.dev) to make sessions durable, resumable, and crash-safe. Eve handles that machinery so your tools focus on the work itself.
 
 ## Grow the project by adding capabilities
 
@@ -93,7 +93,7 @@ As the agent grows, each concern still has a predictable home:
 | [`schedules/`](./schedules)     | Recurring or scheduled work                      |
 | `lib/`                          | Shared code imported by the other agent files    |
 
-The result stays readable before it runs: the directory tells you what the agent can do.
+The result stays readable before it runs. The directory tells you what the agent can do.
 
 ## What to read next
 

package/docs/legal.md

@@ -0,0 +1,16 @@
+---
+title: "Legal"
+description: "Preview status, deployer responsibility, and safeguards to review before using Eve with sensitive, regulated, or production data."
+---
+
+Eve is currently a preview and subject to the Vercel beta terms; the framework, APIs, documentation, and behavior may change before general availability.
+
+As the deployer, it is your responsibility to ensure your agent complies with applicable laws.
+
+You are responsible for configuring approval policies, tool restrictions, connection scopes, route/session authorization, sandbox controls, telemetry exports, and other safeguards appropriate for your use case.
+
+Before using Eve with non-public, sensitive, regulated, or production data, review which default tools, custom tools, MCP tools, shell/file/web tools, connected services, subagents, schedules, and external actions are available to the agent.
+
+Require human approval or other safeguards for sensitive, irreversible, regulated, financial, healthcare, employment, housing, legal, safety-impacting, user-impacting, or external side-effecting actions.
+
+Unless you configure stricter controls, Eve agents may operate with permissive settings, including tool execution without human approval where approval is omitted and sandbox network egress that is not deny-all. Do not rely on model behavior alone to prevent sensitive or irreversible actions.

package/docs/meta.json

@@ -2,6 +2,7 @@
   "pages": [
     "introduction",
     "getting-started",
+    "legal",
     "---",
     "agent-config",
     "instructions",

package/docs/reference/cli.md

@@ -1,38 +1,59 @@
 ---
 title: "CLI"
-description: "eve command reference: info, build, start, dev, eval."
+description: "Reference for every eve CLI command: init, info, build, start, dev, link, deploy, eval, and channels."
 ---
 
-The `eve` binary (`bin: eve`) runs from your app root, and every command loads `.env`/`.env.local` from that root before it does anything else.
+The `eve` binary (`bin: eve`) runs from your app root, and every command first loads `.env`/`.env.local` from that root. Running `eve` with no command runs `eve dev`.
+
+Eve is currently a preview and subject to the Vercel beta terms; the framework, APIs, documentation, and behavior may change before general availability.
 
 ## Commands
 
-| Command                   | Does                                                                                                                                        |
-| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| `eve info`                | Print the resolved application: discovered tools, skills, subagents, schedules, channels, routes, artifact paths, and discovery diagnostics |
-| `eve build`               | Compile `.eve/` artifacts and build the host output; prints the output directory                                                            |
-| `eve start`               | Serve the built `.output/` app; prints the listening URL                                                                                    |
-| `eve dev`                 | Start the local dev server and open the terminal UI                                                                                         |
-| `eve dev <url>`           | Connect the UI to an existing server URL (e.g. a remote deployment) instead of booting a local server                                       |
-| `eve link`                | Link the directory to a Vercel project and pull AI Gateway credentials                                                                      |
-| `eve deploy`              | Deploy the agent to Vercel production (links first if needed)                                                                               |
-| `eve eval`                | Run evals against the local app or a remote target                                                                                          |
-| `eve channels add [kind]` | Scaffold a channel interactively, or by kind (`slack` \| `web`)                                                                             |
-| `eve channels list`       | List user-authored channels                                                                                                                 |
+| Command                   | Description                                                                                                                                           |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `eve init [target]`       | Scaffold a new agent, or add one to an existing project directory                                                                                     |
+| `eve info`                | Print the resolved application, including discovered tools, skills, subagents, schedules, channels, routes, artifact paths, and discovery diagnostics |
+| `eve build`               | Compile `.eve/` artifacts and build the host output; prints the output directory                                                                      |
+| `eve start`               | Serve the built `.output/` app; prints the listening URL                                                                                              |
+| `eve dev`                 | Start the local dev server and open the terminal UI                                                                                                   |
+| `eve dev <url>`           | Connect the UI to an existing server URL (e.g. a remote deployment) instead of booting a local server                                                 |
+| `eve link`                | Link the directory to a Vercel project and pull AI Gateway credentials                                                                                |
+| `eve deploy`              | Deploy the agent to Vercel production (links first if needed)                                                                                         |
+| `eve eval`                | Run evals against the local app or a remote target                                                                                                    |
+| `eve channels add [kind]` | Scaffold a channel interactively, or by kind (`slack` \| `web`)                                                                                       |
+| `eve channels list`       | List user-authored channels                                                                                                                           |
 
 When `eve build` fails on discovery errors, it prints the full diagnostics report (severity, message, source path) and the diagnostics artifact path.
 
+## `eve init`
+
+```bash
+eve init [target] [--channel-web-nextjs]
+```
+
+The optional `target` decides the mode:
+
+- A name (`eve init my-agent`) scaffolds a fresh project in a new `my-agent/` directory.
+- An existing directory, including `.` for the current one (`eve init .`), adds an agent to that project. The project needs a `package.json`, the `agent/` files must not exist yet, and the missing `eve`, `ai`, and `zod` dependencies are added without touching anything else.
+- Omitting the target scaffolds or updates the current directory, the same as `eve init .`.
+
+Either mode installs dependencies, initializes Git, and runs `eve dev` through the project's package manager.
+
+| Flag                   | Type | Default | Description                                                                                                                            |
+| ---------------------- | ---- | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `--channel-web-nextjs` | flag | off     | Add the Web Chat application (a Next.js app). Rejected when adding to an existing project; run `eve channels add web` there afterward. |
+
 ## `eve info`
 
 ```bash
 eve info [--json]
 ```
 
-| Flag     | Effect       |
-| -------- | ------------ |
-| `--json` | Emit as JSON |
+| Flag     | Type | Default | Description  |
+| -------- | ---- | ------- | ------------ |
+| `--json` | flag | off     | Emit as JSON |
 
-When something behaves unexpectedly, run this first. It confirms a file was discovered, lists the active surface, and surfaces discovery diagnostics, all faster than booting the dev server.
+Run this first when something behaves unexpectedly. It confirms a file was discovered, lists the active surface, and surfaces discovery diagnostics, all faster than booting the dev server.
 
 ## `eve build`
 
@@ -44,7 +65,7 @@ No flags. Compiles to `.eve/` and builds the host output, then prints the built
 
 Useful artifacts written under `.eve/` (preserved even on partial failure):
 
-| Artifact                                       | Tells you                                            |
+| Artifact                                       | Description                                          |
 | ---------------------------------------------- | ---------------------------------------------------- |
 | `.eve/discovery/agent-discovery-manifest.json` | What Eve found on disk                               |
 | `.eve/discovery/diagnostics.json`              | Authored-shape errors and warnings                   |
@@ -58,10 +79,10 @@ Useful artifacts written under `.eve/` (preserved even on partial failure):
 eve start [--host <host>] [--port <port>]
 ```
 
-| Flag            | Effect                                               |
-| --------------- | ---------------------------------------------------- |
-| `--host <host>` | Host interface to bind                               |
-| `--port <port>` | Port to listen on (defaults to `$PORT`, then `3000`) |
+| Flag            | Type   | Default            | Description            |
+| --------------- | ------ | ------------------ | ---------------------- |
+| `--host <host>` | string | all interfaces     | Host interface to bind |
+| `--port <port>` | number | `$PORT`, then 3000 | Port to listen on      |
 
 Serves the previously built output. Prints the listening URL.
 
@@ -72,27 +93,27 @@ eve dev [options]
 eve dev https://your-app.vercel.app
 ```
 
-Pass a bare URL as the only argument and the UI connects to that server instead of booting a local one (same as `--url`). That's handy for smoke-testing a preview or production deployment. The interactive UI turns off in a non-TTY terminal.
-
-| Flag                                | Effect                                                                                    |
-| ----------------------------------- | ----------------------------------------------------------------------------------------- |
-| `--host <host>`                     | Host interface to bind                                                                    |
-| `--port <port>`                     | Port to listen on (defaults to `$PORT`, then `2000`)                                      |
-| `-u, --url <url>`                   | Connect to an existing server URL instead of starting one                                 |
-| `--no-ui`                           | Start the server without an interactive UI                                                |
-| `--name <name>`                     | Title shown in the terminal UI (defaults to the app folder name)                          |
-| `--input <text>`                    | Pre-fill the prompt input after launching the UI (editable; not auto-submitted)           |
-| `--tools <mode>`                    | Tool-call rendering: `full` \| `collapsed` \| `auto-collapsed` \| `hidden`                |
-| `--reasoning <mode>`                | Reasoning rendering: `full` \| `collapsed` \| `auto-collapsed` \| `hidden`                |
-| `--subagents <mode>`                | Subagent-section rendering: `full` \| `collapsed` \| `auto-collapsed` \| `hidden`         |
-| `--connection-auth <mode>`          | Connection-authorization rendering: `full` \| `collapsed` \| `auto-collapsed` \| `hidden` |
-| `--assistant-response-stats <mode>` | Assistant header statistic: `tokens` \| `tokensPerSecond`                                 |
-| `--context-size <tokens>`           | Model context window size, shown as a usage percentage                                    |
-| `--logs <mode>`                     | Server/agent logs to show: `all` \| `stderr` \| `sandbox` \| `none`                       |
+Pass a bare URL as the only argument and the UI connects to that server instead of booting a local one (same as `--url`), which lets you smoke-test a preview or production deployment. The interactive UI turns off in a non-TTY terminal.
+
+| Flag                                | Type   | Default            | Description                                                                               |
+| ----------------------------------- | ------ | ------------------ | ----------------------------------------------------------------------------------------- |
+| `--host <host>`                     | string | all interfaces     | Host interface to bind                                                                    |
+| `--port <port>`                     | number | `$PORT`, then 3000 | Port to listen on                                                                         |
+| `-u, --url <url>`                   | string | none               | Connect to an existing server URL instead of starting one                                 |
+| `--no-ui`                           | flag   | UI on              | Start the server without an interactive UI                                                |
+| `--name <name>`                     | string | app folder name    | Title shown in the terminal UI                                                            |
+| `--input <text>`                    | string | none               | Pre-fill the prompt input after launching the UI (editable, not auto-submitted)           |
+| `--tools <mode>`                    | enum   | `auto-collapsed`   | Tool-call rendering: `full` \| `collapsed` \| `auto-collapsed` \| `hidden`                |
+| `--reasoning <mode>`                | enum   | `full`             | Reasoning rendering: `full` \| `collapsed` \| `auto-collapsed` \| `hidden`                |
+| `--subagents <mode>`                | enum   | `auto-collapsed`   | Subagent-section rendering: `full` \| `collapsed` \| `auto-collapsed` \| `hidden`         |
+| `--connection-auth <mode>`          | enum   | `full`             | Connection-authorization rendering: `full` \| `collapsed` \| `auto-collapsed` \| `hidden` |
+| `--assistant-response-stats <mode>` | enum   | `tokensPerSecond`  | Assistant header statistic: `tokens` \| `tokensPerSecond`                                 |
+| `--context-size <tokens>`           | number | none               | Model context window size, shown as a usage percentage                                    |
+| `--logs <mode>`                     | enum   | `stderr`           | Server/agent logs to show: `all` \| `stderr` \| `sandbox` \| `none`                       |
 
 Local dev writes the active server process ID to `.eve/dev-process.pid`. If another `eve dev` starts for the same agent while that process is still running, Eve exits with a message that includes the command to stop the existing server.
 
-Local dev keeps immutable runtime source snapshots under `.eve/dev-runtime/snapshots/` so in-flight sessions keep a consistent code revision while new prompts pick up rebuilds. `eve dev` prunes stale runtime snapshots and old local sandbox templates in the background on startup; stopping `eve dev` and deleting `.eve/dev-runtime/snapshots/` or `.eve/sandbox-cache/local/templates/` is safe when you want a manual cleanup.
+Local dev keeps immutable runtime source snapshots under `.eve/dev-runtime/snapshots/` so in-flight sessions hold a consistent code revision while new prompts pick up rebuilds. On startup, `eve dev` prunes stale runtime snapshots and old local sandbox templates in the background. For manual cleanup, stop `eve dev` and delete `.eve/dev-runtime/snapshots/` or `.eve/sandbox-cache/local/templates/`.
 
 ## `eve link`
 
@@ -100,7 +121,7 @@ Local dev keeps immutable runtime source snapshots under `.eve/dev-runtime/snaps
 eve link
 ```
 
-Links the current directory to an existing Vercel project by selecting a team and then a project, then pulls the project's environment so an AI Gateway credential (`VERCEL_OIDC_TOKEN` or `AI_GATEWAY_API_KEY`) lands in `.env.local`, and verifies one actually did. Running it again re-links: the pickers always run, and the new choice wins. Interactive only — in CI, use `vercel link --project <name> --yes` instead. A running `eve dev` reloads env files automatically, so no restart is needed after the pull.
+Links the current directory to an existing Vercel project. You select a team and then a project, and Eve pulls the project's environment so an AI Gateway credential (`VERCEL_OIDC_TOKEN` or `AI_GATEWAY_API_KEY`) lands in `.env.local`, then verifies one actually did. Running it again re-links: the pickers always run, and the new choice wins. The command is interactive only; in CI, use `vercel link --project <name> --yes` instead. A running `eve dev` reloads env files automatically, so you don't need to restart after the pull.
 
 ## `eve deploy`
 
@@ -108,7 +129,7 @@ Links the current directory to an existing Vercel project by selecting a team an
 eve deploy
 ```
 
-Deploys the agent to Vercel production (`vercel deploy --prod`), installing dependencies first and pulling environment variables after. An already-linked project deploys with or without a TTY (non-interactive runs pass the non-interactive `vercel` flags); an unlinked directory walks the `eve link` pickers when a terminal is present, and exits with guidance otherwise.
+Deploys the agent to Vercel production (`vercel deploy --prod`), installing dependencies first and pulling environment variables after. An already-linked project deploys with or without a TTY (non-interactive runs pass the non-interactive `vercel` flags). An unlinked directory walks the `eve link` pickers when a terminal is present, and exits with guidance otherwise.
 
 ## `eve eval`
 
@@ -118,19 +139,46 @@ eve eval [evalId...] [--url <url>] [options]
 
 Runs all discovered evals when no eval ids are given; ids match exactly or by directory prefix (`eve eval weather` runs everything under `evals/weather/`). Exits `0` when every eval passed its checks, `1` when any eval failed (a failed check, an execution error, or a `--strict` threshold miss), `2` on configuration errors.
 
-| Flag                    | Effect                                         |
-| ----------------------- | ---------------------------------------------- |
-| `--url <url>`           | Remote agent URL (skip local host startup)     |
-| `--tag <tag...>`        | Run only evals carrying a tag                  |
-| `--strict`              | Below-threshold scores also fail the exit code |
-| `--list`                | Print discovered evals without running them    |
-| `--timeout <ms>`        | Per-eval timeout in milliseconds               |
-| `--max-concurrency <n>` | Max concurrent eval executions (default 8)     |
-| `--json`                | Output results as JSON                         |
-| `--skip-report`         | Skip eval-defined reporters (e.g. Braintrust)  |
+| Flag                    | Type   | Default | Description                                    |
+| ----------------------- | ------ | ------- | ---------------------------------------------- |
+| `--url <url>`           | string | none    | Remote agent URL (skip local host startup)     |
+| `--tag <tag...>`        | string | none    | Run only evals carrying a tag                  |
+| `--strict`              | flag   | off     | Below-threshold scores also fail the exit code |
+| `--list`                | flag   | off     | Print discovered evals without running them    |
+| `--timeout <ms>`        | number | none    | Per-eval timeout in milliseconds               |
+| `--max-concurrency <n>` | number | 8       | Max concurrent eval executions                 |
+| `--json`                | flag   | off     | Output results as JSON                         |
+| `--junit <path>`        | string | none    | Write JUnit XML results to a file              |
+| `--skip-report`         | flag   | off     | Skip eval-defined reporters (e.g. Braintrust)  |
+| `--verbose`             | flag   | off     | Stream per-eval `t.log` lines to stdout        |
 
 See [Evals](../evals/overview) for authoring evals.
 
+## `eve channels add`
+
+```bash
+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.
+
+| Flag          | Type | Default | Description                                               |
+| ------------- | ---- | ------- | --------------------------------------------------------- |
+| `-f, --force` | flag | off     | Overwrite existing channel files                          |
+| `-y, --yes`   | flag | off     | Assume yes for confirmations; requires an explicit `kind` |
+
+## `eve channels list`
+
+```bash
+eve channels list [--json]
+```
+
+Lists the user-authored channels in the current project.
+
+| Flag     | Type | Default | Description    |
+| -------- | ---- | ------- | -------------- |
+| `--json` | flag | off     | Output as JSON |
+
 ## Recommended loop
 
 1. Edit files under `agent/`.

package/docs/reference/meta.json

@@ -1,4 +1,4 @@
 {
   "title": "Reference",
-  "pages": ["typescript-api", "cli", "project-layout"]
+  "pages": ["http-api", "typescript-api", "cli", "project-layout"]
 }