@sprid/cli 0.1.2

package/src/post/cli.mjs

@@ -0,0 +1,2285 @@
+// sprid post — the local half of Sprid.
+//
+// **It never renders anything.** How a file was made is the consuming repo's
+// business; this package's whole subject is a finished local file becoming a
+// Sprid draft, reproducibly and with the checks. That boundary is what lets it
+// serve a repo whose reels come out of a bespoke pipeline and one whose reels
+// come out of After Effects.
+//
+// **It does not need an agent.** Everything goes through the REST API with a
+// `sprd_` personal access token, so a CI job can run it. The MCP server is the
+// agent-facing convenience over the same endpoints, not the only door.
+//
+// **A post here is a reel OR a carousel**, and the difference is one field.
+// Everything the package does - measure, gate, preview, upload, draft - is the
+// same shape for a set of images as for one mp4, and the two kinds differ only
+// in what "the media" is and what can be true of it. Naming the whole thing
+// after reels was a bet that the pixels are always video, which they are not.
+//
+// The registry lives in the CONSUMING repo and is committed:
+//
+//   <registry>/posts/<slug>.json     the record  (legacy: reels/, still read)
+//   <registry>/captions/<slug>.txt   the caption, verbatim
+//
+// No media in git. The manifest carries the sha256, so a file that no longer
+// matches its record is detectable without keeping the file, and the specs in
+// the consuming repo reproduce it.
+
+import { execFileSync, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { watch } from "node:fs";
+import { createServer } from "node:http";
+import { previewHandler } from "./preview-server.mjs";
+import { projectPost } from "./rules/platform-rules.mjs";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+// Resolve both the token and its service URL from the same credentials.
+import { resolveAuth, DEFAULT_API_URL } from "../creds.mjs";
+import { assertCredentialDestination } from '../endpoint.mjs';
+
+/**
+ * The API these verbs talk to, from the one login.
+ *
+ * **Lazy and guarded, and both matter.** `resolveAuth` throws when nobody is
+ * logged in, and `doctor` exists precisely to be run in that state; and reading
+ * it at module load would freeze the answer before `sprid.config` or an env var
+ * could be considered. Taking only the token from the login and defaulting the
+ * URL to production can select the wrong service, so both halves come from
+ * the same place or neither does.
+ */
+function defaultApi() {
+  if (process.env.SPRID_URL) return process.env.SPRID_URL;
+  try {
+    return resolveAuth().apiUrl || DEFAULT_API_URL;
+  } catch {
+    return DEFAULT_API_URL;
+  }
+}
+
+// ─── plumbing ────────────────────────────────────────────────────────────────
+
+const C = {
+  dim: (s) => `\x1b[2m${s}\x1b[0m`,
+  bold: (s) => `\x1b[1m${s}\x1b[0m`,
+  ok: (s) => `\x1b[32m${s}\x1b[0m`,
+  bad: (s) => `\x1b[31m${s}\x1b[0m`,
+  warn: (s) => `\x1b[33m${s}\x1b[0m`,
+};
+
+function flag(argv, name) {
+  const args = argv.slice(0, argv.includes("--") ? argv.indexOf("--") : argv.length);
+  const inline = args.find(a => a.startsWith(`--${name}=`));
+  if (inline) return inline.slice(name.length + 3);
+  const i = args.indexOf(`--${name}`);
+  return i >= 0 && !args[i + 1]?.startsWith("--") ? args[i + 1] : undefined;
+}
+const has = (argv, name) => argv.slice(0, argv.includes("--") ? argv.indexOf("--") : argv.length).includes(`--${name}`);
+
+/**
+ * The one bare word: a slug.
+ *
+ * **A flag's value is not a positional argument**, and reading the first
+ * non-`--` token as one made `register --built-with "…"` try to register a
+ * reel called "ffmpeg fixture". Every flag that takes a value is named here.
+ */
+const VALUE_FLAGS = new Set(["out", "lane", "built-with", "port", "serve", "kind", "platforms"]);
+function positional(argv) {
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--") return argv[i + 1];
+    if (a.startsWith("--")) {
+      if (VALUE_FLAGS.has(a.slice(2))) i++;
+      continue;
+    }
+    return a;
+  }
+  return undefined;
+}
+
+/** `KEY=value` out of the consuming repo's `.env`, so a token need not be exported. */
+function readDotEnv(root) {
+  const f = join(root, ".env");
+  if (!existsSync(f)) return {};
+  const out = {};
+  for (const line of readFileSync(f, "utf8").split("\n")) {
+    const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+    if (m) out[m[1]] = m[2].trim().replace(/^["']|["']$/g, "");
+  }
+  return out;
+}
+
+/**
+ * The token - and **which** token matters more than where it is found.
+ *
+ * A PAT is workspace-scoped, and a machine that posts for three brands holds
+ * three of them. `tokenEnv` names the one THIS repo is allowed to use, and when
+ * it is set nothing else is tried: a run that quietly fell back to the personal
+ * token would authenticate against workspaces this repo must not be able to
+ * reach, and nothing in the output would say so. Without `tokenEnv` the order
+ * is the one a person would expect.
+ */
+function token(cfg = {}) {
+  assertCredentialDestination(cfg.apiUrl || defaultApi(), defaultApi());
+  // A repo may pin itself to one workspace's token, and when it does nothing
+  // else is tried: a run that quietly fell back to the personal token would
+  // authenticate against workspaces this repo must not reach, and nothing in
+  // the output would say so.
+  if (cfg.tokenEnv) {
+    const env = cfg.root ? readDotEnv(cfg.root) : {};
+    const v = process.env[cfg.tokenEnv] || env[cfg.tokenEnv];
+    if (v) return v.trim();
+    throw new Error(
+      `No token. sprid.config pins this repo to \`tokenEnv: "${cfg.tokenEnv}"\`, so that is the only one used.\n` +
+        `  Export it, or put it in ${join(cfg.root ?? ".", ".env")}. It must be scoped to the workspace that owns "${cfg.account}".`,
+    );
+  }
+  const env = cfg.root ? readDotEnv(cfg.root) : {};
+  if (env.SPRID_TOKEN) return env.SPRID_TOKEN.trim();
+  return resolveAuth().token;
+}
+
+/**
+ * Config, `.ts` preferred and `.json` accepted.
+ *
+ * The `.ts` form is the one worth writing - it takes comments and a type - and
+ * it loads under bun and under node 22's type stripping. The `.json` fallback
+ * exists so a customer on an older node is not blocked by a file format.
+ */
+async function loadConfig(cwd = process.cwd()) {
+  for (const name of ["sprid.config.ts", "sprid.config.mjs", "sprid.config.js"]) {
+    const p = join(cwd, name);
+    if (existsSync(p)) {
+      const mod = await import(pathToFileURL(p).href);
+      return normalizeConfig(mod.default ?? mod, cwd);
+    }
+  }
+  const j = join(cwd, "sprid.config.json");
+  if (existsSync(j)) return normalizeConfig(JSON.parse(readFileSync(j, "utf8")), cwd);
+  throw new Error("No sprid.config.ts (or .json) here. Run `sprid post init` first.");
+}
+
+const ALL_CHECKS = ["duration", "loudness", "batchSpread", "caption", "slides", "aspect", "provenance", "words", "voice", "sources", "crosspost"];
+const LANE_KEYS = new Set([
+  "kind", "media", "slides", "caption", "spec", "build",
+  "expect", "hashtags", "captionMustContain", "captionEndsSentence", "captionEndWords", "maxDeviationDb",
+  // Where in the video the poster comes from. Frame 0 by default; a lane whose
+  // opening card is still arriving there says so. See `coverFrame`.
+  "coverAtMs",
+  // composed lanes: what Sprid is asked to render, and what may not be said
+  "format", "template", "contentType", "neverSay", "sourcesRequired", "platforms",
+]);
+
+/**
+ * **A misspelled key used to be a silent skip**, which is the worst thing a
+ * gate can do: `lufs:` written at the top of a lane instead of inside
+ * `expect:` reports "skip: no lufs range in the lane" on every row, and a
+ * skipped check reads as a batch that was measured. Anything not recognised is
+ * named here, once, at the top of every command.
+ */
+export function normalizeConfig(cfg, cwd) {
+  if (!cfg?.account) throw new Error("sprid.config: `account` is required (the Sprid account slug).");
+  if (!cfg.lanes || !Object.keys(cfg.lanes).length)
+    throw new Error("sprid.config: at least one lane is required. A lane says where finished media lives.");
+
+  const complaints = [];
+  for (const [name, lane] of Object.entries(cfg.lanes)) {
+    if (lane.kind !== "composed" && !lane.media && !lane.slides)
+      throw new Error(
+        `sprid.config: lane "${name}" needs \`media\` (one file per post), \`slides\` (a deck of images), ` +
+          "or `kind: \"composed\"` (Sprid renders it; this repo holds the copy).",
+      );
+    checkedPlatforms(lane.platforms);
+    for (const k of Object.keys(lane)) if (!LANE_KEYS.has(k)) complaints.push(`lane "${name}": unknown key \`${k}\``);
+    const tpl = lane.kind === "composed" ? (lane.spec ?? "social/specs/<slug>.json") : (lane.slides ?? lane.media);
+    if (!tpl.includes("<slug>")) complaints.push(`lane "${name}": the path has no <slug>, so nothing can be discovered in it`);
+  }
+  for (const c of cfg.checks ?? []) if (!ALL_CHECKS.includes(c)) complaints.push(`unknown check "${c}"`);
+  for (const c of complaints) console.log(`  ${C.warn("config")} ${c}`);
+
+  return {
+    apiUrl: cfg.apiUrl || defaultApi(),
+    account: cfg.account,
+    platforms: checkedPlatforms(cfg.platforms),
+    // The PAT is workspace-scoped; a repo that must only reach one workspace
+    // names its variable here rather than trusting the ambient one.
+    tokenEnv: cfg.tokenEnv ?? null,
+    registry: resolve(cwd, cfg.registry || "social"),
+    root: cwd,
+    lanes: cfg.lanes,
+    checks: cfg.checks || ALL_CHECKS,
+  };
+}
+
+async function api(cfg, method, path, body, extraHeaders = {}) {
+  const url = `${cfg.apiUrl}/api${path}`;
+  const res = await fetch(url, {
+    method,
+    redirect: 'error',
+    signal: AbortSignal.timeout(30000),
+    headers: { Authorization: `Bearer ${token(cfg)}`, "Content-Type": "application/json", ...extraHeaders },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(`${method} ${path} -> ${res.status}${text ? `\n  ${text.slice(0, 400)}` : ""}`);
+  }
+  return res.status === 204 ? null : res.json();
+}
+
+// ─── media measurement ───────────────────────────────────────────────────────
+
+function ffprobe(file, entries, streamSelect = []) {
+  return execFileSync(
+    "ffprobe",
+    ["-v", "error", ...streamSelect, "-show_entries", entries, "-of", "default=nw=1:nk=1", file],
+    { encoding: "utf8" },
+  ).trim();
+}
+
+/**
+ * Loudness, integrated, from ffmpeg's own two-pass measurement.
+ *
+ * Read the SPREAD across a batch, not the value: a set of reels that are each
+ * within a decibel of each other sounds like one library, and a set that
+ * averages -14 with a 4 dB spread is audible between two posts in a row.
+ */
+function loudness(file) {
+  // **loudnorm prints its JSON to stderr, and execFileSync returns stdout.**
+  // Reading the return value gave null and the whole command died on it.
+  const r = spawnSync(
+    "ffmpeg",
+    ["-hide_banner", "-nostats", "-i", file, "-filter:a", "loudnorm=print_format=json", "-f", "null", "-"],
+    { encoding: "utf8" },
+  );
+  const m = `${r.stderr ?? ""}${r.stdout ?? ""}`.match(/"input_i"\s*:\s*"(-?[\d.]+)"/);
+  return m ? Number(m[1]) : null;
+}
+
+function sha256(file) {
+  return createHash("sha256").update(readFileSync(file)).digest("hex");
+}
+
+/** The first frame, which is what a draft shows in a feed before it plays. */
+/**
+ * The still a feed shows before anybody presses play.
+ *
+ * **Frame 0 is the wrong frame for any reel whose opening card assembles**, and
+ * that is a measured rule rather than a preference: a hook that fades in from
+ * nothing gives a feed a cover with no words on it, reproduced on two accounts
+ * (`docs/REEL_FIRST_SECONDS.md` § The skip window). A reel that opens on a
+ * camera move has the same problem in a milder form - the cover is a crop
+ * nobody composed.
+ *
+ * So a lane says when its opening card is finished assembling, and the poster
+ * comes from there. `coverAtMs` defaults to 0, so a lane that does not animate
+ * its opener is unaffected.
+ */
+function coverFrame(file, out, atMs = 0) {
+  mkdirSync(dirname(out), { recursive: true });
+  execFileSync("ffmpeg", [
+    "-loglevel", "error", "-y",
+    ...(atMs > 0 ? ["-ss", (atMs / 1000).toFixed(3)] : []),
+    "-i", file, "-frames:v", "1", out,
+  ]);
+  return out;
+}
+
+// ─── the registry ────────────────────────────────────────────────────────────
+
+// **`posts/` is the directory; `reels/` is read because it was the directory.**
+// A record already committed in a consuming repo is not something to break over
+// a rename, so both are read and a manifest is rewritten where it already
+// lives. Anything new lands in `posts/`.
+const POSTS_DIR = "posts";
+const LEGACY_DIR = "reels";
+const captionPath = (cfg, slug) => join(cfg.registry, "captions", `${slug}.txt`);
+// A sibling .tiktok caption file supplies the TikTok override. Without it,
+// TikTok uses the shared caption. Vocabulary can differ by platform.
+const tiktokCaptionPath = (cfg, slug) => join(cfg.registry, "captions", `${slug}.tiktok.txt`);
+const tiktokSibling = (file) => file.replace(/(\.[^./]+)$/, ".tiktok$1");
+
+function manifestPath(cfg, slug) {
+  const legacy = join(cfg.registry, LEGACY_DIR, `${slug}.json`);
+  if (existsSync(legacy) && !existsSync(join(cfg.registry, POSTS_DIR, `${slug}.json`))) return legacy;
+  return join(cfg.registry, POSTS_DIR, `${slug}.json`);
+}
+
+function readManifest(cfg, slug) {
+  const p = manifestPath(cfg, slug);
+  if (!existsSync(p)) throw new Error(`${slug} is not registered. Run \`sprid post register ${slug}\`.`);
+  return JSON.parse(readFileSync(p, "utf8"));
+}
+
+function writeManifest(cfg, m) {
+  const p = manifestPath(cfg, m.slug);
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, JSON.stringify(m, null, 2) + "\n");
+  return p;
+}
+
+function allManifests(cfg) {
+  const seen = new Map();
+  for (const d of [LEGACY_DIR, POSTS_DIR]) {
+    const dir = join(cfg.registry, d);
+    if (!existsSync(dir)) continue;
+    for (const f of readdirSync(dir).filter((f) => f.endsWith(".json"))) {
+      const m = JSON.parse(readFileSync(join(dir, f), "utf8"));
+      seen.set(m.slug, m); // posts/ is read second, so it wins
+    }
+  }
+  return [...seen.values()].sort((a, b) => a.slug.localeCompare(b.slug));
+}
+
+/** `<slug>` in a lane's path template is the only substitution there is. */
+const fill = (tpl, slug) => tpl.replaceAll("<slug>", slug);
+
+/**
+ * What a lane produces. Inferred rather than required, because a lane that
+ * names `slides:` cannot be anything else and a config should not have to say
+ * the same thing twice.
+ */
+/**
+ * What a lane produces. Three answers, and only one of them owns any pixels.
+ *
+ * **`composed` is the case where Sprid renders and this repo holds the copy.**
+ * A template carousel or a text reel has no local file at all - the slides are
+ * words, the pixels are the server's templates and backdrops, and there is
+ * nothing to measure with ffmpeg. What is worth committing is the copy, the
+ * caption, the gate it passed and where each number came from; the mp4 or the
+ * PNG is downstream of that and disposable. Every other verb is unchanged,
+ * which is the point: one repo can hold a composed lane and a bespoke-render
+ * lane side by side and `status` is still one table.
+ */
+const kindOf = (lane) => lane.kind ?? (lane.slides ? "carousel" : "reel");
+const isComposed = (x) => (x?.kind ?? (x?.slides ? "carousel" : "reel")) === "composed";
+
+/** The path template a lane's media lives at, whichever kind it is. */
+const mediaTemplate = (lane) =>
+  kindOf(lane) === "composed" ? (lane.spec ?? "social/specs/<slug>.json") : kindOf(lane) === "carousel" ? lane.slides : lane.media;
+
+/**
+ * The files of one carousel, in order.
+ *
+ * **Order is the filename, sorted the way a person counts**, so `2.jpg` comes
+ * before `10.jpg`. A deck's slide order is the single most consequential thing
+ * about it and it is not worth hiding in a JSON array somewhere: name the files
+ * and the order is visible in the directory listing.
+ */
+function slideFiles(cfg, lane, slug) {
+  const tpl = resolve(cfg.root, fill(mediaTemplate(lane), slug));
+  const dir = dirname(tpl);
+  if (!existsSync(dir)) return [];
+  const pattern = basename(tpl);
+  const [pre, post] = pattern.includes("*") ? pattern.split("*") : [pattern, ""];
+  return readdirSync(dir)
+    .filter((f) => !f.startsWith(".") && f.startsWith(pre) && f.endsWith(post) && f.length >= pre.length + post.length)
+    .sort((a, b) => a.localeCompare(b, undefined, { numeric: true }))
+    .map((f) => join(dir, f));
+}
+
+/** An image's pixel size, from ffprobe - already a dependency for the video. */
+function imageSize(file) {
+  const [w, h] = ffprobe(file, "stream=width,height", ["-select_streams", "v:0"]).split("\n").map(Number);
+  return { width: w, height: h };
+}
+
+const gcd = (a, b) => (b ? gcd(b, a % b) : a);
+function ratioLabel(w, h) {
+  const g = gcd(w, h) || 1;
+  return `${w / g}:${h / g}`;
+}
+
+/**
+ * Every slug a lane can see.
+ *
+ * Two shapes, because a reel is a file and a carousel is a directory of them:
+ * `out/<slug>.mp4` names the slug inside a filename, `decks/<slug>/*.jpg` names
+ * it as the directory, and which one a lane is, is visible in its template.
+ */
+export function slugsInLane(cfg, laneName) {
+  const lane = cfg.lanes[laneName];
+  const tpl = resolve(cfg.root, mediaTemplate(lane));
+  const [pre, post] = tpl.split("<slug>");
+
+  if (post.startsWith("/")) {
+    const dir = pre.replace(/\/$/, "");
+    if (!existsSync(dir)) return [];
+    return readdirSync(dir)
+      .filter((f) => !f.startsWith(".") && statSync(join(dir, f)).isDirectory())
+      .filter((slug) => slideFiles(cfg, lane, slug).length > 0)
+      .sort();
+  }
+
+  const dir = dirname(tpl);
+  if (!existsSync(dir)) return [];
+  const [fpre, fpost] = basename(tpl).split("<slug>");
+  return readdirSync(dir)
+    .filter((f) => f.startsWith(fpre) && f.endsWith(fpost) && f.length > fpre.length + fpost.length)
+    .map((f) => f.slice(fpre.length, f.length - fpost.length))
+    .sort();
+}
+
+function laneOf(cfg, slug) {
+  for (const name of Object.keys(cfg.lanes)) {
+    const lane = cfg.lanes[name];
+    if (kindOf(lane) === "carousel") {
+      if (slideFiles(cfg, lane, slug).length) return name;
+    } else if (existsSync(resolve(cfg.root, fill(lane.media, slug)))) return name;
+  }
+  return null;
+}
+
+// ─── commands ────────────────────────────────────────────────────────────────
+
+const STARTER_OWN = `// sprid post. \`sprid post status\` to see where everything stands.
+//
+// A LANE is where one kind of finished media lives, and there are two kinds of
+// post: a REEL is one video file, a CAROUSEL is a directory of images. The
+// package ships no lanes, because what a lane is depends on how you make
+// things.
+export default {
+  account: "ACCOUNT_SLUG",
+  registry: "social/",           // manifests + captions, committed to this repo
+  lanes: {
+    films: {
+      media: "path/to/output/<slug>.mp4",
+      caption: "path/to/output/<slug>.caption.txt",
+      // Optional, and worth writing: the command that makes one. It is what
+      // \`build\` runs, and what the record remembers so a re-render is the
+      // same render.
+      build: "your-renderer --slug <slug> --out <out>",
+      // What \`check\` enforces. Ranges are inclusive.
+      expect: { durationMs: [5000, 90000], lufs: [-16, -12] },
+    },
+    decks: {
+      // A carousel: the slug is the directory, the slides are its files, and
+      // they are ordered by filename - so name them 01, 02, 03.
+      slides: "path/to/decks/<slug>/*.jpg",
+      caption: "path/to/decks/<slug>/caption.txt",
+      expect: { slides: [3, 20], aspect: "4:5", minWidth: 1080 },
+    },
+  },
+  // Drop any you do not want. \`batchSpread\` is measured across a lane rather
+  // than per file, which is the only way it means anything; \`aspect\` refuses a
+  // deck whose slides are not all the same shape, because Instagram crops every
+  // later slide to the first one's.
+  checks: ["duration", "loudness", "batchSpread", "caption", "slides", "aspect", "provenance"],
+};
+`;
+
+const STARTER_STILLS = `// sprid post, on the built-in recipe.
+//
+// One spec per reel in social/specs/, pictures and a track, and one command:
+//   sprid post new my-first-reel   ->  edit the spec  ->  sprid post build
+export default {
+  account: "ACCOUNT_SLUG",
+  registry: "social/",
+  lanes: {
+    reels: {
+      build: { recipe: "stills", track: "assets/audio/bed.mp3" },
+      spec: "social/specs/<slug>.json",
+      media: "tmp/reels/<slug>.mp4",
+      caption: "tmp/reels/<slug>.caption.txt",
+      // Example limits. Set these for your format and audio delivery requirements.
+      expect: { durationMs: [8_000, 20_000], lufs: [-16, -12] },
+    },
+  },
+  checks: ["duration", "loudness", "batchSpread", "caption"],
+};
+`;
+
+const STARTER_COMPOSED = `// sprid post, composed: Sprid renders the pixels, this repo holds the copy.
+//
+// One spec per post in social/specs/, then:
+//   sprid post new my-first-post  ->  edit the spec  ->  register -> check -> draft
+export default {
+  account: "ACCOUNT_SLUG",
+  // A PAT is workspace-scoped and this machine may hold several. Name the one
+  // this repo is allowed to use and nothing else is tried.
+  tokenEnv: "SPRID_TOKEN",
+  registry: "social/",
+  lanes: {
+    carousels: {
+      kind: "composed",
+      spec: "social/specs/<slug>.json",
+      // Optional: the Sprid format a post is created from, and the template
+      // every card renders through.
+      // format: <format id from this account>,
+      // template: <template id from this account>,
+      expect: { slides: [5, 9], words: [0, 30] },
+      hashtags: [3, 6],
+      // The phrases this account has decided it does not say. The mechanical
+      // half of a voice; everything else still needs a reader.
+      neverSay: [],
+      // Every card stating a number names the file it came from, and the check
+      // opens it. Turn this on for anything where a wrong figure is the one
+      // unforgivable error.
+      sourcesRequired: false,
+    },
+  },
+  checks: ["slides", "words", "voice", "sources", "caption"],
+};
+`;
+
+async function cmdInit(argv) {
+  const kind = flag(argv, "kind");
+  if (!kind) {
+    console.log(`
+  ${C.bold("What are your posts made of?")}
+
+    ${C.bold("--kind text")}      words on a background, a template, a hook and a payoff
+                    ${C.dim("-> render in the app repo, then let Sprid check and upload")}
+                    ${C.dim("   the finished mp4. Cloud reel rendering is paused.")}
+
+    ${C.bold("--kind stills")}    photographs, screenshots, generated images
+                    ${C.dim("-> the built-in recipe. A spec per reel, one command,")}
+                    ${C.dim("   and it prints the ffmpeg it ran so you can take it over.")}
+
+    ${C.bold("--kind own")}       you already render your own mp4s
+                    ${C.dim("-> sprid post registers, checks and pushes them.")}
+                    ${C.dim("   Point a lane's build: at your existing command.")}
+
+  ${C.dim("Pick one and run it again, e.g.")} sprid post init --kind stills
+`);
+    return;
+  }
+  if (kind === "text") {
+    const p = join(process.cwd(), "sprid.config.ts");
+    if (existsSync(p) && !has(argv, "force")) throw new Error(`${p} already exists. Pass --force to overwrite.`);
+    writeFileSync(p, STARTER_OWN);
+    console.log(`\n  wrote ${C.bold("sprid.config.ts")}`);
+    console.log(`  ${C.dim("point the lane's build command at the app's text renderer, then:")} sprid post build\n`);
+    return;
+  }
+  if (kind === "composed") {
+    throw new Error("Cloud reel composition is paused. Use --kind text with the app's local renderer.");
+  }
+  const p = join(process.cwd(), "sprid.config.ts");
+  if (existsSync(p) && !has(argv, "force")) throw new Error(`${p} already exists. Pass --force to overwrite.`);
+  writeFileSync(p, kind === "stills" ? STARTER_STILLS : STARTER_OWN);
+  console.log(`\n  wrote ${C.bold("sprid.config.ts")}`);
+  console.log(
+    kind === "stills"
+      ? `  ${C.dim("set the account slug, then:")} sprid post new my-first-reel\n`
+      : `  ${C.dim("set the account slug and point build: at your renderer, then:")} sprid post build\n`,
+  );
+}
+
+/**
+ * The step that was missing from the front of this pipeline.
+ *
+ * **`register` used to assume a finished file had appeared by magic**, which is
+ * fine for a repo that already has a renderer and is the entire problem for one
+ * that does not. A lane now says how its media is MADE, and there are exactly
+ * two answers:
+ *
+ *   build: "bun run scripts/make-reel.ts --spec <spec> --out <out>"
+ *   build: { recipe: "stills", track: "assets/bed.mp3" }
+ *
+ * The first runs your own renderer and this package stays out of it. The second
+ * runs the one built-in, so a repo with pictures and no pipeline is producing
+ * something on day one. Both land in the same `media` path and everything
+ * downstream - register, check, push, draft - cannot tell them apart, which is
+ * the point: a customer can start on the recipe and grow into their own
+ * renderer without changing anything else.
+ */
+async function cmdBuild(cfg, argv) {
+  const only = positional(argv);
+  const onlyLane = flag(argv, "lane");
+  const targets = [];
+  for (const laneName of Object.keys(cfg.lanes)) {
+    if (onlyLane && laneName !== onlyLane) continue;
+    const lane = cfg.lanes[laneName];
+    if (!lane.build) continue;
+    // **A named slug belongs to ONE lane.** Without this a repo with two build
+    // lanes - a screen recipe and a stills one - runs the named slug through
+    // both, and the second fails on a spec it was never given.
+    const slugs = only
+      ? (typeof lane.build === "string" || existsSync(specPath(cfg, laneName, only)) ? [only] : [])
+      : specSlugs(cfg, laneName);
+    for (const slug of slugs) targets.push([laneName, slug]);
+  }
+  if (only && targets.length > 1 && !onlyLane)
+    throw new Error(
+      `"${only}" has a spec in ${targets.length} lanes (${targets.map((t) => t[0]).join(", ")}). ` +
+        "Say which: `build " + only + " --lane " + targets[0][0] + "`, or give the lanes separate spec directories.",
+    );
+  if (!targets.length)
+    throw new Error(
+      Object.values(cfg.lanes).every((l) => isComposed(l))
+        ? "Nothing to build, and nothing to build it with: every lane here is `composed`, which means Sprid renders it.\n" +
+            "  Write the copy in a spec, then `register` -> `check` -> `draft`."
+        : "Nothing to build. A lane needs a `build:` - either a command of your own, or { recipe: \"stills\" }.\n" +
+            "  With a recipe, each reel is a spec file; `sprid post new <slug>` writes one.",
+    );
+
+  for (const [laneName, slug] of targets) {
+    const lane = cfg.lanes[laneName];
+    const out = resolve(cfg.root, fill(lane.media, slug));
+    mkdirSync(dirname(out), { recursive: true });
+
+    if (typeof lane.build === "string") {
+      const cmd = lane.build.replaceAll("<slug>", slug).replaceAll("<out>", out).replaceAll("<spec>", specPath(cfg, laneName, slug));
+      console.log(`  ${C.dim(cmd)}`);
+      const r = spawnSync(cmd, { shell: true, stdio: "inherit", cwd: cfg.root });
+      if (r.status !== 0) throw new Error(`build failed for ${slug}`);
+    } else if (lane.build.recipe === "screen") {
+      // The screen recipe drives a simulator, so it is async and it needs the
+      // repo root, a scratch directory and the spec's own script file. It
+      // writes the caption exactly like the stills recipe does below.
+      const { buildScreen } = await import("./recipes/screen.mjs");
+      const spec = readSpec(cfg, laneName, slug);
+      const scriptPath = resolve(cfg.root, spec.script ?? `${basename(cfg.registry)}/scripts/${slug}.json`);
+      if (!existsSync(scriptPath))
+        throw new Error(`${slug}: no gesture script at ${scriptPath}. A screen spec names one with \`script\`; ` +
+          `one script serves every locale.`);
+      const r = await buildScreen({
+        spec: { ...lane.build, ...spec },
+        script: JSON.parse(readFileSync(scriptPath, "utf8")),
+        root: cfg.root,
+        out,
+        // **Scratch goes OUTSIDE the repo unless a lane says otherwise.** The
+        // recording writes a settle screenshot twice a second into this
+        // directory; with it inside the project, Metro's file watcher sees
+        // every one of them, sends the app a Fast Refresh, and RN drops its
+        // blue "Refreshing…" banner over the top of the frame. It landed on
+        // three of eight sampled frames of the first reel built here.
+        recut: has(argv, "recut"),
+        tmp: lane.build.tmp
+          ? resolve(cfg.root, lane.build.tmp, slug)
+          : join(tmpdir(), "sprid", basename(cfg.root), slug),
+      });
+      for (const a of r.advice) console.log(`  ${C.warn("note")}  ${a}`);
+      // The graph is 8KB of overlay expressions; printing it drowns the log it
+      // is supposed to accompany. It still gets written down - a recipe that
+      // hides the command it ran is a framework.
+      console.log(`  ${C.dim(`ffmpeg command: ${r.commandPath}`)}`);
+      if (spec.caption && lane.caption) {
+        const cp = resolve(cfg.root, fill(lane.caption, slug));
+        mkdirSync(dirname(cp), { recursive: true });
+        writeFileSync(cp, spec.caption.trim() + "\n");
+      }
+    } else {
+      const { buildStills } = await import("./recipes/stills.mjs");
+      const spec = readSpec(cfg, laneName, slug);
+      const r = buildStills({
+        images: (spec.images ?? []).map((i) => resolve(cfg.root, i)),
+        track: spec.track ? resolve(cfg.root, spec.track) : lane.build.track ? resolve(cfg.root, lane.build.track) : undefined,
+        out,
+        ...(lane.build.holdMs ? { holdMs: lane.build.holdMs } : {}),
+        ...(spec.holdMs ? { holdMs: spec.holdMs } : {}),
+      });
+      for (const a of r.advice) console.log(`  ${C.warn("note")}  ${a}`);
+      console.log(`  ${C.dim(r.command)}`);
+      // A spec's caption is written out where `register` will find it, so a
+      // recipe lane needs no separate caption step.
+      if (spec.caption && lane.caption) {
+        const cp = resolve(cfg.root, fill(lane.caption, slug));
+        mkdirSync(dirname(cp), { recursive: true });
+        writeFileSync(cp, spec.caption.trim() + "\n");
+      }
+    }
+    // The record is now wrong about the bytes and right about nothing until
+    // `register` runs, but the command is knowable here and nowhere else.
+    if (existsSync(manifestPath(cfg, slug))) {
+      const m = readManifest(cfg, slug);
+      m.build = buildRecord(cfg, laneName, slug, undefined, {});
+      writeManifest(cfg, m);
+    }
+    console.log(`  ${C.ok("built")}   ${slug.padEnd(40)} ${out.replace(cfg.root + "/", "")}\n`);
+  }
+}
+
+const specPath = (cfg, laneName, slug) =>
+  resolve(cfg.root, fill(cfg.lanes[laneName].spec ?? `${basename(cfg.registry)}/specs/<slug>.json`, slug));
+
+function readSpec(cfg, laneName, slug) {
+  const p = specPath(cfg, laneName, slug);
+  if (!existsSync(p)) throw new Error(`No spec at ${p}. Write one, or \`sprid post new ${slug}\`.`);
+  const spec = JSON.parse(readFileSync(p, "utf8"));
+  // **Hashtags are part of the caption.** Sprid publishes one string per
+  // platform and has no tag field to send them to, so a spec carrying them
+  // separately is named rather than quietly dropped - a silently ignored key
+  // is how a post ships without its tags and nobody finds out until it is up.
+  if (spec.hashtags !== undefined)
+    throw new Error(`${p}: \`hashtags\` is not a field. Put the tags at the end of \`caption\`.`);
+  return spec;
+}
+
+/** Every slug a recipe lane can build, from its spec directory. */
+function specSlugs(cfg, laneName) {
+  const tpl = specPath(cfg, laneName, " ");
+  const dir = dirname(tpl);
+  if (!existsSync(dir)) return [];
+  const [pre, post] = basename(tpl).split(" ");
+  return readdirSync(dir)
+    .filter((f) => f.startsWith(pre) && f.endsWith(post) && f.length > pre.length + post.length)
+    .map((f) => f.slice(pre.length, f.length - post.length))
+    .sort();
+}
+
+/**
+ * A spec is the durable artifact and the file a person edits.
+ *
+ * Carried over from the pipeline this package was drawn from, where it is the
+ * single best structural decision in the whole thing: the mp4 is disposable and
+ * regenerates, the spec is what is reviewed, committed and argued about.
+ */
+async function cmdNew(cfg, argv) {
+  const slug = positional(argv);
+  if (!slug) throw new Error("Give it a slug: `sprid post new my-first-reel`.");
+  // Whichever lane keeps specs: a composed one, or a recipe one. Those are the
+  // two kinds of lane a spec means anything to.
+  const laneName =
+    flag(argv, "lane") ??
+    Object.keys(cfg.lanes).find((l) => isComposed(cfg.lanes[l]) || typeof cfg.lanes[l].build === "object") ??
+    Object.keys(cfg.lanes)[0];
+  const p = specPath(cfg, laneName, slug);
+  if (existsSync(p) && !has(argv, "force")) throw new Error(`${p} already exists.`);
+  mkdirSync(dirname(p), { recursive: true });
+  // The spec's shape is the lane's kind: a composed post is its copy, a recipe
+  // reel is its pictures. Scaffolding the wrong one is a file somebody has to
+  // delete before they can start.
+  const starter = isComposed(cfg.lanes[laneName])
+    ? {
+        slug,
+        slides: [
+          { role: "hook", text: "The line that makes someone stop." },
+          { role: "body", text: "One thought.", source: "docs/where-this-came-from.md" },
+          { role: "cta", text: "The line they screenshot." },
+        ],
+        caption: "What this post says. Written here, committed, reviewed in a diff.\n\n#one #two #three",
+      }
+    : {
+        slug,
+        images: ["path/to/first.jpg", "path/to/second.jpg", "path/to/third.jpg"],
+        track: cfg.lanes[laneName].build?.track ?? "path/to/bed.mp3",
+        holdMs: 3000,
+        caption: "What this post says. Written here, committed, reviewed in a diff.",
+      };
+  writeFileSync(p, JSON.stringify(starter, null, 2) + "\n");
+  console.log(`\n  wrote ${C.bold(p.replace(cfg.root + "/", ""))}`);
+  console.log(`  ${C.dim("point `images` at real files, then:")} sprid post build ${slug}\n`);
+}
+
+/** Everything that is true of one finished mp4. */
+function measureReel(cfg, lane, slug) {
+  const media = resolve(cfg.root, fill(cfg.lanes[lane].media, slug));
+  const durationMs = Math.round(Number(ffprobe(media, "format=duration")) * 1000);
+  const { width, height } = imageSize(media);
+  const sizeBytes = statSync(media).size;
+  const lufs = loudness(media);
+  const digest = sha256(media);
+  return {
+    digest,
+    record: { media: { sha256: digest, durationMs, width, height, sizeBytes, lufs } },
+    summary:
+      `${(durationMs / 1000).toFixed(1)}s  ${(sizeBytes / 1e6).toFixed(1)} MB  ` +
+      `${lufs === null ? C.dim("no audio") : `${lufs.toFixed(1)} LUFS`}`,
+  };
+}
+
+/**
+ * Everything that is true of one carousel.
+ *
+ * **The digest is over the slides AND their order**, since two decks holding
+ * the same pictures in a different order are two different posts, and the order
+ * is the half a reviewer argues about.
+ */
+function measureCarousel(cfg, lane, slug) {
+  const files = slideFiles(cfg, cfg.lanes[lane], slug);
+  if (!files.length) throw new Error(`No slides for ${slug} at ${fill(mediaTemplate(cfg.lanes[lane]), slug)}`);
+  const slides = files.map((f) => {
+    const { width, height } = imageSize(f);
+    return {
+      file: f.replace(cfg.root + "/", ""),
+      sha256: sha256(f),
+      width,
+      height,
+      sizeBytes: statSync(f).size,
+      aspect: ratioLabel(width, height),
+    };
+  });
+  const digest = createHash("sha256").update(slides.map((s) => s.sha256).join("\n")).digest("hex");
+  const bytes = slides.reduce((n, s) => n + s.sizeBytes, 0);
+  const ratios = [...new Set(slides.map((s) => s.aspect))];
+  return {
+    digest,
+    record: { media: { sha256: digest, slideCount: slides.length, sizeBytes: bytes, aspect: ratios[0] }, slides },
+    summary:
+      `${slides.length} slides  ${(bytes / 1e6).toFixed(1)} MB  ` +
+      (ratios.length === 1 ? ratios[0] : C.warn(`mixed ratios: ${ratios.join(", ")}`)),
+  };
+}
+
+/**
+ * Everything that is true of one composed post.
+ *
+ * **The spec IS the artifact here**, not a recipe for one, so the digest is
+ * over the spec and the words are measured off it. Word counts are kept per
+ * slide rather than totalled: a deck whose average is fine and whose third card
+ * runs to sixty words is exactly the deck the total hides.
+ */
+function measureComposed(cfg, lane, slug) {
+  const spec = readSpec(cfg, lane, slug);
+  const slides = spec.slides ?? [];
+  if (!slides.length) throw new Error(`${slug}: the spec has no \`slides\`. A composed post is its copy.`);
+  const words = slides.map((sl) => wordsOf(sl));
+  const body = JSON.stringify(slides);
+  return {
+    digest: createHash("sha256").update(body).digest("hex"),
+    record: {
+      media: {
+        sha256: createHash("sha256").update(body).digest("hex"),
+        slideCount: slides.length,
+        sizeBytes: Buffer.byteLength(body),
+        words,
+      },
+      copy: slides,
+    },
+    summary: `${slides.length} cards  ${Math.max(...words)} words at the longest`,
+  };
+}
+
+/** Every word a card shows, headline and body and bullets alike. */
+const wordsOf = (sl) =>
+  [sl.text, sl.subtitle, ...(sl.bullets ?? [])]
+    .filter(Boolean)
+    .join(" ")
+    .split(/\s+/)
+    .filter(Boolean).length;
+
+const digestOf = (m) => m?.media?.sha256 ?? null;
+
+/**
+ * How this file was made.
+ *
+ * **A record that measures the bytes and forgets the command is half a record.**
+ * On 2026-09-03 a reel registered at 17.2s came back from a re-render at 13.8s
+ * without `--map` and 20.6s with it, and nothing in the registry could say
+ * which invocation the 17.2s belonged to - the render line was living in a
+ * deck's notes. The command is the difference between a spec that reproduces a
+ * post and a spec that reproduces something like it.
+ *
+ * Three sources, in the order you would trust them: what the operator says they
+ * just ran, what the lane says it runs, and what the record already held.
+ */
+function buildRecord(cfg, lane, slug, builtWith, prev) {
+  if (builtWith) return { command: builtWith, source: "operator", at: new Date().toISOString() };
+  const b = cfg.lanes[lane]?.build;
+  if (typeof b === "string")
+    return { command: fill(b, slug).replaceAll("<out>", fill(mediaTemplate(cfg.lanes[lane]), slug)), source: "lane", at: new Date().toISOString() };
+  if (b && typeof b === "object")
+    return { command: `sprid post build ${slug}`, source: "recipe", at: new Date().toISOString() };
+  return prev?.build ?? null;
+}
+
+async function cmdRegister(cfg, argv) {
+  const only = positional(argv);
+  const targets = [];
+  if (only) {
+    const lane = flag(argv, "lane") ?? laneOf(cfg, only);
+    if (!lane) throw new Error(`No lane in sprid.config has media for "${only}".`);
+    targets.push([lane, only]);
+  } else {
+    for (const lane of Object.keys(cfg.lanes)) for (const slug of slugsInLane(cfg, lane)) targets.push([lane, slug]);
+  }
+  if (!targets.length) throw new Error("Nothing to register. Check the `media` paths in your lanes.");
+
+  for (const [lane, slug] of targets) {
+    const kind = kindOf(cfg.lanes[lane]);
+    const measured =
+      kind === "composed"
+        ? measureComposed(cfg, lane, slug)
+        : kind === "carousel"
+          ? measureCarousel(cfg, lane, slug)
+          : measureReel(cfg, lane, slug);
+
+    // The caption is copied INTO the registry rather than pointed at. It is the
+    // most reviewable thing the pipeline produces and it usually lives in a
+    // scratch directory, where nobody can read it in a diff.
+    // A composed post keeps its caption in the spec, next to the copy it
+    // belongs to; a rendered one keeps it wherever the renderer dropped it.
+    // Either way it is COPIED into the registry rather than pointed at - it is
+    // the most reviewable thing any of these pipelines produce and it usually
+    // lives in a scratch directory nobody reads a diff of.
+    const capSrc = cfg.lanes[lane].caption ? resolve(cfg.root, fill(cfg.lanes[lane].caption, slug)) : null;
+    let caption = null;
+    if (kind === "composed") {
+      const spec = readSpec(cfg, lane, slug);
+      caption = spec.caption ? String(spec.caption).trim() : null;
+    } else if (capSrc && existsSync(capSrc)) {
+      caption = readFileSync(capSrc, "utf8").trim();
+    }
+    if (caption) {
+      mkdirSync(dirname(captionPath(cfg, slug)), { recursive: true });
+      writeFileSync(captionPath(cfg, slug), caption + "\n");
+    }
+    const ttSrc = capSrc ? tiktokSibling(capSrc) : null;
+    const captionTiktok = ttSrc && existsSync(ttSrc) ? readFileSync(ttSrc, "utf8").trim() : null;
+    if (captionTiktok) writeFileSync(tiktokCaptionPath(cfg, slug), captionTiktok + "\n");
+    else if (existsSync(tiktokCaptionPath(cfg, slug))) rmSync(tiktokCaptionPath(cfg, slug));
+
+    const prev = existsSync(manifestPath(cfg, slug)) ? readManifest(cfg, slug) : {};
+    const authored = existsSync(specPath(cfg, lane, slug)) ? readSpec(cfg, lane, slug) : {};
+    if (authored.remotePostId !== undefined && (!Number.isInteger(authored.remotePostId) || authored.remotePostId <= 0))
+      throw new Error(`${slug}: remotePostId must be a positive integer`);
+    const m = {
+      slug,
+      lane,
+      kind,
+      build: buildRecord(cfg, lane, slug, flag(argv, "built-with"), prev),
+      source: fill(mediaTemplate(cfg.lanes[lane]), slug),
+      ...measured.record,
+      post: {
+        platforms: checkedPlatforms(flag(argv, "platforms")?.split(",") ??
+          authored.platforms ??
+          prev.post?.platforms),
+        title: authored.title ?? prev.post?.title,
+        captionFile: caption ? `${basename(cfg.registry)}/captions/${slug}.txt` : null,
+        captionSha: caption ? createHash("sha256").update(caption + (captionTiktok ?? "")).digest("hex").slice(0, 12) : null,
+        captionTiktokFile: captionTiktok ? `${basename(cfg.registry)}/captions/${slug}.tiktok.txt` : null,
+        instagramLocationId: prev.post?.instagramLocationId ?? null,
+      },
+      // A record is only true of the bytes it measured, so a changed digest
+      // drops the check result with it.
+      checks: measured.digest === digestOf(prev) ? (prev.checks ?? null) : null,
+      sprid: {
+        account: cfg.account,
+        videoId: null,
+        imageIds: null,
+        postId: authored.remotePostId ?? null,
+        status: "none",
+        captionShaAtDraft: null,
+        ...(prev.sprid ?? {}),
+        ...(authored.remotePostId !== undefined ? { postId: authored.remotePostId } : {}),
+      },
+      registeredAt: new Date().toISOString(),
+    };
+    writeManifest(cfg, m);
+    console.log(`  ${C.ok("registered")} ${slug.padEnd(40)} ${measured.summary}`);
+  }
+  console.log(`\n  ${targets.length} registered in ${C.bold(cfg.registry)}\n`);
+}
+
+/**
+ * The gate.
+ *
+ * Every check is a refusal to publish something a person would have caught by
+ * watching the file, and the reason each one exists is written next to it. A
+ * check that cannot run reports that it could not, never a pass.
+ */
+/** Validate the platform projections before a local post is uploaded. */
+export function checkedPlatforms(platforms) {
+  if (platforms === undefined) return undefined;
+  const supported = ["instagram", "tiktok", "youtube", "facebook", "linkedin", "pinterest", "x"];
+  if (!Array.isArray(platforms) || !platforms.length || platforms.some(p => !supported.includes(p)))
+    throw new Error(`platforms must be a non-empty array from: ${supported.join(", ")}`);
+  return [...new Set(platforms)];
+}
+
+export function crosspostCheck(m, caption, slug, platforms) {
+  const title = m.post?.title ?? postTitle(caption, slug);
+  const selected = checkedPlatforms(platforms ?? m.post?.platforms);
+  const modeled = selected?.filter(p => ["instagram", "tiktok", "youtube", "pinterest"].includes(p));
+  const unmodeled = selected?.filter(p => !["instagram", "tiktok", "youtube", "pinterest"].includes(p)) ?? [];
+  const problems = projectPost({ title, captionInstagram: caption,
+    pinterestOptions: m.post?.pinterestOptions,
+    platforms: modeled })
+    .flatMap((p) => p.problems.map((x) => `${p.platform}: ${x}`));
+  return problems.length ? `fail: ${problems.join("; ")}`
+    : unmodeled.length ? `skip: local projection rules unavailable for ${unmodeled.join(", ")}; use --deep for booked posts` : "pass";
+}
+
+
+export function runChecks(cfg, m, batch) {
+  const lane = cfg.lanes[m.lane] ?? {};
+  const want = lane.expect ?? {};
+  const out = {};
+  const enabled = new Set(cfg.checks);
+  const kind = m.kind ?? kindOf(lane);
+  const carousel = kind === "carousel";
+  const composed = kind === "composed";
+
+  // **A check that does not apply says so; it never passes.** Duration and
+  // loudness are properties of a video, and a carousel that reported four
+  // green checks it never ran would be worth less than no check at all. A
+  // composed post has no pixels here at all, so it skips the aspect check too.
+  if (carousel || composed) {
+    for (const name of ["duration", "loudness", "batchSpread"]) {
+      if (enabled.has(name)) out[name] = `skip: not applicable to a ${kind === "composed" ? "composed post" : "carousel"}`;
+    }
+  }
+  if (composed && enabled.has("aspect")) out.aspect = "skip: Sprid renders this one, so the shape is the template's";
+
+  // How many slides. Instagram takes 20, TikTok 35, and a deck of two is a
+  // post that did not get made.
+  if ((carousel || composed) && enabled.has("slides")) {
+    const n = m.media?.slideCount ?? m.slides?.length ?? 0;
+    const [lo, hi] = want.slides ?? [2, 20];
+    out.slides = n >= lo && n <= hi ? "pass" : `fail: ${n} slides, wanted ${lo}-${hi}`;
+  }
+
+  // **One ratio for the whole deck.** Instagram crops every later slide to the
+  // first one's shape, so a deck that mixes 4:5 and 1:1 publishes with the
+  // sides cut off things nobody checked - and it looks fine in every local
+  // preview that shows the files as they are.
+  if (carousel && enabled.has("aspect")) {
+    const ratios = [...new Set((m.slides ?? []).map((s) => s.aspect))];
+    const small = (m.slides ?? []).filter((s) => s.width < (want.minWidth ?? 1080));
+    const problems = [];
+    if (ratios.length > 1) problems.push(`mixed ratios: ${ratios.join(", ")}`);
+    else if (want.aspect && ratios[0] !== want.aspect) problems.push(`${ratios[0]}, wanted ${want.aspect}`);
+    if (small.length) problems.push(`${small.length} slide(s) under ${want.minWidth ?? 1080}px wide`);
+    out.aspect = problems.length ? `fail: ${problems.join("; ")}` : "pass";
+  }
+
+  if (!carousel && enabled.has("duration") && want.durationMs) {
+    const [lo, hi] = want.durationMs;
+    out.duration =
+      m.media.durationMs >= lo && m.media.durationMs <= hi
+        ? "pass"
+        : `fail: ${(m.media.durationMs / 1000).toFixed(1)}s outside ${(lo / 1000).toFixed(1)}-${(hi / 1000).toFixed(1)}s`;
+  }
+
+  if (!carousel && enabled.has("loudness")) {
+    if (m.media.lufs === null) out.loudness = "skip: no audio stream";
+    else if (want.lufs) {
+      const [lo, hi] = want.lufs;
+      out.loudness = m.media.lufs >= lo && m.media.lufs <= hi ? "pass" : `fail: ${m.media.lufs.toFixed(1)} LUFS outside ${lo}..${hi}`;
+    } else out.loudness = "skip: no lufs range in the lane";
+  }
+
+  // Compare loudness within a lane and fail only the outliers.
+  if (!carousel && enabled.has("batchSpread")) {
+    const peers = batch.filter((x) => x.lane === m.lane && typeof x.media?.lufs === "number");
+    const vals = peers.map((x) => x.media.lufs);
+    if (vals.length < 3) out.batchSpread = "skip: fewer than three measured files in this lane";
+    else {
+      const sorted = [...vals].sort((a, b) => a - b);
+      const median = sorted[Math.floor(sorted.length / 2)];
+      const tol = lane.maxDeviationDb ?? 1.2;
+      const off = Math.abs(m.media.lufs - median);
+      out.batchSpread =
+        off <= tol
+          ? "pass"
+          : `fail: ${m.media.lufs.toFixed(1)} LUFS is ${off.toFixed(1)} dB off the ${m.lane} median (${median.toFixed(1)}), ` +
+            `lane spread ${(Math.max(...vals) - Math.min(...vals)).toFixed(1)} dB`;
+    }
+  }
+
+  // Not a pass/fail on the media, a statement about the record: can this file
+  // be made again, exactly? A batch where most rows skip this is a batch whose
+  // provenance lives in somebody's terminal history.
+  if (enabled.has("provenance")) {
+    out.provenance = m.build?.command
+      ? "pass"
+      : "skip: no build command recorded - pass --built-with \"<command>\" to register, or give the lane a build:";
+  }
+
+  // **The word budget is per CARD, never the total.** A deck averaging twenty
+  // words with one card at sixty is exactly the deck an average hides, and the
+  // long card is the one a reader stops on.
+  if (composed && enabled.has("words") && want.words) {
+    const [lo, hi] = want.words;
+    const over = (m.media?.words ?? []).map((n, i) => [i + 1, n]).filter(([, n]) => n < lo || n > hi);
+    out.words = over.length
+      ? `fail: card ${over.map(([i, n]) => `${i} (${n} words)`).join(", ")} outside ${lo}-${hi}`
+      : "pass";
+  }
+
+  // Account-specific phrase restrictions belong in the lane configuration.
+  if (composed && enabled.has("voice")) {
+    const banned = lane.neverSay ?? [];
+    if (!banned.length) out.voice = "skip: no `neverSay` list in the lane";
+    else {
+      const text = (m.copy ?? []).map((sl) => [sl.text, sl.subtitle, ...(sl.bullets ?? [])].filter(Boolean).join(" ")).join("\n");
+      const hits = banned.filter((phrase) => text.toLowerCase().includes(String(phrase).toLowerCase()));
+      const problems = hits.map((h) => `"${h}"`);
+      out.voice = problems.length ? `fail: ${problems.join(", ")}` : "pass";
+    }
+  }
+
+  // **Where the number came from, as a file that exists.** For a YMYL account
+  // this is the whole gate: a slide claiming a cost, a threshold or a rule
+  // names the fact-checked file it came from, and the check opens it. A source
+  // that has been renamed or deleted is the failure worth catching, because the
+  // slide keeps reading true long after the file behind it stopped being.
+  if (composed && enabled.has("sources") && lane.sourcesRequired) {
+    const missing = [];
+    const unsourced = [];
+    (m.copy ?? []).forEach((sl, i) => {
+      const src = sl.source ? [sl.source] : (sl.sources ?? []);
+      const numeric = /\d/.test([sl.text, sl.subtitle, ...(sl.bullets ?? [])].filter(Boolean).join(" "));
+      if (!src.length) {
+        if (numeric) unsourced.push(i + 1);
+        return;
+      }
+      for (const one of src) if (!existsSync(resolve(cfg.root, String(one).split("#")[0]))) missing.push(`${i + 1}: ${one}`);
+    });
+    const problems = [
+      ...(missing.length ? [`source file gone - ${missing.join(", ")}`] : []),
+      ...(unsourced.length ? [`card ${unsourced.join(", ")} states a number with no source`] : []),
+    ];
+    out.sources = problems.length ? `fail: ${problems.join("; ")}` : "pass";
+  }
+
+  if (enabled.has("crosspost")) {
+    const cp = captionPath(cfg, m.slug);
+    // The local half. `check` runs offline and before anything is pushed, so it
+    // asserts what the registry can see. The authoritative half lives in Sprid
+    // and is asked for by `check --deep`, which projects the actual post - see
+    // `deepCrosspost`.
+    out.crosspost = existsSync(cp)
+      ? crosspostCheck(m, readFileSync(cp, "utf8"), m.slug, cfg.checkPlatforms ?? m.post?.platforms ?? lane.platforms ?? cfg.platforms)
+      : "fail: no caption in the registry";
+  }
+
+  if (enabled.has("caption")) {
+    const p = captionPath(cfg, m.slug);
+    if (!existsSync(p)) out.caption = "fail: no caption in the registry";
+    else {
+      const text = readFileSync(p, "utf8");
+      const problems = [];
+      for (const phrase of lane.neverSay ?? []) {
+        if (text.toLowerCase().includes(String(phrase).toLowerCase())) problems.push(`forbidden "${phrase}"`);
+      }
+      // Attribution and hashtag lines do not participate in sentence checks.
+      const prose = text
+        .split("\n")
+        .filter((l) => !/^\s*#/.test(l) && !/^(Photos via|Map ©|Photo:)/.test(l.trim()))
+        .join("\n")
+        .trim();
+      // Language-dependent endings are configured per lane.
+      const tail = prose.split(/\s+/).pop()?.toLowerCase().replace(/[^\p{L}]/gu, "") ?? "";
+      const endWords = new Set((lane.captionEndWords ?? []).map((word) => String(word).toLowerCase()));
+      if (/,$/.test(prose)) problems.push("prose ends on a comma");
+      else if (endWords.has(tail)) problems.push(`prose ends on "${tail}"`);
+      else if (lane.captionEndsSentence && !/[.!?。！？:]$/.test(prose)) problems.push("prose does not end a sentence");
+      for (const rule of lane.captionMustContain ?? []) if (!text.includes(rule)) problems.push(`missing "${rule}"`);
+      if (lane.hashtags) {
+        // `\w` stops at the first non-ASCII letter, so a Swedish lane counted
+        // "#tvätt" as "#tv" and passed a caption that was short of its range.
+        const n = (text.match(/#[\p{L}\p{M}\p{N}_]+/gu) ?? []).length;
+        const [lo, hi] = lane.hashtags;
+        if (n < lo || n > hi) problems.push(`${n} hashtags, wanted ${lo}-${hi}`);
+      }
+      out.caption = problems.length ? `fail: ${problems.join(", ")}` : "pass";
+    }
+  }
+
+  out.at = new Date().toISOString();
+  return out;
+}
+
+/**
+ * What Sprid says each platform will publish, for posts that exist there.
+ *
+ * **The local `crosspost` check asserts preconditions; this one reads the
+ * answer.** A copy of the platform rules living in this package would drift
+ * from the adapters that actually publish and end up agreeing with the bug, so
+ * the rules stay server-side (`projectPost`, beside the adapters) and this asks
+ * for the projection. It is `--deep` rather than the default because `check`
+ * has to work offline and before a post exists.
+ *
+ */
+async function deepCrosspost(cfg, manifests) {
+  const rows = [];
+  for (const m of manifests) {
+    if (!m.sprid?.postId) continue;
+    const p = await api(cfg, "GET", `/posts/${m.sprid.postId}/projection`);
+    if (!p) continue;
+    for (const problem of p.problems ?? []) rows.push({ slug: m.slug, ...problem });
+  }
+  return rows;
+}
+
+async function cmdCheck(cfg, argv) {
+  const only = positional(argv);
+  cfg.checkPlatforms = checkedPlatforms(flag(argv, "platforms")?.split(","));
+  const batch = allManifests(cfg);
+  const hasCarousel = Object.values(cfg.lanes).some((l) => kindOf(l) === "carousel");
+  const missingGates = ["slides", "aspect"].filter((n) => !cfg.checks.includes(n));
+  if (hasCarousel && missingGates.length)
+    console.log(`  ${C.warn("note")}  carousel lane with no ${missingGates.join("/")} check - add them to \`checks\` in sprid.config\n`);
+  const targets = only ? [readManifest(cfg, only)] : batch;
+  let failed = 0;
+  for (const m of targets) {
+    m.checks = runChecks(cfg, m, batch);
+    writeManifest(cfg, m);
+    const bad = Object.entries(m.checks).filter(([k, v]) => k !== "at" && String(v).startsWith("fail"));
+    const skipped = Object.entries(m.checks).filter(([k, v]) => k !== "at" && String(v).startsWith("skip"));
+    if (bad.length) {
+      failed++;
+      console.log(`  ${C.bad("fail")}  ${m.slug}`);
+      for (const [k, v] of bad) console.log(`         ${k}: ${v.replace(/^fail: /, "")}`);
+    } else {
+      console.log(`  ${C.ok("pass")}  ${m.slug}${skipped.length ? C.dim(`   (${skipped.map(([k]) => k).join(", ")} skipped)`) : ""}`);
+    }
+  }
+  console.log(`\n  ${targets.length - failed}/${targets.length} pass\n`);
+
+  // `--deep` asks Sprid what each platform will actually publish. Off by
+  // default because `check` must work offline and before a post exists.
+  let deepProblems = [];
+  if (has(argv, "deep")) {
+    const rows = await deepCrosspost(cfg, targets);
+    if (!rows.length) console.log(`  ${C.ok("crosspost")} every booked platform publishes what it should\n`);
+    else {
+      deepProblems = rows;
+      console.log(`  ${C.bad(`crosspost: ${rows.length} problem(s) in Sprid`)}\n`);
+      for (const r of rows) console.log(`    ${r.slug.padEnd(42)}${r.platform.padEnd(11)}${r.message}`);
+      console.log(`\n  ${C.dim("`sprid post sync --execute` rewrites a post's fields from the registry")}\n`);
+    }
+  }
+  return { exitCode: failed || deepProblems.length ? 1 : 0, checked: targets.length, failed, deepProblems };
+}
+
+const checksPass = (m) =>
+  m.checks && Object.entries(m.checks).every(([k, v]) => k === "at" || !String(v).startsWith("fail"));
+
+async function cmdPush(cfg, argv) {
+  const only = positional(argv);
+  const targets = (only ? [readManifest(cfg, only)] : allManifests(cfg)).filter(
+    (m) => has(argv, "force") || (m.sprid.videoId == null && !(m.sprid.imageIds?.length > 0)),
+  );
+  if (!targets.length) return console.log("\n  nothing to push (everything is already in Sprid)\n");
+
+  for (const m of targets) {
+    if (!checksPass(m)) {
+      console.log(`  ${C.warn("skip")}  ${m.slug} ${C.dim("- checks not passing, run `sprid post check`")}`);
+      continue;
+    }
+    // **A composed post has nothing here to upload.** Its pixels are the
+    // server's templates; the copy travels in `draft`. Saying so beats
+    // silently doing nothing, because "0 pushed" otherwise reads as a failure.
+    if (isComposed(m)) {
+      console.log(`  ${C.dim("composed")} ${m.slug.padEnd(40)} ${C.dim("nothing to upload - go straight to `draft`")}`);
+      continue;
+    }
+    if ((m.kind ?? "reel") === "carousel") {
+      await pushCarousel(cfg, m);
+      continue;
+    }
+    const file = resolve(cfg.root, m.source);
+    if (!existsSync(file)) {
+      console.log(`  ${C.bad("gone")}  ${m.slug} ${C.dim(`- ${m.source} is not on disk; rebuild it`)}`);
+      continue;
+    }
+    // Guard the record against a silent rebuild: the manifest is only true of
+    // the bytes it measured.
+    if (sha256(file) !== m.media.sha256) {
+      console.log(`  ${C.bad("stale")} ${m.slug} ${C.dim("- the file changed since it was registered; re-register it")}`);
+      continue;
+    }
+
+    const filename = `${m.slug}.mp4`;
+    const { uploadUrl, videoId } = await api(cfg, "POST", "/videos/upload-url", {
+      filename,
+      contentType: "video/mp4",
+      accountSlug: cfg.account,
+    });
+    const put = await fetch(uploadUrl, {
+      method: "PUT",
+      headers: { "Content-Type": "video/mp4" },
+      body: readFileSync(file),
+    });
+    if (!put.ok) throw new Error(`PUT to storage -> ${put.status}`);
+
+    // **Both stills, or the grids show nothing.** Sprid's card reads the small
+    // one and its player reads the big one, and a row that carries only a
+    // poster used to be recorded as carrying both - so every tile asked the
+    // CDN for a thumbnail that was never written. ffmpeg is already required
+    // here for measuring, so the second frame costs one more invocation.
+    const cover = coverFrame(
+      file,
+      join(cfg.registry, ".cache", `${m.slug}-cover.png`),
+      cfg.lanes[m.lane]?.coverAtMs ?? 0,
+    );
+    const small = thumbnail(cfg, cover, `${m.slug}-cover`);
+    await api(cfg, "POST", `/videos/${videoId}/confirm`, {
+      durationMs: m.media.durationMs,
+      width: m.media.width,
+      height: m.media.height,
+      sizeBytes: m.media.sizeBytes,
+      posterBase64: `data:image/png;base64,${readFileSync(cover).toString("base64")}`,
+      thumbBase64: small
+        ? `data:image/jpeg;base64,${readFileSync(small).toString("base64")}`
+        : undefined,
+    });
+    rmSync(cover, { force: true });
+    if (small) rmSync(small, { force: true });
+
+    // **`mediaShaAtPush` is what makes a re-render detectable**, and it is the
+    // exact counterpart of `captionShaAtDraft`, which has existed since the
+    // beginning. Without it the registry can say the file changed and cannot
+    // say whether Sprid still holds the old one, so a rebuilt reel sits in a
+    // scheduled post looking finished. Record the exact bytes uploaded.
+    m.sprid = { ...m.sprid, account: cfg.account, videoId, status: "uploaded", mediaShaAtPush: m.media.sha256 };
+    writeManifest(cfg, m);
+    console.log(`  ${C.ok("pushed")} ${m.slug.padEnd(40)} video ${videoId}`);
+  }
+  console.log();
+}
+
+/**
+ * The same two phases as a video, once per slide.
+ *
+ * **Every slide is uploaded twice, main and thumb**, because that is the shape
+ * Sprid's image record has and the thumbnail is what its own grids read. The
+ * small one is made with ffmpeg, which is already required here for measuring,
+ * so the package still has no dependencies.
+ */
+async function pushCarousel(cfg, m) {
+  const files = (m.slides ?? []).map((s) => resolve(cfg.root, s.file));
+  const missing = files.filter((f) => !existsSync(f));
+  if (missing.length) {
+    console.log(`  ${C.bad("gone")}  ${m.slug} ${C.dim(`- ${missing.length} slide(s) not on disk; rebuild it`)}`);
+    return;
+  }
+  const changed = files.filter((f, i) => sha256(f) !== m.slides[i].sha256);
+  if (changed.length) {
+    console.log(`  ${C.bad("stale")} ${m.slug} ${C.dim(`- ${changed.length} slide(s) changed since registering; re-register it`)}`);
+    return;
+  }
+
+  const imageIds = [];
+  for (const [i, file] of files.entries()) {
+    const ext = file.slice(file.lastIndexOf(".") + 1).toLowerCase();
+    const type = ext === "png" ? "image/png" : ext === "webp" ? "image/webp" : "image/jpeg";
+    const res = await api(cfg, "POST", "/images/upload-url", {
+      filename: `${m.slug}-${String(i + 1).padStart(2, "0")}.${ext}`,
+      contentType: type,
+      accountSlug: cfg.account,
+      tag: i === 0 ? "hero" : "body",
+      source: "sprid post",
+    });
+    // A deduped answer means Sprid already holds this file; nothing to upload.
+    if (res.deduped) {
+      imageIds.push(res.image.id);
+      continue;
+    }
+    const bytes = readFileSync(file);
+    const thumb = thumbnail(cfg, file, `${m.slug}-${i}`);
+    for (const [url, body] of [
+      [res.mainUploadUrl, bytes],
+      [res.thumbUploadUrl, thumb ? readFileSync(thumb) : bytes],
+    ]) {
+      const put = await fetch(url, { method: "PUT", headers: { "Content-Type": type }, body });
+      if (!put.ok) throw new Error(`PUT to storage -> ${put.status}`);
+    }
+    if (thumb) rmSync(thumb, { force: true });
+    await api(cfg, "POST", `/images/${res.image.id}/confirm`, {
+      width: m.slides[i].width,
+      height: m.slides[i].height,
+      sizeBytes: m.slides[i].sizeBytes,
+    });
+    imageIds.push(res.image.id);
+  }
+
+  m.sprid = {
+    ...m.sprid, account: cfg.account, imageIds, status: "uploaded",
+    mediaShaAtPush: (m.slides ?? []).map((sl) => sl.sha256).join(","),
+  };
+  writeManifest(cfg, m);
+  console.log(`  ${C.ok("pushed")} ${m.slug.padEnd(40)} ${imageIds.length} images`);
+}
+
+/** A 400px-wide copy, or null if ffmpeg will not make one. */
+function thumbnail(cfg, file, name) {
+  const out = join(cfg.registry, ".cache", `${name}-thumb.jpg`);
+  mkdirSync(dirname(out), { recursive: true });
+  const r = spawnSync("ffmpeg", ["-loglevel", "error", "-y", "-i", file, "-vf", "scale=400:-2", out]);
+  return r.status === 0 && existsSync(out) ? out : null;
+}
+
+/**
+ * Post, slide, video, caption. Stops at `draft` on purpose.
+ *
+ * Moving a post to `ready` is the last gate before something is public, and
+ * that stays a person's decision.
+ */
+async function cmdDraft(cfg, argv) {
+  const only = positional(argv);
+  // A composed post never gets uploaded, so waiting for an asset id would keep
+  // it out of every batch forever.
+  const uploaded = (m) => isComposed(m) || m.sprid.videoId != null || (m.sprid.imageIds?.length ?? 0) > 0;
+  const targets = (only ? [readManifest(cfg, only)] : allManifests(cfg)).filter(
+    (m) => uploaded(m) && (has(argv, "force") || m.sprid.postId == null),
+  );
+  if (!targets.length) return console.log("\n  nothing to draft (push first, or everything is drafted)\n");
+
+  for (const m of targets) {
+    // **`push` refused a failing post and `draft` did not, which left the gate
+    // ungated.** For a composed post there is nothing to push at all, so
+    // `draft` was the only verb that touched Sprid and it happily drafted a
+    // deck that had failed its own checks. Both verbs refuse now; `--force`
+    // does not override this, because a gate you can pass with a flag is a
+    // preference.
+    if (!checksPass(m)) {
+      console.log(`  ${C.warn("skip")}  ${m.slug} ${C.dim("- checks not passing, run `sprid post check`")}`);
+      continue;
+    }
+    const caption = existsSync(captionPath(cfg, m.slug))
+      ? readFileSync(captionPath(cfg, m.slug), "utf8").trim()
+      : "";
+    const captionTiktok = existsSync(tiktokCaptionPath(cfg, m.slug))
+      ? readFileSync(tiktokCaptionPath(cfg, m.slug), "utf8").trim()
+      : caption;
+
+    // **`--force` re-syncs the post it already made; it does not make another
+    // one.** The only reason to run `draft` twice is that something here
+    // changed - the caption was edited after the draft went over, which
+    // `status` reports and had no command to resolve, or the media was rebuilt
+    // and re-pushed. Answering that with a second post leaves the first one in
+    // the account looking equally real. A post that was deleted in Sprid is the
+    // one case where a new one is right, and a 404 is how that is known.
+    const existingPost = m.sprid.postId
+      ? await api(cfg, "GET", `/posts/${m.sprid.postId}`).catch((e) => {
+          // Only a post that is GONE justifies making another one. A network
+          // failure that fell through to the create branch would quietly
+          // duplicate the whole batch.
+          if (/-> 404/.test(e.message)) return null;
+          throw e;
+        })
+      : null;
+    const post =
+      existingPost ??
+      (await api(cfg, "POST", `/posts?account=${encodeURIComponent(cfg.account)}`, {
+        // Public titles come from approved copy; identifiers stay in internalName.
+        title: m.post?.title ?? postTitle(caption, m.slug),
+        internalName: m.post?.internalName ?? m.slug,
+        // A composed lane may name the Sprid format its posts are made from,
+        // and creating with it is what scaffolds the right slide roles.
+        ...(cfg.lanes[m.lane]?.format ? { formatId: cfg.lanes[m.lane].format } : {}),
+      }));
+    const carousel = (m.kind ?? "reel") === "carousel";
+    const composed = isComposed(m);
+
+    // **A new post already has slides, and `POST /posts` does not return
+    // them.** It scaffolds one row (or one per the format's template) and
+    // answers with the post alone, so `post.slides?.[0]` was always undefined
+    // and every draft this package made carried an EMPTY leading slide with
+    // the real media behind it - a blank first frame on a reel, a blank first
+    // card on a deck. Verified against the API on 2026-09-03: create returns
+    // no `slides` key, `GET /posts/:id` shows exactly one row at position 0.
+    //
+    // So: read the seats the post came with, add the ones it is short of,
+    // delete the ones it does not need, and fill them in order.
+    const seats = ((existingPost ? post : await api(cfg, "GET", `/posts/${post.id}`)).slides ?? []).sort(
+      (a, b) => a.position - b.position,
+    );
+    const need = composed ? (m.copy ?? []).length : carousel ? (m.sprid.imageIds ?? []).length : 1;
+    while (seats.length < need)
+      seats.push(await api(cfg, "POST", `/posts/${post.id}/slides`, { role: "body", text: "", subtitle: "" }));
+    for (const spare of seats.splice(need)) await api(cfg, "DELETE", `/slides/${spare.id}`);
+
+    if (composed) {
+      // **The words are the payload.** One card per spec slide, in the spec's
+      // order, and the template if the lane names one - after which Sprid holds
+      // everything it needs to render, and this repo still holds the copy that
+      // was gated.
+      const tpl = cfg.lanes[m.lane]?.template ?? null;
+      for (const [i, seat] of seats.entries()) {
+        const sl = m.copy[i];
+        await api(cfg, "PATCH", `/slides/${seat.id}`, {
+          text: sl.text ?? "",
+          subtitle: sl.subtitle ?? "",
+          ...(sl.bullets ? { bullets: sl.bullets } : {}),
+          role: sl.role ?? (i === 0 ? "hook" : "body"),
+          ...(sl.template || tpl ? { templateId: sl.template ?? tpl } : {}),
+        });
+      }
+    } else if (carousel) {
+      // One slide per image, in the registry's order.
+      const ids = m.sprid.imageIds ?? [];
+      for (const [i, seat] of seats.entries())
+        await api(cfg, "PATCH", `/slides/${seat.id}`, { imageId: ids[i], role: i === 0 ? "hook" : "body" });
+    } else {
+      // A finished reel is the whole composition. Clear every old render
+      // instruction as it is attached, or the publisher correctly refuses to
+      // guess whether the video or the leftover template should win.
+      await api(cfg, "PATCH", `/slides/${seats[0].id}`, {
+        videoId: m.sprid.videoId,
+        durationMs: m.media.durationMs,
+        templateId: null,
+        beats: [],
+      });
+    }
+
+    // **`audio: { silent: true }` is not optional when the music is already in
+    // the file.** A reel with no trackAssetId round-robins the account's track
+    // library, so leaving audio unset lays a second bed over the first.
+    const wanted = {
+      // Reconcile the title on every draft, including previously created posts.
+      title: m.post?.title ?? postTitle(caption, m.slug),
+      internalName: m.post?.internalName ?? m.slug,
+      // Sprid's two content types: a carousel is `image`, whatever it holds.
+      // Sprid's two content types. A composed lane says which it is with
+      // `kind: "composed"` plus its own `contentType`; a deck of images is
+      // `image` whatever it holds.
+      contentType: composed ? (cfg.lanes[m.lane]?.contentType ?? "image") : carousel ? "image" : "reel",
+      // One string per platform, tags included. Sprid has no hashtags field.
+      captionInstagram: caption,
+      captionTiktok,
+      ...(m.post.instagramLocationId ? { instagramLocationId: m.post.instagramLocationId } : {}),
+      ...(m.post.pinterestOptions ? { pinterestOptions: m.post.pinterestOptions } : {}),
+      // **Silence is a reel's problem only.** A carousel has no audio to
+      // double up, and Sprid picks its own track for one if it wants.
+      // **Silence is a rendered reel's problem only.** It says "the music is
+      // already inside this file"; a composed reel has no file yet, so Sprid's
+      // own track rotation is exactly what should happen to it.
+      ...(carousel || composed ? {} : { audio: { silent: true }, motion: null }),
+    };
+    await api(cfg, "PATCH", `/posts/${post.id}`, { ...wanted, status: "draft" });
+
+    // **A 200 does not prove the field landed.** The API validates with a
+    // schema that STRIPS what it does not declare, so a field the server is
+    // too old to know about is dropped and answered with a success. Measured
+    // 2026-09-03 against api.sprid.studio: `audio: { silent: true }` PATCHed
+    // cleanly, came back `null`, and the reel it drafted would have published
+    // with a second music bed laid over its own - which is the exact failure
+    // the field exists to prevent. The consuming repo has no way to know that
+    // from the output, so the record is read back and compared.
+    const dropped = verifyDraft(await api(cfg, "GET", `/posts/${post.id}`), wanted);
+    for (const [field, why] of dropped) console.log(`  ${C.bad("dropped")} ${m.slug.padEnd(40)} ${field} - ${why}`);
+
+    m.sprid = {
+      ...m.sprid,
+      postId: post.id,
+      status: "drafted",
+      captionShaAtDraft: m.post.captionSha ?? null,
+      // Kept, so `status` can still say it a week later and so a re-run after
+      // the server is updated has something to compare against.
+      dropped: dropped.length ? dropped.map(([f]) => f) : null,
+    };
+    writeManifest(cfg, m);
+    console.log(
+      `  ${C.ok(existingPost ? "updated" : "drafted")} ${m.slug.padEnd(40)} post ${post.id}` +
+        (composed ? C.dim(`  ${seats.length} cards`) : carousel ? C.dim(`  ${m.sprid.imageIds.length} slides`) : ""),
+    );
+  }
+  console.log(`\n  ${C.dim("review in Sprid, then move each to `ready` yourself.")}\n`);
+}
+
+/**
+ * What the server kept, against what was asked of it.
+ *
+ * Only fields where a silent drop changes what gets PUBLISHED - the caption,
+ * the shape of the post, the music, the location tag. Each answer carries the
+ * consequence rather than the diff, because "audio.silent missing" is not a
+ * thing anybody can act on and "this reel will publish with two soundtracks"
+ * is.
+ */
+export function verifyDraft(back, wanted) {
+  const out = [];
+  if (wanted.audio?.silent && back.audio?.silent !== true)
+    out.push(["audio.silent", "this reel will publish with a rotated track OVER its own audio. Update Sprid, then `draft --force`"]);
+  if (wanted.instagramLocationId && back.instagramLocationId !== wanted.instagramLocationId)
+    out.push(["instagramLocationId", "the post will publish untagged"]);
+  if (wanted.contentType && back.contentType !== wanted.contentType)
+    out.push(["contentType", `the post is a "${back.contentType}", not a "${wanted.contentType}"`]);
+  if ((back.captionInstagram ?? "") !== (wanted.captionInstagram ?? ""))
+    out.push(["captionInstagram", "the caption in Sprid is not the one in the registry"]);
+  if (wanted.title && back.title !== wanted.title)
+    out.push(["title", "YouTube publishes this as the Short's title; Sprid is holding a different one"]);
+  if (wanted.pinterestOptions && JSON.stringify(back.pinterestOptions ?? null) !== JSON.stringify(wanted.pinterestOptions))
+    out.push(["pinterestOptions", "the Pin will lose its reviewed board, destination or metadata"]);
+  return out;
+}
+
+/**
+ * What is different here from what Sprid is holding, and the smallest set of
+ * calls that closes the gap.
+ *
+ * **A post is never edited; a deck is re-rendered and the queue catches up.**
+ * That is the whole design decision. The alternative - reaching into Sprid to
+ * swap a file on a scheduled post - makes the queue the source of truth for
+ * content, and then a spec and a published reel can disagree with nothing able
+ * to say which is right. Here the registry owns the content, Sprid owns the
+ * calendar, and this is the one command that reconciles them.
+ *
+ * Reconcile media and metadata together so a rebuilt queue remains reproducible.
+ *
+ * Three rules, and the first two are refusals:
+ *
+ * - **A post that is out is frozen.** Sync reads the post's status and touches
+ *   only `draft` and `ready`. Anything else - published, publishing, whatever
+ *   Sprid adds next - is skipped by name. Fail-closed on an unknown status is
+ *   deliberate: re-posting is a new slug, not an edit.
+ * - **It never creates anything.** No postId, no sync; that is what `draft` is
+ *   for. So a sync can never widen a batch by accident.
+ * - **It does the minimum.** Media drifted, caption drifted, or neither. A slug
+ *   whose caption changed does not get its video re-uploaded.
+ *
+ * The schedule is not touched at all. Swapping the file behind a booked post
+ * keeps its slot, which is the point.
+ */
+async function cmdSync(cfg, argv) {
+  const only = positional(argv);
+  const execute = has(argv, "execute");
+  const lane = flag(argv, "lane");
+  const all = (only ? [readManifest(cfg, only)] : allManifests(cfg))
+    .filter((m) => m.sprid?.postId)
+    .filter((m) => !lane || m.lane === lane);
+  if (!all.length) return console.log("\n  nothing drafted yet - `push` then `draft` first\n");
+
+  // **`--adopt` is a migration, not a sync.** Every manifest written before
+  // `mediaShaAtPush` existed reads as stale, which for a batch that was never
+  // rebuilt means uploading files Sprid already holds. Adopting records what is
+  // on disk as what was uploaded and sends nothing.
+  //
+  // It is an assertion, so it can be wrong: adopt a slug that WAS rebuilt and
+  // Sprid keeps serving the old file with nothing left to say so. Scope it -
+  // `--lane`, or a slug - to the ones you know were never touched.
+  if (has(argv, "adopt")) {
+    const orphans = all.filter((m) => m.sprid.mediaShaAtPush == null && !isComposed(m));
+    if (!orphans.length) return console.log("\n  nothing to adopt - every post already records what was uploaded\n");
+    if (!execute) {
+      console.log(`\n  ${C.bold("would adopt")}  ${orphans.length} post(s)`);
+      console.log(`  ${C.dim("asserts Sprid is holding the file now on disk. Wrong for anything rebuilt since.")}\n`);
+      for (const m of orphans) console.log(`  ${m.slug.padEnd(42)}${C.dim(m.lane ?? "")}`);
+      return console.log(`\n  ${C.dim("nothing written. re-run with --execute")}\n`);
+    }
+    for (const m of orphans) {
+      m.sprid = {
+        ...m.sprid,
+        mediaShaAtPush:
+          (m.kind ?? "reel") === "carousel"
+            ? (m.slides ?? []).map((sl) => sl.sha256).join(",")
+            : m.media?.sha256 ?? null,
+      };
+      writeManifest(cfg, m);
+    }
+    return console.log(`\n  ${C.ok("adopted")} ${orphans.length} post(s) - nothing uploaded\n`);
+  }
+
+  // **A third kind of drift, and it is invisible to a sha.** The title Sprid
+  // holds is what TikTok and YouTube publish, and it is derived from the
+  // caption rather than stored beside it - so a post whose media and caption
+  // are both current can still be carrying an outdated title.
+  // One GET each during planning; the execute pass needs the record anyway.
+  /** A post whose current title could not be read. Counts as drift. */
+  const UNREADABLE = Symbol("unreadable");
+  const remoteTitle = new Map();
+  for (const m of all) {
+    const cp = captionPath(cfg, m.slug);
+    if (!existsSync(cp)) continue;
+    // **A read that failed is not a post that agrees with us.** The first cut
+    // swallowed the error and left the slug out of the map, which reads as "no
+    // title drift" - the same unverified-negative that cost the whole day. One
+    // retry for a restarting dev server, then it counts as drift.
+    let post = await api(cfg, "GET", `/posts/${m.sprid.postId}`).catch(() => null);
+    if (!post) post = await api(cfg, "GET", `/posts/${m.sprid.postId}`).catch(() => null);
+    remoteTitle.set(m.slug, post ? (post.title ?? "") : UNREADABLE);
+  }
+
+  const plan = [];
+  for (const m of all) {
+    // **Unknown counts as stale, and it has to.** `mediaShaAtPush` did not
+    // exist before 2026-09-09, so every manifest written before it carries
+    // none - and a record that cannot say what was uploaded cannot say it is
+    // current. Assuming fresh would silently leave old files in the queue,
+    // which is the failure this command exists for.
+    const pushedSha = m.sprid.mediaShaAtPush ?? null;
+    const localSha = isComposed(m)
+      ? null
+      : (m.kind ?? "reel") === "carousel"
+        ? (m.slides ?? []).map((sl) => sl.sha256).join(",")
+        : m.media?.sha256 ?? null;
+    const media = isComposed(m) ? false : pushedSha == null ? "unknown" : pushedSha !== localSha;
+    const caption = (m.post?.captionSha ?? null) !== (m.sprid.captionShaAtDraft ?? null);
+    const cp = captionPath(cfg, m.slug);
+    const want = m.post?.title ?? (existsSync(cp) ? postTitle(readFileSync(cp, "utf8"), m.slug) : null);
+    const title = remoteTitle.has(m.slug) && want !== null && remoteTitle.get(m.slug) !== want;
+    const unreadable = remoteTitle.get(m.slug) === UNREADABLE;
+    if (media || caption || title) plan.push({ m, media, caption, title, unreadable });
+  }
+
+  if (!plan.length) { console.log("\n  in sync - nothing in the registry differs from Sprid\n"); return { plan: [], execute }; }
+
+  console.log(`\n  ${C.bold(execute ? "syncing" : "would sync")}  ${plan.length} of ${all.length}\n`);
+  for (const { m, media, caption, title, unreadable } of plan) {
+    const what = [
+      media === "unknown" ? C.warn("media (never recorded, assumed stale)") : media ? C.warn("media") : null,
+      caption ? C.warn("caption") : null,
+      title ? C.warn(unreadable ? "title (could not read Sprid's, assumed stale)" : "title") : null,
+    ].filter(Boolean).join(" + ");
+    console.log(`  ${m.slug.padEnd(42)}${what}`);
+  }
+  if (!execute) {
+    console.log(`\n  ${C.dim("nothing written. re-run with --execute")}\n`);
+    return { execute, plan: plan.map(({ m, ...change }) => ({ slug: m.slug, ...change })) };
+  }
+
+  console.log();
+  let done = 0, skipped = 0;
+  for (const { m, media } of plan) {
+    // The live status decides whether this one may be touched at all. Read it
+    // here rather than trusting the manifest: the manifest's `status` is what
+    // this machine last wrote, and the queue moves without us.
+    let post;
+    try {
+      post = await api(cfg, "GET", `/posts/${m.sprid.postId}`);
+    } catch (e) {
+      if (/-> 404/.test(e.message)) {
+        console.log(`  ${C.bad("gone")}  ${m.slug.padEnd(40)} ${C.dim("no such post in Sprid - `draft` makes a new one")}`);
+        skipped++;
+        continue;
+      }
+      throw e;
+    }
+    const state = post.status ?? "unknown";
+    if (!SYNCABLE.has(state)) {
+      console.log(`  ${C.dim("frozen")} ${m.slug.padEnd(40)} ${C.dim(`status "${state}" - not a draft any more, leave it`)}`);
+      skipped++;
+      continue;
+    }
+    if (media) await cmdPush(cfg, [m.slug, "--force"]);
+    // Re-read: push rewrote the manifest, and draft has to send the new videoId.
+    await cmdDraft(cfg, [readManifest(cfg, m.slug).slug, "--force"]);
+    done++;
+  }
+  console.log(`  ${done} synced, ${skipped} left alone\n`);
+  return { execute, synced: done, skipped, plan: plan.map(({ m, ...change }) => ({ slug: m.slug, ...change })) };
+}
+
+/**
+ * The post states a sync may write to.
+ *
+ * An allowlist rather than a list of the ones to avoid: a status this package
+ * has never heard of is far more likely to be further along the pipeline than
+ * behind it, and the cost of skipping one is a line of output.
+ */
+const SYNCABLE = new Set(["draft", "ready"]);
+
+/**
+ * Bring Sprid's side of each post back into the registry.
+ *
+ * **The queue lives in Sprid and nothing here could read it**, which is a
+ * bigger hole than it sounds: the repo could not answer "what goes out
+ * tomorrow" or "which one went out last" without the API being reachable, and
+ * a booking made weeks ago left no trace anybody could review in a diff. A post
+ * is committed; when it publishes was not.
+ *
+ * So this writes what Sprid knows back into `sprid.remote`: the status, and the
+ * schedule if the post carries one. The schedule's shape is read defensively -
+ * whatever key it arrives under, it is recorded verbatim under `raw` as well,
+ * so a field this package does not recognise is visible rather than lost.
+ */
+/**
+ * A post's remote state, from its publish rows.
+ *
+ * Track each platform separately: a reel may be published on one and scheduled
+ * on another. Summary dates are the earliest observed date of each kind.
+ */
+export function remoteOf(publishes) {
+  return {
+    publishes,
+    scheduledAt: publishes.map((p) => p.scheduledFor).filter(Boolean).sort()[0] ?? null,
+    publishedAt: publishes.map((p) => p.publishedAt).filter(Boolean).sort()[0] ?? null,
+  };
+}
+
+async function cmdPull(cfg, argv) {
+  const only = positional(argv);
+  const all = (only ? [readManifest(cfg, only)] : allManifests(cfg)).filter((m) => m.sprid?.postId);
+  if (!all.length) return console.log("\n  nothing drafted yet\n");
+
+  // Publish rows hold schedule dates; post summaries do not include them.
+  const rows = await api(cfg, "GET", `/publishes?account=${encodeURIComponent(cfg.account)}&limit=1000`);
+  const byPost = new Map();
+  for (const r of Array.isArray(rows) ? rows : []) {
+    const list = byPost.get(r.postId) ?? [];
+    list.push({
+      platform: r.platform,
+      status: r.status,
+      scheduledFor: r.scheduledFor ?? null,
+      publishedAt: r.publishedAt ?? null,
+      lastError: r.lastError ?? null,
+      attempts: r.attempts ?? 0,
+    });
+    byPost.set(r.postId, list);
+  }
+
+  let orphans = 0;
+  for (const m of all) {
+    const publishes = (byPost.get(m.sprid.postId) ?? []).sort((a, b) => a.platform.localeCompare(b.platform));
+    if (!publishes.length) orphans++;
+    m.sprid = { ...m.sprid, remote: { ...remoteOf(publishes), at: new Date().toISOString() } };
+    writeManifest(cfg, m);
+    const when = m.sprid.remote.publishedAt ?? m.sprid.remote.scheduledAt;
+    const failed = publishes.filter((p) => p.lastError);
+    console.log(
+      `  ${C.ok("pulled")} ${m.slug.padEnd(42)}` +
+        publishes.map((p) => `${p.platform[0]}${p.status === "published" ? C.ok("✓") : p.status === "scheduled" ? C.dim("·") : C.bad("!")}`).join(" ").padEnd(22) +
+        C.dim(when ? when.slice(0, 16).replace("T", " ") : "not booked") +
+        (failed.length ? `  ${C.bad(failed.map((f) => `${f.platform}: ${f.lastError}`).join("; ").slice(0, 60))}` : ""),
+    );
+  }
+  if (orphans)
+    console.log(`\n  ${C.warn(`${orphans} post(s) carry no publish row at all - drafted but never booked`)}`);
+  console.log();
+}
+
+/**
+ * What a post is created with, and it is published rather than filed.
+ *
+ * YouTube's adapter takes `post.title` ahead of the caption for a Short's
+ * `snippet.title`, so a slug here ships "some-slug-like-this #Shorts" to a
+ * viewer. A caption's first line is a title in every repo using this package;
+ * the slug is stored as internalName so an uncaptioned post stays findable
+ * without making an identifier public.
+ */
+export function postTitle(caption, slug) {
+  return (caption ?? "").split("\n")[0].trim();
+}
+
+/**
+ * Where this repo is pointed, whether it answers, and what it says back.
+ *
+ * Probe each candidate URL and report disagreements. A saved registry does
+ * not establish whether its configured service is reachable.
+ */
+async function cmdDoctor(cfg) {
+  let logged = null;
+  try {
+    logged = resolveAuth();
+  } catch {
+    // Not logged in is a state to report, not to throw on: it is exactly what
+    // this command is for.
+  }
+  const candidates = [
+    ["SPRID_URL", process.env.SPRID_URL],
+    ["sprid.config apiUrl", cfg.apiUrl === defaultApi() ? null : cfg.apiUrl],
+    [`sprid login (${logged?.source ?? "not logged in"})`, logged?.apiUrl],
+    ["default", DEFAULT_API_URL],
+  ].filter(([, v]) => v);
+
+  console.log(`\n  ${C.bold(cfg.account)}  ${C.dim("using")} ${C.bold(cfg.apiUrl)}\n`);
+  for (const [where, url] of candidates)
+    console.log(`  ${url === cfg.apiUrl ? C.ok("→") : " "} ${where.padEnd(28)}${C.dim(url)}`);
+  if (new Set(candidates.map(([, u]) => u)).size > 1)
+    console.log(`\n  ${C.dim("more than one candidate: the arrow is the one in use")}`);
+
+  // Dial every candidate, not only the chosen one. A repo pointed at a host
+  // that is down while another candidate answers is the whole failure mode.
+  console.log();
+  for (const url of new Set(candidates.map(([, u]) => u))) {
+    const t0 = Date.now();
+    let line;
+    try {
+      const res = await fetch(`${url}/api/accounts`, {
+        redirect: 'error',
+        headers: url === cfg.apiUrl ? { Authorization: `Bearer ${token(cfg)}` } : {},
+        signal: AbortSignal.timeout(8000),
+      });
+      const ms = Date.now() - t0;
+      if (!res.ok) line = `${C.bad(String(res.status))} ${C.dim(`${ms}ms`)}`;
+      else {
+        const accounts = await res.json();
+        const mine = Array.isArray(accounts) ? accounts.find((a) => a.slug === cfg.account) : null;
+        line = mine
+          ? `${C.ok("ok")} ${C.dim(`${ms}ms`)}  ${C.bold(`account ${mine.id}`)}  ` +
+            (mine.channelSummary ?? [])
+              .map((c) => `${c.platform}:${c.status === "active" ? C.ok(c.status) : C.bad(c.status)}`)
+              .join(" ")
+          : `${C.warn("reachable, but no account")} "${cfg.account}" ${C.dim(`(${ms}ms)`)}`;
+      }
+    } catch (e) {
+      line = `${C.bad("unreachable")} ${C.dim(String(e?.cause?.code ?? e?.name ?? e?.message).slice(0, 40))}`;
+    }
+    console.log(`  ${url.padEnd(30)} ${line}`);
+  }
+
+  // How stale the local view of the queue is. `status` cannot say this and it
+  // is the difference between "Several posts drafted" and "Several posts drafted, as of the last pull".
+  const pulled = allManifests(cfg)
+    .map((m) => m.sprid?.remote?.at)
+    .filter(Boolean)
+    .sort();
+  console.log(
+    `\n  ${pulled.length ? `${pulled.length} post(s) pulled, oldest ${pulled[0].slice(0, 16).replace("T", " ")}` : C.warn("never pulled - `sprid post pull` brings the schedule in")}\n`,
+  );
+}
+
+async function cmdStatus(cfg) {
+  const all = allManifests(cfg);
+  if (!all.length) return console.log("\n  nothing registered yet\n");
+  const lufs = all.map((m) => m.media?.lufs).filter((v) => typeof v === "number");
+
+  console.log(`\n  ${C.bold(cfg.account)}  ${C.dim(cfg.apiUrl)}\n`);
+  console.log(`  ${"slug".padEnd(42)}${"lane".padEnd(15)}${"size".padEnd(11)}${"checks".padEnd(9)}sprid`);
+  console.log(`  ${C.dim("-".repeat(91))}`);
+  for (const m of all) {
+    const checks = !m.checks ? C.dim("-") : checksPass(m) ? C.ok("pass") : C.bad("fail");
+    let state = m.sprid?.status ?? "none";
+    // The one way the two halves drift apart in silence: the caption was
+    // edited here after the draft went over.
+    if (state === "drafted" && m.sprid.captionShaAtDraft && m.post.captionSha !== m.sprid.captionShaAtDraft)
+      state = C.warn("caption changed");
+    // The other way they drift, and the one that had no name until 2026-09-09:
+    // the media was rebuilt and re-registered, so Sprid is still serving the
+    // file from before. `sync` is the answer to both.
+    if (m.sprid?.postId && !isComposed(m) && m.sprid.mediaShaAtPush && m.media?.sha256 !== m.sprid.mediaShaAtPush)
+      state = C.warn("media changed");
+    // A post that is out is a fact about the world, and outranks any local drift.
+    if (m.sprid?.remote?.publishedAt) state = C.dim(`published ${m.sprid.remote.publishedAt.slice(0, 10)}`);
+    else if (m.sprid?.remote?.scheduledAt) state += C.dim(`  ${m.sprid.remote.scheduledAt.slice(0, 16).replace("T", " ")}`);
+    // A field the server silently refused stays visible: it is the one kind of
+    // damage that is invisible in Sprid's own UI too.
+    if (m.sprid?.dropped?.length) state = C.bad(`${m.sprid.dropped.join(", ")} dropped`);
+    // What "how big" means depends on the kind: a reel is seconds, a carousel
+    // is slides.
+    const size = isComposed(m)
+      ? `${m.media?.slideCount ?? 0} cards`
+      : (m.kind ?? "reel") === "carousel"
+        ? `${m.media?.slideCount ?? m.slides?.length ?? 0} slides`
+        : `${(m.media.durationMs / 1000).toFixed(1)}s`;
+    console.log(
+      `  ${m.slug.padEnd(42)}${(m.lane ?? "").padEnd(15)}${size.padEnd(11)}` +
+        `${checks.padEnd(checks.includes("\x1b") ? 18 : 9)}${state}`,
+    );
+  }
+  const drafted = all.filter((m) => m.sprid?.postId).length;
+  const pushed = all.filter((m) => m.sprid?.videoId || m.sprid?.imageIds?.length).length;
+  const legacy = existsSync(join(cfg.registry, LEGACY_DIR))
+    ? readdirSync(join(cfg.registry, LEGACY_DIR)).filter((f) => f.endsWith(".json")).length
+    : 0;
+  if (legacy)
+    console.log(
+      `\n  ${C.dim(`${legacy} record(s) still in ${LEGACY_DIR}/ - the directory is called ${POSTS_DIR}/ now, a rename is the whole migration`)}`,
+    );
+  console.log(
+    `\n  ${all.length} registered · ${pushed} uploaded · ${drafted} drafted` +
+      (lufs.length > 1 ? ` · loudness spread ${(Math.max(...lufs) - Math.min(...lufs)).toFixed(1)} dB` : "") +
+      "\n",
+  );
+}
+
+
+/**
+ * The preview — the whole batch on one page, before any of it is a post.
+ *
+ * **It reads the registry and nothing else**, so it is the same command in
+ * every repo: manifests carry the lane, the length, the check result and the
+ * Sprid state, the captions sit beside them, and the media is wherever the lane
+ * says. That is the entire input. The page it writes is disposable.
+ *
+ * The media is symlinked rather than copied, because a batch is gigabytes and a
+ * preview is meant to be cheap enough to regenerate without thinking about it.
+ * `--copy` is there for the case where the page has to travel (an AirDrop, a
+ * zip to somebody who is not on this machine), and it is the slow path on
+ * purpose.
+ *
+ * **A file that is not on disk is drawn as a missing card, never dropped.** The
+ * mp4s regenerate from their specs and routinely are not there; a preview that
+ * silently omitted them would hide incomplete work.
+ */
+async function cmdPreview(cfg, argv) {
+  const opts = {
+    outDir: resolve(cfg.root, flag(argv, "out") ?? "tmp/sprid-preview"),
+    laneOnly: flag(argv, "lane"),
+    copy: has(argv, "copy"),
+    verify: has(argv, "verify"),
+  };
+  const { indexFile } = await buildPreview(cfg, opts);
+  if (has(argv, "serve"))
+    return serve(cfg, opts, Number(flag(argv, "serve") ?? flag(argv, "port") ?? portForAccount(cfg.account)));
+  if (has(argv, "open")) spawnSync("open", [indexFile]);
+  return { indexFile };
+}
+
+async function buildPreview(cfg, { outDir, laneOnly, copy, verify }) {
+  const { renderPreview } = await import(`./preview.mjs?v=${Date.now()}`);
+  const mediaDir = join(outDir, "media");
+
+  let all = allManifests(cfg);
+  if (laneOnly) all = all.filter((m) => m.lane === laneOnly);
+  if (!all.length) throw new Error(laneOnly ? `Nothing registered in lane "${laneOnly}".` : "Nothing registered yet.");
+
+  rmSync(mediaDir, { recursive: true, force: true });
+  mkdirSync(mediaDir, { recursive: true });
+
+  let missing = 0;
+  let stale = 0;
+  const items = all.map((m) => {
+    const kind = m.kind ?? "reel";
+    const file = kind === "carousel" ? null : resolve(cfg.root, m.source);
+    const present = kind === "carousel" ? (m.slides ?? []).every((sl) => existsSync(resolve(cfg.root, sl.file))) : existsSync(file);
+    let src = null;
+    let slideSrcs = null;
+    let isStale = false;
+
+    if (kind === "carousel" && present) {
+      // Each slide gets its own link, numbered so the page can rely on order.
+      slideSrcs = (m.slides ?? []).map((sl, i) => {
+        const from = resolve(cfg.root, sl.file);
+        if (statSync(from).size !== sl.sizeBytes) isStale = true;
+        const ext = from.slice(from.lastIndexOf("."));
+        const link = join(mediaDir, `${m.slug}-${String(i + 1).padStart(2, "0")}${ext}`);
+        if (copy) copyFileSync(from, link);
+        else symlinkSync(from, link);
+        return `media/${basename(link)}`;
+      });
+    }
+
+    if (kind !== "carousel" && present) {
+      // Cheap by default: a size that no longer matches the record means the
+      // file was rebuilt since it was measured. `--verify` spends the sha.
+      const size = statSync(file).size;
+      isStale = verify ? sha256(file) !== m.media?.sha256 : size !== m.media?.sizeBytes;
+      const link = join(mediaDir, `${m.slug}.mp4`);
+      if (copy) copyFileSync(file, link);
+      else symlinkSync(file, link);
+      src = `media/${m.slug}.mp4`;
+    }
+    if (!present) missing++;
+    if (isStale) stale++;
+
+    const capFile = captionPath(cfg, m.slug);
+    const named = Object.entries(m.checks ?? {}).filter(([k]) => k !== "at");
+    const failures = named.filter(([, v]) => String(v).startsWith("fail")).map(([k]) => k);
+    const passed = named.filter(([, v]) => v === "pass").map(([k]) => k);
+
+    return {
+      slug: m.slug,
+      lane: m.lane,
+      kind,
+      source: m.source,
+      src,
+      slides: slideSrcs,
+      stale: isStale,
+      caption: existsSync(capFile) ? readFileSync(capFile, "utf8").trim() : null,
+      durationMs: m.media?.durationMs ?? null,
+      slideCount: m.media?.slideCount ?? m.slides?.length ?? null,
+      aspect: m.media?.aspect ?? null,
+      sizeBytes: m.media?.sizeBytes ?? null,
+      lufs: typeof m.media?.lufs === "number" ? m.media.lufs : null,
+      checks: !m.checks ? null : failures.length ? "fail" : "pass",
+      failures,
+      passed,
+      build: m.build?.command ?? null,
+      spridStatus: m.sprid?.status ?? "none",
+      captionDrifted:
+        m.sprid?.status === "drafted" &&
+        m.sprid?.captionShaAtDraft != null &&
+        m.post?.captionSha !== m.sprid.captionShaAtDraft,
+    };
+  });
+
+  const indexFile = join(outDir, "index.html");
+  writeFileSync(
+    indexFile,
+    renderPreview({ account: cfg.account, items, generatedAt: new Date().toISOString().replace("T", " ").slice(0, 16) }),
+  );
+
+  console.log(
+    `  ${C.ok("preview")} ${items.length} post${items.length === 1 ? "" : "s"}` +
+      (missing ? C.warn(`  ${missing} with no file on disk`) : "") +
+      (stale ? C.warn(`  ${stale} differing from their record`) : "") +
+      `  ${C.dim(indexFile.replace(cfg.root + "/", ""))}`,
+  );
+  return { indexFile, outDir, count: items.length };
+}
+
+/**
+ * A static server for the preview, with Range and a live reload.
+ *
+ * **`file://` is enough to watch a reel and not enough to scrub one**: without
+ * a 206 the browser cannot seek inside an mp4, and Safari will not play a
+ * symlinked file at all.
+ *
+ * **The reload is here because the alternative is a pile of tabs.** Registering
+ * a reel, editing a caption or changing this page's own code is something you
+ * do a dozen times in a sitting, and re-running the command to see it opens a
+ * new tab each time and loses where you were. The page holds an EventSource;
+ * a change rebuilds the file and tells the tab you already have to refresh -
+ * and since the current reel lives in the URL hash, a refresh comes back to it.
+ */
+/**
+ * A stable port per account, so several repos can preview at once.
+ *
+ * Derive a stable preferred port from the account slug to reduce collisions
+ * between projects. Hash collisions remain possible; --serve <port> overrides.
+ */
+export function portForAccount(account, base = 4599) {
+  let h = 0;
+  for (const ch of account) h = (h * 31 + ch.charCodeAt(0)) >>> 0;
+  return base + (h % 40);
+}
+
+async function serve(cfg, opts, port) {
+  const dir = opts.outDir;
+  const clients = new Set();
+  const srv = createServer(previewHandler({ directory: dir, account: cfg.account, clients }));
+
+  // **A busy port is answered by asking who is on it, never by assuming.** If
+  // it is this account's own preview, re-running the command is how you find
+  // out one is already up and the right answer is to say so. If it is another
+  // project's, walking to the next free port is the only answer that does not
+  // hand somebody the wrong batch.
+  for (let tries = 0; tries < 12; tries++, port++) {
+    const holder = await whoIsServing(port);
+    if (holder === cfg.account) {
+      console.log(
+        `  ${C.warn("already serving")} ${C.bold(cfg.account)} on http://localhost:${port}/` +
+          ` - that tab is live, it reloads itself\n`,
+      );
+      return { url: `http://localhost:${port}/`, alreadyServing: true };
+    }
+    if (holder != null) {
+      // A server too old to answer `/__whoami` reports "", which still means
+      // "not ours" - say that rather than printing an empty pair of quotes.
+      console.log(
+        `  ${C.dim(`:${port} is serving ${holder ? `"${holder}"` : "something else"}, trying :${port + 1}`)}`,
+      );
+      continue;
+    }
+    const bound = await new Promise((ok) => {
+      srv.once("error", (e) => (e.code === "EADDRINUSE" ? ok(false) : (() => { throw e; })()));
+      srv.listen(port, "127.0.0.1", () => ok(true));
+    });
+    if (!bound) continue;
+    const url = `http://localhost:${port}/`;
+    console.log(`  ${C.bold(url)}  ${C.bold(cfg.account)}  ${C.dim("watching for changes · ctrl-c to stop")}\n`);
+    spawnSync("open", [url]);
+    watchAndRebuild(cfg, opts, clients);
+    return { url };
+  }
+  throw new Error(`no free port from ${port - 12}; pass --serve <port>`);
+}
+
+/**
+ * The account whose preview is on this port, or null if nothing is.
+ *
+ * A server too old to answer `/__whoami` returns "" rather than null, which
+ * still means "occupied by something that is not us" - the safe reading.
+ */
+async function whoIsServing(port) {
+  try {
+    const res = await fetch(`http://localhost:${port}/__whoami`, { signal: AbortSignal.timeout(600) });
+    if (!res.ok) return "";
+    const body = await res.json().catch(() => null);
+    return typeof body?.account === "string" ? body.account : "";
+  } catch (e) {
+    // ECONNREFUSED is the only "nothing there"; a timeout is something there.
+    return /ECONNREFUSED|refused/i.test(String(e?.cause?.code ?? e?.message ?? "")) ? null : "";
+  }
+}
+
+/** Everything a preview is a function of: the registry, the media, this code. */
+function watchAndRebuild(cfg, opts, clients) {
+  // **Both registry directories.** The records moved to `posts/` and the
+  // watcher stayed on `reels/`, so in a repo that had migrated, registering
+  // something while the server was up changed nothing on the page.
+  const dirs = new Set([
+    join(cfg.registry, POSTS_DIR),
+    join(cfg.registry, LEGACY_DIR),
+    join(cfg.registry, "captions"),
+    dirname(new URL(import.meta.url).pathname),
+  ]);
+  for (const name of Object.keys(cfg.lanes)) {
+    if (opts.laneOnly && name !== opts.laneOnly) continue;
+    dirs.add(resolve(cfg.root, dirname(fill(mediaTemplate(cfg.lanes[name]), "x"))));
+    if (cfg.lanes[name].caption) dirs.add(resolve(cfg.root, dirname(fill(cfg.lanes[name].caption, "x"))));
+  }
+
+  let timer = null;
+  const rebuild = () => {
+    clearTimeout(timer);
+    timer = setTimeout(async () => {
+      try {
+        await buildPreview(cfg, opts);
+        for (const res of clients) res.write("data: reload\n\n");
+      } catch (e) {
+        console.log(`  ${C.bad("build failed")} ${e.message}`);
+      }
+    }, 200);
+  };
+
+  for (const d of dirs) {
+    if (!existsSync(d)) continue;
+    try {
+      watch(d, rebuild);
+    } catch {
+      // A directory that cannot be watched is not worth failing the server for.
+    }
+  }
+}
+
+// ─── entry ───────────────────────────────────────────────────────────────────
+
+const USAGE = `
+  sprid post — build posts in your own repo, then push them to Sprid.
+  A post is a reel (one video), a carousel (a directory of images), or composed
+  (no local file at all - Sprid renders it and this repo holds the copy).
+
+    post init               what are your posts made of, and do you even need this
+                            --kind text | composed | stills | own
+    post new <slug>         scaffold a spec - the copy, or the pictures
+    post build    [slug]    run the lane's builder - yours, or the stills recipe
+    post register [slug]    measure finished media into the registry (no slug = every lane)
+           --built-with "<cmd>"   record the command that made it, so it can be made again
+    post check    [slug]    run the gate; writes the result into each manifest
+             --deep         also ask Sprid what each platform will publish
+    post push     [slug]    upload to Sprid (refuses anything not passing check)
+    post draft    [slug]    create the post, attach the media or the copy, set the caption
+                            refuses anything not passing check, --force included
+    post sync     [slug]    a re-render into the posts that already exist, keeping their
+                            slot. Plan only, --execute to write. Refuses anything past
+                            'ready' - a published post is frozen.
+             --adopt        one-time: record what is on disk as what was uploaded,
+                            for a batch that predates the record. Uploads nothing.
+             --lane <name>  scope either of the above to one lane
+    post pull     [slug]    bring Sprid's status and schedule back into the registry,
+                            so 'status' is a calendar and works offline
+    post preview            one page of the whole batch: a grid, and a feed you arrow through
+    post status             one table of everything, local and remote
+    post doctor             which API, can it be reached, which channels are live
+
+  --force   push/draft again for something already done
+  --json    one JSON result; diagnostics and builder output on stderr
+  check     --platforms instagram,tiktok  override crosspost validation targets
+  register  --platforms instagram  save a post's intended validation targets
+  preview   --serve [port] a local server (needed to scrub, and for Safari)
+            --open  file:// straight into the browser · --lane <name> · --copy
+            --verify  sha every file instead of trusting its size
+  Config    sprid.config.ts in this repo says where finished media lives and what
+            has to be true of it. Registry: social/, committed.
+  Login     \`sprid login\` - one credentials file for every sprid command.
+`;
+
+
+export async function run(argv, { cwd = process.cwd() } = {}) {
+  const cmd = argv[0];
+  const rest = argv.slice(1);
+  if (!cmd || cmd === "help" || cmd === "--help") {
+    console.log(USAGE);
+    return { command: "help", usage: USAGE };
+  }
+  if (cmd === "init") {
+    await cmdInit(rest);
+    return { command: cmd };
+  }
+  const commands = { new: cmdNew, build: cmdBuild, register: cmdRegister, check: cmdCheck,
+    push: cmdPush, draft: cmdDraft, preview: cmdPreview, doctor: cmdDoctor, sync: cmdSync,
+    pull: cmdPull, status: cmdStatus };
+  if (!commands[cmd]) throw new Error(`Unknown command "${cmd}".${USAGE}`);
+  const cfg = await loadConfig(cwd);
+  const details = await commands[cmd](cfg, rest);
+  return { command: cmd, account: cfg.account, posts: allManifests(cfg), ...details };
+}