pi-weave 0.1.11 → 0.1.13

package/README.md

@@ -1,7 +1,7 @@
 # pi-weave
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/EranYonai/pi-weave/main/docs/pi-weave-logo.png" alt="pi-weave — an agent-native knowledge workspace" width="220"/>
+  <img src="https://raw.githubusercontent.com/EranYonai/pi-weave/main/docs/pi-weave-logo.png" alt="pi-weave" width="220"/>
 </p>
 
 <p align="center">
@@ -11,190 +11,206 @@
   <a href="./LICENSE"><img alt="license: MIT" src="https://img.shields.io/npm/l/pi-weave?color=green"></a>
 </p>
 
-**An agent-native knowledge workspace for your life and your code.**
+**A local knowledge workspace you can talk to.**
 
-pi-weave is a [pi](https://github.com/earendil-works/pi) extension with two faces that are secretly one:
+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`.
 
-1. **A smart notepad.** A persistent vault of knowledge — decisions, ideas, people, meetings — stored as plain Markdown notes with YAML
-   front matter under `~/.okf/notes/`. Your agent reads and writes it *with* you through the `weave_note` tool; everything stays editable by
-   hand in any editor.
+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.
 
-2. **A repository exploration engine.** A derived, git-aware knowledge index of the repo you are standing in, living at `<repo>/.okf/` —
-   structure, languages, packages, modules, entry points, and staleness state. Built and read through the `weave_repo` tool. Rebuildable,
-   disposable, never the source of truth.
+## Core capabilities
 
-One rule spans both: **everything is equally readable by humans and agents.** Markdown and JSON on disk, no opaque database, no lock-in
-format. Every generated artefact carries provenance (`human`, `agent` or `generated`), so agent-written content never masquerades as
-something you wrote.
+- **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.
+- **Repository exploration.** A lightweight, git-aware index gives Pi a structural overview of the current codebase before it reads files.
 
+Nothing is captured silently. pi-weave creates or extends a personal note only when you ask it to.
+
+## Install
+
+```bash
+pi install npm:pi-weave
 ```
-🕸️ vault:12 · my-project:ok      ← pi's status line when weave is active
+
+Other install sources:
+
+```bash
+pi install git:github.com/EranYonai/pi-weave
+pi install /path/to/pi-weave
 ```
 
-See [docs/design.md](docs/design.md) for the reasoning behind all of it.
+Requires Node **20.13 or newer**.
 
-## Install
+## Start taking notes
 
-```bash
-pi install npm:pi-weave                        # from npm (recommended)
-pi install git:github.com/EranYonai/pi-weave   # from git
-pi install /path/to/pi-weave                   # local path
+Talk to Pi normally:
+
+```text
+You: Start a note called Authentication migration.
+
+You: We probably want OIDC next quarter, but existing JWT clients need
+     a compatibility window.
+
+You: Add that the gateway team owns the migration plan.
+
+You: What open questions are in this note?
 ```
 
-Requires Node **>= 20.13.0**. For development against a checkout: `pi -e ./src/pi/index.ts`.
+For live narration or interview notes, tell Pi that you are dictating:
+
+```text
+You: Start a note for this interview. I’m going to narrate; keep my words
+     verbatim and organize the note as we go.
+```
 
-On session start pi-weave detects the repository you are in, checks whether `.okf` exists and is fresh, and reports it in the status footer
-— a filled `●` marks weave as active. An unindexed repository gets a one-line nudge; a stale one gets a warning.
+For each chunk, Pi:
 
-## Tools and commands
+1. appends your words unchanged to the note’s `## Raw` tail;
+2. refreshes the structured summary above it;
+3. leaves the raw record untouched.
 
-| Surface | Name | Purpose |
-|---|---|---|
-| Tool | `weave_note` | `list` / `get` / `add` / `append` / `finalize` / `search` over vault notes |
-| Tool | `weave_repo` | `status` / `scan` / `overview` of the `.okf` repository index |
-| Command | `/weave` | workspace dashboard (vault + repository) |
-| Command | `/weave-view` | open the knowledge workspace in your browser |
-| Command | `/weave-scan` | build or refresh the repository index (light) |
-| Command | `/weave-scan deep` | light index plus model-written per-file summaries (opt-in, incremental, background) |
-| Command | `/weave-scan sessions` | summarize pi session history into the vault as memory notes (incremental, background) |
-| Command | `/weave-scan-cancel` | stop an in-flight `/weave-scan deep` or `sessions` run |
-| Skill | `weave-notepad` | how the agent should take good notes |
-| Skill | `weave-explore` | how the agent should explore repositories |
-
-`/weave-scan deep` refreshes the light index and then writes a short model summary per file to `.okf/repository/summaries/`, skipping files
-whose content hash has not changed 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.
-
-`/weave-scan sessions` is the repo-agnostic sibling (docs/session-scan.md): it reads every pi session transcript under
-`~/.pi/agent/sessions/`, hashes each file while reading it, and writes one generated vault note per changed session under
-`~/.okf/notes/sessions/` — pi's memory as first-class, wikilinked notes in an inner folder of the vault graph. Unchanged transcripts cost no
-LLM calls at all, and older layouts migrate automatically on the next scan.
-
-## The workspace
-
-`/weave-view` opens a browser knowledge workspace over the same graph the tools see — the vault and the repository index as one model.
+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:
+
+| Say this | What happens |
+|---|---|
+| “Start a note about…” | Creates a Markdown note in the vault |
+| “Add this to the … note” | Finds the existing note and appends to it |
+| “Clean up” or “finalize this note” | Reorganizes the readable body and preserves the raw tail |
+| “What did we decide about…?” | Searches the vault, then reads the relevant notes |
+| “Remember that…” | Stores durable knowledge for a future session |
+
+## `/weave-view`
 
 ```bash
-/weave-view              # browser workspace (default), opens a tab
-/weave-view --no-open    # same server, just prints the URL
-/weave-view tui          # the in-terminal explorer instead
+/weave-view              # open the browser workspace
+/weave-view --no-open    # start it and print the URL
+/weave-view tui          # terminal UI for SSH or browser-free use
 ```
 
-Three resizable columns and a context rail:
+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`.
+- **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.
 
-- **Tree** — an expandable containment tree over notes and repository structure, with a filter box and provenance cycling.
-- **Note** — the selected note rendered with [marked](https://marked.js.org) and sanitised with DOMPurify. `[[wikilinks]]` navigate inside
-  the workspace; links with no target render as ghosts rather than dead text.
-- **Graph** — [sigma.js](https://www.sigmajs.org) v3 on WebGL with a [d3-force](https://d3js.org/d3-force) layout: neighbourhood highlight
-  on selection, semantic zoom that reveals labels as you go in, and cluster collapse as real graph reduction rather than hiding.
-- **Context rail** — links, backlinks, tags and mentions for whatever is selected, every entry clickable.
+The browser is read-only. Edit with `$EDITOR`, Obsidian, or the `weave_note` tool; unknown front-matter fields remain preserved.
 
-Selecting anywhere highlights everywhere: the tree, the note body, the graph and the rail are lenses onto one selection. Updates arrive live
-over SSE as files change on disk, so an agent writing a note shows up without a refresh.
+`/weave-view tui` is the smaller, read-only terminal explorer: tree, focused neighborhood, details, and link health over the same graph.
 
-`⌘K` opens a search palette spanning both faces (notes ranked with snippets, repository nodes by label). The whole workspace is keyboard
-drivable — `⌘1/2/3` focus a column, `/` filters the tree, `g` fits the graph, `Esc` clears, and `?` lists the rest. Column widths persist.
+## Repository knowledge
 
-The workspace is **read-first**, but no longer read-only. `⌘E` toggles the note column between read and edit, `⌘S` saves, and every save
-carries the revision read at load — a stale one gets a `409` and a choice of reload, overwrite or keep editing. The draft is never silently
-discarded or clobbered: a remote change arriving over SSE for the note you are editing is recorded rather than applied, and comes back as
-that same `409` when you save.
+Inside a Git repository, pi-weave detects whether `<repo>/.okf/` is missing, fresh, or stale.
 
-Front matter the engine does not own survives a browser save **byte-identically** — `aliases`, `cssclass` and a `tags:` block list all come
-back unchanged and in place, with `updated:` the only line a save moves. That is the P5 exit criterion, and
-`tests/web/editor.roundtrip.test.ts` drives it through the real client, over a real socket, into a real vault — it is what makes editing
-here safe alongside Obsidian.
+```bash
+/weave-scan         # fast structural index
+/weave-scan deep    # also summarize changed files with the active model
+```
 
-Rename and delete have routes, client functions and tests but **no UI**, deliberately: the vault has no trash, so the confirmation flow
-around a destructive button is a design decision rather than a wiring task. Notes are still authorable through the `weave_note` tool or by
-hand, and the note toolbar's "Open in $EDITOR" hands the file to yours. `/weave-view tui` is the read-only in-terminal explorer — the same
-model, a containment tree, a 1-hop focus view, node detail and a link-health surface, for when you are on the far end of an SSH session.
+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 local server
+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 workspace server is deliberately small and deliberately paranoid, because loopback is not an authorisation boundary — any local process
-can reach the port, and any website you visit can try to via DNS rebinding. Four layers:
+## Commands and tools
 
-1. Binds `127.0.0.1` on an ephemeral port. Never `0.0.0.0`.
-2. A `Host` header allowlist (`127.0.0.1:PORT`, `localhost:PORT`, `[::1]:PORT`), which is what actually stops rebinding.
-3. A 256-bit per-session token, handed off once in the URL and exchanged for an `HttpOnly; SameSite=Strict` cookie via a redirect that drops
-   it from the address bar. Compared in constant time.
-4. `Origin` validated when present, and required on anything that is not a `GET` or `HEAD`.
+Most people only need natural language and `/weave-view`.
 
-The page is served under a nonce-only CSP — `default-src 'none'`, no `unsafe-inline`, no `unsafe-eval`, no CORS headers at all. The server
-shuts itself down after 30 minutes with no client attached, and always at the end of the pi session.
+| Surface | Name | Purpose |
+|---|---|---|
+| Command | `/weave-view` | Open the browser or terminal workspace |
+| Command | `/weave` | Show vault and repository status |
+| Command | `/weave-scan` | Build or refresh the repository index |
+| Command | `/weave-scan deep` | Add incremental model-written file summaries |
+| Command | `/weave-scan-cancel` | Stop a deep scan |
+| Tool | `weave_note` | List, read, add, append, finalize, and search notes |
+| Tool | `weave_repo` | Check, scan, and summarize the repository index |
 
-## The formats
+The included `weave-notepad` and `weave-explore` skills teach Pi when and how to use these tools.
 
-Vault note (`~/.okf/notes/auth-boundary.md`):
+## Files, privacy, and portability
 
-```markdown
+Personal notes are ordinary Markdown files:
+
+```text
+~/.okf/
+└── notes/
+    ├── authentication-migration.md
+    └── release-plan.md
+```
+
+A note has small YAML front matter followed by Markdown:
+
+````markdown
 ---
-title: Auth boundary decision
+title: Authentication migration
 created: 2026-08-22T09:00:00.000Z
 updated: 2026-08-22T09:30:00.000Z
 tags: [auth, security]
 source: human
 ---
 
-JWT validation happens at the gateway because…
-```
-
-Repository index (`<repo>/.okf/`):
+## Summary
 
-```text
-.okf/
-├── okf.json            # format version + generator + source: generated
-└── repository/
-    ├── identity.json   # name, remotes, default branch
-    ├── git.json        # HEAD sha + branch + changed-file content hashes (staleness anchor)
-    └── structure.json  # languages, packages, modules, entry points
-```
+Move toward OIDC while keeping a JWT compatibility window.
 
-The `.okf` index is **derived**: delete it, rescan, lose nothing. By default it is excluded from git locally (`.git/info/exclude`);
-committing it to share with a team is a deliberate opt-in. The vault location can be overridden with `PI_WEAVE_VAULT`.
-
-## Zero runtime dependencies
-
-`package.json` declares no `dependencies`. The four peers (`@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`,
-`@earendil-works/pi-tui`, `typebox`) are supplied by the pi harness, which loads `src/pi/index.ts` as TypeScript directly — installing
-pi-weave runs no build step.
+---
 
-The browser client cannot work that way, so preact, sigma, graphology, d3-force, marked and DOMPurify are **devDependencies** bundled into a
-committed artifact at `src/web/client/dist/app.js`. They are inputs to a build, not runtime requirements of the package.
+## Raw
+<!-- NEVER edit below this line. Verbatim user input preserved here. -->
 
-## For other agent harnesses
+```
+We probably want OIDC next quarter…
+```
+````
 
-The skills follow the [Agent Skills standard](https://agentskills.io/specification), and the on-disk artefacts and `src/core` are
-harness-agnostic by design: `src/core` may not import anything pi-specific. Claude Code and opencode adapters are on the roadmap
-([docs/design.md](docs/design.md) §21).
+Set `PI_WEAVE_VAULT` to use a different vault location.
 
-## Documentation
+Reading, writing, searching, and viewing notes are local operations. Deep repository scans 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.
 
-| Where | What |
-|---|---|
-| [docs/design.md](docs/design.md) | the design document — *why* pi-weave is shaped this way |
-| [docs/weave-workspace.md](docs/weave-workspace.md) | the browser workspace: library choices with measurements, security model, phases |
-| [docs/weave-view-tui-design.md](docs/weave-view-tui-design.md) | the in-terminal explorer |
-| [AGENTS.md](AGENTS.md) | contributor and agent rules — read before changing anything |
+The vault format, repository index, and skills are intentionally harness-agnostic. `src/core` contains no pi-specific imports.
 
 ## Development
 
 ```bash
 npm install
-npm run typecheck   # tsc --noEmit, strict, both projects
-npm test            # vitest run
-npm run coverage    # the 95% gate (lines, branches, functions, statements)
-npm run build:web   # rebuild the committed browser bundle
-npm run check       # typecheck + bundle drift check + coverage — run this before committing
+npm run check
 ```
 
-Two rules worth knowing before you send a patch. Coverage must stay at or above **95%** on every metric; the gate is enforced by vitest
-thresholds and `npm run check` fails below it. And the committed web bundle must match its source — `npm run check` rebuilds it in memory
-and byte-compares, so run `npm run build:web` and commit the result whenever you touch `src/web/`.
+Useful individual commands:
+
+```bash
+npm run typecheck
+npm test
+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`.
+
+Read [AGENTS.md](AGENTS.md) before contributing. Work on a feature branch; do not commit directly to `main`.
+
+## More detail
 
-Never commit to `main`; branch, then open a PR. See [AGENTS.md](AGENTS.md) for the rest.
+- [Design](docs/design.md) — product and architecture
+- [Notepad skill](skills/weave-notepad/SKILL.md) — capture, narration, and provenance behavior
+- [Historical browser workspace notes](docs/weave-workspace.md) — superseded implementation record
+- [Repository exploration skill](skills/weave-explore/SKILL.md) — how Pi uses the index
 
-## Licence
+## License
 
-[MIT](LICENSE).
+[MIT](LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-weave",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "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,
@@ -64,7 +64,6 @@
     "@earendil-works/pi-ai": "^0.84.2",
     "@earendil-works/pi-coding-agent": "^0.84.2",
     "@earendil-works/pi-tui": "^0.84.2",
-    "@preact/signals": "^2.11.1",
     "@types/d3-force": "^3.0.10",
     "@types/node": "^24.0.0",
     "@vitest/coverage-v8": "^3.2.4",

package/src/core/cache/workspace.ts

@@ -33,7 +33,7 @@ import { buildGraph, DEFAULT_MAX_NOTES, type BuildGraphInput } from "../graph/bu
 import type { GraphModel } from "../graph/model";
 import { readRepositorySide } from "../graph/current";
 import { withMutationQueue } from "../mutex";
-import { getNote, statNotes } from "../vault";
+import { getNote, listNoteFolders, statNotes } from "../vault";
 import type { Note } from "../types";
 
 /**
@@ -136,11 +136,16 @@ function classify(
 ): { scope: InvalidationScope; slug: string | null } {
   const path = resolve(absPath);
   const rel = relative(resolve(opts.vaultRoot, NOTES_DIR), path);
-  // Directly inside the notes dir (flat vault: no separator in the relative
-  // path) and Markdown — anything else in there is not a note.
-  if (rel.length > 0 && !rel.startsWith("..") && !isAbsolute(rel) && !rel.includes(sep)) {
-    if (rel.endsWith(".md")) return { scope: "vault", slug: rel.slice(0, -".md".length) };
-    return { scope: "none", slug: null };
+  if (rel.length > 0 && !rel.startsWith("..") && !isAbsolute(rel)) {
+    if (rel.endsWith(".md")) {
+      const slug = rel.slice(0, -".md".length).split(sep).join("/");
+      return { scope: "vault", slug };
+    }
+    const base = rel.split(sep).pop() ?? rel;
+    if (base.startsWith(".") || (base.includes(".") && !base.endsWith(".md"))) {
+      return { scope: "none", slug: null };
+    }
+    return { scope: "vault", slug: null };
   }
   return { scope: within(path, resolve(opts.cwd)) ? "repo" : "none", slug: null };
 }
@@ -179,6 +184,7 @@ export class WorkspaceCache {
    * matches the uncached build exactly.
    */
   private fileCount = 0;
+  private folders: string[] = [];
   private repo: CachedRepo | null = null;
   /**
    * The last snapshot handed out, reused verbatim when a build proves nothing
@@ -368,7 +374,12 @@ export class WorkspaceCache {
       // graph has no node for (§4.3).
       const kept = notes.slice(0, DEFAULT_MAX_NOTES);
       const input: BuildGraphInput = {
-        vault: { root: this.vaultRoot, exists: true, noteCount: this.fileCount },
+        vault: {
+          root: this.vaultRoot,
+          exists: true,
+          noteCount: this.fileCount,
+          ...(this.folders.length > 0 ? { folders: this.folders } : {}),
+        },
         notes: kept,
         repository: repo?.repository ?? null,
       };
@@ -418,7 +429,9 @@ export class WorkspaceCache {
    * that disappeared are evicted, so the map never outgrows the vault.
    */
   private async refreshNotes(): Promise<Note[]> {
-    const stats = await statNotes(this.vaultRoot);
+    const previousFolders = this.folders;
+    const [stats, folders] = await Promise.all([statNotes(this.vaultRoot), listNoteFolders(this.vaultRoot)]);
+    this.folders = folders;
     const previousCount = this.notes.size;
     const previousFileCount = this.fileCount;
     this.fileCount = stats.length;
@@ -446,7 +459,11 @@ export class WorkspaceCache {
     // A note vanished if the map shrank without a compensating read; the
     // file count moving covers a malformed file appearing or disappearing,
     // which changes the vault node's `notes` detail without ever parsing.
-    this.notesChanged = read > 0 || next.size !== previousCount || this.fileCount !== previousFileCount;
+    const foldersChanged =
+      folders.length !== previousFolders.length ||
+      folders.some((f, i) => f !== previousFolders[i]);
+    this.notesChanged =
+      read > 0 || next.size !== previousCount || this.fileCount !== previousFileCount || foldersChanged;
     this.notes = next;
     // `statNotes` yields readdir (slug-ascending) order and sort is stable,
     // so ties break by slug — identical to `readVault`.

package/src/core/concurrency.ts

@@ -1,10 +1,7 @@
 /**
- * Bounded-concurrency task runner shared by the deep scan (summaries.ts) and
- * the session scan (sessions.ts).
+ * Bounded-concurrency task runner shared by repository scans.
  *
- * Extracted from summaries.ts so the two scanners cannot drift: a second copy
- * of the scheduler is a second place for an off-by-one or a lost
- * cancellation check.
+ * Keeping the scheduler here gives every scan the same cancellation behavior.
  */
 
 /**
@@ -33,4 +30,4 @@ export async function mapWithConcurrency<T, R>(
   }
   await Promise.all(Array.from({ length: Math.max(1, concurrency) }, worker));
   return results;
-}
+}

package/src/core/frontmatter.ts

@@ -289,59 +289,6 @@ export function parseFrontMatter(text: string): ParsedFrontMatter | null {
   return { fields, body, lines };
 }
 
-/**
- * Upsert owned scalar fields into a front-matter block, preserving order.
- *
- * For each wanted key: the **first** line declaring it is replaced with a
- * fresh `key: value` line in place, and any later declarations are dropped —
- * mirroring how duplicate managed keys collapse in `replayBlock` (the
- * subset parser keeps the last occurrence, so collapsing to one line with
- * the fresh value is the consistent outcome). A key introducing a block
- * construct (`scalar: false`) is replaced too: the value this function writes
- * is a scalar, and leaving the old block head in place would orphan its
- * indented children under a duplicated key.
- *
- * Wanted keys the block never declared are appended at the end, in the order
- * given. Everything else — unknown keys, blank lines, junk — is carried
- * through byte-identically, the same round-trip contract `serializeNote`
- * honors for the note engine's writes.
- *
- * Keys arrive from pi-weave's own generated-note writers (`session_id`,
- * `session_hash`, …); there is no escaping for the *key* because a key is
- * caller-controlled code, not user input — `quoteField` guards the value.
- */
-export function upsertFrontMatterFields(
-  lines: NoteFrontMatter,
-  fields: Record<string, string>,
-): NoteFrontMatter {
-  const wanted = new Set(Object.keys(fields));
-  const out: string[] = [];
-  const written = new Set<string>();
-  let inDroppedBlock = false;
-  for (const line of scanFrontMatter(lines)) {
-    // Continuation lines of a block construct whose head we replaced: their
-    // parent key is gone, so carrying them would leave orphaned YAML children
-    // under a scalar. The block ends at the first non-indented line.
-    if (inDroppedBlock) {
-      if (/^\s/.test(line.text)) continue;
-      inDroppedBlock = false;
-    }
-    if (line.key !== null && wanted.has(line.key)) {
-      if (!written.has(line.key)) {
-        out.push(`${line.key}: ${quoteField(fields[line.key] ?? "")}`);
-        written.add(line.key);
-        if (!line.scalar) inDroppedBlock = true; // swallow the block body too
-      }
-      continue; // later duplicates collapse into the first occurrence
-    }
-    out.push(line.text);
-  }
-  for (const [key, value] of Object.entries(fields)) {
-    if (!written.has(key)) out.push(`${key}: ${quoteField(value)}`);
-  }
-  return out;
-}
-
 /**
  * Parse a note file. Throws on missing/invalid front matter so callers can
  * treat the file as malformed rather than guessing.

package/src/core/graph/build.ts

@@ -2,7 +2,7 @@
  * Pure graph builder: knowledge workspace inputs → GraphModel.
  *
  * No I/O, no clock access, no harness imports (design §21,
- * docs/weave-view.md §3). Stability contract: identical inputs produce
+ * docs/design.md §11). Stability contract: identical inputs produce
  * byte-identical JSON (ids derive from slugs/paths only; `generatedAt` is
  * derived from input timestamps, never from the wall clock) — that is what
  * makes the page's refresh-polling cheap.
@@ -15,7 +15,7 @@ import type { EdgeKind, GraphEdge, GraphModel, GraphNode } from "./model";
 import { buildPathIndex, resolveMentions, type PathIndex } from "./mentions";
 import { extractWikilinks } from "./wikilinks";
 
-/** Hard cap on note nodes (docs/weave-view.md M3 guard). */
+/** Hard cap on note nodes so a large vault cannot overwhelm the viewer. */
 export const DEFAULT_MAX_NOTES = 500;
 
 export interface BuildGraphInput {
@@ -133,14 +133,18 @@ function buildVaultSide(
 
   const keptSlugs = new Set(kept.map((n) => n.slug));
 
-  // Nested notes (`sessions/foo` — session memory, docs/session-scan.md) nest
-  // under synthesized folder nodes so the vault tree groups them the way the
-  // repository tree groups directories. Ids are prefixed `vfolder:` because a
-  // repository module could legitimately share the path (`module:sessions`);
+  // Nested notes nest under synthesized folder nodes so the vault tree groups
+  // them the way the repository tree groups directories. Ids are prefixed
+  // `vfolder:` because a repository module could legitimately share the path;
   // the tree renders any `contains` chain, so the kind reuse needs no client
   // change. Deterministic: dirs sorted, parents before children.
   const folderIds = new Map<string, string>();
-  const noteDirs = [...new Set(kept.map((n) => n.slug.split("/").slice(0, -1).join("/")))]
+  const noteDirs = [
+    ...new Set([
+      ...(input.vault.folders ?? []),
+      ...kept.map((n) => n.slug.split("/").slice(0, -1).join("/")),
+    ]),
+  ]
     .filter((d) => d.length > 0)
     .sort();
   const notesIn = (dir: string): number => kept.filter((n) => n.slug.startsWith(`${dir}/`)).length;
@@ -315,7 +319,7 @@ function buildRepositorySide(
 
 /**
  * Build the graph model for the viewer. Notes are capped at `maxNotes`
- * (docs/weave-view.md M3); the vault node carries a warning when truncated.
+ * (docs/design.md §11); the vault node carries a warning when truncated.
  */
 export function buildGraph(input: BuildGraphInput, options: { maxNotes?: number } = {}): GraphModel {
   const maxNotes = options.maxNotes ?? DEFAULT_MAX_NOTES;

package/src/core/graph/current.ts

@@ -1,6 +1,5 @@
 /**
- * Workspace assembly readers for the viewers (docs/weave-view.md §2,
- * weave-view-tui-design §3.1).
+ * Workspace assembly readers for the viewers (docs/design.md §11).
  *
  * These functions are *workspace assembly*, symmetric to `getWorkspaceStatus`
  * (already in core): pure fan-out over `core/vault`, `core/repoIndex`,
@@ -92,7 +91,7 @@ export async function readRepositorySide(
 
 /**
  * Assemble the fresh graph from disk. Called on every viewer fetch
- * (no caching — docs/weave-view.md §2). Reads the vault (capped at
+ * (no caching). Reads the vault (capped at
  * DEFAULT_MAX_NOTES) and, when cwd is an indexed git repository, the repo
  * index + deep-scan summary sidecars. Degrades to a vault-only graph when
  * the repo has no index or the index is corrupt.
@@ -102,10 +101,10 @@ export async function readRepositorySide(
  * a third readdir) is now N reads and one readdir (weave-workspace §4.1).
  */
 export async function buildCurrentGraph(cwd: string, vaultRoot: string = resolveVaultRoot()): Promise<GraphModel> {
-  const { notes, fileCount } = await readVault(vaultRoot);
+  const { notes, fileCount, folders } = await readVault(vaultRoot);
 
   const input: BuildGraphInput = {
-    vault: { root: vaultRoot, exists: true, noteCount: fileCount },
+    vault: { root: vaultRoot, exists: true, noteCount: fileCount, ...(folders ? { folders } : {}) },
     notes: notes.slice(0, DEFAULT_MAX_NOTES),
     repository: null,
   };
@@ -117,4 +116,3 @@ export async function buildCurrentGraph(cwd: string, vaultRoot: string = resolve
   }
   return buildGraph(input);
 }
-

package/src/core/graph/model.ts

@@ -1,6 +1,6 @@
 /**
  * Graph model shared between the builder (core) and the viewer (adapter).
- * Pure data — no harness imports (design §21). See docs/weave-view.md §3.
+ * Pure data — no harness imports (design §21).
  */
 
 import type { NoteSource, StalenessReport } from "../types";

package/src/core/graph/wikilinks.ts

@@ -1,6 +1,6 @@
 /**
  * Obsidian-compatible [[wiki-link]] extraction from note bodies.
- * Pure module — see docs/weave-view.md §3.
+ * Pure module used by graph construction and viewer view-models.
  */
 
 import { slugify } from "../slug";
@@ -14,8 +14,8 @@ const WIKILINK_RE = /\[\[([^\][|]+)(?:\|[^\]]*)?\]\]/g;
  * `release-plan`. Duplicates are removed, order of first appearance kept.
  *
  * Path separators survive: a nested note's slug is its path relative to
- * `notes/` (`sessions/foo`), so `[[sessions/foo]]` targets the session note,
- * not a flattened name. Each path segment is slugified independently.
+ * `notes/`, so links target the nested note rather than a flattened name.
+ * Each path segment is slugified independently.
  */
 export function extractWikilinks(body: string): string[] {
   const out: string[] = [];