pi-weave 0.1.1

package/src/core/workspace.ts

@@ -0,0 +1,85 @@
+import { findGitRoot } from "./git";
+import { assessStaleness, readRepoIndex } from "./repoIndex";
+import { readSummaries } from "./summaries";
+import { basename } from "node:path";
+import { resolveVaultRoot } from "./paths";
+import { noteCount, vaultExists } from "./vault";
+import type { WorkspaceStatus } from "./types";
+
+/**
+ * The combined knowledge-workspace view: vault + repository (design §5/§17).
+ * This is what session_start, the /weave command, and future adapters read
+ * to decide what knowledge is available in the current directory.
+ */
+
+export interface WorkspaceOptions {
+  /** Override the vault root (defaults to PI_WEAVE_VAULT or ~/.okf). */
+  vaultRoot?: string;
+}
+
+export async function getWorkspaceStatus(cwd: string, options: WorkspaceOptions = {}): Promise<WorkspaceStatus> {
+  const vaultRoot = options.vaultRoot ?? resolveVaultRoot();
+
+  const [exists, count, repoRoot] = await Promise.all([
+    vaultExists(vaultRoot),
+    noteCount(vaultRoot),
+    findGitRoot(cwd),
+  ]);
+
+  const status: WorkspaceStatus = {
+    cwd,
+    vault: { root: vaultRoot, exists, noteCount: count },
+    repository: null,
+  };
+
+  if (!repoRoot) return status;
+
+  const index = await readRepoIndex(repoRoot);
+  const staleness = await assessStaleness(repoRoot);
+  status.repository = {
+    root: repoRoot,
+    name: index?.identity.name ?? basename(repoRoot),
+    indexed: index !== null,
+    staleness,
+    summaryCount: index === null ? 0 : (await readSummaries(repoRoot)).length,
+  };
+  return status;
+}
+
+/** One-line status string for footers/status bars. */
+export function formatStatusLine(status: WorkspaceStatus): string {
+  const vault = `vault:${status.vault.noteCount}`;
+  if (!status.repository) return `🧵 ${vault}`;
+  if (!status.repository.indexed) return `🧵 ${vault} · repo:unindexed`;
+  const mark = status.repository.staleness.state === "fresh" ? "ok" : status.repository.staleness.state;
+  return `🧵 ${vault} · ${status.repository.name}:${mark}`;
+}
+
+/** Multi-line dashboard used by the /weave command and notifications. */
+export function formatDashboard(status: WorkspaceStatus): string {
+  const lines: string[] = [];
+  lines.push(`Vault (${status.vault.root}):`);
+  lines.push(
+    status.vault.exists
+      ? `  ${status.vault.noteCount} note(s)`
+      : "  not initialized — add a note to create it",
+  );
+  if (!status.repository) {
+    lines.push("Repository: none (not inside a git repository)");
+    return lines.join("\n");
+  }
+  const repo = status.repository;
+  lines.push(`Repository (${repo.name} @ ${repo.root}):`);
+  if (!repo.indexed) {
+    lines.push("  not indexed — run a repository scan or ask pi to explore");
+    return lines.join("\n");
+  }
+  lines.push(`  index: ${repo.staleness.state}`);
+  for (const reason of repo.staleness.reasons) {
+    lines.push(`    - ${reason}`);
+  }
+  if (repo.summaryCount > 0) {
+    lines.push(`  summaries: ${repo.summaryCount} file(s) — run /weave-scan deep to refresh`);
+  }
+  return lines.join("\n");
+}

package/src/pi/index.ts

@@ -0,0 +1,191 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import {
+  buildRepoIndex,
+  findGitRoot,
+  formatDashboard,
+  formatStatusLine,
+  getWorkspaceStatus,
+  summarizeIndex,
+  writeRepoIndex,
+  type WorkspaceStatus,
+} from "../core";
+import { registerNoteTool } from "./tools/noteTool";
+import { registerRepoTool } from "./tools/repoTool";
+import { deepScanRepository, formatDeepScanResult } from "./summarize";
+import { openInBrowser } from "./viewer/browser";
+import { startViewer, type ViewerServer } from "./viewer/server";
+import { runWeaveViewTui } from "./viewer/tui/run";
+
+/**
+ * pi-weave — an agent-native knowledge workspace (docs/design.md):
+ *
+ *  1. Smart notepad with AI skills  → the `weave_note` tool + skills/
+ *  2. Repository exploration        → the `weave_repo` tool building .okf
+ *  3. Humans and agents alike       → plain Markdown / JSON on disk
+ *
+ * All behavior lives in src/core (portable); this file only wires it into pi.
+ */
+export default function piWeave(pi: ExtensionAPI): void {
+  registerNoteTool(pi);
+  registerRepoTool(pi);
+
+  // Session-scoped viewer: lazy start on first /weave-view, never from the
+  // factory (extension rules); idempotent stop on session_shutdown.
+  let viewer: ViewerServer | null = null;
+
+  pi.on("session_shutdown", async () => {
+    const server = viewer;
+    viewer = null;
+    await server?.stop();
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    const status = await getWorkspaceStatus(ctx.cwd);
+    ctx.ui.setStatus("weave", formatStatusLine(status));
+
+    if (!ctx.hasUI) return;
+    const repo = status.repository;
+    if (repo && !repo.indexed) {
+      ctx.ui.notify(
+        "pi-weave: this repository has no knowledge index yet — ask pi to explore it, or run /weave-scan.",
+        "info",
+      );
+    } else if (repo && repo.staleness.state === "stale") {
+      const reason = repo.staleness.reasons[0] ?? "index is stale";
+      ctx.ui.notify(`pi-weave: repository index is stale (${reason}). Run /weave-scan to refresh.`, "warning");
+    }
+  });
+
+  pi.registerCommand("weave", {
+    description: "Show the pi-weave workspace dashboard (vault + repository knowledge)",
+    handler: async (_args, ctx) => {
+      const status = await getWorkspaceStatus(ctx.cwd);
+      ctx.ui.notify(formatDashboard(status), "info");
+    },
+  });
+
+  pi.registerCommand("weave-view", {
+    description: "Open the local knowledge-graph viewer in your browser (vault + repository); '/weave-view tui' explores in-terminal",
+    handler: async (args, ctx) => {
+      const arg = args.trim().toLowerCase();
+      if (arg === "tui") {
+        await runWeaveViewTui(ctx);
+        return;
+      }
+      if (arg !== "") {
+        ctx.ui.notify("usage: /weave-view [tui]", "warning");
+        return;
+      }
+      viewer ??= await startViewer({ cwd: ctx.cwd });
+      ctx.ui.notify(`pi-weave viewer: ${viewer.url} (reads from disk live; refresh the page any time)`, "info");
+      await openInBrowser(pi, ctx, viewer.url);
+    },
+  });
+
+  pi.registerCommand("weave-scan", {
+    description: "Build or refresh the repository knowledge index (.okf); 'deep' also summarizes files with the session model",
+    handler: async (args, ctx) => {
+      const root = await findGitRoot(ctx.cwd);
+      if (!root) {
+        ctx.ui.notify("pi-weave: not inside a git repository.", "warning");
+        return;
+      }
+      const index = await buildRepoIndex(root);
+      if (!index) {
+        ctx.ui.notify("pi-weave: cannot index — the repository has no commits yet.", "warning");
+        return;
+      }
+      await writeRepoIndex(root, index);
+      ctx.ui.notify(`pi-weave: index refreshed\n${summarizeIndex(index).join("\n")}`, "info");
+
+      if (args.trim().toLowerCase() === "deep") {
+        if (inFlightDeepScans.has(root)) {
+          ctx.ui.notify("pi-weave: a deep scan is already running for this repository — run /weave-scan-cancel to stop it.", "warning");
+        } else {
+          // Compute the settled status here (no git-lock contention) and let
+          // the background scan restore it when it finishes.
+          const status = await getWorkspaceStatus(ctx.cwd);
+          startDeepScan(root, ctx, status);
+        }
+        return; // the background scan owns the status line until it settles
+      }
+
+      const status = await getWorkspaceStatus(ctx.cwd);
+      ctx.ui.setStatus("weave", formatStatusLine(status));
+    },
+  });
+
+  pi.registerCommand("weave-scan-cancel", {
+    description: "Cancel an in-flight /weave-scan deep run",
+    handler: async (_args, ctx) => {
+      const root = await findGitRoot(ctx.cwd);
+      const scan = root ? inFlightDeepScans.get(root) : undefined;
+      if (!scan) {
+        ctx.ui.notify("pi-weave: no deep scan is currently running.", "info");
+        return;
+      }
+      scan.controller.abort();
+      ctx.ui.notify("pi-weave: deep scan cancellation requested.", "info");
+    },
+  });
+}
+
+/* ------------------------------------------------------------------ */
+/* In-flight deep scans (background, cancellable)                      */
+/* ------------------------------------------------------------------ */
+
+interface InFlightDeepScan {
+  controller: AbortController;
+  /** Resolves when the background scan settles (done, cancelled, or torn down). */
+  done: Promise<void>;
+}
+
+/** In-flight deep scans keyed by repo root — the /weave-scan-cancel target. */
+const inFlightDeepScans = new Map<string, InFlightDeepScan>();
+
+/** Test seam: resolve when the in-flight deep scan for `root` settles. */
+export async function deepScanDone(root: string): Promise<void | undefined> {
+  const canonical = await findGitRoot(root).catch(() => null);
+  return inFlightDeepScans.get(canonical ?? root)?.done;
+}
+
+/**
+ * Kick off a deep scan in the background so the user keeps control of the
+ * session (a blocking command can't be cancelled in the TUI — Esc only aborts
+ * streaming/bash). Progress is pushed to the status line; completion or
+ * cancellation is reported via a notification. `baseStatus` is the workspace
+ * status captured before the scan and restored when it settles.
+ */
+function startDeepScan(root: string, ctx: ExtensionCommandContext, baseStatus: WorkspaceStatus): void {
+  const controller = new AbortController();
+  const done = (async () => {
+    try {
+      ctx.ui.setStatus("weave", "🧵 deep scan: starting…");
+      const outcome = await deepScanRepository(root, ctx, {
+        onProgress: ({ current, total, path }) => {
+          const pct = total > 0 ? Math.round((current / total) * 100) : 100;
+          ctx.ui.setStatus("weave", `🧵 deep scan: ${current}/${total} (${pct}%) — ${path}`);
+        },
+        signal: controller.signal,
+      });
+      if (controller.signal.aborted) {
+        ctx.ui.notify("pi-weave: deep scan cancelled.", "warning");
+      } else if (outcome.kind === "no-model") {
+        ctx.ui.notify(
+          "pi-weave: deep scan needs an active session model — none configured. Light index only.",
+          "warning",
+        );
+      } else if (outcome.kind === "ok") {
+        ctx.ui.notify(`pi-weave: deep scan complete — ${formatDeepScanResult(outcome.result)}`, "info");
+      }
+    } catch {
+      // session ended or extension torn down — stop quietly
+    } finally {
+      // Restore the settled status before removing the map entry, so a caller
+      // awaiting deepScanDone() observes the settled status line.
+      ctx.ui.setStatus("weave", formatStatusLine(baseStatus));
+      inFlightDeepScans.delete(root);
+    }
+  })();
+  inFlightDeepScans.set(root, { controller, done });
+}

package/src/pi/summarize.ts

@@ -0,0 +1,134 @@
+/**
+ * pi adapter for deep scans: resolves the session's already-configured model
+ * (the codebase-memory-mcp lesson — no extra keys/providers) and drives
+ * pi-ai completion through `ctx.modelRegistry`, which owns auth.
+ *
+ * `createLlmSummarizer` returns null when no model is active (headless
+ * runs without a provider, etc.) — callers fall back to light-only.
+ * `deps.complete` is the test seam: unit tests inject a fake and never
+ * touch a network.
+ */
+
+import {
+  contentText,
+  type Api,
+  type AssistantMessage,
+  type Context,
+  type Model,
+} from "@earendil-works/pi-ai";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { runDeepScan, type DeepScanOptions, type DeepScanResult, type SummarizeFn } from "../core";
+
+export type CompleteFn = (
+  model: Model<Api>,
+  context: Context,
+  options: { maxTokens?: number; signal?: AbortSignal },
+) => Promise<AssistantMessage>;
+
+export interface SummarizerDeps {
+  complete?: CompleteFn;
+}
+
+export interface LlmSummarizer {
+  summarize: SummarizeFn;
+  /** Provenance label recorded in sidecar front matter (e.g. "ollama/kimi-k3:cloud"). */
+  label: string;
+}
+
+const SYSTEM_PROMPT = [
+  "You write terse, navigation-oriented summaries of source files for a codebase index.",
+  "Rules: 1–3 sentences. What the file does, its outward surface (exports/routes/commands),",
+  "anything surprising (globals, side effects, generated sections). No preamble, no headings, no code fences.",
+].join("\n");
+
+const MAX_OUTPUT_TOKENS = 220;
+const REQUEST_TIMEOUT_MS = 30_000;
+
+/** Create the model-backed summarizer, or null when the session has no active model. */
+export function createLlmSummarizer(
+  ctx: Pick<ExtensionContext, "model" | "modelRegistry">,
+  deps: SummarizerDeps = {},
+): LlmSummarizer | null {
+  const model = ctx.model;
+  if (!model) return null;
+  const complete: CompleteFn =
+    deps.complete ?? ((m, c, o) => ctx.modelRegistry.complete(m, c, o));
+  const label = `${model.provider}/${model.id}`;
+  const summarize: SummarizeFn = async ({ path, content }) => {
+    const message = await complete(
+      model,
+      {
+        systemPrompt: SYSTEM_PROMPT,
+        messages: [
+          {
+            role: "user",
+            content: `File: ${path}\n\n\`\`\`\n${content}\n\`\`\``,
+            timestamp: Date.now(),
+          },
+        ],
+      },
+      { maxTokens: MAX_OUTPUT_TOKENS, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) },
+    );
+    const text = contentText(message.content).trim();
+    if (text.length === 0) {
+      throw new Error("model returned an empty summary");
+    }
+    return text;
+  };
+  return { summarize, label };
+}
+
+export type DeepScanOutcome =
+  | { kind: "ok"; result: DeepScanResult }
+  | { kind: "no-model" }
+  | { kind: "not-a-repo" };
+
+type DeepScanTuning = {
+  at?: DeepScanOptions["at"];
+  maxFiles?: DeepScanOptions["maxFiles"];
+  maxFileBytes?: DeepScanOptions["maxFileBytes"];
+  concurrency?: DeepScanOptions["concurrency"];
+  onProgress?: DeepScanOptions["onProgress"];
+  signal?: DeepScanOptions["signal"];
+};
+
+/** Run the deep pass against a repo root using the session model. */
+export async function deepScanRepository(
+  repoRoot: string,
+  ctx: Pick<ExtensionContext, "model" | "modelRegistry">,
+  deps: SummarizerDeps & DeepScanTuning = {},
+): Promise<DeepScanOutcome> {
+  const llm = createLlmSummarizer(ctx, deps);
+  if (!llm) return { kind: "no-model" };
+  // exactOptionalPropertyTypes: only present keys may be spread in.
+  const result = await runDeepScan(repoRoot, {
+    summarize: llm.summarize,
+    model: llm.label,
+    ...(deps.at !== undefined ? { at: deps.at } : {}),
+    ...(deps.maxFiles !== undefined ? { maxFiles: deps.maxFiles } : {}),
+    ...(deps.maxFileBytes !== undefined ? { maxFileBytes: deps.maxFileBytes } : {}),
+    ...(deps.concurrency !== undefined ? { concurrency: deps.concurrency } : {}),
+    ...(deps.onProgress !== undefined ? { onProgress: deps.onProgress } : {}),
+    ...(deps.signal !== undefined ? { signal: deps.signal } : {}),
+  });
+  if (result === null) return { kind: "not-a-repo" };
+  return { kind: "ok", result };
+}
+
+/** One-line human summary of a deep-scan result (for notify output). */
+export function formatDeepScanResult(result: DeepScanResult): string {
+  const parts = [
+    `${result.written} summarized`,
+    `${result.skippedFresh} unchanged`,
+  ];
+  if (result.skippedTooBig > 0) parts.push(`${result.skippedTooBig} skipped (size/type)`);
+  if (result.pruned > 0) parts.push(`${result.pruned} pruned`);
+  let text = `${parts.join(", ")} — ${result.considered} files considered`;
+  if (result.failed.length > 0) {
+    const [failed0] = result.failed;
+    if (failed0) {
+      text += `; ${result.failed.length} failed, first: ${failed0.path}: ${failed0.error}`;
+    }
+  }
+  return text;
+}

package/src/pi/tools/noteTool.ts

@@ -0,0 +1,178 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { join } from "node:path";
+import { Type } from "typebox";
+import {
+  addNote,
+  appendToNote,
+  finalizeNote,
+  formatNote,
+  getNote,
+  listNotes,
+  NOTES_DIR,
+  resolveNotePath,
+  withMutationQueue,
+  resolveVaultRoot,
+  searchNotes,
+} from "../../core";
+
+/**
+ * `weave_note` — the smart-notepad tool (design §1: vault knowledge).
+ *
+ * The LLM uses this to remember decisions, facts, and preferences as plain
+ * Markdown notes that humans can read and edit directly on disk.
+ */
+export function registerNoteTool(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "weave_note",
+    label: "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), get (one note by slug), add (new note), " +
+      "append (extend a note), finalize (restructure a note above its raw tail), search (title/tags/body). " +
+      "Use it to remember decisions, facts, and user preferences across sessions.",
+    promptSnippet: "Remember and retrieve durable knowledge in the pi-weave vault",
+    promptGuidelines: [
+      "Use weave_note to store durable knowledge (decisions, preferences, key facts) that should survive the session, marking source as agent-written knowledge.",
+      "Use weave_note with action=search before answering questions about past decisions, people, or projects.",
+    ],
+    parameters: Type.Object({
+      action: StringEnum(["list", "get", "add", "append", "finalize", "search"] as const),
+      title: Type.Optional(Type.String({ description: "Note title (add)" })),
+      text: Type.Optional(Type.String({ description: "Markdown body (add), addition (append), or restructured body above the raw tail (finalize)" })),
+      tags: Type.Optional(Type.Array(Type.String(), { description: "Tags (add)" })),
+      slug: Type.Optional(Type.String({ description: "Note slug (get, append, finalize)" })),
+      source: Type.Optional(StringEnum(["human", "agent"] as const, { description: "Provenance (add): human for user-scribbled notes, agent for Pi-drafted (default agent)" })),
+      query: Type.Optional(Type.String({ description: "Search query (search)" })),
+    }),
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const vault = resolveVaultRoot();
+
+      switch (params.action) {
+        case "list": {
+          const notes = await listNotes(vault);
+          if (notes.length === 0) {
+            return {
+              content: [{ type: "text", text: `The vault at ${vault} has no notes yet.` }],
+              details: { action: "list", notes: [] },
+            };
+          }
+          const lines = notes.map(
+            (n) => `- ${n.slug}: ${n.title}${n.tags.length > 0 ? ` [${n.tags.join(", ")}]` : ""} (updated ${n.updated}, source: ${n.source})`,
+          );
+          return {
+            content: [{ type: "text", 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);
+          if (!note) {
+            return { content: [{ type: "text", text: `No note found with slug '${params.slug}'.` }], details: { action: "get", found: false } };
+          }
+          return { content: [{ type: "text", text: formatNote(note) }], details: { action: "get", found: true, note } };
+        }
+
+        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 title = params.title;
+          const text = params.text;
+          // Serialized per vault: parallel adds of the same title must not
+          // race the unique-slug check and overwrite each other.
+          const note = await withMutationQueue(join(vault, NOTES_DIR), () =>
+            addNote(vault, {
+              title,
+              body: text,
+              ...(params.tags ? { tags: params.tags } : {}),
+              ...(params.source ? { source: params.source } : {}),
+            }),
+          );
+          return {
+            content: [{ type: "text", 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 slug = params.slug;
+          const text = params.text;
+          const path = resolveNotePath(vault, slug);
+          if (!path) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `Invalid note slug '${slug}' — notes are flat files inside the vault (no path separators or '..').`,
+                },
+              ],
+              details: { action: "append", found: false },
+            };
+          }
+          // Serialized read-modify-write: parallel weave_note appends (and
+          // pi's own file tools) targeting the same note would otherwise
+          // lose each other's additions.
+          const note = await withMutationQueue(path, () => appendToNote(vault, slug, text));
+          if (!note) {
+            return { content: [{ type: "text", text: `No note found with slug '${params.slug}'.` }], details: { action: "append", found: false } };
+          }
+          return {
+            content: [{ type: "text", text: `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 slug = params.slug;
+          const text = params.text;
+          const path = resolveNotePath(vault, slug);
+          if (!path) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `Invalid note slug '${slug}' — notes are flat files inside the vault (no path separators or '..').`,
+                },
+              ],
+              details: { action: "finalize", found: false },
+            };
+          }
+          // Serialized read-modify-write, same as append: finalize replaces the
+          // body above the raw tail, so it must not race other writers.
+          const note = await withMutationQueue(path, () => finalizeNote(vault, slug, { body: text }));
+          if (!note) {
+            return { content: [{ type: "text", text: `No note found with slug '${params.slug}'.` }], details: { action: "finalize", found: false } };
+          }
+          return {
+            content: [{ type: "text", text: `Finalized ${note.slug} (updated ${note.updated}). Raw notes tail preserved.` }],
+            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 {
+              content: [{ type: "text", text: `No notes matched '${params.query}'.` }],
+              details: { action: "search", hits: [] },
+            };
+          }
+          const lines = hits.map(
+            (h) => `- ${h.summary.slug}: ${h.summary.title} (score ${h.score})\n  ${h.snippet}`,
+          );
+          return {
+            content: [{ type: "text", text: `${hits.length} hit(s) for '${params.query}':\n${lines.join("\n")}` }],
+            details: { action: "search", hits },
+          };
+        }
+      }
+    },
+  });
+}

package/src/pi/tools/repoTool.ts

@@ -0,0 +1,94 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import {
+  assessStaleness,
+  buildRepoIndex,
+  findGitRoot,
+  readRepoIndex,
+  repoIndexDir,
+  summarizeIndex,
+  writeRepoIndex,
+} from "../../core";
+
+/**
+ * `weave_repo` — the repository-exploration tool (design §2/§8).
+ *
+ * Builds and reads the derived .okf index: structure, modules, packages,
+ * entry points, plus git-aware staleness.
+ */
+export function registerRepoTool(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "weave_repo",
+    label: "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.",
+    promptSnippet: "Explore the repository's structure via its .okf knowledge index",
+    promptGuidelines: [
+      "Use weave_repo action=overview to learn repository structure before broad code exploration instead of scanning files one by one.",
+      "Use weave_repo action=scan when the user asks to explore or index this repository.",
+    ],
+    parameters: Type.Object({
+      action: StringEnum(["status", "scan", "overview"] as const),
+    }),
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const root = await findGitRoot(ctx.cwd);
+      if (!root) {
+        return {
+          content: [{ type: "text", 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 {
+            content: [{ type: "text", text: `Repository ${root}\n${lines.join("\n")}` }],
+            details: { action: "status", inRepo: true, staleness, indexed: index !== null },
+          };
+        }
+
+        case "scan": {
+          onUpdate?.({ content: [{ type: "text", text: `Scanning ${root}…` }], details: {} });
+          const index = await buildRepoIndex(root);
+          if (!index) {
+            return {
+              content: [{ type: "text", text: "Cannot build index: the repository has no commits yet." }],
+              details: { action: "scan", inRepo: true, scanned: false },
+            };
+          }
+          const dir = await writeRepoIndex(root, index);
+          const summary = summarizeIndex(index).join("\n");
+          return {
+            content: [{ type: "text", text: `Knowledge index written to ${dir}\n\n${summary}` }],
+            details: { action: "scan", inRepo: true, scanned: true, index },
+          };
+        }
+
+        case "overview": {
+          const index = await readRepoIndex(root);
+          if (!index) {
+            return {
+              content: [{ type: "text", 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 {
+            content: [{ type: "text", text: header + summarizeIndex(index).join("\n") }],
+            details: { action: "overview", inRepo: true, indexed: true, staleness, index },
+          };
+        }
+      }
+    },
+  });
+}