@yojahny/wp-design-library 0.5.1 → 0.6.0

package/entries/superr/entry.md

@@ -5,7 +5,9 @@ tier: inspiration
 source:
   kind: public-site
   url: https://www.superr.ai/
-  license: Captured from a Refero-hosted recording and the live site; description only, no redistribution of the source.
+  license: >-
+    Captured from a Refero-hosted recording and the live site; description only, no redistribution of the
+    source.
 captured:
   method: frames
   at: '2026-09-16'
@@ -14,14 +16,23 @@ captured:
     - method: frames
       input: /tmp/superr-refero.mp4
       artifacts:
-        - strip.webp
+        - key: entries/superr/1/strip.webp
+          bytes: 274670
+          sha256: aba7bdda980d83f1996a50f7a65cbd370aa0466bc802941c347c873b0c7371f3
       frames: 36
       duration_ms: 20217
 media:
   frames: 36
   duration_ms: 20217
-roles: [hero, explainer, feature]
-feel: [light, playful, warm, premium]
+roles:
+  - hero
+  - explainer
+  - feature
+feel:
+  - light
+  - playful
+  - warm
+  - premium
 palette:
   canvas: '#fdfbf9'
   ink: '#171717'
@@ -30,8 +41,13 @@ type:
   display: gelica, "gelica Fallback", Georgia, serif
   body: gelica, "gelica Fallback", Georgia, serif
 motion:
-  devices: [reveal, pan]
-  notes: Eyeballed from 36 sampled frames, not measured. A large notebook dominates the hero, then reveals handwritten labels, stickers, and an opened-book application scene. No scroll behavior or individual triggers are visible.
+  devices:
+    - reveal
+    - pan
+  notes: >-
+    Eyeballed from 36 sampled frames, not measured. A large notebook dominates the hero, then reveals
+    handwritten labels, stickers, and an opened-book application scene. No scroll behavior or individual
+    triggers are visible.
 ported_from: null
 ---
 

package/entries/svz-weare/entry.md

@@ -14,16 +14,26 @@ captured:
     - method: frames
       input: /home/yojahny/Desktop/inspiration/weare.mp4
       artifacts:
-        - strip.webp
+        - key: entries/svz-weare/1/strip.webp
+          bytes: 219198
+          sha256: 98c48537b768405a47817cbf398892ce026d1202ff50d833916b26e780ba62d7
       frames: 36
       duration_ms: 21900
     - method: both
       input: https://www.svz.io/
       artifacts:
-        - captures/2/strip.webp
-        - captures/2/measure.json
-        - captures/2/screen-1440.png
-        - captures/2/screen-390.png
+        - key: entries/svz-weare/2/strip.webp
+          bytes: 163242
+          sha256: fc794258d46dc28bd7d905f19380c2941775996bcb48f7f49953028b3b361ec4
+        - key: entries/svz-weare/2/measure.json
+          bytes: 2499
+          sha256: c2291e55af1be7426047b2a55188db7fcbd951b98af439aa8ed26161b9fca1e9
+        - key: entries/svz-weare/2/screen-1440.png
+          bytes: 59470
+          sha256: 14abebdc6411792eff6afd1e5692693f857d3ae07363c4ee29a1f24bb8b83efa
+        - key: entries/svz-weare/2/screen-390.png
+          bytes: 20897
+          sha256: 54228ad1733da9a9b403e703e00906942ea2acdb768a092d7d8a42af84286c72
 media:
   frames: 36
   duration_ms: 21900

package/entries/thoughtlab/entry.md

@@ -5,7 +5,9 @@ tier: inspiration
 source:
   kind: public-site
   url: https://www.thoughtlab.com/
-  license: Captured from a Refero-hosted recording and the live site; description only, no redistribution of the source.
+  license: >-
+    Captured from a Refero-hosted recording and the live site; description only, no redistribution of the
+    source.
 captured:
   method: both
   at: '2026-09-16'
@@ -14,21 +16,42 @@ captured:
     - method: frames
       input: /tmp/thoughtlab-refero.mp4
       artifacts:
-        - strip.webp
+        - key: entries/thoughtlab/1/strip.webp
+          bytes: 260958
+          sha256: 8d8e191dd3fecd18a394c54da3a275c90c78bffca607c87df5f1eca7dc052061
       frames: 36
       duration_ms: 24533
     - method: both
       input: https://www.thoughtlab.com/
       artifacts:
-        - captures/2/strip.webp
-        - captures/2/measure.json
-        - captures/2/screen-1440.png
-        - captures/2/screen-390.png
+        - key: entries/thoughtlab/2/strip.webp
+          bytes: 230142
+          sha256: 844c95156c28937ed5709b14bb47b28ec6d26e35a0703c8f39a5e93f5df7a82a
+        - key: entries/thoughtlab/2/measure.json
+          bytes: 1669
+          sha256: 033fcecae1af22f5c822f74fc3beff60c7fade187413fd0ad04e8dea2b7e42a4
+        - key: entries/thoughtlab/2/screen-1440.png
+          bytes: 145595
+          sha256: 1c36b785010a7de3d012b553a7029e5c5b7a57596edde81edf100323c152dc7f
+        - key: entries/thoughtlab/2/screen-390.png
+          bytes: 77652
+          sha256: 3d8dd9d72c2ae7a43cee2d62b5659a73b7d19f308297c4eed2fae551fa454310
 media:
   frames: 36
   duration_ms: 24533
-roles: [hero, feature, capability, proof, closing, footer]
-feel: [dark, premium, editorial, depth, cold]
+roles:
+  - hero
+  - feature
+  - capability
+  - proof
+  - closing
+  - footer
+feel:
+  - dark
+  - premium
+  - editorial
+  - depth
+  - cold
 palette:
   canvas: '#000000'
   ink: '#cccccc'
@@ -37,8 +60,17 @@ type:
   display: sui
   body: sui
 motion:
-  devices: [reveal, pan, drift, wipe, tabs]
-  notes: 'The supplied recording moves through a sequence of project names while irregular glass-like image portals change their internal imagery and edge light. Large condensed labels reveal beside each portal, then the composition wipes to the next case. The live capture confirms the hero portal and fixed header, but does not expose CSS animation records or individual input triggers.'
+  devices:
+    - reveal
+    - pan
+    - drift
+    - wipe
+    - tabs
+  notes: >-
+    The supplied recording moves through a sequence of project names while irregular glass-like image portals
+    change their internal imagery and edge light. Large condensed labels reveal beside each portal, then the
+    composition wipes to the next case. The live capture confirms the hero portal and fixed header, but does
+    not expose CSS animation records or individual input triggers.
 ported_from: null
 ---
 

package/entries/ventriloc/entry.md

@@ -5,7 +5,9 @@ tier: inspiration
 source:
   kind: public-site
   url: https://ventriloc.ca/en
-  license: Captured from a Refero-hosted recording and the live site; description only, no redistribution of the source.
+  license: >-
+    Captured from a Refero-hosted recording and the live site; description only, no redistribution of the
+    source.
 captured:
   method: frames
   at: '2026-09-16'
@@ -14,14 +16,23 @@ captured:
     - method: frames
       input: /tmp/ventriloc-refero.mp4
       artifacts:
-        - strip.webp
+        - key: entries/ventriloc/1/strip.webp
+          bytes: 225040
+          sha256: 7f9e5830cb7fbd754cc82132dba195e7fccec7c6893f5c7e6cf9200712e5de90
       frames: 36
       duration_ms: 6567
 media:
   frames: 36
   duration_ms: 6567
-roles: [hero, proof, feature]
-feel: [light, premium, saas, minimal]
+roles:
+  - hero
+  - proof
+  - feature
+feel:
+  - light
+  - premium
+  - saas
+  - minimal
 palette:
   canvas: '#f5f5f5'
   ink: '#202020'
@@ -30,8 +41,13 @@ type:
   display: PolySans, sans-serif
   body: Inter, sans-serif
 motion:
-  devices: [reveal, pan]
-  notes: Eyeballed from 36 sampled frames, not measured. Dashboard cards and chart lines animate into the right side of the hero while the headline stays anchored on the left; later sampled frames show the metric states changing. Individual triggers are not visible.
+  devices:
+    - reveal
+    - pan
+  notes: >-
+    Eyeballed from 36 sampled frames, not measured. Dashboard cards and chart lines animate into the right
+    side of the hero while the headline stays anchored on the left; later sampled frames show the metric
+    states changing. Individual triggers are not visible.
 ported_from: null
 ---
 

package/entries/vivid-and-co/entry.md

@@ -14,14 +14,28 @@ captured:
     - method: frames
       input: /home/yojahny/Desktop/inspiration/evivid.mp4
       artifacts:
-        - strip.webp
+        - key: entries/vivid-and-co/1/strip.webp
+          bytes: 190158
+          sha256: 881005f80102d0e249067ce9aa89a61c6afaf576f4d5867687f2209081a3caa7
       frames: 36
       duration_ms: 36833
 media:
   frames: 36
   duration_ms: 36833
-roles: [hero, explainer, capability, proof, closing, footer]
-feel: [dark, premium, editorial, minimal, depth, cold]
+roles:
+  - hero
+  - explainer
+  - capability
+  - proof
+  - closing
+  - footer
+feel:
+  - dark
+  - premium
+  - editorial
+  - minimal
+  - depth
+  - cold
 palette:
   canvas: '#101010'
   ink: '#fffdf9'
@@ -30,8 +44,19 @@ type:
   display: '"Neue Montreal"'
   body: '"Neue Montreal", sans-serif'
 motion:
-  devices: [reveal, pan, drift, stagger, wipe]
-  notes: 'The supplied recording shows a refractive block assembly slowly rotating and drifting through the opening statements, while large type changes in staged fragments around it. Each chapter uses a restrained fade or wipe into a new text composition; the prismatic light field remains as a connecting layer. The live capture records a long sequence of SVG animations across the page. It confirms that the chromatic object and surrounding graphic treatment are animated, but this capture does not establish individual interaction triggers.'
+  devices:
+    - reveal
+    - pan
+    - drift
+    - stagger
+    - wipe
+  notes: >-
+    The supplied recording shows a refractive block assembly slowly rotating and drifting through the opening
+    statements, while large type changes in staged fragments around it. Each chapter uses a restrained fade or
+    wipe into a new text composition; the prismatic light field remains as a connecting layer. The live
+    capture records a long sequence of SVG animations across the page. It confirms that the chromatic object
+    and surrounding graphic treatment are animated, but this capture does not establish individual interaction
+    triggers.
 ported_from: null
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yojahny/wp-design-library",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Design reference corpus and MCP server for claude-wp-builder",
   "repository": {
     "type": "git",
@@ -55,10 +55,12 @@
     "docker-compose.yml",
     "docker/",
     "entries/",
+    "src/artifacts.mjs",
     "src/cli/add.mjs",
     "src/cli/check.mjs",
     "src/cli/export.mjs",
     "src/cli/index.mjs",
+    "src/cli/migrate-artifacts.mjs",
     "src/cli/motion.mjs",
     "src/cli/refresh.mjs",
     "src/cli/save.mjs",
@@ -70,6 +72,7 @@
     "src/mcp/",
     "src/motion.mjs",
     "src/paths.mjs",
+    "src/r2.mjs",
     "src/ui/",
     "src/vocab.mjs",
     "vocab.yaml",

package/src/artifacts.mjs

@@ -0,0 +1,31 @@
+// The seam every reader goes through. Callers ask for a file; whether it came from the cache or
+// from R2 is not their business. The cache mirrors motion's .library/media so there is one place
+// on disk where fetched bytes live.
+import fs from 'node:fs';
+import path from 'node:path';
+import { isArtifactKey, objectUrl, readConfig, sha256 } from './r2.mjs';
+
+export function cachePath(p, key) {
+  if (!isArtifactKey(key)) throw new Error(`invalid artifact key: ${key}`);
+  return path.join(p.data, '.library', 'media', key);
+}
+
+// config is resolved lazily, inside the cache MISS, and through readConfig — which asks for
+// R2_PUBLIC_BASE_URL and nothing else. As a default PARAMETER (`config = r2Config()`) it evaluated
+// on entry, before the cache-hit branch below, so a warm cache was unusable without credentials
+// and a read-only host had to hold R2_SECRET_ACCESS_KEY to render a thumbnail. Same bug class
+// 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;
+  config ??= readConfig();
+  const url = objectUrl(config, artifact.key);
+  const response = await fetcher(url, { signal: AbortSignal.timeout(30000) });
+  if (!response.ok) throw new Error(`${artifact.key}: R2 returned HTTP ${response.status}`);
+  const body = Buffer.from(await response.arrayBuffer());
+  if (body.length !== artifact.bytes) throw new Error(`${artifact.key}: expected ${artifact.bytes} bytes, got ${body.length}`);
+  if (sha256(body) !== artifact.sha256) throw new Error(`${artifact.key}: digest does not match what the entry records`);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, body);
+  return file;
+}

package/src/cli/add.mjs

@@ -8,6 +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';
 
 function opt(args, name) { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; }
 
@@ -40,9 +41,9 @@ 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: a total
-// failure (nothing captured at all) must leave nothing under entries/.
-async function addFromUrl({ p, input, slug, title, source, dir, record, force, attach }) {
+// 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 }) {
   const fs = await import('node:fs');
   const os = await import('node:os');
   const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'wpdl-add-'));
@@ -82,27 +83,43 @@ async function addFromUrl({ p, input, slug, title, source, dir, record, force, a
     await stripFromFrames(result.frames, scratchStrip);
   }
 
+  // Upload BEFORE the wipe, straight out of scratch. putAndVerify proves the object is publicly
+  // readable and byte-identical, so an entry can never name a key nobody can fetch — but it is 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.
+  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' };
+  const artifacts = [];
+  try {
+    config ??= r2Config();
+    if (!upload) upload = await s3Upload(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 }));
+    }
+  } catch (err) {
+    fs.rmSync(scratch, { recursive: true, force: true });
+    throw err;
+  }
+
   // Gated on index, not force directly: index===1 is the same decision the attach-vs-recreate
   // branch below acts on, so the two can never disagree — a regression that breaks the line
   // above (force stops forcing index to 1) also stops this wipe from firing, instead of wiping
   // a directory out from under a capture the buggy code is about to attach to. It fires only
-  // here, below the compositing, so nothing between measure() and a written strip can destroy
-  // an existing entry and leave nothing in its place; what follows is copies out of scratch.
+  // here, below the compositing AND below the upload, so nothing that can fail stands between
+  // the wipe and a written entry; what follows is copies out of scratch.
   if (index === 1) fs.rmSync(dir, { recursive: true, force: true });
   const outDir = captureDir(dir, index);
   fs.mkdirSync(outDir, { recursive: true });
   const strip = path.join(outDir, 'strip.webp');
-  fs.copyFileSync(scratchStrip, strip);
-  if (result.ok) {
-    for (const f of ['measure.json', 'screen-1440.png', 'screen-390.png']) {
-      fs.copyFileSync(path.join(scratch, f), path.join(outDir, f));
-    }
-  }
+  for (const name of names) fs.copyFileSync(path.join(scratch, name), path.join(outDir, name));
   fs.rmSync(scratch, { recursive: true, force: true });
 
-  const artifactNames = ['strip.webp'];
-  if (result.ok) artifactNames.push('measure.json', 'screen-1440.png', 'screen-390.png');
-  const artifacts = artifactNames.map((f) => path.relative(dir, path.join(outDir, f)));
   const capture = { method: captured.method, input, artifacts };
 
   if (index > 1) {
@@ -114,7 +131,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 }) {
+export async function addEntry({ input, slug, title, source, force = false, frames, record = false, attach = false, config, upload, 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
@@ -123,14 +140,14 @@ export async function addEntry({ input, slug, title, source, force = false, fram
     return { refused: `source.kind: unknown source term "${source.kind}"` };
   }
   const dir = path.join(p.entries, slug);
-  const { mkdirSync, mkdtempSync, renameSync, copyFileSync, unlinkSync, rmSync } = await import('node:fs');
+  const { mkdirSync, mkdtempSync, renameSync, copyFileSync, unlinkSync, rmSync, readFileSync } = await import('node:fs');
   const os = await import('node:os');
   const exists = existsSync(path.join(dir, 'entry.md'));
   if (exists && !force && !attach) {
     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 });
+    return addFromUrl({ p, input, slug, title, source, dir, record, force, attach, config, upload, fetcher });
   }
   // Sample into a scratch dir first: a refusal must leave nothing under entries/.
   const scratch = mkdtempSync(path.join(os.tmpdir(), 'wpdl-add-'));
@@ -146,13 +163,28 @@ export async function addEntry({ input, slug, title, source, force = false, fram
   // force always wipes and recreates as capture 1, exactly as it does today, regardless of
   // attach; only a plain attach (no force) merges onto the existing capture list.
   const index = (!force && attach) ? nextCaptureIndex(dir) : 1;
+  // Same upload-before-anything-is-destroyed contract as the URL path: the bytes are already in
+  // scratch, and putAndVerify's network round trip must not stand between the wipe and a written
+  // entry. Resolved lazily, after every refusal above, so those never need R2 credentials.
+  let stripArtifact;
+  try {
+    config ??= r2Config();
+    if (!upload) upload = await s3Upload(config);
+    stripArtifact = await putAndVerify({
+      config, key: artifactKey(slug, index, 'strip.webp'), body: readFileSync(scratchStrip),
+      contentType: 'image/webp', upload, fetcher,
+    });
+  } catch (err) {
+    rmSync(scratch, { recursive: true, force: true });
+    throw err;
+  }
+
   // Gated on index, not force directly: index===1 is the same decision the attach-vs-recreate
   // branch below acts on, so the two can never disagree — a regression that breaks the line
   // above (force stops forcing index to 1) also stops this wipe from firing, instead of wiping
   // a directory out from under a capture the buggy code is about to attach to. The wipe happens
-  // only here — after sampleFrames has already succeeded into scratch (a sampling failure above
-  // is already handled by the catch block) — so it can never destroy an existing entry and
-  // leave nothing in its place.
+  // only here — after sampleFrames has succeeded into scratch AND after the upload has been
+  // verified — so it can never destroy an existing entry and leave nothing in its place.
   if (index === 1) rmSync(dir, { recursive: true, force: true });
   const outDir = captureDir(dir, index);
   mkdirSync(outDir, { recursive: true });
@@ -165,9 +197,8 @@ export async function addEntry({ input, slug, title, source, force = false, fram
   }
   rmSync(scratch, { recursive: true, force: true });
 
-  const rel = path.relative(dir, strip);
   const capture = {
-    method: 'frames', input, artifacts: [rel],
+    method: 'frames', input, artifacts: [stripArtifact],
     frames: media.frames, duration_ms: media.durationMs,
   };
   const mediaFields = { frames: media.frames, duration_ms: media.durationMs };
@@ -183,7 +214,7 @@ 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 }) {
+export async function addInbox({ source, config, upload, fetcher }) {
   const p = paths();
   const fs = await import('node:fs');
   const inbox = path.join(p.data, 'inbox');
@@ -204,7 +235,7 @@ export async function addInbox({ source }) {
     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; }
     try {
-      const r = await addEntry({ input: full, slug, title: meta.title ?? slug.replace(/-/g, ' '), source: { kind, url: meta.url ?? source?.url, license } });
+      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 }); }
   }

package/src/cli/index.mjs

@@ -4,7 +4,7 @@ import { buildIndex } from '../index/build.mjs';
 
 export async function run() {
   const p = paths();
-  const r = await buildIndex({ entriesDir: p.entries, indexPath: p.index, vocab: loadVocab(p.vocab), models: p.models });
+  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`);
   for (const s of r.skipped) process.stderr.write(`embeddings: skipped (${s.reason})\n`);

package/src/cli/migrate-artifacts.mjs

@@ -0,0 +1,92 @@
+// One-way move. Nothing is recomputed: agreement blocks, observed colours and captured.at record
+// what was true at capture time, and re-deriving them to match today's files would rewrite history
+// to fit the present. This only changes where the bytes live.
+import fs from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { paths } from '../paths.mjs';
+import { listEntries, parseEntry } from '../entry.mjs';
+import { artifactKey, putAndVerify, r2Config, s3Upload, sha256 } from '../r2.mjs';
+
+const TYPES = { '.webp': 'image/webp', '.png': 'image/png', '.json': 'application/json' };
+
+// config is resolved lazily, only once we know a real upload is about to happen -- the same
+// contract add.mjs already established (`config ??= r2Config()`, "so those never need R2
+// credentials"). A `config = r2Config()` default *parameter* would evaluate eagerly on every
+// call, --dry-run included, since JS runs a default expression whenever the argument is
+// omitted; that would make a dry run impossible without credentials, defeating its purpose
+// as a no-credentials preflight.
+export async function migrateArtifacts({ p = paths(), config, upload, fetcher = fetch, dryRun = false } = {}) {
+  if (!dryRun) config ??= r2Config();
+  if (!upload && !dryRun) upload = await s3Upload(config);
+  // `records` carries every {key, bytes, sha256} the run produced, in both modes. Counts alone
+  // could not be diffed, which is the one thing a preflight is for -- and they left the dry run's
+  // digest unobservable, so nothing could tell a real hash from a placeholder.
+  const report = { entries: 0, uploaded: 0, skipped: 0, failed: [], records: [] };
+  for (const dir of listEntries(p.entries)) {
+    const entry = parseEntry(dir);
+    const slug = path.basename(dir);
+    // An entry written before captures[] existed has no field to read at all -- attach.mjs's
+    // existingCaptureFrom used to synthesize this on the fly ("migration writes them" is the
+    // comment left in its place), so this is the last point capture 1 can be recovered instead
+    // of leaving the entry permanently invalid. Only what is actually recorded is used: method
+    // (captured.method) and frames/duration_ms (media), if present. `input` is deliberately
+    // never invented -- source.url is a fair guess for a URL-sourced entry and actively wrong
+    // for a local-file one (media.frames/duration_ms without a recorded path), and validateEntry
+    // never reads capture.input, so omitting it honestly signals "not recorded".
+    const captured = entry.fm.captured ?? (entry.fm.captured = {});
+    if (captured.captures == null) {
+      const method = captured.method;
+      const artifacts = ['strip.webp'];
+      if (method === 'measured' || method === 'both') artifacts.push('measure.json', 'screen-1440.png', 'screen-390.png');
+      const capture = { method, artifacts };
+      if (entry.fm.media?.frames != null) capture.frames = entry.fm.media.frames;
+      if (entry.fm.media?.duration_ms != null) capture.duration_ms = entry.fm.media.duration_ms;
+      captured.captures = [capture];
+    }
+    const captures = captured.captures;
+    report.entries++;
+    try {
+      for (const [i, capture] of captures.entries()) {
+        const migrated = [];
+        for (const artifact of capture.artifacts ?? []) {
+          if (artifact && typeof artifact === 'object' && artifact.key) { migrated.push(artifact); report.skipped++; continue; }
+          const rel = String(artifact);
+          const file = path.join(dir, rel);
+          const body = fs.readFileSync(file);
+          const key = artifactKey(slug, i + 1, path.basename(rel));
+          // A dry run already has the bytes in hand, so it reports the real digest putAndVerify
+          // would record, not a placeholder -- a preflight worth diffing against the real run,
+          // which is why the record goes into the report and not only into the entry.
+          const record = dryRun
+            ? { key, bytes: body.length, sha256: sha256(body) }
+            : await putAndVerify({ config, key, body, contentType: TYPES[path.extname(rel)], upload, fetcher });
+          migrated.push(record);
+          report.records.push(record);
+          report.uploaded++;
+        }
+        capture.artifacts = migrated;
+      }
+      if (!dryRun) {
+        fs.writeFileSync(path.join(dir, 'entry.md'),
+          `---\n${yaml.dump(entry.fm, { lineWidth: 110, noRefs: true })}---\n\n${entry.body}\n`);
+        for (const capture of captures) {
+          for (const a of capture.artifacts) {
+            const local = path.join(dir, path.basename(a.key));
+            if (fs.existsSync(local)) fs.rmSync(local);
+          }
+        }
+        fs.rmSync(path.join(dir, 'captures'), { recursive: true, force: true });
+      }
+    } catch (err) {
+      report.failed.push({ slug, reason: err.message });
+    }
+  }
+  return report;
+}
+
+export async function run(args) {
+  const report = await migrateArtifacts({ dryRun: args.includes('--dry-run') });
+  process.stdout.write(JSON.stringify(report) + '\n');
+  return report.failed.length ? 1 : 0;
+}