@cursor/july 0.1.92 → 0.1.93

package/dist/docs/llms-full.txt

@@ -20,11 +20,6 @@ Metric callbacks observe the result without approving, rejecting, or
 failing a turn. Use [evals](/docs/evals.md) for pass/fail regression checks
 on fixed inputs.
 
-> [!NOTE]
-> Import paths here use `@cursor/july/ab`. On projects still
-> using `@anysphere/agent-serve`, swap the import. See
-> [Run the CLI](/docs/index.md#run-the-cli) for the full rename table.
-
 ## Choose live A/B metrics or evals
 
 Both features read the session event stream, but they answer different
@@ -45,7 +40,7 @@ There is no `agent-sdk ab` command or assertion API.
 Author one experiment in `agent/ab.ts`, add more under
 `agent/ab/<name>.ts`, or use both forms. Each file defines one
 experiment. The experiment name comes from `name` when set. Otherwise,
-The Agent SDK uses `ab` for `agent/ab.ts` and the file stem for files under
+the Agent SDK uses `ab` for `agent/ab.ts` and the file stem for files under
 `agent/ab/`.
 
 ```ts
@@ -254,10 +249,9 @@ The response has two views of the same durable data:
 `GET /v1/abs` returns sessions visible to the current principal by
 default. In `--dev`, loopback requests include every session. Add
 `--allow-anonymous` to include every session from non-loopback callers
-too. This include-all behavior can still apply to `GET /v1/abs` in dev
-when bearer or custom auth keeps `GET /v1/sessions` owner-scoped.
+too.
 
-Session `events.ndjson` is the source of truth for assignment + fold.
+The session event stream is the source of truth for assignment + fold.
 `GET /v1/abs` recomputes aggregates from those logs. Any
 `agent/storage.ts` exports samples and snapshots durably: an authored
 `abs` table when the backend has a native shape for it, or the table
@@ -267,14 +261,14 @@ derived over the KV core otherwise. See
 ## Configure the playground fold window
 
 Assignments and foldable metrics already persist in each session's
-`events.ndjson` under `--state-root`. The optional `agent/ab.config.ts`
-only caps how many sessions the playground and `GET /v1/abs` fold:
+event stream. The optional `agent/ab.config.ts` only caps how many
+sessions the playground and `GET /v1/abs` fold:
 
 ```ts
 import { defineABConfig } from "@cursor/july/ab";
 
 export default defineABConfig({
-  // Optional — defaults to 200. Only affects GET /v1/abs / A/Bs tab.
+  // Optional. Defaults to 200. Only affects GET /v1/abs / A/Bs tab.
   maxPlaygroundSessions: 500,
 });
 ```
@@ -286,7 +280,7 @@ your metrics vendor, send samples from `onSample` or declare a storage
 
 ## Keep assignments durable
 
-The append-only `events.ndjson` stream is the source of truth. Each
+The append-only event stream is the source of truth. Each
 `ab.assigned` event persists a variant key or null skip. Built-in
 metrics come from the turn and tool events that follow it.
 
@@ -373,9 +367,8 @@ and verify the result without reading terminal prose.
 ## How do I create an agent with the built-in skill?
 
 Have the coding agent read
-[`skills/create-agent/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/create-agent/SKILL.md) (in the
-monorepo: `packages/agent-serve/skills/create-agent/SKILL.md`) and follow
-it.
+[`skills/create-agent/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/create-agent/SKILL.md) and
+follow it.
 
 The skill asks about your agent's purpose, runtime, model, channels, MCP
 connections, and capabilities. It then shows you a plan, writes the
@@ -409,11 +402,6 @@ The package ships task-specific guides under [`skills/`](https://github.com/curs
 Point your coding agent at the matching `SKILL.md`. The guide contains
 the workflow, commands, and common mistakes for that task.
 
-> [!NOTE]
-> The skill bodies use the current `agent-serve` CLI names. This guide
-> uses the upcoming `agent-sdk` names. See
-> [Run the CLI](/docs/index.md#run-the-cli) for the full rename table.
-
 ## How does a coding agent verify its work?
 
 The coding agent should discover the project, test each server tool,
@@ -429,7 +417,7 @@ agent-sdk call inspect_pr --dir . \
 agent-sdk run --dir . \
   --message "Is https://github.com/acme/checkout/pull/42 ready to approve?"
 
-agent-sdk trajectory --events .agent-serve/traces/<sessionId>.ndjson
+agent-sdk trajectory --events <state-root>/traces/<sessionId>.ndjson
 
 agent-sdk eval --dir . --list
 agent-sdk eval --dir . --json
@@ -444,8 +432,8 @@ Test server tools with `call` before tuning the prompt. It runs a tool
 in-process with schema validation and no model turn. If the tool returns
 the wrong data, a prompt change won't fix it.
 
-`validate` and `run` don't type-check the project because tsx strips
-types. Run the project's TypeScript check before shipping. Tool results
+`validate` and `run` do not type-check the project. Run the project's
+TypeScript check before shipping. Tool results
 must also be JSON-shaped. Use object literals or `type` aliases for
 `execute` return types instead of `interface` types.
 
@@ -520,8 +508,8 @@ Other folders add subagents, hooks, schedules, and workspace files. You
 don't register them elsewhere. Run `agent-sdk validate` to catch
 invalid files before serving the project.
 
-See [Project layout](/docs/reference/project-layout.md) for every supported
-path.
+See [Project layout](/docs/reference/project-layout.md) for the folder
+structure.
 
 ## How does the Agent SDK identify a conversation?
 
@@ -540,8 +528,7 @@ observe or manage the conversation.
 
 ## How do I see what an agent did?
 
-Each session writes an append-only NDJSON file:
-`sessions/<id>/events.ndjson`. It includes:
+Each session records an append-only event stream. It includes:
 
 - Messages and streamed text
 - Requested tool calls and their results
@@ -554,7 +541,8 @@ playground renders the stream. Evals assert against it. The
 summary.
 
 When a run surprises you, inspect its event stream first. See
-[Sessions and streaming](/docs/reference/sessions.md) for every event.
+[Sessions and streaming](/docs/reference/sessions.md) for the event
+vocabulary.
 
 ## What does a channel control?
 
@@ -607,18 +595,13 @@ files, and adds agent tool scripts.
 
 The workspace is a real Cursor project. It can inherit `AGENTS.md` and
 `.cursor` settings from parent directories. Nested git checkouts default
-`local.cwd` to `~/.cache/agent-serve/<dir>`. Point `cwd` at a checkout
-only when the agent should inherit that tree. `run` and `eval` already
-use a temporary state root.
+`local.cwd` to a per-project cache directory under `~/.cache`. Point
+`cwd` at a checkout only when the agent should inherit that tree. `run`
+and `eval` already use a temporary state root.
 
-Durable local state uses this shape:
-
-```text
-<project>/.agent-serve/
-  sessions/<id>/events.ndjson
-  sessions/<id>/workspace/
-  traces/<sessionId>.ndjson
-```
+Session files live under `--state-root`. See
+[Sessions](/docs/reference/sessions.md#where-does-the-agent-sdk-store-session-data)
+for the layout.
 
 ## How can one agent call another?
 
@@ -806,10 +789,8 @@ the feature that needs the secret.
 
 Hosted filesystem state can reset during a deploy or runtime
 replacement. Prefer
-[`cursorHostedStorage`](/docs/storage.md) (`@cursor/july/storage/cursor-hosted`)
-so durable records land in Cursor's Bugbot `agent_serve_*` tables through
-a control-plane HTTP proxy (pod credential auth — no database URL in the
-engine). Do not put `BUGBOTDB_URL` or `AGENT_SERVE_DEPLOYMENT_ID` in
+[`cursorHostedStorage`](/docs/storage.md) so records survive replace.
+Do not put platform storage or deployment-identity names in
 `hosting.secretNames`. Self-host with your own `defineStorage` backend or
 a persistent `--state-root` when the complete filesystem must survive.
 
@@ -937,7 +918,7 @@ Without `envPrefix`, a dedicated app reads `SLACK_BOT_TOKEN` and
 ### Update, stop, or delete a deployment
 
 Redeploy the same slug after pushing a new Git ref. The stable alias
-continues to point at the active generation. Follow the same source rules
+continues to point at the latest deploy. Follow the same source rules
 from [Deploy from Git](#deploy-from-git).
 
 ```bash
@@ -954,7 +935,7 @@ reference.
 ## Self-host the Agent SDK
 
 The Agent SDK runs as a Node HTTP server on Node 22.13 or newer. You can host
-it on a VM, container platform, or ECS.
+it on a VM or container platform.
 
 ### The security model in one minute
 
@@ -1007,7 +988,7 @@ export AGENT_SDK_BEARER_TOKEN="$(openssl rand -hex 32)"
 
 # the server: all agents under one port
 agent-sdk serve --dir /srv/agents --port 3000 --host 127.0.0.1 \
-  --state-root /var/lib/agent-serve \
+  --state-root /var/lib/agent-sdk \
   --bearer-token "$AGENT_SDK_BEARER_TOKEN"
 ```
 
@@ -1038,8 +1019,8 @@ agent code. Humans reach the playground through a private network or
 tunnel. Keep `--bearer-token` on because tunneled requests arrive from
 loopback and IP-based policies can't tell them apart.
 
-Health checks: `GET /v1/health` at the host level (made for ALB and ECS
-checks), and each agent also serves `/<slug>/v1/health`.
+Health checks: `GET /v1/health` at the host level, and each agent also
+serves `/<slug>/v1/health`.
 
 ### Containers
 
@@ -1049,7 +1030,7 @@ package dependencies. Run `agent-sdk serve` as a non-root user:
 ```bash
 agent-sdk serve --dir /srv/agents --mode multi \
   --host 0.0.0.0 --port 3000 \
-  --state-root /var/lib/agent-serve \
+  --state-root /var/lib/agent-sdk \
   --bearer-token "$AGENT_SDK_BEARER_TOKEN"
 ```
 
@@ -1139,12 +1120,6 @@ targets) a real agent server, drives sessions over the public API, and
 grades what comes back. A passing eval means the agent started,
 accepted a message, and did what you asserted.
 
-> [!NOTE]
-> Import paths here use `@cursor/july/evals`. On projects still
-> using `@anysphere/agent-serve`, swap the import and run
-> `agent-serve eval`. See
-> [Run the CLI](/docs/index.md#run-the-cli) for the full rename table.
-
 ## Define evals with `defineEval`
 
 The Agent SDK discovers evals under the project-root `evals/` directory,
@@ -1248,7 +1223,7 @@ export default defineEvalConfig({
   // timeoutMs: 180_000, // optional project-wide default
   // judge: { model: "..." }, // default judge model for t.judge.*
   // reporters: [], // destinations that observe every case
-  // maxPlaygroundRuns: 50, // playground /v1/dev/evals history only (default 20)
+  // maxPlaygroundRuns: 50, // playground history only (default 20)
 });
 ```
 
@@ -1262,7 +1237,7 @@ The optional fields:
 | `timeoutMs` | `180_000` | Project-wide per-case timeout |
 | `judge` | unset | Default judge model for `t.judge.*`; see [Judge free-form output](#judge-free-form-output) |
 | `reporters` | unset | Destinations that observe every case; `--skip-report` suppresses them |
-| `maxPlaygroundRuns` | `20` | Max batches in the playground / `/v1/dev/evals*` history (not CLI `eval`) |
+| `maxPlaygroundRuns` | `20` | Max batches in the playground / `/v1/dev/evals*` history (not CLI `eval`). Hard-capped at 500. |
 
 Reporters come from `@cursor/july/evals/reporters`: `JUnit` writes a
 JUnit XML file for CI, `Artifacts` writes per-case files, and
@@ -1274,7 +1249,7 @@ Playground batches survive restarts whenever `agent/storage.ts` exists
 with an `evals` table or a KV core providing `delete` and `list` (the
 table is derived over the core); see
 [Storage](/docs/storage.md#eval-and-a-b-tables). Without storage they live
-in process memory and disappear when `serve` exits — navigating away
+in process memory and disappear when `serve` exits. Navigating away
 and back still works while the process is up.
 
 ## Drive and assert with `t`
@@ -1294,9 +1269,9 @@ intermediate turn before the next send overwrites `t.reply`.
 depend on it.
 
 Read the full case state with `t.reply` (the last assistant text),
-`t.events` (every captured session event across turns), `t.turns`
-(settled turns, oldest first), and `t.sessionId`. `t.signal` aborts
-when the case hits its timeout; pass it to your own async work.
+`t.events` (session events captured so far), `t.turns` (settled
+turns, oldest first), and `t.sessionId`. `t.signal` aborts when the
+case hits its timeout; pass it to your own async work.
 
 Assert with the gates:
 
@@ -1352,10 +1327,10 @@ the CLI and playground result.
 
 Three `t.send` options apply on session create (first `t.send` only):
 
-- `workspaceFiles` — `{ path: contents }`, seeded into the local session
+- `workspaceFiles`: `{ path: contents }`, seeded into the local session
   workspace. Prefer this over machine-local paths.
-- `workspaceDir` — absolute harness cwd (local runtime).
-- `cloud` — per-session cloud options merged over the agent's static
+- `workspaceDir`: absolute harness cwd (local runtime).
+- `cloud`: per-session cloud options merged over the agent's static
   `cloud` config (repos / env / …). Use a pinned `repos` override to
   attach a fixture repo for cloud evals without putting it on the
   agent's default `cloud.repos`. Cloud ignores `workspaceFiles` seeds.
@@ -1417,7 +1392,7 @@ match both groups.
 
 `eval` boots an ephemeral server on port 0 with a temp state root
 outside the project, so cases don't inherit ambient monorepo rules and
-don't pollute `.agent-serve/`. Point `--url` at a running server to eval
+don't write into the project state directory. Point `--url` at a running server to eval
 a live agent instead:
 
 ```bash
@@ -1471,29 +1446,18 @@ failed assertion without parsing terminal text.
 
 ## Run evals in the playground
 
-Start the server with `--dev`, open the playground, and choose
-**Evals**. You can run every case or one case, watch progress, and open
-the resulting session trace.
+Start the server, open the playground, and choose **Evals**. You can run
+every case or one case, watch progress, and open the resulting session
+trace. The Evals tab works on a normal `serve`.
 
 ```bash
-agent-sdk serve --dir . --dev
+agent-sdk serve --dir .
 ```
 
 Playground runs target the live server instead of an ephemeral one.
 Their sessions appear in the session list. One eval batch can run at a
-time. Batches persist across restarts whenever `agent/storage.ts`
-provides an `evals` table or a KV core with `delete` and `list` (the
-table is derived over the core); without storage they are **in-memory
-only** (capped by `maxPlaygroundRuns`) — see
-[Storage](/docs/storage.md#eval-and-a-b-tables).
-
-The UI uses the playground eval routes (available without `--dev`):
-`GET /v1/dev/evals` lists datapoints and config (includes `maxPlaygroundRuns` /
-`durableRuns`),
-`GET /v1/dev/evals/runs` rehydrates recent batches after navigation,
-`POST /v1/dev/evals/runs` starts a batch (returns an **Eval ID** / `runId`),
-`GET /v1/dev/evals/runs/:runId` polls it, and
-`POST /v1/dev/evals/runs/:runId/cancel` cancels a running batch. See
+time. Persistence follows the rule under
+[Configure eval runs](#configure-eval-runs). See
 [Playground eval routes](/docs/reference/http-api.md#playground-eval-routes).
 The start request returns `202` while cases run in the background.
 Poll until the snapshot status becomes `completed`, `failed`, or `cancelled`.
@@ -1512,10 +1476,6 @@ agent-sdk eval cancel evalrun_… --prod --slug vulnerability-scanner
 agent-sdk eval status evalrun_… --prod --slug vulnerability-scanner
 ```
 
-The Evals tab prefers the server’s in-flight batch (`activeRunId`) over a
-stale tab-local remembered id, so CLI / Slack kicks show up without an
-incognito window.
-
 ## What good cases assert
 
 Gate decisions and shape, not prose. Model wording varies run to run.
@@ -1678,7 +1638,7 @@ approving the PR.
 | Server tools | [`agent/tools/`](https://github.com/cursor/cursor/tree/main/packages/agent-serve/examples/approval-buddy/agent/tools/) | Prepare evidence, approve, list buddies, and search GIFs. |
 | Deterministic policy | [`agent/lib/approve.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/approval-buddy/agent/lib/approve.ts), [`agent/lib/buddies.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/approval-buddy/agent/lib/buddies.ts) | Own the roster and live eligibility checks. |
 | Review subagents | [`agent/subagents/`](https://github.com/cursor/cursor/tree/main/packages/agent-serve/examples/approval-buddy/agent/subagents/) | Run deep audit and code-quality passes over the same evidence. |
-| Storage | [`agent/storage.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/approval-buddy/agent/storage.ts) | Persist sessions and events with `cursorHostedStorage` (Bugbot `agent_serve_*`). |
+| Storage | [`agent/storage.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/approval-buddy/agent/storage.ts) | Persist sessions and events with `cursorHostedStorage`. See [Storage](/docs/storage.md). |
 | Live A/B experiment | [`agent/ab.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/approval-buddy/agent/ab.ts) | Compare baseline responses with a concise, presentation-only treatment (`concise-results`). |
 | Evals and unit tests | [`evals/`](https://github.com/cursor/cursor/tree/main/packages/agent-serve/examples/approval-buddy/evals/), [`agent/lib/`](https://github.com/cursor/cursor/tree/main/packages/agent-serve/examples/approval-buddy/agent/lib/) | Protect routing, output contracts, policy, and GitHub behavior. |
 
@@ -1928,7 +1888,7 @@ need the watched-channel path.
 
 | File | Purpose |
 | --- | --- |
-| [`agent/agent.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/benny/agent/agent.ts) | Names the agent, selects its model, and keeps the harness under `.agent-serve/harness`. |
+| [`agent/agent.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/benny/agent/agent.ts) | Names the agent, selects its model, and points the harness at a project-local cwd so inherited playbooks load. |
 | [`agent/instructions.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/benny/agent/instructions.md) | Defines engagement rules, evidence policy, and the playbook routing map. |
 | [`agent/channels/slack.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/benny/agent/channels/slack.ts) | Handles account-linked mentions and direct messages. |
 | [`agent/channels/slack-app.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/benny/agent/channels/slack-app.ts) | Runs the dedicated app and watches one allowlisted channel. |
@@ -1946,18 +1906,9 @@ large monorepo. This prevents ancestor instruction and repository-rule files
 from leaking into an unrelated agent.
 
 The playbook router needs the opposite. Its procedures live at the repository
-root, so
-`agent.ts` sets:
-
-```ts
-local: {
-  cwd: ".agent-serve/harness",
-}
-```
-
-Each harness workspace lands under
-`examples/benny/.agent-serve/harness/<sessionId>`. Walking up the directory
-tree reaches the host repository and its inherited playbook directory.
+root, so `agent.ts` points `local.cwd` at a harness directory under the
+project. Each harness workspace is a child of that directory. Walking up
+reaches the host repository and its inherited playbook directory.
 
 Those playbooks are inherited context. `agent-sdk info` reports zero authored
 skills for the agent. Copying this project into another repository removes
@@ -2333,9 +2284,9 @@ The wiki refuses to become a merge log:
 - Every touched page gets a dated changelog entry citing the PR
   number, so each fact traces back to a merge.
 
-The wiki itself is markdown on the serve host, in `.agent-serve/wiki/`
-by default with a `CODEBASE_WIKI_DIR` override. Sessions are
-disposable; the wiki is the durable state.
+The wiki itself is markdown on the serve host, in a wiki directory by
+default with a `CODEBASE_WIKI_DIR` override. Sessions are disposable;
+the wiki is the durable state.
 
 ## Follow a merged PR
 
@@ -2409,11 +2360,8 @@ agent-sdk github replay https://github.com/owner/repo/pull/123 \
 ```
 
 The reply is a 202 acknowledgement; the ingest continues in the task.
-Watch the session in the playground, then read the result on disk:
-
-```bash
-ls examples/codebase-wiki/.agent-serve/wiki/features/
-```
+Watch the session in the playground, then open the wiki directory on
+the serve host. Feature pages land under `features/`.
 
 Each ingested feature page carries an overview, a "How it works"
 section, and a changelog line citing the PR. Deterministic digest
@@ -2758,7 +2706,7 @@ A peer can only resolve within a multi-agent serve host. Validating Concierge
 alone checks its files, but serving it alone fails because `weather-agent`
 isn't mounted.
 
-From `packages/agent-serve`, validate both projects:
+From this package, validate both projects:
 
 ```bash
 agent-sdk validate --dir examples/concierge
@@ -2771,8 +2719,7 @@ two-project mount instead. Copy only the authored files needed for this proof,
 leaving Weather's Slack channels out:
 
 ```bash
-mkdir -p "$PWD/.agent-serve"
-PAIR_DIR=$(mktemp -d "$PWD/.agent-serve/concierge-weather.XXXXXX")
+PAIR_DIR=$(mktemp -d "${TMPDIR:-/tmp}/concierge-weather.XXXXXX")
 mkdir -p "$PAIR_DIR/concierge" "$PAIR_DIR/weather-agent/agent"
 cp -R examples/concierge/agent "$PAIR_DIR/concierge/"
 cp examples/concierge/package.json "$PAIR_DIR/concierge/"
@@ -2880,340 +2827,6 @@ one parent and needs no independent sessions, use a subagent instead.
 
 ---
 
-Source: /docs/example-agents/fsd.md
-
-# Hand PR triage to managed remote agents
-
-The remote PR coordinator keeps chat and routing on the local serve host,
-then hands each pull request to a managed remote agent with a real checkout.
-The same remote conversation resumes when a user drives the PR again, GitHub
-reports a change, or a merge-conflict reminder fires.
-
-This example is Cursor-internal. For your own repos, scaffold
-[PR autofixer](/docs/templates/pr-autofixer.md) instead.
-
-The workflow backend enrolls each remote run with a workflow MCP. Its tools
-and the host's findings routes read and write the same external findings
-service.
-
-Use this example when repository work is too heavy or concurrent for local
-worktrees, but the host should still own intake, session identity, policy, and
-bookkeeping.
-
-[Browse the current coordinator source.](https://github.com/cursor/cursor/tree/main/packages/agent-serve/examples/fsd/)
-
-## Resume one remote agent across every PR wake
-
-The coordinator uses a hybrid runtime:
-
-- Ordinary playground and Slack chat run locally.
-- The `drive_pr` server tool creates a remote session for one PR.
-- The remote worker gets the repository and PR reference.
-- An `agent.bound` hook records the remote run id and enrolls the run into a
-  workflow MCP.
-- Webhooks and reminders resume the same remote agent through durable
-  PR-to-agent affinity.
-
-No other example moves one logical conversation across local chat, remote
-execution, event wakes, and timed follow-ups.
-
-## Follow a chat request
-
-1. A user asks local chat or Slack to drive a PR.
-2. The root model calls `drive_pr` with the PR, mode, and optional hint.
-3. The tool calls `ctx.send("drive", ...)` with a per-session `cloud` block
-   to attach the PR.
-4. The Agent SDK creates or resumes the `drive` session keyed by
-   `pr:owner/repo#N`.
-5. The remote runtime provisions the agent and emits `agent.bound`.
-6. The enrollment hook writes PR affinity and calls the workflow backend to
-   attach run-scoped MCP tools.
-7. `drive_pr` waits for remote binding, then returns the agent id and URL.
-   If binding exceeds its wait window, those fields can be `null` while work
-   continues.
-8. The remote agent reads the host-prepared PR brief, checks unresolved state,
-   and records findings through the workflow MCP.
-9. The host forwards a validated fallback output block when MCP wasn't
-   available for the turn.
-
-The local chat agent doesn't have the target checkout, `gh`, `git`, or the
-workflow MCP. Its job is coordination.
-
-A request for a merged or closed PR finishes before provisioning. That result
-has `status: "finished"` and no remote session.
-
-## Map the framework features
-
-| Capability | Source | Role |
-| --- | --- | --- |
-| Hybrid config | [`agent/agent.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/fsd/agent/agent.ts) | Keep chat local, set remote-runtime defaults, disable automatic PR creation, and isolate local harness workspaces. |
-| Root instructions | [`agent/instructions.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/fsd/agent/instructions.md) | Separate local coordination from remote triage and define suggest/apply policy. |
-| Drive tool | [`agent/tools/drive_pr.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/fsd/agent/tools/drive_pr.ts) | Hand a chat request to the `drive` channel and wait for remote binding. |
-| Drive channel | [`agent/channels/drive.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/fsd/agent/channels/drive.ts) | Start remote work and expose findings read/write routes. |
-| GitHub channel | [`agent/channels/github.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/fsd/agent/channels/github.ts) | Buffer PR, comment, review, check, and status wakes. |
-| Slack channel | [`agent/channels/slack.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/fsd/agent/channels/slack.ts) | Route Slack requests to the local coordinator. |
-| Hooks | [`agent/hooks/enroll-fsd.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/fsd/agent/hooks/enroll-fsd.ts), [`agent/hooks/record-outputs.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/fsd/agent/hooks/record-outputs.ts) | Bind remote identity, enroll MCP, and forward fallback findings. |
-| Affinity and buffering | [`agent/lib/pr-affinity.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/fsd/agent/lib/pr-affinity.ts), [`agent/lib/webhook-buffer.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/fsd/agent/lib/webhook-buffer.ts) | Persist PR identity, sticky mode, and pending wakes. |
-| Reminders | [`agent/lib/merge-conflict-watch.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/fsd/agent/lib/merge-conflict-watch.ts) | Recheck merge conflicts every 30 minutes. |
-| Workflow client | [`agent/lib/fsd-platform.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/fsd/agent/lib/fsd-platform.ts) | Enroll external runs and read or record findings. |
-| Storage | [`agent/storage.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/fsd/agent/storage.ts) | Persist sessions and events with `cursorHostedStorage`. |
-
-The coordinator has no authored skill, subagent, MCP connection, static
-schedule, A/B experiment, eval, or tool approval.
-
-The workflow MCP is dynamic. Backend enrollment attaches it to the remote run,
-so there is no file under `agent/mcp-connections/`.
-
-## Understand local and remote workspaces
-
-The root config sets `runtime: "local"` because `drive_pr` is a server tool.
-It also supplies remote-runtime defaults through the `cloud` configuration:
-
-```ts
-local: {
-  cwd: join(homedir(), ".cache", "agent-serve", "fsd"),
-},
-cloud: {
-  env: { type: "cloud" },
-  autoCreatePR: false,
-},
-```
-
-The local cwd sits outside the monorepo, so inherited repository instructions
-don't affect coordinator chat.
-
-Remote sessions get a repository attachment with the target PR. The worker starts
-from the PR base and creates an automation side branch from the PR head only when
-code context or a fix is needed. The serve host never checks out target code.
-
-## Prepare access
-
-You need:
-
-- Node 22.13 or newer.
-- An agent-runtime user credential.
-- Access to a managed remote runtime.
-- Access to the target GitHub PR.
-- Access to the workflow backend and findings store.
-
-Keep the affinity and webhook-buffer files on durable storage for a
-long-lived host.
-
-## Validate without starting remote work
-
-```bash
-agent-sdk validate --dir examples/fsd
-agent-sdk info --dir examples/fsd --json
-agent-sdk github events --dir examples/fsd --json
-```
-
-These commands inspect discovery and declared GitHub events. They don't
-provision a remote agent.
-
-## Choose suggest or apply
-
-Every PR has a sticky mode:
-
-| Mode | Required remote behavior |
-| --- | --- |
-| `suggest` | May create verified commits on the VM's local side branch. Instructions require no pushes, comments, PR edits, or workflow actions. Records exact fixes and actions as findings for the owner. |
-| `apply` | Pushes verified fixes to the existing PR head and may update metadata, reply to threads, mark a draft ready, rebase, or rerun CI. |
-
-The remote instructions forbid merging, enabling auto-merge, force-pushing,
-and opening a new PR in both modes. `autoCreatePR: false` also disables the
-SDK's automatic PR creation. The other restrictions are prompt policy, not a
-deterministic host gate. `suggest` is the default.
-
-The selected mode is stored beside PR affinity. Webhooks and reminders reuse
-it. Re-driving a PR can change the host-side mode. Backend enrollment records
-the mode at first enrollment, so each later host prompt repeats the current
-authoritative mode.
-
-> [!CAUTION]
-> `apply` writes to the user's PR branch and triggers CI. Use `suggest` for
-> development. Both modes provision a billed remote agent and can write
-> structured findings to the findings service. `drive_pr` has no approval gate,
-> and suggest/apply restrictions depend on the remote agent following its
-> instructions.
-
-## Start a suggest-mode drive
-
-Run the host:
-
-```bash
-agent-sdk dev examples/fsd
-```
-
-From chat:
-
-> Drive https://github.com/owner/repo/pull/123 in suggest mode.
-
-Or call the coordinator tool:
-
-```bash
-agent-sdk call drive_pr \
-  --dir examples/fsd \
-  --input '{"pr":"https://github.com/owner/repo/pull/123","mode":"suggest"}'
-```
-
-For an open PR, the tool waits up to 60 seconds for remote binding and returns:
-
-- the normalized PR label,
-- session and continuation ids,
-- the remote-agent id and URL when binding completes in that window,
-- `status: "started"`, and
-- the merge-conflict reminder id.
-
-It doesn't wait for findings. A slow binding can return `null` identifiers.
-Open the returned agent URL when present to follow the remote run.
-
-## Use the HTTP drive surface
-
-The custom channel starts the same orchestration:
-
-```bash
-curl -s -X POST \
-  http://127.0.0.1:3000/fsd/v1/channels/drive/ \
-  -H 'content-type: application/json' \
-  -d '{"pr":"owner/repo#123","mode":"suggest"}'
-```
-
-This route returns as soon as the channel session exists. The remote-agent id
-can still be `null` at that point. Triage continues in the background.
-
-Read findings later:
-
-```bash
-curl -s \
-  'http://127.0.0.1:3000/fsd/v1/channels/drive/findings?pr=owner/repo%23123'
-```
-
-The external findings service is the source of truth. The local host doesn't keep a second
-findings database.
-
-The channel also exposes `POST /findings` as a testing surface. It validates
-outputs, then writes them to the findings service for a PR already bound by this
-host. The route has no approval gate. Keep it under the default loopback auth
-or another trusted boundary.
-
-## Keep one remote agent per PR
-
-Within the `drive` channel, the stable continuation token
-`pr:owner/repo#N` resumes the same session. GitHub sessions are scoped to
-another channel, so a continuation token alone can't bridge them.
-
-The enrollment hook closes that gap:
-
-1. Read the PR from the continuation token or host-authored session title.
-2. Record PR to `sdkAgentId` affinity after `agent.bound`.
-3. Seed later sessions with the same remote id.
-4. Retry workflow MCP enrollment after a completed turn when the first RPC
-   failed.
-
-This lets Slack, HTTP drive, GitHub, and reminders talk to one remote
-conversation without sharing one channel session.
-
-## Buffer GitHub wakes
-
-The GitHub channel handles pull requests, comments, reviews, check suites,
-check runs, and selected status events. It doesn't send payload details to the
-model. It asks the remote agent to refresh live source of truth.
-
-The buffer:
-
-- groups events by PR,
-- waits three seconds for a burst to settle,
-- re-buffers while CI settles,
-- skips a flush when the PR session is busy,
-- tries to write its snapshot before acknowledging a wake, and
-- restores pending entries when the channel starts.
-
-Closing a PR discards its pending entry and cancels its reminders.
-
-Snapshot persistence is best-effort. Write failures are swallowed silently,
-so a delivery can still be acknowledged without a durable snapshot.
-
-This is the high-volume counterpart to a direct `{ auth }` GitHub wake. See
-[GitHub](/docs/guides/github.md#handle-high-event-volume) for the reusable
-pattern.
-
-## Add merge-conflict checks
-
-Starting a drive arms one recurring reminder per PR. Every 30 minutes the host
-checks mergeability:
-
-- closed or merged stops the reminder,
-- clean skips delivery,
-- conflicting sends a follow-up to the owning session, and
-- a busy session skips the wake.
-
-This uses runtime reminders, not a static `agent/schedules/` file. The host
-creates, lists, replaces, and cancels reminders through `host.reminders`.
-Development mode doesn't fire reminder timers automatically. Dispatch one
-through the dev reminder endpoint for a manual proof, or use non-dev `serve`
-to run the 30-minute cadence.
-
-The reminder's `run` handler lives in memory. After a host restart, the Agent SDK
-disarms it with `handler_lost_on_restart`; a later drive or webhook path can
-arm a fresh handler. Persisted reminder metadata alone doesn't keep the check
-running.
-
-## Record findings with MCP or a fallback
-
-After enrollment, the remote agent receives workflow tools for:
-
-- recording and updating outputs,
-- listing current outputs,
-- reading PR metadata,
-- reading CI state, and
-- reading review comments.
-
-The main output is a structured workflow suggestion or code-change reference.
-The remote prompt requires findings as soon as each action becomes clear.
-
-If enrollment races or MCP is unavailable, the agent writes one fenced
-fallback JSON block. The host validates allowed kinds, actions, statuses, and
-the 140-character finding body before forwarding it to the same findings
-service. The output hook catches fallback blocks from webhook and reminder
-turns.
-
-## Verify the host logic
-
-The coordinator has no filesystem evals. Its unit tests cover mode parsing, drive
-orchestration, affinity, webhook durability, CI settlement, output parsing,
-reminders, and Slack configuration:
-
-```bash
-pnpm exec vitest run examples/fsd/agent/lib
-```
-
-Use those tests for host policy. Use a dedicated test PR and suggest mode for
-the end-to-end remote path.
-
-## Build another hybrid coordinator
-
-Use this architecture when each work item needs a real checkout:
-
-1. Keep conversational intake local.
-2. Open a remote session only after the request identifies a work item.
-3. Give the work item a stable continuation key.
-4. Persist its remote-agent id for cross-channel resume.
-5. Coalesce noisy events before spending another turn.
-6. Put the current mode and permissions in every host prompt.
-7. Record outputs incrementally in a durable sink.
-8. Add reminders for state requiring periodic rechecks.
-
-## Where to go next
-
-- [Cloud runtime](/docs/guides/cloud-runtime.md)
-- [GitHub](/docs/guides/github.md)
-- [Webhooks and custom channels](/docs/guides/webhooks.md)
-- [Schedules and reminders](/docs/reference/schedules.md)
-- [Sessions and streaming](/docs/reference/sessions.md)
-- [Deployment](/docs/deployment.md)
-
----
-
 Source: /docs/example-agents/index.md
 
 # Choose the right Agent SDK example
@@ -3225,7 +2838,7 @@ design.
 
 The source projects live under
 [`examples/`](https://github.com/cursor/cursor/tree/main/packages/agent-serve/examples/). Run the commands below from
-`packages/agent-serve`. See [Run the CLI](/docs/index.md#run-the-cli) if the
+this package. See [Run the CLI](/docs/index.md#run-the-cli) if the
 `agent-sdk` command isn't installed.
 
 ## Compare the examples
@@ -3239,8 +2852,7 @@ The source projects live under
 | [Alert investigator](/docs/example-agents/oncall.md) | Local | Watched Slack alerts channel | Bot-post channel watching, per-thread debounce, reminder tools, and host Slack calls | Every alert gets a thread-pinned investigation that schedules its own re-checks. |
 | [PR evidence reviewer](/docs/example-agents/bugbot.md) | Local | Custom HTTP and Slack | Host tool, skill, seeded workspaces, and an eval | The model receives a prepared diff-first evidence tree instead of a checkout. |
 | [Approval Buddy](/docs/example-agents/approval-buddy.md) | Local | GitHub and Slack | Policy tools, two subagents, durable storage, and evals | Code decides whether a PR may be approved. Reviews stay informational. |
-| [Security Reviewer](/docs/example-agents/security-reviewer.md) | Local host pipeline | GitHub and chat | Staged tools, parallel SDK agents, progress UI, durable storage, A/B, and evals | Lives in `factory/security-reviewer/`. Reviewers and triage overlap while the playground shows every stage. |
-| [Remote PR coordinator](/docs/example-agents/fsd.md) | Local coordinator and remote PR sessions | HTTP, GitHub, and Slack | Remote handoff, hooks, affinity, buffering, reminders, and workflow MCP | One remote conversation follows a PR across chat, webhooks, and timed wakes. |
+| [Security Reviewer](/docs/example-agents/security-reviewer.md) | Local host pipeline | GitHub and chat | Staged tools, parallel SDK agents, progress UI, durable storage, A/B, and evals | Reviewers and triage overlap while the playground shows every stage. |
 | [Knowledge base](/docs/example-agents/knowledge-base.md) | Local | Built-in HTTP chat | Durable host-side state, a conventions skill, a schedule, unit tests, and evals | People curate shared facts in chat, and fresh sessions retrieve them from markdown. |
 | [Codebase wiki](/docs/example-agents/codebase-wiki.md) | Local | GitHub and chat | Task-dispatch webhooks, seeded digests, a mapping skill, a schedule, and evals | Merged PRs accumulate into per-feature wiki pages with a daily digest. |
 | [Codeowners review](/docs/example-agents/codeowners-review.md) | Local | GitHub, chat, and fixtures | Ownership routing in code, playbook data files, parallel subagents, and evals | Each product area reviews with its own playbook, and verdicts aggregate mechanically. |
@@ -3261,8 +2873,8 @@ Use this order when you want to learn the Agent SDK one capability at a time:
 6. Study [PR evidence reviewer](/docs/example-agents/bugbot.md) before giving a model repository
    evidence.
 7. Move policy into code with [Approval Buddy](/docs/example-agents/approval-buddy.md).
-8. Compare [Security Reviewer](/docs/example-agents/security-reviewer.md) and
-   [Remote PR coordinator](/docs/example-agents/fsd.md) for host-side versus remote PR work.
+8. Study [Security Reviewer](/docs/example-agents/security-reviewer.md) for host-side PR
+   work.
 9. See parallel subagent delegation carry team judgment in
    [Codeowners review](/docs/example-agents/codeowners-review.md).
 10. Curate team context through conversation with
@@ -3285,9 +2897,7 @@ Several examples need more:
 - GitHub examples require access to the target repository. Codebase wiki and
   Codeowners review call the host `gh` CLI for PR data; the codeowners
   fixtures run without network.
-- Example agents use `cursorHostedStorage` (`agent/storage.ts`) for Cursor-hosted session storage (control-plane proxy).
-- Remote PR coordinator starts remote agent sessions and needs access to its
-  workflow backend.
+- Example agents use `cursorHostedStorage` in `agent/storage.ts` for hosted session storage. See [Storage](/docs/storage.md).
 
 Each guide lists its own credentials, services, and side effects.
 
@@ -3339,8 +2949,8 @@ feature documentation instead.
 
 ## Keep shared knowledge on the filesystem
 
-The knowledge base lives outside any session workspace, in
-`.agent-serve/wiki/` by default. `KNOWLEDGE_BASE_DIR` overrides the location,
+The knowledge base lives outside any session workspace, in a wiki
+directory on the serve host by default. `KNOWLEDGE_BASE_DIR` overrides the location,
 and the tools resolve it on every call, so tests and evals can point the same
 code at a temp directory.
 
@@ -3885,10 +3495,10 @@ findings, accounting, and audit events.
 
 ## Separate session storage from review artifacts
 
-`defineStorage` + `cursorHostedStorage` sends Agent SDK session and event records
-to Cursor-hosted Bugbot storage through the control-plane proxy. Security
-Reviewer sets `restore: "off"` so startup doesn't load old review sessions in
-bulk. A continuation lookup can still fetch a needed session.
+`cursorHostedStorage` keeps Agent SDK session and event records on
+Cursor-managed hosting. Security Reviewer sets `restore: "off"` so startup
+doesn't load old review sessions in bulk. A continuation lookup can still
+fetch a needed session. See [Storage](/docs/storage.md).
 
 The staged review files are separate from session storage. Session-store
 durability doesn't preserve those files. All stages for one `runId` must see
@@ -3910,7 +3520,7 @@ instruction overlay asking chat and playground summaries to lead with high
 and critical findings. Full artifacts, `finalResponse`, and finding counts
 still include every finding. Stage-tool counters appear in the
 playground A/B view. Local sample and snapshot files persist under
-`.agent-serve/`.
+the project state directory.
 
 When a treatment session has only low or medium findings, the filtered review
 body currently says no vulnerabilities were found even though artifacts and
@@ -4274,8 +3884,8 @@ A real call writes `vm-tool-observations/<id>.json` in the agent cwd and
 returns hostname, cwd, and pid. Stream events show `probe:probe_cloud_tool`,
 not `shell`.
 
-A local `.agent-serve/tools/probe_cloud_tool.sh` or a marker under `probes/`
-means the model invented a substitute.
+A local tool script or a marker under `probes/` means the model
+invented a substitute.
 
 ```bash
 agent-sdk run --dir examples/weather-agent \
@@ -4390,7 +4000,8 @@ hash:
 - `treatment` adds a brief Celsius instruction and changes `get_weather` to
   return Celsius fields.
 
-Samples and aggregate snapshots persist under `.agent-serve/`. The treatment
+Samples and aggregate snapshots persist under the project state
+directory. The treatment
 only changes current conditions; `get_forecast` still returns Fahrenheit.
 Treat the branch as an example of `ctx.session.abs`, not a complete unit
 policy.
@@ -4442,7 +4053,7 @@ same. A peer MCP connection makes the wiring one line.
 This guide wires a `concierge` agent that delegates weather questions
 to a `weather-agent` peer mounted on the same host.
 
-## The MCP endpoint
+## MCP endpoint
 
 Each agent serves the Model Context Protocol over streamable HTTP at
 `/<slug>/v1/mcp` (or `/v1/mcp` in single mode). The surface is stateless
@@ -4610,34 +4221,21 @@ mapping shifts:
 | `instructions.*` | `AGENTS.md` in the session workspace | prepended to the first prompt |
 | Server tools (`execution: "server"`) | in-process SDK custom tools | authenticated HTTP MCP back to the AgentSDK host, when `--public-url` or `--cloud-tools-url` is set |
 | Agent tools (`execution: "agent"`) | scripts in the session workspace | catalog + script bodies on the first prompt |
-| `skills/*` | `.cursor/skills/` in the workspace | native discovery from the Agent Store (`skills/` on hosted deployments; `agent-serve/<agent>/skills/` on the USER store for local serve/run) |
+| `skills/*` | `.cursor/skills/` in the workspace | native discovery after the first turn, from the hosted store or the signed-in account |
 | `mcp-connections/*.ts` | SDK `mcpServers` | SDK `mcpServers` (peers need `--public-url`) |
 | `sandbox/workspace/**` | seeded into the session workspace | ignored |
 | Tool approvals (`needsApproval`) | supported | not supported; keep approval-gated tools on local turns |
 
-Authored skills copy onto an Agent Store on the first cloud turn so the
-VM discovers them natively. Hosted deployments write the deployment
-store's `skills/` directory; local `serve`/`run` with a personal API
-key writes `agent-serve/<agent>/skills/` on the USER store.
-
-Hosted deployments configure the server-tool MCP URL automatically
-(`cloudToolsUrl`, authenticated with the resolved Cursor API key). A
-self-hosted public server needs `--public-url` (and `--bearer-token` when the
-host is not behind another trusted authentication boundary) so cloud turns
-can reach those tools. Without either, the server warns at startup and
-cloud turns omit the server tools.
+Authored skills are discovered natively after the first cloud turn,
+using the hosted store or the signed-in account.
 
 Approvals are a local-runtime contract. On cloud, a `needsApproval` tool
 call rides one HTTP MCP request from the VM, and a parked call would
 hold that request open until it times out; there is no durable approval
 flow for cloud turns.
 
-Two more behaviors are cloud-specific. Sessions persist a separate SDK
-agent id (`bc-…`), emitted on the stream as `agent.bound` with a URL to
-the cloud conversation. Cloud ids are minted during the first send. And
-peer MCP connections resolve to `--public-url` for cloud turns, because a VM
-cannot reach the host's loopback; without one, peers are omitted from
-cloud turns and the server warns at startup.
+Peer MCP connections need `--public-url` for cloud turns. Without one,
+peers are omitted and the server warns at startup.
 
 ## Hybrid: local agent, cloud sessions
 
@@ -4652,12 +4250,8 @@ base that per-session options merge over.
 
 These come from running a PR driver against real PR traffic:
 
-- One cloud agent per unit of work (per PR, say). Store the `bc-…` id
-  keyed by the work unit (an affinity store written from an
-  `agent.bound` hook) so webhook wakes resume the same conversation
-  instead of booting a fresh VM per event.
-- Stable continuation keys (`pr:owner/repo#N`) so every wake lands on
-  the same session within a channel.
+- One cloud session per unit of work, keyed with a stable continuation
+  token (`pr:owner/repo#N`) so every wake lands on the same conversation.
 - Keep the host deterministic: fetch briefs and metadata on the host,
   send the VM a compact prompt, and let the VM re-read source of truth
   with its own `gh` and `git` instead of trusting payload snapshots.
@@ -4677,7 +4271,7 @@ driving channels directly.
 Continue with these pages:
 
 - [Agent config](/docs/reference/agent-config.md): the `runtime` and
-  `cloud` fields precisely
+  `cloud` fields
 - [GitHub guide](/docs/guides/github.md): the webhook patterns that pair with
   cloud triage
 
@@ -4724,9 +4318,9 @@ cd nightly-triage
 ```
 
 The command fetches the Automation before writing files. A 404 means it
-was not found, you do not have access, or the `agent_serve_mvp` feature
-gate is off for your team. A 422 means it is Cursor-managed. The command
-writes nothing after either error.
+was not found, you do not have access, or convert is not enabled for
+your team. A 422 means it is Cursor-managed. The command writes nothing
+after either error.
 
 The command runs `npm install` after writing the project. If the install
 fails, the files remain. Run `npm install` in the output directory
@@ -4907,8 +4501,9 @@ Choose `permissions` by what the agent needs:
 `contents-write` is an explicit opt-up. `progress.commitStatus` posts a
 GitHub check run (`checks:write`). Hosted `cursorAccount` mints that
 permission on `"contents-write"` tokens. Enabling `commitStatus` opts a
-`"pr-write"` channel up to that tier so github-proxy can post the check.
-`"pr-write"` without `commitStatus` is enough for comments and banners.
+`"pr-write"` channel up to that tier because it needs check-write
+permission. `"pr-write"` without `commitStatus` is enough for comments
+and banners.
 Prefer `"pr-write"` unless the agent must push or post a merge-box check.
 
 Set `checks: true` when channel code posts its own Checks API runs through
@@ -4928,10 +4523,9 @@ Repeat `--repo` for each repository. The stream and credential are
 resolved as the signed-in Cursor principal. `serve` refuses to start
 signed out.
 
-Offset and consumer id live under `<state-root>/cursor-events/`.
-`CURSOR_API_BASE_URL` overrides the backend. The stream carries event
-metadata, not full webhook bodies, so your agent should re-read the PR
-or checks from GitHub instead of trusting a snapshot in the wake.
+The stream carries event metadata, not full webhook bodies, so your
+agent should re-read the PR or checks from GitHub instead of trusting a
+snapshot in the wake.
 
 This is the preferred production path: no public URL, no repo admin
 webhook, and no inbound network for GitHub deliveries.
@@ -4969,7 +4563,7 @@ things:
 | `{ task }` | Host-side work. The delivery is 202-ACKed immediately and the task runs past GitHub's ~10-second timeout. No chat session. |
 | `null` | Skip this delivery. |
 
-`{ auth }` may also carry `workspaceFiles` — the same session seed Slack
+`{ auth }` may also carry `workspaceFiles`, the same session seed Slack
 and `send()` use. Pass a function to fetch after a 202 so I/O can miss
 GitHub's ~10s window.
 
@@ -5056,9 +4650,7 @@ These patterns come from running a PR agent against real traffic:
 - Persist the buffer in `host.kv` before you acknowledge a wake, and
   restore it on channel start. A restart must not drop buffered wakes.
 - Key sessions with a stable continuation token (`pr:owner/repo#N`) so
-  every wake resumes the PR's conversation. Cross-channel resume needs
-  an affinity store mapping PR → SDK agent id; write it from an
-  `agent.bound` hook with `ctx.host.kv`.
+  every wake resumes the PR's conversation.
 - Keep payload details out of wake prompts. Send a generic "re-check
   the PR" and let the agent re-read source of truth instead of trusting a
   stale snapshot.
@@ -5120,19 +4712,9 @@ behavior. Reactions still default on; set `reactions: false` when the
 eyes emoji is noise. Descriptions are optional; defaults derive from
 `botName` or the check `context`.
 
-The check run posts to `channel.state.headSha`. PR and CI wakes seed and
-refresh it (`refreshState` on continuation). A first wake that is only an
-`issue_comment` has no head SHA in the payload, so the check is skipped until
-a PR/CI wake stores one; the banner still posts. Review-comment wakes
-carry `pull_request.head.sha` when GitHub includes it.
-
-The sticky comment id and latest check-run id live on durable
-`GitHubChannelState` (session record). Each wake also passes `refreshState`
-so `headSha` / refs update on continuation without wiping those ids. A later
-turn on the same SHA creates a new check run — GitHub cannot reopen a
-completed run. Persist other derived state
-with `ctx.host.kv` or `ctx.host.files`. `stateRoot` resets on hosted
-replace.
+A comment-only first wake has no head SHA, so the check waits for a
+PR or CI event. The banner still posts. A later turn on the same SHA
+creates a new check run; GitHub cannot reopen a completed run.
 
 Override `events` when the mapping is custom. [Approval Buddy](/docs/example-agents/approval-buddy.md)
 posts commit status from `turn.started` / `action.result` / `turn.failed`
@@ -5299,8 +4881,8 @@ The companion skill is
 
 - Authorize `defineConnection({ url, oauth: true })` with a browser PKCE
   flow (`agent-sdk mcp oauth <connection>`)
-- Keep tokens in `~/.config/agent-serve/mcp-auth.json`, bound to that
-  connection's resource URL
+- Keep tokens in `mcp-auth.json` under the CLI config directory, bound
+  to that connection's resource URL
 - Upsert deployment secrets with `--store` so hosted engines seed the
   same tokens from env
 - Keep privileged servers off the model with `hostOnly: true` while
@@ -5378,8 +4960,8 @@ What happens:
    `oauth: true`
 2. It opens the authorization URL in your browser
 3. The callback lands on `http://localhost:8787/callback`
-4. Tokens land in `~/.config/agent-serve/mcp-auth.json` (override the
-   config dir with `AGENT_SERVE_CONFIG_DIR`)
+4. Tokens land in `mcp-auth.json` under the CLI config directory
+  (override with `AGENT_SERVE_CONFIG_DIR`)
 
 If you're already authorized, the command prints that and exits. Re-run
 it after rotating tokens on the MCP server, or after you change the
@@ -5786,7 +5368,7 @@ writes `<PREFIX>_SLACK_BOT_TOKEN` and `<PREFIX>_SLACK_APP_TOKEN` into
 [below](#wire-the-env-and-verify).
 
 If Slack needs a workspace admin to approve the app, keep the CLI
-running. Managed install does not file the request — open Slack's
+running. Managed install does not file the request. Open Slack's
 **Request approval** page (the CLI prints the link; the same URL is
 **Send a reminder** after you submit). After an admin approves, click
 **Retry** in the wizard.
@@ -5849,9 +5431,9 @@ option.
 agent-sdk slack init --manual --dir . --name "My Agent"
 ```
 
-That writes `agent/channels/slack.ts`, importable manifests at
-`.agent-serve/slack/manifest.{dev,prod}.json`, `env.example`, and
-`setup-status.json`. `--no-prefix` uses shared `SLACK_*` variables on
+That writes `agent/channels/slack.ts`, Slack manifests under the
+project state directory, `env.example`, and `setup-status.json`.
+`--no-prefix` uses shared `SLACK_*` variables on
 a single-agent host. `--prefix CUSTOM` overrides the directory-derived
 prefix. `--channel-posts` subscribes the manifests to channel-post
 events.
@@ -6017,8 +5599,8 @@ mechanism. This page is the mechanism itself.
 The built-in HTTP channel is always mounted (under `/<slug>` in the
 default multi-agent layout). `POST /v1/session` starts a conversation,
 `POST /v1/session/:id` follows up, and `GET /v1/session/:id/stream`
-streams NDJSON events, plus sessions, approvals, and tool routes. The
-full list is in the [HTTP API reference](/docs/reference/http-api.md).
+streams NDJSON events, plus sessions, approvals, and tool routes. See
+the [HTTP API reference](/docs/reference/http-api.md).
 
 Write a custom channel when that shape doesn't fit: a webhook with its
 own payload contract, a surface that keys sessions by a domain id, or a
@@ -6452,7 +6034,7 @@ Start with curl and saved payloads under `fixtures/`. The playground's
 endpoint, has Copy curl, and opens the created session on a successful
 Try. For regression coverage, drive the same behavior through an eval,
 or keep channel logic deterministic in `agent/lib/` and unit-test it
-there. When something looks wrong, read the session's `events.ndjson`.
+there. When something looks wrong, inspect the session event stream.
 The stream is the record of what happened.
 
 For GitHub specifically, don't hand-roll fixtures.
@@ -6525,7 +6107,7 @@ Pin the input first. A moving fixture is noise. For GitHub agents, use `agent-sd
 
 ## How do I run one hillclimb round?
 
-**Measure.** Hit the agent the way a user would: playground, channel HTTP, or Slack in `--dev`. Or ask the hillclimb skill to do it. `agent-sdk run` returns a JSON trajectory and writes a trace under `.agent-serve/traces/`.
+**Measure.** Hit the agent the way a user would: playground, channel HTTP, or Slack in `--dev`. Or ask the hillclimb skill to do it. `agent-sdk run` returns a JSON trajectory and writes a trace under the project state directory.
 
 **Reflect.** Score the trajectory, not impressions. Was the answer right? Did the model thrash (too many tools, fat evidence, grep loops)? Did it invent work the host should have prepared? Name the single dominant problem for this round in one sentence. Example: "Full-file dumps trigger grep loops."
 
@@ -6666,8 +6248,8 @@ npx @cursor/july docs
 
 **Example agents**
 
-- [Choose the right example](/docs/example-agents/index.md): compare all twelve
-  agents by runtime, channels, tools, state, and architecture.
+- [Choose the right example](/docs/example-agents/index.md): compare the
+  example agents by runtime, channels, tools, and state.
 - [Weather agent](/docs/example-agents/weather-agent.md): explore tools, MCP,
   approvals, skills, subagents, schedules, hooks, A/B metrics, and evals.
 - [Slack agent](/docs/example-agents/slack-agent.md): put a minimal agent in
@@ -6684,8 +6266,6 @@ npx @cursor/july docs
   in code while subagents supply review findings.
 - [Security Reviewer](/docs/example-agents/security-reviewer.md): run a staged,
   parallel security pipeline with live playground progress.
-- [Remote PR coordinator](/docs/example-agents/fsd.md): hand PR triage from local
-  chat and webhooks to durable remote sessions.
 - [Knowledge base](/docs/example-agents/knowledge-base.md): turn conversations
   about people, systems, decisions, and preferences into shared markdown.
 - [Codebase wiki](/docs/example-agents/codebase-wiki.md): ingest merged PRs into
@@ -6722,12 +6302,6 @@ npx @cursor/july docs
 Docs use `agent-sdk <command>`. If it isn't on `PATH`, use
 `npx @cursor/july <command>`.
 
-From `packages/agent-serve` in a source checkout:
-
-```bash
-alias agent-sdk="pnpm exec tsx $PWD/src/bin/agent-serve.ts"
-```
-
 ## Credentials
 
 Sign in to Cursor or set `CURSOR_API_KEY`:
@@ -6767,7 +6341,7 @@ review. Add GitHub event handling so pull requests can trigger reviews.
 - Node 22.13 or newer. Bun isn't supported.
 - Run commands as `agent-sdk <command>`, or use
   `npx @cursor/july <command>` when the CLI isn't on `PATH`. See
-  [Run the CLI](/docs/index.md#run-the-cli) for monorepo checkouts and other setups.
+  [Run the CLI](/docs/index.md#run-the-cli) if `agent-sdk` is not on `PATH`.
 - A Cursor credential for model turns. Sign in once:
 
 ```bash
@@ -7185,8 +6759,8 @@ model: "composer-2.5",
 ## Choose a runtime
 
 `runtime: "local"` (the default) runs turns on the Cursor SDK harness on
-this machine. The session id doubles as the SDK agent id, and server
-tools, skills, sandbox seeds, and tool approvals all apply.
+this machine. Server tools, skills, sandbox seeds, and tool approvals
+all apply.
 
 `runtime: "cloud"` runs turns on Cursor cloud agents (`bc-…` ids). Pass
 a `cloud` block with the repos the VM carries. Server tools stay
@@ -7230,8 +6804,8 @@ it.
 
 Session workspaces are real Cursor project directories. The harness loads
 `AGENTS.md` and `.cursor` config from ancestor directories. An agent nested
-in another git repo (a monorepo package) defaults to
-`~/.cache/agent-serve/<dir>` when you omit `cwd`, so the enclosing checkout
+in another git repo (a monorepo package) defaults to a per-project
+cache directory under `~/.cache` when you omit `cwd`, so the enclosing checkout
 does not leak rules, skills, or MCP servers into the turn. A standalone git
 root keeps the in-project session workspace. Point `cwd` at a checkout only
 when the agent should inherit that tree.
@@ -7253,7 +6827,7 @@ export default defineAgent({
 });
 ```
 
-Agent Serve always adds `"mcp"` to a configured allowlist. Authored
+The Agent SDK always adds `"mcp"` to a configured allowlist. Authored
 server tools in `agent/tools/` use MCP to reach the model. MCP can also
 expose declared connections and servers from the harness directory's
 ambient `.cursor` config. To exclude a checkout's MCP servers, point
@@ -7274,7 +6848,7 @@ Two names have broader effects:
 
 Tool allowlists work only with the local runtime. A
 `runtime: "cloud"` agent that sets `tools` fails at serve startup.
-Agent Serve also refuses per-send cloud sessions from a hybrid agent
+The Agent SDK also refuses per-send cloud sessions from a hybrid agent
 with an allowlist. It won't run those sessions with unrestricted tool
 access.
 
@@ -7282,7 +6856,7 @@ The allowlist controls which tools the model can call. It does not
 isolate the serve host. For agents that process untrusted input, also
 set `local: { sandbox: true }`.
 
-## The `cloud` block
+## Cloud options
 
 Cloud agent defaults forwarded to the Cursor SDK: `repos` (each
 `{ url, startingRef? }`), environment selection, `envVars`, and the
@@ -7354,13 +6928,8 @@ console.log(`listening on ${handle.url}`);
 // handle.createReminder(...), handle.project, await handle.close()
 ```
 
-`ServeOptions` mirrors the CLI flags: `port`, `host`, `dev`,
-`stateRoot`, `apiKey`, `schedules`, `reminders`, `noControlPlane`,
-`playground`, `docs`, `authToken` (the `--bearer-token` equivalent),
-`allowAnonymous`, `allowAnonymousCursorGithub`,
-`allowAnonymousCursorAccountMcp`, `cursorGithubProxy`, `publicUrl`,
-`cloudToolsUrl`, `cursorEvents`, and `logger`. `serve()` additionally
-accepts `discovery` (project-loading options) and
+Host settings match the documented [CLI](/docs/reference/cli.md) `serve` flags.
+`serve()` also accepts `discovery` (project-loading options) and
 `mode: "single" | "multi"`. The Cursor credential resolves in one order
 everywhere: explicit `apiKey`, then `CURSOR_API_KEY`, then the key
 stored by `agent-sdk login`.
@@ -7373,7 +6942,7 @@ Continue with these pages:
   agent
 - [Cloud runtime](/docs/guides/cloud-runtime.md): when and how to leave
   the host
-- [CLI](/docs/reference/cli.md): the flags `ServeOptions` mirrors
+- [CLI](/docs/reference/cli.md): the `serve` flags `serve()` accepts
 
 ---
 
@@ -7504,7 +7073,7 @@ under `/v1/channels/<id>`. The Slack and GitHub packs are prebuilt
 channels with platform transports. This page is the authoring reference;
 for the walkthrough, see the [Webhooks guide](/docs/guides/webhooks.md).
 
-## The built-in HTTP channel
+## Built-in HTTP channel
 
 It's always mounted, under `/<slug>` in the default multi-agent layout:
 session create, follow-up, stream, stop, the sessions list, approvals,
@@ -7625,11 +7194,9 @@ Handlers receive the Fetch `Request` and an args object:
 `"coalesce"` enqueues behind the running turn, the
 [Slack policy](/docs/reference/sessions.md#what-happens-when-i-send-a-follow-up)),
 `workspaceFiles`, `workspaceDir`, `cloud` (attach cloud repos for this
-session), `auth` (defaults to the request principal), `sdkAgentId`
-(resume a specific SDK agent), `state` (starting channel state for new
-sessions), `title` (session display title), `purpose` (`"eval"` skips
-sticky A/B enrollment), and `coalesceSourceTs` (dedupe key for coalesce
-queue items already delivered mid-turn).
+session), `auth` (defaults to the request principal), `state` (starting
+channel state for new sessions), `title` (session display title), and
+`purpose` (`"eval"` skips sticky A/B enrollment).
 
 ## Events
 
@@ -7644,14 +7211,12 @@ services. This is where a channel delivers replies back to its surface.
 
 `state` declares the starting per-session adapter state (JSON), persisted
 on the session record. Routes and event handlers read and mutate it
-through `channel.state`. `onStart(args)` runs when the channel mounts;
-the Slack pack opens its Socket Mode connection here. `onStop()` runs
-when the server drains.
+through `channel.state`. `onStart(args)` runs when the channel mounts.
+`onStop()` runs when the server stops.
 
 `onStart` receives the route helpers (`send`, `getSession`, `receive`,
-`callTool`, `host`, `waitUntil`, `artifacts`, and a `logger` that
-respects the server's log sink) plus a set that exists for long-lived
-transports:
+`callTool`, `host`, `waitUntil`, `artifacts`, `logger`) plus helpers
+for long-lived transports:
 
 - `emitAssistantMessage(sessionId, text)` appends an assistant message
   without a model turn, for host tasks that already produced the final
@@ -7659,8 +7224,6 @@ transports:
 - `hasContinuationSession(token)` and `isContinuationBusy(token)`
   report whether a continuation token has a live session and whether a
   turn is in flight on it.
-- `getContinuationLastBotMessageTs(token)` reads the Slack warm-delta
-  watermark from channel state.
 - `interruptContinuation(token)` stops the in-flight turn and clears
   coalesced follow-ups queued behind it.
 - `resolveApproval(sessionId, callId, decision, auth, options?)`
@@ -7714,22 +7277,17 @@ replay and live forwarding. Author `agent/channels/github.ts` with
 converge a merge-box check and sticky PR comment from default stream
 events. Guide: [GitHub](/docs/guides/github.md).
 
-**Deployments** (`@cursor/july/channels/deployments`): pull transport
-over `/v0/deployment-events`. Subscribe per deploy source with
-`deploySourceUris`, narrow with `environments` / `events`, and handle
-each event in `onEvent`. `deploySourceUris` must match
-`Deployment.deploy_source_uri` as your deployment writer records it; the
-field has no format, and matching is case-insensitive but otherwise
-literal. Each event carries `deploySourceUri` and `deployVersion`.
-Author `agent/channels/deployments.ts` with `deploymentsChannel()`. The
-serve host discovers every mounted deployments channel, runs one relay
-for the process against the union of their deploy sources, and routes
-each event to the channels that asked for it; the Slack and SCM relays
-use the same ownership. It authenticates with the host credential and
-keeps a durable offset, so a restart resumes rather than dropping
-events. An empty `deploySourceUris` list mounts the channel but starts
-no relay for it, so an env-configured agent stays inert until its
-deploy sources are set.
+**Deployments** (`@cursor/july/channels/deployments`): pull deploy
+events. Subscribe per deploy source with `deploySourceUris`, narrow
+with `environments` / `events`, and handle each event in `onEvent`.
+`deploySourceUris` must match `Deployment.deploy_source_uri` as your
+deployment writer records it; matching is case-insensitive but
+otherwise literal. Each event carries `deploySourceUri` and
+`deployVersion`. Author `agent/channels/deployments.ts` with
+`deploymentsChannel()`. It uses the host credential. A restart resumes
+rather than dropping events. An empty `deploySourceUris` list mounts
+the channel but starts no pull, so an env-configured agent stays inert
+until its deploy sources are set.
 
 For other platforms like Discord or Teams, use the authored
 `defineChannel` webhook form.
@@ -7748,7 +7306,7 @@ session; one active continuation per session; the HTTP channel returns
 Continue with these pages:
 
 - [Webhooks guide](/docs/guides/webhooks.md): the same API, walked through
-- [HTTP API](/docs/reference/http-api.md): the built-in routes precisely
+- [HTTP API](/docs/reference/http-api.md): session, discovery, and channel routes
 - [Sessions and streaming](/docs/reference/sessions.md): the events channels
   subscribe to
 
@@ -7758,14 +7316,10 @@ Source: /docs/reference/cli.md
 
 # CLI reference
 
-`@cursor/july` installs `july` (so `npx @cursor/july docs` works),
-`agent-sdk`, and the legacy `agent-serve` alias. The examples on this
-page use `agent-sdk`. Run the CLI with Node 22.13 or newer. Don't run it
-with Bun; Bun corrupts tool-result streams from the Cursor SDK.
-
-The current release still uses `.agent-serve` for on-disk state. See the
-[rename table](/docs/index.md#run-the-cli) for identifiers still moving to
-agent-sdk names.
+`@cursor/july` installs `july` (so `npx @cursor/july docs` works) and
+`agent-sdk`. The examples on this page use `agent-sdk`. Run the CLI with
+Node 22.13 or newer. Don't run it with Bun; Bun corrupts tool-result
+streams from the Cursor SDK.
 
 `agent-sdk help` prints the built-in summary. The Slack and GitHub packs
 also provide `agent-sdk slack help` and `agent-sdk github help`.
@@ -7785,7 +7339,7 @@ also provide `agent-sdk slack help` and `agent-sdk github help`.
 | [`run`](#run)                                           | Run one or more turns locally, remotely, or on a hosted agent  |
 | [`call`](#call)                                         | Call a server tool without a model turn                        |
 | [`eval`](#eval)                                         | Run filesystem evals                                           |
-| [`trajectory`](#trajectory)                             | Summarize a saved `events.ndjson` file                         |
+| [`trajectory`](#trajectory)                             | Summarize a saved event stream                                 |
 | [`init`](#init)                                         | Scaffold a project, or print the setup guide                   |
 | [`convert-automation`](#convert-automation)             | Export a Cursor Automation into an agent project               |
 | [`install-skills`](#install-skills)                     | Refresh coding-agent skills (`npm install` already copies them) |
@@ -7850,7 +7404,6 @@ agent-sdk serve [--dir <path>] [--port 3000] [--host 127.0.0.1] [--dev]
                   [--allow-anonymous-cursor-github]
                   [--allow-anonymous-cursor-account-mcp]
                   [--public-url <url>] [--cloud-tools-url <url>]
-                  [--cursor-github-proxy] [--no-control-plane]
                   [--no-schedules] [--no-playground]
                   [--no-docs] [--cursor-events --repo owner/name]...
 ```
@@ -7859,15 +7412,14 @@ If `--dir` is an agent project, it mounts under its directory name. If
 it contains agent projects, each child mounts separately. The index
 lives at `/`. Each agent is available at `/<slug>/v1/*` and
 `/<slug>/playground`. On a TTY, press Enter to restart.
-Unless `--state-root` is set, each mount uses
-`<agent-project>/.agent-serve`; slugged mounts use
-`<agent-project>/.agent-serve/<slug>`.
+Unless `--state-root` is set, each mount uses a state directory under
+the agent project. Slugged mounts get a subdirectory named for the slug.
 
 | Flag | Meaning |
 | --- | --- |
 | `--port` | Listen on this port. `0` selects an available port. The default is `3000`. When the default is taken, serve tries the next free port and prints a notice; an explicit `--port` fails with a next-port hint instead. |
 | `--host` | Bind this host. The default is loopback-only `127.0.0.1`. |
-| `--dev` | Disable automatic schedule and reminder firing, admit unsigned loopback GitHub deliveries, widen playground session access on loopback, and start Vite HMR when available. |
+| `--dev` | Disable automatic schedule and reminder firing, admit unsigned loopback GitHub deliveries, and widen playground session access on loopback. |
 | `--mode` | Use `multi` for slugged routes and an index, or `single` for one agent at the unslugged `/v1/*`. The default is `multi`. |
 | `--api-key` | Use this Cursor API key. The command falls back to `CURSOR_API_KEY`, then the stored login. |
 | `--state-root` | Store sessions, streams, workspaces, and channel state here. Keep durable production state outside the agent repository. |
@@ -7877,12 +7429,10 @@ Unless `--state-root` is set, each mount uses
 | `--allow-anonymous-cursor-account-mcp` | Allow anonymous callers to drive Cursor account MCP connectors (`defineConnection({ cursorAccount: true })`). Use only behind an authenticating proxy (hosted alias token counts). |
 | `--public-url` | Set the externally reachable host URL. Cloud-runtime peer connections need it to call back into this server. |
 | `--cloud-tools-url` | Authenticated HTTP MCP URL for this deployment's direct server-tool endpoint. Hosted deployments configure it automatically. |
-| `--cursor-github-proxy` | Route `githubChannel({ cursorAccount })` API calls through the Cursor backend's GitHub forwarder instead of minting raw installation tokens into this process. `AGENT_SERVE_GITHUB_PROXY_URL` overrides the base URL. |
-| `--no-control-plane` | Skip the bundled schedule and reminder clocks. Cursor hosting passes this so the platform fires timed work through internal routes instead. |
 | `--no-schedules` | Disable the cron runner outside dev mode. |
-| `--no-playground` | Skip the web playground and its build or HMR process. |
-| `--no-docs` | Skip the documentation site at `/docs` and its build. |
-| `--cursor-events` | Pull SCM events from Cursor's `/v0/scm-events` in addition to authored webhook routes. Requires a signed-in host. Pass repeatable `--repo owner/name` values; repos declared by `githubChannel({ cursorAccount })` also enable the relay. State lives under `<state-root>/cursor-events/`. |
+| `--no-playground` | Skip the web playground. |
+| `--no-docs` | Skip the documentation site at `/docs`. |
+| `--cursor-events` | Pull SCM events from Cursor in addition to authored webhook routes. Requires a signed-in host. Pass repeatable `--repo owner/name` values; repos declared by `githubChannel({ cursorAccount })` also enable it. |
 
 Multi-agent slugs must start with a letter or digit, then contain only
 letters, digits, `_`, or `-`. The reserved slugs are `v1`, `playground`,
@@ -7902,10 +7452,9 @@ agent-sdk dev ./sdk-pr-reviewer --port 3000
 `dev` accepts the same flags as [`serve`](#serve). You can use `--dir`
 instead of the positional path.
 Dev mode is always on: schedules and reminders wait for manual dispatch,
-GitHub accepts unsigned loopback deliveries, and Vite HMR starts when
-the toolchain is present. Prefer this over `serve --dev` while
-iterating. Pass at most one positional path. Don't combine a positional
-path with a different `--dir`.
+and GitHub accepts unsigned loopback deliveries. Prefer this over
+`serve --dev` while iterating. Pass at most one positional path. Don't
+combine a positional path with a different `--dir`.
 
 ## chat
 
@@ -8042,7 +7591,7 @@ npx @cursor/july docs
 agent-sdk docs [--port <n>] [--host 127.0.0.1] [--print]
 ```
 
-The site is the same VitePress build mounted at `/docs` on a running
+The site is the same documentation mounted at `/docs` on a running
 `serve` host. `docs` starts a loopback-only static server (default port
 is an ephemeral port) and keeps it open until Ctrl-C. `--print` prints
 the URL without opening a browser.
@@ -8078,7 +7627,7 @@ after the turns finish.
 | `--slug <slug>` | Pick one agent when local discovery mounts several agents. With `--prod`, select the hosted deployment. |
 
 The default trace path is
-`<dir>/.agent-serve/traces/<sessionId>.ndjson`. JSON output contains
+`<state-root>/traces/<sessionId>.ndjson`. JSON output contains
 `ok`, `sessionId`, `continuationToken`, `trace`, `playgroundUrl`,
 `playgroundHint`, `visualize`, and `trajectory`. The command exits
 non-zero when the trajectory fails.
@@ -8146,7 +7695,7 @@ between 1 and 200. Timeout priority is the case's `timeoutMs`, the CLI's
 | `--strict` | Exit `1` when a scored case misses a soft threshold. |
 | `--max-concurrency <n>` | Override `maxConcurrency` from `evals.config.ts`. |
 | `--junit <path>` | Write JUnit XML for CI annotations. |
-| `--artifacts <dir>` | Write run artifacts here. The default is a timestamped directory under `<dir>/.agent-serve/evals/`. |
+| `--artifacts <dir>` | Write run artifacts here. The default is a timestamped directory under `<state-root>/evals/`. |
 | `--no-artifacts` | Skip run artifacts. |
 | `--skip-report` | Ignore reporters from `evals.config.ts` and eval files. |
 | `--out <path>` | Also write the full results JSON to this path (also for `eval status <evalId>`). |
@@ -8318,10 +7867,9 @@ takes precedence over the stored login. `logout` removes the local
 credential file but doesn't revoke the API key. Revoke it in the Cursor
 dashboard when it should stop working.
 
-Non-production backends: login and account RPCs honor
-`CURSOR_API_BASE_URL` while the SDK harness honors `CURSOR_BACKEND_URL`.
-Set both to the same URL, or keys minted on one backend are rejected by
-the other.
+Login and account RPCs honor `CURSOR_API_BASE_URL`. The SDK harness
+honors `CURSOR_BACKEND_URL`. Set both to the same URL, or keys minted
+on one host are rejected by the other.
 
 ## update
 
@@ -8401,7 +7949,7 @@ state layout.
 agent-sdk deployments [--team <id>] [--json]
 ```
 
-Text output shows each slug, status, generation, deployment kind, and
+Text output shows each slug, status, deployment kind, and
 update time. `--json` prints `{ deployments }`.
 
 ## deployment
@@ -8412,7 +7960,7 @@ update time. `--json` prints `{ deployments }`.
 agent-sdk deployment <slug> [--team <id>] [--json]
 ```
 
-Text output includes status, generation, kind, alias, source, egress
+Text output includes status, kind, alias, source, egress
 domains, secret names, engine state, and the last error when present.
 `--json` returns the full API response. It can include short-lived
 `engineAccess.headers`, so handle JSON output as a credential.
@@ -8501,8 +8049,8 @@ as a credential.
 `defineConnection({ cursorAccount: true })` connection.
 
 URL connections run a browser PKCE flow. Tokens are written to
-`mcp-auth.json` under the agent-serve config dir (default
-`~/.config/agent-serve`). Pass `--store` to upsert matching
+`mcp-auth.json` under the CLI config directory (override with
+`AGENT_SERVE_CONFIG_DIR`). Pass `--store` to upsert matching
 `MCP_OAUTH_<CONNECTION>_*` secrets on the hosted deployment.
 
 Cursor-account connections authorize the hosted deployment's service
@@ -8698,9 +8246,9 @@ These environment variables affect the CLI and its channel packs.
 | Variable | Meaning |
 | --- | --- |
 | `CURSOR_API_KEY` | Cursor credential. It takes precedence over the stored login. |
-| `CURSOR_API_BASE_URL` | Backend used by login, account, deployment, and event-relay RPCs in non-production environments. |
-| `CURSOR_BACKEND_URL` | Backend used by the Cursor SDK harness in non-production environments. |
-| `AGENT_SERVE_CONFIG_DIR` | Directory for stored credentials and update-check state. The default is `~/.config/agent-serve`. |
+| `CURSOR_API_BASE_URL` | Backend used by login, account, deployment, and event-relay RPCs. |
+| `CURSOR_BACKEND_URL` | Backend used by the Cursor SDK harness. |
+| `AGENT_SERVE_CONFIG_DIR` | Directory for stored credentials and update-check state. Defaults to the CLI config directory under `~/.config`. |
 | `AGENT_SERVE_NO_UPDATE_CHECK` / `NO_UPDATE_NOTIFIER` | Disable the automatic published-version check when set to a non-empty value other than `0`. |
 | `CI` | Disable the automatic published-version check when set. |
 | `GITHUB_WEBHOOK_SECRET` | Default signing secret for GitHub forwarding and replay. |
@@ -8745,7 +8293,7 @@ Tokens come from env vars. Never hardcode them in the file.
 ## Host MCP OAuth
 
 For servers that speak OAuth, set `oauth: true` and authorize with the
-CLI. Tokens live in `~/.config/agent-serve/mcp-auth.json`. `--store`
+CLI. Tokens live in `mcp-auth.json` under the CLI config directory. `--store`
 copies them onto the hosted deployment as `MCP_OAUTH_<NAME>_*` secrets.
 
 ```ts
@@ -8773,7 +8321,7 @@ local turns, set `advertiseTools: true`.
 ## Per-session auth (`auth`)
 
 For http/sse connections whose credential depends on **who the session is
-for** — a multi-tenant agent asserting the tenant it is acting for —
+for** (a multi-tenant agent asserting the tenant it is acting for),
 declare an `auth` callback instead of static headers. It runs host-side
 at turn-build time with the session's `SessionInfo` and returns headers
 merged over the static ones:
@@ -8788,16 +8336,16 @@ export default defineConnection({
 });
 ```
 
-The callback is evaluated on **every local turn** — reminder fires and
-post-restart follow-ups included — so the identity always comes from the
+The callback is evaluated on **every local turn**, including reminder
+fires and post-restart follow-ups, so the identity always comes from the
 session itself, never from state parked in memory. The model never sees a
 tenant parameter and can never choose the tenant. A callback that throws
 fails the turn: a turn never silently runs without the connection's
 identity. Local runtime only; cloud turns are refused. `host.mcp` calls
 from server tools keep the static headers only. Not combinable with
-`oauth: true` — the host OAuth provider owns the Authorization header.
+`oauth: true`; the host OAuth provider owns the Authorization header.
 
-Derive the identity from durable session facts — `session.auth`,
+Derive the identity from durable session facts: `session.auth`,
 `session.id`, or your channel's own session state. Do **not** key it off
 `session.continuationKey`: the HTTP channel rotates the continuation key
 after every accepted follow-up, so a tenant mapping keyed on it silently
@@ -8808,14 +8356,9 @@ design are the exception.)
 per-operation clients with the evaluated headers. Attached connections
 ride the turn's SDK `mcpServers`, passed on **every send** rather than
 pinned on the cached per-session agent handle, so a rotated credential is
-live on the very next turn. The cost: when any attached connection has
-`auth`, *all* of the agent's attached connections are configured per
-send — the harness opens fresh MCP clients for them on each turn, so a
-stdio (`command`) server respawns per turn and loses any in-process
-state; keep stateful stdio servers out of agents that attach an auth'd
-connection (or advertise the auth'd connection instead). Workspace
-prewarm has no session, so it omits auth'd connections rather than
-attaching them without an identity.
+live on the very next turn. A stateful stdio server cannot share a
+process with an attached `auth` connection. Advertise the auth
+connection instead.
 
 ## Advertise a connection's tools by name (`advertiseTools`) {#advertise-tools}
 
@@ -8994,11 +8537,11 @@ Source: /docs/reference/hooks.md
 # Hooks
 
 A hook is an observe-only subscriber to the session event stream. Hooks
-run after each event is recorded and fanned out (file persistence flushes
-in the background). That makes them the home for audit logging, metrics,
-mirroring transcripts into your own store, and maintaining derived state.
-Handler errors are logged and never fatal. A hook can't modify events,
-inject context into the next turn, or block a turn.
+run after each event is recorded. They cannot change the event or the
+turn. That makes them the home for audit logging, metrics, mirroring
+transcripts into your own store, and maintaining derived state. Handler
+errors are logged and never fatal. A hook can't inject context into the
+next turn or block a turn.
 
 For deterministic context composition before the model runs, use the
 host path that already owns the wake: channel handlers (fetch, `callTool`,
@@ -9026,7 +8569,7 @@ export default defineHook({
 });
 ```
 
-Keys are event types (the full list is in the
+Keys are event types (see the
 [event vocabulary](/docs/reference/sessions.md#which-events-can-i-stream)), or `"*"`
 for everything. Handlers receive the event with its envelope (`index`,
 `sessionId`, `turnId?`, `at`) and a `HookContext`:
@@ -9072,20 +8615,16 @@ Usage metering: subscribe to `turn.completed` and forward
 Failure alerting: `turn.failed` carries the message, and
 `ctx.session.id` points at the trace.
 
-Derived state: `agent.bound` fires when the Cursor SDK agent id is known
-(`bc-…` on cloud). A PR agent can record PR → agent id from it in a
-hook with `ctx.host.kv`, so later webhook wakes resume the same cloud
-conversation. Prefer `ctx.host.kv` or `ctx.host.files` for ids that
-must survive hosted replace. `stateRoot` resets on replace.
+Derived state: persist ids that must survive hosted replace with
+`ctx.host.kv` or `ctx.host.files`. `stateRoot` resets on replace.
 
-Transcript export: subscribe to `"*"` and append to your own store. The
-NDJSON envelope is already ordered and replayable.
+Transcript export: subscribe to `"*"` and append to your own store.
 
 ## What's next
 
 Continue with these pages:
 
-- [Sessions and streaming](/docs/reference/sessions.md): every event a hook can see
+- [Sessions and streaming](/docs/reference/sessions.md): the event vocabulary hooks observe
 - [OpenTelemetry](/docs/guides/opentelemetry.md): OTLP traces and metrics
   from the same event stream
 - [Deployment](/docs/deployment.md#observability): runtime logs and export
@@ -9100,7 +8639,7 @@ Source: /docs/reference/http-api.md
 
 # HTTP API reference
 
-Every Agent SDK host speaks the same stable HTTP API. In the default
+Agent SDK hosts expose the same public HTTP surface. In the default
 multi-agent layout each agent is namespaced under its slug
 (`/<slug>/v1/session`, `/<slug>/playground`), with host-level routes at
 the root. With `--mode single`, one agent serves the same surface
@@ -9125,8 +8664,7 @@ both layouts and removed by `--no-docs`.
 | `GET /`                    | A web index of every mounted agent, linking to playgrounds (playground only)                                                 |
 | `GET /v1/agents`           | The JSON index of mounted agents (playground only, no auth)                                                                  |
 | `GET /docs`, `GET /docs/*` | This documentation, served as a static site (both layouts, no auth)                                                          |
-| `GET /v1/health`           | Host-level liveness, no auth; made for ALB/ECS checks                                                                        |
-| `POST /v1/webhooks/github` | Loopback-only trigger endpoint that fans a GitHub-shaped payload out to every mounted GitHub channel (used by local tooling) |
+| `GET /v1/health`           | Host-level liveness, no auth                                                                                                 |
 
 ## Start a session
 
@@ -9234,17 +8772,16 @@ while a turn runs). Agent-execution tools are rejected with `400`, and
 unknown tools with `404` and the list of available names. For the
 semantics, see [Tools](/docs/reference/tools.md#call-a-tool-without-a-model-turn).
 
-## Discovery and meta
+## Discovery
 
-Five read-only routes describe the running agent.
+These read-only routes describe the running agent.
 
 | Route                  | What it does                                                                                                                                                                             |
 | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `GET /v1/info`         | The manifest snapshot: model, tools, skills, MCP connections, subagents, channels and routes (with schemas), schedules, hooks, A/B experiments, diagnostics. Always the bare project-info object; `agent-sdk info --json` wraps the same data per slug in `{ agents: [...] }` |
+| `GET /v1/info`         | The discovered surface: model, tools, skills, MCP connections, subagents, channels and routes (with schemas), schedules, hooks, A/B experiments, diagnostics |
 | `GET /v1/health`       | Per-agent liveness, no auth                                                                                                                                                              |
-| `GET /v1/meta`         | SPA bootstrap: agent name, dev flag, base path (no auth)                                                                                                                                 |
-| `GET /v1/logs?after=N` | Recent server log lines from the ring buffer, with a polling cursor                                                                                                                      |
-| `GET /v1/abs`          | [Live A/B metrics](/docs/ab.md): per-session assignments and aggregate arm totals folded from durable event streams (`config` reports `maxPlaygroundSessions` / `durableSamples` / `durableSnapshots` from `agent/ab.config.ts`) |
+| `GET /v1/logs?after=N` | Recent server log lines, with a polling cursor                                                                                                                                           |
+| `GET /v1/abs`          | [Live A/B metrics](/docs/ab.md): per-session assignments and aggregate arm totals                                                                                                           |
 
 ## Artifacts
 
@@ -9286,20 +8823,14 @@ it through the URL configured by `serve --cloud-tools-url`. Unlike
 `/v1/mcp`, it runs the CLI-level auth chain (loopback, bearer, or
 anonymous), not any authored channel auth.
 
-`POST /v1/cursor-account/:connection/mcp` is the bridge for
-`defineConnection({ cursorAccount: true })` connections. The runtime
-calls it with a per-boot bearer secret; it never joins the public auth
-chain, and an unknown connection name returns `404`.
-
 ## Playground eval routes
 
-Always registered (including production / non-`--dev` serves). The playground
-Evals tab uses these:
+The playground Evals tab and `agent-sdk eval --prod` / `--url` use these:
 
 | Route                           | What it does                                                                                               |
 | ------------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `GET /v1/dev/evals`             | List discovered eval datapoints and project config as `{ evals, config }` (`config` includes `maxPlaygroundRuns`, `durableRuns`) |
-| `GET /v1/dev/evals/runs`        | List recent run snapshots (newest first) as `{ runs, activeRunId? }` for playground rehydrate              |
+| `GET /v1/dev/evals`             | List discovered eval datapoints and project config                                                         |
+| `GET /v1/dev/evals/runs`        | List recent run snapshots, newest first                                                                    |
 | `POST /v1/dev/evals/runs`       | Start an eval run (`{filterIds?, tags?}`); `202` with a snapshot (`runId` is the Eval ID), `404` when nothing matches, `409` when one is running |
 | `GET /v1/dev/evals/runs/:runId` | Poll a run's progress                                                                                      |
 | `POST /v1/dev/evals/runs/:runId/cancel` | Cancel a running batch; `200` with snapshot, `404` unknown, `409` when not running |
@@ -9308,10 +8839,9 @@ Eval runs are asynchronous. Poll the run route for case progress and
 the final `completed` or `failed` status. Batch errors appear on the
 snapshot returned by the poll. Entries within `filterIds` and `tags`
 use OR semantics. When both fields are present, a case must match one
-entry from each field. Listed runs persist across restarts whenever
-`agent/storage.ts` provides an `evals` table or a KV core with `delete`
-and `list` (the table is derived — see [Storage](/docs/storage.md));
-otherwise they are process-memory only (capped by `maxPlaygroundRuns`).
+entry from each field. Listed runs persist across restarts when storage is configured; see
+[Storage](/docs/storage.md#eval-and-a-b-tables). Otherwise they are
+process-memory only.
 
 ## Dev-mode routes
 
@@ -9319,29 +8849,18 @@ These routes exist only under `serve --dev`.
 
 | Route                                | What it does                                                                                               |
 | ------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
-| `POST /v1/dev/schedules/:scheduleId` | Dispatch a schedule by hand, exactly once, through the production path. Returns `{scheduleId, sessionIds}` |
+| `POST /v1/dev/schedules/:scheduleId` | Dispatch a schedule by hand, exactly once. Returns `{scheduleId, sessionIds}` |
 | `GET /v1/dev/reminders`              | List reminders                                                                                             |
 | `POST /v1/dev/reminders/:reminderId` | Fire a reminder by hand                                                                                    |
 
 Schedules and reminders never fire automatically in dev mode. These
 routes are the only way they run, which keeps iteration deterministic.
 
-## Platform timer routes
-
-`POST /v1/internal/schedules/:scheduleId/fire` and
-`POST /v1/internal/reminders/:reminderId/fire` exist only under
-`serve --no-control-plane`, where the host runs no schedule or reminder
-clocks of its own. Cursor hosting starts engines this way and fires
-timed work through them. They admit only requests carrying the
-platform's `x-agent-serve-timed-work` marker, which the alias proxy
-strips from external traffic, so webhook and playground callers can
-never reach them.
-
 ## Playground assets
 
-`GET /playground` and `GET /playground/assets/:file` serve the static
-SPA bundle (omitted with `--no-playground`). The playground calls the
-JSON API above and has no privileged surface.
+`GET /playground` and `GET /playground/assets/:file` serve the
+playground (omitted with `--no-playground`). It calls the JSON API
+above and has no privileged surface.
 
 ## Status codes
 
@@ -9407,7 +8926,7 @@ may also load ambient `AGENTS.md` and `.cursor` config from ancestor
 directories. [Agent config → Local cwd](/docs/reference/agent-config.md#local-cwd)
 covers controlling that.
 
-## Best Practices
+## What to put in instructions
 
 Keep them a few lines: identity, when to use which tool, output shape.
 The [quickstart PR approver](/docs/quickstart.md) is the pattern:
@@ -9453,40 +8972,35 @@ Source: /docs/reference/playground.md
 
 Every served agent ships with a web playground at
 `http://127.0.0.1:3000/<slug>/playground` (or `/playground` in single
-mode): a static SPA over the same public HTTP API, made for manual
-testing, demos, and reading sessions. Every call it makes runs the
-normal route auth chain, so anything you can do in the playground you
-can also do with curl.
+mode). Anything you can do there you can also do with curl.
 
 ## What it does
 
-The playground covers the whole manual-testing loop.
+Use the playground to chat, try channel routes, and inspect sessions.
 
-- **Chat** with the agent. Text and reasoning stream live, rendered as
-  markdown with syntax highlighting, and tool calls appear inline with
-  their arguments, output, and error state as the `actions.requested` /
-  `action.result` events arrive.
+- **Chat** with the agent. Text and reasoning stream live, and tool
+  calls appear inline with their arguments, output, and error state.
 - **Slash commands**: custom channel routes become composer commands
-  (a `drive` route becomes `/drive <pr-url>`), derived from the schemas
-  on `GET /v1/info`, with `/help` and autocomplete.
+  (a `drive` route becomes `/drive <pr-url>`), with `/help` and
+  autocomplete.
 - **Try** any channel route from the Agent surface. The modal remembers
   your last body per endpoint and has Copy curl, and a successful Try
   opens the created session.
-- **Sessions**: browse every session (chat, custom-channel, schedule
-  tasks) and replay their durable event streams. Search by session ID
-  to filter the list, or press Enter to open an ID directly. "Open
-  trace" renders any `events.ndjson` file.
+- **Sessions**: browse the sessions you own (chat, custom-channel,
+  schedule tasks) and replay their event streams. In `--dev` on
+  loopback, or with `--allow-anonymous`, the list includes every
+  principal. Search by session ID to filter the list, or press Enter
+  to open an ID directly. "Open trace" renders a saved event stream.
 - **Approvals**: parked `needsApproval` tool calls render Approve /
   Deny buttons.
 - **Evals**: list and run filesystem evals from the browser (backed by
   `/v1/dev/evals`). Schedule hand-dispatch still requires `--dev`.
 - **The surface**: inspect the discovered tools, skills, subagents, MCP
   connections, channels, and hooks.
-- **Raw NDJSON pane**: flip it on to see the exact wire events.
+- **Raw events pane**: flip it on to inspect the event stream.
 - **Logs tab**: recent server log lines, polled from `GET /v1/logs`.
 - **A/Bs tab**: per-session and aggregate
-  [live A/B metrics](/docs/ab.md) from `GET /v1/abs` (folds durable
-  `ab.assigned` plus turn and tool events; no separate store).
+  [live A/B metrics](/docs/ab.md) from `GET /v1/abs`.
 
 In multi-agent mode each agent has its own playground at
 `/<slug>/playground`, and `/` is an index of them all.
@@ -9505,7 +9019,7 @@ demo-only alternative for trusted networks.
 
 Continue with these pages:
 
-- [HTTP API](/docs/reference/http-api.md): everything the playground calls
+- [HTTP API](/docs/reference/http-api.md): the HTTP surface the playground uses
 - [Sessions and streaming](/docs/reference/sessions.md): the streams it renders
 - [Human-in-the-loop](/docs/guides/human-in-the-loop.md): the approval
   buttons in context
@@ -9589,7 +9103,7 @@ Each path maps to a capability and a reference page.
 | `agent/artifacts.ts` | `defineArtifacts` kinds, the `tag_artifact` opt-in, and retention | [Artifacts](/docs/reference/artifacts.md) |
 | `agent/schedules/*` | Cron-driven runs (UTC, 5-field; never auto-fire under `--dev`) | [Schedules](/docs/reference/schedules.md) |
 | `agent/sandbox/workspace/**` | Seed files copied into each local session workspace | [Sessions](/docs/reference/sessions.md#what-goes-into-a-local-session-workspace) |
-| `agent/playground/` | Custom playground tool chips for the Vite dev playground | [Playground](/docs/reference/playground.md) |
+| `agent/playground/` | Custom playground tool chips | [Playground](/docs/reference/playground.md) |
 | `agent/lib/` | Import-only shared code, never discovered | None |
 | `evals/evals.config.ts` | Shared eval settings (e.g. `maxConcurrency`); required when evals exist | [Evals](/docs/evals.md) |
 | `evals/**/*.eval.ts` | Filesystem evals; case id = path under `evals/` | [Evals](/docs/evals.md) |
@@ -9611,7 +9125,7 @@ or has the wrong extension.
 ```bash
 agent-sdk validate --dir .    # diagnostics; non-zero exit on errors
 agent-sdk info --dir .        # human-readable surface
-agent-sdk info --dir . --json # machine-readable manifest (same shape as GET /v1/info)
+agent-sdk info --dir . --json # machine-readable project info (same shape as GET /v1/info)
 ```
 
 ## What's next
@@ -9660,7 +9174,7 @@ those lines the same indent as the `prompt` body so dedent stays consistent.
 
 ## `prompt.lines\`…\``
 
-Same dedent rules, but returns `string[]` — one entry per line. Use this
+Same dedent rules, but returns `string[]`, one entry per line. Use this
 where an API wants separate lines (for example GitHub channel `context`):
 
 ```ts
@@ -9854,8 +9368,7 @@ in-memory, so after a restart those reminders are disarmed
 (`handler_lost_on_restart`); re-arm them from the code path that created
 them, or prefer the prompt form.
 
-Dev mode matches schedules. Auto-timers follow `ServeOptions.reminders`
-(default `!dev`), so in `--dev` fire by hand:
+`--dev` does not auto-fire reminders. Dispatch one by hand:
 
 ```bash
 curl http://127.0.0.1:3000/<slug>/v1/dev/reminders             # list
@@ -9971,7 +9484,7 @@ within one session. The `at` field is an ISO-8601 timestamp.
 | Phase | Events | What they tell you |
 | --- | --- | --- |
 | Session | `session.started`, [`ab.assigned`](/docs/ab.md#assign-sticky-variants), `session.waiting`, `session.completed`, `session.failed` | Session creation, A/B enrollment, readiness, and task completion |
-| Agent | `agent.bound` | Cursor SDK agent ID and cloud conversation URL |
+| Agent | `agent.bound` | Cloud conversation URL |
 | Input | `message.received` | A user message was accepted |
 | Turn | `turn.queued`, `turn.started`, `turn.completed`, `turn.failed` | Queue position under a [`maxRunningTurns` cap](/docs/reference/agent-config.md#concurrency), then turn status, final result, and token usage |
 | Steps | `step.started`, `step.completed` | Model step boundaries and duration |
@@ -10010,7 +9523,7 @@ The Agent SDK creates a workspace before the first local turn:
 | ---------------------------------- | ----------------------------------------------------------------------- |
 | `instructions.*`                   | `AGENTS.md`                                                             |
 | `skills/*`                         | `.cursor/skills/<name>/SKILL.md`                                        |
-| agent tools (`execution: "agent"`) | scripts under `.agent-serve/tools/`, with a catalog in `AGENTS.md` |
+| agent tools (`execution: "agent"`) | scripts in the session workspace, with a catalog in `AGENTS.md` |
 | `sandbox/workspace/**`             | copied in as seed files                                                 |
 | per-send `workspaceFiles`          | written before the turn                                                 |
 
@@ -10025,34 +9538,23 @@ inheritance rules.
 
 ## Where does the Agent SDK store session data?
 
-Local state uses one directory tree:
-
-```text
-<project>/.agent-serve/           # or <stateRoot>/<slug>/ under serve
-  sessions/<id>/session.json       # metadata: channel, mode, principal, tokens
-  sessions/<id>/events.ndjson      # the durable stream
-  sessions/<id>/workspace/         # the harness cwd
-  traces/<sessionId>.ndjson        # written by `run`
-  runner/                          # Cursor SDK conversation store
-  tool-calls/<callId>/             # ephemeral deterministic-call workspaces
-```
+Local state lives under `--state-root`. Slugged mounts store it under
+a subdirectory named for the slug.
 
 Deleting a session directory removes the session from the server: it
 disappears from listings and can no longer be streamed or continued.
-The `runner/` store keeps its own conversation copy until you remove it.
 Cloud conversations remain on the Cursor backend.
 
-Change the root with `--state-root` or `stateRoot`. Nested git checkouts
-already default `local.cwd` outside the enclosing repo. See
+Nested git checkouts already default `local.cwd` outside the enclosing
+repo. See
 [local session workspaces](/docs/concepts.md#what-files-can-a-local-session-access).
 
 ## How do I inspect a saved event stream?
 
-Use `trajectory` with a trace or session event file:
+Use `trajectory` with a saved trace:
 
 ```bash
-agent-sdk trajectory --events .agent-serve/traces/<sessionId>.ndjson
-agent-sdk trajectory --events <stateRoot>/<slug>/sessions/<id>/events.ndjson
+agent-sdk trajectory --events <state-root>/traces/<sessionId>.ndjson
 ```
 
 The command prints tool calls, the reply, and token usage in the same
@@ -10124,9 +9626,9 @@ the engine copies the same SKILL.md tree onto an Agent Store for native
 discovery:
 
 - Hosted deployments write store-root `skills/<name>/`.
-- `agent-serve serve` / `run` with a personal `CURSOR_API_KEY` write
-  `agent-serve/<agent>/skills/<name>/` on the USER store, namespaced so
-  they cannot collide with the user's own skills.
+- `agent-sdk serve` / `run` with a personal `CURSOR_API_KEY` write
+  namespaced skills on the USER store so they cannot collide with the
+  user's own skills.
 
 `validate` still warns about the combination so the store path is
 visible. Cloud turns with neither a hosted store nor an API key see
@@ -10295,7 +9797,7 @@ export default defineTool({
 });
 ```
 
-### The `ctx` parameter
+### Tool context
 
 `execute` receives a `ctx` with the runtime accessors:
 
@@ -10307,7 +9809,7 @@ export default defineTool({
 | `ctx.stateRoot` | The agent's durable state root, shared across every session |
 | `ctx.host` | Shared host services (see below) |
 | `ctx.send(channelId, message, options?)` | Start or resume a session on any channel: the cross-channel handoff primitive, e.g. a chat tool opening a `drive` cloud session for a PR. `auth` defaults to this call's session principal |
-| `ctx.getSession(channelId, sessionId)` | Look up a session on a channel, e.g. refresh `sdkAgentId` after a turn |
+| `ctx.getSession(channelId, sessionId)` | Look up a session on a channel |
 | `ctx.artifacts` | Session-bound [artifacts](/docs/reference/artifacts.md) facade: `tag` auto-fills the session |
 
 `ctx.host` carries the shared host services: `host.mcp` (authored MCP
@@ -10315,9 +9817,7 @@ connections: `names()`, `listTools(name)`, `callTool(name, tool, args)`),
 `host.github` and `host.slack` (shared platform clients), `host.kv` and
 `host.files` (durable [storage](/docs/storage.md)), `host.otel` (custom
 metrics and session tags; see [OpenTelemetry](/docs/guides/opentelemetry.md)),
-`host.reminders` (per-session wakes, when attached), `host.evals`
-(playground eval batches, when attached), and `host.slackNudges`
-(Slack ask-dedupe helpers).
+`host.reminders` (per-session wakes, when attached).
 
 ### Return values
 
@@ -10405,15 +9905,15 @@ printf '%s\\n' "$message"
 });
 ```
 
-On the local runtime, scripts land under `.agent-serve/tools/` in the
-session workspace with a catalog in `AGENTS.md`. On cloud, the catalog
-and script bodies travel on the first prompt.
+On the local runtime, scripts land in the session workspace with a
+catalog in `AGENTS.md`. On cloud, the catalog and script bodies travel
+on the first prompt.
 
 ## Tools from an MCP connection, advertised by name
 
 Authored `agent/tools/` files are one catalog for every session. When
-the tools should come from an MCP server — including per-tenant toolsets
-resolved at runtime — declare the connection with
+the tools should come from an MCP server, including per-tenant toolsets
+resolved at runtime, declare the connection with
 `advertiseTools: true` (plus per-session `auth` when the credential
 depends on who the session is for) and the engine synthesizes named 1:1
 passthrough server tools from the connection's live `listTools` on every
@@ -10490,15 +9990,12 @@ const outcome = await handle.callTool("inspect_pr", {
 // { toolName, callId, isError, result, durationMs }
 ```
 
-By default the call runs against an ephemeral scratch workspace under
-`<stateRoot>/tool-calls/<callId>`, materialized like a session workspace
-and removed when the call returns. Pass a `sessionId` (a body field over
+By default the call runs against an ephemeral workspace and is removed
+when the call returns. Pass a `sessionId` (a body field over
 HTTP, `--session` on the CLI, `options.sessionId` programmatically) to
 run inside an existing session instead: the tool sees that session's
-workspace, and the call is recorded on the session's event stream under
-a per-call `turnId`, visible in the playground and trajectories like
-any model-initiated call. Session-bound calls serialize with model
-turns and return `409 session_busy` while a turn runs.
+workspace, and the call is recorded on the session's event stream.
+Session-bound calls return `409 session_busy` while a turn runs.
 
 The error semantics match the model path. Unknown tools are rejected
 with the available names, agent-execution tools cannot be called on the
@@ -10556,12 +10053,11 @@ Where to find the file depends on how you got the package:
   injects the skill body into context instead of waiting for the
   model to pick it from the catalog. The `/` menu lists them as
   `/agentsdk-create-agent`, `/agentsdk-hillclimb`, and the rest. Re-installing overwrites those
-  copies with the package version. Set
-  `CURSOR_JULY_SKIP_SKILL_INSTALL=1` to skip the copy.
+  copies with the package version.
 - Installed `@cursor/july` as a dependency? The skill also ships inside
   the package at `node_modules/@cursor/july/skills/create-agent/SKILL.md`.
-- Working in the monorepo? It's at
-  `packages/agent-serve/skills/create-agent/SKILL.md`. Run
+- Working from this package's source? The skill is at
+  [`skills/create-agent/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/create-agent/SKILL.md). Run
   `agent-sdk install-skills` if you want the same copies in
   `~/.cursor/skills/agentsdk/` (the package postinstall skips the
   source checkout).
@@ -10661,7 +10157,7 @@ inputs again, and adds an eval for each improvement you keep.
 
 ## Related
 
-- [Build your first PR approver](/docs/quickstart.md)
+- [Build your first PR reviewer](/docs/quickstart.md)
 - [Convert a Cursor Automation](/docs/guides/convert-automation.md)
 - [Building agents with agents](/docs/building-with-agents.md)
 - [Evals](/docs/evals.md)
@@ -10676,15 +10172,10 @@ Source: /docs/storage.md
 
 The Agent SDK owns durable storage for sessions, continuation tokens,
 reminders, playground eval history, and live A/B samples. It chooses the
-keys (under `agentkit/v1/`), when to read and write, and how to restore
-after restart.
+keys, when to read and write, and how to restore after restart.
 
-Keys have bounded length: caller-controlled segments (channel ids,
-continuation tokens) are URI-encoded, and any segment past 256 encoded
-bytes is replaced by its `sha256:…` digest — deterministically, so writes
-and lookups always agree. Backends can rely on this instead of imposing
-their own key-length caps (which would silently drop writes, since a
-throwing `put` is at-most-once).
+The Agent SDK owns key encoding. Backends must accept the keys they are
+given. Do not fail `put` to enforce a shorter cap.
 
 By default that storage lives under `--state-root` on local disk. Fine
 for one machine; it does not survive replacing the host.
@@ -10692,8 +10183,7 @@ for one machine; it does not survive replacing the host.
 To keep the same framework storage across hosts, plug in a key-value
 backend with `agent/storage.ts`. You provide `put` / `get` / `delete` /
 `list`. The optional `cas` group adds conditional writes (see
-[Conditional writes](#conditional-writes-the-cas-group)). The Agent SDK
-does the rest.
+[Conditional writes](#conditional-writes-the-cas-group)).
 
 ```ts
 // agent/storage.ts
@@ -10713,15 +10203,10 @@ export default defineStorage({
 });
 ```
 
-> [!NOTE]
-> Import paths here use `@cursor/july/storage`. On projects still
-> using `@anysphere/agent-serve`, swap the import. See
-> [Run the CLI](/docs/index.md#run-the-cli) for the full rename table.
-
 ## Which fields to provide
 
-Implement the small KV core — `put`/`get`/`delete`/`list` plus the `cas`
-group — and you get **full functionality**: eval-run and A/B history are
+Implement the small KV core (`put`/`get`/`delete`/`list` plus the `cas`
+group) and you get **full functionality**: eval-run and A/B history are
 derived over the core automatically. The dedicated `evals` / `abs` groups
 are backend-native optimizations, not required-or-lose-history hooks.
 
@@ -10729,13 +10214,13 @@ are backend-native optimizations, not required-or-lose-history hooks.
 | --- | --- | --- |
 | `put` | Yes | Write or update a value |
 | `cas` | Optional | Conditional writes; see [Conditional writes](#conditional-writes-the-cas-group) |
-| `get` | For restore | Look up one key (also: derived A/B snapshot backfill) |
-| `list` | For restore | Return entries under a prefix, in key order (also: derived eval-runs hydrate) |
-| `delete` | For cleanup | Remove a key (also: derived eval-runs pruning) |
+| `get` | For restore | Look up one key |
+| `list` | For restore | Return entries under a prefix, in key order |
+| `delete` | For cleanup | Remove a key |
 | `name` | No | Label surfaced on `GET /v1/info` diagnostics |
 | `policy` | No | Timing knobs; see [Policy](#policy) |
-| `evals` | No | Backend-native eval-runs table; derived over the core when omitted — see [Eval and A/B tables](#eval-and-a-b-tables) |
-| `abs` | No | Backend-native A/B metrics table; derived over the core when omitted — see [Eval and A/B tables](#eval-and-a-b-tables) |
+| `evals` | No | Backend-native eval-runs table; derived over the core when omitted. See [Eval and A/B tables](#eval-and-a-b-tables) |
+| `abs` | No | Backend-native A/B metrics table; derived over the core when omitted. See [Eval and A/B tables](#eval-and-a-b-tables) |
 
 A throwing `put` is logged and dropped. It never fails a turn. When
 resolving a missing continuation token, a throwing `get` fails the
@@ -10749,30 +10234,20 @@ values. Both are **optional optimizations**: when a group is not
 authored, `defineStorage` derives it over the KV core, so a backend that
 implements only the core loses nothing. Author a group only when the
 backend has a better native shape (a real database table, an analytics
-pipeline) — the built-in `fileKv` and `cursorHostedStorage` both do.
+pipeline). The built-in `fileKv` and `cursorHostedStorage` both do.
 
 `evals` keeps playground eval batches across restarts (`put`, `delete`,
-`list` over run snapshots keyed by `runId`). The Agent SDK upserts a
-snapshot as a batch starts, progresses, and finishes, prunes runs past
-the playground history window, and lists everything back at serve start.
-**Derived form**: one key per run under
-`agentkit/v1/{agent}/eval-runs/{runId}` — needs core `put` + `delete` +
-`list`. Only a core missing `delete` or `list` leaves eval history in
-process memory (cleared on restart). See
-[Evals](/docs/evals.md#configure-eval-runs).
+`list` over run snapshots keyed by `runId`). A core missing `delete` or
+`list` leaves eval history in memory until restart.
+See [Evals](/docs/evals.md#configure-eval-runs).
 
 `abs` exports live A/B metrics: `putSample` appends one cumulative
 metric sample per enrolled experiment on each completed or failed turn;
 optional `putSnapshot` / `getSnapshot` store and serve back the latest
-aggregate so a replacement host with no local sessions can still serve
-the A/Bs surface. **Derived form**: each sample lands as its own key
-(`agentkit/v1/{agent}/ab-samples/{experiment}/{sessionId}/{at}` — a
-blind append-only put, never a read-modify-write of one growing array)
-and the snapshot lives at the fixed `agentkit/v1/{agent}/ab-snapshot`
-key (last-write-wins is correct for "latest aggregate"). `putSample` and
-`putSnapshot` need only core `put`; `getSnapshot` needs core `get`.
-Session event logs remain the assignment source of truth either way. See
-[Live A/B metrics](/docs/ab.md).
+aggregate so a replacement host can still serve the A/Bs surface.
+`putSample` and `putSnapshot` need only core `put`; `getSnapshot` needs
+core `get`. Session event logs remain the assignment source of truth
+either way. See [Live A/B metrics](/docs/ab.md).
 
 ## Policy
 
@@ -10806,8 +10281,6 @@ follow-up arrives instead of at startup.
 With `get` and `list`, serve can rebuild local state from your store:
 
 - At startup, the Agent SDK loads recent sessions up to the restore caps.
-  Local disk wins when both sides have the same session. Reminders
-  hydrate the same way into `--state-root/reminders`.
 - On demand, a missing continuation token resolves through the store
   and resumes that session.
 - Playground eval history and A/B aggregates can load from the same
@@ -10826,19 +10299,16 @@ await ctx.host.kv.put("alert-memory/abc", { updated: "…" });
 const prior = await ctx.host.kv.get("alert-memory/abc");
 ```
 
-The Agent SDK prefixes author keys as `agentkit/v1/{agent}/kv/{key}` (same
-bounded encoding as continuation tokens). Writes **await** the sink and
-propagate errors — unlike session mirrors, which are at-most-once.
+Writes **await** the sink and propagate errors, unlike session mirrors,
+which are at-most-once.
 
-Without `agent/storage.ts`, `host.kv` falls back to files under
-`--state-root/kv`. That is fine for local dogfood; it does **not**
-survive replacing the host. For Cursor-managed hosting, prefer
-`@cursor/july/storage/cursor-hosted` so sessions and author KV share the
-platform Bugbot tables through a control-plane HTTP proxy (authenticated
-as the deployment pod credential — engines never receive a database URL).
+Without `agent/storage.ts`, `host.kv` is local-only and does not
+survive replacing the host. Hosted agents should author
+`cursorHostedStorage()` so session and `host.kv` records survive
+replace.
 
 ```ts
-// agent/storage.ts — Cursor-managed hosting
+// agent/storage.ts: Cursor-managed hosting
 import { defineStorage } from "@cursor/july/storage";
 import { cursorHostedStorage } from "@cursor/july/storage/cursor-hosted";
 
@@ -10851,32 +10321,18 @@ Built-in helpers:
 
 | Import | Backend |
 | --- | --- |
-| `@cursor/july/storage/file-kv` | File-per-key under `.agent-serve/kv` |
-| `@cursor/july/storage/cursor-hosted` | Platform Bugbot `agent_serve_*` via control-plane proxy |
+| `@cursor/july/storage/file-kv` | File-per-key under the project state directory |
+| `@cursor/july/storage/cursor-hosted` | Cursor-managed hosting; records survive replace |
 
 ## Bring your own backend
 
-There is no built-in Postgres backend on purpose. Cursor's internal
-`agent_serve_*` tables are owned by the backend and reachable only
-through the hosted proxy, and this doc does not prescribe a schema —
-what you back the KV with is your call. Any durable store works:
-
-- **Local disk** — the built-in `fileKv` (single process only).
-- **Object storage (S3-class)** — one object per key; conditional
-  writes map directly onto the contract (`putIfAbsent` = put with
-  `If-None-Match: *`, `putIfVersion` = put with `If-Match: <etag>`,
-  the ETag is the version token, `listKeys` is a prefix listing).
-- **Redis, DynamoDB, a SQL table, …** — anything that can do an
-  atomic compare-and-set and a prefix listing.
-
-Implement the `StorageConfig` methods (and the optional `cas` group)
-against that store. The
-contract, defined at `@cursor/july/kv`: version tokens are opaque
-strings that change on every successful write — including plain
-`put`, so a stale token fences instead of clobbering; conditional
-writes are atomic; `listKeys` returns every key under the prefix.
-`@cursor/july/kv/memory` is a complete reference implementation to
-compare behavior against.
+Any durable store works if it can put, get, delete, list by prefix,
+and optionally compare-and-set. Implement the `StorageConfig` methods
+(and the optional `cas` group) against that store. The contract,
+defined at `@cursor/july/kv`: version tokens are opaque strings that
+change on every successful write, including plain `put`, so a stale
+token fences instead of clobbering; conditional writes are atomic;
+`listKeys` returns every key under the prefix.
 
 ## Conditional writes (the `cas` group)
 
@@ -10884,13 +10340,10 @@ The `cas` group is compare-and-swap over the same keyspace:
 `getWithVersion` / `putIfAbsent` / `putIfVersion` / `listKeys`, defined
 backend-agnostically at `@cursor/july/kv`. Plain storage works without
 it, so an existing backend keeps working across a platform upgrade.
-`defineStorage` rejects a partial group — implement all four methods or
+`defineStorage` rejects a partial group. Implement all four methods or
 none. Version tokens are opaque strings that must change on every write
 (a counter column, a row version, a content hash). The built-in backends
-both include it: `fileKv` uses content-hash tokens (single-process
-correctness) and `cursorHostedStorage` the control-plane proxy (a
-`version` counter on the server). `memoryCasTable()` is for test fixtures
-and inert sinks only.
+both include the group.
 
 ---
 
@@ -10925,7 +10378,7 @@ agent-sdk login
 agent-sdk dev
 ```
 
-PR events stream through your Cursor account — no webhook or GitHub App
+PR events stream through your Cursor account. No webhook or GitHub App
 setup. Open a PR, or replay a real one deterministically (this also works
 with `repos` empty):
 
@@ -10968,7 +10421,7 @@ applies the deterministic decision:
 
 - **Approve** when the tier is low and no matched rule demands a human,
   bound to the head SHA.
-- **Request reviewers** otherwise — the policy owners (max 2, never the
+- **Request reviewers** otherwise: the policy owners (max 2, never the
   author), plus one status comment the agent keeps updated in place.
 
 The model never writes to GitHub. A broken policy file fails closed with
@@ -11165,12 +10618,9 @@ opted-in PR wakes the agent. A comment on a plain GitHub issue does
 not. The channel buffers about 3 seconds per PR. Payload details are
 dropped on purpose. The follow-up says something changed.
 
-Pending wakes snapshot to `host.kv` (`webhook-buffer`) before the
-webhook is ACKed, and restore on restart. Affinity is
-`affinity/{owner/repo#N}` → `bc-…` in the same store, written from
-`agent.bound`. `agent/storage.ts` uses `cursorHostedStorage`, so both
-survive host replace. Local serve without that plug-in falls back to
-`--state-root/kv`.
+Pending wakes and the PR-to-cloud-agent map persist in `host.kv` so
+they survive restart. `cursorHostedStorage` keeps both across replace.
+Without that plug-in, `host.kv` is local-only.
 
 Closing a PR cancels its merge-conflict reminder and drops buffered
 wakes.
@@ -11414,8 +10864,8 @@ Start with four checks, in order:
 3. What the playground or HTTP API shows
 4. The session event stream (trace)
 
-Match your symptom below. Keep the commands as `agent-sdk`; see
-[Run the CLI](/docs/index.md#run-the-cli) if you still need an alias.
+Match your symptom below. Keep the commands as `agent-sdk`. If it is
+not on `PATH`, use `npx @cursor/july`.
 
 ## What if serve or the playground looks wrong?
 
@@ -11423,9 +10873,9 @@ Match your symptom below. Keep the commands as `agent-sdk`; see
 | --- | --- |
 | `serve` won't start | Run `agent-sdk validate --dir .` and fix the reported errors. |
 | Playground is blank or says there are no agents | The UI needs a running `serve` process. Building the playground assets alone is not enough. |
-| Edits to the playground don't show up | Use `serve --dev` and open the printed playground HMR URL (often port `5273`), not only the static `:3000` URL. |
-| Sessions exist on disk but the playground list is empty | The list shows sessions for the authenticated caller. In `--dev` on loopback the list is wider. Otherwise open `/<slug>/playground?sessionId=ses_…` or inspect `sessions/` under your state root. |
-| Port 3000 or 5273 is already in use | For the default serve port, the CLI tries the next free port and prints a notice. Pass `--port` to pick one, or `--port 0` for any free port. Stop leftover Vite or webhook-forwarder processes if you need the original port. |
+| The playground UI looks stale | `serve --dev` prints a playground URL. Open that URL. Agent-file edits still need a restart (press Enter on the TTY). |
+| Sessions exist but the playground list is empty | The list shows sessions for the authenticated caller. In `--dev` on loopback the list is wider. Otherwise open `/<slug>/playground?sessionId=ses_…`. |
+| Port 3000 is already in use | For the default serve port, the CLI tries the next free port and prints a notice. Pass `--port` to pick one, or `--port 0` for any free port. Stop leftover playground or webhook-forwarder processes if you need the original port. |
 
 ## What if a model turn goes wrong?
 
@@ -11433,7 +10883,7 @@ Match your symptom below. Keep the commands as `agent-sdk`; see
 | --- | --- |
 | Built-in file reads and greps fail; the turn retries for a long time | Run under Node 22.13+ (or `tsx`), never Bun. Look for `NGHTTP2_FRAME_SIZE_ERROR` in logs. |
 | The turn fails immediately with an API-key error | Sign in with `agent-sdk login`, or set `CURSOR_API_KEY`. Discovery, `info`, `call`, and serve bring-up work without a key; model turns need one. |
-| Replies quote rules or `AGENTS.md` from outside your agent project | The session workspace inherited parent-folder config. Nested git checkouts default `local.cwd` to `~/.cache/agent-serve/<dir>`. Point `defineAgent({ local: { cwd } })` at a checkout only when the agent should inherit that tree, or set `--state-root` to a clean directory (for example under `/tmp`). |
+| Replies quote rules or `AGENTS.md` from outside your agent project | The session workspace inherited parent-folder config. Nested git checkouts default `local.cwd` to a per-project cache directory under `~/.cache`. Point `defineAgent({ local: { cwd } })` at a checkout only when the agent should inherit that tree, or set `--state-root` to a clean directory (for example under `/tmp`). |
 | Yellow box shows Datadog/Linear tools, but the model lists `GetDynamicTools` / IDE `cursor` tools and never calls them | Attached MCP sits behind harness meta-tools, or `hostOnly` hid the connection, or the harness cwd is still inside another checkout. Set `advertiseTools: true` for named tools on local turns. Check `GET /v1/info` `local.cwd` and `connections[].advertiseTools`. |
 | Server tools, skills, or workspace seed files never appear | Server tools and sandbox seeds apply on the local runtime (cloud server tools need `--public-url` / `--cloud-tools-url`). Skills reach cloud through the Agent Store when hosting or a personal `CURSOR_API_KEY` is available; otherwise only skills already in the cloud repo. `validate` warns when this combination is present. |
 | `validate` and `run` succeed, but typecheck fails in CI | The CLI runs TypeScript with type-stripping only. Keep tool `execute` return types as object literals or `type` aliases, not `interface` types. |