@vpxa/aikit 0.1.133 → 0.1.135

package/scaffold/definitions/mcp-entry.json

@@ -3,6 +3,6 @@
   "command": "node",
   "args": [
     "-e",
-    "const{execSync:x}=require('child_process');const{renameSync:m}=require('fs');const{join:j}=require('path');const d=process.platform==='win32'?j(process.env.LOCALAPPDATA||'','npm-cache','_npx'):j(require('os').homedir(),'.npm','_npx');const c='npx -y @vpxa/aikit serve';const s={stdio:'inherit'};try{x(c,s)}catch(e){try{m(d,d+'_'+Date.now())}catch{};x(c,s)}"
+    "const{execSync:x}=require('child_process');const{readdirSync:r,renameSync:m}=require('fs');const{join:j}=require('path');const c=j(process.env.LOCALAPPDATA||process.env.HOME||'','npm-cache');const s={stdio:'inherit'};try{x('npx -y @vpxa/aikit serve',s)}catch{try{x('npx --prefer-online -y @vpxa/aikit serve',s)}catch{try{r(c).filter(d=>d.startsWith('_npx')).forEach(d=>m(j(c,d),j(c,d+'_'+Date.now())))}catch{};x('npx -y @vpxa/aikit serve',s)}}"
   ]
 }

package/scaffold/dist/definitions/bodies.mjs

@@ -180,8 +180,9 @@ Batch 2 (after batch 1):
 4. **Constraints** — patterns, conventions
 5. **Artifacts Path** — the active flow's run directory and artifacts path from \`flow({ action: 'status' })\` (e.g. \`.flows/add-authentication/.spec/\`)
 6. **FORGE** — tier + task_id + evidence requirements (reviewers add CRITICAL/HIGH claims into your task_id; never create their own)
-7. **Self-Review** — checklist before declaring status
-8. **No present** — "Do NOT use the \`present\` tool — return all findings as structured text"
+7. **Flow Context** — "Call \`knowledge({ action: 'withdraw', profile: '<role>', budget: 6000 })\` as your FIRST action to receive pre-analyzed context from prior agents."
+8. **Self-Review** — checklist before declaring status
+9. **No present** — "Do NOT use the \`present\` tool — return all findings as structured text"
 
 **Subagent status protocol:** \`DONE\` | \`DONE_WITH_CONCERNS\` | \`NEEDS_CONTEXT\` | \`BLOCKED\`
 
@@ -743,4 +744,4 @@ Rules adapted from *The Elements of Agent Style* (CC BY 4.0, Yue Zhao) and class
 | \`present\` | When presenting documentation previews, API tables, or architecture visuals to the user |
 | \`c4-architecture\` | When documenting system architecture — generate C4 Mermaid diagrams |
 | \`adr-skill\` | When documenting architecture decisions — create or update ADRs |
-| \`typescript\` | When documenting TypeScript APIs — type signatures, JSDoc patterns |`,Explorer:'**Read `AGENTS.md`** in the workspace root for project conventions and AI Kit protocol.\n\nLoad the `aikit` skill for full tool documentation, workflow chains, and session protocol.\n\n## MANDATORY FIRST ACTION\n\n1. Run `status({})` — if onboard shows ❌, run `onboard({ path: "." })` and wait for completion\n2. Note the **Onboard Directory** path from status output\n3. **Before exploring**, read relevant onboard artifacts using `compact({ path: "<dir>/<file>" })`:\n   - `synthesis-guide.md` — project overview and architecture\n   - `structure.md` — file tree and module purposes\n   - `symbols.md` + `api-surface.md` — exported symbols\n   - `dependencies.md` — import relationships\n   - `code-map.md` — module graph\n4. Only use `find`, `symbol`, `trace`, `graph` for details NOT covered by artifacts\n\n## Exploration Protocol\n\n1. **AI Kit Recall** — `search` for existing analysis on this area\n2. **Discover** — Use `find`, `symbol`, `scope_map` to locate relevant files\n3. **Analyze** — Use `analyze({ aspect: "structure", ... })`, `analyze({ aspect: "dependencies", ... })`, `file_summary`\n4. **Compress** — Use `compact` for targeted file sections, `digest` when synthesizing 3+ sources, `stratum_card` for files you\'ll reference repeatedly\n5. **Map** — Build a picture of the subsystem: files, exports, dependencies, call chains\n6. **Report** — Structured findings with file paths and key observations\n\n## Exploration Modes\n\n| Goal | Tools |\n|------|-------|\n| Find files for a feature | `find`, `scope_map` |\n| Map a symbol\'s usage | `symbol`, `trace` |\n| Map module relationships | `graph({ action: \'neighbors\' })` — import/export edges across packages |\n| Understand a package | `analyze({ aspect: "structure", ... })`, `analyze({ aspect: "dependencies", ... })`, `file_summary` |\n| Check impact of a change | `blast_radius` |\n\n## Output Format\n\n```markdown\n## Exploration: {topic}\n\n### Files Found\n- path/to/file.ts — purpose, key exports\n\n### Dependencies\n- package A → package B (via import)\n\n### Key Observations\n- Notable patterns, potential issues, architectural notes\n```\n\n## Rules\n\n- **Speed over depth** — Provide a useful map quickly, not an exhaustive analysis\n- **Read-only** — Never create, edit, or delete files\n- **Structured output** — Always return findings in the format above'};export{e as AGENT_BODIES};
+| \`typescript\` | When documenting TypeScript APIs — type signatures, JSDoc patterns |`,Explorer:"**Read `AGENTS.md`** in the workspace root for project conventions and AI Kit protocol.\n\nLoad the `aikit` skill for full tool documentation, workflow chains, and session protocol.\n\n## MANDATORY FIRST ACTION\n\n1. Run `status({})` — if onboard shows ❌, run `onboard({ path: \".\" })` and wait for completion\n2. Note the **Onboard Directory** path from status output\n3. **Before exploring**, read relevant onboard artifacts using `compact({ path: \"<dir>/<file>\" })`:\n   - `synthesis-guide.md` — project overview and architecture\n   - `structure.md` — file tree and module purposes\n   - `symbols.md` + `api-surface.md` — exported symbols\n   - `dependencies.md` — import relationships\n   - `code-map.md` — module graph\n4. Only use `find`, `symbol`, `trace`, `graph` for details NOT covered by artifacts\n\n## Flow Context Bootstrap\n\nWhen dispatched as a subagent within an active flow:\n\n1. **Withdraw context first** — before any search or file reads:\n   ```\n   knowledge({ action: 'withdraw', profile: 'researcher', budget: 6000 })\n   ```\n   This returns pre-analyzed context from prior agents.\n\n2. **Use returned context** — do NOT re-search or re-read files already covered\n3. **`read_file` ONLY** for exact lines needed for editing\n4. **Deposit new discoveries:**\n   ```\n   knowledge({ action: 'remember', scope: 'flow', title: '<discovery>', content: '<details>', category: 'context' })\n   ```\n\n**Profile:** `researcher`\n\n## Exploration Protocol\n\n1. **AI Kit Recall** — `search` for existing analysis on this area\n2. **Discover** — Use `find`, `symbol`, `scope_map` to locate relevant files\n3. **Analyze** — Use `analyze({ aspect: \"structure\", ... })`, `analyze({ aspect: \"dependencies\", ... })`, `file_summary`\n4. **Compress** — Use `compact` for targeted file sections, `digest` when synthesizing 3+ sources, `stratum_card` for files you'll reference repeatedly\n5. **Map** — Build a picture of the subsystem: files, exports, dependencies, call chains\n6. **Report** — Structured findings with file paths and key observations\n\n## Exploration Modes\n\n| Goal | Tools |\n|------|-------|\n| Find files for a feature | `find`, `scope_map` |\n| Map a symbol's usage | `symbol`, `trace` |\n| Map module relationships | `graph({ action: 'neighbors' })` — import/export edges across packages |\n| Understand a package | `analyze({ aspect: \"structure\", ... })`, `analyze({ aspect: \"dependencies\", ... })`, `file_summary` |\n| Check impact of a change | `blast_radius` |\n\n## Output Format\n\n```markdown\n## Exploration: {topic}\n\n### Files Found\n- path/to/file.ts — purpose, key exports\n\n### Dependencies\n- package A → package B (via import)\n\n### Key Observations\n- Notable patterns, potential issues, architectural notes\n```\n\n## Rules\n\n- **Speed over depth** — Provide a useful map quickly, not an exhaustive analysis\n- **Read-only** — Never create, edit, or delete files\n- **Structured output** — Always return findings in the format above"};export{e as AGENT_BODIES};

package/scaffold/dist/definitions/mcp-entry.json

@@ -3,6 +3,6 @@
   "command": "node",
   "args": [
     "-e",
-    "const{execSync:x}=require('child_process');const{renameSync:m}=require('fs');const{join:j}=require('path');const d=process.platform==='win32'?j(process.env.LOCALAPPDATA||'','npm-cache','_npx'):j(require('os').homedir(),'.npm','_npx');const c='npx -y @vpxa/aikit serve';const s={stdio:'inherit'};try{x(c,s)}catch(e){try{m(d,d+'_'+Date.now())}catch{};x(c,s)}"
+    "const{execSync:x}=require('child_process');const{readdirSync:r,renameSync:m}=require('fs');const{join:j}=require('path');const c=j(process.env.LOCALAPPDATA||process.env.HOME||'','npm-cache');const s={stdio:'inherit'};try{x('npx -y @vpxa/aikit serve',s)}catch{try{x('npx --prefer-online -y @vpxa/aikit serve',s)}catch{try{r(c).filter(d=>d.startsWith('_npx')).forEach(d=>m(j(c,d),j(c,d+'_'+Date.now())))}catch{};x('npx -y @vpxa/aikit serve',s)}}"
   ]
 }

package/scaffold/dist/definitions/protocols.mjs

@@ -356,6 +356,25 @@ When you need user input or need to explain something before asking:
 - **Prefer the simplest method** that adequately conveys the information
 - **CLI mode override:** When running in terminal (not VS Code chat), always use \`format: "browser"\` for any rich content
 
+## Flow Context Bootstrap
+
+When dispatched as a subagent within an active flow:
+
+1. **Withdraw context first** — before any search or file reads:
+   \`\`\`
+   knowledge({ action: 'withdraw', profile: '<PROFILE>', budget: 6000 })
+   \`\`\`
+   This returns pre-analyzed context from prior agents.
+
+2. **Use returned context** — do NOT re-search or re-read files already covered
+3. **\`read_file\` ONLY** for exact lines needed for editing
+4. **Deposit new discoveries:**
+   \`\`\`
+   knowledge({ action: 'remember', scope: 'flow', title: '<discovery>', content: '<details>', category: 'context' })
+   \`\`\`
+
+**Profile:** Check your role → implementer | documenter | reviewer | researcher | debugger
+
 ---
 
 ## Handoff Format
@@ -413,6 +432,25 @@ common;
 research;
 needs.
 
+## Flow Context Bootstrap
+
+When dispatched as a subagent within an active flow:
+
+1. **Withdraw context first** — before any search or file reads:
+   \`\`\`
+   knowledge({ action: 'withdraw', profile: 'researcher', budget: 6000 })
+   \`\`\`
+   This returns pre-analyzed context from prior agents.
+
+2. **Use returned context** — do NOT re-search or re-read files already covered
+3. **\`read_file\` ONLY** for exact lines needed for editing
+4. **Deposit new discoveries:**
+   \`\`\`
+   knowledge({ action: 'remember', scope: 'flow', title: '<discovery>', content: '<details>', category: 'context' })
+   \`\`\`
+
+**Profile:** \`researcher\`
+
 ---
 
 #
@@ -553,6 +591,25 @@ using;
 )\` — especially \`patterns.md\` and \`api-surface.md\`
 for review context
 
+## Flow Context Bootstrap
+
+When dispatched as a subagent within an active flow:
+
+1. **Withdraw context first** — before any search or file reads:
+   \`\`\`
+  knowledge({ action: 'withdraw', profile: 'reviewer', budget: 6000 })
+   \`\`\`
+  This returns pre-analyzed context from prior agents.
+
+2. **Use returned context** — do NOT re-search or re-read files already covered
+3. **\`read_file\` ONLY** for exact lines needed for editing
+4. **Deposit new discoveries:**
+   \`\`\`
+   knowledge({ action: 'remember', scope: 'flow', title: '<discovery>', content: '<details>', category: 'context' })
+   \`\`\`
+
+**Profile:** \`reviewer\`
+
 ---
 
 #
@@ -729,6 +786,25 @@ using;
 )\` — especially \`structure.md\`, \`dependencies.md\`, and \`diagram.md\`
 for architecture context
 
+## Flow Context Bootstrap
+
+When dispatched as a subagent within an active flow:
+
+1. **Withdraw context first** — before any search or file reads:
+   \`\`\`
+  knowledge({ action: 'withdraw', profile: 'reviewer', budget: 6000 })
+   \`\`\`
+  This returns pre-analyzed context from prior agents.
+
+2. **Use returned context** — do NOT re-search or re-read files already covered
+3. **\`read_file\` ONLY** for exact lines needed for editing
+4. **Deposit new discoveries:**
+   \`\`\`
+   knowledge({ action: 'remember', scope: 'flow', title: '<discovery>', content: '<details>', category: 'context' })
+   \`\`\`
+
+**Profile:** \`reviewer\`
+
 ---
 
 #

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

@@ -1,4 +1,4 @@
-var e=[{file:`SKILL.md`,content:'---\nname: aikit\ndescription: "Use the @vpxa/aikit AI Kit MCP server for codebase search, analysis, and persistent memory. Load when using any aikit_* tool. 61 tools: search (hybrid/semantic/keyword), code analysis (structure, deps, symbols, patterns, entry points, diagrams, blast radius), knowledge graph (module/symbol/import traversal), context (worksets, stash, checkpoints, lanes), code manipulation (rename, codemod, eval), validation (check, test_run, audit), knowledge (remember/read/update/forget/list), web (fetch, search, http), FORGE (ground, classify, evidence map, stratum cards, digest), flows (list, start, step, read, runs, add/remove/update), presentation (dashboards), onboarding, meta-tools, and utilities (regex, encode, measure, changelog, schema-validate, 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 — 61 MCP tools for search, analysis, context compression, FORGE quality gates, knowledge management, code manipulation, execution, web access, flow management, presentation, meta-tool discovery, 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\n## Skills Reference\n\n| Context | Skill | Load when |\n|---------|-------|----------|\n| AI Kit search, analysis, memory | `aikit` | **Always load at session start.** Tool signatures, workflows, session protocol. |\n| Brainstorming & design | `brainstorming` | Before any creative/design work — new features, components, behavior changes. |\n| Session context preservation | `session-handoff` | Context window filling up, session ending, or major milestone completed. |\n| Requirements scoring | `requirements-clarity` | Before planning vague or complex features — score 0-100 until ≥ 90. |\n| Engineering lessons | `lesson-learned` | After completing work — extract principles from git diffs. |\n| Architecture diagrams | `c4-architecture` | When documenting or reviewing architecture — C4 Mermaid diagrams. |\n| Architecture decisions | `adr-skill` | When making non-trivial technical decisions — executable ADRs. |\n| Rich presentation | `present` | When presenting dashboards, charts, tables, or complex visual content to users. |\n| TypeScript patterns | `typescript` | Before TypeScript implementation — type system, compiler config, advanced types. |\n| React patterns | `react` | Before React work — component architecture, React 19 APIs, Server Components. |\n| Frontend design | `frontend-design` | Before UI/UX work — visual design, typography, color, layout, accessibility. |\n| Multi-agent orchestration | `multi-agents-development` | Before delegating to multiple agents — task decomposition, dispatch, review pipelines. |\n| Living documentation | `docs` | When creating or updating project documentation — Diátaxis framework, staleness detection. |\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| Browser automation & auth | `browser-use` | When needing browser interaction — login flows, SAML SSO bypass, cookie extraction, form filling, web scraping, or authenticated browsing. Pairs with `repo-access` for auth recovery via browser. |\n\n## Architecture\n\n16-package monorepo published as a single npm package:\n\n```\ncore → store → embeddings → chunker → indexer → analyzers → tools → server → cli\n                                                                  ↕\n                    dashboard, elicitation, enterprise-bridge, flows, present, settings-ui, aikit-client\n```\n\n- **MCP server**: 61 tools + 2 resources (via `@modelcontextprotocol/sdk`)\n- **CLI**: 49 commands (thin dispatcher + 11 command groups)\n- **Search**: Hybrid vector + keyword + RRF fusion\n- **Embeddings**: ONNX local (mxbai-embed-large-v1, 512 dimensions, int8 quantized)\n- **Vector store**: SQLite-vec (embedded, zero infrastructure)\n- **Chunking**: Tree-sitter AST (TS/JS/Python/Go/Rust/Java) + regex fallback\n- **Dashboard**: Web-based dashboard for knowledge graph visualization and settings management\n\n## Session Protocol (MANDATORY)\n\n### Start (do ALL)\n```\nflow({ action: \'status\' })                                     # Check/resume active flow FIRST\n# If flow active → flow({ action: \'read\', step }) → follow step instructions\nstatus({})                                                     # Check AI Kit health + onboard state\n# If onboard not run → onboard({ path: "." })                 # First-time codebase analysis\nflow({ action: \'list\' })                                       # See available flows\n# Select flow based on task → flow({ action: \'start\', name: "<name>", topic: "<task>" })  # Start — creates .flows/{topic}/\nknowledge({ action: "list" })                                 # 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)\nknowledge({ action: "remember", ... })              (capture insights)\n```\n\n### End of Session\n```\nsession_digest({ persist: true })                              # Auto-capture session activity\nknowledge({ action: "remember", title: "Session checkpoint: <topic>", content: "<what was done, decisions made, next steps>", category: "conventions" })\n```\n\n## Tool Catalog\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 (2)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `analyze` | `aikit analyze <aspect>` | Unified analyzer for structure, dependencies, symbols, patterns, entry_points, and diagram aspects |\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 (4)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `eval` | `aikit eval` | Sandboxed JavaScript/TypeScript execution |\n| `check` | `aikit check` | Incremental typecheck + lint. `detail` param: efficient (default, minimal), normal (parsed errors), full (includes raw) |\n| `test_run` | `aikit test` | Run tests with structured pass/fail results |\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 (2)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `knowledge` | `aikit knowledge <action>` | Unified knowledge tool for remember, read, update, forget, and list actions |\n| `produce_knowledge` | — | Auto-generate knowledge from analysis |\n\n### Auto-Knowledge (automatic)\n\nTool outputs are automatically analyzed after every call. Useful facts (conventions, test patterns, build commands, errors) are extracted and stored as curated entries. Quality gate (score >= 0.3), deduplication, TTL for transient facts, max 50/session.\n\nSearch auto-knowledge with: `search({ query: "...", origin: "curated" })` or `knowledge({ action: "list", category: "conventions" })`\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` | — | Multi-provider web search (DuckDuckGo + Bing-HTML + Mojeek fan-out, no API key needed) |\n| `http` | — | Make HTTP requests for API testing/debugging |\n\n### Developer Utilities (7)\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| `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 (aikit.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 (1)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `flow` | `aikit flow` | Manage flows — list, start, navigate steps, read instructions, inspect runs, add/remove/update. |\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 IDE chat panel), always use `format: "browser"`** — `html` UIResource is invisible in terminal. |\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## Execution & Data Tools\n\n### `eval` — Execute Code in Sandbox\n\nRun JavaScript or TypeScript snippets in a constrained VM. Captures console output and return values.\n\n**Parameters:**\n| Param | Type | Default | Description |\n|-------|------|---------|-------------|\n| `code` | string | — | Code to execute |\n| `lang` | `"js"` \\| `"ts"` | `"js"` | Language mode (ts strips type syntax first) |\n| `timeout` | number | 5000 | Execution timeout in ms (max 60000) |\n\n**Examples:**\n```\n// Quick calculation\neval({ code: "return [1,2,3].reduce((a,b) => a+b, 0)" })\n\n// Process data\neval({ code: "const data = [1,2,3,4,5]; return { sum: data.reduce((a,b)=>a+b), avg: data.reduce((a,b)=>a+b)/data.length }" })\n\n// TypeScript\neval({ code: "interface Point { x: number; y: number }; const p: Point = {x: 1, y: 2}; return p.x + p.y", lang: "ts" })\n```\n\n---\n\n### `data_transform` — jq-like JSON Transforms\n\nApply jq-inspired expressions to JSON input for filtering, projection, grouping, and extraction.\n\n**Parameters:**\n| Param | Type | Description |\n|-------|------|-------------|\n| `input` | string | JSON string to transform |\n| `expression` | string | Transform expression (see syntax below) |\n\n**Supported Expressions:**\n\n| Expression | Description | Example |\n|------------|-------------|---------|\n| `.` | Identity (return input as-is) | `.` |\n| `.field` | Access object field | `.name` |\n| `.[N]` | Array index access | `.[0]` |\n| `.field1.field2` | Nested field access | `.user.name` |\n| `| filter(condition)` | Filter array items | `| filter(.age > 18)` |\n| `| map(expr)` | Transform each item | `| map(.name)` |\n| `| sort_by(.field)` | Sort by field | `| sort_by(.date)` |\n| `| group_by(.field)` | Group items by field | `| group_by(.category)` |\n| `| select(cond)` | Keep items matching condition | `| select(.active == true)` |\n| `| flatten` | Flatten nested arrays | `| flatten` |\n| `| unique` | Remove duplicates | `| unique` |\n| `| keys` | Get object keys | `| keys` |\n| `| values` | Get object values | `| values` |\n| `| length` | Array/string length | `| length` |\n| `| join(sep)` | Join array with separator | `| join(", ")` |\n| `| first` | First element | `| first` |\n| `| last` | Last element | `| last` |\n| `| sum` | Sum numeric array | `| sum` |\n| `| avg` | Average of numeric array | `| avg` |\n| `| min` / `| max` | Min/max value | `| min` |\n\n**Comparisons:** `==`, `!=`, `>`, `<`, `>=`, `<=`\n**Logical:** `and`, `or`, `not`\n\n**Examples:**\n```\n// Filter and project\ndata_transform({ input: \'[{"name":"Alice","age":30},{"name":"Bob","age":17}]\', expression: \'| filter(.age >= 18) | map(.name)\' })\n// → ["Alice"]\n\n// Group and count\ndata_transform({ input: \'[{"type":"bug"},{"type":"feat"},{"type":"bug"}]\', expression: \'| group_by(.type)\' })\n// → {"bug":[...], "feat":[...]}\n\n// Sort and take first\ndata_transform({ input: \'[{"score":3},{"score":1},{"score":5}]\', expression: \'| sort_by(.score) | first\' })\n// → {"score":1}\n```\n\n---\n\n### `time` — Date & Time Operations\n\nParse dates, convert timezones, calculate durations, add time. Supports ISO 8601, unix timestamps, and human-readable formats.\n\n**Parameters:**\n| Param | Type | Description |\n|-------|------|-------------|\n| `operation` | string | `now`, `parse`, `convert`, `diff`, `add` |\n| `input` | string | Date input (ISO, unix, or parseable string). For `diff`: two comma-separated dates |\n| `timezone` | string | Target timezone (e.g., "America/New_York") |\n| `duration` | string | Duration to add (e.g., "2h30m", "1d", "30s") — for `add` |\n\n**Operations:**\n| Op | Purpose | Example |\n|----|---------|---------|\n| `now` | Current time in all formats | `time({ operation: "now" })` |\n| `parse` | Parse any date string | `time({ operation: "parse", input: "2024-03-15T10:30:00Z" })` |\n| `convert` | Convert to timezone | `time({ operation: "convert", input: "2024-03-15T10:30:00Z", timezone: "Asia/Tokyo" })` |\n| `diff` | Duration between dates | `time({ operation: "diff", input: "2024-01-01,2024-12-31" })` |\n| `add` | Add duration to date | `time({ operation: "add", input: "2024-03-15", duration: "2h30m" })` |\n\n**Duration format:** Combine: `Nd` (days), `Nh` (hours), `Nm` (minutes), `Ns` (seconds)\nExample: `"1d2h30m"` = 1 day, 2 hours, 30 minutes\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({ action: \'list\' })                                   # See available flows\nflow({ action: \'info\', name: \'aikit:basic\' })              # View steps, skills, agents\nflow({ action: \'start\', name: \'aikit:basic\', topic: \'Fix login bug\' })  # Start — creates .flows/fix-login-bug/\nflow({ action: \'read\' })                                   # Read current step\'s instructions ({{artifacts_path}} resolved)\n# ... do the work described in the instruction ...\nflow({ action: \'step\', advance: \'next\' })                  # Advance to next step\nflow({ action: \'step\', advance: \'skip\' })                  # Skip current step\nflow({ action: \'step\', advance: \'redo\' })                  # Redo current step\nflow({ action: \'status\' })                                 # Check progress (includes slug, runDir, artifactsPath, phase, isEpilogue)\nflow({ action: \'reset\' })                                  # Abandon active flow\nflow({ action: \'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({ action: \'status\' }) shows phase: \'after\', isEpilogue: true during epilogue\n```\n\nCustom flow lifecycle management:\n\n```text\nflow({ action: \'add\', source: \'.github/flows/my-flow\' })\nflow({ action: \'update\', name: \'my-flow\' })\nflow({ action: \'remove\', name: \'my-flow\' })\n```\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` | Multi-provider web search without browser — **unique to AI Kit** |\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({ aspect: "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## Token Efficiency\n\n`config.tokenBudget` controls output verbosity globally:\n\n| Level | Output | Compression | Context Strategy |\n|-------|--------|-------------|------------------|\n| `efficient` (default) | Minimal output, score + top issues only | threshold 2000, budget 1000 | `stratum_card(T1)` |\n| `normal` | Standard output with parsed errors/pattern names | threshold 4000, budget 2000 | `compact()` |\n| `full` | Maximum detail with raw output/full tables | No compression | `digest()` |\n\nSet via: `config({ action: \'update\', updates: { tokenBudget: \'normal\' } })`\n\nTools with `detail` param inherit from `config.tokenBudget` when not explicitly set.\nCompression middleware applies to ALL tool responses automatically.\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({ aspect: "structure", path: "src/" })\n→ analyze({ aspect: "dependencies", path: "src/" })\n→ analyze({ aspect: "entry_points", path: "src/" })\n→ produce_knowledge({ path: "src/" })\n→ knowledge({ action: "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### Multi-Task Orchestration (DAG Queue)\n```\nqueue({ action: "create", name: "my-tasks" })\n→ queue({ action: "push", name: "my-tasks", title: "Task 1", data: { deps: [] } })\n→ queue({ action: "push", name: "my-tasks", title: "Task 2", data: { deps: ["task-1-id"] } })\n→ queue({ action: "next", name: "my-tasks" })   # Gets next ready task\n→ [do work]\n→ queue({ action: "done", name: "my-tasks", id: "<id>" })\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→ knowledge({ action: "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\n\n| Action | Tool | Category |\n|--------|------|----------|\n| Store | `knowledge({ action: "remember", title, content, category })` | conventions, decisions, patterns, context, session |\n| Search | `search({ query, origin: "curated" })` | — |\n| Browse | `knowledge({ action: "list" })` or `knowledge({ action: "list", category })` | — |\n| Read | `knowledge({ action: "read", id })` | — |\n| Update | `knowledge({ action: "update", id, content })` | — |\n| Remove | `knowledge({ action: "forget", id })` | — |\n\n**Session checkpoint** (end of session): `knowledge({ action: "remember", title: "Session checkpoint: <topic>", content: "Done/Decisions/Next/Blockers", category: "session" })`\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 efficient|normal|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`aikit.config.json` in project root:\n```json\n{\n  "sources": [{ "path": ".", "excludePatterns": ["**/node_modules/**", "**/dist/**", "**/build/**", "**/.git/**", "**/.aikit-data/**", "**/coverage/**"] }],\n  "indexing": { "chunkSize": 1500, "chunkOverlap": 200, "minChunkSize": 100 },\n  "embedding": { "model": "mixedbread-ai/mxbai-embed-large-v1", "dimensions": 1024 },\n  "store": { "backend": "sqlite-vec", "path": ".aikit-data" },\n  "curated": { "path": ".ai/curated" }\n}\n```\n\n## Tool Profiles\n\nTool profiles control which subset of the 61 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 `aikit.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## Development (Self-Dogfooding)\n\nWhen developing @vpxa/aikit itself: always `pnpm build` before using CLI/server (runs from `dist/`), and always `reindex` after structural code changes.\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` | Check if a flow is active + current step + phase (before/flow/after) + isEpilogue |\n\nDifferent `action` values handle listing, starting, reading steps, advancing, resets, run inspection, and add/update/remove flow management.\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({ action: \'list\' })` → choose flow → `flow({ action: \'start\', name: "<name>", topic: "<task>" })`\n2. **Each step**: `flow({ action: \'read\', step: "<name>" })` → follow step instructions → complete work\n3. **Advance**: `flow({ action: \'step\', advance: \'next\' })` → repeat from step 2\n4. **Epilogue**: After last flow step, mandatory epilogue steps run (e.g., `_docs-sync` updates `docs/`)\n5. **Resume**: `flow({ action: \'status\' })` → if active, `flow({ action: \'read\' })` for current step → continue\n6. **Reset**: `flow({ action: \'reset\' })` if you need to start over\n\n---\n\n## Reference Documentation\n\nFor detailed patterns on specific topics, load these reference files:\n\n| Topic | File | When to load |\n|-------|------|-------------|\n| Multi-task orchestration | `references/coordination.md` | Queue, DAG, lanes, worksets, stash, checkpoints |\n| Quality gates (FORGE) | `references/forge-protocol.md` | Complex tasks, evidence maps, tier classification |\n| Search & relationships | `references/search-patterns.md` | Finding code, tracing data flow, graph traversal |\n'},{file:`references/coordination.md`,content:`# Coordination & Multi-Task Orchestration
+var e=[{file:`SKILL.md`,content:'---\nname: aikit\ndescription: "Use the @vpxa/aikit AI Kit MCP server for codebase search, analysis, and persistent memory. Load when using any aikit_* tool. 61 tools: search (hybrid/semantic/keyword), code analysis (structure, deps, symbols, patterns, entry points, diagrams, blast radius), knowledge graph (module/symbol/import traversal), context (worksets, stash, checkpoints, lanes), code manipulation (rename, codemod, eval), validation (check, test_run, audit), knowledge (remember/read/update/forget/list/withdraw/flush), web (fetch, search, http), FORGE (ground, classify, evidence map, stratum cards, digest), flows (list, start, step, read, runs, add/remove/update), presentation (dashboards), onboarding, meta-tools, and utilities (regex, encode, measure, changelog, schema-validate, 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 — 61 MCP tools for search, analysis, context compression, FORGE quality gates, knowledge management, code manipulation, execution, web access, flow management, presentation, meta-tool discovery, 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\n## Skills Reference\n\n| Context | Skill | Load when |\n|---------|-------|----------|\n| AI Kit search, analysis, memory | `aikit` | **Always load at session start.** Tool signatures, workflows, session protocol. |\n| Brainstorming & design | `brainstorming` | Before any creative/design work — new features, components, behavior changes. |\n| Session context preservation | `session-handoff` | Context window filling up, session ending, or major milestone completed. |\n| Requirements scoring | `requirements-clarity` | Before planning vague or complex features — score 0-100 until ≥ 90. |\n| Engineering lessons | `lesson-learned` | After completing work — extract principles from git diffs. |\n| Architecture diagrams | `c4-architecture` | When documenting or reviewing architecture — C4 Mermaid diagrams. |\n| Architecture decisions | `adr-skill` | When making non-trivial technical decisions — executable ADRs. |\n| Rich presentation | `present` | When presenting dashboards, charts, tables, or complex visual content to users. |\n| TypeScript patterns | `typescript` | Before TypeScript implementation — type system, compiler config, advanced types. |\n| React patterns | `react` | Before React work — component architecture, React 19 APIs, Server Components. |\n| Frontend design | `frontend-design` | Before UI/UX work — visual design, typography, color, layout, accessibility. |\n| Multi-agent orchestration | `multi-agents-development` | Before delegating to multiple agents — task decomposition, dispatch, review pipelines. |\n| Living documentation | `docs` | When creating or updating project documentation — Diátaxis framework, staleness detection. |\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| Browser automation & auth | `browser-use` | When needing browser interaction — login flows, SAML SSO bypass, cookie extraction, form filling, web scraping, or authenticated browsing. Pairs with `repo-access` for auth recovery via browser. |\n\n## Architecture\n\n16-package monorepo published as a single npm package:\n\n```\ncore → store → embeddings → chunker → indexer → analyzers → tools → server → cli\n                                                                  ↕\n                    dashboard, elicitation, enterprise-bridge, flows, present, settings-ui, aikit-client\n```\n\n- **MCP server**: 61 tools + 2 resources (via `@modelcontextprotocol/sdk`)\n- **CLI**: 49 commands (thin dispatcher + 11 command groups)\n- **Search**: Hybrid vector + keyword + RRF fusion\n- **Embeddings**: ONNX local (mxbai-embed-large-v1, 512 dimensions, int8 quantized)\n- **Vector store**: SQLite-vec (embedded, zero infrastructure)\n- **Chunking**: Tree-sitter AST (TS/JS/Python/Go/Rust/Java) + regex fallback\n- **Dashboard**: Web-based dashboard for knowledge graph visualization and settings management\n\n## Session Protocol (MANDATORY)\n\n### Start (do ALL)\n```\nflow({ action: \'status\' })                                     # Check/resume active flow FIRST\n# If flow active → flow({ action: \'read\', step }) → follow step instructions\nstatus({})                                                     # Check AI Kit health + onboard state\n# If onboard not run → onboard({ path: "." })                 # First-time codebase analysis\nflow({ action: \'list\' })                                       # See available flows\n# Select flow based on task → flow({ action: \'start\', name: "<name>", topic: "<task>" })  # Start — creates .flows/{topic}/\nknowledge({ action: "list" })                                 # 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)\nknowledge({ action: "remember", ... })              (capture insights)\n```\n\n### End of Session\n```\nsession_digest({ persist: true })                              # Auto-capture session activity\nknowledge({ action: "remember", title: "Session checkpoint: <topic>", content: "<what was done, decisions made, next steps>", category: "conventions" })\n```\n\n## Tool Catalog\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 (2)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `analyze` | `aikit analyze <aspect>` | Unified analyzer for structure, dependencies, symbols, patterns, entry_points, and diagram aspects |\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 (4)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `eval` | `aikit eval` | Sandboxed JavaScript/TypeScript execution |\n| `check` | `aikit check` | Incremental typecheck + lint. `detail` param: efficient (default, minimal), normal (parsed errors), full (includes raw) |\n| `test_run` | `aikit test` | Run tests with structured pass/fail results |\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 (2)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `knowledge` | `aikit knowledge <action>` | Unified knowledge tool for remember, read, update, forget, list, withdraw, and flush actions |\n| `produce_knowledge` | — | Auto-generate knowledge from analysis |\n\n### Auto-Knowledge (automatic)\n\nTool outputs are automatically analyzed after every call. Useful facts (conventions, test patterns, build commands, errors) are extracted and stored as curated entries. Quality gate (score >= 0.3), deduplication, TTL for transient facts, max 50/session.\n\nSearch auto-knowledge with: `search({ query: "...", origin: "curated" })` or `knowledge({ action: "list", category: "conventions" })`\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` | — | Multi-provider web search (DuckDuckGo + Bing-HTML + Mojeek fan-out, no API key needed) |\n| `http` | — | Make HTTP requests for API testing/debugging |\n\n### Developer Utilities (7)\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| `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 (aikit.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 (1)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `flow` | `aikit flow` | Manage flows — list, start, navigate steps, read instructions, inspect runs, add/remove/update. |\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 IDE chat panel), always use `format: "browser"`** — `html` UIResource is invisible in terminal. |\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## Execution & Data Tools\n\n### `eval` — Execute Code in Sandbox\n\nRun JavaScript or TypeScript snippets in a constrained VM. Captures console output and return values.\n\n**Parameters:**\n| Param | Type | Default | Description |\n|-------|------|---------|-------------|\n| `code` | string | — | Code to execute |\n| `lang` | `"js"` \\| `"ts"` | `"js"` | Language mode (ts strips type syntax first) |\n| `timeout` | number | 5000 | Execution timeout in ms (max 60000) |\n\n**Examples:**\n```\n// Quick calculation\neval({ code: "return [1,2,3].reduce((a,b) => a+b, 0)" })\n\n// Process data\neval({ code: "const data = [1,2,3,4,5]; return { sum: data.reduce((a,b)=>a+b), avg: data.reduce((a,b)=>a+b)/data.length }" })\n\n// TypeScript\neval({ code: "interface Point { x: number; y: number }; const p: Point = {x: 1, y: 2}; return p.x + p.y", lang: "ts" })\n```\n\n---\n\n### `data_transform` — jq-like JSON Transforms\n\nApply jq-inspired expressions to JSON input for filtering, projection, grouping, and extraction.\n\n**Parameters:**\n| Param | Type | Description |\n|-------|------|-------------|\n| `input` | string | JSON string to transform |\n| `expression` | string | Transform expression (see syntax below) |\n\n**Supported Expressions:**\n\n| Expression | Description | Example |\n|------------|-------------|---------|\n| `.` | Identity (return input as-is) | `.` |\n| `.field` | Access object field | `.name` |\n| `.[N]` | Array index access | `.[0]` |\n| `.field1.field2` | Nested field access | `.user.name` |\n| `| filter(condition)` | Filter array items | `| filter(.age > 18)` |\n| `| map(expr)` | Transform each item | `| map(.name)` |\n| `| sort_by(.field)` | Sort by field | `| sort_by(.date)` |\n| `| group_by(.field)` | Group items by field | `| group_by(.category)` |\n| `| select(cond)` | Keep items matching condition | `| select(.active == true)` |\n| `| flatten` | Flatten nested arrays | `| flatten` |\n| `| unique` | Remove duplicates | `| unique` |\n| `| keys` | Get object keys | `| keys` |\n| `| values` | Get object values | `| values` |\n| `| length` | Array/string length | `| length` |\n| `| join(sep)` | Join array with separator | `| join(", ")` |\n| `| first` | First element | `| first` |\n| `| last` | Last element | `| last` |\n| `| sum` | Sum numeric array | `| sum` |\n| `| avg` | Average of numeric array | `| avg` |\n| `| min` / `| max` | Min/max value | `| min` |\n\n**Comparisons:** `==`, `!=`, `>`, `<`, `>=`, `<=`\n**Logical:** `and`, `or`, `not`\n\n**Examples:**\n```\n// Filter and project\ndata_transform({ input: \'[{"name":"Alice","age":30},{"name":"Bob","age":17}]\', expression: \'| filter(.age >= 18) | map(.name)\' })\n// → ["Alice"]\n\n// Group and count\ndata_transform({ input: \'[{"type":"bug"},{"type":"feat"},{"type":"bug"}]\', expression: \'| group_by(.type)\' })\n// → {"bug":[...], "feat":[...]}\n\n// Sort and take first\ndata_transform({ input: \'[{"score":3},{"score":1},{"score":5}]\', expression: \'| sort_by(.score) | first\' })\n// → {"score":1}\n```\n\n---\n\n### `time` — Date & Time Operations\n\nParse dates, convert timezones, calculate durations, add time. Supports ISO 8601, unix timestamps, and human-readable formats.\n\n**Parameters:**\n| Param | Type | Description |\n|-------|------|-------------|\n| `operation` | string | `now`, `parse`, `convert`, `diff`, `add` |\n| `input` | string | Date input (ISO, unix, or parseable string). For `diff`: two comma-separated dates |\n| `timezone` | string | Target timezone (e.g., "America/New_York") |\n| `duration` | string | Duration to add (e.g., "2h30m", "1d", "30s") — for `add` |\n\n**Operations:**\n| Op | Purpose | Example |\n|----|---------|---------|\n| `now` | Current time in all formats | `time({ operation: "now" })` |\n| `parse` | Parse any date string | `time({ operation: "parse", input: "2024-03-15T10:30:00Z" })` |\n| `convert` | Convert to timezone | `time({ operation: "convert", input: "2024-03-15T10:30:00Z", timezone: "Asia/Tokyo" })` |\n| `diff` | Duration between dates | `time({ operation: "diff", input: "2024-01-01,2024-12-31" })` |\n| `add` | Add duration to date | `time({ operation: "add", input: "2024-03-15", duration: "2h30m" })` |\n\n**Duration format:** Combine: `Nd` (days), `Nh` (hours), `Nm` (minutes), `Ns` (seconds)\nExample: `"1d2h30m"` = 1 day, 2 hours, 30 minutes\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({ action: \'list\' })                                   # See available flows\nflow({ action: \'info\', name: \'aikit:basic\' })              # View steps, skills, agents\nflow({ action: \'start\', name: \'aikit:basic\', topic: \'Fix login bug\' })  # Start — creates .flows/fix-login-bug/\nflow({ action: \'read\' })                                   # Read current step\'s instructions ({{artifacts_path}} resolved)\n# ... do the work described in the instruction ...\nflow({ action: \'step\', advance: \'next\' })                  # Advance to next step\nflow({ action: \'step\', advance: \'skip\' })                  # Skip current step\nflow({ action: \'step\', advance: \'redo\' })                  # Redo current step\nflow({ action: \'status\' })                                 # Check progress (includes slug, runDir, artifactsPath, phase, isEpilogue)\nflow({ action: \'reset\' })                                  # Abandon active flow\nflow({ action: \'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({ action: \'status\' }) shows phase: \'after\', isEpilogue: true during epilogue\n```\n\nCustom flow lifecycle management:\n\n```text\nflow({ action: \'add\', source: \'.github/flows/my-flow\' })\nflow({ action: \'update\', name: \'my-flow\' })\nflow({ action: \'remove\', name: \'my-flow\' })\n```\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` | Multi-provider web search without browser — **unique to AI Kit** |\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({ aspect: "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## Token Efficiency\n\n`config.tokenBudget` controls output verbosity globally:\n\n| Level | Output | Compression | Context Strategy |\n|-------|--------|-------------|------------------|\n| `efficient` (default) | Minimal output, score + top issues only | threshold 2000, budget 1000 | `stratum_card(T1)` |\n| `normal` | Standard output with parsed errors/pattern names | threshold 4000, budget 2000 | `compact()` |\n| `full` | Maximum detail with raw output/full tables | No compression | `digest()` |\n\nSet via: `config({ action: \'update\', updates: { tokenBudget: \'normal\' } })`\n\nTools with `detail` param inherit from `config.tokenBudget` when not explicitly set.\nCompression middleware applies to ALL tool responses automatically.\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({ aspect: "structure", path: "src/" })\n→ analyze({ aspect: "dependencies", path: "src/" })\n→ analyze({ aspect: "entry_points", path: "src/" })\n→ produce_knowledge({ path: "src/" })\n→ knowledge({ action: "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### Multi-Task Orchestration (DAG Queue)\n```\nqueue({ action: "create", name: "my-tasks" })\n→ queue({ action: "push", name: "my-tasks", title: "Task 1", data: { deps: [] } })\n→ queue({ action: "push", name: "my-tasks", title: "Task 2", data: { deps: ["task-1-id"] } })\n→ queue({ action: "next", name: "my-tasks" })   # Gets next ready task\n→ [do work]\n→ queue({ action: "done", name: "my-tasks", id: "<id>" })\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→ knowledge({ action: "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\n\n| Action | Tool | Category |\n|--------|------|----------|\n| Store | `knowledge({ action: "remember", title, content, category })` | conventions, decisions, patterns, context, session |\n| Search | `search({ query, origin: "curated" })` | — |\n| Browse | `knowledge({ action: "list" })` or `knowledge({ action: "list", category })` | — |\n| Read | `knowledge({ action: "read", id })` | — |\n| Update | `knowledge({ action: "update", id, content })` | — |\n| Remove | `knowledge({ action: "forget", id })` | — |\n| Withdraw | `knowledge({ action: "withdraw", scope: "flow:<run-id>", profile: "<role>", budget: 4000 })` | Flow-scoped context retrieval |\n| Flush | `knowledge({ action: "flush", scope: "flow:<run-id>" })` | Clean up flow context |\n\n**Session checkpoint** (end of session): `knowledge({ action: "remember", title: "Session checkpoint: <topic>", content: "Done/Decisions/Next/Blockers", category: "session" })`\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 efficient|normal|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`aikit.config.json` in project root:\n```json\n{\n  "sources": [{ "path": ".", "excludePatterns": ["**/node_modules/**", "**/dist/**", "**/build/**", "**/.git/**", "**/.aikit-data/**", "**/coverage/**"] }],\n  "indexing": { "chunkSize": 1500, "chunkOverlap": 200, "minChunkSize": 100 },\n  "embedding": { "model": "mixedbread-ai/mxbai-embed-large-v1", "dimensions": 1024 },\n  "store": { "backend": "sqlite-vec", "path": ".aikit-data" },\n  "curated": { "path": ".ai/curated" }\n}\n```\n\n## Tool Profiles\n\nTool profiles control which subset of the 61 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 `aikit.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## Development (Self-Dogfooding)\n\nWhen developing @vpxa/aikit itself: always `pnpm build` before using CLI/server (runs from `dist/`), and always `reindex` after structural code changes.\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` | Check if a flow is active + current step + phase (before/flow/after) + isEpilogue |\n\nDifferent `action` values handle listing, starting, reading steps, advancing, resets, run inspection, and add/update/remove flow management.\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({ action: \'list\' })` → choose flow → `flow({ action: \'start\', name: "<name>", topic: "<task>" })`\n2. **Each step**: `flow({ action: \'read\', step: "<name>" })` → follow step instructions → complete work\n3. **Advance**: `flow({ action: \'step\', advance: \'next\' })` → repeat from step 2\n4. **Epilogue**: After last flow step, mandatory epilogue steps run (e.g., `_docs-sync` updates `docs/`)\n5. **Resume**: `flow({ action: \'status\' })` → if active, `flow({ action: \'read\' })` for current step → continue\n6. **Reset**: `flow({ action: \'reset\' })` if you need to start over\n\n---\n\n## Reference Documentation\n\nFor detailed patterns on specific topics, load these reference files:\n\n| Topic | File | When to load |\n|-------|------|-------------|\n| Multi-task orchestration | `references/coordination.md` | Queue, DAG, lanes, worksets, stash, checkpoints |\n| Quality gates (FORGE) | `references/forge-protocol.md` | Complex tasks, evidence maps, tier classification |\n| Search & relationships | `references/search-patterns.md` | Finding code, tracing data flow, graph traversal |\n'},{file:`references/coordination.md`,content:`# Coordination & Multi-Task Orchestration
 
 Patterns for managing multiple tasks, parallel exploration, and session state.
 

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

@@ -1626,6 +1626,25 @@ Icons appear automatically in step nodes. No configuration needed — the viewer
 3. Order by dependency graph — a step should only reference concepts from prior steps
 4. Aim for 5-12 steps per tour (more → split into multiple tours)
 5. Each step teaches exactly ONE concept
+
+### Interactive C4 Architecture Visualization
+
+For architecture documentation, generate interactive C4 diagrams using the shipped **c4-viewer.html** from the \`c4-architecture\` skill.
+
+**Integration with docs skill:**
+- Architecture docs in \`docs/architecture/\` MUST have interactive HTML companions in \`docs/architecture/interactive/\`
+- Use the \`c4-architecture\` skill to generate C4 viewer HTML — it handles JSON schema, ReactFlow rendering, and ELK auto-layout
+- The \`c4-architecture\` skill provides: zoom/pan, node search, detail panels, drag-to-rearrange, and professional styling
+
+**Workflow:**
+1. During Phase 5 (Domain Docs), identify system-level architecture views
+2. For EACH architecture view (system context, container, component):
+  - Generate C4 JSON data: \`{nodes: [{id, label, type, description, technology}], edges: [{from, to, label}]}\`
+  - Use the \`c4-architecture\` skill to render interactive HTML
+  - Save to \`docs/architecture/interactive/{view-name}.html\`
+3. Cross-reference: link from markdown docs to interactive viewers
+
+**CRITICAL:** NEVER generate architecture HTML from scratch. ALWAYS use the shipped c4-viewer.html via the \`c4-architecture\` skill. Hand-crafted HTML will be inconsistent and unprofessional.
 ## Documentation Generation Prompts
 
 Structured LLM prompt templates for generating high-quality documentation. Each produces strict JSON for consistent, parseable output.
@@ -1785,7 +1804,7 @@ graph({ action: "find_nodes" })                  # Full module graph
 4. Output: layers.json used by tour generation
 \`\`\`
 
-### Phase 4 — Generate Tours (2-phase)
+### Phase 4 — Generate Tours (3-phase)
 \`\`\`
 # Phase 4a: Deterministic ranking
 1. Compute node rankings (in-degree, centrality, layer)
@@ -1794,8 +1813,17 @@ graph({ action: "find_nodes" })                  # Full module graph
 
 # Phase 4b: LLM narrative
 1. Apply Tour Generation Prompt with rankings from 4a
-2. Generate both Mermaid tour diagram AND tour JSON data for shipped viewer
-3. Output: docs/tours/getting-started.md + docs/tours/interactive/
+2. Generate Mermaid tour diagram for markdown docs
+3. Generate tour JSON data matching the shipped viewer schema
+4. Output: docs/tours/{name}.md (markdown with Mermaid diagram)
+
+# Phase 4c: Interactive HTML generation (MANDATORY)
+1. For EACH tour generated in 4b:
+  - Read the shipped tour-viewer.html from assets
+  - Inject the tour JSON into the viewer's data block
+  - Save to docs/tours/interactive/{name}.html
+2. These interactive HTML files are MANDATORY — never skip this step
+3. The result is a professional ReactFlow-based tour with step navigation, code panels, and BFS layout
 \`\`\`
 
 ### Phase 5 — Generate Domain Docs (LLM-assisted)
@@ -1807,13 +1835,33 @@ graph({ action: "find_nodes" })                  # Full module graph
 4. Output: docs/architecture/domains/{domain}.md
 \`\`\`
 
-### Phase 6 — Validate & Cross-Reference
+### Phase 6 — Interactive Architecture HTML (MANDATORY)
+\`\`\`
+# Generate professional interactive C4 viewers for architecture documentation
+1. Identify architecture views from Phase 3 (layers) and Phase 5 (domain analysis):
+  - System Context: overall system boundaries and external actors
+  - Container: major deployable units and their relationships
+  - Component: internal structure of key containers
+2. For EACH architecture view:
+  - Generate C4 JSON data (nodes + edges with types and descriptions)
+  - Use the c4-architecture skill to produce interactive HTML with ELK auto-layout
+  - Save to docs/architecture/interactive/{view-name}.html
+3. Add navigation links:
+  - From docs/architecture/overview.md → link to interactive viewers
+  - From tour steps that reference architecture → link to relevant C4 view
+4. Generate documentation hub:
+  - Use the present tool's docs-browser block type to create a navigable index
+  - Include all markdown docs with status indicators and links to interactive companions
+\`\`\`
+
+### Phase 7 — Validate & Cross-Reference
 \`\`\`
 # Ensure consistency
 1. Check all internal doc links resolve
 2. Verify code references still exist (file:line citations)
 3. Cross-reference tour steps with actual files
 4. check({}) to ensure no build breaks
+5. Verify all interactive HTML files open correctly and contain valid JSON data
 \`\`\`
 
 ### Output Structure

package/scaffold/dist/definitions/skills/multi-agents-development.mjs

@@ -867,6 +867,89 @@ DOCUMENT → remember what went wrong, update plan
 
 ---
 
+## §11 Flow Context Sharing
+
+### The Problem
+Subagents start fresh — they don't know what the Orchestrator already analyzed. Without context sharing, each subagent redundantly re-reads and re-analyzes the same files, wasting tokens and time.
+
+### The Solution: Flow Context Broker
+The \`knowledge\` tool has flow-scoped context actions that enable automatic context sharing between the Orchestrator and subagents during a flow.
+
+**How it works:**
+1. **Auto-deposit** — The auto-knowledge interceptor captures results from \`search\`, \`file_summary\`, \`stratum_card\`, \`compact\`, \`blast_radius\`, and \`scope_map\` as flow-scoped context entries
+2. **Role-filtered retrieval** — Before dispatching a subagent, the Orchestrator calls \`withdraw\` with a role profile to get relevant context
+3. **Manual deposit** — Subagents deposit their own discoveries for later agents
+4. **Cleanup** — On flow completion or reset, \`flush\` removes all flow context
+
+### Orchestrator Workflow
+
+#### Before Dispatching a Subagent
+
+\`\`\`
+// Get role-filtered context for the subagent
+knowledge({ action: 'withdraw', profile: '<role>', budget: 6000 })
+// Profiles: implementer, documenter, reviewer, researcher, debugger
+\`\`\`
+
+Include the withdrawn context in the subagent's prompt under "## 3. Architectural Context" (from the 6-point template in §5).
+
+#### After All Work Completes
+
+\`\`\`
+// Clean up flow context on flow completion
+knowledge({ action: 'flush' })
+\`\`\`
+
+### Subagent Deposit Pattern
+
+Subagents can deposit discoveries for later agents:
+
+\`\`\`
+// Subagent deposits a finding for future agents
+knowledge({ action: 'remember', scope: 'flow', title: 'API validation pattern', content: '...' })
+\`\`\`
+
+### Profile Filtering
+
+Each profile prioritizes different context types:
+
+| Profile | Priorities (highest first) | Use For |
+|---------|---------------------------|---------|
+| \`implementer\` | decisions, patterns, file-cards | Implementer, Frontend, Refactor |
+| \`documenter\` | decisions, step-summaries, analysis | Documenter |
+| \`reviewer\` | decisions, patterns, analysis | Code-Reviewer, Architect-Reviewer |
+| \`researcher\` | search-results, analysis, decisions | Researcher-Alpha/Beta/Gamma/Delta |
+| \`debugger\` | file-cards, analysis, search-results | Debugger |
+
+### Budget Management
+
+The \`budget\` parameter (default: 6000 chars) caps the total context returned. Adjust based on task complexity:
+
+| Task Type | Recommended Budget |
+|-----------|--------------------|
+| Micro (1 file fix) | 2000 |
+| Standard implementation | 6000 |
+| Complex multi-file | 10000 |
+| Research/investigation | 8000 |
+
+### Integration with 6-Point Template
+
+Update the prompt template from §5 to include flow context:
+
+\`\`\`markdown
+## 3. Architectural Context
+[Paste the result of knowledge({ action: 'withdraw', profile: '<role>' })]
+[Supplement with additional compact/digest if the withdrawn context is insufficient]
+\`\`\`
+
+### Key Rules
+
+1. **Always withdraw before dispatch** — even if context seems small, it prevents redundant work
+2. **Flush on completion** — flow context is temporary; don't let it accumulate across flows
+3. **Profile matters** — a reviewer needs different context than an implementer
+4. **Budget caps prevent bloat** — large context confuses subagents, keep it focused
+5. **Auto-deposit is passive** — it captures tool output automatically, no extra calls needed
+
 ## Prompt Template Reference
 
 Detailed prompt templates are provided as sidecar files:

package/scaffold/generated/block-docs.mjs

@@ -1,6 +1,6 @@
 // AUTO-GENERATED - do not edit manually.
 // Source: packages/server/src/tools/present/block-registry.ts
-// Generated at: 2026-05-10T14:06:21.809Z
+// Generated at: 2026-05-11T01:24:09.989Z
 
 export const ALL_BLOCK_DOCS = "| Type | Description | Value Shape |\n|------|-------------|-------------|\n| `markdown` | Markdown content rendered with the marked parser. | `string` |\n| `code` | Formatted code block rendered inside pre/code tags. | `string` |\n| `mermaid` | Mermaid diagram source rendered in a mermaid pre block. | `string` |\n| `table` | Tabular data rendered from records or explicit headers and rows. | `Record<string, unknown>[] | { headers: string[]; rows: unknown[][] }` |\n| `metrics` | Metric cards showing label/value pairs with optional trend and status. | `Array<{ label: string; value: string | number; trend?: string | number; status?: string }>` |\n| `cards` | Card grid for titled items with optional body, badge, and status. | `Array<{ title: string; body?: string; badge?: string; status?: string; description?: string }>` |\n| `tree` | Hierarchical object or name/children tree rendered recursively. | `{ name: string; children?: unknown[] } | Record<string, unknown>` |\n| `graph` | Node and edge graph rendered as a Mermaid flow graph in HTML mode. | `{ nodes: Array<{ id: string; label?: string }>; edges: Array<{ from: string; to: string; label?: string }> }` |\n| `chart` | Structured chart definition rendered as SVG. | `{ chartType: string; data: Record<string, unknown>[]; xKey: string; yKeys: string[] }` |\n| `timeline` | Timeline entries rendered as a vertical sequence of events. | `Array<{ title: string; description?: string; timestamp?: string; status?: string }>` |\n| `checklist` | Checklist items with boolean checked state. | `Array<{label, checked}> | {items: Array<{label, checked}>}` |\n| `comparison` | Side-by-side comparison columns with titled item lists. | `Array<{title, items}> | {columns: Array<{title, items}>}` |\n| `status-board` | Status categories containing labeled status items. | `Array<{category, items}> | {items: Array<{category, items}>}` |\n| `prompt` | Prompt payload rendered through the prompt display helper. | `unknown` |\n| `progress` | Progress bar with current value and optional maximum. | `{label, value, max?} | {items: Array<{label, value, max?, color?}>}` |\n| `docs-browser` | Documentation file list with inline content previews for chat-safe rendering. | `{ files: Array<{ path: string; title?: string; content?: string; status?: \"current\" | \"stale\" | \"missing\" }>; title?: string }` |\n| `text` | Plain text content rendered through the markdown parser. | `string` |\n| `heading` | Single heading with configurable level from h1 to h6. | `string` |\n| `paragraph` | Single paragraph rendered inside a p tag. | `string` |\n| `separator` | Horizontal rule used to separate adjacent blocks. | `undefined` |\n| `actions` | Action bar containing button and select action definitions. | `Array<{ type: string; id: string; label: string; variant?: string; options?: Array<string | { label: string; value: string }> }>` |\n\n### Usage Examples\n\n#### `docs-browser`\n\n```typescript\n{\n  type: 'docs-browser',\n  value: {\n    title: 'Project Docs',\n    files: [\n      { path: 'docs/README.md', title: 'Overview', status: 'current' },\n      { path: 'docs/api.md', title: 'API Reference', status: 'stale' },\n    ],\n  },\n}\n```";