pi-weave 0.1.12 → 0.1.14

package/README.md

@@ -27,7 +27,6 @@ It also understands the repository you are working in. Personal notes live in a
   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` converts prior pi sessions into searchable notes and skips unchanged transcripts.
 - **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.
@@ -98,42 +97,18 @@ Useful requests include:
 
 The browser workspace has four connected views:
 
-- **Tree** — notes, folders, session memories, and repository structure. Filter by text or provenance, create folders, drag notes between
-  folders, and use the context menu to rename or delete.
-- **Note** — rendered Markdown with clickable `[[wikilinks]]`, link previews, tags, and authorship. Click the body or press `⌘E` / `Ctrl E`
-  to edit; save with `⌘S` / `Ctrl S`.
+- **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.
 
-The editor checks revisions before saving. If the note changed elsewhere, it asks whether to reload or overwrite instead of silently losing
-work. Unknown front-matter fields are preserved, so the same vault remains safe to edit with Obsidian or a text editor.
+The browser is read-only. Edit with `$EDITOR`, Obsidian, or the `weave_note` tool; unknown front-matter fields remain preserved.
 
 `/weave-view tui` is the smaller, read-only terminal explorer: tree, focused neighborhood, details, and link health over the same graph.
 
-## Remember past pi sessions
-
-```bash
-/weave-scan sessions
-```
-
-This reads pi’s local session transcripts and creates generated notes under:
-
-```text
-~/.okf/notes/sessions/
-```
-
-Each note records what was asked, what happened, and any open threads. The scan is:
-
-- **opt-in** — it never runs automatically;
-- **incremental** — unchanged transcripts use no model calls;
-- **cancellable** — run `/weave-scan-cancel`;
-- **repo-independent** — it works from any directory.
-
-Session summaries use the active pi model and are marked `source: generated`.
-
 ## Repository knowledge
 
 Inside a Git repository, pi-weave detects whether `<repo>/.okf/` is missing, fresh, or stale.
@@ -159,8 +134,7 @@ Most people only need natural language and `/weave-view`.
 | 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 sessions` | Turn pi session history into vault notes |
-| Command | `/weave-scan-cancel` | Stop a deep or session scan |
+| 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 |
 
@@ -174,8 +148,7 @@ Personal notes are ordinary Markdown files:
 ~/.okf/
 └── notes/
     ├── authentication-migration.md
-    └── sessions/
-        └── plan-the-release.md
+    └── release-plan.md
 ```
 
 A note has small YAML front matter followed by Markdown:
@@ -205,9 +178,8 @@ 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 their 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 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.
 
@@ -236,8 +208,7 @@ Read [AGENTS.md](AGENTS.md) before contributing. Work on a feature branch; do no
 
 - [Design](docs/design.md) — product and architecture
 - [Notepad skill](skills/weave-notepad/SKILL.md) — capture, narration, and provenance behavior
-- [Browser workspace](docs/weave-workspace.md) — UI architecture and security model
-- [Session scanning](docs/session-scan.md) — incremental session memory
+- [Historical browser workspace notes](docs/weave-workspace.md) — superseded implementation record
 - [Repository exploration skill](skills/weave-explore/SKILL.md) — how Pi uses the index
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-weave",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "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,8 +33,8 @@ 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, listNoteFolders, statNotes } from "../vault";
-import type { Note } from "../types";
+import { getHtmlArtifact, getNote, listNoteFolders, statNotes } from "../vault";
+import type { HtmlArtifact, Note } from "../types";
 
 /**
  * One build's outputs: the graph, and the notes it was built from.
@@ -53,6 +53,8 @@ export interface WorkspaceSnapshot {
    * caller mutating it would corrupt the next build.
    */
   notes: readonly Note[];
+  /** Exactly the HTML artifacts represented by the graph. */
+  artifacts: readonly HtmlArtifact[];
 }
 
 /** Cumulative counters, from construction. Callers take deltas. */
@@ -74,6 +76,12 @@ interface CachedNote {
   note: Note;
 }
 
+interface CachedArtifact {
+  mtimeMs: number;
+  size: number;
+  artifact: HtmlArtifact;
+}
+
 /** The repository half, held behind a TTL because assessing it spawns git. */
 interface CachedRepo {
   /** Wall-clock ms (from the injected clock) when this was captured. */
@@ -107,8 +115,8 @@ export type InvalidationScope = "vault" | "repo" | "none";
  * whether an event is worth forwarding at all, and one implementation means
  * the two can never disagree.
  *
- *  - `vault`: a `*.md` under `<vaultRoot>/notes/`. Only note files count —
- *    the vault manifest does not participate in the graph.
+ *  - `vault`: a `*.md`, `*.html`, or `*.htm` under `<vaultRoot>/notes/`. Only
+ *    vault artifacts count — the vault manifest does not participate in graph.
  *  - `repo`:  anything under `<cwd>/.okf/` (the derived index and its summary
  *    sidecars) or under `<cwd>/.git/` (HEAD moves, staged changes), plus any
  *    tracked file in the repo, since editing one makes the index stale.
@@ -141,6 +149,9 @@ function classify(
       const slug = rel.slice(0, -".md".length).split(sep).join("/");
       return { scope: "vault", slug };
     }
+    if (rel.toLowerCase().endsWith(".html") || rel.toLowerCase().endsWith(".htm")) {
+      return { scope: "vault", slug: rel.split(sep).join("/") };
+    }
     const base = rel.split(sep).pop() ?? rel;
     if (base.startsWith(".") || (base.includes(".") && !base.endsWith(".md"))) {
       return { scope: "none", slug: null };
@@ -178,12 +189,14 @@ export class WorkspaceCache {
   private readonly stalenessTtlMs: number;
 
   private notes = new Map<string, CachedNote>();
+  private artifacts = new Map<string, CachedArtifact>();
   /**
    * `.md` files present at the last refresh, including ones too malformed to
    * parse — mirrors `readVault().fileCount` so the vault node's note count
-   * matches the uncached build exactly.
+   * matches the uncached build exactly. HTML artifacts have a separate count.
    */
   private fileCount = 0;
+  private artifactCount = 0;
   private folders: string[] = [];
   private repo: CachedRepo | null = null;
   /**
@@ -229,8 +242,8 @@ export class WorkspaceCache {
   private repoDirtiedDuringBuild = false;
   private building = false;
   /**
-   * Whether the last {@link refreshNotes} observed any note-side movement:
-   * a file read, a note that disappeared, or a change in the raw `.md` count.
+   * Whether the last {@link refreshNotes} observed any vault-side movement:
+   * a file read, a file that disappeared, or a change in raw file counts.
    * Read by {@link build} to decide whether {@link lastSnapshot} is reusable.
    */
   private notesChanged = true;
@@ -299,7 +312,8 @@ export class WorkspaceCache {
   invalidate(absPath: string): void {
     const { scope, slug } = classify(absPath, { cwd: this.cwd, vaultRoot: this.vaultRoot });
     if (scope === "vault" && slug !== null) {
-      this.notes.delete(slug);
+      if (slug.toLowerCase().endsWith(".html") || slug.toLowerCase().endsWith(".htm")) this.artifacts.delete(slug);
+      else this.notes.delete(slug);
       if (this.building) this.evictedDuringBuild.add(slug);
     } else if (scope === "repo") {
       this.repo = null;
@@ -310,6 +324,7 @@ export class WorkspaceCache {
   /** Drop everything: a repo scan landed, or the vault root moved. */
   invalidateAll(): void {
     this.notes.clear();
+    this.artifacts.clear();
     this.repo = null;
     if (this.building) {
       // Whatever the in-flight build writes back was read before this call,
@@ -336,7 +351,8 @@ export class WorkspaceCache {
     this.allEvictedDuringBuild = false;
     this.repoDirtiedDuringBuild = false;
     try {
-      const notes = await this.refreshNotes();
+      const refreshed = await this.refreshNotes();
+      const notes = refreshed.notes;
       const repoFresh = this.repoNeedsRefresh();
       const repo = await this.refreshRepo();
 
@@ -379,15 +395,21 @@ export class WorkspaceCache {
           exists: true,
           noteCount: this.fileCount,
           ...(this.folders.length > 0 ? { folders: this.folders } : {}),
+          ...(this.artifactCount > 0 ? { artifactCount: this.artifactCount } : {}),
         },
         notes: kept,
+        artifacts: refreshed.artifacts,
         repository: repo?.repository ?? null,
       };
       if (repo?.summaries !== undefined) input.summaries = repo.summaries;
 
       this.gitCalls += gitSpawnCount() - spawnsBefore;
       this.builtAt = this.now().toISOString();
-      const snapshot: WorkspaceSnapshot = { model: buildGraph(input), notes: Object.freeze(kept) };
+      const snapshot: WorkspaceSnapshot = {
+        model: buildGraph(input),
+        notes: Object.freeze(kept),
+        artifacts: Object.freeze(input.artifacts ?? []),
+      };
       this.lastSnapshot = snapshot;
       return snapshot;
     } finally {
@@ -416,8 +438,15 @@ export class WorkspaceCache {
    * something else touches it.
    */
   private applyDeferredInvalidations(): void {
-    if (this.allEvictedDuringBuild) this.notes.clear();
-    else for (const slug of this.evictedDuringBuild) this.notes.delete(slug);
+    if (this.allEvictedDuringBuild) {
+      this.notes.clear();
+      this.artifacts.clear();
+    } else {
+      for (const slug of this.evictedDuringBuild) {
+        if (/\.html?$/i.test(slug)) this.artifacts.delete(slug);
+        else this.notes.delete(slug);
+      }
+    }
     if (this.repoDirtiedDuringBuild) this.repo = null;
     this.evictedDuringBuild.clear();
     this.allEvictedDuringBuild = false;
@@ -428,18 +457,40 @@ export class WorkspaceCache {
    * Stat every note; re-read only the ones whose mtime or size moved. Notes
    * that disappeared are evicted, so the map never outgrows the vault.
    */
-  private async refreshNotes(): Promise<Note[]> {
+  private async refreshNotes(): Promise<{ notes: Note[]; artifacts: HtmlArtifact[] }> {
     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 previousArtifactCount = this.artifacts.size;
     const previousFileCount = this.fileCount;
-    this.fileCount = stats.length;
+    const previousRawArtifactCount = this.artifactCount;
+    this.fileCount = stats.filter((st) => st.path.toLowerCase().endsWith(".md")).length;
+    this.artifactCount = stats.filter((st) => /\.html?$/i.test(st.path)).length;
     let read = 0;
 
     const next = new Map<string, CachedNote>();
+    const nextArtifacts = new Map<string, CachedArtifact>();
     const out: Note[] = [];
+    const artifactOut: HtmlArtifact[] = [];
     for (const st of stats) {
+      if (/\.html?$/i.test(st.path)) {
+        const hit = this.artifacts.get(st.slug);
+        if (hit !== undefined && hit.mtimeMs === st.mtimeMs && hit.size === st.size) {
+          this.notesCached += 1;
+          nextArtifacts.set(st.slug, hit);
+          artifactOut.push(hit.artifact);
+          continue;
+        }
+        this.notesRead += 1;
+        read += 1;
+        const artifact = await getHtmlArtifact(this.vaultRoot, st.slug);
+        if (artifact === null) continue;
+        const cached = { mtimeMs: st.mtimeMs, size: st.size, artifact };
+        nextArtifacts.set(st.slug, cached);
+        artifactOut.push(artifact);
+        continue;
+      }
       const hit = this.notes.get(st.slug);
       if (hit !== undefined && hit.mtimeMs === st.mtimeMs && hit.size === st.size) {
         this.notesCached += 1;
@@ -463,11 +514,14 @@ export class WorkspaceCache {
       folders.length !== previousFolders.length ||
       folders.some((f, i) => f !== previousFolders[i]);
     this.notesChanged =
-      read > 0 || next.size !== previousCount || this.fileCount !== previousFileCount || foldersChanged;
+      read > 0 || next.size !== previousCount || nextArtifacts.size !== previousArtifactCount ||
+      this.fileCount !== previousFileCount || this.artifactCount !== previousRawArtifactCount || foldersChanged;
     this.notes = next;
+    this.artifacts = nextArtifacts;
+    const artifacts = artifactOut.sort((a, b) => b.updated.localeCompare(a.updated));
     // `statNotes` yields readdir (slug-ascending) order and sort is stable,
     // so ties break by slug — identical to `readVault`.
-    return out.sort((a, b) => b.updated.localeCompare(a.updated));
+    return { notes: out.sort((a, b) => b.updated.localeCompare(a.updated)), artifacts };
   }
 
   /** The repository half, re-assessed only when the TTL has expired. */

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,26 +2,28 @@
  * 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.
  */
 
-import type { Note, RepoIndex, StalenessReport, VaultStatus } from "../types";
+import type { HtmlArtifact, Note, RepoIndex, StalenessReport, VaultStatus } from "../types";
 import { createHash } from "node:crypto";
 import type { SummaryRecord } from "../summaries";
 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 {
   vault: VaultStatus;
   /** Full notes including bodies (for wiki-link extraction). */
   notes: Note[];
+  /** Standalone HTML/HTM artifacts under the vault's notes directory. */
+  artifacts?: HtmlArtifact[];
   /** Repository half; null when cwd is not an indexed git repository. */
   repository: { index: RepoIndex; staleness: StalenessReport } | null;
   /** Deep-scan summaries keyed by repo-relative path (docs/scan-modes.md). */
@@ -83,6 +85,9 @@ export function dataTimestamp(input: BuildGraphInput): string {
   for (const note of input.notes) {
     if (note.updated > max) max = note.updated;
   }
+  for (const artifact of input.artifacts ?? []) {
+    if (artifact.updated > max) max = artifact.updated;
+  }
   const repoStamp = input.repository?.index.updated ?? "";
   if (repoStamp > max) max = repoStamp;
   if (input.summaries) {
@@ -126,17 +131,22 @@ function buildVaultSide(
     root: input.vault.root,
     notes: String(input.vault.noteCount),
   };
+  const artifacts = input.artifacts ?? [];
+  if ((input.vault.artifactCount ?? artifacts.length) > 0) {
+    vaultDetail.artifacts = String(input.vault.artifactCount ?? artifacts.length);
+  }
   if (truncated) {
     vaultDetail.warning = `Graph shows the ${maxNotes} most recent notes — the vault holds ${input.vault.noteCount}. Wiki-links to older notes are omitted.`;
   }
   nodes.push({ id: "vault", kind: "vault", label: "Vault", provenance: null, detail: vaultDetail });
 
   const keptSlugs = new Set(kept.map((n) => n.slug));
+  const artifactSlugs = new Set(artifacts.map((a) => a.slug));
+  const artifactLinks = new Map<string, number>();
 
-  // 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>();
@@ -144,6 +154,7 @@ function buildVaultSide(
     ...new Set([
       ...(input.vault.folders ?? []),
       ...kept.map((n) => n.slug.split("/").slice(0, -1).join("/")),
+      ...artifacts.map((a) => a.slug.split("/").slice(0, -1).join("/")),
     ]),
   ]
     .filter((d) => d.length > 0)
@@ -180,7 +191,7 @@ function buildVaultSide(
     // The names, not just the count (§4.2). `detail` keeps carrying the count
     // because it is what the TUI's side panel prints; the structured targets
     // go on the model, where a UI can turn them into ghost nodes.
-    const dangling = links.filter((slug) => !keptSlugs.has(slug));
+    const dangling = links.filter((slug) => !keptSlugs.has(slug) && !artifactSlugs.has(slug));
     if (dangling.length > 0) {
       detail["dangling links"] = String(dangling.length);
       danglingLinks[note.slug] = dangling;
@@ -192,6 +203,10 @@ function buildVaultSide(
     for (const target of resolved) {
       edges.push({ source: `note:${note.slug}`, target: `note:${target}`, kind: "links-to" });
     }
+    for (const target of links.filter((slug) => artifactSlugs.has(slug))) {
+      edges.push({ source: `note:${note.slug}`, target: `artifact:${target}`, kind: "links-to" });
+      artifactLinks.set(target, (artifactLinks.get(target) ?? 0) + 1);
+    }
     // A note body naming a repo path → `mentions` (§4.4). Emitted after the
     // wiki-links so a note's edges read vault-ward first, then code-ward, and
     // only for paths that are already nodes — `paths` is built from the repo
@@ -201,6 +216,21 @@ function buildVaultSide(
       edges.push({ source: `note:${note.slug}`, target, kind: "mentions" });
     }
   }
+  for (const artifact of artifacts) {
+    const dir = artifact.slug.split("/").slice(0, -1).join("/");
+    const parent = (dir.length > 0 && folderIds.get(dir)) || "vault";
+    const detail: Record<string, string> = {
+      path: artifact.slug,
+      title: artifact.title,
+      updated: artifact.updated,
+      size: `${artifact.size} bytes`,
+    };
+    if (artifact.description) detail.description = artifact.description;
+    const links = artifactLinks.get(artifact.slug) ?? 0;
+    if (links > 0) detail["link references"] = String(links);
+    nodes.push({ id: `artifact:${artifact.slug}`, kind: "file", label: artifact.title, provenance: null, detail });
+    edges.push({ source: parent, target: `artifact:${artifact.slug}`, kind: "contains" });
+  }
   return [...keptSlugs];
 }
 
@@ -320,7 +350,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,11 +101,18 @@ 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, folders } = await readVault(vaultRoot);
+  const { notes, fileCount, folders, artifacts, artifactCount } = await readVault(vaultRoot);
 
   const input: BuildGraphInput = {
-    vault: { root: vaultRoot, exists: true, noteCount: fileCount, ...(folders ? { folders } : {}) },
+    vault: {
+      root: vaultRoot,
+      exists: true,
+      noteCount: fileCount,
+      ...(folders ? { folders } : {}),
+      ...(artifactCount ? { artifactCount } : {}),
+    },
     notes: notes.slice(0, DEFAULT_MAX_NOTES),
+    ...(artifacts ? { artifacts } : {}),
     repository: null,
   };
 
@@ -117,4 +123,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[] = [];
@@ -23,7 +23,11 @@ export function extractWikilinks(body: string): string[] {
   for (const match of body.matchAll(WIKILINK_RE)) {
     const raw = (match[1] ?? "").trim();
     if (raw.length === 0) continue;
-    const slug = raw.split("/").map((part) => slugify(part)).join("/");
+    // HTML artifacts are addressed by their vault-relative filename; unlike a
+    // Markdown note, the extension is part of the stable identity.
+    const slug = /\.html?$/i.test(raw)
+      ? raw.replace(/\\/g, "/").replace(/^\.\//, "")
+      : raw.split("/").map((part) => slugify(part)).join("/");
     if (seen.has(slug)) continue;
     seen.add(slug);
     out.push(slug);