Skill and CLI: screen folders

The skill files screens in folders (where a screen is) beside tags (groups
across places), with screen folder list|show|create|update|delete, screen
move and screen list --folder; fleet commands and campaign audiences take
--folder ID; a folder default plays on screens with no playlist of their own,
and a move's levels are told to the user. The bundled CLI is cli 7b52466.

Budget: repository 109 files 3,474,581 -> 3,491,811 bytes; plugins/screenrig
50 files 2,437,242 -> 2,453,020 bytes.

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

Author: gersham

components.lock.json

@@ -3,10 +3,10 @@
   "state": "resolved",
   "cli": {
     "repository": "screenrig/cli",
-    "commit": "ad1d7112d4e053729022b40b5fab0cb3eae5a06b",
+    "commit": "7b52466b5529894c8526ed22f245a0fceb5581fe",
     "artifact": {
       "file": "screenrig-cli.tgz",
-      "sha256": "7e1810296cc96359fb03a6e7f2d761b5b97d90062bd6ac0d3043ceee762fabfd"
+      "sha256": "56fab7e708e6cbd190d6a24ff6bcf7d6bfe9ca9b3280c4ff5af0207fbbb4d657"
     }
   }
 }

plugins/screenrig/cli/dist/bin.js

@@ -114,9 +114,11 @@ the screen device, or play.DOMAIN when `doctor` reports another environment's
 api.DOMAIN); no USB or ADB. `screenrig screen pair "ABC 234"`, then
 `screen show SCREEN_ID` until `state` is `active` and `online` is true. Read
 `observation.surfaces[]` for size and orientation. Tag each screen right after
-pairing (`screen tag SCREEN_ID --set Lobby,Floor2`); tags select fleets and are
-not authorization. Displays run by a device manager use `fleet-links create`
-instead of per-screen codes: its URL goes in a kiosk browser, in Android or
+pairing (`screen tag SCREEN_ID --set Lobby,Floor2`) and, for a large estate,
+file it in a folder (`screen move SCREEN_ID --folder ID`); tags and folders
+select fleets and are not authorization. Displays run by a device manager use
+`fleet-links create` instead of per-screen codes: its URL goes in a kiosk
+browser, in Android or
 Apple managed app configuration as `fleet_link` (`asset_id` names the screen),
 or in `/etc/screenrig/fleet-link` on Linux; `--expires-at` ends it. Its URL
 creates screens, so give it only to the person who configures the devices. A
@@ -224,13 +226,30 @@ Downloads are free. On Standard the first 1 GB stored is free and a project with
 no credit cannot store more (`payment_required`), so delete unused media instead
 of piling it up.
 
-**Fleets.** `screen assign|reload|toast|tag` take several IDs or `--tag TAG`.
-The answer stays `ok: true`; read `data.results[]` (`fleet_partial_failure`).
-Rerun an interrupted command unchanged; after a partial failure retry only the
-failed IDs. For a fleet publish, `playlist create FILE` once, then
-`screen assign --tag TAG --playlist-id ID`. Verify with
+**Fleets.** `screen assign|reload|toast|tag` take several IDs, `--tag TAG` or
+`--folder ID`. The answer stays `ok: true`; read `data.results[]`
+(`fleet_partial_failure`). Rerun an interrupted command unchanged; after a
+partial failure retry only the failed IDs. For a fleet publish, `playlist create
+FILE` once, then `screen assign --tag TAG --playlist-id ID`. Verify with
 `screen screenshot --tag TAG --output DIR`.
 
+**Screen folders.** A folder says where a screen is, one place per screen
+(property, building, level, zone); a tag marks a group that cuts across places
+(`overhead`, `menu-board`). Use a folder for "everything in this building", a
+tag for "every menu board", or both:
+`--audience '{"all":[{"folder":"sfd_ID"},{"tag":"overhead"}]}'`.
+`screen folder create --name NAME [--parent ID] [--default-playlist-id ID]`,
+`list`, `show`, `update` and `delete` build the tree, `screen move ID...
+--folder ID|--root` files screens and folders (`scr_` and `sfd_` IDs mixed), and
+`screen list --folder ID|root` lists one folder's own screens. `--folder ID` on a
+fleet command or `campaign create|update` reaches the folder and every folder
+inside it. A folder's default playlist plays on its screens with no playlist of
+their own (`effective_playlist.source` is `folder`). A move or re-parent
+re-resolves the screens within about 15 seconds, and the answer's `levels` lists
+the campaigns and folder defaults they gain or lose: tell the user. Deleting a
+folder moves its contents up and is refused while a campaign names it. Folders
+nest 10 deep, 1,000 to a project; writes need Manage access.
+
 **Per-screen values.** One playlist shows each screen's own details. Set them
 once per screen: `screen update SCREEN_ID --field store_number=0142 --field
 region=north --location 46.8772,-96.7898 --location-name Fargo`. Card params
@@ -242,12 +261,13 @@ region=north` or `--near LAT,LON,KM` finds screens.
 
 **Campaigns, schedules and takeover.** A screen plays its takeover, else the
 first campaign that holds, else the first matching schedule entry, else its
-default playlist. For content across screens (a promotion at every `north`
-store, weekday lunch menus) create one campaign, not per-screen schedules:
-`campaign create --name Lunch --playlist-id ID --tag north --window
-mon-fri@11:00-14:00`. Screens that join its audience later get it too. It needs
-each screen's default playlist and, with `--from`, `--until` or `--window`, its
-timezone (`screen set-timezone`). `campaign screens ID` shows every screen's
+own default playlist, else its nearest folder's default. For content across
+screens (a promotion at every `north` store, weekday lunch menus) create one
+campaign, not per-screen schedules: `campaign create --name Lunch --playlist-id
+ID --tag north --window mon-fri@11:00-14:00` (`--folder ID` for a folder).
+Screens that join its audience later get it too. It needs each screen's default
+playlist and, with `--from`, `--until` or `--window`, its timezone
+(`screen set-timezone`). `campaign screens ID` shows every screen's
 standing and `campaign explain SCREEN_ID` says why one does not play it;
 with `--at TIME` it says what will play then, and `--to TIME` lists the
 switches: check a plan before its date.

plugins/screenrig/skills/screenrig/SKILL.md

@@ -21,7 +21,9 @@ screenrig screen list --json
 
 `screen show SCREEN_ID` returns the same fields for one screen; `list` already
 carries every field below, so one call serves a card or a fleet. `--tag TAG`
-narrows to one tag and `--state archived` lists archived screens.
+narrows to one tag, `--folder ID|root` to the screens directly inside one
+screen folder (or outside every folder), and `--state archived` lists archived
+screens.
 
 Take every displayed value from that envelope. Do not retype a number, an id,
 a revision or a timestamp from a previous reply: re-read it here, so the card

plugins/screenrig/skills/screenrig/references/screen-card.md

@@ -114,9 +114,11 @@ the screen device, or play.DOMAIN when `doctor` reports another environment's
 api.DOMAIN); no USB or ADB. `screenrig screen pair "ABC 234"`, then
 `screen show SCREEN_ID` until `state` is `active` and `online` is true. Read
 `observation.surfaces[]` for size and orientation. Tag each screen right after
-pairing (`screen tag SCREEN_ID --set Lobby,Floor2`); tags select fleets and are
-not authorization. Displays run by a device manager use `fleet-links create`
-instead of per-screen codes: its URL goes in a kiosk browser, in Android or
+pairing (`screen tag SCREEN_ID --set Lobby,Floor2`) and, for a large estate,
+file it in a folder (`screen move SCREEN_ID --folder ID`); tags and folders
+select fleets and are not authorization. Displays run by a device manager use
+`fleet-links create` instead of per-screen codes: its URL goes in a kiosk
+browser, in Android or
 Apple managed app configuration as `fleet_link` (`asset_id` names the screen),
 or in `/etc/screenrig/fleet-link` on Linux; `--expires-at` ends it. Its URL
 creates screens, so give it only to the person who configures the devices. A
@@ -224,13 +226,30 @@ Downloads are free. On Standard the first 1 GB stored is free and a project with
 no credit cannot store more (`payment_required`), so delete unused media instead
 of piling it up.
 
-**Fleets.** `screen assign|reload|toast|tag` take several IDs or `--tag TAG`.
-The answer stays `ok: true`; read `data.results[]` (`fleet_partial_failure`).
-Rerun an interrupted command unchanged; after a partial failure retry only the
-failed IDs. For a fleet publish, `playlist create FILE` once, then
-`screen assign --tag TAG --playlist-id ID`. Verify with
+**Fleets.** `screen assign|reload|toast|tag` take several IDs, `--tag TAG` or
+`--folder ID`. The answer stays `ok: true`; read `data.results[]`
+(`fleet_partial_failure`). Rerun an interrupted command unchanged; after a
+partial failure retry only the failed IDs. For a fleet publish, `playlist create
+FILE` once, then `screen assign --tag TAG --playlist-id ID`. Verify with
 `screen screenshot --tag TAG --output DIR`.
 
+**Screen folders.** A folder says where a screen is, one place per screen
+(property, building, level, zone); a tag marks a group that cuts across places
+(`overhead`, `menu-board`). Use a folder for "everything in this building", a
+tag for "every menu board", or both:
+`--audience '{"all":[{"folder":"sfd_ID"},{"tag":"overhead"}]}'`.
+`screen folder create --name NAME [--parent ID] [--default-playlist-id ID]`,
+`list`, `show`, `update` and `delete` build the tree, `screen move ID...
+--folder ID|--root` files screens and folders (`scr_` and `sfd_` IDs mixed), and
+`screen list --folder ID|root` lists one folder's own screens. `--folder ID` on a
+fleet command or `campaign create|update` reaches the folder and every folder
+inside it. A folder's default playlist plays on its screens with no playlist of
+their own (`effective_playlist.source` is `folder`). A move or re-parent
+re-resolves the screens within about 15 seconds, and the answer's `levels` lists
+the campaigns and folder defaults they gain or lose: tell the user. Deleting a
+folder moves its contents up and is refused while a campaign names it. Folders
+nest 10 deep, 1,000 to a project; writes need Manage access.
+
 **Per-screen values.** One playlist shows each screen's own details. Set them
 once per screen: `screen update SCREEN_ID --field store_number=0142 --field
 region=north --location 46.8772,-96.7898 --location-name Fargo`. Card params
@@ -242,12 +261,13 @@ region=north` or `--near LAT,LON,KM` finds screens.
 
 **Campaigns, schedules and takeover.** A screen plays its takeover, else the
 first campaign that holds, else the first matching schedule entry, else its
-default playlist. For content across screens (a promotion at every `north`
-store, weekday lunch menus) create one campaign, not per-screen schedules:
-`campaign create --name Lunch --playlist-id ID --tag north --window
-mon-fri@11:00-14:00`. Screens that join its audience later get it too. It needs
-each screen's default playlist and, with `--from`, `--until` or `--window`, its
-timezone (`screen set-timezone`). `campaign screens ID` shows every screen's
+own default playlist, else its nearest folder's default. For content across
+screens (a promotion at every `north` store, weekday lunch menus) create one
+campaign, not per-screen schedules: `campaign create --name Lunch --playlist-id
+ID --tag north --window mon-fri@11:00-14:00` (`--folder ID` for a folder).
+Screens that join its audience later get it too. It needs each screen's default
+playlist and, with `--from`, `--until` or `--window`, its timezone
+(`screen set-timezone`). `campaign screens ID` shows every screen's
 standing and `campaign explain SCREEN_ID` says why one does not play it;
 with `--at TIME` it says what will play then, and `--to TIME` lists the
 switches: check a plan before its date.

skills/screenrig/SKILL.md

@@ -21,7 +21,9 @@ screenrig screen list --json
 
 `screen show SCREEN_ID` returns the same fields for one screen; `list` already
 carries every field below, so one call serves a card or a fleet. `--tag TAG`
-narrows to one tag and `--state archived` lists archived screens.
+narrows to one tag, `--folder ID|root` to the screens directly inside one
+screen folder (or outside every folder), and `--state archived` lists archived
+screens.
 
 Take every displayed value from that envelope. Do not retype a number, an id,
 a revision or a timestamp from a previous reply: re-read it here, so the card