@imunitic/synapse 0.4.2 → 0.4.4

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

@@ -27,7 +27,7 @@ reinventing a parallel view — this skill has no separate list/continue mode of
 
 ## Prerequisites
 
-- Requires a matching Obsidian design note (`designs/`) with `Status: Ready`.
+- Requires a matching design note (`designs/`) with `Status: Ready`.
 - No matching note → "No Ready design note found for '{topic}'. Start or continue that design note
   first." Never generate a checklist from scratch.
 - Matching note but `Status: Discussing` → "Design note for '{topic}' is still in Discussing. Finish
@@ -123,7 +123,7 @@ skill doesn't set or watch that field itself.
 ```
 User: let's compile a task note for "rollup direct storage"
 
-Codex: [reads designs/{PROJECT} — Rollup direct storage.md, Status: Ready]
+Codex: [reads designs/{project}/Rollup direct storage.md, Status: Ready]
        [no existing linked task note]
 
        Compiled checklist:
@@ -134,8 +134,8 @@ Codex: [reads designs/{PROJECT} — Rollup direct storage.md, Status: Ready]
 
        Project already known: {PROJECT} → {prefix}-005.
 
-       Created: tasks/{PROJECT}/Rollup direct storage implementation.md (task_id: {prefix}-005)
-       Linked back from designs/{PROJECT} — Rollup direct storage.md.
+       Created: tasks/{project}/Rollup direct storage implementation.md (task_id: {prefix}-005)
+       Linked back from designs/{project}/Rollup direct storage.md.
 
        Status transitions happen automatically via the synapse-task skill once you start work.
 ```

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

@@ -30,14 +30,14 @@ there is no argument to parse, every run produces the same one-pass sweep.
 ## Prerequisites
 
 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`). Both
-real coding-vault backends have one — `disk` (the default) always local, `obsidian` reaching a
-running app when reachable and falling back to `disk`'s own implementation otherwise. If
-`SYNAPSE_VAULT_INTEGRATIONS` ever resolves to a backend with no link graph at all, these commands exit 1
-saying so; stop and report that rather than falling back to anything else.
+(`synapse vault-backlinks`/`vault-links`/`vault-unresolved`/`vault-orphans`/`vault-deadends`).
+`disk`, the one real backend, always has one -- case-insensitive wikilink resolution over the vault
+folder directly, no external dependency. If `SYNAPSE_VAULT_INTEGRATIONS` ever resolves to a backend
+with no link graph at all, 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`/
+door every other skill uses — no MCP tool, no direct store 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)
@@ -87,10 +87,9 @@ 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 (`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.
+Apply with `synapse frontmatter set <path> <key> <value>` (or `vault-patch --frontmatter`, which
+delegates to the same byte-preserving mechanism) — either writes exactly this one field and leaves
+every other line untouched, the way the vault and task-status skills already document.
 
 ## Step 3: Note-health findings (reported, not fixed)
 
@@ -199,4 +198,4 @@ Print a short summary directly in the response, not left only in tool-call outpu
   asked, or on a recurring cadence the user sets up themselves.
 - 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
-  never calls an `mcp__obsidian__*` tool or `ObsidianStore` directly.
+  never calls a store implementation directly.

package/harness/opencode/plugin/synapse.js

@@ -105,6 +105,12 @@ const EDIT_TOOLS = new Set(["write", "edit"])
 // yet -- delivered on that session's next `chat.message`.
 const pendingNudge = new Map()
 
+// sessionID -> queued `staleness` output, same reason and same delivery as
+// `pendingNudge` above: `tool.execute.after` has no message `output` to push
+// a part onto, so a drift/grounding warning from it would otherwise be
+// silently discarded instead of just reaching the next turn late.
+const pendingStaleness = new Map()
+
 export const Synapse = async ({ directory, client }) => {
   return {
     "chat.message": async (input, output) => {
@@ -123,6 +129,12 @@ export const Synapse = async ({ directory, client }) => {
         newParts.push(textPart(sessionID, output, `[SYNAPSE-STOP-NUDGE]\n${queuedNudge}`))
       }
 
+      const queuedStaleness = pendingStaleness.get(sessionID)
+      if (queuedStaleness) {
+        pendingStaleness.delete(sessionID)
+        newParts.push(textPart(sessionID, output, `[SYNAPSE-STALENESS]\n${queuedStaleness}`))
+      }
+
       const promptText = (output.parts || [])
         .filter((p) => p.type === "text")
         .map((p) => p.text)
@@ -136,10 +148,11 @@ export const Synapse = async ({ directory, client }) => {
     "tool.execute.after": async (input) => {
       const filePath = input.args?.filePath
       if (EDIT_TOOLS.has(input.tool) && filePath) {
-        runHook("staleness", {
+        const text = runHook("staleness", {
           session_id: input.sessionID,
           tool_input: { file_path: filePath },
         })
+        if (text) pendingStaleness.set(input.sessionID, text)
       }
     },
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@imunitic/synapse",
-  "version": "0.4.2",
-  "description": "Memory for Claude Code, Codex CLI, and OpenCode: a durable Obsidian vault plus a per-repo code graph.",
+  "version": "0.4.4",
+  "description": "Memory for Claude Code, Codex CLI, and OpenCode: a durable markdown vault plus a per-repo code graph.",
   "repository": {
     "type": "git",
     "url": "https://github.com/imunitic/synapse"
@@ -23,9 +23,9 @@
     "*.conf.template"
   ],
   "optionalDependencies": {
-    "@imunitic/synapse-darwin-arm64": "0.4.2",
-    "@imunitic/synapse-linux-x64": "0.4.2",
-    "@imunitic/synapse-linux-arm64": "0.4.2"
+    "@imunitic/synapse-darwin-arm64": "0.4.4",
+    "@imunitic/synapse-linux-x64": "0.4.4",
+    "@imunitic/synapse-linux-arm64": "0.4.4"
   },
   "license": "SEE LICENSE IN LICENSE"
 }

package/skills/synapse-node/SKILL.md

@@ -21,7 +21,7 @@ needs one.
 
 ## Procedure
 
-1. **Verify the whole project once, with the script.** Run `~/.synapse query stale` from
+1. **Verify the whole project once, with the script.** Run `synapse query stale` from
    inside the repo. It prints one `{node title}\t{reason}` line per stale node and nothing at all
    when everything is current, so its output is the complete stale set for the project.
 
@@ -50,7 +50,7 @@ needs one.
    So skip the frontmatter entirely:
 
    ```sh
-   ~/.synapse query body "{Node title}"
+   synapse query body "{Node title}"
    ```
 
    That prints only what is between the generated fences — so it excludes `## Notes` as well as the
@@ -71,7 +71,7 @@ needs one.
 4. **Regeneration (only if step 1 or 2 found the node stale).** You re-author the prose; a script
    writes the file. **The node contract itself — frontmatter fields, the crux pointer, `## Links`,
    `grounded_in` — is the `synapse-node-format` skill**, shared with `/synapse-init` and
-   `/synapse-rebuild`. What follows here is only what differs when *re*-authoring an existing
+   `/synapse-rebuild-diff`. What follows here is only what differs when *re*-authoring an existing
    node rather than writing a new one. Everything mechanical — hashes, `sources_digest`, the `## Sources` mirror,
    `built_at`, `commit`, `stale: false`, and preserving `## Notes` — belongs to
    `synapse write-node`, because a hub node's `sources` can no more be *emitted* into a tool call
@@ -81,11 +81,11 @@ needs one.
    - **Get the node's path list into a file, never into context:**
 
      ```sh
-     ~/.synapse query sources "{Node title}" > "$W/paths.txt"
+     synapse query sources "{Node title}" > "$W/paths.txt"
      ```
 
      If `$W/manifest.tsv` exists (or the namespace has `_manifest.tsv`), prefer re-running
-     `~/.synapse build-lists` instead and use the regenerated `lists/NN.txt`: it
+     `synapse build-lists` instead and use the regenerated `lists/NN.txt`: it
      re-derives every list from the clustering patterns, so files *added* since the last build are
      picked up automatically rather than sitting in `_unassigned`. `synapse query sources` can only
      return what the node already claims.
@@ -101,11 +101,11 @@ needs one.
      and discards findings the diff has nothing to say about. Project the diff as carefully as
      `sources`: names first, `--stat` to size it, hunks only for the selection.
    - Fall back to reading the files when patching cannot be justified — a large fraction changed, the
-     `crux` file is gone, or the baseline is unusable. Then try `~/.synapse tags {path}`
+     `crux` file is gone, or the baseline is unusable. Then try `synapse tags {path}`
      first (exit 0 use the tags, exit 1 fall back to reading the file, exit 2 run the discovery
      procedure `/synapse-init` documents, then retry), and read the load-bearing files in full — the
      tags signal informs regrouping, it never substitutes for reading a file before rewriting its prose.
-     If this is happening across many nodes at once, stop and run `/synapse-rebuild` instead: that is
+     If this is happening across many nodes at once, stop and run `/synapse-rebuild-diff` instead: that is
      the instrument for major drift, and it triages node by node rather than paying full cost for each.
    - Re-author `## Summary`, `## Crux` and `## Links` to match what the files contain now, into
      `$W/body.md`. Re-check the node's one-line `summary` as well; keep the existing one with
@@ -127,22 +127,22 @@ needs one.
    - **Write it back with the script:**
 
      ```sh
-     ~/.synapse write-node --title "{Node title}" --summary "{one line}" \
+     synapse write-node --title "{Node title}" --summary "{one line}" \
         --paths "$W/paths.txt" --body "$W/body.md"
      ```
 
      It replaces only the generated region and re-emits everything after the closing fence verbatim,
      which is what makes the `## Notes` guarantee enforceable rather than a promise.
    - **Never hand-write the frontmatter**, with `vault_patch` at `targetType: frontmatter` or
-     otherwise. Two reasons, both load-bearing: that patch re-serialises the whole YAML block and
-     YAML-coerces values (an all-digit `hash` becomes `1.1111111111111112e+39`), and
-     enumerating fields by hand is how `summary` and `commit` get silently dropped — which then breaks
-     the next `synapse build-project-index` run, far from the cause.
+     otherwise. `--frontmatter` only ever writes a single scalar value, so it can't represent
+     `sources:`/`grounded_in:` at all, and enumerating the rest of a node's fields by hand one call
+     at a time is how `summary` and `commit` get silently dropped — which then breaks the next
+     `synapse build-project-index` run, far from the cause.
    - **`## Notes` is human-authored only.** Never write into it — not at regeneration, not to record
      what you just did. (Task notes in `tasks/` are a different artifact: the `synapse-task` skill *does*
      append there. Do not carry that habit into a Synapse node.)
    - If the node's `summary` or title changed, rebuild the index so the map matches:
-     `~/.synapse build-project-index`.
+     `synapse build-project-index`.
    - **Say out loud that a regeneration happened** — e.g. "Node '{title}' was stale, regenerated
      before use." This has real latency and token cost, unlike Tier 1/2's detection; it must never
      be absorbed silently into the read.
@@ -150,13 +150,13 @@ needs one.
    - Read the bucket with a shell command, not into context — the index runs to tens of megabytes:
 
      ```sh
-     ~/.synapse index unassigned
+     synapse index unassigned
      ```
 
      Empty → nothing to do, skip silently (an empty sweep isn't worth announcing).
    - Otherwise read `synapse/{project}/Index.md` for the current node list (titles + summaries).
    - Tag the whole bucket in **one** call — write the paths to a list and run
-     `~/.synapse tags --paths {list}`, whose output is attributable (an unindented
+     `synapse tags --paths {list}`, whose output is attributable (an unindented
      line is a path, the tab-indented lines under it are its tags). A per-file loop costs ~33× more
      for the same answer. Fall back to a full read for ambiguous cases, then classify against that
      node list. **The judgment is which cluster a path belongs to; the bookkeeping is not yours to
@@ -167,7 +167,7 @@ needs one.
        immediately. If there is no manifest, add the path to that node's list file instead.
      - **Fits nothing** → leave it unassigned. A genuinely new subsystem wants its own manifest line
        and its own node, which is `/synapse-init` work, not a sweep.
-     - Then rebuild the projection with `~/.synapse build-index`. **Never hand-edit
+     - Then rebuild the projection with `synapse build-index`. **Never hand-edit
        `_index.bin`** — it is derived, binary, and tens of megabytes; there is nothing to
        hand-edit.
    - **Announce every outcome**, same transparency rule as regeneration: which file, and which

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

@@ -126,8 +126,8 @@ candidate list, not something to copy verbatim.
 Never hard-wrap. Write each paragraph as one single unbroken line and let the editor soft-wrap
 it — a newline exists only where a real break is intended (between paragraphs, list items,
 headings). This is a vault-wide rule, not specific to this node, and it is not optional: a
-hard-wrapped paragraph renders as a ragged stack of short lines in Obsidian instead of flowing
-text.
+hard-wrapped paragraph renders as a ragged stack of short lines in a soft-wrapping viewer instead of
+flowing text.
 ```
 
 Same model as the orchestrating session, no override — matches the constraint that "a

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

@@ -1,12 +1,12 @@
 ---
 name: synapse-node-format
-description: The contract for a Synapse code-graph node — frontmatter fields, the crux pointer, `## Links`, `grounded_in`, `## Sources`, and what `synapse write-node` adds or refuses. Load before authoring or regenerating any node, whether from /synapse-init's first build, /synapse-rebuild's triage, or the synapse-node skill's lazy regeneration. Not for reading the graph (that is synapse-query) or for task notes in the vault (that is synapse-task).
+description: The contract for a Synapse code-graph node — frontmatter fields, the crux pointer, `## Links`, `grounded_in`, `## Sources`, and what `synapse write-node` adds or refuses. Load before authoring or regenerating any node, whether from /synapse-init's first build, /synapse-rebuild-diff's triage, or the synapse-node skill's lazy regeneration. Not for reading the graph (that is synapse-query) or for task notes in the vault (that is synapse-task).
 ---
 
 # What a node is, and how to author one
 
 Every component that writes a node loads this: `/synapse-init` (first build), the `synapse-node`
-skill (Tier 2 lazy regeneration), and `/synapse-rebuild` (reseat, patch, re-orient).
+skill (Tier 2 lazy regeneration), and `/synapse-rebuild-diff` (reseat, patch, re-orient).
 
 All three write the same artifact, so the format belongs in one place rather than being restated
 wherever it is used. What stays with each caller is what is genuinely specific to it — the skill's
@@ -42,15 +42,15 @@ to orient someone already inside. A node without one is an error, not a default.
 
 - **Filename/title:** short, senior-engineer-style description of the concept (e.g. "World —
   entity/component/resource core"). Filesystem-illegal characters (`/ : * ? " < > |`) are
-  sanitized — but **reword the title instead of relying on that**, because Obsidian resolves a
-  wikilink by *filename*, so `[[World — entity/component/resource core]]` silently resolves to
+  sanitized — but **reword the title instead of relying on that**, because a wikilink resolves
+  by *filename*, so `[[World — entity/component/resource core]]` silently resolves to
   nothing once the file becomes `...entity_component_resource core.md`. A broken wikilink is a
   valid link to a not-yet-existing note, so it fails quietly. The writer warns when a title needs
   sanitizing; treat that warning as "rename this node". Same trap when you *retitle* a node
   mid-build: inbound links already written keep pointing at the old name.
 - **`sources`:** **every** file the node covers — repo-relative path plus that file's
   `git hash-object <path>` output, run from the repo root at the moment of writing. Exhaustive,
-  not a sample: this is a **machine** field, and it is what makes Obsidian's search able to reach
+  not a sample: this is a **machine** field, and it is what makes a path-based lookup able to reach
   a node from any file it covers (searching a class name that appears in no node's prose still
   finds its node via this list). Do **not** trim it to a handful of "representative" files —
   doing so silently destroys that lookup, leaves the node unable to answer "which files am I
@@ -65,17 +65,15 @@ to orient someone already inside. A node without one is an error, not a default.
   someone through this subsystem), `crux` (the few lines that carry the actual logic — **authored
   as line numbers, stored as text**: you point, the writer slices, so composing is impossible at
   authoring time and nothing decays afterwards the way a stored line number would), `links` (typed
-  Obsidian wikilinks to other nodes in this same namespace: `depends_on`, `part_of`, `uses`, or
+  wikilinks to other nodes in this same namespace: `depends_on`, `part_of`, `uses`, or
   another type that fits better if one doesn't — for `depends_on`/`uses` specifically, `/synapse-init`
   computes candidates before any node exists via `synapse link-graph`; read that node's rows from
   `links.tsv` rather than guessing which siblings it relates to, `part_of` stays a judgement call
   with nothing mechanical behind it), a `## Sources` section, and an empty `## Notes` section.
 - **Break a "does N things" enumeration into real bullets, not inline `(1)/(2)/(3)`.** A sentence
   enumerating three or more parallel sub-points reads as a wall of text once each item carries its
-  own clause or parenthetical -- the node is read by a human skimming it in Obsidian as much as by
-  an agent (see the design note this format came from: hosting the graph as vault-readable markdown
-  was chosen specifically so it stays "just as readable by a human directly in Obsidian as it is by
-  Claude"), and a dense inline run-on defeats that. Use a markdown bullet list under the sentence
+  own clause or parenthetical -- the node is read by a human skimming it as much as by an agent,
+  and a dense inline run-on defeats that. Use a markdown bullet list under the sentence
   introducing them instead. This is narrow, not a general "prefer bullets" rule: an aside of one or
   two items, or connected causal narrative ("X, because Y, which is why Z"), stays flowing prose --
   over-bulleting ordinary narrative just trades one readability problem for another.
@@ -138,10 +136,10 @@ to orient someone already inside. A node without one is an error, not a default.
   per owning directory or module with a file count, `LC_ALL=C` sorted. A node covering 941 files
   would otherwise put 75 KB of paths in front of a reader who wants to know which modules are
   involved — and the frontmatter already carries every path for search, so the mirror doesn't
-  need to repeat them. Rewritten from `sources` on every write, never hand-edited. (Obsidian's
-  Properties panel flattens the raw `sources` field into a truncated one-line string, which is
-  why a mirror exists at all — but that is an argument for aggregating *the mirror*, not for
-  trimming the field.)
+  need to repeat them. Rewritten from `sources` on every write, never hand-edited. (A raw YAML
+  list in frontmatter renders as a flattened, truncated one-line string in typical note-viewer
+  UI, which is why a mirror exists at all — but that is an argument for aggregating *the mirror*,
+  not for trimming the field.)
 - **`## Notes` is human-authored only.** Claude never writes into it — not at build time, not at
   regeneration. It is created empty and preserved verbatim forever after.
 - **Fence the generated region.** Everything the generator owns sits between

package/skills/synapse-orientation/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: synapse-orientation
-description: How to work out where meaning lives in a codebase you have not seen before — first mechanically, from the repo's own symbol vocabulary, and where no grammar exists, by four questions in order with the cheap commands that answer each. Includes tree-sitter grammar discovery. Use when clustering a repo into Synapse graph nodes for the first time, when re-deriving a node's premises in /synapse-rebuild's re-orient class, or any time you need to orient in an unfamiliar tree before making claims about it.
+description: How to work out where meaning lives in a codebase you have not seen before — first mechanically, from the repo's own symbol vocabulary, and where no grammar exists, by four questions in order with the cheap commands that answer each. Includes tree-sitter grammar discovery. Use when clustering a repo into Synapse graph nodes for the first time, when re-deriving a node's premises in /synapse-rebuild-diff's re-orient class, or any time you need to orient in an unfamiliar tree before making claims about it.
 ---
 
 # Orienting in an unfamiliar repo
 
-Loaded by `/synapse-init` at its orientation step, and by `/synapse-rebuild` when a node lands in
+Loaded by `/synapse-init` at its orientation step, and by `/synapse-rebuild-diff` when a node lands in
 the *re-orient* class and its premises have to be re-derived rather than patched. Useful on its own
 terms too: nothing here is Synapse-specific except what you do with the answers.
 
@@ -116,8 +116,8 @@ script fetched from a notes vault. Begin any re-run by reading it, and improve i
 re-deriving from scratch. Nothing like it ships, because which aggregations carry signal depends
 on the codebase — a distributed one would encode the wrong ecosystem's conventions.
 
-`.txt`, with markdown formatting inside, for a measured reason: Obsidian indexes `.md` files as
-notes, so a `_profile.md` turns up in search, Quick Switcher and the graph, where it is pure noise
+`.txt`, with markdown formatting inside, for a measured reason: a vault viewer indexes `.md` files
+as notes, so a `_profile.md` would turn up in search and note-browsing UI, where it is pure noise
 to a human reading notes. A non-`.md` extension is invisible to all of those and still perfectly
 readable. Note the `_` prefix does *nothing* mechanically — it is only a hint to a human who sees
 the file, matching `_manifest.tsv`. Record **negative results** here too ("this abbreviation has no

package/skills/synapse-query/SKILL.md

@@ -32,10 +32,10 @@ already named, to locate a specific detail inside it — never as an unscoped re
 instead of asking Synapse first. If you catch yourself about to grep the whole repo before checking
 `synapse/{project}/Index.md`, stop and check the index instead.
 
-**Why the cost difference is real, not just tidiness.** `synapse query body <node>` never goes
-through Obsidian's API — it's a direct disk read that extracts only the prose between the generated
-fences, skipping the node's `sources` list entirely. On a hub node, going through the API instead
-would move that node's entire frontmatter — megabytes — to print a few hundred words. On a large
+**Why the cost difference is real, not just tidiness.** `synapse query body <node>` is a direct disk
+read that extracts only the prose between the generated fences, skipping the node's `sources` list
+entirely. Reading the whole note instead would move that node's entire frontmatter — megabytes — to
+print a few hundred words. On a large
 repo (dozens to hundreds of thousands of tracked files), that difference is the entire reason a
 query stays cheap instead of dominating the turn.
 

package/skills/synapse-task/SKILL.md

@@ -73,9 +73,9 @@ into `status:` either — always go through this skill, which caps at
    back what you read.
 
    `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
+   delegates to the same field-local mechanism `frontmatter set` uses internally) — 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 `synapse vault-patch`:

package/skills/synapse-vault/SKILL.md

@@ -95,6 +95,29 @@ On a `SYNAPSE_VAULT_INTEGRATIONS=git` vault, every edit commits automatically, s
 calls, not merely a record of intentional edits. The default `disk` backend keeps no history at all,
 so this safety net only exists once that backend is chosen.
 
+## Creating notes: authoring commands, not freeform writes
+
+Every new note is created through an authoring command, never by freeforming a file at
+`vault-write`:
+
+- `/synapse-note` (bare mode) creates plain notes in any category -- `research/`,
+  `scratchpad/`, `inbox/`, anything that is not a tracked task or a design note. It mints the
+  frontmatter (`schema`, `title`, `note_id`, `created`, `updated`, `tags`) to the note schema's
+  contract, including full-timestamp format.
+- `/synapse-note --task` creates tracked task notes under `tasks/{project}/`.
+- `/synapse-design-note` and `/synapse-task-note` handle design discussions and compiled tasks --
+  both delegate the file-minting mechanics to `/synapse-note` internally.
+
+`vault-write` is for *editing existing notes*, or the rare read-modify-write round trip. If a
+direct creation is ever genuinely unavoidable, follow bare mode's frontmatter contract exactly
+(`schema`/`title`/`note_id`/`created`/`updated`/`tags`, full `%Y-%m-%d %H:%M:%S %Z` timestamps)
+rather than improvising a shape.
+
+Schemas are opt-in by declaration: a note whose frontmatter declares `schema:` is held to that
+schema's contract on every `vault-write`/`vault-patch`; a note without the field is never
+validated or failed. Legacy notes predate the feature and stay valid as they are -- no backfill
+is wanted, and "helpfully" adding `schema:` to old notes is not a service to anyone.
+
 ## Tagging is part of writing a note, not a separate pass
 
 Every note-authoring command (`synapse-note`, `synapse-design-note`, `synapse-task-note`) applies tags as one of the steps in creating or substantially updating a note. There is no separate tagging pass or command — `/synapse-vault-tidy`'s recategorization signal reads tag data, it never writes it.

package/synapse-claude.md

@@ -100,27 +100,20 @@ a real yes/no answer, not a formality to wave past.
 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`/`vault-backlinks`/`vault-links`/
 `vault-unresolved`/`vault-orphans`/`vault-deadends`/`vault-ambiguous`/`vault-rename` — 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 (`SYNAPSE_VAULT_INTEGRATIONS unset`, the default; `obsidian`, opted
-into for a running Obsidian app's own live search relevance and graph data; or `git`, opted into for
-the vault to own its own version control -- commit on every write, push/pull in the background) is
-resolved once,
-inside the compiled binary, from `SYNAPSE_VAULT_INTEGRATIONS`/`SYNAPSE_VAULT_DIR` — never something a skill
-or an agent turn needs to know or branch on. By default that means no Obsidian dependency
-whatsoever: `read`/`write`/`list`/`search`/the link graph/rename are all plain disk I/O and direct
-computation against the vault folder. Under the opted-in `obsidian` backend, `search`/the link
-graph/rename go through Obsidian's own CLI over its local socket instead when Obsidian is running,
-falling back to the same disk-backed behavior automatically and silently (a one-line stderr note,
-nothing an agent turn needs to react to) whenever it isn't — no precondition to check or fail on
-either way.
+*and* for writes, never by resolving a vault path and reading or writing the note file directly.
+Which concrete store the CLI talks to (`SYNAPSE_VAULT_INTEGRATIONS unset`, the default; or `git`,
+opted into for the vault to own its own version control -- commit on every write, push/pull in the
+background) is resolved once, inside the compiled binary, from `SYNAPSE_VAULT_INTEGRATIONS`/
+`SYNAPSE_VAULT_DIR` — never something a skill or an agent turn needs to know or branch on. `read`/
+`write`/`list`/`search`/the link graph/rename are all plain disk I/O and direct computation against
+the vault folder, in every configuration.
 
 **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`, and nothing visibly breaks —
-which is why the habit never self-corrects on its own. The reason is not a
+tools on the on-disk path** — 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*: the auto-commit 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`
@@ -129,19 +122,18 @@ differ. If the CLI itself ever fails (not installed, no vault configured), that'
 failure to report and stop on, never a reason to fall back to a raw file edit.
 
 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.
+the `synapse` CLI's `vault-*` subcommands — none of them writes to the vault folder directly.
 
 - You may create and edit notes in this vault **without asking for
   permission first**, as long as each note is placed in the folder
   matching its category per `Index.md`.
-- Filenames are human-readable titles (not timestamp-prefixed — Obsidian's
-  sidebar/graph display the filename directly, so a timestamp prefix reads
-  poorly there). Sanitize filesystem-illegal characters (`/ : * ? " < > |`)
+- Filenames are human-readable titles (not timestamp-prefixed — the filename is the display title,
+  so a timestamp prefix reads poorly). Sanitize filesystem-illegal characters (`/ : * ? " < > |`)
   but otherwise keep the title as-is.
 - Frontmatter carries what the filename no longer does: `title`, `created`
   (real timestamp at creation time), and for task notes `task_id` /
   `status` (`TODO`/`IN-PROGRESS`/`REVIEW`/`DONE`/`CANCELED`).
-- Link with Obsidian wikilinks: `[[filename]]` or `[[filename|display
+- Link with wikilinks: `[[filename]]` or `[[filename|display
   text]]` (no extension, exact filename minus `.md`).
 - **Never hard-wrap note bodies. A newline exists if and only if a break is
   intended in the output** — source line structure mirrors the output's block
@@ -156,16 +148,16 @@ the `synapse` CLI's `vault-*` subcommands — none of them calls an `mcp__obsidi
   makes the text **renderer-independent**: if a newline never appears where
   no break is wanted, then "does a single newline render as `<br>` or as a
   space?" never arises, and strict CommonMark, non-strict CommonMark,
-  Obsidian, pandoc and GitHub all produce the same result — the ambiguous
+  pandoc and GitHub all produce the same result — the ambiguous
   input case is simply gone. This is HTML's content model applied to plain
   text: a newline is markup meaning "break here", not cosmetic formatting of
   the source file.
 
   It also keeps **line length a view decision rather than a content one**.
   Hard-wrapping is the author asserting a measure, baking one viewport into
-  the text; unwrapped, the same bytes are correct at every width — Obsidian's
-  "Readable line length" on or off, a narrow split pane, a wide monitor,
-  mobile, print. Hard-wrapped prose fails both ways and is unfixable at read
+  the text; unwrapped, the same bytes are correct at every width — any
+  reader's readable-line-length setting on or off, a narrow split pane, a
+  wide monitor, mobile, print. Hard-wrapped prose fails both ways and is unfixable at read
   time: at 80 columns it double-wraps raggedly in a narrow pane, and sits as a
   fixed narrow ribbon in a wide one. Wanting a ~66-character measure is right
   (it's a real typographic optimum, which is why that setting exists) — put it

package/synapse-ignore-files.conf.template

@@ -1,5 +1,9 @@
-# Copy this to ~/.claude/synapse-ignore-files.conf (setup.sh does this for you).
-# Never overwritten once installed -- edit or extend any time.
+# Read live from the Synapse package as a fallback (tier 3) -- never copied or
+# seeded anywhere, and this template file is never written to. To customize,
+# create your own synapse-ignore-files.conf at $XDG_CONFIG_HOME/synapse/, else
+# ~/.config/synapse/ (the legacy ~/.claude/ also works); your own copy always
+# wins and is never touched by Synapse.
+# Edit or extend your own copy any time.
 #
 # Extra path patterns dropped at enumeration by synapse build-lists, on top
 # of the built-in exclusions (compiled objects, archives, media, model weights,

package/synapse-module-boilerplate.conf.template

@@ -1,6 +1,9 @@
-# Copy this to ~/.claude/synapse-module-boilerplate.conf (setup.sh does this
-# for you). Never overwritten once installed -- add your own ecosystem's
-# conventions any time.
+# Read live from the Synapse package as a fallback (tier 3) -- never copied or
+# seeded anywhere, and this template file is never written to. To customize,
+# create your own synapse-module-boilerplate.conf at $XDG_CONFIG_HOME/synapse/, else
+# ~/.config/synapse/ (the legacy ~/.claude/ also works); your own copy always
+# wins and is never touched by Synapse.
+# Add your own ecosystem's conventions any time.
 #
 # Boilerplate path-segment chains that module_of() (synapse query,
 # synapse write-node's ## Sources mirror) strips through wholesale when

package/synapse-projects.conf.template

@@ -1,4 +1,8 @@
-# Copy this to ~/.claude/synapse-projects.conf (setup.sh does this for you).
+# Read live from the Synapse package as a fallback (tier 3) -- never copied or
+# seeded anywhere, and this template file is never written to. To customize,
+# create your own synapse-projects.conf at $XDG_CONFIG_HOME/synapse/, else
+# ~/.config/synapse/ (the legacy ~/.claude/ also works); your own copy always
+# wins and is never touched by Synapse.
 #
 # Known project -> task-prefix mappings for THIS machine only. Deliberately
 # separate from the portable Synapse package (never committed

package/synapse-prompt-stopwords.conf.template

@@ -1,5 +1,9 @@
-# Copy this to ~/.claude/synapse-prompt-stopwords.conf (setup.sh does this for
-# you). Never overwritten once installed -- edit or extend any time.
+# Read live from the Synapse package as a fallback (tier 3) -- never copied or
+# seeded anywhere, and this template file is never written to. To customize,
+# create your own synapse-prompt-stopwords.conf at $XDG_CONFIG_HOME/synapse/, else
+# ~/.config/synapse/ (the legacy ~/.claude/ also works); your own copy always
+# wins and is never touched by Synapse.
+# Edit or extend your own copy any time.
 #
 # Common English function words, filtered out by `synapse vocab` before
 # building a search pattern from a raw prompt -- without this, an ordinary

package/synapse.conf.template

@@ -5,15 +5,12 @@ SYNAPSE_VAULT_DIR="$HOME/Vault/YourVault"
 # Unset by default: reads/writes the vault folder directly, no external
 # dependency at all -- search and the link graph
 # (backlinks/links/unresolved/orphans/deadends/ambiguous) are computed by
-# DiskStore's own scan. A comma-separated, outer-to-inner list of
-# integrations layers extra behavior on top instead: "obsidian" prefers a
-# running external app's own live search relevance and graph data, falling
-# back to the same disk-backed behavior automatically whenever that app
-# isn't reachable (see docs/synapse/synapse-extended-store.md); "git" owns
-# the vault's own git lifecycle (commit on write, push once enough pile up).
-# "git,obsidian" combines both. The disk store itself is never named -- it's
-# always the implicit innermost element.
-#SYNAPSE_VAULT_INTEGRATIONS="obsidian"
+# DiskStore's own scan. The one optional integration, "git", layers extra
+# behavior on top instead: it owns the vault's own git lifecycle (commit on
+# write, push once enough pile up) -- see
+# docs/synapse/synapse-extended-store.md. The disk store itself is never
+# named -- it's always the implicit innermost element.
+#SYNAPSE_VAULT_INTEGRATIONS="git"
 
 # Where Synapse clones/builds tree-sitter grammars (shared across every
 # project -- not per-repo). Safe to leave at the default.