octocode-cli 1.3.1 → 1.5.1

package/skills/octocode-chrome-devtools/references/CHROME_FLAGS.md

@@ -0,0 +1,234 @@
+# Chrome Flags Reference
+
+
+## User-Agent override
+
+`open-browser.mjs` does not override Chrome's user-agent by default. Add `--userAgent` only when the task needs a specific browser/device signature:
+
+```
+Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/<current-version>.0.0.0 Safari/537.36
+```
+
+```bash
+node <skill-dir>/scripts/open-browser.mjs --headless \
+  --userAgent "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/<current-version>.0.0.0 Safari/537.36"
+```
+
+Use a current version string that matches the installed browser when possible. A stale or cross-platform UA can be more fingerprintable than Chrome's default.
+
+
+## Headless mode flags (inspection default)
+Applied by `open-browser.mjs --headless`:
+
+| Flag | Purpose |
+|------|---------|
+| `--remote-debugging-port=9222` | Enable CDP WebSocket on this port |
+| `--headless=new` | Modern headless mode (Chrome 112+) — no visible window |
+| `--user-data-dir=<tmpdir>/cdp-chrome-profile-9222` | Isolated temp profile — no user data read/written |
+| `--disable-gpu` | Required for headless on many systems |
+| `--disable-dev-shm-usage` | Prevents /dev/shm exhaustion in containers |
+| `--no-sandbox` | Required for headless in some Linux/CI environments |
+| `--no-first-run` | Skip Chrome's first-run setup dialog |
+| `--no-default-browser-check` | Skip "make Chrome default" prompt |
+| `--disable-background-mode` | Prevent Chrome from staying alive as a background app |
+| `--user-agent=<ua>` | Optional UA override for specific compatibility or emulation tasks |
+
+## Visible mode flags (user-requested only)
+Applied when NOT headless (user says "show me", "open in my browser", "I want to see the page", "keep it open", "interactive"):
+
+| Flag | Purpose |
+|------|---------|
+| `--remote-debugging-port=9222` | Enable CDP WebSocket |
+| `--user-data-dir=<real-profile>` | Uses the user's real Chrome profile only when Chrome is not already running without CDP |
+| `--profile-directory=Default` | Which profile to open when real-profile reuse is possible |
+| `--restore-last-session` | Restore previous tabs when real-profile reuse is possible |
+
+If Chrome is already running without CDP, `open-browser.mjs` launches an isolated visible CDP profile and returns `"isolated": true`. Existing cookies/extensions will not be available; complete auth in that visible CDP window, or close Chrome first if real-profile reuse is required.
+
+## Mobile / viewport emulation
+
+Mobile emulation works at **two levels** — always prefer the script level for full accuracy:
+
+| Level | Flag / Method | Controls | Accuracy |
+|---|---|---|---|
+| **Launch-level** | `open-browser.mjs --windowSize 390x844` | Initial OS window size only — does **not** set `window.innerWidth` in `headless=new` (Chrome 112+) | Unreliable for viewport — no DPR, no touch |
+| **Script-level** | `Emulation.setDeviceMetricsOverride` + `setTouchEmulationEnabled` + `setUserAgentOverride` | Viewport, DPR, mobile mode, touch events, UA + Sec-CH-UA hints | Full |
+
+**Launch-level usage** (sets window before CDP attaches — optional, good for screenshots):
+```bash
+# Mobile window size
+node <skill-dir>/scripts/open-browser.mjs --headless --windowSize 390x844
+
+# Custom desktop size
+node <skill-dir>/scripts/open-browser.mjs --headless --windowSize 1440x900
+
+# Mobile window + mobile UA at launch
+node <skill-dir>/scripts/open-browser.mjs --headless --windowSize 390x844 \
+  --userAgent "Mozilla/5.0 (iPhone; CPU iPhone OS 17_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4 Mobile/15E148 Safari/604.1"
+```
+
+**`--windowSize` does not set `window.innerWidth` in `headless=new`** (Chrome 112+). The OS window size and the page viewport are decoupled in modern headless mode. For any test that reads `window.innerWidth`, `window.innerHeight`, or uses CSS media queries, you must use the script-level approach.
+
+For real mobile emulation (media queries, touch, DPR, Sec-CH-UA), always use the script-level CDP calls from `INTENTS_ENVIRONMENT.md` -> `## emulate`. Launch flags alone are **not enough**.
+
+
+## Optional flags for special scenarios
+Pass these via a custom launch call when needed:
+
+| Flag | When to use |
+|------|------------|
+| `--disable-web-security` | Cross-origin testing (use only on isolated profiles) |
+| `--allow-running-insecure-content` | Test mixed HTTP/HTTPS scenarios |
+| `--ignore-certificate-errors` | Test self-signed cert environments |
+| `--proxy-server=<host:port>` | Route traffic through a proxy |
+| `--window-size=W,H` | Initial window dimensions (use via `--windowSize` in open-browser.mjs) |
+| `--force-dark-mode` | Test dark-mode rendering |
+| `--lang=<locale>` | Test localisation (e.g. `--lang=fr`) |
+| `--disable-extensions` | Clean run without user extensions |
+| `--incognito` | No persistent state — good for auth flow testing |
+
+## Proxy Routing
+
+Chrome can route traffic only through an already-configured proxy endpoint (HTTP/SOCKS/PAC), not directly into a VPN account. Use this only when the user provides or already runs a proxy.
+
+```bash
+node <skill-dir>/scripts/open-browser.mjs --headless \
+  --proxyServer "socks5://127.0.0.1:1080" \
+  --proxyBypassList "<-loopback>"
+
+node <skill-dir>/scripts/open-browser.mjs --headless \
+  --proxyPacUrl "http://127.0.0.1:3128/proxy.pac"
+```
+
+Proxy settings only apply when Chrome is launched fresh. If output has `"reused": true` and `"proxyRequested": true`, cleanup the tracked session first or use a different `--port`; Chrome cannot apply new proxy flags to an already-running CDP session.
+
+Config shape for `<repo>/.octocode/chrome-devtools.json` or global `chromeDevtools.proxy`:
+
+```json
+{
+  "proxy": {
+    "enabled": true,
+    "server": "socks5://127.0.0.1:1080",
+    "bypassList": "<-loopback>"
+  }
+}
+```
+
+## Chrome binary paths per platform
+
+`open-browser.mjs` auto-detects Chrome. If detection fails, pass `--chromePath`:
+
+| Platform | Default paths checked |
+|----------|-----------------------|
+| macOS | `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`, `/Applications/Chromium.app/Contents/MacOS/Chromium` |
+| Linux | `google-chrome`, `google-chrome-stable`, `chromium-browser`, `chromium` (searched in `$PATH`) |
+| Windows | `C:\Program Files\Google\Chrome\Application\chrome.exe`, `C:\Program Files (x86)\Google\Chrome\Application\chrome.exe` |
+
+```bash
+# macOS/Linux — override path
+node <skill-dir>/scripts/open-browser.mjs --headless --chromePath "/usr/bin/chromium-browser"
+
+# Windows PowerShell — override path
+node <skill-dir>/scripts/open-browser.mjs --headless --chromePath "C:\Program Files\Google\Chrome\Application\chrome.exe"
+```
+
+**Linux/CI notes:**
+- `--no-sandbox` is required when running as root or inside Docker
+- `--disable-dev-shm-usage` prevents crashes in low-memory containers
+- For Chromium in CI: install with `apt-get install -y chromium-browser` (Ubuntu/Debian)
+
+**Mode decision** → see `SKILL.md` → Open Browser.
+
+---
+
+## Shell Examples
+
+Set these once in bash/zsh examples:
+
+```bash
+SKILL_DIR=<skill-dir>
+TMPDIR=$(node -e "process.stdout.write(require('os').tmpdir())")
+PORT=9222
+```
+
+Cleanup when a headless or isolated CDP session is no longer needed:
+
+```bash
+node "$SKILL_DIR/scripts/open-browser.mjs" --port "$PORT" --cleanup
+```
+
+Windows equivalents for the common command shape:
+
+```powershell
+# PowerShell
+$SKILL_DIR = "<skill-dir>"
+$TMPDIR    = node -e "process.stdout.write(require('os').tmpdir())"
+node "$SKILL_DIR\scripts\open-browser.mjs" --headless --port 9222
+node "$SKILL_DIR\scripts\cdp-sandbox.mjs" "$TMPDIR\cdp-task.mjs" --new-tab "about:blank" `
+  > "$TMPDIR\cdp-output-task.txt" 2>&1
+```
+
+```cmd
+SET SKILL_DIR=<skill-dir>
+FOR /F "delims=" %%i IN ('node -e "process.stdout.write(require('os').tmpdir())"') DO SET TMPDIR=%%i
+node "%SKILL_DIR%\scripts\open-browser.mjs" --headless --port 9222
+node "%SKILL_DIR%\scripts\cdp-sandbox.mjs" "%TMPDIR%\cdp-task.mjs" --new-tab "about:blank" ^
+  > "%TMPDIR%\cdp-output-task.txt" 2>&1
+```
+
+### One-pass inspection — headless
+
+```bash
+node "$SKILL_DIR/scripts/open-browser.mjs" --headless --port "$PORT"
+# save the selected intent/pattern script to "$TMPDIR/cdp-task.mjs"
+node "$SKILL_DIR/scripts/cdp-sandbox.mjs" "$TMPDIR/cdp-task.mjs" \
+  --port "$PORT" --new-tab "about:blank" \
+  > "$TMPDIR/cdp-output-task.txt" 2>&1
+```
+
+Use this for network, console, performance, memory, security, screenshot, and most audit scripts. Analyze the prefixes requested by that intent, for example `[NETWORK_ERROR]`, `[CONSOLE:ERROR]`, `[EXCEPTION]`, `[PERFORMANCE]`, `[FINDING]`.
+
+### Visible browser / live page
+
+```bash
+node "$SKILL_DIR/scripts/open-browser.mjs" --url "https://site.com" --port "$PORT"
+# after the user interacts, save an on-demand script to "$TMPDIR/cdp-live-check.mjs"
+node "$SKILL_DIR/scripts/cdp-sandbox.mjs" "$TMPDIR/cdp-live-check.mjs" \
+  --port "$PORT" --target-url "site.com" --keep-tab \
+  > "$TMPDIR/cdp-output-live-check.txt" 2>&1
+```
+
+### User login -> authenticated follow-up
+
+Browser must be visible. Ask before using the real profile.
+
+```bash
+node "$SKILL_DIR/scripts/open-browser.mjs" --profile Default --port "$PORT"
+# save the user-auth script from INTENTS_AUTH.md to "$TMPDIR/cdp-user-auth.mjs"
+node "$SKILL_DIR/scripts/cdp-sandbox.mjs" "$TMPDIR/cdp-user-auth.mjs" \
+  --port "$PORT" --new-tab "about:blank" --keep-tab \
+  > "$TMPDIR/cdp-auth-output.txt" 2>&1
+# after [AUTH_COMPLETE], run debug/scrape/security scripts on the same port
+```
+
+### Inspect iframes and service workers
+
+```bash
+node "$SKILL_DIR/scripts/cdp-sandbox.mjs" --list-targets --port "$PORT"
+node "$SKILL_DIR/scripts/cdp-sandbox.mjs" "$TMPDIR/cdp-task.mjs" \
+  --port "$PORT" --target-url "iframe-url-pattern"
+node "$SKILL_DIR/scripts/cdp-sandbox.mjs" "$TMPDIR/cdp-task.mjs" \
+  --port "$PORT" --target-type service_worker
+```
+
+### Mobile / responsive layout
+
+```bash
+node "$SKILL_DIR/scripts/open-browser.mjs" --headless --port "$PORT" \
+  --windowSize 390x844 \
+  --userAgent "Mozilla/5.0 (iPhone; CPU iPhone OS 17_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4 Mobile/15E148 Safari/604.1"
+# still set script-level emulation in the CDP script for viewport/DPR/touch accuracy
+node "$SKILL_DIR/scripts/cdp-sandbox.mjs" "$TMPDIR/cdp-emulate.mjs" \
+  --port "$PORT" --new-tab "about:blank" \
+  > "$TMPDIR/cdp-output-emulate.txt" 2>&1
+```

package/skills/octocode-chrome-devtools/references/INTENTS.md

@@ -0,0 +1,108 @@
+# CDP Intent Router
+
+Use this file to choose intent(s) and load only the matching detail file. Do not load every intent detail file by default.
+
+## Loading Rule
+
+1. Pick one to three intents from the index below.
+2. Load only the detail file(s) listed for those intents.
+3. If a detail section points to `SCRIPT_PATTERNS.md`, load only the named pattern.
+4. Enable the union of required domains, attach listeners before navigation/action, then run the focused script.
+5. For exact CDP params/events, verify `CDP_AGENT_REFERENCE.md` or the official per-domain protocol page.
+6. Treat code snippets as adaptable examples. Verify current Web APIs and feature-detect inside the page before using optional browser APIs.
+
+## Combining Intents
+
+Intents are composable. Most real tasks need 2-3 combined. Enable the **union of domains** for all selected intents and merge their event listeners.
+
+| Common combination | Intents | When to use |
+|---|---|---|
+| Automate + debug | `automate` + `debug` | "do X and tell me what breaks" |
+| Login + network | `login` + `network` | "log in and capture what API calls are made" |
+| Login + security | `login` + `security` | "log in and audit cookies/tokens after auth" |
+| User-auth + scrape | `user-auth` + `scrape` | "let me sign in, then extract data from the authenticated page" |
+| User-auth + debug | `user-auth` + `debug` | "let me sign in, then investigate what is breaking after auth" |
+| User-auth + security | `user-auth` + `security` | "let me sign in, then audit the session tokens and cookies" |
+| Automate + screenshot | `automate` + `screenshot` | "fill the form and take a screenshot of the result" |
+| Automate + performance | `automate` + `performance` | "click through the flow and measure render time" |
+| Scrape + emulate | `scrape` + `emulate` | "extract data as mobile viewport" |
+| Debug + security | `debug` + `security` | "investigate the crash and check what tokens are exposed" |
+| Inject + debug | `inject` + `debug` | "patch the function before load, then observe behavior" |
+| Full audit | all of the above | "audit everything" |
+
+When combining: enable all required domains first, attach all event listeners, then navigate/interact, then run inspection checks.
+
+## Detail Files
+
+| File | Intents | Load when |
+|---|---|---|
+| `INTENTS_DEBUG.md` | `debug`, `network`, `console`, `performance`, `memory`, `dom`, `css-coverage`, `js-coverage` | Load this file when the selected intent is about errors, diagnostics, performance, DOM/CSS inspection, or code coverage. |
+| `INTENTS_INSPECT.md` | `security`, `websocket`, `service-worker`, `workers`, `intercept`, `screenshot`, `accessibility`, `supply-chain`, `full-audit` | Load this file when the selected intent targets browser subsystems, capture surfaces, security, workers, request interception, or full audits. |
+| `INTENTS_AUTOMATION.md` | `automate`, `scrape`, `live-page` | Load this file when the selected intent needs browser interaction, scraping, or a live user-driven page. |
+| `INTENTS_AUTH.md` | `login`, `user-auth` | Load this file when the selected intent needs login automation, manual user authentication, or an authenticated browser session. |
+| `INTENTS_ENVIRONMENT.md` | `emulate`, `inject`, `monitor` | Load this file when the selected intent changes browser environment, injects instrumentation, or monitors a page over time. |
+| `INTENTS_STORAGE_CONSENT.md` | `storage`, `consent` | Load this file when the selected intent audits browser storage, cookies, tokens, quotas, service-worker state, or consent/tracker behavior. |
+
+## Intent Index
+
+| User says... | Intent | Details |
+|---|---|---|
+| debug, what's wrong, broken, fix this, investigate, agent loop, observe, why is X not working | `debug` | [INTENTS_DEBUG.md#debug](INTENTS_DEBUG.md#debug) |
+| automate, do X, click, type, fill, submit, flow, interact, perform steps | `automate` | [INTENTS_AUTOMATION.md#automate](INTENTS_AUTOMATION.md#automate) |
+| login, sign in, authenticate, enter credentials, log me in | `login` | [INTENTS_AUTH.md#login](INTENTS_AUTH.md#login) |
+| let me log in myself, I'll auth, manual login, open browser so I can sign in, auth flow, open visible browser, I need to authenticate first | `user-auth` | [INTENTS_AUTH.md#user-auth](INTENTS_AUTH.md#user-auth) |
+| scrape, extract, collect data, pull content, harvest | `scrape` | [INTENTS_AUTOMATION.md#scrape](INTENTS_AUTOMATION.md#scrape) |
+| emulate, mobile, device, throttle, offline, slow network, geolocation | `emulate` | [INTENTS_ENVIRONMENT.md#emulate](INTENTS_ENVIRONMENT.md#emulate) |
+| inject, patch, override, hook, intercept before load, monkey-patch | `inject` | [INTENTS_ENVIRONMENT.md#inject](INTENTS_ENVIRONMENT.md#inject) |
+| monitor, watch, poll, check every N seconds, keep watching | `monitor` | [INTENTS_ENVIRONMENT.md#monitor](INTENTS_ENVIRONMENT.md#monitor) |
+| network, requests, 4xx, API calls, traffic | `network` | [INTENTS_DEBUG.md#network](INTENTS_DEBUG.md#network) |
+| console, errors, exceptions, crashes, JS error | `console` | [INTENTS_DEBUG.md#console](INTENTS_DEBUG.md#console) |
+| slow, performance, metrics, long task, fps, render | `performance` | [INTENTS_DEBUG.md#performance](INTENTS_DEBUG.md#performance) |
+| memory, leak, heap, detached nodes, retained | `memory` | [INTENTS_DEBUG.md#memory](INTENTS_DEBUG.md#memory) |
+| DOM, elements, structure, HTML, rendering | `dom` | [INTENTS_DEBUG.md#dom](INTENTS_DEBUG.md#dom) |
+| CSS, styles, unused rules, coverage | `css-coverage` | [INTENTS_DEBUG.md#css-coverage](INTENTS_DEBUG.md#css-coverage) |
+| JS coverage, dead code, unused functions | `js-coverage` | [INTENTS_DEBUG.md#js-coverage](INTENTS_DEBUG.md#js-coverage) |
+| security, cookies, tokens, headers, CSP, exfil | `security` | [INTENTS_INSPECT.md#security](INTENTS_INSPECT.md#security) |
+| websocket, WS, real-time, socket frames | `websocket` | [INTENTS_INSPECT.md#websocket](INTENTS_INSPECT.md#websocket) |
+| service worker, SW lifecycle, cache, offline, PWA worker | `service-worker` | [INTENTS_INSPECT.md#service-worker](INTENTS_INSPECT.md#service-worker) |
+| web worker, shared worker, worker thread, background thread | `workers` | [INTENTS_INSPECT.md#workers](INTENTS_INSPECT.md#workers) |
+| intercept, mock, block, fake response, modify request | `intercept` | [INTENTS_INSPECT.md#intercept](INTENTS_INSPECT.md#intercept) |
+| screenshot, capture, visual, PDF, print | `screenshot` | [INTENTS_INSPECT.md#screenshot](INTENTS_INSPECT.md#screenshot) |
+| accessibility, a11y, aria, screen reader | `accessibility` | [INTENTS_INSPECT.md#accessibility](INTENTS_INSPECT.md#accessibility) |
+| third-party, external scripts, CDN, supply chain | `supply-chain` | [INTENTS_INSPECT.md#supply-chain](INTENTS_INSPECT.md#supply-chain) |
+| full audit, all checks, everything | `full-audit` | [INTENTS_INSPECT.md#full-audit](INTENTS_INSPECT.md#full-audit) |
+| storage, cookies, localStorage, sessionStorage, IndexedDB, quota, cache state | `storage` | [INTENTS_STORAGE_CONSENT.md#storage](INTENTS_STORAGE_CONSENT.md#storage) |
+| consent, GDPR, privacy banner, tracker pre-firing, pre-consent cookies | `consent` | [INTENTS_STORAGE_CONSENT.md#consent](INTENTS_STORAGE_CONSENT.md#consent) |
+| open page, browse with monitoring, watch this page, live check, open and monitor, open and inspect | `live-page` | [INTENTS_AUTOMATION.md#live-page](INTENTS_AUTOMATION.md#live-page) |
+
+## Output Prefix Reference
+
+| Prefix | Intent categories | Meaning |
+|---|---|---|
+| `[NETWORK]` | network, security, supply-chain, websocket | HTTP request/response |
+| `[NETWORK_ERROR]` | network, security | 4xx/5xx status |
+| `[NETWORK_FAILED]` | network | Blocked/failed request |
+| `[CONSOLE:ERROR]` | console | `console.error()` call |
+| `[CONSOLE:WARN]` | console | `console.warn()` call |
+| `[EXCEPTION]` | console | Uncaught JS exception |
+| `[EXCEPTION_LOCATION]` | console | Stack frame of exception |
+| `[LOG:ERROR]` | console | Browser Log domain error |
+| `[PERFORMANCE]` | performance, memory | Metric value |
+| `[DOM]` | dom, accessibility | DOM structure info |
+| `[CSS]` | css-coverage | CSS rule info |
+| `[SECURITY]` | security, supply-chain | Security-specific finding |
+| `[METRIC]` | all | Summary count or measurement |
+| `[SCREENSHOT]` | screenshot | Path to saved file |
+| `[FINDING]` | all | Actionable issue — emit for user-relevant findings |
+| `[AUTOMATE]` | automate, login | Step executed in a flow |
+| `[AUTH]` | user-auth | Auth polling status update (progress line) |
+| `[AUTH_COMPLETE]` | user-auth | Authentication detected — agent may proceed |
+| `[AUTH_TIMEOUT]` | user-auth | Timed out waiting for auth — agent must handle |
+| `[SCRAPE]` | scrape | Extracted data item |
+| `[REASON]` | scrape, automate, debug | Why this step/result leads to the next step |
+| `[EMULATE]` | emulate | Environment override active |
+| `[INJECT]` | inject | Script injected into document |
+| `[MONITOR]` | monitor | State snapshot from polling loop |
+| `[SW]` | service-worker | Service Worker lifecycle event or state |
+| `[WORKER]` | workers | Worker target attached or event from worker session |
+| `[ACTION]` | debug, automate | Concrete next step for agent or developer |

package/skills/octocode-chrome-devtools/references/INTENTS_AUTH.md

@@ -0,0 +1,179 @@
+# CDP Auth Intent Details
+
+## login
+
+**Trigger phrases:** "login", "sign in", "log me in", "authenticate", "enter credentials", "fill the login form", "auth flow"
+
+**Purpose:** Automate an authentication flow — navigate to login page, fill credentials, submit, verify auth success, capture session state. Combine with `security` to audit what tokens/cookies are set post-login.
+
+**Domains:** `Page.enable`, `Runtime.enable`, `Network.enable`
+
+**Key steps:**
+1. Navigate to login URL
+2. Wait for username/password fields
+3. Fill credentials via `Runtime.evaluate` with real `input` + `change` events
+4. Click submit or press Enter
+5. Wait for redirect / dashboard element
+6. Verify logged-in state
+7. Optionally inventory auth cookie names and storage-token presence (combine with `security`)
+
+**Selector discovery — when selectors are unknown:**
+```js
+// Find likely username field
+const { result } = await cdp.send('Runtime.evaluate', {
+  expression: `document.querySelector('input[type="email"], input[type="text"], input[name*="user"], input[name*="email"], input[id*="user"], input[id*="email"]')?.name`,
+  returnByValue: true,
+});
+
+// Find likely password field
+// input[type="password"] — usually the most reliable password selector
+```
+
+**Credential injection pattern (triggers React/Vue/framework state):**
+```js
+async function fillField(cdp, selector, value) {
+  await cdp.send('Runtime.evaluate', {
+    expression: `
+      const el = document.querySelector(${JSON.stringify(selector)});
+      const nativeInputValueSetter = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, 'value').set;
+      nativeInputValueSetter.call(el, ${JSON.stringify(value)});
+      el.dispatchEvent(new Event('input', { bubbles: true }));
+      el.dispatchEvent(new Event('change', { bubbles: true }));
+    `
+  });
+  console.log(\`[AUTOMATE] filled ${selector}\`);
+}
+```
+
+**Post-login verification:**
+```js
+// Check URL changed (redirect after login)
+const { result: url } = await cdp.send('Runtime.evaluate', { expression: 'location.href', returnByValue: true });
+console.log(`[AUTOMATE] post-login URL: ${url.value}`);
+
+// Check for auth cookie
+const { cookies } = await cdp.send('Network.getAllCookies', {});
+const authCookie = cookies.find(c => /session|token|auth/i.test(c.name));
+if (authCookie) console.log(`[AUTOMATE] auth cookie set: ${authCookie.name}`);
+else console.log('[FINDING] NO_AUTH_COOKIE: no session/token cookie after login');
+
+// Check localStorage for token
+const { result: token } = await cdp.send('Runtime.evaluate', {
+  expression: `!!(localStorage.getItem('token') || localStorage.getItem('authToken') || localStorage.getItem('jwt'))`,
+  returnByValue: true,
+});
+if (token.value) console.log('[AUTOMATE] token present in localStorage (value redacted)');
+```
+
+**`[FINDING]` conditions:**
+- Login form not found → `[FINDING] LOGIN_FORM_NOT_FOUND: no username/password fields on ${url}`
+- No redirect after submit → `[FINDING] LOGIN_NO_REDIRECT: URL unchanged after submit`
+- Error message visible → `[FINDING] LOGIN_FAILED: error element present — "${errorText}"`
+- No auth cookie and no token in storage → `[FINDING] NO_SESSION: login appeared to succeed but no session established`
+- Auth request returned non-200 → `[FINDING] AUTH_HTTP_ERROR: ${status} on ${url}`
+
+**Combine with:** `security` (audit tokens post-login), `network` (capture auth API calls), `debug` (catch login errors).
+
+## user-auth
+
+**Trigger phrases:** "let me log in myself", "I'll authenticate", "manual login", "open browser so I can sign in", "auth flow", "open visible browser", "I need to authenticate first", "let me sign in then scrape", "open browser non-headless for auth"
+
+**Purpose:** Opens Chrome in **visible** mode (never headless), navigates to the login URL, then polls passively for authentication completion while the user completes any auth flow (password, 2FA, SSO, CAPTCHA, OAuth). Once auth is detected the browser **stays open** so all subsequent CDP scripts reuse the authenticated session.
+
+**Key distinction from `login`:**
+- `login` = agent injects credentials programmatically via CDP
+- `user-auth` = user completes auth manually; agent waits and detects completion
+
+**Key requirement:** Browser must be visible for the user to interact — do not pass `--headless` to `open-browser.mjs` for this intent.
+
+**Domains required:** `Network`, `Page`, `Runtime`
+
+**Critical flags:**
+- `open-browser.mjs` → omit `--headless` (default is already non-headless; just don't add it)
+- `cdp-sandbox.mjs` → add `--keep-tab` so the tab and session stay open after the script exits
+- Do NOT call `cleanup()` in `run()` — the browser must stay alive for subsequent tasks
+
+
+
+**Adaptive user-auth recipe:**
+
+Use visible Chrome and keep the tab alive. Poll configurable signals and report names/booleans only, never cookie or token values.
+
+```js
+export async function run(cdp) {
+  const LOGIN_URL = 'https://example.com/login';
+  const POST_AUTH_PATTERN = '/dashboard';
+  const AUTH_COOKIE_NAME = ''; // optional exact cookie name
+  const TIMEOUT_MS = 120_000;
+
+  await cdp.send('Network.enable', {});
+  await cdp.send('Runtime.enable', {});
+  await cdp.send('Page.enable', {});
+  await cdp.send('Page.navigate', { url: LOGIN_URL });
+
+  async function state() {
+    const { result } = await cdp.send('Runtime.evaluate', {
+      expression: `JSON.stringify({
+        url: location.href,
+        storageKeys: [...Object.keys(localStorage), ...Object.keys(sessionStorage)]
+          .filter(k => /token|auth|jwt|session/i.test(k))
+      })`,
+      returnByValue: true,
+    });
+    const page = JSON.parse(result.value || '{}');
+    const { cookies } = await cdp.send('Network.getAllCookies', {});
+    const authCookies = cookies.filter(c => AUTH_COOKIE_NAME ? c.name === AUTH_COOKIE_NAME : /session|token|auth|jwt|sid/i.test(c.name));
+    return { page, cookieNames: authCookies.map(c => c.name) };
+  }
+
+  const deadline = Date.now() + TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    const s = await state();
+    if ((POST_AUTH_PATTERN && s.page.url?.includes(POST_AUTH_PATTERN)) || s.cookieNames.length || s.page.storageKeys?.length) {
+      console.log(`[AUTH_COMPLETE] url=${s.page.url} cookies=${s.cookieNames.join(',') || 'none'} storageKeys=${s.page.storageKeys?.join(',') || 'none'}`);
+      return;
+    }
+    console.log(`[AUTH] waiting url=${s.page.url}`);
+    await new Promise(r => setTimeout(r, 2000));
+  }
+  console.log('[AUTH_TIMEOUT] authentication not detected; tune POST_AUTH_PATTERN or AUTH_COOKIE_NAME');
+}
+```
+
+Tune detection to the app. Prefer a post-login URL or exact cookie name over broad token heuristics when false positives are possible.
+
+**Agent loop contract:**
+
+```
+REASON   → need authenticated session before running scrape / debug / security tasks
+OPEN     → open-browser.mjs --profile Default --port 9222   ← NO --headless
+WAIT     → run user-auth script with --keep-tab
+           watch stdout for [AUTH_COMPLETE] or [AUTH_TIMEOUT]
+CONTINUE → once [AUTH_COMPLETE], run subsequent scripts on the same port/session
+REUSE    → Chrome stays open; subsequent scripts connect without re-authenticating
+STOP WHEN: [AUTH_COMPLETE] emitted (or [AUTH_TIMEOUT] — handle appropriately)
+```
+
+**Shell shape:**
+```bash
+node "$SKILL_DIR/scripts/open-browser.mjs" --profile Default --port 9222
+node "$SKILL_DIR/scripts/cdp-sandbox.mjs" "$TMPDIR/cdp-user-auth.mjs" \
+  --new-tab "about:blank" --keep-tab \
+  > "$TMPDIR/cdp-auth-output.txt" 2>&1
+# After [AUTH_COMPLETE], run follow-up scripts on the same port.
+```
+
+**Combine with:** `scrape` (extract authenticated data), `security` (audit session tokens after login), `debug` (investigate auth-gated behavior), `network` (capture post-auth API calls).
+
+**Auth detection signals (in precedence order):**
+1. URL changes to `POST_AUTH_PATTERN` (most reliable — redirect after login)
+2. Auth cookie set (name matches `/session|token|auth|jwt|sid/i` or `AUTH_COOKIE_NAME`)
+3. `localStorage` / `sessionStorage` token key present
+
+**Tuning guide:**
+| Situation | Fix |
+|---|---|
+| `[AUTH_TIMEOUT]` — login redirects to subdomain | change `POST_AUTH_PATTERN` to a path fragment, not full URL |
+| `[AUTH_TIMEOUT]` — SSO/SAML takes longer than 2 min | increase `TIMEOUT_MS` to `300_000` |
+| False positive detection | set `AUTH_COOKIE_NAME` to the exact cookie set on your app |
+| Already logged in in the CDP-controlled session | script auto-detects and emits `[AUTH_COMPLETE]` immediately |