@yojahny/wp-design-library 1.0.0 → 1.1.0

package/README.md

@@ -172,6 +172,15 @@ blanks. The same works from the plugin: with the MCP server registered, say
 "add `~/Desktop/site.webp` to the design library as `acme-dark-hero`" and the
 session calls `add`, reads the strip, fills the draft, and calls `save_entry`.
 
+Ingest needs no filesystem: `add` → `set_fields` → `save_entry` closes entirely over
+MCP, so it works against a hosted instance as well as a local checkout. `set_fields`
+writes judgement fields only — roles, feel, motion, palette, type, body, tier — and
+refuses provenance keys by name, so `captured.*` and the artifact digests stay the
+server's record of what it measured. `get_vocab` returns the controlled terms, and
+`add_batch` drafts every file in the server's inbox in one run, resuming where an
+interrupted run stopped. Editing `entries/<slug>/entry.md` by hand remains available in
+a local checkout and does the same thing.
+
 What goes where, with the values checked against `vocab.yaml`:
 
 | Field | What to write |
@@ -248,6 +257,7 @@ The plugin does this for you, but from the CLI:
 ```bash
 node bin/library.mjs index         # rebuild the index from entries/
 node bin/library.mjs check         # validate every entry, 1 line per problem
+node bin/library.mjs check --remote  # + confirm every recorded artifact key resolves in R2
 ```
 
 Over MCP, seven tools: `search` (keyword + facet filters, aliases resolved),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yojahny/wp-design-library",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Design reference corpus and MCP server for claude-wp-builder",
   "repository": {
     "type": "git",

package/src/artifacts.mjs

@@ -17,7 +17,15 @@ export function cachePath(p, key) {
 // migrate-artifacts.mjs documents at length; the fix had not reached this file.
 export async function artifactFile(p, artifact, { config, fetcher = fetch } = {}) {
   const file = cachePath(p, artifact.key);
-  if (fs.existsSync(file) && fs.statSync(file).size === artifact.bytes) return file;
+  // bytes is the cheap first gate -- it short-circuits the common mismatch without hashing. A
+  // length match is not proof: bytes can rewrite in place at the same length, so a HIT is now
+  // verified against the digest too. A hit that fails is a corrupt cache entry, not a dead
+  // reader -- self-heal by deleting it and falling through to the fetch below, the same path a
+  // genuine miss takes.
+  if (fs.existsSync(file) && fs.statSync(file).size === artifact.bytes) {
+    if (sha256(fs.readFileSync(file)) === artifact.sha256) return file;
+    fs.rmSync(file);
+  }
   config ??= readConfig();
   const url = objectUrl(config, artifact.key);
   const response = await fetcher(url, { signal: AbortSignal.timeout(30000) });

package/src/cli/add.mjs

@@ -8,7 +8,7 @@ import { attachCapture } from '../ingest/attach.mjs';
 import { measure } from '../ingest/measure.mjs';
 import { loadVocab, resolveTerm } from '../vocab.mjs';
 import { parseEntry } from '../entry.mjs';
-import { artifactKey, putAndVerify, r2Config, s3Upload } from '../r2.mjs';
+import { artifactKey, putAndVerify, r2Config, s3Head, s3Upload } from '../r2.mjs';
 
 function opt(args, name) { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; }
 
@@ -43,7 +43,7 @@ async function stripFromFrames(framePaths, out) {
 // URL/file:// input: measure the live page with system Chrome instead of sampling
 // frames from a recording. Scratch-dir-first, same as the frame path: nothing under
 // entries/ is created OR destroyed until every byte is captured AND uploaded.
-async function addFromUrl({ p, input, slug, title, source, dir, record, force, attach, config, upload, fetcher }) {
+async function addFromUrl({ p, input, slug, title, source, dir, record, force, attach, config, upload, head, fetcher }) {
   const fs = await import('node:fs');
   const os = await import('node:os');
   const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'wpdl-add-'));
@@ -88,8 +88,8 @@ async function addFromUrl({ p, input, slug, title, source, dir, record, force, a
   // network round trip, and it throws for reasons this process does not control (absent
   // credentials, a reset connection, a digest mismatch). Uploading after the wipe made every one
   // of those a data-loss bug: `--force` deleted the entry and put nothing in its place.
-  // config/upload/fetcher are resolved lazily, here, and not as addEntry's defaults, so a refusal
-  // earlier in the flow never needs R2 credentials.
+  // config/upload/head/fetcher are resolved lazily, here, and not as addEntry's defaults, so a
+  // refusal earlier in the flow never needs R2 credentials.
   const names = ['strip.webp'];
   if (result.ok) names.push('measure.json', 'screen-1440.png', 'screen-390.png');
   const types = { '.webp': 'image/webp', '.png': 'image/png', '.json': 'application/json' };
@@ -97,10 +97,11 @@ async function addFromUrl({ p, input, slug, title, source, dir, record, force, a
   try {
     config ??= r2Config();
     if (!upload) upload = await s3Upload(config);
+    if (!head) head = await s3Head(config);
     for (const name of names) {
       const body = fs.readFileSync(path.join(scratch, name));
       const key = artifactKey(slug, index, name);
-      artifacts.push(await putAndVerify({ config, key, body, contentType: types[path.extname(name)], upload, fetcher }));
+      artifacts.push(await putAndVerify({ config, key, body, contentType: types[path.extname(name)], upload, head, fetcher }));
     }
   } catch (err) {
     fs.rmSync(scratch, { recursive: true, force: true });
@@ -131,7 +132,7 @@ async function addFromUrl({ p, input, slug, title, source, dir, record, force, a
   return { dir: d.dir, strip, blanks: d.blanks, measured: result.ok };
 }
 
-export async function addEntry({ input, slug, title, source, force = false, frames, record = false, attach = false, config, upload, fetcher = fetch }) {
+export async function addEntry({ input, slug, title, source, force = false, frames, record = false, attach = false, config, upload, head, fetcher = fetch }) {
   const p = paths();
   if (!input || !slug || !title || !source?.kind || !source?.license) throw new Error('add: input, slug, title, --source and --license are required');
   // Refused here (draft time), not first at save: resolveTerm is the single vocab gate
@@ -147,7 +148,7 @@ export async function addEntry({ input, slug, title, source, force = false, fram
     return { refused: `entry ${slug} exists; pass attach to add a capture, or force to overwrite` };
   }
   if (URL_RE.test(input)) {
-    return addFromUrl({ p, input, slug, title, source, dir, record, force, attach, config, upload, fetcher });
+    return addFromUrl({ p, input, slug, title, source, dir, record, force, attach, config, upload, head, fetcher });
   }
   // Sample into a scratch dir first: a refusal must leave nothing under entries/.
   const scratch = mkdtempSync(path.join(os.tmpdir(), 'wpdl-add-'));
@@ -170,9 +171,10 @@ export async function addEntry({ input, slug, title, source, force = false, fram
   try {
     config ??= r2Config();
     if (!upload) upload = await s3Upload(config);
+    if (!head) head = await s3Head(config);
     stripArtifact = await putAndVerify({
       config, key: artifactKey(slug, index, 'strip.webp'), body: readFileSync(scratchStrip),
-      contentType: 'image/webp', upload, fetcher,
+      contentType: 'image/webp', upload, head, fetcher,
     });
   } catch (err) {
     rmSync(scratch, { recursive: true, force: true });
@@ -214,30 +216,40 @@ export async function addEntry({ input, slug, title, source, force = false, fram
   return { dir: d.dir, strip, blanks: d.blanks, frames: media.frames };
 }
 
-export async function addInbox({ source, config, upload, fetcher }) {
+export async function addInbox({ source, config, upload, head, fetcher }) {
   const p = paths();
   const fs = await import('node:fs');
   const inbox = path.join(p.data, 'inbox');
   const out = [];
   if (!fs.existsSync(inbox)) return out;
+  // One file per run, not one shared log: a settled 2,000-file inbox re-run appends 2,000 more
+  // `skipped` lines to a file that never shrinks, every time. The ISO stamp also sorts by name,
+  // so "what did the run that died last night do" is answerable by reading the newest file.
+  const runLog = path.join(p.data, '.library', 'runs', `inbox-${new Date().toISOString().replace(/[:.]/g, '-')}.jsonl`);
+  fs.mkdirSync(path.dirname(runLog), { recursive: true });
+  // Appended as each file finishes, not written at the end: a run killed at entry 1,400 never
+  // reaches its own return statement, and that is the case this exists for. One complete line per
+  // append, so a process killed mid-write loses at most its last record rather than corrupting the
+  // file. .library/ is already gitignored.
+  const record = (r) => { fs.appendFileSync(runLog, JSON.stringify({ ...r, at: new Date().toISOString() }) + '\n'); return r; };
   const seenSlugs = new Map(); // ponytail: slug -> first file this run, names the collision
   for (const file of fs.readdirSync(inbox).filter((f) => MEDIA.test(f)).sort()) {
     const slug = slugify(file);
-    if (!slug) { out.push({ file, slug, status: 'refused', reason: 'cannot derive a slug from the file name; pass --slug' }); continue; }
-    if (seenSlugs.has(slug)) { out.push({ file, slug, status: 'refused', reason: `slug ${slug} collides with ${seenSlugs.get(slug)} in this run` }); continue; }
+    if (!slug) { out.push(record({ file, slug, status: 'refused', reason: 'cannot derive a slug from the file name; pass --slug' })); continue; }
+    if (seenSlugs.has(slug)) { out.push(record({ file, slug, status: 'refused', reason: `slug ${slug} collides with ${seenSlugs.get(slug)} in this run` })); continue; }
     seenSlugs.set(slug, file);
     const full = path.join(inbox, file);
-    if (fs.existsSync(path.join(p.entries, slug, 'entry.md'))) { out.push({ file, slug, status: 'skipped', reason: 'entry exists' }); continue; }
+    if (fs.existsSync(path.join(p.entries, slug, 'entry.md'))) { out.push(record({ file, slug, status: 'skipped', reason: 'entry exists' })); continue; }
     let meta = {};
     const side = full + '.json';
-    if (fs.existsSync(side)) { try { meta = JSON.parse(fs.readFileSync(side, 'utf8')); } catch (e) { out.push({ file, slug, status: 'refused', reason: 'sidecar is not JSON' }); continue; } }
-    if (meta === null || typeof meta !== 'object' || Array.isArray(meta)) { out.push({ file, slug, status: 'refused', reason: 'sidecar must be a JSON object' }); continue; }
+    if (fs.existsSync(side)) { try { meta = JSON.parse(fs.readFileSync(side, 'utf8')); } catch (e) { out.push(record({ file, slug, status: 'refused', reason: 'sidecar is not JSON' })); continue; } }
+    if (meta === null || typeof meta !== 'object' || Array.isArray(meta)) { out.push(record({ file, slug, status: 'refused', reason: 'sidecar must be a JSON object' })); continue; }
     const kind = meta.kind ?? source?.kind, license = meta.license ?? source?.license;
-    if (!kind || !license) { out.push({ file, slug, status: 'refused', reason: 'no source kind/license: add a <file>.json sidecar or pass --source and --license' }); continue; }
+    if (!kind || !license) { out.push(record({ file, slug, status: 'refused', reason: 'no source kind/license: add a <file>.json sidecar or pass --source and --license' })); continue; }
     try {
-      const r = await addEntry({ input: full, slug, title: meta.title ?? slug.replace(/-/g, ' '), source: { kind, url: meta.url ?? source?.url, license }, config, upload, fetcher });
-      out.push(r.refused ? { file, slug, status: 'refused', reason: r.refused } : { file, slug, status: 'drafted', frames: r.frames });
-    } catch (e) { out.push({ file, slug, status: 'refused', reason: e.message }); }
+      const r = await addEntry({ input: full, slug, title: meta.title ?? slug.replace(/-/g, ' '), source: { kind, url: meta.url ?? source?.url, license }, config, upload, head, fetcher });
+      out.push(record(r.refused ? { file, slug, status: 'refused', reason: r.refused } : { file, slug, status: 'drafted', frames: r.frames }));
+    } catch (e) { out.push(record({ file, slug, status: 'refused', reason: e.message })); }
   }
   return out;
 }

package/src/cli/check.mjs

@@ -4,6 +4,17 @@ import { loadVocab } from '../vocab.mjs';
 import { listEntries, parseEntry, validateEntry } from '../entry.mjs';
 import { fetchModels, modelDirs } from '../index/embed.mjs';
 
+// A fixed-width worker pool, not one request at a time: ~2000 entries at up to four artifacts
+// each is ~8000 HEADs, and sequential that is minutes at a realistic edge RTT and tens of hours
+// against a bucket that black-holes connections (each request burning the full timeout below). 8
+// is a guess, not tuned -- enough to matter, low enough that a real outage's failures still read
+// as a report instead of a wall of interleaved errors.
+async function mapPool(items, limit, fn) {
+  let i = 0;
+  const worker = async () => { while (i < items.length) { const idx = i++; await fn(items[idx], idx); } };
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+}
+
 export async function run(args = []) {
   const p = paths();
   if (args.includes('--fetch-models')) {
@@ -15,13 +26,47 @@ export async function run(args = []) {
   }
   const vocab = loadVocab(p.vocab);
   let bad = 0, n = 0;
+  const artifacts = [];
   for (const dir of listEntries(p.entries)) {
     n++;
     let e;
     try { e = parseEntry(dir); } catch (err) { bad++; process.stderr.write(`${path.basename(dir)}: ${err.message}\n`); continue; }
     const r = validateEntry(e, vocab);
     if (!r.ok) { bad++; for (const m of r.errors) process.stderr.write(`${e.slug}: ${m}\n`); }
+    for (const c of e.fm.captured?.captures ?? []) for (const a of c.artifacts ?? []) artifacts.push(a);
   }
   process.stdout.write(`${n - bad}/${n} entries ok\n`);
+
+  // --remote answers the question `check` otherwise never asks: does every key this corpus
+  // CLAIMS is in R2 actually resolve. Metadata validation above never touches the network --
+  // that stays the default, so CI with no credentials keeps working -- this is opt-in.
+  if (args.includes('--remote')) {
+    const { readConfig, objectUrl } = await import('../r2.mjs');
+    // readConfig throws when R2_PUBLIC_BASE_URL is absent, and unguarded that reaches the operator
+    // as a raw Node stack trace -- the same "work it out from the wreckage" failure 1.0.1 fixed for
+    // the gallery. It needs only that one variable and no credentials, so the refusal can say
+    // exactly what to set.
+    let config;
+    try { config = readConfig(); }
+    catch (err) { process.stderr.write(`check --remote: ${err.message}\n`); return 1; }
+    // Collected and sorted before printing, not written as each HEAD lands -- 8 in flight would
+    // otherwise interleave and print in whatever order they happen to settle, so the same broken
+    // corpus would read differently run to run.
+    const problems = [];
+    await mapPool(artifacts, 8, async (a) => {
+      try {
+        const r = await fetch(objectUrl(config, a.key), { method: 'HEAD', signal: AbortSignal.timeout(20000) });
+        // Existence AND size. A 200 with the wrong length means the object is not what the entry
+        // records -- exactly as broken as it being absent, and cheaper to catch here than at read
+        // time on a visitor's page.
+        if (!r.ok) { problems.push(`${a.key}: HTTP ${r.status}`); return; }
+        const len = Number(r.headers.get('content-length'));
+        if (len !== a.bytes) problems.push(`${a.key}: expected ${a.bytes} bytes, bucket says ${len}`);
+      } catch (err) { problems.push(`${a.key}: ${err.message}`); }
+    });
+    for (const p of problems.sort()) process.stderr.write(`${p}\n`);
+    process.stdout.write(`${artifacts.length - problems.length}/${artifacts.length} artifacts reachable\n`);
+    if (problems.length) return 1;
+  }
   return bad ? 1 : 0;
 }

package/src/cli/index.mjs

@@ -6,7 +6,7 @@ export async function run() {
   const p = paths();
   const r = await buildIndex({ entriesDir: p.entries, indexPath: p.index, vocab: loadVocab(p.vocab), models: p.models, p });
   for (const m of r.refused) process.stderr.write(`refused ${m}\n`);
-  process.stdout.write(`indexed ${r.entries} entries, refused: ${r.refused.length}, arms: ${r.arms.join(',')}\n`);
+  process.stdout.write(`indexed ${r.entries} entries, refused: ${r.refused.length}, arms: ${r.arms.join(',')}, embedded ${r.embedded.text} text and ${r.embedded.image} image vectors\n`);
   for (const s of r.skipped) process.stderr.write(`embeddings: skipped (${s.reason})\n`);
   return 0;
 }

package/src/cli/refresh.mjs

@@ -8,7 +8,7 @@ import { loadVocab } from '../vocab.mjs';
 import { buildIndex } from '../index/build.mjs';
 import { measure } from '../ingest/measure.mjs';
 import { refuseUnsafeUrl } from '../ingest/url-guard.mjs';
-import { artifactKey, putAndVerify, r2Config, s3Upload } from '../r2.mjs';
+import { artifactKey, putAndVerify, r2Config, s3Head, s3Upload } from '../r2.mjs';
 
 const REFRESHED = ['measure.json', 'screen-1440.png', 'screen-390.png'];
 const TYPES = { '.png': 'image/png', '.json': 'application/json' };
@@ -19,7 +19,7 @@ const TYPES = { '.png': 'image/png', '.json': 'application/json' };
 // the measurement and captured.at change. `transport` is undefined for the CLI, 'http'
 // for the hosted MCP server; the SSRF guard only consults DNS in the latter case.
 // `measurer` exists so this path can be driven without a browser; nothing but a test passes it.
-export async function refreshEntry({ slug, transport, config, upload, fetcher = fetch, measurer = measure }) {
+export async function refreshEntry({ slug, transport, config, upload, head, fetcher = fetch, measurer = measure }) {
   const p = paths();
   const dir = path.join(p.entries, slug);
   let e;
@@ -61,10 +61,11 @@ export async function refreshEntry({ slug, transport, config, upload, fetcher =
   try {
     config ??= r2Config();
     if (!upload) upload = await s3Upload(config);
+    if (!head) head = await s3Head(config);
     uploaded = [];
     for (const f of REFRESHED) {
       uploaded.push(await putAndVerify({ config, key: artifactKey(slug, 1, f), body: fs.readFileSync(path.join(scratch, f)),
-        contentType: TYPES[path.extname(f)], upload, fetcher }));
+        contentType: TYPES[path.extname(f)], upload, head, fetcher }));
     }
   } catch (err) {
     fs.rmSync(scratch, { recursive: true, force: true });

package/src/cli/serve.mjs

@@ -66,7 +66,7 @@ async function buildTheIndex(p) {
   const { loadVocab } = await import('../vocab.mjs');
   const { buildIndex } = await import('../index/build.mjs');
   const r = await buildIndex({ entriesDir: p.entries, indexPath: p.index, vocab: loadVocab(p.vocab), models: p.models, p });
-  process.stderr.write(`index: ${r.entries} entries, refused ${r.refused.length}\n`);
+  process.stderr.write(`index: ${r.entries} entries, refused ${r.refused.length}, arms: ${r.arms.join(',')}, embedded ${r.embedded.text} text and ${r.embedded.image} image vectors\n`);
   for (const s of r.skipped) process.stderr.write(`embeddings: skipped (${s.reason})\n`);
 }
 
@@ -93,7 +93,8 @@ export async function run(args) {
     await buildTheIndex(p);
     try {
       const { buildUi } = await import('../ui/build.mjs');
-      await buildUi({ indexPath: p.index, entriesDir: p.entries, outDir: path.join(p.data, 'ui'), p });
+      const r = await buildUi({ indexPath: p.index, entriesDir: p.entries, outDir: path.join(p.data, 'ui'), p });
+      process.stderr.write(`ui: ${r.entries} entries, ${r.drafts} drafts, rendered ${r.rendered} thumbnails\n`);
     } catch (err) {
       // the gallery is a convenience for a human; the MCP API must not depend on it
       process.stderr.write(`ui: build failed, serving without it: ${err.stack || err}\n`);

package/src/cli/ui.mjs

@@ -9,7 +9,7 @@ export async function run(args = []) {
   const outDir = path.join(p.data, 'ui');
   const previewMediaDir = args.includes('--local-media') ? path.join(p.data, '.library', 'media') : undefined;
   const r = await buildUi({ indexPath: p.index, entriesDir: p.entries, outDir, previewMediaDir, p });
-  process.stdout.write(`ui: ${r.entries} entries, ${r.drafts} drafts, built into ${outDir}\n`);
+  process.stdout.write(`ui: ${r.entries} entries, ${r.drafts} drafts, built into ${outDir}, rendered ${r.rendered} thumbnails\n`);
   if (args.includes('--serve')) {
     const port = Number(opt(args, '--port') ?? 4180);
     const { serveStatic } = await import('../ui/serve.mjs');

package/src/entry.mjs

@@ -19,6 +19,15 @@ export function parseEntry(dir) {
   return { slug: fm.slug, dir, fm, body: m[2].trim() };
 }
 
+// The symmetric partner to parseEntry. Four other call sites serialize an entry
+// inline with their own lineWidth; they are deliberately left alone, because
+// changing a writer reflows YAML in files it was not asked to touch. New code
+// uses this one.
+export function writeEntry(dir, fm, body) {
+  const text = `---\n${yaml.dump(fm, { lineWidth: 120 })}---\n${body ? `\n${body}\n` : ''}`;
+  fs.writeFileSync(path.join(dir, 'entry.md'), text);
+}
+
 function get(obj, dotted) {
   return dotted.split('.').reduce((o, k) => (o == null ? undefined : o[k]), obj);
 }

package/src/index/build.mjs

@@ -1,10 +1,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { createHash } from 'node:crypto';
 import { listEntries, parseEntry, validateEntry } from '../entry.mjs';
 import { openIndex } from './query.mjs';
 import { getEmbedder, absentReason } from './embed.mjs';
 import { artifactFile } from '../artifacts.mjs';
+import { openVecCache } from './veccache.mjs';
 
 const DIR = path.dirname(fileURLToPath(import.meta.url));
 const SCHEMA = fs.readFileSync(path.join(DIR, 'schema.sql'), 'utf8');
@@ -26,11 +28,23 @@ export async function buildIndex({ entriesDir, indexPath, vocab, models, p }) {
   // a killed build can leave a half-written .tmp behind; clear it so the open below always starts fresh
   fs.rmSync(tmpPath, { force: true });
   let db;
+  let cache = null;
   try {
     db = openIndex(tmpPath, { readonly: false });
     db.exec(SCHEMA);
     if (db.vec) db.exec(SCHEMA_VEC);
     const emb = await getEmbedder({ models });
+    // The cache is only worth opening when there is an embedder and a vec arm to feed.
+    // .library/vectors.sqlite is derived, gitignored and regenerable: a reader that finds it
+    // broken (first-open lock contention on a fresh volume, an unopenable file) should recompute,
+    // not die -- the same ruling artifactFile already applies to a bad cache entry.
+    try { cache = emb && db.vec ? openVecCache(p) : null; }
+    catch (err) { process.stderr.write(`index: vector cache unavailable, recomputing: ${err.message}\n`); cache = null; }
+    // skipped.image is nested here, not returned as a sibling top-level `skipped`, because that
+    // name is already taken by the arm-level skip-reason array below (`skipped: [{arm,reason}]`,
+    // consumed by src/cli/index.mjs, src/cli/serve.mjs and src/mcp/tools.mjs as an iterable) --
+    // a same-named sibling with a different shape would break every one of those.
+    const embedded = { text: 0, image: 0, skipped: { image: 0 } };
     const refused = [];
     const insEntry = db.prepare(`INSERT INTO entries VALUES (@slug,@title,@tier,@source_kind,@captured_at,@dir,@body,@fm)`);
     const insTag = db.prepare(`INSERT INTO entry_tags VALUES (?,?,?)`);
@@ -58,26 +72,53 @@ export async function buildIndex({ entriesDir, indexPath, vocab, models, p }) {
       tx(e, tags);
       if (emb && db.vec) {
         const tagsStr = tags.map(([f, t]) => `${f}/${t}`).join(' ');
-        const tv = await emb.text(e.fm.title + '\n' + searchableBody(e) + '\n' + tagsStr);
-        insVecText.run(e.slug, Buffer.from(tv.buffer));
+        const text = e.fm.title + '\n' + searchableBody(e) + '\n' + tagsStr;
+        // Keyed on the exact string that gets embedded, so an edit that changes the text changes
+        // the key and re-embeds, and an edit that does not (whitespace in an unindexed field)
+        // correctly costs nothing.
+        const textKey = createHash('sha256').update(text).digest('hex');
+        let tv = cache?.get(`text:${emb.id}`, textKey) ?? null;
+        if (!tv) {
+          tv = Buffer.from((await emb.text(text)).buffer);
+          // tv is already computed; a cache write failure (SQLITE_FULL, a broken cache) must
+          // cost exactly the write, not the build.
+          try { cache?.put(`text:${emb.id}`, textKey, tv); } catch (err) {
+            process.stderr.write(`index: ${e.slug}: text vector cache write skipped: ${err.message}\n`);
+          }
+          embedded.text++;
+        }
+        insVecText.run(e.slug, tv);
         // An unreachable strip must not abort the whole index: skip this entry's image
         // vector and keep going, the same degradation buildUi applies to its thumbnail.
         const strip = (e.fm.captured?.captures?.[0]?.artifacts ?? []).find((a) => a?.key?.endsWith('/strip.webp'));
         if (strip) {
-          try {
-            const iv = await emb.image(await artifactFile(p, strip));
-            insVecImage.run(e.slug, Buffer.from(iv.buffer));
-          } catch (err) {
-            process.stderr.write(`index: ${e.slug}: image vector skipped: ${err.message}\n`);
+          // Keyed on the digest entry.md ALREADY records, which is the whole win: on a hit there
+          // is no artifactFile call, so no fetch and no cache read -- a restart over an unchanged
+          // corpus does zero network I/O for images.
+          let iv = cache?.get(`image:${emb.id}`, strip.sha256) ?? null;
+          if (!iv) {
+            try {
+              iv = Buffer.from((await emb.image(await artifactFile(p, strip))).buffer);
+              cache?.put(`image:${emb.id}`, strip.sha256, iv);
+              embedded.image++;
+            } catch (err) {
+              iv = null;
+              embedded.skipped.image++;
+              process.stderr.write(`index: ${e.slug}: image vector skipped: ${err.message}\n`);
+            }
           }
+          if (iv) insVecImage.run(e.slug, iv);
         }
       }
       n++;
     }
-    db.close();
+    // A close failure here must not mask a completed build or discard its index -- same
+    // reasoning as the catch block below, extended to the success path.
+    try { db.close(); } catch {}
+    try { cache?.close(); } catch {}
     fs.renameSync(tmpPath, indexPath);
     return {
-      entries: n, refused,
+      entries: n, refused, embedded,
       arms: emb && db.vec ? ['fts', 'vec'] : ['fts'],
       skipped: emb
         ? (db.vec ? [] : [{ arm: 'vec', reason: 'sqlite-vec failed to load' }])
@@ -88,6 +129,7 @@ export async function buildIndex({ entriesDir, indexPath, vocab, models, p }) {
     // handle here leaks for the life of the process. A close failure must not mask
     // the original error, so it's swallowed rather than rethrown.
     try { db?.close(); } catch {}
+    try { cache?.close(); } catch {}
     fs.rmSync(tmpPath, { force: true });
     throw err;
   }

package/src/index/embed.mjs

@@ -29,7 +29,12 @@ export async function getEmbedder({ models, mode = process.env.LIBRARY_EMBED } =
   if (mode === 'off') return null;
   if (mode === 'stub') {
     return {
-      arm: 'vec', dims: DIMS,
+      // Namespaced, so no value of LIBRARY_EMBED_STUB_ID can equal the real arm's id below.
+      // Unprefixed, setting it to the two model constants verbatim produced a cache key
+      // byte-identical to a genuine real-arm build, and a later real build read the stub's
+      // hash-noise vectors as a warm hit — the very bug this id exists to prevent, re-entered
+      // through its own test seam. Reproduced before this line was added.
+      arm: 'vec', dims: DIMS, id: `stub:${process.env.LIBRARY_EMBED_STUB_ID ?? 'default'}`,
       text: async (s) => stubVec('t:' + s, DIMS.text),
       // ponytail: seeded on byte length + basename, not pixel content. Every
       // indexed strip shares the basename strip.webp, so two strips of the same
@@ -48,7 +53,7 @@ export async function getEmbedder({ models, mode = process.env.LIBRARY_EMBED } =
   const proc = await tf.AutoProcessor.from_pretrained(IMAGE_MODEL);
   const vision = await tf.SiglipVisionModel.from_pretrained(IMAGE_MODEL);
   return {
-    arm: 'vec', dims: DIMS,
+    arm: 'vec', dims: DIMS, id: `${TEXT_MODEL}|${IMAGE_MODEL}`,
     text: async (s) => Float32Array.from((await textPipe(s, { pooling: 'mean', normalize: true })).data),
     image: async (p) => {
       const img = await tf.RawImage.read(p);

package/src/index/veccache.mjs

@@ -0,0 +1,53 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { openIndex } from './query.mjs';
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS vectors (
+  kind TEXT NOT NULL,
+  key  TEXT NOT NULL,
+  vec  BLOB NOT NULL,
+  PRIMARY KEY (kind, key)
+);
+`;
+
+// A separate file, deliberately. buildIndex writes index.sqlite.tmp and renames it over the real
+// index on every run, so a cache table inside it would be destroyed by the very operation it is
+// meant to make cheap. This one lives beside it and outlives every rebuild.
+export function openVecCache(p) {
+  // .library/, beside index.sqlite and media/ — the one place on disk where derived bytes live,
+  // and the directory .gitignore covers. Loose in p.data it would be an untracked file in the
+  // repo root of every local checkout.
+  const file = path.join(p.data, '.library', 'vectors.sqlite');
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  let db;
+  try {
+    db = openIndex(file, { readonly: false });
+    // Unconditional, and deliberately so. A review flagged this as taking a write lock on every
+    // open — two processes legitimately share this volume, so that would have mattered. Measured,
+    // it does not: with another connection holding BEGIN IMMEDIATE, `CREATE TABLE IF NOT EXISTS`
+    // against an EXISTING table succeeds and takes no write lock, and only the first open, when
+    // the table really is absent, raises SQLITE_BUSY. Guarding this with a `SELECT name FROM
+    // sqlite_master` first would add a query to every open to avoid a lock that is never taken
+    // after the first one. Left simple on purpose.
+    db.exec(SCHEMA);
+    const sel = db.prepare('SELECT vec FROM vectors WHERE kind = ? AND key = ?');
+    const ins = db.prepare('INSERT OR REPLACE INTO vectors (kind, key, vec) VALUES (?, ?, ?)');
+    return {
+      // null means MISS. A row holding a zero-length blob is a hit whose value is empty, and the
+      // two must stay distinguishable or an empty vector re-embeds on every single start.
+      get(kind, key) {
+        const row = sel.get(kind, key);
+        return row ? Buffer.from(row.vec) : null;
+      },
+      put(kind, key, buf) { ins.run(kind, key, buf); },
+      close() { db.close(); },
+    };
+  } catch (err) {
+    // openVecCache can be called on every http server startup or in CLI runs on a shared
+    // volume; an unclosed handle here leaks for the life of the process. A close failure must
+    // not mask the original error, so it's swallowed rather than rethrown.
+    try { db?.close(); } catch {}
+    throw err;
+  }
+}

package/src/ingest/fields.mjs

@@ -0,0 +1,77 @@
+import { parseEntry, writeEntry, REQUIRED_BLANKS } from '../entry.mjs';
+import { resolveTerm } from '../vocab.mjs';
+
+// Exactly the fields a session is the author of. tier and ported_from are here
+// because a ported entry cannot be completed without them and the licence gate in
+// validateEntry still judges the result. Everything absent from this list is
+// provenance the server measured, and is refused by name below.
+const ALLOWED = new Set([...REQUIRED_BLANKS, 'tier', 'ported_from']);
+
+// Which vocabulary facet governs which field. A field absent here takes free text.
+const FACET_OF = { roles: 'role', feel: 'feel', 'motion.devices': 'motion', tier: 'tier' };
+
+function get(obj, dotted) {
+  return dotted.split('.').reduce((o, k) => (o == null ? undefined : o[k]), obj);
+}
+function set(obj, dotted, value) {
+  const keys = dotted.split('.');
+  const last = keys.pop();
+  let o = obj;
+  for (const k of keys) {
+    if (o[k] == null || typeof o[k] !== 'object') o[k] = {};
+    o = o[k];
+  }
+  o[last] = value;
+}
+function isBlank(v) {
+  return v == null || v === '' || (Array.isArray(v) && v.length === 0);
+}
+
+export function setFields({ dir, fields, vocab }) {
+  const entry = parseEntry(dir);
+  const fm = entry.fm;
+  let body = entry.body;
+  const refused = [];
+  const staged = [];
+
+  for (const [key, value] of Object.entries(fields ?? {})) {
+    if (!ALLOWED.has(key)) {
+      refused.push(`${key}: not a judgement field — set_fields writes ${[...ALLOWED].join(', ')} and nothing else`);
+      continue;
+    }
+    const facet = FACET_OF[key];
+    if (facet) {
+      const terms = Array.isArray(value) ? value : [value];
+      const canon = [];
+      for (const t of terms) {
+        const c = resolveTerm(vocab, facet, t);
+        if (c === null) refused.push(`${key}: unknown ${facet} term "${t}"`);
+        else canon.push(c);
+      }
+      staged.push([key, Array.isArray(value) ? canon : canon[0]]);
+      continue;
+    }
+    staged.push([key, value]);
+  }
+
+  // Nothing is written when anything was refused. A partial write leaves the agent
+  // reasoning about a draft that is neither what it sent nor what it had.
+  if (refused.length) {
+    return { ok: false, slug: fm.slug, blanks: REQUIRED_BLANKS.filter((k) => isBlank(get({ ...fm, body }, k))), written: [], refused };
+  }
+
+  for (const [key, value] of staged) {
+    if (key === 'body') body = value;
+    else set(fm, key, value);
+  }
+  writeEntry(dir, fm, body);
+
+  const view = { ...fm, body };
+  return {
+    ok: true,
+    slug: fm.slug,
+    blanks: REQUIRED_BLANKS.filter((k) => isBlank(get(view, k))),
+    written: staged.map(([k]) => k),
+    refused: [],
+  };
+}

package/src/mcp/http.mjs

@@ -23,8 +23,23 @@ async function handle(req, res, p, token, embedder) {
       if (db.vec && db.prepare('SELECT count(*) c FROM vec_text').get().c > 0) arms = ['fts', 'vec'];
       db.close();
     } catch {}
+    // A host with a full index and no reachable artifacts serves 31 grey boxes and reported
+    // ok:true, which is how a missing R2_PUBLIC_BASE_URL stayed invisible through two rounds of
+    // "it still is not showing images". Name it here, where anyone can see it without log access.
+    // It is not part of `ok`: the MCP API answers perfectly well on text alone, and failing the
+    // health check would take a working server down over missing pictures.
+    // "configured", never "ok": this reads the environment, it does not fetch an object, so it
+    // cannot claim the bucket is reachable. It catches the failure actually hit — the variable
+    // being absent — and says only what it checked.
+    let artifacts;
+    try {
+      const { readConfig } = await import('../r2.mjs');
+      artifacts = `configured: ${readConfig().base}`;
+    } catch (err) {
+      artifacts = `unconfigured: ${err.message}`;
+    }
     res.writeHead(200, { 'content-type': 'application/json' });
-    return res.end(JSON.stringify({ ok: true, entries, arms, version: p.version }));
+    return res.end(JSON.stringify({ ok: true, entries, arms, artifacts, version: p.version }));
   }
   if (url.pathname === '/mcp') {
     if (!authorized(req.headers.authorization, token)) { res.writeHead(401); return res.end('unauthorized'); }

package/src/mcp/prompts.mjs

@@ -40,8 +40,14 @@ session did not make.
    \`frames: 36\` before tagging. The server caps at 36 frames; beyond about 18 seconds a
    section can still be missed, so build a denser sheet yourself from the source file
    before writing the motion note.
-4. **Tag.** Fill every field in the returned \`blanks\` list in \`<dir>/entry.md\`, per the
-   rubric below. Write the motion note last, after the roster.
+4. **Tag.** Fill every field in the returned \`blanks\` list, per the rubric below. Write
+   the motion note last, after the roster. Two ways, same result: call \`set_fields\` with
+   those field names — this needs **no filesystem** and is the only way that works against
+   a hosted server — or, in a local checkout, edit \`<dir>/entry.md\` directly.
+   \`set_fields\` resolves aliases and refuses an unknown term by name without writing
+   anything, so a refusal never leaves a half-filled draft. It writes judgement fields
+   only; provenance is refused. \`get_vocab\` returns the terms if you did not read them
+   above.
 5. **Approve.** Show the draft to the user and **show the draft and wait for a yes** before
    anything else. Apply their edits.
 6. **Save.** Call \`save_entry\`. On \`refused\`, show the field names, fix, and call again;

package/src/mcp/tools.mjs

@@ -213,6 +213,15 @@ export function makeTools(ctx) {
         return { arms: arms ?? ['fts'], ...(skipped ? { skipped } : {}), feel, roles };
       }),
     },
+    {
+      name: 'get_vocab',
+      description: 'The five controlled facets and the alias map, read from vocab.yaml. roles and feel tag an entry, motion names the data-motion devices, source and tier gate the licence. A term is added by PR, never by an ingest, so an unknown term is a refusal rather than a new term.',
+      schema: z.object({}),
+      handler: async () => ({
+        ...Object.fromEntries(Object.entries(ctx.vocab.facets).map(([k, v]) => [k, [...v]])),
+        aliases: Object.fromEntries(ctx.vocab.aliases),
+      }),
+    },
     {
       name: 'add',
       description: 'Ingest a video/animated image, or measure a live https:// URL with the system Chrome: sample frames or measure into strip.webp/measure.json and write a draft entry. Returns the blank fields the caller must fill before save_entry. Pass attach to add a second capture of the same site — a video beside a live URL — instead of refusing; the existing entry\'s tags, body, palette and type are left untouched.',
@@ -238,6 +247,26 @@ export function makeTools(ctx) {
         return (await import('../cli/add.mjs')).addEntry(a);
       },
     },
+    {
+      name: 'add_batch',
+      description: "Ingest every media file in the server's inbox in one run: one draft per file, an existing slug skipped so an interrupted run resumes, and a failed file costing only itself. Returns one record per file. Takes no path — the walk is the inbox and nothing else. Each drafted entry still needs set_fields then save_entry.",
+      schema: z.object({
+        source: z.object({
+          kind: z.enum(['own', 'open', 'paid', 'public-site']),
+          url: z.string().url().optional(),
+          license: z.string().min(1),
+        }).optional(),
+      }),
+      handler: async ({ source }) => {
+        const { addInbox } = await import('../cli/add.mjs');
+        const results = await addInbox({ source });
+        return {
+          results,
+          drafted: results.filter((r) => r.status === 'drafted').length,
+          refused: results.filter((r) => r.status === 'refused').length,
+        };
+      },
+    },
     {
       name: 'refresh',
       description: 'Re-measure a drafted URL entry (source.url set, captured.method measured|both) with the system Chrome: rewrites measure.json, bumps captured.at, and reindexes. Refuses an entry with no URL or one drafted from frames only.',
@@ -253,6 +282,18 @@ export function makeTools(ctx) {
         return saveEntry({ dir: path.join(ctx.paths.entries, slug), vocab: ctx.vocab, indexPath: ctx.paths.index, entriesDir: ctx.paths.entries, models: ctx.paths.models, p: ctx.paths });
       },
     },
+    {
+      name: 'set_fields',
+      description: "Fill a draft's judgement fields: roles, feel, motion.devices, motion.notes, palette, type, body, tier, ported_from — never provenance. Vocabulary terms are resolved through aliases and an unknown one is refused by name with nothing written, so a refusal never leaves a half-filled draft. Returns the fields still blank. This is the step between add and save_entry, and it is the only one that does not need a filesystem.",
+      schema: z.object({
+        slug: z.string().regex(/^[a-z0-9-]+$/),
+        fields: z.record(z.any()),
+      }),
+      handler: async ({ slug, fields }) => {
+        const { setFields } = await import('../ingest/fields.mjs');
+        return setFields({ dir: path.join(ctx.paths.entries, slug), fields, vocab: ctx.vocab });
+      },
+    },
   ];
 }
 

package/src/r2.mjs

@@ -59,15 +59,50 @@ export function sha256(body) {
   return createHash('sha256').update(body).digest('hex');
 }
 
+// Extracted from s3Upload, which built this inline. Two constructions of the same client that can
+// drift apart is exactly the kind of duplication that makes one of them quietly wrong later.
+function clientConfig(config) {
+  return { region: 'auto', endpoint: `https://${config.account}.r2.cloudflarestorage.com`,
+    credentials: { accessKeyId: config.accessKeyId, secretAccessKey: config.secretAccessKey } };
+}
+
 export async function s3Upload(config) {
   const { S3Client, PutObjectCommand } = await import('@aws-sdk/client-s3');
-  const client = new S3Client({ region: 'auto', endpoint: `https://${config.account}.r2.cloudflarestorage.com`,
-    credentials: { accessKeyId: config.accessKeyId, secretAccessKey: config.secretAccessKey } });
+  const client = new S3Client(clientConfig(config));
   return (args) => client.send(new PutObjectCommand(args));
 }
 
-// Upload, then prove the object is publicly readable and byte-identical before any caller records
-// the key. motion.mjs established this order: an entry must never name an object nobody can read.
+// Mirrors s3Upload: the SDK is imported lazily so a reader never loads it.
+export async function s3Head(config) {
+  const { S3Client, HeadObjectCommand } = await import('@aws-sdk/client-s3');
+  const client = new S3Client(clientConfig(config));
+  return async ({ Bucket, Key }) => {
+    const r = await client.send(new HeadObjectCommand({ Bucket, Key }));
+    return { Metadata: r.Metadata ?? {} };
+  };
+}
+
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+// Only the PUT is retried. The range-fetch verification below is not: a verification failure
+// means the object in the bucket is not what we sent, and repeating the read cannot change that
+// -- it would just delay a refusal that is already correct.
+async function withRetry(fn, retries, sleep) {
+  for (let attempt = 1; ; attempt++) {
+    try { return await fn(); }
+    catch (err) {
+      if (attempt >= retries) throw err;
+      await sleep(250 * 2 ** (attempt - 1));
+    }
+  }
+}
+
+// Upload -- or, when the digest already matches what's in the bucket, skip the PUT -- then prove
+// the object is publicly readable and byte-identical before any caller records the key. motion.mjs
+// established this order: an entry must never name an object nobody can read, and that holds for
+// the skip path too. The HEAD above is an authenticated S3-API call against the origin; it proves
+// the bytes are right, not that the public edge serves them, so the skip still pays for a 32-byte
+// range-fetch through R2_PUBLIC_BASE_URL -- cheap next to the full upload it avoided.
 //
 // `immutable` is NOT carried over from motion.mjs with it. That key embeds the digest
 // (motion/<slug>/<id>-<sha256[0:16]>.mp4) so it never names two different bodies; an artifact key
@@ -78,18 +113,38 @@ export async function s3Upload(config) {
 // verification below, which range-fetches through R2_PUBLIC_BASE_URL (the edge): under `immutable`
 // it can compare the new body against a cached old object and throw `public bytes differ` AFTER
 // the object was overwritten. The cost is a re-capture taking up to max-age to reach the edge.
-export async function putAndVerify({ config, key, body, contentType, upload, fetcher = fetch }) {
-  const digest = sha256(body);
-  await upload({ Bucket: config.bucket, Key: key, Body: body, ContentType: contentType,
-    CacheControl: 'public, max-age=300', Metadata: { sha256: digest } });
+// The one range-fetch check, run after either a real upload or a skip. Two copies of this would
+// drift -- the whole point of the invariant above is that neither path is allowed to skip it.
+async function verifyPublic({ config, key, body, fetcher, digest, uploaded }) {
   const url = objectUrl(config, key);
   const response = await fetcher(url, { headers: { Range: 'bytes=0-31' }, signal: AbortSignal.timeout(20000) });
   const range = response.headers.get('content-range');
   if (response.status !== 206 || range !== `bytes 0-31/${body.length}`) {
     await response.body?.cancel();
-    throw new Error(`uploaded ${key}, but public verification failed (HTTP ${response.status}); nothing was recorded`);
+    const verb = uploaded ? 'uploaded' : 'matched';
+    throw new Error(`${verb} ${key}, but public verification failed (HTTP ${response.status}); nothing was recorded`);
+  }
+  const headBytes = Buffer.from(await response.arrayBuffer());
+  if (!headBytes.equals(body.subarray(0, 32))) throw new Error(`public bytes differ for ${key}`);
+  return { key, bytes: body.length, sha256: digest, uploaded };
+}
+
+export async function putAndVerify({ config, key, body, contentType, upload, head, fetcher = fetch,
+  retries = 3, sleep = defaultSleep }) {
+  const digest = sha256(body);
+  // Skip a PUT whose bytes are already in the bucket. The digest is compared against the object's
+  // own recorded metadata, not against its length: two different objects of the same size would
+  // otherwise read as identical, which is the exact mistake the artifact cache made and that
+  // 1.0.1 had to fix. An object with NO recorded digest is re-uploaded rather than assumed
+  // identical -- anything written before this field existed has none, and guessing would skip a
+  // needed write forever.
+  if (head) {
+    try {
+      const existing = await head({ Bucket: config.bucket, Key: key });
+      if (existing?.Metadata?.sha256 === digest) return verifyPublic({ config, key, body, fetcher, digest, uploaded: false });
+    } catch { /* NotFound, or a HEAD this account cannot make: fall through and upload */ }
   }
-  const head = Buffer.from(await response.arrayBuffer());
-  if (!head.equals(body.subarray(0, 32))) throw new Error(`public bytes differ for ${key}`);
-  return { key, bytes: body.length, sha256: digest };
+  await withRetry(() => upload({ Bucket: config.bucket, Key: key, Body: body, ContentType: contentType,
+    CacheControl: 'public, max-age=300', Metadata: { sha256: digest } }), retries, sleep);
+  return verifyPublic({ config, key, body, fetcher, digest, uploaded: true });
 }

package/src/ui/app.js

@@ -1,5 +1,8 @@
 // Vanilla, no build step: filters the manifest already rendered into `.card`
 // data attributes. Within one facet, checked boxes OR together; across facets, AND.
+// Filtering sets eligibility only (dataset.filtered); repage(), defined globally by the inline
+// script in index.html loaded before this file, is what decides what's actually painted. Paging
+// stays a view over whatever the filter left eligible, never a filter of its own.
 (function () {
   var grid = document.getElementById('grid');
   var cards = grid ? Array.prototype.slice.call(grid.querySelectorAll('.card')) : [];
@@ -24,8 +27,9 @@
         var have = (card.dataset[facets[i]] || '').split(' ');
         ok = want.some(function (t) { return have.indexOf(t) !== -1; });
       }
-      card.hidden = !ok;
+      card.dataset.filtered = ok ? '' : 'out';
     });
+    repage();
   }
 
   var inputs = document.querySelectorAll('#filters input[type="checkbox"]');

package/src/ui/build.mjs

@@ -46,7 +46,7 @@ function filterFieldset(facet, terms) {
 }
 
 function card(row) {
-  const img = row.thumbnail ? `<img src="${row.thumbnail}" alt="" loading="lazy" decoding="async">` : `<div class="ph"></div>`;
+  const img = row.thumbnail ? `<img src="${row.thumbnail}" alt="" loading="lazy" decoding="async" width="640" height="480">` : `<div class="ph"></div>`;
   const badge = row.draft ? ' <span class="badge">draft</span>' : '';
   const tags = esc([...row.roles, ...row.feel, ...row.motion].join(', '));
   const data = `data-role="${esc(row.roles.join(' '))}" data-feel="${esc(row.feel.join(' '))}" data-motion="${esc(row.motion.join(' '))}"`;
@@ -150,12 +150,20 @@ function writeEntryPage(outDir, entry, row, previewMediaDir, measureFile) {
 export async function buildUi({ indexPath, entriesDir, outDir, previewMediaDir, p }) {
   void indexPath;
   const vocab = loadVocab();
-  fs.rmSync(outDir, { recursive: true, force: true });
+  // Wipe the HTML, keep the pixels. Re-encoding 2000 unchanged thumbnails on every deploy is the
+  // single most expensive thing this build does, and a thumbnail is a pure function of the strip
+  // digest already recorded in entry.md — so it is safe to keep and cheap to invalidate.
+  for (const name of fs.existsSync(outDir) ? fs.readdirSync(outDir) : []) {
+    if (name === 'thumbnails' || name === 'strips') continue;
+    fs.rmSync(path.join(outDir, name), { recursive: true, force: true });
+  }
   fs.mkdirSync(path.join(outDir, 'entry'), { recursive: true });
   fs.mkdirSync(path.join(outDir, 'strips'), { recursive: true });
   fs.mkdirSync(path.join(outDir, 'thumbnails'), { recursive: true });
 
   const rows = [];
+  const unresolved = [];
+  let rendered = 0;
   for (const dir of listEntries(entriesDir)) {
     let entry;
     try { entry = parseEntry(dir); } catch (err) { process.stderr.write(`ui: skipping ${path.basename(dir)}: ${err.message}\n`); continue; }
@@ -167,21 +175,45 @@ export async function buildUi({ indexPath, entriesDir, outDir, previewMediaDir,
     const slug = path.basename(dir);
     let stripSrc = null;
     const strip = (entry.fm.captured?.captures?.[0]?.artifacts ?? []).find((a) => a?.key?.endsWith('/strip.webp'));
-    // One unreachable object must not take the gallery down with it: the entry renders without a
-    // thumbnail, exactly as a draft does, and the build continues.
-    if (strip) { try { stripSrc = await artifactFile(p, strip); } catch { stripSrc = null; } }
-    // Same treatment for measure.json: a record to resolve, never a file next to entry.md.
+    // The index is a browsing surface. Its previews must not make each visitor
+    // download a multi-frame source sheet; the full strip remains on the detail page.
+    const thumb = path.join(outDir, 'thumbnails', `${slug}.webp`);
+    const stamp = path.join(outDir, 'thumbnails', `${slug}.sha256`);
+    const stripOut = path.join(outDir, 'strips', `${slug}.webp`);
+    // The sidecar records WHICH strip produced this thumbnail, AND which encoder made it: a strip
+    // whose digest is unchanged still needs a new render once the encode below changes shape, or
+    // a deploy that ships a new encoder serves the old pixels forever. THUMB sits next to the
+    // sharp() call it describes (below) so the two cannot drift apart silently -- bump it when
+    // that call's parameters change.
+    const THUMB = '640x480-cover-north-webp-q72-e4';
+    // Consulted BEFORE artifactFile, not after: the selective wipe above preserves thumbnails/
+    // and strips/, so when the stamp matches and both outputs are already on disk there is
+    // nothing to resolve -- no cache read, no hash, no fetch, for this entry's strip.
+    let current = null;
+    try { current = fs.readFileSync(stamp, 'utf8').trim(); } catch {}
+    const sidecarHit = !!strip && current === `${THUMB}:${strip.sha256}` && fs.existsSync(thumb) && fs.existsSync(stripOut);
+    // Same treatment for measure.json: a record to resolve, never a file next to entry.md. It has
+    // no sidecar of its own and is a different artifact, so it always resolves here regardless of
+    // the strip's sidecar outcome.
     let measureSrc = null;
     const measured = (entry.fm.captured?.captures?.[0]?.artifacts ?? []).find((a) => a?.key?.endsWith('/measure.json'));
-    if (measured) { try { measureSrc = await artifactFile(p, measured); } catch { measureSrc = null; } }
-    const hasStrip = stripSrc !== null;
-    if (hasStrip) {
-      fs.copyFileSync(stripSrc, path.join(outDir, 'strips', `${slug}.webp`));
-      // The index is a browsing surface. Its previews must not make each visitor
-      // download a multi-frame source sheet; the full strip remains on the detail page.
-      await sharp(stripSrc).resize(640, 480, { fit: 'cover', position: 'north' })
-        .webp({ quality: 72, effort: 4 }).toFile(path.join(outDir, 'thumbnails', `${slug}.webp`));
+    if (measured) { try { measureSrc = await artifactFile(p, measured); } catch (err) { measureSrc = null; unresolved.push(err); } }
+    // One unreachable object must not take the gallery down with it: the entry renders without a
+    // thumbnail, exactly as a draft does, and the build continues.
+    // Degrading silently is what made a misconfigured host indistinguishable from a broken one:
+    // a gallery of 31 grey boxes, `ok: true` from healthz, and not one line saying why. Swallow
+    // the failure, still — but count it and keep the first reason.
+    if (strip && !sidecarHit) {
+      try {
+        stripSrc = await artifactFile(p, strip);
+        fs.copyFileSync(stripSrc, stripOut);
+        await sharp(stripSrc).resize(640, 480, { fit: 'cover', position: 'north' }) // THUMB above must name these params
+          .webp({ quality: 72, effort: 4 }).toFile(thumb);
+        fs.writeFileSync(stamp, `${THUMB}:${strip.sha256}`);
+        rendered++;
+      } catch (err) { stripSrc = null; unresolved.push(err); }
     }
+    const hasStrip = sidecarHit || stripSrc !== null;
     const fm = entry.fm;
     const capturedAt = fm.captured?.at;
     const captured = capturedAt instanceof Date ? capturedAt.toISOString().slice(0, 10) : String(capturedAt ?? '');
@@ -212,5 +244,11 @@ export async function buildUi({ indexPath, entriesDir, outDir, previewMediaDir,
   fs.writeFileSync(path.join(outDir, 'index.html'), render(tpl, { FILTERS: filters, GRID: rows.map(card).join('\n'), NOTICE: notice }));
   fs.copyFileSync(path.join(DIR, 'app.js'), path.join(outDir, 'app.js'));
 
-  return { entries: rows.length - drafts, drafts };
+  // One line, not one per artifact: 31 entries failing for the same missing variable is one
+  // fact, and printing it 62 times would bury it. The first reason is the one that matters —
+  // they are identical when the cause is configuration, which is the case worth naming.
+  if (unresolved.length) {
+    process.stderr.write(`ui: ${unresolved.length} artifact(s) could not be resolved, so those entries render without a thumbnail; first reason: ${unresolved[0].message}\n`);
+  }
+  return { entries: rows.length - drafts, drafts, unresolved: unresolved.length, rendered };
 }

package/src/ui/templates/index.html

@@ -26,9 +26,32 @@
 <label><input type="checkbox" id="drafts-toggle"> Show drafts</label>
 </form>
 {{NOTICE}}
-<div id="grid">
+<div id="grid" data-page-size="60">
 {{GRID}}
 </div>
+<button id="show-more" hidden>Show more</button>
+<script>
+// Paging is a view over whatever the filter left eligible, never a filter itself: `cards` is
+// still every card in the document, so a search always sees the whole corpus. Only how many
+// eligible cards are currently painted changes.
+var cards = document.querySelectorAll(".card");
+var PAGE = parseInt(document.querySelector("[data-page-size]").dataset.pageSize, 10);
+var shown = PAGE;
+function repage() {
+  var n = 0;
+  cards.forEach(function (c) {
+    if (c.dataset.filtered === "out") { c.hidden = true; return; }
+    n++;
+    c.hidden = n > shown;
+  });
+  var more = document.getElementById("show-more");
+  more.hidden = n <= shown;
+}
+document.getElementById("show-more").addEventListener("click", function () {
+  shown += PAGE;
+  repage();
+});
+</script>
 <script src="app.js"></script>
 </body>
 </html>