Agent Cookbook

Scenario-keyed reference for AI coding agents that need to do something specific against this wiki and its code. Each entry below is a type: runbook page: structured frontmatter (when_to_use, steps, pitfalls, related_tools, references) plus a short freeform body. Read the page when the named scenario applies; cite it by canonical_id when you act on it.

How to use this cookbook

1. Pick the runbook whose when_to_use matches your situation.
2. Read its runbook: block over /api/pages/for-agent/{canonical_id} or get_page_for_agent on /knowledge-mcp — the steps are the contract.
3. The body prose elaborates and links to references.

The cookbook is small on purpose. New runbooks are added when observed agent thrashing in MCP transcripts can be summarised in two-to-five imperative steps. Topic-keyed how-tos go in narrative articles instead.

Members

Retrieval and citation

• ChoosingARetrievalMode — BM25 vs. hybrid vs. graph traversal.
• FindingTheRightMcpTool — decision tree across the live MCP surface.
• CitingAWikiPage — use canonical_id, never slug.
• InterpretingHybridRetrievalMetrics — what the Prometheus gauges mean.
• HandlingEmbeddingServiceOutages — fail-closed BM25 fallback.
• WhatToDoWhenANonExistentFunctionIsCited — verify before recommending.

Authoring and contribution

• VerifyingAnAgentGeneratedPage — mark_page_verified + triage.
• ProposingKnowledgeGraphEdges — propose_knowledge workflow.
• RunningTheRetrievalQualityHarness — manual invocation.

Code and tooling

• WritingANewMcpTool — scaffolding, registration, description convention.
• ExploringAModulesApiSurface — grep + MCP patterns for unfamiliar modules.
• AnsweringRestApiQuestions — find the endpoint, method, and permission model.
• PlanningAMigrationChange — what tables, files, and tests to touch.
• DebuggingFailingIntegrationTests — port conflicts, Cargo, pgvector.
• BuildingAndDeployingLocally — one-screen canonical flow.

Authoring a new runbook

1. Pick a scenario that has bitten you (or an agent you're observing) at least twice.
2. Phrase it as a when_to_use entry — the trigger should be unambiguous.
3. Write 2–5 imperative steps.
4. List the pitfalls you'd warn a colleague about. (none known) is permitted but discouraged.
5. Save through the wiki — RunbookValidationPageFilter will reject schema violations with a FilterException naming the issue kind.

Editorial / ongoing

This section captures the maintenance cadence for the cookbook and the verification system that backs it. Neither item needs an engineering pass — both grow over time as the project evolves.

Cookbook expansion

The 15 seed runbooks listed under Members cover the scenarios that were obvious at launch (2026-04-25). New runbooks land when one of three triggers fires:

• Observed agent thrashing. An MCP transcript shows an agent retrying the same operation 3+ times with different phrasings, or reaching for the wrong tool repeatedly. If the right behaviour can be summarised in 2–5 imperative steps, it's a runbook candidate.
• A new subsystem ships that an agent will need to use. Write the runbook with the subsystem's first release, not after the third bug report.
• Recurring human questions. If the same human asks the same question of the wiki twice, that's data — write the runbook.

What does NOT belong as a runbook:

• Topic explainers ("how does X work?") — those go in narrative articles.
• One-off recipes that won't generalise.
• Speculative procedures with no observed need.

The validator (FrontmatterRunbookValidator) enforces structural rules at save time: ≥1 when_to_use, ≥2 steps, ≥1 pitfalls, related_tools matching /api|knowledge-mcp|wikantik-admin-mcp|tools/* or bare snake_case names, references resolving to canonical_ids or page titles. A save that violates any of these returns FilterException naming the issue kind.

Trusted-authors registry growth

Verification confidence is computed by ConfidenceComputer from verified_at + the verifier's membership in the trusted_authors table:

• A mark_page_verified call from a trusted author within the last 90 days → confidence: authoritative.
• A mark_page_verified call from a non-trusted author → stays provisional (the timestamp lands; the confidence does not promote).
• No verification, or verification older than 90 days → confidence: stale.

The wiki currently runs single-developer, so trusted_authors has one row (jakefear). Adding contributors is a one-line INSERT per person:

INSERT INTO trusted_authors (login_name, notes)
VALUES ('alice', 'primary maintainer, security')
ON CONFLICT (login_name) DO NOTHING;

The cache (TrustedAuthorsDao) refreshes on the next save event, so the new author's verifications start producing authoritative results immediately.

When to add a new trusted author:

• They've shipped at least one substantive review of an existing page (a non-trivial edit, not a typo fix).
• They understand the verification semantics (see VerifyingAnAgentGeneratedPage).
• They're willing to be cited as the verifier of pages they mark.

When to remove a trusted author:

• They're no longer active.
• They've left the project.
• A pattern of mass-marking emerges — verification only retains signal if every authoritative mark is backed by a real read.