// turbo-all

Visual Review

Run a visual review of the Stack Contracts Visual Target using the MCP server.

[!CAUTION] You must NEVER run Playwright, xcodebuild, or browser tools directly. The MCP server handles all visual testing. You call it via curl.

You must NEVER access ux-sandbox/captures/ or any ux-sandbox files directly. All artifact data comes through the API responses — use content for text artifacts and downloadUrl for binary artifacts.

Target

The MCP server tests web UIs by URL. Your target is:

TARGET_URL_HERE

This repo has no dedicated GUI endpoint; specify the target URL in the startSmartRun message.

When to Use

• •After any code change that affects UI
• •When asked to do a "visual review" or "NRQA"
• •During VISUAL REVIEW mode in codex-collab
• •Before writing a walkthrough

Step 0: Health Check

curl -sf http://127.0.0.1:4040/health && echo "UP" || echo "DOWN"

If DOWN → tell the user: "MCP server is not responding. Check the com.antigravity.ux-visual-reviewer-mcp launchd service." Stop here.

Step 1: Register Token

TOKEN=$(curl -s -X POST http://127.0.0.1:4040/registerToken \
  -H 'Content-Type: application/json' \
  -d '{"tier":"standard","audience":"external","allowedEndpoints":["*"],"budgetRemaining":100,"rateLimitRpm":30}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['tokenId'])")
echo "TOKEN=$TOKEN"

Step 2: Start Smart Run

RESULT=$(curl -s -X POST http://127.0.0.1:4040/startSmartRun \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"message":"Full NRQA visual review of TARGET_URL_HERE"}')
RUNID=$(echo "$RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin)['runId'])")
echo "RUNID=$RUNID"

Step 3: Poll for Results

sleep 30
curl -s "http://127.0.0.1:4040/streamRunEvents?runId=$RUNID" \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool

Look for "status": "completed". If still running, wait and poll again.

Step 4: Get Artifacts

curl -s "http://127.0.0.1:4040/getArtifacts?runId=$RUNID" \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool

The response contains an artifacts array. Each artifact has:

• •type — assertion, console, screenshot, video, trace, har, a11y
• •content — inlined JSON/text for text-based artifacts (assertion, console, a11y). Read findings from here.
• •downloadUrl — HTTP URL for binary artifacts (screenshot, video, trace, har). Use curl to download if needed.
• •sizeBytes — file size

Do NOT use find, cat, or any filesystem commands to access artifacts. Everything you need is in the API response.

Step 5: Fix Cycle

1. •Read NRQA findings from the assertion artifact's content field
2. •Report all severities: P0=N, P1=N, P2=N, P3=N
3. •Fix every finding in your code
4. •Run npm test to ensure fixes don't break anything
5. •Commit fixes
6. •Re-run from Step 2 until all findings = 0

Ownership Rules

Artifact Retention

[!IMPORTANT] ux-sandbox purges captures after 48 hours. Download any screenshots or reports you need via downloadUrl and save them locally in your repo's evidence directory. Your repo must enforce its own 7-day retention policy for saved artifacts.

Cross-Repo Copy Block (ux-sandbox bugs only)

For Opus:

From Team: stack-contracts
To Team: ux-visual-reviewer

Action: BUG REPORT
File: [path in ux-sandbox]
Issue: [what's broken]
Expected: [what should happen]