pi-weave 0.1.13 → 0.1.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-weave",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "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/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/graph/build.ts

@@ -8,7 +8,7 @@
  * 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";
@@ -22,6 +22,8 @@ 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,12 +131,18 @@ 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 nest under synthesized folder nodes so the vault tree groups
   // them the way the repository tree groups directories. Ids are prefixed
@@ -143,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)
@@ -179,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;
@@ -191,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
@@ -200,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];
 }
 

package/src/core/graph/current.ts

@@ -101,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,
   };
 

package/src/core/graph/wikilinks.ts

@@ -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);

package/src/core/index.ts

@@ -21,11 +21,15 @@ export {
   finalizeNote,
   formatNote,
   formatRawAppend,
+  getHtmlArtifact,
   getNote,
   listNotes,
+  parseHtmlArtifact,
+  resolveHtmlPath,
   resolveNotePath,
   searchNotes,
 } from "./vault";
+export type { HtmlArtifact } from "./types";
 export { withMutationQueue } from "./mutex";
 export { formatDashboard, formatStatusLine, getWorkspaceStatus } from "./workspace";
 export { WorkspaceCache } from "./cache/workspace";

package/src/core/types.ts

@@ -69,6 +69,17 @@ export interface Note extends NoteMeta {
   frontMatter?: NoteFrontMatter;
 }
 
+/** A standalone HTML artifact discovered under the vault's notes directory. */
+export interface HtmlArtifact {
+  /** Vault-relative path, including the `.html`/`.htm` extension. */
+  slug: string;
+  title: string;
+  description: string;
+  /** ISO mtime and byte size, used for graph display and cache invalidation. */
+  updated: string;
+  size: number;
+}
+
 /** Summary of one note for list/search output. */
 export interface NoteSummary extends NoteMeta {
   slug: string;
@@ -175,6 +186,8 @@ export interface VaultStatus {
   exists: boolean;
   noteCount: number;
   folders?: string[];
+  /** Number of discovered HTML/HTM artifacts. */
+  artifactCount?: number;
 }
 
 /** Status of the repository half of the workspace. */

package/src/core/vault.ts

@@ -1,16 +1,18 @@
 import { existsSync } from "node:fs";
 import { promises as fs } from "node:fs";
-import { dirname, isAbsolute, join, relative } from "node:path";
+import { basename, dirname, isAbsolute, join, relative } from "node:path";
 import {
   parseFrontMatter,
   parseNoteFile,
   serializeNote,
+  unquoteField,
 } from "./frontmatter";
 import { withMutationQueue } from "./mutex";
 import { NOTES_DIR, OKF_MANIFEST } from "./paths";
 import { slugify, uniqueSlug } from "./slug";
 import type {
   Note,
+  HtmlArtifact,
   NoteFrontMatter,
   NoteMeta,
   NoteSearchHit,
@@ -345,26 +347,127 @@ export async function finalizeNote(
   });
 }
 
-async function listNoteFiles(root: string): Promise<string[]> {
+async function listVaultEntries(root: string): Promise<{ files: string[]; folders: string[] }> {
   const dir = join(root, NOTES_DIR);
-  const out: string[] = [];
-  async function walk(prefix: string): Promise<void> {
+  const files: string[] = [];
+  const folders: string[] = [];
+  const seen = new Set<string>();
+  async function walk(prefix: string, includeFolders = true): Promise<boolean> {
+    const path = prefix.length > 0 ? join(dir, prefix) : dir;
+    let realPath: string;
     let entries;
     try {
-      entries = await fs.readdir(prefix.length > 0 ? join(dir, prefix) : dir, { withFileTypes: true });
+      realPath = await fs.realpath(path);
+      if (seen.has(realPath)) return false;
+      seen.add(realPath);
+      entries = await fs.readdir(path, { withFileTypes: true });
     } catch {
-      return;
+      return false;
     }
     for (const entry of entries) {
-      if (entry.isDirectory()) {
-        await walk(prefix.length > 0 ? `${prefix}/${entry.name}` : entry.name);
-      } else if (entry.isFile() && entry.name.endsWith(".md")) {
-        out.push(prefix.length > 0 ? `${prefix}/${entry.name}` : entry.name);
+      const child = prefix.length > 0 ? `${prefix}/${entry.name}` : entry.name;
+      let isDirectory = entry.isDirectory();
+      let isFile = entry.isFile();
+      if (entry.isSymbolicLink()) {
+        try {
+          const stat = await fs.stat(join(dir, child));
+          isDirectory = stat.isDirectory();
+          isFile = stat.isFile();
+        } catch {
+          continue;
+        }
+      }
+      if (isDirectory) {
+        const visible = includeFolders && !entry.name.startsWith(".");
+        if ((await walk(child, visible)) && visible) folders.push(child);
+      } else if (isFile && isVaultArtifact(entry.name)) {
+        files.push(child);
       }
     }
+    return true;
   }
   await walk("");
-  return out.sort();
+  return { files: files.sort(), folders: folders.sort() };
+}
+
+async function listNoteFiles(root: string): Promise<string[]> {
+  return (await listVaultEntries(root)).files;
+}
+
+function isMarkdown(path: string): boolean {
+  return path.endsWith(".md");
+}
+
+function isHtml(path: string): boolean {
+  return path.toLowerCase().endsWith(".html") || path.toLowerCase().endsWith(".htm");
+}
+
+function isVaultArtifact(path: string): boolean {
+  return isMarkdown(path) || isHtml(path);
+}
+
+/** Resolve a vault-relative HTML path without allowing traversal. */
+export function resolveHtmlPath(root: string, slug: string): string | null {
+  if (slug.trim().length === 0 || !isHtml(slug)) return null;
+  const notesDir = join(root, NOTES_DIR);
+  const candidate = join(notesDir, slug);
+  const rel = relative(notesDir, candidate);
+  return rel.startsWith("..") || isAbsolute(rel) || rel.length === 0 ? null : candidate;
+}
+
+function decodeHtml(value: string): string {
+  return value
+    .replace(/&amp;/gi, "&")
+    .replace(/&lt;/gi, "<")
+    .replace(/&gt;/gi, ">")
+    .replace(/&quot;/gi, '"')
+    .replace(/&#39;|&apos;/gi, "'")
+    .replace(/&#(\d+);/g, (_, n: string) => String.fromCodePoint(Number(n)));
+}
+
+function htmlTagValue(text: string, tag: string): string {
+  const match = new RegExp(`<${tag}\\b[^>]*>([\\s\\S]*?)<\\/${tag}>`, "i").exec(text);
+  return match?.[1] === undefined ? "" : decodeHtml(match[1].replace(/<[^>]+>/g, "").trim());
+}
+
+function htmlMeta(text: string, name: string): string {
+  for (const match of text.matchAll(/<meta\b([^>]*)>/gi)) {
+    const attrs = match[1] ?? "";
+    const get = (key: string): string => {
+      const value = new RegExp(`\\b${key}\\s*=\\s*([\\\"'])(.*?)\\1`, "i").exec(attrs);
+      return value?.[2] ? decodeHtml(value[2].trim()) : "";
+    };
+    if (get("name").toLowerCase() === name.toLowerCase()) return get("content");
+  }
+  return "";
+}
+
+/** Parse metadata from an HTML file without attempting to interpret its body. */
+export function parseHtmlArtifact(slug: string, text: string, updated = "", size = Buffer.byteLength(text)): HtmlArtifact {
+  const comment = /<!--[\s\S]*?---\n([\s\S]*?)\n---[\s\S]*?-->/m.exec(text);
+  const fields = comment ? parseFrontMatter(`---\n${comment[1]}\n---\n`)?.fields : undefined;
+  const fallback = basename(slug).replace(/\.html?$/i, "").replace(/[-_]+/g, " ");
+  return {
+    slug,
+    title: fields?.get("title") ? unquoteField(fields.get("title")!) : htmlTagValue(text, "title") || fallback,
+    description: fields?.get("description")
+      ? unquoteField(fields.get("description")!)
+      : htmlMeta(text, "description"),
+    updated,
+    size,
+  };
+}
+
+/** Read one HTML artifact by its vault-relative path. */
+export async function getHtmlArtifact(root: string, slug: string): Promise<HtmlArtifact | null> {
+  const path = resolveHtmlPath(root, slug);
+  if (!path) return null;
+  try {
+    const [text, st] = await Promise.all([fs.readFile(path, "utf8"), fs.stat(path)]);
+    return parseHtmlArtifact(slug, text, st.mtime.toISOString(), st.size);
+  } catch {
+    return null;
+  }
 }
 
 export function summarizeNote(note: Note): NoteSummary {
@@ -383,25 +486,7 @@ function byUpdatedDesc(a: { updated: string }, b: { updated: string }): number {
 }
 
 export async function listNoteFolders(root: string): Promise<string[]> {
-  const dir = join(root, NOTES_DIR);
-  const out: string[] = [];
-  async function walk(prefix: string): Promise<void> {
-    let entries;
-    try {
-      entries = await fs.readdir(prefix.length > 0 ? join(dir, prefix) : dir, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const entry of entries) {
-      if (entry.isDirectory() && !entry.name.startsWith(".")) {
-        const folder = prefix.length > 0 ? `${prefix}/${entry.name}` : entry.name;
-        out.push(folder);
-        await walk(folder);
-      }
-    }
-  }
-  await walk("");
-  return out.sort();
+  return (await listVaultEntries(root)).folders;
 }
 
 /**
@@ -422,21 +507,33 @@ export interface VaultSnapshot {
   fileCount: number;
   /** Subdirectories present in <vault>/notes/, including empty ones. */
   folders?: string[];
+  /** Readable standalone HTML/HTM artifacts. */
+  artifacts?: HtmlArtifact[];
+  /** Number of HTML/HTM files present, including malformed files. */
+  artifactCount?: number;
 }
 
 /** Read the whole vault in one pass: one readdir, one read per note. */
 export async function readVault(root: string): Promise<VaultSnapshot> {
-  const [files, folders] = await Promise.all([listNoteFiles(root), listNoteFolders(root)]);
+  const { files, folders } = await listVaultEntries(root);
   const notes: Note[] = [];
+  const artifacts: HtmlArtifact[] = [];
   for (const file of files) {
-    const note = await getNote(root, file.slice(0, -".md".length));
-    if (!note) continue; // unreadable/malformed files are skipped, not fatal
-    notes.push(note);
+    if (isMarkdown(file)) {
+      const note = await getNote(root, file.slice(0, -".md".length));
+      if (note) notes.push(note);
+    } else if (isHtml(file)) {
+      const artifact = await getHtmlArtifact(root, file);
+      if (artifact) artifacts.push(artifact);
+    }
   }
+  const artifactCount = files.filter(isHtml).length;
   return {
     notes: notes.sort(byUpdatedDesc),
-    fileCount: files.length,
+    fileCount: files.filter(isMarkdown).length,
     ...(folders.length > 0 ? { folders } : {}),
+    ...(artifacts.length > 0 ? { artifacts: artifacts.sort(byUpdatedDesc) } : {}),
+    ...(artifactCount > 0 ? { artifactCount } : {}),
   };
 }
 
@@ -465,7 +562,7 @@ export async function statNotes(root: string): Promise<NoteStat[]> {
       const path = join(dir, file);
       try {
         const st = await fs.stat(path);
-        return { slug: file.slice(0, -".md".length), path, mtimeMs: st.mtimeMs, size: st.size };
+        return { slug: isMarkdown(file) ? file.slice(0, -".md".length) : file, path, mtimeMs: st.mtimeMs, size: st.size };
       } catch {
         return null; // raced a delete
       }
@@ -480,7 +577,7 @@ export async function listNotes(root: string): Promise<NoteSummary[]> {
 }
 
 export async function noteCount(root: string): Promise<number> {
-  return (await listNoteFiles(root)).length;
+  return (await listNoteFiles(root)).filter(isMarkdown).length;
 }
 
 /**

package/src/core/view/detail.ts

@@ -35,7 +35,10 @@ export interface DetailModel {
 
 /** Ordered meta keys shown in the detail header. */
 const META_ORDER = [
+  "title",
+  "description",
   "path",
+  "size",
   "slug",
   "source",
   "updated",
@@ -55,6 +58,7 @@ const META_ORDER = [
   "summarized at",
   "summary",
   "dangling links",
+  "link references",
   "warning",
   "stale",
   "preview",