@sprid/cli 1.2.3 → 1.2.5

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 sprid follows semver: a breaking change to a command's arguments, its output
 shape or its exit codes is a major release.
 
+## 1.2.5 - 2026-10-12
+
+- `sprid docs chat` carries the updated chat guide: an agent creates a missing content account itself with `create_content_account`, and asks whether the app has users before offering analytics and revenue connections.
+
+## 1.2.4 - 2026-10-11
+
+- `sprid post sync` no longer reports a post as synced when its new media never reached Sprid. A file rebuilt since `register`, or a post whose checks are not passing, is now listed as not synced with the step that fixes it, and the command exits 1. `draft` also reads each slide back and says so when Sprid is still holding the old file.
+
 ## 1.2.3 - 2026-10-08
 
 - `sprid screenshots` carries @sprid/shots 0.2.2: bounded device commands, retries for transient capture errors, and Android cold-boot recovery for capture hooks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sprid/cli",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "The Sprid command line: connect your app, review results, prepare posts and store screenshots, and release mobile apps.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",

package/src/docs/guides.generated.mjs

@@ -1665,8 +1665,8 @@ export const CONTENT_GUIDES = [
     "title": "Use Sprid in chat",
     "summary": "Take an app from setup to a reviewed post and confirmed delivery using only your chat app and a browser. No CLI or installed skills needed.",
     "url": "https://sprid.studio/docs/chat",
-    "markdown": "# Use Sprid in chat\n\n**What this guide does:** Take an app from setup to a reviewed post and confirmed delivery using only your chat app and a browser. No CLI or installed skills needed.\n\nYou tell the agent what you want; it handles the tool calls below. The tool names are here so the agent knows the order. Setup should only ask for the connection the current task needs.\n\n## Connect Sprid\n\nChoose your chat at `https://sprid.studio/start#chat` and follow its steps. Your chat may call this an app, connector or integration. The address is `https://api.sprid.studio/api/mcp?surface=core`. Sign in to Sprid and authorize the right workspace.\n\nAgent: when available, start with `get_marketing_plan` and reuse its prepared work and next step rather than starting over. Discovery can start from a website or store URL, with no social account.\n\n## Pick the app and account\n\nAgent: call `get_capabilities`, then `list_apps` and `list_accounts`, and reuse what exists. If the app is missing, get its description or website/store URL, confirm it and create it with `upsert_app_profile`. A content account owns voice and media; a channel is one exact social destination. Never pick a handle just because it is first in a list. A missing account is created in the dashboard.\n\n## Connect a destination or data source\n\n- **Social channel:** `get_documentation` with the platform name, then `connect_channel`. The person opens the returned link and approves in the browser; `channel_status` confirms the saved result.\n- **Store or analytics:** the person enters identifiers and the key in the secure form at `https://app.sprid.studio/settings/app-profiles`. Credentials never go in chat, tool arguments or reports. A saved-key indicator only proves configuration; `get_marketing_review` does a live read.\n\n## Bring images or a finished video\n\nDraft copy in the chat, in the account’s voice. No extra model key needed.\n\nIf the chat exposes the attached files, pass them to `import_assets`: each file has `download_url` and `file_id`, optionally `mime_type` and `file_name`. Public HTTPS URLs and existing `{kind, id}` library references also work. Limits: PNG, JPEG, WebP or finished MP4, up to 32 MiB each. Each position reports on its own; retry the missing ones before building the post. Files are copied to the account and deduplicated by bytes; temporary download URLs are not kept.\n\nA `sandbox:` URL or local path can’t be fetched. For an image the chat generated, use the existing file if the host exposes it (not verified for every host); otherwise download it and use the browser upload. Never ask the agent to recreate an image or transcribe binary data.\n\n**Fallback: browser upload.** Call `create_upload_session` with the account and a new UUID `requestId`. The person opens the link and picks the files. Then read `get_studio_job` with the returned ID; its result keys are zero-based positions. The same session and asset IDs work from any other chat. No image-generation charge.\n\n## Create and review the post\n\nCall `create_post` with a new UUID `requestId`, the account, ordered `{kind, id}` assets, captions and aspect ratio. Reuse the same ID and inputs if a response is lost.\n\n- `presentation: \"finished\"` keeps artwork as-is: no text overlay, no added music. Images fit inside the canvas, which can add margins.\n- `presentation: \"editable\"` allows `text` and `subtitle` on image slides.\n- One finished video becomes one reel. Never mix a video with image slides.\n\nEdit with `update_post` (captions) and `update_slides` (slides). Call `preview_post` and check every slide or the video: captions, order, crop, legibility. It returns a small image of each slide for the agent to look at and an embedded preview for the person; a chat without embedded apps still shows the images. A preview is not approval to publish.\n\nAgent: show the person the preview, and link every post you mention with the `links` the tools return, as a Markdown link on its ref or title: `links.review` when the ask is to approve or schedule, `links.editor` when it is to change something. Never draw the slides in your own widget or artifact: those sandboxes block Sprid's media host and the images show broken.\n\n## Make a reel from photos or text\n\nCheck `get_capabilities` for hosted creation first. `create_reel` takes ordered scenes (`imageId`, `text`, `durationMs`), up to 120 seconds, and makes a silent MP4. It costs 3 Sprid credits per started render minute, or uses the plan allowance: check `spend_status`, tell the person, and get their go-ahead before sending `confirmed: true`. Save the job ID and read `get_studio_job`. Retrying with the same ID never starts a second render; a stopped job reports `needs_attention` instead of charging again.\n\nTo turn an existing post's slides into a video instead, use its own video: `get_video_capabilities`, then `get_post_video` and `edit_post_video` for transitions and motion, and `update_post {outputs}` for which destinations get it. Rendering it is metered the same way: `quote_post_video_render`, the person's go-ahead, then `render_post_video` with `confirmed: true`. Schedule a video destination with the render's `videoRenderId`.\n\nApp captures, simulator recordings and your own build scripts run outside remote MCP. Upload their finished files.\n\n## Approve and confirm delivery\n\nPublishing and scheduling require the person's approval of the preview and intended destinations. The browser review link remains available for picking channels, time and platform options.\n\nTikTok requires an explicit `postMode`; nothing defaults to a direct post or a draft:\n\n- `MEDIA_UPLOAD` sends the media to the creator's TikTok inbox. They finish the post in TikTok; report it as a draft.\n- `DIRECT_POST` requires `privacyLevel`, `disableComment`, `disableDuet`, `disableStitch`, `yourBrandToggle`, `brandedContentToggle` and `confirmed: true` in `options.tiktok`. Fetch fresh choices with `list_connections {includeTikTokCreatorInfo: true}` and show the creator identity, media and caption. The person chooses every setting for this post. Photo posts use `disableDuet: true` and `disableStitch: true`; comments respect the creator's restriction. Branded content cannot use `SELF_ONLY`.\n\nBefore sending `confirmed: true`, get the person's approval of this exact post and their agreement to TikTok's [Music Usage Confirmation](https://www.tiktok.com/legal/page/global/music-usage-confirmation/en), plus the [Branded Content Policy](https://www.tiktok.com/legal/page/global/bc-policy/en) for branded content. That flag is a caller's attestation, not proof of a click in TikTok's prescribed UI. Never invent choices or carry usual preferences into a new post. If choices are missing, open the returned `approvalUrl` for the person to answer in Sprid.\n\nAn approval covers the version the person saw. If you edit a scheduled direct post afterwards, the edit's result carries `tiktokApproval`: the scheduled post will not publish as it is. Show the person the change and the settings in its `rebook` call, ask whether to post this version, and only after they agree call `rebook` with `options.tiktok.confirmed: true` added. `post_queue` returns the same call while the approval is outstanding.\n\nTikTok's published guidelines specify a privacy dropdown and posting controls. Acceptance of this chat-based confirmation flow has not been verified with TikTok. Keep that distinction explicit in review submissions.\n\nAfter approval, read `post_queue`. Keep draft, scheduled, failed and delivered apart, and report delivery only with the platform receipt. Read a failure before retrying. Never repeat a publish call just because a response was lost.\n\nFor results, read `get_documentation` for `marketing-review`. Keep the same app, account and post IDs across clients. `next_actions` gives the next step; an empty `verb` means follow its browser link.\n\n## Limits and troubleshooting\n\n- **Attachment can’t be read:** use the browser upload, not the CLI.\n- **Missing account or service:** set it up in the dashboard. Never paste credentials into chat.\n- **Hosted creation:** check `get_capabilities` before promising it. Store screenshots and store releases are local unless it reports otherwise.\n- **File transfer:** whether a host exposes uploaded or generated files has to be checked per host. A supported schema doesn’t prove it.\n",
-    "revision": "bcf0b60a52e82938"
+    "markdown": "# Use Sprid in chat\n\n**What this guide does:** Take an app from setup to a reviewed post and confirmed delivery using only your chat app and a browser. No CLI or installed skills needed.\n\nYou tell the agent what you want; it handles the tool calls below. The tool names are here so the agent knows the order. Setup should only ask for the connection the current task needs.\n\n## Connect Sprid\n\nChoose your chat at `https://sprid.studio/start#chat` and follow its steps. Your chat may call this an app, connector or integration. The address is `https://api.sprid.studio/api/mcp?surface=core`. Sign in to Sprid and authorize the right workspace.\n\nAgent: once the app exists, start with `get_marketing_plan` and reuse its prepared work and next step rather than starting over. Discovery can start from a website or store URL, with no social account.\n\n## Pick the app and account\n\nAgent: call `get_capabilities`, then `list_apps` and `list_accounts`, and reuse what exists. If the app is missing, get its description or website/store URL, confirm it and create it with `upsert_app_profile`. A content account owns voice and media; a channel is one exact social destination. Never pick a handle just because it is first in a list. If the app has no account, ask what to call it and create it with `create_content_account`.\n\nThen ask whether the app has users yet. If it does, offer the analytics and revenue connections `next_actions` lists first: each link opens Sprid’s secure form, and the first recommendation then reads real numbers. If it has none yet, go on to the first post; connecting stays optional.\n\n## Connect a destination or data source\n\n- **Social channel:** `get_documentation` with the platform name, then `connect_channel`. The person opens the returned link and approves in the browser; `channel_status` confirms the saved result.\n- **Store or analytics:** the person enters identifiers and the key in the secure form at `https://app.sprid.studio/settings/app-profiles`. Credentials never go in chat, tool arguments or reports. A saved-key indicator only proves configuration; `get_marketing_review` does a live read.\n\n## Bring images or a finished video\n\nDraft copy in the chat, in the account’s voice. No extra model key needed.\n\nIf the chat exposes the attached files, pass them to `import_assets`: each file has `download_url` and `file_id`, optionally `mime_type` and `file_name`. Public HTTPS URLs and existing `{kind, id}` library references also work. Limits: PNG, JPEG, WebP or finished MP4, up to 32 MiB each. Each position reports on its own; retry the missing ones before building the post. Files are copied to the account and deduplicated by bytes; temporary download URLs are not kept.\n\nA `sandbox:` URL or local path can’t be fetched. For an image the chat generated, use the existing file if the host exposes it (not verified for every host); otherwise download it and use the browser upload. Never ask the agent to recreate an image or transcribe binary data.\n\n**Fallback: browser upload.** Call `create_upload_session` with the account and a new UUID `requestId`. The person opens the link and picks the files. Then read `get_studio_job` with the returned ID; its result keys are zero-based positions. The same session and asset IDs work from any other chat. No image-generation charge.\n\n## Create and review the post\n\nCall `create_post` with a new UUID `requestId`, the account, ordered `{kind, id}` assets, captions and aspect ratio. Reuse the same ID and inputs if a response is lost.\n\n- `presentation: \"finished\"` keeps artwork as-is: no text overlay, no added music. Images fit inside the canvas, which can add margins.\n- `presentation: \"editable\"` allows `text` and `subtitle` on image slides.\n- One finished video becomes one reel. Never mix a video with image slides.\n\nEdit with `update_post` (captions) and `update_slides` (slides). Call `preview_post` and check every slide or the video: captions, order, crop, legibility. It returns a small image of each slide for the agent to look at and an embedded preview for the person; a chat without embedded apps still shows the images. A preview is not approval to publish.\n\nAgent: show the person the preview, and link every post you mention with the `links` the tools return, as a Markdown link on its ref or title: `links.review` when the ask is to approve or schedule, `links.editor` when it is to change something. Never draw the slides in your own widget or artifact: those sandboxes block Sprid's media host and the images show broken.\n\n## Make a reel from photos or text\n\nCheck `get_capabilities` for hosted creation first. `create_reel` takes ordered scenes (`imageId`, `text`, `durationMs`), up to 120 seconds, and makes a silent MP4. It costs 3 Sprid credits per started render minute, or uses the plan allowance: check `spend_status`, tell the person, and get their go-ahead before sending `confirmed: true`. Save the job ID and read `get_studio_job`. Retrying with the same ID never starts a second render; a stopped job reports `needs_attention` instead of charging again.\n\nTo turn an existing post's slides into a video instead, use its own video: `get_video_capabilities`, then `get_post_video` and `edit_post_video` for transitions and motion, and `update_post {outputs}` for which destinations get it. Rendering it is metered the same way: `quote_post_video_render`, the person's go-ahead, then `render_post_video` with `confirmed: true`. Schedule a video destination with the render's `videoRenderId`.\n\nApp captures, simulator recordings and your own build scripts run outside remote MCP. Upload their finished files.\n\n## Approve and confirm delivery\n\nPublishing and scheduling require the person's approval of the preview and intended destinations. The browser review link remains available for picking channels, time and platform options.\n\nTikTok requires an explicit `postMode`; nothing defaults to a direct post or a draft:\n\n- `MEDIA_UPLOAD` sends the media to the creator's TikTok inbox. They finish the post in TikTok; report it as a draft.\n- `DIRECT_POST` requires `privacyLevel`, `disableComment`, `disableDuet`, `disableStitch`, `yourBrandToggle`, `brandedContentToggle` and `confirmed: true` in `options.tiktok`. Fetch fresh choices with `list_connections {includeTikTokCreatorInfo: true}` and show the creator identity, media and caption. The person chooses every setting for this post. Photo posts use `disableDuet: true` and `disableStitch: true`; comments respect the creator's restriction. Branded content cannot use `SELF_ONLY`.\n\nBefore sending `confirmed: true`, get the person's approval of this exact post and their agreement to TikTok's [Music Usage Confirmation](https://www.tiktok.com/legal/page/global/music-usage-confirmation/en), plus the [Branded Content Policy](https://www.tiktok.com/legal/page/global/bc-policy/en) for branded content. That flag is a caller's attestation, not proof of a click in TikTok's prescribed UI. Never invent choices or carry usual preferences into a new post. If choices are missing, open the returned `approvalUrl` for the person to answer in Sprid.\n\nAn approval covers the version the person saw. If you edit a scheduled direct post afterwards, the edit's result carries `tiktokApproval`: the scheduled post will not publish as it is. Show the person the change and the settings in its `rebook` call, ask whether to post this version, and only after they agree call `rebook` with `options.tiktok.confirmed: true` added. `post_queue` returns the same call while the approval is outstanding.\n\nTikTok's published guidelines specify a privacy dropdown and posting controls. Acceptance of this chat-based confirmation flow has not been verified with TikTok. Keep that distinction explicit in review submissions.\n\nAfter approval, read `post_queue`. Keep draft, scheduled, failed and delivered apart, and report delivery only with the platform receipt. Read a failure before retrying. Never repeat a publish call just because a response was lost.\n\nFor results, read `get_documentation` for `marketing-review`. Keep the same app, account and post IDs across clients. `next_actions` gives the next step; an empty `verb` means follow its browser link.\n\n## Limits and troubleshooting\n\n- **Attachment can’t be read:** use the browser upload, not the CLI.\n- **Missing account or service:** set it up in the dashboard. Never paste credentials into chat.\n- **Hosted creation:** check `get_capabilities` before promising it. Store screenshots and store releases are local unless it reports otherwise.\n- **File transfer:** whether a host exposes uploaded or generated files has to be checked per host. A supported schema doesn’t prove it.\n",
+    "revision": "73520c8ba4e3e270"
   },
   {
     "id": "local",

package/src/post/cli.mjs

@@ -384,6 +384,14 @@ const fill = (tpl, slug) => tpl.replaceAll("<slug>", slug);
 const kindOf = (lane) => lane.kind ?? (lane.slides ? "carousel" : "reel");
 const isComposed = (x) => (x?.kind ?? (x?.slides ? "carousel" : "reel")) === "composed";
 
+/** What the media files hash to right now, in the manifest's sha shape. Null if any is missing. */
+function diskSha(cfg, m) {
+  const files = (m.kind ?? "reel") === "carousel" ? (m.slides ?? []).map((sl) => sl.file) : [m.source];
+  const paths = files.map((f) => (f ? resolve(cfg.root, f) : null));
+  if (paths.some((f) => !f || !existsSync(f))) return null;
+  return paths.map(sha256).join(",");
+}
+
 /** 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;
@@ -1561,9 +1569,14 @@ async function cmdPush(cfg, argv) {
   );
   if (!targets.length) return console.log("\n  nothing to push (everything is already in Sprid)\n");
 
+  // **What was refused is returned, not only printed.** `sync` calls this and
+  // used to count a slug as synced whatever happened here, so a refused upload
+  // reported "1 synced" while the draft kept the old file.
+  const pushed = [], refused = [];
   for (const m of targets) {
     if (!checksPass(m)) {
       console.log(`  ${C.warn("skip")}  ${m.slug} ${C.dim("- checks not passing, run `sprid post check`")}`);
+      refused.push({ slug: m.slug, why: "checks not passing - run `sprid post check`" });
       continue;
     }
     // **A composed post has nothing here to upload.** Its pixels are the
@@ -1574,18 +1587,21 @@ async function cmdPush(cfg, argv) {
       continue;
     }
     if ((m.kind ?? "reel") === "carousel") {
-      await pushCarousel(cfg, m);
+      const why = await pushCarousel(cfg, m);
+      (why ? refused : pushed).push(why ? { slug: m.slug, why } : m.slug);
       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`)}`);
+      refused.push({ slug: m.slug, why: `${m.source} is not on disk` });
       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")}`);
+      refused.push({ slug: m.slug, why: "the file changed since `register` - run `register`, then `check`" });
       continue;
     }
 
@@ -1633,9 +1649,11 @@ async function cmdPush(cfg, argv) {
     // 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);
+    pushed.push(m.slug);
     console.log(`  ${C.ok("pushed")} ${m.slug.padEnd(40)} video ${videoId}`);
   }
   console.log();
+  return { pushed, refused };
 }
 
 /**
@@ -1651,12 +1669,12 @@ async function pushCarousel(cfg, m) {
   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;
+    return `${missing.length} slide(s) not on disk`;
   }
   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;
+    return `${changed.length} slide(s) changed since \`register\` - run \`register\`, then \`check\``;
   }
 
   const imageIds = [];
@@ -1699,6 +1717,7 @@ async function pushCarousel(cfg, m) {
   };
   writeManifest(cfg, m);
   console.log(`  ${C.ok("pushed")} ${m.slug.padEnd(40)} ${imageIds.length} images`);
+  return null;
 }
 
 /** A 400px-wide copy, or null if ffmpeg will not make one. */
@@ -1725,6 +1744,7 @@ async function cmdDraft(cfg, argv) {
   );
   if (!targets.length) return console.log("\n  nothing to draft (push first, or everything is drafted)\n");
 
+  const drafted = [], refused = [];
   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
@@ -1734,6 +1754,7 @@ async function cmdDraft(cfg, argv) {
     // preference.
     if (!checksPass(m)) {
       console.log(`  ${C.warn("skip")}  ${m.slug} ${C.dim("- checks not passing, run `sprid post check`")}`);
+      refused.push({ slug: m.slug, why: "checks not passing - run `sprid post check`" });
       continue;
     }
     const caption = existsSync(captionPath(cfg, m.slug))
@@ -1858,8 +1879,16 @@ async function cmdDraft(cfg, argv) {
     // 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);
+    const back = await api(cfg, "GET", `/posts/${post.id}`);
+    const dropped = verifyDraft(back, wanted);
     for (const [field, why] of dropped) console.log(`  ${C.bad("dropped")} ${m.slug.padEnd(40)} ${field} - ${why}`);
+    // **The media is read back too.** Same reason as the fields above: the
+    // slide PATCH answering 200 is not proof the post now shows the new file.
+    const mediaDrift = composed ? null : slideMediaDrift(back, carousel ? m.sprid.imageIds ?? [] : [m.sprid.videoId], carousel);
+    if (mediaDrift) {
+      console.log(`  ${C.bad("media")}   ${m.slug.padEnd(40)} ${mediaDrift}`);
+      refused.push({ slug: m.slug, why: mediaDrift });
+    }
 
     m.sprid = {
       ...m.sprid,
@@ -1872,12 +1901,28 @@ async function cmdDraft(cfg, argv) {
       dropped: dropped.length ? dropped.map(([f]) => f) : null,
     };
     writeManifest(cfg, m);
+    if (mediaDrift) continue;
+    drafted.push(m.slug);
     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`);
+  return { drafted, refused };
+}
+
+/**
+ * Whether the post's slides carry the files the registry pushed, in order.
+ * Null when they do; otherwise what a person needs to read.
+ */
+export function slideMediaDrift(back, ids, carousel) {
+  const slides = [...(back.slides ?? [])].sort((a, b) => a.position - b.position);
+  const held = slides.map((sl) => (carousel ? sl.imageId : sl.videoId) ?? null);
+  if (held.length === ids.length && held.every((id, i) => id === ids[i])) return null;
+  return carousel
+    ? `Sprid's slides hold images ${held.join(",") || "none"}, not the pushed ${ids.join(",")}`
+    : `Sprid's slide holds video ${held[0] ?? "none"}, not the pushed ${ids[0]}`;
 }
 
 /**
@@ -2007,7 +2052,18 @@ async function cmdSync(cfg, argv) {
       : (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;
+    // **The registry's sha is not the file.** A rebuild that was never
+    // re-registered leaves the manifest agreeing with what was pushed, and sync
+    // answered "in sync" while the drafts held the old video. So the bytes on
+    // disk are hashed too, and a mismatch is reported as the step it needs.
+    // A file no longer on disk proves nothing either way, so it falls back to
+    // the record: scratch builds get cleaned up after a push.
+    const onDisk = isComposed(m) ? null : diskSha(cfg, m);
+    const media = isComposed(m)
+      ? false
+      : onDisk != null && onDisk !== localSha
+        ? "unregistered"
+        : pushedSha == null ? "unknown" : pushedSha !== localSha;
     const caption = (m.post?.captionSha ?? null) !== (m.sprid.captionShaAtDraft ?? null);
     // The Pin's board, link and words. Unrecorded counts as changed, same as
     // media: a record that cannot say what was sent cannot say it is current.
@@ -2024,7 +2080,10 @@ async function cmdSync(cfg, argv) {
   console.log(`\n  ${C.bold(execute ? "syncing" : "would sync")}  ${plan.length} of ${all.length}\n`);
   for (const { m, media, caption, title, pin, unreadable } of plan) {
     const what = [
-      media === "unknown" ? C.warn("media (never recorded, assumed stale)") : media ? C.warn("media") : null,
+      media === "unregistered"
+        ? C.bad("media (file on disk changed since `register`)")
+        : media === "unknown" ? C.warn("media (never recorded, assumed stale)") : media ? C.warn("media") : null,
+      !checksPass(m) ? C.bad("checks not passing") : null,
       caption ? C.warn("caption") : null,
       title ? C.warn(unreadable ? "title (could not read Sprid's, assumed stale)" : "title") : null,
       pin ? C.warn("pin") : null,
@@ -2038,7 +2097,20 @@ async function cmdSync(cfg, argv) {
 
   console.log();
   let done = 0, skipped = 0;
+  const failed = [];
   for (const { m, media } of plan) {
+    // Refused before touching Sprid: pushing or drafting would either do
+    // nothing or re-send the old file, and both used to be counted as synced.
+    if (media === "unregistered") {
+      console.log(`  ${C.bad("not synced")} ${m.slug.padEnd(36)} ${C.dim("file changed since `register` - run `register`, then `check`")}`);
+      failed.push({ slug: m.slug, why: "file changed since `register`" });
+      continue;
+    }
+    if (!checksPass(m)) {
+      console.log(`  ${C.bad("not synced")} ${m.slug.padEnd(36)} ${C.dim("checks not passing - run `check`")}`);
+      failed.push({ slug: m.slug, why: "checks not passing" });
+      continue;
+    }
     // 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.
@@ -2059,13 +2131,31 @@ async function cmdSync(cfg, argv) {
       skipped++;
       continue;
     }
-    if (media) await cmdPush(cfg, [m.slug, "--force"]);
+    if (media) {
+      const pushed = await cmdPush(cfg, [m.slug, "--force"]);
+      if (!pushed?.pushed.includes(m.slug)) {
+        const why = pushed?.refused.find((r) => r.slug === m.slug)?.why ?? "nothing was uploaded";
+        console.log(`  ${C.bad("not synced")} ${m.slug.padEnd(36)} ${C.dim(why)}`);
+        failed.push({ slug: m.slug, why });
+        continue;
+      }
+    }
     // Re-read: push rewrote the manifest, and draft has to send the new videoId.
-    await cmdDraft(cfg, [readManifest(cfg, m.slug).slug, "--force"]);
+    const drafted = await cmdDraft(cfg, [readManifest(cfg, m.slug).slug, "--force"]);
+    if (!drafted?.drafted.includes(m.slug)) {
+      const why = drafted?.refused.find((r) => r.slug === m.slug)?.why ?? "the draft was not updated";
+      console.log(`  ${C.bad("not synced")} ${m.slug.padEnd(36)} ${C.dim(why)}`);
+      failed.push({ slug: m.slug, why });
+      continue;
+    }
     done++;
   }
-  console.log(`  ${done} synced, ${skipped} left alone\n`);
-  return { execute, synced: done, skipped, plan: plan.map(({ m, ...change }) => ({ slug: m.slug, ...change })) };
+  console.log(`  ${done} synced, ${skipped} left alone${failed.length ? `, ${C.bad(`${failed.length} not synced`)}` : ""}\n`);
+  return {
+    exitCode: failed.length ? 1 : 0,
+    execute, synced: done, skipped, failed,
+    plan: plan.map(({ m, ...change }) => ({ slug: m.slug, ...change })),
+  };
 }
 
 /**