@cursor/july 0.1.93 → 0.1.95

package/docs/design/agsh.md

@@ -0,0 +1,406 @@
+# 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.

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

@@ -104,8 +104,8 @@ 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-mcp-connection-is-available-in-three-places)
-for the three places every MCP connection is available.
+[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.
 
 ## What's next
 

package/docs/guides/cloud-runtime.md

@@ -66,6 +66,7 @@ mapping shifts:
 | Agent tools (`execution: "agent"`) | scripts in the session workspace | catalog + script bodies on the first prompt |
 | `skills/*` | `.cursor/skills/` in the workspace | native discovery after the first turn, from the hosted store or the signed-in account |
 | `mcp-connections/*.ts` | SDK `mcpServers` | SDK `mcpServers` (peers need `--public-url`) |
+| `host-connections/*.ts` | `ctx.host.mcp` only | `ctx.host.mcp` only |
 | `sandbox/workspace/**` | seeded into the session workspace | ignored |
 | Tool approvals (`needsApproval`) | supported | not supported; keep approval-gated tools on local turns |
 

package/docs/guides/convert-automation.md

@@ -78,7 +78,7 @@ or run lifecycle scripts from an existing `package.json`.
 | Prompt model | Pins the model on `defineAgent` in `agent/agent.ts`. `git_config` and `agent_options` remain comments. |
 | Cron trigger | Creates `agent/schedules/<slug>.ts` with `defineSchedule` in UTC. |
 | GitHub trigger | Creates `agent/channels/github.ts`. It converts pull-request action, push branch, issue action, and user allowlist filters. |
-| Slack trigger | Creates `agent/channels/slack.ts`. Mention-only uses `cursorAccount`; watches, reactions, and channel-created triggers use Socket Mode. Watches add `engagement.channelPosts`. |
+| Slack trigger | Creates `agent/channels/slack.ts` as Socket Mode with `envPrefix` from the automation name (same names `slack create` writes). Watches add `engagement.channelPosts`. Run `agent-sdk slack create` for the bot. |
 | Linear, PagerDuty, Sentry, Teams, or generic webhook | Creates a boilerplate `agent/channels/<slug>.ts`. |
 | HTTP or SSE MCP server | Creates a name-based Cursor-account connection under `agent/mcp-connections/`. The project contains no server URL or credentials. |
 | Stdio MCP server | Writes `agent/mcp-connections/<slug>.todo.md`. |

package/docs/guides/github.md

@@ -264,10 +264,10 @@ A comment-only first wake has no head SHA, so the check waits for a
 PR or CI event. The banner still posts. A later turn on the same SHA
 creates a new check run; GitHub cannot reopen a completed run.
 
-Override `events` when the mapping is custom. [Approval Buddy](../example-agents/approval-buddy.md)
-posts commit status from `turn.started` / `action.result` / `turn.failed`
-and stays never-red; that pattern still wins when you replace a default
-handler key. Handlers you author replace the matching defaults (same as
+Override `events` when the mapping is custom. A handler can post commit
+status from `turn.started` / `action.result` / `turn.failed` and stay
+never-red; that pattern still wins when you replace a default handler
+key. Handlers you author replace the matching defaults (same as
 `progress.reactions` composition today).
 
 ## Related

package/docs/guides/mcp-oauth.md

@@ -22,10 +22,8 @@ The companion skill is
   to that connection's resource URL
 - Upsert deployment secrets with `--store` so hosted engines seed the
   same tokens from env
-- Keep privileged servers off the model with `hostOnly: true` while
-  tools still call them through `ctx.host.mcp`. Do not set `hostOnly` on
-  connectors the playground or local chat should call. Use
-  `advertiseTools: true` for those.
+- Use `advertiseTools: true` when local turns should call the server by
+  name. Host tools can still call it through `ctx.host.mcp`.
 
 Prefer a Cursor account MCP connection when the connector already lives
 in the signed-in account dashboard:
@@ -40,7 +38,8 @@ and the host must hold tokens.
 
 ## How do I declare a host-OAuth connection?
 
-Add one file under `agent/mcp-connections/`. The filename is the
+Add one file under `agent/mcp-connections/` (model + host) or
+`agent/host-connections/` (host + `mcp oauth` only). The filename is the
 connection name you pass to the CLI and to `host.mcp`.
 
 ```ts
@@ -50,17 +49,14 @@ import { defineConnection } from "@cursor/july/connections";
 export default defineConnection({
   url: "https://mcp.example.com/inventory",
   oauth: true,
-  hostOnly: true,
-  description:
-    "Inventory MCP (privileged). Call only from host tools, not the model.",
+  description: "Inventory MCP.",
 });
 ```
 
 Rules of the road:
 
 - `oauth: true` is required for `agent-sdk mcp oauth`
-- `hostOnly: true` hides the server from the model; `ctx.host.mcp` and
-  channel handlers still see it
+- A file under `mcp-connections/` is visible to the model and to `ctx.host.mcp`. A file under `host-connections/` stays on the host.
 - Declare expected secret names on the agent when you plan to `--store`:
 
 ```ts
@@ -93,8 +89,7 @@ agent-sdk mcp oauth inventory
 
 What happens:
 
-1. The Agent SDK loads `agent/mcp-connections/inventory.ts` and checks
-   `oauth: true`
+1. The Agent SDK loads the connection file and checks `oauth: true`
 2. It opens the authorization URL in your browser
 3. The callback lands on `http://localhost:8787/callback`
 4. Tokens land in `mcp-auth.json` under the CLI config directory
@@ -133,8 +128,6 @@ on the pod.
 
 ## How do host tools call the server?
 
-Keep privileged calls on the host:
-
 ```ts
 const result = await ctx.host.mcp.callTool(
   "inventory",
@@ -143,9 +136,8 @@ const result = await ctx.host.mcp.callTool(
 );
 ```
 
-The model never sees `hostOnly` tools in its MCP namespace list. If the
-agent asks to "check IDE MCP" or run `mcp_auth`, point it at your host
-tool instead.
+The model can call the same server. Use a host tool when the write needs
+an allowlist or other deterministic gate.
 
 ## What if authorization fails?
 
@@ -158,7 +150,7 @@ tool instead.
 
 ## What's next
 
-- [MCP connections](../reference/connections.md): transports, `hostOnly`, account MCP
+- [MCP connections](../reference/connections.md): transports, account MCP
 - [CLI](../reference/cli.md#mcp-oauth): full flag list for `mcp oauth`
 - [Deployment](../deployment.md): secrets, egress, and hosted engines
 - [Fix common agent problems](../troubleshooting.md): more symptom → fix tables

package/docs/guides/slack.md

@@ -1,14 +1,14 @@
 ---
 title: "Slack"
-description: "Put the agent in Slack: Cursor-hosted connection, a dedicated Socket Mode app via the dashboard wizard, or a manual manifest import."
+description: "Put the agent in Slack: a dedicated Socket Mode app via the dashboard wizard, or a manual manifest import."
 ---
 
 # Slack agents
 
-The Slack channel puts your agent in Slack. Two products: the Cursor-hosted
-connection (`cursorAccount: true`), or a dedicated Socket Mode app created
-in the dashboard wizard (`agent-sdk slack create`). To own the Slack app
-yourself, run `agent-sdk slack init --manual` and paste the manifests at
+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.
@@ -47,41 +47,12 @@ 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.
 
-## Use the Cursor Slack connection
-
-If the Cursor Slack app is already installed in your workspace and linked
-to your Cursor account, skip the dedicated Slack app:
-
-```ts
-import { slackChannel } from "@cursor/july/channels/slack";
-
-export default slackChannel({
-  cursorAccount: true,
-  agentName: "Weatherbot", // single token — no spaces; defaults from mount slug (PascalCase)
-  agentIcon: { emoji: ":robot_face:" },
-});
-```
-
-Sign the host in (`agent-sdk login` or `CURSOR_API_KEY`), then mention the
-agent in Slack as `@Cursor Weatherbot …`. Thread replies and DMs keep going to
-the same agent. Messages appear as the Cursor app under that agent's name
-and icon. Slack shows its working status, then posts one final reply.
-
-Use a dedicated Socket Mode Slack app when you need your own bot user,
-channel watching (`engagement.channelPosts`), or approval buttons. On
-`cursorAccount`, agents must be explicitly addressed (@mention, DM, or
-claimed-thread reply). Channel watching and `toolApprovals` /
-`interactivity` are Socket Mode only; the Cursor connection does not relay
-Block Kit clicks. Agent names must be unique on the host; an unmatched
-`@Cursor <name>` stays on Cursor's normal Slack agent.
-
 ## 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. That applies to Socket Mode and `cursorAccount: true`. Set
-`blockExternals: false` only when the agent should serve people outside
-your org:
+handler. Set `blockExternals: false` only when the agent should serve
+people outside your org:
 
 ```ts
 export default slackChannel({
@@ -244,8 +215,7 @@ export default slackChannel({
 ```
 
 Channel watching needs the `message.channels` / `message.groups` events
-on the Slack app (Socket Mode only; not available with
-`cursorAccount: true`). Pass `--channel-posts` on `slack create` or
+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.
 
@@ -255,9 +225,7 @@ 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. The
-[alert investigator example](../example-agents/oncall.md) watches a
-bot-fed alerts channel this way.
+own replies. Use this for a bot-fed alerts channel.
 
 ## Prepare work on the host
 
@@ -286,11 +254,6 @@ Approval cards need interactivity on the Slack app. Recreate with
 `buildToolApprovalEvents({ credentials })` into `events` and set
 `interactivity: true` on the channel so Socket Mode routes the clicks.
 
-Approval buttons need Socket Mode. `slackChannel({ cursorAccount: true })`
-rejects `toolApprovals` and `interactivity` at construction, since the
-Cursor Slack connection does not relay Block Kit clicks. Use a dedicated
-Slack app to run approvals for a cursor-account agent.
-
 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
@@ -322,7 +285,7 @@ Two habits matter most.
 The `slack` subcommands cover setup end to end.
 
 ```bash
-agent-sdk slack setup                     # two-product chooser plus manual phases
+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

package/docs/quickstart.md

@@ -356,9 +356,8 @@ See [GitHub](./guides/github.md) for local event delivery and
 
 ## Where to go next
 
-- [`examples/approval-buddy`](../examples/approval-buddy/): an example
-  with commit statuses, review subagents, and a deterministic stamp
-  policy
+- [PR autofixer template](./templates/pr-autofixer.md): drive a PR on a
+  Cursor cloud VM
 - [Evals](./evals.md): freeze these two PRs as regression checks so
   prompt changes can't flip a verdict
 - [Tools](./reference/tools.md): more on typed tools, approvals, and