docs(ai): clarify browser session choice for verification

Author: tomcasaburi

.codex/agents/browser-check.toml

@@ -4,6 +4,8 @@ sandbox_mode = "read-only"
 developer_instructions = """
 Verify only the route, user flow, and acceptance criteria the parent agent gives you.
 Use playwright-cli against the already-running local app at http://5chan.localhost:1355 unless the parent agent gives a different URL. Never start, restart, or stop the dev server.
+Default to a fresh isolated playwright-cli browser session. If verification depends on auth, cookies, extensions, open tabs, or other existing browser state and the parent agent did not specify session mode, stop and ask whether to use a fresh browser or the contributor's current browser session.
+Never attach to a live personal browser session without explicit permission. If current-session reuse is requested, use the supported attach path only when available; otherwise report the limitation instead of silently switching modes.
 Check desktop and mobile viewport when the request touches layout, responsiveness, or touch interactions.
 Return concrete PASS/FAIL findings with the route, actions taken, and evidence observed. Do not modify application code or expand the audit beyond the requested flow.
 """

.codex/skills/playwright-cli/SKILL.md

@@ -23,6 +23,34 @@ playwright-cli screenshot
 playwright-cli close
 ```
 
+## Session mode selection
+
+Default to a fresh isolated browser session for reproducible verification.
+
+Before browser work where existing state may matter, explicitly confirm the mode if the user has not already said which one they want:
+
+1. Fresh isolated `playwright-cli` session
+2. Current browser session reuse
+
+Existing state usually matters when the task depends on auth, cookies, extensions, open tabs, or reproducing something already happening in the contributor's browser.
+
+Do not attach to a live personal browser session without explicit approval.
+
+If current-session reuse is requested, prefer the supported attach path in the local setup:
+
+```bash
+# Fresh isolated browser (default)
+playwright-cli -s=verify open https://example.com
+
+# Reusable Playwright-managed profile
+playwright-cli -s=verify open https://example.com --persistent
+
+# Attach to an existing browser when the local extension bridge is set up
+playwright-cli open --extension
+```
+
+If the task requires the contributor's current browser session and the attach path is not available in the current setup, stop and ask whether to switch to a fresh session or provide an explicit CDP-based Playwright script.
+
 ## Commands
 
 ### Core

.cursor/agents/browser-check.md

@@ -23,6 +23,8 @@ Use the already-running Portless dev server at `http://5chan.localhost:1355` unl
 
 Do not start, restart, or stop the dev server yourself. If the app is unreachable, report the failure and stop.
 
+Default to a fresh isolated `playwright-cli` browser session. If the requested verification depends on auth, cookies, extensions, open tabs, or other existing browser state and the parent agent did not specify session mode, stop and ask whether to use a fresh browser or the contributor's current browser session.
+
 ### Step 2: Navigate and Snapshot
 
 Use playwright-cli to check the relevant page:
@@ -74,4 +76,6 @@ playwright-cli snapshot
 - Only check what the parent agent asked you to verify — don't audit the entire app
 - If playwright-cli is not installed, report it immediately and stop
 - If the dev server is unreachable, report the error and stop
+- Never attach to a live personal browser session without explicit permission
+- If current-session reuse is requested, use the supported attach path only when available; otherwise report the limitation instead of silently switching to a fresh session
 - Don't modify any code — you are read-only, verification only

.cursor/skills/playwright-cli/SKILL.md

@@ -23,6 +23,34 @@ playwright-cli screenshot
 playwright-cli close
 ```
 
+## Session mode selection
+
+Default to a fresh isolated browser session for reproducible verification.
+
+Before browser work where existing state may matter, explicitly confirm the mode if the user has not already said which one they want:
+
+1. Fresh isolated `playwright-cli` session
+2. Current browser session reuse
+
+Existing state usually matters when the task depends on auth, cookies, extensions, open tabs, or reproducing something already happening in the contributor's browser.
+
+Do not attach to a live personal browser session without explicit approval.
+
+If current-session reuse is requested, prefer the supported attach path in the local setup:
+
+```bash
+# Fresh isolated browser (default)
+playwright-cli -s=verify open https://example.com
+
+# Reusable Playwright-managed profile
+playwright-cli -s=verify open https://example.com --persistent
+
+# Attach to an existing browser when the local extension bridge is set up
+playwright-cli open --extension
+```
+
+If the task requires the contributor's current browser session and the attach path is not available in the current setup, stop and ask whether to switch to a fresh session or provide an explicit CDP-based Playwright script.
+
 ## Commands
 
 ### Core

AGENTS.md

@@ -32,7 +32,7 @@ Only record items that are repo-specific, likely to recur, and have a concrete m
 | Translation key/value changed | Use `docs/agent-playbooks/translations.md` |
 | Bug report in a specific file/line | Start with git history scan from `docs/agent-playbooks/bug-investigation.md` before editing |
 | `CHANGELOG.md` or package version changed | Run `yarn blotter:check`; if needed add a concise release one-liner |
-| UI/visual behavior changed | Verify in browser with `playwright-cli`; test desktop and mobile viewport |
+| UI/visual behavior changed | Verify in browser with `playwright-cli`; test desktop and mobile viewport; if existing browser state matters, confirm whether to use a fresh session or the contributor's current browser session |
 | Long-running task spans multiple sessions, handoffs, or spawned agents | Use `docs/agent-playbooks/long-running-agent-workflow.md`, keep a machine-readable feature list plus a progress log, and run `./scripts/agent-init.sh --smoke` before starting a fresh feature slice |
 | New reviewable feature/fix started while on `master` | Create a short-lived `codex/feature/*`, `codex/fix/*`, `codex/docs/*`, or `codex/chore/*` branch from `master` before editing; use a separate worktree only for parallel tasks |
 | New unrelated task started while another task branch is already checked out or being worked on by another agent | Create a separate worktree from `master`, create a new short-lived task branch there, and keep each agent on its own worktree/branch/PR |
@@ -119,6 +119,9 @@ src/
 - After React UI logic changes, run: `yarn doctor`.
 - Treat React Doctor output as actionable guidance; prioritize `error` then `warning`.
 - For UI/visual changes, verify with `playwright-cli` on desktop and mobile viewport.
+- For browser automation and verification, default to a fresh isolated `playwright-cli` session for reproducibility.
+- If the task depends on existing auth, cookies, extensions, open tabs, or another live browser state, explicitly confirm whether to use a fresh isolated session or the contributor's current browser session.
+- Do not assume permission to drive the contributor's active personal browser session.
 - The shared hook verification path is strict by default. Only set `AGENT_VERIFY_MODE=advisory` when you intentionally need signal from a broken tree without blocking the session.
 - Use `yarn test:coverage` as an advisory check when expanding test coverage or auditing risky logic; do not invent a repo-wide coverage gate unless the user asks for one.
 - If verification fails, fix and re-run until passing.

docs/agent-playbooks/skills-and-tools.md

@@ -32,6 +32,13 @@ npx skills add https://github.com/vercel-labs/skills --skill find-skills
 
 Use `playwright-cli` for browser automation (navigation, interaction, screenshots, tests, extraction).
 
+Default to a fresh isolated browser session for normal verification. If the task depends on the contributor's existing browser state, ask whether they want:
+
+- a fresh isolated `playwright-cli` session
+- their current browser session reused
+
+Do not attach to a live personal browser session without explicit confirmation.
+
 ```bash
 npm install -g @playwright/cli@latest
 playwright-cli install --skills
@@ -48,3 +55,4 @@ Avoid GitHub MCP and browser MCP servers for this project because they add signi
 
 - GitHub operations: use `gh` CLI.
 - Browser operations: use `playwright-cli`.
+- If current browser reuse is needed, keep using Playwright-based attach paths rather than browser MCP servers.