oh-my-llmwikimode 1.0.0

package/bin/llmwiki.js

@@ -0,0 +1,1493 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { expandHome } from "../src/config.js";
+import { buildCuratorBrowserData } from "../src/curator/browser-data.js";
+import { proposeConsolidation, readCuratorQueue, suggestLessonCandidate } from "../src/curator/queue.js";
+import { generateWeeklyDigest, getDigest, listDigests } from "../src/librarian/weekly-digest.js";
+import { rebuildBrowserData } from "../src/wiki/browser-data.js";
+import { runGraphReasoningAnalysis, buildGraphReasoningBrowserData } from "../src/stage4/graph-reasoning/browser-data.js";
+import { readGraphReasoningQueue } from "../src/stage4/graph-reasoning/queue.js";
+import { addTodo, listTodos, markTodoDone, removeTodo } from "../src/todo/queue.js";
+import { createDispatchPacketArtifact } from "../src/team/dispatch.js";
+import {
+  appendTaskEvidence,
+  createAgentGroup,
+  createAgentProfile,
+  createTaskCard,
+  readAgentTeamQueue,
+  updateTaskStatus,
+} from "../src/team/queue.js";
+import { ingestKnowledge } from "../src/wiki/ingest.js";
+import { lintWiki } from "../src/wiki/lint.js";
+import { importSourceFile, readSourceRecords } from "../src/wiki/source-ledger.js";
+import { doctorWiki } from "../src/wiki/doctor.js";
+import { buildIndex, ensureWikiStructure, getWikiPaths, promoteEntry, rejectEntry } from "../src/wiki/store.js";
+import { queryWiki } from "../src/wiki/query.js";
+import {
+  appendSearchFailure,
+  readSearchFailures,
+} from "../src/wiki/search-feedback.js";
+import {
+  generateAliasSuggestion,
+  listAliasSuggestions,
+} from "../src/wiki/alias-suggestions.js";
+import {
+  listRawContents,
+  getRawSummary,
+  validateRawStructure,
+} from "../src/wiki/raw-manager.js";
+import {
+  generateLessonProposals,
+} from "../src/wiki/lesson-proposal-analyzer.js";
+import {
+  listProposals,
+  getProposal,
+  applyProposal,
+} from "../src/wiki/lesson-proposal-manager.js";
+import {
+  buildSemanticIndex,
+  getSemanticIndexSize,
+  loadSemanticIndex,
+  updateSemanticIndex,
+} from "../src/wiki/semantic-index.js";
+import { semanticSearch } from "../src/wiki/semantic-search.js";
+
+const DEFAULT_WIKI_ROOT = "~/Documents/llm-wiki";
+
+const COMMANDS = {
+  init: {
+    usage: "llmwiki init [--wiki-root ~/Documents/llm-wiki] [options]",
+    description: "Create the local wiki directory structure and an OpenCode config snippet.",
+  },
+  lint: {
+    usage: "llmwiki lint [options]",
+    description: "Validate wiki entries.",
+  },
+  doctor: {
+    usage: "llmwiki doctor [options]",
+    description: "Run read-only core health checks and print a dry-run migration plan.",
+  },
+  query: {
+    usage: "llmwiki query [options] <query>",
+    description: "Search wiki entries using the current derived index.",
+  },
+  ingest: {
+    usage: "llmwiki ingest [options]",
+    description: "Safely ingest local knowledge into inbox/ or project/ candidate entries.",
+  },
+  promote: {
+    usage: "llmwiki promote [options] <entry-path>",
+    description: "Promote an inbox/ or problems/ entry to a lesson.",
+  },
+  reject: {
+    usage: "llmwiki reject [options] <entry-path>",
+    description: "Mark an entry as rejected.",
+  },
+  rebuild: {
+    usage: "llmwiki rebuild [options]",
+    description: "Rebuild .system/index.json and .system/graph.json.",
+  },
+  audit: {
+    usage: "llmwiki audit [--limit 10] [options]",
+    description: "Print recent auto-memory audit entries.",
+  },
+  todo: {
+    usage: "llmwiki todo <add|list|done|remove> [options]",
+    description: "Manage the primary simple local TODO list.",
+  },
+  team: {
+    usage: "llmwiki team <list|create-task|create-profile|create-group|approve|status|generate-packet|evidence> [options]",
+    description: "Manage local approval-first Agent Team queue artifacts.",
+  },
+  curator: {
+    usage: "llmwiki curator <list|suggest-lesson|propose-consolidation> [options]",
+    description: "Manage local artifact-only Curator review packets.",
+  },
+  digest: {
+    usage: "llmwiki digest <generate|list|show> [options]",
+    description: "Generate, list, or show review-required weekly digest reports.",
+  },
+  "source-ledger": {
+    usage: "llmwiki source-ledger <import|list|search> [options]",
+    description: "Import source files into the source ledger, list recorded sources, or search raw evidence.",
+  },
+  stage4: {
+    usage: "llmwiki stage4 <graph-reasoning list|graph-reasoning analyze> [options]",
+    description: "Run Stage 4 Personal Local Graph Reasoning analysis.",
+  },
+  "search-feedback": {
+    usage: "llmwiki search-feedback <list|record|suggest-aliases> [options]",
+    description: "List search failures, record a zero-result query, or generate alias suggestions.",
+  },
+  "semantic-search": {
+    usage: "llmwiki semantic-search <query> [options]",
+    description: "Run local semantic search over the embedding index.",
+  },
+  "semantic-index": {
+    usage: "llmwiki semantic-index build | semantic-index status | semantic-index update [options]",
+    description: "Build, inspect, or incrementally update the local semantic embedding index.",
+  },
+  raw: {
+    usage: "llmwiki raw <list|status|validate> [options]",
+    description: "List raw contents, show raw statistics, or validate raw directory structure.",
+  },
+  "lesson-proposal": {
+    usage: "llmwiki lesson-proposal <analyze|list|show|apply> [options]",
+    description: "Analyze usage events, list proposals, show a proposal, or apply a proposal to create a lesson.",
+  },
+};
+
+function print(message, isError = false) {
+  const stream = isError ? process.stderr : process.stdout;
+  stream.write(`${message}\n`);
+}
+
+function commandList() {
+  return Object.entries(COMMANDS)
+    .map(([name, command]) => `  ${name.padEnd(8)} ${command.description}`)
+    .join("\n");
+}
+
+function globalOptionsHelp() {
+  return [
+    "Options:",
+    `  --wiki-root <path>  Wiki root directory (default: ${DEFAULT_WIKI_ROOT})`,
+    "  --project <name>    Target project for ingest/store (creates projects/<name>/inbox/)",
+    "  --tags <tags>       Comma-separated tags for ingest/todo add",
+    "  --browser-data      Rebuild .system/browser-data.json (rebuild only)",
+    "  --limit <n>         Number of audit entries to print (audit only)",
+    "  --json              Output JSON",
+    "  --format context    Output untrusted context for query results",
+    "  --related <paths>    Comma-separated related entries (curator suggest-lesson)",
+    "  --entries <paths>    Comma-separated entries (curator propose-consolidation)",
+    "  --rationale <text>   Reviewer rationale (curator propose-consolidation)",
+    "  -h, --help          Show help",
+  ].join("\n");
+}
+
+function mainHelp() {
+  return [
+    "Usage: llmwiki <command> [options]",
+    "",
+    "Commands:",
+    commandList(),
+    "",
+    globalOptionsHelp(),
+  ].join("\n");
+}
+
+function commandHelp(commandName) {
+  const command = COMMANDS[commandName];
+  return [
+    `Usage: ${command.usage}`,
+    "",
+    command.description,
+    "",
+    globalOptionsHelp(),
+  ].join("\n");
+}
+
+function helpPayload(commandName) {
+  if (!commandName) {
+    return {
+      usage: "llmwiki <command> [options]",
+      commands: Object.fromEntries(
+        Object.entries(COMMANDS).map(([name, command]) => [name, command.description])
+      ),
+      defaultWikiRoot: DEFAULT_WIKI_ROOT,
+    };
+  }
+
+  const command = COMMANDS[commandName];
+  return {
+    usage: command.usage,
+    command: commandName,
+    description: command.description,
+    defaultWikiRoot: DEFAULT_WIKI_ROOT,
+  };
+}
+
+const TEAM_VALUE_OPTIONS = new Set([
+  "--agent-profile",
+  "--agent-profile-id",
+  "--allowed",
+  "--approved-by",
+  "--approved-capabilities",
+  "--artifact",
+  "--blocked-reason",
+  "--capabilities",
+  "--criteria",
+  "--denied",
+  "--description",
+  "--entries",
+  "--goal",
+  "--id",
+  "--kind",
+  "--policy",
+  "--profiles",
+  "--rationale",
+  "--related",
+  "--requires-approval",
+  "--role",
+  "--role-id",
+  "--scope",
+  "--summary",
+  "--template",
+  "--title",
+]);
+
+function parseList(value) {
+  return String(value ?? "")
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function applyTeamValueOption(parsed, optionName, value) {
+  if (!TEAM_VALUE_OPTIONS.has(optionName)) return false;
+
+  if (optionName === "--agent-profile" || optionName === "--agent-profile-id") {
+    parsed.agentProfileId = value;
+  } else if (optionName === "--allowed") {
+    parsed.allowedCapabilities.push(...parseList(value));
+  } else if (optionName === "--approved-by") {
+    parsed.approvedBy = value;
+  } else if (optionName === "--approved-capabilities") {
+    parsed.approvedCapabilities.push(...parseList(value));
+  } else if (optionName === "--artifact") {
+    parsed.artifacts.push(...parseList(value));
+  } else if (optionName === "--blocked-reason") {
+    parsed.blockedReason = value;
+  } else if (optionName === "--capabilities") {
+    parsed.capabilities.push(...parseList(value));
+  } else if (optionName === "--criteria") {
+    parsed.criteria.push(...parseList(value));
+  } else if (optionName === "--denied") {
+    parsed.deniedCapabilities.push(...parseList(value));
+  } else if (optionName === "--description") {
+    parsed.description = value;
+  } else if (optionName === "--entries") {
+    parsed.entries.push(...parseList(value));
+  } else if (optionName === "--goal") {
+    parsed.goal = value;
+  } else if (optionName === "--id") {
+    parsed.id = value;
+  } else if (optionName === "--kind") {
+    parsed.kind = value;
+  } else if (optionName === "--policy") {
+    parsed.policy = value;
+  } else if (optionName === "--profiles") {
+    parsed.profiles.push(...parseList(value));
+  } else if (optionName === "--rationale") {
+    parsed.rationale = value;
+  } else if (optionName === "--related") {
+    parsed.related.push(...parseList(value));
+  } else if (optionName === "--requires-approval") {
+    parsed.requiresApprovalCapabilities.push(...parseList(value));
+  } else if (optionName === "--role" || optionName === "--role-id") {
+    parsed.roleId = value;
+  } else if (optionName === "--scope") {
+    parsed.scope = value;
+  } else if (optionName === "--summary") {
+    parsed.summary = value;
+  } else if (optionName === "--template") {
+    parsed.template = value;
+  } else if (optionName === "--title") {
+    parsed.title = value;
+  }
+
+  return true;
+}
+
+function parseArgs(argv) {
+  const parsed = {
+    args: [],
+    command: null,
+    allowedCapabilities: [],
+    browserData: false,
+    deniedCapabilities: [],
+    description: null,
+    format: "json",
+    help: false,
+    inputPath: null,
+    json: false,
+    kind: "custom",
+    limit: 10,
+    limitProvided: false,
+    agentProfileId: "main-opencode",
+    approvedBy: null,
+    approvedCapabilities: [],
+    artifacts: [],
+    blockedReason: null,
+    capabilities: [],
+    criteria: [],
+    goal: null,
+    id: null,
+    policy: "approval-first",
+    profiles: [],
+    rationale: null,
+    related: [],
+    requiresApprovalCapabilities: [],
+    roleId: "builder",
+    scope: "custom",
+    summary: null,
+    source: "manual",
+    stdin: false,
+    tags: null,
+    template: "Return evidence only.",
+    title: null,
+    wikiRoot: DEFAULT_WIKI_ROOT,
+    wikiRootInput: DEFAULT_WIKI_ROOT,
+    entries: [],
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    if (token === "--") {
+      parsed.args.push(...argv.slice(index + 1));
+      break;
+    }
+
+    if (token.startsWith("--") && token.includes("=")) {
+      const equalsIndex = token.indexOf("=");
+      const optionName = token.slice(0, equalsIndex);
+      const optionValue = token.slice(equalsIndex + 1);
+      if (TEAM_VALUE_OPTIONS.has(optionName)) {
+        if (!optionValue) {
+          return { ...parsed, error: `${optionName} requires a value` };
+        }
+        applyTeamValueOption(parsed, optionName, optionValue);
+        continue;
+      }
+    }
+
+    if (TEAM_VALUE_OPTIONS.has(token)) {
+      const optionValue = argv[index + 1];
+      if (!optionValue) {
+        return { ...parsed, error: `${token} requires a value` };
+      }
+      applyTeamValueOption(parsed, token, optionValue);
+      index += 1;
+      continue;
+    }
+
+    if (token === "--help" || token === "-h") {
+      parsed.help = true;
+      continue;
+    }
+
+    if (token === "--json") {
+      parsed.json = true;
+      continue;
+    }
+
+    if (token === "--browser-data") {
+      parsed.browserData = true;
+      continue;
+    }
+
+    if (token === "--limit") {
+      const limit = argv[index + 1];
+      if (!limit) {
+        return { ...parsed, error: "--limit requires a number" };
+      }
+      const parsedLimit = Number.parseInt(limit, 10);
+      if (!Number.isInteger(parsedLimit) || parsedLimit < 1) {
+        return { ...parsed, error: "--limit must be a positive integer" };
+      }
+      parsed.limit = parsedLimit;
+      parsed.limitProvided = true;
+      index += 1;
+      continue;
+    }
+
+    if (token.startsWith("--limit=")) {
+      const limit = token.slice("--limit=".length);
+      const parsedLimit = Number.parseInt(limit, 10);
+      if (!Number.isInteger(parsedLimit) || parsedLimit < 1) {
+        return { ...parsed, error: "--limit must be a positive integer" };
+      }
+      parsed.limit = parsedLimit;
+      parsed.limitProvided = true;
+      continue;
+    }
+
+    if (token === "--stdin") {
+      parsed.stdin = true;
+      continue;
+    }
+
+    if (token === "--input-path") {
+      const inputPath = argv[index + 1];
+      if (!inputPath) {
+        return { ...parsed, error: "--input-path requires a path" };
+      }
+      parsed.inputPath = inputPath;
+      index += 1;
+      continue;
+    }
+
+    if (token.startsWith("--input-path=")) {
+      const inputPath = token.slice("--input-path=".length);
+      if (!inputPath) {
+        return { ...parsed, error: "--input-path requires a path" };
+      }
+      parsed.inputPath = inputPath;
+      continue;
+    }
+
+    if (token === "--source") {
+      const source = argv[index + 1];
+      if (!source) {
+        return { ...parsed, error: "--source requires a value" };
+      }
+      parsed.source = source;
+      index += 1;
+      continue;
+    }
+
+    if (token.startsWith("--source=")) {
+      const source = token.slice("--source=".length);
+      if (!source) {
+        return { ...parsed, error: "--source requires a value" };
+      }
+      parsed.source = source;
+      continue;
+    }
+
+    if (token === "--title") {
+      const title = argv[index + 1];
+      if (!title) {
+        return { ...parsed, error: "--title requires a value" };
+      }
+      parsed.title = title;
+      index += 1;
+      continue;
+    }
+
+    if (token.startsWith("--title=")) {
+      const title = token.slice("--title=".length);
+      if (!title) {
+        return { ...parsed, error: "--title requires a value" };
+      }
+      parsed.title = title;
+      continue;
+    }
+
+    if (token === "--tags") {
+      const tags = argv[index + 1];
+      if (!tags) {
+        return { ...parsed, error: "--tags requires a value" };
+      }
+      parsed.tags = tags;
+      index += 1;
+      continue;
+    }
+
+    if (token.startsWith("--tags=")) {
+      const tags = token.slice("--tags=".length);
+      if (!tags) {
+        return { ...parsed, error: "--tags requires a value" };
+      }
+      parsed.tags = tags;
+      continue;
+    }
+
+    if (token === "--query") {
+      const query = argv[index + 1];
+      if (!query) {
+        return { ...parsed, error: "--query requires a value" };
+      }
+      parsed.query = query;
+      index += 1;
+      continue;
+    }
+
+    if (token.startsWith("--query=")) {
+      const query = token.slice("--query=".length);
+      if (!query) {
+        return { ...parsed, error: "--query requires a value" };
+      }
+      parsed.query = query;
+      continue;
+    }
+
+    if (token === "--result-count") {
+      const resultCount = argv[index + 1];
+      if (!resultCount) {
+        return { ...parsed, error: "--result-count requires a number" };
+      }
+      const parsedResultCount = Number.parseInt(resultCount, 10);
+      if (!Number.isInteger(parsedResultCount) || parsedResultCount < 0) {
+        return { ...parsed, error: "--result-count must be a non-negative integer" };
+      }
+      parsed.resultCount = parsedResultCount;
+      index += 1;
+      continue;
+    }
+
+    if (token.startsWith("--result-count=")) {
+      const resultCount = token.slice("--result-count=".length);
+      const parsedResultCount = Number.parseInt(resultCount, 10);
+      if (!Number.isInteger(parsedResultCount) || parsedResultCount < 0) {
+        return { ...parsed, error: "--result-count must be a non-negative integer" };
+      }
+      parsed.resultCount = parsedResultCount;
+      continue;
+    }
+
+    if (token === "--stdin") {
+      parsed.stdin = true;
+      continue;
+    }
+
+    if (token === "--browser-data") {
+      parsed.browserData = true;
+      continue;
+    }
+
+    if (token === "--format") {
+      const format = argv[index + 1];
+      if (!format) {
+        return { ...parsed, error: "--format requires a value" };
+      }
+      if (format !== "context") {
+        return { ...parsed, error: `Unsupported format: ${format}` };
+      }
+      parsed.format = format;
+      index += 1;
+      continue;
+    }
+
+    if (token.startsWith("--format=")) {
+      const format = token.slice("--format=".length);
+      if (!format) {
+        return { ...parsed, error: "--format requires a value" };
+      }
+      if (format !== "context") {
+        return { ...parsed, error: `Unsupported format: ${format}` };
+      }
+      parsed.format = format;
+      continue;
+    }
+
+    if (token === "--project") {
+      const project = argv[index + 1];
+      if (!project) {
+        return { ...parsed, error: "--project requires a name" };
+      }
+      parsed.project = project;
+      index += 1;
+      continue;
+    }
+
+    if (token.startsWith("--project=")) {
+      const project = token.slice("--project=".length);
+      if (!project) {
+        return { ...parsed, error: "--project requires a name" };
+      }
+      parsed.project = project;
+      continue;
+    }
+
+    if (token === "--wiki-root") {
+      const wikiRoot = argv[index + 1];
+      if (!wikiRoot) {
+        return { ...parsed, error: "--wiki-root requires a path" };
+      }
+      parsed.wikiRoot = wikiRoot;
+      parsed.wikiRootInput = wikiRoot;
+      index += 1;
+      continue;
+    }
+
+    if (token.startsWith("--wiki-root=")) {
+      const wikiRoot = token.slice("--wiki-root=".length);
+      if (!wikiRoot) {
+        return { ...parsed, error: "--wiki-root requires a path" };
+      }
+      parsed.wikiRoot = wikiRoot;
+      parsed.wikiRootInput = wikiRoot;
+      continue;
+    }
+
+    if (token.startsWith("-")) {
+      return { ...parsed, error: `Unknown option: ${token}` };
+    }
+
+    if (!parsed.command) {
+      parsed.command = token;
+    } else {
+      parsed.args.push(token);
+    }
+  }
+
+  parsed.wikiRoot = path.resolve(expandHome(parsed.wikiRoot));
+  return parsed;
+}
+
+function humanMessage(result) {
+  if (result.message) return result.message;
+  if (typeof result.ok === "boolean") {
+    const errorCount = result.errors?.length || 0;
+    const warningCount = result.warnings?.length || 0;
+    return result.ok
+      ? `Lint passed for ${result.entries?.length || 0} entr${(result.entries?.length || 0) === 1 ? "y" : "ies"}.`
+      : `Lint found ${errorCount} error(s) and ${warningCount} warning(s).`;
+  }
+  if (result.success === false) return result.error || "Command failed";
+  return "OK";
+}
+
+function outputResult(result, json) {
+  if (json) {
+    print(JSON.stringify(result, null, 2), result.success === false);
+  } else {
+    print(humanMessage(result), result.success === false);
+  }
+}
+
+function stubResult(command, wikiRoot) {
+  return {
+    success: true,
+    command,
+    implemented: false,
+    wikiRoot,
+    message: `${command} is not implemented yet.`,
+  };
+}
+
+function createOpenCodeSnippet(wikiRootInput) {
+  return {
+    plugin: [
+      ["oh-my-llmwikimode", {
+        wikiRoot: wikiRootInput,
+        autoMemoryEnabled: true,
+        autoSearchEnabled: true,
+      }],
+    ],
+  };
+}
+
+function defaultOpenCodeConfigPath() {
+  return path.join(os.homedir(), ".config", "opencode", "opencode.json");
+}
+
+function initializeWikiDirectories(wikiRoot) {
+  const paths = getWikiPaths(wikiRoot);
+  const directoryPaths = [
+    paths.root,
+    paths.inbox,
+    paths.problems,
+    paths.lessons,
+    paths.projects,
+    paths.rawRoot,
+    paths.rawSources,
+    paths.rawNotebooklm,
+    paths.rawPacks,
+    paths.system,
+  ];
+  const directories = directoryPaths.map((directoryPath) => ({
+    path: directoryPath,
+    created: !fs.existsSync(directoryPath),
+  }));
+
+  ensureWikiStructure(paths);
+  return directories;
+}
+
+function runInit({ wikiRoot, wikiRootInput }) {
+  const directories = initializeWikiDirectories(wikiRoot);
+  const snippet = createOpenCodeSnippet(wikiRootInput);
+  const snippetPath = path.join(wikiRoot, ".system", "opencode.plugin-snippet.json");
+
+  fs.writeFileSync(snippetPath, `${JSON.stringify(snippet, null, 2)}\n`, "utf-8");
+
+  return {
+    success: true,
+    wikiRoot,
+    directories,
+    snippetPath,
+    opencodeConfigPath: defaultOpenCodeConfigPath(),
+    snippet,
+    message: [
+      `Initialized LLM Wiki at ${wikiRoot}.`,
+      `OpenCode snippet written to ${snippetPath}.`,
+      `Merge the snippet into ${defaultOpenCodeConfigPath()}, then restart OpenCode.`,
+    ].join("\n"),
+  };
+}
+
+function runLint({ wikiRoot }) {
+  return lintWiki(wikiRoot);
+}
+
+function runDoctor({ wikiRoot }) {
+  return doctorWiki(wikiRoot);
+}
+
+function runQuery({ args, wikiRoot, format }) {
+  if (args.length === 0) {
+    return { success: false, error: "query requires search text" };
+  }
+
+  const query = args.join(" ");
+  return queryWiki(wikiRoot, query, { format });
+}
+
+function runIngest({ args, inputPath, source, stdin, tags, title, wikiRoot, project }) {
+  const inputText = stdin ? fs.readFileSync(0, "utf-8") : undefined;
+  return ingestKnowledge({
+    wikiRoot,
+    inputText,
+    inputPath: inputPath || args[0],
+    source,
+    title,
+    tags,
+    project,
+  });
+}
+
+function runPromote({ args, wikiRoot }) {
+  const entryPath = args[0];
+  if (!entryPath) {
+    return { success: false, error: "promote requires an entry path" };
+  }
+
+  const result = promoteEntry(wikiRoot, entryPath);
+  if (!result.success) return result;
+
+  buildIndex(wikiRoot);
+  rebuildBrowserData(wikiRoot);
+  return {
+    ...result,
+    wikiRoot,
+    message: `Promoted to lesson: ${result.path}`,
+  };
+}
+
+function runReject({ args, wikiRoot }) {
+  const entryPath = args[0];
+  if (!entryPath) {
+    return { success: false, error: "reject requires an entry path" };
+  }
+
+  const result = rejectEntry(wikiRoot, entryPath);
+  if (!result.success) return result;
+
+  buildIndex(wikiRoot);
+  rebuildBrowserData(wikiRoot);
+  return {
+    ...result,
+    wikiRoot,
+    message: `Rejected entry: ${result.path}`,
+  };
+}
+
+function runRebuild({ wikiRoot }) {
+  const index = buildIndex(wikiRoot);
+  const indexPath = path.join(wikiRoot, ".system", "index.json");
+  const graphPath = path.join(wikiRoot, ".system", "graph.json");
+  const browserDataResult = rebuildBrowserData(wikiRoot);
+
+  return {
+    success: true,
+    wikiRoot,
+    indexPath,
+    graphPath,
+    browserData: true,
+    browserDataPath: browserDataResult.path,
+    browserDataMeta: browserDataResult.data.meta,
+    entries: index.entries.length,
+    message: `Rebuilt index, graph, and browser data for ${index.entries.length} entr${index.entries.length === 1 ? "y" : "ies"}.`,
+  };
+}
+
+function parseAuditLine(line) {
+  try {
+    return JSON.parse(line);
+  } catch (error) {
+    return {
+      timestamp: "",
+      action: "error",
+      reason: `Malformed audit line: ${error.message}`,
+      entry_id: "",
+      source: "auto-memory-audit.jsonl",
+      raw: line,
+    };
+  }
+}
+
+function runAudit({ limit, wikiRoot }) {
+  const auditPath = path.join(wikiRoot, ".system", "auto-memory-audit.jsonl");
+  const entries = fs.existsSync(auditPath)
+    ? fs.readFileSync(auditPath, "utf-8")
+      .split(/\r?\n/)
+      .filter(Boolean)
+      .slice(-limit)
+      .map(parseAuditLine)
+    : [];
+
+  return {
+    success: true,
+    wikiRoot,
+    path: auditPath,
+    limit,
+    entries,
+    message: entries.length > 0
+      ? entries.map((entry) => JSON.stringify(entry)).join("\n")
+      : "No auto-memory audit entries found.",
+  };
+}
+
+function refreshTeamBrowserData(wikiRoot) {
+  rebuildBrowserData(wikiRoot);
+}
+
+function refreshTodoBrowserData(wikiRoot) {
+  rebuildBrowserData(wikiRoot);
+}
+
+function runTodo(parsed) {
+  const action = parsed.args[0] || "list";
+
+  if (action === "add") {
+    const title = (parsed.title || parsed.args.slice(1).join(" ")).trim();
+    if (!title) return { success: false, error: "todo add requires a title" };
+    const result = addTodo(parsed.wikiRoot, {
+      title,
+      project: parsed.project,
+      tags: parseList(parsed.tags),
+    }, { actor: "cli" });
+    if (result.success) refreshTodoBrowserData(parsed.wikiRoot);
+    return { ...result, wikiRoot: parsed.wikiRoot };
+  }
+
+  if (action === "list") {
+    const result = listTodos(parsed.wikiRoot, { project: parsed.project });
+    return { ...result, wikiRoot: parsed.wikiRoot };
+  }
+
+  if (action === "done") {
+    const idOrTitle = parsed.args.slice(1).join(" ").trim();
+    if (!idOrTitle) return { success: false, error: "todo done requires an id or title" };
+    const result = markTodoDone(parsed.wikiRoot, idOrTitle, { actor: "cli" });
+    if (result.success) refreshTodoBrowserData(parsed.wikiRoot);
+    return { ...result, wikiRoot: parsed.wikiRoot };
+  }
+
+  if (action === "remove") {
+    const idOrTitle = parsed.args.slice(1).join(" ").trim();
+    if (!idOrTitle) return { success: false, error: "todo remove requires an id or title" };
+    const result = removeTodo(parsed.wikiRoot, idOrTitle, { actor: "cli" });
+    if (result.success) refreshTodoBrowserData(parsed.wikiRoot);
+    return { ...result, wikiRoot: parsed.wikiRoot };
+  }
+
+  return { success: false, error: `Unknown todo subcommand: ${action}` };
+}
+
+function approvalFromParsed(parsed) {
+  return {
+    approved_by: parsed.approvedBy || "cli",
+    approved_at: new Date().toISOString(),
+    approved_capabilities: parsed.approvedCapabilities,
+  };
+}
+
+function requireTeamTaskId(args, action) {
+  const taskId = args[1];
+  if (!taskId) return { success: false, error: `team ${action} requires a task id` };
+  return { success: true, taskId };
+}
+
+function runTeam(parsed) {
+  const action = parsed.args[0] || "list";
+
+  if (action === "list") {
+    return {
+      success: true,
+      wikiRoot: parsed.wikiRoot,
+      queue: readAgentTeamQueue(parsed.wikiRoot),
+      message: "Agent Team queue loaded.",
+    };
+  }
+
+  if (action === "create-task") {
+    const result = createTaskCard(parsed.wikiRoot, {
+      id: parsed.id,
+      title: parsed.title,
+      role_id: parsed.roleId,
+      agent_profile_id: parsed.agentProfileId,
+      goal: parsed.goal,
+      success_criteria: parsed.criteria,
+      capability_request: parsed.capabilities,
+    }, { actor: "cli" });
+    if (result.success) refreshTeamBrowserData(parsed.wikiRoot);
+    return result;
+  }
+
+  if (action === "create-profile") {
+    const result = createAgentProfile(parsed.wikiRoot, {
+      id: parsed.id,
+      label: parsed.title,
+      kind: parsed.kind,
+      default_role_id: parsed.roleId,
+      scope: parsed.scope,
+      capability_policy: {
+        allowed: parsed.allowedCapabilities,
+        requires_approval: parsed.requiresApprovalCapabilities,
+        denied: parsed.deniedCapabilities,
+      },
+      dispatch_template: parsed.template,
+    }, { actor: "cli" });
+    if (result.success) refreshTeamBrowserData(parsed.wikiRoot);
+    return result;
+  }
+
+  if (action === "create-group") {
+    const result = createAgentGroup(parsed.wikiRoot, {
+      id: parsed.id,
+      label: parsed.title,
+      agent_profile_ids: parsed.profiles,
+      default_queue_policy: parsed.policy,
+      description: parsed.description || "",
+    }, { actor: "cli" });
+    if (result.success) refreshTeamBrowserData(parsed.wikiRoot);
+    return result;
+  }
+
+  if (action === "approve") {
+    const taskIdResult = requireTeamTaskId(parsed.args, action);
+    if (!taskIdResult.success) return taskIdResult;
+    const result = updateTaskStatus(parsed.wikiRoot, taskIdResult.taskId, "approved", {
+      actor: "cli",
+      approval: approvalFromParsed(parsed),
+    });
+    if (result.success) refreshTeamBrowserData(parsed.wikiRoot);
+    return result;
+  }
+
+  if (action === "status") {
+    const taskIdResult = requireTeamTaskId(parsed.args, action);
+    if (!taskIdResult.success) return taskIdResult;
+    const status = parsed.args[2];
+    if (!status) return { success: false, error: "team status requires a target status" };
+    const options = { actor: "cli" };
+    if (parsed.blockedReason) options.blocked_reason = parsed.blockedReason;
+    if (parsed.approvedBy || parsed.approvedCapabilities.length > 0) options.approval = approvalFromParsed(parsed);
+    const result = updateTaskStatus(parsed.wikiRoot, taskIdResult.taskId, status, options);
+    if (result.success) refreshTeamBrowserData(parsed.wikiRoot);
+    return result;
+  }
+
+  if (action === "generate-packet") {
+    const taskIdResult = requireTeamTaskId(parsed.args, action);
+    if (!taskIdResult.success) return taskIdResult;
+    const result = createDispatchPacketArtifact(parsed.wikiRoot, taskIdResult.taskId, { actor: "cli" });
+    if (result.success) refreshTeamBrowserData(parsed.wikiRoot);
+    return result;
+  }
+
+  if (action === "evidence") {
+    const taskIdResult = requireTeamTaskId(parsed.args, action);
+    if (!taskIdResult.success) return taskIdResult;
+    const result = appendTaskEvidence(parsed.wikiRoot, taskIdResult.taskId, {
+      id: parsed.id || `evidence-${taskIdResult.taskId}`,
+      agent_profile_id: parsed.agentProfileId,
+      summary: parsed.summary,
+      artifacts: parsed.artifacts,
+      created_at: new Date().toISOString(),
+    }, { actor: "cli" });
+    if (result.success) refreshTeamBrowserData(parsed.wikiRoot);
+    return result;
+  }
+
+  return { success: false, error: `Unknown team subcommand: ${action}` };
+}
+
+function refreshCuratorBrowserData(wikiRoot) {
+  rebuildBrowserData(wikiRoot);
+}
+
+function runCurator(parsed) {
+  const action = parsed.args[0] || "list";
+
+  if (action === "list") {
+    return {
+      success: true,
+      wikiRoot: parsed.wikiRoot,
+      queue: readCuratorQueue(parsed.wikiRoot),
+      curator: buildCuratorBrowserData(parsed.wikiRoot),
+      message: "Curator queue loaded.",
+    };
+  }
+
+  if (action === "suggest-lesson") {
+    const result = suggestLessonCandidate(parsed.wikiRoot, {
+      source: parsed.source,
+      related: parsed.related,
+      title: parsed.title,
+      summary: parsed.summary,
+    }, { actor: "cli" });
+    if (result.success) refreshCuratorBrowserData(parsed.wikiRoot);
+    return result;
+  }
+
+  if (action === "propose-consolidation") {
+    const positionalEntries = parsed.args.slice(1);
+    const result = proposeConsolidation(parsed.wikiRoot, {
+      entries: parsed.entries.length > 0 ? parsed.entries : positionalEntries,
+      rationale: parsed.rationale,
+      title: parsed.title,
+    }, { actor: "cli" });
+    if (result.success) refreshCuratorBrowserData(parsed.wikiRoot);
+    return result;
+  }
+
+  return { success: false, error: `Unknown curator subcommand: ${action}` };
+}
+
+function runDigest(parsed) {
+  const action = parsed.args[0] || "list";
+
+  if (action === "generate") {
+    return generateWeeklyDigest(parsed.wikiRoot, { actor: "cli" });
+  }
+
+  if (action === "list") {
+    return listDigests(parsed.wikiRoot);
+  }
+
+  if (action === "show") {
+    const digestId = parsed.args[1] || parsed.id;
+    if (!digestId) return { success: false, error: "digest show requires a digest ID" };
+    return getDigest(parsed.wikiRoot, digestId);
+  }
+
+  return { success: false, error: `Unknown digest subcommand: ${action}` };
+}
+
+function refreshGraphReasoningBrowserData(wikiRoot) {
+  rebuildBrowserData(wikiRoot);
+}
+
+function runSourceLedger(parsed) {
+  const action = parsed.args[0] || "list";
+
+  if (action === "import") {
+    const filePath = parsed.args[1] || parsed.inputPath;
+    if (!filePath) {
+      return { success: false, error: "source-ledger import requires a file path" };
+    }
+    const result = importSourceFile(parsed.wikiRoot, filePath, {
+      actor: "cli",
+      source_id: parsed.id,
+      title: parsed.title,
+      kind: parsed.kind,
+    });
+    return result;
+  }
+
+  if (action === "list") {
+    const result = readSourceRecords(parsed.wikiRoot);
+    if (!result.success) return result;
+    const sorted = [...result.records].sort(function (a, b) {
+      var byTime = String(a.imported_at || "").localeCompare(String(b.imported_at || ""));
+      if (byTime !== 0) return byTime;
+      return String(a.source_id || "").localeCompare(String(b.source_id || ""));
+    });
+    return { success: true, records: sorted, message: "Source ledger has " + sorted.length + " record(s)." };
+  }
+
+  if (action === "search") {
+    const query = parsed.args[1] || parsed.summary;
+    if (!query) {
+      return { success: false, error: "source-ledger search requires a query" };
+    }
+    const recordsResult = readSourceRecords(parsed.wikiRoot);
+    if (!recordsResult.success) return recordsResult;
+    const queryLower = String(query).toLowerCase();
+    const hits = [];
+    for (const r of recordsResult.records) {
+      let matches = false;
+      let snippet = String(r.title || "");
+      // Check metadata
+      if (snippet.toLowerCase().includes(queryLower)) matches = true;
+      if (String(r.source_path || "").toLowerCase().includes(queryLower)) matches = true;
+      if (String(r.kind || "").toLowerCase().includes(queryLower)) matches = true;
+      // For text sources, search content
+      if (r.redaction === "content_redacted" || r.redaction === "content_clean") {
+        try {
+          const contentPath = path.join(parsed.wikiRoot, "raw", "sources", "files", r.source_id, "content.txt");
+          if (fs.existsSync(contentPath)) {
+            const content = fs.readFileSync(contentPath, "utf-8");
+            if (content.toLowerCase().includes(queryLower)) {
+              matches = true;
+              // Extract a snippet around the match
+              const idx = content.toLowerCase().indexOf(queryLower);
+              const start = Math.max(0, idx - 50);
+              const end = Math.min(content.length, idx + queryLower.length + 50);
+              snippet = content.slice(start, end).replace(/\s+/g, " ").trim();
+            }
+          }
+        } catch {
+          // Ignore read errors
+        }
+      }
+      if (matches) {
+        hits.push({
+          source_id: r.source_id,
+          path: r.source_path,
+          chunk_id: "source",
+          snippet: snippet.slice(0, 200),
+          score: 1,
+          review_status: "raw_evidence",
+        });
+      }
+    }
+    return { success: true, hits, query, message: "Source ledger search: " + hits.length + " hit(s)." };
+  }
+
+  return { success: false, error: "Unknown source-ledger subcommand: " + action };
+}
+
+function runStage4(parsed) {
+  const action = parsed.args[0] || "";
+
+  if (action === "graph-reasoning") {
+    const subAction = parsed.args[1] || "list";
+
+    if (subAction === "list") {
+      return {
+        success: true,
+        wikiRoot: parsed.wikiRoot,
+        queue: readGraphReasoningQueue(parsed.wikiRoot),
+        graph_reasoning: buildGraphReasoningBrowserData(parsed.wikiRoot),
+        message: "Stage 4 graph reasoning queue loaded.",
+      };
+    }
+
+    if (subAction === "analyze") {
+      const result = runGraphReasoningAnalysis(parsed.wikiRoot, { actor: "cli" });
+      if (result.success) refreshGraphReasoningBrowserData(parsed.wikiRoot);
+      return result;
+    }
+
+    return { success: false, error: `Unknown stage4 graph-reasoning subcommand: ${subAction}` };
+  }
+
+  return { success: false, error: `Unknown stage4 subcommand: ${action}` };
+}
+
+function runRaw(parsed) {
+  const action = parsed.args[0] || "list";
+
+  if (action === "list") {
+    const result = listRawContents(parsed.wikiRoot);
+    return {
+      success: true,
+      wikiRoot: parsed.wikiRoot,
+      data: result,
+      message: parsed.json
+        ? undefined
+        : `Sources: ${result.sources.length}, NotebookLM: ${result.notebooklm.length}, Packs: ${result.packs.length}`,
+    };
+  }
+
+  if (action === "status") {
+    const result = getRawSummary(parsed.wikiRoot);
+    return {
+      success: true,
+      wikiRoot: parsed.wikiRoot,
+      data: result,
+      message: parsed.json
+        ? undefined
+        : `Raw total: ${result.total_files} files, ${result.total_bytes} bytes`,
+    };
+  }
+
+  if (action === "validate") {
+    const result = validateRawStructure(parsed.wikiRoot);
+    return {
+      success: result.valid,
+      wikiRoot: parsed.wikiRoot,
+      data: result,
+      message: result.valid
+        ? "Raw structure is valid."
+        : `Raw structure invalid: ${result.checks.filter((c) => c.required && !c.exists).map((c) => c.path).join(", ")}`,
+    };
+  }
+
+  return { success: false, error: `Unknown raw subcommand: ${action}` };
+}
+
+function runSearchFeedback(parsed) {
+  const action = parsed.args[0] || "list";
+
+  if (action === "list") {
+    const result = readSearchFailures(parsed.wikiRoot, { limit: parsed.limit || 100 });
+    if (!result.success) return result;
+    return {
+      success: true,
+      wikiRoot: parsed.wikiRoot,
+      failures: result.events,
+      count: result.events.length,
+      message: result.events.length > 0
+        ? result.events.map((e) => JSON.stringify(e)).join("\n")
+        : "No search failures recorded.",
+    };
+  }
+
+  if (action === "record") {
+    const query = parsed.query || parsed.summary || parsed.args[1] || "";
+    const resultCount = Number(parsed.resultCount ?? parsed.args[2] ?? 0);
+    if (!query) {
+      return { success: false, error: "search-feedback record requires --query or a positional argument" };
+    }
+    const result = appendSearchFailure(parsed.wikiRoot, {
+      query,
+      result_count: resultCount,
+      max_results: parsed.limit || 3,
+      source: "manual_cli",
+    });
+    return result;
+  }
+
+  if (action === "suggest-aliases") {
+    const failuresResult = readSearchFailures(parsed.wikiRoot, { limit: 50 });
+    if (!failuresResult.success) return failuresResult;
+
+    const index = buildIndex(parsed.wikiRoot);
+    const suggestions = [];
+    for (const failure of failuresResult.events) {
+      const result = generateAliasSuggestion(parsed.wikiRoot, failure, index);
+      if (result.success) {
+        suggestions.push(result.skipped
+          ? { skipped: true, reason: result.reason, query: failure.query }
+          : { created: true, id: result.artifact.id, path: result.path }
+        );
+      }
+    }
+
+    return {
+      success: true,
+      wikiRoot: parsed.wikiRoot,
+      suggestions,
+      generated: suggestions.filter((s) => s.created).length,
+      skipped: suggestions.filter((s) => s.skipped).length,
+      message: `Generated ${suggestions.filter((s) => s.created).length} alias suggestion(s), skipped ${suggestions.filter((s) => s.skipped).length}.`,
+    };
+  }
+
+  return { success: false, error: `Unknown search-feedback subcommand: ${action}` };
+}
+
+async function runSemanticSearch(parsed) {
+  const query = parsed.args.join(" ").trim();
+  if (!query) {
+    return { success: false, error: "semantic-search requires a query" };
+  }
+
+  const searchResult = await semanticSearch(parsed.wikiRoot, query, {
+    topK: parsed.limitProvided ? parsed.limit : 5,
+  });
+  const results = searchResult.results;
+
+  return {
+    success: true,
+    wikiRoot: parsed.wikiRoot,
+    ...searchResult,
+    count: results.length,
+    message: results.length > 0
+      ? results.map((result) => `${result.similarity.toFixed(4)} ${result.path} ${result.title}`).join("\n")
+      : "No semantic results found.",
+  };
+}
+
+async function runSemanticIndex(parsed) {
+  const action = parsed.args[0] || "status";
+
+  if (action === "build") {
+    const result = await buildSemanticIndex(parsed.wikiRoot);
+    if (!result.success) return result;
+    return {
+      ...result,
+      wikiRoot: parsed.wikiRoot,
+      message: `Built semantic index with ${result.count} entr${result.count === 1 ? "y" : "ies"}.`,
+    };
+  }
+
+  if (action === "status") {
+    const result = loadSemanticIndex(parsed.wikiRoot);
+    if (!result.success) return result;
+    const fileSize = fs.existsSync(result.path) ? fs.statSync(result.path).size : 0;
+    const lastBuild = result.entries.reduce((latest, entry) => {
+      const ts = String(entry.ts || "");
+      return ts > latest ? ts : latest;
+    }, "");
+    return {
+      success: true,
+      wikiRoot: parsed.wikiRoot,
+      path: result.path,
+      count: getSemanticIndexSize(parsed.wikiRoot),
+      size_bytes: fileSize,
+      last_build: lastBuild || null,
+      message: `Semantic index: ${result.entries.length} entr${result.entries.length === 1 ? "y" : "ies"}, ${fileSize} bytes.`,
+    };
+  }
+
+  if (action === "update") {
+    const result = await updateSemanticIndex(parsed.wikiRoot);
+    if (!result.success) return result;
+    return {
+      ...result,
+      wikiRoot: parsed.wikiRoot,
+      message: `Updated semantic index with ${result.count} entr${result.count === 1 ? "y" : "ies"}.`,
+    };
+  }
+
+  return { success: false, error: `Unknown semantic-index subcommand: ${action}` };
+}
+
+function runLessonProposal(parsed) {
+  const action = parsed.args[0] || "list";
+
+  if (action === "analyze") {
+    const result = generateLessonProposals(parsed.wikiRoot, {
+      days: parsed.limitProvided ? parsed.limit : 30,
+    });
+    if (!result.success) return result;
+    return {
+      ...result,
+      wikiRoot: parsed.wikiRoot,
+      message: `Analyzed ${result.total_events} usage events. Generated ${result.proposals_generated} proposal(s), skipped ${result.proposals_skipped} duplicate(s).`,
+    };
+  }
+
+  if (action === "list") {
+    const result = listProposals(parsed.wikiRoot);
+    if (!result.success) return result;
+    return {
+      ...result,
+      wikiRoot: parsed.wikiRoot,
+      message: result.count > 0
+        ? `${result.count} lesson proposal(s) found.`
+        : "No lesson proposals found.",
+    };
+  }
+
+  if (action === "show") {
+    const proposalId = parsed.args[1] || parsed.id;
+    if (!proposalId) {
+      return { success: false, error: "lesson-proposal show requires a proposal ID" };
+    }
+    const result = getProposal(parsed.wikiRoot, proposalId);
+    if (!result.success) return result;
+    return {
+      ...result,
+      wikiRoot: parsed.wikiRoot,
+      message: `Proposal: ${result.proposal.proposed_title} (${result.proposal.status})`,
+    };
+  }
+
+  if (action === "apply") {
+    const proposalId = parsed.args[1] || parsed.id;
+    if (!proposalId) {
+      return { success: false, error: "lesson-proposal apply requires a proposal ID" };
+    }
+    const result = applyProposal(parsed.wikiRoot, proposalId, {
+      actor: "cli",
+      now: parsed.now,
+    });
+    if (result.success) {
+      try {
+        buildIndex(parsed.wikiRoot);
+        rebuildBrowserData(parsed.wikiRoot);
+      } catch (rebuildError) {
+        return {
+          success: true,
+          warning: `Lesson created, but index rebuild failed: ${rebuildError.message}`,
+          ...result,
+        };
+      }
+    }
+    return result;
+  }
+
+  return { success: false, error: `Unknown lesson-proposal subcommand: ${action}` };
+}
+
+const HANDLERS = {
+  init: runInit,
+  lint: runLint,
+  doctor: runDoctor,
+  query: runQuery,
+  ingest: runIngest,
+  promote: runPromote,
+  reject: runReject,
+  rebuild: runRebuild,
+  audit: runAudit,
+  todo: runTodo,
+  team: runTeam,
+  curator: runCurator,
+  digest: runDigest,
+  "source-ledger": runSourceLedger,
+  stage4: runStage4,
+  "search-feedback": runSearchFeedback,
+  "semantic-search": runSemanticSearch,
+  "semantic-index": runSemanticIndex,
+  raw: runRaw,
+  "lesson-proposal": runLessonProposal,
+};
+
+function handleHelp(commandName, json) {
+  if (json) {
+    print(JSON.stringify(helpPayload(commandName), null, 2));
+  } else if (commandName) {
+    print(commandHelp(commandName));
+  } else {
+    print(mainHelp());
+  }
+}
+
+async function main() {
+  const parsed = parseArgs(process.argv.slice(2));
+
+  if (parsed.error) {
+    outputResult({ success: false, error: parsed.error }, parsed.json);
+    return 1;
+  }
+
+  if (!parsed.command) {
+    handleHelp(null, parsed.json);
+    return 0;
+  }
+
+  if (!Object.hasOwn(COMMANDS, parsed.command)) {
+    outputResult({ success: false, error: `Unknown command: ${parsed.command}` }, parsed.json);
+    return 1;
+  }
+
+  if (parsed.help) {
+    handleHelp(parsed.command, parsed.json);
+    return 0;
+  }
+
+  const result = await HANDLERS[parsed.command](parsed);
+  outputResult(result, parsed.json);
+  return result.success === false ? 1 : 0;
+}
+
+main()
+  .then((code) => {
+    process.exitCode = code;
+  })
+  .catch((error) => {
+    outputResult({ success: false, error: error.message }, process.argv.includes("--json"));
+    process.exitCode = 1;
+  });