@llmkb/claude-code 0.1.0

package/dist/cli.js

@@ -0,0 +1,3214 @@
+#!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// lib/types.ts
+function getDefaultPluginConfig() {
+  return {
+    llmkb_base_url: "https://api.llmkb.ai",
+    watch: {
+      enabled: true,
+      debounce_ms: 300,
+      gitignore: true,
+      llmkbignore: true,
+      default_verbosity: "silent"
+    },
+    sync: {
+      concurrency: 5,
+      retry_attempts: 3,
+      retry_delay_ms: 1e3
+    },
+    hook: {
+      timeout_ms: 5e3,
+      skip: false
+    },
+    debug: false
+  };
+}
+var PACKAGE_VERSION;
+var init_types = __esm({
+  "lib/types.ts"() {
+    "use strict";
+    PACKAGE_VERSION = "0.1.0";
+  }
+});
+
+// lib/parser.ts
+import { readFile, writeFile } from "fs/promises";
+import { existsSync } from "fs";
+import { join, dirname, resolve } from "path";
+import { parse, stringify, parseDocument } from "yaml";
+import { writeFile as writeVersion } from "fs/promises";
+function findProjectRoot(startDir = process.cwd()) {
+  let current = resolve(startDir);
+  while (current !== dirname(current)) {
+    if (existsSync(join(current, ".llmkb"))) {
+      return current;
+    }
+    current = dirname(current);
+  }
+  if (existsSync(join(current, ".llmkb"))) {
+    return current;
+  }
+  return null;
+}
+async function readSpaceConfig(projectDir) {
+  const filePath = join(projectDir, ".llmkb", "spaces.yml");
+  if (!existsSync(filePath)) return null;
+  try {
+    const content = await readFile(filePath, "utf-8");
+    const raw = parse(content);
+    if (raw === null) {
+      return {};
+    }
+    if (raw.active !== void 0 || isOldSpaceFormat(raw)) {
+      const migrated = migrateOldSpaceConfig(raw);
+      await writeSpaceConfig(projectDir, migrated);
+      await writeVersion(
+        join(projectDir, ".llmkb", ".llmkb-version"),
+        PACKAGE_VERSION + "\n",
+        "utf-8"
+      );
+      return migrated;
+    }
+    return raw;
+  } catch {
+    return null;
+  }
+}
+function isOldSpaceFormat(raw) {
+  if (!raw.spaces || !Array.isArray(raw.spaces)) return false;
+  return raw.spaces.length > 0 && typeof raw.spaces[0] === "object" && raw.spaces[0] !== null && "name" in raw.spaces[0] && !("id" in raw.spaces[0]);
+}
+function migrateOldSpaceConfig(old) {
+  const result = {};
+  const oldSpaces = old.spaces ?? [];
+  const activeName = old.active ?? oldSpaces[0]?.name;
+  if (oldSpaces.length > 0) {
+    if (activeName) {
+      const activeDef = oldSpaces.find((s) => s.name === activeName);
+      const projectEntry = {
+        id: String(activeDef?.name ?? activeName),
+        name: String(activeDef?.label ?? activeName)
+      };
+      result.project_space = [projectEntry];
+    }
+    result.spaces = oldSpaces.map((s) => ({
+      id: String(s.name),
+      name: s.label ? String(s.label) : String(s.name)
+    }));
+  }
+  return result;
+}
+async function writeSpaceConfig(projectDir, config) {
+  const filePath = join(projectDir, ".llmkb", "spaces.yml");
+  const yaml = stringify(config, { lineWidth: 120 });
+  await writeFile(filePath, yaml + "\n", "utf-8");
+}
+async function addSpaceEntry(projectDir, spaceId, spaceName) {
+  let config = await readSpaceConfig(projectDir);
+  if (!config) config = {};
+  if (!config.spaces) config.spaces = [];
+  if (!config.spaces.some((s) => s.id === spaceId)) {
+    config.spaces.push({ id: spaceId, name: spaceName });
+  }
+  await writeSpaceConfig(projectDir, config);
+  return true;
+}
+async function removeSpaceEntry(projectDir, spaceId) {
+  const config = await readSpaceConfig(projectDir);
+  if (!config?.spaces) return false;
+  const idx = config.spaces.findIndex((s) => s.id === spaceId);
+  if (idx === -1) return false;
+  config.spaces.splice(idx, 1);
+  await writeSpaceConfig(projectDir, config);
+  return true;
+}
+async function updateProjectSpace(projectDir, spaceId) {
+  const config = await readSpaceConfig(projectDir);
+  if (!config) return false;
+  if (!config.project_space || config.project_space.length === 0) {
+    config.project_space = [{ id: spaceId }];
+  } else {
+    config.project_space[0].id = spaceId;
+  }
+  await writeSpaceConfig(projectDir, config);
+  return true;
+}
+async function deleteAllSpaces(projectDir) {
+  const config = await readSpaceConfig(projectDir);
+  if (!config) return false;
+  config.spaces = [];
+  await writeSpaceConfig(projectDir, config);
+  return true;
+}
+async function readVersionStamp(projectDir) {
+  const filePath = join(projectDir, ".llmkb", ".llmkb-version");
+  if (!existsSync(filePath)) return null;
+  try {
+    const content = await readFile(filePath, "utf-8");
+    return content.trim();
+  } catch {
+    return null;
+  }
+}
+var init_parser = __esm({
+  "lib/parser.ts"() {
+    "use strict";
+    init_types();
+  }
+});
+
+// lib/sync-state.ts
+var sync_state_exports = {};
+__export(sync_state_exports, {
+  clearSyncState: () => clearSyncState,
+  computeSha256: () => computeSha256,
+  getChangedFiles: () => getChangedFiles,
+  readSyncState: () => readSyncState,
+  updateSyncEntry: () => updateSyncEntry,
+  writeSyncState: () => writeSyncState
+});
+import { readFile as readFile4, writeFile as writeFile6, unlink, mkdir as mkdir4 } from "fs/promises";
+import { existsSync as existsSync7 } from "fs";
+import { createHash } from "crypto";
+import { createReadStream } from "fs";
+import { resolve as resolve5 } from "path";
+function statePath(projectDir) {
+  return resolve5(projectDir, SYNC_STATE_FILE);
+}
+function llmkbDir(projectDir) {
+  return resolve5(projectDir, ".llmkb");
+}
+async function computeSha256(filePath) {
+  return new Promise((resolve8, reject) => {
+    const hash = createHash("sha256");
+    const stream = createReadStream(filePath);
+    stream.on("data", (chunk) => hash.update(chunk));
+    stream.on("end", () => resolve8(hash.digest("hex")));
+    stream.on("error", reject);
+  });
+}
+async function readSyncState(projectDir) {
+  const filePath = statePath(projectDir);
+  if (!existsSync7(filePath)) return null;
+  try {
+    const raw = await readFile4(filePath, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+async function writeSyncState(projectDir, state) {
+  const dir = llmkbDir(projectDir);
+  if (!existsSync7(dir)) {
+    await mkdir4(dir, { recursive: true });
+  }
+  await writeFile6(statePath(projectDir), JSON.stringify(state, null, 2) + "\n", "utf-8");
+}
+async function updateSyncEntry(projectDir, relativePath, entry) {
+  const state = await readSyncState(projectDir) ?? {
+    space: "",
+    lastSyncAt: (/* @__PURE__ */ new Date()).toISOString(),
+    files: {}
+  };
+  state.files[relativePath] = entry;
+  state.lastSyncAt = (/* @__PURE__ */ new Date()).toISOString();
+  await writeSyncState(projectDir, state);
+}
+async function clearSyncState(projectDir) {
+  const filePath = statePath(projectDir);
+  if (existsSync7(filePath)) {
+    await unlink(filePath);
+  }
+}
+async function getChangedFiles(files, state) {
+  const newFiles = [];
+  const changedFiles = [];
+  const unchangedFiles = [];
+  const renamed = [];
+  const hashToPath = /* @__PURE__ */ new Map();
+  if (state) {
+    for (const [path, entry] of Object.entries(state.files)) {
+      hashToPath.set(entry.sha256, path);
+    }
+  }
+  for (const [relPath, absPath] of files) {
+    const hash = await computeSha256(absPath);
+    if (!state) {
+      newFiles.push(relPath);
+      continue;
+    }
+    const existingEntry = state.files[relPath];
+    if (!existingEntry) {
+      const oldPath = hashToPath.get(hash);
+      if (oldPath && oldPath !== relPath) {
+        renamed.push({ oldPath, newPath: relPath });
+        continue;
+      }
+      newFiles.push(relPath);
+    } else if (existingEntry.sha256 !== hash) {
+      changedFiles.push(relPath);
+    } else {
+      unchangedFiles.push(relPath);
+    }
+  }
+  return { newFiles, changedFiles, unchangedFiles, renamed };
+}
+var SYNC_STATE_FILE;
+var init_sync_state = __esm({
+  "lib/sync-state.ts"() {
+    "use strict";
+    SYNC_STATE_FILE = ".llmkb/sync-state.json";
+  }
+});
+
+// bin/cli.ts
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname as dirname2, resolve as resolve7 } from "path";
+import { Command as Command15 } from "commander";
+
+// src/commands/init.ts
+import { Command as Command2 } from "commander";
+import * as readline from "readline/promises";
+import { stdin, stdout } from "process";
+import { resolve as resolve4 } from "path";
+
+// lib/writer.ts
+init_types();
+init_parser();
+import { mkdir as mkdir2, writeFile as writeFile3 } from "fs/promises";
+import { join as join3, resolve as resolve3 } from "path";
+import { stringify as stringify2 } from "yaml";
+
+// src/commands/hooks.ts
+import { Command } from "commander";
+import { existsSync as existsSync2 } from "fs";
+import { mkdir, writeFile as writeFile2, rm } from "fs/promises";
+import { join as join2, resolve as resolve2 } from "path";
+var HOOKS_DIR = ".claude/hooks/llmkb";
+function hooksJson() {
+  return JSON.stringify(
+    {
+      hooks: {
+        PreToolUse: [
+          {
+            matcher: "Read|Bash",
+            hooks: [
+              {
+                type: "command",
+                command: "node ${CLAUDE_PLUGIN_ROOT}/hooks/llmkb-hook.js --pre --tool ${TOOL_NAME}",
+                timeout: 5,
+                statusMessage: "Checking llmkb space context..."
+              }
+            ]
+          }
+        ],
+        PostToolUse: [
+          {
+            matcher: "Edit|Write|Bash",
+            hooks: [
+              {
+                type: "command",
+                command: "node ${CLAUDE_PLUGIN_ROOT}/hooks/llmkb-hook.js --post --tool ${TOOL_NAME} --exit-code ${EXIT_CODE}",
+                timeout: 5,
+                statusMessage: "Checking sync freshness..."
+              }
+            ]
+          }
+        ]
+      }
+    },
+    null,
+    2
+  );
+}
+function hookScript() {
+  return `#!/usr/bin/env node
+// llmkb Claude Code hook \u2014 PreToolUse (space context) + PostToolUse (sync freshness)
+// Input: --pre/--post, --tool <name>, --exit-code <code>
+// Stdin: { hook_event_name, tool_name, tool_input, cwd }
+// Stdout: JSON { hookSpecificOutput: { hookEventName, additionalContext } }
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+// --- Config ---
+const HOOK_TIMEOUT = parseInt(process.env.LLMKB_HOOK_TIMEOUT_MS || "5000", 10);
+const HOOK_SKIP = process.env.LLMKB_HOOK_SKIP === "1" || process.env.LLMKB_HOOK_SKIP === "true";
+const DEBUG = process.env.LLMKB_DEBUG === "1" || process.env.LLMKB_DEBUG === "true";
+const POWERSHELL_PATH = process.env.LLMKB_HOOK_POWERSHELL_PATH || "powershell.exe";
+
+function log(msg) {
+  if (DEBUG) process.stderr.write("[llmkb hook] " + msg + "\\n");
+}
+
+function findProjectRoot(startDir) {
+  let dir = startDir;
+  for (let i = 0; i < 10; i++) {
+    if (fs.existsSync(path.join(dir, ".llmkb", "spaces.yml"))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
+function getActiveSpace(projectRoot) {
+  try {
+    const content = fs.readFileSync(path.join(projectRoot, ".llmkb", "spaces.yml"), "utf-8");
+    const match = content.match(/^active:\\s*(\\S+)/m);
+    return match ? match[1] : null;
+  } catch { return null; }
+}
+
+function handlePreToolUse(input) {
+  if (HOOK_SKIP) return;
+  const cwd = input.cwd || process.cwd();
+  const projectRoot = findProjectRoot(cwd);
+  if (!projectRoot) return; // silent skip
+  const space = getActiveSpace(projectRoot);
+  if (!space) return;
+  log("active space: " + space);
+  console.log(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      additionalContext: "llmkb space: " + space
+    }
+  }));
+}
+
+function handlePostToolUse(input) {
+  if (HOOK_SKIP) return;
+  const toolName = input.tool_name || "";
+  if (toolName !== "Edit" && toolName !== "Write" && toolName !== "Bash") return;
+  const exitCode = input.tool_output ? input.tool_output.exit_code : 0;
+  if (exitCode !== 0) return;
+  const cwd = input.cwd || process.cwd();
+  const projectRoot = findProjectRoot(cwd);
+  if (!projectRoot) return;
+  log("post-tool: suggesting sync freshness check");
+  console.log(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PostToolUse",
+      additionalContext: "Files may have changed. Consider running \`llmkb sync\` to update the space."
+    }
+  }));
+}
+
+function main() {
+  try {
+    const args = process.argv.slice(2);
+    const isPre = args.includes("--pre");
+    const isPost = args.includes("--post");
+    const raw = fs.readFileSync(0, "utf-8").trim();
+    const input = raw ? JSON.parse(raw) : {};
+
+    if (isPre) handlePreToolUse(input);
+    else if (isPost) handlePostToolUse(input);
+  } catch (err) {
+    if (DEBUG) process.stderr.write("[llmkb hook] error: " + (err.message || "") + "\\n");
+  }
+}
+
+main();
+`;
+}
+function ps1Script() {
+  return `# llmkb Claude Code hook \u2014 PowerShell fallback for Windows
+# Input: --pre/--post, --tool <name>, --exit-code <code>
+# Stdin: JSON { hook_event_name, tool_name, tool_input, cwd }
+
+param(
+  [switch]$pre,
+  [switch]$post,
+  [string]$tool = "",
+  [int]$exitCode = 0
+)
+
+$skip = $env:LLMKB_HOOK_SKIP
+if ($skip -eq "1" -or $skip -eq "true") { exit 0 }
+
+$debug = $env:LLMKB_DEBUG
+function Log($msg) {
+  if ($debug -eq "1" -or $debug -eq "true") {
+    [Console.Error]::WriteLine("[llmkb hook] $msg")
+  }
+}
+
+# Walk up to find .llmkb/spaces.yml
+$dir = (Get-Location).Path
+for ($i = 0; $i -lt 10; $i++) {
+  $check = Join-Path $dir ".llmkb" "spaces.yml"
+  if (Test-Path $check) {
+    $content = Get-Content $check -Raw
+    if ($content -match 'active:\\s*(\\S+)') {
+      $space = $Matches[1]
+      if ($pre) {
+        $result = @{
+          hookSpecificOutput = @{
+            hookEventName = "PreToolUse"
+            additionalContext = "llmkb space: $space"
+          }
+        }
+        ConvertTo-Json $result -Compress
+      }
+    }
+    break
+  }
+  $parent = Split-Path $dir -Parent
+  if ($parent -eq $dir) { break }
+  $dir = $parent
+}
+`;
+}
+async function writeHooks(projectDir, force) {
+  const hooksDir = resolve2(projectDir, HOOKS_DIR);
+  const written = [];
+  await mkdir(hooksDir, { recursive: true });
+  const hooksJsonPath = join2(hooksDir, "hooks.json");
+  if (!existsSync2(hooksJsonPath) || force) {
+    await writeFile2(hooksJsonPath, hooksJson() + "\n", "utf-8");
+    written.push(".claude/hooks/llmkb/hooks.json");
+  }
+  const hookJsPath = join2(hooksDir, "llmkb-hook.js");
+  if (!existsSync2(hookJsPath) || force) {
+    await writeFile2(hookJsPath, hookScript(), "utf-8");
+    written.push(".claude/hooks/llmkb/llmkb-hook.js");
+  }
+  const ps1Path = join2(hooksDir, "llmkb-hook.ps1");
+  if (!existsSync2(ps1Path) || force) {
+    await writeFile2(ps1Path, ps1Script(), "utf-8");
+    written.push(".claude/hooks/llmkb/llmkb-hook.ps1");
+  }
+  return written;
+}
+async function removeHooks(projectDir) {
+  const hooksDir = resolve2(projectDir, HOOKS_DIR);
+  if (existsSync2(hooksDir)) {
+    await rm(hooksDir, { recursive: true, force: true });
+    return true;
+  }
+  return false;
+}
+function hooksInstalled(projectDir) {
+  const hooksDir = resolve2(projectDir, HOOKS_DIR);
+  return existsSync2(join2(hooksDir, "hooks.json"));
+}
+var hooksCommand = new Command("hooks").description("Manage Claude Code hooks for llmkb context enrichment").addCommand(
+  new Command("install").description("Install llmkb hooks").option("-f, --force", "Overwrite existing hook files").action(async (opts) => {
+    const projectDir = process.cwd();
+    try {
+      const files = await writeHooks(projectDir, opts.force);
+      if (files.length > 0) {
+        console.log(`Installed ${files.length} hook file(s):`);
+        for (const f of files) console.log(`  \u2714 ${f}`);
+      } else {
+        console.log("Hooks already installed. Use --force to overwrite.");
+      }
+    } catch (err) {
+      console.error("Error installing hooks:", err.message);
+      process.exit(1);
+    }
+  })
+).addCommand(
+  new Command("uninstall").description("Remove llmkb hooks").action(async () => {
+    const projectDir = process.cwd();
+    const removed = await removeHooks(projectDir);
+    if (removed) {
+      console.log("Hooks removed.");
+    } else {
+      console.log("No hooks found.");
+    }
+  })
+).addCommand(
+  new Command("status").description("Check whether hooks are installed").action(() => {
+    const projectDir = process.cwd();
+    if (hooksInstalled(projectDir)) {
+      console.log("llmkb hooks are installed.");
+    } else {
+      console.log(
+        "llmkb hooks are not installed. Run `llmkb hooks install`."
+      );
+    }
+  })
+);
+
+// lib/writer.ts
+function projectPath(projectDir, ...parts) {
+  return resolve3(projectDir, ...parts);
+}
+async function ensureDir(filePath) {
+  await mkdir2(filePath, { recursive: true });
+}
+var PLUGIN_JSON = {
+  name: "llmkb",
+  description: "LLM-powered knowledge base with wiki generation, semantic search, and knowledge graphs. Sync codebases, query spaces, and explore architecture from Claude.",
+  version: PACKAGE_VERSION,
+  author: { name: "llmkb" },
+  homepage: "https://llmkb.ai",
+  keywords: ["knowledge-base", "wiki", "mcp"]
+};
+var MCP_JSON_CLAUDE = {
+  mcpServers: {
+    llmkb: {
+      description: "llmkb wiki \u2014 search, read, and write your knowledge base via MCP tools",
+      command: "docker",
+      args: [
+        "compose",
+        "--profile",
+        "mvp",
+        "exec",
+        "-i",
+        "api",
+        "python",
+        "-m",
+        "app.mcp.stdio"
+      ]
+    }
+  }
+};
+var MCP_JSON_CURSOR = {
+  mcpServers: {
+    llmkb: {
+      description: "llmkb wiki \u2014 search, read, and write your knowledge base via MCP tools",
+      command: "docker",
+      args: [
+        "compose",
+        "--profile",
+        "mvp",
+        "exec",
+        "-i",
+        "api",
+        "python",
+        "-m",
+        "app.mcp.stdio"
+      ]
+    }
+  }
+};
+function buildSpaceConfig(spaceDefs) {
+  const config = {};
+  if (spaceDefs.length > 0) {
+    config.project_space = [{ id: spaceDefs[0].id }];
+    config.spaces = spaceDefs;
+  }
+  return config;
+}
+function spacesYml(projectSpaceId) {
+  if (!projectSpaceId) {
+    return [
+      `# llmkb space configuration`,
+      `# Managed by \`llmkb init\`. Edit to add or remove spaces.`,
+      `#`,
+      `# Example:`,
+      `# project_space:`,
+      `#   - id: b6087faa-0bf0-4935-98b2-f3100905b99c`,
+      `#     slug: my_project`,
+      `#     name: "My Project"`,
+      `#   dirs: ['app', 'src']`,
+      `# spaces:`,
+      `#   - id: c599f13a-2d75-4e4e-8fb3-03afbac7e115`,
+      `#     name: "Reference Library"`,
+      `#     slug: reference_library`,
+      ``
+    ].join("\n");
+  }
+  const config = {
+    project_space: [{ id: projectSpaceId }]
+  };
+  return `# llmkb space configuration
+# Managed by \`llmkb init\`. Edit to add or remove spaces.
+
+` + stringify2(config, { lineWidth: 120 });
+}
+function configYml() {
+  const defaults = getDefaultPluginConfig();
+  return [
+    `# .llmkb/config.yml \u2014 plugin behavior settings`,
+    `# Managed by \`llmkb init\`. Uncomment fields to override defaults.`,
+    ``,
+    `# llmkb_base_url: ${defaults.llmkb_base_url}`,
+    `#`,
+    `# watch:`,
+    `#   enabled: ${defaults.watch.enabled}`,
+    `#   debounce_ms: ${defaults.watch.debounce_ms}`,
+    `#   gitignore: ${defaults.watch.gitignore}`,
+    `#   llmkbignore: ${defaults.watch.llmkbignore}`,
+    `#   default_verbosity: ${defaults.watch.default_verbosity}`,
+    `#`,
+    `# sync:`,
+    `#   concurrency: ${defaults.sync.concurrency}`,
+    `#   retry_attempts: ${defaults.sync.retry_attempts}`,
+    `#   retry_delay_ms: ${defaults.sync.retry_delay_ms}`,
+    `#`,
+    `# hook:`,
+    `#   timeout_ms: ${defaults.hook.timeout_ms}`,
+    `#   skip: ${defaults.hook.skip}`,
+    `#`,
+    `# debug: ${defaults.debug}`,
+    ``
+  ].join("\n");
+}
+async function writePluginJson(projectDir) {
+  const dir = projectPath(projectDir, ".claude-plugin");
+  await ensureDir(dir);
+  await writeFile3(
+    join3(dir, "plugin.json"),
+    JSON.stringify(PLUGIN_JSON, null, 2) + "\n",
+    "utf-8"
+  );
+}
+async function writeMcpJson(projectDir, platform) {
+  if (platform === "cursor") {
+    const dir = projectPath(projectDir, ".cursor");
+    await ensureDir(dir);
+    await writeFile3(
+      join3(dir, "mcp.json"),
+      JSON.stringify(MCP_JSON_CURSOR, null, 2) + "\n",
+      "utf-8"
+    );
+  } else {
+    await writeFile3(
+      projectPath(projectDir, ".mcp.json"),
+      JSON.stringify(MCP_JSON_CLAUDE, null, 2) + "\n",
+      "utf-8"
+    );
+  }
+}
+async function writeLlmkbDir(projectDir, spaceName, spaceDefs, force) {
+  const dir = projectPath(projectDir, ".llmkb");
+  const written = [];
+  if (!force) {
+    const stamp = await readVersionStamp(projectDir);
+    if (stamp === PACKAGE_VERSION) return written;
+  }
+  await ensureDir(dir);
+  if (spaceDefs && spaceDefs.length > 0) {
+    const config = buildSpaceConfig(spaceDefs);
+    await writeFile3(
+      join3(dir, "spaces.yml"),
+      stringify2(config, { lineWidth: 120 }),
+      "utf-8"
+    );
+  } else {
+    await writeFile3(
+      join3(dir, "spaces.yml"),
+      spacesYml(spaceName) + "\n",
+      "utf-8"
+    );
+  }
+  written.push(".llmkb/spaces.yml");
+  await writeFile3(join3(dir, "config.yml"), configYml(), "utf-8");
+  written.push(".llmkb/config.yml");
+  await writeFile3(join3(dir, ".llmkb-version"), PACKAGE_VERSION + "\n", "utf-8");
+  written.push(".llmkb/.llmkb-version");
+  return written;
+}
+var CURSOR_RULES = [
+  {
+    name: "llmkb-guide.mdc",
+    description: "llmkb overview, architecture, getting started, and how to use llmkb spaces",
+    globs: ["*"],
+    content: [
+      "llmkb is an AI-powered knowledge base. It uses a three-layer model: raw sources (PDFs, code, markdown) -> LLM-generated wiki pages -> knowledge graph.",
+      "",
+      "- Run `docker compose --profile mvp ps` to verify the MCP server is running",
+      "- Use `space_search(space_name, query)` to find relevant wiki pages",
+      "- Use `space_read(space_name, path)` to read a specific wiki page",
+      "- Use `space_graph(space_name, mode, entity)` to explore entity relationships",
+      "- Check `llmkb status` to verify setup is correct"
+    ].join("\n")
+  },
+  {
+    name: "llmkb-query.mdc",
+    description: "Search and read wiki content via MCP tools \u2014 use space_search and space_read",
+    globs: ["*"],
+    content: [
+      "When asked to find information, always:",
+      "",
+      "1. Start with `space_search` to locate relevant wiki pages:",
+      `   space_search(space_name: "my-project", query: "<user's question>")`,
+      "2. Read the full content of the best matching page:",
+      `   space_read(space_name: "my-project", path: "/path/to/page")`,
+      "3. For relationship context, use:",
+      `   space_graph(space_name: "my-project", mode: "neighbours", entity: "<entity name>")`
+    ].join("\n")
+  },
+  {
+    name: "llmkb-sync.mdc",
+    description: "File sync and upload rules \u2014 run llmkb sync after making significant changes",
+    globs: ["*"],
+    content: [
+      "Files modified under this project should be synced to the configured llmkb space.",
+      "",
+      "- Run `llmkb sync` from the project root after significant changes",
+      "- For continuous syncing: `llmkb sync --watch`",
+      "- Files are content-addressed (SHA256); unchanged files skip re-processing",
+      "- Respects .gitignore and .llmkbignore patterns",
+      "- After syncing, use `llmkb status` to check ingestion progress"
+    ].join("\n")
+  },
+  {
+    name: "llmkb-exploring.mdc",
+    description: "Architecture and graph exploration \u2014 use space_graph for entity relationships",
+    globs: ["*"],
+    content: [
+      "When asked about code architecture or entity relationships:",
+      "",
+      "1. Start with `space_guide` for a structured overview:",
+      `   space_guide(space_name: "my-project")`,
+      "2. Explore entity neighbourhoods:",
+      `   space_graph(space_name: "my-project", mode: "neighbours", entity: "<entity>")`,
+      "3. Find paths between entities:",
+      `   space_graph(space_name: "my-project", mode: "path", source: "<source>", target: "<target>")`,
+      "4. Follow up with `space_search` for deeper context"
+    ].join("\n")
+  },
+  {
+    name: "llmkb-admin.mdc",
+    description: "Space management, token setup, credentials, configuration, and llmkb CLI commands",
+    globs: ["*"],
+    content: [
+      "When setting up or managing llmkb:",
+      "",
+      "- `llmkb init` \u2014 scaffold project config files and skills",
+      "- `llmkb init --no-with-skills` \u2014 config-only setup (skip skills)",
+      "- `llmkb init --platform cursor` \u2014 use Cursor-compatible paths",
+      "- `llmkb login --project-space <id>` \u2014 store access token in keychain",
+      "- `llmkb whoami` \u2014 show current user identity and access token status",
+      "- `llmkb status` \u2014 verify versions, config, and installed skills",
+      "- Set LLMKB_ACCESS_TOKEN env var for CI/headless environments"
+    ].join("\n")
+  }
+];
+async function writeCursorRules(projectDir) {
+  const rulesDir = projectPath(projectDir, ".cursor", "rules", "llmkb");
+  await ensureDir(rulesDir);
+  for (const rule of CURSOR_RULES) {
+    const frontmatter = [
+      "---",
+      `name: ${rule.name}`,
+      `description: ${rule.description}`,
+      `globs: ${JSON.stringify(rule.globs)}`,
+      "---",
+      ""
+    ].join("\n");
+    await writeFile3(
+      join3(rulesDir, rule.name),
+      frontmatter + rule.content + "\n",
+      "utf-8"
+    );
+  }
+}
+async function scaffoldConfig(opts) {
+  const projectDir = opts.projectDir ?? process.cwd();
+  const platform = opts.platform ?? "claude";
+  const spaceName = opts.spaceName;
+  const spaceDefs = opts.spaceDefs;
+  const filesWritten = [];
+  await writePluginJson(projectDir);
+  filesWritten.push(".claude-plugin/plugin.json");
+  await writeMcpJson(projectDir, platform);
+  filesWritten.push(platform === "cursor" ? ".cursor/mcp.json" : ".mcp.json");
+  if (platform === "cursor") {
+    await writeCursorRules(projectDir);
+    filesWritten.push(".cursor/rules/llmkb/ (5 rule files)");
+  }
+  const llmkbFiles = await writeLlmkbDir(
+    projectDir,
+    spaceName,
+    spaceDefs,
+    opts.force
+  );
+  for (const f of llmkbFiles) {
+    filesWritten.push(f);
+  }
+  if (opts.withHooks) {
+    const hookFiles = await writeHooks(projectDir, opts.force);
+    for (const f of hookFiles) {
+      filesWritten.push(f);
+    }
+  }
+  return { filesWritten };
+}
+
+// lib/skills.ts
+init_types();
+import { mkdir as mkdir3, writeFile as writeFile4, readFile as readFile2 } from "fs/promises";
+import { existsSync as existsSync3 } from "fs";
+import { join as join4 } from "path";
+var SKILLS = [
+  {
+    name: "llmkb-guide",
+    description: "Use when the user asks how llmkb works, how to get started, or what llmkb can do. Examples: 'How do I use llmkb?', 'What is llmkb?', 'Get started with llmkb', 'Show me the llmkb architecture'",
+    body: [
+      "## Overview",
+      "",
+      "llmkb is an AI-powered knowledge base that transforms documents into an organized, interlinked wiki and knowledge graph. It uses a three-layer model: raw sources (PDFs, code, markdown) \u2192 LLM-generated wiki pages \u2192 structured knowledge graph with entity relationships.",
+      "",
+      "## Quick Start",
+      "",
+      "```",
+      "llmkb status            -- check your current configuration",
+      "llmkb whoami            -- show active space and credentials",
+      "docker compose --profile mvp ps  -- verify MCP server is running",
+      "```",
+      "",
+      "## Workflow",
+      "",
+      "### 1. Verify Setup",
+      "",
+      "Start by checking that everything is configured:",
+      "",
+      "- Run `llmkb status` to confirm version stamps match",
+      "- Run `llmkb whoami` to verify credentials are stored",
+      "- Check `docker compose --profile mvp ps` to confirm the API container is running",
+      "",
+      "### 2. Search the Wiki",
+      "",
+      "Use `space_search` with a specific query targeting your space:",
+      "",
+      "```",
+      "-- space_search example --",
+      `space_search(space_name: "my-project", query: "authentication flow")`,
+      "-- result: ranked list of wiki pages with snippets and confidence scores --",
+      "```",
+      "",
+      "### 3. Read a Page",
+      "",
+      "Get the full content of a wiki page:",
+      "",
+      "```",
+      "-- space_read example --",
+      `space_read(space_name: "my-project", path: "/docs/architecture")`,
+      "-- result: full wiki content with frontmatter, body, and metadata --",
+      "```",
+      "",
+      "### 4. Explore the Graph",
+      "",
+      "When you need to understand how concepts connect:",
+      "",
+      "```",
+      "-- space_graph example --",
+      `space_graph(space_name: "my-project", mode: "neighbours", entity: "AuthModule")`,
+      "-- result: entity nodes, relationship edges, and community clusters --",
+      "```",
+      "",
+      "### 5. Save New Information",
+      "",
+      "Write directly to a space when you discover something new:",
+      "",
+      "```",
+      "-- space_write example --",
+      `space_write(`,
+      `  space_name: "my-project",`,
+      `  path: "/notes/api-pattern",`,
+      `  content: "# API Pattern\\nThe project uses repository pattern with SQLAlchemy."`,
+      `)`,
+      "-- result: new wiki page created in the space --",
+      "```",
+      "",
+      "## Troubleshooting",
+      "",
+      "| Error | Cause | Fix |",
+      "|-------|-------|-----|",
+      '| "Space not found" | Wrong space name | Run `llmkb use` to see configured spaces |',
+      '| "Token required" | Private space needs auth | Run `llmkb login --space <name>` |',
+      "| MCP server timeout | Docker not running | `docker compose --profile mvp ps` to check |",
+      "| Version mismatch | Skills or config out of date | `llmkb init` to re-install |",
+      "",
+      "## Self-Check",
+      "",
+      "- [ ] Active space configured via `llmkb status`",
+      "- [ ] Tokens stored in keychain or env vars",
+      "- [ ] MCP server reachable: `docker compose --profile mvp ps`",
+      "- [ ] Version stamps match package version"
+    ].join("\n")
+  },
+  {
+    name: "llmkb-query",
+    description: "Use when searching or reading wiki content via MCP tools. Examples: 'Search the wiki for X', 'Read this wiki page', 'Find relevant documentation', 'Look up authentication patterns', 'What does the wiki say about pgvector?'",
+    body: [
+      "## Overview",
+      "",
+      "Search and read your llmkb wiki using hybrid full-text + vector search and knowledge graph navigation. Start with `space_search` to find relevant pages, then use `space_read` to get full content.",
+      "",
+      "## Quick Start",
+      "",
+      "```",
+      "-- search for information --",
+      `space_search(space_name: "my-project", query: "pgvector indexing")`,
+      "",
+      "-- read a specific page --",
+      `space_read(space_name: "my-project", path: "/docs/indexing-strategy")`,
+      "```",
+      "",
+      "## Workflow",
+      "",
+      "### 1. Find Relevant Content",
+      "",
+      "Start with `space_search` to locate relevant wiki pages:",
+      "",
+      "```",
+      "-- search with a specific query --",
+      `space_search(space_name: "my-project", query: "authentication flow")`,
+      "",
+      "-- search with confidence filter --",
+      `space_search(space_name: "my-project", query: "database schema", min_confidence: 0.8)`,
+      "```",
+      "",
+      "Returns ranked results with paths, snippets, confidence scores, and entity types.",
+      "",
+      "### 2. Read Full Content",
+      "",
+      "Once you have identified the right page, read it fully:",
+      "",
+      "```",
+      "-- read by path --",
+      `space_read(space_name: "my-project", path: "/docs/architecture")`,
+      "",
+      "-- result includes frontmatter (type, category, source_pages) and full body content --",
+      "```",
+      "",
+      "### 3. Get a Space Overview",
+      "",
+      "For a structured summary of a space's content:",
+      "",
+      "```",
+      "-- overview of all entities and pages --",
+      `space_guide(space_name: "my-project")`,
+      "-- result: summary of entity types, page categories, and top-level relationships --",
+      "```",
+      "",
+      "### 4. Explore Entity Relationships",
+      "",
+      "When search results surface an entity, dig into its connections:",
+      "",
+      "```",
+      "-- find neighbours of a specific entity --",
+      `space_graph(space_name: "my-project", mode: "neighbours", entity: "AuthModule")`,
+      "-- result: all entities directly connected to AuthModule with relationship types --",
+      "```",
+      "",
+      "## Troubleshooting",
+      "",
+      "| Error | Cause | Fix |",
+      "|-------|-------|-----|",
+      "| Empty results | Query too narrow | Broaden terms or check space has content with `space_guide` |",
+      '| "Space not found" | Wrong space name | `llmkb status` to list configured spaces |',
+      "| Path not found | Page path incorrect | Search first with `space_search` to find the exact path |",
+      "| Token error | Expired credentials | `llmkb login --space <name>` |",
+      "",
+      "## Self-Check",
+      "",
+      "- [ ] Used `space_search` first to find relevant pages",
+      "- [ ] Used `space_read` to get full context when snippet is insufficient",
+      "- [ ] Verified the space name matches a configured space",
+      "- [ ] Used `space_graph` for deeper relationship exploration when needed"
+    ].join("\n")
+  },
+  {
+    name: "llmkb-sync",
+    description: "Use when syncing local files to an llmkb space for ingestion. Examples: 'Upload these docs', 'Sync this folder to my wiki', 'Ingest this README', 'Watch this directory for changes', 'Upload my codebase'",
+    body: [
+      "## Overview",
+      "",
+      "Sync local files and codebases to your llmkb spaces for processing and wiki generation. Files are content-addressed (SHA256) so unchanged files skip re-processing. Supports PDF, Markdown, code files, images, and audio.",
+      "",
+      "## Quick Start",
+      "",
+      "```",
+      "llmkb sync                    -- sync current directory to active space",
+      "llmkb sync --space my-project -- sync to a specific space",
+      "llmkb sync --watch            -- watch directory for changes",
+      "```",
+      "",
+      "## Workflow",
+      "",
+      "### 1. Sync Files to a Space",
+      "",
+      "Navigate to the directory containing files you want to ingest and run:",
+      "",
+      "```",
+      "cd /path/to/your/project",
+      "llmkb sync --space my-project",
+      "```",
+      "",
+      "The command will:",
+      "",
+      "1. Walk the directory recursively",
+      "2. Compute SHA256 hashes for each file",
+      "3. Skip unchanged files (cached in `.llmkb/sync-state.json`)",
+      "4. Upload new/changed files via TUS protocol",
+      "5. Report progress per file",
+      "",
+      "### 2. Watch for Changes",
+      "",
+      "Keep a directory synced automatically:",
+      "",
+      "```",
+      "llmkb sync --watch --space my-project",
+      "```",
+      "",
+      "Watcher behaviour:",
+      "",
+      "- Respects `.gitignore` and `.llmkbignore` patterns",
+      "- Debounces rapid file changes",
+      "- Detects file renames by content hash (not path)",
+      "- Press Ctrl+C to stop watching",
+      "",
+      "### 3. Check Sync Status",
+      "",
+      "After syncing, verify ingestion progress:",
+      "",
+      "```",
+      "llmkb status --space my-project",
+      "```",
+      "",
+      "### 4. Query Synced Content",
+      "",
+      "Once processing completes, search the newly ingested content:",
+      "",
+      "```",
+      `space_search(space_name: "my-project", query: "topics from the synced files")`,
+      "```",
+      "",
+      "## Troubleshooting",
+      "",
+      "| Error | Cause | Fix |",
+      "|-------|-------|-----|",
+      "| File skipped | Matches .gitignore or .llmkbignore | Check ignore files |",
+      "| Upload failed | TUS endpoint unreachable | Verify Docker is running |",
+      "| Hash mismatch | File changed during upload | Re-run `llmkb sync` |",
+      '| "No space configured" | No active space | `llmkb use <space-name>` |',
+      "| Sync slow | Large directory | Use `--verbose` to see progress; files over 5MB use chunked TUS uploads |",
+      "",
+      "## Self-Check",
+      "",
+      "- [ ] Files upload successfully (check terminal output for each file)",
+      "- [ ] Ingestion job progresses through phases",
+      "- [ ] Wiki pages generated after processing completes",
+      "- [ ] Unchanged files are skipped (cached by SHA256)"
+    ].join("\n")
+  },
+  {
+    name: "llmkb-exploring",
+    description: "Use when exploring architecture, codebase structure, and entity relationships. Examples: 'How does X work?', 'Show me the codebase architecture', 'What connections exist in this space?', 'Find relationships between these concepts', 'Map the auth module dependencies'",
+    body: [
+      "## Overview",
+      "",
+      "Explore entity relationships, knowledge graph structure, and how different pieces of information connect in your llmkb spaces. Use graph queries to discover neighbours, find paths between entities, and get structured space overviews.",
+      "",
+      "## Quick Start",
+      "",
+      "```",
+      "-- explore neighbours of an entity --",
+      `space_graph(space_name: "my-project", mode: "neighbours", entity: "AuthModule")`,
+      "",
+      "-- find path between two entities --",
+      `space_graph(space_name: "my-project", mode: "path", source: "ServiceA", target: "ServiceB")`,
+      "```",
+      "",
+      "## Workflow",
+      "",
+      "### 1. Get a Space Overview",
+      "",
+      "Start with `space_guide` for a high-level summary:",
+      "",
+      "```",
+      `space_guide(space_name: "my-project")`,
+      "-- result: entity count, relationship count, page categories, top-level clusters --",
+      "```",
+      "",
+      "### 2. Explore Neighbourhoods",
+      "",
+      "Drill into a specific entity to see its direct connections:",
+      "",
+      "```",
+      `space_graph(space_name: "my-project", mode: "neighbours", entity: "AuthModule")`,
+      "-- result: all entities directly connected to AuthModule with relationship types and confidence scores --",
+      "```",
+      "",
+      "### 3. Find Paths",
+      "",
+      "Discover how two entities connect through intermediate nodes:",
+      "",
+      "```",
+      `space_graph(space_name: "my-project", mode: "path", source: "Database", target: "UserService")`,
+      "-- result: shortest path showing each hop with relationship type --",
+      "```",
+      "",
+      "### 4. Search Within the Exploration",
+      "",
+      "When you find interesting entities, search for more details:",
+      "",
+      "```",
+      `space_search(space_name: "my-project", query: "user authentication")`,
+      "```",
+      "",
+      "## Troubleshooting",
+      "",
+      "| Error | Cause | Fix |",
+      "|-------|-------|-----|",
+      "| Empty graph | Space has no processed content | Run `llmkb sync` to upload files first |",
+      '| "Entity not found" | Wrong entity name | Use `space_search` to find the exact label |',
+      "| No path found | Entities not connected in the graph | Try broader search to find bridging entities |",
+      "| Graph too large | Too many neighbours | Narrow the entity or use `space_search` instead |",
+      "",
+      "## Self-Check",
+      "",
+      "- [ ] Started with `space_guide` for orientation",
+      "- [ ] Used `space_graph` with `neighbours` mode for direct connections",
+      "- [ ] Used `space_graph` with `path` mode for indirect connections",
+      "- [ ] Followed up with `space_search` for deeper context"
+    ].join("\n")
+  },
+  {
+    name: "llmkb-admin",
+    description: "Use when managing spaces, tokens, configuration, or credentials. Examples: 'Show my space members', 'Configure a new space', 'Manage API tokens', 'Switch active space', 'Check my credentials', 'Set up a new project with llmkb'",
+    body: [
+      "## Overview",
+      "",
+      "Manage llmkb spaces, API tokens, configuration settings, and credentials. The CLI provides commands for switching spaces, authenticating, and verifying setup.",
+      "",
+      "## Quick Start",
+      "",
+      "```",
+      "llmkb status              -- check version stamps and active config",
+      "llmkb use my-project      -- switch active space",
+      "llmkb login --space admin -- store credentials for a space",
+      "```",
+      "",
+      "## Workflow",
+      "",
+      "### 1. Initialise a Project",
+      "",
+      "Set up a new project with llmkb:",
+      "",
+      "```",
+      "cd /path/to/project",
+      "llmkb init --space my-project",
+      "```",
+      "",
+      "This creates:",
+      "",
+      "- `.claude-plugin/plugin.json` \u2014 plugin metadata for discovery",
+      "- `.mcp.json` \u2014 MCP server registration with Docker stdio transport",
+      "- `.llmkb/spaces.yml` \u2014 space configuration",
+      "- `.llmkb/config.yml` \u2014 plugin behaviour settings",
+      "- `.claude/skills/llmkb/` \u2014 5 Claude Code skills",
+      "",
+      "For Cursor: `llmkb init --platform cursor` writes equivalent `.cursor/` files.",
+      "",
+      "To skip skill installation: `llmkb init --no-with-skills` (for config-only setup).",
+      "",
+      "### 2. Authenticate",
+      "",
+      "Store credentials for a space after init:",
+      "",
+      "```",
+      "llmkb login --space my-project",
+      "```",
+      "",
+      "This stores the space token in the OS keychain. For CI/headless environments, set the `LLMKB_TOKEN` environment variable instead.",
+      "",
+      "### 3. Switch Spaces",
+      "",
+      "When working with multiple spaces:",
+      "",
+      "```",
+      "llmkb use client-project",
+      "llmkb login --space client-project",
+      "llmkb status --space client-project",
+      "```",
+      "",
+      "### 4. Verify Setup",
+      "",
+      "Check that everything is configured correctly:",
+      "",
+      "```",
+      "llmkb status",
+      "llmkb whoami",
+      "```",
+      "",
+      "The `status` command warns on:",
+      "",
+      "- Config version mismatch: `llmkb init` to update",
+      "- Skill version mismatch: `llmkb init` to re-install skills",
+      "- Missing or expired tokens",
+      "",
+      "### 5. Token Management",
+      "",
+      "- Space tokens grant read access to a specific space",
+      "- Admin tokens grant write/admin access",
+      "- Tokens are stored in the OS keychain (requires `keychain` package)",
+      "- Set `LLMKB_TOKEN` / `LLMKB_ADMIN_TOKEN` env vars for CI",
+      "- Token groups allow sharing a single token across multiple spaces",
+      "",
+      "## Troubleshooting",
+      "",
+      "| Error | Cause | Fix |",
+      "|-------|-------|-----|",
+      '| "Version mismatch" | Config or skills out of date | `llmkb init` to update |',
+      '| "Not found: .llmkb/" | Project not initialised | `llmkb init` first |',
+      "| Keychain access denied | Missing keychain permission | Fall back to `LLMKB_TOKEN` env var |",
+      "| Token expired | Credentials rotated | `llmkb login --space <name>` |",
+      "| Multiple spaces confusing | Wrong active space | `llmkb use <name>` to switch |",
+      "",
+      "## Self-Check",
+      "",
+      "- [ ] Project initialised with `llmkb init`",
+      "- [ ] Tokens stored and accessible (keychain or env vars)",
+      "- [ ] Correct space is active via `llmkb use`",
+      "- [ ] Version stamps match package version (`llmkb status`)",
+      "- [ ] MCP server is running: `docker compose --profile mvp ps`"
+    ].join("\n")
+  }
+];
+async function installSkills(platform = "claude", projectDir) {
+  if (platform === "cursor") {
+    return 0;
+  }
+  const projectRoot = projectDir ?? process.cwd();
+  const targetDir = join4(projectRoot, ".claude", "skills", "llmkb");
+  for (const skill of SKILLS) {
+    const skillDir = join4(targetDir, skill.name);
+    await mkdir3(skillDir, { recursive: true });
+    const trigger = skill.name.replace("llmkb-", "/llmkb-");
+    const frontmatter = [
+      "---",
+      `name: ${skill.name}`,
+      `description: ${skill.description}`,
+      `trigger: ${trigger}`,
+      "---",
+      ""
+    ].join("\n");
+    await writeFile4(
+      join4(skillDir, "SKILL.md"),
+      frontmatter + skill.body + "\n",
+      "utf-8"
+    );
+    await writeFile4(
+      join4(skillDir, ".llmkb-version"),
+      PACKAGE_VERSION + "\n",
+      "utf-8"
+    );
+  }
+  return SKILLS.length;
+}
+async function checkSkillVersions(skillsDir) {
+  const mismatches = [];
+  if (!existsSync3(skillsDir)) return mismatches;
+  const { readdir: readdir2 } = await import("fs/promises");
+  const entries = await readdir2(skillsDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const versionPath = join4(skillsDir, entry.name, ".llmkb-version");
+    try {
+      const content = await readFile2(versionPath, "utf-8");
+      const installedVersion = content.split("\n")[0]?.trim();
+      if (installedVersion && installedVersion !== PACKAGE_VERSION) {
+        mismatches.push({
+          name: entry.name,
+          installed: installedVersion,
+          current: PACKAGE_VERSION
+        });
+      }
+    } catch {
+      mismatches.push({
+        name: entry.name,
+        installed: "(none)",
+        current: PACKAGE_VERSION
+      });
+    }
+  }
+  return mismatches;
+}
+
+// src/commands/init.ts
+function rl() {
+  return readline.createInterface({ input: stdin, output: stdout });
+}
+async function promptSpace(rl2, index) {
+  console.log(`
+--- Space #${index + 1} ---`);
+  const id = await rl2.question("  Space UUID (e.g. b6087faa-...): ");
+  if (!id.trim()) return null;
+  const name = await rl2.question(`  Name (optional): `);
+  return {
+    id: id.trim(),
+    ...name.trim() ? { name: name.trim() } : {}
+  };
+}
+async function interactiveSetup() {
+  const rli = rl();
+  const spaceDefs = [];
+  try {
+    console.log("llmkb init \u2014 interactive setup");
+    console.log("Configure one or more spaces for this project.");
+    console.log("Press Enter with an empty space UUID to finish.\n");
+    let index = 0;
+    while (true) {
+      const def = await promptSpace(rli, index);
+      if (!def) break;
+      spaceDefs.push(def);
+      index++;
+    }
+    if (spaceDefs.length === 0) {
+      console.log("\nNo spaces configured. A template config will be created.");
+    } else {
+      console.log(`
+Configured ${spaceDefs.length} space(s).`);
+    }
+  } finally {
+    rli.close();
+  }
+  return { spaceDefs };
+}
+var initCommand = new Command2("init").description("Scaffold llmkb config files and skills").argument("[directory]", "Target directory (defaults to cwd)").option(
+  "-p, --platform <type>",
+  "Target platform: claude or cursor",
+  "claude"
+).option("--with-skills", "Install Claude Code skills").option("--without-skills", "Skip skill installation").option("--with-hooks", "Install Claude Code hooks (default: false)", false).option(
+  "--non-interactive",
+  "Skip confirmation prompts (for CI/headless environments)"
+).action(
+  async (directory, opts) => {
+    const targetDir = directory ? resolve4(process.cwd(), directory) : process.cwd();
+    const platform = opts.platform === "cursor" ? "cursor" : "claude";
+    const interactive = !opts.nonInteractive;
+    const installSkillsFlag = opts.withSkills ?? !opts.withoutSkills;
+    let spaceDefs;
+    if (interactive) {
+      const result = await interactiveSetup();
+      spaceDefs = result.spaceDefs;
+    }
+    if (interactive) {
+      console.log(
+        "\nThis will create the following files in the current directory:"
+      );
+      console.log("  - .claude-plugin/plugin.json");
+      console.log(
+        `  - ${platform === "cursor" ? ".cursor/mcp.json" : ".mcp.json"}`
+      );
+      console.log("  - .llmkb/spaces.yml");
+      console.log("  - .llmkb/config.yml");
+      console.log("  - .llmkb/.llmkb-version");
+      console.log("  - .claude/skills/llmkb/ (5 skills)");
+      if (opts.withHooks) {
+        console.log("  - .claude/hooks/llmkb/ (hooks.json + scripts)\n");
+      }
+    }
+    try {
+      const { filesWritten } = await scaffoldConfig({
+        platform,
+        spaceDefs,
+        projectDir: targetDir,
+        withHooks: opts.withHooks
+      });
+      console.log(`Created ${filesWritten.length} config file(s):`);
+      for (const f of filesWritten) {
+        console.log(`  \u2714 ${f}`);
+      }
+      if (installSkillsFlag) {
+        const skillCount = await installSkills(platform, targetDir);
+        console.log(
+          `  \u2714 ${skillCount} skills installed to .claude/skills/llmkb/`
+        );
+      }
+      const loginSpace = spaceDefs?.[0]?.id;
+      if (loginSpace) {
+        console.log(
+          `
+Run \`llmkb login --project-space ${loginSpace}\` to authenticate.`
+        );
+      }
+      console.log("\nPost-install note:");
+      console.log(
+        "  Docker --profile mvp : Used for MCP tools only (what this config creates)."
+      );
+      console.log(
+        "  Docker --profile poc : Use for full stack with Nuxt frontend on port 3000."
+      );
+      console.log(
+        "  See infra/mcp/claude_desktop_config.example.json for the alternative."
+      );
+      console.log("\nDone. Run `llmkb status` to verify the installation.");
+    } catch (err) {
+      console.error("Error:", err.message);
+      process.exit(1);
+    }
+  }
+);
+
+// src/commands/login.ts
+import { Command as Command3 } from "commander";
+
+// lib/config.ts
+import { env } from "process";
+var DEFAULT_ENDPOINT = "http://localhost:8000";
+function getConfig() {
+  return {
+    endpoint: env["LLMKB_ENDPOINT"] ?? DEFAULT_ENDPOINT
+  };
+}
+
+// lib/credentials.ts
+import { env as env2 } from "process";
+var kcGetPassword = null;
+var kcSetPassword = null;
+var kcDeletePassword = null;
+var keychainAvailable = false;
+async function ensureKeychain() {
+  if (keychainAvailable) return true;
+  try {
+    const mod = await import("keychain");
+    const kc = mod.default ?? mod;
+    if (typeof kc.setPassword === "function") {
+      kcGetPassword = kc.getPassword.bind(kc);
+      kcSetPassword = kc.setPassword.bind(kc);
+      kcDeletePassword = kc.deletePassword.bind(kc);
+      keychainAvailable = true;
+      return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+async function getToken() {
+  const envVal = env2["LLMKB_ACCESS_TOKEN"];
+  if (envVal) return envVal;
+  const kcToken = await keychainGet();
+  if (kcToken) return kcToken;
+  return null;
+}
+async function keychainGet() {
+  const available = await ensureKeychain();
+  if (!available) return null;
+  return new Promise((resolve8) => {
+    try {
+      kcGetPassword(
+        { service: "llmkb", account: "user/access_token" },
+        (err, password) => {
+          if (err) resolve8(null);
+          else resolve8(password);
+        }
+      );
+    } catch {
+      resolve8(null);
+    }
+  });
+}
+async function setToken(token) {
+  const available = await ensureKeychain();
+  if (!available) {
+    throw new Error(
+      "Keychain is not available. Set LLMKB_ACCESS_TOKEN env var instead."
+    );
+  }
+  return new Promise((resolve8, reject) => {
+    kcSetPassword(
+      {
+        service: "llmkb",
+        account: "user/access_token",
+        password: token
+      },
+      (err) => {
+        if (err) reject(err);
+        else resolve8();
+      }
+    );
+  });
+}
+async function deleteToken() {
+  const available = await ensureKeychain();
+  if (!available) return;
+  return new Promise((resolve8, reject) => {
+    kcDeletePassword(
+      { service: "llmkb", account: "user/access_token" },
+      (err) => {
+        if (err) reject(err);
+        else resolve8();
+      }
+    );
+  });
+}
+
+// src/commands/login.ts
+init_parser();
+
+// lib/sync-spaces-config.ts
+init_parser();
+import { readFile as readFile3, writeFile as writeFile5 } from "fs/promises";
+import { existsSync as existsSync4 } from "fs";
+import { join as join5 } from "path";
+async function syncRelatedSpaces(projectDir, endpoint, token) {
+  const config = await readSpaceConfig(projectDir);
+  if (!config?.project_space?.length) {
+    return { added: 0, alreadyPresent: 0, removed: 0 };
+  }
+  const projectSpaceId = config.project_space[0].id;
+  const relations = await fetchRelatedSpaces(endpoint, token, projectSpaceId);
+  const backendIds = new Set(relations.map((r) => r.id));
+  const syncedIdsPath = join5(projectDir, ".llmkb", "sync-relations.json");
+  const prevSyncedIds = await readSyncedIds(syncedIdsPath);
+  let added = 0;
+  let alreadyPresent = 0;
+  let removed = 0;
+  if (config.spaces) {
+    for (const s of config.spaces) {
+      if (s.id === projectSpaceId) {
+        await removeSpaceEntry(projectDir, s.id);
+        removed++;
+      }
+    }
+  }
+  for (const rel of relations) {
+    if (rel.id === projectSpaceId) continue;
+    const existingIds = /* @__PURE__ */ new Set([
+      ...(config.spaces ?? []).map((s) => s.id),
+      ...(config.project_space ?? []).map((s) => s.id)
+    ]);
+    if (existingIds.has(rel.id)) {
+      alreadyPresent++;
+    } else {
+      await addSpaceEntry(projectDir, rel.id, rel.name);
+      added++;
+    }
+  }
+  if (prevSyncedIds.size > 0 && config.spaces) {
+    for (const s of config.spaces) {
+      if (prevSyncedIds.has(s.id) && !backendIds.has(s.id)) {
+        await removeSpaceEntry(projectDir, s.id);
+        removed++;
+      }
+    }
+  }
+  await writeSyncedIds(syncedIdsPath, backendIds);
+  return { added, alreadyPresent, removed };
+}
+async function readSyncedIds(filePath) {
+  try {
+    if (existsSync4(filePath)) {
+      const raw = await readFile3(filePath, "utf-8");
+      const parsed = JSON.parse(raw);
+      return new Set(parsed);
+    }
+  } catch {
+  }
+  return /* @__PURE__ */ new Set();
+}
+async function writeSyncedIds(filePath, ids) {
+  await writeFile5(filePath, JSON.stringify([...ids], null, 2) + "\n", "utf-8");
+}
+async function fetchRelatedSpaces(endpoint, token, spaceId) {
+  try {
+    const url = `${endpoint.replace(/\/+$/, "")}/api/spaces/${encodeURIComponent(spaceId)}/relations`;
+    const res = await fetch(url, {
+      headers: { Authorization: `Bearer ${token}` }
+    });
+    if (!res.ok) return [];
+    const body = await res.json();
+    if (!body.data) return [];
+    return body.data.filter((d) => d.attributes?.relatedSpaceId).map((d) => ({
+      id: d.attributes.relatedSpaceId,
+      name: d.attributes?.relatedSpaceName ?? void 0
+    }));
+  } catch {
+    return [];
+  }
+}
+
+// src/commands/login.ts
+import { createInterface as createInterface2 } from "readline/promises";
+
+// lib/color.ts
+import pc from "picocolors";
+var success = pc.green;
+var error = pc.red;
+var warning = pc.yellow;
+var info = pc.cyan;
+var highlight = (s) => pc.bold(pc.white(s));
+var muted = pc.dim;
+var ICON_COLORS = {
+  "\u2714": success,
+  "\u2713": success,
+  "\u2716": error,
+  "\u2717": error,
+  "\u26A0": warning,
+  "\u2139": info,
+  "\u231A": info
+};
+function label(icon, text) {
+  const colorFn = ICON_COLORS[icon];
+  if (colorFn) {
+    return `${colorFn(icon)} ${text}`;
+  }
+  return `${icon} ${text}`;
+}
+
+// src/commands/login.ts
+function prompt(query) {
+  const rl2 = createInterface2({ input: process.stdin, output: process.stdout });
+  return rl2.question(query).finally(() => rl2.close());
+}
+async function validateToken(endpoint, token) {
+  try {
+    const url = `${endpoint.replace(/\/+$/, "")}/api/v1/auth/me`;
+    const res = await fetch(url, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${token}` }
+    });
+    const body = await res.json();
+    if (res.ok && body.data?.attributes?.token_status === "active") {
+      return {
+        valid: true,
+        user_id: body.data.attributes.user_id,
+        email: body.data.attributes.email,
+        token_status: body.data.attributes.token_status
+      };
+    }
+    const detail = body.errors?.[0]?.detail ?? body.data?.attributes?.token_status ?? "Token rejected";
+    return { valid: false, error: detail };
+  } catch (err) {
+    return {
+      valid: false,
+      error: `Cannot reach server: ${err.message}`
+    };
+  }
+}
+async function discoverSpaces(endpoint, token) {
+  try {
+    const url = `${endpoint.replace(/\/+$/, "")}/api/v1/auth/spaces`;
+    const res = await fetch(url, {
+      headers: { Authorization: `Bearer ${token}` }
+    });
+    const body = await res.json();
+    if (res.ok && body.data) {
+      return body.data.filter((d) => d.attributes?.space_id).map((d) => ({
+        space_id: d.attributes.space_id,
+        space_name: d.attributes.space_name ?? d.attributes.space_id,
+        slug: d.attributes.slug ?? "",
+        role: d.attributes.role ?? "guest"
+      }));
+    }
+    return [];
+  } catch {
+    return [];
+  }
+}
+var loginCommand = new Command3("login").description("Authenticate with an access token and configure the project space").requiredOption("-p, --project-space <id>", "Project space UUID to use as primary space").action(async (opts) => {
+  const config = getConfig();
+  const projectSpaceId = opts.projectSpace;
+  const endpoint = config.endpoint;
+  const existing = await getToken();
+  if (existing) {
+    console.log(info("Already logged in."));
+    const ans = await prompt(`${warning("Re-authenticate? (y/N):")} `);
+    if (ans.toLowerCase() !== "y") {
+      console.log(muted("Aborted."));
+      return;
+    }
+  }
+  const accessToken = await prompt(`${info("Access token (paste, then Enter):")} `);
+  if (!accessToken.trim()) {
+    console.log(error("Access token is required."));
+    process.exit(1);
+  }
+  console.log(`  ${muted("Validating token against")} ${info(endpoint)}${muted("...")}`);
+  const result = await validateToken(endpoint, accessToken.trim());
+  if (!result.valid) {
+    console.log(`${error("Authentication failed:")} ${result.error}`);
+    process.exit(1);
+  }
+  console.log(`  ${success("\u2714 Authenticated as")} ${info(result.email ?? result.user_id ?? "unknown")} ${muted(`(status: ${result.token_status})`)}`);
+  await setToken(accessToken.trim());
+  console.log(`  ${success("\u2714 Access token stored in keychain.")}`);
+  console.log(`  ${muted("Discovering accessible spaces...")}`);
+  const spaces = await discoverSpaces(endpoint, accessToken.trim());
+  console.log(`  ${info(`Found ${spaces.length} space(s).`)}`);
+  const projectRoot = findProjectRoot();
+  const spaceConfig = {
+    project_space: [{ id: projectSpaceId }],
+    spaces: spaces.map((s) => ({
+      id: s.space_id,
+      name: s.space_name,
+      slug: s.slug || void 0
+    }))
+  };
+  if (projectRoot) {
+    await writeSpaceConfig(projectRoot, spaceConfig);
+    const syncResult = await syncRelatedSpaces(projectRoot, endpoint, accessToken.trim());
+    if (syncResult.added > 0) {
+      console.log(`  ${info(`\u2139 Also synced ${syncResult.added} related space(s) from space relations.`)}`);
+    }
+    console.log(`  ${success("\u2714 Project space set to")} ${info(projectSpaceId)}`);
+  }
+  console.log(`
+${success("Logged in.")} ${muted("Accessible spaces:")}`);
+  for (const s of spaces) {
+    const roleColor = s.role === "owner" || s.role === "admin" ? success : warning;
+    console.log(`  ${muted(s.space_id)} ${roleColor(`(${s.role})`)}`);
+  }
+  const verifyResult = await validateToken(endpoint, accessToken.trim());
+  if (verifyResult.valid) {
+    console.log(`  ${success("\u2714 Connection verified.")} ${muted(`User: ${verifyResult.email}`)}`);
+  }
+});
+
+// src/commands/logout.ts
+import { Command as Command4 } from "commander";
+var logoutCommand = new Command4("logout").description("Remove the access token from the OS keychain").action(async () => {
+  await deleteToken();
+  console.log(`${success("\u2714")} ${muted("Access token removed from keychain.")}`);
+});
+
+// src/commands/add.ts
+init_parser();
+import { Command as Command5 } from "commander";
+var addCommand = new Command5("add").description("Add a space to .llmkb/spaces.yml").requiredOption("-s, --space <id>", "Space UUID to add").option("-n, --name <name>", "Optional space name").action(async (opts) => {
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) {
+    console.log(error("No .llmkb/ directory found. Run `llmkb init` first."));
+    process.exit(1);
+  }
+  const ok = await addSpaceEntry(projectRoot, opts.space, opts.name);
+  if (ok) {
+    console.log(`${success("\u2714")} Space ${info(opts.space)} added to .llmkb/spaces.yml.`);
+  } else {
+    console.log(error("Could not find or parse .llmkb/spaces.yml."));
+    process.exit(1);
+  }
+});
+
+// src/commands/remove.ts
+init_parser();
+import { Command as Command6 } from "commander";
+var removeCommand = new Command6("remove").description("Remove a space from .llmkb/spaces.yml by id").requiredOption("-s, --space <id>", "Space UUID to remove").action(async (opts) => {
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) {
+    console.log(error("No .llmkb/ directory found. Run `llmkb init` first."));
+    process.exit(1);
+  }
+  const ok = await removeSpaceEntry(projectRoot, opts.space);
+  if (ok) {
+    console.log(`${success("\u2714")} Space ${info(opts.space)} removed from .llmkb/spaces.yml.`);
+  } else {
+    console.log(warning(`Space "${opts.space}" not found in .llmkb/spaces.yml.`));
+    process.exit(1);
+  }
+});
+
+// src/commands/spaces.ts
+init_parser();
+import { Command as Command7 } from "commander";
+import { createInterface as createInterface3 } from "readline/promises";
+function prompt2(query) {
+  const rl2 = createInterface3({ input: process.stdin, output: process.stdout });
+  return rl2.question(query).finally(() => rl2.close());
+}
+var spacesCommand = new Command7("spaces").description("List all spaces in .llmkb/spaces.yml").option("--delete-all", "Remove all space entries (requires confirmation)").action(async (opts) => {
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) {
+    console.log(error("No .llmkb/ directory found. Run `llmkb init` first."));
+    process.exit(1);
+  }
+  const config = await readSpaceConfig(projectRoot);
+  if (!config) {
+    console.log(warning("No .llmkb/spaces.yml found."));
+    return;
+  }
+  if (opts.deleteAll) {
+    console.log(warning("This will remove ALL space entries from .llmkb/spaces.yml."));
+    const ans = await prompt2(`${warning("Continue? (y/N):")} `);
+    if (ans.toLowerCase() !== "y") {
+      console.log(muted("Aborted."));
+      return;
+    }
+    await deleteAllSpaces(projectRoot);
+    console.log(success("All space entries removed."));
+    return;
+  }
+  if (config.project_space && config.project_space.length > 0) {
+    console.log(info("Project space:"));
+    for (const ps of config.project_space) {
+      console.log(`  ${ps.id}${ps.name ? success(` (${ps.name})`) : ""}`);
+    }
+  }
+  if (config.spaces && config.spaces.length > 0) {
+    console.log(info("Additional spaces:"));
+    for (const s of config.spaces) {
+      console.log(`  ${muted(s.id)}${s.name ? ` (${s.name})` : ""}`);
+    }
+  }
+  if ((!config.project_space || config.project_space.length === 0) && (!config.spaces || config.spaces.length === 0)) {
+    console.log(warning("No spaces configured."));
+  }
+});
+
+// src/commands/update.ts
+init_parser();
+import { Command as Command8 } from "commander";
+var updateCommand = new Command8("update").description("Update the project space in .llmkb/spaces.yml").requiredOption("-p, --project-space <id>", "New project space UUID").action(async (opts) => {
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) {
+    console.log(error("No .llmkb/ directory found. Run `llmkb init` first."));
+    process.exit(1);
+  }
+  const ok = await updateProjectSpace(projectRoot, opts.projectSpace);
+  if (ok) {
+    console.log(`${success("\u2714")} Project space updated to ${info(opts.projectSpace)}.`);
+  } else {
+    console.log(error("Could not update project space in .llmkb/spaces.yml."));
+    process.exit(1);
+  }
+});
+
+// src/commands/whoami.ts
+import { Command as Command9 } from "commander";
+var whoamiCommand = new Command9("whoami").description("Show current authenticated user and access token status").action(async () => {
+  const config = getConfig();
+  const token = await getToken();
+  if (!token) {
+    console.log(error("Not logged in."));
+    console.log(`Run ${info("`llmkb login --project-space <id>`")} to authenticate.`);
+    return;
+  }
+  console.log(`${muted("Access token:")} ${success("\u2714 present")}`);
+  try {
+    const url = `${config.endpoint}/api/v1/auth/me`;
+    const res = await fetch(url, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${token}` }
+    });
+    if (res.ok) {
+      const body = await res.json();
+      const attrs = body.data?.attributes;
+      if (attrs) {
+        console.log(`  ${muted("User:")}         ${info(attrs.email ?? attrs.user_id)}`);
+        console.log(`  ${muted("Token status:")} ${success(attrs.token_status ?? "active")}`);
+        if (attrs.expires_at) {
+          console.log(`  ${muted("Expires at:")}   ${attrs.expires_at}`);
+        }
+      }
+    } else {
+      const statusText = res.status === 401 ? error("invalid or expired") : warning(`server returned ${res.status}`);
+      console.log(`  ${muted("Token status:")} ${statusText}`);
+      console.log(`  ${muted("Endpoint:")}     ${config.endpoint}`);
+    }
+  } catch {
+    console.log(`  ${muted("Endpoint:")}     ${warning(config.endpoint + " (unreachable)")}`);
+  }
+});
+
+// src/commands/use.ts
+import { Command as Command10 } from "commander";
+import { existsSync as existsSync5 } from "fs";
+import { join as join6 } from "path";
+init_parser();
+init_parser();
+init_types();
+var useCommand = new Command10("use").description("Set the project space in .llmkb/spaces.yml").argument("<space-id>", "Space UUID to set as project space").action(async (spaceId) => {
+  const config = getConfig();
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) {
+    console.log(error("No .llmkb/ directory found. Run `llmkb init` first."));
+    process.exit(1);
+  }
+  const spacesFile = join6(projectRoot, ".llmkb", "spaces.yml");
+  if (!existsSync5(spacesFile)) {
+    console.log(error("No .llmkb/spaces.yml found. Run `llmkb init` first."));
+    process.exit(1);
+  }
+  const stamp = await readVersionStamp(projectRoot);
+  if (stamp && stamp !== PACKAGE_VERSION) {
+    console.log(warning(`  \u26A0 Version stamp mismatch (${stamp}). Re-run \`llmkb init\` to update.`));
+  }
+  const token = await getToken();
+  if (!token) {
+    console.log(warning("No access token found."));
+    console.log(`Run ${info("`llmkb login --project-space <id>`")} to authenticate.`);
+  }
+  const url = `${config.endpoint}/api/v1/auth/me`;
+  try {
+    const res = await fetch(url, {
+      method: "GET",
+      headers: token ? { Authorization: `Bearer ${token}` } : {}
+    });
+    if (!res.ok) {
+      console.log(warning(`Warning: Cannot reach server \u2014 returned ${res.status}`));
+    }
+  } catch {
+    console.log(warning(`Warning: Cannot reach ${config.endpoint} \u2014 server may be offline`));
+  }
+  const updated = await updateProjectSpace(projectRoot, spaceId);
+  if (updated) {
+    console.log(`${success("\u2714")} Project space set to ${info(spaceId)}.`);
+  } else {
+    console.log(error("Failed to update .llmkb/spaces.yml."));
+    process.exit(1);
+  }
+});
+
+// src/commands/status.ts
+init_parser();
+init_types();
+import { Command as Command11 } from "commander";
+import { existsSync as existsSync6 } from "fs";
+import { join as join7 } from "path";
+var statusCommand = new Command11("status").description("Show version stamps, configuration, and access token status").action(async () => {
+  console.log(`${info("llmkb status")}
+`);
+  console.log(`  ${muted("Package version:")}  ${PACKAGE_VERSION}`);
+  const token = await getToken();
+  const tokenStatus = token ? success("\u2714 present") : error("\u2717 missing");
+  console.log(`  ${muted("Access token:")}     ${tokenStatus}`);
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) {
+    console.log(`  ${muted("Project root:")}     ${warning("(not found \u2014 run `llmkb init`)")}`);
+    console.log(`  ${muted("Config version:")}   ${warning("(not found)")}`);
+    console.log(`  ${muted("Skills installed:")} 0`);
+    return;
+  }
+  console.log(`  ${muted("Project root:")}     ${projectRoot}`);
+  const configVersion = await readVersionStamp(projectRoot);
+  if (configVersion) {
+    const versionOk = configVersion === PACKAGE_VERSION;
+    console.log(`  ${muted("Config version:")}   ${versionOk ? success(configVersion) : warning(configVersion)}`);
+    if (!versionOk) {
+      console.log(`  ${warning("\u26A0 Version mismatch! Re-run `llmkb init` to update config.")}`);
+    }
+  } else {
+    console.log(`  ${muted("Config version:")}   ${warning("(not found \u2014 run `llmkb init`)")}`);
+  }
+  const spaceConfig = await readSpaceConfig(projectRoot);
+  if (spaceConfig) {
+    if (spaceConfig.project_space && spaceConfig.project_space.length > 0) {
+      const ps = spaceConfig.project_space[0];
+      console.log(`  ${muted("Project space:")}    ${info(ps.id)}${ps.name ? ` (${ps.name})` : ""}`);
+    } else {
+      console.log(`  ${muted("Project space:")}    ${warning("(not configured)")}`);
+    }
+    const spaceCount = spaceConfig.spaces?.length ?? 0;
+    console.log(`  ${muted("Spaces defined:")}   ${spaceCount}`);
+    if (spaceCount > 0 && spaceConfig.spaces) {
+      console.log(`  ${muted(spaceConfig.spaces.map((s) => s.id).join(", "))}`);
+    }
+  } else {
+    console.log(`  ${muted("Project space:")}    ${warning("(not configured)")}`);
+  }
+  const skillsDir = join7(projectRoot, ".claude", "skills", "llmkb");
+  if (existsSync6(skillsDir)) {
+    const mismatches = await checkSkillVersions(skillsDir);
+    const entryCount = await (await import("fs/promises")).readdir(skillsDir, { withFileTypes: true }).then((e) => e.filter((x) => x.isDirectory()).length).catch(() => 0);
+    console.log(`  ${muted("Skills installed:")} ${entryCount}`);
+    for (const m of mismatches) {
+      console.log(`  ${warning(`  ${m.name}: ${m.installed} \u26A0 mismatch`)}`);
+    }
+    if (mismatches.length > 0) {
+      console.log(`  ${warning("\u26A0 Some skills have version mismatches. Re-run `llmkb init`.")}`);
+    }
+  } else {
+    console.log(`  ${muted("Skills installed:")} 0 (run \`llmkb init\`)`);
+  }
+});
+
+// src/commands/sync.ts
+import { Command as Command12 } from "commander";
+import { join as join11 } from "path";
+init_parser();
+init_sync_state();
+
+// lib/sync.ts
+import { readdir, stat as fsStat, readFile as readFile5 } from "fs/promises";
+import { join as join9, relative, resolve as resolve6 } from "path";
+import ignore from "ignore";
+import * as tus from "tus-js-client";
+import { existsSync as existsSync8 } from "fs";
+init_parser();
+var IGNORE_FILES = [".gitignore", ".llmkbignore"];
+var DEFAULT_SKIP_PATTERNS = [
+  "node_modules/**",
+  ".git/**",
+  ".llmkb/**",
+  ".claude/**",
+  ".cursor/**",
+  ".next/**",
+  "dist/**",
+  ".venv/**",
+  "__pycache__/**",
+  "*.pyc",
+  "*.exe",
+  "*.dll",
+  "*.so",
+  "*.dylib",
+  "*.bin",
+  // Test & ephemeral artifacts — exclude by default to avoid polluting
+  // the knowledge graph with test fixtures, snapshots, and build artifacts.
+  "**/__tests__/**",
+  "**/__snapshots__/**",
+  "**/test/**",
+  "**/tests/**",
+  "**/*.test.*",
+  "**/*.spec.*",
+  "**/fixtures/**",
+  "**/coverage/**",
+  "*.log",
+  "tmp/**",
+  "temp/**"
+];
+async function buildFilter(projectDir, targetDir, respectGitignore, respectLlmkbignore) {
+  const ig = ignore().add(DEFAULT_SKIP_PATTERNS);
+  const searchDirs = [projectDir, targetDir];
+  const seen = /* @__PURE__ */ new Set();
+  for (const baseDir of searchDirs) {
+    for (const fileName of IGNORE_FILES) {
+      const shouldRespect = fileName === ".gitignore" ? respectGitignore : respectLlmkbignore;
+      if (!shouldRespect) continue;
+      const filePath = join9(baseDir, fileName);
+      if (seen.has(filePath)) continue;
+      seen.add(filePath);
+      if (existsSync8(filePath)) {
+        const st = await fsStat(filePath);
+        if (!st.isFile()) continue;
+        const content = await readFile5(filePath, "utf-8");
+        ig.add(content);
+      }
+    }
+  }
+  return (testPath) => ig.ignores(testPath);
+}
+async function walkFiles(opts) {
+  const projectDir = resolve6(opts.projectDir);
+  const targetDir = resolve6(opts.targetDir ?? projectDir);
+  const respectGitignore = opts.respectGitignore ?? true;
+  const respectLlmkbignore = opts.respectLlmkbignore ?? true;
+  const isIgnored = await buildFilter(projectDir, targetDir, respectGitignore, respectLlmkbignore);
+  const files = [];
+  const skipped = [];
+  async function walk(dir) {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      skipped.push({ path: relative(targetDir, dir), reason: "unreadable" });
+      return;
+    }
+    for (const entry of entries) {
+      const fullPath = join9(dir, entry.name);
+      const relPath = relative(targetDir, fullPath);
+      if (entry.name.startsWith(".") && !IGNORE_FILES.includes(entry.name)) {
+        skipped.push({ path: relPath, reason: "hidden" });
+        continue;
+      }
+      if (isIgnored(relPath)) {
+        skipped.push({ path: relPath, reason: "ignored" });
+        continue;
+      }
+      if (entry.isDirectory()) {
+        await walk(fullPath);
+      } else if (entry.isFile()) {
+        files.push([relPath, fullPath]);
+      } else if (entry.isSymbolicLink()) {
+        try {
+          const st = await fsStat(fullPath);
+          if (st.isFile()) {
+            files.push([relPath, fullPath]);
+          } else {
+            skipped.push({ path: relPath, reason: "symlink-to-dir" });
+          }
+        } catch {
+          skipped.push({ path: relPath, reason: "broken-symlink" });
+        }
+      } else {
+        skipped.push({ path: relPath, reason: "not-a-file" });
+      }
+    }
+  }
+  await walk(targetDir);
+  return { files, skipped };
+}
+async function tusUpload(opts) {
+  const st = await fsStat(opts.absolutePath);
+  if (!st.isFile()) {
+    throw new Error(`Not a file: ${opts.relativePath}`);
+  }
+  const fileBuffer = await readFile5(opts.absolutePath);
+  const fileName = opts.relativePath.split("/").pop() ?? opts.relativePath;
+  return new Promise((resolve8, reject) => {
+    const upload = new tus.Upload(
+      fileBuffer,
+      {
+        endpoint: `${opts.endpoint}/api/spaces/${opts.space}/uploads`,
+        metadata: {
+          filename: opts.relativePath,
+          filetype: "application/octet-stream"
+        },
+        headers: {
+          Authorization: `Bearer ${opts.token}`
+        },
+        chunkSize: 5 * 1024 * 1024,
+        // 5 MB chunks
+        retryDelays: [0, 1e3, 3e3, 5e3],
+        removeFingerprintOnSuccess: true,
+        onError: (err) => reject(err),
+        onProgress: (bytesSent, bytesTotal) => {
+          opts.onProgress?.(bytesSent, bytesTotal);
+        },
+        onSuccess: () => {
+          resolve8(upload.url ?? "");
+        }
+      }
+    );
+    upload.start();
+  });
+}
+async function finalizeUpload(uploadUrl, token, ingestionJobId) {
+  const params = new URLSearchParams({ postpone_ingestion: "true" });
+  if (ingestionJobId) {
+    params.set("ingestion_job_id", ingestionJobId);
+  }
+  const completeUrl = `${uploadUrl}/complete?${params.toString()}`;
+  const res = await fetch(completeUrl, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Tus-Resumable": "1.0.0"
+    }
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    const shortId = uploadUrl.split("/").pop() ?? "unknown";
+    throw new Error(`Upload completion failed for ${shortId} (${res.status}): ${body}`);
+  }
+  return uploadUrl;
+}
+async function runSync(space, syncState, opts) {
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) throw new Error("No .llmkb/ directory found. Run `llmkb init` first.");
+  const config = getConfig();
+  const endpoint = config.endpoint;
+  const token = await getToken();
+  const result = { uploaded: 0, skipped: 0, unchanged: 0, renamed: 0, errors: [] };
+  const walkResult = await walkFiles({
+    projectDir: projectRoot,
+    targetDir: resolve6(opts.path)
+  });
+  for (const s of walkResult.skipped) {
+    result.skipped++;
+    opts.onFile?.(s.path, "skipped", s.reason);
+  }
+  if (walkResult.files.length === 0) {
+    result.status = "no_files";
+    const filteredCount = walkResult.skipped.length;
+    if (filteredCount > 0) {
+      result.reason = `No files to sync \u2014 all ${filteredCount} file(s) were filtered out by .gitignore / .llmkbignore rules.`;
+    } else {
+      result.reason = "No files found in sync target. The directory appears to be empty.";
+    }
+    return result;
+  }
+  const changes = await Promise.resolve().then(() => (init_sync_state(), sync_state_exports)).then(
+    (m) => m.getChangedFiles(walkResult.files, syncState)
+  );
+  for (const f of changes.unchangedFiles) {
+    result.unchanged++;
+    opts.onFile?.(f, "unchanged");
+  }
+  for (const r of changes.renamed) {
+    result.renamed++;
+    opts.onFile?.(r.newPath, "renamed", `${r.oldPath} \u2192 ${r.newPath}`);
+  }
+  const toUpload = [...changes.newFiles, ...changes.changedFiles];
+  if (toUpload.length === 0) {
+    result.status = "up_to_date";
+    result.reason = `No changes detected \u2014 all files are up to date (${walkResult.files.length} files, unchanged: ${result.unchanged}, renamed: ${result.renamed}, skipped: ${result.skipped}).`;
+    return result;
+  }
+  const uploadUrls = [];
+  const ingestionJobId = void 0;
+  for (const relPath of toUpload) {
+    const absPath = join9(resolve6(opts.path), relPath);
+    if (!token) {
+      result.errors.push({ path: relPath, error: "No token found" });
+      opts.onFile?.(relPath, "failed", "no token");
+      continue;
+    }
+    try {
+      const absEntry = walkResult.files.find(([, a]) => a === absPath);
+      const absPathResolved = absEntry?.[1] ?? absPath;
+      const url = await tusUpload({
+        space,
+        relativePath: relPath,
+        absolutePath: absPathResolved,
+        endpoint,
+        token
+      });
+      uploadUrls.push(url);
+      result.uploaded++;
+      opts.onFile?.(relPath, "uploading");
+    } catch (err) {
+      result.errors.push({ path: relPath, error: err.message });
+      opts.onFile?.(relPath, "failed", err.message);
+    }
+  }
+  if (uploadUrls.length > 0) {
+    for (const url of uploadUrls) {
+      try {
+        await finalizeUpload(url, token, ingestionJobId);
+      } catch (err) {
+        const shortId = url.split("/").pop() ?? "unknown";
+        result.errors.push({ path: shortId, error: err.message });
+        opts.onFile?.(shortId, "failed", err.message);
+      }
+    }
+    if (token) {
+      try {
+        const ingestRes = await fetch(
+          `${endpoint}/api/spaces/${space}/uploads/start-ingest`,
+          {
+            method: "POST",
+            headers: { Authorization: `Bearer ${token}` }
+          }
+        );
+        if (ingestRes.ok) {
+          const ingestBody = await ingestRes.json();
+          const realUrl = ingestBody.data?.attributes?.url;
+          if (realUrl) {
+            result.ingestionJobUrl = realUrl;
+          }
+        }
+      } catch {
+      }
+    }
+  }
+  result.status = "synced";
+  return result;
+}
+
+// lib/output.ts
+import { stdout as stdout2 } from "process";
+import cliProgress from "cli-progress";
+function isTTY() {
+  return stdout2.isTTY ?? false;
+}
+var ProgressBar = class {
+  bar = null;
+  label;
+  constructor(opts) {
+    this.label = opts.label ?? "Progress";
+    if (isTTY()) {
+      this.bar = new cliProgress.SingleBar(
+        {
+          format: `{label} [{bar}] {percentage}% | {value}/{total} | {eta_formatted}`,
+          barCompleteChar: "\u2588",
+          barIncompleteChar: "\u2591",
+          hideCursor: true
+        },
+        cliProgress.Presets.shades_classic
+      );
+      this.bar.start(opts.total, 0, { label: this.label });
+    }
+  }
+  /** Advance the progress bar by one step. */
+  increment() {
+    if (this.bar) this.bar.increment();
+  }
+  /** Set the current value directly. */
+  update(value) {
+    if (this.bar) this.bar.update(value);
+  }
+  /** Finalise the progress bar. */
+  stop() {
+    if (this.bar) this.bar.stop();
+  }
+};
+function writeJson(result) {
+  stdout2.write(JSON.stringify(result, null, 2) + "\n");
+}
+function writeLine(message, icon) {
+  if (icon) {
+    stdout2.write(`${label(icon, message)}
+`);
+  } else {
+    stdout2.write(`${message}
+`);
+  }
+}
+function writeDetail(message) {
+  stdout2.write(`  ${muted(message)}
+`);
+}
+function writeWarning(message) {
+  stdout2.write(`${warning("\u26A0")} ${warning(message)}
+`);
+}
+
+// src/commands/sync.ts
+init_parser();
+
+// lib/watch-lock.ts
+import { writeFile as writeFile7, readFile as readFile6, unlink as unlink2 } from "fs/promises";
+import { existsSync as existsSync9 } from "fs";
+import { join as join10 } from "path";
+var LOCK_FILE = ".llmkb/.watch.lock";
+async function acquireWatchLock(projectRoot) {
+  if (!projectRoot) return true;
+  const lockPath = join10(projectRoot, LOCK_FILE);
+  if (existsSync9(lockPath)) {
+    try {
+      const content = await readFile6(lockPath, "utf-8");
+      const pid = parseInt(content.trim(), 10);
+      if (Number.isFinite(pid) && pid > 0) {
+        try {
+          process.kill(pid, 0);
+          return false;
+        } catch (e) {
+          if (e.code !== "ESRCH") {
+            return false;
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  await writeFile7(lockPath, String(process.pid), "utf-8");
+  return true;
+}
+async function releaseWatchLock(projectRoot) {
+  if (!projectRoot) return;
+  const lockPath = join10(projectRoot, LOCK_FILE);
+  try {
+    if (existsSync9(lockPath)) {
+      const content = await readFile6(lockPath, "utf-8");
+      if (content.trim() === String(process.pid)) {
+        await unlink2(lockPath);
+      }
+    }
+  } catch {
+  }
+}
+
+// src/commands/sync.ts
+var DEFAULT_SKIP_PATTERNS2 = [
+  "node_modules/**",
+  ".git/**",
+  ".llmkb/**",
+  ".claude/**",
+  ".cursor/**",
+  ".next/**",
+  "dist/**",
+  ".venv/**",
+  "__pycache__/**",
+  "*.pyc",
+  "*.exe",
+  "*.dll",
+  "*.so",
+  "*.dylib",
+  "*.bin",
+  "**/__tests__/**",
+  "**/__snapshots__/**",
+  "**/test/**",
+  "**/tests/**",
+  "**/*.test.*",
+  "**/*.spec.*",
+  "**/fixtures/**",
+  "**/coverage/**",
+  "*.log",
+  "tmp/**",
+  "temp/**"
+];
+async function startWatch(targetPath, space, opts) {
+  const projectRoot = findProjectRoot();
+  if (projectRoot) {
+    const lockReleased = await acquireWatchLock(projectRoot);
+    if (!lockReleased) {
+      writeLine(
+        "Another watcher is already running. Use --force to override or stop the existing watcher.",
+        "\u2716"
+      );
+      process.exit(1);
+    }
+    process.on("exit", () => releaseWatchLock(projectRoot));
+    process.on("SIGINT", () => {
+      releaseWatchLock(projectRoot);
+      process.exit(0);
+    });
+    process.on("SIGTERM", () => {
+      releaseWatchLock(projectRoot);
+      process.exit(0);
+    });
+  }
+  const chokidar = await import("chokidar");
+  const ignore2 = await import("ignore");
+  const { readFile: readFile8 } = await import("fs/promises");
+  const { existsSync: existsSync11 } = await import("fs");
+  const ig = ignore2.default();
+  ig.add([
+    "node_modules/**",
+    ".git/**",
+    ".llmkb/**",
+    ".claude/**",
+    ".cursor/**",
+    ".next/**",
+    "dist/**",
+    ".venv/**",
+    "__pycache__/**",
+    "*.pyc",
+    "*.exe",
+    "*.dll",
+    "*.so",
+    "*.dylib",
+    "*.bin"
+  ]);
+  for (const fn of [".gitignore", ".llmkbignore"]) {
+    const fp = join11(targetPath, fn);
+    if (existsSync11(fp)) {
+      ig.add(String(await readFile8(fp)));
+    }
+  }
+  function fmtIgnoreRule(rel) {
+    for (const p of DEFAULT_SKIP_PATTERNS2) {
+      if (ig.ignores(rel)) return `(${p})`;
+    }
+    if (/(^|[\/\\])\../.test(rel)) return "(dotfile)";
+    return null;
+  }
+  function isWatched(filePath) {
+    const rel = join11(targetPath, filePath);
+    const ignored = ig.ignores(rel) || /(^|[\/\\])\../.test(rel);
+    if (ignored && opts.debug) {
+      const rule = fmtIgnoreRule(rel);
+      writeDetail(`[debug] skip ${rel} ${rule ?? ""}`);
+    }
+    return !ignored;
+  }
+  const watcher = chokidar.watch(targetPath, {
+    ignored: (path) => !isWatched(path),
+    persistent: true,
+    ignoreInitial: true
+  });
+  let timer = null;
+  const onChange = async (filePath) => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(async () => {
+      if (opts.debug) writeDetail(`[debug] detected: ${filePath}`);
+      try {
+        await performSync(targetPath, space, { ...opts, watchEvent: filePath });
+      } catch (err) {
+        writeLine(`Sync error: ${err.message}`, "\u2716");
+      }
+    }, opts.debounceMs);
+  };
+  watcher.on("change", onChange);
+  watcher.on("add", onChange);
+  watcher.on("unlink", (p) => {
+    if (opts.verbose) writeDetail(`[watch] removed: ${p}`);
+  });
+  writeLine(
+    `Watching ${targetPath} for changes (debounce: ${opts.debounceMs}ms)...`,
+    "\u231A"
+  );
+}
+async function performSync(targetPath, space, opts) {
+  const config = getConfig();
+  const endpoint = config.endpoint;
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) {
+    writeLine("No .llmkb/ directory found. Run `llmkb init` first.", "\u2716");
+    process.exit(1);
+  }
+  const spaceConfig = await readSpaceConfig(projectRoot);
+  const activeSpace = space || spaceConfig?.project_space?.[0]?.id;
+  if (!activeSpace) {
+    writeLine(
+      "No space specified. Use --space <id> or configure a project space.",
+      "\u2716"
+    );
+    process.exit(1);
+  }
+  const token = await getToken();
+  if (!token && !opts.dryRun) {
+    writeLine(
+      `No credentials. Run \`llmkb login --project-space <id>\`.`,
+      "\u2716"
+    );
+    process.exit(1);
+  }
+  const startTime = Date.now();
+  const syncState = opts.force ? null : await readSyncState(projectRoot);
+  if (opts.force) {
+    await clearSyncState(projectRoot);
+  }
+  if (opts.dryRun) {
+    const walkResult = await walkFiles({
+      projectDir: projectRoot,
+      targetDir: targetPath
+    });
+    const changes = await Promise.resolve().then(() => (init_sync_state(), sync_state_exports)).then(
+      (m) => m.getChangedFiles(walkResult.files, syncState)
+    );
+    if (opts.json) {
+      writeJson({
+        command: "sync",
+        success: true,
+        data: {
+          space: activeSpace,
+          dryRun: true,
+          newFiles: changes.newFiles,
+          changedFiles: changes.changedFiles,
+          unchangedFiles: changes.unchangedFiles,
+          renamed: changes.renamed,
+          skipped: walkResult.skipped.map((s) => ({
+            path: s.path,
+            reason: s.reason
+          }))
+        },
+        meta: {
+          durationMs: Date.now() - startTime,
+          totalItems: walkResult.files.length,
+          processedItems: changes.newFiles.length + changes.changedFiles.length,
+          skippedItems: walkResult.skipped.length,
+          renamedItems: changes.renamed.length
+        }
+      });
+    } else {
+      writeLine(`Dry-run for space "${activeSpace}":`, "\u2139");
+      for (const f of changes.newFiles) writeDetail(`[new] ${f}`);
+      for (const f of changes.changedFiles) writeDetail(`[changed] ${f}`);
+      for (const f of changes.unchangedFiles) writeDetail(`[unchanged] ${f}`);
+      for (const r of changes.renamed)
+        writeDetail(`[rename] ${r.oldPath} \u2192 ${r.newPath}`);
+      for (const s of walkResult.skipped)
+        writeDetail(`[skip] ${s.path} (${s.reason})`);
+      writeLine(
+        `${changes.newFiles.length} new, ${changes.changedFiles.length} changed, ${changes.unchangedFiles.length} unchanged, ${changes.renamed.length} renamed, ${walkResult.skipped.length} skipped`
+      );
+    }
+    return;
+  }
+  const filesResult = await walkFiles({
+    projectDir: projectRoot,
+    targetDir: targetPath
+  });
+  const totalFiles = filesResult.files.length;
+  const bar = isTTY() && !opts.json ? new ProgressBar({ total: totalFiles || 1, label: "Syncing" }) : null;
+  const result = await runSync(activeSpace, syncState, {
+    path: targetPath,
+    onFile: (_relPath, _status) => {
+      bar?.increment();
+    }
+  });
+  bar?.stop();
+  if (result.uploaded === 0 && result.errors.length === 0) {
+    if (opts.json) {
+      writeJson({
+        command: "sync",
+        success: true,
+        data: result,
+        meta: { durationMs: Date.now() - startTime }
+      });
+    } else {
+      const { status, reason, unchanged, renamed, skipped } = result;
+      if (status === "no_files") {
+        writeWarning(reason ?? "No files to sync.");
+      } else if (unchanged === 0 && renamed === 0 && skipped === 0) {
+        writeWarning("No files found in sync target. The directory appears to be empty.");
+      } else {
+        writeLine(
+          `No changes detected \u2014 all files up to date (${unchanged} unchanged, ${renamed} renamed, ${skipped} skipped).`,
+          "\u2714"
+        );
+      }
+    }
+    return;
+  }
+  const newState = {
+    space: activeSpace,
+    lastSyncAt: (/* @__PURE__ */ new Date()).toISOString(),
+    files: {}
+  };
+  for (const [relPath, absPath] of filesResult.files) {
+    try {
+      const hash = await Promise.resolve().then(() => (init_sync_state(), sync_state_exports)).then(
+        (m) => m.computeSha256(absPath)
+      );
+      newState.files[relPath] = {
+        sha256: hash,
+        lastUploaded: (/* @__PURE__ */ new Date()).toISOString(),
+        status: "synced"
+      };
+    } catch {
+    }
+  }
+  await writeSyncState(projectRoot, newState);
+  if (token) {
+    triggerDedup(endpoint, activeSpace, token).catch((err) => {
+      if (opts.json) {
+        writeJson({
+          command: "dedup",
+          success: false,
+          data: null,
+          error: err.message
+        });
+      } else if (opts.verbose) {
+        writeDetail(`Dedup skipped: ${err.message}`);
+      }
+    });
+  }
+  if (projectRoot && token) {
+    const syncSpacesResult = await syncRelatedSpaces(projectRoot, endpoint, token).catch(() => null);
+    if (opts.verbose && syncSpacesResult && syncSpacesResult.added > 0) {
+      writeDetail(`Related spaces: ${syncSpacesResult.added} new space(s) synced to spaces.yml`);
+    }
+  }
+  const duration = Date.now() - startTime;
+  if (opts.json) {
+    writeJson({
+      command: "sync",
+      success: result.errors.length === 0,
+      data: result,
+      meta: {
+        durationMs: duration,
+        totalItems: result.uploaded + result.unchanged + result.skipped + result.renamed + result.errors.length,
+        processedItems: result.uploaded,
+        skippedItems: result.skipped,
+        renamedItems: result.renamed
+      }
+    });
+  } else {
+    writeLine(
+      `Sync complete: ${result.uploaded} uploaded, ${result.unchanged} unchanged, ${result.skipped} skipped, ${result.renamed} renamed, ${result.errors.length} errors (${duration}ms)`,
+      "\u2714"
+    );
+  }
+  if (result.ingestionJobUrl && !opts.json) {
+    writeLine(`Ingestion job: ${result.ingestionJobUrl}`, "\u2139");
+  }
+  if (result.errors.length > 0 && !opts.json) {
+    for (const e of result.errors) {
+      writeDetail(`\u2716 ${e.path}: ${e.error}`);
+    }
+    process.exitCode = 1;
+  }
+}
+async function triggerDedup(endpoint, space, token) {
+  const url = `${endpoint}/api/spaces/${encodeURIComponent(space)}/dedup`;
+  const res = await fetch(url, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Content-Type": "application/json"
+    }
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => "unknown");
+    throw new Error(`Dedup failed (${res.status}): ${body}`);
+  }
+}
+var syncCommand = new Command12("sync").description("Sync local files to an llmkb space").argument("[path]", "Directory or file to sync", ".").option("-s, --space <id>", "Space UUID (overrides project_space)").option("-n, --dry-run", "Show what would be uploaded without uploading").option("-f, --force", "Re-upload everything, bypassing cache").option("-w, --watch", "Watch for file changes and auto-sync").option("--debounce <ms>", "Watch debounce in ms", "300").option("--json", "Output JSON for machine parsing").option("--verbose", "Detailed output including skipped files").option(
+  "--debug",
+  "Show all events including ignored files with matching rule"
+).action(
+  async (path, opts) => {
+    try {
+      const resolvedSpace = opts.space ?? "";
+      if (opts.watch) {
+        await startWatch(path, resolvedSpace, {
+          debounceMs: parseInt(opts.debounce, 10) || 300,
+          json: opts.json ?? false,
+          verbose: opts.verbose ?? false,
+          debug: opts.debug ?? false
+        });
+        return;
+      }
+      await performSync(path, resolvedSpace, {
+        dryRun: opts.dryRun,
+        force: opts.force,
+        json: opts.json,
+        verbose: opts.verbose
+      });
+    } catch (err) {
+      if (opts.json) {
+        writeJson({
+          command: "sync",
+          success: false,
+          data: null,
+          error: err.message
+        });
+      } else {
+        writeLine(`Error: ${err.message}`, "\u2716");
+      }
+      process.exit(1);
+    }
+  }
+);
+
+// src/commands/query.ts
+import { Command as Command13 } from "commander";
+init_parser();
+async function search(space, query, endpoint, token, limit) {
+  const url = `${endpoint}/api/v1/${space}/search?q=${encodeURIComponent(query)}&limit=${limit}`;
+  const res = await fetch(url, {
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: "application/json"
+    }
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`Search failed (${res.status}): ${body}`);
+  }
+  return await res.json();
+}
+var queryCommand = new Command13("query").description("Search an llmkb space and print ranked results").argument("<text>", "Search query text").option("-s, --space <id>", "Space UUID (overrides project_space)").option("-n, --limit <count>", "Max results", "10").option("--json", "Output JSON for machine parsing").action(async (text, opts) => {
+  const startTime = Date.now();
+  const config = getConfig();
+  try {
+    const projectRoot = findProjectRoot();
+    let endpoint = config.endpoint;
+    let token = null;
+    let activeSpace = opts.space;
+    if (projectRoot) {
+      const spaceConfig = await readSpaceConfig(projectRoot);
+      if (spaceConfig) {
+        activeSpace = activeSpace ?? spaceConfig.project_space?.[0]?.id;
+      }
+    }
+    token = await getToken();
+    if (!token) {
+      throw new Error(
+        "No access token found. Set LLMKB_ACCESS_TOKEN env var or run `llmkb login --project-space <id>`."
+      );
+    }
+    const limit = parseInt(opts.limit, 10) || 10;
+    const result = await search(activeSpace ?? "", text, endpoint, token, limit);
+    if (opts.json) {
+      writeJson({
+        command: "query",
+        success: true,
+        data: result.data,
+        meta: {
+          durationMs: Date.now() - startTime,
+          totalItems: result.meta.total,
+          processedItems: result.data.length
+        }
+      });
+    } else {
+      writeLine(`Search results for "${text}" in "${activeSpace}" (${result.meta.total} total):`, "\u2139");
+      for (const r of result.data) {
+        writeLine(`[${r.score.toFixed(2)}] ${r.title}`, "\u25CF");
+        writeDetail(`${r.path} (${r.matchType})`);
+        if (r.excerpt) writeDetail(r.excerpt);
+      }
+      writeDetail(`Completed in ${Date.now() - startTime}ms`);
+    }
+  } catch (err) {
+    if (opts.json) {
+      writeJson({
+        command: "query",
+        success: false,
+        data: null,
+        error: err.message,
+        meta: { durationMs: Date.now() - startTime }
+      });
+    } else {
+      writeLine(`Error: ${err.message}`, "\u2716");
+    }
+    process.exit(1);
+  }
+});
+
+// src/commands/doctor.ts
+import { Command as Command14 } from "commander";
+init_parser();
+
+// lib/config-validation.ts
+import { readFile as readFile7 } from "fs/promises";
+import { existsSync as existsSync10 } from "fs";
+import { join as join12 } from "path";
+import { parse as parse2 } from "yaml";
+function validateBaseUrl(url) {
+  try {
+    const parsed = new URL(url);
+    if (!parsed.protocol || !parsed.host) {
+      return {
+        name: "Base URL format",
+        passed: false,
+        message: "URL missing scheme or host",
+        detail: `Got: ${url}`
+      };
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      return {
+        name: "Base URL format",
+        passed: false,
+        message: `Unsupported protocol: ${parsed.protocol}`,
+        detail: `Got: ${url}`
+      };
+    }
+    return {
+      name: "Base URL format",
+      passed: true,
+      message: `Valid URL: ${url}`
+    };
+  } catch {
+    return {
+      name: "Base URL format",
+      passed: false,
+      message: "Invalid URL format",
+      detail: `Got: ${url}. Must include scheme (e.g., https://api.llmkb.ai)`
+    };
+  }
+}
+async function validateConfigYml(projectDir) {
+  const filePath = join12(projectDir, ".llmkb", "config.yml");
+  if (!existsSync10(filePath)) {
+    return {
+      name: "config.yml",
+      passed: false,
+      message: "File not found",
+      detail: "Run `llmkb init` to create it."
+    };
+  }
+  try {
+    const content = await readFile7(filePath, "utf-8");
+    const cfg = parse2(content);
+    if (cfg === null) {
+      return {
+        name: "config.yml",
+        passed: true,
+        message: "Valid config file (all defaults)"
+      };
+    }
+    if (cfg.llmkb_base_url !== void 0) {
+      const urlResult = validateBaseUrl(String(cfg.llmkb_base_url));
+      if (!urlResult.passed) {
+        return {
+          name: "config.yml",
+          passed: false,
+          message: "llmkb_base_url has invalid value",
+          detail: urlResult.detail
+        };
+      }
+    }
+    return {
+      name: "config.yml",
+      passed: true,
+      message: "Valid config file"
+    };
+  } catch (err) {
+    return {
+      name: "config.yml",
+      passed: false,
+      message: "Invalid YAML",
+      detail: err.message
+    };
+  }
+}
+async function validateSpacesYml(projectDir) {
+  const filePath = join12(projectDir, ".llmkb", "spaces.yml");
+  if (!existsSync10(filePath)) {
+    return {
+      name: "spaces.yml",
+      passed: false,
+      message: "File not found",
+      detail: "Run `llmkb init` or `llmkb login` to create it."
+    };
+  }
+  try {
+    const content = await readFile7(filePath, "utf-8");
+    const cfg = parse2(content);
+    if (cfg.project_space && Array.isArray(cfg.project_space)) {
+      for (const ps of cfg.project_space) {
+        if (!ps.id) {
+          return {
+            name: "spaces.yml",
+            passed: false,
+            message: "project_space entry missing required 'id' field"
+          };
+        }
+      }
+    }
+    if (cfg.spaces && Array.isArray(cfg.spaces)) {
+      for (const s of cfg.spaces) {
+        if (!s.id) {
+          return {
+            name: "spaces.yml",
+            passed: false,
+            message: "spaces entry missing required 'id' field"
+          };
+        }
+      }
+    }
+    return {
+      name: "spaces.yml",
+      passed: true,
+      message: `Valid config (${cfg.spaces?.length ?? 0} space(s))`
+    };
+  } catch (err) {
+    return {
+      name: "spaces.yml",
+      passed: false,
+      message: "Invalid YAML",
+      detail: err.message
+    };
+  }
+}
+async function validateAccessToken(endpoint) {
+  const token = await getToken();
+  if (!token) {
+    return {
+      name: "Access token",
+      passed: false,
+      message: "No access token found",
+      detail: "Set LLMKB_ACCESS_TOKEN env var or run `llmkb login --project-space <id>`."
+    };
+  }
+  try {
+    const url = `${endpoint.replace(/\/+$/, "")}/api/v1/auth/me`;
+    const res = await fetch(url, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${token}` }
+    });
+    if (res.ok) {
+      const body = await res.json();
+      const attrs = body.data?.attributes;
+      const status = attrs?.token_status;
+      if (status === "active") {
+        return {
+          name: "Access token",
+          passed: true,
+          message: `Token is valid (user: ${attrs?.email ?? "unknown"})`
+        };
+      }
+      return {
+        name: "Access token",
+        passed: false,
+        message: `Token status: ${status}`,
+        detail: "Generate a new token at /settings/access-tokens."
+      };
+    }
+    return {
+      name: "Access token",
+      passed: false,
+      message: `Server returned ${res.status}`,
+      detail: "Token may be expired or invalid. Run `llmkb login --project-space <id>`."
+    };
+  } catch (err) {
+    return {
+      name: "Access token",
+      passed: false,
+      message: "Cannot validate \u2014 server unreachable",
+      detail: err.message
+    };
+  }
+}
+async function checkBackendConnectivity(endpoint) {
+  try {
+    const url = `${endpoint.replace(/\/+$/, "")}/health`;
+    const res = await fetch(url);
+    if (res.ok) {
+      return {
+        name: "Backend connectivity",
+        passed: true,
+        message: `Server reachable at ${endpoint}`
+      };
+    }
+    return {
+      name: "Backend connectivity",
+      passed: false,
+      message: `Server returned ${res.status}`,
+      detail: "Check that the server is running."
+    };
+  } catch (err) {
+    return {
+      name: "Backend connectivity",
+      passed: false,
+      message: "Server unreachable",
+      detail: err.message
+    };
+  }
+}
+var WRITE_ROLES = /* @__PURE__ */ new Set(["owner", "admin"]);
+async function checkSpaceAccess(endpoint, spaceId, token, checkWrite) {
+  try {
+    const url = `${endpoint.replace(/\/+$/, "")}/api/v1/auth/spaces`;
+    const res = await fetch(url, {
+      headers: { Authorization: `Bearer ${token}` }
+    });
+    if (res.ok) {
+      const body = await res.json();
+      const space = body.data?.find((d) => d.attributes?.space_id === spaceId);
+      if (space) {
+        const role = space.attributes.role ?? "guest";
+        if (checkWrite && !WRITE_ROLES.has(role)) {
+          return {
+            name: `Space access (${spaceId})`,
+            passed: false,
+            message: `Access granted (role: ${role}) but no write permission`,
+            detail: `Role "${role}" is read-only. Need owner or admin to sync. Ask the space owner to upgrade your role.`
+          };
+        }
+        return {
+          name: `Space access (${spaceId})`,
+          passed: true,
+          message: `Access granted (role: ${role})${checkWrite ? " \u2014 write permission OK" : ""}`
+        };
+      }
+      return {
+        name: `Space access (${spaceId})`,
+        passed: false,
+        message: "No access to this space",
+        detail: "Ask the space owner to invite you."
+      };
+    }
+    return {
+      name: `Space access (${spaceId})`,
+      passed: false,
+      message: `Server returned ${res.status}`
+    };
+  } catch (err) {
+    return {
+      name: `Space access (${spaceId})`,
+      passed: false,
+      message: "Cannot check \u2014 server unreachable",
+      detail: err.message
+    };
+  }
+}
+
+// src/commands/doctor.ts
+async function report(label2, result) {
+  const icon = result.passed ? success("\u2714") : error("\u2716");
+  const msg = result.passed ? success(result.message) : error(result.message);
+  console.log(`  ${icon} ${label2}: ${msg}`);
+  if (result.detail) {
+    console.log(`       ${muted(result.detail)}`);
+  }
+}
+function spaceNameMap(config) {
+  const map = {};
+  for (const ps of config.project_space ?? []) {
+    if (ps.name) map[ps.id] = ps.name;
+  }
+  for (const s of config.spaces ?? []) {
+    if (s.name) map[s.id] = s.name;
+  }
+  return map;
+}
+function formatSpaceId(spaceId, nameMap) {
+  const name = nameMap[spaceId];
+  return name ? `${spaceId} (${info(name)})` : muted(spaceId);
+}
+var doctorCommand = new Command14("doctor").description("Diagnose configuration and permission issues").action(async () => {
+  const config = getConfig();
+  const endpoint = config.endpoint;
+  console.log(`${info("llmkb doctor")} ${muted("\u2014 diagnostic report")}
+`);
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) {
+    console.log(`  ${error("\u2716 Project root: No .llmkb/ directory found.")}`);
+    console.log(`    ${info("Run `llmkb init` to create one.")}`);
+    return;
+  }
+  console.log(`  ${success("\u2714")} ${muted("Project root:")} ${projectRoot}
+`);
+  console.log(muted("1. Config file checks"));
+  const configResult = await validateConfigYml(projectRoot);
+  await report("config.yml", configResult);
+  const spaceConfig = await readSpaceConfig(projectRoot);
+  const spacesResult = await validateSpacesYml(projectRoot);
+  await report("spaces.yml", spacesResult);
+  console.log(`
+${muted("2. Backend connectivity")}`);
+  const connectivityResult = await checkBackendConnectivity(endpoint);
+  await report("Backend", connectivityResult);
+  console.log(`
+${muted("3. Authentication")}`);
+  const tokenResult = await validateAccessToken(endpoint);
+  await report("Access token", tokenResult);
+  if (tokenResult.passed && projectRoot && spaceConfig?.project_space?.length) {
+    const token = await getToken();
+    if (token) {
+      const syncResult = await syncRelatedSpaces(projectRoot, endpoint, token);
+      const parts = [];
+      if (syncResult.added > 0) parts.push(`added ${syncResult.added}`);
+      if (syncResult.removed > 0) parts.push(`removed ${syncResult.removed}`);
+      if (syncResult.alreadyPresent > 0) parts.push(`${syncResult.alreadyPresent} already configured`);
+      if (parts.length > 0) {
+        console.log(`  ${info(`\u2139 Related spaces synced: ${parts.join(", ")}.`)}`);
+      }
+    }
+  }
+  console.log(`
+${muted("4. Space access")}`);
+  if (tokenResult.passed) {
+    const token = await getToken();
+    const nameMap = spaceConfig ? spaceNameMap(spaceConfig) : {};
+    const allSpaces = [];
+    if (spaceConfig?.project_space) {
+      for (const ps of spaceConfig.project_space) {
+        allSpaces.push({ id: ps.id, isProject: true });
+      }
+    }
+    if (spaceConfig?.spaces) {
+      for (const s of spaceConfig.spaces) {
+        if (!allSpaces.find((e) => e.id === s.id)) {
+          allSpaces.push({ id: s.id, isProject: false });
+        }
+      }
+    }
+    if (allSpaces.length > 0) {
+      for (const entry of allSpaces) {
+        const accessResult = await checkSpaceAccess(endpoint, entry.id, token, entry.isProject);
+        const label2 = entry.isProject ? `${highlight("\u2605 PROJECT")} ${formatSpaceId(entry.id, nameMap)}` : formatSpaceId(entry.id, nameMap);
+        await report(label2, accessResult);
+      }
+    } else {
+      console.log(`  ${info("\u2139 No spaces configured. Run `llmkb add --space <id>`.")}`);
+    }
+  } else {
+    console.log(`  ${warning("\u26A0 Skipping space access checks \u2014 not authenticated.")}`);
+  }
+  console.log(`
+${success("Diagnostic complete.")}`);
+});
+
+// bin/cli.ts
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = dirname2(__filename);
+var pkg = JSON.parse(
+  readFileSync(resolve7(__dirname, "../package.json"), "utf-8")
+);
+var program = new Command15();
+program.name("llmkb").description(
+  "llmkb Claude Code plugin \u2014 manage spaces, sync code, and query your knowledge base"
+).version(pkg.version);
+program.addCommand(initCommand);
+program.addCommand(loginCommand);
+program.addCommand(logoutCommand);
+program.addCommand(addCommand);
+program.addCommand(removeCommand);
+program.addCommand(spacesCommand);
+program.addCommand(updateCommand);
+program.addCommand(whoamiCommand);
+program.addCommand(useCommand);
+program.addCommand(statusCommand);
+program.addCommand(syncCommand);
+program.addCommand(queryCommand);
+program.addCommand(doctorCommand);
+program.addCommand(hooksCommand);
+program.parse();
+//# sourceMappingURL=cli.js.map