@vpxa/kb 0.1.27 → 0.1.28

package/scaffold/README.md

@@ -0,0 +1,192 @@
+# Scaffold System — Contributor Guide
+
+> **⚠️ GOLDEN RULE: Never edit files in `scaffold/general/` or `scaffold/claude-code/` directly.**
+> They are **generated output** and will be overwritten by `generate.mjs`.
+> Always edit the **source files** in `scaffold/definitions/`.
+
+## Architecture
+
+```
+scaffold/
+├── definitions/          ← SOURCE OF TRUTH (edit here)
+│   ├── agents.mjs        Agent metadata (name, description, model, tools, category)
+│   ├── bodies.mjs        Agent body text (mode instructions per agent)
+│   ├── models.mjs        Available models per IDE
+│   ├── protocols.mjs     Shared protocol files (_shared/*.md) + templates
+│   ├── tools.mjs         Tool capability → IDE tool mappings
+│   ├── prompts.mjs       Prompt file content
+│   ├── hooks.mjs         Hook definitions
+│   └── plugins.mjs       Plugin definitions
+│
+├── adapters/             ← IDE-specific generators
+│   ├── copilot.mjs       GitHub Copilot adapter (active — generates ~32 files)
+│   └── claude-code.mjs   Claude Code adapter (stub — no output yet)
+│
+├── generate.mjs          ← BUILD SCRIPT (run after any change)
+│
+├── general/              ← GENERATED OUTPUT for Copilot (DO NOT EDIT)
+│   ├── agents/
+│   │   ├── _shared/      Protocol files (from PROTOCOLS in protocols.mjs)
+│   │   ├── templates/    Template files (from TEMPLATES in protocols.mjs)
+│   │   └── *.agent.md    Agent files (from AGENT_BODIES in bodies.mjs)
+│   └── prompts/          Prompt files (from PROMPTS in prompts.mjs)
+│
+└── claude-code/          ← GENERATED OUTPUT for Claude Code (stub, DO NOT EDIT)
+```
+
+### Data Flow
+
+```
+definitions/*.mjs  →  generate.mjs  →  scaffold/general/  →  kb init  →  .github/ (user project)
+    (source)          (build script)    (generated output)    (deploy)     (user workspace)
+```
+
+## How to Make Changes
+
+### Step 1: Edit Source Files
+
+| What you want to change | Edit this file |
+|--------------------------|---------------|
+| An agent's body/instructions | `definitions/bodies.mjs` → `AGENT_BODIES[agentName]` |
+| Shared rules for code agents | `definitions/protocols.mjs` → `PROTOCOLS['code-agent-base']` |
+| Shared rules for researchers | `definitions/protocols.mjs` → `PROTOCOLS['researcher-base']` |
+| Agent metadata (model, tools) | `definitions/agents.mjs` → `AGENTS[agentName]` |
+| Available models | `definitions/models.mjs` |
+| Tool mappings | `definitions/tools.mjs` |
+| Prompt files | `definitions/prompts.mjs` |
+
+### Step 2: Regenerate Output
+
+```bash
+node scaffold/generate.mjs
+```
+
+This will:
+1. Clean `general/agents/` and `general/prompts/` directories
+2. Regenerate all files from definitions via the copilot adapter
+3. Print every file written (expect ~32 files)
+
+To generate for a specific IDE only:
+```bash
+node scaffold/generate.mjs --ide copilot
+node scaffold/generate.mjs --ide claude-code
+```
+
+### Step 3: Verify
+
+```bash
+# Syntax check the source file you edited
+node -c scaffold/definitions/bodies.mjs
+node -c scaffold/definitions/protocols.mjs
+
+# Verify your changes appear in generated output
+# (use grep/Select-String for key phrases)
+grep -r "your key phrase" scaffold/general/agents/
+```
+
+### Step 4: Commit Both Source AND Generated
+
+Always commit the definition source files AND the regenerated output together.
+The generated files are checked into git so `kb init` can deploy them without
+running the generator.
+
+## Source File Details
+
+### bodies.mjs
+
+Contains `AGENT_BODIES` — an object mapping agent names to their body text.
+
+- Most values are **template literal strings** (`` `...` ``)
+- The **Orchestrator** body is a **function** `(agentTable) => string` because it
+  dynamically includes the agent roster table
+- Backticks inside content must be escaped: `` \` ``
+
+```js
+export const AGENT_BODIES = {
+  Orchestrator: (agentTable) => `# Orchestrator\n${agentTable}\n...`,
+  Implementer: `# Implementer\n...`,
+  Debugger:    `# Debugger\n...`,
+  // ...
+};
+```
+
+### protocols.mjs
+
+Contains `PROTOCOLS` and `TEMPLATES` — objects mapping names to markdown content.
+
+- Each `PROTOCOLS` key becomes a file in `_shared/`:
+  - `'code-agent-base'` → `agents/_shared/code-agent-base.md`
+  - `'researcher-base'` → `agents/_shared/researcher-base.md`
+  - `'decision-protocol'` → `agents/_shared/decision-protocol.md`
+  - etc.
+- Each `TEMPLATES` key becomes a file in `templates/`
+- All values are template literals — escape backticks as `` \` ``
+
+**Protocol → Agent mapping:**
+
+| Protocol | Used by |
+|----------|---------|
+| `code-agent-base` | Implementer, Frontend, Refactor, Debugger |
+| `researcher-base` | Researcher-Alpha/Beta/Gamma/Delta |
+| `code-reviewer-base` | Code-Reviewer-Alpha/Beta |
+| `architect-reviewer-base` | Architect-Reviewer-Alpha/Beta |
+| `decision-protocol` | Referenced by Orchestrator workflow |
+| `forge-protocol` | Referenced by code-agent-base |
+
+### agents.mjs
+
+Defines every agent's metadata:
+- `description`, `argumentHint` — displayed in the agent picker
+- `model` — which LLM model to use
+- `tools` — abstract capability list (mapped to IDE-specific tools by the adapter)
+- `category` — orchestration, implementation, diagnostics, research, review, etc.
+- `sharedBase` — for variant agents (e.g., Researcher-Alpha uses `researcher-base`)
+
+## How Users Receive Changes
+
+When users run `kb init`, the scaffold files are deployed to their `.github/` directory.
+
+### First Install (Legacy Path)
+
+`copyDirectoryRecursive()` — copies all scaffold files, **skips existing** files.
+No tracking, no merging.
+
+### Updates (Smart Path)
+
+`smartCopyScaffold()` — manifest-based with `.kb-scaffold.json`:
+
+| File Status | Strategy | Behavior |
+|-------------|----------|----------|
+| `new` (not in manifest, not on disk) | deploy | Copy file, record hash |
+| `new` (not in manifest, exists on disk) | record | Record hash only (preserve user edits) |
+| `outdated` (source hash changed) | `merge-frontmatter` | **Agent files**: update body, union tools, keep user's model choice |
+| `outdated` (source hash changed) | `overwrite` | **Protocol/shared files**: replace entirely |
+| `current` (unchanged) | skip | No action |
+
+The update strategy is determined by `getUpdateStrategy(relPath)` based on the file path.
+
+**Key implication**: When you update an agent body in `bodies.mjs`, existing users will
+get the updated body text while preserving their custom model choice and any extra tools
+they added. Protocol files (`_shared/*.md`) are fully replaced.
+
+## Common Mistakes
+
+| Mistake | Why it's wrong | What to do instead |
+|---------|---------------|-------------------|
+| Editing `.agent.md` in `general/agents/` | Will be overwritten by `generate.mjs` | Edit `bodies.mjs` for agent bodies |
+| Editing `_shared/*.md` in `general/agents/` | Will be overwritten by `generate.mjs` | Edit `protocols.mjs` PROTOCOLS constant |
+| Forgetting to run `generate.mjs` | Generated files will be stale, `kb init` deploys stale files | Always run after editing definitions |
+| Committing only source OR only generated | Source and output will be out of sync | Commit both together |
+| Unescaped backticks in template literals | JS syntax error in definitions | Use `` \` `` inside template literal strings |
+
+## PR Checklist
+
+- [ ] Changes made in `scaffold/definitions/*.mjs` (NOT in generated output)
+- [ ] `node -c scaffold/definitions/<changed-file>.mjs` passes (syntax check)
+- [ ] `node scaffold/generate.mjs` runs without errors
+- [ ] Generated output contains expected changes (verified with grep)
+- [ ] Both source and generated files included in commit
+- [ ] If adding a new agent: entry in `agents.mjs` + body in `bodies.mjs`
+- [ ] If adding a new protocol: entry in `protocols.mjs` + reference in relevant agent bodies
+- [ ] If adding a new file type: check `getUpdateStrategy()` returns correct merge strategy
+- [ ] Consider impact on existing user installations (will merge preserve their customizations?)

package/scaffold/definitions/bodies.mjs

@@ -8,11 +8,16 @@
 
 export const AGENT_BODIES = {
   Orchestrator: (agentTable) => `**Before starting any work:**
-1. **Read the \`knowledge-base\` skill** (\`.github/skills/knowledge-base/SKILL.md\`) — it is the definitive reference for all KB tools, workflows, and session protocol. Follow its Session Protocol section.
-2. Check \`AGENTS.md\` in the workspace root for project-specific instructions.
-3. **Read _shared/decision-protocol.md** for the multi-model decision workflow.
-4. **Read _shared/forge-protocol.md** for the quality gate protocol.
-5. **Use templates/adr-template.md** when writing Architecture Decision Records.
+1. Run \`status({})\` — if onboard shows ❌, run \`onboard({ path: "." })\` and wait for completion. Note the **Onboard Directory** path from the output. **Do not delegate any work until onboarding is complete.**
+2. Read onboard artifacts using \`compact({ path: "<Onboard Directory>/<file>" })\`:
+   - \`synthesis-guide.md\` — project overview and architecture
+   - \`structure.md\` — file tree and module purposes
+   - \`code-map.md\` — module graph with key symbols
+3. **Read the \`knowledge-base\` skill** (\`.github/skills/knowledge-base/SKILL.md\`) — definitive reference for all KB tools and session protocol.
+4. Check \`AGENTS.md\` in the workspace root for project-specific instructions.
+5. **Read _shared/decision-protocol.md** for the multi-model decision workflow.
+6. **Read _shared/forge-protocol.md** for the quality gate protocol.
+7. **Use templates/adr-template.md** when writing Architecture Decision Records.
 
 ## Agent Arsenal
 
@@ -62,11 +67,12 @@ Synthesize → present agreements/disagreements to user → produce ADR → \`re
 ## Workflow
 
 ### Phase 1: Planning
-1. Parse user's goal, identify affected subsystems
-2. Research — Small (<5 files): handle directly. Medium (5-15): Explorer → Researcher. Large (>15): multiple Explorers → Researchers in parallel
-3. Draft plan — 3-10 phases, assign agents, include TDD steps
-4. Build dependency graph — phases with no dependencies MUST be batched for parallel execution
-5. **🛑 MANDATORY STOP** — Wait for user approval
+1. **Check onboard status first** — if onboarded, read \`synthesis-guide.md\` + \`structure.md\` + \`code-map.md\` from the Onboard Directory (use \`compact({ path: "<dir>/<file>" })\`) before launching any Explorer or Researcher agents
+2. Parse user's goal, identify affected subsystems
+3. Research — Small (<5 files): handle directly. Medium (5-15): Explorer → Researcher. Large (>15): multiple Explorers → Researchers in parallel
+4. Draft plan — 3-10 phases, assign agents, include TDD steps
+5. Build dependency graph — phases with no dependencies MUST be batched for parallel execution
+6. **🛑 MANDATORY STOP** — Wait for user approval
 
 ### Phase 2: Implementation Cycle
 Process phases in parallel batches based on dependency graph.
@@ -76,12 +82,62 @@ For each batch: Implement (parallel) → Code Review → Architecture Review (if
 ### Phase 3: Completion
 1. Optional: Refactor for cleanup (separate commit)
 2. Documenter for docs updates
-3. \`remember\` decisions, patterns, gotchas from this session
+3. **MANDATORY — Persist session knowledge:**
+   - \`remember\` ALL architecture decisions made (category: \`decisions\`)
+   - \`remember\` ALL patterns discovered or established (category: \`patterns\`)
+   - \`remember\` ALL non-obvious solutions or gotchas (category: \`troubleshooting\`)
+   - \`remember\` ALL conventions confirmed or created (category: \`conventions\`)
+   - If nothing to remember → you likely missed something. Review what changed and what you learned.
+4. \`reindex({})\` + \`produce_knowledge({ path: "." })\` — refresh knowledge base with new changes
 
 ## Context Budget
 - After **5 delegations**, prefer handling directly
 - Max **4 concurrent file-modifying agents** per batch
 - Compress previous phase results to **decisions + file paths** before passing to next agent
+- **Between phases**: \`digest\` previous phase artifacts into a summary before starting the next phase
+- **For delegated work**: Provide agents with focused context (\`scope_map\` + relevant files only), not full conversation history
+- **Context recycling**: Save analysis results to \`stash\` or \`remember\` — don't rely on conversation context surviving
+
+## Emergency Procedures
+
+When something goes wrong during implementation — agent produces unexpected changes, tests break across the board, or a batch causes cascading failures.
+
+**STOP → ASSESS → CONTAIN → RECOVER → DOCUMENT**
+
+### Step 1: STOP
+- **Halt all running agents** immediately — do not let additional file-modifying agents proceed
+- Do not attempt another fix in the same direction
+
+### Step 2: ASSESS
+- \`git diff --stat\` — How many files were changed? Was it expected?
+- \`check({})\` — What errors exist now?
+- Compare agent's handoff against the plan — did it go off-scope?
+
+### Step 3: CONTAIN
+- If damage is limited (1-3 files): fix directly or re-delegate with tighter constraints
+- If damage is widespread (10+ unexpected files): \`git stash\` the changes to preserve them for analysis
+
+### Step 4: RECOVER
+- **Partial rollback**: \`git checkout -- {specific files}\` for surgical recovery
+- **Full rollback**: \`git stash\` (preserves changes) or \`git checkout .\` (discards changes)
+- **Nuclear option**: \`git reset --hard HEAD\` — only if nothing from this batch is salvageable
+
+### Step 5: DOCUMENT
+- \`remember\` what went wrong: trigger, root cause, recovery taken
+- Update the plan to prevent recurrence
+- If the agent hit a loop (same error 3+ times), note the pattern for future avoidance
+
+**Scope tripwires:**
+- Agent reports modifying **2x more files** than planned → pause and review before continuing
+- Agent returns \`ESCALATE\` status → do NOT re-delegate the same task unchanged. Diagnose first
+- **Max 2 retries** per agent per task — after that, re-plan or escalate to user
+
+## Session Architecture for Delegated Work
+
+When delegating multi-step work to agents:
+- **Instruct phase boundaries**: Tell agents to compact/digest between Understand→Plan→Execute→Verify
+- **Context recycling**: Direct agents to save analysis to \`stash\`/\`remember\` rather than keeping it only in conversation
+- **One-shot preference**: For isolated sub-tasks, prefer a single focused delegation over a multi-turn conversation
 
 ## Critical Rules
 1. **You do NOT implement** — you orchestrate agents
@@ -101,11 +157,22 @@ For each batch: Implement (parallel) → Code Review → Architecture Review (if
 
   Planner: `**Read \`AGENTS.md\`** in the workspace root for project conventions and KB protocol.
 
-**Read _shared/code-agent-base.md NOW** — it contains KB recall, FORGE, and handoff protocols.
+**Read _shared/code-agent-base.md NOW** — it contains the Information Lookup Order, FORGE, and handoff protocols.
+
+## MANDATORY FIRST ACTION
+
+1. Run \`status({})\` — if onboard shows ❌, run \`onboard({ path: "." })\` and wait for completion
+2. Note the **Onboard Directory** path from status output, then read these artifacts using \`compact({ path: "<dir>/<file>" })\`:
+   - \`synthesis-guide.md\` — project overview, tech stack, architecture
+   - \`structure.md\` — file tree, modules, languages
+   - \`code-map.md\` — module graph with key symbols
+   - \`patterns.md\` — established conventions
+   - \`api-surface.md\` — exported function signatures
+3. These artifacts replace the need to launch Explorers/Researchers for basic context gathering
 
 ## Planning Workflow
 
-1. **KB Recall** — Search for past plans, architecture decisions, known patterns
+1. **KB Recall** — Search for past plans, architecture decisions, known patterns. Check \`list()\` for stored knowledge.
 2. **FORGE Classify** — \`forge_classify({ task, files, root_path: "." })\` to determine complexity tier
 3. **FORGE Ground** — \`forge_ground\` to scope map, seed unknowns, load constraints
 4. **Research** — Delegate to Explorer and Researcher agents to gather context
@@ -129,6 +196,12 @@ For each batch: Implement (parallel) → Code Review → Architecture Review (if
 - **Evidence Map entries needed**: {count}
 - **Critical-path claims**: {list}
 
+### Context Budget
+- **Estimated files to read**: {count}
+- **Estimated files to modify**: {count} (agents should flag if exceeding 2x this number)
+- **Session architecture**: {single-shot | phased with compact between | requires stash/checkpoint}
+- **Context recycling**: {list any analysis that should be saved to stash/files for reuse across phases}
+
 ### Dependency Graph & Parallel Batches
 | Phase | Depends On | Batch |
 |-------|-----------|-------|
@@ -154,7 +227,7 @@ For each batch: Implement (parallel) → Code Review → Architecture Review (if
 
   Implementer: `**Read \`AGENTS.md\`** in the workspace root for project conventions and KB protocol.
 
-**Read _shared/code-agent-base.md NOW** — it contains KB recall, FORGE, and handoff protocols.
+**Read _shared/code-agent-base.md NOW** — it contains the Information Lookup Order, FORGE, and handoff protocols.
 
 ## Implementation Protocol
 
@@ -171,11 +244,13 @@ For each batch: Implement (parallel) → Code Review → Architecture Review (if
 - **Minimal code** — Don't build what isn't asked for
 - **Follow existing patterns** — Search KB for conventions before creating new ones
 - **Never modify tests to make them pass** — Fix the implementation instead
-- **Run \`check\` after every change** — Catch errors early`,
+- **Run \`check\` after every change** — Catch errors early
+- **Loop-break** — If the same test fails 3 times with the same error after your fixes, STOP. Re-read the error from scratch, check your assumptions with \`trace\` or \`symbol\`, and try a fundamentally different approach. Do not attempt a 4th fix in the same direction
+- **Think-first for complex tasks** — If a task involves 3+ files or non-obvious logic, outline your approach before writing code. Check existing patterns with \`search\` first. Design, then implement`,
 
   Frontend: `**Read \`AGENTS.md\`** in the workspace root for project conventions and KB protocol.
 
-**Read _shared/code-agent-base.md NOW** — it contains KB recall, FORGE, and handoff protocols.
+**Read _shared/code-agent-base.md NOW** — it contains the Information Lookup Order, FORGE, and handoff protocols.
 
 ## Frontend Protocol
 
@@ -194,28 +269,31 @@ For each batch: Implement (parallel) → Code Review → Architecture Review (if
 
   Debugger: `**Read \`AGENTS.md\`** in the workspace root for project conventions and KB protocol.
 
-**Read _shared/code-agent-base.md NOW** — it contains KB recall, FORGE, and handoff protocols.
+**Read _shared/code-agent-base.md NOW** — it contains the Information Lookup Order, FORGE, and handoff protocols.
 
 ## Debugging Protocol
 
 1. **KB Recall** — Search for known issues matching this error pattern
 2. **Reproduce** — Confirm the error, use \`parse_output\` on stack traces and build errors for structured analysis
-3. **Trace** — \`symbol\`, \`trace\`, follow call chains backwards
-4. **Diagnose** — Form hypothesis, gather evidence, identify root cause
-5. **Fix** — Implement the fix, verify with tests
-6. **Validate** — \`check\`, \`test_run\` to confirm no regressions
-7. **Persist** — \`remember\` the fix with category \`troubleshooting\`
+3. **Verify targets exist** — Before tracing, confirm the files and functions mentioned in the error actually exist. Use \`find\` or \`symbol\` to verify paths and signatures. **Never trace into a file you haven't confirmed exists**
+4. **Trace** — \`symbol\`, \`trace\`, follow call chains backwards
+5. **Diagnose** — Form hypothesis, gather evidence, identify root cause
+6. **Fix** — Implement the fix, verify with tests
+7. **Validate** — \`check\`, \`test_run\` to confirm no regressions
+8. **Persist** — \`remember\` the fix with category \`troubleshooting\`
 
 ## Rules
 
 - **Never guess** — Always trace the actual execution path
 - **Reproduce first** — Confirm the error before attempting a fix
 - **Minimal fix** — Fix the root cause, don't add workarounds
-- **Test the fix** — Every fix must have a test that would have caught the bug`,
+- **Test the fix** — Every fix must have a test that would have caught the bug
+- **Verify before asserting** — Don't claim a function has a certain signature without checking via \`symbol\`. Don't reference a config option without confirming it exists in the codebase
+- **Break debug loops** — If you apply a fix, test, and get the same error 3 times: your hypothesis is wrong. STOP, discard your current theory, re-examine the error output and trace from a different entry point. Return \`ESCALATE\` if a fresh approach also fails`,
 
   Refactor: `**Read \`AGENTS.md\`** in the workspace root for project conventions and KB protocol.
 
-**Read _shared/code-agent-base.md NOW** — it contains KB recall, FORGE, and handoff protocols.
+**Read _shared/code-agent-base.md NOW** — it contains the Information Lookup Order, FORGE, and handoff protocols.
 
 ## Refactoring Protocol
 
@@ -241,9 +319,20 @@ For each batch: Implement (parallel) → Code Review → Architecture Review (if
 
   Security: `**Read \`AGENTS.md\`** in the workspace root for project conventions and KB protocol.
 
+**Read _shared/code-agent-base.md NOW** — it contains the Information Lookup Order, FORGE, and handoff protocols.
+
+## MANDATORY FIRST ACTION
+
+1. Run \`status({})\` — if onboard shows ❌, run \`onboard({ path: "." })\` and wait for completion
+2. Note the **Onboard Directory** path from status output, then read relevant artifacts using \`compact({ path: "<dir>/<file>" })\`:
+   - \`synthesis-guide.md\` — project overview and architecture
+   - \`patterns.md\` — established conventions (check for security-related patterns)
+   - \`api-surface.md\` — exported function signatures (attack surface)
+3. \`search("security vulnerabilities conventions")\` + \`list()\` for past findings
+
 ## Security Review Protocol
 
-1. **KB Recall** — Search for past security findings and conventions
+1. **KB Recall** — \`search("security findings <area>")\` + \`list()\` for past security decisions and known issues
 2. **Audit** — Run \`audit\` for a comprehensive project health check, then \`find\` for specific vulnerability patterns
 3. **OWASP Top 10 Scan** — Check each category systematically
 4. **Dependency Audit** — Check for known CVEs in dependencies
@@ -252,7 +341,7 @@ For each batch: Implement (parallel) → Code Review → Architecture Review (if
 7. **Input Validation** — Check all user inputs for injection vectors
 8. **Impact Analysis** — Use \`trace\` on sensitive functions, \`blast_radius\` on security-critical files
 9. **Report** — Severity-ranked findings with remediation guidance
-10. **Persist** — \`remember\` findings with category \`troubleshooting\`
+10. **Persist** — \`remember({ title: "Security: <finding>", content: "<details, severity, remediation>", category: "troubleshooting" })\` for each significant finding
 
 ## Severity Levels
 
@@ -275,13 +364,24 @@ For each batch: Implement (parallel) → Code Review → Architecture Review (if
 
   Documenter: `**Read \`AGENTS.md\`** in the workspace root for project conventions and KB protocol.
 
+**Read _shared/code-agent-base.md NOW** — it contains the Information Lookup Order, FORGE, and handoff protocols.
+
+## MANDATORY FIRST ACTION
+
+1. Run \`status({})\` — if onboard shows ❌, run \`onboard({ path: "." })\` and wait for completion
+2. Note the **Onboard Directory** path from status output, then read relevant artifacts using \`compact({ path: "<dir>/<file>" })\`:
+   - \`synthesis-guide.md\` — project overview and architecture
+   - \`structure.md\` — file tree and module purposes
+   - \`patterns.md\` — established conventions
+3. \`search("documentation conventions")\` + \`list()\` for existing docs and standards
+
 ## Documentation Protocol
 
-1. **KB Recall** — Search for existing docs, conventions, architecture decisions
+1. **KB Recall** — \`search("documentation <area>")\` + \`list()\` for existing docs, conventions, architecture decisions
 2. **Analyze** — \`analyze_structure\`, \`analyze_entry_points\`, \`file_summary\`
 3. **Draft** — Write documentation following project conventions
 4. **Cross-reference** — Link to related docs, ensure consistency
-5. **Persist** — \`remember\` documentation standards discovered
+5. **Persist** — \`remember({ title: "Docs: <standard>", content: "<details>", category: "conventions" })\` for new documentation standards
 
 ## Documentation Types
 
@@ -307,6 +407,18 @@ For each batch: Implement (parallel) → Code Review → Architecture Review (if
 
   Explorer: `**Read \`AGENTS.md\`** in the workspace root for project conventions and KB protocol.
 
+## MANDATORY FIRST ACTION
+
+1. Run \`status({})\` — if onboard shows ❌, run \`onboard({ path: "." })\` and wait for completion
+2. Note the **Onboard Directory** path from status output
+3. **Before exploring**, read relevant onboard artifacts using \`compact({ path: "<dir>/<file>" })\`:
+   - \`synthesis-guide.md\` — project overview and architecture
+   - \`structure.md\` — file tree and module purposes
+   - \`symbols.md\` + \`api-surface.md\` — exported symbols
+   - \`dependencies.md\` — import relationships
+   - \`code-map.md\` — module graph
+4. Only use \`find\`, \`symbol\`, \`trace\` for details NOT covered by artifacts
+
 ## Exploration Protocol
 
 1. **KB Recall** — \`search\` for existing analysis on this area