@skillcap/gdh 0.13.2 → 0.14.0

package/INSTALL-BUNDLE.json

@@ -1,5 +1,5 @@
 {
   "product": "GDH",
-  "version": "0.13.2",
+  "version": "0.14.0",
   "installMode": "packaged_install"
 }

package/README.md

@@ -12,10 +12,10 @@ GDH detects your Godot project, configures your AI agents, and gives them the co
 ## Install
 
 ```sh
-npx -y @skillcap/gdh@0.13.2 setup
+npx -y @skillcap/gdh@0.14.0 setup
 ```
 
-Replace `0.13.2` with the GDH version you want to pin this project to. `gdh setup` records the pinned version in `.gdh/project.yaml`; every managed surface generated from that config invokes GDH at that exact pinned version, so future sessions stay reproducible.
+Replace `0.14.0` with the GDH version you want to pin this project to. `gdh setup` records the pinned version in `.gdh/project.yaml`; every managed surface generated from that config invokes GDH at that exact pinned version, so future sessions stay reproducible.
 
 From `0.9.0` onward, the shipped package also carries bounded release-span update metadata in `RELEASE-SPAN-UPDATE-CONTRACTS.json` so update flows can explain release-specific migration steps without reading repo-only `docs/releases/` files at target runtime.
 
@@ -36,7 +36,7 @@ The full install and update contract lives in [install-and-update.md](docs/devel
 
 ```sh
 # 1. Run setup in your Godot project
-npx -y @skillcap/gdh@0.13.2 setup
+npx -y @skillcap/gdh@0.14.0 setup
 
 # 2. Open your AI agent (Claude, Cursor, Codex) in the repo
 
@@ -101,7 +101,7 @@ The CLI exists for advanced operators, debugging, and automation. Update preview
 
 ## Status
 
-GDH now ships the current `0.13.2` release line and remains ready for broader internal use within the documented support contract. The current release line is `0.13.2` at the `broader_internal_release` stage.
+GDH now ships the current `0.14.0` release line and remains ready for broader internal use within the documented support contract. The current release line is `0.14.0` at the `broader_internal_release` stage.
 That line includes one first-class Docker-backed rendered runtime provider and bounded screenshot evidence on rendered-capable paths.
 
 The release-stage label applies only to the documented support window in [runtime-support-matrix.md](docs/development/runtime-support-matrix.md) and [runtime-release-readiness.md](docs/development/runtime-release-readiness.md). It is not a blanket claim that every Godot project shape is supported or that this implementation checkout should behave like a GDH-managed target repo.

package/RELEASE-SPAN-UPDATE-CONTRACTS.json

@@ -891,6 +891,127 @@
           }
         ]
       }
+    },
+    {
+      "version": "0.13.3",
+      "releaseTag": "v0.13.3",
+      "migrationStatus": "no_op",
+      "summary": "v0.13.3 restores GDH-owned rendered screenshot verification after the v0.13.2 regression. Verification scenarios can again request one supporting screenshot artifact through the canonical `artifact_policy.screenshots: \"rendered\"` policy, legacy `\"fallback\"` remains a compatibility alias, the shipped Docker rendered-runtime image is rebuilt around current Node and Godot truth, and runtime-bridge screenshot capture now waits for real scene readiness before declaring success or failure. Existing targets do not require a new release-scoped managed-project migrate step for this release line.",
+      "releaseHighlights": {
+        "summary": "v0.13.3 is a patch release that restores GDH-owned rendered screenshot verification after the v0.13.2 regression. Verification scenarios can again request one supporting rendered screenshot artifact through the canonical `artifact_policy.screenshots: \"rendered\"` policy, legacy `\"fallback\"` remains accepted as a compatibility alias, and the shipped Docker plus runtime-bridge path is hardened enough to pass the real Beacon title-screen proof again.",
+        "operatorChanges": [
+          "**Rendered screenshot requests are reachable again through GDH's normal verification surfaces.** `gdh verify run` and `gdh run-config run` now share an explicit rendered-screenshot request contract, verification scenarios can declare `artifact_policy.screenshots: \"rendered\"`, and legacy `\"fallback\"` now normalizes to the same supporting-artifact behavior instead of blocking the run outright.",
+          "**The shipped Docker rendered-runtime image is rebuilt around the current toolchain truth.** The default image now targets `gdh-runtime-rendered:4.6-stable-r3`, uses Ubuntu 24.04 plus Node 22 and Godot 4.6, and exposes both `godot-linux` and `godot` inside the container for consistent GDH and manual debugging behavior.",
+          "**Rendered Docker launches are more resilient against real-target drift.** GDH now overlays sanitized `project.godot` and `.godot/extension_list.cfg` inputs for Docker Godot launches, rewrites stale UID-backed main-scene references when a resolvable `res://` path exists, forces dummy audio, and allows a longer Docker bridge handshake for slow real targets.",
+          "**Managed bridge screenshot capture is now honest about scene readiness.** The runtime bridge waits for a real current scene before attempting capture, keeps retrying until the viewport image is actually ready, and writes structured unavailability metadata when the session exits before capture completes."
+        ]
+      },
+      "updateContract": {
+        "summary": "No release-specific managed migration is required after self-update. v0.13.3 restores rendered screenshot verification and hardens the Docker plus bridge path; if a target still behaves like the older bridge template, use the ordinary `gdh bridge status` and `gdh bridge repair` flow before retrying rendered verification.",
+        "steps": [
+          {
+            "id": "repair_managed_bridge_if_rendered_verify_still_looks_stale",
+            "kind": "mechanical",
+            "summary": "If rendered verification still behaves like the older managed bridge files, run the ordinary bridge repair flow before retrying.",
+            "detail": "v0.13.3 does not bump a managed surface version, but it does ship a stricter runtime-bridge screenshot path. When a target still carries older managed bridge files or rendered verification exits before a scene becomes ready, use `gdh bridge status` and `gdh bridge repair` to rebake the managed bridge baseline. This is bounded ordinary repair, not a new release-scoped migrate step.",
+            "commands": [
+              "gdh bridge status",
+              "gdh bridge repair"
+            ],
+            "validationCommands": [
+              "gdh bridge status",
+              "gdh verify run <target> <run-config-id> --verification-scenario <scenario-id> --provider docker"
+            ]
+          },
+          {
+            "id": "prefer_canonical_rendered_policy_for_project_owned_scenarios",
+            "kind": "agent_reasoning",
+            "summary": "Project-owned screenshot scenarios should prefer `artifact_policy.screenshots: \"rendered\"` going forward.",
+            "detail": "Legacy `\"fallback\"` remains accepted as a compatibility alias in v0.13.3, but `\"rendered\"` is the canonical screenshot policy now and keeps docs, tests, and future migrations aligned. Scenario truth should still come from project-owned signals rather than image interpretation.",
+            "commands": [],
+            "validationCommands": []
+          }
+        ]
+      }
+    },
+    {
+      "version": "0.14.0",
+      "releaseTag": "v0.14.0",
+      "migrationStatus": "required",
+      "summary": "v0.14.0 expands state-first runtime verification with node-presence and signal waiters, persists waiter evidence in run records, and refreshes shipped guidance to the canonical rendered-screenshot plus waiter vocabulary. The release changes both GDH_GUIDANCE_UNIT_VERSION (2 -> 3) and GDH_RUNTIME_BRIDGE_SURFACE_VERSION (3 -> 4), so managed targets need release-specific follow-through: bridge-enabled targets repair the runtime bridge and finish plugin/autoload registration, then onboarded targets run `gdh migrate --apply` to regenerate guidance units and return to a healthy lifecycle state.",
+      "releaseHighlights": {
+        "summary": "v0.14.0 pushes GDH runtime verification toward state-first proof instead of ad hoc polling. The managed runtime bridge now supports node-presence and signal-observation waiters, run records preserve waiter evidence and clearer rendered failure classes, and the shipped guidance plus bridge surfaces move to versions `3` and `4`. Because both managed guidance units and the managed runtime bridge surface changed, this release requires a bounded post-update migration path.",
+        "operatorChanges": [
+          "**Bounded waiter coverage expands beyond node-property polling.** The managed runtime bridge now ships the plumbing behind `state.node_presence.await` and `state.signal.await`, so runtime verification can wait on node appearance/disappearance and signal emission through structured bridge evidence instead of open-ended sleep loops.",
+          "**Run records keep waiter evidence and split rendered failures more honestly.** Runtime assertion results now persist waiter evidence and transcripts, inspect surfaces prefer the latest valid run record when local debris exists, and rendered verification feedback now separates screenshot-unavailable, provider/runtime incompatibility, and assertion-failure signals.",
+          "**Project-owned guidance surfaces now reinforce the shipped runtime vocabulary.** Managed guidance units now say `artifact_policy.screenshots: \"rendered\"` is canonical, keep legacy `\"fallback\"` only as a compatibility alias, and carry the bounded `player_reachable` / `internal_route` / `waiter` terminology used by the runtime and verification surfaces.",
+          "**Release safety checks are stricter for maintainers.** `corepack yarn release:preview --json` now refuses stale branch lineages, and required-release migration proof is part of the hard `check:public-release` gate instead of maintainer ceremony only."
+        ]
+      },
+      "updateContract": {
+        "summary": "Managed targets need a release-specific post-update path for v0.14.0 because guidance units move to version 3 and the runtime bridge surface moves to version 4. Bridge-enabled targets repair the managed bridge and finish plugin registration first, then `gdh migrate --apply` refreshes the guidance units and returns the target to a healthy lifecycle state.",
+        "steps": [
+          {
+            "id": "verify_post_update_status",
+            "kind": "mechanical",
+            "summary": "Run the standard post-update lifecycle check.",
+            "detail": "Start with `gdh status` so GDH can tell you whether the target only needs the guidance refresh branch or whether it also entered the bridge-specific repair branch for the v0.14.0 runtime bridge surface update.",
+            "commands": [
+              "gdh status"
+            ],
+            "validationCommands": [
+              "gdh status"
+            ]
+          },
+          {
+            "id": "inspect_bridge_specific_branch",
+            "kind": "agent_reasoning",
+            "summary": "Decide whether the target also needs the bridge-specific repair branch.",
+            "detail": "If `gdh status` surfaces `runtime_bridge_*` reasons, inspect `gdh bridge status` and treat that as the v0.14.0 bridge branch. If no runtime-bridge reasons appear, skip the bridge-specific steps and proceed straight to `gdh migrate --apply` for the guidance-unit refresh.",
+            "commands": [
+              "gdh bridge status"
+            ],
+            "validationCommands": [
+              "gdh status"
+            ]
+          },
+          {
+            "id": "repair_runtime_bridge_surface",
+            "kind": "mechanical",
+            "summary": "Repair the managed runtime bridge files when the bridge branch is active.",
+            "detail": "Bridge-enabled `v0.13.3` targets drift on the managed bridge files shipped in surface version 4. Run `gdh bridge repair` to rewrite the managed bridge files before attempting the final guidance refresh.",
+            "commands": [
+              "gdh bridge repair"
+            ],
+            "validationCommands": [
+              "gdh bridge status"
+            ]
+          },
+          {
+            "id": "enable_plugin_and_finish_gdhbridge_registration",
+            "kind": "manual_review",
+            "summary": "Enable the GDH Runtime Bridge plugin so GDHBridge registers again.",
+            "detail": "GDH still does not hand-edit `project.godot` for operators. After `gdh bridge repair`, open the project in the Godot editor and enable the `GDH Runtime Bridge` plugin so it can register `GDHBridge` and clear the remaining plugin/autoload reasons.",
+            "commands": [],
+            "validationCommands": [
+              "gdh bridge status",
+              "gdh status"
+            ]
+          },
+          {
+            "id": "refresh_guidance_units_and_validate",
+            "kind": "mechanical",
+            "summary": "Run migrate apply to refresh the guidance units and finish the release hop.",
+            "detail": "Once bridge follow-through is complete, or immediately when the target had no bridge-specific reasons, run `gdh migrate --apply`. This regenerates the managed guidance-unit surfaces at version 3 and should return the target to a healthy lifecycle state.",
+            "commands": [
+              "gdh migrate --apply"
+            ],
+            "validationCommands": [
+              "gdh status"
+            ]
+          }
+        ]
+      }
     }
   ]
 }

package/node_modules/@gdh/adapters/package.json

@@ -11,13 +11,13 @@
     }
   },
   "dependencies": {
-    "@gdh/authoring": "0.13.2",
-    "@gdh/core": "0.13.2",
-    "@gdh/docs": "0.13.2",
-    "@gdh/observability": "0.13.2",
-    "@gdh/runtime": "0.13.2",
-    "@gdh/scan": "0.13.2",
-    "@gdh/verify": "0.13.2"
+    "@gdh/authoring": "0.14.0",
+    "@gdh/core": "0.14.0",
+    "@gdh/docs": "0.14.0",
+    "@gdh/observability": "0.14.0",
+    "@gdh/runtime": "0.14.0",
+    "@gdh/scan": "0.14.0",
+    "@gdh/verify": "0.14.0"
   },
-  "version": "0.13.2"
+  "version": "0.14.0"
 }

package/node_modules/@gdh/authoring/package.json

@@ -14,7 +14,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@gdh/core": "0.13.2"
+    "@gdh/core": "0.14.0"
   },
-  "version": "0.13.2"
+  "version": "0.14.0"
 }

package/node_modules/@gdh/cli/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA2EA,OAAO,EAIL,2BAA2B,EAC5B,MAAM,oBAAoB,CAAC;AA4C5B,eAAO,MAAM,UAAU,wCAerB,CAAC;AAEH,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;CACpD;AAED,wBAAsB,MAAM,CAC1B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,GAAE,KAA0D,GAC7D,OAAO,CAAC,MAAM,CAAC,CA4HjB;AAED,wBAAgB,eAAe,CAC7B,EAAE,EAAE,KAAK,EACT,KAAK,EAAE,OAAO,EACd,OAAO,GAAE;IAAE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAAO,GACvD,IAAI,CAGN;AAw/ID,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAErD;AAyDD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAchG;AAED,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE;IACP,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7C,GACA,MAAM,GAAG,IAAI,CAcf;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE;IACP,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CACtC,GACA;IACD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B,CA4CA;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iCAAiC,CAC/C,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE;IACP,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,2BAA2B,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC5D,GACA;IACD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B,CAeA;AAuBD,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,UAAU,CAAC,OAAO,2BAA2B,CAAC,CAAC,CAAC,CAAC,GAAG;IACzD,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC,GACA,OAAO,CAAC,IAAI,CAAC,CAef;AAiFD,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,GACrC,SAAS,MAAM,EAAE,CAuBnB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA2EA,OAAO,EAIL,2BAA2B,EAC5B,MAAM,oBAAoB,CAAC;AA4C5B,eAAO,MAAM,UAAU,wCAerB,CAAC;AAEH,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;CACpD;AAED,wBAAsB,MAAM,CAC1B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,GAAE,KAA0D,GAC7D,OAAO,CAAC,MAAM,CAAC,CA4HjB;AAED,wBAAgB,eAAe,CAC7B,EAAE,EAAE,KAAK,EACT,KAAK,EAAE,OAAO,EACd,OAAO,GAAE;IAAE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAAO,GACvD,IAAI,CAGN;AA6/ID,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAErD;AAyDD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAchG;AAED,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE;IACP,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7C,GACA,MAAM,GAAG,IAAI,CAcf;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE;IACP,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CACtC,GACA;IACD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B,CA4CA;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iCAAiC,CAC/C,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE;IACP,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,2BAA2B,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC5D,GACA;IACD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B,CAeA;AAuBD,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,UAAU,CAAC,OAAO,2BAA2B,CAAC,CAAC,CAAC,CAAC,GAAG;IACzD,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC,GACA,OAAO,CAAC,IAAI,CAAC,CAef;AAiFD,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,GACrC,SAAS,MAAM,EAAE,CAuBnB"}

package/node_modules/@gdh/cli/dist/index.js

@@ -1431,7 +1431,7 @@ async function runRecipeCommand(args, io) {
         "Usage: gdh run-config list [target]",
         "Usage: gdh run-config show [target] <run-config-id>",
         "Usage: gdh run-config check [target] <run-config-id> [--provider <id>] [--param key=value] [--feature <id>] [--no-feature <id>] [--env NAME=value]",
-        "Usage: gdh run-config run [target] <run-config-id> [--provider <id>] [--param key=value] [--feature <id>] [--no-feature <id>] [--env NAME=value] [--live-workspace]",
+        "Usage: gdh run-config run [target] <run-config-id> [--provider <id>] [--param key=value] [--feature <id>] [--no-feature <id>] [--env NAME=value] [--live-workspace] [--rendered-screenshot]",
     ].join("\n") + "\n");
     return 1;
 }
@@ -1849,16 +1849,16 @@ async function runRecipeCheckCommand(args, io) {
 async function runRecipeRunCommand(args, io) {
     if (args.includes("--help")) {
         io.stdout.write([
-            "Usage: gdh run-config run [target] <run-config-id> [--provider <id>] [--param key=value] [--feature <id>] [--no-feature <id>] [--env NAME=value] [--live-workspace]",
+            "Usage: gdh run-config run [target] <run-config-id> [--provider <id>] [--param key=value] [--feature <id>] [--no-feature <id>] [--env NAME=value] [--live-workspace] [--rendered-screenshot]",
             "",
             "Run one run configuration and print structured process evidence as JSON.",
         ].join("\n") + "\n");
         return 0;
     }
     const unsupportedOptionsError = findUnsupportedOptionsError(args, {
-        usage: "Usage: gdh run-config run [target] <run-config-id> [--provider <id>] [--param key=value] [--feature <id>] [--no-feature <id>] [--env NAME=value] [--live-workspace]\n",
+        usage: "Usage: gdh run-config run [target] <run-config-id> [--provider <id>] [--param key=value] [--feature <id>] [--no-feature <id>] [--env NAME=value] [--live-workspace] [--rendered-screenshot]\n",
         optionsWithValues: ["--provider", "--param", "--feature", "--no-feature", "--env"],
-        booleanOptions: ["--live-workspace"],
+        booleanOptions: ["--live-workspace", "--rendered-screenshot"],
     });
     if (unsupportedOptionsError !== null) {
         io.stderr.write(unsupportedOptionsError);
@@ -1885,6 +1885,7 @@ async function runRecipeRunCommand(args, io) {
             disabledFeatures: collectOptionValues(args, "--no-feature"),
             environment: collectAssignmentOptionValues(args, "--env"),
             workspaceMode: args.includes("--live-workspace") ? "live_workspace" : "isolated_copy",
+            screenshotCapture: args.includes("--rendered-screenshot") ? "rendered" : "never",
         });
         await recordSessionEvent(effectiveTargetPath, {
             commandStartedAtMs,
@@ -2446,14 +2447,14 @@ async function runVerifyDoneCommand(args, io) {
 async function runVerifyRunCommand(args, io) {
     if (args.includes("--help")) {
         io.stdout.write([
-            "Usage: gdh verify run [target] <run-config-id> --verification-scenario <verification-scenario-id> [--provider <id>] [--param key=value] [--feature <id>] [--no-feature <id>] [--env NAME=value] [--live-workspace]",
+            "Usage: gdh verify run [target] <run-config-id> --verification-scenario <verification-scenario-id> [--provider <id>] [--param key=value] [--feature <id>] [--no-feature <id>] [--env NAME=value] [--live-workspace] [--rendered-screenshot]",
             "",
             "Execute one verification scenario over a selected run configuration and print the structured run record as JSON.",
         ].join("\n") + "\n");
         return 0;
     }
     const unsupportedOptionsError = findUnsupportedOptionsError(args, {
-        usage: "Usage: gdh verify run [target] <run-config-id> --verification-scenario <verification-scenario-id> [--provider <id>] [--param key=value] [--feature <id>] [--no-feature <id>] [--env NAME=value] [--live-workspace]\n",
+        usage: "Usage: gdh verify run [target] <run-config-id> --verification-scenario <verification-scenario-id> [--provider <id>] [--param key=value] [--feature <id>] [--no-feature <id>] [--env NAME=value] [--live-workspace] [--rendered-screenshot]\n",
         optionsWithValues: [
             "--verification-scenario",
             "--scenario",
@@ -2463,7 +2464,7 @@ async function runVerifyRunCommand(args, io) {
             "--no-feature",
             "--env",
         ],
-        booleanOptions: ["--live-workspace"],
+        booleanOptions: ["--live-workspace", "--rendered-screenshot"],
     });
     if (unsupportedOptionsError !== null) {
         io.stderr.write(unsupportedOptionsError);
@@ -2505,6 +2506,9 @@ async function runVerifyRunCommand(args, io) {
             disabledFeatures: collectOptionValues(args, "--no-feature"),
             environment: collectAssignmentOptionValues(args, "--env"),
             workspaceMode: args.includes("--live-workspace") ? "live_workspace" : "isolated_copy",
+            screenshotCapture: args.includes("--rendered-screenshot") || readSingleOptionValue(args, "--provider") === "docker"
+                ? "rendered"
+                : "never",
         });
         await recordSessionEvent(effectiveTargetPath, {
             commandStartedAtMs,