@imunitic/synapse 0.0.1-test.0

package/commands/synapse-note.md

@@ -0,0 +1,196 @@
+---
+description: Create a plain note in Synapse Vault (bare mode — title + frontmatter, category resolved from Index.md), a tracked task note (--task, scaffolds the checklist skeleton synapse-task expects), list every tracked task (--list), or search existing notes (--search) before creating a new one. Use for a note with no design framing, or any task note not compiled from a design discussion. Not for starting/continuing a design conversation (that's synapse-design-note) or compiling a Ready one into a task (that's synapse-task-note) — both of those delegate to this command themselves.
+---
+
+Create a note in Synapse Vault with the title and options, list existing notes, or search existing notes: $ARGUMENTS
+
+## Argument parsing
+
+If `$ARGUMENTS` is `--list` (or starts with `--list`) → **list mode**: see "List mode" below, skip note creation entirely.
+
+If `$ARGUMENTS` starts with `--search` → **search mode**: see "Search mode" below, skip note creation entirely. This is also the mode to reach for programmatically (not just when the user explicitly asks to search) — per the Synapse Vault CLAUDE.md instructions, linking to an existing note is the highest-priority step before creating a new one, so run a search here before every bare-mode note creation, not only when a search is requested outright.
+
+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.
+
+The title is everything before `--task` (trimmed). Example:
+
+- `/synapse-note "My idea"` → bare note titled "My idea"
+- `/synapse-note "proj-035 — Implement Foo" --task` → task note titled "proj-035 — Implement Foo"
+
+In task mode, also attempt to extract a task ID from the title by matching a `{prefix}-\d+` pattern (letters, a hyphen, then digits). Use it as `task_id` in frontmatter.
+
+If no match is found, **don't just leave it blank** — see "Resolving a missing task ID" below before proceeding.
+
+## List mode
+
+Use `mcp__obsidian__search_query` with the JsonLogic query `{"var": "frontmatter.task_id"}` — this returns every file that has a `task_id` set, along with that file's `task_id` value as `result`. For each match, also read the file's `status` and `title` (either via a second query `{"var": "frontmatter.status"}` / `{"var": "frontmatter.title"}`, or via `mcp__obsidian__vault_read` on the handful of matched files — whichever is fewer round-trips for the count involved).
+
+Categorize:
+- **Prefixed notes**: `task_id` matches `{prefix}-\d+`. Group by the distinct prefix found (whatever
+  prefixes actually appear — don't assume a fixed set). Within each prefix, split further into:
+  - **Open**: `status` is `TODO`, `IN-PROGRESS`, or `REVIEW` (or missing — treat as open)
+  - **Closed**: `status` is `DONE`, `CANCELED`, or `CANCELLED`
+- **Other notes**: no `task_id`, or one that doesn't match `{prefix}-\d+`
+
+Sort each prefix group's notes numerically by task id (`{prefix}-9` before `{prefix}-10`); sort other notes alphabetically by title. Report one section per prefix found — "{prefix} notes — open", "{prefix} notes — closed" — plus "Other notes", each line as `{task-id or filename} — {title} [{status}]`. Omit a section header if it has zero entries. End with a total count.
+
+Do not modify any files in list mode.
+
+## Search mode
+
+Everything after `--search` (trimmed, quotes stripped) is the query.
+
+1. Run `mcp__obsidian__search_simple` with the query — this gives full-text relevance-ranked matches with context, the closest equivalent to a title/body search.
+2. If the query looks like it's targeting metadata specifically (a tag, a task ID, a status value) rather than free text, also run `mcp__obsidian__search_query` with an appropriate JsonLogic filter (e.g. `{"==": [{"var": "frontmatter.task_id"}, "proj-032"]}`).
+3. Report matches as `{title} — {file path relative to vault root}`, deduped across both. If nothing matches, say so plainly — the caller (agent or user) needs a clear "no existing note" signal to proceed with `--task`-less creation.
+
+Do not modify any files in search mode.
+
+## Resolving a missing task ID (task mode only)
+
+Triggered when `--task` is given but the title doesn't match `{prefix}-\d+`.
+
+The known project/prefix pairs live in a plain local file named `synapse-projects.conf` (one
+`project-name=prefix` line each) — read/appended with the Read/Edit tools, not the `obsidian`
+MCP server, since it's outside the vault. It is deliberately **not** part of the portable
+Synapse package and never copied between machines, so contexts that shouldn't mix (e.g.
+personal vs. work projects) never end up in the same file. It's self-managed — this command appends
+newly resolved pairs to it — but also plain text, so the user can add, fix, or remove a line by hand
+at any time.
+
+Resolve *which* file that is with the same tiered lookup every `synapse-*.conf` file uses for
+reading: first `$XDG_CONFIG_HOME/synapse/synapse-projects.conf` if `$XDG_CONFIG_HOME` is set, else
+`~/.config/synapse/synapse-projects.conf`; then `~/.claude/synapse-projects.conf`. Read whichever of
+those exists first. Append a newly resolved pair (step 5 below) to that same file.
+
+If neither exists yet, decide where to create it fresh: `$XDG_CONFIG_HOME/synapse/synapse-projects.conf`
+if `$XDG_CONFIG_HOME` is set; else `~/.config/synapse/synapse-projects.conf` if `~/.config` already
+exists as a directory on this machine (it's adopted XDG conventions for other tools even without ever
+setting the env var); else `~/.claude/synapse-projects.conf` as the final fallback — today's default,
+unchanged for anyone who has never touched an XDG config directory.
+
+1. Identify the current project from context: the repo's `CLAUDE.md` (title/"About" section) or
+   `git remote`.
+2. Check the resolved `synapse-projects.conf` for a line whose project name matches (loosely —
+   case/whitespace-insensitive). If found, use that prefix directly — no need to ask.
+3. If the file doesn't have it yet, fall back to deducing from the vault itself (useful the first
+   time this runs, or for a project whose notes predate this file): `search_simple` for the
+   project/repo name across existing notes, and/or `search_query` on
+   `{"var": "frontmatter.task_id"}` to see which prefixes exist, then check whether any of those
+   prefixed notes reference this project. If exactly one prefix confidently matches, use it.
+4. If nothing confidently matches (new project, or an ambiguous/multiple match), ask the user
+   directly: "What's the project prefix for this task?" — plain free-text, not a multiple-choice
+   list. Don't offer or hint at any other project's prefix as an option.
+5. Whenever step 3 or step 4 resolves a pair not already in the conf file (including a fresh
+   `project-name=prefix` line matching what was just deduced or asked), append it — so the next task
+   for this project resolves from step 2 without a search or a question.
+6. Once the prefix is known, find the next number: run
+   `mcp__obsidian__search_query` with `{"var": "frontmatter.task_id"}`,
+   filter the returned `result` values client-side for ones matching
+   `{prefix}-\d+`, take the highest number found, add 1. If none exist yet
+   for that prefix, start at 1.
+7. Format the new task ID **zero-padded to 3 digits** (`{prefix}-001`, `{prefix}-030`,
+   `{prefix}-037`, ...), matching the org-roam-era convention — widening
+   naturally past 3 digits if a prefix ever needs it.
+8. **Prepend the resolved task ID to the title itself** — the final title
+   becomes `{task-id} — {original title}` (em dash). Use this same final
+   title for both the `title` frontmatter field and the `# ` heading, and
+   use the resolved task ID for `task_id`. Don't let the frontmatter task
+   ID and the visible title disagree.
+
+`/synapse-design-note`/`/synapse-task-note` read the same conf file directly for the same reason —
+they don't duplicate this resolution logic, just this file.
+
+## Choosing a category (bare mode only)
+
+Task mode always uses `tasks/` — skip this step entirely in task mode.
+
+In bare mode, ask the user which category the note belongs to. Read
+`Index.md`'s folder list first — every top-level folder listed there
+except `designs`/`tasks`/`synapse` (structurally fixed, not a bare-mode
+destination — see `synapse-claude.md`'s Folders bullet) is a candidate
+category, offered with that folder's own `Index.md` description as the
+option's description. Don't hardcode a fixed option set: a fresh vault's
+`Index.md` lists `research`/`scratchpad`/`inbox` (see
+`${CLAUDE_PLUGIN_ROOT}/Index.md.template`), but a vault owner's own `Index.md` may have
+renamed or restructured these, and whatever it currently says is what gets
+offered.
+
+Resolve this to a `category` matching the folder name exactly as
+`Index.md` currently spells it, before moving on to the creation steps
+below. No project-slug question is needed here — Obsidian 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
+triage/priority one a vault owner might maintain by hand (e.g.
+`inbox/{high,medium,low}/`, per that folder's own `Index.md` description);
+sorting a note into one of those, if a category has one, is never an
+agent's call to make.
+
+## Resolving the project folder (task mode only)
+
+Task notes are grouped one level deeper by project, `tasks/{project}/{filename}.md` — see
+`Index.md`'s `tasks/` section. The prefix (`proj`, `sb`, ...) is not itself the folder name — it
+names the *task*, not the *project* — so resolve what project it belongs to, regardless of how
+the prefix became known (matched from the title, resolved in "Resolving a missing task ID" above,
+or supplied directly by a caller like `/synapse-task-note`):
+
+1. Reverse-lookup the prefix in the resolved `synapse-projects.conf` (same tiered lookup as
+   "Resolving a missing task ID" above) — find the line whose value after `=` equals the prefix;
+   its key is the project name.
+2. If no line matches, check `Index.md`'s `tasks/` section, which documents the prefix-to-project
+   mapping directly (e.g. `proj-NNN` → `widget`).
+3. If still unresolved (a genuinely new prefix with no mapping anywhere), ask the user for the
+   project name and append `{project-name}={prefix}` to the conf file — so the next task note
+   under this prefix resolves without asking.
+
+## Creating the note
+
+1. Sanitize the title into a filename: replace filesystem-illegal
+   characters (`/ : * ? " < > |`) with `-`, collapse repeated whitespace.
+   No timestamp prefix, no project-slug prefix — the filename is just the
+   (sanitized) title.
+2. Fetch machine local time: `date '+%Y-%m-%d %H:%M'` — never use inferred
+   time. Use this for the `created` frontmatter field.
+3. Build the file content:
+
+   **Bare mode:**
+   ```
+   ---
+   title: "{title}"
+   created: "{now}"
+   ---
+
+   ```
+
+   **Task mode:**
+   ```
+   ---
+   title: "{title}"
+   created: "{now}"
+   task_id: {task-id}
+   status: TODO
+   last_updated: "{now}"
+   ---
+
+   # {title}
+
+   ## Notes
+
+   ```
+4. Write it with `mcp__obsidian__vault_write`. Task mode: path
+   `tasks/{project}/{filename}.md` (project resolved in "Resolving the
+   project folder" above). Bare mode: path `{category}/{filename}.md`
+   (category resolved above).
+
+## Confirm
+
+Report the file path back to the user.
+
+- Bare mode: note that the note is intentionally near-empty.
+- Task mode: note the task ID extracted or resolved, and remind the user
+  to populate the `## Notes` section and checklist before starting work,
+  per the `synapse-task` skill.

package/commands/synapse-rebuild-diff.md

@@ -0,0 +1,314 @@
+---
+name: synapse-rebuild-diff
+description: Manually bring a repo's Synapse namespace back in line after major same-branch drift — a pull, a rebase, or a long absence. Triages each drifted node into reseat / patch-from-diff / re-orient rather than rebuilding everything. Refuses outright on a cross-branch mismatch; for a full rebuild from scratch, use /synapse-rebuild-full instead.
+---
+
+# Synapse Rebuild Diff: Reconcile a Namespace After Same-Branch Drift
+
+`/synapse-init` builds a namespace. The two staleness tiers and `synapse query drift` *detect*
+that it has moved. This command is the deliberate, human-invoked repair for the case where enough has
+moved that lazy per-read regeneration is the wrong instrument.
+
+**Same-branch only.** Every scenario below happens on the branch the namespace already describes —
+a pull, a rebase, time passing, your own hand-written commits. None of them involve the current
+checkout being on a *different* branch than the namespace's own recorded `branch:` field. If it is,
+this command refuses outright rather than attempting a diff — see the branch-identity check under
+Prerequisites. Comparing one branch's tree against another isn't drift, it's just two unrelated
+states, and none of the triage classes below (reseat / patch / re-orient) were built for that.
+
+## When to run it
+
+Manually, when you already expect major drift:
+
+- **A plain `pull`** that landed a meaningful number of commits — fast-forward, same branch throughout.
+- **A `pull --rebase`** — your local commits get new SHAs, so `synapse query drift` will likely
+  report the baseline as "not an ancestor of HEAD". That's expected here, not a sign of anything
+  wrong: you were on the same branch the whole time, only its history got rewritten.
+- **A large merge landing in your current branch** — another branch's tip merged in via `git merge`.
+  Still same-branch throughout: `HEAD` gains a merge commit, it doesn't move to a different branch.
+- **A long absence** — weeks or months of other people's commits landed while you were elsewhere, on
+  the same branch.
+- **You wrote a lot of code by hand.** The plainest case and probably the most common: days of ordinary
+  work in your own branch, in your own editor, with no model involved. Tier 1 only fires on
+  `Write`/`Edit`/`MultiEdit` *in this session*, so none of it was flagged as it happened. `stale` will
+  still catch content changes to files a node already claims — but it reports a rename as "gone", and a
+  **newly added file it cannot see at all**, because a path in no node's `sources` has nothing to
+  compare against. Real feature work adds files, so this is exactly where the graph goes quietly out of
+  date. Same applies to anything else that bypasses the session: an IDE refactor (which produces both
+  bad cases at once — renames *and* new paths), a `sed -i`, generated code that the build rewrote from a
+  schema, a dependency bump, or a moved submodule pointer.
+
+Do **not** run it after an ordinary pull. Tier 1 flags what this session edited, the `synapse-node`
+skill regenerates a node lazily when its body is actually needed, and `synapse query drift` is the
+cheap check that tells you whether anything more is warranted. This command exists for when the answer
+is clearly yes.
+
+**A large job is the expected outcome, not a warning sign.** On a monorepo with a hundred thousand
+files and heavy traffic, most of the graph moving at once is simply what the situation looks like, and
+forty nodes in *re-orient* is a normal shape for this command rather than a reason to hesitate. Nothing
+invokes this automatically — a human typed it, knowing their own repo and why they are here. So report
+the size, then **do the work**. Do not recommend against a rebuild on the grounds that it is expensive,
+do not offer a reduced version of it unasked, and do not describe replacing the graph as destructive:
+replacing it is the entire point. Volunteer a smaller option only where a *correctness* reason argues
+for one, and even then do the full job if the human says so.
+
+**One mechanical fact about branches, because it is not guessable.** A namespace is keyed by repo
+*and branch* (`synapse/{repo}@{branch}/`), so each branch has its own or has none. A branch switch
+therefore no longer invalidates anything: the graph you built on the mainline stays intact and keeps
+describing the mainline, and the branch you switched to simply has no namespace until someone runs
+`/synapse-init` there. That is an ordinary state, not a problem to fix.
+
+So the massive-drift case this command exists for is now the *unusual* one rather than the norm. It
+still happens — a branch can be checked out inside any worktree, and a long-lived branch gets rebased
+onto a moved trunk, which leaves the recorded baseline off the current line exactly as a branch switch
+used to. Read a "not an ancestor of HEAD" warning as "history moved under this graph", and reach for
+this command when it does. What no longer happens is arriving here merely because you changed branch.
+
+## Prerequisites
+
+- The namespace must exist. If `synapse/{repo}@{branch}/Index.md` is absent, this is a first build — use
+  `/synapse-init`.
+- **Branch-identity check — hard stop, run this before anything else, including drift/grounding.**
+  Compare the current checkout's branch against the namespace's own recorded `branch:` frontmatter
+  field:
+  ```sh
+  current_branch="$(git symbolic-ref --short HEAD)"
+  ns_branch="$(grep -m1 '^branch:' "synapse/{repo}@{branch}/Index.md" \
+      | sed -e 's/^branch: *//' -e 's/^"//' -e 's/"$//')"
+  ```
+  If they don't match, **refuse immediately** — do not run `synapse query drift`, do not read
+  anything else. Say plainly that this namespace describes a different branch than the current
+  checkout, and point at `/synapse-init` (if the current branch has no namespace of its own) or at
+  checking out the branch/worktree the namespace actually describes. This is a distinct, harder check
+  than the "baseline is not an ancestor of HEAD" ancestry signal below — that one is a *soft*,
+  informational finding (expected after a same-branch `pull --rebase`); this one is a hard refusal,
+  because it is not this checkout's namespace to diff at all. Never conflate the two: a non-ancestor
+  baseline on a branch-identity match still proceeds normally, per the "One mechanical fact about
+  branches" section above.
+- The work directory (`$SYNAPSE_WORK_DIR`, default `~/.claude/synapse-work/{repo}@{branch}/`) ideally
+  holds the `manifest.tsv` from the original build. Without it, new paths cannot be classified as
+  auto-claimable, and clustering decisions have to be re-derived — say so rather than proceeding as if
+  nothing were missing. `synapse/{repo}@{branch}/_manifest.tsv` is the fallback copy.
+- Read `synapse/{repo}@{branch}/_profile.txt` if it exists, before triaging anything. It records the
+  aggregations that carried signal for this repo and the searches that came back empty.
+
+## Procedure
+
+### 1. Size the job before doing any of it
+
+```sh
+~/.synapse query drift
+~/.synapse query grounding
+```
+
+Report what it says, in the human's terms, **before** touching anything: how far the baseline is from
+HEAD (and whether it is an ancestor at all), how many nodes are flagged in each class, and how many
+added paths need a decision. Silence means nothing to rebuild — say so and stop, including when the
+repo is behind its upstream: drift prints that only alongside a finding, because an accurate graph
+plus unpulled commits is nothing to repair yet.
+
+Two answers change the plan:
+
+- **"baseline … is not an ancestor of HEAD"** — a branch switch or a reset. The file-level diff is
+  still exactly right (it compares trees, not history), but expect deletions to dominate: files that
+  exist on the built line and simply are not here.
+- **"no commit recorded"** or **"baseline … not in local history"** — those nodes cannot be diffed at
+  all. They go straight to the *re-orient* class in step 3; there is no cheaper option for them.
+
+### 2. Mechanical phase — always, and cheap
+
+```sh
+~/.synapse build-lists --reenumerate
+```
+
+`--reenumerate` matters here: without it an existing `all.txt` is reused, so a branch switch would be
+invisible to enumeration. **Read the coverage report.** On a branch switch, per-node list sizes will
+move a lot and some may reach zero.
+
+- **A node whose list is now empty** means that subsystem does not exist on this branch. **Do not
+  write it** — `synapse write-node` refuses an empty path list, and that refusal is correct. Report
+  the node and leave it in place, untouched. **Never delete a node to tidy up a branch switch:**
+  `## Notes` is human-authored, lives outside the generated fence, and is unrecoverable.
+- **Unclaimed added paths** are a judgment call: widen an existing manifest line where a path belongs
+  to a cluster that already exists, and leave a genuinely new subsystem for a new manifest line and
+  its own node. Re-run `synapse build-lists` after editing the manifest, and check coverage again.
+
+Then rebuild the reverse index so the hook and the read path agree with the new enumeration:
+
+```sh
+~/.synapse build-index
+```
+
+### 3. Triage each flagged node — reseat, patch, or re-orient
+
+**Hard requirement for the *re-orient* class, not a recommendation: invoke the `synapse-orientation`
+skill before writing one sentence of new prose for that node.** Reading the node's own source
+directly and reasoning from what you already know about the codebase is not a substitute, no matter
+how accurate or hard-won that knowledge is — a node's premises being re-derived is the same problem
+a first build faces, and it gets the same required technique, every time, not just when nothing
+faster is available. The reason this can't be skipped even by a confident, correct reading of the
+source: the skill's own verification step is to *run* something real (`synapse tags`/`synapse query`
+against a real sample) and judge the actual output, not what the source implies the output should
+be — and only an executed check can surface a gap in the tooling itself, one the source reading alone
+has no way to reveal, however carefully it's done. A node whose own subject is the tagging or
+extraction pipeline is exactly the case most tempting to shortcut this way, and exactly the case
+where doing so costs the most.
+
+`synapse-node-format` is the other skill to load before triaging, for every class, not just
+*re-orient*: the node contract — frontmatter, the crux pointer, `## Links`, `grounded_in` — the same
+one `/synapse-init` and the `synapse-node` skill write against.
+
+**The principle: compute new prose from the diff, not by re-reading the node's sources.** A node
+covering 15,000 files where 12 changed already has prose encoding the other 14,988. Re-reading it all
+is the expensive mistake this command exists to avoid, and it also throws away hard-won findings the
+diff has nothing to say about.
+
+**Take the nodes that lost files first, and keep the full list of deleted paths in front of you for
+every node after that.** A deletion in one node is routinely the other half of an addition in
+another — a type moved from the binary into a library, a module promoted out of a `util`. Triaged in
+drift's arbitrary order, the node that *gained* the file is patched first, with no way to know the
+file came from anywhere, and the patch fills the gap with a guess. One cheap list, read once:
+
+```sh
+git diff --diff-filter=D --name-only -M <commit>..HEAD
+```
+
+**Size each node by changed lines, not by changed files.** Drift reports file counts because that is
+what it can compute without a diff, but a file count saturates immediately in a repo of small
+modules: a node of 9 files with 5 touched reads as 56% when the actual change is 199 lines out of
+2,077, and every one of them a formatting or import edit. Get the real ratio before choosing:
+
+```sh
+git diff --numstat <commit>..HEAD -- $(tr '\n' ' ' < "$W/lists/NN.txt") \
+  | awk '{a += $1; d += $2} END {print a + d}'
+```
+
+against the node's own line count, and use `synapse query sources "{Node}" --count` for the file
+count drift's numbers are relative to. Then pick one of three strategies and **say which one you
+picked and why**:
+
+**Restore the crux directive before writing any node back.** `synapse query body` returns the
+*expanded* crux — the fenced code the writer sliced — not the directive that produced it. Writing that
+straight back stores a quote of a file as it looked at the old baseline, presented as if it were
+current. So rebuild the directive from the pointer the writer recorded:
+
+```sh
+~/.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
+current file. One judgment goes with it: re-slicing the same range is only safe if that file did not
+change. If it did, the line numbers may now point at something else entirely — treat the crux as
+needing a fresh pointer, exactly as the prose needs a fresh sentence. A node with no `crux_path` had
+`none`, and stays that way.
+
+**The same applies to groundings, and forgetting them loses more.** `grounded_in` is frontmatter and
+its directives are stripped from the body, so a recovered body contains none — write it back as-is and
+the node's provenance is gone with no error. Recover the pointers per node:
+
+```sh
+~/.synapse query grounding "{Node}" --list   # path<TAB>lines
+```
+
+and re-emit a `<!-- grounded_in: <path> <lines> -->` for each. Run `synapse query grounding` before
+triaging: it is cheaper than the diff and sharper than a churn ratio. A **`moved`** line hands you the
+corrected range outright, no reading. A **`changed`** line points at evidence that no longer says what
+the summary claims — which is a better reason to re-read a node than any percentage, because it names
+the sentence at risk rather than the volume of change around it.
+
+**Reseat** — renames only, no content change. No reading at all. Recover the existing prose with
+`synapse query body "{Node}"`, drop its trailing `## Sources` block (the writer regenerates that),
+re-enumerate so the list holds the new paths, and write it back. Repeating this is safe: the writer
+trims the body's leading and trailing blank lines, so a reseat is idempotent rather than accreting
+padding each time. The concept did not change; only paths moved. This also
+works on a machine that never built the namespace, because the body came from the node itself rather
+than from a work-dir file.
+
+**Patch from the diff** — a small fraction of the node's *lines* changed (rule of thumb: under ~15%),
+and the file its `crux` quotes still exists. Read three things and nothing else:
+
+1. the current prose — `synapse query body "{Node}"`;
+2. `git diff --name-status -M <commit>..HEAD` restricted to that node's paths, for *which* files moved;
+3. hunks for a **bounded** selection of those files — always including any file the `crux` quotes.
+
+Then amend only the sentences the diff contradicts, and keep everything else verbatim.
+
+**A patch may say what the node now contains. It must not say where something came from** unless the
+rename is in the diff it read. Provenance is the one claim a node-restricted diff structurally cannot
+support: the other end of the move is in a different node's paths, so the diff shows an unexplained
+new file, and the plausible local origin is an invention. `git`'s rename detection is not a
+safety net here — a file that moved between modules and was rewritten on the way lands below the
+similarity threshold and shows up as a delete in one node and an add in another even under
+`-M --find-copies-harder`. Which is why deletions get read first, below.
+
+**Re-orient** — a large fraction changed, the baseline is unusable, or there is a structural signal:
+the `crux` file is gone or renamed, whole modules entered or left the node, or a package root changed
+name. Here the prose's premises are suspect, so patching would preserve a claim that is no longer
+true. Re-run this node's aggregations from `_profile.txt` (path-level, so cheap even on a hub node),
+read the few load-bearing files the aggregations point at, and re-author as `/synapse-init` would.
+
+**The diff must be projected as carefully as `sources` is.** `git diff` with hunks across a hub node's
+paths over hundreds of commits runs to megabytes — the same constraint that makes `sources` unreadable
+applies to the diff. So: `--name-status` for names, `--stat` to size it, and hunks only for a bounded
+selection. Never pipe an unbounded `git diff <commit>..HEAD` into a context window.
+
+### 4. Write each rebuilt node
+
+```sh
+~/.synapse write-node --title "{Node}" --summary "{one line}" \
+   --paths "$W/lists/NN.txt" --body "$W/body.md"
+```
+
+It re-records `commit`, so this checkout becomes the node's new baseline — which is what makes the next
+`drift` meaningful. **Re-check the one-line `summary`**: after a branch switch it can be wrong in kind,
+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
+```
+
+`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.
+
+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.
+
+### 6. Report what happened
+
+Per node: the strategy chosen and why. Plus what was deliberately left alone — nodes drift did not
+flag, and nodes whose sources vanished on this branch. A rebuild that silently re-authored forty nodes
+is indistinguishable, from the outside, from one that did nothing.
+
+## Guardrails
+
+- **Never `pull`, `fetch --prune`, `rebase`, `reset` or `checkout`.** The human chose this checkout;
+  this command describes and records it. Report how far behind the upstream ref is and stop there.
+- **Never re-read a node's full sources to patch a small diff.** That is the specific waste this
+  command is built to avoid.
+- **Know what patching cannot fix.** It keeps every sentence the diff does not contradict, so a claim
+  that was wrong when the node was *built* survives every future patch untouched — the diff has
+  nothing to say about a statement that was never true. Patching is therefore only as good as the
+  baseline prose, and a node's most likely error is not drift but an explanation invented at build
+  time. The `crux` is no longer the exposure it was — `synapse write-node` slices it out of the
+  file from a `<!-- crux: path start-end -->` directive, so it is verbatim by construction rather than
+  by instruction. What remains unguarded is the prose. A sentence asserting a *mechanism* ("X is
+  behind a mutex, which is why Y")
+  deserves more suspicion than one asserting structure — if the diff touches its file at all, verify
+  it rather than carrying it over.
+- **Never write a node with an empty path list**, and never delete a node whose sources vanished — its
+  `## Notes` is human-authored and outside the generated fence.
+- **Never hand-write frontmatter or the `## Sources` mirror.** `synapse write-node` owns them; doing
+  it by hand cannot scale to a hub node and silently drops `summary` and `commit`.
+- **Never rebuild a node drift did not flag.** Regeneration has real cost and it is not free of risk —
+  each rewrite is a chance to lose a good sentence.
+- **Say when the graph now describes a different branch than it did before**, in the final report. That
+  fact outlives the session, and the next reader has no other way to know.