pi-dev-team 0.2.0

package/skills/benchmark/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: benchmark
+description: >-
+  Capture runtime performance metrics (Core Web Vitals, resource sizes, load
+  times) for web pages. Compare against baselines and performance budgets.
+  Use when the user says "benchmark", "check performance", "page speed",
+  "web vitals", "performance regression", or "how fast is this page".
+argument-hint: "<url> [--baseline] [--budget] [--trend] [--mobile] [--3g] [--runs <n>]"
+user-invocable: true
+allowed-tools: Read, Write, Glob, Grep, Bash(npx playwright *), Bash(node *), Bash(mkdir *), Bash(date *), Bash(cat *)
+---
+
+# Benchmark
+
+Role: worker. This command measures runtime performance of web pages using Playwright.
+
+You have been invoked with the `/benchmark` command.
+
+## Worker constraints
+
+1. Measure only; do not modify the page or app under test.
+2. Compare against the declared budget; do not invent thresholds.
+3. **Be concise.** Report the metrics table and verdict, no narration.
+
+## Parse Arguments
+
+Arguments: $ARGUMENTS
+
+- Positional: URL to benchmark (required). Can be a full URL or a path (prefixed with the dev server URL).
+- `--baseline`: Capture current metrics as the new baseline (overwrites existing)
+- `--budget`: Check against performance budgets in `performance-budget.json`
+- `--trend`: Show performance trends from historical data
+- `--mobile`: Simulate mobile device (375×812 viewport, 4x CPU throttle)
+- `--3g`: Simulate slow 3G network (400 Kbps, 400ms latency, 4x CPU)
+- `--runs <n>`: Number of measurement runs (default: 3, median reported)
+
+If no URL is provided, look for a `performance-budget.json` file and benchmark all paths listed there.
+
+## Prerequisites Check
+
+1. Verify Playwright is installed: `npx playwright --version`. If not installed, tell the user: "Playwright is required. Run `/project-init` to set up this repo's tooling (it installs Playwright + Chromium for frontend projects), or install directly: `npx playwright install chromium`."
+2. If the URL is localhost, verify the dev server is running by attempting a fetch. If not running, tell the user: "Dev server doesn't appear to be running at <url>. Start it first."
+
+## Steps
+
+### 1. Load the skill
+
+Read `skills/performance-benchmark/SKILL.md` for the full metric definitions, output format, and collection methodology. Read `skills/performance-benchmark/references/benchmark-script.md` for the Playwright script template.
+
+### 2. Generate and run the benchmark script
+
+Generate a Node.js script based on the template that:
+
+- Navigates to the target URL
+- Collects Core Web Vitals (LCP, FCP, CLS, INP) via Performance Observer
+- Collects Navigation Timing (TTFB, DOM Interactive, Load Complete)
+- Collects Resource metrics (transfer sizes by type, request count, largest resource)
+- Captures console errors during load
+- Runs the specified number of times (default 3)
+- Computes median and p95 for each metric
+
+Run the script with `node` and capture the JSON output.
+
+### 3. Compare against baseline (unless --baseline)
+
+If `--baseline` is set:
+
+- Save the metrics to `benchmarks/<page-slug>/baseline.json`
+- Create the directory if needed
+- Report: "Baseline saved for <url>"
+
+If `--baseline` is NOT set:
+
+- Read `benchmarks/<page-slug>/baseline.json` if it exists
+- Compare each metric: regression (>10% worse) → `fail`, degradation (5-10%) → `warn`, stable (±5%) → `pass`, improvement (>10% better) → noted
+- If no baseline exists, report metrics without comparison and suggest: "No baseline found. Run `/benchmark <url> --baseline` to establish one."
+
+### 4. Check performance budgets (if --budget or budget file exists)
+
+Read `performance-budget.json` from the project root. Match the benchmarked URL path against budget entries. Flag any metric that exceeds its budget.
+
+### 5. Append to trend history
+
+Append the current metrics to `benchmarks/<page-slug>/history.jsonl` (one JSON object per line, with timestamp).
+
+If `--trend` is set, read the history file and produce a trend summary showing metric changes over the last 10 entries.
+
+### 6. Generate report
+
+Write a markdown report to `benchmarks/<page-slug>/report.md` using the report format from the skill file.
+
+Display in chat:
+
+- Core Web Vitals table with pass/warn/fail status
+- Resource budget table
+- Any regressions with severity
+- Overall verdict
+
+## Integration
+
+- Complements the `performance-review` agent (static code analysis) with runtime measurement
+- Uses Playwright infrastructure shared with `/browse` and the Browser Testing skill
+- QA Engineer invokes this for performance validation
+- Platform Engineer uses baselines for SLI/SLO definition
+- Can be run as part of `/build` for performance-critical plan steps

package/skills/branch-workflow/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: branch-workflow
+description: Clean branch completion workflow — PR creation, merge strategy, and cleanup. Use this skill when implementation is complete and it's time to ship — after Phase 3 human gate passes. Also use when the user says "create a PR", "merge this", "ship it", "finish this branch", or asks about merge strategy.
+role: worker
+user-invocable: true
+---
+
+# Branch Workflow
+
+Role: worker. This command performs PR creation, merge, and branch cleanup
+directly via git/gh commands.
+
+## Overview
+
+The three-phase workflow ends at the Phase 3 human gate. This skill formalizes what happens after approval: PR creation, merge decision, and branch cleanup. Without this, branches linger and merge conflicts accumulate.
+
+## Constraints
+
+- Do not push to main/master directly — always use a PR
+- Do not force-push unless the human explicitly requests it
+- Do not delete branches that have unmerged work
+- Do not merge without a passing CI check (if CI is configured)
+- Do not switch branches (checkout, worktree enter) without first checking working-tree state and confirming with the human if dirty
+
+## Workflow
+
+### 1. Pre-PR Checklist
+
+Before creating the PR, verify:
+
+- [ ] All tests pass (fresh run, not cached)
+- [ ] `/code-review` passed or warnings are documented
+- [ ] Documentation is current (tech-writer verified in Phase 3)
+- [ ] Branch is rebased on latest main (resolve conflicts if needed)
+
+### 2. Create the PR
+
+- Title: concise, under 70 characters, describes the change
+- Body: Summary (what and why), test plan, link to design doc if one exists
+- Labels: add relevant labels (bug, feature, refactor, docs)
+- Reviewers: assign based on who should review (human decides)
+
+### 3. Present Options
+
+After confirming the base branch, present exactly four choices. If this session entered a worktree via `EnterWorktree` for this branch, each option's cleanup step is performed with the paired `ExitWorktree` call below — never raw `git worktree remove`. If no worktree was entered via `EnterWorktree` (branch-workflow can also run directly in the primary checkout), the `ExitWorktree` steps are a no-op — skip them.
+
+1. **Merge locally** — Integrate feature branch into base, run tests on merged result, delete feature branch, then call `ExitWorktree(action="remove")`
+2. **Push and create PR** — Push branch and create pull request via `gh pr create`. Once the PR is opened, call `ExitWorktree(action="keep")` so the worktree persists on disk while the session's CWD bookkeeping is closed
+3. **Keep as-is** — Preserve branch and worktree for later handling; call `ExitWorktree(action="keep")` immediately after the option is confirmed — do not leave the worktree silently "entered" for the rest of the session
+4. **Discard** — Permanently delete branch and all commits. **Requires the human to type "discard" to confirm.** Never discard without typed confirmation. After confirmation, call `ExitWorktree(action="remove", discard_changes=true)`
+
+### 3a. Pre-Switch Verification (Option 1 only)
+
+Before performing the checkout/merge that Option 1 ("Merge locally") requires, verify the working tree is safe to switch:
+
+1. Run a working-tree status check (`git status --short`, or the worktree-tool equivalent) covering the feature branch's tree. This surfaces both tracked changes (modified/staged) and untracked files — not just tracked ones.
+2. Show the result to the human.
+3. If the tree is clean, proceed with the switch.
+4. If the tree is **not** clean (any modified, staged, or untracked files), stop. Do not switch branches silently. Require the human to explicitly say how to proceed — commit, stash, or abort — before running the checkout. This follows the same explicit-confirmation pattern as Option 4's typed "discard," not a bare warning that can be clicked through.
+5. Re-check that the target/base branch still matches what was confirmed in step 3's "After confirming the base branch..." — this does not re-ask for that confirmation, only verifies it hasn't drifted since.
+
+This step applies only to the branch/worktree switch Option 1 performs. It does not replace or duplicate the Pre-PR Checklist's "Branch is rebased on latest main" item (§1) — that is a rebase-currency check performed earlier, not a dirty-tree check performed at the moment of switching. It also does not modify Post-Merge Verification & Cleanup (§5), which handles branch/worktree deletion after the merge, not the switch before it.
+
+### 4. Merge Strategy (for options 1 and 2)
+
+| Situation | Strategy | Why |
+| ----------- | ---------- | ----- |
+| Single logical change, clean history | Squash merge | One commit tells the story |
+| Multiple logical changes that should stay separate | Merge commit | Preserves the history of each change |
+| Long-lived branch with many commits | Squash merge | Reduces noise in main history |
+| Experimental/spike work | Squash merge | The journey doesn't matter, only the result |
+
+Default: **squash merge** unless the human specifies otherwise.
+
+### 5. Post-Merge Verification & Cleanup
+
+- Run tests on the merged result — **do not skip this**. Broken code must never reach base branches.
+- Delete the feature branch (remote and local) — only for options 1 and 4
+- If a worktree was entered via `EnterWorktree` for this branch, call `ExitWorktree(action="remove")` for options 1 and 4 (never raw `git worktree remove`); options 2 and 3 use `ExitWorktree(action="keep")` as described in Section 3. If no worktree was entered via `EnterWorktree`, this step is a no-op.
+- After removal, verify no orphaned worktree or branch remains — e.g. `git worktree list` and `git branch` should show nothing for the deleted branch
+
+## Integration
+
+- Triggered after Phase 3 human gate approval
+- PR creation follows the git commit conventions in the project
+
+## Output
+
+A merged PR with clean branch history, closed issues, and deleted feature branch.

package/skills/browse/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: browse
+description: >-
+  Launch a browser to navigate URLs, take screenshots, click elements, and fill
+  forms. Use for visual verification, e2e testing, and interactive debugging.
+argument-hint: "<url> [--screenshot <path>] [--click <selector>] [--fill <selector> <value>] [--wait <ms>] [--viewport <WxH>]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash(npx playwright *), Bash(node *)
+---
+
+# Browse
+
+Role: worker. This command provides browser-based interaction for visual verification and e2e testing.
+
+You have been invoked with the `/browse` command.
+
+## Worker constraints
+
+1. Drive the browser only; do not edit source.
+2. Capture evidence (screenshots/logs); do not assert pass/fail beyond what was observed.
+3. **Be concise.** Report observations and artifacts, no preamble.
+
+## Parse Arguments
+
+Arguments: $ARGUMENTS
+
+- Positional: `<url>` (required) — the URL to navigate to
+- `--screenshot <path>`: Save screenshot to this path (default: `tmp/screenshots/<timestamp>.png`)
+- `--click <selector>`: CSS selector to click after page load
+- `--fill <selector> <value>`: CSS selector and value for form input (can be repeated)
+- `--wait <ms>`: Wait this many milliseconds after page load (default: 1000)
+- `--viewport <WxH>`: Viewport dimensions (default: `1280x720`)
+
+## Steps
+
+### 1. Check Playwright availability
+
+Run:
+
+```bash
+npx playwright --version 2>/dev/null
+```
+
+If Playwright is not available, ask the user:
+> Playwright is required for browser interaction. Run `/project-init` to set up
+> this repo's tooling (installs Playwright + Chromium for frontend projects), or
+> install it directly now:
+>
+> ```
+> npx playwright install chromium
+> ```
+
+Do not proceed until Playwright is confirmed available.
+
+### 2. Ensure screenshot directory exists
+
+```bash
+mkdir -p tmp/screenshots
+```
+
+### 3. Execute browser action
+
+Write a temporary Node.js script and execute it with `node`. Use Playwright's API directly for reliable, scriptable interaction.
+
+**Template** (adapt based on parsed arguments):
+
+```javascript
+const { chromium } = require('playwright');
+
+(async () => {
+  const browser = await chromium.launch({ headless: true });
+  const context = await browser.newContext({
+    viewport: { width: VIEWPORT_WIDTH, height: VIEWPORT_HEIGHT }
+  });
+  const page = await context.newPage();
+
+  try {
+    await page.goto('URL', { waitUntil: 'networkidle', timeout: 30000 });
+    await page.waitForTimeout(WAIT_MS);
+
+    // -- Click actions (if --click provided) --
+    // await page.click('SELECTOR');
+
+    // -- Fill actions (if --fill provided) --
+    // await page.fill('SELECTOR', 'VALUE');
+
+    // -- Screenshot --
+    await page.screenshot({ path: 'SCREENSHOT_PATH', fullPage: true });
+
+    console.log('Screenshot saved to: SCREENSHOT_PATH');
+    console.log('Page title:', await page.title());
+    console.log('Page URL:', page.url());
+  } catch (err) {
+    console.error('Browser error:', err.message);
+    // Take a screenshot of the error state if possible
+    try {
+      await page.screenshot({ path: 'SCREENSHOT_PATH', fullPage: true });
+      console.log('Error-state screenshot saved to: SCREENSHOT_PATH');
+    } catch {}
+  } finally {
+    await browser.close();
+  }
+})();
+```
+
+Write the script to a temp file, execute it, then clean up:
+
+```bash
+node /tmp/browse-action.js && rm /tmp/browse-action.js
+```
+
+### 4. Read and describe the screenshot
+
+Use the Read tool to view the screenshot image. Claude's multimodal capabilities will interpret the visual content.
+
+Describe what you see:
+
+- Page layout and structure
+- Key visible content (headings, text, images)
+- State of interactive elements (forms, buttons, error messages)
+- Anything that looks broken, misaligned, or unexpected
+
+### 5. Report results
+
+Provide a summary:
+
+```
+## Browse Results
+- **URL**: <final URL after any redirects>
+- **Title**: <page title>
+- **Viewport**: <width>x<height>
+- **Screenshot**: <path to screenshot>
+- **Actions performed**: <list of click/fill actions, or "none">
+- **Observations**: <what you see in the screenshot>
+```
+
+If the user's goal appears to be testing or verification, note any issues found and suggest next steps.
+
+## Error Handling
+
+- **Navigation timeout**: Report the URL that failed and suggest checking if the server is running
+- **Element not found**: Report the selector that failed and suggest inspecting the page structure
+- **CAPTCHA or auth wall**: Report that manual intervention is needed — instruct the user to complete the challenge in their browser, then re-run `/browse` to continue
+- **Playwright not installed**: Point the user at `/project-init` to set up the repo's tooling, or guide them through `npx playwright install chromium`
+
+## Automated Smoke Test Mode
+
+When invoked non-interactively by the inline review pipeline (Stage 3 browser verification), the caller provides:
+
+- **URL**: The dev server URL for the page under test
+- **Selectors to verify**: CSS selectors that should be visible after the change (e.g., `[data-testid="user-list"]`, `.dashboard-header`)
+- **Expected state**: Brief description of what the page should look like
+
+In this mode:
+
+1. Navigate to the URL with a 30-second timeout
+2. Wait for network idle
+3. For each selector, verify it exists and is visible
+4. Take a full-page screenshot as verification evidence
+5. Return a structured result:
+
+   ```
+   - url: <final URL>
+   - selectors_found: [list of selectors that were visible]
+   - selectors_missing: [list of selectors that were not found or not visible]
+   - screenshot: <path to screenshot>
+   - status: pass | fail
+   - issues: [description of any rendering problems observed]
+   ```
+
+If the connection times out or refuses (dev server not running), return:
+
+```
+- status: skipped
+- reason: "Dev server not reachable at <URL>"
+```
+
+This result feeds into the review loop — `fail` triggers correction iterations (max 2), `skipped` is logged as a warning and does not block the build.
+
+## Multi-Step Interactions
+
+For complex flows (login → navigate → fill form → submit), chain actions in a single script rather than multiple `/browse` invocations. Build the full action sequence in the Node.js script.
+
+If the user describes a multi-step flow conversationally, translate it into the appropriate Playwright action sequence.

package/skills/browser-testing/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: browser-testing
+description: >-
+  Patterns and templates for browser-based QA using Playwright. Covers
+  navigation, form interaction, screenshot capture, visual verification,
+  and CAPTCHA/auth handoff.
+role: worker
+user-invocable: false
+---
+
+# Browser Testing Skill
+
+## Overview
+
+This skill provides reusable patterns for browser-based testing and visual verification using Playwright. Agents load this skill when they need to interact with a running application through a real browser.
+
+## Prerequisites
+
+Playwright must be installed with at least the Chromium browser — `/project-init` installs it for frontend projects, or install manually:
+
+```bash
+npx playwright install chromium
+```
+
+## Playwright Patterns
+
+| Category | Description |
+| ---------- | ------------- |
+| Navigation | `goto`, `waitForSelector`, `waitForNavigation` with network-idle |
+| Form Interaction | `fill`, `selectOption`, `check`, `setInputFiles`, submit |
+| Click Actions | Click by selector/text, double-click, right-click, hover |
+| Screenshots | Full page, viewport, element, and clipped region captures |
+| Waiting Strategies | Selector appear/disappear, text match, network response |
+| Data Extraction | `textContent`, `getAttribute`, `inputValue`, `count`, `isVisible` |
+| Script Template | Full `/browse` boilerplate with error capture and console logging |
+| Error Handling | Common timeout, connection, and protocol errors with resolutions |
+| CAPTCHA/Auth Handoff | Detect walls, report to user, resume from `storageState` |
+
+See `references/playwright-patterns.md` for full code examples, the script template, and the error handling table.
+
+## Fast Feedback Loop
+
+A verification pass is usually a *sequence* of related checks, not one isolated check — keep the loop cheap:
+
+- **Batch checks into one session.** Launch the browser once, run the full sequence of actions/waits/screenshots needed for the verification pass, then close — don't relaunch a fresh browser per individual check.
+- **Reserve `networkidle` for the first navigation.** After the initial `goto`, a re-check following a known, small change should wait on the specific signal that changed (`waitForSelector`, `waitForResponse`) rather than re-waiting on full network idle.
+- **Skip the reload when nothing routed.** If the change under verification didn't require a new route or a fresh document, act on the already-loaded page instead of calling `page.goto()` again or relaunching; use `page.reload()` only when a fresh document is genuinely required.
+- **Scope intermediate screenshots.** Prefer element/clip screenshots for the in-between checks in a sequence; reserve full-page screenshots for the final verification.
+
+The underlying principle — prefer the cheapest deterministic signal over a broad, expensive wait — is the same one that governs CI-gate test-suite design, but this section applies it to a single interactive verification session, not a project's test architecture.
+
+## Visual Verification Guidelines
+
+When interpreting screenshots, describe:
+
+1. **Layout**: Is the page structure correct? Any overlapping elements, broken grids, or overflow?
+2. **Content**: Is the expected text/data visible? Any placeholder text or missing images?
+3. **State**: Are interactive elements in the right state? (buttons enabled/disabled, forms populated, etc.)
+4. **Responsiveness**: At the given viewport, does the layout adapt correctly?
+5. **Errors**: Any visible error messages, 404 pages, or console errors captured?
+
+Compare observations against acceptance criteria when available. Flag discrepancies as findings.

package/skills/browser-testing/references/playwright-patterns.md

@@ -0,0 +1,216 @@
+# Playwright Patterns Reference
+
+## Interaction Patterns
+
+### Navigation
+
+```javascript
+// Basic navigation — waits for network to settle
+await page.goto('http://localhost:3000', { waitUntil: 'networkidle', timeout: 30000 });
+
+// Wait for a specific element before proceeding
+await page.waitForSelector('[data-testid="app-loaded"]', { timeout: 10000 });
+
+// Wait for navigation after a click
+await Promise.all([
+  page.waitForNavigation({ waitUntil: 'networkidle' }),
+  page.click('a[href="/dashboard"]')
+]);
+```
+
+### Form Interaction
+
+```javascript
+// Fill a text input
+await page.fill('input[name="email"]', 'user@example.com');
+
+// Fill and submit a form
+await page.fill('input[name="username"]', 'testuser');
+await page.fill('input[name="password"]', 'testpass');
+await page.click('button[type="submit"]');
+
+// Select from a dropdown
+await page.selectOption('select#country', 'US');
+
+// Check a checkbox
+await page.check('input[type="checkbox"]#agree');
+
+// Upload a file
+await page.setInputFiles('input[type="file"]', '/path/to/file.pdf');
+```
+
+### Click and Interact
+
+```javascript
+// Click a button
+await page.click('button.submit');
+
+// Click by text content
+await page.click('text=Sign In');
+
+// Double-click
+await page.dblclick('.editable-cell');
+
+// Right-click
+await page.click('.context-menu-target', { button: 'right' });
+
+// Hover
+await page.hover('.tooltip-trigger');
+```
+
+### Screenshots
+
+```javascript
+// Full page screenshot
+await page.screenshot({ path: 'tmp/screenshots/full.png', fullPage: true });
+
+// Viewport-only screenshot
+await page.screenshot({ path: 'tmp/screenshots/viewport.png' });
+
+// Element screenshot
+const element = await page.locator('.hero-section');
+await element.screenshot({ path: 'tmp/screenshots/hero.png' });
+
+// Screenshot with custom clip region
+await page.screenshot({
+  path: 'tmp/screenshots/region.png',
+  clip: { x: 0, y: 0, width: 800, height: 600 }
+});
+```
+
+### Waiting Strategies
+
+```javascript
+// Wait for element to appear
+await page.waitForSelector('.results-loaded');
+
+// Wait for element to disappear (e.g., loading spinner)
+await page.waitForSelector('.spinner', { state: 'hidden' });
+
+// Wait for specific text
+await page.waitForSelector('text=Results found');
+
+// Wait for network request to complete
+await page.waitForResponse(resp =>
+  resp.url().includes('/api/data') && resp.status() === 200
+);
+
+// Fixed delay (use sparingly — prefer selector/response waits)
+await page.waitForTimeout(2000);
+```
+
+#### Batched re-check session (fast feedback loop)
+
+For a QA pass with several related checks, reuse one browser/page instead of relaunching per check. Use `networkidle` only for the first navigation; wait on the specific signal that changed for each re-check after that.
+
+```javascript
+const browser = await chromium.launch({ headless: true });
+const page = await (await browser.newContext()).newPage();
+
+// First navigation: full network-idle wait
+await page.goto('http://localhost:3000/form', { waitUntil: 'networkidle' });
+await page.screenshot({ path: 'tmp/screenshots/01-initial.png', fullPage: true });
+
+// Re-check 1: same page, small change — wait on the specific signal, not networkidle
+await page.fill('input[name="email"]', 'user@example.com');
+await page.click('button[type="submit"]');
+await page.waitForSelector('.confirmation-banner');
+await page.locator('.confirmation-banner').screenshot({ path: 'tmp/screenshots/02-confirmation.png' });
+
+// Re-check 2: still no route change — no goto/reload needed
+await page.waitForResponse(resp => resp.url().includes('/api/status') && resp.status() === 200);
+await page.locator('.status-panel').screenshot({ path: 'tmp/screenshots/03-status.png' });
+
+await browser.close();
+```
+
+### Extracting Information
+
+```javascript
+// Get text content
+const heading = await page.textContent('h1');
+
+// Get attribute
+const href = await page.getAttribute('a.primary', 'href');
+
+// Get input value
+const value = await page.inputValue('input[name="search"]');
+
+// Count elements
+const count = await page.locator('.list-item').count();
+
+// Get all text from a list
+const items = await page.locator('.list-item').allTextContents();
+
+// Check visibility
+const isVisible = await page.locator('.error-message').isVisible();
+```
+
+## Script Template
+
+Full template for a `/browse` action script:
+
+```javascript
+const { chromium } = require('playwright');
+
+(async () => {
+  const browser = await chromium.launch({ headless: true });
+  const context = await browser.newContext({
+    viewport: { width: 1280, height: 720 },
+    // Uncomment for mobile testing:
+    // ...require('playwright').devices['iPhone 13']
+  });
+  const page = await context.newPage();
+
+  // Capture console messages for debugging
+  page.on('console', msg => {
+    if (msg.type() === 'error') console.log('CONSOLE ERROR:', msg.text());
+  });
+
+  // Capture uncaught errors
+  page.on('pageerror', err => console.log('PAGE ERROR:', err.message));
+
+  try {
+    await page.goto('TARGET_URL', { waitUntil: 'networkidle', timeout: 30000 });
+
+    // --- Actions go here ---
+
+    await page.screenshot({ path: 'SCREENSHOT_PATH', fullPage: true });
+    console.log('Page title:', await page.title());
+    console.log('Page URL:', page.url());
+  } catch (err) {
+    console.error('Error:', err.message);
+    try {
+      await page.screenshot({ path: 'SCREENSHOT_PATH', fullPage: true });
+    } catch {}
+    process.exitCode = 1;
+  } finally {
+    await browser.close();
+  }
+})();
+```
+
+## Error Handling
+
+| Error | Cause | Resolution |
+| ------- | ------- | ------------ |
+| `TimeoutError: page.goto` | Server not running or URL wrong | Check if dev server is up; verify URL |
+| `TimeoutError: waiting for selector` | Element doesn't exist or is hidden | Inspect page HTML; check selector syntax |
+| `net::ERR_CONNECTION_REFUSED` | No server at the target port | Start the dev server first |
+| `Protocol error: Target closed` | Page crashed or browser closed | Simplify the script; check for infinite loops |
+
+## CAPTCHA and Authentication Handoff
+
+When automated browsing hits a CAPTCHA, MFA, or OAuth login wall:
+
+1. **Detect**: Page contains CAPTCHA iframe, MFA form, or redirected to OAuth provider
+2. **Report**: Tell the user what was encountered and where
+3. **Handoff**: Instruct the user to complete the challenge manually in their browser
+4. **Resume**: After manual completion, re-run `/browse` from the authenticated state
+
+For recurring auth needs, suggest the user:
+
+- Set up a test account with MFA disabled
+- Use session cookies via Playwright's `storageState`
+- Pre-authenticate and save state: `await context.storageState({ path: 'auth.json' })`
+- Load saved state: `browser.newContext({ storageState: 'auth.json' })`