@time-machine-lab/tmlbrain 0.1.1 → 0.1.2

package/README.md

@@ -19,7 +19,7 @@ TMLBrain keeps three coordinated copies of the knowledge base:
 - Maintain a clean folder structure for documents.
 - Let AI search local snapshots and request server-side precise Markdown updates.
 - Pull read-only local snapshots from the server copy.
-- Back up the server copy to GitHub on a server-side schedule.
+- Back up accepted server writes to GitHub from the server side.
 - Build an optional online reading layer later.
 
 ## Repository Layout
@@ -59,8 +59,18 @@ After installation:
 ```text
 tmlbrain find "keyword"
 tmlbrain save --title "Title" --content "Content"
+tmlbrain remote update --file knowledge/30-resources/note.md --replace "old" --with "new"
+tmlbrain remote delete --file knowledge/30-resources/old-note.md
 ```
 
+Saving and archiving into the knowledge base are the same user intent:
+TMLBrain stores the content and classifies it into the approved taxonomy. It
+does not default normal saves to `knowledge/00-inbox/`; inbox is only for
+genuinely unclassified or explicitly temporary capture.
+
+Deletion is explicit: use `remote delete` only when the user really wants a
+document removed. Otherwise prefer marking content stale through `remote update`.
+
 Clients use Node for exact search and local indexing. HTTP-only clients do not
 need Git. Server-side writes use Node plus Git from the server worktree.
 Python-based CocoIndex and LightRAG support are optional graph retrieval
@@ -83,7 +93,7 @@ The server is deployed separately from clients and requires a token:
 docker run -d --name tmlbrain-server \
   -p 8477:8477 \
   -e TMLBRAIN_SERVER_TOKEN=change-me \
-  -e TMLBRAIN_KNOWLEDGE_REPO=https://github.com/Time-Machine-Lab/TMLBrainKnowledge.git \
+  -e TMLBRAIN_KNOWLEDGE_REPO=https://github.com/Time-Machine-Lab/Knowledge.git \
   -e TMLBRAIN_KNOWLEDGE_REF=main \
   -v tmlbrain-data:/data \
   <DOCKER_REPO>:latest
@@ -152,6 +162,17 @@ for private repositories, or `public_repo` only for public repositories. The
 running server needs this credential to push knowledge backups to GitHub;
 clients never need it.
 
+Optional GitHub connectivity secret:
+
+```text
+TMLBRAIN_SERVER_GIT_PROXY_URL
+```
+
+Use it only when the server cannot reach GitHub directly. The deployment applies
+the proxy to Git operations for `https://github.com` only. If this secret is not
+set but a `tmlbrain-proxy` container exists on the server, deployment uses that
+container as the Git-only proxy automatically.
+
 The Docker image contains the TMLBrain tool and knowledge templates only. Real
 team knowledge should live in a dedicated knowledge repository configured with
 `TMLBRAIN_KNOWLEDGE_REPO`. If the server volume already has `/data/worktree`,
@@ -166,5 +187,7 @@ starts.
 - Markdown is the default document format.
 - Small, precise server-side edits are preferred over whole-document rewrites.
 - Every document should have a clear owner, status, and update path.
+- Saved knowledge should be classified into the taxonomy instead of piling up
+  in inbox.
 - AI should help maintain the knowledge base instead of only searching it.
 - Clients do not push to the server repository or dedicated knowledge repository.

package/bin/tmlbrain.js

@@ -132,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]
@@ -139,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
@@ -429,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,
@@ -443,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);
@@ -460,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);
@@ -482,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") {
@@ -524,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}`);
@@ -629,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, () => {
@@ -731,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);
 }
@@ -801,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 } = {}) {
@@ -827,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),
@@ -849,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",
@@ -872,9 +965,12 @@ function capabilities() {
       { 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." },
@@ -882,11 +978,14 @@ function capabilities() {
       { 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." }
     ]
@@ -926,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}` });
 }
 
@@ -948,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) {
@@ -958,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.");
@@ -975,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();
@@ -1002,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 {
@@ -1011,6 +1170,7 @@ function serverMutation(message, mutate) {
     head,
     pushed: pushResult.ok,
     pushMessage: pushResult.message,
+    backup: backupResult,
     validation,
     result,
     diff: diff.stdout || ""
@@ -1026,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 });
@@ -1141,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);
 }
@@ -1177,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);
@@ -1254,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 = [];
@@ -1369,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);
@@ -1451,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) {
@@ -1699,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() {

package/docs/architecture.md

@@ -50,6 +50,19 @@ editing interface, and clients do not push to it.
 The Docker image intentionally contains only the TMLBrain tool and knowledge
 templates. It must not contain real team knowledge.
 
+## Knowledge Placement
+
+Archive, store, save, and record are equivalent user intents for adding content
+to TMLBrain. New knowledge is classified into the approved taxonomy by default:
+
+- `project`, `meeting`, and `decision` content goes under `knowledge/10-projects/`.
+- `area` content goes under `knowledge/20-areas/`.
+- `resource` content goes under `knowledge/30-resources/`.
+- `reference` content goes under `knowledge/40-references/`.
+
+`knowledge/00-inbox/` is reserved for genuinely unclassified or explicitly
+temporary capture, not as the default destination for normal saves.
+
 ## Release Workflow
 
 The npm client package, Docker server image, and server deployment are handled
@@ -72,7 +85,13 @@ After pushing the image, the workflow logs in to the configured server with
 restarts the `tmlbrain-server` container. Runtime knowledge repository
 credentials are passed to the server as mounted secrets or environment
 configuration; they are never baked into the image. Knowledge repository URLs
-must be HTTPS URLs and use `TMLBRAIN_KNOWLEDGE_TOKEN`.
+must be HTTPS URLs and use `TMLBRAIN_KNOWLEDGE_TOKEN`. Deployment validates the
+knowledge repository URL and token before replacing the running server.
+
+If the server needs a proxy for GitHub, deployment can use
+`TMLBRAIN_SERVER_GIT_PROXY_URL` or an existing `tmlbrain-proxy` container. The
+proxy is configured as a Git-only proxy for `https://github.com`, so normal
+server API traffic is unchanged.
 
 ## Search And Graph Layer
 

package/docs/backup.md

@@ -6,9 +6,9 @@ The dedicated knowledge repository is used for disaster recovery, reviewable
 history, first-boot restore, and off-server backup. It is not the primary
 editing surface.
 
-The server needs a dedicated knowledge repository credential only if it is
-expected to push backup state to a private GitHub repository. Clients never
-need repository write credentials.
+The server needs a dedicated knowledge repository credential if it is expected
+to push backup state to GitHub. Clients never need repository write
+credentials.
 
 If TMLBrain must upload modified server knowledge back to GitHub, the running
 server needs write authorization for the dedicated knowledge repository. GitHub
@@ -27,7 +27,7 @@ Recommended credential option:
 Do not bake knowledge repository credentials into the Docker image. Do not
 commit them to the project configuration. GitHub Actions secrets can be used to
 deploy the credential to the server or create a Docker secret, but the running
-server still needs access to a credential when it performs `tmlbrain backup`.
+server still needs access to a credential when it performs backup.
 
 The auto-release workflow supports this deployment pattern with:
 
@@ -40,6 +40,18 @@ TMLBRAIN_KNOWLEDGE_REF
 `TMLBRAIN_KNOWLEDGE_REPO` must be an HTTPS repository URL. The workflow writes
 `TMLBRAIN_KNOWLEDGE_TOKEN` to a mounted secret file and uses `GIT_ASKPASS`
 inside the container, so Git can clone on first boot and push backups later.
+During deployment, the workflow validates the repository URL and token before
+restarting the server container.
+
+If the server cannot reach GitHub directly, set:
+
+```text
+TMLBRAIN_SERVER_GIT_PROXY_URL
+```
+
+This proxy is scoped to Git operations for `https://github.com` only. If the
+secret is not set but a `tmlbrain-proxy` container exists on the server, the
+deployment uses that container automatically.
 
 ## Dry Run
 
@@ -51,6 +63,46 @@ tmlbrain backup --dry-run --remote backup
 
 The command reports the source commit, target remote, and whether the target remote exists. Backup attempts are logged under `.tmlbrain/logs/backup.log`.
 
+## Write-Time Backup
+
+When a server API write creates a new commit, the server first pushes that
+commit to its local `origin` bare repository, then attempts to push `HEAD` to
+the configured `backup` remote. The backup result is returned in the API
+response and appended to `.tmlbrain/logs/backup.log`.
+
+Backup failure does not roll back the accepted knowledge write. Maintainers can
+inspect the backup log and rerun:
+
+```text
+tmlbrain backup --remote backup
+```
+
+## Scheduled Backup
+
+Write-time backup is the primary path. Scheduled backup is a server-side
+fallback for missed pushes or manual server maintenance.
+
+Docker deployments can enable the fallback loop with:
+
+```text
+TMLBRAIN_BACKUP_INTERVAL_SECONDS=900
+TMLBRAIN_BACKUP_REMOTE=backup
+```
+
+When the interval is greater than zero, the container starts
+`scripts/backup/scheduled-backup.sh` in the background and runs
+`tmlbrain backup --remote <remote>` from `/data/worktree` at that interval.
+
+Non-Docker deployments can use the templates:
+
+```text
+scripts/backup/tmlbrain-backup.service
+scripts/backup/tmlbrain-backup.timer
+```
+
+Copy them to `/etc/systemd/system/`, adjust paths if needed, then enable the
+timer.
+
 For Docker deployments, keep Git inside the server image or sidecar because the
 server write path still commits and pushes. The client runtime can remain
 HTTP-only and does not need Git.
@@ -60,7 +112,7 @@ HTTP-only and does not need Git.
 For Docker deployments, first-boot restore can be handled by:
 
 ```text
-TMLBRAIN_KNOWLEDGE_REPO=https://github.com/Time-Machine-Lab/TMLBrainKnowledge.git
+TMLBRAIN_KNOWLEDGE_REPO=https://github.com/Time-Machine-Lab/Knowledge.git
 ```
 
 If `/data/worktree` is missing, the container clones that repository. If the

package/docs/indexing.md

@@ -6,8 +6,8 @@ TMLBrain retrieval is local-first:
 
 1. Exact search with ripgrep or the CLI fallback.
 2. Deterministic Markdown index generated by `tmlbrain index`.
-3. Optional CocoIndex incremental pipeline.
-4. Optional LightRAG graph and semantic retrieval.
+3. CocoIndex-compatible incremental pipeline through `tmlbrain graph index`.
+4. LightRAG-compatible graph and semantic retrieval through `tmlbrain graph query`.
 
 ## Deterministic Index
 
@@ -22,11 +22,30 @@ These files are local generated artifacts and must not be pushed to the server.
 
 ## Graph Runtime
 
-CocoIndex and LightRAG are preferred for the fuller graph retrieval pipeline, but exact search and the deterministic index remain available when the graph runtime is disabled.
+CocoIndex and LightRAG are preferred for the fuller graph retrieval pipeline,
+but exact search and the deterministic index remain available when the graph
+runtime is disabled or optional packages are unavailable.
 
 Optional adapter entrypoints live in:
 
 - `scripts/index/cocoindex_pipeline.py`
 - `scripts/index/lightrag_retrieval.py`
 
-They intentionally return degraded status when the Python graph packages are not installed. A later implementation pass should wire them to a real CocoIndex flow and provider-configured LightRAG storage/retrieval setup.
+Use:
+
+```text
+tmlbrain graph index --json
+tmlbrain graph query "question" --json
+```
+
+`tmlbrain graph index` scans `knowledge/**/*.md`, parses front matter,
+headings, chunks, hashes, Markdown links, wiki links, heading anchors, and
+backlinks, then writes local artifacts under `.tmlbrain/index/cocoindex/`.
+It reuses the previous manifest to skip unchanged document entries by content
+hash.
+
+`tmlbrain graph query` reads the CocoIndex-compatible chunks and graph context,
+then returns ranked local chunks with source paths, line ranges, document
+metadata, and related graph edges. When LightRAG is installed/configured, the
+adapter reports the preferred engine as available; otherwise it uses the
+deterministic local compatible retriever and reports degraded status.

package/docs/install.md

@@ -58,7 +58,7 @@ skeleton.
 docker run -d --name tmlbrain-server \
   -p 8477:8477 \
   -e TMLBRAIN_SERVER_TOKEN=<required-token> \
-  -e TMLBRAIN_KNOWLEDGE_REPO=https://github.com/Time-Machine-Lab/TMLBrainKnowledge.git \
+  -e TMLBRAIN_KNOWLEDGE_REPO=https://github.com/Time-Machine-Lab/Knowledge.git \
   -e TMLBRAIN_KNOWLEDGE_REF=main \
   -v tmlbrain-data:/data \
   <DOCKER_REPO>:latest
@@ -83,7 +83,7 @@ The Docker image does not contain real team knowledge. Real knowledge should be
 stored in a separate private repository, for example:
 
 ```text
-https://github.com/Time-Machine-Lab/TMLBrainKnowledge.git
+https://github.com/Time-Machine-Lab/Knowledge.git
 ```
 
 That repository must contain the TMLBrain `knowledge/` directory at its root.
@@ -134,7 +134,7 @@ TMLBRAIN_KNOWLEDGE_REF
 ```
 
 `TMLBRAIN_KNOWLEDGE_REPO` must be an HTTPS URL, for example
-`https://github.com/Time-Machine-Lab/TMLBrainKnowledge.git`.
+`https://github.com/Time-Machine-Lab/Knowledge.git`.
 `TMLBRAIN_KNOWLEDGE_TOKEN` must be a GitHub token with write access to that
 dedicated knowledge repository. Fine-grained tokens are preferred; classic
 tokens also work when they have the right repository scope: use `repo` for
@@ -142,6 +142,20 @@ private repositories, or `public_repo` only for public repositories. This
 credential belongs to the server runtime, not to clients and not to the Docker
 image.
 
+Optional GitHub connectivity secret:
+
+```text
+TMLBRAIN_SERVER_GIT_PROXY_URL
+```
+
+Use this only when the deployment server cannot reach GitHub directly. The
+workflow applies the proxy to Git operations for `https://github.com` only. If
+the secret is absent but a `tmlbrain-proxy` container is running on the server,
+deployment connects the TMLBrain server container to that proxy automatically.
+Before replacing the running server, the workflow validates
+`TMLBRAIN_KNOWLEDGE_REPO` plus `TMLBRAIN_KNOWLEDGE_TOKEN` with Git so a broken
+token does not create a bad deployment.
+
 ## Release Command Format
 
 Releases are driven by the HEAD commit message on `main`. The workflow skips

package/docs/runtime.md

@@ -22,7 +22,7 @@ The core runtime must work without Python:
 - Local workspace state under `.tmlbrain/`.
 - Exact search.
 - Markdown validation.
-- Document creation.
+- Document creation with taxonomy-based placement.
 - Server API write requests.
 - Read-only snapshot sync.
 
@@ -35,9 +35,14 @@ CocoIndex and LightRAG are optional graph retrieval features. They are enabled b
 
 ```text
 tmlbrain graph setup
+tmlbrain graph index
+tmlbrain graph query "question"
 ```
 
-If Python, CocoIndex, or LightRAG cannot be activated, core TMLBrain remains usable in degraded search mode.
+If Python cannot be activated, core TMLBrain remains usable in degraded search
+mode. If Python is available but CocoIndex or LightRAG packages are missing,
+the graph commands use compatible local adapters and report degraded status
+instead of blocking exact search or deterministic indexing.
 
 ## Installer Entry Points
 
@@ -77,7 +82,7 @@ tmlbrain client install --server http://server-host:8477 --token secret --yes
 Run with Docker:
 
 ```text
-docker run -d --name tmlbrain-server -p 8477:8477 -e TMLBRAIN_SERVER_TOKEN=secret -e TMLBRAIN_KNOWLEDGE_REPO=https://github.com/Time-Machine-Lab/TMLBrainKnowledge.git -v tmlbrain-data:/data <DOCKER_REPO>:latest
+docker run -d --name tmlbrain-server -p 8477:8477 -e TMLBRAIN_SERVER_TOKEN=secret -e TMLBRAIN_KNOWLEDGE_REPO=https://github.com/Time-Machine-Lab/Knowledge.git -v tmlbrain-data:/data <DOCKER_REPO>:latest
 ```
 
 The image contains tooling and templates only. Real knowledge is restored from
@@ -94,5 +99,14 @@ node bin/tmlbrain.js serve --host 0.0.0.0 --port 8477
 
 Only the server runtime should mutate Markdown, commit repository changes, or
 push to the dedicated knowledge repository. Clients should use `tmlbrain sync
---pull` for snapshots, `tmlbrain find` for local search, and `tmlbrain save` or
-`tmlbrain remote update` for write requests.
+--pull` for snapshots, `tmlbrain find` for local search, and `tmlbrain save`,
+`tmlbrain remote update`, or explicit `tmlbrain remote delete` for write
+requests. Normal `tmlbrain save` requests classify content into the knowledge
+taxonomy; `00-inbox` is reserved for genuinely unclear or explicitly temporary
+capture. Deletion is reserved for explicit user intent; otherwise prefer
+marking content stale.
+
+Server writes attempt GitHub backup immediately after an accepted commit. A
+scheduled fallback can be enabled in Docker with
+`TMLBRAIN_BACKUP_INTERVAL_SECONDS`; systemd timer templates are available under
+`scripts/backup/` for non-Docker deployments.

package/docs/server-api.md

@@ -5,7 +5,15 @@ TMLBrain uses a server-owned write boundary.
 Clients keep a read-only local snapshot for search and indexing. Clients request
 knowledge mutations through the TMLBrain server API. The server mutates
 Markdown, validates the knowledge base, commits the repository change, and then
-pushes from the server worktree to the server bare repository.
+pushes from the server worktree to the server bare repository. After a
+successful write commit, the server also attempts to push the same commit to
+the configured `backup` remote so the dedicated GitHub knowledge repository
+stays current.
+
+For new knowledge, archive/store/save/record requests are treated as the same
+save operation. The client and server classify the document into the approved
+taxonomy by default; `00-inbox` is reserved for genuinely unclear or explicitly
+temporary capture.
 
 ## Run The Server
 
@@ -15,7 +23,7 @@ Recommended Docker deployment:
 docker run -d --name tmlbrain-server \
   -p 8477:8477 \
   -e TMLBRAIN_SERVER_TOKEN=secret \
-  -e TMLBRAIN_KNOWLEDGE_REPO=https://github.com/Time-Machine-Lab/TMLBrainKnowledge.git \
+  -e TMLBRAIN_KNOWLEDGE_REPO=https://github.com/Time-Machine-Lab/Knowledge.git \
   -v tmlbrain-data:/data \
   <DOCKER_REPO>:latest
 ```
@@ -24,6 +32,12 @@ docker run -d --name tmlbrain-server \
 data volume already contains `/data/worktree`, the container reuses that
 worktree instead of cloning again.
 
+For private GitHub knowledge repositories, deploy the server with
+`TMLBRAIN_KNOWLEDGE_TOKEN` as a runtime secret. If the server cannot reach
+GitHub directly, deployment may set `TMLBRAIN_SERVER_GIT_PROXY_URL` or reuse an
+existing `tmlbrain-proxy` container; that proxy is applied only to GitHub Git
+traffic.
+
 Run from the server worktree:
 
 ```text
@@ -39,7 +53,8 @@ TMLBRAIN_SERVER_TOKEN=secret node bin/tmlbrain.js serve --host 0.0.0.0 --port 84
 Clients then install with:
 
 ```text
-npx -y @time-machine-lab/tmlbrain@latest client install --server http://server-host:8477 --token secret --yes
+npm install -g @time-machine-lab/tmlbrain@latest
+tmlbrain client install --server http://server-host:8477 --token secret --yes
 ```
 
 The client stores this in `.tmlbrain/state.json`. The token is not shown by
@@ -66,7 +81,7 @@ and use a tunnel from the client machine:
 
 ```text
 ssh -N -L 8478:127.0.0.1:8477 tmlbrain-1007
-npx -y @time-machine-lab/tmlbrain@latest client install --server http://127.0.0.1:8478 --token secret --yes
+tmlbrain client install --server http://127.0.0.1:8478 --token secret --yes
 ```
 
 ## Client Commands
@@ -101,19 +116,53 @@ Ask the server to update a precise text region:
 node bin/tmlbrain.js remote update --file knowledge/00-inbox/note.md --replace "old text" --with "new text"
 ```
 
+Ask the server to delete a knowledge document only after the user explicitly
+requests deletion:
+
+```text
+node bin/tmlbrain.js remote delete --file knowledge/30-resources/old-note.md
+```
+
+Normal client updates automatically include the last synced file hash as
+`expectedSha256` when the local snapshot has one. If the server document has
+changed, the server returns a structured `409` conflict containing the current
+hash, relevant current text, rejected intent, reason, and suggested next
+actions. Delete requests use the same stale-file protection when the local
+snapshot has a file hash. The CLI turns that response into a local TMLBrain
+conflict package and refreshes the snapshot when possible.
+
 ## API Endpoints
 
 - `GET /health`: server health and current head.
 - `GET /capabilities`: machine-readable command and boundary description.
 - `GET /snapshot`: read-only Markdown snapshot for clients.
-- `POST /knowledge/add`: server-side add, validate, commit, and push.
-- `POST /knowledge/update`: server-side replace or content-file update, validate, commit, and push.
+- `POST /knowledge/add`: server-side classified add, validate, commit, push to local server repository, and attempt GitHub backup.
+- `POST /knowledge/update`: server-side replace or content-file update, validate, commit, push to local server repository, and attempt GitHub backup.
+- `POST /knowledge/delete`: server-side Markdown document delete, validate, commit, push to local server repository, and attempt GitHub backup.
+
+Structured update conflicts return:
+
+```json
+{
+  "ok": false,
+  "error": "Expected sha256 ...",
+  "conflict": {
+    "path": "knowledge/...",
+    "reason": "expected-sha256-mismatch",
+    "currentSha256": "...",
+    "expectedSha256": "...",
+    "currentRelevantText": "...",
+    "rejectedIntent": {},
+    "suggestedNextActions": []
+  }
+}
+```
 
 ## Boundary
 
 Clients MUST NOT push to the server Git repository or dedicated knowledge
 repository. Backing up to that repository remains a server-side operation
-through `tmlbrain backup`.
+through write-time backup and `tmlbrain backup`.
 
 HTTP-only clients do not need Git installed. The server runtime still needs Git
 because it validates, commits, pushes to the server bare repository, and runs

package/docs/sync.md

@@ -14,8 +14,14 @@ Users ask TMLBrain to write knowledge through the server:
 tmlbrain save --title "Title" --content "Content"
 tmlbrain save ./note.md
 tmlbrain remote update --file knowledge/00-inbox/note.md --replace "old" --with "new"
+tmlbrain remote delete --file knowledge/30-resources/old-note.md
 ```
 
+Archive, store, save, and record are equivalent user intents for adding content
+to the knowledge base. Save requests classify content into the approved
+taxonomy by default. `00-inbox` is only used when the correct long-term folder
+is genuinely unclear or explicitly requested.
+
 They should not need to run `git pull`, `git push`, `git merge`, or `git rebase`.
 Clients also should not perform hidden Git writes to the server. In the
 HTTP-only workflow, clients do not need Git installed.
@@ -35,9 +41,14 @@ client write request
   -> server validation
   -> server Git commit
   -> server bare repository
-  -> dedicated knowledge repository backup
+  -> dedicated knowledge repository backup attempt
 ```
 
+`tmlbrain remote delete` is a server-owned write request too. Clients only send
+the explicit delete intent; the server performs the file removal, validates the
+remaining knowledge base, commits the change, pushes the server repository, and
+attempts the dedicated GitHub backup.
+
 ## Conflict Handling
 
 When the server cannot apply a requested update safely, it rejects the request
@@ -45,10 +56,19 @@ instead of silently overwriting remote knowledge. For precise text replacement,
 the server requires the replacement text to match exactly once unless a broader
 operation is explicitly requested.
 
+For normal `tmlbrain remote update` requests, the client reads the last synced
+file hash from `.tmlbrain/state.json` and sends it as `expectedSha256`. If the
+server file has changed, or if replacement text is missing or ambiguous, the
+server returns a structured `409` response with the current hash, relevant
+server text, rejected intent, reason, and suggested next action.
+
 When future merge flows need human review, TMLBrain should create conflict
 packages under `.tmlbrain/conflicts/` instead of dropping the user into raw Git
 conflict markers.
 
+The CLI now creates those packages for API `409` responses and refreshes the
+local snapshot when possible.
+
 Conflict packages contain:
 
 - conflict id;
@@ -72,8 +92,8 @@ Recommended MVP server layout:
 
 The server API should run from `/srv/tmlbrain-worktree`. After an accepted
 write request, the server commits in the worktree and pushes to
-`/srv/tmlbrain.git`. Backup to the dedicated knowledge repository is a separate
-server-side job.
+`/srv/tmlbrain.git`, then attempts to push the accepted commit to the
+dedicated knowledge repository backup remote.
 
 Recommended Docker server layout:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@time-machine-lab/tmlbrain",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "TMLBrain local-first team knowledge base tooling.",
   "type": "commonjs",
   "bin": {
@@ -19,6 +19,8 @@
     "tmlbrain": "node bin/tmlbrain.js",
     "validate": "node bin/tmlbrain.js validate",
     "index": "node bin/tmlbrain.js index",
+    "graph:index": "node bin/tmlbrain.js graph index --json",
+    "graph:query": "node bin/tmlbrain.js graph query \"knowledge\" --json",
     "test": "node bin/tmlbrain.js validate && node bin/tmlbrain.js index --json"
   },
   "engines": {

package/scripts/backup/scheduled-backup.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env sh
+set -eu
+
+INTERVAL="${TMLBRAIN_BACKUP_INTERVAL_SECONDS:-0}"
+REMOTE="${TMLBRAIN_BACKUP_REMOTE:-backup}"
+WORKTREE="${TMLBRAIN_WORKTREE:-${TMLBRAIN_DATA_DIR:-/data}/worktree}"
+APP_DIR="${TMLBRAIN_APP_DIR:-/app}"
+
+case "$INTERVAL" in
+  ''|*[!0-9]*)
+    echo "TMLBRAIN_BACKUP_INTERVAL_SECONDS must be a positive integer." >&2
+    exit 2
+    ;;
+esac
+
+if [ "$INTERVAL" -le 0 ]; then
+  echo "TMLBrain scheduled backup disabled."
+  exit 0
+fi
+
+while :; do
+  sleep "$INTERVAL"
+  if [ ! -d "$WORKTREE/.git" ]; then
+    echo "TMLBrain scheduled backup skipped: $WORKTREE is not a Git worktree." >&2
+    continue
+  fi
+  echo "Running scheduled TMLBrain backup to $REMOTE."
+  (
+    cd "$WORKTREE"
+    node "$APP_DIR/bin/tmlbrain.js" backup --remote "$REMOTE"
+  ) || echo "Scheduled TMLBrain backup failed." >&2
+done

package/scripts/backup/tmlbrain-backup.service

@@ -0,0 +1,9 @@
+[Unit]
+Description=TMLBrain scheduled knowledge backup
+Wants=network-online.target
+After=network-online.target
+
+[Service]
+Type=oneshot
+WorkingDirectory=/data/worktree
+ExecStart=/usr/bin/node /app/bin/tmlbrain.js backup --remote backup

package/scripts/backup/tmlbrain-backup.timer

@@ -0,0 +1,10 @@
+[Unit]
+Description=Run TMLBrain knowledge backup periodically
+
+[Timer]
+OnBootSec=5min
+OnUnitActiveSec=15min
+Persistent=true
+
+[Install]
+WantedBy=timers.target

package/scripts/docker/server-entrypoint.sh

@@ -81,4 +81,8 @@ fi
 
 git push -u origin HEAD:main >/dev/null 2>&1 || true
 
+if [ "${TMLBRAIN_BACKUP_INTERVAL_SECONDS:-0}" != "0" ]; then
+  TMLBRAIN_WORKTREE="$WORKTREE" TMLBRAIN_APP_DIR="/app" /app/scripts/backup/scheduled-backup.sh &
+fi
+
 exec node /app/bin/tmlbrain.js serve --host "$HOST" --port "$PORT"

package/skills/tmlbrain/SKILL.md

@@ -29,9 +29,13 @@ the TMLBrain knowledge base.
 
 - When a user says "archive to the knowledge base", "store this", "save this",
   "record this", or similar, treat it as "save this knowledge into TMLBrain".
-- Use `tmlbrain save` for that user-facing save path. Do not set
+- Use `tmlbrain save` for that user-facing save path. Treat archive, store,
+  save, and record as equivalent user intents for storing knowledge. Do not set
   `status: archived` or choose `knowledge/90-archive/` unless the user
   explicitly means inactive historical content.
+- Classify new saved knowledge according to the folder taxonomy before saving.
+  Do not default to `knowledge/00-inbox/` when the document intent can be
+  inferred from the title or content.
 - Explain available actions as save, search, update, and sync. Avoid exposing
   internal names such as archive, ingest, Git, commit, or backup unless the user
   asks about implementation details.
@@ -40,7 +44,7 @@ the TMLBrain knowledge base.
 
 Use the approved folder taxonomy:
 
-- `knowledge/00-inbox/`: temporary or unclassified notes.
+- `knowledge/00-inbox/`: temporary or genuinely unclassified notes only.
 - `knowledge/10-projects/`: project-specific documents, plans, decisions, and retrospectives.
 - `knowledge/20-areas/`: long-lived responsibility areas.
 - `knowledge/30-resources/`: reusable research, notes, methods, and learning material.
@@ -72,10 +76,11 @@ for newly saved knowledge.
 4. If needed, use `tmlbrain index` and inspect `.tmlbrain/index/` outputs.
 5. If graph retrieval is enabled, use CocoIndex-derived metadata/graph indexes and LightRAG retrieval after exact search.
 6. Read relevant local source documents.
-7. For new knowledge, use `tmlbrain save`.
+7. For new knowledge, classify its intent, then use `tmlbrain save`.
 8. For updates, use `tmlbrain remote update --file <path> --replace <old> --with <new>` or a content-file update when a full document replacement is explicitly intended.
-9. Show or summarize the server-returned diff and result.
-10. Run `tmlbrain sync --pull` again so the local snapshot and indexes reflect the accepted server commit.
+9. For explicit deletion requests, use `tmlbrain remote delete --file <path>`; otherwise prefer marking stale.
+10. Show or summarize the server-returned diff and result.
+11. Run `tmlbrain sync --pull` again so the local snapshot and indexes reflect the accepted server commit.
 
 ## Command Recipes
 
@@ -102,6 +107,8 @@ Enable optional graph runtime:
 
 ```text
 tmlbrain graph setup
+tmlbrain graph index
+tmlbrain graph query "question"
 ```
 
 Validate metadata and links:
@@ -140,6 +147,12 @@ Update a precise server-side text region:
 tmlbrain remote update --file knowledge/00-inbox/note.md --replace "old text" --with "new text"
 ```
 
+Delete a knowledge document only when the user explicitly asks for deletion:
+
+```text
+tmlbrain remote delete --file knowledge/30-resources/old-note.md
+```
+
 Refresh local snapshot from the server:
 
 ```text
@@ -184,6 +197,10 @@ If TMLBrain reports a conflict package:
 Do not ask the user to interpret raw Git conflict markers. Do not force-push or
 silently overwrite remote content.
 
+For API update conflicts, the CLI creates a conflict package automatically from
+the server's structured `409` response and refreshes the local snapshot when it
+can. Review the package before retrying the update.
+
 ## Forbidden Client Actions
 
 Do not run these as a normal client workflow: