@vpxa/aikit 0.1.99 → 0.1.100

package/scaffold/dist/definitions/skills.mjs

@@ -43,7 +43,7 @@ Chosen option: "{title of option 1}", because {justification — reference drive
 {This section tells an agent exactly what to do to implement this decision. Be specific — an agent should be able to start coding from this without asking follow-up questions.}
 
 - **Affected paths**: {list files and directories that need to change, e.g., \`src/db/\`, \`src/config/database.ts\`, \`tests/integration/\`}
-- **Dependencies**: {packages to add/remove/update, e.g., "add \`better-sqlite3@11.x\`, remove \`pg-mem\`"}
+- **Dependencies**: {packages to add/remove/update, e.g., "add \`sql.js@1.x\`, remove \`pg-mem\`"}
 - **Patterns to follow**: {reference existing code patterns, e.g., "follow the repository pattern in \`src/db/repositories/\`"}
 - **Patterns to avoid**: {what NOT to do, e.g., "do not use raw SQL outside the data-access layer"}
 - **Configuration**: {env vars, config files, feature flags to add/change}
@@ -249,7 +249,7 @@ Our integration tests require a database but currently hit a shared PostgreSQL i
 
 ## Decision
 
-Use SQLite (via better-sqlite3) for local development and CI test runs. Production remains on PostgreSQL. We'll use a thin data-access layer that abstracts the database engine, tested against both SQLite and PostgreSQL in CI.
+Use SQLite (via sql.js) for local development and CI test runs. Production remains on PostgreSQL. We'll use a thin data-access layer that abstracts the database engine, tested against both SQLite and PostgreSQL in CI.
 
 Non-goals: we are NOT migrating production to SQLite or building a full ORM abstraction.
 
@@ -264,15 +264,15 @@ Non-goals: we are NOT migrating production to SQLite or building a full ORM abst
 ## Implementation Plan
 
 - **Affected paths**: \`src/db/client.ts\` (new abstraction layer), \`src/db/sqlite-client.ts\` (new), \`src/db/pg-client.ts\` (refactored from current inline usage), \`tests/setup.ts\`, \`package.json\`
-- **Dependencies**: add \`better-sqlite3@11.x\` and \`@types/better-sqlite3@7.x\` as devDependencies; no production dependency changes
+- **Dependencies**: add \`sql.js@1.x\` and \`@types/sql.js@1.x\` as devDependencies; no production dependency changes
 - **Patterns to follow**: existing repository pattern in \`src/db/repositories/\` — all queries go through repository methods, never raw SQL in business logic
-- **Patterns to avoid**: do not import \`better-sqlite3\` or \`pg\` directly outside \`src/db/\`; do not use PostgreSQL-specific SQL (JSONB operators, \`ANY()\`, array literals) in shared queries
+- **Patterns to avoid**: do not import \`sql.js\` or \`pg\` directly outside \`src/db/\`; do not use PostgreSQL-specific SQL (JSONB operators, \`ANY()\`, array literals) in shared queries
 
 ### Verification
 
 - [ ] \`npm test\` passes with \`DB_ENGINE=sqlite\` (default for test env)
 - [ ] \`npm test\` passes with \`DB_ENGINE=postgres\` against a real PostgreSQL instance
-- [ ] No imports of \`better-sqlite3\` or \`pg\` outside \`src/db/\`
+- [ ] No imports of \`sql.js\` or \`pg\` outside \`src/db/\`
 - [ ] CI pipeline total time under 90 seconds (was 5+ minutes)
 - [ ] \`src/db/client.ts\` exports a unified interface used by all repositories
 
@@ -323,13 +323,13 @@ Related: [Use PostgreSQL for production](2025-05-01-use-postgresql-for-productio
 
 ## Considered Options
 
-- SQLite via better-sqlite3
+- SQLite via sql.js
 - Docker PostgreSQL per CI run
 - In-memory PostgreSQL (pg-mem)
 
 ## Decision Outcome
 
-Chosen option: "SQLite via better-sqlite3", because it eliminates the CI bottleneck (2s vs 3+ min), provides full isolation, works offline, and has minimal maintenance cost. The dialect-drift risk is mitigated by a weekly CI job against real PostgreSQL.
+Chosen option: "SQLite via sql.js", because it eliminates the CI bottleneck (2s vs 3+ min), provides full isolation, works offline, and has minimal maintenance cost. The dialect-drift risk is mitigated by a weekly CI job against real PostgreSQL.
 
 ### Consequences
 
@@ -352,13 +352,13 @@ Chosen option: "SQLite via better-sqlite3", because it eliminates the CI bottlen
   - \`.env.test\` — new: \`DB_ENGINE=sqlite\`
   - \`.github/workflows/ci.yml\` — update: remove PostgreSQL service container from main CI
   - \`package.json\` — add devDependencies
-- **Dependencies**: add \`better-sqlite3@11.x\`, \`@types/better-sqlite3@7.x\` as devDependencies
+- **Dependencies**: add \`sql.js@1.x\`, \`@types/sql.js@1.x\` as devDependencies
 - **Patterns to follow**:
   - Repository pattern in \`src/db/repositories/\` — all database access goes through repository methods
   - Use parameterized queries exclusively (no string interpolation)
   - Reference implementation: \`src/db/repositories/users.ts\` for the expected style
 - **Patterns to avoid**:
-  - Do NOT import \`better-sqlite3\` or \`pg\` directly outside \`src/db/\`
+  - Do NOT import \`sql.js\` or \`pg\` directly outside \`src/db/\`
   - Do NOT use PostgreSQL-specific SQL in shared queries: no \`JSONB\` operators (\`->\`, \`->>\`), no \`ANY(ARRAY[...])\`, no \`ON CONFLICT ... DO UPDATE\`
   - Do NOT use SQLite-specific SQL either — keep queries portable
 - **Configuration**: \`DB_ENGINE\` env var (\`sqlite\` | \`postgres\`), defaults to \`sqlite\` in test, \`postgres\` in production
@@ -373,7 +373,7 @@ Chosen option: "SQLite via better-sqlite3", because it eliminates the CI bottlen
 
 - [ ] \`DB_ENGINE=sqlite npm test\` passes (all integration tests)
 - [ ] \`DB_ENGINE=postgres npm test\` passes against a real PostgreSQL 16 instance
-- [ ] \`grep -r "from 'better-sqlite3'" src/ --include='*.ts' | grep -v 'src/db/'\` returns no results
+- [ ] \`grep -r "from 'sql.js'" src/ --include='*.ts' | grep -v 'src/db/'\` returns no results
 - [ ] \`grep -r "from 'pg'" src/ --include='*.ts' | grep -v 'src/db/'\` returns no results
 - [ ] CI pipeline completes in under 90 seconds (measured on main branch)
 - [ ] \`src/db/client.ts\` exports \`DatabaseClient\` interface and \`createClient()\` factory
@@ -382,9 +382,9 @@ Chosen option: "SQLite via better-sqlite3", because it eliminates the CI bottlen
 
 ## Pros and Cons of the Options
 
-### SQLite via better-sqlite3
+### SQLite via sql.js
 
-[better-sqlite3](https://github.com/WiseLibs/better-sqlite3) — synchronous SQLite bindings for Node.js.
+[sql.js](https://sql.js.org/) — WASM-based SQLite for Node.js and browsers.
 
 - Good, because zero infrastructure — just an npm dependency
 - Good, because synchronous API makes test setup/teardown trivial
@@ -1589,9 +1589,9 @@ The Implementation Plan section names specific files, directories, and patterns:
 When implementing code guided by an ADR, add a comment referencing it:
 
 \`\`\`typescript
-// ADR: Using better-sqlite3 for test database
+// ADR: Using sql.js for test database
 // See: docs/decisions/2025-06-15-use-sqlite-for-test-database.md
-import Database from 'better-sqlite3';
+import initSqlJs from 'sql.js';
 \`\`\`
 
 Keep these lightweight — one comment at the entry point, not on every line. The goal is discoverability: when a future agent reads this code, they can find the reasoning.
@@ -1704,7 +1704,7 @@ Notes:
 - Scripts auto-detect ADR directory and filename strategy.
 - Use \`--dir\` and \`--strategy\` to override.
 - Use \`--json\` to emit machine-readable output.
-`}],aikit:[{file:`SKILL.md`,content:'---\nname: aikit\ndescription: "Use the @vpxa/aikit AI Kit MCP server for codebase search, analysis, and persistent memory. Load this skill when using aikit_search, aikit_remember, aikit_analyze_*, or any aikit_* tool. Covers all 82 MCP tools: search (hybrid/semantic/keyword), code analysis (structure, dependencies, symbols, patterns, entry points, diagrams, blast radius), knowledge graph (auto-populated module/symbol/import graph with traversal), context management (worksets, stash, checkpoints, restore, lanes), code manipulation (rename, codemod, eval), knowledge management (remember/read/update/forget), web access (fetch, search, http), FORGE protocol (ground, classify, evidence map, stratum cards, digest), brainstorming (interactive ideation sessions), presentation (rich dashboards via present tool), onboarding (full codebase analysis in one call), and developer utilities (regex, encode, measure, changelog, schema-validate, snippet, env, time)."\nmetadata:\n  category: cross-cutting\n  domain: general\n  applicability: always\n  inputs: [codebase]\n  outputs: [search-results, analysis, knowledge]\n  relatedSkills: [present]\n---\n\n# @vpxa/aikit — AI Kit\n\nLocal-first AI developer toolkit — 82 MCP tools for search, analysis, context compression, FORGE quality gates, knowledge management, code manipulation, execution, web access, brainstorming, presentation, and developer utilities.\n\n## When to Use\n\n- You need long-term memory across coding sessions\n- You want to search a codebase semantically (by meaning, not just keywords)\n- You need to compress large contexts to focus on what matters\n- You want structured output from build tools (tsc, vitest, biome, git)\n- You need to plan which files to read for a task\n- You want to safely explore refactors in isolated lanes\n- You need to rename symbols, apply codemods, or run code transformations\n- You want to fetch and read web pages or search the web\n- You need to make HTTP requests, test APIs, or debug endpoints\n- You want to test regex patterns, encode/decode data, or validate JSON schemas\n- You need code complexity metrics or a git changelog\n- You want to save and reuse code snippets across sessions\n\n## Skills Reference\n\n| Context | Skill | Load when |\n|---------|-------|----------|\n| Repository access recovery | `repo-access` | When encountering git auth failures, accessing private/enterprise repos, or when `web_fetch`/`http` returns auth errors on repository URLs. |\n\n## Architecture\n\n10-package monorepo published as a single npm package:\n\n```\ncore → store → embeddings → chunker → indexer → analyzers → tools → server → cli → tui\n```\n\n- **MCP server**: 82 tools + 2 resources (via `@modelcontextprotocol/sdk`)\n- **CLI**: 45 commands (thin dispatcher + 10 command groups)\n- **Search**: Hybrid vector + keyword + RRF fusion\n- **Embeddings**: ONNX local (mxbai-embed-large-v1, 1024 dimensions)\n- **Vector store**: LanceDB (embedded, zero infrastructure)\n- **Chunking**: Tree-sitter AST (TS/JS/Python/Go/Rust/Java) + regex fallback\n- **TUI**: Ink/React dashboard for human monitoring (search, status, curated, activity log)\n\n## Session Protocol (MANDATORY)\n\n### Start (do ALL)\n```\nflow_status({})                                                # Check/resume active flow FIRST\n# If flow active → flow_read_instruction({ step }) → follow step instructions\nstatus({})                                                     # Check AI Kit health + onboard state\n# If onboard not run → onboard({ path: "." })                 # First-time codebase analysis\nflow_list({})                                                  # See available flows\n# Select flow based on task → flow_start({ flow: "<name>", topic: "<task>" })  # Start — creates .flows/{topic}/\nlist()                                                         # See stored knowledge\nsearch({ query: "SESSION CHECKPOINT", origin: "curated" })     # Resume prior work\n```\n\n### During Session\n```\nsearch → scope_map → symbol → trace  (orient)\ncheck → test_run                             (validate changes)\nremember                                         (capture insights)\n```\n\n### End of Session\n```\nsession_digest({ persist: true })                              # Auto-capture session activity\nremember({ title: "Session checkpoint: <topic>", content: "<what was done, decisions made, next steps>", category: "conventions" })\n```\n\n## Tool Catalog (82 tools)\n\n### Search & Discovery (8)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `search` | `aikit search` | Hybrid/semantic/keyword search with `search_mode` param |\n| `find` | `aikit find` | Federated search: vector + FTS + glob + regex in one call. Use `mode: \'examples\'` to find usage examples. |\n| `symbol` | `aikit symbol` | Resolve symbol definition, imports, and references |\n| `lookup` | `aikit lookup` | Full-file retrieval by path or record ID |\n| `scope_map` | `aikit scope-map` | Task-scoped reading plan with token estimates |\n| `trace` | `aikit trace` | Forward/backward flow tracing through call chains |\n| `dead_symbols` | `aikit dead-symbols` | Find exported symbols never imported — separates source (actionable) from docs (informational). Accepts `path` to scope the search. |\n| `file_summary` | `aikit summarize` | Structural overview of a file (exports, imports, functions) |\n\n### Code Analysis (7)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `analyze_structure` | `aikit analyze structure` | Project structure overview |\n| `analyze_dependencies` | `aikit analyze deps` | Dependency graph with confidence |\n| `analyze_symbols` | `aikit analyze symbols` | Symbol extraction and cross-references |\n| `analyze_patterns` | `aikit analyze patterns` | Design pattern detection |\n| `analyze_entry_points` | `aikit analyze entry-points` | Find entry points: handlers, CDK constructs, test suites, package exports (walks workspace packages) |\n| `analyze_diagram` | `aikit analyze diagram` | Generate Mermaid diagrams |\n| `blast_radius` | `aikit analyze blast-radius` | Change impact analysis |\n\n### Context Management (6)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `compact` | `aikit compact` | Compress text to relevant sections using embeddings (no LLM). Accepts `path` for server-side file read. |\n| `workset` | `aikit workset` | Named file set management (save/load/add/remove) |\n| `stash` | `aikit stash` | Named key-value store for session data |\n| `checkpoint` | `aikit checkpoint` | Save/restore session checkpoints |\n| `restore` | `aikit restore` | Restore a previously saved checkpoint |\n| `parse_output` | `aikit parse-output` | Parse tsc/vitest/biome/git output → structured JSON |\n\n### Code Manipulation (4)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `rename` | `aikit rename` | Smart whole-word symbol rename across files (dry-run supported) |\n| `codemod` | `aikit codemod` | Regex-based code transformations with rules (dry-run supported) |\n| `diff_parse` | `aikit diff` | Parse unified diff → structured changes |\n| `data_transform` | `aikit transform` | JQ-like JSON transformations |\n\n### Execution & Validation (5)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `eval` | `aikit eval` | Sandboxed JavaScript/TypeScript execution |\n| `check` | `aikit check` | Incremental typecheck + lint. `detail` param: efficient (default, minimal), normal (parsed errors), full (includes raw) |\n| `test_run` | `aikit test` | Run tests with structured pass/fail results |\n| `batch` | `aikit batch` | Execute multiple operations in parallel |\n| `audit` | `aikit audit` | Unified project audit: structure, deps, patterns, health, dead symbols, check, entry points → synthesized report with score and recommendations. 6 round-trips → 1. |\n\n### Knowledge Management (6)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `remember` | `aikit remember` | Store a curated knowledge entry |\n| `update` | `aikit update` | Update an existing entry |\n| `forget` | `aikit forget` | Delete an entry (requires reason) |\n| `read` | `aikit read` | Read a curated entry by path |\n| `list` | `aikit list` | List curated entries |\n| `produce_knowledge` | — | Auto-generate knowledge from analysis |\n\n### Auto-Knowledge (automatic)\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 `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` | — | Search the web via DuckDuckGo (no API key needed) |\n| `http` | — | Make HTTP requests for API testing/debugging |\n\n### Developer Utilities (8)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `regex_test` | — | Test regex patterns with match/replace/split modes |\n| `encode` | — | Base64, URL, SHA-256, MD5, hex encode/decode, JWT decode |\n| `measure` | — | Code complexity metrics (cyclomatic, cognitive complexity, lines, functions) |\n| `changelog` | — | Generate changelog from git history (conventional commits) |\n| `schema_validate` | — | Validate JSON data against JSON Schema |\n| `snippet` | — | Save/get/search/delete persistent code snippets |\n| `env` | — | System and runtime environment info (sensitive values redacted) |\n| `time` | — | Date parsing, timezone conversion, duration math |\n\n### FORGE Quality Gates (5)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `forge_ground` | — | Full Ground phase: classify tier, scope map, unknowns, constraints |\n| `forge_classify` | — | Quick tier classification (Floor/Standard/Critical) |\n| `evidence_map` | — | CRUD + Gate evaluation for verified/assumed/unknown claims. Safety gate tags (`provenance`/`commitment`/`coverage`) enable mandatory pre-YIELD checks |\n| `stratum_card` | — | Generate T1/T2 compressed context cards from files (10-100x token reduction) |\n| `digest` | — | Compress N text sources into token-budgeted summary |\n\n### System (9)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `config` | `aikit config` | View or update project configuration (kb.config.json) |\n| `status` | `aikit status` | Index statistics |\n| `reindex` | `aikit reindex` | Rebuild index |\n| `health` | `aikit health` | Project health checks (package.json, tsconfig, lockfile, circular deps) |\n| `guide` | `aikit guide` | Tool discovery — given a goal, recommends tools and workflow order |\n| `onboard` | `aikit onboard` | Full codebase onboarding in one call (structure + deps + patterns + knowledge) |\n| `graph` | `aikit graph` | Query the auto-populated knowledge graph (modules, symbols, imports) |\n| `queue` | `aikit queue` | Task queue for sequential agent operations (create/push/next/done/fail) |\n| `replay` | `aikit replay` | View or clear the audit trail of tool invocations (action: list/clear) |\n\n### Flows (11)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `flow_list` | `aikit flow list` | List available flows and active run |\n| `flow_info` | `aikit flow info` | Get flow details including steps and skill paths |\n| `flow_start` | `aikit flow start` | Start a flow with topic — creates `.flows/{topic-slug}/` run directory |\n| `flow_step` | `aikit flow step` | Advance, skip, or redo the current step |\n| `flow_status` | `aikit flow status` | Check active run including slug, runDir, artifactsPath |\n| `flow_read_instruction` | `aikit flow read-instruction` | Read instruction with `{{artifacts_path}}` and `{{run_dir}}` resolved |\n| `flow_reset` | `aikit flow reset` | Abandon the active flow (preserves run directory) |\n| `flow_runs` | `aikit flow runs` | List all flow runs (current and past) |\n| `flow_add` | `aikit flow add` | Add a custom flow from a directory |\n| `flow_update` | `aikit flow update` | Update an existing custom flow |\n| `flow_remove` | `aikit flow remove` | Remove a custom flow |\n\n### Presentation (1)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `present` | — | Rich dashboards, charts, tables, timelines. Use `format: "browser"` then `openBrowserPage` to display. **In CLI mode (no VS Code chat), always use `format: "browser"`** — `html` UIResource is invisible in terminal. |\n\n### Brainstorming (1)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `brainstorm` | — | Interactive brainstorming and ideation sessions with structured output |\n\n### Meta-Tools — Tool Discovery (3)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `list_tools` | — | List all active AI Kit tools with names, titles, and categories. Accepts optional `category` filter. Use for initial tool discovery. |\n| `describe_tool` | — | Get detailed metadata for a specific tool (title, categories, annotations). Use after `list_tools` to understand a tool before calling it. |\n| `search_tools` | — | Search active tools by keyword across names, titles, and categories. Use when you know what you need but not the tool name. |\n\n### Session Management (1)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `session_digest` | — | Generate a compressed digest of session activity (replay log, stash, checkpoints). Options: `scope` (tools/stash/all), `since`, `last`, `focus`, `mode` (deterministic/sampling), `tokenBudget`, `persist`. Use at session end for handoff or mid-session to review what happened. |\n\n## Flow System\n\nFlows are multi-step guided workflows that structure complex tasks. Each step has a skill file with detailed instructions, required artifacts, and agent assignments.\n\n### Built-in Flows\n\n| Flow | Steps | Use When |\n|------|-------|----------|\n| `aikit:basic` | assess → implement → verify | Bug fixes, config changes, small features |\n| `aikit:advanced` | spec → plan → task → execute → verify | New modules, cross-service changes, architectural work |\n\n### Flow Lifecycle\n\n```text\nflow_list()                          # See available flows\nflow_info({ flow: "aikit:basic" })   # View steps, skills, agents\nflow_start({ flow: "aikit:basic", topic: "Fix login bug" })  # Start — creates .flows/fix-login-bug/\nflow_read_instruction()              # Read current step\'s instructions ({{artifacts_path}} resolved)\n# ... do the work described in the instruction ...\nflow_step({ action: "next" })        # Advance to next step\nflow_step({ action: "skip" })        # Skip current step\nflow_step({ action: "redo" })        # Redo current step\nflow_status()                        # Check progress (includes slug, runDir, artifactsPath, phase, isEpilogue)\nflow_reset()                         # Abandon active flow\nflow_runs()                          # List all runs (current + past)\n# Epilogue steps (mandatory, injected after every flow):\n# After last flow step → _docs-sync epilogue runs automatically\n# flow_status() shows phase: \'after\', isEpilogue: true during epilogue\n```\n\nCustom flow lifecycle management:\n\n```text\nflow_add({ source: ".github/flows/my-flow" })\nflow_update({ name: "my-flow" })\nflow_remove({ name: "my-flow" })\n```\n\n## CRITICAL: Use AI Kit Tools Instead of Native IDE Tools\n\nAI Kit tools provide **10x richer output** than native IDE tools — with AST-analyzed call graphs, scope context, import classification, and cognitive complexity. **You MUST use AI Kit tools instead of native read/search tools.**\n\n### ⛔ PROHIBITED: Native File Reading\n\n**`read_file` / `read_file_raw` MUST NOT be used to understand code.** They waste tokens and miss structural information.\n\nThe **ONLY** acceptable use of `read_file`: getting exact lines immediately before an edit (to verify the `old_str` for replacement). Even then, use `file_summary` first to identify which lines to read.\n\n### Tool Replacement Table\n\n| ❌ NEVER do this | ✅ Use AI Kit Tool | Why |\n|---|---|---|\n| `read_file` (full file) | `file_summary` | Exports, imports, call edges — **10x fewer tokens** |\n| `read_file` (specific section) | `compact({ path, query })` | Server-side read + extract — **5-20x reduction** |\n| `grep_search` / `textSearch` | `search` | Semantic + keyword hybrid across all indexed content |\n| `grep_search` for a symbol | `symbol` | Definition + references **with scope context** |\n| Multiple `read_file` calls | `digest` | Compresses multiple sources into token-budgeted summary |\n| `listDirectory` + `read_file` | `scope_map` | Identifies relevant files for a task automatically |\n| Manual code tracing | `trace` | AST call-graph traversal with scope context |\n| Line counting / `wc` | `measure` | Lines, complexity, **cognitive complexity**, functions |\n| Grep for unused exports | `dead_symbols` | AST-powered export detection with regex fallback |\n| Repeated file reads | `stratum_card` | Reusable compressed context — **10-100x reduction** |\n| `fetch_webpage` | `web_fetch` | Readability extract + token budget — richer output |\n| Web research / browsing | `web_search` | Structured web results without browser — **unique to KB** |\n\n### Decision Tree — How to Read Code\n\n```\nNeed to understand a file?\n├─ Just structure?        → file_summary (exports, imports, call edges — ~50 tokens)\n├─ Specific section?      → compact({ path, query }) — 5-20x reduction\n├─ Multiple files?        → digest (multi-source compression — token-budgeted)\n├─ Repeated reference?    → stratum_card (T1/T2 card — 10-100x reduction)\n├─ Need exact lines to EDIT? → read_file (the ONLY acceptable use)\n└─ "I want to read the whole file" → ⛔ STOP. Use file_summary or compact instead.\n```\n\n### Decision Tree — Need Structural Relationships?\n\nWhen vector search and file reads don\'t answer the question (e.g. "who imports this?",\n"what does this depend on?", "how are these files connected?"), use `graph`:\n\n```\nNeed to understand relationships between code?\n├─ Who imports / calls this?     → graph({action:\'find_nodes\', name_pattern}) → graph({action:\'neighbors\', node_id, direction:\'incoming\'})\n├─ What does this depend on?     → graph({action:\'neighbors\', node_id, direction:\'outgoing\'})\n├─ Full context for a symbol?    → graph({action:\'symbol360\', name})\n├─ Related files within N hops?  → graph({action:\'traverse\', node_id, max_depth:2})\n├─ Layer/module isolation check? → graph({action:\'depth_traverse\', node_id, max_depth:3})\n└─ Graph size/health?            → graph({action:\'stats\'})\n```\n\n**Use this BEFORE** reaching for `analyze_dependencies` (slower, less precise) or manually\ntracing via `symbol` + `trace` chains. The graph is auto-populated during indexing.\n\n### What AI Kit Tools Return (AST-Enhanced)\n\nThese tools use Tree-sitter WASM to analyze source code at the AST level, providing structured data that raw file reads cannot:\n\n| Tool | Rich Output |\n|------|-------------|\n| `file_summary` | Imports classified as **external vs internal** (`isExternal` flag). **Call edges** between functions (e.g., `handleRequest() → validateInput() @ line 42`). `exported` flag on interfaces and types. Import count breakdown. |\n| `symbol` | References include **scope** — which function/class/method contains each usage (e.g., `referenced in processOrder() at auth-service.ts:55`). |\n| `trace` | **Call-graph edges** discovered via AST syntax tree, not text matching. Supports forward (who does X call?) and backward (who calls X?) tracing. Scope context on each node. |\n| `measure` | **Cognitive complexity** — weights nesting depth (nested `if` inside `for` inside `try` scores higher). More useful than cyclomatic complexity for understanding code difficulty. |\n| `dead_symbols` | **AST export enumeration** — catches `export default`, barrel re-exports (`export { x } from`), `export =`, and `export type`. Regex fallback for non-AST-supported languages. |\n\n### Example: `file_summary` Output\n\n```\nsrc/auth-service.ts\nLanguage: typescript | Lines: 180 | Estimated tokens: ~1400\n\nImports (6): 3 external, 3 internal\n  - import { hash } from \'bcrypt\'          [external]\n  - import { UserRepo } from \'./user-repo\' [internal]\n\nFunctions (4):\n  - authenticate @ line 22 [exported]\n  - validateToken @ line 55 [exported]\n  - hashPassword @ line 90\n  - generateJwt @ line 110\n\nCall edges (12 intra-file):\n  - authenticate() → hashPassword() @ line 35\n  - authenticate() → generateJwt() @ line 42\n  - validateToken() → UserRepo.findById() @ line 68\n\nInterfaces (2):\n  - AuthResult @ line 8 [exported]\n  - TokenPayload @ line 14\n```\n\nCompare: `read_file` would cost ~1400 tokens for raw text. `file_summary` gives structured data in ~120 tokens — **12x reduction** with richer information.\n\n## 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_structure({ path: "src/" })\n→ analyze_dependencies({ path: "src/" })\n→ analyze_entry_points({ path: "src/" })\n→ produce_knowledge({ path: "src/" })\n→ remember({ title: "Codebase onboarding complete", ... })\n```\n\n### Planning a Task\n```\nscope_map({ task: "implement user auth" })\n→ compact({ path: "src/auth.ts", query: "auth flow" })\n→ workset({ action: "save", name: "auth-task", files: [...] })\n```\n\n### Bug Investigation\n```\nparse_output({ output: <error> }) → symbol({ name: "failingFn" })\n→ trace({ symbol: "failingFn", direction: "backward" })\n→ blast_radius({ changed_files: ["suspect.ts"] })\n→ eval({ code: "hypothesis test" }) → check({ files: ["suspect.ts"] })\n```\n\n### 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→ 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 | `remember({ title, content, category })` | conventions, decisions, patterns, context, session |\n| Search | `search({ query, origin: "curated" })` | — |\n| Browse | `list()` or `list({ category })` | — |\n| Read | `read({ id })` | — |\n| Update | `update({ id, content })` | — |\n| Remove | `forget({ id })` | — |\n\n**Session checkpoint** (end of session): `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`kb.config.json` in project root:\n```json\n{\n  "sources": [{ "path": ".", "excludePatterns": ["node_modules/**", "**/node_modules/**", "dist/**", "coverage/**", ".aikit-data/**"] }],\n  "indexing": { "chunkSize": 1500, "chunkOverlap": 200, "minChunkSize": 100, "concurrency": 5 },\n  "embedding": { "model": "mixedbread-ai/mxbai-embed-large-v1", "dimensions": 1024 },\n  "store": { "backend": "lancedb", "path": ".aikit-data" },\n  "curated": { "path": "curated", "adapter": "filesystem" }\n}\n```\n\n## Tool Profiles\n\nTool profiles control which subset of the 82 tools are active. Profiles reduce token overhead by exposing only relevant tools for a given task.\n\n### Built-in Profiles\n\n| Profile | Description | Use When |\n|---------|-------------|----------|\n| `full` | All tools enabled (default) | General development, orchestration |\n| `safe` | Read-only tools — no file/state modifications | Code review, analysis, research |\n| `research` | Search, analysis, knowledge, web access | Investigation, documentation |\n| `minimal` | Essential tools only — search, check, test | Simple tasks, low-token budgets |\n| `discovery` | Full toolset + meta-tools for guided exploration | New users, onboarding, tool learning |\n\n### Activating a Profile\n\nSet `toolProfile` in `kb.config.json`:\n\n```json\n{\n  "toolProfile": "research"\n}\n```\n\nBase tools (`status`, `config`, `guide`, `health`) are **always available** regardless of profile.\n\n## Development (Self-Dogfooding)\n\nWhen developing @vpxa/aikit itself: always `pnpm build` before using CLI/server (runs from `dist/`), always `reindex` after structural code changes, and don\'t run CLI and HTTP server simultaneously (LanceDB is single-process).\n\n---\n\n## Flows\n\nFlows are structured multi-step workflows that guide agents through complex tasks. They are the **primary workflow system** — use them instead of ad-hoc planning when a matching flow exists.\n\n### Flow Tools\n\n| Tool | Purpose |\n|------|---------|\n| `flow_status` | Check if a flow is active + current step + phase (before/flow/after) + isEpilogue |\n| `flow_list` | List available flows |\n| `flow_info` | Get flow details including steps and skill paths |\n| `flow_start` | Start a named flow |\n| `flow_step` | Advance: `next`, `skip`, or `redo` current step |\n| `flow_read_instruction` | Read the current step\'s instruction file content directly |\n| `flow_reset` | Clear flow state to start over |\n| `flow_add` | Add a custom flow from a directory |\n| `flow_update` | Update an existing custom flow |\n| `flow_remove` | Remove a custom flow |\n\n### Flow Selection\n\n| Task Type | Flow | Why |\n|-----------|------|-----|\n| Bug fix, config change, small refactor | `aikit:basic` | Known scope, low risk |\n| New feature in existing module | `aikit:basic` | Clear boundaries |\n| New system/service/module | `aikit:advanced` | Needs spec + planning |\n| Cross-service changes | `aikit:advanced` | Multiple boundaries |\n| Architectural change | `aikit:advanced` | High impact |\n| Unclear scope or exploratory | No flow | Use agent\'s native workflow |\n\n### Flow Lifecycle\n\n1. **Start**: `flow_list({})` → choose flow → `flow_start({ flow: "<name>", topic: "<task>" })`\n2. **Each step**: `flow_read_instruction({ step: "<name>" })` → follow step instructions → complete work\n3. **Advance**: `flow_step({ action: "next" })` → repeat from step 2\n4. **Epilogue**: After last flow step, mandatory epilogue steps run (e.g., `_docs-sync` updates `docs/`)\n5. **Resume**: `flow_status({})` → if active, `flow_read_instruction` for current step → continue\n6. **Reset**: `flow_reset({})` if you need to start over\n\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
+`}],aikit:[{file:`SKILL.md`,content:'---\nname: aikit\ndescription: "Use the @vpxa/aikit AI Kit MCP server for codebase search, analysis, and persistent memory. Load this skill when using aikit_search, aikit_analyze, aikit_knowledge, or any aikit_* tool. Covers all 82 MCP tools: search (hybrid/semantic/keyword), code analysis (analyze aspects for structure, dependencies, symbols, patterns, entry points, diagrams, plus blast radius), knowledge graph (auto-populated module/symbol/import graph with traversal), context management (worksets, stash, checkpoints, restore, lanes), code manipulation (rename, codemod, eval), knowledge management (knowledge actions: remember/read/update/forget/list), web access (fetch, search, http), FORGE protocol (ground, classify, evidence map, stratum cards, digest), brainstorming (interactive ideation sessions), presentation (rich dashboards via present tool), onboarding (full codebase analysis in one call), and developer utilities (regex, encode, measure, changelog, schema-validate, snippet, env, time)."\nmetadata:\n  category: cross-cutting\n  domain: general\n  applicability: always\n  inputs: [codebase]\n  outputs: [search-results, analysis, knowledge]\n  relatedSkills: [present]\n---\n\n# @vpxa/aikit — AI Kit\n\nLocal-first AI developer toolkit — 82 MCP tools for search, analysis, context compression, FORGE quality gates, knowledge management, code manipulation, execution, web access, brainstorming, presentation, and developer utilities.\n\n## When to Use\n\n- You need long-term memory across coding sessions\n- You want to search a codebase semantically (by meaning, not just keywords)\n- You need to compress large contexts to focus on what matters\n- You want structured output from build tools (tsc, vitest, biome, git)\n- You need to plan which files to read for a task\n- You want to safely explore refactors in isolated lanes\n- You need to rename symbols, apply codemods, or run code transformations\n- You want to fetch and read web pages or search the web\n- You need to make HTTP requests, test APIs, or debug endpoints\n- You want to test regex patterns, encode/decode data, or validate JSON schemas\n- You need code complexity metrics or a git changelog\n- You want to save and reuse code snippets across sessions\n\n## Skills Reference\n\n| Context | Skill | Load when |\n|---------|-------|----------|\n| Repository access recovery | `repo-access` | When encountering git auth failures, accessing private/enterprise repos, or when `web_fetch`/`http` returns auth errors on repository URLs. |\n\n## Architecture\n\n10-package monorepo published as a single npm package:\n\n```\ncore → store → embeddings → chunker → indexer → analyzers → tools → server → cli → tui\n```\n\n- **MCP server**: 82 tools + 2 resources (via `@modelcontextprotocol/sdk`)\n- **CLI**: 45 commands (thin dispatcher + 10 command groups)\n- **Search**: Hybrid vector + keyword + RRF fusion\n- **Embeddings**: ONNX local (mxbai-embed-large-v1, 1024 dimensions)\n- **Vector store**: LanceDB (embedded, zero infrastructure)\n- **Chunking**: Tree-sitter AST (TS/JS/Python/Go/Rust/Java) + regex fallback\n- **TUI**: Ink/React dashboard for human monitoring (search, status, curated, activity log)\n\n## Session Protocol (MANDATORY)\n\n### Start (do ALL)\n```\nflow_status({})                                                # Check/resume active flow FIRST\n# If flow active → flow_read_instruction({ step }) → follow step instructions\nstatus({})                                                     # Check AI Kit health + onboard state\n# If onboard not run → onboard({ path: "." })                 # First-time codebase analysis\nflow_list({})                                                  # See available flows\n# Select flow based on task → flow_start({ flow: "<name>", topic: "<task>" })  # Start — creates .flows/{topic}/\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 (82 tools)\n\n### Search & Discovery (8)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `search` | `aikit search` | Hybrid/semantic/keyword search with `search_mode` param |\n| `find` | `aikit find` | Federated search: vector + FTS + glob + regex in one call. Use `mode: \'examples\'` to find usage examples. |\n| `symbol` | `aikit symbol` | Resolve symbol definition, imports, and references |\n| `lookup` | `aikit lookup` | Full-file retrieval by path or record ID |\n| `scope_map` | `aikit scope-map` | Task-scoped reading plan with token estimates |\n| `trace` | `aikit trace` | Forward/backward flow tracing through call chains |\n| `dead_symbols` | `aikit dead-symbols` | Find exported symbols never imported — separates source (actionable) from docs (informational). Accepts `path` to scope the search. |\n| `file_summary` | `aikit summarize` | Structural overview of a file (exports, imports, functions) |\n\n### Code Analysis (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 (5)\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| `batch` | `aikit batch` | Execute multiple operations in parallel |\n| `audit` | `aikit audit` | Unified project audit: structure, deps, patterns, health, dead symbols, check, entry points → synthesized report with score and recommendations. 6 round-trips → 1. |\n\n### Knowledge Management (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` | — | Search the web via DuckDuckGo (no API key needed) |\n| `http` | — | Make HTTP requests for API testing/debugging |\n\n### Developer Utilities (8)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `regex_test` | — | Test regex patterns with match/replace/split modes |\n| `encode` | — | Base64, URL, SHA-256, MD5, hex encode/decode, JWT decode |\n| `measure` | — | Code complexity metrics (cyclomatic, cognitive complexity, lines, functions) |\n| `changelog` | — | Generate changelog from git history (conventional commits) |\n| `schema_validate` | — | Validate JSON data against JSON Schema |\n| `snippet` | — | Save/get/search/delete persistent code snippets |\n| `env` | — | System and runtime environment info (sensitive values redacted) |\n| `time` | — | Date parsing, timezone conversion, duration math |\n\n### FORGE Quality Gates (5)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `forge_ground` | — | Full Ground phase: classify tier, scope map, unknowns, constraints |\n| `forge_classify` | — | Quick tier classification (Floor/Standard/Critical) |\n| `evidence_map` | — | CRUD + Gate evaluation for verified/assumed/unknown claims. Safety gate tags (`provenance`/`commitment`/`coverage`) enable mandatory pre-YIELD checks |\n| `stratum_card` | — | Generate T1/T2 compressed context cards from files (10-100x token reduction) |\n| `digest` | — | Compress N text sources into token-budgeted summary |\n\n### System (9)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `config` | `aikit config` | View or update project configuration (kb.config.json) |\n| `status` | `aikit status` | Index statistics |\n| `reindex` | `aikit reindex` | Rebuild index |\n| `health` | `aikit health` | Project health checks (package.json, tsconfig, lockfile, circular deps) |\n| `guide` | `aikit guide` | Tool discovery — given a goal, recommends tools and workflow order |\n| `onboard` | `aikit onboard` | Full codebase onboarding in one call (structure + deps + patterns + knowledge) |\n| `graph` | `aikit graph` | Query the auto-populated knowledge graph (modules, symbols, imports) |\n| `queue` | `aikit queue` | Task queue for sequential agent operations (create/push/next/done/fail) |\n| `replay` | `aikit replay` | View or clear the audit trail of tool invocations (action: list/clear) |\n\n### Flows (11)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `flow_list` | `aikit flow list` | List available flows and active run |\n| `flow_info` | `aikit flow info` | Get flow details including steps and skill paths |\n| `flow_start` | `aikit flow start` | Start a flow with topic — creates `.flows/{topic-slug}/` run directory |\n| `flow_step` | `aikit flow step` | Advance, skip, or redo the current step |\n| `flow_status` | `aikit flow status` | Check active run including slug, runDir, artifactsPath |\n| `flow_read_instruction` | `aikit flow read-instruction` | Read instruction with `{{artifacts_path}}` and `{{run_dir}}` resolved |\n| `flow_reset` | `aikit flow reset` | Abandon the active flow (preserves run directory) |\n| `flow_runs` | `aikit flow runs` | List all flow runs (current and past) |\n| `flow_add` | `aikit flow add` | Add a custom flow from a directory |\n| `flow_update` | `aikit flow update` | Update an existing custom flow |\n| `flow_remove` | `aikit flow remove` | Remove a custom flow |\n\n### Presentation (1)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `present` | — | Rich dashboards, charts, tables, timelines. Use `format: "browser"` then `openBrowserPage` to display. **In CLI mode (no VS Code chat), always use `format: "browser"`** — `html` UIResource is invisible in terminal. |\n\n### Brainstorming (1)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `brainstorm` | — | Interactive brainstorming and ideation sessions with structured output |\n\n### Meta-Tools — Tool Discovery (3)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `list_tools` | — | List all active AI Kit tools with names, titles, and categories. Accepts optional `category` filter. Use for initial tool discovery. |\n| `describe_tool` | — | Get detailed metadata for a specific tool (title, categories, annotations). Use after `list_tools` to understand a tool before calling it. |\n| `search_tools` | — | Search active tools by keyword across names, titles, and categories. Use when you know what you need but not the tool name. |\n\n### Session Management (1)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `session_digest` | — | Generate a compressed digest of session activity (replay log, stash, checkpoints). Options: `scope` (tools/stash/all), `since`, `last`, `focus`, `mode` (deterministic/sampling), `tokenBudget`, `persist`. Use at session end for handoff or mid-session to review what happened. |\n\n## Flow System\n\nFlows are multi-step guided workflows that structure complex tasks. Each step has a skill file with detailed instructions, required artifacts, and agent assignments.\n\n### Built-in Flows\n\n| Flow | Steps | Use When |\n|------|-------|----------|\n| `aikit:basic` | assess → implement → verify | Bug fixes, config changes, small features |\n| `aikit:advanced` | spec → plan → task → execute → verify | New modules, cross-service changes, architectural work |\n\n### Flow Lifecycle\n\n```text\nflow_list()                          # See available flows\nflow_info({ flow: "aikit:basic" })   # View steps, skills, agents\nflow_start({ flow: "aikit:basic", topic: "Fix login bug" })  # Start — creates .flows/fix-login-bug/\nflow_read_instruction()              # Read current step\'s instructions ({{artifacts_path}} resolved)\n# ... do the work described in the instruction ...\nflow_step({ action: "next" })        # Advance to next step\nflow_step({ action: "skip" })        # Skip current step\nflow_step({ action: "redo" })        # Redo current step\nflow_status()                        # Check progress (includes slug, runDir, artifactsPath, phase, isEpilogue)\nflow_reset()                         # Abandon active flow\nflow_runs()                          # List all runs (current + past)\n# Epilogue steps (mandatory, injected after every flow):\n# After last flow step → _docs-sync epilogue runs automatically\n# flow_status() shows phase: \'after\', isEpilogue: true during epilogue\n```\n\nCustom flow lifecycle management:\n\n```text\nflow_add({ source: ".github/flows/my-flow" })\nflow_update({ name: "my-flow" })\nflow_remove({ name: "my-flow" })\n```\n\n## CRITICAL: Use AI Kit Tools Instead of Native IDE Tools\n\nAI Kit tools provide **10x richer output** than native IDE tools — with AST-analyzed call graphs, scope context, import classification, and cognitive complexity. **You MUST use AI Kit tools instead of native read/search tools.**\n\n### ⛔ PROHIBITED: Native File Reading\n\n**`read_file` / `read_file_raw` MUST NOT be used to understand code.** They waste tokens and miss structural information.\n\nThe **ONLY** acceptable use of `read_file`: getting exact lines immediately before an edit (to verify the `old_str` for replacement). Even then, use `file_summary` first to identify which lines to read.\n\n### Tool Replacement Table\n\n| ❌ NEVER do this | ✅ Use AI Kit Tool | Why |\n|---|---|---|\n| `read_file` (full file) | `file_summary` | Exports, imports, call edges — **10x fewer tokens** |\n| `read_file` (specific section) | `compact({ path, query })` | Server-side read + extract — **5-20x reduction** |\n| `grep_search` / `textSearch` | `search` | Semantic + keyword hybrid across all indexed content |\n| `grep_search` for a symbol | `symbol` | Definition + references **with scope context** |\n| Multiple `read_file` calls | `digest` | Compresses multiple sources into token-budgeted summary |\n| `listDirectory` + `read_file` | `scope_map` | Identifies relevant files for a task automatically |\n| Manual code tracing | `trace` | AST call-graph traversal with scope context |\n| Line counting / `wc` | `measure` | Lines, complexity, **cognitive complexity**, functions |\n| Grep for unused exports | `dead_symbols` | AST-powered export detection with regex fallback |\n| Repeated file reads | `stratum_card` | Reusable compressed context — **10-100x reduction** |\n| `fetch_webpage` | `web_fetch` | Readability extract + token budget — richer output |\n| Web research / browsing | `web_search` | Structured web results without browser — **unique to KB** |\n\n### Decision Tree — How to Read Code\n\n```\nNeed to understand a file?\n├─ Just structure?        → file_summary (exports, imports, call edges — ~50 tokens)\n├─ Specific section?      → compact({ path, query }) — 5-20x reduction\n├─ Multiple files?        → digest (multi-source compression — token-budgeted)\n├─ Repeated reference?    → stratum_card (T1/T2 card — 10-100x reduction)\n├─ Need exact lines to EDIT? → read_file (the ONLY acceptable use)\n└─ "I want to read the whole file" → ⛔ STOP. Use file_summary or compact instead.\n```\n\n### Decision Tree — Need Structural Relationships?\n\nWhen vector search and file reads don\'t answer the question (e.g. "who imports this?",\n"what does this depend on?", "how are these files connected?"), use `graph`:\n\n```\nNeed to understand relationships between code?\n├─ Who imports / calls this?     → graph({action:\'find_nodes\', name_pattern}) → graph({action:\'neighbors\', node_id, direction:\'incoming\'})\n├─ What does this depend on?     → graph({action:\'neighbors\', node_id, direction:\'outgoing\'})\n├─ Full context for a symbol?    → graph({action:\'symbol360\', name})\n├─ Related files within N hops?  → graph({action:\'traverse\', node_id, max_depth:2})\n├─ Layer/module isolation check? → graph({action:\'depth_traverse\', node_id, max_depth:3})\n└─ Graph size/health?            → graph({action:\'stats\'})\n```\n\n**Use this BEFORE** reaching for `analyze({ 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`kb.config.json` in project root:\n```json\n{\n  "sources": [{ "path": ".", "excludePatterns": ["node_modules/**", "**/node_modules/**", "dist/**", "coverage/**", ".aikit-data/**"] }],\n  "indexing": { "chunkSize": 1500, "chunkOverlap": 200, "minChunkSize": 100, "concurrency": 5 },\n  "embedding": { "model": "mixedbread-ai/mxbai-embed-large-v1", "dimensions": 1024 },\n  "store": { "backend": "lancedb", "path": ".aikit-data" },\n  "curated": { "path": "curated", "adapter": "filesystem" }\n}\n```\n\n## Tool Profiles\n\nTool profiles control which subset of the 82 tools are active. Profiles reduce token overhead by exposing only relevant tools for a given task.\n\n### Built-in Profiles\n\n| Profile | Description | Use When |\n|---------|-------------|----------|\n| `full` | All tools enabled (default) | General development, orchestration |\n| `safe` | Read-only tools — no file/state modifications | Code review, analysis, research |\n| `research` | Search, analysis, knowledge, web access | Investigation, documentation |\n| `minimal` | Essential tools only — search, check, test | Simple tasks, low-token budgets |\n| `discovery` | Full toolset + meta-tools for guided exploration | New users, onboarding, tool learning |\n\n### Activating a Profile\n\nSet `toolProfile` in `kb.config.json`:\n\n```json\n{\n  "toolProfile": "research"\n}\n```\n\nBase tools (`status`, `config`, `guide`, `health`) are **always available** regardless of profile.\n\n## Development (Self-Dogfooding)\n\nWhen developing @vpxa/aikit itself: always `pnpm build` before using CLI/server (runs from `dist/`), always `reindex` after structural code changes, and don\'t run CLI and HTTP server simultaneously (LanceDB is single-process).\n\n---\n\n## Flows\n\nFlows are structured multi-step workflows that guide agents through complex tasks. They are the **primary workflow system** — use them instead of ad-hoc planning when a matching flow exists.\n\n### Flow Tools\n\n| Tool | Purpose |\n|------|---------|\n| `flow_status` | Check if a flow is active + current step + phase (before/flow/after) + isEpilogue |\n| `flow_list` | List available flows |\n| `flow_info` | Get flow details including steps and skill paths |\n| `flow_start` | Start a named flow |\n| `flow_step` | Advance: `next`, `skip`, or `redo` current step |\n| `flow_read_instruction` | Read the current step\'s instruction file content directly |\n| `flow_reset` | Clear flow state to start over |\n| `flow_add` | Add a custom flow from a directory |\n| `flow_update` | Update an existing custom flow |\n| `flow_remove` | Remove a custom flow |\n\n### Flow Selection\n\n| Task Type | Flow | Why |\n|-----------|------|-----|\n| Bug fix, config change, small refactor | `aikit:basic` | Known scope, low risk |\n| New feature in existing module | `aikit:basic` | Clear boundaries |\n| New system/service/module | `aikit:advanced` | Needs spec + planning |\n| Cross-service changes | `aikit:advanced` | Multiple boundaries |\n| Architectural change | `aikit:advanced` | High impact |\n| Unclear scope or exploratory | No flow | Use agent\'s native workflow |\n\n### Flow Lifecycle\n\n1. **Start**: `flow_list({})` → choose flow → `flow_start({ flow: "<name>", topic: "<task>" })`\n2. **Each step**: `flow_read_instruction({ step: "<name>" })` → follow step instructions → complete work\n3. **Advance**: `flow_step({ action: "next" })` → repeat from step 2\n4. **Epilogue**: After last flow step, mandatory epilogue steps run (e.g., `_docs-sync` updates `docs/`)\n5. **Resume**: `flow_status({})` → if active, `flow_read_instruction` for current step → continue\n6. **Reset**: `flow_reset({})` if you need to start over\n\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.
 
@@ -4943,7 +4943,7 @@ type: explanation
 
 ---
 
-*Templates follow the Diátaxis documentation framework (CC-BY-SA 4.0, Daniele Procida).*`},{file:`references/flow-artifacts-guide.md`,content:'# Flow Artifacts Guide\n\n## What Are Flow Artifacts\n\nFlows produce structured markdown artifacts in `{{artifacts_path}}/`. These files capture requirements, decisions, plan shape, implementation progress, and verification results for the completed flow.\n\nUse artifacts to document the why behind changes. Code diffs still matter, but artifacts usually contain the rationale, constraints, risks, and review findings that should shape durable documentation.\n\n## How to Discover Artifacts\n\n```text\nflow_status()                                      # Get artifactsPath\nfind({ pattern: "*.md", path: "<artifactsPath>" }) # Discover artifact files\ndigest({ sources: [                                # Compress into working context\n  { path: "<found-artifact-1>" },\n  { path: "<found-artifact-2>" },\n  ...\n]})\n```\n\nRead every artifact `find()` returns. Different flows produce different files — do not assume specific filenames exist.\n\n## Artifact Catalog\n\n| Artifact | Flow | Contains |\n|---|---|---|\n| `design-decisions.md` | `aikit:basic`, `aikit:advanced` | FORGE tier, approach, key decisions, constraints, and risks |\n| `assessment.md` | `aikit:basic` | Goal, affected files, approach steps, risks, and open questions |\n| `spec.md` | `aikit:advanced` | Requirements, acceptance criteria, and scope boundaries |\n| `plan.md` | `aikit:advanced` | Phased implementation plan and architecture decisions |\n| `tasks.md` | `aikit:advanced` | Atomic task list, dependencies, and agent assignments |\n| `progress.md` | `aikit:basic`, `aikit:advanced` | Changes made, tests, deviations, and validation results |\n| `verify-report.md` | `aikit:basic`, `aikit:advanced` | Verdict, quality gates, review findings, security, and recommendation |\n\n## Artifact-to-Documentation Mapping\n\n| Artifact | Contains | Documentation Target | Action |\n|---|---|---|---|\n| `design-decisions.md` | FORGE tier, approach, key decisions | `docs/decisions/` | Create or update ADRs via `adr-skill` for each key decision |\n| `design-decisions.md` | Architecture approach, constraints | `docs/architecture/overview.md` | Update the design rationale section |\n| `spec.md` | Requirements, acceptance criteria | `docs/reference/` | Update API or component reference when public surface changed |\n| `plan.md` | Architecture decisions, phase design | `docs/architecture/` | Update architecture docs with structural changes |\n| `tasks.md` | Task breakdown, dependencies | Usually skip | Only document if it reveals new component boundaries |\n| `progress.md` | Files changed, deviations, tests | `docs/guides/testing.md` | Update when testing strategy changed |\n| `progress.md` | Deviations from plan | `docs/decisions/` | Document significant deviations as ADRs |\n| `verify-report.md` | Code review findings, security | `docs/architecture/overview.md` | Update if findings reveal architectural patterns |\n| `verify-report.md` | Security concerns | `docs/guides/` | Create or update security guidance when concerns are material |\n\n## Reading Strategy\n\nRead every artifact `find()` returns. Triage by content type:\n\n| Content Signal | Documentation Value | Action |\n|---|---|---|\n| Decisions, rationale, constraints | High — durable knowledge | Extract into `docs/decisions/` or architecture docs |\n| Requirements, scope, acceptance criteria | High — defines intent | Update reference docs if public surface changed |\n| Review findings, security concerns, quality gates | Medium — surfaces issues | Update architecture or guides if findings are material |\n| Implementation progress, task lists | Low — transient | Document only meaningful deviations from the plan |\n\nSkip artifacts that only repeat completed work with no insights beyond the code diff.\n\n> The catalog and mapping tables above list artifacts from built-in flows (`aikit:basic`, `aikit:advanced`). Custom flows may produce entirely different artifacts — always discover dynamically with `find()` and classify by content, not by filename.\n\n## What Not to Document\n\n| Avoid | Do Instead |\n|---|---|\n| Copying artifact text verbatim into `docs/` | Extract decisions, rationale, constraints, and stable guidance |\n| Documenting every task or progress update | Keep only durable insights that help future readers |\n| Mirroring temporary planning details | Preserve the final reasoning, not the transient workflow chatter |'},{file:`references/project-knowledge-gotchas.md`,content:'# Project Knowledge — Gotchas\n\nCommon pitfalls when documenting project knowledge. Reference this during Phase 2 (Investigate) and Phase 4 (Validate).\n\n## Environment Gotchas\n\n**Monorepos:** Root `package.json` may have no source — check for `workspaces`, `packages/`, or `apps/` directories. Each workspace may have independent dependencies and conventions. Map each sub-package separately.\n\n**Outdated README:** README often describes intended architecture, not the current one. Cross-reference with actual file structure before treating any README claim as fact.\n\n**TypeScript path aliases:** `tsconfig.json` `paths` config means imports like `@/foo` don\'t map directly to the filesystem. Map aliases to real paths before documenting structure.\n\n**Generated/compiled output:** Never document patterns from `dist/`, `build/`, `generated/`, `.next/`, `out/`, or `__pycache__/`. These are artefacts — document source conventions only.\n\n**`.env.example` reveals required config:** Secrets are never committed. Read `.env.example`, `.env.template`, or `.env.sample` to discover required environment variables.\n\n**`devDependencies` ≠ production stack:** Only `dependencies` (or equivalent) runs in production. Document linters, formatters, and test frameworks separately as dev tooling in `stack.md`.\n\n**Test TODOs ≠ production debt:** TODOs inside test directories are coverage gaps, not production technical debt. Separate them in `concerns.md`.\n\n**High-churn files = fragile areas:** Files appearing most in recent `git_context({})` output have the highest modification rate and likely hidden complexity. Always note them in `concerns.md`.\n\n## Anti-Pattern Table\n\n| ❌ Don\'t | ✅ Do instead |\n|---------|--------------|\n| "Uses Clean Architecture with Domain/Data layers" (when no such directories exist) | State only what directory structure actually shows |\n| "This is a Next.js project" (without checking `package.json`) | Check `dependencies` first. State what\'s actually there |\n| Guess the database from a variable name like `dbUrl` | Check manifest for `pg`, `mysql2`, `mongoose`, `prisma`, etc. |\n| Document `dist/` or `build/` naming patterns as conventions | Source files only |\n| Assume README describes current architecture | Cross-reference with actual file structure via `analyze_structure` |\n| Treat test TODOs as production tech debt | Separate coverage gaps from production concerns in `concerns.md` |'},{file:`references/project-knowledge-templates.md`,content:`# Project Knowledge Templates
+*Templates follow the Diátaxis documentation framework (CC-BY-SA 4.0, Daniele Procida).*`},{file:`references/flow-artifacts-guide.md`,content:'# Flow Artifacts Guide\n\n## What Are Flow Artifacts\n\nFlows produce structured markdown artifacts in `{{artifacts_path}}/`. These files capture requirements, decisions, plan shape, implementation progress, and verification results for the completed flow.\n\nUse artifacts to document the why behind changes. Code diffs still matter, but artifacts usually contain the rationale, constraints, risks, and review findings that should shape durable documentation.\n\n## How to Discover Artifacts\n\n```text\nflow_status()                                      # Get artifactsPath\nfind({ pattern: "*.md", path: "<artifactsPath>" }) # Discover artifact files\ndigest({ sources: [                                # Compress into working context\n  { path: "<found-artifact-1>" },\n  { path: "<found-artifact-2>" },\n  ...\n]})\n```\n\nRead every artifact `find()` returns. Different flows produce different files — do not assume specific filenames exist.\n\n## Artifact Catalog\n\n| Artifact | Flow | Contains |\n|---|---|---|\n| `design-decisions.md` | `aikit:basic`, `aikit:advanced` | FORGE tier, approach, key decisions, constraints, and risks |\n| `assessment.md` | `aikit:basic` | Goal, affected files, approach steps, risks, and open questions |\n| `spec.md` | `aikit:advanced` | Requirements, acceptance criteria, and scope boundaries |\n| `plan.md` | `aikit:advanced` | Phased implementation plan and architecture decisions |\n| `tasks.md` | `aikit:advanced` | Atomic task list, dependencies, and agent assignments |\n| `progress.md` | `aikit:basic`, `aikit:advanced` | Changes made, tests, deviations, and validation results |\n| `verify-report.md` | `aikit:basic`, `aikit:advanced` | Verdict, quality gates, review findings, security, and recommendation |\n\n## Artifact-to-Documentation Mapping\n\n| Artifact | Contains | Documentation Target | Action |\n|---|---|---|---|\n| `design-decisions.md` | FORGE tier, approach, key decisions | `docs/decisions/` | Create or update ADRs via `adr-skill` for each key decision |\n| `design-decisions.md` | Architecture approach, constraints | `docs/architecture/overview.md` | Update the design rationale section |\n| `spec.md` | Requirements, acceptance criteria | `docs/reference/` | Update API or component reference when public surface changed |\n| `plan.md` | Architecture decisions, phase design | `docs/architecture/` | Update architecture docs with structural changes |\n| `tasks.md` | Task breakdown, dependencies | Usually skip | Only document if it reveals new component boundaries |\n| `progress.md` | Files changed, deviations, tests | `docs/guides/testing.md` | Update when testing strategy changed |\n| `progress.md` | Deviations from plan | `docs/decisions/` | Document significant deviations as ADRs |\n| `verify-report.md` | Code review findings, security | `docs/architecture/overview.md` | Update if findings reveal architectural patterns |\n| `verify-report.md` | Security concerns | `docs/guides/` | Create or update security guidance when concerns are material |\n\n## Reading Strategy\n\nRead every artifact `find()` returns. Triage by content type:\n\n| Content Signal | Documentation Value | Action |\n|---|---|---|\n| Decisions, rationale, constraints | High — durable knowledge | Extract into `docs/decisions/` or architecture docs |\n| Requirements, scope, acceptance criteria | High — defines intent | Update reference docs if public surface changed |\n| Review findings, security concerns, quality gates | Medium — surfaces issues | Update architecture or guides if findings are material |\n| Implementation progress, task lists | Low — transient | Document only meaningful deviations from the plan |\n\nSkip artifacts that only repeat completed work with no insights beyond the code diff.\n\n> The catalog and mapping tables above list artifacts from built-in flows (`aikit:basic`, `aikit:advanced`). Custom flows may produce entirely different artifacts — always discover dynamically with `find()` and classify by content, not by filename.\n\n## What Not to Document\n\n| Avoid | Do Instead |\n|---|---|\n| Copying artifact text verbatim into `docs/` | Extract decisions, rationale, constraints, and stable guidance |\n| Documenting every task or progress update | Keep only durable insights that help future readers |\n| Mirroring temporary planning details | Preserve the final reasoning, not the transient workflow chatter |'},{file:`references/project-knowledge-gotchas.md`,content:'# Project Knowledge — Gotchas\n\nCommon pitfalls when documenting project knowledge. Reference this during Phase 2 (Investigate) and Phase 4 (Validate).\n\n## Environment Gotchas\n\n**Monorepos:** Root `package.json` may have no source — check for `workspaces`, `packages/`, or `apps/` directories. Each workspace may have independent dependencies and conventions. Map each sub-package separately.\n\n**Outdated README:** README often describes intended architecture, not the current one. Cross-reference with actual file structure before treating any README claim as fact.\n\n**TypeScript path aliases:** `tsconfig.json` `paths` config means imports like `@/foo` don\'t map directly to the filesystem. Map aliases to real paths before documenting structure.\n\n**Generated/compiled output:** Never document patterns from `dist/`, `build/`, `generated/`, `.next/`, `out/`, or `__pycache__/`. These are artefacts — document source conventions only.\n\n**`.env.example` reveals required config:** Secrets are never committed. Read `.env.example`, `.env.template`, or `.env.sample` to discover required environment variables.\n\n**`devDependencies` ≠ production stack:** Only `dependencies` (or equivalent) runs in production. Document linters, formatters, and test frameworks separately as dev tooling in `stack.md`.\n\n**Test TODOs ≠ production debt:** TODOs inside test directories are coverage gaps, not production technical debt. Separate them in `concerns.md`.\n\n**High-churn files = fragile areas:** Files appearing most in recent `git_context({})` output have the highest modification rate and likely hidden complexity. Always note them in `concerns.md`.\n\n## Anti-Pattern Table\n\n| ❌ Don\'t | ✅ Do instead |\n|---------|--------------|\n| "Uses Clean Architecture with Domain/Data layers" (when no such directories exist) | State only what directory structure actually shows |\n| "This is a Next.js project" (without checking `package.json`) | Check `dependencies` first. State what\'s actually there |\n| Guess the database from a variable name like `dbUrl` | Check manifest for `pg`, `mysql2`, `mongoose`, `prisma`, etc. |\n| Document `dist/` or `build/` naming patterns as conventions | Source files only |\n| Assume README describes current architecture | Cross-reference with actual file structure via `analyze({ aspect: "structure", ... })` |\n| Treat test TODOs as production tech debt | Separate coverage gaps from production concerns in `concerns.md` |'},{file:`references/project-knowledge-templates.md`,content:`# Project Knowledge Templates
 
 Templates for the seven project knowledge documents in \`docs/architecture/\`. Use these to ensure consistent structure across projects.
 
@@ -5016,8 +5016,8 @@ Templates for the seven project knowledge documents in \`docs/architecture/\`. U
 
 ## Evidence
 
-- \`analyze_structure\` output — directory tree
-- \`analyze_entry_points\` output — entry points
+- \`analyze({ aspect: "structure", ... })\` output — directory tree
+- \`analyze({ aspect: "entry_points", ... })\` output — entry points
 \`\`\`
 
 ## design.md
@@ -5057,9 +5057,9 @@ Templates for the seven project knowledge documents in \`docs/architecture/\`. U
 
 ## Evidence
 
-- \`analyze_structure\` output — layers
-- \`analyze_patterns\` output — design patterns
-- \`analyze_diagram\` output — component diagrams
+- \`analyze({ aspect: "structure", ... })\` output — layers
+- \`analyze({ aspect: "patterns", ... })\` output — design patterns
+- \`analyze({ aspect: "diagram", ... })\` output — component diagrams
 \`\`\`
 
 ## conventions.md
@@ -5097,7 +5097,7 @@ Templates for the seven project knowledge documents in \`docs/architecture/\`. U
 
 ## Evidence
 
-- \`analyze_patterns\` output — detected conventions
+- \`analyze({ aspect: "patterns", ... })\` output — detected conventions
 - Linter/formatter config files — enforced rules
 \`\`\`
 
@@ -5136,7 +5136,7 @@ Templates for the seven project knowledge documents in \`docs/architecture/\`. U
 
 ## Evidence
 
-- \`analyze_dependencies\` output — external packages
+- \`analyze({ aspect: "dependencies", ... })\` output — external packages
 - \`.env.example\` — required environment variables
 - CI config files — pipeline definitions
 \`\`\`
@@ -5178,7 +5178,7 @@ Templates for the seven project knowledge documents in \`docs/architecture/\`. U
 
 ## Evidence
 
-- \`analyze_patterns\` output — test patterns
+- \`analyze({ aspect: "patterns", ... })\` output — test patterns
 - \`test_run({})\` output — test health
 - Test config files — framework configuration
 \`\`\`
@@ -5241,8 +5241,8 @@ Detailed workflow for acquiring and documenting project knowledge into \`docs/ar
 \`\`\`
 onboard({ path: "." })                           # Full codebase scan
 produce_knowledge({ path: "." })                  # Comprehensive analysis
-analyze_structure({ path: "." })                  # Project layout, packages, layers
-analyze_dependencies({ path: "." })               # All dependencies + import graph
+analyze({ aspect: "structure", path: "." })      # Project layout, packages, layers
+analyze({ aspect: "dependencies", path: "." })   # All dependencies + import graph
 \`\`\`
 
 Then read \`README\`, \`PRD\`, \`TRD\`, \`ROADMAP\`, \`SPEC\`, \`DESIGN\` files if they exist.
@@ -5254,12 +5254,12 @@ Use Phase 1 tool outputs to answer questions for each of the seven documents. Ru
 
 | Document | Investigation Tools |
 |----------|-------------------|
-| stack.md | \`analyze_dependencies\` → manifests, frameworks; \`analyze_structure\` → runtime signals |
-| structure.md | \`analyze_structure\` → file tree, packages; \`analyze_entry_points\` → entry points, key files |
-| design.md | \`analyze_structure\` → layers; \`analyze_patterns\` → design patterns; \`analyze_diagram\` → component diagrams |
-| conventions.md | \`analyze_patterns\` → naming, formatting; \`search("conventions")\` → detected conventions |
-| integrations.md | \`analyze_dependencies\` → external deps; \`search("API\\|database\\|auth\\|webhook")\` → integration points |
-| testing.md | \`analyze_patterns\` → test patterns; \`search("test framework")\` → test setup; \`test_run({})\` → test health |
+| stack.md | \`analyze({ aspect: "dependencies", ... })\` → manifests, frameworks; \`analyze({ aspect: "structure", ... })\` → runtime signals |
+| structure.md | \`analyze({ aspect: "structure", ... })\` → file tree, packages; \`analyze({ aspect: "entry_points", ... })\` → entry points, key files |
+| design.md | \`analyze({ aspect: "structure", ... })\` → layers; \`analyze({ aspect: "patterns", ... })\` → design patterns; \`analyze({ aspect: "diagram", ... })\` → component diagrams |
+| conventions.md | \`analyze({ aspect: "patterns", ... })\` → naming, formatting; \`search("conventions")\` → detected conventions |
+| integrations.md | \`analyze({ aspect: "dependencies", ... })\` → external deps; \`search("API\\|database\\|auth\\|webhook")\` → integration points |
+| testing.md | \`analyze({ aspect: "patterns", ... })\` → test patterns; \`search("test framework")\` → test setup; \`test_run({})\` → test health |
 | concerns.md | \`audit({ path: "." })\` → health issues; \`dead_symbols({})\` → dead code; \`git_context({})\` → high-churn files |
 
 ### Phase 3: Populate Documents
@@ -5366,12 +5366,12 @@ Use these existing AI Kit tools to generate documentation content — never writ
 | Documentation Task | AI Kit Tool | What It Provides |
 |---|---|---|
 | Project overview | \`produce_knowledge({ path: "." })\` | Comprehensive analysis: structure, patterns, dependencies → \`docs/README.md\` |
-| Architecture overview | \`analyze_structure({ path: "." })\` | File tree, package layout, layer organization → \`docs/architecture/overview.md\` |
-| Architecture diagrams | \`analyze_diagram({ path: "." })\` | Mermaid diagrams of component relationships → \`docs/architecture/\` |
-| Dependency map | \`analyze_dependencies({ path: "." })\` | Import graph, cross-package edges → \`docs/architecture/overview.md\` dependencies section |
-| Component analysis | \`analyze_symbols({ path: "src/component" })\` | Exports, classes, interfaces → \`docs/architecture/components/{name}.md\` |
-| Entry points / API surface | \`analyze_entry_points({ path: "." })\` | CLI bins, route handlers, main exports → \`docs/reference/api.md\` |
-| Code patterns | \`analyze_patterns({ path: "." })\` | Design patterns, conventions → \`docs/architecture/overview.md\` patterns section |
+| Architecture overview | \`analyze({ aspect: "structure", path: "." })\` | File tree, package layout, layer organization → \`docs/architecture/overview.md\` |
+| Architecture diagrams | \`analyze({ aspect: "diagram", path: "." })\` | Mermaid diagrams of component relationships → \`docs/architecture/\` |
+| Dependency map | \`analyze({ aspect: "dependencies", path: "." })\` | Import graph, cross-package edges → \`docs/architecture/overview.md\` dependencies section |
+| Component analysis | \`analyze({ aspect: "symbols", path: "src/component" })\` | Exports, classes, interfaces → \`docs/architecture/components/{name}.md\` |
+| Entry points / API surface | \`analyze({ aspect: "entry_points", path: "." })\` | CLI bins, route handlers, main exports → \`docs/reference/api.md\` |
+| Code patterns | \`analyze({ aspect: "patterns", path: "." })\` | Design patterns, conventions → \`docs/architecture/overview.md\` patterns section |
 | Impact analysis | \`blast_radius({ changed_files: [...] })\` | What's affected by changes → targeted doc updates |
 | Change detection | \`git_context({})\` | Recent changes, diff summary → determine which docs need updating |
 | Module graph | \`graph({ action: 'neighbors', node_id })\` | Who-imports-whom, cross-package dependencies → architecture diagrams |
@@ -5586,12 +5586,12 @@ All of the following must be true before finishing:
 
 | Document | Covers | Primary Tools |
 |----------|--------|---------------|
-| \`stack.md\` | Language, runtime, frameworks, dependencies, dev tooling | \`analyze_dependencies\`, \`analyze_structure\` |
-| \`structure.md\` | Directory layout, entry points, key files, packages | \`analyze_structure\`, \`analyze_entry_points\` |
-| \`design.md\` | Layers, patterns, data flow, component boundaries | \`analyze_structure\`, \`analyze_patterns\`, \`analyze_diagram\` |
-| \`conventions.md\` | Naming, formatting, error handling, import conventions | \`analyze_patterns\`, \`search("conventions")\` |
-| \`integrations.md\` | External APIs, databases, auth, monitoring, CI/CD | \`analyze_dependencies\`, \`search("API\\|database\\|auth")\` |
-| \`testing.md\` | Test frameworks, file organization, mocking, coverage | \`analyze_patterns\`, \`test_run({})\`, \`search("test")\` |
+| \`stack.md\` | Language, runtime, frameworks, dependencies, dev tooling | \`analyze({ aspect: "dependencies", ... })\`, \`analyze({ aspect: "structure", ... })\` |
+| \`structure.md\` | Directory layout, entry points, key files, packages | \`analyze({ aspect: "structure", ... })\`, \`analyze({ aspect: "entry_points", ... })\` |
+| \`design.md\` | Layers, patterns, data flow, component boundaries | \`analyze({ aspect: "structure", ... })\`, \`analyze({ aspect: "patterns", ... })\`, \`analyze({ aspect: "diagram", ... })\` |
+| \`conventions.md\` | Naming, formatting, error handling, import conventions | \`analyze({ aspect: "patterns", ... })\`, \`search("conventions")\` |
+| \`integrations.md\` | External APIs, databases, auth, monitoring, CI/CD | \`analyze({ aspect: "dependencies", ... })\`, \`search("API\\|database\\|auth")\` |
+| \`testing.md\` | Test frameworks, file organization, mocking, coverage | \`analyze({ aspect: "patterns", ... })\`, \`test_run({})\`, \`search("test")\` |
 | \`concerns.md\` | Tech debt, bugs, security risks, perf, high-churn files | \`audit()\`, \`dead_symbols()\`, \`git_context()\` |
 
 Use [references/project-knowledge-templates.md](references/project-knowledge-templates.md) for the standard template of each document.
@@ -5611,17 +5611,17 @@ When bootstrapping \`docs/\` for the first time or refreshing architecture docum
 
 \`\`\`
 Step 1: Detect & Analyze
-  analyze_structure({ path: "." })                    → project layout, packages, layers
-  analyze_patterns({ path: "." })                     → conventions, design patterns
-  analyze_entry_points({ path: "." })                 → API surface, CLI entry points
+  analyze({ aspect: "structure", path: "." })        → project layout, packages, layers
+  analyze({ aspect: "patterns", path: "." })         → conventions, design patterns
+  analyze({ aspect: "entry_points", path: "." })     → API surface, CLI entry points
 
 Step 2: Map Dependencies
-  analyze_dependencies({ path: "." })                 → import graph, cross-package edges
+  analyze({ aspect: "dependencies", path: "." })     → import graph, cross-package edges
   graph({ action: 'find_nodes', name_pattern: '*' })   → module graph nodes
   graph({ action: 'neighbors', node_id: '...' })       → dependency directions
 
 Step 3: Visualize
-  analyze_diagram({ path: "." })                      → Mermaid architecture diagrams
+  analyze({ aspect: "diagram", path: "." })          → Mermaid architecture diagrams
   Delegate to c4-architecture skill                    → C4 context/container/component views
 
 Step 4: Synthesize
@@ -5635,21 +5635,21 @@ The architecture blueprint should cover these areas (adapted from the Architectu
 
 #### 1. Architecture Detection & Analysis
 - **Auto-detect**: Project type, framework, architectural pattern (Clean Architecture, Microservices, Layered, etc.)
-- **Tools**: \`analyze_structure\` → folder organization, \`analyze_patterns\` → framework detection, \`analyze_dependencies\` → dependency flow
+- **Tools**: \`analyze({ aspect: "structure", ... })\` → folder organization, \`analyze({ aspect: "patterns", ... })\` → framework detection, \`analyze({ aspect: "dependencies", ... })\` → dependency flow
 - **Output**: \`docs/architecture/overview.md\` header section
 
 #### 2. Architectural Overview
 - Guiding principles from code structure
 - Architectural boundaries and enforcement mechanisms
 - Hybrid patterns or adaptations
-- **Tools**: \`produce_knowledge\` + \`analyze_structure\`
+- **Tools**: \`produce_knowledge\` + \`analyze({ aspect: "structure", ... })\`
 - **Output**: \`docs/architecture/overview.md\` main body
 
 #### 3. Architecture Visualization
 - High-level subsystem diagram
 - Component interaction diagrams
 - Data flow diagrams
-- **Tools**: \`analyze_diagram\` + \`c4-architecture\` skill
+- **Tools**: \`analyze({ aspect: "diagram", ... })\` + \`c4-architecture\` skill
 - **Output**: \`docs/architecture/overview.md\` diagrams + \`docs/architecture/diagrams/\`
 
 #### 4. Core Architectural Components
@@ -5658,7 +5658,7 @@ For each major component:
 - Internal structure
 - Key abstractions
 - Interaction patterns
-- **Tools**: \`analyze_symbols({ path: "component/" })\` + \`compact({ path, query: "exports" })\`
+- **Tools**: \`analyze({ aspect: "symbols", path: "component/" })\` + \`compact({ path, query: "exports" })\`
 - **Output**: \`docs/architecture/components/{name}.md\`
 
 #### 5. Layers & Dependencies
@@ -5666,7 +5666,7 @@ For each major component:
 - Dependency rules between layers
 - Abstraction mechanisms for separation
 - Circular dependencies or violations
-- **Tools**: \`analyze_dependencies\` + \`graph({ action: 'neighbors' })\`
+- **Tools**: \`analyze({ aspect: "dependencies", ... })\` + \`graph({ action: 'neighbors' })\`
 - **Output**: \`docs/architecture/overview.md\` layers section
 
 #### 6. Cross-Cutting Concerns
@@ -5675,21 +5675,21 @@ Document implementation patterns for:
 - Logging & observability
 - Validation patterns
 - Configuration management
-- **Tools**: \`analyze_patterns\` + \`search({ query: "error handling" })\`
+- **Tools**: \`analyze({ aspect: "patterns", ... })\` + \`search({ query: "error handling" })\`
 - **Output**: \`docs/architecture/overview.md\` cross-cutting section
 
 #### 7. Testing Architecture
 - Test framework and strategy
 - Test boundary patterns (unit, integration, e2e)
 - Test file conventions
-- **Tools**: \`analyze_patterns\` + \`search({ query: "test" })\`
+- **Tools**: \`analyze({ aspect: "patterns", ... })\` + \`search({ query: "test" })\`
 - **Output**: \`docs/guides/testing.md\`
 
 #### 8. Extension & Evolution
 - How to add features while preserving architecture
 - Component creation patterns
 - Integration patterns for external systems
-- **Tools**: \`analyze_entry_points\` + \`analyze_patterns\`
+- **Tools**: \`analyze({ aspect: "entry_points", ... })\` + \`analyze({ aspect: "patterns", ... })\`
 - **Output**: \`docs/guides/contributing.md\` or \`docs/architecture/overview.md\` extension section
 
 ## Rules for the \`_docs-sync\` Epilogue Step
@@ -5747,24 +5747,24 @@ If \`docs/\` doesn't exist, run the full Architecture Blueprint workflow:
 \`\`\`
 # Generate content with tools
 produce_knowledge({ path: "." })           # → docs/README.md foundation
-analyze_structure({ path: "." })           # → docs/architecture/overview.md structure section
-analyze_diagram({ path: "." })             # → docs/architecture/ Mermaid diagrams
-analyze_dependencies({ path: "." })        # → docs/architecture/overview.md dependency section
-analyze_entry_points({ path: "." })        # → docs/reference/api.md foundation
-analyze_patterns({ path: "." })            # → docs/architecture/overview.md patterns section
+analyze({ aspect: "structure", path: "." })      # → docs/architecture/overview.md structure section
+analyze({ aspect: "diagram", path: "." })        # → docs/architecture/ Mermaid diagrams
+analyze({ aspect: "dependencies", path: "." })   # → docs/architecture/overview.md dependency section
+analyze({ aspect: "entry_points", path: "." })   # → docs/reference/api.md foundation
+analyze({ aspect: "patterns", path: "." })       # → docs/architecture/overview.md patterns section
 
 # Create the docs/ tree
 docs/
 ├── README.md              ← From produce_knowledge output + project context
 ├── architecture/
-│   ├── overview.md        ← From analyze_structure + analyze_dependencies + analyze_diagram
-│   └── components/        ← From analyze_symbols per major component
+│   ├── overview.md        ← From analyze(structure|dependencies|diagram)
+│   └── components/        ← From analyze(symbols) per major component
 ├── decisions/
 │   └── index.md           ← ADR log with Source column linking to flow artifacts
 ├── guides/
-│   └── testing.md         ← From analyze_patterns test info
+│   └── testing.md         ← From analyze(patterns) test info
 └── reference/
-    └── api.md             ← From analyze_entry_points
+    └── api.md             ← From analyze(entry_points)
 \`\`\`
 
 ### 4. Update Existing Docs (tool-assisted)
@@ -9758,7 +9758,7 @@ Determine which mode applies:
 **Proactive suggestion?** After substantial work (5+ file edits, complex debugging, major decisions), suggest:
 > "We've made significant progress. Consider creating a handoff document to preserve this context for future sessions. Say 'create handoff' when ready."
 
-> **aikit Integration:** If the project uses the aikit MCP server, complement file-based handoffs with \`remember({ title: "Session checkpoint: ...", content: "...", category: "conventions" })\` to persist key decisions in the knowledge base. Use \`search({ query: "SESSION CHECKPOINT" })\` at session start to retrieve past checkpoints.
+> **aikit Integration:** If the project uses the aikit MCP server, complement file-based handoffs with \`knowledge({ action: "remember", title: "Session checkpoint: ...", content: "...", category: "conventions" })\` to persist key decisions in the AI Kit knowledge store. Use \`search({ query: "SESSION CHECKPOINT" })\` at session start to retrieve past checkpoints.
 
 ## CREATE Workflow
 

package/scaffold/dist/definitions/tools.mjs

@@ -1 +1 @@
-const e=`analyze_dependencies.analyze_diagram.analyze_entry_points.analyze_patterns.analyze_structure.analyze_symbols.audit.batch.blast_radius.brainstorm.changelog.check.checkpoint.codemod.compact.config.data_transform.dead_symbols.delegate.describe_tool.diff_parse.digest.encode.env.eval.evidence_map.file_summary.find.flow_add.flow_info.flow_list.flow_read_instruction.flow_remove.flow_reset.flow_start.flow_status.flow_step.flow_update.forge_classify.forge_ground.forget.git_context.graph.guide.health.http.lane.list.list_tools.lookup.measure.onboard.parse_output.present.process.produce_knowledge.queue.read.regex_test.reindex.remember.rename.replay.restore.schema_validate.scope_map.search.search_tools.session_digest.snippet.stash.status.stratum_card.symbol.test_run.time.trace.update.watch.web_fetch.web_search.workset`.split(`.`),t={orchestrator:[`memory`,`runCommand`,`switchAgent`,`newWorkspace`,`reviewPlan`,`killTerminal`,`createTask`,`terminal`,`terminalSel`,`lastCommand`,`problems`,`readFile`,`subagent`,`createFile`,`editFiles`,`rename`,`createDirectory`,`search`,`web`,`todo`,`searchSubagent`,`textSearch`,`browser`,`askQuestions`,`resolveMemoryFileUri`],researcher:[`terminal`,`problems`,`readFile`,`lastCommand`,`subagent`,`search`,`web`,`browser`],reviewer:[`terminal`,`problems`,`readFile`,`lastCommand`,`subagent`,`search`,`web`,`browser`],codeAgent:[`createTask`,`terminal`,`problems`,`readFile`,`lastCommand`,`subagent`,`createFile`,`editFiles`,`rename`,`createDirectory`,`search`,`todo`,`browser`],debugger:[`terminal`,`problems`,`readFile`,`terminalSel`,`lastCommand`,`subagent`,`createFile`,`editFiles`,`search`,`browser`],refactor:[`terminal`,`problems`,`readFile`,`lastCommand`,`subagent`,`createFile`,`editFiles`,`rename`,`createDirectory`,`search`,`browser`],explorer:[`problems`,`readFile`,`search`,`fileSearch`,`listDir`,`textSearch`,`browser`],planner:[`terminal`,`problems`,`readFile`,`reviewPlan`,`memory`,`askQuestions`,`resolveMemoryFileUri`,`lastCommand`,`subagent`,`createFile`,`editFiles`,`rename`,`createDirectory`,`search`,`web`,`todo`,`searchSubagent`,`browser`],security:[`terminal`,`problems`,`readFile`,`subagent`,`search`,`web`,`browser`],documenter:[`terminal`,`problems`,`readFile`,`lastCommand`,`subagent`,`createFile`,`editFiles`,`rename`,`createDirectory`,`search`,`web`,`browser`]};export{e as AIKIT_TOOLS,t as IDE_CAPABILITIES};
+const e=`analyze.audit.batch.blast_radius.brainstorm.changelog.check.checkpoint.codemod.compact.config.data_transform.dead_symbols.delegate.describe_tool.diff_parse.digest.encode.env.eval.evidence_map.file_summary.find.flow_add.flow_info.flow_list.flow_read_instruction.flow_remove.flow_reset.flow_start.flow_status.flow_step.flow_update.forge_classify.forge_ground.git_context.graph.guide.health.http.knowledge.lane.list_tools.lookup.measure.onboard.parse_output.present.process.produce_knowledge.queue.regex_test.reindex.rename.replay.restore.schema_validate.scope_map.search.search_tools.session_digest.snippet.stash.status.stratum_card.symbol.test_run.time.trace.watch.web_fetch.web_search.workset`.split(`.`),t={orchestrator:[`memory`,`runCommand`,`switchAgent`,`newWorkspace`,`reviewPlan`,`killTerminal`,`createTask`,`terminal`,`terminalSel`,`lastCommand`,`problems`,`readFile`,`subagent`,`createFile`,`editFiles`,`rename`,`createDirectory`,`search`,`web`,`todo`,`searchSubagent`,`textSearch`,`browser`,`askQuestions`,`resolveMemoryFileUri`],researcher:[`terminal`,`problems`,`readFile`,`lastCommand`,`subagent`,`search`,`web`,`browser`],reviewer:[`terminal`,`problems`,`readFile`,`lastCommand`,`subagent`,`search`,`web`,`browser`],codeAgent:[`createTask`,`terminal`,`problems`,`readFile`,`lastCommand`,`subagent`,`createFile`,`editFiles`,`rename`,`createDirectory`,`search`,`todo`,`browser`],debugger:[`terminal`,`problems`,`readFile`,`terminalSel`,`lastCommand`,`subagent`,`createFile`,`editFiles`,`search`,`browser`],refactor:[`terminal`,`problems`,`readFile`,`lastCommand`,`subagent`,`createFile`,`editFiles`,`rename`,`createDirectory`,`search`,`browser`],explorer:[`problems`,`readFile`,`search`,`fileSearch`,`listDir`,`textSearch`,`browser`],planner:[`terminal`,`problems`,`readFile`,`reviewPlan`,`memory`,`askQuestions`,`resolveMemoryFileUri`,`lastCommand`,`subagent`,`createFile`,`editFiles`,`rename`,`createDirectory`,`search`,`web`,`todo`,`searchSubagent`,`browser`],security:[`terminal`,`problems`,`readFile`,`subagent`,`search`,`web`,`browser`],documenter:[`terminal`,`problems`,`readFile`,`lastCommand`,`subagent`,`createFile`,`editFiles`,`rename`,`createDirectory`,`search`,`web`,`browser`]};export{e as AIKIT_TOOLS,t as IDE_CAPABILITIES};

package/packages/cli/dist/init-CVtbu7zj.js

@@ -1,7 +0,0 @@
-import{i as e,n as t,r as n,t as r}from"./constants-BHJ95m41.js";import{n as i,t as a}from"./templates-DVcEiTlc.js";import{guideFlows as o,guideScaffold as s,guideSkills as c,smartCopyClaudeCommands as l,smartCopyFlows as u,smartCopyScaffold as d,smartCopySkills as f}from"./scaffold-D664MT9M.js";import{appendFileSync as p,existsSync as m,mkdirSync as h,readFileSync as g,unlinkSync as _,writeFileSync as v}from"node:fs";import{basename as y,dirname as b,join as x,resolve as S}from"node:path";import{fileURLToPath as C}from"node:url";import{AIKIT_PATHS as w,isUserInstalled as T}from"../../core/dist/index.js";function E(e){return m(S(e,`.cursor`))?`cursor`:m(S(e,`.claude`))?`claude-code`:m(S(e,`.windsurf`))?`windsurf`:`copilot`}function D(e){return{servers:{[e]:{...t}}}}function O(e){let{type:n,...r}=t;return{mcpServers:{[e]:r}}}const k={scaffoldDir:`general`,writeMcpConfig(e,t){let n=S(e,`.vscode`),r=S(n,`mcp.json`);m(r)||(h(n,{recursive:!0}),v(r,`${JSON.stringify(D(t),null,2)}\n`,`utf-8`),console.log(`  Created .vscode/mcp.json`))},writeInstructions(e,t){let n=S(e,`.github`),r=S(n,`copilot-instructions.md`);h(n,{recursive:!0}),v(r,i(y(e),t),`utf-8`),console.log(`  Updated .github/copilot-instructions.md`)},writeAgentsMd(e,t){v(S(e,`AGENTS.md`),a(y(e),t),`utf-8`),console.log(`  Updated AGENTS.md`)}},A={scaffoldDir:`general`,writeMcpConfig(e,t){let n=S(e,`.mcp.json`);m(n)||(v(n,`${JSON.stringify(O(t),null,2)}\n`,`utf-8`),console.log(`  Created .mcp.json`))},writeInstructions(e,t){let n=S(e,`CLAUDE.md`),r=y(e);v(n,`${i(r,t)}\n---\n\n${a(r,t)}`,`utf-8`),console.log(`  Updated CLAUDE.md`)},writeAgentsMd(e,t){}},j={scaffoldDir:`general`,writeMcpConfig(e,t){let n=S(e,`.cursor`),r=S(n,`mcp.json`);m(r)||(h(n,{recursive:!0}),v(r,`${JSON.stringify(O(t),null,2)}\n`,`utf-8`),console.log(`  Created .cursor/mcp.json`))},writeInstructions(e,t){let n=S(e,`.cursor`,`rules`),r=S(n,`aikit.mdc`);h(n,{recursive:!0});let o=y(e);v(r,`${i(o,t)}\n---\n\n${a(o,t)}`,`utf-8`),console.log(`  Updated .cursor/rules/aikit.mdc`);let s=S(n,`kb.mdc`);m(s)&&s!==r&&(_(s),console.log(`  Removed legacy .cursor/rules/kb.mdc`))},writeAgentsMd(e,t){}},M={scaffoldDir:`general`,writeMcpConfig(e,t){let n=S(e,`.vscode`),r=S(n,`mcp.json`);m(r)||(h(n,{recursive:!0}),v(r,`${JSON.stringify(D(t),null,2)}\n`,`utf-8`),console.log(`  Created .vscode/mcp.json (Windsurf-compatible)`))},writeInstructions(e,t){let n=S(e,`.windsurfrules`),r=y(e);v(n,`${i(r,t)}\n---\n\n${a(r,t)}`,`utf-8`),console.log(`  Updated .windsurfrules`)},writeAgentsMd(e,t){}};function N(e){switch(e){case`copilot`:return k;case`claude-code`:return A;case`cursor`:return j;case`windsurf`:return M}}const P={serverName:n,sources:[{path:`.`,excludePatterns:[`**/node_modules/**`,`**/dist/**`,`**/build/**`,`**/.git/**`,`**/${w.data}/**`,`**/coverage/**`,`**/*.min.js`,`**/package-lock.json`,`**/pnpm-lock.yaml`]}],indexing:{chunkSize:1500,chunkOverlap:200,minChunkSize:100},embedding:{model:`mixedbread-ai/mxbai-embed-large-v1`,dimensions:1024},store:{backend:`lancedb`,path:`${w.data}/lance`},curated:{path:w.aiCurated}};function F(e,t){let n=S(e,`aikit.config.json`);return m(n)&&!t?(console.log(`aikit.config.json already exists. Use --force to overwrite.`),!1):(v(n,`${JSON.stringify(P,null,2)}\n`,`utf-8`),console.log(`  Created aikit.config.json`),!0)}function I(e){let t=S(e,`.gitignore`),n=[{dir:`${w.data}/`,label:`AI Kit vector store`},{dir:`${w.state}/`,label:`AI Kit session state`},{dir:`${w.restorePoints}/`,label:`Restore points (codemod/rename undo snapshots)`},{dir:`${w.brainstorm}/`,label:`Brainstorming sessions`},{dir:`${w.handoffs}/`,label:`Handoff documents`}];if(m(t)){let e=g(t,`utf-8`),r=n.filter(t=>!e.includes(t.dir));r.length>0&&(p(t,`\n${r.map(e=>`# ${e.label}\n${e.dir}`).join(`
-`)}\n`,`utf-8`),console.log(`  Added ${r.map(e=>e.dir).join(`, `)} to .gitignore`))}else v(t,`${n.map(e=>`# ${e.label}\n${e.dir}`).join(`
-`)}\n`,`utf-8`),console.log(`  Created .gitignore with AI Kit entries`)}function L(){return P.serverName}const R=[`decisions`,`patterns`,`conventions`,`troubleshooting`];function z(e){let t=S(e,`.ai`,`curated`);m(t)||(h(t,{recursive:!0}),console.log(`  Created .ai/curated/`));for(let e of R){let n=S(t,e);m(n)||h(n,{recursive:!0})}console.log(`  Created .ai/curated/{${R.join(`,`)}}/`)}function B(e){let t=e;for(let e=0;e<10;e++){try{let e=x(t,`package.json`);if(m(e)&&JSON.parse(g(e,`utf8`)).name===`@vpxa/aikit`)return t}catch{}let e=b(t);if(e===t)break;t=e}return S(e,`..`,`..`,`..`)}async function V(t){let n=process.cwd();if(!F(n,t.force))return;I(n);let i=L(),a=N(E(n));a.writeMcpConfig(n,i),a.writeInstructions(n,i),a.writeAgentsMd(n,i);let o=B(b(C(import.meta.url))),s=JSON.parse(g(S(o,`package.json`),`utf-8`)).version;await f(n,o,[...e],s,t.force),await u(n,o,[...r],s,t.force),await d(n,o,`copilot`,s,t.force),await l(n,o,s,t.force),z(n),console.log(`
-AI Kit initialized! Next steps:`),console.log(`  aikit reindex  Index your codebase`),console.log(`  aikit search   Search indexed content`),console.log(`  aikit serve    Start MCP server for IDE integration`),T()&&console.log(`
-Note: User-level AI Kit is also installed. This workspace uses its own local data store.`)}async function H(e){T()?await U(e):await V(e)}async function U(e){let t=process.cwd(),n=L(),i=N(E(t));i.writeInstructions(t,n),i.writeAgentsMd(t,n);let a=B(b(C(import.meta.url))),o=JSON.parse(g(S(a,`package.json`),`utf-8`)).version;await d(t,a,`copilot`,o,e.force),await l(t,a,o,e.force),await u(t,a,[...r],o,e.force),z(t),I(t),console.log(`
-Workspace scaffolded for user-level AI Kit! Files added:`),console.log(`  Instruction files (AGENTS.md, copilot-instructions.md, etc.)`),console.log(`  .ai/curated/ directories`),console.log(`  .github/agents/ & .github/prompts/`),console.log(`
-The user-level AI Kit server will auto-index this workspace when opened in your IDE.`)}async function W(){let t=process.cwd(),n=N(E(t)),i=B(b(C(import.meta.url))),a=[...await c(t,i,[...e]),...await o(t,i,[...r]),...await s(t,i,n.scaffoldDir)],l={summary:{total:a.length,new:a.filter(e=>e.status===`new`).length,outdated:a.filter(e=>e.status===`outdated`).length,current:a.filter(e=>e.status===`current`).length},files:a};console.log(JSON.stringify(l,null,2))}export{W as guideProject,V as initProject,U as initScaffoldOnly,H as initSmart};