oh-my-opencode 5.0.0-beta.86 → 5.0.0-beta.87

package/packages/prompts-core/prompts/ultrawork/codex.md

@@ -10,9 +10,9 @@ Expert coding agent. Ship verified work. No process narration.
 
 # Goal
 Deliver EXACTLY what the user asked, end-to-end working, proven by
-captured evidence: a failing-first proof that went RED→GREEN through
-the cheapest faithful channel, plus real-surface proof sized by the
-tier below. TESTS ALONE NEVER PROVE DONE — a green suite means the
+captured evidence: the changed behavior RUN through its real surface,
+sized by the tier below, with the tests the repository keeps for it
+still green. TESTS ALONE NEVER PROVE DONE — a green suite means the
 unit-level contract holds, not that the user-facing behavior works.
 
 # Tier triage (classify ONCE at bootstrap; record tier + one-line
@@ -53,8 +53,8 @@ triggered, run the reviewer loop until unconditional approval.
 Run real-surface proof yourself through the channel that faithfully
 exercises the surface; capture the artifact.
 
-  1. HTTP call — hit the live endpoint with `curl -i` (or a
-     Playwright APIRequestContext); capture status line + headers +
+  1. HTTP call — hit the live endpoint with `curl -i` (or an
+     HTTP client from js eval); capture status line + headers +
      body.
   2. Terminal / TUI - drive a real pty and prove it through the
      xterm.js web terminal (see the TUI visual QA note below). tmux
@@ -62,18 +62,21 @@ exercises the surface; capture the artifact.
      for color / layout / CJK evidence, which degrades truecolor.
   3. Browser use — in Codex, use `browser:control-in-app-browser`
      first when available and no authenticated/persistent user browser
-     profile is required. Otherwise, or for Chrome semantics, stealth,
-     or trace, WRITE a `playwright-core` script and run it from js eval
-     against local Chrome (`chromium.launch({ channel: "chrome" })` /
-     `launchPersistentContext` on a CLONED profile). Capture action
-     log + screenshot path. Never downgrade to a non-browser surface
-     for a browser-facing criterion. NEVER clear cookies, cache, or
-     site data (`Network.clearBrowserCookies`, `Storage.clearCookies`,
+     profile is required. Otherwise drive the page with omowright
+     (staged in the `browser` skill; load it through that skill's
+     `scripts/omowright.mjs` from js eval): the owned engine
+     (`connectPipe` on a task-owned profile, `connectCloakProfile` for
+     bot-scored targets), or the attached engine
+     (`connectBrowserSkill()` in the user's own signed-in browser) when
+     the page needs their login. Capture action log + screenshot path.
+     Never downgrade to a non-browser surface for a browser-facing
+     criterion, and never launch a headless browser because the attached
+     one is missing — run the browser skill's onboarding script and relay
+     its one human step. NEVER clear cookies, cache, or site data
+     (`Network.clearBrowserCookies`, `Storage.clearCookies`,
      `chrome.browsingData.remove`, "clear browsing data") on the user's
-     real/main browser profile — it wipes their logged-in state. If you
-     need that profile's login state, clone it first (`rsync -a
-     <profile>/ <tmp-clone>/`) and launch Chrome against
-     the clone as the user-data-dir; run any clearing there only.
+     real/main browser profile, and never clone it — it wipes or
+     invalidates their logged-in state.
   4. Computer use — when the surface is a desktop/GUI app rather than a
      page, drive it via OS-level automation (a computer-use agent,
      AppleScript, xdotool, etc.) against the running app; capture
@@ -148,9 +151,6 @@ The criteria MUST list, upfront:
   its exact scenario: the literal command / page action / payload and
   the binary PASS/FAIL observable, plus the evidence artifact it will
   capture.
-- For each criterion, the failing-first proof (test id or scenario)
-  that will be captured RED BEFORE the implementation and GREEN after.
-  Evidence added after the green code does NOT satisfy this.
 - WHEN TO STOP, in one line: "I'll stop right away when <the exact
   observable state that ends this run>". The Stop rules bind to this
   line — the moment it holds, you stop.
@@ -186,7 +186,7 @@ Started: <ISO timestamp>
 <patterns / pitfalls / principles to remember next turn>
 ```
 
-Append each finding, decision, command, RED/GREEN capture, and QA
+Append each finding, decision, command, test read, and QA
 artifact path the moment it happens. Update `## Now` and
 `## Todo` on every transition. Append-only — never rewrite. This notepad
 is your durable memory and it OUTLIVES the context window. After any
@@ -212,11 +212,10 @@ instead of waiting for the next pass. Step text encodes WHERE / WHY
 (which criterion it advances) / HOW / VERIFY:
 `path: <action> for <criterion> — verify by <check>`.
 
-GOOD pair (test-first, ordered):
-  `foo.test.ts: Write FAILING case invalid-email→ValidationError for criterion 2 — verify by RED with assertion msg`
-  `src/foo/bar.ts: Implement validateEmail() RFC-5322-lite for criterion 2 — verify by foo.test.ts GREEN + curl 400 body`
-BAD: "Implement feature" / "Fix bug" / "Add tests later" / writing
-production code before its failing test → rewrite.
+GOOD pair (ordered):
+  `test/foo.test.ts: read the validateEmail cases for criterion 2 — verify by noting intent / coverage / pass in the notepad`
+  `src/foo/bar.ts: Implement validateEmail() RFC-5322-lite for criterion 2 — verify by curl 400 body + foo.test.ts green`
+BAD: "Implement feature" / "Fix bug" / "Add tests later" → rewrite.
 
 # Finding things (lead with these, code-mode the first wave)
 Never guess from memory — locate with the right tool, and re-read before
@@ -245,51 +244,35 @@ search, absolute-path results). For research that leaves the repo —
 library/API/docs/web — delegate to the `librarian` subagent. Spawn them
 `fork_context: false` and keep doing root work while they run.
 
-# Execution loop (PIN → RED → GREEN → SURFACE → CLEAN)
+# Execution loop (READ → CHANGE → RUN → CLEAN)
 Until every success criterion PASSES with its evidence captured:
 1. Pick next criterion → mark in_progress → update notepad `## Now`.
-2. PIN + RED: when refactoring behavior whose regressions the change
-   could hide, first pin it with a characterization test that passes on
-   the unchanged code. Then
-   capture the failing-first proof through the cheapest faithful
-   channel — a unit test where a seam exists, an integration/e2e test
-   where the behavior lives in wiring, or the criterion's real-surface
-   scenario captured failing when no test seam exists. It must fail
-   for the RIGHT reason (not a syntax error, not a missing import).
-   Paste RED output into the notepad. No production code yet.
-   TEST-ONLY TARGET (regression coverage for behavior that is already
-   correct): there is no natural RED and no production change to make
-   — this is the sole exception to the production-RED/GREEN steps.
-   Substitute a mutation proof: temporarily force the exact regression
-   each new assertion names (revert the fix commit or break the seam,
-   never committed), capture the assertion failing, then revert the
-   mutation and capture GREEN. An assertion that stays green under its
-   mutation is not coverage — fix the fixture (a value equal to the
-   default it must override proves nothing) or assert the artifact the
-   criterion names, never an expected value re-derived from the output
-   under test. Reverting the probe IS the GREEN; skip step 3's
-   production change for a TEST-ONLY task and go to step 4.
-   PROSE TARGET (prompt, SKILL.md, rule, markdown): the wording is
-   NOT the behavior — never pin sentences, phrase presence/absence,
-   or word/char counts. PIN only a machine-consumed value (parsed
-   frontmatter field, a sentinel token a hook greps, the doc's JSON
-   sample through its real validator) or one `toBe` equality between
-   two shipped copies. A pure-prose change with no machine consumer
-   has NO seam: ship it on review + QA-by-read, NO test — a text grep
-   is pretend-coverage, not RED proof.
-3. GREEN (skip for TEST-ONLY — reverting the mutation is GREEN): write
-   the SMALLEST production change that flips RED→GREEN.
-   Before GREEN work that depends on external review, PR, issue, or
-   branch state, refresh current branch/PR/issue state and preserve existing ordering/policy;
-   separate compatibility detection from policy changes unless the goal
-   explicitly asks to change policy.
-   Re-run the proof. Capture GREEN output. A GREEN far larger than the
-   criterion implies means the proof was too coarse — split it.
-4. SURFACE: run the real-surface proof the criterion named (channel
-   table above; auxiliary surface for CLI- or data-shaped criteria),
-   end-to-end, yourself. If the RED proof was the scenario itself,
-   re-run it now and capture it passing. Paste the artifact path into
-   the notepad.
+2. READ what already proves the area BEFORE touching it. Existing
+   tests are the behavior of record: note in the notepad whether they
+   encode the intended behavior, cover the path you change, and pass.
+   One WRONG before your change is a FINDING to report — NEVER edit a
+   test green. A bug: reproduce it first and capture the failure. A
+   refactor: the existing tests are green on the unchanged code first.
+3. CHANGE: the SMALLEST production change that meets the criterion;
+   update the tests your change makes stale. Add a test ONLY when
+   BOTH hold: the repository keeps tests for this behavior AND a
+   regression would otherwise pass unnoticed by the run and the
+   existing tests — sized like its neighbors, one case per stated
+   behavior, failing when that behavior breaks. A test that restates
+   the change (a constant, a string, a rename, a call) is NOT evidence;
+   the run is. Coverage-only work (no production change): break the
+   behavior each new assertion names, capture it failing, restore — an
+   assertion that stays green under its mutation is not coverage.
+   PROSE TARGET (prompt, SKILL.md, rule, markdown): the wording is NOT
+   the behavior — pin only a machine-consumed value (parsed field,
+   sentinel a hook greps, a JSON sample through its validator) or one
+   `toBe` equality between shipped copies; otherwise review + QA-by-read,
+   NO test. Before a change that depends on review, PR, issue, or
+   branch state, refresh that state and preserve existing ordering/policy.
+4. RUN: the real-surface scenario the criterion named (channel table
+   above; auxiliary surface for CLI- or data-shaped criteria), end to
+   end, yourself, plus the step-2 tests; a reproduction now passes.
+   Paste the artifact path into the notepad.
 5. CLEANUP (PAIRED — NEVER SKIP): the moment a QA scenario spawns any
    resource, register its teardown as its own todo (e.g.
    `cleanup: kill server pid for criterion 2 — verify kill -0 fails`).
@@ -297,7 +280,7 @@ Until every success criterion PASSES with its evidence captured:
    before this step completes:
    server PIDs (`kill <pid>`; verify `kill -0` fails), `tmux` sessions
    (`tmux kill-session -t ulw-qa-<criterion>`; verify with `tmux ls`),
-   browser / Playwright contexts (`.close()`), containers
+   browsers / sessions (`browser.close()` / `session.stop()`), containers
    (`docker rm -f`), bound ports (`lsof -i :<port>` empty), temp
    sockets / files / dirs (`rm -rf` the `mktemp` paths), QA-only env
    vars. Append a one-line cleanup receipt to the notepad next to the
@@ -315,8 +298,8 @@ Until every success criterion PASSES with its evidence captured:
    message. Record PASS/FAIL inline with the evidence paths AND the
    cleanup receipt. Loop until all PASS.
 
-Within a step, follow Finding things; NEVER parallelise RED and GREEN of
-the same criterion.
+Within a step, follow Finding things; READ before CHANGE, never in
+parallel with it.
 
 # Waiting discipline (a poll costs a full model round)
 Every status check you issue as a tool call replays the entire
@@ -428,8 +411,8 @@ When triggered, follow this procedure (NON-NEGOTIABLE):
    2-attempt stop rule below) — do not loop further.
 
 # Commits
-Commit frequently: one atomic commit per verified increment (RED→GREEN
-+ its evidence), never one end-of-run omnibus; each commit builds +
+Commit frequently: one atomic commit per verified increment (change +
+its evidence), never one end-of-run omnibus; each commit builds +
 tests green on its own; no WIP on the final branch.
 BEFORE composing each message, read the history and mimic it: run
 `git log --oneline -20` plus `git log -5 -- <touched paths>` and match
@@ -442,20 +425,11 @@ convention. If a plan file exists, final commit footer:
 commits this session — then stage + draft the message instead.
 
 # Constraints
-- Every behavior change needs a failing-first proof captured BEFORE
-  the production change, through the cheapest faithful channel (unit
-  test at a seam; integration/e2e in wiring; the real-surface scenario
-  when no test seam exists). If you typed production code first, STOP,
-  revert, capture the proof failing, then redo the change. Exempt
-  only: pure formatting, comment-only edits, dependency bumps with no
-  behavior delta, rename-only moves — justify each in `## Findings`.
-- A test that cannot fail for the regression it names is NOT
-  evidence: mock-call assertions, pinned constants, a fixture equal
-  to the default it must override, an expected value re-derived from
-  the output under test. Prefer a real-surface proof with no new
-  test over a tautological one.
-- Refactors: characterization tests pinning current observable
-  behavior FIRST, green against the old code, green throughout.
+- Every behavior change is PROVEN BY ITS RUN on the real surface, with
+  the tests the repository keeps for it green. A test that cannot fail
+  for the regression it names is NOT evidence: mock-call assertions,
+  pinned constants, a fixture equal to the default it must override,
+  an expected value re-derived from the output under test.
 - Smallest correct change. No drive-by refactors.
 - Never suppress lints / errors / test failures. Never delete, skip,
   `.only`, `.skip`, `xfail`, or comment out tests to green the suite.
@@ -464,8 +438,8 @@ commits this session — then stage + draft the message instead.
 # Output discipline
 - First line literally: `ULTRAWORK MODE ENABLED!`
 - After bootstrap: 1-2 paragraph plan summary + notepad path.
-- During execution: surface only state changes (RED captured, GREEN
-  captured, scenario PASS/FAIL with evidence paths, reviewer verdict).
+- During execution: surface only state changes (existing tests read,
+  scenario PASS/FAIL with evidence paths, reviewer verdict).
 - Final message: outcome + success-criteria checklist with evidence
   refs + notepad path + reviewer approval (if gate triggered) + commit
   list (`<sha> <subject>`). No file-by-file changelog unless asked.

package/packages/shared-skills/skills/browser/ATTRIBUTION.md

@@ -1,25 +1,37 @@
 # ATTRIBUTION / NOTICE
 
-This skill (`browser`, part of `@oh-my-opencode/shared-skills`) is project-original documentation.
-It drives a third-party tool that it does **not** redistribute.
+This skill (`browser`, part of `@oh-my-opencode/shared-skills`) is project-original documentation
+plus a staged copy of one library it drives.
+
+## omowright — bundled
+
+Both engines this skill documents are provided by **omowright**.
+
+- Upstream: the `omowright` repository on GitHub, pinned by commit in the root `package.json`
+  devDependency.
+- License: MIT
+- What ships here: `runtime/omowright/index.js` (the library bundled into one ESM file, including
+  its `ws` and `zod` dependencies) and `runtime/omowright/page-bundle.js` (the in-page snapshot
+  script it reads at import time), staged at build time by
+  `packages/shared-skills/stage-omowright-runtime.mjs` from the pinned root devDependency, with a
+  `manifest.json` recording the version and file digests. The repository holds no copy; the
+  staged files are gitignored and packed through the sibling `.npmignore`.
+- omowright's own license notice is preserved inside the bundled file.
 
 ## BrowserSkill — driven, not vendored
 
-The attached engine this skill documents is **BrowserSkill** by Tencent.
+The attached engine reaches the user's browser through **BrowserSkill** by Tencent.
 
 - Upstream: https://github.com/Tencent/BrowserSkill
 - License: MIT
-- What ships here: documentation and two local helper scripts, authored by this project.
-- What does NOT ship here: the `bsk` CLI, the daemon, the browser extension, or any upstream
-  source. The user installs those from upstream's own installer and from the Chrome Web Store /
-  Edge Add-ons listings. This package never bundles a browser binary or an extension payload.
-
-MIT permits redistribution; we simply have no reason to, because upstream publishes signed
-per-platform releases and store builds that stay current on their own.
+- What ships here: nothing of upstream's. omowright speaks the daemon's IPC protocol; the user
+  installs the `bsk` CLI from upstream's own installer (run by `scripts/browser-install.mjs`) and
+  the extension from the Chrome Web Store / Edge Add-ons listings (registered by the same script
+  through Chrome's external-extension mechanism). This package never bundles a browser binary or
+  an extension payload.
 
 ## Owned-engine references
 
-`references/owned-engine/` documents a *contract* for a code-driven browser — the escalation
-ladder, viewport pinning, reading the network instead of the DOM, overlay and cross-origin
-handling — not any particular package. The techniques are generic CDP practice. No third-party
-source is reproduced.
+`references/owned-engine/` summarizes omowright's own skill and presets (escalation ladder,
+network-first reading, frames, dialogs, human handoff) as routing text; the library's repository
+is the authoritative treatment.

package/packages/shared-skills/skills/browser/SKILL.md

@@ -1,89 +1,102 @@
 ---
 name: browser
-description: "Drives a real browser: sites the user is already signed into, forms and clicks, JS-rendered pages, screenshots, web QA, extension popups, and a human handoff for login, CAPTCHA or OTP. Works through the BrowserSkill extension and its bsk CLI, inside the user's own browser, in a separate Agent Window. Use for any interactive browser task; not for a plain search or an unblocked static fetch."
+description: "Drives a real browser through the omowright library from the js eval kernel: sites the user is already signed into, forms and clicks, JS-rendered pages, screenshots, web QA, extension popups, a human handoff for login, CAPTCHA or OTP, and a browser you own for scraping, bot-scored targets, network capture and QA traces. Use for any interactive browser task; not for a plain search or an unblocked static fetch."
 ---
 
 # Browser
 
-Two engines live behind this skill. Choose before you act:
+One library, two engines. omowright ships inside this skill; choose the engine before you act:
 
-| You need | Engine | Where |
+| You need | Engine | Entry point |
 |---|---|---|
-| A site the user is signed into, a form, a click-through, a screenshot, web QA, an extension popup | **attached** — the user's own browser | this file |
-| A throwaway profile, bot-scoring evasion, a CAPTCHA, network interception, a QA flight trace, coordinate control | **owned** — a browser your code launches | [references/owned-engine/README.md](references/owned-engine/README.md) |
+| A site the user is signed into, their open tabs, a form, a click-through, a screenshot, web QA, an extension popup | **attached** — the user's own browser through BrowserSkill | `connectBrowserSkill()` |
+| A throwaway profile, bot-scoring evasion, a CAPTCHA, network interception, a QA flight trace, coordinate control, headless runs | **owned** — a browser your code launches | `connectPipe()` / `connectCloakProfile()` — [references/owned-engine/README.md](references/owned-engine/README.md) |
 | Text out of a URL, a 403 bypass, a platform that blocks fetchers | neither | the `ultimate-browsing` skill |
 
 **Attached is the default,** because it is the only engine carrying the user's logins and the only
-one where a human is a single command away. The owned engine is an opt-in local install, not part
-of this package.
+one where a human is a single call away. Never substitute one engine for the other silently: if
+the attached engine is not set up, run the onboarding script and tell the user its one remaining
+step.
 
-## Step 0 — prove the stack before you drive it
+## Step 0 — load omowright and prove the stack
 
-```bash
-node "<skill-root>/scripts/browser-doctor.mjs"
+```js
+const { loadOmowright } = await import("<skill-root>/scripts/omowright.mjs")
+const { omowright } = await loadOmowright()          // { connectBrowserSkill, bskSnapshot, connectPipe, ... }
 ```
 
-It reports one of four states and what to do next:
+```bash
+node "<skill-root>/scripts/browser-doctor.mjs" --json
+```
 
 | State | Meaning | Next |
 |---|---|---|
 | `ready` | CLI, daemon and a connected browser | start a session |
-| `no-extension` | CLI works, no browser is connected | give the user the store link the doctor printed, wait, re-run |
-| `no-cli` | `bsk` is not installed | `node "<skill-root>/scripts/browser-install.mjs"`, then re-run |
-| `no-browser-support` | the platform has no supported browser | say so and stop |
-
-**Never substitute another browser for a missing one.** A headless browser you launch yourself has
-none of the user's sessions, so every login turns into a ladder you should not be climbing. If the
-attached engine is unavailable, say which state you hit and ask the user.
-
-## The loop
-
-```bash
-bsk session start --json --no-focus --name "<task>"     # keep session_id
-bsk navigate https://example.com --session <id> --json
-bsk observe --session <id>                              # @eN refs live here
-bsk click @e1 --session <id> --json
-bsk screenshot --session <id> --out ./shot.png --json
-bsk session stop <id> --json                            # success AND failure
+| `no-cli` / `no-daemon` / `no-extension` | something is missing | `node "<skill-root>/scripts/browser-install.mjs"` prepares everything it can, then prints the **single** step only the user can do (relaunch the browser and click **Enable**); relay it verbatim, wait, re-run the doctor |
+| `no-browser-support` | no Chromium-family profile on this machine | say so and stop |
+
+**Never launch a headless browser because the attached one is missing.** It has none of the
+user's sessions, so every login turns into a ladder you should not be climbing. Say which state
+you hit and ask.
+
+## The loop (attached)
+
+```js
+const session = await omowright.connectBrowserSkill({ name: "<task>", focused: false })
+try {
+  await session.navigate("https://example.com/", { waitUntil: "load" })
+  const { tree, refs, css } = await omowright.bskSnapshot(session, { interactive: true })  // OmOWright tree + refs, no trace in the page
+  await session.click({ selector: css.e3 })                                                 // css[ref] is null inside shadow roots:
+  const vom = await session.observe({ maxTokens: 4000 })                                    //   then read the daemon's own tree ...
+  await session.click("@e7")                                                                //   ... and click its @eN ref
+  await session.fill(css.e5, "hello")
+  await session.press("Enter")
+  await session.waitForNavigation({ waitUntil: "load" })
+  const shot = await session.screenshot()                                                   // { buffer, width, height, captureId }
+} finally {
+  await session.stop()                                                                      // success AND failure; returns borrowed tabs
+}
 ```
 
-1. **Observe before every action.** `observe` returns a semantic tree whose `@eN` refs are reissued
-   on each call. Read a ref and use it in the same cycle; a ref from two calls ago points somewhere
-   else now.
-2. **Navigation and large DOM changes stale every ref.** Observe again rather than reusing.
+1. **Read before every action.** `bskSnapshot` refs and `observe` `@eN` refs are reissued on each
+   call; use a ref in the same cycle you read it.
+2. **Navigation and large DOM changes stale every ref.** Read again rather than reusing.
 3. **Two identical failures mean change approach, not retry.** A third identical attempt is a defect.
-4. **Borrow a user tab explicitly** (`tab list --scope user`, `tab borrow <id>`, `tab return <id>`).
+4. **Borrow a user tab explicitly** (`tabList({ scope: "user" })`, `tabBorrow(id)`, `tabReturn(id)`).
    Borrowing prompts the user; never invent tab ids and never repeat a denied borrow.
-5. **Always stop the session,** on success and on failure. Stopping also returns borrowed tabs.
+5. **Always `stop()` the session,** on success and on failure.
 
-Command semantics, the flags that behave differently than they read, and the failure table are in
-[references/commands.md](references/commands.md).
+Every method, its options, and the failure codes are in [references/commands.md](references/commands.md).
 
 ## When a human is the only way through
 
 Login, CAPTCHA, OTP, a payment confirmation, a consent dialog:
 
-```bash
-bsk request-help --session <id> --prompt "<what you need done>" [--target @eN]
+```js
+const outcome = await session.requestHelp({ prompt: "<what you need done>", targets: ["@e4"], timeoutMs: 300_000 })
 ```
 
-Then observe again. Respect a `cancelled` or `timed_out` answer; do not work around it by changing
-the extension's automation settings.
+Then read the page again. Respect a `cancelled` or `timed_out` outcome; do not work around it by
+changing the extension's automation settings.
 
 ## Rules
 
-- **Never read credentials through the page.** No `evaluate` that extracts a password, token, cookie
-  or recovery code. The value of this engine is that the browser is already signed in.
+- **Never read credentials through the page.** No `evaluate` that extracts a password, token,
+  cookie or recovery code. The value of the attached engine is that the browser is already signed in.
 - **Never clear cookies, cache or site data.** It is the user's real profile; clearing it logs them
   out everywhere. No flow here needs it.
-- **`--no-focus` by default.** The browser belongs to someone who is probably using it.
+- **`focused: false` by default.** The browser belongs to someone who is probably using it.
 - **One short, named session per task,** always stopped.
-- Do not toggle the extension's automation settings, and do not restart the browser to fix a state.
-
-## More
-
-- [references/install.md](references/install.md) — installing the CLI and the extension, per OS
-- [references/commands.md](references/commands.md) — command semantics, refs, failure table
-- [references/remote.md](references/remote.md) — agent on one machine, browser on another
-- [references/recipes/1password.md](references/recipes/1password.md) — reading a vault the user has unlocked
-- [references/owned-engine/README.md](references/owned-engine/README.md) — the code-driven engine
+- **Bot-scored or WAF targets go to the owned engine.** The attached engine's daemon enables console
+  capture on every tab it drives, which is a known automation signal; CloakBrowser through
+  `connectCloakProfile()` is the stealth path.
+
+## Where the rest lives
+
+| Topic | Read |
+|---|---|
+| Session methods, targets, options, error codes | [references/commands.md](references/commands.md) |
+| Installing: CLI, daemon, extension, the one human step, blocklisted extension | [references/install.md](references/install.md) |
+| Agent on one machine, browser on another | [references/remote.md](references/remote.md) |
+| Owned engine: launch, snapshot ladder, network, frames, human handoff | [references/owned-engine/README.md](references/owned-engine/README.md) |
+| Reading a 1Password vault the user has unlocked | [references/recipes/1password.md](references/recipes/1password.md) |