@cursor/july 0.1.92 → 0.1.94

package/docs/example-agents/fsd.md

@@ -1,334 +0,0 @@
----
-title: "Hand PR triage to managed remote agents"
-description: "Coordinate local chat, per-PR remote sessions, GitHub wake buffering, workflow MCP enrollment, durable affinity, findings, and reminders."
----
-
-# Hand PR triage to managed remote agents
-
-The remote PR coordinator keeps chat and routing on the local serve host,
-then hands each pull request to a managed remote agent with a real checkout.
-The same remote conversation resumes when a user drives the PR again, GitHub
-reports a change, or a merge-conflict reminder fires.
-
-This example is Cursor-internal. For your own repos, scaffold
-[PR autofixer](../templates/pr-autofixer.md) instead.
-
-The workflow backend enrolls each remote run with a workflow MCP. Its tools
-and the host's findings routes read and write the same external findings
-service.
-
-Use this example when repository work is too heavy or concurrent for local
-worktrees, but the host should still own intake, session identity, policy, and
-bookkeeping.
-
-[Browse the current coordinator source.](../../examples/fsd/)
-
-## Resume one remote agent across every PR wake
-
-The coordinator uses a hybrid runtime:
-
-- Ordinary playground and Slack chat run locally.
-- The `drive_pr` server tool creates a remote session for one PR.
-- The remote worker gets the repository and PR reference.
-- An `agent.bound` hook records the remote run id and enrolls the run into a
-  workflow MCP.
-- Webhooks and reminders resume the same remote agent through durable
-  PR-to-agent affinity.
-
-No other example moves one logical conversation across local chat, remote
-execution, event wakes, and timed follow-ups.
-
-## Follow a chat request
-
-1. A user asks local chat or Slack to drive a PR.
-2. The root model calls `drive_pr` with the PR, mode, and optional hint.
-3. The tool calls `ctx.send("drive", ...)` with a per-session `cloud` block
-   to attach the PR.
-4. The Agent SDK creates or resumes the `drive` session keyed by
-   `pr:owner/repo#N`.
-5. The remote runtime provisions the agent and emits `agent.bound`.
-6. The enrollment hook writes PR affinity and calls the workflow backend to
-   attach run-scoped MCP tools.
-7. `drive_pr` waits for remote binding, then returns the agent id and URL.
-   If binding exceeds its wait window, those fields can be `null` while work
-   continues.
-8. The remote agent reads the host-prepared PR brief, checks unresolved state,
-   and records findings through the workflow MCP.
-9. The host forwards a validated fallback output block when MCP wasn't
-   available for the turn.
-
-The local chat agent doesn't have the target checkout, `gh`, `git`, or the
-workflow MCP. Its job is coordination.
-
-A request for a merged or closed PR finishes before provisioning. That result
-has `status: "finished"` and no remote session.
-
-## Map the framework features
-
-| Capability | Source | Role |
-| --- | --- | --- |
-| Hybrid config | [`agent/agent.ts`](../../examples/fsd/agent/agent.ts) | Keep chat local, set remote-runtime defaults, disable automatic PR creation, and isolate local harness workspaces. |
-| Root instructions | [`agent/instructions.md`](../../examples/fsd/agent/instructions.md) | Separate local coordination from remote triage and define suggest/apply policy. |
-| Drive tool | [`agent/tools/drive_pr.ts`](../../examples/fsd/agent/tools/drive_pr.ts) | Hand a chat request to the `drive` channel and wait for remote binding. |
-| Drive channel | [`agent/channels/drive.ts`](../../examples/fsd/agent/channels/drive.ts) | Start remote work and expose findings read/write routes. |
-| GitHub channel | [`agent/channels/github.ts`](../../examples/fsd/agent/channels/github.ts) | Buffer PR, comment, review, check, and status wakes. |
-| Slack channel | [`agent/channels/slack.ts`](../../examples/fsd/agent/channels/slack.ts) | Route Slack requests to the local coordinator. |
-| Hooks | [`agent/hooks/enroll-fsd.ts`](../../examples/fsd/agent/hooks/enroll-fsd.ts), [`agent/hooks/record-outputs.ts`](../../examples/fsd/agent/hooks/record-outputs.ts) | Bind remote identity, enroll MCP, and forward fallback findings. |
-| Affinity and buffering | [`agent/lib/pr-affinity.ts`](../../examples/fsd/agent/lib/pr-affinity.ts), [`agent/lib/webhook-buffer.ts`](../../examples/fsd/agent/lib/webhook-buffer.ts) | Persist PR identity, sticky mode, and pending wakes. |
-| Reminders | [`agent/lib/merge-conflict-watch.ts`](../../examples/fsd/agent/lib/merge-conflict-watch.ts) | Recheck merge conflicts every 30 minutes. |
-| Workflow client | [`agent/lib/fsd-platform.ts`](../../examples/fsd/agent/lib/fsd-platform.ts) | Enroll external runs and read or record findings. |
-| Storage | [`agent/storage.ts`](../../examples/fsd/agent/storage.ts) | Persist sessions and events with `cursorHostedStorage`. |
-
-The coordinator has no authored skill, subagent, MCP connection, static
-schedule, A/B experiment, eval, or tool approval.
-
-The workflow MCP is dynamic. Backend enrollment attaches it to the remote run,
-so there is no file under `agent/mcp-connections/`.
-
-## Understand local and remote workspaces
-
-The root config sets `runtime: "local"` because `drive_pr` is a server tool.
-It also supplies remote-runtime defaults through the `cloud` configuration:
-
-```ts
-local: {
-  cwd: join(homedir(), ".cache", "agent-serve", "fsd"),
-},
-cloud: {
-  env: { type: "cloud" },
-  autoCreatePR: false,
-},
-```
-
-The local cwd sits outside the monorepo, so inherited repository instructions
-don't affect coordinator chat.
-
-Remote sessions get a repository attachment with the target PR. The worker starts
-from the PR base and creates an automation side branch from the PR head only when
-code context or a fix is needed. The serve host never checks out target code.
-
-## Prepare access
-
-You need:
-
-- Node 22.13 or newer.
-- An agent-runtime user credential.
-- Access to a managed remote runtime.
-- Access to the target GitHub PR.
-- Access to the workflow backend and findings store.
-
-Keep the affinity and webhook-buffer files on durable storage for a
-long-lived host.
-
-## Validate without starting remote work
-
-```bash
-agent-sdk validate --dir examples/fsd
-agent-sdk info --dir examples/fsd --json
-agent-sdk github events --dir examples/fsd --json
-```
-
-These commands inspect discovery and declared GitHub events. They don't
-provision a remote agent.
-
-## Choose suggest or apply
-
-Every PR has a sticky mode:
-
-| Mode | Required remote behavior |
-| --- | --- |
-| `suggest` | May create verified commits on the VM's local side branch. Instructions require no pushes, comments, PR edits, or workflow actions. Records exact fixes and actions as findings for the owner. |
-| `apply` | Pushes verified fixes to the existing PR head and may update metadata, reply to threads, mark a draft ready, rebase, or rerun CI. |
-
-The remote instructions forbid merging, enabling auto-merge, force-pushing,
-and opening a new PR in both modes. `autoCreatePR: false` also disables the
-SDK's automatic PR creation. The other restrictions are prompt policy, not a
-deterministic host gate. `suggest` is the default.
-
-The selected mode is stored beside PR affinity. Webhooks and reminders reuse
-it. Re-driving a PR can change the host-side mode. Backend enrollment records
-the mode at first enrollment, so each later host prompt repeats the current
-authoritative mode.
-
-> [!CAUTION]
-> `apply` writes to the user's PR branch and triggers CI. Use `suggest` for
-> development. Both modes provision a billed remote agent and can write
-> structured findings to the findings service. `drive_pr` has no approval gate,
-> and suggest/apply restrictions depend on the remote agent following its
-> instructions.
-
-## Start a suggest-mode drive
-
-Run the host:
-
-```bash
-agent-sdk dev examples/fsd
-```
-
-From chat:
-
-> Drive https://github.com/owner/repo/pull/123 in suggest mode.
-
-Or call the coordinator tool:
-
-```bash
-agent-sdk call drive_pr \
-  --dir examples/fsd \
-  --input '{"pr":"https://github.com/owner/repo/pull/123","mode":"suggest"}'
-```
-
-For an open PR, the tool waits up to 60 seconds for remote binding and returns:
-
-- the normalized PR label,
-- session and continuation ids,
-- the remote-agent id and URL when binding completes in that window,
-- `status: "started"`, and
-- the merge-conflict reminder id.
-
-It doesn't wait for findings. A slow binding can return `null` identifiers.
-Open the returned agent URL when present to follow the remote run.
-
-## Use the HTTP drive surface
-
-The custom channel starts the same orchestration:
-
-```bash
-curl -s -X POST \
-  http://127.0.0.1:3000/fsd/v1/channels/drive/ \
-  -H 'content-type: application/json' \
-  -d '{"pr":"owner/repo#123","mode":"suggest"}'
-```
-
-This route returns as soon as the channel session exists. The remote-agent id
-can still be `null` at that point. Triage continues in the background.
-
-Read findings later:
-
-```bash
-curl -s \
-  'http://127.0.0.1:3000/fsd/v1/channels/drive/findings?pr=owner/repo%23123'
-```
-
-The external findings service is the source of truth. The local host doesn't keep a second
-findings database.
-
-The channel also exposes `POST /findings` as a testing surface. It validates
-outputs, then writes them to the findings service for a PR already bound by this
-host. The route has no approval gate. Keep it under the default loopback auth
-or another trusted boundary.
-
-## Keep one remote agent per PR
-
-Within the `drive` channel, the stable continuation token
-`pr:owner/repo#N` resumes the same session. GitHub sessions are scoped to
-another channel, so a continuation token alone can't bridge them.
-
-The enrollment hook closes that gap:
-
-1. Read the PR from the continuation token or host-authored session title.
-2. Record PR to `sdkAgentId` affinity after `agent.bound`.
-3. Seed later sessions with the same remote id.
-4. Retry workflow MCP enrollment after a completed turn when the first RPC
-   failed.
-
-This lets Slack, HTTP drive, GitHub, and reminders talk to one remote
-conversation without sharing one channel session.
-
-## Buffer GitHub wakes
-
-The GitHub channel handles pull requests, comments, reviews, check suites,
-check runs, and selected status events. It doesn't send payload details to the
-model. It asks the remote agent to refresh live source of truth.
-
-The buffer:
-
-- groups events by PR,
-- waits three seconds for a burst to settle,
-- re-buffers while CI settles,
-- skips a flush when the PR session is busy,
-- tries to write its snapshot before acknowledging a wake, and
-- restores pending entries when the channel starts.
-
-Closing a PR discards its pending entry and cancels its reminders.
-
-Snapshot persistence is best-effort. Write failures are swallowed silently,
-so a delivery can still be acknowledged without a durable snapshot.
-
-This is the high-volume counterpart to a direct `{ auth }` GitHub wake. See
-[GitHub](../guides/github.md#handle-high-event-volume) for the reusable
-pattern.
-
-## Add merge-conflict checks
-
-Starting a drive arms one recurring reminder per PR. Every 30 minutes the host
-checks mergeability:
-
-- closed or merged stops the reminder,
-- clean skips delivery,
-- conflicting sends a follow-up to the owning session, and
-- a busy session skips the wake.
-
-This uses runtime reminders, not a static `agent/schedules/` file. The host
-creates, lists, replaces, and cancels reminders through `host.reminders`.
-Development mode doesn't fire reminder timers automatically. Dispatch one
-through the dev reminder endpoint for a manual proof, or use non-dev `serve`
-to run the 30-minute cadence.
-
-The reminder's `run` handler lives in memory. After a host restart, the Agent SDK
-disarms it with `handler_lost_on_restart`; a later drive or webhook path can
-arm a fresh handler. Persisted reminder metadata alone doesn't keep the check
-running.
-
-## Record findings with MCP or a fallback
-
-After enrollment, the remote agent receives workflow tools for:
-
-- recording and updating outputs,
-- listing current outputs,
-- reading PR metadata,
-- reading CI state, and
-- reading review comments.
-
-The main output is a structured workflow suggestion or code-change reference.
-The remote prompt requires findings as soon as each action becomes clear.
-
-If enrollment races or MCP is unavailable, the agent writes one fenced
-fallback JSON block. The host validates allowed kinds, actions, statuses, and
-the 140-character finding body before forwarding it to the same findings
-service. The output hook catches fallback blocks from webhook and reminder
-turns.
-
-## Verify the host logic
-
-The coordinator has no filesystem evals. Its unit tests cover mode parsing, drive
-orchestration, affinity, webhook durability, CI settlement, output parsing,
-reminders, and Slack configuration:
-
-```bash
-pnpm exec vitest run examples/fsd/agent/lib
-```
-
-Use those tests for host policy. Use a dedicated test PR and suggest mode for
-the end-to-end remote path.
-
-## Build another hybrid coordinator
-
-Use this architecture when each work item needs a real checkout:
-
-1. Keep conversational intake local.
-2. Open a remote session only after the request identifies a work item.
-3. Give the work item a stable continuation key.
-4. Persist its remote-agent id for cross-channel resume.
-5. Coalesce noisy events before spending another turn.
-6. Put the current mode and permissions in every host prompt.
-7. Record outputs incrementally in a durable sink.
-8. Add reminders for state requiring periodic rechecks.
-
-## Where to go next
-
-- [Cloud runtime](../guides/cloud-runtime.md)
-- [GitHub](../guides/github.md)
-- [Webhooks and custom channels](../guides/webhooks.md)
-- [Schedules and reminders](../reference/schedules.md)
-- [Sessions and streaming](../reference/sessions.md)
-- [Deployment](../deployment.md)

package/docs/example-agents/index.md

@@ -1,107 +0,0 @@
----
-title: "Choose the right Agent SDK example"
-description: "Compare all twelve example agents by runtime, channels, tools, state, and the framework pattern each one teaches."
----
-
-# Choose the right Agent SDK example
-
-The examples progress from one-channel assistants to durable, event-driven
-workflows. Start with the smallest agent for your use case. Each guide
-explains its request flow, framework features, verification path, and reusable
-design.
-
-The source projects live under
-[`examples/`](../../examples/). Run the commands below from
-`packages/agent-serve`. See [Run the CLI](/#run-the-cli) if the
-`agent-sdk` command isn't installed.
-
-## Compare the examples
-
-| Agent | Runtime | Intake | Framework focus | What sets it apart |
-| --- | --- | --- | --- | --- |
-| [Weather agent](./weather-agent.md) | Cloud | HTTP and two Slack transports | Tools, stdio MCP, skill, subagent, schedule, hooks, A/B, and evals | It demonstrates the broad cloud-runtime surface in one domain. |
-| [Slack agent](./slack-agent.md) | Local | Account-linked Slack | Channel identity, threads, and suggested prompts | It reaches Slack without authored tools. |
-| [Concierge](./concierge.md) | Local | Built-in HTTP | Peer MCP and multi-agent serving | It delegates to a separate agent with its own tools, sessions, and context. |
-| [Playbook router](./benny.md) | Local with repo context | Two Slack transports | Channel watching, inherited skills, custom cwd, and an eval | An allowlisted Slack channel becomes an intake queue for repo playbooks. |
-| [Alert investigator](./oncall.md) | Local | Watched Slack alerts channel | Bot-post channel watching, per-thread debounce, reminder tools, and host Slack calls | Every alert gets a thread-pinned investigation that schedules its own re-checks. |
-| [PR evidence reviewer](./bugbot.md) | Local | Custom HTTP and Slack | Host tool, skill, seeded workspaces, and an eval | The model receives a prepared diff-first evidence tree instead of a checkout. |
-| [Approval Buddy](./approval-buddy.md) | Local | GitHub and Slack | Policy tools, two subagents, durable storage, and evals | Code decides whether a PR may be approved. Reviews stay informational. |
-| [Security Reviewer](./security-reviewer.md) | Local host pipeline | GitHub and chat | Staged tools, parallel SDK agents, progress UI, durable storage, A/B, and evals | Lives in `factory/security-reviewer/`. Reviewers and triage overlap while the playground shows every stage. |
-| [Remote PR coordinator](./fsd.md) | Local coordinator and remote PR sessions | HTTP, GitHub, and Slack | Remote handoff, hooks, affinity, buffering, reminders, and workflow MCP | One remote conversation follows a PR across chat, webhooks, and timed wakes. |
-| [Knowledge base](./knowledge-base.md) | Local | Built-in HTTP chat | Durable host-side state, a conventions skill, a schedule, unit tests, and evals | People curate shared facts in chat, and fresh sessions retrieve them from markdown. |
-| [Codebase wiki](./codebase-wiki.md) | Local | GitHub and chat | Task-dispatch webhooks, seeded digests, a mapping skill, a schedule, and evals | Merged PRs accumulate into per-feature wiki pages with a daily digest. |
-| [Codeowners review](./codeowners-review.md) | Local | GitHub, chat, and fixtures | Ownership routing in code, playbook data files, parallel subagents, and evals | Each product area reviews with its own playbook, and verdicts aggregate mechanically. |
-
-## Pick a learning path
-
-Use this order when you want to learn the Agent SDK one capability at a time:
-
-1. Start with [Weather agent](./weather-agent.md) to explore the filesystem
-   conventions and cloud runtime.
-2. Strip the project back to [Slack agent](./slack-agent.md) to see the
-   minimum channel surface.
-3. Read [Playbook router](./benny.md) when Slack should route requests into repo
-   playbooks.
-4. Continue to [Alert investigator](./oncall.md) when the intake is bot
-   posts and the agent must pace its own engagement and re-checks.
-5. Add composition with [Concierge](./concierge.md).
-6. Study [PR evidence reviewer](./bugbot.md) before giving a model repository
-   evidence.
-7. Move policy into code with [Approval Buddy](./approval-buddy.md).
-8. Compare [Security Reviewer](./security-reviewer.md) and
-   [Remote PR coordinator](./fsd.md) for host-side versus remote PR work.
-9. See parallel subagent delegation carry team judgment in
-   [Codeowners review](./codeowners-review.md).
-10. Curate team context through conversation with
-    [Knowledge base](./knowledge-base.md), then let GitHub events maintain
-    product documentation in [Codebase wiki](./codebase-wiki.md).
-
-## Common prerequisites
-
-All examples require:
-
-- Node 22.13 or newer. Don't run the Agent SDK under Bun.
-- Workspace dependencies installed.
-- An agent-runtime credential for model turns.
-
-Several examples need more:
-
-- Account-linked Slack channels require a connected host account.
-- Alert investigator needs a dedicated Socket Mode app with channel-post
-  events and membership in the watched alerts channel.
-- GitHub examples require access to the target repository. Codebase wiki and
-  Codeowners review call the host `gh` CLI for PR data; the codeowners
-  fixtures run without network.
-- Example agents use `cursorHostedStorage` (`agent/storage.ts`) for Cursor-hosted session storage (control-plane proxy).
-- Remote PR coordinator starts remote agent sessions and needs access to its
-  workflow backend.
-
-Each guide lists its own credentials, services, and side effects.
-
-## Validate any example
-
-Discovery commands don't start a model turn:
-
-```bash
-agent-sdk validate --dir examples/weather-agent
-agent-sdk info --dir examples/weather-agent --json
-```
-
-Start one development server with `agent-sdk dev examples/<name>`.
-Concierge depends on Weather agent, so its guide creates an isolated
-two-project mount. Don't mount the whole examples directory to test one
-agent; several advanced examples subscribe to live GitHub events.
-
-## Read by framework feature
-
-- [Concepts](../concepts.md) explains filesystem discovery and runtime
-  boundaries.
-- [Project layout](../reference/project-layout.md) lists every authored
-  folder.
-- [Tools](../reference/tools.md), [channels](../reference/channels.md), and
-  [MCP connections](../reference/connections.md) cover the core extension
-  points.
-- [Evals](../evals.md) and [live A/B metrics](../ab.md) cover measured
-  iteration.
-- [Deployment](../deployment.md) covers credentials, auth, storage, and
-  hosting.

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
-`.agent-serve/wiki/` 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)