@cursor/july 0.1.113 → 0.2.0

package/docs/reference/http-api.md

@@ -3,34 +3,33 @@ title: "HTTP API"
 description: "Public session, discovery, and channel routes callers use."
 ---
 
-# HTTP API reference
-
-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
-unslugged (`/v1/*`).
-
-Unless noted otherwise, routes run the agent's HTTP auth chain: the
-default is `localDevStrict()` (loopback only), replaced by `bearerAuth` under
-`--bearer-token` or `allowAll()` under `--allow-anonymous`. Session
-routes also require the caller to be the session's owner (`403`
-otherwise). Errors return JSON
-`{ ok: false, error: "<code>", message? }` with a matching HTTP status.
-
-## Host-level routes (multi-agent mode)
-
-These routes live at the host root, above any agent. The two index
-routes exist only while the playground is enabled (`--no-playground`
-removes them) and run no auth. The documentation site is mounted in
-both layouts and removed by `--no-docs`.
-
-| Route                      | What it does                                                                                                                 |
-| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| `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                                                                                                 |
+# HTTP API
+
+Agent SDK hosts expose one public HTTP surface. In the default
+multi-agent layout, each agent uses `/<slug>/v1/*`; `--mode single`
+serves the same routes at `/v1/*`. Routes use the agent's HTTP auth
+chain, and session-owned resources return `403` to another principal.
+
+Unless a section says otherwise, the default auth policy is
+`localDevStrict()`. `--bearer-token` replaces it with bearer auth, and
+`--allow-anonymous` replaces it with anonymous access. Built-in JSON
+routes use `{ ok: false, error: "<code>", message? }` for errors; MCP
+uses JSON-RPC, and custom channel handlers define their own responses.
+
+## Host routes
+
+These routes live at the host root in multi-agent mode. The index routes
+exist only when the playground is enabled.
+
+| Route | Contract |
+| --- | --- |
+| `GET /` | HTML index of mounted agents; no auth |
+| `GET /v1/agents` | JSON index of mounted agents; no auth |
+| `GET /docs`, `GET /docs/*` | Documentation site in either layout; no auth |
+| `GET /v1/health` | Host liveness; no auth |
+
+`--no-playground` removes the two index routes. `--no-docs` removes the
+documentation site.
 
 ## Start a session
 
@@ -44,18 +43,18 @@ curl -X POST http://127.0.0.1:3000/<slug>/v1/session \
 #  "playgroundUrl":"…?sessionId=ses_…","traceUrl":"…/v1/session/ses_…/events"}
 ```
 
-The response returns as soon as the message is accepted; follow the
-stream for progress. The continuation token is the follow-up credential,
-and `playgroundUrl` deep-links the session in the playground.
+Once accepted, the response returns `sessionId` for inspection and
+`continuationToken` for follow-ups; follow the stream for progress.
 
-| Body field | Meaning |
+| Body field | Contract |
 | --- | --- |
 | `message` | Required user message |
-| `title` | Session title |
+| `title` | Display title |
 | `dryRun` | Run read tools and stub write tools |
-| `asOf` | ISO-8601 instant with a timezone, frozen at create; the prompt states it, `ctx.now()` returns it, and tool calls with relative, later-than-`asOf`, or omitted schema-declared time bounds are refused. `400` when unusable |
-| `workspaceFiles` | UTF-8 files written into the session workspace |
+| `asOf` | ISO-8601 instant with a timezone; sets `ctx.now()` and rejects omitted, relative, or later declared tool time arguments. Invalid values return `400` |
+| `workspaceFiles` | Relative files added to the session workspace |
 | `cloud` | Per-session cloud options merged over the agent defaults |
+| `purpose` | Use `"eval"` to mark regression traffic |
 
 ## Send a follow-up
 
@@ -67,15 +66,15 @@ curl -X POST http://127.0.0.1:3000/<slug>/v1/session/ses_… \
   -d '{"continuationToken":"http:…","message":"Make it shorter."}'
 ```
 
-Works for any chat session, including ones created by custom channels.
-Each accepted follow-up rotates the token, and the response carries the
-new one. Sending to a busy session interrupts the in-flight turn, waits
-for it to settle, then sends.
+The route accepts any chat session, including one created by a custom
+channel. Each accepted follow-up rotates the continuation token and
+returns the replacement. A message sent to a busy session interrupts
+the active turn before starting.
 
-Expect `409` on a stale token or a task session. Task sessions do not accept
-follow-ups. Expect `403` when the caller is not the session owner.
+The route returns `409` for a stale token or task session, and `403`
+when the caller doesn't own the session.
 
-## Stream a session
+## Stream or replay session events
 
 `GET /v1/session/:sessionId/stream` is the live NDJSON feed.
 
@@ -83,44 +82,36 @@ follow-ups. Expect `403` when the caller is not the session owner.
 curl -N 'http://127.0.0.1:3000/<slug>/v1/session/ses_…/stream?startIndex=0'
 ```
 
-One NDJSON event per line, from `startIndex`, then following live. The
-default is `0`: omitting the parameter replays the entire recorded
-stream before following. Pass the last index you've seen plus one to
-resume without duplicates. The stream is durable and reconnectable. For
-the vocabulary, see
-[Sessions](./sessions.md#which-events-can-i-stream).
+The route replays one event per line from `startIndex`, then follows new
+events. The default `0` replays the full stream. To reconnect without
+duplicates, pass the last index you received plus one.
 
 `GET /v1/session/:sessionId/events` returns a one-shot NDJSON dump.
-Pass `?format=json` for `{ sessionId, events, playgroundUrl }`.
-
-## Stop and list
-
-`POST /v1/session/:sessionId/stop` interrupts the in-flight turn without
-sending a new message. `GET /v1/sessions` lists sessions owned by the
-calling principal. Under `serve --dev` on loopback it includes all
-sessions, which is how webhook and schedule sessions show up in the
-playground.
+Pass `?format=json` for `{ sessionId, events, playgroundUrl }`. See
+[Stream events](./sessions.md#stream-events) for the event vocabulary.
 
-## Session cost
+## Manage sessions
 
-`GET /v1/session/:sessionId/cost` returns the session's cost report:
-per-turn token usage and the engine's estimated cost, folded from
-`turn.completed` events. It runs the same owner check as the other
-session routes and returns `404` for an unknown session. The
-[`agent-sdk cost`](./cli.md#cost) command reports the same data.
+| Route | Contract |
+| --- | --- |
+| `POST /v1/session/:sessionId/stop` | Interrupt the active turn without sending another message |
+| `GET /v1/sessions` | List sessions owned by the caller |
+| `GET /v1/session/:sessionId/cost` | Return per-turn token usage and estimated cost |
 
-## Approvals
+On loopback under `serve --dev`, the session list includes every
+principal so webhook and schedule sessions appear in the playground.
+The cost route returns `404` for an unknown session.
 
-Two routes list and resolve parked tool calls.
+## Resolve tool approvals
 
-| Route                                           | What it does                                                   |
-| ----------------------------------------------- | -------------------------------------------------------------- |
-| `GET /v1/session/:sessionId/approvals`          | Pending human-in-the-loop tool approvals                       |
-| `POST /v1/session/:sessionId/approvals/:callId` | Resolve one: `{"decision":"approve"}` or `{"decision":"deny"}` |
+| Route | Contract |
+| --- | --- |
+| `GET /v1/session/:sessionId/approvals` | List pending tool approvals |
+| `POST /v1/session/:sessionId/approvals/:callId` | Resolve one with `{"decision":"approve"}` or `{"decision":"deny"}` |
 
 For the lifecycle, see [Gate a tool on human approval](./tools.md#gate-a-tool-on-human-approval).
 
-## Call a tool directly
+## Call a tool without a model turn
 
 `POST /v1/tools/:toolName` runs a server tool with no model turn.
 
@@ -132,130 +123,115 @@ curl -X POST http://127.0.0.1:3000/<slug>/v1/tools/inspect_pr \
 #  "isError":false,"result":{…},"durationMs":12}
 ```
 
-It runs an authored server tool in-process: schema-validated, no model
-turn. An optional `"sessionId"` in the body runs it inside an existing
-session and records it on that session's stream (`409 session_busy`
-for a write-effect call while a turn runs; reads run alongside the
-turn). 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).
+| Body field | Contract |
+| --- | --- |
+| `input` | Tool input; defaults to `{}` |
+| `sessionId` | Bind the call to an existing session |
+| `continuationToken` | Bind the call by its wire continuation token; mutually exclusive with `sessionId` |
 
-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).
+Omit both identifiers for an unbound call. Agent-execution tools return
+`400`, and an unknown name returns `404` with the available names. See
+[Tools](./tools.md#call-a-tool-without-a-model-turn) for session
+binding, busy-session rules, and error codes.
 
-## Discovery
+## Discovery routes
 
 These read-only routes describe the running agent.
 
-| Route                  | What it does                                                                                                                                                                             |
-| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `GET /v1/info`         | The discovered surface: model, tools, skills, MCP connections, subagents, channels and routes (with schemas), schedules, hooks, 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/logs?after=N` | Recent server log lines, with a polling cursor                                                                                                                                           |
+| Route | Contract |
+| --- | --- |
+| `GET /v1/info` | Return the discovered model, tools, skills, connections, subagents, channels, schedules, hooks, and diagnostics |
+| `GET /v1/tools` | Return live server tools and advertised MCP tools as `{ name, title?, source? }`; bind tenant-scoped listings with `session` or `continuationToken` |
+| `GET /v1/tools/:name` | Return one tool's description, execution mode, approval and effect rules, schemas, and source |
+| `GET /v1/health` | Return per-agent liveness; no auth |
+| `GET /v1/logs?after=N` | Return recent server logs and the next polling cursor |
 
-## Artifacts
+An unknown tool name returns `404` with available names. If an MCP
+connection can't list its tools, the catalog skips that connection and
+includes it in `connectionErrors`.
 
-Two routes read durable artifacts tagged by `ctx.artifacts` or
-`tag_artifact`. See [Artifacts](./artifacts.md).
+## List and download artifacts
 
-| Route                            | What it does                                                                                          |
-| -------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `GET /v1/artifacts`              | List artifacts as `{ artifacts }`, newest-updated first. Filter with `?kind=`, `?sessionId=`, and `?limit=` (a positive integer) |
-| `GET /v1/artifacts/:id/content`  | Download one artifact's file or blob payload. Served as an attachment, never rendered inline; `404` when the artifact is unknown or carries no content |
+| Route | Contract |
+| --- | --- |
+| `GET /v1/artifacts` | Return `{ artifacts }`, newest-updated first; filter with `kind`, `sessionId`, and a positive `limit` |
+| `GET /v1/artifacts/:id/content` | Download an artifact's file or blob as an attachment; return `404` when no content exists |
 
-Session ownership applies the same way as `GET /v1/sessions`: under
-`serve --dev` on loopback (or `--allow-anonymous`) the list spans all
-principals, while bearer or custom channel auth keeps strict
-per-principal isolation.
+The list follows the same ownership rules as `GET /v1/sessions`. See
+[Artifacts](./artifacts.md) for tagging and record fields.
 
-## Custom channel routes
+## Call custom channel routes
 
-Authored routes mount under `/v1/channels/<id>` with the methods, paths,
-and Zod schemas the channel declared (a
-`POST /<slug>/v1/channels/drive` route, say). Bodies are validated before
-handlers run (`400` on schema violations), and each channel's auth chain
-applies. The GitHub channel verifies `X-Hub-Signature-256` when a
-secret is configured. See [Channels](./channels.md).
+Authored routes mount under `/v1/channels/<id>` with their declared
+methods and paths. The host validates their Zod body and query schemas
+before calling the handler, returning `400` on failure. Each channel's
+auth chain applies. See [Channels](./channels.md).
 
 ## MCP endpoint
 
-`/v1/mcp` serves the Model Context Protocol over streamable HTTP
-(stateless; POST carries the protocol, and GET/DELETE return
-spec-compliant 405s). The tools are `ask` (delegate a message, bounded
-waits), `check` (poll a running session), and `call_tool` (deterministic
-server-tool passthrough, present when the agent has server tools). The
-route runs the same auth chain as the session API. Peer wiring:
-[MCP connections](./connections.md#peer-mcp-connection).
+Both MCP routes use stateless streamable HTTP. Send protocol requests
+with `POST`; `GET` and `DELETE` return `405`.
 
-`/v1/mcp/tools` is a second stateless MCP endpoint exposing only the
-agent's deterministic server tools. Hosted cloud turns call back into
-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.
+| Route | Tools and auth |
+| --- | --- |
+| `/v1/mcp` | `ask`, `check`, and `call_tool` when server tools exist; uses the session API auth chain |
+| `/v1/mcp/tools` | Deterministic server tools only; uses the CLI-level loopback, bearer, or anonymous auth chain |
+
+See [MCP connections](./connections.md#peer-mcp-connection) to connect
+one agent to another.
 
 ## Playground eval routes
 
-The playground Evals tab and `agent-sdk eval --prod` / `--url` use these:
+The playground Evals tab and remote eval commands use these routes:
 
-| Route                           | What it does                                                                                               |
-| ------------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `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 |
+| Route | Contract |
+| --- | --- |
+| `GET /v1/dev/evals` | List discovered cases and eval config |
+| `GET /v1/dev/evals/runs` | List recent run snapshots, newest first |
+| `POST /v1/dev/evals/runs` | Start `{ filterIds?, tags?, timeoutMs?, verbose? }`; return `202`, `404` for no match, or `409` while another run is active |
+| `GET /v1/dev/evals/runs/:runId` | Return progress and the final snapshot |
+| `POST /v1/dev/evals/runs/:runId/cancel` | Cancel an active run; return `404` when unknown or `409` when no longer running |
 
-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 when
-durable storage is configured. Otherwise they are
-process-memory only.
+Poll the run route until its status is `completed`, `failed`, or
+`cancelled`. Entries within `filterIds` and `tags` use OR semantics;
+when both fields are present, a case must match each group.
 
 ## Dev-mode routes
 
 These routes exist only under `serve --dev`.
 
-| Route                                | What it does                                                                                               |
-| ------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
+| Route | Contract |
+| --- | --- |
 | `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                                                                                    |
+| `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.
+routes run them manually.
 
 ## Playground assets
 
 `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.
+playground. `--no-playground` removes both routes.
 
 ## Status codes
 
-Error responses use a small, consistent set of status codes.
-
-| Code  | Meaning here                                                                                                               |
-| ----- | -------------------------------------------------------------------------------------------------------------------------- |
-| `400` | Schema-invalid body or query, agent-execution tool called on the host, malformed request                                   |
-| `401` | No auth policy admitted the request                                                                                        |
-| `403` | Authenticated, but not the session owner                                                                                   |
-| `404` | Unknown session, tool, schedule, reminder, or eval run; no eval datapoints match a run request                              |
-| `405` | Wrong method (GET on the MCP endpoint, say)                                                                                |
-| `409` | Stale continuation token, a busy session-bound tool call, a non-followable task session, or an eval run already in progress |
-| `202` | Accepted for background work (GitHub `{ task }` hooks, eval runs)                                                          |
-
-## What's next
+Built-in routes use these common status codes.
 
-Continue with these pages:
-
-- [Sessions and streaming](./sessions.md): the handles and events these
-  routes traffic in
-- [Channels](./channels.md): authoring your own routes
-- [Deployment](../deployment.md): auth on real hosts
+| Code | Meaning |
+| --- | --- |
+| `400` | Invalid body, query, tool input, or request shape |
+| `401` | No auth policy admitted the request |
+| `403` | The caller is authenticated but doesn't own the resource |
+| `404` | A named resource doesn't exist, or an eval selection matches no cases |
+| `405` | The route doesn't accept this method |
+| `409` | The resource state rejects the request, such as a stale token or busy write |
+| `202` | The request was accepted for asynchronous work |
+| `500` | A write-effect tool can't create its session workspace (`workspace_unavailable`) |
+
+## Related
+
+- [Sessions](./sessions.md)
+- [Channels](./channels.md)
+- [Tools](./tools.md)
+- [Deployment](../deployment.md)

package/docs/reference/instructions.md

@@ -1,23 +1,21 @@
 ---
 title: "Instructions"
-description: "The always-on system prompt: authoring forms, how it reaches the model on each runtime, and what makes instructions hold up."
+description: "The always-on system prompt: authoring forms, how it reaches each runtime, and what belongs in it."
 ---
 
 # Instructions
 
-`agent/instructions.md` is the always-on system prompt. It's the one
-piece of prose the model sees on every turn. It's required on the root
-agent; subagents may inline `instructions` in their `agent.ts` instead.
+Agent instructions form the always-on system prompt and reach the model
+on every turn. A root agent requires them; a subagent may inline
+`instructions` in `agent.ts` instead.
 
 ## Authoring forms
 
-Three forms cover every case.
-
-| Form | Reach for it when |
+| Form | Use it when |
 | --- | --- |
-| `agent/instructions.md` | Plain Markdown for most agents. |
-| `agent/instructions.ts` | Generated prompts. Default-export `defineInstructions({ markdown })` or a plain string. |
-| `agent/instructions/` directory | A long prompt split across files, composed in filename order. |
+| `agent/instructions.md` | Plain Markdown for most agents |
+| `agent/instructions.ts` | Generated prompts. Default-export `defineInstructions({ markdown })` or a plain string |
+| `agent/instructions/` directory | A long prompt split across files, composed in filename order |
 
 ```ts
 // agent/instructions.ts
@@ -28,22 +26,17 @@ export default defineInstructions({
 });
 ```
 
-## How instructions reach the model
-
-On the local runtime, instructions land in the session workspace as
-`AGENTS.md`, and the harness loads them natively. On the cloud runtime,
-they're prepended to the first prompt, because the cloud VM doesn't
-share the local session workspace.
+## Delivery
 
-The local workspace is a real Cursor project directory, so the harness
-may also load ambient `AGENTS.md` and `.cursor` config from ancestor
-directories. [Agent config → Local cwd](./agent-config.md#local-cwd)
-covers controlling that.
+Local and cloud turns receive the composed instructions. They aren't
+written into the session workspace. Parent directories can still
+contribute ambient `AGENTS.md` and `.cursor` settings; [Agent config:
+local cwd](./agent-config.md#local-cwd) covers how to control that.
 
-## What to put in instructions
+## Contents
 
-Keep them a few lines: identity, when to use which tool, output shape.
-The [quickstart PR approver](../quickstart.md) is the pattern:
+Keep them a few lines: identity, when to use which tool, and the output
+shape. The [quickstart PR approver](../quickstart.md) is the pattern:
 
 ```md
 # PR approver
@@ -57,21 +50,13 @@ You review GitHub pull requests. Be specific and brief.
 End with one sentence: the verdict and why.
 ```
 
-- Name the tools and the decision rule ("use X before answering about
-  Y"), not general encouragement.
-- State the output contract: length, format, fences. That contract is
-  what your [evals](../evals.md) gate.
-- Move procedures to [skills](./skills.md). A multi-step workflow the
-  model only sometimes needs belongs in `agent/skills/`, where it loads
-  on demand and keeps the always-on prompt small.
-
-Instructions are the third lever in the
-[hillclimbing loop](../hillclimbing.md), after host preparation and evidence
-shape. If a fixture keeps failing, look there before rewriting prose.
-
-## What's next
+Name the tools and the decision rule ("use X before answering about
+Y"), not general encouragement. State the output contract, including
+length, format, and fences, so your [evals](../evals.md) can gate it.
+Put multi-step workflows the model only sometimes needs in
+`agent/skills/`; they load on demand and keep the always-on prompt small.
 
-Continue with these pages:
+## Related
 
 - [Skills](./skills.md): procedures the model loads only when relevant
 - [Agent config](./agent-config.md): the file next to this one

package/docs/reference/playground.md

@@ -5,55 +5,38 @@ description: "The built-in web UI: chat with streaming, Try buttons and slash co
 
 # Playground
 
-Every served agent ships with a web playground at
+`agent-sdk serve` enables a web playground at
 `http://127.0.0.1:3000/<slug>/playground` (or `/playground` in single
-mode). Anything you can do there you can also do with curl.
-
-## What it does
-
-Use the playground to chat, try channel routes, and inspect sessions.
-
-- **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>`), 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 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.
-- **Custom tool chips**: drop `agent/playground/tools/<toolName>.tsx` to
-  change how that tool renders. Chips compile from the agent tree;
-  an [extension](./extensions.md) cannot contribute them.
-- **Raw events pane**: flip it on to inspect the event stream.
-- **Logs tab**: recent server log lines, polled from `GET /v1/logs`.
-
-In multi-agent mode each agent has its own playground at
-`/<slug>/playground`, and `/` is an index of them all.
-
-## Share it beyond localhost
+mode). In multi-agent mode, each agent has its own playground, and `/`
+lists them all.
+
+## Playground surfaces
+
+| Surface | What you can do |
+| --- | --- |
+| Chat | Talk to the agent. Text and reasoning stream live, and tool calls appear inline with their arguments, output, and error state |
+| Slash commands | Custom channel routes without path parameters become composer commands; GitHub and Slack ingress routes are excluded. A `drive` route becomes `/drive <pr-url>`, with `/help` and autocomplete |
+| Try | Invoke a custom channel route from the Agent tab. The modal remembers your last body per endpoint, copies curl, and opens a session when the route creates one |
+| Runs | Browse the sessions you own and eval runs. Search by title or identifier; open sessions in Chat, Trace, or Raw and eval runs in Evals |
+| Approvals | Parked `needsApproval` tool calls render Approve / Deny buttons |
+| Evals | List and run filesystem evals from the browser |
+| Agent | Inspect the discovered tools, skills, subagents, MCP connections, channels, and hooks |
+| Raw | Inspect the selected session's event stream |
+| Logs | Recent server log lines, polled from `GET /v1/logs` |
+
+In `--dev` on loopback, or with `--allow-anonymous`, the session list
+includes every principal.
+
+## Remote access
 
 The default `localDevStrict()` auth admits direct loopback calls only
 and rejects proxy-forwarding headers, so a tunnel or LAN address won't
-work
-until you pass `--bearer-token <secret>` (or
+work until you pass `--bearer-token <secret>` (or
 `serve(dir, { authToken })`). Open the playground on the remote device
-and paste the token into the token field in the navbar. `--allow-anonymous` is the
-demo-only alternative for trusted networks.
-
-## What's next
+and paste the token into the token field in the navbar.
+`--allow-anonymous` is the demo-only alternative for trusted networks.
 
-Continue with these pages:
+## Related
 
 - [HTTP API](./http-api.md): the HTTP surface the playground uses
 - [Sessions and streaming](./sessions.md): the streams it renders