Teach JSON-default agent workflows and regenerate plugin documentation

AGENTS.md

@@ -34,6 +34,10 @@ does not require that file for standalone contribution.
 
 - Never edit `plugins/screenrig/` independently. Change canonical inputs and
   regenerate.
+- For documentation-only updates, `scripts/build-plugin.py --docs-only`
+  refreshes canonical public files and skills in an existing bundle. Check with
+  `--docs-only --check`. It preserves the CLI, manifests and provenance; full
+  artifact generation and validation are still required before release.
 - After packing, write `components.lock.json` as provenance of that tarball.
   Do not refetch a pinned CLI SHA.
 - Keep Codex and Claude marketplace metadata, generated manifests, public
@@ -55,12 +59,16 @@ marketplace listing unless the user asks.
   marketplace commands, with Grok `--trust` named and `GROK_PLUGIN_ROOT`
   lookup.
 - After install, prepend `$SCREENRIG_PLUGIN_ROOT/skills/screenrig/scripts` to
-  `PATH` once, then run `screenrig --json version`,
+  `PATH` once, then run `screenrig version`,
   `screenrig-plugin-freshness --json`, `doctor`, then content work. Do not
   export `SR`. Do not teach `npm i -g screenrig`.
 - Teach implemented account enrollment, connection and Player pairing in the
   operating skill, without making them the marketplace sales pitch.
-- Keep `--json` envelopes. Never teach a token flag or pasted bearer.
+- Operational commands use JSON envelopes by default with the JSON-default CLI;
+  `--json` remains compatible and `--human` opts into manual text output. Help
+  stays readable unless `--json` is explicit. Do not combine the output flags.
+  Keep explicit `--json` for the separate freshness helper and scripts that
+  must remain compatible with older bundles. Never teach a token flag or pasted bearer.
 - Never write MCP. `validate-plugin.py` rejects MCP manifests.
 - Keep the skill operational: launcher, first-use account state, supported task
   paths, errors and verification. Put detailed command families in references.
@@ -79,11 +87,12 @@ host paths, no local listener service, no internal tooling names.
 
 ```sh
 python3 scripts/check-public-repo.py
-plugins/screenrig/skills/screenrig/scripts/screenrig --json version
+plugins/screenrig/skills/screenrig/scripts/screenrig version
 python3 scripts/build-plugin.py --check --cli-artifact <current-cli-tarball>
 python3 scripts/validate-plugin.py --cli-artifact <current-cli-tarball>
 python3 scripts/test-skill-commands.py
 python3 scripts/test-plugin-freshness.py
+python3 scripts/test-docs-only.py
 ```
 
 These gates do not prove marketplace installation, live API use, native

CONTRIBUTING.md

@@ -15,3 +15,17 @@ belong here. The source and generated skill must travel with the same CLI bundle
 
 Skill validation checks command availability, references, launcher/version flow,
 error handling and secret boundaries. It does not require marketing sentences.
+
+The canonical skill's operational examples target JSON-default CLI output.
+`--json` stays compatible, `--human` selects manual text, and help remains
+readable by default. Runtime helpers retain explicit `--json` for
+compatibility; the freshness helper itself still requires it. Normal skill
+examples use the default, including version bootstrap.
+
+For documentation-only work, `python3 scripts/build-plugin.py --docs-only`
+refreshes canonical public files and skills in the existing generated bundle.
+Verify those copies with `python3 scripts/build-plugin.py --docs-only --check`.
+This preserves the bundled CLI, manifests and artifact provenance; it does not
+establish that the executable supports newly documented behavior. Before
+release, run the full build and validation against the CLI artifact containing
+the documented changes.

components.lock.json

@@ -6,7 +6,7 @@
     "commit": "d007df89b308e391584e5731c4c53e2fe20bf273",
     "artifact": {
       "file": "screenrig-cli.tgz",
-      "sha256": "9f95563e14710828e891cb2362ca050b9328ed59928ab7277c5bd9639b77dc8d"
+      "sha256": "0f7a7dbd685c34461840e706660ebcee98cddfbc510e86089cca7611e8e5475c"
     }
   }
 }

plugins/screenrig/CONTRIBUTING.md

@@ -15,3 +15,17 @@ belong here. The source and generated skill must travel with the same CLI bundle
 
 Skill validation checks command availability, references, launcher/version flow,
 error handling and secret boundaries. It does not require marketing sentences.
+
+The canonical skill's operational examples target JSON-default CLI output.
+`--json` stays compatible, `--human` selects manual text, and help remains
+readable by default. Runtime helpers retain explicit `--json` for
+compatibility; the freshness helper itself still requires it. Normal skill
+examples use the default, including version bootstrap.
+
+For documentation-only work, `python3 scripts/build-plugin.py --docs-only`
+refreshes canonical public files and skills in the existing generated bundle.
+Verify those copies with `python3 scripts/build-plugin.py --docs-only --check`.
+This preserves the bundled CLI, manifests and artifact provenance; it does not
+establish that the executable supports newly documented behavior. Before
+release, run the full build and validation against the CLI artifact containing
+the documented changes.

plugins/screenrig/skills/screenrig/SKILL.md

@@ -18,7 +18,7 @@ launcher on this shell's PATH. Never substitute a global or source-checkout bina
 SCREENRIG_PLUGIN_ROOT="${GROK_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-}}}}"
 if [ -n "$SCREENRIG_PLUGIN_ROOT" ]; then
   PATH="$SCREENRIG_PLUGIN_ROOT/skills/screenrig/scripts:$PATH"
-  screenrig --json version
+  screenrig version
 fi
 ```
 
@@ -31,7 +31,7 @@ Require a successful version envelope, then run:
 
 ```bash
 screenrig-plugin-freshness --json
-screenrig --json doctor
+screenrig doctor
 ```
 
 For freshness, `keep` means continue, `refresh` means update the plugin using the
@@ -49,7 +49,7 @@ For a new account, obtain the user's contact email and use the supported explici
 step:
 
 ```bash
-screenrig --json agent enroll --email ADDRESS
+screenrig agent enroll --email ADDRESS
 ```
 
 Use the user's actual address. For an existing account, use `agent connect` and
@@ -62,8 +62,8 @@ shows a setup code, use `screen pair CODE` with that code. A missing screen is n
 reason to assign to another screen or invent an identifier.
 
 ```bash
-screenrig --json screen list
-screenrig --json screen show SCREEN_ID
+screenrig screen list
+screenrig screen show SCREEN_ID
 ```
 
 ## Choose the content path
@@ -110,7 +110,12 @@ provides a compact reference for supported operations.
 
 ## Responses, retries and secrets
 
-Use `--json`. Branch on `ok`, `error.status`, `error.code` and `warnings[].code`,
+Operational commands return JSON envelopes by default; `--json` remains a
+compatible explicit choice. Use `--human` only for manual inspection, never
+together with `--json`. Help and bare command groups are readable by default;
+`--json --help` returns structured help. Progress stays on stderr; parse stdout
+separately. `events follow` emits one JSON envelope per line (NDJSON).
+Branch on `ok`, `error.status`, `error.code` and `warnings[].code`,
 not prose. Follow an applicable `error.next.command` without inventing flags.
 On a revision conflict, refetch and reconcile the intended change. After an
 ambiguous write, retry with the same idempotency key and same request, not a new write.

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

@@ -17,7 +17,7 @@ reaches `window.screenrig` at runtime with no build step and no dependency to
 install.
 
 ```bash
-screenrig --json app upload ./lobby-board --name "Lobby board"
+screenrig app upload ./lobby-board --name "Lobby board"
 ```
 
 `app upload` waits for the publication operation by default. Read three fields
@@ -35,8 +35,8 @@ first immutable release. To repair or improve the same app, read its current
 revision with `app show`, then publish a new release:
 
 ```bash
-screenrig --json app show app_EXAMPLE
-screenrig --json app update app_EXAMPLE ./lobby-board --if-match 3
+screenrig app show app_EXAMPLE
+screenrig app update app_EXAMPLE ./lobby-board --if-match 3
 ```
 
 `app update` preserves application identity, name, and application K/V. It uses
@@ -115,9 +115,9 @@ must carry `controller: true`. Do not set `controller` on a `duration` or
 ### 4. Create the playlist and assign it to a screen
 
 ```bash
-screenrig --json playlist create ./lobby-board.json
-screenrig --json screen list
-screenrig --json screen assign scr_EXAMPLE --playlist-id pl_EXAMPLE --if-match 3
+screenrig playlist create ./lobby-board.json
+screenrig screen list
+screenrig screen assign scr_EXAMPLE --playlist-id pl_EXAMPLE --if-match 3
 ```
 
 Take `--playlist-id` from `data.id` of the `playlist create` result. Take
@@ -142,10 +142,10 @@ blocks on a WebP. Do not print pixels.
 Application K/V is binary-safe. Use exactly one value mode.
 
 ```bash
-screenrig --json kv set --application-id app_EXAMPLE lobby --json-value '{"open":true}'
-screenrig --json kv get --application-id app_EXAMPLE lobby
-screenrig --json kv list --application-id app_EXAMPLE
-screenrig --json kv delete --application-id app_EXAMPLE lobby --if-match REVISION
+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 --if-match REVISION
 ```
 
 `kv get` returns the stored bytes only as `data.value_base64`, including when

plugins/screenrig/skills/screenrig/references/commands.md

@@ -81,8 +81,13 @@ doctor [--repair-config]
 version
 ```
 
-Global flags go before the command: `--json`, `--api-url URL`, `--config
-PATH`, `--request-id ID`, `--idempotency-key KEY`, and `--timeout MS`.
+Operational commands default to JSON envelopes. `--json` remains supported;
+`--human` selects text and conflicts with `--json`. Help and bare command groups
+remain readable by default; use `screenrig --json --help` for structured help.
+`events follow` emits NDJSON. Progress goes to stderr, separately from stdout.
+
+Global flags include `--json`, `--human`, `--api-url URL`, `--config PATH`,
+`--request-id ID`, `--idempotency-key KEY`, and `--timeout MS`.
 
 On `revision_conflict`, fetch the resource, reapply the intended change, and
 retry with the returned revision. On an ambiguous transport failure, reuse the

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

@@ -26,13 +26,13 @@ before `compose render` so the directory name is the human handle. Default
 `generic_filename` warning will not rename on upload.
 
 ```bash
-screenrig --json compose catalog
-screenrig --json compose render ./exec-intro.json --output ./exec-intro
+screenrig compose catalog
+screenrig compose render ./exec-intro.json --output ./exec-intro
 # read ./exec-intro/manifest.json and the region PNGs
 # agent reads the PNGs with vision; do not cat pixels into chat
 # iterate the JSON and re-render
-screenrig --json media upload ./exec-intro/left.png --tag TAG
-screenrig --json media list --tag TAG --primitive image
+screenrig media upload ./exec-intro/left.png --tag TAG
+screenrig media list --tag TAG --primitive image
 # playlist page: image primitives at the manifest rects, or one combined image
 # many files: media upload-batch ./images.json --state ./upload-state.json
 ```
@@ -182,8 +182,8 @@ file is enough. `compose batch` adds a contact sheet and `--only ID`.
 ```
 
 ```bash
-screenrig --json compose render ./deck.json --output ./rendered --target-width 3840 --target-height 2160 --safe-area
-screenrig --json compose batch ./deck.json --output ./rendered --target-width 3840 --target-height 2160 --safe-area
+screenrig compose render ./deck.json --output ./rendered --target-width 3840 --target-height 2160 --safe-area
+screenrig compose batch ./deck.json --output ./rendered --target-width 3840 --target-height 2160 --safe-area
 ```
 
 `compose batch` accepts 1 to 2000 pages and returns ordered page results,
@@ -207,7 +207,7 @@ Validate the separate wire playlist locally before expensive upload/publication
 work, and again after replacing draft references with accepted resource IDs:
 
 ```bash
-screenrig --json playlist validate ./playlist.json
+screenrig playlist validate ./playlist.json
 ```
 
 This uses backend-generated schema and semantics, including application

plugins/screenrig/skills/screenrig/references/installation.md

@@ -42,15 +42,15 @@ package.
 SCREENRIG_PLUGIN_ROOT="${GROK_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-}}}}"
 if [ -n "$SCREENRIG_PLUGIN_ROOT" ]; then
   PATH="$SCREENRIG_PLUGIN_ROOT/skills/screenrig/scripts:$PATH"
-  screenrig --json version
+  screenrig version
 fi
 ```
 
 An empty root means use the lookup below before running the CLI; do not add
 `/skills/screenrig/scripts` to PATH. The plugin launcher is scoped to this
 shell session, so a new shell may need the same root lookup and PATH setup.
 
-Require a successful screenRIG JSON envelope from `--json version` before any
+Require a successful screenRIG JSON envelope from `version` before any
 other command.
 
 If `SCREENRIG_PLUGIN_ROOT` is empty after installation, recover it without
@@ -64,7 +64,7 @@ entry whose `pluginId` is `screenrig@screenrig`, and use its `source.path`.
 4. For Grok, run `grok plugin list` and use the installed screenRIG plugin
 path, then export it as `GROK_PLUGIN_ROOT` for this session.
 5. Prepend `<plugin-root>/skills/screenrig/scripts` to `PATH` and run
-`screenrig --json version`. Require a successful screenRIG JSON envelope
+`screenrig version`. Require a successful screenRIG JSON envelope
 before the requested command. Do not export `SR`.
 
 If there is no matching entry, run the exact canonical marketplace add/install
@@ -73,8 +73,14 @@ report the failing runtime command and the canonical repository URL to the
 user. Do not substitute a globally installed command or download an
 executable.
 
-Use `--json` for agent work. Branch on `ok`, `error.status`, and `error.code`;
-do not parse prose.
+Operational commands use JSON by default. If an older installed bundle returns
+prose, add `--json` until the plugin is updated. The separate
+`screenrig-plugin-freshness` helper still requires `--json`.
+
+Use `--human` only for manual text output; it cannot be combined with `--json`.
+Help and bare command groups are readable by default, with structured discovery
+available through `--json --help`. Branch on `ok`, `error.status`, and
+`error.code`; do not parse prose. Keep stdout separate from progress on stderr.
 
 ## Detect and refresh
 
@@ -83,7 +89,7 @@ installed plugin and bundled CLI to the published plugin version on GitHub
 `main`. Skill text and the bundled CLI travel together. Do not PATH-swap in a
 local checkout. Do not `npm i -g screenrig`. Do not install a global package.
 
-After PATH prepend and a successful `screenrig --json version`, run:
+After PATH prepend and a successful `screenrig version`, run:
 
 ```bash
 screenrig-plugin-freshness --json
@@ -125,4 +131,4 @@ If a probed update command is missing, re-run the exact canonical marketplace
 add and install commands above. Grok install must keep `--trust`. Refresh
 updates skill text and the bundled CLI together. After refresh, re-resolve
 the plugin root, prepend scripts to PATH, and require a successful
-`screenrig --json version` envelope before any other command.
+`screenrig version` envelope before any other command.

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

@@ -5,7 +5,7 @@ Use the authoring choice in the main skill before opening this reference.
 ## Generate a finished still
 
 Use the task selection in the main skill. Choose the intended aspect ratio from
-`screenrig --json screen show SCREEN_ID` or the user's supplied dimensions before
+`screenrig screen show SCREEN_ID` or the user's supplied dimensions before
 generation. If the screen has no observation, confirm its orientation. Fit and
 cropping are deliberate choices; a source image's aspect need not match a canvas
 when the design intentionally contains or crops it.
@@ -29,7 +29,7 @@ Use a consistent campaign style rather than forcing variation on every page.
 For example, a fictional bookshop announcement:
 
 ```bash
-screenrig --json media generate --aspect-ratio 16:9 --quality medium --tag AuthorNight --prompt "Landscape 16:9 event poster artwork for fictional Example Books. Full bleed. Two-colour risograph style: paper white, teal and coral. Exact copy: 'Author Night', 'Guest Author reads from Sample Title', 'Thursday 24 September, 7 pm', 'Free entry', 'Fictional Example Books, Main Hall'. Large readable headline, clear time and location, open-book illustration. Artwork only, no display device or additional text."
+screenrig media generate --aspect-ratio 16:9 --quality medium --tag AuthorNight --prompt "Landscape 16:9 event poster artwork for fictional Example Books. Full bleed. Two-colour risograph style: paper white, teal and coral. Exact copy: 'Author Night', 'Guest Author reads from Sample Title', 'Thursday 24 September, 7 pm', 'Free entry', 'Fictional Example Books, Main Hall'. Large readable headline, clear time and location, open-book illustration. Artwork only, no display device or additional text."
 ```
 
 Read [visual design](composition.md) when establishing a layout or reviewing a
@@ -60,8 +60,8 @@ as a hang, and allow at least three minutes in any wrapper that imposes a
 timeout of its own.
 
 Do not pass `--timeout` on generate. The CLI budgets 150 s for this call by
-default, above the server's own budget, so plain `screenrig --json media
-generate …` completes at `high`. Under `--json` the command writes one
+default, above the server's own budget, so plain `screenrig media
+generate …` completes at `high`. With default JSON output the command writes one
 `media_generate_started` line to stderr before it blocks, carrying `quality`,
 `typical_seconds`, and `timeout_ms` and never the prompt; `--no-progress`
 suppresses it. The success envelope reports `elapsed_ms` beside `media_id`.
@@ -109,7 +109,7 @@ regenerating, not by composing a correction over the top. Never print the
 downloaded bytes.
 
 ```bash
-screenrig --json media download med_EXAMPLE --output ./burger-board.webp
+screenrig media download med_EXAMPLE --output ./burger-board.webp
 ```
 
 `--output` is a file path, not a directory; the default is `./<id>.<ext>` in
@@ -126,7 +126,7 @@ using a generated picture, not text layered over a generated poster.
 ## Doctor
 
 ```bash
-screenrig --json doctor
+screenrig doctor
 ```
 
 Read `data.status` and `data.checks`. Each check is `pass`, `warn`, or `fail`.
@@ -237,7 +237,7 @@ local bytes. Items already present with a `media_id` are reported as
 `resumed`. Do not share one state file across accounts.
 
 ```bash
-screenrig --json media upload-batch ./images.json --state ./upload-state.json
+screenrig media upload-batch ./images.json --state ./upload-state.json
 ```
 
 The envelope carries `data.items[]`, one row per item that reached the
@@ -247,6 +247,6 @@ a batch no longer needs a follow-up `media list --tag` to learn what it
 created. `data.failed[]` carries the items that did not land, with their
 problem code and status.
 
-Run `doctor --json` for local diagnostics. Use
-`doctor --repair-config --json` only to repair an existing credential file
+Run `doctor` for local diagnostics. Use
+`doctor --repair-config` only to repair an existing credential file
 whose permissions are too broad.