@browserless.io/mcp 1.6.0

package/build/src/resources/api-docs.js

@@ -0,0 +1,54 @@
+export function registerApiDocsResource(server, config) {
+    server.addResource({
+        uri: 'browserless://api-docs',
+        name: 'Browserless API Documentation',
+        mimeType: 'text/markdown',
+        async load() {
+            return {
+                text: [
+                    '# Browserless Smart Scraper API',
+                    '',
+                    '## Endpoint',
+                    `POST ${config.browserlessApiUrl}/smart-scrape`,
+                    '',
+                    '## Authentication',
+                    'Pass your API token as the `token` query parameter or via the `Authorization: Bearer <token>` header.',
+                    '',
+                    '## Request Body',
+                    '```json',
+                    '{',
+                    '  "url": "https://example.com",',
+                    '  "formats": ["markdown", "screenshot"]',
+                    '}',
+                    '```',
+                    '',
+                    '## Parameters',
+                    '- **url** (required): The URL to scrape. Must use http or https protocol.',
+                    '- **formats** (optional, default: `["html"]`): Output formats to include in the response.',
+                    '  - `"markdown"` – page content converted to markdown',
+                    '  - `"html"` – cleaned HTML (returned by default in `content`)',
+                    '  - `"screenshot"` – full-page PNG screenshot as base64 (forces browser strategy)',
+                    '  - `"pdf"` – PDF of the page as base64 (forces browser strategy)',
+                    '  - `"links"` – list of links extracted from the page',
+                    '',
+                    '## Response',
+                    'Returns JSON with fields: ok, statusCode, content, contentType, headers, strategy, attempted, message, screenshot, pdf, markdown, links.',
+                    '',
+                    '## Scraping Strategies',
+                    'The smart scraper automatically cascades through multiple strategies:',
+                    '1. HTTP fetch (fast, no browser)',
+                    '2. HTTP fetch with proxy',
+                    '3. Headless browser',
+                    '4. Headless browser with captcha solving',
+                    '',
+                    'When `screenshot` or `pdf` is in formats, a browser strategy is forced.',
+                    'The response includes which strategy succeeded and which were attempted.',
+                    '',
+                    '## Documentation',
+                    '- [Browserless Docs](https://docs.browserless.io/)',
+                    '- [REST APIs](https://docs.browserless.io/rest-apis/intro)',
+                ].join('\n'),
+            };
+        },
+    });
+}

package/build/src/resources/status.d.ts

@@ -0,0 +1,3 @@
+import type { FastMCP } from 'fastmcp';
+import type { McpConfig } from '../@types/types.js';
+export declare function registerStatusResource(server: FastMCP, config: McpConfig): void;

package/build/src/resources/status.js

@@ -0,0 +1,30 @@
+import { createApiClient } from '../lib/api-client.js';
+export function registerStatusResource(server, config) {
+    server.addResource({
+        uri: 'browserless://status',
+        name: 'Browserless Service Status',
+        mimeType: 'application/json',
+        async load() {
+            const { browserlessToken } = config;
+            if (!browserlessToken) {
+                return {
+                    text: JSON.stringify({
+                        apiUrl: config.browserlessApiUrl,
+                        ok: false,
+                        message: 'No BROWSERLESS_TOKEN configured. For HTTP: pass Authorization header.',
+                        timestamp: new Date().toISOString(),
+                    }, null, 2),
+                };
+            }
+            const client = createApiClient({ ...config, browserlessToken });
+            const status = await client.getStatus();
+            return {
+                text: JSON.stringify({
+                    apiUrl: config.browserlessApiUrl,
+                    ...status,
+                    timestamp: new Date().toISOString(),
+                }, null, 2),
+            };
+        },
+    });
+}

package/build/src/skills/autonomous-login.md

@@ -0,0 +1,95 @@
+# Autonomous Login
+
+Page wants auth. **Default: don't.** Logins are intrusive and can damage account state. Proceed only when both gates pass.
+
+## Gate 1 — Login required for continuing _this_ task?
+
+If the user's task is literally "log in / post / DM", or needs login to continue, gate passed. For extract/read/observe tasks, check whether the wall actually blocks the goal:
+
+- Target content already in DOM beneath the wall? Read it directly.
+- Dismiss available (`Maybe later`, `Skip`, modal `×`)? Click it.
+- Alternative path — public mirror, archive.org, RSS, JSON endpoint, deep link?
+
+If the rest of the task completes without auth → `LOGIN_NOT_NEEDED`. Wikipedia, public docs/news, public read-only profiles.
+
+## Gate 2 — Credentials unambiguously for _this_ site?
+
+**Password is not required to pass Gate 2.** Many sites use magic-link / email-only / passkey auth — an email alone (or any contextually-matched identifier) can be sufficient. Don't preemptively fail Gate 2 because no password is in context; let the form tell you at runtime. Only fail Gate 2 if the form actually demands a credential type you don't have.
+
+Identified **contextually** by name-to-domain correspondence — fixed names not required. Bar is **extraordinary evidence**, not plausibility.
+
+- ✅ `instagram.com` + `instagramHandle` / `instagramPassword`
+- ✅ `LOGIN_USERNAME` / `LOGIN_PASSWORD` paired with `LOGIN_TARGET_URL` whose host matches
+- ❌ `wikipedia.org` + `instagramHandle` (names belong to a different service)
+- ❌ Bare `username` / `password` with no domain qualifier (ambiguous)
+
+Absent / ambiguous / multiple plausible pairs → `MISSING_CONTEXT`. TOTP follows the same rule.
+
+---
+
+If either gate fails, stop and emit the matching `reason_code`. Rest runs only when both pass.
+
+## Reach the form
+
+- Password input in snapshot → continue.
+- Sign-in link/button visible → click, wait, re-snapshot.
+- Email-first (username only): type username, click `Continue` / `Next`, `waitForSelector` on `input[type="password"]` (10000ms), re-snapshot.
+- After two transitions with no password input → `FORM_NOT_FOUND`.
+
+## Sanity check
+
+Confirm login (not signup/reset): submit name is `Sign in` / `Log in` / `Continue` (not `Sign up` / `Register` / `Reset`), and exactly **one** password field present. Else `FORM_NOT_FOUND`.
+
+## Field selection (anchor off password)
+
+- **Password**: `input[type="password"]`. With multiples: matches `/password/i` and **not** `confirm|new password`.
+- **Username** (first match): same-form `input[type="email"]` → input matching `/email|username|user|login|account/i` → visible text/email/tel input immediately preceding the password in `ref` order.
+- **Submit** (first match): same-form button matching `/^(sign in|log in|login|continue|submit)$/i` → `button[type="submit"]` in form → the only non-SSO visible button (skip `Continue with Google` etc. unless context names that provider).
+
+Any missing → `FORM_NOT_FOUND` with what's missing.
+
+## Submit
+
+Single batched call (type username, type password, click submit) with Gate-2 values. Then `waitForNavigation` (10000ms) or `waitForResponse` on `*`. If both time out, verify anyway — page may have updated in place. Re-snapshot.
+
+## Verify success (any one, priority order)
+
+1. URL no longer matches `/login|signin|sign-in|log-in|auth|sso|account\/sign/i`.
+2. Password input absent from new snapshot.
+3. Authed-state element matching `/log out|sign out|my account|profile|dashboard|avatar/i`.
+
+If none holds:
+
+- Form error matching `/invalid|incorrect|wrong|doesn'?t match|not recognized|please try again/i` → `INVALID_CREDENTIALS`.
+- Captcha indicator → invoke `captchas` skill, re-verify. Unsolvable → `CAPTCHA_BLOCKED`.
+- MFA prompt → MFA branch.
+- No change, no error → `SUBMIT_NO_FEEDBACK`.
+
+**Never retype the same credentials to retry.** Caller's call.
+
+## MFA branch
+
+Required when snapshot has `autocomplete="one-time-code"`, numeric input with `maxlength` ∈ {4, 6, 8}, or label/`name`/`placeholder` matching `/code|verification|otp|2fa|two[- ]?factor|authenticator/i`.
+
+- Contextually-matched TOTP available (same Gate-2 rule) → type, click submit, re-verify.
+- **No matching TOTP in context → ask the user for the code in plain text and STOP this turn. Do not call `close`. Do not emit the final JSON block. Leave the agent session open so the next turn can resume — the OTP input is still on the page and the cookies/state are intact.** When the user replies with a code, treat it as the TOTP value, type + click submit + re-verify. If the user declines or says they don't have one → `MFA_INPUT_MISSING`. Never attempt SMS/email/WebAuthn flows.
+- TOTP rejected (`/invalid|expired|incorrect/i`) → ask user for a fresh code (same don't-close rule); after one fresh-code rejection → `MFA_FAILED`.
+- Second MFA prompt after first cleared → `UNEXPECTED_STATE`.
+
+## Final response
+
+Call `close`, then emit **exactly one** fenced JSON block — nothing before or after, no prose. Fields: `success`, `reason_code`, `final_url`, `evidence`, `steps_taken` (JSON-RPC call count; batched call = 1). On failure, `success: false` and `final_url` = current URL.
+
+`reason_code` ∈ `SUCCESS` | `LOGIN_NOT_NEEDED` | `MISSING_CONTEXT` | `INVALID_CREDENTIALS` | `MFA_INPUT_MISSING` | `MFA_FAILED` | `CAPTCHA_BLOCKED` | `FORM_NOT_FOUND` | `SUBMIT_NO_FEEDBACK` | `FIELD_TYPE_MISMATCH` | `UNEXPECTED_STATE`.
+
+## Don't
+
+- Log in just because a form is visible — gates first.
+- Use credentials whose names don't unambiguously belong to this site.
+- Guess among multiple plausible pairs — `MISSING_CONTEXT`.
+- Retry with the same credentials after failure.
+- Try SSO buttons unless the task names that provider.
+- `evaluate` to set input `value` — use `type` so real keystrokes fire.
+- Leak credentials into narration, errors, or non-`type.params.text` fields.
+- Emit anything other than the final JSON block in your last _terminal_ message (ask-the-user turns are not terminal — emit plain prose and stop without `close`).
+- Close the session while waiting for a user-supplied OTP — leave it open so cookies, page state, and the OTP input survive the round-trip.

package/build/src/skills/captchas.md

@@ -0,0 +1,48 @@
+# Captchas & Bot Challenges
+
+Page shows captcha widget (reCAPTCHA, hCaptcha, Cloudflare Turnstile, DataDome) **or** navigation returned 403/429 with bot-challenge headers. Use `solve` command, not click.
+
+> **EXPERIMENTAL — Cloud-only.** `solve` works on `production.browserless.io` only. Self-hosted Enterprise lacks solver backend; use `smartscraper` or `liveURL` instead.
+
+## `solve` command
+
+```json
+{
+  "method": "solve",
+  "params": { "type": "recaptcha", "wait": true, "timeout": 30000 }
+}
+```
+
+**Params (all optional):**
+
+- `type` — auto-detects if omitted. Specify only when needed: `cloudflare`, `hcaptcha`, `recaptcha`, `recaptchaV3`, `geetest`, `normal`, `friendlyCaptcha`, `capy`, `textCaptcha`, `amazonWaf`, `dataDome`, `akamai`, `lemin`, `mtcaptcha`, `slider`
+- `wait` (default `true`) — wait for captcha appearance. `false` if already visible
+- `timeout` (default 30000ms) — wait duration for detection
+
+## Response
+
+```json
+{ "found": true, "solved": true, "time": 18342, "token": "03AGdBq25..." }
+```
+
+- `found: false` → no captcha within timeout. May be passed or wrong heuristic
+- `found: true, solved: false` → detected but failed (rate-limited/unsupported variant/nav mid-solve). Re-snapshot; don't retry blindly
+- `solved: true` → token injected. **Re-snapshot for Continue/Submit button** or await auto-navigation
+
+## Recipe
+
+1. Run `solve` with no `type`: `{ "method": "solve", "params": {} }`
+2. Check `found`/`solved`
+3. Re-snapshot (page state changed)
+4. Click continue button if present, or `waitForNavigation`
+
+## Escalation on failure
+
+1. `found: false` but widget visible → specify `type`, retry once
+2. `solved: false` → re-snapshot first (don't retry immediately; costs & rate-limited)
+3. Repeated failures → use `smartscraper` or surface `liveURL` for human
+
+## Don't
+
+- Click checkboxes via `click` — opens challenge UI but doesn't solve
+- `evaluate` JS to set `g-recaptcha-response` — tokens session-bound; hand-written values rejected

package/build/src/skills/cookie-consent.md

@@ -0,0 +1,50 @@
+# Cookie Consent Banners
+
+Snapshot contains button/link matching `accept all`, `reject all`, `consent`, or `cookies`. Handle consent banner **before** anything else. Banners overlay content, intercept clicks, break selectors.
+
+## Recipe
+
+1. **Find dismiss button in snapshot.** Look for:
+   - `Reject all`, `Decline`, `Deny`, `Refuse all`
+   - `Accept all`, `Accept`, `Agree` (only if no reject — can't interact with site rejecting consent every load)
+   - `Manage preferences`, `Cookie settings` (avoid — opens sub-flow)
+2. **Click via `ref=` or `deep-ref=`.** Modern banners (OneTrust, Cookiebot, Didomi, Quantcast Choice, TrustArc) render in shadow DOM; expect `deep-ref=`
+3. **Re-snapshot.** DOM behind banner changes on close; previous refs stale
+4. **Proceed** with actual task
+
+## Dismiss button NOT in snapshot
+
+Banner rendering inside shadow root accessibility tree didn't pierce. Try deep selector by host:
+
+| Vendor    | Common deep selector                                                 |
+| --------- | -------------------------------------------------------------------- |
+| OneTrust  | `< #onetrust-reject-all-handler` or `< #onetrust-accept-btn-handler` |
+| Cookiebot | `< #CybotCookiebotDialogBodyButtonDecline`                           |
+| Didomi    | `< #didomi-notice-disagree-button`                                   |
+| Quantcast | `< button.css-47sehv` (reject) — class names rotate, snapshot first  |
+| TrustArc  | `< *consent.trustarc.com* #decline_btn_text` (iframe-hosted)         |
+| Cookieyes | `< .cky-btn-reject`                                                  |
+
+No match → fallback to attribute-based deep selectors: `< button[aria-label*="Reject" i]`, `< button[id*="reject" i]`. See shadow-dom skill for full syntax.
+
+## Don't
+
+- Click `Accept all` reflexively. Sites track aggressively and may serve different content. Prefer reject when both present
+- Dismiss via `evaluate` removing banner element. Consent state server-side/cookies; hiding banner doesn't grant access, leaves event handlers blocking clicks
+- Continue with selectors from pre-dismiss snapshot. Always re-snapshot after close
+
+## Batching
+
+Combine dismiss click with re-snapshot:
+
+```json
+{
+  "commands": [
+    {
+      "method": "click",
+      "params": { "selector": "< #onetrust-reject-all-handler" }
+    },
+    { "method": "snapshot" }
+  ]
+}
+```

package/build/src/skills/dynamic-content.md

@@ -0,0 +1,72 @@
+# Waiting for Dynamic Content
+
+`wait*` timed out or page loads async content. Wait for signal work is done, not arbitrary delay.
+
+## Decision tree
+
+| Situation                      | Use                                        |
+| ------------------------------ | ------------------------------------------ |
+| Know API endpoint              | `waitForResponse { url, statuses: [200] }` |
+| Know CSS selector appears      | `waitForSelector { selector, timeout }`    |
+| Page navigates                 | `waitForNavigation { timeout }`            |
+| Nothing specific (last resort) | `waitForTimeout { time: 3000 }`            |
+
+`waitForResponse` most reliable — fires on network event. Prefer when URL pattern known.
+
+## Patterns
+
+**Search results:**
+
+```json
+{
+  "commands": [
+    { "method": "type", "params": { "selector": "input#q", "text": "query" } },
+    { "method": "click", "params": { "selector": "button#search" } },
+    {
+      "method": "waitForResponse",
+      "params": { "url": "*api/search*", "statuses": [200] }
+    },
+    { "method": "snapshot" }
+  ]
+}
+```
+
+**Form with redirect:**
+
+```json
+{
+  "commands": [
+    { "method": "click", "params": { "selector": "button#submit" } },
+    { "method": "waitForNavigation", "params": { "timeout": 10000 } },
+    { "method": "snapshot" }
+  ]
+}
+```
+
+**Lazy modal:**
+
+```json
+{
+  "commands": [
+    { "method": "click", "params": { "selector": "button#open" } },
+    {
+      "method": "waitForSelector",
+      "params": { "selector": "[role='dialog']", "timeout": 5000 }
+    },
+    { "method": "snapshot" }
+  ]
+}
+```
+
+## When timeout occurs
+
+1. **Re-snapshot** — content may already be there (wrong wait condition)
+2. **Widen pattern** — `*api/search*` matches more than exact URL
+3. **Switch wait type** — if `waitForResponse` fails, try `waitForSelector` for rendered output
+4. **Last resort:** `waitForTimeout { time: 3000 }`
+
+## Avoid
+
+- `evaluate` with setTimeout/Promise (returns before timer completes)
+- Multiple `waitForTimeout` stacked (use specific wait methods)
+- Tight snapshot loop without wait (burns tokens, races page)

package/build/src/skills/index.d.ts

@@ -0,0 +1,9 @@
+import type { DetectContext, Skill, SkillFireState, SkillId } from '../@types/types.js';
+export type { SkillId, DetectContext, SkillFireState, } from '../@types/types.js';
+export declare const skillsRegistry: ReadonlyArray<Skill>;
+export declare const isCloudApi: (apiUrl: string | undefined) => boolean;
+export declare const createSkillState: () => SkillFireState;
+export declare const detectSkills: (ctx: DetectContext, state: SkillFireState) => SkillId[];
+export declare const markFired: (state: SkillFireState, ids: ReadonlyArray<SkillId>) => void;
+export declare const renderSkill: (id: SkillId) => string;
+export declare const renderSkills: (ids: ReadonlyArray<SkillId>) => string;

package/build/src/skills/index.js

@@ -0,0 +1,221 @@
+import { readFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const DEFAULT_MAX_ELEMENTS = 500;
+const CLOUD_API_HOSTS = ['production.browserless.io', 'chrome.browserless.io'];
+const COOKIE_NAME_RE = /\b(accept all|reject all|consent|cookies?)\b/i;
+const CAPTCHA_TEXT_RE = /\b(verify you are human|verifying you are human|i'?m not a robot|checking your browser|are you human|complete the (captcha|challenge))\b/i;
+const CAPTCHA_HOST_RE = /(challenges\.cloudflare\.com|geo\.captcha-delivery\.com|hcaptcha\.com|recaptcha\.net|google\.com\/recaptcha)/i;
+const CAPTCHA_ERROR_RE = /\b(captcha|cloudflare|challenge|forbidden|429|403)\b/i;
+const LOGIN_URL_RE = /\/(login|signin|sign-?in|log-?in|auth|sso|oauth)\b|\/account\/sign/i;
+const LOGIN_NUDGE_RE = /sign in to (view|see|continue|access|read|comment|post|reply|save|order|buy|checkout|your account)|please sign in|signed out\b.*sign in|create (an )?account to/i;
+const TAB_ERROR_CODES = ['TAB_NOT_FOUND', 'TAB_CLOSED', 'TAB_LIMIT_EXCEEDED'];
+const TAB_COMMAND_METHODS = ['getTabs', 'switchTab', 'createTab', 'closeTab'];
+const evalPredicate = (p, ctx) => {
+    switch (p.kind) {
+        case 'snapshot.has-element': {
+            const els = ctx.snapshot?.elements;
+            if (!els)
+                return false;
+            return els.some((el) => {
+                if (p.roles && !p.roles.includes(el.role))
+                    return false;
+                if (p.nameRegex) {
+                    const name = el.name || el.text || '';
+                    if (!p.nameRegex.test(name))
+                        return false;
+                }
+                if (p.selectorPrefix && !el.selector?.startsWith(p.selectorPrefix)) {
+                    return false;
+                }
+                return true;
+            });
+        }
+        case 'snapshot.has-input-type':
+            return !!ctx.snapshot?.elements?.some((el) => el.type === p.type);
+        case 'snapshot.url-match':
+            return !!ctx.snapshot?.url && p.regex.test(ctx.snapshot.url);
+        case 'snapshot.has-detected-challenge':
+            return !!ctx.snapshot?.detectedChallenges?.length;
+        case 'snapshot.tabs-at-least':
+            return (ctx.snapshot?.tabs?.length ?? 0) >= p.count;
+        case 'snapshot.element-cap-hit': {
+            const snap = ctx.snapshot;
+            const cmd = ctx.cmd;
+            if (!snap || cmd?.method !== 'snapshot')
+                return false;
+            const len = snap.elements.length;
+            if (len === 0)
+                return true;
+            const requestedMax = typeof cmd.params?.maxElements === 'number'
+                ? cmd.params.maxElements
+                : DEFAULT_MAX_ELEMENTS;
+            return len >= requestedMax;
+        }
+        case 'error.code':
+            return !!ctx.error?.code && p.codes.includes(ctx.error.code);
+        case 'error.message-match':
+            return !!ctx.error?.message && p.regex.test(ctx.error.message);
+        case 'command.method':
+            return !!ctx.cmd?.method && p.methods.includes(ctx.cmd.method);
+        case 'command.method-prefix':
+            return !!ctx.cmd?.method && ctx.cmd.method.startsWith(p.prefix);
+        case 'command.selector-not-deep': {
+            const sel = ctx.cmd?.params?.selector;
+            return typeof sel === 'string' && !sel.startsWith('< ');
+        }
+    }
+};
+const SKILL_SPECS = [
+    {
+        id: 'shadow-dom',
+        path: 'src/skills/shadow-dom.md',
+        refireAfter: 3,
+        triggers: [
+            // snapshot contains a deep-ref element
+            [{ kind: 'snapshot.has-element', selectorPrefix: '< ' }],
+            // selector-not-found error on a non-deep selector
+            [
+                { kind: 'error.code', codes: ['SELECTOR_NOT_FOUND'] },
+                { kind: 'command.selector-not-deep' },
+            ],
+        ],
+    },
+    {
+        id: 'cookie-consent',
+        path: 'src/skills/cookie-consent.md',
+        triggers: [
+            [
+                {
+                    kind: 'snapshot.has-element',
+                    roles: ['button', 'link'],
+                    nameRegex: COOKIE_NAME_RE,
+                },
+            ],
+        ],
+    },
+    {
+        id: 'modals',
+        path: 'src/skills/modals.md',
+        triggers: [
+            [{ kind: 'snapshot.has-element', roles: ['dialog', 'alertdialog'] }],
+        ],
+    },
+    {
+        id: 'snapshot-misses',
+        path: 'src/skills/snapshot-misses.md',
+        triggers: [[{ kind: 'snapshot.element-cap-hit' }]],
+    },
+    {
+        id: 'screenshots',
+        path: 'src/skills/screenshots.md',
+        triggers: [[{ kind: 'command.method', methods: ['screenshot'] }]],
+    },
+    {
+        id: 'dynamic-content',
+        path: 'src/skills/dynamic-content.md',
+        triggers: [
+            [
+                { kind: 'command.method-prefix', prefix: 'wait' },
+                { kind: 'error.message-match', regex: /timeout|timed out/i },
+            ],
+        ],
+    },
+    {
+        id: 'tabs',
+        path: 'src/skills/tabs.md',
+        triggers: [
+            [{ kind: 'snapshot.tabs-at-least', count: 2 }],
+            [{ kind: 'error.code', codes: TAB_ERROR_CODES }],
+            [{ kind: 'command.method', methods: TAB_COMMAND_METHODS }],
+        ],
+    },
+    {
+        id: 'autonomous-login',
+        path: 'src/skills/autonomous-login.md',
+        triggers: [
+            [{ kind: 'snapshot.has-input-type', type: 'password' }],
+            [{ kind: 'snapshot.url-match', regex: LOGIN_URL_RE }],
+            [
+                {
+                    kind: 'snapshot.has-element',
+                    roles: ['button', 'link'],
+                    nameRegex: LOGIN_NUDGE_RE,
+                },
+            ],
+        ],
+    },
+    {
+        id: 'captchas',
+        path: 'src/skills/captchas.md',
+        cloudOnly: true,
+        refireAfter: 3,
+        triggers: [
+            [{ kind: 'snapshot.has-detected-challenge' }],
+            [{ kind: 'snapshot.url-match', regex: CAPTCHA_HOST_RE }],
+            [{ kind: 'snapshot.has-element', nameRegex: CAPTCHA_TEXT_RE }],
+            [
+                { kind: 'command.method', methods: ['goto'] },
+                { kind: 'error.message-match', regex: CAPTCHA_ERROR_RE },
+            ],
+        ],
+    },
+];
+const skillsDir = dirname(fileURLToPath(import.meta.url));
+const loadBody = (filename) => readFileSync(join(skillsDir, filename), 'utf-8');
+const skills = SKILL_SPECS.map((spec) => ({
+    ...spec,
+    body: loadBody(basename(spec.path)),
+}));
+export const skillsRegistry = skills;
+export const isCloudApi = (apiUrl) => {
+    if (!apiUrl)
+        return false;
+    try {
+        const host = new URL(apiUrl).hostname;
+        return CLOUD_API_HOSTS.includes(host);
+    }
+    catch {
+        return false;
+    }
+};
+export const createSkillState = () => ({
+    fired: new Map(),
+    cmdIndex: 0,
+});
+const fires = (skill, ctx) => skill.triggers.some((trigger) => trigger.every((p) => evalPredicate(p, ctx)));
+export const detectSkills = (ctx, state) => {
+    const triggered = [];
+    for (const skill of skills) {
+        if (skill.cloudOnly && !isCloudApi(ctx.apiUrl))
+            continue;
+        if (!fires(skill, ctx))
+            continue;
+        const lastFired = state.fired.get(skill.id);
+        if (lastFired === undefined) {
+            triggered.push(skill.id);
+            continue;
+        }
+        if (skill.refireAfter !== undefined &&
+            state.cmdIndex - lastFired >= skill.refireAfter) {
+            triggered.push(skill.id);
+        }
+    }
+    return triggered;
+};
+export const markFired = (state, ids) => {
+    for (const id of ids) {
+        state.fired.set(id, state.cmdIndex);
+    }
+};
+export const renderSkill = (id) => {
+    const skill = skills.find((s) => s.id === id);
+    if (!skill)
+        return '';
+    return [
+        `--- SKILL: ${skill.id} (${skill.path}) ---`,
+        skill.body.trimEnd(),
+        '--- END SKILL ---',
+    ].join('\n');
+};
+export const renderSkills = (ids) => ids.map(renderSkill).filter(Boolean).join('\n\n');

package/build/src/skills/modals.md

@@ -0,0 +1,56 @@
+# Modal Dialogs
+
+Snapshot shows `role: dialog` or `role: alertdialog` — modal is open, traps focus/clicks.
+
+## Strategy
+
+**Want to interact with it?** → Use element refs from current snapshot.  
+**Want it gone?** → Close it, then re-snapshot.
+
+## Closing (try in order)
+
+1. **Close button in snapshot** — `Close`, `×`, `Dismiss`, `No thanks`, etc. Click its ref.
+
+2. **Aria-labeled close:**
+
+   ```json
+   { "method": "click", "params": { "selector": "[aria-label='Close']" } }
+   ```
+
+3. **Escape key:**
+
+   ```json
+   {
+     "method": "evaluate",
+     "params": {
+       "content": "(() => { document.activeElement?.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true })); document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true })); })()"
+     }
+   }
+   ```
+
+4. **Click backdrop:**
+
+   ```json
+   {
+     "method": "click",
+     "params": {
+       "selector": ".modal-backdrop, [class*='overlay']:not([class*='inner'])"
+     }
+   }
+   ```
+
+5. **Re-snapshot** to confirm gone.
+
+## alertdialog
+
+Critical confirmations ("Delete?"). Don't auto-dismiss. Find explicit button (`Confirm`, `Delete`, `Yes`) if task requires it.
+
+## After closing
+
+- Refs behind modal still valid (overlay, not reflow)
+- Focus/scroll may have shifted — re-snapshot before type/scroll actions
+
+## Avoid
+
+- Removing modal DOM via evaluate (SPAs remount it)
+- Interacting with page behind without closing first (pointer events captured)