@cursor/july 0.1.1

package/skills/framework-map/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: agent-serve-framework-map
+description: >-
+  Orientation for @anysphere/agent-serve — folder structure, local vs cloud
+  runtimes, sessions, state layout, and invariants (Node not Bun, root
+  evals/, typecheck after tsx). Use when creating, editing, or running
+  agent-serve projects with agent/agent.ts and agent/instructions.md.
+---
+
+# agent-serve framework map
+
+`@anysphere/agent-serve` serves agents defined as ordinary files: markdown
+for prose, TypeScript for typed behavior, under an `agent/` directory. The
+framework discovers the files, compiles a manifest, and serves the agent
+over HTTP/Slack/GitHub channels, with the Cursor SDK + harness as the
+execution engine. Ground truth is the package `README.md` (full reference)
+and `AGENTS.md` (coding-agent loop) — this skill is the map, not the spec.
+
+Run the CLI as `agent-serve <cmd>`. In the everysphere monorepo there is no
+installed bin — use:
+
+```bash
+cd packages/agent-serve
+pnpm exec tsx src/bin/agent-serve.ts <cmd> ...
+```
+
+## Hard invariants (violating these wastes hours)
+
+1. **Node 22+, never Bun.** Bun's HTTP/2 client corrupts harness
+   tool-result streams (`NGHTTP2_FRAME_SIZE_ERROR`): every built-in
+   read/grep the model makes fails and turns degrade into 8-minute retry
+   loops. All package mise tasks already use tsx.
+2. **Evals live at the project root `evals/`**, never `agent/evals/` (that
+   path is silently ignored).
+3. **tsx strips types without checking them.** `validate`/`run` passing
+   does not mean the code typechecks — run the repo's TypeScript check
+   (in everysphere: `dev check typecheck packages/agent-serve/... --timeout 120`)
+   before shipping. Classic miss: a tool `execute` return that fails
+   `ToolExecuteResult` — returns must be JSON-shaped, so use object
+   literals or `type` aliases, not `interface` types.
+4. **Keep session state out of big monorepos.** Session workspaces are real
+   Cursor project directories and inherit ambient `AGENTS.md`/`.cursor`
+   rules from **ancestors**. Set `defineAgent({ local: { cwd } })` outside
+   the monorepo or pass a temp `--state-root`. (`run`/`eval` already use a
+   temp state root.)
+5. **A model turn needs `CURSOR_API_KEY`.** Everything structural
+   (`validate`, `info`, `call`, `serve` bring-up) works without one.
+
+## Folder structure
+
+One file per concept; the path is the identity. Full details for each
+path live under README "Folder structure".
+
+| Path | What it is |
+| --- | --- |
+| `agent/agent.ts` | `defineAgent({ model?, runtime?, cloud?, local? })`; model defaults to `grok-4.5` with `effort=high`, `fast=true` |
+| `agent/instructions.md` | Always-on system prompt (required; `.ts`/dir forms exist) |
+| `agent/tools/<name>.ts` | One typed tool; filename = tool name. `execution: "server"` (in-process, default) or `"agent"` (script that runs where the agent runs) |
+| `agent/skills/*` | SKILL.md-convention procedures, loaded on demand |
+| `agent/mcp-connections/<name>.ts` | MCP servers — available to the model, to server tools (`ctx.host.mcp`), and to channel/schedule handlers (`args.host.mcp`) |
+| `agent/subagents/<id>/` | Child agent dir (`description` required; per-subagent tools/skills/MCP connections ignored for now) |
+| `agent/channels/*.ts` | HTTP surfaces beyond the built-in session API; `slack.ts` / `github.ts` use the platform packs |
+| `agent/hooks/*.ts` | Observe-only event subscribers (never fatal) |
+| `agent/ab.ts` or `agent/ab/*.ts` | Live A/B metrics (`defineAB`); sticky `split` + `onSample` |
+| `agent/ab.config.ts` | Optional A/B `maxPlaygroundSessions` / `persistSamples` / `persistSnapshots` |
+| `agent/schedules/*` | Cron-driven runs (UTC, 5-field; never auto-fire under `--dev`) |
+| `agent/sandbox/workspace/` | Files seeded into each session workspace (local runtime only) |
+| `agent/lib/` | Import-only shared code, never discovered |
+| `evals/**/*.eval.ts` | Filesystem evals; case id = path under `evals/` |
+
+## Local vs cloud runtime
+
+`runtime: "local"` (default) runs turns on the Cursor SDK local harness on
+the serve host; `runtime: "cloud"` runs them on Cursor cloud agents
+(`bc-...` ids, needs `cloud: { repos: [...] }`).
+
+| Capability | local | cloud |
+| --- | --- | --- |
+| Server tools (`execution: "server"`), approvals | yes | **no** |
+| Agent tools (`execution: "agent"` scripts) | yes | yes |
+| Skills, sandbox seeds | yes | only if in the cloud repo |
+| Instructions | `AGENTS.md` in session workspace | prepended to first prompt |
+| Checkout of a repo/PR | you arrange it | the VM carries it |
+
+Rule of thumb: per-PR worktrees on the serve host die at
+"hundreds of engineers issuing PRs" — when the job needs a repo checkout at
+scale, use cloud and keep the host to routing, briefs, and bookkeeping.
+`validate` warns when cloud is combined with local-only capabilities.
+
+## Sessions, tokens, streams
+
+Two handles, two owners:
+
+- **continuationToken** — channel-owned conversation key. Same token =
+  same durable session (a Slack `channelId:threadTs`, a `pr:owner/repo#N`).
+  Rotates on each accepted HTTP follow-up; stale tokens get `409`.
+- **sessionId** — runtime-owned handle for streaming/inspection
+  (`GET /v1/session/:id/stream?startIndex=N`, durable NDJSON replay).
+
+A follow-up to a busy session **interrupts the in-flight turn** and waits
+for it to settle before the new turn sends. `POST /v1/session/:id/stop`
+interrupts without sending. Session-bound deterministic tool calls are
+rejected with `409 session_busy` while a turn runs.
+
+Key built-in routes (each agent, under `/<slug>` in multi-agent mode):
+`POST /v1/session`, `POST /v1/session/:id`, `GET /v1/session/:id/stream`,
+`GET /v1/sessions`, `POST /v1/tools/:toolName` (deterministic call),
+`GET/POST /v1/session/:id/approvals[/:callId]`, `GET /v1/info`,
+`GET /v1/health`, and in dev `POST /v1/dev/schedules/:id`,
+`POST /v1/dev/reminders/:id`.
+
+## State layout
+
+```
+<project>/.agent-serve/            # or <stateRoot>/<slug>/ under serve
+  sessions/<id>/session.json       # metadata
+  sessions/<id>/events.ndjson      # durable stream (replayable)
+  sessions/<id>/workspace/         # the harness cwd for that session
+  traces/<sessionId>.ndjson        # written by `run`
+  runner/                          # SDK conversation store
+```
+
+Delete a session directory to forget a conversation. The playground can
+open any `events.ndjson` ("Open trace").
+
+## The loop
+
+Edit → inspect → run → assert. Canonical commands and flags live in
+`AGENTS.md` (`validate` / `info` / `call` / `run` / `eval` / `serve`).
+Serve only your agent's directory during bring-up — mounting a parent
+folder mounts every sibling agent too.
+
+## Where to go next
+
+- Scaffolding → `packages/agent-serve/skills/create-agent/SKILL.md`
+- Evals → `packages/agent-serve/skills/evals/SKILL.md`
+- Live A/B metrics → `packages/agent-serve/skills/ab/SKILL.md`
+- GitHub webhooks → `packages/agent-serve/skills/github/SKILL.md`
+- Slack → `packages/agent-serve/skills/setup-slack/SKILL.md`
+- Local triage → `packages/agent-serve/skills/debug/SKILL.md`
+- Measured improvement → `packages/agent-serve/skills/hillclimb/SKILL.md`
+- Dogfood / deploy → `packages/agent-serve/skills/operate/SKILL.md`

package/skills/github/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: agent-serve-github
+description: >-
+  Build and test GitHub-webhook-driven agent-serve agents: githubChannel
+  hooks (auth turn vs host task), signature modes, and testing tiers
+  (fixtures, github replay, github forward, serve --cursor-events). Use
+  when wiring GitHub events, replaying PR webhooks, or debugging delivery.
+---
+
+# GitHub channels in agent-serve
+
+Author `agent/channels/github.ts` with `githubChannel()` from
+`@anysphere/agent-serve/channels/github`. It mounts
+`POST /<slug>/v1/channels/github` and publishes the events it dispatches on
+(derived from declared hooks, or pinned via `webhookEvents`) so the CLI can
+auto-derive forwarding.
+
+```ts
+import { defaultGitHubAuth, githubChannel } from "@anysphere/agent-serve/channels/github";
+
+export default githubChannel({
+  botName: "my-agent", // or GITHUB_APP_SLUG; used to ignore self-comments
+  credentials: { webhookSecret: () => process.env.GITHUB_WEBHOOK_SECRET },
+  onPullRequest: (ctx, pr) =>
+    pr.action === "opened" ? { auth: defaultGitHubAuth(ctx) } : null,
+  onCheckSuite: (ctx, suite) =>
+    suite.conclusion === "failure" ? { task: () => triage(ctx) } : null,
+});
+```
+
+Hooks: `onPullRequest`, `onComment`, `onIssue`, `onCheckSuite`,
+`onCheckRun`, `onWorkflowRun`, `onStatus`, plus catch-all `onEvent` and
+lifecycle `onStart`/`onStop`. Each hook returns one of:
+
+| Return | Meaning |
+| --- | --- |
+| `{ auth }` | Start/continue a **model turn** as that actor (a chat session exists; shows in the playground) |
+| `{ task }` | **Host-side work**, 202-ACKed immediately so it can run past GitHub's ~10s delivery timeout (no chat session) |
+| `null` | Skip this delivery |
+
+Use `{ task }` for deterministic pipelines (a security reviewer can run its
+whole review loop this way and report via commit status); use `{ auth }` when
+the model should reason about the event.
+
+## Auth modes
+
+- **Secret set** → route auth is `allowAll()` + `X-Hub-Signature-256`
+  verification before parsing; the HMAC becomes the request principal.
+- **No secret** → `localDevStrict()` (loopback only) — except under
+  `serve --dev`, which admits **unsigned loopback** deliveries so fixtures
+  and forwarding work with zero config.
+- Non-dev targets always need the secret; keep the same value on the
+  server and whatever signs deliveries.
+
+## Testing tiers — pick deliberately
+
+### 1. Saved fixtures (offline, free)
+
+```bash
+curl -s -X POST http://127.0.0.1:3000/<slug>/v1/channels/github \
+  -H 'content-type: application/json' \
+  -H 'x-github-event: pull_request' \
+  -d @fixtures/github/pull_request.synchronize.json
+```
+
+No signature needed against `--dev`. Snapshot fixtures with replay's
+`--dry-run --out` (below) instead of hand-writing payloads.
+
+### 2. `github replay` — deterministic, read-only (the hillclimbing tier)
+
+Reads a real PR via `gh api` (**pull access is enough** — `GITHUB_TOKEN`
+is fine here), synthesizes GitHub-shaped payloads, signs them when a secret
+is configured, and POSTs them at the channel. Fully deterministic.
+
+```bash
+agent-serve github replay https://github.com/owner/repo/pull/123 --dir <project>
+agent-serve github replay owner/repo#123 --dir <project> --events '*' --conclusion failure
+agent-serve github replay owner/repo#123 --dir <project> --events '*' --dry-run --out fixtures/github
+```
+
+`--events` defaults to `pull_request` (`'*'` = the channel's declared
+set); `--action` / `--conclusion` / `--comment` / `--context` shape each
+event; `--secret` or `GITHUB_WEBHOOK_SECRET` signs.
+
+### 3. `github forward` — live deliveries (needs repo admin)
+
+Wraps `gh webhook forward`: registers a real webhook and relays deliveries
+to loopback. URL + events auto-derived; repo inferred from the git remote.
+
+```bash
+agent-serve github doctor --install     # one-time: gh + cli/gh-webhook
+agent-serve github events --dir <parent> --json   # what would be forwarded
+GITHUB_TOKEN= GH_TOKEN= agent-serve github forward --dir <project>
+```
+
+Traps, in order of hours lost:
+
+1. **`GITHUB_TOKEN`/`GH_TOKEN` in the env → every delivery 401s** while
+   hook creation still succeeds. The relay authenticates with the gh CLI
+   login and rejects env tokens. Blank them for the command. `doctor` and
+   `forward` warn about this.
+2. **One forwarder per repo** (GitHub limit). Point one
+   `forward --dir <parent>` at a folder of agents and it fans out each raw,
+   still-signed delivery to every channel whose event set matches; N
+   separate forwarders collide with `Hook already exists`.
+3. Requires **admin** on the repo (org owner for `--org`) — if you lack
+   it, use replay.
+4. Best-effort dev relay: deliveries while the process is down are lost.
+
+`--repo owner/repo` / `--org ORG` override the target, `--events` narrows,
+`--url` points at a tunnel, `--slug` / `--channel` target one agent.
+
+### 4. `serve --cursor-events` — pull from Cursor (`/v0/scm-events`)
+
+```bash
+agent-serve serve --dir <project> --cursor-events --repo owner/repo
+```
+
+Reads the stream as the host's Cursor user, so it **requires sign-in**
+(`agent-serve login` / `CURSOR_API_KEY`) — `serve` refuses to start signed
+out instead of running a relay that can never receive events. No public URL
+or repo admin. Registers before consuming; offset + consumer id under
+`<state-root>/cursor-events/`. `CURSOR_API_BASE_URL` for a non-default
+backend. Stream is metadata-only today (payload lookup later).
+
+## Production-shaped channel patterns
+
+Steal these when an agent must survive real webhook volume.
+
+- **Debounce per PR** (~3s, latest event wins) and re-buffer while CI
+  settles; skip a flush when a turn for that PR is already in flight.
+- **Persist the buffer before ACKing** the webhook
+  (e.g. `.agent-serve/<slug>/webhook-buffer.json`) and restore it on channel
+  start — a restart must not drop buffered wakes.
+- **Stable continuation key** `pr:owner/repo#N` so every wake resumes the
+  PR's session; cross-channel resume needs an affinity store mapping PR →
+  SDK agent id (write it from an `agent.bound` hook).
+- **Discard payload details in wake prompts** — send a generic "re-check
+  the PR" refresh; the agent re-reads ground truth instead of trusting a
+  stale payload.
+- **Cancel PR-scoped reminders on `pull_request.closed`.**
+- No repo allowlist means the channel wakes for whatever deliveries
+  reach it — decide explicitly what repos an agent may act on, and
+  remember each wake spends real model budget.

package/skills/hillclimb/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: agent-serve-hillclimb
+description: >-
+  Iterate on a specific agent-serve agent by running the local server,
+  sending real requests, measuring correctness/efficiency, and proposing
+  the next harness or prompt change. Read this skill when improving an
+  existing agent.
+paths:
+  - packages/agent-serve/**/*
+---
+
+# Agent-serve hillclimb
+
+Optimize one agent-serve agent project
+with a tight measure → change → remeasure loop. Do not redesign the
+whole framework; climb one concrete failure mode at a time. Sibling skills:
+`framework-map` (orientation), `evals` (the ratchet), `ab` (live variant
+metrics under serve), `github` (deterministic webhook replay), `debug`
+(when a run misbehaves rather than underperforms).
+
+## Preconditions
+
+Confirm with the user (or take from the invoking message):
+
+1. **Target agent** — path or slug, e.g. `./my-agent`
+2. **Fixture(s)** — fixed inputs to compare across runs (PR URL, webhook
+   payload, playground prompt, etc.)
+3. **Success criteria** — what “better” means this round (fewer tools, faster
+   wall time, higher finding quality, fewer wrong side-effects, …)
+4. **Freeze line** — what must not change (API contracts, public output shape)
+
+If those are missing, ask before editing.
+
+## Make the fixture deterministic first
+
+A climb over a moving input is noise. Before round 1:
+
+- **GitHub agents** — replay, don't wait for live events:
+  `agent-serve github replay <pr> --dir <project>` synthesizes signed,
+  GitHub-shaped payloads from read access only, identically every run;
+  `--dry-run --out fixtures/github` snapshots them for offline replay.
+- **Tool behavior** — isolate host tools from the model with
+  `agent-serve call <tool> --dir <project> --input '{...}'` (schema-validated,
+  in-process, no turn). If the tool output is wrong, no prompt change fixes it.
+- **Chat agents** — `agent-serve run --dir <project> --message "<fixture>"`
+  gives a JSON trajectory plus an NDJSON trace under
+  `<project>/.agent-serve/traces/`; `agent-serve trajectory --events <file>`
+  re-summarizes any saved trace.
+- **Manual probes** — the playground Try modal on any channel route
+  remembers your last body per endpoint and has Copy curl; a successful Try
+  opens the created session.
+
+## Loop
+
+Repeat until the user stops or fixtures meet the criteria.
+
+### 1. Baseline
+
+- Serve with Node (never Bun):
+
+  ```bash
+  agent-serve serve --dir <project> --dev
+  ```
+
+- Hit the agent the way a user would (channel HTTP, playground, Slack in
+  `--dev` if that is the surface under test).
+
+  Custom channels live at `http://127.0.0.1:3000/<slug>/v1/channels/<id>`.
+  Playground: `http://127.0.0.1:3000/<slug>/playground`.
+
+- Record for each fixture:
+  - HTTP/status and wall time
+  - `sessionId` + playground URL
+  - final result text / structured output
+  - tool trajectory from session `events.ndjson` (`actions.requested` /
+    `action.result`)
+  - workspace footprint (what the host seeded vs what the model opened)
+
+Sessions typically live under:
+
+`<project>/.agent-serve/<slug>/sessions/<sessionId>/`
+
+### 2. Reflect
+
+Score the run on three axes; cite evidence from the trajectory, not vibes.
+
+| Axis | Ask |
+| --- | --- |
+| **Correctness** | Right answer / findings? Misses? Hallucinated context? |
+| **Efficiency** | Tool-call count, redundant reads/greps, fat evidence, latency |
+| **Harness fit** | Did the model invent work the host should have done? Escape the intended workspace? Fight the instructions? |
+
+Name the **single dominant failure mode** for this round (e.g. “full-file dumps
+trigger grep loops”, “skill not on disk so model searches the monorepo”).
+
+### 3. Propose one change
+
+Prefer the smallest lever that addresses that failure mode:
+
+1. **Host prep** — deterministic tools / channel handlers seed only what the
+   model needs (`workspaceFiles`, channel `callTool`, …)
+2. **Evidence shape** — trim, split, or order artifacts so the intended file
+   is primary
+3. **Instructions / skills** — tighten procedure, forbid escape hatches that
+   invite thrash
+4. **Tool surface** — remove or gate tools that enable wandering
+5. Framework changes only if the agent cannot express the fix otherwise
+
+State the hypothesis in one sentence: *“If we X, metric Y should move because Z.”*
+
+### 4. Apply and remeasure
+
+- Implement the change.
+- Restart serve if needed (agent project code or package `src/`).
+- Re-run the **same** fixtures.
+- Diff metrics side-by-side (tools, bytes, time, quality notes).
+- Keep the change only if the target metric improves without regressing the
+  freeze line; otherwise revert or narrow.
+- **Ratchet every kept change**: land an eval that would have failed before
+  it (tool-choice gate, `action.result` count bound, output-shape regex —
+  see `evals/SKILL.md`), and never weaken an existing gate to make a round
+  pass. `agent-serve eval --dir <project> --json` is the regression check
+  between rounds.
+
+Present a short round report to the user before starting the next climb.
+
+## Measurement tips
+
+- Prefer `action.result` counts by `toolName` over raw event volume.
+- Log paths the model actually read; escape outside the session workspace is a
+  harness smell.
+- Separate **host** work (channel `callTool`, prepare steps) from **model**
+  tools when blaming latency. The biggest wins this framework has seen came
+  from moving deterministic work to the host (one PR reviewer's host-prepared
+  reviews cut ~8-minute tool-wandering turns to ~1 minute), not from prompt
+  tuning.
+- For quality, spot-check against a known-good review or oracle on at least
+  one fixture; efficiency-only climbs will silently drop findings.
+- `turn.failed` with `"turn interrupted"` in a trace means a follow-up or
+  stop preempted the turn — measurement artifact, not a regression.
+
+## Working agreements
+
+- One failure mode per round — no mixed “also rewrite instructions while
+  trimming evidence” bundles unless the user asks.
+- Keep fixtures fixed until a climb explicitly needs a harder case.
+- Use mise/Node workflows already documented for this package; do not introduce
+  Bun.
+- Do not deploy, post real GitHub reviews, or push unless the user asks.
+- Commit only when asked.
+
+## Round report template
+
+```markdown
+### Hillclimb round N — <slug>
+- Fixture(s): …
+- Hypothesis: …
+- Change: <files / one-liner>
+- Before → after: tools …; wall …; evidence …; quality …
+- Verdict: keep | revert | narrow
+- Next failure mode (if any): …
+```

package/skills/setup-slack/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: agent-serve-setup-slack
+description: >-
+  Set up a Slack channel for an agent-serve project — Socket Mode,
+  manifests, doctor, smoke test, and opt-in Slack tool approvals (HITL).
+  Read this skill when wiring Slack for an agent-serve project.
+---
+
+# Setup Slack for agent-serve
+
+Use this skill when a human asks to wire Slack to an agent-serve agent.
+
+## Goal
+
+- Importable **dev** and **prod** Slack app manifests (Socket Mode on)
+- App-level Token (`xapp-…`, `connections:write`) + Bot token (`xoxb-…`)
+- No public Request URL (Socket Mode only)
+- Thread ↔ session via `continuationToken = channelId:threadTs`
+- One Slack app (token pair) **per agent** when serving multiple demos
+
+## Phases
+
+Update `.agent-serve/slack/setup-status.json` as you complete phases.
+
+### Phase 0 — Generate (agent)
+
+```bash
+pnpm exec tsx packages/agent-serve/src/bin/agent-serve.ts slack init \
+  --dir <agent> --name "My Agent"
+```
+
+Creates:
+
+- `agent/channels/slack.ts` with `envPrefix` from the directory name
+- `.agent-serve/slack/manifest.{dev,prod}.json`
+- `.agent-serve/slack/env.example` (`<PREFIX>_SLACK_BOT_TOKEN` / `_APP_TOKEN`)
+
+Use `--no-prefix` for the shared `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` globals
+(single-agent only). Use `--prefix CUSTOM` to override the default prefix.
+
+### Phase 1 — Create apps (human)
+
+1. Open https://api.slack.com/apps → **Create New App** → **From a manifest**
+2. Paste `manifest.dev.json` → create the *dev* app
+3. Repeat with `manifest.prod.json` for prod
+
+Stop and ask the human to complete this gate.
+
+### Phase 2 — Install + tokens (human)
+
+For each app:
+
+1. **Install to Workspace** — copy Bot User OAuth Token (`xoxb-…`)
+2. **Basic Information → App-Level Tokens** — Create Token with scope `connections:write` → copy (`xapp-…`)
+
+### Phase 3 — Env (agent)
+
+Write into `.env.local` (dev app), using the keys from `env.example`:
+
+```bash
+MY_AGENT_SLACK_BOT_TOKEN=xoxb-…
+MY_AGENT_SLACK_APP_TOKEN=xapp-…
+```
+
+```bash
+agent-serve slack doctor --prefix MY_AGENT
+```
+
+Stop when `app_token`, `connections_open`, `bot_token`, and `auth_test` are green.
+
+### Phase 4 — Serve + smoke (agent + human)
+
+```bash
+agent-serve serve --dir . --dev
+```
+
+Confirm log: `[agent-serve/slack] Socket Mode connected`.
+
+When tokens are missing the channel logs
+`channel idle reason=missing credentials need=…` and `serve` continues — useful
+when mounting a folder of agents where only some have tokens.
+
+Human:
+
+1. Invite the bot to a channel
+2. `@mention` it (or DM)
+3. Confirm Thinking… / Working… typing and a threaded reply
+4. Server logs should show correlated lines (`event_id`, `session`, `channel`, `thread_ts`):
+   - `inbound kind=app_mention …`
+   - `session start …`
+   - `reply delivered via postMessage|stream …`
+
+## Features (defaults ON)
+
+- Chat streaming (`chat.startStream` / `appendStream` / `stopStream`) with postMessage fallback
+- Thinking / task cards for tool calls
+- `assistant.threads.setStatus` with rotating `loading_messages`
+- Thread title + suggested prompts
+- `markdown_text` when supported
+- Handler `message` / `workspaceFiles` / `cloud` passthrough for PR demos
+
+If a Slack API is unavailable (`method_not_found` / `missing_scope`), the pack falls back to postMessage + setStatus.
+
+## Engagement: mentions by default, channel watch opt-in
+
+The pack dispatches only on `app_mention` + DMs unless told otherwise —
+summoned, never proactive. To watch channels (dispatch on new posts without
+a mention), opt in explicitly:
+
+```ts
+export default slackChannel({
+  engagement: {
+    channelPosts: {
+      allow: ["#issues-glass"], // explicit allowlist; no wildcard exists
+      posts: "top-level",       // default — thread replies never dispatch
+      debounceMs: 15_000,       // optional: edits settle, deletes cancel
+    },
+  },
+  onChannelPost: async (ctx, message) => ({}), // null = skip
+});
+```
+
+Requirements: generate manifests with `slack init --channel-posts` (or add
+`message.channels` / `message.groups` events + re-import), and invite the
+bot to each watched channel. Posts mentioning the bot stay on the
+`app_mention` path; watch sessions reuse the thread-scoped principal with an
+`engagement: "channel_post"` attribute, so a later mention continues the
+thread. `engagement.mentions` / `engagement.directMessages` can be set to
+`false` to turn those surfaces off.
+
+## Tool approvals over Slack (opt-in HITL)
+
+Tools with `needsApproval` park until a human approves or denies. To route
+that through Slack, set `toolApprovals: true` on `slackChannel` — it posts
+Block Kit Approve/Deny cards and routes Socket Mode `interactive` clicks
+back to the parked call:
+
+```ts
+export default slackChannel({
+  credentials: { /* … */ },
+  toolApprovals: true,
+});
+```
+
+Requirements and caveats:
+
+- The Slack app manifest needs **interactivity** enabled
+  (`buildSlackManifest({ interactivity: true })`; `toolApprovals: true`
+  implies the Socket Mode routing, but the app must allow it). Re-import
+  the manifest after changing this.
+- Composing by hand: spread `buildToolApprovalEvents({ credentials })` into
+  `events` **and** set `interactivity: true` on the channel.
+- Cards show **redacted / truncated** args (Block Kit limits); execution
+  uses the full validated input. Review sensitive tools in the playground
+  when args may exceed the card.
+- Approvals only exist for `execution: "server"` tools on the `local`
+  runtime, and parked calls do not survive a host restart.
+- In `--dev` (loopback) or `--allow-anonymous` (trusted shared host), the
+  playground can also list Slack sessions and Approve/Deny
+  their parked tools (audit records the HTTP caller). Production and
+  bearer-auth hosts stay strict: Slack resolve must come from Slack
+  interactivity or a matching principal.
+
+## Notes
+
+- Dev and prod are **separate Slack apps** (separate tokens).
+- Socket Mode only — no Events HTTP / Request URL path.
+- Do not `await waitForCompletion()` inside Slack dispatch handlers — the pack uses `waitUntil`.
+- Do not share one token pair across multiple agents in the same process.
+
+## CLI reference
+
+```bash
+agent-serve slack setup
+agent-serve slack init --dir . --name "My Agent"
+agent-serve slack init --dir . --no-prefix
+agent-serve slack init --dir . --channel-posts   # + message.channels/groups events
+agent-serve slack manifest --env both
+agent-serve slack doctor --prefix MY_AGENT
+```