lazycodex-ai 5.0.0-beta.82 → 5.0.0-beta.83

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

@@ -0,0 +1,24 @@
+# Agent here, browser there
+
+The agent and the browser do not have to be the same machine. Upstream supports this directly;
+nothing in this package needs to bridge it.
+
+Shape:
+
+- The **browser machine** needs only the extension.
+- The **agent machine** runs the `bsk` CLI and this skill.
+- They are joined by a daemon in server mode plus a pairing link.
+
+```bash
+bsk daemon start --mode server      # on the machine the agent runs on
+```
+
+Then follow upstream's pairing guide, which owns the current flag surface and the TLS
+prerequisites: https://github.com/Tencent/BrowserSkill/blob/main/docs/remote-extension-connection.md
+
+Once paired, every command in `commands.md` behaves identically; `--out` paths still resolve on
+the machine that ran the command.
+
+If pairing is not configured, say so and ask. Do not substitute a browser on the agent machine:
+the point of the attached engine is the sessions that live in the user's browser, and a local
+browser has none of them.

package/packages/omo-codex/plugin/skills/browser/scripts/browser-doctor.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import { platform } from "node:os"
+import { connectedBrowsers, readStatus, resolveCli, STORE_LISTINGS, SUPPORTED_PLATFORMS } from "./browser-env.mjs"
+
+const REMEDIES = {
+  ready: "Start a session: bsk session start --json --no-focus --name \"<task>\"",
+  "no-extension": `Ask the user to install and enable the extension, then re-run this doctor.\n  Chrome: ${STORE_LISTINGS.chrome}\n  Edge:   ${STORE_LISTINGS.edge}`,
+  "no-cli": "Install the CLI: node \"<skill-root>/scripts/browser-install.mjs\", then re-run this doctor.",
+  "no-browser-support": "This platform has no supported browser. Say so and stop; do not substitute another engine.",
+}
+
+async function diagnose() {
+  if (!SUPPORTED_PLATFORMS.has(platform())) {
+    return { state: "no-browser-support", platform: platform() }
+  }
+  const cli = await resolveCli()
+  if (cli === undefined) return { state: "no-cli", platform: platform() }
+
+  let status
+  try {
+    status = await readStatus(cli)
+  } catch (error) {
+    return { state: "no-extension", platform: platform(), cli, detail: `status failed: ${error.message}` }
+  }
+  const browsers = connectedBrowsers(status)
+  if (browsers.length === 0) return { state: "no-extension", platform: platform(), cli }
+  return { state: "ready", platform: platform(), cli, browsers: browsers.length }
+}
+
+const report = await diagnose()
+const json = process.argv.includes("--json")
+if (json) {
+  console.log(JSON.stringify({ ...report, remedy: REMEDIES[report.state] }, null, 2))
+} else {
+  console.log(`state: ${report.state}`)
+  if (report.cli) console.log(`cli:   ${report.cli}`)
+  if (report.browsers) console.log(`browsers connected: ${report.browsers}`)
+  if (report.detail) console.log(`detail: ${report.detail}`)
+  console.log(`\n${REMEDIES[report.state]}`)
+}
+process.exit(report.state === "ready" ? 0 : 1)

package/packages/omo-codex/plugin/skills/browser/scripts/browser-env.mjs

@@ -0,0 +1,41 @@
+import { execFile } from "node:child_process"
+import { existsSync } from "node:fs"
+import { homedir, platform } from "node:os"
+import { join } from "node:path"
+import { promisify } from "node:util"
+
+const run = promisify(execFile)
+
+export const STORE_LISTINGS = {
+  chrome: "https://chromewebstore.google.com/detail/hhcmgoofomhgciiibhipgmgkgnoenaoi",
+  edge: "https://microsoftedge.microsoft.com/addons/detail/browserskill/emacgiaaaiojkkpkddmmdfhmokgmnikg",
+}
+
+export const SUPPORTED_PLATFORMS = new Set(["darwin", "linux", "win32"])
+
+export function localBinCandidates() {
+  const bin = join(homedir(), ".local", "bin")
+  return platform() === "win32" ? [join(bin, "bsk.exe"), join(bin, "bsk")] : [join(bin, "bsk")]
+}
+
+export async function resolveCli() {
+  for (const candidate of localBinCandidates()) {
+    if (existsSync(candidate)) return candidate
+  }
+  try {
+    await run("bsk", ["--version"], { timeout: 15000, windowsHide: true })
+    return "bsk"
+  } catch {
+    return undefined
+  }
+}
+
+export async function readStatus(cli) {
+  const { stdout } = await run(cli, ["status", "--json"], { timeout: 30000, windowsHide: true })
+  return JSON.parse(stdout)
+}
+
+export function connectedBrowsers(status) {
+  const browsers = status?.browsers
+  return Array.isArray(browsers) ? browsers : []
+}

package/packages/omo-codex/plugin/skills/browser/scripts/browser-install.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process"
+import { platform } from "node:os"
+import { resolveCli, STORE_LISTINGS, SUPPORTED_PLATFORMS } from "./browser-env.mjs"
+
+const UNIX_INSTALL = "curl -fsSL https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.sh | sh"
+const WINDOWS_INSTALL = "irm https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.ps1 | iex"
+
+function installCommand() {
+  return platform() === "win32"
+    ? { file: "powershell", args: ["-NoProfile", "-Command", WINDOWS_INSTALL], display: WINDOWS_INSTALL }
+    : { file: "sh", args: ["-c", UNIX_INSTALL], display: UNIX_INSTALL }
+}
+
+function spawnInstaller({ file, args }) {
+  return new Promise((resolve) => {
+    const child = spawn(file, args, { stdio: "inherit", windowsHide: true })
+    child.on("error", () => resolve(1))
+    child.on("close", (code) => resolve(code ?? 1))
+  })
+}
+
+if (!SUPPORTED_PLATFORMS.has(platform())) {
+  console.error(`unsupported platform: ${platform()}. macOS, Linux and Windows x64 only.`)
+  process.exit(1)
+}
+
+if (await resolveCli()) {
+  console.log("bsk is already installed; run browser-doctor.mjs to check the extension.")
+  process.exit(0)
+}
+
+const command = installCommand()
+console.log(`installing the bsk CLI with the upstream installer:\n  ${command.display}\n`)
+const code = await spawnInstaller(command)
+if (code !== 0) {
+  console.error(`\ninstaller exited ${code}. Report this instead of retrying blindly.`)
+  process.exit(code)
+}
+
+console.log([
+  "",
+  "CLI installed. Two things remain, and only the user can do the first:",
+  "",
+  "1. Install the browser extension from the store, then enable it:",
+  `     Chrome: ${STORE_LISTINGS.chrome}`,
+  `     Edge:   ${STORE_LISTINGS.edge}`,
+  "2. Re-run: node \"<skill-root>/scripts/browser-doctor.mjs\"",
+  "",
+  "If PATH does not pick up the CLI in this shell, use its absolute path under ~/.local/bin.",
+].join("\n"))

package/packages/omo-codex/plugin/test/sync-skills-test-support.mjs

@@ -6,6 +6,7 @@ export const CONTEXT_PRESSURE_SKILL_BUDGET_BYTES = 25_000;
 
 export const expectedSkills = [
 	"ast-grep",
+	"browser",
 	"coding-agent-sessions",
 	"comment-checker",
 	"data-scientist",

package/packages/omo-codex/scripts/install-dist/install-local.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// omo-codex-install:6df5dbbbb7ca9b9dce86fae98a525a9caa7de96caed85a4b77d4e8b4ab4d1501:4c50a551b52c74c82521d2fcbd9c9a1db21370470eb76a3195db19bdfcbad5b1
+// omo-codex-install:88ab1eaf77d9f58468ed3f04e9c7d6c7dbb32d7c87feee69f45401431352184f:6f7e0588dc9a653cf42c9b4466272eea05e8c081bc8dc62082c03c1e5562cc31
 var __esm = (fn, res, err) => () => {
   if (fn)
     try {
@@ -316,7 +316,7 @@ function shouldRetainLine(line, cutoffMs) {
 function parseDiagnosticLine(line) {
   try {
     const parsed = JSON.parse(line);
-    if (!isRecord9(parsed)) {
+    if (!isRecord10(parsed)) {
       return null;
     }
     return parsed;
@@ -327,7 +327,7 @@ function parseDiagnosticLine(line) {
     throw error;
   }
 }
-function isRecord9(value) {
+function isRecord10(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function trimToMaxBytes(lines) {
@@ -7817,7 +7817,7 @@ function coerceBool(value) {
 function coerceString(value) {
   return typeof value == "string" ? value : undefined;
 }
-function isRecord10(value) {
+function isRecord11(value) {
   return typeof value == "object" && value !== null && !Array.isArray(value);
 }
 function toRfc3339(timestamp) {
@@ -7839,7 +7839,7 @@ function relocateInto(properties, key, value) {
     properties[key] = value;
 }
 function buildV1Event(message) {
-  const sourceProperties = isRecord10(message.properties) ? message.properties : {};
+  const sourceProperties = isRecord11(message.properties) ? message.properties : {};
   const properties = {
     ...sourceProperties
   };
@@ -9984,7 +9984,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@oh-my-opencode/omo-codex",
-    version: "5.0.0-beta.82",
+    version: "5.0.0-beta.83",
     type: "module",
     private: true,
     description: "Codex harness adapter for oh-my-openagent. Vendored Codex plugin namespace (omo) + TypeScript installer + telemetry.",
@@ -16515,8 +16515,10 @@ var OmoGitMasterSettingsSchema = OmoGitMasterSettingsLayerSchema.extend({
 
 // packages/omo-config-core/src/schema/harness.ts
 var HARNESS_IDS = ["codex", "opencode", "omo"];
-var OMO_CONFIG_HARNESS_IDS = ["opencode", "senpi", "codex"];
+var OMO_CONFIG_HARNESS_IDS = ["opencode", "native", "codex"];
 var OmoHarnessIdSchema = _enum(OMO_CONFIG_HARNESS_IDS);
+var OMO_CONFIG_LEGACY_HARNESS_ALIASES = { senpi: "native" };
+var OMO_CONFIG_LEGACY_HARNESS_IDS = Object.keys(OMO_CONFIG_LEGACY_HARNESS_ALIASES);
 
 // packages/omo-config-core/src/schema/memory.ts
 var OmoMemoryReflectionTriggerSchema = object({
@@ -16975,6 +16977,7 @@ var OmoConfigProfileSchema = object({
   telemetry: OmoTelemetrySettingsLayerSchema.optional(),
   disabled_skills: OmoDisabledSkillsSchema.optional(),
   "[opencode]": OmoOpenCodeHarnessConfigSchema.optional(),
+  "[native]": OmoTypedHarnessConfigSchema.optional(),
   "[senpi]": OmoTypedHarnessConfigSchema.optional(),
   "[codex]": OmoTypedHarnessConfigSchema.optional()
 }).strict();
@@ -16993,6 +16996,7 @@ var OmoConfigSchema = object({
   telemetry: OmoTelemetrySettingsSchema.optional(),
   disabled_skills: OmoDisabledSkillsSchema.optional(),
   "[opencode]": OmoOpenCodeHarnessConfigSchema.optional(),
+  "[native]": OmoTypedHarnessConfigSchema.optional(),
   "[senpi]": OmoTypedHarnessConfigSchema.optional(),
   "[codex]": OmoTypedHarnessConfigSchema.optional(),
   profiles: record(string2(), OmoConfigProfileSchema).default({}),
@@ -17014,6 +17018,7 @@ var OmoConfigLayerSchema = object({
   telemetry: OmoTelemetrySettingsLayerSchema.optional(),
   disabled_skills: OmoDisabledSkillsSchema.optional(),
   "[opencode]": OmoOpenCodeHarnessConfigSchema.optional(),
+  "[native]": OmoTypedHarnessConfigSchema.optional(),
   "[senpi]": OmoTypedHarnessConfigSchema.optional(),
   "[codex]": OmoTypedHarnessConfigSchema.optional(),
   profiles: record(string2(), OmoConfigProfileSchema).optional(),
@@ -17077,6 +17082,54 @@ function canonicalizeLegacyCategoryNames(document) {
   return { document: canonicalized, renames };
 }
 
+// packages/omo-config-core/src/schema/legacy-harness-names.ts
+function canonicalHarnessName(name) {
+  return Object.hasOwn(OMO_CONFIG_LEGACY_HARNESS_ALIASES, name) ? OMO_CONFIG_LEGACY_HARNESS_ALIASES[name] : name;
+}
+function harnessBlockKey(harness) {
+  return `[${harness}]`;
+}
+function legacyHarnessOfBlockKey(key) {
+  if (!key.startsWith("[") || !key.endsWith("]"))
+    return;
+  const harness = key.slice(1, -1);
+  return Object.hasOwn(OMO_CONFIG_LEGACY_HARNESS_ALIASES, harness) ? harness : undefined;
+}
+function isRecord7(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function canonicalizeBlocksIn(container, path, renames) {
+  const result = {};
+  for (const [key, value] of Object.entries(container)) {
+    const legacyHarness = legacyHarnessOfBlockKey(key);
+    if (legacyHarness === undefined) {
+      result[key] = value;
+      continue;
+    }
+    const canonical = harnessBlockKey(canonicalHarnessName(legacyHarness));
+    const dropped = Object.hasOwn(container, canonical);
+    renames.push({ canonical, dropped, legacy: key, path: [...path, key].join(".") });
+    if (!dropped)
+      result[canonical] = value;
+  }
+  return result;
+}
+function canonicalizeLegacyHarnessBlocks(document) {
+  if (!isRecord7(document))
+    return { document: {}, renames: [] };
+  const renames = [];
+  const canonicalized = canonicalizeBlocksIn(document, [], renames);
+  const profiles = canonicalized["profiles"];
+  if (isRecord7(profiles)) {
+    const canonicalProfiles = {};
+    for (const [name, profile] of Object.entries(profiles)) {
+      canonicalProfiles[name] = isRecord7(profile) ? canonicalizeBlocksIn(profile, ["profiles", name], renames) : profile;
+    }
+    canonicalized["profiles"] = canonicalProfiles;
+  }
+  return { document: canonicalized, renames };
+}
+
 // node_modules/.bun/jsonc-parser@3.3.1/node_modules/jsonc-parser/lib/esm/impl/scanner.js
 function createScanner(text, ignoreTrivia = false) {
   const len = text.length;
@@ -18052,7 +18105,7 @@ function resolveOmoConfigPaths(options) {
 }
 
 // packages/omo-config-core/src/loader/resolution.ts
-var HARNESS_KEYS = [...new Set([...HARNESS_IDS, ...OMO_CONFIG_HARNESS_IDS])].map((harness) => `[${harness}]`);
+var HARNESS_KEYS = [...new Set([...HARNESS_IDS, ...OMO_CONFIG_HARNESS_IDS, ...OMO_CONFIG_LEGACY_HARNESS_IDS])].map((harness) => harnessBlockKey(harness));
 function profileName(value) {
   return value === "" ? undefined : value;
 }
@@ -18081,7 +18134,13 @@ function withoutControlKeys(config) {
 function harnessLayer(config, harness) {
   if (harness === undefined)
     return {};
-  return toRecord(config[`[${harness}]`]) ?? {};
+  const canonical = canonicalHarnessName(harness);
+  const legacyKeys = Object.entries(OMO_CONFIG_LEGACY_HARNESS_ALIASES).filter(([, target]) => target === canonical).map(([legacy]) => harnessBlockKey(legacy));
+  let layer = {};
+  for (const key of [...legacyKeys, harnessBlockKey(canonical)]) {
+    layer = mergeOmoConfigRecords(layer, toRecord(config[key]) ?? {});
+  }
+  return layer;
 }
 function resolveOmoConfigView(options) {
   const profiles = toRecord(options.config["profiles"]);
@@ -18132,6 +18191,7 @@ var DEFAULT_RAW_CONFIG = {
 function stripResolutionControlKeys(config) {
   const {
     "[codex]": _codex,
+    "[native]": _native,
     "[opencode]": _opencode,
     "[senpi]": _senpi,
     profiles: _profiles,
@@ -18157,21 +18217,21 @@ function hasUnsafeUnrecognizedKey(issues) {
 function hasTamperedPrototype(value) {
   if (Array.isArray(value))
     return value.some((entry) => hasTamperedPrototype(entry));
-  if (!isRecord7(value))
+  if (!isRecord8(value))
     return false;
   const prototype = Object.getPrototypeOf(value);
   if (prototype !== Object.prototype && prototype !== null)
     return true;
   return Object.values(value).some((entry) => hasTamperedPrototype(entry));
 }
-function isRecord7(value) {
+function isRecord8(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function containerAt(record, path) {
   let container = record;
   for (const segment of path) {
     const next = container[segment];
-    if (!isRecord7(next))
+    if (!isRecord8(next))
       return null;
     container = next;
   }
@@ -18282,6 +18342,15 @@ function legacyCategoryDiagnostic(path, renames) {
     issuePaths: renames.map((rename) => rename.path)
   };
 }
+function legacyHarnessDiagnostic(path, renames) {
+  const detail = renames.map((rename) => rename.dropped ? `${rename.path} ignored because ${rename.canonical} is also configured` : `${rename.path} renamed to ${rename.canonical}`).join(", ");
+  return {
+    kind: "deprecated-keys",
+    message: `Deprecated harness block in ${path}: ${detail}. Rename it; the alias is removed in a future release.`,
+    path,
+    issuePaths: renames.map((rename) => rename.path)
+  };
+}
 function loadOmoConfig(options = {}) {
   const fileSystem = options.fileSystem ?? DEFAULT_READ_FILE_SYSTEM;
   const cwd = options.cwd ?? process.cwd();
@@ -18304,8 +18373,12 @@ function loadOmoConfig(options = {}) {
       if (canonicalized.renames.length > 0) {
         diagnostics.push(legacyCategoryDiagnostic(candidate.path, canonicalized.renames));
       }
-      layers.push({ config: canonicalized.document, source: loaded.source });
-      merged = mergeOmoConfigRecords(merged, canonicalized.document);
+      const harnessCanonicalized = canonicalizeLegacyHarnessBlocks(canonicalized.document);
+      if (harnessCanonicalized.renames.length > 0) {
+        diagnostics.push(legacyHarnessDiagnostic(candidate.path, harnessCanonicalized.renames));
+      }
+      layers.push({ config: harnessCanonicalized.document, source: loaded.source });
+      merged = mergeOmoConfigRecords(merged, harnessCanonicalized.document);
     }
   }
   const requestedProfile = resolveOmoProfileName({
@@ -20905,10 +20978,10 @@ function readCatalogMultiAgentVersion(model, cachePath) {
   } catch {
     return null;
   }
-  if (!isRecord8(cache) || !Array.isArray(cache.models))
+  if (!isRecord9(cache) || !Array.isArray(cache.models))
     return null;
   for (const entry of cache.models) {
-    if (!isRecord8(entry))
+    if (!isRecord9(entry))
       continue;
     if (entry.slug !== model && entry.id !== model)
       continue;
@@ -20933,7 +21006,7 @@ function readRootModelCatalogPath(config) {
   const single = config.match(/^\s*model_catalog_json\s*=\s*'([^']+)'/m);
   return single?.[1] ?? null;
 }
-function isRecord8(value) {
+function isRecord9(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function removeFeatureFlagSetting(config, featureName) {

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

@@ -0,0 +1,25 @@
+# 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.
+
+## BrowserSkill — driven, not vendored
+
+The attached engine this skill documents is **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.
+
+## 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.

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

@@ -0,0 +1,89 @@
+---
+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."
+---
+
+# Browser
+
+Two engines live behind this skill. Choose before you act:
+
+| You need | Engine | Where |
+|---|---|---|
+| 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) |
+| 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.
+
+## Step 0 — prove the stack before you drive it
+
+```bash
+node "<skill-root>/scripts/browser-doctor.mjs"
+```
+
+It reports one of four states and what to do next:
+
+| 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
+```
+
+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.
+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>`).
+   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.
+
+Command semantics, the flags that behave differently than they read, and the failure table 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]
+```
+
+Then observe again. Respect a `cancelled` or `timed_out` answer; 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 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.
+- **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

package/packages/shared-skills/skills/browser/references/commands.md

@@ -0,0 +1,90 @@
+# Command semantics
+
+Everything here cost a failed attempt to learn. Read it before improvising.
+
+## Sessions
+
+```bash
+bsk session start --json --no-focus --name "<task>"   # keep session_id
+bsk session list
+bsk session stop <id> --json                          # positional id, not --session
+```
+
+Every session-scoped command needs `--session <id>`. `--no-focus` keeps the Agent Window from
+stealing focus; drop it only when the user is watching on purpose.
+
+## Reading
+
+| Command | Returns |
+|---|---|
+| `observe --session <id>` | semantic tree with `@eN` refs and perception probes — **the default read** |
+| `snapshot --session <id>` | static accessibility tree |
+| `get-html --session <id>` | exact markup, hidden metadata |
+| `screenshot --session <id> --out <path>` | PNG; add `--full-page` for a long capture |
+| `evaluate "<js>" --session <id> --json` | `{ok, value}` — **check `.ok`; exit code 0 does not mean the script succeeded** |
+| `console` / `network` | buffered log lines and responses |
+
+**Refs are reissued by every `observe` and `snapshot`.** 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.
+
+`observe --max-tokens <n>` bounds a large page. There is no default cap.
+
+## Acting
+
+| Need | Command |
+|---|---|
+| Click | `click @e3 --session <id>` |
+| Fill | `fill @e3 --value "text" --session <id>` |
+| Select | `select @e3 --value "<option value>" --session <id>` |
+| Key | `press Enter --ref @e3 --session <id>` |
+| Hover | `hover @e3 --session <id>` |
+| Scroll into view | `scroll-to @e3 --session <id>` |
+| Wheel | `wheel --delta-y 600 --session <id>` |
+| Focus / blur | `focus @e3` / `blur @e3` |
+| Upload / download | `upload --file <path>` / `download --out <path>` |
+
+Traps:
+
+- `select` takes the option's **value attribute**, not its visible label.
+- `fill` and `click` accept a CSS selector; **`press --ref` does not** — it answers
+  `ref_not_found` for a selector. `press` without `--ref` goes to the focused node.
+- 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, observe, then act on the
+  revealed item's fresh ref. Markers like `[has-submenu]` and `[expanded]` identify triggers;
+  `observe --probe-hover` finds one when no marker does, at the cost of touching the live page.
+- The clipboard is unavailable in a window started `--no-focus` (no document focus), so read
+  values out of the DOM instead.
+
+## Borrowing a user tab
+
+```bash
+bsk tab list --scope user
+bsk tab borrow <tab-id>
+bsk tab return <tab-id>
+```
+
+Borrowing asks the user to confirm. Never invent a tab id, never repeat a denied borrow, and
+always return what you borrowed (`session stop` also returns them).
+
+## Failures
+
+| Symptom | Meaning | Response |
+|---|---|---|
+| `browsers: []` | extension not connected | ask the user to open the browser / enable the extension |
+| daemon missing | idle exit or reboot | none; the next call restarts it |
+| `cdp_failed: Cannot access a chrome-extension:// URL of different extension` | another extension injected a frame, so the debugger cannot attach to that tab | transient and page-specific; collapse the work into one `evaluate` and retry, or navigate away and back |
+| `permission_denied: element not visible` | hover-gated or clipped control | drive its menu instead |
+| `ref_not_found` | stale ref, or a selector passed to `press` | observe again; use a real ref |
+| version skew warning | CLI and extension disagree | `bsk update` after finishing sessions; the extension updates through its store |
+
+**Two identical failures select a different approach. A third identical attempt is a defect.**
+
+## Sandboxed hosts
+
+If the host kills background children after each command, the daemon cannot survive between calls.
+Set `BSK_AUTO_START=0`, share one `BSK_HOME` across every call, and start
+`bsk daemon start --foreground` in the host's persistent background task. Check readiness with
+`bsk status --json` in a separate call before continuing. Do not loop on launches, delete runtime
+files, or restart a daemon another task is using.