@cursor/july 0.1.91 → 0.1.93

package/AGENTS.md

@@ -9,6 +9,10 @@ User-facing documentation lives in [`docs/`](./docs/README.md)
 troubleshooting, reference). This file is the terse loop reference;
 point humans at the docs.
 
+Start machine-readable docs at `dist/docs/llms.txt` when it exists, or at
+`/docs/llms.txt` on a running host. Use `llms-full.txt` only when the whole
+documentation set is needed.
+
 Before committing or reviewing any Agent SDK documentation change, read
 `docs/.cursor/skills/writing/SKILL.md` and
 `docs/.cursor/skills/docs-lint/SKILL.md`. Run `/docs-lint` on every change.

package/README.md

@@ -7,14 +7,14 @@
 > release, and 0.x versions may ship breaking changes without notice.
 
 A filesystem-first framework for building and serving Cursor agents.
-Customers define an agent as ordinary files — markdown for prose,
-TypeScript for typed behavior — under an `agent/` directory. The framework
+Customers define an agent as ordinary files: markdown for prose,
+TypeScript for typed behavior, under an `agent/` directory. The framework
 discovers those files, compiles them into a manifest, and serves the agent
 over channels, using the Cursor SDK (`@cursor/sdk`) and the Cursor harness
 as the execution engine.
 
-**User-facing documentation lives in [`docs/`](./docs/README.md)** —
-open it with `npx @cursor/july docs`, or at `/docs` on every running
+**User-facing documentation lives in [`docs/`](./docs/README.md)**.
+Open it with `npx @cursor/july docs`, or at `/docs` on every running
 `agent-sdk serve` host. It covers getting started, concepts, guides (Slack,
 GitHub webhooks, approvals, agent-to-agent, cloud runtime), evals, live
 A/B metrics, hillclimbing, deployment, troubleshooting, and reference
@@ -68,15 +68,13 @@ Serve one project with `agent-sdk serve --dir ./my-agent --dev`, or point
 `serve` at a folder of agent projects to mount every child under its
 directory name.
 
-## Node only — do not run under Bun
+## Node only: do not run under Bun
 
-Run the Agent SDK with **Node 22.13+** (from source: `pnpm exec tsx
-src/bin/agent-serve.ts …`, or the built `dist/bin/agent-serve.js`). Do not
-run it under Bun: Bun's HTTP/2 client corrupts the Cursor SDK's local
-harness tool-result streams (`NGHTTP2_FRAME_SIZE_ERROR`), so every built-in
-read/grep the model makes fails and turns degrade into failed-read retry
-loops (we measured an 8-minute review that takes ~1 minute under Node).
-The `mise` tasks in this package already use tsx.
+Run the Agent SDK with **Node 22.13+**. Use `agent-sdk` or
+`npx @cursor/july`. Do not run it under Bun: Bun's HTTP/2 client
+corrupts the Cursor SDK's local harness tool-result streams
+(`NGHTTP2_FRAME_SIZE_ERROR`), so every built-in read/grep the model
+makes fails and turns degrade into failed-read retry loops.
 
 ## Serving many agents at once
 
@@ -86,7 +84,7 @@ one port, each under its own slug (its directory name):
 ```bash
 agent-sdk serve --dir ./agents --dev
 # 2 agents listening
-#   playground  http://127.0.0.1:5273
+#   playground  <printed URL>
 ```
 
 `serve` always uses multi-agent layout by default: agents are mounted under
@@ -116,7 +114,7 @@ segments.
 
 Every mounted agent also serves the **Model Context Protocol** over
 streamable HTTP at `/<slug>/v1/mcp` (or `/v1/mcp` in single mode), so other
-agents — and any MCP client — can delegate work to it. The surface is
+agents, and any MCP client, can delegate work to it. The surface is
 stateless (session identity travels in tool arguments) and runs the same
 route auth chain as the session API. Tools:
 
@@ -146,15 +144,15 @@ export default defineConnection({
 ```
 
 The parent model then sees the peer's `ask` / `check` (/ `call_tool`) tools
-under the `weather` server name — subagent-style delegation where the peer
+under the `weather` server name: subagent-style delegation where the peer
 keeps its **own** instructions, tools, MCP connections, and sessions. Peer URLs
 resolve when the server starts (so `run` / `eval` ephemeral ports work):
 
 - **Local-runtime turns** (and host-side `ctx.host.mcp` / channel handlers)
-  call the peer over loopback — works out of the box under the default
+  call the peer over loopback. That works under the default
   `localDevStrict()` auth.
 - **Cloud-runtime turns** execute on a cloud VM that cannot reach this
-  host's loopback address. Pass `--public-url https://agent-serve.example.com`
+  host's loopback address. Pass `--public-url https://agents.example.com`
   (or `serve(dir, { publicUrl })`) so peers resolve to a reachable URL;
   without it, peers are omitted from cloud turns (the server warns at
   startup). With `--bearer-token`, the token is attached to peer calls
@@ -163,7 +161,7 @@ resolve when the server starts (so `run` / `eval` ephemeral ports work):
 Unknown peer slugs and self-references fail at serve startup. Peers require
 the multi-agent layout (each agent mounted under its slug). There is no
 cross-host loop protection yet: if agent A's instructions delegate to B and
-B's delegate back to A, they can recurse — scope each agent's delegation
+B's delegate back to A, they can recurse. Scope each agent's delegation
 instructions narrowly (the concierge above delegates *weather questions* to
 `weather-agent`, not everything).
 
@@ -190,8 +188,8 @@ You are a concise assistant. Use tools when they are available.
 import { defineAgent } from "@cursor/july";
 
 export default defineAgent({
-  // optional — defaults to grok-4.5 with effort=high and fast=true
-  // runtime: "local", // default — Cursor SDK local harness
+  // optional: defaults to grok-4.5 with effort=high and fast=true
+  // runtime: "local", // default: Cursor SDK local harness
   // runtime: "cloud",
   // cloud: {
   //   repos: [{ url: "https://github.com/org/repo", startingRef: "main" }],
@@ -200,7 +198,7 @@ export default defineAgent({
 ```
 
 Serve it (turns run on the Cursor harness, so the host needs a Cursor
-credential — sign in once, or export an API key):
+credential: sign in once, or export an API key):
 
 ```bash
 agent-sdk login          # browser sign-in; mints + stores a revocable API key
@@ -245,7 +243,7 @@ agent-sdk validate --dir .    # exit non-zero on error diagnostics
 ## Terminal client
 
 `agent-sdk chat` talks to a running server over the same public API and
-renders the reply live — streamed text, tool calls, and a per-turn usage
+renders the reply live: streamed text, tool calls, and a per-turn usage
 footer. Pass `--json` for a compact trajectory (same shape as `run`).
 
 ```bash
@@ -326,7 +324,7 @@ import { defineEvalConfig } from "@cursor/july/evals";
 
 export default defineEvalConfig({
   maxConcurrency: 20,
-  // Optional — playground /v1/dev/evals history window (default 20):
+  // Optional: playground /v1/dev/evals history window (default 20):
   // maxPlaygroundRuns: 50,
 });
 ```
@@ -349,61 +347,32 @@ evals, hillclimb, GitHub webhooks, Slack setup, debugging).
 
 Every served agent ships with a built-in playground. The default multi-agent
 mode serves it at `http://127.0.0.1:3000/<slug>/playground`.
-`--mode single` uses `http://127.0.0.1:3000/playground`. The Vite and React
-app uses the same public HTTP API for manual testing and demo recordings:
+`--mode single` uses `http://127.0.0.1:3000/playground`. The playground
+uses the same public HTTP API for manual testing and demo recordings:
 
 - chat with the agent and watch text/reasoning stream live, rendered as
   markdown (headings, lists, tables, blockquotes, links) with syntax
   highlighting for fenced code blocks (C-like languages, Python, shell,
   and diffs),
 - invoke custom channels as **slash commands** in the composer (e.g. a
-  `/drive https://github.com/org/repo/pull/1` channel route) — routes from `GET /v1/info`,
+  `/drive https://github.com/org/repo/pull/1` channel route). Routes from `GET /v1/info`,
   with `/help` and autocomplete; same HTTP as the Agent surface **Try**
   buttons,
 - see tool calls inline (args, output, error state) as `actions.requested`
   / `action.result` events arrive,
-- browse every session (chat, custom-channel, and schedule task sessions)
-  and replay their durable event streams,
+- browse the sessions you own (chat, custom-channel, and schedule
+  task sessions) and replay their event streams. In `--dev` on loopback,
+  or with `--allow-anonymous`, the list includes every principal,
 - dispatch schedules by hand in dev mode,
 - inspect the discovered agent surface (tools, skills, subagents, MCP
   connections, channels, hooks),
 - flip on the raw NDJSON pane to see the exact wire events.
 
-The SPA is a static bundle. `agent-sdk serve` auto-builds `dist/playground/`
-when it is missing and the local vite toolchain is present (`pnpm run build`
-also emits it for publish). The server serves the bundle and every call it
-makes runs the normal route auth chain (there's a bearer-token field for
-non-loopback setups). Disable it with `--no-playground` (CLI) or
-`serve(dir, { playground: false })`. When serving many agents, each has its
-own playground at `/<slug>/playground` and `/` is an index of them all (see
-"Serving many agents at once").
-
-### Developing the playground
-
-`serve --dev` / `dev` also starts Vite HMR (default `:5273`) and prints that
-URL as `playground`. Single-agent proxies `/v1` to the serve URL; multi-agent
-serves the agents index at `/` and each SPA at `/<slug>/playground`:
-
-```bash
-# single agent — auto-build + HMR in one process
-pnpm exec tsx src/bin/agent-serve.ts serve --dir ./my-agent --dev
-
-# monorepo dev: multi-agent HMR
-mise //packages/agent-serve:start
-# → backend :3000, playground HMR :5273 (open /, then /<slug>/playground)
-
-# pin one slug at the HMR root, or UI-only against an already-running serve
-AGENT_SERVE_BASE=/my-agent mise //packages/agent-serve:start
-AGENT_SERVE_MULTI=1 mise //packages/agent-serve:dev-playground
-```
-
-The Vite dev server proxies API calls to the backend (`AGENT_SERVE_TARGET`,
-default `http://127.0.0.1:3000`). Multi-agent HMR proxies `/<slug>/v1/*` as-is
-and serves each SPA at `/<slug>/playground`; a single-slug pin uses
-`AGENT_SERVE_BASE=/<slug>` at the HMR root. Editing anything under
-`playground/src` hot-reloads in the browser. The playground source lives in
-`playground/` (entry `playground/src/main.tsx`); markdown rendering and the
-trace model are plain modules under `playground/src/lib` with unit tests.
+`agent-sdk serve` serves the playground bundle. Disable it with
+`--no-playground` (CLI) or `serve(dir, { playground: false })`. When
+serving many agents, each has its own playground at `/<slug>/playground`
+and `/` is an index of them all (see "Serving many agents at once").
+`serve --dev` prints a playground URL; open that URL if the UI looks stale.
 
 To share the server beyond localhost (a tunnel, a LAN address, a phone),
 pass `--bearer-token <secret>` (or `serve(dir, { authToken })`). That
@@ -418,32 +387,19 @@ token into the top-right field.
 
 Session follow-up, stream, and list routes also bind to the principal that
 created the session (`403` when a different admitted principal addresses
-someone else's handle). Session ids are restricted to a single safe path
-segment before they touch `<stateRoot>/sessions`.
+someone else's handle).
 
 ## How it runs on the Cursor harness
 
-Every session is one Cursor SDK agent (`Agent.create` / `Agent.resume`).
-Local agents use the session id as the SDK agent id; cloud agents persist
-a separate `sdkAgentId` (typically `bc-…`). Each session gets its own
-workspace directory, materialized from the authored files and handed to
-the local harness as its working directory:
-
-| Folder or file           | Runtime mapping                                                                 |
-| ------------------------ | ------------------------------------------------------------------------------- |
-| `instructions.*`         | Local: `AGENTS.md` in the session workspace. Cloud: prepended to the first prompt. |
-| `tools/*.ts` (`execution: "server"`, default) | Local: in-process SDK custom tools. Cloud: authenticated HTTP MCP callbacks to the AgentSDK host. |
-| `tools/*.ts` (`execution: "agent"`) | Local: scripts under `.agent-serve/tools/` + catalog in `AGENTS.md`. Cloud: catalog + script bodies on the first prompt. |
-| `skills/*`               | Local: `.cursor/skills/<name>/SKILL.md` in the workspace. Cloud: native discovery from the Agent Store (`skills/` when hosted; `agent-serve/<agent>/skills/` on the USER store for local serve/run). |
-| `mcp-connections/*.ts`   | Always three places: Cursor agent via SDK `mcpServers` (local + cloud), host-side `ctx.host.mcp` for in-process tools, and `args.host.mcp` on channel/schedule handlers. |
-| `subagents/<id>/`        | SDK custom subagents (the model delegates via the harness `task` tool)          |
-| `sandbox/workspace/**`   | Local session workspace seed on first turn; ignored for cloud runtime. |
-| `channels/`, `schedules/`, `hooks/` | Served by this framework around the harness                         |
-
-Conversation state for local agents persists through the SDK's local store
-under `.agent-serve/runner/`, and every session's event stream is recorded
-to `.agent-serve/sessions/<id>/events.ndjson` — sessions survive server
-restarts, and streams replay from any `startIndex`.
+Each session is one Cursor SDK agent. Local turns run on this host.
+Cloud turns run on a Cursor cloud agent. The session stream records
+`agent.bound` with the cloud conversation URL.
+
+Authored files reach the model as instructions, tools, skills, and
+workspace seed files. The mapping differs by runtime; see
+[Cloud runtime](./docs/guides/cloud-runtime.md). Sessions and their
+event streams survive server restarts. Reconnect with `?startIndex=` to
+replay.
 
 ## Folder structure
 
@@ -460,7 +416,7 @@ export default defineAgent({
       { id: "fast", value: "true" },
     ],
   }, // optional; this is the default
-  runtime: "local", // default — or "cloud"
+  runtime: "local", // default: or "cloud"
   // cloud: {
   //   repos: [{ url: "https://github.com/org/repo", startingRef: "main" }],
   //   env: { type: "cloud" },
@@ -476,7 +432,7 @@ and `fast=true`.
 
 | Value     | Behavior |
 | --------- | ------- |
-| `"local"` | Cursor SDK local harness on this machine. Session id doubles as the SDK agent id. Authored tools, skills, and sandbox seeds apply. |
+| `"local"` | Cursor SDK local harness on this machine. Authored tools, skills, and sandbox seeds apply. |
 | `"cloud"` | Cursor cloud agents. Pass a `cloud` block with the repositories and environment the agent needs. Server tools work on managed hosting. Self-hosted cloud turns need `--public-url`. |
 
 Discovery warns when cloud turns ignore a local-only capability. Authored
@@ -527,7 +483,7 @@ stream emits `action.approval_requested` / `action.approval_resolved`.
 - Playground Approve / Deny buttons
 - HTTP: `POST /v1/session/:sessionId/approvals/:callId` with
   `{"decision":"approve"|"deny"}`
-- **Slack** (opt-in channel surface) — set `toolApprovals: true` on
+- **Slack** (opt-in channel surface): set `toolApprovals: true` on
   `slackChannel`, and enable `interactivity` in the Slack app
   manifest:
 
@@ -567,7 +523,7 @@ does **not** open cross-owner approval for HTTP sessions. Production and
 bearer-auth hosts stay strict: Slack resolve must come from Slack interactivity
 (or a matching principal).
 
-`--allow-anonymous` is for trusted-network demos only — every HTTP caller shares
+`--allow-anonymous` is for trusted-network demos only. Every HTTP caller shares
 the same `anonymous` principal. Prefer `--bearer-token` when the host is shared.
 
 Slack cards show **redacted / truncated** args for Block Kit limits; execution
@@ -592,9 +548,9 @@ export default defineTool({
 
 Approvals are only supported for `execution: "server"` tools on the
 `local` runtime. Exact resume of a parked SDK tool call does **not**
-survive host process restart — pending approvals left after a crash are
+survive host process restart. Pending approvals left after a crash are
 treated as interrupted.
-Agent tool (runs where the Cursor agent runs — local harness or cloud VM):
+Agent tool (runs where the Cursor agent runs: local harness or cloud VM):
 
 ```ts
 import { defineTool } from "@cursor/july/tools";
@@ -621,7 +577,7 @@ it explicitly next to `content` and `isError`. For server tools, `ctx` carries
 
 #### Deterministic tool calls
 
-Server tools can also be called **deterministically** — you pick the tool
+Server tools can also be called **deterministically**. You pick the tool
 and the input, no model turn decides anything. The input is validated
 against the tool's schema and `execute` runs in-process; the result comes
 back exactly as the model would receive it. No Cursor API key is needed.
@@ -646,7 +602,7 @@ agent-sdk call get_weather --url http://127.0.0.1:3000/<slug> --input '{"city":"
 
 Programmatically, `callTool(toolName, input, options?)` is available on the
 serve handle, on channel route handlers and `onStart` args, and on schedule
-`run` handlers — so a channel can mix deterministic tool calls with model
+`run` handlers, so a channel can mix deterministic tool calls with model
 turns (e.g. fetch PR metadata deterministically, then `send()` the review
 prompt):
 
@@ -655,17 +611,17 @@ const outcome = await handle.callTool("get_weather", { city: "NYC" });
 // { toolName, callId, isError, result, durationMs }
 ```
 
-By default the tool runs against an **ephemeral** scratch workspace under
-`<stateRoot>/tool-calls/<callId>` with a synthetic `direct` session context —
-materialized like a session workspace (AGENTS.md, skills, seed files) and
-removed once the call returns. Pass `sessionId` (body field over HTTP,
-`--session` on the CLI, `options.sessionId` programmatically) to run it
-**inside an existing session** instead: the tool sees that session's info
-and materialized workspace, and the call is recorded on the session's event
-stream as `actions.requested` / `action.result` under a per-call `turnId` —
-visible in the playground, NDJSON trace, and trajectories like any
-model-initiated call. Session-bound calls are serialized with model turns:
-while a turn is running the call is rejected with `409 session_busy`.
+By default the tool runs against an ephemeral scratch workspace,
+materialized like a session workspace (AGENTS.md, skills, seed files)
+and removed once the call returns. Pass `sessionId` (body field over
+HTTP, `--session` on the CLI, `options.sessionId` programmatically) to
+run it inside an existing session instead: the tool sees that session's
+info and materialized workspace, and the call is recorded on the
+session's event stream as `actions.requested` / `action.result` under a
+per-call `turnId`. That call is visible in the playground, NDJSON
+trace, and trajectories like any model-initiated call. Session-bound
+calls are serialized with model turns: while a turn is running the call
+is rejected with `409 session_busy`.
 
 Unknown tools are rejected with the available tool names, `execution:
 "agent"` tools cannot be called on the host (400), schema-invalid input is a
@@ -678,7 +634,7 @@ that throws is reported as `isError: true` with the same
 
 Skills follow the `SKILL.md` convention: model-loadable procedures the
 harness advertises by description and loads on demand. Author them as flat
-markdown (`skills/forecast.md`, optional `description` frontmatter — the
+markdown (`skills/forecast.md`, optional `description` frontmatter. The
 first body line is the fallback), packaged directories
 (`skills/research/SKILL.md` plus `references/…`, which require `description`
 frontmatter), or TypeScript (`defineSkill` from
@@ -755,7 +711,7 @@ Every MCP connection is always available in three places:
 
 1. the Cursor agent (local or cloud), via SDK `mcpServers`
 2. the serve host, for in-process tools via `ctx.host.mcp`
-3. channel / schedule handlers, via `args.host.mcp` (deterministic — no agent loop)
+3. channel / schedule handlers, via `args.host.mcp` (deterministic; no agent loop)
 
 ```ts
 export default defineTool({
@@ -768,7 +724,7 @@ export default defineTool({
 ```
 
 ```ts
-// agent/channels/webhook.ts — call MCP directly from a webhook
+// agent/channels/webhook.ts: call MCP directly from a webhook
 POST("/sync", {
   bodySchema: z.object({}),
   handler: async (_req, { host }) => {
@@ -784,8 +740,8 @@ POST("/sync", {
 ### Subagents (`agent/subagents/<id>/`)
 
 A subagent is its own directory with the same `agent.ts` +
-`instructions.md` shape. `description` is required — the parent model reads
-it to decide when to delegate — and `model` is optional (`inherit` by
+`instructions.md` shape. `description` is required. The parent model reads
+it to decide when to delegate, and `model` is optional (`inherit` by
 default). On the Cursor harness, subagents run as SDK custom subagents:
 they inherit the parent's execution surface, so per-subagent `tools/`,
 `skills/`, and `mcp-connections/` are reported as warnings and ignored for now.
@@ -795,22 +751,22 @@ they inherit the parent's execution surface, so per-subagent `tools/`,
 The **built-in HTTP channel** is always mounted (under `/<slug>` in the
 default multi-agent layout; at the server root with `mode: "single"`):
 
-- `POST /v1/session` — start a session (`{"message": "..."}`; returns
+- `POST /v1/session`: start a session (`{"message": "..."}`; returns
   `sessionId` + `continuationToken`)
-- `POST /v1/session/:sessionId` — follow-up (`{"message", "continuationToken"}`;
+- `POST /v1/session/:sessionId`: follow-up (`{"message", "continuationToken"}`;
   rotates the token; works for any chat session including custom channels like
   `drive`; `409` on stale tokens or task sessions;
   `403` if the caller is not the session owner)
-- `GET /v1/session/:sessionId/stream?startIndex=N` — replay + live NDJSON
+- `GET /v1/session/:sessionId/stream?startIndex=N`: replay + live NDJSON
   (same owner check)
-- `GET /v1/session/:sessionId/approvals` — pending human-in-the-loop
+- `GET /v1/session/:sessionId/approvals`: pending human-in-the-loop
   tool approvals for the session
-- `POST /v1/session/:sessionId/approvals/:callId` — approve or deny
+- `POST /v1/session/:sessionId/approvals/:callId`: approve or deny
   (`{"decision":"approve"|"deny"}`)
-- `GET /v1/sessions` — sessions owned by the calling principal
-- `POST /v1/tools/:toolName` — call a server tool deterministically
+- `GET /v1/sessions`: sessions owned by the calling principal
+- `POST /v1/tools/:toolName`: call a server tool deterministically
   (`{"input": {...}, "sessionId"?}`; see "Deterministic tool calls")
-- `GET /v1/health`, `GET /v1/info` — liveness and the manifest snapshot
+- `GET /v1/health`, `GET /v1/info`: liveness and the manifest snapshot
 Author `agent/channels/http.ts` only to override its defaults:
 
 ```ts
@@ -862,7 +818,7 @@ export default defineChannel({
 ```
 
 `GET` requires a Zod `querySchema` and `POST` / `PUT` / `PATCH` require a
-Zod `bodySchema` at compile time — plain JSON Schema objects will not
+Zod `bodySchema` at compile time. Plain JSON Schema objects will not
 type-check. Use `z.object({})` or `z.unknown()` when the surface is
 intentionally open. Schemas are validated by the host before the handler
 runs (handlers get typed `args.body` / `args.query`) and projected on
@@ -871,15 +827,16 @@ so the composer can offer matching **slash commands** (e.g. `/drive`).
 
 Route handlers receive a Fetch `Request` and helpers: `send`, `getSession`,
 `receive` (cross-channel hand-off), `params`, `requestIp`, `auth`, `host`
-(shared host services — MCP / GitHub / Slack; same as tool `ctx.host`), and
+(shared host services: MCP / GitHub / Slack; same as tool `ctx.host`), and
 `waitUntil`. Channel `state` declares initial per-session adapter state,
 persisted across events; handlers receive it on `channel.state`.
 
-**Auth**: every route runs an auth-policy chain (`auth` on the channel).
-The default is `[localDevStrict()]` — direct loopback callers only, with
-proxy-forwarding headers and non-loopback `Host` rejected — so nothing
-is exposed publicly until you add real auth (`bearerAuth(...)`, a custom
-policy, or the explicit `allowAll()`).
+**Auth**: channel routes and the session API run an auth-policy chain
+(`auth` on the channel). The host index, docs, and health routes run no
+auth. The default policy is `[localDevStrict()]`: direct loopback
+callers only, with proxy-forwarding headers and non-loopback `Host`
+rejected, so nothing is exposed publicly until you add real auth
+(`bearerAuth(...)`, a custom policy, or the explicit `allowAll()`).
 
 **Slack** (`@cursor/july/channels/slack`): a platform channel pack
 that defaults to **Socket Mode**. Author `agent/channels/slack.ts` with
@@ -888,14 +845,14 @@ that defaults to **Socket Mode**. Author `agent/channels/slack.ts` with
 ```ts
 import { slackChannel } from "@cursor/july/channels/slack";
 
-// Single agent — SLACK_BOT_TOKEN + SLACK_APP_TOKEN
+// Single agent: SLACK_BOT_TOKEN + SLACK_APP_TOKEN
 export default slackChannel();
 
-// Multi-agent serve — one Slack app (and token pair) per agent
+// Multi-agent serve: one Slack app (and token pair) per agent
 export default slackChannel({ envPrefix: "WEATHER_AGENT" });
 // → WEATHER_AGENT_SLACK_BOT_TOKEN + WEATHER_AGENT_SLACK_APP_TOKEN
 
-// Cursor account connection — no dedicated Slack app. `@Cursor Weatherbot …`
+// Cursor account connection: no dedicated Slack app. `@Cursor Weatherbot …`
 // routes here; replies post as "Weatherbot" through the Cursor Slack app.
 export default slackChannel({ cursorAccount: true, agentName: "Weatherbot" });
 ```
@@ -912,7 +869,7 @@ return a prepared `message` / `workspaceFiles` / `cloud` to host-prepare PR
 reviews or attach
 cloud repos from an `@mention`.
 
-**Engagement:** by default the agent is summoned, never proactive — it
+**Engagement:** by default the agent is summoned, never proactive. It
 dispatches only on `app_mention` and DMs. Channel watch is an explicit opt-in:
 
 ```ts
@@ -954,7 +911,7 @@ Approve/Deny cards and routes Socket Mode `interactive` clicks to
 (App-Level Token with `connections:write`).
 
 Most demos under `examples/` use the Cursor Slack connection
-(`cursorAccount: true`) with a unique single-token `agentName` —
+(`cursorAccount: true`) with a unique single-token `agentName`.
 `@Cursor Benny …`, `@Cursor Bugbot …`, `@Cursor ApprovalBuddy …`, etc.
 Sign the host in, then mention the agent; no per-agent Slack app required
 for chat. Agents that need channel watch or tool approvals keep a Socket
@@ -965,11 +922,11 @@ from the directory name by `slack create`).
 | Agent | `@Cursor` name | Optional Socket Mode app |
 | --- | --- | --- |
 | `weather-agent` | Weather | `slack-app.ts` (`WEATHER_AGENT_SLACK_*`, tool approvals) |
-| `slack-agent` | SlackAgent | — |
-| `bugbot` | Bugbot | — |
-| `fsd` | FSD | — |
+| `slack-agent` | SlackAgent | - |
+| `bugbot` | Bugbot | - |
+| `fsd` | FSD | - |
 | `benny` | Benny | `slack-app.ts` (`BENNY_SLACK_*`, channel watch) |
-| `approval-buddy` | ApprovalBuddy | — |
+| `approval-buddy` | ApprovalBuddy | - |
 
 PR-oriented demos (`bugbot`, `fsd`) extract a GitHub PR URL / `owner/repo#N`
 from the mention and run the same host path as their HTTP channels.
@@ -1014,7 +971,7 @@ export default githubChannel({
 
 Mounts at `POST /<slug>/v1/channels/github`. When a webhook secret is set the
 channel verifies `X-Hub-Signature-256` before parsing (the HMAC becomes the
-request auth); without one it stays loopback-only (`localDevStrict()`) — except
+request auth); without one it stays loopback-only (`localDevStrict()`), except
 under `serve --dev`, which admits unsigned loopback deliveries so
 `gh webhook forward` and fixtures work with zero config. Hooks return
 `{ auth }` to start a model turn as the actor, `{ task }` for host-side work
@@ -1032,7 +989,7 @@ auth prefers GitHub App installation tokens when `GITHUB_APP_ID` /
 `GITHUB_TOKEN` / `GH_TOKEN` or `gh auth login`. The channel publishes the
 webhook events it dispatches on (derived from the declared hooks, or pinned
 via `webhookEvents`), so `agent-sdk github …` can forward live
-deliveries with zero hand-listing — it wraps [`gh webhook
+deliveries with zero hand-listing. It wraps [`gh webhook
 forward`](https://docs.github.com/en/webhooks/testing-and-troubleshooting-webhooks/using-the-github-cli-to-forward-webhooks-for-testing):
 
 ```bash
@@ -1057,12 +1014,12 @@ agent-sdk github forward --dir ./agents
 When several channels match (e.g. a folder of agent projects with more than
 one github channel), one forwarder fans out to all of them: `gh webhook
 forward` runs against a local proxy that re-posts each raw (still-signed)
-delivery to the channels whose event set matches. This is required — GitHub
+delivery to the channels whose event set matches. This is required. GitHub
 allows only one forwarder per repo, and `gh webhook forward` targets a single
 URL, so N processes would collide with `Hook already exists`.
 
-`gh webhook forward` needs **admin** on the repo (or org owner for `--org`) —
-it registers a real webhook — and authenticates its relay with the GitHub CLI's
+`gh webhook forward` needs **admin** on the repo (or org owner for `--org`).
+It registers a real webhook, and authenticates its relay with the GitHub CLI's
 own login. If `GITHUB_TOKEN` / `GH_TOKEN` is set in your env, deliveries fail
 with **HTTP 401** (the relay rejects env tokens); blank it for the command
 (`GITHUB_TOKEN= GH_TOKEN= agent-sdk github forward …`) or `unset` it.
@@ -1074,12 +1031,12 @@ tunnel), and `--slug` / `--channel` to forward to just one of several agents.
 Against a `--dev` server no secret is needed; set `GITHUB_WEBHOOK_SECRET` (or
 `--secret`) to exercise signature verification (required for a non-dev target).
 Only one forwarder per repo/org at a time (a GitHub limitation). Fixture replay
-still works too — `POST` a saved payload with an `x-github-event` header (no
+still works too: `POST` a saved payload with an `x-github-event` header (no
 signature needed in `--dev`).
 
 **No admin? Hillclimbing? Use `github replay`.** `gh webhook forward` needs repo
 admin and a live event. `agent-sdk github replay <pr_url>` instead **reads**
-the PR (pull access is enough — no admin, no relay, and `GITHUB_TOKEN` is fine)
+the PR (pull access is enough: no admin, no relay, and `GITHUB_TOKEN` is fine)
 and synthesizes GitHub-shaped payloads it POSTs straight at the channel:
 
 ```bash
@@ -1097,7 +1054,7 @@ agent-sdk github replay owner/repo#123 --dir ./my-agent --events '*' --dry-run -
 `--action` / `--conclusion` / `--comment` / `--context` tune each synthesized
 event; `--secret` (or `GITHUB_WEBHOOK_SECRET`) signs them so a secret-configured
 channel verifies. Because replay sends a clean, signed loopback request, it
-passes both the `localDevStrict()` and `allowAll()`+signature auth modes — and
+passes both the `localDevStrict()` and `allowAll()`+signature auth modes, and
 it's fully deterministic, which is what hillclimbing wants.
 
 **Production alternative: pull from Cursor (`--cursor-events`).** If the
@@ -1110,7 +1067,7 @@ Serve fails fast rather than starting with a relay that can never receive
 events.
 
 ### Hooks (`agent/hooks/*.ts`)
-Observe-only subscribers that run after each event is recorded — audit
+Observe-only subscribers that run after each event is recorded: audit
 logs, metrics, mirroring transcripts into your own store. Keys are event
 types (or `*`); handler errors are logged, never fatal.
 
@@ -1148,7 +1105,7 @@ export default defineSchedule({
 
 Cron expressions are standard 5-field, evaluated in UTC with minute
 granularity. In production mode (`agent-sdk serve`) schedules fire on
-cadence; in dev mode (`--dev`) they never fire automatically — dispatch one
+cadence; in dev mode (`--dev`) they never fire automatically. Dispatch one
 by hand, exactly once, through the same path production uses:
 
 ```bash
@@ -1179,19 +1136,18 @@ await handle.createReminder({
 ```
 
 Host/policy packs may pass `run` (return `stop` / `skip` / `delivered`)
-instead of prompts. In `--dev`, use `POST /v1/dev/reminders/:id` (or
-`handle.dispatchReminder`) to fire; auto-timers follow
-`ServeOptions.reminders` (default `!dev`). Run handlers are in-memory —
-after restart those reminders are disarmed (`handler_lost_on_restart`);
-re-arm from enroll/policy.
+instead of prompts. `--dev` does not auto-fire reminders. Dispatch one
+with `POST /v1/dev/reminders/:id` or `handle.dispatchReminder`. Run
+handlers are in-memory. After a restart those reminders are disarmed
+(`handler_lost_on_restart`); re-arm from enroll/policy.
 
-The NDJSON stream vocabulary — one JSON object per line, each carrying
+The NDJSON stream vocabulary: one JSON object per line, each carrying
 `{ type, index, sessionId, turnId?, at, data }`:
 
 | Event                 | Meaning                                                        |
 | --------------------- | -------------------------------------------------------------- |
 | `session.started`     | A durable session was created.                                 |
-| `agent.bound`          | Cursor agent id is known (`sdkAgentId`; cloud: `bc-…` + URL).  |
+| `agent.bound`          | Cloud conversation URL.                                        |
 | `ab.assigned`         | Sticky A/B enrollment (`experiment`, `variant` or `null` skip). |
 | `message.received`    | An inbound user message was accepted.                          |
 | `turn.started`        | A turn began.                                                  |
@@ -1219,7 +1175,7 @@ import { serve } from "@cursor/july";
 
 const handle = await serve("./my-agent", {
   port: 3000,
-  apiKey: process.env.CURSOR_API_KEY, // optional — see credential order below
+  apiKey: process.env.CURSOR_API_KEY, // optional: see credential order below
 });
 console.log(`listening on ${handle.url}`);
 // handle.dispatchSchedule("heartbeat"), handle.project, await handle.close()
@@ -1233,22 +1189,21 @@ Cursor dashboard to kill it outright).
 
 Local-dev note: login/account RPCs honor `CURSOR_API_BASE_URL` while the
 Cursor SDK harness honors `CURSOR_BACKEND_URL`. When pointing at a
-non-production backend, set **both** to the same URL — a key minted on one
+non-production backend, set **both** to the same URL. A key minted on one
 backend is rejected by the other.
 
 `serve` refuses to start when discovery produced error diagnostics; run
 `agent-sdk validate` (or read `project.diagnostics`) to see why.
 
-State lives under `<project>/.agent-serve/` (override with `stateRoot` /
-`--state-root`): `sessions/<id>/{session.json,events.ndjson,workspace/}`
-plus the SDK conversation store under `runner/`. Delete a session directory
-to forget that conversation.
+State lives under the project state directory (override with
+`--state-root`). Forget a conversation by removing that session from
+state.
 
-Session workspaces are real Cursor project directories, so the harness also
-loads ambient project config from ancestor directories (nested
-`AGENTS.md` / `.cursor` rules and skills). Nested git checkouts default
-`local.cwd` to `~/.cache/agent-serve/<dir>`. Point `cwd` at a checkout only
-when the agent should inherit that tree.
+Session workspaces are real Cursor project directories, so the harness
+also loads ambient project config from ancestor directories. Nested git
+checkouts default `local.cwd` to a per-project cache directory under
+`~/.cache`. Point `cwd` at a checkout only when the agent should inherit
+that tree.
 
 ## Not supported (yet)