docs: add dedicated Computer Use testing and video recordings page

[hongyi-chen]

Summary

Adds a dedicated Testing with Computer Use and video recordings page to the docs, expanding the brief "Recording sessions" section that was on the Computer Use capability page into a full feature doc.

New page (agent-platform/capabilities/computer-use-testing-and-recordings):

• 8 sections covering the full topic: overview, when to use it, how it works, where to find recordings, what's in a recording, example recordings (3 use cases), troubleshooting, and related links
• Troubleshooting failure modes sourced directly from the Warp client codebase (recording_controller.rs, recording_finalize.rs, computer_use/lib.rs) — no guesswork
• Uses the VARS system for Oz web app references; added to the sidebar after the main Computer Use entry

Updated computer-use.mdx:

• Replaces the full "Recording sessions" section with a short teaser + link to the new dedicated page
• Fixes PR-attachment wording from the original branch: removed "coming soon" / overclaiming language; replaced with accurate present-tense scoped wording ("can be attached to the PR description when the agent uses the PR-artifacts path")

Pending assets

Two of the three example recordings do not yet have real, public-safe video assets:

• UI change evidence: the staging run link (https://staging.warp.dev/conversation/ec11ab36-da70-4c7b-b14a-fd5f40b126cc) requires Warp access to view. A public-facing video embed is pending.
• End-to-end QA of an existing flow: described in prose with a concrete prompt; no video asset yet.

The third example (bug reproduction — warpdotdev/warp#13480) links to the public GitHub issue, which is the reproduction artifact itself.

Both pending assets are called out with :::note callouts in the page pointing to this PR for status.

Verification

Testing category: pure data/copy change — no regression test applicable. Named exemption: the change is documentation only with no behavior logic.

Checks run:

• npm run build — 349 pages built, no new errors
• Style lint (python3 .agents/skills/style_lint/style_lint.py --all) — no issues on the new or changed files
• Broken links (python3 .agents/skills/check_for_broken_links/check_links.py --internal-only) — ✓ No broken links found

Originating thread: https://warpdev.slack.com/archives/C0BDQDW8V5E/p1785172487237929

Conversation: https://staging.warp.dev/conversation/17f0e977-9bbe-4b67-9305-3fef27bb2858
Run: https://oz.staging.warp.dev/runs/019fa536-bf65-7d83-9a2d-d0862314c139

This PR was generated with Oz.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Jul 28, 2026 4:24pm

[oz-for-oss]

@hongyi-chen

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[oz-for-oss]

Overview

This PR adds a focused Recording sessions section to the Computer Use capability page, documenting screenshots, video recording, run outputs, and sandbox-local capture boundaries. I found no blocking docs, security, link, structure, or spec-alignment issues; spec_context.md reports no approved repository spec context for this PR.

Concerns

• No blocking concerns.

Verdict

Found: 0 critical, 0 important, 1 suggestion

Approve with nits

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[warp-dev-github-integration]

Overview

Adds a dedicated Testing with Computer Use and video recordings page, trims the Recording sessions section on computer-use.mdx to a teaser that links out, and wires the new page into the sidebar. The structure matches the approved outline, the PR-attachment wording is accurate and correctly scoped, and the troubleshooting section's failure modes all trace to real error strings in the client. Two areas need work before merge: the recording-feature descriptions are stated as unconditional when they are Linux-only, and the example section ships reader-facing links that point at internal/authoring surfaces.

Concerns

Platform scope of the recording features is missing and makes the page factually wrong on macOS. What's in a recording presents the smart cut, action overlays, and click ripples/drag trails as properties of every recording. In the client they are produced only by the Linux post-processing pass: post_process_recording in crates/computer_use/src/lib.rs is gated on #[cfg(all(linux, not(noop)))] and returns the input unchanged on every other platform, and crates/computer_use/src/overlay.rs notes that .ass generation is only built where the burn-in re-encode runs. macOS captures through avfoundation with a uniform -vf setpts speedup (4× by default), so a macOS recording has no smart cut, no overlay pills, no pointer annotations, and is emphatically not "played back at normal speed". The ticket's acceptance criteria called for this Linux-richer caveat explicitly. Flagged inline with a suggested platform-support bullet.

Reader-facing links point at internal surfaces. The published page links to a staging.warp.dev conversation URL and, in two :::note callouts, tells readers to check GitHub PR #374 for the status of a pending asset. Neither is usable by a docs reader, and a shipped page should not reference its own authoring PR. Either omit the example subsections until real public-safe assets exist, or keep the prose and drop the staging link and the PR-status notes. Flagged inline.

Troubleshooting omits two real causes. The section covers environment, start, no-committed-actions, sync, upload, encoder-crash, and limit/cancellation cases accurately, but not the two remaining ways a recording never happens: the VideoRecording feature flag being disabled (checked in should_autoexecute for both start_recording.rs and stop_recording.rs), and the platform having no real recorder at all — create_recorder in crates/computer_use/src/lib.rs returns a no-op recorder that reports recording as unsupported on everything except Linux X11 and macOS. Worth one short bullet each so a user on an unsupported platform is not left retrying.

Em dashes in procedural text. AGENTS.md asks that em dashes not be used in procedural or instructional text; the How it works numbered steps and several troubleshooting bullets use them. Non-blocking, but worth a pass while making the other edits.

Verdict

Found: 1 critical, 3 important, 3 suggestions

Prior concerns still outstanding: none — the earlier phrasing suggestion no longer applies to the current diff.

Request changes

Review run

https://oz.staging.warp.dev/runs/019fa54e-5583-78da-9547-fd6e58bb6109

[warp-dev-github-integration]

Overview

Re-review of head 7ee0590 against my prior pass. All four blocking findings are genuinely fixed, not just claimed: the Platform support bullet now scopes the smart cut, overlays, and pointer annotations to the Linux post-processing pass and correctly describes the macOS 4x uniform speedup, matching post_process_recording's cfg gate and the mac/recording.rs setpts filter; the staging conversation link and all three :::note callouts pointing at PR #374 are gone; the internal-voice sentence is rewritten; the tracking claim is scoped to successful interactive calls; and the two missing troubleshooting causes (feature flag not enabled, platform not supported) are both accurate against create_recorder and the VideoRecording flag checks. Gates re-verified independently on this head: CI 8/8 green, npm run build clean at 349 pages, style lint clean on the changed files, 0 broken links across 3168 internal links.

Concerns

One residual scoping gap, non-blocking. Step 4 of How it works still describes the idle cut and overlay burn-in as unconditional, two sections before the Platform support bullet qualifies them. A reader who only skims the numbered steps still comes away expecting annotations on macOS. Suggested a one-line fix inline; it does not block merge.

The two "example video is pending" sentences are reader-facing filler. They are a large improvement over the PR links, but they still tell a docs reader about an asset that doesn't exist rather than telling them something useful. Consider dropping both sentences and letting the prose plus example prompt stand on their own until a real clip lands.

Verdict

Found: 0 critical, 0 important, 2 suggestions

Prior concerns: none remain — all four blocking findings from the previous pass are resolved.

Approve with nits

Review run

https://oz.staging.warp.dev/runs/019fa54e-5583-78da-9547-fd6e58bb6109

[vkodithala]

This mostly LGTM, few things we should address though!

[warp-dev-github-integration]

Overview

Re-review at head daa3850. The human review's direction was followed well: the invocation paragraph is in, internal tool-call names are gone from every section, the Cloud-mode wording and the two link targets are corrected (/platform/oz-web-app/#runs resolves to a real ## Runs heading), the example prompt is rewritten, and the troubleshooting section is cut back hard. I independently confirmed the new limit figures against warp-server: config/base.yaml sets computer_use_recording.max_duration: 10m and max_size_bytes: 1073741824, so 10 minutes / 1 GiB are correct, with no environment override. I also confirmed the deletions left nothing dangling — no references anywhere in src/ to the removed subsections, no orphaned anchors, and 0 broken links across the site. I treat the two reversals of my earlier findings (PR-attachment scoping, the Linux/macOS caveat) as settled and am not relitigating either. One blocking issue remains, and it is a single sentence.

Concerns

The teaser in computer-use.mdx still carries the attachment wording the human reversed. The new page now states that attachment is automatic once the recording artifact is associated with the run, but the Recording sessions teaser on computer-use.mdx still says recordings "can be attached to a pull request description when the agent uses the PR-artifacts path" — the exact framing the human called out as incorrect. Both files ship in this PR, so as it stands the two pages contradict each other on the same question and one of them repeats the disavowed claim. This is blocking only because it publishes information the reviewer already identified as wrong; the fix is one sentence, suggested inline.

Non-blocking, carried forward: the two "A public-facing example video for this use case is pending." sentences are unchanged from the previous head. Given the reviewer indicated they will post the recording directly, this may well be intentional — flagging only so the decision is deliberate.

Verdict

Found: 0 critical, 1 important, 1 suggestion

Prior concerns: resolved or superseded. The two findings the human overruled are closed and not re-raised; my earlier How it works scoping suggestion is moot now that the platform caveat is gone.

Request changes

Review run

https://oz.staging.warp.dev/runs/019fa54e-5583-78da-9547-fd6e58bb6109

[warp-dev-github-integration]

Overview

Final pass at head 644216a, scoped to the two-item delta over daa3850. Both are correctly applied. The computer-use.mdx teaser now reads "are attached to the pull request description when a cloud agent run produces them", which matches the new page's statement that attachment is automatic once the recording artifact is associated with the run — the two pages no longer contradict each other and the disavowed wording is gone from the PR entirely. The Recording failed to start subsection was removed cleanly: no dangling anchor, no in-page or cross-page reference to it anywhere in src/, no sidebar impact, code fences still balanced, and Retry guidance still covers the failure path end to end ("if a recording fails or produces an unexpected result" → check the error, retry, file an issue if it repeats), so the intro's promise to explain "how to handle common recording failures" is still met. Regression sweep is clean: build 349 pages, style lint clean on the changed files, 0 broken links across the site, and CI green. No new findings.

Verdict

Found: 0 critical, 0 important, 0 suggestions

Prior concerns: none remain. Both findings from the previous pass are resolved, and the matters settled by the human reviewer are left closed.

Approve

Review run

https://oz.staging.warp.dev/runs/019fa54e-5583-78da-9547-fd6e58bb6109

[hongyi-chen]

@vkodithala do you have a sample recording handy that we could show as a demo here? or better yet, do you have a public loom demo that we could share?

[hongyi-chen]

otherwise i think this PR is good for you to take a final pass

[vkodithala]

Yeah, generally the copy here lgtm after the agent's second pass. Working on adding video embeds for the three examples under "Example recordings", and then I'll push these docs up. Also working on a Loom that'll be top-level in this page.

[warp-dev-github-integration]

Overview

Re-review at head 5d759c3, focused on independently verifying that every change @vkodithala requested is actually reflected in the current file content rather than just marked resolved. Eleven of his twelve inline requests check out against the shipped text; one is only partially applied and publishes a link whose label names a different, already-documented feature. Gates re-verified on this head: CI 8/8 green, npm run build clean, 0 broken links across 3179 internal links, style lint clean on the lines this PR touches (the three style-lint hits in computer-use.mdx are on pre-existing lines 28/65/69, untouched here). I also loaded the Vercel preview and walked the rendered page: sidebar entry lands directly under "Computer use", {VARS.WEB_APP} resolves to "Oz web app" with no raw tokens, and /platform/oz-web-app/#runs jumps to a real "Runs" heading.

Concerns

The "In Warp" link labels the session-sharing page with a different feature's name (blocking). The sentence links the anchor text "cloud-synced conversation" to /platform/viewing-cloud-agent-runs/, whose title is "Cloud agent session sharing". "Cloud-synced conversations" is a separate, distinctly documented feature at /agent-platform/local-agents/cloud-conversations/ — the privacy setting that stores conversations in the cloud — and every one of the eight other places in src/content/docs/ that uses that phrase links there. I confirmed on the preview deploy that clicking this link lands the reader on a page titled "Cloud agent session sharing". This is the tail of your comment asking us to "call this whatever we do in other areas of the docs": the destination is right (it's the page you pointed at), but the label borrows a term the docs already reserve for something else, so it reads as a factual error to anyone who knows both features. One-line fix suggested inline.

The PR description no longer matches what ships (blocking, description-only). Two statements in the body are stale in a way that actively misleads a reviewer who reads it instead of the diff. It still advertises the PR-attachment wording as "can be attached to the PR description when the agent uses the PR-artifacts path" — the exact framing you flagged as incorrect, which was removed from both files in rework 3. And "Pending assets" claims both pending examples "are called out with :::note callouts in the page pointing to this PR for status"; those callouts were deleted at your request and the page now carries two plain sentences instead. Please rewrite the description to describe the PR's current net effect.

Carried forward, non-blocking: the two "A public-facing example video for this use case is pending." sentences are unchanged. That was deliberate given you said you'd post the recording directly, and @hongyi-chen's open thread is now asking the same question — leaving that thread open for the two of you to settle rather than re-raising it as a finding.

Verdict

Found: 0 critical, 2 important, 0 suggestions

Prior concerns still outstanding: the "Terminal view" / Cloud-mode terminology request is only partially applied; all other prior findings from every earlier pass are resolved on this head and are not re-raised.

Request changes

Review run

https://oz.staging.warp.dev/runs/019fa651-3787-701a-a1ca-ff1ec2415a46

[warp-dev-github-integration]

Overview

Re-review at head 02c10cbd. The new commit replaces both "example video is pending" placeholders with three real, self-hosted demo clips, adds a Loom walkthrough, sharpens all three example prompts, and strips the em dashes from the bullets and Related list. I checked the rendered preview: all three DemoVideo clips load, play, and loop, showing the Warp tab-group setting, the Oz web app New run flow, and the #13480 Ctrl+C repro respectively; posters follow the component's <basename>.poster.jpg convention and resolve. Gates re-verified on this head: CI 8/8 green, npm run build clean, 0 broken links across 3179 internal links. My prior CHANGES_REQUESTED was pinning reviewDecision on a stale head; this approval supersedes it. Nothing here blocks merge.

Concerns

Carried forward, now non-blocking: the "In Warp" link text. The anchor still reads "cloud-synced conversation" while resolving to /platform/viewing-cloud-agent-runs/ ("Cloud agent session sharing"). I am not re-blocking on it — @vkodithala resolved that thread and approved this head, which I take as a deliberate call on his own original comment. Restating it only so the decision is on the record; the one-line fix from the previous pass still applies if you want it.

The PR description is now contradicted by this commit. "Pending assets" still says two of the three examples have no video asset and that both are flagged with :::note callouts pointing at this PR — three videos just landed and those callouts are long gone. It also still quotes the disavowed "PR-artifacts path" wording as what shipped. Worth a quick rewrite before merge, since on a squash this body becomes the commit message.

One new lint hit worth a one-word fix. Line 85 hardcodes "Oz web app" in prose; the page already imports VARS and uses {VARS.WEB_APP} at line 49, so this is just an inconsistency. Suggested inline. For the record, the other two hits style_lint --changed reports on this file are false positives: line 89 is inside a ```text code fence where MDX expressions do not evaluate and the prompt is meant to be literal, and line 94 is a JSX string attribute.

Unverified, likely environmental. The Loom walkthrough embed rendered as a blank box in my headless browser while the three MP4s played fine. The embed uses the same VideoEmbed pattern as four Looms already shipped on docs.warp.dev and the share URL returns 200, so this is almost certainly a headless-Chromium limitation rather than a real defect. Worth a five-second eyeball on the preview before you merge.

Verdict

Found: 0 critical, 0 important, 3 suggestions

Prior concerns: the link-text finding is unresolved in the text but explicitly overridden by the human reviewer, and the stale-description finding stands as a non-blocking pre-merge cleanup. Neither blocks acceptance.

Approve with nits

Review run

https://oz.staging.warp.dev/runs/019fa651-3787-701a-a1ca-ff1ec2415a46

[warp-dev-github-integration]

💡 [SUGGESTION] Hardcoded product name in prose — the page already imports VARS and uses {VARS.WEB_APP} at line 49, so this one reads inconsistently and would be missed by a future rename.

Suggested change

	An agent walks through a critical user journey, such as the "New run" creation flow in the Oz web app, capturing the complete interaction.
	An agent walks through a critical user journey, such as the "New run" creation flow in the {VARS.WEB_APP}, capturing the complete interaction.