docs(readme): document run-capsule shareable run videos

[drewstone]

Documents how a bad run becomes a shareable, reasoning-captioned video.

A run's report.json is already a complete trace — per-turn screenshot, action, and reasoning — so it renders directly into screen.mp4 / replay.mp4 via run-capsule, no extra capture step and no bad-side code change. The new "Shareable run videos" subsection (under Session Viewer) gives the one-liner, the screenshot/vision-on requirement, and the dependency on the suite-aware adapter (tangle-network/run-capsule#4).

Verified end-to-end against real reports: a 24-turn Variant run renders real product frames each captioned with the agent's 💭 reasoning + action + URL.

Docs-only; no changeset.

[tangletools]

✅ Auto-approved PR — c2192d57

Blanket team auto-approval is enabled for this reviewer service.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: blanket_auto_approve · 2026-06-21T14:34:55Z}

[tangletools]

🟢 Value Audit — sound

Verdict	sound
Concerns	0 (none)
Heuristic	0.0s
Duplication	0.0s
Interrogation	149.4s (2 bridge agents)
Total	149.4s

💰 Value — sound

Adds README docs showing how to render a bad run's report.json into captioned shareable MP4s via the external run-capsule CLI; accurate, fits the existing Session Viewer section, and leverages the suite-shaped report schema without bad-side code changes.

• What it does: Appends a 'Shareable run videos' subsection to the README's Session Viewer section (README.md:510) documenting the one-liner npx run-capsule --playwright agent-results/report.json --no-upload, which turns a completed run's per-turn screenshots, actions, and reasoning into screen.mp4 and replay.mp4.
• Goals it achieves: Makes users aware that bad's existing report.json trace can be reused (no extra capture step) to produce reasoning-captioned demo/replay videos for sharing, and clarifies the prerequisites: vision-on screenshots and a suite-aware run-capsule adapter.
• Assessment: Good. The docs are accurate — report.json carries TestSuiteResult with per-test screenshots (src/types/test-runner.ts:108) and AgentResult.turns containing action/reasoning per turn (src/types/turn.ts:8, src/types/result.ts:7). The section fits naturally under the existing Session Viewer heading and correctly distinguishes run-capsule's captioned MP4 output from the native --show-cursor recordin
• Better / existing approach: none for the video-generation goal. The codebase has native bad share for web share links (src/cli-share.ts:2) and --show-cursor for raw browser recordings, but neither produces a captioned MP4 from report.json; an external tool is the right lightweight approach. Note the README's CLI Reference (README.md:298) already omits bad share and bad preview, a pre-existing docs gap unrelated to th
• Model: opencode/kimi-for-coding/k2p7
• Bridge attempts: 1

🎯 Usefulness — sound

Docs-only README subsection accurately documents an already-existing capability (report.json's per-turn screenshot+action+reasoning trace) and points at a complementary external video renderer without competing with in-repo tooling.

• Integration: N/A in the code sense — this is a README-only change with no new surface in the repo. The capability it documents already exists: report.json is written as a suite artifact (src/test-runner.ts:626), is suite-shaped TestSuiteResult (src/types/test-runner.ts:126), and the default sink path in the docs (agent-results/report.json) matches src/config.ts:203 and src/cli/commands/run.ts:190. Reachability
• Fit with existing patterns: Fits the grain. The new subsection lives directly under the existing 'Session Viewer' / bad view block (README:507-509) and is explicitly framed as complementary — bad view for interactive drill-down, --show-cursor for an in-run recording.webm, and run-capsule for a captioned shareable video. No competing in-repo video renderer exists (grep for run-capsule returns only the new README lines).
• Real-world viability: Docs accuracy holds under the conditions the README itself states. Verified: screenshots are captured per-turn only when vision is on, which defaults ON (src/config.ts:182; src/cli-ui.ts:470-471), so the 'screen capsule shows real frames only when the run captured screenshots' caveat is correct. The suite-shape caveat is also real and honestly flagged: the doc explicitly notes older run-capsule ve
• Model: opencode/zai-coding-plan/glm-5.2
• Bridge attempts: 1

No concerns — sound change, no better or existing approach found. ✅

---

What this audit checks

It judges the change on its merits — not whether it was tasked out in an issue. Unticketed, fast-moving work is fine; the question is whether the change is good and whether a better or existing approach should be used instead.

Pass	What it asks
Heuristic	Vague title? Whitespace-only or cruft-bearing diff? (content signals only)
Duplication	Do added function/class names already exist elsewhere in the repo?
Value Audit	What does it do? What goal does it achieve? Is it good? Better architecture or already-exists?
Usefulness Audit	Does it integrate and fit? Will it hold up in real use and actually get used?

Findings are concerns, not blocks — the human reviewer decides what to do with them.

_{value-audit · 20260621T144313Z}

[tangletools]

✅ No Blockers — c2192d57

Readiness 92/100 · Confidence 65/100 · 2 findings (2 low)

	deepseek	glm	aggregate
Readiness	92	92	92
Confidence	65	65	65
Correctness	92	92	92
Security	92	92	92
Testing	92	92	92
Architecture	92	92	92

Full multi-shot audit completed 1/1 planned shots over 1 changed files. Global verifier still owns final merge decision. | Full multi-shot audit completed 1/1 planned shots over 1 changed files. Global verifier still owns final merge decision.

🟡 LOW Documents feature backed by unmerged external PR — README.md

Line 520: 'Needs a run-capsule whose Playwright adapter understands this driver's suite-shaped report.json' — the linked PR (tangle-network/run-capsule#4) appears unmerged. Users installing a released run-capsule will get an empty capsule for suite-shaped reports. The caveat is present but easy to miss; consider adding 'until run-capsule#4 merges' for clarity, or waiting to merge this section until the dependency lands.

🟡 LOW Wrong report.json path in run-capsule command example — README.md

README.md:515 shows npx run-capsule --playwright agent-results/report.json --no-upload, but report.json is written at {baseDir}/suite/report.json, not {baseDir}/report.json. Evidence chain: src/test-runner.ts:625 writes report.json with testId: 'suite'; src/artifacts/filesystem-sink.ts:75 writes to path.join(this.baseDir, artifact.testId); src/cli/commands/run.ts:190 sets default baseDir to ./agent-results. So the real path is agent-results/suite/report.json. Impact: anyone copy-pasting the headline command of this new section gets a file-not-found error on first try. Fix: change agent-results/report.json to agent-results/suite/report.json on line 515.

---

_{tangletools · 2026-06-21T14:46:52Z · trace}