@vpxa/aikit 0.1.185 → 0.1.187

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

@@ -1,328 +1,301 @@
-var e=[{file:`SKILL.md`,content:'---\nname: aikit\ndescription: "Use the @vpxa/aikit AI Kit MCP server for codebase search, analysis, and persistent memory. Load when using any aikit_* tool. 63 tools: search (hybrid/semantic/keyword), code analysis (structure, deps, symbols, patterns, entry points, diagrams, blast radius), knowledge graph (module/symbol/import traversal), context (worksets, stash, checkpoints, lanes), signaling (inter-agent signals, leases), code manipulation (rename, codemod, eval), validation (check, test_run, audit), knowledge (remember/read/update/forget/list/history/diff/recover/orphaned/withdraw/flush/lesson), web (fetch, search, http), FORGE (ground, classify, evidence map, stratum cards, digest), flows (list, start, step, read, runs, add/remove/update), presentation (dashboards), onboarding, meta-tools, and utilities (regex, encode, measure, changelog, schema-validate, env, time)."\nmetadata:\n  category: cross-cutting\n  domain: general\n  applicability: always\n  inputs: [codebase]\n  outputs: [search-results, analysis, knowledge]\n  relatedSkills: [present]\n---\n\n# @vpxa/aikit — AI Kit\n\nLocal-first AI developer toolkit — 63 MCP tools for search, analysis, context compression, FORGE quality gates, knowledge management, signaling and coordination, code manipulation, execution, web access, flow management, presentation, meta-tool discovery, and developer utilities.\n\n## When to Use\n\n- You need long-term memory across coding sessions\n- You want to search a codebase semantically (by meaning, not just keywords)\n- You need to compress large contexts to focus on what matters\n- You want structured output from build tools (tsc, vitest, biome, git)\n- You need to plan which files to read for a task\n- You want to safely explore refactors in isolated lanes\n- You need to rename symbols, apply codemods, or run code transformations\n- You want to fetch and read web pages or search the web\n- You need to make HTTP requests, test APIs, or debug endpoints\n- You want to test regex patterns, encode/decode data, or validate JSON schemas\n- You need code complexity metrics or a git changelog\n\n## Skills Reference\n\n| Skill | Audience | Load when |\n|-------|----------|-----------|\n| `aikit` | All agents | **Always load at session start.** Tool signatures, workflows, session protocol. |\n| `brainstorming` | Orchestrator, Planner, Researchers | Design/planning phase — exploring requirements, user intent, and design before implementation. NOT for code agents. |\n| `session-handoff` | Any agent | Context window filling up, session ending, or major milestone completed. |\n| `requirements-clarity` | Orchestrator, Planner | Before planning vague or complex features — score 0-100 until ≥ 90. |\n| `lesson-learned` | Any agent | After completing work — extract principles from git diffs. |\n| `c4-architecture` | Planner, Documenter, Researchers | When documenting or reviewing architecture — C4 Mermaid diagrams. |\n| `adr-skill` | Orchestrator, Planner, Researchers | When making non-trivial technical decisions — executable ADRs. |\n| `present` | Orchestrator, Planner, Documenter | When presenting dashboards, charts, tables, or complex visual content to users. NOT for subagents. |\n| `typescript` | Implementer, Frontend, Refactor, Debugger | Before TypeScript implementation — type system, compiler config, advanced types. |\n| `react` | Frontend | Before React work — component architecture, React 19 APIs, Server Components. |\n| `frontend-design` | Frontend | Before UI/UX work — visual design, typography, color, layout, accessibility. |\n| `multi-agents-development` | Orchestrator | Before delegating to multiple agents — task decomposition, dispatch, review pipelines. |\n| `docs` | Documenter | When creating or updating project documentation — Diátaxis framework, staleness detection. |\n| `repo-access` | Any agent | When encountering git auth failures, accessing private/enterprise repos. |\n| `browser-use` | Frontend, any agent (auth) | When needing browser interaction — login flows, visual validation, web scraping. |\n\n## Architecture\n\n16-package monorepo published as a single npm package:\n\n```\ncore → store → embeddings → chunker → indexer → analyzers → tools → server → cli\n                                                                  ↕\n                    dashboard, elicitation, enterprise-bridge, flows, present, settings-ui, aikit-client\n```\n\n- **MCP server**: 62 tools + 2 resources (via `@modelcontextprotocol/sdk`)\n- **CLI**: 49 commands (thin dispatcher + 11 command groups)\n- **Search**: Hybrid vector + keyword + RRF fusion\n- **Embeddings**: ONNX local (mxbai-embed-large-v1, 512 dimensions, int8 quantized)\n- **Vector store**: SQLite-vec (embedded, zero infrastructure)\n- **Chunking**: Tree-sitter AST (TS/JS/Python/Go/Rust/Java) + regex fallback\n- **Dashboard**: Web-based dashboard for knowledge graph visualization and settings management\n\n## Session Protocol (MANDATORY)\n\n### Start (do ALL)\n```\nflow({ action: \'status\' })                                     # Check/resume active flow FIRST\n# If flow active → flow({ action: \'read\', step }) → follow step instructions\nstatus({})                                                     # Check AI Kit health + onboard state\n# If onboard not run → onboard({ path: "." })                 # First-time codebase analysis\nflow({ action: \'list\' })                                       # See available flows\n# Select flow based on task → flow({ action: \'start\', name: "<name>", topic: "<task>" })  # Start — creates .flows/{topic}/\nknowledge({ action: "list" })                                 # See stored knowledge\nsearch({ query: "SESSION CHECKPOINT", origin: "curated" })     # Resume prior work\n```\n\n### During Session\n```\nsearch → scope_map → symbol → trace  (orient)\ncheck → test_run                             (validate changes)\nknowledge({ action: "remember", ... })              (capture insights)\n```\n\n### End of Session\n```\nsession_digest({ persist: true })                              # Auto-capture session activity\nknowledge({ action: "remember", title: "Session checkpoint: <topic>", content: "<what was done, decisions made, next steps>", category: "conventions" })\n```\n\n## Tool Catalog\n\n### Search & Discovery (8)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `search` | `aikit search` | Hybrid/semantic/keyword search with `search_mode` param |\n| `find` | `aikit find` | Federated search: vector + FTS + glob + regex in one call. Use `mode: \'examples\'` to find usage examples. |\n| `symbol` | `aikit symbol` | Resolve symbol definition, imports, and references |\n| `lookup` | `aikit lookup` | Full-file retrieval by path or record ID |\n| `scope_map` | `aikit scope-map` | Task-scoped reading plan with token estimates |\n| `trace` | `aikit trace` | Forward/backward flow tracing through call chains |\n| `dead_symbols` | `aikit dead-symbols` | Find exported symbols never imported — separates source (actionable) from docs (informational). Accepts `path` to scope the search. |\n| `file_summary` | `aikit summarize` | Structural overview of a file (exports, imports, functions) |\n\n### Code Analysis (2)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `analyze` | `aikit analyze <aspect>` | Unified analyzer for structure, dependencies, symbols, patterns, entry_points, and diagram aspects |\n| `blast_radius` | `aikit analyze blast-radius` | Change impact analysis |\n\n### Context Management (6)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `compact` | `aikit compact` | Compress text to relevant sections using embeddings (no LLM). Accepts `path` for server-side file read. |\n| `workset` | `aikit workset` | Named file set management (save/load/add/remove) |\n| `stash` | `aikit stash` | Named key-value store for session data |\n| `checkpoint` | `aikit checkpoint` | Save/restore session checkpoints |\n| `restore` | `aikit restore` | Restore a previously saved checkpoint |\n| `parse_output` | `aikit parse-output` | Parse tsc/vitest/biome/git output → structured JSON |\n\n### Code Manipulation (4)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `rename` | `aikit rename` | Smart whole-word symbol rename across files (dry-run supported) |\n| `codemod` | `aikit codemod` | Regex-based code transformations with rules (dry-run supported) |\n| `diff_parse` | `aikit diff` | Parse unified diff → structured changes |\n| `data_transform` | `aikit transform` | JQ-like JSON transformations |\n\n### Execution & Validation (4)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `eval` | `aikit eval` | Sandboxed JavaScript/TypeScript execution |\n| `check` | `aikit check` | Incremental typecheck + lint. `detail` param: efficient (default, minimal), normal (parsed errors), full (includes raw) |\n| `test_run` | `aikit test` | Run tests with structured pass/fail results |\n| `audit` | `aikit audit` | Unified project audit: structure, deps, patterns, health, dead symbols, check, entry points → synthesized report with score and recommendations. 6 round-trips → 1. |\n\n### Knowledge Management (2)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `knowledge` | `aikit knowledge <action>` | Unified knowledge tool for remember, read, update, forget, list, history, diff, recover, orphaned, withdraw, flush, and `lesson` actions |\n| `produce_knowledge` | — | Auto-generate knowledge from analysis |\n\n### Signaling & Coordination (1)\n\n| `signal` | — | Inter-agent signaling and write-intent leases for multi-agent coordination |\n\n### Auto-Knowledge (automatic)\n\nTool outputs are automatically analyzed after every call. Useful facts (conventions, test patterns, build commands, errors) are extracted and stored as curated entries. Quality gate (score >= 0.3), deduplication, TTL for transient facts, max 50/session.\n\nSearch auto-knowledge with: `search({ query: "...", origin: "curated" })` or `knowledge({ action: "list", category: "conventions" })`\n\n### Verified Lanes (1 tool, 6 actions)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `lane` | `aikit lane` | Manage isolated file copies for parallel exploration |\n\nLane actions: `create` (copy files to lane), `list`, `status` (modified/added/deleted), `diff` (line-level diff), `merge` (apply back to originals), `discard`.\n\n### Git & Environment (4)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `git_context` | `aikit git` | Branch, status, recent commits |\n| `process` | `aikit proc` | Process supervisor (start/stop/logs) |\n| `watch` | `aikit watch` | Filesystem watcher |\n| `delegate` | `aikit delegate` | Delegate subtask to local Ollama model |\n\n### Web & Network (3)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `web_fetch` | — | Fetch web page → markdown/raw/links/outline for LLM consumption |\n| `web_search` | — | Multi-provider web search (DuckDuckGo + Bing-HTML + Mojeek fan-out, no API key needed) |\n| `http` | — | Make HTTP requests for API testing/debugging |\n\nExamples: `web_fetch({ urls: ["https://docs.example.com"], mode: "markdown" })`, `web_search({ queries: ["react suspense", "vitest retries"], limit: 5 })`\n\n### Browser Automation (1)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `browser` | — | Unified browser automation — owned Chromium runtime with 13 actions |\n\n**Actions:**\n| Action | Purpose | Key params |\n|--------|---------|------------|\n| `open` | Launch a browser page | `url`, `mode` (ui/headless/panel), `waitUntil`, `label`, `autoDialog` |\n| `read` | Extract page content | `readMode` (snapshot/dom/markdown/text), `selector` for scoping |\n| `act` | Interact with elements | `kind` (click/type/press/hover/drag/select/scroll/upload), `ref`/`selector` |\n| `network` | Capture network traffic | `subAction` (enable/get/clear/export-har), `filter` |\n| `console` | Browser console messages | `consoleSubAction` (enable/get/clear), `level` |\n| `fetch` | HTTP with page cookies/session | `fetchUrl`, `fetchMethod`, `fetchHeaders`, `fetchBody` |\n| `batch` | Multi-action execution | `steps` (array of action objects) |\n| `diff` | Snapshot diff vs baseline | `pageId` |\n| `navigate` | URL navigation and waiting | `url`, `type` (back/forward/reload/waitFor) |\n| `eval` | Execute JavaScript in page | `code` |\n| `screenshot` | Capture page/element | `selector`, `clip` ({x,y,width,height}), `format` (png/jpeg), `quality` (0-100), `fullPage` |\n| `dialog` | Handle browser dialogs | `accept`, `promptText` |\n| `session` | Manage pages and state | `sessionAction` (list/close/cookies/set-cookie/delete-cookie/clear-cookies/get-storage/set-storage/clear-storage) |\n\n**Read modes:** `snapshot` (accessibility tree, default), `dom` (cleaned HTML), `markdown` (converted md), `text` (visible text only). All support `selector` scoping.\n\n**Session state:** Full cookie CRUD (`set-cookie`, `delete-cookie`, `clear-cookies`, `cookies` to export) + localStorage/sessionStorage management (`get-storage`, `set-storage`, `clear-storage` with `storageType` param).\n\n### Developer Utilities (7)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `regex_test` | — | Test regex patterns with match/replace/split modes |\n| `encode` | — | Base64, URL, SHA-256, MD5, hex encode/decode, JWT decode |\n| `measure` | — | Code complexity metrics (cyclomatic, cognitive complexity, lines, functions) |\n| `changelog` | — | Generate changelog from git history (conventional commits) |\n| `schema_validate` | — | Validate JSON data against JSON Schema |\n| `env` | — | System and runtime environment info (sensitive values redacted) |\n| `time` | — | Date parsing, timezone conversion, duration math |\n\n### FORGE Quality Gates (5)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `forge_ground` | — | Full Ground phase: classify tier, scope map, unknowns, constraints |\n| `forge_classify` | — | Quick tier classification (Floor/Standard/Critical) |\n| `evidence_map` | — | CRUD + Gate evaluation for verified/assumed/unknown claims. Safety gate tags (`provenance`/`commitment`/`coverage`) enable mandatory pre-YIELD checks |\n| `stratum_card` | — | Generate T1/T2 compressed context cards from files (10-100x token reduction) |\n| `digest` | — | Compress N text sources into token-budgeted summary |\n\n### System (9)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `config` | `aikit config` | View or update project configuration (aikit.config.json) |\n| `status` | `aikit status` | Index statistics |\n| `reindex` | `aikit reindex` | Rebuild index |\n| `health` | `aikit health` | Project health checks (package.json, tsconfig, lockfile, circular deps) |\n| `guide` | `aikit guide` | Tool discovery — given a goal, recommends tools and workflow order |\n| `onboard` | `aikit onboard` | Full codebase onboarding in one call (structure + deps + patterns + knowledge) |\n| `graph` | `aikit graph` | Query the auto-populated knowledge graph (modules, symbols, imports) |\n| `queue` | `aikit queue` | Task queue for sequential agent operations (create/push/next/done/fail) |\n| `replay` | `aikit replay` | View or clear the audit trail of tool invocations (action: list/clear) |\n\n### Flows (1)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `flow` | `aikit flow` | Manage flows — list, start, navigate steps, read instructions, inspect runs, add/remove/update. |\n\n### Presentation (1)\n| Tool | CLI | Purpose |\n|------|-----|---------|\n| `present` | — | Rich dashboards, charts, tables, timelines. Use `blocks` or `template` + `data`; no `actions` renders inline in the host client, any `actions` uses browser transport. |\n\n**Viewer templates:** For architecture diagrams use `c4-static@1` (inline) or `c4@1` (interactive). For process flows use `process-flow-static@1` / `process-flow@1`. For code tours use `tour@1`.\nLoad the `present` skill for data schemas. Server validates template `data` — wrong shapes return clear field-level errors.\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), `token_budget`, `persist`. Use at session end for handoff or mid-session to review what happened. |\n\n## Execution & Data Tools\n\n### `eval` — Execute Code in Sandbox\n\nRun JavaScript or TypeScript snippets in a constrained VM. Captures console output and return values.\n\n**Parameters:**\n| Param | Type | Default | Description |\n|-------|------|---------|-------------|\n| `code` | string | — | Code to execute |\n| `lang` | `"js"` \\| `"ts"` | `"js"` | Language mode (ts strips type syntax first) |\n| `timeout` | number | 5000 | Execution timeout in ms (max 60000) |\n\n**Examples:**\n```\n// Quick calculation\neval({ code: "return [1,2,3].reduce((a,b) => a+b, 0)" })\n\n// Process data\neval({ code: "const data = [1,2,3,4,5]; return { sum: data.reduce((a,b)=>a+b), avg: data.reduce((a,b)=>a+b)/data.length }" })\n\n// TypeScript\neval({ code: "interface Point { x: number; y: number }; const p: Point = {x: 1, y: 2}; return p.x + p.y", lang: "ts" })\n```\n\n---\n\n### `data_transform` — jq-like JSON Transforms\n\nApply jq-inspired expressions to JSON input for filtering, projection, grouping, and extraction.\n\n**Parameters:**\n| Param | Type | Description |\n|-------|------|-------------|\n| `input` | string | JSON string to transform |\n| `expression` | string | Transform expression (see syntax below) |\n\n**Supported Expressions:**\n\n| Expression | Description | Example |\n|------------|-------------|---------|\n| `.` | Identity (return input as-is) | `.` |\n| `.field` | Access object field | `.name` |\n| `.[N]` | Array index access | `.[0]` |\n| `.field1.field2` | Nested field access | `.user.name` |\n| `| filter(condition)` | Filter array items | `| filter(.age > 18)` |\n| `| map(expr)` | Transform each item | `| map(.name)` |\n| `| sort_by(.field)` | Sort by field | `| sort_by(.date)` |\n| `| group_by(.field)` | Group items by field | `| group_by(.category)` |\n| `| select(cond)` | Keep items matching condition | `| select(.active == true)` |\n| `| flatten` | Flatten nested arrays | `| flatten` |\n| `| unique` | Remove duplicates | `| unique` |\n| `| keys` | Get object keys | `| keys` |\n| `| values` | Get object values | `| values` |\n| `| length` | Array/string length | `| length` |\n| `| join(sep)` | Join array with separator | `| join(", ")` |\n| `| first` | First element | `| first` |\n| `| last` | Last element | `| last` |\n| `| sum` | Sum numeric array | `| sum` |\n| `| avg` | Average of numeric array | `| avg` |\n| `| min` / `| max` | Min/max value | `| min` |\n\n**Comparisons:** `==`, `!=`, `>`, `<`, `>=`, `<=`\n**Logical:** `and`, `or`, `not`\n\n**Examples:**\n```\n// Filter and project\ndata_transform({ input: \'[{"name":"Alice","age":30},{"name":"Bob","age":17}]\', expression: \'| filter(.age >= 18) | map(.name)\' })\n// → ["Alice"]\n\n// Group and count\ndata_transform({ input: \'[{"type":"bug"},{"type":"feat"},{"type":"bug"}]\', expression: \'| group_by(.type)\' })\n// → {"bug":[...], "feat":[...]}\n\n// Sort and take first\ndata_transform({ input: \'[{"score":3},{"score":1},{"score":5}]\', expression: \'| sort_by(.score) | first\' })\n// → {"score":1}\n```\n\n---\n\n### `time` — Date & Time Operations\n\nParse dates, convert timezones, calculate durations, add time. Supports ISO 8601, unix timestamps, and human-readable formats.\n\n**Parameters:**\n| Param | Type | Description |\n|-------|------|-------------|\n| `operation` | string | `now`, `parse`, `convert`, `diff`, `add` |\n| `input` | string | Date input (ISO, unix, or parseable string). For `diff`: two comma-separated dates |\n| `timezone` | string | Target timezone (e.g., "America/New_York") |\n| `duration` | string | Duration to add (e.g., "2h30m", "1d", "30s") — for `add` |\n\n**Operations:**\n| Op | Purpose | Example |\n|----|---------|---------|\n| `now` | Current time in all formats | `time({ operation: "now" })` |\n| `parse` | Parse any date string | `time({ operation: "parse", input: "2024-03-15T10:30:00Z" })` |\n| `convert` | Convert to timezone | `time({ operation: "convert", input: "2024-03-15T10:30:00Z", timezone: "Asia/Tokyo" })` |\n| `diff` | Duration between dates | `time({ operation: "diff", input: "2024-01-01,2024-12-31" })` |\n| `add` | Add duration to date | `time({ operation: "add", input: "2024-03-15", duration: "2h30m" })` |\n\n**Duration format:** Combine: `Nd` (days), `Nh` (hours), `Nm` (minutes), `Ns` (seconds)\nExample: `"1d2h30m"` = 1 day, 2 hours, 30 minutes\n\n## Flow System\n\nFlows are multi-step guided workflows that structure complex tasks. Each step has a skill file with detailed instructions, required artifacts, and agent assignments.\n\n### Built-in Flows\n\n| Flow | Steps | Use When |\n|------|-------|----------|\n| `aikit:basic` | assess → implement → verify | Bug fixes, config changes, small features |\n| `aikit:advanced` | spec → plan → task → execute → verify | New modules, cross-service changes, architectural work |\n\n### Flow Lifecycle\n\n```text\nflow({ action: \'list\' })                                   # See available flows\nflow({ action: \'info\', name: \'aikit:basic\' })              # View steps, skills, agents\nflow({ action: \'start\', name: \'aikit:basic\', topic: \'Fix login bug\' })  # Start — creates .flows/fix-login-bug/\nflow({ action: \'read\' })                                   # Read current step\'s instructions ({{artifacts_path}} resolved)\n# ... do the work described in the instruction ...\nflow({ action: \'step\', advance: \'next\' })                  # Advance to next step\nflow({ action: \'step\', advance: \'skip\' })                  # Skip current step\nflow({ action: \'step\', advance: \'redo\' })                  # Redo current step\nflow({ action: \'status\' })                                 # Check progress (includes slug, runDir, artifactsPath, phase, isEpilogue)\nflow({ action: \'reset\' })                                  # Abandon active flow\nflow({ action: \'runs\' })                                   # List all runs (current + past)\n# Epilogue steps (mandatory, injected after every flow):\n# After last flow step → _docs-sync epilogue runs automatically\n# flow({ action: \'status\' }) shows phase: \'after\', isEpilogue: true during epilogue\n```\n\nCustom flow lifecycle management:\n\n```text\nflow({ action: \'add\', source: \'.github/flows/my-flow\' })\nflow({ action: \'update\', name: \'my-flow\' })\nflow({ action: \'remove\', name: \'my-flow\' })\n```\n\n## CRITICAL: Use AI Kit Tools Instead of Native IDE Tools\n\nAI Kit tools provide **10x richer output** than native IDE tools — with AST-analyzed call graphs, scope context, import classification, and cognitive complexity. **You MUST use AI Kit tools instead of native read/search tools.**\n\n### ⛔ PROHIBITED: Native File Reading\n\n**`read_file` / `read_file_raw` MUST NOT be used to understand code.** They waste tokens and miss structural information.\n\nThe **ONLY** acceptable use of `read_file`: getting exact lines immediately before an edit (to verify the `old_str` for replacement). Even then, use `file_summary` first to identify which lines to read.\n\n### Tool Replacement Table\n\n| ❌ NEVER do this | ✅ Use AI Kit Tool | Why |\n|---|---|---|\n| `read_file` (full file) | `file_summary` | Exports, imports, call edges — **10x fewer tokens** |\n| `read_file` (specific section) | `compact({ path, query })` | Server-side read + extract — **5-20x reduction** |\n| `grep_search` / `textSearch` | `search` | Semantic + keyword hybrid across all indexed content |\n| `grep_search` for a symbol | `symbol` | Definition + references **with scope context** |\n| Multiple `read_file` calls | `digest` | Compresses multiple sources into token-budgeted summary |\n| `listDirectory` + `read_file` | `scope_map` | Identifies relevant files for a task automatically |\n| Manual code tracing | `trace` | AST call-graph traversal with scope context |\n| Line counting / `wc` | `measure` | Lines, complexity, **cognitive complexity**, functions |\n| Grep for unused exports | `dead_symbols` | AST-powered export detection with regex fallback |\n| Repeated file reads | `stratum_card` | Reusable compressed context — **10-100x reduction** |\n| `fetch_webpage` | `web_fetch` | Readability extract + token budget — richer output |\n| Web research / browsing | `web_search` | Multi-provider web search without browser — **unique to AI Kit** |\n\n### Decision Tree — How to Read Code\n\n```\nNeed to understand a file?\n├─ Just structure?        → file_summary (exports, imports, call edges — ~50 tokens)\n├─ Specific section?      → compact({ path, query }) — 5-20x reduction\n├─ Multiple files?        → digest (multi-source compression — token-budgeted)\n├─ Repeated reference?    → stratum_card (T1/T2 card — 10-100x reduction)\n├─ Need exact lines to EDIT? → read_file (the ONLY acceptable use)\n└─ "I want to read the whole file" → ⛔ STOP. Use file_summary or compact instead.\n```\n\n### Decision Tree — Need Structural Relationships?\n\nWhen vector search and file reads don\'t answer the question (e.g. "who imports this?",\n"what does this depend on?", "how are these files connected?"), use `graph`:\n\n```\nNeed to understand relationships between code?\n├─ Who imports / calls this?     → graph({action:\'find_nodes\', name_pattern}) → graph({action:\'neighbors\', node_id, direction:\'incoming\'})\n├─ What does this depend on?     → graph({action:\'neighbors\', node_id, direction:\'outgoing\'})\n├─ Full context for a symbol?    → graph({action:\'symbol360\', name})\n├─ Related files within N hops?  → graph({action:\'traverse\', node_id, max_depth:2})\n├─ Layer/module isolation check? → graph({action:\'depth_traverse\', node_id, max_depth:3})\n└─ Graph size/health?            → graph({action:\'stats\'})\n```\n\n**Use this BEFORE** reaching for `analyze({ aspect: "dependencies", ... })` (slower, less precise) or manually\ntracing via `symbol` + `trace` chains. The graph is auto-populated during indexing.\n\n### What AI Kit Tools Return (AST-Enhanced)\n\nThese tools use Tree-sitter WASM to analyze source code at the AST level, providing structured data that raw file reads cannot:\n\n| Tool | Rich Output |\n|------|-------------|\n| `file_summary` | Imports classified as **external vs internal** (`isExternal` flag). **Call edges** between functions (e.g., `handleRequest() → validateInput() @ line 42`). `exported` flag on interfaces and types. Import count breakdown. |\n| `symbol` | References include **scope** — which function/class/method contains each usage (e.g., `referenced in processOrder() at auth-service.ts:55`). |\n| `trace` | **Call-graph edges** discovered via AST syntax tree, not text matching. Supports forward (who does X call?) and backward (who calls X?) tracing. Scope context on each node. |\n| `measure` | **Cognitive complexity** — weights nesting depth (nested `if` inside `for` inside `try` scores higher). More useful than cyclomatic complexity for understanding code difficulty. |\n| `dead_symbols` | **AST export enumeration** — catches `export default`, barrel re-exports (`export { x } from`), `export =`, and `export type`. Regex fallback for non-AST-supported languages. |\n\n### Example: `file_summary` Output\n\n```\nsrc/auth-service.ts\nLanguage: typescript | Lines: 180 | Estimated tokens: ~1400\n\nImports (6): 3 external, 3 internal\n  - import { hash } from \'bcrypt\'          [external]\n  - import { UserRepo } from \'./user-repo\' [internal]\n\nFunctions (4):\n  - authenticate @ line 22 [exported]\n  - validateToken @ line 55 [exported]\n  - hashPassword @ line 90\n  - generateJwt @ line 110\n\nCall edges (12 intra-file):\n  - authenticate() → hashPassword() @ line 35\n  - authenticate() → generateJwt() @ line 42\n  - validateToken() → UserRepo.findById() @ line 68\n\nInterfaces (2):\n  - AuthResult @ line 8 [exported]\n  - TokenPayload @ line 14\n```\n\nCompare: `read_file` would cost ~1400 tokens for raw text. `file_summary` gives structured data in ~120 tokens — **12x reduction** with richer information.\n\n## 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", path })` | Relative path within `.ai/curated/` |\n| Update | `knowledge({ action: "update", path, content })` | Relative path within `.ai/curated/` |\n| Remove | `knowledge({ action: "forget", path })` | Relative path within `.ai/curated/` |\n| History | `knowledge({ action: "history", path })` | Entry version history |\n| Diff | `knowledge({ action: "diff", path, from_sha?, to_sha? })` | Compare entry versions |\n| Recover | `knowledge({ action: "recover", path })` | Restore a withdrawn entry |\n| Orphaned | `knowledge({ action: "orphaned" })` | Find orphaned knowledge entries |\n| Withdraw | `knowledge({ action: "withdraw", scope: "flow:<run-id>", profile: "<role>", budget: 4000 })` | Flow-scoped context retrieval |\n| Flush | `knowledge({ action: "flush", scope: "flow:<run-id>" })` | Clean up flow context |\n\n### Lessons (structured insights with confidence)\n\n| Create | `knowledge({ action: "lesson", sub_action: "create", title, content, category })` | Create a scored lesson entry |\n| Confirm | `knowledge({ action: "lesson", sub_action: "confirm", path })` | Increase confidence when a lesson is validated |\n| Contradict | `knowledge({ action: "lesson", sub_action: "contradict", path })` | Decrease confidence when a lesson is invalidated |\n| List | `knowledge({ action: "lesson", sub_action: "list-lessons" })` | Browse lessons by confidence |\n\n**Session checkpoint** (end of session): `knowledge({ action: "remember", title: "Session checkpoint: <topic>", content: "Done/Decisions/Next/Blockers", category: "session" })`\n\n## Memory Lifecycle (Automatic)\n\nAI Kit manages memory health automatically in the background:\n\n- **Retention scoring** — Ebbinghaus forgetting curve. Frequently accessed entries stay fresh; unused entries decay and may be flagged for review.\n- **Tier consolidation** — 4 tiers: Working → Episodic → Semantic → Procedural. Entries promote automatically based on stability and access frequency.\n- **Auto-supersession** — On `remember`, the system detects similar existing entries (Jaccard similarity > 0.6) and may suggest superseding them.\n- **Observation capture** — Tool results are automatically captured as knowledge observations (rate-limited, 50/session max).\n- **Procedural extraction** — Repeated tool sequences are detected and stored as reusable procedures.\n\nThese systems run transparently — you do NOT need to invoke them manually. They improve memory quality over time.\n\n## Inter-Agent Signaling\n\nFor multi-agent workflows, use the `signal` tool to coordinate:\n\n| Post | `signal({ action: "post", workspace: "<ws>", key: "status", value: "done", agent: "<name>" })` |\n| Get | `signal({ action: "get", workspace: "<ws>", key: "status" })` |\n| Lease | `signal({ action: "lease", workspace: "<ws>", resource: "src/auth.ts", agent: "Implementer" })` |\n| Unlease | `signal({ action: "unlease", workspace: "<ws>", resource: "src/auth.ts" })` |\n| List leases | `signal({ action: "leases", workspace: "<ws>" })` |\n\nUse signals to:\n- Communicate completion status between parallel agents\n- Prevent write conflicts with file-level leases\n- Share discoveries across agent boundaries\n\n## CLI Quick Reference\n\n```bash\naikit init              # Scaffold AI Kit in current directory\naikit init --force      # Overwrite all scaffold/skill files\naikit init --guide      # JSON report of stale files for LLM-driven updates\naikit serve             # Start MCP server (stdio or HTTP)\naikit search <q>    # Hybrid search\naikit find <q>      # Federated search\naikit symbol <name> # Resolve symbol\naikit scope-map <t> # Task reading plan\naikit compact <q>   # Context compression (--path file or stdin)\naikit check         # Typecheck + lint (--detail efficient|normal|full)\naikit test          # Run tests\naikit rename <old> <new> <path>  # Rename symbol\naikit lane create <name> --files f1,f2  # Create lane\naikit lane diff <name>  # View lane changes\naikit lane merge <name> # Merge lane back\naikit status        # Index stats\naikit reindex       # Rebuild index\n```\n\n## Configuration\n\n`aikit.config.json` in project root:\n```json\n{\n  "sources": [{ "path": ".", "excludePatterns": ["**/node_modules/**", "**/dist/**", "**/build/**", "**/.git/**", "**/.aikit-data/**", "**/coverage/**"] }],\n  "indexing": { "chunkSize": 1500, "chunkOverlap": 200, "minChunkSize": 100 },\n  "embedding": { "model": "mixedbread-ai/mxbai-embed-large-v1", "dimensions": 1024 },\n  "store": { "backend": "sqlite-vec", "path": ".aikit-data" },\n  "curated": { "path": ".ai/curated" }\n}\n```\n\n## Tool Profiles\n\nTool profiles control which subset of the 61 tools are active. Profiles reduce token overhead by exposing only relevant tools for a given task.\n\n### Built-in Profiles\n\n| Profile | Description | Use When |\n|---------|-------------|----------|\n| `full` | All tools enabled (default) | General development, orchestration |\n| `safe` | Read-only tools — no file/state modifications | Code review, analysis, research |\n| `research` | Search, analysis, knowledge, web access | Investigation, documentation |\n| `minimal` | Essential tools only — search, check, test | Simple tasks, low-token budgets |\n| `discovery` | Full toolset + meta-tools for guided exploration | New users, onboarding, tool learning |\n\n### Activating a Profile\n\nSet `toolProfile` in `aikit.config.json`:\n\n```json\n{\n  "toolProfile": "research"\n}\n```\n\nBase tools (`status`, `config`, `guide`, `health`) are **always available** regardless of profile.\n\n## Development (Self-Dogfooding)\n\nWhen developing @vpxa/aikit itself: always `pnpm build` before using CLI/server (runs from `dist/`), and always `reindex` after structural code changes.\n\n---\n\n## Flows\n\nFlows are structured multi-step workflows that guide agents through complex tasks. They are the **primary workflow system** — use them instead of ad-hoc planning when a matching flow exists.\n\n### Flow Tools\n\n| Tool | Purpose |\n|------|---------|\n| `flow` | Check if a flow is active + current step + phase (before/flow/after) + isEpilogue |\n\nDifferent `action` values handle listing, starting, reading steps, advancing, resets, run inspection, and add/update/remove flow management.\n\n### Flow Selection\n\n| Task Type | Flow | Why |\n|-----------|------|-----|\n| Bug fix, config change, small refactor | `aikit:basic` | Known scope, low risk |\n| New feature in existing module | `aikit:basic` | Clear boundaries |\n| New system/service/module | `aikit:advanced` | Needs spec + planning |\n| Cross-service changes | `aikit:advanced` | Multiple boundaries |\n| Architectural change | `aikit:advanced` | High impact |\n| Unclear scope or exploratory | No flow | Use agent\'s native workflow |\n\n### Flow Lifecycle\n\n1. **Start**: `flow({ action: \'list\' })` → choose flow → `flow({ action: \'start\', name: "<name>", topic: "<task>" })`\n2. **Each step**: `flow({ action: \'read\', step: "<name>" })` → follow step instructions → complete work\n3. **Advance**: `flow({ action: \'step\', advance: \'next\' })` → repeat from step 2\n4. **Epilogue**: After last flow step, mandatory epilogue steps run (e.g., `_docs-sync` updates `docs/`)\n5. **Resume**: `flow({ action: \'status\' })` → if active, `flow({ action: \'read\' })` for current step → continue\n6. **Reset**: `flow({ action: \'reset\' })` if you need to start over\n\n---\n\n## Reference Documentation\n\nFor detailed patterns on specific topics, load these reference files:\n\n| Topic | File | When to load |\n|-------|------|-------------|\n| Multi-task orchestration | `references/coordination.md` | Queue, DAG, lanes, worksets, stash, checkpoints |\n| Quality gates (FORGE) | `references/forge-protocol.md` | Complex tasks, evidence maps, tier classification |\n| Search & relationships | `references/search-patterns.md` | Finding code, tracing data flow, graph traversal |\n'},{file:`references/coordination.md`,content:`# Coordination & Multi-Task Orchestration
+var e=[{file:`SKILL.md`,content:`---
+name: aikit
+description: "Use the @vpxa/aikit AI Kit MCP server for codebase search, context compression, validation, and persistent memory. Load at session start or before using aikit_* tools. This skill teaches tool judgment: minimize raw reads, choose the smallest useful retrieval path, and persist decisions that matter."
+metadata:
+  category: cross-cutting
+  domain: general
+  applicability: always
+  inputs: [codebase]
+  outputs: [search-results, analysis, knowledge]
+  relatedSkills: [session-handoff, present]
+---
 
-Patterns for managing multiple tasks, parallel exploration, and session state.
+# @vpxa/aikit — AI Kit
 
-## Queue (Task Management)
+Local-first AI developer toolkit for search, analysis, compression, validation, memory, flows, and coordination.
 
-| Action | Purpose | Example |
-|--------|---------|---------|
-| \`create\` | New queue | \`queue({ action: "create", name: "tasks" })\` |
-| \`push\` | Add item | \`queue({ action: "push", name: "tasks", title: "Fix auth", data: { deps: [] } })\` |
-| \`next\` | Get next ready item | \`queue({ action: "next", name: "tasks" })\` |
-| \`done\` | Mark complete | \`queue({ action: "done", name: "tasks", id: "<id>" })\` |
-| \`fail\` | Mark failed | \`queue({ action: "fail", name: "tasks", id: "<id>", error: "reason" })\` |
-| \`get\` | View queue state | \`queue({ action: "get", name: "tasks" })\` |
-| \`list\` | List all queues | \`queue({ action: "list" })\` |
-| \`clear\` | Clear all items | \`queue({ action: "clear", name: "tasks" })\` |
-| \`delete\` | Delete queue | \`queue({ action: "delete", name: "tasks" })\` |
+## When to Use
 
-### DAG Dependencies
+- You need to understand unfamiliar code without raw-reading large files.
+- You need structured search across code, docs, and prior decisions.
+- You need typecheck, test, or audit results in structured form.
+- You need memory across sessions, not just within one conversation.
+- You need to estimate blast radius before changing shared code.
+- You need guided flows, FORGE gates, or coordination primitives.
 
-Push items with \`data: { deps: ["item-id-1", "item-id-2"] }\`. The \`next\` action returns items whose dependencies are ALL marked done — automatic topological ordering.
+## Mindset
 
-\`\`\`
-queue({ action: "create", name: "build-pipeline" })
-queue({ action: "push", name: "build-pipeline", title: "Compile types", data: { deps: [] } })        // → id: "a"
-queue({ action: "push", name: "build-pipeline", title: "Bundle JS", data: { deps: ["a"] } })         // → id: "b"
-queue({ action: "push", name: "build-pipeline", title: "Run tests", data: { deps: ["a"] } })         // → id: "c"
-queue({ action: "push", name: "build-pipeline", title: "Deploy", data: { deps: ["b", "c"] } })       // → id: "d"
-queue({ action: "next", name: "build-pipeline" })  // Returns "Compile types" (no deps)
-queue({ action: "done", name: "build-pipeline", id: "a" })
-queue({ action: "next", name: "build-pipeline" })  // Returns "Bundle JS" or "Run tests" (deps satisfied)
-\`\`\`
+AI Kit tools are a compression layer. Their job is to prevent agents from wasting tokens on raw file reads and flat text search.
 
-## Lanes (Parallel Exploration)
+Every call should reduce context, not add to it.
 
-Isolated file copies for exploring alternatives without affecting the workspace:
+Think: what's the minimum I need to read to act? Then choose the tool that gives exactly that.
 
-| Action | Purpose |
-|--------|---------|
-| \`lane({ action: "create", name: "approach-a", files: ["src/auth.ts"] })\` | Copy files into lane |
-| \`lane({ action: "status", name: "approach-a" })\` | Check lane state |
-| \`lane({ action: "diff", name: "approach-a" })\` | See changes vs original |
-| \`lane({ action: "merge", name: "approach-a" })\` | Apply changes back |
-| \`lane({ action: "discard", name: "approach-a" })\` | Throw away exploration |
-| \`lane({ action: "list" })\` | See all active lanes |
-
-**Use case:** Create lanes for two approaches, explore both, diff to compare, merge the winner.
-
-## Worksets (Named File Groups)
-
-Persist named sets of files for repeated reference:
-
-\`\`\`
-workset({ action: "save", name: "auth-files", files: ["src/auth.ts", "src/middleware.ts"], description: "Auth module" })
-workset({ action: "get", name: "auth-files" })     // Returns file list
-workset({ action: "add", name: "auth-files", files: ["src/session.ts"] })
-workset({ action: "remove", name: "auth-files", files: ["src/middleware.ts"] })
-workset({ action: "list" })                        // All worksets
-workset({ action: "delete", name: "auth-files" })
-\`\`\`
-
-## Stash (Intermediate Values)
-
-Key-value store for results between tool calls:
-
-\`\`\`
-stash({ action: "set", key: "analysis-result", value: "{ findings: [...] }" })
-stash({ action: "get", key: "analysis-result" })
-stash({ action: "list" })
-stash({ action: "delete", key: "analysis-result" })
-stash({ action: "clear" })
-\`\`\`
-
-## Checkpoints (Session Milestones)
-
-Save and restore session state:
-
-\`\`\`
-checkpoint({ action: "save", label: "before-refactor", notes: "Pre-refactor state" })
-checkpoint({ action: "list" })
-checkpoint({ action: "latest" })
-checkpoint({ action: "load", label: "before-refactor" })
-\`\`\`
-`},{file:`references/forge-protocol.md`,content:`# FORGE Protocol — Quality Gates for Complex Tasks
-
-Fact-Oriented Reasoning with Graduated Evidence. Use for any Standard+ tier task.
-
-## Tier Classification
-
-| Tier | Criteria | Ceremony |
-|------|----------|----------|
-| **Floor** | Single file, blast_radius ≤ 2, no schema change, no unknowns | Skip Break phase, no evidence map needed |
-| **Standard** | Multi-file or non-trivial, default for most tasks | Full 4-phase flow |
-| **Critical** | blast_radius > 5, cross-service, schema change, security code | Comprehensive evidence, extra review |
-
-When uncertain, round up. Use \`forge_classify({ task, files, root_path })\` for automatic classification.
-
-## 4-Phase Flow
-
-### Phase 1 — Ground
-Read files, classify tier, build Typed Unknown Queue, load constraints.
-
-\`\`\`
-forge_ground({ task: "Add user API", files: ["src/routes/user.ts", "src/models/user.ts"], root_path: "." })
-\`\`\`
-
-This single call chains: classify → scope_map → unknowns → constraints → file_summaries → evidence_map creation.
-
-### Phase 2 — Build
-Generate code with evidence anchoring. Route typed unknowns mid-generation.
-- Every claim must be backed by a tool receipt (search result, file line, test output)
-- Add evidence as you go: \`evidence_map({ action: "add", task_id, claim, status: "V", receipt })\`
-
-### Phase 3 — Break (Standard+ only, skip for Floor)
-One adversarial round:
-- Check error paths and edge cases
-- Verify blast radius hasn't expanded
-- Check convention violations
-- Look for missing validation at system boundaries
-
-### Phase 4 — Gate
-Binary evaluation: \`evidence_map({ action: "gate", task_id })\`
-
-| Result | Meaning | Action |
-|--------|---------|--------|
-| **YIELD** | All evidence verified | Proceed — task complete |
-| **HOLD** | Fixable issues | Fix + re-gate (max 3 iterations) |
-| **HARD_BLOCK** | Contract-type unknowns unresolved | Escalate to user |
-
-## Evidence Map
-
-### Creating
-\`\`\`
-evidence_map({ action: "create", task_id: "add-user-api", tier: "standard" })
-\`\`\`
-
-### Adding Claims
-\`\`\`
-evidence_map({
-  action: "add",
-  task_id: "add-user-api",
-  claim: "User schema matches existing patterns",
-  status: "V",           // V=Verified, A=Assumed, U=Unresolved
-  receipt: "search → models/user.ts#L12",
-  safety_gate: "provenance"   // Optional: provenance | commitment | coverage
-})
-\`\`\`
-
-### Status Values
-| Status | Meaning | Requirements |
-|--------|---------|-------------|
-| **V** (Verified) | Proven by tool output | Must have non-empty receipt |
-| **A** (Assumed) | Reasonable assumption | Must have reasoning in receipt |
-| **U** (Unresolved) | Unknown, needs investigation | Blocks gate if on critical path |
-
-### Safety Gates (Standard+ only)
-Three mandatory checks evaluated during \`gate\`:
-
-| Gate | Rule | Failure |
-|------|------|---------|
-| **Provenance** | Every V claim has a non-empty receipt | HOLD |
-| **Commitment** | Every commitment-tagged entry is V | HOLD |
-| **Coverage** | No coverage-tagged entry is U | HOLD |
-
-### Gating
-\`\`\`
-evidence_map({ action: "gate", task_id: "add-user-api" })
-// Returns: { verdict: "YIELD" | "HOLD" | "HARD_BLOCK", ... }
-\`\`\`
-
-## Score-Driven Iteration
-
-For quality-sensitive tasks:
-
-1. Execute task (Build phase)
-2. Score: \`check({})\` + \`test_run({})\` + \`evidence_map({ action: "gate" })\`
-3. If gate ≠ YIELD → fix issues → re-score (max 3 iterations)
-4. Track progress: \`stash({ action: "set", key: "iteration-N", value: "{ score, issues }" })\`
-
-## Quick Reference
-
-\`\`\`
-// Classify
-forge_classify({ task: "...", files: ["..."], root_path: "." })
-
-// Full Ground phase (single call)
-forge_ground({ task: "...", files: ["..."], root_path: "." })
-
-// Evidence lifecycle
-evidence_map({ action: "create", task_id: "my-task", tier: "standard" })
-evidence_map({ action: "add", task_id: "my-task", claim: "...", status: "V", receipt: "..." })
-evidence_map({ action: "gate", task_id: "my-task" })
-\`\`\`
-`},{file:`references/search-patterns.md`,content:`# Search Patterns & Code Discovery
-
-How to find code, understand relationships, and trace data flow.
-
-## Decision Tree: Which Tool?
-
-\`\`\`
-What do you need?
-├─ Understand a file's structure?     → file_summary({ path })
-├─ Find specific content in a file?   → compact({ path, query })
-├─ Find code across the codebase?     → search({ query })
-├─ Find a specific symbol?            → symbol({ name })
-├─ Trace data flow?                   → trace({ start, direction })
-├─ Understand module relationships?   → graph({ action: "find_nodes" }) → graph({ action: "neighbors" })
-├─ Plan what to read for a task?      → scope_map({ task })
-├─ Multi-strategy precision search?   → find({ query, pattern, glob })
-└─ Compress multiple files?           → digest({ sources, query })
-\`\`\`
-
-## Search Modes
-
-| Mode | When | Example |
-|------|------|---------|
-| \`hybrid\` (default) | General queries, combines vector + full-text | \`search({ query: "error handling" })\` |
-| \`semantic\` | Conceptual similarity, find related patterns | \`search({ query: "retry with backoff", search_mode: "semantic" })\` |
-| \`keyword\` | Exact identifiers, class/function names | \`search({ query: "CircuitBreaker", search_mode: "keyword" })\` |
-
-## Search Filters
-
-| Filter | Values | Purpose |
-|--------|--------|---------|
-| \`content_type\` | code-typescript, code-javascript, documentation, config-json, test-code, etc. | Restrict to file types |
-| \`origin\` | indexed, curated, produced | Source of knowledge |
-| \`source_type\` | source, documentation, test, config, generated | Coarse file category |
-| \`tags\` | string[] | Match any tag |
-| \`category\` | conventions, decisions, patterns, context, session | Curated knowledge category |
-| \`dedup\` | chunk (default), file | Collapse results from same file |
-
-## Symbol Lookup
-
-Find where a symbol is defined, imported, and used:
-
-\`\`\`
-symbol({ name: "AuthService" })
-// Returns: definition location, all imports, all references with context
-\`\`\`
-
-## Data Flow Tracing
-
-Follow data forward (who uses this?) or backward (where does this come from?):
-
-\`\`\`
-trace({ start: "handleRequest", direction: "forward" })   // What does handleRequest call?
-trace({ start: "src/db.ts:42", direction: "backward" })   // What calls this line?
-trace({ start: "validateInput", direction: "both" })       // Full call chain
-\`\`\`
-
-## Knowledge Graph
-
-The graph is auto-populated with modules, symbols, and import relationships. Two-step pattern:
-
-\`\`\`
-// Step 1: Find nodes
-graph({ action: "find_nodes", name_pattern: "auth" })
-// Returns: nodes with IDs
-
-// Step 2: Explore connections
-graph({ action: "neighbors", node_id: "<id-from-step-1>", direction: "incoming" })
-// Returns: what imports/depends on this module
-\`\`\`
-
-### Graph Actions
-
-| Action | Purpose |
-|--------|---------|
-| \`find_nodes\` | Search nodes by name pattern or type |
-| \`neighbors\` | Direct connections (incoming/outgoing/both) |
-| \`traverse\` | Multi-hop traversal (max_depth: 1-5) |
-| \`symbol360\` | Full context for a named symbol |
-| \`stats\` | Graph size and health |
-| \`cohesion\` | Module cohesion score |
-
-## Scope Map (Reading Plans)
-
-Generate a task-scoped reading plan:
-
-\`\`\`
-scope_map({ task: "Add rate limiting to API routes" })
-// Returns: prioritized file list with relevance scores, token estimates, reading order
-\`\`\`
-
-## Find (Multi-Strategy)
-
-Combines vector search, full-text search, glob matching, and regex in one call:
-
-\`\`\`
-find({ query: "rate limit", glob: "src/middleware/**", limit: 10 })
-find({ pattern: "new RateLimiter\\(", mode: "search" })
-find({ query: "handleRequest", mode: "examples" })   // Find real usage examples
-\`\`\`
-
-## Context Compression
-
-| Tool | Purpose | Token Reduction |
-|------|---------|----------------|
-| \`file_summary\` | Structure only (imports, exports, functions) | ~10x |
-| \`compact\` | Query-relevant content from a file | 5-20x |
-| \`digest\` | Compress multiple sources with budget | configurable |
-| \`stratum_card\` | Reusable T1/T2 context cards | 10-100x |
-
-## Example Workflows
-
-### Bug Investigation
-\`\`\`
-symbol({ name: "failingFunction" })          // Find definition
-→ trace({ start: "failingFunction", direction: "backward" })  // Who calls it?
-→ compact({ path: "src/caller.ts", query: "error handling around failingFunction" })
-→ blast_radius({ path: ".", files: ["src/caller.ts"] })  // What else is affected?
-\`\`\`
-
-### Dependency Analysis
-\`\`\`
-graph({ action: "find_nodes", name_pattern: "auth-module" })
-→ graph({ action: "neighbors", node_id: "<id>", direction: "incoming" })  // Who depends on auth?
-→ graph({ action: "traverse", node_id: "<id>", max_depth: 2 })  // Deep dependency tree
-\`\`\`
-
-### Codebase Onboarding
-\`\`\`
-scope_map({ task: "Understand the authentication system" })
-→ [read each file with file_summary or compact based on relevance]
-→ graph({ action: "find_nodes", name_pattern: "auth" })
-→ graph({ action: "neighbors", node_id: "<id>" })
-\`\`\`
+Common mistake: using \`read_file\` out of habit. That is the last resort, not the first.
+
+Default progression: \`file_summary\` → \`compact\` → \`digest\` → \`read_file\` only for exact edit lines.
+
+If you are unsure which tool fits, ask AI Kit for the live catalog with \`list_tools\`, then narrow with \`search_tools\` or \`describe_tool\`.
+
+## Operating Model
+
+1. Orient with compressed retrieval, not raw reads.
+2. Validate with structured tools, not noisy terminal output.
+3. Persist decisions that future sessions must reuse.
+4. Reuse previous context before searching again.
+5. Use reference docs only when the main routing logic is not enough.
+
+## Tool Selection (Decision Tree)
+
+~~~text
+Need to understand code?
+├─ Just structure?     → file_summary (exports, imports — ~50 tokens)
+├─ Specific section?   → compact({ path, query }) — 5-20x token reduction
+├─ Multiple files?     → digest (multi-source compression)
+├─ Need relationships? → graph (find_nodes → neighbors)
+└─ Need exact lines?   → read_file (ONLY for editing)
+
+Need to find something?
+├─ Code/symbols?       → search (hybrid — default)
+├─ Symbol definition?  → symbol (definition + refs + call context)
+├─ Usage examples?     → find({ mode: 'examples', query })
+├─ Cross-file flow?    → trace (forward/backward/both)
+└─ Change impact?      → blast_radius
+
+Need to validate?
+├─ Type errors?        → check (typecheck + lint combined)
+├─ Tests pass?         → test_run (structured output)
+└─ Full audit?         → audit (structure + deps + health)
+
+Need to remember?
+├─ Store decision?     → knowledge({ action: 'remember' })
+├─ Find past decision? → search({ query, origin: 'curated' })
+├─ Session state?      → stash (ephemeral) or checkpoint (persistent)
+└─ Cross-session?      → knowledge (curated memory)
+
+Need tool discovery?
+├─ Full live catalog?  → list_tools
+├─ Know capability, not name? → search_tools
+└─ Need details first? → describe_tool or guide
+~~~
+
+## Session Protocol
+
+### Why This Matters
+
+Without session discipline, agents repeat work, miss context, and make decisions that contradict earlier choices. These steps exist to keep work cumulative.
+
+### Start (do first, every session)
+
+1. \`status({})\` — Why: confirms index is built, tools are ready, and onboard state is known. Skipping this causes tool-avoidance and blind exploration.
+2. \`search({ query: "SESSION CHECKPOINT", origin: "curated" })\` — Why: pulls prior session context so you do not re-solve finished work.
+3. \`scope_map({ task })\` — Why: creates a reading plan before exploration, which prevents broad wandering.
+4. If a flow may already exist, run \`flow({ action: 'status' })\` — Why: flow state is part of task state. Resuming the wrong way duplicates work.
+5. If onboard is missing, run \`onboard({ path: "." })\` — Why: AI Kit is strongest after structure, patterns, and symbols are pre-analyzed.
+
+### During (do continuously)
+
+- \`stash({ action: "set", key, value })\` for intermediate results — Why: chat context compresses; stash survives it.
+- \`knowledge({ action: "remember" })\` for decisions and conventions — Why: decisions must outlive the current conversation.
+- \`checkpoint({ action: "save" })\` before risky multi-step changes — Why: it gives you a known milestone for recovery.
+- \`blast_radius\` before shared-symbol edits — Why: public changes are rarely local.
+- \`check\` and \`test_run\` after changes — Why: verification is cheaper than debugging assumptions later.
+
+### End (do always)
+
+- \`session_digest({ persist: true })\` — Why: captures tool trajectory and supports crash recovery.
+- \`knowledge({ action: "remember", title: "Session checkpoint: <topic>" })\` — Why: the next session's first search is looking for exactly this.
+- \`reindex\` after structural code changes — Why: stale index data makes every later search worse.
+
+## Search Strategy
+
+1. Start with \`search\` in hybrid mode unless you know you need exact identifiers.
+2. Switch to \`symbol\` when the question is about one named thing.
+3. Switch to \`trace\` when the question is flow, not location.
+4. Switch to \`graph\` when the question is relationships between modules or importers.
+5. Use \`compact\`, not raw file reads, once you know the file and the question.
+
+## Judgment Patterns
+
+### Understanding a New Area
+
+~~~text
+search → scope_map → file_summary/compact → graph or trace → stash
+~~~
+
+Use this when you need a fast mental model. Do not start with \`read_file\`.
+
+### Investigating a Bug
+
+~~~text
+search → symbol → trace → compact → check/test_run → knowledge remember
+~~~
+
+Use this when the failure path matters more than file ownership.
+
+### Refactoring Shared Code
+
+~~~text
+blast_radius → checkpoint → compact/file_summary → rename or codemod → check → test_run
+~~~
+
+Use this when contract breakage is more dangerous than local implementation detail.
+
+### Picking the Right Tool
+
+~~~text
+list_tools → search_tools → describe_tool → execute
+~~~
+
+Use this instead of baking a static catalog into the skill. Tool metadata is live at runtime.
+
+## Memory Discipline
+
+- Use \`stash\` for temporary state you may need again in the same task.
+- Use \`checkpoint\` for recoverable milestones in longer sessions.
+- Use \`knowledge\` for decisions, conventions, non-obvious findings, and reusable lessons.
+- Search curated memory before inventing a new pattern.
+- Keep memory high-signal. Store what must survive, not everything you observed.
+
+## Flows
+
+Flows are the preferred path for guided multi-step work.
+
+- Use \`flow({ action: 'status' })\` first to detect active work.
+- Use \`flow({ action: 'list' })\` when the task looks repeatable or cross-cutting.
+- Use \`flow({ action: 'read' })\` before acting inside a started flow.
+- Use native agent workflow only when no flow matches the problem.
+
+## Reference Docs
+
+Load these only when the main skill is not enough:
+
+- \`references/coordination.md\` — queue, lanes, stash, checkpoints, signaling
+- \`references/forge-protocol.md\` — tiering, evidence, gates
+- \`references/search-patterns.md\` — search, trace, graph, compression patterns
+
+## NEVER
+
+- NEVER use \`read_file\` to "understand" a file. \`file_summary\` gives structure in ~50 tokens instead of hundreds.
+- NEVER use \`grep_search\` or \`semantic_search\` when \`search\` is available. \`search\` combines both strategies and ranks them.
+- NEVER run tsc, lint, or tests through the terminal when \`check()\` and \`test_run()\` exist. Structured output beats terminal noise.
+- NEVER skip \`status()\` at session start. If index state is unknown, every later choice is lower quality.
+- NEVER call \`knowledge({ action: 'remember' })\` for trivial facts. Memory is for decisions, conventions, lessons, and durable findings.
+- NEVER search the same thing twice without checking \`stash\` or prior results.
+- NEVER use a long flat tool catalog as your primary routing aid. Use runtime discovery when you need exact tool metadata.
+- NEVER jump to \`analyze\` for simple local questions. Start with cheaper retrieval and escalate only if needed.
+- NEVER leave structural changes unindexed. Run \`reindex\` when symbols, files, or imports change.
+
+## Complementary Skills
+
+- Load \`typescript\` before TypeScript-heavy implementation work.
+- Load \`react\` before React component or hooks work.
+- Load \`session-handoff\` when context is filling up or a pause is imminent.
+- Load \`repo-access\` when repo auth fails.
+
+## Practical Defaults
+
+- Default search mode: \`search\` with hybrid ranking.
+- Default read path: \`file_summary\` then \`compact\`.
+- Default validation pair: \`check\` then \`test_run\`.
+- Default persistence: \`knowledge remember\` for durable findings, \`stash\` for everything temporary.
+
+## Self-Dogfooding
+
+When developing AI Kit itself, rebuild generated output before trusting runtime behavior, and reindex after structural changes so the toolkit can see its own new shape.
+`},{file:`references/coordination.md`,content:`# Coordination
+
+Use coordination tools when work is parallel, long-running, or easy to repeat incorrectly.
+
+## Pick the Right Primitive
+
+- \`queue\` for ordered task execution or DAG-style dependencies.
+- \`lane\` for isolated exploration of alternative approaches.
+- \`workset\` for named file groups you will revisit.
+- \`stash\` for temporary intermediate results between tool calls.
+- \`checkpoint\` for recoverable milestones before risky changes.
+- \`signal\` for cross-agent status or file-level leases.
+
+## Minimal Patterns
+
+~~~text
+Multi-step task: queue → next → done/fail
+Try two approaches: lane create A/B → diff → merge winner
+Need same files repeatedly: workset save → get
+Need temporary findings later: stash set → get
+About to make risky change: checkpoint save → edit → load only if recovery needed
+Parallel agents: signal post/get or lease/unlease
+~~~
+
+## Rule of Thumb
+
+If the problem is about sequence, use \`queue\`. If it is about comparison, use \`lane\`. If it is about memory within one effort, use \`stash\` or \`checkpoint\`.
+`},{file:`references/forge-protocol.md`,content:`# FORGE Protocol
+
+Use FORGE when the task is large enough that being "probably right" is not enough.
+
+## Tiering
+
+- Floor: single-file, low-blast-radius, few unknowns.
+- Standard: multi-file or non-trivial. Default when unsure.
+- Critical: schema, security, cross-service, or high-blast-radius work.
+
+Start with \`forge_classify\` if tier is unknown. Use \`forge_ground\` when you want one call to classify, scope, load constraints, and seed evidence.
+
+## Flow
+
+~~~text
+Ground → Build → Break → Gate
+~~~
+
+- Ground: classify task, gather constraints, identify unknowns.
+- Build: implement with evidence-backed claims.
+- Break: challenge assumptions and edge cases.
+- Gate: evaluate evidence quality before declaring completion.
+
+## Core Tools
+
+- \`forge_classify\` to size ceremony.
+- \`forge_ground\` to bootstrap full context.
+- \`evidence_map\` to track verified, assumed, and unresolved claims.
+- \`blast_radius\`, \`check\`, and \`test_run\` to verify the implementation actually holds.
+
+## Rule of Thumb
+
+If the task crosses boundaries or would be expensive to get wrong, pay the FORGE cost up front.
+`},{file:`references/search-patterns.md`,content:`# Search Patterns
+
+Use the smallest search primitive that answers the real question.
+
+## Routing
+
+~~~text
+Need rough discovery?        → search
+Need one named thing?        → symbol
+Need real usage examples?    → find({ mode: 'examples' })
+Need call/data flow?         → trace
+Need import/module graph?    → graph
+Need file reading plan?      → scope_map
+Need one file section?       → compact
+Need many files compressed?  → digest
+~~~
+
+## Heuristics
+
+- Use \`search\` first when you know the topic but not the owner.
+- Use \`symbol\` when the question is definition, imports, or refs.
+- Use \`trace\` when you care about execution path.
+- Use \`graph\` when you care about who depends on what.
+- Use \`compact\` after you already know the file and the question.
+- Use \`file_summary\` before \`compact\` if you still need structure.
+
+## Compression Ladder
+
+~~~text
+file_summary → compact → digest → read_file only for edit lines
+~~~
+
+## Rule of Thumb
+
+If you are about to read raw code, ask whether the answer is really about structure, relevance, flow, or relationships. AI Kit has a smaller tool for each of those.
 `}];export{e as default};