@imunitic/synapse 0.1.2 → 0.2.0

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

@@ -7,12 +7,12 @@ description: Print a read-only report of what in Synapse Vault currently needs a
 
 A read-only sweep over Synapse Vault answering one question: what currently needs a human decision?
 Five categories, one pass, printed as plain chat text -- an org-agenda-style check-in, not a document
-to hand to someone else and not a live dashboard (a published Artifact has no route to the local
-Obsidian REST API, so nothing here is ever presented that way). Run it whenever the user asks for a
-vault status check, or on a recurring schedule the user has set up themselves -- never wired into
-session start: two of the five categories need a per-note body read, not just a frontmatter check,
-and unlike the vault's own index note this report is a periodic human check-in, not something the
-agent needs injected every session to behave correctly.
+to hand to someone else and not a live dashboard (a published Artifact has no route to the vault, so
+nothing here is ever presented that way). Run it whenever the user asks for a vault status check, or
+on a recurring schedule the user has set up themselves -- never wired into session start: some of the
+five categories need a per-note content read, not just a frontmatter check, and unlike the vault's
+own index note this report is a periodic human check-in, not something the agent needs injected every
+session to behave correctly.
 
 Scoped to `designs/`/`tasks/` only -- the two folders design-note creation and task-note creation
 structurally require, so every Synapse install has them in the same shape. The free-form taxonomy
@@ -28,78 +28,91 @@ produces the same five-category sweep.
 
 ## Prerequisites
 
-Requires the `obsidian` MCP server (`mcp__obsidian__*` tools). If unreachable, say so and stop --
-there is no local-file fallback.
+Requires the `synapse` CLI on `PATH`. Backend-agnostic -- every query below goes through `synapse
+vault-search`, so it works the same whether the vault is Obsidian-backed or plain-disk-backed. If the
+CLI errors (no vault configured), say so and stop -- there is no other fallback.
 
 ## Producing the report
 
-Run all five queries in parallel where the tool call shape allows it; none depends on another's
-result.
+Run each query below via `synapse vault-search --fields <fields>`, with the JsonLogic query on stdin.
+`--fields` asks for exactly the columns the query needs back -- no separate read per match required,
+since a matched row already carries them.
 
 **1. Design notes still `Discussing`.** Design notes carry status in-body under `## Status`, not in
-frontmatter (unlike task notes) -- a content match, scoped to `designs/`:
+frontmatter (unlike task notes) -- a content match, scoped to `designs/`. Needs only the title:
 
 ```
+synapse vault-search --fields frontmatter.title <<'EOF'
 {"and": [
   {"glob": ["designs/*", {"var": "path"}]},
   {"regexp": ["## Status\\nDiscussing", {"var": "content"}]}
 ]}
+EOF
 ```
 
 **2. `Ready` design notes with no compiled task yet.** The design-compilation skill's own "Linking
 back" step patches a compiled design note with a `> Compiled task: [[...]]` line right after its
 title -- "`Ready` and missing that line" is a direct signal, not fuzzy title-matching against
-`tasks/`:
+`tasks/`. Needs only the title:
 
 ```
+synapse vault-search --fields frontmatter.title <<'EOF'
 {"and": [
   {"glob": ["designs/*", {"var": "path"}]},
   {"regexp": ["## Status\\nReady", {"var": "content"}]},
   {"!": [{"regexp": ["Compiled task:", {"var": "content"}]}]}
 ]}
+EOF
 ```
 
 **3. Design notes (any status) with a non-empty `## Open Questions`.** Match the heading followed by
 at least one bullet -- a heading with nothing under it (fully pruned, per the design-note skill's own
 Ready-gate convention) doesn't count as open. Since this section spans every status, each line in the
-composed report also shows *which* status the note is currently in:
+composed report also shows *which* status the note is currently in -- request `content` too, and pull
+the status directly out of the returned text rather than reading the note again:
 
 ```
+synapse vault-search --fields frontmatter.title,content <<'EOF'
 {"and": [
   {"glob": ["designs/*", {"var": "path"}]},
   {"regexp": ["## Open Questions\\n- ", {"var": "content"}]}
 ]}
+EOF
 ```
 
-`regexp` is boolean-only (no captured groups), so getting each match's actual status needs a second
-pass. Run the same query three more times, `and`-ed with `{"regexp": ["## Status\\nDiscussing", ...]}`
-/ `Ready` / `Reference` respectively, to sort the matches from the first query into the three known
-statuses without a body read. **A design note written before `## Status` was standardized on those
-exact three words can carry free text there instead** (e.g. `Superseded by [[...]]`) -- it matches
-the first query but none of the three status-scoped ones. Whatever's left over after removing the
-Discussing/Ready/Reference matches from the first query's full result set is exactly this case:
-report those under a fourth bucket, "Other", rather than silently dropping them -- surfacing an odd
-note beats losing it, the same reasoning behind reporting a 0-unchecked task instead of hiding it
-(see Query 4 below).
+Do not chain further `and`/`regexp` conditions onto this query to sort matches by status -- compound
+`regexp` conditions against `content` have been observed to return results that are logically
+impossible (a query with strictly more AND-ed conditions returning *more* matches than one with
+fewer), so any query beyond a single `glob` + single `regexp` pair is unverified and not to be
+trusted here. Instead, take the line following `## Status` directly out of each row's `content`
+column -- normally `Discussing`/`Ready`/`Reference`, but a design note written before that
+three-word convention was standardized can carry free text there instead (e.g. `Superseded by
+[[...]]`); report that verbatim rather than forcing it into a bucket, surfacing an odd note beats
+losing it, the same reasoning behind reporting a 0-unchecked task instead of hiding it (see Query 4
+below).
 
 **4. Open task notes with at least one unchecked item.** Task notes carry `status:` in frontmatter,
-unlike design notes -- filter there first:
+unlike design notes -- filter there first, and request `content` to count `- [ ]` lines directly from
+the row rather than reading each match again:
 
 ```
+synapse vault-search --fields frontmatter.title,content <<'EOF'
 {"in": [{"var": "frontmatter.status"}, ["TODO", "IN-PROGRESS"]]}
+EOF
 ```
 
-Then `mcp__obsidian__vault_read` each match and count `- [ ]` lines in the body. A match with zero
-unchecked lines (a checklist that's fully checked but hasn't been promoted to `REVIEW` yet) is still
-worth surfacing -- report it under this section with its count shown as 0, rather than silently
-dropping it, since that state itself is worth a human noticing.
+A match with zero unchecked lines (a checklist that's fully checked but hasn't been promoted to
+`REVIEW` yet) is still worth surfacing -- report it under this section with its count shown as 0,
+rather than silently dropping it, since that state itself is worth a human noticing.
 
-**5. Task notes stuck in `REVIEW`.** Frontmatter-only, no body read needed -- a fully-checked
-checklist waiting specifically on human sign-off, since the task-status skill deliberately never
-promotes a note past `REVIEW` on its own:
+**5. Task notes stuck in `REVIEW`.** Frontmatter-only, no body needed -- a fully-checked checklist
+waiting specifically on human sign-off, since the task-status skill deliberately never promotes a
+note past `REVIEW` on its own:
 
 ```
+synapse vault-search --fields frontmatter.title <<'EOF'
 {"==": [{"var": "frontmatter.status"}, "REVIEW"]}
+EOF
 ```
 
 ## Composing the report
@@ -108,8 +121,7 @@ One section per category, in the order above. Each line names the note (title, o
 `title` frontmatter) plus the one identifying detail that category needs. The Open Questions section
 is the one place a note's status also belongs on the line -- every other section's heading already
 implies it (the "Discussing" section only ever holds `Discussing` notes), but Open Questions spans
-every status (`Discussing`/`Ready`/`Reference`/the "Other" catch-all from Query 3 above), so put the
-status first, before the title, so it's the first thing scanned:
+every status, so put the status first, before the title, so it's the first thing scanned:
 
 ```
 ## Discussing
@@ -138,9 +150,8 @@ go dig for.
 
 ## Constraints
 
-- Read-only end to end. Never calls `vault_write`/`vault_patch`/`vault_move`/`vault_delete`/
-  `vault_copy` -- if a step here ever seems to need one, that step is out of scope, not a case to
-  special-case around.
+- Read-only end to end. Never calls `vault-write`/`vault-patch` -- if a step here ever seems to need
+  one, that step is out of scope, not a case to special-case around.
 - No Artifact/web-UI output. No session-start wiring. Not a new binary CLI subcommand -- every
-  category above is a plain mechanical query already reachable through `mcp__obsidian__*` tools.
+  category above is a plain mechanical query already reachable through `synapse vault-search`.
 - Scoped to `designs/`/`tasks/` only -- never `inbox/`/`research/`/`scratchpad/`.

package/harness/codex/skills/synapse-task-note/SKILL.md

@@ -89,12 +89,19 @@ don't duplicate that scaffolding here, just supply its inputs:
 
 ## Linking back
 
-After creation, patch the design note: add `> Compiled task: [[{task note title}]]` near the top
-(via `mcp__obsidian__vault_patch`) — a small annotation line, same idea as any other cross-reference
-you'd drop near a note's title. This is a one-time link; the design note's `Status` itself does not
-change and does not need to track the task's progress — Obsidian's own backlinks panel already
-surfaces the live task note from the design note, and the task's `status:` frontmatter is the
-authoritative progress signal from here on.
+After creation, patch the design note: add `> Compiled task: [[{task note title}]]` near the top —
+right after the `# {title}` heading, before `## Status`:
+
+```
+printf '> Compiled task: [[%s]]\n\n' "{task note title}" | \
+  synapse vault-patch "{design note path}" --heading "{design note title}" --prepend
+```
+
+A small annotation line, same idea as any other cross-reference you'd drop near a note's title. This
+is a one-time link; the design note's `Status` itself does not change and does not need to track the
+task's progress — a plain `synapse vault-search-text` for the task note's title already surfaces the
+live task note from the design note, and the task's `status:` frontmatter is the authoritative
+progress signal from here on.
 
 ## Confirm
 

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

@@ -90,7 +90,7 @@ instead of a silent edit:
   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 (`OBSIDIAN_VAULT_DIR`), skip this sub-step entirely if `{vault}/.git` doesn't
+  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

package/harness/opencode/plugin/synapse.js

@@ -19,12 +19,21 @@
 // edit: `write` (`args.filePath`, `args.content`) and `edit` (`args.filePath`,
 // `args.oldString`, `args.newString`) -- both share `filePath`, matching
 // Claude Code's `Write`/`Edit` sharing `tool_input.file_path`. `db_sync.zig`
-// itself reads no payload at all (a blind `git add -A && commit` against the
-// vault's own repo), so it only needs a trigger, not a translated payload --
-// fired on the same write/edit tools, plus the two vault-mutating MCP tools
-// (`obsidian_vault_write`/`obsidian_vault_patch`, the same OpenCode
+// 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).
+// 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.
 //
 // `stop-nudge`'s Claude Code trigger (`Stop`, once per turn) maps to
 // `session.idle` -- live-verified as firing exactly once, after every tool
@@ -104,6 +113,15 @@ 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
+// evade in the cases that matter (`synapse vault-write ...`, `/path/to/synapse
+// vault-patch ...`), matching `db_sync.zig`'s own `shouldSkipBash` filter for
+// the harnesses that can't pre-filter on args the way this plugin can.
+function isVaultWriteCommand(command) {
+  return typeof command === "string" && (command.includes("vault-write") || command.includes("vault-patch"))
+}
+
 // sessionID -> nudge text from a `stop-nudge` call that had nowhere to land
 // yet -- delivered on that session's next `chat.message`.
 const pendingNudge = new Map()
@@ -146,6 +164,8 @@ export const Synapse = async ({ directory, client }) => {
         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/lib/obsidian-mcp-refresh.cjs

@@ -130,7 +130,7 @@ function confExpand(raw) {
 
 // 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
+// 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) {
@@ -150,7 +150,7 @@ function resolveConfPath(name) {
 // 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;
+  const override = process.env.SYNAPSE_VAULT_DIR;
   if (override) return override;
 
   for (const name of ["synapse.conf", "second-brain.conf"]) {
@@ -162,7 +162,7 @@ function resolveVaultDir() {
     } catch {
       continue;
     }
-    const raw = confGet(text, "OBSIDIAN_VAULT_DIR");
+    const raw = confGet(text, "SYNAPSE_VAULT_DIR");
     if (raw === null) continue;
     const expanded = confExpand(raw);
     if (expanded) return expanded;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imunitic/synapse",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "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.1.2",
-    "@imunitic/synapse-linux-x64": "0.1.2",
-    "@imunitic/synapse-linux-arm64": "0.1.2"
+    "@imunitic/synapse-darwin-arm64": "0.2.0",
+    "@imunitic/synapse-linux-x64": "0.2.0",
+    "@imunitic/synapse-linux-arm64": "0.2.0"
   },
   "license": "SEE LICENSE IN LICENSE"
 }

package/skills/synapse-node/SKILL.md

@@ -38,7 +38,7 @@ needs one.
    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"`
+2. **Also honour the Tier 1 flag.** `rg -m1 '^stale:' "$SYNAPSE_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
@@ -55,13 +55,13 @@ needs one.
 
    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`
+   files or 941. **A full `synapse 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.
+   path list you are not going to use. Use `vault-read` only when you specifically need the
+   frontmatter itself.
 
    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
+   exhaustive, `synapse vault-search-text` 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:

package/skills/synapse-query/SKILL.md

@@ -47,7 +47,7 @@ required:
 
 | Need | Reach for | Why |
 |---|---|---|
-| "Where does X live?" (ranked, natural-language) | `mcp__obsidian__search_simple`/`search_query` over the vault, plus a first read of `synapse/{project}/Index.md` | Full-text, relevance-ranked. Not semantic ranking, but genuinely comparable for locating a concept. |
+| "Where does X live?" (ranked, natural-language) | `synapse vault-search-text`/`vault-search` over the vault, plus a first read of `synapse/{project}/Index.md` | Full-text, relevance-ranked. Not semantic ranking, but genuinely comparable for locating a concept. |
 | Every occurrence of a pattern | native `grep`/`rg`, **scoped to a file Synapse already named** | Not a repo-wide first move — the deterred, last-resort case. See "Why this exists" above. |
 | A file's API surface | read the file directly | Claude already has direct, cheap filesystem access — no separate view needed. |
 | Who depends on a subsystem, or what it depends on | `synapse query links "{Node}" --inbound` / `--closure` | Real transitive-closure traversal over the typed relations, at node granularity. |
@@ -63,7 +63,7 @@ required:
 |---|---|---|
 | Orienting on an unfamiliar repo | `synapse/{project}/Index.md`, then the relevant node's `body` | grepping around to build a mental map by hand |
 | Understanding a flow ("how does X work") | `synapse query body "{Node}"` for the node that covers it | reading every file the flow touches, cold |
-| Finding where a change belongs | `search_simple`/`Index.md` to find the owning node, then that node's `sources`/`crux_path` for the exact file(s) | a repo-wide grep for a guessed symbol name |
+| Finding where a change belongs | `vault-search-text`/`Index.md` to find the owning node, then that node's `sources`/`crux_path` for the exact file(s) | a repo-wide grep for a guessed symbol name |
 | Judging blast radius before an edit | `synapse query links "{Node}" --inbound` (or `--closure` for transitive) | assuming nothing else depends on it |
 | You already know the exact file and line range | just fetch it (`sed`, or a direct file read) | asking Synapse a question you can already answer |
 | Finding every occurrence of a literal pattern | native `grep`/`rg`, scoped to files Synapse already named | an unscoped repo-wide grep before consulting Synapse at all |

package/skills/synapse-task/SKILL.md

@@ -52,10 +52,11 @@ into `status:` either — always go through this skill, which caps at
 
 ## Procedure
 
-1. Find the task note: `mcp__obsidian__search_query` with
-   `{"==": [{"var": "frontmatter.task_id"}, "<task-id>"]}`, where `<task-id>`
+1. Find the task note: `synapse vault-search --fields content` with
+   `{"==": [{"var": "frontmatter.task_id"}, "<task-id>"]}` on stdin, where `<task-id>`
    is the specific task's ID (whatever prefix it uses — `proj-035`, `sb-008`,
-   etc.), then `mcp__obsidian__vault_read` the matched file.
+   etc.) — one call returns the matched note's path and full body together, no
+   separate read needed.
 2. Inspect its checklist items (`- [ ]` / `- [x]`).
 3. Determine the new `status:` value: `IN-PROGRESS` if any unchecked,
    `REVIEW` if all checked.
@@ -67,44 +68,38 @@ into `status:` either — always go through this skill, which caps at
    changes exactly that one line and nothing else, entirely inside the
    compiled binary — the note's body never enters your context at all.
    When the command isn't available, fall back to **read-modify-write**:
-   `vault_read` the file, replace the one line in the returned content,
-   `vault_write` the whole file back — byte-preserving, because you write
+   `synapse vault-read` the file, replace the one line in the returned content,
+   `synapse vault-write` the whole file back — byte-preserving, because you write
    back what you read.
 
-   **Never use `vault_patch` with `targetType: frontmatter`.** It is *not*
-   field-local, despite reading that way: two patches
-   (one for `status`, one for `last_updated`) re-serialise the entire
-   frontmatter block — every quoted value loses its quotes (`created:
-   "2024-01-01 15:57"` → `created: 2024-01-01 15:57`) and a long `title:`
-   is folded across two lines. Both are valid YAML, so nothing breaks
-   loudly, but any tool string-matching `^title: "` stops matching, and
-   every status transition silently reformats the note. Since transitions
-   are this skill's main job, that reformatting would land on every task
-   note in the vault. `frontmatter set` exists specifically so this never
-   has to be reached for.
+   `synapse vault-patch <path> --frontmatter <key> --replace` is also byte-preserving now (it
+   delegates to the same field-local mechanism `frontmatter set` uses internally), unlike the old
+   Obsidian MCP tool of the same shape — but it only ever writes a plain scalar, and it's a full
+   read-apply-write round trip through the patch layer for one field. `frontmatter set` stays the
+   right tool for this step: narrower, and the one call that exists specifically for it.
 6. **For completion only:** append implementation bullets to the existing
-   `## Notes` section with `mcp__obsidian__vault_patch`
-   (`targetType: heading`, `target: "{H1 title}::Notes"`, `operation:
-   append`) — append is safe here too. **The target must be the full
-   nested path** (`H1::Notes`), not just `"Notes"`: since `## Notes` is
-   nested under the top-level `# {title}` heading, the
-   plugin's heading lookup fails with "target not found in document" on
-   the bare leaf name and requires the `::`-joined path from the tool's
-   own docs. If no notes section exists, same call with
-   `createTargetIfMissing: true`.
-
-The vault_patch hazards below are the task-note-specific instance of a general rule; the
-`synapse-vault` skill carries the full list (H1 replace, nested heading paths, frontmatter
-re-serialisation) for every note, not just task notes.
-
-**Do not use `vault_patch` with `operation: replace` on the top-level
-heading to edit checklist items.** "Content beneath
-heading" for a top-level (`#`) heading extends through *all* nested
-subheadings (including `## Notes`), not just the leading paragraph/checklist
-directly under it — a replace there silently deletes everything past the
-checklist, including the Notes section. To check off checklist items,
-instead `vault_read` the full file, edit the `- [ ]` → `- [x]` lines in the
-returned content, and `vault_write` the whole file back.
+   `## Notes` section with `synapse vault-patch`:
+
+   ```
+   printf '%s\n' "- bullet one" "- bullet two" | \
+     synapse vault-patch "{path}" --heading "{H1 title}::Notes" --append --create
+   ```
+
+   Append is safe here too. **The target must be the full nested path** (`H1::Notes`), not just
+   `"Notes"`: since `## Notes` is nested under the top-level `# {title}` heading, a bare leaf name
+   fails with "target not found in {path}" -- check `synapse vault-doc-map <path>` rather than
+   guessing. `--create` creates the section (and any missing parent) if it doesn't exist yet.
+
+The vault-patch hazards below are the task-note-specific instance of a general rule; the
+`synapse-vault` skill carries the full list (H1 replace, nested heading paths, frontmatter) for
+every note, not just task notes.
+
+**Do not use `vault-patch --heading "{H1 title}" --replace` to edit checklist items.** A top-level
+heading's own section extends through *all* nested subheadings (including `## Notes`), not just
+the leading paragraph/checklist directly under it — a replace there silently deletes everything
+past the checklist, including the Notes section. To check off checklist items,
+instead `synapse vault-read` the full file, edit the `- [ ]` → `- [x]` lines in the
+returned content, and `synapse vault-write` the whole file back.
 
 ## Notes format
 
@@ -245,13 +240,13 @@ repos/<owner>/<repo>/issues/<n>/comments`).
   commit/push — a prior "commit and push" is not a standing license for the
   next one, and setting `DONE` is itself a human action this skill never
   takes (see "Never write `DONE`" above).
-- **Never create a task note via a bare `vault_write`.** Always
+- **Never create a task note via a bare `vault-write`.** Always
   `/synapse-note --task`, or `/synapse-task-note` when compiling one from a
   `Ready` design note. A freeform write skips both the skeleton (checklist
   items plus a single `## Notes` section) and every guardrail in this file —
   there is no partial-credit version of following this skill.
-- **Never restructure an existing task note's shape via `vault_write`/
-  `vault_patch` outside this skill's own procedure.** Ad hoc edits that add
+- **Never restructure an existing task note's shape via `vault-write`/
+  `vault-patch` outside this skill's own procedure.** Ad hoc edits that add
   new headings, drop the checklist, or otherwise diverge from the skeleton
   are what this guardrail exists to prevent — not just wrong `status:`
   values.

package/skills/synapse-vault/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: synapse-vault
-description: Synapse Vault is durable memory, and only its Index.md is ever auto-injected — every other note is pull-only. Load this BEFORE answering from your own reasoning about tooling behaviour, a past decision, a convention, a gotcha, or anything a previous session might have written down; and before creating or editing any note in the vault. Covers what to search with, and the vault_patch operations that silently destroy a note.
+description: Synapse Vault is durable memory, and only its Index.md is ever auto-injected — every other note is pull-only. Load this BEFORE answering from your own reasoning about tooling behaviour, a past decision, a convention, a gotcha, or anything a previous session might have written down; and before creating or editing any note in the vault. Covers what to search with, and the vault-patch operations that silently destroy a note.
 ---
 
 # Synapse Vault: search it first, and do not destroy it
@@ -27,12 +27,18 @@ Search before you answer when the question is about:
 - anything that starts "I think it works like…"
 
 ```
-mcp__obsidian__search_simple    full-text, relevance-ranked, with match context
-mcp__obsidian__search_query     JsonLogic over frontmatter, tags, links, backlinks, path globs
-mcp__obsidian__vault_list       when you already know roughly where it is
-mcp__obsidian__vault_read       with targetType/target to pull one section, not the whole note
+synapse vault-search-text <query>          full-text, relevance-ranked, with match context
+synapse vault-search --fields <f1,f2,...>  JsonLogic over frontmatter, tags, content, path globs
+synapse vault-list                         when you already know roughly where it is
+synapse vault-read <path>                  the whole note -- no partial/targeted read exists
 ```
 
+`vault-search`'s JsonLogic filter and `--fields` projection both stop at frontmatter/tags/content/
+path -- there is no `links`/`backlinks`/`unresolvedLinks` equivalent (no whole-vault wikilink index
+exists yet), and `vault-read` always returns the full body, never one section on its own -- request
+exactly what you need with `--fields` instead of over-fetching, and pull a specific section out of
+`vault-read`'s output locally when that's all you actually need.
+
 A search that returns nothing is a real result and worth one line in the note you then write —
 a negative result cannot be rediscovered by searching for it.
 
@@ -40,37 +46,39 @@ a negative result cannot be rediscovered by searching for it.
 
 Every item below returns success.
 
-- **`vault_patch` + `operation: replace` targeting the H1 replaces the entire document.**
-  `targetScope` defaults to `content` = "everything below this heading until one of the same or
-  higher level", and below the H1 there is no higher level, so that is the whole note. To insert
-  between the title and the first H2 — a status or metadata blockquote, the usual reason to touch
-  that region — use **`operation: prepend` against the H1**. Never `replace`.
-- **Heading targets are nested paths.** An H2 is `H1 title::H2 title`; a bare `H2 title` fails
-  with "target not found in document", which reads like the heading is missing rather than like
-  the path is wrong. `mcp__obsidian__vault_get_document_map` returns the exact `::` paths.
-- **`operation: append` against the bare H1 can land one heading level too deep.** When the
-  document's last section has a subheading of its own (e.g. `## Approach` ending in
-  `### Alternatives considered`), an appended `## Notes` can come back as `### Notes`, nested
-  under that last subsection instead of sitting as a sibling top-level heading. Target the
-  specific preceding heading directly, or check `mcp__obsidian__vault_get_document_map` after —
-  it shows the real heading tree, so a wrong level is visible immediately rather than assumed
-  from the call's own success response.
-- **Never `vault_patch` frontmatter.** `targetType: frontmatter` reads as field-local and is not:
-  it re-serialises the whole YAML block, so unrelated values lose their quotes, long lines get
-  re-wrapped, and an array value comes back as a quoted string instead of a real YAML list. Use
-  `synapse frontmatter set <path> <key> <value>` (or `--add-tag`/`--remove-tag` for `tags`
-  specifically; `synapse frontmatter get <path> <key>` reads one back) — it changes one field in
-  the compiled binary, byte-preserving, without ever
-  pulling the note's body into your context. It only handles a flat scalar or comma-separated
-  array field; for anything it doesn't cover (a block-style value, or an edit outside
-  frontmatter), fall back to reading the file, changing the one line, and writing the whole file
-  back.
-- **Do not patch for whitespace-precise edits.** A blank line between a heading and the block
-  under it is exactly what a patch may normalise away. A disk-level file edit with a unique anchor
-  is more predictable; Obsidian picks up external changes automatically.
-- **Never hardcode the vault path.** The REST API targets whichever vault the running headless
-  Obsidian has open. If you must reach disk, the path comes from `OBSIDIAN_VAULT_DIR` in
-  `~/.claude/synapse.conf`.
+- **`vault-patch --heading "{title}" --replace` targeting the H1 replaces the entire document.**
+  A heading target's `content` scope is "everything below this heading's own line, until the next
+  heading at the same or shallower level" -- below a top-level H1 there is nothing shallower, so
+  that scope is the whole note. To insert between the title and the first H2 — a status or
+  metadata blockquote, the usual reason to touch that region — use **`--prepend` against the H1**.
+  Never `--replace` there.
+- **Heading targets are nested paths.** An H2 under the H1 is `"{H1 title}::{H2 title}"`; a bare
+  `"{H2 title}"` fails with "target not found in {path}", which reads like the heading is missing
+  rather than like the path is wrong. `synapse vault-doc-map <path>` returns the exact `::` paths
+  (and every block id and frontmatter key too), so check it rather than guessing a path.
+- **`--append`/`--prepend`/`--replace` splice `content` in exactly as given, with no relative
+  heading-level translation.** Unlike some patch tools, a `#` in `content` is never adjusted
+  relative to the target -- if you write `## Notes` in `content`, `## Notes` is what lands, at
+  whatever nesting level you typed. `--append` always lands as the last thing in the target's own
+  section (right before the next heading at the same level or shallower, or end of document),
+  regardless of how deeply nested the immediately preceding content happens to be -- so a wrong
+  heading level in your own `content` string is the only way to get this wrong, not an artifact of
+  where in the section you're inserting.
+- **`vault-patch --frontmatter <key>` only ever writes a scalar.** It delegates to
+  `core.frontmatter.set` internally, so unlike a patch tool that re-serialises the whole YAML
+  block, it *is* byte-preserving — every other line survives untouched. But its `content` is
+  always written as a plain scalar, never a list, so it's the wrong tool for `tags` specifically.
+  Prefer `synapse frontmatter set <path> <key> <value>` (or `--add-tag`/`--remove-tag` for `tags`;
+  `synapse frontmatter get <path> <key>` reads one back) regardless — it's the narrower, one-field
+  tool this exists for, without a read-then-write round trip through `vault-patch` for a single
+  value. Neither tool handles a block-style value; fall back to reading the file, changing the one
+  line, and writing the whole file back for that.
+- **Block targets (`--block <id>`) only recognize a single-line block** — a line ending in
+  ` ^{id}`. A multi-line block has no target grammar here at all; fall back to a heading target
+  around it, or a disk-level edit.
+- **The vault path is never hardcoded in a skill.** Every `vault-*` subcommand resolves it itself
+  (`SYNAPSE_VAULT_DIR`, same tiered lookup `synapse.conf` uses) — pass a vault-relative path, never
+  an absolute one you constructed by hand.
 
 ## Verify with a structural invariant, not by re-reading what you wrote
 
@@ -94,7 +102,7 @@ The vocabulary is `synapse-tag-vocabulary.conf` — one tag per line, `#`-commen
 
 Before adding a tag to a note, read the conf and prefer an existing entry over minting a new one. Add a new entry only for a genuinely new concept the existing vocabulary doesn't cover, and append it to the conf when you do. A note's tag set is agent-owned working content: a command may add or remove a tag freely, including one a human added by hand — there is no special protection that would block reconsidering it.
 
-Tagging many existing notes at once (a backfill) should be rare to the point of not recurring — every note created through the authoring commands above is tagged inline as part of being written, so a vault only ever needs a backfill once, for notes that predate tagging being wired in at all. If one is ever needed anyway, resolve tags mechanically first: title text, folder path, and frontmatter (`task_id` prefix, `project` field) matched against the vocabulary settle the large majority of notes with no content read at all. Read a note's body only when those signals don't already resolve to at least one vocabulary tag. A full `vault_read` on every note in a large backfill spends session context on a decision cheap signals usually already make.
+Tagging many existing notes at once (a backfill) should be rare to the point of not recurring — every note created through the authoring commands above is tagged inline as part of being written, so a vault only ever needs a backfill once, for notes that predate tagging being wired in at all. If one is ever needed anyway, resolve tags mechanically first: title text, folder path, and frontmatter (`task_id` prefix, `project` field) matched against the vocabulary settle the large majority of notes with no content read at all. Read a note's body only when those signals don't already resolve to at least one vocabulary tag. A full `vault-read` on every note in a large backfill spends session context on a decision cheap signals usually already make.
 
 ## The graph side of the vault