Teach editable playlists and resumable screen publishing

components.lock.json

@@ -3,10 +3,10 @@
   "state": "resolved",
   "cli": {
     "repository": "screenrig/cli",
-    "commit": "e21fcc552442e4dbd08d81cdd85abaccf76b0fbf",
+    "commit": "880abf4fbf53af93e30ed59553ba1320db649e9f",
     "artifact": {
       "file": "screenrig-cli.tgz",
-      "sha256": "cfea694d7c14a0008e521174e46376fb767283a54032137fe95d46676b21caaa"
+      "sha256": "19c4d7843edce94b35f73fc262ab4e52e6b84fb4266bd32b14e1f287def07c83"
     }
   }
 }

plugins/screenrig/cli/README.md

@@ -156,3 +156,63 @@ Development profiles are described in [CONTRIBUTING.md](https://github.com/scree
 
 See [`RELEASING.md`](https://github.com/screenrig/cli/blob/main/RELEASING.md) for CalVer stamping and npm publication.
 Report suspected vulnerabilities through the [security policy](SECURITY.md).
+
+## Prepare, publish, and edit playlists
+
+For ready images and videos, prepare a full-screen playlist in playback order:
+
+```sh
+screenrig playlist init med_POSTER med_VIDEO --name "Lobby loop" --screen scr_LOBBY --output lobby.json
+screenrig playlist preview lobby.json --output preview --contact-sheet
+screenrig screen publish scr_LOBBY lobby.json --expect-rev 7
+```
+
+Inspect the preview before publishing. `playlist init` reads media metadata and
+screen observations but makes no remote writes. It creates one page per media ID,
+with `contain` fit, a black background, and a 200 ms crossfade. Images last 8000 ms;
+videos are muted, do not loop, and advance on completion. Use `--duration-ms` for
+image duration and `--fit contain|cover|fill` for content fit. Override the canvas
+with both `--target-width` and `--target-height`; these also work without `--screen`.
+Unknown or multiple reported surfaces require explicit dimensions. Output files
+must not already exist.
+
+`screen publish <screen-id> <file>` creates a new playlist, assigns it using the
+expected **screen** revision, and reads back the assignment. It does not update an
+existing playlist by name. A name collision requires a different name or an
+explicit `playlist update`. Its JSON result reports `playlist_id`,
+`playlist_revision`, `screen_id`, `screen_revision`, `assignment_verified`, and
+`playback_verified`. Assignment verification does not prove playback; request and
+inspect a screenshot and relevant playback evidence separately.
+
+Publishing saves a private local journal automatically. After an ambiguous failure,
+repeat the identical command and input with the same config to resume. If playlist
+creation succeeded before assignment failed, the error identifies the created
+playlist. Do not delete it or start another create to recover. A revision conflict
+requires inspecting the screen and reconciling the intended assignment; an already
+created playlist can be assigned explicitly with `screen assign`. Publishing never
+silently refreshes the expected revision. Unfinished recovery stops after the
+24-hour server idempotency window; inspect and reconcile before making more writes.
+
+To edit an existing playlist:
+
+```sh
+screenrig playlist show pl_EXISTING --output lobby.json
+screenrig playlist update pl_EXISTING lobby.json --expect-rev 4
+```
+
+`playlist show --output` writes the editable `{name, pages}` document and returns
+its path, `playlist_id`, and source `revision` on stdout. Use that returned revision
+for the update. It preserves dynamic selectors, schedules, motion, and pinned
+application releases, removing server-derived media and timing fields. Comments
+remain separate. Plain `playlist show` is an inspection response; `--editable`
+without `--output` returns `data.document`, `data.playlist_id`, and `data.revision`.
+Updating a playlist affects every screen assigned to it.
+
+Playlist validate, create, update, preview, and screen publish accept `-` as their
+input file to read stdin. JSON envelopes are never written into authored files.
+`--expect-rev` is the preferred revision spelling; `--if-match` remains a compatible
+alias. Supply only one. The HTTP revision contract is unchanged.
+
+Generation accepts either `--prompt TEXT` or `--prompt-file FILE`, including
+`--prompt-file -` for stdin. The file is the complete prompt, with no trimming;
+the existing 4000-character limit applies. Prompts are excluded from diagnostics.

plugins/screenrig/skills/screenrig/SKILL.md

@@ -95,13 +95,15 @@ shapes belong in prepared content, not additional native playlist primitives.
 
 1. Prepare and inspect the content at the intended size. Generation stores its
    returned media ID directly; do not upload it again.
-2. Write or update the authored playlist file. Read [playlists](references/playlists.md)
-   before editing its shape, motion or schedule. Keep at least one page always eligible.
-3. Create or update the playlist, then assign it to the resolved screen. Use the
-   current revision with `--if-match` when changing an existing resource.
-4. Read back the assignment, request a screenshot, and inspect relevant playback
-   and events. Report what was observed and any remaining uncertainty. A command
-   succeeding alone does not prove physical display.
+2. For full-screen images or videos, use `playlist init` to prepare the authored
+   file from media IDs and screen dimensions. For other layouts, author the file
+   using [playlists](references/playlists.md). Preview and inspect it.
+3. Publish a new playlist with `screen publish SCREEN_ID FILE --expect-rev REV`.
+   To edit an existing playlist, obtain its file with `playlist show ID --output
+   FILE`, then use `playlist update` with the returned revision. Updates affect
+   all assigned screens. See the playlist reference for partial-failure recovery.
+4. Request a screenshot and inspect relevant playback and events. Assignment
+   readback alone does not prove physical display. Report the observed evidence.
 
 For screen controls, screenshots, comments, events and feedback, use
 [operations](references/operations.md). For app uploads, page completion and K/V,

plugins/screenrig/skills/screenrig/references/applications.md

@@ -36,7 +36,7 @@ revision with `app show`, then publish a new release:
 
 ```bash
 screenrig app show app_EXAMPLE
-screenrig app update app_EXAMPLE ./lobby-board --if-match 3
+screenrig app update app_EXAMPLE ./lobby-board --expect-rev 3
 ```
 
 `app update` preserves application identity, name, and application K/V. It uses
@@ -117,11 +117,11 @@ must carry `controller: true`. Do not set `controller` on a `duration` or
 ```bash
 screenrig playlist create ./lobby-board.json
 screenrig screen list
-screenrig screen assign scr_EXAMPLE --playlist-id pl_EXAMPLE --if-match 3
+screenrig screen assign scr_EXAMPLE --playlist-id pl_EXAMPLE --expect-rev 3
 ```
 
 Take `--playlist-id` from `data.id` of the `playlist create` result. Take
-`--if-match` from the screen's current `revision`, which both `screen list` and
+`--expect-rev` from the screen's current `revision`, which both `screen list` and
 `screen show` return. `revision_conflict` means refetch and retry. Do not
 invent the revision.
 
@@ -145,7 +145,7 @@ Application K/V is binary-safe. Use exactly one value mode.
 screenrig kv set --application-id app_EXAMPLE lobby --json-value '{"open":true}'
 screenrig kv get --application-id app_EXAMPLE lobby
 screenrig kv list --application-id app_EXAMPLE
-screenrig kv delete --application-id app_EXAMPLE lobby --if-match REVISION
+screenrig kv delete --application-id app_EXAMPLE lobby --expect-rev REVISION
 ```
 
 `kv get` returns the stored bytes only as `data.value_base64`, including when

plugins/screenrig/skills/screenrig/references/commands.md

@@ -13,10 +13,10 @@ agent disconnect --yes [--allow-lockout]
 dashboard [--print-url]
 app pack <directory> [--output FILE]
 app upload <directory> [--name NAME] [--no-wait] [--poll-ms MS]
-app update <id> <directory> --if-match REVISION [--no-wait] [--poll-ms MS]
+app update <id> <directory> --expect-rev REVISION [--no-wait] [--poll-ms MS]
 app list
 app show <id>
-media generate --prompt TEXT [--aspect-ratio RATIO] [--quality low|medium|high] [--tag TAG]
+media generate (--prompt TEXT | --prompt-file FILE) [--aspect-ratio RATIO] [--quality low|medium|high] [--tag TAG]
                 [--no-progress]
 media upload <file> [--content-type TYPE] [--tag TAG] [--no-wait] [--poll-ms MS]
                     [--no-transcode] [--codec h264|hevc] [--max-fps N]
@@ -27,38 +27,41 @@ media upload-batch <manifest.json> --state FILE [--concurrency N]
 media show <id>
 media download <id> [--output FILE]
 media list [--tag TAG] [--primitive image|video]
-media update <id> (--tag TAG | --clear-tag) --if-match REVISION
-media delete <id> --if-match REVISION
+media update <id> (--tag TAG | --clear-tag) --expect-rev REVISION
+media delete <id> --expect-rev REVISION
 compose catalog
 compose render <file> [--output DIRECTORY] [--combined] [--target-width PX --target-height PX] [--safe-area]
                       [--open] [--lint-only]
 compose batch <file> --output DIRECTORY [--only ID] [--target-width PX --target-height PX]
                       [--safe-area] [--lint-only]
+playlist init <media-ids...> --name NAME --output FILE [--screen ID]
+              [--target-width PX --target-height PX] [--duration-ms MS] [--fit contain|cover|fill]
 playlist validate <file>
 playlist create <file>
-playlist update <id> <file> --if-match REVISION
+playlist update <id> <file> --expect-rev REVISION
 playlist export <id> --output DIRECTORY
-playlist import <directory> [--name NAME] [--update ID --if-match REVISION]
-playlist show <id>
+playlist import <directory> [--name NAME] [--update ID --expect-rev REVISION]
+playlist show <id> [--output FILE | --editable]
 playlist list
-playlist delete <id> --if-match REVISION
+playlist delete <id> --expect-rev REVISION
 screen update <id> [--name NAME] [--playlist-id ID] [--timezone ZONE]
-                   --if-match REVISION
+                   --expect-rev REVISION
 screen list [--state archived]
 screen show <id>
-screen assign <id> --playlist-id ID --if-match REVISION
-screen set-timezone <id> --timezone ZONE --if-match REVISION
-screen archive <id> --if-match REVISION
-screen unarchive <id> --if-match REVISION
-screen delete <id> --if-match REVISION
-screen rotate-public-id <id> --if-match REVISION
+screen publish <id> <file> --expect-rev REVISION
+screen assign <id> --playlist-id ID --expect-rev REVISION
+screen set-timezone <id> --timezone ZONE --expect-rev REVISION
+screen archive <id> --expect-rev REVISION
+screen unarchive <id> --expect-rev REVISION
+screen delete <id> --expect-rev REVISION
+screen rotate-public-id <id> --expect-rev REVISION
 screen toast <id> --text TEXT [--level info] [--duration-ms MS]
 screen screenshot <id> [--output FILE] [--timeout MS] [--poll-ms MS]
 kv get --application-id ID <key>
-kv set --application-id ID <key> --json-value JSON [--if-match REVISION]
-kv set --application-id ID <key> --file FILE --content-type TYPE [--if-match REVISION]
-kv set --application-id ID <key> --value-base64 BASE64 --content-type TYPE [--if-match REVISION]
-kv delete --application-id ID <key> --if-match REVISION
+kv set --application-id ID <key> --json-value JSON [--expect-rev REVISION]
+kv set --application-id ID <key> --file FILE --content-type TYPE [--expect-rev REVISION]
+kv set --application-id ID <key> --value-base64 BASE64 --content-type TYPE [--expect-rev REVISION]
+kv delete --application-id ID <key> --expect-rev REVISION
 kv list --application-id ID
 comment show screen <id>
 comment show playlist <id> [--page PAGE_ID]
@@ -92,3 +95,5 @@ Global flags include `--json`, `--human`, `--api-url URL`, `--config PATH`,
 On `revision_conflict`, fetch the resource, reapply the intended change, and
 retry with the returned revision. On an ambiguous transport failure, reuse the
 same idempotency key.
+
+`--if-match` remains an alias for `--expect-rev`; do not supply both.

plugins/screenrig/skills/screenrig/references/compose.md

@@ -329,3 +329,5 @@ cropping. Eight-digit hex is how the page stays transparent and the plate
 keeps alpha. Layered region PNGs can sit as image primitives at their
 manifest rects. Inspect with `--combined`; default agent output stays layered.
 A presentable poster is one generated `image` primitive, not photo plus overlay.
+
+After uploading finished slide images, pass their media IDs in playback order to `playlist init`, inspect the preview, then use `screen publish`. See [playlists](playlists.md).

plugins/screenrig/skills/screenrig/references/media.md

@@ -164,7 +164,7 @@ On a build that converts:
   object. Hyphens are rejected; `ExecIntro2026` is valid and `exec-intro`
   is not. `media list --tag TAG [--primitive image|video]` filters by that tag
   and is the reliable filename → id map after upload.
-  `media update <id> (--tag TAG | --clear-tag) --if-match REVISION` changes
+  `media update <id> (--tag TAG | --clear-tag) --expect-rev REVISION` changes
   or clears it. Untagged objects are omitted when `--tag` is present on
   `media list`.
 - The conversion runs `ffmpeg` and `ffprobe`. They must be on `PATH`, or their
@@ -250,3 +250,5 @@ problem code and status.
 Run `doctor` for local diagnostics. Use
 `doctor --repair-config` only to repair an existing credential file
 whose permissions are too broad.
+
+For long or exact-copy prompts, use `media generate --prompt-file FILE` (or `-` for stdin) instead of `--prompt`. For full-screen playback of ready media IDs, use `playlist init` and `screen publish`; see [playlists](playlists.md).

plugins/screenrig/skills/screenrig/references/operations.md

@@ -5,11 +5,11 @@
 ```bash
 screenrig screen list
 screenrig screen show scr_EXAMPLE
-screenrig screen update scr_EXAMPLE --name "Lobby" --playlist-id pl_EXAMPLE --if-match REVISION
-screenrig screen assign scr_EXAMPLE --playlist-id pl_EXAMPLE --if-match REVISION
-screenrig screen set-timezone scr_EXAMPLE --timezone America/Los_Angeles --if-match REVISION
-screenrig screen archive scr_EXAMPLE --if-match REVISION
-screenrig screen unarchive scr_EXAMPLE --if-match REVISION
+screenrig screen update scr_EXAMPLE --name "Lobby" --playlist-id pl_EXAMPLE --expect-rev REVISION
+screenrig screen assign scr_EXAMPLE --playlist-id pl_EXAMPLE --expect-rev REVISION
+screenrig screen set-timezone scr_EXAMPLE --timezone America/Los_Angeles --expect-rev REVISION
+screenrig screen archive scr_EXAMPLE --expect-rev REVISION
+screenrig screen unarchive scr_EXAMPLE --expect-rev REVISION
 screenrig screen toast scr_EXAMPLE --text "Updated lobby loop" --level info
 screenrig screen screenshot scr_EXAMPLE --output ./lobby.webp
 ```
@@ -59,7 +59,7 @@ screenrig comment delete screen scr_EXAMPLE
 ```
 
 `--json-value` is a JSON object. `--file` reads a JSON object from disk.
-Exactly one of those on set. Last write wins; do not send `--if-match`.
+Exactly one of those on set. Last write wins; do not send `--expect-rev`.
 Unset show is `{ "comments": null }`.
 
 ## Events