@time-machine-lab/tmlbrain 0.1.0

package/bin/tmlbrain.js

@@ -0,0 +1,1653 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const http = require("http");
+const https = require("https");
+const readline = require("readline");
+const { spawnSync } = require("child_process");
+
+const PACKAGE_ROOT = path.resolve(__dirname, "..");
+const ROOT = findRoot(process.cwd());
+const KNOWLEDGE_DIR = path.join(ROOT, "knowledge");
+const LOCAL_DIR = path.join(ROOT, ".tmlbrain");
+const INDEX_DIR = path.join(LOCAL_DIR, "index");
+const BASE_DIR = path.join(LOCAL_DIR, "base");
+const CONFLICT_DIR = path.join(LOCAL_DIR, "conflicts");
+const PATCH_DIR = path.join(LOCAL_DIR, "patches");
+const LOG_DIR = path.join(LOCAL_DIR, "logs");
+const STATE_FILE = path.join(LOCAL_DIR, "state.json");
+
+const VALID_TYPES = new Set(["project", "area", "resource", "reference", "meeting", "decision"]);
+const VALID_STATUSES = new Set(["draft", "active", "stale", "archived"]);
+const DEFAULT_SERVER_HOST = "127.0.0.1";
+const DEFAULT_SERVER_PORT = 7389;
+
+main().catch((error) => fail(error.message || String(error)));
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args.shift() || "help";
+
+  try {
+    switch (command) {
+      case "help":
+      case "-h":
+      case "--help":
+        printHelp();
+        break;
+      case "install":
+      case "init":
+        cmdInstall(args);
+        break;
+      case "client":
+        await cmdClient(args);
+        break;
+      case "doctor":
+        cmdDoctor(args);
+        break;
+      case "validate":
+        cmdValidate(args);
+        break;
+      case "search":
+      case "find":
+        cmdSearch(args);
+        break;
+      case "index":
+      case "reindex":
+        cmdIndex(args);
+        break;
+      case "capabilities":
+        cmdCapabilities(args);
+        break;
+      case "add":
+        await cmdAdd(args);
+        break;
+      case "save":
+        await cmdSave(args);
+        break;
+      case "remote":
+        await cmdRemote(args);
+        break;
+      case "config":
+        cmdConfig(args);
+        break;
+      case "sync":
+        await cmdSync(args);
+        break;
+      case "serve":
+      case "server":
+        cmdServe(args);
+        break;
+      case "patch":
+        cmdPatch(args);
+        break;
+      case "conflict":
+        cmdConflict(args);
+        break;
+      case "backup":
+        cmdBackup(args);
+        break;
+      case "publish":
+        cmdPublish(args);
+        break;
+      case "graph":
+        cmdGraph(args);
+        break;
+      default:
+        fail(`Unknown command: ${command}\nRun "tmlbrain help" for usage.`);
+    }
+  } catch (error) {
+    fail(error.message || String(error));
+  }
+}
+
+function printHelp() {
+  console.log(`TMLBrain knowledge base toolkit
+
+Usage:
+  tmlbrain client install [--server <http-url>] [--token <token>] [--local] [--yes]
+  tmlbrain install [--server <http-url>] [--token <token>] [--graph] [--with-git]
+  tmlbrain config show|set-server|clear-token
+  tmlbrain doctor
+  tmlbrain capabilities [--json]
+  tmlbrain validate [--json]
+  tmlbrain search|find <query> [--json]
+  tmlbrain index [--json]
+  tmlbrain save (--title <title> --content <text> | <file>) [--folder <path>] [--type <type>]
+  tmlbrain add --title <title> [--folder <path>] [--type <type>] [--content <text>] [--local]
+  tmlbrain remote add --title <title> [--folder <path>] [--type <type>] [--content <text>]
+  tmlbrain remote ingest <file> [--title <title>] [--folder <path>] [--type <type>]
+  tmlbrain remote update --file <path> (--replace <text> --with <text> | --content-file <file>)
+  tmlbrain sync [--dry-run] [--pull]
+  tmlbrain serve [--host <host>] [--port <port>] [--token <token>]
+  tmlbrain patch create|check|apply [file]
+  tmlbrain conflict list|show|resolve|demo
+  tmlbrain backup [--dry-run] [--remote <remote>]
+  tmlbrain publish [--dry-run] [--site <dir>] [--pagefind]
+  tmlbrain graph setup [--dry-run]
+
+Clients use local snapshots for search and call the TMLBrain server for writes.
+HTTP-only clients do not need Git. Git is required only for the server runtime
+or legacy Git migration flows.
+Only the server performs repository writes, GitHub backup, or remote Git operations.
+CocoIndex/LightRAG are optional graph-runtime features enabled with "tmlbrain graph setup".`);
+}
+
+async function cmdClient(args) {
+  const action = args.shift() || "install";
+  if (action === "help" || action === "-h" || action === "--help") {
+    console.log(`TMLBrain client commands
+
+Usage:
+  tmlbrain client install [--server <http-url>] [--token <token>] [--local] [--yes]
+  tmlbrain client doctor
+
+If --server is omitted, interactive install asks for one. Press Enter to start
+in local-only mode.`);
+    return;
+  }
+  if (action === "install" || action === "init") {
+    await cmdClientInstall(args);
+    return;
+  }
+  if (action === "doctor") {
+    cmdDoctor(args);
+    return;
+  }
+  fail(`Unknown client action: ${action}`);
+}
+
+async function cmdClientInstall(args) {
+  const opts = parseArgs(args);
+  const interactive = !opts.yes && !opts["non-interactive"];
+  ensureLocalDirs();
+
+  let server = opts.local ? "" : (opts.server || "");
+  let token = opts.token || "";
+  let graph = Boolean(opts.graph);
+
+  if (interactive) {
+    console.log("TMLBrain client setup");
+    console.log(`Workspace: ${ROOT}`);
+    server = await promptText("Server URL (leave empty for local-only)", server);
+    if (server && !isHttpUrl(server)) fail("Server URL must start with http:// or https://");
+    if (server) token = await promptSecret("Server token", token);
+    graph = await promptYesNo("Enable optional CocoIndex/LightRAG graph runtime now?", graph);
+  }
+  if (server && !token) fail("Server token is required when a server URL is configured. Use --token <token> or leave the server URL empty for local-only mode.");
+
+  const installArgs = [];
+  if (server) installArgs.push("--server", server);
+  if (token) installArgs.push("--token", token);
+  if (graph) installArgs.push("--graph");
+  if (opts["dry-run"]) installArgs.push("--dry-run");
+  cmdInstall(installArgs);
+
+  if (server && !opts["skip-sync"] && !opts["dry-run"]) {
+    try {
+      await cmdSync(["--pull", ...(opts.json ? ["--json"] : [])]);
+    } catch (error) {
+      console.warn(`Initial sync failed: ${error.message || String(error)}`);
+      console.warn("Run `tmlbrain sync --pull` after checking the server URL/token.");
+    }
+  } else if (!server) {
+    ensureDir(KNOWLEDGE_DIR);
+    console.log("Local-only mode is ready. Configure a server later with `tmlbrain config set-server <url> --token <token>`.");
+  }
+  console.log("Try `tmlbrain capabilities --json` to see available commands.");
+}
+
+function cmdInstall(args) {
+  const opts = parseArgs(args);
+  ensureLocalDirs();
+  const gitInfo = opts["with-git"] || opts["legacy-git"]
+    ? ensureGit({ install: true, dryRun: Boolean(opts["dry-run"]) })
+    : checkCommand("git", ["--version"]);
+  const state = readState();
+  if (opts.server) state.server = opts.server;
+  if (opts.token) state.token = opts.token;
+  if (!state.workspaceVersion) state.workspaceVersion = 1;
+  state.git = { detected: gitInfo.ok, version: gitInfo.version || null };
+  state.updatedAt = new Date().toISOString();
+  writeJson(STATE_FILE, state);
+  installSkillToCodex({ dryRun: Boolean(opts["dry-run"]) });
+  if (opts.graph) setupGraphRuntime({ dryRun: Boolean(opts["dry-run"]) });
+  console.log("TMLBrain workspace is ready.");
+}
+
+function cmdDoctor(args) {
+  const opts = parseArgs(args);
+  const state = readState();
+  output({
+    root: ROOT,
+    git: checkCommand("git", ["--version"]),
+    node: { ok: true, version: process.version },
+    ripgrep: checkCommand("rg", ["--version"]),
+    state: fs.existsSync(STATE_FILE),
+    server: state.server || null,
+    serverApi: Boolean(state.server && isHttpUrl(state.server)),
+    knowledge: fs.existsSync(KNOWLEDGE_DIR),
+    graphRuntime: detectGraphRuntime()
+  }, opts);
+}
+
+function cmdCapabilities(args) {
+  const opts = parseArgs(args);
+  output(capabilities(), opts);
+}
+
+function cmdConfig(args) {
+  const action = args.shift() || "show";
+  const opts = parseArgs(args);
+  ensureLocalDirs();
+  const state = readState();
+  if (action === "show") {
+    output(safeConfigView(state), opts);
+    return;
+  }
+  if (action === "set-server") {
+    const server = opts.server || opts._[0];
+    if (!server || !isHttpUrl(server)) fail("Use: tmlbrain config set-server <http-url> [--token <token>]");
+    state.server = server;
+    if (opts.token) state.token = opts.token;
+    state.updatedAt = new Date().toISOString();
+    writeJson(STATE_FILE, state);
+    output(safeConfigView(state), opts);
+    return;
+  }
+  if (action === "clear-token") {
+    delete state.token;
+    state.updatedAt = new Date().toISOString();
+    writeJson(STATE_FILE, state);
+    output(safeConfigView(state), opts);
+    return;
+  }
+  fail("Config action must be show, set-server, or clear-token.");
+}
+
+function cmdValidate(args) {
+  const opts = parseArgs(args);
+  const result = validateKnowledge();
+  output(result, opts);
+  if (result.errors.length > 0) process.exit(1);
+}
+
+function cmdSearch(args) {
+  const opts = parseArgs(args);
+  const query = opts._.join(" ").trim();
+  if (!query) fail("Search query is required.");
+  const matches = exactSearch(query);
+  output({ query, count: matches.length, matches }, opts);
+}
+
+function cmdIndex(args) {
+  const opts = parseArgs(args);
+  ensureLocalDirs();
+  const index = buildIndex();
+  writeJson(path.join(INDEX_DIR, "documents.json"), index.documents);
+  writeJson(path.join(INDEX_DIR, "chunks.json"), index.chunks);
+  writeJson(path.join(INDEX_DIR, "graph.json"), index.graph);
+  writeJson(path.join(INDEX_DIR, "manifest.json"), {
+    generatedAt: new Date().toISOString(),
+    documents: index.documents.length,
+    chunks: index.chunks.length,
+    edges: index.graph.edges.length,
+    degraded: detectGraphRuntime().available ? [] : ["graph-semantic-runtime-disabled"]
+  });
+  output({
+    generatedAt: new Date().toISOString(),
+    documents: index.documents.length,
+    chunks: index.chunks.length,
+    edges: index.graph.edges.length,
+    indexDir: rel(INDEX_DIR)
+  }, opts);
+}
+
+async function cmdAdd(args) {
+  const opts = parseArgs(args);
+  if (!opts.local && shouldUseServerWrite(opts)) {
+    const response = await requestServerJson("/knowledge/add", {
+      title: opts.title || opts._.join(" ").trim(),
+      type: opts.type || "resource",
+      folder: opts.folder || folderForType(opts.type || "resource"),
+      slug: opts.slug || null,
+      owner: opts.owner || "TML",
+      content: opts.content || "",
+      message: opts.message || null
+    }, opts);
+    output(response, opts);
+    return;
+  }
+  const title = opts.title || opts._.join(" ").trim();
+  if (!title) fail("Document title is required. Use --title <title>.");
+  const created = createKnowledgeDocument({
+    title,
+    type: opts.type || "resource",
+    folder: opts.folder || folderForType(opts.type || "resource"),
+    slug: opts.slug || title,
+    owner: opts.owner || "TML",
+    content: opts.content || "",
+    force: Boolean(opts.force)
+  });
+  console.log(`Created ${created.path}`);
+}
+
+async function cmdSave(args) {
+  const opts = parseArgs(args);
+  const source = opts.file || opts._[0];
+  const sourcePath = source ? path.resolve(ROOT, source) : null;
+  if (!shouldUseServerWrite(opts)) {
+    if (source && !opts.title && !opts.content && !opts["content-file"] && looksLikeFilePath(source) && (!sourcePath || !fs.existsSync(sourcePath))) {
+      fail(`File not found: ${source}`);
+    }
+    let title = opts.title || opts._.join(" ").trim();
+    let content = opts.content || readContentOption(opts) || "";
+    if (sourcePath && fs.existsSync(sourcePath) && fs.statSync(sourcePath).isFile() && !opts.content && !opts["content-file"]) {
+      title = opts.title || path.basename(sourcePath, path.extname(sourcePath));
+      content = fs.readFileSync(sourcePath, "utf8");
+    }
+    if (!title) fail("Use: tmlbrain save --title <title> --content <text>, or tmlbrain save <file>");
+    const created = createKnowledgeDocument({
+      title,
+      type: opts.type || "resource",
+      folder: opts.folder || "knowledge/00-inbox",
+      slug: opts.slug || title,
+      owner: opts.owner || "TML",
+      content,
+      force: Boolean(opts.force)
+    });
+    output({ ok: true, mode: "local-only", action: "save", path: created.path, sha256: created.sha256 }, opts);
+    return;
+  }
+  if (sourcePath && fs.existsSync(sourcePath) && fs.statSync(sourcePath).isFile() && !opts.content && !opts["content-file"]) {
+    const title = opts.title || path.basename(sourcePath, path.extname(sourcePath));
+    const response = await requestServerJson("/knowledge/add", {
+      title,
+      type: opts.type || "resource",
+      folder: opts.folder || "knowledge/00-inbox",
+      slug: opts.slug || null,
+      owner: opts.owner || "TML",
+      content: fs.readFileSync(sourcePath, "utf8"),
+      message: opts.message || `Save knowledge: ${title}`
+    }, opts);
+    output(response, opts);
+    return;
+  }
+  if (source && !opts.title && !opts.content && !opts["content-file"] && looksLikeFilePath(source)) {
+    fail(`File not found: ${source}`);
+  }
+  const title = opts.title || opts._.join(" ").trim();
+  if (!title) fail("Use: tmlbrain save --title <title> --content <text>, or tmlbrain save <file>");
+  const response = await requestServerJson("/knowledge/add", {
+    title,
+    type: opts.type || "resource",
+    folder: opts.folder || "knowledge/00-inbox",
+    slug: opts.slug || null,
+    owner: opts.owner || "TML",
+    content: opts.content || readContentOption(opts) || "",
+    message: opts.message || `Save knowledge: ${title}`
+  }, opts);
+  output(response, opts);
+}
+
+async function cmdRemote(args) {
+  const action = args.shift() || "help";
+  const opts = parseArgs(args);
+  if (action === "help" || action === "-h" || action === "--help") {
+    console.log(`TMLBrain remote write commands
+
+Usage:
+  tmlbrain remote capabilities [--json]
+  tmlbrain remote add --title <title> [--folder <path>] [--type <type>] [--content <text>]
+  tmlbrain remote ingest <file> [--title <title>] [--folder <path>] [--type <type>]
+  tmlbrain remote update --file <path> (--replace <text> --with <text> | --content-file <file>)`);
+    return;
+  }
+  if (action === "capabilities") {
+    output(await requestServerGetJson("/capabilities", opts), opts);
+    return;
+  }
+  if (action === "add") {
+    const title = opts.title || opts._.join(" ").trim();
+    const response = await requestServerJson("/knowledge/add", {
+      title,
+      type: opts.type || "resource",
+      folder: opts.folder || folderForType(opts.type || "resource"),
+      slug: opts.slug || null,
+      owner: opts.owner || "TML",
+      content: opts.content || readContentOption(opts),
+      message: opts.message || null
+    }, opts);
+    output(response, opts);
+    return;
+  }
+  if (action === "ingest") {
+    const source = opts._[0] || opts.file;
+    if (!source) fail("Use: tmlbrain remote ingest <file>");
+    const sourcePath = path.resolve(ROOT, source);
+    if (!fs.existsSync(sourcePath)) fail(`File not found: ${source}`);
+    const title = opts.title || path.basename(sourcePath, path.extname(sourcePath));
+    const response = await requestServerJson("/knowledge/add", {
+      title,
+      type: opts.type || "resource",
+      folder: opts.folder || "knowledge/00-inbox",
+      slug: opts.slug || null,
+      owner: opts.owner || "TML",
+      content: fs.readFileSync(sourcePath, "utf8"),
+      message: opts.message || `Ingest knowledge: ${title}`
+    }, opts);
+    output(response, opts);
+    return;
+  }
+  if (action === "update") {
+    const file = opts.file || opts._[0];
+    if (!file) fail("Use: tmlbrain remote update --file <path> ...");
+    const payload = {
+      path: file,
+      replace: opts.replace,
+      with: opts.with,
+      content: opts.content || readContentOption(opts),
+      expectedSha256: opts["expected-sha256"] || null,
+      message: opts.message || null
+    };
+    const response = await requestServerJson("/knowledge/update", payload, opts);
+    output(response, opts);
+    return;
+  }
+  fail(`Unknown remote action: ${action}`);
+}
+
+async function cmdSync(args) {
+  const opts = parseArgs(args);
+  ensureLocalDirs();
+  const dryRun = Boolean(opts["dry-run"]);
+  if (opts.push) {
+    fail("Client push is disabled. Use `tmlbrain remote add`, `tmlbrain remote update`, or `tmlbrain remote ingest`; only the TMLBrain server may write repositories.");
+  }
+  const state = readState();
+  if (state.server && isHttpUrl(state.server)) {
+    const result = { dryRun, server: state.server, actions: [] };
+    if (dryRun) {
+      result.actions.push("Would fetch a read-only knowledge snapshot from the TMLBrain server.");
+      output(result, opts);
+      return;
+    }
+    const snapshot = await requestServerGetJson("/snapshot", opts);
+    applySnapshot(snapshot);
+    result.head = snapshot.head;
+    result.files = snapshot.files.length;
+    result.actions.push("Fetched and applied read-only knowledge snapshot from TMLBrain server.");
+    output(result, opts);
+    return;
+  }
+  if (!opts.pull) {
+    fail("Client Git synchronization is disabled. Configure an HTTP server with `tmlbrain install --server <http-url>` and run `tmlbrain sync --pull`.");
+  }
+  if (!opts["legacy-git"]) {
+    fail("Client Git pull is disabled. Configure an HTTP TMLBrain server with `tmlbrain install --server <http-url>`; use `--legacy-git` only for migration.");
+  }
+  ensureGit();
+  const status = git(["status", "--porcelain"]);
+  const upstream = git(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"], { allowFail: true });
+  const result = {
+    dryRun,
+    workingTreeChanged: status.stdout.trim().length > 0,
+    upstream: upstream.ok ? upstream.stdout.trim() : null,
+    actions: []
+  };
+  if (!upstream.ok) {
+    result.actions.push("No upstream remote is configured. TMLBrain sync cannot contact the server yet.");
+    output(result, opts);
+    return;
+  }
+  const fetch = dryRun ? { ok: true, stdout: "" } : git(["fetch", "--prune"], { allowFail: true });
+  result.actions.push(fetch.ok ? "Fetched remote state." : "Remote fetch failed.");
+  if (!fetch.ok) {
+    result.error = sanitizeGit(fetch.stderr || fetch.stdout);
+    output(result, opts);
+    process.exit(1);
+  }
+  if (result.workingTreeChanged) {
+    const patch = createLocalPatch();
+    result.actions.push(`Captured local patch at ${rel(patch)}`);
+    if (hasRemoteChanges()) {
+      const conflict = createConflictPackage({
+        reason: "local changes and remote updates both exist",
+        patchPath: patch,
+        pathName: "workspace",
+        base: "",
+        local: fs.readFileSync(patch, "utf8"),
+        remote: "Remote has updates. Review with tmlbrain conflict show."
+      });
+      result.conflict = rel(conflict);
+      result.actions.push("Created a TMLBrain conflict package instead of entering raw Git conflict handling.");
+      output(result, opts);
+      return;
+    }
+  }
+  if (opts.pull || !opts.push) {
+    const pull = dryRun ? { ok: true, stdout: "dry-run" } : git(["pull", "--ff-only"], { allowFail: true });
+    result.actions.push(pull.ok ? "Local workspace is refreshed." : "Could not fast-forward local workspace.");
+    if (!pull.ok) {
+      result.error = sanitizeGit(pull.stderr || pull.stdout);
+      output(result, opts);
+      process.exit(1);
+    }
+    if (!dryRun) snapshotBase();
+  }
+  output(result, opts);
+}
+
+function cmdServe(args) {
+  const opts = parseArgs(args);
+  ensureGit();
+  ensureGitWorktree();
+  const host = opts.host || process.env.TMLBRAIN_HOST || DEFAULT_SERVER_HOST;
+  const port = Number(opts.port || process.env.TMLBRAIN_PORT || DEFAULT_SERVER_PORT);
+  const token = opts.token || process.env.TMLBRAIN_SERVER_TOKEN || null;
+  const server = http.createServer((req, res) => {
+    routeServerRequest(req, res, token).catch((error) => {
+      sendJson(res, error.statusCode || 500, { ok: false, error: error.message || String(error) });
+    });
+  });
+  server.listen(port, host, () => {
+    console.log(`TMLBrain server listening on http://${host}:${port}`);
+  });
+}
+
+function cmdPatch(args) {
+  const action = args.shift();
+  const opts = parseArgs(args);
+  ensureGit();
+  ensureLocalDirs();
+  if (action === "create") {
+    console.log(rel(createLocalPatch()));
+    return;
+  }
+  const file = opts._[0];
+  if (!file) fail("Patch file is required.");
+  const patchPath = path.resolve(ROOT, file);
+  const patchText = fs.existsSync(patchPath) ? fs.readFileSync(patchPath, "utf8") : "";
+  if ((action === "check" || action === "apply") && patchText.trim() === "") {
+    console.log("Patch is empty; no changes to apply.");
+    return;
+  }
+  if (action === "check") {
+    let check = git(["apply", "--3way", "--check", patchPath], { allowFail: true });
+    if (!check.ok && /does not exist in index/.test(check.stderr || check.stdout)) {
+      check = git(["apply", "--check", patchPath], { allowFail: true });
+    }
+    if (!check.ok) fail(`Patch check failed: ${sanitizeGit(check.stderr || check.stdout)}`);
+    console.log("Patch can be applied.");
+    return;
+  }
+  if (action === "apply") {
+    let apply = git(["apply", "--3way", patchPath], { allowFail: true });
+    if (!apply.ok && /does not exist in index/.test(apply.stderr || apply.stdout)) {
+      apply = git(["apply", patchPath], { allowFail: true });
+    }
+    if (!apply.ok) {
+      const conflict = createConflictPackage({
+        reason: "patch application failed",
+        patchPath,
+        pathName: file,
+        base: "",
+        local: fs.readFileSync(patchPath, "utf8"),
+        remote: sanitizeGit(apply.stderr || apply.stdout)
+      });
+      fail(`Patch could not be applied. Conflict package: ${rel(conflict)}`);
+    }
+    console.log("Patch applied.");
+    return;
+  }
+  fail("Patch action must be create, check, or apply.");
+}
+
+function cmdConflict(args) {
+  const action = args.shift() || "list";
+  const opts = parseArgs(args);
+  ensureDir(CONFLICT_DIR);
+  const files = fs.readdirSync(CONFLICT_DIR).filter((name) => name.endsWith(".json")).sort();
+  if (action === "list") {
+    const conflicts = files.map((name) => JSON.parse(fs.readFileSync(path.join(CONFLICT_DIR, name), "utf8")));
+    output({ count: conflicts.length, conflicts }, opts);
+    return;
+  }
+  if (action === "show") {
+    const id = opts._[0] || files[0];
+    if (!id) fail("No conflict packages found.");
+    output(JSON.parse(fs.readFileSync(resolveConflictFile(id, files), "utf8")), opts);
+    return;
+  }
+  if (action === "resolve") {
+    const id = opts._[0];
+    const mergedFile = opts["merged-file"];
+    if (!id || !mergedFile) fail("Use: tmlbrain conflict resolve <id> --merged-file <path>");
+    const file = resolveConflictFile(id, files);
+    const conflict = JSON.parse(fs.readFileSync(file, "utf8"));
+    fs.copyFileSync(path.resolve(ROOT, mergedFile), path.join(ROOT, conflict.path));
+    conflict.resolvedAt = new Date().toISOString();
+    writeJson(file, conflict);
+    console.log(`Resolved ${conflict.id} into ${conflict.path}`);
+    return;
+  }
+  if (action === "demo") {
+    const conflict = createConflictPackage({
+      reason: "simulated conflict package",
+      patchPath: null,
+      pathName: opts.path || "knowledge/00-inbox/demo.md",
+      base: "Base version\n",
+      local: "Local version\n",
+      remote: "Remote version\n"
+    });
+    console.log(rel(conflict));
+    return;
+  }
+  fail("Conflict action must be list, show, resolve, or demo.");
+}
+
+function cmdBackup(args) {
+  const opts = parseArgs(args);
+  ensureGit();
+  ensureDir(LOG_DIR);
+  const remote = opts.remote || "backup";
+  const dryRun = Boolean(opts["dry-run"]);
+  const source = git(["rev-parse", "HEAD"], { allowFail: true });
+  const remotes = git(["remote"], { allowFail: true });
+  const hasRemote = remotes.ok && remotes.stdout.split(/\r?\n/).includes(remote);
+  const entry = {
+    time: new Date().toISOString(),
+    dryRun,
+    remote,
+    sourceCommit: source.ok ? source.stdout.trim() : null,
+    ok: false
+  };
+  if (!hasRemote) {
+    entry.message = `Remote "${remote}" is not configured.`;
+  } else {
+    const pushArgs = ["push"];
+    if (dryRun) pushArgs.push("--dry-run");
+    pushArgs.push(remote, "HEAD");
+    const push = git(pushArgs, { allowFail: true });
+    entry.ok = push.ok;
+    entry.message = sanitizeGit(push.stderr || push.stdout);
+  }
+  fs.appendFileSync(path.join(LOG_DIR, "backup.log"), JSON.stringify(entry) + "\n", "utf8");
+  output(entry, opts);
+  if (!entry.ok && !dryRun) process.exit(1);
+}
+
+function cmdPublish(args) {
+  const opts = parseArgs(args);
+  const dryRun = Boolean(opts["dry-run"]);
+  const site = opts.site || "site";
+  const result = {
+    dryRun,
+    reader: opts.reader || "quartz",
+    pagefind: Boolean(opts.pagefind),
+    site,
+    source: "server worktree or clean clone",
+    canonicalEditingSurface: false,
+    actions: []
+  };
+  if (opts.pagefind) {
+    if (dryRun) {
+      result.actions.push(`Would run Pagefind against ${site}.`);
+    } else if (!fs.existsSync(path.resolve(ROOT, site))) {
+      result.ok = false;
+      result.actions.push(`Site directory does not exist: ${site}`);
+      output(result, opts);
+      process.exit(1);
+    } else if (!checkCommand("npx", ["--version"]).ok) {
+      result.ok = false;
+      result.actions.push("npx is not available; cannot run Pagefind.");
+      output(result, opts);
+      process.exit(1);
+    } else {
+      const pagefind = spawnSync("npx", ["-y", "pagefind", "--site", site], { cwd: ROOT, encoding: "utf8" });
+      result.ok = pagefind.status === 0;
+      result.actions.push(result.ok ? "Generated Pagefind static search index." : sanitizeGit(pagefind.stderr || pagefind.stdout));
+      if (!result.ok) {
+        output(result, opts);
+        process.exit(1);
+      }
+    }
+  }
+  output(result, opts);
+}
+
+function cmdGraph(args) {
+  const action = args.shift() || "setup";
+  const opts = parseArgs(args);
+  if (action !== "setup") fail("Graph action must be setup.");
+  output(setupGraphRuntime({ dryRun: Boolean(opts["dry-run"]) }), opts);
+}
+
+function setupGraphRuntime({ dryRun = false } = {}) {
+  const uv = checkCommand("uv", ["--version"]);
+  const python = checkCommand("python", ["--version"]);
+  const result = {
+    dryRun,
+    preferred: "uv",
+    uv,
+    python,
+    packages: ["cocoindex", "lightrag-hku"],
+    actions: []
+  };
+  if (dryRun) {
+    result.actions.push("Would create or update an isolated graph runtime for CocoIndex and LightRAG.");
+    return result;
+  }
+  ensureDir(path.join(LOCAL_DIR, "runtime"));
+  if (uv.ok) result.actions.push("uv detected. Use uv to create graph runtime in implementation packaging.");
+  else if (python.ok) result.actions.push("python detected. Use venv/pip fallback for graph runtime in implementation packaging.");
+  else result.actions.push("No Python runtime detected. Core TMLBrain remains usable; graph retrieval is degraded.");
+  return result;
+}
+
+function safeConfigView(state) {
+  return {
+    configFile: rel(STATE_FILE),
+    server: state.server || null,
+    tokenConfigured: Boolean(state.token),
+    workspaceVersion: state.workspaceVersion || null,
+    updatedAt: state.updatedAt || null
+  };
+}
+
+function capabilities() {
+  const state = readState();
+  return {
+    name: "tmlbrain",
+    terminology: {
+      saveKnowledge: "When a user says save, store, record, or archive something into the knowledge base, treat it as a knowledge save request.",
+      internalArchive: "Use knowledge/90-archive and status: archived only when the user explicitly asks to mark inactive historical content."
+    },
+    boundary: {
+      client: [
+        "pull read-only knowledge snapshots from the TMLBrain server",
+        "build local indexes and run local search",
+        "request server-side save/update operations through the TMLBrain server API"
+      ],
+      server: [
+        "mutate Markdown knowledge files",
+        "validate knowledge before commit",
+        "commit repository changes",
+        "push server worktree changes to the server bare repository",
+        "run GitHub backup jobs"
+      ],
+      forbiddenForClients: [
+        "git push to the server repository",
+        "git push to GitHub backup",
+        "direct mutation of remote server files"
+      ]
+    },
+    configuredServer: state.server || null,
+    config: safeConfigView(state),
+    userCommands: [
+      { command: "tmlbrain config show", role: "client", description: "Show the configured server without printing the token." },
+      { command: "tmlbrain config set-server <http-url> --token <token>", role: "client", description: "Switch this client to another TMLBrain server." },
+      { command: "tmlbrain sync --pull", role: "client", description: "Refresh the local read-only knowledge snapshot from the configured server." },
+      { command: "tmlbrain find <query>", role: "client", description: "Search the local knowledge snapshot." },
+      { command: "tmlbrain save --title <title> --content <text>", role: "client-request", description: "Save new knowledge through the server API." },
+      { command: "tmlbrain save <file>", role: "client-request", description: "Save a local file into the knowledge base through the server API." },
+      { command: "tmlbrain remote update --file <path> --replace <old> --with <new>", role: "client-request", description: "Ask the server to update a precise text region." }
+    ],
+    commands: [
+      { command: "tmlbrain sync --pull", role: "client", description: "Fetch a read-only knowledge snapshot from the configured HTTP server." },
+      { command: "tmlbrain search <query>", role: "client", description: "Search local Markdown snapshot." },
+      { command: "tmlbrain find <query>", role: "client", description: "Alias for local search." },
+      { command: "tmlbrain index", role: "client", description: "Build local deterministic index and graph files." },
+      { command: "tmlbrain save --title <title> --content <text>", role: "client-request", description: "User-facing alias that asks the server to save knowledge." },
+      { command: "tmlbrain save <file>", role: "client-request", description: "User-facing alias that asks the server to save a local file." },
+      { command: "tmlbrain remote add --title <title> --content <text>", role: "client-request", description: "Ask the server to create a knowledge document and commit it." },
+      { command: "tmlbrain remote ingest <file>", role: "client-request", description: "Ask the server to ingest a local file as a knowledge document." },
+      { command: "tmlbrain remote update --file <path> --replace <old> --with <new>", role: "client-request", description: "Ask the server to apply a precise text replacement and commit it." },
+      { command: "tmlbrain serve", role: "server", description: "Run the TMLBrain server API from the server worktree." },
+      { command: "tmlbrain backup --remote backup", role: "server", description: "Push the server repository state to GitHub backup." }
+    ]
+  };
+}
+
+async function routeServerRequest(req, res, token) {
+  const requestUrl = new URL(req.url, "http://localhost");
+  if (req.method === "GET" && requestUrl.pathname === "/health") {
+    sendJson(res, 200, {
+      ok: true,
+      root: ROOT,
+      head: currentHead(),
+      documents: markdownFiles(KNOWLEDGE_DIR).filter((file) => !rel(file).includes("/_templates/")).length
+    });
+    return;
+  }
+  if (!isAuthorized(req, token)) {
+    sendJson(res, 401, { ok: false, error: "Unauthorized TMLBrain request." });
+    return;
+  }
+  if (req.method === "GET" && requestUrl.pathname === "/capabilities") {
+    sendJson(res, 200, capabilities());
+    return;
+  }
+  if (req.method === "GET" && requestUrl.pathname === "/snapshot") {
+    sendJson(res, 200, snapshotKnowledge());
+    return;
+  }
+  if (req.method === "POST" && requestUrl.pathname === "/knowledge/add") {
+    const body = await readJsonBody(req);
+    sendJson(res, 200, serverAddKnowledge(body));
+    return;
+  }
+  if (req.method === "POST" && requestUrl.pathname === "/knowledge/update") {
+    const body = await readJsonBody(req);
+    sendJson(res, 200, serverUpdateKnowledge(body));
+    return;
+  }
+  sendJson(res, 404, { ok: false, error: `Unknown TMLBrain endpoint: ${req.method} ${requestUrl.pathname}` });
+}
+
+function serverAddKnowledge(payload) {
+  return serverMutation(payload.message || `Add knowledge: ${payload.title || "untitled"}`, () => {
+    const created = createKnowledgeDocument({
+      title: requiredString(payload.title, "title"),
+      type: payload.type || "resource",
+      folder: payload.folder || folderForType(payload.type || "resource"),
+      slug: payload.slug || payload.title,
+      owner: payload.owner || "TML",
+      content: payload.content || "",
+      force: Boolean(payload.force)
+    });
+    return { action: "add", path: created.path, sha256: created.sha256 };
+  });
+}
+
+function serverUpdateKnowledge(payload) {
+  return serverMutation(payload.message || `Update knowledge: ${payload.path || "unknown"}`, () => {
+    const target = safeKnowledgeFile(payload.path);
+    const before = fs.readFileSync(target, "utf8");
+    if (payload.expectedSha256 && sha256(before) !== payload.expectedSha256) {
+      failRequest(409, `Expected sha256 ${payload.expectedSha256}, found ${sha256(before)}.`);
+    }
+    let after = before;
+    if (payload.content !== undefined && payload.content !== null) {
+      after = String(payload.content);
+    } else if (payload.replace !== undefined && payload.with !== undefined) {
+      const needle = String(payload.replace);
+      if (!needle) failRequest(400, "Replacement text cannot be empty.");
+      const occurrences = countOccurrences(before, needle);
+      if (occurrences === 0) failRequest(404, "Replacement text was not found in the server document.");
+      if (occurrences > 1 && !payload.all) failRequest(409, `Replacement text matched ${occurrences} times. Provide a more specific replacement.`);
+      after = payload.all ? before.split(needle).join(String(payload.with)) : before.replace(needle, String(payload.with));
+    } else {
+      failRequest(400, "Use either `content` or `replace` plus `with` for update.");
+    }
+    if (after === before) failRequest(400, "Update produced no document changes.");
+    fs.writeFileSync(target, after.endsWith("\n") ? after : `${after}\n`, "utf8");
+    return {
+      action: "update",
+      path: rel(target),
+      beforeSha256: sha256(before),
+      afterSha256: sha256(fs.readFileSync(target, "utf8"))
+    };
+  });
+}
+
+function serverMutation(message, mutate) {
+  ensureGit();
+  ensureGitWorktree();
+  ensureServerGitIdentity();
+  const beforeHead = currentHead();
+  const beforeStatus = git(["status", "--porcelain"], { allowFail: true });
+  if (beforeStatus.ok && beforeStatus.stdout.trim()) {
+    failRequest(409, "Server worktree has uncommitted changes; refusing to mutate knowledge.");
+  }
+  const result = mutate();
+  const validation = validateKnowledge();
+  if (validation.errors.length > 0) {
+    revertServerWorktree();
+    failRequest(400, `Knowledge validation failed: ${validation.errors.join("; ")}`);
+  }
+  git(["add", "knowledge"], { allowFail: true });
+  const staged = git(["diff", "--cached", "--quiet"], { allowFail: true });
+  if (staged.ok) {
+    return { ok: true, changed: false, beforeHead, head: beforeHead, validation, result };
+  }
+  const diff = git(["diff", "--cached", "--", "knowledge"], { allowFail: true });
+  const commit = git(["commit", "-m", message], { allowFail: true });
+  if (!commit.ok) {
+    revertServerWorktree();
+    failRequest(500, sanitizeGit(commit.stderr || commit.stdout));
+  }
+  const pushResult = pushServerRepository();
+  const head = currentHead();
+  snapshotBase();
+  return {
+    ok: true,
+    changed: true,
+    beforeHead,
+    head,
+    pushed: pushResult.ok,
+    pushMessage: pushResult.message,
+    validation,
+    result,
+    diff: diff.stdout || ""
+  };
+}
+
+function pushServerRepository() {
+  const remotes = git(["remote"], { allowFail: true });
+  if (!remotes.ok || !remotes.stdout.split(/\r?\n/).includes("origin")) {
+    return { ok: false, message: "No origin remote configured on server worktree." };
+  }
+  const push = git(["push", "origin", "HEAD:main"], { allowFail: true });
+  return { ok: push.ok, message: sanitizeGit(push.stderr || push.stdout) };
+}
+
+function revertServerWorktree() {
+  git(["reset", "--hard"], { allowFail: true });
+  git(["clean", "-fd", "knowledge"], { allowFail: true });
+}
+
+function ensureServerGitIdentity() {
+  const name = git(["config", "user.name"], { allowFail: true });
+  const email = git(["config", "user.email"], { allowFail: true });
+  if (!name.ok || !name.stdout.trim()) git(["config", "user.name", "TMLBrain Server"], { allowFail: true });
+  if (!email.ok || !email.stdout.trim()) git(["config", "user.email", "tmlbrain@localhost"], { allowFail: true });
+}
+
+function ensureGitWorktree() {
+  const inside = git(["rev-parse", "--is-inside-work-tree"], { allowFail: true });
+  if (!inside.ok || inside.stdout.trim() !== "true") {
+    failRequest(500, "TMLBrain server writes require a Git worktree. Run `tmlbrain serve` from the server worktree.");
+  }
+}
+
+function snapshotKnowledge() {
+  const files = markdownFiles(KNOWLEDGE_DIR).map((file) => {
+    const content = fs.readFileSync(file, "utf8");
+    return { path: rel(file), sha256: sha256(content), content };
+  });
+  return { ok: true, head: currentHead(), generatedAt: new Date().toISOString(), files };
+}
+
+function applySnapshot(snapshot) {
+  if (!snapshot || !Array.isArray(snapshot.files)) fail("Invalid TMLBrain snapshot response.");
+  ensureDir(KNOWLEDGE_DIR);
+  const allowed = new Set();
+  for (const file of snapshot.files) {
+    const target = safeKnowledgeFile(file.path);
+    allowed.add(rel(target));
+    ensureDir(path.dirname(target));
+    fs.writeFileSync(target, file.content || "", "utf8");
+  }
+  for (const file of markdownFiles(KNOWLEDGE_DIR)) {
+    const fileRel = rel(file);
+    if (!allowed.has(fileRel) && !fileRel.includes("/_templates/")) fs.unlinkSync(file);
+  }
+  const state = readState();
+  state.lastSyncedRevision = snapshot.head || null;
+  state.lastSyncedAt = new Date().toISOString();
+  state.files = {};
+  for (const file of snapshot.files) state.files[file.path] = { sha256: file.sha256 };
+  writeJson(STATE_FILE, state);
+  const index = buildIndex();
+  writeJson(path.join(INDEX_DIR, "documents.json"), index.documents);
+  writeJson(path.join(INDEX_DIR, "chunks.json"), index.chunks);
+  writeJson(path.join(INDEX_DIR, "graph.json"), index.graph);
+}
+
+function createKnowledgeDocument({ title, type, folder, slug, owner, content, force }) {
+  if (!title) failRequest(400, "Document title is required.");
+  if (!VALID_TYPES.has(type)) failRequest(400, `Invalid type "${type}". Allowed: ${Array.from(VALID_TYPES).join(", ")}`);
+  const safeFolder = safeKnowledgeFolder(folder || folderForType(type));
+  const fileName = `${slugify(slug || title)}.md`;
+  const target = path.join(safeFolder, fileName);
+  if (fs.existsSync(target) && !force) failRequest(409, `Document already exists: ${rel(target)}`);
+  ensureDir(path.dirname(target));
+  const doc = [
+    "---",
+    `title: ${title}`,
+    `type: ${type}`,
+    "status: draft",
+    `owner: ${owner || "TML"}`,
+    "tags: []",
+    `updated: ${today()}`,
+    "---",
+    "",
+    `# ${title}`,
+    "",
+    content || ""
+  ].join("\n").replace(/\n+$/, "\n");
+  fs.writeFileSync(target, doc, "utf8");
+  return { path: rel(target), sha256: sha256(doc) };
+}
+
+function safeKnowledgeFolder(folder) {
+  const normalized = normalizeKnowledgePath(folder || "knowledge/00-inbox");
+  const target = path.resolve(ROOT, normalized);
+  if (!target.startsWith(KNOWLEDGE_DIR)) failRequest(400, "Knowledge folder must be under knowledge/.");
+  return target;
+}
+
+function safeKnowledgeFile(filePath) {
+  const normalized = normalizeKnowledgePath(filePath);
+  if (!normalized.endsWith(".md")) failRequest(400, "Knowledge file must be a Markdown file.");
+  const target = path.resolve(ROOT, normalized);
+  if (!target.startsWith(KNOWLEDGE_DIR)) failRequest(400, "Knowledge file must be under knowledge/.");
+  return target;
+}
+
+function normalizeKnowledgePath(value) {
+  const normalized = String(value || "").replace(/\\/g, "/").replace(/^\/+/, "");
+  if (!normalized || normalized.includes("..") || path.isAbsolute(normalized)) failRequest(400, `Invalid knowledge path: ${value}`);
+  if (!normalized.startsWith("knowledge/")) failRequest(400, "Knowledge paths must start with knowledge/.");
+  return path.posix.normalize(normalized);
+}
+
+function shouldUseServerWrite(opts) {
+  if (opts.remote) return true;
+  const state = readState();
+  return Boolean(state.server && isHttpUrl(state.server));
+}
+
+function readContentOption(opts) {
+  const file = opts["content-file"];
+  if (!file) return undefined;
+  const filePath = path.resolve(ROOT, file);
+  if (!fs.existsSync(filePath)) fail(`Content file not found: ${file}`);
+  return fs.readFileSync(filePath, "utf8");
+}
+
+async function requestServerGetJson(endpoint, opts) {
+  return requestServer("GET", endpoint, null, opts);
+}
+
+async function requestServerJson(endpoint, body, opts) {
+  return requestServer("POST", endpoint, body, opts);
+}
+
+async function requestServer(method, endpoint, body, opts) {
+  const state = readState();
+  const base = opts.server || state.server;
+  if (!base || !isHttpUrl(base)) fail("Configure an HTTP TMLBrain server first: tmlbrain install --server http://host:7389");
+  const token = opts.token || state.token || process.env.TMLBRAIN_TOKEN || null;
+  const url = new URL(endpoint, base.endsWith("/") ? base : `${base}/`);
+  const transport = url.protocol === "https:" ? https : http;
+  const payload = body ? Buffer.from(JSON.stringify(body), "utf8") : null;
+  const headers = { Accept: "application/json" };
+  if (payload) {
+    headers["Content-Type"] = "application/json";
+    headers["Content-Length"] = String(payload.length);
+  }
+  if (token) headers.Authorization = `Bearer ${token}`;
+  return new Promise((resolve, reject) => {
+    const req = transport.request(url, { method, headers }, (res) => {
+      const chunks = [];
+      res.on("data", (chunk) => chunks.push(chunk));
+      res.on("end", () => {
+        const text = Buffer.concat(chunks).toString("utf8");
+        let data;
+        try {
+          data = text ? JSON.parse(text) : {};
+        } catch (error) {
+          reject(new Error(`Invalid JSON from TMLBrain server: ${text}`));
+          return;
+        }
+        if (res.statusCode >= 400) {
+          reject(new Error(data.error || `TMLBrain server returned HTTP ${res.statusCode}`));
+          return;
+        }
+        resolve(data);
+      });
+    });
+    req.on("error", reject);
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
+function isHttpUrl(value) {
+  return /^https?:\/\//i.test(String(value || ""));
+}
+
+function isAuthorized(req, token) {
+  if (!token) return true;
+  const authorization = req.headers.authorization || "";
+  const headerToken = req.headers["x-tmlbrain-token"] || "";
+  return authorization === `Bearer ${token}` || headerToken === token;
+}
+
+function readJsonBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    req.on("data", (chunk) => {
+      size += chunk.length;
+      if (size > 5 * 1024 * 1024) {
+        reject(new Error("Request body is too large."));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => {
+      const text = Buffer.concat(chunks).toString("utf8");
+      try {
+        resolve(text ? JSON.parse(text) : {});
+      } catch (error) {
+        reject(new Error("Request body must be valid JSON."));
+      }
+    });
+    req.on("error", reject);
+  });
+}
+
+function sendJson(res, statusCode, value) {
+  const text = JSON.stringify(value, null, 2) + "\n";
+  res.writeHead(statusCode, {
+    "Content-Type": "application/json; charset=utf-8",
+    "Content-Length": Buffer.byteLength(text)
+  });
+  res.end(text);
+}
+
+function requiredString(value, name) {
+  if (!value || !String(value).trim()) failRequest(400, `${name} is required.`);
+  return String(value);
+}
+
+function countOccurrences(text, needle) {
+  return text.split(needle).length - 1;
+}
+
+function currentHead() {
+  const head = git(["rev-parse", "HEAD"], { allowFail: true });
+  return head.ok ? head.stdout.trim() : null;
+}
+
+function failRequest(statusCode, message) {
+  const error = new Error(message);
+  error.statusCode = statusCode;
+  throw error;
+}
+
+function validateKnowledge() {
+  const errors = [];
+  const warnings = [];
+  const files = markdownFiles(KNOWLEDGE_DIR).filter((file) => !rel(file).includes("/_templates/"));
+  const docs = files.map((file) => {
+    const text = fs.readFileSync(file, "utf8");
+    const parsed = parseFrontMatter(text);
+    return { file, rel: rel(file), parsed };
+  });
+  const knownFiles = new Set(docs.map((doc) => doc.rel.replace(/\\/g, "/")));
+  for (const doc of docs) {
+    if (doc.rel.includes("/00-inbox/")) {
+      if (!doc.parsed.data.title) warnings.push(`${doc.rel}: pending classification in 00-inbox`);
+      continue;
+    }
+    for (const field of ["title", "type", "status", "owner", "tags", "updated"]) {
+      if (doc.parsed.data[field] === undefined || doc.parsed.data[field] === "") {
+        errors.push(`${doc.rel}: missing required metadata field "${field}"`);
+      }
+    }
+    if (doc.parsed.data.type && !VALID_TYPES.has(String(doc.parsed.data.type))) errors.push(`${doc.rel}: invalid type "${doc.parsed.data.type}"`);
+    if (doc.parsed.data.status && !VALID_STATUSES.has(String(doc.parsed.data.status))) errors.push(`${doc.rel}: invalid status "${doc.parsed.data.status}"`);
+    if (doc.rel.includes("/90-archive/") && doc.parsed.data.status !== "archived") errors.push(`${doc.rel}: archived documents must use status: archived`);
+    if (doc.parsed.data.status === "stale") warnings.push(`${doc.rel}: stale but retained and searchable`);
+    for (const link of extractMarkdownLinks(doc.parsed.body)) {
+      if (link.startsWith("http") || link.startsWith("#") || link.startsWith("mailto:")) continue;
+      const linkPath = path.posix.normalize(path.posix.join(path.posix.dirname(doc.rel.replace(/\\/g, "/")), link.split("#")[0]));
+      if (linkPath.endsWith(".md") && !knownFiles.has(linkPath)) warnings.push(`${doc.rel}: unresolved internal link ${link}`);
+    }
+  }
+  return { ok: errors.length === 0, errors, warnings, checked: docs.length };
+}
+
+function buildIndex() {
+  const documents = [];
+  const chunks = [];
+  const edges = [];
+  for (const file of markdownFiles(KNOWLEDGE_DIR).filter((f) => !rel(f).includes("/_templates/"))) {
+    const text = fs.readFileSync(file, "utf8");
+    const parsed = parseFrontMatter(text);
+    const fileRel = rel(file).replace(/\\/g, "/");
+    const headings = extractHeadings(parsed.body);
+    const stat = fs.statSync(file);
+    const doc = {
+      path: fileRel,
+      title: parsed.data.title || headings[0]?.text || path.basename(file, ".md"),
+      type: parsed.data.type || null,
+      status: parsed.data.status || null,
+      owner: parsed.data.owner || null,
+      tags: Array.isArray(parsed.data.tags) ? parsed.data.tags : [],
+      updated: parsed.data.updated || null,
+      sha256: sha256(text),
+      mtimeMs: stat.mtimeMs,
+      headings
+    };
+    documents.push(doc);
+    for (const chunk of chunkByHeading(fileRel, parsed.body)) chunks.push(chunk);
+    for (const link of extractMarkdownLinks(parsed.body)) edges.push({ from: fileRel, to: link, type: "markdown-link" });
+    for (const link of extractWikiLinks(parsed.body)) edges.push({ from: fileRel, to: link, type: "wiki-link" });
+    for (const tag of doc.tags) edges.push({ from: fileRel, to: String(tag), type: "has-tag" });
+    if (doc.owner) edges.push({ from: fileRel, to: String(doc.owner), type: "owned-by" });
+    if (doc.status) edges.push({ from: fileRel, to: String(doc.status), type: "has-status" });
+  }
+  return { documents, chunks, graph: { nodes: graphNodes(documents, edges), edges } };
+}
+
+function exactSearch(query) {
+  const rg = checkCommand("rg", ["--version"]);
+  if (rg.ok) {
+    const result = spawnSync("rg", ["-n", "--glob", "*.md", query, "knowledge"], { cwd: ROOT, encoding: "utf8" });
+    if (result.status === 0) return result.stdout.trim().split(/\r?\n/).filter(Boolean).map(parseRgLine);
+    if (result.status !== 1) fail(sanitizeGit(result.stderr || result.stdout));
+    return [];
+  }
+  const matches = [];
+  for (const file of markdownFiles(KNOWLEDGE_DIR)) {
+    const lines = fs.readFileSync(file, "utf8").split(/\r?\n/);
+    lines.forEach((line, index) => {
+      if (line.toLowerCase().includes(query.toLowerCase())) matches.push({ path: rel(file), line: index + 1, text: line });
+    });
+  }
+  return matches;
+}
+
+function createLocalPatch() {
+  ensureDir(PATCH_DIR);
+  const target = path.join(PATCH_DIR, `local-${timestamp()}.patch`);
+  const diff = git(["diff", "--", "knowledge", "docs", "skills", "scripts", "bin", "package.json"], { allowFail: true });
+  fs.writeFileSync(target, diff.stdout || "", "utf8");
+  return target;
+}
+
+function createConflictPackage({ reason, patchPath, pathName, base, local, remote }) {
+  ensureDir(CONFLICT_DIR);
+  const id = `conflict-${timestamp()}`;
+  const data = {
+    id,
+    createdAt: new Date().toISOString(),
+    reason,
+    path: pathName,
+    patchPath: patchPath ? rel(path.resolve(ROOT, patchPath)) : null,
+    base,
+    local,
+    remote,
+    nextActions: [
+      "Ask TMLBrain Skill to explain the conflict.",
+      "Confirm a merged Markdown result.",
+      "Run tmlbrain conflict resolve <id> --merged-file <path>."
+    ]
+  };
+  const file = path.join(CONFLICT_DIR, `${id}.json`);
+  writeJson(file, data);
+  return file;
+}
+
+function snapshotBase() {
+  if (!fs.existsSync(KNOWLEDGE_DIR)) return;
+  ensureDir(BASE_DIR);
+  for (const file of markdownFiles(KNOWLEDGE_DIR)) {
+    const target = path.join(BASE_DIR, rel(file));
+    ensureDir(path.dirname(target));
+    fs.copyFileSync(file, target);
+  }
+  const state = readState();
+  const head = git(["rev-parse", "HEAD"], { allowFail: true });
+  state.lastSyncedRevision = head.ok ? head.stdout.trim() : null;
+  state.lastSyncedAt = new Date().toISOString();
+  state.files = {};
+  for (const file of markdownFiles(KNOWLEDGE_DIR)) state.files[rel(file)] = { sha256: sha256(fs.readFileSync(file, "utf8")) };
+  writeJson(STATE_FILE, state);
+}
+
+function hasRemoteChanges() {
+  const upstream = git(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"], { allowFail: true });
+  if (!upstream.ok) return false;
+  const count = git(["rev-list", "--count", `HEAD..${upstream.stdout.trim()}`], { allowFail: true });
+  return count.ok && Number(count.stdout.trim()) > 0;
+}
+
+function ensureGit({ install = false, dryRun = false } = {}) {
+  const gitInfo = checkCommand("git", ["--version"]);
+  if (gitInfo.ok) return gitInfo;
+  if (!install) fail(gitInstallMessage());
+  if (dryRun) {
+    console.log(gitInstallMessage());
+    return { ok: false };
+  }
+  const installResult = installGit();
+  if (!installResult.ok) fail(installResult.message);
+  return checkCommand("git", ["--version"]);
+}
+
+function installGit() {
+  if (process.platform === "win32" && checkCommand("winget", ["--version"]).ok) {
+    const result = spawnSync("winget", ["install", "--id", "Git.Git", "-e", "--source", "winget"], { stdio: "inherit" });
+    return { ok: result.status === 0, message: "winget Git installation failed." };
+  }
+  if (process.platform === "darwin") {
+    if (checkCommand("brew", ["--version"]).ok) {
+      const result = spawnSync("brew", ["install", "git"], { stdio: "inherit" });
+      return { ok: result.status === 0, message: "Homebrew Git installation failed." };
+    }
+    return { ok: false, message: "Install Xcode Command Line Tools with: xcode-select --install" };
+  }
+  if (process.platform === "linux") {
+    return { ok: false, message: "Install Git with your distribution package manager, then rerun tmlbrain install." };
+  }
+  return { ok: false, message: gitInstallMessage() };
+}
+
+function gitInstallMessage() {
+  return "Git is required for TMLBrain server, backup, and legacy Git migration flows. HTTP-only clients can use TMLBrain without Git.";
+}
+
+function installSkillToCodex({ dryRun = false } = {}) {
+  const packagedSource = path.join(PACKAGE_ROOT, "skills", "tmlbrain");
+  const workspaceSource = path.join(ROOT, "skills", "tmlbrain");
+  const source = fs.existsSync(packagedSource) ? packagedSource : workspaceSource;
+  const target = path.join(ROOT, ".codex", "skills", "tmlbrain");
+  if (!fs.existsSync(source) || dryRun) return;
+  copyDir(source, target);
+}
+
+function detectGraphRuntime() {
+  return {
+    available: fs.existsSync(path.join(LOCAL_DIR, "runtime")),
+    uv: checkCommand("uv", ["--version"]).ok,
+    python: checkCommand("python", ["--version"]).ok
+  };
+}
+
+function folderForType(type) {
+  return {
+    project: "knowledge/10-projects",
+    area: "knowledge/20-areas",
+    resource: "knowledge/30-resources",
+    reference: "knowledge/40-references",
+    meeting: "knowledge/00-inbox",
+    decision: "knowledge/10-projects"
+  }[type] || "knowledge/00-inbox";
+}
+
+function looksLikeFilePath(value) {
+  return /[\\/]/.test(value) || /\.[A-Za-z0-9]{1,8}$/.test(value);
+}
+
+function parseArgs(args) {
+  const opts = { _: [] };
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (!arg.startsWith("--")) {
+      opts._.push(arg);
+      continue;
+    }
+    const key = arg.slice(2);
+    const next = args[i + 1];
+    if (next && !next.startsWith("--")) {
+      opts[key] = next;
+      i += 1;
+    } else {
+      opts[key] = true;
+    }
+  }
+  return opts;
+}
+
+function promptText(label, defaultValue = "") {
+  const suffix = defaultValue ? ` [${defaultValue}]` : "";
+  return promptLine(`${label}${suffix}: `).then((answer) => {
+    const value = answer.trim();
+    return value || defaultValue || "";
+  });
+}
+
+function promptSecret(label, defaultValue = "") {
+  const suffix = defaultValue ? " [configured, press Enter to keep]" : "";
+  return promptLine(`${label}${suffix}: `).then((answer) => {
+    const value = answer.trim();
+    return value || defaultValue || "";
+  });
+}
+
+function promptYesNo(label, defaultValue = false) {
+  const suffix = defaultValue ? " [Y/n]" : " [y/N]";
+  return promptLine(`${label}${suffix}: `).then((answer) => {
+    const value = answer.trim().toLowerCase();
+    if (!value) return Boolean(defaultValue);
+    return ["y", "yes", "true", "1"].includes(value);
+  });
+}
+
+function promptLine(prompt) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(prompt, (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+  });
+}
+
+function output(value, opts) {
+  if (opts.json) {
+    console.log(JSON.stringify(value, null, 2));
+  } else if (Array.isArray(value.matches)) {
+    for (const match of value.matches) console.log(`${match.path}:${match.line}: ${match.text}`);
+    if (value.matches.length === 0) console.log("No matches.");
+  } else {
+    console.log(JSON.stringify(value, null, 2));
+  }
+}
+
+function parseFrontMatter(text) {
+  if (!text.startsWith("---\n") && !text.startsWith("---\r\n")) return { data: {}, body: text };
+  const lines = text.split(/\r?\n/);
+  const end = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+  if (end < 0) return { data: {}, body: text };
+  return { data: parseSimpleYaml(lines.slice(1, end)), body: lines.slice(end + 1).join("\n") };
+}
+
+function parseSimpleYaml(lines) {
+  const data = {};
+  let current = null;
+  for (const line of lines) {
+    const list = line.match(/^\s*-\s+(.*)$/);
+    if (list && current) {
+      if (!Array.isArray(data[current])) data[current] = [];
+      data[current].push(unquote(list[1].trim()));
+      continue;
+    }
+    const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!match) continue;
+    current = match[1];
+    const raw = match[2].trim();
+    data[current] = raw === "[]" ? [] : unquote(raw);
+  }
+  return data;
+}
+
+function unquote(value) {
+  return value.replace(/^["']|["']$/g, "");
+}
+
+function markdownFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return walk(dir).filter((file) => file.endsWith(".md"));
+}
+
+function walk(dir) {
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if ([".git", ".tmlbrain", "node_modules"].includes(entry.name)) continue;
+      out.push(...walk(full));
+    } else {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+function extractHeadings(markdown) {
+  return markdown.split(/\r?\n/).map((line, index) => ({ line, index: index + 1 }))
+    .filter((item) => /^#{1,6}\s+/.test(item.line))
+    .map((item) => {
+      const match = item.line.match(/^(#{1,6})\s+(.*)$/);
+      return { level: match[1].length, text: match[2].trim(), line: item.index, anchor: slugify(match[2].trim()) };
+    });
+}
+
+function chunkByHeading(fileRel, markdown) {
+  const lines = markdown.split(/\r?\n/);
+  const chunks = [];
+  let current = { heading: null, startLine: 1, lines: [] };
+  lines.forEach((line, index) => {
+    const heading = line.match(/^(#{1,6})\s+(.*)$/);
+    if (heading && current.lines.length > 0) {
+      chunks.push(makeChunk(fileRel, current));
+      current = { heading: heading[2].trim(), startLine: index + 1, lines: [line] };
+    } else {
+      if (heading && !current.heading) current.heading = heading[2].trim();
+      current.lines.push(line);
+    }
+  });
+  if (current.lines.length > 0) chunks.push(makeChunk(fileRel, current));
+  return chunks;
+}
+
+function makeChunk(fileRel, chunk) {
+  const text = chunk.lines.join("\n").trim();
+  return { id: sha256(`${fileRel}:${chunk.startLine}:${text}`).slice(0, 16), path: fileRel, heading: chunk.heading, startLine: chunk.startLine, endLine: chunk.startLine + chunk.lines.length - 1, sha256: sha256(text), text };
+}
+
+function extractMarkdownLinks(markdown) {
+  const links = [];
+  const re = /\[[^\]]+\]\(([^)]+)\)/g;
+  let match;
+  while ((match = re.exec(markdown))) links.push(match[1]);
+  return links;
+}
+
+function extractWikiLinks(markdown) {
+  const links = [];
+  const re = /\[\[([^\]]+)\]\]/g;
+  let match;
+  while ((match = re.exec(markdown))) links.push(match[1]);
+  return links;
+}
+
+function graphNodes(documents, edges) {
+  const nodes = new Map();
+  for (const doc of documents) nodes.set(doc.path, { id: doc.path, type: "document", title: doc.title });
+  for (const edge of edges) if (!nodes.has(edge.to)) nodes.set(edge.to, { id: edge.to, type: edge.type.includes("link") ? "target" : "metadata" });
+  return Array.from(nodes.values());
+}
+
+function parseRgLine(line) {
+  const match = line.match(/^(.+?):(\d+):(.*)$/);
+  if (!match) return { path: "", line: 0, text: line };
+  return { path: match[1], line: Number(match[2]), text: match[3] };
+}
+
+function readState() {
+  return fs.existsSync(STATE_FILE) ? JSON.parse(fs.readFileSync(STATE_FILE, "utf8")) : {};
+}
+
+function ensureLocalDirs() {
+  [LOCAL_DIR, INDEX_DIR, BASE_DIR, CONFLICT_DIR, PATCH_DIR, LOG_DIR].forEach(ensureDir);
+}
+
+function writeJson(file, data) {
+  ensureDir(path.dirname(file));
+  fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n", "utf8");
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function copyDir(source, target) {
+  ensureDir(target);
+  for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+    const sourcePath = path.join(source, entry.name);
+    const targetPath = path.join(target, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(sourcePath, targetPath);
+    } else if (entry.isFile()) {
+      fs.copyFileSync(sourcePath, targetPath);
+    }
+  }
+}
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function slugify(value) {
+  return String(value).trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "untitled";
+}
+
+function today() {
+  const now = new Date();
+  const year = now.getFullYear();
+  const month = String(now.getMonth() + 1).padStart(2, "0");
+  const day = String(now.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+function timestamp() {
+  return new Date().toISOString().replace(/[-:T.Z]/g, "").slice(0, 14);
+}
+
+function checkCommand(command, args = []) {
+  if (process.env.TMLBRAIN_SIMULATE_MISSING_GIT === "1" && command === "git") {
+    return { ok: false, version: null };
+  }
+  const result = spawnSync(command, args, { encoding: "utf8" });
+  return { ok: result.status === 0, version: result.stdout ? result.stdout.split(/\r?\n/)[0] : null };
+}
+
+function git(args, opts = {}) {
+  const result = spawnSync("git", args, { cwd: ROOT, encoding: "utf8" });
+  const out = { ok: result.status === 0, stdout: result.stdout || "", stderr: result.stderr || "" };
+  if (!out.ok && !opts.allowFail) fail(sanitizeGit(out.stderr || out.stdout));
+  return out;
+}
+
+function sanitizeGit(value) {
+  return String(value || "").trim().replace(/\r/g, "");
+}
+
+function rel(file) {
+  return path.relative(ROOT, file).replace(/\\/g, "/");
+}
+
+function findRoot(start) {
+  let dir = start;
+  while (dir && dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, "knowledge")) || fs.existsSync(path.join(dir, ".git"))) return dir;
+    dir = path.dirname(dir);
+  }
+  return start;
+}
+
+function resolveConflictFile(id, files) {
+  const name = id.endsWith(".json") ? id : `${id}.json`;
+  const file = path.join(CONFLICT_DIR, name);
+  if (fs.existsSync(file)) return file;
+  const found = files.find((candidate) => candidate.startsWith(id));
+  if (found) return path.join(CONFLICT_DIR, found);
+  fail(`Conflict package not found: ${id}`);
+}
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}