@noesis-brain/mcp-server 2.0.0 → 2.1.0

package/skill-templates/noesis-refine-note.md

@@ -1,92 +1,92 @@
----
-description: Polish a Noesis note's metadata and structure. Use a scope (today/session/catalog/cascade) or pass a specific note to iterate over multiple notes.
----
-
-Refine Noesis notes: fill missing metadata (title, description, keywords, aliases), tighten structure (heading hierarchy, frontmatter completeness), refresh AI-rated quality and importance scores. Works on a single note or a batch discovered by scope.
-
-## Arguments
-
-$ARGUMENTS
-
-Accepted forms:
-
-- (no args) — ask the user to pick a scope via `AskUserQuestion`.
-- `<path-or-filename>.md` — refine this specific note.
-- `<topic-or-query>` — search for matching notes and offer them to the user.
-- `today` — discover and refine notes referenced in today's conversation logs.
-- `session [id]` — discover and refine notes referenced in a specific session (or the latest).
-- `catalog <name>` — refine all notes in a named Noesis catalog.
-- `cascade <anchor>` — refine the anchor note plus its semantically-similar neighbors.
-- `--limit <N>` — cap how many notes a batch mode processes (default: 15).
-- `--dry-run` — show what would change without writing.
-
-## Workflow
-
-### Step 1 — Parse mode
-
-From `$ARGUMENTS`, determine `MODE` using the first matching rule:
-
-| Priority | Pattern | Mode |
-|---|---|---|
-| 1 | `cascade <anchor>` | CASCADE |
-| 2 | `today` (anywhere) | TODAY |
-| 3 | `catalog <name>` | CATALOG |
-| 4 | `session [<id>]` | SESSION |
-| 5 | Ends in `.md` (path or filename) | SINGLE |
-| 6 | Non-empty string (treated as search query) | SEARCH |
-| 7 | Empty | ASK |
-
-For `ASK`, prompt the user via `AskUserQuestion` with options for each mode and proceed once they pick.
-
-### Step 2 — Discover candidate notes
-
-Cap the candidate list per mode:
-
-- **SINGLE**: just the one note. Resolve filename to a path via `mcp__noesis__search_notes` if needed.
-- **SEARCH**: call `mcp__noesis__search_notes(query)` with the user's query; show the top 10, ask the user to pick one or more.
-- **TODAY**: read `~/.claude/logs/console_*.clog` files dated today, extract note paths and search terms mentioned, deduplicate, cap at `--limit` (default 15).
-- **SESSION**: same as TODAY but scoped to the chosen session UUID (or the latest if unspecified).
-- **CATALOG**: call `mcp__noesis__list_notes(catalog: <name>)`, cap at `--limit` (default 25).
-- **CASCADE**: resolve the anchor note's ID via `mcp__noesis__get_note(path)`, then call `mcp__noesis__find_similar_notes(note_id, limit: --limit ?? 10)`. Include the anchor itself.
-
-Show the discovered list to the user and ask them to confirm or trim before refining. Sort by ascending `quality_score` (worst first) so the most-needed refinement happens first.
-
-### Step 3 — Refine each note sequentially
-
-For each candidate note:
-
-1. **Read current state:** `mcp__noesis__get_note(path|id)` to get the full metadata + content.
-2. **Fill missing metadata:** call `mcp__noesis__enhance_note_metadata(note_id)` with the relevant fields requested (`title`, `description`, `keywords`, `aliases`). The MCP tool uses AI to derive values from the note content. Apply with user approval if the change looks substantial; auto-apply if filling pure gaps (e.g., empty `keywords`).
-3. **Structural suggestions** (light touch — skip if `--dry-run`):
-   - Frontmatter completeness: title / description / keywords / aliases / date / updated / status / importance_score / quality_score.
-   - Heading hierarchy: surface any H3+ without parent H2, or duplicate H1s.
-   - Suggest and apply with `Edit` after user approval per file.
-4. **Refresh scores:** call `mcp__noesis__rate_quality(note_id)` and `mcp__noesis__rate_importance(note_id)` — these run an AI rating pass; track the delta vs the prior values.
-5. **Push:** if anything changed locally, call `mcp__noesis__sync_notes(files: [<absolute path>])` to push.
-
-### Step 4 — Report
-
-Per-note line:
-
-- `refined <path>: metadata filled (Δ desc / kw / aliases), quality <old> → <new>, importance <old> → <new>`
-- `refined <path>: no changes needed`
-- `skipped <path> (<reason>)`
-
-Final tally:
-
-- `Total: T. Refined: R. Score delta: avg +X quality / +Y importance. Skipped: S. Errors: E.`
-
-## Constraints
-
-- Never overwrite a user-authored description with an AI-generated one without confirmation. The MCP tool returns suggestions; you apply them only after the user OKs substantial replacements.
-- Never touch note `content` body text in refinement — only frontmatter and structural markers (headings, list normalization). Body rewrites are out of scope; that's an editing task, not a refinement.
-- One note at a time — sequential, not parallel. Each push uses `sync_notes(files:[...])` so conflicts surface per-note.
-- If a sync push returns conflict, hand off to `/noesis-sync` (which has the conflict-resolution flow embedded) or stop the batch and report.
-
-## Examples
-
-- `/noesis-refine-note c:/path/to/note.md` — refine a single note.
-- `/noesis-refine-note today` — refine notes touched today.
-- `/noesis-refine-note catalog Work` — refine the Work catalog.
-- `/noesis-refine-note cascade c:/path/to/anchor.md` — refine the anchor and its semantic neighbors.
-- `/noesis-refine-note today --dry-run` — preview only.
+---
+description: Polish a Noesis note's metadata and structure. Use a scope (today/session/catalog/cascade) or pass a specific note to iterate over multiple notes.
+---
+
+Refine Noesis notes: fill missing metadata (title, description, keywords, aliases), tighten structure (heading hierarchy, frontmatter completeness), refresh AI-rated quality and importance scores. Works on a single note or a batch discovered by scope.
+
+## Arguments
+
+$ARGUMENTS
+
+Accepted forms:
+
+- (no args) — ask the user to pick a scope via `AskUserQuestion`.
+- `<path-or-filename>.md` — refine this specific note.
+- `<topic-or-query>` — search for matching notes and offer them to the user.
+- `today` — discover and refine notes referenced in today's conversation logs.
+- `session [id]` — discover and refine notes referenced in a specific session (or the latest).
+- `catalog <name>` — refine all notes in a named Noesis catalog.
+- `cascade <anchor>` — refine the anchor note plus its semantically-similar neighbors.
+- `--limit <N>` — cap how many notes a batch mode processes (default: 15).
+- `--dry-run` — show what would change without writing.
+
+## Workflow
+
+### Step 1 — Parse mode
+
+From `$ARGUMENTS`, determine `MODE` using the first matching rule:
+
+| Priority | Pattern | Mode |
+|---|---|---|
+| 1 | `cascade <anchor>` | CASCADE |
+| 2 | `today` (anywhere) | TODAY |
+| 3 | `catalog <name>` | CATALOG |
+| 4 | `session [<id>]` | SESSION |
+| 5 | Ends in `.md` (path or filename) | SINGLE |
+| 6 | Non-empty string (treated as search query) | SEARCH |
+| 7 | Empty | ASK |
+
+For `ASK`, prompt the user via `AskUserQuestion` with options for each mode and proceed once they pick.
+
+### Step 2 — Discover candidate notes
+
+Cap the candidate list per mode:
+
+- **SINGLE**: just the one note. Resolve filename to a path via `mcp__noesis__search_notes` if needed.
+- **SEARCH**: call `mcp__noesis__search_notes(query)` with the user's query; show the top 10, ask the user to pick one or more.
+- **TODAY**: read `~/.claude/logs/console_*.clog` files dated today, extract note paths and search terms mentioned, deduplicate, cap at `--limit` (default 15).
+- **SESSION**: same as TODAY but scoped to the chosen session UUID (or the latest if unspecified).
+- **CATALOG**: call `mcp__noesis__list_notes(catalog: <name>)`, cap at `--limit` (default 25).
+- **CASCADE**: resolve the anchor note's ID via `mcp__noesis__get_note(path)`, then call `mcp__noesis__find_similar_notes(note_id, limit: --limit ?? 10)`. Include the anchor itself.
+
+Show the discovered list to the user and ask them to confirm or trim before refining. Sort by ascending `quality_score` (worst first) so the most-needed refinement happens first.
+
+### Step 3 — Refine each note sequentially
+
+For each candidate note:
+
+1. **Read current state:** `mcp__noesis__get_note(path|id)` to get the full metadata + content.
+2. **Fill missing metadata:** call `mcp__noesis__enhance_note_metadata(note_id)` with the relevant fields requested (`title`, `description`, `keywords`, `aliases`). The MCP tool uses AI to derive values from the note content. Apply with user approval if the change looks substantial; auto-apply if filling pure gaps (e.g., empty `keywords`).
+3. **Structural suggestions** (light touch — skip if `--dry-run`):
+   - Frontmatter completeness: title / description / keywords / aliases / date / updated / status / importance_score / quality_score.
+   - Heading hierarchy: surface any H3+ without parent H2, or duplicate H1s.
+   - Suggest and apply with `Edit` after user approval per file.
+4. **Refresh scores:** call `mcp__noesis__rate_quality(note_id)` and `mcp__noesis__rate_importance(note_id)` — these run an AI rating pass; track the delta vs the prior values.
+5. **Push:** if anything changed locally, call `mcp__noesis__sync_notes(files: [<absolute path>])` to push.
+
+### Step 4 — Report
+
+Per-note line:
+
+- `refined <path>: metadata filled (Δ desc / kw / aliases), quality <old> → <new>, importance <old> → <new>`
+- `refined <path>: no changes needed`
+- `skipped <path> (<reason>)`
+
+Final tally:
+
+- `Total: T. Refined: R. Score delta: avg +X quality / +Y importance. Skipped: S. Errors: E.`
+
+## Constraints
+
+- Never overwrite a user-authored description with an AI-generated one without confirmation. The MCP tool returns suggestions; you apply them only after the user OKs substantial replacements.
+- Never touch note `content` body text in refinement — only frontmatter and structural markers (headings, list normalization). Body rewrites are out of scope; that's an editing task, not a refinement.
+- One note at a time — sequential, not parallel. Each push uses `sync_notes(files:[...])` so conflicts surface per-note.
+- If a sync push returns conflict, hand off to `/noesis-sync` (which has the conflict-resolution flow embedded) or stop the batch and report.
+
+## Examples
+
+- `/noesis-refine-note c:/path/to/note.md` — refine a single note.
+- `/noesis-refine-note today` — refine notes touched today.
+- `/noesis-refine-note catalog Work` — refine the Work catalog.
+- `/noesis-refine-note cascade c:/path/to/anchor.md` — refine the anchor and its semantic neighbors.
+- `/noesis-refine-note today --dry-run` — preview only.

package/skill-templates/noesis-skim-read.md

@@ -0,0 +1,72 @@
+---
+description: Generate Skim-Read key parts for a Noesis note YOURSELF (no in-app AI) and persist them as suggested marks — the Gemini-free fallback for the Skim-Read panel. Accepts a note ID or file path.
+argument-hint: <note path or ID> [--style gist|balanced|thorough|structure|keyword] [--intensity light|normal|heavy]
+---
+
+Generate the KEY PARTS a reader should focus on in a Noesis note and persist them, so the note's Skim-Read panel surfaces them. YOU do the extraction (using your own model) and the server only anchors + saves — no in-app Gemini call. This is the fallback to use when the app's built-in Skim-Read is rate-limited / 503, or any time you want to drive it from Claude Code.
+
+## Arguments
+
+$ARGUMENTS
+
+Accepted forms:
+
+- `<path>.md` — a file path (e.g. from the Noesis web UI "Copy File Path" button). Quote paths with spaces.
+- `<id>` — a numeric Note ID.
+- Natural language — e.g. `Create skim-read for the note "/path/to/note.md"`; extract the path/ID from the request.
+- `--style <s>` — reading strategy: `gist` | `balanced` (default) | `thorough` | `structure` | `keyword`.
+- `--intensity <i>` — how many parts: `light` | `normal` (default) | `heavy`.
+
+## Workflow
+
+### Step 1 — Resolve the note
+
+From `$ARGUMENTS`, extract the target: an all-digits token is a Note ID; anything else (a path, possibly quoted) is a file path. Capture optional `--style` / `--intensity`. If neither an ID nor a path is present, ask the user which note via `AskUserQuestion`.
+
+### Step 2 — Read the note content
+
+Call `mcp__noesis__get_note(id: <id>)` or `mcp__noesis__get_note(path: <path>)`. Use the returned `content` as the source of truth. Do NOT call `mcp__noesis__get_note_skim_read` — that uses the in-app AI, which this skill deliberately bypasses.
+
+### Step 3 — Generate the key parts
+
+Pick the spans a reader should focus on to get the gist efficiently — spread across the note's sections, each a DISTINCT idea (don't spend several parts on the same point). For each part produce `{ granularity, quote, headingPath?, importance, reason }`:
+
+- **quote** — copied CHARACTER-FOR-CHARACTER (verbatim) from `content`. Do NOT paraphrase, translate, fix typos, summarize, or add ellipses. Make each quote long enough to occur exactly once (add surrounding words if a short phrase repeats).
+  - `section` → the heading line text · `sentence` → the full sentence · `paragraph` → its first ~12 words · `keyword` → the exact token(s).
+- **granularity** — `section` | `paragraph` | `sentence` | `keyword`.
+- **importance** — 0..1; reserve > 0.8 for the few genuinely load-bearing parts.
+- **reason** — ≤ 12 words, plainly what the span says (no hype words).
+- Only quote VISIBLE prose. Skip code fences (```), YAML frontmatter, HTML tags, and any COLLAPSED `<details>` block (one without the `open` attribute).
+- `headingPath` — ancestor heading texts (top-most first) to disambiguate a repeated quote; omit or `[]` if unknown.
+
+Prefer fewer high-confidence parts over filling a quota; it is correct to return few parts for a short or list-like note.
+
+### Step 4 — Apply
+
+Call `mcp__noesis__apply_note_skim_read` with `{ id | path, keyParts: [...], style?, intensity? }`. The server anchors each verbatim quote and persists matches as `suggested` marks (replacing prior un-accepted suggestions; accepted/dismissed marks are preserved).
+
+### Step 5 — Fix unmatched quotes (loop)
+
+The result includes `unmatchedQuotes` — quotes that did not occur verbatim in the note. If non-empty:
+
+1. Re-read those spans in `content` and correct each quote to the note's EXACT text.
+2. Call `mcp__noesis__apply_note_skim_read` again with the corrected full set.
+3. Repeat until `unmatchedQuotes` is empty (or you've corrected every quote you reasonably can — typically ≤ 3 rounds).
+
+### Step 6 — Report
+
+State how many key parts were applied (`keyPartCount`), list any quotes that still didn't anchor, and tell the user to open the note's **Skim-Read** panel to see them.
+
+## Constraints
+
+- Quotes MUST be verbatim slices of the note content — never invented or edited. A verbatim quote is what lets the server anchor the mark.
+- This skill never calls the in-app Skim-Read AI; generating the parts yourself is the entire point (it works when Gemini is down).
+- The path must sit under one of the user's registered Noesis roots, and the note must exist in the database the MCP server targets. If the lookup 404s, confirm the path/ID and that the MCP server points at the right backend.
+- Do not edit the note's body — Skim-Read only adds non-destructive `suggested` marks.
+
+## Examples
+
+- `/noesis-skim-read "/path/to/note.md"` — skim-read by file path.
+- `/noesis-skim-read 2302 --style gist` — terse gist of note 2302.
+- `/noesis-skim-read 2302 --intensity heavy` — more key parts.
+- `Create skim-read for the note "/path/to/note.md"` — natural-language invocation.

package/skill-templates/noesis-sync.md

@@ -1,110 +1,110 @@
----
-description: Sync local Noesis notes with the cloud — pulls web-UI edits, pushes local changes, resolves conflicts inline.
----
-
-The one-stop sync command for Noesis notes. Discovers notes edited via the Noesis web UI (Quick Fix), pulls them locally first, pushes your local changes, and resolves any conflicts inline with your input.
-
-## Arguments
-
-$ARGUMENTS
-
-Accepted forms:
-- (no args) — auto-scope: sync files edited in this conversation, else the current project root.
-- `--files <absolute-paths>` — push these specific files (still pulls web-UI edits first for the matching root).
-- `<root-name>` — bulk sync the named root (full scan).
-- `--dry-run` — preview all actions without writing anything.
-- `--skip-online-edits` — skip the web-UI-edit pull step (advanced; rarely needed).
-
-## Workflow
-
-CRITICAL: never start backend servers, write temporary scripts, or improvise HTTP calls. The cloud API at noesis-notes.vercel.app is always available through the MCP tool or the bundled script.
-
-### Step 1 — Discover web-UI edits (unless `--skip-online-edits`)
-
-Call `mcp__noesis__list_edited_online_notes` (filter by `root_id` if `$ARGUMENTS` names a root). For each returned note inspect the `localStatus`:
-
-- `unchanged` — local file matches the last sync baseline; pull is safe and silent.
-- `not_on_disk` — file does not exist locally; pull creates it (auto-pull, no conflict possible).
-- `also_modified` — local file has diverged from the baseline. Tell the user the conflict cascade will run for those entries and ask `AskUserQuestion` to confirm before proceeding. If they decline, skip Step 2 for the `also_modified` entries and continue to Step 3 for the rest.
-
-If `list_edited_online_notes` returns an empty list, skip to Step 3.
-
-### Step 2 — Pull web-UI edits
-
-For each pending note from Step 1 (excluding any the user declined), call:
-
-```
-mcp__noesis__sync_notes(files: ["<absolute path = root_path + '/' + relative_path>"])
-```
-
-Process one file at a time so per-file conflicts surface immediately. Track each result for the Step 5 summary.
-
-### Step 3 — Push local changes
-
-Apply scoping:
-
-1. **Specific files just edited in this conversation** → pass `files: [<paths>]` (do NOT sync everything else).
-2. **User passed `--files <paths>`** → use those paths.
-3. **User passed a root name** → pass `root: "<name>"` (slow full scan).
-4. **No context, no args** → pass `root` matching the current project directory if it maps to a registered root; otherwise fall back to `files` of the files edited in this conversation.
-
-Choose the tier:
-
-- **Tier 1 (preferred):** call `mcp__noesis__sync_notes` with the resolved scope (and `dryRun: true` if `--dry-run`).
-- **Tier 2 (MCP unavailable):** run `node "{{NOESIS_MCP_SCRIPT_PATH}}" [args]` — the bundled script reads its token from `~/.claude.json` → `mcpServers.noesis.env.NOESIS_API_TOKEN` and talks to the cloud API directly. Pass the same CLI args (`--files`, `--root`, `--dry-run`).
-- **Tier 3 (no Node.js):** call the cloud HTTPS endpoints directly via `curl`. Read the token from `~/.claude.json` as above.
-  ```bash
-  curl -H "Authorization: Bearer $TOKEN" https://noesis-notes.vercel.app/api/mcp/roots?forSync=true
-  curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-    https://noesis-notes.vercel.app/api/mcp/notes/upsert \
-    -d '{"file":{"path":"...","relativePath":"...","content":"...","hash":"...","rootId":N,"rootName":"...","project":"..."},"metadata":{}}'
-  ```
-
-### Step 4 — Resolve conflicts inline (if any)
-
-If Step 2 or Step 3 reported `conflicts.length > 0` (Tier C of the bidirectional sync — overlapping hunks that anchor reapply and `node-diff3` could not auto-merge), do this PER conflicting file rather than reporting "run another skill":
-
-1. **Gather three sides:**
-   - **CLOUD** — `mcp__noesis__get_note(id)` (id is in the conflict payload, or resolve via `mcp__noesis__list_notes` filtered to the relative path).
-   - **LOCAL** — `Read` the local file at the resolved absolute path.
-   - **BASE** — read `.noesis/baseline/<relative_path>` under the root. If the baseline file is missing (legacy sync state), tell the user and ask whether to treat as a two-way merge or skip the file.
-
-2. **Classify each pair of overlapping hunks:**
-   - **Trivial overlap** (one side adds, other doesn't touch; or one side is a strict superset) → auto-merge silently with the inclusive result.
-   - **Mixed overlap** → resolve the trivial parts automatically; STOP and ask only about the irreconcilable parts.
-   - **Semantic overlap** (opposing edits, contradictory rewrites) → present the diff and ask via `AskUserQuestion`: `keep-local` / `keep-cloud` / paste merged text. NEVER silently overwrite.
-
-3. **Apply the merge:**
-   - `Write` the merged content to the local file.
-   - Call `mcp__noesis__sync_notes(files: [<absolute path>])` to push the resolved version.
-   - If the push returns 409 (cloud changed since this step started), the cloud was updated concurrently — repeat Step 4 for that file from the top.
-   - After a clean push, call `POST /api/mcp/notes/:id/clear-conflict` (via `Bash` + `curl` with the API token) to clear the cloud `conflict_marker`.
-
-Process one file at a time. Do NOT batch a chosen-text response across multiple files.
-
-### Step 5 — Report
-
-Print one line per file processed:
-
-- `pulled (web-UI edit applied locally)` — Step 2 succeeded with no conflict.
-- `pushed (local change applied to cloud)` — Step 3 succeeded with no conflict.
-- `merged auto for <path>` — Step 4 resolved trivial overlap without user input.
-- `merged by user for <path>` — Step 4 resolved with explicit user choice.
-- `skipped <path> (<reason>)` — user declined, baseline missing, or other.
-
-End with a final tally: `Pulled: N. Pushed: M. Merged: K (auto X / by-user Y). Skipped: Z. Errors: E.`
-
-## Constraints
-
-- Never silently overwrite opposing edits — always present the diff and ask.
-- Never modify cloud-side content directly via `PUT /api/notes/:id` — go through `sync_notes` so the optimistic-concurrency 409 catches concurrent changes.
-- Never strip frontmatter or H1 from either side during merge — preserve verbatim from whichever side wrote them.
-- One file at a time for conflict resolution.
-
-## Examples
-
-- `/noesis-sync` — auto-scope to recent conversation edits or current project root.
-- `/noesis-sync --dry-run` — preview the full flow without writing.
-- `/noesis-sync --files <absolute-path>` — push a specific file (still pulls web-UI edits first).
-- `/noesis-sync <root-name>` — bulk sync a named root.
-- `/noesis-sync --skip-online-edits` — push only, skip the web-UI pull step.
+---
+description: Sync local Noesis notes with the cloud — pulls web-UI edits, pushes local changes, resolves conflicts inline.
+---
+
+The one-stop sync command for Noesis notes. Discovers notes edited via the Noesis web UI (Quick Fix), pulls them locally first, pushes your local changes, and resolves any conflicts inline with your input.
+
+## Arguments
+
+$ARGUMENTS
+
+Accepted forms:
+- (no args) — auto-scope: sync files edited in this conversation, else the current project root.
+- `--files <absolute-paths>` — push these specific files (still pulls web-UI edits first for the matching root).
+- `<root-name>` — bulk sync the named root (full scan).
+- `--dry-run` — preview all actions without writing anything.
+- `--skip-online-edits` — skip the web-UI-edit pull step (advanced; rarely needed).
+
+## Workflow
+
+CRITICAL: never start backend servers, write temporary scripts, or improvise HTTP calls. The cloud API at noesis-notes.vercel.app is always available through the MCP tool or the bundled script.
+
+### Step 1 — Discover web-UI edits (unless `--skip-online-edits`)
+
+Call `mcp__noesis__list_edited_online_notes` (filter by `root_id` if `$ARGUMENTS` names a root). For each returned note inspect the `localStatus`:
+
+- `unchanged` — local file matches the last sync baseline; pull is safe and silent.
+- `not_on_disk` — file does not exist locally; pull creates it (auto-pull, no conflict possible).
+- `also_modified` — local file has diverged from the baseline. Tell the user the conflict cascade will run for those entries and ask `AskUserQuestion` to confirm before proceeding. If they decline, skip Step 2 for the `also_modified` entries and continue to Step 3 for the rest.
+
+If `list_edited_online_notes` returns an empty list, skip to Step 3.
+
+### Step 2 — Pull web-UI edits
+
+For each pending note from Step 1 (excluding any the user declined), call:
+
+```
+mcp__noesis__sync_notes(files: ["<absolute path = root_path + '/' + relative_path>"])
+```
+
+Process one file at a time so per-file conflicts surface immediately. Track each result for the Step 5 summary.
+
+### Step 3 — Push local changes
+
+Apply scoping:
+
+1. **Specific files just edited in this conversation** → pass `files: [<paths>]` (do NOT sync everything else).
+2. **User passed `--files <paths>`** → use those paths.
+3. **User passed a root name** → pass `root: "<name>"` (slow full scan).
+4. **No context, no args** → pass `root` matching the current project directory if it maps to a registered root; otherwise fall back to `files` of the files edited in this conversation.
+
+Choose the tier:
+
+- **Tier 1 (preferred):** call `mcp__noesis__sync_notes` with the resolved scope (and `dryRun: true` if `--dry-run`).
+- **Tier 2 (MCP unavailable):** run `node "{{NOESIS_MCP_SCRIPT_PATH}}" [args]` — the bundled script reads its token from `~/.claude.json` → `mcpServers.noesis.env.NOESIS_API_TOKEN` and talks to the cloud API directly. Pass the same CLI args (`--files`, `--root`, `--dry-run`).
+- **Tier 3 (no Node.js):** call the cloud HTTPS endpoints directly via `curl`. Read the token from `~/.claude.json` as above.
+  ```bash
+  curl -H "Authorization: Bearer $TOKEN" https://noesis-notes.vercel.app/api/mcp/roots?forSync=true
+  curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+    https://noesis-notes.vercel.app/api/mcp/notes/upsert \
+    -d '{"file":{"path":"...","relativePath":"...","content":"...","hash":"...","rootId":N,"rootName":"...","project":"..."},"metadata":{}}'
+  ```
+
+### Step 4 — Resolve conflicts inline (if any)
+
+If Step 2 or Step 3 reported `conflicts.length > 0` (Tier C of the bidirectional sync — overlapping hunks that anchor reapply and `node-diff3` could not auto-merge), do this PER conflicting file rather than reporting "run another skill":
+
+1. **Gather three sides:**
+   - **CLOUD** — `mcp__noesis__get_note(id)` (id is in the conflict payload, or resolve via `mcp__noesis__list_notes` filtered to the relative path).
+   - **LOCAL** — `Read` the local file at the resolved absolute path.
+   - **BASE** — read `.noesis/baseline/<relative_path>` under the root. If the baseline file is missing (legacy sync state), tell the user and ask whether to treat as a two-way merge or skip the file.
+
+2. **Classify each pair of overlapping hunks:**
+   - **Trivial overlap** (one side adds, other doesn't touch; or one side is a strict superset) → auto-merge silently with the inclusive result.
+   - **Mixed overlap** → resolve the trivial parts automatically; STOP and ask only about the irreconcilable parts.
+   - **Semantic overlap** (opposing edits, contradictory rewrites) → present the diff and ask via `AskUserQuestion`: `keep-local` / `keep-cloud` / paste merged text. NEVER silently overwrite.
+
+3. **Apply the merge:**
+   - `Write` the merged content to the local file.
+   - Call `mcp__noesis__sync_notes(files: [<absolute path>])` to push the resolved version.
+   - If the push returns 409 (cloud changed since this step started), the cloud was updated concurrently — repeat Step 4 for that file from the top.
+   - After a clean push, call `POST /api/mcp/notes/:id/clear-conflict` (via `Bash` + `curl` with the API token) to clear the cloud `conflict_marker`.
+
+Process one file at a time. Do NOT batch a chosen-text response across multiple files.
+
+### Step 5 — Report
+
+Print one line per file processed:
+
+- `pulled (web-UI edit applied locally)` — Step 2 succeeded with no conflict.
+- `pushed (local change applied to cloud)` — Step 3 succeeded with no conflict.
+- `merged auto for <path>` — Step 4 resolved trivial overlap without user input.
+- `merged by user for <path>` — Step 4 resolved with explicit user choice.
+- `skipped <path> (<reason>)` — user declined, baseline missing, or other.
+
+End with a final tally: `Pulled: N. Pushed: M. Merged: K (auto X / by-user Y). Skipped: Z. Errors: E.`
+
+## Constraints
+
+- Never silently overwrite opposing edits — always present the diff and ask.
+- Never modify cloud-side content directly via `PUT /api/notes/:id` — go through `sync_notes` so the optimistic-concurrency 409 catches concurrent changes.
+- Never strip frontmatter or H1 from either side during merge — preserve verbatim from whichever side wrote them.
+- One file at a time for conflict resolution.
+
+## Examples
+
+- `/noesis-sync` — auto-scope to recent conversation edits or current project root.
+- `/noesis-sync --dry-run` — preview the full flow without writing.
+- `/noesis-sync --files <absolute-path>` — push a specific file (still pulls web-UI edits first).
+- `/noesis-sync <root-name>` — bulk sync a named root.
+- `/noesis-sync --skip-online-edits` — push only, skip the web-UI pull step.

package/templates/claude-md-block.md

@@ -1,22 +1,26 @@
-## Noesis MCP — conventions
-
-### Writing notes
-- Use plain `##` headings for primary sections — Noesis builds its sidebar outline from them. Reserve collapsible `<details>` blocks for appendix-style noise (logs, references, changelogs).
-
-### Pushing notes to the cloud
-- "Sync to Noesis" means push to the Noesis cloud database, not `cp` to a folder.
-- Use `mcp__noesis__sync_notes` with `files: [<absolute paths>]`.
-- Files must be within a registered root — check via `mcp__noesis__list_roots`.
-
-### Reading and discovering notes
-- Note relations and codebase links live in the Noesis **database**, not in `.md` frontmatter — don't grep `.md` files for them.
-- Use `mcp__noesis__get_note` (read by ID or path), `mcp__noesis__find_similar_notes` (semantic similarity), `mcp__noesis__search_semantic` / `mcp__noesis__search_notes` (meaning / keyword search), `mcp__noesis__update_relations` (read-only when called without the `relations` param).
-
-### Path-as-identifier (cross-machine)
-For any path inside a Noesis-watched root (paths containing `/.noesis/`, or any path under a directory listed by `mcp__noesis__list_roots`), the path is a Noesis identifier — the cloud copy is always authoritative, and the local copy on this machine may be **missing** (other machine) or **stale** (the user edited the note via the Noesis web UI's Quick Fix; the web UI surfaces that state with the badge 「在线编辑 · 等待本地同步」). Either way, the local copy is not a trustworthy source of truth — reading it directly silently feeds outdated content into the rest of the turn.
-
-Trigger: when the user references such a path and you are about to read, edit, or otherwise consume it, sync first — once per path per turn, before the first tool call that touches it. Not before subsequent re-reads of the same path in the same turn.
-
-- **NORMAL mode (writes allowed):** call `mcp__noesis__sync_notes(files: [<that path>])`. The three-way merge handles every case: in-sync → cheap no-op (`'skip'`); cloud-newer → auto-pulls to local disk; local-newer → pushes to cloud; both diverged → conflict cascade (3-way merge); missing locally → auto-creates from cloud. In all five cases the next `Read`/`Edit`/`Write` sees the right bytes.
-- **PLAN mode (writes forbidden):** call `mcp__noesis__get_note(path=<that path>)` for a read-only cloud lookup. Compare its `content_hash` / `updated_at` against the local file's hash / mtime; if drift exists, surface it in the plan and propose `sync_notes` as Step 1 of the implementation.
-- In either mode, do NOT fall back to Glob/Grep to hunt for similar filenames; do NOT ask the user to disambiguate the path. The cloud is authoritative for Noesis-watched paths.
+## Noesis MCP — conventions
+
+### Writing notes
+- Use plain `##` headings for primary sections — Noesis builds its sidebar outline from them. Reserve collapsible `<details>` blocks for appendix-style noise (logs, references, changelogs).
+
+### Pushing notes to the cloud
+- "Sync to Noesis" means push to the Noesis cloud database, not `cp` to a folder.
+- Use `mcp__noesis__sync_notes` with `files: [<absolute paths>]`.
+- Files must be within a registered root — check via `mcp__noesis__list_roots`.
+
+### Reading and discovering notes
+- Note relations and codebase links live in the Noesis **database**, not in `.md` frontmatter — don't grep `.md` files for them.
+- Use `mcp__noesis__get_note` (read by ID or path), `mcp__noesis__find_similar_notes` (semantic similarity), `mcp__noesis__search_semantic` / `mcp__noesis__search_notes` (meaning / keyword search), `mcp__noesis__update_relations` (read-only when called without the `relations` param).
+
+### Path-as-identifier (cross-machine)
+For any path inside a Noesis-watched root, the path is a Noesis identifier — the cloud copy is always authoritative, and the local copy on this machine may be **missing** (other machine) or **stale** (the user edited the note via the Noesis web UI's Quick Fix; the web UI surfaces that state with the badge 「在线编辑 · 等待本地同步」). Either way, the local copy is not a trustworthy source of truth — reading it directly silently feeds outdated content into the rest of the turn.
+
+A path is Noesis-watched if it contains `/.noesis/` **OR sits under a folder named `Noesis`** (the cloud root — e.g. `~/Noesis/…`, `%USERPROFILE%\Noesis\…`, or `C:\Users\<you>\Noesis\…`), **OR** is under any directory listed by `mcp__noesis__list_roots`. The `Noesis`/`.noesis` folder name is the cheap signal; when in doubt, treat a `.md` path that looks like a note as watched and let the MCP tool decide.
+
+Trigger: when the user references such a path and you are about to read, edit, or otherwise consume it, sync first — once per path per turn, before the first tool call that touches it. Not before subsequent re-reads of the same path in the same turn.
+
+**RECOVERY RULE:** if `Read` returns "file does not exist" for a `.md` path that looks like a note — especially one under a `.noesis`/`Noesis` folder — your immediate next action is the MCP tool below with the **same path**. Do NOT conclude the note is missing, on another machine, or that the path was mistyped until the MCP lookup also fails.
+
+- **NORMAL mode (writes allowed):** call `mcp__noesis__sync_notes(files: [<that path>])`. The three-way merge handles every case: in-sync → cheap no-op (`'skip'`); cloud-newer → auto-pulls to local disk; local-newer → pushes to cloud; both diverged → conflict cascade (3-way merge); missing locally → auto-creates from cloud. In all five cases the next `Read`/`Edit`/`Write` sees the right bytes.
+- **PLAN mode (writes forbidden):** call `mcp__noesis__get_note(path=<that path>)` for a read-only cloud lookup. Compare its `content_hash` / `updated_at` against the local file's hash / mtime; if drift exists, surface it in the plan and propose `sync_notes` as Step 1 of the implementation.
+- In either mode, do NOT fall back to Glob/Grep to hunt for similar filenames; do NOT ask the user to disambiguate the path. The cloud is authoritative for Noesis-watched paths.

package/templates/claude-md-restructure-on-sync.md

@@ -0,0 +1,10 @@
+### Restructuring notes that grew by accretion (optional)
+Before syncing a note that shows the **accretion smell** — bolt-on sections (e.g. "a later round of testing exposed a case sections 1–7 didn't cover"), duplicated passages re-explaining the same point under different headings, or a chronological log of patches — do NOT push the sprawl as-is, and do NOT just append another section. Notes that grow by accretion become hard to study.
+
+Restructure first:
+1. Read the FULL current note (`mcp__noesis__get_note` or the local file) so you preserve the substance — diagrams, inventories, code snippets, instrumentation, repro tables.
+2. Reorganize into ONE coherent narrative led by the **root cause / main finding**, not by chronology: Context & Symptom → Root Cause → supporting detail → inventory/appendix.
+3. Merge the duplicated sections; fold each bolted-on "later round" addition into the section it belongs to. Revise the existing section rather than adding a new one.
+4. Then sync, and briefly say which notes you restructured — never rewrite a note body silently.
+
+This deliberately permits **body rewrites** on sync — broader than `/noesis-refine-note`, which only touches metadata and headings. You are reorganizing for clarity, not deleting content: preserve every fact, diagram, and snippet.