@sprid/cli 0.1.18 → 1.0.0

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 sprid follows semver: a breaking change to a command's arguments, its output
 shape or its exit codes is a major release.
 
+## 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
+  retains retry protection and finished-artwork safeguards; one or many slides
+  use the same editing and appending operations.
+
 ## 0.1.18 - 2026-09-28
 
 - `sprid post video <ref>` reads a post's own video: its revision, version

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.18",
+  "version": "1.0.0",
   "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

@@ -1604,16 +1604,16 @@ 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_from_assets` 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_slide` or `batch_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 where your tool list offers it (the reviewed connector does not list these tools yet; Sprid's own MCP server does): `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`. Book 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\nThe person opens the returned `/p/<postId>` link, reviews the real media and captions, and picks the channels, time and platform options. TikTok privacy and interaction choices have no defaults and are made on that screen. An agent-supplied confirmation flag is not a human click.\n\nTikTok works two ways from chat. A draft, `options.tiktok = { \"postMode\": \"MEDIA_UPLOAD\" }`, goes to the creator's TikTok inbox without anyone approving it in Sprid; they finish it in the TikTok app. A post straight to their profile is refused from chat and comes back with `approvalUrl`: send the person that link. It opens the posting screen on TikTok at the time asked for, and once they answer and confirm, the booking publishes on its own.\n\nAfter approval, read `get_publication_status`. 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": "ed1ece7b8bb7113d"
+    "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`. Book 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\nThe person opens the returned `/p/<postId>` link, reviews the real media and captions, and picks the channels, time and platform options. TikTok privacy and interaction choices have no defaults and are made on that screen. An agent-supplied confirmation flag is not a human click.\n\nTikTok works two ways from chat. A draft, `options.tiktok = { \"postMode\": \"MEDIA_UPLOAD\" }`, goes to the creator's TikTok inbox without anyone approving it in Sprid; they finish it in the TikTok app. A post straight to their profile is refused from chat and comes back with `approvalUrl`: send the person that link. It opens the posting screen on TikTok at the time asked for, and once they answer and confirm, the booking publishes on its own.\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": "203ffeb3b12a34b7"
   },
   {
     "id": "local",
     "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({

package/src/tools.mjs

@@ -71,11 +71,18 @@ export function listFlag(value) {
   return items.length ? items : undefined;
 }
 
-/** A positive integer positional, or a usage error naming the command. */
-export function needInt(arg, usage) {
-  const n = Number(arg);
-  if (!Number.isInteger(n) || n <= 0) throw new UsageError(usage);
-  return n;
+/** Sprid identifiers are UUIDv4; a post or review may also use its readable reference. */
+export const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+export function needId(arg, usage) {
+  if (typeof arg !== "string" || !UUID.test(arg)) throw new UsageError(usage);
+  return arg.toLowerCase();
+}
+export function needRef(arg, usage, review = false) {
+  if (typeof arg !== "string") throw new UsageError(usage);
+  if (UUID.test(arg)) return arg.toLowerCase();
+  const pattern = review ? /^[A-Z][A-Z0-9]{1,4}-R[1-9]\d*$/i : /^[A-Z][A-Z0-9]{1,4}-[1-9]\d*$/i;
+  if (pattern.test(arg)) return arg.toUpperCase();
+  throw new UsageError(usage);
 }
 
 /** Human output for results with no bespoke renderer. */