@imunitic/synapse 0.0.1-test.0

package/commands/synapse-rebuild-full.md

@@ -0,0 +1,152 @@
+---
+name: synapse-rebuild-full
+description: Wipe a repo's Synapse namespace and rebuild it from scratch via /synapse-init, for the case where diff-driven triage isn't the right tool — the graph has drifted too far, or a clean rebuild is just wanted directly. Preserves any hand-written `## Notes` content first and auto-merges what it can back into the new nodes. For ordinary same-branch drift, use /synapse-rebuild-diff instead — it's cheaper and never deletes a node outright.
+---
+
+# Synapse Rebuild Full: Wipe and Rebuild a Namespace From Scratch
+
+`/synapse-rebuild-diff` triages drift node by node — reseat, patch, or re-orient — and never deletes
+anything. This command is the other tool: it deletes the current namespace outright and rebuilds it
+from nothing via `/synapse-init`'s own First-time-build procedure. Reach for it when the graph has
+drifted past the point where triage is worth it (most nodes would land in *re-orient* anyway), when
+the namespace is corrupted or was built badly, or when a clean rebuild is simply what's wanted —
+never as a reflex for ordinary drift, which `/synapse-rebuild-diff` handles more cheaply and without
+touching anything irreplaceable.
+
+**Unlike `/synapse-rebuild-diff`, this command does not care which branch is checked out beyond the
+ordinary sense.** It isn't diffing against anything — it resolves `{repo}@{branch}` for whatever's
+currently checked out and rebuilds *that* namespace, exactly as `/synapse-init` does. There is no
+branch-identity guardrail here because there is nothing to compare against; the branch you're on is
+simply the branch being rebuilt.
+
+## Usage
+
+```
+/synapse-rebuild-full
+```
+
+No arguments — always operates on the repo and branch containing the current working directory.
+
+## Prerequisites
+
+- Requires the `obsidian` MCP server (`mcp__obsidian__*` tools). If unreachable, say so and stop —
+  same requirement `/synapse-init` has.
+- Must be run from inside a git repository, on a named branch (not detached `HEAD`) — same
+  requirement `/synapse-init` has, since `synapse_namespace` needs a branch to key on.
+
+## Procedure
+
+### 1. Resolve the namespace
+
+Same resolution `/synapse-init` uses: repo root (`git rev-parse --show-toplevel`), namespace key
+(`{repo}@{branch}`, printed by `synapse namespace`), remote (for the `Index.md`
+verification field).
+
+Check whether `synapse/{repo}@{branch}/Index.md` exists.
+
+- **Doesn't exist** → there is nothing to wipe. This is just a first build, not a rebuild — hand off
+  directly to `/synapse-init` and stop here. Do not run the wipe step at all in this case; it would
+  only fail on a directory that isn't there.
+- **Exists, `remote` mismatches** → belongs to a different repo sharing this key. Same refusal
+  `/synapse-init` gives in this case: stop, name both remotes, do not touch it.
+- **Exists, `remote` matches** → continue to step 2.
+
+### 2. Preview the wipe and get explicit confirmation
+
+```sh
+~/.synapse graph-wipe --dry-run
+```
+
+Report its output plainly: node count, and — the one thing this step exists to surface — how many
+nodes carry hand-written `## Notes` content that's about to be deleted, and which ones. `## Notes` is
+human-authored, lives outside every generated fence, and no rebuild regenerates it; a wipe is the one
+operation in this pair of commands that actually deletes files rather than overwriting them with
+preservation, so it earns an explicit stop here that `/synapse-rebuild-diff` deliberately does not
+have.
+
+**Get an explicit yes before continuing.** This is a hard-to-reverse filesystem operation on content
+that includes irreplaceable human prose — do not proceed past this point on an assumption, even if
+the human is the one who typed `/synapse-rebuild-full` in the first place. Typing the command signals
+intent to rebuild; it is not itself confirmation of a delete that touches N nodes with hand-written
+notes attached, which the human hasn't seen a number for yet.
+
+### 3. Wipe
+
+Once confirmed:
+
+```sh
+~/.synapse graph-wipe
+```
+
+This deletes `synapse/{repo}@{branch}/` and, if any node had non-empty `## Notes`, first dumps that
+content verbatim to `scratchpad/{repo}@{branch} — preserved notes before full rebuild.md`. See
+`synapse graph-wipe`'s own header for the exact mechanics (belt-and-braces path check, same
+discipline `synapse graph-clean` uses for its own deletion).
+
+### 4. Rebuild from scratch
+
+Run `/synapse-init`'s **First-time build** procedure (its steps 1–8) against the now-empty namespace,
+by reference rather than repeating it here — enumerate, read hint files, orientation pass, cluster
+into `manifest.tsv`, gate, write each node, build `_index.bin`, build `Index.md`. Same command, same
+judgment calls, nothing rebuild-specific about this phase: from the namespace's perspective this is
+identical to a first build, because as of step 3 it is one.
+
+### 5. Merge preserved notes back
+
+Skip this step entirely if step 2 found nothing preserved (no staging note was created).
+
+**Only once the new `Index.md` exists** — not during clustering, not node-by-node as nodes are
+written. Read the staging note (`scratchpad/{repo}@{branch} — preserved notes before full rebuild.md`)
+and classify each preserved note's old title + content against the finished new node list, the same
+technique `/synapse-init`'s `_unassigned` sweep already uses for classifying files against an existing
+node list: read the note against the new summaries, judge which node it best fits.
+
+- **Confident match** → append the note's content into that node's `## Notes` section (every node
+  written by `synapse write-node` already carries one, empty if nothing else was there — never a
+  "create the section" case) with a one-line provenance breadcrumb: `(carried over from "{old node
+  title}" during full rebuild on {date})`. The note is losing its original context by moving to a new
+  home, and that breadcrumb is the only way a future reader recovers why it's there.
+
+  **Report the placement even though it succeeded.** Say which old node's notes went to which new
+  node, for every single one, not only the ones that failed to place. A wrong auto-placement is most
+  dangerous exactly when it's silent — this is the one class of content in the whole system marked
+  irreplaceable, and "it succeeded" is not the same claim as "it succeeded correctly."
+- **No confident match** → leave it in the staging note, and say why: no equivalent concept survived
+  the re-cluster, or more than one new node looked equally plausible. Do not guess past a stated
+  uncertainty here — a note in the wrong node is worse than a note sitting in scratchpad waiting for a
+  human to place it.
+
+Once every preserved note has been classified: if every one found a confident home, delete the
+staging note — nothing is left needing manual attention. If any remain unplaced, leave the staging
+note live containing only the leftovers, trimmed of everything that did get merged.
+
+### 6. Report
+
+- Old node count vs. new node count.
+- Whether any notes were preserved, and the outcome of every single one from step 5 (merged where, or
+  left for manual placement and why) — not just a summary count.
+- If the staging note still exists, say so explicitly and give its path — it needs a human look.
+
+## Guardrails
+
+- **Never wipe without running `--dry-run` first and getting explicit confirmation on its output.**
+  The preview step exists specifically so "how many notes are about to be deleted" is answered before
+  it happens, not after.
+- **Never invent a placement for a preserved note that isn't a confident match.** Leaving it in
+  scratchpad, flagged, is the correct outcome when nothing else is — don't fill the gap with a guess
+  to make the report look cleaner.
+- **Never merge into a node's generated region.** The merge target is always `## Notes`, appended, never
+  touching anything inside the `<!-- synapse:generated:start -->`…`<!-- synapse:generated:end -->`
+  fence — that region belongs to `synapse write-node` alone.
+- **Never treat this as the default repair path.** `/synapse-rebuild-diff` is cheaper, preserves every
+  node rather than deleting them, and is the right tool for ordinary drift. Use this command when
+  triage genuinely isn't worth it, not as a heavier habit that replaces the lighter one.
+
+## Integration
+
+- Delegates the actual rebuild to `/synapse-init`'s First-time-build procedure — this command owns
+  only the wipe-with-preservation step before it and the note-merge step after it.
+- The wipe itself is `synapse graph-wipe` (via `synapse graph-wipe`), mirroring
+  `synapse graph-clean` as the only other destructive tool in the system.
+- Resolves the namespace the same way `/synapse-init` and `/synapse-rebuild-diff` do -- one chain, in `core/identity.zig`
+  — never re-derives repo/branch/remote independently.

package/commands/synapse-status.md

@@ -0,0 +1,144 @@
+---
+description: Print a read-only report of what in Synapse Vault currently needs a human decision -- design notes still Discussing, design notes marked Ready with no compiled task yet, design notes with open questions, task notes with unchecked items, and task notes stuck in REVIEW. Use whenever the user wants a status check on the vault ("what's outstanding", "what needs my attention", "vault status", "what did we leave open"). Never modifies anything -- a report only, not a task-management action. Not for creating, continuing, or listing a specific note kind (that's synapse-note/synapse-design-note/synapse-task-note's own --list modes) -- this is the one cross-cutting view over all of them at once.
+---
+
+# Synapse Status: Vault-Wide Attention Report
+
+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 on demand, or from a
+scheduled `/loop`/cron invocation of this same command -- never wired into `SessionStart`: two of
+the five categories need a per-note body read, not just a frontmatter check, and unlike `Index.md`
+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 `/synapse-design-note`/`/synapse-note --task`
+structurally require, so every Synapse install has them in the same shape. The free-form taxonomy
+(`inbox/`/`research/`/`scratchpad/`) is per-install customizable (see `Index.md`), not guaranteed to
+exist or mean the same thing across installs, and `inbox/` specifically is for the vault owner's own
+periodic look on their own schedule -- this report doesn't cover it.
+
+## Usage
+
+```
+/synapse-status    # Print the current vault status report
+```
+
+## Prerequisites
+
+Requires the `obsidian` MCP server (`mcp__obsidian__*` tools). If unreachable, say so and stop --
+there is no local-file fallback.
+
+## Producing the report
+
+Run all five queries in parallel where the tool call shape allows it; none depends on another's
+result.
+
+**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/`:
+
+```
+{"and": [
+  {"glob": ["designs/*", {"var": "path"}]},
+  {"regexp": ["## Status\\nDiscussing", {"var": "content"}]}
+]}
+```
+
+**2. `Ready` design notes with no compiled task yet.** `/synapse-task-note`'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/`:
+
+```
+{"and": [
+  {"glob": ["designs/*", {"var": "path"}]},
+  {"regexp": ["## Status\\nReady", {"var": "content"}]},
+  {"!": [{"regexp": ["Compiled task:", {"var": "content"}]}]}
+]}
+```
+
+**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 Ready-gate convention
+`/synapse-design-note` now follows) 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:
+
+```
+{"and": [
+  {"glob": ["designs/*", {"var": "path"}]},
+  {"regexp": ["## Open Questions\\n- ", {"var": "content"}]}
+]}
+```
+
+`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).
+
+**4. Open task notes with at least one unchecked item.** Task notes carry `status:` in frontmatter,
+unlike design notes -- filter there first:
+
+```
+{"in": [{"var": "frontmatter.status"}, ["TODO", "IN-PROGRESS"]]}
+```
+
+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.
+
+**5. Task notes stuck in `REVIEW`.** Frontmatter-only, no body read needed -- a fully-checked
+checklist waiting specifically on human sign-off, since `synapse-task` deliberately never promotes a
+note past `REVIEW` on its own:
+
+```
+{"==": [{"var": "frontmatter.status"}, "REVIEW"]}
+```
+
+## Composing the report
+
+One section per category, in the order above. Each line names the note (title, or filename if no
+`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:
+
+```
+## Discussing
+- {title}
+
+## Ready, not yet compiled
+- {title}
+
+## Open questions
+- **{status}** — {title}
+
+## In progress (unchecked items)
+- {title} ({N} unchecked)
+
+## Awaiting review
+- {title}
+```
+
+Omit a section entirely when it has zero matches -- matching `/synapse-note --list`'s own convention
+of leaving out empty headers -- rather than printing five headers with nothing under most of them. If
+every category is empty, say so in one line ("Vault is clear -- nothing outstanding.") instead of five
+empty headers.
+
+Print the report directly in the response, not left only in tool-call output the user would have to
+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.
+- No Artifact/web-UI output. No `SessionStart` wiring. Not a new binary CLI subcommand -- every
+  category above is a plain mechanical query already reachable through `mcp__obsidian__*` tools.
+- Scoped to `designs/`/`tasks/` only -- never `inbox/`/`research/`/`scratchpad/`.

package/commands/synapse-task-note.md

@@ -0,0 +1,133 @@
+---
+description: Compile a Ready design note into a single tracked, checklist-based task note in Synapse Vault — delegates the actual note creation to synapse-note --task under the hood. Use whenever the user wants to turn a settled design discussion into actionable, tracked work ("let's compile a task note", "let's turn this into a task", "make this a task now") — not for starting or continuing the design discussion itself (that's synapse-design-note).
+---
+
+# Synapse Task Note: Compile a Design into a Tracked Checklist
+
+Compiles a `Ready` design note (from `/synapse-design-note`) into a single tracked task, using the
+vault's existing task-tracking machinery instead of a bespoke format: creation goes through
+`/synapse-note --task`, and status transitions from then on belong entirely to the `synapse-task`
+skill. This command's only job is the compile step — turning a design into an ordered checklist —
+not tracking progress itself.
+
+One design compiles into **one** task note, one `task_id`, and the checklist items *are* the
+steps — matching how every other task in the vault already works (see `synapse-task`'s "Task file
+structure").
+
+## Usage
+
+```
+/synapse-task-note "topic"    # Compile the task note for a Ready design note
+```
+
+No `--continue`/`--list` here — once created, the task note's own progress (checked items,
+`status:` frontmatter) is what `/synapse-note --list` and the `synapse-task` skill already track.
+Use those instead of reinventing a parallel view.
+
+## Prerequisites
+
+- Requires a matching Obsidian 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
+  it first."
+- Matching note but `Status: Reference` → "Design note for '{topic}' concluded as Reference —
+  nothing to compile. Reopen it with `/synapse-design-note \"{topic}\"` and mark it Ready if that's
+  changed."
+- A task note already exists for this design (check the design note's `> Compiled task:` annotation,
+  or `search_query` for a `tasks/` note linking to it) → show its current state (title, `status:`,
+  checked/total) and ask: view it, or recompile (only on explicit confirmation — recompiling rewrites
+  the checklist, so any progress on items that no longer exist is lost).
+
+  **A recompile updates the existing note in place. It never creates a second one and never bumps
+  the `task_id`.** One design has exactly one task note for its whole life; a design that gets
+  revised mid-implementation is the normal case, not a new task. Preserve `task_id`, `created`,
+  `status`, the filename, and any `## Notes` content the human added; replace the checklist and the
+  pre-implementation notes. Carry forward `- [x]` marks for items that survive the recompile
+  unchanged — work already done doesn't become undone because the plan around it grew.
+
+  Record *why* in the note itself, in one line at the top of the body: what the old plan got wrong
+  and what changed. A recompiled task with no explanation reads like a plan that was always this
+  shape, which hides the fact that implementation found a gap.
+
+## Compiling the checklist
+
+1. Read the design note in full.
+2. Break the approach into an ordered list of small, sequential, independently-completable steps.
+3. For each step, write it the way `synapse-task`'s own checklist convention expects: a short
+   `- [ ] {Do}` line; for substantive steps (type definitions, API surfaces, interface signatures)
+   add a one-line nested description plus a fenced code block showing the exact interface, per that
+   skill's "Inline code examples in checklist items". Don't invent separate Files/Tests/AC fields —
+   fold what matters into the item's own description instead (e.g. "...; test: X returns Y").
+4. Note explicit exclusions — things a reasonable implementer might also attempt that are out of
+   scope — for the `## Notes` section below, not a separate heading.
+
+## Creating the note
+
+Follow `/synapse-note`'s task-mode procedure exactly (its "Creating the note" section) — don't
+duplicate that scaffolding here, just supply its inputs:
+
+- **Title:** a short, plain description of the compiled plan (e.g. "Rollup direct storage
+  implementation") — `/synapse-note --task` resolves the project prefix and `task_id` and prepends
+  them itself.
+- **Project:** derive from the source design note's `project:` frontmatter — that prefix is already
+  resolved (the design note went through `/synapse-design-note`'s resolution when it was created,
+  which reads/appends the resolved `synapse-projects.conf`, per `/synapse-note`'s tiered lookup),
+  so supply it directly instead of
+  re-deriving or re-asking. This is the *prefix* (`ecs`, `sb`, ...), not the `tasks/{project}/`
+  folder name — `/synapse-note --task`'s own "Resolving the project folder" step turns it into
+  the folder name. 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 unrelated contexts (e.g. personal vs. work) must
+  never end up in the same place.
+- **Body:** the checklist from "Compiling the checklist" above, under the single top-level heading —
+  exactly the structure `synapse-task`'s "Task file structure" requires (no `## Step` sub-headings).
+- **`## Notes` (pre-implementation):** populate per `synapse-task`'s own convention —
+  - Design reference: `[[{design note title}]]`
+  - Key constraints the implementor must not miss
+  - Deliberate exclusions (from step 4 above) and why
+
+## 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.
+
+## Confirm
+
+Report the created path and title, and remind the user that `status:` transitions (TODO →
+IN-PROGRESS → REVIEW) happen automatically via the `synapse-task` skill once work starts — this
+command doesn't set or watch that field itself.
+
+## Integration
+
+- Reads `/synapse-design-note`'s `Ready` output only — never invents a design.
+- Delegates note creation to `/synapse-note --task` and status tracking to the `synapse-task` skill
+  — this command owns only the design → checklist compile step.
+
+---
+
+## Example
+
+```
+User: /synapse-task-note "rollup direct storage"
+
+Claude: [reads designs/{PROJECT} — Rollup direct storage.md, Status: Ready]
+        [no existing linked task note]
+
+        Compiled checklist:
+        - [ ] Add ReplacingMergeTree target table for the daily rollup
+        - [ ] Point the rollup MV at the new table instead of AggregatingMergeTree
+        - [ ] Migrate existing daily/monthly rollups (drop+recreate, sort-key change)
+        - [ ] Update the 5 retrofitted dashboards' rollup queries to drop argMaxMerge
+
+        Project already known: {PROJECT} → {prefix}-005.
+
+        Created: tasks/{PROJECT}/{prefix}-005 — Rollup direct storage implementation.md
+        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

@@ -0,0 +1,187 @@
+---
+description: Run one on-demand vault-tidy pass over Synapse Vault -- surface recategorization candidates (notes that no longer fit their folder, clusters that deserve a new top-level category, categories that have gone stale) into a single inbox/ proposal, silently fill in the one class of missing-frontmatter default that has an unambiguous fix, and fold the rest of note health (broken links, orphaned notes, duplicate titles) into that same proposal since none of them has a safe mechanical repair either. Use whenever the user wants the vault's own organization checked or tidied ("tidy the vault", "check vault health", "any notes drifted out of their folder", "find orphaned/duplicate notes"). Never invoked automatically -- no SessionStart wiring, no autonomous scheduling; run it yourself, or under your own /loop if you want a cadence. Scoped to everything except designs/, tasks/, and synapse/ (the code graph's own generated namespace), which stay entirely /synapse-status's (the first two) or /synapse-init's (the third) territory.
+---
+
+# Synapse Vault Tidy: Recategorization Proposals and Note-Health Fixes
+
+A single on-demand pass over Synapse Vault's free-form taxonomy (`inbox/`/`research/`/`scratchpad/`/
+whatever a given install's `Index.md` currently lists) that a person would otherwise have to notice
+and fix by hand: a note's folder fit drifting since it was filed, several notes sharing enough in
+common to deserve a category of their own, a category that stopped earning its keep, a link that
+broke when its target moved, a note nothing points to or from, two notes that are really the same
+thing under slightly different titles. Nothing here runs unprompted — it exists because nothing else
+in the vault periodically re-checks any of this, not because it's meant to run behind the user's
+back.
+
+Never touches `designs/`, `tasks/`, or `synapse/` — the first two are `/synapse-design-note`'s and
+`/synapse-note --task`'s own interface for directing project work (any gap found there is
+`/synapse-status`'s territory, not this command's); `synapse/` is the code graph's own generated
+namespace, a different note kind entirely, owned and kept fresh by `/synapse-init` and the
+`synapse-node`/`synapse-node-format` skills. `Index.md` and any vault-root `README.md` are also out
+of scope — foundational files, not taxonomy notes.
+
+## Usage
+
+```
+/synapse-vault-tidy    # Run one vault-tidy pass
+```
+
+## Prerequisites
+
+Requires the `obsidian` MCP server (`mcp__obsidian__*` tools). If unreachable, say so and stop —
+there is no local-file fallback.
+
+No compiled code anywhere in this command. `adapters/obsidian/store.zig`'s `ObsidianStore` does now
+implement `read`/`list`/`search`, but for `synapse frontmatter get`/`set`'s narrow one-field-at-a-time
+use — a full-vault tidy sweep, reading every note's whole body to judge category, tags and broken
+links, is a different shape of work entirely, and stays on these same MCP tools rather than the
+compiled binary, the same way `/synapse-status` and `/synapse-rebuild-diff`'s vault-side checks
+already work. The one exception is Step 3's broken-link history check, a plain `git log` call (via
+Bash, not a compiled tool) against the vault's own local repo when one exists — best-effort, never
+a hard requirement.
+
+## Step 1: Inventory sweep
+
+Enumerate every note in scope and read each one exactly once — every later step reuses this same
+sweep rather than re-reading anything.
+
+```
+{"and": [
+  {"!": [{"glob": ["designs/*", {"var": "path"}]}]},
+  {"!": [{"glob": ["tasks/*", {"var": "path"}]}]},
+  {"!": [{"glob": ["synapse/*", {"var": "path"}]}]},
+  {"!=": [{"var": "path"}, "Index.md"]},
+  {"!=": [{"var": "path"}, "README.md"]}
+]}
+```
+
+`mcp__obsidian__search_query` with that filter, then `mcp__obsidian__vault_read` each match. Keep
+the full result (`path`, `frontmatter`, `tags`, `links`, `backlinks`, `unresolvedLinks`, `stat`,
+`content`) per note — Steps 2–4 below only ever reason over the structured fields, never `content`
+itself; the judgment layer in Step 5 is the first point anything actually reads note *bodies*, and
+only for the subset flagged by then. `content` is fetched for free in this same call regardless, so
+there's no separate "light" read to bother with.
+
+## Step 2: Frontmatter defaults (fixed directly)
+
+The only note-health fix applied silently, because it's the only one with exactly one correct
+answer per note. Design and task notes are out of scope entirely; the plain/free-form schema is
+just two fields (`title`, `created` — see `synapse-note`'s bare-mode format), both derivable without
+guessing:
+
+- Missing `title` → the filename with its `.md` extension stripped.
+- Missing `created` → `stat.ctime`, formatted `YYYY-MM-DD HH:MM` to match every other note's
+  convention.
+
+Apply via read-modify-write on the whole file (`vault_read` → edit the one frontmatter line in the
+returned content → `vault_write` the whole file back) — never `vault_patch` with
+`targetType: frontmatter`, which re-serializes the entire YAML block and silently reformats
+unrelated fields, the same hazard `synapse-vault`/`synapse-task` already document.
+
+## Step 3: Note-health findings (reported, not fixed)
+
+From the same inventory, no additional vault reads (the broken-link history check below reads the
+vault's local git log, not more notes). Each of these three has no safe mechanical repair —
+fixing any of them means guessing at intent — so they become findings for the Step 6 proposal
+instead of a silent edit:
+
+- **Broken links** — `unresolvedLinks` non-empty. Before writing the finding, check the vault's own
+  local git history to say *why* it's broken instead of leaving that to guesswork — the vault is
+  usually a git repo (`db-sync` auto-commits every agent-driven edit into it, opt-in per vault, same
+  precondition as that hook). Resolve the vault's filesystem path the same way `synapse.conf`
+  already does (`OBSIDIAN_VAULT_DIR`), skip this sub-step entirely if `{vault}/.git` doesn't exist,
+  and never let a missing/unreachable git repo block the rest of the finding — worst case it's
+  reported with no history context, same as today.
+  - `git -C {vault} log --all --diff-filter=A --name-only --pretty=format: -- "**/{target}.md"` — a
+    hit means a note by that exact title was created at some point (even if later renamed or
+    deleted): report it as *"used to be a note — find what it's called now, or was deleted"*.
+  - No hit → `git -C {vault} log --all -p -S"[[{target}]]" -- .` and look at the earliest match's
+    diff: if the line first appears inside a `new file mode` addition (the note was created with the
+    link already broken), report it as *"born broken — never pointed at a real note; probably meant
+    as plain text or an external reference, not a vault link"* rather than implying anything was
+    lost.
+  - Neither check resolves anything more specific → report the target plainly, same as before.
+- **Orphaned notes** — `links` empty *and* `backlinks` empty.
+- **Duplicate/near-duplicate titles** — group notes by title normalized (lowercased, trimmed,
+  internal whitespace collapsed); any group with 2+ members is a finding. This is a mechanical
+  string-normalization match, not fuzzy similarity — genuinely fuzzy "these might be the same
+  note" calls belong to the judgment layer in Step 5, not here.
+
+## Step 4: Recategorization signal layer
+
+Mechanical, from the same inventory, still no note-body reasoning:
+
+- **Weak folder fit** — a note (not already an orphan from Step 3) that shares no tag with any
+  other note in its own folder, and where fewer than half of its combined `links`+`backlinks` point
+  to notes within that same folder.
+- **Uncovered clusters** — a tag or keyword held by 3+ notes spanning 2+ different folders, where no
+  existing top-level folder name (from `Index.md`'s current list) already matches it.
+- **Stale categories** — a scope-eligible top-level folder whose newest note's `stat.mtime` is more
+  than 90 days old (no new note gained in that window) is flagged as a merge-back candidate, the
+  same way a newly proposed split is flagged — one signal, checked at a different point in a
+  category's life.
+
+## Step 5: Recategorization judgment layer
+
+For each Step 4 candidate — a weak-fit note, a cluster, or a stale folder — read its full content
+(and, for a cluster, every member's content) and decide with real judgment, not the mechanical
+signal alone:
+
+- Weak-fit note: does it genuinely belong in a different existing category, or was the signal a
+  false positive (a note that's fine where it is, just thin on tags/links)?
+- Cluster: given what these notes actually say, is this a real emerging category, or just a
+  coincidental shared keyword?
+- Stale folder: has it truly stopped being useful, or is low volume expected and fine (a narrow but
+  still-active category)?
+
+Never moves a note or creates a folder here — every conclusion becomes one line in the Step 6
+proposal, for the vault owner to act on.
+
+## Step 6: Compose the proposal
+
+One note, `inbox/Vault tidy — {YYYY-MM-DD}.md` (fetch machine local time, never infer it), written
+via `vault_write` (creates `inbox/` automatically if it doesn't exist yet; if `inbox/` isn't already
+in `Index.md`'s folder list, add it there in the same pass, matching the folder-layout rule every
+other command that can create a top-level folder already follows). Two sections:
+
+```
+## Recategorization
+- {note or cluster}: {proposed move/new category/merge}, because {reasoning}
+
+## Note health
+- Broken link in {note}: → {target text that doesn't resolve} ({history classification, if the
+  vault's local git repo yielded one — "used to be a note", "born broken", or omitted entirely if
+  neither check resolved anything})
+- Orphaned: {note}
+- Possible duplicate: {note A} / {note B}
+```
+
+Omit either section if Steps 3–5 found nothing for it. If both are empty, don't write a proposal at
+all — say so directly instead of creating an empty note.
+
+This command never edits `Index.md` itself beyond the `inbox/` bootstrap case above — creating or
+renaming a category is the vault owner's call, made by hand using
+[[sb — Make vault folder taxonomy user-customizable via Index.md.template]]'s already-shipped
+mechanism, not something this command does on its own.
+
+## Step 7: Report
+
+Print a short summary directly in the response, not left only in tool-call output:
+
+- Count of frontmatter defaults silently filled, with filenames.
+- Count of recategorization candidates and note-health findings written to the proposal, with a
+  link to `inbox/Vault tidy — {date}.md`.
+- If nothing was found anywhere: "Vault's in good shape — nothing to fix or propose."
+
+## Constraints
+
+- Never touches — moves, edits, or reorganizes — anything inside `designs/`, `tasks/`, or
+  `synapse/`. `Index.md` and a vault-root `README.md` are also out of scope.
+- Recategorization never auto-moves a note or auto-creates a folder — proposal only, to `inbox/`.
+- Only the frontmatter-default class of note-health fix (Step 2) is applied directly and silently.
+  Broken links, orphaned notes, and duplicate titles are proposal findings, never auto-repaired.
+- Invoked on demand only — no `SessionStart` wiring, no autonomous scheduling. Run it directly, or
+  under a `/loop` the user sets up themselves.
+- No compiled code — every step above is a plain `mcp__obsidian__*` call, or (Step 3's broken-link
+  history check only) a plain `git log` via Bash against the vault's own local repo; this command
+  itself never calls into `ObsidianStore`.