@time-machine-lab/tmlbrain 0.1.0 → 0.1.2

package/bin/tmlbrain.js

@@ -19,11 +19,12 @@ 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 PACKAGE_INFO = readPackageInfo();
 
 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;
+const DEFAULT_SERVER_PORT = 8477;
 
 main().catch((error) => fail(error.message || String(error)));
 
@@ -38,10 +39,18 @@ async function main() {
       case "--help":
         printHelp();
         break;
+      case "version":
+      case "-v":
+      case "--version":
+        console.log(PACKAGE_INFO.version);
+        break;
       case "install":
       case "init":
         cmdInstall(args);
         break;
+      case "update":
+        await cmdUpdate(args);
+        break;
       case "client":
         await cmdClient(args);
         break;
@@ -109,6 +118,8 @@ function printHelp() {
 
 Usage:
   tmlbrain client install [--server <http-url>] [--token <token>] [--local] [--yes]
+  tmlbrain update [latest|<version>] [--sync] [--dry-run]
+  tmlbrain version|--version
   tmlbrain install [--server <http-url>] [--token <token>] [--graph] [--with-git]
   tmlbrain config show|set-server|clear-token
   tmlbrain doctor
@@ -121,6 +132,7 @@ Usage:
   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 remote delete --file <path>
   tmlbrain sync [--dry-run] [--pull]
   tmlbrain serve [--host <host>] [--port <port>] [--token <token>]
   tmlbrain patch create|check|apply [file]
@@ -128,6 +140,8 @@ Usage:
   tmlbrain backup [--dry-run] [--remote <remote>]
   tmlbrain publish [--dry-run] [--site <dir>] [--pagefind]
   tmlbrain graph setup [--dry-run]
+  tmlbrain graph index [--json]
+  tmlbrain graph query <query> [--limit <n>] [--json]
 
 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
@@ -143,6 +157,7 @@ async function cmdClient(args) {
 
 Usage:
   tmlbrain client install [--server <http-url>] [--token <token>] [--local] [--yes]
+  tmlbrain client update [latest|<version>] [--sync] [--dry-run]
   tmlbrain client doctor
 
 If --server is omitted, interactive install asks for one. Press Enter to start
@@ -153,6 +168,10 @@ in local-only mode.`);
     await cmdClientInstall(args);
     return;
   }
+  if (action === "update") {
+    await cmdUpdate(args);
+    return;
+  }
   if (action === "doctor") {
     cmdDoctor(args);
     return;
@@ -164,9 +183,10 @@ async function cmdClientInstall(args) {
   const opts = parseArgs(args);
   const interactive = !opts.yes && !opts["non-interactive"];
   ensureLocalDirs();
+  const existingState = readState();
 
-  let server = opts.local ? "" : (opts.server || "");
-  let token = opts.token || "";
+  let server = opts.local ? "" : (opts.server || existingState.server || "");
+  let token = opts.local ? "" : (opts.token || existingState.token || "");
   let graph = Boolean(opts.graph);
 
   if (interactive) {
@@ -180,6 +200,7 @@ async function cmdClientInstall(args) {
   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 (opts.local) installArgs.push("--local");
   if (server) installArgs.push("--server", server);
   if (token) installArgs.push("--token", token);
   if (graph) installArgs.push("--graph");
@@ -207,9 +228,17 @@ function cmdInstall(args) {
     ? ensureGit({ install: true, dryRun: Boolean(opts["dry-run"]) })
     : checkCommand("git", ["--version"]);
   const state = readState();
+  if (opts.local) {
+    delete state.server;
+    delete state.token;
+  }
   if (opts.server) state.server = opts.server;
   if (opts.token) state.token = opts.token;
   if (!state.workspaceVersion) state.workspaceVersion = 1;
+  state.package = {
+    name: PACKAGE_INFO.name,
+    version: PACKAGE_INFO.version
+  };
   state.git = { detected: gitInfo.ok, version: gitInfo.version || null };
   state.updatedAt = new Date().toISOString();
   writeJson(STATE_FILE, state);
@@ -218,6 +247,59 @@ function cmdInstall(args) {
   console.log("TMLBrain workspace is ready.");
 }
 
+async function cmdUpdate(args) {
+  const opts = parseArgs(args);
+  ensureLocalDirs();
+  const state = readState();
+  const target = opts.version || opts.tag || opts._[0] || "latest";
+  const packageSpec = `${PACKAGE_INFO.name}@${target}`;
+  const dryRun = Boolean(opts["dry-run"]);
+  const skipNpm = Boolean(opts["skip-npm"]);
+  const server = opts.local ? "" : (opts.server || state.server || "");
+  const token = opts.local ? "" : (opts.token || state.token || "");
+  const installArgs = ["install"];
+
+  if (opts.local) installArgs.push("--local");
+  if (opts.server) installArgs.push("--server", opts.server);
+  if (opts.token) installArgs.push("--token", opts.token);
+  if (opts.graph) installArgs.push("--graph");
+  if (dryRun) installArgs.push("--dry-run");
+
+  if (dryRun) {
+    console.log(`Would update npm package: npm install -g ${packageSpec}`);
+    console.log(`Would refresh local runtime: tmlbrain ${redactArgs(installArgs).join(" ")}`);
+    if (server && !opts.server) console.log("Would preserve the existing configured server.");
+    if (token && !opts.token) console.log("Would preserve the existing configured token.");
+    return;
+  }
+
+  if (!skipNpm) {
+    if (!checkCommand("npm", ["--version"]).ok) {
+      fail("npm is required for `tmlbrain update`. Install Node.js/npm first, or use `npx -y @time-machine-lab/tmlbrain@latest client install`.");
+    }
+    console.log(`Updating ${packageSpec} with npm...`);
+    const npmResult = runCommand("npm", ["install", "-g", packageSpec], { stdio: "inherit" });
+    if (npmResult.status !== 0) fail(`npm update failed for ${packageSpec}.`);
+  }
+
+  console.log("Refreshing TMLBrain workspace runtime and skill from the installed package...");
+  const cliPath = path.join(PACKAGE_ROOT, "bin", "tmlbrain.js");
+  const refreshResult = fs.existsSync(cliPath)
+    ? spawnSync(process.execPath, [cliPath, ...installArgs], { cwd: ROOT, stdio: "inherit" })
+    : runCommand("tmlbrain", installArgs, { cwd: ROOT, stdio: "inherit" });
+
+  if (refreshResult.status !== 0) {
+    console.warn("Updated package, but automatic runtime refresh failed. Falling back to current CLI runtime.");
+    cmdInstall(installArgs.slice(1));
+  }
+
+  if (opts.sync && server) {
+    await cmdSync(["--pull", ...(opts.json ? ["--json"] : [])]);
+  }
+
+  console.log("TMLBrain update is complete.");
+}
+
 function cmdDoctor(args) {
   const opts = parseArgs(args);
   const state = readState();
@@ -350,10 +432,11 @@ async function cmdSave(args) {
       content = fs.readFileSync(sourcePath, "utf8");
     }
     if (!title) fail("Use: tmlbrain save --title <title> --content <text>, or tmlbrain save <file>");
+    const placement = classifyKnowledgePlacement({ title, content, type: opts.type, folder: opts.folder });
     const created = createKnowledgeDocument({
       title,
-      type: opts.type || "resource",
-      folder: opts.folder || "knowledge/00-inbox",
+      type: placement.type,
+      folder: placement.folder,
       slug: opts.slug || title,
       owner: opts.owner || "TML",
       content,
@@ -364,13 +447,15 @@ async function cmdSave(args) {
   }
   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 content = fs.readFileSync(sourcePath, "utf8");
+    const placement = classifyKnowledgePlacement({ title, content, type: opts.type, folder: opts.folder });
     const response = await requestServerJson("/knowledge/add", {
       title,
-      type: opts.type || "resource",
-      folder: opts.folder || "knowledge/00-inbox",
+      type: placement.type,
+      folder: placement.folder,
       slug: opts.slug || null,
       owner: opts.owner || "TML",
-      content: fs.readFileSync(sourcePath, "utf8"),
+      content,
       message: opts.message || `Save knowledge: ${title}`
     }, opts);
     output(response, opts);
@@ -381,13 +466,15 @@ async function cmdSave(args) {
   }
   const title = opts.title || opts._.join(" ").trim();
   if (!title) fail("Use: tmlbrain save --title <title> --content <text>, or tmlbrain save <file>");
+  const content = opts.content || readContentOption(opts) || "";
+  const placement = classifyKnowledgePlacement({ title, content, type: opts.type, folder: opts.folder });
   const response = await requestServerJson("/knowledge/add", {
     title,
-    type: opts.type || "resource",
-    folder: opts.folder || "knowledge/00-inbox",
+    type: placement.type,
+    folder: placement.folder,
     slug: opts.slug || null,
     owner: opts.owner || "TML",
-    content: opts.content || readContentOption(opts) || "",
+    content,
     message: opts.message || `Save knowledge: ${title}`
   }, opts);
   output(response, opts);
@@ -403,7 +490,8 @@ 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>)`);
+  tmlbrain remote update --file <path> (--replace <text> --with <text> | --content-file <file>)
+  tmlbrain remote delete --file <path>`);
     return;
   }
   if (action === "capabilities") {
@@ -445,16 +533,78 @@ Usage:
   if (action === "update") {
     const file = opts.file || opts._[0];
     if (!file) fail("Use: tmlbrain remote update --file <path> ...");
+    const expectedSha256 = opts["expected-sha256"] || localSnapshotSha(file) || null;
     const payload = {
       path: file,
       replace: opts.replace,
       with: opts.with,
       content: opts.content || readContentOption(opts),
-      expectedSha256: opts["expected-sha256"] || null,
+      expectedSha256,
       message: opts.message || null
     };
-    const response = await requestServerJson("/knowledge/update", payload, opts);
-    output(response, opts);
+    try {
+      const response = await requestServerJson("/knowledge/update", payload, opts);
+      output(response, opts);
+    } catch (error) {
+      if (error.statusCode === 409 && error.data?.conflict) {
+        const conflictFile = createApiConflictPackage(error.data.conflict, payload);
+        try {
+          const snapshot = await requestServerGetJson("/snapshot", opts);
+          applySnapshot(snapshot);
+        } catch {
+          // Keep the conflict package even when refresh fails.
+        }
+        output({
+          ok: false,
+          conflict: rel(conflictFile),
+          serverConflict: error.data.conflict,
+          actions: [
+            "Created a TMLBrain conflict package.",
+            "Refreshed the local snapshot when possible.",
+            "Review with `tmlbrain conflict show <id>` and retry with a more precise update."
+          ]
+        }, opts);
+        return;
+      }
+      throw error;
+    }
+    return;
+  }
+  if (action === "delete" || action === "remove") {
+    const file = opts.file || opts._[0];
+    if (!file) fail("Use: tmlbrain remote delete --file <path>");
+    const expectedSha256 = opts["expected-sha256"] || localSnapshotSha(file) || null;
+    const payload = {
+      path: file,
+      expectedSha256,
+      message: opts.message || null
+    };
+    try {
+      const response = await requestServerJson("/knowledge/delete", payload, opts);
+      output(response, opts);
+    } catch (error) {
+      if (error.statusCode === 409 && error.data?.conflict) {
+        const conflictFile = createApiConflictPackage(error.data.conflict, payload);
+        try {
+          const snapshot = await requestServerGetJson("/snapshot", opts);
+          applySnapshot(snapshot);
+        } catch {
+          // Keep the conflict package even when refresh fails.
+        }
+        output({
+          ok: false,
+          conflict: rel(conflictFile),
+          serverConflict: error.data.conflict,
+          actions: [
+            "Created a TMLBrain conflict package.",
+            "Refreshed the local snapshot when possible.",
+            "Review with `tmlbrain conflict show <id>` before retrying the delete."
+          ]
+        }, opts);
+        return;
+      }
+      throw error;
+    }
     return;
   }
   fail(`Unknown remote action: ${action}`);
@@ -550,7 +700,7 @@ function cmdServe(args) {
   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) });
+      sendJson(res, error.statusCode || 500, error.payload || { ok: false, error: error.message || String(error) });
     });
   });
   server.listen(port, host, () => {
@@ -652,30 +802,9 @@ function cmdConflict(args) {
 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");
+  const entry = pushBackupRepository(remote, { dryRun, reason: "manual" });
   output(entry, opts);
   if (!entry.ok && !dryRun) process.exit(1);
 }
@@ -722,8 +851,21 @@ function cmdPublish(args) {
 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);
+  if (action === "setup") {
+    output(setupGraphRuntime({ dryRun: Boolean(opts["dry-run"]) }), opts);
+    return;
+  }
+  if (action === "index") {
+    output(runGraphScript("cocoindex_pipeline.py", ["--root", ROOT, "--json"], opts), opts);
+    return;
+  }
+  if (action === "query" || action === "search") {
+    const query = opts._.join(" ").trim();
+    if (!query) fail("Use: tmlbrain graph query <query>");
+    output(runGraphScript("lightrag_retrieval.py", [query, "--root", ROOT, "--limit", String(opts.limit || 5), "--json"], opts), opts);
+    return;
+  }
+  fail("Graph action must be setup, index, or query.");
 }
 
 function setupGraphRuntime({ dryRun = false } = {}) {
@@ -748,6 +890,36 @@ function setupGraphRuntime({ dryRun = false } = {}) {
   return result;
 }
 
+function runGraphScript(scriptName, args) {
+  const python = checkCommand("python", ["--version"]).ok ? "python" : (checkCommand("py", ["--version"]).ok ? "py" : null);
+  if (!python) {
+    return {
+      ok: false,
+      degraded: true,
+      reason: "python is not available; exact search and deterministic Node index remain usable"
+    };
+  }
+  const script = path.join(PACKAGE_ROOT, "scripts", "index", scriptName);
+  if (!fs.existsSync(script)) fail(`Graph script not found: ${script}`);
+  const result = spawnSync(python, [script, ...args], {
+    cwd: ROOT,
+    encoding: "utf8",
+    env: { ...process.env, PYTHONIOENCODING: "utf-8" }
+  });
+  const text = (result.stdout || "").trim();
+  let payload;
+  try {
+    payload = text ? JSON.parse(text) : { ok: result.status === 0 };
+  } catch {
+    payload = { ok: result.status === 0, output: text };
+  }
+  if (result.status !== 0 && result.status !== 2) {
+    payload.ok = false;
+    payload.error = sanitizeGit(result.stderr || result.stdout);
+  }
+  return payload;
+}
+
 function safeConfigView(state) {
   return {
     configFile: rel(STATE_FILE),
@@ -770,7 +942,7 @@ function capabilities() {
       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"
+        "request server-side save/update/delete operations through the TMLBrain server API"
       ],
       server: [
         "mutate Markdown knowledge files",
@@ -788,24 +960,32 @@ function capabilities() {
     configuredServer: state.server || null,
     config: safeConfigView(state),
     userCommands: [
+      { command: "tmlbrain update", role: "client", description: "Update the npm package, refresh the local Skill/runtime, and preserve existing client configuration." },
       { 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." }
+      { command: "tmlbrain graph index", role: "client", description: "Build the CocoIndex-compatible local Markdown index under .tmlbrain/index/." },
+      { command: "tmlbrain graph query <query>", role: "client", description: "Query local chunks and graph context through the LightRAG-compatible retrieval adapter." },
+      { command: "tmlbrain save --title <title> --content <text>", role: "client-request", description: "Classify and save new knowledge through the server API." },
+      { command: "tmlbrain save <file>", role: "client-request", description: "Classify and 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." },
+      { command: "tmlbrain remote delete --file <path>", role: "client-request", description: "Ask the server to delete a knowledge document after explicit user confirmation." }
     ],
     commands: [
+      { command: "tmlbrain update", role: "client", description: "Update the globally installed package and refresh local runtime files without asking for setup again." },
       { 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 graph index", role: "client", description: "Build CocoIndex-compatible local index artifacts from knowledge/**/*.md." },
+      { command: "tmlbrain graph query <query>", role: "client", description: "Retrieve relevant local chunks and graph context through the LightRAG-compatible adapter." },
+      { command: "tmlbrain save --title <title> --content <text>", role: "client-request", description: "User-facing alias that classifies knowledge and asks the server to save it." },
+      { command: "tmlbrain save <file>", role: "client-request", description: "User-facing alias that classifies a local file and asks the server to save it." },
       { 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 remote delete --file <path>", role: "client-request", description: "Ask the server to delete a Markdown knowledge document 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." }
     ]
@@ -845,6 +1025,11 @@ async function routeServerRequest(req, res, token) {
     sendJson(res, 200, serverUpdateKnowledge(body));
     return;
   }
+  if (req.method === "POST" && requestUrl.pathname === "/knowledge/delete") {
+    const body = await readJsonBody(req);
+    sendJson(res, 200, serverDeleteKnowledge(body));
+    return;
+  }
   sendJson(res, 404, { ok: false, error: `Unknown TMLBrain endpoint: ${req.method} ${requestUrl.pathname}` });
 }
 
@@ -867,8 +1052,17 @@ function serverUpdateKnowledge(payload) {
   return serverMutation(payload.message || `Update knowledge: ${payload.path || "unknown"}`, () => {
     const target = safeKnowledgeFile(payload.path);
     const before = fs.readFileSync(target, "utf8");
+    const currentSha256 = sha256(before);
     if (payload.expectedSha256 && sha256(before) !== payload.expectedSha256) {
-      failRequest(409, `Expected sha256 ${payload.expectedSha256}, found ${sha256(before)}.`);
+      failConflict(structuredConflict({
+        pathName: rel(target),
+        reason: "expected-sha256-mismatch",
+        message: `Expected sha256 ${payload.expectedSha256}, found ${currentSha256}.`,
+        currentText: before,
+        rejected: payload,
+        currentSha256,
+        expectedSha256: payload.expectedSha256
+      }));
     }
     let after = before;
     if (payload.content !== undefined && payload.content !== null) {
@@ -877,8 +1071,27 @@ function serverUpdateKnowledge(payload) {
       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.`);
+      if (occurrences === 0) {
+        failConflict(structuredConflict({
+          pathName: rel(target),
+          reason: "replacement-not-found",
+          message: "Replacement text was not found in the server document.",
+          currentText: before,
+          rejected: payload,
+          currentSha256
+        }));
+      }
+      if (occurrences > 1 && !payload.all) {
+        failConflict(structuredConflict({
+          pathName: rel(target),
+          reason: "replacement-ambiguous",
+          message: `Replacement text matched ${occurrences} times. Provide a more specific replacement.`,
+          currentText: before,
+          rejected: payload,
+          currentSha256,
+          occurrences
+        }));
+      }
       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.");
@@ -894,14 +1107,40 @@ function serverUpdateKnowledge(payload) {
   });
 }
 
+function serverDeleteKnowledge(payload) {
+  return serverMutation(payload.message || `Delete knowledge: ${payload.path || "unknown"}`, () => {
+    const target = safeKnowledgeFile(payload.path);
+    if (!fs.existsSync(target)) failRequest(404, `Knowledge file not found: ${rel(target)}`);
+    const before = fs.readFileSync(target, "utf8");
+    const currentSha256 = sha256(before);
+    if (payload.expectedSha256 && currentSha256 !== payload.expectedSha256) {
+      failConflict(structuredConflict({
+        pathName: rel(target),
+        reason: "expected-sha256-mismatch",
+        message: `Expected sha256 ${payload.expectedSha256}, found ${currentSha256}.`,
+        currentText: before,
+        rejected: { ...payload, delete: true },
+        currentSha256,
+        expectedSha256: payload.expectedSha256
+      }));
+    }
+    fs.unlinkSync(target);
+    return {
+      action: "delete",
+      path: rel(target),
+      beforeSha256: currentSha256
+    };
+  });
+}
+
 function serverMutation(message, mutate) {
   ensureGit();
   ensureGitWorktree();
   ensureServerGitIdentity();
   const beforeHead = currentHead();
-  const beforeStatus = git(["status", "--porcelain"], { allowFail: true });
+  const beforeStatus = git(["status", "--porcelain", "--", "knowledge"], { allowFail: true });
   if (beforeStatus.ok && beforeStatus.stdout.trim()) {
-    failRequest(409, "Server worktree has uncommitted changes; refusing to mutate knowledge.");
+    failRequest(409, "Server knowledge files have uncommitted changes; refusing to mutate knowledge.");
   }
   const result = mutate();
   const validation = validateKnowledge();
@@ -921,6 +1160,7 @@ function serverMutation(message, mutate) {
     failRequest(500, sanitizeGit(commit.stderr || commit.stdout));
   }
   const pushResult = pushServerRepository();
+  const backupResult = pushBackupRepository("backup", { reason: "api-write" });
   const head = currentHead();
   snapshotBase();
   return {
@@ -930,6 +1170,7 @@ function serverMutation(message, mutate) {
     head,
     pushed: pushResult.ok,
     pushMessage: pushResult.message,
+    backup: backupResult,
     validation,
     result,
     diff: diff.stdout || ""
@@ -945,6 +1186,34 @@ function pushServerRepository() {
   return { ok: push.ok, message: sanitizeGit(push.stderr || push.stdout) };
 }
 
+function pushBackupRepository(remote = "backup", { dryRun = false, reason = "manual" } = {}) {
+  ensureDir(LOG_DIR);
+  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(),
+    reason,
+    dryRun,
+    remote,
+    sourceCommit: source.ok ? source.stdout.trim() : null,
+    ok: false
+  };
+  if (!hasRemote) {
+    entry.skipped = true;
+    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");
+  return entry;
+}
+
 function revertServerWorktree() {
   git(["reset", "--hard"], { allowFail: true });
   git(["clean", "-fd", "knowledge"], { allowFail: true });
@@ -1060,6 +1329,12 @@ function readContentOption(opts) {
   return fs.readFileSync(filePath, "utf8");
 }
 
+function localSnapshotSha(filePath) {
+  const normalized = String(filePath || "").replace(/\\/g, "/");
+  const state = readState();
+  return state.files?.[normalized]?.sha256 || null;
+}
+
 async function requestServerGetJson(endpoint, opts) {
   return requestServer("GET", endpoint, null, opts);
 }
@@ -1071,7 +1346,7 @@ async function requestServerJson(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");
+  if (!base || !isHttpUrl(base)) fail("Configure an HTTP TMLBrain server first: tmlbrain install --server http://host:8477");
   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;
@@ -1096,7 +1371,10 @@ async function requestServer(method, endpoint, body, opts) {
           return;
         }
         if (res.statusCode >= 400) {
-          reject(new Error(data.error || `TMLBrain server returned HTTP ${res.statusCode}`));
+          const error = new Error(data.error || `TMLBrain server returned HTTP ${res.statusCode}`);
+          error.statusCode = res.statusCode;
+          error.data = data;
+          reject(error);
           return;
         }
         resolve(data);
@@ -1173,6 +1451,47 @@ function failRequest(statusCode, message) {
   throw error;
 }
 
+function failConflict(conflict) {
+  const error = new Error(conflict.message || "TMLBrain update conflict.");
+  error.statusCode = 409;
+  error.payload = { ok: false, error: error.message, conflict };
+  throw error;
+}
+
+function structuredConflict({ pathName, reason, message, currentText, rejected, currentSha256, expectedSha256 = null, occurrences = null }) {
+  const relevant = relevantConflictText(currentText, rejected?.replace);
+  return {
+    path: pathName,
+    reason,
+    message,
+    currentSha256,
+    expectedSha256,
+    currentRelevantText: relevant,
+    rejectedIntent: {
+      replace: rejected?.replace ?? null,
+      with: rejected?.with ?? null,
+      contentProvided: rejected?.content !== undefined && rejected?.content !== null,
+      expectedSha256: rejected?.expectedSha256 ?? null
+    },
+    occurrences,
+    suggestedNextActions: [
+      "Run `tmlbrain sync --pull` to refresh the local snapshot.",
+      "Review the current relevant text.",
+      "Retry with a more precise replacement or ask the user to confirm a merged result."
+    ]
+  };
+}
+
+function relevantConflictText(text, needle) {
+  if (!needle) return String(text || "").slice(0, 4000);
+  const source = String(text || "");
+  const index = source.indexOf(String(needle));
+  if (index < 0) return source.slice(0, 4000);
+  const start = Math.max(0, index - 1000);
+  const end = Math.min(source.length, index + String(needle).length + 1000);
+  return source.slice(start, end);
+}
+
 function validateKnowledge() {
   const errors = [];
   const warnings = [];
@@ -1288,6 +1607,25 @@ function createConflictPackage({ reason, patchPath, pathName, base, local, remot
   return file;
 }
 
+function createApiConflictPackage(conflict, rejectedPayload) {
+  return createConflictPackage({
+    reason: conflict.reason || "api update conflict",
+    patchPath: null,
+    pathName: conflict.path || rejectedPayload.path || "knowledge",
+    base: conflict.expectedSha256 ? `expectedSha256: ${conflict.expectedSha256}` : "",
+    local: JSON.stringify(conflict.rejectedIntent || rejectedPayload, null, 2),
+    remote: [
+      conflict.message || "Server rejected the update.",
+      "",
+      "Current relevant text:",
+      conflict.currentRelevantText || "",
+      "",
+      "Suggested next actions:",
+      ...(conflict.suggestedNextActions || [])
+    ].join("\n")
+  });
+}
+
 function snapshotBase() {
   if (!fs.existsSync(KNOWLEDGE_DIR)) return;
   ensureDir(BASE_DIR);
@@ -1370,9 +1708,32 @@ function folderForType(type) {
     area: "knowledge/20-areas",
     resource: "knowledge/30-resources",
     reference: "knowledge/40-references",
-    meeting: "knowledge/00-inbox",
+    meeting: "knowledge/10-projects",
     decision: "knowledge/10-projects"
-  }[type] || "knowledge/00-inbox";
+  }[type] || "knowledge/30-resources";
+}
+
+function classifyKnowledgePlacement({ title = "", content = "", type, folder }) {
+  if (folder) {
+    const normalizedType = VALID_TYPES.has(type) ? type : inferKnowledgeType(title, content);
+    return { type: normalizedType, folder, reason: "explicit-folder" };
+  }
+  if (VALID_TYPES.has(type)) return { type, folder: folderForType(type), reason: "explicit-type" };
+  const inferredType = inferKnowledgeType(title, content);
+  return { type: inferredType, folder: folderForType(inferredType), reason: "classified" };
+}
+
+function inferKnowledgeType(title = "", content = "") {
+  const text = `${title}\n${content}`.toLowerCase();
+  const frontMatter = parseFrontMatter(String(content || "")).data || {};
+  if (VALID_TYPES.has(String(frontMatter.type))) return String(frontMatter.type);
+
+  if (/(决策|决定|decision|adr|选型|结论|取舍|trade-?off)/i.test(text)) return "decision";
+  if (/(会议|纪要|meeting|minutes|复盘|retro|standup|周会|例会)/i.test(text)) return "meeting";
+  if (/(项目|project|roadmap|里程碑|计划|排期|需求|方案|proposal|prd)/i.test(text)) return "project";
+  if (/(规范|流程|制度|职责|责任区|area|长期维护|运维|运营规则|治理|标准)/i.test(text)) return "area";
+  if (/(参考|reference|api|接口|配置项|清单|checklist|手册|词典|字段|参数|索引)/i.test(text)) return "reference";
+  return "resource";
 }
 
 function looksLikeFilePath(value) {
@@ -1399,6 +1760,18 @@ function parseArgs(args) {
   return opts;
 }
 
+function redactArgs(args) {
+  const redacted = [];
+  for (let i = 0; i < args.length; i += 1) {
+    redacted.push(args[i]);
+    if (args[i] === "--token" && i + 1 < args.length) {
+      redacted.push("<token>");
+      i += 1;
+    }
+  }
+  return redacted;
+}
+
 function promptText(label, defaultValue = "") {
   const suffix = defaultValue ? ` [${defaultValue}]` : "";
   return promptLine(`${label}${suffix}: `).then((answer) => {
@@ -1556,6 +1929,21 @@ function parseRgLine(line) {
   return { path: match[1], line: Number(match[2]), text: match[3] };
 }
 
+function readPackageInfo() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf8"));
+    return {
+      name: pkg.name || "@time-machine-lab/tmlbrain",
+      version: pkg.version || "0.0.0"
+    };
+  } catch {
+    return {
+      name: "@time-machine-lab/tmlbrain",
+      version: "0.0.0"
+    };
+  }
+}
+
 function readState() {
   return fs.existsSync(STATE_FILE) ? JSON.parse(fs.readFileSync(STATE_FILE, "utf8")) : {};
 }
@@ -1591,7 +1979,12 @@ function sha256(value) {
 }
 
 function slugify(value) {
-  return String(value).trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "untitled";
+  return String(value)
+    .trim()
+    .toLowerCase()
+    .normalize("NFKC")
+    .replace(/[^\p{Letter}\p{Number}]+/gu, "-")
+    .replace(/^-+|-+$/g, "") || "untitled";
 }
 
 function today() {
@@ -1610,10 +2003,20 @@ 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" });
+  const result = runCommand(command, args, { encoding: "utf8" });
   return { ok: result.status === 0, version: result.stdout ? result.stdout.split(/\r?\n/)[0] : null };
 }
 
+function runCommand(command, args = [], opts = {}) {
+  const spawnOpts = {
+    cwd: opts.cwd || ROOT,
+    shell: process.platform === "win32"
+  };
+  if (opts.stdio) spawnOpts.stdio = opts.stdio;
+  else spawnOpts.encoding = opts.encoding || "utf8";
+  return spawnSync(command, args, spawnOpts);
+}
+
 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 || "" };