@cursor/july 0.1.99 → 0.1.101

package/dist/docs/llms-full.txt

@@ -336,7 +336,7 @@ Continue with these pages:
   `ab.assigned` event and durable log
 - [Playground](/docs/reference/playground.md): the A/Bs tab
 - [HTTP API](/docs/reference/http-api.md): `GET /v1/abs`
-- [Live A/B metrics skill](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/ab/SKILL.md): have a coding agent
+- [Live A/B metrics skill](/docs/skills/ab.md): have a coding agent
   wire an experiment
 
 ---
@@ -367,7 +367,7 @@ and verify the result without reading terminal prose.
 ## How do I create an agent with the built-in skill?
 
 Have the coding agent read
-[`skills/create-agent/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/create-agent/SKILL.md) and
+[`skills/create-agent/SKILL.md`](/docs/skills/create-agent.md) and
 follow it.
 
 The skill asks about your agent's purpose, runtime, model, channels, MCP
@@ -386,18 +386,20 @@ the first end-to-end turn works.
 
 ## Which built-in skill should I use?
 
-The package ships task-specific guides under [`skills/`](https://github.com/cursor/cursor/tree/main/packages/agent-serve/skills/):
+The package ships task-specific guides under [`skills/`](/docs/skills/index.md):
 
 | What you want to do | Skill |
 | --- | --- |
-| Understand the project layout and runtimes | [`framework-map`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/framework-map/SKILL.md) |
-| Create and verify a new agent | [`create-agent`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/create-agent/SKILL.md) |
-| Write fixtures and regression checks | [`evals`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/evals/SKILL.md) |
-| Live A/B metrics on traffic (`defineAB`) | [`ab`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/ab/SKILL.md) |
-| Improve an agent against fixed inputs | [`hillclimb`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/hillclimb/SKILL.md) |
-| Add GitHub webhooks and replay events | [`github`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/github/SKILL.md) |
-| Connect an agent to Slack | [`setup-slack`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/setup-slack/SKILL.md) |
-| Diagnose a local run | [`debug`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/debug/SKILL.md) |
+| Understand the project layout and runtimes | [`framework-map`](/docs/skills/framework-map.md) |
+| Create and verify a new agent | [`create-agent`](/docs/skills/create-agent.md) |
+| Write fixtures and regression checks | [`evals`](/docs/skills/evals.md) |
+| Live A/B metrics on traffic (`defineAB`) | [`ab`](/docs/skills/ab.md) |
+| Export OpenTelemetry traces | [`otel`](/docs/skills/otel.md) |
+| Improve an agent against fixed inputs | [`hillclimb`](/docs/skills/hillclimb.md) |
+| Add GitHub webhooks and replay events | [`github`](/docs/skills/github.md) |
+| Connect an agent to Slack | [`setup-slack`](/docs/skills/setup-slack.md) |
+| Authorize host MCP OAuth | [`mcp-auth`](/docs/skills/mcp-auth.md) |
+| Diagnose a local run | [`debug`](/docs/skills/debug.md) |
 
 Point your coding agent at the matching `SKILL.md`. The guide contains
 the workflow, commands, and common mistakes for that task.
@@ -450,7 +452,7 @@ smoke turn passes, give the hillclimb skill:
    evals that must stay unchanged
 
 Have the coding agent read
-[`skills/hillclimb/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/hillclimb/SKILL.md). It measures
+[`skills/hillclimb/SKILL.md`](/docs/skills/hillclimb.md). It measures
 the current run, proposes one change, remeasures the same fixtures, and
 adds an eval for each kept improvement.
 
@@ -458,6 +460,7 @@ adds an eval for each kept improvement.
 
 - [Create your first agent](/docs/quickstart.md)
 - [Scaffold an agent with Cursor](/docs/scaffolding-agents.md)
+- [Coding-agent skills](/docs/skills/index.md)
 - [Evals](/docs/evals.md)
 - [Hillclimbing](/docs/hillclimbing.md)
 - [CLI reference](/docs/reference/cli.md)
@@ -3277,7 +3280,7 @@ resolution for other file formats).
 `maxConcurrency` limits parallel datapoints. It does not limit model or
 API fan-out inside one datapoint. Materialized fixtures prevent a large
 suite from exhausting provider and GitHub rate limits. The
-[evals skill](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/evals/SKILL.md) has the full fixture workflow.
+[evals skill](/docs/skills/evals.md) has the full fixture workflow.
 
 ## Keep improvements with regression evals
 
@@ -3739,7 +3742,7 @@ event stream for repos you've connected to Cursor. You still declare a
 `githubChannel` so hooks decide what each event does.
 
 The companion skill for coding agents is
-[`skills/github/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/github/SKILL.md).
+[`skills/github/SKILL.md`](/docs/skills/github.md).
 
 ## Pull events from Cursor
 
@@ -4152,7 +4155,7 @@ deployment as secrets so prod can reconnect after a redeploy. Hosted
 Connect lets the current process retry.
 
 The companion skill is
-[`skills/mcp-auth/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/mcp-auth/SKILL.md).
+[`skills/mcp-auth/SKILL.md`](/docs/skills/mcp-auth.md).
 
 ## What can host MCP OAuth do?
 
@@ -4404,7 +4407,7 @@ You can also pass the same object to `serve(dir, { otel })`. Precedence
 is `serve({ otel })` over `agent/otel.ts` over env. An empty
 `defineOtel()` still enables export when `OTEL_EXPORTER_OTLP_*` is set.
 
-The companion skill is [`skills/otel/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/otel/SKILL.md).
+The companion skill is [`skills/otel/SKILL.md`](/docs/skills/otel.md).
 
 ## What spans does a session produce?
 
@@ -4519,7 +4522,7 @@ through `serve({ otel })` or env.
 
 ## What's next
 
-- [`skills/otel/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/otel/SKILL.md): compact
+- [`skills/otel/SKILL.md`](/docs/skills/otel.md): compact
   `defineOtel` reference for coding agents
 - [Hooks](/docs/reference/hooks.md): observe the same session event stream
   in-process
@@ -4539,7 +4542,7 @@ Replies stream there, with thinking steps and suggested prompts.
 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).
+follow [`skills/setup-slack/SKILL.md`](/docs/skills/setup-slack.md).
 
 ## Define the channel
 
@@ -4582,6 +4585,85 @@ export default slackChannel({
 });
 ```
 
+## Choose how the reply arrives
+
+Slack gives an agent two places to show progress while a turn runs: the
+status chip under the thread ("Running grep…") and the reply message
+itself. It won't fill both at once. While a message is streaming, Slack
+shows its own "is working…" chip and hides any status text you set. Cards
+only exist inside a streamed message. `reply.mode` picks which one you get.
+
+### `post` (default): status chip, then one message
+
+Tool calls and the first line of each reasoning block show in the chip as
+they happen. The answer lands as a single message when the turn finishes.
+
+```ts
+export default slackChannel({
+  reply: {
+    mode: "post",
+    status: {
+      reasoning: true,
+      tools: true,
+      idle: ["Checking the monorepo…", "Poking Datadog…"],
+    },
+  },
+});
+```
+
+`idle` is the rotation Slack cycles through when nothing more specific is
+known, up to 5 lines of 50 characters. Pass a function to `tools` to write
+your own line from the calls in flight.
+
+### `stream`: live text, with cards
+
+The answer streams into one message as the model writes it. Slack owns the
+chip for the duration, so live feedback inside the message comes from
+cards. Both are off unless you turn them on.
+
+```ts
+export default slackChannel({
+  reply: {
+    mode: "stream",
+    reasoningCard: true,
+    toolCards: { group: "per-tool" },
+  },
+  toolLabels: { grep: "Searching code", read: "Reading files" },
+});
+```
+
+The reasoning card is one task card, titled "Thinking", that receives the
+model's reasoning as it streams and completes when the answer text starts.
+`maxChars` (default 1500) caps how much it collects. Slack caps a streamed
+message near 12k characters including cards; when an answer outgrows that,
+the streamed message closes where it stands and the rest continues in a
+new message.
+
+Tool cards default to one card per tool name with a call count in the title
+(`grep ×3`), updated in place as calls finish. `group: "per-call"` shows one
+card per call instead.
+
+Cards are collapsible by default: each call adds one line under the title,
+the same summary the playground shows in a tool's header (the grep pattern,
+the file path, the shell command), and the group expands the same way the
+reasoning card does. `collapsible: false` keeps cards to their titles. On a
+collapsible card, `details(call)` returns the line to add when a call starts
+and `output(result)` the text to add when it finishes.
+
+`toolLabels` renames tools everywhere they appear: the chip, card titles,
+and the default `Running …` line.
+
+### Migrating from `streaming` and `thinkingSteps`
+
+`streaming: false` is `reply: { mode: "post" }`. `streaming: true` is
+`reply: { mode: "stream", toolCards: { group: "per-call", collapsible:
+false } }`, the title-only cards it used to show. `loadingMessages` moves
+to `reply.status.idle`. The old options still work and `agent-sdk validate`
+prints the rewrite for each one.
+
+A channel that set none of these used to stream. It now posts. Set
+`reply: { mode: "stream" }` to keep streaming.
+
 ## Set it up
 
 `slack create` opens the Cursor dashboard wizard. Finish Slack consent
@@ -5213,7 +5295,7 @@ flowchart LR
 
 ## How do I hillclimb an agent with a coding agent?
 
-Have Cursor read [`skills/hillclimb/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/hillclimb/SKILL.md).
+Have Cursor read [`skills/hillclimb/SKILL.md`](/docs/skills/hillclimb.md).
 
 Tell it:
 
@@ -5227,10 +5309,10 @@ Other skills cover the edges:
 
 | When you need… | Skill |
 | --- | --- |
-| The measured improvement loop | [`skills/hillclimb/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/hillclimb/SKILL.md) |
-| An eval that locks a kept win | [`skills/evals/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/evals/SKILL.md) |
-| Repeatable GitHub webhook inputs | [`skills/github/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/github/SKILL.md) |
-| A run that misbehaves | [`skills/debug/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/debug/SKILL.md) |
+| The measured improvement loop | [`skills/hillclimb/SKILL.md`](/docs/skills/hillclimb.md) |
+| An eval that locks a kept win | [`skills/evals/SKILL.md`](/docs/skills/evals.md) |
+| Repeatable GitHub webhook inputs | [`skills/github/SKILL.md`](/docs/skills/github.md) |
+| A run that misbehaves | [`skills/debug/SKILL.md`](/docs/skills/debug.md) |
 
 See [Building agents with agents](/docs/building-with-agents.md) for every framework skill and a good first prompt.
 
@@ -5435,7 +5517,7 @@ Confirm `agent-sdk whoami` shows the expected account.
 ## Related documentation
 
 - Package reference: [`README.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/README.md)
-- Coding-agent workflows: [`skills/`](https://github.com/cursor/cursor/tree/main/packages/agent-serve/skills/)
+- Coding-agent workflows: [`skills/`](/docs/skills/index.md)
 
 ---
 
@@ -5451,7 +5533,7 @@ review. Add GitHub event handling so pull requests can trigger reviews.
 
 - **Get started with an agent in Cursor:** follow
   [Scaffold an agent with Cursor](/docs/scaffolding-agents.md) and ask Cursor
-  to read [`skills/create-agent/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/create-agent/SKILL.md).
+  to read [`skills/create-agent/SKILL.md`](/docs/skills/create-agent.md).
 - **Get started in the CLI:** continue below.
 
 ## Prerequisites
@@ -7454,7 +7536,7 @@ agent-sdk mcp oauth inventory --store   # also upsert deployment secrets
 ```
 
 Full walkthrough: [Host MCP OAuth](/docs/guides/mcp-oauth.md). Companion
-skill: [`skills/mcp-auth/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/mcp-auth/SKILL.md).
+skill: [`skills/mcp-auth/SKILL.md`](/docs/skills/mcp-auth.md).
 
 Account MCP (`cursorAccount: true`) is the right choice for connectors
 already linked in the Cursor dashboard. Omit `servers` (or pass `"*"`)
@@ -7524,6 +7606,37 @@ be called through the direct tool API.
 In a dry-run session, MCP tools marked read-only run normally. Tools marked
 as writes are stubbed. Tools without effect annotations are unavailable.
 
+## Restrict which tools a connection serves
+
+Use `tools` the same way you allowlist harness tools on the agent. When
+set, the connection serves only those names. Use `disallowedTools` to
+drop names instead. The two combine as deny-wins, same as the Cursor
+SDK. The model and `host.mcp` only see what remains. On a model-visible
+connection, set `advertiseTools: true` so the raw server is not attached.
+
+```ts
+export default defineConnection({
+  url: "https://mcp.example.com/inventory",
+  advertiseTools: true,
+  tools: ["search_skus", "get_stock"],
+});
+
+export default defineConnection({
+  url: "https://mcp.example.com/inventory",
+  advertiseTools: true,
+  disallowedTools: ["place_order", "delete_sku"],
+});
+```
+
+Names are the server's `tools/list` names. Unknown names are omitted. A
+filter that matches nothing on the server fails the turn. Combine with
+`effects: "read"` to keep only the listed tools the server classifies as
+reads.
+
+A list of names is an allowlist. An object of handlers authors TypeScript
+tools. On `host-connections/`, a name list restricts `host.mcp` without
+advertising.
+
 ## Local stdio MCP server
 
 Run a local MCP server as a child process with `command`.
@@ -7830,7 +7943,7 @@ and `playgroundUrl` deep-links the session in the playground.
 | `message` | Required user message |
 | `title` | Session title |
 | `dryRun` | Run read tools and stub write tools |
-| `asOf` | ISO-8601 instant with a timezone, frozen at create; the prompt states it, `ctx.now()` returns it, and tools declaring `timeArgs` refuse calls not bounded at or before it. `400` when unusable |
+| `asOf` | ISO-8601 instant with a timezone, frozen at create; the prompt states it, `ctx.now()` returns it, and tool calls with relative, later-than-`asOf`, or omitted schema-declared time bounds are refused. `400` when unusable |
 | `workspaceFiles` | UTF-8 files written into the session workspace |
 | `cloud` | Per-session cloud options merged over the agent defaults |
 
@@ -9249,7 +9362,7 @@ decision.
 ## What does the create-agent skill do?
 
 The bundled
-[`create-agent` skill](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/create-agent/SKILL.md) turns your goal
+[`create-agent` skill](/docs/skills/create-agent.md) turns your goal
 into a small working project. Have Cursor read that file and follow it.
 
 Where to find the file depends on how you got the package:
@@ -9264,7 +9377,7 @@ Where to find the file depends on how you got the package:
 - Installed `@cursor/july` as a dependency? The skill also ships inside
   the package at `node_modules/@cursor/july/skills/create-agent/SKILL.md`.
 - Working from this package's source? The skill is at
-  [`skills/create-agent/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/create-agent/SKILL.md). Run
+  [`skills/create-agent/SKILL.md`](/docs/skills/create-agent.md). Run
   `agent-sdk install-skills` if you want the same copies in
   `~/.cursor/skills/agentsdk/` (the package postinstall skips the
   source checkout).
@@ -9357,7 +9470,7 @@ without a Cursor credential. Model turns and evals need
 
 Choose one to three fixed inputs, define what should improve, and name
 what must stay unchanged. Then have Cursor follow
-[`skills/hillclimb/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/hillclimb/SKILL.md).
+[`skills/hillclimb/SKILL.md`](/docs/skills/hillclimb.md).
 
 The hillclimb skill measures a baseline, changes one lever, runs the same
 inputs again, and adds an eval for each improvement you keep.
@@ -9373,6 +9486,935 @@ inputs again, and adds an eval for each improvement you keep.
 
 ---
 
+Source: /docs/skills/ab.md
+
+# Agent SDK A/B metrics (`defineAB`)
+
+Live metrics plug-in. No `agent-sdk ab` CLI. No assertion API.
+Reference: `docs/ab.md`.
+
+| | `defineEval` | `defineAB` |
+| --- | --- | --- |
+| Job | Gates on frozen fixtures | Metrics on live runs |
+| Location | `evals/**/*.eval.ts` | `agent/ab.ts` or `agent/ab/<name>.ts` |
+| How it runs | `agent-sdk eval` | Under `serve` / `run` |
+
+```ts
+import { defineAB, splitBySessionHash } from "@cursor/july/ab";
+
+export default defineAB({
+  name: "concise-instructions",
+  variants: {
+    control: { label: "Baseline" },
+    treatment: {
+      label: "Shorter",
+      instructions: "Keep replies to one short paragraph.",
+    },
+  },
+  split: splitBySessionHash({ holdout: 0.1 }),
+  derive: {
+    weatherCalls: (event) =>
+      event.type === "action.result" && event.data.toolName === "get_weather"
+        ? 1
+        : null,
+  },
+  onSample(sample) {
+    console.log(sample.variant, sample.metrics.toolCalls, sample.metrics.wallTimeMs);
+  },
+});
+```
+
+```ts
+async execute(input, ctx) {
+  if (ctx.session.abs?.["concise-instructions"] === "treatment") {
+    // treatment-specific behavior
+  }
+}
+```
+
+Enrollment is at session creation. Eval sessions skip it. Do not
+use `splitIf` to filter evals. Split helpers and `onSample`
+fields: `docs/ab.md`.
+
+Pick a name, arm labels, a split, and a real `onSample` sink. Do
+not invent credentials.
+
+---
+
+Source: /docs/skills/create-agent.md
+
+# Create an Agent SDK agent
+
+1. **Interview.** Two `AskQuestion` rounds, then a plan gate.
+2. **Scaffold.** `agent-sdk init`, then shape the files.
+3. **Verify.** `validate` / `info` / `call`, then a model turn.
+4. **Channels.** Slack, GitHub, webhook, or schedule as chosen.
+5. **Hillclimb.** `skills/hillclimb/SKILL.md`.
+
+Read `skills/framework-map/SKILL.md` if you have not. CLI is
+`agent-sdk`. Public docs:
+`node_modules/@cursor/july/dist/docs/llms.txt` or `/docs/llms.txt`
+on a running host.
+
+## Interview
+
+`AskQuestion`: batched, recommended option first and labeled
+`(recommended)`.
+
+- Mine the invoking message. Target: two rounds, then files.
+- Round 1 is identity. Round 2 is the surface, tailored by round 1.
+- Multi-select for channels, MCP, capabilities. Other where a
+  custom answer is plausible.
+- Ask decisions, not how to build it. File layout, tool names,
+  env prefix, and eval shape are yours.
+- If `AskQuestion` is missing or the user skips, state defaults
+  in one list and proceed.
+
+### Round 1: identity
+
+| Question | Options |
+| --- | --- |
+| **Purpose** | chat assistant · PR / repo automation · domain assistant over APIs/tools · scheduled reporter · Other |
+| **Name** | 2–3 slugs from the purpose + Other. Directory: `[A-Za-z0-9][A-Za-z0-9_-]*`, not `v1`/`playground`/`docs` |
+| **Location** | `./<slug>` (default) · another directory |
+
+### Round 2: surface
+
+| Question | Options | Guidance |
+| --- | --- | --- |
+| **Runtime** | `local` (default) · `cloud` | Cloud needs `cloud.repos`. Approvals and sandbox seeds are local only. Recommend local unless the job needs a cloud checkout. |
+| **Model** | `grok-4.5` + `effort=high`, `fast=true` · Other id | Params, not id suffixes: `{ id: "grok-4.5", params: [{ id: "effort", value: "high" }, { id: "fast", value: "true" }] }` |
+| **Channels** (multi) | playground + HTTP (always on) · Slack · GitHub · custom webhook · schedule | Slack: `skills/setup-slack/SKILL.md`. GitHub: `skills/github/SKILL.md`. No Discord/Teams pack; offer custom webhook. |
+| **MCP** (multi) | none · remote URL · local stdio · Cursor account connectors · Other | One file under `agent/mcp-connections/`. Account file is `account.ts`, never `cursor.ts`. Named local tools need `advertiseTools: true`. Privileged servers go in `agent/host-connections/`. |
+| **Capabilities** (multi) | server tools · agent tools · skills · subagents · hooks · sandbox seeds · approvals · evals (recommend) | Always recommend one smoke eval. |
+
+Close with the plan and file tree, then "Scaffold it" / "Adjust
+something". Write files only after approval.
+
+## Fill the blanks
+
+| Purpose | Shape |
+| --- | --- |
+| Slack chat | `slackChannel({ envPrefix })` + suggested prompts. `agent-sdk slack create` mints the bot. Prefix: `skills/setup-slack/SKILL.md` |
+| PR review with host prep | Channel `callTool` into a trimmed workspace `pr/` tree |
+| GitHub automation | `githubChannel()` hooks, replay fixtures |
+| Domain assistant | Server tools + one MCP connection + a skill |
+| Wrap an existing pipeline | GitHub `{ task }` over a thin `agent/lib/` loop |
+
+Defaults:
+
+- Instructions + 1–2 tools + chosen channels + one smoke eval.
+- `local.cwd` stays outside a monorepo checkout (default: a cache
+  directory under `~/.cache`) unless the agent must inherit that
+  tree.
+- `agent/instructions.md`: identity, when to use which tool,
+  output shape.
+- One tool per file. Prefer `execution: "server"` + zod
+  `inputSchema`. Gate side effects with `needsApproval: true`.
+- Long prompts: `prompt\`…\`` / `prompt.lines\`…\`` from
+  `@cursor/july`.
+- Host prep is for evidence (`callTool`, `workspaceFiles`), not
+  judgment, formatting, or replies.
+
+### Deterministic-path budget
+
+Default to instructions and skills. Promote to TypeScript only
+when it earns the left column:
+
+| Code owns | Model owns |
+| --- | --- |
+| Side-effect gates (approve, deploy, post) | Human-facing output to a stated shape |
+| Dedupe of external writes | Summarizing, classifying, wording |
+| Auth and signature checks | What to do next from ground truth |
+| Evidence seeding | Soft-failure retries |
+| Hard API caps | Formatting under those caps |
+
+Smells: prose builders in `.ts` (write `.md`); `agent/lib/` +
+`tools/` dwarfing instructions + skills on a first cut.
+
+## Scaffold
+
+```bash
+agent-sdk init ./<slug>
+```
+
+`init` writes the project, runs `npm install`, and may wait on
+`login`. Then shape it:
+
+1. `defineAgent` with the chosen model/runtime. Add
+   `cloud: { repos: [...] }` for cloud.
+2. Real `instructions.md`. Replace `echo.ts`.
+3. Chosen `channels/`, `mcp-connections/`, `skills/`,
+   `subagents/<id>/` (needs `description`), `schedules/`, `hooks/`.
+   Slack: `agent-sdk slack create --dir ./<slug> --name "<Name>"`,
+   not a hand-written channel. Manual Slack app:
+   `agent-sdk slack init --manual` (Slack CLI, or paste at
+   api.slack.com).
+4. `evals/evals.config.ts` with `maxConcurrency: 20` (required;
+   cap 200) plus `evals/**/*.eval.ts`. Assert `t.succeeded()` +
+   `t.calledTool(...)`. API: `skills/evals/SKILL.md`.
+
+Stay on deps the Agent SDK already ships (`zod`,
+`@modelcontextprotocol/sdk`, `tsx`).
+
+## Verify
+
+```bash
+agent-sdk validate --dir ./<slug>
+agent-sdk info --dir ./<slug> --json
+agent-sdk call <tool> --dir ./<slug> --input '{…}'
+agent-sdk eval --dir ./<slug> --list
+npx tsc --noEmit -p ./<slug>
+```
+
+tsx does not typecheck. Tool `execute` must return JSON-shaped
+values: object literals or `type` aliases, not `interface` types.
+
+Model turns need `CURSOR_API_KEY`. Without one, finish the
+key-free checks, confirm `run` fails with only the API-key error,
+and hand these over:
+
+```bash
+agent-sdk run --dir ./<slug> --message "<fixture prompt>"
+agent-sdk serve --dir ./<slug> --mode single --dev
+# http://127.0.0.1:3000/playground
+agent-sdk eval --dir ./<slug>
+```
+
+Serve only this agent's directory. Session files land in the
+project state directory (`--state-root`). That is not harness cwd.
+
+## Channel setup
+
+- **Slack.** `skills/setup-slack/SKILL.md`
+- **GitHub.** `skills/github/SKILL.md`
+- **Custom webhook.** `POST /v1/channels/<id>/<route>`.
+  Loopback-only until you add `bearerAuth(...)`.
+- **Schedules.** Never auto-fire under `--dev`.
+  `POST /v1/dev/schedules/<id>`.
+
+## Hillclimb handoff
+
+Once a smoke turn passes, agree fixtures, success criteria, and a
+freeze line, then follow `skills/hillclimb/SKILL.md`. Seed from
+the smoke session under the project state directory. GitHub:
+snapshot `agent-sdk github replay ... --dry-run --out fixtures/github`.
+
+Do not deploy or post to real Slack/GitHub beyond the smoke the
+user asked for. If the plan grows past ~10 files, cut scope.
+Re-check the budget at hand-off.
+
+---
+
+Source: /docs/skills/debug.md
+
+# Debugging the Agent SDK locally
+
+Local `agent-sdk serve`. Hosted start or health failures:
+`docs/troubleshooting.md` and `docs/deployment.md`.
+
+1. **Validate.** `agent-sdk validate --dir <project>`
+2. **Info.** `curl -s http://127.0.0.1:3000/<slug>/v1/info | jq .`
+3. **Trace.** Session events under the project state directory.
+   Then match the table.
+
+| Symptom | Fix |
+| --- | --- |
+| Playground blank / "no agents" | Start `serve`. A built SPA with no backend serves nothing. |
+| Playground UI edits do not show | Open the URL `serve --dev` prints as `playground`, not `:3000`. |
+| Sessions on disk, empty playground list | List is the calling principal. `--dev` or `--allow-anonymous` shows all. Or `?sessionId=ses_...`. |
+| Built-in read/grep fail; retry loops | Bun. Rerun under Node. The tell is `NGHTTP2_FRAME_SIZE_ERROR`. |
+| `github forward` 401s; hook created | Blank `GITHUB_TOKEN`/`GH_TOKEN`. Relay uses `gh` login. |
+| `Hook already exists` | One forwarder per repo. `forward --dir <parent>`. |
+| Answers cite ancestor `AGENTS.md` | Nested checkout. Default `local.cwd` is a cache directory under `~/.cache`. |
+| Model lists IDE `cursor` tools, never MCP | `advertiseTools: true`. Check `GET /v1/info`. |
+| Port 3000 in use | `lsof -iTCP:3000 -sTCP:LISTEN` and kill that pid. |
+| Approval vanished after restart | Parked calls do not survive restart. Re-run. |
+| Schedule / reminder silent under `--dev` | Dev never auto-fires. `POST /<slug>/v1/dev/schedules/<id>`. |
+| `409` on follow-up | Stale `continuationToken`, busy session, or a task session. |
+| `409 session_busy` on `call --session` | Wait, or drop `--session`. |
+| `403` on stream | Wrong principal. Same auth as create; beyond loopback send `--bearer-token`. |
+| Works on loopback, blocked via tunnel | `localDevStrict()` rejects forwarded headers. Use `--bearer-token`. Never `--allow-anonymous` with account MCP. |
+| Slack `channel idle … missing credentials` | Expected. `slack doctor --prefix <PREFIX>`. |
+| Immediate API-key error | Model turns need `CURSOR_API_KEY`. |
+| Approvals or sandbox seeds missing | `runtime: "cloud"`. Those are local only. `validate` warns. |
+| `validate` clean, CI typecheck fails | tsx skipped types. JSON-shaped returns; `type` not `interface`. |
+
+Count `action.result` by `toolName` before blaming latency.
+`turn.failed` + `"turn interrupted"` is a follow-up or stop, not a
+crash. `agent-sdk trajectory --events <file>` renders a saved
+trace.
+
+---
+
+Source: /docs/skills/evals.md
+
+# Agent SDK evals
+
+Fixed input, model turn, gates on the trajectory. Files live at
+project-root `evals/**/*.eval.ts`. `agent/evals/` is ignored.
+
+Live traffic variants: `skills/ab/SKILL.md`. That is not a test
+runner.
+
+```bash
+agent-sdk eval --dir . --list
+agent-sdk eval --dir . --json
+agent-sdk eval --dir . weather/nyc
+agent-sdk eval --dir . --tag smoke
+```
+
+| Form | Case id |
+| --- | --- |
+| `evals/weather.eval.ts` + `test` | `weather` |
+| `evals/weather/nyc.eval.ts` + `test` | `weather/nyc` |
+| `evals/weather.eval.ts` + `{ id: "nyc" }` | `weather/nyc` |
+
+`eval` boots an ephemeral server and a temp state root. `--url`
+points at a running agent. Model turns need `CURSOR_API_KEY`.
+
+## Seeding
+
+Creating or expanding cases: `AskQuestion` first.
+
+| Question | Options |
+| --- | --- |
+| **How should we get eval samples?** | Generate test eval samples for me `(recommended)` · I will add / upload the data manually |
+
+1. **Manual.** They provide files or paste. Show the shape below.
+   Do not invent cases. Then `eval --list` and wire gates.
+   API-backed pointers (PR URLs, SHAs, gold labels): materialize
+   under `fixtures/` first.
+2. **Generated.** Ask count (`3` recommended). Append to an
+   existing `cases` array when it fits. Never overwrite or weaken
+   a datapoint. Create `evals/evals.config.ts` if missing
+   (`maxConcurrency: 20`; cap 200).
+
+## API
+
+```ts
+import { defineEval, includes, satisfies } from "@cursor/july/evals";
+
+export default defineEval({
+  tags: ["smoke", "weather"],
+  cases: [
+    {
+      id: "nyc",
+      description: "NYC temperature.",
+      async test(t) {
+        await t.send("What's the temperature in NYC?");
+        t.succeeded();
+        t.calledTool("get_weather");
+        t.notCalledTool("save_weather_note");
+        t.check(t.reply, includes(/°|[FC]/));
+      },
+    },
+  ],
+});
+```
+
+```ts
+import { defineEvalConfig } from "@cursor/july/evals";
+
+export default defineEvalConfig({
+  maxConcurrency: 20,
+});
+```
+
+Either `test(t)` or `cases`, not both. `t.send` waits for park/fail.
+`workspaceFiles` seeds the first turn. Assert with `t.succeeded()`,
+`calledTool` / `notCalledTool`, `t.check(t.reply, …)`, `t.metric`.
+
+## What to gate
+
+Decisions and shape, not prose.
+
+1. `t.succeeded()` first
+2. Intended tool + the tempting wrong one
+3. A shape regex or `satisfies` on parsed fields
+4. If formatting keeps failing, tighten instructions. Do not move
+   rendering into a host tool.
+
+Anti-patterns: exact phrasing; more than ~5 gates (split); live
+drifting inputs (pin them).
+
+| Surface | Fixture |
+| --- | --- |
+| Chat | One frozen prompt |
+| Tool-heavy | `agent-sdk call` first, then the prompt |
+| GitHub | `github replay … --dry-run --out fixtures/github` |
+| Host-prep PR review | A team-owned PR; gate findings shape, not counts |
+| Workspace | `workspaceFiles` in `t.send` |
+
+Every kept hillclimb change lands an eval that would have failed
+before it. Never weaken a gate to pass a round.
+
+---
+
+Source: /docs/skills/framework-map.md
+
+# Agent SDK framework map
+
+`@cursor/july` discovers files under `agent/` and serves the agent
+over HTTP, Slack, and GitHub. Markdown is prose. TypeScript is typed
+behavior. Ground truth: package `README.md` and `AGENTS.md`.
+
+CLI is `agent-sdk` (Node, never Bun).
+
+Public docs: `node_modules/@cursor/july/dist/docs/llms.txt` or
+`/docs/llms.txt` on a running host.
+
+## Invariants
+
+1. **Node 22.13+, never Bun.** Bun corrupts harness tool-result
+   streams (`NGHTTP2_FRAME_SIZE_ERROR`).
+2. **Evals live at project-root `evals/`.** `agent/evals/` is ignored.
+3. **tsx does not typecheck.** Tool `execute` must return JSON-shaped
+   values: object literals or `type` aliases, not `interface` types.
+4. **Nested git checkouts.** Discovery sets `local.cwd` to a
+   per-project cache directory under `~/.cache`. Point cwd at a
+   checkout only when the agent must inherit that tree.
+5. **Attached MCP is nameless** until `advertiseTools: true`.
+6. **Model turns need `CURSOR_API_KEY`.** `validate`, `info`, `call`,
+   and `serve` bring-up do not.
+
+## Folder structure
+
+Path is identity. Full list: README "Folder structure".
+
+| Path | Role |
+| --- | --- |
+| `agent/agent.ts` | `defineAgent({ model?, runtime?, cloud?, local? })` |
+| `agent/instructions.md` | Always-on system prompt (required) |
+| `agent/tools/<name>.ts` | One tool. `execution: "server"` or `"agent"` |
+| `agent/skills/*` | On-demand procedures |
+| `agent/mcp-connections/<name>.ts` | MCP. Never name an account file `cursor.ts`. `advertiseTools: true` for named local tools |
+| `agent/host-connections/<name>.ts` | Privileged MCP for `ctx.host.mcp` / `mcp oauth` |
+| `agent/subagents/<id>/` | Child agent (`description` required) |
+| `agent/channels/*.ts` | Slack / GitHub / custom HTTP |
+| `agent/hooks/*.ts` | Observe-only |
+| `agent/ab.ts` or `agent/ab/*.ts` | Live A/B (`defineAB`) |
+| `agent/otel.ts` | OpenTelemetry (`defineOtel`) |
+| `agent/schedules/*` | Cron. Never auto-fire under `--dev` |
+| `agent/sandbox/workspace/` | Session seed files (local only) |
+| `agent/lib/` | Import-only. Never discovered |
+| `evals/**/*.eval.ts` | Case id is the path under `evals/` |
+
+## Local vs cloud
+
+`runtime: "local"` (default) runs on the serve host.
+`runtime: "cloud"` needs `cloud: { repos: [...] }`.
+
+| Capability | local | cloud |
+| --- | --- | --- |
+| Server tools | yes | yes on managed hosting; self-hosted needs `--public-url` |
+| Tool approvals | yes | no |
+| Agent tools / skills | yes | yes |
+| sandbox seeds | yes | no |
+| Checkout | you arrange it | the VM carries it |
+
+Use cloud when the job needs a checkout at scale. `validate` warns
+when cloud is combined with local-only capabilities.
+
+## Sessions
+
+- **continuationToken** continues a conversation. HTTP follow-ups
+  rotate it. Stale tokens return `409`.
+- **sessionId** is the inspect handle
+  (`GET /v1/session/:id/stream?startIndex=N`).
+
+A follow-up to a busy HTTP/MCP session interrupts the in-flight
+turn. Slack coalesces. Routes: `docs/reference/http-api.md`.
+Session files live under the project state directory
+(`--state-root`).
+
+## Where logic belongs
+
+Code: side-effect gates, write dedupe, auth, evidence seeding, hard
+API caps. Model: formatting, summarizing, classification, replies.
+Budget: `skills/create-agent/SKILL.md`.
+
+Loop: `validate` / `info` / `call` / `run` / `eval` / `serve`. Serve
+only this agent's directory.
+
+| Task | Skill |
+| --- | --- |
+| Scaffold | `skills/create-agent/SKILL.md` |
+| Evals | `skills/evals/SKILL.md` |
+| Live A/B | `skills/ab/SKILL.md` |
+| OpenTelemetry | `skills/otel/SKILL.md` |
+| GitHub | `skills/github/SKILL.md` |
+| Slack | `skills/setup-slack/SKILL.md` |
+| Host MCP OAuth | `skills/mcp-auth/SKILL.md` |
+| Local triage | `skills/debug/SKILL.md` |
+| Measured improvement | `skills/hillclimb/SKILL.md` |
+
+---
+
+Source: /docs/skills/github.md
+
+# GitHub channels in the Agent SDK
+
+Author `agent/channels/github.ts`. Production wakes:
+`cursorAccount` + `serve --cursor-events`. No public webhook URL.
+Use the HTTP route for fixtures, replay, and hosts that already
+terminate GitHub webhooks.
+
+Guide: `docs/guides/github.md`.
+
+```ts
+import { defaultGitHubAuth, githubChannel } from "@cursor/july/channels/github";
+
+export default githubChannel({
+  botName: "my-agent",
+  cursorAccount: { repos: ["owner/repo"] }, // permissions?: "read" | "pr-write" | "contents-write"
+
+  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 `onEvent` and
+`onStart`/`onStop`.
+
+| Return | Meaning |
+| --- | --- |
+| `{ auth }` | Model turn. Session shows in the playground. `workspaceFiles` can be a function. |
+| `{ task }` | Host work. No chat session. Use when the work can outlive a webhook timeout. |
+| `null` | Skip |
+
+To keep repo scope in deploy config, use `cursorAccount: true`
+and pass `--repo owner/name` at serve / `--cursor-events-repo`
+at deploy. Repos must share one GitHub owner.
+
+## Event sources
+
+| Source | When |
+| --- | --- |
+| `cursorAccount` + `serve --cursor-events` | Preferred. Signed-in host (`agent-sdk login` / `CURSOR_API_KEY`). Repos from the channel and from repeatable `--repo owner/name`. Cap 20, one GitHub owner |
+| HTTP `POST /<slug>/v1/channels/github` with a webhook secret | `allowAll()` + `X-Hub-Signature-256` |
+| HTTP, no secret | Loopback only. `serve --dev` also admits unsigned loopback (fixtures / forward) |
+
+`permissions`: `"read"` inspect; `"pr-write"` (default) comments /
+PR writes; `"contents-write"` push or merge-box checks.
+`progress.commitStatus` needs check-write; see the GitHub guide.
+Set `checks: true` when channel code posts its own Checks API
+runs through `ctx.github.createCheck`. The flag grants access.
+It does not post a check.
+
+Without `cursorAccount`, outbound calls prefer App installation
+tokens (`GITHUB_APP_ID` + `GITHUB_APP_PRIVATE_KEY`). Local tests
+can use `GITHUB_TOKEN` / `gh auth login`.
+
+The Cursor stream is metadata, not full webhook bodies. Re-read
+the PR from GitHub.
+
+## Test locally
+
+1. **Fixtures** (offline, `--dev`, no signature):
+
+```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
+```
+
+2. **Replay** (hillclimb tier; pull access is enough):
+
+```bash
+agent-sdk github replay owner/repo#123 --dir <project>
+agent-sdk github replay owner/repo#123 --dir <project> --events '*' --dry-run --out fixtures/github
+```
+
+3. **Forward** (live; repo admin). One forwarder per repo. Blank
+   `GITHUB_TOKEN`/`GH_TOKEN` or every delivery 401s:
+
+```bash
+agent-sdk github doctor --install
+GITHUB_TOKEN= GH_TOKEN= agent-sdk github forward --dir <project>
+```
+
+4. **Cursor pull** (same as production):
+
+```bash
+agent-sdk serve --dir <project> --cursor-events --repo owner/repo
+```
+
+Volume, debounce, and `progress.commitStatus` / `progress.banner`
+live in `docs/guides/github.md`. Do not preinstall them.
+
+---
+
+Source: /docs/skills/hillclimb.md
+
+# Agent SDK hillclimb
+
+Measure → change one lever → remeasure. One failure mode per round.
+
+Siblings: `skills/evals/SKILL.md`, `skills/github/SKILL.md`,
+`skills/debug/SKILL.md`.
+
+## Preconditions
+
+From the user or the invoking message:
+
+1. **Target.** Path or slug
+2. **Fixtures.** Fixed inputs
+3. **Success.** What better means this round
+4. **Freeze line.** What must not change
+
+Ask before editing if any are missing. A moving fixture is noise.
+
+| Surface | Pin it |
+| --- | --- |
+| GitHub | `agent-sdk github replay <pr> --dir <project>` (`--dry-run --out fixtures/github`) |
+| One tool | `agent-sdk call <tool> --dir <project> --input '{...}'` |
+| Chat | `agent-sdk run --dir <project> --message "<fixture>"` |
+
+## Loop
+
+1. **Serve.** `agent-sdk serve --dir <project> --mode single --dev`
+   Playground: `http://127.0.0.1:3000/playground`.
+2. **Hit it.** Same path a user would. Record status, wall time,
+   `sessionId`, output, and `action.result` counts by `toolName`.
+3. **Name the failure.** Score correctness, efficiency, harness
+   fit. One dominant failure this round.
+4. **Change one lever.** Smallest first. Delete the code or prompt
+   that caused it. Then instructions / skills, evidence shape,
+   host prep (`workspaceFiles`, channel `callTool`) for wandering
+   and latency (not formatting or judgment), remove or gate
+   wandering tools, framework only if the agent cannot express
+   the fix. Hypothesis: *If we X, metric Y should move because Z.*
+5. **Remeasure.** Same fixtures. Keep only if the target metric
+   improves and the freeze line holds.
+6. **Lock.** A kept change gets an eval that would have failed
+   before it (`skills/evals/SKILL.md`). Never weaken a gate to
+   pass a round.
+
+```markdown
+### Hillclimb round N. `<slug>`
+- Fixture(s): …
+- Hypothesis: …
+- Change: …
+- Before → after: tools …; wall …; quality …
+- Verdict: keep | revert | narrow
+- Next failure mode:
+```
+
+Do not deploy or post real GitHub reviews unless asked.
+
+---
+
+Source: /docs/skills/index.md
+
+# Coding-agent skills
+
+Each skill is a procedure a coding agent can follow. Installing
+`@cursor/july` copies them into `~/.cursor/skills/agentsdk/`. This site
+publishes the same files.
+
+See [Building agents with agents](/docs/building-with-agents.md) for when
+to use each one.
+
+| Skill | Use it to |
+| --- | --- |
+| [framework-map](/docs/skills/framework-map.md) | Learn the project layout and runtimes |
+| [create-agent](/docs/skills/create-agent.md) | Scaffold and verify a new agent |
+| [evals](/docs/skills/evals.md) | Write fixtures and regression checks |
+| [ab](/docs/skills/ab.md) | Compare variants on live traffic |
+| [otel](/docs/skills/otel.md) | Export OpenTelemetry traces |
+| [hillclimb](/docs/skills/hillclimb.md) | Improve an agent against fixed inputs |
+| [github](/docs/skills/github.md) | Add GitHub webhooks and replay events |
+| [setup-slack](/docs/skills/setup-slack.md) | Connect an agent to Slack |
+| [mcp-auth](/docs/skills/mcp-auth.md) | Authorize host MCP OAuth |
+| [debug](/docs/skills/debug.md) | Diagnose a local run |
+
+---
+
+Source: /docs/skills/mcp-auth.md
+
+# Host MCP OAuth
+
+Guide: `docs/guides/mcp-oauth.md`.
+
+| Need | Use |
+| --- | --- |
+| Connector already in the Cursor dashboard | `defineConnection({ cursorAccount: true })` or `servers: "*"` / `servers: […]` |
+| Remote URL that speaks OAuth; host holds tokens | `defineConnection({ url, oauth: true })` + this skill |
+| Static bearer / API key | `headers` / env on `{ url }` |
+
+`advertiseTools: true` puts named tools on local turns. Host tools
+can still call `ctx.host.mcp`.
+
+## Checklist
+
+1. **Declare the connection.** `agent/mcp-connections/<name>.ts`
+   with `url` + `oauth: true`. Use `agent/host-connections/` when
+   the model must not see it.
+2. **Name the secrets** if you will `--store`:
+   `hosting.secretNames` lists
+   `MCP_OAUTH_<NAME>_{ACCESS_TOKEN,REFRESH_TOKEN,CLIENT_ID}`.
+3. **Allow egress** on hosted non-bootstrap hosts:
+   `hosting.egressDomains`.
+4. **Authorize.** Local: `agent-sdk mcp oauth <name>`. Hosted:
+   finish Connect so the current process can retry, then
+   `agent-sdk mcp oauth <name> --store` and `agent-sdk deploy` so
+   the next pod gets `MCP_OAUTH_*`. `secrets list` shows the names.
+   Secrets are deployment-wide, not per caller. `cursorAccount: true`
+   stays on the Cursor backend.
+
+```ts
+// agent/mcp-connections/inventory.ts
+export default defineConnection({
+  url: "https://mcp.example.com/inventory",
+  oauth: true,
+});
+```
+
+```ts
+// agent/agent.ts
+export default defineAgent({
+  hosting: {
+    secretNames: [
+      "MCP_OAUTH_INVENTORY_ACCESS_TOKEN",
+      "MCP_OAUTH_INVENTORY_REFRESH_TOKEN",
+      "MCP_OAUTH_INVENTORY_CLIENT_ID",
+    ],
+    egressDomains: ["mcp.example.com"],
+  },
+});
+```
+
+File `inventory.ts` → prefix `MCP_OAUTH_INVENTORY`. Do not put
+`CURSOR_*` names in `secretNames`.
+
+```bash
+agent-sdk mcp oauth <connection>
+agent-sdk mcp oauth <connection> --store [--slug <slug>]
+agent-sdk secrets list <slug>
+agent-sdk deploy
+```
+
+Browser callback: `http://127.0.0.1:8787/callback`. Tokens live in
+the CLI config directory (`mcp-auth.json` or
+`$AGENT_SERVE_CONFIG_DIR`). URL change drops the old entry; re-run.
+`--store` does not restart a running engine.
+
+| Symptom | Fix |
+| --- | --- |
+| `must be defineConnection({ url, oauth: true })` | Wrong name or missing `oauth: true` |
+| `Unknown MCP connection` | Filename must match the CLI arg |
+| Callback hang | Free port 8787; finish the browser flow here |
+| Hosted 401 | `secrets list`; Connect or `--store`; redeploy |
+| Model invents `mcp_auth` / IDE MCP | `advertiseTools: true` on local turns |
+
+No raw tokens in git.
+
+---
+
+Source: /docs/skills/otel.md
+
+# Agent SDK OpenTelemetry (`defineOtel`)
+
+Push traces and metrics from the serve process to an OTLP
+collector. Logs are off until you opt in.
+
+Guide: `docs/guides/opentelemetry.md`.
+
+## Enable
+
+Any one of:
+
+1. `OTEL_EXPORTER_OTLP_ENDPOINT` (optional
+   `OTEL_SERVICE_NAME`, `OTEL_EXPORTER_OTLP_HEADERS`,
+   `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf|http/json`)
+2. `agent/otel.ts`:
+
+```ts
+import { defineOtel } from "@cursor/july/otel";
+
+export default defineOtel({
+  serviceName: "cursor",
+  exporters: [{ url: "https://otel.example.com", protocol: "http/protobuf" }],
+});
+```
+
+3. `serve(dir, { otel: { … } })`. `otel: false` disables env and
+   authored config.
+
+| Signal | Default |
+| --- | --- |
+| Traces | on (`agent_sdk.http` → session → turn → tool / subagent) |
+| Metrics | on (`cursor.token.usage`, `cursor.tool.calls`, `cursor.cost.usage`) |
+| Logs | off (`logs: true` or `OTEL_LOGS_EXPORTER=otlp`) |
+
+Prompt text and tool payloads stay off the wire unless you set
+`OTEL_LOG_USER_PROMPTS` / `OTEL_LOG_TOOL_CONTENT`.
+
+## Custom metrics
+
+```ts
+ctx.host.otel.setAttributes({ "abc.ticket_id": "INC-123" });
+ctx.host.otel.increment("abc.ticket.resolved");
+ctx.host.otel.record("abc.approval.duration_ms", 1420);
+```
+
+Prefix names with team or agent. No custom spans. Join on
+`cursor.conversation.id` and `agent_sdk.agent`. Run `serve` as its
+own process when Agent SDK should own the destination.
+
+---
+
+Source: /docs/skills/setup-slack.md
+
+# Setup Slack for the Agent SDK
+
+Dedicated Socket Mode bot. `agent-sdk slack create` opens the
+signed-in dashboard wizard. Tokens land in `.env.local` and as
+deployment secrets. Never print token values.
+
+Do not generate manifests or ask anyone to paste tokens unless
+they asked for `slack init --manual`.
+
+Existing `<PREFIX>_SLACK_BOT_TOKEN` + `_SLACK_APP_TOKEN` in
+`.env.local` keep working. Do not force those onto the wizard.
+
+Guide: `docs/guides/slack.md`.
+
+## 1. Wizard (default)
+
+```bash
+agent-sdk login
+agent-sdk slack create --dir .
+```
+
+Same Cursor account in the browser. **Add Slack to this agent**,
+approve Slack, pick the bot name. CLI writes
+`<PREFIX>_SLACK_BOT_TOKEN` / `<PREFIX>_SLACK_APP_TOKEN` and runs
+`doctor`.
+
+Prefix is the directory basename in upper snake (`jenny` →
+`JENNY`, `pr-approver` → `PR_APPROVER` → `PR_APPROVER_SLACK_*`).
+`--prefix` / `--no-prefix` override. Dev and prod are separate
+apps; `--prod` is the prod app. `--name` / `--icon` /
+`--channel-posts` / `--slack-team` prefill the wizard.
+
+If Slack needs workspace-admin approval, keep the CLI running.
+Open the **Request approval** link it prints. Managed install
+does not file the request. After approval, **Retry** in the
+wizard.
+
+`create` scaffolds `agent/channels/slack.ts` when missing:
+
+```ts
+export default slackChannel({
+  envPrefix: "JENNY",
+  suggestedPrompts: [{ title: "Help", message: "How can you help me?" }],
+});
+```
+
+Return from dispatch handlers. Do not await long work in the
+handler.
+
+A second `slack create` for the same agent and env overwrites the
+app (same Slack app id, new manifest and tokens).
+`agent-sdk slack destroy` deletes it.
+
+Local serve does not need a hosted engine. Next
+`agent-sdk deploy` injects the stored secrets.
+
+## 2. Manual (`slack init --manual`)
+
+Only when they own the app. Preferred: Slack CLI
+(`~/.slack/bin/slack`). Paste at api.slack.com if the CLI is
+missing. Never `slack deploy`; Agent SDK serve owns Socket Mode.
+
+```bash
+agent-sdk slack init --manual --dir . --name "My Agent"
+# --slack-team T0123ABCD when several workspaces are logged in
+# --no-install to scaffold only
+```
+
+Writes `agent/channels/slack.ts` (`envPrefix` from the directory),
+manifests, a `.slack/` project (`get-manifest` → those JSON files),
+and `env.example`. `--channel-posts` subscribes `message.channels`
+/ `message.groups`. If Slack CLI is logged in, this installs the
+app. `--install` fails when that cannot run.
+
+Human gates, one at a time. Stop after each.
+
+1. **Install the app.** If `next` starts with "Ask the user to
+   install this Slack app", stop and prompt them. Slack CLI: they
+   run `slack login --no-prompt`, send `/slackauthticket <ticket>`,
+   then `slack login --ticket <ticket> --challenge <code>`, then
+   `slack app install --environment local --team <T> --force`.
+   Prod: `SLACK_ENV=deployed slack app install --environment
+   deployed --team <T> --force`. Fallback: Create New App → From a
+   manifest, start with `.slack/manifest.dev.json`.
+2. **Tokens.** Slack CLI leaves xoxb / xapp in that process only.
+   Copy the bot token from the app's OAuth page. Mint an app-level
+   token with `connections:write`. Put both in `.env.local` using
+   `env.example` names. If Slack CLI wrote `SLACK_*` to `.env`,
+   copy those values to the prefixed keys.
+3. **Doctor.**
+
+## 3. Doctor and smoke
+
+```bash
+agent-sdk slack doctor --prefix JENNY
+agent-sdk serve --dir . --dev
+```
+
+Green: `app_token`, `connections_open`, `bot_token`, `auth_test`.
+Log: `[agent-sdk/slack] Socket Mode connected`. Missing tokens
+idle the channel; `serve` continues.
+
+1. Invite the bot
+2. `@mention` or DM
+3. Thinking / Working, then a threaded reply
+4. Logs: `inbound kind=app_mention`, `session start`,
+   `reply delivered via postMessage|stream`
+
+## Watch channels (opt-in)
+
+Default is mentions + DMs only. To wake on new posts:
+
+```ts
+export default slackChannel({
+  envPrefix: "JENNY",
+  engagement: {
+    channelPosts: {
+      allow: ["#alerts"], // ["*"] for every joined channel
+      posts: "top-level",
+    },
+  },
+  onChannelPost: async (ctx, message) => ({}), // null = skip
+});
+```
+
+Pass `--channel-posts` on `create` / `init --manual`. Invite the
+bot to each watched channel. Mentions stay on `app_mention`; a
+later mention continues the watch thread.
+
+## Approvals (opt-in)
+
+```ts
+export default slackChannel({
+  envPrefix: "JENNY",
+  toolApprovals: true,
+});
+```
+
+Wizard enables interactivity when this is set. Server tools on
+`local` only. Parked calls die on host restart. Cards truncate
+args; execution uses the full input.
+
+---
+
 Source: /docs/storage.md
 
 # Storage
@@ -10399,7 +11441,7 @@ not on `PATH`, use `npx @cursor/july`.
 | 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
-[`skills/mcp-auth/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/mcp-auth/SKILL.md).
+[`skills/mcp-auth/SKILL.md`](/docs/skills/mcp-auth.md).
 
 ## What if a secret showed up in a terminal transcript?