pi-weave 0.2.3 → 0.3.0

package/README.md

@@ -53,14 +53,24 @@ pi-weave keeps track of where knowledge came from, while making the whole worksp
 
 **The conversation can end. The knowledge doesn't have to.**
 
-## Built on Pi
+## Install
 
-pi-weave is built as an extension for [Pi](https://github.com/earendil-works/pi).
+pi-weave supports [Pi](https://github.com/earendil-works/pi) and OpenCode (V1 **1.18.29+** and V2) from the same package. The adapters share
+the vault, repository index, browser workspace, tools, and skills.
 
-I've grown to love Pi precisely because it is such a lightweight agent harness. It gives the model tools and context without trying to
-become the product itself, and its extensibility makes projects like pi-weave possible.
+OpenCode V2:
 
-Install pi-weave:
+```bash
+opencode plugin add pi-weave
+```
+
+OpenCode V1 1.18.29+: add the package to both `opencode.json` (server) and `tui.json` (browser opening):
+
+```json
+{ "plugin": ["pi-weave"] }
+```
+
+Pi:
 
 ```bash
 pi install npm:pi-weave
@@ -75,7 +85,7 @@ pi install /path/to/pi-weave
 
 Requires Node **20.13 or newer**.
 
-Then just talk to Pi.
+Then just talk to your agent.
 
 ## Start taking notes
 
@@ -92,21 +102,21 @@ You: Add that the gateway team owns the migration plan.
 You: What open questions are in this note?
 ```
 
-For live narration or interview notes, tell Pi that you are dictating:
+For live narration or interview notes, tell your agent that you are dictating:
 
 ```text
 You: Start a note for this interview. I’m going to narrate; keep my words
      verbatim and organize the note as we go.
 ```
 
-For each chunk, Pi:
+For each chunk, the agent:
 
 1. appends your words unchanged to the note’s `## Raw` tail;
 2. refreshes the structured summary above it;
 3. leaves the raw record untouched.
 
 This makes the note readable during the conversation without replacing your words with an AI reconstruction. Notes based on your dictation
-remain marked `source: human`; notes drafted by Pi are marked `source: agent`.
+remain marked `source: human`; notes drafted by the agent are marked `source: agent`.
 
 Useful requests include:
 
@@ -141,7 +151,7 @@ Renaming or moving a note rewrites its inbound links automatically, so its backl
 ```bash
 /weave-view              # open the browser workspace
 /weave-view --no-open    # start it and print the URL
-/weave-view tui          # terminal UI for SSH or browser-free use
+/weave-view tui          # Pi only: terminal UI for SSH or browser-free use
 ```
 
 The browser workspace has four connected views:
@@ -163,17 +173,18 @@ last writer wins, and the workspace picks up outside changes within a couple of
 
 `/weave-view tui` is the smaller, read-only terminal explorer: tree, focused neighborhood, details, and link health over the same graph.
 
-## Remember past pi sessions
+## Remember sessions
 
 ```bash
-/weave-scan sessions                    # pi history (default)
+/weave-scan sessions                    # Pi history, or the current OpenCode session
 /weave-scan sessions /path/to/history   # explicit history root
 ```
 
 This opt-in scan treats a supplied file—or every bounded text file under a supplied directory—as opaque session material for the active
-model to interpret, then writes generated notes under `~/.okf/notes/sessions/`. That makes it usable with Claude Code, opencode, Codex, or
-exported history trees without requiring their schema or file extension. It skips unchanged files, captures outcomes plus reusable technical
-takeaways, works outside Git repositories, and can be stopped with `/weave-scan-cancel`.
+model to interpret, then writes generated notes under `~/.okf/notes/sessions/`. In OpenCode, the pathless form reads the current session
+through the public plugin API; it never inspects OpenCode's internal database. That makes explicit paths usable with Claude Code, OpenCode,
+Codex, or exported history trees without requiring their schema or file extension. It skips unchanged files, captures outcomes plus reusable
+technical takeaways, works outside Git repositories, and can be stopped with `/weave-scan-cancel`.
 
 ## Repository knowledge
 
@@ -196,7 +207,7 @@ Most people only need natural language and `/weave-view`.
 
 | Surface | Name | Purpose |
 |---|---|---|
-| Command | `/weave-view` | Open the browser or terminal workspace |
+| Command | `/weave-view` | Open the browser workspace (`tui` is a Pi-only argument) |
 | Command | `/weave` | Show vault and repository status |
 | Command | `/weave-scan` | Build or refresh the repository index |
 | Command | `/weave-scan deep` | Add incremental model-written file summaries |
@@ -205,7 +216,11 @@ Most people only need natural language and `/weave-view`.
 | Tool | `weave_note` | List, read, add, append, finalize, and search notes |
 | Tool | `weave_repo` | Check, scan, and summarize the repository index |
 
-The included `weave-notepad` and `weave-explore` skills teach Pi when and how to use these tools.
+The included `weave-notepad` and `weave-explore` skills teach Pi and OpenCode when and how to use these tools. In OpenCode, `/weave` shows
+vault/repository status and scan progress appears in toasts; Pi keeps its persistent status line. V1 slash commands use its standard prompt
+pipeline, so the model reports command results in the conversation. `/weave` does not open a dialog. V1 scans use the model from your last
+chat message: send a message after selecting a model, then scan. Generation runs in temporary child sessions with tools denied;
+those sessions are removed on completion or cancellation. V2 uses its direct command and generation APIs.
 
 ## Files, privacy, and portability
 
@@ -245,14 +260,18 @@ We probably want OIDC next quarter…
 
 Set `PI_WEAVE_VAULT` to use a different vault location.
 
-Reading, writing, searching, and viewing notes are local operations. Deep repository scans and session summaries send bounded input to
-whichever model you configured in pi. The browser workspace binds only to loopback, uses a per-session token, and shuts down with the pi
-session.
+Reading, writing, searching, and viewing notes are local operations. Deep repository scans and session summaries send bounded input to the
+active Pi/V2 model or the last-used V1 chat model. The browser workspace binds only to loopback, uses a per-session token, and shuts down
+with the plugin lifecycle. OpenCode opens it automatically when the terminal can reach the viewer's loopback URL. Otherwise, it shows the
+exact URL for a browser or tunnel.
 
-The vault format, repository index, and skills are intentionally harness-agnostic. `src/core` contains no pi-specific imports.
+The vault format, repository index, and skills are intentionally harness-agnostic. `src/core` contains no Pi- or OpenCode-specific imports.
 
 ## Development
 
+The OpenCode V1/V2 bindings share tool schemas, core actions, and one command/scan workflow. Zod is the only direct runtime dependency,
+required by V1's tool-schema protocol; OpenCode SDKs are development-only.
+
 ```bash
 npm install
 npm run check

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-weave",
-  "version": "0.2.3",
-  "description": "An agent-native knowledge workspace for your life and your code. Smart notepad + repository exploration, readable by humans and agents alike.",
+  "version": "0.3.0",
+  "description": "Local-first Markdown memory and knowledge graph for Pi and OpenCode: preserve decisions, recall sessions, and explore notes with code.",
   "type": "module",
   "sideEffects": false,
   "publishConfig": {
@@ -9,10 +9,17 @@
   },
   "keywords": [
     "pi-package",
-    "knowledge-graph",
-    "agent",
+    "pi-coding-agent",
+    "opencode-plugin",
+    "agent-memory",
+    "persistent-memory",
+    "markdown",
     "notepad",
-    "repository-index"
+    "local-first",
+    "knowledge-graph",
+    "codebase-memory",
+    "obsidian",
+    "developer-tools"
   ],
   "license": "MIT",
   "author": "Eran Yonai <yonai.eran@gmail.com>",
@@ -26,6 +33,10 @@
     "node": ">=20.13.0"
   },
   "exports": {
+    "./server": "./src/opencode/index.ts",
+    ".": "./src/opencode/index.ts",
+    "./tui": "./src/opencode/tui.ts",
+    "./rpc": "./src/opencode/rpc.ts",
     "./core": "./src/core/index.ts"
   },
   "files": [
@@ -50,6 +61,7 @@
     "build:web": "node scripts/build-web.mjs",
     "build:web:check": "node scripts/build-web.mjs --check",
     "check": "npm run typecheck && npm run build:web:check && npm run coverage",
+    "eval:notepad": "node scripts/eval-notepad-search.mjs",
     "rewrap:md": "node scripts/rewrap-md.mjs",
     "rewrap:md:check": "node scripts/rewrap-md.mjs --check",
     "prepublishOnly": "npm run check"
@@ -64,6 +76,8 @@
     "@earendil-works/pi-ai": "^0.84.2",
     "@earendil-works/pi-coding-agent": "^0.84.2",
     "@earendil-works/pi-tui": "^0.84.2",
+    "@opencode-ai/plugin": "1.18.29",
+    "@opencode/plugin": "^2.0.19",
     "@types/d3-force": "^3.0.10",
     "@types/node": "^24.0.0",
     "@vitest/coverage-v8": "^3.2.4",
@@ -78,5 +92,8 @@
     "typebox": "1.3.7",
     "typescript": "^5.8.0",
     "vitest": "^3.2.4"
+  },
+  "dependencies": {
+    "zod": "4.1.8"
   }
 }

package/skills/weave-explore/SKILL.md

@@ -1,54 +1,38 @@
 ---
 name: weave-explore
-description: Explore a git repository through its pi-weave knowledge index (.okf). Use when starting work in an unfamiliar repo, when asked to "explore this repository", or before broad structural questions about modules, packages, or architecture.
+description: Explore unfamiliar git repositories and answer structural questions about modules, packages, or architecture using the pi-weave index (.okf).
 ---
 
 # Weave Explore
 
-pi-weave keeps a **derived** knowledge index of the repository at `<repo>/.okf/`. Source code is the truth; the index is a rebuildable
-cache. Deleting `.okf` loses nothing — rescan to regenerate it.
-
-## Tools
-
-In pi, use the `weave_repo` tool (or the `/weave-scan` command). To see the assembled graph in the terminal, run `/weave-view tui` (Explore
-tree, Focus neighborhood, Health surface); `/weave-view` opens the browser viewer. In other harnesses, read the JSON documents under `.okf/`
-directly.
+Use `weave_repo`. Without the tool, read `<repo>/.okf/` directly. The index is a generated, rebuildable cache; source code is authoritative.
 
 ## Workflow
 
-1. **Check for an index**: `weave_repo` action=status.
-   - `missing` → offer to scan (`weave_repo` action=scan), or scan directly when the user asked to explore.
-   - `stale` → scan again; the repository moved on.
-   - `fresh` → read it: action=overview.
-2. **Start from the overview**: file counts, languages, packages, module groupings, and likely entry points. This replaces dozens of
-   `ls`/`find` calls.
-3. **Descend progressively** (design §9): only open files in modules relevant to the user's question. The index gives you the map; the code
-   gives you the terrain.
-4. **Read summaries before full files**: if the repo has been deep-scanned (`.okf/repository/summaries/` exists), read the relevant sidecars
-   first — they tell you what a file does and its outward surface in 1–3 sentences, so you can decide whether to open the full file at all.
-5. **Answer with structure**: name modules and packages by their indexed paths so the user can jump straight to them.
+1. Check `action=status`: if missing, offer a scan or scan when exploration was requested; if stale, rescan; if fresh, read
+   `action=overview`.
+2. Use the overview's languages, packages, modules, and entry points to select relevant paths instead of listing the whole repository.
+3. Read available `.okf/repository/summaries/` sidecars before opening full files.
+4. Inspect the relevant code and cite indexed paths in your answer.
 
-## Deep summaries
+## Commands
 
-`/weave-scan deep` creates or refreshes `.okf/repository/summaries/` — one sidecar per file, written by the session model. It is **opt-in
-and incremental**: it never runs implicitly, and it only re-summarizes files whose content hash changed since their last summary. If
-summaries are missing or stale, offer `/weave-scan deep` to create or refresh them before diving into full files.
+- `/weave-scan` refreshes the index (`weave_repo` action=scan).
+- `/weave-scan deep` generates file summaries using the session model. Offer it when summaries are missing or stale; never run it
+  implicitly. Only changed content is summarized again.
+- `/weave-view` opens the browser workspace.
+- `/weave-scan sessions [path]` writes session memories to the vault, not the repository index; see `weave-notepad`.
 
-Its sibling `/weave-scan sessions` is a different scope: it summarizes past *session transcripts* into the vault (`notes/sessions/`), not the repository. See the `weave-notepad` skill — nothing it writes lands in `.okf/`.
-
-## On-disk layout
+## Files and trust
 
 ```text
 .okf/
 ├── okf.json               # format version + generator
 └── repository/
     ├── identity.json      # name, remotes, default branch
-    ├── git.json           # HEAD sha + branch + changed files (staleness anchor)
+    ├── git.json           # HEAD, branch, changed files
     ├── structure.json     # languages, packages, modules, entry points
-    └── summaries/         # deep-scan sidecars (one per file, when present)
+    └── summaries/         # generated file summaries, when present
 ```
 
-## Trust model
-
-Everything in `.okf` is machine-generated (`source: generated`). If the user corrects an interpretation, that correction belongs in the
-vault (see the `weave-notepad` skill) as human knowledge, not in the derived index.
+Index content is `source: generated`. Store user corrections as human knowledge in the vault, never only in the derived index.

package/skills/weave-notepad/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: weave-notepad
-description: "Take and retrieve durable notes in the pi-weave vault. Use when the user asks to remember something or to start/add to a note (aliases: notes, ai note, note-taking, note-taker), or when answering questions about past decisions, people, or projects. Also handles interview note-taking where raw dictations are appended AND expanded, and deterministic repair of stale [[wiki-links]] between notes."
+description: "Create, update, and retrieve durable notes and past decisions. Use for remember/note requests (notes, ai note, note-taking, note-taker), live dictation, interviews, and repairing or suggesting [[wiki-links]]."
 ---
 
 # Weave Notepad
@@ -8,26 +8,41 @@ description: "Take and retrieve durable notes in the pi-weave vault. Use when th
 The pi-weave vault is the user's long-term memory: plain Markdown notes with front matter under `~/.okf/notes/`. It is shared with the human
 — anything you write here, they can read and edit, and vice versa.
 
-## Tools
+Use `weave_note`. Without the tool, edit the files directly (`PI_WEAVE_VAULT` overrides the vault root). Front matter:
+`title`, `created`, `updated` (ISO-8601), `tags`, and `source: human | agent | generated`.
 
-In pi, use the `weave_note` tool. In other harnesses (or when the tool is not available), operate on the files directly:
+## Capture
 
-- **Notes** live at `~/.okf/notes/<slug>.md` (vault root overridable via `PI_WEAVE_VAULT`).
-- Each note has YAML front matter: `title`, `created`, `updated` (ISO-8601), `tags: [..]`, and `source: human | agent | generated`.
-- `weave_note` actions: `list`, `get`, `add`, `append`, `finalize`, `search`, `links`, `suggest`. `finalize` restructures the body *above* the `## Raw` tail and
-  preserves the tail verbatim — a body with no tail yet is preserved **in full** as a newly created tail, so finalization never destroys
-  dictation.
-- **Dictation appends**: use `append` with `raw: true` — the tool appends the text verbatim into the `## Raw` tail as a dated fenced block,
-  creating the tail if the note has none. In pi, never hand-format the raw tail; the tool maintains it.
+- Create notes only on explicit requests: “remember this”, “start a note”, “add to this note”. Do not capture conversation unprompted.
+- Given new content, call `add` directly and report the slug. Do not list the vault, inspect the repository, or run git first.
+- When extending existing knowledge, make one targeted `search`, then `append` to the matching note instead of duplicating it.
+- Ask one short question if content is missing; exploration cannot reveal what the user meant.
+- Use a specific title and 1–4 lowercase tags; reuse existing tags when known.
+- User-supplied words are `source: human`; pass that explicitly to `add`. Agent-drafted notes are `source: agent` (the default).
+  Finalization changes presentation, not authorship. Preserve human meaning; put agent additions in a dated “Agent addendum”.
+- Do not store repository-derived facts, temporary task state, or secrets the user has not confirmed are safe to persist.
 
-## Raw Tail Format
+## Dictation mode (continuous compile)
+
+During live dictation or interviews, keep the organized note current after every append; do not wait until the session ends:
 
-In pi you rarely format this by hand: `weave_note` append with `raw: true` appends a dated fenced block into the tail (and creates the whole
-tail — separator, heading, notice — when the note has none). The format below is what that produces, and what to write when editing files
-directly or working in other harnesses.
+1. `append` with `raw: true` preserves the user's words verbatim under `## Raw`. Never silently reword dictation.
+2. Immediately `finalize` the body above the tail: front-loaded summary, sections, decisions, questions, tasks, entities, and links
+   reflecting everything said so far.
 
-Every note maintains a verbatim, append-only raw section at the bottom separated by a horizontal rule (`---`):
+Outside dictation, finalize only on request.
+
+### How to capture and append raw input
 
+- Keep an append-only raw section at the bottom: `---`, then `## Raw`, then the notice shown below.
+- Fence verbatim input in code blocks. Prepend each subsequent block with `<!-- appended YYYY-MM-DD HH:MM -->`.
+- Use `append` with `raw: true` when available; it maintains this format and creates the tail if missing. Do not hand-format it.
+- `finalize` changes only the body above the tail. Never rewrite, remove, or move words out of the raw tail. If no tail exists, preserve the
+  entire previous body as a new raw tail before restructuring; the tool does this automatically.
+
+When editing files directly, preserve the same format:
+
+````markdown
 ---
 
 ## Raw
@@ -37,109 +52,42 @@ Every note maintains a verbatim, append-only raw section at the bottom separated
 <Initial verbatim input>
 ```
 
-<!-- appended 2026-08-23 08:45 -->
+<!-- appended YYYY-MM-DD HH:MM -->
 ```
-<Follow-up verbatim user input>
+<Follow-up verbatim input>
 ```
+````
 
-### How to capture and append raw input
-
-1. **Divider and Heading**: The raw section starts with `---` followed by `## Raw` and the notice comment: `<!-- NEVER edit below this line.
-   Verbatim user input preserved here. -->`.
-2. **Code Blocks for Verbatim Input**: Always wrap verbatim user lines inside code blocks (triple backticks).
-3. **Date and Time on Appends**: When appending subsequent snippets, prepend each snippet with: `<!-- appended YYYY-MM-DD HH:MM -->`.
-4. **Finalization (`finalize`)**:
-   - `finalize` replaces or structures content only above the `---` and `## Raw` section.
-   - The `## Raw` block and all verbatim code blocks are never modified or removed.
-
-## Dictation mode (continuous compile)
-
-During live dictation / interview note-taking (see the skill description), Pi does **not** wait until the end to organize the note. Every
-interactive append is immediately compiled into the body:
-
-1. **Append the raw words verbatim** into the `## Raw` tail (`weave_note` action=append with `raw: true` — the tool adds the dated code block
-   and creates the tail if missing).
-2. **Then immediately finalize** (`weave_note` action=finalize): rewrite the body *above* the `## Raw` tail — front-loaded summary,
-   sections, decisions, questions, tasks, entities, links — so the compiled document reflects everything said so far.
-3. **Never rewrite or remove the `## Raw` tail.** It stays append-only and verbatim; only the body above it changes.
-
-The result is a continuously-updated compiled document that stays current throughout the session — not just a raw tail that gets organized
-once at the end.
+## Retrieve
 
-## When to take a note
+- Known slug: `get`. Otherwise, one targeted `search` with the user's terms; never list the vault to find a note.
+- One result or a unique exact-title match returns the full note. Use it; do not fetch it again. A body marked `complete` needs no `get`.
+- For multiple plausible matches, fetch at most the three strongest slugs together. If still ambiguous, ask for another identifier instead
+  of repeating searches. Fetch additional content only when marked as an excerpt.
+- Search accepts ordinary multi-term queries, with exact-phrase matching followed by ranked lexical fallback. Read the match evidence and
+  bounded content before another call.
+- Connected notes are discovery context, not query matches. Use them only when their stated relationship matters; connections are lexical or
+  explicit, not semantic.
+- Trust repository code over conflicting notes about implementation; flag potentially stale intent.
 
-Create a note **only when the user explicitly asks** for one to exist: "start a note on X", "add to the X note", "remember this", "jot that
-down". Never promote conversation into a note on your own initiative — capture is explicit by design.
+## Session memory
 
-## When NOT to take a note
+`/weave-scan sessions [path]` creates searchable notes under `notes/sessions/` from available session transcripts.
 
-- Anything derivable from the repository itself (that knowledge belongs to the `.okf` index, not the vault).
-- Session-scratch information (in-progress task state).
-- Secrets, credentials, or anything the user hasn't confirmed is safe to persist.
+- These are `source: generated` recollections; a contradicting human decision record wins.
+- Search their `## Takeaways` for reusable lessons before re-deriving a familiar solution.
+- Rescans update changed transcripts while preserving human edits above the raw tail. Session notes remain re-derivable.
 
-## How to write a good note
+Scans spend model tokens. Never run them unprompted; suggest one when asked to recover history or improve memory across sessions. An
+explicit path accepts a history file or directory.
 
-0. **Go straight to the tool.** A note is one `weave_note` call. Do not `list` the vault, inspect the repository, or run `git` — none of that
-   informs what to write, and on a large vault `list` alone floods the context. When the user gives you the content ("note that says X"),
-   `add` it and report the slug.
-1. **Search first when adding to existing knowledge** (`weave_note` action=search, with the note's key terms): if a note on the subject
-   exists, `append` to it rather than creating a duplicate. Skip this when the user is clearly starting something new — one targeted search,
-   never a vault listing.
-2. Title: short noun phrase ("Auth boundary decision", not "Notes").
-3. **Ask only when the content is genuinely missing.** A vague request ("write a note weave") needs one short question, not exploration —
-   searching the vault or the repo will not reveal what the user meant.
-4. **Scribble in, verbatim.** When the user is dictating, append their words to the note as rough, verbatim scribbles — no silent rewording.
-   Append with `raw: true` so they land under the `## Raw` tail at the end of the note (the tail is created automatically if missing).
-5. **Compile continuously during dictation.** After *every* interactive append in dictation mode, immediately finalize the body *above* the
-   raw tail so the compiled doc stays current (see [Dictation mode](#dictation-mode-continuous-compile)). Outside dictation mode,
-   compilation stays on request.
-6. **Finalize on request.** When the user says "finalize this" / "clean this up", restructure the body *above* the raw tail: front-loaded
-   summary, sections, entities, links. Use `weave_note` action=finalize (or edit the file directly in other harnesses). Move nothing out of
-   `## Raw` — it is append-only and never rewritten. A note with no `## Raw` tail yet gets its entire pre-finalize body preserved as a new
-   raw tail: finalization is editorial, never destructive.
-7. Tags: 1–4 lowercase tags; reuse existing tags when possible.
-8. Provenance: notes the user scribbled stay `source: human` (finalization is editorial, not authorship) — pass `source: "human"` to `add`
-   for user-scribbled notes. Notes you draft from scratch are `source: agent` (the default). Never overwrite a `source: human` note's
-   meaning; append with a dated "Agent addendum" section instead.
+## Links
 
-## Session memory (`notes/sessions/`)
-
-`/weave-scan sessions` summarizes past agent session transcripts into generated notes under `notes/sessions/`. These are ordinary vault notes — `search` and `get` reach them like any other — with three differences worth knowing:
-
-- They are `source: generated`, not human knowledge. Treat one as a recollection of what a past session did, not as a decision record; a human note that contradicts it wins.
-- Each carries a `## Takeaways` section: reusable technical lessons (gotchas, root causes, non-obvious rules) from that session. When the user hits a problem that smells familiar, search the vault before re-deriving the answer — a previous session may already have paid for it.
-- They are re-derivable. The scan rewrites a note in place when its transcript changes, preserving human edits above the raw tail, so no session note is the only copy of anything.
-
-The scan is opt-in and never runs on its own. Suggest it when the user asks why the agent keeps forgetting across sessions, or wants history from another tool (`/weave-scan sessions <path>` accepts any history file or directory). Never run it unprompted: it spends model tokens per changed session.
-
-## Retrieving knowledge
-
-Use `weave_note` action=search with the user's key terms, then `get` the best hits. When a note and the repository index disagree, trust the
-repository for facts about code and flag the discrepancy — the note may be stale intent.
-
-## Repairing stale links
-
-A link written as a bare title or basename — `[[Quarterly Roadmap]]` when the note is `planning/roadmap-2026` — resolves to nothing.
-**Never reconnect a vault by reading every note and guessing which ones relate.** Run the deterministic pass instead:
-
-```jsonc
-weave_note { "action": "links" }              // report: fixable / ambiguous / unresolvable
-weave_note { "action": "links", "fix": true } // apply only the unambiguous repairs
-```
-
-It resolves by exact slug, then unique basename, then unique title — each requiring exactly one candidate. Ambiguous links are reported
-with their candidates and never guessed; unresolvable ones point at notes that were never written. Aliases are preserved, the `## Raw`
-tail and code fences are never touched, and `updated` is not bumped. Report first, apply after the user sees it.
-
-To find connections that were **never written** — two notes that belong together but have never referenced each other — use `suggest`:
-
-```jsonc
-weave_note { "action": "suggest" }                      // strongest unlinked pairs
-weave_note { "action": "suggest", "slug": "some/note" } // what relates to one note
-```
+Use `links` to report stale targets, then `links` with `fix: true` after the user reviews the report. Resolution requires exactly one
+candidate: exact slug, then basename, then slugified title. Never guess ambiguous targets or invent content for missing notes. Repairs
+preserve aliases, raw tails, code fences, and `updated`; do not reconstruct links by reading the entire vault and guessing.
 
-It ranks pairs by how much *rare* vocabulary they share, and cites the shared terms as evidence. **`suggest` never writes** — there is no `fix`.
-A similarity score is a soft signal and a `[[link]]` is a hard claim, so propose the worthwhile pairs to the user and add links only to those they
-confirm.
+Use `suggest` (optionally with `slug` or `limit`) for unwritten connections. It reports unlinked pairs with shared-term evidence and never
+writes. Propose relevant pairs and add links only after user confirmation; similarity is not an established relationship.
 
-See [references/link-repair.md](references/link-repair.md) for the full rules, guarantees, and when to run each.
+See [references/link-repair.md](references/link-repair.md) for examples and repair guarantees.

package/skills/weave-notepad/references/link-repair.md

@@ -1,90 +1,42 @@
-# Link repair — keeping the vault connected
+# Link repair
 
-A wiki-link resolves to nothing when it is written as a bare title or basename — `[[Quarterly Roadmap]]` while the note lives at
-`planning/roadmap-2026` — or when it points at a note that was never written. The graph then shows an isolated note that is in fact well
-connected.
-
-**Never reconnect a vault by reading it.** Do not search the vault note by note, infer which notes "feel related", and hand-write links.
-That is slow, costs tokens, and is not reproducible — two runs give two different answers. There is a deterministic pass that does it in
-one shot.
-
-## The tool
+Use deterministic repair for stale `[[wiki-links]]`; do not read every note and guess connections.
 
 ```jsonc
-weave_note { "action": "links" }              // read-only report
-weave_note { "action": "links", "fix": true } // apply the unambiguous repairs
+weave_note { "action": "links" }              // report
+weave_note { "action": "links", "fix": true } // apply unambiguous repairs
 ```
 
-In other harnesses, call `repairVaultLinks(vaultRoot, { apply })` from `pi-weave/core`.
-
-Always run the report first, read it, then apply. The report is cheap (one pass over the vault, no model calls).
-
-## How targets resolve
-
-Three rules, tried in order. A rule fires only when it yields **exactly one** candidate:
-
-| # | Rule | Example |
-|---|------|---------|
-| 1 | exact slug | `[[planning/roadmap-2026]]` — already correct, left alone |
-| 2 | unique basename | `[[roadmap-2026]]` → `planning/roadmap-2026` |
-| 3 | unique slugified title | `[[Quarterly Roadmap]]` → `planning/roadmap-2026` |
-
-Anything else is reported, never guessed:
-
-- **ambiguous** — several notes match (two `plan.md` in different folders). The report lists the candidates; a human picks one, or you
-  ask. Do not choose on their behalf.
-- **unresolvable** — no note matches. The link points at something never written. Offer to create the note or drop the link; **never
-  invent content to satisfy a link.**
+Without the tool, call `repairVaultLinks(vaultRoot, { apply })` from `pi-weave/core`. Report first, then apply after user review; never run
+`fix: true` unprompted on a vault you did not just change.
 
-## What a repair does and does not do
+## Resolution
 
-- Rewrites `[[Quarterly Roadmap]]` → `[[planning/roadmap-2026|Quarterly Roadmap]]`. The **alias preserves the visible text**, so the rendered prose is unchanged —
-  only the target moves.
-- **Does not touch the `## Raw` tail.** A link inside dictation is the user's words, quoted. Off limits, always.
-- **Does not touch fenced code blocks.** `[[…]]` in a code sample is a string literal.
-- **Does not bump `updated`.** A repair is bookkeeping, not an edit; bumping it would reorder the whole vault by recency.
-- **Is idempotent.** A second run finds nothing.
+Try these in order; each requires exactly one candidate:
 
-## Renames repair themselves
+| Rule | Example |
+|------|---------|
+| Exact slug | `[[planning/roadmap-2026]]` — unchanged |
+| Unique basename | `[[roadmap-2026]]` → `planning/roadmap-2026` |
+| Unique slugified title | `[[Quarterly Roadmap]]` → `planning/roadmap-2026` |
 
-`renameNote`, `moveNote` and `renameFolder` rewrite inbound links automatically, so renaming or moving a note keeps its backlinks intact.
-The repair pass is for links that were *written* stale — typed as a bare title, or pointing somewhere that never existed.
+- **Ambiguous:** report candidates and ask; never choose for the user.
+- **Unresolvable:** offer to create the missing note or remove the link; never invent content to satisfy it.
 
-## Finding connections that were never made
+Repairs preserve visible text through aliases: `[[Quarterly Roadmap]]` becomes `[[planning/roadmap-2026|Quarterly Roadmap]]`. They leave raw
+tails, fenced code, and `updated` untouched. A second run makes no changes. `renameNote`, `moveNote`, and `renameFolder` already repair
+inbound links automatically.
 
-Repair fixes links that point wrong. It cannot find links that were **never written** — two notes that belong together but have never referenced each
-other. That is `suggest`:
+## Unwritten connections
 
 ```jsonc
-weave_note { "action": "suggest" }                              // strongest pairs vault-wide
-weave_note { "action": "suggest", "slug": "some/note" }         // what relates to this note
+weave_note { "action": "suggest" }                      // strongest unlinked pairs
+weave_note { "action": "suggest", "slug": "some/note" } // one note's candidates
 weave_note { "action": "suggest", "limit": 40 }
 ```
 
-It ranks unlinked pairs by IDF-weighted cosine over every term a note carries — title, tags and body in one bag — weighting each term by how rare
-it is *in this vault*. Vocabulary shared by most notes (`sprint`, `meeting`, a tag on half the vault) scores near zero and connects nothing;
-a ticket id or an unusual name on a handful of notes scores high. Nothing is domain-specific: the vault's own frequencies decide.
-
-Every suggestion cites the shared terms that earned it. **Read the evidence, not the score** — a list like `shared: acme-1234, release-pipeline`
-is checkable, `0.16` is not.
-
-### suggest never writes
-
-This is the rule that matters. `suggest` only reports; there is no `fix`. A similarity score is a soft signal and a `[[link]]` is a hard claim —
-once written into a body it is indistinguishable from one the user wrote deliberately. Good scores here are around 0.1–0.3, not 0.9, so treat the
-output as a shortlist for a human:
-
-1. Run `suggest`, read the shared terms.
-2. Propose the worthwhile pairs **to the user**.
-3. Add `[[wikilinks]]` only to those they confirm.
-
-Never bulk-apply suggestions, and never present one as an established connection.
-
-## When to run it
-
-- The user asks to "fix the links in" their notes — `links`.
-- The health panel or `/weave` reports dangling links — `links`.
-- After bulk-importing or reorganising notes outside the tool — `links`.
-- The user asks what a note "relates to", or to "connect" / "link up" the vault — `suggest`, then confirm before writing.
+Suggestions rank unlinked pairs by IDF-weighted cosine over title, tags, and body. Rare shared vocabulary matters more than common terms.
+Read the cited terms, not just the score. `suggest` never writes and has no `fix`: propose useful pairs and add links only after
+confirmation. Never bulk-apply suggestions or present them as established connections.
 
-Do not run `fix: true` unprompted on a vault you did not just change — show the report and let the user approve. Reporting is always safe.
+Use `links` for dangling links or after external bulk imports; use `suggest` when asked to discover relationships or connect notes.