@cursor/july 0.1.96 → 0.1.97

package/dist/docs/llms-full.txt

@@ -693,9 +693,10 @@ use `UPPER_SNAKE_CASE`. Commit names only; set their values after
 creating the deployment. Names beginning with `CURSOR_` are reserved.
 
 For `defineConnection({ url, oauth: true })`, declare
-`MCP_OAUTH_<CONNECTION>_*` in `secretNames`, authorize with
-`agent-sdk mcp oauth <connection> --store`, then redeploy. See
-[Host MCP OAuth](/docs/guides/mcp-oauth.md).
+`MCP_OAUTH_<CONNECTION>_*` in `secretNames`. Finish Connect for the
+current process. Run `agent-sdk mcp oauth <connection> --store` and
+redeploy so the next pod sees the secrets.
+See [Host MCP OAuth](/docs/guides/mcp-oauth.md).
 
 Run `agent-sdk validate` before deploying. It reports invalid domains and
 secret names as warnings, so fix them even when validation exits zero.
@@ -943,7 +944,7 @@ A self-hosted server can read these credentials.
 | Slack tokens | Slack channels | `<PREFIX>_SLACK_BOT_TOKEN` + `<PREFIX>_SLACK_APP_TOKEN` per agent |
 | GitHub webhook secret | delivery signature verification | `GITHUB_WEBHOOK_SECRET`, same value on server and signer |
 | GitHub API | outbound API calls | a GitHub App (`GITHUB_APP_ID` + `GITHUB_APP_PRIVATE_KEY` + installation id) or `GITHUB_TOKEN` / `gh auth login` |
-| MCP connection tokens | authored MCP connections | env vars your `mcp-connections/*.ts` read, or host OAuth secrets from `agent-sdk mcp oauth <name> --store` (`MCP_OAUTH_*`; see [Host MCP OAuth](/docs/guides/mcp-oauth.md)) |
+| MCP connection tokens | authored MCP connections | env vars your `mcp-connections/*.ts` read, or host OAuth secrets from hosted Connect / `agent-sdk mcp oauth <name> --store` (`MCP_OAUTH_*`; see [Host MCP OAuth](/docs/guides/mcp-oauth.md)) |
 
 Use a dedicated Cursor key per host. `agent-sdk whoami` shows the active
 credential. `logout` removes the stored key from the host; revoke the key
@@ -1087,417 +1088,6 @@ Continue with these pages:
 
 ---
 
-Source: /docs/design/agsh.md
-
-# agsh: a shell for deployed agents
-
-## What this is
-
-`agsh` (agent shell) is a standalone CLI that connects to one agent-sdk
-deployment and turns the agent's live tool surface into commands. Every tool
-the deployment can execute (authored server tools and tools provided by the
-agent's MCP connections) becomes a subcommand with a synopsis derived from its
-input schema, a man-page style `--help`, and a place in an interactive shell.
-
-It is a separate binary and a separate package from `agent-sdk`. The
-`agent-sdk` CLI stays what it is today: the developer workflow tool for
-authoring, validating, deploying, and debugging agent projects. `agsh` is the
-operator's tool for working *inside* one deployed agent. The split also keeps
-heavy presentation dependencies (markdown rendering, syntax highlighting, the
-shell interpreter) out of `@cursor/july`, which ships to every agent project.
-
-## The experience
-
-```
-$ agsh help                        # list of commands, man-page style
-$ agsh read --help                 # man-page style: NAME, SYNOPSIS, DESCRIPTION, OPTIONS
-$ agsh read /repo/README.md
-$ agsh datadog_list_monitors --query "service:api"
-$ agsh                             # bare: interactive shell on a TTY, script from stdin otherwise
-❯ ls /repo | grep -i readme
-❯ read /repo/config.json | jq .version
-```
-
-Every invocation binds to the deployment's latest session by default, with
-`--session` and `--continuation-token` overrides, and prints the session
-identifier as a final stderr line.
-
-## Configuration
-
-`agsh` is a client only; it never boots an agent. Every invocation needs a
-target deployment, given by flags or by environment variables. Flags always
-win over the environment.
-
-Global command line options, accepted on every command and on the bare shell
-launch:
-
-| Option | Environment default | Meaning |
-| --- | --- | --- |
-| `--target <url \| name>` | `AGENT_SHELL_TARGET` | The deployment to talk to: a URL is a local deployment (`http://127.0.0.1:39400/executor`), a name a production one (`change-monitor-executor`). |
-| `--team <team>` | `AGENT_SHELL_TEAM` | Team override for production resolution, when the login spans several. |
-| `--bearer-token <token>` | `AGENT_SHELL_BEARER_TOKEN` | Explicit bearer auth for a deployment that is not behind the Cursor login. |
-| `--session <id>` | | Bind to a specific session instead of the latest. |
-| `--continuation-token <token>` | | Bind by continuation token instead of session id. |
-| `--output <text\|json>` | | Result rendering: human-friendly views (default) or raw JSON. |
-| `-h`, `--help` | | Per-command help. |
-
-One parameter carries the whole target selection, and the value's shape
-encodes the mode: a URL (`http://` or `https://`) targets a local
-deployment, anything else names a production one. Two options with a
-precedence rule would invite exactly the confusion a target selector must
-not have; with one parameter the only rule is that the flag beats the
-environment. A URL is self-contained down to the agent because one local
-agent-sdk serve process hosts every agent of the project (change-monitor's
-dev stack mounts `/executor` and `/planner` from a single port); a
-production deployment is a single agent, so its name is the complete
-address (`--team` narrows resolution when the login spans several).
-Authentication defaults to the stored Cursor login (the same engine-access
-credential agent-sdk uses); `--bearer-token` is the escape hatch for direct
-deployments. Session flags are per invocation and have no environment
-default: a session is state, not configuration. Color output follows the
-`NO_COLOR` convention and TTY detection; there is no agsh-specific color
-setting. No configuration file: one environment variable pins a working
-target for a terminal session
-(`AGENT_SHELL_TARGET=change-monitor-executor`, or a URL for a local stack),
-which is the whole persistent-configuration need.
-
-With no target from flags or environment, every command fails with a message
-naming both ways to provide one.
-
-## Architecture
-
-### A new package
-
-A new workspace package (working name `packages/agsh`, bin `agsh`) that
-depends on `@cursor/july` for target resolution, stored Cursor login, and the
-HTTP client plumbing. It owns the presentation stack: `marked` for terminal
-markdown (moved out of `@cursor/july`), with syntax highlighting (`shiki`)
-arriving in the phase that renders code; the shell interpreter is
-purpose-built (see Rationale).
-No new abstraction seam between the two packages; `agsh` imports what it
-needs until a second consumer justifies extracting a thin client.
-
-### The tool catalog
-
-At startup `agsh` fetches one live catalog of everything invocable on the
-deployment. This is the piece the current `/v1/info` cannot provide: `/v1/info`
-projects the authored manifest, and connection tools only exist at runtime,
-resolved per session under the connection's auth. A new endpoint provides the
-live view (see Backend changes).
-
-Catalog entries carry exactly one identifier each: the tool name exactly as
-the agent sees it. Authored server tools keep their authored name (`read`).
-Connection tools appear under their model-facing advertised name (the
-sanitized passthrough name from `advertise-tools.ts`, e.g.
-`datadog_list_monitors`). The CLI never invents a different naming format:
-a tool name copied from a session transcript is a valid `agsh` command, and
-vice versa. Where a tool came from — the upstream connector name when the
-tool declares one, the connection name otherwise — is a field on the
-catalog entry, not part of the identifier.
-
-### Two command tiers
-
-Each catalog entry becomes a command, through one of two shapes:
-
-**Curated commands for builtin tools.** The well-known tool names (`ls`,
-`read`, `grep`, `glob`, `diff`, ...) get hand-designed, POSIX-flavored
-command shapes, hardcoded in `agsh` next to their titles. These tools are
-what an operator types all day; their shapes should feel like the unix
-commands they mirror, not like generated bindings. A curated shape decides
-which schema fields are positional operands and which are flags, and every
-input has exactly one spelling: an operand is only an operand, never also a
-flag.
-
-```
-$ agsh read /repo/package.json --limit 2
-{
-  "name": "change-monitor",
-→ ses_a99d1b69c329eb75a2ec8603
-
-$ agsh grep -i -A 2 toolEffect /repo/src
-src/tool-policy.ts:12:export type ToolEffect = "read" | "write";
-...
-→ ses_a99d1b69c329eb75a2ec8603
-
-$ agsh ls /repo --ignore-globs '*.test.ts' --ignore-globs 'node_modules/**'
-```
-
-`read` takes its path as an operand mapped to the schema's `path` field, with
-`--offset` and `--limit` as integer flags. `grep` follows POSIX grep:
-`grep [options] <pattern> [path]`, with the rg-style options (`-i`, `-A`,
-`-B`, `-C`, `--output-mode`, `--head-limit`) mapping onto the schema fields
-of the same names (kebab-cased). `ls` shows array input: an array field's flag repeats once
-per element. A curated shape binds to the deployment's live schema at
-startup; when a deployment's tool lacks the expected field, the command
-degrades to the generic shape below rather than guessing.
-
-A curated shape may also reformat the tool's text result toward the unix
-command's own output conventions: the VFS ls tool returns the model-facing
-tree (`  - name/` rows under a header), and `agsh ls` prints it as standard
-ls does, one name per line with the trailing slash kept on directories. The
-tool's result string itself stays what the model sees; when a result does
-not match the expected shape it prints verbatim.
-
-**Generated commands for MCP tools.** Connection tools are dynamically
-discovered, so no special treatment is possible; they get a uniform
-schema-derived mapping:
-
-- Every schema property is accepted as one flag, spelled as the
-  kebab-cased property name (`org_slug` → `--org-slug`) — the unix
-  convention; kebab collisions gain a numeric suffix. Properties already
-  shaped like flags (grep's `-i`) stay literal. No positionals, no other
-  aliases.
-- Object-typed properties flatten recursively into one flag per leaf,
-  dash-joined (`--telemetry-context` for `telemetry.context`), so every
-  option reads as a plain value; a free-form object with no declared
-  properties stays one JSON-valued flag. A leaf is required only when its
-  whole ancestor chain is.
-- Values are coerced by schema type: booleans are valueless flags, numbers
-  and integers are parsed, arrays accept the flag repeated once per element,
-  enums are validated before the call.
-
-```
-$ agsh datadog_list_monitors --query "service:api" --limit 10
-```
-
-In both tiers `-h`/`--help` and the global target and session flags are
-reserved and injected, a flag that names no schema property fails before any
-request (listing the tool's actual properties), and the bound session prints
-as a final stderr line.
-
-### Result rendering
-
-Raw JSON on a terminal is not an experience for people, so `--output=text`
-(the default) renders structured results through a small set of views,
-selected automatically by the shape of the value each call actually returned;
-tool metadata plays no part, since most tools advertise no output schema, and
-many return structured data as JSON text. A string result that parses as a
-JSON object or array counts as structured. An array of objects renders as a
-table (columns are the union of keys, missing cells stay blank, the table
-clamps to the terminal width); a single object renders as a property view
-(aligned keys, scalar lists as bullets, nested structures indented); an
-object that is nothing but an error wrapper renders as an `Error:` line;
-plain text prints verbatim. `--output=json` renders the structured value as
-raw JSON. The rendering never depends on the TTY: piped and interactive
-output carry the same content, only color follows TTY detection.
-
-### Help rendering
-
-`--help` on a tool renders a man-page layout: NAME (the tool name, with the
-tool's `title` beside it when the catalog carries one; titles are curated
-data, never derived from the description), SYNOPSIS (operands from the
-curated shape; options never enumerate — they summarize as `[options...]`,
-man-page style, so the line stays bounded), DESCRIPTION (the tool
-description rendered as terminal markdown), OPERANDS (positional arguments,
-curated commands only), and OPTIONS. Descriptions of operands and options
-come from the schema's property descriptions. Effect and approval metadata
-render as notes when declared. Everything except the curated shape derives
-from `GET /v1/tools/:name`; nothing else is hand-written per tool.
-
-```
-$ agsh read --help
-NAME
-    read - Read a file
-
-SYNOPSIS
-    read [options...] <path>
-
-DESCRIPTION
-    Reads a file from the local filesystem. This tool can also read image
-    files when called with the appropriate path. Formats supported:
-    jpeg/jpg, png, gif, webp.
-
-OPERANDS
-    <path>
-        The absolute path of the file to read.
-
-OPTIONS
-    --offset <integer>
-        The line number to start reading from. Positive values are 1-indexed
-        from the start of the file. Negative values count backwards from the
-        end. Only provide if the file is too large to read at once.
-
-    --limit <integer>
-        The number of lines to read. Only provide if the file is too large
-        to read at once.
-
-NOTES
-    Effect: read (performs no writes).
-```
-
-`agsh help` lists the available command names grouped by source, authored
-tools first, then one group per upstream connector (its name is the group
-header — one aggregating connection can host tools from several connectors,
-and the connector name is what an operator recognizes). Each row is the
-name, with the title beside it when the tool declares one; everything else
-lives behind the command's `--help`:
-
-The agent's description renders as a DESCRIPTION section when the deployment
-declares one (`/v1/info` carries both name and description).
-
-```
-$ agsh help
-NAME
-    change-monitor-executor
-
-DESCRIPTION
-    Executes monitoring plans against changed code.
-
-COMMANDS
-    diff                     Show workspace changes
-    glob                     Find files by pattern
-    grep                     Search file contents
-    ls                       List a directory
-    read                     Read a file
-    report_change_issue
-    report_change_succeeded
-
-DATADOG
-    datadog_list_monitors    List monitors
-    ...
-
-Run any command with --help for its synopsis and options.
-```
-
-### Shell mode
-
-Invoked bare, `agsh` starts a shell. On a TTY this is a REPL; on a pipe it
-reads a script from stdin, so `echo 'ls /' | agsh` and here-docs work.
-
-The interpreter is purpose-built and minimal: tokenizing (quotes, escapes),
-pipelines, and `;` / `&&` / `||`. The command namespace is exactly the
-deployment's tool catalog plus a small curated set of local pipe filters
-(`head`, `tail`, `wc`, stdin-filtering `grep`), so a tool name can never be
-shadowed. There is no local filesystem, no variables, no control flow: agsh
-has nothing local to operate on, and every command is a single traced
-`POST /v1/tools/:name` call.
-
-The shell binds one session identity at launch (latest by default) and keeps
-it for the whole run, so a sequence of tool calls observes one consistent
-session context.
-
-## Backend changes on the agent-sdk runtime
-
-Two read endpoints, mirroring the invocation path:
-
-**`GET /v1/tools`: the live tool listing.** Returns the session's tool
-namespace exactly as a turn would assemble it: authored server tools plus the
-advertised passthrough tools synthesized from connections, under their
-model-facing names. Entries are light (name, source, and `title` when one is
-known); everything else lives behind the detail endpoint. Titles have two
-sources and no new authoring surface: connection tools inherit the upstream
-server's MCP title, which the host already propagates length-capped off
-listings; tools that do not come from MCP get theirs from a hardcoded
-name-to-title table in the runtime's endpoint implementation, covering the
-well-known tool names. A tool in neither place has no title. Accepts the same
-optional session binding as invocation (`session` or `continuationToken`)
-because advertised inventories can be tenant-scoped and resolved per session.
-Implementation reuses the existing plumbing: the discovered manifest for
-authored tools and the advertise-tools synthesis (`McpHost.listTools`, or the
-`oneOff` path when per-session auth substitution applies) for connection
-tools. This is not a duplicate of `/v1/info`: the info document stays the
-static authored manifest; the listing is the runtime view that only the
-running deployment can answer.
-
-**`GET /v1/tools/:name`: one tool's full description.** Description, input
-schema, output schema when declared, effect when declared, approval
-requirement, and source connection. Same path as invocation
-(`POST /v1/tools/:name`), different method: GET describes what POST executes,
-for the same identifier.
-
-Invocation needs no new naming scheme. Advertised connection tools are
-synthesized as ordinary server tools in the session's namespace, so
-`POST /v1/tools/:name` addresses them by their model-facing name like any
-authored tool, with the same session binding, policy checks, and per-call
-tracing. (The direct-call path did need the synthesis step added: it now
-resolves the advertised listing for the call's session identity when the
-authored lookup misses.)
-
-Phase 1 ships the minimal runtime surface agsh calls: the `effect`
-projection in `/v1/info` (rendered in per-tool help), the scratch-workspace
-fallback on direct calls, and `continuationToken` binding on
-`POST /v1/tools/:toolName`. The detail endpoint in phase 2 also closes the
-output-schema gap; `/v1/info` stays as it is.
-
-## Local development loop
-
-`factory/change-monitor` is the test bed. Its `pnpm start` already serves the
-planner and executor locally through the agent-sdk dev runtime
-(`agent-sdk serve --dir . --dev`). The loop:
-
-1. `cd factory/change-monitor && pnpm start` (local stack, both agents).
-2. `agsh --target http://127.0.0.1:<port>/<agent>` against it, via a dev shim
-   analogous to `agent-sdk-dev` so the CLI runs from the worktree.
-3. Iterate end to end: VFS verbs (`ls`, `read`, `grep`, `glob`, `diff`) for the
-   authored-tool path, and the planner's tenant connectors for the
-   connection-tool path once `GET /v1/tools` exists.
-
-## Removing the inspector surface from agent-sdk
-
-The inspector CLI is still on development branches, so nothing migrates: the
-CLI-side code is removed from `agent-sdk` and `agsh` is built in its place.
-
-- The verb commands (`ls`, `read`, `grep`, `glob`, `diff`) become the
-  curated tier: their hand-designed shapes, schema-binding logic (including
-  the candidate-field fallback), and session binding carry over. The
-  schema-to-argv flag mapping seeds the generated tier for MCP tools.
-- The `tools` and `skills` commands disappear entirely. `agsh help` and
-  per-tool `--help` are the discovery surface.
-- `marked` and `shiki` leave `@cursor/july`; agsh's help rendering takes
-  `marked`, and `shiki` returns when agsh ships syntax highlighting.
-  `agent-sdk` keeps its developer workflow commands unchanged.
-
-## Plan
-
-1. **Package and core invocation.** Create the package, port target
-   resolution, the schema-to-argv mapping, and help rendering from the
-   inspector code. Authored tools only, against the existing endpoints.
-   Verified end to end on the local change-monitor stack.
-2. **Live catalog.** Add `GET /v1/tools` and `GET /v1/tools/:name` to
-   the agent-sdk runtime, with the hardcoded title table for non-MCP tools, and verify
-   direct invocation resolves advertised connection tools by their
-   model-facing names. Connection tools appear as commands. Verified against
-   the planner's connectors.
-3. **Shell mode.** The purpose-built mini-shell: REPL on TTY, script on
-   stdin, tools as the command namespace, one session per shell run.
-4. **Cleanup.** Remove the inspector CLI surface and presentation
-   dependencies from `@cursor/july`.
-
-## Rationale and rejected alternatives
-
-**Why not extend `agent-sdk`.** The audiences differ: `agent-sdk` is for the
-person building and deploying an agent; this tool is for the person operating
-inside one. Bundling also forces every agent project to carry markdown
-rendering, syntax highlighting, and a bash interpreter it never uses.
-
-**Name.** `agsh` reads as "agent shell", is four characters, collides with
-nothing common, and works as a shell prompt name. Considered: `august`
-(pairs with `july` but says nothing about purpose), `toolsh` (awkward to
-pronounce), `cursor-shell` (too broad; this is scoped to one agent).
-
-**Why a REST catalog instead of the MCP endpoint.** The deployment already
-speaks MCP at `/v1/mcp/tools`, including a per-connection bridge, but the
-bridge is bound to an active turn and speaks JSON-RPC. The CLI wants a plain
-authenticated GET with session binding that returns the assembled tool
-namespace under the names the model sees. Wrapping that in MCP framing buys
-nothing for a first-party client.
-
-**Why a purpose-built interpreter instead of just-bash.** just-bash was the
-original plan (a full bash emulation with a custom-command extension point),
-and a prototype disproved it: custom commands replace its coreutils but can
-never shadow its shell builtins, and `read`, `test`, `type`, and `help` are
-builtins — so the flagship `read` tool is unreachable, and the precedence is
-not ours to control (vercel-labs owns the package). No other embeddable JS
-shell interpreter has a workable custom-command story (mvdan-sh's JS build
-does not expose one; bash-parser is a parser only). agsh also needs almost
-none of bash: no local filesystem, no variables, no control flow — just
-tokenizing, pipelines, and a command namespace it fully owns. A TypeScript
-REPL with tools as async functions (the shape of change-monitor's `script`
-tool) was considered and kept as a possible later addition; it trades away
-the unix muscle memory the curated commands exist for.
-
----
-
 Source: /docs/evals.md
 
 # Evals
@@ -2795,8 +2385,9 @@ Source: /docs/guides/mcp-oauth.md
 Use host MCP OAuth when your agent talks to a remote MCP server that
 speaks OAuth, and you want credentials on the serve host (or the hosted
 engine) instead of a Cursor account connector. Local login writes tokens
-next to your Cursor credentials. `--store` copies them onto the
-deployment as secrets so prod can reconnect after a redeploy.
+next to your Cursor credentials. `--store` copies those tokens onto the
+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`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/mcp-auth/SKILL.md).
@@ -2807,8 +2398,8 @@ The companion skill is
   flow (`agent-sdk mcp oauth <connection>`)
 - Keep tokens in `mcp-auth.json` under the CLI config directory, bound
   to that connection's resource URL
-- Upsert deployment secrets with `--store` so hosted engines seed the
-  same tokens from env
+- Upsert deployment secrets with `--store` so the next deploy seeds the
+  same tokens from env. Hosted Connect lets the current process retry.
 - Use `advertiseTools: true` when local turns should call the server by
   name. Host tools can still call it through `ctx.host.mcp`.
 
@@ -2888,7 +2479,16 @@ connection URL (tokens are bound to the resource URL).
 
 ## How do I store credentials on a hosted deployment?
 
-Authorize once, then push secrets to the deployment:
+Authorize once. Then get the tokens onto the deployment.
+
+On a hosted engine, finishing Connect lets the current process retry.
+Self-hosted serve writes tokens locally only.
+
+`--store` from a signed-in laptop is the reliable way to put
+`MCP_OAUTH_*` on the next deploy. If `agent-sdk secrets list` is
+empty, run `--store` and redeploy.
+
+From a laptop, push secrets with the CLI:
 
 ```bash
 agent-sdk mcp oauth inventory --store
@@ -2906,13 +2506,21 @@ agent-sdk mcp oauth inventory --store
 | `MCP_OAUTH_<NAME>_CLIENT_ID` | dynamic client id when registration returned one |
 
 You must be signed in (`agent-sdk login`) with permission to set secrets
-on that slug. Secrets apply on the **next** deploy; run
-`agent-sdk deploy` (or wait for your usual deploy path) after `--store`.
+on that slug. Secrets apply on the **next** deploy. Run
+`agent-sdk deploy` after `--store`. A fresh pod sees `MCP_OAUTH_*`
+only after that deploy.
 
 On the engine, when `mcp-auth.json` is empty, serve seeds the OAuth
 provider from those env vars so host MCP calls work without a browser
 on the pod.
 
+These secrets are deployment-wide. Anyone who can list or set secrets
+on that slug, and the hosted engine's runtime env, can use them. That
+is the same blast radius as `--store`. They are not scoped to the
+caller who clicked Connect. `cursorAccount: true` tokens stay on the
+Cursor backend for the deployment service account and do not use
+`MCP_OAUTH_*`.
+
 ## How do host tools call the server?
 
 ```ts
@@ -2932,7 +2540,7 @@ an allowlist or other deterministic gate.
 | --- | --- |
 | `must be defineConnection({ url, oauth: true })` | Add `oauth: true` on that connection, or pick the right connection name |
 | Callback never completes | Keep port `8787` free; finish the browser login on this machine |
-| Hosted calls unauthorized after `--store` | Confirm secrets with `agent-sdk secrets list <slug>`, then redeploy |
+| Hosted calls unauthorized after Connect or `--store` | Confirm secrets with `agent-sdk secrets list <slug>`, then redeploy |
 | Tokens ignored after URL change | Expected: resource URL binding drops stale entries. Re-run `mcp oauth` |
 
 ## What's next
@@ -3162,16 +2770,14 @@ Source: /docs/guides/slack.md
 
 # Slack agents
 
-The Slack channel puts your agent in Slack as its own Socket Mode bot.
-`agent-sdk slack create` opens the dashboard wizard and writes tokens
-to `.env.local`. To own the Slack app yourself, run
-`agent-sdk slack init --manual` and paste the manifests at
-[api.slack.com](https://api.slack.com/apps). Socket Mode has no
-public Request URL. Replies stream in threads, with tool "thinking" steps,
-suggested prompts, and opt-in approval buttons.
+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.
 
-The companion skill is
-[`skills/setup-slack/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/setup-slack/SKILL.md).
+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](/docs/reference/cli.md#slack). Coding agents should
+follow [`skills/setup-slack/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/setup-slack/SKILL.md).
 
 ## Define the channel
 
@@ -3181,35 +2787,23 @@ Author `agent/channels/slack.ts` with `slackChannel()` from
 ```ts
 import { slackChannel } from "@cursor/july/channels/slack";
 
-// Single agent: reads SLACK_BOT_TOKEN + SLACK_APP_TOKEN
 export default slackChannel();
-
-// Multi-agent serve: one Slack app (and token pair) per agent
-export default slackChannel({ envPrefix: "WEATHER_AGENT" });
-// → WEATHER_AGENT_SLACK_BOT_TOKEN + WEATHER_AGENT_SLACK_APP_TOKEN
 ```
 
-By default the channel connects over Socket Mode (the app connects
-outward, so it works from behind any firewall) and responds only to
-`app_mention` events and direct messages. It also refuses Slack Connect
-users, guests, and senders from other workspaces. Threads bind to
-sessions with `continuationToken = channelId:threadTs`, so a thread is
-one durable conversation. Replies stream (`chat.startStream` /
-`appendStream` / `stopStream`) with a plain-message fallback, a rotating
-status shows while the agent works, and the pack sets thread titles and
-suggested prompts. When a Slack API is unavailable (`method_not_found`,
-`missing_scope`), the pack degrades to `postMessage` instead of failing.
+`slackChannel()` reads `SLACK_BOT_TOKEN` and `SLACK_APP_TOKEN`. Pass
+`envPrefix: "WEATHER_AGENT"` to read `WEATHER_AGENT_SLACK_BOT_TOKEN`
+and `WEATHER_AGENT_SLACK_APP_TOKEN` instead. Use a prefix when one
+host serves several Slack bots.
 
-Missing tokens leave the channel idle (`channel idle … missing
-credentials`) rather than failing `serve`. That's useful when you mount
-many agents and only some have Slack apps.
+A thread is one conversation. The bot answers mentions and DMs. It
+refuses Slack Connect users, guests, and people from other workspaces.
+Missing tokens leave this channel idle. The rest of `serve` still
+starts.
 
 ## Control who can message the agent
 
-External senders are blocked by default. Slack Connect users, guests, and
-people whose home workspace is not the install team never reach the
-handler. Set `blockExternals: false` only when the agent should serve
-people outside your org:
+External senders are blocked. Set `blockExternals: false` only when
+people outside your org should reach the agent:
 
 ```ts
 export default slackChannel({
@@ -3217,9 +2811,8 @@ export default slackChannel({
 });
 ```
 
-Sessions are thread-scoped by default, so anyone in the thread can
-continue. Restrict follow-ups to the person who started the session with
-`respondTo: "author"`:
+Anyone in the thread can continue it. Restrict follow-ups to the person
+who started the session with `respondTo: "author"`:
 
 ```ts
 export default slackChannel({
@@ -3229,237 +2822,143 @@ export default slackChannel({
 
 ## Set it up
 
-For a dedicated Socket Mode bot, run `agent-sdk slack create`. The CLI
-opens the signed-in Cursor dashboard wizard. Slack consent, bot name,
-and admin-approval wait happen there. Tokens are stored as deployment
-secrets and written to `.env.local`. They are never shown. Do not paste
-a manifest at [api.slack.com](https://api.slack.com/apps) unless you
-are on the [manual setup](#manual-setup) path.
-
-Bots that already have tokens in `.env.local` keep working. Skip the
-wizard unless you want a Cursor-managed app.
+`slack create` opens the Cursor dashboard wizard. Finish Slack consent
+and the bot name there. The CLI writes tokens to `.env.local` and never
+prints them. Skip the wizard if those tokens are already set, unless
+you want a Cursor-managed app.
 
 ### Provision with the CLI
 
 ```bash
-agent-sdk slack create --dir .          # dev app (default)
-agent-sdk slack create --dir . --prod   # prod app
+agent-sdk slack create --dir .
+agent-sdk slack create --dir . --prod
 ```
 
-`slack create` needs a signed-in host (`agent-sdk login` or
-`CURSOR_API_KEY`). It scaffolds `agent/channels/slack.ts` when the file
-is missing, opens the dashboard wizard, and waits. Finish **Add Slack
-to this agent** in the browser as the same Cursor account. The CLI
-writes `<PREFIX>_SLACK_BOT_TOKEN` and `<PREFIX>_SLACK_APP_TOKEN` into
-`<dir>/.env.local`, then runs `doctor`. Serve and smoke it as described
-[below](#wire-the-env-and-verify).
+Sign in first (`agent-sdk login` or `CURSOR_API_KEY`). Finish **Add
+Slack to this agent** as the same Cursor account. Then run
+`agent-sdk slack doctor --prefix MY_AGENT` and serve:
 
-If Slack needs a workspace admin to approve the app, keep the CLI
-running. Managed install does not file the request. Open Slack's
-**Request approval** page (the CLI prints the link; the same URL is
-**Send a reminder** after you submit). After an admin approves, click
+```bash
+agent-sdk serve --dir . --dev
+```
+
+Invite the bot and mention it, or DM it. Expect a Thinking status,
+then a threaded streaming reply.
+
+If Slack needs a workspace admin, keep the CLI running. Open the
+**Request approval** link it prints. After an admin approves, click
 **Retry** in the wizard.
 
-Useful companions: `--name` / `--icon` / `--channel-posts` prefill the
-wizard. `--slack-team T0123ABCD` picks a workspace when several are
-connected. A second `slack create` for the same agent and env overwrites
-that Slack app. It keeps the Slack app id and replaces the manifest and
-tokens. `agent-sdk slack destroy` deletes the provisioned app.
-`agent-sdk slack icon <source>` updates the icon later.
+`slack destroy` deletes the Cursor-managed app. `slack icon` updates
+its icon. A second `slack create` for the same agent and environment
+replaces that app's manifest and tokens.
 
 ### Provision from the dashboard
 
 The same wizard is on [Deployed Agents](https://cursor.com/dashboard).
-Open **Integrations** on an agent and click **Add Slack to this agent**,
-or follow the URL `slack create` printed.
+Open **Integrations** and click **Add Slack to this agent**.
 
-A first-run agent that has no hosted engine yet shows **Not deployed
-yet**. Local `agent-sdk serve` works from `.env.local`. The next
-**Deploy** injects the stored secrets; there is no Slack-only Redeploy.
+Local `agent-sdk serve` reads `.env.local`. The next deploy injects the
+stored secrets.
 
-If Slack needs admin approval, the wizard waits. Click **Request
-approval** to file the request in Slack (that same page later sends a
-reminder). After an admin approves, click **Retry**.
+If Slack needs admin approval, click **Request approval**, then
+**Retry** after an admin approves.
 
-The app row's menu covers later care: rename, set an icon, rotate
-tokens, remove the app, or disconnect the workspace.
+The app row's menu covers rename, icon, token rotation, removal, and
+workspace disconnect.
 
-### Wire the env and verify
+### Create your own Slack app
 
-`agent-sdk slack create` already wrote the tokens to `.env.local`, so
-after provisioning skip straight to `doctor`. `serve` / `dev` /
-`slack doctor` load that file (real environment variables always win).
+`slack init --manual` is for an app you own. It writes the channel file
+and Slack manifests. When Slack CLI (`~/.slack/bin/slack`) is logged
+in, it installs the app. When it isn't, install the app yourself.
 
 ```bash
-agent-sdk slack doctor --prefix MY_AGENT
-```
-
-Proceed when `app_token`, `connections_open`, `bot_token`, and
-`auth_test` are all green. Then serve and smoke it:
-
-```bash
-agent-sdk serve --dir . --dev
-# expect: [agent-sdk/slack] Socket Mode connected
+agent-sdk slack init --manual --dir . --name "My Agent"
 ```
 
-Invite the bot to a channel and @mention it (or DM it). Expect the
-Thinking… status, then a threaded streaming reply, with correlated
-server logs (`inbound kind=app_mention`, `session start`,
-`reply delivered via stream|postMessage`).
-
-### Manual setup
-
-`slack init --manual` is for a Slack app you own at api.slack.com. You
-paste the generated manifests and mint tokens yourself. Use this when
-you want an unmanaged app, or when the dashboard wizard is not an
-option.
+Install Slack CLI if you need it:
 
 ```bash
-agent-sdk slack init --manual --dir . --name "My Agent"
+curl -fsSL https://downloads.slack-edge.com/slack-cli/install.sh | bash
 ```
 
-That writes `agent/channels/slack.ts`, Slack manifests under the
-project state directory, `env.example`, and `setup-status.json`.
-`--no-prefix` uses shared `SLACK_*` variables on
-a single-agent host. `--prefix CUSTOM` overrides the directory-derived
-prefix. `--channel-posts` subscribes the manifests to channel-post
-events.
+Log in with `slack login --no-prompt`. In Slack, send
+`/slackauthticket <ticket>`, then
+`slack login --ticket <ticket> --challenge <code>`. Install the
+workspace app with `slack app install`. Create a separate production
+app the same way.
 
-`slack manifest --env both` regenerates the JSON files without
-touching the channel file.
+Or paste `.slack/manifest.dev.json` at
+[api.slack.com/apps](https://api.slack.com/apps) (**Create New App** →
+**From a manifest**). Repeat with `.slack/manifest.prod.json`. Dev and
+prod are separate Slack apps.
 
-#### Create the apps
+Then put a bot token (`xoxb-...`) and an app-level token with
+`connections:write` (`xapp-...`) in `.env.local`. Use the names
+`slack init --manual` printed. Run `slack doctor` and serve as above.
 
-This phase needs someone with permission to create Slack apps.
-
-1. Open [api.slack.com/apps](https://api.slack.com/apps) → **Create New
-   App** → **From a manifest**.
-2. Paste `manifest.dev.json` and create the dev app.
-3. Repeat with `manifest.prod.json`. Dev and prod are separate Slack
-   apps with separate tokens.
-
-#### Install and mint tokens
-
-For each app: **Install to Workspace** and copy the Bot User OAuth Token
-(`xoxb-…`). Then under **Basic Information → App-Level Tokens** create a
-token with scope `connections:write` and copy it (`xapp-…`).
-
-Put the pair in `.env.local` using the names from `env.example`, then
-run `slack doctor` and serve as [above](#wire-the-env-and-verify).
+Serve this app with Agent SDK. Do not run `slack deploy`.
 
 ## Choose when the agent engages
 
-Mentions and DMs are on by default. Watching channels means dispatching
-on new posts without a mention. That's an explicit opt-in:
+Mentions and DMs are on. Watching channel posts without a mention is
+opt-in:
 
 ```ts
 export default slackChannel({
   envPrefix: "TRIAGE",
   engagement: {
-    // mentions / directMessages default to true
     channelPosts: {
-      allow: ["#triage-alerts"], // use ["*"] for every joined channel
-      posts: "top-level",       // default: thread replies never dispatch
-      debounceMs: 15_000,       // optional: let rapid edits settle
-      includeBotPosts: false,   // default: bot-authored posts never dispatch
+      allow: ["#triage-alerts"],
+      posts: "top-level",
+      debounceMs: 15_000,
     },
   },
-  onChannelPost: async (ctx, message) => {
-    // same contract as onAppMention: return null to skip
+  onChannelPost: async (_ctx, message) => {
     return message.markdown.length > 20 ? {} : null;
   },
 });
 ```
 
-Channel watching needs the `message.channels` / `message.groups` events
-on the Slack app. Pass `--channel-posts` on `slack create` or
-`slack init --manual`. The bot must also be a member of each watched
-channel.
-
-Set `allow: ["*"]` to watch every channel the bot has joined.
+Pass `--channel-posts` on `slack create` or `slack init --manual` so
+the Slack app receives those events. The bot must be in each watched
+channel. `allow: ["*"]` watches every joined channel.
 
-Set `includeBotPosts: true` when the posts worth watching come from bots:
-alert feeds, webhook integrations, or other agents posting notes. The
-watching app's own posts stay dropped either way, matched by the `bot_id`
-and bot user id from `auth.test`, so an agent can never dispatch on its
-own replies. Use this for a bot-fed alerts channel.
+Set `includeBotPosts: true` for alert feeds and other bots. This app
+never wakes on its own posts.
 
 ## Prepare work on the host
 
 Mention and DM handlers may return a prepared `message`,
-`workspaceFiles`, or `cloud` block. It's the same host-prep pattern as
+`workspaceFiles`, or `cloud` block. Use the same host-prep pattern as
 [custom channels](/docs/guides/webhooks.md#prepare-on-the-host-then-hand-off).
-PR agents use it: extract a PR URL from the mention text and run the
-same host path as the HTTP channel.
 
-Slack file uploads are attached automatically. Images become vision input.
+Slack file uploads attach automatically. Images become vision input.
 Supported documents become workspace files for the turn.
 
 ## Add approval buttons
 
-Tools with `needsApproval` park until a person decides. Route that
-through Slack with one flag:
+Tools with `needsApproval` park until a person decides. Post those
+decisions in Slack with one flag:
 
 ```ts
 export default slackChannel({
-  toolApprovals: true, // posts Block Kit Approve/Deny cards + routes clicks
+  toolApprovals: true,
 });
 ```
 
-Approval cards need interactivity on the Slack app. Recreate with
-`slack create` if clicks do nothing. Composing events by hand: spread
-`buildToolApprovalEvents({ credentials })` into `events` and set
-`interactivity: true` on the channel so Socket Mode routes the clicks.
-
-Cards show redacted, truncated arguments (Block Kit size limits);
-execution still uses the full validated input, so review sensitive tools
-in the playground when the arguments may exceed the card. Approvals
-exist for `execution: "server"` tools on the local runtime only, and
-parked calls do not survive a host restart. The full lifecycle is in
+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](/docs/guides/human-in-the-loop.md).
 
 ## Run several agents on one host
 
-One Slack app and token pair per agent. Never share a pair across
-agents in the same process. `envPrefix` keeps them apart
-(`WEATHER_AGENT_SLACK_*`, `TRIAGE_SLACK_*`, …), and agents without tokens mount
-with their Slack channel idle while everything else serves normally.
-
-## Keep the channel healthy
-
-Two habits matter most.
-
-- Don't `await` long work inside Slack dispatch handlers. The pack
-  dispatches through `waitUntil` and streams as the turn progresses.
-- In `--dev` (loopback) or `--allow-anonymous` (trusted shared host), the
-  playground can list and stream Slack sessions and resolve their parked
-  approvals (the audit trail records the HTTP caller). Bearer-auth hosts
-  stay strict: Slack approvals must come from Slack interactivity or a
-  matching principal.
-
-## CLI reference
-
-The `slack` subcommands cover setup end to end.
-
-```bash
-agent-sdk slack setup                     # printed setup guide
-agent-sdk slack create --dir .            # dashboard wizard (dev app)
-agent-sdk slack create --dir . --prod     # prod app
-agent-sdk slack destroy --dir .           # delete the provisioned app
-agent-sdk slack icon ./icon.png --dir .   # set the provisioned app's icon
-agent-sdk slack init --manual --dir .     # manifests to paste at api.slack.com
-agent-sdk slack manifest --env both       # regenerate those JSON files
-agent-sdk slack doctor --prefix MY_AGENT  # token / connectivity checks
-```
-
-## What's next
-
-Continue with these pages:
-
-- [Human-in-the-loop](/docs/guides/human-in-the-loop.md): the approval lifecycle
-  behind `toolApprovals`
-- [Webhooks and custom channels](/docs/guides/webhooks.md): the mechanism this
-  pack is built on
+Give each agent its own Slack app and token pair. Set `envPrefix` so
+the names don't collide (`WEATHER_AGENT_SLACK_*`, `TRIAGE_SLACK_*`).
+Agents without tokens stay idle. The others still serve.
 
 ---
 
@@ -4058,7 +3557,7 @@ npx @cursor/july docs
 | Building a new agent with Cursor | [Scaffold an agent with Cursor](/docs/scaffolding-agents.md) |
 | Turning a Cursor Automation into a project | [Convert a Cursor Automation](/docs/guides/convert-automation.md) |
 | Wiring an agent to Slack | [Slack guide](/docs/guides/slack.md) |
-| Starting from a packaged template | [Demo](/docs/templates/demo.md), [Code wiki](/docs/templates/code-wiki.md), [Security reviewer](/docs/templates/security-reviewer.md), [Security help](/docs/templates/security-help.md), [Triage](/docs/templates/triage.md), or [Agentic Owners](/docs/templates/agentic-owners.md) |
+| Starting from a packaged template | [Demo](/docs/templates/demo.md), [Code wiki](/docs/templates/code-wiki.md), [Living AGENTS.md](/docs/templates/agents-md.md), [Security reviewer](/docs/templates/security-reviewer.md), [Security help](/docs/templates/security-help.md), [Triage](/docs/templates/triage.md), or [Agentic Owners](/docs/templates/agentic-owners.md) |
 | Wiring an agent to GitHub webhooks | [GitHub guide](/docs/guides/github.md) |
 | Driving PRs from a cloud VM | [PR autofixer template](/docs/templates/pr-autofixer.md) |
 | Driving an agent from Linear (or another tracker) | [Webhooks guide: Linear example](/docs/guides/webhooks.md#example-linear-as-the-control-plane) |
@@ -4086,6 +3585,8 @@ npx @cursor/july docs
   collects the PR, the model records, then comments.
 - [Keep a code wiki current after merge](/docs/templates/code-wiki.md):
   update in-repo `wiki/` pages when a pull request merges.
+- [Keep AGENTS.md current from last week's work](/docs/templates/agents-md.md):
+  pull rules out of merged PRs and Slack, then open a follow-up PR.
 - [Security reviewer](/docs/templates/security-reviewer.md): review pull
   requests for exploitable bugs and post one comment.
 - [Answer security questions in Slack](/docs/templates/security-help.md):
@@ -4119,8 +3620,8 @@ npx @cursor/july docs
 - [Human-in-the-loop approvals](/docs/guides/human-in-the-loop.md): park a
   tool call until a person signs off.
 - [Host MCP OAuth](/docs/guides/mcp-oauth.md): authorize
-  `oauth: true` connections, store tokens locally, and `--store` them
-  on hosted deployments.
+  `oauth: true` connections, store tokens locally, and persist them
+  on hosted deployments (`--store`).
 - [Agent-to-agent](/docs/guides/agent-to-agent.md): every agent is an MCP
   server; agents can delegate to each other.
 - [Cloud runtime](/docs/guides/cloud-runtime.md): run turns on Cursor cloud
@@ -4727,8 +4228,8 @@ When every slot is busy, newly admitted turns queue FIFO instead of
 failing: the stream records a durable `turn.queued` event with the
 queue position, `GET /v1/sessions` reports `queued: true`, and each
 queued turn starts as soon as a slot frees. A queued turn still counts
-as running for busy semantics: follow-ups preempt it, and direct tool
-calls get `409 session_busy`. Omit for unlimited.
+as running for busy semantics: follow-ups preempt it, and direct
+write-effect tool calls get `409 session_busy`. Omit for unlimited.
 
 ```ts
 export default defineAgent({
@@ -5507,8 +5008,9 @@ the value before execution. A local call needs no inference credential.
 A hosted call still needs Cursor credentials to reach the deployment.
 
 `--session` runs the tool inside an existing session and records it on
-the event stream. If a model turn is active or pending, the server
-returns `session_busy`; retry after the turn finishes. The command
+the event stream. If a model turn is active or pending, a read-effect
+tool runs alongside it and a write-effect tool gets `session_busy`;
+retry after the turn finishes. The command
 prints the server's JSON response and exits non-zero unless the HTTP
 response succeeds with `ok: true`. See
 [Tools](/docs/reference/tools.md#call-a-tool-without-a-model-turn).
@@ -5580,6 +5082,7 @@ non-zero when the reconstructed trajectory failed.
 agent-sdk init ./my-agent          # scaffold package.json, tsconfig.json, agent/ + a demo tool
 agent-sdk init ./my-demo --template demo              # record a PR walkthrough
 agent-sdk init ./code-wiki --template code-wiki       # keep wiki pages current after merge
+agent-sdk init ./agents-md --template agents-md       # keep AGENTS.md current from last week's PRs and Slack
 agent-sdk init ./my-reviewer --template security-reviewer   # review PRs for security bugs
 agent-sdk init ./security-help --template security-help   # answer security questions in Slack
 agent-sdk init ./my-triage --template triage-linear   # comment on Linear issues
@@ -5597,8 +5100,9 @@ agent-sdk init                     # no directory: print the setup guide
 `@cursor/july` resolves for `dev` and `run`.
 
 Templates may ship `init.json`. On a TTY, `init` asks those questions
-before writing files. `code-wiki`, `pr-autofixer`, and `security-help`
-ask for GitHub repos. Repeat
+before writing files. `code-wiki`, `pr-autofixer`, `security-help`, and
+`agents-md` ask for GitHub repos. `agents-md` also asks for Slack
+channels. Repeat
 `--var id=value` to answer without a prompt.
 `--json` and non-TTY hosts skip the interview unless `--var` is set.
 
@@ -5756,7 +5260,8 @@ commands with an explicit `--json` flag skip this automatic check.
 agent-sdk deploy [--dir <path>] [--slug <slug> | --all] [--team <id>]
                 [--repo <https-url>] [--ref <git-ref>] [--path <agent-path>]
                 [--cursor-events-repo owner/name]...
-                [--allow-domain <domain>]... [--no-wait] [--json]
+                [--allow-domain <domain>]... [--multi-tenant]
+                [--no-wait] [--json]
 ```
 
 Managed hosting requires team-admin permission and the team's
@@ -5783,6 +5288,12 @@ be a lowercase hostname with at least two labels and an alphabetic
 top-level domain. One leading `*.` wildcard is allowed. A deployment
 can declare at most 20 domains.
 
+`--multi-tenant` adds a release to an existing Cursor-managed
+(multi-tenant) product such as `security-reviewer`. It is valid only
+for `architecture: "v2"` and cannot create a new multi-tenant
+application — those stay on the operator seed path. Without the flag,
+HTTP deploy stays single-tenant and a managed slug 409s.
+
 By default, the command polls every three seconds for up to ten minutes
 and succeeds only when the deployment reaches `running`. `--no-wait`
 returns after the deployment request is accepted. Multi-agent deploys
@@ -5909,6 +5420,8 @@ URL connections run a browser PKCE flow. Tokens are written to
 `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.
+`--store` is the path for the next deploy. Hosted Connect lets the
+current process retry.
 
 Cursor-account connections authorize the hosted deployment's service
 account through the Cursor backend's connector consent flow. Those
@@ -5987,6 +5500,7 @@ agent-sdk slack icon <https-url-or-file> [--dir <path>] [--prod]
                     [--slack-team <T…>] [--team <id>] [--json]
 agent-sdk slack init --manual [--dir <path>] [--name <name>]
                     [--prefix <prefix> | --no-prefix] [--channel-posts]
+                    [--install | --no-install] [--slack-team <T…>] [--prod]
 agent-sdk slack manifest [--dir <path>] [--name <name>]
                     [--env dev|prod|both] [--channel-posts] [--print]
 agent-sdk slack doctor [--dir <path>] [--prefix <prefix> | --no-prefix] [--json]
@@ -6015,17 +5529,26 @@ a local png, jpg, or gif file of at most 512KB.
 
 `slack init` without `--manual` exits non-zero and writes no files. Use
 `slack create` for the dashboard wizard. `slack init --manual` writes
-the channel file, development and production manifests, `env.example`,
-and setup status under the project. You paste those manifests at
-api.slack.com. The command refuses to overwrite a target file. If a
-collision occurs, it exits non-zero; files created earlier in the run
-remain. The token prefix defaults to the directory basename normalized
-to uppercase snake case. Explicit `--prefix` values use the same
-normalization. For example, `pr-approver` becomes
-`PR_APPROVER_SLACK_BOT_TOKEN`. `--no-prefix` uses shared
-`SLACK_BOT_TOKEN` and `SLACK_APP_TOKEN`. `--channel-posts` subscribes
-the manifests to channel-post events. The command always prints a JSON
-summary.
+the channel file, development and production manifests, a Slack CLI
+`.slack/` project (hook + manifests, committed with the repo). When
+Slack CLI is logged in, it installs the app. Otherwise `next` asks
+you to install it. `--install` requires that install. `--no-install`
+skips it. `--prod` selects the deployed app.
+`--slack-team` picks the workspace. Slack CLI keeps install tokens in
+that process; copy `xoxb` and mint `xapp` (`connections:write`) into
+`.env.local`. Tokens that appear in `.env` during that install are
+copied onto the prefixed names. Paste `.slack/manifest.dev.json` at
+api.slack.com when the Slack CLI is missing. Do not run
+`slack deploy`. The command refuses to overwrite the channel file.
+It updates the Slack CLI hook and manifests when `.slack/` already
+exists. If a collision occurs, it exits non-zero; files created
+earlier in the run remain. The token prefix defaults to the directory
+basename normalized to uppercase snake case.
+Explicit `--prefix` values use the same normalization. For example,
+`pr-approver` becomes `PR_APPROVER_SLACK_BOT_TOKEN`. `--no-prefix`
+uses shared `SLACK_BOT_TOKEN` and `SLACK_APP_TOKEN`.
+`--channel-posts` subscribes the manifests to channel-post events.
+The command always prints a JSON summary.
 
 `slack manifest` regenerates selected manifest files. `--env` defaults
 to `both`, and `--name` defaults to the directory name. `--print` writes
@@ -6156,8 +5679,10 @@ 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 `mcp-auth.json` under the CLI config directory. `--store`
-copies them onto the hosted deployment as `MCP_OAUTH_<NAME>_*` secrets.
+CLI or mid-run Connect. Tokens live in `mcp-auth.json` under the CLI
+config directory. `--store` copies them onto the deployment as
+`MCP_OAUTH_<NAME>_*` secrets. Hosted Connect lets the current
+process retry.
 
 ```ts
 export default defineConnection({
@@ -6169,6 +5694,7 @@ export default defineConnection({
 ```bash
 agent-sdk mcp oauth inventory           # browser PKCE → local mcp-auth.json
 agent-sdk mcp oauth inventory --store   # also upsert deployment secrets
+# Hosted Connect retries this process. Self-hosted stays file-only.
 ```
 
 Full walkthrough: [Host MCP OAuth](/docs/guides/mcp-oauth.md). Companion
@@ -6387,7 +5913,7 @@ lazily on first use.
 
 Continue with these pages:
 
-- [Host MCP OAuth](/docs/guides/mcp-oauth.md): `mcp oauth`, `--store`
+- [Host MCP OAuth](/docs/guides/mcp-oauth.md): `mcp oauth`, Connect, `--store`
 - [Agent-to-agent](/docs/guides/agent-to-agent.md): peers in depth
 - [Tools](/docs/reference/tools.md): authored tools that wrap MCP connections
 - [Webhooks](/docs/guides/webhooks.md): calling MCP connections from handlers
@@ -6629,7 +6155,8 @@ curl -X POST http://127.0.0.1:3000/<slug>/v1/tools/inspect_pr \
 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`
-while a turn runs). Agent-execution tools are rejected with `400`, and
+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](/docs/reference/tools.md#call-a-tool-without-a-model-turn).
 
@@ -7345,8 +6872,10 @@ message. Interrupted turns record `turn.failed` with
 Slack `stop` / `@agent stop` does the same for that thread and clears
 pending coalesced nudges.
 
-Session-bound deterministic tool calls share the same execution lock.
-They return `409 session_busy` while a model turn is running.
+Session-bound deterministic tool calls share the lock only for writes: a
+write-effect call returns `409 session_busy` while a model turn is
+running, a read-effect call runs alongside the turn (see
+[Tools](/docs/reference/tools.md#call-a-tool-without-a-model-turn)).
 
 ## Which events can I stream?
 
@@ -7869,7 +7398,14 @@ 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.
-Session-bound calls return `409 session_busy` while a turn runs. When the
+While a model turn is running, a session-bound call is admitted by its
+effect: a read-effect call (a declared `effect: "read"`, or an advertised
+MCP tool whose server annotates it read-only) runs alongside the turn,
+reading the workspace as the turn has left it, and is recorded under its
+own per-call `turnId` so trajectories keep it apart from the turn's own
+calls; a write-effect call — including an undeclared tool, which counts
+as a write — returns `409 session_busy` until the turn finishes, because
+a running turn owns the workspace. 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
@@ -7879,7 +7415,7 @@ 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
+check, same busy semantics, 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
@@ -8333,6 +7869,116 @@ sessions skip GitHub writes.
 
 ---
 
+Source: /docs/templates/agents-md.md
+
+# Keep AGENTS.md current from last week's work
+
+This agent runs every Monday at 09:00 UTC. It reads last week's merged
+pull requests and the Slack channels you list. When a durable rule
+showed up, `apply_agents` parks the write until a person approves it,
+then opens a draft follow-up pull request against the default branch.
+Chores and rules the file already states stay quiet.
+
+This template is one model turn: read the week, then call
+`apply_agents`.
+
+Init once per app. Pass a different repo and channel list each time.
+
+## Scaffold
+
+```bash
+npx @cursor/july init ./agents-md --template agents-md
+```
+
+`init` asks which GitHub repo to watch and which Slack channels to
+read. Pass `--var repos=acme/api --var slack=#eng-api,#api-private`
+to skip the prompt. Use `--var slack=none` when Slack is out of
+scope.
+
+The answers land in `agent/lib/config.ts`. Edit that file when the
+set changes.
+
+## Connect GitHub and Slack
+
+Connect GitHub in Cursor for that repository (Settings or
+[cursor.com/dashboard](https://cursor.com/dashboard)). Sign the host
+in:
+
+```bash
+cd agents-md
+agent-sdk login
+```
+
+`cursorAccount` mints a short-lived, repo-scoped credential with
+`contents-write` so the agent can open the follow-up PR. See the
+[GitHub guide](/docs/guides/github.md).
+
+Create the Slack app and invite the bot to each listed channel,
+including private ones:
+
+```bash
+agent-sdk slack create --dir .
+```
+
+See the [Slack guide](/docs/guides/slack.md).
+
+## First weekly run
+
+```bash
+agent-sdk dev
+```
+
+Schedules never fire under `dev`. Dispatch the same path production
+uses:
+
+```bash
+curl -X POST http://127.0.0.1:3000/v1/dev/schedules/weekly
+```
+
+The playground can run `/queue/run` too.
+
+The host writes `week/prs.md`, `week/slack.md`, `week/window.txt`,
+and `week/tree/**.txt` snapshots of the current `AGENTS.md` files,
+then starts a model turn. The
+model calls `apply_agents` once. A skip finishes. An update parks in
+the playground until someone approves; then a draft PR opens against
+the repository default branch. Later updates to the same base stack
+on `agents-md/<base>`. Pull requests from those branches are ignored
+so the follow-up cannot feed the next week.
+
+Chat replies stay in the playground. `apply_agents` records a skip,
+or parks the write. Approve there or with
+`POST /v1/session/:id/approvals/:callId`.
+
+## What to edit
+
+- `agent/lib/config.ts`: repo and Slack channels
+- `agent/instructions.md`: what counts as an update
+- `evals/agents.eval.ts`: smoke cases
+
+## Evals
+
+Four smoke cases: a lint-only week, a billing rule that parks the
+write, the same rule already in `AGENTS.md`, and an empty week.
+
+```bash
+agent-sdk eval
+```
+
+Eval sessions skip the GitHub write.
+
+## Deploy
+
+```bash
+agent-sdk deploy
+```
+
+Run it from the agent's git checkout. The command infers repository,
+ref, path, and slug. Production fires the Monday cron. The deployment
+uses the team's Cursor GitHub connection for the watched repo.
+
+---
+
 Source: /docs/templates/code-wiki.md
 
 # Keep a code wiki current after merge
@@ -8939,7 +8585,7 @@ not on `PATH`, use `npx @cursor/july`.
 | What you see | What to do |
 | --- | --- |
 | `409` on a follow-up message | Refresh the `continuationToken` or confirm the session is a chat session. Task sessions do not accept follow-ups. |
-| `409 session_busy` on `call --session` | Wait for the model turn to finish, or omit `--session` for a one-off call. |
+| `409 session_busy` on `call --session` | The tool is a write (or declares no effect) and a model turn is running. Wait for the turn to finish, omit `--session` for a one-off call, or declare `effect: "read"` on a tool that only reads so it runs alongside turns. |
 | `403` on stream or follow-up | Use the same auth identity that created the session. Off localhost, pass `--bearer-token` and send it on every request. |
 | Works on localhost; blocked through a tunnel or LAN | Default auth allows only direct loopback callers. Share the host with `--bearer-token <secret>` (or authored `bearerAuth`). Use `--allow-anonymous` only on a trusted private network. |
 | A channel route fails to compile with a schema type error | `GET` routes need a Zod `querySchema`. `POST` / `PUT` / `PATCH` need a Zod `bodySchema`. Use `z.object({})` or `z.unknown()` for open shapes. |
@@ -8967,7 +8613,7 @@ not on `PATH`, use `npx @cursor/july`.
 | What you see | What to do |
 | --- | --- |
 | `must be defineConnection({ url, oauth: true })` | The connection file needs `oauth: true`, or you passed the wrong connection name to `agent-sdk mcp oauth`. |
-| Local auth works; hosted calls unauthorized | Run `agent-sdk mcp oauth <name> --store`, confirm names with `agent-sdk secrets list <slug>`, then redeploy. |
+| Local auth works; hosted calls unauthorized | Finish Connect on the hosted engine, or run `agent-sdk mcp oauth <name> --store`. Confirm names with `agent-sdk secrets list <slug>`, then redeploy. |
 | Model asks for `mcp_auth` or IDE MCP for a connector it already has | Attached MCP is behind meta-tools. Set `advertiseTools: true` for named tools on local turns, or call it from a host tool via `ctx.host.mcp`. |
 
 See [Host MCP OAuth](/docs/guides/mcp-oauth.md) and