diff --git a/AGENTS.md b/AGENTS.md
index 0926dd49..6a35ab08 100644
--- a/AGENTS.md
+++ b/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
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5713e9a5..4fdf0634 100644
--- a/CONTRIBUTING.md
+++ b/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.
diff --git a/components.lock.json b/components.lock.json
index a9c7b65a..bc8640c3 100644
--- a/components.lock.json
+++ b/components.lock.json
@@ -6,7 +6,7 @@
     "commit": "d007df89b308e391584e5731c4c53e2fe20bf273",
     "artifact": {
       "file": "screenrig-cli.tgz",
-      "sha256": "9f95563e14710828e891cb2362ca050b9328ed59928ab7277c5bd9639b77dc8d"
+      "sha256": "0f7a7dbd685c34461840e706660ebcee98cddfbc510e86089cca7611e8e5475c"
     }
   }
 }
diff --git a/plugins/screenrig/CONTRIBUTING.md b/plugins/screenrig/CONTRIBUTING.md
index 5713e9a5..4fdf0634 100644
--- a/plugins/screenrig/CONTRIBUTING.md
+++ b/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.
diff --git a/plugins/screenrig/skills/screenrig/SKILL.md b/plugins/screenrig/skills/screenrig/SKILL.md
index 1f5dc433..c41356e7 100644
--- a/plugins/screenrig/skills/screenrig/SKILL.md
+++ b/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.
diff --git a/plugins/screenrig/skills/screenrig/references/applications.md b/plugins/screenrig/skills/screenrig/references/applications.md
index f2d5d73b..19cd9f97 100644
--- a/plugins/screenrig/skills/screenrig/references/applications.md
+++ b/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
diff --git a/plugins/screenrig/skills/screenrig/references/commands.md b/plugins/screenrig/skills/screenrig/references/commands.md
index dcae5f1c..e35a0b50 100644
--- a/plugins/screenrig/skills/screenrig/references/commands.md
+++ b/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
diff --git a/plugins/screenrig/skills/screenrig/references/compose.md b/plugins/screenrig/skills/screenrig/references/compose.md
index 61f0489f..9e209f13 100644
--- a/plugins/screenrig/skills/screenrig/references/compose.md
+++ b/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
diff --git a/plugins/screenrig/skills/screenrig/references/installation.md b/plugins/screenrig/skills/screenrig/references/installation.md
index 79c45ab3..8c28c64a 100644
--- a/plugins/screenrig/skills/screenrig/references/installation.md
+++ b/plugins/screenrig/skills/screenrig/references/installation.md
@@ -42,7 +42,7 @@ 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
 ```
 
@@ -50,7 +50,7 @@ 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.
diff --git a/plugins/screenrig/skills/screenrig/references/media.md b/plugins/screenrig/skills/screenrig/references/media.md
index 8f19ade3..a8af6bfb 100644
--- a/plugins/screenrig/skills/screenrig/references/media.md
+++ b/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.
diff --git a/plugins/screenrig/skills/screenrig/references/operations.md b/plugins/screenrig/skills/screenrig/references/operations.md
index 23d5bbf0..b1dff90e 100644
--- a/plugins/screenrig/skills/screenrig/references/operations.md
+++ b/plugins/screenrig/skills/screenrig/references/operations.md
@@ -3,15 +3,15 @@
 ## Screens
 
 ```bash
-screenrig --json screen list
-screenrig --json screen show scr_EXAMPLE
-screenrig --json screen update scr_EXAMPLE --name "Lobby" --playlist-id pl_EXAMPLE --if-match REVISION
-screenrig --json screen assign scr_EXAMPLE --playlist-id pl_EXAMPLE --if-match REVISION
-screenrig --json screen set-timezone scr_EXAMPLE --timezone America/Los_Angeles --if-match REVISION
-screenrig --json screen archive scr_EXAMPLE --if-match REVISION
-screenrig --json screen unarchive scr_EXAMPLE --if-match REVISION
-screenrig --json screen toast scr_EXAMPLE --text "Updated lobby loop" --level info
-screenrig --json screen screenshot scr_EXAMPLE --output ./lobby.webp
+screenrig screen list
+screenrig screen show scr_EXAMPLE
+screenrig screen update scr_EXAMPLE --name "Lobby" --playlist-id pl_EXAMPLE --if-match REVISION
+screenrig screen assign scr_EXAMPLE --playlist-id pl_EXAMPLE --if-match REVISION
+screenrig screen set-timezone scr_EXAMPLE --timezone America/Los_Angeles --if-match REVISION
+screenrig screen archive scr_EXAMPLE --if-match REVISION
+screenrig screen unarchive scr_EXAMPLE --if-match REVISION
+screenrig screen toast scr_EXAMPLE --text "Updated lobby loop" --level info
+screenrig screen screenshot scr_EXAMPLE --output ./lobby.webp
 ```
 
 `screen list` omits archived screens. `screen list --state archived` lists
@@ -52,10 +52,10 @@ value must be an object. screenRIG does not read or use it and never sends it
 to players.
 
 ```bash
-screenrig --json comment set screen scr_EXAMPLE --json-value '{"note":"lobby hours"}'
-screenrig --json comment show screen scr_EXAMPLE
-screenrig --json comment set playlist pl_EXAMPLE --page poster --file ./note.json
-screenrig --json comment delete screen scr_EXAMPLE
+screenrig comment set screen scr_EXAMPLE --json-value '{"note":"lobby hours"}'
+screenrig comment show screen scr_EXAMPLE
+screenrig comment set playlist pl_EXAMPLE --page poster --file ./note.json
+screenrig comment delete screen scr_EXAMPLE
 ```
 
 `--json-value` is a JSON object. `--file` reads a JSON object from disk.
@@ -64,9 +64,10 @@ Unset show is `{ "comments": null }`.
 
 ## Events
 
-Human `events list` and `events follow` print one logfmt line per event.
-`--json events list` is one JSON page envelope. `--json events follow` is a
-JSON stream of envelopes.
+`events list` returns one JSON page envelope by default. `events follow` emits
+NDJSON: one JSON envelope per line. An empty follow emits an envelope with
+`data.items: []`. `--human events list` and `--human events follow` select one
+logfmt line per event for manual inspection. `--json` remains compatible.
 
 An `application.event` line leads its details with `code` and `primitive_id`,
 the id of the primitive that emitted it.
@@ -97,10 +98,10 @@ supplied cursor.
 ## Feedback
 
 ```bash
-screenrig --json feedback bug "Playlist stalls after assign" \
+screenrig feedback bug "Playlist stalls after assign" \
   --body-file ./report.md --command "screen assign"
-screenrig --json feedback feature "Add a dry-run flag" --body "Preview a change first."
-screenrig --json feedback list [--kind bug|feature]
+screenrig feedback feature "Add a dry-run flag" --body "Preview a change first."
+screenrig feedback list [--kind bug|feature]
 ```
 
 `--body` is inline text. `--body-file` reads a file. A title is at most 120
diff --git a/plugins/screenrig/skills/screenrig/references/playlists.md b/plugins/screenrig/skills/screenrig/references/playlists.md
index 7b71077d..57e9056c 100644
--- a/plugins/screenrig/skills/screenrig/references/playlists.md
+++ b/plugins/screenrig/skills/screenrig/references/playlists.md
@@ -301,7 +301,7 @@ owns it. `{"days": ["fri"], "start": "22:00", "end": "02:00"}` runs Friday
 22:00 through Saturday 02:00.
 
 ```bash
-screenrig --json screen set-timezone scr_EXAMPLE --timezone America/Los_Angeles --if-match 3
+screenrig screen set-timezone scr_EXAMPLE --timezone America/Los_Angeles --if-match 3
 ```
 
 `--timezone` is an IANA identifier such as `America/Los_Angeles` or
@@ -314,9 +314,9 @@ Use a `screenrig.playlist-bundle/v1` directory to move one playlist and every
 referenced image or video rendition together.
 
 ```bash
-screenrig --json playlist export pl_EXAMPLE --output ./lobby-bundle
-screenrig --json playlist import ./lobby-bundle
-screenrig --json playlist import ./lobby-bundle --update pl_TARGET --if-match REVISION
+screenrig playlist export pl_EXAMPLE --output ./lobby-bundle
+screenrig playlist import ./lobby-bundle
+screenrig playlist import ./lobby-bundle --update pl_TARGET --if-match REVISION
 ```
 
 The export destination must not exist. The bundle contains
@@ -332,5 +332,5 @@ that problem's `error.next` names the two ways forward. `--name NAME` (1 to
 Updating requires both `--update` and the current `--if-match` revision.
 
 ```bash
-screenrig --json playlist import ./lobby-bundle --name "Lobby loop (copy)"
+screenrig playlist import ./lobby-bundle --name "Lobby loop (copy)"
 ```
diff --git a/scripts/build-plugin.py b/scripts/build-plugin.py
index d5877b46..eb6c5913 100755
--- a/scripts/build-plugin.py
+++ b/scripts/build-plugin.py
@@ -379,6 +379,23 @@ def verify_generated_launcher(plugin_root: Path) -> None:
         raise BuildError("generated plugin launcher did not run the bundled CLI with clean offline output")
 
 
+def copy_docs(plugin_root: Path) -> None:
+    """Refresh canonical public files and skills without changing CLI provenance."""
+    public_root = PUBLIC_ROOT if PUBLIC_ROOT.is_dir() else ROOT
+    plugin_root.mkdir(parents=True, exist_ok=True)
+    for relative in PUBLIC_FILES:
+        source = public_root / relative
+        if not source.is_file():
+            raise BuildError(f"public plugin root file is missing: {relative}")
+        destination = plugin_root / relative
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(source, destination)
+    skill_target = plugin_root / "skills" / PLUGIN_NAME
+    if skill_target.exists():
+        shutil.rmtree(skill_target)
+    shutil.copytree(SKILL, skill_target)
+
+
 def build(
     output: Path,
     cli_artifact: Path | None = None,
@@ -392,16 +409,7 @@ def build(
         raise BuildError("build/plugin.json name must be screenrig")
     release_version = version()
     plugin_root = output / PLUGIN_NAME
-    public_root = PUBLIC_ROOT if PUBLIC_ROOT.is_dir() else ROOT
-    plugin_root.mkdir(parents=True, exist_ok=True)
-    for relative in PUBLIC_FILES:
-        source = public_root / relative
-        if not source.is_file():
-            raise BuildError(f"public plugin root file is missing: {relative}")
-        destination = plugin_root / relative
-        destination.parent.mkdir(parents=True, exist_ok=True)
-        shutil.copy2(source, destination)
-    shutil.copytree(SKILL, plugin_root / "skills" / PLUGIN_NAME)
+    copy_docs(plugin_root)
 
     cli_root = plugin_root / "cli"
     with cli_input(cli_artifact, write_lock=write_lock, cli_commit=cli_commit, check=check) as (
@@ -446,9 +454,26 @@ def compare(expected: Path, actual: Path) -> list[str]:
     return changes
 
 
+def compare_docs(expected: Path, actual: Path) -> list[str]:
+    changes = compare(expected / "skills" / PLUGIN_NAME, actual / "skills" / PLUGIN_NAME)
+    for relative in PUBLIC_FILES:
+        source, target = expected / relative, actual / relative
+        if not target.is_file():
+            changes.append(f"missing {relative}")
+        elif not filecmp.cmp(source, target, shallow=False):
+            changes.append(f"changed {relative}")
+        elif file_mode(source) != file_mode(target):
+            changes.append(f"mode {relative}")
+    return changes
+
+
 def main() -> int:
     parser = argparse.ArgumentParser()
     parser.add_argument("--check", action="store_true")
+    parser.add_argument(
+        "--docs-only", action="store_true",
+        help="refresh canonical public files and skills in an existing bundle; preserve CLI, manifests and provenance",
+    )
     parser.add_argument("--cli-artifact", type=Path, help="tarball packed from sibling ../cli or current screenrig/cli main")
     parser.add_argument(
         "--write-lock",
@@ -460,6 +485,9 @@ def main() -> int:
         help="commit that produced the packed tarball, recorded as provenance only",
     )
     args = parser.parse_args()
+    if args.docs_only and (args.cli_artifact or args.write_lock or args.cli_commit):
+        print("build-plugin: --docs-only cannot be combined with CLI artifact or provenance options", file=sys.stderr)
+        return 2
     if args.write_lock and args.check:
         print("build-plugin: --write-lock cannot be combined with --check", file=sys.stderr)
         return 2
@@ -467,6 +495,25 @@ def main() -> int:
         print("build-plugin: --cli-commit must be a 40-character lowercase SHA-1", file=sys.stderr)
         return 2
     try:
+        if args.docs_only:
+            target = PLUGINS / PLUGIN_NAME
+            if not (target / "cli" / "package.json").is_file():
+                raise BuildError("--docs-only requires an existing generated CLI bundle")
+            if args.check:
+                with tempfile.TemporaryDirectory(prefix="screenrig-plugin-docs-") as temp:
+                    expected = Path(temp) / PLUGIN_NAME
+                    copy_docs(expected)
+                    changes = compare_docs(expected, target)
+                    if changes:
+                        print("generated ScreenRig plugin docs are stale:", file=sys.stderr)
+                        for change in changes:
+                            print(f"  {change}", file=sys.stderr)
+                        return 1
+                print("generated ScreenRig plugin docs are current; CLI bundle not checked")
+                return 0
+            copy_docs(target)
+            print("updated ScreenRig plugin docs; CLI bundle and provenance unchanged")
+            return 0
         if args.check:
             with tempfile.TemporaryDirectory(prefix="screenrig-plugin-") as temp:
                 expected = Path(temp) / "plugins"
diff --git a/scripts/test-docs-only.py b/scripts/test-docs-only.py
new file mode 100644
index 00000000..bfb60eed
--- /dev/null
+++ b/scripts/test-docs-only.py
@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+"""Verify documentation refresh preserves executable bytes and provenance."""
+
+from __future__ import annotations
+
+import contextlib
+import importlib.util
+import io
+from pathlib import Path
+import sys
+import tempfile
+from unittest.mock import patch
+
+ROOT = Path(__file__).resolve().parent.parent
+spec = importlib.util.spec_from_file_location("build_plugin", ROOT / "scripts/build-plugin.py")
+assert spec and spec.loader
+builder = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(builder)
+
+
+def run(*args: str) -> int:
+    with patch.object(sys, "argv", ["build-plugin.py", *args]):
+        with contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(io.StringIO()):
+            return builder.main()
+
+
+def main() -> None:
+    with tempfile.TemporaryDirectory(prefix="screenrig-docs-only-test-") as temporary:
+        root = Path(temporary)
+        plugins = root / "plugins"
+        target = plugins / "screenrig"
+        protected = {
+            target / "cli/package.json": b'{"version":"26.09.1"}\n',
+            target / "cli/dist/bin.js": b'// preserved executable\n',
+            target / ".codex-plugin/plugin.json": b'{"version":"26.09.1"}\n',
+            target / ".claude-plugin/plugin.json": b'{"version":"26.09.1"}\n',
+            root / "components.lock.json": b'{"provenance":"preserved"}\n',
+        }
+        for path, content in protected.items():
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_bytes(content)
+        executable = target / "cli/dist/bin.js"
+        executable.chmod(0o755)
+        stale = target / "skills/screenrig/references/obsolete.md"
+        stale.parent.mkdir(parents=True)
+        stale.write_text("obsolete generated documentation\n")
+        with patch.object(builder, "PLUGINS", plugins), patch.object(builder, "LOCK_PATH", root / "components.lock.json"):
+            assert run("--docs-only", "--check") == 1
+            assert run("--docs-only") == 0
+            assert not stale.exists()
+            assert run("--docs-only", "--check") == 0
+            for path, content in protected.items():
+                assert path.read_bytes() == content, f"changed protected file: {path}"
+            assert executable.stat().st_mode & 0o777 == 0o755
+            for options in (("--cli-artifact", "unused.tgz"), ("--write-lock",), ("--cli-commit", "a" * 40)):
+                assert run("--docs-only", *options) == 2
+            (target / "cli/package.json").unlink()
+            assert run("--docs-only") == 2
+    print("documentation-only generation checks passed")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/validate-plugin.py b/scripts/validate-plugin.py
index f401db7c..e006b60b 100755
--- a/scripts/validate-plugin.py
+++ b/scripts/validate-plugin.py
@@ -370,8 +370,8 @@ def check_no_alternate_surfaces(cli_source: Path | None) -> None:
         audit_paths.extend(cli_source / relative for relative in CLI_SOURCE_FILES)
     required_marketplace = {
         "README.md": ["https://screenrig.ai/docs/start/", "SECURITY.md", "Node.js 20.11"],
-        "skills/screenrig/SKILL.md": ["screenrig --json version", "screenrig-plugin-freshness --json",
-            "screenrig --json doctor", "not_enrolled", "agent enroll", "--if-match",
+        "skills/screenrig/SKILL.md": ["screenrig version", "screenrig-plugin-freshness --json",
+            "screenrig doctor", "not_enrolled", "agent enroll", "--if-match",
             "payment_required", "idempotency", "references/commands.md"],
     }
     for relative, facts in required_marketplace.items():
diff --git a/skills/screenrig/SKILL.md b/skills/screenrig/SKILL.md
index 1f5dc433..c41356e7 100644
--- a/skills/screenrig/SKILL.md
+++ b/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.
diff --git a/skills/screenrig/references/applications.md b/skills/screenrig/references/applications.md
index f2d5d73b..19cd9f97 100644
--- a/skills/screenrig/references/applications.md
+++ b/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
diff --git a/skills/screenrig/references/commands.md b/skills/screenrig/references/commands.md
index dcae5f1c..e35a0b50 100644
--- a/skills/screenrig/references/commands.md
+++ b/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
diff --git a/skills/screenrig/references/compose.md b/skills/screenrig/references/compose.md
index 61f0489f..9e209f13 100644
--- a/skills/screenrig/references/compose.md
+++ b/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
diff --git a/skills/screenrig/references/installation.md b/skills/screenrig/references/installation.md
index 79c45ab3..8c28c64a 100644
--- a/skills/screenrig/references/installation.md
+++ b/skills/screenrig/references/installation.md
@@ -42,7 +42,7 @@ 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
 ```
 
@@ -50,7 +50,7 @@ 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.
diff --git a/skills/screenrig/references/media.md b/skills/screenrig/references/media.md
index 8f19ade3..a8af6bfb 100644
--- a/skills/screenrig/references/media.md
+++ b/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.
diff --git a/skills/screenrig/references/operations.md b/skills/screenrig/references/operations.md
index 23d5bbf0..b1dff90e 100644
--- a/skills/screenrig/references/operations.md
+++ b/skills/screenrig/references/operations.md
@@ -3,15 +3,15 @@
 ## Screens
 
 ```bash
-screenrig --json screen list
-screenrig --json screen show scr_EXAMPLE
-screenrig --json screen update scr_EXAMPLE --name "Lobby" --playlist-id pl_EXAMPLE --if-match REVISION
-screenrig --json screen assign scr_EXAMPLE --playlist-id pl_EXAMPLE --if-match REVISION
-screenrig --json screen set-timezone scr_EXAMPLE --timezone America/Los_Angeles --if-match REVISION
-screenrig --json screen archive scr_EXAMPLE --if-match REVISION
-screenrig --json screen unarchive scr_EXAMPLE --if-match REVISION
-screenrig --json screen toast scr_EXAMPLE --text "Updated lobby loop" --level info
-screenrig --json screen screenshot scr_EXAMPLE --output ./lobby.webp
+screenrig screen list
+screenrig screen show scr_EXAMPLE
+screenrig screen update scr_EXAMPLE --name "Lobby" --playlist-id pl_EXAMPLE --if-match REVISION
+screenrig screen assign scr_EXAMPLE --playlist-id pl_EXAMPLE --if-match REVISION
+screenrig screen set-timezone scr_EXAMPLE --timezone America/Los_Angeles --if-match REVISION
+screenrig screen archive scr_EXAMPLE --if-match REVISION
+screenrig screen unarchive scr_EXAMPLE --if-match REVISION
+screenrig screen toast scr_EXAMPLE --text "Updated lobby loop" --level info
+screenrig screen screenshot scr_EXAMPLE --output ./lobby.webp
 ```
 
 `screen list` omits archived screens. `screen list --state archived` lists
@@ -52,10 +52,10 @@ value must be an object. screenRIG does not read or use it and never sends it
 to players.
 
 ```bash
-screenrig --json comment set screen scr_EXAMPLE --json-value '{"note":"lobby hours"}'
-screenrig --json comment show screen scr_EXAMPLE
-screenrig --json comment set playlist pl_EXAMPLE --page poster --file ./note.json
-screenrig --json comment delete screen scr_EXAMPLE
+screenrig comment set screen scr_EXAMPLE --json-value '{"note":"lobby hours"}'
+screenrig comment show screen scr_EXAMPLE
+screenrig comment set playlist pl_EXAMPLE --page poster --file ./note.json
+screenrig comment delete screen scr_EXAMPLE
 ```
 
 `--json-value` is a JSON object. `--file` reads a JSON object from disk.
@@ -64,9 +64,10 @@ Unset show is `{ "comments": null }`.
 
 ## Events
 
-Human `events list` and `events follow` print one logfmt line per event.
-`--json events list` is one JSON page envelope. `--json events follow` is a
-JSON stream of envelopes.
+`events list` returns one JSON page envelope by default. `events follow` emits
+NDJSON: one JSON envelope per line. An empty follow emits an envelope with
+`data.items: []`. `--human events list` and `--human events follow` select one
+logfmt line per event for manual inspection. `--json` remains compatible.
 
 An `application.event` line leads its details with `code` and `primitive_id`,
 the id of the primitive that emitted it.
@@ -97,10 +98,10 @@ supplied cursor.
 ## Feedback
 
 ```bash
-screenrig --json feedback bug "Playlist stalls after assign" \
+screenrig feedback bug "Playlist stalls after assign" \
   --body-file ./report.md --command "screen assign"
-screenrig --json feedback feature "Add a dry-run flag" --body "Preview a change first."
-screenrig --json feedback list [--kind bug|feature]
+screenrig feedback feature "Add a dry-run flag" --body "Preview a change first."
+screenrig feedback list [--kind bug|feature]
 ```
 
 `--body` is inline text. `--body-file` reads a file. A title is at most 120
diff --git a/skills/screenrig/references/playlists.md b/skills/screenrig/references/playlists.md
index 7b71077d..57e9056c 100644
--- a/skills/screenrig/references/playlists.md
+++ b/skills/screenrig/references/playlists.md
@@ -301,7 +301,7 @@ owns it. `{"days": ["fri"], "start": "22:00", "end": "02:00"}` runs Friday
 22:00 through Saturday 02:00.
 
 ```bash
-screenrig --json screen set-timezone scr_EXAMPLE --timezone America/Los_Angeles --if-match 3
+screenrig screen set-timezone scr_EXAMPLE --timezone America/Los_Angeles --if-match 3
 ```
 
 `--timezone` is an IANA identifier such as `America/Los_Angeles` or
@@ -314,9 +314,9 @@ Use a `screenrig.playlist-bundle/v1` directory to move one playlist and every
 referenced image or video rendition together.
 
 ```bash
-screenrig --json playlist export pl_EXAMPLE --output ./lobby-bundle
-screenrig --json playlist import ./lobby-bundle
-screenrig --json playlist import ./lobby-bundle --update pl_TARGET --if-match REVISION
+screenrig playlist export pl_EXAMPLE --output ./lobby-bundle
+screenrig playlist import ./lobby-bundle
+screenrig playlist import ./lobby-bundle --update pl_TARGET --if-match REVISION
 ```
 
 The export destination must not exist. The bundle contains
@@ -332,5 +332,5 @@ that problem's `error.next` names the two ways forward. `--name NAME` (1 to
 Updating requires both `--update` and the current `--if-match` revision.
 
 ```bash
-screenrig --json playlist import ./lobby-bundle --name "Lobby loop (copy)"
+screenrig playlist import ./lobby-bundle --name "Lobby loop (copy)"
 ```