pi-weave 0.2.4 → 0.3.0

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 },
+      };
+    }
+  }
+}

package/src/core/sessions.ts

@@ -48,6 +48,15 @@ export const SESSION_SCAN_MAX_SESSIONS = 100;
 export const SESSION_SCAN_MAX_FILE_BYTES = 16 * 1024 * 1024;
 export const SESSION_SCAN_CONCURRENCY = 2;
 
+export const SESSION_SCAN_SYSTEM_PROMPT = [
+  "You write durable memory notes that compact coding-agent sessions into their bottom line.",
+  "First summarize what happened, what shipped (features, files, commands, decisions), and",
+  "what went less well (dead ends, breakage, unfinished work) using concrete technical details.",
+  "Then add a '## Takeaways' section with 2–4 reusable lessons: gotchas, root causes of tricky",
+  "failures, non-obvious syntax rules, or architecture patterns a future agent can apply.",
+  "Past tense. No preamble or code fences. Omit lessons unsupported by the transcript.",
+].join("\n");
+
 const DIGEST_MAX_CHARS = 12_000;
 const USER_MSG_MAX_CHARS = 400;
 const MAX_USER_MESSAGES = 60;
@@ -810,6 +819,76 @@ export interface SessionScanResult {
   failed: SessionScanFailure[];
 }
 
+export function formatSessionScanResult(result: SessionScanResult): string {
+  const parts = [
+    `${result.written} summarized (${result.created} new, ${result.updated} updated)`,
+    `${result.skippedFresh} unchanged`,
+  ];
+  if (result.skippedEmpty > 0) parts.push(`${result.skippedEmpty} empty`);
+  if (result.skippedTooBig > 0) parts.push(`${result.skippedTooBig} skipped (size)`);
+  if (result.skippedUnreadable > 0) parts.push(`${result.skippedUnreadable} unreadable`);
+  let text = `${parts.join(", ")} — ${result.considered} sessions considered`;
+  const first = result.failed[0];
+  if (first) text += `; ${result.failed.length} failed, first: ${first.path}: ${first.error}`;
+  return text;
+}
+
+export interface SessionDigestScanOptions {
+  vaultRoot: string;
+  digest: SessionDigest;
+  content: string;
+  source: string;
+  hash: string;
+  summarize: SummarizeFn;
+  model?: string;
+  now?: () => Date;
+}
+
+/** Summarize one in-memory public session without reading a harness database. */
+export async function runSessionDigestScan(options: SessionDigestScanOptions): Promise<SessionScanResult> {
+  const result: SessionScanResult = {
+    discovered: 1,
+    considered: 1,
+    written: 0,
+    created: 0,
+    updated: 0,
+    skippedFresh: 0,
+    skippedEmpty: 0,
+    skippedTooBig: 0,
+    skippedUnreadable: 0,
+    migrated: await migrateLegacySessionNotes(options.vaultRoot),
+    failed: [],
+  };
+  const pointer = (await readSessionNoteIndex(options.vaultRoot)).get(options.digest.id);
+  if (pointer?.hash === options.hash) {
+    result.skippedFresh = 1;
+    return result;
+  }
+  if (!sessionHasContent(options.digest)) {
+    result.skippedEmpty = 1;
+    return result;
+  }
+  try {
+    const summary = (await options.summarize({ path: options.source, content: options.content })).trim();
+    if (summary.length === 0) throw new Error("model returned an empty summary");
+    await writeSessionNote(options.vaultRoot, {
+      digest: options.digest,
+      file: { path: options.source },
+      hash: options.hash,
+      summary,
+      model: options.model ?? null,
+      at: (options.now ?? (() => new Date()))().toISOString(),
+      existingSlug: pointer?.slug ?? null,
+    });
+    result.written = 1;
+    if (pointer) result.updated = 1;
+    else result.created = 1;
+  } catch (error) {
+    result.failed.push({ path: options.source, error: error instanceof Error ? error.message : String(error) });
+  }
+  return result;
+}
+
 /**
  * Run the session scan, in three phases:
  *
@@ -960,4 +1039,4 @@ export async function runSessionScan(options: SessionScanOptions): Promise<Sessi
   }, aborted);
 
   return result;
-}
+}

package/src/core/summaries.ts

@@ -24,6 +24,12 @@ export const DEEP_SCAN_MAX_FILES = 300;
 export const DEEP_SCAN_MAX_FILE_BYTES = 32_768;
 export const DEEP_SCAN_CONCURRENCY = 4;
 
+export const DEEP_SCAN_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");
+
 /** A parsed summary sidecar. */
 export interface SummaryRecord {
   /** Repo-relative source path this summary describes. */
@@ -75,6 +81,16 @@ export interface DeepScanResult {
   pruned: number;
 }
 
+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`;
+  const first = result.failed[0];
+  if (first) text += `; ${result.failed.length} failed, first: ${first.path}: ${first.error}`;
+  return text;
+}
+
 /** Deterministic sidecar file name for a repo-relative target path. */
 export function summaryFileName(target: string): string {
   return target.split("/").join("--") + SUMMARY_SUFFIX;

package/src/core/workspace.ts

@@ -71,7 +71,7 @@ export function formatDashboard(status: WorkspaceStatus): string {
   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");
+    lines.push("  not indexed — run /weave-scan or ask your agent to explore");
     return lines.join("\n");
   }
   lines.push(`  index: ${repo.staleness.state}`);