docs: stop validate_ui_refs flagging JSX props and code fences as Command Palette commands

[rachaelrenk]

Summary

The validate_ui_refs Command Palette check reported 12 findings on main. Half were extractor false positives rather than documentation errors, which makes the check noisy and easy to start ignoring.

This fixes the false positives. It does not touch any documentation content.

The problem

extract_command_palette_refs() captured any quoted string on a line near a "Command Palette" mention, regardless of the surrounding syntax. Two categories leaked through.

Component props and CSS values. Quoted strings inside JSX tags were treated as command names:

<DemoVideo src="/assets/terminal/block-divider-demo.mp4" label="Block Divider Demo" />
<VideoEmbed url="https://..." title="Command Palette Demo" />
<figure style={{ maxWidth: "375px" }}>

That produced findings for Block Divider Demo, Tab Indicator Demo, Logout Demo, Command Palette Demo, and 375px.

Fenced code blocks. Prompt examples were scanned as if they were live UI references. In agents/capabilities/computer-use/testing-and-recordings.mdx, a prompt describing the Oz web app's "New run" creation flow was reported as a missing Warp Command Palette command — a different product's UI, quoted inside a fenced text block.

Changes

.agents/skills/validate_ui_refs/validate_ui_refs.py

• Skip quoted strings that fall inside an HTML/JSX tag span. The check matches the tag span rather than sniffing for a word= prefix, so legitimate prose such as Palette: "Open theme picker" is not suppressed.
• Skip fenced code blocks during Command Palette extraction. This follows the precedent already set by the missing_docs skill's strip_code_spans() helper, which exists so CLI examples don't trigger prose-oriented findings.
• Extend --self-test with a fifth case asserting both filters drop the bogus captures while genuine prose references are still detected. This runs in CI, so the behavior is locked in.

Result

Command Palette findings drop from 12 to 6, with no documentation changes.

What is deliberately not fixed

The remaining 6 findings are a different problem and are left alone on purpose:

Exit Vim Insert Mode (×2), Toggle Mouse Reporting, Warpify SSH Session, Share pane, and Share session.

These appear to be real commands, and the docs are correct — keyboard-shortcuts.mdx documents Toggle Mouse Reporting with the action workspace:toggle_mouse_reporting. I confirmed none of them exist in the snapshot's 164 extracted commands. The cause is that _extract_command_palette_commands() reads only two Rust source files:

source_files = [
    warp_repo / "app" / "src" / "terminal" / "view" / "init.rs",
    warp_repo / "app" / "src" / "workspace" / "mod.rs",
]

Commands registered anywhere else are invisible to it. Here the tool is wrong and the docs are right, so "fixing" these would mean corrupting correct documentation. Broadening the extractor changes the snapshot and needs verification against a real warp checkout, which makes it a separate change with its own risk profile.

Worth noting that command findings are never auto-fixed — only path and format issues have a fix_type — so --fix was never at risk of editing these pages.

Notes for reviewers

--all also reports one Settings path finding on main, in reference.mdx:55 (Settings > Platform should now be Settings > Cloud platform > Oz Cloud API Keys). I verified it is pre-existing by re-running the check against pristine main; it is unrelated to this change and left out to keep this PR to tooling only.

Verification

• --self-test passes, including the new case.
• Command Palette findings: 12 before, 6 after.
• Settings path and format findings are unchanged.
• No files under src/content/docs/ are modified.

Co-Authored-By: Oz oz-agent@warp.dev

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 4, 2026 9:23pm

[oz-for-oss]

@rachaelrenk

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 tightens the validate_ui_refs Command Palette extractor so quoted JSX/HTML attribute values and fenced code examples are ignored, and extends the self-test coverage for those false-positive cases.

Concerns

• No blocking correctness, security, or spec-alignment concerns found in the changed lines.

Verdict

Found: 0 critical, 0 important, 0 suggestions

Approve

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

Powered by Oz