pi-weave 0.2.4 → 0.3.1

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.

package/src/core/frontmatter.ts

@@ -14,7 +14,7 @@ import { NOTE_SOURCES } from "./types";
  * not the same promise. `parseNoteFile` read five keys and `serializeNote`
  * wrote five keys, so every write through core silently deleted whatever
  * else the file carried — `aliases`, `cssclass`, `publish`, any property an
- * Obsidian user or another tool had added. Reading a note and appending one
+ * external editor or another tool had added. Reading a note and appending one
  * line destroyed the rest of its metadata (weave-workspace §11 P5).
  *
  * The fix is *not* a fuller YAML parser. A vault is plain text a human edits,
@@ -46,8 +46,8 @@ import { NOTE_SOURCES } from "./types";
  * change rather than a silent one. See {@link isDefaulted}.
  *
  * **An owned key whose on-disk syntax this subset cannot represent is
- * frozen**: carried verbatim, and not re-rendered or duplicated. Obsidian's
- * property editor writes tags as a YAML block list —
+ * frozen**: carried verbatim, and not re-rendered or duplicated. A property
+ * editor may write tags as a YAML block list —
  *
  * ```yaml
  * tags:

package/src/core/graph/model.ts

@@ -64,8 +64,8 @@ export interface GraphModel {
    * slug → wiki-link targets that resolved to no note in the graph
    * (weave-workspace §4.2).
    *
-   * A `[[target]]` that matches nothing is not an error — it is Obsidian's
-   * ghost node, the affordance that offers to create the missing note. The
+   * A `[[target]]` that matches nothing is not an error — it is a ghost node,
+   * the affordance that offers to create the missing note. The
    * builder used to count these and throw the names away, leaving
    * `detail["dangling links"] = "3"` as the only trace; a display string is
    * not something a UI can navigate.

package/src/core/graph/wikilinks.ts

@@ -1,5 +1,5 @@
 /**
- * Obsidian-compatible [[wiki-link]] extraction from note bodies.
+ * Wiki-link extraction from note bodies.
  * Pure module used by graph construction and viewer view-models.
  */
 

package/src/core/index.ts

@@ -13,11 +13,20 @@ export {
   summarizeIndex,
   writeRepoIndex,
 } from "./repoIndex";
-export { runDeepScan, type DeepScanOptions, type DeepScanResult, type SummarizeFn } from "./summaries";
+export {
+  DEEP_SCAN_SYSTEM_PROMPT,
+  formatDeepScanResult,
+  hashContent,
+  runDeepScan,
+  type DeepScanOptions,
+  type DeepScanResult,
+  type SummarizeFn,
+} from "./summaries";
 export {
   DEFAULT_SESSIONS_ROOT,
   SESSIONS_ENV_VAR,
   deriveSessionTitle,
+  formatSessionScanResult,
   listSessionFiles,
   migrateLegacySessionNotes,
   parseSessionDigest,
@@ -27,6 +36,8 @@ export {
   renderSessionDigest,
   resolveSessionsRoot,
   runSessionScan,
+  runSessionDigestScan,
+  SESSION_SCAN_SYSTEM_PROMPT,
   sessionHasContent,
   sessionNoteBody,
   sessionNoteFields,
@@ -34,6 +45,7 @@ export {
   writeSessionNote,
   type SessionChain,
   type SessionDigest,
+  type SessionDigestScanOptions,
   type SessionScanOptions,
   type SessionScanResult,
 } from "./sessions";
@@ -84,6 +96,18 @@ export type { HtmlArtifact } from "./types";
 export { withMutationQueue } from "./mutex";
 export { formatDashboard, formatStatusLine, getWorkspaceStatus } from "./workspace";
 export { WorkspaceCache } from "./cache/workspace";
+export {
+  executeNoteAction,
+  WEAVE_NOTE_DESCRIPTION,
+  type NoteActionInput,
+  type NoteActionResult,
+} from "./noteAction";
+export {
+  executeRepoAction,
+  WEAVE_REPO_DESCRIPTION,
+  type RepoActionInput,
+  type RepoActionResult,
+} from "./repoAction";
 export {
   buildCurrentGraph,
   readNoteForView,

package/src/core/noteAction.ts

@@ -0,0 +1,343 @@
+import { join } from "node:path";
+import {
+  addNote,
+  appendToNote,
+  extractRawTail,
+  finalizeNote,
+  formatNote,
+  getNote,
+  listNotes,
+  readVault,
+  repairVaultLinks,
+  resolveNotePath,
+  searchNotes,
+  type LinkRepairResult,
+} from "./vault";
+import { relatedNotes, suggestLinks, type RelatedNote, type SuggestionReport } from "./links/similar";
+import { NOTES_DIR, resolveVaultRoot } from "./paths";
+import { withMutationQueue } from "./mutex";
+import type { Note, NoteSearchHit } from "./types";
+
+export const WEAVE_NOTE_DESCRIPTION =
+  "Read and write notes in the pi-weave vault — a persistent, human-readable knowledge base " +
+  "of Markdown notes. Actions: list (all notes — avoid on large vaults, prefer search), get (one note by slug), add (new note), " +
+  "append (extend a note; raw=true appends verbatim dictation into the ## Raw tail), " +
+  "finalize (restructure a note above its raw tail), search (ranked slug/title/tags/body matches plus linked, tagged, and lexically related notes; returns the full note when one result or one exact identity resolves), " +
+  "links (audit stale [[wiki-links]]; fix=true repairs the unambiguous ones), " +
+  "suggest (rank unlinked notes that share distinctive vocabulary; reports only, never writes). " +
+  "Use it to remember decisions, facts, and user preferences across sessions.";
+
+export interface NoteActionInput {
+  action: "list" | "get" | "add" | "append" | "finalize" | "search" | "links" | "suggest";
+  title?: string;
+  text?: string;
+  tags?: string[];
+  slug?: string;
+  raw?: boolean;
+  source?: "human" | "agent";
+  query?: string;
+  fix?: boolean;
+  limit?: number;
+}
+
+export interface NoteActionResult {
+  text: string;
+  details: Record<string, unknown>;
+}
+
+const LINK_REPORT_CAP = 20;
+const LIST_CAP = 50;
+const SEARCH_REPORT_CAP = 10;
+const RELATED_REPORT_CAP = 5;
+const COMPLETE_BODY_CAP = 2_000;
+const COMPLETE_BODY_RESULTS = 3;
+
+function capped<T>(items: readonly T[], render: (item: T) => string): string[] {
+  const lines = items.slice(0, LINK_REPORT_CAP).map(render);
+  if (items.length > LINK_REPORT_CAP) lines.push(`  … and ${items.length - LINK_REPORT_CAP} more`);
+  return lines;
+}
+
+function formatSuggestions(report: SuggestionReport, focus: string | undefined): string {
+  if (report.suggestions.length === 0) {
+    return focus === undefined
+      ? `No unlinked notes share enough distinctive vocabulary to suggest a connection (${report.considered} note(s) considered).`
+      : `Nothing unlinked looks related to '${focus}' (${report.considered} note(s) considered).`;
+  }
+  const head = focus === undefined
+    ? `${report.suggestions.length} suggested connection(s) across ${report.considered} note(s):`
+    : `${report.suggestions.length} note(s) look related to '${focus}':`;
+  const rows = report.suggestions.map((suggestion) => {
+    const pair = focus === undefined
+      ? `${suggestion.a} ↔ ${suggestion.b}`
+      : suggestion.a === focus ? suggestion.b : suggestion.a;
+    return `  ${suggestion.score.toFixed(3)}  ${pair}\n         shared: ${suggestion.shared.join(", ")}`;
+  });
+  return [
+    head,
+    ...rows,
+    "",
+    "These are suggestions, not links — nothing was written. Add a [[wikilink]] to any pair worth keeping.",
+  ].join("\n");
+}
+
+function searchReasons(hit: NoteSearchHit, query: string): string[] {
+  const q = query.trim().toLowerCase();
+  const title = hit.summary.title.toLowerCase();
+  const slug = hit.summary.slug.toLowerCase();
+  const reasons: string[] = [];
+  if (title === q) reasons.push("exact title");
+  else if (slug === q) reasons.push("exact slug");
+  else if (title.includes(q)) reasons.push("title");
+  else if (slug.includes(q)) reasons.push("slug");
+  const tags = hit.summary.tags.filter((tag) => tag.toLowerCase().includes(q));
+  if (tags.length > 0) reasons.push(`tags: ${tags.join(", ")}`);
+  if (hit.snippet.toLowerCase().includes(q)) reasons.push("body");
+  if (reasons.length === 0) {
+    const haystack = `${title} ${slug} ${hit.summary.tags.join(" ").toLowerCase()} ${hit.snippet.toLowerCase()}`;
+    const terms = [...new Set(q.match(/[\p{L}\p{N}_-]{2,}/gu) ?? [])].filter((term) => haystack.includes(term));
+    if (terms.length > 0) reasons.push(`query terms: ${terms.join(", ")}`);
+  }
+  return reasons;
+}
+
+function searchContent(note: Note | undefined, snippet: string, complete: boolean): string {
+  const body = note?.body.trim() ?? "";
+  if (complete && body.length <= COMPLETE_BODY_CAP) return `[complete body]\n  ${body}`;
+  return `[excerpt${body.length > COMPLETE_BODY_CAP ? "; use get for the full note" : ""}]\n  ${snippet}`;
+}
+
+function formatSearchHits(
+  hits: readonly NoteSearchHit[],
+  query: string,
+  relations: ReadonlyMap<string, RelatedNote>,
+  notes: ReadonlyMap<string, Note>,
+): string {
+  const shown = hits.slice(0, SEARCH_REPORT_CAP);
+  const lines = shown.map((hit, index) => {
+    const tags = hit.summary.tags.length > 0 ? `; tags: ${hit.summary.tags.join(", ")}` : "";
+    const relation = relations.get(hit.summary.slug);
+    const connected = relation ? `; connected: ${relation.reasons.join("; ")}` : "";
+    const content = searchContent(notes.get(hit.summary.slug), hit.snippet, index < COMPLETE_BODY_RESULTS);
+    return `- ${hit.summary.slug}: ${hit.summary.title}\n  matched: ${searchReasons(hit, query).join(", ")}${connected}; source: ${hit.summary.source}; updated: ${hit.summary.updated}${tags}\n  ${content}`;
+  });
+  if (hits.length > shown.length) lines.push(`… and ${hits.length - shown.length} more direct match(es).`);
+  return lines.join("\n");
+}
+
+function preview(body: string): string {
+  const flat = body.trim().replace(/\s+/g, " ");
+  return flat.length > 180 ? `${flat.slice(0, 180)}…` : flat;
+}
+
+function formatRelatedNotes(
+  relations: readonly RelatedNote[],
+  notes: ReadonlyMap<string, Note>,
+  direct: ReadonlySet<string>,
+  anchor: Note,
+): string {
+  const shown = relations
+    .filter((relation) => !direct.has(relation.slug))
+    .flatMap((relation) => {
+      const note = notes.get(relation.slug);
+      return note ? [{ relation, note }] : [];
+    })
+    .slice(0, RELATED_REPORT_CAP);
+  if (shown.length === 0) return "";
+  const lines = shown.map(({ relation, note }, index) => {
+    const tags = note.tags.length > 0 ? `; tags: ${note.tags.join(", ")}` : "";
+    const content = searchContent(note, preview(note.body), index < COMPLETE_BODY_RESULTS);
+    return `- ${note.slug}: ${note.title}\n  connected: ${relation.reasons.join("; ")}; source: ${note.source}; updated: ${note.updated}${tags}\n  ${content}`;
+  });
+  return `Connected notes to '${anchor.title}' (discovery context only — not direct query matches or evidence about the query):\n${lines.join("\n")}`;
+}
+
+function formatLinkReport(result: LinkRepairResult, applied: boolean): string {
+  const { audit } = result;
+  const lines = [`${audit.total} wiki-link(s): ${audit.resolved} resolved, ${audit.total - audit.resolved} stale.`];
+  if (applied) {
+    lines.push(
+      result.applied.length === 0
+        ? "Nothing to repair automatically."
+        : `Repaired ${result.applied.length} link(s) across ${result.notes.length} note(s):`,
+      ...capped(result.applied, (fix) => `  ${fix.slug}: [[${fix.from}]] → [[${fix.to}]] (${fix.rule})`),
+    );
+  } else if (audit.fixable.length > 0) {
+    lines.push(
+      `${audit.fixable.length} auto-fixable (re-run with fix: true):`,
+      ...capped(audit.fixable, (fix) => `  ${fix.slug}: [[${fix.from}]] → [[${fix.to}]] (${fix.rule})`),
+    );
+  }
+  if (audit.ambiguous.length > 0) {
+    lines.push(
+      `${audit.ambiguous.length} ambiguous link(s) (several candidates — pick one and edit the note):`,
+      ...capped(audit.ambiguous, (link) => `  ${link.slug}: [[${link.target}]] → ${link.candidates.join(" | ")}`),
+    );
+  }
+  if (audit.unresolvable.length > 0) {
+    lines.push(
+      `${audit.unresolvable.length} unresolvable target(s) (no such note — write it or drop the link):`,
+      ...capped(audit.unresolvable, (link) => `  [[${link.target}]] ← ${link.notes.join(", ")}`),
+    );
+  }
+  if (audit.fixable.length === 0 && audit.ambiguous.length === 0 && audit.unresolvable.length === 0) {
+    lines.push("Every link resolves.");
+  }
+  return lines.join("\n");
+}
+
+export async function executeNoteAction(
+  params: NoteActionInput,
+  vault = resolveVaultRoot(),
+  now: () => Date = () => new Date(),
+): Promise<NoteActionResult> {
+  switch (params.action) {
+    case "list": {
+      const notes = await listNotes(vault);
+      if (notes.length === 0) return { text: `The vault at ${vault} has no notes yet.`, details: { action: "list", notes: [] } };
+      const shown = notes.slice(0, LIST_CAP);
+      const lines = shown.map(
+        (note) => `- ${note.slug}: ${note.title}${note.tags.length > 0 ? ` [${note.tags.join(", ")}]` : ""} (updated ${note.updated}, source: ${note.source})`,
+      );
+      if (notes.length > shown.length) {
+        lines.push(`… and ${notes.length - shown.length} more (newest ${shown.length} shown) — use action=search to find a specific note.`);
+      }
+      return { text: `${notes.length} note(s) in ${vault}:\n${lines.join("\n")}`, details: { action: "list", notes } };
+    }
+
+    case "get": {
+      if (!params.slug) throw new Error("weave_note(get) requires 'slug'");
+      const note = await getNote(vault, params.slug);
+      return note
+        ? { text: formatNote(note), details: { action: "get", found: true, note } }
+        : { text: `No note found with slug '${params.slug}'.`, details: { action: "get", found: false } };
+    }
+
+    case "add": {
+      if (!params.title) throw new Error("weave_note(add) requires 'title'");
+      if (!params.text) throw new Error("weave_note(add) requires 'text'");
+      const note = await withMutationQueue(join(vault, NOTES_DIR), () =>
+        addNote(vault, {
+          title: params.title!,
+          body: params.text!,
+          ...(params.tags ? { tags: params.tags } : {}),
+          ...(params.source ? { source: params.source } : {}),
+        }),
+      );
+      return { text: `Note created: ${note.slug} (${vault})`, details: { action: "add", note } };
+    }
+
+    case "append": {
+      if (!params.slug) throw new Error("weave_note(append) requires 'slug'");
+      if (!params.text) throw new Error("weave_note(append) requires 'text'");
+      const path = resolveNotePath(vault, params.slug);
+      if (!path) {
+        return {
+          text: `Invalid note slug '${params.slug}' — notes are flat files inside the vault (no path separators or '..').`,
+          details: { action: "append", found: false },
+        };
+      }
+      const note = await withMutationQueue(path, () =>
+        appendToNote(vault, params.slug!, params.text!, now(), params.raw ? { raw: true } : {}),
+      );
+      if (!note) return { text: `No note found with slug '${params.slug}'.`, details: { action: "append", found: false } };
+      return {
+        text: params.raw
+          ? `Appended verbatim to the ## Raw tail of ${note.slug} (updated ${note.updated}).`
+          : `Appended to ${note.slug} (updated ${note.updated}).`,
+        details: { action: "append", found: true, note },
+      };
+    }
+
+    case "finalize": {
+      if (!params.slug) throw new Error("weave_note(finalize) requires 'slug'");
+      if (!params.text) throw new Error("weave_note(finalize) requires 'text'");
+      const path = resolveNotePath(vault, params.slug);
+      if (!path) {
+        return {
+          text: `Invalid note slug '${params.slug}' — notes are flat files inside the vault (no path separators or '..').`,
+          details: { action: "finalize", found: false },
+        };
+      }
+      const note = await withMutationQueue(path, () => finalizeNote(vault, params.slug!, { body: params.text! }));
+      if (!note) return { text: `No note found with slug '${params.slug}'.`, details: { action: "finalize", found: false } };
+      const preserved = extractRawTail(note.body) !== "";
+      return {
+        text: `Finalized ${note.slug} (updated ${note.updated}). ${preserved ? "Raw tail preserved beneath the structured body." : "Note body was empty — nothing to preserve."}`,
+        details: { action: "finalize", found: true, note },
+      };
+    }
+
+    case "search": {
+      if (!params.query) throw new Error("weave_note(search) requires 'query'");
+      const hits = await searchNotes(vault, params.query);
+      if (hits.length === 0) return { text: `No notes matched '${params.query}'.`, details: { action: "search", hits: [] } };
+      const { notes } = await readVault(vault);
+      const bySlug = new Map(notes.map((note) => [note.slug, note]));
+      const direct = new Set(hits.map((hit) => hit.summary.slug));
+      const anchor = bySlug.get(hits[0]!.summary.slug);
+      const related = anchor ? relatedNotes({ notes }, anchor.slug) : [];
+      const relatedBySlug = new Map(related.map((relation) => [relation.slug, relation]));
+      const connected = anchor ? formatRelatedNotes(related, bySlug, direct, anchor) : "";
+      const query = params.query.trim().toLowerCase();
+      const exact = hits.filter((hit) =>
+        hit.summary.title.trim().toLowerCase() === query || hit.summary.slug.toLowerCase() === query
+      );
+      const resolved = hits.length === 1 ? hits[0] : exact.length === 1 ? exact[0] : undefined;
+      if (resolved) {
+        const note = bySlug.get(resolved.summary.slug);
+        if (note) {
+          const others = hits.filter((hit) => hit.summary.slug !== note.slug);
+          const otherMatches = others.length > 0
+            ? `Other direct matches (${others.length}):\n${formatSearchHits(others, params.query, relatedBySlug, bySlug)}`
+            : "";
+          return {
+            text: [formatNote(note).trimEnd(), otherMatches, connected].filter(Boolean).join("\n\n") + "\n",
+            details: { action: "search", hits, resolved: note, related },
+          };
+        }
+      }
+      return {
+        text: [
+          `${hits.length} direct match(es) for '${params.query}', strongest first:\n${formatSearchHits(hits, params.query, relatedBySlug, bySlug)}`,
+          connected,
+        ].filter(Boolean).join("\n\n"),
+        details: { action: "search", hits, related },
+      };
+    }
+
+    case "suggest": {
+      const { notes } = await readVault(vault);
+      const report = suggestLinks(
+        { notes },
+        {
+          ...(params.slug ? { slug: params.slug } : {}),
+          ...(params.limit !== undefined ? { limit: params.limit } : {}),
+        },
+      );
+      return {
+        text: formatSuggestions(report, params.slug),
+        details: { action: "suggest", considered: report.considered, suggestions: report.suggestions },
+      };
+    }
+
+    case "links": {
+      const apply = params.fix === true;
+      const result = await repairVaultLinks(vault, apply ? { apply: true } : {});
+      return {
+        text: formatLinkReport(result, apply),
+        details: {
+          action: "links",
+          fixed: apply,
+          total: result.audit.total,
+          resolved: result.audit.resolved,
+          fixable: result.audit.fixable,
+          ambiguous: result.audit.ambiguous,
+          unresolvable: result.audit.unresolvable,
+          applied: result.applied,
+          notes: result.notes,
+        },
+      };
+    }
+  }
+}

package/src/core/repoAction.ts

@@ -0,0 +1,84 @@
+import {
+  assessStaleness,
+  buildRepoIndex,
+  readRepoIndex,
+  summarizeIndex,
+  writeRepoIndex,
+} from "./repoIndex";
+import { findGitRoot } from "./git";
+import { repoIndexDir } from "./paths";
+
+export const WEAVE_REPO_DESCRIPTION =
+  "Explore the current git repository through its pi-weave knowledge index (.okf). " +
+  "Actions: status (index freshness vs git state), scan (build/refresh the index), " +
+  "overview (read the indexed structure: languages, packages, modules, entry points). " +
+  "The index is derived and rebuildable; scanning is always safe.";
+
+export interface RepoActionInput {
+  action: "status" | "scan" | "overview";
+}
+
+export interface RepoActionResult {
+  text: string;
+  details: Record<string, unknown>;
+}
+
+export async function executeRepoAction(
+  params: RepoActionInput,
+  cwd: string,
+  onProgress?: (text: string) => void | Promise<void>,
+): Promise<RepoActionResult> {
+  const root = await findGitRoot(cwd);
+  if (!root) {
+    return {
+      text: "Not inside a git repository — repository knowledge is unavailable here.",
+      details: { action: params.action, inRepo: false },
+    };
+  }
+
+  switch (params.action) {
+    case "status": {
+      const staleness = await assessStaleness(root);
+      const index = staleness.state !== "missing" ? await readRepoIndex(root) : null;
+      const lines = [`Index state: ${staleness.state}`];
+      for (const reason of staleness.reasons) lines.push(`- ${reason}`);
+      if (index) lines.push(`Indexed at: ${index.updated} by ${index.generator}`);
+      return {
+        text: `Repository ${root}\n${lines.join("\n")}`,
+        details: { action: "status", inRepo: true, staleness, indexed: index !== null },
+      };
+    }
+
+    case "scan": {
+      await onProgress?.(`Scanning ${root}…`);
+      const index = await buildRepoIndex(root);
+      if (!index) {
+        return {
+          text: "Cannot build index: the repository has no commits yet.",
+          details: { action: "scan", inRepo: true, scanned: false },
+        };
+      }
+      const dir = await writeRepoIndex(root, index);
+      return {
+        text: `Knowledge index written to ${dir}\n\n${summarizeIndex(index).join("\n")}`,
+        details: { action: "scan", inRepo: true, scanned: true, index },
+      };
+    }
+
+    case "overview": {
+      const index = await readRepoIndex(root);
+      if (!index) {
+        return {
+          text: `No knowledge index at ${repoIndexDir(root)} yet. Use action=scan to build one.`,
+          details: { action: "overview", inRepo: true, indexed: false },
+        };
+      }
+      const staleness = await assessStaleness(root);
+      const header = staleness.state === "fresh" ? "" : `⚠ index is ${staleness.state} (consider rescanning)\n`;
+      return {
+        text: header + summarizeIndex(index).join("\n"),
+        details: { action: "overview", inRepo: true, indexed: true, staleness, index },
+      };
+    }
+  }
+}