pi-weave 0.1.21 → 0.1.23

package/README.md

@@ -82,6 +82,24 @@ Useful requests include:
 | “Clean up” or “finalize this note” | Reorganizes the readable body and preserves the raw tail |
 | “What did we decide about…?” | Searches the vault, then reads the relevant notes |
 | “Remember that…” | Stores durable knowledge for a future session |
+| “Fix the broken links” | Audits and repairs stale `[[wiki-links]]` deterministically |
+
+## Keeping the vault connected
+
+A wiki-link resolves to nothing when it is written as a bare title — `[[Quarterly Roadmap]]` when the note lives at
+`planning/roadmap-2026` — or when it points at a note that was never written. Pi repairs those in one deterministic pass instead of
+rereading the vault and guessing.
+
+```text
+You: Check the links in my notes.
+You: Fix the ones you're sure about.
+```
+
+A target resolves by exact slug, then unique basename, then unique title — each rule requiring **exactly one** candidate. Ambiguous links
+are reported with their candidates and never guessed; links to notes that were never written are listed, never invented. Repairs preserve
+the alias, so the visible text does not change, and never touch the `## Raw` tail or code fences.
+
+Renaming or moving a note rewrites its inbound links automatically, so its backlinks stay intact.
 
 ## `/weave-view`
 
@@ -209,6 +227,7 @@ Read [AGENTS.md](AGENTS.md) before contributing. Work on a feature branch; do no
 
 - [Design](docs/design.md) — product and architecture
 - [Notepad skill](skills/weave-notepad/SKILL.md) — capture, narration, and provenance behavior
+- [Link repair reference](skills/weave-notepad/references/link-repair.md) — how stale links resolve, and what repair will not do
 - [Historical browser workspace notes](docs/weave-workspace.md) — superseded implementation record
 - [Repository exploration skill](skills/weave-explore/SKILL.md) — how Pi uses the index
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-weave",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "An agent-native knowledge workspace for your life and your code. Smart notepad + repository exploration, readable by humans and agents alike.",
   "type": "module",
   "sideEffects": false,

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."
+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."
 ---
 
 # Weave Notepad
@@ -14,7 +14,7 @@ In pi, use the `weave_note` tool. In other harnesses (or when the tool is not av
 
 - **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`. `finalize` restructures the body *above* the `## Raw` tail and
+- `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,
@@ -79,19 +79,26 @@ down". Never promote conversation into a note on your own initiative — capture
 
 ## How to write a good note
 
-1. **Search first** (`weave_note` action=search): if a note exists, `append` to it rather than creating a duplicate.
+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. **Scribble in, verbatim.** When the user is dictating, append their words to the note as rough, verbatim scribbles — no silent rewording.
+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).
-4. **Compile continuously during dictation.** After *every* interactive append in dictation mode, immediately finalize the body *above* the
+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.
-5. **Finalize on request.** When the user says "finalize this" / "clean this up", restructure the body *above* the raw tail: front-loaded
+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.
-6. Tags: 1–4 lowercase tags; reuse existing tags when possible.
-7. Provenance: notes the user scribbled stay `source: human` (finalization is editorial, not authorship) — pass `source: "human"` to `add`
+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.
 
@@ -109,3 +116,30 @@ The scan is opt-in and never runs on its own. Suggest it when the user asks why
 
 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
+```
+
+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.
+
+See [references/link-repair.md](references/link-repair.md) for the full rules, guarantees, and when to run each.

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

@@ -0,0 +1,90 @@
+# Link repair — keeping the vault connected
+
+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
+
+```jsonc
+weave_note { "action": "links" }              // read-only report
+weave_note { "action": "links", "fix": true } // apply the 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.**
+
+## What a repair does and does not do
+
+- 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.
+
+## Renames repair themselves
+
+`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.
+
+## Finding connections that were never made
+
+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`:
+
+```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", "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.
+
+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.

package/src/core/cache/workspace.ts

@@ -29,7 +29,7 @@
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { gitSpawnCount } from "../git";
 import { NOTES_DIR } from "../paths";
-import { buildGraph, DEFAULT_MAX_NOTES, type BuildGraphInput } from "../graph/build";
+import { buildGraph, type BuildGraphInput } from "../graph/build";
 import type { GraphModel } from "../graph/model";
 import { readRepositorySide } from "../graph/current";
 import { withMutationQueue } from "../mutex";
@@ -41,16 +41,14 @@ import type { HtmlArtifact, Note } from "../types";
  *
  * The two travel together because a caller deriving anything per-note — the
  * tag index (§4.3) is the motivating case — must use *the same* list the
- * graph used, including the `DEFAULT_MAX_NOTES` truncation. Reading the notes
- * from a second call would let the cap fall between them and produce a tag
- * pointing at a slug the graph has no node for.
+ * graph used. Reading the notes from a second call could race a vault change
+ * and produce a tag pointing at a slug the graph has no node for.
  */
 export interface WorkspaceSnapshot {
   model: GraphModel;
   /**
-   * Exactly the notes `buildGraph` saw: newest-updated first and already
-   * truncated to the cap. Frozen — this is the cache's own array and a
-   * caller mutating it would corrupt the next build.
+   * Exactly the notes `buildGraph` saw, newest-updated first. Frozen — this
+   * is the cache's own array and a caller mutating it would corrupt the next build.
    */
   notes: readonly Note[];
 }
@@ -383,10 +381,6 @@ export class WorkspaceCache {
         return this.lastSnapshot;
       }
 
-      // Truncated once, here, and then handed to *both* the builder and the
-      // snapshot — so a caller deriving per-note data cannot see a note the
-      // graph has no node for (§4.3).
-      const kept = notes.slice(0, DEFAULT_MAX_NOTES);
       const input: BuildGraphInput = {
         vault: {
           root: this.vaultRoot,
@@ -395,7 +389,7 @@ export class WorkspaceCache {
           ...(this.folders.length > 0 ? { folders: this.folders } : {}),
           ...(this.artifactCount > 0 ? { artifactCount: this.artifactCount } : {}),
         },
-        notes: kept,
+        notes,
         artifacts: refreshed.artifacts,
         repository: repo?.repository ?? null,
       };
@@ -405,7 +399,7 @@ export class WorkspaceCache {
       this.builtAt = this.now().toISOString();
       const snapshot: WorkspaceSnapshot = {
         model: buildGraph(input),
-        notes: Object.freeze(kept),
+        notes: Object.freeze(notes),
       };
       this.lastSnapshot = snapshot;
       return snapshot;

package/src/core/graph/build.ts

@@ -15,9 +15,6 @@ import type { EdgeKind, GraphEdge, GraphModel, GraphNode } from "./model";
 import { buildPathIndex, resolveMentions, type PathIndex } from "./mentions";
 import { extractWikilinks } from "./wikilinks";
 
-/** Hard cap on note nodes so a large vault cannot overwhelm the viewer. */
-export const DEFAULT_MAX_NOTES = 500;
-
 export interface BuildGraphInput {
   vault: VaultStatus;
   /** Full notes including bodies (for wiki-link extraction). */
@@ -118,15 +115,11 @@ function parseRemote(raw: string): { label: string; url: string } {
 
 function buildVaultSide(
   input: BuildGraphInput,
-  maxNotes: number,
   nodes: GraphNode[],
   edges: GraphEdge[],
   danglingLinks: Record<string, string[]>,
   paths: PathIndex,
-): string[] {
-  const truncated = input.notes.length > maxNotes;
-  const kept = input.notes.slice(0, maxNotes);
-
+): void {
   const vaultDetail: Record<string, string> = {
     root: input.vault.root,
     notes: String(input.vault.noteCount),
@@ -135,12 +128,9 @@ function buildVaultSide(
   if ((input.vault.artifactCount ?? artifacts.length) > 0) {
     vaultDetail.artifacts = String(input.vault.artifactCount ?? artifacts.length);
   }
-  if (truncated) {
-    vaultDetail.warning = `Graph shows the ${maxNotes} most recent notes — the vault holds ${input.vault.noteCount}. Wiki-links to older notes are omitted.`;
-  }
   nodes.push({ id: "vault", kind: "vault", label: "Vault", provenance: null, detail: vaultDetail });
 
-  const keptSlugs = new Set(kept.map((n) => n.slug));
+  const allSlugs = new Set(input.notes.map((n) => n.slug));
   const artifactSlugs = new Set(artifacts.map((a) => a.slug));
   const artifactLinks = new Map<string, number>();
 
@@ -153,23 +143,17 @@ function buildVaultSide(
   const noteDirs = [
     ...new Set([
       ...(input.vault.folders ?? []),
-      ...kept.map((n) => n.slug.split("/").slice(0, -1).join("/")),
+      ...input.notes.map((n) => n.slug.split("/").slice(0, -1).join("/")),
       ...artifacts.map((a) => a.slug.split("/").slice(0, -1).join("/")),
     ]),
   ]
     .filter((d) => d.length > 0)
     .sort();
-  const notesIn = (dir: string): number => kept.filter((n) => n.slug.startsWith(`${dir}/`)).length;
-  const totalNotesIn = (dir: string): number => input.notes.filter((n) => n.slug.startsWith(`${dir}/`)).length;
+  const notesIn = (dir: string): number => input.notes.filter((n) => n.slug.startsWith(`${dir}/`)).length;
   for (const dir of noteDirs) {
     const id = `vfolder:${dir}`;
     folderIds.set(dir, id);
-    const keptCount = notesIn(dir);
-    const totalCount = totalNotesIn(dir);
-    const folderDetail: Record<string, string> = { path: dir, notes: String(keptCount) };
-    if (totalCount > keptCount) {
-      folderDetail.warning = `${totalCount - keptCount} older note(s) in this folder omitted by note limit`;
-    }
+    const folderDetail: Record<string, string> = { path: dir, notes: String(notesIn(dir)) };
     nodes.push({
       id,
       kind: "module",
@@ -186,9 +170,9 @@ function buildVaultSide(
     return (dir.length > 0 && folderIds.get(dir)) || "vault";
   };
 
-  for (const note of kept) {
+  for (const note of input.notes) {
     const links = extractWikilinks(note.body);
-    const resolved = links.filter((slug) => keptSlugs.has(slug));
+    const resolved = links.filter((slug) => allSlugs.has(slug));
     const detail: Record<string, string> = {
       slug: note.slug,
       source: note.source,
@@ -198,7 +182,7 @@ function buildVaultSide(
     // The names, not just the count (§4.2). `detail` keeps carrying the count
     // because it is what the TUI's side panel prints; the structured targets
     // go on the model, where a UI can turn them into ghost nodes.
-    const dangling = links.filter((slug) => !keptSlugs.has(slug) && !artifactSlugs.has(slug));
+    const dangling = links.filter((slug) => !allSlugs.has(slug) && !artifactSlugs.has(slug));
     if (dangling.length > 0) {
       detail["dangling links"] = String(dangling.length);
       danglingLinks[note.slug] = dangling;
@@ -238,7 +222,6 @@ function buildVaultSide(
     nodes.push({ id: `artifact:${artifact.slug}`, kind: "file", label: artifact.title, provenance: null, detail });
     edges.push({ source: parent, target: `artifact:${artifact.slug}`, kind: "contains" });
   }
-  return [...keptSlugs];
 }
 
 function buildRepositorySide(
@@ -355,12 +338,8 @@ function buildRepositorySide(
   }
 }
 
-/**
- * Build the graph model for the viewer. Notes are capped at `maxNotes`
- * (docs/design.md §11); the vault node carries a warning when truncated.
- */
-export function buildGraph(input: BuildGraphInput, options: { maxNotes?: number } = {}): GraphModel {
-  const maxNotes = options.maxNotes ?? DEFAULT_MAX_NOTES;
+/** Build the complete graph model for the viewer. */
+export function buildGraph(input: BuildGraphInput): GraphModel {
   const nodes: GraphNode[] = [];
   const edges: GraphEdge[] = [];
   const danglingLinks: Record<string, string[]> = {};
@@ -372,7 +351,7 @@ export function buildGraph(input: BuildGraphInput, options: { maxNotes?: number
   const paths = input.repository === null
     ? (new Map<string, string>() as PathIndex)
     : buildPathIndex(input.repository.index.structure);
-  buildVaultSide(input, maxNotes, nodes, edges, danglingLinks, paths);
+  buildVaultSide(input, nodes, edges, danglingLinks, paths);
   if (input.repository !== null) {
     buildRepositorySide(input.repository, input.summaries, nodes, edges);
   }
@@ -382,9 +361,8 @@ export function buildGraph(input: BuildGraphInput, options: { maxNotes?: number
     nodes,
     edges,
     danglingLinks,
-    // The same slice the vault side kept, so the digest describes exactly
-    // the notes that have nodes. Slug-ordered inside, hence order-stable.
-    contentDigest: noteContentDigest(input.notes.slice(0, maxNotes)),
+    // Slug-ordered inside, hence order-stable.
+    contentDigest: noteContentDigest(input.notes),
   };
 }
 

package/src/core/graph/current.ts

@@ -19,7 +19,7 @@ import { assessStaleness, readRepoIndex } from "../repoIndex";
 import { readSummaryMap } from "../summaries";
 import type { Note } from "../types";
 import { getNote, readVault, resolveNotePath } from "../vault";
-import { buildGraph, DEFAULT_MAX_NOTES, type BuildGraphInput } from "./build";
+import { buildGraph, type BuildGraphInput } from "./build";
 import type { GraphModel } from "./model";
 
 /** A note read for the viewers (read-only; never cached). Mirrors the vault `Note` shape. */
@@ -91,9 +91,8 @@ export async function readRepositorySide(
 
 /**
  * Assemble the fresh graph from disk. Called on every viewer fetch
- * (no caching). Reads the vault (capped at
- * DEFAULT_MAX_NOTES) and, when cwd is an indexed git repository, the repo
- * index + deep-scan summary sidecars. Degrades to a vault-only graph when
+ * (no caching). Reads the complete vault and, when cwd is an indexed git
+ * repository, the repo index + deep-scan summary sidecars. Degrades to a vault-only graph when
  * the repo has no index or the index is corrupt.
  *
  * One read per note: `readVault` returns bodies *and* the file count, so the
@@ -111,7 +110,7 @@ export async function buildCurrentGraph(cwd: string, vaultRoot: string = resolve
       ...(folders ? { folders } : {}),
       ...(artifactCount ? { artifactCount } : {}),
     },
-    notes: notes.slice(0, DEFAULT_MAX_NOTES),
+    notes,
     ...(artifacts ? { artifacts } : {}),
     repository: null,
   };

package/src/core/index.ts

@@ -53,12 +53,30 @@ export {
   moveNote,
   parseHtmlArtifact,
   renameFolder,
+  readVault,
   renameNote,
+  repairVaultLinks,
   resolveHtmlPath,
   resolveNotePath,
   searchNotes,
   upsertNote,
+  type LinkRepairResult,
 } from "./vault";
+export {
+  suggestLinks,
+  type LinkSuggestion,
+  type SuggestOptions,
+  type SuggestionReport,
+} from "./links/similar";
+export {
+  auditLinks,
+  rewriteLinks,
+  scanLinks,
+  type AmbiguousLink,
+  type LinkAudit,
+  type LinkFix,
+  type UnresolvableLink,
+} from "./links/repair";
 export type { HtmlArtifact } from "./types";
 export { withMutationQueue } from "./mutex";
 export { formatDashboard, formatStatusLine, getWorkspaceStatus } from "./workspace";