@imunitic/synapse 0.4.2 → 0.4.4

package/Index.md.template

@@ -3,20 +3,20 @@ title: "Index"
 ---
 
 # Index
-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`).
+Map of the note folders and what each is for. This is the 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.
 
 This is a starter index, not a fixed schema. `research/`, `scratchpad/`, and `inbox/` below are yours to rename, restructure, or drop -- an agent reads this file as the authority on what your folders are and mean, not the other way around. `designs/`, `tasks/`, and `synapse/` aren't listed yet because nothing has created one on this vault -- `/synapse-design-note`, `/synapse-task-note`, and `/synapse-init` each add their own section here the first time they actually create that folder.
 
 ## research/
-Standalone research/reading notes -- general research about a topic, project-related or not: language features, library evaluations, design patterns, reference material. Filenames are plain, human-readable titles.
+Standalone research/reading notes -- general research about a topic, project-related or not: language features, library evaluations, design patterns, reference material. Filenames are plain, human-readable titles. Created via `/synapse-note` (bare mode), which declares `schema: vault-note/v1`.
 
 ## scratchpad/
-Notes for iterating on an idea just to see whether it works -- high-churn and exploratory, not yet worth filing under a settled category. A note here has a high chance of either being moved into a proper folder once it solidifies, or being deleted wholesale once the idea is settled one way or the other. Filenames are plain, human-readable titles.
+Notes for iterating on an idea just to see whether it works -- high-churn and exploratory, not yet worth filing under a settled category. A note here has a high chance of either being moved into a proper folder once it solidifies, or being deleted wholesale once the idea is settled one way or the other. Filenames are plain, human-readable titles. Created via `/synapse-note` (bare mode), which declares `schema: vault-note/v1`.
 
 ## inbox/
-A staging area for notes that need more input or reflection before they're settled -- most often the result of being asked to find something and write it down as a note, without yet knowing where it properly belongs, or that otherwise don't cleanly fit `research/` or `scratchpad/`. Filenames are plain, human-readable titles, same as every other folder -- no numbering scheme. Review periodically and move settled notes into a proper category; this folder is meant to stay small.
+A staging area for notes that need more input or reflection before they're settled -- most often the result of being asked to find something and write it down as a note, without yet knowing where it properly belongs, or that otherwise don't cleanly fit `research/` or `scratchpad/`. Filenames are plain, human-readable titles, same as every other folder -- no numbering scheme. Created via `/synapse-note` (bare mode), which declares `schema: vault-note/v1`. Review periodically and move settled notes into a proper category; this folder is meant to stay small.
 
 A second kind of note also lives here: standalone ideas that surface mid-discussion (with you, or an agent reasoning out loud) and are worth keeping without yet warranting a full design note of their own -- a small, self-contained "worth doing someday" item rather than an open question tied to a bigger design. Filenames are plain, human-readable titles like any other inbox note. Loosely ticket-shaped (a one-line summary, why it came up, rough acceptance criteria) is a fine, optional format for these -- not a requirement, just a convenient shape for something meant to be picked up and acted on later.
 

package/commands/synapse-design-note.md

@@ -31,10 +31,10 @@ Not every design discussion ends with something to build. See `Status: Reference
 
 ## Determining the project
 
-Every design note is tagged with the project it belongs to — both in the title
-(`{PROJECT} — {Topic}`) and as `project: {prefix}` in frontmatter (the same short prefix
-`/synapse-note --task` uses for task IDs) — so a flat `designs/` folder still reads clearly, and
-both note kinds can be filtered together via `synapse vault-search`.
+Every design note records the project it belongs to as `project: {prefix}` in frontmatter (the
+same short prefix `/synapse-note --task` uses for task IDs) — that field also decides the note's
+`designs/{project}/` subfolder, so design notes and task notes can be filtered together via
+`synapse vault-search`. The title itself is plain `{Topic}` — no project prefix, no id.
 
 Same resolution `/synapse-note` uses for a missing task ID (its "Resolving a missing task ID"),
 reading the same file:
@@ -56,7 +56,7 @@ reading the same file:
    check both fields (`synapse vault-search --fields frontmatter.task_id,frontmatter.note_id`, filter
    both for `{prefix}-\d+`, take the highest number found across both, add 1; start at 1 if none exist
    yet). This is frontmatter only — unlike a task note, a design note's title and filename stay
-   exactly `{PROJECT} — {Topic}`, with no id prepended.
+   exactly `{Topic}`, with no id and no project prefix prepended.
 
 Never hardcode a specific project/prefix pair in this command's own instructions — the conf file is
 machine-local and deliberately outside the portable Synapse package, so projects from
@@ -156,11 +156,11 @@ judgment call, not the automatic result of an `## Approach` section existing. Be
   blocking question is fine to carry forward), but a note with a *blocking* open question is not
   `Ready`, no matter how developed the rest of it is.
 
-- **Both hold** → `Status: Ready`. Confirm: "Design note ready: `designs/{title}.md`.
+- **Both hold** → `Status: Ready`. Confirm: "Design note ready: `designs/{project}/{title}.md`.
   Whenever you're ready to implement, generate the task with
   `/synapse-task-note \"{topic}\"` — no rush, nothing here expires."
 - **Genuinely nothing to build** → `Status: Reference`. Confirm: "Design note concluded as
-  Reference: `designs/{title}.md`. No task note needed."
+  Reference: `designs/{project}/{title}.md`. No task note needed."
 - **Anything else** (the approach is still hedged, or an open question blocks it) → stays
   `Status: Discussing`. This is the default outcome, not a fallback to apologize for — most
   conversations end here, and that's fine; nothing here expires either.
@@ -178,7 +178,7 @@ so the `## Status` line is the only lifecycle marker that matters. It simply sta
 ```
 ---
 schema: vault-design-note/v1
-title: "{PROJECT} — {Topic}"
+title: "{Topic}"
 project: {prefix}
 note_id: {id}
 created: "{now}"
@@ -186,7 +186,7 @@ updated: "{now}"
 tags: [{comma-separated configured tags, or empty}]
 ---
 
-# {PROJECT} — {Topic}
+# {Topic}
 
 ## Status
 Discussing | Ready | Reference
@@ -197,16 +197,21 @@ Discussing | Ready | Reference
 ## Approach
 {Chosen approach}
 
-### Alternatives considered (optional)
+### Alternatives considered
 - {Option}: why not
 
 ## Constraints
 {Hard constraints, non-negotiables}
 
-## Open Questions (optional)
+## Open Questions
 - {Anything deferred or unresolved}
 ```
 
+`### Alternatives considered` and `## Open Questions` are both optional per the schema — omit
+either section entirely rather than leaving it as an empty heading, and never write it as `##
+Open Questions (optional)`: the schema and `/synapse-status`'s own query both match this exact
+heading text, and a suffixed one is invisible to both.
+
 Any string scalar that is all digits (e.g. a numeric-looking title) must be quoted: an
 unquoted all-digit value is parsed as an integer, which fails a `type: string` schema
 field. `title`, `project`, `note_id`, and both timestamps are quoted above.
@@ -220,8 +225,10 @@ edit history here worth tracking separately.
 
 ## Filename
 
-`designs/{PROJECT} — {Topic}.md` — sanitize filesystem-illegal characters (`/ : * ? " < > |`). No
-slug, no numbering — vault filenames are the title itself.
+`designs/{project}/{Topic}.md` — grouped one level deeper into a per-project
+subfolder named by the note's own `project:` frontmatter value (e.g. `designs/eon/`,
+`designs/synapse/`), the same mapping `tasks/{project}/` uses. Sanitize filesystem-illegal
+characters (`/ : * ? " < > |`). No slug, no numbering — vault filenames are the title itself.
 
 ---
 
@@ -242,12 +249,12 @@ Claude: [searches designs/ for existing matches — none found]
 
 User: Replacing the AggregatingMergeTree rollup resolution with direct-value storage.
 
-Claude: [creates designs/{PROJECT} — Rollup direct storage.md, Status: Discussing]
+Claude: [creates designs/{project}/Rollup direct storage.md, Status: Discussing]
 
         What's driving this over just tuning the current argMaxMerge query?
 ...
 User: The resolution cost alone dominates the query, tuning won't fix that. Mark it ready.
 
-Claude: Design note ready: designs/{PROJECT} — Rollup direct storage.md.
+Claude: Design note ready: designs/{project}/Rollup direct storage.md.
         Generate the task with /synapse-task-note "rollup direct storage" whenever you're ready.
 ```

package/commands/synapse-init.md

@@ -100,7 +100,7 @@ yours and cannot be scripted because what counts as signal differs per codebase.
 **The work directory** defaults to `~/.cache/synapse/work/{repo}@{branch}/`, created on demand, and
 holds `manifest.tsv`, `all.txt`, `lists/`, the authored `b-NN.md` bodies and the coverage files. Override with `$SYNAPSE_WORK_DIR` if you need to. Two things never to do: point it
 at the repo (`synapse` runs from inside the repo, so its working files would land in the user's
-checkout) or at the vault (Obsidian would index a file list that runs to six figures of lines).
+checkout) or at the vault (a file list that runs to six figures of lines has no business inside it).
 It is deliberately persistent rather than a temp dir, so a later run finds the previous manifest
 instead of re-deriving the clustering.
 - **Interpretation (only you can do this):** deciding what the nodes *are*, and writing their prose.
@@ -153,7 +153,7 @@ emit into tool calls than read into a window. Never hand-author those.
 
    **Load the `synapse-orientation` skill** for how to read the vocabulary, the four questions that
    cover a tree with no grammar, and the grammar-discovery procedure. It is shared with
-   `/synapse-rebuild`'s re-orient class, which needs the same technique.
+   `/synapse-rebuild-diff`'s re-orient class, which needs the same technique.
 4. **Cluster into nodes — write `manifest.tsv`, the seam.** Group what you learned into a few dozen
    readable nodes, not one per file — same density Graft aims for. A node is a subsystem or concept,
    not a file; a file may legitimately belong to more than one node's `sources` when it's genuinely
@@ -249,7 +249,7 @@ emit into tool calls than read into a window. Never hand-author those.
    **Load the `synapse-node-format` skill too, before writing the first one** — it is the
    single description of the node contract itself (summary, the crux *pointer*, `## Links`,
    `grounded_in`, what the writer adds and what it refuses), shared with the `synapse-node`
-   skill and `/synapse-rebuild`, which write the same artifact. `synapse-node-authoring`
+   skill and `/synapse-rebuild-diff`, which write the same artifact. `synapse-node-authoring`
    covers *how* nodes get written; this covers *what* one is. Do not re-derive either from an
    existing node: a node you are reading may predate a change to its format.
 8. **Write `_index.bin`** — mechanics, run `synapse build-index`. It emits
@@ -289,8 +289,8 @@ emit into tool calls than read into a window. Never hand-author those.
    **Then verify, before reporting success.** Three checks, all cheap:
    - `synapse query stale` must print nothing. (40s for a 125k-file namespace.)
    - Every `[[wikilink]]` in the namespace must resolve to a file that exists — extract them all and
-     test `-f "$link.md"`. Nothing else catches a broken link, since Obsidian treats it as a link to
-     a note not yet created.
+     test `-f "$link.md"`. Nothing else catches a broken link -- a wikilink to a note that does not
+     exist yet just fails silently.
    - Every node file must appear in `Index.md`. An unlisted node exists but is invisible to a reader.
 
    ```yaml

package/commands/synapse-note.md

@@ -13,7 +13,7 @@ If `$ARGUMENTS` starts with `--search` → **search mode**: see "Search mode" be
 Otherwise, split `$ARGUMENTS` on `--task`:
 
 - If `--task` is present → **task mode**: scaffold the note as a tracked task, following the `synapse-task` skill's conventions. Task notes always live under `tasks/`.
-- Otherwise → **bare mode**: create an empty node (title + frontmatter only). Which category folder it lands in is resolved from `Index.md`, per "Choosing a category (bare mode only)" below — not a fixed set.
+- Otherwise → **bare mode**: create an empty node (title + frontmatter only). Which category folder it lands in is resolved from `Index.md`, per "Choosing a category (bare mode only)" below — not a fixed set. The typical categories are `research/`, `scratchpad/`, or `inbox/` — any plain note that isn't a task or design note.
 
 The title is everything before `--task` (trimmed). Example:
 

package/commands/synapse-rebuild-diff.md

@@ -97,8 +97,8 @@ this command when it does. What no longer happens is arriving here merely becaus
 ### 1. Size the job before doing any of it
 
 ```sh
-~/.synapse query drift
-~/.synapse query grounding
+synapse query drift
+synapse query grounding
 ```
 
 Report what it says, in the human's terms, **before** touching anything: how far the baseline is from
@@ -118,7 +118,7 @@ Two answers change the plan:
 ### 2. Mechanical phase — always, and cheap
 
 ```sh
-~/.synapse build-lists --reenumerate
+synapse build-lists --reenumerate
 ```
 
 `--reenumerate` matters here: without it an existing `all.txt` is reused, so a branch switch would be
@@ -136,7 +136,7 @@ move a lot and some may reach zero.
 Then rebuild the reverse index so the hook and the read path agree with the new enumeration:
 
 ```sh
-~/.synapse build-index
+synapse build-index
 ```
 
 ### 3. Triage each flagged node — reseat, patch, or re-orient
@@ -193,8 +193,8 @@ straight back stores a quote of a file as it looked at the old baseline, present
 current. So rebuild the directive from the pointer the writer recorded:
 
 ```sh
-~/.synapse query field "{Node}" crux_path
-~/.synapse query field "{Node}" crux_lines
+synapse query field "{Node}" crux_path
+synapse query field "{Node}" crux_lines
 ```
 
 and replace the fenced block with `<!-- crux: <crux_path> <crux_lines> -->` so it is cut from the
@@ -208,7 +208,7 @@ its directives are stripped from the body, so a recovered body contains none —
 the node's provenance is gone with no error. Recover the pointers per node:
 
 ```sh
-~/.synapse query grounding "{Node}" --list   # path<TAB>lines
+synapse query grounding "{Node}" --list   # path<TAB>lines
 ```
 
 and re-emit a `<!-- grounded_in: <path> <lines> -->` for each. Run `synapse query grounding` before
@@ -256,7 +256,7 @@ selection. Never pipe an unbounded `git diff <commit>..HEAD` into a context wind
 ### 4. Write each rebuilt node
 
 ```sh
-~/.synapse write-node --title "{Node}" --summary "{one line}" \
+synapse write-node --title "{Node}" --summary "{one line}" \
    --paths "$W/lists/NN.txt" --body "$W/body.md"
 ```
 
@@ -267,17 +267,17 @@ not merely stale, if the subsystem's shape differs on this line.
 ### 5. Rebuild the projections and verify
 
 ```sh
-~/.synapse build-index
-~/.synapse build-project-index
-~/.synapse query drift     # expect silence
-~/.synapse query stale     # expect silence
-~/.synapse query grounding # expect silence: re-pointed, not dropped
-~/.synapse query links --check   # expect silence: no dangling targets
+synapse build-index
+synapse build-project-index
+synapse query drift     # expect silence
+synapse query stale     # expect silence
+synapse query grounding # expect silence: re-pointed, not dropped
+synapse query links --check   # expect silence: no dangling targets
 ```
 
 `links --check` covers what used to be a manual instruction here: a broken `[[wikilink]]` is a valid
-link to a not-yet-existing note, so Obsidian renders it without complaint and nothing else in the
-system notices. It now reports `Node<TAB>relation -> Target (no such node)` per dangling edge.
+link to a not-yet-existing note, silently, and nothing else in the system notices. It now reports
+`Node<TAB>relation -> Target (no such node)` per dangling edge.
 
 One check is still yours, because no command performs it: **every node file appears in `Index.md`**. An
 unlisted node exists and is reachable by search, but is invisible to anyone reading the map.

package/commands/synapse-rebuild-full.md

@@ -54,7 +54,7 @@ Check whether `synapse/{repo}@{branch}/Index.md` exists.
 ### 2. Preview the wipe and get explicit confirmation
 
 ```sh
-~/.synapse graph-wipe --dry-run
+synapse graph-wipe --dry-run
 ```
 
 Report its output plainly: node count, and — the one thing this step exists to surface — how many
@@ -75,7 +75,7 @@ notes attached, which the human hasn't seen a number for yet.
 Once confirmed:
 
 ```sh
-~/.synapse graph-wipe
+synapse graph-wipe
 ```
 
 This deletes `synapse/{repo}@{branch}/` and, if any node had non-empty `## Notes`, first dumps that

package/commands/synapse-task-note.md

@@ -26,7 +26,7 @@ Use those instead of reinventing a parallel view.
 
 ## 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}'. Run
   `/synapse-design-note \"{topic}\"` first." Never generate a checklist from scratch.
 - Matching note but `Status: Discussing` → "Design note for '{topic}' is still in Discussing. Finish
@@ -99,8 +99,8 @@ printf '> Compiled task: [[%s]]\n\n' "{task note title}" | \
 
 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 (or a plain `synapse vault-search-text` for the task
-note's title, on a disk-backed vault) already surfaces the live task note from the design note, and
+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
@@ -122,7 +122,7 @@ command doesn't set or watch that field itself.
 ```
 User: /synapse-task-note "rollup direct storage"
 
-Claude: [reads designs/{PROJECT} — Rollup direct storage.md, Status: Ready]
+Claude: [reads designs/{project}/Rollup direct storage.md, Status: Ready]
         [no existing linked task note]
 
         Compiled checklist:
@@ -133,8 +133,8 @@ Claude: [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/commands/synapse-vault-tidy.md

@@ -29,15 +29,14 @@ of scope — foundational files, not taxonomy notes.
 ## Prerequisites
 
 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` and `sb — DiskStore's own index, Obsidian becomes
-optional`). Both real coding-vault backends have one now — `obsidian` reaching the CLI when
-reachable and falling back to `disk`'s own implementation otherwise, `disk` always local. If
-`SYNAPSE_VAULT_INTEGRATIONS` ever resolves to a backend with no `LinkGraph` 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`).
+`DiskStore`, 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 `LinkGraph` at all, 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`/
+same 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 Bash, not a compiled tool)
@@ -87,10 +86,9 @@ 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 `synapse-vault`/`synapse-task` 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 `synapse-vault`/`synapse-task` already document.
 
 ## Step 3: Note-health findings (reported, not fixed)
 
@@ -200,4 +198,4 @@ Print a short summary directly in the response, not left only in tool-call outpu
   under a `/loop` 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 Bash against the vault's own local repo; this command
-  never calls an `mcp__obsidian__*` tool or `ObsidianStore` directly.
+  never calls a store implementation directly.

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

@@ -38,10 +38,10 @@ There is no flag syntax here — read intent from how the user asks:
 
 ## Determining the project
 
-Every design note is tagged with the project it belongs to — both in the title
-(`{PROJECT} — {Topic}`) and as `project: {prefix}` in frontmatter (the same short prefix the
-synapse-note skill's task mode uses for task IDs) — so a flat `designs/` folder still reads clearly,
-and both note kinds can be filtered together via `synapse vault-search`.
+Every design note records the project it belongs to as `project: {prefix}` in frontmatter (the
+same short prefix the synapse-note skill's task mode uses for task IDs) — that field also decides
+the note's `designs/{project}/` subfolder, so design notes and task notes can be filtered together
+via `synapse vault-search`. The title itself is plain `{Topic}` — no project prefix, no id.
 
 Same resolution the synapse-note skill uses for a missing task ID (its "Resolving a missing task
 ID"), reading the same file:
@@ -58,6 +58,12 @@ ID"), reading the same file:
 4. If nothing confidently matches, ask the user for a short project tag — plain free-text, not a
    multiple-choice list, never hinting at any other project's tag as an example — then append the
    resolved pair to the conf file.
+5. Once the prefix is known, mint the note's `note_id` the same shared-counter way the synapse-note
+   skill's "Resolving a missing task ID" step 6 does: `task_id` and `note_id` share one counter per
+   prefix, so check both fields (`synapse vault-search --fields frontmatter.task_id,frontmatter.note_id`,
+   filter both for `{prefix}-\d+`, take the highest number found across both, add 1; start at 1 if none
+   exist yet). This is frontmatter only — unlike a task note, a design note's title and filename stay
+   exactly `{Topic}`, with no id and no project prefix prepended.
 
 Never hardcode a specific project/prefix pair in this skill's own instructions — the conf file is
 machine-local and deliberately outside the portable Synapse package, so projects from
@@ -157,11 +163,11 @@ judgment call, not the automatic result of an `## Approach` section existing. Be
   blocking question is fine to carry forward), but a note with a *blocking* open question is not
   `Ready`, no matter how developed the rest of it is.
 
-- **Both hold** → `Status: Ready`. Confirm: "Design note ready: `designs/{title}.md`.
+- **Both hold** → `Status: Ready`. Confirm: "Design note ready: `designs/{project}/{title}.md`.
   Whenever you're ready to implement, ask me to compile it into a task note — no rush, nothing
   here expires."
 - **Genuinely nothing to build** → `Status: Reference`. Confirm: "Design note concluded as
-  Reference: `designs/{title}.md`. No task note needed."
+  Reference: `designs/{project}/{title}.md`. No task note needed."
 - **Anything else** (the approach is still hedged, or an open question blocks it) → stays
   `Status: Discussing`. This is the default outcome, not a fallback to apologize for — most
   conversations end here, and that's fine; nothing here expires either.
@@ -179,7 +185,7 @@ so the `## Status` line is the only lifecycle marker that matters. It simply sta
 ```
 ---
 schema: vault-design-note/v1
-title: "{PROJECT} — {Topic}"
+title: "{Topic}"
 project: {prefix}
 note_id: {id}
 created: "{now}"
@@ -187,7 +193,7 @@ updated: "{now}"
 tags: [{comma-separated configured tags, or empty}]
 ---
 
-# {PROJECT} — {Topic}
+# {Topic}
 
 ## Status
 Discussing | Ready | Reference
@@ -198,16 +204,21 @@ Discussing | Ready | Reference
 ## Approach
 {Chosen approach}
 
-### Alternatives considered (optional)
+### Alternatives considered
 - {Option}: why not
 
 ## Constraints
 {Hard constraints, non-negotiables}
 
-## Open Questions (optional)
+## Open Questions
 - {Anything deferred or unresolved}
 ```
 
+`### Alternatives considered` and `## Open Questions` are both optional per the schema — omit
+either section entirely rather than leaving it as an empty heading, and never write it as `##
+Open Questions (optional)`: the schema and `/synapse-status`'s own query both match this exact
+heading text, and a suffixed one is invisible to both.
+
 Resolve tags through the `synapse-vault` skill's configured vocabulary procedure. Fetch machine
 local time once (`date '+%Y-%m-%d %H:%M:%S %Z'`) — never infer it — and use the exact same value
 for `created` and `updated`.
@@ -217,8 +228,10 @@ edit history here worth tracking separately.
 
 ## Filename
 
-`designs/{PROJECT} — {Topic}.md` — sanitize filesystem-illegal characters (`/ : * ? " < > |`). No
-slug, no numbering — Obsidian filenames are the title itself.
+`designs/{project}/{Topic}.md` — grouped one level deeper into a per-project
+subfolder named by the note's own `project:` frontmatter value (e.g. `designs/eon/`,
+`designs/synapse/`), the same mapping tasks use. Sanitize filesystem-illegal
+characters (`/ : * ? " < > |`). No slug, no numbering — vault filenames are the title itself.
 
 ---
 
@@ -239,12 +252,12 @@ Codex: [searches designs/ for existing matches — none found]
 
 User: Replacing the AggregatingMergeTree rollup resolution with direct-value storage.
 
-Codex: [creates designs/{PROJECT} — Rollup direct storage.md, Status: Discussing]
+Codex: [creates designs/{project}/Rollup direct storage.md, Status: Discussing]
 
        What's driving this over just tuning the current argMaxMerge query?
 ...
 User: The resolution cost alone dominates the query, tuning won't fix that. Mark it ready.
 
-Codex: Design note ready: designs/{PROJECT} — Rollup direct storage.md.
+Codex: Design note ready: designs/{project}/Rollup direct storage.md.
        Ask me to compile the task note whenever you're ready to implement.
 ```

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

@@ -100,7 +100,7 @@ yours and cannot be scripted because what counts as signal differs per codebase.
 **The work directory** defaults to `~/.cache/synapse/work/{repo}@{branch}/`, created on demand, and
 holds `manifest.tsv`, `all.txt`, `lists/`, the authored `b-NN.md` bodies and the coverage files. Override with `$SYNAPSE_WORK_DIR` if you need to. Two things never to do: point it
 at the repo (`synapse` runs from inside the repo, so its working files would land in the user's
-checkout) or at the vault (Obsidian would index a file list that runs to six figures of lines).
+checkout) or at the vault (a file list that runs to six figures of lines has no business inside it).
 It is deliberately persistent rather than a temp dir, so a later run finds the previous manifest
 instead of re-deriving the clustering.
 - **Interpretation (only you can do this):** deciding what the nodes *are*, and writing their prose.
@@ -289,8 +289,8 @@ emit into tool calls than read into a window. Never hand-author those.
    **Then verify, before reporting success.** Three checks, all cheap:
    - `synapse query stale` must print nothing. (40s for a 125k-file namespace.)
    - Every `[[wikilink]]` in the namespace must resolve to a file that exists — extract them all and
-     test `-f "$link.md"`. Nothing else catches a broken link, since Obsidian treats it as a link to
-     a note not yet created.
+     test `-f "$link.md"`. Nothing else catches a broken link -- a wikilink to a note that does not
+     exist yet just fails silently.
    - Every node file must appear in `Index.md`. An unlisted node exists but is invisible to a reader.
 
    ```yaml

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

@@ -27,7 +27,8 @@ below:
 - **Asking to create any other note** ("make a note about X", "save this as a note") → **bare
   mode**: create an empty node (title + frontmatter only). Which category folder it lands in is
   resolved from the vault's index note, per "Choosing a category (bare mode only)" below — not a
-  fixed set.
+  fixed set. The typical categories are `research/`, `scratchpad/`, or `inbox/` — any plain note
+  that isn't a task or design note.
 
 The title is whatever the user is naming or describing, minus any mode-signaling phrasing. Example:
 
@@ -138,7 +139,7 @@ offered.
 
 Resolve this to a `category` matching the folder name exactly as
 the index note currently spells it, before moving on to the creation steps
-below. No project-slug question is needed here — Obsidian filenames are
+below. No project-slug question is needed here — vault filenames are
 the title itself, not a slug-prefixed timestamp, so there's no separate
 namespacing concern to resolve. The note always lands flat at
 `{category}/{filename}.md` — never inferred into a subfolder such as a

package/harness/codex/skills/synapse-rebuild-diff/SKILL.md

@@ -97,8 +97,8 @@ this skill when it does. What no longer happens is arriving here merely because
 ### 1. Size the job before doing any of it
 
 ```sh
-~/.synapse query drift
-~/.synapse query grounding
+synapse query drift
+synapse query grounding
 ```
 
 Report what it says, in the human's terms, **before** touching anything: how far the baseline is from
@@ -118,7 +118,7 @@ Two answers change the plan:
 ### 2. Mechanical phase — always, and cheap
 
 ```sh
-~/.synapse build-lists --reenumerate
+synapse build-lists --reenumerate
 ```
 
 `--reenumerate` matters here: without it an existing `all.txt` is reused, so a branch switch would be
@@ -136,7 +136,7 @@ move a lot and some may reach zero.
 Then rebuild the reverse index so the hook and the read path agree with the new enumeration:
 
 ```sh
-~/.synapse build-index
+synapse build-index
 ```
 
 ### 3. Triage each flagged node — reseat, patch, or re-orient
@@ -193,8 +193,8 @@ straight back stores a quote of a file as it looked at the old baseline, present
 current. So rebuild the directive from the pointer the writer recorded:
 
 ```sh
-~/.synapse query field "{Node}" crux_path
-~/.synapse query field "{Node}" crux_lines
+synapse query field "{Node}" crux_path
+synapse query field "{Node}" crux_lines
 ```
 
 and replace the fenced block with `<!-- crux: <crux_path> <crux_lines> -->` so it is cut from the
@@ -208,7 +208,7 @@ its directives are stripped from the body, so a recovered body contains none —
 the node's provenance is gone with no error. Recover the pointers per node:
 
 ```sh
-~/.synapse query grounding "{Node}" --list   # path<TAB>lines
+synapse query grounding "{Node}" --list   # path<TAB>lines
 ```
 
 and re-emit a `<!-- grounded_in: <path> <lines> -->` for each. Run `synapse query grounding` before
@@ -257,7 +257,7 @@ selection. Never pipe an unbounded `git diff <commit>..HEAD` into a context wind
 ### 4. Write each rebuilt node
 
 ```sh
-~/.synapse write-node --title "{Node}" --summary "{one line}" \
+synapse write-node --title "{Node}" --summary "{one line}" \
    --paths "$W/lists/NN.txt" --body "$W/body.md"
 ```
 
@@ -268,16 +268,16 @@ not merely stale, if the subsystem's shape differs on this line.
 ### 5. Rebuild the projections and verify
 
 ```sh
-~/.synapse build-index
-~/.synapse build-project-index
-~/.synapse query drift     # expect silence
-~/.synapse query stale     # expect silence
-~/.synapse query grounding # expect silence: re-pointed, not dropped
-~/.synapse query links --check   # expect silence: no dangling targets
+synapse build-index
+synapse build-project-index
+synapse query drift     # expect silence
+synapse query stale     # expect silence
+synapse query grounding # expect silence: re-pointed, not dropped
+synapse query links --check   # expect silence: no dangling targets
 ```
 
 `links --check` covers what used to be a manual instruction here: a broken `[[wikilink]]` is a valid
-link to a not-yet-existing note, so Obsidian renders it without complaint and nothing else in the
+link to a not-yet-existing note, silently, and nothing else in the
 system notices. It now reports `Node<TAB>relation -> Target (no such node)` per dangling edge.
 
 One check is still yours, because no command performs it: **every node file appears in `Index.md`**. An

package/harness/codex/skills/synapse-rebuild-full/SKILL.md

@@ -51,7 +51,7 @@ Check whether `synapse/{repo}@{branch}/Index.md` exists.
 ### 2. Preview the wipe and get explicit confirmation
 
 ```sh
-~/.synapse graph-wipe --dry-run
+synapse graph-wipe --dry-run
 ```
 
 Report its output plainly: node count, and — the one thing this step exists to surface — how many
@@ -72,7 +72,7 @@ attached, which the human hasn't seen a number for yet.
 Once confirmed:
 
 ```sh
-~/.synapse graph-wipe
+synapse graph-wipe
 ```
 
 This deletes `synapse/{repo}@{branch}/` and, if any node had non-empty `## Notes`, first dumps that