@vpxa/aikit 0.1.74 → 0.1.76

package/scaffold/{compiled → dist/compiled}/skills-data.mjs

@@ -1,7 +1,4 @@
-// Auto-generated by scaffold/compile.mjs — DO NOT EDIT
-export const SKILLS = {
-  "adr-skill": [
-    { file: "assets/templates/adr-madr.md", content: `---
+const e={"adr-skill":[{file:`assets/templates/adr-madr.md`,content:`---
 status: '{proposed | accepted | rejected | deprecated | superseded by [title](YYYY-MM-DD-title.md)}'
 date: { YYYY-MM-DD }
 decision-makers: '{list everyone who owns the decision}'
@@ -90,29 +87,7 @@ Chosen option: "{title of option 1}", because {justification — reference drive
 ## More Information
 
 {Additional context, links to related ADRs, team agreements, implementation notes, or conditions that would trigger revisiting this decision. This section is a catch-all for anything that helps future readers (human or agent) understand the full picture.}
-` },
-    { file: "assets/templates/adr-readme.md", content: `# Architecture Decision Records (ADR)
-
-An Architecture Decision Record (ADR) captures an important architecture decision along with its context and consequences.
-
-## Conventions
-
-- Directory: \`{ADR_DIR}\`
-- Naming:
-  - Use date-prefixed files: \`YYYY-MM-DD-choose-database.md\`
-  - If the repo already uses slug-only names, keep that: \`choose-database.md\`
-- Status values: \`proposed\`, \`accepted\`, \`rejected\`, \`deprecated\`, \`superseded\`
-
-## Workflow
-
-- Create a new ADR as \`proposed\`.
-- Discuss and iterate.
-- When the team commits: mark it \`accepted\` (or \`rejected\`).
-- If replaced later: create a new ADR and mark the old one \`superseded\` with a link.
-
-## ADRs
-` },
-    { file: "assets/templates/adr-simple.md", content: `---
+`},{file:`assets/templates/adr-readme.md`,content:"# Architecture Decision Records (ADR)\n\nAn Architecture Decision Record (ADR) captures an important architecture decision along with its context and consequences.\n\n## Conventions\n\n- Directory: `{ADR_DIR}`\n- Naming:\n  - Use date-prefixed files: `YYYY-MM-DD-choose-database.md`\n  - If the repo already uses slug-only names, keep that: `choose-database.md`\n- Status values: `proposed`, `accepted`, `rejected`, `deprecated`, `superseded`\n\n## Workflow\n\n- Create a new ADR as `proposed`.\n- Discuss and iterate.\n- When the team commits: mark it `accepted` (or `rejected`).\n- If replaced later: create a new ADR and mark the old one `superseded` with a link.\n\n## ADRs\n"},{file:`assets/templates/adr-simple.md`,content:`---
 status: '{proposed | accepted | rejected | deprecated | superseded by [title](YYYY-MM-DD-title.md)}'
 date: { YYYY-MM-DD }
 decision-makers: '{list everyone who owns the decision}'
@@ -158,8 +133,7 @@ decision-makers: '{list everyone who owns the decision}'
 ## More Information
 
 {Related ADRs, PRs, issues, docs, or conditions that would trigger revisiting this decision.}
-` },
-    { file: "references/adr-conventions.md", content: `# ADR Conventions (Reference)
+`},{file:`references/adr-conventions.md`,content:`# ADR Conventions (Reference)
 
 ## Directory
 
@@ -254,8 +228,7 @@ contributing/decisions/   # or docs/decisions/
 Date prefixes are local to each category. Choose a categorization scheme early (by architectural layer, by domain, by team) and document it in the index.
 
 Alternative: use tags or a flat structure with a searchable index. Subdirectories are simpler and work with all tools.
-` },
-    { file: "references/examples.md", content: `# ADR Examples
+`},{file:`references/examples.md`,content:`# ADR Examples
 
 These are filled-out examples showing the same decision at two levels of detail. Use these as reference when drafting ADRs — never leave placeholder text in a real ADR.
 
@@ -448,8 +421,7 @@ Spin up a fresh PostgreSQL container for each CI job.
 - Revisit trigger: if dialect-drift bugs exceed 2 per quarter, reconsider Docker PostgreSQL approach
 - Code references: after implementation, key files will have \`// ADR: 2025-06-15-use-sqlite-for-test-database\` comments at entry points
 \`\`\`
-` },
-    { file: "references/review-checklist.md", content: `# ADR Review Checklist
+`},{file:`references/review-checklist.md`,content:`# ADR Review Checklist
 
 Use this checklist in Phase 3 to validate an ADR before finalizing. The goal: **could a coding agent read this ADR and start implementing the decision immediately, without asking any clarifying questions?**
 
@@ -526,8 +498,7 @@ Count the checked items. This isn't a gate — it's a conversation tool.
 | Implementation Plan says "update the code" | Too abstract                           | Ask: "which files, which functions, what pattern?"          |
 | Verification says "it works"               | Not testable                           | Ask: "what command would you run to prove it works?"        |
 | No affected paths listed                   | Implementation Plan is hand-wavy       | Agent should scan the codebase and propose specific paths   |
-` },
-    { file: "references/template-variants.md", content: `# Template Variants
+`},{file:`references/template-variants.md`,content:`# Template Variants
 
 This skill ships two templates in \`assets/templates/\`.
 
@@ -579,8 +550,7 @@ This template aligns with [MADR 4.0](https://adr.github.io/madr/) and extends it
 | Needs stakeholder review | No              | Yes          |
 
 When in doubt, start with Simple. You can always expand to MADR if the discussion reveals more complexity.
-` },
-    { file: "scripts/bootstrap_adr.js", content: `#!/usr/bin/env node
+`},{file:`scripts/bootstrap_adr.js`,content:`#!/usr/bin/env node
 /**
  * Bootstrap ADRs in a repo:
  * - create ADR directory
@@ -839,8 +809,7 @@ function main() {
 }
 
 main();
-` },
-    { file: "scripts/new_adr.js", content: `#!/usr/bin/env node
+`},{file:`scripts/new_adr.js`,content:`#!/usr/bin/env node
 /**
  * Create a new ADR markdown file using repo conventions and a template.
  *
@@ -1231,8 +1200,7 @@ function main() {
 }
 
 main();
-` },
-    { file: "scripts/set_adr_status.js", content: `#!/usr/bin/env node
+`},{file:`scripts/set_adr_status.js`,content:`#!/usr/bin/env node
 /**
  * Update an ADR's status in-place.
  *
@@ -1401,8 +1369,7 @@ function main() {
 }
 
 main();
-` },
-    { file: "SKILL.md", content: `---
+`},{file:`SKILL.md`,content:`---
 name: adr-skill
 description: Create and maintain Architecture Decision Records (ADRs) optimized for agentic coding workflows. Use when you need to propose, write, update, accept/reject, deprecate, or supersede an ADR; bootstrap an adr folder and index; consult existing ADRs before implementing changes; or enforce ADR conventions. This skill uses Socratic questioning to capture intent before drafting, and validates output against an agent-readiness checklist.
 metadata:
@@ -1737,767 +1704,7 @@ Notes:
 - Scripts auto-detect ADR directory and filename strategy.
 - Use \`--dir\` and \`--strategy\` to override.
 - Use \`--json\` to emit machine-readable output.
-` },
-  ],
-  "aikit": [
-    { file: "SKILL.md", content: `---
-name: aikit
-description: "Use the @vpxa/aikit AI Kit MCP server for codebase search, analysis, and persistent memory. Load this skill when using aikit_search, aikit_remember, aikit_analyze_*, or any aikit_* tool. Covers all 82 MCP tools: search (hybrid/semantic/keyword), code analysis (structure, dependencies, symbols, patterns, entry points, diagrams, blast radius), knowledge graph (auto-populated module/symbol/import graph with traversal), context management (worksets, stash, checkpoints, restore, lanes), code manipulation (rename, codemod, eval), knowledge management (remember/read/update/forget), web access (fetch, search, http), FORGE protocol (ground, classify, evidence map, stratum cards, digest), brainstorming (interactive ideation sessions), presentation (rich dashboards via present tool), onboarding (full codebase analysis in one call), and developer utilities (regex, encode, measure, changelog, schema-validate, snippet, env, time)."
-metadata:
-  category: cross-cutting
-  domain: general
-  applicability: always
-  inputs: [codebase]
-  outputs: [search-results, analysis, knowledge]
-  relatedSkills: [present]
----
-
-# @vpxa/aikit — AI Kit
-
-Local-first AI developer toolkit — 82 MCP tools for search, analysis, context compression, FORGE quality gates, knowledge management, code manipulation, execution, web access, brainstorming, presentation, and developer utilities.
-
-## When to Use
-
-- You need long-term memory across coding sessions
-- You want to search a codebase semantically (by meaning, not just keywords)
-- You need to compress large contexts to focus on what matters
-- You want structured output from build tools (tsc, vitest, biome, git)
-- You need to plan which files to read for a task
-- You want to safely explore refactors in isolated lanes
-- You need to rename symbols, apply codemods, or run code transformations
-- You want to fetch and read web pages or search the web
-- You need to make HTTP requests, test APIs, or debug endpoints
-- You want to test regex patterns, encode/decode data, or validate JSON schemas
-- You need code complexity metrics or a git changelog
-- You want to save and reuse code snippets across sessions
-
-## Skills Reference
-
-| Context | Skill | Load when |
-|---------|-------|----------|
-| Repository access recovery | \`repo-access\` | When encountering git auth failures, accessing private/enterprise repos, or when \`web_fetch\`/\`http\` returns auth errors on repository URLs. |
-
-## Architecture
-
-10-package monorepo published as a single npm package:
-
-\`\`\`
-core → store → embeddings → chunker → indexer → analyzers → tools → server → cli → tui
-\`\`\`
-
-- **MCP server**: 82 tools + 2 resources (via \`@modelcontextprotocol/sdk\`)
-- **CLI**: 45 commands (thin dispatcher + 10 command groups)
-- **Search**: Hybrid vector + keyword + RRF fusion
-- **Embeddings**: ONNX local (mxbai-embed-large-v1, 1024 dimensions)
-- **Vector store**: LanceDB (embedded, zero infrastructure)
-- **Chunking**: Tree-sitter AST (TS/JS/Python/Go/Rust/Java) + regex fallback
-- **TUI**: Ink/React dashboard for human monitoring (search, status, curated, activity log)
-
-## Session Protocol (MANDATORY)
-
-### Start (do ALL)
-\`\`\`
-flow_status({})                                                # Check/resume active flow FIRST
-# If flow active → flow_read_instruction({ step }) → follow step instructions
-status({})                                                     # Check AI Kit health + onboard state
-# If onboard not run → onboard({ path: "." })                 # First-time codebase analysis
-flow_list({})                                                  # See available flows
-# Select flow based on task → flow_start({ flow: "<name>", topic: "<task>" })  # Start — creates .flows/{topic}/
-list()                                                         # See stored knowledge
-search({ query: "SESSION CHECKPOINT", origin: "curated" })     # Resume prior work
-\`\`\`
-
-### During Session
-\`\`\`
-search → scope_map → symbol → trace  (orient)
-check → test_run                             (validate changes)
-remember                                         (capture insights)
-\`\`\`
-
-### End of Session
-\`\`\`
-session_digest({ persist: true })                              # Auto-capture session activity
-remember({ title: "Session checkpoint: <topic>", content: "<what was done, decisions made, next steps>", category: "conventions" })
-\`\`\`
-
-## Tool Catalog (82 tools)
-
-### Search & Discovery (8)
-| Tool | CLI | Purpose |
-|------|-----|---------|
-| \`search\` | \`aikit search\` | Hybrid/semantic/keyword search with \`search_mode\` param |
-| \`find\` | \`aikit find\` | Federated search: vector + FTS + glob + regex in one call. Use \`mode: 'examples'\` to find usage examples. |
-| \`symbol\` | \`aikit symbol\` | Resolve symbol definition, imports, and references |
-| \`lookup\` | \`aikit lookup\` | Full-file retrieval by path or record ID |
-| \`scope_map\` | \`aikit scope-map\` | Task-scoped reading plan with token estimates |
-| \`trace\` | \`aikit trace\` | Forward/backward flow tracing through call chains |
-| \`dead_symbols\` | \`aikit dead-symbols\` | Find exported symbols never imported — separates source (actionable) from docs (informational). Accepts \`path\` to scope the search. |
-| \`file_summary\` | \`aikit summarize\` | Structural overview of a file (exports, imports, functions) |
-
-### Code Analysis (7)
-| Tool | CLI | Purpose |
-|------|-----|---------|
-| \`analyze_structure\` | \`aikit analyze structure\` | Project structure overview |
-| \`analyze_dependencies\` | \`aikit analyze deps\` | Dependency graph with confidence |
-| \`analyze_symbols\` | \`aikit analyze symbols\` | Symbol extraction and cross-references |
-| \`analyze_patterns\` | \`aikit analyze patterns\` | Design pattern detection |
-| \`analyze_entry_points\` | \`aikit analyze entry-points\` | Find entry points: handlers, CDK constructs, test suites, package exports (walks workspace packages) |
-| \`analyze_diagram\` | \`aikit analyze diagram\` | Generate Mermaid diagrams |
-| \`blast_radius\` | \`aikit analyze blast-radius\` | Change impact analysis |
-
-### Context Management (6)
-| Tool | CLI | Purpose |
-|------|-----|---------|
-| \`compact\` | \`aikit compact\` | Compress text to relevant sections using embeddings (no LLM). Accepts \`path\` for server-side file read. |
-| \`workset\` | \`aikit workset\` | Named file set management (save/load/add/remove) |
-| \`stash\` | \`aikit stash\` | Named key-value store for session data |
-| \`checkpoint\` | \`aikit checkpoint\` | Save/restore session checkpoints |
-| \`restore\` | \`aikit restore\` | Restore a previously saved checkpoint |
-| \`parse_output\` | \`aikit parse-output\` | Parse tsc/vitest/biome/git output → structured JSON |
-
-### Code Manipulation (4)
-| Tool | CLI | Purpose |
-|------|-----|---------|
-| \`rename\` | \`aikit rename\` | Smart whole-word symbol rename across files (dry-run supported) |
-| \`codemod\` | \`aikit codemod\` | Regex-based code transformations with rules (dry-run supported) |
-| \`diff_parse\` | \`aikit diff\` | Parse unified diff → structured changes |
-| \`data_transform\` | \`aikit transform\` | JQ-like JSON transformations |
-
-### Execution & Validation (5)
-| Tool | CLI | Purpose |
-|------|-----|---------|
-| \`eval\` | \`aikit eval\` | Sandboxed JavaScript/TypeScript execution |
-| \`check\` | \`aikit check\` | Incremental typecheck + lint. \`detail\` param: summary (default, ~300 tokens), errors, full |
-| \`test_run\` | \`aikit test\` | Run tests with structured pass/fail results |
-| \`batch\` | \`aikit batch\` | Execute multiple operations in parallel |
-| \`audit\` | \`aikit audit\` | Unified project audit: structure, deps, patterns, health, dead symbols, check, entry points → synthesized report with score and recommendations. 6 round-trips → 1. |
-
-### Knowledge Management (6)
-| Tool | CLI | Purpose |
-|------|-----|---------|
-| \`remember\` | \`aikit remember\` | Store a curated knowledge entry |
-| \`update\` | \`aikit update\` | Update an existing entry |
-| \`forget\` | \`aikit forget\` | Delete an entry (requires reason) |
-| \`read\` | \`aikit read\` | Read a curated entry by path |
-| \`list\` | \`aikit list\` | List curated entries |
-| \`produce_knowledge\` | — | Auto-generate knowledge from analysis |
-
-### Auto-Knowledge (automatic background extraction)
-
-Auto-knowledge runs automatically in the background after every tool completion. It extracts useful facts from tool outputs and stores them in curated memory — no manual action required.
-
-**What gets captured:**
-
-| Extractor | Triggers on | What it stores |
-|-----------|-------------|----------------|
-| Test results | \`check\`, \`test_run\` | Framework detection (vitest/jest/mocha), test file naming patterns |
-| Environment | \`env\`, \`config\`, \`status\` | Node.js version, OS, workspace path, store backend, embedding model |
-| Research | \`web_search\`, \`web_fetch\`, \`search\` | Web research findings, fetched page summaries |
-| Conventions | \`check\`, \`analyze_patterns\`, \`analyze_structure\`, \`onboard\` | Linter/formatter, TypeScript strict mode, package manager, monorepo detection |
-| Build commands | \`check\`, \`test_run\` | Verified check results, test summaries, test runner commands |
-| Codebase insights | \`analyze_*\`, \`scope_map\`, \`blast_radius\`, \`onboard\` | Structure analysis, dependency info, entry points, impact analysis |
-| Tool failures | All tools (global) | Classified actionable errors (filters out transient network/ENOENT errors) |
-
-**Quality controls:**
-- **Quality gate**: Facts scored 0-1; only facts >= 0.3 are stored
-- **Dedup**: Checks existing curated titles + in-memory hash dedup
-- **TTL**: Transient facts (errors, blast radius, search context) automatically expire after 1-2 hours
-- **Session limit**: Maximum 50 auto-knowledge facts per session
-
-**Searching auto-knowledge:**
-Auto-knowledge facts are stored as regular curated entries. Search them with:
-\`\`\`
-search({ query: "error patterns", origin: "curated" })
-search({ query: "conventions", origin: "curated" })
-list({ category: "conventions" })
-list({ tags: ["errors"] })
-\`\`\`
-
-### Verified Lanes (1 tool, 6 actions)
-| Tool | CLI | Purpose |
-|------|-----|---------|
-| \`lane\` | \`aikit lane\` | Manage isolated file copies for parallel exploration |
-
-Lane actions: \`create\` (copy files to lane), \`list\`, \`status\` (modified/added/deleted), \`diff\` (line-level diff), \`merge\` (apply back to originals), \`discard\`.
-
-### Git & Environment (4)
-| Tool | CLI | Purpose |
-|------|-----|---------|
-| \`git_context\` | \`aikit git\` | Branch, status, recent commits |
-| \`process\` | \`aikit proc\` | Process supervisor (start/stop/logs) |
-| \`watch\` | \`aikit watch\` | Filesystem watcher |
-| \`delegate\` | \`aikit delegate\` | Delegate subtask to local Ollama model |
-
-### Web & Network (3)
-| Tool | CLI | Purpose |
-|------|-----|---------|
-| \`web_fetch\` | — | Fetch web page → markdown/raw/links/outline for LLM consumption |
-| \`web_search\` | — | Search the web via DuckDuckGo (no API key needed) |
-| \`http\` | — | Make HTTP requests for API testing/debugging |
-
-### Developer Utilities (8)
-| Tool | CLI | Purpose |
-|------|-----|---------|
-| \`regex_test\` | — | Test regex patterns with match/replace/split modes |
-| \`encode\` | — | Base64, URL, SHA-256, MD5, hex encode/decode, JWT decode |
-| \`measure\` | — | Code complexity metrics (cyclomatic, cognitive complexity, lines, functions) |
-| \`changelog\` | — | Generate changelog from git history (conventional commits) |
-| \`schema_validate\` | — | Validate JSON data against JSON Schema |
-| \`snippet\` | — | Save/get/search/delete persistent code snippets |
-| \`env\` | — | System and runtime environment info (sensitive values redacted) |
-| \`time\` | — | Date parsing, timezone conversion, duration math |
-
-### FORGE Quality Gates (5)
-| Tool | CLI | Purpose |
-|------|-----|---------|
-| \`forge_ground\` | — | Full Ground phase: classify tier, scope map, unknowns, constraints |
-| \`forge_classify\` | — | Quick tier classification (Floor/Standard/Critical) |
-| \`evidence_map\` | — | CRUD + Gate evaluation for verified/assumed/unknown claims. Safety gate tags (\`provenance\`/\`commitment\`/\`coverage\`) enable mandatory pre-YIELD checks |
-| \`stratum_card\` | — | Generate T1/T2 compressed context cards from files (10-100x token reduction) |
-| \`digest\` | — | Compress N text sources into token-budgeted summary |
-
-### System (9)
-| Tool | CLI | Purpose |
-|------|-----|---------|
-| \`config\` | \`aikit config\` | View or update project configuration (kb.config.json) |
-| \`status\` | \`aikit status\` | Index statistics |
-| \`reindex\` | \`aikit reindex\` | Rebuild index |
-| \`health\` | \`aikit health\` | Project health checks (package.json, tsconfig, lockfile, circular deps) |
-| \`guide\` | \`aikit guide\` | Tool discovery — given a goal, recommends tools and workflow order |
-| \`onboard\` | \`aikit onboard\` | Full codebase onboarding in one call (structure + deps + patterns + knowledge) |
-| \`graph\` | \`aikit graph\` | Query the auto-populated knowledge graph (modules, symbols, imports) |
-| \`queue\` | \`aikit queue\` | Task queue for sequential agent operations (create/push/next/done/fail) |
-| \`replay\` | \`aikit replay\` | View or clear the audit trail of tool invocations (action: list/clear) |
-
-### Flows (11)
-| Tool | CLI | Purpose |
-|------|-----|---------|
-| \`flow_list\` | \`aikit flow list\` | List available flows and active run |
-| \`flow_info\` | \`aikit flow info\` | Get flow details including steps and skill paths |
-| \`flow_start\` | \`aikit flow start\` | Start a flow with topic — creates \`.flows/{topic-slug}/\` run directory |
-| \`flow_step\` | \`aikit flow step\` | Advance, skip, or redo the current step |
-| \`flow_status\` | \`aikit flow status\` | Check active run including slug, runDir, artifactsPath |
-| \`flow_read_instruction\` | \`aikit flow read-instruction\` | Read instruction with \`{{artifacts_path}}\` and \`{{run_dir}}\` resolved |
-| \`flow_reset\` | \`aikit flow reset\` | Abandon the active flow (preserves run directory) |
-| \`flow_runs\` | \`aikit flow runs\` | List all flow runs (current and past) |
-| \`flow_add\` | \`aikit flow add\` | Add a custom flow from a directory |
-| \`flow_update\` | \`aikit flow update\` | Update an existing custom flow |
-| \`flow_remove\` | \`aikit flow remove\` | Remove a custom flow |
-
-### Presentation (1)
-| Tool | CLI | Purpose |
-|------|-----|---------|
-| \`present\` | — | Rich dashboards, charts, tables, timelines. Use \`format: "browser"\` then \`openBrowserPage\` to display. **In CLI mode (no VS Code chat), always use \`format: "browser"\`** — \`html\` UIResource is invisible in terminal. |
-
-### Brainstorming (1)
-| Tool | CLI | Purpose |
-|------|-----|---------|
-| \`brainstorm\` | — | Interactive brainstorming and ideation sessions with structured output |
-
-### Meta-Tools — Tool Discovery (3)
-| Tool | CLI | Purpose |
-|------|-----|---------|
-| \`list_tools\` | — | List all active AI Kit tools with names, titles, and categories. Accepts optional \`category\` filter. Use for initial tool discovery. |
-| \`describe_tool\` | — | Get detailed metadata for a specific tool (title, categories, annotations). Use after \`list_tools\` to understand a tool before calling it. |
-| \`search_tools\` | — | Search active tools by keyword across names, titles, and categories. Use when you know what you need but not the tool name. |
-
-### Session Management (1)
-| Tool | CLI | Purpose |
-|------|-----|---------|
-| \`session_digest\` | — | Generate a compressed digest of session activity (replay log, stash, checkpoints). Options: \`scope\` (tools/stash/all), \`since\`, \`last\`, \`focus\`, \`mode\` (deterministic/sampling), \`tokenBudget\`, \`persist\`. Use at session end for handoff or mid-session to review what happened. |
-
-## Flow System
-
-Flows are multi-step guided workflows that structure complex tasks. Each step has a skill file with detailed instructions, required artifacts, and agent assignments.
-
-### Built-in Flows
-
-| Flow | Steps | Use When |
-|------|-------|----------|
-| \`aikit:basic\` | assess → implement → verify | Bug fixes, config changes, small features |
-| \`aikit:advanced\` | spec → plan → task → execute → verify | New modules, cross-service changes, architectural work |
-
-### Flow Lifecycle
-
-\`\`\`text
-flow_list()                          # See available flows
-flow_info({ flow: "aikit:basic" })   # View steps, skills, agents
-flow_start({ flow: "aikit:basic", topic: "Fix login bug" })  # Start — creates .flows/fix-login-bug/
-flow_read_instruction()              # Read current step's instructions ({{artifacts_path}} resolved)
-# ... do the work described in the instruction ...
-flow_step({ action: "next" })        # Advance to next step
-flow_step({ action: "skip" })        # Skip current step
-flow_step({ action: "redo" })        # Redo current step
-flow_status()                        # Check progress (includes slug, runDir, artifactsPath, phase, isEpilogue)
-flow_reset()                         # Abandon active flow
-flow_runs()                          # List all runs (current + past)
-# Epilogue steps (mandatory, injected after every flow):
-# After last flow step → _docs-sync epilogue runs automatically
-# flow_status() shows phase: 'after', isEpilogue: true during epilogue
-\`\`\`
-
-Custom flow lifecycle management:
-
-\`\`\`text
-flow_add({ source: ".github/flows/my-flow" })
-flow_update({ name: "my-flow" })
-flow_remove({ name: "my-flow" })
-\`\`\`
-
-### Creating Custom Flows
-
-1. Create a directory under \`.github/flows/<flow-name>/\`
-2. Add \`manifest.yaml\`:
-
-\`\`\`yaml
-name: my-flow
-version: "1.0.0"
-description: "My custom flow"
-artifacts_dir: .spec
-steps:
-  - id: design
-    name: Design
-    instruction: steps/design/README.md
-    description: "Create the design document"
-    produces: [design.md]
-    requires: []
-    agents: [Planner]
-  - id: implement
-    name: Implement
-    instruction: steps/implement/README.md
-    description: "Implement the design"
-    produces: [code]
-    requires: [design]
-    agents: [Implementer]
-agents:
-  - agents/planner.agent.md
-install: []
-\`\`\`
-
-3. Add skill files under \`.github/flows/<flow-name>/skills/<step-id>/SKILL.md\`
-4. The flow appears in \`flow_list()\` automatically
-
-### How Flows Are Delivered
-
-- **Built-in flows** ship with the AI Kit MCP server in \`scaffold/flows/\`
-- \`aikit init\` copies them to \`.github/flows/\` in your workspace
-- At runtime, flow tools resolve paths to \`.github/flows/\` (workspace-local copies)
-- Custom flows placed in \`.github/flows/\` are discovered alongside built-in ones
-
-### Agent-Flow Integration
-
-- All code agents have a "Flows" section instructing them to check \`flow_status()\` first
-- If a flow is active, the agent follows the current step's instruction via \`flow_read_instruction()\`
-- After completing a step's work, advance with \`flow_step({ action: "next" })\`
-- The **Orchestrator** selects and starts flows; other agents follow them
-- The **Orchestrator** specifies \`aikit\` skill loading — all agents should load \`aikit\` skill to access flow tools
-
-## CRITICAL: Use AI Kit Tools Instead of Native IDE Tools
-
-AI Kit tools provide **10x richer output** than native IDE tools — with AST-analyzed call graphs, scope context, import classification, and cognitive complexity. **You MUST use AI Kit tools instead of native read/search tools.**
-
-### ⛔ PROHIBITED: Native File Reading
-
-**\`read_file\` / \`read_file_raw\` MUST NOT be used to understand code.** They waste tokens and miss structural information.
-
-The **ONLY** acceptable use of \`read_file\`: getting exact lines immediately before an edit (to verify the \`old_str\` for replacement). Even then, use \`file_summary\` first to identify which lines to read.
-
-### Tool Replacement Table
-
-| ❌ NEVER do this | ✅ Use AI Kit Tool | Why |
-|---|---|---|
-| \`read_file\` (full file) | \`file_summary\` | Exports, imports, call edges — **10x fewer tokens** |
-| \`read_file\` (specific section) | \`compact({ path, query })\` | Server-side read + extract — **5-20x reduction** |
-| \`grep_search\` / \`textSearch\` | \`search\` | Semantic + keyword hybrid across all indexed content |
-| \`grep_search\` for a symbol | \`symbol\` | Definition + references **with scope context** |
-| Multiple \`read_file\` calls | \`digest\` | Compresses multiple sources into token-budgeted summary |
-| \`listDirectory\` + \`read_file\` | \`scope_map\` | Identifies relevant files for a task automatically |
-| Manual code tracing | \`trace\` | AST call-graph traversal with scope context |
-| Line counting / \`wc\` | \`measure\` | Lines, complexity, **cognitive complexity**, functions |
-| Grep for unused exports | \`dead_symbols\` | AST-powered export detection with regex fallback |
-| Repeated file reads | \`stratum_card\` | Reusable compressed context — **10-100x reduction** |
-| \`fetch_webpage\` | \`web_fetch\` | Readability extract + token budget — richer output |
-| Web research / browsing | \`web_search\` | Structured web results without browser — **unique to KB** |
-
-### Decision Tree — How to Read Code
-
-\`\`\`
-Need to understand a file?
-├─ Just structure?        → file_summary (exports, imports, call edges — ~50 tokens)
-├─ Specific section?      → compact({ path, query }) — 5-20x reduction
-├─ Multiple files?        → digest (multi-source compression — token-budgeted)
-├─ Repeated reference?    → stratum_card (T1/T2 card — 10-100x reduction)
-├─ Need exact lines to EDIT? → read_file (the ONLY acceptable use)
-└─ "I want to read the whole file" → ⛔ STOP. Use file_summary or compact instead.
-\`\`\`
-
-### Decision Tree — Need Structural Relationships?
-
-When vector search and file reads don't answer the question (e.g. "who imports this?",
-"what does this depend on?", "how are these files connected?"), use \`graph\`:
-
-\`\`\`
-Need to understand relationships between code?
-├─ Who imports / calls this?     → graph({action:'find_nodes', name_pattern}) → graph({action:'neighbors', node_id, direction:'incoming'})
-├─ What does this depend on?     → graph({action:'neighbors', node_id, direction:'outgoing'})
-├─ Full context for a symbol?    → graph({action:'symbol360', name})
-├─ Related files within N hops?  → graph({action:'traverse', node_id, max_depth:2})
-├─ Layer/module isolation check? → graph({action:'depth_traverse', node_id, max_depth:3})
-└─ Graph size/health?            → graph({action:'stats'})
-\`\`\`
-
-**Use this BEFORE** reaching for \`analyze_dependencies\` (slower, less precise) or manually
-tracing via \`symbol\` + \`trace\` chains. The graph is auto-populated during indexing.
-
-### What AI Kit Tools Return (AST-Enhanced)
-
-These tools use Tree-sitter WASM to analyze source code at the AST level, providing structured data that raw file reads cannot:
-
-| Tool | Rich Output |
-|------|-------------|
-| \`file_summary\` | Imports classified as **external vs internal** (\`isExternal\` flag). **Call edges** between functions (e.g., \`handleRequest() → validateInput() @ line 42\`). \`exported\` flag on interfaces and types. Import count breakdown. |
-| \`symbol\` | References include **scope** — which function/class/method contains each usage (e.g., \`referenced in processOrder() at auth-service.ts:55\`). |
-| \`trace\` | **Call-graph edges** discovered via AST syntax tree, not text matching. Supports forward (who does X call?) and backward (who calls X?) tracing. Scope context on each node. |
-| \`measure\` | **Cognitive complexity** — weights nesting depth (nested \`if\` inside \`for\` inside \`try\` scores higher). More useful than cyclomatic complexity for understanding code difficulty. |
-| \`dead_symbols\` | **AST export enumeration** — catches \`export default\`, barrel re-exports (\`export { x } from\`), \`export =\`, and \`export type\`. Regex fallback for non-AST-supported languages. |
-
-### Example: \`file_summary\` Output
-
-\`\`\`
-src/auth-service.ts
-Language: typescript | Lines: 180 | Estimated tokens: ~1400
-
-Imports (6): 3 external, 3 internal
-  - import { hash } from 'bcrypt'          [external]
-  - import { UserRepo } from './user-repo' [internal]
-
-Functions (4):
-  - authenticate @ line 22 [exported]
-  - validateToken @ line 55 [exported]
-  - hashPassword @ line 90
-  - generateJwt @ line 110
-
-Call edges (12 intra-file):
-  - authenticate() → hashPassword() @ line 35
-  - authenticate() → generateJwt() @ line 42
-  - validateToken() → UserRepo.findById() @ line 68
-
-Interfaces (2):
-  - AuthResult @ line 8 [exported]
-  - TokenPayload @ line 14
-\`\`\`
-
-Compare: \`read_file\` would cost ~1400 tokens for raw text. \`file_summary\` gives structured data in ~120 tokens — **12x reduction** with richer information.
-
-## Search Strategy
-
-1. **Start broad**: \`search({ query: "topic", search_mode: "hybrid" })\`
-2. **Narrow**: Add \`content_type\`, \`origin\`, or \`category\` filters
-3. **Exact match**: Use \`search_mode: "keyword"\` for identifiers
-4. **Federated**: Use \`find\` to combine vector + glob + regex
-
-## Workflow Chains
-
-### Codebase Onboarding
-\`\`\`
-analyze_structure({ path: "src/" })
-→ analyze_dependencies({ path: "src/" })
-→ analyze_entry_points({ path: "src/" })
-→ produce_knowledge({ path: "src/" })
-→ remember({ title: "Codebase onboarding complete", ... })
-\`\`\`
-
-### Planning a Task
-\`\`\`
-scope_map({ task: "implement user auth" })
-→ compact({ path: "src/auth.ts", query: "auth flow" })
-→ workset({ action: "save", name: "auth-task", files: [...] })
-\`\`\`
-
-### Bug Investigation
-\`\`\`
-parse_output({ output: <error> }) → symbol({ name: "failingFn" })
-→ trace({ symbol: "failingFn", direction: "backward" })
-→ blast_radius({ changed_files: ["suspect.ts"] })
-→ eval({ code: "hypothesis test" }) → check({ files: ["suspect.ts"] })
-\`\`\`
-
-### Safe Refactor with Lanes
-\`\`\`
-scope_map({ task: "rename UserService" })
-→ lane({ action: "create", name: "refactor", files: [...] })
-→ [make changes in lane files]
-→ lane({ action: "diff", name: "refactor" })
-→ check({}) → test_run({})
-→ lane({ action: "merge", name: "refactor" })
-\`\`\`
-
-### Lane — isolated read-only exploration
-
-\`lane({ action:'create', name })\` creates an isolated copy of the workspace. Use to try approach A vs B WITHOUT touching canonical source. Other actions: \`list\`, \`diff\`, \`delete\`. Compare with \`lane({ action:'diff', names:['a','b'] })\`. Do NOT use \`lane\` for actual refactors — use \`checkpoint\` instead (\`checkpoint\` = reversible on canonical source; \`lane\` = isolated copies for comparison).
-
-### After Making Changes
-\`\`\`
-blast_radius({ changed_files: ["src/auth.ts"] })
-→ check({}) → test_run({ grep: "auth" })
-→ reindex()
-→ remember({ title: "Implemented auth", content: "..." })
-\`\`\`
-
-### Pre-Commit Validation
-\`\`\`
-git_context({ diff: true })
-→ diff_parse({ diff: <staged diff> })
-→ blast_radius({ changed_files: [...] })
-→ check({}) → test_run({})
-\`\`\`
-
----
-
-## Persistent Memory (Long-Term Knowledge)
-
-AI Kit provides cross-session persistent memory via a curated knowledge store. Use it to remember decisions, patterns, conventions, and context that should survive beyond the current conversation.
-
-### Writing to Memory
-
-| Tool | Purpose | Example |
-|------|---------|---------|
-| \`remember\` | Store a new knowledge entry | \`remember({ title: "Auth uses JWT RS256", content: "All API auth uses RS256 JWT tokens issued by /auth/token. Refresh via httpOnly cookie.", category: "decisions" })\` |
-| \`update\` | Modify an existing entry | \`update({ id: "<entry-id>", content: "Updated: now also supports Ed25519" })\` |
-| \`produce_knowledge\` | Auto-generate analysis entries from code | \`produce_knowledge({ path: "src/" })\` |
-
-**Categories** — use these to organize entries:
-- \`conventions\` — coding standards, naming rules, file organization
-- \`decisions\` — architecture decisions, technology choices, trade-offs made
-- \`patterns\` — recurring code patterns, design patterns in use
-- \`context\` — project context, domain knowledge, business rules
-- \`session\` — session checkpoints for resuming work
-
-### Reading from Memory
-
-| Tool | Purpose | Example |
-|------|---------|---------|
-| \`list\` | Browse all stored entries | \`list()\` or \`list({ category: "decisions" })\` |
-| \`read\` | Read a specific entry by ID | \`read({ id: "<entry-id>" })\` |
-| \`search\` | Find entries by content/query | \`search({ query: "authentication", origin: "curated" })\` |
-| \`forget\` | Remove an outdated entry | \`forget({ id: "<entry-id>" })\` |
-
-### When to Remember
-
-| Situation | What to store | Category |
-|-----------|--------------|----------|
-| Architecture decision made | Decision + rationale + alternatives considered | \`decisions\` |
-| Pattern discovered in codebase | Pattern description + example locations | \`patterns\` |
-| Convention established | Rule + enforcement approach | \`conventions\` |
-| Session ending | Checkpoint: what was done, what's next, blockers | \`session\` |
-| Bug root cause found | Root cause + fix approach + prevention strategy | \`context\` |
-| External API behavior learned | Behavior quirks, rate limits, gotchas | \`context\` |
-
-### Session Checkpoint Pattern
-
-At the END of every meaningful work session:
-\`\`\`
-remember({
-  title: "Session checkpoint: <topic>",
-  content: "## Done\\n- <completed items>\\n\\n## Decisions\\n- <key decisions made>\\n\\n## Next\\n- <pending work>\\n\\n## Blockers\\n- <issues encountered>",
-  category: "session"
-})
-\`\`\`
-
-At the START of the next session:
-\`\`\`
-search({ query: "SESSION CHECKPOINT", origin: "curated" })    # Find last checkpoint
-list({ category: "session" })                                  # Browse all checkpoints
-\`\`\`
-
-### Memory Best Practices
-
-1. **Remember decisions, not code** — store *why*, not *what*. Code changes; rationale persists.
-2. **Search before remembering** — avoid duplicates: \`search({ query: "..." })\` first.
-3. **Use categories** — structured categories enable filtered \`list()\` queries.
-4. **Checkpoint regularly** — don't wait for session end. Checkpoint at milestones.
-5. **Clean up** — \`forget()\` outdated entries. Memory is only valuable when accurate.
-6. **Cross-reference** — mention related entry titles in content for discoverability.
-
-## CLI Quick Reference
-
-\`\`\`bash
-aikit init              # Scaffold AI Kit in current directory
-aikit init --force      # Overwrite all scaffold/skill files
-aikit init --guide      # JSON report of stale files for LLM-driven updates
-aikit serve             # Start MCP server (stdio or HTTP)
-aikit search <q>    # Hybrid search
-aikit find <q>      # Federated search
-aikit symbol <name> # Resolve symbol
-aikit scope-map <t> # Task reading plan
-aikit compact <q>   # Context compression (--path file or stdin)
-aikit check         # Typecheck + lint (--detail summary|errors|full)
-aikit test          # Run tests
-aikit rename <old> <new> <path>  # Rename symbol
-aikit lane create <name> --files f1,f2  # Create lane
-aikit lane diff <name>  # View lane changes
-aikit lane merge <name> # Merge lane back
-aikit status        # Index stats
-aikit reindex       # Rebuild index
-\`\`\`
-
-## Configuration
-
-\`kb.config.json\` in project root:
-\`\`\`json
-{
-  "sources": [{ "path": ".", "excludePatterns": ["node_modules/**", "**/node_modules/**", "dist/**", "coverage/**", ".aikit-data/**"] }],
-  "indexing": { "chunkSize": 1500, "chunkOverlap": 200, "minChunkSize": 100, "concurrency": 5 },
-  "embedding": { "model": "mixedbread-ai/mxbai-embed-large-v1", "dimensions": 1024 },
-  "store": { "backend": "lancedb", "path": ".aikit-data" },
-  "curated": { "path": "curated", "adapter": "filesystem" }
-}
-\`\`\`
-
-## Tool Profiles
-
-Tool profiles control which subset of the 82 tools are active. Profiles reduce token overhead by exposing only relevant tools for a given task.
-
-### Built-in Profiles
-
-| Profile | Description | Use When |
-|---------|-------------|----------|
-| \`full\` | All tools enabled (default) | General development, orchestration |
-| \`safe\` | Read-only tools — no file/state modifications | Code review, analysis, research |
-| \`research\` | Search, analysis, knowledge, web access | Investigation, documentation |
-| \`minimal\` | Essential tools only — search, check, test | Simple tasks, low-token budgets |
-| \`discovery\` | Full toolset + meta-tools for guided exploration | New users, onboarding, tool learning |
-
-### Activating a Profile
-
-Set \`toolProfile\` in \`kb.config.json\`:
-
-\`\`\`json
-{
-  "toolProfile": "research"
-}
-\`\`\`
-
-Base tools (\`status\`, \`config\`, \`guide\`, \`health\`) are **always available** regardless of profile.
-
-### Meta-Tool Discovery Pattern (Token Cost Reduction)
-
-Instead of loading all 82 tool descriptions at session start, use the \`discovery\` profile:
-
-1. \`list_tools()\` — get a compact list of tool names + categories (~50 tokens)
-2. \`search_tools({ query: "what I need" })\` — find relevant tools by keyword
-3. \`describe_tool({ tool_name: "specific_tool" })\` — get full metadata only for tools you'll use
-
-This pattern reduces initial tool-loading cost from ~3000 tokens to ~200 tokens.
-
-## IDE Integration
-
-### VS Code — HTTP mode (recommended for development)
-\`\`\`json
-// .vscode/mcp.json
-{
-  "servers": {
-    "kb": {
-      "type": "http",
-      "url": "http://localhost:3210/mcp"
-    }
-  }
-}
-\`\`\`
-Start server: \`npx aikit serve --http --port 3210\`
-
-### VS Code — stdio mode (no separate server)
-\`\`\`json
-{
-  "servers": {
-    "kb": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["@vpxa/aikit", "serve", "--stdio"]
-    }
-  }
-}
-\`\`\`
-
-### Claude Code (\`.mcp.json\`)
-\`\`\`json
-{
-  "mcpServers": {
-    "kb": {
-      "command": "npx",
-      "args": ["@vpxa/aikit", "serve"]
-    }
-  }
-}
-\`\`\`
-
-## Development (Self-Dogfooding)
-
-When developing @vpxa/aikit itself, use the tool on its own codebase:
-
-\`\`\`bash
-# Build → Reindex → Use loop
-pnpm build                          # Build all 10 packages
-node bin/aikit.mjs reindex          # Index own source into LanceDB
-node bin/aikit.mjs search "query"   # Search own code
-node bin/aikit.mjs symbol "FnName"  # Resolve symbols in own code
-node bin/aikit.mjs check            # Typecheck + lint
-pnpm test                           # Run 287+ tests
-
-# Start MCP server for agent use during development
-node bin/aikit.mjs serve --http --port 3210
-\`\`\`
-
-**Rules:**
-- Always \`pnpm build\` before using CLI/server (runs from \`dist/\`)
-- Always \`reindex\` after structural code changes
-- LanceDB is single-process — don't run CLI and HTTP server simultaneously
-- Curated entries in \`curated/\` survive reindex and are indexed separately
-
----
-
-## Flows
-
-Flows are structured multi-step workflows that guide agents through complex tasks. They are the **primary workflow system** — use them instead of ad-hoc planning when a matching flow exists.
-
-### Flow Tools
-
-| Tool | Purpose |
-|------|---------|
-| \`flow_status\` | Check if a flow is active + current step + phase (before/flow/after) + isEpilogue |
-| \`flow_list\` | List available flows |
-| \`flow_info\` | Get flow details including steps and skill paths |
-| \`flow_start\` | Start a named flow |
-| \`flow_step\` | Advance: \`next\`, \`skip\`, or \`redo\` current step |
-| \`flow_read_instruction\` | Read the current step's instruction file content directly |
-| \`flow_reset\` | Clear flow state to start over |
-| \`flow_add\` | Add a custom flow from a directory |
-| \`flow_update\` | Update an existing custom flow |
-| \`flow_remove\` | Remove a custom flow |
-
-### Flow Selection
-
-| Task Type | Flow | Why |
-|-----------|------|-----|
-| Bug fix, config change, small refactor | \`aikit:basic\` | Known scope, low risk |
-| New feature in existing module | \`aikit:basic\` | Clear boundaries |
-| New system/service/module | \`aikit:advanced\` | Needs spec + planning |
-| Cross-service changes | \`aikit:advanced\` | Multiple boundaries |
-| Architectural change | \`aikit:advanced\` | High impact |
-| Unclear scope or exploratory | No flow | Use agent's native workflow |
-
-### Flow Lifecycle
-
-1. **Start**: \`flow_list({})\` → choose flow → \`flow_start({ flow: "<name>", topic: "<task>" })\`
-2. **Each step**: \`flow_read_instruction({ step: "<name>" })\` → follow step instructions → complete work
-3. **Advance**: \`flow_step({ action: "next" })\` → repeat from step 2
-4. **Epilogue**: After last flow step, mandatory epilogue steps run (e.g., \`_docs-sync\` updates \`docs/\`)
-5. **Resume**: \`flow_status({})\` → if active, \`flow_read_instruction\` for current step → continue
-6. **Reset**: \`flow_reset({})\` if you need to start over
-` },
-  ],
-  "brainstorming": [
-    { file: "SKILL.md", content: `---
+`}],aikit:[{file:`SKILL.md`,content:'---\nname: aikit\ndescription: "Use the @vpxa/aikit AI Kit MCP server for codebase search, analysis, and persistent memory. Load this skill when using aikit_search, aikit_remember, aikit_analyze_*, or any aikit_* tool. Covers all 82 MCP tools: search (hybrid/semantic/keyword), code analysis (structure, dependencies, symbols, patterns, entry points, diagrams, blast radius), knowledge graph (auto-populated module/symbol/import graph with traversal), context management (worksets, stash, checkpoints, restore, lanes), code manipulation (rename, codemod, eval), knowledge management (remember/read/update/forget), web access (fetch, search, http), FORGE protocol (ground, classify, evidence map, stratum cards, digest), brainstorming (interactive ideation sessions), presentation (rich dashboards via present tool), onboarding (full codebase analysis in one call), and developer utilities (regex, encode, measure, changelog, schema-validate, snippet, env, time)."\nmetadata:\n  category: cross-cutting\n  domain: general\n  applicability: always\n  inputs: [codebase]\n  outputs: [search-results, analysis, knowledge]\n  relatedSkills: [present]\n---\n\n# @vpxa/aikit — AI Kit\n\nLocal-first AI developer toolkit — 82 MCP tools for search, analysis, context compression, FORGE quality gates, knowledge management, code manipulation, execution, web access, brainstorming, presentation, and developer utilities.\n\n## When to Use\n\n- You need long-term memory across coding sessions\n- You want to search a codebase semantically (by meaning, not just keywords)\n- You need to compress large contexts to focus on what matters\n- You want structured output from build tools (tsc, vitest, biome, git)\n- You need to plan which files to read for a task\n- You want to safely explore refactors in isolated lanes\n- You need to rename symbols, apply codemods, or run code transformations\n- You want to fetch and read web pages or search the web\n- You need to make HTTP requests, test APIs, or debug endpoints\n- You want to test regex patterns, encode/decode data, or validate JSON schemas\n- You need code complexity metrics or a git changelog\n- You want to save and reuse code snippets across sessions\n\n## Skills Reference\n\n| Context | Skill | Load when |\n|---------|-------|----------|\n| Repository access recovery | `repo-access` | When encountering git auth failures, accessing private/enterprise repos, or when `web_fetch`/`http` returns auth errors on repository URLs. |\n\n## Architecture\n\n10-package monorepo published as a single npm package:\n\n```\ncore → store → embeddings → chunker → indexer → analyzers → tools → server → cli → tui\n```\n\n- **MCP server**: 82 tools + 2 resources (via `@modelcontextprotocol/sdk`)\n- **CLI**: 45 commands (thin dispatcher + 10 command groups)\n- **Search**: Hybrid vector + keyword + RRF fusion\n- **Embeddings**: ONNX local (mxbai-embed-large-v1, 1024 dimensions)\n- **Vector store**: LanceDB (embedded, zero infrastructure)\n- **Chunking**: Tree-sitter AST (TS/JS/Python/Go/Rust/Java) + regex fallback\n- **TUI**: Ink/React dashboard for human monitoring (search, status, curated, activity log)\n\n## Session Protocol (MANDATORY)\n\n### Start (do ALL)\n```\nflow_status({})                                                # Check/resume active flow FIRST\n# If flow active → flow_read_instruction({ step }) → follow step instructions\nstatus({})                                                     # Check AI Kit health + onboard state\n# If onboard not run → onboard({ path: "." })                 # First-time codebase analysis\nflow_list({})                                                  # See available flows\n# Select flow based on task → flow_start({ flow: "<name>", topic: "<task>" })  # Start — creates .flows/{topic}/\nlist()                                                         # See stored knowledge\nsearch({ query: "SESSION CHECKPOINT", origin: "curated" })     # Resume prior work\n```\n\n### During Session\n```\nsearch → scope_map → symbol → trace  (orient)\ncheck → test_run                             (validate changes)\nremember                                         (capture insights)\n```\n\n### End of Session\n```\nsession_digest({ persist: true })                              # Auto-capture session activity\nremember({ title: "Session checkpoint: <topic>", content: "<what was done, decisions made, next steps>", category: "conventions" })\n```\n\n## Tool Catalog (82 tools)\n\n### Search & Discovery (8)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `search` | `aikit search` | Hybrid/semantic/keyword search with `search_mode` param |\n| `find` | `aikit find` | Federated search: vector + FTS + glob + regex in one call. Use `mode: \'examples\'` to find usage examples. |\n| `symbol` | `aikit symbol` | Resolve symbol definition, imports, and references |\n| `lookup` | `aikit lookup` | Full-file retrieval by path or record ID |\n| `scope_map` | `aikit scope-map` | Task-scoped reading plan with token estimates |\n| `trace` | `aikit trace` | Forward/backward flow tracing through call chains |\n| `dead_symbols` | `aikit dead-symbols` | Find exported symbols never imported — separates source (actionable) from docs (informational). Accepts `path` to scope the search. |\n| `file_summary` | `aikit summarize` | Structural overview of a file (exports, imports, functions) |\n\n### Code Analysis (7)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `analyze_structure` | `aikit analyze structure` | Project structure overview |\n| `analyze_dependencies` | `aikit analyze deps` | Dependency graph with confidence |\n| `analyze_symbols` | `aikit analyze symbols` | Symbol extraction and cross-references |\n| `analyze_patterns` | `aikit analyze patterns` | Design pattern detection |\n| `analyze_entry_points` | `aikit analyze entry-points` | Find entry points: handlers, CDK constructs, test suites, package exports (walks workspace packages) |\n| `analyze_diagram` | `aikit analyze diagram` | Generate Mermaid diagrams |\n| `blast_radius` | `aikit analyze blast-radius` | Change impact analysis |\n\n### Context Management (6)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `compact` | `aikit compact` | Compress text to relevant sections using embeddings (no LLM). Accepts `path` for server-side file read. |\n| `workset` | `aikit workset` | Named file set management (save/load/add/remove) |\n| `stash` | `aikit stash` | Named key-value store for session data |\n| `checkpoint` | `aikit checkpoint` | Save/restore session checkpoints |\n| `restore` | `aikit restore` | Restore a previously saved checkpoint |\n| `parse_output` | `aikit parse-output` | Parse tsc/vitest/biome/git output → structured JSON |\n\n### Code Manipulation (4)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `rename` | `aikit rename` | Smart whole-word symbol rename across files (dry-run supported) |\n| `codemod` | `aikit codemod` | Regex-based code transformations with rules (dry-run supported) |\n| `diff_parse` | `aikit diff` | Parse unified diff → structured changes |\n| `data_transform` | `aikit transform` | JQ-like JSON transformations |\n\n### Execution & Validation (5)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `eval` | `aikit eval` | Sandboxed JavaScript/TypeScript execution |\n| `check` | `aikit check` | Incremental typecheck + lint. `detail` param: summary (default, ~300 tokens), errors, full |\n| `test_run` | `aikit test` | Run tests with structured pass/fail results |\n| `batch` | `aikit batch` | Execute multiple operations in parallel |\n| `audit` | `aikit audit` | Unified project audit: structure, deps, patterns, health, dead symbols, check, entry points → synthesized report with score and recommendations. 6 round-trips → 1. |\n\n### Knowledge Management (6)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `remember` | `aikit remember` | Store a curated knowledge entry |\n| `update` | `aikit update` | Update an existing entry |\n| `forget` | `aikit forget` | Delete an entry (requires reason) |\n| `read` | `aikit read` | Read a curated entry by path |\n| `list` | `aikit list` | List curated entries |\n| `produce_knowledge` | — | Auto-generate knowledge from analysis |\n\n### Auto-Knowledge (automatic background extraction)\n\nAuto-knowledge runs automatically in the background after every tool completion. It extracts useful facts from tool outputs and stores them in curated memory — no manual action required.\n\n**What gets captured:**\n\n| Extractor | Triggers on | What it stores |\n|-----------|-------------|----------------|\n| Test results | `check`, `test_run` | Framework detection (vitest/jest/mocha), test file naming patterns |\n| Environment | `env`, `config`, `status` | Node.js version, OS, workspace path, store backend, embedding model |\n| Research | `web_search`, `web_fetch`, `search` | Web research findings, fetched page summaries |\n| Conventions | `check`, `analyze_patterns`, `analyze_structure`, `onboard` | Linter/formatter, TypeScript strict mode, package manager, monorepo detection |\n| Build commands | `check`, `test_run` | Verified check results, test summaries, test runner commands |\n| Codebase insights | `analyze_*`, `scope_map`, `blast_radius`, `onboard` | Structure analysis, dependency info, entry points, impact analysis |\n| Tool failures | All tools (global) | Classified actionable errors (filters out transient network/ENOENT errors) |\n\n**Quality controls:**\n- **Quality gate**: Facts scored 0-1; only facts >= 0.3 are stored\n- **Dedup**: Checks existing curated titles + in-memory hash dedup\n- **TTL**: Transient facts (errors, blast radius, search context) automatically expire after 1-2 hours\n- **Session limit**: Maximum 50 auto-knowledge facts per session\n\n**Searching auto-knowledge:**\nAuto-knowledge facts are stored as regular curated entries. Search them with:\n```\nsearch({ query: "error patterns", origin: "curated" })\nsearch({ query: "conventions", origin: "curated" })\nlist({ category: "conventions" })\nlist({ tags: ["errors"] })\n```\n\n### Verified Lanes (1 tool, 6 actions)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `lane` | `aikit lane` | Manage isolated file copies for parallel exploration |\n\nLane actions: `create` (copy files to lane), `list`, `status` (modified/added/deleted), `diff` (line-level diff), `merge` (apply back to originals), `discard`.\n\n### Git & Environment (4)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `git_context` | `aikit git` | Branch, status, recent commits |\n| `process` | `aikit proc` | Process supervisor (start/stop/logs) |\n| `watch` | `aikit watch` | Filesystem watcher |\n| `delegate` | `aikit delegate` | Delegate subtask to local Ollama model |\n\n### Web & Network (3)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `web_fetch` | — | Fetch web page → markdown/raw/links/outline for LLM consumption |\n| `web_search` | — | Search the web via DuckDuckGo (no API key needed) |\n| `http` | — | Make HTTP requests for API testing/debugging |\n\n### Developer Utilities (8)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `regex_test` | — | Test regex patterns with match/replace/split modes |\n| `encode` | — | Base64, URL, SHA-256, MD5, hex encode/decode, JWT decode |\n| `measure` | — | Code complexity metrics (cyclomatic, cognitive complexity, lines, functions) |\n| `changelog` | — | Generate changelog from git history (conventional commits) |\n| `schema_validate` | — | Validate JSON data against JSON Schema |\n| `snippet` | — | Save/get/search/delete persistent code snippets |\n| `env` | — | System and runtime environment info (sensitive values redacted) |\n| `time` | — | Date parsing, timezone conversion, duration math |\n\n### FORGE Quality Gates (5)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `forge_ground` | — | Full Ground phase: classify tier, scope map, unknowns, constraints |\n| `forge_classify` | — | Quick tier classification (Floor/Standard/Critical) |\n| `evidence_map` | — | CRUD + Gate evaluation for verified/assumed/unknown claims. Safety gate tags (`provenance`/`commitment`/`coverage`) enable mandatory pre-YIELD checks |\n| `stratum_card` | — | Generate T1/T2 compressed context cards from files (10-100x token reduction) |\n| `digest` | — | Compress N text sources into token-budgeted summary |\n\n### System (9)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `config` | `aikit config` | View or update project configuration (kb.config.json) |\n| `status` | `aikit status` | Index statistics |\n| `reindex` | `aikit reindex` | Rebuild index |\n| `health` | `aikit health` | Project health checks (package.json, tsconfig, lockfile, circular deps) |\n| `guide` | `aikit guide` | Tool discovery — given a goal, recommends tools and workflow order |\n| `onboard` | `aikit onboard` | Full codebase onboarding in one call (structure + deps + patterns + knowledge) |\n| `graph` | `aikit graph` | Query the auto-populated knowledge graph (modules, symbols, imports) |\n| `queue` | `aikit queue` | Task queue for sequential agent operations (create/push/next/done/fail) |\n| `replay` | `aikit replay` | View or clear the audit trail of tool invocations (action: list/clear) |\n\n### Flows (11)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `flow_list` | `aikit flow list` | List available flows and active run |\n| `flow_info` | `aikit flow info` | Get flow details including steps and skill paths |\n| `flow_start` | `aikit flow start` | Start a flow with topic — creates `.flows/{topic-slug}/` run directory |\n| `flow_step` | `aikit flow step` | Advance, skip, or redo the current step |\n| `flow_status` | `aikit flow status` | Check active run including slug, runDir, artifactsPath |\n| `flow_read_instruction` | `aikit flow read-instruction` | Read instruction with `{{artifacts_path}}` and `{{run_dir}}` resolved |\n| `flow_reset` | `aikit flow reset` | Abandon the active flow (preserves run directory) |\n| `flow_runs` | `aikit flow runs` | List all flow runs (current and past) |\n| `flow_add` | `aikit flow add` | Add a custom flow from a directory |\n| `flow_update` | `aikit flow update` | Update an existing custom flow |\n| `flow_remove` | `aikit flow remove` | Remove a custom flow |\n\n### Presentation (1)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `present` | — | Rich dashboards, charts, tables, timelines. Use `format: "browser"` then `openBrowserPage` to display. **In CLI mode (no VS Code chat), always use `format: "browser"`** — `html` UIResource is invisible in terminal. |\n\n### Brainstorming (1)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `brainstorm` | — | Interactive brainstorming and ideation sessions with structured output |\n\n### Meta-Tools — Tool Discovery (3)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `list_tools` | — | List all active AI Kit tools with names, titles, and categories. Accepts optional `category` filter. Use for initial tool discovery. |\n| `describe_tool` | — | Get detailed metadata for a specific tool (title, categories, annotations). Use after `list_tools` to understand a tool before calling it. |\n| `search_tools` | — | Search active tools by keyword across names, titles, and categories. Use when you know what you need but not the tool name. |\n\n### Session Management (1)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `session_digest` | — | Generate a compressed digest of session activity (replay log, stash, checkpoints). Options: `scope` (tools/stash/all), `since`, `last`, `focus`, `mode` (deterministic/sampling), `tokenBudget`, `persist`. Use at session end for handoff or mid-session to review what happened. |\n\n## Flow System\n\nFlows are multi-step guided workflows that structure complex tasks. Each step has a skill file with detailed instructions, required artifacts, and agent assignments.\n\n### Built-in Flows\n\n| Flow | Steps | Use When |\n|------|-------|----------|\n| `aikit:basic` | assess → implement → verify | Bug fixes, config changes, small features |\n| `aikit:advanced` | spec → plan → task → execute → verify | New modules, cross-service changes, architectural work |\n\n### Flow Lifecycle\n\n```text\nflow_list()                          # See available flows\nflow_info({ flow: "aikit:basic" })   # View steps, skills, agents\nflow_start({ flow: "aikit:basic", topic: "Fix login bug" })  # Start — creates .flows/fix-login-bug/\nflow_read_instruction()              # Read current step\'s instructions ({{artifacts_path}} resolved)\n# ... do the work described in the instruction ...\nflow_step({ action: "next" })        # Advance to next step\nflow_step({ action: "skip" })        # Skip current step\nflow_step({ action: "redo" })        # Redo current step\nflow_status()                        # Check progress (includes slug, runDir, artifactsPath, phase, isEpilogue)\nflow_reset()                         # Abandon active flow\nflow_runs()                          # List all runs (current + past)\n# Epilogue steps (mandatory, injected after every flow):\n# After last flow step → _docs-sync epilogue runs automatically\n# flow_status() shows phase: \'after\', isEpilogue: true during epilogue\n```\n\nCustom flow lifecycle management:\n\n```text\nflow_add({ source: ".github/flows/my-flow" })\nflow_update({ name: "my-flow" })\nflow_remove({ name: "my-flow" })\n```\n\n### Creating Custom Flows\n\n1. Create a directory under `.github/flows/<flow-name>/`\n2. Add `manifest.yaml`:\n\n```yaml\nname: my-flow\nversion: "1.0.0"\ndescription: "My custom flow"\nartifacts_dir: .spec\nsteps:\n  - id: design\n    name: Design\n    instruction: steps/design/README.md\n    description: "Create the design document"\n    produces: [design.md]\n    requires: []\n    agents: [Planner]\n  - id: implement\n    name: Implement\n    instruction: steps/implement/README.md\n    description: "Implement the design"\n    produces: [code]\n    requires: [design]\n    agents: [Implementer]\nagents:\n  - agents/planner.agent.md\ninstall: []\n```\n\n3. Add skill files under `.github/flows/<flow-name>/skills/<step-id>/SKILL.md`\n4. The flow appears in `flow_list()` automatically\n\n### How Flows Are Delivered\n\n- **Built-in flows** ship with the AI Kit MCP server in `scaffold/flows/`\n- `aikit init` copies them to `.github/flows/` in your workspace\n- At runtime, flow tools resolve paths to `.github/flows/` (workspace-local copies)\n- Custom flows placed in `.github/flows/` are discovered alongside built-in ones\n\n### Agent-Flow Integration\n\n- All code agents have a "Flows" section instructing them to check `flow_status()` first\n- If a flow is active, the agent follows the current step\'s instruction via `flow_read_instruction()`\n- After completing a step\'s work, advance with `flow_step({ action: "next" })`\n- The **Orchestrator** selects and starts flows; other agents follow them\n- The **Orchestrator** specifies `aikit` skill loading — all agents should load `aikit` skill to access flow tools\n\n## CRITICAL: Use AI Kit Tools Instead of Native IDE Tools\n\nAI Kit tools provide **10x richer output** than native IDE tools — with AST-analyzed call graphs, scope context, import classification, and cognitive complexity. **You MUST use AI Kit tools instead of native read/search tools.**\n\n### ⛔ PROHIBITED: Native File Reading\n\n**`read_file` / `read_file_raw` MUST NOT be used to understand code.** They waste tokens and miss structural information.\n\nThe **ONLY** acceptable use of `read_file`: getting exact lines immediately before an edit (to verify the `old_str` for replacement). Even then, use `file_summary` first to identify which lines to read.\n\n### Tool Replacement Table\n\n| ❌ NEVER do this | ✅ Use AI Kit Tool | Why |\n|---|---|---|\n| `read_file` (full file) | `file_summary` | Exports, imports, call edges — **10x fewer tokens** |\n| `read_file` (specific section) | `compact({ path, query })` | Server-side read + extract — **5-20x reduction** |\n| `grep_search` / `textSearch` | `search` | Semantic + keyword hybrid across all indexed content |\n| `grep_search` for a symbol | `symbol` | Definition + references **with scope context** |\n| Multiple `read_file` calls | `digest` | Compresses multiple sources into token-budgeted summary |\n| `listDirectory` + `read_file` | `scope_map` | Identifies relevant files for a task automatically |\n| Manual code tracing | `trace` | AST call-graph traversal with scope context |\n| Line counting / `wc` | `measure` | Lines, complexity, **cognitive complexity**, functions |\n| Grep for unused exports | `dead_symbols` | AST-powered export detection with regex fallback |\n| Repeated file reads | `stratum_card` | Reusable compressed context — **10-100x reduction** |\n| `fetch_webpage` | `web_fetch` | Readability extract + token budget — richer output |\n| Web research / browsing | `web_search` | Structured web results without browser — **unique to KB** |\n\n### Decision Tree — How to Read Code\n\n```\nNeed to understand a file?\n├─ Just structure?        → file_summary (exports, imports, call edges — ~50 tokens)\n├─ Specific section?      → compact({ path, query }) — 5-20x reduction\n├─ Multiple files?        → digest (multi-source compression — token-budgeted)\n├─ Repeated reference?    → stratum_card (T1/T2 card — 10-100x reduction)\n├─ Need exact lines to EDIT? → read_file (the ONLY acceptable use)\n└─ "I want to read the whole file" → ⛔ STOP. Use file_summary or compact instead.\n```\n\n### Decision Tree — Need Structural Relationships?\n\nWhen vector search and file reads don\'t answer the question (e.g. "who imports this?",\n"what does this depend on?", "how are these files connected?"), use `graph`:\n\n```\nNeed to understand relationships between code?\n├─ Who imports / calls this?     → graph({action:\'find_nodes\', name_pattern}) → graph({action:\'neighbors\', node_id, direction:\'incoming\'})\n├─ What does this depend on?     → graph({action:\'neighbors\', node_id, direction:\'outgoing\'})\n├─ Full context for a symbol?    → graph({action:\'symbol360\', name})\n├─ Related files within N hops?  → graph({action:\'traverse\', node_id, max_depth:2})\n├─ Layer/module isolation check? → graph({action:\'depth_traverse\', node_id, max_depth:3})\n└─ Graph size/health?            → graph({action:\'stats\'})\n```\n\n**Use this BEFORE** reaching for `analyze_dependencies` (slower, less precise) or manually\ntracing via `symbol` + `trace` chains. The graph is auto-populated during indexing.\n\n### What AI Kit Tools Return (AST-Enhanced)\n\nThese tools use Tree-sitter WASM to analyze source code at the AST level, providing structured data that raw file reads cannot:\n\n| Tool | Rich Output |\n|------|-------------|\n| `file_summary` | Imports classified as **external vs internal** (`isExternal` flag). **Call edges** between functions (e.g., `handleRequest() → validateInput() @ line 42`). `exported` flag on interfaces and types. Import count breakdown. |\n| `symbol` | References include **scope** — which function/class/method contains each usage (e.g., `referenced in processOrder() at auth-service.ts:55`). |\n| `trace` | **Call-graph edges** discovered via AST syntax tree, not text matching. Supports forward (who does X call?) and backward (who calls X?) tracing. Scope context on each node. |\n| `measure` | **Cognitive complexity** — weights nesting depth (nested `if` inside `for` inside `try` scores higher). More useful than cyclomatic complexity for understanding code difficulty. |\n| `dead_symbols` | **AST export enumeration** — catches `export default`, barrel re-exports (`export { x } from`), `export =`, and `export type`. Regex fallback for non-AST-supported languages. |\n\n### Example: `file_summary` Output\n\n```\nsrc/auth-service.ts\nLanguage: typescript | Lines: 180 | Estimated tokens: ~1400\n\nImports (6): 3 external, 3 internal\n  - import { hash } from \'bcrypt\'          [external]\n  - import { UserRepo } from \'./user-repo\' [internal]\n\nFunctions (4):\n  - authenticate @ line 22 [exported]\n  - validateToken @ line 55 [exported]\n  - hashPassword @ line 90\n  - generateJwt @ line 110\n\nCall edges (12 intra-file):\n  - authenticate() → hashPassword() @ line 35\n  - authenticate() → generateJwt() @ line 42\n  - validateToken() → UserRepo.findById() @ line 68\n\nInterfaces (2):\n  - AuthResult @ line 8 [exported]\n  - TokenPayload @ line 14\n```\n\nCompare: `read_file` would cost ~1400 tokens for raw text. `file_summary` gives structured data in ~120 tokens — **12x reduction** with richer information.\n\n## Search Strategy\n\n1. **Start broad**: `search({ query: "topic", search_mode: "hybrid" })`\n2. **Narrow**: Add `content_type`, `origin`, or `category` filters\n3. **Exact match**: Use `search_mode: "keyword"` for identifiers\n4. **Federated**: Use `find` to combine vector + glob + regex\n\n## Workflow Chains\n\n### Codebase Onboarding\n```\nanalyze_structure({ path: "src/" })\n→ analyze_dependencies({ path: "src/" })\n→ analyze_entry_points({ path: "src/" })\n→ produce_knowledge({ path: "src/" })\n→ remember({ title: "Codebase onboarding complete", ... })\n```\n\n### Planning a Task\n```\nscope_map({ task: "implement user auth" })\n→ compact({ path: "src/auth.ts", query: "auth flow" })\n→ workset({ action: "save", name: "auth-task", files: [...] })\n```\n\n### Bug Investigation\n```\nparse_output({ output: <error> }) → symbol({ name: "failingFn" })\n→ trace({ symbol: "failingFn", direction: "backward" })\n→ blast_radius({ changed_files: ["suspect.ts"] })\n→ eval({ code: "hypothesis test" }) → check({ files: ["suspect.ts"] })\n```\n\n### Safe Refactor with Lanes\n```\nscope_map({ task: "rename UserService" })\n→ lane({ action: "create", name: "refactor", files: [...] })\n→ [make changes in lane files]\n→ lane({ action: "diff", name: "refactor" })\n→ check({}) → test_run({})\n→ lane({ action: "merge", name: "refactor" })\n```\n\n### Lane — isolated read-only exploration\n\n`lane({ action:\'create\', name })` creates an isolated copy of the workspace. Use to try approach A vs B WITHOUT touching canonical source. Other actions: `list`, `diff`, `delete`. Compare with `lane({ action:\'diff\', names:[\'a\',\'b\'] })`. Do NOT use `lane` for actual refactors — use `checkpoint` instead (`checkpoint` = reversible on canonical source; `lane` = isolated copies for comparison).\n\n### After Making Changes\n```\nblast_radius({ changed_files: ["src/auth.ts"] })\n→ check({}) → test_run({ grep: "auth" })\n→ reindex()\n→ remember({ title: "Implemented auth", content: "..." })\n```\n\n### Pre-Commit Validation\n```\ngit_context({ diff: true })\n→ diff_parse({ diff: <staged diff> })\n→ blast_radius({ changed_files: [...] })\n→ check({}) → test_run({})\n```\n\n---\n\n## Persistent Memory (Long-Term Knowledge)\n\nAI Kit provides cross-session persistent memory via a curated knowledge store. Use it to remember decisions, patterns, conventions, and context that should survive beyond the current conversation.\n\n### Writing to Memory\n\n| Tool | Purpose | Example |\n|------|---------|---------|\n| `remember` | Store a new knowledge entry | `remember({ title: "Auth uses JWT RS256", content: "All API auth uses RS256 JWT tokens issued by /auth/token. Refresh via httpOnly cookie.", category: "decisions" })` |\n| `update` | Modify an existing entry | `update({ id: "<entry-id>", content: "Updated: now also supports Ed25519" })` |\n| `produce_knowledge` | Auto-generate analysis entries from code | `produce_knowledge({ path: "src/" })` |\n\n**Categories** — use these to organize entries:\n- `conventions` — coding standards, naming rules, file organization\n- `decisions` — architecture decisions, technology choices, trade-offs made\n- `patterns` — recurring code patterns, design patterns in use\n- `context` — project context, domain knowledge, business rules\n- `session` — session checkpoints for resuming work\n\n### Reading from Memory\n\n| Tool | Purpose | Example |\n|------|---------|---------|\n| `list` | Browse all stored entries | `list()` or `list({ category: "decisions" })` |\n| `read` | Read a specific entry by ID | `read({ id: "<entry-id>" })` |\n| `search` | Find entries by content/query | `search({ query: "authentication", origin: "curated" })` |\n| `forget` | Remove an outdated entry | `forget({ id: "<entry-id>" })` |\n\n### When to Remember\n\n| Situation | What to store | Category |\n|-----------|--------------|----------|\n| Architecture decision made | Decision + rationale + alternatives considered | `decisions` |\n| Pattern discovered in codebase | Pattern description + example locations | `patterns` |\n| Convention established | Rule + enforcement approach | `conventions` |\n| Session ending | Checkpoint: what was done, what\'s next, blockers | `session` |\n| Bug root cause found | Root cause + fix approach + prevention strategy | `context` |\n| External API behavior learned | Behavior quirks, rate limits, gotchas | `context` |\n\n### Session Checkpoint Pattern\n\nAt the END of every meaningful work session:\n```\nremember({\n  title: "Session checkpoint: <topic>",\n  content: "## Done\\n- <completed items>\\n\\n## Decisions\\n- <key decisions made>\\n\\n## Next\\n- <pending work>\\n\\n## Blockers\\n- <issues encountered>",\n  category: "session"\n})\n```\n\nAt the START of the next session:\n```\nsearch({ query: "SESSION CHECKPOINT", origin: "curated" })    # Find last checkpoint\nlist({ category: "session" })                                  # Browse all checkpoints\n```\n\n### Memory Best Practices\n\n1. **Remember decisions, not code** — store *why*, not *what*. Code changes; rationale persists.\n2. **Search before remembering** — avoid duplicates: `search({ query: "..." })` first.\n3. **Use categories** — structured categories enable filtered `list()` queries.\n4. **Checkpoint regularly** — don\'t wait for session end. Checkpoint at milestones.\n5. **Clean up** — `forget()` outdated entries. Memory is only valuable when accurate.\n6. **Cross-reference** — mention related entry titles in content for discoverability.\n\n## CLI Quick Reference\n\n```bash\naikit init              # Scaffold AI Kit in current directory\naikit init --force      # Overwrite all scaffold/skill files\naikit init --guide      # JSON report of stale files for LLM-driven updates\naikit serve             # Start MCP server (stdio or HTTP)\naikit search <q>    # Hybrid search\naikit find <q>      # Federated search\naikit symbol <name> # Resolve symbol\naikit scope-map <t> # Task reading plan\naikit compact <q>   # Context compression (--path file or stdin)\naikit check         # Typecheck + lint (--detail summary|errors|full)\naikit test          # Run tests\naikit rename <old> <new> <path>  # Rename symbol\naikit lane create <name> --files f1,f2  # Create lane\naikit lane diff <name>  # View lane changes\naikit lane merge <name> # Merge lane back\naikit status        # Index stats\naikit reindex       # Rebuild index\n```\n\n## Configuration\n\n`kb.config.json` in project root:\n```json\n{\n  "sources": [{ "path": ".", "excludePatterns": ["node_modules/**", "**/node_modules/**", "dist/**", "coverage/**", ".aikit-data/**"] }],\n  "indexing": { "chunkSize": 1500, "chunkOverlap": 200, "minChunkSize": 100, "concurrency": 5 },\n  "embedding": { "model": "mixedbread-ai/mxbai-embed-large-v1", "dimensions": 1024 },\n  "store": { "backend": "lancedb", "path": ".aikit-data" },\n  "curated": { "path": "curated", "adapter": "filesystem" }\n}\n```\n\n## Tool Profiles\n\nTool profiles control which subset of the 82 tools are active. Profiles reduce token overhead by exposing only relevant tools for a given task.\n\n### Built-in Profiles\n\n| Profile | Description | Use When |\n|---------|-------------|----------|\n| `full` | All tools enabled (default) | General development, orchestration |\n| `safe` | Read-only tools — no file/state modifications | Code review, analysis, research |\n| `research` | Search, analysis, knowledge, web access | Investigation, documentation |\n| `minimal` | Essential tools only — search, check, test | Simple tasks, low-token budgets |\n| `discovery` | Full toolset + meta-tools for guided exploration | New users, onboarding, tool learning |\n\n### Activating a Profile\n\nSet `toolProfile` in `kb.config.json`:\n\n```json\n{\n  "toolProfile": "research"\n}\n```\n\nBase tools (`status`, `config`, `guide`, `health`) are **always available** regardless of profile.\n\n### Meta-Tool Discovery Pattern (Token Cost Reduction)\n\nInstead of loading all 82 tool descriptions at session start, use the `discovery` profile:\n\n1. `list_tools()` — get a compact list of tool names + categories (~50 tokens)\n2. `search_tools({ query: "what I need" })` — find relevant tools by keyword\n3. `describe_tool({ tool_name: "specific_tool" })` — get full metadata only for tools you\'ll use\n\nThis pattern reduces initial tool-loading cost from ~3000 tokens to ~200 tokens.\n\n## IDE Integration\n\n### VS Code — HTTP mode (recommended for development)\n```json\n// .vscode/mcp.json\n{\n  "servers": {\n    "kb": {\n      "type": "http",\n      "url": "http://localhost:3210/mcp"\n    }\n  }\n}\n```\nStart server: `npx aikit serve --http --port 3210`\n\n### VS Code — stdio mode (no separate server)\n```json\n{\n  "servers": {\n    "kb": {\n      "type": "stdio",\n      "command": "npx",\n      "args": ["@vpxa/aikit", "serve", "--stdio"]\n    }\n  }\n}\n```\n\n### Claude Code (`.mcp.json`)\n```json\n{\n  "mcpServers": {\n    "kb": {\n      "command": "npx",\n      "args": ["@vpxa/aikit", "serve"]\n    }\n  }\n}\n```\n\n## Development (Self-Dogfooding)\n\nWhen developing @vpxa/aikit itself, use the tool on its own codebase:\n\n```bash\n# Build → Reindex → Use loop\npnpm build                          # Build all 10 packages\nnode bin/aikit.mjs reindex          # Index own source into LanceDB\nnode bin/aikit.mjs search "query"   # Search own code\nnode bin/aikit.mjs symbol "FnName"  # Resolve symbols in own code\nnode bin/aikit.mjs check            # Typecheck + lint\npnpm test                           # Run 287+ tests\n\n# Start MCP server for agent use during development\nnode bin/aikit.mjs serve --http --port 3210\n```\n\n**Rules:**\n- Always `pnpm build` before using CLI/server (runs from `dist/`)\n- Always `reindex` after structural code changes\n- LanceDB is single-process — don\'t run CLI and HTTP server simultaneously\n- Curated entries in `curated/` survive reindex and are indexed separately\n\n---\n\n## Flows\n\nFlows are structured multi-step workflows that guide agents through complex tasks. They are the **primary workflow system** — use them instead of ad-hoc planning when a matching flow exists.\n\n### Flow Tools\n\n| Tool | Purpose |\n|------|---------|\n| `flow_status` | Check if a flow is active + current step + phase (before/flow/after) + isEpilogue |\n| `flow_list` | List available flows |\n| `flow_info` | Get flow details including steps and skill paths |\n| `flow_start` | Start a named flow |\n| `flow_step` | Advance: `next`, `skip`, or `redo` current step |\n| `flow_read_instruction` | Read the current step\'s instruction file content directly |\n| `flow_reset` | Clear flow state to start over |\n| `flow_add` | Add a custom flow from a directory |\n| `flow_update` | Update an existing custom flow |\n| `flow_remove` | Remove a custom flow |\n\n### Flow Selection\n\n| Task Type | Flow | Why |\n|-----------|------|-----|\n| Bug fix, config change, small refactor | `aikit:basic` | Known scope, low risk |\n| New feature in existing module | `aikit:basic` | Clear boundaries |\n| New system/service/module | `aikit:advanced` | Needs spec + planning |\n| Cross-service changes | `aikit:advanced` | Multiple boundaries |\n| Architectural change | `aikit:advanced` | High impact |\n| Unclear scope or exploratory | No flow | Use agent\'s native workflow |\n\n### Flow Lifecycle\n\n1. **Start**: `flow_list({})` → choose flow → `flow_start({ flow: "<name>", topic: "<task>" })`\n2. **Each step**: `flow_read_instruction({ step: "<name>" })` → follow step instructions → complete work\n3. **Advance**: `flow_step({ action: "next" })` → repeat from step 2\n4. **Epilogue**: After last flow step, mandatory epilogue steps run (e.g., `_docs-sync` updates `docs/`)\n5. **Resume**: `flow_status({})` → if active, `flow_read_instruction` for current step → continue\n6. **Reset**: `flow_reset({})` if you need to start over\n'}],brainstorming:[{file:`SKILL.md`,content:`---
 name: brainstorming
 description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
 metadata:
@@ -2762,8 +1969,7 @@ Use the \`present\` MCP tool for showing mockups, diagrams, and visual options d
 
 - **Use \`present({ format: "html" })\`** for visual content — mockups, wireframes, layout comparisons, architecture diagrams, side-by-side visual designs
 - **Use regular chat** for text content — requirements questions, conceptual choices, tradeoff lists, A/B/C/D text options, scope decisions
-` },
-    { file: "spec-document-reviewer-prompt.md", content: `# Spec Document Reviewer Prompt Template
+`},{file:`spec-document-reviewer-prompt.md`,content:`# Spec Document Reviewer Prompt Template
 
 Use this template when dispatching a spec document reviewer subagent.
 
@@ -2812,10 +2018,7 @@ Task tool (general-purpose):
 \`\`\`
 
 **Reviewer returns:** Status, Issues (if any), Recommendations
-` },
-  ],
-  "c4-architecture": [
-    { file: "references/advanced-patterns.md", content: `# Advanced C4 Architecture Patterns
+`}],"c4-architecture":[{file:`references/advanced-patterns.md`,content:`# Advanced C4 Architecture Patterns
 
 This guide covers advanced patterns for documenting complex architectures including microservices, event-driven systems, deployments, and API documentation.
 
@@ -3367,8 +2570,7 @@ C4Context
 5. **Link to ADRs**: Document why decisions were made
 6. **Use system landscape for enterprise views**: Show all systems and their relationships
 7. **Keep diagrams focused**: One concern per diagram, split when complex
-` },
-    { file: "references/c4-syntax.md", content: `# C4 Mermaid Diagram Syntax Reference
+`},{file:`references/c4-syntax.md`,content:`# C4 Mermaid Diagram Syntax Reference
 
 Complete syntax reference for Mermaid C4 diagrams. Compatible with PlantUML C4 syntax.
 
@@ -3878,8 +3080,7 @@ For features Mermaid doesn't support, consider:
 - **Structurizr DSL** - Full C4 support with model-based generation
 - **C4-PlantUML** - More mature C4 implementation
 - **IcePanel** - Visual C4 diagram editor
-` },
-    { file: "references/common-mistakes.md", content: `# Common C4 Model Mistakes to Avoid
+`},{file:`references/common-mistakes.md`,content:`# Common C4 Model Mistakes to Avoid
 
 This guide documents frequent anti-patterns and errors when creating C4 architecture diagrams, with examples of what to do instead.
 
@@ -4316,346 +3517,7 @@ Before finalizing any C4 diagram, verify:
 - [ ] Message topics shown individually (not as single broker)
 - [ ] No infrastructure details in container diagrams
 - [ ] Consistent with other diagrams in the set
-` },
-    { file: "references/html-design-system.md", content: `# HTML/SVG Architecture Diagram Design System
-
-This file is the centralized design system for HTML and SVG architecture diagrams.
-
-It is the single source of truth for visual tokens, component categories, layout rules, and \`present\` tool composition guidance used by the \`c4-architecture\` skill and the \`present\` skill. Update component types, colors, layout rules, and icon slots here only.
-
-## Purpose
-
-- Define a reusable visual language for C4-style architecture diagrams rendered as HTML and inline SVG.
-- Keep category styling extensible through a registry instead of hardcoded component types.
-- Standardize diagram composition for both skill-authored documentation and \`present\` output.
-
-## Core Design Tokens
-
-### Typography
-
-- Font family: \`"JetBrains Mono", monospace\`
-- Font source: Google Fonts (\`https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;700;800&display=swap\`)
-- Component names: \`12px\`
-- Sublabels: \`9px\`
-- Annotations: \`8px\`
-- Tiny labels: \`7px\`
-- Legend: \`10px\`
-- Icon area labels: \`11px\`
-
-### Background
-
-- Page background: \`#020617\` (\`slate-950\`)
-- Background pattern: inline SVG grid pattern over the page background
-- Recommended grid line colors:
-  - Major grid: \`rgba(148, 163, 184, 0.08)\`
-  - Minor grid: \`rgba(148, 163, 184, 0.04)\`
-
-### Component Box Defaults
-
-- Shape: rounded rectangle
-- Border radius: \`rx="6"\`
-- Stroke width: \`1.5px\`
-- Fill: category-specific semi-transparent RGBA fill
-- Stroke: category-specific hex stroke
-- Label stack:
-  - Line 1: C4 label such as \`<<Container>>\`
-  - Line 2: component name
-  - Line 3: subtype or technology summary
-
-## Category Registry
-
-The registry is hierarchical: categories define shared tokens and C4 intent, while sub-types inherit the category styling and reserve an icon slot for future SVG glyphs.
-
-| Category | Stroke Color | Fill Color | C4 Mapping | Sub-types |
-|---|---|---|---|---|
-| Frontend | \`#22d3ee\` | \`rgba(8, 51, 68, 0.4)\` | Container (SPA, web) | SPA, Mobile App, Static Site, Micro-frontend, PWA, Desktop App |
-| Backend | \`#34d399\` | \`rgba(6, 78, 59, 0.4)\` | Container (service) | API Service, Worker/Job, BFF, Microservice, Serverless Function, gRPC Service |
-| Data | \`#a78bfa\` | \`rgba(76, 29, 149, 0.4)\` | ContainerDb | Relational DB, Document DB, Key-Value Store, Cache, Search Engine, Data Warehouse, Graph DB, Time-Series DB |
-| Infrastructure | \`#fbbf24\` | \`rgba(120, 53, 15, 0.3)\` | Deployment_Node | CDN, Load Balancer, DNS, Object Storage, Container Registry, Reverse Proxy, Service Mesh |
-| Messaging | \`#fb923c\` | \`rgba(251, 146, 60, 0.3)\` | ContainerQueue | Message Queue, Event Bus, Stream, Pub/Sub, Webhook |
-| Security | \`#fb7185\` | \`rgba(136, 19, 55, 0.4)\` | System_Ext / boundary | Auth Provider, API Gateway, WAF, Secret Manager, Certificate Manager, Identity Provider |
-| External | \`#94a3b8\` | \`rgba(30, 41, 59, 0.5)\` | System_Ext | Third-party API, SaaS, Legacy System, Partner Service, Payment Provider |
-| Monitoring | \`#38bdf8\` | \`rgba(12, 74, 110, 0.4)\` | Container | Logging, Metrics, Tracing, Alerting, APM |
-
-## Sub-type Registry
-
-Each sub-type inherits its category tokens and keeps a placeholder slot for an inline SVG icon.
-
-| Category | Sub-type | C4 Label | Icon Slot |
-|---|---|---|---|
-| Frontend | SPA | \`<<Container>>\` | \`icon-spa\` |
-| Frontend | Mobile App | \`<<Container>>\` | \`icon-mobile-app\` |
-| Frontend | Static Site | \`<<Container>>\` | \`icon-static-site\` |
-| Frontend | Micro-frontend | \`<<Container>>\` | \`icon-micro-frontend\` |
-| Frontend | PWA | \`<<Container>>\` | \`icon-pwa\` |
-| Frontend | Desktop App | \`<<Container>>\` | \`icon-desktop-app\` |
-| Backend | API Service | \`<<Container>>\` | \`icon-api-service\` |
-| Backend | Worker/Job | \`<<Container>>\` | \`icon-worker-job\` |
-| Backend | BFF | \`<<Container>>\` | \`icon-bff\` |
-| Backend | Microservice | \`<<Container>>\` | \`icon-microservice\` |
-| Backend | Serverless Function | \`<<Container>>\` | \`icon-serverless-function\` |
-| Backend | gRPC Service | \`<<Container>>\` | \`icon-grpc-service\` |
-| Data | Relational DB | \`<<ContainerDb>>\` | \`icon-relational-db\` |
-| Data | Document DB | \`<<ContainerDb>>\` | \`icon-document-db\` |
-| Data | Key-Value Store | \`<<ContainerDb>>\` | \`icon-key-value-store\` |
-| Data | Cache | \`<<ContainerDb>>\` | \`icon-cache\` |
-| Data | Search Engine | \`<<ContainerDb>>\` | \`icon-search-engine\` |
-| Data | Data Warehouse | \`<<ContainerDb>>\` | \`icon-data-warehouse\` |
-| Data | Graph DB | \`<<ContainerDb>>\` | \`icon-graph-db\` |
-| Data | Time-Series DB | \`<<ContainerDb>>\` | \`icon-time-series-db\` |
-| Infrastructure | CDN | \`<<Deployment_Node>>\` | \`icon-cdn\` |
-| Infrastructure | Load Balancer | \`<<Deployment_Node>>\` | \`icon-load-balancer\` |
-| Infrastructure | DNS | \`<<Deployment_Node>>\` | \`icon-dns\` |
-| Infrastructure | Object Storage | \`<<Deployment_Node>>\` | \`icon-object-storage\` |
-| Infrastructure | Container Registry | \`<<Deployment_Node>>\` | \`icon-container-registry\` |
-| Infrastructure | Reverse Proxy | \`<<Deployment_Node>>\` | \`icon-reverse-proxy\` |
-| Infrastructure | Service Mesh | \`<<Deployment_Node>>\` | \`icon-service-mesh\` |
-| Messaging | Message Queue | \`<<ContainerQueue>>\` | \`icon-message-queue\` |
-| Messaging | Event Bus | \`<<ContainerQueue>>\` | \`icon-event-bus\` |
-| Messaging | Stream | \`<<ContainerQueue>>\` | \`icon-stream\` |
-| Messaging | Pub/Sub | \`<<ContainerQueue>>\` | \`icon-pub-sub\` |
-| Messaging | Webhook | \`<<ContainerQueue>>\` | \`icon-webhook\` |
-| Security | Auth Provider | \`<<System_Ext>>\` | \`icon-auth-provider\` |
-| Security | API Gateway | \`<<System_Ext>>\` | \`icon-api-gateway\` |
-| Security | WAF | \`<<System_Ext>>\` | \`icon-waf\` |
-| Security | Secret Manager | \`<<System_Ext>>\` | \`icon-secret-manager\` |
-| Security | Certificate Manager | \`<<System_Ext>>\` | \`icon-certificate-manager\` |
-| Security | Identity Provider | \`<<System_Ext>>\` | \`icon-identity-provider\` |
-| External | Third-party API | \`<<System_Ext>>\` | \`icon-third-party-api\` |
-| External | SaaS | \`<<System_Ext>>\` | \`icon-saas\` |
-| External | Legacy System | \`<<System_Ext>>\` | \`icon-legacy-system\` |
-| External | Partner Service | \`<<System_Ext>>\` | \`icon-partner-service\` |
-| External | Payment Provider | \`<<System_Ext>>\` | \`icon-payment-provider\` |
-| Monitoring | Logging | \`<<Container>>\` | \`icon-logging\` |
-| Monitoring | Metrics | \`<<Container>>\` | \`icon-metrics\` |
-| Monitoring | Tracing | \`<<Container>>\` | \`icon-tracing\` |
-| Monitoring | Alerting | \`<<Container>>\` | \`icon-alerting\` |
-| Monitoring | APM | \`<<Container>>\` | \`icon-apm\` |
-
-## Icon Registry
-
-Icons are inline SVG \`<symbol>\` elements with a 16x16 viewBox, rendered via \`<use>\` at \`(x+W-22, y+4)\` inside the component box. They use \`currentColor\` to inherit the category stroke color.
-
-### Category-Level Icons (active)
-
-Each category has a shared icon defined in \`html-template.html\` \`<defs>\`. All sub-types within a category use their category icon by default. Sub-type-specific icons can override these in the future.
-
-| Category | Symbol ID | Shape | Status |
-|---|---|---|---|
-| Frontend | \`icon-frontend\` | Monitor with stand | **active** |
-| Backend | \`icon-backend\` | Server rack (3 units) | **active** |
-| Data | \`icon-data\` | Database cylinder | **active** |
-| Infrastructure | \`icon-infrastructure\` | Cloud | **active** |
-| Messaging | \`icon-messaging\` | Envelope | **active** |
-| Security | \`icon-security\` | Shield with checkmark | **active** |
-| External | \`icon-external\` | Globe with meridians | **active** |
-| Monitoring | \`icon-monitoring\` | Line chart with axes | **active** |
-
-Usage pattern:
-\`\`\`svg
-<use href="#icon-frontend" class="icon-use" x="448" y="154" width="16" height="16"/>
-\`\`\`
-
-### Sub-type Icons (planned)
-
-When a sub-type icon is added, it overrides the category icon for that specific component. Until implemented, all sub-types use their category icon.
-
-| Sub-type | Icon | Status |
-|---|---|---|
-| SPA | \`icon-spa\` | planned |
-| Mobile App | \`icon-mobile-app\` | planned |
-| Static Site | \`icon-static-site\` | planned |
-| Micro-frontend | \`icon-micro-frontend\` | planned |
-| PWA | \`icon-pwa\` | planned |
-| Desktop App | \`icon-desktop-app\` | planned |
-| API Service | \`icon-api-service\` | planned |
-| Worker/Job | \`icon-worker-job\` | planned |
-| BFF | \`icon-bff\` | planned |
-| Microservice | \`icon-microservice\` | planned |
-| Serverless Function | \`icon-serverless-function\` | planned |
-| gRPC Service | \`icon-grpc-service\` | planned |
-| Relational DB | \`icon-relational-db\` | planned |
-| Document DB | \`icon-document-db\` | planned |
-| Key-Value Store | \`icon-key-value-store\` | planned |
-| Cache | \`icon-cache\` | planned |
-| Search Engine | \`icon-search-engine\` | planned |
-| Data Warehouse | \`icon-data-warehouse\` | planned |
-| Graph DB | \`icon-graph-db\` | planned |
-| Time-Series DB | \`icon-time-series-db\` | planned |
-| CDN | \`icon-cdn\` | planned |
-| Load Balancer | \`icon-load-balancer\` | planned |
-| DNS | \`icon-dns\` | planned |
-| Object Storage | \`icon-object-storage\` | planned |
-| Container Registry | \`icon-container-registry\` | planned |
-| Reverse Proxy | \`icon-reverse-proxy\` | planned |
-| Service Mesh | \`icon-service-mesh\` | planned |
-| Message Queue | \`icon-message-queue\` | planned |
-| Event Bus | \`icon-event-bus\` | planned |
-| Stream | \`icon-stream\` | planned |
-| Pub/Sub | \`icon-pub-sub\` | planned |
-| Webhook | \`icon-webhook\` | planned |
-| Auth Provider | \`icon-auth-provider\` | planned |
-| API Gateway | \`icon-api-gateway\` | planned |
-| WAF | \`icon-waf\` | planned |
-| Secret Manager | \`icon-secret-manager\` | planned |
-| Certificate Manager | \`icon-certificate-manager\` | planned |
-| Identity Provider | \`icon-identity-provider\` | planned |
-| Third-party API | \`icon-third-party-api\` | planned |
-| SaaS | \`icon-saas\` | planned |
-| Legacy System | \`icon-legacy-system\` | planned |
-| Partner Service | \`icon-partner-service\` | planned |
-| Payment Provider | \`icon-payment-provider\` | planned |
-| Logging | \`icon-logging\` | planned |
-| Metrics | \`icon-metrics\` | planned |
-| Tracing | \`icon-tracing\` | planned |
-| Alerting | \`icon-alerting\` | planned |
-| APM | \`icon-apm\` | planned |
-
-## Visual Elements
-
-### Component Box Pattern
-
-Use a rounded component box with semi-transparent fill and category stroke.
-
-\`\`\`svg
-<g class="node backend">
-  <rect x="280" y="210" width="190" height="60" rx="6" />
-  <text class="c4-tag" x="294" y="226">&lt;&lt;Container&gt;&gt;</text>
-  <text class="node-title" x="294" y="243">API Service</text>
-  <text class="node-subtitle" x="294" y="257">Backend / HTTPS JSON</text>
-</g>
-\`\`\`
-
-### Arrow Masking Technique
-
-Use an opaque background rectangle below the box content to visually hide arrows beneath components without breaking the component fill style.
-
-\`\`\`svg
-<g class="node-mask-layer">
-  <rect x="280" y="210" width="190" height="60" rx="6" fill="#020617" />
-  <rect x="280" y="210" width="190" height="60" rx="6"
-        fill="rgba(6, 78, 59, 0.4)" stroke="#34d399" stroke-width="1.5" />
-</g>
-\`\`\`
-
-### Security Group Boundary
-
-- Purpose: show auth, gateway, WAF, or identity zones
-- Stroke color: rose (\`#fb7185\`)
-- Pattern: \`stroke-dasharray="4,4"\`
-- Suggested label: \`Security Boundary\`
-
-\`\`\`svg
-<rect x="700" y="140" width="220" height="180" rx="12"
-      fill="transparent" stroke="#fb7185" stroke-width="1.5"
-      stroke-dasharray="4,4" />
-\`\`\`
-
-### Region Boundary
-
-- Purpose: group a deployment region, platform segment, or domain slice
-- Stroke color: amber (\`#fbbf24\`)
-- Pattern: \`stroke-dasharray="8,4"\`
-- Radius: \`rx="12"\`
-
-\`\`\`svg
-<rect x="70" y="120" width="600" height="430" rx="12"
-      fill="transparent" stroke="#fbbf24" stroke-width="1.5"
-      stroke-dasharray="8,4" />
-\`\`\`
-
-### Arrow Marker SVG Definition
-
-\`\`\`svg
-<defs>
-  <marker id="arrowhead" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto">
-    <path d="M0,0 L8,4 L0,8 Z" fill="#cbd5e1" />
-  </marker>
-</defs>
-\`\`\`
-
-### Arrow Z-order Rule
-
-Draw arrows early in the SVG so component boxes and masking layers paint over them. This keeps connectors readable in dense diagrams and avoids arrow overlap across component interiors.
-
-## Spacing Rules
-
-- Standard component height: \`60px\`
-- Minimum vertical gap between stacked components: \`40px\`
-- Inline connectors should route through gaps rather than through component interiors
-- Keep labels inside the top \`28px\` of the box and the subtype line inside the lower third
-- Place legends outside boundaries to prevent classification noise inside the diagram area
-
-## Layout Structure
-
-The canonical page composition is:
-
-1. Header: title, pulse dot, subtitle
-2. Main SVG diagram: embedded inside a rounded border card
-3. Summary cards: grid of 3 cards beneath the diagram
-4. Footer metadata: generator, scope, rendering notes, last-updated stamp
-
-## Present Tool Integration
-
-Compose architecture diagrams with the \`present\` tool by embedding the full HTML/SVG diagram in a markdown block and pairing it with metrics or cards blocks as needed.
-
-### \`format: "html"\`
-
-Use a \`markdown\` block with embedded \`<div>\`, inline SVG, and a \`<style>\` tag containing the full CSS. The \`present\` html format renders raw HTML in markdown blocks.
-
-### \`format: "browser"\`
-
-Use the same composition: a \`markdown\` block containing the full HTML structure. Summary content can also be added with \`cards\` and \`metrics\` blocks alongside the SVG diagram block.
-
-### Example \`present\` Call Structure
-
-\`\`\`js
-present({
-  format: "html", // or "browser"
-  title: "System Architecture",
-  content: [
-    {
-      type: "metrics",
-      title: "Overview",
-      value: [
-        { label: "Services", value: "6" },
-        { label: "Data Stores", value: "2" },
-        { label: "External Systems", value: "3" }
-      ]
-    },
-    {
-      type: "markdown",
-      title: "Architecture Diagram",
-      value: "<div class='arch-diagram'>...(inline SVG)...</div><style>...(design system CSS)...</style>"
-    },
-    {
-      type: "cards",
-      title: "Summary",
-      value: [
-        { title: "Frontend", body: "React SPA..." },
-        { title: "Backend", body: "API + async workers..." },
-        { title: "Security", body: "Gateway + IdP..." }
-      ]
-    }
-  ]
-})
-\`\`\`
-
-This design system is the single source of truth. The \`c4-architecture\` skill and \`present\` skill both reference this file. Update component types, colors, or layout rules here only.
-
-## Adding New Categories
-
-1. Add a new row to the Category Registry with the category name, colors, C4 mapping, and initial subtype set.
-2. Add the new sub-types to the Sub-type Registry with a C4 label and icon slot name.
-3. Add icon placeholders to the Icon Registry.
-4. Update [html-template.html](html-template.html) legend content so the new category appears in the rendered template.
-5. Update summary card accent colors in [html-template.html](html-template.html) if the new category needs a dedicated card treatment.
-
-## Template Pairing
-
-See [html-template.html](html-template.html) for the complete self-contained reference implementation of this design system.
-` },
-    { file: "SKILL.md", content: `---
+`},{file:`references/html-design-system.md`,content:'# HTML/SVG Architecture Diagram Design System\n\nThis file is the centralized design system for HTML and SVG architecture diagrams.\n\nIt is the single source of truth for visual tokens, component categories, layout rules, and `present` tool composition guidance used by the `c4-architecture` skill and the `present` skill. Update component types, colors, layout rules, and icon slots here only.\n\n## Purpose\n\n- Define a reusable visual language for C4-style architecture diagrams rendered as HTML and inline SVG.\n- Keep category styling extensible through a registry instead of hardcoded component types.\n- Standardize diagram composition for both skill-authored documentation and `present` output.\n\n## Core Design Tokens\n\n### Typography\n\n- Font family: `"JetBrains Mono", monospace`\n- Font source: Google Fonts (`https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;700;800&display=swap`)\n- Component names: `12px`\n- Sublabels: `9px`\n- Annotations: `8px`\n- Tiny labels: `7px`\n- Legend: `10px`\n- Icon area labels: `11px`\n\n### Background\n\n- Page background: `#020617` (`slate-950`)\n- Background pattern: inline SVG grid pattern over the page background\n- Recommended grid line colors:\n  - Major grid: `rgba(148, 163, 184, 0.08)`\n  - Minor grid: `rgba(148, 163, 184, 0.04)`\n\n### Component Box Defaults\n\n- Shape: rounded rectangle\n- Border radius: `rx="6"`\n- Stroke width: `1.5px`\n- Fill: category-specific semi-transparent RGBA fill\n- Stroke: category-specific hex stroke\n- Label stack:\n  - Line 1: C4 label such as `<<Container>>`\n  - Line 2: component name\n  - Line 3: subtype or technology summary\n\n## Category Registry\n\nThe registry is hierarchical: categories define shared tokens and C4 intent, while sub-types inherit the category styling and reserve an icon slot for future SVG glyphs.\n\n| Category | Stroke Color | Fill Color | C4 Mapping | Sub-types |\n|---|---|---|---|---|\n| Frontend | `#22d3ee` | `rgba(8, 51, 68, 0.4)` | Container (SPA, web) | SPA, Mobile App, Static Site, Micro-frontend, PWA, Desktop App |\n| Backend | `#34d399` | `rgba(6, 78, 59, 0.4)` | Container (service) | API Service, Worker/Job, BFF, Microservice, Serverless Function, gRPC Service |\n| Data | `#a78bfa` | `rgba(76, 29, 149, 0.4)` | ContainerDb | Relational DB, Document DB, Key-Value Store, Cache, Search Engine, Data Warehouse, Graph DB, Time-Series DB |\n| Infrastructure | `#fbbf24` | `rgba(120, 53, 15, 0.3)` | Deployment_Node | CDN, Load Balancer, DNS, Object Storage, Container Registry, Reverse Proxy, Service Mesh |\n| Messaging | `#fb923c` | `rgba(251, 146, 60, 0.3)` | ContainerQueue | Message Queue, Event Bus, Stream, Pub/Sub, Webhook |\n| Security | `#fb7185` | `rgba(136, 19, 55, 0.4)` | System_Ext / boundary | Auth Provider, API Gateway, WAF, Secret Manager, Certificate Manager, Identity Provider |\n| External | `#94a3b8` | `rgba(30, 41, 59, 0.5)` | System_Ext | Third-party API, SaaS, Legacy System, Partner Service, Payment Provider |\n| Monitoring | `#38bdf8` | `rgba(12, 74, 110, 0.4)` | Container | Logging, Metrics, Tracing, Alerting, APM |\n\n## Sub-type Registry\n\nEach sub-type inherits its category tokens and keeps a placeholder slot for an inline SVG icon.\n\n| Category | Sub-type | C4 Label | Icon Slot |\n|---|---|---|---|\n| Frontend | SPA | `<<Container>>` | `icon-spa` |\n| Frontend | Mobile App | `<<Container>>` | `icon-mobile-app` |\n| Frontend | Static Site | `<<Container>>` | `icon-static-site` |\n| Frontend | Micro-frontend | `<<Container>>` | `icon-micro-frontend` |\n| Frontend | PWA | `<<Container>>` | `icon-pwa` |\n| Frontend | Desktop App | `<<Container>>` | `icon-desktop-app` |\n| Backend | API Service | `<<Container>>` | `icon-api-service` |\n| Backend | Worker/Job | `<<Container>>` | `icon-worker-job` |\n| Backend | BFF | `<<Container>>` | `icon-bff` |\n| Backend | Microservice | `<<Container>>` | `icon-microservice` |\n| Backend | Serverless Function | `<<Container>>` | `icon-serverless-function` |\n| Backend | gRPC Service | `<<Container>>` | `icon-grpc-service` |\n| Data | Relational DB | `<<ContainerDb>>` | `icon-relational-db` |\n| Data | Document DB | `<<ContainerDb>>` | `icon-document-db` |\n| Data | Key-Value Store | `<<ContainerDb>>` | `icon-key-value-store` |\n| Data | Cache | `<<ContainerDb>>` | `icon-cache` |\n| Data | Search Engine | `<<ContainerDb>>` | `icon-search-engine` |\n| Data | Data Warehouse | `<<ContainerDb>>` | `icon-data-warehouse` |\n| Data | Graph DB | `<<ContainerDb>>` | `icon-graph-db` |\n| Data | Time-Series DB | `<<ContainerDb>>` | `icon-time-series-db` |\n| Infrastructure | CDN | `<<Deployment_Node>>` | `icon-cdn` |\n| Infrastructure | Load Balancer | `<<Deployment_Node>>` | `icon-load-balancer` |\n| Infrastructure | DNS | `<<Deployment_Node>>` | `icon-dns` |\n| Infrastructure | Object Storage | `<<Deployment_Node>>` | `icon-object-storage` |\n| Infrastructure | Container Registry | `<<Deployment_Node>>` | `icon-container-registry` |\n| Infrastructure | Reverse Proxy | `<<Deployment_Node>>` | `icon-reverse-proxy` |\n| Infrastructure | Service Mesh | `<<Deployment_Node>>` | `icon-service-mesh` |\n| Messaging | Message Queue | `<<ContainerQueue>>` | `icon-message-queue` |\n| Messaging | Event Bus | `<<ContainerQueue>>` | `icon-event-bus` |\n| Messaging | Stream | `<<ContainerQueue>>` | `icon-stream` |\n| Messaging | Pub/Sub | `<<ContainerQueue>>` | `icon-pub-sub` |\n| Messaging | Webhook | `<<ContainerQueue>>` | `icon-webhook` |\n| Security | Auth Provider | `<<System_Ext>>` | `icon-auth-provider` |\n| Security | API Gateway | `<<System_Ext>>` | `icon-api-gateway` |\n| Security | WAF | `<<System_Ext>>` | `icon-waf` |\n| Security | Secret Manager | `<<System_Ext>>` | `icon-secret-manager` |\n| Security | Certificate Manager | `<<System_Ext>>` | `icon-certificate-manager` |\n| Security | Identity Provider | `<<System_Ext>>` | `icon-identity-provider` |\n| External | Third-party API | `<<System_Ext>>` | `icon-third-party-api` |\n| External | SaaS | `<<System_Ext>>` | `icon-saas` |\n| External | Legacy System | `<<System_Ext>>` | `icon-legacy-system` |\n| External | Partner Service | `<<System_Ext>>` | `icon-partner-service` |\n| External | Payment Provider | `<<System_Ext>>` | `icon-payment-provider` |\n| Monitoring | Logging | `<<Container>>` | `icon-logging` |\n| Monitoring | Metrics | `<<Container>>` | `icon-metrics` |\n| Monitoring | Tracing | `<<Container>>` | `icon-tracing` |\n| Monitoring | Alerting | `<<Container>>` | `icon-alerting` |\n| Monitoring | APM | `<<Container>>` | `icon-apm` |\n\n## Icon Registry\n\nIcons are inline SVG `<symbol>` elements with a 16x16 viewBox, rendered via `<use>` at `(x+W-22, y+4)` inside the component box. They use `currentColor` to inherit the category stroke color.\n\n### Category-Level Icons (active)\n\nEach category has a shared icon defined in `html-template.html` `<defs>`. All sub-types within a category use their category icon by default. Sub-type-specific icons can override these in the future.\n\n| Category | Symbol ID | Shape | Status |\n|---|---|---|---|\n| Frontend | `icon-frontend` | Monitor with stand | **active** |\n| Backend | `icon-backend` | Server rack (3 units) | **active** |\n| Data | `icon-data` | Database cylinder | **active** |\n| Infrastructure | `icon-infrastructure` | Cloud | **active** |\n| Messaging | `icon-messaging` | Envelope | **active** |\n| Security | `icon-security` | Shield with checkmark | **active** |\n| External | `icon-external` | Globe with meridians | **active** |\n| Monitoring | `icon-monitoring` | Line chart with axes | **active** |\n\nUsage pattern:\n```svg\n<use href="#icon-frontend" class="icon-use" x="448" y="154" width="16" height="16"/>\n```\n\n### Sub-type Icons (planned)\n\nWhen a sub-type icon is added, it overrides the category icon for that specific component. Until implemented, all sub-types use their category icon.\n\n| Sub-type | Icon | Status |\n|---|---|---|\n| SPA | `icon-spa` | planned |\n| Mobile App | `icon-mobile-app` | planned |\n| Static Site | `icon-static-site` | planned |\n| Micro-frontend | `icon-micro-frontend` | planned |\n| PWA | `icon-pwa` | planned |\n| Desktop App | `icon-desktop-app` | planned |\n| API Service | `icon-api-service` | planned |\n| Worker/Job | `icon-worker-job` | planned |\n| BFF | `icon-bff` | planned |\n| Microservice | `icon-microservice` | planned |\n| Serverless Function | `icon-serverless-function` | planned |\n| gRPC Service | `icon-grpc-service` | planned |\n| Relational DB | `icon-relational-db` | planned |\n| Document DB | `icon-document-db` | planned |\n| Key-Value Store | `icon-key-value-store` | planned |\n| Cache | `icon-cache` | planned |\n| Search Engine | `icon-search-engine` | planned |\n| Data Warehouse | `icon-data-warehouse` | planned |\n| Graph DB | `icon-graph-db` | planned |\n| Time-Series DB | `icon-time-series-db` | planned |\n| CDN | `icon-cdn` | planned |\n| Load Balancer | `icon-load-balancer` | planned |\n| DNS | `icon-dns` | planned |\n| Object Storage | `icon-object-storage` | planned |\n| Container Registry | `icon-container-registry` | planned |\n| Reverse Proxy | `icon-reverse-proxy` | planned |\n| Service Mesh | `icon-service-mesh` | planned |\n| Message Queue | `icon-message-queue` | planned |\n| Event Bus | `icon-event-bus` | planned |\n| Stream | `icon-stream` | planned |\n| Pub/Sub | `icon-pub-sub` | planned |\n| Webhook | `icon-webhook` | planned |\n| Auth Provider | `icon-auth-provider` | planned |\n| API Gateway | `icon-api-gateway` | planned |\n| WAF | `icon-waf` | planned |\n| Secret Manager | `icon-secret-manager` | planned |\n| Certificate Manager | `icon-certificate-manager` | planned |\n| Identity Provider | `icon-identity-provider` | planned |\n| Third-party API | `icon-third-party-api` | planned |\n| SaaS | `icon-saas` | planned |\n| Legacy System | `icon-legacy-system` | planned |\n| Partner Service | `icon-partner-service` | planned |\n| Payment Provider | `icon-payment-provider` | planned |\n| Logging | `icon-logging` | planned |\n| Metrics | `icon-metrics` | planned |\n| Tracing | `icon-tracing` | planned |\n| Alerting | `icon-alerting` | planned |\n| APM | `icon-apm` | planned |\n\n## Visual Elements\n\n### Component Box Pattern\n\nUse a rounded component box with semi-transparent fill and category stroke.\n\n```svg\n<g class="node backend">\n  <rect x="280" y="210" width="190" height="60" rx="6" />\n  <text class="c4-tag" x="294" y="226">&lt;&lt;Container&gt;&gt;</text>\n  <text class="node-title" x="294" y="243">API Service</text>\n  <text class="node-subtitle" x="294" y="257">Backend / HTTPS JSON</text>\n</g>\n```\n\n### Arrow Masking Technique\n\nUse an opaque background rectangle below the box content to visually hide arrows beneath components without breaking the component fill style.\n\n```svg\n<g class="node-mask-layer">\n  <rect x="280" y="210" width="190" height="60" rx="6" fill="#020617" />\n  <rect x="280" y="210" width="190" height="60" rx="6"\n        fill="rgba(6, 78, 59, 0.4)" stroke="#34d399" stroke-width="1.5" />\n</g>\n```\n\n### Security Group Boundary\n\n- Purpose: show auth, gateway, WAF, or identity zones\n- Stroke color: rose (`#fb7185`)\n- Pattern: `stroke-dasharray="4,4"`\n- Suggested label: `Security Boundary`\n\n```svg\n<rect x="700" y="140" width="220" height="180" rx="12"\n      fill="transparent" stroke="#fb7185" stroke-width="1.5"\n      stroke-dasharray="4,4" />\n```\n\n### Region Boundary\n\n- Purpose: group a deployment region, platform segment, or domain slice\n- Stroke color: amber (`#fbbf24`)\n- Pattern: `stroke-dasharray="8,4"`\n- Radius: `rx="12"`\n\n```svg\n<rect x="70" y="120" width="600" height="430" rx="12"\n      fill="transparent" stroke="#fbbf24" stroke-width="1.5"\n      stroke-dasharray="8,4" />\n```\n\n### Arrow Marker SVG Definition\n\n```svg\n<defs>\n  <marker id="arrowhead" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto">\n    <path d="M0,0 L8,4 L0,8 Z" fill="#cbd5e1" />\n  </marker>\n</defs>\n```\n\n### Arrow Z-order Rule\n\nDraw arrows early in the SVG so component boxes and masking layers paint over them. This keeps connectors readable in dense diagrams and avoids arrow overlap across component interiors.\n\n## Spacing Rules\n\n- Standard component height: `60px`\n- Minimum vertical gap between stacked components: `40px`\n- Inline connectors should route through gaps rather than through component interiors\n- Keep labels inside the top `28px` of the box and the subtype line inside the lower third\n- Place legends outside boundaries to prevent classification noise inside the diagram area\n\n## Layout Structure\n\nThe canonical page composition is:\n\n1. Header: title, pulse dot, subtitle\n2. Main SVG diagram: embedded inside a rounded border card\n3. Summary cards: grid of 3 cards beneath the diagram\n4. Footer metadata: generator, scope, rendering notes, last-updated stamp\n\n## Present Tool Integration\n\nCompose architecture diagrams with the `present` tool by embedding the full HTML/SVG diagram in a markdown block and pairing it with metrics or cards blocks as needed.\n\n### `format: "html"`\n\nUse a `markdown` block with embedded `<div>`, inline SVG, and a `<style>` tag containing the full CSS. The `present` html format renders raw HTML in markdown blocks.\n\n### `format: "browser"`\n\nUse the same composition: a `markdown` block containing the full HTML structure. Summary content can also be added with `cards` and `metrics` blocks alongside the SVG diagram block.\n\n### Example `present` Call Structure\n\n```js\npresent({\n  format: "html", // or "browser"\n  title: "System Architecture",\n  content: [\n    {\n      type: "metrics",\n      title: "Overview",\n      value: [\n        { label: "Services", value: "6" },\n        { label: "Data Stores", value: "2" },\n        { label: "External Systems", value: "3" }\n      ]\n    },\n    {\n      type: "markdown",\n      title: "Architecture Diagram",\n      value: "<div class=\'arch-diagram\'>...(inline SVG)...</div><style>...(design system CSS)...</style>"\n    },\n    {\n      type: "cards",\n      title: "Summary",\n      value: [\n        { title: "Frontend", body: "React SPA..." },\n        { title: "Backend", body: "API + async workers..." },\n        { title: "Security", body: "Gateway + IdP..." }\n      ]\n    }\n  ]\n})\n```\n\nThis design system is the single source of truth. The `c4-architecture` skill and `present` skill both reference this file. Update component types, colors, or layout rules here only.\n\n## Adding New Categories\n\n1. Add a new row to the Category Registry with the category name, colors, C4 mapping, and initial subtype set.\n2. Add the new sub-types to the Sub-type Registry with a C4 label and icon slot name.\n3. Add icon placeholders to the Icon Registry.\n4. Update [html-template.html](html-template.html) legend content so the new category appears in the rendered template.\n5. Update summary card accent colors in [html-template.html](html-template.html) if the new category needs a dedicated card treatment.\n\n## Template Pairing\n\nSee [html-template.html](html-template.html) for the complete self-contained reference implementation of this design system.\n'},{file:`SKILL.md`,content:`---
 name: c4-architecture
 description: "Generate architecture documentation using C4 model diagrams. Supports two output formats: Mermaid (md) for documentation and HTML/SVG for presentations. Use when asked to create architecture diagrams, document system architecture, visualize software structure, create C4 diagrams, or generate context/container/component/deployment diagrams."
 metadata:
@@ -5044,10 +3906,7 @@ Write architecture documentation to \`docs/architecture/\` with naming conventio
 - [references/advanced-patterns.md](references/advanced-patterns.md) - Microservices, event-driven, deployment
 - [references/html-design-system.md](references/html-design-system.md) - Centralized HTML/SVG design system (types, colors, icons, present integration)
 - [references/html-template.html](references/html-template.html) - Self-contained HTML template for C4 diagrams
-` },
-  ],
-  "docs": [
-    { file: "references/diataxis-anti-patterns.md", content: `# Diátaxis Anti-Patterns
+`}],docs:[{file:`references/diataxis-anti-patterns.md`,content:`# Diátaxis Anti-Patterns
 
 Five common documentation anti-patterns that violate Diátaxis quadrant boundaries. Each pattern includes detection signals, a violation/compliant example pair, and remediation.
 
@@ -5193,8 +4052,7 @@ Common cases where the boundary between two quadrants is genuinely ambiguous:
 
 ## Attribution
 
-This reference adapts concepts from the Diátaxis framework at diataxis.fr and from keithpatton/diataxis-agent-skill. Diátaxis framework content is licensed under CC-BY-SA 4.0; retain attribution and share-alike terms for further adaptations.` },
-    { file: "references/diataxis-compass.md", content: `# The Diataxis Compass
+This reference adapts concepts from the Diátaxis framework at diataxis.fr and from keithpatton/diataxis-agent-skill. Diátaxis framework content is licensed under CC-BY-SA 4.0; retain attribution and share-alike terms for further adaptations.`},{file:`references/diataxis-compass.md`,content:`# The Diataxis Compass
 
 The Diataxis Compass is a simple classification aid for documentation. It reduces classification to two axes so an author can decide what kind of document they are writing before structure and tone drift across quadrants.
 
@@ -5316,8 +4174,7 @@ This document adapts concepts from the Diataxis framework at [diataxis.fr](https
 
 Source material is licensed under **CC-BY-SA 4.0**.
 
-Attribution: Daniele Procida, *Diataxis*, [https://diataxis.fr/](https://diataxis.fr/).` },
-    { file: "references/diataxis-quadrants.md", content: `# Diataxis Quadrants
+Attribution: Daniele Procida, *Diataxis*, [https://diataxis.fr/](https://diataxis.fr/).`},{file:`references/diataxis-quadrants.md`,content:`# Diataxis Quadrants
 
 This reference describes the four documentation quadrants in Diataxis: Tutorial, How-to guide, Reference, and Explanation. Use it when a document has already been classified, or when you need boundary tests to decide whether content belongs in one quadrant or has drifted into another.
 
@@ -5508,8 +4365,7 @@ This document adapts concepts from the Diataxis framework at [diataxis.fr](https
 
 Source material is licensed under **CC-BY-SA 4.0**.
 
-Attribution: Daniele Procida, *Diataxis*, [https://diataxis.fr/](https://diataxis.fr/).` },
-    { file: "references/diataxis-quality.md", content: `# Diataxis Quality & Iteration
+Attribution: Daniele Procida, *Diataxis*, [https://diataxis.fr/](https://diataxis.fr/).`},{file:`references/diataxis-quality.md`,content:`# Diataxis Quality & Iteration
 
 How to assess and improve documentation quality using the Diátaxis framework.
 
@@ -5584,8 +4440,7 @@ Per document, count how many checklist items pass out of the total applicable it
 
 ---
 
-*Quality framework follows the Diátaxis documentation framework (CC-BY-SA 4.0, Daniele Procida).*` },
-    { file: "references/diataxis-templates.md", content: `# Diataxis Templates
+*Quality framework follows the Diátaxis documentation framework (CC-BY-SA 4.0, Daniele Procida).*`},{file:`references/diataxis-templates.md`,content:`# Diataxis Templates
 
 Templates for Tutorial and Explanation documents. For How-To and Reference templates, see the main docs SKILL.md.
 
@@ -5704,110 +4559,7 @@ type: explanation
 
 ---
 
-*Templates follow the Diátaxis documentation framework (CC-BY-SA 4.0, Daniele Procida).*` },
-    { file: "references/flow-artifacts-guide.md", content: `# Flow Artifacts Guide
-
-## What Are Flow Artifacts
-
-Flows produce structured markdown artifacts in \`{{artifacts_path}}/\`. These files capture requirements, decisions, plan shape, implementation progress, and verification results for the completed flow.
-
-Use artifacts to document the why behind changes. Code diffs still matter, but artifacts usually contain the rationale, constraints, risks, and review findings that should shape durable documentation.
-
-## How to Discover Artifacts
-
-\`\`\`text
-flow_status()                                      # Get artifactsPath
-find({ pattern: "*.md", path: "<artifactsPath>" }) # Discover artifact files
-digest({ sources: [                                # Compress into working context
-  { path: "<found-artifact-1>" },
-  { path: "<found-artifact-2>" },
-  ...
-]})
-\`\`\`
-
-Read every artifact \`find()\` returns. Different flows produce different files — do not assume specific filenames exist.
-
-## Artifact Catalog
-
-| Artifact | Flow | Contains |
-|---|---|---|
-| \`design-decisions.md\` | \`aikit:basic\`, \`aikit:advanced\` | FORGE tier, approach, key decisions, constraints, and risks |
-| \`assessment.md\` | \`aikit:basic\` | Goal, affected files, approach steps, risks, and open questions |
-| \`spec.md\` | \`aikit:advanced\` | Requirements, acceptance criteria, and scope boundaries |
-| \`plan.md\` | \`aikit:advanced\` | Phased implementation plan and architecture decisions |
-| \`tasks.md\` | \`aikit:advanced\` | Atomic task list, dependencies, and agent assignments |
-| \`progress.md\` | \`aikit:basic\`, \`aikit:advanced\` | Changes made, tests, deviations, and validation results |
-| \`verify-report.md\` | \`aikit:basic\`, \`aikit:advanced\` | Verdict, quality gates, review findings, security, and recommendation |
-
-## Artifact-to-Documentation Mapping
-
-| Artifact | Contains | Documentation Target | Action |
-|---|---|---|---|
-| \`design-decisions.md\` | FORGE tier, approach, key decisions | \`docs/decisions/\` | Create or update ADRs via \`adr-skill\` for each key decision |
-| \`design-decisions.md\` | Architecture approach, constraints | \`docs/architecture/overview.md\` | Update the design rationale section |
-| \`spec.md\` | Requirements, acceptance criteria | \`docs/reference/\` | Update API or component reference when public surface changed |
-| \`plan.md\` | Architecture decisions, phase design | \`docs/architecture/\` | Update architecture docs with structural changes |
-| \`tasks.md\` | Task breakdown, dependencies | Usually skip | Only document if it reveals new component boundaries |
-| \`progress.md\` | Files changed, deviations, tests | \`docs/guides/testing.md\` | Update when testing strategy changed |
-| \`progress.md\` | Deviations from plan | \`docs/decisions/\` | Document significant deviations as ADRs |
-| \`verify-report.md\` | Code review findings, security | \`docs/architecture/overview.md\` | Update if findings reveal architectural patterns |
-| \`verify-report.md\` | Security concerns | \`docs/guides/\` | Create or update security guidance when concerns are material |
-
-## Reading Strategy
-
-Read every artifact \`find()\` returns. Triage by content type:
-
-| Content Signal | Documentation Value | Action |
-|---|---|---|
-| Decisions, rationale, constraints | High — durable knowledge | Extract into \`docs/decisions/\` or architecture docs |
-| Requirements, scope, acceptance criteria | High — defines intent | Update reference docs if public surface changed |
-| Review findings, security concerns, quality gates | Medium — surfaces issues | Update architecture or guides if findings are material |
-| Implementation progress, task lists | Low — transient | Document only meaningful deviations from the plan |
-
-Skip artifacts that only repeat completed work with no insights beyond the code diff.
-
-> The catalog and mapping tables above list artifacts from built-in flows (\`aikit:basic\`, \`aikit:advanced\`). Custom flows may produce entirely different artifacts — always discover dynamically with \`find()\` and classify by content, not by filename.
-
-## What Not to Document
-
-| Avoid | Do Instead |
-|---|---|
-| Copying artifact text verbatim into \`docs/\` | Extract decisions, rationale, constraints, and stable guidance |
-| Documenting every task or progress update | Keep only durable insights that help future readers |
-| Mirroring temporary planning details | Preserve the final reasoning, not the transient workflow chatter |` },
-    { file: "references/project-knowledge-gotchas.md", content: `# Project Knowledge — Gotchas
-
-Common pitfalls when documenting project knowledge. Reference this during Phase 2 (Investigate) and Phase 4 (Validate).
-
-## Environment Gotchas
-
-**Monorepos:** Root \`package.json\` may have no source — check for \`workspaces\`, \`packages/\`, or \`apps/\` directories. Each workspace may have independent dependencies and conventions. Map each sub-package separately.
-
-**Outdated README:** README often describes intended architecture, not the current one. Cross-reference with actual file structure before treating any README claim as fact.
-
-**TypeScript path aliases:** \`tsconfig.json\` \`paths\` config means imports like \`@/foo\` don't map directly to the filesystem. Map aliases to real paths before documenting structure.
-
-**Generated/compiled output:** Never document patterns from \`dist/\`, \`build/\`, \`generated/\`, \`.next/\`, \`out/\`, or \`__pycache__/\`. These are artefacts — document source conventions only.
-
-**\`.env.example\` reveals required config:** Secrets are never committed. Read \`.env.example\`, \`.env.template\`, or \`.env.sample\` to discover required environment variables.
-
-**\`devDependencies\` ≠ production stack:** Only \`dependencies\` (or equivalent) runs in production. Document linters, formatters, and test frameworks separately as dev tooling in \`stack.md\`.
-
-**Test TODOs ≠ production debt:** TODOs inside test directories are coverage gaps, not production technical debt. Separate them in \`concerns.md\`.
-
-**High-churn files = fragile areas:** Files appearing most in recent \`git_context({})\` output have the highest modification rate and likely hidden complexity. Always note them in \`concerns.md\`.
-
-## Anti-Pattern Table
-
-| ❌ Don't | ✅ Do instead |
-|---------|--------------|
-| "Uses Clean Architecture with Domain/Data layers" (when no such directories exist) | State only what directory structure actually shows |
-| "This is a Next.js project" (without checking \`package.json\`) | Check \`dependencies\` first. State what's actually there |
-| Guess the database from a variable name like \`dbUrl\` | Check manifest for \`pg\`, \`mysql2\`, \`mongoose\`, \`prisma\`, etc. |
-| Document \`dist/\` or \`build/\` naming patterns as conventions | Source files only |
-| Assume README describes current architecture | Cross-reference with actual file structure via \`analyze_structure\` |
-| Treat test TODOs as production tech debt | Separate coverage gaps from production concerns in \`concerns.md\` |` },
-    { file: "references/project-knowledge-templates.md", content: `# Project Knowledge Templates
+*Templates follow the Diátaxis documentation framework (CC-BY-SA 4.0, Daniele Procida).*`},{file:`references/flow-artifacts-guide.md`,content:'# Flow Artifacts Guide\n\n## What Are Flow Artifacts\n\nFlows produce structured markdown artifacts in `{{artifacts_path}}/`. These files capture requirements, decisions, plan shape, implementation progress, and verification results for the completed flow.\n\nUse artifacts to document the why behind changes. Code diffs still matter, but artifacts usually contain the rationale, constraints, risks, and review findings that should shape durable documentation.\n\n## How to Discover Artifacts\n\n```text\nflow_status()                                      # Get artifactsPath\nfind({ pattern: "*.md", path: "<artifactsPath>" }) # Discover artifact files\ndigest({ sources: [                                # Compress into working context\n  { path: "<found-artifact-1>" },\n  { path: "<found-artifact-2>" },\n  ...\n]})\n```\n\nRead every artifact `find()` returns. Different flows produce different files — do not assume specific filenames exist.\n\n## Artifact Catalog\n\n| Artifact | Flow | Contains |\n|---|---|---|\n| `design-decisions.md` | `aikit:basic`, `aikit:advanced` | FORGE tier, approach, key decisions, constraints, and risks |\n| `assessment.md` | `aikit:basic` | Goal, affected files, approach steps, risks, and open questions |\n| `spec.md` | `aikit:advanced` | Requirements, acceptance criteria, and scope boundaries |\n| `plan.md` | `aikit:advanced` | Phased implementation plan and architecture decisions |\n| `tasks.md` | `aikit:advanced` | Atomic task list, dependencies, and agent assignments |\n| `progress.md` | `aikit:basic`, `aikit:advanced` | Changes made, tests, deviations, and validation results |\n| `verify-report.md` | `aikit:basic`, `aikit:advanced` | Verdict, quality gates, review findings, security, and recommendation |\n\n## Artifact-to-Documentation Mapping\n\n| Artifact | Contains | Documentation Target | Action |\n|---|---|---|---|\n| `design-decisions.md` | FORGE tier, approach, key decisions | `docs/decisions/` | Create or update ADRs via `adr-skill` for each key decision |\n| `design-decisions.md` | Architecture approach, constraints | `docs/architecture/overview.md` | Update the design rationale section |\n| `spec.md` | Requirements, acceptance criteria | `docs/reference/` | Update API or component reference when public surface changed |\n| `plan.md` | Architecture decisions, phase design | `docs/architecture/` | Update architecture docs with structural changes |\n| `tasks.md` | Task breakdown, dependencies | Usually skip | Only document if it reveals new component boundaries |\n| `progress.md` | Files changed, deviations, tests | `docs/guides/testing.md` | Update when testing strategy changed |\n| `progress.md` | Deviations from plan | `docs/decisions/` | Document significant deviations as ADRs |\n| `verify-report.md` | Code review findings, security | `docs/architecture/overview.md` | Update if findings reveal architectural patterns |\n| `verify-report.md` | Security concerns | `docs/guides/` | Create or update security guidance when concerns are material |\n\n## Reading Strategy\n\nRead every artifact `find()` returns. Triage by content type:\n\n| Content Signal | Documentation Value | Action |\n|---|---|---|\n| Decisions, rationale, constraints | High — durable knowledge | Extract into `docs/decisions/` or architecture docs |\n| Requirements, scope, acceptance criteria | High — defines intent | Update reference docs if public surface changed |\n| Review findings, security concerns, quality gates | Medium — surfaces issues | Update architecture or guides if findings are material |\n| Implementation progress, task lists | Low — transient | Document only meaningful deviations from the plan |\n\nSkip artifacts that only repeat completed work with no insights beyond the code diff.\n\n> The catalog and mapping tables above list artifacts from built-in flows (`aikit:basic`, `aikit:advanced`). Custom flows may produce entirely different artifacts — always discover dynamically with `find()` and classify by content, not by filename.\n\n## What Not to Document\n\n| Avoid | Do Instead |\n|---|---|\n| Copying artifact text verbatim into `docs/` | Extract decisions, rationale, constraints, and stable guidance |\n| Documenting every task or progress update | Keep only durable insights that help future readers |\n| Mirroring temporary planning details | Preserve the final reasoning, not the transient workflow chatter |'},{file:`references/project-knowledge-gotchas.md`,content:'# Project Knowledge — Gotchas\n\nCommon pitfalls when documenting project knowledge. Reference this during Phase 2 (Investigate) and Phase 4 (Validate).\n\n## Environment Gotchas\n\n**Monorepos:** Root `package.json` may have no source — check for `workspaces`, `packages/`, or `apps/` directories. Each workspace may have independent dependencies and conventions. Map each sub-package separately.\n\n**Outdated README:** README often describes intended architecture, not the current one. Cross-reference with actual file structure before treating any README claim as fact.\n\n**TypeScript path aliases:** `tsconfig.json` `paths` config means imports like `@/foo` don\'t map directly to the filesystem. Map aliases to real paths before documenting structure.\n\n**Generated/compiled output:** Never document patterns from `dist/`, `build/`, `generated/`, `.next/`, `out/`, or `__pycache__/`. These are artefacts — document source conventions only.\n\n**`.env.example` reveals required config:** Secrets are never committed. Read `.env.example`, `.env.template`, or `.env.sample` to discover required environment variables.\n\n**`devDependencies` ≠ production stack:** Only `dependencies` (or equivalent) runs in production. Document linters, formatters, and test frameworks separately as dev tooling in `stack.md`.\n\n**Test TODOs ≠ production debt:** TODOs inside test directories are coverage gaps, not production technical debt. Separate them in `concerns.md`.\n\n**High-churn files = fragile areas:** Files appearing most in recent `git_context({})` output have the highest modification rate and likely hidden complexity. Always note them in `concerns.md`.\n\n## Anti-Pattern Table\n\n| ❌ Don\'t | ✅ Do instead |\n|---------|--------------|\n| "Uses Clean Architecture with Domain/Data layers" (when no such directories exist) | State only what directory structure actually shows |\n| "This is a Next.js project" (without checking `package.json`) | Check `dependencies` first. State what\'s actually there |\n| Guess the database from a variable name like `dbUrl` | Check manifest for `pg`, `mysql2`, `mongoose`, `prisma`, etc. |\n| Document `dist/` or `build/` naming patterns as conventions | Source files only |\n| Assume README describes current architecture | Cross-reference with actual file structure via `analyze_structure` |\n| Treat test TODOs as production tech debt | Separate coverage gaps from production concerns in `concerns.md` |'},{file:`references/project-knowledge-templates.md`,content:`# Project Knowledge Templates
 
 Templates for the seven project knowledge documents in \`docs/architecture/\`. Use these to ensure consistent structure across projects.
 
@@ -6087,8 +4839,7 @@ Templates for the seven project knowledge documents in \`docs/architecture/\`. U
 - \`audit()\` output — health issues
 - \`dead_symbols({})\` output — dead code
 - \`git_context({})\` output — high-churn files
-\`\`\`` },
-    { file: "references/project-knowledge-workflow.md", content: `# Project Knowledge — Workflow
+\`\`\``},{file:`references/project-knowledge-workflow.md`,content:`# Project Knowledge — Workflow
 
 Detailed workflow for acquiring and documenting project knowledge into \`docs/architecture/\`.
 
@@ -6167,8 +4918,7 @@ If the user specifies a focus area (e.g., "architecture only" or "testing and co
 1. Always run Phase 1 in full
 2. Fully complete focus-area documents first
 3. For non-focus documents, keep required sections present and mark unknowns as \`[TODO]\`
-4. Still run the Phase 4 validation loop on all seven documents` },
-    { file: "SKILL.md", content: `---
+4. Still run the Phase 4 validation loop on all seven documents`},{file:`SKILL.md`,content:`---
 name: docs
 description: "Living documentation management — Diátaxis framework, docs/ convention, create/update rules, staleness detection, integration with adr-skill and c4-architecture."
 metadata:
@@ -6720,10 +5470,7 @@ All links in generated docs must be correct relative to the file that contains t
 
 ---
 
-*Diátaxis content in this skill and its reference files is adapted from the [Diátaxis framework](https://diataxis.fr/) by Daniele Procida, used under [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/).*` },
-  ],
-  "frontend-design": [
-    { file: "SKILL.md", content: `---
+*Diátaxis content in this skill and its reference files is adapted from the [Diátaxis framework](https://diataxis.fr/) by Daniele Procida, used under [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/).*`}],"frontend-design":[{file:`SKILL.md`,content:`---
 name: frontend-design
 description: "Comprehensive frontend design system — visual design thinking, typography, color, layout, motion, accessibility, performance, and anti-pattern detection."
 metadata:
@@ -6960,10 +5707,7 @@ If 3+ items match → **STOP and redesign**. The goal is distinctive, not generi
 3. **Progressive enhancement** — works without JS, enhanced with JS
 4. **Content-first** — design with real content, not lorem ipsum
 5. **Test in context** — view components inside the actual page, not just in isolation
-` },
-  ],
-  "lesson-learned": [
-    { file: "references/anti-patterns.md", content: `---
+`}],"lesson-learned":[{file:`references/anti-patterns.md`,content:`---
 description: Common anti-patterns to detect in code diffs. Use alongside se-principles.md for balanced analysis -- principles show what's good, anti-patterns show what to watch for.
 ---
 
@@ -7018,8 +5762,7 @@ Functions that do too much.
 Comments explaining "what" instead of "why."
 **Diff signals:** Comments restating the code (\`// increment counter\`). Large comment blocks before straightforward code. Commented-out code left in place.
 **Suggest:** Make the code self-documenting through better naming. Use comments only for "why" -- intent, trade-offs, non-obvious constraints.
-` },
-    { file: "references/se-principles.md", content: `---
+`},{file:`references/se-principles.md`,content:`---
 description: Curated catalog of software engineering principles. Load this before analyzing code changes so you can map observations to named principles.
 ---
 
@@ -7128,8 +5871,7 @@ Code signals: A switch/if-else chain replaced with a strategy pattern or subclas
 
 **Introduce Parameter Object**
 Code signals: Multiple related parameters grouped into a single options/config object. Function signatures simplified.
-` },
-    { file: "SKILL.md", content: `---
+`},{file:`SKILL.md`,content:`---
 name: lesson-learned
 description: "Analyze recent code changes via git history and extract software engineering lessons. Use when the user asks 'what is the lesson here?', 'what can I learn from this?', 'engineering takeaway', 'what did I just learn?', 'reflect on this code', or wants to extract principles from recent work."
 metadata:
@@ -7242,446 +5984,439 @@ If there is a second lesson worth noting (maximum 2 additional):
 - **If the code is good, say so.** Not every lesson is about what went wrong. Recognizing good patterns reinforces them.
 - **If the changes are trivial** (a single config tweak, a typo fix), say so honestly rather than forcing a lesson. "These changes are straightforward -- no deep lesson here, just good housekeeping."
 - **Be specific.** Generic advice is worthless. Every claim must point to a concrete code change.
-` },
-  ],
-  "multi-agents-development": [
-    { file: "architecture-review-prompt.md", content: `# Architecture Review Prompt Template
-
-Use this template when dispatching **Architect-Reviewer-Alpha** and **Architect-Reviewer-Beta** for architecture review. Only needed when changes cross module boundaries, introduce new patterns, or modify shared infrastructure.
-
----
-
-## Prompt Template
-
-\`\`\`markdown
-You are performing an architecture review. Focus on structural decisions, not code quality (that's handled separately).
-
-## Change Summary
-[What was changed and why — high-level description]
-
-## Files Changed
-[List of files with module/boundary information]
-
-## Architectural Context
-[Paste relevant architecture docs, module graph, dependency structure from compact/digest]
-
----
-
-## Review Dimensions
-
-### 1. Boundary Integrity
-- Do changes respect existing module boundaries?
-- Are there new cross-module dependencies that shouldn't exist?
-- Is the dependency direction correct (inner → outer, not reverse)?
-
-### 2. Pattern Adherence
-- Do new components follow established architectural patterns?
-- Are there deviations from the documented architecture?
-- If a new pattern is introduced, is it justified and documented?
-
-### 3. Coupling & Cohesion
-- Are new dependencies minimal and well-justified?
-- Could any coupling be reduced with interfaces or inversion?
-- Are related concerns grouped together?
-
-### 4. Scalability Impact
-- Will this change create bottlenecks under load?
-- Are there single points of failure introduced?
-- Does this work with horizontal scaling?
-
-### 5. Migration & Evolution
-- Does this change make future changes harder?
-- Are there implicit assumptions that will break?
-- Is the change reversible if needed?
-
-### 6. API Surface
-- Are new public APIs minimal and well-designed?
-- Could any public surface be internal instead?
-- Are breaking changes flagged?
-
----
-
-## Output Format
-
-### Verdict: [APPROVE | APPROVE_WITH_NOTES | REQUEST_CHANGES]
-
-**APPROVE** — Architecture is sound.
-**APPROVE_WITH_NOTES** — Acceptable, but track these concerns.
-**REQUEST_CHANGES** — Structural issues that must be resolved.
-
-### Findings:
-| # | Dimension | Severity | Description | Impact |
-|---|-----------|----------|-------------|--------|
-| 1 | [Dimension] | [Blocker/Concern/Note] | [Issue] | [What breaks/degrades] |
-
-### Recommendation:
-[Structural guidance for improvement]
-\`\`\`
-
----
-
-## Usage Notes
-
-- **Only trigger architecture review when**: changes cross module boundaries, new patterns are introduced, shared infrastructure is modified, or public API surface changes
-- Both Alpha and Beta reviewers run in parallel for multi-model perspective
-- Architecture blockers are HIGH priority — must resolve before merge
-- If both reviewers flag the same concern, it's almost certainly a real issue
-` },
-    { file: "code-quality-review-prompt.md", content: `# Code Quality Review Prompt Template
-
-Use this template when dispatching **Code-Reviewer-Alpha** and **Code-Reviewer-Beta** for dual code quality review. Both reviewers get the same prompt — different models catch different issues.
-
-This review runs AFTER spec compliance passes.
-
----
-
-## Prompt Template
-
-\`\`\`markdown
-You are performing a code quality review. The code has already passed spec compliance — it does what was asked. Your job is to evaluate HOW it does it.
-
-## Task Context
-[Brief description of what was implemented and why]
-
-## Files Changed
-[List of files with a one-line description of changes in each]
-
-## Code Diff
-[Paste the actual code changes — full diff or new file contents]
-
----
-
-## Review Dimensions
-
-### 1. Readability & Maintainability
-- Are names clear and intention-revealing?
-- Is the code self-documenting or does it need comments?
-- Is complexity managed (small functions, single responsibility)?
-- Would a new team member understand this in 5 minutes?
-
-### 2. Pattern Adherence
-- Does the code follow the project's established patterns?
-- Are there inconsistencies with surrounding code?
-- Are there framework idioms being violated?
-
-### 3. Error Handling & Edge Cases
-- Are errors handled at appropriate boundaries?
-- Are edge cases considered (null, empty, overflow, concurrent access)?
-- Are error messages helpful for debugging?
-
-### 4. Performance
-- Any obvious N+1 queries or unnecessary iterations?
-- Any blocking operations that should be async?
-- Any missing caching opportunities or unnecessary allocations?
-
-### 5. Security
-- Input validation present for external data?
-- No secrets in code?
-- No injection vulnerabilities (SQL, XSS, command)?
-- Proper authorization checks?
-
-### 6. Spec Alignment (Cross-Check)
-- Does the implementation match what was requested?
-- Any over-engineering beyond requirements?
-- Any subtle deviations from the intended behavior?
-
-### 7. Testability
-- Is the code testable in isolation?
-- Are dependencies injectable?
-- Are there missing test cases?
-
----
-
-## Output Format
-
-### Verdict: [APPROVE | APPROVE_WITH_SUGGESTIONS | REQUEST_CHANGES]
-
-**APPROVE** — Code is production-ready.
-**APPROVE_WITH_SUGGESTIONS** — Good to merge, but consider these improvements.
-**REQUEST_CHANGES** — Must fix before proceeding. List blocking issues.
-
-### Findings:
-| # | Dimension | Severity | Description | Location | Suggestion |
-|---|-----------|----------|-------------|----------|------------|
-| 1 | [Dimension] | [Blocker/Major/Minor/Nit] | [Issue] | [file:line] | [Fix] |
-
-### Summary:
-[2-3 sentence overall assessment]
-\`\`\`
-
----
-
-## Usage Notes
-
-- Both Alpha and Beta reviewers get this same template — multi-model cross-validation
-- Combine findings from both reviewers before deciding on action
-- **Blocker** findings = REQUEST_CHANGES (must fix)
-- **Major** findings = usually REQUEST_CHANGES unless truly optional
-- **Minor/Nit** = APPROVE_WITH_SUGGESTIONS (fix in follow-up or ignore)
-` },
-    { file: "implementer-prompt.md", content: `# Implementer Dispatch Prompt Template
-
-Use this template when dispatching **Implementer**, **Frontend**, or **Refactor** agents.
-
-Fill in the bracketed sections with task-specific content. The Orchestrator provides ALL context — the subagent should NOT need to search/explore.
-
----
-
-## Prompt Template
-
-\`\`\`markdown
-You are implementing a focused task. All context you need is provided below. Do NOT search for additional files or read the full plan — work only within the scope defined here.
-
-## 1. Scope
-**Files to create/modify:**
-- [exact/path/to/file1.ts] — [create | modify]
-- [exact/path/to/file2.ts] — [create | modify]
-
-**Boundary — do NOT touch:**
-- [files/that/are/off/limits.ts]
-- [other/agents/territory/]
-
-## 2. Goal
-[Clear description of what the code should do]
-
-**Acceptance criteria:**
-- [ ] [Specific, testable criterion 1]
-- [ ] [Specific, testable criterion 2]
-- [ ] [Specific, testable criterion 3]
-
-## 3. Architectural Context
-[Relevant code snippets, patterns, conventions from compact/digest — paste actual code, don't reference files]
-
-Example existing pattern:
-\\\`\\\`\\\`typescript
-// From services/auth.service.ts — follow this pattern
-export class AuthService {
-  constructor(private readonly repo: AuthRepository) {}
-  async validate(token: string): Promise<User> { ... }
-}
-\\\`\\\`\\\`
-
-## 4. Constraints
-- Follow [specific pattern/convention]
-- Use [specific library/approach]
-- Do NOT [specific anti-pattern to avoid]
-- [Any other boundaries]
-
-## 5. FORGE Context
-**Tier:** [Floor | Standard | Critical]
-**Evidence requirements:** [What evidence to collect — test results, type coverage, etc.]
-
-## 6. Self-Review Checklist
-Before declaring your status, verify ALL:
-- [ ] All acceptance criteria from §2 are met
-- [ ] No files outside §1 scope were modified
-- [ ] Code follows conventions from §3 and constraints from §4
-- [ ] Tests pass (run them if possible)
-- [ ] No TODO/FIXME/HACK left without justification
-- [ ] No hardcoded values that should be configurable
-
----
-
-**STATUS PROTOCOL — End your response with EXACTLY ONE:**
-
-### DONE
-All tasks complete. Self-review checklist passed. Ready for review.
-
-### DONE_WITH_CONCERNS
-All tasks complete, but I have concerns:
-- [Concern 1: description + suggested resolution]
-- [Concern 2: description + suggested resolution]
-
-### NEEDS_CONTEXT
-Cannot proceed without the following:
-- [Specific question or missing information]
-
-### BLOCKED
-Hit a wall and cannot proceed:
-- [Description of blocker]
-- [What I tried]
-- [Suggestion for resolution]
-\`\`\`
-
----
-
-## Usage Notes
-
-- **Always paste actual code snippets** in §3 — use \`compact()\` or \`digest()\` to extract relevant context before crafting the prompt
-- **Keep scope tight** — 1-3 files maximum per dispatch
-- **Include failing test output** if dispatching a bug fix
-- **For Frontend agent**: add design requirements, responsive breakpoints, component hierarchy
-- **For Refactor agent**: include before/after expectations, what specifically to clean up
-` },
-    { file: "parallel-dispatch-example.md", content: `# Parallel Dispatch Worked Example
-
-This example shows how the Orchestrator decomposes a feature into parallel tasks, crafts context for each subagent, and manages the batch through review.
-
----
-
-## Scenario: Add User Notification Preferences
-
-**User request:** "Add a notification preferences page where users can toggle email, push, and in-app notifications per category (marketing, security, product updates)."
-
----
-
-## Step 1: Scope Map & Decomposition
-
-Orchestrator runs \`scope_map({ task: "notification preferences" })\` and identifies:
-
-| Area | Files | Agent |
-|------|-------|-------|
-| Backend API | \`services/notification-prefs.service.ts\`, \`routes/notification-prefs.route.ts\` | Implementer |
-| Database | \`migrations/add-notification-prefs.ts\`, \`models/notification-prefs.model.ts\` | Implementer |
-| Frontend Page | \`pages/settings/notifications.tsx\`, \`components/NotificationToggle.tsx\` | Frontend |
-| Tests | \`__tests__/notification-prefs.test.ts\` | Implementer |
-
-## Step 2: Independence Check (5-Question Checklist)
-
-| # | Question | Backend API + DB | Frontend Page |
-|---|----------|-----------------|---------------|
-| 1 | Same files? | \`services/\`, \`routes/\`, \`migrations/\`, \`models/\` | \`pages/\`, \`components/\` |
-| 2 | Shared state? | No — backend defines API contract | No — consumes API contract |
-| 3 | Execution order? | No — can define API while UI is built | No — can mock API response |
-| 4 | Shared new types? | Exports \`NotificationPrefs\` type | Imports same type |
-| 5 | Parallel-safe? | ✅ Yes — different directories | ✅ Yes — different directories |
-
-**Decision: PARALLEL** — But first define the shared type contract.
-
-## Step 3: Shared Context Prep
-
-Before dispatching, Orchestrator creates the shared contract:
-
-\`\`\`typescript
-// Type contract — paste into BOTH agent prompts
-interface NotificationPrefs {
-  userId: string;
-  categories: {
-    marketing: { email: boolean; push: boolean; inApp: boolean };
-    security: { email: boolean; push: boolean; inApp: boolean };
-    product: { email: boolean; push: boolean; inApp: boolean };
-  };
-  updatedAt: Date;
-}
-
-// API contract
-// GET  /api/notifications/preferences → NotificationPrefs
-// PUT  /api/notifications/preferences → NotificationPrefs (body: Partial<NotificationPrefs['categories']>)
-\`\`\`
-
-## Step 4: Parallel Dispatch
-
-### Dispatch A → Implementer (Backend + DB + Tests)
-
-\`\`\`markdown
-You are implementing a focused task. All context below.
-
-## 1. Scope
-- services/notification-prefs.service.ts — create
-- routes/notification-prefs.route.ts — create
-- migrations/add-notification-prefs.ts — create
-- models/notification-prefs.model.ts — create
-- __tests__/notification-prefs.test.ts — create
-
-## 2. Goal
-Create backend API for notification preferences CRUD.
-- GET endpoint returns current prefs (default all-true for new users)
-- PUT endpoint updates partial categories
-- Migration creates notification_preferences table
-
-## 3. Architectural Context
-[Paste existing service pattern from compact()]
-[Paste existing route pattern from compact()]
-[Paste existing migration pattern from compact()]
-[Paste the shared type contract above]
-
-## 4. Constraints
-- Follow existing repository pattern (see §3)
-- Use Zod for request validation
-- Include unit tests for service layer
-
-## 5. FORGE Context
-Tier: Standard. Evidence: test pass, type coverage.
-
-## 6. Self-Review Checklist
-[standard checklist]
-
-STATUS PROTOCOL: DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED
-\`\`\`
-
-### Dispatch B → Frontend (UI Page + Components)
-
-\`\`\`markdown
-You are implementing a focused task. All context below.
-
-## 1. Scope
-- pages/settings/notifications.tsx — create
-- components/NotificationToggle.tsx — create
-
-## 2. Goal
-Create notification preferences settings page.
-- Grid layout: rows = categories, columns = channels
-- Toggle switches for each cell
-- Auto-save on toggle (optimistic update with rollback)
-- Loading skeleton on initial fetch
-
-## 3. Architectural Context
-[Paste existing settings page pattern from compact()]
-[Paste existing toggle component from compact()]
-[Paste the shared type contract + API contract above]
-
-## 4. Constraints
-- Use existing Toggle component from design system
-- Follow settings page layout pattern
-- Mobile responsive (stack columns on small screens)
-- Mock API response for now: GET returns all-true defaults
-
-## 5. FORGE Context
-Tier: Floor. Evidence: renders without error.
-
-## 6. Self-Review Checklist
-[standard checklist]
-
-STATUS PROTOCOL: DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED
-\`\`\`
-
-## Step 5: Review Pipeline
-
-Both agents return DONE. Orchestrator runs review:
-
-1. **Spec Review** (Code-Reviewer-Alpha as spec reviewer):
-   - Backend: PASS — all acceptance criteria met
-   - Frontend: PASS_WITH_NOTES — missing keyboard accessibility on toggles
-
-2. **Code Quality Review** (Alpha + Beta in parallel):
-   - Alpha: APPROVE_WITH_SUGGESTIONS — extract validation schema to shared file
-   - Beta: APPROVE — clean implementation
-
-3. **Architecture Review** (not triggered — no boundary changes)
-
-4. **FORGE Gate**: \`evidence_map({ action: "gate" })\` → YIELD (all evidence collected)
-
-## Step 6: Commit
-
-\`\`\`
-feat: add notification preferences page
-
-- Backend: CRUD API for notification preferences per category
-- Frontend: Settings page with toggle grid, auto-save
-- Migration: notification_preferences table
-\`\`\`
-
----
-
-## Key Takeaways
-
-1. **Define shared contracts FIRST** — paste into all agent prompts
-2. **Independence check takes 30 seconds** — prevents hours of merge conflicts
-3. **Each agent gets ONLY its files** — focused context = better output
-4. **Review is sequential** — spec first, then quality, then architecture (conditional)
-5. **FORGE gates at the end** — not between every step
-` },
-    { file: "SKILL.md", content: `---
+`}],"multi-agents-development":[{file:`architecture-review-prompt.md`,content:`# Architecture Review Prompt Template
+
+Use this template when dispatching **Architect-Reviewer-Alpha** and **Architect-Reviewer-Beta** for architecture review. Only needed when changes cross module boundaries, introduce new patterns, or modify shared infrastructure.
+
+---
+
+## Prompt Template
+
+\`\`\`markdown
+You are performing an architecture review. Focus on structural decisions, not code quality (that's handled separately).
+
+## Change Summary
+[What was changed and why — high-level description]
+
+## Files Changed
+[List of files with module/boundary information]
+
+## Architectural Context
+[Paste relevant architecture docs, module graph, dependency structure from compact/digest]
+
+---
+
+## Review Dimensions
+
+### 1. Boundary Integrity
+- Do changes respect existing module boundaries?
+- Are there new cross-module dependencies that shouldn't exist?
+- Is the dependency direction correct (inner → outer, not reverse)?
+
+### 2. Pattern Adherence
+- Do new components follow established architectural patterns?
+- Are there deviations from the documented architecture?
+- If a new pattern is introduced, is it justified and documented?
+
+### 3. Coupling & Cohesion
+- Are new dependencies minimal and well-justified?
+- Could any coupling be reduced with interfaces or inversion?
+- Are related concerns grouped together?
+
+### 4. Scalability Impact
+- Will this change create bottlenecks under load?
+- Are there single points of failure introduced?
+- Does this work with horizontal scaling?
+
+### 5. Migration & Evolution
+- Does this change make future changes harder?
+- Are there implicit assumptions that will break?
+- Is the change reversible if needed?
+
+### 6. API Surface
+- Are new public APIs minimal and well-designed?
+- Could any public surface be internal instead?
+- Are breaking changes flagged?
+
+---
+
+## Output Format
+
+### Verdict: [APPROVE | APPROVE_WITH_NOTES | REQUEST_CHANGES]
+
+**APPROVE** — Architecture is sound.
+**APPROVE_WITH_NOTES** — Acceptable, but track these concerns.
+**REQUEST_CHANGES** — Structural issues that must be resolved.
+
+### Findings:
+| # | Dimension | Severity | Description | Impact |
+|---|-----------|----------|-------------|--------|
+| 1 | [Dimension] | [Blocker/Concern/Note] | [Issue] | [What breaks/degrades] |
+
+### Recommendation:
+[Structural guidance for improvement]
+\`\`\`
+
+---
+
+## Usage Notes
+
+- **Only trigger architecture review when**: changes cross module boundaries, new patterns are introduced, shared infrastructure is modified, or public API surface changes
+- Both Alpha and Beta reviewers run in parallel for multi-model perspective
+- Architecture blockers are HIGH priority — must resolve before merge
+- If both reviewers flag the same concern, it's almost certainly a real issue
+`},{file:`code-quality-review-prompt.md`,content:`# Code Quality Review Prompt Template
+
+Use this template when dispatching **Code-Reviewer-Alpha** and **Code-Reviewer-Beta** for dual code quality review. Both reviewers get the same prompt — different models catch different issues.
+
+This review runs AFTER spec compliance passes.
+
+---
+
+## Prompt Template
+
+\`\`\`markdown
+You are performing a code quality review. The code has already passed spec compliance — it does what was asked. Your job is to evaluate HOW it does it.
+
+## Task Context
+[Brief description of what was implemented and why]
+
+## Files Changed
+[List of files with a one-line description of changes in each]
+
+## Code Diff
+[Paste the actual code changes — full diff or new file contents]
+
+---
+
+## Review Dimensions
+
+### 1. Readability & Maintainability
+- Are names clear and intention-revealing?
+- Is the code self-documenting or does it need comments?
+- Is complexity managed (small functions, single responsibility)?
+- Would a new team member understand this in 5 minutes?
+
+### 2. Pattern Adherence
+- Does the code follow the project's established patterns?
+- Are there inconsistencies with surrounding code?
+- Are there framework idioms being violated?
+
+### 3. Error Handling & Edge Cases
+- Are errors handled at appropriate boundaries?
+- Are edge cases considered (null, empty, overflow, concurrent access)?
+- Are error messages helpful for debugging?
+
+### 4. Performance
+- Any obvious N+1 queries or unnecessary iterations?
+- Any blocking operations that should be async?
+- Any missing caching opportunities or unnecessary allocations?
+
+### 5. Security
+- Input validation present for external data?
+- No secrets in code?
+- No injection vulnerabilities (SQL, XSS, command)?
+- Proper authorization checks?
+
+### 6. Spec Alignment (Cross-Check)
+- Does the implementation match what was requested?
+- Any over-engineering beyond requirements?
+- Any subtle deviations from the intended behavior?
+
+### 7. Testability
+- Is the code testable in isolation?
+- Are dependencies injectable?
+- Are there missing test cases?
+
+---
+
+## Output Format
+
+### Verdict: [APPROVE | APPROVE_WITH_SUGGESTIONS | REQUEST_CHANGES]
+
+**APPROVE** — Code is production-ready.
+**APPROVE_WITH_SUGGESTIONS** — Good to merge, but consider these improvements.
+**REQUEST_CHANGES** — Must fix before proceeding. List blocking issues.
+
+### Findings:
+| # | Dimension | Severity | Description | Location | Suggestion |
+|---|-----------|----------|-------------|----------|------------|
+| 1 | [Dimension] | [Blocker/Major/Minor/Nit] | [Issue] | [file:line] | [Fix] |
+
+### Summary:
+[2-3 sentence overall assessment]
+\`\`\`
+
+---
+
+## Usage Notes
+
+- Both Alpha and Beta reviewers get this same template — multi-model cross-validation
+- Combine findings from both reviewers before deciding on action
+- **Blocker** findings = REQUEST_CHANGES (must fix)
+- **Major** findings = usually REQUEST_CHANGES unless truly optional
+- **Minor/Nit** = APPROVE_WITH_SUGGESTIONS (fix in follow-up or ignore)
+`},{file:`implementer-prompt.md`,content:`# Implementer Dispatch Prompt Template
+
+Use this template when dispatching **Implementer**, **Frontend**, or **Refactor** agents.
+
+Fill in the bracketed sections with task-specific content. The Orchestrator provides ALL context — the subagent should NOT need to search/explore.
+
+---
+
+## Prompt Template
+
+\`\`\`markdown
+You are implementing a focused task. All context you need is provided below. Do NOT search for additional files or read the full plan — work only within the scope defined here.
+
+## 1. Scope
+**Files to create/modify:**
+- [exact/path/to/file1.ts] — [create | modify]
+- [exact/path/to/file2.ts] — [create | modify]
+
+**Boundary — do NOT touch:**
+- [files/that/are/off/limits.ts]
+- [other/agents/territory/]
+
+## 2. Goal
+[Clear description of what the code should do]
+
+**Acceptance criteria:**
+- [ ] [Specific, testable criterion 1]
+- [ ] [Specific, testable criterion 2]
+- [ ] [Specific, testable criterion 3]
+
+## 3. Architectural Context
+[Relevant code snippets, patterns, conventions from compact/digest — paste actual code, don't reference files]
+
+Example existing pattern:
+\\\`\\\`\\\`typescript
+// From services/auth.service.ts — follow this pattern
+export class AuthService {
+  constructor(private readonly repo: AuthRepository) {}
+  async validate(token: string): Promise<User> { ... }
+}
+\\\`\\\`\\\`
+
+## 4. Constraints
+- Follow [specific pattern/convention]
+- Use [specific library/approach]
+- Do NOT [specific anti-pattern to avoid]
+- [Any other boundaries]
+
+## 5. FORGE Context
+**Tier:** [Floor | Standard | Critical]
+**Evidence requirements:** [What evidence to collect — test results, type coverage, etc.]
+
+## 6. Self-Review Checklist
+Before declaring your status, verify ALL:
+- [ ] All acceptance criteria from §2 are met
+- [ ] No files outside §1 scope were modified
+- [ ] Code follows conventions from §3 and constraints from §4
+- [ ] Tests pass (run them if possible)
+- [ ] No TODO/FIXME/HACK left without justification
+- [ ] No hardcoded values that should be configurable
+
+---
+
+**STATUS PROTOCOL — End your response with EXACTLY ONE:**
+
+### DONE
+All tasks complete. Self-review checklist passed. Ready for review.
+
+### DONE_WITH_CONCERNS
+All tasks complete, but I have concerns:
+- [Concern 1: description + suggested resolution]
+- [Concern 2: description + suggested resolution]
+
+### NEEDS_CONTEXT
+Cannot proceed without the following:
+- [Specific question or missing information]
+
+### BLOCKED
+Hit a wall and cannot proceed:
+- [Description of blocker]
+- [What I tried]
+- [Suggestion for resolution]
+\`\`\`
+
+---
+
+## Usage Notes
+
+- **Always paste actual code snippets** in §3 — use \`compact()\` or \`digest()\` to extract relevant context before crafting the prompt
+- **Keep scope tight** — 1-3 files maximum per dispatch
+- **Include failing test output** if dispatching a bug fix
+- **For Frontend agent**: add design requirements, responsive breakpoints, component hierarchy
+- **For Refactor agent**: include before/after expectations, what specifically to clean up
+`},{file:`parallel-dispatch-example.md`,content:`# Parallel Dispatch Worked Example
+
+This example shows how the Orchestrator decomposes a feature into parallel tasks, crafts context for each subagent, and manages the batch through review.
+
+---
+
+## Scenario: Add User Notification Preferences
+
+**User request:** "Add a notification preferences page where users can toggle email, push, and in-app notifications per category (marketing, security, product updates)."
+
+---
+
+## Step 1: Scope Map & Decomposition
+
+Orchestrator runs \`scope_map({ task: "notification preferences" })\` and identifies:
+
+| Area | Files | Agent |
+|------|-------|-------|
+| Backend API | \`services/notification-prefs.service.ts\`, \`routes/notification-prefs.route.ts\` | Implementer |
+| Database | \`migrations/add-notification-prefs.ts\`, \`models/notification-prefs.model.ts\` | Implementer |
+| Frontend Page | \`pages/settings/notifications.tsx\`, \`components/NotificationToggle.tsx\` | Frontend |
+| Tests | \`__tests__/notification-prefs.test.ts\` | Implementer |
+
+## Step 2: Independence Check (5-Question Checklist)
+
+| # | Question | Backend API + DB | Frontend Page |
+|---|----------|-----------------|---------------|
+| 1 | Same files? | \`services/\`, \`routes/\`, \`migrations/\`, \`models/\` | \`pages/\`, \`components/\` |
+| 2 | Shared state? | No — backend defines API contract | No — consumes API contract |
+| 3 | Execution order? | No — can define API while UI is built | No — can mock API response |
+| 4 | Shared new types? | Exports \`NotificationPrefs\` type | Imports same type |
+| 5 | Parallel-safe? | ✅ Yes — different directories | ✅ Yes — different directories |
+
+**Decision: PARALLEL** — But first define the shared type contract.
+
+## Step 3: Shared Context Prep
+
+Before dispatching, Orchestrator creates the shared contract:
+
+\`\`\`typescript
+// Type contract — paste into BOTH agent prompts
+interface NotificationPrefs {
+  userId: string;
+  categories: {
+    marketing: { email: boolean; push: boolean; inApp: boolean };
+    security: { email: boolean; push: boolean; inApp: boolean };
+    product: { email: boolean; push: boolean; inApp: boolean };
+  };
+  updatedAt: Date;
+}
+
+// API contract
+// GET  /api/notifications/preferences → NotificationPrefs
+// PUT  /api/notifications/preferences → NotificationPrefs (body: Partial<NotificationPrefs['categories']>)
+\`\`\`
+
+## Step 4: Parallel Dispatch
+
+### Dispatch A → Implementer (Backend + DB + Tests)
+
+\`\`\`markdown
+You are implementing a focused task. All context below.
+
+## 1. Scope
+- services/notification-prefs.service.ts — create
+- routes/notification-prefs.route.ts — create
+- migrations/add-notification-prefs.ts — create
+- models/notification-prefs.model.ts — create
+- __tests__/notification-prefs.test.ts — create
+
+## 2. Goal
+Create backend API for notification preferences CRUD.
+- GET endpoint returns current prefs (default all-true for new users)
+- PUT endpoint updates partial categories
+- Migration creates notification_preferences table
+
+## 3. Architectural Context
+[Paste existing service pattern from compact()]
+[Paste existing route pattern from compact()]
+[Paste existing migration pattern from compact()]
+[Paste the shared type contract above]
+
+## 4. Constraints
+- Follow existing repository pattern (see §3)
+- Use Zod for request validation
+- Include unit tests for service layer
+
+## 5. FORGE Context
+Tier: Standard. Evidence: test pass, type coverage.
+
+## 6. Self-Review Checklist
+[standard checklist]
+
+STATUS PROTOCOL: DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED
+\`\`\`
+
+### Dispatch B → Frontend (UI Page + Components)
+
+\`\`\`markdown
+You are implementing a focused task. All context below.
+
+## 1. Scope
+- pages/settings/notifications.tsx — create
+- components/NotificationToggle.tsx — create
+
+## 2. Goal
+Create notification preferences settings page.
+- Grid layout: rows = categories, columns = channels
+- Toggle switches for each cell
+- Auto-save on toggle (optimistic update with rollback)
+- Loading skeleton on initial fetch
+
+## 3. Architectural Context
+[Paste existing settings page pattern from compact()]
+[Paste existing toggle component from compact()]
+[Paste the shared type contract + API contract above]
+
+## 4. Constraints
+- Use existing Toggle component from design system
+- Follow settings page layout pattern
+- Mobile responsive (stack columns on small screens)
+- Mock API response for now: GET returns all-true defaults
+
+## 5. FORGE Context
+Tier: Floor. Evidence: renders without error.
+
+## 6. Self-Review Checklist
+[standard checklist]
+
+STATUS PROTOCOL: DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED
+\`\`\`
+
+## Step 5: Review Pipeline
+
+Both agents return DONE. Orchestrator runs review:
+
+1. **Spec Review** (Code-Reviewer-Alpha as spec reviewer):
+   - Backend: PASS — all acceptance criteria met
+   - Frontend: PASS_WITH_NOTES — missing keyboard accessibility on toggles
+
+2. **Code Quality Review** (Alpha + Beta in parallel):
+   - Alpha: APPROVE_WITH_SUGGESTIONS — extract validation schema to shared file
+   - Beta: APPROVE — clean implementation
+
+3. **Architecture Review** (not triggered — no boundary changes)
+
+4. **FORGE Gate**: \`evidence_map({ action: "gate" })\` → YIELD (all evidence collected)
+
+## Step 6: Commit
+
+\`\`\`
+feat: add notification preferences page
+
+- Backend: CRUD API for notification preferences per category
+- Frontend: Settings page with toggle grid, auto-save
+- Migration: notification_preferences table
+\`\`\`
+
+---
+
+## Key Takeaways
+
+1. **Define shared contracts FIRST** — paste into all agent prompts
+2. **Independence check takes 30 seconds** — prevents hours of merge conflicts
+3. **Each agent gets ONLY its files** — focused context = better output
+4. **Review is sequential** — spec first, then quality, then architecture (conditional)
+5. **FORGE gates at the end** — not between every step
+`},{file:`SKILL.md`,content:`---
 name: multi-agents-development
 description: "Comprehensive patterns for orchestrating multiple AI agents in parallel development workflows. Covers task decomposition, parallel dispatch, context crafting, status handling, review pipelines, and recovery."
 metadata:
@@ -8129,92 +6864,88 @@ Detailed prompt templates are provided as sidecar files:
 | Code quality review | [\`code-quality-review-prompt.md\`](code-quality-review-prompt.md) | Dual code quality review (Code-Reviewer-Beta) |
 | Architecture review | [\`architecture-review-prompt.md\`](architecture-review-prompt.md) | Boundary changes, pattern adherence review |
 | Parallel dispatch example | [\`parallel-dispatch-example.md\`](parallel-dispatch-example.md) | Worked example of decomposing a feature into parallel tasks |
-` },
-    { file: "spec-review-prompt.md", content: `# Spec Compliance Review Prompt Template
-
-Use this template when dispatching **Code-Reviewer-Alpha** for adversarial spec compliance review. This review runs BEFORE code quality review.
-
-**Mindset: "Don't trust the report."** The implementer says it's done — verify independently.
-
----
-
-## Prompt Template
-
-\`\`\`markdown
-You are performing an adversarial spec compliance review. Your job is to verify that the implementation matches what was requested — nothing more, nothing less.
-
-**Do NOT trust the implementer's self-assessment.** Verify independently.
-
-## Task Specification
-[Paste the original task that was dispatched to the implementer — including all acceptance criteria]
-
-## Implementation Output
-[Paste the implementer's response — code changes, self-review, status]
-
-## Files Changed
-[List of files modified with brief description of changes]
-
----
-
-## Review Dimensions
-
-### 1. Acceptance Criteria Match
-For EACH acceptance criterion in the task spec:
-- [ ] **Met** / **Not Met** / **Partially Met**
-- Evidence: [specific code or test that proves it]
-
-### 2. Over-Build Detection
-- Are there features, functions, or abstractions NOT requested in the spec?
-- Are there unnecessary generalizations?
-- Were files modified outside the stated scope?
-→ Flag each over-build with: what was added, why it shouldn't be there
-
-### 3. Under-Build Detection
-- Are any acceptance criteria unaddressed?
-- Are there edge cases implied by the spec but not handled?
-- Are there missing tests for stated requirements?
-→ Flag each under-build with: what's missing, what should exist
-
-### 4. Scope Compliance
-- List every file modified — does it match the scope in the original task?
-- Were any out-of-scope files touched? (this is a red flag)
-
-### 5. Contract Adherence
-- Do new exports/interfaces match what other components expect?
-- Are function signatures compatible with existing callers?
-- Will this break anything downstream?
-
----
-
-## Output Format
-
-### Verdict: [PASS | PASS_WITH_NOTES | FAIL]
-
-**PASS** — Implementation matches spec completely.
-**PASS_WITH_NOTES** — Matches spec but has minor concerns that don't block.
-**FAIL** — Implementation does not match spec. List specific gaps.
-
-### Findings:
-| # | Type | Severity | Description | Location |
-|---|------|----------|-------------|----------|
-| 1 | [Over/Under/Scope/Contract] | [Critical/Major/Minor] | [Description] | [file:line] |
-
-### Recommendation:
-[What needs to change before this passes spec review]
-\`\`\`
-
----
-
-## Usage Notes
-
-- Run this BEFORE code quality review — no point reviewing quality if spec is wrong
-- Paste the ORIGINAL task spec, not a summary — the reviewer needs exact acceptance criteria
-- If verdict is FAIL, bounce back to implementer with specific gaps before proceeding
-- PASS_WITH_NOTES can proceed to code quality review, but notes should be tracked
-` },
-  ],
-  "present": [
-    { file: "SKILL.md", content: `---
+`},{file:`spec-review-prompt.md`,content:`# Spec Compliance Review Prompt Template
+
+Use this template when dispatching **Code-Reviewer-Alpha** for adversarial spec compliance review. This review runs BEFORE code quality review.
+
+**Mindset: "Don't trust the report."** The implementer says it's done — verify independently.
+
+---
+
+## Prompt Template
+
+\`\`\`markdown
+You are performing an adversarial spec compliance review. Your job is to verify that the implementation matches what was requested — nothing more, nothing less.
+
+**Do NOT trust the implementer's self-assessment.** Verify independently.
+
+## Task Specification
+[Paste the original task that was dispatched to the implementer — including all acceptance criteria]
+
+## Implementation Output
+[Paste the implementer's response — code changes, self-review, status]
+
+## Files Changed
+[List of files modified with brief description of changes]
+
+---
+
+## Review Dimensions
+
+### 1. Acceptance Criteria Match
+For EACH acceptance criterion in the task spec:
+- [ ] **Met** / **Not Met** / **Partially Met**
+- Evidence: [specific code or test that proves it]
+
+### 2. Over-Build Detection
+- Are there features, functions, or abstractions NOT requested in the spec?
+- Are there unnecessary generalizations?
+- Were files modified outside the stated scope?
+→ Flag each over-build with: what was added, why it shouldn't be there
+
+### 3. Under-Build Detection
+- Are any acceptance criteria unaddressed?
+- Are there edge cases implied by the spec but not handled?
+- Are there missing tests for stated requirements?
+→ Flag each under-build with: what's missing, what should exist
+
+### 4. Scope Compliance
+- List every file modified — does it match the scope in the original task?
+- Were any out-of-scope files touched? (this is a red flag)
+
+### 5. Contract Adherence
+- Do new exports/interfaces match what other components expect?
+- Are function signatures compatible with existing callers?
+- Will this break anything downstream?
+
+---
+
+## Output Format
+
+### Verdict: [PASS | PASS_WITH_NOTES | FAIL]
+
+**PASS** — Implementation matches spec completely.
+**PASS_WITH_NOTES** — Matches spec but has minor concerns that don't block.
+**FAIL** — Implementation does not match spec. List specific gaps.
+
+### Findings:
+| # | Type | Severity | Description | Location |
+|---|------|----------|-------------|----------|
+| 1 | [Over/Under/Scope/Contract] | [Critical/Major/Minor] | [Description] | [file:line] |
+
+### Recommendation:
+[What needs to change before this passes spec review]
+\`\`\`
+
+---
+
+## Usage Notes
+
+- Run this BEFORE code quality review — no point reviewing quality if spec is wrong
+- Paste the ORIGINAL task spec, not a summary — the reviewer needs exact acceptance criteria
+- If verdict is FAIL, bounce back to implementer with specific gaps before proceeding
+- PASS_WITH_NOTES can proceed to code quality review, but notes should be tracked
+`}],present:[{file:`SKILL.md`,content:`---
 name: present
 description: "Use the AI Kit \`present\` tool to display rich interactive dashboards, charts, timelines, status boards, and data visualizations in the browser or in-chat. Covers all block types, chart types, actions, composition patterns, and MCP Apps templates (list-sort, data-table, picker, flame-graph, form, timeline, kanban, tree, diff-view, dashboard). Load this skill before calling the present tool to ensure professional output."
 metadata:
@@ -8830,10 +7561,7 @@ Metric types: \`'stat'\` (default), \`'progress'\` (with bar), \`'list'\` (sub-i
 | tree | Display only | — |
 | diff-view | Display only | — |
 | dashboard | Display only | — |
-` },
-  ],
-  "react": [
-    { file: "SKILL.md", content: `---
+`}],react:[{file:`SKILL.md`,content:`---
 name: react
 description: "Comprehensive React development patterns — component architecture, React 19 APIs, Server Components, TypeScript integration, and performance optimization."
 metadata:
@@ -9142,448 +7870,7 @@ When implementing a React feature:
 5. **Loading?** → \`<Suspense>\` with skeleton fallback.
 6. **Performance?** → Try React Compiler first. Then manual memo. Then virtualization. Then code splitting.
 7. **Error?** → Error boundaries for rendering errors. try/catch for Server Actions.
-` },
-  ],
-  "repo-access": [
-    { file: "references/error-patterns.md", content: `# Repo Access Error Patterns
-
-Use this reference to distinguish missing repositories from authentication and policy failures when probing Git hosts.
-
-## HTTP Status Code Matrix
-
-| Platform | No auth (private repo) | Wrong credentials | Rate limited | SSO required |
-|---|---|---|---|---|
-| GitHub REST API | \`404\` (TRAP!) | \`401\` -> \`403\` | \`403\` + rate limit body | \`403\` + \`X-GitHub-SSO\` header |
-| GitHub Web | HTML "Page not found" or login redirect | Login redirect | - | - |
-| GitLab | \`401\` | \`401\` | \`429\` | \`401\` (PAT mandatory) |
-| Bitbucket | \`403\` | \`403\` | \`429\` | \`403\` |
-| Azure DevOps | \`401\` | \`401\` | - | \`401\` |
-
-## CRITICAL: The GitHub 404 Trap
-
-GitHub deliberately returns \`404\`, not \`401\`, for private repositories accessed without authentication.
-This is by design to avoid leaking whether a repository exists.
-
-- Never conclude a GitHub repository does not exist from an unauthenticated \`404\`.
-- \`GET https://api.github.com/repos/{owner}/{repo}\` without auth returns \`404\` for both "repo truly missing" and "repo exists but is private".
-- The only reliable disambiguation is an authenticated probe.
-- If the same request still returns \`404\` with valid auth, the repository is truly missing.
-
-Probe order:
-
-1. Try the authenticated API request first.
-2. If it returns \`200\`, access works.
-3. If it returns \`404\` without auth context, treat it as ambiguous and recover.
-4. If it returns \`404\` with known-good auth, treat the repo as missing.
-
-## Git CLI Stderr Patterns
-
-| Error Text Pattern | Platform | Diagnosis | Action |
-|---|---|---|---|
-| \`remote: Repository not found.\` | GitHub | Auth failure, not proof the repo is missing | Try auth strategies |
-| \`git@github.com: Permission denied (publickey).\` | GitHub | SSH key not recognized | Check SSH keys, try HTTPS |
-| \`remote: HTTP Basic: Access denied.\` | GitLab | Auth failure, 2FA likely | Use PAT; password auth is blocked with 2FA |
-| \`error: The requested URL returned error: 403\` | Bitbucket | Auth failure | Try app password |
-| \`TF401019: The Git repository with name or identifier X does not exist\` | Azure DevOps | Auth failure or missing repo | Try PAT with Code:Read scope |
-| \`fatal: Authentication failed for 'https://...'\` | Any (HTTPS) | General auth failure | Escalate through the strategy ladder |
-| \`Permission denied (publickey).\` | Any (SSH) | SSH key not recognized | Check \`~/.ssh/\`, run \`ssh-add\`, try HTTPS |
-| \`fatal: Could not read from remote repository.\` | Any (SSH) | SSH access denied | Verify the SSH key is added to the platform |
-| \`unable to access '...': SSL certificate problem\` | Any | Self-signed or enterprise CA issue | Ask about local cert config; skip to local clone if needed |
-
-Treat these stderr strings as direct signals from tool output. Do not reinterpret GitHub's \`Repository not found\` as a clean existence check.
-
-## web_fetch / http Tool Detection
-
-- \`web_fetch\` against a private GitHub repo URL often returns HTML with "Page not found" or a login page.
-- GitHub web responses can be \`200\` with a 404-looking body, so \`web_fetch\` is unreliable for auth diagnosis.
-- \`http\` against the platform API gives machine-readable bodies and real status codes, so use it for probes.
-- For \`web_fetch\` on \`github.com\`, inspect the body for \`Page not found\`, \`Sign in\`, or \`/login\` links. If present, assume private or auth-gated access and trigger recovery.
-
-Recommended diagnostic probe:
-
-\`\`\`text
-http GET https://api.github.com/repos/{owner}/{repo}
--> 404 + no auth header -> might be private
--> 401 -> explicit auth failure
--> 200 -> repo is public, access works
-\`\`\`
-
-## Edge Cases
-
-| Edge Case | Signal | Response |
-|---|---|---|
-| GitHub.com SAML SSO | \`403\` + \`X-GitHub-SSO: required; url=...\` | PAT needs SSO authorization for the org |
-| GHE SAML SSO (web_fetch) | \`200\` + body contains \`Initiating SAML single sign-on\`, redirect to \`login.microsoftonline.com\` or other IdP | Repo EXISTS and is auth-gated. NOT inaccessible. Use PAT + \`http\` with auth headers, or \`gh auth login --hostname <host>\` |
-| GHE SAML SSO (http) | \`302\` redirect to \`/login?return_to=...\` or IdP URL | Same — repo exists, needs auth. Walk the Strategy Ladder |
-| GHE SAML SSO (git CLI) | \`fatal: Authentication failed\` or credential prompt | \`gh auth login --hostname <host>\` or PAT via credential helper |
-
-## SAML SSO — Detailed Pattern
-
-GitHub Enterprise instances commonly use SAML SSO via Azure AD (Entra ID), Okta, or other IdPs. When \`web_fetch\` hits a GHE URL without auth:
-
-1. GHE returns \`200 OK\` (not 401/403!) with an HTML page
-2. The HTML contains \`Initiating SAML single sign-on\` and a redirect URL to the IdP
-3. The redirect URL includes \`SAMLRequest=\`, \`RelayState=\`, and often \`login.microsoftonline.com\`
-4. The agent sees HTML content and may conclude the repo is "inaccessible" or "behind SSO"
-
-**Detection strings** (check \`web_fetch\` output for ANY of these):
-\`\`\`
-Initiating SAML single sign-on
-login.microsoftonline.com
-You are being redirected to your identity provider
-/login?return_to=
-SAMLRequest=
-RelayState=
-\`\`\`
-
-**Correct response:** The repo exists. The \`web_fetch\` path will never work for SSO-protected GHE. Switch to:
-- \`gh auth login --hostname <ghe-host>\` (if \`gh\` CLI available)
-- PAT + \`http\` with \`Authorization: token <PAT>\` against \`<ghe-host>/api/v3/repos/{owner}/{repo}/contents/{path}\`
-- Ask user for local clone if no token can be obtained
-| GitLab 2FA enabled | \`401\` on password auth | PAT is mandatory; 2FA blocks password auth |
-| Expired token | \`401\` after providing a valid-looking PAT | Generate a new token and check expiry |
-| GitHub rate limit | \`403\` + body contains \`rate limit\` | Not an auth failure; wait or authenticate for a higher limit |
-| IP allowlisting | \`403\` + body mentions IP or org policies | Cannot be fixed programmatically; skip to local clone (Step 5) |
-| Fine-grained PAT scope | \`403\` + \`insufficient scope\` | Switch to a classic PAT for org repos |
-| SSH key not in agent | \`Permission denied (publickey)\` + key file exists | Run \`ssh-add ~/.ssh/id_ed25519\` |
-| Wrong SSH username | \`Permission denied\` | Use \`git@host\`, not \`username@host\` |
-| Deploy key conflict | \`key is already in use\` | Use a user SSH key or PAT instead |
-
-## Escalation Decision Rules
-
-- Retry the same step for transient failures such as DNS failure, timeout, or \`5xx\` responses.
-- Escalate to the next strategy step for \`401\`, \`403\`, \`404\`, \`Permission denied\`, \`Authentication failed\`, or \`Access denied\`.
-- Skip directly to Step 5 (local clone) for IP allowlisting, enterprise SSL certificate issues, or org policy blocks.
-
-Default interpretation order:
-
-1. Prefer API probes over web page fetches.
-2. Treat GitHub \`404\` as ambiguous until valid auth disproves privacy.
-3. Treat SSH \`publickey\` errors as key-distribution failures, not repo absence.
-4. Separate rate limits and org policy blocks from authentication failures before escalating.` },
-    { file: "references/platform-matrix.md", content: `# Platform Matrix
-
-Use this reference when a repository URL reveals the hosting platform and the skill needs platform-specific authentication or cloning guidance. Prefer platform CLI login flows or OS-backed credential helpers over raw PAT handling.
-
-## Platform Detection
-
-| URL Pattern | Platform | CLI Tool (optional) | Auth Command | No-CLI Alternative |
-|---|---|---|---|---|
-| \`github.com\` | GitHub | \`gh\` | \`gh auth login\` | PAT + \`http\` with \`Authorization: token <PAT>\` |
-| Any custom domain (e.g. \`ghe.corp.com\`, \`github.corp.com\`) | GitHub Enterprise | \`gh\` | \`gh auth login --hostname <host>\` | PAT + \`http\` against \`<host>/api/v3\` |
-| \`gitlab.com\` | GitLab | \`glab\` | \`glab auth login\` | PAT + \`http\` with \`PRIVATE-TOKEN\` header |
-| Self-hosted GitLab | GitLab Self-Managed | \`glab\` | \`glab auth login --hostname <host>\` | PAT + \`http\` with \`PRIVATE-TOKEN\` header |
-| \`bitbucket.org\` | Bitbucket Cloud | None | N/A | App password + \`http\` with \`Authorization: Bearer\` |
-| \`dev.azure.com\` or \`*.visualstudio.com\` | Azure DevOps | \`az\` + GCM | \`az login\` | PAT + \`http\` with Basic auth |
-| Gitea instances | Gitea | \`tea\` (optional) | \`tea login add\` | PAT + \`http\` with \`Authorization: token\` |
-| Unknown or custom domain | Ask user which platform | N/A | N/A | Probe \`http\` or ask before assuming generic Git |
-
-> **Note:** Platform CLIs (\`gh\`, \`glab\`, \`az\`, \`tea\`) are native binaries, not npm packages. Do NOT use \`npx\` to install them — it will fail or install unrelated/unofficial packages. When the CLI is unavailable, use the No-CLI Alternative column.
-
-## GitHub / GitHub Enterprise
-
-- CLI: \`gh auth login\` uses a browser or device code flow and can open the browser automatically.
-- GitHub Enterprise CLI: \`gh auth login --hostname <host>\`.
-- PAT creation: \`https://github.com/settings/tokens\` for classic tokens.
-- PAT creation: \`https://github.com/settings/personal-access-tokens\` for fine-grained tokens.
-- Minimum scopes: \`repo\` for classic PATs (NOTE: \`repo\` grants read and write — prefer fine-grained PATs with \`Contents: Read\` for read-only access).
-- Minimum scopes: \`Contents: Read\` for fine-grained PATs.
-- SSH: \`git@github.com:owner/repo.git\`.
-- Credential helper: \`gh auth setup-git\` configures Git to use the GitHub credential flow.
-- Note: Fine-grained PATs may not cover organization-level access or every repo path; classic PATs are still required for some org repos.
-- SAML SSO: PATs often require explicit org authorization from \`https://github.com/settings/tokens\` after creation.
-- Enterprise note: PAT URLs and token policy can vary by host; reuse the same auth pattern with the enterprise hostname and instance settings pages.
-- Enterprise detection: GHE instances use fully custom domains (e.g. \`ghe.coxautoinc.com\`, \`github.acme.com\`). If unsure, probe \`https://<host>/api/v3\` — a GitHub Enterprise instance returns a JSON response with \`installed_version\`. Use \`gh auth login --hostname <host>\` with any custom GHE domain.
-
-## GitLab / GitLab Self-Managed
-
-- CLI: \`glab auth login\` uses a browser-backed OAuth flow.
-- Self-managed CLI: \`glab auth login --hostname <host>\`.
-- PAT creation: \`https://gitlab.com/-/user_settings/personal_access_tokens\`.
-- Minimum scopes: \`read_repository\`.
-- SSH: \`git@gitlab.com:owner/repo.git\`.
-- Credential helper: \`glab auth setup-git\` configures Git credential handling.
-- Note: If 2FA is enabled, username/password Git auth is blocked; a PAT is mandatory for HTTPS auth.
-- Self-managed note: PAT URL is typically \`https://<host>/-/user_settings/personal_access_tokens\` unless the instance customizes settings paths.
-
-## Bitbucket Cloud
-
-- CLI: No official first-party CLI OAuth flow for repo auth.
-- PAT/App Password creation: \`https://bitbucket.org/{workspace}/settings/app-passwords\`.
-- Minimum permissions: \`Repositories: Read\`.
-- SSH: \`git@bitbucket.org:owner/repo.git\`.
-- Note: Bitbucket Cloud uses App Passwords rather than standard PAT terminology.
-- Note: HTTPS auth requires both the Bitbucket username and the app password, delivered through a credential helper or \`GIT_ASKPASS\` script — never embedded in the clone URL.
-
-## Azure DevOps
-
-- CLI: \`az login\` authenticates to Microsoft Entra ID; Git Credential Manager then handles Git credentials automatically.
-- PAT-based auth remains the fallback when Entra ID or GCM is unavailable.
-- PAT creation: \`https://dev.azure.com/{org}/_usersSettings/tokens\`.
-- Minimum scopes: \`Code: Read\`.
-- SSH: \`git@ssh.dev.azure.com:v3/{org}/{project}/{repo}\`.
-- Note: Microsoft Entra ID tokens are generally preferred over PATs in enterprise environments.
-- Credential helper: Git Credential Manager via \`git-credential-manager configure\`.
-- Legacy host note: Azure DevOps may also appear under \`*.visualstudio.com\` URLs.
-
-## Gitea / Forgejo
-
-- CLI: \`tea login add\` is available but optional and not universally installed.
-- PAT creation: \`https://{host}/user/settings/applications\`.
-- Minimum scopes: \`repo\`.
-- SSH: \`git@{host}:owner/repo.git\`.
-- Note: Forgejo commonly mirrors the same applications-token path and PAT model as Gitea.
-- Note: Some self-hosted instances rename scopes or disable API token creation, so confirm the instance policy if \`repo\` is rejected.
-
-## Generic Git (Self-Hosted)
-
-- Platform CLI: None assumed.
-- Auth path: Prefer SSH keys first, then PAT if the host documents HTTPS token auth.
-- PAT creation: Ask the user for the platform's PAT or application-token settings URL.
-- SSH: Use the host's documented SSH remote format; do not assume GitHub-style shortcuts if the server advertises a different pattern.
-
-## API File-Read Endpoints (for web-based code access)
-
-When agents need to read individual files without cloning, use these authenticated API endpoints.
-
-### GitHub / GitHub Enterprise
-
-\`\`\`text
-# Read file contents (returns JSON with base64 content)
-GET https://api.github.com/repos/{owner}/{repo}/contents/{path}?ref={branch}
-Authorization: token <PAT>
-
-# GHE: replace api.github.com with <ghe-host>/api/v3
-GET https://<ghe-host>/api/v3/repos/{owner}/{repo}/contents/{path}?ref={branch}
-
-# Or use gh CLI (auto-authenticated):
-gh api repos/{owner}/{repo}/contents/{path}?ref={branch} --jq '.content' | base64 -d
-\`\`\`
-
-### GitLab / GitLab Self-Managed
-
-\`\`\`text
-# URL-encode the file path (/ becomes %2F)
-GET https://gitlab.com/api/v4/projects/{project-id}/repository/files/{url-encoded-path}/raw?ref={branch}
-PRIVATE-TOKEN: <PAT>
-
-# Or use project path instead of ID:
-GET https://gitlab.com/api/v4/projects/{url-encoded-namespace%2Fproject}/repository/files/{url-encoded-path}/raw?ref={branch}
-\`\`\`
-
-### Azure DevOps
-
-\`\`\`text
-GET https://dev.azure.com/{org}/{project}/_apis/git/repositories/{repo}/items?path={path}&api-version=7.0
-Authorization: Basic {base64(:PAT)}
-\`\`\`
-
-### Bitbucket Cloud
-
-\`\`\`text
-GET https://api.bitbucket.org/2.0/repositories/{workspace}/{repo}/src/{commit-or-branch}/{path}
-Authorization: Bearer <app-password-or-token>
-\`\`\`
-- Note: Self-hosted products often customize auth policy, token names, and minimum scopes.
-
-## Safe Credential Delivery Patterns
-
-| Method | Command | Safety |
-|---|---|---|
-| Platform CLI | \`gh auth login\` / \`glab auth login\` | Best — handles credential storage |
-| Git Credential Manager | \`git credential-manager configure\` | Good — OS keychain storage |
-| Environment variable | \`GH_TOKEN=xxx gh repo clone ...\` | OK — ephemeral; safer than URL tokens but visible to same-user processes |
-| Git askpass | \`GIT_ASKPASS=script git clone ...\` | OK — no shell history exposure |
-| Inline in URL | \`git clone https://token@host/...\` | FORBIDDEN — leaks in history/logs |
-
-## Operational Notes
-
-- Prefer SSH when the user already has working keys and the host advertises a stable SSH remote format.
-- Prefer platform CLI login for GitHub and GitLab because it also wires Git credential storage.
-- Prefer Git Credential Manager for Azure DevOps and other HTTPS-heavy enterprise setups.
-- When recommending PAT creation, always suggest setting a short expiry (7-30 days for task-specific work). Prefer fine-grained or short-lived tokens.
-- Never recommend pasting tokens inline into clone URLs, scripts checked into the repo, or long-lived shell profiles.` },
-    { file: "SKILL.md", content: `---
-name: repo-access
-description: "Progressive repository access recovery for private and enterprise git repositories. Triggered when: (1) git clone/fetch/pull fails with auth errors (401, 403, 404, Permission denied), (2) web_fetch or http tool returns auth failure on repository URLs, (3) user mentions private repo, enterprise repo, or internal repo, (4) user asks to access code from GitHub Enterprise, GitLab Self-Managed, Bitbucket Server, Azure DevOps. Guides through 5-step progressive strategy: anonymous HTTPS, SSH keys, CLI OAuth, PAT, local clone fallback."
-metadata:
-  category: cross-cutting
-  domain: general
-  applicability: on-demand
-  inputs: [git-error, repository-url, platform-context]
-  outputs: [authenticated-access, recovery-instructions]
-  requires: []
-  relatedSkills: [aikit]
-argument-hint: "Repository URL or error message"
----
-
-# Repository Access Recovery
-
-Progressively recover repository access for private, enterprise, and internal git hosts without leaking credentials.
-
-## When to Activate
-
-### Reactive triggers
-
-- \`git clone\`, \`git fetch\`, or \`git pull\` fails with \`401\`, \`403\`, \`404\`, \`Authentication failed\`, or \`Permission denied (publickey)\`.
-- \`http\` diagnostics against a repo endpoint show auth failure or ambiguous private-repo responses.
-- \`web_fetch\` returns login page HTML, SSO redirect, "Sign in", "Page not found", or empty/truncated content for a repo URL.
-- Any tool output contains "behind SSO", "SSO required", "SAML", "requires authentication", or similar auth-gate language about a repository.
-- A repository URL works in a browser for the user but fails from agent tools or terminal commands.
-- **You are about to declare a repo "inaccessible" or "unreachable"** — STOP and activate this skill first.
-
-### Proactive triggers
-
-- The user says the repo is private, enterprise, self-managed, internal, or SSO-protected.
-- The repo is hosted on GitHub Enterprise, GitLab Self-Managed, Bitbucket Server/Data Center, Azure DevOps, Gitea, or another custom git host.
-- The environment may need browser sign-in, SSH agent setup, or token-based recovery before any code access can work.
-
-## When NOT to Activate
-
-- Public repositories that already clone or read successfully over HTTPS.
-- Local-only repositories where no remote auth is involved.
-- Problems caused by branch protection, merge conflicts, or rate limiting rather than repository access.
-
-## Step 0: Platform Detection & Capability Gate
-
-Detect platform from the URL, then decide what recovery options are possible in this environment.
-
-| URL pattern | Platform |
-| --- | --- |
-| \`github.com\`, or any GHE host (e.g. \`ghe.*\`, \`github.*\`, custom domain) | GitHub / GitHub Enterprise |
-| \`gitlab.com\`, \`gitlab.<corp-host>\` | GitLab / GitLab Self-Managed |
-| \`bitbucket.org\`, \`bitbucket.<corp-host>\` | Bitbucket Cloud / Server |
-| \`dev.azure.com\`, \`visualstudio.com\`, \`/_git/\` | Azure DevOps |
-| anything else with git over HTTPS/SSH | Unknown — ask the user which platform before assuming generic Git |
-
-- Capability gate: has terminal, has browser, or conversation-only.
-- If terminal is unavailable, skip directly to PAT guidance or local clone fallback.
-- If browser is unavailable, prefer SSH or pre-created credentials over CLI OAuth.
-- If only the \`http\` tool is available (no terminal, no CLI): use PAT + authenticated API reads (see "Web-Based Code Access" below). This is the zero-dependency path — no \`gh\`, \`glab\`, or \`az\` installation needed.
-
-For platform-specific details, read \`references/platform-matrix.md\`.
-
-## Strategy Ladder
-
-### Step 1: Try HTTPS Anonymous Access
-
-- Goal: prove the repo is public or already reachable without extra auth.
-- What to do: normalize the remote to an HTTPS URL and run \`git ls-remote https://...\`. If it succeeds, use HTTPS and stop. If it fails with auth-like errors, continue instead of assuming the repo is missing.
-- Verify: \`git ls-remote <url>\`; SUCCESS -> stop, FAIL -> Step 2.
-
-### Step 2: Check Existing SSH Keys
-
-- Goal: reuse working SSH credentials before asking for new secrets.
-- What to do: inspect \`~/.ssh/\` for key files, run \`ssh-add -l\`, then test host auth with \`ssh -T git@{host}\`. If SSH works, switch the remote to the SSH URL and continue with that transport.
-- Verify: \`git ls-remote <ssh-url>\`; SUCCESS -> stop, FAIL -> Step 3.
-
-### Step 3: Platform CLI OAuth
-
-- Goal: use the platform's interactive login flow with stored credentials.
-- What to do: check whether the matching CLI exists, for example \`which gh\`, \`which glab\`, or \`which az\` (or platform equivalent). If installed, run \`{cli} auth login\` and let it complete browser or device OAuth, then retry git access.
-- **If the CLI is not installed**: do NOT try \`npx\` — platform CLIs (\`gh\`, \`glab\`, \`az\`) are native binaries, not npm packages. Skip straight to Step 4 (PAT). For file-read-only tasks, the \`http\` tool with a PAT header is a zero-dependency alternative to any CLI.
-- Verify: \`git ls-remote <url>\`; SUCCESS -> stop, FAIL -> Step 4.
-
-### Step 4: Personal Access Token
-
-- Goal: recover access when SSH and CLI OAuth are unavailable or blocked.
-- What to do: ask the user to create a PAT or app password at the platform-specific URL with minimum read scopes only. Have the user provide it through an env var or credential helper, then configure git credentials without embedding the token in the remote URL.
-- Verify: \`git ls-remote <url>\`; SUCCESS -> stop, FAIL -> Step 5.
-
-### Step 5: Local Clone Fallback
-
-- Goal: unblock work when remote auth cannot be completed from the current environment.
-- What to do: ask the user to clone the repository on their machine using their normal workflow, then provide the local filesystem path. Use the local checkout as the source of truth for code access.
-- Verify: local repo exists and \`git rev-parse --show-toplevel\` succeeds; SUCCESS -> stop.
-
-## Security Rules (HARD GATE)
-
-- NEVER include a PAT in a git URL; it leaks into shell history, process lists, logs, and config.
-- NEVER repeat a user's token value in chat output, summaries, examples, or when relaying tool output that may contain credentials.
-- Use env vars, credential helpers, or platform login tools for token delivery.
-- Recommend minimum scopes only: read-only repo scopes, not broad write/admin scopes.
-- Prefer ephemeral credentials, OAuth/device flows, or short-lived tokens over long-lived PATs.
-- When guiding PAT creation, recommend the shortest feasible expiry (7–30 days for task-specific work).
-
-## After Access Is Established
-
-- Remind the user to revoke single-use PATs once the task is complete.
-- If credentials were stored via a credential helper, note that they persist until manually removed or the token expires.
-
-## Web-Based Code Access (web_fetch / http)
-
-Agents often use \`web_fetch\` or \`http\` to read individual files without a full clone. These requests fail silently on private repos — GitHub returns \`404\` or login HTML, not an auth error.
-
-### Common URL Patterns That Fail on Private Repos
-
-| URL Pattern | Platform | What Happens |
-|---|---|---|
-| \`raw.githubusercontent.com/{owner}/{repo}/{ref}/{path}\` | GitHub | \`404\` — no auth header accepted |
-| \`github.com/{owner}/{repo}/blob/{ref}/{path}\` | GitHub web view | \`200\` with login HTML, not code |
-| \`api.github.com/repos/{owner}/{repo}/contents/{path}\` | GitHub API | \`404\` (the GitHub 404 trap) |
-| \`<ghe-host>/{owner}/{repo}/*\` (any GHE URL) | GitHub Enterprise | \`200\` with SAML SSO redirect page — body contains "Initiating SAML single sign-on" and redirect to \`login.microsoftonline.com\` or other IdP |
-| \`gitlab.com/{owner}/{repo}/-/raw/{ref}/{path}\` | GitLab | \`401\` or login redirect |
-| \`dev.azure.com/{org}/{project}/_apis/git/repositories/{repo}/items\` | Azure DevOps | \`401\` or \`203\` non-authoritative |
-
-### SAML SSO Detection (CRITICAL)
-
-GHE instances with SAML SSO return \`200 OK\` with an HTML body that is NOT the requested content. **This is the most common false-"inaccessible" scenario.** Detect it by checking \`web_fetch\` output for ANY of these strings:
-
-- \`Initiating SAML single sign-on\`
-- \`login.microsoftonline.com\` (Azure AD / Entra ID)
-- \`You are being redirected to your identity provider\`
-- \`/login?return_to=\`
-- \`SAMLRequest=\`
-- \`RelayState=\`
-
-If ANY of these appear → the repo exists and is accessible, it just needs authentication. This is NOT "inaccessible" — follow the Strategy Ladder.
-
-### Recovery: Authenticated API Reads
-
-When \`web_fetch\` fails on a private repo URL, switch to authenticated \`http\` calls:
-
-1. **Ensure auth is established first** — walk the Strategy Ladder (Steps 1-4) to get working credentials.
-2. **Use the platform API with auth headers**, not raw/web URLs:
-
-| Platform | Authenticated file-read endpoint | Auth header |
-|---|---|---|
-| GitHub / GHE | \`http GET https://api.github.com/repos/{owner}/{repo}/contents/{path}?ref={branch}\` | \`Authorization: token <PAT>\` or use \`gh api\` |
-| GitLab | \`http GET https://gitlab.com/api/v4/projects/{id}/repository/files/{path}/raw?ref={branch}\` | \`PRIVATE-TOKEN: <PAT>\` |
-| Azure DevOps | \`http GET https://dev.azure.com/{org}/{project}/_apis/git/repositories/{repo}/items?path={path}&api-version=7.0\` | \`Authorization: Basic <base64(:PAT)>\` |
-| Bitbucket | \`http GET https://api.bitbucket.org/2.0/repositories/{owner}/{repo}/src/{ref}/{path}\` | \`Authorization: Bearer <token>\` |
-
-3. **Prefer \`http\` over \`web_fetch\`** for private repos — \`http\` sends proper headers and returns machine-readable JSON; \`web_fetch\` gets HTML login pages.
-4. **For bulk reads**, prefer \`git clone --depth 1\` over many individual API calls — it's faster and avoids rate limits.
-5. **NEVER embed tokens in URLs** — use auth headers via the \`http\` tool or \`gh api\` CLI wrapper.
-
-### Quick Decision: Clone vs API Read
-
-| Situation | Preferred method |
-|---|---|
-| Need 1-3 specific files | Authenticated API via \`http\` |
-| Need to browse/search the repo | \`git clone --depth 1\` (shallow) |
-| Need file history or blame | \`git clone\` |
-| No terminal available | Authenticated API via \`http\` with PAT |
-| Rate-limited on API | \`git clone --depth 1\` |
-
-## Tool Routing
-
-| Tool | Use |
-| --- | --- |
-| \`git_context\` | Check local repo state and confirm a clone or fallback checkout is usable |
-| \`http\` | Probe platform APIs for auth diagnostics AND read file contents from private repos with auth headers |
-| \`web_fetch\` | Only for public repos or after confirming access works; unreliable for private repos (returns HTML, not code) |
-| \`web_search\` | Find current platform-specific auth documentation when the host is unusual or self-managed |
-| Terminal | Run git commands, SSH tests, CLI auth flows, and credential-helper setup |
-
-For detailed error patterns, read \`references/error-patterns.md\`.
-
-## CRITICAL: The GitHub 404 Trap
-
-GitHub commonly returns \`404 Not Found\` for private repositories when the caller is unauthenticated or under-authenticated. NEVER conclude that a GitHub repository does not exist from a \`404\` alone. Treat that response as an authentication signal first, then walk the ladder before declaring the repo missing.` },
-  ],
-  "requirements-clarity": [
-    { file: "SKILL.md", content: `---
+`}],"repo-access":[{file:`references/error-patterns.md`,content:'# Repo Access Error Patterns\n\nUse this reference to distinguish missing repositories from authentication and policy failures when probing Git hosts.\n\n## HTTP Status Code Matrix\n\n| Platform | No auth (private repo) | Wrong credentials | Rate limited | SSO required |\n|---|---|---|---|---|\n| GitHub REST API | `404` (TRAP!) | `401` -> `403` | `403` + rate limit body | `403` + `X-GitHub-SSO` header |\n| GitHub Web | HTML "Page not found" or login redirect | Login redirect | - | - |\n| GitLab | `401` | `401` | `429` | `401` (PAT mandatory) |\n| Bitbucket | `403` | `403` | `429` | `403` |\n| Azure DevOps | `401` | `401` | - | `401` |\n\n## CRITICAL: The GitHub 404 Trap\n\nGitHub deliberately returns `404`, not `401`, for private repositories accessed without authentication.\nThis is by design to avoid leaking whether a repository exists.\n\n- Never conclude a GitHub repository does not exist from an unauthenticated `404`.\n- `GET https://api.github.com/repos/{owner}/{repo}` without auth returns `404` for both "repo truly missing" and "repo exists but is private".\n- The only reliable disambiguation is an authenticated probe.\n- If the same request still returns `404` with valid auth, the repository is truly missing.\n\nProbe order:\n\n1. Try the authenticated API request first.\n2. If it returns `200`, access works.\n3. If it returns `404` without auth context, treat it as ambiguous and recover.\n4. If it returns `404` with known-good auth, treat the repo as missing.\n\n## Git CLI Stderr Patterns\n\n| Error Text Pattern | Platform | Diagnosis | Action |\n|---|---|---|---|\n| `remote: Repository not found.` | GitHub | Auth failure, not proof the repo is missing | Try auth strategies |\n| `git@github.com: Permission denied (publickey).` | GitHub | SSH key not recognized | Check SSH keys, try HTTPS |\n| `remote: HTTP Basic: Access denied.` | GitLab | Auth failure, 2FA likely | Use PAT; password auth is blocked with 2FA |\n| `error: The requested URL returned error: 403` | Bitbucket | Auth failure | Try app password |\n| `TF401019: The Git repository with name or identifier X does not exist` | Azure DevOps | Auth failure or missing repo | Try PAT with Code:Read scope |\n| `fatal: Authentication failed for \'https://...\'` | Any (HTTPS) | General auth failure | Escalate through the strategy ladder |\n| `Permission denied (publickey).` | Any (SSH) | SSH key not recognized | Check `~/.ssh/`, run `ssh-add`, try HTTPS |\n| `fatal: Could not read from remote repository.` | Any (SSH) | SSH access denied | Verify the SSH key is added to the platform |\n| `unable to access \'...\': SSL certificate problem` | Any | Self-signed or enterprise CA issue | Ask about local cert config; skip to local clone if needed |\n\nTreat these stderr strings as direct signals from tool output. Do not reinterpret GitHub\'s `Repository not found` as a clean existence check.\n\n## web_fetch / http Tool Detection\n\n- `web_fetch` against a private GitHub repo URL often returns HTML with "Page not found" or a login page.\n- GitHub web responses can be `200` with a 404-looking body, so `web_fetch` is unreliable for auth diagnosis.\n- `http` against the platform API gives machine-readable bodies and real status codes, so use it for probes.\n- For `web_fetch` on `github.com`, inspect the body for `Page not found`, `Sign in`, or `/login` links. If present, assume private or auth-gated access and trigger recovery.\n\nRecommended diagnostic probe:\n\n```text\nhttp GET https://api.github.com/repos/{owner}/{repo}\n-> 404 + no auth header -> might be private\n-> 401 -> explicit auth failure\n-> 200 -> repo is public, access works\n```\n\n## Edge Cases\n\n| Edge Case | Signal | Response |\n|---|---|---|\n| GitHub.com SAML SSO | `403` + `X-GitHub-SSO: required; url=...` | PAT needs SSO authorization for the org |\n| GHE SAML SSO (web_fetch) | `200` + body contains `Initiating SAML single sign-on`, redirect to `login.microsoftonline.com` or other IdP | Repo EXISTS and is auth-gated. NOT inaccessible. Use PAT + `http` with auth headers, or `gh auth login --hostname <host>` |\n| GHE SAML SSO (http) | `302` redirect to `/login?return_to=...` or IdP URL | Same — repo exists, needs auth. Walk the Strategy Ladder |\n| GHE SAML SSO (git CLI) | `fatal: Authentication failed` or credential prompt | `gh auth login --hostname <host>` or PAT via credential helper |\n\n## SAML SSO — Detailed Pattern\n\nGitHub Enterprise instances commonly use SAML SSO via Azure AD (Entra ID), Okta, or other IdPs. When `web_fetch` hits a GHE URL without auth:\n\n1. GHE returns `200 OK` (not 401/403!) with an HTML page\n2. The HTML contains `Initiating SAML single sign-on` and a redirect URL to the IdP\n3. The redirect URL includes `SAMLRequest=`, `RelayState=`, and often `login.microsoftonline.com`\n4. The agent sees HTML content and may conclude the repo is "inaccessible" or "behind SSO"\n\n**Detection strings** (check `web_fetch` output for ANY of these):\n```\nInitiating SAML single sign-on\nlogin.microsoftonline.com\nYou are being redirected to your identity provider\n/login?return_to=\nSAMLRequest=\nRelayState=\n```\n\n**Correct response:** The repo exists. The `web_fetch` path will never work for SSO-protected GHE. Switch to:\n- `gh auth login --hostname <ghe-host>` (if `gh` CLI available)\n- PAT + `http` with `Authorization: token <PAT>` against `<ghe-host>/api/v3/repos/{owner}/{repo}/contents/{path}`\n- Ask user for local clone if no token can be obtained\n| GitLab 2FA enabled | `401` on password auth | PAT is mandatory; 2FA blocks password auth |\n| Expired token | `401` after providing a valid-looking PAT | Generate a new token and check expiry |\n| GitHub rate limit | `403` + body contains `rate limit` | Not an auth failure; wait or authenticate for a higher limit |\n| IP allowlisting | `403` + body mentions IP or org policies | Cannot be fixed programmatically; skip to local clone (Step 5) |\n| Fine-grained PAT scope | `403` + `insufficient scope` | Switch to a classic PAT for org repos |\n| SSH key not in agent | `Permission denied (publickey)` + key file exists | Run `ssh-add ~/.ssh/id_ed25519` |\n| Wrong SSH username | `Permission denied` | Use `git@host`, not `username@host` |\n| Deploy key conflict | `key is already in use` | Use a user SSH key or PAT instead |\n\n## Escalation Decision Rules\n\n- Retry the same step for transient failures such as DNS failure, timeout, or `5xx` responses.\n- Escalate to the next strategy step for `401`, `403`, `404`, `Permission denied`, `Authentication failed`, or `Access denied`.\n- Skip directly to Step 5 (local clone) for IP allowlisting, enterprise SSL certificate issues, or org policy blocks.\n\nDefault interpretation order:\n\n1. Prefer API probes over web page fetches.\n2. Treat GitHub `404` as ambiguous until valid auth disproves privacy.\n3. Treat SSH `publickey` errors as key-distribution failures, not repo absence.\n4. Separate rate limits and org policy blocks from authentication failures before escalating.'},{file:`references/platform-matrix.md`,content:"# Platform Matrix\n\nUse this reference when a repository URL reveals the hosting platform and the skill needs platform-specific authentication or cloning guidance. Prefer platform CLI login flows or OS-backed credential helpers over raw PAT handling.\n\n## Platform Detection\n\n| URL Pattern | Platform | CLI Tool (optional) | Auth Command | No-CLI Alternative |\n|---|---|---|---|---|\n| `github.com` | GitHub | `gh` | `gh auth login` | PAT + `http` with `Authorization: token <PAT>` |\n| Any custom domain (e.g. `ghe.corp.com`, `github.corp.com`) | GitHub Enterprise | `gh` | `gh auth login --hostname <host>` | PAT + `http` against `<host>/api/v3` |\n| `gitlab.com` | GitLab | `glab` | `glab auth login` | PAT + `http` with `PRIVATE-TOKEN` header |\n| Self-hosted GitLab | GitLab Self-Managed | `glab` | `glab auth login --hostname <host>` | PAT + `http` with `PRIVATE-TOKEN` header |\n| `bitbucket.org` | Bitbucket Cloud | None | N/A | App password + `http` with `Authorization: Bearer` |\n| `dev.azure.com` or `*.visualstudio.com` | Azure DevOps | `az` + GCM | `az login` | PAT + `http` with Basic auth |\n| Gitea instances | Gitea | `tea` (optional) | `tea login add` | PAT + `http` with `Authorization: token` |\n| Unknown or custom domain | Ask user which platform | N/A | N/A | Probe `http` or ask before assuming generic Git |\n\n> **Note:** Platform CLIs (`gh`, `glab`, `az`, `tea`) are native binaries, not npm packages. Do NOT use `npx` to install them — it will fail or install unrelated/unofficial packages. When the CLI is unavailable, use the No-CLI Alternative column.\n\n## GitHub / GitHub Enterprise\n\n- CLI: `gh auth login` uses a browser or device code flow and can open the browser automatically.\n- GitHub Enterprise CLI: `gh auth login --hostname <host>`.\n- PAT creation: `https://github.com/settings/tokens` for classic tokens.\n- PAT creation: `https://github.com/settings/personal-access-tokens` for fine-grained tokens.\n- Minimum scopes: `repo` for classic PATs (NOTE: `repo` grants read and write — prefer fine-grained PATs with `Contents: Read` for read-only access).\n- Minimum scopes: `Contents: Read` for fine-grained PATs.\n- SSH: `git@github.com:owner/repo.git`.\n- Credential helper: `gh auth setup-git` configures Git to use the GitHub credential flow.\n- Note: Fine-grained PATs may not cover organization-level access or every repo path; classic PATs are still required for some org repos.\n- SAML SSO: PATs often require explicit org authorization from `https://github.com/settings/tokens` after creation.\n- Enterprise note: PAT URLs and token policy can vary by host; reuse the same auth pattern with the enterprise hostname and instance settings pages.\n- Enterprise detection: GHE instances use fully custom domains (e.g. `ghe.coxautoinc.com`, `github.acme.com`). If unsure, probe `https://<host>/api/v3` — a GitHub Enterprise instance returns a JSON response with `installed_version`. Use `gh auth login --hostname <host>` with any custom GHE domain.\n\n## GitLab / GitLab Self-Managed\n\n- CLI: `glab auth login` uses a browser-backed OAuth flow.\n- Self-managed CLI: `glab auth login --hostname <host>`.\n- PAT creation: `https://gitlab.com/-/user_settings/personal_access_tokens`.\n- Minimum scopes: `read_repository`.\n- SSH: `git@gitlab.com:owner/repo.git`.\n- Credential helper: `glab auth setup-git` configures Git credential handling.\n- Note: If 2FA is enabled, username/password Git auth is blocked; a PAT is mandatory for HTTPS auth.\n- Self-managed note: PAT URL is typically `https://<host>/-/user_settings/personal_access_tokens` unless the instance customizes settings paths.\n\n## Bitbucket Cloud\n\n- CLI: No official first-party CLI OAuth flow for repo auth.\n- PAT/App Password creation: `https://bitbucket.org/{workspace}/settings/app-passwords`.\n- Minimum permissions: `Repositories: Read`.\n- SSH: `git@bitbucket.org:owner/repo.git`.\n- Note: Bitbucket Cloud uses App Passwords rather than standard PAT terminology.\n- Note: HTTPS auth requires both the Bitbucket username and the app password, delivered through a credential helper or `GIT_ASKPASS` script — never embedded in the clone URL.\n\n## Azure DevOps\n\n- CLI: `az login` authenticates to Microsoft Entra ID; Git Credential Manager then handles Git credentials automatically.\n- PAT-based auth remains the fallback when Entra ID or GCM is unavailable.\n- PAT creation: `https://dev.azure.com/{org}/_usersSettings/tokens`.\n- Minimum scopes: `Code: Read`.\n- SSH: `git@ssh.dev.azure.com:v3/{org}/{project}/{repo}`.\n- Note: Microsoft Entra ID tokens are generally preferred over PATs in enterprise environments.\n- Credential helper: Git Credential Manager via `git-credential-manager configure`.\n- Legacy host note: Azure DevOps may also appear under `*.visualstudio.com` URLs.\n\n## Gitea / Forgejo\n\n- CLI: `tea login add` is available but optional and not universally installed.\n- PAT creation: `https://{host}/user/settings/applications`.\n- Minimum scopes: `repo`.\n- SSH: `git@{host}:owner/repo.git`.\n- Note: Forgejo commonly mirrors the same applications-token path and PAT model as Gitea.\n- Note: Some self-hosted instances rename scopes or disable API token creation, so confirm the instance policy if `repo` is rejected.\n\n## Generic Git (Self-Hosted)\n\n- Platform CLI: None assumed.\n- Auth path: Prefer SSH keys first, then PAT if the host documents HTTPS token auth.\n- PAT creation: Ask the user for the platform's PAT or application-token settings URL.\n- SSH: Use the host's documented SSH remote format; do not assume GitHub-style shortcuts if the server advertises a different pattern.\n\n## API File-Read Endpoints (for web-based code access)\n\nWhen agents need to read individual files without cloning, use these authenticated API endpoints.\n\n### GitHub / GitHub Enterprise\n\n```text\n# Read file contents (returns JSON with base64 content)\nGET https://api.github.com/repos/{owner}/{repo}/contents/{path}?ref={branch}\nAuthorization: token <PAT>\n\n# GHE: replace api.github.com with <ghe-host>/api/v3\nGET https://<ghe-host>/api/v3/repos/{owner}/{repo}/contents/{path}?ref={branch}\n\n# Or use gh CLI (auto-authenticated):\ngh api repos/{owner}/{repo}/contents/{path}?ref={branch} --jq '.content' | base64 -d\n```\n\n### GitLab / GitLab Self-Managed\n\n```text\n# URL-encode the file path (/ becomes %2F)\nGET https://gitlab.com/api/v4/projects/{project-id}/repository/files/{url-encoded-path}/raw?ref={branch}\nPRIVATE-TOKEN: <PAT>\n\n# Or use project path instead of ID:\nGET https://gitlab.com/api/v4/projects/{url-encoded-namespace%2Fproject}/repository/files/{url-encoded-path}/raw?ref={branch}\n```\n\n### Azure DevOps\n\n```text\nGET https://dev.azure.com/{org}/{project}/_apis/git/repositories/{repo}/items?path={path}&api-version=7.0\nAuthorization: Basic {base64(:PAT)}\n```\n\n### Bitbucket Cloud\n\n```text\nGET https://api.bitbucket.org/2.0/repositories/{workspace}/{repo}/src/{commit-or-branch}/{path}\nAuthorization: Bearer <app-password-or-token>\n```\n- Note: Self-hosted products often customize auth policy, token names, and minimum scopes.\n\n## Safe Credential Delivery Patterns\n\n| Method | Command | Safety |\n|---|---|---|\n| Platform CLI | `gh auth login` / `glab auth login` | Best — handles credential storage |\n| Git Credential Manager | `git credential-manager configure` | Good — OS keychain storage |\n| Environment variable | `GH_TOKEN=xxx gh repo clone ...` | OK — ephemeral; safer than URL tokens but visible to same-user processes |\n| Git askpass | `GIT_ASKPASS=script git clone ...` | OK — no shell history exposure |\n| Inline in URL | `git clone https://token@host/...` | FORBIDDEN — leaks in history/logs |\n\n## Operational Notes\n\n- Prefer SSH when the user already has working keys and the host advertises a stable SSH remote format.\n- Prefer platform CLI login for GitHub and GitLab because it also wires Git credential storage.\n- Prefer Git Credential Manager for Azure DevOps and other HTTPS-heavy enterprise setups.\n- When recommending PAT creation, always suggest setting a short expiry (7-30 days for task-specific work). Prefer fine-grained or short-lived tokens.\n- Never recommend pasting tokens inline into clone URLs, scripts checked into the repo, or long-lived shell profiles."},{file:`SKILL.md`,content:'---\nname: repo-access\ndescription: "Progressive repository access recovery for private and enterprise git repositories. Triggered when: (1) git clone/fetch/pull fails with auth errors (401, 403, 404, Permission denied), (2) web_fetch or http tool returns auth failure on repository URLs, (3) user mentions private repo, enterprise repo, or internal repo, (4) user asks to access code from GitHub Enterprise, GitLab Self-Managed, Bitbucket Server, Azure DevOps. Guides through 5-step progressive strategy: anonymous HTTPS, SSH keys, CLI OAuth, PAT, local clone fallback."\nmetadata:\n  category: cross-cutting\n  domain: general\n  applicability: on-demand\n  inputs: [git-error, repository-url, platform-context]\n  outputs: [authenticated-access, recovery-instructions]\n  requires: []\n  relatedSkills: [aikit]\nargument-hint: "Repository URL or error message"\n---\n\n# Repository Access Recovery\n\nProgressively recover repository access for private, enterprise, and internal git hosts without leaking credentials.\n\n## When to Activate\n\n### Reactive triggers\n\n- `git clone`, `git fetch`, or `git pull` fails with `401`, `403`, `404`, `Authentication failed`, or `Permission denied (publickey)`.\n- `http` diagnostics against a repo endpoint show auth failure or ambiguous private-repo responses.\n- `web_fetch` returns login page HTML, SSO redirect, "Sign in", "Page not found", or empty/truncated content for a repo URL.\n- Any tool output contains "behind SSO", "SSO required", "SAML", "requires authentication", or similar auth-gate language about a repository.\n- A repository URL works in a browser for the user but fails from agent tools or terminal commands.\n- **You are about to declare a repo "inaccessible" or "unreachable"** — STOP and activate this skill first.\n\n### Proactive triggers\n\n- The user says the repo is private, enterprise, self-managed, internal, or SSO-protected.\n- The repo is hosted on GitHub Enterprise, GitLab Self-Managed, Bitbucket Server/Data Center, Azure DevOps, Gitea, or another custom git host.\n- The environment may need browser sign-in, SSH agent setup, or token-based recovery before any code access can work.\n\n## When NOT to Activate\n\n- Public repositories that already clone or read successfully over HTTPS.\n- Local-only repositories where no remote auth is involved.\n- Problems caused by branch protection, merge conflicts, or rate limiting rather than repository access.\n\n## Step 0: Platform Detection & Capability Gate\n\nDetect platform from the URL, then decide what recovery options are possible in this environment.\n\n| URL pattern | Platform |\n| --- | --- |\n| `github.com`, or any GHE host (e.g. `ghe.*`, `github.*`, custom domain) | GitHub / GitHub Enterprise |\n| `gitlab.com`, `gitlab.<corp-host>` | GitLab / GitLab Self-Managed |\n| `bitbucket.org`, `bitbucket.<corp-host>` | Bitbucket Cloud / Server |\n| `dev.azure.com`, `visualstudio.com`, `/_git/` | Azure DevOps |\n| anything else with git over HTTPS/SSH | Unknown — ask the user which platform before assuming generic Git |\n\n- Capability gate: has terminal, has browser, or conversation-only.\n- If terminal is unavailable, skip directly to PAT guidance or local clone fallback.\n- If browser is unavailable, prefer SSH or pre-created credentials over CLI OAuth.\n- If only the `http` tool is available (no terminal, no CLI): use PAT + authenticated API reads (see "Web-Based Code Access" below). This is the zero-dependency path — no `gh`, `glab`, or `az` installation needed.\n\nFor platform-specific details, read `references/platform-matrix.md`.\n\n## Strategy Ladder\n\n### Step 1: Try HTTPS Anonymous Access\n\n- Goal: prove the repo is public or already reachable without extra auth.\n- What to do: normalize the remote to an HTTPS URL and run `git ls-remote https://...`. If it succeeds, use HTTPS and stop. If it fails with auth-like errors, continue instead of assuming the repo is missing.\n- Verify: `git ls-remote <url>`; SUCCESS -> stop, FAIL -> Step 2.\n\n### Step 2: Check Existing SSH Keys\n\n- Goal: reuse working SSH credentials before asking for new secrets.\n- What to do: inspect `~/.ssh/` for key files, run `ssh-add -l`, then test host auth with `ssh -T git@{host}`. If SSH works, switch the remote to the SSH URL and continue with that transport.\n- Verify: `git ls-remote <ssh-url>`; SUCCESS -> stop, FAIL -> Step 3.\n\n### Step 3: Platform CLI OAuth\n\n- Goal: use the platform\'s interactive login flow with stored credentials.\n- What to do: check whether the matching CLI exists, for example `which gh`, `which glab`, or `which az` (or platform equivalent). If installed, run `{cli} auth login` and let it complete browser or device OAuth, then retry git access.\n- **If the CLI is not installed**: do NOT try `npx` — platform CLIs (`gh`, `glab`, `az`) are native binaries, not npm packages. Skip straight to Step 4 (PAT). For file-read-only tasks, the `http` tool with a PAT header is a zero-dependency alternative to any CLI.\n- Verify: `git ls-remote <url>`; SUCCESS -> stop, FAIL -> Step 4.\n\n### Step 4: Personal Access Token\n\n- Goal: recover access when SSH and CLI OAuth are unavailable or blocked.\n- What to do: ask the user to create a PAT or app password at the platform-specific URL with minimum read scopes only. Have the user provide it through an env var or credential helper, then configure git credentials without embedding the token in the remote URL.\n- Verify: `git ls-remote <url>`; SUCCESS -> stop, FAIL -> Step 5.\n\n### Step 5: Local Clone Fallback\n\n- Goal: unblock work when remote auth cannot be completed from the current environment.\n- What to do: ask the user to clone the repository on their machine using their normal workflow, then provide the local filesystem path. Use the local checkout as the source of truth for code access.\n- Verify: local repo exists and `git rev-parse --show-toplevel` succeeds; SUCCESS -> stop.\n\n## Security Rules (HARD GATE)\n\n- NEVER include a PAT in a git URL; it leaks into shell history, process lists, logs, and config.\n- NEVER repeat a user\'s token value in chat output, summaries, examples, or when relaying tool output that may contain credentials.\n- Use env vars, credential helpers, or platform login tools for token delivery.\n- Recommend minimum scopes only: read-only repo scopes, not broad write/admin scopes.\n- Prefer ephemeral credentials, OAuth/device flows, or short-lived tokens over long-lived PATs.\n- When guiding PAT creation, recommend the shortest feasible expiry (7–30 days for task-specific work).\n\n## After Access Is Established\n\n- Remind the user to revoke single-use PATs once the task is complete.\n- If credentials were stored via a credential helper, note that they persist until manually removed or the token expires.\n\n## Web-Based Code Access (web_fetch / http)\n\nAgents often use `web_fetch` or `http` to read individual files without a full clone. These requests fail silently on private repos — GitHub returns `404` or login HTML, not an auth error.\n\n### Common URL Patterns That Fail on Private Repos\n\n| URL Pattern | Platform | What Happens |\n|---|---|---|\n| `raw.githubusercontent.com/{owner}/{repo}/{ref}/{path}` | GitHub | `404` — no auth header accepted |\n| `github.com/{owner}/{repo}/blob/{ref}/{path}` | GitHub web view | `200` with login HTML, not code |\n| `api.github.com/repos/{owner}/{repo}/contents/{path}` | GitHub API | `404` (the GitHub 404 trap) |\n| `<ghe-host>/{owner}/{repo}/*` (any GHE URL) | GitHub Enterprise | `200` with SAML SSO redirect page — body contains "Initiating SAML single sign-on" and redirect to `login.microsoftonline.com` or other IdP |\n| `gitlab.com/{owner}/{repo}/-/raw/{ref}/{path}` | GitLab | `401` or login redirect |\n| `dev.azure.com/{org}/{project}/_apis/git/repositories/{repo}/items` | Azure DevOps | `401` or `203` non-authoritative |\n\n### SAML SSO Detection (CRITICAL)\n\nGHE instances with SAML SSO return `200 OK` with an HTML body that is NOT the requested content. **This is the most common false-"inaccessible" scenario.** Detect it by checking `web_fetch` output for ANY of these strings:\n\n- `Initiating SAML single sign-on`\n- `login.microsoftonline.com` (Azure AD / Entra ID)\n- `You are being redirected to your identity provider`\n- `/login?return_to=`\n- `SAMLRequest=`\n- `RelayState=`\n\nIf ANY of these appear → the repo exists and is accessible, it just needs authentication. This is NOT "inaccessible" — follow the Strategy Ladder.\n\n### Recovery: Authenticated API Reads\n\nWhen `web_fetch` fails on a private repo URL, switch to authenticated `http` calls:\n\n1. **Ensure auth is established first** — walk the Strategy Ladder (Steps 1-4) to get working credentials.\n2. **Use the platform API with auth headers**, not raw/web URLs:\n\n| Platform | Authenticated file-read endpoint | Auth header |\n|---|---|---|\n| GitHub / GHE | `http GET https://api.github.com/repos/{owner}/{repo}/contents/{path}?ref={branch}` | `Authorization: token <PAT>` or use `gh api` |\n| GitLab | `http GET https://gitlab.com/api/v4/projects/{id}/repository/files/{path}/raw?ref={branch}` | `PRIVATE-TOKEN: <PAT>` |\n| Azure DevOps | `http GET https://dev.azure.com/{org}/{project}/_apis/git/repositories/{repo}/items?path={path}&api-version=7.0` | `Authorization: Basic <base64(:PAT)>` |\n| Bitbucket | `http GET https://api.bitbucket.org/2.0/repositories/{owner}/{repo}/src/{ref}/{path}` | `Authorization: Bearer <token>` |\n\n3. **Prefer `http` over `web_fetch`** for private repos — `http` sends proper headers and returns machine-readable JSON; `web_fetch` gets HTML login pages.\n4. **For bulk reads**, prefer `git clone --depth 1` over many individual API calls — it\'s faster and avoids rate limits.\n5. **NEVER embed tokens in URLs** — use auth headers via the `http` tool or `gh api` CLI wrapper.\n\n### Quick Decision: Clone vs API Read\n\n| Situation | Preferred method |\n|---|---|\n| Need 1-3 specific files | Authenticated API via `http` |\n| Need to browse/search the repo | `git clone --depth 1` (shallow) |\n| Need file history or blame | `git clone` |\n| No terminal available | Authenticated API via `http` with PAT |\n| Rate-limited on API | `git clone --depth 1` |\n\n## Tool Routing\n\n| Tool | Use |\n| --- | --- |\n| `git_context` | Check local repo state and confirm a clone or fallback checkout is usable |\n| `http` | Probe platform APIs for auth diagnostics AND read file contents from private repos with auth headers |\n| `web_fetch` | Only for public repos or after confirming access works; unreliable for private repos (returns HTML, not code) |\n| `web_search` | Find current platform-specific auth documentation when the host is unusual or self-managed |\n| Terminal | Run git commands, SSH tests, CLI auth flows, and credential-helper setup |\n\nFor detailed error patterns, read `references/error-patterns.md`.\n\n## CRITICAL: The GitHub 404 Trap\n\nGitHub commonly returns `404 Not Found` for private repositories when the caller is unauthenticated or under-authenticated. NEVER conclude that a GitHub repository does not exist from a `404` alone. Treat that response as an authentication signal first, then walk the ladder before declaring the repo missing.'}],"requirements-clarity":[{file:`SKILL.md`,content:`---
 name: requirements-clarity
 description: Clarify ambiguous requirements through focused dialogue before implementation. Use when requirements are unclear, features are complex (>2 days), or involve cross-team coordination. Ask two core questions - Why? (YAGNI check) and Simpler? (KISS check) - to ensure clarity before coding.
 metadata:
@@ -9916,10 +8203,7 @@ Use \`create_file\` to save this file. Derive \`{version}\` from the document ve
 - Execution phases actionable with concrete tasks
 - User approves final PRD
 - Ready for development handoff
-` },
-  ],
-  "session-handoff": [
-    { file: "references/handoff-template.md", content: `# Handoff Template
+`}],"session-handoff":[{file:`references/handoff-template.md`,content:`# Handoff Template
 
 Use this template structure when creating handoff documents. The smart scaffold script will pre-fill metadata sections; complete the remaining sections based on session context.
 
@@ -10058,8 +8342,7 @@ When filling this template:
 3. Prioritize the "Important Context" and "Immediate Next Steps" sections
 4. Don't include sensitive data (API keys, passwords, tokens)
 5. Focus on WHAT and WHY, not just WHAT - rationale is crucial for handoffs
-` },
-    { file: "references/resume-checklist.md", content: `# Resume Checklist
+`},{file:`references/resume-checklist.md`,content:`# Resume Checklist
 
 Follow this checklist when resuming work from a handoff document to ensure zero-ambiguity continuation.
 
@@ -10139,8 +8422,7 @@ Rate the handoff quality to identify if more exploration is needed:
 | Context | Complete picture | Gaps or assumptions |
 
 If multiple aspects "Need Exploration", spend time re-exploring the codebase before continuing implementation.
-` },
-    { file: "scripts/check_staleness.js", content: `#!/usr/bin/env node
+`},{file:`scripts/check_staleness.js`,content:`#!/usr/bin/env node
 /**
  * Check staleness of a handoff document compared to current project state.
  *
@@ -10409,8 +8691,7 @@ if (args.includes('--json')) {
   const result = checkStaleness(args[0]);
   printReport(result);
 }
-` },
-    { file: "scripts/create_handoff.js", content: `#!/usr/bin/env node
+`},{file:`scripts/create_handoff.js`,content:`#!/usr/bin/env node
 /**
  * Smart scaffold generator for handoff documents.
  *
@@ -10709,8 +8990,7 @@ const { filepath } = generateHandoff(cwd, slug, continuesFrom);
 console.log(\`Created handoff: \${filepath}\`);
 console.log(\`\\nNext: Open the file and fill in all [TODO: ...] sections.\`);
 console.log(\`Then validate: node scripts/validate_handoff.js \${filepath}\`);
-` },
-    { file: "scripts/list_handoffs.js", content: `#!/usr/bin/env node
+`},{file:`scripts/list_handoffs.js`,content:`#!/usr/bin/env node
 /**
  * List available handoff documents in the current project.
  *
@@ -10823,8 +9103,7 @@ for (const h of handoffs) {
 if (args.includes('--json')) {
   console.log(\`\\n\${JSON.stringify(handoffs, null, 2)}\`);
 }
-` },
-    { file: "scripts/validate_handoff.js", content: `#!/usr/bin/env node
+`},{file:`scripts/validate_handoff.js`,content:`#!/usr/bin/env node
 /**
  * Validate a handoff document for completeness and quality.
  *
@@ -11065,8 +9344,7 @@ if (args.includes('--json')) {
   const result = validateHandoff(args[0]);
   printReport(result);
 }
-` },
-    { file: "SKILL.md", content: `---
+`},{file:`SKILL.md`,content:`---
 name: session-handoff
 description: "Creates comprehensive handoff documents for seamless AI agent session transfers. Triggered when: (1) user requests handoff/memory/context save, (2) context window approaches capacity, (3) major task milestone completed, (4) work session ending, (5) user says 'save state', 'create handoff', 'I need to pause', 'context is getting full', (6) resuming work with 'load handoff', 'resume from', 'continue where we left off'. Proactively suggests handoffs after substantial work (multiple file edits, complex debugging, architecture decisions). Solves long-running agent context exhaustion by enabling fresh agents to continue with zero ambiguity."
 metadata:
@@ -11265,10 +9543,7 @@ Example: \`2024-01-15-143022-implementing-auth.md\`
 
 - [handoff-template.md](references/handoff-template.md) - Complete template structure with guidance
 - [resume-checklist.md](references/resume-checklist.md) - Verification checklist for resuming agents
-` },
-  ],
-  "typescript": [
-    { file: "SKILL.md", content: `---
+`}],typescript:[{file:`SKILL.md`,content:`---
 name: typescript
 description: "Comprehensive TypeScript development patterns — type system performance, compiler configuration, advanced types, type safety, async patterns, module organization, and runtime optimization."
 metadata:
@@ -11673,6 +9948,4 @@ When writing TypeScript:
 5. **Import style?** → \`import type\` for types. Direct imports, not barrel files. Named exports, not default.
 6. **Error handling?** → Result pattern for expected errors. throw for unexpected/programmer errors.
 7. **Async?** → Promise.all for parallel. AbortController for timeouts. AsyncGenerator for streams.
-` },
-  ],
-};
+`}]};export{e as SKILLS};