@cursor/july 0.1.109 → 0.1.111

package/docs/deployment.md

@@ -107,7 +107,9 @@ Pass `--team <id>` when the signed-in account has no default team or you
 want another team.
 
 `--all` creates a separate deployment for each child. Self-host when the
-agents must share one multi-agent process.
+agents must share one multi-agent process. Cloud-runtime peers on that
+host need `--public-url` and `--bearer-token`. Walkthrough:
+[Agent-to-agent](./guides/agent-to-agent.md#how-do-i-wire-two-agents).
 
 The command waits up to ten minutes for a running engine. Use
 `--no-wait` to return after Cursor accepts the deployment, then inspect
@@ -146,7 +148,6 @@ out of agent-captured terminals when you can.
 | Command | What prints |
 | --- | --- |
 | `secrets set` / `secrets list` | Names only. Values never print. |
-| `rotate-pod-credential` | Masked key only. |
 | First `deploy` / `rotate-token` | Full alias token once. Save it outside the agent transcript; it cannot be retrieved later. |
 | `deployment --json` | May include short-lived `engineAccess.headers`. Treat JSON as a credential. |
 
@@ -158,7 +159,7 @@ the feature that needs the secret.
 
 Hosted filesystem state can reset during a deploy or runtime
 replacement. Prefer
-[`cursorHostedStorage`](./storage.md) so records survive replace.
+`cursorHostedStorage` so records survive replace.
 Do not put platform storage or deployment-identity names in
 `hosting.secretNames`. Self-host with your own `defineStorage` backend or
 a persistent `--state-root` when the complete filesystem must survive.
@@ -323,8 +324,8 @@ credential resolution.
 
 Place `--state-root` on a persistent volume outside the agent
 repository, and back it up. Sessions survive restarts only when their
-state does. See [Storage](./storage.md) and
-[Sessions](./reference/sessions.md) for persistence and layout details.
+state does. See [Sessions](./reference/sessions.md) for persistence
+and layout details.
 
 ### A single box
 
@@ -445,8 +446,6 @@ Continue with these pages:
 
 - [CLI reference](./reference/cli.md#deploy): deploy, inspect, stop, and
   rotate hosted agents
-- [Storage](./storage.md): preserve supported records across engine
-  replacements
 - [Channels](./reference/channels.md#auth-policies): the auth policies
   in detail
 - [GitHub guide](./guides/github.md): delivery paths without a public URL

package/docs/evals.md

@@ -41,7 +41,7 @@ has the side-by-side table.
   gate.
 - Stop a bad turn while it runs with
   [`needsApproval`](./reference/tools.md#gate-a-tool-on-human-approval)
-  on the tool or [`defineResult`](./reference/result.md). Evals grade
+  on the tool or `defineResult`. Evals grade
   after the fact.
 
 ## Write your first eval
@@ -206,7 +206,7 @@ creation:
 | --- | --- |
 | `workspaceFiles` | `{ path: contents }` seeded into the local session workspace. Prefer this over machine-local paths |
 | `workspaceDir` | Absolute harness cwd for the local runtime |
-| `cloud` | Per-session cloud options merged over the agent's static `cloud` config. Pin a fixture repo here for cloud evals instead of on the agent's default `cloud.repos`. On the cloud runtime, seeded files reach the agent as described under [Where does a turn run?](./concepts.md#where-does-a-turn-run) |
+| `cloud` | Per-session cloud options merged over the agent's static `cloud` config. Pin a fixture repo here for cloud evals instead of on the agent's default `cloud.repos`. On the cloud runtime, seeded files reach the agent as described under [Choose a runtime](./reference/agent-config.md#choose-a-runtime) |
 
 ```ts
 await t.send("Review pr/diff.patch and post findings.", {
@@ -441,7 +441,7 @@ async execute({ findings }, ctx) {
 Return a shaped result instead of throwing, so the eval can still
 assert `t.calledTool("post_findings", { input: ... })` on the decision.
 The same check belongs in [hooks](./reference/hooks.md) that meter or
-page and in [`defineResult`](./reference/result.md) commits.
+page and in `defineResult` commits.
 
 ## Worked examples
 
@@ -603,8 +603,8 @@ throws is logged and never fails the run. CI usually attaches the
 built-in two with `--junit` and `--artifacts` instead of `reporters`,
 so output paths stay with the pipeline, not the eval author.
 
-Playground batches survive restarts when the project has
-[storage](./storage.md#eval-table). Otherwise they live in process
+Playground batches survive restarts when the project configures
+durable storage. Otherwise they live in process
 memory until `serve` exits.
 
 ## Run evals from the CLI

package/docs/guides/agent-to-agent.md

@@ -1,45 +1,41 @@
 ---
 title: "Agent-to-agent"
-description: "Every agent is an MCP server. Peer MCP connections let one agent delegate to another that keeps its own tools, sessions, and context."
+description: "Wire two Agent SDK agents on one host so one can ask the other."
 ---
 
 # Agent-to-agent
 
-Every mounted agent is also an MCP server. So agents can delegate to each
-other without extra infrastructure. One agent hands a question to
-another, and the peer answers in its own session with its own
-instructions, tools, and context. Any external MCP client can do the
-same. A peer MCP connection makes the wiring one line.
+Point one agent at another on the same host. The peer keeps its own
+session, instructions, and tools.
 
-This guide wires a `concierge` agent that delegates weather questions
-to a `weather-agent` peer mounted on the same host.
-
-## MCP endpoint
+## Peer or subagent?
 
-Each agent serves the Model Context Protocol over streamable HTTP at
-`/<slug>/v1/mcp` (or `/v1/mcp` in single mode). The surface is stateless
-(session identity travels in tool arguments) and runs the same route
-auth chain as the session API. It exposes three tools:
+Use a [subagent](../reference/subagents.md) to split one job into roles
+inside a single agent. Use a peer when the specialist is a full agent
+you would run on its own.
 
-| Tool | Behavior |
-| --- | --- |
-| `ask` | Send a message. Runs a model turn in this agent's own session and returns `{ status, sessionId, reply }`. Omit `sessionId` for a fresh session; pass it back to follow up. |
-| `check` | Wait for or poll a running session (`waitSeconds: 0` polls without blocking). |
-| `call_tool` | Call one of the agent's server tools directly, no model turn. Registered only when the agent has server tools. |
+| | Subagent (`agent/subagents/<id>/`) | Peer (`defineConnection({ agent })`) |
+| --- | --- | --- |
+| Runs as | a child of this agent | an agent on the same host |
+| Tools, MCP connections, sessions | the parent's | its own |
+| Who can reach it | only the parent | other agents, MCP clients, its playground |
 
-Waits are bounded at roughly 50 seconds, below typical MCP client
-request timeouts: a long turn returns `status: "running"` and the caller
-keeps waiting with `check`. Sessions created this way live on the `mcp`
-channel, bind to the calling principal, and show up in the playground
-and `GET /v1/sessions` like any other session.
+## How do I wire two agents?
 
-Any MCP client can attach to this endpoint. It isn't only for other
-Agent SDK agents.
+Put both projects in one directory:
 
-## Wire a peer MCP connection
+```
+agents/
+  concierge/
+    agent/instructions.md
+    agent/mcp-connections/weather.ts
+  weather-agent/
+    agent/instructions.md
+```
 
-A peer MCP connection points one agent at another mounted on the same
-serve host. Author an MCP connection whose transport is the peer's slug:
+`weather-agent` is a normal Agent SDK project. On the concierge, add a
+connection. Set `agent` to the peer's slug, which is its directory
+name:
 
 ```ts
 // agents/concierge/agent/mcp-connections/weather.ts
@@ -51,68 +47,29 @@ export default defineConnection({
 });
 ```
 
-The parent model now sees the peer's `ask` and `check` (and `call_tool`)
-tools under the `weather` server name. It reads like subagent
-delegation, except the peer is a full agent that keeps its own
-instructions, tools, MCP connections, and sessions.
+The filename is the MCP server name. The concierge model sees the peer
+under `weather`. See
+[HTTP API](../reference/http-api.md#mcp-endpoint) for the MCP tools.
+
+In the concierge `instructions.md`, say when to ask: "When a request
+needs weather, ask the `weather` peer." Scope the line to the work the
+peer should handle. If two agents can ask each other, they will loop.
 
 ```bash
-agent-sdk serve --dir ./agents --dev
+agent-sdk dev ./agents
 agent-sdk chat --url http://127.0.0.1:3000/concierge \
   --message "What's the weather in Paris right now?"
-# concierge → weather.ask → weather-agent's own session/tools → reply
 ```
 
-## Peer or subagent?
-
-The two delegation mechanisms solve different problems.
+Cursor-managed hosting deploys one agent per slug. Keep peers on one
+self-hosted process. Cloud-runtime turns need `--public-url` and
+`--bearer-token`. See [Deployment](../deployment.md).
 
-| | Subagent (`agent/subagents/<id>/`) | Peer (`defineConnection({ agent })`) |
-| --- | --- | --- |
-| Runs as | an SDK custom subagent inside the parent's harness | an independent agent on the same host |
-| Own tools, MCP connections, sessions | no, inherits the parent's surface | yes, everything is its own |
-| Visible to others | only its parent | any MCP client, other agents, its own playground |
-| Reach for it when | splitting one job into specialist roles | composing independently useful agents |
-
-## How peer URLs resolve
-
-Peer URLs resolve when the server starts, so the ephemeral ports `run`
-and `eval` use work too. Local-runtime turns (and host-side
-`ctx.host.mcp` or channel-handler calls) reach the peer over loopback,
-which works under the default auth. Cloud-runtime turns execute on a VM
-that cannot reach this host's loopback address: pass
-`--public-url https://agent-sdk.example.com` (or
-`serve(dir, { publicUrl })`) so peers resolve to a reachable URL.
-Without one, peers are omitted from cloud turns and the server warns at
-startup. With `--bearer-token`, the token is attached to peer calls
-automatically so they pass the target agent's auth chain.
-
-## Guardrails
-
-Unknown peer slugs and self-references fail `serve` at startup, so you
-find out immediately rather than at delegation time. Peers require the
-multi-agent layout (each agent mounted under its slug, the default).
-
-The framework does not provide cross-host loop protection. If agent A's
-instructions delegate to B and B's delegate back to A, they can recurse.
-Scope each agent's delegation instructions narrowly. The concierge
-delegates *weather questions* to `weather-agent`, not everything.
-
-## Call a peer from host code
-
-Peer MCP connections are ordinary MCP connections, so deterministic host code
-can use them too. A channel handler or server tool can call
-`host.mcp.callTool("weather", "ask", { message: "…" })` without any
-model turn deciding to. See
-[MCP connections](../reference/connections.md#every-model-visible-mcp-connection-is-available-in-three-places)
-for the three places every model-visible MCP connection is available.
+Unknown slugs and self-references fail `serve` at startup. Peers need
+the default multi-agent layout.
 
 ## What's next
 
-Continue with these pages:
-
-- [MCP connections](../reference/connections.md): all four MCP connection
-  transports
-- [Subagents](../reference/subagents.md): the in-harness alternative
-- [HTTP API](../reference/http-api.md#mcp-endpoint): the endpoint
-  contract
+- [MCP connections](../reference/connections.md#peer-mcp-connection): `{ agent }`
+- [Subagents](../reference/subagents.md): specialists inside one agent
+- [HTTP API](../reference/http-api.md#mcp-endpoint): `/v1/mcp`

package/docs/guides/cloud-agents.md

@@ -3,7 +3,7 @@ title: "Cursor cloud agents"
 description: "Let an agent-sdk agent hand coding work to Cursor cloud agents and steer them: mount the extension, pick the repositories it may touch, and decide what needs approval."
 ---
 
-# Cursor cloud agents
+# Cloud agents
 
 The `cursor-cloud-agents` extension lets an agent delegate coding work
 to Cursor cloud agents and stay in the conversation while they do it.
@@ -14,7 +14,7 @@ a PR, a planner fans a refactor out across repositories, a reviewer asks
 a cloud agent to address its own comments.
 
 This is different from
-[`runtime: "cloud"`](../reference/agent-config.md#choose-a-runtime). The
+`[runtime: "cloud"](../reference/agent-config.md#choose-a-runtime)`. The
 runtime moves *this* agent's turns onto a cloud VM. The extension keeps
 the agent where it is and lets it start *other* cloud agents.
 
@@ -49,18 +49,18 @@ With the extension mounted, the agent can hand off coding work and stay
 in the conversation while it happens:
 
 - **Hand off a task.** Launch a cloud agent on one of your repositories,
-  or on a pull request, with a self-contained brief. It gets back an
-  agent id and a URL to share.
+or on a pull request, with a self-contained brief. It gets back an
+agent id and a URL to share.
 - **Check on it.** See whether the agent is still running, what it
-  produced, and which branches or pull requests it pushed.
+produced, and which branches or pull requests it pushed.
 - **Read what was done.** Pull the agent's full conversation into the
-  workspace, quote its final report, or trace the exact edits before
-  summarizing for a person.
+workspace, quote its final report, or trace the exact edits before
+summarizing for a person.
 - **Steer or stop.** Send a follow-up to an agent it launched; it queues
-  behind the current run, or interrupts it on request. Cancel a run that
-  went sideways.
+behind the current run, or interrupts it on request. Cancel a run that
+went sideways.
 - **Keep track.** List the agents launched in this conversation, or
-  everything it has launched before.
+everything it has launched before.
 
 A skill teaches the model when to delegate, how to write a brief a cloud
 agent can act on alone, and how to follow up. Everything the extension
@@ -73,13 +73,17 @@ their own.
 
 ## Configure it
 
-| Option | What it controls |
-| --- | --- |
-| `cloud` | Launch defaults, in the same shape as the agent's own [cloud options](../reference/agent-config.md#cloud-options). |
-| `cloud.repos` | The repositories the agent may hand work to, with a default branch or pull request for each. Without it, launches run with no repository and the model can't name one, so secrets in `cloud.envVars` never reach a repository you didn't list. |
-| `model` | The model launched agents run. Omit it to use the account default. |
-| `needsApproval` | Park launches and follow-ups for a [human decision](./human-in-the-loop.md). Defaults to `true` when no `cloud.repos` are configured, `false` otherwise. |
-| `apiKey` | A Cursor API key to launch with instead of the host's own. |
+
+| Option          | What it controls                                                                                                                                                                                                                               |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cloud`         | Launch defaults, in the same shape as the agent's own [cloud options](../reference/agent-config.md#cloud-options).                                                                                                                             |
+| `cloud.repos`   | The repositories the agent may hand work to, with a default branch or pull request for each. Without it, launches run with no repository and the model can't name one, so secrets in `cloud.envVars` never reach a repository you didn't list. |
+| `model`         | The model launched agents run. Omit it to use the account default.                                                                                                                                                                             |
+| `needsApproval` | Park launches and follow-ups for a [human decision](../reference/tools.md#gate-a-tool-on-human-approval). Defaults to `true` when no `cloud.repos` are configured, `false` otherwise.                                                          |
+| `apiKey`        | A Cursor API key to launch with instead of the host's own.                                                                                                                                                                                     |
+
+
+
 
 ## Adjust it
 
@@ -92,6 +96,7 @@ directory and disable that tool; see
 Continue with these pages:
 
 - [Extensions](../reference/extensions.md): how mounts, namespaces, and
-  overrides work
-- [Human-in-the-loop approvals](./human-in-the-loop.md): where parked
-  launches get approved
+overrides work
+- [Gate a tool on human approval](../reference/tools.md#gate-a-tool-on-human-approval):
+where parked launches get approved
+

package/docs/guides/github.md

@@ -11,7 +11,7 @@ event stream for repos you've connected to Cursor. You still declare a
 `githubChannel` so hooks decide what each event does.
 
 The companion skill for coding agents is
-[`skills/github/SKILL.md`](../skills/github.md).
+[`skills/github/SKILL.md`](../../skills/github/SKILL.md).
 
 ## Pull events from Cursor
 

package/docs/guides/grokbot-agents.md

@@ -3,7 +3,7 @@ title: "Cursor Grok Bot agents"
 description: "Let an agent-sdk agent talk to your Grok Bot agents: mount the extension, name the bots it may reach, and decide what needs approval."
 ---
 
-# Cursor Grok Bot agents
+# Grok Bot agents
 
 The `cursor-grokbot-agents` extension lets an agent send a message to
 one of your Grok Bot agents and read the reply. The Grok Bot keeps its
@@ -35,8 +35,13 @@ a name outside the list is refused. Calls run under the host's
 signed-in account (`agent-sdk login`, `CURSOR_API_KEY`, or
 `CURSOR_SERVICE_ACCOUNT_KEY`). Keep approval on when you can't.
 
-Start from the [Grok Bot agents template](../templates/grokbot-agents.md)
-when you want a project that already mounts this.
+To scaffold a project that already mounts this:
+
+```bash
+npx @cursor/july init ./grokbot --template grokbot-agents
+```
+
+
 
 ## What the agent can do
 
@@ -44,15 +49,15 @@ With the extension mounted, the agent can consult a Grok Bot and stay
 in its own conversation:
 
 - **Ask.** Send a self-contained message to a Grok Bot by the name
-  shown in the Grok Bot app. The message lands in your conversation
-  with that bot. The tool waits for the bot's reply.
+shown in the Grok Bot app. The message lands in your conversation
+with that bot. The tool waits for the bot's reply.
 - **Keep waiting.** A long turn returns `status: "running"`. Call check
-  with the same name to read what arrived since the last look.
+with the same name to read what arrived since the last look.
 - **Stop a turn.** Interrupt the bot's current work. The conversation
-  stays; a later ask continues it.
+stays; a later ask continues it.
 - **See who you can talk to.** List the configured bots and the ones
-  this caller has already asked. Add a name to `agents` when you want
-  the model to reach another bot.
+this caller has already asked. Add a name to `agents` when you want
+the model to reach another bot.
 
 A skill teaches the model when to bring a Grok Bot in, how to write a
 message the bot can act on alone, and how to wait or interrupt. The
@@ -69,11 +74,15 @@ need their own.
 
 ## Configure it
 
-| Option | What it controls |
-| --- | --- |
-| `agents` | The Grok Bot agents the model may talk to, by the name shown in the app. A lone entry is the default when a call names none. Omit `agents` to allow any name; an unknown name creates an empty Grok Bot on the account. |
-| `needsApproval` | Park asks for a [human decision](./human-in-the-loop.md). Defaults to `true` when no `agents` are configured, `false` otherwise. |
-| `apiKey` | A Cursor API key to call with instead of the host's own. |
+
+| Option          | What it controls                                                                                                                                                                                                        |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agents`        | The Grok Bot agents the model may talk to, by the name shown in the app. A lone entry is the default when a call names none. Omit `agents` to allow any name; an unknown name creates an empty Grok Bot on the account. |
+| `needsApproval` | Park asks for a [human decision](../reference/tools.md#gate-a-tool-on-human-approval). Defaults to `true` when no `agents` are configured, `false` otherwise.                                                           |
+| `apiKey`        | A Cursor API key to call with instead of the host's own.                                                                                                                                                                |
+
+
+
 
 ## Adjust it
 
@@ -85,9 +94,8 @@ directory and disable that tool; see
 
 Continue with these pages:
 
-- [Grok Bot agents template](../templates/grokbot-agents.md): scaffold
-  an agent that already mounts this
 - [Extensions](../reference/extensions.md): how mounts, namespaces, and
-  overrides work
-- [Human-in-the-loop approvals](./human-in-the-loop.md): where parked
-  asks get approved
+overrides work
+- [Gate a tool on human approval](../reference/tools.md#gate-a-tool-on-human-approval):
+where parked asks get approved
+

package/docs/guides/mcp-oauth.md

@@ -13,7 +13,7 @@ deployment as secrets so prod can reconnect after a redeploy. Hosted
 Connect lets the current process retry.
 
 The companion skill is
-[`skills/mcp-auth/SKILL.md`](../skills/mcp-auth.md).
+[`skills/mcp-auth/SKILL.md`](../../skills/mcp-auth/SKILL.md).
 
 ## What can host MCP OAuth do?
 

package/docs/guides/opentelemetry.md

@@ -7,11 +7,11 @@ description: "Push session, turn, and tool traces from the serve process to an O
 
 Agent SDK can push traces, metrics, and logs from the serve process to
 an OTLP collector you run. Point the process at the collector with
-standard `OTEL_EXPORTER_OTLP_*` env, or author `agent/otel.ts`. Traces
-cover the inbound request, each turn, and every tool call.
+standard `OTEL_EXPORTER_OTLP_*` environment variables, or pass the
+same options to `serve({ otel })`. Traces cover the inbound request,
+each turn, and every tool call.
 
-Export is opt-in. Nothing leaves the process until you set an endpoint
-or a `defineOtel` config.
+Export is opt-in. Nothing leaves the process until you set an endpoint.
 
 ## What does Agent SDK export?
 
@@ -22,7 +22,7 @@ or a `defineOtel` config.
 | Logs | off | Session events as log records. Prompt text, tool payloads, and failure messages stay off unless you opt in |
 
 Turn off a signal with `traces: false`, `metrics: false`, or `logs: false`
-on `defineOtel`. Logs also turn on when you set `OTEL_LOGS_EXPORTER` to
+on `serve({ otel })`. Logs also turn on when you set `OTEL_LOGS_EXPORTER` to
 anything other than `none`, or when you set the content flags below.
 
 ## How do I turn OpenTelemetry export on?
@@ -61,46 +61,34 @@ Optional:
 | `OTEL_LOG_USER_PROMPTS=1` | Include user prompt text on logs and span events |
 | `OTEL_LOG_TOOL_CONTENT=1` | Include tool payloads and failure text (truncated) |
 
-`serve(dir, { otel: false })` turns export off even when env or
-`agent/otel.ts` is set.
+`serve(dir, { otel: false })` turns export off even when env is set.
 
-## How do I author `agent/otel.ts`?
-
-Use `defineOtel` when you want the collector URL, headers, or sampling
-in the project instead of the environment:
+You can pass the same options object to `serve(dir, { otel })`.
+Precedence is `serve({ otel })` over env.
 
 ```ts
-import { defineOtel } from "@cursor/july/otel";
-
-export default defineOtel({
-  serviceName: "cursor",
-  exporters: [
-    {
-      url: "https://otel.example.com",
-      protocol: "http/protobuf",
-      headers: { Authorization: "Bearer …" },
-    },
-  ],
+await serve(dir, {
+  otel: {
+    serviceName: "cursor",
+    exporters: [
+      {
+        url: "https://otel.example.com",
+        protocol: "http/protobuf",
+        headers: { Authorization: "Bearer …" },
+      },
+    ],
+  },
 });
 ```
 
 Multiple `exporters` fan out to every destination. Restrict one
 destination with `signals: ["traces"]`.
 
-You can also pass the same object to `serve(dir, { otel })`. Precedence
-is `serve({ otel })` over `agent/otel.ts` over env. An empty
-`defineOtel()` still records traces; export starts when
-`OTEL_EXPORTER_OTLP_*` or a factory-returned `exporters` list appears.
-
-Hosted deployments can bind secrets after startup. Pass a factory so
-flush can re-read them. The hosted handler constructs the OTLP client
-when it flushes and sends the queued batch.
-
-```ts
-export default defineOtel(() => resolveMyOtelConfig());
-```
+`defineOtel` / `agent/otel.ts` (`@cursor/july/internal/otel`) is
+factory-only. Discovery still loads that file for Cursor factory
+agents. It is not a public Agent SDK export.
 
-The companion skill is [`skills/otel/SKILL.md`](../skills/otel.md).
+The companion skill is [`skills/otel/SKILL.md`](../../skills/otel/SKILL.md).
 
 ## What spans does a session produce?
 
@@ -192,7 +180,7 @@ generic message (`turn failed` / `session failed`).
 
 Opt in with `OTEL_LOG_USER_PROMPTS=1` and `OTEL_LOG_TOOL_CONTENT=1`, or
 the matching `logs: { userPrompts, toolContent }` fields on
-`defineOtel`. Opted-in strings truncate at 2,048 characters.
+`serve({ otel })`. Opted-in strings truncate at 2,048 characters.
 
 Deployment URLs from `agent.bound` stay off spans unless
 `toolContent` is on.
@@ -223,14 +211,13 @@ another library already registered a TracerProvider, MeterProvider, or
 LoggerProvider, Agent SDK reuses it. Run `serve` as its own process
 when the Agent SDK exporters should own the destination.
 
-Two mounts with different `agent/otel.ts` files fail at serve start.
-Use the same `defineOtel` config on every mount, or configure once
-through `serve({ otel })` or env.
+Two mounts with different authored OTel configs fail at serve start.
+Configure once through `serve({ otel })` or env.
 
 ## What's next
 
-- [`skills/otel/SKILL.md`](../skills/otel.md): compact
-  `defineOtel` reference for coding agents
+- [`skills/otel/SKILL.md`](../../skills/otel/SKILL.md): compact
+  env / `serve({ otel })` reference for coding agents
 - [Hooks](../reference/hooks.md): observe the same session event stream
   in-process
 - [Deployment](../deployment.md): env, secrets, and self-hosting

package/docs/guides/slack.md

@@ -7,12 +7,13 @@ description: "Run a Socket Mode Slack bot from the dashboard wizard, or import a
 
 The Slack channel is a Socket Mode bot. The app connects out, so you
 don't need a public Request URL. Mentions and DMs start a thread.
-Replies stream there, with thinking steps and suggested prompts.
+Replies land in that thread. You choose the status chip, a live
+stream, or agent-owned posts.
 
 Use `agent-sdk slack create` when Cursor should own the Slack app. Use
 `agent-sdk slack init --manual` when you own it. Commands and flags live
 in the [CLI reference](../reference/cli.md#slack). Coding agents should
-follow [`skills/setup-slack/SKILL.md`](../skills/setup-slack.md).
+follow [`skills/setup-slack/SKILL.md`](../../skills/setup-slack/SKILL.md).
 
 ## Define the channel
 
@@ -61,7 +62,7 @@ Slack gives an agent two places to show progress while a turn runs: the
 status chip under the thread ("Running grep…") and the reply message
 itself. It won't fill both at once. While a message is streaming, Slack
 shows its own "is working…" chip and hides any status text you set. Cards
-only exist inside a streamed message. `reply.mode` picks which one you get.
+only exist inside a streamed message. `reply.mode` picks the path.
 
 ### `post` (default): status chip, then one message
 
@@ -123,6 +124,54 @@ and `output(result)` the text to add when it finishes.
 `toolLabels` renames tools everywhere they appear: the chip, card titles,
 and the default `Running …` line.
 
+### `agentic`: the agent posts
+
+Opt in when the agent should own every message in the thread. Mentions
+and DMs still start turns. The channel does not write the status chip,
+tool cards, reasoning cards, or assistant text. Approval cards
+still post if you set `toolApprovals`.
+
+Mount `@cursor/july/extensions/slack-communication` so the agent can
+talk. The extension adds typed tools and the `slack-voice` skill. The
+channel watches those tool names (bare or `<namespace>__<name>`) and
+calls Slack through the channel client after a successful result. A
+rejected call, a dry-run stub, or a turn that never calls
+`post-update` stays silent. The framework does not also finalize
+assistant text.
+
+```ts
+// agent/extensions/slack.ts
+import slackCommunication from "@cursor/july/extensions/slack-communication";
+
+export default slackCommunication();
+```
+
+```ts
+// agent/channels/slack.ts
+export default slackChannel({
+  reply: { mode: "agentic" },
+});
+```
+
+| Tool | What it writes | Scope |
+| --- | --- | --- |
+| `post-update` | Mid-turn progress and the final reply (`chat.postMessage` / `chat.update`) | `chat:write` |
+| `post-card` | Collapsible task card (`chat.startStream` / `chat.appendStream`) | `chat:write` |
+| `post-file` | Workspace file on the reply (`files.getUploadURLExternal`) | `files:write` |
+| `react` | Emoji on a message `ts` (`reactions.add`). Omit `ts` for the thread root. | `reactions:write` |
+| `set-status` | Subtitle chip (`assistant.threads.setStatus`). Empty string clears it. | `assistant:write` |
+
+`agent-sdk slack create` already grants those scopes. Do not add a
+freeform Slack method tool.
+
+Pass `tone` to add agent-specific voice without forking the tools:
+
+```ts
+export default slackCommunication({
+  tone: "Lead with the merge decision. Name the risk next.",
+});
+```
+
 ### Migrating from `streaming` and `thinkingSteps`
 
 `streaming: false` is `reply: { mode: "post" }`. `streaming: true` is
@@ -267,7 +316,7 @@ The Slack app needs interactivity. Recreate it with `slack create` if
 clicks do nothing. Cards show redacted, truncated arguments. Execution
 still uses the full input, so review sensitive tools in the playground
 when the card may hide fields. The lifecycle is in
-[Human-in-the-loop](./human-in-the-loop.md).
+[Gate a tool on human approval](../reference/tools.md#gate-a-tool-on-human-approval).
 
 ## Run several agents on one host