@cursor/july 0.1.5 → 0.1.7

package/docs/example-agents/approval-buddy.md

@@ -0,0 +1,270 @@
+---
+title: "Keep PR approval policy deterministic with Approval Buddy"
+description: "Separate code-owned eligibility from model-owned review, then connect GitHub, Slack, subagents, durable storage, and evals."
+---
+
+# Keep PR approval policy deterministic with Approval Buddy
+
+Approval Buddy approves eligible pull requests from a fixed roster and
+declines every other request. GitHub still blocks self-approval when the stamp
+identity authored the PR. Code decides eligibility. The model prepares
+evidence, runs two specialist reviews, and passes their findings to the
+approval tool without changing the policy decision.
+
+Use this example when an agent can make a judgment inside a workflow, but
+authorization and the final side effect must stay in deterministic code.
+
+[Browse the Approval Buddy source.](../../examples/approval-buddy/)
+
+## Keep approval policy in code
+
+Approval Buddy draws three hard boundaries:
+
+- `prepare_review` and `approve_pr` re-read the live PR and apply the same
+  eligibility rules.
+- Two subagents inspect prepared evidence, but their findings never grant or
+  block approval.
+- Only `approve_pr` posts the GitHub review.
+
+A spoofed webhook, Slack message, or model claim can't add someone to the
+buddy roster. The mutating tool checks the source of truth immediately before it
+acts.
+
+## Follow the intended stamp flow
+
+The root instructions ask the model to run this sequence for a qualifying PR:
+
+1. A non-draft `pull_request` event arrives with action `opened`, `reopened`,
+   or `ready_for_review`.
+2. The GitHub channel checks its repository allowlist and starts a session.
+3. `turn.started` posts a pending commit status.
+4. The model calls `prepare_review`.
+5. Host code fetches the live PR. It checks the author, open state, merged
+   state, and draft state.
+6. A qualifying PR gets `pr/MANIFEST.md`, `pr/meta.json`, and
+   `pr/diff.patch` in the session workspace. Diffs above 2,000,000
+   characters are truncated and marked in metadata.
+7. The model calls both review subagents through the built-in `task` tool.
+8. It concatenates their contracted replies and calls `approve_pr`.
+9. `approve_pr` re-runs eligibility, posts an `APPROVE` review, and returns
+   the outcome.
+10. The channel posts a final commit status. A self-approval block also gets
+    a short timeline comment because no approval review can appear.
+
+Ineligible PRs skip evidence and subagents. The model still calls
+`approve_pr` so the deterministic tool returns the formal decline reason.
+
+Steps 4 through 9 are prompt-driven. The channel doesn't enforce tool order
+or prove both subagents ran, and `approve_pr` accepts missing findings. A
+failed turn clears the pending status with a green non-blocking result without
+approving the PR.
+
+## Map the framework features
+
+| Capability | Source | Role |
+| --- | --- | --- |
+| Root agent and policy prompt | [`agent/agent.ts`](../../examples/approval-buddy/agent/agent.ts), [`agent/instructions.md`](../../examples/approval-buddy/agent/instructions.md) | Configure the local agent and describe orchestration order. |
+| GitHub channel | [`agent/channels/github.ts`](../../examples/approval-buddy/agent/channels/github.ts) | Filter wakes, lease GitHub access, and publish status events. |
+| Slack channel | [`agent/channels/slack.ts`](../../examples/approval-buddy/agent/channels/slack.ts) | Accept approval-bot stamp and qualification requests. |
+| Server tools | [`agent/tools/`](../../examples/approval-buddy/agent/tools/) | Prepare evidence, approve, list buddies, and search GIFs. |
+| Deterministic policy | [`agent/lib/approve.ts`](../../examples/approval-buddy/agent/lib/approve.ts), [`agent/lib/buddies.ts`](../../examples/approval-buddy/agent/lib/buddies.ts) | Own the roster and live eligibility checks. |
+| Review subagents | [`agent/subagents/`](../../examples/approval-buddy/agent/subagents/) | Run deep audit and code-quality passes over the same evidence. |
+| Storage | [`agent/storage.ts`](../../examples/approval-buddy/agent/storage.ts) | Persist sessions and events through a custom durable adapter. |
+| Evals and unit tests | [`evals/`](../../examples/approval-buddy/evals/), [`agent/lib/`](../../examples/approval-buddy/agent/lib/) | Protect routing, output contracts, policy, and GitHub behavior. |
+
+There are no authored skills, MCP connections, schedules, reminders, hooks,
+A/B experiments, sandbox seeds, or tool approvals.
+
+## Prepare credentials
+
+You need:
+
+- Node 22.13 or newer.
+- An agent-runtime credential.
+- GitHub access to read PRs, post reviews, create commit statuses, and
+  post the self-approval visibility comment.
+
+Optional GIF selection uses:
+
+- `GIPHY_API_KEY` or `APPROVAL_BUDDY_GIPHY_API_KEY`,
+- `APPROVAL_BUDDY_STAMP_GIF`, or
+- severity-specific `APPROVAL_BUDDY_STAMP_GIF_<LEVEL>` variables.
+
+If you enable Giphy in a hosted copy, declare its secret and
+`api.giphy.com` egress.
+
+## Validate without approving a PR
+
+```bash
+agentkit validate --dir examples/approval-buddy
+agentkit info --dir examples/approval-buddy --json
+```
+
+List the deterministic roster:
+
+```bash
+agentkit call list_buddies \
+  --dir examples/approval-buddy \
+  --input '{}'
+```
+
+Set a known merged PR, then run the read-only precheck:
+
+```bash
+MERGED_PR_URL=https://github.com/your-org/your-repo/pull/123
+agentkit call prepare_review \
+  --dir examples/approval-buddy \
+  --input "{\"prUrl\":\"$MERGED_PR_URL\"}"
+```
+
+The result should decline because the PR is no longer open. `prepare_review`
+never posts an approval.
+
+> [!CAUTION]
+> Don't use `agentkit call approve_pr` as a smoke test. The tool has no
+> `needsApproval` gate and posts a real GitHub review when the PR qualifies.
+
+## See why preparation is separate
+
+`prepare_review` is read-only. It checks policy before fetching a large diff,
+so declined requests don't spend review-agent work.
+
+Direct calls return the evidence file map because their scratch workspace is
+deleted after the call. In-session calls write the tree to
+`ctx.workspaceDir`, where both subagents can read it.
+
+`approve_pr` repeats the live check instead of trusting preparation. A PR can
+close, merge, become a draft, or change author-related context between the two
+steps. Revalidation keeps the final write bound to current state.
+
+This is a reusable two-tool pattern:
+
+- a read-only tool prepares and explains the decision,
+- a mutating tool repeats policy at the side-effect boundary.
+
+## Fan out two review contracts
+
+The two discovered subagents have different contracts:
+
+- The security reviewer reports bugs, breaking changes, and security findings
+  with `High`, `Medium`, or `Low` tags.
+- The code-quality reviewer reports maintainability and structure concerns
+  with `Blocker`, `Major`, or `Minor` tags.
+
+The parent calls both through the harness `task` tool. They inherit the root
+agent's execution surface and read the same `pr/` workspace. The prompt asks
+the parent not to rewrite either reply. The review body trims the combined
+text and caps it at 16,000 characters.
+
+Findings are informational. A high-severity finding doesn't veto the stamp.
+That policy is explicit in the root instructions and approval code.
+
+## Trace GitHub channel behavior
+
+The channel uses `githubChannel` with:
+
+- a configured repository allowlist on the account-linked GitHub transport,
+- a second optional `APPROVAL_BUDDY_REPOS` wake filter,
+- `deliverReplies: false`,
+- progress reactions disabled, and
+- event handlers for turn start, `approve_pr` results, and failed turns.
+
+The source requests `contents-write`, even though the documented workflow
+posts reviews, statuses, and comments. When adapting the example, start with
+`pr-write` and opt up only if a tool must push code.
+
+Every terminal status is green by design. Declines and crashed turns are
+informational, not merge-blocking. This is a product decision in the example,
+not an agentkit default.
+
+A successful turn that never calls `approve_pr` leaves the pending status in
+place. The channel clears it on `approve_pr` results and `turn.failed`, but
+has no `turn.completed` fallback.
+
+`github replay` reaches the same channel and can post a real approval, status,
+or comment. Use replay only against a repository and PR created for this
+test.
+
+## Use Slack for explicit requests
+
+Start the dev server:
+
+```bash
+agentkit dev examples/approval-buddy
+```
+
+Then ask through the signed-in account-linked Slack connection:
+
+> Would this PR qualify for a stamp?
+
+The instructions route qualification questions to `prepare_review` only. A
+stamp request runs the complete flow and may approve the PR.
+
+This channel uses the account-linked transport instead of a dedicated Socket
+Mode app.
+
+## See how durable storage fits
+
+`defineStorage` replaces the default local session store with a shared,
+durable key-value adapter. Approval Buddy chooses:
+
+- a 15-second write debounce,
+- startup restoration for up to 200 sessions, and
+- a 14-day restore window.
+
+That policy fits long-lived Slack threads and a small webhook fleet. The
+security reviewer uses the same adapter with lazy restore, which fits its
+shorter sessions.
+
+## Run the regression suite
+
+List the four eval cases:
+
+```bash
+agentkit eval --dir examples/approval-buddy --list
+```
+
+The suite covers:
+
+- buddy-list routing,
+- declining a merged PR,
+- using only `prepare_review` for a qualification question, and
+- the combined findings headings and severity format over seeded evidence.
+
+Run the safe qualification case:
+
+```bash
+agentkit eval \
+  --dir examples/approval-buddy \
+  qualify/merged-pr-question \
+  --json
+```
+
+The qualification case reads a live merged PR. The seeded format case shown
+by `--list` uses a planted auth-bypass diff
+and checks for a `task` call, both headings, and severity tags. It doesn't
+prove both named subagents ran or whether their output reached `approve_pr`.
+Unit tests under `agent/lib/` cover policy, self-approval handling, evidence
+limits, status mapping, GIF selection, and severity parsing.
+
+## Reuse the policy boundary
+
+Keep these properties when you replace the buddy policy:
+
+1. Put authorization in typed code.
+2. Fetch the source of truth inside both prepare and mutate steps.
+3. Give the model evidence only after the request qualifies.
+4. Treat specialist findings as data, not authority.
+5. Keep the core domain mutation in one named tool. Treat channel status and
+   visibility writes as separate, audited effects.
+6. Add a human approval gate if your policy still needs operator consent.
+7. Test read-only routing separately from mutation.
+
+## Where to go next
+
+- [GitHub](../guides/github.md)
+- [Tools](../reference/tools.md)
+- [Subagents](../reference/subagents.md)
+- [Storage](../storage.md)
+- [Slack](../guides/slack.md)
+- [Evals](../evals.md)

package/docs/example-agents/benny.md

@@ -0,0 +1,186 @@
+---
+title: "Route Slack work through repository playbooks"
+description: "Combine account-linked chat, allowlisted Socket Mode channel watching, inherited repository skills, and a custom local workspace."
+---
+
+# Route Slack work through repository playbooks
+
+This agent is a Slack teammate for a product team. Mentions and direct
+messages reach it through an account-linked transport. New top-level posts in
+an allowlisted issue channel reach it through a dedicated Slack app, even
+without a mention. The agent then selects a repository playbook for triage,
+reproduction, fixes, reviews, on-call work, or design critique.
+
+Use this example when Slack is the intake surface and your durable procedures
+already live as repository skills.
+
+[Browse the current playbook-router source.](../../examples/benny/)
+
+## Combine two Slack transports with repo skills
+
+The playbook router uniquely combines three decisions:
+
+- Two Slack transports serve different engagement modes.
+- `local.cwd` keeps session workspaces inside the monorepo.
+- Instructions route work to inherited repository playbooks
+  instead of authored `agent/skills/`.
+
+The result is a thin agent project over a mature procedure library.
+
+## Follow an issue report
+
+1. A teammate creates a top-level post in the allowlisted issue channel.
+2. The dedicated Socket Mode channel accepts the allowlisted channel.
+3. A 15-second debounce lets edits settle. Deleting the post during that
+   window cancels the dispatch.
+4. Agentkit creates a thread-scoped session and sends the report to the
+   playbook router.
+5. The instructions select the matching triage playbook.
+6. The harness finds the repository root, opens the inherited playbook, and
+   follows its procedure.
+7. The agent posts only in the source thread and reports the evidence it
+   gathered.
+
+Mentions and direct messages follow the same agent instructions. They don't
+need the watched-channel path.
+
+## Map the playbook router files
+
+| File | Purpose |
+| --- | --- |
+| [`agent/agent.ts`](../../examples/benny/agent/agent.ts) | Names the agent, selects its model, and keeps the harness under `.agent-serve/harness`. |
+| [`agent/instructions.md`](../../examples/benny/agent/instructions.md) | Defines engagement rules, evidence policy, and the playbook routing map. |
+| [`agent/channels/slack.ts`](../../examples/benny/agent/channels/slack.ts) | Handles account-linked mentions and direct messages. |
+| [`agent/channels/slack-app.ts`](../../examples/benny/agent/channels/slack-app.ts) | Runs the dedicated app and watches one allowlisted channel. |
+| [`evals/smoke.eval.ts`](../../examples/benny/evals/smoke.eval.ts) | Checks the agent identity and expected triage route. |
+
+The playbook router authors no tools, MCP connections, subagents, schedules, hooks, A/B
+experiments, or sandbox seeds.
+
+## See why `local.cwd` matters
+
+Agentkit normally keeps an ephemeral `run` or `eval` workspace outside a
+large monorepo. This prevents ancestor instruction and repository-rule files
+from leaking into an unrelated agent.
+
+The playbook router needs the opposite. Its procedures live at the repository
+root, so
+`agent.ts` sets:
+
+```ts
+local: {
+  cwd: ".agent-serve/harness",
+}
+```
+
+Each harness workspace lands under
+`examples/benny/.agent-serve/harness/<sessionId>`. Walking up the directory
+tree reaches the host repository and its inherited playbook directory.
+
+Those playbooks are inherited context. `agentkit info` reports zero authored
+skills for the agent. Copying this project into another repository removes
+its main procedures unless you copy or replace the skill library too.
+
+## Connect both Slack paths
+
+The account-linked path needs an agent-runtime login and a connected Slack
+account:
+
+```bash
+agentkit login
+agentkit whoami
+```
+
+It routes explicit mentions without a dedicated Slack token on the host.
+
+For the watched-channel path, configure a dedicated Socket Mode app with:
+
+- subscribe to `message.channels` and `message.groups`,
+- have an App-Level Token with `connections:write`, and
+- be a member of the watched channel.
+
+Run `agentkit slack setup` for the guided app workflow. Generate the project
+manifest with `--channel-posts` when you create a new copy, then validate the
+configured channel prefix with `agentkit slack doctor`.
+
+Missing dedicated-app tokens leave that channel idle. They don't stop the
+account-linked channel.
+
+## Validate and start the server
+
+```bash
+agentkit validate --dir examples/benny
+agentkit info --dir examples/benny --json
+agentkit dev examples/benny
+```
+
+The info output should show two Slack channels and no authored skill. That
+combination confirms the example is using inherited playbooks.
+
+## Exercise each engagement mode
+
+Test the explicit account-linked path by asking:
+
+> Which playbook would you use to triage a product UI bug?
+
+Test the dedicated app:
+
+1. Create a top-level post in the allowlisted issue channel.
+2. Don't mention the bot.
+3. Wait for the debounce window.
+4. Confirm the agent replies in the post's thread.
+
+Thread replies don't trigger the proactive watch. Mentions still use Slack's
+normal mention path. Bot-authored posts are ignored to prevent loops.
+
+The channel uses the default handler after filtering. It doesn't apply a
+second code-level classifier, so every accepted top-level post spends a model
+turn and reaches the prompt.
+
+## Inspect thread continuity
+
+Agentkit keys Slack sessions by channel and thread timestamp. A follow-up in
+the same thread resumes the conversation and workspace. A new top-level issue
+gets a new session.
+
+This lets a playbook gather evidence over several turns without mixing two
+reports. The playground shows both the account-linked and dedicated-app
+sessions while the dev server runs.
+
+## Run the smoke eval
+
+```bash
+agentkit eval --dir examples/benny --list
+agentkit eval --dir examples/benny smoke --json
+```
+
+The case asks for the agent identity and the playbook used for issue triage.
+It checks the configured identity and route label.
+
+This is a lexical smoke test. It doesn't prove Slack delivery, skill
+selection, skill loading, procedure execution, or thread-only behavior. Add
+fixture-backed evals around the playbooks when you reuse this design.
+
+## Build a playbook-routed teammate
+
+Use this structure when your organization already has tested skills:
+
+1. Put the playbooks under a stable repository path.
+2. Set `local.cwd` so harness workspaces can inherit that path.
+3. Write a short routing table in `instructions.md`.
+4. Use account-linked Slack for explicit requests.
+5. Add a dedicated app only for allowlisted proactive intake.
+6. Keep the channel allowlist narrow and debounce edited posts.
+7. Add an eval for every important request-to-playbook route.
+
+If the procedures should ship with the agent, put them under
+`agent/skills/` instead. Authored skills appear in the manifest and travel
+with the project.
+
+## Where to go next
+
+- [Slack](../guides/slack.md)
+- [Agent config](../reference/agent-config.md)
+- [Skills](../reference/skills.md)
+- [Sessions and streaming](../reference/sessions.md)
+- [Evals](../evals.md)

package/docs/example-agents/bugbot.md

@@ -0,0 +1,231 @@
+---
+title: "Review prepared pull-request evidence"
+description: "Fetch a PR on the host, seed a trimmed diff-first workspace, and run a GitHub-read-only review through HTTP, Slack, or an eval."
+---
+
+# Review prepared pull-request evidence
+
+This GitHub-read-only reviewer uses host code to fetch the PR
+with `gh` and `git`, builds a trimmed `pr/` evidence tree, then hands that tree
+to the model. The model reads the diff, loads a review skill, and returns at
+most three high-confidence findings.
+
+Use this example when the host should control evidence collection and the
+model shouldn't browse or mutate the source repository.
+
+[Browse the current reviewer source.](../../examples/bugbot/)
+
+## Separate evidence preparation from review
+
+The reviewer separates preparation from judgment:
+
+- Host code owns GitHub and Git access.
+- A server tool turns untrusted PR input into bounded workspace files.
+- A custom channel seeds those files before the model starts.
+- An on-demand skill defines the review procedure and output contract.
+- The model returns chat text. No path posts a GitHub review.
+
+This architecture gives the model a purpose-built evidence package instead of
+a checkout.
+
+## Follow a review
+
+The custom HTTP path runs this sequence:
+
+1. `POST /v1/channels/review/` receives a PR reference.
+2. The handler calls `prepare_pr` without a model turn.
+3. Host code reads PR metadata and the unified diff.
+4. It reuses a matching checkout, force-fetching the PR ref there when the
+   commit is missing. Without a matching checkout, it uses a temporary bare
+   cache.
+5. It creates `pr/MANIFEST.md`, `pr/meta.json`, `pr/diff.patch`, and selected
+   small files and rules.
+6. `send({ workspaceFiles })` creates the model session with that evidence.
+7. The model reads the manifest and diff, then loads `pr-review`.
+8. The channel returns session and playground URLs while the review streams.
+
+If a normal chat starts without evidence, the model can call `prepare_pr`
+mid-turn. That form writes the same files into the active session workspace.
+
+## Map the evidence-review files
+
+| File | Purpose |
+| --- | --- |
+| [`agent/agent.ts`](../../examples/bugbot/agent/agent.ts) | Selects the local runtime and model. |
+| [`agent/instructions.md`](../../examples/bugbot/agent/instructions.md) | Requires diff-first review and confines model work to `pr/`. |
+| [`agent/tools/prepare_pr.ts`](../../examples/bugbot/agent/tools/prepare_pr.ts) | Exposes host preparation as a typed server tool. |
+| [`agent/lib/prepare-pr.ts`](../../examples/bugbot/agent/lib/prepare-pr.ts) | Parses PR references, runs `gh` and `git`, and builds the evidence map. |
+| [`agent/channels/review.ts`](../../examples/bugbot/agent/channels/review.ts) | Provides the loopback-only prepare-and-send HTTP route. |
+| [`agent/channels/slack.ts`](../../examples/bugbot/agent/channels/slack.ts) | Extracts PR references and prepares evidence for mentions and direct messages. |
+| [`agent/skills/pr-review.md`](../../examples/bugbot/agent/skills/pr-review.md) | Sets finding limits, severities, and the machine-readable review format. |
+| [`evals/review/smoke.eval.ts`](../../examples/bugbot/evals/review/smoke.eval.ts) | Seeds fake evidence and checks the review path without GitHub. |
+
+There is no authored GitHub channel, MCP connection, subagent, schedule,
+hook, A/B experiment, approval, or custom storage.
+
+## Prepare the host
+
+You need:
+
+- Node 22.13 or newer.
+- An agent-runtime credential for model turns and account-linked Slack.
+- `gh` and `git` on `PATH`.
+- `gh` access to the target PR.
+- Network access to GitHub and a writable temporary directory.
+
+The preparer can prefer a configured local checkout. Its `origin` must match
+the target repository. Otherwise the reviewer uses its bare cache. It never
+checks out the PR into the serve host's working tree.
+
+## Validate the surface
+
+```bash
+agentkit validate --dir examples/bugbot
+agentkit info --dir examples/bugbot --json
+```
+
+The manifest should show one server tool, one skill, and two authored
+channels.
+
+## Inspect evidence without a model turn
+
+Call the preparation tool directly:
+
+```bash
+agentkit call prepare_pr \
+  --dir examples/bugbot \
+  --input '{"pr":"https://github.com/owner/repo/pull/123"}'
+```
+
+Direct tool calls use a scratch workspace removed after the call.
+`prepare_pr` detects this path and returns the complete file map in its
+result. In a model session, it writes the files and returns a smaller summary.
+
+The evidence builder applies explicit limits:
+
+| Evidence | Limit |
+| --- | --- |
+| Post-change file | 12,000 characters |
+| One rule file | 8,000 characters |
+| Combined rules | 12,000 characters |
+| PR body in metadata | 2,000 characters |
+
+Large files remain visible in `diff.patch`. The manifest records which full
+files or rules were omitted.
+
+The per-file limits aren't an aggregate context cap. Every changed file below
+12,000 characters can be included. The diff command has a 12 MiB output
+buffer; a larger diff fails preparation instead of being truncated.
+
+## Run the HTTP review path
+
+Start the server:
+
+```bash
+agentkit dev examples/bugbot
+```
+
+From another terminal:
+
+```bash
+curl -s -X POST \
+  http://127.0.0.1:3000/bugbot/v1/channels/review/ \
+  -H 'content-type: application/json' \
+  -d '{"pr":"https://github.com/owner/repo/pull/123"}'
+```
+
+The route returns `status: "started"`, a continuation token, and session and
+playground URLs. Open the session URL to watch the model read the evidence and
+produce findings.
+
+The channel declares `localDevStrict()`. Direct loopback callers can use it.
+Proxy-forwarding headers and non-loopback hosts are rejected.
+
+Send a follow-up by passing the returned key:
+
+```bash
+curl -s -X POST \
+  http://127.0.0.1:3000/bugbot/v1/channels/review/ \
+  -H 'content-type: application/json' \
+  -d '{"pr":"owner/repo#123","key":"<continuation-token>"}'
+```
+
+The follow-up resumes the session without fetching a new evidence tree.
+
+## Run the Slack path
+
+The account-linked Slack channel handles review-bot mentions and direct
+messages:
+
+> Review https://github.com/owner/repo/pull/123
+
+Slack handlers don't receive the channel `callTool` helper. This example calls
+the shared `preparePrReview` host function, then returns `workspaceFiles` in
+the Slack message preparation result. The model sees the same evidence and
+prompt as the HTTP path.
+
+If a message contains no PR reference, the handler asks for one. Thread
+follow-ups keep the same session.
+
+## See how the skill constrains review
+
+`pr-review.md` tells the model to:
+
+- read the manifest and unified diff first,
+- open at most one supporting file or rules file when a hunk is ambiguous,
+- avoid shell, network, `gh`, and `git`,
+- report no more than three findings,
+- keep each description under 120 words, and
+- emit the machine-readable review contract.
+
+The root instructions set the evidence boundary. The skill holds the reusable
+review procedure. Keeping those roles separate lets another agent reuse the
+same skill with different intake channels.
+
+## Run the fixture-backed eval
+
+```bash
+agentkit eval --dir examples/bugbot --list
+agentkit eval --dir examples/bugbot review/smoke --json
+```
+
+The eval constructs a `PreparedPrReview`, seeds its file map through
+`workspaceFiles`, and checks for at least one read call with no shell call. It
+doesn't assert which evidence file was read or whether the skill loaded. It
+accepts either a formatted review or a clean result.
+
+This case tests review behavior without GitHub credentials or network data.
+Add fixtures with reachable bugs when you need stricter location and severity
+checks.
+
+## Keep the side-effect boundary clear
+
+The reviewer makes no remote GitHub writes. It doesn't author a GitHub channel and
+doesn't call a review API. Host preparation does write session evidence and
+force-update `refs/pull/<N>/head` in either its bare cache or a matching local
+checkout when the commit is missing. Every result ends with a note saying no
+GitHub review was posted.
+
+If you add publishing later, keep it in a separate tool. This preserves a
+read-only preparation and review path safe to run in evals.
+
+## Reuse the evidence handoff
+
+Use host-prepared workspaces when:
+
+- external APIs should stay off the model's tool surface,
+- context needs hard size limits,
+- the model should inspect a snapshot instead of a live checkout, or
+- several channels need the same preparation.
+
+Return `workspaceFiles` from direct host preparation, write into
+`ctx.workspaceDir` for mid-turn recovery, and encode the reading order in both
+the manifest and a skill.
+
+## Where to go next
+
+- [Webhooks and custom channels](../guides/webhooks.md)
+- [Tools](../reference/tools.md)
+- [Skills](../reference/skills.md)
+- [Slack](../guides/slack.md)
+- [Evals](../evals.md)