oh-my-opencode 5.0.0-beta.9 → 5.0.0-beta.90

package/packages/omo-codex/plugin/shared/test/config-loader.test.ts

@@ -78,9 +78,9 @@ describe("getCodexOmoConfig", () => {
 		writeOmoConfig(
 			homeDir,
 			JSON.stringify({
-				codegraph: { enabled: true, install_dir: "/base" },
-				"[codex]": { codegraph: { enabled: false } },
-				"[opencode]": { codegraph: { install_dir: "/opencode-only" } },
+				telemetry: { enabled: true },
+				"[codex]": { telemetry: { enabled: false } },
+				"[opencode]": { telemetry: { enabled: true } },
 			}),
 		)
 
@@ -88,120 +88,36 @@ describe("getCodexOmoConfig", () => {
 		const result = getCodexOmoConfig({ cwd, homeDir, env: {} })
 
 		// then
-		expect(result.codegraph).toEqual({
-			auto_provision: true,
-			daemon: true,
-			enabled: false,
-			install_dir: "/base",
-			telemetry: false,
-		})
-		expect(result.trustedCodegraphInstallDir).toBe("/base")
-	})
-
-	it("#given project SOT sets install_dir #when loading config #then only the effective value changes while trusted install root stays global", () => {
-		// given
-		const homeDir = createTemporaryDirectory("omo-codex-shared-trusted-home-")
-		const cwd = createTemporaryDirectory("omo-codex-shared-trusted-project-")
-		writeOmoConfig(homeDir, JSON.stringify({ codegraph: { enabled: true, install_dir: "/global-codegraph" } }))
-		writeOmoConfig(cwd, JSON.stringify({ codegraph: { install_dir: "/project-codegraph" } }))
-
-		// when
-		const result = getCodexOmoConfig({ cwd, homeDir, env: {} })
-
-		// then
-		expect(result.codegraph?.install_dir).toBe("/project-codegraph")
-		expect(result.trustedCodegraphInstallDir).toBe("/global-codegraph")
-	})
-
-	it("#given codex SOT sets CodeGraph excluded roots #when loading config #then roots are returned to hooks", () => {
-		// given
-		const homeDir = createTemporaryDirectory("omo-codex-shared-excluded-home-")
-		const cwd = createTemporaryDirectory("omo-codex-shared-excluded-project-")
-		writeOmoConfig(
-			homeDir,
-			JSON.stringify({
-				"[codex]": { codegraph: { excluded_roots: ["/tmp/omo-research", "/private/tmp/omo-research"] } },
-			}),
-		)
-
-		// when
-		const result = getCodexOmoConfig({ cwd, homeDir, env: {} })
-
-		// then
-		expect(result.codegraph?.excluded_roots).toEqual(["/tmp/omo-research", "/private/tmp/omo-research"])
-	})
-
-	it("#given codex SOT sets the SessionStart cooldown #when loading config #then the configured base interval is returned", () => {
-		// given
-		const homeDir = createTemporaryDirectory("omo-codex-shared-cooldown-home-")
-		const cwd = createTemporaryDirectory("omo-codex-shared-cooldown-project-")
-		writeOmoConfig(homeDir, JSON.stringify({ "[codex]": { codegraph: { session_start_cooldown_ms: 900_000 } } }))
-
-		// when
-		const result = getCodexOmoConfig({ cwd, homeDir, env: {} })
-
-		// then
-		expect(result.codegraph?.session_start_cooldown_ms).toBe(900_000)
+		expect(result.telemetry?.enabled).toBe(false)
 		expect(result.warnings).toEqual([])
 	})
 
-	it("#given no codegraph.daemon key #when loading config #then daemon defaults to on", () => {
+	it("#given a project SOT layer #when loading config #then the project value overrides the user layer", () => {
 		// given
-		const homeDir = createTemporaryDirectory("omo-codex-shared-daemon-default-home-")
-		const cwd = createTemporaryDirectory("omo-codex-shared-daemon-default-project-")
-		writeOmoConfig(homeDir, JSON.stringify({ codegraph: { enabled: true } }))
+		const homeDir = createTemporaryDirectory("omo-codex-shared-project-home-")
+		const cwd = createTemporaryDirectory("omo-codex-shared-project-project-")
+		writeOmoConfig(homeDir, JSON.stringify({ task: { default_concurrency: 3 } }))
+		writeOmoConfig(cwd, JSON.stringify({ task: { default_concurrency: 7 } }))
 
 		// when
 		const result = getCodexOmoConfig({ cwd, homeDir, env: {} })
 
 		// then
-		expect(result.codegraph?.daemon).toBe(true)
-		expect(result.warnings).toEqual([])
+		expect(result.task?.default_concurrency).toBe(7)
 	})
 
-	it("#given codex SOT sets codegraph.daemon=false #when loading config #then daemon opt-out is returned", () => {
+	it("#given a codex SOT setting with the wrong type #when loading config #then the value is rejected with a warning", () => {
 		// given
-		const homeDir = createTemporaryDirectory("omo-codex-shared-daemon-off-home-")
-		const cwd = createTemporaryDirectory("omo-codex-shared-daemon-off-project-")
-		writeOmoConfig(homeDir, JSON.stringify({ "[codex]": { codegraph: { daemon: false } } }))
+		const homeDir = createTemporaryDirectory("omo-codex-shared-invalid-home-")
+		const cwd = createTemporaryDirectory("omo-codex-shared-invalid-project-")
+		writeOmoConfig(homeDir, JSON.stringify({ telemetry: { enabled: true }, "[codex]": { telemetry: { enabled: "yes" } } }))
 
 		// when
 		const result = getCodexOmoConfig({ cwd, homeDir, env: {} })
 
 		// then
-		expect(result.codegraph?.daemon).toBe(false)
-		expect(result.warnings).toEqual([])
-	})
-
-	it("#given codex SOT sets codegraph.daemon to a non-boolean #when loading config #then the value is rejected with a warning", () => {
-		// given
-		const homeDir = createTemporaryDirectory("omo-codex-shared-daemon-invalid-home-")
-		const cwd = createTemporaryDirectory("omo-codex-shared-daemon-invalid-project-")
-		writeOmoConfig(homeDir, JSON.stringify({ "[codex]": { codegraph: { daemon: "yes" } } }))
-
-		// when
-		const result = getCodexOmoConfig({ cwd, homeDir, env: {} })
-
-		// then
-		expect(result.codegraph?.daemon).toBe(true)
-		expect(result.warnings).toContain(`Invalid omo config at ${join(homeDir, ".omo", "omo.jsonc")}: [codex].codegraph.daemon`)
-	})
-
-	it("#given legacy env override and SOT value #when loading config #then env wins over the SOT", () => {
-		// given
-		const homeDir = createTemporaryDirectory("omo-codex-shared-env-")
-		const cwd = createTemporaryDirectory("omo-codex-project-env-")
-		writeOmoConfig(homeDir, JSON.stringify({ codegraph: { enabled: false } }))
-
-		// when
-		const result = getCodexOmoConfig({
-			cwd,
-			homeDir,
-			env: { CODEX_CODEGRAPH_ENABLED: "1" },
-		})
-
-		// then
-		expect(result.codegraph?.enabled).toBe(true)
+		expect(result.telemetry).toBeUndefined()
+		expect(result.warnings).toContain(`Invalid omo config at ${join(homeDir, ".omo", "omo.jsonc")}: [codex].telemetry.enabled`)
 	})
 
 	it("#given no SOT files #when loading config #then returns built-in defaults and missing global source", () => {
@@ -213,12 +129,8 @@ describe("getCodexOmoConfig", () => {
 		const result = getCodexOmoConfig({ cwd, homeDir, env: {} })
 
 		// then
-		expect(result.codegraph).toEqual({
-			auto_provision: true,
-			daemon: true,
-			enabled: true,
-			telemetry: false,
-		})
+		expect(result.telemetry).toBeUndefined()
+		expect(result.warnings).toEqual([])
 		expect(result.sources).toContainEqual({
 			exists: false,
 			loaded: false,
@@ -227,23 +139,10 @@ describe("getCodexOmoConfig", () => {
 		})
 	})
 
-	it("#given codex-unsupported codegraph setting #when loading config #then returns loader warnings", () => {
-		// given
-		const homeDir = createTemporaryDirectory("omo-codex-shared-warnings-")
-		const cwd = createTemporaryDirectory("omo-codex-project-warnings-")
-		writeOmoConfig(homeDir, JSON.stringify({ "[codex]": { codegraph: { watch_debounce_ms: 42 } } }))
-
-		// when
-		const result = getCodexOmoConfig({ cwd, homeDir, env: {} })
-
-		// then
-		expect(result.warnings).toContain("codegraph.watch_debounce_ms is not supported for harness codex")
-	})
-
 	it("#given only legacy config.jsonc #when codex starts #then migrates once with a backup before loading the unified codex view", () => {
 		// given
 		const homeDir = createTemporaryDirectory("omo-codex-legacy-upgrade-")
-		writeLegacyOmoConfig(homeDir, JSON.stringify({ "[codex]": { codegraph: { daemon: false } } }))
+		writeLegacyOmoConfig(homeDir, JSON.stringify({ "[codex]": { telemetry: { enabled: false } } }))
 		const legacyPath = join(homeDir, ".omo", "config.jsonc")
 
 		// when
@@ -252,7 +151,7 @@ describe("getCodexOmoConfig", () => {
 		const second = getCodexOmoConfig({ cwd: homeDir, homeDir, env: {} })
 
 		// then
-		expect(first.codegraph?.daemon).toBe(false)
+		expect(first.telemetry?.enabled).toBe(false)
 		expect(first.warnings.some((warning) => warning.startsWith("omo-codex: migrated legacy configuration from ")
 			&& warning.endsWith("/.omo/config.jsonc"))).toBe(true)
 		expect(readOmoJson(homeDir)["_migrations"]).toEqual(["2026-07-codex-config-jsonc"])
@@ -266,8 +165,8 @@ describe("getCodexOmoConfig", () => {
 	it("#given a legacy migration conflict #when codex starts #then exposes the migration summary and conflict through loader warnings", () => {
 		// given
 		const homeDir = createTemporaryDirectory("omo-codex-legacy-conflict-")
-		writeOmoConfig(homeDir, JSON.stringify({ codegraph: { enabled: true } }))
-		writeLegacyOmoConfig(homeDir, JSON.stringify({ codegraph: { enabled: false } }))
+		writeOmoConfig(homeDir, JSON.stringify({ "[codex]": { telemetry: { enabled: true } } }))
+		writeLegacyOmoConfig(homeDir, JSON.stringify({ "[codex]": { telemetry: { enabled: false } } }))
 
 		// when
 		const result = getCodexOmoConfig({ cwd: homeDir, homeDir, env: {} })
@@ -275,7 +174,7 @@ describe("getCodexOmoConfig", () => {
 		// then
 		expect(result.warnings.some((warning) => warning.startsWith("omo-codex: migrated legacy configuration from ")
 			&& warning.endsWith("/.omo/config.jsonc"))).toBe(true)
-		expect(result.warnings).toContain("omo-codex: configuration migration: skipped: codegraph.enabled legacy=false kept=true")
+		expect(result.warnings).toContain("omo-codex: configuration migration: skipped: [codex].telemetry.enabled legacy=false kept=true")
 	})
 
 	it("#given overlapping [omo] and [senpi] blocks in legacy config #when Codex migrates #then the transform conflict is reported", () => {
@@ -310,7 +209,7 @@ describe("getCodexOmoConfig", () => {
 	it("#given codex starts before opencode #when both legacy source groups exist #then each distinct migration id is applied once", () => {
 		// given
 		const homeDir = createTemporaryDirectory("omo-codex-order-codex-first-")
-		writeLegacyOmoConfig(homeDir, JSON.stringify({ "[codex]": { codegraph: { daemon: false } } }))
+		writeLegacyOmoConfig(homeDir, JSON.stringify({ "[codex]": { telemetry: { enabled: false } } }))
 		writeOpenCodeConfig(homeDir)
 		const openCodeSource = join(homeDir, ".config", "opencode", "oh-my-openagent.jsonc")
 
@@ -322,13 +221,17 @@ describe("getCodexOmoConfig", () => {
 		// then
 		expect(remainsAfterCodexStartup).toBe(true)
 		expect(existsSync(openCodeSource)).toBe(false)
-		expect(migrationIds(homeDir)).toEqual(["2026-07-codex-config-jsonc", "2026-07-opencode-config-unification"])
+		expect(migrationIds(homeDir)).toEqual([
+			"2026-07-codex-config-jsonc",
+			"2026-07-opencode-config-unification",
+			"2026-08-reasoning-unification",
+		])
 	})
 
 	it("#given opencode starts before codex #when both legacy source groups exist #then each distinct migration id is applied once", () => {
 		// given
 		const homeDir = createTemporaryDirectory("omo-codex-order-opencode-first-")
-		writeLegacyOmoConfig(homeDir, JSON.stringify({ "[codex]": { codegraph: { daemon: false } } }))
+		writeLegacyOmoConfig(homeDir, JSON.stringify({ "[codex]": { telemetry: { enabled: false } } }))
 		writeOpenCodeConfig(homeDir)
 
 		// when
@@ -336,13 +239,17 @@ describe("getCodexOmoConfig", () => {
 		getCodexOmoConfig({ cwd: homeDir, homeDir, env: {} })
 
 		// then
-		expect(migrationIds(homeDir)).toEqual(["2026-07-opencode-config-unification", "2026-07-codex-config-jsonc"])
+		expect(migrationIds(homeDir)).toEqual([
+			"2026-07-opencode-config-unification",
+			"2026-07-codex-config-jsonc",
+			"2026-08-reasoning-unification",
+		])
 	})
 
 	it("#given concurrent codex and opencode starts #when opencode owns the shared lock #then both migration ids are applied exactly once", () => {
 		// given
 		const homeDir = createTemporaryDirectory("omo-codex-order-concurrent-")
-		writeLegacyOmoConfig(homeDir, JSON.stringify({ "[codex]": { codegraph: { daemon: false } } }))
+		writeLegacyOmoConfig(homeDir, JSON.stringify({ "[codex]": { telemetry: { enabled: false } } }))
 		writeOpenCodeConfig(homeDir)
 		let codexResult: ReturnType<typeof runCodexStartupMigration> | undefined
 
@@ -355,6 +262,10 @@ describe("getCodexOmoConfig", () => {
 		// then
 		if (codexResult === undefined) throw new Error("Expected concurrent Codex migration attempt")
 		expect(codexResult.error).toBe("Configuration migration is already running")
-		expect(migrationIds(homeDir)).toEqual(["2026-07-opencode-config-unification", "2026-07-codex-config-jsonc"])
+		expect(migrationIds(homeDir)).toEqual([
+			"2026-07-opencode-config-unification",
+			"2026-07-codex-config-jsonc",
+			"2026-08-reasoning-unification",
+		])
 	})
 })

package/packages/omo-codex/plugin/skills/ast-grep/AGENTS.md

@@ -0,0 +1,51 @@
+# ast-grep — Vendored Structural-Search Skill
+
+**Generated:** 2026-08-24 (f3642fcda)
+
+## OVERVIEW
+
+Vendored skill teaching agents ast-grep (`sg`) structural search/rewrite, plus a stdlib-Python helper CLI that wraps the `sg` binary. Vendoring pin in `SOURCE`: upstream `code-yeongyu/ast-grep-skill @ 3148c69` (ast-grep 0.45.0), "vendored as a sync; do not fork-drift". Earned this file: own executable surface (749-LOC helper + installers + smoke tests) and a no-fork-drift upstream contract that has no analogue elsewhere in `shared-skills`.
+
+## STRUCTURE
+
+```
+ast-grep/
+├── SKILL.md / README.md          # agent workflow / user overview
+├── SOURCE                        # upstream pin — the no-fork-drift contract
+├── scripts/ast_grep_helper.py    # 749-LOC stdlib CLI (argparse; no deps)
+├── install.sh / install.ps1      # macOS/Linux + Windows installers
+├── references/                   # cli, install, patterns, pitfalls, recipes, yaml-rules (510 LOC), sgconfig
+└── tests/smoke.{sh,ps1}          # POSIX + PowerShell smoke (also shell syntax + content checks)
+```
+
+## HELPER CLI (`scripts/ast_grep_helper.py`)
+
+Subcommands: `search`, `replace` (dry-run; `--apply` to write), `scan`, `test`, `new`, `langs`, `doctor`, `install`, `validate`. Resolves the `sg`/`ast-grep` binary across PATH, Homebrew, npm, and OMO caches, validates patterns before executing, and shells out — it never links ast-grep as a library. Internal handlers `cmd_*`; utilities `validate_pattern`, `normalize_lang`, `resolve_binary`, `run_sg`. Nothing in-repo imports it; docs and skills invoke it by path. `omo-opencode/src/cli/install-ast-grep-sg.ts` locates this skill dir to install the binary.
+
+## CONVENTIONS
+
+- AST patterns, never regex, for syntax-shaped queries; `$VAR` singles, `$$$` multis; patterns must parse as complete code in the target language.
+- Two-pass rewrites: preview with `--json=compact`, apply separately with `--update-all` — the flags are mutually exclusive in `sg`.
+- `sgconfig.yml` discovered upward; `ruleDirs`, optional `testConfigs`/`utilDirs`, language globs, custom languages, injections.
+- Upstream syncs land as whole vendored refreshes matching `SOURCE`; local edits ride along until the next sync absorbs or reverts them.
+
+## ANTI-PATTERNS
+
+- NO regex constructs (`.*`, `.+`, `\w`, `\d`, literal `|`) inside AST patterns — that is the skill's #1 pitfall.
+- No incomplete patterns (e.g. Python `def $F($$$):` without a body).
+- NEVER `--apply` a rewrite without the dry-run preview first.
+- Text/comment/byte queries go to `rg`, not structural matching.
+- Do not fork-drift from the `SOURCE` pin; a sync is a vendored refresh, not a merge.
+
+## COMMANDS
+
+```bash
+# from packages/shared-skills/skills/ast-grep/
+python3 scripts/ast_grep_helper.py search '<PATTERN>' --lang ts [path]
+python3 scripts/ast_grep_helper.py replace '<PATTERN>' '<REWRITE>' --lang ts   # dry-run; add --apply
+python3 scripts/ast_grep_helper.py doctor
+bash tests/smoke.sh          # or: pwsh tests/smoke.ps1
+# direct:  sg run -p '<PATTERN>' --lang ts path
+```
+
+- Parent: [`packages/shared-skills/AGENTS.md`](../../AGENTS.md).

package/packages/omo-codex/plugin/skills/ast-grep/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ast-grep
-description: "Use ast-grep (sg) for AST-aware code search and rewrite across 25 languages. Trigger for structural code matching or deterministic codemods: find every function/call/class/import shaped like X, rewrite console.log to logger.info, strip `as any`, migrate require() to import, find empty catch blocks or missing await, and scan/apply YAML rules. Prefer this over rg/grep when the target is syntax shape rather than text; use rg for string contents, comments, filenames, or regex-style byte searches."
+description: "Searches and rewrites code by AST shape across 25 languages. Use when the target is a syntax pattern (every call/class/import shaped like X, a codemod, a YAML rule) rather than literal text; for plain strings, comments, or filenames, use rg."
 ---
 
 # ast-grep
@@ -11,6 +11,18 @@ This skill ships a Python wrapper at `scripts/ast_grep_helper.py` and platform i
 
 ---
 
+## OmO native: the ast-grep MCP tools (fastest path, no CLI needed)
+
+OmO native also registers a bundled ast-grep MCP server. Its three tools are **deferred**: they are absent from the resident tool list and activate automatically the first time you call them by name — no `tool_search` round trip needed.
+
+- `mcp__ast_grep_search({ pattern, language, paths })` — AST-shape search, the MCP equivalent of `sg run -p`. Prefer this over shelling out to `sg` for one-off lookups: no install, no PATH issues.
+- `mcp__ast_grep_rewrite({ pattern, rewrite, language, paths, apply })` — preview matches (`apply: false`, the default) or apply the rewrite (`apply: true`). Same two-pass discipline as `sg run -r`: preview first, then apply.
+- `mcp__ast_grep_scan({ paths })` — run project YAML rules (`sgconfig.yml`, `rules/`), the MCP equivalent of `sg scan`.
+
+Same pattern language as the CLI: `$VAR` matches one AST node, `$$$VAR` matches zero or more, and the pattern is code, not regex. `paths` accepts a file or directory list; `language` is required for patterns that are ambiguous across languages.
+
+---
+
 ## When to use this skill
 
 Use it whenever the user's question is about **code structure**, not bytes:

package/packages/omo-codex/plugin/skills/browser/ATTRIBUTION.md

@@ -0,0 +1,37 @@
+# ATTRIBUTION / NOTICE
+
+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 reaches the user's browser through **BrowserSkill** by Tencent.
+
+- Upstream: https://github.com/Tencent/BrowserSkill
+- License: MIT
+- 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/` 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/omo-codex/plugin/skills/browser/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: browser
+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
+
+One library, two engines. omowright ships inside this skill; choose the engine before you act:
+
+| You need | Engine | Entry point |
+|---|---|---|
+| 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 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 — load omowright and prove the stack
+
+```js
+const { loadOmowright } = await import("<skill-root>/scripts/omowright.mjs")
+const { omowright } = await loadOmowright()          // { connectBrowserSkill, bskSnapshot, connectPipe, ... }
+```
+
+```bash
+node "<skill-root>/scripts/browser-doctor.mjs" --json
+```
+
+| State | Meaning | Next |
+|---|---|---|
+| `ready` | CLI, daemon and a connected browser | start a session |
+| `no-cli` / `no-daemon` / `no-extension` | something is missing | `node "<skill-root>/scripts/browser-install.mjs" [--browser=<id>]` prepares everything it can for **the browser the user uses**, then prints the **single** step only the user can do (relaunch that browser and click **Enable**); relay it verbatim, wait, re-run the doctor |
+| `choose-browser` | the signals do not single out one browser (Safari/Firefox default, an idle default while another browser runs, several in use) | nothing was installed; take the browser from memory or ask the user, then `browser-install.mjs --browser=<id>` |
+| `no-browser-support` | no Chromium-family profile on this machine | say so and stop |
+
+**Install into the browser the user actually uses, never into whatever happens to be on disk.** Before
+installing, check your memory for the user's browser; otherwise read the doctor's `browser` (picked
+from the OS default browser, running apps and recent use — `candidates` shows the evidence). If memory
+and the doctor disagree, or the doctor says `choose-browser`, ask the user. Pass the answer as
+`--browser=<id>` and record it in memory. A Chrome that is merely installed is not their browser.
+
+**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. **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** (`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.
+
+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:
+
+```js
+const outcome = await session.requestHelp({ prompt: "<what you need done>", targets: ["@e4"], timeoutMs: 300_000 })
+```
+
+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 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.
+- **`focused: false` by default.** The browser belongs to someone who is probably using it.
+- **One short, named session per task,** always stopped.
+- **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) |

package/packages/omo-codex/plugin/skills/browser/agents/openai.yaml

@@ -0,0 +1,2 @@
+interface:
+  display_name: "(OmO) browser"

package/packages/omo-codex/plugin/skills/browser/references/commands.md

@@ -0,0 +1,105 @@
+# Session methods
+
+`connectBrowserSkill()` returns a `BskSession`. Every method is one call on the BrowserSkill
+daemon's tool surface; options are the daemon's parameter names in camelCase.
+
+## Sessions
+
+```js
+const session = await omowright.connectBrowserSkill({ name: "<task>", focused: false, browser: "<instance id>", width: 1200, height: 800 })
+session.sessionId            // four letters, e.g. "ckhg"
+session.browserInstanceId    // which connected browser owns the Agent Window
+await session.stop()         // ALWAYS, on success and failure
+```
+
+`browser` is needed only when more than one browser is connected (`bskDoctor()` lists them).
+`focused: false` keeps the Agent Window from stealing focus; drop it only when the user is watching
+on purpose. Throws `BskRpcError` `no_browser_connected` when no extension is attached — that is a
+stop, not a cue to launch something else.
+
+## Targets
+
+| Form | Meaning |
+|---|---|
+| `"@e3"` / `"e3"` | a ref from the last `observe()` / `snapshot()` |
+| `"#login > button"` | a CSS selector, resolved live |
+| `{ captureId, x, y }` | a point in a screenshot, from `screenshot()` |
+| `css.e3` from `bskSnapshot` | the light-DOM CSS path of an OmOWright ref (`null` inside shadow roots — use the daemon ref instead) |
+
+## Reading
+
+| Call | Returns |
+|---|---|
+| `bskSnapshot(session, { interactive, maxDepth })` | `{ tree, refs, css }` — the OmOWright accessibility tree with refs, computed in the page **without** leaving a global or touching the DOM |
+| `session.observe({ maxTokens, cursor, probeHover })` | the daemon's semantic tree (`@vom`) with `@eN` refs, layers and hover probes — **the default read for shadow DOM and iframes** |
+| `session.snapshot({ maxDepth, maxTokens })` | the daemon's plain accessibility tree |
+| `session.getHtml({ ref, maxBytes })` | exact markup |
+| `session.screenshot({ ref })` / `screenshot({ fullPage: true })` | `{ buffer, width, height, captureId }`; full-page captures stream back in chunks |
+| `session.evaluate(expression, { awaitPromise, timeoutMs })` | `{ ok, value, error }` — **check `.ok`**; a resolved promise does not mean the script succeeded |
+| `session.console({ since })` / `session.network({ since })` | buffered console entries / request metadata (no bodies) |
+
+**Refs are reissued by every read.** Read a ref and act on it in the same cycle. A ref captured
+two calls ago silently addresses a different element — this is how a click lands on the
+neighbouring row.
+
+## Acting
+
+| Need | Call |
+|---|---|
+| Click | `session.click(target, { button, clickCount, modifiers })` |
+| Fill | `session.fill(target, value, { clearBefore })` |
+| Select | `session.select(target, ["<option value>"])` |
+| Key | `session.press("Enter", { target, modifiers, holdMs })` |
+| Hover | `session.hover(target, { settleMs })` |
+| Scroll into view | `session.scrollTo(target)` |
+| Wheel | `session.wheel({ deltaY: 600, target })` |
+| Focus / blur | `session.focus(target)` / `session.blur(target)` |
+| Navigate | `session.navigate(url, { waitUntil: "load" \| "domcontentloaded" \| "networkidle" \| "commit", timeoutMs })`, `back()`, `forward()`, `reload({ hard })`, `waitForNavigation()` |
+| Window | `session.resize(width, height)`, `session.emulate({ overrides: { width, mobile } })` |
+
+Traps:
+
+- `select` takes the option's **value attribute**, not its visible label.
+- `press` without `target` goes to the focused node; `press` with a CSS selector is fine, but a
+  daemon ref must come from the current read.
+- A menu that a `click` opens can be toggled shut by that same click. `focus` then `press("Enter")`
+  opens it reliably.
+- Hover-only controls report `element not visible`: hover the trigger, read again, then act on the
+  revealed item's fresh ref. `observe({ probeHover: true })` finds one when no marker does, at the
+  cost of touching the live page.
+- The clipboard is unavailable in a window started `focused: false`, so read values out of the DOM.
+
+## Tabs
+
+```js
+const { tabs } = await session.tabList({ scope: "user" })   // "user" | "agent" | "all"
+await session.tabBorrow(tabId)                                // the user confirms in the browser (60 s)
+await session.tabReturn(tabId)                                // stop() returns anything still borrowed
+await session.tabCreate({ url }); await session.tabSelect(id); await session.tabClose(id)
+```
+
+Never invent tab ids and never repeat a denied borrow.
+
+## Humans
+
+```js
+const { outcome } = await session.requestHelp({ prompt, title, targets: ["@e4"], completionCriteria, timeoutMs })
+// outcome: "completed" | "continued" | "cancelled" | "timed_out" | "navigated" | "disabled"
+```
+
+## Errors
+
+Every refusal is a `BskRpcError` with the daemon's own `code`:
+
+| `code` | Meaning | Do |
+|---|---|---|
+| `no_browser_connected` | no extension attached | run the onboarding script, relay the human step, wait |
+| `not_found` | stale ref or unknown session | read again; if the session is gone, start a new one |
+| `invalid_params` | wrong option shape | fix the call, do not retry as-is |
+| `permission_denied` | `evaluate` on a tab outside the Agent Window, or a denied borrow | stop; the user said no |
+| `timeout` | the tool did not finish in its budget | read the page state before retrying once |
+| `user_aborted` | the user pressed Stop in the browser | stop the task and report |
+| `cdp_failed` | the page cannot be attached (restricted URL, DevTools open) | say which page and why |
+
+Long calls can be cancelled: `const h = session.client.callWithHandle("tool.navigate", {...})`
+then `await session.client.cancel(h.rpcId)`.