pi-weave 0.1.23 → 0.2.1

package/README.md

@@ -11,24 +11,56 @@
   <a href="./LICENSE"><img alt="license: MIT" src="https://img.shields.io/npm/l/pi-weave?color=green"></a>
 </p>
 
-**A local knowledge workspace you can talk to.**
+**Your notes. Your agent's notes. One searchable knowledge workspace.**
 
-pi-weave is an extension for [pi](https://github.com/earendil-works/pi). Ask Pi to take notes while you think out loud, keep your exact words alongside a useful summary, and explore everything in `/weave-view`.
+I've been chasing the right note-taking workflow for years. Notion, OneNote, Obsidian, and plenty of others.
 
-It also understands the repository you are working in. Personal notes live in a Markdown vault; repository knowledge lives in a disposable `.okf` index. Both are plain files that humans and agents can read.
+With pi-weave, I've made one that finally answers the way I want to work today — especially now that AI agents are part of that work.
 
-## Core capabilities
+The idea is simple:
 
-- **Conversational note-taking.** Create and update notes through natural-language requests such as “start a note”, “add this”, or “remember that”.
-- **Verbatim narration with structured summaries.** During dictation, Pi preserves each spoken passage in an append-only `## Raw` section while maintaining an organized summary above it.
-- **Knowledge retrieval.** Pi searches existing notes when answering questions about previous decisions, people, projects, or meetings.
-- **Unified visual workspace.** `/weave-view` presents notes, links, repository structure, and provenance in a live browser interface.
-- **Optional session memory.** `/weave-scan sessions` turns changed pi transcripts into searchable notes with reusable technical takeaways.
-- **Repository exploration.** A lightweight, git-aware index gives Pi a structural overview of the current codebase before it reads files.
+**You and your agent should share the same knowledge.**
 
-Nothing is captured silently. pi-weave creates or extends a personal note only when you ask it to.
+Talk naturally and let your thoughts become structured notes. Write notes yourself. Let your agent capture decisions, discoveries, and
+useful context. Bring important knowledge forward from previous sessions.
 
-## Install
+Then find it again — by searching the workspace yourself, or simply asking your agent.
+
+Everything is local. Everything is readable. Your notes are ordinary files, not knowledge trapped inside another chat.
+
+## Think out loud
+
+Dictation is one of my favorite ways to use AI.
+
+Instead of stopping to organize every thought while I'm having it, I can just talk:
+
+> Start a note about pi-weave positioning. I'm going to think out loud.
+
+pi-weave keeps what I actually said while Pi continuously turns it into a useful, structured note.
+
+The raw thought stays yours. The organization is handled for you.
+
+And it doesn't end with human notes.
+
+## Your knowledge + your agent's knowledge
+
+pi-weave gives humans and agents one workspace.
+
+A note you dictate, something you write manually, a useful discovery made by an agent, or knowledge recovered from an earlier session can
+all live together.
+
+pi-weave keeps track of where knowledge came from, while making the whole workspace searchable by both you and your agent.
+
+**The conversation can end. The knowledge doesn't have to.**
+
+## Built on Pi
+
+pi-weave is built as an extension for [Pi](https://github.com/earendil-works/pi).
+
+I've grown to love Pi precisely because it is such a lightweight agent harness. It gives the model tools and context without trying to
+become the product itself, and its extensibility makes projects like pi-weave possible.
+
+Install pi-weave:
 
 ```bash
 pi install npm:pi-weave
@@ -43,6 +75,8 @@ pi install /path/to/pi-weave
 
 Requires Node **20.13 or newer**.
 
+Then just talk to Pi.
+
 ## Start taking notes
 
 Talk to Pi normally:
@@ -71,7 +105,8 @@ For each chunk, Pi:
 2. refreshes the structured summary above it;
 3. leaves the raw record untouched.
 
-This makes the note readable during the conversation without replacing your words with an AI reconstruction. Notes based on your dictation remain marked `source: human`; notes drafted by Pi are marked `source: agent`.
+This makes the note readable during the conversation without replacing your words with an AI reconstruction. Notes based on your dictation
+remain marked `source: human`; notes drafted by Pi are marked `source: agent`.
 
 Useful requests include:
 
@@ -86,9 +121,9 @@ Useful requests include:
 
 ## Keeping the vault connected
 
-A wiki-link resolves to nothing when it is written as a bare title — `[[Quarterly Roadmap]]` when the note lives at
-`planning/roadmap-2026` — or when it points at a note that was never written. Pi repairs those in one deterministic pass instead of
-rereading the vault and guessing.
+A wiki-link resolves to nothing when it is written as a bare title — `[[Quarterly Roadmap]]` when the note lives at `planning/roadmap-2026`
+— or when it points at a note that was never written. Pi repairs those in one deterministic pass instead of rereading the vault and
+guessing.
 
 ```text
 You: Check the links in my notes.
@@ -112,13 +147,19 @@ Renaming or moving a note rewrites its inbound links automatically, so its backl
 The browser workspace has four connected views:
 
 - **Tree** — notes, folders, and repository structure, with text and provenance filters.
-- **Note** — rendered Markdown with clickable `[[wikilinks]]`, link previews, tags, authorship, and an action to open the source in `$EDITOR`.
+- **Note** — rendered Markdown with clickable `[[wikilinks]]`, link previews, tags, authorship, click-to-edit, and an action to open the
+  source in `$EDITOR`.
 - **Graph** — a navigable map of notes, links, mentions, modules, and repository relationships. Selecting something updates every view.
 - **Context** — links, backlinks, tags, and code mentions for the current selection.
 
-Search with `⌘K` / `Ctrl K`. Press `?` for all shortcuts. The workspace updates as notes change on disk, so a note written by Pi appears without a reload. It follows the system theme by default and can be switched between light and dark.
+Search with `⌘K` / `Ctrl K`. Press `?` for all shortcuts. The workspace updates as notes change on disk, so a note written by Pi appears
+without a reload. It follows the system theme by default and can be switched between light and dark.
 
-The browser is read-only. Edit with `$EDITOR`, Obsidian, or the `weave_note` tool; unknown front-matter fields remain preserved.
+**Click the note text to edit it** — the prose swaps for its Markdown source; `⌘S` / `Ctrl S` saves, `Esc` or **Done** closes. Selecting
+text to copy and clicking a `[[wikilink]]` do what they always did; neither opens the editor. A save rewrites the body and nothing
+else — unknown front-matter fields, key order, and the append-only `## Raw` tail of a dictated note all survive untouched, so a note edited
+here and a note edited in Obsidian stay byte-compatible. Editing with `$EDITOR`, Obsidian, or the `weave_note` tool works as before; the
+last writer wins, and the workspace picks up outside changes within a couple of seconds.
 
 `/weave-view tui` is the smaller, read-only terminal explorer: tree, focused neighborhood, details, and link health over the same graph.
 
@@ -129,7 +170,10 @@ The browser is read-only. Edit with `$EDITOR`, Obsidian, or the `weave_note` too
 /weave-scan sessions /path/to/history   # explicit history root
 ```
 
-This opt-in scan treats a supplied file—or every bounded text file under a supplied directory—as opaque session material for the active model to interpret, then writes generated notes under `~/.okf/notes/sessions/`. That makes it usable with Claude Code, opencode, Codex, or exported history trees without requiring their schema or file extension. It skips unchanged files, captures outcomes plus reusable technical takeaways, works outside Git repositories, and can be stopped with `/weave-scan-cancel`.
+This opt-in scan treats a supplied file—or every bounded text file under a supplied directory—as opaque session material for the active
+model to interpret, then writes generated notes under `~/.okf/notes/sessions/`. That makes it usable with Claude Code, opencode, Codex, or
+exported history trees without requiring their schema or file extension. It skips unchanged files, captures outcomes plus reusable technical
+takeaways, works outside Git repositories, and can be stopped with `/weave-scan-cancel`.
 
 ## Repository knowledge
 
@@ -140,9 +184,11 @@ Inside a Git repository, pi-weave detects whether `<repo>/.okf/` is missing, fre
 /weave-scan deep    # also summarize changed files with the active model
 ```
 
-The light index covers languages, packages, modules, entry points, and Git state. A deep scan adds short per-file summaries and only revisits files whose content changed.
+The light index covers languages, packages, modules, entry points, and Git state. A deep scan adds short per-file summaries and only
+revisits files whose content changed.
 
-The repository index is a cache, not a source of truth. Delete `.okf`, scan again, and nothing important is lost. pi-weave excludes it locally from Git by default.
+The repository index is a cache, not a source of truth. Delete `.okf`, scan again, and nothing important is lost. pi-weave excludes it
+locally from Git by default.
 
 ## Commands and tools
 
@@ -199,7 +245,9 @@ We probably want OIDC next quarter…
 
 Set `PI_WEAVE_VAULT` to use a different vault location.
 
-Reading, writing, searching, and viewing notes are local operations. Deep repository scans and session summaries send bounded input to whichever model you configured in pi. The browser workspace binds only to loopback, uses a per-session token, and shuts down with the pi session.
+Reading, writing, searching, and viewing notes are local operations. Deep repository scans and session summaries send bounded input to
+whichever model you configured in pi. The browser workspace binds only to loopback, uses a per-session token, and shuts down with the pi
+session.
 
 The vault format, repository index, and skills are intentionally harness-agnostic. `src/core` contains no pi-specific imports.
 
@@ -219,7 +267,8 @@ npm run coverage
 npm run build:web
 ```
 
-Coverage must remain at or above **95%** for lines, branches, functions, and statements. If browser source changes, rebuild and commit `src/web/client/dist/app.js`.
+Coverage must remain at or above **95%** for lines, branches, functions, and statements. If browser source changes, rebuild and commit
+`src/web/client/dist/app.js`.
 
 Read [AGENTS.md](AGENTS.md) before contributing. Work on a feature branch; do not commit directly to `main`.
 

package/package.json

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

package/src/core/index.ts

@@ -59,6 +59,7 @@ export {
   resolveHtmlPath,
   resolveNotePath,
   searchNotes,
+  setNoteBody,
   upsertNote,
   type LinkRepairResult,
 } from "./vault";

package/src/core/links/repair.ts

@@ -99,7 +99,7 @@ const RAW_HEADING_RE = new RegExp(`^${RAW_NOTES_HEADING}[ \\t]*\\r?$`, "m");
  * inside a ```` block would too — and each mistake ends the protected region
  * early, exposing example links in documentation to rewriting.
  */
-function fenceRanges(body: string): [number, number][] {
+export function fenceRanges(body: string): [number, number][] {
   const ranges: [number, number][] = [];
   let open: { at: number; marker: string; length: number } | null = null;
   for (const match of body.matchAll(FENCE_RE)) {
@@ -134,7 +134,7 @@ function fenceRanges(body: string): [number, number][] {
  * refuse to repair — every link below it. Matching a whole heading line also
  * keeps `## Rawhide` from starting a tail.
  */
-function rawTailStart(body: string, fences: readonly [number, number][]): number {
+export function rawTailStart(body: string, fences: readonly [number, number][]): number {
   let from = 0;
   for (;;) {
     const rest = body.slice(from);

package/src/core/vault.ts

@@ -10,7 +10,7 @@ import {
   unquoteField,
   upsertFrontMatterFields,
 } from "./frontmatter";
-import { auditLinks, rewriteLinks, RAW_NOTES_HEADING, type LinkAudit, type LinkFix } from "./links/repair";
+import { auditLinks, fenceRanges, rawTailStart, rewriteLinks, RAW_NOTES_HEADING, type LinkAudit, type LinkFix } from "./links/repair";
 import { withMutationQueue } from "./mutex";
 import { NOTES_DIR, OKF_MANIFEST } from "./paths";
 import { slugify, uniqueSlug } from "./slug";
@@ -596,6 +596,51 @@ export async function repairVaultLinks(root: string, options: { apply?: boolean
   });
 }
 
+/**
+ * Keep the on-disk `## Raw` tail whatever the body says — it is append-only.
+ * `rawTailStart`, not `extractRawTail`: fence-aware, for untrusted input.
+ */
+function preserveRawTail(currentBody: string, nextBody: string): string {
+  const tail = currentBody.slice(tailBoundary(currentBody)).trimEnd();
+  const head = nextBody.slice(0, tailBoundary(nextBody)).trim();
+  if (tail === "") return head;
+  // An emptied head leaves the tail alone, not a leading blank line.
+  return head === "" ? tail : `${head}\n\n${tail}`;
+}
+
+/** A `---` rule, alone on the line, with only blank space after it. */
+const TAIL_RULE_RE = /(?:^|\n)-{3,}[ \t]*\r?\n\s*$/;
+
+/**
+ * Where the tail's text begins — the `---` rule, not the heading
+ * `rawTailStart` returns. Splitting at the heading orphans the rule.
+ */
+function tailBoundary(body: string): number {
+  const heading = rawTailStart(body, fenceRanges(body));
+  if (heading === body.length) return heading;
+  const rule = TAIL_RULE_RE.exec(body.slice(0, heading));
+  if (rule === null) return heading;
+  // `index` is the newline before the rule when there is one; step over it.
+  return rule.index === 0 && !body.startsWith("\n") ? 0 : rule.index + 1;
+}
+
+/**
+ * Replace a note's Markdown body; unknown front matter rides on
+ * `note.frontMatter` and only `updated` moves. Last write wins — no
+ * `expectedRevision`; docs/weave-workspace.md §11 P5.3 argues the trade.
+ */
+export async function setNoteBody(root: string, slug: string, body: string, now = new Date()): Promise<VaultMutationResult> {
+  const path = resolveNotePath(root, slug);
+  if (path === null) return { ok: false, reason: "invalid" };
+  return withVaultLock(root, async () => {
+    const note = await getNote(root, slug);
+    if (note === null) return { ok: false, reason: "missing" };
+    const next = preserveRawTail(note.body, body);
+    await writeNote(path, slug, { ...note, updated: now.toISOString() }, next, note.frontMatter);
+    return { ok: true, slug };
+  });
+}
+
 /** Rename a note in place and keep its front-matter title in sync. */
 export async function renameNote(root: string, slug: string, name: string, now = new Date()): Promise<VaultMutationResult> {
   const from = resolveNotePath(root, slug);

package/src/web/client/api.ts

@@ -323,6 +323,12 @@ function mutation(fetchImpl: FetchLike, url: string, method: string, body?: unkn
 const noteUrl = (slug: string, suffix = ""): string => `/api/note/${encodeURIComponent(slug)}${suffix}`;
 const folderUrl = (path: string, suffix = ""): string => `/api/folder/${path.split("/").map(encodeURIComponent).join("/")}${suffix}`;
 
+/**
+ * `POST /api/note/:slug` — save the note's Markdown body. No revision
+ * (last-write-wins, see core's `setNoteBody`), and a `MutationResult` rather
+ * than the note: the poll is what puts the new text back on screen.
+ */
+export const saveNote = (fetchImpl: FetchLike, slug: string, body: string) => mutation(fetchImpl, noteUrl(slug), "POST", { body });
 export const renameNote = (fetchImpl: FetchLike, slug: string, name: string) => mutation(fetchImpl, noteUrl(slug, "/rename"), "POST", { name });
 export const moveNote = (fetchImpl: FetchLike, slug: string, folder: string | null) => mutation(fetchImpl, noteUrl(slug, "/move"), "POST", { folder });
 export const deleteNote = (fetchImpl: FetchLike, slug: string) => mutation(fetchImpl, noteUrl(slug), "DELETE");