@noesis-brain/mcp-server 2.1.3 → 2.3.1

package/scripts/start-agent.sh

@@ -0,0 +1,331 @@
+#!/usr/bin/env bash
+#
+# Start the Noesis Local Agent daemon, replacing any instance already running — and
+# refuse to leave a daemon running that lacks the tool-boundary fix.
+#
+# Why this exists: the daemon is normally launched by hand
+# (`npx @noesis-brain/mcp-server@latest agent`), and nothing stops a second one. On
+# 2026-08-14 four were running at once, two rooted at $HOME. They all poll the same queue,
+# so whichever won the race decided which build served the job — a stale daemon answered
+# minutes after a fixed one started, which looked exactly like a fix that did not work.
+#
+# Killing is deliberately two passes because the launcher is TWO processes: an
+# `npm exec @noesis-brain/mcp-server@<spec> agent` parent and a `node .../noesis-mcp agent`
+# child. Killing only the child lets npm respawn it.
+#
+# WHY THE VERSION ASSERT: an earlier version of this script started `@latest` by default
+# while the fix was still unpublished, so its no-argument path SIGKILLed the fixed daemon,
+# started an UNFIXED one, and printed success — silently restoring the vulnerability it
+# exists to prevent. Publishing lags code, so the script must verify what it actually
+# started rather than trust the tag.
+#
+# Usage:  ./scripts/start-agent.sh            # published build via npx (default)
+#         ./scripts/start-agent.sh --local    # this checkout's dist/ (after npm run build)
+#         ./scripts/start-agent.sh --status   # report running daemons, exit 1 if any is unfixed
+#         ./scripts/start-agent.sh --stop     # stop everything, start nothing
+#         ./scripts/start-agent.sh --grade <package-dir>   # grade one build; touches no process
+
+set -euo pipefail
+
+# Resolve this script's own location BEFORE any cd — $BASH_SOURCE is relative when invoked
+# as ./scripts/start-agent.sh, so reading it after the cd to $RUN_DIR resolves against the
+# wrong directory and --local would fail.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PKG_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# First release carrying `tools: []` + the canUseTool gate. A daemon below this exposes
+# Claude Code's whole built-in tool set (Bash/Read/Write/Edit/Grep/Task) to every Navi.
+MIN_FIXED_VERSION="2.1.5"
+
+MODE="${1:-}"
+case "$MODE" in
+  ''|--local|--stop|--status) ;;
+  --grade)
+    [ -n "${2:-}" ] || { echo "usage: $(basename "$0") --grade <package-dir>" >&2; exit 2; }
+    ;;
+  *)
+    echo "usage: $(basename "$0") [--local | --status | --stop | --grade <package-dir>]" >&2
+    # Deliberately NOT a silent fallback: a typo'd flag used to start the PUBLISHED build
+    # instead of the local one — the same "wrong build served the job" signature.
+    exit 2
+    ;;
+esac
+
+RUN_DIR="${NOESIS_AGENT_RUN_DIR:-$HOME/.noesis-agent}"
+LOG_FILE="$RUN_DIR/agent.log"
+
+# Every shape the daemon can appear as, matched against the full command line.
+# `@noesis-brain/mcp-server(@[^ ]*)? agent` covers the npm exec parent for a pinned spec,
+# a tag, AND no spec. A plain MCP-server invocation has no ` agent` argument and is never
+# matched: that process is the user's Claude Code integration, not a daemon.
+PATTERNS=(
+  'noesis-mcp agent'
+  '@noesis-brain/mcp-server(@[^ ]*)? agent'
+  'dist/index.js agent'
+)
+
+# Only ever our own processes. Unscoped pgrep also matches other users' and root's, which
+# `kill` cannot touch (EPERM) — those would be counted as survivors forever, wedging the
+# guard into "refusing to start" after having already killed the real daemon.
+pids_matching() {
+  for pattern in "${PATTERNS[@]}"; do
+    pgrep -U "$(id -u)" -f "$pattern" 2>/dev/null || true
+  done | sort -un
+}
+
+# `|| true` inside the braces is load-bearing: pgrep exits 1 on no match, and with
+# `set -e` + `pipefail` that would abort. Dedupe, or a process matching two patterns
+# inflates the count and can trip the refuse-to-start guard.
+count_matching() { pids_matching | wc -l | tr -d ' '; }
+
+kill_matching() {
+  local signal="$1" pid
+  while read -r pid; do
+    [ -z "$pid" ] && continue
+    [ "$pid" = "$$" ] && continue
+    [ "$pid" = "${PPID:-0}" ] && continue
+    if kill "$signal" "$pid" 2>/dev/null; then
+      echo "  ${signal#-} pid $pid"
+    elif ! kill -0 "$pid" 2>/dev/null; then
+      : # already exited from the previous pass — the normal case, not worth a line
+    else
+      # Still alive and we could not signal it (EPERM). Do NOT swallow this: a kill we
+      # cannot perform is exactly what leaves a survivor and wedges the guard below.
+      echo "  ${signal#-} pid $pid FAILED — still running and not killable by us" >&2
+    fi
+  done < <(pids_matching)
+  return 0
+}
+
+# `$1 >= $2` for plain x.y.z versions.
+version_ge() {
+  [ "$(printf '%s\n%s\n' "$2" "$1" | sort -t. -k1,1n -k2,2n -k3,3n | head -1)" = "$2" ]
+}
+
+# The package directory backing a running daemon. Extracted WITHOUT a `[^ ]*` path regex:
+# that could not cross a space, so an install under "/Users/x/My Repos/..." resolved to the
+# wrong directory, was graded UNKNOWN, and the assert below killed a perfectly good daemon.
+pkg_dir_for_pid() {
+  local pid="$1" cmd path
+  cmd="$(ps -o command= -p "$pid" 2>/dev/null || true)"
+  case "$cmd" in *" agent") cmd="${cmd% agent}" ;; *) ;; esac
+  path="${cmd#* }"                       # drop the interpreter, keep the (possibly spaced) path
+  case "$path" in
+    */dist/index.js) dirname "$(dirname "$path")"; return ;;
+    */node_modules/.bin/noesis-mcp)
+      printf '%s/@noesis-brain/mcp-server' "$(dirname "$(dirname "$path")")"; return ;;
+  esac
+  printf ''
+}
+
+# Comments are copied verbatim into dist (tsconfig sets no `removeComments`), and this
+# codebase DOCUMENTS both markers heavily — `tools: []` occurs on 6 lines of the compiled
+# output, only ONE of which is code. Grepping the raw file therefore certified a build with
+# the boundary deleted as FIXED, which made the whole assurance layer theatre. Strip
+# comments before looking for code.
+strip_js_comments() { perl -0pe 's{/\*.*?\*/}{}gs; s{^[[:space:]]*//.*$}{}gm' "$1" 2>/dev/null || true; }
+
+# True when compiled runner.js (comments already stripped, on stdin) restricts the SDK's
+# built-in tools. Two accepted shapes:
+#   - `tools: []`              — 2.1.5 to 2.1.x: no built-ins at all;
+#   - `tools: webTools` built by `clampWebTools(` over the literal two-name list
+#                              — 2.2.0+: none, or at most WebFetch + WebSearch, which have
+#                                no filesystem access (web Navis; see runner.ts).
+# Recognising ONLY the first shape graded every 2.2.0 daemon UNFIXED and the assert at the
+# bottom then killed it: a guaranteed outage on the first restart after publishing.
+# The version floor stays 2.1.5 — the filesystem boundary is what this guards.
+has_tool_boundary() {
+  local code; code="$(cat)"
+  # Here-strings, not `printf | grep -q`: under pipefail an early-exiting grep can SIGPIPE
+  # the writer once the file outgrows the pipe buffer, turning a match into a failure.
+  grep -q 'canUseTool:' <<<"$code" || return 1
+  grep -q 'tools: \[\]' <<<"$code" && return 0
+  grep -q 'tools: webTools,' <<<"$code" \
+    && grep -q 'const webTools = clampWebTools(' <<<"$code" \
+    && grep -q "ALLOWED_WEB_TOOLS = \['WebFetch', 'WebSearch'\]" <<<"$code"
+}
+
+# Prints "<version> <FIXED|UNFIXED(reason)>" for a package directory.
+#
+# TWO INDEPENDENT SIGNALS, both required:
+#   - the package version is >= MIN_FIXED_VERSION (the same signal the backend's
+#     MIN_TOOL_AGENT_VERSION gate uses), and
+#   - the compiled output actually contains both halves of the fix, comments removed.
+# An earlier version compared neither: MIN_FIXED_VERSION was assigned and never used, and
+# the content check matched documentation. "v2.1.5 FIXED" was two non-facts side by side.
+describe_dir() {
+  local dir="$1" ver ver_ok=0 code_ok=0
+  ver="$(node -e "process.stdout.write(String(require('$dir/package.json').version||'0.0.0'))" 2>/dev/null || echo '0.0.0')"
+  version_ge "$ver" "$MIN_FIXED_VERSION" && ver_ok=1
+  if [ -f "$dir/dist/agent/runner.js" ]; then
+    if strip_js_comments "$dir/dist/agent/runner.js" | has_tool_boundary; then code_ok=1; fi
+  fi
+  if [ "$ver_ok" = 1 ] && [ "$code_ok" = 1 ]; then echo "$ver FIXED"
+  elif [ "$ver_ok" = 0 ]; then echo "$ver UNFIXED(v<$MIN_FIXED_VERSION)"
+  else echo "$ver UNFIXED(code)"; fi
+}
+
+# Prints "<version> <FIXED|UNFIXED(reason)|PARENT>" for a pid.
+describe_pid() {
+  local dir
+  dir="$(pkg_dir_for_pid "$1")"
+  # No package dir = the `npm exec` wrapper, not a daemon. Its child is graded separately;
+  # counting the parent as "unknown, therefore exposed" cried wolf on every healthy npx
+  # launch, which is the mode that becomes correct once the fix is published.
+  if [ -z "$dir" ] || [ ! -f "$dir/package.json" ]; then echo "- PARENT"; return; fi
+  describe_dir "$dir"
+}
+
+# --grade <dir>: grade one package directory and touch no process. The test suite runs
+# this against a fresh compile of runner.ts, so a change the check above stops recognising
+# fails a test instead of killing every user's daemon on their next restart.
+if [ "$MODE" = "--grade" ]; then
+  grade_dir="$(cd "$2" && pwd)"
+  read -r ver state <<<"$(describe_dir "$grade_dir")"
+  echo "$ver $state"
+  if [ "$state" = "FIXED" ]; then exit 0; fi
+  exit 1
+fi
+
+# --status: the one command that answers "is my machine exposed right now?".
+if [ "$MODE" = "--status" ]; then
+  exposed=0 total=0
+  while read -r pid; do
+    [ -z "$pid" ] && continue
+    read -r ver state <<<"$(describe_pid "$pid")"
+    if [ "$state" = "PARENT" ]; then
+      printf '  pid %-7s %-10s (npm exec wrapper — its child is graded below)\n' "$pid" "$state"
+      continue
+    fi
+    total=$((total + 1))
+    printf '  pid %-7s v%-8s %s\n' "$pid" "$ver" "$state"
+    [ "$state" = "FIXED" ] || exposed=$((exposed + 1))
+  done < <(pids_matching)
+  [ "$total" -eq 0 ] && echo "  no daemon running"
+  # Honest about what this can and cannot see, rather than implying a clean bill of health.
+  echo "  (grades the package on disk, for this user's processes only; a daemon started"
+  echo "   before a rebuild may still be running older code in memory)"
+  if [ "$exposed" -gt 0 ]; then
+    echo "[start-agent] EXPOSED: $exposed of $total daemon process(es) lack the tool boundary." >&2
+    echo "              They can read your filesystem. Run: $(basename "$0") --local" >&2
+    exit 1
+  fi
+  echo "[start-agent] ok — $total daemon process(es), all carry the fix."
+  exit 0
+fi
+
+# CHECK BEFORE KILLING. The published build is what the default mode is about to install,
+# so verify it is new enough BEFORE tearing down a working daemon. Without this the default
+# path was a guaranteed outage while the fix was unpublished: kill everything (including a
+# healthy fixed daemon) -> install an unfixed one -> assert fails -> kill it -> exit 1,
+# leaving the machine with NO daemon and subscription chat dead.
+if [ "$MODE" = "" ]; then
+  published="$(npm view @noesis-brain/mcp-server dist-tags.latest 2>/dev/null || true)"
+  if [ -z "$published" ]; then
+    echo "[start-agent] Could not reach npm to check the published version; refusing to" >&2
+    echo "              tear down a running daemon on a guess. Use --local." >&2
+    exit 1
+  fi
+  if ! version_ge "$published" "$MIN_FIXED_VERSION"; then
+    echo "[start-agent] Published @latest is v$published, which is older than v$MIN_FIXED_VERSION" >&2
+    echo "              and lacks the tool boundary. NOT touching the running daemon." >&2
+    echo "              Publish $MIN_FIXED_VERSION, or start this checkout: $(basename "$0") --local" >&2
+    exit 1
+  fi
+fi
+
+echo "[start-agent] stopping existing daemons..."
+[ "$(count_matching)" -eq 0 ] && echo "  none running"
+kill_matching -TERM
+sleep 2                 # a parent can respawn its child on SIGTERM
+kill_matching -KILL
+sleep 1
+
+remaining="$(count_matching)"
+if [ "$MODE" = "--stop" ]; then
+  if [ "$remaining" -gt 0 ]; then
+    echo "[start-agent] WARNING: $remaining daemon process(es) survived --stop." >&2
+    exit 1
+  fi
+  echo "[start-agent] all stopped."
+  exit 0
+fi
+if [ "$remaining" -gt 0 ]; then
+  echo "[start-agent] ERROR: $remaining daemon process(es) still alive; refusing to start another." >&2
+  pids_matching | sed 's/^/  surviving pid /' >&2
+  exit 1
+fi
+
+# Credentials come from the same place the MCP server registration uses, so the token never
+# has to be pasted into a shell or a process argv.
+CLAUDE_JSON="$HOME/.claude.json"
+if ! node -e "
+  const e = (require('$CLAUDE_JSON').mcpServers || {}).noesis?.env;
+  if (!e?.NOESIS_API_URL || !e?.NOESIS_API_TOKEN) process.exit(1);
+" 2>/dev/null; then
+  echo "[start-agent] No Noesis credentials in $CLAUDE_JSON (mcpServers.noesis.env)." >&2
+  echo "              claude mcp add -s user noesis -- npx -y @noesis-brain/mcp-server" >&2
+  exit 1
+fi
+NOESIS_API_URL="$(node -e "console.log(require('$CLAUDE_JSON').mcpServers.noesis.env.NOESIS_API_URL)")"
+NOESIS_API_TOKEN="$(node -e "console.log(require('$CLAUDE_JSON').mcpServers.noesis.env.NOESIS_API_TOKEN)")"
+export NOESIS_API_URL NOESIS_API_TOKEN
+
+mkdir -p "$RUN_DIR"
+cd "$RUN_DIR"
+
+if [ "$MODE" = "--local" ]; then
+  DIST="$PKG_DIR/dist/index.js"
+  [ -f "$DIST" ] || { echo "[start-agent] $DIST missing — run 'npm run build' first." >&2; exit 1; }
+  echo "[start-agent] starting LOCAL build: $DIST"
+  nohup node "$DIST" agent >> "$LOG_FILE" 2>&1 &
+else
+  echo "[start-agent] starting published @noesis-brain/mcp-server@latest"
+  nohup npx -y @noesis-brain/mcp-server@latest agent >> "$LOG_FILE" 2>&1 &
+fi
+
+# Wait for the DAEMON, not the npx parent. A cold `npx -y` install can take 10-60s, and the
+# parent alone used to satisfy the old fixed 6s check — so a failed install reported success
+# with zero daemons running.
+started=0
+for _ in $(seq 1 60); do
+  sleep 1
+  while read -r pid; do
+    [ -z "$pid" ] && continue
+    case "$(ps -o command= -p "$pid" 2>/dev/null || true)" in
+      *dist/index.js\ agent*|*noesis-mcp\ agent*) started="$pid"; break ;;
+    esac
+  done < <(pids_matching)
+  [ "$started" != 0 ] && break
+done
+
+if [ "$started" = 0 ]; then
+  echo "[start-agent] ERROR: daemon did not come up within 60s. Tail of $LOG_FILE:" >&2
+  tail -5 "$LOG_FILE" >&2 2>/dev/null || true
+  exit 1
+fi
+
+# THE ASSERT. Never leave a daemon running that lacks the tool boundary, whichever mode got
+# us here — including the published default while the fix is unpublished.
+read -r ver state <<<"$(describe_pid "$started")"
+if [ "$state" != "FIXED" ]; then
+  echo "[start-agent] ERROR: started daemon pid $started is v$ver ($state) — it lacks the" >&2
+  echo "              tool boundary and can read your filesystem. Stopping it." >&2
+  # Both passes over the whole pattern set, not just this pid: killing the child alone
+  # leaves the `npm exec` parent to respawn it — which is the exact failure this script's
+  # own header describes, and it would have happened right after printing "Stopping it."
+  kill_matching -TERM >&2
+  sleep 2
+  kill_matching -KILL >&2
+  sleep 1
+  if [ "$(count_matching)" -gt 0 ]; then
+    echo "              WARNING: $(count_matching) process(es) survived; run --status." >&2
+  fi
+  echo "              Publish $MIN_FIXED_VERSION or newer, or start the local build:" >&2
+  echo "              $(basename "$0") --local" >&2
+  exit 1
+fi
+
+echo "[start-agent] running: pid $started (v$ver, $state)"
+echo "[start-agent] log: $LOG_FILE"
+tail -3 "$LOG_FILE" 2>/dev/null | sed 's/^/  /'

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

@@ -0,0 +1,163 @@
+---
+description: Refine the typed relations (Related Notes) of a SET of Noesis notes so the Graph view shows real structure. Scopes by timeframe, topic, catalog or signal — "last two weeks", "notes about BTC", "BTO printing in the last month", "points over 100". Proposes a diff per note and writes only on approval. Use when the user says 'refine relations', 'refine note relations', 'fix my graph', 'link my notes', 'these notes have no relations', or names a batch of notes to connect.
+argument-hint: "[recent <N> days|weeks|months] [topic <words>] [catalog <NAME>] [points over <N>] [<note path | note ID | query>]"
+---
+
+# /noesis-refine-relations — Batch relation refinement
+
+You are executing `/noesis-refine-relations`. It selects a **set** of notes, works out which
+other notes each one should formally link to, shows you the diff, and writes only what you
+approve.
+
+Relations live in the Noesis **database**, not in the markdown. This skill therefore never
+edits a note body and never needs a sync.
+
+## What this is NOT
+
+The app already has a per-note **"Suggest relations"** in the graph's node menu. It reasons
+over ≤20 candidates carrying only a title and a short description — **it never reads note
+bodies**, and it runs on one note at a time.
+
+This skill is the complement: many notes at once, and it *reads the content*, so it can find
+the links a note states in its own text (cited file paths, note URLs, quoted titles). Where
+the in-app suggester is the right tool for one note, say so and stop.
+
+## Step 0 — Route on the argument
+
+The raw arguments string is: `$ARGUMENTS`
+
+First match wins:
+
+| Argument looks like | Mode |
+|---|---|
+| "last N days/weeks/months", "recent", "this week" | **RECENT** |
+| a topic phrase *and* a timeframe | **TOPIC ∩ RECENT** |
+| a topic phrase ("about BTC", "BTO printing") | **TOPIC** |
+| "points over N", "score above N", "favorite", "pinned", "starred" | **SIGNAL** |
+| "catalog X" | **CATALOG** |
+| a note ID, a `.md` path, or a bare query | **SINGLE** |
+| empty | **ASK** — `AskUserQuestion` offering the modes above |
+
+State the mode and the resolved parameters before doing anything.
+
+## Step 1 — Resolve the note set
+
+- **RECENT** — `mcp__noesis__list_notes(recent: <N_DAYS>, limit: 100)`.
+- **TOPIC** — `mcp__noesis__search_semantic(query, limit: 20)` **and**
+  `mcp__noesis__search_notes(query, limit: 50)`; union by ID.
+- **TOPIC ∩ RECENT** — run both of the above and intersect.
+- **SIGNAL** — `list_notes(limit: 100)`, then filter client-side on the `⭐` and `[N pts]`
+  markers in the output.
+- **CATALOG** — `list_notes(catalog: <NAME>, limit: 100)`.
+- **SINGLE** — resolve directly (`get_note` by id/path, or `search_notes` then pick).
+
+Then **always**:
+
+1. **Drop capture notes** — anything under a `captures/` folder is an auto-pushed session
+   mirror, not a note the user authored. Never link them unless explicitly asked.
+2. **Cap the batch.** Default to 15 notes. If the scope resolved to more, take the 15 most
+   recently modified and **say how many you dropped** — never present a truncated sweep as
+   a complete one.
+3. Print the candidate table (ID, title, path, current relation count) and confirm the set
+   before moving on.
+
+### Selection limits you must respect
+
+These are properties of the MCP tools, not preferences:
+
+- `list_notes` caps `limit` at **100** server-side and exposes no offset. A scope wider than
+  100 notes cannot be enumerated in one call — narrow it and say so.
+- When `recent` is set, `root` and `catalog` are **silently ignored**. Combined filters must
+  be applied client-side.
+- `list_notes` prints `⭐` and `[N pts]` but **not the note ID**, so resolve IDs from paths
+  before writing anything.
+- `search_semantic` and `find_similar_notes` need embeddings and fail without a Gemini key.
+  Degrade to keyword-only and note it; never abort the run over it.
+
+## Step 2 — Per note: build the proposed set
+
+For each note in the confirmed set, in order:
+
+**2a. Read the current relations.** `mcp__noesis__get_note(id)`. This is the only reliable
+read — use it every time, even when you expect none.
+
+**2b. Gather candidates**, in one parallel batch:
+- `mcp__noesis__find_similar_notes(note_id, limit: 15)`
+- `mcp__noesis__search_semantic(query: title + description, limit: 10)`
+- **The body scan — the highest-precision source, and the reason this skill exists.**
+  Read the note content and extract every note it already cites:
+  - file paths ending in `.md` (absolute, `~/Noesis/...`, or bare filenames)
+  - `noesisbrain.com/notes/<id>` URLs — the `<id>` is the target, use it directly
+  - quoted note titles
+  Resolve each to an ID with `mcp__noesis__search_notes`. An edge grounded in a line of the
+  note's own text is worth more than any similarity score; keep the line as evidence.
+
+**2c. Filter.** Drop captures, drop the note itself (the MCP write path does **not** reject
+self-links), drop anything that fails to resolve. Never invent an ID — if a cited note cannot
+be resolved, report it as unresolved rather than guessing.
+
+**2d. Choose a type** per edge, from exactly these five:
+`related` · `references` · `implements` · `extends` · `supersedes`.
+Default to `references` when the note merely cites the target, `related` when the connection
+is thematic.
+
+**2e. Union with the existing set from 2a.** Keep every existing entry unless the user has
+explicitly asked to prune. This matters — see the write contract below.
+
+**2f. Apply a cap.** 2–5 relations for a focused note; up to 8 for a comprehensive
+architecture, workflow, or strategy note. **Tracker, sprint and index notes are exempt** —
+being a hub is their job, and a tracker citing 25 notes should link to 25.
+
+## Step 3 — Propose
+
+Print, per note:
+
+```
+Note 2923  BTO 12.3 Aug Sprint 0        edges 0 -> 25
+  = keep  references  4424  IDEA-1579 HTTPS support
+  + add   references  3611  BPLAT-14016 UltraLite Simple Serialization
+          evidence: "my-git/issues/BPLAT-14016-phoenix-tsc-ultralite...md"
+  + add   related     2924  Epsilon Branch Merge Convention
+          evidence: similar 0.81, both cover the Epsilon merge workflow
+  ! unresolved: "support-https-print-portal-investigation.md" (no match)
+```
+
+Then ask once, for the whole batch, via `AskUserQuestion`: apply all / pick per note / cancel.
+**Never write before this point.**
+
+## Step 4 — Write
+
+For each approved note, issue **exactly one** `mcp__noesis__update_relations` call carrying
+the **complete** desired set.
+
+> **The write REPLACES the note's whole relation set.** It clears the column and stores what
+> you send. One call per relation — a pattern that exists elsewhere in this repo's older
+> commands — leaves the note with only the last relation written and silently deletes the
+> rest. Send the union from 2e, always.
+
+No inverse relation is created on the target, and you must not try to write one. Backlinks
+are **derived**: the app scans every note's one-way array to build the graph, so a single
+edge already shows up on both notes — as "linked to" on the source and "linked by" on the
+target. Writing the mirror by hand would double-store derived data and turn every edge into
+"mutual", destroying the direction the user can currently see.
+
+Do **not** write a "Related Notes" section into the markdown body. Relations are database
+metadata; a section in the file is a stale duplicate. If a previous run left one, remove it.
+
+## Step 5 — Report
+
+A table of note · edges before → after · skipped-and-why, plus every unresolved citation.
+Then suggest `mcp__noesis__get_relation_graph(note_id, depth: 1)` or the Graph view to
+confirm the shape.
+
+## Implementation notes
+
+- **Read before write, every time.** The write is a replace; skipping 2a loses relations.
+- **The body scan is the differentiator.** If you skip it, this skill is just a slower
+  version of the in-app suggester.
+- **Evidence or no edge.** Every proposed link needs either a quoted line from the note or a
+  similarity score. "These feel related" is not a reason.
+- **Sequential per note.** Parallel `get_note` batches race the API rate limit; the
+  *candidate gathering* inside one note (2b) is the part to parallelize.
+- **Report every cap.** A truncated batch, a dropped candidate, an unresolved citation — all
+  of it goes in the Step 5 report. A sweep that hides what it skipped is worse than no sweep.