@imunitic/synapse 0.0.1-test.0

package/skills/synapse-task/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: synapse-task
+description: Update Obsidian task notes' status frontmatter and Notes sections, enforcing status transitions so active work is IN-PROGRESS and completed checklists move only to REVIEW (not DONE).
+---
+
+# Synapse Task Status Skill
+
+Tracks status for task notes created via `/synapse-note --task` and compiled via `/synapse-task-note`,
+using a `status:` frontmatter field and GFM `- [ ]`/`- [x]` checklists (the vault's native format,
+no conversion needed).
+
+## When to invoke (proactive — do not wait to be asked)
+
+Applies to any task note, in any project — a task note is identified by having
+`task_id` and `status` frontmatter fields, not by which prefix `task_id` uses
+(`proj-NNN`, `sb-NNN`, or any other project's prefix from
+`~/.claude/synapse-projects.conf`). Never gate this skill on a specific
+prefix.
+
+Invoke this skill **automatically** in two situations:
+
+1. **Starting work on a task** — as soon as the user confirms work is
+   beginning, before writing any code. Set `status: IN-PROGRESS` and update
+   `last_updated`. No notes needed at this point.
+
+2. **Finishing work on a task** — after all phases are committed and
+   the task note's checklist has been updated. Set `status: REVIEW` (if all
+   items checked) or `status: IN-PROGRESS` (if any remain), update
+   `last_updated`, and append an implementation summary to the `## Notes`
+   section.
+
+Never wait to be asked — apply this skill proactively at both transitions.
+
+## What this skill does
+
+- Updates the `status:` frontmatter field (`TODO` → `IN-PROGRESS` or
+  `REVIEW`).
+- Updates `last_updated` in frontmatter.
+- At task completion: appends concise implementation bullets to the
+  existing `## Notes` section (or creates one if none exists).
+
+## Status transitions
+
+| Checklist state | `status:` value |
+|-----------------|-----------------|
+| Any `[ ]` unchecked | `IN-PROGRESS` |
+| All `[x]` checked | `REVIEW` |
+
+**Never set `DONE` through this workflow.** Do not manually write `DONE`
+into `status:` either — always go through this skill, which caps at
+`REVIEW`.
+
+## Procedure
+
+1. Find the task note: `mcp__obsidian__search_query` with
+   `{"==": [{"var": "frontmatter.task_id"}, "<task-id>"]}`, where `<task-id>`
+   is the specific task's ID (whatever prefix it uses — `proj-035`, `sb-008`,
+   etc.), then `mcp__obsidian__vault_read` the matched file.
+2. Inspect its checklist items (`- [ ]` / `- [x]`).
+3. Determine the new `status:` value: `IN-PROGRESS` if any unchecked,
+   `REVIEW` if all checked.
+4. Fetch machine local time: `date '+%Y-%m-%d %H:%M'` — never use inferred
+   time.
+5. Update `status:` and `last_updated:` with two `synapse frontmatter set`
+   calls, one per field: `synapse frontmatter set <path> status <value>`
+   then `synapse frontmatter set <path> last_updated "{now}"`. Each call
+   changes exactly that one line and nothing else, entirely inside the
+   compiled binary — the note's body never enters your context at all.
+   When the command isn't available, fall back to **read-modify-write**:
+   `vault_read` the file, replace the one line in the returned content,
+   `vault_write` the whole file back — byte-preserving, because you write
+   back what you read.
+
+   **Never use `vault_patch` with `targetType: frontmatter`.** It is *not*
+   field-local, despite reading that way: two patches
+   (one for `status`, one for `last_updated`) re-serialise the entire
+   frontmatter block — every quoted value loses its quotes (`created:
+   "2024-01-01 15:57"` → `created: 2024-01-01 15:57`) and a long `title:`
+   is folded across two lines. Both are valid YAML, so nothing breaks
+   loudly, but any tool string-matching `^title: "` stops matching, and
+   every status transition silently reformats the note. Since transitions
+   are this skill's main job, that reformatting would land on every task
+   note in the vault. `frontmatter set` exists specifically so this never
+   has to be reached for.
+6. **For completion only:** append implementation bullets to the existing
+   `## Notes` section with `mcp__obsidian__vault_patch`
+   (`targetType: heading`, `target: "{H1 title}::Notes"`, `operation:
+   append`) — append is safe here too. **The target must be the full
+   nested path** (`H1::Notes`), not just `"Notes"`: since `## Notes` is
+   nested under the top-level `# {title}` heading, the
+   plugin's heading lookup fails with "target not found in document" on
+   the bare leaf name and requires the `::`-joined path from the tool's
+   own docs. If no notes section exists, same call with
+   `createTargetIfMissing: true`.
+
+The vault_patch hazards below are the task-note-specific instance of a general rule; the
+`synapse-vault` skill carries the full list (H1 replace, nested heading paths, frontmatter
+re-serialisation) for every note, not just task notes.
+
+**Do not use `vault_patch` with `operation: replace` on the top-level
+heading to edit checklist items.** "Content beneath
+heading" for a top-level (`#`) heading extends through *all* nested
+subheadings (including `## Notes`), not just the leading paragraph/checklist
+directly under it — a replace there silently deletes everything past the
+checklist, including the Notes section. To check off checklist items,
+instead `vault_read` the full file, edit the `- [ ]` → `- [x]` lines in the
+returned content, and `vault_write` the whole file back.
+
+## Notes format
+
+Append flat bullets to the existing notes section. Keep them factual and short:
+
+- What was implemented / changed
+- Key design decisions or deviations from the spec
+- Files added or modified
+- Validation result (`just check` / test counts)
+
+Avoid creating a new heading if a notes section already exists at any
+level. Append to the last existing notes section.
+
+## Task file structure
+
+Each task note, in any project, has **exactly one top-level heading** (the
+task itself, `# {title}`). Implementation steps go as `- [ ]` checklist items
+**under that heading**, not as additional headings. Do not create `##
+Step` sub-headings for implementation steps.
+
+Correct structure:
+```md
+# Implement something
+
+Description of the task.
+- [ ] Step one
+- [ ] Step two
+- [ ] Step three
+```
+
+Wrong structure (do not do this):
+```md
+# Implement something
+## Step one
+## Step two
+```
+
+### Inline code examples in checklist items
+
+Only applicable to code tasks. Non-code tasks (research, documentation,
+configuration, simple one-liners) need no code blocks at all.
+
+For code tasks, substantive checklist items (type definitions, API
+surfaces, interface signatures) must include a fenced code block showing
+the exact interface, directly under the checklist item text, indented to
+match:
+
+```md
+- [ ] Implement Foo
+
+  One-line description of what this covers and any non-obvious constraints.
+
+  ```ocaml
+  // path/to/file
+  interface or type definition goes here
+  ```
+```
+
+Draw the signatures directly from the design document. Do not paraphrase
+or abbreviate — the checklist item is the implementor's authoritative
+reference.
+
+### Notes section (pre-implementation)
+
+Every new task note must have a `## Notes` section, **written before
+implementation begins** (not only appended after completion). For tasks
+backed by a design document, populate it with:
+
+- Design reference: file path and task ID
+- Key constraints the implementor must not miss
+- Deliberate exclusions (what is out of scope and why)
+
+For research or simple tasks with no design doc, a brief one-liner stating
+the goal or context is sufficient. Omit the section only if there is
+genuinely nothing non-obvious to capture.
+
+```md
+## Notes
+
+Design reference: docs/design/foo_design.md (task-NNN).
+
+- Key constraint one
+- Key constraint two
+- Out of scope: X (reason), Y (reason)
+```
+
+Post-implementation summaries are appended under `## Notes` as dated
+sub-headings (`### YYYY-MM-DD — ...`), as shown in the completion
+procedure above.
+
+## Creating a GitHub issue from a task
+
+When the user asks to create a GitHub issue from a task note:
+
+1. **Title** — `<TASK-ID> — <description>`, where `<TASK-ID>` is the
+   `task_id` frontmatter field (whatever project's prefix it uses — e.g.
+   `proj-030`, `sb-008`) and `<description>` is the heading with any leading
+   task-id prefix stripped (`<TASK-ID>`, `<TASK-ID> —`, or `<TASK-ID> - `).
+   Example: heading `# proj-035 - Widget catalog rework` → title
+   `proj-035 — Widget catalog rework`.
+2. **Body** — the full content of the top-level heading section: the
+   description paragraph and all checklist items (with any inline code
+   blocks) — already GFM Markdown, so this goes straight into
+   `gh issue create --body-file` unchanged.
+3. **First comment** — the full content of the `## Notes` section,
+   including any dated sub-headings and their bullets, straight into
+   `gh issue comment --body-file` unchanged.
+4. **State** — `gh issue create` has no `--state` flag; every issue is
+   created open, then closed as a separate step if needed. Leave it open
+   for `TODO`, `IN-PROGRESS`, and `REVIEW`. For `DONE`, close it after
+   creating: `gh issue close <n>` (defaults to `state_reason: completed`).
+   For `CANCELED`/`CANCELLED`, close it with `gh issue close <n> --reason
+   "not planned"`.
+
+```sh
+gh issue create --title "..." --repo <owner>/<repo> --body-file body.md
+gh issue comment <issue-number> --repo <owner>/<repo> --body-file notes.md
+```
+
+To edit an already-created issue/comment instead of creating a new one:
+`gh issue edit <n> --body-file <file>` for the issue body; comments have no
+`gh` subcommand for editing, use `gh api
+repos/<owner>/<repo>/issues/comments/<comment-id> -X PATCH -f
+body="$(cat <file>)"` (get the comment ID from the URL `gh issue comment`
+printed when it was created, or `gh api
+repos/<owner>/<repo>/issues/<n>/comments`).
+
+## Guardrails
+
+- **Never write `DONE`** — not in `status:`, not manually, not through any
+  other path. The cap is always `REVIEW`.
+- **Never `git commit` or `git push` in the project repo while a task note
+  tracked by this skill is anything but `DONE`.** Work through the whole
+  checklist stays uncommitted in the working tree — do not commit after each
+  checked-off item; that fragments the history and loses the thread of what
+  the task actually did. Commit (and push) only once the task note's
+  `status` is `DONE` and the human has explicitly asked for that specific
+  commit/push — a prior "commit and push" is not a standing license for the
+  next one, and setting `DONE` is itself a human action this skill never
+  takes (see "Never write `DONE`" above).
+- **Never create a task note via a bare `vault_write`.** Always
+  `/synapse-note --task`, or `/synapse-task-note` when compiling one from a
+  `Ready` design note. A freeform write skips both the skeleton (checklist
+  items plus a single `## Notes` section) and every guardrail in this file —
+  there is no partial-credit version of following this skill.
+- **Never restructure an existing task note's shape via `vault_write`/
+  `vault_patch` outside this skill's own procedure.** Ad hoc edits that add
+  new headings, drop the checklist, or otherwise diverge from the skeleton
+  are what this guardrail exists to prevent — not just wrong `status:`
+  values.
+- Preserve `task_id` untouched — it is set manually (or resolved once by
+  `/synapse-note --task`) and must not be auto-generated or overwritten.
+- If checklist content is ambiguous or missing, default to `IN-PROGRESS`.
+- Keep notes wording deterministic; avoid speculative claims.

package/skills/synapse-vault/SKILL.md

@@ -0,0 +1,107 @@
+---
+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.
+---
+
+# Synapse Vault: search it first, and do not destroy it
+
+Knowledge, not a procedure — like `synapse-node-format`. Nothing here tells you what to do
+next; it tells you what is true about the store you are about to read from or write to.
+
+## Only `Index.md` is pushed. Everything else is pull.
+
+The SessionStart hook injects the vault's `Index.md` — folder layout and the namespace
+catalogue. That is all. The other notes exist and are never injected, so the only thing standing
+between you and a written-down answer is deciding to look.
+
+**The failure this exists to prevent is not "not knowing". It is re-deriving, in the reply, a
+thing the vault already says** — sometimes in three places at once. A wrong answer gets corrected;
+a re-derived one is invisible, costs a turn, and quietly asserts that the memory system does not
+work.
+
+Search before you answer when the question is about:
+
+- how a tool behaves, especially an option you have not used before
+- whether a decision was already made, and why it went that way
+- a convention, a naming rule, a threshold, a measured number
+- anything that starts "I think it works like…"
+
+```
+mcp__obsidian__search_simple    full-text, relevance-ranked, with match context
+mcp__obsidian__search_query     JsonLogic over frontmatter, tags, links, backlinks, path globs
+mcp__obsidian__vault_list       when you already know roughly where it is
+mcp__obsidian__vault_read       with targetType/target to pull one section, not the whole note
+```
+
+A search that returns nothing is a real result and worth one line in the note you then write —
+a negative result cannot be rediscovered by searching for it.
+
+## What silently destroys a note
+
+Every item below returns success.
+
+- **`vault_patch` + `operation: replace` targeting the H1 replaces the entire document.**
+  `targetScope` defaults to `content` = "everything below this heading until one of the same or
+  higher level", and below the H1 there is no higher level, so that is the whole note. To insert
+  between the title and the first H2 — a status or metadata blockquote, the usual reason to touch
+  that region — use **`operation: prepend` against the H1**. Never `replace`.
+- **Heading targets are nested paths.** An H2 is `H1 title::H2 title`; a bare `H2 title` fails
+  with "target not found in document", which reads like the heading is missing rather than like
+  the path is wrong. `mcp__obsidian__vault_get_document_map` returns the exact `::` paths.
+- **`operation: append` against the bare H1 can land one heading level too deep.** When the
+  document's last section has a subheading of its own (e.g. `## Approach` ending in
+  `### Alternatives considered`), an appended `## Notes` can come back as `### Notes`, nested
+  under that last subsection instead of sitting as a sibling top-level heading. Target the
+  specific preceding heading directly, or check `mcp__obsidian__vault_get_document_map` after —
+  it shows the real heading tree, so a wrong level is visible immediately rather than assumed
+  from the call's own success response.
+- **Never `vault_patch` frontmatter.** `targetType: frontmatter` reads as field-local and is not:
+  it re-serialises the whole YAML block, so unrelated values lose their quotes, long lines get
+  re-wrapped, and an array value comes back as a quoted string instead of a real YAML list. Use
+  `synapse frontmatter set <path> <key> <value>` (or `--add-tag`/`--remove-tag` for `tags`
+  specifically; `synapse frontmatter get <path> <key>` reads one back) — it changes one field in
+  the compiled binary, byte-preserving, without ever
+  pulling the note's body into your context. It only handles a flat scalar or comma-separated
+  array field; for anything it doesn't cover (a block-style value, or an edit outside
+  frontmatter), fall back to reading the file, changing the one line, and writing the whole file
+  back.
+- **Do not patch for whitespace-precise edits.** A blank line between a heading and the block
+  under it is exactly what a patch may normalise away. A disk-level file edit with a unique anchor
+  is more predictable; Obsidian picks up external changes automatically.
+- **Never hardcode the vault path.** The REST API targets whichever vault the running headless
+  Obsidian has open. If you must reach disk, the path comes from `OBSIDIAN_VAULT_DIR` in
+  `~/.claude/synapse.conf`.
+
+## Verify with a structural invariant, not by re-reading what you wrote
+
+Re-reading the region you just changed can only confirm the change landed. It is silent about
+everything else the operation touched, which for a destructive edit is the entire question.
+
+Count the H2s (`awk '/^## /' file`) or compare the byte size against what you read. **A
+verification that cannot fail in the direction you are worried about is not a verification.**
+
+## If you do destroy something
+
+`synapse-hook db-sync` auto-commits every vault edit, so the intact version is one
+`git show <sha>:<path>` away in the vault's own git history. That hook is a vault-wide undo for
+destructive tool calls, not merely a record of intentional edits.
+
+## Tagging is part of writing a note, not a separate pass
+
+Every note-authoring command (`synapse-note`, `synapse-design-note`, `synapse-task-note`) applies tags as one of the steps in creating or substantially updating a note. There is no separate tagging pass or command — `/synapse-vault-tidy`'s recategorization signal reads tag data, it never writes it.
+
+The vocabulary is `synapse-tag-vocabulary.conf` — one tag per line, `#`-comments allowed, agent-maintained but freely human-editable. It resolves with the same tiered lookup `synapse-projects.conf` uses: first `$XDG_CONFIG_HOME/synapse/synapse-tag-vocabulary.conf` if `$XDG_CONFIG_HOME` is set, else `~/.config/synapse/synapse-tag-vocabulary.conf`, then `~/.claude/synapse-tag-vocabulary.conf` — read whichever of those exists first. If none exists yet, create it fresh at `$XDG_CONFIG_HOME/synapse/synapse-tag-vocabulary.conf` when `$XDG_CONFIG_HOME` is set, else `~/.config/synapse/synapse-tag-vocabulary.conf` if `~/.config` already exists as a directory, else `~/.claude/synapse-tag-vocabulary.conf` as the final fallback. It lives outside the portable Synapse package, same as `synapse-projects.conf` — never committed there, never copied between machines.
+
+Before adding a tag to a note, read the conf and prefer an existing entry over minting a new one. Add a new entry only for a genuinely new concept the existing vocabulary doesn't cover, and append it to the conf when you do. A note's tag set is agent-owned working content: a command may add or remove a tag freely, including one a human added by hand — there is no special protection that would block reconsidering it.
+
+Tagging many existing notes at once (a backfill) should be rare to the point of not recurring — every note created through the authoring commands above is tagged inline as part of being written, so a vault only ever needs a backfill once, for notes that predate tagging being wired in at all. If one is ever needed anyway, resolve tags mechanically first: title text, folder path, and frontmatter (`task_id` prefix, `project` field) matched against the vocabulary settle the large majority of notes with no content read at all. Read a note's body only when those signals don't already resolve to at least one vocabulary tag. A full `vault_read` on every note in a large backfill spends session context on a decision cheap signals usually already make.
+
+## The graph side of the vault
+
+`synapse/{repo}@{branch}/` is not free-form notes. Nodes are written by `synapse write-node`
+and regenerated by the `synapse-node` skill — never hand-edited, because the writer computes
+`sources` hashes, `sources_digest` and the `## Sources` mirror, and a hand edit desynchronises
+them. `_profile.txt` and `_manifest.tsv` are human-readable and may be edited directly. The
+machine-only artifacts -- `_index.bin`, `_refs.tsv`, `_tags_cache.bin` -- are not here at all: they
+live in `~/.claude/synapse-work/{repo}@{branch}/`, because they are derived, rebuildable and large,
+and the vault is version-controlled.

package/synapse-claude.md

@@ -0,0 +1,220 @@
+# Synapse Vault as permanent memory
+
+The user keeps a permanent, curated knowledge base — **Synapse Vault** —
+as a memory system separate from and complementary to the `~/.claude`
+auto-memory system: use the Vault for durable, browsable
+knowledge-base notes, not for session bookkeeping. It's an Obsidian vault,
+running headless at login with the Local REST API plugin installed — see
+"Reading and writing the vault" below for how to reach it. A SessionStart hook
+already injects the vault's `Index.md` at the start of every session, so
+you shouldn't need to go read it yourself. Don't re-read it reflexively,
+but do treat its injected contents as live information, not background
+flavor. If the hook instead reports that the configured vault has no
+`Index.md` yet, offer to seed it from the shipped default
+(`${CLAUDE_PLUGIN_ROOT}/Index.md.template`) before creating or
+linking any note in this session — never copy it yourself without asking;
+seeding the vault's foundational bootstrap file warrants a confirmation
+step the way an ordinary note-write doesn't.
+
+**This is a primary, load-bearing memory system, not an optional nicety.**
+Actively use it — don't wait to be asked. You MUST create or update a note
+whenever, during a session, any of the following happens. Before deciding
+which folder, check `Index.md`'s folder list for the matching category —
+don't rely on categories already in memory from earlier in the session,
+since a vault owner's own `Index.md` is the only authority on what exists
+and what each folder means:
+
+- A non-trivial bug is diagnosed and fixed, especially if the root cause
+  or the fix was non-obvious.
+- The user states a preference, a decision, or a piece of standing
+  context ("we always do X", "the reason we do Y is...") that isn't
+  already captured in a note.
+- A project reaches a milestone, or its direction/scope changes.
+- You do research (reading docs, comparing libraries/approaches,
+  evaluating tradeoffs) that would be wasteful to redo from scratch next
+  time.
+- An existing note is now stale or wrong in light of what just happened —
+  update it in place rather than leaving it to rot.
+
+If none of these clearly apply, err on the side of asking yourself the
+question rather than silently skipping it — a nudge hook periodically
+prompts exactly this check; treat that prompt as a real question requiring
+a real yes/no answer, not a formality to wave past.
+
+- **Linking is the highest-priority step, not an afterthought.** Before
+  writing a new note, search for related existing notes (see "Searching
+  notes" below) and link to them — prefer linking over duplicating content
+  every time a related note exists. If genuinely nothing else applies,
+  link the new note back to the index itself rather than leaving it an
+  orphan with zero backlinks.
+- **Split growing notes rather than letting one balloon.** During a long
+  session (e.g. a multi-hour debugging or optimization effort), don't just
+  keep appending every new finding to the same note indefinitely. Once a
+  note is accumulating genuinely separate findings/topics rather than one
+  cohesive update, split the new material into its own linked note instead
+  of growing the original further. A handful of focused, well-linked notes
+  is more useful later than one sprawling one — easier to search, easier to
+  link into from elsewhere, easier to skim.
+- Folders: two are structurally fixed, and hardcoded here on purpose —
+  `designs/` (design directions already discussed and agreed, created by
+  `/synapse-design-note`) and `tasks/` (concrete tracked tasks, created
+  only by `/synapse-task-note` or `/synapse-note --task`, never freeform).
+  Every install has both; the commands that write to them assume those
+  exact names regardless of what a vault's `Index.md` says. Beyond those
+  two, `Index.md`'s own folder list is the authority on what exists and
+  what each one is for — check it rather than assuming a fixed set. A
+  fresh vault ships with `research/`, `scratchpad/`, and `inbox/` as a
+  starting point (see `${CLAUDE_PLUGIN_ROOT}/Index.md.template`), but a vault owner's own
+  `Index.md` may have renamed or restructured them; if nothing about a
+  note fits an existing category, use whichever folder `Index.md` itself
+  marks as the catch-all (`inbox/` by default) rather than forcing a bad
+  fit or inventing a folder for a one-off. Agents may create new folders
+  beyond what `Index.md` lists, but folder depth is capped at two levels
+  (`folder/subfolder`, never deeper). Creating a new top-level folder
+  requires adding a matching entry to `Index.md` in the same action — the
+  index must never fall behind what's actually on disk.
+- **`tasks/` and `designs/` both group one level deeper by project**,
+  using the two-level cap above: `tasks/{project}/` and
+  `designs/{project}/` (e.g. `tasks/widget/`, `designs/synapse/`). A design
+  note already carries its project as a `project:` frontmatter field, so
+  its subfolder is that value directly. A task note has no such field —
+  decide from its task-prefix family per `Index.md`'s `tasks/` section
+  (`proj-NNN` → `widget`, `sb-NNN` → `synapse`) or, for a non-prefixed note,
+  from its title naming that same project. Either way, a note with no
+  established project family stays flat directly in `tasks/` or
+  `designs/` — don't invent a one-note subfolder.
+- **`inbox/` notes are always freeform-titled, never numbered.** This
+  includes the standalone-idea subtype ("worth doing someday" items that
+  surface mid-discussion) — it gets a plain descriptive title like any
+  other inbox note, not a sequential id. `inbox/{high,medium,low}/`
+  subfolders may exist as an optional, human-managed-only triage layer —
+  an agent never creates them, never infers a priority, and never moves a
+  note into or between them. Always write a new inbox note flat into
+  `inbox/` root; the user triages it by hand whenever they choose to.
+
+## Reading and writing the vault
+
+Obsidian runs headless at login (via a startup plugin) with the Claude
+vault already open, and the Local REST API plugin is installed there —
+this is the only valid way to reach the vault, for reads *and* for
+writes, and it always targets whichever vault is currently open in the
+running Obsidian instance, not a hardcoded path. The `obsidian` MCP
+server wraps that REST API. Do not resolve or care about
+`$OBSIDIAN_VAULT_DIR` (see `~/.claude/synapse.conf`) unless the MCP tools
+are erroring or unavailable and you must fall back to grepping files on
+disk directly — that path variable matters only for that fallback case,
+since the vault is also reachable as plain files on disk at that
+location.
+
+**Every write to a note goes through `mcp__obsidian__vault_write` or
+`vault_patch`. Never the `Write`/`Edit` tools on the on-disk path** — not
+for a one-line change, and least of all when those tools are already in
+hand from editing code earlier in the same turn, because that proximity
+is precisely what causes this to be violated. The vault being an ordinary
+directory means the wrong path *works*: Obsidian's file watcher
+converges, the auto-commit hook matches `Write|Edit` as well as the MCP
+tools, and nothing visibly breaks — which is why the habit never
+self-corrects on its own. The reason is not a failure mode to dodge; it
+is that an invariant upheld only when convenient is worth nothing.
+Nothing else in the system can rely on it, and every note then has to be
+re-checked by hand instead of trusted. Synapse's own tooling holds this
+line — `synapse write-node` curls the same REST API rather than
+writing files directly — so agent writes have no reason to differ.
+
+If a project's `.claude.json` `mcpServers.obsidian` entry ever diverges
+from the user-scoped one (e.g. points at the wrong vault path via a stdio
+`obsidian-mcp` package instead of the REST API), that's a bug in that
+project's config, not a Synapse Vault routing choice — fix it by removing
+the project-level override so the correct user-scoped REST API server
+applies.
+
+- You may create and edit notes in this vault **without asking for
+  permission first**, as long as each note is placed in the folder
+  matching its category per `Index.md`.
+- Filenames are human-readable titles (not timestamp-prefixed — Obsidian's
+  sidebar/graph display the filename directly, so a timestamp prefix reads
+  poorly there). Sanitize filesystem-illegal characters (`/ : * ? " < > |`)
+  but otherwise keep the title as-is.
+- Frontmatter carries what the filename no longer does: `title`, `created`
+  (real timestamp at creation time), and for task notes `task_id` /
+  `status` (`TODO`/`IN-PROGRESS`/`REVIEW`/`DONE`/`CANCELED`).
+- Link with Obsidian wikilinks: `[[filename]]` or `[[filename|display
+  text]]` (no extension, exact filename minus `.md`).
+- **Never hard-wrap note bodies. A newline exists if and only if a break is
+  intended in the output** — source line structure mirrors the output's block
+  structure. Write each paragraph and each list item as one single unbroken
+  line and let the editor soft-wrap it. Sentence and clause boundaries are
+  *not* logical breaks: the paragraph is the unit and sentences flow within
+  it. Line-based constructs — headings, list items, table rows, frontmatter,
+  code blocks — legitimately own their newlines and keep them.
+
+  The point is not merely that rewrapping by hand is tedious (though it is,
+  and stray newlines are diff and search-context noise). It is that this
+  makes the text **renderer-independent**: if a newline never appears where
+  no break is wanted, then "does a single newline render as `<br>` or as a
+  space?" never arises, and strict CommonMark, non-strict CommonMark,
+  Obsidian, pandoc and GitHub all produce the same result — the ambiguous
+  input case is simply gone. This is HTML's content model applied to plain
+  text: a newline is markup meaning "break here", not cosmetic formatting of
+  the source file.
+
+  It also keeps **line length a view decision rather than a content one**.
+  Hard-wrapping is the author asserting a measure, baking one viewport into
+  the text; unwrapped, the same bytes are correct at every width — Obsidian's
+  "Readable line length" on or off, a narrow split pane, a wide monitor,
+  mobile, print. Hard-wrapped prose fails both ways and is unfixable at read
+  time: at 80 columns it double-wraps raggedly in a narrow pane, and sits as a
+  fixed narrow ribbon in a wide one. Wanting a ~66-character measure is right
+  (it's a real typographic optimum, which is why that setting exists) — put it
+  in the renderer, which can adapt, not in the content, which can't.
+
+  **Corollary — never fake a break.** Don't rely on a soft newline inside a
+  paragraph or blockquote to produce separate lines, and don't reach for
+  trailing double-spaces or a trailing `\`. If several entries each need
+  their own line, they *are* separate items: use a list, which owns its line
+  breaks, nested inside the blockquote if the blockquote framing is wanted
+  (`> - entry`). Consecutive bare `>` lines render as one flowing paragraph
+  under strict CommonMark, and separating them with blank `>` lines makes
+  them full paragraphs with paragraph spacing — neither is what "three
+  labelled lines" means.
+
+  Accepted costs, both tooling-side rather than content-side: a line-based
+  diff treats a paragraph as atomic (use word-level diffing — `--word-diff`,
+  or a review UI that highlights intra-line changes), and very long lines are
+  awkward in tools that don't soft-wrap (`less` without `-S`, narrow terminal
+  diffs).
+- Create notes via the `/synapse-note` command. **Task notes are a hard
+  exception, not a style preference:** create them only with
+  `/synapse-note --task` (or compile one from a `Ready` design note with
+  `/synapse-task-note`), and make every status transition, checklist edit,
+  or `## Notes` append only through the `synapse-task` skill's own
+  procedure — never a bare `vault_write`/`vault_patch` on a task note, not
+  even mid-session, not even for a quick update. Bypassing the command/skill
+  doesn't just risk drifting from the checklist-items-plus-`## Notes`
+  skeleton every other task note shares — the skill is also where the
+  guardrails live, most importantly that `status:` never reaches `DONE`
+  through it, capped at `REVIEW` instead, and a freeform write has no such
+  cap. If the command or skill genuinely doesn't fit what a task note needs,
+  that's a signal to fix the command/skill, not a license to route around
+  it once.
+
+## Searching notes
+
+Prefer the `mcp__obsidian__` MCP tools over raw file grepping — they're
+live against the running vault and don't require re-deriving paths:
+
+- `mcp__obsidian__search_simple` — full-text search with relevance scoring
+  and match context, for "does a note about X already exist" checks.
+- `mcp__obsidian__search_query` — JsonLogic queries over note metadata
+  (frontmatter fields, tags, links, backlinks, path globs) when you need a
+  structured filter rather than free text, e.g. finding all notes with a
+  given `task_id` or `status`.
+- `mcp__obsidian__vault_list` / `vault_read` for direct navigation when you
+  already know roughly where something is.
+
+# Git commits
+
+Do not add a `Co-Authored-By: Claude ...` trailer to commit messages.
+Enforced via `attribution.commit: ""` in `~/.claude/settings.json`, which
+suppresses it mechanically — this note is a backstop in case that setting
+ever gets reverted or overridden by a project-level settings file.

package/synapse-fence-languages.conf.template

@@ -0,0 +1,24 @@
+{
+  ".java": "java",
+  ".kt": "kotlin",
+  ".kts": "kotlin",
+  ".rs": "rust",
+  ".py": "python",
+  ".ts": "typescript",
+  ".tsx": "typescript",
+  ".js": "javascript",
+  ".mjs": "javascript",
+  ".cjs": "javascript",
+  ".go": "go",
+  ".rb": "ruby",
+  ".sh": "bash",
+  ".bash": "bash",
+  ".ml": "ocaml",
+  ".mli": "ocaml",
+  ".sql": "sql",
+  ".xml": "xml",
+  ".yml": "yaml",
+  ".yaml": "yaml",
+  ".json": "json",
+  ".zig": "zig"
+}

package/synapse-ignore-files.conf.template

@@ -0,0 +1,45 @@
+# Copy this to ~/.claude/synapse-ignore-files.conf (setup.sh does this for you).
+# Never overwritten once installed -- edit or extend any time.
+#
+# Extra path patterns dropped at enumeration by synapse build-lists, on top
+# of the built-in exclusions (compiled objects, archives, media, model weights,
+# lockfiles, minified bundles, source maps). This is the repo-specific half:
+# whatever *this* machine's projects carry that is noise everywhere else too.
+#
+# One extended regular expression per line, matched against the repo-relative
+# path. Blank lines and `#` comments are ignored. Lines are OR'd together, so
+# each is independent -- there is no ordering and no negation.
+#
+# NOT gitignore syntax, deliberately. Gitignore has anchoring rules, `**`
+# globs, and negation with precedence, and a half-implementation of it that
+# silently disagrees with git on an edge case would be worse than an honest
+# regex list. If you want git's semantics, use git's: a tracked file can be
+# removed from the graph by untracking it, and `git ls-files` already respects
+# every ignore rule for untracked ones.
+#
+# Superseded nothing: $SYNAPSE_EXTRA_EXCLUDE_RE still works and is OR'd with
+# whatever is here, so an existing one-off invocation keeps behaving the same.
+#
+# WHAT BELONGS HERE, and what does not. Excluding a path removes it from the
+# graph entirely -- it gets no owning node, so searching its name in the vault
+# finds nothing, and editing it flags nothing stale. That is right for build
+# output and vendored code, which nobody asks questions about. It is wrong for
+# files that are merely *uninteresting to read*: a declarative artifact whose
+# edits still change behaviour wants to stay covered, so that its owning node
+# is flagged when it changes, even if no summary is ever written from it.
+# Coverage and relevance are separate questions; this file answers only the
+# first one.
+#
+# Examples, all commented out -- the default is to exclude nothing extra.
+
+# Vendored dependencies checked into the tree
+# (^|/)(vendor|third_party|external)/
+
+# Generated sources that are tracked rather than gitignored
+# (^|/)(gen|generated|__generated__)/
+
+# Fixture corpora and recorded payloads -- large, numerous, never read
+# (^|/)(fixtures|testdata|__snapshots__|cassettes)/
+
+# IDE and tooling metadata that happens to be tracked
+# (^|/)\.(idea|vscode|settings)/