@imunitic/synapse 0.0.1-test.0

package/lib/obsidian-mcp-refresh.cjs

@@ -0,0 +1,303 @@
+#!/usr/bin/env node
+// SessionStart hook: keeps the `obsidian` MCP server registration current,
+// automatically, every session -- the hook-driven replacement for manually
+// running setup-obsidian-mcp.sh. Independent of, and never wired through,
+// fetch-and-run.cjs/synapse-hook: different domain (wiring up the connection
+// to the vault, not Synapse's own code-graph/vault logic), kept separate so
+// a bug here can never risk the core Synapse injection into every turn's
+// context.
+//
+// Node, not a shell script: the only interpreter every hook subprocess is
+// guaranteed to have on PATH is the one Claude Code itself ships with. `jq`
+// and `curl` are gone entirely (native JSON.parse and the built-in `https`
+// module replace them); `claude` itself is still an external dependency,
+// since MCP registration is its own command, not something this hook can do
+// any other way.
+//
+// Every missing precondition is silence, same convention every other Synapse
+// hook already follows -- this never blocks a turn, and produces no stdout
+// (a SessionStart hook's stdout becomes injected context; this is a pure
+// side-effecting maintenance task, nothing worth telling the model). Genuine
+// problems go to stderr only, same as the original script already did.
+//
+// One real, pre-existing limitation, not new here: MCP servers connect at
+// Claude Code startup, before any hook fires, so this can't fix the *current*
+// session's connection -- first-time registration or a cert/key rotation
+// still needs one restart to take effect.
+
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const https = require("https");
+const { spawnSync } = require("child_process");
+
+function commandExists(cmd) {
+  const res = spawnSync(cmd, ["--version"], { stdio: "ignore" });
+  return !(res.error && res.error.code === "ENOENT");
+}
+
+// `$VAR`/`${VAR}` expansion looks HOME up through this rather than reading
+// `process.env.HOME` directly, so the one thing standing between this
+// resolving correctly and not on a platform with no `HOME` env var (Windows)
+// is this one substitution -- everything downstream (conf-file tiering,
+// `~`/`$HOME` expansion) is otherwise a direct port of core/conf.zig's
+// algorithm and stays untouched.
+function getVar(name) {
+  if (name === "HOME") return os.homedir();
+  return process.env[name];
+}
+
+// Mirrors core/conf.zig's `get`: one key's raw value from a conf file's
+// text, unexpanded. Comments, blank lines, an `export` prefix, and a
+// matched-quote or trailing-comment unquote, same as a shell would read it.
+// The last assignment wins, same as sourcing would.
+function confGet(text, key) {
+  let found = null;
+  for (let raw of text.split("\n")) {
+    let line = raw.trim();
+    if (line.length === 0 || line[0] === "#") continue;
+    if (line.startsWith("export ")) line = line.slice("export ".length).trimStart();
+    if (!line.startsWith(key)) continue;
+    const rest = line.slice(key.length);
+    if (rest.length === 0 || rest[0] !== "=") continue;
+    found = confUnquote(rest.slice(1).trim());
+  }
+  return found;
+}
+
+function confUnquote(raw) {
+  if (raw.length >= 2 && (raw[0] === '"' || raw[0] === "'") && raw[raw.length - 1] === raw[0]) {
+    return raw.slice(1, -1);
+  }
+  const m = raw.match(/[#\s]/);
+  return m ? raw.slice(0, m.index) : raw;
+}
+
+const NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*/;
+
+// Mirrors core/conf.zig's `expand`: a leading `~`, `$VAR` and `${VAR}`
+// replaced against `getVar`; everything else (including `${VAR:-default}`,
+// `~user`, and a Windows path's backslashes) left exactly as-is.
+function confExpand(raw) {
+  let out = "";
+  let i = 0;
+  if (raw.length !== 0 && raw[0] === "~" && (raw.length === 1 || raw[1] === "/")) {
+    out += getVar("HOME") || "";
+    i = 1;
+  }
+  while (i < raw.length) {
+    if (raw[i] === "\\" && raw[i + 1] === "$") {
+      out += "$";
+      i += 2;
+      continue;
+    }
+    if (raw[i] !== "$") {
+      out += raw[i];
+      i += 1;
+      continue;
+    }
+    const after = raw.slice(i + 1);
+    if (after[0] === "{") {
+      const close = after.indexOf("}");
+      if (close === -1) {
+        out += raw[i];
+        i += 1;
+        continue;
+      }
+      const name = after.slice(1, close);
+      if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+        out += raw[i];
+        i += 1;
+        continue;
+      }
+      out += getVar(name) || "";
+      i += 1 + close + 1;
+      continue;
+    }
+    const m = after.match(NAME_RE);
+    if (!m) {
+      out += raw[i];
+      i += 1;
+      continue;
+    }
+    out += getVar(m[0]) || "";
+    i += 1 + m[0].length;
+  }
+  return out;
+}
+
+// Mirrors core/conf.zig's `resolveExisting` (tiers 1-2 only -- this hook,
+// like the shell script it replaces, never falls back to the plugin's own
+// bundled template: that template's OBSIDIAN_VAULT_DIR is a placeholder
+// path, not a real vault, and silently trying it would be worse than doing
+// nothing).
+function resolveConfPath(name) {
+  const xdg = process.env.XDG_CONFIG_HOME;
+  const home = getVar("HOME");
+  const candidates = [];
+  if (xdg) candidates.push(path.join(xdg, "synapse", name));
+  if (home) candidates.push(path.join(home, ".config", "synapse", name));
+  if (home) candidates.push(path.join(home, ".claude", name));
+  for (const p of candidates) {
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+// Mirrors core/conf.zig's `vaultDir`: the env override first, then each
+// conf file name in turn (synapse.conf, then the pre-rename second-brain.conf
+// as a fallback), each resolved through the same tier order.
+function resolveVaultDir() {
+  const override = process.env.OBSIDIAN_VAULT_DIR;
+  if (override) return override;
+
+  for (const name of ["synapse.conf", "second-brain.conf"]) {
+    const confPath = resolveConfPath(name);
+    if (!confPath) continue;
+    let text;
+    try {
+      text = fs.readFileSync(confPath, "utf8");
+    } catch {
+      continue;
+    }
+    const raw = confGet(text, "OBSIDIAN_VAULT_DIR");
+    if (raw === null) continue;
+    const expanded = confExpand(raw);
+    if (expanded) return expanded;
+  }
+  return null;
+}
+
+// Same request curl -s --cacert ... --max-time 5 made: any HTTP response
+// (whatever the status) counts as reachable, matching curl's own default of
+// treating a completed request, not a 2xx, as success. Only a TLS/connection
+// failure or the timeout counts as unreachable.
+function endpointReachable(port, certPath) {
+  return new Promise((resolve) => {
+    let ca;
+    try {
+      ca = fs.readFileSync(certPath);
+    } catch {
+      resolve(false);
+      return;
+    }
+    const req = https.request(
+      { hostname: "127.0.0.1", port, path: "/", method: "GET", ca, timeout: 5000 },
+      (res) => {
+        res.resume();
+        resolve(true);
+      }
+    );
+    req.on("timeout", () => {
+      req.destroy();
+      resolve(false);
+    });
+    req.on("error", () => resolve(false));
+    req.end();
+  });
+}
+
+function updateSettingsCaCert(settingsPath, certPath) {
+  let settings = {};
+  try {
+    settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+  } catch {
+    // Missing file -> {} (matches the original always seeding one); invalid
+    // JSON in an existing file -> also {}, but written to a temp file and
+    // swapped in atomically below, same as jq's own "never touch the
+    // original until the replacement is known-good" behavior.
+  }
+  settings.env = settings.env || {};
+  settings.env.NODE_EXTRA_CA_CERTS = certPath;
+
+  const tmp = path.join(os.tmpdir(), `obsidian-mcp-refresh.${process.pid}.${Date.now()}`);
+  fs.writeFileSync(tmp, JSON.stringify(settings, null, 2) + "\n");
+  fs.renameSync(tmp, settingsPath);
+}
+
+// Registering means removing first -- `claude mcp add` will not overwrite an
+// existing name, and there is no atomic replace.
+function isRegistered() {
+  const res = spawnSync("claude", ["mcp", "get", "obsidian"], { stdio: "ignore" });
+  return !res.error && res.status === 0;
+}
+
+function main() {
+  if (!commandExists("claude")) return;
+
+  const vault = resolveVaultDir();
+  if (!vault || !fs.existsSync(vault)) return;
+
+  const pluginData = path.join(vault, ".obsidian", "plugins", "obsidian-local-rest-api", "data.json");
+  if (!fs.existsSync(pluginData)) return;
+
+  const home = os.homedir();
+  const certPath = path.join(home, ".claude", "obsidian-local-rest-api-ca.pem");
+
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(pluginData, "utf8"));
+  } catch {
+    return;
+  }
+
+  const apiKey = data.apiKey;
+  const port = data.port;
+  if (!apiKey || !port) return;
+  if (!data.crypto || typeof data.crypto.cert !== "string") return;
+
+  fs.mkdirSync(path.dirname(certPath), { recursive: true });
+  fs.writeFileSync(certPath, data.crypto.cert);
+
+  endpointReachable(port, certPath).then((endpointOk) => {
+    // Written unconditionally, before the registered/reachable check below --
+    // the cert path itself doesn't depend on whether the endpoint answers
+    // right now, so a session that never gets past the "leave it alone"
+    // branch still ends up with NODE_EXTRA_CA_CERTS pointing at the current
+    // cert.
+    const settingsPath = path.join(home, ".claude", "settings.json");
+    try {
+      updateSettingsCaCert(settingsPath, certPath);
+    } catch {
+      // Best-effort, matching the original: a failed settings.json update
+      // does not block anything below.
+    }
+
+    const registered = isRegistered();
+
+    // An existing registration that already works is, by definition, one
+    // that worked at some point; replacing it with one pointing at a port
+    // that does not currently answer trades something working for nothing,
+    // so leave it alone in that case rather than risk it.
+    if (!endpointOk && registered) {
+      process.stderr.write(
+        "synapse: obsidian MCP endpoint unreachable, left the existing registration in place\n"
+      );
+      return;
+    }
+
+    spawnSync("claude", ["mcp", "remove", "obsidian", "-s", "user"], { stdio: "ignore" });
+    spawnSync(
+      "claude",
+      [
+        "mcp",
+        "add",
+        "--transport",
+        "http",
+        "obsidian",
+        `https://127.0.0.1:${port}/mcp/`,
+        "--header",
+        `Authorization: Bearer ${apiKey}`,
+        "-s",
+        "user",
+      ],
+      { stdio: "ignore" }
+    );
+  });
+}
+
+if (require.main === module) main();
+
+module.exports = { confGet, confUnquote, confExpand, resolveConfPath, resolveVaultDir };

package/lib/resolve-binaries.cjs

@@ -0,0 +1,54 @@
+// Locates the compiled synapse/synapse-hook binaries for the current
+// platform -- shipped as a separate optionalDependency package
+// (@imunitic/synapse-{platform}-{arch}, mirroring esbuild/@rollup's own
+// split), not fetched at install time. npm's own `os`/`cpu` package.json
+// fields make `npm install` skip every platform package but the matching
+// one, and registry shasum verification already covers integrity, so
+// there's no fetch/SHA256SUMS/timeout logic to hand-roll here at all --
+// this module only ever reads what npm already put on disk.
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const CLI_NAME = "synapse";
+const HOOK_NAME = "synapse-hook";
+
+// Matches process.platform/process.arch directly (not a Zig target triple)
+// since that's what npm's own `os`/`cpu` fields select against -- the
+// release pipeline maps its Zig target names to this naming once, at
+// publish time, not here.
+function platformPackageName() {
+  return `@imunitic/synapse-${process.platform}-${process.arch}`;
+}
+
+// Goes through node's own module resolution -- works whether the platform
+// package landed as a normal npm dependency, a workspace symlink, or a
+// `file:` link for local testing, rather than assuming a node_modules
+// layout this shouldn't hardcode.
+function resolveBinDir() {
+  try {
+    const pkgJsonPath = require.resolve(`${platformPackageName()}/package.json`);
+    return path.join(path.dirname(pkgJsonPath), "bin");
+  } catch {
+    return null;
+  }
+}
+
+function resolvedPath(name) {
+  const binDir = resolveBinDir();
+  if (!binDir) return null;
+  const file = path.join(binDir, name);
+  return fs.existsSync(file) ? file : null;
+}
+
+function cliPath() {
+  return resolvedPath(CLI_NAME);
+}
+
+function hookPath() {
+  return resolvedPath(HOOK_NAME);
+}
+
+module.exports = { platformPackageName, resolveBinDir, cliPath, hookPath, CLI_NAME, HOOK_NAME };

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@imunitic/synapse",
+  "version": "0.0.1-test.0",
+  "description": "Memory for Claude Code, Codex CLI, and OpenCode: a durable Obsidian vault plus a per-repo code graph.",
+  "bin": {
+    "synapse-setup": "bin/synapse-setup.cjs",
+    "synapse": "bin/synapse.cjs",
+    "synapse-hook": "bin/synapse-hook.cjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "skills",
+    "commands",
+    "harness",
+    "synapse-claude.md",
+    "Index.md.template",
+    "*.conf.template"
+  ],
+  "optionalDependencies": {
+    "@imunitic/synapse-darwin-arm64": "0.0.1-test.0",
+    "@imunitic/synapse-linux-x64": "0.0.1-test.0",
+    "@imunitic/synapse-linux-arm64": "0.0.1-test.0"
+  },
+  "license": "SEE LICENSE IN LICENSE"
+}

package/skills/synapse-node/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: synapse-node
+description: Tier 2 staleness check and lazy regeneration for a Synapse code-graph node, run whenever a node's body is about to be read and used — not a hook, a procedure Claude follows itself.
+---
+
+# Synapse Node Read: Staleness Check, Regeneration, Unassigned Sweep
+
+Built by `/synapse-init`, kept flagged stale at edit time by the `PostToolUse`
+hook (`synapse-hook staleness`, Tier 1). This skill is Tier 2 — the authoritative, lazy check that
+fires only when a node's content is actually about to be consumed, never on a schedule and never
+speculatively.
+
+## When to invoke (proactive — do not wait to be asked)
+
+Whenever a `synapse/{project}/{Node}.md` file is about to be read **for its content to actually be
+used** (orienting on a subsystem, answering a question about it, deciding where to make a change)
+— not for a `vault_list`/title-only skim. Run this procedure *before* trusting what comes back from
+that read. This is the one Synapse mechanism that isn't a hook: a hook is compiled code with no
+reasoning, and classifying whether a file "fits" a node is exactly the kind of judgment call that
+needs one.
+
+## Procedure
+
+1. **Verify the whole project once, with the script.** Run `~/.synapse query stale` from
+   inside the repo. It prints one `{node title}\t{reason}` line per stale node and nothing at all
+   when everything is current, so its output is the complete stale set for the project.
+
+   Do this **once** per orienting task, not once per node: it costs a single `git hash-object` fork
+   plus one GET per node (a couple of seconds for a few dozen nodes), and covers every node at once. Re-run only
+   after source files have actually changed since the last run.
+
+   Never do this by hand instead. Recomputing a digest needs the node's path list, and both places
+   it lives are ruinous to read into context — a hub node's own `sources` runs to ~38k tokens and
+   the index is binary and tens of megabytes. The script exists so the only thing reaching a context window is the list
+   of stale titles.
+
+   **Exit 1 means "no information", not "clean."** It signals a missing dependency, no vault, no
+   namespace for this repo, or a `remote:` mismatch. Do not treat that as a passing verification —
+   either fix the cause or proceed knowing the graph is unverified, and say which.
+
+2. **Also honour the Tier 1 flag.** `rg -m1 '^stale:' "$OBSIDIAN_VAULT_DIR/synapse/{project}/{Node}.md"`
+   — one line, negligible cost. The two tiers catch different things: Tier 1 flags edits made through
+   this Claude Code session the moment they happen, the script catches everything including changes
+   the hook never saw (`git pull`, branch switch, rebase, an IDE edit). **Either one saying stale
+   means stale.** A node named by neither is fresh — use its content as-is and skip Regeneration and
+   the sweep, which only ride along when some regeneration actually occurs.
+3. **Read the node's body, never the whole file.** `sources` is exhaustive — every file the node
+   covers, each with a hash — so a hub node's frontmatter alone can run to ~38k tokens while its
+   actual prose is under 1k. Consultation never needs `sources`; the script handles verification.
+   So skip the frontmatter entirely:
+
+   ```sh
+   ~/.synapse query body "{Node title}"
+   ```
+
+   That prints only what is between the generated fences — so it excludes `## Notes` as well as the
+   frontmatter, which a raw offset read would not — and costs ~500 tokens whether the node covers 5
+   files or 941. **A full `mcp__obsidian__vault_read`
+   of a hub node is a mistake, not merely expensive** — it spends tens of thousands of tokens on a
+   path list you are not going to use. Use `vault_read` only when you specifically need the
+   frontmatter or the links/backlinks metadata it returns.
+
+   Finding *which* node to read is a separate job, and search does it: because `sources` is
+   exhaustive, `mcp__obsidian__search_simple` on a class or file name locates the owning node even
+   when that name appears nowhere in any node's prose, and returns snippets rather than whole files.
+
+   For the other questions about a node, use the same tool rather than reading frontmatter:
+   `synapse query sources "{Node}" --count|--modules|--filter <p>` for what it covers, and
+   `synapse query field "{Node}" <key>` for a single scalar such as `stale` or `built_at`.
+
+4. **Regeneration (only if step 1 or 2 found the node stale).** You re-author the prose; a script
+   writes the file. **The node contract itself — frontmatter fields, the crux pointer, `## Links`,
+   `grounded_in` — is the `synapse-node-format` skill**, shared with `/synapse-init` and
+   `/synapse-rebuild`. What follows here is only what differs when *re*-authoring an existing
+   node rather than writing a new one. Everything mechanical — hashes, `sources_digest`, the `## Sources` mirror,
+   `built_at`, `commit`, `stale: false`, and preserving `## Notes` — belongs to
+   `synapse write-node`, because a hub node's `sources` can no more be *emitted* into a tool call
+   than read into a window. Let `$W` be the project's work directory,
+   `~/.claude/synapse-work/{repo}@{branch}/`.
+
+   - **Get the node's path list into a file, never into context:**
+
+     ```sh
+     ~/.synapse query sources "{Node title}" > "$W/paths.txt"
+     ```
+
+     If `$W/manifest.tsv` exists (or the namespace has `_manifest.tsv`), prefer re-running
+     `~/.synapse build-lists` instead and use the regenerated `lists/NN.txt`: it
+     re-derives every list from the clustering patterns, so files *added* since the last build are
+     picked up automatically rather than sitting in `_unassigned`. `synapse query sources` can only
+     return what the node already claims.
+   - Consult `synapse/{project}/_profile.txt` if it exists — the aggregations that proved useful for
+     this repo, and the negative results (searches that came back empty) worth not re-deriving.
+   - **Prefer patching the prose from the diff over re-reading the node's sources.** If the node has a
+     `commit` and only a small fraction of its files changed, read the current prose
+     (`synapse query body`), get `git diff --name-status -M <commit>..HEAD` for its paths, and read
+     hunks only for a bounded selection — always including `crux_path`, the file the crux was cut from.
+     Amend the sentences the diff contradicts and keep the rest verbatim. A node covering 15,000 files
+     where 12
+     changed already has prose encoding the other 14,988, and re-reading them all both costs enormously
+     and discards findings the diff has nothing to say about. Project the diff as carefully as
+     `sources`: names first, `--stat` to size it, hunks only for the selection.
+   - Fall back to reading the files when patching cannot be justified — a large fraction changed, the
+     `crux` file is gone, or the baseline is unusable. Then try `~/.synapse tags {path}`
+     first (exit 0 use the tags, exit 1 fall back to reading the file, exit 2 run the discovery
+     procedure `/synapse-init` documents, then retry), and read the load-bearing files in full — the
+     tags signal informs regrouping, it never substitutes for reading a file before rewriting its prose.
+     If this is happening across many nodes at once, stop and run `/synapse-rebuild` instead: that is
+     the instrument for major drift, and it triages node by node rather than paying full cost for each.
+   - Re-author `## Summary`, `## Crux` and `## Links` to match what the files contain now, into
+     `$W/body.md`. Re-check the node's one-line `summary` as well; keep the existing one with
+     `synapse query field "{Node title}" summary` if it still fits.
+   - **`## Crux` goes back as a directive, never as the code you just read.** `synapse query body`
+     returns the *expanded* crux — the fenced block the writer sliced last time — so copying it forward
+     stores a quote of an older version of the file as though it were current. Emit
+     `<!-- crux: <path> <start>-<end> -->` and let the writer cut it out again. Reuse the recorded
+     pointer (`synapse query field "{Node}" crux_path` and `crux_lines`) when that file did not
+     change; pick a fresh span when it did, because the old line numbers may now land somewhere else.
+     `<!-- crux: none -->` if nothing focal remains — and a node with no `crux_path` had none already.
+   - **Re-emit the groundings, or they are lost.** `grounded_in` lives in frontmatter and the writer
+     strips its directives from the body, so a recovered body carries none of them: writing it back
+     without re-emitting drops the node's whole provenance silently. Recover the pointers with
+     `synapse query grounding "{Node}" --list` (prints `path<TAB>lines`) and put a
+     `<!-- grounded_in: <path> <lines> -->` back for each. Run `synapse query grounding` first: a
+     `moved` line gives you the corrected range to use, and a `changed` line marks evidence that no
+     longer says what the summary claims — re-point that one, and fix the sentence resting on it.
+   - **Write it back with the script:**
+
+     ```sh
+     ~/.synapse write-node --title "{Node title}" --summary "{one line}" \
+        --paths "$W/paths.txt" --body "$W/body.md"
+     ```
+
+     It replaces only the generated region and re-emits everything after the closing fence verbatim,
+     which is what makes the `## Notes` guarantee enforceable rather than a promise.
+   - **Never hand-write the frontmatter**, with `vault_patch` at `targetType: frontmatter` or
+     otherwise. Two reasons, both load-bearing: that patch re-serialises the whole YAML block and
+     YAML-coerces values (an all-digit `hash` becomes `1.1111111111111112e+39`), and
+     enumerating fields by hand is how `summary` and `commit` get silently dropped — which then breaks
+     the next `synapse build-project-index` run, far from the cause.
+   - **`## Notes` is human-authored only.** Never write into it — not at regeneration, not to record
+     what you just did. (Task notes in `tasks/` are a different artifact: the `synapse-task` skill *does*
+     append there. Do not carry that habit into a Synapse node.)
+   - If the node's `summary` or title changed, rebuild the index so the map matches:
+     `~/.synapse build-project-index`.
+   - **Say out loud that a regeneration happened** — e.g. "Node '{title}' was stale, regenerated
+     before use." This has real latency and token cost, unlike Tier 1/2's detection; it must never
+     be absorbed silently into the read.
+5. **Unassigned sweep (rides along on step 4, whenever any regeneration fires for this project):**
+   - Read the bucket with a shell command, not into context — the index runs to tens of megabytes:
+
+     ```sh
+     ~/.synapse index unassigned
+     ```
+
+     Empty → nothing to do, skip silently (an empty sweep isn't worth announcing).
+   - Otherwise read `synapse/{project}/Index.md` for the current node list (titles + summaries).
+   - Tag the whole bucket in **one** call — write the paths to a list and run
+     `~/.synapse tags --paths {list}`, whose output is attributable (an unindented
+     line is a path, the tab-indented lines under it are its tags). A per-file loop costs ~33× more
+     for the same answer. Fall back to a full read for ambiguous cases, then classify against that
+     node list. **The judgment is which cluster a path belongs to; the bookkeeping is not yours to
+     do:**
+     - **Fits an existing node** → widen that node's line in `$W/manifest.tsv` so the pattern claims
+       it, then re-run `synapse build-lists`. Set that node's `stale: true` for its own next read
+       rather than regenerating it now — only the node that triggered step 4 is regenerated
+       immediately. If there is no manifest, add the path to that node's list file instead.
+     - **Fits nothing** → leave it unassigned. A genuinely new subsystem wants its own manifest line
+       and its own node, which is `/synapse-init` work, not a sweep.
+     - Then rebuild the projection with `~/.synapse build-index`. **Never hand-edit
+       `_index.bin`** — it is derived, binary, and tens of megabytes; there is nothing to
+       hand-edit.
+   - **Announce every outcome**, same transparency rule as regeneration: which file, and which
+     node it was attached to (or that it's still unassigned).
+   - Sweep the **whole** bucket unconditionally, not just entries related to the node that
+     triggered step 4 — an unrelated new subsystem rides along on any regeneration event
+     happening anywhere in the project, by design (see the design note's Node Granularity &
+     Grouping section).
+
+## Guardrails
+
+- `stale` is the right check for *this* procedure, but know what it cannot tell you: a file in no
+  node's `sources` is invisible to it, and a renamed file reads as "gone". `synapse query drift`
+  answers both, by diffing each node's recorded `commit` against HEAD. It is not on this hot path on
+  purpose — reading one node's body should not pay for a repo-wide coverage audit — so reach for it
+  when orienting after a `git pull` or a branch switch, and leave the systematic case to a deliberate
+  refresh rather than a read.
+- Never skip `synapse query stale` just because `stale: false` looked plausible — Tier 1 only catches
+  edits made through this Claude Code session; a `git pull`, branch switch, or externally-made
+  edit is invisible to it and only the script catches those.
+- Never hand-roll the verification by reading `sources` or the index — that is the whole reason
+  the script exists, and doing it manually costs tens to hundreds of thousands of tokens.
+- Never hand-write a node's frontmatter or `## Sources` mirror. `synapse write-node` owns them, and
+  writing them by hand both cannot scale to a hub node and silently drops `summary`/`commit`.
+- Never treat the script's exit 1 as a clean result. It means the check could not run.
+- Never regenerate a node that neither the script nor its `stale:` flag named — regeneration is real
+  cost, reserved for actual staleness.
+- Never `vault_read` a hub node just to read its summary. Offset past the frontmatter (step 3).
+- Never silently fold a regeneration or an unassigned-file attachment into normal output — both
+  get an explicit, visible announcement line.
+- `## Notes` content is sacrosanct across regeneration — if a rewrite would touch it, that's a bug
+  in the regeneration step, not an acceptable side effect.
+
+## Fallback if regeneration proves disruptive
+
+If lazy per-read regeneration turns out to be too disruptive in practice (e.g. a single task
+orienting against several stale nodes at once, each paying a regeneration cost), the documented
+fallback (see the design note's Alternatives) is to downgrade staleness to a plain cache miss:
+skip the stale node's content entirely and read its underlying source files directly instead,
+leaving regeneration to a manual step. This is a deliberate escape hatch, not the default — only
+switch to it if the default is causing real friction, and say so if you do.