@sprid/cli 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+sprid follows semver: a breaking change to a command's arguments, its output
+shape or its exit codes is a major release.
+
+## 0.1.2 - 2026-09-22
+
+- Published as `@sprid/cli`. The command is still `sprid`.
+- Reports the API's supported-version floor, and stops with the upgrade
+  instruction when the API refuses a version as too old.
+- `bugs` reaches the package, the README drops a maintainer-only section, and
+  the sample output is generic.

package/LICENSE

@@ -0,0 +1,14 @@
+Copyright (c) 2026 Väder AB. All rights reserved.
+
+Use is subject to Sprid's Terms of Service at https://sprid.studio/terms,
+which set out what you may do with these files.
+
+Bundled third-party components keep their own licences, which are included
+beside the files they cover.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README-post.md

@@ -0,0 +1,615 @@
+# `sprid post` — build posts in your own repo, then push them to Sprid
+
+Build posts wherever you like, then push them to Sprid. **A post is a reel (one
+video file) or a carousel (a directory of images)** - the registry, the gate,
+the preview and the upload are the same for both, and a lane says which it is.
+
+```bash
+bunx @sprid/cli post init          # what are your reels made of, and do you need this
+bunx @sprid/cli post new <slug>    # scaffold a spec (recipe lanes)
+bunx @sprid/cli post build         # run the lane's builder - yours, or the recipe
+bunx @sprid/cli post register      # measure every finished file into the registry
+bunx @sprid/cli post check         # the gate
+bunx @sprid/cli post preview       # the whole batch on one page: a grid, and a feed
+bunx @sprid/cli post push          # upload to Sprid
+bunx @sprid/cli post draft         # post + slide + video + caption
+bunx @sprid/cli post status        # one table, local and remote
+```
+
+## Start with the pixels
+
+Cloud reel rendering is paused. Keep a text reel's spec, visual system and
+renderer in the app repo, then use Sprid Local to register, check, upload and
+publish the finished MP4. The same handoff covers photographs, screen recordings
+and any other composition whose pixels the app owns.
+
+## Two ways to make the file
+
+A lane says how its media is built, and there are exactly two answers:
+
+```ts
+build: "bun run scripts/make-reel.ts --spec <spec> --out <out>"   // your renderer
+build: { recipe: "stills", track: "assets/bed.mp3" }              // the built-in
+```
+
+Everything downstream - `register`, `check`, `push`, `draft` - cannot tell them
+apart, so you can start on the recipe and grow into your own renderer without
+changing anything else.
+
+There are two built-in recipes, `stills` and `screen`.
+
+**`stills`**: pictures, a slow eased push on each, a
+cross-fade between, music measured and baked. It answers the thing nothing else
+does - material that is neither text nor already a video. It **prints the ffmpeg
+command it ran**, which is the whole difference between a recipe and a
+framework: the output is a starting point you edit, not a black box.
+
+A **spec** is one JSON file per reel and it is the durable artifact - the mp4
+regenerates, the spec is what you review and commit:
+
+```json
+{ "slug": "…", "images": ["a.jpg", "b.jpg"], "track": "bed.mp3",
+  "holdMs": 5800, "caption": "…" }
+```
+
+**`screen`** records your own app being used. See the next section.
+
+**Beyond that it renders nothing.** How a file was made is your repo's business.
+This package's whole subject is *a finished local file becoming a Sprid draft,
+reproducibly and with the checks* - which is why it serves a repo with a bespoke
+render pipeline and a repo whose reels come out of After Effects equally well.
+
+**It does not need an agent.** Everything goes through the REST API with a
+`sprd_` personal access token, so CI can run it. The MCP server is the
+agent-facing convenience over the same endpoints, not the only door.
+
+## `screen`: the app, driven and recorded
+
+```ts
+build: { recipe: "screen", app: { bundleId: "com.example.app", prepare: "…", launchMs: 19000 } }
+```
+
+It boots an iOS simulator, dresses the status bar, runs a **gesture script**
+against the app, records the screen, and cuts the recording into a 9:16 reel
+with TikTok-style captions, a touch indicator and music.
+
+**The reason it exists is the seven-language version.** A demo reel is normally
+impossible to remake in another language, because the work is a person holding a
+phone. Here that work splits in two:
+
+```
+social/scripts/complete-task.json    the finger's path. NO WORDS.
+social/specs/complete-task-en.json   the locale, the captions, the music.
+social/specs/complete-task-sv.json   the same path, a different language.
+```
+
+A locale then costs its translation and one 90-second run. Nothing else.
+
+### The script
+
+Normalised coordinates, `0..1` of the device screen, and five kinds of step:
+
+```json
+{ "steps": [
+  { "mark": "home" },
+  { "wait": 1600 },
+  { "tap": [0.388, 0.730], "note": "Create task" },
+  { "settle": 1900 },
+  { "swipe": [0.8, 0.62, 0.22, 0.62], "duration": 300 },
+  { "swipe": [0.5, 0.72, 0.5, 0.46], "duration": 800, "precise": true },
+  { "shell": "xcrun simctl openurl <udid> \"app:///demo?lang=<locale>\"" }
+] }
+```
+
+- **`mark`** names a moment. Captions bind to marks, never to seconds, which is
+  the only reason the same script survives a run that is two seconds longer.
+- **`settle`** waits for the screen to change and then to stop changing, up to
+  the given ceiling. Both halves matter - see below.
+- **`swipe`** is a flick by default: it is still moving when the finger lifts,
+  so iOS computes momentum. `precise: true` is an eased drag that stops where
+  the finger stops, which is what you want for reading rather than browsing.
+- **`shell`** runs a command mid-script, with `<udid>`, `<locale>` and
+  `<bundleId>` filled in from the spec - so an app that picks its language
+  through a deep link keeps ONE script.
+
+Everything else - Metro, the dev client, the demo seed, the login - is welded to
+your repo and belongs in `app.prepare`, a command the recipe runs and waits for.
+**`prepare` must not launch the app**; the recipe does, after the clapperboard.
+
+### The spec
+
+```json
+{ "slug": "complete-task-sv", "locale": "sv", "device": "iPhone 17",
+  "script": "social/scripts/complete-task.json",
+  "render": { "speed": 1.7, "capY": 0.78, "capSize": 76, "pill": 0, "background": "blur", "drift": 0 },
+  "captions": [ { "at": "home", "text": "Jag säger ja innan jag läst klart." } ],
+  "broll": { "clip": "assets/broll/couch.mp4", "seconds": 2.4 },
+  "track": "assets/audio/bed.mp3",
+  "caption": "the post caption" }
+```
+
+Captions are chunked into two or three words and timed by the same prosody model
+Sprid's own renderer uses: **weights, not milliseconds**, so a word's share of
+its beat tracks its syllables and the pauses sit at the punctuation. A beat that
+is longer than its words need is **left empty at the end rather than stretched**
+- that silence is the moment the viewer looks at the app with nothing written
+over it, which is the product demo.
+
+`speed` speeds the recording up; 1.6-1.7 is where a UI demo lands in the 15-18s
+band without reading as a fast-forward. `broll` cuts a clip in front, hard, never
+a dissolve.
+
+**`drift` is 0 and should stay there.** It offsets the phone a few pixels on two
+sine pairs to imitate a hand. It does not read as one: the status bar in a screen
+recording is pin-sharp, so the movement registers as the video being unstable
+rather than as being filmed. A screen recording holds still.
+
+### Iterating: `--recut`
+
+```bash
+sprid post build <slug>            # drive the app and cut
+sprid post build <slug> --recut    # re-cut what is already recorded, no simulator
+```
+
+**This is the loop that matters.** A caption, a beat, where the captions sit,
+the speed, the background - none of it needs the app driven again. `cut.json`
+next to the recording holds what a re-cut needs: the timeline, the second
+clapper's wall time and the device's pixel size.
+
+### Five things it does that are not obvious
+
+**`settle` waits for the screen to become something else, not to stop moving.**
+Waiting only for quiet cannot tell *the transition has finished* from *it has not
+started*, and a Debug build behind Metro can run seconds behind the script - and
+while it is behind, the screen it is still showing is perfectly quiet. Every
+settle then returns on a stale frame and the next tap lands on a screen that is
+about to be replaced. It compares against a frame captured before the gesture
+that caused the change.
+
+**Two clapperboards, because the recorder's clock is not the wall clock.**
+`simctl io recordVideo` reports nothing about when it opened the stream, so the
+run flashes the springboard dark before the app comes up and again after the
+script, and solves `videoSeconds = v0 + k · wallMs`. Measured `k` here ranged
+0.76 to 1.00 across runs. One flash cannot see a rate error - the first version
+had one, and its last caption was four seconds off the screen it described.
+
+**Full-resolution probes starve the recorder.** `settle` screenshots twice a
+second while recording. As PNG, one heavier app came back holding 76% of the
+elapsed time; the probes now run through `baguette screenshot --scale 4`, a
+twentieth of the pixels for ffmpeg to decode. A recording that solves below
+**0.9x wall is treated as spoiled and fails**: the solve keeps the captions in
+sync but the missing time cannot be put back, so the app's own motion plays fast
+on top of whatever `speed` asked for.
+
+**Scratch goes outside your repo** (`$TMPDIR/sprid/<repo>/<slug>`) unless a
+lane sets `tmp`. Inside it, Metro's watcher sees every probe screenshot, sends a
+Fast Refresh, and RN drops its blue "Refreshing…" banner over the frame.
+
+**Input goes through `baguette`, which does not touch the machine.** It injects
+through SimulatorKit's private symbols with the iOS-26 calling conventions: the
+pointer never moves, the Simulator never comes to the front, and you can keep
+working through a run. Its `input` command streams newline-delimited JSON
+gestures, which is the part that matters - **we keep our own velocity curve**,
+where a canned `swipe --duration` would be the linear interpolation that makes a
+scripted scroll read as scripted.
+
+Two details inside that, both of which cost a take:
+
+- **Swipes stream, taps do not.** The streaming path is `IOHIDDigitizerDispatch`,
+  built for continuous gestures. React Native surfaces can accept a
+  streamed tap and the one UIKit surface, the tab bar, silently did not.
+  `baguette tap` lands on it every time, and a tap has no timing worth owning.
+- **A tap must not move.** An earlier version jittered the touch a pixel or two
+  during the hold, on the theory that a finger is never still. Nothing can see it
+  - a screen recording has no cursor in it - and UIKit reads those moves as the
+  start of a drag and cancels the tap.
+
+Without baguette it falls back to posting CGEvents through a compiled Swift
+helper (`src/screen/simkit.swift`), and **that path owns the pointer for the
+length of the run**. It is a fallback, not a preference: the Simulator ignores
+events posted to its process, tested both plain and with the window-number
+routing trick, so the global HID tap is the only other way in. simkit stays
+either way, because it also rasterises the caption cards through CoreText -
+Homebrew's ffmpeg has neither `drawtext` nor `subtitles`.
+
+### What it needs
+
+macOS with Xcode 26, an Apple Silicon Mac, a simulator with your app installed,
+`ffmpeg`, and `brew install baguette`. No npm dependency. Without baguette it
+still runs, on the CGEvent fallback, which needs the terminal to hold macOS
+Accessibility permission and **takes over the pointer for the length of the
+run**.
+
+The status bar is dressed for a reel rather than for the store: the **host
+clock**, not 9:41, and a battery in the seventies rather than 100% and charging.
+9:41 reads as an advertisement, and the app's own content gives the real time
+away anyway - a row logged during the recording carries the wall clock, so a
+9:41 status bar above it is a tell. `statusBarTime` and `battery` in the spec
+override both.
+
+## Two kinds of post
+
+```ts
+films: { media:  "out/<slug>.mp4",        caption: "out/<slug>.caption.txt" },  // a reel
+decks: { slides: "decks/<slug>/*.jpg",    caption: "decks/<slug>/caption.txt" }, // a carousel
+```
+
+A lane that names `slides:` is a carousel and needs to say nothing else; the
+slug is the **directory**, its files are the slides, and **they are ordered by
+filename**, so name them `01`, `02`, `03`. That order is the most consequential
+thing about a deck and it belongs somewhere a person can see it, not in a JSON
+array. The record hashes the slides *and their order*, since the same pictures
+in a different order are a different post.
+
+What each kind is measured and gated on:
+
+| | reel | carousel |
+|---|---|---|
+| record | duration, dimensions, LUFS, sha256 | per-slide dimensions, ratio, sha256; count |
+| gate | `duration` `loudness` `batchSpread` | `slides` `aspect` |
+| both | `caption`, `provenance` | `caption`, `provenance` |
+| in Sprid | one video on one slide, `contentType: reel` | one image per slide, `contentType: image` |
+
+**`aspect` is the one that catches a real defect you cannot see locally.**
+Instagram crops every later slide to the first slide's shape, so a deck mixing
+4:5 and 1:1 publishes with the sides cut off things nobody checked - and every
+local preview shows the files as they are, uncropped and fine.
+
+A check that does not apply to a kind reports `skip`, never `pass`: a carousel
+with four green video checks would be worth less than no check at all.
+
+## The third kind: a post Sprid composes
+
+**Most posts are words on a background, and those are rendered on the server** -
+templates, backdrops, fonts, timing. There is no local file, so there is nothing
+for ffmpeg to measure and nothing to upload. A `composed` lane is for wanting
+the *copy* here anyway:
+
+```ts
+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"],
+  sourcesRequired: true,
+},
+```
+
+The spec IS the post:
+
+```json
+{ "slug": "…",
+  "slides": [{ "role": "hook", "text": "…" },
+             { "role": "body", "text": "The plan includes 10 projects", "source": "docs/guides/plans.md" }],
+  "caption": "… \n\n#a #b #c" }
+```
+
+**One caption per platform, when the repo has one.** Vocabulary can differ between
+platforms. A lane may write a second file beside its caption,
+`<caption>` with `.tiktok` before the extension (`out/<slug>.caption.tiktok.txt`).
+`register` copies it to `social/captions/<slug>.tiktok.txt` and `draft` sends
+it as `captionTiktok`; absent, TikTok gets the Instagram string.
+
+**The tags go at the end of the caption.** Sprid publishes one string per
+platform and has no hashtag field to send them to, so there is no `hashtags`
+key here either - a spec carrying one is refused by name rather than quietly
+ignored. The caption in the registry is therefore the whole published text,
+which is what the tag-count gate and the drift check read.
+
+`build` and `push` have nothing to do; `register`, `check`, `draft` and `status`
+work exactly as they do for a file. What you get for it is three checks a
+rendered post cannot have:
+
+- **`words`, per card and never totalled.** A deck averaging twenty words with
+  one card at sixty is the deck an average hides, and the long card is the one a
+  reader stops on.
+- **`voice`.** The phrases this account has decided it does not say, plus the
+  punctuation it does not use. The mechanical half of a voice; the rest still
+  needs a reader.
+- **`sources`.** A card stating a number names the file it came from and the
+  check *opens* it. This is the whole gate for anything where a wrong figure is
+  the unforgivable error: a slide keeps reading true long after the file behind
+  it was renamed.
+
+**It is opt-in, and skipping it is a real answer.** If the words do not have to
+answer to anything in your repo, compose the post in Sprid and keep nothing
+here.
+
+## The registry
+
+Committed to *your* repo:
+
+```
+social/posts/<slug>.json     the record: sha256, size, sprid ids, how it was built
+social/captions/<slug>.txt   the caption, verbatim
+```
+
+The directory used to be `social/reels/`, which is still read - a record already
+committed in somebody's repo is not worth breaking over a rename - and `status`
+says how many are still sitting there. Renaming it is the whole migration.
+
+**No media in git.** The bytes go into Sprid's own storage through the presigned
+upload, and the manifest keeps a sha256, so a file that no longer matches its
+record is caught before it is pushed - without keeping the file.
+
+The caption is copied *into* the registry rather than pointed at, because it is
+usually generated into a scratch directory. It is the most reviewable artifact
+most pipelines produce and it belongs where somebody can read it in a diff.
+
+## Config
+
+```ts
+// sprid.config.ts
+export default {
+  account: "myapp",             // the ACCOUNT slug, not the workspace name
+  tokenEnv: "SPRID_PAT_MYAPP",  // optional, and see Auth before skipping it
+  registry: "social/",
+  lanes: {
+    reels: {
+      // `media:` one file per post · `slides:` a deck of images
+      // · `kind: "composed"` is for server-rendered carousel copy
+      media: "path/to/output/<slug>.mp4",
+      caption: "path/to/output/<slug>.caption.txt",
+      expect: { durationMs: [15_000, 50_000], lufs: [-16, -12] },
+      hashtags: [4, 6],
+      captionMustContain: ["Photos via Wikimedia Commons:"],
+    },
+  },
+  checks: ["duration", "loudness", "batchSpread", "caption"],
+};
+```
+
+A **lane** is where one kind of finished media lives. The package ships none,
+because what a lane is depends entirely on how you make things. `<slug>` in a
+path is the only substitution there is, and it is also how `register` discovers
+what exists.
+
+### The checks
+
+| check | what it refuses |
+|---|---|
+| `duration` | a file outside the lane's range - usually a render that stopped early |
+| `loudness` | integrated LUFS outside the range |
+| `batchSpread` | a file more than `maxDeviationDb` (1.2) from **its own lane's** median. One file's loudness says nothing; the step between two posts in a row is what a listener hears |
+| `caption` | a `neverSay` match, an invalid configured ending, a missing `captionMustContain` string, or a hashtag count outside `hashtags` |
+| `slides` | a deck outside `expect.slides`. Instagram takes 20, TikTok 35, and a deck of two is a post that did not get made |
+| `aspect` | a deck that mixes ratios, or slides under `expect.minWidth`. Instagram crops every later slide to the FIRST one's shape, so a mixed deck publishes with the sides cut off things nobody checked - and it looks right in every local preview |
+| `provenance` | nothing. It reports whether the record knows the command that made the file, so a batch where most rows skip it is a batch whose provenance lives in somebody's terminal history |
+
+`captionMustContain` is for licence terms rather than style. A Creative Commons
+import is somebody's work and the licence is only free if the credit is there;
+a Mapbox static image may only drop its on-image attribution if the attribution
+appears beside it. Both are things you notice a week after publishing, or not at
+all.
+
+A check that cannot run reports `skip`, never `pass`.
+
+## The record remembers how the file was made
+
+```bash
+sprid post register <slug> --built-with "make-reel --spec x.json --map --depth"
+```
+
+Record the command that produced the measured bytes so the build can be repeated.
+A lane with a `build:` records that command automatically; a
+pipeline run by hand records it with `--built-with`; and the `provenance` check
+reports - never refuses - when a record cannot say. The preview prints the line
+under each card, one click to copy.
+
+## `preview`, looking at the batch before it is real
+
+```bash
+bunx @sprid/cli post preview --serve      # a local server, opens in your browser
+bunx @sprid/cli post preview --open       # file://, fine for watching, cannot scrub
+bunx @sprid/cli post preview --lane collage --copy --out ~/Desktop/reels
+```
+
+It reads the registry and nothing else, so it is the same command in every repo,
+and it writes one disposable HTML file with **two views**, because a batch and a
+post are two different questions:
+
+- **Grid.** Everything at once, small. Hover plays a reel and walks a deck, the filter matches slug and
+  caption, and a card carries the caption itself and nothing derived from it -
+  the length, the loudness, the check result and the Sprid state ride along as
+  badges. This is where you see repetition, an outlier, a caption that ran long.
+- **Feed.** One post at reading size with its caption under it, arrow keys
+  between them, `m` for sound, `esc` back. A carousel advances by itself at
+  reading pace (`space` stops it, `[` `]` step it, the dots say how many are
+  left), because the question a batch review asks of a deck is whether it holds
+  together as one set, and that is a thing you watch rather than click through. It is the only view that answers
+  *would I stop on this*, because it is the shape a reader meets. Each reel has
+  its own `#slug` address, so a position is a link.
+
+**`--serve` watches and reloads.** The registry, the lanes' media directories
+and this package's own source are all watched; a change rebuilds the page and
+refreshes the tab you already have open, and since the current reel lives in the
+URL hash it comes back to where you were. Running the command again while a
+server is up says so and opens nothing, rather than stacking tabs.
+
+Media is **symlinked**, not copied: a batch is gigabytes and this page is meant
+to be cheap enough to regenerate without thinking about it. `--copy` is for a
+page that has to travel. **`--serve` is worth the extra word** - over `file://`
+a browser cannot seek inside an mp4 and Safari will not play a symlink at all.
+
+A registered reel whose file is not on disk is drawn as a **missing card**,
+never dropped: the mp4s regenerate from their specs and routinely are not there,
+and silently omitting missing files would hide incomplete work. A
+file whose size no longer matches its record is badged instead of trusted
+(`--verify` spends the sha256 rather than comparing sizes).
+
+## What `draft` does
+
+1. `POST /videos/upload-url` → PUT the file → `POST /videos/:id/confirm`
+2. `POST /posts`
+3. `PATCH /slides/:id { videoId }` - **this is what makes the post publish your
+   exact file** with its own audio, rather than be re-composed from the slide's
+   template in the render container
+4. `PATCH /posts/:id { contentType: "reel", captions, location,
+   audio: { silent: true }, status: "draft" }` - the caption carries the
+   hashtags; there is no separate tag field
+5. `GET /posts/:id`, and compare it to what was asked for
+
+**`audio: { silent: true }` is not optional when the music is already in your
+file.** A reel with no `trackAssetId` round-robins the account's track library,
+so leaving `audio` unset lays a second bed over the first.
+
+**Step 5 verifies that fields were stored.** An older server may accept a request
+while ignoring fields its schema does not support. Read them back and retain any
+mismatch in the registry so `status` can report it.
+
+**A new post arrives with a slide already on it**, and `POST /posts` answers
+with the post alone - no `slides` key. `draft` therefore reads the seats back,
+adds the ones it is short of and deletes the ones it does not need. Trusting the
+create response is how every draft ends up with an empty leading slide and the
+real media behind it.
+
+`draft` stops at `draft`. Moving a post to `ready` is the last gate before
+something is public, and that stays a person's call.
+
+## Local production and crossposting
+
+The consuming repo owns media, specs and its build commands. Sprid owns accounts,
+channels and publishing state. The registry connects them without requiring a
+particular renderer or access to another repository.
+
+The CLI bundles the rules used by its offline checks. `check --deep` asks the
+server for the actual platform projection of an existing post. Review both the
+content and each platform's title, caption and cover before publishing.
+
+- `postTitle()` derives a title from the caption's first line when present and
+  reconciles it on subsequent drafts. Review it as published copy.
+- `coverAtMs` selects a cover frame per lane. Choose a completed, readable frame.
+- A `.tiktok.txt` sibling provides a separate TikTok caption; otherwise it uses
+  the shared caption. YouTube's description uses the shared caption.
+
+## `sync`: a re-render, into posts that already exist
+
+**A booked post is never edited. The source is re-rendered and the queue catches
+up.** That is the design decision, and the alternative is worse than it sounds:
+reaching into Sprid to swap a file on a scheduled post makes the queue the
+source of truth for content, and then a spec and a published post can disagree
+with nothing able to say which is right. Here the registry owns the content,
+Sprid owns the calendar, and `sync` is the one command that reconciles them.
+
+```bash
+sprid post sync                     # what differs, and what it would send
+sprid post sync --execute           # send it
+sprid post sync --lane collage      # scope it
+```
+
+It diffs local against remote, uploads only what changed, re-points the existing
+post's slide at the new file, and **leaves the schedule alone** - the post keeps
+its slot. Three rules, two of them refusals:
+
+- **A post that is out is frozen.** It reads the live status and writes only to
+  `draft` and `ready`. Anything else is skipped by name, including a status this
+  package has never heard of: an unknown state is far more likely to be further
+  along the pipeline than behind it. Re-posting is a new slug, not an edit.
+- **It never creates a post.** No `postId`, no sync - that is `draft`'s job, so
+  a sync cannot widen a batch by accident.
+- **It does the minimum.** Media changed, caption changed, or neither. A slug
+  whose caption moved does not get its video re-uploaded.
+
+Changing media across a booked queue requires reconciling both uploaded media and post metadata.
+`sync` keeps that operation reproducible.
+
+**`mediaShaAtPush` is what makes it possible**, and it is the counterpart of
+`captionShaAtDraft`, which existed from the start. A manifest written before it
+reads as *unknown*, and unknown counts as stale - a record that cannot say what
+was uploaded cannot say it is current. `sync --adopt` is the one-time migration
+for a batch that was never rebuilt: it records what is on disk as what was
+uploaded and sends nothing. It is an assertion and it can be wrong, so scope it.
+
+## `doctor`: which Sprid, and can it be reached
+
+**A credential names the service it belongs to. Use both halves or neither.**
+
+`sprid login` writes `~/.sprid/credentials.json` with a token *and* the API it
+was issued against. Reading a token from one configuration and defaulting to another
+server can make a working service appear unavailable. Keep the token and URL paired.
+
+- `credentials.json` is read for **both** the token and `apiUrl`, after
+  `SPRID_URL` and a repo's pinned `tokenEnv`.
+- `sprid post doctor` dials **every** candidate URL it knows about, not only
+  the winner, and prints the account and its live channels from whichever
+  answers. A disagreement between candidates is the failure mode, so the command
+  shows the disagreement rather than resolving it silently.
+
+```
+  yourapp  using http://localhost:4005
+
+  → ~/.sprid/credentials.json   http://localhost:4005
+    default                     https://api.sprid.studio
+
+  http://localhost:4005    ok 175ms  account 3  instagram:active tiktok:active youtube:active
+  https://api.sprid.studio unreachable TimeoutError
+```
+
+**`status` prints the registry and `doctor` prints the world.** "Several posts drafted"
+reads identically whether Sprid is up, down, or a different Sprid than the one
+holding your posts; `doctor` is the command that can tell you which.
+
+## `pull`: the schedule, back into the registry
+
+**The queue lives in Sprid, and until `pull` nothing local could read it.** A
+post is committed; when it publishes was not. So the repo could not answer "what
+goes out tomorrow" or "which one went out last" without the API being up, and a
+booking made weeks ago left no trace anybody could review in a diff.
+
+`pull` writes each post's status and dates into `sprid.remote` on its manifest,
+which is what lets `status` print a calendar and work offline.
+
+> **It was written blind.** The API was unreachable for the whole session it
+> went in, so `scheduleOf` tries the key names a post plausibly carries and
+> returns null rather than inventing one. `pull` prints how many posts it could
+> not read a date from - **if that is not zero on the first real run, put the
+> real key in `scheduleOf` and add it to the test.** `sync` has no such doubt:
+> every call it makes is one `push` and `draft` were already making.
+
+## Auth
+
+`SPRID_TOKEN`, this repo's `.env`, or `~/.sprid/token`. Make one in Sprid under
+Settings → Tokens; it starts with `sprd_`. `SPRID_URL` overrides the API host,
+default `https://api.sprid.studio`.
+
+**A PAT is workspace-scoped, and a machine that posts for three brands holds
+three of them.** `tokenEnv` names the one this repo is allowed to use, and when
+it is set nothing else is tried - a run that quietly fell back to the ambient
+token would authenticate against workspaces this repo must not be able to reach,
+and nothing in the output would say so. Set it in any repo that is not the only
+one on the machine.
+
+## Account-specific copy checks
+
+`neverSay` lists exact strings forbidden in captions and composed slide text.
+Punctuation is allowed unless configured there, for example `["—", "!"]` for an
+account that avoids those characters. `captionEndsSentence` optionally requires
+terminal punctuation. `captionEndWords` optionally lists trailing words that
+indicate an incomplete caption in this account's language; the default is empty.
+Do not reuse another account's phrase list or language rules without reviewing them.
+
+## Destination selection and structured output
+
+Local media can come from any renderer or framework. The `screen` recipe is an
+optional iOS simulator workflow; existing Expo projects can keep their capture
+scripts. Finished MP4s and image decks do not require Expo or Xcode. A custom
+`build` command can run a named slug without a Sprid spec; built-in recipes still
+require their specs. Use `--lane` when multiple builders could handle that slug.
+
+Set `platforms: ["instagram"]` at the config or lane level to check only your
+intended destinations in the `crosspost` check. A post spec/manifest can override it; `check --platforms
+instagram,tiktok` overrides the selection for that check. `register --platforms
+instagram` records a post's selection. With no selection, the existing Instagram,
+TikTok and YouTube checks remain the default. This selects validation targets;
+publishing destinations are still chosen when scheduling in Sprid. Local projection
+rules currently cover Instagram, TikTok and YouTube; other platforms report a
+skip, and `--deep` reads the booked post’s server projection. Media checks retain
+their existing defaults and can be customized with `lane.expect`.
+
+`sprid post <command> --json` writes one JSON result to stdout and diagnostics to
+stderr, including output from custom builders. Results include `command`,
+`account` and registry `posts` when available; checks include failures and a
+nonzero exit status. `post help --json` includes the usage text. Original argument
+order is preserved, including values of local flags such as `--lane` and `--out`.