@cursor/july 0.1.93 → 0.1.95

package/docs/example-agents/knowledge-base.md

@@ -1,173 +0,0 @@
----
-title: "Build a team knowledge base through conversation"
-description: "Teach an agent about people, systems, decisions, and preferences; store that knowledge as markdown and retrieve it in fresh sessions."
----
-
-# Build a team knowledge base through conversation
-
-Knowledge base turns conversations into shared team context. Teach the agent
-about people, systems, decisions, and standing preferences. Three server
-tools read, search, and write human-readable markdown pages; a conventions
-skill shapes each write; and a daily schedule merges duplicates and rebuilds
-the index. A fresh session retrieves what an earlier conversation captured.
-
-Use this project when people should curate organizational knowledge through
-chat. Use [Codebase wiki](./codebase-wiki.md) when merged PRs should maintain
-feature documentation instead.
-
-[Browse the knowledge base source.](../../examples/knowledge-base/)
-
-## Keep shared knowledge on the filesystem
-
-The knowledge base lives outside any session workspace, in a wiki
-directory on the serve host by default. `KNOWLEDGE_BASE_DIR` overrides the location,
-and the tools resolve it on every call, so tests and evals can point the same
-code at a temp directory.
-
-The store enforces its own safety:
-
-- Page ids are one to three lowercase kebab-case segments, so a page id
-  can't escape the wiki directory.
-- Pages cap at 64 KiB. Oversized writes fail with instructions to split
-  the page.
-- `wiki_write` replaces whole pages. The instructions require reading a
-  page before updating it, so rewrites carry existing facts forward.
-
-Every page is plain markdown. You can open the wiki in an editor,
-review it in a PR, or grep it.
-
-## Follow a fact through the agent
-
-1. You tell the agent something durable: a system, an owner, a standing
-   preference.
-2. The instructions require a `wiki_search` before claiming knowledge
-   and a `wiki_write` after learning something worth keeping.
-3. The `wiki-conventions` skill picks the page id (`staging-database`,
-   `people/jane-doe`), the page shape, and the dated fact format.
-4. The tool writes the page under the durable wiki root and returns
-   whether it created or updated the page.
-5. A later session, on any channel, finds the fact with `wiki_search`
-   and cites the knowledge-base page in its answer.
-
-Ephemeral chatter stays out. The instructions tell the model to skip
-one-off questions and to ask before saving anything borderline.
-
-## Map the knowledge-base files
-
-| File | Purpose |
-| --- | --- |
-| [`agent/agent.ts`](../../examples/knowledge-base/agent/agent.ts) | Selects the local runtime and model. |
-| [`agent/instructions.md`](../../examples/knowledge-base/agent/instructions.md) | Sets the read-before-answer and save-after-learning policy. |
-| [`agent/lib/wiki-store.ts`](../../examples/knowledge-base/agent/lib/wiki-store.ts) | Validates page ids, lists, reads, writes, and searches the knowledge base. |
-| [`agent/tools/wiki_read.ts`](../../examples/knowledge-base/agent/tools/wiki_read.ts) | Reads one page or lists every page with titles and timestamps. |
-| [`agent/tools/wiki_search.ts`](../../examples/knowledge-base/agent/tools/wiki_search.ts) | Searches titles and bodies with per-page match lines. |
-| [`agent/tools/wiki_write.ts`](../../examples/knowledge-base/agent/tools/wiki_write.ts) | Creates or replaces a page and reports created versus updated. |
-| [`agent/skills/wiki-conventions.md`](../../examples/knowledge-base/agent/skills/wiki-conventions.md) | Names pages, shapes them, and dates every fact. |
-| [`agent/schedules/gardener.md`](../../examples/knowledge-base/agent/schedules/gardener.md) | Merges duplicates, rebuilds the index, and flags stale facts daily. |
-| [`agent/lib/wiki-store.test.ts`](../../examples/knowledge-base/agent/lib/wiki-store.test.ts) | Unit-tests slug safety and store round-trips. |
-| [`agent/storage.ts`](../../examples/knowledge-base/agent/storage.ts) | Persists sessions and events with `cursorHostedStorage`. |
-| [`evals/evals.config.ts`](../../examples/knowledge-base/evals/evals.config.ts) | Caps eval run concurrency. |
-| [`evals/knowledge.eval.ts`](../../examples/knowledge-base/evals/knowledge.eval.ts) | Seeds a temp knowledge base and gates recall, save, and no-write decisions. |
-
-There is no authored channel, MCP connection, subagent, hook, or A/B
-experiment. The wiki directory is the durable knowledge store.
-
-## Prepare the example
-
-You need:
-
-- Node 22.13 or newer.
-- An agent-runtime credential for model turns.
-
-Nothing else. The wiki is created on first write.
-
-## Validate the surface
-
-```bash
-agent-sdk validate --dir examples/knowledge-base
-agent-sdk info --dir examples/knowledge-base --json
-```
-
-The manifest should report three server tools, one skill, and one
-schedule.
-
-## Exercise the store without a model turn
-
-```bash
-agent-sdk call wiki_write \
-  --dir examples/knowledge-base \
-  --input '{"page":"staging-database","content":"# Staging database\n\n- Port: 6432 (recorded 2026-07-19)\n"}'
-
-agent-sdk call wiki_search \
-  --dir examples/knowledge-base \
-  --input '{"query":"6432"}'
-
-agent-sdk call wiki_read --dir examples/knowledge-base --input '{}'
-```
-
-Invalid page ids fail fast. Try `{"page":"../escape"}` and the tool
-returns the validation error instead of touching the filesystem.
-
-## Prove recall across sessions
-
-```bash
-agent-sdk dev examples/knowledge-base
-```
-
-Teach it something in the playground:
-
-> Remember: our staging database is Postgres at
-> staging-db.internal.example.com, port 6432 via PgBouncer. Jane Doe
-> owns it.
-
-The trace shows the conventions skill load, then `wiki_write` calls
-for `staging-database`, `people/jane-doe`, and `index`. Start a new
-session and ask:
-
-> What port does our staging database use, and who owns it?
-
-The fresh session finds the answer with `wiki_search` and `wiki_read`
-and cites the pages. The conversation history is empty; the wiki is the
-source of truth.
-
-## Run the gardener
-
-The `gardener` schedule fires at 06:00 UTC and rewrites the wiki for
-consistency: merge near-duplicate pages, rebuild `index`, and flag
-facts older than 90 days. Under `agent-sdk dev`, timers don't auto-fire.
-Trigger it by hand:
-
-```bash
-curl -s -X POST http://127.0.0.1:3000/knowledge-base/v1/dev/schedules/gardener
-```
-
-## Run the evals
-
-```bash
-agent-sdk eval --dir examples/knowledge-base --list
-agent-sdk eval --dir examples/knowledge-base knowledge/recall
-```
-
-The eval file seeds a temp directory through `KNOWLEDGE_BASE_DIR`
-inside the cases, so the durable knowledge base never sees test data.
-`knowledge/recall` proves the fact comes from disk, not the conversation.
-`knowledge/save`
-gates the write decision, and `knowledge/no-write-on-ephemera` proves small
-talk stays out of the knowledge base.
-
-## Reuse the knowledge-base pattern
-
-Copy this shape when an agent needs durable, inspectable team knowledge:
-
-- Resolve the storage root lazily behind an environment override.
-- Validate identifiers in the store, not in the prompt.
-- Put naming and structure conventions in a skill so writes stay
-  consistent.
-- Add a consolidation schedule instead of letting pages rot.
-
-## Where to go next
-
-- [Tools](../reference/tools.md)
-- [Skills](../reference/skills.md)
-- [Schedules](../reference/schedules.md)
-- [Evals](../evals.md)

package/docs/example-agents/oncall.md

@@ -1,217 +0,0 @@
----
-title: "Investigate every alert in its own Slack thread"
-description: "Watch a bot-fed alerts channel, react when the agent locks in, coalesce thread chatter behind a quiet window, and let the agent schedule its own re-checks."
----
-
-# Investigate every alert in its own Slack thread
-
-This agent is an on-call teammate. Alert feeds post into an alerts channel
-as bots. Each new alert dispatches an investigation session pinned to that
-post's thread: the agent reacts 👀 the moment it locks in, investigates
-immediately, and posts brief findings backed by evidence it observed.
-Replies in the thread reach it only after the thread has been quiet for
-about a minute, and reminder tools let it wake itself later to re-check a
-baseline or confirm an alert cleared.
-
-Use this example when alerts land in Slack and you want one thread-scoped
-investigation per alert, with an agent that paces its own engagement
-instead of answering every message.
-
-[Browse the current alert-investigator source.](../../examples/oncall/)
-
-## Follow an alert
-
-1. An alert feed (Alertmanager, PagerDuty, Datadog) posts a new top-level
-   message in the watched alerts channel.
-2. The channel watch accepts it. `includeBotPosts` lets bot authors
-   through; the agent's own posts always stay dropped.
-3. The handler reacts 👀 on the alert post and sets "Investigating…"
-   typing. The reaction is the lock-in signal: this alert has an owner.
-4. The Agent SDK creates a session keyed to the alert's thread and dispatches
-   immediately. New alerts get no debounce.
-5. The agent reads the alert, gathers evidence, and posts findings to the
-   thread once it has a hypothesis.
-6. People discuss in the thread. Replies buffer per thread and dispatch as
-   one coalesced follow-up after roughly a minute of quiet.
-7. The agent arms reminders for anything that needs time and posts interim
-   updates when new evidence changes the picture.
-
-Mentions and DMs skip the watch entirely and behave like ordinary chat.
-
-## Map the files
-
-| File | Purpose |
-| --- | --- |
-| [`agent/agent.ts`](../../examples/oncall/agent/agent.ts) | Names the agent and keeps harness workspaces outside any monorepo checkout. |
-| [`agent/instructions.md`](../../examples/oncall/agent/instructions.md) | Engagement rules, the investigation loop, and the message discipline. |
-| [`agent/channels/slack-app.ts`](../../examples/oncall/agent/channels/slack-app.ts) | Dedicated Socket Mode app: watch configuration and handler wiring. |
-| [`agent/lib/alert-watch.ts`](../../examples/oncall/agent/lib/alert-watch.ts) | The engagement policy: lock in on new alerts, coalesce replies. |
-| [`agent/lib/thread-debounce.ts`](../../examples/oncall/agent/lib/thread-debounce.ts) | Per-thread quiet window. |
-| [`agent/lib/alerts.ts`](../../examples/oncall/agent/lib/alerts.ts) | Dispatch classification, prompt building, and thread addressing. |
-| [`agent/lib/slack-api.ts`](../../examples/oncall/agent/lib/slack-api.ts) | Reactions and thread posts on this agent's own token pair. |
-| [`agent/tools/reminders_create.ts`](../../examples/oncall/agent/tools/reminders_create.ts) | Self-scheduled wakes bound to the thread (plus `reminders_list` and `reminders_cancel`). |
-| [`agent/tools/post_thread_update.ts`](../../examples/oncall/agent/tools/post_thread_update.ts) | Interim updates to the thread mid-turn. |
-| [`agent/storage.ts`](../../examples/oncall/agent/storage.ts) | Persists sessions and events with `cursorHostedStorage`. |
-| [`evals/evals.config.ts`](../../examples/oncall/evals/evals.config.ts) | Caps eval run concurrency. |
-| [`evals/smoke.eval.ts`](../../examples/oncall/evals/smoke.eval.ts) | Checks identity and the reminder-tool route. |
-
-## Let bot posts through the watch
-
-Channel watching drops bot-authored posts by default so two agents can
-never feed each other. Alert channels invert the assumption: the posts
-worth watching come from bots. `channelPosts.includeBotPosts` opts in per
-channel:
-
-```ts
-engagement: {
-  channelPosts: {
-    allow: ["#alerts"],
-    posts: "all",
-    includeBotPosts: true,
-  },
-},
-```
-
-Loop safety survives the opt-in. The pack matches the watching app's own
-posts by the `bot_id` and bot user id from `auth.test` and drops them, so
-the agent's findings never re-dispatch it. Posts that mention the bot stay
-on the mention path.
-
-`posts: "all"` also delivers thread replies. The handler, not the pack,
-decides their pace.
-
-## Pace the engagement
-
-The example runs two rhythms:
-
-- A new alert dispatches immediately.
-- Thread replies produce one engagement per lull.
-
-The pack's `debounceMs` is per message; it exists to let edits settle. This
-agent needs a per-thread window instead, so the handler owns it
-([`lib/thread-debounce.ts`](../../examples/oncall/agent/lib/thread-debounce.ts)).
-Every reply restarts a 60-second timer keyed by thread. Superseded waiters
-resolve `null` and the handler returns `null` for them. When the thread
-goes quiet, the newest waiter receives the whole batch and dispatches one
-follow-up that lists every message with mentionable attribution.
-
-Two details make the window matter. A follow-up that arrives while a turn
-runs preempts that turn (latest message wins), so engaging per message
-would keep cancelling the investigation. And @mentions bypass the window
-through Slack's mention path, so a person who needs the agent now still
-gets it now.
-
-## Schedule your own re-checks
-
-Investigations rarely finish in one pass. A baseline comparison needs 20
-minutes of data. An alert that cleared may re-fire. The example hands the
-model three tools over `host.reminders`:
-
-- `reminders_create` arms a one-shot (`delay: "20m"`) or recurring
-  (`every: "30m"` with a plain-language stop condition) wake bound to the
-  thread's conversation.
-- `reminders_list` shows the thread's standing watches.
-- `reminders_cancel` disarms one, and refuses ids that belong to another
-  thread's conversation.
-
-When a reminder fires, its prompt returns to the same session as a
-follow-up turn, and the reply lands in the alert thread. The instructions
-keep wake prompts generic (re-read live state instead of replaying stale
-numbers) and wake replies to one line, for example "re-checked p99 on
-api-gateway: 120ms, back at baseline, cancelling the watch."
-
-Keep these tool filenames if you copy the design: the framework's reminder
-fire prompt tells the model to call `reminders_cancel` by name when a stop
-condition is set.
-
-## Alert people mid-investigation
-
-The final reply of each turn posts to the thread on its own.
-`post_thread_update` covers evidence that shouldn't wait for the turn to
-finish: it posts a one-or-two-sentence update through the agent's token,
-with `<@USERID>` mentions for the people who need to act. The instructions
-restrict it to changes in hypothesis, severity, or blast radius. Progress
-narration doesn't qualify.
-
-## Connect the Slack app
-
-Channel watching is Socket Mode only, so this example uses a dedicated
-app:
-
-```bash
-agent-sdk slack create --dir examples/oncall --name "Oncall" --channel-posts
-agent-sdk slack doctor --prefix ONCALL
-```
-
-`--channel-posts` prefills channel-watch events (`message.channels` /
-`message.groups`). Invite the bot to each watched channel after the
-wizard finishes.
-
-`ONCALL_ALERTS_CHANNELS` sets the watch list as comma-separated ids or
-`#names`. It defaults to `#alerts`.
-
-Wire observability MCP servers under `agent/mcp-connections/` so evidence
-gathering reaches your logs, metrics, and dashboards. The example ships
-none; without them the agent works from the alert text, its links, and the
-thread.
-
-## Validate and start the server
-
-```bash
-agent-sdk validate --dir examples/oncall
-agent-sdk info --dir examples/oncall --json
-agent-sdk dev examples/oncall
-```
-
-The info output lists four server tools and the watched channel on the
-`slack-app` channel. Missing tokens leave that channel idle without
-stopping the server.
-
-In dev mode, reminder timers don't auto-fire. List and fire them by hand
-through the dev routes described in
-[Schedules and reminders](../reference/schedules.md#dispatch-and-dev-mode).
-
-## Test the policy without Slack
-
-The engagement policy is plain code with unit tests:
-
-```bash
-pnpm exec vitest run examples/oncall
-```
-
-The integration test drives a synthetic Events API delivery through the
-real parse, watch, and dispatch plumbing. It asserts a bot alert
-dispatches pinned to its thread after the lock-in reaction, the agent's
-own posts never loop, and replies coalesce behind the quiet window.
-
-The smoke eval spends a model turn:
-
-```bash
-agent-sdk eval --dir examples/oncall smoke --json
-```
-
-It checks identity and the reminder-tool route lexically. It doesn't prove
-Slack delivery or reaction behavior; the unit tests cover the dispatch
-side, and a live check needs the dedicated app connected.
-
-## Build an alert investigator
-
-Use this structure when a bot feed should drive thread-scoped work:
-
-1. Watch the feed channel with `includeBotPosts: true` and a narrow
-   allowlist.
-2. Acknowledge on the triggering post before dispatching, so people see
-   ownership without opening the thread.
-3. Dispatch new items immediately; coalesce thread chatter behind a
-   per-thread quiet window.
-4. Give the agent reminder tools for anything that needs time, and make
-   cancel discipline part of the instructions.
-5. Keep every posted message brief and tied to evidence the agent saw.
-
-## Where to go next
-
-- [Slack](../guides/slack.md)
-- [Schedules and reminders](../reference/schedules.md)
-- [Tools](../reference/tools.md)
-- [Playbook router](./benny.md) for the human-post variant of channel
-  watching

package/docs/example-agents/security-reviewer.md

@@ -1,270 +0,0 @@
----
-title: "Run staged security reviews from GitHub events"
-description: "Orchestrate parallel reviewer agents, streamed triage, deterministic stages, live playground progress, durable sessions, and severity A/B metrics."
----
-
-# Run staged security reviews from GitHub events
-
-Security Reviewer turns a pull request into a staged host-side review. One
-tool prepares the diff and selects modules. A second fans out specialized
-reviewers and triages candidates as they arrive. A third deduplicates the
-confirmed findings, writes artifacts, and may publish a GitHub review.
-
-Use this example when the workflow needs several model workers, but the host
-must own orchestration, progress, artifacts, and the final write.
-
-Source lives under [`factory/security-reviewer/`](../../../../factory/security-reviewer/) (factory agent, not under `examples/`).
-
-Want one model turn and one comment? Scaffold the
-[security-reviewer template](../templates/security-reviewer.md).
-
-[Browse the Security Reviewer source.](../../../../factory/security-reviewer/)
-
-## Run a three-stage host pipeline
-
-Security Reviewer is a pipeline, not one long agent turn:
-
-| Stage | Tool | Result |
-| --- | --- | --- |
-| Prepare | `prepare_review` | Fetch metadata and diff, create a `runId`, and select security modules. |
-| Review and triage | `run_reviewers` | Run module reviewers in parallel and start triage as each candidate arrives. |
-| Finalize | `finalize_review` | Apply thresholds, deduplicate findings, write artifacts, and optionally post a review. |
-
-`run_triage` remains available as a compatibility stage. In the normal flow,
-triage has already completed inside `run_reviewers`, so it reports existing
-results. If candidates exist without triage output, it starts triage workers
-and writes their state.
-
-The configured root agent chooses and sequences tools in chat. The review
-workers use a model selected by the host pipeline. They are
-created programmatically with the agent SDK, not discovered from
-`agent/subagents/`.
-
-## Follow a GitHub review
-
-1. A pull request event starts a review and opens a playground session.
-2. The playground shows reviewer and triage progress.
-3. Confirmed findings appear in the PR review.
-4. A GitHub Check reports completion or a processing failure.
-
-## Map the framework features
-
-| Capability | Source | Role |
-| --- | --- | --- |
-| Root agent | [`agent/agent.ts`](../../../../factory/security-reviewer/agent/agent.ts), [`agent/instructions.md`](../../../../factory/security-reviewer/agent/instructions.md) | Configure local chat and explain the three-stage contract. |
-| Server tools | [`agent/tools/`](../../../../factory/security-reviewer/agent/tools/) | Expose each review stage to chat and host orchestration. |
-| GitHub channel | [`agent/channels/github.ts`](../../../../factory/security-reviewer/agent/channels/github.ts) | Filter wakes, run background tasks, and publish status. |
-| Progress channel | [`agent/channels/asr-progress.ts`](../../../../factory/security-reviewer/agent/channels/asr-progress.ts) | Serve live reviewer and triage state by `runId`. |
-| Playground renderer | [`agent/playground/tools/run_reviewers.tsx`](../../../../factory/security-reviewer/agent/playground/tools/run_reviewers.tsx) | Replace the generic tool chip with live module rows. |
-| SDK review pipeline | [`review-stages.ts`](../../../../factory/security-reviewer/agent/lib/review-stages.ts), [`@anysphere/security-review-lib`](../../../../packages/security-review-lib/src/index.ts) | Select modules, call model workers, triage, deduplicate, and write artifacts. |
-| Storage | [`agent/storage.ts`](../../../../factory/security-reviewer/agent/storage.ts) | Persist framework sessions with `cursorHostedStorage` (lazy restore). |
-| A/B | [`agent/ab.ts`](../../../../factory/security-reviewer/agent/ab.ts) | Compare all-severity versus high-only GitHub comments. |
-| Eval | [`evals/`](../../../../factory/security-reviewer/evals/) | Check stage-tool presence against a pinned sample. |
-
-There is no Slack channel, authored skill, discovered subagent, MCP
-connection, schedule, reminder, hook, tool approval, or cloud runtime.
-
-## Prepare the host
-
-You need:
-
-- Node 22.13 or newer.
-- An agent-runtime credential for the root turn and review workers.
-- GitHub read access for preparation.
-- GitHub write access for webhook-driven reviews and Checks.
-
-The pipeline exposes settings for:
-
-- the worker model,
-- reviewer and triage parallelism,
-- reviewer, triage, duplicate-gate, and final-dedupe timeouts, and
-- prior-comment loading.
-
-The active names live beside the orchestration in
-[`review-stages.ts`](../../../../factory/security-reviewer/agent/lib/review-stages.ts).
-
-## Validate the discovered agent
-
-```bash
-agent-sdk validate --dir ../../factory/security-reviewer
-agent-sdk info --dir ../../factory/security-reviewer --json
-agent-sdk eval --dir ../../factory/security-reviewer --list
-```
-
-`validate` should pass. `info` and `eval --list` should match the capabilities
-mapped above.
-
-## Know the chat path's write boundary
-
-In chat, the root instructions ask the model to use this order:
-
-```text
-prepare_review -> run_reviewers -> finalize_review
-```
-
-They also ask the model to set `postComment: true` only on request. This is
-prompt policy, not a deterministic safety gate. The model chooses tool
-arguments, and `finalize_review` has no human approval. Use the direct stage
-calls below when a no-post proof must be enforced.
-
-## Call stages directly without publishing
-
-Call each stage and pass `postComment: false` yourself:
-
-```bash
-agent-sdk call prepare_review \
-  --dir ../../factory/security-reviewer \
-  --input '{"prUrl":"https://github.com/owner/repo/pull/123"}'
-
-agent-sdk call run_reviewers \
-  --dir ../../factory/security-reviewer \
-  --input '{"runId":"<run-id>"}'
-
-agent-sdk call finalize_review \
-  --dir ../../factory/security-reviewer \
-  --input '{"runId":"<run-id>","postComment":false}'
-```
-
-Review state lives under the project's run-artifact directory, so later
-stages can open the prepared `runId`.
-
-> [!CAUTION]
-> `finalize_review` with `postComment: true` writes to GitHub. The webhook
-> path always requests that write. Chat instructions alone don't prevent it.
-
-## Watch parallel work in the playground
-
-Run the dev server:
-
-```bash
-agent-sdk dev ../../factory/security-reviewer
-```
-
-Open the printed playground and start a review. The custom
-`run_reviewers` renderer polls the progress channel's `GET /:runId` route.
-
-It refreshes every 500 ms while the stage runs. Each row shows a reviewer
-module's state, candidates, reviewed areas, and failure. A second section
-shows triage jobs and confirmed or rejected counts.
-
-This is an authored playground extension. The Agent SDK discovers it by the tool
-name, so the generic `run_reviewers` chip becomes a domain-specific view
-without changing the framework playground.
-
-## Fan out reviewers while triage starts
-
-Module selection uses repository and path rules. The current module set
-covers:
-
-- agent tooling trust boundaries,
-- privileged service RPCs,
-- product-specific security risks,
-- dependency and supply-chain changes,
-- deployment and infrastructure code,
-- filesystem and workspace boundaries,
-- privacy, and
-- general security review.
-
-Selected modules may run more than once. Candidates pass through a duplicate
-gate, then bounded triage. Reviewer or triage failures can produce partial
-results. A final dedupe failure stops finalization.
-
-The pipeline writes JSONL journals as work completes. Final artifacts include
-the review bundle, patch, reviewer outputs, candidates, triage decisions,
-findings, accounting, and audit events.
-
-## Separate session storage from review artifacts
-
-`cursorHostedStorage` keeps Agent SDK session and event records on
-Cursor-managed hosting. Security Reviewer sets `restore: "off"` so startup
-doesn't load old review sessions in bulk. A continuation lookup can still
-fetch a needed session. See [Storage](../storage.md).
-
-The staged review files are separate from session storage. Session-store
-durability doesn't preserve those files. All stages for one `runId` must see
-the same filesystem.
-
-This split is useful when conversation history needs shared durability but
-large review artifacts belong on attached storage or an object store.
-
-## Compare live comment variants
-
-The comment-severity experiment uses sticky session assignment with a 5%
-holdout:
-
-- `control` posts every finding.
-- `treatment` posts only high and critical findings.
-
-Finalization enforces the comment filter. The treatment also adds an
-instruction overlay asking chat and playground summaries to lead with high
-and critical findings. Full artifacts, `finalResponse`, and finding counts
-still include every finding. Stage-tool counters appear in the
-playground A/B view. Local sample and snapshot files persist under
-the project state directory.
-
-When a treatment session has only low or medium findings, the filtered review
-body currently says no vulnerabilities were found even though artifacts and
-status retain findings. Account for that mismatch before using this
-experiment as a publishing policy.
-
-Eval sessions skip A/B enrollment.
-
-## Test the GitHub channel carefully
-
-The channel uses the host's Cursor account repository scope. It wakes on
-`opened` and `synchronize`, skips drafts, and posts its own GitHub Check.
-
-Inspect its event surface:
-
-```bash
-agent-sdk github events \
-  --dir ../../factory/security-reviewer \
-  --json
-```
-
-Replay reaches the full publishing path:
-
-```bash
-TEST_PR_URL=https://github.com/your-org/allowlisted-test-repo/pull/123
-agent-sdk github replay \
-  "$TEST_PR_URL" \
-  --dir ../../factory/security-reviewer \
-  --action opened
-```
-
-Set `TEST_PR_URL` to a PR in the channel's configured repository allowlist.
-Run the command only against a PR intended for test reviews. It posts a
-GitHub Check and may post findings.
-
-## Inspect the eval before running it
-
-```bash
-agent-sdk eval --dir ../../factory/security-reviewer --list
-```
-
-The case gates the review flow and prevents comment posting. It still fetches
-the live PR, so it needs GitHub access.
-
-## Build another staged pipeline
-
-Use staged host orchestration when:
-
-- each phase needs its own timeout and artifact,
-- model workers should run in bounded parallel,
-- later work can start as soon as partial results arrive,
-- a webhook must acknowledge before the work finishes, or
-- operators need live progress beyond one tool spinner.
-
-Keep external writes in finalization. Pass a `runId` between stages, journal
-progress before publishing, and make partial-worker failures visible in the
-result.
-
-## Where to go next
-
-- [GitHub](../guides/github.md)
-- [Tools](../reference/tools.md)
-- [Channels](../reference/channels.md)
-- [Playground](../reference/playground.md)
-- [Storage](../storage.md)
-- [Live A/B metrics](../ab.md)
-- [Evals](../evals.md)