@cursor/july 0.1.109 → 0.1.111

package/docs/guides/webhooks.md

@@ -362,7 +362,7 @@ A plain API key fits a personal integration. A production Linear agent
 is an OAuth application: installing it in a workspace mints an access
 token with an expiry plus a refresh token. The serve host can be
 replaced at any time, so the pair can't live in process memory.
-Persist it in [`host.kv`](../storage.md#author-kv-ctx-host-kv) instead.
+Persist it in `host.kv` instead.
 Route handlers receive `host` in their args, and event handlers get the
 same services on `ctx`.
 
@@ -372,9 +372,8 @@ Two prerequisites:
   [deployment secrets](../deployment.md). They're static, so
   deploy-time env vars fit them.
 - Back kv with durable storage. On Cursor-managed hosting, use
-  `cursorHostedStorage` in `agent/storage.ts`
-  ([Storage](../storage.md)). Without it, kv falls back to local disk
-  and a host replacement drops the tokens.
+  `cursorHostedStorage` in `agent/storage.ts`. Without it, kv falls back
+  to local disk and a host replacement drops the tokens.
 
 Save the pair when the install flow completes, then refresh on demand:
 

package/docs/hillclimbing.md

@@ -22,7 +22,7 @@ flowchart LR
 
 ## How do I hillclimb an agent with a coding agent?
 
-Have Cursor read [`skills/hillclimb/SKILL.md`](./skills/hillclimb.md).
+Have Cursor read [`skills/hillclimb/SKILL.md`](../skills/hillclimb/SKILL.md).
 
 Tell it:
 
@@ -36,10 +36,10 @@ Other skills cover the edges:
 
 | When you need… | Skill |
 | --- | --- |
-| The measured improvement loop | [`skills/hillclimb/SKILL.md`](./skills/hillclimb.md) |
-| An eval that locks a kept win | [`skills/evals/SKILL.md`](./skills/evals.md) |
-| Repeatable GitHub webhook inputs | [`skills/github/SKILL.md`](./skills/github.md) |
-| A run that misbehaves | [`skills/debug/SKILL.md`](./skills/debug.md) |
+| The measured improvement loop | [`skills/hillclimb/SKILL.md`](../skills/hillclimb/SKILL.md) |
+| An eval that locks a kept win | [`skills/evals/SKILL.md`](../skills/evals/SKILL.md) |
+| Repeatable GitHub webhook inputs | [`skills/github/SKILL.md`](../skills/github/SKILL.md) |
+| A run that misbehaves | [`skills/debug/SKILL.md`](../skills/debug/SKILL.md) |
 
 See [Building agents with agents](./building-with-agents.md) for every framework skill and a good first prompt.
 

package/docs/quickstart.md

@@ -1,45 +1,36 @@
 ---
-title: "Build your first PR reviewer"
+title: "Build a PR reviewer"
 description: "Create an agent that reviews pull requests by complexity, approves safe changes, and handles GitHub webhook events."
 ---
 
-# Build your first PR reviewer
+# Build a PR reviewer
 
 Build a GitHub PR reviewer that classifies changes as `trivial`,
 `moderate`, or `large`, then approves safe changes or requests human
-review. Add GitHub event handling so pull requests can trigger reviews.
+review.
 
-## Getting started
+## Prerequisites
 
-- **Get started with an agent in Cursor:** follow
-  [Scaffold an agent with Cursor](./scaffolding-agents.md) and ask Cursor
-  to read [`skills/create-agent/SKILL.md`](./skills/create-agent.md).
-- **Get started in the CLI:** continue below.
+- Node 22.13 or newer.
+- agent-sdk cli
 
-## Prerequisites
+```
+npm install -g @cursor/agent-sdk
+```
 
-- Node 22.13 or newer. Bun isn't supported.
-- Run commands as `agent-sdk <command>`, or use
-  `npx @cursor/july <command>` when the CLI isn't on `PATH`. See
-  [Run the CLI](/#run-the-cli) if `agent-sdk` is not on `PATH`.
 - A Cursor credential for model turns. Sign in once:
 
 ```bash
 agent-sdk login
 ```
 
-You can also set `CURSOR_API_KEY` instead of signing in.
-
-- Authenticate with `gh auth login` or `GITHUB_TOKEN`. You can read
-  public pull requests. Posting reviews requires repository write access.
-
 ## Create and run the project
 
 Initialize the project and start the development server:
 
 ```bash
-npx @cursor/july init ./sdk-pr-reviewer
-cd sdk-pr-reviewer
+npx @cursor/agent-sdk init ./pr-reviewer
+cd pr-reviewer
 agent-sdk dev
 ```
 
@@ -79,35 +70,6 @@ For every pull request:
 End with one sentence: the verdict and why.
 ```
 
-Remove the demo echo tool:
-
-```bash
-rm agent/tools/echo.ts
-```
-
-## Add a shared helper
-
-Create `agent/lib/github.ts`:
-
-```ts
-export interface PullRef {
-  owner: string;
-  repo: string;
-  number: number;
-}
-
-/** Split https://github.com/owner/repo/pull/123 into its parts. */
-export function parsePullUrl(prUrl: string): PullRef {
-  const url = new URL(prUrl);
-  const [owner, repo, pulls, number] = url.pathname.split("/").filter(Boolean);
-  const parsed = Number.parseInt(number ?? "", 10);
-  if (pulls !== "pull" || owner === undefined || Number.isNaN(parsed)) {
-    throw new Error(`Not a pull request URL: ${prUrl}`);
-  }
-  return { owner, repo, number: parsed };
-}
-```
-
 ## Add the inspect tool
 
 Create `agent/tools/inspect_pr.ts`:
@@ -115,18 +77,18 @@ Create `agent/tools/inspect_pr.ts`:
 ```ts
 import { defineTool } from "@cursor/july/tools";
 import { z } from "zod";
-import { parsePullUrl } from "../lib/github.js";
 
 export type Complexity = "trivial" | "moderate" | "large";
 
-/** Rate complexity from fixed line and file-count thresholds. */
 function rateComplexity(linesChanged: number, changedFiles: number): Complexity {
   if (linesChanged <= 25 && changedFiles <= 2) {
     return "trivial";
   }
+
   if (linesChanged <= 400 && changedFiles <= 15) {
     return "moderate";
   }
+
   return "large";
 }
 
@@ -135,6 +97,7 @@ function trimPatch(patch: string | undefined): string | undefined {
   if (patch === undefined || patch.length <= 3000) {
     return patch;
   }
+
   return `${patch.slice(0, 3000)}\n[... patch trimmed ...]`;
 }
 
@@ -147,17 +110,24 @@ export default defineTool({
       .describe("Pull request URL: https://github.com/owner/repo/pull/123"),
   }),
   async execute({ prUrl }, ctx) {
-    const { owner, repo, number } = parsePullUrl(prUrl);
+    const url = new URL(prUrl);
+    const [owner, repo, pulls, number] = url.pathname.split("/").filter(Boolean);
+    const pull_number = Number.parseInt(number ?? "", 10);
+    if (pulls !== "pull" || owner === undefined || Number.isNaN(pull_number)) {
+      throw new Error(`Not a pull request URL: ${prUrl}`);
+    }
+
     const octokit = await ctx.host.github.getOctokit();
     const { data: pr } = await octokit.rest.pulls.get({
       owner,
       repo,
-      pull_number: number,
+      pull_number,
     });
+
     const { data: files } = await octokit.rest.pulls.listFiles({
       owner,
       repo,
-      pull_number: number,
+      pull_number,
       per_page: 100,
     });
 
@@ -165,6 +135,7 @@ export default defineTool({
       pr.additions + pr.deletions,
       pr.changed_files
     );
+
     return {
       title: pr.title,
       author: pr.user?.login,
@@ -178,7 +149,6 @@ export default defineTool({
         path: file.filename,
         additions: file.additions,
         deletions: file.deletions,
-        // Large changes get a stats-only skim; a human reads the code.
         ...(complexity === "large" ? {} : { patch: trimPatch(file.patch) }),
       })),
     };
@@ -214,7 +184,6 @@ Create `agent/tools/submit_review.ts` to post each verdict:
 ```ts
 import { defineTool } from "@cursor/july/tools";
 import { z } from "zod";
-import { parsePullUrl } from "../lib/github.js";
 
 export default defineTool({
   description:
@@ -229,7 +198,13 @@ export default defineTool({
       .describe("One or two sentences explaining the verdict."),
   }),
   async execute({ prUrl, verdict, summary }, ctx) {
-    const { owner, repo, number } = parsePullUrl(prUrl);
+    const url = new URL(prUrl);
+    const [owner, repo, pulls, number] = url.pathname.split("/").filter(Boolean);
+    const pull_number = Number.parseInt(number ?? "", 10);
+    if (pulls !== "pull" || owner === undefined || Number.isNaN(pull_number)) {
+      throw new Error(`Not a pull request URL: ${prUrl}`);
+    }
+
     const review =
       verdict === "approve"
         ? { event: "APPROVE" as const, body: `PR reviewer: ${summary}` }
@@ -242,7 +217,7 @@ export default defineTool({
     await octokit.rest.pulls.createReview({
       owner,
       repo,
-      pull_number: number,
+      pull_number,
       event: review.event,
       body: review.body,
     });
@@ -280,20 +255,16 @@ const REVIEW_ACTIONS = new Set(["opened", "reopened", "ready_for_review"]);
 
 export default githubChannel({
   botName: "sdk-pr-reviewer",
-  webhookEvents: ["pull_request"],
-  deliverReplies: false,
-  progress: { reactions: false },
+  cursorAccount: { repos: ["acme/checkout"] },
   onPullRequest: (ctx, pr) => {
     if (!REVIEW_ACTIONS.has(pr.action) || pr.draft) {
       return null;
     }
+
     return {
       auth: defaultGitHubAuth(ctx),
       title: `Review ${ctx.repository.fullName}#${pr.number}`,
-      context: [
-        "",
-        `Review ${pr.url}. Inspect it first, then submit your verdict with submit_review.`,
-      ],
+      context: `Review ${pr.url}. Inspect it first, then submit your verdict with submit_review.`,
     };
   },
 });
@@ -313,56 +284,24 @@ trigger, both tool calls, and the verdict.
 ## Run options
 
 1. **CLI message**
-
-   ```bash
+  ```bash
    agent-sdk run --dir . --message "Review https://github.com/acme/checkout/pull/42"
-   ```
-
+  ```
 2. **Local replay**
-
-   ```bash
+  ```bash
    agent-sdk github replay https://github.com/acme/checkout/pull/42 \
      --dir . --action opened
-   ```
-
-3. **Forward or `--cursor-events`**
-
-   Pull Cursor events:
-
-   ```bash
-   agent-sdk serve --dir . --cursor-events --repo owner/repo
-   ```
-
-   Forward GitHub webhooks:
-
-   ```bash
-   agent-sdk github forward --dir .
-   ```
-
-   Keep the local `dev` or `serve` process running.
-
-4. **Hosted deployment**
-
-   Deploy once, set the GitHub App secrets, then redeploy:
-
-   ```bash
-   agent-sdk deploy
-   agent-sdk secrets set sdk-pr-reviewer GITHUB_APP_ID GITHUB_APP_PRIVATE_KEY
-   agent-sdk deploy
-   ```
-
-See [GitHub](./guides/github.md) for local event delivery and
-[Deployment](./deployment.md) for hosting.
+  ```
 
 ## Where to go next
 
 - [PR autofixer template](./templates/pr-autofixer.md): drive a PR on a
-  Cursor cloud VM
+Cursor cloud VM
 - [Evals](./evals.md): freeze these two PRs as regression checks so
-  prompt changes can't flip a verdict
+prompt changes can't flip a verdict
 - [Tools](./reference/tools.md): more on typed tools, approvals, and
-  direct calls
+direct calls
 - [GitHub](./guides/github.md): fixtures, forwarding, and pulling
-  events from Cursor
+events from Cursor
 - [Building agents with agents](./building-with-agents.md): have a
-  coding agent extend the project for you
+coding agent extend the project for you

package/docs/reference/channels.md

@@ -19,22 +19,6 @@ session create, follow-up, stream, stop, the sessions list, approvals,
 deterministic tool calls, health, and info. For the route-by-route
 contract, see the [HTTP API reference](./http-api.md).
 
-Author `agent/channels/http.ts` only to override its defaults:
-
-```ts
-import {
-  bearerAuth,
-  httpChannel,
-  localDevStrict,
-} from "@cursor/july/channels";
-
-export default httpChannel({
-  auth: [localDevStrict(), bearerAuth(process.env.AGENT_TOKEN ?? "")],
-  onMessage: (message, { auth }) =>
-    `[caller ${auth?.principalId ?? "anonymous"}] ${message}`,
-});
-```
-
 ## Define a custom channel
 
 Author `agent/channels/<id>.ts`. The filename is the channel id and the

package/docs/reference/cli.md

@@ -42,7 +42,6 @@ also provide `agent-sdk slack help` and `agent-sdk github help`.
 | [`stop`](#stop)                                         | Stop a hosted deployment                                       |
 | [`delete`](#delete)                                     | Delete a hosted deployment                                     |
 | [`rotate-token`](#rotate-token)                         | Replace a deployment's alias token                             |
-| [`rotate-pod-credential`](#rotate-pod-credential)       | Replace a deployment's pod credential                          |
 | [`secrets`](#secrets)                                   | Manage deployment secrets                                      |
 | [`mcp`](#mcp)                                           | Proxy the agent's MCP endpoint over stdio; `mcp install` writes `~/.cursor/mcp.json` |
 | [`mcp oauth`](#mcp-oauth)                               | Authorize host MCP OAuth; optional `--store` to deployment secrets |
@@ -704,21 +703,6 @@ agent-sdk rotate-token <slug> [--team <id>] [--json]
 The old token stops working immediately. The replacement is shown once.
 `--json` prints `{ aliasToken }`.
 
-## rotate-pod-credential
-
-`rotate-pod-credential` replaces the credential used by the running
-engine pod.
-
-```bash
-agent-sdk rotate-pod-credential <slug> [--team <id>] [--json]
-```
-
-The command prints only the masked key (`--json` prints
-`{ podCredentialMaskedKey }`). The running pod keeps the old credential
-until the next deploy, so nothing breaks in between. Run
-`agent-sdk deploy --slug <slug>` to inject the replacement and retire
-the old credential.
-
 ## mcp
 
 `mcp` proxies an agent's MCP endpoint over stdio for MCP clients that

package/docs/reference/connections.md

@@ -54,7 +54,7 @@ agent-sdk mcp oauth inventory --store   # also upsert deployment secrets
 ```
 
 Full walkthrough: [Host MCP OAuth](../guides/mcp-oauth.md). Companion
-skill: [`skills/mcp-auth/SKILL.md`](../skills/mcp-auth.md).
+skill: [`skills/mcp-auth/SKILL.md`](../../skills/mcp-auth/SKILL.md).
 
 Account MCP (`cursorAccount: true`) is the right choice for connectors
 already linked in the Cursor dashboard. Omit `servers` (or pass `"*"`)
@@ -255,9 +255,8 @@ export default defineConnection({
 });
 ```
 
-Unknown slugs and self-references fail `serve` at startup. Resolution
-(loopback versus `--public-url`), loop caveats, and the delegation model
-are in the [Agent-to-agent guide](../guides/agent-to-agent.md).
+Unknown slugs and self-references fail `serve` at startup. Walkthrough:
+[Agent-to-agent](../guides/agent-to-agent.md#how-do-i-wire-two-agents).
 
 ## Every model-visible MCP connection is available in three places
 
@@ -302,6 +301,5 @@ lazily on first use.
 Continue with these pages:
 
 - [Host MCP OAuth](../guides/mcp-oauth.md): `mcp oauth`, Connect, `--store`
-- [Agent-to-agent](../guides/agent-to-agent.md): peers in depth
 - [Tools](./tools.md): authored tools that wrap MCP connections
 - [Webhooks](../guides/webhooks.md): calling MCP connections from handlers

package/docs/reference/extensions.md

@@ -64,8 +64,8 @@ namespace:
 The root agent still needs its own `instructions.md`. Extension
 instructions are extra fragments, not a substitute.
 
-`httpChannel()` stays on the agent. An extension authors
-`defineChannel` only; a file named `http.ts` becomes `<ns>__http`.
+The built-in HTTP session channel stays on the agent. An extension
+authors `defineChannel` only; a file named `http.ts` becomes `<ns>__http`.
 
 These stay on the agent that mounts the extension. Each is a singleton
 or is outside discovery:

package/docs/reference/hooks.md

@@ -91,7 +91,7 @@ exported from `@cursor/july`.
 | `ctx.session` | Read-only session info: `id`, `channelId`, `mode` (`chat` or `task`), `purpose` (`live` or `eval`), `auth`, plus `title` and `sdkAgentId` when set |
 | `ctx.agent` | `{ name }` of the agent the event belongs to |
 | `ctx.channel` | `{ id, continuationToken }`. The token is `null` when the session can't take follow-ups |
-| `ctx.host.kv` | Durable JSON, shared by every session of the agent; the [storage backend](../storage.md#author-kv-ctx-host-kv) decides whether it survives a hosted replace. Prefix keys with `ctx.session.id` for per-session state |
+| `ctx.host.kv` | Durable JSON, shared by every session of the agent; the storage backend decides whether it survives a hosted replace. Prefix keys with `ctx.session.id` for per-session state |
 | `ctx.host.files` | Durable files, bound to this session. Pass `{ scope: "deployment" }` for agent-wide files |
 | `ctx.host.otel` | Counters, histograms, and tags, attributed to this session |
 | `ctx.host.mcp`, `ctx.host.github`, `ctx.host.slack` | The same shared clients tools get |
@@ -139,7 +139,7 @@ All of them consume the same stream, for different jobs:
 | Reply on Slack, comment on a PR, or post any other delivery | The channel's `events` map, or the Slack and GitHub packs |
 | Show PR progress (merge-box check, sticky banner) | `githubChannel({ progress: { commitStatus, banner } })`; see [Show PR progress](../guides/github.md#show-pr-progress) |
 | Block, approve, or rewrite a tool call | [`needsApproval`](./tools.md#gate-a-tool-on-human-approval) on the tool |
-| Act on the final assistant text, or fail a bad turn | [`defineResult`](./result.md) |
+| Act on the final assistant text, reject it for a same-turn repair, or fail a bad turn | `defineResult` |
 | Gate a change on behavior | [Evals](../evals.md) |
 
 ## Patterns
@@ -258,9 +258,7 @@ At runtime:
 
 Continue with these pages:
 
-- [Turn result](./result.md): fail a turn from `commit`, not from a hook
 - [Sessions and streaming](./sessions.md): the event vocabulary hooks observe
-- [Storage](../storage.md): where `ctx.host.kv` and `ctx.host.files` live
 - [OpenTelemetry](../guides/opentelemetry.md): OTLP traces and metrics
   from the same event stream
 - [Deployment](../deployment.md#observability): runtime logs and export

package/docs/reference/http-api.md

@@ -118,7 +118,7 @@ Two routes list and resolve parked tool calls.
 | `GET /v1/session/:sessionId/approvals`          | Pending human-in-the-loop tool approvals                       |
 | `POST /v1/session/:sessionId/approvals/:callId` | Resolve one: `{"decision":"approve"}` or `{"decision":"deny"}` |
 
-For the lifecycle, see [Human-in-the-loop](../guides/human-in-the-loop.md).
+For the lifecycle, see [Gate a tool on human approval](./tools.md#gate-a-tool-on-human-approval).
 
 ## Call a tool directly
 
@@ -189,8 +189,8 @@ secret is configured. See [Channels](./channels.md).
 spec-compliant 405s). The tools are `ask` (delegate a message, bounded
 waits), `check` (poll a running session), and `call_tool` (deterministic
 server-tool passthrough, present when the agent has server tools). The
-route runs the same auth chain as the session API. See
-[Agent-to-agent](../guides/agent-to-agent.md).
+route runs the same auth chain as the session API. Peer wiring:
+[MCP connections](./connections.md#peer-mcp-connection).
 
 `/v1/mcp/tools` is a second stateless MCP endpoint exposing only the
 agent's deterministic server tools. Hosted cloud turns call back into
@@ -214,8 +214,8 @@ Eval runs are asynchronous. Poll the run route for case progress and
 the final `completed` or `failed` status. Batch errors appear on the
 snapshot returned by the poll. Entries within `filterIds` and `tags`
 use OR semantics. When both fields are present, a case must match one
-entry from each field. Listed runs persist across restarts when storage is configured; see
-[Storage](../storage.md#eval-table). Otherwise they are
+entry from each field. Listed runs persist across restarts when
+durable storage is configured. Otherwise they are
 process-memory only.
 
 ## Dev-mode routes

package/docs/reference/playground.md

@@ -57,5 +57,5 @@ Continue with these pages:
 
 - [HTTP API](./http-api.md): the HTTP surface the playground uses
 - [Sessions and streaming](./sessions.md): the streams it renders
-- [Human-in-the-loop](../guides/human-in-the-loop.md): the approval
-  buttons in context
+- [Gate a tool on human approval](./tools.md#gate-a-tool-on-human-approval):
+  the approval buttons in context

package/docs/reference/project-layout.md

@@ -73,10 +73,10 @@ Each path maps to a capability and a reference page.
 | `agent/extensions/<ns>.ts` or `agent/extensions/<ns>/` | A mounted extension or Cursor plugin; its contributions become `<ns>__<name>` | [Extensions](./extensions.md) |
 | `agent/channels/*.ts` | HTTP surfaces beyond the built-in session API; `slack.ts` and `github.ts` use the platform packs | [Channels](./channels.md) |
 | `agent/hooks/*.ts` | Observe-only event subscribers, never fatal | [Hooks](./hooks.md) |
-| `agent/otel.ts` | `defineOtel` OTLP export (traces, metrics, optional logs) | [OpenTelemetry](../guides/opentelemetry.md) |
-| `agent/storage.ts` | `defineStorage` backend for the durable `host.kv` / `host.files` APIs | [Storage](../storage.md) |
+| `agent/otel.ts` | Factory-only OTLP authoring (`defineOtel`). Public path is env / `serve({ otel })`. | [OpenTelemetry](../guides/opentelemetry.md) |
+| `agent/storage.ts` | `defineStorage` backend for the durable `host.kv` / `host.files` APIs | None |
 | `agent/artifacts.ts` | `defineArtifacts` kinds, the `tag_artifact` opt-in, and retention | [Artifacts](./artifacts.md) |
-| `agent/result.ts` | `defineResult` host `commit` on the final assistant text | [Turn result](./result.md) |
+| `agent/result.ts` | `defineResult` host `commit` on the final assistant text (`throw` or `ctx.reject`) | None |
 | `agent/schedules/*` | Cron-driven runs (UTC, 5-field; never auto-fire under `--dev`) | [Schedules](./schedules.md) |
 | `agent/sandbox/workspace/**` | Seed files copied into each local session workspace | [Sessions](./sessions.md#what-goes-into-a-local-session-workspace) |
 | `agent/playground/` | Custom playground tool chips | [Playground](./playground.md) |
@@ -110,4 +110,3 @@ Continue with these pages:
 
 - [Agent config](./agent-config.md): the runtime config at the root
 - [Tools](./tools.md): add typed actions under `agent/tools/`
-- [Concepts](../concepts.md): why the filesystem is the interface

package/docs/reference/sessions.md

@@ -95,8 +95,10 @@ within one session. The `at` field is an ISO-8601 timestamp.
 Pair `actions.requested` with `action.result` to reconstruct the tool
 trajectory. Read `turn.completed.data.usage` for input, output, and
 cache token counts. When `agent/result.ts` is authored, a thrown
-`commit` or empty assistant text emits `turn.failed` instead of
-`turn.completed`. See [Turn result](./result.md).
+`commit`, a `ctx.reject` that exhausts the two-repair budget, or empty
+assistant text emits `turn.failed` instead of `turn.completed`.
+`ctx.reject(message)` re-runs the same turn with that message so the
+model can revise while tools and the session filesystem are still up.
 
 ## How do I stream or replay session events?
 
@@ -146,7 +148,7 @@ Cloud conversations remain on the Cursor backend.
 
 Nested git checkouts already default `local.cwd` outside the enclosing
 repo. See
-[local session workspaces](../concepts.md#what-files-can-a-local-session-access).
+[What goes into a local session workspace?](#what-goes-into-a-local-session-workspace).
 
 ## How do I inspect a saved event stream?
 
@@ -164,4 +166,3 @@ view.
 
 - [HTTP API](./http-api.md)
 - [Hooks](./hooks.md)
-- [How the Agent SDK works](../concepts.md)

package/docs/reference/subagents.md

@@ -53,9 +53,8 @@ subagent."
 
 Subagents split one job into roles inside a single agent. When the
 specialist is independently useful, with its own tools, sessions, and
-playground, make it a full agent and wire a peer MCP connection instead. The
-comparison table is in the
-[Agent-to-agent guide](../guides/agent-to-agent.md#peer-or-subagent).
+playground, make it a full agent. See
+[Agent-to-agent](../guides/agent-to-agent.md#peer-or-subagent).
 
 ## Patterns
 
@@ -71,6 +70,5 @@ parent routes; the specialist executes.
 
 Continue with these pages:
 
-- [Agent-to-agent](../guides/agent-to-agent.md): the peer alternative
 - [Skills](./skills.md): when a procedure is enough and a child agent
   is overkill

package/docs/reference/tools.md

@@ -81,7 +81,7 @@ export default defineTool({
 `ctx.host` carries the shared host services: `host.mcp` (authored MCP
 connections: `names()`, `listTools(name)`, `callTool(name, tool, args)`),
 `host.github` and `host.slack` (shared platform clients), `host.kv` and
-`host.files` (durable [storage](../storage.md)), `host.otel` (custom
+`host.files` (durable storage), `host.otel` (custom
 metrics and session tags; see [OpenTelemetry](../guides/opentelemetry.md)),
 `host.reminders` (per-session wakes, when attached).
 
@@ -239,8 +239,7 @@ The call parks, the turn stays running, and the stream emits
 `action.approval_requested` until someone resolves it from the
 playground, `POST /v1/session/:id/approvals/:callId`, or Slack
 Approve/Deny cards. Approvals exist for server tools on the local
-runtime only, and parked calls don't survive a host restart. The full
-lifecycle is in [Human-in-the-loop](../guides/human-in-the-loop.md).
+runtime only, and parked calls don't survive a host restart.
 
 ## Call a tool without a model turn
 
@@ -338,8 +337,6 @@ dry-run sessions can execute reads and stub writes.
 
 Continue with these pages:
 
-- [Human-in-the-loop](../guides/human-in-the-loop.md): the approval
-  lifecycle in full
 - [MCP connections](./connections.md): tools that come from MCP servers
   instead
 - [Extensions](./extensions.md): tools installed as a package under a

package/docs/troubleshooting.md

@@ -74,7 +74,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](./guides/mcp-oauth.md) and
-[`skills/mcp-auth/SKILL.md`](./skills/mcp-auth.md).
+[`skills/mcp-auth/SKILL.md`](../skills/mcp-auth/SKILL.md).
 
 ## What if a secret showed up in a terminal transcript?
 
@@ -111,6 +111,5 @@ stream. The playground **Open trace** control does the same visually.
 
 ## What's next
 
-- [Concepts](./concepts.md): the model behind these symptoms
 - [Hillclimbing](./hillclimbing.md): when the agent runs but underperforms
 - [Deployment](./deployment.md): auth and state on shared hosts