chore: /setup-browser-cookies skill + docs (Phase 3.5)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

SKILL.md

@@ -158,6 +158,21 @@ $B dialog-accept "my answer"  # accept with text
 $B click "#rename-button"     # triggers prompt
 ```
 
+### Test authenticated pages (import real browser cookies)
+
+```bash
+# Import cookies from your real browser (opens interactive picker)
+$B cookie-import-browser
+
+# Or import a specific domain directly
+$B cookie-import-browser comet --domain .github.com
+
+# Now test authenticated pages
+$B goto https://github.com/settings/profile
+$B snapshot -i
+$B screenshot /tmp/github-profile.png
+```
+
 ### Compare two pages / environments
 
 ```bash
@@ -270,6 +285,7 @@ Refs are invalidated on navigation — run `snapshot` again after `goto`.
 | `wait --load` | Wait for page load event |
 | `upload <sel> <file...>` | Upload file(s) |
 | `cookie-import <json>` | Import cookies from JSON file |
+| `cookie-import-browser [browser] [--domain <d>]` | Import cookies from real browser (opens picker UI, or direct import with --domain) |
 | `dialog-accept [text]` | Auto-accept dialogs |
 | `dialog-dismiss` | Auto-dismiss dialogs |
 | `viewport <WxH>` | Set viewport size |

TODO.md

@@ -40,7 +40,14 @@
   - [x] `browse/bin/find-browse` (DRY binary discovery across skills)
   - [ ] Video recording (deferred to Phase 5 — recreateContext destroys page state)
 
-## Phase 3.5: Visual PR Annotations + S3 Upload
+## Phase 3.5: Browser Cookie Import (v0.3.x)
+  - [x] `cookie-import-browser` command (Chromium cookie DB decryption)
+  - [x] Cookie picker web UI (served from browse server)
+  - [x] `/setup-browser-cookies` skill
+  - [x] Unit tests with encrypted cookie fixtures (18 tests)
+  - [x] Browser registry (Comet, Chrome, Arc, Brave, Edge)
+
+## Phase 3.6: Visual PR Annotations + S3 Upload
   - [ ] `/setup-gstack-upload` skill (configure S3 bucket for image hosting)
   - [ ] `browse/bin/gstack-upload` helper (upload file to S3, return public URL)
   - [ ] `/ship` Step 7.5: visual verification with screenshots in PR body
@@ -70,6 +77,7 @@
     - Pass/fail with evidence
 
 ## Phase 5: State & Sessions
+  - [ ] v20 encryption format support (AES-256-GCM) — future Chromium versions may change from v10
   - [ ] Sessions (isolated browser instances with separate cookies/storage/history)
   - [ ] State persistence (save/load cookies + localStorage to JSON files)
   - [ ] Auth vault (encrypted credential storage, referenced by name, LLM never sees passwords)
@@ -91,6 +99,7 @@
   - [ ] CDP mode (connect to already-running Chrome/Electron apps)
 
 ## Future Ideas
+  - [ ] Linux/Windows cookie decryption (GNOME Keyring / kwallet / DPAPI)
   - [ ] Trend tracking across QA runs — compare baseline.json over time, detect regressions (P2, S)
   - [ ] CI/CD integration — `/qa` as GitHub Action step, fail PR if health score drops (P2, M)
   - [ ] Accessibility audit mode — `--a11y` flag for focused accessibility testing (P3, S)

setup-browser-cookies/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: setup-browser-cookies
+version: 1.0.0
+description: |
+  Import cookies from your real browser (Comet, Chrome, Arc, Brave, Edge) into the
+  headless browse session. Opens an interactive picker UI where you select which
+  cookie domains to import. Use before QA testing authenticated pages.
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# Setup Browser Cookies
+
+Import logged-in sessions from your real Chromium browser into the headless browse session.
+
+## How it works
+
+1. Find the browse binary
+2. Run `cookie-import-browser` to detect installed browsers and open the picker UI
+3. User selects which cookie domains to import in their browser
+4. Cookies are decrypted and loaded into the Playwright session
+
+## Steps
+
+### 1. Find the browse binary
+
+```bash
+B=$(browse/bin/find-browse 2>/dev/null || ~/.claude/skills/gstack/browse/bin/find-browse 2>/dev/null)
+if [ -n "$B" ]; then
+  echo "READY: $B"
+else
+  echo "NEEDS_SETUP"
+fi
+```
+
+If `NEEDS_SETUP`:
+1. Tell the user: "gstack browse needs a one-time build (~10 seconds). OK to proceed?" Then STOP and wait.
+2. Run: `cd <SKILL_DIR> && ./setup`
+3. If `bun` is not installed: `curl -fsSL https://bun.sh/install | bash`
+
+### 2. Open the cookie picker
+
+```bash
+$B cookie-import-browser
+```
+
+This auto-detects installed Chromium browsers (Comet, Chrome, Arc, Brave, Edge) and opens
+an interactive picker UI in your default browser where you can:
+- Switch between installed browsers
+- Search domains
+- Click "+" to import a domain's cookies
+- Click trash to remove imported cookies
+
+Tell the user: **"Cookie picker opened — select the domains you want to import in your browser, then tell me when you're done."**
+
+### 3. Direct import (alternative)
+
+If the user specifies a domain directly (e.g., `/setup-browser-cookies github.com`), skip the UI:
+
+```bash
+$B cookie-import-browser comet --domain github.com
+```
+
+Replace `comet` with the appropriate browser if specified.
+
+### 4. Verify
+
+After the user confirms they're done:
+
+```bash
+$B cookies
+```
+
+Show the user a summary of imported cookies (domain counts).
+
+## Notes
+
+- First import per browser may trigger a macOS Keychain dialog — click "Allow" / "Always Allow"
+- Cookie picker is served on the same port as the browse server (no extra process)
+- Only domain names and cookie counts are shown in the UI — no cookie values are exposed
+- The browse session persists cookies between commands, so imported cookies work immediately