Skill: playlist init output guard, verify release_ids/media_ids, application hold

The skill and references now tell the operating agent that playlist init
refuses a non-empty existing --output with exit 2 / usage_error and leaves it
untouched (new path or --overwrite), to check that init exited 0 and that
data.release_ids and data.media_ids match the intended inputs before screen
publish, and that application pages hold 24 hours by default with an
application_page_short warning under 60 seconds. Docs-only regeneration
(build-plugin.py --docs-only); the bundled CLI and provenance are unchanged.

Budget (validate-plugin.py --budget): repository 110 files, 3,255,053 bytes
-> 110 files, 3,257,719 bytes; plugins/screenrig 52 files, 2,086,817 bytes ->
52 files, 2,088,150 bytes.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

Author: gersham

plugins/screenrig/skills/screenrig/SKILL.md

@@ -66,7 +66,11 @@ facts are already supplied, operate without another confirmation question.
 3. Read `observation.surfaces[]` for size and orientation; prepare the requested
    content ([content path](#signage-branch-choose-the-content-path)).
 4. `screenrig playlist init SOURCES... --screen-id SCREEN_ID --name NAME --output playlist.json`,
-   then `screenrig screen publish SCREEN_ID playlist.json`.
+   then `screenrig screen publish SCREEN_ID playlist.json`. `playlist init`
+   refuses a non-empty existing `--output` with exit 2 / `usage_error` and leaves
+   it untouched: choose a new path or pass `--overwrite`. Before publishing,
+   check that init exited 0 and that `data.release_ids` and `data.media_ids`
+   match what you intended.
 5. Request `screenrig screen screenshot SCREEN_ID` and inspect that returned
    Player image before saying the content is showing. A local preview is a
    design check. Ask the user to look at the display too.
@@ -575,8 +579,11 @@ Canvas video stays muted, so the soundtrack is the only sound on the screen.
    IDs, pinned application releases, or HTTPS URLs and `--screen-id`. Local files
    upload during preparation, several at a time, and it returns once every file
    is uploaded and processed. If it is interrupted, rerun the identical command:
-   finished uploads return their existing media IDs. Follow `data.preview.argv`,
-   inspect the result, then use `data.publish.argv`. For layouts, read
+   finished uploads return their existing media IDs. A pinned application page
+   holds 24 hours by default so an app that rotates internally and keeps state
+   is not restarted; `--duration-ms` overrides it, and an application page under
+   60 seconds returns an `application_page_short` warning. Follow
+   `data.preview.argv`, inspect the result, then use `data.publish.argv`. For layouts, read
    [playlists](references/playlists.md).
 3. Publish a new playlist with `screen publish SCREEN_ID FILE`. It assigns the
    playlist and waits, up to two minutes by default, until the Player shows it.

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

@@ -101,9 +101,9 @@ name leaves the revision unchanged.
 
 ### 2. Write the application primitive
 
-For a timed full-screen application page, pass its `rel_` ID to `playlist init`;
+For a 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
+no controller privileges and holds the page for 24 hours. For application-controlled advancement, author this
 page fragment instead:
 
 ```json
@@ -137,10 +137,12 @@ page fragment instead:
 ### 3. Choose how the page advances
 
 Use `duration` when the app never signals that it is finished, and omit
-`controller` from its primitive:
+`controller` from its primitive. An app that rotates internally and keeps state
+needs a long hold, since every advance restarts it; `playlist init` writes
+`86400000` (24 hours) and warns below 60 seconds:
 
 ```json
-{ "mode": "duration", "after_ms": 15000 }
+{ "mode": "duration", "after_ms": 86400000 }
 ```
 
 Use `application` when the app calls `window.screenrig.nextPage()`:

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

@@ -134,10 +134,15 @@ instead of uploading again. There is nothing to reconcile by hand.
 
 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
+Videos are muted, do not loop, and advance on completion. Image and iframe 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
+releases are pinned with timed advancement and no controller privileges, and hold
+86400000 ms (24 hours, the longest `after_ms`) unless `--duration-ms` is given, so
+an app that rotates internally and keeps state is not restarted by the page timer.
+An explicit `--duration-ms` applies to every non-video page, and an application page
+under 60 seconds returns an `application_page_short` warning from `playlist init`,
+`validate`, `preview` and `screen publish`. 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.
 
@@ -149,7 +154,7 @@ Inspect the preview before publishing. Add `--expect-rev` explicitly to guard ag
 
 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 are exclusive by default; use `--overwrite` to replace an existing authoring file atomically. An empty file does not count as existing. Parent directories are created automatically. URL and release-ID inputs with explicit dimensions work without login.
+Unknown or multiple reported surfaces require explicit dimensions. Output files are exclusive by default: a non-empty existing `--output` fails with `usage_error` (exit 2) and stays untouched, so choose a new path or use `--overwrite` to replace it atomically. An empty file does not count as existing. Confirm init exited 0 and that `data.release_ids` and `data.media_ids` match the intended inputs before `screen publish`. Parent directories are created automatically. URL and release-ID inputs with explicit dimensions work without login.
 
 `screen publish <screen-id> <file>` creates a new playlist, assigns it with an optional **screen** revision guard, reads back the assignment, and waits for the Player to show it. It does not update an
 existing playlist by name. Display names may repeat; use the playlist ID for an explicit `playlist update`.

skills/screenrig/SKILL.md

@@ -66,7 +66,11 @@ facts are already supplied, operate without another confirmation question.
 3. Read `observation.surfaces[]` for size and orientation; prepare the requested
    content ([content path](#signage-branch-choose-the-content-path)).
 4. `screenrig playlist init SOURCES... --screen-id SCREEN_ID --name NAME --output playlist.json`,
-   then `screenrig screen publish SCREEN_ID playlist.json`.
+   then `screenrig screen publish SCREEN_ID playlist.json`. `playlist init`
+   refuses a non-empty existing `--output` with exit 2 / `usage_error` and leaves
+   it untouched: choose a new path or pass `--overwrite`. Before publishing,
+   check that init exited 0 and that `data.release_ids` and `data.media_ids`
+   match what you intended.
 5. Request `screenrig screen screenshot SCREEN_ID` and inspect that returned
    Player image before saying the content is showing. A local preview is a
    design check. Ask the user to look at the display too.
@@ -575,8 +579,11 @@ Canvas video stays muted, so the soundtrack is the only sound on the screen.
    IDs, pinned application releases, or HTTPS URLs and `--screen-id`. Local files
    upload during preparation, several at a time, and it returns once every file
    is uploaded and processed. If it is interrupted, rerun the identical command:
-   finished uploads return their existing media IDs. Follow `data.preview.argv`,
-   inspect the result, then use `data.publish.argv`. For layouts, read
+   finished uploads return their existing media IDs. A pinned application page
+   holds 24 hours by default so an app that rotates internally and keeps state
+   is not restarted; `--duration-ms` overrides it, and an application page under
+   60 seconds returns an `application_page_short` warning. Follow
+   `data.preview.argv`, inspect the result, then use `data.publish.argv`. For layouts, read
    [playlists](references/playlists.md).
 3. Publish a new playlist with `screen publish SCREEN_ID FILE`. It assigns the
    playlist and waits, up to two minutes by default, until the Player shows it.

skills/screenrig/references/applications.md

@@ -101,9 +101,9 @@ name leaves the revision unchanged.
 
 ### 2. Write the application primitive
 
-For a timed full-screen application page, pass its `rel_` ID to `playlist init`;
+For a 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
+no controller privileges and holds the page for 24 hours. For application-controlled advancement, author this
 page fragment instead:
 
 ```json
@@ -137,10 +137,12 @@ page fragment instead:
 ### 3. Choose how the page advances
 
 Use `duration` when the app never signals that it is finished, and omit
-`controller` from its primitive:
+`controller` from its primitive. An app that rotates internally and keeps state
+needs a long hold, since every advance restarts it; `playlist init` writes
+`86400000` (24 hours) and warns below 60 seconds:
 
 ```json
-{ "mode": "duration", "after_ms": 15000 }
+{ "mode": "duration", "after_ms": 86400000 }
 ```
 
 Use `application` when the app calls `window.screenrig.nextPage()`:

skills/screenrig/references/playlists.md

@@ -134,10 +134,15 @@ instead of uploading again. There is nothing to reconcile by hand.
 
 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
+Videos are muted, do not loop, and advance on completion. Image and iframe 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
+releases are pinned with timed advancement and no controller privileges, and hold
+86400000 ms (24 hours, the longest `after_ms`) unless `--duration-ms` is given, so
+an app that rotates internally and keeps state is not restarted by the page timer.
+An explicit `--duration-ms` applies to every non-video page, and an application page
+under 60 seconds returns an `application_page_short` warning from `playlist init`,
+`validate`, `preview` and `screen publish`. 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.
 
@@ -149,7 +154,7 @@ Inspect the preview before publishing. Add `--expect-rev` explicitly to guard ag
 
 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 are exclusive by default; use `--overwrite` to replace an existing authoring file atomically. An empty file does not count as existing. Parent directories are created automatically. URL and release-ID inputs with explicit dimensions work without login.
+Unknown or multiple reported surfaces require explicit dimensions. Output files are exclusive by default: a non-empty existing `--output` fails with `usage_error` (exit 2) and stays untouched, so choose a new path or use `--overwrite` to replace it atomically. An empty file does not count as existing. Confirm init exited 0 and that `data.release_ids` and `data.media_ids` match the intended inputs before `screen publish`. Parent directories are created automatically. URL and release-ID inputs with explicit dimensions work without login.
 
 `screen publish <screen-id> <file>` creates a new playlist, assigns it with an optional **screen** revision guard, reads back the assignment, and waits for the Player to show it. It does not update an
 existing playlist by name. Display names may repeat; use the playlist ID for an explicit `playlist update`.