@cursor/july 0.1.91 → 0.1.93

package/docs/reference/channels.md

@@ -11,7 +11,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](../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,
@@ -132,11 +132,9 @@ Handlers receive the Fetch `Request` and an args object:
 `"coalesce"` enqueues behind the running turn, the
 [Slack policy](./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
 
@@ -151,14 +149,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
@@ -166,8 +162,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?)`
@@ -221,22 +215,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](../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.
@@ -255,6 +244,6 @@ session; one active continuation per session; the HTTP channel returns
 Continue with these pages:
 
 - [Webhooks guide](../guides/webhooks.md): the same API, walked through
-- [HTTP API](./http-api.md): the built-in routes precisely
+- [HTTP API](./http-api.md): session, discovery, and channel routes
 - [Sessions and streaming](./sessions.md): the events channels
   subscribe to

package/docs/reference/cli.md

@@ -5,14 +5,10 @@ description: "Commands and common flags for local development, running servers,
 
 # 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](/#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`.
@@ -32,7 +28,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) |
@@ -97,7 +93,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]...
 ```
@@ -106,15 +101,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. |
@@ -124,12 +118,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`,
@@ -149,10 +141,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
 
@@ -289,7 +280,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.
@@ -325,7 +316,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.
@@ -393,7 +384,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>`). |
@@ -565,10 +556,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
 
@@ -648,7 +638,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
@@ -659,7 +649,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.
@@ -748,8 +738,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
@@ -945,9 +935,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. |

package/docs/reference/connections.md

@@ -30,7 +30,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
@@ -58,7 +58,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:
@@ -73,16 +73,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
@@ -93,14 +93,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}
 

package/docs/reference/hooks.md

@@ -6,11 +6,11 @@ description: "Observe-only subscribers to the session event stream: audit logs,
 # 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`,
@@ -38,7 +38,7 @@ export default defineHook({
 });
 ```
 
-Keys are event types (the full list is in the
+Keys are event types (see the
 [event vocabulary](./sessions.md#which-events-can-i-stream)), or `"*"`
 for everything. Handlers receive the event with its envelope (`index`,
 `sessionId`, `turnId?`, `at`) and a `HookContext`:
@@ -84,20 +84,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](./sessions.md): every event a hook can see
+- [Sessions and streaming](./sessions.md): the event vocabulary hooks observe
 - [OpenTelemetry](../guides/opentelemetry.md): OTLP traces and metrics
   from the same event stream
 - [Deployment](../deployment.md#observability): runtime logs and export

package/docs/reference/http-api.md

@@ -1,11 +1,11 @@
 ---
 title: "HTTP API"
-description: "Every route the server mounts: sessions, approvals, deterministic tool calls, discovery, the MCP endpoint, and dev-mode dispatch."
+description: "Public session, discovery, and channel routes callers use."
 ---
 
 # 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
@@ -30,8 +30,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
 
@@ -139,17 +138,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](./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](../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](../ab.md): per-session assignments and aggregate arm totals                                                                                                           |
 
 ## Artifacts
 
@@ -191,20 +189,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 |
@@ -213,10 +205,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](../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](../storage.md#eval-and-a-b-tables). Otherwise they are
+process-memory only.
 
 ## Dev-mode routes
 
@@ -224,29 +215,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
 

package/docs/reference/instructions.md

@@ -40,7 +40,7 @@ may also load ambient `AGENTS.md` and `.cursor` config from ancestor
 directories. [Agent config → Local cwd](./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](../quickstart.md) is the pattern:

package/docs/reference/playground.md

@@ -7,40 +7,35 @@ description: "The built-in web UI: chat with streaming, Try buttons and slash co
 
 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](../ab.md) from `GET /v1/abs` (folds durable
-  `ab.assigned` plus turn and tool events; no separate store).
+  [live A/B metrics](../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.
@@ -59,7 +54,7 @@ demo-only alternative for trusted networks.
 
 Continue with these pages:
 
-- [HTTP API](./http-api.md): everything the playground calls
+- [HTTP API](./http-api.md): the HTTP surface the playground uses
 - [Sessions and streaming](./sessions.md): the streams it renders
 - [Human-in-the-loop](../guides/human-in-the-loop.md): the approval
   buttons in context

package/docs/reference/project-layout.md

@@ -76,7 +76,7 @@ Each path maps to a capability and a reference page.
 | `agent/artifacts.ts` | `defineArtifacts` kinds, the `tag_artifact` opt-in, and retention | [Artifacts](./artifacts.md) |
 | `agent/schedules/*` | Cron-driven runs (UTC, 5-field; never auto-fire under `--dev`) | [Schedules](./schedules.md) |
 | `agent/sandbox/workspace/**` | Seed files copied into each local session workspace | [Sessions](./sessions.md#what-goes-into-a-local-session-workspace) |
-| `agent/playground/` | Custom playground tool chips for the Vite dev playground | [Playground](./playground.md) |
+| `agent/playground/` | Custom playground tool chips | [Playground](./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](../evals.md) |
 | `evals/**/*.eval.ts` | Filesystem evals; case id = path under `evals/` | [Evals](../evals.md) |
@@ -98,7 +98,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

package/docs/reference/prompt.md

@@ -35,7 +35,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

package/docs/reference/schedules.md

@@ -182,8 +182,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