@vpxa/aikit 0.1.307 → 0.1.309

package/scaffold/dist/definitions/skills/adr-skill.mjs

@@ -421,7 +421,7 @@ Count checked items.
 | Verification says "it works" | Not testable | Ask: "what command proves it works?" |
 `},{file:`references/template-variants.md`,content:`# Template Variants
 
-This skill ships two templates in \`assets/templates/\`.
+This skill ships decision templates and a README in \`assets/templates/\`.
 
 ## Simple
 
@@ -470,6 +470,12 @@ Aligns with [MADR 4.0](https://adr.github.io/madr/) plus agent-first sections.
 | Needs stakeholder review | No              | Yes          |
 
 When in doubt, start with Simple. Expand to MADR if needed.
+
+## Readme
+
+File: \`assets/templates/adr-readme.md\`
+
+A directory README that documents conventions, naming, status values, and lists ADRs. Use when introducing ADRs to a repo that has none — place alongside the ADR index.
 `},{file:`scripts/bootstrap_adr.js`,content:`#!/usr/bin/env node
 const fs=require('node:fs');
 const path=require('node:path');
@@ -868,211 +874,49 @@ metadata:
 
 # ADR Skill
 
-## Quick Reference
-
-**Purpose:** Create ADRs agents can implement from without follow-up.
-
-**Write an ADR when:** decision changes system shape, is hard to reverse, affects other people/agents, or has real alternatives.
-
-**Four-Phase Workflow:**
-1. **Discover** — surface intent, constraints, alternatives
-2. **Draft** — fill Simple or MADR template with concrete constraints
-3. **Validate** — review for agent-readiness (target ≥ 80%)
-4. **Record** — save to \`docs/decisions/\` or \`adr/\`, update index
-
-**Two templates:**
-- **Simple** (≤3 options, single-team) — Context → Decision → Consequences → Implementation Plan → Alternatives
-- **MADR** (complex, multi-team) — adds drivers, options matrix, deeper plan
-
-**Commands:** Consult existing ADRs before impl. Create/update with scripts below.
-
-**Agent-readiness gate:** target ≥ 80%.
-
-## Mindset
-
-Write for future readers with zero context. ADR = decision record, not meeting notes.
-
-## Philosophy
-
-ADR must let an agent implement without follow-up: explicit constraints, concrete decision, follow-up tasks, non-goals, self-contained context, and an implementation plan.
-
-## ADR Quality Criteria
-
-An ADR is agent-ready when it passes:
-- [ ] **Context is self-contained**
-- [ ] **Options include at least 2 genuine alternatives**
-- [ ] **Decision rationale cites concrete evidence**
-- [ ] **Consequences are bidirectional**
-- [ ] **Status is explicit**
-- [ ] **Superseded ADRs link to their replacement**
-
-## When to Write an ADR
-
-Write an ADR when a decision:
-
-- **Changes how system is built or operated** (new dep, pattern, infra choice, API design)
-- **Is hard to reverse** once code is written against it
-- **Affects other people or agents** who will work in codebase later
-- **Has real alternatives** that were considered and rejected
-
-## NEVER
-
-- **NEVER write ADR after impl** unless documenting discovery
-- **NEVER include only one option**
-- **NEVER use vague consequences**
-- **NEVER let ADRs linger in stale proposed state**
-- **NEVER modify an accepted ADR**; supersede instead
-- **NEVER write ADR for trivial decisions**
-- **NEVER skip rejected alternatives**
-
-
-
-### Proactive ADR Triggers (For Agents)
-
-Stop and propose an ADR when you hit a new dependency, a new shared pattern, a non-obvious tradeoff, a conflict with an accepted ADR, or a long code comment explaining "why".
-
-**How to propose**: state decision, why it matters, ask whether to capture as ADR. If yes, run workflow. If no, note reasoning in code comment and move on.
-
-## Creating an ADR: Four-Phase Workflow
-
-Every ADR goes through four phases. Do not skip them.
-
-### Phase 0: Scan the Codebase
-
-Before questions, gather enough repo context to avoid contradictory ADRs:
-
-1. **Find existing ADRs.** Check \`contributing/decisions/\`, \`docs/decisions/\`, \`adr/\`, \`docs/adr/\`, \`decisions/\`. Note dir, naming, status style, related ADRs, possible supersession.
-2. **Check tech stack.** Read \`package.json\`, \`go.mod\`, \`requirements.txt\`, \`Cargo.toml\`, or equivalent for relevant deps and versions.
-3. **Find related code patterns.** Identify files, dirs, and impl patterns affected.
-4. **Look for ADR references in code.** Comments and docs often reveal governing decisions.
-
-### Phase 1: Capture Intent (Socratic)
-
-Ask questions **one at a time**.
+Use for consequential technical decisions: architecture, tech choice, hard-to-reverse tradeoff, public contract, >3 files, >1 team/agent, or user asks for ADR/decision record.
 
-**Core questions** (skip what Phase 0 or context already answered): title, why now, constraints, success criteria, real options, current lean, who decides, and what an agent needs to implement.
+## Workflow
 
-**Adaptive follow-ups**: probe fuzzy areas. Useful prompts: "What's worst case if this is wrong?", "What would make you revisit this in 6 months?", "I found [existing ADR/pattern] — does this interact with it?"
+1. Discover: decision, forces, constraints, alternatives, reversibility.
+2. Choose template: simple for small decisions, MADR for bigger context/tradeoffs.
+3. Draft ADR with status, context, decision, consequences, options considered.
+4. Validate agent-readiness: can an implementation agent act without follow-up?
+5. Update index/status links; mark supersedes/superseded-by when relevant.
 
-**When to stop**: stop only when every ADR section, especially Implementation Plan and Verification, can be filled without guessing.
+## Questions
 
-**Intent Summary Gate**: Before Phase 2, summarize title, trigger, constraints, options, lean, non-goals, related ADRs/code, affected files, and verification plan. Ask: **Does this capture your intent? Anything to add or correct?**
+Ask only missing critical facts:
+- What decision is being made?
+- Why now?
+- What alternatives are plausible?
+- What constraints are fixed?
+- What breaks if wrong?
+- Who/what must implement or maintain it?
 
-Do NOT proceed to Phase 2 until human confirms summary.
+## Readiness Bar
 
-### Phase 2: Draft the ADR
+ADR is ready when it has:
+- Decision stated in one sentence.
+- Scope and non-goals.
+- At least 2 alternatives or reason no real alternative exists.
+- Consequences: benefits, costs, risks, migration work.
+- Acceptance/rollback signals for future agents.
+- Links to code/docs/issues when available.
 
-1. **Choose the ADR directory.**
-   - If one exists, use it.
-   - If none exists, create \`contributing/decisions/\` (if \`contributing/\` exists), \`docs/decisions/\`, or \`adr/\`.
-2. **Choose a filename strategy.**
-   - If existing ADRs use date prefixes (\`YYYY-MM-DD-...\`), continue that.
-   - Otherwise use slug-only filenames (\`choose-database.md\`).
-3. **Choose a template.**
-   - Use \`assets/templates/adr-simple.md\` for straightforward decisions.
-   - Use \`assets/templates/adr-madr.md\` for multiple options with structured tradeoffs.
-   - See \`references/template-variants.md\` if unsure.
-4. **Fill every section from confirmed intent summary.** Remove placeholders.
-5. **Write the Implementation Plan.** It tells next agent exactly what to do.
-6. **Write Verification criteria as checkboxes.** They must be specific enough for manual or programmatic checking.
-7. **Generate the file.** Preferred: run \`scripts/new_adr.js\`. Otherwise copy a template and fill it manually.
+## Files
 
-### Phase 3: Review Against Checklist
+Use bundled scripts/templates when available:
+- scripts/bootstrap_adr.js — bootstrap ADR directory
+- scripts/new_adr.js — create new ADR from template
+- scripts/set_adr_status.js — update ADR status
+- assets/templates/adr-simple.md — lightweight decision template
+- assets/templates/adr-madr.md — options-heavy MADR template
+- assets/templates/adr-readme.md — ADR directory README
 
-Review against inline quality criteria, then use \`references/review-checklist.md\` for full pass.
+Load references on demand: references/adr-conventions.md, references/examples.md, references/review-checklist.md, references/template-variants.md.
 
-**Present the review as summary**, not raw checklist dump. Format:
-
-> **ADR Review**
->
-> ✅ **Passes**: {list what's solid — e.g., "context is self-contained, implementation plan covers affected files, verification criteria are checkable"}
->
-> ⚠️ **Gaps found**:
->
-> - {specific gap 1 — e.g., "Implementation Plan doesn't mention test files — which test suite should cover this?"}
-> - {specific gap 2}
->
-> **Recommendation**: {Ship it / Fix the gaps first / Needs more Phase 1 work}
-
-Surface failures and notable strengths only. If gaps exist, propose fixes. Do not finalize until ADR passes or human accepts gaps.
-
-## Consulting ADRs (Read Workflow)
-
-Read existing ADRs **before implementing changes** in repos that have them.
-
-1. **Before architecture work.**
-2. **Find ADR dir and index.** Start with accepted ADRs.
-3. **Read full ADR, not just title.**
-4. **Follow the Implementation Plan.**
-5. **Escalate conflicts or contradictions.**
-6. **Reference governing ADR in your work.**
-
-## Code ↔ ADR Linking
-
-- **ADR → Code**: Implementation Plan names affected paths, patterns, config changes, verification commands.
-- **Code → ADR**: add one lightweight comment at entry point linking back to governing ADR.
-
-## Other Operations
-
-### Update an Existing ADR
-
-1. Identify intent: accept/reject, deprecate, supersede, or add learnings.
-2. Use \`scripts/set_adr_status.js\` for status changes.
-
-### Post-Acceptance Lifecycle
-
-After an ADR is accepted:
-
-1. **Create implementation tasks.**
-2. **Reference ADR in PRs.**
-3. **Add code references.**
-4. **Check verification criteria.** Update ADR with results in \`## More Information\`.
-5. **Revisit when triggers fire.**
-
-### Index
-
-If repo has ADR index/log file, keep it updated.
-
-- Let \`scripts/new_adr.js --update-index\` handle it when possible.
-- Otherwise add new ADR entry and keep ordering consistent.
-
-### Bootstrap
-
-When introducing ADRs to repo that has none:
-
-\`\`\`bash
-node scripts/bootstrap_adr.js
-\`\`\`
-
-Creates dir, index, and first ADR.
-
-## Resources
-
-### scripts/
-
-- \`scripts/new_adr.js\`
-- \`scripts/set_adr_status.js\`
-- \`scripts/bootstrap_adr.js\`
-
-### references/
-
-- \`references/review-checklist.md\`
-- \`references/adr-conventions.md\`
-- \`references/template-variants.md\`
-- \`references/examples.md\`
-
-### assets/
-
-- \`assets/templates/adr-simple.md\`
-- \`assets/templates/adr-madr.md\`
-- \`assets/templates/adr-readme.md\`
-
-### Script Usage
-
-\`\`\`bash
-node scripts/new_adr.js --title "Choose database" --status proposed
-node scripts/bootstrap_adr.js --dir docs/decisions
-\`\`\`
+## Output
 
-Use \`--dir\`, \`--strategy\`, and \`--json\` as needed.
+Return created/updated ADR path, status, key decision, open questions, and implementation implications. Do not invent missing team intent; mark ASK USER.
 `}];export{e as default};

package/scaffold/dist/definitions/skills/aikit.mjs

@@ -10,233 +10,80 @@ metadata:
   relatedSkills: [session-handoff, present]
 ---
 
-# @vpxa/aikit — AI Kit
+# @vpxa/aikit - AI Kit
 
-> This skill provides DEEP GUIDANCE beyond base instructions. For tool routing rules, see your base instructions.
+Use AI Kit as compression, memory, validation, and coordination layer. Each call should reduce uncertainty or token load.
 
-Local-first AI developer toolkit with 60+ tools for search, analysis, compression, validation, memory, flows, and coordination.
+## Session Loop
 
-## When to Use
+Start:
+1. status({ includePrelude: true }); onboard if missing.
+2. search({ query: "SESSION CHECKPOINT", origin: "curated" }).
+3. flow({ action: 'status' }) when active flow may exist.
+4. scope_map({ task }) for non-trivial work.
 
-- You need to understand unfamiliar code without raw-reading large files.
-- You need structured search across code, docs, and prior decisions.
-- You need typecheck, test, or audit results in structured form.
-- You need memory across sessions, not just within one conversation.
-- You need to estimate blast radius before changing shared code.
-- You need guided flows, FORGE gates, or coordination primitives.
+During:
+- Prefer search/file_summary/compact/digest/symbol/trace/graph over raw reads.
+- Use stash for temporary findings; knowledge for durable decisions.
+- Run blast_radius before shared/public edits.
+- Validate with check + relevant test_run.
 
-## Mindset
+End:
+- reindex after structural changes.
+- produce_knowledge for durable project updates.
+- session_digest({ persist: true }).
+- knowledge remember session checkpoint with done/decisions/next/blockers.
 
-AI Kit tools are a compression layer. Their job is to prevent agents from wasting tokens on raw file reads and flat text search.
+## Retrieval Ladder
 
-Every call should reduce context, not add to it.
+| Need | Tool |
+|---|---|
+| Prior decisions/conventions | search / knowledge |
+| File structure | file_summary |
+| Exact relevant section | compact |
+| Many files | digest |
+| Symbol defs/refs | symbol |
+| Call/data flow | trace |
+| Module/import relationships | graph |
+| Impact | blast_radius |
+| Type/lint/test | check / test_run |
+| Tool choice unknown | list_tools -> search_tools -> describe_tool |
 
-Think: what's the minimum I need to read to act? Then choose the tool that gives exactly that.
+Raw read_file only for exact edit lines after compressed tools identify target.
 
-Common mistake: using \`read_file\` out of habit. That is the last resort, not the first.
+## Context Reuse
 
-Default progression: \`file_summary\` → \`compact\` → \`digest\` → \`read_file\` only for exact edit lines.
+Before rereading path/topic, search exact path/topic first. If response gives ctxc_..., reuse with compact({ ref }) or compact({ ref, query }). Use enrich: true on tools that support it after first pass.
 
-If you are unsure which tool fits, ask AI Kit for the live catalog with \`list_tools\`, then narrow with \`search_tools\` or \`describe_tool\`.
+## Patterns
 
-## Operating Model
-
-1. Orient with compressed retrieval, not raw reads.
-2. Validate with structured tools, not noisy terminal output.
-3. Persist decisions that future sessions must reuse.
-4. Reuse previous context before searching again.
-5. Use reference docs only when the main routing logic is not enough.
-
-**When tools return empty:**
-- \`search\` → 0 results? Broaden query terms OR fall back to \`find({ pattern })\` with regex
-- \`symbol\` → not found? Check spelling, try \`search\` with partial name
-- \`compact\` → irrelevant content? Refine \`query\` parameter or try different \`segmentation\`
-
-## Session Protocol
-
-### Why This Matters
-
-Without session discipline, agents repeat work, miss context, and make decisions that contradict earlier choices. These steps exist to keep work cumulative.
-
-### Start (do first, every session)
-
-1. \`status({})\` — Why: confirms index is built, tools are ready, and onboard state is known. Skipping this causes tool-avoidance and blind exploration.
-2. \`search({ query: "SESSION CHECKPOINT", origin: "curated" })\` — Why: pulls prior session context so you do not re-solve finished work.
-3. \`scope_map({ task })\` — Why: creates a reading plan before exploration, which prevents broad wandering.
-4. If a flow may already exist, run \`flow({ action: 'status' })\` — Why: flow state is part of task state. Resuming the wrong way duplicates work.
-5. If onboard is missing, run \`onboard({ path: "." })\` — Why: AI Kit is strongest after structure, patterns, and symbols are pre-analyzed.
-
-### During (do continuously)
-
-- \`stash({ action: "set", key, value })\` for intermediate results — Why: chat context compresses; stash survives it.
-- \`knowledge({ action: "remember" })\` for decisions and conventions — Why: decisions must outlive the current conversation.
-- \`checkpoint({ action: "save" })\` before risky multi-step changes — Why: it gives you a known milestone for recovery.
-- \`blast_radius\` before shared-symbol edits — Why: public changes are rarely local.
-- \`check\` and \`test_run\` after changes — Why: verification is cheaper than debugging assumptions later.
-
-### End (do always)
-
-- \`session_digest({ persist: true })\` — Why: captures tool trajectory and supports crash recovery.
-- \`knowledge({ action: "remember", title: "Session checkpoint: <topic>" })\` — Why: the next session's first search is looking for exactly this.
-- \`reindex\` after structural code changes — Why: stale index data makes every later search worse.
-- \`knowledge({ action: "flagged" })\` periodically (not every session, but every few) — Why: decayed entries accumulate; reviewing them prevents stale advice from persisting.
-
-## Anti-Patterns (NEVER)
-
-- NEVER \`search\` then immediately \`read_file\` the result — search already returns content snippets
-- NEVER call \`compact\` on a file you just \`file_summary\`'d — pick one retrieval depth
-- NEVER stash >10 items without \`checkpoint\` — stash has no TTL, checkpoints do
-- NEVER run \`reindex\` mid-implementation — wait until all edits are done
-- NEVER skip \`search\` before implementing — past decisions may exist that constrain your approach
-- NEVER echo full subagent output to user — compress with \`stash\` + brief summary
-
-## Search Strategy
-
-1. Start with \`search\` in hybrid mode unless you know you need exact identifiers.
-2. Switch to \`symbol\` when the question is about one named thing.
-3. Switch to \`trace\` when the question is flow, not location.
-4. Switch to \`graph\` when the question is relationships between modules or importers.
-5. Use \`compact\`, not raw file reads, once you know the file and the question.
-
-## Judgment Patterns
-
-### Understanding a New Area
-
-~~~text
-search → scope_map → file_summary/compact → graph or trace → stash
-~~~
-
-Use this when you need a fast mental model. Do not start with \`read_file\`.
-
-### Investigating a Bug
-
-~~~text
-search → symbol → trace → compact → check/test_run → knowledge remember
-~~~
-
-Use this when the failure path matters more than file ownership.
-
-### Refactoring Shared Code
-
-~~~text
-blast_radius → checkpoint → compact/file_summary → rename or codemod → check → test_run
-~~~
-
-Use this when contract breakage is more dangerous than local implementation detail.
-
-### Picking the Right Tool
-
-~~~text
-list_tools → search_tools → describe_tool → execute
-~~~
-
-Use this instead of baking a static catalog into the skill. Tool metadata is live at runtime.
+- New area: search -> scope_map -> file_summary/compact -> graph/trace -> stash.
+- Bug: search -> symbol -> trace -> compact -> test/check -> remember.
+- Refactor shared code: blast_radius -> checkpoint -> compact -> rename/codemod -> check -> test_run.
+- Web/API: web_search/web_fetch/http; browser only when JS/auth interaction needed.
 
 ## Memory Discipline
 
-- Use \`stash\` for temporary state you may need again in the same task.
-- Use \`checkpoint\` for recoverable milestones in longer sessions.
-- Use \`knowledge\` for decisions, conventions, non-obvious findings, and reusable lessons.
-- Search curated memory before inventing a new pattern.
-- Keep memory high-signal. Store what must survive, not everything you observed.
-
-## Memory Lifecycle
-
-AI Kit auto-captures knowledge from tool outputs. Know what it captures so you can leverage it.
-
-### Auto-Knowledge Capture
-
-Every tool call passes through extractors that capture reusable facts:
-
-| Extractor | Tools Covered | What It Captures |
-|-----------|--------------|-----------------|
-| **Content reads** | \`compact\`, \`file_summary\`, \`digest\`, \`lookup\`, \`stratum_card\` | File structure, exports, compressed sections |
-| **Symbol analysis** | \`symbol\`, \`trace\`, \`graph\` (read-only) | Definitions, references, call chains, module relationships |
-| **Research results** | \`web_search\`, \`web_fetch\`, \`search\`, \`find\` | Search findings, web content, code discoveries |
-| **Behavioral patterns** | ALL tools (ring buffer) | Tool preferences, search→edit sequences, error-fix cycles |
-
-**Refresh model:** High-use extractors should converge on stable facts keyed by path, task, query, or analysis scope. Revisiting the same thing should refresh or no-op instead of multiplying near-duplicate memory.
-
-**Retrieval:** Use \`enrich: true\` on any tool that supports it — the server automatically surfaces previously captured facts relevant to your query. Search/find/knowledge responses can also emit reusable \`ctxc_...\` refs; pass them as \`ref\` to \`compact({ ref })\` or \`compact({ ref, query? })\` instead of reopening the source. \`ctxc_...\` is a reversible ref, not an id or path.
-
-**Best practice:** Before re-reading a file you've already explored, try \`search({ query: "exact-file-path-or-topic" })\` first. If you already have a \`ctxc_...\` ref, reuse it with \`compact({ ref })\` or \`compact({ ref, query? })\`. Reach for fresh \`file_summary\` / \`scope_map\` calls only when the topic materially changed or retrieval came back thin.
-
-### Retention & Tier Promotion
-- Memories start at **working** tier → promote on repeated access: episodic (2) → semantic (5) → procedural (10)
-- Unused entries decay via Ebbinghaus curve. Re-accessing important memories strengthens them.
-- Check decayed entries: \`knowledge({ action: "flagged" })\` — review, refresh important ones, forget stale ones.
-
-### Lessons
-
-Capture reusable engineering insights via \`knowledge({ action: "lesson", subAction: "create" })\`. Confirm with \`confirm\`, contradict with \`contradict\`, list with \`list-lessons\`. Confidence 60-70 for single-observation, 80+ when multiple diffs confirm. Auto-archived below 20 confidence after contradictions.
-
-See the \`lesson-learned\` skill for the full extraction workflow.
-
-### Lesson Lifecycle Management
-
-| SubAction | Purpose | Default |
-|-----------|---------|---------|
-| \`prune\` | Archive stale lessons (confidence < 15, idle > 30d) | dryRun: true |
-| \`group\` | Cluster similar lessons, add group tags | dryRun: true |
-| \`promote\` | Cross-workspace promotion to global store | dryRun: true |
-| \`demote\` | Remove from global store | -- |
-| \`auto-observe\` | Pattern detection from tool outputs | automatic |
-
-**Maintenance workflow** (periodic):
-\`\`\`
-knowledge({ action: "lesson", subAction: "prune" })   // review stale
-knowledge({ action: "lesson", subAction: "group" })   // organize
-knowledge({ action: "lesson", subAction: "promote" }) // share universal
-\`\`\`
-
-### Session Prelude
-Request context-primed session start:
-\`\`\`
-status({ includePrelude: true })
-\`\`\`
-Returns: top 3 lessons (by decayed confidence), top 2 conventions (by recency), last session checkpoint.
-Use at session start for immediate situational awareness.
-
-### Confidence Decay
-Lesson confidence decays over time via Ebbinghaus curve:
-- Accessing lessons (via withdraw, list-lessons) implicitly reinforces them
-- Unaccessed lessons gradually lose confidence
-- Below threshold 15 + idle > 30 days -> eligible for pruning
-- \`knowledge({ action: "flagged" })\` surfaces decayed entries for review
-
-### Supersession (automatic dedup)
-When you \`remember()\`, similar entries are detected automatically:
-- Jaccard > 0.7 → flagged for review
-- Jaccard > 0.95 → auto-superseded (replaced)
-- Use \`force: true\` to explicitly supersede flagged entries
-
-## Flows
-
-Flows are the preferred path for guided multi-step work.
-
-- Use \`flow({ action: 'status' })\` first to detect active work.
-- Use \`flow({ action: 'list' })\` when the task looks repeatable or cross-cutting.
-- Use \`flow({ action: 'read' })\` before acting inside a started flow.
-- Use native agent workflow only when no flow matches the problem.
-
-## Reference Docs
+Store only high-signal facts:
+- Decisions and rationale.
+- Conventions that constrain future work.
+- Non-obvious root causes and fixes.
+- Checkpoints and blockers.
 
-Load these only when the main skill is not enough:
+Review decayed/stale entries periodically with knowledge({ action: 'flagged' }). Use lesson actions for reusable engineering lessons; load lesson-learned after implementation/review work.
 
-- \`references/coordination.md\` — queue, lanes, stash, checkpoints, signaling
-- \`references/forge-protocol.md\` — tiering, evidence, gates
-- \`references/search-patterns.md\` — search, trace, graph, compression patterns
+## Flow + FORGE
 
-## Complementary Skills
+Flows guide multi-step work. Read active step before acting. FORGE handles tiering/evidence/gates; load references only when main skill is too thin.
 
-- Load \`typescript\` before TypeScript-heavy implementation work.
-- Load \`react\` before React component or hooks work.
-- Load \`session-handoff\` when context is filling up or a pause is imminent.
-- Load \`repo-access\` when repo auth fails.
+Reference docs:
+- references/coordination.md - queue, lanes, stash, checkpoints, signaling.
+- references/forge-protocol.md - tiering, evidence, gates.
+- references/search-patterns.md - search, trace, graph, compression recipes.
 
 ## Self-Dogfooding
 
-When developing AI Kit itself, rebuild generated output before trusting runtime behavior, and reindex after structural changes so the toolkit can see its own new shape.
+When developing AI Kit itself: regenerate scaffold output, run focused checks, rebuild, then reindex so future searches see new shape.
 `},{file:`references/coordination.md`,content:`# Coordination
 
 Use coordination tools when work is parallel, long-running, or easy to repeat incorrectly.