Align operating skill and bundled CLI with playlist preparation workflows

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "screenrig",
       "source": "./plugins/screenrig",
       "description": "Operate ScreenRig screens, media, and playlists with the bundled CLI.",
-      "version": "26.09.25",
+      "version": "26.09.0-dev",
       "author": {
         "name": "ScreenRig"
       },

plugins/screenrig/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "screenrig",
-  "version": "26.09.25",
+  "version": "26.09.0-dev",
   "description": "Operate ScreenRig screens, media, playlists, and applications with the bundled CLI.",
   "author": {
     "name": "ScreenRig"

plugins/screenrig/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "screenrig",
-  "version": "26.09.25",
+  "version": "26.09.0-dev",
   "description": "Operate ScreenRig screens, media, playlists, and applications with the bundled CLI.",
   "author": {
     "name": "ScreenRig"

plugins/screenrig/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "screenrig",
-  "version": "26.09.25",
+  "version": "26.09.0-dev",
   "private": false,
   "description": "ScreenRig control-plane CLI for agent-driven digital signage and kiosk operations.",
   "homepage": "https://screenrig.ai",

plugins/screenrig/skills/screenrig/SKILL.md

@@ -53,7 +53,10 @@ screenrig agent enroll --email ADDRESS
 ```
 
 Use the user's actual address. For an existing account, use `agent connect` and
-complete the supported dashboard approval flow instead of creating another account.
+resume the dashboard approval flow instead of creating another account. Connection
+returns promptly by default; a pending success is not active access. Follow
+`data.next.argv` after approval and require `data.connection_complete: true`.
+See [connection behavior](references/commands.md#connect-an-existing-account).
 Consult `screenrig --help` for the installed command's arguments. Never ask the user
 to paste an account bearer into the conversation or command line.
 
@@ -111,13 +114,17 @@ 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. 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.
+2. For full-screen pages, use `playlist init` with local media files, ready media
+   IDs, pinned application releases, or HTTPS URLs and `--screen-id`. Local files
+   upload during preparation. Follow `data.preview.argv`, inspect the result, then
+   use `data.publish.argv`. For layouts and file retry rules, read
+   [playlists](references/playlists.md).
 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.
+   all assigned screens. For an application pin change, use `playlist replace-release`
+   to review the shared-screen impact before applying it. See the playlist reference
+   for revision guards and 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.
 

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

@@ -41,15 +41,19 @@ screenrig app update app_EXAMPLE ./lobby-board --expect-rev 3
 
 `app update` preserves application identity, name, and application K/V. It uses
 the same packer, upload limits, operation wait, and release result as upload.
-Wait for `operation.state: "succeeded"`, then explicitly replace the intended
-playlist primitive's `release_id` and update the playlist with its revision.
-Existing playlists remain pinned to their old immutable release until edited.
+Wait for `data.operation.state: "succeeded"`, then use `playlist replace-release`
+to review the exact page and primitive replacement and all affected screens. Apply
+with the returned revision and impact token; see [release replacement](playlists.md#replace-one-application-release).
+Existing playlists remain pinned until that replacement is applied.
 On a revision conflict, read the app again before deciding whether to retry;
 do not create a replacement application just to bypass the conflict.
 
 ### 2. Write the application primitive
 
-Application-controlled page fragment:
+For a timed full-screen application page, pass its `rel_` ID to `playlist init`;
+see [preparation](playlists.md#prepare-publish-and-edit-playlists). That default has
+no controller privileges. For application-controlled advancement, author this
+page fragment instead:
 
 ```json
 {
@@ -142,10 +146,10 @@ blocks on a WebP. Do not print pixels.
 Application K/V is binary-safe. Use exactly one value mode.
 
 ```bash
-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 --expect-rev REVISION
+screenrig kv set --app-id app_EXAMPLE lobby --json-value '{"open":true}'
+screenrig kv get --app-id app_EXAMPLE lobby
+screenrig kv list --app-id app_EXAMPLE
+screenrig kv delete --app-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

@@ -2,13 +2,56 @@
 
 Use `screenrig --help` to confirm flags against the installed executable.
 
+### Command names and discovery
+
+Use `show` to inspect a resource, `list` for collections, and `kv get` / `kv set`
+for values. Use `--name` for display names, `--screen-id`, `--app-id`,
+`--playlist-id`, and `--release-id` for resource selectors, `--expect-rev` for
+revision guards, and `--after` for event cursors. The group is `app`; “application”
+is the resource name. Comments keep `comment ACTION screen|playlist ID`.
+
+Compatibility aliases remain: `operations get`, `playlist get`, `--if-match`,
+K/V `--application-id`, screen pair/provision `--label`, playlist init `--screen`,
+and events `--cursor`. Supply only one spelling of an option. Response field
+names are unchanged.
+
+Use `screenrig help --all` for the full inventory or `screenrig playlist init
+--help` for focused help. Add `--json` for argument metadata, choices, defaults,
+examples, aliases, and option relationships. `exactlyOne`, `atLeastOne`, and
+`together` groups are checked before configuration or network access; `requires`
+means the first option requires all remaining options. Read stdin only where
+command help explicitly supports `-`.
+
+### Connect an existing account
+
+```sh
+screenrig agent connect --print-url
+```
+
+By default, this starts or resumes an approval request and reads one status
+snapshot for at most one second. A successful pending result means submission,
+not activation: `data.request_submitted` is `true` and `data.connection_complete`
+is `false`. Send the handoff from `data.approval_url` to the intended user, then
+resume with `data.next.argv` or `screenrig agent connect`. The argument array
+preserves the selected config and API origin. Activation returns `data.status:
+active` and `data.connection_complete: true`, without returning a credential.
+
+If no snapshot arrives, `data.status_checked` is `false`; do not infer current
+approval state from that result. Without `--print-url`, the CLI tries to open the
+browser and includes the handoff URL only if opening fails. `--no-wait` explicitly
+selects the default behavior. `--wait` waits up to 30000 ms; `--wait --timeout 10000`
+sets a shorter approval wait. Timeout accepts 1–86400000 ms. Without `--wait`, it
+can shorten but cannot extend the one-second snapshot budget. Budget expiry is
+resumable; approval requests expire after 24 hours. Denial, cancellation, and
+expiry return errors.
+
 ## Commands
 
 ```text
 account show
 agent status
 agent enroll --email EMAIL
-agent connect
+agent connect [--name NAME] [--print-url] [--wait | --no-wait] [--timeout MS]
 agent disconnect --yes [--allow-lockout]
 dashboard [--print-url]
 app pack <directory> [--output FILE]
@@ -34,8 +77,13 @@ compose render <file> [--output DIRECTORY] [--combined] [--target-width PX --tar
                       [--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]
+playlist init <inputs...> --name NAME --output FILE [--screen-id ID]
               [--target-width PX --target-height PX] [--duration-ms MS] [--fit contain|cover|fill]
+              [--no-transcode] [--no-progress] [--poll-ms MS]
+playlist replace-release <id> --page ID --primitive ID --release-id ID
+                         [--apply --expect-rev REVISION --expect-impact TOKEN]
+playlist preview <file|id> --output DIRECTORY [--contact-sheet] [--frame-ms MS] [--lint-only]
+playlist templates
 playlist validate <file>
 playlist create <file>
 playlist update <id> <file> --expect-rev REVISION
@@ -44,6 +92,8 @@ playlist import <directory> [--name NAME] [--update ID --expect-rev REVISION]
 playlist show <id> [--output FILE | --editable]
 playlist list
 playlist delete <id> --expect-rev REVISION
+screen pair <code> [--name NAME]
+screen provision (--open | --print-url) [--name NAME]
 screen update <id> [--name NAME] [--playlist-id ID] [--timezone ZONE]
                    --expect-rev REVISION
 screen list [--state archived]
@@ -57,19 +107,19 @@ 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 [--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
+kv get --app-id ID <key>
+kv set --app-id ID <key> --json-value JSON [--expect-rev REVISION]
+kv set --app-id ID <key> --file FILE --content-type TYPE [--expect-rev REVISION]
+kv set --app-id ID <key> --value-base64 BASE64 --content-type TYPE [--expect-rev REVISION]
+kv delete --app-id ID <key> --expect-rev REVISION
+kv list --app-id ID
 comment show screen <id>
 comment show playlist <id> [--page PAGE_ID]
 comment set screen <id> (--json-value JSON | --file FILE)
 comment set playlist <id> [--page PAGE_ID] (--json-value JSON | --file FILE)
 comment delete screen <id>
 comment delete playlist <id> [--page PAGE_ID]
-operations get <id>
+operations show <id>
 operations wait <id> [--timeout MS] [--poll-ms MS]
 operations cancel <id>
 events list [--after CURSOR] [--limit N]

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

@@ -330,4 +330,4 @@ 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).
+Pass finished slide image files to `playlist init` for upload and preparation, or reuse their ready media IDs in playback order, inspect the preview, then use `screen publish`. See [playlists](playlists.md).

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

@@ -260,4 +260,4 @@ 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).
+For long or exact-copy prompts, use `media generate --prompt-file FILE` (or `-` for stdin) instead of `--prompt`. For full-screen playback, `playlist init` accepts ready media IDs or local files (uploading them during preparation), followed by `screen publish`; see [playlists](playlists.md).

plugins/screenrig/skills/screenrig/references/playlists.md

@@ -5,17 +5,49 @@
 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 init med_POSTER med_VIDEO --name "Lobby loop" --screen-id 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`.
+Inspect the document and preview before publishing. `playlist init` accepts local
+image/video files, ready `med_` IDs, pinned `rel_` application releases, and HTTPS
+iframe URLs in playback order, including mixed inputs:
+
+```sh
+screenrig playlist init ./poster.png med_VIDEO rel_APP https://example.com --name Lobby --screen-id scr_LOBBY --output lobby.json
+```
+
+Local files upload through the normal media path and wait for readiness. This
+requires ffmpeg and ffprobe unless `--no-transcode` is supplied. Preparation writes
+the local document and may upload media; it neither creates a remote playlist nor
+assigns a screen. Existing media must be ready. HTTPS URLs must contain no username
+or password and are not fetched during preparation.
+
+For retryable file preparation, choose `--idempotency-key` on the first attempt
+and reuse it with identical files and input order within the server replay window.
+Each file occurrence gets its own upload keys. Without an explicit key, a new
+invocation gets new keys. Uploaded media survives a later preparation failure;
+inspect `media list` and reuse those IDs when reconciling a partial result.
+
+Each input becomes one full-screen page with a black background and a 200 ms
+crossfade. Images and videos use `--fit contain|cover|fill` (default `contain`).
+Videos are muted, do not loop, and advance on completion. Other pages use
+`--duration-ms` (default 8000). Applications and iframes use `fill`; application
+releases are pinned with timed advancement and no controller privileges. Edit the
+document for application-controlled advancement. The static preview represents
+applications and iframes with placeholders; verify release readiness, embedding,
+and actual playback through the server and intended Player.
+
+Supply `--screen-id` to read the target dimensions and revision. The result includes
+`data.screen_id`, `data.screen_revision`, `data.preview.argv`, and `data.publish.argv`.
+Pass these argument arrays to the bundled `screenrig` launcher without shell
+splitting: they preserve paths, config, API origin, and the observed revision.
+Inspect the preview before publishing. Later screen changes still cause revision
+conflicts. Target metadata stays outside the authored document.
+
+To override the canvas, supply both `--target-width` and `--target-height`. These
+also work without a screen, in which case no publish arguments are returned.
 Unknown or multiple reported surfaces require explicit dimensions. Output files
 must not already exist.
 
@@ -51,6 +83,32 @@ 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.
 
+### Replace one application release
+
+After a successful `app update`, take `data.application.release_id` and identify the
+exact playlist, page, and application primitive to change. Preview the replacement:
+
+```sh
+screenrig playlist replace-release pl_EXISTING --page board-page --primitive board --release-id rel_NEW
+```
+
+This is a read-only impact review, not a rendered preview. Inspect
+`data.previous_release_id`, `data.release_id`, and `data.affected_screens`, including
+archived assignments. Apply the reviewed change using its `data.revision` and
+`data.impact`:
+
+```sh
+screenrig playlist replace-release pl_EXISTING --page board-page --primitive board --release-id rel_NEW --apply --expect-rev 4 --expect-impact TOKEN_FROM_PREVIEW
+```
+
+Other primitives and settings are preserved. The update affects every screen
+assigned to this shared playlist; archived screens retain the new pin for later
+use. A changed replacement, revision, or observed screen impact requires a fresh
+preview and review. Assignments may change after the snapshot: only the playlist
+revision is checked atomically by the server. The server validates release
+availability and ownership on apply. Existing pins remain unchanged until apply;
+afterward, verify manifest revisions and playback on the affected screens.
+
 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

skills/screenrig/SKILL.md

@@ -53,7 +53,10 @@ screenrig agent enroll --email ADDRESS
 ```
 
 Use the user's actual address. For an existing account, use `agent connect` and
-complete the supported dashboard approval flow instead of creating another account.
+resume the dashboard approval flow instead of creating another account. Connection
+returns promptly by default; a pending success is not active access. Follow
+`data.next.argv` after approval and require `data.connection_complete: true`.
+See [connection behavior](references/commands.md#connect-an-existing-account).
 Consult `screenrig --help` for the installed command's arguments. Never ask the user
 to paste an account bearer into the conversation or command line.
 
@@ -111,13 +114,17 @@ 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. 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.
+2. For full-screen pages, use `playlist init` with local media files, ready media
+   IDs, pinned application releases, or HTTPS URLs and `--screen-id`. Local files
+   upload during preparation. Follow `data.preview.argv`, inspect the result, then
+   use `data.publish.argv`. For layouts and file retry rules, read
+   [playlists](references/playlists.md).
 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.
+   all assigned screens. For an application pin change, use `playlist replace-release`
+   to review the shared-screen impact before applying it. See the playlist reference
+   for revision guards and 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.