pi-weave 0.1.4 → 0.1.6

package/README.md

@@ -13,21 +13,15 @@
 
 **An agent-native knowledge workspace for your life and your code.**
 
-pi-weave is a [pi](https://github.com/earendil-works/pi)
-extension with two faces that are secretly one:
+pi-weave is a [pi](https://github.com/earendil-works/pi) extension with two faces that are secretly one:
 
-1. **A smart notepad with AI skills.** A persistent vault of knowledge —
-   decisions, ideas, people, meetings — stored as plain Markdown notes with
-   front matter under `~/.okf/notes/`. Your agent reads and writes it *with*
-   you; everything is editable by hand in any editor.
+1. **A smart notepad with AI skills.** A persistent vault of knowledge — decisions, ideas, people, meetings — stored as plain Markdown notes
+   with front matter under `~/.okf/notes/`. Your agent reads and writes it *with* you; everything is editable by hand in any editor.
 
-2. **A repository exploration engine.** A derived, git-aware knowledge index
-   of the repo you're in, living at `<repo>/.okf/` — structure, languages,
-   packages, modules, entry points, and staleness state. Rebuildable,
-   disposable, never the source of truth.
+2. **A repository exploration engine.** A derived, git-aware knowledge index of the repo you're in, living at `<repo>/.okf/` — structure,
+   languages, packages, modules, entry points, and staleness state. Rebuildable, disposable, never the source of truth.
 
-And one rule across both: **everything is equally usable by humans and
-agents.** No opaque databases. No lock-in formats.
+And one rule across both: **everything is equally usable by humans and agents.** No opaque databases. No lock-in formats.
 
 ```
 🧵 vault:12 · my-project:ok      ← pi's status line when weave is active
@@ -43,47 +37,40 @@ pi install /path/to/pi-weave       # local path
 
 Or for development: `pi -e ./src/pi/index.ts`.
 
-The package is [published on npm](https://www.npmjs.com/package/pi-weave);
-releases are cut from `main` and auto-published with provenance attestation
-([Publish workflow](.github/workflows/publish.yml)).
+The package is [published on npm](https://www.npmjs.com/package/pi-weave); releases are cut from `main` and auto-published with provenance
+attestation ([Publish workflow](.github/workflows/publish.yml)).
 
 ## What you get
 
 | Surface | Name | Purpose |
 |---|---|---|
-| Tool | `weave_note` | list / get / add / append / search vault notes |
+| Tool | `weave_note` | list / get / add / append / finalize / search vault notes |
 | Tool | `weave_repo` | status / scan / overview of the `.okf` repo index |
 | Command | `/weave` | workspace dashboard (vault + repository) |
 | Command | `/weave-scan` | build/refresh the repository index (light) |
 | Command | `/weave-scan deep` | light index + model-summarized sidecars (opt-in, incremental) |
+| Command | `/weave-scan-cancel` | stop an in-flight `/weave-scan deep` run |
 | Command | `/weave-view` | open the local graph viewer in your browser |
 | Command | `/weave-view tui` | explore the same graph in-terminal (keyboard) |
 | Skill | `weave-notepad` | how the agent should take good notes |
 | Skill | `weave-explore` | how the agent should explore repositories |
 
-**`/weave-view`** starts a loopback-only server (`127.0.0.1`, random port)
-and opens an interactive graph of your knowledge space: vault notes with
-trust provenance (solid = human, dashed = agent, dimmed = generated),
-wiki-link edges between notes, and the repository's structure anchored to
-git state. It reads disk live on every refresh — never a stale cache.
-Zoom/scroll, drag to pan, click nodes to expand; notes open in a rendered
-markdown side panel.
-
-**`/weave-view tui`** explores the same knowledge graph in the terminal:
-an expandable containment tree (Explore), a 1-hop neighborhood (Focus), a
-selected-node detail view with note/`.okf` bodies, and a staleness + link
-health surface — all keyboard-driven and read-only. Same data as the
-browser viewer (the `GraphModel` assembled from vault + repo index); a
-pure, harness-free view-model (`src/pi/viewer/tui/model.ts`) backs the
-`WeaveExplorer` component. See `docs/weave-view-tui-design.md`.
-
-On session start, pi-weave detects the repository you're in, checks whether
-`.okf` exists and is fresh, and says so in the status line.
-
-**`/weave-scan deep`** is the opt-in, incremental deep pass: it refreshes the
-light index and then writes a short model summary per file to
-`.okf/repository/summaries/`, skipping files whose content hash is unchanged
-since their last summary. It costs tokens, so it never runs implicitly.
+**`/weave-view`** starts a loopback-only server (`127.0.0.1`, random port) and opens an interactive graph of your knowledge space: vault
+notes with trust provenance (solid = human, dashed = agent, dimmed = generated), wiki-link edges between notes, and the repository's
+structure anchored to git state. It reads disk live on every refresh — never a stale cache. Zoom/scroll, drag to pan, click nodes to expand;
+notes open in a rendered markdown side panel.
+
+**`/weave-view tui`** explores the same knowledge graph in the terminal: an expandable containment tree (Explore), a 1-hop neighborhood
+(Focus), a selected-node detail view with note/`.okf` bodies, and a staleness + link health surface — all keyboard-driven and read-only.
+Same data as the browser viewer (the `GraphModel` assembled from vault + repo index); a pure, harness-free view-model
+(`src/pi/viewer/tui/model.ts`) backs the `WeaveExplorer` component. See `docs/weave-view-tui-design.md`.
+
+On session start, pi-weave detects the repository you're in, checks whether `.okf` exists and is fresh, and says so in the status footer — a
+filled `●` marks weave as active (a deep scan spins it while running).
+
+**`/weave-scan deep`** is the opt-in, incremental deep pass: it refreshes the light index and then writes a short model summary per file to
+`.okf/repository/summaries/`, skipping files whose content hash is unchanged since their last summary. It costs tokens, so it never runs
+implicitly — and it runs in the background, so `/weave-scan-cancel` can stop it mid-flight.
 
 ## The formats (why everything is portable)
 
@@ -112,15 +99,13 @@ Repository index (`<repo>/.okf/`):
     └── structure.json  # languages, packages, modules, entry points
 ```
 
-The `.okf` index is **derived**: delete it, rescan, lose nothing. By default
-it's excluded from git locally (`.git/info/exclude`); committing it for team
-sharing is a deliberate opt-in.
+The `.okf` index is **derived**: delete it, rescan, lose nothing. By default it's excluded from git locally (`.git/info/exclude`);
+committing it for team sharing is a deliberate opt-in.
 
 ## For other agent harnesses
 
-The on-disk artifacts and `src/core` are harness-agnostic by design — Claude
-Code and opencode adapters are on the roadmap (docs/design.md §21), and the
-skills follow the [Agent Skills standard](https://agentskills.io/specification).
+The on-disk artifacts and `src/core` are harness-agnostic by design — Claude Code and opencode adapters are on the roadmap (docs/design.md
+§21), and the skills follow the [Agent Skills standard](https://agentskills.io/specification).
 
 ## Development
 
@@ -129,5 +114,4 @@ npm install
 npm run check     # typecheck + tests with coverage gate (≥95%)
 ```
 
-See [AGENTS.md](AGENTS.md) for contributor/agent rules and
-[docs/design.md](docs/design.md) for the full design.
+See [AGENTS.md](AGENTS.md) for contributor/agent rules and [docs/design.md](docs/design.md) for the full design.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-weave",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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,
@@ -48,6 +48,8 @@
     "coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit",
     "check": "npm run typecheck && npm run coverage",
+    "rewrap:md": "node scripts/rewrap-md.mjs",
+    "rewrap:md:check": "node scripts/rewrap-md.mjs --check",
     "prepublishOnly": "npm run check"
   },
   "peerDependencies": {

package/skills/weave-explore/SKILL.md

@@ -5,45 +5,34 @@ description: Explore a git repository through its pi-weave knowledge index (.okf
 
 # Weave Explore
 
-pi-weave keeps a **derived** knowledge index of the repository at
-`<repo>/.okf/`. Source code is the truth; the index is a rebuildable cache.
-Deleting `.okf` loses nothing — rescan to regenerate it.
+pi-weave keeps a **derived** knowledge index of the repository at `<repo>/.okf/`. Source code is the truth; the index is a rebuildable
+cache. Deleting `.okf` loses nothing — rescan to regenerate it.
 
 ## Tools
 
-In pi, use the `weave_repo` tool (or the `/weave-scan` command). To see
-the assembled graph in the terminal, run `/weave-view tui` (Explore tree,
-Focus neighborhood, Health surface); `/weave-view` opens the browser viewer.
-In other harnesses, read the JSON documents under `.okf/` directly.
+In pi, use the `weave_repo` tool (or the `/weave-scan` command). To see the assembled graph in the terminal, run `/weave-view tui` (Explore
+tree, Focus neighborhood, Health surface); `/weave-view` opens the browser viewer. In other harnesses, read the JSON documents under `.okf/`
+directly.
 
 ## Workflow
 
 1. **Check for an index**: `weave_repo` action=status.
-   - `missing` → offer to scan (`weave_repo` action=scan), or scan directly
-     when the user asked to explore.
+   - `missing` → offer to scan (`weave_repo` action=scan), or scan directly when the user asked to explore.
    - `stale` → scan again; the repository moved on.
    - `fresh` → read it: action=overview.
-2. **Start from the overview**: file counts, languages, packages, module
-   groupings, and likely entry points. This replaces dozens of `ls`/`find`
-   calls.
-3. **Descend progressively** (design §9): only open files in modules relevant
-   to the user's question. The index gives you the map; the code gives you
-   the terrain.
-4. **Read summaries before full files**: if the repo has been deep-scanned
-   (`.okf/repository/summaries/` exists), read the relevant sidecars first —
-   they tell you what a file does and its outward surface in 1–3 sentences,
-   so you can decide whether to open the full file at all.
-5. **Answer with structure**: name modules and packages by their indexed
-   paths so the user can jump straight to them.
+2. **Start from the overview**: file counts, languages, packages, module groupings, and likely entry points. This replaces dozens of
+   `ls`/`find` calls.
+3. **Descend progressively** (design §9): only open files in modules relevant to the user's question. The index gives you the map; the code
+   gives you the terrain.
+4. **Read summaries before full files**: if the repo has been deep-scanned (`.okf/repository/summaries/` exists), read the relevant sidecars
+   first — they tell you what a file does and its outward surface in 1–3 sentences, so you can decide whether to open the full file at all.
+5. **Answer with structure**: name modules and packages by their indexed paths so the user can jump straight to them.
 
 ## Deep summaries
 
-`/weave-scan deep` creates or refreshes `.okf/repository/summaries/` — one
-sidecar per file, written by the session model. It is **opt-in and
-incremental**: it never runs implicitly, and it only re-summarizes files
-whose content hash changed since their last summary. If summaries are
-missing or stale, offer `/weave-scan deep` to create or refresh them before
-diving into full files.
+`/weave-scan deep` creates or refreshes `.okf/repository/summaries/` — one sidecar per file, written by the session model. It is **opt-in
+and incremental**: it never runs implicitly, and it only re-summarizes files whose content hash changed since their last summary. If
+summaries are missing or stale, offer `/weave-scan deep` to create or refresh them before diving into full files.
 
 ## On-disk layout
 
@@ -59,6 +48,5 @@ diving into full files.
 
 ## Trust model
 
-Everything in `.okf` is machine-generated (`source: generated`). If the user
-corrects an interpretation, that correction belongs in the vault (see the
-`weave-notepad` skill) as human knowledge, not in the derived index.
+Everything in `.okf` is machine-generated (`source: generated`). If the user corrects an interpretation, that correction belongs in the
+vault (see the `weave-notepad` skill) as human knowledge, not in the derived index.

package/skills/weave-notepad/SKILL.md

@@ -5,21 +5,17 @@ description: "Take and retrieve durable notes in the pi-weave vault. Use when th
 
 # Weave Notepad
 
-The pi-weave vault is the user's long-term memory: plain Markdown notes with
-front matter under `~/.okf/notes/`. It is shared with the human — anything
-you write here, they can read and edit, and vice versa.
+The pi-weave vault is the user's long-term memory: plain Markdown notes with front matter under `~/.okf/notes/`. It is shared with the human
+— anything you write here, they can read and edit, and vice versa.
 
 ## Tools
 
-In pi, use the `weave_note` tool. In other harnesses (or when the tool is not
-available), operate on the files directly:
+In pi, use the `weave_note` tool. In other harnesses (or when the tool is not available), operate on the files directly:
 
 - **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 preserves
-  the tail verbatim.
+- 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
+  preserves the tail verbatim.
 
 ## Raw Tail Format
 
@@ -41,49 +37,56 @@ Every note maintains a verbatim, append-only raw section at the bottom separated
 
 ### How to capture and append raw input
 
-1. **Divider and Heading**: The raw section starts with `---` followed by `## Raw` and the notice comment: `<!-- NEVER edit below this line. Verbatim user input preserved here. -->`.
+1. **Divider and Heading**: The raw section starts with `---` followed by `## Raw` and the notice comment: `<!-- NEVER edit below this line.
+   Verbatim user input preserved here. -->`.
 2. **Code Blocks for Verbatim Input**: Always wrap verbatim user lines inside code blocks (triple backticks).
 3. **Date and Time on Appends**: When appending subsequent snippets, prepend each snippet with: `<!-- appended YYYY-MM-DD HH:MM -->`.
 4. **Finalization (`finalize`)**:
    - `finalize` replaces or structures content only above the `---` and `## Raw` section.
    - The `## Raw` block and all verbatim code blocks are never modified or removed.
 
+## Dictation mode (continuous compile)
+
+During live dictation / interview note-taking (see the skill description), Pi does **not** wait until the end to organize the note. Every
+interactive append is immediately compiled into the body:
+
+1. **Append the raw words verbatim** to the `## Raw` tail as usual (a dated `<!-- appended YYYY-MM-DD HH:MM -->` code block).
+2. **Then immediately finalize** (`weave_note` action=finalize): rewrite the body *above* the `## Raw` tail — front-loaded summary,
+   sections, decisions, questions, tasks, entities, links — so the compiled document reflects everything said so far.
+3. **Never rewrite or remove the `## Raw` tail.** It stays append-only and verbatim; only the body above it changes.
+
+The result is a continuously-updated compiled document that stays current throughout the session — not just a raw tail that gets organized
+once at the end.
+
 ## When to take a note
 
-Create a note **only when the user explicitly asks** for one to exist:
-"start a note on X", "add to the X note", "remember this", "jot that down".
-Never promote conversation into a note on your own initiative — capture is
-explicit by design.
+Create a note **only when the user explicitly asks** for one to exist: "start a note on X", "add to the X note", "remember this", "jot that
+down". Never promote conversation into a note on your own initiative — capture is explicit by design.
 
 ## When NOT to take a note
 
-- Anything derivable from the repository itself (that knowledge belongs to
-  the `.okf` index, not the vault).
+- Anything derivable from the repository itself (that knowledge belongs to the `.okf` index, not the vault).
 - Session-scratch information (in-progress task state).
 - Secrets, credentials, or anything the user hasn't confirmed is safe to persist.
 
 ## 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.
+1. **Search first** (`weave_note` action=search): if a note exists, `append` to it rather than creating a duplicate.
 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. Keep them
-   under the `## Raw` tail format at the end of the note.
-4. **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.
-5. Tags: 1–4 lowercase tags; reuse existing tags when possible.
-6. 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.
+3. **Scribble in, verbatim.** When the user is dictating, append their words to the note as rough, verbatim scribbles — no silent rewording.
+   Keep them under the `## Raw` tail format at the end of the note.
+4. **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
+   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.
+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`
+   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.
 
 ## Retrieving knowledge
 
-Use `weave_note` action=search with the user's key terms, then `get` the best
-hits. When a note and the repository index disagree, trust the repository for
-facts about code and flag the discrepancy — the note may be stale intent.
+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.

package/src/pi/index.ts

@@ -32,6 +32,32 @@ export default function piWeave(pi: ExtensionAPI): void {
   // 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;
+  let lastCtx: ExtensionContext | ExtensionCommandContext | null = null;
+  let lastStatusText: string | undefined = undefined;
+  let isActive = false;
+
+  function updateStatus(ctx?: ExtensionContext | ExtensionCommandContext, text?: string): void {
+    if (ctx) lastCtx = ctx;
+    const c = ctx || lastCtx;
+    if (!c?.ui?.setStatus) return;
+    if (text !== undefined) {
+      lastStatusText = text;
+    }
+    if (!lastStatusText) {
+      c.ui.setStatus("weave", undefined);
+      return;
+    }
+    let theme: { fg?: (slot: string, text: string) => string } | undefined;
+    try {
+      theme = (c.ui as unknown as { theme?: { fg?: (slot: string, text: string) => string } })?.theme;
+    } catch {
+      // ignore
+    }
+    const indicator = (isActive || inFlightDeepScans.size > 0)
+      ? (theme?.fg ? theme.fg("accent", "●") : "●")
+      : (theme?.fg ? theme.fg("dim", "○") : "○");
+    c.ui.setStatus("weave", `${indicator} ${lastStatusText}`);
+  }
 
   pi.on("session_shutdown", async () => {
     const server = viewer;
@@ -39,9 +65,19 @@ export default function piWeave(pi: ExtensionAPI): void {
     await server?.stop();
   });
 
+  pi.on("agent_start", async (_event, ctx) => {
+    isActive = true;
+    updateStatus(ctx);
+  });
+
+  pi.on("agent_end", async (_event, ctx) => {
+    isActive = false;
+    updateStatus(ctx);
+  });
+
   pi.on("session_start", async (_event, ctx) => {
     const status = await getWorkspaceStatus(ctx.cwd);
-    updateStatusWidget(ctx, formatStatusLine(status));
+    updateStatus(ctx, formatStatusLine(status));
 
     if (!ctx.hasUI) return;
     const repo = status.repository;
@@ -105,13 +141,13 @@ export default function piWeave(pi: ExtensionAPI): void {
           // 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);
+          startDeepScan(root, ctx, status, updateStatus);
         }
         return; // the background scan owns the status line until it settles
       }
 
       const status = await getWorkspaceStatus(ctx.cwd);
-      updateStatusWidget(ctx, formatStatusLine(status));
+      updateStatus(ctx, formatStatusLine(status));
     },
   });
 
@@ -156,15 +192,26 @@ export async function deepScanDone(root: string): Promise<void | undefined> {
  * 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 {
+function startDeepScan(
+  root: string,
+  ctx: ExtensionCommandContext,
+  baseStatus: WorkspaceStatus,
+  updateStatus: (ctx?: ExtensionContext | ExtensionCommandContext, text?: string) => void,
+): void {
   const controller = new AbortController();
-  const done = (async () => {
+  let doneResolve: () => void;
+  const done = new Promise<void>((resolve) => {
+    doneResolve = resolve;
+  });
+  inFlightDeepScans.set(root, { controller, done });
+
+  void (async () => {
     try {
-      updateStatusWidget(ctx, "🧵 deep scan: starting…");
+      updateStatus(ctx, "🧵 deep scan: starting…");
       const outcome = await deepScanRepository(root, ctx, {
         onProgress: ({ current, total, path }) => {
           const pct = total > 0 ? Math.round((current / total) * 100) : 100;
-          updateStatusWidget(ctx, `🧵 deep scan: ${current}/${total} (${pct}%) — ${path}`);
+          updateStatus(ctx, `🧵 deep scan: ${current}/${total} (${pct}%) — ${path}`);
         },
         signal: controller.signal,
       });
@@ -183,13 +230,9 @@ function startDeepScan(root: string, ctx: ExtensionCommandContext, baseStatus: W
     } finally {
       // Restore the settled status before removing the map entry, so a caller
       // awaiting deepScanDone() observes the settled status line.
-      updateStatusWidget(ctx, formatStatusLine(baseStatus));
       inFlightDeepScans.delete(root);
+      updateStatus(ctx, formatStatusLine(baseStatus));
+      doneResolve!();
     }
   })();
-  inFlightDeepScans.set(root, { controller, done });
-}
-
-function updateStatusWidget(ctx: ExtensionContext | ExtensionCommandContext, text: string | undefined): void {
-  ctx.ui.setWidget("weave", text ? [text] : undefined, { placement: "belowEditor" });
 }

package/src/pi/viewer/tui/run.ts

@@ -60,7 +60,14 @@ export async function runWeaveViewTui(ctx: ExtensionCommandContext): Promise<voi
 
   // Refresh the status line after close (a /weave-scan may have landed meanwhile).
   const status = await getWorkspaceStatus(ctx.cwd);
-  ctx.ui.setWidget("weave", [formatStatusLine(status)], { placement: "belowEditor" });
+  let theme: { fg?: (slot: string, text: string) => string } | undefined;
+  try {
+    theme = (ctx.ui as unknown as { theme?: { fg?: (slot: string, text: string) => string } })?.theme;
+  } catch {
+    // ignore
+  }
+  const indicator = theme?.fg ? theme.fg("dim", "○") : "○";
+  ctx.ui.setStatus("weave", `${indicator} ${formatStatusLine(status)}`);
 }
 
 /** Test seam: build the model the explorer opens with, without a terminal. */