eve 0.52.2 → 0.52.4

package/docs/tools/workflows.mdx

@@ -79,8 +79,8 @@ or days later, the run resumes, deploys, and returns. The model sees one tool re
   `start`, `getRun`, and `resumeHook` from `workflow/api` belong in steps. Your app does not install
   the SDK; for types, new projects list `eve/workflow-modules` in the tsconfig `types`.
 - In the body, `ctx` has `session`, `callId`, `toolName`, `abortSignal`, `agent`, and `ask`.
-  `getSandbox`, `getSkill`, `getToken`, and `requireAuth` are not part of `WorkflowToolContext`.
-  Read credentials from `process.env` in a step; session-scoped workflow authorization is not yet available.
+  `getToken` and `requireAuth` work inside a `"use step"` helper that receives `ctx` as a direct argument;
+  they throw in the workflow body. `getSandbox` and `getSkill` remain unavailable.
 - The tool's input must be a JSON object. Workflow bodies are for static tools under `agent/tools/`,
   not tools returned from `defineDynamic` resolvers.
 
@@ -93,6 +93,12 @@ tool object, a channel handler, or a schedule handler fails the build. To start
 channel or schedule, use the [channel operations](/docs/channels/custom#channel-operations-and-session-handles)
 or [schedule handler](/docs/schedules#handler-form-run) APIs.
 
+Workflow imports resolve `paths` aliases from your application's `tsconfig.json` or
+`jsconfig.json`, including when the application is a workspace package. eve includes only
+workflow and step modules reachable from the agent's runtime modules. Unrelated workflows
+in the host application stay outside the agent bundle. An unresolved workflow import fails
+the build with the missing import in the error.
+
 ### Migrate an existing workflow tool
 
 Replace `defineTool` with `defineWorkflowTool`, keep the executor's `"use workflow"` directive,
@@ -148,6 +154,65 @@ Answering resumes the body in either mode.
 Promise or Node.js timer inside a step also does not create a durable workflow suspension; use
 the workflow operations for waits that must survive a restart.
 
+## Authorize inside a step
+
+Pass `ctx` directly to a step helper and call `ctx.getToken(provider)` there. User-scoped providers
+resolve as whoever launched this workflow tool, even if another person speaks in the session while it waits.
+The provider declaration and the API request both stay inside the step:
+
+```ts
+import { connect } from "@vercel/connect/eve";
+import type { WorkflowToolContext } from "eve/tools";
+
+async function readRepository(ctx: WorkflowToolContext, repository: string) {
+  "use step";
+  const provider = connect("github/my-agent");
+  const { token } = await ctx.getToken(provider);
+  const response = await fetch(`https://api.github.com/repos/${repository}`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  if (response.status === 401) ctx.requireAuth(provider);
+  if (!response.ok) throw new Error(`GitHub returned ${response.status}`);
+  return response.json();
+}
+```
+
+Connections discovered through `connection_search`, ordinary tools, and workflow steps use the same
+authorization machinery for requester identity, token caching, callback completion, and rejection
+after sign-in. The execution runtime owns the wait: an agent returns to its model after authorization,
+while a workflow retries the interrupted step and continues the authored body.
+
+The workflow body calls `await readRepository(ctx, repository)`.
+
+<Callout type="warning" title="Keep tokens out of step results">
+  Step results enter the workflow's durable history, so do not return the token from the helper.
+  eve's token cache stays inside the step. The step input is recorded too and, after sign-in,
+  carries the provider's callback parameters, such as a one-time authorization code. This matches
+  how agent turns record callbacks. Bearer tokens are never written.
+</Callout>
+
+When sign-in is required, the step attempt ends and the workflow waits on its own callback hook,
+without holding compute. The channel renders the sign-in challenge. After the callback, eve retries
+**the whole interrupted step**, resolves the token, and continues. Previously completed steps are
+not rerun. Resolve auth before other side effects in that step, and make operations before
+`requireAuth` safe to retry. A token rejected immediately after sign-in fails instead of prompting
+again. Provider declarations can be shared imports, but context must be passed directly, not nested
+inside another argument or captured in a closure.
+
+After a successful callback exchange, eve records a completion marker before returning to authored
+code. If that code later fails and the step retries, eve reads the token from the provider instead
+of exchanging the same callback again. The provider must persist the grant or token; the marker
+itself contains no credentials.
+
+A background task becomes `input_required` during sign-in. The callback resumes that task; it does
+not rely on the launching agent turn still being active. Cancelling an authorization wait withdraws
+its callback. Cancellation uses the existing turn or task cancellation path rather than a separate
+authorization completion event.
+
+Background workflow authorization requires a new session after upgrading. In older sessions,
+`ctx.getToken` and `ctx.requireAuth` fail immediately with an instruction to start a new session.
+Blocking workflows and background workflows without auth are unaffected.
+
 ## Ask a human: `ctx.ask`
 
 ```ts

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

@@ -1,58 +1,81 @@
 ---
-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."
+title: "Connect a Warehouse (Optional)"
+description: "Optional follow-up to the Build an Agent tutorial. Let each user connect their own warehouse over an OAuth MCP via Vercel Connect."
 ---
 
-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.
+Complete [the tutorial with sample data](./first-agent) first. When you have a warehouse with an MCP server, you can connect it to the analytics assistant and let each user sign 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.
+[Vercel Connect is generally available](https://vercel.com/changelog/vercel-connect-secure-access-to-external-services-for-your-agents). You can complete the tutorial with the [sample dataset](./query-sample-data); Connect is only needed for the OAuth integration shown on this page.
 
-The filename sets the runtime name. Put the file at `agent/connections/warehouse.ts` and it registers as `"warehouse"`, with its tools surfaced as `warehouse__<tool>`.
+## Before you start
+
+This integration needs:
+
+- A warehouse account and a working MCP server for that warehouse, with its full endpoint URL. Connect manages credentials; it does not create a warehouse or turn a SQL database into an MCP server.
+- Permission to authorize that server, with read-only access to the data you want the agent to query.
+- A Vercel account and a linked project for Connect.
+- An authenticated user on the eve session. Complete the route-auth setup in [Ship it](./ship-it#replace-placeholderauth) before trying per-user OAuth from a web app.
+
+If you are working through the tutorial for the first time, keep `run_sql` and [continue to Run analysis](./run-analysis). You can add this integration later.
+
+## Register the connector
+
+Run these commands from `analytics-assistant/`. Replace the example URL with your MCP server's actual endpoint, including its path:
+
+```bash
+npm install @vercel/connect
+npx vercel@latest link
+npx vercel@latest connect create "https://your-warehouse.example/mcp" --name warehouse
+```
+
+Follow the provider-specific registration prompts. Copy the **connector UID returned by the CLI**. The display name `warehouse` is not the connector UID. Attach the returned connector to this project, then pull the local environment:
+
+```bash
+npx vercel@latest connect attach "<returned-connector-uid>" --yes
+npx vercel@latest env pull
+```
+
+`vercel env pull` provides `VERCEL_OIDC_TOKEN` for local requests to Connect. That token identifies your Vercel project; it does not sign an end user into the app. The steps below use the authenticated deployment from [Ship it](./ship-it#replace-placeholderauth). The [Connect reference](https://vercel.com/docs/connect) covers service-specific setup and project attachments.
 
 ## Declare the connection
 
-The warehouse exposes a generic SQL MCP behind OAuth. Pass `connect()` from `@vercel/connect/eve` as the auth, and Vercel Connect handles the OAuth flow, stores the tokens, and refreshes them for you:
+Create `agent/connections/warehouse.ts`. Replace both the endpoint URL and connector UID below with the values you just configured:
 
 ```ts title="agent/connections/warehouse.ts"
 import { connect } from "@vercel/connect/eve";
 import { defineMcpClientConnection } from "eve/connections";
 
 export default defineMcpClientConnection({
-  url: "https://mcp.your-warehouse.example/sse",
+  url: "https://your-warehouse.example/mcp",
   description: "The team's data warehouse: run read-only SQL and list tables and columns.",
-  auth: connect("warehouse"),
+  auth: connect("<returned-connector-uid>"),
 });
 ```
 
-`"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.
+The filename registers the eve connection as `"warehouse"`, with tools named `warehouse__<tool>`. This eve name is independent of the Connect connector UID. The remote server determines which tools exist; check its tool inventory and read-only permissions before using it.
 
-Before testing the warehouse from a web app, make sure the eve channel route auth maps your signed-in app user to `principalType: "user"`. A Connect-backed connection can only start per-user OAuth when the active session already has an authenticated user principal. If route auth still only accepts `localDev()`, a runtime token, or a placeholder guard, the first warehouse tool call fails with `reason: "principal_required"` instead of showing the sign-in challenge.
+`connect("...")` is user-scoped by default. Each end-user authorizes in their own browser, and eve resolves that user's token before a tool call. The eve channel's route auth must map the signed-in app user to `principalType: "user"`. `localDev()`, a runtime token, or a placeholder guard cannot supply that identity; those sessions fail with `reason: "principal_required"` before OAuth starts. For a shared app credential, see [app vs. user auth](../connections#choose-app-vs-user-auth).
 
-Once Connect is enabled on your account, wire it up:
+## Deploy and try it
 
-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.
+Deploy the updated app so the authenticated web app includes the new connection:
 
-For the full reference, see [MCP connections](../connections/mcp).
-
-## What the user sees
+```bash
+npx vercel@latest deploy
+```
 
-Ask a question that needs the warehouse:
+Open the new HTTPS preview URL, sign in with the credentials configured in [Ship it](./ship-it#replace-placeholderauth), and create a new session. The tutorial's development server bypasses the browser login and uses `localDev()`; restarting `npm run dev` alone does not provide the user identity this connection requires.
 
-```text
-How many enterprise customers signed up last month?
-```
+From your authenticated web app, ask the agent to inspect the warehouse's available tables and then query a table you have access to. Use the server's schema rather than assuming it has the tutorial's `orders` and `customers` tables.
 
-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.
+If the user has not authorized the connector, the turn parks and the channel shows a sign-in link. Complete authorization in the browser; after the callback succeeds, the turn resumes and retries the tool call. Later calls use the existing grant while it remains valid. See [MCP connection troubleshooting](../connections/mcp#troubleshooting) if registration succeeds but the tool cannot connect.
 
 ## The token never reaches the model
 
-Right before each request to the MCP server, eve resolves the bearer and sends it as `Authorization: Bearer <token>`. The model only ever sees tool names, descriptions, and results. The credential stays out of its reach.
+Right before each request to the MCP server, eve resolves the bearer and sends it as `Authorization: Bearer <token>`. The model sees tool names, descriptions, and results. The credential stays in the app runtime.
 
-If you want more control, gate the connection behind approval (`approval: once()`) or narrow which tools the model sees (`tools.allow`). See [MCP connections](../connections/mcp).
+Gate the connection behind approval (`approval: once()`) or narrow which tools the model sees (`tools.allow`) when needed. See [MCP connections](../connections/mcp).
 
-→ Next: [Run analysis](./run-analysis)
+→ Return to the tutorial: [Run analysis](./run-analysis)
 
 Learn more: [MCP connections](../connections/mcp) · [Authentication](../guides/auth-and-route-protection)

package/docs/tutorial/first-agent.mdx

@@ -1,16 +1,22 @@
 ---
 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."
+description: "Scaffold the analytics assistant, give it an analyst persona, run it, and ask a question."
 ---
 
-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.
+For a bespoke learning experience, start with the [eve template gallery](https://eve.dev/templates) or ask your coding agent to build your use case. For example:
 
-Step 1 gets it talking. The scaffold bundles a small sample dataset, so your first question works with zero setup.
+- “Build an eve Slack agent that answers questions from our team’s documentation.”
+- “Build an eve incident-response agent that investigates alerts using our observability tools.”
+- “Build an eve GitHub maintainer that triages issues and summarizes pull requests.”
+
+If you prefer a step-by-step walkthrough, continue with this tutorial. It constructs one app end to end: a data analytics assistant. You ask in natural language, and over eight steps it learns to query sample data, 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. In Step 3 you create a small local dataset that you use throughout the tutorial. You can complete the tutorial without a warehouse or Vercel Connect account. [Connect a warehouse](./connect-a-warehouse) is an optional follow-up once your agent works.
 
 ## 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 model like `anthropic("claude-opus-4-8")` instead needs that provider's AI SDK package and key, here `@ai-sdk/anthropic` and `ANTHROPIC_API_KEY`.
+- A working model credential, configured through [Getting Started](../getting-started). Keep the model and credential you already tested there.
 
 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.
 
@@ -21,24 +27,19 @@ 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. `init` creates the
+The command writes the starter agent and built-in HTTP API channel
+(`agent/channels/eve.ts`), installs dependencies, initializes Git, and offers
+to start the development server. Stop the server if you started it before
+continuing with the edits 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
-
-`agent/agent.ts` holds the model and config. Use a capable model for analysis work:
+## Keep your configured model
 
-```ts
-import { defineAgent } from "eve";
-
-export default defineAgent({
-  model: "anthropic/claude-opus-4.8",
-});
-```
+`agent/agent.ts` holds the model and config. Use the same model and credentials
+that worked in Getting Started. The tutorial does not require switching providers.
+If you need to configure this new project, use `/model` in the dev TUI before
+sending your first question.
 
 ## Give it an analyst persona
 
@@ -53,7 +54,7 @@ You are a senior data analyst. You answer questions about the team's data.
   the data, say so plainly.
 ```
 
-Instructions are identity and standing rules. On-demand procedures belong in skills (Step 7), and actions belong in tools (Step 3). See [Instructions](../instructions).
+Instructions are identity and standing rules. On-demand procedures belong in skills (Step 6), and actions belong in tools (Step 3). See [Instructions](../instructions).
 
 ## Run the agent
 

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

@@ -1,15 +1,15 @@
 ---
 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."
+description: "Part 7 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 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.
+Use the sample dataset to practice an approval before a tool runs. The example assigns a simulated scan cost to each query; it does not incur warehouse charges. Make the analytics assistant stop and check with you before a query exceeds that threshold. 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.
 
 `approval` runs before `execute`. Return `"user-approval"` 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
 
-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.
+This step keeps `run_sql` on the Step 3 sample dataset so you can demo the gate locally. If you later [connect a warehouse](./connect-a-warehouse), use the provider's dry-run estimate to decide when approval is needed.
 
 Add a cheap estimator and gate `run_sql` on it:
 
@@ -30,7 +30,7 @@ const THRESHOLD_GB = 50;
 
 export default defineTool({
   description: "Run a read-only SQL query against the analytics tables.",
-  inputSchema: z.object({ sql: z.string() }),
+  inputSchema: z.object({ sql: z.string().max(10_000) }),
   // Cost-based gate: only the expensive queries need a human yes.
   approval: ({ toolInput }) =>
     estimateScanGb(toolInput?.sql ?? "") > THRESHOLD_GB ? "user-approval" : "not-applicable",

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

@@ -15,9 +15,8 @@ Each turn runs as a durable workflow, and eve saves progress at every step. Comp
 
 That's why the features in the rest of this tutorial work the way they do:
 
-- The warehouse sign-in in Step 4 parks the turn until you authorize in the browser. A few minutes is fine.
-- 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.
+- The metric glossary in Step 5 survives across turns. State is checkpointed at step boundaries, so it sticks.
+- The spend approval in Step 7 pauses the turn on your yes/no, then picks up exactly where it left off.
 
 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.
 

package/docs/tutorial/meta.json

@@ -5,11 +5,11 @@
     "first-agent",
     "how-it-runs",
     "query-sample-data",
-    "connect-a-warehouse",
     "run-analysis",
     "remember-definitions",
     "team-playbooks",
     "guard-the-spend",
-    "ship-it"
+    "ship-it",
+    "connect-a-warehouse"
   ]
 }

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

@@ -1,6 +1,6 @@
 ---
 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."
+description: "Part 3 of the Build an Agent tutorial. Add a run_sql tool over a local sample dataset and watch the tool loop."
 ---
 
 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`.
@@ -14,27 +14,21 @@ npm install sql.js
 npm install --save-dev @types/sql.js
 ```
 
-`sql.js` loads its WebAssembly binary from the installed package at runtime. Keep the package external so the binary remains next to its JavaScript:
+`sql.js` loads its WebAssembly binary from the installed package at runtime. Keep the package external so the binary remains next to its JavaScript. Add this `build` property inside your existing `defineAgent({ ... })` in `agent/agent.ts`, keeping your configured `model` and its imports:
 
-```ts title="agent/agent.ts" {5-7}
-import { defineAgent } from "eve";
-
-export default defineAgent({
-  model: "anthropic/claude-opus-4.8",
-  build: {
-    externalDependencies: ["sql.js"],
-  },
-});
+```ts
+build: {
+  externalDependencies: ["sql.js"],
+},
 ```
 
 Restart the dev server after changing `externalDependencies`. eve reads this setting when the server starts.
 
 ## A tiny sample dataset
 
-Store a small in-memory dataset under `agent/lib/`. Keep it tiny. This is throwaway scaffolding, not the real warehouse (that comes in Step 4).
+Create `agent/lib/sample-db.ts` with the dataset below. These four orders and three customers supply the data for every remaining tutorial step. No database server, account, or connection string is needed. The dataset is recreated when the app restarts.
 
 ```ts title="agent/lib/sample-db.ts"
-// A toy SQLite-in-memory stand-in. Swap for your real warehouse in Step 4.
 import initSqlJs from "sql.js";
 
 const SEED = `
@@ -60,12 +54,27 @@ async function db() {
 
 export async function runReadOnlySql(sql: string) {
   const database = await db();
-  const [result] = database.exec(sql);
-  if (!result) return { columns: [], rows: [] as unknown[][] };
-  return { columns: result.columns, rows: result.values };
+  const query = `SELECT * FROM (\n${sql.trim().replace(/;$/, "")}\n) LIMIT 501`;
+  const statement = database.prepare(query);
+  try {
+    // prepare() accepts the first statement; reject any unparsed trailing SQL.
+    if (statement.getSQL() !== query) {
+      throw new Error("Provide a single SELECT query.");
+    }
+    const columns = statement.getColumnNames();
+    const rows: unknown[][] = [];
+    while (rows.length < 501 && statement.step()) rows.push(statement.get());
+    return { columns, rows };
+  } finally {
+    statement.free();
+  }
 }
 ```
 
+The outer `SELECT` lets SQLite accept queries, including `WITH` queries, while rejecting writes and configuration statements. The helper prepares one statement, rejects trailing SQL, and reads at most 501 rows. The extra row lets the tool report that its 500-row output was truncated. It frees the statement even when a query fails.
+
+This is an in-memory tutorial database. A row limit does not bound the work needed to compute a query; use database-enforced read-only permissions and query timeouts when adapting the tool to a production database.
+
 ## Define the run_sql tool
 
 ```ts title="agent/tools/run_sql.ts"
@@ -78,7 +87,7 @@ export default defineTool({
     "Run a read-only SQL query against the analytics tables (orders, customers) " +
     "and return the columns and rows.",
   inputSchema: z.object({
-    sql: z.string().describe("A single read-only SELECT statement."),
+    sql: z.string().max(10_000).describe("A single read-only SELECT statement."),
   }),
   async execute({ sql }) {
     const { columns, rows } = await runReadOnlySql(sql);
@@ -98,8 +107,10 @@ Restart the dev server with `npm run dev` and ask:
 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.
+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. The result is Globex with 9,900 cents ($99.00). The amounts are stored in cents, so divide by 100 when reporting dollars. eve drove the whole loop; you supplied the tool.
+
+Keep `run_sql` and the sample database for the rest of the tutorial. When you have your own data service, [Connect a warehouse](./connect-a-warehouse) explains the optional integration.
 
-→ Next: [Connect a warehouse](./connect-a-warehouse)
+→ Next: [Run analysis](./run-analysis)
 
 Learn more: [Tools](../tools)

package/docs/tutorial/remember-definitions.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Remember Definitions"
-description: "Part 6 of the Build an Agent tutorial. Use defineState to remember the team's metric glossary across turns."
+description: "Part 5 of the Build an Agent tutorial. Use defineState to remember the team's metric glossary across turns."
 ---
 
 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.
@@ -55,15 +55,15 @@ export default defineTool({
 ## See it persist
 
 ```text
-> For us, an active customer is one with a purchase in the last 30 days.
+> For this dataset, a high-value customer has at least $50 in total orders.
   Remember that.
-  → calls define_metric("active customer", "purchase in the last 30 days")
+  → calls define_metric("high-value customer", "at least $50 in total orders")
 
-> How many active customers do we have?
+> How many high-value customers do we have?
   → recalls the definition, writes the matching SQL, answers
 ```
 
-The second turn is a separate turn in the same session, yet the definition is still there. State checkpoints at step boundaries, so it's the same durability from [Step 2](./how-it-runs), now applied to your own data.
+The sample data has two high-value customers: Acme ($57) and Globex ($99). This definition works with the same fixed dataset whenever you run the tutorial. The second turn is a separate turn in the same session, yet the definition is still there. State checkpoints at step boundaries, so it's the same durability from [Step 2](./how-it-runs), now applied to your own data.
 
 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](../concepts/state).