@imunitic/synapse 0.13.11 → 0.13.13

package/commands/synapse-design-note.md

@@ -1,5 +1,5 @@
 ---
-description: Start or continue a free-form, cross-project design discussion, written to Synapse Vault rather than tied to one repo — thinking through a problem/approach/tradeoffs out loud before anything is built. Use whenever the user wants to open, resume, or reason through a design ("let's create/write a design note", "let's think through X", "let's design this", "let's talk this through"). Not for a note that's already ready to become tracked work (that's synapse-task-note), or a plain vault note with no design framing (that's synapse-note, whose project-resolution logic this command reuses).
+description: Start or continue a design discussion as a Synapse Vault design note.
 ---
 
 # Synapse Design Note: Cross-Project Personal Design Discussion

package/commands/synapse-init.md

@@ -1,5 +1,5 @@
 ---
-description: Build a repo's Synapse Graph namespace from scratch — enumerate tracked files, orient into the repo's own symbol vocabulary, cluster into manifest.tsv, gate cluster quality, compute the link graph, author each node's prose, and write the two derived projections (_index.bin, Index.md). This is the only way a project gets a Synapse namespace in the first place — nothing else in the system creates one unprompted. Also handles the lighter re-run case for an already-initialized project (sweeping unassigned files into existing nodes, never re-clustering). Use whenever the user wants to set up Synapse for a repo for the first time ("init synapse here", "build the code graph", "set up the namespace") or asks to sweep newly-unassigned files into an existing graph. Not for repairing drift in an existing namespace (that's synapse-rebuild-diff) or a full wipe-and-rebuild (that's synapse-rebuild-full).
+description: Build this repo's Synapse code-graph namespace from scratch, or sweep unassigned files into an existing one.
 ---
 
 # Synapse Init: Build or Refresh a Repo's Code-Graph Namespace

package/commands/synapse-note.md

@@ -1,5 +1,5 @@
 ---
-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.
+description: Create a plain or task note in Synapse Vault, list tracked tasks, or search existing notes.
 ---
 
 Create a note in Synapse Vault with the title and options, list existing notes, or search existing notes: $ARGUMENTS

package/commands/synapse-rebuild-diff.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: Bring this repo's Synapse namespace back in line after same-branch drift: a pull, a rebase, or a long absence.
 ---
 
 # Synapse Rebuild Diff: Reconcile a Namespace After Same-Branch Drift
@@ -38,10 +38,10 @@ Manually, when you already expect major drift:
   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.
+Run it whenever the graph has fallen behind: the SessionStart line reports how many commits HEAD is
+past it, and `synapse query drift` shows what changed. A small drift after an ordinary pull is an
+ordinary run, with a few nodes in the *patch-from-diff* class. Between runs, Tier 1 flags what a
+session edits and the `synapse-node` skill regenerates a stale node lazily when its body is needed.
 
 **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

package/commands/synapse-rebuild-full.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: Wipe and rebuild this repo's Synapse namespace from scratch, keeping hand-written Notes.
 ---
 
 # Synapse Rebuild Full: Wipe and Rebuild a Namespace From Scratch

package/commands/synapse-status.md

@@ -1,5 +1,5 @@
 ---
-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, Ready design notes with open questions still outstanding, 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.
+description: Read-only report of what in Synapse Vault currently needs a human decision.
 ---
 
 # Synapse Status: Vault-Wide Attention Report

package/commands/synapse-task-note.md

@@ -1,5 +1,5 @@
 ---
-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).
+description: Compile a Ready design note into one tracked task note in Synapse Vault.
 ---
 
 # Synapse Task Note: Compile a Design into a Tracked Checklist

package/commands/synapse-vault-tidy.md

@@ -1,5 +1,5 @@
 ---
-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.
+description: One on-demand tidy pass over Synapse Vault: recategorization and note-health findings as a single proposal.
 ---
 
 # Synapse Vault Tidy: Recategorization Proposals and Note-Health Fixes

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

@@ -1,6 +1,6 @@
 ---
 name: synapse-design-note
-description: Start or continue a free-form, cross-project design discussion, written to Synapse Vault rather than tied to one repo — thinking through a problem/approach/tradeoffs out loud before anything is built. Use whenever the user wants to open, resume, or reason through a design ("let's create/write a design note", "let's think through X", "let's design this", "let's talk this through"). Not for a note that's already ready to become tracked work (that's the synapse-task-note skill), or a plain vault note with no design framing (that's the synapse-note skill, whose project-resolution logic this skill reuses).
+description: Start or continue a design discussion as a Synapse Vault design note.
 ---
 
 # Synapse Design Note: Cross-Project Personal Design Discussion

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

@@ -1,6 +1,6 @@
 ---
 name: synapse-init
-description: Build a repo's Synapse Graph namespace from scratch — enumerate tracked files, orient into the repo's own symbol vocabulary, cluster into manifest.tsv, gate cluster quality, compute the link graph, author each node's prose, and write the two derived projections (_index.bin, Index.md). This is the only way a project gets a Synapse namespace in the first place — nothing else in the system creates one unprompted. Also handles the lighter re-run case for an already-initialized project (sweeping unassigned files into existing nodes, never re-clustering). Use whenever the user wants to set up Synapse for a repo for the first time ("init synapse here", "build the code graph", "set up the namespace") or asks to sweep newly-unassigned files into an existing graph. Not for repairing drift in an existing namespace (that's the synapse-rebuild-diff skill) or a full wipe-and-rebuild (that's the synapse-rebuild-full skill).
+description: Build this repo's Synapse code-graph namespace from scratch, or sweep unassigned files into an existing one.
 ---
 
 # Synapse Init: Build or Refresh a Repo's Code-Graph Namespace

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

@@ -1,6 +1,6 @@
 ---
 name: synapse-note
-description: Create a plain note in Synapse Vault (bare mode — title + frontmatter, category resolved from the vault's index note), a tracked task note (task mode, scaffolds the checklist skeleton the synapse-task skill expects), list every tracked task, or search existing notes 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 the synapse-design-note skill) or compiling a Ready one into a task (that's the synapse-task-note skill) — both of those delegate to this skill themselves.
+description: Create a plain or task note in Synapse Vault, list tracked tasks, or search existing notes.
 ---
 
 # Synapse Note: Plain Vault Notes, Task Notes, Listing, and Search

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

@@ -1,6 +1,6 @@
 ---
 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 the synapse-rebuild-full skill instead.
+description: Bring this repo's Synapse namespace back in line after same-branch drift: a pull, a rebase, or a long absence.
 ---
 
 # Synapse Rebuild Diff: Reconcile a Namespace After Same-Branch Drift
@@ -38,10 +38,10 @@ Manually, when you already expect major drift:
   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 skill exists for when the answer
-is clearly yes.
+Run it whenever the graph has fallen behind: the SessionStart line reports how many commits HEAD is
+past it, and `synapse query drift` shows what changed. A small drift after an ordinary pull is an
+ordinary run, with a few nodes in the *patch-from-diff* class. Between runs, Tier 1 flags what a
+session edits and the `synapse-node` skill regenerates a stale node lazily when its body is needed.
 
 **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

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

@@ -1,6 +1,6 @@
 ---
 name: synapse-rebuild-full
-description: Wipe a repo's Synapse namespace and rebuild it from scratch via the synapse-init skill, 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 the synapse-rebuild-diff skill instead — it's cheaper and never deletes a node outright.
+description: Wipe and rebuild this repo's Synapse namespace from scratch, keeping hand-written Notes.
 ---
 
 # Synapse Rebuild Full: Wipe and Rebuild a Namespace From Scratch

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

@@ -1,6 +1,6 @@
 ---
 name: synapse-status
-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, Ready design notes with open questions still outstanding, 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 the synapse-note/synapse-design-note/synapse-task-note skills' own --list modes) -- this is the one cross-cutting view over all of them at once.
+description: Read-only report of what in Synapse Vault currently needs a human decision.
 ---
 
 # Synapse Status: Vault-Wide Attention Report

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

@@ -1,6 +1,6 @@
 ---
 name: synapse-task-note
-description: Compile a Ready design note into a single tracked, checklist-based task note in Synapse Vault — delegates the actual note creation to the synapse-note skill's task mode 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 the synapse-design-note skill).
+description: Compile a Ready design note into one tracked task note in Synapse Vault.
 ---
 
 # Synapse Task Note: Compile a Design into a Tracked Checklist

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

@@ -1,6 +1,6 @@
 ---
 name: synapse-vault-tidy
-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 session-start wiring, no autonomous scheduling; run it only when asked, or on a recurring cadence the user sets up themselves. Scoped to everything except designs/, tasks/, and synapse/ (the code graph's own generated namespace), which stay entirely the synapse-status skill's (the first two) or the synapse-init skill's (the third) territory.
+description: One on-demand tidy pass over Synapse Vault: recategorization and note-health findings as a single proposal.
 ---
 
 # Synapse Vault Tidy: Recategorization Proposals and Note-Health Fixes

package/package.json

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

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

@@ -1,6 +1,6 @@
 ---
 name: synapse-node-authoring
-description: How to write every node's prose in a build — sequentially by default, or fanned out to a configurable pool of concurrent subagents. Covers pool-size resolution from synapse.conf, the synapse brief data file each author reads, dispatch/verify/retry mechanics, and the standing contract every author works under. Use at /synapse-init's node-authoring step, or anywhere else a batch of nodes needs fresh prose (e.g. /synapse-rebuild-diff's re-orient class).
+description: Writing node prose for a batch of nodes, sequentially or with a subagent pool. Loaded by /synapse-init and /synapse-rebuild-diff.
 ---
 
 # Writing every node's prose: sequential by default, pooled on request

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

@@ -1,6 +1,6 @@
 ---
 name: synapse-node-format
-description: The contract for a Synapse code-graph node — frontmatter fields, the crux pointer, `## Links`, `grounded_in`, `## Sources`, and what `synapse write-node` adds or refuses. Load before authoring or regenerating any node, whether from /synapse-init's first build, /synapse-rebuild-diff's triage, or the synapse-node skill's lazy regeneration. Not for reading the graph (that is synapse-query) or for task notes in the vault (that is synapse-task).
+description: The node contract: frontmatter, crux, `## Links`, `grounded_in`, `## Sources`, and what `synapse write-node` refuses. Load before authoring any node.
 ---
 
 # What a node is, and how to author one

package/skills/synapse-orientation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: synapse-orientation
-description: How to work out where meaning lives in a codebase you have not seen before — first mechanically, from the repo's own symbol vocabulary, and where no grammar exists, by four questions in order with the cheap commands that answer each. Includes tree-sitter grammar discovery. Use when clustering a repo into Synapse graph nodes for the first time, when re-deriving a node's premises in /synapse-rebuild-diff's re-orient class, or any time you need to orient in an unfamiliar tree before making claims about it.
+description: Orienting in an unfamiliar codebase before clustering it into graph nodes, including tree-sitter grammar discovery.
 ---
 
 # Orienting in an unfamiliar repo

package/skills/synapse-query/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: synapse-query
-description: This repo has a Synapse code graph. For ANY task here — understanding how something works, finding where code lives, tracing what depends on a file, or scoping an edit — consult synapse/{project}/Index.md and synapse query before grepping or reading source files. Grep only after Synapse has named the exact file(s) to read. Also applies when this repo has no graph of its own but the task concerns another checkout that does — synapse query --namespace <repo>@<branch> reaches that graph without switching directories.
+description: This repo has a Synapse code graph. For any task here (how something works, where code lives, what depends on a file, scoping an edit), query the graph before grepping or reading source, and grep only inside files it named. Another checkout's graph: --namespace <repo>@<branch>.
 ---
 
 # Synapse Query: Day-to-Day Use of the Code Graph
@@ -52,6 +52,7 @@ required:
 | A file's API surface | read the file directly | Claude already has direct, cheap filesystem access — no separate view needed. |
 | Who depends on a subsystem, or what it depends on | `synapse query links "{Node}" --inbound` / `--closure` | Real transitive-closure traversal over the typed relations, at node granularity. |
 | **Who calls this method/class, repo-wide** | `synapse callers <name>` | Every call site as `path:line ⇥ calling expression`, off the flat index `synapse build-refs` projects from the tags cache. Well under a second even against a multi-gigabyte index. Needs **no node and no graph** — it works in a repo `/synapse-init` has never touched, as long as the cache is filled. Still name-based rather than type-resolved, so hits are candidates with evidence: the calling expression is on the line, which usually settles the receiver without opening the file. |
+| **Where a symbol is defined, or every definition and reference of a name** | `synapse query symbol <name> "{Node}"`, or repo-wide `synapse callers <name> --all` | `symbol` gives `path:line` plus the defining expression inside one node's files. `callers --all` needs no node: every def and ref repo-wide from the Code Cache, the first move when you don't know the owning node yet. |
 | One frontmatter scalar (`stale`, `built_at`, `commit`, ...) | `synapse query field "{Node}" <key>` | Cheap, targeted extraction — never reads the rest of the node. |
 | A node's prose, without its (possibly huge) `sources` list | `synapse query body "{Node}"` | Disk read, never the API; skips frontmatter and `## Notes`. See the cost note above. |
 | Every file a node covers | `synapse query sources "{Node}" [--count\|--modules\|--filter <p>]` | Filtered/counted/grouped, never the raw megabyte-scale list. |
@@ -73,6 +74,12 @@ required:
 
 ## When a node isn't enough
 
+A query's answer scopes the work: open the files it names at the ranges it gives, and do not grep
+the repo to re-derive what it already answered. Line ranges come from the last graph build and can
+drift after edits. When the lines you open don't match what the query described, re-locate the
+symbol within that same file (the file is the truth, the range is a pointer), and only widen the
+search if the file no longer contains it at all, which means the graph is stale for that node.
+
 Synapse has no exact per-symbol call graph — a node's answer is a concept-level summary, not a
 parse. This matters more here than it would for a tool that does have one: short, reused names
 (common in languages that don't require import qualification for same-package references) can't

package/skills/synapse-vault/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: synapse-vault
-description: Synapse Vault is durable memory, and only its Index.md is ever auto-injected — every other note is pull-only. Load this BEFORE answering from your own reasoning about tooling behaviour, a past decision, a convention, a gotcha, or anything a previous session might have written down; and before creating or editing any note in the vault. Covers what to search with, and the vault-patch operations that silently destroy a note.
+description: Synapse Vault is durable memory; only its Index.md is auto-injected. Load before answering from your own reasoning about tooling, a past decision, a convention or a gotcha a previous session may have recorded, and before creating or editing any vault note.
 ---
 
 # Synapse Vault: search it first, and do not destroy it