@cursor/july 0.1.92 → 0.1.94

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,24 @@ 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
+An optional `"continuationToken"` (`<channelId>:<key>`, as
+`/v1/sessions` lists it; mutually exclusive with `sessionId`) addresses
+the session by continuation token instead; malformed tokens are
+rejected with `400 invalid_continuation_token`. For the semantics, see
+[Tools](./tools.md#call-a-tool-without-a-model-turn).
 
-Five read-only routes describe the running agent.
+## Discovery
+
+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/tools`        | The live tool catalog: authored server tools plus advertised MCP passthroughs under model-facing names, as light `{ name, title?, source? }` entries. `session` / `continuationToken` query parameters bind the listing to a session identity (advertised inventories can be tenant-scoped); a connection whose listing fails is skipped and reported in `connectionErrors` |
+| `GET /v1/tools/:name`  | One catalog tool's full description: description, execution, `needsApproval`, `effect`, input and output schemas, source connection. Same session binding as the listing; unknown names get `404` with the available names |
 | `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 +197,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 +213,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 +223,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

@@ -17,7 +17,8 @@ experiments can override their file-derived name.
 | Path | Resolves to |
 | --- | --- |
 | `agent/tools/approve_pr.ts` | tool `approve_pr` |
-| `agent/mcp-connections/linear.ts` | MCP connection `linear` |
+| `agent/mcp-connections/linear.ts` | MCP connection `linear` (model + host) |
+| `agent/host-connections/anytool.ts` | Host MCP connection `anytool` (host + `mcp oauth` only) |
 | `agent/skills/pr-review.md` | skill `pr-review` |
 | `agent/subagents/reviewer/` | subagent `reviewer` |
 | `agent/channels/drive.ts` | channel `drive`, routes under `/v1/channels/drive` |
@@ -45,6 +46,8 @@ my-agent/
 │   │   └── pr-review.md       # on-demand procedures (SKILL.md convention)
 │   ├── mcp-connections/
 │   │   └── linear.ts          # tools from external MCP servers
+│   ├── host-connections/
+│   │   └── anytool.ts         # privileged MCP, host tools only
 │   └── channels/
 │       └── github.ts          # messages and external events
 └── evals/
@@ -66,6 +69,7 @@ Each path maps to a capability and a reference page.
 | `agent/tools/<name>.ts` | One typed tool; filename = tool name. `execution: "server"` (in-process, default) or `"agent"` (a script that runs where the agent runs) | [Tools](./tools.md) |
 | `agent/skills/*` | SKILL.md-convention procedures, loaded on demand | [Skills](./skills.md) |
 | `agent/mcp-connections/<name>.ts` | MCP servers, available to the model, to server tools (`ctx.host.mcp`), and to channel/schedule handlers (`args.host.mcp`) | [MCP connections](./connections.md) |
+| `agent/host-connections/<name>.ts` | Privileged MCP servers for `ctx.host.mcp` and `mcp oauth`. The model never sees them. | [MCP connections](./connections.md) |
 | `agent/subagents/<id>/` | Child agent directory; `description` required | [Subagents](./subagents.md) |
 | `agent/channels/*.ts` | HTTP surfaces beyond the built-in session API; `slack.ts` and `github.ts` use the platform packs | [Channels](./channels.md) |
 | `agent/hooks/*.ts` | Observe-only event subscribers, never fatal | [Hooks](./hooks.md) |
@@ -76,7 +80,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 +102,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

package/docs/reference/sessions.md

@@ -79,7 +79,7 @@ within one session. The `at` field is an ISO-8601 timestamp.
 | Phase | Events | What they tell you |
 | --- | --- | --- |
 | Session | `session.started`, [`ab.assigned`](../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](./agent-config.md#concurrency), then turn status, final result, and token usage |
 | Steps | `step.started`, `step.completed` | Model step boundaries and duration |
@@ -118,7 +118,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                                                 |
 
@@ -133,34 +133,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](../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

package/docs/reference/skills.md

@@ -57,9 +57,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

package/docs/reference/subagents.md

@@ -41,8 +41,8 @@ different one.
 Subagents inherit the parent's execution surface. Every per-subagent
 capability directory is reported as a warning and ignored: `tools/`,
 `skills/`, `mcp-connections/` (and the legacy `connections/` alias),
-`channels/`, `schedules/`, `hooks/`, `sandbox/`, and nested
-`subagents/`.
+`host-connections/`, `channels/`, `schedules/`, `hooks/`, `sandbox/`,
+and nested `subagents/`.
 
 Delegation needs both halves: the description makes it possible, and the
 parent's [instructions](./instructions.md) make it happen. "When a

package/docs/reference/tools.md

@@ -64,7 +64,7 @@ export default defineTool({
 });
 ```
 
-### The `ctx` parameter
+### Tool context
 
 `execute` receives a `ctx` with the runtime accessors:
 
@@ -76,7 +76,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](./artifacts.md) facade: `tag` auto-fills the session |
 
 `ctx.host` carries the shared host services: `host.mcp` (authored MCP
@@ -84,9 +84,7 @@ connections: `names()`, `listTools(name)`, `callTool(name, tool, args)`),
 `host.github` and `host.slack` (shared platform clients), `host.kv` and
 `host.files` (durable [storage](../storage.md)), `host.otel` (custom
 metrics and session tags; see [OpenTelemetry](../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
 
@@ -174,23 +172,24 @@ 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
 local turn. See
 [MCP Connections](connections.md#advertise-tools).
 Advertised tools ride the same execution path as authored server tools,
-but cannot be invoked via
-[direct tool calls](#call-a-tool-without-a-model-turn).
+and [direct tool calls](#call-a-tool-without-a-model-turn) address them
+by the same model-facing names: the call's session identity resolves the
+advertised listing when the authored lookup misses.
 
 ## Gate a tool on human approval
 
@@ -259,15 +258,27 @@ 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. When the
+session's harness cwd cannot be materialized, a read-effect call runs
+in a scratch workspace instead and the outcome carries
+`scratchWorkspace: true`; a write-effect call fails with
+`workspace_unavailable`.
+
+A session can also be addressed by its continuation token: an optional
+`continuationToken` (`<channelId>:<key>`, as `/v1/sessions` lists it;
+mutually exclusive with `sessionId`). A token that maps to a live
+session behaves exactly like passing that session's id — same ownership
+check, same `409 session_busy`, same event recording. A token with no
+session behind it runs the call scratch-bound with the token's channel
+id and continuation key as the call's session identity, so a deployment
+whose tools resolve state from the continuation key can serve it with
+no live session. Malformed tokens are rejected with
+`400 invalid_continuation_token`.
 
 The error semantics match the model path. Unknown tools are rejected
 with the available names, agent-execution tools cannot be called on the

package/docs/scaffolding-agents.md

@@ -22,12 +22,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`](../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).
@@ -127,7 +126,7 @@ inputs again, and adds an eval for each improvement you keep.
 
 ## Related
 
-- [Build your first PR approver](./quickstart.md)
+- [Build your first PR reviewer](./quickstart.md)
 - [Convert a Cursor Automation](./guides/convert-automation.md)
 - [Building agents with agents](./building-with-agents.md)
 - [Evals](./evals.md)