@noesis-brain/mcp-server 2.0.1 → 2.1.1

package/skill-templates/noesis-capture.md

@@ -0,0 +1,166 @@
+---
+description: Continuously capture one or more Claude Code sessions into Noesis notes — a deterministic Node watcher tails each transcript, renders readable Markdown, and pushes it to the Noesis cloud on every change (zero tokens, no model loop). Use when the user says 'capture', 'start capture', 'capture session', 'monitor session', 'mirror session to noesis', or '/noesis-capture <id-or-name>'. Sub-commands - stop [<id|name>], status, sync.
+argument-hint: "<session-id | name> | stop [<id|name>] | status | sync"
+---
+
+# /noesis-capture — Live Session Capture into Noesis (multi-session)
+
+You are executing the `/noesis-capture` slash command. It runs in a **second** Claude session (the **controller** session) and mirrors one or more **other** sessions into Noesis notes that update in place — both locally and in the cloud — as those sessions progress.
+
+**Architecture (fully deterministic — no model in the periodic path).** A bundled Node watcher does *everything that must run continuously*: it tails the source transcript, renders JSONL→Markdown to the local `.md`, **and pushes that note to the Noesis cloud directly** (`POST /api/mcp/notes/upsert`) on every change. One watcher process runs per captured session. Both the local render and the cloud push cost **zero tokens** and need **no Claude session in the loop**. This controller session only does what genuinely needs a Claude session: resolve targets, start/stop watchers, and report status.
+
+The watcher path is `{{NOESIS_CAPTURE_WATCHER_PATH}}` — invoke it with `node "<that path>"`.
+
+> There is **no** model-driven sync loop and **no** wake-up/reschedule here. That earlier design was unreliable — a single missed/no-op model turn, an `Esc`, or a non-resumed restart killed cloud sync permanently while the local file kept updating. The watcher now owns the cloud push, so cloud freshness is as reliable as the local render. **Never** reintroduce a model-driven periodic sync.
+
+The watcher writes each capture note to `<outPath>` — an absolute path the watcher itself chooses: a `captures/` folder under a registered Noesis root (it prefers the standard `~/Noesis` root, already home-expanded), so the cloud push always finds a matching root. You get the exact `outPath` from the watcher's `--resolve-only` output (Step 1) — **do not compute it yourself from `list_roots`** (stored root paths can be in `~`/`%USERPROFILE%` form and must not be passed to the watcher literally). Alongside the note the watcher writes a per-session status sidecar `<dir>/.<session-id>.cloud.json` (last push time / action / error — read by the `status` sub-command for cloud freshness). All controller state lives in a single shared file **`~/.claude/noesis-capture-state.json`** (v3 schema below), keyed by session id so multiple captures coexist. If the optional `SessionEnd` hook is installed (via `noesis-mcp setup --with-capture`), it marks every capture stopped and kills lingering watchers when this controller session ends; otherwise stop them yourself with `/noesis-capture stop`.
+
+**Cloud auth (handled by the watcher).** The watcher reads `NOESIS_API_TOKEN` / `NOESIS_API_URL` from its environment, else from `~/.claude.json → mcpServers.noesis.env`. The token is never logged or placed on a command line. If no token is found, the watcher runs **local-only** (renders but does not push); in that case the cloud copy is maintained only by the skill's `mcp__noesis__sync_notes` calls at Start / Stop / `sync`.
+
+## Arguments
+
+The raw argument string is: `$ARGUMENTS`
+
+Forms:
+- `<session-id>` (a UUID) or `<name>` (a substring of the session's ai-title / summary), optionally followed by `--max-life <dur>` (or a trailing bare `<dur>`) — **start** capturing that session (adds to any already running). `--max-life` sets an optional **hard lifetime cap**: the capture auto-stops (with a final sync) after `<dur>` of wall-clock time.
+- `stop [<id|name>]` — stop **all** captures, or just the one matching `<id|name>`. Final cloud sync each stopped note.
+- `status` — report every capture currently tracked (incl. cloud freshness).
+- `sync` — one-shot: force an immediate cloud sync of every capture via `mcp__noesis__sync_notes`. **Not a loop** — the watcher already keeps the cloud current; use this only to force/confirm a push right now.
+- empty — treat as `status`.
+
+**Duration `<dur>`** (for `--max-life`): one or both of `<N>h` and `<N>m` — e.g. `2h`, `90m`, `1h30m`. Convert to milliseconds as `(hours*60 + minutes) * 60000`; treat as **no cap** if it parses to 0 or is absent. Default: no cap (monitor until `/noesis-capture stop`). The cap is **per-capture**.
+
+## State schema (`~/.claude/noesis-capture-state.json`, version 3)
+
+```json
+{
+  "version": 3,
+  "controllerSessionId": "<this-capture-session-id (SELF)>",
+  "sessions": {
+    "<session-id>": {
+      "title": "<display-title> — Capture",
+      "outPath": "<absolute path returned by --resolve-only>",
+      "transcriptPath": "<path-to-source-.jsonl>",
+      "bgTaskId": "<background-task-id>",
+      "watching": true,
+      "startedAt": 0,
+      "maxLifetimeMs": null,
+      "lastChangeTime": 0
+    }
+  }
+}
+```
+
+- **Global:** `version`, `controllerSessionId` (this controller's own id / `SELF` — lets the optional `SessionEnd` hook auto-dispose captures when the controller closes).
+- **Per-session** (under `sessions[<id>]`): `title`, `outPath`, `transcriptPath`, `bgTaskId`, `watching`, `startedAt` (unix-ms the capture began — the lifetime-cap clock), `maxLifetimeMs` (hard cap in ms, or `null`), `lastChangeTime` (unix-ms). The session id is the map key — do not duplicate it inside the object.
+- All timestamps are **unix milliseconds**. Cloud freshness is **not** stored here — it lives in each watcher's `.<id>.cloud.json` sidecar next to the note.
+
+### Read + migrate (do this at the top of every sub-command that touches state)
+
+Read `~/.claude/noesis-capture-state.json` with the Read tool and normalize **in memory** to v3:
+- Missing / unparseable → start a fresh v3 object: `{version:3, controllerSessionId:null, sessions:{}}`.
+- Has a `sessions` object (v2 or v3) → keep `sessions`; **drop** any obsolete model-loop / cost-guard globals if present (`baseDelaySeconds`, `maxDelaySeconds`, `idleLevel`, `lastSyncTime`, `nextSyncTime`, `model`, `effort`, `costGuardOk`). For each session, default `startedAt` to its `lastChangeTime` (or `<now-ms>` if unset) and `maxLifetimeMs` to `null` when absent. Set `version:3`.
+- Has a top-level `sessionId` (the **old singleton** format) → fold it into `sessions[sessionId]`, drop legacy globals, set `version:3`, `controllerSessionId:null` (recorded on the next Start/Sync).
+
+Only **Start**, **Sync**, and **Stop** write the file back (Write tool, whole object). **Status** never writes.
+
+## Instructions
+
+### Step 0 — Discover THIS session id (for the self-monitor guard)
+
+Ask the watcher for the current session's id so it can refuse to capture itself:
+
+```bash
+node "{{NOESIS_CAPTURE_WATCHER_PATH}}" --print-self
+```
+
+It prints `SELF=<id>` (possibly empty if it can't resolve — then omit `--self`). Keep `SELF` for the `--self` flag.
+
+The watcher picks the output location itself (a `captures/` folder under a registered Noesis root, home-expanded), so you do **not** resolve roots or build paths here — you get the exact `outPath` back from `--resolve-only` in the Start step.
+
+### Step 1 — Route on the sub-command
+
+- `stop` (with or without an argument) -> go to **Stop** (pass the remainder of the argument).
+- `status` or empty -> go to **Status**.
+- `sync`   -> go to **Sync (one-shot)**.
+- anything else -> treat the whole argument as a session id/name and go to **Start**.
+
+### Start — `/noesis-capture <id-or-name>`
+
+1. **Parse the lifetime cap, then resolve.** First strip an optional lifetime cap from `$ARGUMENTS`: a `--max-life <dur>` / `--max-life=<dur>` flag, or a trailing standalone `<dur>` token (see **Duration**). Convert it to `maxLifetimeMs` (or `null`). The remaining text is `<target>`. Then resolve `<target>` with the watcher's read-only mode and respect the self-guard:
+
+   ```bash
+   node "{{NOESIS_CAPTURE_WATCHER_PATH}}" --resolve-only --self "<SELF>" --session "<target>"
+   ```
+
+   - Non-zero exit / `ERROR: could not resolve` -> tell the user no session matched and stop. Suggest the session id (UUID) or a more specific name fragment.
+   - Exit code 3 (`REFUSED: self-monitor guard`) -> they pointed capture at the current session; refuse and stop.
+   - Success -> parse the JSON (`sessionId`, `transcriptPath`, `title`, `outPath`, `candidates`). Use the returned **`outPath` as-is** (an absolute path under a registered Noesis root) for state, sync, and sidecar — do not recompute it. If `candidates` has more than one entry, briefly say which match was chosen (most recently modified) and list the alternatives.
+
+2. **Read + migrate state.** Compute `activeCount` = number of sessions with `watching === true` **before** this start (informational only — there is no shared loop to start).
+
+3. **Dedup / restart guard** on `resolved.sessionId`:
+   - Already present AND `watching === true` -> tell the user it's already being captured (its `title` + `outPath`) and offer a restart. On restart: `TaskStop` the old `bgTaskId` (tolerate failure), then continue and overwrite just that one entry. Never spawn a second watcher for the same id.
+   - Present AND `watching === false` (previously stopped/paused) -> treat as restart: reuse the entry with a fresh watcher.
+
+4. **Decide `startedAt`, then start the watcher in the background** (the long-running tail + render + cloud push).
+   - **`startedAt`:** if this is a brand-new entry, or `maxLifetimeMs` was supplied on this call, set `startedAt = <now-ms>` (fresh lifetime window). On a restart with no new duration, keep the existing `startedAt` and `maxLifetimeMs`.
+   - Launch the watcher. Append `--max-life-ms <remaining>` **only** when `maxLifetimeMs` is set, where `remaining = max(1000, maxLifetimeMs - (<now-ms> - startedAt))` — the watcher self-exits (after a final cloud push) when its own lifetime elapses:
+
+   ```bash
+   node "{{NOESIS_CAPTURE_WATCHER_PATH}}" --session "<sessionId>" --self "<SELF>" --out "<outPath>" [--max-life-ms <remaining>]
+   ```
+
+   Run with `run_in_background: true`. Record the returned background **task id** as `bgTaskId`. The watcher self-loads the Noesis token and begins pushing to the cloud on its first render — there is **nothing to schedule**.
+
+5. **Upsert the session entry** (never overwrite siblings):
+   `sessions[sessionId] = { title, outPath, transcriptPath, bgTaskId, watching: true, startedAt, maxLifetimeMs, lastChangeTime: <now-ms> }`.
+   Ensure global `version:3` and `controllerSessionId = <SELF>` are present. Write state once.
+
+6. **Immediate confirmation sync.** Give the watcher ~2 s to write the first render, then call `mcp__noesis__sync_notes` with `files: ["<outPath>"]` for an instant cloud copy; report `create`/`push`/`skip`. (This is a one-shot confirmation only — thereafter the watcher keeps the cloud current automatically, and it also covers the case where the watcher is running local-only.)
+
+7. **Tell the user:** what is being captured (`title` + `sessionId`), the note path, and that **both** the local note and the **cloud** copy now update in real time via the watcher (deterministic, no token cost, no model loop) until `/noesis-capture stop`. If the watcher's sidecar reports `cloudEnabled:false` (no token), say so and note that the cloud copy will only refresh on `/noesis-capture sync` / `stop`.
+
+### Sync (one-shot) — `/noesis-capture sync`
+
+This is **not** a loop and never reschedules anything. Use it to force/confirm a cloud push right now.
+
+1. **Read + migrate state.** If `sessions` is empty or no session has `watching === true` -> say nothing is being captured and stop.
+2. For each `sessions[id]` with `watching === true`: call `mcp__noesis__sync_notes` with `files: ["<outPath>"]`. `skip` (unchanged — the watcher already pushed it) is normal and expected. On `conflict`: report it and tell the user to inspect the note (these notes are auto-generated, so a conflict means the cloud copy was hand-edited); do not auto-resolve.
+3. Keep output to one short line, e.g. "Captures: 2 synced · 1 already current".
+
+### Status — `/noesis-capture status`
+
+Read + migrate state and report:
+- Global: the controller session id (`controllerSessionId`) and the active count.
+- Per session in `sessions`: `title`, short id (`id[:8]`), `watching` (true/false), **local** last-updated (mtime of `outPath`), **cloud** freshness — read the sidecar `<dirname(outPath)>/.<id>.cloud.json` and report `lastAction` + age of `lastPushTime`, or `lastError` if set, or `local-only` when `cloudEnabled:false` (missing sidecar → "cloud: starting…"), the lifetime cap (from `maxLifetimeMs`/`startedAt` → e.g. "2h cap · 1h12m left", or "no cap"), and `outPath`.
+
+If there is no state file or `sessions` is empty, say nothing is being captured.
+
+### Stop — `/noesis-capture stop [<id-or-name>]`
+
+Read + migrate state first.
+
+- **No argument** -> stop **all** `watching:true` sessions. For each: `TaskStop` its `bgTaskId` (if stale/unknown, warn that the node watcher may still be running and that closing it or ending the `noesis-capture-watcher.mjs` process will stop it), then a **final** `mcp__noesis__sync_notes` with its `outPath`, then set `watching:false`. List every stopped session (title + outPath).
+- **With an argument** -> match it against `sessions`: exact id key first; else case-insensitive substring on `title` (if ambiguous, list the matches and ask which). Stop **only that one** (TaskStop + final sync + `watching:false`); **leave siblings running**. Unknown arg -> say it isn't being captured and list the current sessions.
+
+Write state once at the end. Confirm to the user with the final note path(s).
+
+## Constraints
+
+- **Never** sync this skill file or the watcher to Noesis — only the generated capture `.md` notes (the `outPath` files).
+- The watcher owns the **periodic** cloud push; the controller **never** runs a sync loop or reschedule. The only cloud pushes the controller issues are the one-shot `mcp__noesis__sync_notes` at Start (confirmation), `sync`, and Stop (final).
+- Push to Noesis **only** via the watcher or `mcp__noesis__sync_notes` (never `cp` into a folder).
+- Never edit a watcher's output `.md` by hand — it is fully regenerated on every change.
+- Multiple sessions coexist under one state file; each has its own independent watcher. Start adds; it never overwrites a sibling.
+- Capture costs **no tokens while monitoring** (the watcher is a plain Node process), so there is no cost guard, no idle auto-pause, and no model/effort prompt — capture any session on any model.
+
+## Examples
+
+- `/noesis-capture 1b1bcf99-f520-4bf5-9575-247d7574e8f5` — capture that session by id (adds to any already running)
+- `/noesis-capture Implement auth redesign` — capture by name (ai-title substring)
+- `/noesis-capture 1b1bcf99-… --max-life 2h` — capture with a hard 2-hour lifetime cap; `--max-life 90m` and a trailing `1h30m` also work
+- `/noesis-capture status` — list every capture, with local + cloud freshness
+- `/noesis-capture sync` — force an immediate cloud push of every capture (normally unnecessary)
+- `/noesis-capture stop 1b1bcf99-…` — stop just that one capture, leave the rest running
+- `/noesis-capture stop` — stop all captures and do a final cloud sync of each

package/skill-templates/noesis-create-study-note.md

@@ -0,0 +1,149 @@
+---
+description: "Research a URL or topic from the web and create a polished Noesis study note with structural diagrams, then refine its metadata and sync to the cloud. Use when the user says 'create study note', 'study note from <url>', 'make a note about', 'note from this video/article/URL', or 'summarize this link into a note'."
+---
+
+Research a source from the web and turn it into a well-structured Noesis study note: fetch and corroborate the material, author accurate prose with proper ASCII diagrams, then fill metadata, link it into your knowledge base, and sync to the cloud. Works from a URL (video, article, docs) or a plain topic.
+
+This skill is self-contained — it embeds the note-structure and diagram rules below, so it does not depend on any local reference files or external scripts.
+
+## Arguments
+
+$ARGUMENTS
+
+Accepted forms:
+
+- `<url>` — research this page / video / article and build a note from it. Extra URLs after the first are treated as additional sources.
+- `<topic>` or `"quoted title"` — research the topic from scratch (no URL).
+- `--path <file.md>` — explicit output path. Otherwise a path is derived under a registered Noesis root.
+- `--type reference|procedure|investigation|architecture|strategy` — force the content type. Otherwise it is classified.
+- `--catalog <name>` — force a catalog assignment.
+- `--no-sync` — author locally but do not push to the Noesis cloud.
+- `--no-refine` — skip the `/noesis-refine-note` hand-off (just author, enrich, and sync).
+
+## Workflow
+
+### Step 1 — Parse
+
+Detect URL vs topic; extract the flags above and remove them from the subject string. If the subject is empty, ask the user what URL or topic to create a note about, then stop until answered.
+
+### Step 2 — Research (never write from memory)
+
+1. **Fetch the primary URL** with `WebFetch`, asking for title, author/date, and a full content summary.
+   - **YouTube / JS-page caveat:** a `youtube.com/watch` page (or any JS-heavy page) fetched via `WebFetch` usually returns only nav/footer chrome — no transcript or description. When the result is thin, do not give up: use the title as a search seed and rely on the next two sub-steps.
+2. **Web-search** with 2–4 `WebSearch` queries (exact title, product/feature name, "official docs", "announcement"/"release", a how-it-works phrasing) to find the authoritative primary sources and corroborate facts.
+3. **Fetch the top 2–3 primary sources** (official docs, the vendor's own announcement, a reputable deep-dive) with `WebFetch`. Prefer primary over aggregators. Skip any source that returns 403/blocked — do not retry endlessly.
+4. **Build a fact sheet**: the 1-line "what it is", the problem it solves, key mechanics/constraints/requirements, dates/versions, and the **Sources** list (every URL you actually used). Resolve contradictions across sources before writing; if a genuine disagreement cannot be resolved, state it in the note rather than picking silently.
+
+### Step 3 — Plan
+
+- **Classify** the content type (default `reference` for a feature/concept/talk explainer; `procedure` for a how-to; `investigation` for a bug study; `architecture` for system design; `strategy` for a decision).
+- **Derive identity**: a descriptive title; a 1–2 sentence description (anchor a date/version if time-bound); 6–12 keywords; 3–5 aliases (alternative names / query phrasings).
+- **Derive the path** (unless `--path`): `lowercase-hyphenated-title.md`, punctuation stripped, placed in a registered Noesis root. Call `mcp__noesis__list_roots` and pick a writable root (prefer one ending in `/.noesis` or the `~/Noesis` cloud root). Use today's date (absolute `YYYY-MM-DD`) for `date`/`updated`.
+- **Plan sections** from the content-type table (see rules below); always lead with an Overview. **Plan diagrams** per the trigger checklist and the density tier.
+
+### Step 4 — Author the note (one pass)
+
+Compose the **entire** note — frontmatter + H1 + TOC + all prose + all diagrams — and `Write` it in a single pass.
+
+- **Never** retro-fit diagrams by bulk-replacing fenced blocks in an already-written file: ` ```text ` / ` ```markdown ` fences mis-pair against plain ` ``` ` fences and corrupt the document. Author the whole file at once, or insert via anchored string replacement on a unique heading.
+- Author framed / nested / multi-column / sequence diagrams with the **coordinate-grid generator** (below) so columns are guaranteed to align. Trees (`├── └──`) and tiny 2–3 box flows may be authored inline.
+
+### Step 5 — Verify diagrams
+
+Re-read every fenced diagram and confirm: ASCII-only inside the fence, right walls aligned, no Unicode arrows (`→ ← ↑ ↓`), no `│` glitches, no trailing spaces. Fix drift by **regenerating** that diagram with the grid script — not by hand-patching columns. If a diagram will not converge after a few tries, surface it rather than claiming success.
+
+### Step 6 — Refine metadata + sync (delegate)
+
+Unless `--no-refine`, invoke the **`/noesis-refine-note`** skill on the new file by passing just its path (this runs it in single-note mode):
+
+```
+/noesis-refine-note <NOTE_PATH>
+```
+
+That fills missing metadata, refreshes the AI quality/importance scores, and pushes the note to the Noesis cloud. Do not duplicate that logic here.
+
+If `--no-refine`: push the note yourself with `mcp__noesis__sync_notes(files: ["<NOTE_PATH>"])`, unless `--no-sync`.
+
+### Step 7 — Link it into the knowledge base (this skill)
+
+`/noesis-refine-note` does not assign catalogs or create relations, so do those here:
+
+1. Get the note id and current cloud metadata: `mcp__noesis__get_note(path: "<NOTE_PATH>")`.
+2. **Persist aliases/keywords** (frontmatter-only additions do not stick in the cloud fields): `mcp__noesis__enhance_note_metadata(note_id, apply_suggestions: { aliases: [...], keywords: [...] })` with your authored values.
+3. **Catalogs**: `mcp__noesis__list_catalogs`, then assign up to 2 confident best-fit catalogs via `mcp__noesis__set_note_catalogs` (honor `--catalog`). Skip if nothing fits.
+4. **Relations**: `mcp__noesis__find_similar_notes(note_id)` (optionally also `mcp__noesis__search_semantic`); create 2–5 genuinely meaningful bidirectional links via `mcp__noesis__update_relations`. Reject weak / generic-vocabulary matches — the cap is a ceiling, not a target.
+
+### Step 8 — Report
+
+```
+=== STUDY NOTE CREATED ===
+Path:      <NOTE_PATH>
+Type:      <content type>
+Sections:  <N primary> | TOC links verified
+Diagrams:  <N> (<types>) — alignment verified
+Sources:   <count> (primary: <url>)
+Catalogs:  <list>   Relations: <count>
+Synced:    <yes | skipped (--no-sync)>
+```
+
+Remind the user to **check the diagram rendering** in their markdown viewer (box-drawing alignment) before relying on the note.
+
+---
+
+## Note structure rules (inlined)
+
+- **Frontmatter** (YAML between `---`): `title`, `description`, `keywords` (list), `aliases` (list), `date`, `updated` (`YYYY-MM-DD`), `status` (`active`/`draft`/`completed`). Only add fields with real values.
+- **Headings**: exactly one H1 = the title. Major sections are H2. Use **plain `##`** for primary sections (Noesis builds its sidebar outline from them). Reserve collapsible `<details><summary>…</summary>` for noise (raw logs, long tables, references, appendix); put an `id="<slug>"` on a `<summary>` only if you link to it from the TOC.
+- **Table of Contents**: if there are 4+ primary sections, add a standalone `## Table of Contents` immediately below the H1, listing each primary section as `- [Title](#slug)`. Compute slugs GitHub-style: lowercase, strip punctuation (keep `-`/`_`/space), spaces → `-`, collapse repeats. Verify every link resolves.
+- **Content-type sections**: reference → Overview, (Problem It Solves), What It Is, How It Works, core mechanics, Constraints, Availability; procedure → Overview, Prerequisites, Steps, Verification; investigation → Overview, Symptoms, Root Cause, Fix, Verification; architecture → Overview, Components, Data Flow, Key Decisions; strategy → Overview, Context, Recommendation, Action Plan, Risks. Only include sections you have content for.
+- **No emojis** in headings or `<summary>` tags.
+- **Do not** write "Related Notes" / "Related Codebase" sections into the file — those are database metadata (Step 7).
+- End with a `<details><summary>Sources</summary>…</summary>` appendix listing the URLs used.
+
+## Diagram rules (inlined)
+
+- **ASCII is the default** — author diagrams in an untagged fenced code block. Reserve Mermaid (```` ```mermaid ````) for small (≤10 nodes), balanced decision/hierarchy graphs.
+- **Density** scales with the note: 1–2 diagrams for a short note (≤4 sections), 3–5 for a moderate note (5–7), **6–10 for a complex reference/architecture note** (8+ sections).
+- **Quality bar**: ≥5 elements per diagram (a 3-box A→B→C is a sentence, not a diagram); when a note has 4+ diagrams they must span **≥3 distinct types** from {workflow, component, sequence, state, tree, data-flow, comparison}; every branching diagram labels its secondary/error/HALT path; sequence diagrams show **response** messages, not just requests; component/data-flow diagrams show at least one **labeled direction** arrow.
+- **ASCII-only inside fences**: use box-drawing `─ │ ┌ ┐ └ ┘ ┬ ┴ ├ ┤ ┼` for frames and plain-ASCII markers `> < v ^` for arrows. **Never** use Unicode arrows `→ ← ↑ ↓` inside a fence — editors using Consolas/Courier fall back to a CJK font for them and render at 2 cells wide, breaking column alignment. (Unicode arrows are fine in prose, headings, and tables.)
+- **Type → shape**: workflow/procedure → boxes + branch points; architecture/services → nested boxes with data-flow arrows; request/response → sequence (vertical lifelines, horizontal labeled arrows); lifecycle/status → state boxes + labeled transitions; hierarchy → `├── └──` tree; pipeline → boxes with typed arrows.
+
+## Diagram grid generator (alignment technique)
+
+Hand-drawn box/framed/sequence ASCII almost always drifts (misaligned right walls, trailing spaces, skewed nested boxes). Generate those diagrams with a small Python coordinate grid that places every wall at a fixed column. Write this to a throwaway script, build each diagram, have the script assemble the whole note (interpolating the rendered diagrams into the prose), then run it to write the file:
+
+```python
+class Grid:
+    def __init__(self, w, h): self.g = [[" "]*w for _ in range(h)]
+    def put(self, r, c, s):
+        for i, ch in enumerate(s): self.g[r][c+i] = ch
+    def box(self, r, c, w, h, lines):
+        self.put(r, c, "┌"+"─"*(w-2)+"┐"); self.put(r+h-1, c, "└"+"─"*(w-2)+"┘")
+        for i in range(1, h-1): self.put(r+i, c, "│"); self.put(r+i, c+w-1, "│")
+        for i, ln in enumerate(lines): self.put(r+1+i, c+2, ln)
+    def render(self):
+        rows = ["".join(row).rstrip() for row in self.g]
+        while rows and rows[-1] == "": rows.pop()
+        return "\n".join(rows)
+```
+
+Guidance:
+
+- Place boxes at fixed `(row, col)`; connect them with arrows in the gutters between boxes — keep each box's text shorter than its inner width so it never overwrites the right wall.
+- Write the file with `encoding="utf-8", newline="\n"`. Do **not** `print()` box-drawing to a Windows console (cp1252 will crash) — write to the file and read it back to verify.
+- Delete the throwaway script when done if it sits inside a Noesis-watched folder.
+
+## Constraints
+
+- **Accuracy over volume.** Ground every claim in a fetched source; cite what you used; resolve contradictions before writing.
+- **One-pass authoring.** Never bulk-replace fenced blocks in an existing file — it desyncs on `text`/`markdown` fences.
+- **Self-contained.** Do not reference machine-specific files (e.g. `~/.claude/...`) or external scripts; the rules and the grid technique above are everything you need.
+- **Stay inside a registered Noesis root** so `mcp__noesis__sync_notes` works. Confirm with `mcp__noesis__list_roots`.
+- **Delegate metadata/scores/sync** to `/noesis-refine-note`; this skill owns research, authoring, diagrams, catalogs, and relations.
+
+## Examples
+
+- `/noesis-create-study-note https://www.youtube.com/watch?v=XXXX` — research a video and build a note.
+- `/noesis-create-study-note "Event sourcing vs CRUD" --type architecture` — research a topic from scratch.
+- `/noesis-create-study-note https://example.com/post --catalog Work` — force a catalog.
+- `/noesis-create-study-note https://example.com/post --no-refine --no-sync` — author locally only.

package/skill-templates/noesis-find-related.md

@@ -0,0 +1,89 @@
+---
+description: Discover related Noesis notes for either a NOTE (its formal relations, similar notes, and relation graph) or a CODEBASE (notes matching its tech stack, domain, and concepts). Read-only. Use when the user says 'find related notes', 'related docs', 'discover relations', 'what relates to this', 'what notes relate to this project', or 'find notes for this codebase'.
+argument-hint: "[N results] <note path | note ID | codebase directory | search query>"
+---
+
+# /noesis-find-related — Discover Related Content in Noesis
+
+You are executing the `/noesis-find-related` slash command. It discovers related content in the Noesis knowledge base from one of two starting points:
+
+- **Note mode** — given a note (ID, `.md` path, filename, or search query), find its formal relations, semantically similar notes, keyword/semantic matches, reverse codebase links, and relation-graph neighbours.
+- **Codebase mode** — given a codebase directory, profile its tech stack / domain / concepts and search Noesis for notes related to it.
+
+This is a **read-only** skill — it never writes, edits, syncs, or modifies anything.
+
+## Step 0 — Route on the argument
+
+The raw arguments string is: `$ARGUMENTS`
+
+Parse an optional leading integer **N** (1–50, how many results to display; default 10). Then classify the remaining `<target>`:
+
+- **Numeric only** → a note **ID** → Note mode.
+- **Path ending in `.md`** (has `/` or `\`) → a note **path** → Note mode.
+- **`.md` filename** (no path separator) → Note mode (find it via `mcp__noesis__list_notes` matching the filename, or `mcp__noesis__search_notes` on the name — resolve by the Noesis DB, not the filesystem).
+- **Path without `.md`** (a directory, or `.`) → a **codebase directory** → Codebase mode.
+- **Anything else** → a **search query** → Note mode (resolve to a note first).
+- **Empty** → Codebase mode with the current working directory.
+
+Clamp N to [1, 50], then go to the matching part below.
+
+---
+
+## Part A — Codebase mode (codebase → related notes)
+
+### A1. Analyze the codebase
+Read key identity files (skip any that are absent), in parallel:
+- `Glob` for `{README*,CLAUDE.md,package.json,Cargo.toml,go.mod,pyproject.toml,requirements.txt,*.csproj,*.sln,pom.xml,build.gradle*,docker-compose.yml,Dockerfile}` and `Read` the matches (first ~100 lines of large files).
+- `git -C <dir> log --oneline -20` for recent focus, and `ls` for top-level layout.
+- If `src/` `lib/` `app/` `cmd/` exist, `ls` them; read the main entry point (≤ 2–3 source files total).
+
+Synthesize a profile: **PROJECT_NAME**, **PURPOSE** (one sentence), **TECH_STACK**, **DOMAIN**, **KEY_CONCEPTS** (5–10 terms), **RECENT_FOCUS**. Display it. If essentially nothing is found, say so and `AskUserQuestion` for a description or a different path (use a description directly as queries).
+
+### A2. Generate 6 diverse queries
+Two each across **tech stack**, **domain**, and **concepts** — each query targeting a genuinely different facet (avoid 6 variations of one search).
+
+### A3. Search in parallel (single batch)
+For each of the 6 queries call **both** `mcp__noesis__search_notes` (`limit: N`) and `mcp__noesis__search_semantic` (`limit: min(N,20)`). In the same batch, call `mcp__noesis__search_by_related_code` with the **last folder segment** of the codebase path (never include slashes/backslashes — the lookup is SQL `ILIKE` where `\` escapes; use one distinctive folder name). These reverse-lookup hits are high-confidence explicit links.
+
+Error handling: if all searches fail, say Noesis is unavailable and stop. If only `search_semantic` fails (common without a Gemini key), continue keyword-only and note it.
+
+### A4. Deduplicate, rank, present
+Group by note ID; per note track hit_count, best_score, categories hit (tech/domain/concept/codebase-link), and search types (keyword/semantic). Rank by a composite that rewards notes found by **many diverse** queries and by the reverse codebase lookup — not just a single high BM25 score. Show the top N as a ranked table (score, title, path, "found via"), then a one-line "why relevant" per result tying it to the profile (from title/path/snippet — do **not** `get_note` each result). Close with brief stats (unique notes, queries with 0 results, semantic available/unavailable).
+
+If nothing is found, show the profile and suggest creating notes as you work, or retrying with a different path.
+
+---
+
+## Part B — Note mode (note → related content)
+
+### B1. Resolve the target note
+- **ID** → `mcp__noesis__get_note(id)`. **Path** → `mcp__noesis__get_note(path)`. **Query** → `mcp__noesis__search_notes(query, limit:5)`, pick via `AskUserQuestion` if several, then `get_note`.
+- If it fails, show the error and stop.
+
+From the response, store: `NOTE_ID`, `NOTE_PATH`, `NOTE_TITLE`, `NOTE_DESCRIPTION`, `NOTE_KEYWORDS`, `NOTE_ALIASES`, `NOTE_RELATIONS` (typed links w/ target_id + context), `NOTE_RELATED_CODEBASES` (resolved objects w/ `path`, `label`), `NOTE_IMPORTANCE`, `NOTE_QUALITY`. Display `Discovering relations for: <title> (ID: <id>)`.
+
+### B2. Discover (single parallel batch)
+- **Relation targets:** for each unique `target_id` in `NOTE_RELATIONS`, `get_note` (≤ 10 parallel) to resolve titles.
+- **Similar:** `mcp__noesis__find_similar_notes(note_id, limit:15)`. Record status `ok` / `no_embedding` / `no_api_key`.
+- **Search:** `search_semantic(query: title + first 50 chars of description, limit:10)` and `search_notes(query: keywords or title, limit:10)`. Note if semantic is unavailable.
+- **Reverse codebase:** for each `NOTE_RELATED_CODEBASES` path (≤ 5), `search_by_related_code` with a **single distinctive folder segment** (never slashes/backslashes; dedupe fragments).
+- **Relation graph:** `mcp__noesis__get_relation_graph(note_id, depth:2)` for 2-hop neighbours.
+
+### B3. Consolidate and present
+Merge all discovered notes (exclude the target itself by ID). Per note track discovery_sources (e.g. "formal relation", "similar 82%", "keyword", "semantic", "reverse codebase", "graph depth 2"), best_score, and whether it's a formal relation (+ type). Present:
+- **Formal Relations** — type · target title (ID) · context.
+- **Related Codebase** — the linked paths.
+- **Discovered Similar Notes** — notes not already formally related, sorted by best_score (score · title (ID) · discovery · path).
+- **Discovery stats** — counts per method; embedding/semantic availability.
+- **Next actions** — e.g. `/noesis-refine-note <path>` to enrich metadata and create formal relations; `update_relations` to formally link promising matches; `generate_embeddings` if `no_embedding`.
+
+If nothing is found, note the note may be new/unique, embeddings may be missing (`generate_embeddings`), or metadata may be thin (`/noesis-refine-note`).
+
+---
+
+## Implementation notes
+- **Read-only.** Never write, edit, sync, or modify — this skill only reads and searches.
+- **Parallelism matters.** Batch the codebase file reads (A1) and the discovery calls (A3 / B2) into single parallel batches.
+- **Don't `get_note` every result.** Search/similarity tools return enough metadata (title, path, snippet, score) for the tables; only `get_note` to resolve formal-relation target titles.
+- **Composite ranking over raw scores.** A note surfaced by many diverse queries (or an explicit codebase link) is more relevant than one with a slightly higher single-query score.
+- **Graceful degradation.** Every discovery method is optional — proceed with whatever succeeds (down to keyword-only when Gemini is unavailable).

package/skill-templates/noesis-investigate.md

@@ -0,0 +1,90 @@
+---
+description: Cross-domain context enrichment — given a prompt that mentions codebases AND Noesis notes, resolve the notes and enrich context by querying Noesis (relations, similar notes, codebase links, semantic/keyword search), then produce a consolidated context brief so you can proceed with full awareness. Read-only. Use when the user says 'investigate', 'gather context', 'enrich context', or a prompt references both codebases and notes.
+argument-hint: "<investigation prompt mentioning codebases, notes, aliases, and intent>"
+---
+
+# /noesis-investigate — Cross-Domain Context Enrichment
+
+You are executing the `/noesis-investigate` slash command. It takes a natural-language prompt that mentions codebases, Noesis notes, aliases, and/or intent, then enriches it by querying Noesis MCP tools to discover related knowledge. The result is a compiled **context brief** followed by the original prompt re-stated with full awareness, so you can proceed with the actual work.
+
+This is a **read-only** skill — it enriches context and never writes, edits, syncs, or modifies anything.
+
+## Step 1 — Parse the prompt
+
+The raw arguments string is: `$ARGUMENTS`. If empty, check the conversation for a recent investigation request; else `AskUserQuestion` for one. Store it as `INVESTIGATION_PROMPT`.
+
+Extract four categories using natural-language understanding (not rigid regex):
+- **Codebases** — directory paths (contain `/` or `\`, do NOT end in `.md`). Store `{full_path, project_name}` where `project_name` is the last folder segment.
+- **Notes** — paths ending in `.md`, bare `.md` filenames, or references like "the note about X". Store `{input, type}` with type `path` | `filename` | `query`.
+- **Aliases** — informal names ("we call it X", "aka X", quoted labels). Store `{term, alias, source}`.
+- **Intent** — a one-sentence summary of the goal (review / understand / compare / audit …).
+
+If no codebases AND no notes are found, `AskUserQuestion` for paths, then re-parse. Display a short scope summary (intent, codebases, notes, aliases).
+
+## Step 2 — Resolve notes to Noesis IDs (parallel)
+
+- **`path`** → `mcp__noesis__get_note(path)`.
+- **`filename`** → find it via `mcp__noesis__list_notes` matching the filename (or `mcp__noesis__search_notes` on the name), then `get_note` by its id/path — resolve by the Noesis DB, not the filesystem.
+- **`query`** → `mcp__noesis__search_notes(query, limit:3)`; use the top hit, falling back to `search_semantic`.
+
+For each resolved note store `note_id`, `note_path`, `note_title`, `note_description`, `note_keywords`, `note_aliases`, `note_relations` (typed links w/ target_id), `note_related_codebases` (resolved objects — read `entry.path`). Skip (don't abort on) individual resolution failures. If ALL notes fail and no codebases were given, stop with an error.
+
+Merge aliases from the prompt + each note's `note_aliases`. Scan `note_related_codebases` for codebase paths not already listed and add them as `DISCOVERED_CODEBASES`.
+
+## Step 3 — Enrichment (single maximum-parallel batch)
+
+Dedupe first: collapse repeated note IDs and repeated codebase fragments so each `get_relation_graph` / `find_similar_notes` / `search_by_related_code` runs once. Then issue ALL of the following in one parallel batch:
+
+- **Per resolved note:** `mcp__noesis__get_relation_graph(note_id, depth:2)` and `mcp__noesis__find_similar_notes(note_id, limit:10)`.
+- **Per codebase** (input + discovered): `mcp__noesis__search_by_related_code(path: <project_name>, limit:15)`. **Path rule:** pass only a single distinctive folder segment — never slashes/backslashes (the lookup is SQL `ILIKE` where `\` escapes). Dedupe fragments.
+- **Intent:** `mcp__noesis__search_semantic(query: INTENT, limit:15)` and `mcp__noesis__search_notes(query: INTENT key terms + alias values, limit:15)`.
+- **Aliases** not already covered by the intent search: `mcp__noesis__search_notes(query: <alias>, limit:5)`.
+
+Error handling: any individual call may fail (no embedding, no Gemini key, empty codebase link) — continue with the rest; record `SEMANTIC_AVAILABLE = false` if semantic search fails. Never abort for a single failure.
+
+## Step 4 — Deduplicate and score
+
+Collect results with a `discovery_source` tag (`relation-graph:<note>`, `similar:<note>`, `codebase-link:<project>`, `intent-semantic`, `intent-keyword`, `alias:<value>`), a `score`, and graph `depth` where applicable. Group by `note_id`, **excluding the input notes themselves**. Per unique note aggregate `discovery_sources`, `source_count`, `best_score`, and `is_formally_related`.
+
+Composite relevance (0–100): reward notes found by **many distinct sources**, formally related, linked via a codebase, or reached from 2+ different input notes — not just a single high score. Sort descending and partition into Tier 1 (≥ 60, full detail), Tier 2 (40–59, compact), Tier 3 (< 40, count only).
+
+## Step 5 — Compile the context brief
+
+Present:
+- **Header** — intent; counts (input notes / codebases / aliases; discovered notes / codebases); semantic available?
+- **Input entities** — input notes (id, title, path, relation/related-code/alias counts) and input codebases (project, path, notes-linked).
+- **Aliases** — term → alias (source: prompt / Noesis).
+- **Discovered notes** — Tier 1 (score, title (id), found-via, path), Tier 2 (compact), Tier 3 (count only). Do **not** `get_note` discovered notes — search/similarity metadata is enough.
+- **Additionally discovered codebases** — any found in note metadata but not in the prompt (path · referenced-by). Skip if none.
+- **Connection map** — how input entities connect through discovered notes / shared codebases / aliases. Skip if none.
+- **Enrichment stats** — MCP calls issued, raw vs deduped counts, tier sizes, failed calls.
+
+## Step 6 — Proceed with enriched context
+
+After the brief, hand off to the actual work:
+
+```
+Original request:
+> [INVESTIGATION_PROMPT — full original text]
+
+Key facts to carry forward:
+- [Alias]: "[term]" is also known as "[alias]"
+- [Connection]: [Note X] and [Note Y] connect through [relation / shared codebase]
+- [Discovery]: [Title] (score N) may hold important context about [topic]
+- [Coverage gap]: [N] codebases have no Noesis documentation yet
+```
+
+Then continue in the same conversation with full awareness — read the input notes and codebases as needed to fulfill the request. This skill does **not** spawn sub-agents or write anything.
+
+**Follow-up actions:**
+- `/noesis-find-related <note ID or path>` — deep-dive one note's relation web, or a codebase's related notes.
+- `/noesis-refine-note <note path>` — enrich a discovered note's metadata and formal relations.
+- `/noesis-create-study-note <topic or URL>` — turn the investigation into a new structured note.
+
+## Implementation notes
+- **Read-only.** Enriches context only — never writes, edits, or syncs.
+- **Maximum parallelism.** Step 3 must issue all MCP calls in a single parallel batch.
+- **Only input notes get `get_note`.** Discovered notes use search/similarity metadata (title, path, score).
+- **Best-effort extraction.** Extract what you can from natural language and proceed; don't over-confirm every entity.
+- **`search_by_related_code` path rule:** always a single folder name, no slashes/backslashes.
+- **Graceful degradation.** Every enrichment call is optional; works keyword-only when semantic/embeddings are unavailable, and still presents the input entities even if all enrichment fails.

package/skill-templates/noesis-manage-news.md

@@ -0,0 +1,80 @@
+---
+description: Manage Daily News preferences on Noesis — add/remove sources, analyze preferences, discover new feeds. Use when the user says 'manage news', 'news preferences', 'add news source', 'find RSS feeds', or wants to manage their Daily News tool configuration via natural language.
+argument-hint: "<natural language instruction about news preferences>"
+---
+
+# /noesis-manage-news — Manage Daily News Preferences
+
+You are executing the `/noesis-manage-news` slash command. This is a **natural-language, prompt-driven** skill for managing the user's Daily News preferences in Noesis via MCP tools.
+
+## Arguments
+
+$ARGUMENTS
+
+## Available MCP Tools
+
+You have access to these Noesis MCP tools:
+- `mcp__noesis__get_news_preferences` — Read current preferences (topics, sources, seeds, weights, language, daily limit)
+- `mcp__noesis__update_news_preferences` — Update preferences (language, daily limit, topic/source weights)
+- `mcp__noesis__add_news_source` — Add an RSS feed source (name, URL, topic, language)
+
+## Instructions
+
+Parse the user's natural language intent and dispatch to the appropriate MCP tools. Common intents:
+
+### "Add this news URL" / "I like this article"
+1. Extract the domain from the URL
+2. Use web search to find the RSS feed for that domain (search for `"{domain}" RSS feed URL`)
+3. Call `add_news_source` with the discovered feed URL, domain name, and an appropriate topic category
+4. Report what was added
+
+### "Summarize my preferences" / "What am I reading?"
+1. Call `get_news_preferences`
+2. Present a human-readable summary: top topics by weight, active sources, language, daily limit
+3. Highlight any topics or sources with very low weights (< 0.2) that might need attention
+
+### "Remove topic X" / "I don't like X anymore"
+1. Call `get_news_preferences` to get current state
+2. Identify matching topics and sources
+3. Call `update_news_preferences` to set the topic weight to 0 and/or remove related source weights
+4. Report what was changed
+
+### "Find RSS feeds about [topic]" / "Add [topic] news"
+1. Use web search to find reputable RSS feeds for the topic (search for `"{topic}" RSS feed`, `"{topic}" news RSS`)
+2. Validate discovered URLs are actual RSS feeds
+3. Call `add_news_source` for each valid feed
+4. Report what was added
+
+### "Change language to [X]"
+1. Call `update_news_preferences` with the new `preferred_language`
+2. Suggest that existing sources may not match the new language
+
+### "Set daily limit to N"
+1. Call `update_news_preferences` with the new `daily_article_limit`
+
+## Language Awareness
+
+When adding sources or searching for feeds, respect the user's preferred language (check via `get_news_preferences` if not specified). Search for feeds in that language. Common language codes: `en`, `zh-TW`, `zh-CN`, `ja`, `ko`, `fr`, `de`, `es`.
+
+## Response Style
+
+- Be concise — report what you did, not how you did it
+- After making changes, show a brief summary of the updated state
+- If the user's intent is ambiguous, ask for clarification before making changes
+
+## Examples
+
+User: "I like this news https://arstechnica.com/tech-policy/2026/04/eu-ai-act/"
+Action: Search for Ars Technica RSS feed, add it as a source with topic "Technology"
+
+User: "What are my news preferences?"
+Action: Call get_news_preferences, present summary
+
+User: "Find me some Japanese tech news feeds"
+Action: Web search for Japanese tech RSS feeds, add discovered feeds with language "ja"
+
+User: "Remove the World Politics topic"
+Action: Get preferences, set World Politics weight to 0, report change
+
+User: "I want 30 articles per day"
+Action: Update daily_article_limit to 30