@cursor/july 0.1.4 → 0.1.6

package/docs/example-agents/fsd.md

@@ -0,0 +1,330 @@
+---
+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.
+
+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. Agentkit 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. |
+
+The coordinator has no authored skill, subagent, MCP connection, static
+schedule, A/B experiment, eval, custom storage definition, 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
+agentkit validate --dir examples/fsd
+agentkit info --dir examples/fsd --json
+agentkit 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
+agentkit dev examples/fsd
+```
+
+From chat:
+
+> Drive https://github.com/owner/repo/pull/123 in suggest mode.
+
+Or call the coordinator tool:
+
+```bash
+agentkit 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, agentkit
+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

@@ -0,0 +1,102 @@
+---
+title: "Choose the right agentkit example"
+description: "Compare all eleven example agents by runtime, channels, tools, state, and the framework pattern each one teaches."
+---
+
+# Choose the right agentkit 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](../README.md#run-the-cli) if the
+`agentkit` command isn't installed.
+
+## Compare the examples
+
+| Agent | Runtime | Intake | Framework focus | What sets it apart |
+| --- | --- | --- | --- | --- |
+| [Weather agent](./weather-agent.md) | Local | HTTP and two Slack transports | Tools, stdio MCP, approvals, skill, subagent, schedule, hook, A/B, and evals | It demonstrates the broad local-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. |
+| [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 | 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 agentkit one capability at a time:
+
+1. Start with [Weather agent](./weather-agent.md) to explore the filesystem
+   conventions and local 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. Add composition with [Concierge](./concierge.md).
+5. Study [PR evidence reviewer](./bugbot.md) before giving a model repository
+   evidence.
+6. Move policy into code with [Approval Buddy](./approval-buddy.md).
+7. Compare [Security Reviewer](./security-reviewer.md) and
+   [Remote PR coordinator](./fsd.md) for host-side versus remote PR work.
+8. See parallel subagent delegation carry team judgment in
+   [Codeowners review](./codeowners-review.md).
+9. 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 agentkit 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.
+- 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.
+- Approval Buddy and Security Reviewer define custom durable session storage.
+- 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
+agentkit validate --dir examples/weather-agent
+agentkit info --dir examples/weather-agent --json
+```
+
+Start one development server with `agentkit 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

@@ -0,0 +1,171 @@
+---
+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 cloud 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. |
+| [`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, A/B
+experiment, or custom storage. The wiki directory is the durable state.
+
+## 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
+agentkit validate --dir examples/knowledge-base
+agentkit 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
+agentkit call wiki_write \
+  --dir examples/knowledge-base \
+  --input '{"page":"staging-database","content":"# Staging database\n\n- Port: 6432 (recorded 2026-07-19)\n"}'
+
+agentkit call wiki_search \
+  --dir examples/knowledge-base \
+  --input '{"query":"6432"}'
+
+agentkit 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
+agentkit 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 `agentkit 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
+agentkit eval --dir examples/knowledge-base --list
+agentkit 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)