@ulpi/browse 2.3.4 → 2.4.0

package/skill/browse/references/commands.md

@@ -197,11 +197,42 @@ browse --runtime rebrowser goto https://example.com
 # State list / show
 browse state list
 browse state show mysite
+
+# Native app automation (Android, iOS, macOS)
+browse sim start --platform android --app com.android.settings --visible
+browse sim start --platform ios --app com.apple.Preferences --visible
+browse --platform android --app com.android.settings snapshot -i
+browse --platform ios --app com.apple.Preferences snapshot -i
+browse --app "System Settings" snapshot -i              # macOS
+browse --platform android --app com.android.settings tap @e3
+browse --platform android --app com.android.settings swipe up
+browse --platform android --app com.android.settings press back
+browse --platform ios --app com.apple.mobilesafari type "example.com"
+browse --app TextEdit press "cmd+n"                     # macOS modifier combos
+browse sim stop --platform android
+browse sim stop --platform ios
+
+# Install and test your own app from a file
+browse sim start --platform ios --app ./build/MyApp.app --visible   # .app bundle
+browse sim start --platform ios --app ./MyApp.ipa --visible          # .ipa archive
+browse sim start --platform android --app ./app-debug.apk --visible  # .apk file
+
+# Cloud providers (encrypted API keys, never visible to agents)
+browse provider save browserbase <api-key>
+browse --provider browserbase goto https://example.com
+
+# Performance audit
+browse perf-audit https://example.com
+browse perf-audit save baseline
+browse perf-audit compare baseline
 ```
 
 ## Navigation
 ```
 browse goto <url>         Navigate current tab
+browse goto <url> --ready Wait for hydration/readiness after navigation
+browse goto @google "query"   Search macro — expands to Google search URL
+browse goto @youtube "query"  Search macro — YouTube, Amazon, Reddit, Wikipedia, etc.
 browse back               Go back
 browse forward            Go forward
 browse reload             Reload page
@@ -215,6 +246,13 @@ browse html [selector]    innerHTML of element, or full page HTML
 browse links              All links as "text -> href"
 browse forms              All forms + fields as JSON
 browse accessibility      Accessibility tree snapshot (ARIA)
+browse images             List page images (src, alt, dimensions)
+browse images [selector]  Images within a specific element
+browse images --limit 20  Limit number of images returned
+browse images --inline    Include base64-encoded image data
+browse schema             Extract JSON-LD, Microdata, RDFa structured data (parsed JSON)
+browse meta               Extract page meta tags (title, description, canonical, OG, Twitter, hreflang, robots, viewport)
+browse headings           Extract H1-H6 heading hierarchy with counts and indented tree
 ```
 
 ## Snapshot (ref-based element selection)
@@ -227,6 +265,9 @@ browse snapshot -c        Compact (no empty structural elements)
 browse snapshot -C        Cursor-interactive (detect divs with cursor:pointer/onclick/tabindex)
 browse snapshot -d <N>    Limit depth to N levels
 browse snapshot -s <sel>  Scope to CSS selector
+browse snapshot --offset <N>    Start output from line N (windowing for large snapshots)
+browse snapshot --max-chars <N> Limit snapshot output to N characters
+browse snapshot --serp    Google SERP fast extraction (structured results, no refs)
 browse snapshot-diff      Compare current vs previous snapshot
 ```
 
@@ -245,15 +286,26 @@ Refs are invalidated on navigation -- run `snapshot` again after `goto`.
 ## Interaction
 ```
 browse click <selector>        Click element (CSS selector or @ref)
+browse click <sel> --force     Force-click through overlay interception (bypasses actionability checks)
+browse click <sel> --if-exists Click only if element exists (no error if missing)
+browse click <sel> --if-visible Click only if element is visible
 browse click <x>,<y>           Click at page coordinates (e.g. 590,461)
 browse rightclick <selector>   Right-click element (context menu)
 browse dblclick <selector>     Double-click element
 browse fill <selector> <value> Fill input field
+browse fill <sel> <val> --if-empty  Fill only if field is empty
 browse select <selector> <val> Select dropdown value
 browse hover <selector>        Hover over element
+browse hover <sel> --if-exists Hover only if element exists
+browse hover <sel> --if-visible Hover only if visible
 browse focus <selector>        Focus element
+browse focus <sel> --if-exists Focus only if element exists
+browse focus <sel> --if-visible Focus only if visible
 browse tap <selector>          Tap element (requires touch context via emulate)
+browse tap <sel> --if-exists   Tap only if element exists
+browse tap <sel> --if-visible  Tap only if visible
 browse check <selector>        Check checkbox
+browse check <sel> --if-unchecked  Check only if not already checked
 browse uncheck <selector>      Uncheck checkbox
 browse drag <src> <tgt>        Drag source to target
 browse type <text>             Type into focused element
@@ -277,6 +329,7 @@ browse wait --fn "expr"        Wait for JavaScript condition
 browse wait --load <state>     Wait for load state
 browse wait --url <pattern>    Wait for URL match
 browse wait --network-idle     Wait for network idle
+browse wait --request <pattern>  Wait for a matching network request
 browse wait --download                    Wait for download, return temp path
 browse wait --download ./report.pdf       Wait and save to path
 browse wait --download 60000              Custom timeout (ms)
@@ -289,6 +342,7 @@ browse viewport <WxH>          Set viewport size (e.g. 375x812)
 browse upload <sel> <files>    Upload file(s) to a file input
 browse highlight <selector>    Highlight element (visual debugging)
 browse download <sel> [path]   Download file triggered by click
+browse download <sel> --inline Return file content as base64 (no disk write)
 browse dialog-accept [value]   Set dialogs to auto-accept
 browse dialog-dismiss          Set dialogs to auto-dismiss (default)
 browse emulate <device>        Emulate device (iphone, pixel, etc.)
@@ -322,6 +376,8 @@ browse element-state <selector> Element state (visible/enabled/checked/focused)
 browse value <selector>        Get input field value
 browse count <selector>        Count matching elements
 browse box <selector>          Get bounding box as JSON {x, y, width, height}
+browse layout <selector>       Get element layout details
+browse request <index|url>     Inspect a captured network request by index or URL pattern
 browse dialog                  Last dialog info or "(no dialog detected)"
 browse console [--clear]       View/clear console messages
 browse errors [--clear]        View/clear page errors (filtered from console)
@@ -397,6 +453,7 @@ browse --profile <name> <cmd>             Use persistent browser profile
 browse profile list                       List profiles with disk size
 browse profile delete <name>              Delete a profile
 browse profile clean [--older-than <d>]   Remove old profiles (default: 7 days)
+browse profiles                           List available camoufox profiles from .browse/camoufox-profiles/
 ```
 
 ## State persistence
@@ -444,6 +501,123 @@ browse record stop                     Stop recording, keep steps for export
 browse record status                   Recording state and step count
 browse record export browse [path]     Export as chain-compatible JSON (replay with browse chain)
 browse record export replay [path]    Export as Chrome DevTools Recorder (Playwright/Puppeteer)
+browse record export replay --selectors css,aria [path]  Filter selector types in export
+```
+
+## Native App Automation
+```
+browse sim start --platform ios|android --app <id-or-path> [--visible] [--device <name>]  Start + install/launch app
+browse sim stop --platform ios|android                          Stop simulator/emulator
+browse sim status --platform ios|android                        Check runner status
+browse --platform ios --app <bundleId> <command>                Target iOS app
+browse --platform android --app <package> <command>             Target Android app
+browse --app <name> <command>                                   Target macOS app
+```
+
+The `--app` flag accepts a bundle ID, package name, **or file path** (.app/.ipa/.apk). File paths auto-install the app into the simulator/emulator.
+
+Supported commands on all app platforms: `snapshot`, `text`, `tap`, `fill`, `type`, `press`, `swipe`, `screenshot`.
+macOS also supports modifier combos: `browse --app TextEdit press "cmd+n"`.
+Android auto-installs adb, Java, SDK, and emulator on first use (macOS via Homebrew).
+
+### Common iOS Bundle IDs
+| App | Bundle ID |
+|-----|-----------|
+| Settings | `com.apple.Preferences` |
+| Safari | `com.apple.mobilesafari` |
+| Maps | `com.apple.Maps` |
+| Photos | `com.apple.mobileslideshow` |
+| Calendar | `com.apple.mobilecal` |
+
+### Common Android Package Names
+| App | Package Name |
+|-----|-------------|
+| Settings | `com.android.settings` |
+| Chrome | `com.android.chrome` |
+| Dialer | `com.google.android.dialer` |
+| Messages | `com.google.android.apps.messaging` |
+| Calculator | `com.google.android.calculator` |
+
+### Platform enablement (run once)
+```
+browse enable android    # Auto-installs adb, JDK, SDK, emulator, driver
+browse enable ios        # Builds iOS runner (needs Xcode)
+browse enable macos      # Builds browse-ax bridge
+browse enable all        # All platforms
+```
+
+## Performance audit
+```
+browse perf-audit [url]                  Full performance audit (Web Vitals, resources, images, fonts, DOM, render-blocking, third-party, stack detection, correlations, recommendations)
+browse perf-audit [url] --no-coverage    Skip JS/CSS coverage collection (faster)
+browse perf-audit [url] --no-detect      Skip framework/SaaS/infrastructure detection
+browse perf-audit [url] --json           Output as structured JSON (for programmatic use)
+browse perf-audit [url] --budget lcp:2500,cls:0.1,tbt:300  Set performance budgets (fail if exceeded)
+browse perf-audit save [name]            Save audit report to .browse/audits/ (auto-names from URL + date if omitted)
+browse perf-audit compare <base> [curr]  Compare saved baseline vs current page or another saved audit (regression detection)
+browse perf-audit list                   List saved audit reports (name, size, date)
+browse perf-audit delete <name>          Delete a saved audit report
+browse detect                            Detect tech stack: frameworks, SaaS platforms, CDN, protocol, compression, caching, DOM complexity, third-party inventory
+browse coverage start                    Start JS/CSS code coverage collection
+browse coverage stop                     Stop collection and report per-file used/unused bytes
+browse initscript set <code>             Inject JS that runs before every page load (pre-navigation observers, mocks, polyfills)
+browse initscript show                   Show current init script
+browse initscript clear                  Remove init script
+```
+
+## YouTube transcript
+```
+browse youtube-transcript <url>            Extract captions from YouTube video
+browse youtube-transcript <url> --lang en  Specify caption language
+```
+
+## API requests
+```
+browse api <method> <url>                          Make HTTP request (GET, POST, PUT, DELETE, etc.)
+browse api <method> <url> --body '{"key":"val"}'   With JSON body
+browse api <method> <url> --header "Auth:Bearer x"  With custom header
+```
+
+## Assertions (expect)
+```
+browse expect --url <pattern>                      Assert current URL matches
+browse expect --text <text>                        Assert text exists on page
+browse expect --visible <selector>                 Assert element is visible
+browse expect --hidden <selector>                  Assert element is hidden
+browse expect --count <selector> <n>               Assert element count
+browse expect --request <pattern>                  Assert a network request was made
+browse expect --timeout 5000                       Custom timeout for assertions (ms)
+```
+
+## Visual & Accessibility audit
+```
+browse visual                  Visual snapshot of the page
+browse a11y-audit              Accessibility audit (WCAG violations, warnings, passes)
+```
+
+## Flows (reusable test sequences)
+```
+browse flow <file.yaml>        Run a flow from a YAML file
+browse flow save <name>        Save recorded commands as a named flow
+browse flow run <name>         Run a saved flow by name
+browse flow list               List saved flows
+```
+
+## Retry & Watch
+```
+browse retry "<cmd>" --until <condition>            Retry a command until condition is met
+browse retry "<cmd>" --until <cond> --max 5         Max retry attempts (default: 10)
+browse retry "<cmd>" --until <cond> --backoff       Exponential backoff between retries
+browse watch "<selector>"                           Watch an element for changes
+browse watch "<sel>" --on-change "<cmd>"            Run command when element changes
+browse watch "<sel>" --timeout 30000                Custom watch timeout (ms)
+```
+
+## Cloud Providers
+```
+browse provider save <name> <key>  Save provider API key (encrypted)
+browse provider list               List saved providers
+browse provider delete <name>      Delete provider key
 ```
 
 ## React DevTools
@@ -461,24 +635,6 @@ browse react-devtools owners <sel>     Parent component chain
 browse react-devtools context <sel>    Context values consumed by component
 ```
 
-## Performance audit
-```
-browse perf-audit [url]                  Full performance audit (Web Vitals, resources, images, fonts, DOM, coverage, stack detection, recommendations)
-browse perf-audit [url] --no-coverage    Skip JS/CSS coverage (faster)
-browse perf-audit [url] --no-detect      Skip framework/SaaS detection
-browse perf-audit [url] --json           Structured JSON output
-browse perf-audit save [name]            Save audit report to .browse/audits/ (auto-names from URL + date)
-browse perf-audit compare <base> [curr]  Compare saved baseline vs current page or another saved audit
-browse perf-audit list                   List saved audit reports
-browse perf-audit delete <name>          Delete a saved audit
-browse detect                            Tech stack fingerprint (frameworks, SaaS, CDN, infra)
-browse coverage start                    Start JS/CSS code coverage collection
-browse coverage stop                     Stop and report per-file used/unused bytes
-browse initscript set <code>             Inject JS before every page load
-browse initscript show                   Show current init script
-browse initscript clear                  Remove init script
-```
-
 ## Server management
 ```
 browse status                  Server health, uptime, session count
@@ -491,6 +647,35 @@ browse restart                 Kill + restart server
 browse inspect                 Open DevTools (requires BROWSE_DEBUG_PORT)
 ```
 
+## CLI Flags
+
+| Flag | Description |
+|------|-------------|
+| `--session <id>` | Named session (isolates tabs, refs, cookies — auto-persists on close) |
+| `--profile <name>` | Persistent browser profile (own Chromium, full state) |
+| `--state <path>` | Load state file (cookies/storage) before first command |
+| `--json` | Wrap output as `{success, data, command}` |
+| `--content-boundaries` | Wrap page content in nonce-delimited markers (prompt injection defense) |
+| `--allowed-domains <d,d>` | Block navigation/resources outside allowlist |
+| `--max-output <n>` | Truncate output to N characters |
+| `--headed` | Run browser in headed (visible) mode |
+| `--chrome` | Shortcut for `--runtime chrome --headed` (uses real Chrome, bypasses bot detection) |
+| `--cdp <port>` | Connect to Chrome on a specific debugging port |
+| `--connect` | Auto-discover and connect to a running Chrome instance |
+| `--provider <name>` | Cloud browser provider (browserless, browserbase) |
+| `--runtime <name>` | Browser engine: playwright (default), camoufox (anti-detection Firefox), rebrowser (stealth), lightpanda, chrome |
+| `--ready` | Wait for hydration/readiness after goto |
+| `--force` | Force-click through overlay interception |
+| `--serp` | Google SERP fast extraction mode |
+| `--mcp` | Run as MCP server (for Cursor, Windsurf, Cline) |
+| `--context` | Show state changes after commands |
+| `--context delta` | ARIA diff with refs |
+| `--context full` | Complete snapshot with refs after write commands |
+| `--camoufox-profile <name>` | Use a named camoufox profile for browser launch (JSON in `.browse/camoufox-profiles/<name>.json`). Only applies when starting a new server. |
+| `--platform <ios\|android>` | Target native app platform |
+| `--app <id-or-path>` | Target app by bundle ID, package name, or file path (.app/.ipa/.apk) |
+| `--device <name>` | Simulator/emulator device name (e.g. "iPhone 15", "Pixel 7") |
+
 ## Handoff (human takeover)
 ```
 browse handoff [reason]        Swap to visible browser for user to solve CAPTCHA/MFA

package/skill/browse-aeo/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: browse-aeo
+version: 1.0.0
+description: |
+  Answer Engine Optimization (AEO) audit and SERP analysis for AI-generated answers.
+  Analyzes pages for AEO readiness (structured data, FAQ patterns, heading hierarchy,
+  meta quality) and checks how queries appear in AI-powered search results (Google AI
+  Overviews, Perplexity, ChatGPT Search). Uses the browse CLI for all page interaction.
+allowed-tools:
+  - Bash
+  - Read
+argument-hint: "[URL to audit or search query to analyze]"
+arguments:
+  - request
+when_to_use: |
+  Use when the user asks for AEO audit, answer engine optimization, AI search optimization,
+  AI Overview analysis, Perplexity citation check, or says /browse-aeo. Also use when the
+  user wants to understand how a page or domain appears in AI-generated answers.
+effort: high
+---
+
+# browse-aeo: Answer Engine Optimization
+
+## Goal
+
+Audit a page for AEO readiness or analyze how a query surfaces in AI-powered search.
+Two modes: **Page Audit** (analyze a URL) and **SERP Analysis** (analyze a search query).
+
+## Mode 1: Page Audit
+
+Evaluate a single URL for AEO readiness. Run each step in order.
+
+### Step 1: Navigate and stabilize
+
+```bash
+browse goto <url>
+browse wait --network-idle
+```
+
+### Step 2: Extract structured data
+
+```bash
+browse schema
+```
+
+Analyze for: JSON-LD presence (critical for AEO), FAQPage schema (directly feeds AI answers), HowTo schema (surfaces in how-to answers), Article/NewsArticle/BlogPosting (attribution), Organization/Person (authority), Breadcrumb (hierarchy), QAPage (Q&A pairs). Empty or minimal structured data is a major AEO gap.
+
+### Step 3: Extract and evaluate meta tags
+
+```bash
+browse meta
+```
+
+Check: meta description (concise direct answer, under 160 chars -- AI uses this as candidate snippet), canonical URL (must be present), Open Graph tags (og:title, og:description), robots directives (`noindex` or `nosnippet` blocks AI citation entirely).
+
+### Step 4: Analyze heading hierarchy
+
+```bash
+browse headings
+```
+
+Evaluate: single H1 (clear topic statement), H2s as questions or clear topic labels (AI uses headings to find answer boundaries), question-format H2s ("What is X?", "How to Y?") are strongly preferred, logical nesting (no skipped levels).
+
+### Step 5: Analyze page content for answer patterns
+
+```bash
+browse text
+```
+
+Scan for: direct definitions in the first paragraph ("X is a..." -- AI favors concise leads), FAQ patterns (Q&A pairs even without schema), numbered/bulleted lists (AI prefers extractable structure), concise paragraphs (under 50 words are more likely cited), authority signals ("We tested...", "In our experience..." -- original research language).
+
+### Step 6: Produce the AEO audit report
+
+Score the page on a 0-100 scale across these dimensions:
+
+| Dimension | Weight | What to check |
+|-----------|--------|---------------|
+| Structured Data | 25% | JSON-LD presence, FAQ/HowTo/Article schema, completeness |
+| Meta Quality | 15% | Description as answer snippet, canonical, no blocking robots |
+| Heading Structure | 20% | Single H1, question-format H2s, logical nesting |
+| Answer Readiness | 25% | Direct definitions, FAQ patterns, concise paragraphs, lists |
+| Authority Signals | 15% | Organization schema, author markup, original research language |
+
+Report: overall score out of 100, per-dimension score with findings and recommendations, then the top 3 highest-impact actions.
+
+## Mode 2: SERP Analysis
+
+Check how a query appears in AI-powered search results.
+
+### Step 1: Google search with AI Overview detection
+
+```bash
+browse goto "https://www.google.com/search?q=<url-encoded-query>"
+browse wait --network-idle
+browse snapshot -i
+```
+
+Read the snapshot to identify: AI Overview (generative answer block, note cited domains), Featured Snippet (boxed answer, note source domain), People Also Ask (expandable questions -- these are AEO targets), organic position of target domain.
+
+If Google blocks the request, retry with camoufox:
+
+```bash
+browse --runtime camoufox --headed goto "https://www.google.com/search?q=<url-encoded-query>"
+browse --runtime camoufox --headed snapshot -i
+```
+
+### Step 2: Perplexity analysis (camoufox recommended)
+
+Perplexity has bot detection. Use camoufox:
+
+```bash
+browse --runtime camoufox --headed goto "https://www.perplexity.ai/search?q=<url-encoded-query>"
+browse --runtime camoufox --headed wait --network-idle
+browse --runtime camoufox --headed snapshot -i
+```
+
+Read the snapshot to identify: cited source domains (numbered citations), answer structure (paragraphs, lists, tables), citation density. If Perplexity blocks, note it in the report and skip.
+
+### Step 3: Produce the SERP analysis report
+
+Report: for each engine (Google, Perplexity), list AI Overview presence, cited domains, featured snippet source, People Also Ask questions, and target domain position. End with observations on what content types are being cited and specific actions to improve citation likelihood.
+
+## Key Rules
+
+1. **Always wait after navigation** -- `browse wait --network-idle` before extracting content.
+2. **Use camoufox for search engines** -- Google and Perplexity actively block headless browsers. Fall back to `--runtime camoufox --headed` when blocked.
+3. **Agent interprets snapshots** -- there is no magic SERP parser. The agent reads `browse snapshot -i` output and identifies AI Overview elements, citations, and People Also Ask by reading the accessibility tree.
+4. **Structured data is the top signal** -- JSON-LD FAQ and HowTo schemas are the single most impactful AEO lever. Always check this first.
+5. **Do not fabricate scores** -- if a dimension cannot be evaluated (e.g., page is behind a login wall), mark it as "N/A" and explain why.
+6. **Keep recommendations actionable** -- "Add FAQ schema" is good. "Improve SEO" is not.
+
+## Guardrails
+
+- Do not add `disable-model-invocation`; this is a general-purpose audit skill.
+- Do not add `context: fork`; audit results are needed in the current flow.
+- Do not run `browse handoff` without explicit user confirmation.
+- Do not guess SERP structure -- always take a snapshot and read it.
+- Do not claim a page "appears in AI Overviews" without actually checking via SERP analysis.
+
+## Output Contract
+
+Report:
+
+1. the mode used (Page Audit or SERP Analysis)
+2. the URL audited or query analyzed
+3. findings per dimension with specific evidence
+4. actionable recommendations ranked by impact
+5. any blockers encountered (bot detection, login walls, empty results)

package/skill/browse-config/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: browse-config
+version: 1.0.0
+description: |
+  Guided configuration generator for the browse CLI's camoufox integration.
+  Asks the user questions to build a browse.json camoufox section or a named
+  profile JSON file for stealth, fast-scraping, Google-safe, or custom setups.
+allowed-tools:
+  - AskUserQuestion
+  - Bash
+  - Read
+  - Write
+argument-hint: "[preset or 'custom']"
+arguments:
+  - request
+when_to_use: |
+  Use when the user asks to configure camoufox, set up stealth browsing, create a browse
+  profile, tune anti-detection settings, or says /browse-config. Do NOT use for general
+  browse CLI usage or non-camoufox configuration.
+effort: medium
+---
+
+# browse-config: Camoufox Configuration Generator
+
+## Step 0: Ask what the user needs
+
+Use AskUserQuestion to determine the goal. Offer these presets:
+
+| Preset | Description |
+|--------|-------------|
+| **Stealth browsing** | For scraping protected sites. Enables geoip, humanize, default OS fingerprint. |
+| **Fast scraping** | Minimal footprint. Blocks images, WebRTC, WebGL. Enables disk cache. |
+| **Google-safe** | For Google search without "unusual traffic" blocks. Enables geoip, humanize, random OS. |
+| **Custom** | Walk through each option group interactively. |
+
+### Preset defaults
+
+**Stealth browsing:**
+```json
+{
+  "geoip": true,
+  "humanize": true
+}
+```
+
+**Fast scraping:**
+```json
+{
+  "blockImages": true,
+  "blockWebrtc": true,
+  "blockWebgl": true,
+  "enableCache": true
+}
+```
+
+**Google-safe:**
+```json
+{
+  "geoip": true,
+  "humanize": true,
+  "os": ["windows", "macos", "linux"]
+}
+```
+
+## Step 1: Custom configuration (skip if preset chosen)
+
+If the user chose "Custom", ask about each option group using AskUserQuestion. Present one group at a time.
+
+### Identity
+- `os` (string or array) -- target OS fingerprint: "windows", "macos", "linux", or an array for random selection
+- `locale` (string or array) -- browser locale, e.g. "en-US" or ["en-US", "en-GB"]
+- `fingerprint` (object) -- advanced fingerprint overrides (most users skip this)
+
+### Privacy
+- `blockWebrtc` (boolean) -- block WebRTC to prevent IP leaks
+- `blockWebgl` (boolean) -- block WebGL fingerprinting
+- `blockImages` (boolean) -- block image loading (also improves speed)
+
+### Performance
+- `enableCache` (boolean) -- enable browser disk cache
+- `blockImages` (boolean) -- already covered in Privacy, mention speed benefit here
+
+### Network
+- `proxy` (string or object) -- proxy URL like "http://user:pass@host:port" or `{"server":"...","username":"...","password":"..."}`
+- `geoip` (string or boolean) -- true to auto-derive from proxy IP, or a country code like "US"
+
+### Behavior
+- `humanize` (boolean or number) -- true for default human-like delays, or a number (0.5-2.0) to control speed
+
+### Advanced (offer only if user asks)
+- `addons` (string[]) -- Firefox addon paths to load
+- `excludeAddons` (string[]) -- built-in addons to skip
+- `firefoxUserPrefs` (Record) -- raw Firefox about:config preferences
+- `args` (string[]) -- extra browser launch arguments
+- `fonts` (string[]) -- custom font list
+- `customFontsOnly` (boolean) -- use only custom fonts
+- `screen` (object) -- `{minWidth, maxWidth, minHeight, maxHeight}`
+- `window` ([width, height]) -- fixed window size
+- `ffVersion` (number) -- target Firefox version
+- `headless` (boolean or "virtual") -- headless mode (not recommended for anti-detection)
+- `mainWorldEval` (boolean) -- enable main world JavaScript eval
+- `executablePath` (string) -- custom camoufox binary path
+- `env` (Record) -- environment variables for the browser process
+- `virtualDisplay` (string) -- virtual display config (Linux only)
+- `disableCoop` (boolean) -- disable Cross-Origin-Opener-Policy headers
+- `debug` (boolean) -- enable debug logging
+
+## Step 2: Ask where to save
+
+Use AskUserQuestion with two options:
+
+1. **browse.json** -- adds a `"camoufox"` section to the project's `browse.json`. Applied automatically whenever `--runtime camoufox` is used.
+2. **Named profile** -- saves to `.browse/camoufox-profiles/<name>.json`. Used with `--camoufox-profile <name>`. Good for per-scenario configs (e.g. "google", "scrape", "stealth").
+
+If the user picks a named profile, ask for the profile name.
+
+## Step 3: Generate and write the file
+
+### If browse.json
+
+Read the existing `browse.json` first (if it exists). Merge the new `camoufox` key into it. Write the result:
+
+```json
+{
+  "camoufox": {
+    "geoip": true,
+    "humanize": true
+  }
+}
+```
+
+### If named profile
+
+Create the directory `.browse/camoufox-profiles/` if needed. Write just the config object:
+
+```json
+{
+  "geoip": true,
+  "humanize": true,
+  "os": "windows"
+}
+```
+
+## Step 4: Show usage
+
+After writing the file, tell the user exactly how to use it.
+
+**If browse.json:**
+```
+Run: browse --runtime camoufox goto <url>
+The camoufox section is applied automatically.
+```
+
+**If named profile:**
+```
+Run: browse --runtime camoufox --camoufox-profile <name> goto <url>
+```
+
+Always note: "The `--camoufox-profile` flag only applies when starting a new server. If a server is already running, stop it first with `browse stop`."
+
+## All CamoufoxConfig options
+
+All keys use camelCase in JSON. They are auto-mapped to snake_case for camoufox-js internally.
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `os` | string or string[] | Target OS fingerprint |
+| `blockImages` | boolean | Block image loading |
+| `blockWebrtc` | boolean | Block WebRTC |
+| `blockWebgl` | boolean | Block WebGL |
+| `disableCoop` | boolean | Disable COOP headers |
+| `geoip` | string or boolean | GeoIP spoofing (true or country code) |
+| `humanize` | boolean or number | Human-like delays (true or speed factor) |
+| `locale` | string or string[] | Browser locale |
+| `addons` | string[] | Firefox addon paths |
+| `fonts` | string[] | Custom fonts |
+| `customFontsOnly` | boolean | Only use custom fonts |
+| `screen` | object | Screen size range ({minWidth, maxWidth, minHeight, maxHeight}) |
+| `window` | [number, number] | Fixed window size |
+| `fingerprint` | object | Fingerprint overrides |
+| `ffVersion` | number | Firefox version |
+| `headless` | boolean or "virtual" | Headless mode |
+| `mainWorldEval` | boolean | Main world eval |
+| `firefoxUserPrefs` | Record | Firefox about:config prefs |
+| `proxy` | string or object | Proxy config |
+| `enableCache` | boolean | Enable disk cache |
+| `debug` | boolean | Debug logging |
+| `excludeAddons` | string[] | Addons to exclude |
+| `executablePath` | string | Custom browser path |
+| `args` | string[] | Extra browser args |
+| `env` | Record | Environment variables |
+| `virtualDisplay` | string | Virtual display (Linux) |
+
+## Guardrails
+
+- Always use AskUserQuestion before generating config. Do not assume preferences.
+- Use camelCase keys in all generated JSON (the CLI handles snake_case mapping).
+- Never overwrite existing browse.json fields outside the `camoufox` key.
+- Never include proxy credentials in output shown to the user. Write them to the file only.
+- Do not include options the user did not ask for or confirm, beyond the preset defaults.