From d742d1cf44433e4994e9f8e160c25b763883901f Mon Sep 17 00:00:00 2001
From: Kurtis Jantzen <kurtis@telemetrytv.com>
Date: Thu, 10 Sep 2026 16:31:13 -0700
Subject: [PATCH] Document playlist preparation and publishing in CLI README

---
 README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/README.md b/README.md
index 92629ae1..83778504 100644
--- a/README.md
+++ b/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.