{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "foundations-browser-proof-field-guide",
  "slug": "browser-proof-field-guide",
  "title": "Browser Proof Field Guide",
  "summary": "Make Codex prove rendered web behavior with routes, actions, logs, screenshots, and receipts.",
  "category": "Verification",
  "tags": [
    "field guide",
    "browser proof"
  ],
  "sources": [
    {
      "label": "Agent foundations: Explore software through perspectives and runtime QA (authorized access required)",
      "url": "https://codex-workshop-followup.pages.dev/lesson-05.html"
    },
    {
      "label": "Agent foundations: Verify fixes with deterministic evidence and narrow boundaries (authorized access required)",
      "url": "https://codex-workshop-followup.pages.dev/lesson-08.html"
    },
    {
      "label": "Agent foundations: Preserve contracts and state machines while code changes (authorized access required)",
      "url": "https://codex-workshop-followup.pages.dev/lesson-11.html"
    }
  ],
  "sourceUnits": [
    "field-guides/guides.mjs#browser-proof/overview",
    "field-guides/guides.mjs#browser-proof/quote",
    "field-guides/guides.mjs#browser-proof/decision",
    "field-guides/guides.mjs#browser-proof/agentPrompt",
    "field-guides/guides.mjs#browser-proof/stories",
    "field-guides/guides.mjs#browser-proof/tips",
    "field-guides/guides.mjs#browser-proof/refs"
  ],
  "collection": "foundations",
  "categoryId": "verification",
  "wordCount": 505,
  "url": "/topics/foundations-browser-proof-field-guide/",
  "markdownUrl": "/markdown/foundations-browser-proof-field-guide.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/foundations-browser-proof-field-guide.json",
  "headings": [
    {
      "id": "choose-the-right-mechanism",
      "text": "Choose the right mechanism",
      "level": 2
    },
    {
      "id": "agent-ready-prompt",
      "text": "Agent-ready prompt",
      "level": 2
    },
    {
      "id": "applied-stories",
      "text": "Applied stories",
      "level": 2
    },
    {
      "id": "authenticated-billing-route",
      "text": "Authenticated billing route",
      "level": 3
    },
    {
      "id": "pricing-weird-path-qa",
      "text": "Pricing weird-path QA",
      "level": 3
    },
    {
      "id": "preview-deployment-triage",
      "text": "Preview deployment triage",
      "level": 3
    },
    {
      "id": "tips-and-gotchas",
      "text": "Tips and gotchas",
      "level": 2
    },
    {
      "id": "references",
      "text": "References",
      "level": 2
    },
    {
      "id": "related-principles",
      "text": "Related principles",
      "level": 2
    }
  ],
  "markdown": "# Browser Proof Field Guide\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nMake Codex prove rendered web behavior with routes, actions, logs, screenshots, and receipts.\n\nUse this when a UI, auth, form, route, or responsive change cannot be considered done from source inspection alone.\n\n> Browser automation CLI designed for AI agents.\n\n[agent-browser docs](https://agent-browser.dev/)\n\n## Choose the right mechanism\n\n| Mechanism | Use when | Agent responsibility | Artifact |\n|---|---|---|---|\n| Codex Browser | Local/public unauthenticated route | Fast visual proof and screenshots | .notes/browser-proof/<task>/browser-proof.md |\n| Chrome extension/manual Chrome | Signed-in browser state | Auth flows and internal SaaS pages | Redacted manual proof plus screenshot |\n| agent-browser | Terminal-friendly browser control | snapshot, click, fill, screenshot | snapshot.txt plus screenshot.png |\n| Playwright | Repeatable or CI-friendly flow | Trace, console, screenshot, deterministic test | trace.zip plus console.json |\n| DevTools/CDP | Raw console/network evidence | HAR, console objects, performance details | console.log plus network.har |\n\n## Agent-ready prompt\n\n```text\nUse browser proof before claiming this UI task is done.\nInspect package.json and AGENTS.md first.\nPick the browser surface that matches the auth and repeatability needs.\nSave .notes/browser-proof/<task>/browser-proof.md with URL, viewport, auth context, actions, expected/observed result, console errors, network failures, artifacts, command output, diff summary, and pass/fail.\nRedact cookies, tokens, customer data, QR codes, and auth headers.\n```\n\n## Applied stories\n\n### Authenticated billing route\n\n**Role:** SaaS frontend engineer\n\nCodex changed /settings/billing, but the route only works when logged in.\n\n**Agent brief:** Use signed-in Chrome or a seeded login; verify current plan, change plan, submit, and capture final visible success state.\n\n**Done when:**\n\n- browser-proof.md\n- screenshot\n- console/network summary\n- typecheck/test log\n\n### Pricing weird-path QA\n\n**Role:** Growth engineer\n\nPlan toggles, coupons, and checkout modals fail after repeated back/refresh/toggle sequences.\n\n**Agent brief:** Run five browser QA perspectives and collate reproducible findings into .notes/qa/pricing-summary.md.\n\n**Done when:**\n\n- perspective files\n- summary severity list\n- screenshots/transcripts\n- console status\n\n### Preview deployment triage\n\n**Role:** Frontend lead\n\nA PR preview is green but nobody opened changed routes.\n\n**Agent brief:** Discover preview URL, open homepage and changed route, capture status, visible error text, console errors, and screenshot.\n\n**Done when:**\n\n- preview URL\n- browser receipt\n- blocker/warning/clean verdict\n- no source edits\n\n## Tips and gotchas\n\n- Tests prove code paths; browser proof proves user-visible behavior.\n- Use the in-app browser for localhost/public pages, but use Chrome/manual auth for signed-in state.\n- Do not make Playwright mandatory for every UI task; use it when repeatability matters.\n- Treat screenshots, traces, HARs, and console logs as sensitive local artifacts by default.\n- A Stop hook should check receipt files, not drive the browser itself.\n\n## References\n\n- [Codex in-app browser](https://developers.openai.com/codex/app/browser)\n- [Codex Chrome extension](https://developers.openai.com/codex/app/chrome-extension)\n- [agent-browser](https://github.com/vercel-labs/agent-browser)\n- [Playwright screenshots](https://playwright.dev/docs/screenshots)\n- [Playwright Trace Viewer](https://playwright.dev/docs/trace-viewer)\n- [Chrome DevTools Console](https://developer.chrome.com/docs/devtools/console/log)\n\n## Related principles\n\n- [Explore software through perspectives and runtime QA](/topics/foundations-perspective-qa-and-testing/)\n- [Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/)\n- [Preserve contracts and state machines while code changes](/topics/foundations-contracts-state-machines-and-code/)"
}
