@noesis-brain/mcp-server 2.0.1 → 2.1.0

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/templates/claude-md-block.md

@@ -13,10 +13,14 @@
 - 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.
+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.