@imunitic/synapse 0.2.2 → 0.2.4

package/Index.md.template

@@ -3,7 +3,7 @@ title: "Index"
 ---
 
 # Index
-Map of the note folders and what each is for. This is the Obsidian second-brain vault, queried via the Local REST API plugin (see the Synapse repo's `CLAUDE.md`).
+Map of the note folders and what each is for. This is the Obsidian second-brain vault, reached through the `synapse` CLI (see the Synapse repo's `CLAUDE.md`).
 
 This index is agent-maintained: whenever an agent creates a new top-level folder (folder depth is capped at two levels, i.e. `folder/subfolder`), it must add a one-line section for it here in the same edit. Treat this file as out of date if a folder exists on disk with no matching section below -- fix the drift rather than working around it.
 

package/bin/synapse-setup.cjs

@@ -17,7 +17,6 @@
 const fs = require("fs");
 const os = require("os");
 const path = require("path");
-const { execFileSync } = require("child_process");
 const { hookPath, platformPackageName, HOOK_NAME } = require("../lib/resolve-binaries.cjs");
 
 const PKG_ROOT = path.join(__dirname, "..");
@@ -56,28 +55,40 @@ function resolveHookBin() {
 }
 
 function configure(harness) {
+  bootstrapSynapseConf();
   if (harness === "claude") return configureClaude();
   if (harness === "codex") return configureCodex();
   if (harness === "opencode") return configureOpencode();
 }
 
 // ---------------------------------------------------------------------------
-// Shared: vault/Obsidian plugin data, skill/command copies, JSON merge helpers
+// Shared: synapse.conf bootstrap, skill/command copies, JSON merge helpers
 // ---------------------------------------------------------------------------
 
-function readObsidianPluginData() {
-  const { resolveVaultDir } = require("../lib/obsidian-mcp-refresh.cjs");
-  const vault = resolveVaultDir();
-  if (!vault || !fs.existsSync(vault)) {
-    fail("no SYNAPSE_VAULT_DIR resolvable (see synapse.conf) -- can't configure the obsidian MCP connection");
-  }
-  const pluginDataPath = path.join(vault, ".obsidian", "plugins", "obsidian-local-rest-api", "data.json");
-  if (!fs.existsSync(pluginDataPath)) {
-    fail(`${pluginDataPath} not found -- install/enable the Local REST API plugin in Obsidian first`);
-  }
-  const data = JSON.parse(fs.readFileSync(pluginDataPath, "utf8"));
-  if (!data.apiKey) fail(`${pluginDataPath} has no apiKey`);
-  return data;
+// Mirrors `core.conf.resolveConfPath`/`resolveWritePath`'s own three-tier
+// order for `synapse.conf` specifically (see `docs/synapse/synapse-config.md`
+// "Where a conf file actually lives"), so a fresh machine gets a real file to
+// edit instead of a silent gap the next `SessionStart` hook has to explain.
+// A no-op once any tier already has a file -- re-running `configure` never
+// overwrites an existing choice, deliberate or inherited.
+function bootstrapSynapseConf() {
+  const home = os.homedir();
+  const xdg = process.env.XDG_CONFIG_HOME;
+  const candidates = [];
+  if (xdg) candidates.push(path.join(xdg, "synapse", "synapse.conf"));
+  candidates.push(path.join(home, ".config", "synapse", "synapse.conf"));
+  candidates.push(path.join(home, ".claude", "synapse.conf"));
+  if (candidates.some((p) => fs.existsSync(p))) return;
+
+  let dest;
+  if (xdg) dest = path.join(xdg, "synapse", "synapse.conf");
+  else if (fs.existsSync(path.join(home, ".config")) && fs.statSync(path.join(home, ".config")).isDirectory())
+    dest = path.join(home, ".config", "synapse", "synapse.conf");
+  else dest = path.join(home, ".claude", "synapse.conf");
+
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(path.join(PKG_ROOT, "synapse.conf.template"), dest);
+  console.log(`wrote ${dest} -- edit SYNAPSE_VAULT_DIR in it before your next session`);
 }
 
 // The manifest recording exactly which names this tool wrote into a given
@@ -110,14 +121,13 @@ function pruneStale(destRoot, currentNames) {
   fs.writeFileSync(manifestPath, JSON.stringify(currentNames, null, 2) + "\n");
 }
 
-// Copies every shared SKILL.md into `destRoot/{name}/SKILL.md`, verbatim
-// unless `transform` is given. Each skill gets its own uniquely-named
-// subdirectory, so overwriting ours on every run never touches anything a
-// harness's own skill discovery also finds there under a different name.
-// Returns the names written -- pruning stale ones is the caller's job,
-// since a destRoot shared with another source (Codex's own skills, on top
-// of these) needs the combined set before it can prune safely.
-function copySkills(destRoot, transform) {
+// Copies every shared SKILL.md into `destRoot/{name}/SKILL.md`. Each skill
+// gets its own uniquely-named subdirectory, so overwriting ours on every run
+// never touches anything a harness's own skill discovery also finds there
+// under a different name. Returns the names written -- pruning stale ones is
+// the caller's job, since a destRoot shared with another source (Codex's own
+// skills, on top of these) needs the combined set before it can prune safely.
+function copySkills(destRoot) {
   const src = path.join(PKG_ROOT, "skills");
   const names = fs
     .readdirSync(src, { withFileTypes: true })
@@ -127,32 +137,21 @@ function copySkills(destRoot, transform) {
   for (const name of names) {
     const destDir = path.join(destRoot, name);
     fs.mkdirSync(destDir, { recursive: true });
-    writeMaybeTransformed(path.join(src, name, "SKILL.md"), path.join(destDir, "SKILL.md"), transform);
+    fs.copyFileSync(path.join(src, name, "SKILL.md"), path.join(destDir, "SKILL.md"));
   }
   return names;
 }
 
-function copyCommands(destRoot, transform) {
+function copyCommands(destRoot) {
   const src = path.join(PKG_ROOT, "commands");
   const names = fs.readdirSync(src).filter((f) => f.endsWith(".md"));
   fs.mkdirSync(destRoot, { recursive: true });
   for (const name of names) {
-    writeMaybeTransformed(path.join(src, name), path.join(destRoot, name), transform);
+    fs.copyFileSync(path.join(src, name), path.join(destRoot, name));
   }
   return names;
 }
 
-function writeMaybeTransformed(srcPath, destPath, transform) {
-  const text = fs.readFileSync(srcPath, "utf8");
-  fs.writeFileSync(destPath, transform ? transform(text) : text);
-}
-
-// `\w+` catches a real tool name (mcp__obsidian__vault_read); `\*` catches
-// prose referring to the whole family (mcp__obsidian__*).
-function opencodeToolNameTransform(text) {
-  return text.replace(/mcp__obsidian__(\w+|\*)/g, "obsidian_$1");
-}
-
 function backupIfExists(filePath) {
   if (!fs.existsSync(filePath)) return;
   fs.copyFileSync(filePath, `${filePath}.bak`);
@@ -201,12 +200,11 @@ function mergeHooksInto(existingHooks, rendered, hookBin) {
 // install: `~/.claude/skills/{name}/SKILL.md` and `~/.claude/commands/
 // {name}.md` are both read with no plugin involved (a probe skill dropped
 // directly into the global skills dir showed up in a fresh `claude -p`
-// session's own skill listing). Commands need no transform either: they were
-// authored for Claude Code in the first place, so the copy is the identity
-// function. `~/.claude/settings.json`'s own `hooks`/`env` keys are the same
-// mechanism the retired setup.sh (pre-plugin Synapse) already used, and the
-// same one NanoNets/Graft uses for its own Claude Code integration -- this
-// harness is not doing anything Claude Code doesn't already support natively.
+// session's own skill listing). `~/.claude/settings.json`'s own `hooks`/`env`
+// keys are the same mechanism the retired setup.sh (pre-plugin Synapse)
+// already used, and the same one NanoNets/Graft uses for its own Claude Code
+// integration -- this harness is not doing anything Claude Code doesn't
+// already support natively.
 function configureClaude() {
   const hookBin = resolveHookBin();
 
@@ -231,26 +229,6 @@ function configureClaude() {
   const rendered = renderHooksTemplate(path.join(PKG_ROOT, "harness", "claude", "hooks.json"), hookBin);
   settings.hooks = mergeHooksInto(settings.hooks, rendered, hookBin);
 
-  // Keeps the obsidian MCP registration current automatically, every
-  // session -- the same job plugins/synapse/hooks/obsidian-mcp-refresh.cjs
-  // did as a plugin-era SessionStart hook. Merged the same way as the
-  // templated hooks above (dedup key = the exact resolved command), just
-  // not sourced from harness/claude/hooks.json since its path needs no
-  // per-platform hookBin substitution -- it's always PKG_ROOT-relative.
-  const refreshCmd = `node ${path.join(PKG_ROOT, "lib", "obsidian-mcp-refresh.cjs")}`;
-  const refreshHooks = { hooks: { SessionStart: [{ hooks: [{ type: "command", command: refreshCmd }] }] } };
-  settings.hooks = mergeHooksInto(settings.hooks, refreshHooks, refreshCmd);
-
-  const pluginData = readObsidianPluginData();
-  if (!pluginData.crypto || typeof pluginData.crypto.cert !== "string") {
-    fail("Local REST API's data.json has no crypto.cert -- can't set up the HTTPS trust Claude Code needs");
-  }
-  const certPath = path.join(os.homedir(), ".claude", "obsidian-local-rest-api-ca.pem");
-  fs.mkdirSync(path.dirname(certPath), { recursive: true });
-  fs.writeFileSync(certPath, pluginData.crypto.cert);
-  settings.env = settings.env || {};
-  settings.env.NODE_EXTRA_CA_CERTS = certPath;
-
   // The npm-install counterpart to $CLAUDE_PLUGIN_ROOT -- conf.zig's own
   // resolveConfPath and session_start.zig's synapse-claude.md/Index.md.template
   // lookups both check this env var now that there's no plugin marketplace
@@ -258,42 +236,15 @@ function configureClaude() {
   // relative shape CLAUDE_PLUGIN_ROOT used to point at plugins/synapse/ --
   // synapse-claude.md, Index.md.template, and every *.conf.template sit
   // directly under it.
+  settings.env = settings.env || {};
   settings.env.SYNAPSE_CONTENT_ROOT = PKG_ROOT;
 
   backupIfExists(settingsPath);
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
   console.log(`configured ${settingsPath}`);
-  console.log(`wrote ${certPath}`);
-
-  // Claude Code already has a working HTTPS cert-trust story (unlike
-  // Codex/OpenCode), so this registers against the real endpoint directly --
-  // no plain-HTTP fallback needed here. Registering means removing first --
-  // `claude mcp add` will not overwrite an existing name.
-  try {
-    execFileSync("claude", ["mcp", "remove", "obsidian", "-s", "user"], { stdio: "ignore" });
-  } catch {
-    // Fine if it wasn't registered yet.
-  }
-  execFileSync(
-    "claude",
-    [
-      "mcp",
-      "add",
-      "--transport",
-      "http",
-      "obsidian",
-      `https://127.0.0.1:${pluginData.port}/mcp/`,
-      "--header",
-      `Authorization: Bearer ${pluginData.apiKey}`,
-      "-s",
-      "user",
-    ],
-    { stdio: "ignore" }
-  );
-  console.log("registered the obsidian MCP server");
   console.log("");
-  console.log("No manual steps -- restart Claude Code so the new hooks/settings/MCP");
-  console.log("registration take effect for the running session.");
+  console.log("No manual steps -- restart Claude Code so the new hooks/settings take effect");
+  console.log("for the running session.");
 }
 
 // ---------------------------------------------------------------------------
@@ -333,54 +284,9 @@ function configureCodex() {
   pruneStale(skillsDestRoot, [...sharedNames, ...codexNames]);
   console.log(`installed ${sharedNames.length + codexNames.length} skills to ${skillsDestRoot}`);
 
-  const pluginData = readObsidianPluginData();
-  if (!pluginData.enableInsecureServer || !pluginData.insecurePort) {
-    fail(
-      "Local REST API's plain-HTTP server is off -- Codex can't trust its self-signed HTTPS cert " +
-        "(no per-server cert field in config.toml). Enable it: Obsidian Settings -> " +
-        "Local REST API -> Enable HTTP server, then re-run this command."
-    );
-  }
-  const tokenEnvVar = "SYNAPSE_OBSIDIAN_API_KEY";
-  mergeCodexConfigToml(path.join(os.homedir(), ".codex", "config.toml"), pluginData.insecurePort, tokenEnvVar);
-  console.log(`configured ${path.join(os.homedir(), ".codex", "config.toml")}`);
-
-  console.log("");
-  console.log("One manual step -- Codex reads the vault API key from an env var by name,");
-  console.log("not from config.toml. Add this to your shell profile, then restart your terminal:");
-  console.log("");
-  console.log(`  export ${tokenEnvVar}="${pluginData.apiKey}"`);
   console.log("");
-  console.log("The next real `codex` session will prompt to trust the hooks this just wrote --");
-  console.log("approve it interactively.");
-}
-
-const CODEX_TOML_BEGIN = "# >>> synapse: obsidian MCP (managed by synapse-setup configure codex) >>>";
-const CODEX_TOML_END = "# <<< synapse <<<";
-
-function mergeCodexConfigToml(configTomlPath, insecurePort, tokenEnvVar) {
-  const block = [
-    CODEX_TOML_BEGIN,
-    "[mcp_servers.obsidian]",
-    `url = "http://127.0.0.1:${insecurePort}/mcp/"`,
-    `bearer_token_env_var = "${tokenEnvVar}"`,
-    CODEX_TOML_END,
-  ].join("\n");
-
-  let text = "";
-  if (fs.existsSync(configTomlPath)) text = fs.readFileSync(configTomlPath, "utf8");
-  const beginIdx = text.indexOf(CODEX_TOML_BEGIN);
-  const endIdx = text.indexOf(CODEX_TOML_END);
-  let next;
-  if (beginIdx !== -1 && endIdx !== -1 && endIdx > beginIdx) {
-    next = text.slice(0, beginIdx) + block + text.slice(endIdx + CODEX_TOML_END.length);
-  } else {
-    const sep = text.length === 0 || text.endsWith("\n\n") ? "" : text.endsWith("\n") ? "\n" : "\n\n";
-    next = text + sep + block + "\n";
-  }
-  fs.mkdirSync(path.dirname(configTomlPath), { recursive: true });
-  backupIfExists(configTomlPath);
-  fs.writeFileSync(configTomlPath, next);
+  console.log("No manual steps -- the next real `codex` session will prompt to trust the");
+  console.log("hooks this just wrote, approve it interactively.");
 }
 
 // ---------------------------------------------------------------------------
@@ -404,56 +310,18 @@ function configureOpencode() {
   console.log(`installed ${pluginDest}`);
 
   const skillsDest = path.join(os.homedir(), ".config", "opencode", "skill");
-  const skillNames = copySkills(skillsDest, opencodeToolNameTransform);
+  const skillNames = copySkills(skillsDest);
   pruneStale(skillsDest, skillNames);
   const commandsDest = path.join(os.homedir(), ".config", "opencode", "command");
-  const commandNames = copyCommands(commandsDest, opencodeToolNameTransform);
+  const commandNames = copyCommands(commandsDest);
   pruneStale(commandsDest, commandNames);
   console.log(`installed ${skillNames.length} skills, ${commandNames.length} commands to ~/.config/opencode`);
 
-  const pluginData = readObsidianPluginData();
-  if (!pluginData.enableInsecureServer || !pluginData.insecurePort) {
-    fail(
-      "Local REST API's plain-HTTP server is off -- OpenCode's mcp.obsidian schema has no per-server " +
-        "cert/TLS field either. Enable it: Obsidian Settings -> Local REST API -> Enable HTTP server, " +
-        "then re-run this command."
-    );
-  }
-  const configPath = path.join(os.homedir(), ".config", "opencode", "opencode.jsonc");
-  mergeOpencodeMcp(configPath, pluginData.insecurePort, pluginData.apiKey);
-  console.log(`configured ${configPath}`);
-
   console.log("");
   console.log("No manual steps -- the plugin resolves its synapse-hook binary from the shared");
   console.log(`install location (${hookBin}) automatically.`);
 }
 
-function mergeOpencodeMcp(configPath, insecurePort, apiKey) {
-  let config = {};
-  if (fs.existsSync(configPath)) {
-    const raw = fs.readFileSync(configPath, "utf8");
-    try {
-      config = JSON.parse(raw);
-    } catch (err) {
-      fail(
-        `${configPath} isn't plain JSON (${err.message}) -- can't safely merge into a commented .jsonc ` +
-          `file without risking losing the comments. Add this entry by hand instead: ` +
-          `mcp.obsidian: {"type":"remote","url":"http://127.0.0.1:${insecurePort}/mcp/",` +
-          `"headers":{"Authorization":"Bearer <the vault's apiKey>"}}`
-      );
-    }
-  }
-  config.mcp = config.mcp || {};
-  config.mcp.obsidian = {
-    type: "remote",
-    url: `http://127.0.0.1:${insecurePort}/mcp/`,
-    headers: { Authorization: `Bearer ${apiKey}` },
-  };
-  fs.mkdirSync(path.dirname(configPath), { recursive: true });
-  backupIfExists(configPath);
-  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
-}
-
 function fail(message) {
   console.error(`synapse-setup: ${message}`);
   process.exit(1);

package/commands/synapse-init.md

@@ -238,7 +238,7 @@ emit into tool calls than read into a window. Never hand-author those.
    **Do not choose which files to read by judgment, and do not decide how the writing itself
    happens by habit.** Both are decided by the `synapse-node-authoring` skill — **load it
    before writing the first node.** It resolves `SYNAPSE_AUTHOR_POOL` (env var, then
-   `~/.claude/synapse.conf`, default 0) and either walks you through authoring every node
+   `synapse.conf`, default 0) and either walks you through authoring every node
    yourself in one continuous pass (`rank --sources` per node, `## Links` candidates from
    step 6's `links.tsv`, reading order only — `sources` stays exhaustive either way), or fans
    out to a configurable pool of concurrent subagents, each handed a self-contained

package/commands/synapse-vault-tidy.md

@@ -28,17 +28,18 @@ of scope — foundational files, not taxonomy notes.
 
 ## Prerequisites
 
-Requires the `obsidian` MCP server (`mcp__obsidian__*` tools). If unreachable, say so and stop —
-there is no local-file fallback.
-
-No compiled code anywhere in this command. `adapters/obsidian/store.zig`'s `ObsidianStore` does now
-implement `read`/`list`/`search`, but for `synapse frontmatter get`/`set`'s narrow one-field-at-a-time
-use — a full-vault tidy sweep, reading every note's whole body to judge category, tags and broken
-links, is a different shape of work entirely, and stays on these same MCP tools rather than the
-compiled binary, the same way `/synapse-status` and `/synapse-rebuild-diff`'s vault-side checks
-already work. The one exception is Step 3's broken-link history check, a plain `git log` call (via
-Bash, not a compiled tool) against the vault's own local repo when one exists — best-effort, never
-a hard requirement.
+Requires the `synapse` CLI on `PATH`, resolving a vault with a working `LinkGraph`
+(`synapse vault-backlinks`/`vault-links`/`vault-unresolved`/`vault-orphans`/`vault-deadends` — see
+`sb — Obsidian CLI as ObsidianStore's transport`). If `SYNAPSE_VAULT_STORE` resolves to a backend
+with no `LinkGraph` yet, these commands exit 1 saying so; stop and report that rather than falling
+back to anything else.
+
+This command reaches the vault store only through the `synapse` CLI's `vault-*` subcommands, the
+same door every other skill uses — no MCP tool, no direct `ObsidianStore` call. `vault-links`/
+`vault-backlinks` each answer for one note at a time, so Step 1's inventory sweep runs one pair per
+note in scope: `2N` process spawns for an `N`-note vault. Acceptable for an on-demand, rare command.
+Step 3's broken-link history check is a plain `git log` call (via Bash, not a compiled tool)
+against the vault's own local repo when one exists — best-effort, never a hard requirement.
 
 ## Step 1: Inventory sweep
 
@@ -55,12 +56,23 @@ sweep rather than re-reading anything.
 ]}
 ```
 
-`mcp__obsidian__search_query` with that filter, then `mcp__obsidian__vault_read` each match. Keep
-the full result (`path`, `frontmatter`, `tags`, `links`, `backlinks`, `unresolvedLinks`, `stat`,
-`content`) per note — Steps 2–4 below only ever reason over the structured fields, never `content`
-itself; the judgment layer in Step 5 is the first point anything actually reads note *bodies*, and
-only for the subset flagged by then. `content` is fetched for free in this same call regardless, so
-there's no separate "light" read to bother with.
+`synapse vault-search --fields frontmatter,tags,content` with that filter on stdin gives `path`,
+`frontmatter`, `tags`, `content` per matching note in one pass (`stat`'s `ctime`/`mtime` aren't a
+`vault-search` field — see the note below). Also run `synapse vault-orphans`, `synapse
+vault-deadends`, and `synapse vault-unresolved` once each, vault-wide — three cheap bulk calls that
+Step 3 cross-references by path rather than recomputing per note. For each note in scope, also run
+`synapse vault-backlinks <path>` and `synapse vault-links <path>` and keep the results alongside it
+— this is the `2N` cost named in Prerequisites, needed only for Step 4's weak-folder-fit signal
+(which folder a note's actual link targets fall in, not just whether it has any). Keep the full
+assembled result (`path`, `frontmatter`, `tags`, `content`, `links`, `backlinks`) per note — Steps
+2–4 below only ever reason over the structured fields, never `content` itself; the judgment layer in
+Step 5 is the first point anything actually reads note *bodies*, and only for the subset flagged by
+then.
+
+`stat.ctime`/`stat.mtime` (Step 2's `created` default, Step 4's stale-category check) have no
+`vault-search` equivalent — read a note's mtime directly off disk (`SYNAPSE_VAULT_DIR`-resolved
+path) with a plain `stat` via Bash when either step needs it, same file the vault store itself
+already addresses.
 
 ## Step 2: Frontmatter defaults (fixed directly)
 
@@ -73,25 +85,25 @@ guessing:
 - Missing `created` → `stat.ctime`, formatted `YYYY-MM-DD HH:MM` to match every other note's
   convention.
 
-Apply via read-modify-write on the whole file (`vault_read` → edit the one frontmatter line in the
-returned content → `vault_write` the whole file back) — never `vault_patch` with
-`targetType: frontmatter`, which re-serializes the entire YAML block and silently reformats
-unrelated fields, the same hazard `synapse-vault`/`synapse-task` already document.
+Apply via read-modify-write on the whole file (`synapse vault-read` → edit the one frontmatter line
+in the returned content → `synapse vault-write` the whole file back) — never `vault-patch` with
+`--frontmatter`, which re-serializes the entire YAML block and silently reformats unrelated fields,
+the same hazard `synapse-vault`/`synapse-task` already document.
 
 ## Step 3: Note-health findings (reported, not fixed)
 
-From the same inventory, no additional vault reads (the broken-link history check below reads the
-vault's local git log, not more notes). Each of these three has no safe mechanical repair —
-fixing any of them means guessing at intent — so they become findings for the Step 6 proposal
-instead of a silent edit:
-
-- **Broken links** — `unresolvedLinks` non-empty. Before writing the finding, check the vault's own
-  local git history to say *why* it's broken instead of leaving that to guesswork — the vault is
-  usually a git repo (`db-sync` auto-commits every agent-driven edit into it, opt-in per vault, same
-  precondition as that hook). Resolve the vault's filesystem path the same way `synapse.conf`
-  already does (`SYNAPSE_VAULT_DIR`), skip this sub-step entirely if `{vault}/.git` doesn't exist,
-  and never let a missing/unreachable git repo block the rest of the finding — worst case it's
-  reported with no history context, same as today.
+From the same inventory plus Step 1's three bulk link-graph calls, no additional vault reads (the
+broken-link history check below reads the vault's local git log, not more notes). Each of these
+three has no safe mechanical repair — fixing any of them means guessing at intent — so they become
+findings for the Step 6 proposal instead of a silent edit:
+
+- **Broken links** — every `vault-unresolved` row whose `source` is in scope. Before writing the
+  finding, check the vault's own local git history to say *why* it's broken instead of leaving that
+  to guesswork — the vault is usually a git repo (`db-sync` auto-commits every agent-driven edit into
+  it, opt-in per vault, same precondition as that hook). Resolve the vault's filesystem path the same
+  way `synapse.conf` already does (`SYNAPSE_VAULT_DIR`), skip this sub-step entirely if
+  `{vault}/.git` doesn't exist, and never let a missing/unreachable git repo block the rest of the
+  finding — worst case it's reported with no history context, same as today.
   - `git -C {vault} log --all --diff-filter=A --name-only --pretty=format: -- "**/{target}.md"` — a
     hit means a note by that exact title was created at some point (even if later renamed or
     deleted): report it as *"used to be a note — find what it's called now, or was deleted"*.
@@ -101,7 +113,9 @@ instead of a silent edit:
     as plain text or an external reference, not a vault link"* rather than implying anything was
     lost.
   - Neither check resolves anything more specific → report the target plainly, same as before.
-- **Orphaned notes** — `links` empty *and* `backlinks` empty.
+- **Orphaned notes** — in scope, in both `vault-orphans`' output (no backlinks) and `vault-deadends`'
+  (no outgoing links) — the intersection, not either alone: a note with backlinks but no outgoing
+  links is a dead end worth noting differently, not an orphan.
 - **Duplicate/near-duplicate titles** — group notes by title normalized (lowercased, trimmed,
   internal whitespace collapsed); any group with 2+ members is a finding. This is a mechanical
   string-normalization match, not fuzzy similarity — genuinely fuzzy "these might be the same
@@ -182,6 +196,6 @@ Print a short summary directly in the response, not left only in tool-call outpu
   Broken links, orphaned notes, and duplicate titles are proposal findings, never auto-repaired.
 - Invoked on demand only — no `SessionStart` wiring, no autonomous scheduling. Run it directly, or
   under a `/loop` the user sets up themselves.
-- No compiled code — every step above is a plain `mcp__obsidian__*` call, or (Step 3's broken-link
+- Every step above goes through the `synapse` CLI's `vault-*` subcommands, or (Step 3's broken-link
   history check only) a plain `git log` via Bash against the vault's own local repo; this command
-  itself never calls into `ObsidianStore`.
+  never calls an `mcp__obsidian__*` tool or `ObsidianStore` directly.

package/harness/claude/hooks.json

@@ -22,7 +22,7 @@
     ],
     "PostToolUse": [
       {
-        "matcher": "Write|Edit|Bash|mcp__obsidian__vault_(write|patch|append|delete|move)",
+        "matcher": "Write|Edit|Bash",
         "hooks": [
           {
             "type": "command",

package/harness/codex/hooks.json

@@ -22,7 +22,7 @@
     ],
     "PostToolUse": [
       {
-        "matcher": "apply_patch|Bash|mcp__obsidian__vault_(write|patch|append|delete|move)",
+        "matcher": "apply_patch|Bash",
         "hooks": [
           {
             "type": "command",

package/harness/codex/skills/synapse-init/SKILL.md

@@ -238,7 +238,7 @@ emit into tool calls than read into a window. Never hand-author those.
    **Do not choose which files to read by judgment, and do not decide how the writing itself
    happens by habit.** Both are decided by the `synapse-node-authoring` skill — **load it
    before writing the first node.** It resolves `SYNAPSE_AUTHOR_POOL` (env var, then
-   `~/.claude/synapse.conf`, default 0) and either walks you through authoring every node
+   `synapse.conf`, default 0) and either walks you through authoring every node
    yourself in one continuous pass (`rank --sources` per node, `## Links` candidates from
    step 6's `links.tsv`, reading order only — `sources` stays exhaustive either way), or fans
    out to a configurable pool of concurrent subagents, each handed a self-contained

package/harness/codex/skills/synapse-vault-tidy/SKILL.md

@@ -29,17 +29,17 @@ there is no argument to parse, every run produces the same one-pass sweep.
 
 ## Prerequisites
 
-Requires the `obsidian` MCP server (`mcp__obsidian__*` tools). If unreachable, say so and stop —
-there is no local-file fallback.
-
-No compiled code anywhere in this skill. `adapters/obsidian/store.zig`'s `ObsidianStore` does now
-implement `read`/`list`/`search`, but for `synapse frontmatter get`/`set`'s narrow one-field-at-a-time
-use — a full-vault tidy sweep, reading every note's whole body to judge category, tags and broken
-links, is a different shape of work entirely, and stays on these same MCP tools rather than the
-compiled binary, the same way the synapse-status and synapse-rebuild-diff skills' vault-side checks
-already work. The one exception is Step 3's broken-link history check, a plain `git log` call (via
-the shell, not a compiled tool) against the vault's own local repo when one exists — best-effort,
-never a hard requirement.
+Requires the `synapse` CLI on `PATH`, resolving a vault with a working link graph
+(`synapse vault-backlinks`/`vault-links`/`vault-unresolved`/`vault-orphans`/`vault-deadends`). If
+`SYNAPSE_VAULT_STORE` resolves to a backend with no link graph yet, these commands exit 1 saying so;
+stop and report that rather than falling back to anything else.
+
+This skill reaches the vault store only through the `synapse` CLI's `vault-*` subcommands, the same
+door every other skill uses — no MCP tool, no direct `ObsidianStore` call. `vault-links`/
+`vault-backlinks` each answer for one note at a time, so Step 1's inventory sweep runs one pair per
+note in scope: `2N` process spawns for an `N`-note vault. Acceptable for an on-demand, rare command.
+Step 3's broken-link history check is a plain `git log` call (via the shell, not a compiled tool)
+against the vault's own local repo when one exists — best-effort, never a hard requirement.
 
 ## Step 1: Inventory sweep
 
@@ -56,12 +56,23 @@ sweep rather than re-reading anything.
 ]}
 ```
 
-`mcp__obsidian__search_query` with that filter, then `mcp__obsidian__vault_read` each match. Keep
-the full result (`path`, `frontmatter`, `tags`, `links`, `backlinks`, `unresolvedLinks`, `stat`,
-`content`) per note — Steps 2–4 below only ever reason over the structured fields, never `content`
-itself; the judgment layer in Step 5 is the first point anything actually reads note *bodies*, and
-only for the subset flagged by then. `content` is fetched for free in this same call regardless, so
-there's no separate "light" read to bother with.
+`synapse vault-search --fields frontmatter,tags,content` with that filter on stdin gives `path`,
+`frontmatter`, `tags`, `content` per matching note in one pass (`stat`'s `ctime`/`mtime` aren't a
+`vault-search` field — see the note below). Also run `synapse vault-orphans`, `synapse
+vault-deadends`, and `synapse vault-unresolved` once each, vault-wide — three cheap bulk calls that
+Step 3 cross-references by path rather than recomputing per note. For each note in scope, also run
+`synapse vault-backlinks <path>` and `synapse vault-links <path>` and keep the results alongside it
+— this is the `2N` cost named in Prerequisites, needed only for Step 4's weak-folder-fit signal
+(which folder a note's actual link targets fall in, not just whether it has any). Keep the full
+assembled result (`path`, `frontmatter`, `tags`, `content`, `links`, `backlinks`) per note — Steps
+2–4 below only ever reason over the structured fields, never `content` itself; the judgment layer in
+Step 5 is the first point anything actually reads note *bodies*, and only for the subset flagged by
+then.
+
+`stat.ctime`/`stat.mtime` (Step 2's `created` default, Step 4's stale-category check) have no
+`vault-search` equivalent — read a note's mtime directly off disk (`SYNAPSE_VAULT_DIR`-resolved
+path) with a plain `stat` via the shell when either step needs it, same file the vault store itself
+already addresses.
 
 ## Step 2: Frontmatter defaults (fixed directly)
 
@@ -74,25 +85,25 @@ derivable without guessing:
 - Missing `created` → `stat.ctime`, formatted `YYYY-MM-DD HH:MM` to match every other note's
   convention.
 
-Apply via read-modify-write on the whole file (`vault_read` → edit the one frontmatter line in the
-returned content → `vault_write` the whole file back) — never `vault_patch` with
-`targetType: frontmatter`, which re-serializes the entire YAML block and silently reformats
-unrelated fields, the same hazard the vault and task-status skills already document.
+Apply via read-modify-write on the whole file (`synapse vault-read` → edit the one frontmatter line
+in the returned content → `synapse vault-write` the whole file back) — never `vault-patch` with
+`--frontmatter`, which re-serializes the entire YAML block and silently reformats unrelated fields,
+the same hazard the vault and task-status skills already document.
 
 ## Step 3: Note-health findings (reported, not fixed)
 
-From the same inventory, no additional vault reads (the broken-link history check below reads the
-vault's local git log, not more notes). Each of these three has no safe mechanical repair —
-fixing any of them means guessing at intent — so they become findings for the Step 6 proposal
-instead of a silent edit:
-
-- **Broken links** — `unresolvedLinks` non-empty. Before writing the finding, check the vault's own
-  local git history to say *why* it's broken instead of leaving that to guesswork — the vault is
-  usually a git repo (a db-sync hook auto-commits every agent-driven edit into it, opt-in per vault,
-  same precondition as that hook). Resolve the vault's filesystem path the same way its own conf
-  file already does (`SYNAPSE_VAULT_DIR`), skip this sub-step entirely if `{vault}/.git` doesn't
-  exist, and never let a missing/unreachable git repo block the rest of the finding — worst case
-  it's reported with no history context, same as today.
+From the same inventory plus Step 1's three bulk link-graph calls, no additional vault reads (the
+broken-link history check below reads the vault's local git log, not more notes). Each of these
+three has no safe mechanical repair — fixing any of them means guessing at intent — so they become
+findings for the Step 6 proposal instead of a silent edit:
+
+- **Broken links** — every `vault-unresolved` row whose `source` is in scope. Before writing the
+  finding, check the vault's own local git history to say *why* it's broken instead of leaving that
+  to guesswork — the vault is usually a git repo (a db-sync hook auto-commits every agent-driven edit
+  into it, opt-in per vault, same precondition as that hook). Resolve the vault's filesystem path the
+  same way its own conf file already does (`SYNAPSE_VAULT_DIR`), skip this sub-step entirely if
+  `{vault}/.git` doesn't exist, and never let a missing/unreachable git repo block the rest of the
+  finding — worst case it's reported with no history context, same as today.
   - `git -C {vault} log --all --diff-filter=A --name-only --pretty=format: -- "**/{target}.md"` — a
     hit means a note by that exact title was created at some point (even if later renamed or
     deleted): report it as *"used to be a note — find what it's called now, or was deleted"*.
@@ -102,7 +113,9 @@ instead of a silent edit:
     as plain text or an external reference, not a vault link"* rather than implying anything was
     lost.
   - Neither check resolves anything more specific → report the target plainly, same as before.
-- **Orphaned notes** — `links` empty *and* `backlinks` empty.
+- **Orphaned notes** — in scope, in both `vault-orphans`' output (no backlinks) and `vault-deadends`'
+  (no outgoing links) — the intersection, not either alone: a note with backlinks but no outgoing
+  links is a dead end worth noting differently, not an orphan.
 - **Duplicate/near-duplicate titles** — group notes by title normalized (lowercased, trimmed,
   internal whitespace collapsed); any group with 2+ members is a finding. This is a mechanical
   string-normalization match, not fuzzy similarity — genuinely fuzzy "these might be the same
@@ -182,6 +195,6 @@ Print a short summary directly in the response, not left only in tool-call outpu
   Broken links, orphaned notes, and duplicate titles are proposal findings, never auto-repaired.
 - Invoked on demand only — no session-start wiring, no autonomous scheduling. Run it only when
   asked, or on a recurring cadence the user sets up themselves.
-- No compiled code — every step above is a plain `mcp__obsidian__*` call, or (Step 3's broken-link
+- Every step above goes through the `synapse` CLI's `vault-*` subcommands, or (Step 3's broken-link
   history check only) a plain `git log` via the shell against the vault's own local repo; this skill
-  itself never calls into `ObsidianStore`.
+  never calls an `mcp__obsidian__*` tool or `ObsidianStore` directly.

package/harness/opencode/plugin/synapse.js

@@ -21,19 +21,15 @@
 // Claude Code's `Write`/`Edit` sharing `tool_input.file_path`. `db_sync.zig`
 // itself is a blind `git add -A && commit` against the vault's own repo, so
 // this plugin only needs to decide *whether* to fire it, not translate a
-// payload -- fired on the same write/edit tools, the two vault-mutating MCP
-// tools (`obsidian_vault_write`/`obsidian_vault_patch`, the same OpenCode
-// tool-naming transform `mcp__obsidian__vault_write`/`vault_patch` go
-// through elsewhere in this plugin's own skill/command prose), and `bash`
-// (`args.command`, confirmed against `packages/core/src/tool/bash.ts` in
-// the real `sst/opencode` source) when the command actually names `synapse
-// vault-write`/`vault-patch` -- the CLI door skills use instead of calling
-// the MCP tools directly (see `sb — Vault store backend selection`). Unlike
-// Claude Code's/Codex's `hooks.json`, which can only match a tool *name* and
-// so must widen their own matcher to `Bash` and let `db_sync.zig` filter the
-// command text itself, this plugin has the real args in hand before ever
-// spawning the hook, so it filters right here instead -- no spawn at all for
-// an unrelated `bash` call.
+// payload -- fired on the same write/edit tools, and on `bash` (`args.command`,
+// confirmed against `packages/core/src/tool/bash.ts` in the real
+// `sst/opencode` source) when the command actually names `synapse
+// vault-write`/`vault-patch` -- the CLI door skills use to reach the vault
+// (see `sb — Vault store backend selection`). Unlike Claude Code's/Codex's
+// `hooks.json`, which can only match a tool *name* and so must widen their
+// own matcher to `Bash` and let `db_sync.zig` filter the command text itself,
+// this plugin has the real args in hand before ever spawning the hook, so it
+// filters right here instead -- no spawn at all for an unrelated `bash` call.
 //
 // `stop-nudge`'s Claude Code trigger (`Stop`, once per turn) maps to
 // `session.idle` -- live-verified as firing exactly once, after every tool
@@ -111,7 +107,6 @@ async function alreadyInjected(client, sessionID) {
 }
 
 const EDIT_TOOLS = new Set(["write", "edit"])
-const VAULT_WRITE_TOOLS = new Set(["obsidian_vault_write", "obsidian_vault_patch"])
 
 // A `bash` call whose command names a `synapse vault-write`/`vault-patch`
 // invocation -- the substring check a real shell quoting/path prefix can't
@@ -162,8 +157,6 @@ export const Synapse = async ({ directory, client }) => {
           tool_input: { file_path: filePath },
         })
         runHook("db-sync", {});
-      } else if (VAULT_WRITE_TOOLS.has(input.tool)) {
-        runHook("db-sync", {});
       } else if (input.tool === "bash" && isVaultWriteCommand(input.args?.command)) {
         runHook("db-sync", {});
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imunitic/synapse",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Memory for Claude Code, Codex CLI, and OpenCode: a durable Obsidian vault plus a per-repo code graph.",
   "repository": {
     "type": "git",
@@ -22,9 +22,9 @@
     "*.conf.template"
   ],
   "optionalDependencies": {
-    "@imunitic/synapse-darwin-arm64": "0.2.2",
-    "@imunitic/synapse-linux-x64": "0.2.2",
-    "@imunitic/synapse-linux-arm64": "0.2.2"
+    "@imunitic/synapse-darwin-arm64": "0.2.4",
+    "@imunitic/synapse-linux-x64": "0.2.4",
+    "@imunitic/synapse-linux-arm64": "0.2.4"
   },
   "license": "SEE LICENSE IN LICENSE"
 }

package/skills/synapse-node-authoring/SKILL.md

@@ -26,16 +26,28 @@ ever loaded.
 ```sh
 pool="${SYNAPSE_AUTHOR_POOL:-}"
 if [ -z "$pool" ]; then
-  pool="$(grep -m1 '^SYNAPSE_AUTHOR_POOL=' ~/.claude/synapse.conf 2>/dev/null | cut -d= -f2- | tr -d '"')"
+  for conf in \
+    ${XDG_CONFIG_HOME:+"$XDG_CONFIG_HOME/synapse/synapse.conf"} \
+    "$HOME/.config/synapse/synapse.conf" \
+    "$HOME/.claude/synapse.conf"
+  do
+    if [ -f "$conf" ]; then
+      pool="$(grep -m1 '^SYNAPSE_AUTHOR_POOL=' "$conf" 2>/dev/null | cut -d= -f2- | tr -d '"')"
+      break
+    fi
+  done
 fi
 pool="${pool:-0}"
 ```
 
-Environment variable wins over the conf file, same precedence every other Synapse setting
-uses. Absent, empty, or malformed all fall through to `0`. **This is read by you, the
-orchestrating agent, directly — not by any Zig binary.** Nothing compiled dispatches
-subagents, so there is nothing for a `synapse` flag to feed. The conf file is the shared home
-for the setting; the reader is markdown, not code.
+Environment variable wins over the conf file. The conf lookup is the same three-tier order
+every `synapse-*.conf` file resolves through (see `docs/synapse/synapse-config.md`, "Where a
+conf file actually lives"): the first tier with a file at all wins, whether or not that file
+sets `SYNAPSE_AUTHOR_POOL` — a `synapse.conf` at `~/.claude/` is not consulted when one already
+exists at the XDG tier, even if the XDG one is silent on this key. Absent, empty, or malformed
+all fall through to `0`. **This is read by you, the orchestrating agent, directly — not by any
+Zig binary.** Nothing compiled dispatches subagents, so there is nothing for a `synapse` flag to
+feed. The conf file is the shared home for the setting; the reader is markdown, not code.
 
 `pool = 0` is not "a pool of zero workers" — go to §2. `pool >= 1` is a real worker pool — go
 to §3.

package/skills/synapse-orientation/SKILL.md

@@ -31,7 +31,10 @@ symbol names on CamelCase and snake_case, drops stopwords, and aggregates per di
   path rather than the code subset — the interesting files here are usually the ones no grammar
   can read.
 - `namespaces.tsv` — `group ⇥ namespace ⇥ agree ⇥ total`, where a rule is configured (question 3,
-  below, for whichever extensions `~/.claude/synapse-namespace-rules.conf` knows about).
+  below, for whichever extensions `synapse-namespace-rules.conf` knows about -- resolved through
+  the standard tiered lookup every `synapse-*.conf` file uses, see
+  `docs/synapse/synapse-config.md`'s "Where a conf file actually lives"; read/write whichever tier
+  actually resolves, never assume `~/.claude/`).
 - `parseable.tsv` and `distinctive.tsv` feed `synapse gate` and this section's own distinctiveness
   question respectively — see immediately below.
 
@@ -75,9 +78,10 @@ is about the gap between what the code calls itself and what the *directory* cal
    family) are what a node's prose should be about.
 
 **Namespace rules are self-populating too, the same way grammar discovery below is — write one
-back when question 3 turns up a real declaration convention.** `~/.claude/synapse-namespace-rules.conf`
-starts empty and nothing seeds it, so `namespaces.tsv` stays empty forever unless something
-writes a rule into it. If you just hand-derived a namespace root for an ecosystem this repo uses
+back when question 3 turns up a real declaration convention.** `synapse-namespace-rules.conf`
+(same tiered lookup as above) starts empty and nothing seeds it, so `namespaces.tsv` stays empty
+forever unless something writes a rule into it. If you just hand-derived a namespace root for an
+ecosystem this repo uses
 and `synapse-namespace-rules.conf` has no entry for its extension yet, the derivation you just
 did *is* the rule — write it back (create the file as `{}` first if it doesn't exist) so the next
 repo in this ecosystem gets `namespaces.tsv` for free instead of a repeat of this same
@@ -219,7 +223,8 @@ contribute to a node's prose. Do not build a tally out of those warnings.
        handling covers a real, cross-grammar class, a per-grammar word substitution would not.
 
      The kind-synonym rule list both bullets above lean on is
-     `~/.claude/synapse-kind-synonyms.conf` (`SYNAPSE_KIND_SYNONYMS_CONF` overrides the path), the
+     `synapse-kind-synonyms.conf` (`SYNAPSE_KIND_SYNONYMS_CONF` overrides the path; otherwise the
+     same tiered lookup as above), the
      same shape and precedence as `synapse-grammars.conf`/`synapse-namespace-rules.conf` — ordered
      rules, first match wins, absent means no mapping rather than a guessed one. Keyed by a
      `locals.scm` capture's kind suffix (or the empty string for an unsuffixed capture) or by a
@@ -325,7 +330,7 @@ contribute to a node's prose. Do not build a tally out of those warnings.
      query file that preempts the whole cascade, not a tier to reach automatically. Name it as an
      option when reporting the outcome (step 5) rather than silently accepting a weak result or a
      bare `unsupported`.
-  4. Write the result back to `~/.claude/synapse-grammars.conf` (create it as `{}` first if it
+  4. Write the result back to `synapse-grammars.conf` (same tiered lookup as above; create it as `{}` first if it
      doesn't exist) — a positive entry (`{"repo": "...", "scope": "..."}`) for whichever tier
      verified, `{"unsupported": true}` only when both came up empty or unusable. Record which
      tier with `"queries"`: omit it (or write `"tags"`) for a real `queries/tags.scm` found in the

package/synapse-claude.md

@@ -95,22 +95,26 @@ a real yes/no answer, not a formality to wave past.
 ## Reading and writing the vault
 
 The vault is reached through the `synapse` CLI — `synapse vault-read`/`vault-write`/`vault-list`/
-`vault-search`/`vault-search-text`/`vault-doc-map`/`vault-patch` — for reads *and* for writes, never
-by resolving a vault path or calling an `mcp__obsidian__*` tool directly. Which concrete store the
-CLI talks to (today, an Obsidian vault via its Local REST API; potentially a plain-disk vault later)
-is resolved once, inside the compiled binary, from `SYNAPSE_VAULT_STORE`/`SYNAPSE_VAULT_DIR` — never
-something a skill or an agent turn needs to know or branch on. Today that means Obsidian running
-headless at login (via a startup plugin) with the Local REST API plugin installed, and the CLI
-reaching it over that REST API; a future disk-backed vault would need no change to any skill or to
-this document.
+`vault-search`/`vault-search-text`/`vault-doc-map`/`vault-patch`/`vault-backlinks`/`vault-links`/
+`vault-unresolved`/`vault-orphans`/`vault-deadends` — for reads *and* for writes, never by resolving
+a vault path or calling an `mcp__obsidian__*` tool directly. Which concrete store the CLI talks to
+(today, an Obsidian vault reached through its own official CLI; also a plain-disk vault,
+`SYNAPSE_VAULT_STORE=disk`) is resolved once, inside the compiled binary, from
+`SYNAPSE_VAULT_STORE`/`SYNAPSE_VAULT_DIR` — never something a skill or an agent turn needs to know or
+branch on. Today that means Obsidian running headless at login, with no plugin, no cert, no MCP
+server needed: `read`/`write`/`list` are plain disk I/O against the vault folder, and
+`search`/the link graph go through Obsidian's own CLI over its local socket — off by default, so a
+`vault-search-text`/`vault-backlinks`/etc. failure is worth mentioning **Settings → General →
+Advanced → Command line interface** for, alongside stopping on it (see the precondition-failure
+rule below).
 
 **Every write to a note goes through `synapse vault-write` or `vault-patch`. Never the `Write`/`Edit`
 tools on the on-disk path, and never a raw `mcp__obsidian__*` tool call either** — not for a one-line
 change, and least of all when `Write`/`Edit` are already in hand from editing code earlier in the
 same turn, because that proximity is precisely what causes this to be violated. The vault being an
 ordinary directory means the wrong path *works*: Obsidian's file watcher converges, the auto-commit
-hook matches `Write|Edit`/`Bash` running `vault-write`/`vault-patch` as well as the MCP tools, and
-nothing visibly breaks — which is why the habit never self-corrects on its own. The reason is not a
+hook matches `Write|Edit`/`Bash` running `vault-write`/`vault-patch`, and nothing visibly breaks —
+which is why the habit never self-corrects on its own. The reason is not a
 failure mode to dodge; it is that an invariant upheld only when convenient is worth nothing. Nothing
 else in the system can rely on it, and every note then has to be re-checked by hand instead of
 trusted. Synapse's own tooling holds this line — `synapse write-node` goes through the same `Store`
@@ -118,13 +122,8 @@ abstraction the CLI does, rather than writing files directly — so agent writes
 differ. If the CLI itself ever fails (not installed, no vault configured), that's a real precondition
 failure to report and stop on, never a reason to fall back to a raw file edit.
 
-The `obsidian` MCP server (wrapping the same Local REST API) still exists and is still the right
-tool for a command that hasn't been migrated onto the CLI's `vault-*` subcommands yet (`/synapse-vault-tidy`, as of
-this writing — it needs whole-vault link/backlink data the CLI doesn't expose). If a project's
-`.claude.json` `mcpServers.obsidian` entry ever diverges from the user-scoped one (e.g. points at the
-wrong vault path via a stdio `obsidian-mcp` package instead of the REST API), that's a bug in that
-project's config, not a Synapse Vault routing choice — fix it by removing the project-level override
-so the correct user-scoped REST API server applies.
+Every shipped command and skill, `/synapse-vault-tidy` included, reaches the vault only through
+the `synapse` CLI's `vault-*` subcommands — none of them calls an `mcp__obsidian__*` tool.
 
 - You may create and edit notes in this vault **without asking for
   permission first**, as long as each note is placed in the folder

package/synapse.conf.template

@@ -1,4 +1,5 @@
-# Copy this to ~/.claude/synapse.conf and edit the path for this machine.
+# synapse-setup configure copies this file in automatically when it finds no
+# synapse.conf anywhere. Edit the path below for this machine.
 SYNAPSE_VAULT_DIR="$HOME/Obsidian/YourVault"
 
 # Where Synapse clones/builds tree-sitter grammars (shared across every

package/lib/obsidian-mcp-refresh.cjs

@@ -1,303 +0,0 @@
-#!/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 SYNAPSE_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.SYNAPSE_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, "SYNAPSE_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 };