@sprid/cli 0.1.19 → 1.0.2

package/CHANGELOG.md

@@ -3,6 +3,32 @@
 sprid follows semver: a breaking change to a command's arguments, its output
 shape or its exit codes is a major release.
 
+## 1.0.2 - 2026-10-01
+
+- Local video previews include a safe-zone toggle using the editor's approximate
+  bottom and right interface bands. Guides follow the actual picture through
+  letterboxing, resizing and feed view. They never appear in exported videos.
+- Screen-reel captions stay above the bottom band and left of the action rail,
+  including their entrance animation. Oversized caption cards fail with a
+  readable error instead of drawing under the platform interface.
+
+## 1.0.1 - 2026-10-01
+
+- Local post previews use a compact artwork grid and a caption comparison list.
+  Clicking a post opens its media beside the caption, with icon controls and
+  file details on demand. Search and lane filters also scope post navigation.
+- The preview follows the system theme, with a light/dark switch. Needs attention
+  includes missing files and captions, failed checks, and changed files or captions.
+  Carousel controls, keyboard navigation and the feed view remain available offline.
+- A sound toggle above the grid also controls hover playback. The sun icon’s
+  diagonal rays render correctly.
+- Feed previews preload every visible post plus one beyond each edge, and
+  keep outgoing video frames until scrolling stops.
+
+## 1.0.0 - 2026-09-30
+
+- Breaking: Sprid record IDs are UUIDs. Post and review references remain accepted. Incremental IDs are refused.
+
 ## 0.1.19 - 2026-09-30
 
 - `sprid docs chat` uses the consolidated post and slide tools. Asset creation

package/README-post.md

@@ -405,21 +405,27 @@ bunx @sprid/cli post preview --open       # file://, fine for watching, cannot s
 bunx @sprid/cli post preview --lane collage --copy --out ~/Desktop/reels
 ```
 
-It reads the registry and nothing else, so it is the same command in every repo,
-and it writes one disposable HTML file with **two views**, because a batch and a
-post are two different questions:
-
-- **Grid.** Everything at once, small. Hover plays a reel and walks a deck, the filter matches slug and
-  caption, and a card carries the caption itself and nothing derived from it -
-  the length, the loudness, the check result and the Sprid state ride along as
-  badges. This is where you see repetition, an outlier, a caption that ran long.
-- **Feed.** One post at reading size with its caption under it, arrow keys
-  between them, `m` for sound, `esc` back. A carousel advances by itself at
-  reading pace (`space` stops it, `[` `]` step it, the dots say how many are
-  left), because the question a batch review asks of a deck is whether it holds
-  together as one set, and that is a thing you watch rather than click through. It is the only view that answers
-  *would I stop on this*, because it is the shape a reader meets. Each reel has
-  its own `#slug` address, so a position is a link.
+The video viewer has a **Safe zones** toggle: approximate bottom 20% and right 14% from 38% down to the bottom band. Hatching follows the video picture, including letterboxing; keep captions and important graphics outside it. This guide is not a guarantee of platform UI placement. Screen-reel captions use the same margins when rendered.
+
+It reads the local registry and writes one self-contained HTML file. The preview
+uses Sprid’s paper colours, follows the system theme, and works offline.
+
+- **Grid.** A compact picture grid. Hover plays a reel or walks through a deck.
+  The sound button above the grid, or `m`, unmutes hover playback.
+  Click opens the post with its full caption beside the media, copy controls,
+  and file details. Missing files remain visible.
+- **List.** One row per post, with the caption’s opening line, lane, length and
+  check state. Use it to compare captions across a batch.
+- **Feed.** One post at reading size, with its caption underneath. Swipe sideways
+  or use arrow keys between posts, `m` for sound, and `esc` to return. Carousels
+  advance automatically; `space` pauses, `[` and `]` step slides manually.
+  Visible media and one extra post beyond each edge preload. Outgoing videos
+  stay loaded until scrolling stops.
+
+Search matches the local ID, lane and caption. The lane selector and
+**Needs attention** filter also apply to navigation between posts. Needs attention
+includes failed checks, missing media or captions, and files or captions changed
+since their saved record. Every post has a `#slug` address.
 
 **`--serve` watches and reloads.** The registry, the lanes' media directories
 and this package's own source are all watched; a change rebuilds the page and

package/README.md

@@ -153,7 +153,7 @@ Use `sprid use <slug>` to save a choice; it also works with an environment token
 
 ```json
 { "apiUrl": "https://api.sprid.studio", "token": "sprd_…", "tokenId": 7,
-  "workspace": { "id": 1, "slug": "example-team", "name": "Example Team", "tier": "starter" },
+  "workspace": { "id": "9cc2a060-e371-4df3-8432-88dcaa207628", "slug": "example-team", "name": "Example Team", "tier": "starter" },
   "email": "you@example.com" }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sprid/cli",
-  "version": "0.1.19",
+  "version": "1.0.2",
   "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",
@@ -38,8 +38,8 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@sprid/shots": "0.1.2",
-    "@sprid/release": "0.1.2"
+    "@sprid/shots": "0.1.3",
+    "@sprid/release": "1.0.0"
   },
   "publishConfig": {
     "access": "public"

package/src/commands/ads.mjs

@@ -5,7 +5,7 @@
 
 import { UsageError } from "../args.mjs";
 import { C, OK } from "../format.mjs";
-import { callTool, needInt, readJson, show } from "../tools.mjs";
+import { callTool, needId, readJson, show } from "../tools.mjs";
 import { confirm } from "./reviews.mjs";
 
 const USAGE = [
@@ -37,7 +37,7 @@ export async function ads(ctx) {
     return 0;
   }
   if (READS[sub]) {
-    const adSetId = needInt(arg, `sprid ads ${sub} <adSetId> --account <slug>`);
+    const adSetId = needId(arg, `sprid ads ${sub} <adSetId> --account <slug>`);
     const days = ctx.flags.days && sub !== "status" ? { days: Number(ctx.flags.days) } : {};
     show(ctx, await callTool(ctx, READS[sub], { account, adSetId, ...days }));
     return 0;
@@ -48,11 +48,11 @@ export async function ads(ctx) {
     show(ctx, await callTool(ctx, tool, { ...(await readJson(ctx, ctx.flags.file)), account }));
     return 0;
   }
-  if (sub === "launch") return launch(ctx, account, needInt(arg, "sprid ads launch <adSetId> --account <slug> [--yes]"));
-  if (sub === "budget") return budget(ctx, account, needInt(arg, "sprid ads budget <adSetId> --daily-cents N --account <slug> [--yes]"));
-  if (sub === "pause") return pause(ctx, account, needInt(arg, "sprid ads pause <adSetId> --account <slug> [--yes]"));
+  if (sub === "launch") return launch(ctx, account, needId(arg, "sprid ads launch <adSetId> --account <slug> [--yes]"));
+  if (sub === "budget") return budget(ctx, account, needId(arg, "sprid ads budget <adSetId> --daily-cents N --account <slug> [--yes]"));
+  if (sub === "pause") return pause(ctx, account, needId(arg, "sprid ads pause <adSetId> --account <slug> [--yes]"));
   if (sub === "close") {
-    show(ctx, await callTool(ctx, "close_ad_set", { account, adSetId: needInt(arg, "sprid ads close <adSetId> --account <slug>") }));
+    show(ctx, await callTool(ctx, "close_ad_set", { account, adSetId: needId(arg, "sprid ads close <adSetId> --account <slug>") }));
     return 0;
   }
   throw new UsageError(USAGE);

package/src/commands/family.mjs

@@ -1,3 +1,4 @@
+import { needId } from "../tools.mjs";
 import { readFileSync } from "node:fs";
 import { extname, resolve } from "node:path";
 import { UsageError } from "../args.mjs";
@@ -15,12 +16,7 @@ function objectFile(ctx) {
     throw new UsageError("Expected a JSON object.");
   return data;
 }
-function positiveId(raw) {
-  const id = Number(raw);
-  if (!Number.isInteger(id) || id <= 0)
-    throw new UsageError("Pass a positive account ID.");
-  return id;
-}
+const positiveId = (raw) => needId(raw, "Pass an account UUID.");
 export async function apps(ctx) {
   ctx.out(await ctx.api().get("/api/app-profiles/hierarchy"));
   return 0;

package/src/commands/inbox.mjs

@@ -5,7 +5,7 @@
 
 import { UsageError } from "../args.mjs";
 import { C, OK } from "../format.mjs";
-import { callTool, listFlag } from "../tools.mjs";
+import { callTool, listFlag, needId } from "../tools.mjs";
 import { confirm, stars, truncate } from "./reviews.mjs";
 
 const USAGE = "sprid inbox [--view needs_you|all|done] [--kind all|comment|review] [--accounts a,b] [--app <slug>] [--limit N] | draft <commentId> | reply <commentId> --text \"…\" [--yes] | done|flag|reopen <c:id|r:id>";
@@ -58,11 +58,11 @@ function render(item) {
   return lines.join("\n");
 }
 
-/** `c:12` or a bare `12` is a comment; `r:41` is a store review. */
+/** `c:UUID` or a bare UUID is a comment; `r:UUID` is a store review. */
 function parseRef(ref, usage) {
-  const m = String(ref ?? "").match(/^(?:(c|r):)?([1-9]\d*)$/i);
+  const m = String(ref ?? "").match(/^(?:(c|r):)?([0-9a-f-]+)$/i);
   if (!m) throw new UsageError(usage);
-  return { kind: (m[1] ?? "c").toLowerCase() === "r" ? "review" : "comment", id: Number(m[2]) };
+  return { kind: (m[1] ?? "c").toLowerCase() === "r" ? "review" : "comment", id: needId(m[2], usage) };
 }
 
 async function draft(ctx, ref) {

package/src/commands/init.mjs

@@ -102,12 +102,12 @@ export async function init(ctx) {
   }
 
   const wid = await ctx.workspaceId();
-  if (local?.data.workspaceId && Number(local.data.workspaceId) !== Number(wid))
+  if (local?.data.workspaceId && local.data.workspaceId !== wid)
     throw new UsageError(`This repo belongs to workspace ${local.data.workspaceId}. Use --workspace ${local.data.workspaceId}; do not register it in a different workspace.`);
   const profiles = await listProfiles(ctx, wid);
   const pinnedId = local?.data.appId;
   const existing = pinnedId
-    ? profiles.find(p => Number(p.id) === Number(pinnedId))
+    ? profiles.find(p => p.id === pinnedId)
     : profiles.find(p => input.slug && p.slug === input.slug);
   if (pinnedId && !existing) throw new UsageError(`App ${pinnedId} is unavailable in workspace ${wid}. Restore access before registering again.`);
   // A server rename does not change the app this repo is attached to.

package/src/commands/misc.mjs

@@ -1,3 +1,4 @@
+import { needRef } from "../tools.mjs";
 // open / invite / upgrade: deep links and the two workspace verbs.
 
 import { UsageError } from "../args.mjs";
@@ -13,8 +14,7 @@ export async function open(ctx) {
       path = "/";
       break;
     case "post": {
-      const id = Number(arg);
-      if (!Number.isInteger(id) || id <= 0) throw new UsageError("sprid open post <id>");
+      const id = needRef(arg, "sprid open post <UUID|ref>");
       path = `/p/${id}`;
       break;
     }

package/src/commands/pinterest.mjs

@@ -92,7 +92,7 @@ export async function pinterest(ctx) {
     if ((value.description?.length ?? 0) > 800) throw new UsageError("Pinterest description exceeds 800 characters.");
     if ((value.altText?.length ?? 0) > 500) throw new UsageError("Pinterest alt text exceeds 500 characters.");
     const updated = await ctx.api().patch(`/api/posts/${ref}`, { pinterestOptions: value });
-    if (ctx.json) ctx.out({ ok: true, postId: Number(ref), pinterestOptions: updated.pinterestOptions });
+    if (ctx.json) ctx.out({ ok: true, postId: updated.id, pinterestOptions: updated.pinterestOptions });
     else ctx.print(`  ${C.ok("✓")} Pinterest details saved on post ${ref}. Review the visual and schedule in Sprid.`);
     return 0;
   }

package/src/commands/plan.mjs

@@ -139,7 +139,7 @@ export async function plan(ctx) {
     const original = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
     if (input.artifact?.body !== original) throw new UsageError('The proposed artifact must contain the original saved text exactly. Revise the shared artifact after importing.');
     const current = await ctx.api().get(`${base}?${scoped}`);
-    const wid = Number(new URLSearchParams(scoped).get('workspaceId'));
+    const wid = new URLSearchParams(scoped).get('workspaceId');
     if ((state.appId && state.appId !== current.appProfile.id) || (state.workspaceId && state.workspaceId !== wid) || (state.apiUrl && state.apiUrl !== ctx.auth().apiUrl)) throw new UsageError('The local task belongs to another app, workspace or server.');
     const response = await ctx.api().raw('POST', `${base}/actions/prepare?${scoped}`, { ...input, idempotencyKey: `local-task:${state.key}` });
     if (response.status < 200 || response.status >= 300) { ctx.out(response.data); return 1; }
@@ -149,7 +149,7 @@ export async function plan(ctx) {
   }
   if (verb === 'link-local') {
     const result = await ctx.api().get(`${base}?${scoped}`);
-    ctx.out(linkLocalTask(ctx.cwd, result, decodeURIComponent(id(ctx)), ctx.auth().apiUrl, Number(new URLSearchParams(scoped).get('workspaceId'))));
+    ctx.out(linkLocalTask(ctx.cwd, result, decodeURIComponent(id(ctx)), ctx.auth().apiUrl, new URLSearchParams(scoped).get('workspaceId')));
     return 0;
   }
   if (verb === 'get' || verb === 'export') {

package/src/commands/post-video.mjs

@@ -1,3 +1,4 @@
+import { needRef } from "../tools.mjs";
 // sprid post video <postId>             read the post's own video
 // sprid post video render <postId> ...  render it to MP4 (spends credits)
 //
@@ -13,7 +14,6 @@ import { UsageError } from "../args.mjs";
 import { C, OK } from "../format.mjs";
 import { callTool } from "../tools.mjs";
 
-const POST_REF = /^([1-9]\d*|[A-Za-z][A-Za-z0-9]{1,4}-\d+)$/;
 const READ_USAGE = "sprid post video <postId>";
 const RENDER_USAGE = "sprid post video render <postId> [--confirm] [--ceiling N] [--final]";
 
@@ -24,8 +24,7 @@ export async function postVideo(ctx) {
 }
 
 function postRef(ref, usage) {
-  if (!POST_REF.test(String(ref ?? ""))) throw new UsageError(usage);
-  return /^\d+$/.test(ref) ? Number(ref) : String(ref).toUpperCase();
+  return needRef(ref, usage);
 }
 
 /** A refused tool call answers `{ok: false, error}`; print it and fail. */

package/src/commands/publishing.mjs

@@ -1,3 +1,4 @@
+import { needRef } from "../tools.mjs";
 // sprid post schedule | publish | schedule-batch: putting a post in front of
 // an audience, through the same tools an agent calls. Publishing now is public
 // and cannot be taken back, so it asks unless --yes. A booking can be taken
@@ -14,7 +15,6 @@ import { C, OK } from "../format.mjs";
 import { callTool, listFlag, readJson, show } from "../tools.mjs";
 import { confirm } from "./reviews.mjs";
 
-const POST_REF = /^([1-9]\d*|[A-Za-z][A-Za-z0-9]{1,4}-\d+)$/;
 
 export const PUBLISHING_VERBS = ["schedule", "publish", "schedule-batch"];
 
@@ -24,8 +24,7 @@ export async function publishing(ctx) {
   const usage = verb === "publish"
     ? "sprid post publish <postId> [--platforms a,b] [--options <options.json>] [--video-render <renderId>] [--yes]"
     : "sprid post schedule <postId> (--at ISO|--next|--queue-end) [--platforms a,b] [--time HH:MM] [--shift-later] [--options <options.json>] [--video-render <renderId>]";
-  if (!POST_REF.test(String(ref ?? ""))) throw new UsageError(usage);
-  const id = /^\d+$/.test(ref) ? Number(ref) : String(ref).toUpperCase();
+  const id = needRef(ref, usage);
   const base = { id, ...(await destination(ctx)) };
   return verb === "publish" ? publish(ctx, base) : schedule(ctx, base, usage);
 }
@@ -105,7 +104,7 @@ async function scheduleBatch(ctx) {
   if (typeof ctx.flags.account !== "string" || !ids) throw new UsageError(usage);
   const args = {
     account: ctx.flags.account,
-    postIds: ids.map((v) => (/^\d+$/.test(v) ? Number(v) : v.toUpperCase())),
+    postIds: ids.map((v) => needRef(v, "Use post UUIDs or references in --ids.")),
     ...(await destination(ctx)),
     ...(typeof ctx.flags.cadence === "string" ? { cadence: ctx.flags.cadence } : {}),
     ...(listFlag(ctx.flags.times) ? { times: listFlag(ctx.flags.times) } : {}),

package/src/commands/reviews.mjs

@@ -1,3 +1,4 @@
+import { needRef } from "../tools.mjs";
 // reviews: what users wrote in the stores, the reply the workspace's model
 // drafted, and the one call that sends it. Sending is public and cannot be
 // undone on Play, so `reply` is the single interactive prompt in the CLI:
@@ -57,7 +58,7 @@ export function truncate(s, n = 200) {
 
 export function renderReview(r) {
   const date = r.reviewedAt ? String(r.reviewedAt).slice(0, 10) : "";
-  const head = `  ${stars(r.rating)}  ${r.app?.slug ?? r.appProfileId}  ${STORE_LABEL[r.source] ?? r.source}  ${date}  ${C.dim(`#${r.id}`)}`;
+  const head = `  ${stars(r.rating)}  ${r.app?.slug ?? r.appProfileId}  ${STORE_LABEL[r.source] ?? r.source}  ${date}  ${C.dim(r.ref ?? r.id)}`;
   const lines = [head];
   const text = [r.title, r.body].filter(Boolean).join(" · ");
   if (text) lines.push(`  ${truncate(text)}`);
@@ -70,17 +71,8 @@ export function renderReview(r) {
   return lines.join("\n");
 }
 
-// A review is named by its row id (41) or its ref (BND-R41); the server
-// resolves either, so the CLI only checks the shape.
-function needId(arg, usage) {
-  const id = String(arg ?? "").trim();
-  if (/^[1-9]\d*$/.test(id)) return Number(id); // --json keeps printing a number
-  if (/^[A-Za-z][A-Za-z0-9]{1,4}-[Rr]\d+$/.test(id)) return id.toUpperCase();
-  throw new UsageError(usage);
-}
-
-/** `BND-R41` as is; a bare row id as `#41`. */
-const label = (id) => (/^\d+$/.test(String(id)) ? `#${id}` : String(id));
+const needId = (arg, usage) => needRef(arg, usage, true);
+const label = (id) => String(id);
 
 async function draft(ctx, arg) {
   const id = needId(arg, "sprid reviews draft <id|ref>");

package/src/commands/status.mjs

@@ -1,3 +1,4 @@
+import { needId } from "../tools.mjs";
 import { readLocalApp } from "../profiles.mjs";
 // status / next / queue. Every line here is one field of the StatusView the
 // server computes; the web Home card and the Monday mail print the same list.
@@ -187,16 +188,14 @@ export async function next(ctx) {
 export async function queue(ctx) {
   const [sub, arg] = ctx.positionals;
   if (sub === "retry") {
-    const id = Number(arg);
-    if (!Number.isInteger(id) || id <= 0) throw usage("sprid queue retry <publishId>");
+    const id = needId(arg, "sprid queue retry <publishId>");
     const row = await ctx.api().post(`/api/publishes/${id}/retry`);
     if (ctx.json) ctx.out({ ok: true, publish: row });
     else ctx.print(`  ${C.ok(OK)} Publish ${id} is back on the queue${row?.scheduledFor ? ` for ${dayTime(row.scheduledFor)}` : ""}.`);
     return 0;
   }
   if (sub === "cancel") {
-    const id = Number(arg);
-    if (!Number.isInteger(id) || id <= 0) throw usage("sprid queue cancel <publishId>");
+    const id = needId(arg, "sprid queue cancel <publishId>");
     await ctx.api().del(`/api/publishes/${id}`);
     if (ctx.json) ctx.out({ ok: true, publishId: id });
     else ctx.print(`  ${C.ok(OK)} Booking ${id} cancelled. The post stays as it is.`);

package/src/commands/studio.mjs

@@ -1,3 +1,4 @@
+import { needRef } from "../tools.mjs";
 import { readFile, stat } from 'node:fs/promises';
 import { basename, resolve, extname } from 'node:path';
 import { randomUUID, createHash } from 'node:crypto';
@@ -13,10 +14,8 @@ export async function remotePost(ctx) {
   const [verb, ref] = ctx.positionals;
   let id = ctx.flags.id ?? ref;
   if (!['create', 'get', 'update', 'deliveries', 'handoff'].includes(verb) && !(verb === 'preview' && ctx.flags.id)) return false;
-  // The server post id (271) or its ref (BND-78); the server resolves either.
-  if (verb !== 'create' && !/^([1-9]\d*|[A-Za-z][A-Za-z0-9]{1,4}-\d+)$/.test(String(id))) throw new UsageError('Supply the server post ID or its ref, such as 271 or BND-78. Local preview slugs remain unchanged.');
+  if (verb !== 'create') id = encodeURIComponent(needRef(String(id ?? ''), 'Supply the post UUID or its reference, such as SPR-9.'));
   const api = ctx.api();
-  if (verb !== 'create') id = encodeURIComponent(String(id).toUpperCase());
   const result = verb === 'create' ? await api.post('/api/studio/posts', await payload(ctx))
     : verb === 'update' ? await api.patch(`/api/posts/${id}`, await payload(ctx))
     : verb === 'preview' ? await api.get(`/api/studio/posts/${id}/preview`)

package/src/docs/commands.mjs

@@ -29,7 +29,7 @@ export const COMMAND_GROUPS = [
     ['media', 'sprid media job <UUID>', 'Read saved upload results or creation progress without repeating the operation.'],
     ['media', 'sprid media init|build|register|check|push|preview …', 'Run the existing local media pipeline. Historical sprid post invocations remain supported.'],
     ['post', 'sprid post create --file <draft.json>', 'Create a shared draft from ordered asset references and a stable requestId. With "status": "idea" it saves an idea instead: notes, a sourceUrl and any gathered assets, before layout. Never publishes.'],
-    ['post', 'sprid post get <postId>', 'Read the shared post and its slides. Every <postId> here takes the number or the post\'s ref, such as BND-142.'],
+    ['post', 'sprid post get <postId>', 'Read the shared post and its slides. Every <postId> here takes the UUID or the post\'s ref, such as BND-142.'],
     ['post', 'sprid post update <postId> --file <changes.json>', 'Apply the existing post-update contract to a shared draft.'],
     ['post', 'sprid post preview --id <postId>', 'Preview a shared post. Without --id, historical local preview arguments are unchanged.'],
     ['post', 'sprid post deliveries <postId>', 'Read scheduled, failed and delivered publications with platform receipts.'],
@@ -104,7 +104,7 @@ export const COMMAND_GROUPS = [
     ['queue', 'sprid queue retry <publishId>', 'Retry a failed or missed publish.'],
     ['queue', 'sprid queue cancel <publishId>', 'Cancel a booking. The post itself is unchanged and can be scheduled again.'],
     ['post', 'sprid post schedule <postId> (--at ISO|--next|--queue-end) [--platforms a,b] [--time HH:MM] [--shift-later] [--options <options.json>] [--video-render <renderId>]', 'Book a post: at a time, the next free slot, or after everything already booked. --shift-later moves later bookings down a slot. A destination that goes out as the post\'s video needs --video-render, a final render of the video as it is now. TikTok goes as a draft to the TikTok inbox: {"tiktok": {"postMode": "MEDIA_UPLOAD"}} in --options. A direct TikTok post is answered and confirmed by the person on the review link the refusal prints. A Pinterest Pin needs its board and destination link saved first with sprid pinterest set.'],
-    ['post', 'sprid post schedule-batch --account <slug> --ids 1,2,3 [--cadence daily|every-other-day|weekdays] [--times 09:00] [--start YYYY-MM-DD] [--platforms a,b] [--skip-busy] [--dry-run]', 'Place a list of posts on a cadence in one call. --dry-run returns the plan without booking anything.'],
+    ['post', 'sprid post schedule-batch --account <slug> --ids SPR-9,SPR-10 [--cadence daily|every-other-day|weekdays] [--times 09:00] [--start YYYY-MM-DD] [--platforms a,b] [--skip-busy] [--dry-run]', 'Place a list of posts on a cadence in one call. --dry-run returns the plan without booking anything.'],
     ['post', 'sprid post publish <postId> [--platforms a,b] [--options <options.json>] [--video-render <renderId>] [--yes]', 'Publish now. Public and not reversible, so it asks unless --yes. Read the receipts with sprid post deliveries.'],
     ['inbox', 'sprid inbox [--view needs_you|all|done] [--kind all|comment|review] [--accounts a,b] [--app <slug>] [--intent <intent>] [--limit N]', 'Comments on posts and ads plus store reviews, as one ranked queue.'],
     ['inbox', 'sprid inbox draft <commentId> [--count N]', 'Draft replies in the account’s reply voice. Nothing is sent.'],
@@ -168,7 +168,7 @@ export const COMMAND_EXAMPLES = {
   status: ['sprid status --workspace my-team --json'],
   docs: ['sprid docs search posthog permissions', 'sprid docs posthog --offline'],
   connect: ['sprid docs posthog', 'sprid connect instagram --account myapp'],
-  post: ['sprid post create --file draft.json', 'sprid post get 123 --json', 'sprid post preview --id 123', 'sprid post check launch --deep'],
+  post: ['sprid post create --file draft.json', 'sprid post get SPR-9 --json', 'sprid post preview --id SPR-9', 'sprid post check launch --deep'],
   media: ['sprid media upload cover.jpg detail.jpg --account myapp', 'sprid media build launch'],
   'marketing-review': ['sprid marketing-review --app myapp --days 7 --json', 'sprid marketing-review capabilities --app myapp --source gsc --json'],
   ads: ['sprid ads --account myapp', 'sprid ads launch 12 --account myapp'],

package/src/docs/guides.generated.mjs

@@ -1612,8 +1612,8 @@ export const CONTENT_GUIDES = [
     "title": "Build locally and send to Sprid",
     "summary": "Build content with your own tools, upload the finished files to Sprid, and keep editing, reviewing and measuring the same posts in chat or the dashboard.",
     "url": "https://sprid.studio/docs/local",
-    "markdown": "# Build locally and send to Sprid\n\n**What this guide does:** Build content with your own tools, upload the finished files to Sprid, and keep editing, reviewing and measuring the same posts in chat or the dashboard.\n\nTwo command families: `sprid media` is local production and file transfer (`init`, `build`, `check`, `register`, `push`, `preview`, `upload`). `sprid post` works on shared posts on the server. If sign-in fails, the local result stays usable. Keep the same post and plan IDs when you move work into Sprid.\n\n## Build\n\nUse your app’s own renderer or design tools, or a built-in recipe:\n\n```sh\nsprid media init          # set up the stills or simulator-screen recipe\nsprid media build <slug>\nsprid media check <slug>\n```\n\nA TS/JS config runs local code, so only use one you trust. Native captures and binary builds need your app’s own environment. A local slug stays local; a shared preview is always `sprid post preview --id <postId>`.\n\n## Upload\n\n```sh\nsprid login\nsprid media upload slide-01.png slide-02.png --account my-account --json\n```\n\nFiles go straight to storage and come back as ordered asset IDs. PNG, JPEG, WebP and MP4, up to 32 MiB each; larger videos go through `sprid media push`. The command prints a request ID first. To resume, rerun with the same files in the same order and `--request-id <UUID>`, or read the saved result with `sprid media job <UUID>`. Don’t reuse a request ID for a different selection.\n\n## Create and review the post\n\nWrite `draft.json` with the returned IDs and a new UUID as `requestId` (keep it for retries):\n\n```json\n{\n  \"account\": \"my-account\",\n  \"requestId\": \"5e253644-d8a5-4b18-9cc9-d4d921874138\",\n  \"title\": \"A concrete moment\",\n  \"captionInstagram\": \"The caption, with hashtags at the end\",\n  \"aspectRatio\": \"4:5\",\n  \"presentation\": \"finished\",\n  \"assets\": [{ \"kind\": \"image\", \"id\": 101 }, { \"kind\": \"image\", \"id\": 102 }]\n}\n```\n\nFor a finished reel, use one asset with `kind: \"video\"`. `finished` artwork gets no overlay or music; images fit inside the canvas, so check the preview for margins.\n\n```sh\nsprid post create --file draft.json --json\nsprid post get 123 --json\nsprid post update 123 --file changes.json --json   # e.g. {\"captionInstagram\":\"Revised caption\"}\nsprid post preview --id 123 --json\nsprid post deliveries 123 --json\n```\n\nThe review link opens the same dashboard screen as from chat. To continue in chat, give it post ID `123` instead of creating another draft. Approval and platform choices stay with a person. Check delivery receipts before reporting success.\n\n## Hosted options and results\n\n- `sprid capabilities --json`: server limits and what stays local.\n- `sprid media import --file sources.json`: the same account/files/urls/assets payload as MCP `import_assets`.\n- `sprid media reel --file recipe.json`: the metered hosted reel. Payload and approval rules are in `sprid docs chat`. Poll with `sprid media job <UUID>`.\n- `sprid marketing-review`: connected evidence. `sprid docs marketing-review` covers coverage and attribution.\n\nKeys go in through CLI key-file commands or the secure Sprid forms, never a conversation.\n",
-    "revision": "9fca88d8e62aa719"
+    "markdown": "# Build locally and send to Sprid\n\n**What this guide does:** Build content with your own tools, upload the finished files to Sprid, and keep editing, reviewing and measuring the same posts in chat or the dashboard.\n\nTwo command families: `sprid media` is local production and file transfer (`init`, `build`, `check`, `register`, `push`, `preview`, `upload`). `sprid post` works on shared posts on the server. If sign-in fails, the local result stays usable. Keep the same post and plan IDs when you move work into Sprid.\n\n## Build\n\nUse your app’s own renderer or design tools, or a built-in recipe:\n\n```sh\nsprid media init          # set up the stills or simulator-screen recipe\nsprid media build <slug>\nsprid media check <slug>\n```\n\nA TS/JS config runs local code, so only use one you trust. Native captures and binary builds need your app’s own environment. A local slug stays local; a shared preview is always `sprid post preview --id <postId>`.\n\n## Upload\n\n```sh\nsprid login\nsprid media upload slide-01.png slide-02.png --account my-account --json\n```\n\nFiles go straight to storage and come back as ordered asset IDs. PNG, JPEG, WebP and MP4, up to 32 MiB each; larger videos go through `sprid media push`. The command prints a request ID first. To resume, rerun with the same files in the same order and `--request-id <UUID>`, or read the saved result with `sprid media job <UUID>`. Don’t reuse a request ID for a different selection.\n\n## Create and review the post\n\nSprid record IDs are UUIDs. Posts also have readable references such as `SPR-9`; either identifies the same post.\n\nWrite `draft.json` with the returned IDs and a new UUID as `requestId` (keep it for retries):\n\n```json\n{\n  \"account\": \"my-account\",\n  \"requestId\": \"5e253644-d8a5-4b18-9cc9-d4d921874138\",\n  \"title\": \"A concrete moment\",\n  \"captionInstagram\": \"The caption, with hashtags at the end\",\n  \"aspectRatio\": \"4:5\",\n  \"presentation\": \"finished\",\n  \"assets\": [{ \"kind\": \"image\", \"id\": \"28dc0981-a925-44b0-8ec5-70279f8fef41\" }, { \"kind\": \"image\", \"id\": \"b7a4e0bc-92de-451d-9b3e-d384a2ddcc83\" }]\n}\n```\n\nFor a finished reel, use one asset with `kind: \"video\"`. `finished` artwork gets no overlay or music; images fit inside the canvas, so check the preview for margins.\n\n```sh\nsprid post create --file draft.json --json\nsprid post get SPR-9 --json\nsprid post update SPR-9 --file changes.json --json   # e.g. {\"captionInstagram\":\"Revised caption\"}\nsprid post preview --id SPR-9 --json\nsprid post deliveries SPR-9 --json\n```\n\nThe review link opens the same dashboard screen as from chat. To continue in chat, give it post reference `SPR-9` instead of creating another draft. Approval and platform choices stay with a person. Check delivery receipts before reporting success.\n\n## Hosted options and results\n\n- `sprid capabilities --json`: server limits and what stays local.\n- `sprid media import --file sources.json`: the same account/files/urls/assets payload as MCP `import_assets`.\n- `sprid media reel --file recipe.json`: the metered hosted reel. Payload and approval rules are in `sprid docs chat`. Poll with `sprid media job <UUID>`.\n- `sprid marketing-review`: connected evidence. `sprid docs marketing-review` covers coverage and attribution.\n\nKeys go in through CLI key-file commands or the secure Sprid forms, never a conversation.\n",
+    "revision": "ca02de2e5e236255"
   },
   {
     "id": "marketing-review",

package/src/docs/queries.mjs

@@ -71,7 +71,7 @@ for (const source of Object.keys(QUERY_SOURCES).filter(s => QUERY_SOURCES[s].sto
   op(source, 'posts', source === 'pinterest'
     ? 'Filter stored Pin publishing outcomes with collected daily Pin metrics summed from publication to the exclusive end: impressions, saves, Pin clicks, outbound clicks and video views, each with its observed-day coverage.'
     : 'Filter stored publishing outcomes with the latest metric snapshot before the exclusive end.', { ...dates, status: choice('Publishing status.', ['published', 'failed', 'missed', 'scheduled', 'pending', 'rendering', 'publishing']), contentType: choice('Post type.', ['carousel', 'reel']), limit, offset: integer('Zero-based offset.', 100000, 0) }, ['start', 'end'], { start: '2026-08-01', end: '2026-09-01', status: 'published', limit: 100 });
-  if (QUERY_SOURCES[source].comments) op(source, 'comments', 'Read feedback already collected into Sprid’s Inbox, with optional post and reply filters.', { ...dates, postId: integer('Sprid post ID.', 1000000000), replied: { type: 'boolean', description: 'Filter comments by reply state.' }, limit, offset: integer('Zero-based offset.', 100000, 0) }, ['start', 'end'], { start: '2026-08-01', end: '2026-09-01', replied: false, limit: 100 });
+  if (QUERY_SOURCES[source].comments) op(source, 'comments', 'Read feedback already collected into Sprid’s Inbox, with optional post and reply filters.', { ...dates, postId: str('Sprid post UUID.', { format: 'uuid' }), replied: { type: 'boolean', description: 'Filter comments by reply state.' }, limit, offset: integer('Zero-based offset.', 100000, 0) }, ['start', 'end'], { start: '2026-08-01', end: '2026-09-01', replied: false, limit: 100 });
 }
 
 export function renderQueryReference() {

package/src/post/cli.mjs

@@ -1,3 +1,4 @@
+import { UUID } from "../tools.mjs";
 // sprid post — the local half of Sprid.
 //
 // **It never renders anything.** How a file was made is the consuming repo's
@@ -1208,8 +1209,8 @@ async function cmdRegister(cfg, argv) {
 
     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`);
+    if (authored.remotePostId !== undefined && (typeof authored.remotePostId !== "string" || !UUID.test(authored.remotePostId)))
+      throw new Error(`${slug}: remotePostId must be a UUID`);
     const platforms = checkedPlatforms(flag(argv, "platforms")?.split(",") ?? authored.platforms ?? prev.post?.platforms);
     const title = authored.title ?? prev.post?.title;
     const pinterestOptions = composePinterestOptions({