{"id":"c76112fd-6dc3-45a5-83ee-ac88aa4ecd96","entityType":"agent","slug":"clawhub-xor777-magicbrowse","name":"MagicBrowse","canonicalUrl":"https://www.xpersona.co/agent/clawhub-xor777-magicbrowse","canonicalPath":"/agent/clawhub-xor777-magicbrowse","generatedAt":"2026-10-10T08:44:58.437Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T02:38:43.838Z","emptyReason":null},"description":"Browser automation fallback through the magicbrowse CLI with goal-driven act as the default primitive and observe/primitives only for recovery, with changed page state verified by fresh observation.","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.8K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s170j1f52qsha0313xn4j1rjsn84bn5f:magicbrowse","sourceUrl":"https://clawhub.ai/xor777/magicbrowse","homepage":"https://clawhub.ai/xor777/skills/magicbrowse","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/xor777/magicbrowse","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/xor777/skills/magicbrowse","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":65,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"MagicBrowse technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T02:38:43.838Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T02:38:43.838Z","emptyReason":null},"stars":null,"forks":null,"downloads":1766,"packageName":null,"latestVersion":"0.1.19","tractionLabel":"1.8K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T02:38:43.571Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T02:38:43.838Z","lastCrawledAt":"2026-10-10T02:38:43.571Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T02:38:43.571Z","lastVerifiedAt":null,"highlights":[{"version":"0.1.19","createdAt":"2026-08-20T07:31:37.089Z","changelog":"Release magicbrowse-v0.1.19","fileCount":8,"zipByteSize":23885},{"version":"0.1.18","createdAt":"2026-08-07T09:44:20.666Z","changelog":"Release magicbrowse-v0.1.18","fileCount":8,"zipByteSize":23476},{"version":"0.1.16","createdAt":"2026-06-10T12:30:53.825Z","changelog":"Release magicbrowse-v0.1.16","fileCount":8,"zipByteSize":23612},{"version":"0.1.14","createdAt":"2026-06-04T15:47:43.948Z","changelog":"Release magicbrowse-v0.1.14","fileCount":8,"zipByteSize":22691},{"version":"0.1.13","createdAt":"2026-06-02T15:07:58.820Z","changelog":"Release magicbrowse-v0.1.13","fileCount":8,"zipByteSize":22639},{"version":"0.1.12","createdAt":"2026-05-29T10:19:49.532Z","changelog":"Release magicbrowse-v0.1.12","fileCount":8,"zipByteSize":22003},{"version":"0.1.11","createdAt":"2026-05-22T16:08:04.247Z","changelog":"Release magicbrowse-v0.1.11","fileCount":8,"zipByteSize":21854},{"version":"0.1.10","createdAt":"2026-05-12T15:03:38.687Z","changelog":"Release magicbrowse-v0.1.10","fileCount":7,"zipByteSize":18928}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s170j1f52qsha0313xn4j1rjsn84bn5f:magicbrowse","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s170j1f52qsha0313xn4j1rjsn84bn5f:magicbrowse` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/xor777/magicbrowse before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-xor777-magicbrowse/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-xor777-magicbrowse/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-xor777-magicbrowse/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-xor777-magicbrowse/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-xor777-magicbrowse/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-xor777-magicbrowse/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T08:44:58.432Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-xor777-magicbrowse/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-xor777-magicbrowse/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-xor777-magicbrowse/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-xor777-magicbrowse/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T02:38:43.838Z","emptyReason":null},"readme":"Skill: MagicBrowse\n\nOwner: xor777\n\nSummary: Browser automation fallback through the magicbrowse CLI with goal-driven act as the default primitive and observe/primitives only for recovery, with changed page state verified by fresh observation.\n\nTags: latest:0.1.19\n\nVersion history:\n\nv0.1.19 | 2026-08-20T07:31:37.089Z | user\n\nRelease magicbrowse-v0.1.19\n\nv0.1.18 | 2026-08-07T09:44:20.666Z | user\n\nRelease magicbrowse-v0.1.18\n\nv0.1.16 | 2026-06-10T12:30:53.825Z | user\n\nRelease magicbrowse-v0.1.16\n\nv0.1.14 | 2026-06-04T15:47:43.948Z | user\n\nRelease magicbrowse-v0.1.14\n\nv0.1.13 | 2026-06-02T15:07:58.820Z | user\n\nRelease magicbrowse-v0.1.13\n\nv0.1.12 | 2026-05-29T10:19:49.532Z | user\n\nRelease magicbrowse-v0.1.12\n\nv0.1.11 | 2026-05-22T16:08:04.247Z | user\n\nRelease magicbrowse-v0.1.11\n\nv0.1.10 | 2026-05-12T15:03:38.687Z | user\n\nRelease magicbrowse-v0.1.10\n\nv0.1.9 | 2026-05-12T13:42:28.780Z | user\n\nRelease magicbrowse-v0.1.9\n\nv0.1.8 | 2026-05-12T12:29:26.269Z | user\n\nRelease magicbrowse-v0.1.8\n\nv0.1.7 | 2026-05-12T11:45:09.891Z | user\n\nRelease magicbrowse-v0.1.7\n\nv0.1.6 | 2026-05-12T10:35:08.798Z | user\n\nRelease magicbrowse-v0.1.6\n\nv0.1.5 | 2026-05-11T10:54:11.543Z | user\n\nRelease magicbrowse-v0.1.5\n\nv0.1.4 | 2026-05-11T10:37:13.512Z | user\n\nRelease magicbrowse-v0.1.4\n\nv0.1.3 | 2026-05-03T10:44:58.403Z | user\n\nRelease magicbrowse-v0.1.3\n\nv0.1.2 | 2026-05-03T10:36:55.160Z | user\n\nRelease magicbrowse-v0.1.2\n\nv0.1.1 | 2026-05-03T07:54:26.271Z | user\n\nRelease magicbrowse-v0.1.1\n\nv0.1.0 | 2026-05-03T07:33:48.091Z | user\n\nRelease magicbrowse-v0.1.0\n\nArchive index:\n\nArchive v0.1.19: 8 files, 23885 bytes\n\nFiles: metadata.openclaw.json (402b), references/commands.md (9840b), references/guardrails.md (9692b), references/statuses.md (7133b), references/workflow.md (7222b), skill-card.md (3136b), SKILL.md (15252b), _meta.json (131b)\n\nFile v0.1.19:SKILL.md\n\n---\nname: magicbrowse\ndescription: Browser automation fallback through the magicbrowse CLI with\n goal-driven act as the default primitive and observe/primitives only for\n recovery, with changed page state verified by fresh observation.\nhomepage: https://www.npmjs.com/package/@nuanu-ai/magicbrowse-cli\nmetadata:\n openclaw:\n homepage: https://github.com/nuanu-ai/skills/blob/main/docs/magicbrowse/openclaw/marketplace/README.md\n requires:\n bins:\n - magicbrowse\n primaryEnv: MAGICPAY_API_KEY\n install:\n - id: npm\n kind: node\n package: \"@nuanu-ai/magicbrowse-cli@latest\"\n bins:\n - magicbrowse\n label: Install MagicBrowse CLI (npm)\n---\n\nUse `magicbrowse` to reach a target page when your runtime's own\npage-control tool cannot do it reliably. \"Page-control tool\"\nmeans a tool that drives browser pages programmatically and reports page state\nback — not the user's desktop browser, and not screen-control of a\nbrowser window. The planner runs two LLM loops per task and is slower\nthan direct browser control; prefer your own page-control tool\nwhen it suffices. Use `magicbrowse` to *reach* a target page (search, navigation,\ntraversal through non-sensitive screens). At any login, identity, checkout,\ndonation, subscription, payment, or human-verification page, stop and surface\nto the user — do not invent or type credentials, identity data, payment data,\nor any value you do not legitimately have.\n\nFor a MagicPay product/payment workflow, use the MagicPay workflow-first\nrecipe instead of treating a standalone MagicBrowse browser as the product\nparent: MagicPay starts the product session, then launches or attaches the\nbrowser as a child resource.\n\n## Fallback Ladder\n\nTry in order. Do not start at layer 4 just because primitives exist.\n\n1. **Your runtime's own page-control tool** — programmatic page\n control owned by your runtime. Screen-control (computer use) of an\n already-open desktop browser does not qualify: takeover needs the\n browser's CDP endpoint, a typical desktop browser starts without one,\n and CDP cannot be enabled on a running browser without a restart. If\n the session may need a MagicBrowse or MagicPay takeover mid-flow,\n start from a browser with a known private CDP endpoint.\n2. **`magicbrowse act \"\"`** — DOM-only navigator.\n3. **`magicbrowse act \"\" --use-vision`** — same goal, navigator\n with screenshots. Use only when the user is comfortable sending\n screenshots/page context for this workflow. Vision is a retry mode\n for the same task; keep the granule.\n4. **`magicbrowse observe` + primitives** —\n `click `, `type `,\n `fill `, `select `,\n `press `. Use only when vision-mode `act` cannot make\n progress, or when single-element precision is required. A primitive\n `completed` result means the direct action ran; it is not a semantic\n proof that the intended page state changed. Re-run `observe` before the\n next decision. `press` is global — `click` first if focus matters.\n5. **Surface failure to the user.**\n\n## Preferred Pattern\n\nFor public navigation tasks, give `act` the semantic goal and a checkable\nterminal condition:\n\n✓ `magicbrowse act \"navigate to the public page that lists supported regions and stop when the region list is visible\"`\n\nAvoid manually replaying snapshot ids before `act` has failed:\n\n✗ `magicbrowse observe` → `magicbrowse click 13` → `magicbrowse observe` → `magicbrowse click 23`\n\n## Setup Check\n\n1. Run `magicbrowse doctor` first on a fresh install. It verifies the\n gateway config and reachability.\n2. If it fails because the API key is missing, run\n `magicbrowse init ` (sign up at\n `https://app.magiccard.ai/signup`).\n3. Only proceed to `launch` and `act` once `doctor` passes.\n\n## Hard Rules\n\n> **Consequential actions require approval.** `magicbrowse` may\n> navigate, inspect, draft, and prepare. It must stop and ask before\n> submitting a form, posting or sending content, accepting terms,\n> changing account data or settings, booking, buying, ordering,\n> deleting or modifying remote data, or otherwise committing an\n> irreversible or account-affecting action. After approval, re-run\n> `observe` and execute only the approved final action. A successful typed\n> MagicPay approval counts for that exact payment, signing, or confirmation\n> action; ask again only if the approved page facts changed.\n\n> **Memory-managed data — never invent.** Do **not** use `act`, `type`,\n> `fill`, or `select` for any of the following on any page:\n> - login or signup credentials (email, username, password, OTP),\n> - identity-document fields (passport, ID, KYC address, DOB tied to\n> identity),\n> - payment-card or banking fields (PAN, CVV, expiry, IBAN, account),\n> - any value sourced from a Memory or Memory store, or any value you\n> do not legitimately have.\n>\n> Reach the page, stop before entering Memory values, and return the\n> handoff to the orchestrator or MagicPay Memory fill workflow. Do not\n> guess, placeholder, or fabricate Memory values. Be honest about what\n> you cannot do.\n\n> **Use `act` before snapshot primitives.** Do not start MagicBrowse work\n> with `observe` plus `click`/`type`/`select`/`press`/`fill` before\n> attempting `act` on the same goal. Why: the navigator keeps the goal,\n> current page context, and completion check in one planner loop instead of\n> spreading them across fragile snapshot ids. Use primitives only after\n> DOM-only and vision-mode `act` cannot make progress, or when the recovery\n> step is deliberately single-element.\n\n> **Target-ids are snapshot-scoped.** Valid only for the `observe`\n> snapshot that produced them. Re-run `observe` after any primitive that\n> may change the page state before the next primitive — reusing an old id\n> silently addresses a different element.\n>\n> ✓ `observe` → `click 12` → `observe` → `type 7 \"hello\"`\n> ✗ `observe` → `click 12` → `type 7 \"hello\"`\n\n> **Primitive completion is not goal completion.** For deterministic\n> `click`/`type`/`fill`/`select`/`press`, `status: \"completed\"` means the\n> browser action was dispatched through the direct action layer. It does not\n> certify that a higher-level page condition is now true. If the next step\n> depends on changed page state, observe again and branch on the fresh page\n> state. If the task itself needs a completion check, use `act` with a\n> checkable terminal condition instead of interpreting a primitive result as\n> task success.\n\n> **One workflow per default home.** The current-session pointer at\n> `$MAGICBROWSE_HOME/current-session.json` (default `~/.magicbrowse/`) is a\n> singleton. Concurrent workflows on the same home overwrite each other. For\n> parallel use, set a distinct `MAGICBROWSE_HOME` per workflow, or do not run\n> the tasks in parallel.\n\n> **Fresh browser by default.** Prefer an owned, fresh browser session.\n> Use `attach`, `--profile`, or `--user-data-dir` only when the user\n> explicitly approves that browser/session for the current task. One\n> exception needs no separate approval: attaching to the browser child\n> that MagicPay launched inside the current approved product workflow —\n> that is the normal in-workflow bind of an owned disposable browser.\n> Keep CDP endpoints private. Close the session before unrelated work.\n\n> **Page context can leave the browser.** LLM-backed `act` sends page\n> state to the gateway; `--use-vision` can include screenshots. Avoid\n> private pages unless the user approves that workflow, and stop at login,\n> identity, checkout, donation, subscription, or payment pages.\n\n## Primary Workflow\n\nContract: `launch [url] → act … act → close`. Sequential `act` calls in\none session preserve page state and planner memory.\n\n1. `magicbrowse launch ` — start a headless owned Chrome session\n pre-placed at the entry URL. Keep browser launches headless unless\n the user explicitly asks for a visible browser or you are doing live\n debugging. To attach to an existing CDP browser instead, first get\n explicit user approval for that endpoint/session:\n `magicbrowse attach ` (positional, not a\n `--cdp-url` flag).\n2. `magicbrowse act \"\"` — natural-language browser step. Prompt is\n **positional**. `act` does **not** take `--url`; you cannot reset\n the page from inside `act`. To re-anchor, `close` and `launch` again.\n3. Repeat `act` for the next strategic granule.\n4. `magicbrowse close` — release the session when the overall\n MagicBrowse-owned browser task is done. If the workflow hands off to\n another tool or the user on a sensitive page, keep the browser open until\n that handoff completes. After the handoff completes, close only a\n MagicBrowse-owned disposable browser that the user is not taking over; do\n not close an external/user-owned attach without explicit approval.\n\n`magicbrowse run` exists in the CLI for one-shot developer use. **It\nis not part of this skill contract** — its bundled `close` destroys\ncontinuity. Do not use it in an orchestrated workflow.\n\n## Goal Granularity\n\n1. **Granule = atomic strategic segment.** End each `act` where the\n orchestrator needs the next strategic decision. Tactics (which form\n field first) live inside `act`; strategy (this partner is wrong, try\n another) lives between `act` calls.\n2. **Target horizon: 15-30 navigator steps per `act`; smaller is\n safer.** `maxSteps: 100` is a safety ceiling. The planner\n self-validates terminal status, so longer tasks have more room for\n false-positive completion. Prefer smaller granules when the success\n criterion cannot be checked externally.\n3. **Auth walls and CAPTCHA are hard boundaries, not obstacles.** A\n task that reaches auth, CAPTCHA, or human verification ends with\n `status: needs_handoff`, not `failed`. Plan tasks to end *at* such\n a wall, not through it. `magicbrowse` does not solve CAPTCHA and\n does not enter credentials. For a confirmed real CAPTCHA on the current\n approved browser session, have the user or an external solver clear it;\n after a successful solve, run `magicbrowse mark-captcha-resolved` before\n the next `act`. Branch on `handoff.kind`: `captcha` means solve/mark,\n `auth` means stop for user authentication, `identity_verification` means\n stop for user/KYC handling, and `memory_fill` means hand off to the\n MagicPay Memory fill workflow. Memory-fill handoffs include\n `resumeObjective`; after the approved handler fills the form, continue\n with that page-local objective. Never retry the same `act` against the\n same wall. If the page asks for something you cannot legitimately\n provide, be honest about it.\n4. **Rely on session memory; do not re-narrate.** Sequential `act`\n calls in one session preserve page state and planner memory. Do not\n write \"as we already found, continue with…\" into goals — if you\n feel the need to, the granularity is wrong.\n\n## Goal Formulation\n\n1. **No element indexes or selectors in goal text.** Indexes renumber\n on every DOM scan. Describe elements semantically.\n - ✗ `act \"click target 14\"`\n - ✓ `act \"click the 'Continue' button under the price summary\"`\n2. **Describe the expected terminal state where it adds a checkable\n criterion.**\n - ✗ `act \"get to checkout\"`\n - ✓ `act \"navigate to a checkout page that shows passenger fields and total fare\"`\n3. **Pass the starting URL to `launch`, not as a separate step.** To\n switch sites mid-workflow, either `close` and re-`launch`, or\n describe the navigation inside the goal text.\n\n## Common Mistakes\n\n> - Element indexes (`[14]`, `target 7`) in goal text.\n> - `magicbrowse run` for orchestrated multi-step workflows.\n> - `type` / `fill` / `select` / `act` on Memory-managed fields. Stop at\n> the form boundary; if `act` returns a memory-fill handoff, send it to\n> the orchestrator or MagicPay Memory fill workflow and then resume with\n> `handoff.resumeObjective`.\n> - Letting `act` submit, post, book, buy, save, delete, or otherwise\n> commit an account-affecting action without explicit approval or a matching\n> typed MagicPay approval for unchanged page facts.\n> - Trying to solve CAPTCHA through `magicbrowse`. On a confirmed real\n> CAPTCHA, have the user or an external solver clear it, then\n> `magicbrowse mark-captcha-resolved` before the next MagicBrowse step.\n> - Attaching to a logged-in browser or named profile without explicit\n> approval for the current task.\n> - Closing a browser that was handed to another tool or the user before the\n> overall task is actually done.\n> - Re-narrating prior `act` results into the next goal — sequential\n> `act` calls keep state.\n> - Skipping the `act`-first path and starting at layer 4\n> (observe + primitives).\n> - Reusing a target-id from before a page mutation.\n> - Treating a deterministic primitive's `completed` status as proof that\n> the intended page state changed.\n\n## Status and Errors\n\n`act` returns `status: completed | blocked | needs_handoff |\nneeds_approval | failed | max_steps | cancelled`. Branch on `status`;\ndo not parse `finalMessage` to detect missing input, Memory\nhandoff, handoff subtype, or approval stops. For `blocked`, branch on\n`blockedReason: missing_input | item_unavailable | ambiguous | no_path`.\nFor `needs_handoff`, branch on\n`handoff.kind: memory_fill | captcha | auth | identity_verification`.\n\nLayer-4 primitives return direct action results. Branch on their `status`\nand `reason`, but verify page-state assumptions with a fresh `observe`;\nprimitive `completed` is not a substitute for a goal-level completion check.\n`finalMessage` is the explanation to show the user or pass upstream.\nMemory-fill handoff details are in `handoff.resumeObjective`. Exit\ncode `0` includes `blocked`, `needs_handoff`, and `needs_approval`; it\ndoes not mean success.\n\nA failure never ends the conversation. `failed`, `max_steps`, and\n`timed_out` results carry `failureCode`, an optional `retryable: true`, and\n`agentInstructions` — follow `agentInstructions` verbatim: tell the user what\nwas already completed safely on the page, why automatic browsing cannot\ncontinue, and that they can finish manually at `finalUrl`. Retry once only\nwhen `retryable: true`; a result without it (for example\n`failureCode: \"llm_provider_payment_required\"`) needs an account or\nconfiguration fix, and retrying or restarting the helper will not succeed —\nstop the helper and hand over.\nSee [references/statuses.md](https://github.com/nuanu-ai/skills/blob/main/docs/magicbrowse/references/statuses.md).\n\n## References\n\n- [references/commands.md](https://github.com/nuanu-ai/skills/blob/main/docs/magicbrowse/references/commands.md) — every CLI command.\n- [references/workflow.md](https://github.com/nuanu-ai/skills/blob/main/docs/magicbrowse/references/workflow.md) — worked end-to-end\n example.\n- [references/guardrails.md](https://github.com/nuanu-ai/skills/blob/main/docs/magicbrowse/references/guardrails.md) — long-form hard\n rules.\n- [references/statuses.md](https://github.com/nuanu-ai/skills/blob/main/docs/magicbrowse/references/statuses.md) — outcome codes and\n status handling.\n\nFile v0.1.19:_meta.json\n\n{\n \"ownerId\": \"kn76jq44xm9vvwz0h4grasjvax84b83f\",\n \"slug\": \"magicbrowse\",\n \"version\": \"0.1.19\",\n \"publishedAt\": 1787211097089\n}\n\nFile v0.1.19:references/commands.md\n\n# MagicBrowse Command Guide\n\nFull reference for the `magicbrowse` CLI. The skill workflow uses\n`launch`, `act`, `observe`, `click`/`type`/`fill`/`select`/`press`,\n`mark-captcha-resolved`, and `close`. Agent setup uses\n`magicbrowse init`, then `doctor`. Everything else is for diagnostics,\ncompatibility, or one-shot developer use.\n\nThe hard rules from `SKILL.md` apply to every command: use a fresh\nbrowser by default, get explicit approval before using an existing\nprofile/CDP session, stop before consequential actions unless a matching typed\nMagicPay approval covers unchanged page facts, and stop at memory fills —\nnever invent or placeholder Memory data.\n\n## Setup And Readiness\n\n### `magicbrowse init [--api-url ]`\n\nWrites the gateway config used by LLM-backed `act`. When `--api-url` is\nprovided, it also stores the gateway base URL. Omit `--api-url` for normal\nsetup; pass `--api-url ` only for a non-default staging, self-hosted, or\ntest gateway.\n\nCurrent CLI compatibility note: the persisted config path and environment\noverride names still use the existing `~/.magicpay/config.json`,\n`MAGICPAY_API_KEY`, and `MAGICPAY_API_URL` names. Treat these as gateway\nconfiguration names, not memory-fill ownership.\n\nExit codes: `0` on success, `1` if `` is missing.\n\n### `magicbrowse doctor`\n\nVerify the gateway config and reachability. Use this as the preflight\nbefore `launch` and `act`.\n\nExit codes: `0` if config is healthy, `1` if not.\n\n### `magicbrowse browser-status`\n\nInspect live browser/page/runtime state. Use for diagnostics only.\n\nExit code: `0`.\n\n## Session Lifecycle\n\n### `magicbrowse launch [url] [--headful] [--profile ]`\n\nStart an owned Chrome session and persist it as the current session.\nThe URL is **positional and optional**. Headless is the default;\n`--headful` is a debug/visible-browser override. Use it only when the\nuser explicitly asks for a visible browser or a live debugging protocol\nrequires it; do not add it to normal agent workflows or examples.\nAdvanced flags (`--user-data-dir`, `--chrome-path`, `--user-agent`)\naccept overrides for non-default Chrome layouts.\n\nPrefer a fresh owned profile. Use `--profile` or `--user-data-dir`\nonly after the user explicitly approves that browser state for the\ncurrent task.\n\nExit code: `0`.\n\n### `magicbrowse attach `\n\nAttach to an existing CDP browser as the current session. The\nendpoint is **positional**, not a `--cdp-url` flag.\n\nOnly attach to a private endpoint that the user provided or explicitly\napproved for the current task. Treat CDP endpoints as sensitive because\nthey inherit the authority of that browser session. Attaching to the\nbrowser child that MagicPay launched inside the current approved product\nworkflow is the normal in-workflow path and needs no separate approval;\nthe approval requirement targets external or user-owned browsers.\n\nExit codes: `0` on success, `1` if the endpoint is missing.\n\n### `magicbrowse close`\n\nClose or detach the current session. Always returns `0`.\n\nUse this only when the overall browser workflow is done or recovery requires\nteardown. If the current page was handed to another tool or the user, wait for\nthat handoff to finish before closing a MagicBrowse-owned disposable browser.\nDo not close an external/user-owned attach without explicit teardown approval.\n\n## Natural-Language Browser Step\n\n### `magicbrowse act \"\" [--max-steps ] [--use-vision] [--format ]`\n\nRun one natural-language browser step on the current session. The prompt is\n**positional** (use double quotes for any prompt with spaces). `act`\ndoes **not** take `--url`.\n\nUse `act` for navigation, inspection, drafting, and preparation. If\nthe next step would submit a form, post or send content, accept terms,\nchange account data/settings, book, buy, order, delete, save, or\notherwise commit an irreversible/account-affecting action, stop and\nask for explicit approval. After approval, re-run `observe` and do\nonly the approved final action. A matching typed MagicPay approval counts for\nthe exact payment, signing, or confirmation action while page facts stay\nunchanged.\n\nOptions:\n\n- `--max-steps ` — override the navigator step ceiling (default 100).\n- `--use-vision` — include screenshots in the navigator's view. Use as\n a retry mode for the same goal only when the user is comfortable\n sending screenshots/page context for this workflow.\n- `--format ` — output format. `json` emits JSON\n Lines suitable for an orchestrator. Default is `human`.\n\nExit codes (mapped from the act `status` field):\n\n- `0` — `completed`, `blocked`, `needs_handoff`, or\n `needs_approval`.\n- `1` — `failed` or missing prompt or missing gateway config.\n- `2` — `max_steps` (planner did not converge before the step ceiling).\n- `130` — `cancelled` (e.g. SIGINT).\n\n`blocked`, `needs_handoff`, and `needs_approval` are controlled\nbrowser-task stops, not runtime failures. Branch on `status`, then on\n`blockedReason` or `handoff.kind` when present; use `finalMessage` only\nas the explanation to show the user or upstream orchestrator.\n\n### `magicbrowse mark-captcha-resolved [--ttl ]`\n\nRecord that a real CAPTCHA on the current active page was solved by an\nexternal participant. This command does not solve CAPTCHA, click a CAPTCHA\nwidget, or prove success. It writes a one-shot trusted marker into the\ncurrent session, bound to the active page identity. The next `act`\nconsumes the marker, passes it to the planner/navigator as evidence that\na previously visible CAPTCHA was solved out-of-band, then clears it.\n\n**Not part of the skill workflow.** The default `magicbrowse` contract\non a CAPTCHA is *stop and surface to the user* (`status:\nneeds_handoff`). This command is a low-level CLI primitive for hosts\nthat have their own out-of-band solver approved by the user and want\nto record that fact for the next `act`. Only call after a real CAPTCHA\non the current page has actually been solved externally. The marker\ndoes not bypass page state: if the next `act` still sees a CAPTCHA, the\nplanner returns `needs_handoff` again, meaning the solver did not\nactually clear the wall. Do not re-mark in that case; surface to the\nuser.\n\nThe marker auto-clears without error in three cases:\n\n- consumed by the next `act` (normal one-shot path);\n- TTL elapsed before the next `act` ran (default 300 seconds; override\n with `--ttl `, positive integer);\n- the active page identity at `act` time does not match the page\n identity recorded when the marker was written (the page changed in\n the meantime).\n\nExit codes: `0` on success, `1` on missing/invalid `--ttl`, an\nunexpected positional argument, no current session, or runtime error.\n\n## Deterministic Primitives (Layer 4)\n\nAll take a `` from the most recent `observe`. Target-ids\nare bare integers from `[N]text` lines. They are scoped\nto that single snapshot — re-run `observe` after any primitive that may\nchange the page state.\n\nPrimitive `status: \"completed\"` means the direct action ran. It is not a\ngoal-level completion check and does not prove that the intended page state is\nnow true. If the next step depends on changed page state, use a fresh\n`observe` result before deciding what to do next.\n\n### `magicbrowse observe`\n\nPrint the current public page snapshot (`plannerView`). Does not\naccept a prompt or any positional argument. Stdout carries the human\nsnapshot; stderr carries a one-line summary of fillable target counts.\n\nExit codes: `0` on success, `1` if any positional argument is passed.\n\n### `magicbrowse click `\n\nClick an observed action target.\n\n### `magicbrowse type `\n\nType text into an observed text target. `` is the rest of the\ncommand line; quote it if it contains spaces or shell metacharacters.\n\n### `magicbrowse fill `\n\nFill (replace) the current value of an observed text target.\n\n### `magicbrowse select `\n\nSelect a native `` option by visible label.\n\n### `magicbrowse press `\n\nSend a key chord to whatever the browser currently considers focused.\n**Not target-scoped**: there is no way to address a specific element.\n`click` an element first if focus matters. Examples: `Enter`,\n`Tab`, `Control+A`.\n\nAll primitives:\n\n- Return `0` on success and `1` on missing arguments.\n- Emit a JSON action result on stdout (blocked or executed).\n- Report direct action execution only; use `observe` or `act` when the\n orchestrator must verify page-state change.\n- Inherit the same approval boundary as `act`; do not click/press the\n final submit, save, delete, buy, book, accept, or send control unless\n the user explicitly approved that exact action or a matching typed MagicPay\n approval covers the unchanged page facts. Re-observe the page first.\n\n## Developer / One-Shot Compatibility\n\n### `magicbrowse run --url --goal \"\" [--use-vision]`\n\n**Forbidden in orchestrated workflows.** Compatibility wrapper for\n`launch + act + close`. The bundled `close` destroys session\ncontinuity and persistent agent state, so it is documented here only\nfor one-shot developer use through `--help`. Hosts running a\nmulti-step skill workflow must use `launch [url] → act … act → close`.\n\nExit codes follow `act`.\n\n## Environment Variables\n\n- `MAGICPAY_API_KEY` — API key for the gateway, alternative to\n `magicbrowse init`.\n- `MAGICPAY_API_URL` — override the bundled default gateway base URL.\n- `MAGICBROWSE_HOME` — root for per-run records and the singleton\n `current-session.json` (default `~/.magicbrowse`). Set distinct\n values per workflow for multi-tenant or parallel use.\n\n## Updating The CLI\n\nIf `magicbrowse --version` is missing or outdated, run\n`npm i -g @nuanu-ai/magicbrowse-cli@latest`, then verify with\n`magicbrowse --version`.\n\nFile v0.1.18:references/guardrails.md\n\n# MagicBrowse Guardrails\n\nThe Hard Rules from SKILL.md, expanded to long form.\n\n## Consequential Actions\n\n`magicbrowse` can navigate, inspect, draft, and prepare. It must not\nsilently commit an account-affecting or irreversible action.\n\nStop and ask the user before:\n\n- submitting a form;\n- posting or sending content;\n- accepting terms or confirming consent;\n- changing account data, account settings, permissions, or privacy\n controls;\n- booking, buying, ordering, subscribing, or paying;\n- deleting, overwriting, publishing, or otherwise modifying remote\n data.\n\nAfter approval, re-run `observe` so the target-id and visible state are\nfresh, then execute only the exact final action the user approved. If\nthe page changed meaningfully, ask again rather than widening the\napproval.\n\nA successful typed MagicPay approval counts for the exact payment, signing,\nor confirmation action it approved. Use it only while the approved page facts\nstay unchanged.\n\nWhen LLM-backed `act` reaches this boundary, it returns\n`status: needs_approval`. Treat that as a controlled stop, not a\nbrowser failure.\n\n## Memory Fill Boundary\n\nThe `magicbrowse` skill ends at the boundary of any memory fill.\nIt gets the host *to* the form; it never *into* it. Reach the page,\nstop before entering Memory values, and return the handoff to the\norchestrator or MagicPay Memory fill workflow.\n\n**Forbidden field categories.** Do not use `act`, `type`, `fill`, or\n`select` on:\n\n- **Login / signup credentials.** Email, username, password, OTP,\n TOTP, magic-link inputs, \"remember me\" toggles tied to credential\n entry, social-auth connectors that solicit OAuth credentials in the\n same flow.\n- **Identity-document fields.** Passport number, national ID number,\n KYC/AML address, date of birth tied to a verified identity,\n document expiry, document-issuing country, machine-readable-zone\n inputs, photo-of-document upload buttons.\n- **Payment-card and banking fields.** Cardholder name when bound to\n the PAN, PAN, CVV/CVC, expiry, IBAN, BIC/SWIFT, sort code, routing\n number, account number, billing-address fields when they are part\n of the card form.\n- **Vault- or secret-store-sourced values.** Any value whose origin is\n the user's Memory, password manager, or other Memory store, even if\n the field type itself looks generic.\n- **Any value you do not legitimately have.** If you do not know it,\n do not guess and do not fabricate.\n\nThe planner and navigator already refuse credential entry at the LLM\nlayer. This guardrail raises that refusal from a probabilistic LLM\nbehaviour to a host-facing contract: even if the planner *would*\nrefuse, the host must not attempt it. Stop before entering Memory-managed\nvalues, surface the situation to the user or orchestrator, and never invent\nor placeholder Memory values. Be honest about what `magicbrowse` cannot\ndo.\n\nThe narrow exception is **placeholder values to traverse an ordinary\nscreen during non-committal exploration** (e.g. typing dummy passenger\nnames to reveal the final fare in a flight-price check). Do not type\nreal identity data; use semantically obvious placeholders. The moment a\nfield starts asking for something Memory-managed, stop. If the flow is\nexpected to submit real data — booking, ordering, registering — do not\nplaceholder those fields at all: they are Memory-fill handoff targets,\nand placeholder values left in a real submission corrupt it. End the\ngranule at that form instead.\n\n## Act Before Snapshot Primitives\n\nWithin MagicBrowse, `act` is the default primitive. Do not begin a task\nwith `observe` plus `click`/`type`/`select`/`press`/`fill` unless `act`\nhas already failed to make progress on the same goal, or unless the\noperation is deliberately a single-element recovery step.\n\nThe navigator has the current page context, the natural-language goal,\nand its completion check in one planner loop. A host that starts from\nsnapshot ids has to preserve that intent externally while remembering\nthat every id expires after any page mutation or expected state change.\nThat is a recovery path, not the happy path.\n\nWhen primitives are necessary, re-run `observe` after every page\nmutation and use the fresh target id only for the next primitive.\nFor deterministic `click`/`type`/`fill`/`select`/`press`, a\n`status: \"completed\"` result means the direct action was dispatched through\nthe action layer. It does not certify that a higher-level page condition is\nnow true. If the next step depends on changed page state, branch on a fresh\n`observe` result. If the task needs its own completion check, use `act` with a\ncheckable terminal condition rather than treating a primitive result as task\nsuccess.\n\n## Singleton Session\n\n`$MAGICBROWSE_HOME/current-session.json` (default\n`~/.magicbrowse/current-session.json`) is a singleton pointer. Concurrent\nworkflows on the same home silently overwrite each other's session state —\nthe second `launch` becomes the current session, the first one is orphaned\nmid-task.\n\nFor multi-tenant or parallel use, set a distinct `MAGICBROWSE_HOME` per\nworkflow, or do not run the tasks in parallel. Per-user tools that may run\nmore than one `magicbrowse` flow simultaneously must scope homes per request,\nnot share the defaults.\n\nThis is not a security boundary — it is a correctness boundary.\nSharing default homes between concurrent workflows produces\nsilent cross-talk, not visible errors.\n\n## Browser Authority\n\nUse a fresh owned browser session by default. Existing CDP endpoints,\nnamed profiles, and explicit `--user-data-dir` paths may already be\nlogged in to real accounts. Acting through them inherits that browser's\nauthority even though `magicbrowse` never receives the password.\n\nOnly use `magicbrowse attach`, `--profile`, or `--user-data-dir` when\nthe user explicitly approves that browser/session for the current\ntask. The exception is the browser child MagicPay launched inside the\ncurrent approved product workflow: attaching to it is the normal\nin-workflow path for preparing pages in the same browser, not an\nexternal attach that needs separate approval. Keep CDP endpoints\nprivate and do not paste them into shared logs. Close or detach when\nthe overall browser workflow is done, and start a fresh session for\nunrelated work. If MagicBrowse handed the current page to\nanother tool or the user, wait until that handoff finishes before closing a\nMagicBrowse-owned disposable browser. Do not close an external/user-owned\nbrowser or approved attach without explicit teardown approval.\n\n## Page Context And Screenshots\n\nLLM-backed `act` sends page state to the gateway. `act --use-vision`\ncan include screenshots. Treat both as external processing of the\ncurrent page context.\n\nAvoid private, sensitive, or unrelated pages unless the user approves\nthat workflow. Do not use vision mode on sensitive pages unless it is\nexplicitly required and approved. At memory fills, stop and surface\nto the user.\n\n## CAPTCHA And Auth Walls\n\nBoth the planner and navigator are instructed to refuse to attempt\ncredential entry or solve CAPTCHAs. When `act` runs into either, it\nreturns `status: needs_handoff` with a `finalMessage` describing the\nwall and a machine-readable `handoff.kind` — *not* `status: failed`.\n\n- **Do not** retry the same `act` after a CAPTCHA or auth-wall handoff.\n The same prompt will hit the same wall.\n- **Do not** try to solve CAPTCHA through `magicbrowse`. MagicBrowse does not\n solve CAPTCHA.\n- **Do not** invent credentials, identity values, payment values, or\n CAPTCHA answers to get past the wall. Do not placeholder Memory-managed\n data either.\n- **Do** surface `finalMessage` to the user or orchestrator and branch on\n `handoff.kind`. For `memory_fill`, pass\n `{ kind: \"memory_fill\", resumeObjective }` to the approved\n Memory fill workflow, then call `magicbrowse act` with that\n `resumeObjective` after the fill completes. For `captcha`, have the user\n or an external solver clear it; after a successful solve, run\n `magicbrowse mark-captcha-resolved` before the next `act`. For `auth` or\n `identity_verification`, stop for the user or approved flow. If the next\n `act` still returns `needs_handoff`, the wall was not cleared; do not\n re-mark.\n\n## Diagnostics\n\n- `magicbrowse browser-status` inspects the live browser/page/runtime\n state. Use for debugging, not as a control-flow signal.\n- `magicbrowse doctor` inspects the gateway config. Use after\n `magicbrowse init` if `act` reports a missing-key error.\n- `magicbrowse close` is teardown or recovery, never a success\n signal. Task success or stop reason comes from the `act` `status`;\n `finalMessage` explains that outcome. Use it after handoff work is done,\n not as part of Memory handoff completion itself.\n- `magicbrowse act` can exit `0` for controlled stops such as `blocked`,\n `needs_handoff`, and `needs_approval`. Branch on `status`, not on the shell\n exit code.\n\n## Ask The User When\n\n- `doctor` fails and there is no configured API key available;\n- the environment cannot launch or attach to a Chrome session;\n- the task requires `attach`, `--profile`, or `--user-data-dir`;\n- `--use-vision` would expose screenshots of a private or sensitive\n page;\n- `act` returns `status: needs_handoff`;\n- `act` returns `status: blocked` because ordinary input or a\n different strategy is needed;\n- `act` returns `status: needs_approval`;\n- the next action would submit, post, send, save, delete, accept,\n book, buy, order, pay, publish, or otherwise commit a consequential\n change, and there is no matching typed MagicPay approval for unchanged page\n facts;\n- the task crosses into a memory fill — stop and surface, do not\n improvise, guess, or placeholder Memory values.\n\nFile v0.1.18:references/statuses.md\n\n# MagicBrowse Statuses\n\n## `act` Result Shape\n\n`magicbrowse act` returns:\n\n- `status: completed | blocked | needs_handoff | needs_approval |\n failed | max_steps | cancelled`\n- `finalUrl: string | undefined` — last URL the navigator observed\n- `finalMessage: string` — concise terminal report or stop explanation\n- `stepCount: number` — navigator step count\n- `blockedReason?: missing_input | item_unavailable | ambiguous | no_path`\n — required when `status` is `blocked`\n- `handoff?: { kind, resumeObjective? }` — required when `status` is\n `needs_handoff`\n\nJSON output shape:\n\n```json\n{\n \"type\": \"result\",\n \"status\": \"needs_handoff\",\n \"finalUrl\": \"https://merchant.example/checkout\",\n \"finalMessage\": \"CAPTCHA challenge shown before the address form.\",\n \"handoff\": { \"kind\": \"captcha\" },\n \"stepCount\": 14\n}\n```\n\nBranch on `status`, then on `blockedReason` or `handoff.kind` when\npresent. Do not parse `finalMessage` to distinguish task success,\nmissing input, handoff subtype, approval, runtime failure, max steps, or\ncancellation. Use `finalMessage` as text to show the user or pass to the\nupstream orchestrator.\n\nCLI exit codes:\n\n| `status` | exit code |\n| --- | ---: |\n| `completed` | `0` |\n| `blocked` | `0` |\n| `needs_handoff` | `0` |\n| `needs_approval` | `0` |\n| `failed` | `1` |\n| `max_steps` | `2` |\n| `cancelled` | `130` |\n\nA non-zero exit code means runtime failure, budget exhaustion, or\ncancellation. `blocked`, `needs_handoff`, and `needs_approval` are\ncontrolled browser-task stops and still exit `0`.\n\n## Status Meanings\n\n- `completed` — the delegated browser task reached the requested\n terminal state. Confirm with the visible evidence in `finalMessage`\n when the host needs an extra business-rule check.\n- `blocked` — MagicBrowse cannot continue because ordinary\n input is missing, the requested item is unavailable,\n the delegated task is ambiguous, or the page state has no reasonable\n page-control path left inside the task. Read `blockedReason`.\n- `needs_handoff` — the task reached Memory data or human\n verification: login, password, OTP, identity/KYC data, payment or\n banking fields, API keys/tokens/secrets, CAPTCHA, or a similar human\n check. Read `handoff.kind`. Surface `finalMessage` to the user and\n stop; do not retry through the barrier and do not invent or\n placeholder Memory values.\n- `needs_approval` — the next useful action would commit an external\n side effect such as buy, book, pay, send, post, publish, accept\n terms, delete, or save account settings. Ask for approval before the\n exact final action unless a matching typed MagicPay approval already covers\n the unchanged page facts.\n- `failed` — runtime, model, browser, or tool failure. Inspect\n `finalUrl` and the event stream before retrying.\n- `max_steps` — the planner did not converge inside the step ceiling.\n- `cancelled` — the act was cancelled mid-run, usually by SIGINT or a\n caller abort.\n\n## When `status: blocked`\n\nTreat this as a controlled stop. Branch on `blockedReason`:\n\n- `missing_input` — ask the user for the missing ordinary input.\n- `item_unavailable` — report that the requested item, route, result,\n appointment, or option is unavailable; do not retry the same page path.\n- `ambiguous` — ask the user to clarify the delegated browser task or\n required choice.\n- `no_path` — choose another strategy outside MagicBrowse, restart from\n a better entry point, or abort.\n\nDo not blindly rerun the same `act` goal.\n\n## When `status: needs_handoff`\n\nSurface `finalMessage` to the user or orchestrator and stop. The wall is\nreal and `magicbrowse` will not pass it. Do not retry the same `act`\nagainst the same wall. Do not invent credentials, identity values,\npayment values, or CAPTCHA answers, and do not placeholder Memory-managed\nfields to slip past.\n\nBranch on `handoff.kind`:\n\n- `memory_fill` — pass `{ kind: \"memory_fill\", resumeObjective }`\n to the orchestrator or MagicPay Memory fill workflow. After the\n Memory fill completes, call `magicbrowse act` with that page-local\n `resumeObjective`.\n- `captcha` — have the user or an approved external solver clear the\n CAPTCHA, then run `magicbrowse mark-captcha-resolved` before the next\n `act`.\n- `auth` — stop and ask the user to authenticate, approve the login, or\n provide the required auth step through an approved flow.\n- `identity_verification` — stop and ask the user to complete or approve\n the identity/KYC step through an approved flow.\n\n## When `status: needs_approval`\n\nAsk the user to approve the exact visible action and page state. After\napproval, re-run `observe` so target ids and page facts are fresh, then\nexecute only the approved action. If the page changed meaningfully,\nask again.\n\nA successful typed MagicPay approval is enough for the exact payment,\nsigning, or confirmation action it approved. Do not ask again while the page\nfacts remain unchanged.\n\n## When `status: max_steps`\n\nThe granule was likely too large or vague. Split it on a page-change\nboundary or tighten the expected terminal state before retrying. Raise\n`--max-steps` only when you have a specific reason to believe the task\nneeds the headroom.\n\n## Layer-4 Primitive Results\n\n`click`, `type`, `fill`, `select`, and `press` emit a JSON action\nresult on stdout. For these direct actions, `status: \"completed\"` means the\nprimitive ran through the action layer. It is not a semantic claim that the\nintended page state changed. When the next step depends on changed page state,\nre-`observe` and branch on the fresh snapshot. Use `act` for a delegated task\nthat needs its own completion check.\n\nCommon blocked reasons:\n\n- `target_not_found` — the `` does not match anything in\n the most recent observe snapshot. Re-`observe` and retry.\n- `unsupported_target` — the target is not the right kind for the\n action, such as `type` on a button. Re-read the observe snapshot for\n the correct kind.\n- `click_failed` / `input_failed` / `select_failed` / `press_failed`\n — the action reached the page but the page rejected it. Re-`observe`\n to see the new state.\n\n## Browser Session Errors\n\n- `magicbrowse launch` failure — the runtime could not start Chrome.\n Check permissions, keep the default headless mode unless a visible\n debug browser was explicitly requested, or switch to `attach` if a\n host browser is available.\n- `magicbrowse attach ` failure — the CDP endpoint is\n unreachable or rejected the connection. Verify the endpoint and\n retry.\n- `browser-status` reports the session unreachable mid-task —\n reconnect with `launch` or `attach`, then re-`observe`. Treat all\n pre-disconnect target ids as stale.\n\nFile v0.1.18:references/workflow.md\n\n# MagicBrowse Worked Example\n\nThis walkthrough shows the primary workflow end-to-end: reach the\ncheckout page of an airline meta-search, then stop at the payment\nboundary and surface to the user. The scenario assumes the runtime's\npage-control tool cannot drive the meta-search reliably.\n\n## Scenario\n\nThe user wants to know the final payable fare for a one-way flight from\nLondon to Lisbon next Tuesday for one passenger, before deciding whether\nto book. The orchestrator has already chosen `magicbrowse` as the\nfallback after the runtime's page-control tool failed to search\nthe site reliably.\n\n## Preflight\n\n```text\n$ magicbrowse doctor\n{ \"success\": true, ... }\n```\n\nHealthy. Proceed.\n\nIf `doctor` had failed, the orchestrator would ask the user for an\nAPI key (sign-up at `https://agents.mercuryo.io/signup`) and run\n`magicbrowse init ` once, then re-run `doctor`.\n\n## Granule 1 — Search\n\nPre-place the session at the entry URL. Headless is the default; the\nhost has no reason to surface the browser to the user.\n\n```text\n$ magicbrowse launch https://www.kayak.com/flights\n{ \"session\": { \"id\": \"...\", ... } }\n\n$ magicbrowse act \"Search one-way flights from London to Lisbon for next Tuesday for one adult passenger. End on the search results page.\"\n... planner / navigator events ...\n{ \"status\": \"completed\", \"finalMessage\": \"Search results displayed for LON → LIS, Tue 2026-05-12, 1 adult.\", ... }\n```\n\nThe granule ends at a strategic decision point: which result to\nchoose. That decision belongs between `act` calls, not inside one.\n\n## Granule 2 — Select a result\n\nThe orchestrator picks the first non-stop based on its own criteria\nand asks `magicbrowse` to navigate to that result's checkout entry.\n\n```text\n$ magicbrowse act \"Open the first non-stop result and proceed to the page that asks for passenger details.\"\n... ...\n{ \"status\": \"completed\", \"finalMessage\": \"Reached passenger details page on partner site (gotogate.com).\", ... }\n```\n\nNote: the planner navigated through a redirect from the meta-search to\na partner OTA. That is expected — do not add \"stay on the same host\"\nto the goal; it would break almost every real booking flow.\n\n## Granule 3 — Reach the Memory boundary\n\n```text\n$ magicbrowse act \"Fill the passenger first/last name and contact email with placeholder values, then proceed until the page shows the payment form. Do not enter any payment details yourself.\"\n... ...\n{ \"status\": \"needs_handoff\", \"finalMessage\": \"Payment page displayed with card number / expiry / CVV fields. Payment entry is Memory-managed — surface to the user.\", \"handoff\": { \"kind\": \"memory_fill\", \"resumeObjective\": \"Continue the checkout from the filled payment form to the next merchant response.\" }, ... }\n```\n\nThe goal explicitly reminds the planner not to enter payment details.\nThe planner and navigator already refuse credentials and payment\nfields by default; the explicit instruction is a belt-and-braces note\nfor the host's own log.\n\n> **Stop here.** The next step — typing into the payment fields — is\n> the Memory boundary. `magicbrowse` does not enter credentials,\n> identity data, or payment data. Surface `finalMessage` to the user\n> and let them decide what happens next. If the result includes\n> `handoff.kind: \"memory_fill\"`, pass that handoff to the orchestrator or\n> MagicPay Memory fill workflow. The page-control owner can resume with\n> `handoff.resumeObjective` after the Memory fill completes.\n\nPlaceholders were acceptable in this granule only because the task is\nnon-committal price exploration — nothing typed here is meant to be\nsubmitted as part of a real transaction. In a real booking, passenger\nidentity and contact fields are Memory-managed fill targets themselves:\nend the granule at that form and hand off to the Memory fill workflow\ninstead of typing placeholders that would end up inside a real order.\n\n## Surface and cleanup\n\nThe orchestrator passes `finalMessage` to the user along with the\ncurrent `finalUrl`. If the user closes the task here, release the\nsession:\n\n```text\n$ magicbrowse close\nclosed current magicbrowse session ...\n```\n\nIf the next step is a Memory fill workflow on the current page, do not close\nthe browser before that handoff completes. Keep the browser available for the\norchestrator, the user, or the MagicPay Memory fill workflow. Close only if\nMagicBrowse launched an owned disposable browser for this task and the user\ndoes not need to inspect or take over the page.\n\nIf the user instead takes over the browser themselves (or hands the\nlive CDP session to another tool they approved), the orchestrator\nleaves the session open and lets `magicbrowse close` be called later\nas teardown.\n\n## Failure Modes Encountered In This Scenario\n\n- **Auth wall on the partner site.** If the partner OTA gates the\n passenger form behind a sign-in, `act` returns\n `status: needs_handoff` with `handoff.kind: \"auth\"` and `finalMessage`\n asking the user to log in. The orchestrator surfaces that to the user; it\n does not retry into the auth wall.\n- **CAPTCHA.** Same status: `needs_handoff`, with\n `handoff.kind: \"captcha\"` and `finalMessage` describing the challenge.\n `magicbrowse` does not solve CAPTCHA. For a confirmed real CAPTCHA on the\n current approved browser session, have the user or an external solver clear\n it; after a successful solve, run `magicbrowse mark-captcha-resolved`\n before the next `act`. Do not invent an answer or retry the same `act`\n against the wall.\n- **Missing ordinary input.** `status: blocked` with\n `blockedReason: \"missing_input\"` means MagicBrowse needs ordinary\n input before it can continue. Other `blockedReason` values distinguish\n unavailable items, ambiguous tasks, and no remaining page-control path.\n- **Final booking/payment action.** `status: needs_approval` means the\n page is ready for a consequential action and the user must approve\n the exact visible action before it is executed. A successful typed MagicPay\n approval counts for that exact payment, signing, or confirmation action;\n ask again only if the approved page facts changed.\n- **`status: max_steps`.** The granule was too large or too vague.\n Split it on a page-change boundary or tighten the goal's terminal\n state, then retry.\n- **Stale meta-search state.** If the session has been open long\n enough for prices to drift, the host can `close` and re-`launch`\n to start clean instead of re-narrating into a follow-up `act`.\n\n## What Not To Do In This Scenario\n\n- ✗ A single `act \"book the cheapest non-stop London → Lisbon and pay\n with my card\"` — combines four strategic decisions into one task and\n crosses the memory-fill boundary.\n- ✗ `magicbrowse run --url ... --goal ...` — the bundled `close`\n destroys session continuity; a multi-step workflow must use\n `launch → act … act → close`.\n- ✗ Re-narrating prior context: `act \"as we already searched, now\n pick result 2\"` — sequential `act` calls preserve page state and\n planner memory; re-narration is a granularity smell.\n- ✗ Driving payment fields with `type` or `fill`, or placeholdering\n real card/identity data to push past the form. Stop at the boundary\n and surface to the user — never fabricate Memory values.\n\nFile v0.1.18:skill-card.md\n\n## Description:\n\nBrowser automation fallback through the magicbrowse CLI with goal-driven act as the default primitive and observe/primitives only for recovery, with changed page state verified by fresh observation.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[xor777](https://clawhub.ai/user/xor777)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agent runtimes use MagicBrowse when their native page-control tool cannot reliably navigate a public web flow, especially to reach a target page, inspect state, or prepare a browser handoff while respecting approval and sensitive-data boundaries.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Browser automation can expose page context, and vision mode can expose screenshots, to the third-party gateway.\n\nMitigation: Use fresh browser sessions by default, avoid private pages unless the workflow is approved, and use vision mode only when the user is comfortable sending screenshots or page context.\n\nRisk: Automated browser actions can commit external side effects such as submitting, buying, posting, saving, deleting, or changing account settings.\n\nMitigation: Stop for explicit user approval before consequential actions, re-run observe before the approved final action, and execute only the exact action that was approved.\n\nRisk: Attaching to an existing browser, named profile, or CDP endpoint can inherit logged-in account authority.\n\nMitigation: Prefer owned fresh sessions, use attach/profile/user-data-dir only with explicit approval for the current task, and keep CDP endpoints private.\n\nRisk: Pages may request credentials, identity details, payment data, CAPTCHA handling, or other Memory-managed values.\n\nMitigation: Stop and hand off at sensitive-data or human-verification boundaries; do not invent, placeholder, or enter credentials, identity, payment, banking, API key, or Memory-sourced values.\n\n## Reference(s):\n\n- [MagicBrowse ClawHub Skill Page](https://clawhub.ai/xor777/skills/magicbrowse)\n- [OpenClaw Marketplace README](https://github.com/nuanu-ai/skills/blob/main/docs/magicbrowse/openclaw/marketplace/README.md)\n- [MagicBrowse CLI Package](https://www.npmjs.com/package/@nuanu-ai/magicbrowse-cli)\n- [Command Guide](https://github.com/nuanu-ai/skills/blob/main/docs/magicbrowse/references/commands.md)\n- [Workflow Example](https://github.com/nuanu-ai/skills/blob/main/docs/magicbrowse/references/workflow.md)\n- [Guardrails](https://github.com/nuanu-ai/skills/blob/main/docs/magicbrowse/references/guardrails.md)\n- [Statuses](https://github.com/nuanu-ai/skills/blob/main/docs/magicbrowse/references/statuses.md)\n\n## Skill Output:\n\n**Output Type(s):** [Guidance, Shell commands, Configuration]\n\n**Output Format:** [Markdown guidance with inline shell commands and JSON status-handling examples]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Requires the magicbrowse CLI and MAGICPAY_API_KEY for gateway-backed act workflows.]\n\n## Skill Version(s):\n\n0.1.18 (source: server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v0.1.18:metadata.openclaw.json\n\n{\n \"homepage\": \"https://github.com/nuanu-ai/skills/blob/main/docs/magicbrowse/openclaw/marketplace/README.md\",\n \"requires\": {\n \"bins\": [\"magicbrowse\"]\n },\n \"primaryEnv\": \"MAGICPAY_API_KEY\",\n \"install\": [\n {\n \"id\": \"npm\",\n \"kind\": \"node\",\n \"package\": \"@nuanu-ai/magicbrowse-cli@latest\",\n \"bins\": [\"magicbrowse\"],\n \"label\": \"Install MagicBrowse CLI (npm)\"\n }\n ]\n}\n\nArchive v0.1.16: 8 files, 23612 bytes\n\nFiles: metadata.openclaw.json (407b), references/commands.md (9843b), references/guardrails.md (9692b), references/statuses.md (6681b), references/workflow.md (7224b), skill-card.md (3819b), SKILL.md (14668b), _meta.json (131b)\n\nFile v0.1.16:SKILL.md\n\n---\nname: magicbrowse\ndescription: Browser automation fallback through the magicbrowse CLI with\n goal-driven act as the default primitive and observe/primitives only for\n recovery, with changed page state verified by fresh observation.\nhomepage: https://www.npmjs.com/package/@mercuryo-ai/magicbrowse-cli\nmetadata:\n openclaw:\n homepage: https://github.com/MercuryoAI/skills/blob/main/docs/magicbrowse/openclaw/marketplace/README.md\n requires:\n bins:\n - magicbrowse\n primaryEnv: MAGICPAY_API_KEY\n install:\n - id: npm\n kind: node\n package: \"@mercuryo-ai/magicbrowse-cli@latest\"\n bins:\n - magicbrowse\n label: Install MagicBrowse CLI (npm)\n---\n\nUse `magicbrowse` to reach a target page when your runtime's own\npage-control tool cannot do it reliably. \"Page-control tool\"\nmeans a tool that drives browser pages programmatically and reports page state\nback — not the user's desktop browser, and not screen-control of a\nbrowser window. The planner runs two LLM loops per task and is slower\nthan direct browser control; prefer your own page-control tool\nwhen it suffices. Use `magicbrowse` to *reach* a target page (search, navigation,\ntraversal through non-sensitive screens). At any login, identity, checkout,\ndonation, subscription, payment, or human-verification page, stop and surface\nto the user — do not invent or type credentials, identity data, payment data,\nor any value you do not legitimately have.\n\nFor a MagicPay product/payment workflow, use the MagicPay workflow-first\nrecipe instead of treating a standalone MagicBrowse browser as the product\nparent: MagicPay starts the product session, then launches or attaches the\nbrowser as a child resource.\n\n## Fallback Ladder\n\nTry in order. Do not start at layer 4 just because primitives exist.\n\n1. **Your runtime's own page-control tool** — programmatic page\n control owned by your runtime. Screen-control (computer use) of an\n already-open desktop browser does not qualify: takeover needs the\n browser's CDP endpoint, a typical desktop browser starts without one,\n and CDP cannot be enabled on a running browser without a restart. If\n the session may need a MagicBrowse or MagicPay takeover mid-flow,\n start from a browser with a known private CDP endpoint.\n2. **`magicbrowse act \"\"`** — DOM-only navigator.\n3. **`magicbrowse act \"\" --use-vision`** — same goal, navigator\n with screenshots. Use only when the user is comfortable sending\n screenshots/page context for this workflow. Vision is a retry mode\n for the same task; keep the granule.\n4. **`magicbrowse observe` + primitives** —\n `click `, `type `,\n `fill `, `select `,\n `press `. Use only when vision-mode `act` cannot make\n progress, or when single-element precision is required. A primitive\n `completed` result means the direct action ran; it is not a semantic\n proof that the intended page state changed. Re-run `observe` before the\n next decision. `press` is global — `click` first if focus matters.\n5. **Surface failure to the user.**\n\n## Preferred Pattern\n\nFor public navigation tasks, give `act` the semantic goal and a checkable\nterminal condition:\n\n✓ `magicbrowse act \"navigate to the public page that lists supported regions and stop when the region list is visible\"`\n\nAvoid manually replaying snapshot ids before `act` has failed:\n\n✗ `magicbrowse observe` → `magicbrowse click 13` → `magicbrowse observe` → `magicbrowse click 23`\n\n## Setup Check\n\n1. Run `magicbrowse doctor` first on a fresh install. It verifies the\n gateway config and reachability.\n2. If it fails because the API key is missing, run\n `magicbrowse init ` (sign up at\n `https://agents.mercuryo.io/signup`).\n3. Only proceed to `launch` and `act` once `doctor` passes.\n\n## Hard Rules\n\n> **Consequential actions require approval.** `magicbrowse` may\n> navigate, inspect, draft, and prepare. It must stop and ask before\n> submitting a form, posting or sending content, accepting terms,\n> changing account data or settings, booking, buying, ordering,\n> deleting or modifying remote data, or otherwise committing an\n> irreversible or account-affecting action. After approval, re-run\n> `observe` and execute only the approved final action. A successful typed\n> MagicPay approval counts for that exact payment, signing, or confirmation\n> action; ask again only if the approved page facts changed.\n\n> **Memory-managed data — never invent.** Do **not** use `act`, `type`,\n> `fill`, or `select` for any of the following on any page:\n> - login or signup credentials (email, username, password, OTP),\n> - identity-document fields (passport, ID, KYC address, DOB tied to\n> identity),\n> - payment-card or banking fields (PAN, CVV, expiry, IBAN, account),\n> - any value sourced from a Memory or Memory store, or any value you\n> do not legitimately have.\n>\n> Reach the page, stop before entering Memory values, and return the\n> handoff to the orchestrator or MagicPay Memory fill workflow. Do not\n> guess, placeholder, or fabricate Memory values. Be honest about what\n> you cannot do.\n\n> **Use `act` before snapshot primitives.** Do not start MagicBrowse work\n> with `observe` plus `click`/`type`/`select`/`press`/`fill` before\n> attempting `act` on the same goal. Why: the navigator keeps the goal,\n> current page context, and completion check in one planner loop instead of\n> spreading them across fragile snapshot ids. Use primitives only after\n> DOM-only and vision-mode `act` cannot make progress, or when the recovery\n> step is deliberately single-element.\n\n> **Target-ids are snapshot-scoped.** Valid only for the `observe`\n> snapshot that produced them. Re-run `observe` after any primitive that\n> may change the page state before the next primitive — reusing an old id\n> silently addresses a different element.\n>\n> ✓ `observe` → `click 12` → `observe` → `type 7 \"hello\"`\n> ✗ `observe` → `click 12` → `type 7 \"hello\"`\n\n> **Primitive completion is not goal completion.** For deterministic\n> `click`/`type`/`fill`/`select`/`press`, `status: \"completed\"` means the\n> browser action was dispatched through the direct action layer. It does not\n> certify that a higher-level page condition is now true. If the next step\n> depends on changed page state, observe again and branch on the fresh page\n> state. If the task itself needs a completion check, use `act` with a\n> checkable terminal condition instead of interpreting a primitive result as\n> task success.\n\n> **One workflow per default home.** The current-session pointer at\n> `$MAGICBROWSE_HOME/current-session.json` (default `~/.magicbrowse/`) is a\n> singleton. Concurrent workflows on the same home overwrite each other. For\n> parallel use, set a distinct `MAGICBROWSE_HOME` per workflow, or do not run\n> the tasks in parallel.\n\n> **Fresh browser by default.** Prefer an owned, fresh browser session.\n> Use `attach`, `--profile`, or `--user-data-dir` only when the user\n> explicitly approves that browser/session for the current task. One\n> exception needs no separate approval: attaching to the browser child\n> that MagicPay launched inside the current approved product workflow —\n> that is the normal in-workflow bind of an owned disposable browser.\n> Keep CDP endpoints private. Close the session before unrelated work.\n\n> **Page context can leave the browser.** LLM-backed `act` sends page\n> state to the gateway; `--use-vision` can include screenshots. Avoid\n> private pages unless the user approves that workflow, and stop at login,\n> identity, checkout, donation, subscription, or payment pages.\n\n## Primary Workflow\n\nContract: `launch [url] → act … act → close`. Sequential `act` calls in\none session preserve page state and planner memory.\n\n1. `magicbrowse launch ` — start a headless owned Chrome session\n pre-placed at the entry URL. Keep browser launches headless unless\n the user explicitly asks for a visible browser or you are doing live\n debugging. To attach to an existing CDP browser instead, first get\n explicit user approval for that endpoint/session:\n `magicbrowse attach ` (positional, not a\n `--cdp-url` flag).\n2. `magicbrowse act \"\"` — natural-language browser step. Prompt is\n **positional**. `act` does **not** take `--url`; you cannot reset\n the page from inside `act`. To re-anchor, `close` and `launch` again.\n3. Repeat `act` for the next strategic granule.\n4. `magicbrowse close` — release the session when the overall\n MagicBrowse-owned browser task is done. If the workflow hands off to\n another tool or the user on a sensitive page, keep the browser open until\n that handoff completes. After the handoff completes, close only a\n MagicBrowse-owned disposable browser that the user is not taking over; do\n not close an external/user-owned attach without explicit approval.\n\n`magicbrowse run` exists in the CLI for one-shot developer use. **It\nis not part of this skill contract** — its bundled `close` destroys\ncontinuity. Do not use it in an orchestrated workflow.\n\n## Goal Granularity\n\n1. **Granule = atomic strategic segment.** End each `act` where the\n orchestrator needs the next strategic decision. Tactics (which form\n field first) live inside `act`; strategy (this partner is wrong, try\n another) lives between `act` calls.\n2. **Target horizon: 15-30 navigator steps per `act`; smaller is\n safer.** `maxSteps: 100` is a safety ceiling. The planner\n self-validates terminal status, so longer tasks have more room for\n false-positive completion. Prefer smaller granules when the success\n criterion cannot be checked externally.\n3. **Auth walls and CAPTCHA are hard boundaries, not obstacles.** A\n task that reaches auth, CAPTCHA, or human verification ends with\n `status: needs_handoff`, not `failed`. Plan tasks to end *at* such\n a wall, not through it. `magicbrowse` does not solve CAPTCHA and\n does not enter credentials. For a confirmed real CAPTCHA on the current\n approved browser session, have the user or an external solver clear it;\n after a successful solve, run `magicbrowse mark-captcha-resolved` before\n the next `act`. Branch on `handoff.kind`: `captcha` means solve/mark,\n `auth` means stop for user authentication, `identity_verification` means\n stop for user/KYC handling, and `memory_fill` means hand off to the\n MagicPay Memory fill workflow. Memory-fill handoffs include\n `resumeObjective`; after the approved handler fills the form, continue\n with that page-local objective. Never retry the same `act` against the\n same wall. If the page asks for something you cannot legitimately\n provide, be honest about it.\n4. **Rely on session memory; do not re-narrate.** Sequential `act`\n calls in one session preserve page state and planner memory. Do not\n write \"as we already found, continue with…\" into goals — if you\n feel the need to, the granularity is wrong.\n\n## Goal Formulation\n\n1. **No element indexes or selectors in goal text.** Indexes renumber\n on every DOM scan. Describe elements semantically.\n - ✗ `act \"click target 14\"`\n - ✓ `act \"click the 'Continue' button under the price summary\"`\n2. **Describe the expected terminal state where it adds a checkable\n criterion.**\n - ✗ `act \"get to checkout\"`\n - ✓ `act \"navigate to a checkout page that shows passenger fields and total fare\"`\n3. **Pass the starting URL to `launch`, not as a separate step.** To\n switch sites mid-workflow, either `close` and re-`launch`, or\n describe the navigation inside the goal text.\n\n## Common Mistakes\n\n> - Element indexes (`[14]`, `target 7`) in goal text.\n> - `magicbrowse run` for orchestrated multi-step workflows.\n> - `type` / `fill` / `select` / `act` on Memory-managed fields. Stop at\n> the form boundary; if `act` returns a memory-fill handoff, send it to\n> the orchestrator or MagicPay Memory fill workflow and then resume with\n> `handoff.resumeObjective`.\n> - Letting `act` submit, post, book, buy, save, delete, or otherwise\n> commit an account-affecting action without explicit approval or a matching\n> typed MagicPay approval for unchanged page facts.\n> - Trying to solve CAPTCHA through `magicbrowse`. On a confirmed real\n> CAPTCHA, have the user or an external solver clear it, then\n> `magicbrowse mark-captcha-resolved` before the next MagicBrowse step.\n> - Attaching to a logged-in browser or named profile without explicit\n> approval for the current task.\n> - Closing a browser that was handed to another tool or the user before the\n> overall task is actually done.\n> - Re-narrating prior `act` results into the next goal — sequential\n> `act` calls keep state.\n> - Skipping the `act`-first path and starting at layer 4\n> (observe + primitives).\n> - Reusing a target-id from before a page mutation.\n> - Treating a deterministic primitive's `completed` status as proof that\n> the intended page state changed.\n\n## Status and Errors\n\n`act` returns `status: completed | blocked | needs_handoff |\nneeds_approval | failed | max_steps | cancelled`. Branch on `status`;\ndo not parse `finalMessage` to detect missing input, Memory\nhandoff, handoff subtype, or approval stops. For `blocked`, branch on\n`blockedReason: missing_input | item_unavailable | ambiguous | no_path`.\nFor `needs_handoff`, branch on\n`handoff.kind: memory_fill | captcha | auth | identity_verification`.\n\nLayer-4 primitives return direct action results. Branch on their `status`\nand `reason`, but verify page-state assumptions with a fresh `observe`;\nprimitive `completed` is not a substitute for a goal-level completion check.\n`finalMessage` is the explanation to show the user or pass upstream.\nMemory-fill handoff details are in `handoff.resumeObjective`. Exit\ncode `0` includes `blocked`, `needs_handoff`, and `needs_approval`; it\ndoes not mean success.\nSee [references/statuses.md](https://github.com/MercuryoAI/skills/blob/main/docs/magicbrowse/references/statuses.md).\n\n## References\n\n- [references/commands.md](https://github.com/MercuryoAI/skills/blob/main/docs/magicbrowse/references/commands.md) — every CLI command.\n- [references/workflow.md](https://github.com/MercuryoAI/skills/blob/main/docs/magicbrowse/references/workflow.md) — worked end-to-end\n example.\n- [references/guardrails.md](https://github.com/MercuryoAI/skills/blob/main/docs/magicbrowse/references/guardrails.md) — long-form hard\n rules.\n- [references/statuses.md](https://github.com/MercuryoAI/skills/blob/main/docs/magicbrowse/references/statuses.md) — outcome codes and\n status handling.\n\nFile v0.1.16:_meta.json\n\n{\n \"ownerId\": \"kn76jq44xm9vvwz0h4grasjvax84b83f\",\n \"slug\": \"magicbrowse\",\n \"version\": \"0.1.16\",\n \"publishedAt\": 1781094653825\n}\n\nFile v0.1.16:references/commands.md\n\n# MagicBrowse Command Guide\n\nFull reference for the `magicbrowse` CLI. The skill workflow uses\n`launch`, `act`, `observe`, `click`/`type`/`fill`/`select`/`press`,\n`mark-captcha-resolved`, and `close`. Agent setup uses\n`magicbrowse init`, then `doctor`. Everything else is for diagnostics,\ncompatibility, or one-shot developer use.\n\nThe hard rules from `SKILL.md` apply to every command: use a fresh\nbrowser by default, get explicit approval before using an existing\nprofile/CDP session, stop before consequential actions unless a matching typed\nMagicPay approval covers unchanged page facts, and stop at memory fills —\nnever invent or placeholder Memory data.\n\n## Setup And Readiness\n\n### `magicbrowse init [--api-url ]`\n\nWrites the gateway config used by LLM-backed `act`. When `--api-url` is\nprovided, it also stores the gateway base URL. Omit `--api-url` for normal\nsetup; pass `--api-url ` only for a non-default staging, self-hosted, or\ntest gateway.\n\nCurrent CLI compatibility note: the persisted config path and environment\noverride names still use the existing `~/.magicpay/config.json`,\n`MAGICPAY_API_KEY`, and `MAGICPAY_API_URL` names. Treat these as gateway\nconfiguration names, not memory-fill ownership.\n\nExit codes: `0` on success, `1` if `` is missing.\n\n### `magicbrowse doctor`\n\nVerify the gateway config and reachability. Use this as the preflight\nbefore `launch` and `act`.\n\nExit codes: `0` if config is healthy, `1` if not.\n\n### `magicbrowse browser-status`\n\nInspect live browser/page/runtime state. Use for diagnostics only.\n\nExit code: `0`.\n\n## Session Lifecycle\n\n### `magicbrowse launch [url] [--headful] [--profile ]`\n\nStart an owned Chrome session and persist it as the current session.\nThe URL is **positional and optional**. Headless is the default;\n`--headful` is a debug/visible-browser override. Use it only when the\nuser explicitly asks for a visible browser or a live debugging protocol\nrequires it; do not add it to normal agent workflows or examples.\nAdvanced flags (`--user-data-dir`, `--chrome-path`, `--user-agent`)\naccept overrides for non-default Chrome layouts.\n\nPrefer a fresh owned profile. Use `--profile` or `--user-data-dir`\nonly after the user explicitly approves that browser state for the\ncurrent task.\n\nExit code: `0`.\n\n### `magicbrowse attach `\n\nAttach to an existing CDP browser as the current session. The\nendpoint is **positional**, not a `--cdp-url` flag.\n\nOnly attach to a private endpoint that the user provided or explicitly\napproved for the current task. Treat CDP endpoints as sensitive because\nthey inherit the authority of that browser session. Attaching to the\nbrowser child that MagicPay launched inside the current approved product\nworkflow is the normal in-workflow path and needs no separate approval;\nthe approval requirement targets external or user-owned browsers.\n\nExit codes: `0` on success, `1` if the endpoint is missing.\n\n### `magicbrowse close`\n\nClose or detach the current session. Always returns `0`.\n\nUse this only when the overall browser workflow is done or recovery requires\nteardown. If the current page was handed to another tool or the user, wait for\nthat handoff to finish before closing a MagicBrowse-owned disposable browser.\nDo not close an external/user-owned attach without explicit teardown approval.\n\n## Natural-Language Browser Step\n\n### `magicbrowse act \"\" [--max-steps ] [--use-vision] [--format ]`\n\nRun one natural-language browser step on the current session. The prompt is\n**positional** (use double quotes for any prompt with spaces). `act`\ndoes **not** take `--url`.\n\nUse `act` for navigation, inspection, drafting, and preparation. If\nthe next step would submit a form, post or send content, accept terms,\nchange account data/settings, book, buy, order, delete, save, or\notherwise commit an irreversible/account-affecting action, stop and\nask for explicit approval. After approval, re-run `observe` and do\nonly the approved final action. A matching typed MagicPay approval counts for\nthe exact payment, signing, or confirmation action while page facts stay\nunchanged.\n\nOptions:\n\n- `--max-steps ` — override the navigator step ceiling (default 100).\n- `--use-vision` — include screenshots in the navigator's view. Use as\n a retry mode for the same goal only when the user is comfortable\n sending screenshots/page context for this workflow.\n- `--format ` — output format. `json` emits JSON\n Lines suitable for an orchestrator. Default is `human`.\n\nExit codes (mapped from the act `status` field):\n\n- `0` — `completed`, `blocked`, `needs_handoff`, or\n `needs_approval`.\n- `1` — `failed` or missing prompt or missing gateway config.\n- `2` — `max_steps` (planner did not converge before the step ceiling).\n- `130` — `cancelled` (e.g. SIGINT).\n\n`blocked`, `needs_handoff`, and `needs_approval` are controlled\nbrowser-task stops, not runtime failures. Branch on `status`, then on\n`blockedReason` or `handoff.kind` when present; use `finalMessage` only\nas the explanation to show the user or upstream orchestrator.\n\n### `magicbrowse mark-captcha-resolved [--ttl ]`\n\nRecord that a real CAPTCHA on the current active page was solved by an\nexternal participant. This command does not solve CAPTCHA, click a CAPTCHA\nwidget, or prove success. It writes a one-shot trusted marker into the\ncurrent session, bound to the active page identity. The next `act`\nconsumes the marker, passes it to the planner/navigator as evidence that\na previously visible CAPTCHA was solved out-of-band, then clears it.\n\n**Not part of the skill workflow.** The default `magicbrowse` contract\non a CAPTCHA is *stop and surface to the user* (`status:\nneeds_handoff`). This command is a low-level CLI primitive for hosts\nthat have their own out-of-band solver approved by the user and want\nto record that fact for the next `act`. Only call after a real CAPTCHA\non the current page has actually been solved externally. The marker\ndoes not bypass page state: if the next `act` still sees a CAPTCHA, the\nplanner returns `needs_handoff` again, meaning the solver did not\nactually clear the wall. Do not re-mark in that case; surface to the\nuser.\n\nThe marker auto-clears without error in three cases:\n\n- consumed by the next `act` (normal one-shot path);\n- TTL elapsed before the next `act` ran (default 300 seconds; override\n with `--ttl `, positive integer);\n- the active page identity at `act` time does not match the page\n identity recorded when the marker was written (the page changed in\n the meantime).\n\nExit codes: `0` on success, `1` on missing/invalid `--ttl`, an\nunexpected positional argument, no current session, or runtime error.\n\n## Deterministic Primitives (Layer 4)\n\nAll take a `` from the most recent `observe`. Target-ids\nare bare integers from `[N]text` lines. They are scoped\nto that single snapshot — re-run `observe` after any primitive that may\nchange the page state.\n\nPrimitive `status: \"completed\"` means the direct action ran. It is not a\ngoal-level completion check and does not prove that the intended page state is\nnow true. If the next step depends on changed page state, use a fresh\n`observe` result before deciding what to do next.\n\n### `magicbrowse observe`\n\nPrint the current public page snapshot (`plannerView`). Does not\naccept a prompt or any positional argument. Stdout carries the human\nsnapshot; stderr carries a one-line summary of fillable target counts.\n\nExit codes: `0` on success, `1` if any positional argument is passed.\n\n### `magicbrowse click `\n\nClick an observed action target.\n\n### `magicbrowse type `\n\nType text into an observed text target. `` is the rest of the\ncommand line; quote it if it contains spaces or shell metacharacters.\n\n### `magicbrowse fill `\n\nFill (replace) the current value of an observed text target.\n\n### `magicbrowse select `\n\nSelect a native `