eve 0.9.8 → 0.11.0

package/docs/tutorial/connect-a-warehouse.mdx

@@ -1,9 +1,11 @@
 ---
-title: "Step 4: Connect a Warehouse"
-description: "Let each user connect their own warehouse over an OAuth MCP via Vercel Connect."
+title: "Connect a Warehouse"
+description: "Part 4 of the Build an Agent tutorial. Let each user connect their own warehouse over an OAuth MCP via Vercel Connect."
 ---
 
-The sample dataset got you running, but it's a stand-in. The next step is to point the agent at a real warehouse and let each user connect their own by signing in through their browser. That's what a connection is for: an MCP server the model reaches through tools, with auth that Eve drives for you.
+The sample dataset got the analytics assistant running, but it's a stand-in. Now point the agent at a real warehouse and let each user connect their own by signing in through their browser. That's what a connection is for. It's an MCP server the model reaches through tools, with auth that Eve drives for you.
+
+This step depends on Vercel Connect, which is in private beta. No Connect access? Keep the Step 3 sample dataset and read this step for the connection model. Steps 5 through 9 work against the sample dataset, so you can complete the tutorial without a warehouse.
 
 The filename sets the runtime name. Put the file at `agent/connections/warehouse.ts` and it registers as `"warehouse"`, with its tools surfaced as `connection__warehouse__<tool>`.
 
@@ -24,7 +26,14 @@ export default defineMcpClientConnection({
 
 `"warehouse"` is the UID you chose when registering the Connect client. By default this OAuth is user-scoped. Each end-user authorizes in their own browser, and Eve resolves that user's token before every tool call.
 
-Connect is in private beta. Once enabled: `npm install @vercel/connect`, create the Connect client (`vercel connect create <type> --name warehouse`), link it to your project, then `vercel link` and `vercel env pull` so `VERCEL_OIDC_TOKEN` is available locally. Full setup: [Connections](../connections).
+Once Connect is enabled on your account, wire it up:
+
+1. Install the package: `npm install @vercel/connect`.
+2. Create the Connect client: `vercel connect create <type> --name warehouse`.
+3. Link the client to your project.
+4. Run `vercel link` and `vercel env pull` so `VERCEL_OIDC_TOKEN` is available locally.
+
+For the full reference, see [Connections](../connections).
 
 ## What the user sees
 
@@ -34,7 +43,7 @@ Ask a question that needs the warehouse:
 How many enterprise customers signed up last month?
 ```
 
-The first time around, the model picks a warehouse tool but there's no token yet. So the turn parks and the channel shows a “Sign in” affordance. You authorize in the browser, and once the OAuth callback completes, the turn resumes from exactly that step (the durable parking from [Step 2](./how-it-runs)) and the query runs. Later calls in the session reuse the cached per-user token, so there's no prompt.
+The first time, the model picks a warehouse tool but there's no token yet, so the turn parks and the channel shows a "Sign in" affordance. You authorize in the browser, and once the OAuth callback completes, the turn resumes from exactly that step (the durable parking from [Step 2](./how-it-runs)) and the query runs. Later calls in the session reuse the cached per-user token, so there's no prompt.
 
 ## The token never reaches the model
 
@@ -42,6 +51,6 @@ Right before each request to the MCP server, Eve resolves the bearer and sends i
 
 If you want more control, gate the connection behind approval (`approval: once()`) or narrow which tools the model sees (`tools.allow`). See [Connections](../connections).
 
-→ Next: [Step 5: Run analysis](./run-analysis)
+→ Next: [Run analysis](./run-analysis)
 
-Depth: [Connections](../connections) · [Auth & route protection](../guides/auth-and-route-protection)
+Learn more: [Connections](../connections) · [Auth and route protection](../guides/auth-and-route-protection)

package/docs/tutorial/first-agent.mdx

@@ -1,22 +1,32 @@
 ---
-title: "Step 1: Your First Agent"
-description: "Scaffold the analytics assistant, give it an analyst persona, run it, and ask a question."
+title: "Your First Agent"
+description: "Part 1 of the Build an Agent tutorial. Scaffold the analytics assistant, give it an analyst persona, run it, and ask a question."
 ---
 
-This tutorial builds one app end to end: a data analytics assistant. You ask in natural language, and over the next nine steps it learns to query a warehouse, run analysis in a sandbox, remember your team’s metric definitions, and refuse to torch your query budget without asking.
+The Build an Agent tutorial constructs one app end to end, a data analytics assistant. You ask in natural language, and over the next nine steps it learns to query a warehouse, run analysis in a sandbox, remember your team's metric definitions, and refuse to exceed your query budget without asking.
 
 Step 1 gets it talking. The scaffold bundles a small sample dataset, so your first question works with zero setup.
 
-## Scaffold
+## Prerequisites
+
+- Node 24 or newer and npm.
+- A model credential. The scaffold's default model goes through the [Vercel AI Gateway](../getting-started), so you need `AI_GATEWAY_API_KEY` (or `VERCEL_OIDC_TOKEN` pulled via `vercel link`). A direct provider id like `anthropic/claude-opus-4.8` instead needs that provider's key, here `ANTHROPIC_API_KEY`.
+
+If you have not run Eve before, complete [Getting Started](../getting-started) first. Without a credential, "Run the agent" below fails when the runtime tries to reach the model; the dev TUI's `/model` flow walks you through pasting a key or linking a project.
+
+## Scaffold the agent
 
 ```bash
 npx eve@latest init analytics-assistant
+cd analytics-assistant
 ```
 
 The command writes the starter agent with Eve's default model and built-in HTTP API
 channel (`agent/channels/eve.ts`), installs dependencies, initializes Git, and
 starts the development server. Stop the server before continuing with the edits
-below. It does not create a Vercel project or deploy.
+below. It does not create a Vercel project or deploy. `init` creates the
+`analytics-assistant/` directory, so `cd` into it before running further
+commands.
 
 ## Set the model
 
@@ -45,20 +55,20 @@ You are a senior data analyst. You answer questions about the team's data.
 
 Instructions are identity and standing rules. On-demand procedures belong in skills (Step 7), and actions belong in tools (Step 3). See [Instructions](../instructions).
 
-## Run it
+## Run the agent
 
 ```bash
-eve dev
+npm run dev
 ```
 
-The local runtime boots and the dev TUI opens. Ask it something it can answer from general knowledge first:
+The `init` scaffold writes a `dev` script that runs the `eve dev` binary from the project's `node_modules`. The local runtime boots and the dev TUI opens. Ask it something it can answer from general knowledge first:
 
 ```text
 What's a good way to measure week-over-week retention?
 ```
 
-You’ll get a reply that follows the analyst persona. It can’t see your data yet (that’s Step 3). First, a look at what just happened under the hood.
+You get a reply that follows the analyst persona. It can't see your data yet (that comes in Step 3). First, a look at what happened under the hood.
 
-→ Next: [Step 2: How it runs](./how-it-runs)
+→ Next: [How it runs](./how-it-runs)
 
-Depth: [Getting Started](../getting-started) · [Instructions](../instructions)
+Learn more: [Getting Started](../getting-started) · [Instructions](../instructions)

package/docs/tutorial/guard-the-spend.mdx

@@ -1,15 +1,17 @@
 ---
-title: "Step 8: Guard the Spend"
-description: "Gate expensive queries with cost-based approval: the agent pauses, asks, and resumes."
+title: "Guard the Spend"
+description: "Part 8 of the Build an Agent tutorial. Gate expensive queries with cost-based approval. The agent pauses, asks, and resumes."
 ---
 
-A single warehouse query can scan terabytes and bill you for the privilege. So before the agent fires off an expensive scan, make it stop and check with you: for a costly query, the agent pauses, asks you, and resumes with your answer. That's human-in-the-loop, and you wire it up with one field on the tool.
+A single warehouse query can scan terabytes and run up the bill. So before the analytics assistant fires off an expensive scan, make it stop and check with you. The agent pauses, asks you, and resumes with your answer. That's human-in-the-loop, and you wire it up with one field on the tool.
 
 `needsApproval` runs before `execute`. Return `true` and the turn parks on an approval request; you answer, and the run picks up from that exact step. The function gets the tool input, so you can make the decision cost-based.
 
 ## Estimate, then gate
 
-Add a cheap estimator (a real warehouse exposes a dry-run byte estimate, so keep the helper illustrative) and gate `run_sql` on it:
+This step keeps `run_sql` on the Step 3 sample dataset so you can demo the gate locally. With a real warehouse you'd gate the warehouse connection tool from Step 4 the same way, on a dry-run byte estimate instead of the toy heuristic below.
+
+Add a cheap estimator and gate `run_sql` on it:
 
 ```ts title="agent/lib/cost.ts"
 // Illustrative: a real warehouse exposes a dry-run byte estimate.
@@ -27,7 +29,7 @@ import { estimateScanGb } from "../lib/cost.js";
 const THRESHOLD_GB = 50;
 
 export default defineTool({
-  description: "Run a read-only SQL query against the warehouse.",
+  description: "Run a read-only SQL query against the analytics tables.",
   inputSchema: z.object({ sql: z.string() }),
   // Cost-based gate: only the expensive queries need a human yes.
   needsApproval: ({ toolInput }) => estimateScanGb(toolInput?.sql ?? "") > THRESHOLD_GB,
@@ -48,12 +50,12 @@ Ask for something that forces a large unfiltered scan:
 Total revenue across all customers, all time, broken out by day.
 ```
 
-The model proposes the query, `needsApproval` returns `true`, and the turn parks. The stream emits `input.requested`, then `session.waiting`. How the prompt looks depends on the channel: buttons in the TUI, Block Kit in Slack, a UI control on the web. Approve it and the run resumes from exactly that step, then the query runs. Deny it and the tool is skipped, with the model told why.
+The model proposes the query, `needsApproval` returns `true`, and the turn parks. The stream emits `input.requested`, then `session.waiting`. How the prompt looks depends on the channel, whether buttons in the TUI, Block Kit in Slack, or a UI control on the web. Approve it and the run resumes from exactly that step, then the query runs. Deny it and the tool is skipped, with the model told why.
 
 Each session has exactly one active continuation. Answer an approval against a stale handle and it's rejected, so there's no way to double-resume the same parked turn.
 
-The same machinery backs the built-in `ask_question` tool, where the model asks you mid-turn, and per-connection approval via `approval: once()`. See [Tools: human-in-the-loop](../tools).
+The same machinery backs the built-in `ask_question` tool, where the model asks you mid-turn, and per-connection approval via `approval: once()`. See [Tools and human-in-the-loop](../tools).
 
-→ Next: [Step 9: Ship it](./ship-it)
+→ Next: [Ship it](./ship-it)
 
-Depth: [Tools: human-in-the-loop](../tools)
+Learn more: [Tools and human-in-the-loop](../tools)

package/docs/tutorial/how-it-runs.mdx

@@ -1,15 +1,17 @@
 ---
-title: "Step 2: How It Runs"
-description: "Session, turn, and durable steps: what you just watched, and why it survives a crash."
+title: "How It Runs"
+description: "Part 2 of the Build an Agent tutorial. Session, turn, and durable steps, and why a turn survives a crash."
 ---
 
-You sent one message and got one answer. Here's the model behind that, in three words.
+The analytics assistant sent one message and got one answer. Three terms describe the model behind that.
 
-**session** → your whole conversation (durable, can span days)
-**turn** → one message you send and the work it triggers
-**step** → a durable checkpoint within the turn
+| Term        | Meaning                                           |
+| ----------- | ------------------------------------------------- |
+| **session** | Your whole conversation (durable, can span days). |
+| **turn**    | One message you send and the work it triggers.    |
+| **step**    | A durable checkpoint within the turn.             |
 
-Each turn runs as a durable workflow, and Eve saves progress at every step. Restart in the middle of a turn and it picks up from the last completed step, without re-running your tool calls. A turn that's waiting on you (an approval, a question) resumes whenever you answer, even if that's much later.
+Each turn runs as a durable workflow, and Eve saves progress at every step. 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. A turn that's waiting on you (an approval, a question) resumes whenever you answer, even if that's much later.
 
 That's why the features in the rest of this tutorial work the way they do:
 
@@ -17,7 +19,7 @@ That's why the features in the rest of this tutorial work the way they do:
 - The metric glossary in Step 6 survives across turns. State is checkpointed at step boundaries, so it sticks.
 - The spend approval in Step 8 pauses the turn on your yes/no, then picks up exactly where it left off.
 
-Your job is to author capabilities: tools, instructions, channels, skills. Eve drives the model↔tool loop and decides when a turn continues, waits, or ends. You never write that loop yourself.
+You author capabilities, including tools, instructions, channels, and skills. Eve drives the model-to-tool loop and decides when a turn continues, waits, or ends. You never write that loop yourself.
 
 → Next: [Step 3: Query sample data](./query-sample-data)
 

package/docs/tutorial/query-sample-data.mdx

@@ -1,13 +1,13 @@
 ---
-title: "Step 3: Query Sample Data"
-description: "Add a run_sql tool over the bundled sample dataset and watch the tool loop."
+title: "Query Sample Data"
+description: "Part 3 of the Build an Agent tutorial. Add a run_sql tool over the bundled sample dataset and watch the tool loop."
 ---
 
-Right now the agent can hold a conversation but it can't see a single row of data. So give it a tool. A tool is the action primitive: typed input goes in, your code runs, structured output comes back. The name the model sees is just the filename, so `agent/tools/run_sql.ts` becomes the tool `run_sql`.
+The analytics assistant can hold a conversation, but it can't see a single row of data. Give it a tool. A tool is the action primitive. Typed input goes in, your code runs, structured output comes back. The name the model sees is the filename, so `agent/tools/run_sql.ts` becomes the tool `run_sql`.
 
 ## A tiny sample dataset
 
-To make the first query work without any setup, bundle a small in-memory dataset under `agent/lib/`. Keep it tiny. This is throwaway scaffolding, not the real warehouse (that comes in Step 4).
+To make the first query work without setup, bundle a small in-memory dataset under `agent/lib/`. Keep it tiny. This is throwaway scaffolding, not the real warehouse (that comes in Step 4).
 
 ```ts title="agent/lib/sample-db.ts"
 // A toy SQLite-in-memory stand-in. Swap for your real warehouse in Step 4.
@@ -42,7 +42,7 @@ export async function runReadOnlySql(sql: string) {
 }
 ```
 
-## The tool
+## Define the run_sql tool
 
 ```ts title="agent/tools/run_sql.ts"
 import { defineTool } from "eve/tools";
@@ -68,7 +68,7 @@ Tools run in your app runtime with full `process.env`, not in the sandbox. The `
 
 ## Watch the tool loop
 
-Restart `eve dev` and ask:
+Restart the dev server with `npm run dev` and ask:
 
 ```text
 Which customer has spent the most, and how much?
@@ -76,6 +76,6 @@ Which customer has spent the most, and how much?
 
 Watch the loop play out in the TUI. The model emits a `run_sql` call, Eve runs your `execute`, and the rows come back as a tool result. The model reads them and answers with a real number. Eve drove the whole loop. All you supplied was the tool.
 
-→ Next: [Step 4: Connect a warehouse](./connect-a-warehouse)
+→ Next: [Connect a warehouse](./connect-a-warehouse)
 
-Depth: [Tools](../tools)
+Learn more: [Tools](../tools)

package/docs/tutorial/remember-definitions.mdx

@@ -1,9 +1,9 @@
 ---
-title: "Step 6: Remember Definitions"
-description: "Use defineState to remember the team's metric glossary across turns."
+title: "Remember Definitions"
+description: "Part 6 of the Build an Agent tutorial. Use defineState to remember the team's metric glossary across turns."
 ---
 
-Every team has house definitions. “Active” means a purchase in the last 30 days, revenue is net of refunds, a “week” starts Monday. Re-explaining all of that on every turn is a waste. State gives the agent a place to keep it.
+Every team has house definitions for the analytics assistant. "Active" means a purchase in the last 30 days, revenue is net of refunds, a "week" starts Monday. Re-explaining all of that on every turn is a waste. State gives the agent a place to keep them.
 
 `defineState(name, initial)` creates a typed, named slot that survives across step and turn boundaries within a session. You read it with `get()` and change it with `update()`.
 
@@ -67,6 +67,6 @@ The second turn is a separate turn in the same session, yet the definition is st
 
 State is scoped to a session and isolated per agent, so a subagent starts with fresh state and never sees the parent's. Need to reset something each turn? Call `update(() => fresh)` in a lifecycle hook. More in [State](../guides/state).
 
-→ Next: [Step 7: Team playbooks](./team-playbooks)
+→ Next: [Team playbooks](./team-playbooks)
 
-Depth: [State](../guides/state)
+Learn more: [State](../guides/state)

package/docs/tutorial/run-analysis.mdx

@@ -1,15 +1,15 @@
 ---
-title: "Step 5: Run Analysis"
-description: "Seed the warehouse schema into the sandbox workspace, then compute and chart beyond SQL."
+title: "Run Analysis"
+description: "Part 5 of the Build an Agent tutorial. Seed the warehouse schema into the sandbox workspace, then compute and chart beyond SQL."
 ---
 
-SQL tells you the numbers, but a cohort curve, a forecast, or a chart needs real computation. That's what the sandbox is for: an isolated bash environment with a `/workspace` filesystem. Every agent gets exactly one.
+SQL tells the analytics assistant the numbers, but a cohort curve, a forecast, or a chart needs real computation. That's what the sandbox is for. It's an isolated bash environment with a `/workspace` filesystem, and every agent gets exactly one.
 
-There are two pieces. First seed reference files the model can read, then compute against them.
+This takes two pieces. First seed reference files the model can read, then compute against them.
 
 ## Seed the schema into the workspace
 
-Mount the warehouse schema into the sandbox so the model isn't guessing at table shapes. Seeding uses the folder sandbox layout: anything under `agent/sandbox/workspace/` lands in the live `/workspace` cwd at session bootstrap.
+Mount the warehouse schema into the sandbox so the model isn't guessing at table shapes. Seeding uses the folder sandbox layout, where anything under `agent/sandbox/workspace/` lands in the live `/workspace` cwd at session bootstrap.
 
 ```text
 agent/sandbox/
@@ -25,7 +25,7 @@ CREATE TABLE orders     (id INT, customer_id INT, amount_cents INT, created_at D
 CREATE TABLE customers  (id INT, name TEXT, plan TEXT, signed_up_at DATE);
 ```
 
-Top-level workspace entries get advertised to the model automatically, so it knows `schema.sql` is there to read. No `agent/sandbox/sandbox.ts` required. A `workspace/` folder keeps the default sandbox and just seeds your files into it.
+Top-level workspace entries get advertised to the model automatically, so it knows `schema.sql` is there to read. No `agent/sandbox/sandbox.ts` required. A `workspace/` folder keeps the default sandbox and seeds your files into it.
 
 ## Compute and chart in the sandbox
 
@@ -67,13 +67,15 @@ export default defineTool({
 });
 ```
 
-Now ask for something past plain SQL:
+This tool shells out to `python` with matplotlib, which the sandbox base image does not preinstall. Install the runtime in sandbox bootstrap (or bake it into a custom image) so `python plot.py` resolves. See [Sandbox](../sandbox) for where bootstrap runs.
+
+Now ask for something past plain SQL. If you skipped Step 4, this still works against the Step 3 sample dataset:
 
 ```text
-Plot weekly revenue for the last 8 weeks.
+Plot total order revenue per customer.
 ```
 
-The model queries the warehouse (Step 4) for the numbers, checks `schema.sql` to get the grain right, then calls `chart_series` to render the PNG in `/workspace`.
+The model queries for the numbers (the warehouse from Step 4, or the sample dataset if you skipped it), checks `schema.sql` to get the grain right, then calls `chart_series` to render the PNG in `/workspace`.
 
 ## Secrets stay out of the sandbox
 
@@ -81,6 +83,6 @@ The sandbox has no `process.env` and no access to your app's secrets. Your wareh
 
 The local backend runs the sandbox on your laptop during `eve dev`; on Vercel it runs on Vercel Sandbox. Lifecycle, backends, and network policy are in [Sandbox](../sandbox).
 
-→ Next: [Step 6: Remember definitions](./remember-definitions)
+→ Next: [Remember definitions](./remember-definitions)
 
-Depth: [Sandbox](../sandbox)
+Learn more: [Sandbox](../sandbox)

package/docs/tutorial/ship-it.mdx

@@ -1,27 +1,39 @@
 ---
-title: "Step 9: Ship It"
-description: "Put a web dashboard on the agent with useEveAgent, replace placeholderAuth, and deploy to Vercel."
+title: "Ship It"
+description: "Part 9 of the Build an Agent tutorial. Put a web dashboard on the agent with useEveAgent, replace placeholderAuth, and deploy to Vercel."
 ---
 
-The assistant runs fine in the TUI. Now ship it for real: a web dashboard your team logs into, behind actual auth, deployed on Vercel. Three pieces to wire up: a React UI, the channel's auth, and the deploy itself.
+The analytics assistant runs fine in the TUI. Now ship it for real, as a web dashboard your team logs into, behind actual auth, deployed on Vercel. There are three pieces to wire up. A React UI, the channel's auth, and the deploy itself.
 
-## A dashboard with `useEveAgent`
+## Add the Web Chat app
+
+Step 1 scaffolded the agent without a web frontend. Add one now with `eve channels add`, run from the `analytics-assistant/` directory:
 
-The dashboard talks to the built-in Eve HTTP channel (`agent/channels/eve.ts`). On the browser side, `useEveAgent` takes care of session creation, streaming, and HITL. In a Next.js app, wrap the config and the routes get wired automatically:
+```bash
+npx eve channels add web
+```
+
+This adds a Next.js app (`next.config.ts`, `app/page.tsx`, `app/_components/`) wired to the existing Eve channel, plus the chat UI components and their dependencies. Run `npm install` afterward to install the added packages. The generated `next.config.ts` wraps your config with `withEve`, which wires the Eve routes automatically:
 
 ```ts title="next.config.ts"
 import type { NextConfig } from "next";
 import { withEve } from "eve/next";
 
-export default withEve({} satisfies NextConfig);
+const nextConfig: NextConfig = {};
+
+export default withEve(nextConfig);
 ```
 
-```tsx title="app/dashboard/chat.tsx"
+## A dashboard with `useEveAgent`
+
+The dashboard talks to the built-in Eve HTTP channel (`agent/channels/eve.ts`). On the browser side, `useEveAgent` handles session creation, streaming, and HITL. The scaffold renders its chat from `app/_components/agent-chat.tsx`, mounted by `app/page.tsx`. That component is fuller than you need to start, so replace its contents with this minimal version:
+
+```tsx title="app/_components/agent-chat.tsx"
 "use client";
 
 import { useEveAgent } from "eve/react";
 
-export function AnalyticsChat() {
+export function AgentChat() {
   const agent = useEveAgent();
   const isBusy = agent.status === "submitted" || agent.status === "streaming";
 
@@ -51,11 +63,37 @@ export function AnalyticsChat() {
 }
 ```
 
-`agent.data.messages` and `agent.status` cover most chat UIs. The hook also surfaces HITL prompts (the spend approval from [Step 8](./guard-the-spend)), so the dashboard can render approve/deny controls. Full API: [Frontend](../guides/frontend/overview).
+The generated `app/page.tsx` already imports and renders this `AgentChat` export, so no other wiring is needed:
+
+```tsx title="app/page.tsx"
+import { AgentChat } from "@/app/_components/agent-chat";
+
+export default function Page() {
+  return <AgentChat />;
+}
+```
+
+`agent.data.messages` and `agent.status` cover most chat UIs. The hook also surfaces HITL prompts (the spend approval from [Step 8](./guard-the-spend)), so the dashboard can render approve/deny controls. For the full API, see [Frontend](../guides/frontend/overview).
 
 ## Replace `placeholderAuth`
 
-The scaffold's channel ships with `placeholderAuth()`, which fails closed: it rejects production traffic so an unauthenticated app can't go live by accident. Swap it for your app's real auth before you deploy. Order matters here. List your app auth first, ahead of the catch-all helpers, so any entry that doesn't recognize the caller falls through to the next one:
+The scaffold's channel ships with `placeholderAuth()`, which fails closed. It rejects production traffic so an unauthenticated app can't go live by accident. Swap it for your app's real auth before you deploy.
+
+Your auth lives in one module that turns a request into a user. Create `agent/lib/auth.ts` and wire your real provider (a cookie session, Auth.js, Clerk) in here. The stub below returns a fixed user so the page compiles and runs end to end:
+
+```ts title="agent/lib/auth.ts"
+export interface AppUser {
+  id: string;
+  team: string;
+}
+
+// Replace with your real session/provider lookup.
+export async function authenticate(_request: Request): Promise<AppUser | null> {
+  return { id: "demo-user", team: "growth" };
+}
+```
+
+Now point the channel at it. Replace the contents of `agent/channels/eve.ts`, which Step 7 left with a dev-only `devTeam` entry and `placeholderAuth()`. List your app auth first, ahead of the catch-all helpers, so any entry that doesn't recognize the caller falls through to the next one:
 
 ```ts title="agent/channels/eve.ts"
 import { eveChannel } from "eve/channels/eve";
@@ -81,7 +119,7 @@ export default eveChannel({
 
 That `team` attribute is exactly what the dynamic playbook in [Step 7](./team-playbooks) reads from `ctx.session.auth`. Identity is set in this one place and flows out to every capability from there.
 
-## Deploy
+## Deploy to Vercel
 
 ```bash
 vercel deploy
@@ -90,11 +128,29 @@ vercel deploy
 On Vercel, the web app stays public and the Eve runtime sits behind it on the same origin, with the sandbox running on Vercel Sandbox. You can smoke-test the deployment without leaving the CLI:
 
 ```bash
-eve dev https://your-analytics-app.vercel.app
+npx eve dev https://your-analytics-app.vercel.app
 ```
 
 That's the full assistant, deployed and authed. It queries the warehouse, runs analysis in a sandbox, charts the results, remembers your team's definitions, loads the right playbook per team, and asks before it spends.
 
-Depth: [Frontend](../guides/frontend/overview) · [Auth & route protection](../guides/auth-and-route-protection) · [Deployment](../guides/deployment)
+## What you learned
+
+Across the nine steps you built and shipped one agent, and along the way you used:
+
+- **Tools** to give the model typed actions (`run_sql`, `chart_series`, `define_metric`).
+- **Connections** to reach a warehouse over an OAuth MCP, with per-user tokens Eve resolves for you.
+- **The sandbox** to compute and chart beyond SQL in an isolated `/workspace`.
+- **State** (`defineState`) to remember the team's glossary across turns.
+- **Dynamic skills** (`defineDynamic`) to load the right team playbook per caller.
+- **Human-in-the-loop** approval (`needsApproval`) to gate expensive queries.
+- **Channel auth** to turn a request into an authenticated principal.
+- **Deployment** to Vercel, with the runtime behind your web app.
+
+## Next steps
+
+- [Connections](../connections) for tool allowlists and per-connection approval.
+- [Sandbox](../sandbox) for backends, lifecycle, and network policy.
+- [Dynamic capabilities](../guides/dynamic-capabilities) for schema-derived dynamic tools, a read-only analyst subagent, and model-authored report workflows on this same example.
+- [Auth and route protection](../guides/auth-and-route-protection) for production auth patterns.
 
-Go deeper on this same example in [Advanced](../guides/dynamic-capabilities): schema-derived dynamic tools, a read-only analyst subagent, and model-authored report workflows.
+Learn more: [Frontend](../guides/frontend/overview) · [Auth and route protection](../guides/auth-and-route-protection) · [Deployment](../guides/deployment)

package/docs/tutorial/team-playbooks.mdx

@@ -1,15 +1,15 @@
 ---
-title: "Step 7: Team Playbooks"
-description: "Load the caller's team playbook with a dynamic skill keyed on the principal."
+title: "Team Playbooks"
+description: "Part 7 of the Build an Agent tutorial. Load the caller's team playbook with a dynamic skill keyed on the principal."
 ---
 
-The glossary from [Step 6](./remember-definitions) is per-session. But your teams have standing analysis conventions (Growth runs cohort retention a particular way, Finance has its own revenue-recognition rules), and those shouldn't bleed across tenants. Load the right team's playbook for whoever is asking.
+The glossary from [Step 6](./remember-definitions) is per-session. But your teams have standing analysis conventions for the analytics assistant (Growth runs cohort retention a particular way, Finance has its own revenue-recognition rules), and those shouldn't bleed across tenants. Load the right team's playbook for whoever is asking.
 
-A skill is an on-demand procedure: the model pulls it in with `load_skill` only when a turn actually needs it. Make it dynamic and the skill gets decided at runtime instead of baked in. A `defineDynamic` resolver reads the session and returns a `defineSkill` (or nothing). Here we key that decision on the caller's identity in `ctx.session.auth`.
+A skill is an on-demand procedure. The model pulls it in with `load_skill` only when a turn needs it. Make it dynamic and the skill gets decided at runtime instead of baked in. A `defineDynamic` resolver reads the session and returns a `defineSkill` (or nothing). Here you key that decision on the caller's identity in `ctx.session.auth`.
 
 ## A playbook per principal
 
-`ctx.session.auth.current` holds the most recent caller, or `null` if there isn't one. Its `attributes` are the claims your auth layer stamped on, team included. Read the team, look up that team's playbook, and emit a skill for it:
+`ctx.session.auth.current` holds the most recent caller, or `null` if there isn't one. Its `attributes` are the claims your auth layer stamped on, including the team. Read the team, look up that team's playbook, and emit a skill for it:
 
 ```ts title="agent/skills/team-playbook.ts"
 import { defineDynamic, defineSkill } from "eve/skills";
@@ -48,16 +48,39 @@ export default defineDynamic({
 });
 ```
 
-`session.started` fires once per session. The resolver reads the team a single time, and the resulting skill stays available for every turn that follows. Returning `null` produces no skill at all, so a caller with no team simply gets no playbook.
+`session.started` fires once per session. The resolver reads the team once, and the resulting skill stays available for every turn that follows. Returning `null` produces no skill, so a caller with no team gets no playbook.
 
 ## See it route
 
-A Growth user asks "what's our 8-week retention?" The model sees the playbook fits, calls `load_skill`, and applies the Growth conventions to that turn: weekly cohorts, no trial accounts. Ask the same question as a Finance user and you'll never see the Growth playbook. You get Finance's.
+The team comes from authenticated claims, which the auth layer stamps on in [Step 9](./ship-it). Until then `ctx.session.auth.current` has no `team`, so the resolver returns `null` and no playbook loads. To verify routing now, stamp a team in local dev. Add a dev-only entry to `agent/channels/eve.ts` ahead of `localDev()`, and remove it before Step 9 wires real auth:
 
-The team comes from authenticated claims, not from the message, so one tenant can't borrow another's playbook by asking nicely. (Those `attributes` are set by the auth layer in [Step 9](./ship-it).)
+```ts title="agent/channels/eve.ts"
+import { eveChannel } from "eve/channels/eve";
+import { localDev, placeholderAuth, vercelOidc, type AuthFn } from "eve/channels/auth";
+
+// Dev-only: stamp a team so Step 7's playbook resolver has something to read.
+// Remove before Step 9.
+const devTeam: AuthFn<Request> = () =>
+  process.env.NODE_ENV === "production"
+    ? null
+    : {
+        attributes: { team: "growth" },
+        authenticator: "dev-team",
+        principalId: "dev",
+        principalType: "user",
+      };
+
+export default eveChannel({
+  auth: [devTeam, localDev(), vercelOidc(), placeholderAuth()],
+});
+```
+
+Restart with `npm run dev` and ask "what's our 8-week retention?" The model sees the Growth playbook fits, calls `load_skill`, and applies the Growth conventions to that turn (weekly cohorts, no trial accounts). Switch `team` to `"finance"`, restart, and the same question routes to Finance's playbook instead.
+
+Because the team comes from authenticated claims, not from the message, one tenant can't borrow another's playbook through the message content.
 
 The same `defineDynamic` resolver drives dynamic tools and instructions too. For the full mechanism, see [Dynamic capabilities](../guides/dynamic-capabilities).
 
-→ Next: [Step 8: Guard the spend](./guard-the-spend)
+→ Next: [Guard the spend](./guard-the-spend)
 
-Depth: [Skills](../skills) · [Dynamic capabilities](../guides/dynamic-capabilities)
+Learn more: [Skills](../skills) · [Dynamic capabilities](../guides/dynamic-capabilities)

package/package.json

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