@ulpi/browse 2.3.3 → 2.4.0

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.

package/skill/browse-geo/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: browse-geo
+version: 1.0.0
+description: |
+  Generative Engine Optimization (GEO) monitoring — track brand and domain visibility
+  across AI-powered search engines: Google AI Overviews, Perplexity, and ChatGPT Search.
+  Run multi-query sweeps, detect citations, measure domain presence, and generate
+  cross-engine visibility reports. Uses the browse CLI with camoufox for stealth.
+allowed-tools:
+  - Bash
+  - Read
+  - AskUserQuestion
+argument-hint: "[brand queries or domain to monitor]"
+arguments:
+  - request
+when_to_use: |
+  Use when the user asks for GEO monitoring, generative engine optimization, AI visibility
+  tracking, brand monitoring in AI search, or says /browse-geo. Examples:
+  - "Check if my domain appears in Google AI Overviews for these queries"
+  - "Monitor brand visibility across Perplexity and ChatGPT Search"
+  - "Run a GEO audit for our product across AI search engines"
+  - "Track which domains get cited in AI-generated answers"
+  Do NOT use for traditional SEO (rankings, meta tags, crawlability) — use browse-seo instead.
+effort: high
+---
+
+# browse-geo: Generative Engine Optimization Monitoring
+
+## Goal
+
+Monitor how a brand or domain appears in AI-generated search results across three engines:
+Google AI Overviews, Perplexity, and ChatGPT Search. Produce a visibility matrix showing
+which queries surface the target domain, in what position, and with what context.
+
+## Prerequisites
+
+Camoufox is required for Google (bot detection). Install if not available:
+
+```bash
+browse --runtime camoufox doctor
+# If not installed:
+npm install camoufox-js && npx camoufox-js fetch
+```
+
+For ChatGPT Search, a persistent browser profile with an authenticated ChatGPT session is
+required. Create one if needed:
+
+```bash
+browse --profile chatgpt --headed goto https://chatgpt.com
+# User logs in manually via headed browser
+# Profile persists cookies for future sessions
+```
+
+## Step 0: Gather inputs
+
+Before running any queries, collect from the user:
+
+1. **Target domain** — the domain to track (e.g., `example.com`)
+2. **Query list** — 3-10 brand-relevant search queries
+3. **Engines** — which engines to check (default: all three)
+
+If the user provides only a domain, suggest relevant queries based on the domain's likely
+industry and product category. Use `AskUserQuestion` to confirm the query list.
+
+## Step 1: Google AI Overviews
+
+Google AI Overviews appear at the top of search results for informational queries.
+Use camoufox with consent dismissal to avoid bot detection and cookie banners.
+
+### Navigate and extract
+
+For each query:
+
+```bash
+BROWSE_CONSENT_DISMISS=1 browse --runtime camoufox --headed goto "https://www.google.com/search?q=<url-encoded-query>"
+browse --runtime camoufox --headed wait --network-idle
+browse --runtime camoufox --headed snapshot -i
+```
+
+### Analyze results
+
+Read the snapshot output. The AI Overview section typically has an "AI Overview" label,
+expandable summary text with inline citations, and source links. If present, use
+`browse --runtime camoufox --headed text` to extract full content.
+
+For each query, record: `ai_overview_present` (yes/no), `domain_cited` (yes/no),
+`citation_position` (number or null), `citation_context` (the claim it supports),
+and `competing_domains` (other cited domains).
+
+## Step 2: Perplexity
+
+Perplexity shows AI-generated answers with numbered source citations.
+
+### Navigate and extract
+
+For each query:
+
+```bash
+browse goto "https://www.perplexity.ai/search?q=<url-encoded-query>"
+browse wait --network-idle
+browse snapshot -i
+```
+
+### Analyze results
+
+Perplexity shows numbered footnote-style citations (e.g., [1], [2]) within the answer
+and a "Sources" section with URLs. Use `browse text` for full content if needed.
+
+For each query, record: `answer_generated` (yes/no), `domain_cited` (yes/no),
+`citation_numbers` (positions referencing the target domain), `citation_context`,
+`total_citations`, and `competing_domains`.
+
+## Step 3: ChatGPT Search (authenticated)
+
+ChatGPT Search requires an authenticated session. Use a persistent profile.
+
+### Navigate and query
+
+For each query:
+
+```bash
+browse --profile chatgpt goto https://chatgpt.com
+browse --profile chatgpt snapshot -i
+```
+
+Find the input field from the snapshot, then:
+
+```bash
+browse --profile chatgpt fill <input-ref> "<query>"
+browse --profile chatgpt press Enter
+browse --profile chatgpt wait --network-idle
+```
+
+ChatGPT streams responses. Wait for output to stabilize, then snapshot:
+
+```bash
+browse --profile chatgpt wait --network-idle
+browse --profile chatgpt snapshot -i
+```
+
+If a stop/regenerate button is visible, the response is still streaming — wait and
+re-snapshot. Use `browse --profile chatgpt text` for full content extraction.
+
+### Analyze results
+
+ChatGPT Search shows inline numbered citation links and a "Sources" panel with URLs.
+
+For each query, record: `response_generated` (yes/no), `search_used` (yes/no --
+ChatGPT may answer from training data without search), `domain_cited` (yes/no),
+`citation_position` (number or null), `citation_context`, and `competing_domains`.
+
+## Step 4: Generate visibility report
+
+After running all queries across selected engines, compile the results into a
+structured report.
+
+### Visibility matrix
+
+Create a table with queries as rows and engines as columns:
+
+```
+| Query                  | Google AI Overview | Perplexity | ChatGPT Search |
+|------------------------|--------------------|------------|----------------|
+| "best <product>"       | Cited (#2)         | Cited (#1) | Not cited      |
+| "<brand> vs competitor"| No AI Overview     | Cited (#3) | Cited (#2)     |
+| "how to <task>"        | Cited (#1)         | Not cited  | Not cited      |
+```
+
+### Summary metrics
+
+Calculate and report:
+
+- **Visibility rate**: percentage of queries where the domain appears, per engine
+- **Average citation position**: mean position when cited, per engine
+- **Best-performing queries**: queries where the domain appears across multiple engines
+- **Gap queries**: queries where the domain is absent from all engines
+- **Top competing domains**: domains that appear most frequently across all queries
+
+### Recommendations
+
+Based on the findings, suggest:
+
+- Which queries have the highest AI visibility potential
+- Where competitors are cited but the target domain is not
+- Content gaps that could improve citation likelihood
+- Which engines favor the domain (focus optimization there)
+
+## Multi-query workflow
+
+When running many queries, batch by engine to minimize context switching:
+
+1. Run all queries on Google AI Overviews first (camoufox session stays warm)
+2. Run all queries on Perplexity second (no special runtime needed)
+3. Run all queries on ChatGPT Search last (authenticated profile session)
+
+Between queries on the same engine, no need to restart the browser. Navigate directly
+to the next search URL.
+
+## Important rules
+
+- **Camoufox for Google** — Google blocks regular Chromium for automated searches. Always
+  use `--runtime camoufox --headed` for Google queries.
+- **Rate limiting** — Add natural pauses between queries on the same engine. Do not run
+  more than one query every 5-10 seconds on Google. Perplexity and ChatGPT are more lenient.
+- **AI Overviews are not always present** — Google shows AI Overviews for informational
+  queries, not navigational or transactional ones. Record absence as a data point.
+- **ChatGPT may not use search** — ChatGPT sometimes answers from training data without
+  invoking web search. When no sources panel appears, record `search_used: no`.
+- **Snapshot before text** — always take a snapshot first to understand page structure,
+  then use text extraction for full content if needed.
+- **Do not fabricate results** — if a citation is ambiguous or unclear, note it as
+  uncertain rather than asserting presence or absence.
+- **Profile persistence** — the `--profile chatgpt` flag reuses cookies across sessions.
+  If the session expires, ask the user to re-authenticate via headed mode.
+
+## Limitations
+
+- **Google AI Overviews availability** — not all queries trigger AI Overviews; availability
+  varies by region and query type
+- **ChatGPT Search access** — requires a ChatGPT Plus or Team subscription with search enabled
+- **Rate limits** — aggressive querying may trigger temporary blocks on any engine
+- **Dynamic content** — AI-generated answers change over time; results represent a
+  point-in-time snapshot
+- **Image/video citations** — this workflow tracks text citations only; rich media
+  citations in AI answers are not captured