feat(skill): guide agents through local previews and card workflows

Bundle CLI bb531a1 with local Chromium card/page previews, expiry flags and guarded screen revert. Explain conditional pages, applied-data/loop receipts, effective timezone, colour overrides and bullet newlines. Repository: 111 files, 3,301,499 to 3,327,790 bytes; plugin: 53 files, 2,118,918 to 2,140,925 bytes; budgets pass.

Author: gersham

components.lock.json

@@ -3,10 +3,10 @@
   "state": "resolved",
   "cli": {
     "repository": "screenrig/cli",
-    "commit": "01c9c82c5739b9584b479dab55ceb15b064642ea",
+    "commit": "bb531a167d8d124e620b87bfffd4c139f2ba54df",
     "artifact": {
       "file": "screenrig-cli.tgz",
-      "sha256": "458511933eb38397f7e41fc980a8abdfdc07e91dfafcbfb3d79232406d555c61"
+      "sha256": "80b2dd810d07e638b3bef54eb2219c73fdf0b67ea5bc5f3279f1a8c3c0e720d8"
     }
   }
 }

plugins/screenrig/cli/dist/bin.js

@@ -70,7 +70,8 @@ facts are already supplied, operate without another confirmation question.
    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.
+   match what you intended. Run `screenrig playlist preview playlist.json --output preview --contact-sheet`,
+   open the contact sheet and inspect the pages before `screen publish`.
 5. To check a specific page, run
    `screenrig screen play-page SCREEN_ID --page-id PAGE_ID` first. Request
    `screenrig screen screenshot SCREEN_ID` and inspect that returned
@@ -566,7 +567,17 @@ Run `cards list --category CATEGORY` (`time`, `public`, `messages`, `media`,
 `food`, `weather`) and `cards show ID` to choose a type, read its tier and
 layouts, and pick a schema-listed theme. Run `card create --type ID --file
 params.json`, put the returned `crd_` ID in a card item on a playlist page, and
-set dynamic properties with `card data put crd_ID --file data.json`. A
+set dynamic properties with `card data put crd_ID --file data.json`.
+Render a card locally with `card preview crd_ID --output card.png`; for an
+unpublished design use `card preview TYPE --params params.json --data data.json
+--output card.png`. Open and inspect the PNG. Then render the whole playlist
+with `playlist preview FILE --output preview --contact-sheet` and inspect the
+contact sheet, including cards over their background images. These commands
+use installed Chromium or Chrome locally (`SCREENRIG_BROWSER` selects its
+executable) and the verified published card renderer. `--now ISO --timezone
+ZONE` makes time-dependent designs repeatable. Check `data.placeholders` and
+resolve or explicitly account for every item whose pixels were not rendered.
+A
 `fullscreen` card takes `layout: "full"` only; the other layouts, anchors and
 page limits are in [cards and feeds](references/playlists.md#built-in-cards-and-feeds).
 For weather, rates and other third-party data use screenRIG's cached feeds,
@@ -597,7 +608,8 @@ Canvas video stays muted, so the soundtrack is the only sound on the screen.
    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
+   `data.preview.argv`, open and inspect its local contact sheet, then use `data.publish.argv`.
+   This applies to card-only playlists as well as media pages. 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/SKILL.md

@@ -947,3 +947,56 @@ one-at-a-time or complete-pass playback; a bounded runtime sequence using
 `batch_size` with `one_at_a_time: false` requires removing that field or
 choosing explicit IDs before export. This prevents silently losing a runtime
 batch cursor in a static bundle.
+
+## Local card previews, data conditions and receipts
+
+Use `card preview TYPE --params params.json --data data.json --output card.png`
+for one card, or `card preview crd_CARD --output card.png` for a saved instance.
+Then run `playlist preview FILE --output preview --contact-sheet` for its full
+page context. Open and inspect the image files before publishing. The CLI runs
+an installed Chromium or Chrome locally; `SCREENRIG_BROWSER` selects its
+executable. It fetches the verified published renderer and fonts and reuses its
+cache. `--now 2026-10-20T18:00:00Z --timezone America/Vancouver` freezes card
+clocks. `data.rendered_cards` names rendered card versions; `data.placeholders`
+names content that was represented by a box. Application interaction and live
+streams still need Player verification.
+
+Optional `backgroundColor` and `textColor` card params accept `#RRGGBB` or
+`#RRGGBBAA` (CSS alpha order). `backgroundColor: "#382719CC"` makes a translucent
+warm scrim; `#E86A17` makes a solid orange ground. `background: "none"` takes
+precedence. `textColor` sets main and secondary text, while `accent` continues
+to colour eyebrows/highlights. Unset properties preserve the theme. Text-card
+bodies keep newlines and put inline bullet separators on separate lines.
+
+`card data put crd_CARD --file data.json --ttl 2h` expires that edition two
+hours after acceptance; `--expires-at ISO` supplies an absolute deadline. Use
+one option at a time. A replacement without either removes expiry. Expired
+data stays inspectable through the agent read but blanks on an updated Player,
+including offline caches. Repeating an identical idempotent write preserves
+its original deadline.
+
+A page can use `"visibility":{"enabled":true,"data":{"key":"crd_CARD",
+"path":"/enabled","equals":true}}`. `key` names card data; `path` is an optional
+JSON Pointer. Without `equals`, the document or field must exist (a present
+null counts); with it, the scalar must equal the supplied value. Missing and
+expired data never match. Keep one ordinary page without visibility as a
+permanent fallback. Date/time bounds can be combined with the data condition.
+Players advertise `page.conditions`; other Players receive conditional pages
+disabled. A screen's `effective_timezone` and `timezone_source` show the
+configured zone, device fallback, or unknown. An explicit UTC zone stays UTC.
+
+Watch project events `screen.card_data_applied` for a rendered edition
+(`manifest_revision`, `page_id`, `primitive_id`, `data_key`, `data_revision`)
+and `screen.playlist_loop_completed` for the first uninterrupted eligible loop
+of a manifest. These are Player receipts, separate from write acceptance.
+Screenshot-ready events continue to identify completed captures.
+
+Use `screen changes scr_SCREEN` to list up to 50 issued composition changes
+retained for 30 days. `screen revert scr_SCREEN --change-id man_CHANGE
+--expect-rev REV` restores that change's preceding composition on that screen
+by creating a separate playlist. Other screens and source playlists stay as
+they are. Live card data stays current, with its expiry. A newer publish,
+assignment, takeover, expired history or unavailable dependency refuses the
+revert. Exact retries return the same accepted assignment. Check the returned
+screen's `manifest_upgrade` or its activation event before claiming the Player
+has applied it.

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

@@ -70,7 +70,8 @@ facts are already supplied, operate without another confirmation question.
    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.
+   match what you intended. Run `screenrig playlist preview playlist.json --output preview --contact-sheet`,
+   open the contact sheet and inspect the pages before `screen publish`.
 5. To check a specific page, run
    `screenrig screen play-page SCREEN_ID --page-id PAGE_ID` first. Request
    `screenrig screen screenshot SCREEN_ID` and inspect that returned
@@ -566,7 +567,17 @@ Run `cards list --category CATEGORY` (`time`, `public`, `messages`, `media`,
 `food`, `weather`) and `cards show ID` to choose a type, read its tier and
 layouts, and pick a schema-listed theme. Run `card create --type ID --file
 params.json`, put the returned `crd_` ID in a card item on a playlist page, and
-set dynamic properties with `card data put crd_ID --file data.json`. A
+set dynamic properties with `card data put crd_ID --file data.json`.
+Render a card locally with `card preview crd_ID --output card.png`; for an
+unpublished design use `card preview TYPE --params params.json --data data.json
+--output card.png`. Open and inspect the PNG. Then render the whole playlist
+with `playlist preview FILE --output preview --contact-sheet` and inspect the
+contact sheet, including cards over their background images. These commands
+use installed Chromium or Chrome locally (`SCREENRIG_BROWSER` selects its
+executable) and the verified published card renderer. `--now ISO --timezone
+ZONE` makes time-dependent designs repeatable. Check `data.placeholders` and
+resolve or explicitly account for every item whose pixels were not rendered.
+A
 `fullscreen` card takes `layout: "full"` only; the other layouts, anchors and
 page limits are in [cards and feeds](references/playlists.md#built-in-cards-and-feeds).
 For weather, rates and other third-party data use screenRIG's cached feeds,
@@ -597,7 +608,8 @@ Canvas video stays muted, so the soundtrack is the only sound on the screen.
    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
+   `data.preview.argv`, open and inspect its local contact sheet, then use `data.publish.argv`.
+   This applies to card-only playlists as well as media pages. 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/SKILL.md

@@ -947,3 +947,56 @@ one-at-a-time or complete-pass playback; a bounded runtime sequence using
 `batch_size` with `one_at_a_time: false` requires removing that field or
 choosing explicit IDs before export. This prevents silently losing a runtime
 batch cursor in a static bundle.
+
+## Local card previews, data conditions and receipts
+
+Use `card preview TYPE --params params.json --data data.json --output card.png`
+for one card, or `card preview crd_CARD --output card.png` for a saved instance.
+Then run `playlist preview FILE --output preview --contact-sheet` for its full
+page context. Open and inspect the image files before publishing. The CLI runs
+an installed Chromium or Chrome locally; `SCREENRIG_BROWSER` selects its
+executable. It fetches the verified published renderer and fonts and reuses its
+cache. `--now 2026-10-20T18:00:00Z --timezone America/Vancouver` freezes card
+clocks. `data.rendered_cards` names rendered card versions; `data.placeholders`
+names content that was represented by a box. Application interaction and live
+streams still need Player verification.
+
+Optional `backgroundColor` and `textColor` card params accept `#RRGGBB` or
+`#RRGGBBAA` (CSS alpha order). `backgroundColor: "#382719CC"` makes a translucent
+warm scrim; `#E86A17` makes a solid orange ground. `background: "none"` takes
+precedence. `textColor` sets main and secondary text, while `accent` continues
+to colour eyebrows/highlights. Unset properties preserve the theme. Text-card
+bodies keep newlines and put inline bullet separators on separate lines.
+
+`card data put crd_CARD --file data.json --ttl 2h` expires that edition two
+hours after acceptance; `--expires-at ISO` supplies an absolute deadline. Use
+one option at a time. A replacement without either removes expiry. Expired
+data stays inspectable through the agent read but blanks on an updated Player,
+including offline caches. Repeating an identical idempotent write preserves
+its original deadline.
+
+A page can use `"visibility":{"enabled":true,"data":{"key":"crd_CARD",
+"path":"/enabled","equals":true}}`. `key` names card data; `path` is an optional
+JSON Pointer. Without `equals`, the document or field must exist (a present
+null counts); with it, the scalar must equal the supplied value. Missing and
+expired data never match. Keep one ordinary page without visibility as a
+permanent fallback. Date/time bounds can be combined with the data condition.
+Players advertise `page.conditions`; other Players receive conditional pages
+disabled. A screen's `effective_timezone` and `timezone_source` show the
+configured zone, device fallback, or unknown. An explicit UTC zone stays UTC.
+
+Watch project events `screen.card_data_applied` for a rendered edition
+(`manifest_revision`, `page_id`, `primitive_id`, `data_key`, `data_revision`)
+and `screen.playlist_loop_completed` for the first uninterrupted eligible loop
+of a manifest. These are Player receipts, separate from write acceptance.
+Screenshot-ready events continue to identify completed captures.
+
+Use `screen changes scr_SCREEN` to list up to 50 issued composition changes
+retained for 30 days. `screen revert scr_SCREEN --change-id man_CHANGE
+--expect-rev REV` restores that change's preceding composition on that screen
+by creating a separate playlist. Other screens and source playlists stay as
+they are. Live card data stays current, with its expiry. A newer publish,
+assignment, takeover, expired history or unavailable dependency refuses the
+revert. Exact retries return the same accepted assignment. Check the returned
+screen's `manifest_upgrade` or its activation event before claiming the Player
+has applied it.