@vpxa/aikit 0.1.125 → 0.1.127

package/TECH.md

@@ -1,1348 +0,0 @@
-# @vpxa/aikit
-
-Local-first AI developer toolkit and multi-agent operating system for LLM-powered software teams.
-
-## Why AI Kit?
-
-AI Kit is built around 17 specialized agents with clear roles, not one general-purpose agent improvising across research, planning, coding, debugging, review, and architecture at the same time. The Orchestrator conducts. The Planner researches and designs. The Implementer writes code. The Debugger diagnoses failures. Security audits risk. Four Researcher variants analyze hard decisions from different model perspectives. Dual code and architecture reviewers catch what one model alone will miss.
-
-That specialization is paired with parallel dispatch. The Orchestrator decomposes complex work into independent sub-tasks, runs read-only agents concurrently without artificial limits, and can run up to four file-modifying agents in parallel when their file sets do not overlap. The result is lower wall-clock time without turning the repo into a race condition.
-
-For non-trivial technical choices, AI Kit uses multi-model decision analysis. Researcher-Alpha, Beta, Gamma, and Delta run in parallel on different LLMs, then the Orchestrator synthesizes agreement, disagreement, trade-offs, and implementation risk into one recommendation. Important decisions do not depend on a single model's blind spots.
-
-Every code change also goes through FORGE. Tasks are classified by tier, critical claims are tracked in an evidence map, and completion is gated by provenance, commitment, and coverage checks. Floor, Standard, and Critical work do not get the same ceremony, but they do get explicit, deterministic quality control.
-
-AI Kit keeps that system fast by compressing code context 5-20x with `compact`, `digest`, and `stratum_card`. Agents get fresh, scoped context for the task in front of them instead of inheriting a bloated conversation transcript. Each sub-agent receives exactly the code context it needs to do one job well.
-
-## Features
-
-- **61 MCP tools** for AI agents to search, analyze, and manipulate codebases
-- **17 specialized agents** — Orchestrator, Planner, Implementer, Frontend, Refactor, Debugger, Security, Documenter, Explorer, 4 Researchers, 2 Code Reviewers, 2 Architect Reviewers — each with a focused role and optimal model
-- **Parallel agent dispatch** — independent sub-tasks run concurrently, up to 4 file-modifying agents in parallel on non-overlapping files
-- **Multi-model decisions** — 4 Researcher variants with different LLMs analyze every non-trivial technical choice in parallel, then synthesize consensus
-- **FORGE quality gates** — evidence-tracked code changes with tiered classification (Floor/Standard/Critical) and deterministic pass/fail gating
-- **49 CLI commands** for shell-based interaction
-- **Local-first** — ONNX embeddings, SQLite-vec vector store, no cloud dependencies
-- **Three interfaces**: MCP (for agent IDEs), CLI (for terminal agents), and programmatic API
-- **Tool profiles** — `full`, `safe`, `research`, `minimal`, `discovery` presets to control which tools are exposed
-- **Meta-tool discovery** — `list_tools`, `describe_tool`, `search_tools` for token-efficient tool exploration
-- **Pluggable flows** — `aikit:basic` and `aikit:advanced` built-in, plus custom team flows managed through unified `aikit_flow` actions
-- **Session digest** — auto-capture session activity for handoff between agents or sessions
-- **Middleware pipeline** — extensible plugin hooks for tool execution customization
-- **Pluggable memory** — adapter interface for curated knowledge storage backends
-
-## Agent Architecture
-
-| Agent | Role | Category |
-|-------|------|----------|
-| Orchestrator | Master conductor — decomposes tasks, dispatches agents, gates quality | Orchestration |
-| Planner | Autonomous research and TDD implementation planning | Orchestration |
-| Implementer | Code writing following TDD practices | Implementation |
-| Frontend | UI/UX specialist — React, styling, responsive design | Implementation |
-| Refactor | Code cleanup, structure improvement, maintainability | Implementation |
-| Debugger | Issue diagnosis, error tracing, root cause analysis | Diagnostics |
-| Security | Vulnerability analysis, OWASP compliance, security review | Diagnostics |
-| Explorer | Rapid codebase navigation and context gathering | Exploration |
-| Documenter | Comprehensive project documentation generation | Documentation |
-| Researcher-Alpha | Deep research — primary investigator | Research |
-| Researcher-Beta | Pragmatic analysis — trade-offs and edge cases | Research |
-| Researcher-Gamma | Broad pattern matching across domains | Research |
-| Researcher-Delta | Implementation feasibility and performance | Research |
-| Code-Reviewer-Alpha | Primary code review | Review |
-| Code-Reviewer-Beta | Code review from different LLM perspective | Review |
-| Architect-Reviewer-Alpha | Primary architecture review | Review |
-| Architect-Reviewer-Beta | Architecture review from different LLM perspective | Review |
-
-The Orchestrator never writes code itself; it delegates, reviews, and gates. Dual-perspective reviewers catch defects and design issues a single model can miss, while multi-model research reduces single-LLM blind spots before implementation begins. All of these agents are scaffolded by `aikit init` and can be customized per project.
-
-## What This Is
-
-This is an **MCP (Model Context Protocol) server** that gives AI agents:
-
-1. **Hybrid search** — combines semantic vector search with full-text keyword search (BM25) using Reciprocal Rank Fusion (RRF) for best results. Supports `hybrid` (default), `semantic`, and `keyword` modes.
-2. **Persistent curated memory** — agents can `remember`, `update`, `read`, `list`, and `forget` knowledge entries that survive across sessions
-3. **Codebase analysis** — structural analysis, dependency graphs with confidence scoring, symbol extraction, pattern detection, and Mermaid diagram generation. Analysis results are auto-persisted into the vector store for future search.
-4. **Knowledge production** — automated analysis pipelines that produce structured baselines for the agent to synthesize and store
-5. **Next-step workflow hints** — every tool response includes contextual `_Next:` suggestions guiding the agent to logical follow-up actions
-6. **Tree-sitter code chunking** — AST-based chunking for TS/JS/Python/Go/Rust/Java preserves function/class boundaries for higher-quality code search
-7. **Knowledge graph** — auto-populated SQLite graph of modules, symbols, and import relationships with traversal, neighbor queries, and change impact tracking
-8. **Graph auto-population** — during indexing, a lightweight regex extractor builds the knowledge graph automatically from TS/JS source files (functions, classes, interfaces, types, imports)
-9. **Optimized reindex** — full reindex skips redundant hash checks, batches graph writes (flush every 50 files), and skips per-file graph deletes when bulk-cleared
-10. **Tool profiles** — five built-in profiles (`full`, `safe`, `research`, `minimal`, `discovery`) that control which subset of 61 tools are exposed, reducing token overhead for focused tasks
-11. **Meta-tools** — `list_tools`, `describe_tool`, and `search_tools` for incremental tool discovery without loading full descriptions (~200 tokens vs ~3000)
-12. **Pluggable flow system** — built-in `basic` and `advanced` development flows plus custom flow support through unified `flow` actions (`list`, `start`, `step`, `status`, `read`, `runs`, `add`, `remove`, `update`, `reset`, `info`)
-13. **Session digest** — auto-capture session decisions, files touched, and checkpoint state for seamless agent handoffs
-14. **Middleware pipeline** — plugin hook system for extending tool execution with pre/post processing, logging, or custom validation
-15. **Pluggable memory providers** — adapter interface for curated knowledge storage, supporting filesystem (default) and custom backends
-
-The AI Kit auto-indexes configured source directories on startup, stores embeddings in a local SQLite-vec vector store, and exposes everything through 61 MCP tools, 49 CLI commands, and 2 resources.
-
----
-
-## Quick Start
-
-### User-Level Install (recommended for multi-project setups)
-
-```bash
-# Install once, works across all your projects
-npx @vpxa/aikit init --user
-
-# Then in any workspace, scaffold instructions only
-npx @vpxa/aikit init
-```
-
-### Workspace Install (per-project, self-contained)
-
-```bash
-# Full workspace initialization
-npx @vpxa/aikit init --workspace
-
-# Index and search
-npx @vpxa/aikit reindex
-npx @vpxa/aikit search "authentication middleware"
-npx @vpxa/aikit serve
-```
-
-### After upgrading
-
-```bash
-npx @vpxa/aikit init --force    # Overwrite all scaffold/skill files
-npx @vpxa/aikit init --guide    # Check which files are outdated
-```
-
-> **Note:** In workspace mode, once `@vpxa/aikit` is installed locally, you can use the short `aikit` command (e.g. `aikit search`, `aikit serve`) since the local binary takes precedence.
-
-## User-Level vs Workspace Mode
-
-AI Kit supports two installation modes:
-
-| | User-Level | Workspace |
-|---|---|---|
-| **Install** | `aikit init --user` (once) | `aikit init --workspace` (per project) |
-| **MCP config** | User-level (IDE-wide) | `.vscode/mcp.json` (workspace) |
-| **Data store** | `~/.aikit-data/<partition>/` | `.aikit-data/store/` (in project) |
-| **Skills** | `~/.aikit-data/skills/` | `.github/skills/` (in project) |
-| **Config** | Auto defaults per workspace | `aikit.config.json` (in project) |
-
-### How it works
-
-- **`aikit init --user`** — Installs the MCP server in your user-level IDE config (VS Code, Cursor, Claude Code, Windsurf). Creates `~/.aikit-data/` for data. Skills are shared. The server auto-indexes each workspace it's opened in.
-- **`aikit init`** (smart default) — If user-level is installed, scaffolds workspace-only files (AGENTS.md, instructions, curated directories). If not, does a full workspace install.
-- **`aikit init --workspace`** — Traditional per-project install with full local config and data store.
-
-### Checking your mode
-
-```bash
-aikit status
-# Mode:     user (workspace scaffolded)
-# Data:     ~/.aikit-data/my-project-a1b2c3d4/
-# Registry: 3 workspace(s) enrolled
-```
-
-### Cross-workspace search (user-level mode only)
-
-```
-search({ query: "error handling", workspaces: ["*"] })        # All workspaces
-search({ query: "CircuitBreaker", workspaces: ["other-project"] })  # Specific workspace
-symbol({ name: "MyService", workspaces: ["*"] })                    # Find symbol across all
-find({ query: "retry logic", workspaces: ["backend", "shared"] })   # Multiple workspaces
-```
-
-Tools supporting `workspaces` param: `search`, `find`, `symbol`.
-
-## Tools by Category
-
-### Search & Discovery
-| Tool | CLI | Description |
-|------|-----|-------------|
-| `aikit_search` | `aikit search` | Hybrid vector + keyword search |
-| `aikit_find` | `aikit find` | Federated search (vector, FTS, glob, regex). Use `mode: 'examples'` to find usage examples. |
-| `aikit_symbol` | `aikit symbol` | Resolve symbol definition, imports, references |
-| `aikit_lookup` | `aikit lookup` | Look up indexed chunks by file path |
-| `aikit_trace` | `aikit trace` | Forward/backward flow tracing |
-| `aikit_scope_map` | `aikit scope-map` | Generate task-scoped reading plan |
-| `aikit_dead_symbols` | `aikit dead-symbols` | Find unused exported symbols (source vs docs) |
-| `aikit_file_summary` | `aikit summarize` | Structural file overview |
-
-### Code Analysis
-| Tool | CLI | Description |
-|------|-----|-------------|
-| `aikit_analyze` | `aikit analyze <aspect>` | Unified analysis entry point for `structure`, `dependencies`, `symbols`, `patterns`, `entry_points`, and `diagram` |
-| `aikit_blast_radius` | `aikit analyze blast-radius` | Change impact analysis |
-
-### Context Management
-| Tool | CLI | Description |
-|------|-----|-------------|
-| `aikit_compact` | `aikit compact` | Compress text/file to relevant sections (accepts `path`) |
-| `aikit_workset` | `aikit workset` | Named file set management |
-| `aikit_stash` | `aikit stash` | Named key-value store |
-| `aikit_checkpoint` | `aikit checkpoint` | Session checkpoint save/restore |
-| `aikit_parse_output` | `aikit parse-output` | Parse build tool output (tsc, vitest, biome) |
-| `aikit_session_digest` | `aikit session-digest` | Auto-capture session activity, decisions, and state for handoff |
-
-### FORGE & Context Compression
-| Tool | CLI | Description |
-|------|-----|-------------|
-| `aikit_forge_ground` | — | Complete FORGE Ground phase in one call (chains classify→scope→summarize→constraints→evidence) |
-| `aikit_forge_classify` | — | Classify FORGE tier (Floor/Standard/Critical) from files and task |
-| `aikit_evidence_map` | — | Track critical-path claims as V/A/U with receipts + deterministic Gate |
-| `aikit_digest` | — | Compress multiple text sources into token-budgeted digest |
-| `aikit_stratum_card` | — | Generate STRATUM T1/T2 context cards (10-100x token reduction) |
-
-### Code Manipulation
-| Tool | CLI | Description |
-|------|-----|-------------|
-| `aikit_rename` | `aikit rename` | Smart symbol rename across files |
-| `aikit_codemod` | `aikit codemod` | Regex-based code transformations |
-| `aikit_diff_parse` | `aikit diff` | Parse unified diff into structured changes |
-| `aikit_data_transform` | `aikit transform` | JQ-like JSON transformations |
-
-### Execution & Validation
-| Tool | CLI | Description |
-|------|-----|-------------|
-| `aikit_eval` | `aikit eval` | Sandboxed JavaScript/TypeScript execution |
-| `aikit_check` | `aikit check` | Incremental typecheck + lint (`detail`: summary/errors/full) |
-| `aikit_test_run` | `aikit test` | Run tests with structured results |
-| `aikit_audit` | `aikit audit` | Unified project audit: runs structure, deps, patterns, health, dead symbols, check, entry points in one call. Returns score, recommendations, and next steps. |
-
-### Knowledge Management
-| Tool | CLI | Description |
-|------|-----|-------------|
-| `aikit_knowledge` | `aikit knowledge <action>` | Unified knowledge entry point for `remember`, `read`, `update`, `forget`, and `list` |
-| `aikit_produce_knowledge` | — | Auto-generate knowledge from analysis |
-
-### Git & Environment
-| Tool | CLI | Description |
-|------|-----|-------------|
-| `aikit_git_context` | `aikit git` | Branch, status, recent commits |
-| `aikit_process` | `aikit proc` | Process supervisor |
-| `aikit_watch` | `aikit watch` | Filesystem watcher |
-| `aikit_delegate` | `aikit delegate` | Delegate subtask to local Ollama model |
-
-### Web & Network
-| Tool | CLI | Description |
-|------|-----|-------------|
-| `aikit_web_fetch` | — | Fetch web page → markdown/raw/links/outline |
-| `aikit_web_search` | — | Search the web via DuckDuckGo (no API key) |
-| `aikit_http` | — | Make HTTP requests for API testing/debugging |
-
-### Developer Utilities
-| Tool | CLI | Description |
-|------|-----|-------------|
-| `aikit_regex_test` | — | Test regex patterns (match/replace/split modes) |
-| `aikit_encode` | — | Base64, URL, SHA-256, MD5, hex, JWT decode |
-| `aikit_measure` | — | Code complexity and line-count metrics |
-| `aikit_changelog` | — | Generate changelog from git history |
-| `aikit_schema_validate` | — | Validate JSON data against JSON Schema |
-| `aikit_env` | — | System and runtime environment info |
-| `aikit_time` | — | Date parsing, timezone conversion, duration math |
-
-### Verified Lanes
-| Tool | CLI | Description |
-|------|-----|-------------|
-| `aikit_lane` (create) | `aikit lane create` | Create isolated file copy for parallel exploration |
-| `aikit_lane` (list) | `aikit lane list` | List active lanes |
-| `aikit_lane` (status) | `aikit lane status` | Show modified/added/deleted files in a lane |
-| `aikit_lane` (diff) | `aikit lane diff` | Generate diff between lane and originals |
-| `aikit_lane` (merge) | `aikit lane merge` | Merge lane files back to originals |
-| `aikit_lane` (discard) | `aikit lane discard` | Discard a lane entirely |
-
-### System
-| Tool | CLI | Description |
-|------|-----|-------------|
-| `aikit_status` | `aikit status` | Index statistics + tree-sitter availability |
-| `aikit_reindex` | `aikit reindex` | Rebuild index |
-| `aikit_health` | `aikit health` | Project health checks (package.json, tsconfig, lockfile, circular deps) |
-| `aikit_guide` | `aikit guide` | Tool discovery — given a goal, recommends tools and workflow order |
-| `aikit_queue` | `aikit queue` | Task queue for sequential agent operations |
-| `aikit_graph` | `aikit graph` | Query and manage the knowledge graph (8 actions: find_nodes, find_edges, neighbors, traverse, stats, add, delete, clear) |
-| `aikit_onboard` | `aikit onboard` | First-time codebase onboarding — runs all analysis tools in one command, auto-persists results |
-| `aikit_replay` | `aikit replay` | View or clear the audit trail of tool invocations (action: list/clear) |
-| `aikit_config` | `aikit config` | View and modify runtime configuration |
-
-### Meta-Tools
-| Tool | CLI | Description |
-|------|-----|-------------|
-| `aikit_list_tools` | `aikit list-tools` | List all currently active tools with categories |
-| `aikit_describe_tool` | `aikit describe-tool` | Get detailed metadata for a specific tool |
-| `aikit_search_tools` | `aikit search-tools` | Search tools by keyword or capability |
-
-### Flow Management
-| Tool | CLI | Description |
-|------|-----|-------------|
-| `aikit_flow` | `aikit flow` | Manage flows — list, start, navigate steps, read instructions, inspect runs, add/remove/update. Use `action` parameter. |
-
-## MCP Integration
-
-After `aikit init`, your `.vscode/mcp.json` is configured automatically:
-
-```json
-{
-  "servers": {
-    "aikit": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["@vpxa/aikit", "serve"]
-    }
-  }
-}
-```
-
-> **User-level mode:** When installed with `aikit init --user`, the MCP server is configured at the user level — no per-project `mcp.json` needed. The server auto-detects and indexes each workspace.
-
-## CLI Usage
-
-```bash
-aikit <command> [options]
-
-# Search & Discovery
-aikit search <query> [--limit N] [--mode hybrid|semantic|keyword]
-aikit find [query] [--glob pattern] [--pattern regex] [--limit N]
-aikit symbol <name>
-aikit scope-map <task> [--max-files N]
-aikit trace <symbol> [--direction forward|backward|both] [--depth N]
-aikit examples <query> [--limit N]
-aikit summarize <file>
-aikit dead-symbols [--limit N]
-
-# Analysis
-aikit analyze <type> <path>
-aikit lookup <path>
-
-# Context
-aikit compact <query> [--path <file>] [--max-chars N]
-aikit workset <action> [name] [--files f1,f2]
-aikit stash <action> [key] [value]
-aikit checkpoint <action> [label]
-aikit parse-output [--tool tsc|vitest|biome|git-status]
-
-# Code Manipulation
-aikit rename <old> <new> <path> [--dry-run]
-aikit codemod <path> --rules <file.json> [--dry-run]
-aikit diff
-aikit transform <expression>
-
-# Execution
-aikit eval <code> [--lang js|ts] [--timeout N]
-aikit test [files...] [--grep pattern]
-aikit check [--skip-types] [--skip-lint] [--detail summary|errors|full]
-aikit batch
-
-# Knowledge
-aikit remember <title> --category <cat> [--tags t1,t2]
-aikit forget <path> --reason <reason>
-aikit read <path>
-aikit list [--category cat] [--tag tag]
-aikit update <path> --reason <reason>
-
-# Git & Environment
-aikit git [--commits N] [--diff]
-aikit proc <action> [id] [--command cmd]
-aikit watch <action> [--path dir]
-
-# Verified Lanes
-aikit lane create <name> --files file1.ts,file2.ts
-aikit lane list
-aikit lane status <name>
-aikit lane diff <name>
-aikit lane merge <name>
-aikit lane discard <name>
-
-# Graph
-aikit graph stats
-aikit graph find-nodes [--type module|function|class] [--query pattern]
-aikit graph find-edges [--type imports|defines] [--source path]
-aikit graph neighbors <nodeId> [--direction in|out|both]
-aikit graph traverse <startId> [--direction forward|backward] [--depth N]
-
-# System
-aikit status
-aikit reindex [--full]
-aikit onboard <path> [--generate] [--out-dir <dir>]
-aikit serve [--transport stdio|http] [--port N]
-aikit init [--user|--workspace] [--force] [--guide]
-aikit dashboard [--port N] [--no-open]
-aikit settings [--port N] [--no-open]
-```
-
-## Settings UI
-
-`aikit settings` launches a local web UI for managing `aikit.config.json`
-and environment variables (workspace `.env` and global
-`~/.aikit-data/global.env`).
-
-```bash
-aikit settings              # opens http://localhost:3210/settings/
-aikit settings --port 4000  # custom port
-aikit settings --no-open    # don't auto-open browser
-```
-
-The same UI is also mounted at `/settings/` whenever the MCP server is
-running with `--transport http`. Both surfaces share these REST endpoints
-under `/settings/api`:
-
-| Method | Path | Purpose |
-|--------|------|---------|
-| GET | `/status` | Mode (workspace/user), config path, env paths, MCP info |
-| GET | `/schema` | Known config keys and env vars with types and descriptions |
-| GET | `/config` | Current `aikit.config.json` content |
-| PATCH | `/config` | Apply set/unset patch ops, atomic write |
-| GET | `/env?reveal=true` | Workspace + global env snapshots (secrets masked unless `reveal`) |
-| PUT | `/env/:key` | Write a value to `{ scope: 'workspace' \| 'global' }` |
-| DELETE | `/env/:key?scope=...` | Remove a key from the chosen scope |
-
-The HTTP server binds `127.0.0.1` only (matching the existing
-`/_dashboard/` convention). Restart the MCP server for environment
-changes to take effect.
-
-## Configuration
-
-`aikit.config.json`:
-
-```json
-{
-  "sources": [{ "path": ".", "name": "project" }],
-  "embedding": {
-    "model": "Xenova/mxbai-embed-large-v1",
-    "dimensions": 1024
-  },
-  "store": {
-    "backend": "sqlite-vec",
-    "path": ".aikit-data/store"
-  },
-  "curated": {
-    "path": "curated"
-  }
-}
-```
-
-### Server Configuration
-
-The aikit MCP server also supports these SDK v2 configuration options in `aikit.config.json`:
-
-#### Feature Groups (`features`)
-
-Restrict the server to specific tool categories:
-
-```json
-{
-  "features": ["search", "knowledge", "execution"]
-}
-```
-
-When set, only tools belonging to the specified categories are registered, plus the base tools: `status`, `config`, `guide`, and `health`. Valid category names match the tool metadata categories exposed by the server.
-
-#### Read-Only Mode (`readOnly`)
-
-Prevent the server from modifying the codebase:
-
-```json
-{
-  "readOnly": true
-}
-```
-
-When enabled, tools annotated with `readOnlyHint: false` are excluded. This filters out mutating tools such as `remember`, `update`, `forget`, `codemod`, and `rename`. The `config` tool is also limited to its `view` action.
-
-#### Server Instructions (`serverInstructions`)
-
-Override the auto-generated MCP server instructions:
-
-```json
-{
-  "serverInstructions": "Custom instructions for the LLM about this server"
-}
-```
-
-If not set, the server auto-generates instructions that list the available tool categories and note any active restrictions.
-
-#### Tool Profiles (`toolProfile`)
-
-Select a predefined tool profile:
-
-```json
-{
-  "toolProfile": "safe"
-}
-```
-
-Available profiles: `full` (default), `safe`, `research`, `minimal`, `discovery`.
-
-## Architecture
-
-```text
-@vpxa/aikit
-├── packages/
-│   ├── core/         — types, config, logger, constants, global registry
-│   ├── store/        — SQLite-vec vector store
-│   ├── embeddings/   — ONNX local embeddings
-│   ├── chunker/      — tree-sitter + regex code chunking
-│   ├── indexer/      — incremental file indexer
-│   ├── analyzers/    — blast-radius, deps, symbols, patterns, diagrams
-│   ├── tools/        — consolidated tool modules (61 MCP tools)
-│   ├── server/       — MCP protocol server
-│   └── cli/          — command-line interface
-├── bin/aikit.mjs     — CLI entry point
-└── skills/           — LLM skill files
-```
-
-## License
-
-MIT
-
-### Development
-
-```bash
-pnpm install       # Install dependencies
-pnpm build         # Build all packages
-pnpm test          # Run tests (Vitest)
-pnpm lint          # Lint (Biome)
-```
-
----
-
-## Detailed MCP Tools Reference
-
-### Search & Retrieval
-
-#### `aikit_search` — Hybrid search across the AI Kit index
-
-Find relevant code, docs, patterns, and curated knowledge using hybrid (vector + keyword), semantic, or keyword-only search.
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `query` | string | **yes** | — | Natural language search query |
-| `limit` | number (1–20) | no | 5 | Maximum results to return |
-| `search_mode` | enum | no | `hybrid` | Search strategy: `hybrid` (vector + FTS + RRF fusion), `semantic` (vector only), `keyword` (FTS only) |
-| `content_type` | enum | no | — | Filter: `markdown`, `code-typescript`, `code-javascript`, `code-python`, `config-json`, `config-yaml`, `config-toml`, `config-dotenv`, `infrastructure`, `documentation`, `test`, `script`, `curated-knowledge`, `produced-knowledge`, `other` |
-| `origin` | enum | no | — | Filter: `indexed` (from files), `curated` (agent memory), `produced` (auto-generated) |
-| `category` | string | no | — | Filter by curated category (e.g., `decisions`, `patterns`) |
-| `tags` | string[] | no | — | Filter by tags (OR matching) |
-| `workspaces` | string[] | no | — | Cross-workspace search: partition names, folder basenames, or `["*"]` for all. User-level mode only. |
-| `min_score` | number (0–1) | no | 0.25 | Minimum similarity score threshold |
-
-**Returns**: Ranked results with score, source path, content type, line range, heading path, origin, tags, and full content text. Each response includes a `_Next:` hint suggesting logical follow-up tools.
-
-**Search modes**:
-- **`hybrid`** (default) — Runs vector similarity and full-text keyword search in parallel, then merges rankings using Reciprocal Rank Fusion (k=60). Best for most queries.
-- **`semantic`** — Pure vector cosine similarity. Best when searching by meaning/concept rather than exact terms.
-- **`keyword`** — Full-text search using SQLite FTS5 index. Best when searching for exact identifiers, function names, or specific strings.
-
-**Best practices for query**:
-- Use natural language describing what you're looking for: `"how does the notification dispatcher route messages"` 
-- Include domain terms that would appear in the code: `"DynamoDB single-table GSI pattern for notifications"`
-- Use `search_mode: "keyword"` for exact function/class names: `"reciprocalRankFusion"`
-- Use `search_mode: "semantic"` for conceptual queries: `"retry strategy with exponential backoff"`
-- For curated knowledge, combine with `origin: "curated"`: `query: "architecture decision", origin: "curated"`
-
-#### `aikit_lookup` — Get all chunks for a specific file
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `path` | string | **yes** | Relative file path (e.g., `src/index.ts`) |
-
-**Returns**: All chunks for that file, sorted by position, with line ranges and content.
-
-#### `aikit_status` — View index statistics
-
-No parameters. Returns total records, total files, content type breakdown, last indexed timestamp, and list of indexed files.
-
-### Curated Knowledge (Persistent Memory)
-
-These tools give the agent **persistent, version-tracked memory** that survives across sessions. Knowledge is stored as markdown files with YAML frontmatter in the `curated/` directory and simultaneously indexed into the vector store for semantic search.
-
-#### `aikit_knowledge` — Unified curated knowledge tool
-
-Use the `action` parameter to choose the operation: `remember`, `read`, `update`, `forget`, or `list`.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `title` | string (3–120 chars) | **yes** | Short descriptive title |
-| `content` | string (≥10 chars) | **yes** | Markdown content to store |
-| `category` | string (kebab-case) | **yes** | Category slug: `decisions`, `patterns`, `conventions`, `troubleshooting`, or any custom kebab-case name |
-| `tags` | string[] | no | Tags for filtering |
-
-**What to remember**: Architecture decisions, coding conventions, recurring patterns, API contracts, deployment procedures, debugging solutions, team agreements, review findings.
-
-#### `aikit_knowledge` with `action: "update"` — Update existing knowledge
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `path` | string | **yes** | Path from `aikit_list` (e.g., `decisions/use-sqlite-vec.md`) |
-| `content` | string (≥10 chars) | **yes** | New markdown content (replaces existing) |
-| `reason` | string (≥3 chars) | **yes** | Why this update is being made (recorded in changelog) |
-
-Increments version number and appends to the entry's changelog.
-
-#### `aikit_knowledge` with `action: "read"` — Read a curated entry
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `path` | string | **yes** | Path from `aikit_list` |
-
-**Returns**: Full metadata (title, version, tags, created, updated) and content.
-
-#### `aikit_knowledge` with `action: "list"` — List curated entries
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `category` | string | no | Filter by category |
-| `tag` | string | no | Filter by tag |
-
-**Returns**: All entries with title, version, tags, path, and 80-char content preview.
-
-#### `aikit_knowledge` with `action: "forget"` — Remove a curated entry
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `path` | string | **yes** | Path from `aikit_list` |
-| `reason` | string (≥3 chars) | **yes** | Why this entry is being removed |
-
-Deletes from disk and vector store.
-
-### Indexing
-
-#### `aikit_reindex` — Trigger re-indexing
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `full` | boolean | no | false | If true, force full re-index ignoring file hashes |
-
-Incremental mode (default) only re-indexes files whose content hash has changed. Full mode drops the table and rebuilds from scratch.
-
-### Codebase Analysis
-
-#### `aikit_produce_knowledge` — Automated analysis + synthesis instructions
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `scope` | string | no | `.` (root) | Root path to analyze |
-| `aspects` | enum[] | no | `["all"]` | `all`, `structure`, `dependencies`, `symbols`, `patterns`, `entry-points`, `diagrams` |
-
-Runs deterministic analyzers, then returns structured instructions for the agent to synthesize and store findings using `aikit_knowledge` with `action: "remember"`.
-
-#### `aikit_analyze` with `aspect: "structure"` — File/directory tree with language stats
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `path` | string | **yes** | — | Root path to analyze |
-| `max_depth` | number (1–10) | no | 6 | Maximum directory depth |
-| `format` | enum | no | `markdown` | `json` or `markdown` |
-
-#### `aikit_analyze` with `aspect: "dependencies"` — Import/require dependency graph (with confidence)
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `path` | string | **yes** | — | Root path |
-| `format` | enum | no | `markdown` | `json`, `markdown`, or `mermaid` |
-
-Dependency results include a **confidence** level per import: `high` (ES static imports), `medium` (dynamic imports, require()), `low` (inferred). The markdown format shows a Confidence column in dependency tables.
-
-#### `aikit_analyze` with `aspect: "symbols"` — Exported & local symbols
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `path` | string | **yes** | — | Root path |
-| `filter` | string | no | — | Filter symbols by name substring |
-| `format` | enum | no | `markdown` | `json` or `markdown` |
-
-#### `aikit_analyze` with `aspect: "patterns"` — Detect architectural patterns & frameworks
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `path` | string | **yes** | Root path |
-
-#### `aikit_analyze` with `aspect: "entry_points"` — Find Lambda handlers, CDK constructs, test suites, package exports
-
-Walks monorepo workspace packages (pnpm-workspace.yaml / package.json#workspaces), parses `exports` fields, detects CDK constructs and test suites.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `path` | string | **yes** | Root path |
-
-#### `aikit_analyze` with `aspect: "diagram"` — Generate Mermaid architecture/dependency diagrams
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `path` | string | **yes** | — | Root path |
-| `diagram_type` | enum | no | `architecture` | `architecture` or `dependencies` |
-
-### Context Management
-
-#### `aikit_compact` — Compress text to query-relevant sections
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `text` | string | no* | — | The text to compress (provide `text` or `path`) |
-| `path` | string | no* | — | File path to read server-side (avoids read_file round-trip) |
-| `query` | string | **yes** | — | Focus query — what are you trying to understand? |
-| `max_chars` | number (100–50000) | no | `3000` | Target output size in characters |
-| `segmentation` | enum | no | `paragraph` | How to split: `paragraph`, `sentence`, `line` |
-
-\* At least one of `text` or `path` must be provided. Using `path` is preferred — it eliminates the `read_file` → `compact` two-call chain and prevents token doubling.
-
-#### `aikit_workset` — Manage named file sets
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `action` | enum | **yes** | — | `save`, `get`, `list`, `delete`, `add`, `remove` |
-| `name` | string | varies | — | Workset name (required for all except `list`) |
-| `files` | string[] | varies | — | File paths (required for `save`, `add`, `remove`) |
-| `description` | string | no | — | Description (for `save`) |
-
-Worksets persist across sessions in `.aikit-state/worksets.json`.
-
-#### `aikit_stash` — Persist named key-value pairs
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `action` | enum | **yes** | — | `set`, `get`, `list`, `delete`, `clear` |
-| `key` | string | varies | — | Entry key (for `set`, `get`, `delete`) |
-| `value` | string | varies | — | String or JSON value (for `set`) |
-
-Stores intermediate results between tool calls in `.aikit-state/stash.json`.
-
-#### `aikit_checkpoint` — Save/restore session checkpoints
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `action` | enum | **yes** | — | `save`, `load`, `list`, `latest` |
-| `label` | string | varies | — | Checkpoint label (for `save`), or checkpoint ID (for `load`) |
-| `data` | string | varies | — | JSON object string (for `save`) |
-| `notes` | string | no | — | Optional notes (for `save`) |
-
-Lightweight checkpoints stored in `.aikit-state/checkpoints/` for cross-session continuity.
-
-#### `aikit_parse_output` — Parse build tool output
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `output` | string | **yes** | — | Raw output text from a build tool |
-| `tool` | enum | no | auto-detect | `tsc`, `vitest`, `biome`, `git-status` |
-
-Returns JSON structured parse result with errors, warnings, and file references. Auto-detects the tool format when not specified.
-
-### FORGE & Context Compression
-
-#### `aikit_forge_ground` — Complete FORGE Ground phase
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `task` | string | **yes** | — | Task description |
-| `files` | string[] | **yes** | — | Target files being modified (absolute paths) |
-| `root_path` | string | **yes** | — | Root path of the codebase |
-| `max_constraints` | number (0–10) | no | `3` | Max constraint entries to load from AI Kit |
-| `force_tier` | enum | no | auto | Force tier: `floor`, `standard`, `critical` (skips auto-classification) |
-| `task_id` | string | no | auto-generated | Custom task ID for evidence map |
-
-Chains: tier classification → scope map → file summaries → constraint loading → typed unknown seeds → evidence map creation. Replaces 5-15 manual tool calls. Floor tasks get a minimal shortcut (no scope map / constraints / evidence map).
-
-#### `aikit_forge_classify` — Classify FORGE tier
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `files` | string[] | **yes** | Files being modified (paths) |
-| `task` | string | **yes** | Task description |
-| `root_path` | string | **yes** | Root path of the codebase |
-
-Checks blast radius, cross-package boundaries, schema/contract patterns, and security signals. Returns tier, triggers, typed unknown seeds, packages crossed, and ceremony guidance.
-
-#### `aikit_evidence_map` — FORGE Evidence Map CRUD + Gate
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `action` | enum | **yes** | — | `create`, `add`, `update`, `get`, `gate`, `list`, `delete` |
-| `task_id` | string | varies | — | Task identifier (all except `list`) |
-| `tier` | enum | varies | — | FORGE tier (for `create`): `floor`, `standard`, `critical` |
-| `claim` | string | varies | — | Critical-path claim text (for `add`) |
-| `status` | enum | varies | — | `V` (Verified), `A` (Assumed), `U` (Unresolved) |
-| `receipt` | string | no | — | Evidence: tool→ref for V, reasoning for A, attempts for U |
-| `id` | number | varies | — | Entry ID (for `update`) |
-| `critical_path` | boolean | no | `true` | Whether claim is on the critical path |
-| `unknown_type` | enum | no | — | `contract`, `convention`, `freshness`, `runtime`, `data-flow`, `impact` |
-| `retry_count` | number | no | `0` | Retry count for gate evaluation |
-
-Gate decision logic: HARD_BLOCK (contract U on critical path) → HOLD (non-contract U, retry 0) → FORCED_DELIVERY (non-contract U, retry ≥ 1) → YIELD. Persists in `.aikit-state/evidence-maps.json`.
-
-#### `aikit_digest` — Token-budgeted multi-source compression
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `sources` | object[] | **yes** | — | Sources: `{ id, text, weight }` (weight = priority, higher = more budget) |
-| `query` | string | **yes** | — | Focus query — what matters for the next step? |
-| `max_chars` | number (100–50000) | no | `4000` | Target budget in characters |
-| `pin_fields` | string[] | no | status, files, decisions, blockers, next | Key fields to always extract |
-| `segmentation` | enum | no | `paragraph` | `paragraph`, `sentence`, `line` |
-
-Jointly ranks across all sources using embedding similarity. Pins structured fields (key:value patterns) and allocates remaining budget proportionally by weight. Returns compressed text + extracted fields + per-source stats.
-
-#### `aikit_stratum_card` — STRATUM context cards
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `files` | string[] | **yes** | — | Absolute file paths to generate cards for |
-| `query` | string | **yes** | — | Current task query — guides relevance scoring |
-| `tier` | enum | no | `T1` | `T1` = structural only (~100 tok/file), `T2` = T1 + compressed content (~300 tok/file) |
-| `max_content_chars` | number (100–5000) | no | `800` | For T2: max chars for compressed content section |
-
-T1 cards contain: ROLE, DEPS, EXPORTS, UNKNOWNS, RISK. T2 adds a CONTEXT section with query-compressed content. Uses `aikit_file_summary` + embedder similarity. No generative LLM needed.
-
-### Search & Discovery
-
-#### `aikit_find` — Federated multi-strategy search
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `query` | string | no | — | Semantic/keyword search query |
-| `glob` | string | no | — | File glob pattern |
-| `pattern` | string | no | — | Regex pattern to match in content |
-| `limit` | number (1–50) | no | `10` | Max results |
-| `content_type` | string | no | — | Filter by content type |
-
-Combines vector similarity, keyword (FTS), file glob, and regex strategies. Deduplicates and returns unified results with source, path, line range, score %, and preview.
-
-#### `aikit_symbol` — Resolve a symbol across the codebase
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `name` | string | **yes** | — | Symbol name (function, class, type, etc.) |
-| `limit` | number (1–50) | no | `20` | Max results per category |
-
-Finds where a symbol is defined, who imports it, and where it is referenced. Works on TypeScript and JavaScript.
-
-#### `aikit_scope_map` — Generate a task-scoped reading plan
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `task` | string | **yes** | — | Description of the task to scope |
-| `max_files` | number (1–50) | no | `15` | Maximum files to include |
-| `content_type` | string | no | — | Filter by content type |
-
-Returns a ranked file list with estimated token counts, relevance %, focus line ranges, and a suggested reading order.
-
-#### `aikit_trace` — Trace data flow through imports/references
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `start` | string | **yes** | — | Starting point — symbol name or `file:line` reference |
-| `direction` | enum | **yes** | — | `forward`, `backward`, `both` |
-| `max_depth` | number (1–10) | no | `3` | Maximum trace depth |
-
-Follows imports, call sites, and references to build a relationship graph from a starting symbol or file location.
-
-#### `aikit_dead_symbols` — Find unused exported symbols
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `limit` | number (1–500) | no | `100` | Maximum exported symbols to scan |
-
-Finds exported symbols that are never imported or re-exported anywhere in the project.
-
-#### `aikit_file_summary` — Structural summary of a source file
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `path` | string | **yes** | Absolute path to the file |
-
-Returns imports, exports, functions, classes, interfaces, and types found in the file.
-
-### Code Manipulation
-
-#### `aikit_rename` — Rename a symbol across files
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `old_name` | string | **yes** | — | Existing symbol name |
-| `new_name` | string | **yes** | — | New symbol name |
-| `root_path` | string | **yes** | — | Root directory to search within |
-| `extensions` | string[] | no | — | File extensions to include (e.g., `.ts`, `.tsx`) |
-| `dry_run` | boolean | no | `true` | Preview changes without writing files |
-
-Uses whole-word regex matching for exports, imports, and general usage references. Defaults to dry run.
-
-#### `aikit_codemod` — Apply regex-based codemod rules
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `root_path` | string | **yes** | — | Root directory to transform within |
-| `rules` | object[] (min 1) | **yes** | — | Codemod rules: `description`, `pattern` (regex), `replacement` (with capture groups) |
-| `dry_run` | boolean | no | `true` | Preview changes without writing files |
-
-Returns structured before/after changes for each affected line. Defaults to dry run.
-
-#### `aikit_diff_parse` — Parse unified diff text
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `diff` | string | **yes** | Raw unified diff text |
-
-Parses into file-level and hunk-level structural changes.
-
-#### `aikit_data_transform` — jq-like JSON transforms
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `input` | string | **yes** | Input JSON string |
-| `expression` | string | **yes** | Transform expression (filtering, projection, grouping, path extraction) |
-
-### Execution & Validation
-
-#### `aikit_eval` — Execute code in a sandboxed VM
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `code` | string | **yes** | — | Code snippet to execute |
-| `lang` | enum | no | `js` | `js` (direct) or `ts` (strips type syntax first) |
-| `timeout` | number (1–60000) | no | `5000` | Execution timeout in milliseconds |
-
-Captures console output and return values. Constrained VM with timeout.
-
-#### `aikit_check` — Run typecheck and lint
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `files` | string[] | no | — | Specific files (omit to check all) |
-| `cwd` | string | no | — | Working directory |
-| `skip_types` | boolean | no | `false` | Skip TypeScript typecheck |
-| `skip_lint` | boolean | no | `false` | Skip Biome lint |
-
-Runs incremental `tsc` and `biome` and returns structured error/warning lists.
-
-#### `aikit_test_run` — Run Vitest tests
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `files` | string[] | no | — | Specific test files or patterns |
-| `grep` | string | no | — | Only run tests matching this pattern |
-| `cwd` | string | no | — | Working directory |
-
-Returns structured pass/fail summary. `isError` set if any tests failed.
-
-#### `aikit_audit` — Unified project audit
-
-Runs multiple analysis checks in a single call and returns a synthesized report with a composite score (0–100), per-check summaries, and prioritized recommendations.
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `path` | string | no | `.` | Root path to audit |
-| `checks` | string[] | no | all | Subset of checks: `structure`, `dependencies`, `patterns`, `health`, `dead_symbols`, `check`, `entry_points` |
-| `detail` | enum | no | `summary` | `summary` (markdown overview) or `full` (structured JSON data) |
-
-Returns `KBResponse<AuditData>` with `next[]` hints for follow-up actions.
-
-### Git & Environment
-
-#### `aikit_git_context` — Summarize Git repository state
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `cwd` | string | no | — | Repository root |
-| `commit_count` | number (1–50) | no | `5` | Recent commits to include |
-| `include_diff` | boolean | no | `false` | Include diff stat for working tree |
-
-Returns branch, working tree status, recent commits, and optionally diff stats.
-
-#### `aikit_process` — Manage child processes
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `action` | enum | **yes** | — | `start`, `stop`, `status`, `list`, `logs` |
-| `id` | string | varies | — | Managed process ID |
-| `command` | string | varies | — | Executable (for `start`) |
-| `args` | string[] | no | — | Arguments (for `start`) |
-| `tail` | number (1–500) | no | — | Log lines (for `logs`) |
-
-#### `aikit_watch` — Filesystem watchers
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `action` | enum | **yes** | — | `start`, `stop`, `list` |
-| `path` | string | varies | — | Directory path (for `start`) |
-| `id` | string | varies | — | Watcher ID (for `stop`) |
-
-#### `aikit_delegate` — Delegate subtask to local Ollama model
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `prompt` | string | **yes** | — | Task or question to send |
-| `model` | string | no | first available | Ollama model name |
-| `system` | string | no | — | System prompt |
-| `context` | string | no | — | Context text (e.g., file contents) |
-| `temperature` | number (0–2) | no | `0.3` | Sampling temperature |
-| `timeout` | number (1000–600000) | no | `120000` | Timeout in ms |
-| `action` | enum | no | `generate` | `generate` or `list_models` |
-
-Fails fast if Ollama is not running. Returns model name, response text, duration, and token count.
-
-### Web & Network
-
-#### `aikit_web_fetch` — Fetch web page for LLM consumption
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `url` | string | **yes** | — | URL to fetch (http/https only) |
-| `mode` | enum | no | `markdown` | `markdown`, `raw`, `links`, `outline` |
-| `selector` | string | no | — | CSS selector to extract a specific element |
-| `max_length` | number (500–100000) | no | `15000` | Max output characters |
-| `include_metadata` | boolean | no | `true` | Include page title/description header |
-| `include_links` | boolean | no | `false` | Append extracted links |
-| `include_images` | boolean | no | `false` | Include image alt texts |
-| `timeout` | number (1000–60000) | no | `15000` | Request timeout in ms |
-
-Strips scripts, styles, and boilerplate. Smart truncation at paragraph boundaries.
-
-#### `aikit_web_search` — Search the web
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `query` | string | **yes** | — | Search query |
-| `limit` | number (1–20) | no | `5` | Max results |
-| `site` | string | no | — | Restrict to domain (e.g., `docs.aws.amazon.com`) |
-
-Uses DuckDuckGo HTML search — no API key required. Returns title, URL, and snippet for each result.
-
-#### `aikit_http` — Make HTTP requests
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `url` | string | **yes** | — | Request URL (http/https only) |
-| `method` | enum | no | `GET` | `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD` |
-| `headers` | record | no | — | Request headers |
-| `body` | string | no | — | Request body |
-| `timeout` | number (1000–60000) | no | `15000` | Timeout in ms |
-
-Returns status, headers, formatted body (auto-pretty-prints JSON), timing, and size. Truncates responses over 50K chars.
-
-### Developer Utilities
-
-#### `aikit_regex_test` — Test regex patterns
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `pattern` | string | **yes** | — | Regex pattern (without delimiters) |
-| `flags` | string | no | `""` | Regex flags (g, i, m, s, etc.) |
-| `test_strings` | string[] | **yes** | — | Strings to test against |
-| `mode` | enum | no | `match` | `match`, `replace`, `split` |
-| `replacement` | string | no | — | Replacement string (for replace mode) |
-
-Returns match details with groups and indices for each test string.
-
-#### `aikit_encode` — Encoding, decoding, and hashing
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `operation` | enum | **yes** | `base64_encode`, `base64_decode`, `url_encode`, `url_decode`, `sha256`, `md5`, `jwt_decode`, `hex_encode`, `hex_decode` |
-| `input` | string | **yes** | Input text |
-
-JWT decode shows header and payload without signature verification.
-
-#### `aikit_measure` — Code complexity metrics
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `path` | string | **yes** | — | File or directory to measure |
-| `extensions` | string[] | no | `.ts,.tsx,.js,.jsx` | File extensions to include |
-
-Returns per-file metrics (cyclomatic complexity, line counts, function counts, imports/exports) sorted by complexity, plus aggregate summary.
-
-#### `aikit_changelog` — Generate changelog from git history
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `from` | string | **yes** | — | Start ref (tag, SHA, HEAD~N) |
-| `to` | string | no | `HEAD` | End ref |
-| `format` | enum | no | `grouped` | `grouped`, `chronological`, `per-scope` |
-| `include_breaking` | boolean | no | `true` | Highlight breaking changes |
-
-Parses conventional commit format (type(scope): subject). Groups by feat/fix/refactor/etc.
-
-#### `aikit_schema_validate` — JSON Schema validation
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `data` | string | **yes** | JSON data to validate (as string) |
-| `schema` | string | **yes** | JSON Schema to validate against (as string) |
-
-Supports: type, required, properties, additionalProperties, items, enum, const, pattern, minimum/maximum, minLength/maxLength, minItems/maxItems.
-
-#### `aikit_env` — System environment info
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `include_env` | boolean | no | `false` | Include environment variables |
-| `filter_env` | string | no | — | Filter env vars by name substring |
-| `show_sensitive` | boolean | no | `false` | Show sensitive values (redacted by default) |
-
-Returns platform, arch, OS, CPU count, memory, Node version, CWD. Sensitive env var values (keys matching key/secret/token/password) are redacted unless explicitly requested.
-
-#### `aikit_time` — Date/time utilities
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `operation` | enum | **yes** | `now`, `parse`, `convert`, `diff`, `add` |
-| `input` | string | varies | Date input (ISO, unix timestamp, parseable string). For diff: two comma-separated dates |
-| `timezone` | string | no | Target timezone (e.g., `America/New_York`) |
-| `duration` | string | no | Duration to add (e.g., `2h30m`, `1d`) — for add operation |
-
-Auto-detects unix seconds vs milliseconds. Supports human-readable duration format (2h30m, 1d12h).
-
-### Verified Lanes
-
-#### `aikit_lane` — Manage verified lanes
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `action` | enum | **yes** | — | `create`, `list`, `status`, `diff`, `merge`, `discard` |
-| `name` | string | varies | — | Lane name |
-| `files` | string[] | varies | — | File paths to copy into lane (for `create`) |
-
-Isolated file copies for parallel exploration. Create a lane, make changes, diff against originals, merge back, or discard.
-
-### System
-
-#### `aikit_guide` — Tool discovery
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `goal` | string | **yes** | — | What you want to accomplish |
-| `max_recommendations` | number | no | 5 | Max tools to recommend (1-10) |
-
-Given a goal description, recommends which AI Kit tools to use and in what order. Matches against 10 predefined workflows: onboard, audit, bugfix, implement, refactor, search, context, memory, validate, analyze.
-
-#### `aikit_health` — Run project health checks
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `path` | string | no | cwd | Root directory to check |
-
-Verifies package.json, tsconfig, scripts, lockfile, README, LICENSE, .gitignore, circular dependencies.
-
-#### `aikit_queue` — Manage task queues
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `action` | enum | **yes** | — | `create`, `push`, `next`, `done`, `fail`, `get`, `list`, `clear`, `delete` |
-| `name` | string | varies | — | Queue name |
-| `title` | string | varies | — | Item title (for `push`) |
-| `id` | string | varies | — | Item ID (for `done`/`fail`) |
-| `data` | any | no | — | Arbitrary data to attach |
-| `error` | string | varies | — | Error message (for `fail`) |
-
-Sequential task queues for agent operations.
-
-#### `aikit_replay` — View or clear audit trail
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `action` | enum | no | `list` | `list` to view entries, `clear` to wipe the log |
-| `last` | number | no | 20 | Number of entries to return (list only) |
-| `tool` | string | no | — | Filter by tool name (list only) |
-| `source` | enum | no | — | Filter by source: `mcp` or `cli` (list only) |
-| `since` | string | no | — | ISO timestamp — only show entries after this time (list only) |
-
-Shows the audit trail of recent tool invocations. Each entry includes tool name, duration, input/output summaries, and status. Useful for debugging agent behavior.
-
-### Flow Management
-
-#### `aikit_flow` — Manage development flows
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `action` | string | **yes** | — | Operation: `list`, `info`, `start`, `step`, `status`, `read`, `reset`, `runs`, `add`, `remove`, `update` |
-| `name` | string | varies | — | Flow name (for `info`, `start`, `remove`, `update`) |
-| `topic` | string | no | — | Human-readable topic for the run (for `start`) |
-| `advance` | string | varies | — | Step action: `next`, `skip`, `redo` (for `step`) |
-| `step` | string | no | — | Step id to read (for `read`; defaults to current step) |
-| `source` | string | varies | — | Git URL, local path, or shorthand (for `add`) |
-| `roots` | string[] | no | — | Workspace roots for multi-root flows (for `start`) |
-
-**Actions:**
-- `list` — List installed flows (builtin + custom)
-- `info` — Get detailed flow info including all steps
-- `start` — Start a named flow with a topic
-- `step` — Advance current step (next/skip/redo)
-- `status` — Check active flow state, current step, phase
-- `read` — Read instruction content for current or named step
-- `reset` — Clear flow state to start over
-- `runs` — List historical flow runs
-- `add` — Install a custom flow from source
-- `remove` — Remove an installed custom flow
-- `update` — Update flow definition
-
----
-
-## MCP Resources
-
-| URI | Name | Description |
-|-----|------|-------------|
-| `aikit://status` | `aikit-status` | Quick status: record count, file count, last indexed time |
-| `aikit://file-tree` | `aikit-file-tree` | Sorted list of all indexed source file paths |
-
----
-
-## Curated Knowledge System
-
-The curated system is the agent's **persistent memory layer**. Files are stored as markdown with YAML frontmatter in `curated/`:
-
-```
-curated/
-├── conventions/   # 214 entries — coding conventions, style rules, naming patterns
-├── decisions/     # 295 entries — architecture decisions, ADRs, design rationale
-├── patterns/      # 165 entries — recurring patterns, templates, code idioms
-└── troubleshooting/  # 62 entries — known issues, fixes, debugging guides
-```
-
-### Frontmatter Format
-
-```yaml
----
-title: "Use SQLite-vec for local vector storage"
-category: decisions
-tags: ["vector-store", "architecture", "sqlite-vec"]
-created: 2026-01-15T10:30:00.000Z
-updated: 2026-02-20T14:22:00.000Z
-version: 3
-origin: curated
-changelog:
-  - version: 1
-    date: 2026-01-15T10:30:00.000Z
-    reason: "Initial creation"
-  - version: 2
-    date: 2026-02-01T09:00:00.000Z
-    reason: "Added performance benchmarks"
-  - version: 3
-    date: 2026-02-20T14:22:00.000Z
-    reason: "Updated with hybrid search findings"
----
-
-Markdown content here...
-```
-
-### Category Guidelines
-
-| Category | Use For | Examples |
-|----------|---------|---------|
-| `conventions` | Rules the team follows | Naming patterns, import ordering, error handling style, test structure |
-| `decisions` | Why something was chosen | ADRs, technology choices, pattern selections with trade-offs |
-| `patterns` | How to do recurring things | CDK stack templates, API endpoint patterns, state machine shapes |
-| `troubleshooting` | Known problems and fixes | Build failures, deployment gotchas, dependency conflicts |
-| Custom (`api-contracts`, `runbooks`, etc.) | Any kebab-case slug | Domain-specific categories as needed |
-
----
-
-## How to Write Agent Instructions for Using This KB
-
-When writing instructions for an AI agent (e.g., in `.copilot-instructions.md`, `AGENTS.md`, `CLAUDE.md`, or system prompts), include the following guidance:
-
-### Recommended Agent Instruction Template
-
-```markdown
-## AI Kit Knowledge Usage
-
-You have access to persistent AI Kit knowledge via MCP tools. Use it proactively.
-
-### Before Starting Any Task
-1. **Search first**: Use `aikit_search` with a natural language query describing your task to find relevant context, prior decisions, conventions, and patterns before writing code.
-2. **Check conventions**: `aikit_search` with `origin: "curated"` and `category: "conventions"` for coding standards that apply to your work.
-3. **Check decisions**: `aikit_search` with `category: "decisions"` to understand why things were built a certain way.
-
-### Search Strategies
-- **Broad hybrid** (default, best for most queries): `aikit_search({ query: "notification routing architecture" })`
-- **Exact identifier lookup**: `aikit_search({ query: "handleNotification", search_mode: "keyword" })`
-- **Conceptual similarity**: `aikit_search({ query: "event-driven message fanout design", search_mode: "semantic" })`
-- **Specific convention**: `aikit_search({ query: "error handling", origin: "curated", category: "conventions" })`
-- **Code patterns**: `aikit_search({ query: "DynamoDB batch write pattern", content_type: "code-typescript" })`
-- **Troubleshooting**: `aikit_search({ query: "deployment failure CDK", category: "troubleshooting" })`
-- **View a full file**: `aikit_lookup({ path: "src/services/dispatcher.ts" })`
-
-### Follow the Hints
-Every tool response includes a `_Next:` suggestion at the bottom. Follow these hints for efficient workflows — they guide you to logical next actions (e.g., after `aikit_search`, the hint suggests `aikit_lookup` or `aikit_analyze`).
-
-### After Completing a Task
-1. **Remember decisions**: If you made an architecture or design decision, store it:
-   ```
-  aikit_knowledge({
-    action: "remember",
-     title: "Use event-driven pattern for notification fanout",
-     content: "## Decision\n\n...\n\n## Rationale\n\n...\n\n## Alternatives Considered\n\n...",
-     category: "decisions",
-     tags: ["notifications", "architecture", "event-driven"]
-   })
-   ```
-2. **Remember patterns**: If you established a reusable code pattern:
-   ```
-  aikit_knowledge({
-    action: "remember",
-     title: "CDK construct pattern for SQS-Lambda integration",
-     content: "## Pattern\n\n```typescript\n...\n```\n\n## When to Use\n\n...",
-     category: "patterns",
-     tags: ["cdk", "sqs", "lambda"]
-   })
-   ```
-3. **Remember troubleshooting**: If you solved a tricky bug:
-   ```
-  aikit_knowledge({
-    action: "remember",
-     title: "Dimension mismatch after model change",
-     content: "## Problem\n\n...\n\n## Solution\n\nRun `aikit_reindex({ full: true })`...",
-     category: "troubleshooting",
-     tags: ["sqlite-vec", "embeddings"]
-   })
-   ```
-4. **Update existing knowledge**: If you're revising a prior decision:
-   ```
-   aikit_update({
-     path: "decisions/use-event-driven-fanout.md",
-     content: "updated markdown...",
-     reason: "Added retry strategy after production incident"
-   })
-   ```
-
-### Knowledge Quality Standards
-- **Decisions** should include: Context, Decision, Rationale, Alternatives Considered, Consequences
-- **Patterns** should include: Pattern description, Code example, When to Use, When Not to Use
-- **Conventions** should include: The Rule, Why, Examples (good vs bad)
-- **Troubleshooting** should include: Problem, Symptoms, Root Cause, Solution, Prevention
-
-### Codebase Analysis (for onboarding or deep understanding)
-- Run `aikit_produce_knowledge({ aspects: ["all"] })` to get analysis baselines and follow the synthesis instructions to populate the KB
-- Use `aikit_analyze({ aspect: "structure", path: "." })` for project layout overview
-- Use `aikit_analyze({ aspect: "dependencies", path: ".", format: "mermaid" })` for dependency visualization
-- Use `aikit_analyze({ aspect: "patterns", path: "." })` to detect frameworks and conventions
-
-### Index Maintenance
-- Run `aikit_reindex()` after significant code changes (incremental, fast)
-- Run `aikit_reindex({ full: true })` after model changes or corruption
-- Check `aikit_status()` to verify index health
-```
-
----
-
-## Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `AIKIT_TRANSPORT` | `stdio` | Transport mode: `stdio` or `http` |
-| `AIKIT_PORT` | `3210` | HTTP server port (when `--transport http`) |
-| `AIKIT_AUTO_INDEX` | `true` | Set to `false` to skip initial auto-indexing |
-| `AIKIT_CORS_ORIGIN` | `*` | CORS allowed origin for HTTP mode |
-| `AIKIT_WORKSPACE_DIR` | — | Override workspace root path |
-| `AIKIT_DATA_DIR` | — | Override data directory |
-| `AIKIT_MODEL_DIR` | — | Override ONNX model cache directory |
-
----
-
-## Tech Stack
-
-- **Embeddings**: `@huggingface/transformers` with `mixedbread-ai/mxbai-embed-large-v1` (1024 dimensions, ONNX, query-prefixed with `"Represent this sentence for searching relevant passages: "`)
-- **Vector Store**: SQLite-vec (local disk, cosine similarity, SQLite FTS5 for keyword search)
-- **Search**: Hybrid (vector + FTS + RRF fusion), semantic-only, or keyword-only modes
-- **Chunking**: Markdown-aware (heading hierarchy), **tree-sitter AST-based** (TS/JS/Python/Go/Rust/Java — preserves function/class boundaries), with overlap. Falls back to regex-based generic chunking when tree-sitter grammars are unavailable.
-- **Dependency Analysis**: Confidence-scored imports (high/medium/low per import pattern)
-- **Auto-Persist**: Analysis tool results are automatically indexed as `origin: 'produced'` entries for future search
-- **Workflow Hints**: Every tool response includes `_Next:` suggestions for logical follow-up actions
-- **MCP SDK**: `@modelcontextprotocol/sdk` (stdio + StreamableHTTP transports)
-- **Runtime**: Node.js ≥ 24, TypeScript, ESM, pnpm workspaces
-- **Build**: tsdown with integrated dts generation
-- **Lint**: Biome
-- **Test**: Vitest