@sprid/cli 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 sprid follows semver: a breaking change to a command's arguments, its output
 shape or its exit codes is a major release.
 
+## 0.1.4 - 2026-09-23
+
+- `sprid whoami` warns when the credentials file is readable by other users
+  on the machine, with the `chmod 600` that fixes it, and reports
+  `credentialsFileSecure` in `--json`.
+- `sprid docs` carries the tightened connect guides and the new distribution,
+  first-seconds and store-listing guides.
+- `sprid post create --file` saves an idea when the file says `"status":
+  "idea"`: notes, a `sourceUrl` and any gathered assets, with no assets
+  required. The same `requestId` makes a retry safe, so a repo's hook bank
+  can be pushed in and pushed again.
+- `sprid family` is removed with market editions, which the server no longer
+  has. `sprid apps`, `sprid insights` and `sprid account` are unchanged.
+
 ## 0.1.3 - 2026-09-23
 
 - Posts and reviews have refs: `BND-78` is post 78 of the account keyed BND,

package/README-post.md

@@ -269,7 +269,6 @@ the *copy* here anyway:
 carousels: {
   kind: "composed",
   spec: "social/specs/<slug>.json",
-  // format: <format id>,        // choose from this account’s formats
   // template: <template id>,    // choose from this account’s templates
   expect: { slides: [5, 9], words: [0, 30] },
   neverSay: ["the phrase this account decided it does not say"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sprid/cli",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "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/cli.mjs

@@ -29,7 +29,7 @@ import * as mcp from "./commands/mcp.mjs";
 import * as reviews from "./commands/reviews.mjs";
 import { marketingReview } from "./commands/marketing-review.mjs";
 import { plan, research } from './commands/plan.mjs';
-import { apps, family, insights, account } from "./commands/family.mjs";
+import { apps, insights, account } from "./commands/family.mjs";
 import * as post from "./commands/post.mjs";
 import { docs } from "./commands/docs.mjs";
 import { screenshots, release } from './commands/local-tools.mjs';
@@ -55,7 +55,7 @@ export const COMMANDS = {
   plan, research,
   media, capabilities, completion,
   screenshots, release, doctor, update,
-  apps, family, insights, account,
+  apps, insights, account,
   docs,
   login: auth.login,
   logout: auth.logout,

package/src/commands/auth.mjs

@@ -2,7 +2,7 @@
 // a long secret, the person types a short code into a signed-in browser, and
 // the server hands over a personal access token exactly once.
 
-import { DEFAULT_API_URL, deleteCredentials, credentialsPath, readCredentials, stripSlash, writeCredentials } from "../creds.mjs";
+import { DEFAULT_API_URL, deleteCredentials, credentialsModeOk, credentialsPath, readCredentials, stripSlash, writeCredentials } from "../creds.mjs";
 import { ApiError } from "../http.mjs";
 import { C, OK } from "../format.mjs";
 import { pickWorkspace } from "../cli.mjs";
@@ -124,6 +124,8 @@ export async function whoami(ctx) {
   // The current one, if it can be known without asking; never exit 2 from whoami.
   const current = await ctx.workspace().catch(() => null);
   const source = a.source === "env" ? "SPRID_PAT" : credentialsPath(ctx.env);
+  // Written 0600, but a later copy, restore or chmod can loosen it silently.
+  const fileSecure = a.source === "env" ? null : credentialsModeOk(ctx.env);
   if (ctx.json) {
     ctx.out({
       email: user.email ?? a.email ?? null,
@@ -133,6 +135,7 @@ export async function whoami(ctx) {
       apiUrl: a.apiUrl,
       tokenSource: source,
       tokenId: a.tokenId,
+      credentialsFileSecure: fileSecure,
     });
     return 0;
   }
@@ -143,6 +146,9 @@ export async function whoami(ctx) {
       : "no workspace";
   ctx.print(`  ${user.email ?? a.email ?? "(unknown)"} · workspace ${wsLine}`);
   ctx.print(C.dim(`  ${a.apiUrl} · token from ${source}`));
+  if (fileSecure === false) {
+    ctx.print(`  Warning: ${source} is readable by other users on this machine. Fix: chmod 600 "${source}"`);
+  }
   if (workspaces.length > 1) {
     ctx.print(workspaceList(workspaces, current));
     if (!current) ctx.print(C.dim("  Pick one: sprid use <slug>"));

package/src/commands/family.mjs

@@ -18,53 +18,13 @@ function objectFile(ctx) {
 function positiveId(raw) {
   const id = Number(raw);
   if (!Number.isInteger(id) || id <= 0)
-    throw new UsageError("Pass a positive family or edition ID.");
+    throw new UsageError("Pass a positive account ID.");
   return id;
 }
 export async function apps(ctx) {
   ctx.out(await ctx.api().get("/api/app-profiles/hierarchy"));
   return 0;
 }
-export async function family(ctx) {
-  const [verb = "list", raw] = ctx.positionals;
-  let result;
-  if (verb === "list" || verb === "compare") {
-    const workspaceId = await ctx.workspaceId();
-    const app = await resolveProfile(ctx, workspaceId);
-    result = await ctx
-      .api()
-      .get(
-        `/api/content-families${verb === "compare" ? "/performance" : ""}?workspaceId=${workspaceId}&app=${app.id}&ageDays=${encodeURIComponent(ctx.flags.days ?? 7)}`,
-      );
-  } else if (verb === "create")
-    result = await ctx.api().post("/api/content-families", objectFile(ctx));
-  else {
-    const id = positiveId(raw);
-    const edition = ["get", "preview", "review", "localize"].includes(verb);
-    const path = edition
-      ? `/api/content-families/editions/${id}`
-      : `/api/content-families/${id}`;
-    if (verb === "get") result = await ctx.api().get(path);
-    else if (verb === "preview")
-      result = await ctx.api().post(`${path}/preview`, {});
-    else if (
-      ["edition", "review", "localize", "plan", "schedule"].includes(verb)
-    )
-      result = await ctx
-        .api()
-        .post(
-          `${path}/${verb === "edition" ? "editions" : verb}`,
-          objectFile(ctx),
-        );
-    else
-      throw new UsageError(
-        "sprid family list|create|edition|get|localize|preview|review|plan|schedule|compare [id] [--file payload.json]",
-      );
-  }
-  // Always print exact IDs, preview URLs, blockers and revision fingerprints.
-  ctx.out(result);
-  return 0;
-}
 export async function insights(ctx) {
   const workspaceId = await ctx.workspaceId();
   const app = await resolveProfile(ctx, workspaceId);

package/src/docs/commands.mjs

@@ -28,7 +28,7 @@ export const COMMAND_GROUPS = [
     ['media', 'sprid media reel --file <recipe.json>', 'Create a metered hosted photos/text reel after explicit user authorization. Returns a durable job ID.'],
     ['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. Never publishes.'],
+    ['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 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.'],
@@ -45,19 +45,11 @@ export const COMMAND_GROUPS = [
     ['release', 'sprid release metadata|screenshots|graphics [--config release.config.ts] [--execute]', 'Preview store listing changes locally; --execute sends the reviewed changes. Requires Bun.'],
     ['release', 'sprid release ship [--execute] [--ios-only|--android-only]', 'Build and submit your app using its release configuration. Dry run by default; use --help for all options.'],
   ] },
-  { title: 'Apps and market editions', entries: [
+  { title: 'Apps and accounts', entries: [
     ['account', 'sprid account create|update [id] --file payload.json', 'Create an app content account or update its identity. Creation requires workspaceId, appProfileId, name and slug; market, locale, persona and timezone are explicit.'],
     ['account', 'sprid account avatar <account> [file|url]', 'Set the avatar Sprid’s mails and templates draw. No source uses the app’s icon: App Store artwork, else the website’s manifest or touch icon. A file must be PNG, JPEG or WebP; a 1024 px app icon from the repo is the best source.'],
     ['apps', 'sprid apps', 'List apps with their content accounts and workspace IDs.'],
     ['insights', 'sprid insights --app <slug> [--account <slug>] [--days N]', 'Read app results once, with social content optionally narrowed to one account.'],
-    ['family', 'sprid family compare --app <slug> [--days N]', 'Compare themes at matched post age with sample counts and channel baselines.'],
-    ['family', 'sprid family list --app <slug>', 'List content families, themes and market editions.'],
-    ['family', 'sprid family create --file payload.json', 'Create a family: sourcePostId, title, theme and sourceReference.'],
-    ['family', 'sprid family edition <familyId> --file payload.json', 'Copy an independent draft: accountId, locale and market. Translate it in the editor or through the API.'],
-    ['family', 'sprid family localize <postId> --file payload.json', 'Save translated captions and slide text or reel beats atomically, clearing old approval.'],
-    ['family', 'sprid family get|preview <postId>', 'Read the edition or render its current content for review.'],
-    ['family', 'sprid family review <postId> --file payload.json', 'Approve a rendered revision with fingerprint, sourceReference and confirmed: true.'],
-    ['family', 'sprid family plan|schedule <familyId> --file payload.json', 'Plan exact postId/channelId/scheduledFor destinations. Scheduling also requires the returned planFingerprint.'],
   ] },
   { title: 'Sign in', entries: [
     ['setup', 'sprid setup begin --file <artifact> --task publish|review|repo [--source <source>] [--entry website|installed-skill|browser|paid]', 'Save the first useful result locally before signup. Repeating begin preserves the same task and retry key.'],

package/src/docs/guides.generated.mjs

@@ -1144,8 +1144,8 @@ export const CONTENT_GUIDES = [
     "title": "Review marketing from connected evidence",
     "summary": "Investigate acquisition, activation, retention and revenue through the services connected to Sprid, and say plainly what evidence is missing.",
     "url": "https://sprid.studio/docs/marketing-review",
-    "markdown": "# Review marketing from connected evidence\n\n**What this guide does:** Investigate acquisition, activation, retention and revenue through the services connected to Sprid, and say plainly what evidence is missing.\n\n## Start with the question\n\nName the app, the date range and the decision the review should inform.\n\n1. `list_apps` and `list_app_profiles` to find the app.\n2. `get_marketing_review_context` for shared definitions, required investigations, earlier decisions and corrections.\n3. `get_marketing_review` for the app over two comparable periods. The summary links to full evidence per source (`view: \"full\", sources: [<source>]`); omit `sources` to include social history, store reviews and milestones.\n4. Re-read an exact saved packet with `get_marketing_review_evidence` and its `evidence.id` (CLI: `sprid marketing-review evidence --id <id> --app <slug>`). It still works after a connection changes.\n\n`refresh: true` asks for live reads; `cachedOnly: true` reads only stored evidence. Keep returned errors, coverage, population definitions and sample counts in the report.\n\nIn a browser chat there is no repository. For a question about a shipped change, ask for a release summary or public changelog and label it as supplied. Never claim to have read a repository or private database. Local users can add repo diffs and database reads through their own tools.\n\n## Follow the evidence\n\n`list_marketing_queries` lists supported reads and their schemas; `query_marketing_source` runs them with Sprid’s saved credentials. Follow pagination and keep truncation visible. `get_documentation` with `metrics` covers definitions and refused calculations; with `queries`, source-specific reads.\n\n- Keep acquisition apart from activation, and people apart from events. A post impression is not an install; a download is not an activated user.\n- Compare equal windows and comparable populations.\n- No onboarding events means recommending instrumentation, not guessing a funnel.\n- Keep revenue sources separate until the overlap check says they can be added.\n\nFor each finding, test another explanation: tracking changes, traffic exclusions, attribution window, seasonality, a different audience mix. A before/after comparison doesn’t prove cause. If a difference is within normal variation or the sample is small, say so and don’t rank it.\n\n## Report and save\n\nLead with the decision, then the evidence, the limits and what would change the answer. Keep failed reads apart from reads that returned nothing. `next_actions` gives the follow-up. A missing credential goes to the secure App Profile form or a CLI key-file command; no provider MCP is needed for a supported query.\n\n- **Shared context:** when authorized, save non-secret definitions, investigations, decisions, corrections and release references with `save_marketing_review_context`, sending `baseRevision` from the latest read. A conflict returns both versions; reconcile before retrying. Saved context is a claim with references, not verification. CLI: `sprid marketing-review context --app <slug>` reads, `--file <context.json>` imports `{baseRevision,context}`. Private notes stay local.\n- **Changes:** log confirmed product or marketing changes with `add_event`, naming the areas they affect and why.\n- **The review itself:** save it as an app-scoped `kind: \"note\"` event with the date, conclusion, evidence references, coverage and next hypothesis in `meta`. Other clients read it with `list_events`. `log_reflection` is only for a post’s own statistics.\n\nNever store secrets or signed attachment URLs in any of these.\n\n## Collection and coverage\n\n- Sprid refreshes two rolling 30-day windows daily for configured services on active plans, and re-reads late provider exports. No model calls, publishing or paid social reads. Other windows are read on demand.\n- Pause with the App Profile’s `metricsCollectionEnabled: false` or `sprid marketing-review collection --enabled false`. Stored evidence stays readable.\n- Snapshots are private to the app, tied to its configuration and kept 90 days. Save local evidence exports for a lasting archive.\n- Missing days stay unknown. Incomplete store or Search Console windows get no percentage change. Never sum daily unique people into a monthly count.\n- `configuration_only` means identifiers and a key are saved, not that access works. Errors return a safe code, the HTTP status when known, whether to retry and the next step. Retry transient errors before recommending a reconnect. Unsupported metrics and provider privacy thresholds are stated as limits.\n",
-    "revision": "71f8c7a54ea9307e"
+    "markdown": "# Review marketing from connected evidence\n\n**What this guide does:** Investigate acquisition, activation, retention and revenue through the services connected to Sprid, and say plainly what evidence is missing.\n\n## Start with the question\n\nName the app, the date range and the decision the review should inform.\n\n1. `list_apps` and `list_app_profiles` to find the app.\n2. `get_marketing_review_context` for shared definitions, required investigations, earlier decisions and corrections.\n3. `get_marketing_review` for the app over two comparable periods. The summary links to full evidence per source (`view: \"full\", sources: [<source>]`); omit `sources` to include social history, store reviews and milestones.\n4. Re-read an exact saved packet with `get_marketing_review_evidence` and its `evidence.id` (CLI: `sprid marketing-review evidence --id <id> --app <slug>`). It still works after a connection changes.\n\n`refresh: true` asks for live reads; `cachedOnly: true` reads only stored evidence. Keep returned errors, coverage, population definitions and sample counts in the report.\n\nIn a browser chat there is no repository. For a question about a shipped change, ask for a release summary or public changelog and label it as supplied. Never claim to have read a repository or private database. Local users can add repo diffs and database reads through their own tools.\n\n## Follow the evidence\n\n`list_marketing_queries` lists supported reads and their schemas; `query_marketing_source` runs them with Sprid’s saved credentials. Follow pagination and keep truncation visible. `get_documentation` with `metrics` covers definitions and refused calculations; with `queries`, source-specific reads.\n\n- Keep acquisition apart from activation, and people apart from events. A post impression is not an install; a download is not an activated user.\n- Compare equal windows and comparable populations.\n- No onboarding events means recommending instrumentation, not guessing a funnel.\n- Keep revenue sources separate until the overlap check says they can be added.\n\nFor each finding, test another explanation: tracking changes, traffic exclusions, attribution window, seasonality, a different audience mix. A before/after comparison doesn’t prove cause. If a difference is within normal variation or the sample is small, say so and don’t rank it.\n\n## Report and save\n\nLead with the decision, then the evidence, the limits and what would change the answer. Keep failed reads apart from reads that returned nothing. `next_actions` gives the follow-up. A missing credential goes to the secure App Profile form or a CLI key-file command; no provider MCP is needed for a supported query.\n\n- **Shared context:** when authorized, save non-secret definitions, investigations, decisions, corrections and release references with `save_marketing_review_context`, sending `baseRevision` from the latest read. A conflict returns both versions; reconcile before retrying. Saved context is a claim with references, not verification. CLI: `sprid marketing-review context --app <slug>` reads, `--file <context.json>` imports `{baseRevision,context}`. Private notes stay local.\n- **Changes:** log confirmed product or marketing changes with `add_event`, naming the areas they affect and why.\n- **The review itself:** save it as an app-scoped `kind: \"note\"` event with the date, conclusion, evidence references, coverage and next hypothesis in `meta`. Other clients read it with `list_events`.\n\nNever store secrets or signed attachment URLs in any of these.\n\n## Collection and coverage\n\n- Sprid refreshes two rolling 30-day windows daily for configured services on active plans, and re-reads late provider exports. No model calls, publishing or paid social reads. Other windows are read on demand.\n- Pause with the App Profile’s `metricsCollectionEnabled: false` or `sprid marketing-review collection --enabled false`. Stored evidence stays readable.\n- Snapshots are private to the app, tied to its configuration and kept 90 days. Save local evidence exports for a lasting archive.\n- Missing days stay unknown. Incomplete store or Search Console windows get no percentage change. Never sum daily unique people into a monthly count.\n- `configuration_only` means identifiers and a key are saved, not that access works. Errors return a safe code, the HTTP status when known, whether to retry and the next step. Retry transient errors before recommending a reconnect. Unsupported metrics and provider privacy thresholds are stated as limits.\n",
+    "revision": "f5e9475cb0f8636e"
   },
   {
     "id": "traffic",
@@ -1162,5 +1162,29 @@ export const CONTENT_GUIDES = [
     "url": "https://sprid.studio/docs/pinterest",
     "markdown": "# Pinterest content and publishing\n\n**What this guide does:** Plan searchable Pins, approve a useful batch, let Sprid publish the selected Pins on schedule and judge the result by qualified traffic and activation.\n\nChecked against Pinterest’s guidance on 21 September 2026. Anything labelled a test is a starting hypothesis, not a claim about what will win for your account.\n\n## How Pinterest discovery works\n\nPinterest is visual search and recommendation. A Pin can show up in search, home feeds and related Pins long after it is published, mostly regardless of followers.\n\nRelevance comes from the Pin itself and how people interact with it: clear keywords, original imagery, link quality and board context. Pinterest publishes no weighting. Make the visual, title, description, board and landing page all answer the same “what is this about?”, in the words a person would search, without repeating a keyword unnaturally.\n\nBecause Pins keep getting found, compare them at equal ages and keep older Pins in the analysis.\n\n## Start with the destination\n\nPick the page and the action before making the visual:\n\n1. One useful guide, tool, feature page or store destination.\n2. The concrete question it answers.\n3. One next action that continues the same task, such as opening that feature.\n4. Campaign parameters added without removing existing ones, with a stable Pin or creative ID so visits trace back to the exact Pin.\n\nThe page must deliver the pictured promise immediately and work on a phone. A specific Pin that lands on a generic homepage breaks the promise. A store visit is not an install, and an outbound click is not activation: report each step separately.\n\n## Prepare the website\n\n- **Claim your website** in Pinterest to link the profile to Pins from that domain and get website analytics. A website can be claimed by only one Pinterest account.\n- **Rich Pins:** for articles, products or recipes, add Open Graph or Schema.org metadata. Pinterest syncs it from the page; it is not a Sprid export. Check how it appears before a batch, because editing a Pin by hand can override synced article or recipe details.\n- Make sure Pinterestbot can read the page, links work and it loads fast on mobile.\n\n## Choose topics and boards\n\nBuild the topic list from Pinterest Trends, Pinterest search suggestions, customer language and site queries that already work. Search Console is a useful seed, but Google demand doesn’t prove Pinterest demand.\n\nMix evergreen questions with relevant seasonal moments. Use focused boards whose name and description explain the topic: a Pin about apartment-viewing costs belongs on a board about buying an apartment, not a broad “Ideas” board. Only create a board when the topic can fill it.\n\n## Build the Pin\n\n| | Ratio | Ideal size | Notes |\n|---|---|---|---|\n| Image | 2:3 | 1000 × 1500 px | |\n| Video | 9:16 | 1080 × 1920 px | 4 seconds to 5 minutes, H.264 or H.265 |\n\nSprid publishes one image or one finished video per Pin. It never turns an Instagram carousel into a Pin, so make a dedicated asset and check its crop in the preview.\n\nAt thumbnail size the subject and benefit should still be clear: one focus, strong contrast, short readable overlay copy. Check the real phone preview. The Pin must stand alone; an opener that only makes sense after swiping is incomplete here.\n\nFormats worth testing:\n\n- an editorial cover for a specific guide\n- a reference card with a concrete checklist or answer\n- a real app demo showing one task\n- a coherent visual collection for design, travel or architecture\n- a short captioned video when motion explains the task better\n\nPinterest can label detected or declared AI imagery. Keep provenance, use accurate licensed assets and disclose where required. Never publish an image that misrepresents the linked place, product or result.\n\n## Write the metadata\n\n| Field | Limit | Notes |\n|---|---|---|\n| Title | 100 characters | Put the subject early; feeds may cut it. |\n| Description | 800 characters | Often hidden in feeds, but Pinterest reads it for relevance. |\n| Alt text | 500 characters | Describe what the image shows. Not a keyword field. |\n\nWrite a natural title and description naming the topic, audience or situation and what the destination provides. Choose a relevant board, add a working destination, and set the AI disclosure in Sprid when it applies. No stuffed keyword variants, unrelated trends or promises the page doesn’t keep.\n\nThe visual earns attention, the metadata gives context, the destination completes the task. Keep all three aligned.\n\n## Publish your first Pin\n\nPublishing and scheduling need Sprid’s Pinterest app to have Standard access. With Trial access you can connect, browse boards and prepare drafts, but Sprid refuses to publish or schedule. That access belongs to Sprid’s integration; you don’t apply for a developer app.\n\n1. Connect Pinterest, run `sprid status` and confirm the account.\n2. Create or open a post with exactly one image (ideally 2:3) or one finished video (ideally 9:16).\n3. Open **Publish**, select **Pinterest**, then pick a **Board** and optional section.\n4. Add the title, description, destination, alt text and any AI disclosure.\n5. Check the rendered creative and every public field. Publish now or pick a time.\n6. After delivery, open the Pin signed out or from another account and follow its link.\n\n**CLI:** `sprid pinterest boards --account <slug>` lists board IDs, or says there are none; create one with `sprid pinterest create --account <slug> --name <name> [--privacy public|secret]`. `sprid pinterest set <postId> --board <id> --link <url>` saves the draft (optional metadata flags in `sprid docs cli`); review and schedule it in Sprid. `sprid pinterest metrics <publishId> --account <slug>` reads results.\n\n**MCP:** read `get_documentation` topic `pinterest-content`, pick the exact channel from `list_connections`, then `list_pinterest_boards`. If there are none, say so, and call `create_pinterest_board` only with a name and privacy the user approved. Save `pinterestOptions` with `update_post`, preferring `aspectRatio: \"2:3\"` for a new image Pin. Show the user the rendered Pin or dry-run batch, then call `schedule_post` or commit `schedule_batch` only for the Pins they chose. `get_pinterest_metrics` reads results.\n\n## Choose a cadence to test\n\nStart with **2 original Pins a day** in separate slots. With a broad catalog of useful destinations and genuinely distinct assets, test **5 a day** against that. These are Sprid’s proposed tests, not Pinterest limits or proven optimums. A small destination library needs more useful content, not cosmetic duplicates in the queue.\n\nRotate destinations and topics. Start with two distinct treatments per destination, on different days. No exact spacing or best hour is established.\n\nWhat the evidence says: Pinterest recommends original content at least weekly. [Sarah Hanford](https://www.sarahhanford.com/blog/pinterest-growth-organically-60-days) went from three Pins a day to five alongside keyword research and a new website, so frequency isn’t isolated as the cause. [Tailwind’s benchmark](https://www.tailwindapp.com/pinterest-marketing/research/2025-benchmark-study-part-1) of about 1.2 million organic Pins (2024 data) found results concentrated in a small share of Pins; its English-speaking, observational sample can’t set a universal cadence.\n\n## Review and schedule the batch\n\nFor a two-a-day test, choose **Daily** and two times in the batch scheduler, for example **09:00 and 17:00** (convenient, not researched best times). Check the account’s timezone and the actual dates before confirming; they may differ from your device. Keep a cadence the user already chose unless they ask to change it.\n\nOrder Pins so destinations alternate, and check the calendar preview for busy days, gaps and unplaced Pins. Preparing a large batch at once is fine; publication spreads across the schedule.\n\n**MCP:** `schedule_batch` with `cadence: \"daily\"`, `times: [\"09:00\", \"17:00\"]`, the account/channel and the selected post IDs. Run `dryRun: true` first and check `placements`, `unplaced` and `timezone`. Busy days are skipped by default, so read the returned plan instead of promising an end date. Commit only the reviewed Pins and report what was booked. CLI users read this guide with `sprid docs pinterest-content` and the queue with `sprid queue`; place batches in the scheduling screen or over MCP.\n\nBefore approving, check every Pin’s creative, metadata, destination, board and time, plus factual claims, rights and disclosure. Pinterest’s developer guidelines require the user to choose each Pin that publishes: Sprid shows the concrete Pins and schedule and records the selection. Those Pins then publish on time without asking again.\n\n- Moving only the time keeps the reviewed Pin. Changing content, board or link means reviewing and rescheduling it; changed drafts can be blocked at publish until reviewed.\n- After an unclear publish failure, check Pinterest before retrying; the Pin may already exist.\n- After the first Pin publishes, check it and its link from outside the connected account. A draft, preview or accepted schedule is not delivery.\n\n## Measure what happened\n\n- **Impressions:** times the Pin was on screen.\n- **Saves:** times people saved it to a board.\n- **Pin clicks:** opens of the Pin in close-up.\n- **Outbound clicks:** clicks through to a destination outside Pinterest.\n- **Video views:** at least 2 seconds with at least 50% of the video in view.\n\nFor app growth the path is **impression → outbound click → qualified visit → app action → activation**. Saves are a diagnostic, not the goal: a Pin with many saves and few outbound clicks may be a good reference on Pinterest and bring little acquisition.\n\nCompare Pins of similar age within the same topic, language and market. Judge creative by outbound-click rate and qualified visits, the whole path by activations per Pin and revenue where available. Pinterest’s outbound clicks and your own site sessions are measured differently; show both rather than forcing them to match.\n\nReview cohorts at 30, 60 and 90 days of Pin age. Report counts and coverage, including results with the top Pin removed, so one outlier can’t set the strategy. Keep a higher frequency while extra Pins keep adding qualified visits or activations; a lower click rate alone doesn’t cancel growth in total qualified traffic.\n\n- Visits but no activation: check page speed, message match and the next app action before making more Pins.\n- Low impressions: check topic relevance, board, metadata and visual clarity.\n- Negligible qualified traffic and activation across repeated relevant cohorts: stop scaling Pinterest for that app.\n\n## Improve the next batch\n\nChange one meaningful thing per comparison (visual treatment, question, format or destination angle) and repeat across comparable destinations. Organic distribution isn’t randomized, so call it a directional test, not an A/B test.\n\nMake fresh, useful treatments, not cosmetic duplicates. [Tailwind’s freshness study](https://www.tailwindapp.com/pinterest-marketing/research/2025-benchmark-study-part-three) found new images for an existing URL kept distribution better than reusing the same image and URL (an association, not a guaranteed lift). Pinterest advises against re-uploading the same Pin, and repetitive or irrelevant commercial content can be treated as spam. Space treatments of the same destination apart and keep every Pin on a relevant board.\n\nFor a worked example, [Elaine Timms’s recipe-client case](https://elainetimms.com/evergreen-growth-how-food-creator-pins-for-profit/) combines search-specific overlays, creative variants and email opt-ins. Its growth can’t be credited to cadence alone.\n\n## Sources\n\n- [How Pinterest discovery works](https://create.pinterest.com/blog/how-to-increase-discoverability-seo-pinterest/)\n- [Growing through search, boards and keywords](https://create.pinterest.com/blog/best-ways-to-grow-on-pinterest/)\n- [Pin specifications](https://help.pinterest.com/en/article/review-pin-specs)\n- [Pin performance and distribution](https://help.pinterest.com/en/business/article/pin-performance-and-distribution)\n- [Pinterest Analytics definitions](https://help.pinterest.com/en/business/article/pinterest-analytics)\n- [Pinterest developer guidelines](https://policy.pinterest.com/en/developer-guidelines)\n- [Pinterest API schema](https://github.com/pinterest/api-description/blob/main/v5/openapi.json)\n- [Pinterest community guidelines](https://policy.pinterest.com/en/community-guidelines)\n- [Pinterest labels for AI-generated or modified images](https://help.pinterest.com/en/article/gen-ai-labels)\n- [Claim your website](https://help.pinterest.com/en/business/article/claim-your-website)\n- [Rich Pins](https://help.pinterest.com/en-gb/business/article/rich-pins)\n",
     "revision": "563dbb5a9c4b3053"
+  },
+  {
+    "id": "distribution",
+    "title": "Why a post travels",
+    "summary": "Explains what Instagram and TikTok actually reward, and turns each mechanic into a rule you can build a post against. Read it before deciding a format, a slide count or a caption length, and when a post that looked good got no reach.",
+    "url": "https://sprid.studio/docs/distribution",
+    "markdown": "# Why a post travels\n\n**What this guide does:** Explains what Instagram and TikTok actually reward,\nand turns each mechanic into a rule you can build a post against. Read it before\ndeciding a format, a slide count or a caption length, and when a post that\nlooked good got no reach.\n\nWhether a post is *good* and whether it *travels* are two different questions.\nThis one is about the second. Every rule here exists because of a specific\nmechanic, and if the mechanic changes the rule goes with it - so each is written\nwith its reason attached rather than as a commandment.\n\n**Verified against published sources 2026-08-04.** Platform mechanics decay.\nTreat anything here as a claim about a moving system, re-check it quarterly, and\nprefer your own numbers the moment you have them.\n\n## Instagram\n\n**The three named ranking signals are watch time, sends per reach, and likes per\nreach.** Sends are the heaviest, reported at roughly three to five times the\nweight of a like. Sends per reach is specifically the signal that reaches people\nwho do not follow you, which is the only reach a new account can grow on.\n\n**Feed, Reels, Stories and Explore rank separately** and weight those signals\ndifferently. Feed leans on how close you already are to the viewer; Explore on\nengagement velocity and interest match. A post that does well with your existing\nfollowers is not automatically a post that travels.\n\n**Why carousels, specifically:**\n\n- Every swipe is engagement, and dwell time accumulates across the slides.\n  Carousels are reported at two to three times the reach of a single image for\n  the same content.\n- **The platform re-serves a carousel to people who did not swipe, starting from\n  the second slide.** This is the most actionable mechanic available: slide two\n  gets an independent second chance to be someone's first impression.\n- Carousels out-save single images by a wide margin, and saves compound, because\n  saved posts get resurfaced.\n- Completion - how many people reach the last slide - is what pushes a post out\n  of your followers and into Explore.\n\n**Hashtags do not drive distribution.** The platform's own position is that they\ncategorise rather than distribute. Discovery comes from the words in your\ncaption: captions, alt text, bios and on-screen text are indexed and served into\nin-app search. Keyword-rich captions have been measured at around 30% more reach\nthan hashtag-heavy ones. Keep three to five hashtags as labels and spend the\neffort on the prose.\n\n## TikTok, photo mode\n\n- Ranking is swipe-through rate, dwell time and reverse swipes, with completion\n  rate as the primary signal.\n- Distribution starts with a **small test batch of roughly 200-500 viewers**,\n  mostly followers and people who engage with adjacent content. What that batch\n  does decides everything afterwards. This is why the first hour matters, and\n  why a weak second slide is fatal rather than merely costly.\n- Saves are weighted and photo posts save well. A carousel with fewer views but\n  a high save-and-comment share is doing better than a higher-view post that\n  bounces on slide one.\n- Interest-based distribution means an outlier is possible from your first post.\n  TikTok is spikier; Instagram grinds.\n\n## What follows for how you build a post\n\n| Rule | Because |\n|---|---|\n| **Slide 2 is a second hook.** It delivers on slide 1 *and* opens a new thread, and it has to work cold | the platform re-serves from slide 2; TikTok's test batch dies there |\n| **Seven slides for a narrative format** (hook, five body, closer) | seven to ten is the reported dwell-time sweet spot; under five reads as a short post, over ten causes mid-carousel fatigue |\n| **No slide may be skippable.** If a body slide can be removed without breaking the post, you wrote a list, not an experience | completion is the ranking signal, and a list lets people stop anywhere |\n| **The peak lands in the last third** | a middle peak makes the tail a letdown, and the tail is where completion is won |\n| **Design for the send, not the like.** At least one slide should make someone think of a specific person | sends per reach is the non-follower signal, worth several likes |\n| **The send prompt lives in the caption**, naming one kind of person, never \"share if you relate\" | it belongs where sends are earned, and it keeps the last slide screenshottable |\n| **At least two slides hand over something usable** | recognition earns likes; recognition plus something doable earns saves, and saves compound |\n| **Captions carry the audience's own search phrases, in prose** | captions are indexed; hashtags are not distribution |\n| **Caption length 400-600 characters on Instagram, 150-300 on TikTok**, first line an independent hook under 125 characters | that is where the \"more\" cut falls; past roughly 300 characters TikTok needs a tap and reach drops |\n| **Three to five hashtags, never the generic feed tag** | labels, not reach |\n| **One canvas at 4:5, content clear of the top and bottom edges** | survives the 3:4 grid crop, letterboxes acceptably on TikTok |\n\n## Cadence, and the first hour\n\n**Three to five posts a week, sustained.** Three a week for twelve weeks beats\nseven a week for three. The failure mode is not low quality, it is stopping - and\nthe documented version of it is 34 drafts and 3 published posts.\n\n**The first hour is the test batch.** Being there to answer early comments is the\ncheapest intervention available on either platform; a comment answered in the\nfirst hour is worth more than the same reply a day later.\n\n**Post at a fixed time** your audience is awake for, set once on the account's\nposting schedule rather than decided per post.\n\n**Expect silence for two months.** A new account with no face takes three to six\nmonths to reach a thousand followers on Instagram. Distribution is a power law:\na few posts carry most of the reach. Judging before 90 days is judging noise.\n\n## When something works, fan it out\n\nA post that breaks out is the beginning of the work, not the end.\n\n1. Make five to ten variants of the winner with the structure fixed and **exactly\n   one variable changed** - the hook phrasing, the register, the opening image.\n2. One variable per variant, or the result teaches nothing.\n3. Log which variant won *and* which source line its hook came from. That tells\n   you which well to keep digging.\n4. A losing variant is data. Kill it rather than nursing it.\n\n## What is worth not believing\n\nEverything above is published guidance and platform statements, not our\nmeasurements. Before you treat any of it as settled for **your** audience, these\nare the clean one-variable tests: caption length judged on saves and sends per\nreach; a quiet text card against a photo behind text; a native 9:16 crop against\na letterboxed 4:5; whether a screenshot of your app costs reach or buys installs.\n\nLog the real numbers per post at seven days - views, completion, saves, sends,\ncomments, profile taps. The moment you have your own numbers they outrank every\nsource below.\n\n## Sources\n\n- [Instagram algorithm ranking signals (Buffer)](https://buffer.com/resources/instagram-algorithms/) - watch time, sends per reach, likes per reach, per-surface ranking\n- [The ranking signals that matter (Clixie)](https://www.clixie.ai/blog/instagram-algorithm) - sends weighted three to five times a like\n- [How carousels beat Reels for engagement (Storrito)](https://storrito.com/resources/how-instagram-carousels-beat-reels-for-engagement-in-2026-and-when-to-use-each/) - re-serving from slide 2, reach multiple\n- [Carousel best practices (Adpicto)](https://www.adpicto.com/en/blog/instagram-carousel-best-practices-2026) - slide count, dwell time, saves\n- [Carousel algorithm (TryMyPost)](https://www.trymypost.com/blog/instagram-carousel-algorithm-strategy-2026) - dwell time and completion\n- [Do hashtags still work (Kontentino)](https://www.kontentino.com/q-and-a/instagram-hashtags-reach/) - hashtags do not drive reach\n- [Keywords versus hashtags (Dive Media)](https://www.divemedia.com.au/marketing-tips-and-insights/social-seo-keywords-vs-hashtags) - caption indexing and the reach lift\n- [TikTok photo mode algorithm (ReelBase)](https://reelbase.io/blog/tiktok-photo-mode-algorithm-explained) - photo mode reach against video\n- [TikTok carousel algorithm (PostWaffle)](https://www.postwaffle.com/blog/tiktok-carousel-algorithm) - swipe-through, reverse swipes, test batch size, saves\n",
+    "revision": "6799e74c42287dc5"
+  },
+  {
+    "id": "reel-first-seconds",
+    "title": "The first seconds of a reel",
+    "summary": "Explains why a vertical video is watched or skipped in its opening seconds, and gives the timing arithmetic to build one that gets past it. Read it before writing a hook, choosing a length, or diagnosing a reel that got no views.",
+    "url": "https://sprid.studio/docs/reel-first-seconds",
+    "markdown": "# The first seconds of a reel\n\n**What this guide does:** Explains why a vertical video is watched or skipped in\nits opening seconds, and gives the timing arithmetic to build one that gets past\nit. Read it before writing a hook, choosing a length, or diagnosing a reel that\ngot no views.\n\nBoth platforms decide a video's reach from a small first batch of viewers and\nfrom what each of them does in the first seconds. Nothing after second three\nmatters to someone who left at second two. Everything below follows from that.\n\nEach claim carries how we know it: **measured** (we ran it and wrote the number\ndown), **reproduced** (we made the mistake and watched it happen), **published**\n(the platform or a cited source says so, we have not tested it).\n\n## Frame 0 is the cover, so it must already be readable\n\n**Reproduced, twice, on two different accounts.** The feed shows the video's\nfirst frame as its poster image. A hook that fades in from black has a black\ncover. A hook that animates up from 0.42 opacity reads as washed-out grey for\nthe first half second - which is inside the window that decides whether anyone\nstays.\n\nPlace the first card. Do not animate it in. Light it at 0.7 opacity or more, and\nmake it true at t=0.\n\n## The opener has to end before second three\n\n**Reproduced.** A hook card held for 3.3 seconds puts the first cut at 3.1\nseconds, so the entire skip window contains one motionless card. Nothing has\nhappened yet when the viewer decides.\n\nSize the opener to its own reading load with a floor of 1.6 seconds, and check\nthat the first cut lands under three. A cut inside the window is the cheapest\nsignal you have that this video is going somewhere.\n\n## Length: one measured result, and its confound\n\n**Measured, on one of our own accounts, 2026-08-29.** A batch cut to 15.5\nseconds drew 113-162 views on an account with a single follower. The 29-32\nsecond cuts that followed on the same account drew 6-22, and one sat at 6 views\nafter 29 hours - a distribution collapse rather than a slow start.\n\nState the confound honestly: three things changed in that batch at once\n(background, word density, length). Length is the reversible one, not the proven\none. That account now runs a 10-13 second test. **Neither band is a benchmark**,\nand anyone quoting 15.5 seconds as an optimum - including us - is over-reading a\nsingle comparison.\n\n## The timing arithmetic\n\nReading load, not taste. These are the holds that stop a card from reading faster\nthan it is shown.\n\n| | hold | why |\n|---|---|---|\n| any word | 300 ms | silent reading speed on a phone |\n| any character | 52 ms | a compound noun is one word and twenty letters, so take `max(words, chars)` |\n| opener | 1.6-2.8 s | reading load + 0.5 s, and the first cut must land under 3 s |\n| body or turn | 2.4-4.2 s | reading load + 0.7 s |\n| a big number | 2.6-3.8 s | the number reads at a glance, its label does not |\n| closer | 3.6-5.0 s | reading load + 1.3 s; this is the card people screenshot |\n| overlap | 200 ms | each card starts before the previous one leaves |\n\nWord budgets per card, never totalled: hook 3-11, body 3-14, closer 4-16. A\n3.5-second card holds roughly 10 words or 55 characters at a comfortable size.\nPast that the card reads faster than it holds, and the viewer waits - which is\nthe same experience as being bored.\n\n## What a hook is, and is not\n\n- A sentence your buyer has actually thought, or the sharpest fact stated flat.\n  A scene or a number. It opens a loop the closer shuts.\n- **Not a \"how to\".** That creates an expectation of information, and information\n  can be postponed. Not a question. Not \"did you know\".\n- **Recognition stops a scroll; tempo does not.** A harvested ten-word hook beat\n  an invented four-word one on our own account (**reproduced**). Hooks come from\n  what people actually said - forum threads, reviews, support mail - not from the\n  bank of phrases that sound like hooks.\n- **The second card is a second hook.** It has to work cold, with the first card\n  gone. On carousels the platform literally re-serves from the second slide; on\n  video, the first cut is the same second chance.\n- The closer is flat and screenshottable, and it lets the product do the work\n  rather than issuing an install instruction.\n\n## The kill rule\n\n**Published**, from platform averages rather than our own numbers: under 25% of\nviewers still watching past three seconds, keep the body and replace the hook.\nAround 30% is healthy and 40% is exceptional on TikTok.\n\nTwo guards on that rule. Never judge a format before ten posts, and never judge\na new account before 90 days - distribution is a power law, and a handful of\nposts carry most of the reach. Reading the first three posts of a new account\nis reading noise.\n\n## Where that number actually lives\n\nThis matters more than it sounds, because the metric the kill rule needs is the\none hardest to get:\n\n- Views, likes, comments, shares, saves and reach come back through the\n  platforms' public APIs, and Sprid stores them per post.\n- **Three-second hook rate and the retention curve exist only inside the native\n  Instagram and TikTok insights screens.** There is no API field for them as an\n  organic number. If you need them, you open the app.\n- Average watch time is available through both business APIs, which makes\n  `average watch ÷ duration` the honest proxy you can automate.\n- Taps through to your site or store are the number that pays. The rest are\n  directional.\n\n## One picture, many languages\n\nThe reason a demo video is usually made once is that the work is a person\nholding a phone. Split it instead: the wordless part (the footage, the gesture\nscript, the photographs) and the worded part (the captions and cards, bound to\nmarks in the footage rather than to timestamps).\n\nThe rule that makes it hold: **no word is ever inside a picture.** A wordless\ncutaway serves every language you have a string table for, so a seventh language\ncosts its translation and one render rather than a second shoot.\n",
+    "revision": "2997f4c1f66e439a"
+  },
+  {
+    "id": "store-listing",
+    "title": "Write a store listing people can find",
+    "summary": "Explains what each field of an App Store and Google Play listing is actually for, which characters are wasted, and what to change first. Read it before editing a listing, and before accepting any keyword suggestion.",
+    "url": "https://sprid.studio/docs/store-listing",
+    "markdown": "# Write a store listing people can find\n\n**What this guide does:** Explains what each field of an App Store and Google\nPlay listing is actually for, which characters are wasted, and what to change\nfirst. Read it before editing a listing, and before accepting any keyword\nsuggestion.\n\nA listing is two jobs in one form. Some fields decide whether you appear in a\nsearch at all; others decide whether the person who found you taps Get. They\nare not the same words, and writing all of them for one job is the most common\nway a listing quietly costs downloads.\n\n## The fields, and what each one does\n\n**App Store name, 30 characters. Indexed.** Your brand, and - when the evidence\nsupports it - one term describing the category. It is the heaviest indexed\nfield, so a name of only a coined brand word spends the store's strongest signal\non a word nobody searches. Against that: an established name is an asset you\nalready own. Quote the current name and the alternatives side by side and decide\nin the open, rather than letting a keyword tool pick.\n\n**App Store subtitle, 30 characters. Indexed.** The benefit, the use case, or the\none thing that separates you from the app above you in the results. It is read\nby a person mid-scroll and indexed by the store, which is why it is the hardest\n30 characters in the listing.\n\n**App Store keyword field, 100 characters. Indexed, invisible.** Comma-separated,\n**no spaces after the commas** - a space costs a character and buys nothing. The\nrules that reclaim the most room:\n\n- **No word that already appears in your name or subtitle.** Those are indexed\n  already, and repeating them is the single biggest waste of the 100.\n- **No plural beside its own singular.** The store handles that.\n- No category names the store already knows you by, and no competitor brands.\n- Single words, not phrases: the store builds combinations across your terms, so\n  `budget,tracker,expense` covers more searches than `budget tracker`.\n\n**Google Play has no keyword field, and that changes the work.** Play indexes the\ntitle (30), the short description (80) and the full description (4000). So on\nPlay the searchable words have to live inside sentences a human also reads -\nnaturally, a few times, not stuffed. The same app therefore needs two different\npieces of writing, and a listing that pastes the Apple keyword string into a Play\ndescription reads like spam to both the algorithm and the reader.\n\n**The first line of the description survives the fold** (around 170 characters on\niOS before \"more\"). Almost nobody opens the rest - but the store's reviewers do,\nso every claim in it has to be true.\n\n## What to change first\n\nIn order, because this is the order of what it costs to be wrong:\n\n1. **The subtitle**, if it is a slogan. A slogan is indexed and converts nothing.\n2. **The keyword field**, if it repeats the name, carries plurals or has spaces\n   after commas. This is pure reclaimed space and needs no new idea.\n3. **The first two lines of the description**, if they open with the company\n   rather than with what the person came for.\n4. **The name**, last and rarely. It is the one change that costs you the\n   recognition you have already built, and it resets any word-of-mouth search.\n\n## Locales are separate listings, not translations\n\nChoose the locales your actual markets use, and write each one's keyword field\nagainst that language's searches rather than translating the English terms. The\nuseful words are frequently not the translated ones: people search the phrase\nthey say out loud, and in some languages that is a compound noun with no English\nshape at all. Keep what already works in a locale - an existing keyword that\nearns installs is evidence, and replacing it with a tidier translation is how a\nrewrite loses ground.\n\nDo not assume one English locale covers every English-speaking country. Check\nthe store's current localization guidance before making any claim about which\nlocale is indexed where; it changes, and a confident wrong answer here costs a\nwhole market's discoverability.\n\n## When the store will and will not accept a change\n\nKeywords and the description are attached to a **version** on App Store Connect.\nThey push only when an editable version exists - one in \"Prepare for Submission\" -\nand the name and subtitle additionally need an editable app information record.\nSo a listing change is not a live edit: it is a change that ships with your next\nrelease, and a dry run that validates your text locally can still be refused by\nthe store minutes later for this reason alone.\n\nSprid's listing tooling prints the exact fields and values it would send before\nit sends anything, and pushes only on an explicit execute. Read the diff. A\nlisting is one of the few things in marketing where a bad change is visible to\nevery future visitor and takes a release to undo.\n\n## How to tell whether it worked\n\nImpressions, not installs, are the field that moves when a listing's indexed\nwords get better; the conversion rate is what moves when the subtitle and first\nscreenshot get better. Separating those two is the whole reason to change one at\na time.\n\nGive it a full release cycle plus two weeks before reading the result, and\ncompare against the same weekday span, not against the launch spike. If the app\nalso runs paid installs, exclude that traffic first or you will read the ad\nbudget as a listing improvement.\n",
+    "revision": "404de4aaddcf2979"
   }
 ];

package/src/docs/queries.mjs

@@ -63,7 +63,7 @@ op('lemonsqueezy', 'subscription-invoices', 'Read initial, renewal and update in
 op('paddle', 'transactions', 'Read billed transactions by time, status, customer or subscription.', { ...dates, status: array(choice('Status.', ['draft', 'ready', 'billed', 'paid', 'completed', 'canceled', 'past_due']), 7), customer_id: id('Paddle customer ID.'), subscription_id: id('Paddle subscription ID.'), limit, cursor }, [], { start: '2026-08-01', end: '2026-09-01', status: ['completed'], limit: 100 });
 op('paddle', 'subscriptions', 'Read subscription lifecycles by status or price; optional creation dates filter each returned page locally.', { ...dates, status: array(choice('Status.', ['active', 'canceled', 'past_due', 'paused', 'trialing']), 5), customer_id: id('Paddle customer ID.'), price_id: id('Paddle price ID.'), limit, cursor }, [], { status: ['trialing'], limit: 100 });
 for (const source of Object.keys(QUERY_SOURCES).filter(s => QUERY_SOURCES[s].stored)) {
-  op(source, 'posts', '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', 'awaiting_runner']), formatId: integer('Sprid format ID.', 1000000000), 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 });
+  op(source, 'posts', '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', 'awaiting_runner']), 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 });
   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 });
 }
 

package/src/post/cli.mjs

@@ -179,7 +179,7 @@ const LANE_KEYS = new Set([
   // opening card is still arriving there says so. See `coverFrame`.
   "coverAtMs",
   // composed lanes: what Sprid is asked to render, and what may not be said
-  "format", "template", "contentType", "neverSay", "sourcesRequired", "platforms",
+  "template", "contentType", "neverSay", "sourcesRequired", "platforms",
 ]);
 
 /**
@@ -515,9 +515,7 @@ export default {
     carousels: {
       kind: "composed",
       spec: "social/specs/<slug>.json",
-      // Optional: the Sprid format a post is created from, and the template
-      // every card renders through.
-      // format: <format id from this account>,
+      // Optional: the template every card renders through.
       // template: <template id from this account>,
       expect: { slides: [5, 9], words: [0, 30] },
       hashtags: [3, 6],
@@ -1462,15 +1460,12 @@ async function cmdDraft(cfg, argv) {
         // Public titles come from approved copy; identifiers stay in internalName.
         title: m.post?.title ?? postTitle(caption, m.slug),
         internalName: m.post?.internalName ?? m.slug,
-        // A composed lane may name the Sprid format its posts are made from,
-        // and creating with it is what scaffolds the right slide roles.
-        ...(cfg.lanes[m.lane]?.format ? { formatId: cfg.lanes[m.lane].format } : {}),
       }));
     const carousel = (m.kind ?? "reel") === "carousel";
     const composed = isComposed(m);
 
     // **A new post already has slides, and `POST /posts` does not return
-    // them.** It scaffolds one row (or one per the format's template) and
+    // them.** It scaffolds one row and
     // answers with the post alone, so `post.slides?.[0]` was always undefined
     // and every draft this package made carried an EMPTY leading slide with
     // the real media behind it - a blank first frame on a reel, a blank first