@vpxa/aikit 0.1.1

package/packages/cli/dist/commands/init/templates.js

@@ -0,0 +1,194 @@
+function e(e,t){return`# ${e} — Copilot Instructions
+
+This project has an MCP server (\`${t}\`) providing 67 tools for search, analysis, memory, and validation.
+**These tools REPLACE most native IDE tools.** You MUST use them.
+
+## Step 0: Load KB Tools
+
+Before doing ANYTHING else, load the KB MCP tools. They are deferred — you must load them first.
+Search for tools matching the server name (e.g. \`knowledge-bas\`):
+\`\`\`
+tool_search_tool_regex({ pattern: "knowledge-bas" })   // loads all 67 KB tools
+\`\`\`
+Once loaded, KB tools appear as \`mcp_<server>_<tool>\` (e.g. \`mcp_knowledge-bas_search\`).
+
+## FORBIDDEN: Native Tools When KB Alternative Exists
+
+| NEVER use this | USE THIS KB TOOL INSTEAD | Why |
+|---|---|---|
+| \`read_file\` to understand a file | \`file_summary({ path })\` | Structure, exports, imports — 10x fewer tokens |
+| \`read_file\` to find specific code | \`compact({ path, query })\` | Server-side read + semantic extract — 5-20x reduction |
+| Multiple \`read_file\` calls | \`digest({ sources })\` | Compresses multiple files into token-budgeted summary |
+| \`grep_search\` / \`semantic_search\` | \`search({ query })\` | Hybrid search across all indexed + curated content |
+| \`grep_search\` for a symbol name | \`symbol({ name })\` | Definition + references with scope and call context |
+| \`run_in_terminal\` for find/grep | \`find({ pattern })\` or \`search()\` | No shell needed, richer results |
+| \`run_in_terminal\` for tsc/lint | \`check({})\` | Typecheck + lint combined, summary output |
+| \`run_in_terminal\` for test | \`test_run({})\` | Run tests with structured output |
+| Manual code tracing | \`trace({ symbol, direction })\` | AST call-graph traversal |
+| Line counting / wc | \`measure({ path })\` | Lines, functions, cognitive complexity |
+| \`fetch_webpage\` | \`web_fetch({ url })\` | Readability extract + token budget — richer output |
+| Web research / browsing | \`web_search({ query })\` | Structured web results without browser — unique to KB |
+
+**\`read_file\` is ONLY acceptable when you need exact line content FOR EDITING (before \`replace_string_in_file\`).**
+Even then, use \`file_summary\` first to identify which lines to read.
+
+## Core Rules
+
+1. **Search before acting** — \`search({ query })\` then \`scope_map({ task })\` before ANY code change. If a prior decision exists, follow it.
+2. **Compress, don't read** — \`file_summary\` → \`compact\` → \`digest\`. NEVER raw-read a file to "understand" it.
+3. **Remember** — \`search({ query: "SESSION CHECKPOINT", origin: "curated" })\` at session start. \`remember()\` decisions at session end.
+4. **Validate** — \`check({})\` + \`test_run({})\` before presenting changes. \`blast_radius({ changed_files })\` for impact.
+5. **Lifecycle** — Check \`status({})\` first. If onboard not run, run \`onboard({ path: "." })\`. After implementation, \`reindex({})\` + \`produce_knowledge({})\`. At session end, \`remember()\` checkpoint.
+
+## User Interaction Rules
+
+When you need to explain something or ask for user input:
+
+| Situation | Method | Details |
+|-----------|--------|---------|
+| Simple explanation + question | **Elicitation** | Text-only context is sufficient; ask via elicitation fields |
+| Rich content + question | **\`present\` (html)** + **Elicitation** | Use \`present({ format: "html" })\` for visual explanation, then elicitation for user input |
+| Complex visual + interaction | **\`present\` (browser)** | Use \`present({ format: "browser" })\` for full HTML dashboard; confirmations/selections can use browser actions, other input uses elicitation |
+
+**Rules:**
+- Never dump long tables or complex visuals as plain text — use \`present\` to render them
+- Confirmation selections (yes/no, pick from list) can be handled inside browser mode via actions
+- Free-form text input always goes through elicitation, even when using \`present\` for the explanation
+- Prefer the simplest method that adequately conveys the information
+
+## Custom Agents
+
+This project has specialized agents in \`.github/agents/\`. Use them instead of built-in modes:
+
+| Category | Agents | Purpose |
+|----------|--------|---------|
+| Orchestration | **Orchestrator**, **Planner** | Lifecycle conductor, TDD implementation plans |
+| Implementation | **Implementer**, **Frontend**, **Refactor** | Code writing, UI/UX, cleanup |
+| Diagnostics | **Debugger**, **Security** | Issue tracing, vulnerability analysis |
+| Research | **Researcher-Alpha/Beta/Gamma/Delta** | Multi-model deep investigation |
+| Review | **Code-Reviewer-Alpha/Beta**, **Architect-Reviewer-Alpha/Beta** | Dual-perspective code and architecture review |
+| Exploration | **Explorer** | Rapid codebase navigation |
+| Documentation | **Documenter** | Comprehensive project docs |
+
+Check \`.github/agents/\` for the full list of available agents.
+`}function t(e,t){return`# ${e} — Agent Instructions
+
+## KB MCP Server (\`${t}\`)
+
+67 tools for search, code analysis, persistent memory, validation, and context compression.
+Load them: \`tool_search_tool_regex({ pattern: "knowledge-bas" })\`
+
+### Skills Reference
+
+| Context | Skill | Load when |
+|---------|-------|----------|
+| KB search, analysis, memory | \`knowledge-base\` | **Always load at session start.** Tool signatures, workflows, session protocol. |
+| Brainstorming & design | \`brainstorming\` | Before any creative/design work — new features, components, behavior changes. |
+| Session context preservation | \`session-handoff\` | Context window filling up, session ending, or major milestone completed. |
+| Requirements scoring | \`requirements-clarity\` | Before planning vague or complex features — score 0-100 until \u2265 90. |
+| Engineering lessons | \`lesson-learned\` | After completing work — extract principles from git diffs. |
+| Architecture diagrams | \`c4-architecture\` | When documenting or reviewing architecture — C4 Mermaid diagrams. |
+| Architecture decisions | \`adr-skill\` | When making non-trivial technical decisions — executable ADRs. |
+| Rich presentation | \`present\` | When presenting dashboards, charts, tables, or complex visual content to users. |
+
+### Tool Categories
+
+| Category | Tools | Purpose |
+|----------|-------|---------|
+| Search & Discovery | \`search\`, \`find\`, \`symbol\`, \`trace\`, \`scope_map\`, \`lookup\`, \`dead_symbols\`, \`file_summary\` | Find code, symbols, data flow, reading plans |
+| Code Analysis | \`analyze_structure\`, \`analyze_dependencies\`, \`analyze_symbols\`, \`analyze_patterns\`, \`analyze_entry_points\`, \`analyze_diagram\`, \`blast_radius\` | Structure, deps, patterns, impact |
+| Knowledge | \`remember\`, \`read\`, \`update\`, \`forget\`, \`list\`, \`produce_knowledge\` | Persistent cross-session memory |
+| Execution | \`check\`, \`test_run\`, \`eval\`, \`batch\`, \`audit\` | Typecheck, lint, test, run code |
+| Context Compression | \`compact\`, \`digest\`, \`stratum_card\`, \`workset\`, \`stash\`, \`checkpoint\`, \`restore\` | Reduce tokens, manage working sets |
+| FORGE | \`forge_ground\`, \`forge_classify\`, \`evidence_map\` | Quality gates for complex tasks |
+| Code Manipulation | \`rename\`, \`codemod\`, \`diff_parse\`, \`data_transform\` | Safe renames, transforms |
+| Web & API | \`web_fetch\`, \`web_search\`, \`http\` | Fetch pages, search web |
+| Lanes | \`lane\` | Isolated file copies for parallel exploration |
+| Git & Environment | \`git_context\`, \`process\`, \`watch\`, \`delegate\` | Git info, process management |
+| Utilities | \`regex_test\`, \`encode\`, \`measure\`, \`changelog\`, \`schema_validate\`, \`snippet\`, \`parse_output\`, \`env\`, \`time\` | Regex, encoding, metrics, output parsing |
+| Presentation | \`present\` | Rich dashboards, charts, tables, timelines |
+| Brainstorming | \`brainstorm\` | Interactive ideation sessions with structured output |
+| System | \`status\`, \`reindex\`, \`health\`, \`guide\`, \`onboard\`, \`graph\`, \`queue\`, \`replay\` | Index management, knowledge graph |
+
+---
+
+## How to Read Code (Decision Tree)
+
+\`\`\`
+Need to understand a file?
+\u251C\u2500 Just structure?     \u2192 file_summary (exports, imports, functions \u2014 ~50 tokens)
+\u251C\u2500 Specific section?   \u2192 compact({ path, query }) \u2014 5-20x token reduction
+\u251C\u2500 Multiple files?     \u2192 digest (multi-source compression)
+\u251C\u2500 Repeated reference? \u2192 stratum_card (reusable T1/T2 card)
+\u2514\u2500 Need exact lines to EDIT? \u2192 read_file (ONLY acceptable use)
+\`\`\`
+
+**Rules:**
+1. NEVER \`read_file\` a file >50 lines to "understand" it — use \`file_summary\` or \`compact\`
+2. NEVER \`grep_search\` or \`semantic_search\` — use \`search\` (hybrid across >12k indexed records)
+3. NEVER \`run_in_terminal\` for tsc/lint/test — use \`check\` / \`test_run\`
+4. \`read_file\` is ONLY for getting exact lines before \`replace_string_in_file\`
+
+---
+
+## Session Protocol
+
+### Start (do ALL)
+\`\`\`
+status({})                                                    # Check KB health + onboard state
+# If onboard not run → onboard({ path: "." })                # First-time codebase analysis
+list()                                                        # See stored knowledge
+search({ query: "SESSION CHECKPOINT", origin: "curated" })    # Resume prior work
+\`\`\`
+
+### During
+| Situation | Tool |
+|-----------|------|
+| Intermediate result | \`stash({ key, value })\` |
+| Milestone completed | \`checkpoint({ action: "save", name })\` |
+| Architecture decision made | \`remember({ title, content, category: "decisions" })\` |
+| Pattern discovered | \`remember({ title, content, category: "patterns" })\` |
+| About to propose new approach | \`search({ query })\` — check if already decided |
+
+### After Implementation (do ALL)
+\`\`\`
+check({})                                                      # Typecheck + lint
+test_run({})                                                   # Run tests
+blast_radius({ changed_files: ["..."] })                       # Impact analysis
+reindex({})                                                    # Background refresh (non-blocking)
+produce_knowledge({ path: "." })                               # Regenerate codebase analysis
+remember({ title: "Session checkpoint: ...", ... })            # Persist decisions
+\`\`\`
+
+### End (MUST do)
+\`\`\`
+remember({ title: "Session checkpoint: <topic>", content: "<decisions, blockers, next steps>", category: "conventions" })
+\`\`\`
+For long sessions or context approaching capacity, use the \`session-handoff\` skill to create a structured handoff document.
+
+---
+
+## Search Modes
+
+| Mode | When | Example |
+|------|------|---------|
+| \`hybrid\` (default) | General queries | \`search({ query: "error handling" })\` |
+| \`semantic\` | Conceptual | \`search({ query: "retry with backoff", search_mode: "semantic" })\` |
+| \`keyword\` | Exact identifiers | \`search({ query: "CircuitBreaker", search_mode: "keyword" })\` |
+
+---
+
+## Workflow Chains
+
+**Planning:** \`search\` → \`scope_map\` → \`file_summary\` per file → \`compact\` for detail → \`workset({ action: "save" })\`
+
+**Bug investigation:** \`parse_output\` → \`symbol\` → \`trace({ direction: "backward" })\` → \`blast_radius\`
+
+**Codebase onboarding:** \`onboard({ path: "." })\` → \`produce_knowledge({ path: "src/" })\` → \`remember\`
+
+**After implementation:** \`check\` → \`test_run\` → \`blast_radius\` → \`reindex\` → \`produce_knowledge\` → \`remember\`
+
+**Complex tasks (FORGE):** \`forge_classify({ task })\` → \`forge_ground({ task })\` → \`evidence_map({ claims })\`
+
+**Quality iteration:** \`check\` → \`test_run\` → \`evidence_map({ action: "gate" })\` → fix → re-gate (max 3 rounds)
+`}export{t as buildAgentsMd,e as buildCopilotInstructions};

package/packages/cli/dist/commands/init/user.d.ts

@@ -0,0 +1,61 @@
+//#region packages/cli/src/commands/init/user.d.ts
+/**
+ * `aikit init --user` — configure KB as a user-level MCP server.
+ *
+ * Auto-detects all installed IDEs, writes user-level mcp.json for each,
+ * installs skills to a user-level location, and creates the shared data store.
+ */
+/** Represents a user-level IDE config location. */
+interface UserLevelIdePath {
+  ide: string;
+  configDir: string;
+  mcpConfigPath: string;
+  /**
+   * User-level scaffold root for agents/prompts/skills.
+   * VS Code: ~/.copilot, Claude Code: ~/.claude, Cursor: ~/.cursor, Windsurf: ~/.windsurf.
+   * Null if the IDE has no user-level scaffold support.
+   */
+  globalScaffoldRoot: string | null;
+  /**
+   * User-level instruction file root (may differ from scaffold root).
+   * VS Code uses ~/.copilot/instructions/ for .instructions.md files.
+   * When null, falls back to globalScaffoldRoot.
+   */
+  instructionsRoot: string | null;
+}
+/**
+ * Detect all installed IDEs by checking if their user-level config directory exists.
+ */
+declare function detectInstalledIdes(): UserLevelIdePath[];
+/**
+ * Write or merge the KB server entry into a user-level mcp.json.
+ * Preserves all existing non-KB entries. Backs up existing file before writing.
+ */
+declare function writeUserLevelMcpConfig(idePath: UserLevelIdePath, serverName: string, force?: boolean): void;
+/**
+ * Merge aikit-related settings into a VS Code-family IDE's settings.json.
+ * Preserves all existing settings. Only writes keys defined in VSCODE_SETTINGS.
+ */
+declare function writeVscodeSettings(idePath: UserLevelIdePath, force?: boolean): void;
+/**
+ * Install agents, prompts, skills, and instruction files to each detected IDE's
+ * global scaffold root.
+ *
+ * Each IDE has its own global discovery path:
+ *   - VS Code / VSCodium:  ~/.copilot/ (agents/, prompts/, skills/, instructions/)
+ *   - Claude Code:         ~/.claude/ (CLAUDE.md, agents/)
+ *   - Cursor:              ~/.cursor/ (rules/kb.mdc, agents/, prompts/, skills/)
+ *   - Windsurf:            ~/.windsurf/ (rules/kb.md, agents/, prompts/, skills/)
+ *
+ * Multiple IDEs may share the same root (e.g. VS Code + VSCodium both use ~/.copilot/).
+ * We deduplicate scaffold files but generate IDE-specific instruction files.
+ */
+declare function installGlobalScaffold(pkgRoot: string, ides: UserLevelIdePath[], serverName: string, version: string, force?: boolean): void;
+/**
+ * Main orchestrator for `aikit init --user`.
+ */
+declare function initUser(options: {
+  force: boolean;
+}): Promise<void>;
+//#endregion
+export { UserLevelIdePath, detectInstalledIdes, initUser, installGlobalScaffold, writeUserLevelMcpConfig, writeVscodeSettings };

package/packages/cli/dist/commands/init/user.js

@@ -0,0 +1,5 @@
+import{MCP_SERVER_ENTRY as e,SERVER_NAME as t,SKILL_NAMES as n,VSCODE_SETTINGS as r}from"./constants.js";import{buildAgentsMd as i,buildCopilotInstructions as a}from"./templates.js";import{smartCopySubdir as o}from"./scaffold.js";import{existsSync as s,mkdirSync as c,readFileSync as l,writeFileSync as u}from"node:fs";import{dirname as d,resolve as f}from"node:path";import{fileURLToPath as p}from"node:url";import{getGlobalDataDir as m,saveRegistry as h}from"../../../../core/dist/index.js";import{homedir as g}from"node:os";function _(){let e=g(),t=process.platform,n=[],r=f(e,`.copilot`),i=f(r,`instructions`),a=f(e,`.claude`),o=f(e,`.cursor`),c=f(e,`.windsurf`);if(t===`win32`){let t=process.env.APPDATA??f(e,`AppData`,`Roaming`);n.push({ide:`VS Code`,configDir:f(t,`Code`,`User`),mcpConfigPath:f(t,`Code`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VS Code Insiders`,configDir:f(t,`Code - Insiders`,`User`),mcpConfigPath:f(t,`Code - Insiders`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VSCodium`,configDir:f(t,`VSCodium`,`User`),mcpConfigPath:f(t,`VSCodium`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`Cursor`,configDir:f(t,`Cursor`,`User`),mcpConfigPath:f(t,`Cursor`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Cursor Nightly`,configDir:f(t,`Cursor Nightly`,`User`),mcpConfigPath:f(t,`Cursor Nightly`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Windsurf`,configDir:f(t,`Windsurf`,`User`),mcpConfigPath:f(t,`Windsurf`,`User`,`mcp.json`),globalScaffoldRoot:c,instructionsRoot:null})}else if(t===`darwin`){let t=f(e,`Library`,`Application Support`);n.push({ide:`VS Code`,configDir:f(t,`Code`,`User`),mcpConfigPath:f(t,`Code`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VS Code Insiders`,configDir:f(t,`Code - Insiders`,`User`),mcpConfigPath:f(t,`Code - Insiders`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VSCodium`,configDir:f(t,`VSCodium`,`User`),mcpConfigPath:f(t,`VSCodium`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`Cursor`,configDir:f(t,`Cursor`,`User`),mcpConfigPath:f(t,`Cursor`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Cursor Nightly`,configDir:f(t,`Cursor Nightly`,`User`),mcpConfigPath:f(t,`Cursor Nightly`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Windsurf`,configDir:f(t,`Windsurf`,`User`),mcpConfigPath:f(t,`Windsurf`,`User`,`mcp.json`),globalScaffoldRoot:c,instructionsRoot:null})}else{let t=process.env.XDG_CONFIG_HOME??f(e,`.config`);n.push({ide:`VS Code`,configDir:f(t,`Code`,`User`),mcpConfigPath:f(t,`Code`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VS Code Insiders`,configDir:f(t,`Code - Insiders`,`User`),mcpConfigPath:f(t,`Code - Insiders`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`VSCodium`,configDir:f(t,`VSCodium`,`User`),mcpConfigPath:f(t,`VSCodium`,`User`,`mcp.json`),globalScaffoldRoot:r,instructionsRoot:i},{ide:`Cursor`,configDir:f(t,`Cursor`,`User`),mcpConfigPath:f(t,`Cursor`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Cursor Nightly`,configDir:f(t,`Cursor Nightly`,`User`),mcpConfigPath:f(t,`Cursor Nightly`,`User`,`mcp.json`),globalScaffoldRoot:o,instructionsRoot:null},{ide:`Windsurf`,configDir:f(t,`Windsurf`,`User`),mcpConfigPath:f(t,`Windsurf`,`User`,`mcp.json`),globalScaffoldRoot:c,instructionsRoot:null})}return n.push({ide:`Claude Code`,configDir:f(e,`.claude`),mcpConfigPath:f(e,`.claude`,`mcp.json`),globalScaffoldRoot:a,instructionsRoot:null}),n.filter(e=>s(e.configDir))}function v(t,n,r=!1){let{mcpConfigPath:i,configDir:a}=t,o={...e},d={};if(s(i)){try{let e=l(i,`utf-8`);d=JSON.parse(e)}catch{let e=`${i}.bak`;u(e,l(i,`utf-8`),`utf-8`),console.log(`  Backed up invalid ${i} to ${e}`),d={}}if((d.servers??d.mcpServers??{})[n]&&!r){console.log(`  ${t.ide}: ${n} already configured (use --force to update)`);return}}let f=new Set([`VS Code`,`VS Code Insiders`,`VSCodium`,`Windsurf`]).has(t.ide)?`servers`:`mcpServers`,p=d[f]??{};p[n]=o,d[f]=p,c(a,{recursive:!0}),u(i,`${JSON.stringify(d,null,2)}\n`,`utf-8`),console.log(`  ${t.ide}: configured ${n} in ${i}`)}const y=new Set([`VS Code`,`VS Code Insiders`,`VSCodium`]);function b(e,t=!1){if(!y.has(e.ide))return;let n=f(e.configDir,`settings.json`),i={};if(s(n))try{let e=l(n,`utf-8`);i=JSON.parse(e)}catch{console.log(`  ${e.ide}: skipped settings.json (invalid JSON)`);return}let a=!1;for(let[e,n]of Object.entries(r))if(typeof n==`object`&&n){let t=typeof i[e]==`object`&&i[e]!==null?i[e]:{},r={...t,...n};JSON.stringify(r)!==JSON.stringify(t)&&(i[e]=r,a=!0)}else (t||!(e in i))&&(i[e]=n,a=!0);a&&(u(n,`${JSON.stringify(i,null,2)}\n`,`utf-8`),console.log(`  ${e.ide}: updated settings.json`))}function x(e,t,r,l,d=!1){let p=new Set;for(let e of t)e.globalScaffoldRoot&&p.add(e.globalScaffoldRoot);if(p.size===0){console.log(`  No IDEs with global scaffold support detected.`);return}let m=f(e,`scaffold`,`general`);for(let e of p){o(m,e,`agents`,l,d),o(m,e,`prompts`,l,d);let t=0;for(let r of n)s(f(m,`skills`,r))&&(o(m,e,`skills/${r}`,l,d),t++);console.log(`  ${e}: scaffold updated (${t} skills)`)}let h=new Set,g=a(`aikit`,r),_=i(`aikit`,r);for(let e of t){if(!e.globalScaffoldRoot)continue;let t=e.globalScaffoldRoot;if(e.ide===`Claude Code`){let e=f(t,`CLAUDE.md`);u(e,`${g}\n---\n\n${_}`,`utf-8`),h.add(e)}else if(e.ide===`VS Code`||e.ide===`VS Code Insiders`||e.ide===`VSCodium`){let n=e.instructionsRoot??t;c(n,{recursive:!0});let r=f(n,`kb.instructions.md`);h.has(r)||(u(r,`---\napplyTo: "**"\n---\n\n${g}\n---\n\n${_}`,`utf-8`),h.add(r))}else if(e.ide===`Cursor`||e.ide===`Cursor Nightly`){let e=f(t,`rules`);c(e,{recursive:!0});let n=f(e,`kb.mdc`);h.has(n)||(u(n,`${g}\n---\n\n${_}`,`utf-8`),h.add(n))}else if(e.ide===`Windsurf`){let e=f(t,`rules`);c(e,{recursive:!0});let n=f(e,`kb.md`);h.has(n)||(u(n,`${g}\n---\n\n${_}`,`utf-8`),h.add(n))}}h.size>0&&console.log(`  Instruction files: ${[...h].join(`, `)}`)}async function S(e){let n=t,r=f(d(p(import.meta.url)),`..`,`..`,`..`,`..`,`..`,`package.json`),i=JSON.parse(l(r,`utf-8`)).version;console.log(`Initializing @vpxa/aikit v${i}...\n`);let a=m();c(a,{recursive:!0}),console.log(`  Global data store: ${a}`),h({version:1,workspaces:{}}),console.log(`  Created registry.json`);let o=_();if(o.length===0)console.log(`
+  No supported IDEs detected. You can manually add the MCP server config.`);else{console.log(`\n  Detected ${o.length} IDE(s):`);for(let t of o)v(t,n,e.force),b(t,e.force)}let s=f(d(p(import.meta.url)),`..`,`..`,`..`,`..`,`..`);console.log(`
+  Installing scaffold files:`),x(s,o,n,i,e.force),console.log(`
+User-level KB installation complete!`),console.log(`
+Next steps:`),console.log(`  1. Open any workspace in your IDE`),console.log(`  2. The KB server will auto-start and index the workspace`),console.log(`  3. Agents, prompts, skills & instructions are available globally`),console.log(`  4. No per-workspace init needed — just open a project and start coding`)}export{_ as detectInstalledIdes,S as initUser,x as installGlobalScaffold,v as writeUserLevelMcpConfig,b as writeVscodeSettings};

package/packages/cli/dist/commands/knowledge.d.ts

@@ -0,0 +1,6 @@
+import { Command } from "../types.js";
+
+//#region packages/cli/src/commands/knowledge.d.ts
+declare const knowledgeCommands: Command[];
+//#endregion
+export { knowledgeCommands };

package/packages/cli/dist/commands/knowledge.js

@@ -0,0 +1 @@
+import{ctx as e}from"../context.js";import{extractNumFlag as t,extractStrFlag as n,readStdin as r,splitCsv as i}from"../helpers.js";import{compact as a}from"../../../tools/dist/index.js";const o=[{name:`remember`,description:`Store curated knowledge`,usage:`aikit remember <title> --category <cat> [--tags tag1,tag2]`,run:async t=>{let a=n(t,`--category`,``).trim(),o=i(n(t,`--tags`,``)),s=t.shift()?.trim()??``,c=await r(),l=c.trim().length>0?c:t.join(` `).trim();(!s||!a||!l.trim())&&(console.error(`Usage: aikit remember <title> --category <cat> [--tags tag1,tag2]`),process.exit(1));let{curated:u}=await e(),d=await u.remember(s,l,a,o);console.log(`Stored curated entry`),console.log(`  Path: ${d.path}`),console.log(`  Category: ${a}`),o.length>0&&console.log(`  Tags: ${o.join(`, `)}`)}},{name:`forget`,description:`Remove a curated entry`,usage:`aikit forget <path> --reason <reason>`,run:async t=>{let r=n(t,`--reason`,``).trim(),i=t.shift()?.trim()??``;(!i||!r)&&(console.error(`Usage: aikit forget <path> --reason <reason>`),process.exit(1));let{curated:a}=await e(),o=await a.forget(i,r);console.log(`Removed curated entry: ${o.path}`)}},{name:`read`,description:`Read a curated entry`,usage:`aikit read <path>`,run:async t=>{let n=t.shift()?.trim()??``;n||(console.error(`Usage: aikit read <path>`),process.exit(1));let{curated:r}=await e(),i=await r.read(n);console.log(i.title),console.log(`─`.repeat(60)),console.log(`Path: ${i.path}`),console.log(`Category: ${i.category}`),console.log(`Version: ${i.version}`),console.log(`Tags: ${i.tags.length>0?i.tags.join(`, `):`None`}`),console.log(``),console.log(i.content)}},{name:`list`,description:`List curated entries`,usage:`aikit list [--category <cat>] [--tag <tag>]`,run:async t=>{let r=n(t,`--category`,``).trim()||void 0,i=n(t,`--tag`,``).trim()||void 0,{curated:a}=await e(),o=await a.list({category:r,tag:i});if(o.length===0){console.log(`No curated entries found.`);return}console.log(`Curated entries (${o.length})`),console.log(`─`.repeat(60));for(let e of o){console.log(e.path),console.log(`  ${e.title}`),console.log(`  Category: ${e.category} | Version: ${e.version}`),console.log(`  Tags: ${e.tags.length>0?e.tags.join(`, `):`None`}`);let t=e.contentPreview.replace(/\s+/g,` `).trim();t&&console.log(`  Preview: ${t}`),console.log(``)}}},{name:`update`,description:`Update a curated entry`,usage:`aikit update <path> --reason <reason>`,run:async t=>{let i=n(t,`--reason`,``).trim(),a=t.shift()?.trim()??``,o=await r();(!a||!i||!o.trim())&&(console.error(`Usage: aikit update <path> --reason <reason>`),process.exit(1));let{curated:s}=await e(),c=await s.update(a,o,i);console.log(`Updated curated entry`),console.log(`  Path: ${c.path}`),console.log(`  Version: ${c.version}`)}},{name:`compact`,description:`Compress text for context`,usage:`aikit compact <query> [--path <file>] [--max-chars N] [--segmentation paragraph|sentence|line]`,run:async i=>{let o=t(i,`--max-chars`,3e3),s=n(i,`--path`,``).trim()||void 0,c=n(i,`--segmentation`,`paragraph`),l=i.join(` `).trim(),u=s?void 0:await r();(!l||!s&&!u?.trim())&&(console.error(`Usage: aikit compact <query> --path <file>  OR  cat file | aikit compact <query>`),process.exit(1));let{embedder:d}=await e(),f=await a(d,{text:u,path:s,query:l,maxChars:o,segmentation:c});console.log(`Compressed ${f.originalChars} chars to ${f.compressedChars} chars`),console.log(`Ratio: ${(f.ratio*100).toFixed(1)}% | Segments: ${f.segmentsKept}/${f.segmentsTotal}`),console.log(``),console.log(f.text)}}];export{o as knowledgeCommands};

package/packages/cli/dist/commands/search.d.ts

@@ -0,0 +1,6 @@
+import { Command } from "../types.js";
+
+//#region packages/cli/src/commands/search.d.ts
+declare const searchCommands: Command[];
+//#endregion
+export { searchCommands };

package/packages/cli/dist/commands/search.js

@@ -0,0 +1 @@
+import{ctx as e}from"../context.js";import{extractNumFlag as t,extractStrFlag as n,formatFocusRanges as r,printDeadSymbolsResult as i,printExamplesResult as a,printSymbolInfo as o,printTraceResult as s,rrf as c}from"../helpers.js";import{find as l,findDeadSymbols as u,findExamples as d,scopeMap as f,symbol as p,trace as m}from"../../../tools/dist/index.js";const h=[{name:`search`,description:`Search the knowledge base`,usage:`aikit search <query> [--limit N] [--mode hybrid|semantic|keyword] [--graph-hops 0-3]`,run:async r=>{let i=t(r,`--limit`,5),a=n(r,`--mode`,`hybrid`),o=t(r,`--graph-hops`,0),s=r.join(` `).trim();s||(console.error(`Usage: aikit search <query>`),process.exit(1));let{embedder:l,store:u,graphStore:d}=await e(),f=await l.embedQuery(s),p;if(a===`keyword`)p=await u.ftsSearch(s,{limit:i});else if(a===`semantic`)p=await u.search(f,{limit:i});else{let[e,t]=await Promise.all([u.search(f,{limit:i*2}),u.ftsSearch(s,{limit:i*2}).catch(()=>[])]);p=c(e,t).slice(0,i)}if(p.length===0){console.log(`No results found.`);return}for(let{record:e,score:t}of p){console.log(`\n${`─`.repeat(60)}`),console.log(`[${(t*100).toFixed(1)}%] ${e.sourcePath}:${e.startLine}-${e.endLine}`),console.log(`  Type: ${e.contentType} | Origin: ${e.origin}`),e.tags.length>0&&console.log(`  Tags: ${e.tags.join(`, `)}`),console.log(``);let n=e.content.length>500?`${e.content.slice(0,500)}...`:e.content;console.log(n)}if(console.log(`\n${`─`.repeat(60)}`),console.log(`${p.length} result(s) found.`),o>0&&p.length>0)try{let{graphAugmentSearch:e}=await import(`../../../tools/dist/index.js`),t=(await e(d,p.map(e=>({recordId:e.record.id,score:e.score,sourcePath:e.record.sourcePath})),{hops:o,maxPerHit:5})).filter(e=>e.graphContext.nodes.length>0);if(t.length>0){console.log(`\nGraph context (${o} hop${o>1?`s`:``}):\n`);for(let e of t){console.log(`  ${e.sourcePath}:`);for(let t of e.graphContext.nodes.slice(0,5))console.log(`    → ${t.name} (${t.type})`);for(let t of e.graphContext.edges.slice(0,5))console.log(`    → ${t.fromId} --[${t.type}]--> ${t.toId}`)}}}catch(e){console.error(`[graph] augmentation failed: ${e.message}`)}}},{name:`find`,description:`Run federated search across indexed content and files`,usage:`aikit find [query] [--glob <pattern>] [--pattern <regex>] [--limit N]`,run:async r=>{let i=t(r,`--limit`,10),a=n(r,`--glob`,``).trim()||void 0,o=n(r,`--pattern`,``).trim()||void 0,s=r.join(` `).trim()||void 0;!s&&!a&&!o&&(console.error(`Usage: aikit find [query] [--glob <pattern>] [--pattern <regex>] [--limit N]`),process.exit(1));let{embedder:c,store:u}=await e(),d=await l(c,u,{query:s,glob:a,pattern:o,limit:i});if(d.results.length===0){console.log(`No matches found.`);return}console.log(`Strategies: ${d.strategies.join(`, `)}`),console.log(`Results: ${d.results.length} shown (${d.totalFound} total)`);for(let e of d.results){let t=e.lineRange?`:${e.lineRange.start}-${e.lineRange.end}`:``;console.log(`\n[${e.source}] ${e.path}${t}`),console.log(`  Score: ${(e.score*100).toFixed(1)}%`),e.preview&&console.log(`  ${e.preview.replace(/\s+/g,` `).trim()}`)}}},{name:`scope-map`,description:`Generate a reading plan for a task`,usage:`aikit scope-map <task> [--max-files N]`,run:async n=>{let i=t(n,`--max-files`,15),a=n.join(` `).trim();a||(console.error(`Usage: aikit scope-map <task> [--max-files N]`),process.exit(1));let{embedder:o,store:s}=await e(),c=await f(o,s,{task:a,maxFiles:i});console.log(`Task: ${c.task}`),console.log(`Files: ${c.files.length}`),console.log(`Estimated tokens: ${c.totalEstimatedTokens}`),console.log(``),console.log(`Reading order:`);for(let e of c.readingOrder)console.log(`  ${e}`);for(let[e,t]of c.files.entries())console.log(`\n${e+1}. ${t.path}`),console.log(`   Relevance: ${(t.relevance*100).toFixed(1)}% | Tokens: ${t.estimatedTokens}`),console.log(`   Why: ${t.reason}`),t.focusRanges.length>0&&console.log(`   Focus: ${r(t.focusRanges)}`)}},{name:`symbol`,description:`Resolve a symbol definition, imports, and references`,usage:`aikit symbol <name> [--limit N]`,run:async n=>{let r=t(n,`--limit`,20),i=n.join(` `).trim();i||(console.error(`Usage: aikit symbol <name> [--limit N]`),process.exit(1));let{embedder:a,store:s}=await e();o(await p(a,s,{name:i,limit:r}))}},{name:`trace`,description:`Trace forward/backward flow for a symbol or file location`,usage:`aikit trace <start> [--direction forward|backward|both] [--max-depth N]`,run:async r=>{let i=n(r,`--direction`,`both`).trim()||`both`,a=t(r,`--max-depth`,3),o=r.join(` `).trim();(!o||![`forward`,`backward`,`both`].includes(i))&&(console.error(`Usage: aikit trace <start> [--direction forward|backward|both] [--max-depth N]`),process.exit(1));let{embedder:c,store:l}=await e();s(await m(c,l,{start:o,direction:i,maxDepth:a}))}},{name:`examples`,description:`Find real code examples of a symbol or pattern`,usage:`aikit examples <query> [--limit N] [--content-type type]`,run:async r=>{let i=t(r,`--limit`,5),o=n(r,`--content-type`,``).trim()||void 0,s=r.join(` `).trim();s||(console.error(`Usage: aikit examples <query> [--limit N] [--content-type type]`),process.exit(1));let{embedder:c,store:l}=await e();a(await d(c,l,{query:s,limit:i,contentType:o}))}},{name:`dead-symbols`,description:`Find exported symbols that appear to be unused`,usage:`aikit dead-symbols [--limit N]`,run:async n=>{let r=t(n,`--limit`,100),{embedder:a,store:o}=await e();i(await u(a,o,{limit:r}))}},{name:`lookup`,description:`Look up indexed content by record ID or source path`,usage:`aikit lookup <id>`,run:async t=>{let n=t.join(` `).trim();n||(console.error(`Usage: aikit lookup <id>`),process.exit(1));let{store:r}=await e(),i=await r.getById(n);if(i){console.log(i.id),console.log(`─`.repeat(60)),console.log(`Path: ${i.sourcePath}`),console.log(`Chunk: ${i.chunkIndex+1}/${i.totalChunks}`),console.log(`Lines: ${i.startLine}-${i.endLine}`),console.log(`Type: ${i.contentType} | Origin: ${i.origin}`),i.tags.length>0&&console.log(`Tags: ${i.tags.join(`, `)}`),console.log(``),console.log(i.content);return}let a=await r.getBySourcePath(n);if(a.length===0){console.log(`No indexed content found for: ${n}`);return}a.sort((e,t)=>e.chunkIndex-t.chunkIndex),console.log(n),console.log(`─`.repeat(60)),console.log(`Chunks: ${a.length} | Type: ${a[0].contentType}`);for(let e of a){let t=e.startLine?` (lines ${e.startLine}-${e.endLine})`:``;console.log(`\nChunk ${e.chunkIndex+1}/${e.totalChunks}${t}`),console.log(e.content)}}}];export{h as searchCommands};

package/packages/cli/dist/commands/system.d.ts

@@ -0,0 +1,6 @@
+import { Command } from "../types.js";
+
+//#region packages/cli/src/commands/system.d.ts
+declare const systemCommands: Command[];
+//#endregion
+export { systemCommands };

package/packages/cli/dist/commands/system.js

@@ -0,0 +1,4 @@
+import{ctx as e}from"../context.js";import{executeCliBatchOperation as t,extractStrFlag as n,parseBatchPayload as r,printCheckResult as i,readInput as a}from"../helpers.js";import{dirname as o,resolve as s}from"node:path";import{fileURLToPath as c}from"node:url";import{audit as l,batch as u,check as d,guide as f,health as p,replayClear as m,replayList as h,replayTrim as g}from"../../../tools/dist/index.js";import{fork as _}from"node:child_process";const v=o(c(import.meta.url)),y=[{name:`status`,description:`Show knowledge base index status and statistics`,run:async()=>{let{isUserInstalled:t,getGlobalDataDir:n,computePartitionKey:r,listWorkspaces:i}=await import(`../../../core/dist/index.js`),{existsSync:a}=await import(`node:fs`),o=process.cwd(),c=t(),l=a(s(o,`.vscode`,`mcp.json`)),u,d;if(c&&l)u=`workspace (overrides user-level for this workspace)`,d=s(o,`.aikit-data`);else if(c){let e=r(o);u=a(s(o,`AGENTS.md`))?`user (workspace scaffolded)`:`user (workspace not scaffolded)`,d=s(n(),e)}else u=`workspace`,d=s(o,`.aikit-data`);if(console.log(`Knowledge Base Status`),console.log(`─`.repeat(40)),console.log(`  Mode:     ${u}`),console.log(`  Data:     ${d}`),c&&!l){let e=i();console.log(`  Registry: ${e.length} workspace(s) enrolled`)}try{let{store:t}=await e(),n=await t.getStats(),r=await t.listSourcePaths();console.log(`  Records:  ${n.totalRecords}`),console.log(`  Files:    ${n.totalFiles}`),console.log(`  Indexed:  ${n.lastIndexedAt??`Never`}`),console.log(`  Backend:  ${n.storeBackend}`),console.log(`  Model:    ${n.embeddingModel}`),console.log(``),console.log(`Content Types:`);for(let[e,t]of Object.entries(n.contentTypeBreakdown))console.log(`  ${e}: ${t}`);if(r.length>0){console.log(``),console.log(`Files (${r.length} total):`);for(let e of r.slice(0,20))console.log(`  ${e}`);r.length>20&&console.log(`  ... and ${r.length-20} more`)}}catch{console.log(``),console.log("  Index not available — run `aikit reindex` to index this workspace.")}c&&!l&&!a(s(o,`AGENTS.md`))&&(console.log(``),console.log("  Action: Run `npx @vpxa/aikit init` to add AGENTS.md and copilot-instructions.md"))}},{name:`reindex`,description:`Re-index the knowledge base from configured sources`,usage:`aikit reindex [--full]`,run:async t=>{let n=t.includes(`--full`),{store:r,indexer:i,curated:a,config:o}=await e();console.log(`Indexing sources...`);let s=e=>{e.phase===`chunking`&&e.currentFile&&process.stdout.write(`\r  [${e.filesProcessed+1}/${e.filesTotal}] ${e.currentFile}`),e.phase===`done`&&process.stdout.write(`
+`)},c;n?(console.log(`Dropping existing index for full reindex...`),c=await i.reindexAll(o,s)):c=await i.index(o,s),console.log(`Done: ${c.filesProcessed} files, ${c.chunksCreated} chunks in ${(c.durationMs/1e3).toFixed(1)}s`),console.log(`Building FTS index...`),await r.createFtsIndex(),console.log(`Re-indexing curated entries...`);let l=await a.reindexAll();console.log(`Curated: ${l.indexed} entries restored`)}},{name:`serve`,description:`Start the MCP server (stdio or HTTP)`,usage:`aikit serve [--transport stdio|http] [--port N]`,run:async e=>{let t=s(v,`..`,`..`,`..`,`server`,`dist`,`index.js`),r=n(e,`--transport`,`stdio`),i=n(e,`--port`,`3210`),a=_(t,[],{stdio:r===`stdio`?[`pipe`,`pipe`,`inherit`,`ipc`]:`inherit`,env:{...process.env,AIKIT_TRANSPORT:r,AIKIT_PORT:i}});r===`stdio`&&a.stdin&&a.stdout&&(process.stdin.pipe(a.stdin),a.stdout.pipe(process.stdout)),a.on(`exit`,e=>process.exit(e??0)),process.on(`SIGINT`,()=>a.kill(`SIGINT`)),process.on(`SIGTERM`,()=>a.kill(`SIGTERM`)),await new Promise(()=>{})}},{name:`init`,description:`Initialize a knowledge base in the current directory`,usage:`aikit init [--user|--workspace] [--force] [--guide]`,run:async e=>{let t=e.includes(`--user`),n=e.includes(`--workspace`),r=e.includes(`--guide`),i=e.includes(`--force`);if(t&&n&&(console.error(`Cannot use --user and --workspace together.`),process.exit(1)),r){let{guideProject:e}=await import(`./init/index.js`);await e();return}if(t){let{initUser:e}=await import(`./init/user.js`);await e({force:i})}else if(n){let{initProject:e}=await import(`./init/index.js`);await e({force:i})}else{let{initSmart:e}=await import(`./init/index.js`);await e({force:i})}}},{name:`check`,description:`Run incremental typecheck and lint`,usage:`aikit check [--cwd <dir>] [--files f1,f2] [--skip-types] [--skip-lint] [--detail summary|errors|full]`,run:async e=>{let t=n(e,`--cwd`,``).trim()||void 0,r=n(e,`--files`,``),a=n(e,`--detail`,`full`)||`full`,o=r.split(`,`).map(e=>e.trim()).filter(Boolean),s=!1;e.includes(`--skip-types`)&&(e.splice(e.indexOf(`--skip-types`),1),s=!0);let c=!1;e.includes(`--skip-lint`)&&(e.splice(e.indexOf(`--skip-lint`),1),c=!0);let l=await d({cwd:t,files:o.length>0?o:void 0,skipTypes:s,skipLint:c,detail:a});i(l),l.passed||(process.exitCode=1)}},{name:`batch`,description:`Execute built-in operations from JSON input`,usage:`aikit batch [--file path] [--concurrency N]`,run:async i=>{let o=n(i,`--file`,``).trim()||void 0,s=(()=>{let e=i.indexOf(`--concurrency`);if(e===-1||e+1>=i.length)return 0;let t=Number.parseInt(i.splice(e,2)[1],10);return Number.isNaN(t)?0:t})(),c=await a(o);c.trim()||(console.error(`Usage: aikit batch [--file path] [--concurrency N]`),process.exit(1));let l=r(c),d=s>0?s:l.concurrency,f=l.operations.some(e=>e.type!==`check`)?await e():null,p=await u(l.operations,async e=>t(e,f),{concurrency:d});console.log(JSON.stringify(p,null,2)),p.some(e=>e.status===`error`)&&(process.exitCode=1)}},{name:`health`,description:`Run project health checks on the current directory`,usage:`aikit health [path]`,run:async e=>{let t=p(e.shift());console.log(`Project Health: ${t.path}`),console.log(`─`.repeat(50));for(let e of t.checks){let t=e.status===`pass`?`+`:e.status===`warn`?`~`:`X`;console.log(`  [${t}] ${e.name}: ${e.message}`)}console.log(`─`.repeat(50)),console.log(`Score: ${t.score}% — ${t.summary}`)}},{name:`audit`,description:`Run a unified project audit (structure, deps, patterns, health, dead symbols, check)`,usage:`aikit audit [path] [--checks structure,dependencies,patterns,health,dead_symbols,check,entry_points] [--detail summary|full]`,run:async t=>{let{store:r,embedder:i}=await e(),a=n(t,`--detail`,`summary`)||`summary`,o=n(t,`--checks`,``),s=o?o.split(`,`).map(e=>e.trim()):void 0,c=await l(r,i,{path:t.shift()||`.`,checks:s,detail:a});if(c.ok){if(console.log(c.summary),c.next&&c.next.length>0){console.log(`
+Suggested next steps:`);for(let e of c.next)console.log(`  → ${e.tool}: ${e.reason}`)}}else console.error(c.error?.message??`Audit failed`),process.exitCode=1}},{name:`guide`,description:`Tool discovery — recommend KB tools for a given goal`,usage:`aikit guide <goal> [--max N]`,run:async e=>{let t=e.indexOf(`--max`),n=5;t!==-1&&t+1<e.length&&(n=Number.parseInt(e.splice(t,2)[1],10)||5);let r=e.join(` `).trim();r||(console.error(`Usage: aikit guide <goal> [--max N]`),console.error(`Example: aikit guide "audit this project"`),process.exit(1));let i=f(r,n);console.log(`Workflow: ${i.workflow}`),console.log(`  ${i.description}\n`),console.log(`Recommended tools:`);for(let e of i.tools){let t=e.suggestedArgs?` ${JSON.stringify(e.suggestedArgs)}`:``;console.log(`  ${e.order}. ${e.tool} — ${e.reason}${t}`)}i.alternativeWorkflows.length>0&&console.log(`\nAlternatives: ${i.alternativeWorkflows.join(`, `)}`)}},{name:`replay`,description:`Show recent tool invocation audit trail`,usage:`aikit replay [--last N] [--tool <name>] [--source mcp|cli]`,run:async e=>{let t=h({last:Number.parseInt(e[e.indexOf(`--last`)+1],10)||20,tool:e.includes(`--tool`)?e[e.indexOf(`--tool`)+1]:void 0,source:e.includes(`--source`)?e[e.indexOf(`--source`)+1]:void 0});if(t.length===0){console.log(`No replay entries. Activity is logged when tools are invoked.`);return}console.log(`Replay Log (${t.length} entries)\n`);for(let e of t){let t=e.ts.split(`T`)[1]?.split(`.`)[0]??e.ts,n=e.status===`ok`?`✓`:`✗`;console.log(`${t} ${n} ${e.tool} (${e.durationMs}ms) [${e.source}]`),console.log(`  in:  ${e.input}`),console.log(`  out: ${e.output}`)}g().catch(()=>{})}},{name:`replay-clear`,description:`Clear the replay audit trail`,run:async()=>{m(),console.log(`Replay log cleared.`)}},{name:`tui`,description:`Launch interactive terminal dashboard (human monitoring)`,run:async()=>{try{let{launch:t}=await import(`../../../tui/dist/index.js`),{DirectKBClient:n}=await import(`../../../client/dist/index.js`),{store:r,embedder:i,graphStore:a,curated:o}=await e();t(new n({store:r,embedder:i,graphStore:a,listCurated:async()=>(await o.list()).map(e=>({...e,content:e.contentPreview})),readCurated:e=>o.read(e)}))}catch(e){throw e.code===`ERR_MODULE_NOT_FOUND`&&(console.error(`TUI requires ink and react. Install them with:
+  pnpm add -D ink react @types/react`),process.exit(1)),e}}},{name:`dashboard`,description:`Launch web dashboard for knowledge graph visualization`,usage:`aikit dashboard [--port <port>] [--no-open]`,run:async e=>{let t=e.indexOf(`--port`),n=t!==-1&&e[t+1]?Number.parseInt(e[t+1],10):3210,r=Number.isFinite(n)?n:3210,i=e.includes(`--no-open`);console.log(`Starting KB server on port ${r}...`);let{spawn:a}=await import(`node:child_process`),{platform:o}=await import(`node:os`),c=s(v,`..`,`..`,`..`,`server`,`dist`,`index.js`),l=a(process.execPath,[c,`--transport`,`http`,`--port`,String(r)],{stdio:[`ignore`,`pipe`,`pipe`],env:{...process.env,AIKIT_TRANSPORT:`http`,AIKIT_PORT:String(r)}}),u=`http://localhost:${r}/_dashboard/`,d=`http://localhost:${r}/health`,f=!1;for(let e=0;e<30;e+=1){try{if((await fetch(d)).ok){f=!0;break}}catch{}await new Promise(e=>setTimeout(e,1e3))}if(f||(console.error(`Server failed to start within 30 seconds.`),l.kill(),process.exit(1)),console.log(`KB Dashboard: ${u}`),console.log(`Press Ctrl+C to stop.`),!i){let e=o();e===`win32`?a(`cmd`,[`/c`,`start`,``,u],{stdio:`ignore`,detached:!0}).unref():a(e===`darwin`?`open`:`xdg-open`,[u],{stdio:`ignore`,detached:!0}).unref()}let p=()=>{l.kill(),process.exit(0)};process.on(`SIGINT`,p),process.on(`SIGTERM`,p),await new Promise(e=>{l.on(`exit`,()=>e())})}}];export{y as systemCommands};

package/packages/cli/dist/commands/upgrade.d.ts

@@ -0,0 +1,6 @@
+import { Command } from "../types.js";
+
+//#region packages/cli/src/commands/upgrade.d.ts
+declare const upgradeCommands: Command[];
+//#endregion
+export { upgradeCommands };

package/packages/cli/dist/commands/upgrade.js

@@ -0,0 +1 @@
+import{SKILL_NAMES as e}from"./init/constants.js";import{existsSync as t,readFileSync as n}from"node:fs";import{dirname as r,resolve as i}from"node:path";import{fileURLToPath as a}from"node:url";const o=[{name:`upgrade`,description:`Upgrade KB agents, prompts, and skills to the latest version (user-level and workspace-level)`,usage:`kb upgrade`,run:async()=>{let{initUser:o}=await import(`./init/user.js`);if(await o({force:!0}),t(i(process.cwd(),`.github`,`.aikit-scaffold.json`))){let{initScaffoldOnly:o}=await import(`./init/index.js`);if(await o({force:!0}),t(i(process.cwd(),`.github`,`skills`))){let{smartCopySkills:t}=await import(`./init/scaffold.js`),o=i(r(a(import.meta.url)),`..`,`..`,`..`,`..`),s=JSON.parse(n(i(o,`package.json`),`utf-8`)).version;t(process.cwd(),o,[...e],s,!0)}}}}];export{o as upgradeCommands};

package/packages/cli/dist/commands/workspace.d.ts

@@ -0,0 +1,6 @@
+import { Command } from "../types.js";
+
+//#region packages/cli/src/commands/workspace.d.ts
+declare const workspaceCommands: Command[];
+//#endregion
+export { workspaceCommands };

package/packages/cli/dist/commands/workspace.js

@@ -0,0 +1 @@
+import{extractStrFlag as e,parseMaybeJsonString as t,printWorkset as n,readStdin as r,splitCsv as i}from"../helpers.js";import{addToWorkset as a,deleteWorkset as o,getWorkset as s,laneCreate as c,laneDiff as l,laneDiscard as u,laneList as d,laneMerge as f,laneStatus as p,listWorksets as m,queueClear as h,queueCreate as g,queueDelete as _,queueDone as v,queueFail as y,queueGet as b,queueList as x,queueNext as S,queuePush as C,removeFromWorkset as w,saveWorkset as T,stashClear as E,stashDelete as D,stashGet as O,stashList as k,stashSet as A}from"../../../tools/dist/index.js";const j=[{name:`workset`,description:`Manage saved file sets`,usage:`kb workset <action> [name] [--files f1,f2] [--description desc]`,run:async t=>{let r=t.shift()?.trim(),c=i(e(t,`--files`,``)),l=e(t,`--description`,``).trim()||void 0,u=t.shift()?.trim();switch(r||(console.error(`Usage: kb workset <action> [name] [--files f1,f2] [--description desc]`),console.error(`Actions: save, get, list, delete, add, remove`),process.exit(1)),r){case`save`:{(!u||c.length===0)&&(console.error(`Usage: kb workset save <name> --files f1,f2 [--description desc]`),process.exit(1));let e=T(u,c,{description:l});console.log(`Saved workset: ${e.name}`),n(e);return}case`get`:{u||(console.error(`Usage: kb workset get <name>`),process.exit(1));let e=s(u);if(!e){console.log(`No workset found: ${u}`);return}n(e);return}case`list`:{let e=m();if(e.length===0){console.log(`No worksets saved.`);return}console.log(`Worksets (${e.length})`),console.log(`─`.repeat(60));for(let t of e)n(t),console.log(``);return}case`delete`:{u||(console.error(`Usage: kb workset delete <name>`),process.exit(1));let e=o(u);console.log(e?`Deleted workset: ${u}`:`No workset found: ${u}`);return}case`add`:{(!u||c.length===0)&&(console.error(`Usage: kb workset add <name> --files f1,f2`),process.exit(1));let e=a(u,c);console.log(`Updated workset: ${e.name}`),n(e);return}case`remove`:{(!u||c.length===0)&&(console.error(`Usage: kb workset remove <name> --files f1,f2`),process.exit(1));let e=w(u,c);if(!e){console.log(`No workset found: ${u}`);return}console.log(`Updated workset: ${e.name}`),n(e);return}default:console.error(`Unknown workset action: ${r}`),console.error(`Actions: save, get, list, delete, add, remove`),process.exit(1)}}},{name:`stash`,description:`Persist and retrieve named intermediate values`,usage:`kb stash <set|get|list|delete|clear> [key] [value]`,run:async e=>{let n=e.shift()?.trim(),i=e.shift()?.trim();switch(n||(console.error(`Usage: kb stash <set|get|list|delete|clear> [key] [value]`),process.exit(1)),n){case`set`:{i||(console.error(`Usage: kb stash set <key> <value>`),process.exit(1));let n=e.join(` `),a=n.trim()?``:await r(),o=A(i,t(n||a));console.log(`Stored stash entry: ${o.key}`),console.log(`  Type: ${o.type}`),console.log(`  Stored: ${o.storedAt}`);return}case`get`:{i||(console.error(`Usage: kb stash get <key>`),process.exit(1));let e=O(i);if(!e){console.log(`No stash entry found: ${i}`);return}console.log(JSON.stringify(e,null,2));return}case`list`:{let e=k();if(e.length===0){console.log(`No stash entries saved.`);return}console.log(`Stash entries (${e.length})`),console.log(`─`.repeat(60));for(let t of e)console.log(`${t.key} (${t.type})`),console.log(`  Stored: ${t.storedAt}`);return}case`delete`:{i||(console.error(`Usage: kb stash delete <key>`),process.exit(1));let e=D(i);console.log(e?`Deleted stash entry: ${i}`:`No stash entry found: ${i}`);return}case`clear`:{let e=E();console.log(`Cleared ${e} stash entr${e===1?`y`:`ies`}.`);return}default:console.error(`Unknown stash action: ${n}`),console.error(`Actions: set, get, list, delete, clear`),process.exit(1)}}},{name:`lane`,description:`Manage verified lanes — isolated file copies for parallel exploration`,usage:`aikit lane <create|list|status|diff|merge|discard> [name] [--files f1,f2]`,run:async t=>{let n=t.shift();if((!n||![`create`,`list`,`status`,`diff`,`merge`,`discard`].includes(n))&&(console.error(`Usage: aikit lane <create|list|status|diff|merge|discard> [name] [--files f1,f2]`),process.exit(1)),n===`list`){let e=d();if(e.length===0){console.log(`No active lanes.`);return}for(let t of e)console.log(`${t.name}  (${t.sourceFiles.length} files, created ${t.createdAt})`);return}let r=t.shift();switch(r||(console.error(`Lane name is required for "${n}".`),process.exit(1)),n){case`create`:{let n=e(t,`--files`,``);n||(console.error(`Usage: aikit lane create <name> --files file1.ts,file2.ts`),process.exit(1));let i=c(r,n.split(`,`).map(e=>e.trim()));console.log(`Lane "${i.name}" created with ${i.sourceFiles.length} files.`);break}case`status`:{let e=p(r);console.log(`Lane: ${e.name}`),console.log(`Modified: ${e.modified} | Added: ${e.added} | Deleted: ${e.deleted}`);for(let t of e.entries)console.log(`  ${t.status.padEnd(10)} ${t.file}`);break}case`diff`:{let e=l(r);console.log(`Lane: ${e.name} — ${e.modified} modified, ${e.added} added, ${e.deleted} deleted`);for(let t of e.entries)t.diff&&(console.log(`\n--- ${t.file} (${t.status})`),console.log(t.diff));break}case`merge`:{let e=f(r);console.log(`Merged ${e.filesMerged} files from lane "${e.name}".`);for(let t of e.files)console.log(`  ${t}`);break}case`discard`:{let e=u(r);console.log(e?`Lane "${r}" discarded.`:`Lane "${r}" not found.`);break}}}},{name:`queue`,description:`Manage task queues for sequential agent operations`,usage:`kb queue <create|push|next|done|fail|get|list|clear|delete> [name] [args]`,run:async e=>{let t=e.shift();if((!t||![`create`,`push`,`next`,`done`,`fail`,`get`,`list`,`clear`,`delete`].includes(t))&&(console.error(`Usage: kb queue <create|push|next|done|fail|get|list|clear|delete> [name] [args]`),process.exit(1)),t===`list`){let e=x();if(e.length===0){console.log(`No queues.`);return}for(let t of e)console.log(`${t.name}  pending:${t.pending} done:${t.done} failed:${t.failed} total:${t.total}`);return}let n=e.shift();switch(n||(console.error(`Queue name is required for "${t}".`),process.exit(1)),t){case`create`:{let e=g(n);console.log(`Queue "${e.name}" created.`);break}case`push`:{let t=C(n,e.join(` `)||`Untitled task`);console.log(`Pushed "${t.title}" (${t.id}) to queue "${n}".`);break}case`next`:{let e=S(n);console.log(e?`Next: ${e.title} (${e.id})`:`No pending items in queue "${n}".`);break}case`done`:{let t=e.shift();t||(console.error(`Usage: kb queue done <name> <id>`),process.exit(1));let r=v(n,t);console.log(`Marked "${r.title}" as done.`);break}case`fail`:{let t=e.shift(),r=e.join(` `)||`Unknown error`;t||(console.error(`Usage: kb queue fail <name> <id> [error message]`),process.exit(1));let i=y(n,t,r);console.log(`Marked "${i.title}" as failed: ${r}`);break}case`get`:{let e=b(n);if(!e){console.log(`Queue "${n}" not found.`);return}console.log(`Queue: ${e.name} (${e.items.length} items)`);for(let t of e.items){let e=t.error?` — ${t.error}`:``;console.log(`  ${t.status.padEnd(12)} ${t.id}  ${t.title}${e}`)}break}case`clear`:{let e=h(n);console.log(`Cleared ${e} completed/failed items from queue "${n}".`);break}case`delete`:{let e=_(n);console.log(e?`Queue "${n}" deleted.`:`Queue "${n}" not found.`);break}}}}];export{j as workspaceCommands};

package/packages/cli/dist/context.d.ts

@@ -0,0 +1,7 @@
+import { KBContext } from "./aikit-init.js";
+
+//#region packages/cli/src/context.d.ts
+declare function ctx(): Promise<KBContext>;
+declare function getCtx(): KBContext | null;
+//#endregion
+export { type KBContext, ctx, getCtx };

package/packages/cli/dist/context.js

@@ -0,0 +1 @@
+import{initKB as e}from"./aikit-init.js";let t=null;async function n(){return t||=await e(),t}function r(){return t}export{n as ctx,r as getCtx};

package/packages/cli/dist/helpers.d.ts

@@ -0,0 +1,55 @@
+import { KBContext } from "./aikit-init.js";
+import { SearchResult } from "../../core/dist/index.js";
+import { BatchOperation, ManagedProcess, check, checkpointSave, diffParse, fileSummary, findDeadSymbols, findExamples, gitContext, parseOutput, symbol, testRun, trace } from "../../tools/dist/index.js";
+
+//#region packages/cli/src/helpers.d.ts
+declare function extractNumFlag(args: string[], flag: string, defaultValue: number): number;
+declare function extractStrFlag(args: string[], flag: string, defaultValue: string): string;
+declare function extractBoolFlag(args: string[], flag: string): boolean;
+declare function readStdin(): Promise<string>;
+declare function readInput(filePath?: string): Promise<string>;
+declare function splitCsv(value: string): string[];
+declare function parseBatchPayload(input: string): {
+  operations: BatchOperation[];
+  concurrency?: number;
+};
+declare function validateBatchOperations(value: unknown): BatchOperation[];
+declare function formatFocusRanges(ranges: Array<{
+  start: number;
+  end: number;
+  heading?: string;
+}>): string;
+declare function printParsedOutput(result: ReturnType<typeof parseOutput>): void;
+declare function printCheckResult(result: Awaited<ReturnType<typeof check>>): void;
+declare function printCheckSection(label: string, passed: boolean, errors: Array<{
+  file: string;
+  line?: number;
+  column?: number;
+  severity: 'error' | 'warning' | 'info';
+  code?: string;
+  message: string;
+}>): void;
+declare function printTestRunResult(result: Awaited<ReturnType<typeof testRun>>): void;
+declare function printGitContext(result: Awaited<ReturnType<typeof gitContext>>): void;
+declare function printDiffFiles(files: ReturnType<typeof diffParse>): void;
+declare function printTraceResult(result: Awaited<ReturnType<typeof trace>>): void;
+declare function printExamplesResult(result: Awaited<ReturnType<typeof findExamples>>): void;
+declare function printManagedProcess(info: ManagedProcess): void;
+declare function printDeadSymbolsResult(result: Awaited<ReturnType<typeof findDeadSymbols>>): void;
+declare function printFileSummary(summary: Awaited<ReturnType<typeof fileSummary>>): void;
+declare function printSymbolInfo(result: Awaited<ReturnType<typeof symbol>>): void;
+declare function printWorkset(workset: {
+  name: string;
+  files: string[];
+  created: string;
+  updated: string;
+  description?: string;
+}): void;
+declare function printCheckpoint(checkpoint: ReturnType<typeof checkpointSave>): void;
+declare function printSection(label: string, items: string[]): void;
+declare function parseMaybeJsonString(value: string): unknown;
+declare function parseRecordString(value: string): Record<string, unknown>;
+declare function rrf(vecResults: SearchResult[], ftsResults: SearchResult[], k?: number): SearchResult[];
+declare function executeCliBatchOperation(operation: BatchOperation, context: KBContext | null): Promise<unknown>;
+//#endregion
+export { executeCliBatchOperation, extractBoolFlag, extractNumFlag, extractStrFlag, formatFocusRanges, parseBatchPayload, parseMaybeJsonString, parseRecordString, printCheckResult, printCheckSection, printCheckpoint, printDeadSymbolsResult, printDiffFiles, printExamplesResult, printFileSummary, printGitContext, printManagedProcess, printParsedOutput, printSection, printSymbolInfo, printTestRunResult, printTraceResult, printWorkset, readInput, readStdin, rrf, splitCsv, validateBatchOperations };

package/packages/cli/dist/helpers.js

@@ -0,0 +1,5 @@
+import{resolve as e}from"node:path";import{readFile as t}from"node:fs/promises";import{check as n,find as r}from"../../tools/dist/index.js";function i(e,t,n){let r=e.indexOf(t);if(r===-1||r+1>=e.length)return n;let i=Number.parseInt(e.splice(r,2)[1],10);return Number.isNaN(i)?n:i}function a(e,t,n){let r=e.indexOf(t);return r===-1||r+1>=e.length?n:e.splice(r,2)[1]}function o(e,t){let n=e.indexOf(t);return n===-1?!1:(e.splice(n,1),!0)}async function s(){if(process.stdin.isTTY)return``;let e=[];for await(let t of process.stdin)e.push(t);return Buffer.concat(e).toString(`utf-8`)}async function c(n){return n?t(e(n),`utf-8`):s()}function l(e){return e.split(`,`).map(e=>e.trim()).filter(Boolean)}function u(e){let t=JSON.parse(e);if(Array.isArray(t))return{operations:d(t)};if(t&&typeof t==`object`&&`operations`in t){let e=t;return{operations:d(e.operations),concurrency:typeof e.concurrency==`number`?e.concurrency:void 0}}throw Error(`Batch input must be an array of operations or an object with an operations array.`)}function d(e){if(!Array.isArray(e))throw Error(`Batch operations must be an array.`);return e.map((e,t)=>{if(!e||typeof e!=`object`)throw Error(`Batch operation at index ${t} must be an object.`);let n=e;if(typeof n.id!=`string`||n.id.length===0)throw Error(`Batch operation at index ${t} is missing a valid id.`);if(typeof n.type!=`string`||n.type.length===0)throw Error(`Batch operation ${n.id} is missing a valid type.`);if(!n.args||typeof n.args!=`object`||Array.isArray(n.args))throw Error(`Batch operation ${n.id} must include an args object.`);return{id:n.id,type:n.type,args:n.args}})}function f(e){return e.map(e=>{let t=e.heading?` ${e.heading}`:``;return`${e.start}-${e.end}${t}`}).join(`, `)}function p(e){switch(e.tool){case`tsc`:case`biome`:console.log(`${e.tool} errors: ${e.errors.length}`);for(let t of e.errors){let e=[t.line,t.column].filter(e=>e!==void 0).join(`:`),n=e?`${t.file}:${e}`:t.file,r=t.code?` ${t.code}`:``;console.log(`- ${n} [${t.severity}${r}] ${t.message}`)}return;case`vitest`:console.log(`Vitest summary`),console.log(`  Passed:  ${e.summary.passed}`),console.log(`  Failed:  ${e.summary.failed}`),console.log(`  Skipped: ${e.summary.skipped}`),e.summary.duration!==void 0&&console.log(`  Duration: ${e.summary.duration}ms`);for(let t of e.summary.tests)t.status===`fail`&&(console.log(`- ${t.name}${t.file?` (${t.file})`:``}`),t.error&&console.log(`  ${t.error}`));return;case`git-status`:console.log(`Branch: ${e.status.branch??`unknown`}`),console.log(`Staged: ${e.status.staged.length}`);for(let t of e.status.staged)console.log(`  ${t.status} ${t.file}`);console.log(`Unstaged: ${e.status.unstaged.length}`);for(let t of e.status.unstaged)console.log(`  ${t.status} ${t.file}`);console.log(`Untracked: ${e.status.untracked.length}`);for(let t of e.status.untracked)console.log(`  ?? ${t}`);return}}function m(e){console.log(`Overall: ${e.passed?`passed`:`failed`}`),h(`tsc`,e.tsc.passed,e.tsc.errors),h(`biome`,e.biome.passed,e.biome.errors)}function h(e,t,n){console.log(`${e}: ${t?`passed`:`${n.length} issue(s)`}`);for(let e of n){let t=[e.line,e.column].filter(e=>e!==void 0).join(`:`),n=t?`${e.file}:${t}`:e.file,r=e.code?` ${e.code}`:``;console.log(`  - ${n} [${e.severity}${r}] ${e.message}`)}}function g(e){console.log(`Vitest: ${e.passed?`passed`:`failed`}`),console.log(`  Duration: ${e.durationMs}ms`),console.log(`  Passed: ${e.summary.passed}`),console.log(`  Failed: ${e.summary.failed}`),console.log(`  Skipped: ${e.summary.skipped}`),e.summary.suites!==void 0&&console.log(`  Suites: ${e.summary.suites}`);let t=e.summary.tests.filter(e=>e.status===`fail`);if(t.length!==0){console.log(`Failed tests:`);for(let e of t)console.log(`  - ${e.name}${e.file?` (${e.file})`:``}`),e.error&&console.log(`    ${e.error}`)}}function _(e){console.log(`Branch: ${e.branch}`),console.log(`Staged: ${e.status.staged.length}`);for(let t of e.status.staged)console.log(`  - ${t}`);console.log(`Modified: ${e.status.modified.length}`);for(let t of e.status.modified)console.log(`  - ${t}`);console.log(`Untracked: ${e.status.untracked.length}`);for(let t of e.status.untracked)console.log(`  - ${t}`);if(console.log(``),console.log(`Recent commits:`),e.recentCommits.length===0)console.log(`  none`);else for(let t of e.recentCommits)console.log(`  - ${t.hash} ${t.message}`),console.log(`    ${t.author} @ ${t.date}`);e.diff&&(console.log(``),console.log(`Diff stat:`),console.log(e.diff))}function v(e){if(e.length===0){console.log(`No diff files found.`);return}for(let t of e){let e=t.oldPath?` (from ${t.oldPath})`:``;console.log(`${t.path}${e}`),console.log(`  Status: ${t.status}`),console.log(`  Changes: +${t.additions} -${t.deletions}`),console.log(`  Hunks: ${t.hunks.length}`);for(let e of t.hunks){let t=e.header?` ${e.header}`:``;console.log(`    @@ -${e.oldStart},${e.oldLines} +${e.newStart},${e.newLines} @@${t}`)}}}function y(e){if(console.log(`Start: ${e.start}`),console.log(`Direction: ${e.direction}`),console.log(`Depth reached: ${e.depth}`),console.log(`Nodes: ${e.nodes.length}`),e.nodes.length===0){console.log(`No trace nodes found.`);return}for(let t of e.nodes)console.log(`  - [${t.relationship}] ${t.path}:${t.line} ${t.symbol}`)}function b(e){if(console.log(`Query: ${e.query}`),console.log(`Examples: ${e.examples.length} shown (${e.totalFound} total)`),e.examples.length===0){console.log(`No matching examples found.`);return}for(let t of e.examples){console.log(``),console.log(`${t.path}:${t.startLine}-${t.endLine}`),console.log(`  Context: ${t.context}`),console.log(`  Relevance: ${(t.relevance*100).toFixed(1)}%`);for(let e of t.content.split(`
+`))console.log(`  ${e}`)}}function x(e){console.log(e.id),console.log(`  Command: ${e.command}${e.args.length>0?` ${e.args.join(` `)}`:``}`),console.log(`  PID: ${e.pid??`unknown`}`),console.log(`  Status: ${e.status}`),console.log(`  Started: ${e.startedAt}`),e.exitCode!==void 0&&console.log(`  Exit code: ${e.exitCode}`),console.log(`  Logs: ${e.logs.length}`)}function S(e){if(console.log(`Exports scanned: ${e.totalExports}`),console.log(`Dead in source: ${e.totalDeadSource} (actionable)`),console.log(`Dead in docs: ${e.totalDeadDocs} (informational)`),e.totalDeadSource===0&&e.totalDeadDocs===0){console.log(`No dead symbols found.`);return}if(e.deadInSource.length>0){console.log(`
+Dead in source (actionable):`);for(let t of e.deadInSource)console.log(`  - ${t.path}:${t.line} ${t.kind} ${t.name}`)}if(e.deadInDocs.length>0){console.log(`
+Dead in docs (informational):`);for(let t of e.deadInDocs)console.log(`  - ${t.path}:${t.line} ${t.kind} ${t.name}`)}}function C(e){console.log(e.path),console.log(`  Language: ${e.language}`),console.log(`  Lines: ${e.lines}`),console.log(`  Estimated tokens: ~${e.estimatedTokens}`),console.log(``),D(`Imports`,e.imports),D(`Exports`,e.exports),D(`Functions`,e.functions.map(e=>`${e.name} @ line ${e.line}${e.exported?` [exported]`:``}`)),D(`Classes`,e.classes.map(e=>`${e.name} @ line ${e.line}${e.exported?` [exported]`:``}`)),D(`Interfaces`,e.interfaces.map(e=>`${e.name} @ line ${e.line}`)),D(`Types`,e.types.map(e=>`${e.name} @ line ${e.line}`))}function w(e){if(console.log(`Symbol: ${e.name}`),e.definedIn?console.log(`Defined in: ${e.definedIn.path}:${e.definedIn.line} (${e.definedIn.kind})`):console.log(`Defined in: not found`),console.log(``),console.log(`Imported by:`),e.importedBy.length===0)console.log(`  none`);else for(let t of e.importedBy)console.log(`  - ${t.path}:${t.line} ${t.importStatement}`);if(console.log(``),console.log(`Referenced in:`),e.referencedIn.length===0)console.log(`  none`);else for(let t of e.referencedIn)console.log(`  - ${t.path}:${t.line} ${t.context}`)}function T(e){console.log(e.name),console.log(`  Files: ${e.files.length}`),console.log(`  Updated: ${e.updated}`),e.description&&console.log(`  Description: ${e.description}`);for(let t of e.files)console.log(`  - ${t}`)}function E(e){if(console.log(e.id),console.log(`  Label: ${e.label}`),console.log(`  Created: ${e.createdAt}`),e.notes&&console.log(`  Notes: ${e.notes}`),e.files?.length){console.log(`  Files: ${e.files.length}`);for(let t of e.files)console.log(`  - ${t}`)}console.log(`  Data:`);for(let t of JSON.stringify(e.data,null,2).split(`
+`))console.log(`    ${t}`)}function D(e,t){if(console.log(`${e}:`),t.length===0){console.log(`  none`),console.log(``);return}for(let e of t)console.log(`  - ${e}`);console.log(``)}function O(e){let t=e.trim();if(!t)return``;try{return JSON.parse(t)}catch{return e}}function k(e){let t=e.trim();if(!t)return{};let n=JSON.parse(t);if(!n||typeof n!=`object`||Array.isArray(n))throw Error(`Checkpoint data must be a JSON object.`);return n}function A(e,t,n=60){let r=new Map;for(let t=0;t<e.length;t++){let i=e[t];r.set(i.record.id,{record:i.record,score:1/(n+t+1)})}for(let e=0;e<t.length;e++){let i=t[e],a=r.get(i.record.id);a?a.score+=1/(n+e+1):r.set(i.record.id,{record:i.record,score:1/(n+e+1)})}return[...r.values()].sort((e,t)=>t.score-e.score)}async function j(e,t){switch(e.type){case`search`:{if(!t)throw Error(`search operation requires knowledge base context`);let n=typeof e.args.query==`string`?e.args.query.trim():``;if(!n)throw Error(`search operation requires a query`);let r=typeof e.args.limit==`number`?e.args.limit:5,i=e.args.search_mode===`semantic`||e.args.search_mode===`keyword`?e.args.search_mode:`hybrid`,a=typeof e.args.content_type==`string`?e.args.content_type:void 0,o=typeof e.args.min_score==`number`?e.args.min_score:.25;if(i===`keyword`)return(await t.store.ftsSearch(n,{limit:r,contentType:a,minScore:o})).slice(0,r);let s=await t.embedder.embedQuery(n);if(i===`semantic`)return t.store.search(s,{limit:r,contentType:a,minScore:o});let[c,l]=await Promise.all([t.store.search(s,{limit:r*2,contentType:a,minScore:o}),t.store.ftsSearch(n,{limit:r*2,contentType:a,minScore:o}).catch(()=>[])]);return A(c,l).slice(0,r)}case`find`:{if(!t)throw Error(`find operation requires knowledge base context`);let n=typeof e.args.query==`string`?e.args.query:void 0,i=typeof e.args.glob==`string`?e.args.glob:void 0,a=typeof e.args.pattern==`string`?e.args.pattern:void 0,o=typeof e.args.limit==`number`?e.args.limit:10,s=typeof e.args.content_type==`string`?e.args.content_type:void 0,c=typeof e.args.cwd==`string`?e.args.cwd:void 0;if(!n&&!i&&!a)throw Error(`find operation requires query, glob, or pattern`);return r(t.embedder,t.store,{query:n,glob:i,pattern:a,limit:o,contentType:s,cwd:c})}case`check`:return n({files:Array.isArray(e.args.files)?e.args.files.filter(e=>typeof e==`string`):void 0,cwd:typeof e.args.cwd==`string`?e.args.cwd:void 0,skipTypes:e.args.skip_types===!0,skipLint:e.args.skip_lint===!0});default:throw Error(`Unsupported batch operation type: ${e.type}`)}}export{j as executeCliBatchOperation,o as extractBoolFlag,i as extractNumFlag,a as extractStrFlag,f as formatFocusRanges,u as parseBatchPayload,O as parseMaybeJsonString,k as parseRecordString,m as printCheckResult,h as printCheckSection,E as printCheckpoint,S as printDeadSymbolsResult,v as printDiffFiles,b as printExamplesResult,C as printFileSummary,_ as printGitContext,x as printManagedProcess,p as printParsedOutput,D as printSection,w as printSymbolInfo,g as printTestRunResult,y as printTraceResult,T as printWorkset,c as readInput,s as readStdin,A as rrf,l as splitCsv,d as validateBatchOperations};

package/packages/cli/dist/index.d.ts

@@ -0,0 +1,10 @@
+//#region packages/cli/src/index.d.ts
+/**
+ * @vpxa/aikit CLI — command-line interface for the knowledge base toolkit.
+ *
+ * Thin adapter: arg parsing + output formatting.
+ * All core logic lives in @aikit/core, @aikit/store, @aikit/embeddings, etc.
+ */
+declare function run(argv: string[]): Promise<void>;
+//#endregion
+export { run };

package/packages/cli/dist/index.js

@@ -0,0 +1,3 @@
+import{getCtx as e}from"./context.js";import{analyzeCommands as t}from"./commands/analyze.js";import{contextCommands as n}from"./commands/context-cmds.js";import{environmentCommands as r}from"./commands/environment.js";import{executionCommands as i}from"./commands/execution.js";import{flowCommands as a}from"./commands/flow.js";import{graphCommands as o}from"./commands/graph.js";import{knowledgeCommands as s}from"./commands/knowledge.js";import{searchCommands as c}from"./commands/search.js";import{systemCommands as l}from"./commands/system.js";import{upgradeCommands as u}from"./commands/upgrade.js";import{workspaceCommands as d}from"./commands/workspace.js";import{readFileSync as f}from"node:fs";import{dirname as p,resolve as m}from"node:path";import{fileURLToPath as h}from"node:url";const g=[...c,...s,...t,...o,...l,...i,...n,...d,...r,...u,...a];g.push({name:`help`,description:`Show available commands`,run:async()=>{v()}});async function _(t){let n=[...t],r=n.shift();if(!r||r===`--help`||r===`-h`){v();return}if(r===`--version`||r===`-v`){let e=m(p(h(import.meta.url)),`..`,`..`,`..`,`package.json`),t=JSON.parse(f(e,`utf-8`));console.log(t.version);return}let i=g.find(e=>e.name===r);i||(console.error(`Unknown command: ${r}`),v(),process.exit(1));try{await i.run(n)}finally{let t=e();t&&await t.store.close()}}function v(){console.log(`@vpxa/aikit — Local-first AI developer toolkit
+`),console.log(`Usage: aikit <command> [options]
+`),console.log(`Commands:`);let e=Math.max(...g.map(e=>e.name.length));for(let t of g)console.log(`  ${t.name.padEnd(e+2)}${t.description}`);console.log(``),console.log(`Options:`),console.log(`  --help, -h     Show this help`),console.log(`  --version, -v  Show version`)}export{_ as run};

package/packages/cli/dist/types.d.ts

@@ -0,0 +1,9 @@
+//#region packages/cli/src/types.d.ts
+interface Command {
+  name: string;
+  description: string;
+  usage?: string;
+  run: (args: string[]) => Promise<void>;
+}
+//#endregion
+export { Command };

package/packages/cli/dist/types.js

@@ -0,0 +1 @@
+export{};

package/packages/core/dist/constants.d.ts

@@ -0,0 +1,74 @@
+//#region packages/core/src/constants.d.ts
+/**
+ * Default constants for the Knowledge Base system.
+ */
+/**
+ * Centralized directory paths for all KB artifacts.
+ * Single source of truth — change here to update everywhere.
+ */
+declare const AIKIT_PATHS: {
+  /** AI artifacts root directory */readonly ai: ".ai"; /** Onboard / produce_knowledge output directory */
+  readonly aiKb: ".ai/kb"; /** Curated knowledge directory */
+  readonly aiCurated: ".ai/curated"; /** Restore points for destructive operations (codemod, rename, forget) */
+  readonly restorePoints: ".ai/restore-points"; /** Vector store + graph data */
+  readonly data: ".aikit-data"; /** Session state (stash, lanes, checkpoints, worksets, queues, replay, evidence-maps, snippets) */
+  readonly state: ".aikit-state"; /** Persistent warn/error logs for dogfooding review */
+  readonly logs: ".aikit-state/logs"; /** Brainstorming sessions */
+  readonly brainstorm: ".brainstorm"; /** Session handoff documents */
+  readonly handoffs: ".handoffs";
+};
+/**
+ * Global-mode directory paths (under ~/.aikit-data/).
+ * Used when KB is installed at user level rather than per-workspace.
+ */
+declare const AIKIT_GLOBAL_PATHS: {
+  /** Root directory name for global data store */readonly root: ".aikit-data"; /** Registry file tracking all enrolled workspaces */
+  readonly registry: "registry.json";
+};
+/** Default chunk sizes by content type */
+declare const CHUNK_SIZES: {
+  readonly markdown: {
+    readonly max: 1500;
+    readonly min: 100;
+  };
+  readonly code: {
+    readonly max: 2000;
+    readonly min: 50;
+  };
+  readonly config: {
+    readonly max: 3000;
+    readonly min: 50;
+  };
+  readonly default: {
+    readonly max: 1500;
+    readonly min: 100;
+    readonly overlap: 200;
+  };
+};
+/** Default embedding config */
+declare const EMBEDDING_DEFAULTS: {
+  readonly model: "mixedbread-ai/mxbai-embed-large-v1";
+  readonly dimensions: 1024;
+};
+/** Default store config */
+declare const STORE_DEFAULTS: {
+  readonly backend: "lancedb";
+  readonly path: ".aikit-data";
+  readonly tableName: "knowledge";
+};
+/** File size limits */
+declare const FILE_LIMITS: {
+  readonly maxFileSizeBytes: 1000000;
+  readonly maxCuratedFileSizeBytes: 50000;
+};
+/** Search defaults */
+declare const SEARCH_DEFAULTS: {
+  readonly maxResults: 10;
+  readonly minScore: 0.25;
+};
+/** Category validation regex */
+declare const CATEGORY_PATTERN: RegExp;
+/** Default knowledge categories */
+declare const DEFAULT_CATEGORIES: readonly ["decisions", "patterns", "troubleshooting", "conventions", "architecture"];
+//#endregion
+export { AIKIT_GLOBAL_PATHS, AIKIT_PATHS, CATEGORY_PATTERN, CHUNK_SIZES, DEFAULT_CATEGORIES, EMBEDDING_DEFAULTS, FILE_LIMITS, SEARCH_DEFAULTS, STORE_DEFAULTS };

package/packages/core/dist/constants.js

@@ -0,0 +1 @@
+const e={ai:`.ai`,aiKb:`.ai/kb`,aiCurated:`.ai/curated`,restorePoints:`.ai/restore-points`,data:`.aikit-data`,state:`.aikit-state`,logs:`.aikit-state/logs`,brainstorm:`.brainstorm`,handoffs:`.handoffs`},t={root:`.aikit-data`,registry:`registry.json`},n={markdown:{max:1500,min:100},code:{max:2e3,min:50},config:{max:3e3,min:50},default:{max:1500,min:100,overlap:200}},r={model:`mixedbread-ai/mxbai-embed-large-v1`,dimensions:1024},i={backend:`lancedb`,path:e.data,tableName:`knowledge`},a={maxFileSizeBytes:1e6,maxCuratedFileSizeBytes:5e4},o={maxResults:10,minScore:.25},s=/^[a-z][a-z0-9-]*$/,c=[`decisions`,`patterns`,`troubleshooting`,`conventions`,`architecture`];export{t as AIKIT_GLOBAL_PATHS,e as AIKIT_PATHS,s as CATEGORY_PATTERN,n as CHUNK_SIZES,c as DEFAULT_CATEGORIES,r as EMBEDDING_DEFAULTS,a as FILE_LIMITS,o as SEARCH_DEFAULTS,i as STORE_DEFAULTS};

package/packages/core/dist/content-detector.d.ts

@@ -0,0 +1,13 @@
+import { ContentType, SourceType } from "./types.js";
+
+//#region packages/core/src/content-detector.d.ts
+/**
+ * Detect the content type of a file based on its path.
+ */
+declare function detectContentType(filePath: string): ContentType;
+/** Derive the coarse SourceType from a ContentType. */
+declare function contentTypeToSourceType(ct: ContentType): SourceType;
+/** Get all ContentTypes that belong to a given SourceType. */
+declare function sourceTypeContentTypes(st: SourceType): ContentType[];
+//#endregion
+export { contentTypeToSourceType, detectContentType, sourceTypeContentTypes };