LLM USAGE GUIDE:
  Workflow: inspect -> read uids -> act (click/fill) -> inspect again.
  Headless by default. Add --stealth for bot-protected sites. Use --json for structured output.

  Quick start:
    chrome-agent goto https://example.com --inspect
    chrome-agent click n12 --inspect
    chrome-agent fill --uid n20 "hello@example.com"
    chrome-agent read                              # article content (Readability)
    chrome-agent eval "document.title"

  Stealth (bypass Cloudflare/bot detection):
    chrome-agent --stealth goto https://protected-site.com --inspect
    # Patches navigator.webdriver, chrome.runtime, UA, WebGL, input leak, skips Runtime.enable

  Logged-in sites (X.com, Gmail, dashboards — use your Chrome cookies):
    chrome-agent --stealth --copy-cookies goto x.com/home --inspect
    # Copies cookies from your real Chrome profile. No manual login needed.

  Heavy bot protection (DataDome, Kasada — when --stealth isn't enough):
    # Use your real Chrome instead of bundled Chromium:
    google-chrome --remote-debugging-port=9222 &
    chrome-agent --connect http://127.0.0.1:9222 goto https://protected-site.com --inspect
    # Real Chrome passes fingerprint checks that Chromium can't

  Targeting elements (3 modes):
    chrome-agent click n40                              # by uid from inspect
    chrome-agent click --selector "button.submit"      # by CSS selector
    chrome-agent click --xy 100,200                    # by coordinates
    chrome-agent fill --uid n20 "value"                 # fill by uid
    chrome-agent fill --selector "input[name=q]" "val" # fill by CSS selector

  Inspection + filtering:
    chrome-agent inspect                               # full accessibility tree
    chrome-agent inspect --max-depth 2                 # limit depth (saves tokens)
    chrome-agent inspect --filter "button,link"        # only these roles (flat list)
    chrome-agent inspect --uid n50                     # subtree only
    chrome-agent inspect --filter "article" --scroll --limit 50  # infinite scroll (X.com, feeds)

  Content extraction (choose the right tool):
    chrome-agent read                                  # article/main content (Readability)
    chrome-agent read --truncate 1000                  # capped at N chars
    chrome-agent text --selector "main" --truncate 500 # visible text of CSS-matched element
    chrome-agent text                                  # full page innerText (verbose)
    chrome-agent extract                                # auto-detect repeating data (tables, cards, lists)
    chrome-agent extract --scroll                      # scroll first for lazy-loaded pages (YouTube, Pinterest)
    chrome-agent extract --a11y --scroll --limit 20    # React SPAs (X.com) -- uses a11y tree, not DOM
    chrome-agent eval "JSON.stringify(...)"            # structured data via JS
    chrome-agent eval --selector "h1" "el.textContent" # eval scoped to a CSS element (el = matched)
    chrome-agent network --filter "api" --body         # intercept API responses directly
    chrome-agent console --level error                 # see JS errors from the page

  Network capture ("Readability for APIs"):
    chrome-agent network                               # resources already loaded (stealth-safe)
    chrome-agent network --filter "graphql" --body     # filter + response bodies
    chrome-agent network --live 5 --body               # capture live traffic for 5 seconds

  Console capture (stealth-safe):
    chrome-agent console                               # all messages
    chrome-agent console --level error                 # errors + exceptions only

  Pipe mode (persistent connection, 10x faster):
    echo '{"cmd":"goto","url":"https://example.com","inspect":true}' | chrome-agent pipe
    # Returns one JSON line per command: {"ok":true,...}

  Navigation:
    chrome-agent goto https://example.com              # navigate
    chrome-agent goto https://spa.com --wait-for "main" # wait for selector after nav
    chrome-agent back                                  # history.back()
    chrome-agent scroll down                           # scroll page
    chrome-agent wait text "Success"                   # wait for content

  Multi-tab:
    chrome-agent --page tab2 goto https://other.com
    chrome-agent --page tab2 inspect

  Parallel agents (avoid session conflicts):
    chrome-agent --browser agent1 goto https://example.com  # isolated browser per agent
    chrome-agent --browser agent2 goto https://other.com    # separate Chrome instance

  JSON mode:
    chrome-agent --json goto https://example.com
    -> {"ok":true,"url":"...","title":"..."}
    Errors: {"ok":false,"error":"...","hint":"..."} (exit 0, always parseable)

  Cleanup:
    chrome-agent close                                 # stop browser
    chrome-agent close --purge                         # stop + delete cookies/profile

  Important tips:
    - Use --stealth on sites with bot protection (Cloudflare, Turnstile).
    - UIDs (n47, n123) are stable across inspects on the same page.
    - After SPA navigation (back, click that triggers route change), re-inspect — UIDs change.
    - For SPA product pages, prefer `goto <direct-url>` over `click` (avoids modal routing).
    - Use `read` for articles/blogs, `text --selector` for scoped extraction, `eval` for structured data.
    - Prefer inspect over screenshot (~50 vs ~100K tokens).
    - --max-depth works on goto/click/fill --inspect too (not just standalone inspect).
    - --filter gives a flat list — great for finding interactive elements quickly.
