rename BROWSER.md to browser-execute-guide.md

bcode · bcode · commit 85fc1d339b79 · 2026-05-10T17:47:00.000-07:00
Renames the primary browser_execute guide and updates every code/doc reference. The file's role is the same; the name now states what it documents.
diff --git a/packages/bcode-browser/README.md b/packages/bcode-browser/README.md
@@ -12,7 +12,7 @@ See `decisions.md §1c` (three-level model) and `§1d` (this package) in the Bro
 | `src/browser-execute.ts` | In-process JS-eval `browser_execute` body. |
 | `src/session-store.ts` | Per-opencode-session CDP `Session` map. The agent calls `session.connect(...)` from a snippet; subsequent snippets find the same Session. |
 | `src/skills.ts` | Runtime resolver for embedded skills (extract on first call in compiled mode; in-tree path in dev). |
-| `skills/` | `BROWSER.md` (the agent's prompt for `browser_execute`) and `cloud-browser.md` (Way 3 — provision/stop a Browser Use cloud browser via raw HTTP from inside a snippet). Embedded into the binary by `script/embed-skills.ts`. The interaction-skills set inherited from the Python harness was archived 2026-05-09 — we'll reintroduce only what evals show is needed, one skill at a time. |
+| `skills/` | `browser-execute-guide.md` (the agent's prompt for `browser_execute`) and `cloud-browser.md` (Way 3 — provision/stop a Browser Use cloud browser via raw HTTP from inside a snippet). Embedded into the binary by `script/embed-skills.ts`. The interaction-skills set inherited from the Python harness was archived 2026-05-09 — we'll reintroduce only what evals show is needed, one skill at a time. |
 | `script/embed-skills.ts` | Build-time embed; emits `bcode-skills.gen.ts` consumed by the compiled binary. |
 | `test/` | `bun test` smoke coverage for the workspace dynamic-import pattern. |
 
diff --git a/packages/bcode-browser/skills/browser-execute-guide.md b/packages/bcode-browser/skills/browser-execute-guide.md
@@ -1,11 +1,11 @@
-# BROWSER.md — driving a real browser with `browser_execute`
+# browser-execute-guide.md — driving a real browser with `browser_execute`
 
 Use the `browser_execute` tool to run JavaScript against a connected browser via the Chrome DevTools Protocol. The snippet runs in-process; `session` is bound to a long-lived CDP `Session` that persists across calls within the same bcode session. You connect once, drive many.
 
 **Locations:**
 
 - Workspace (read/write your reusable scripts): `<projectRoot>/.bcode/agent-workspace/`. The bcode CLI runs from the project root, so `./.bcode/agent-workspace/foo.ts` works directly with the `read`/`write`/`edit` tools.
-- Skills (read-only reference docs): `{{SKILLS_DIR}}/`. Currently `BROWSER.md` (this file) and `cloud-browser.md`.
+- Skills (read-only reference docs): `{{SKILLS_DIR}}/`. Currently `browser-execute-guide.md` (this file) and `cloud-browser.md`.
 
 ## The model in one paragraph
 
diff --git a/packages/bcode-browser/skills/cloud-browser.md b/packages/bcode-browser/skills/cloud-browser.md
@@ -1,6 +1,6 @@
 # cloud-browser.md — Browser Use cloud browser via raw HTTP
 
-When BROWSER.md sent you here, the user wants a Browser Use cloud browser (Way 3): a clean isolated Chrome on BU's infrastructure, optionally with a geo-located proxy or a synced profile, with a `liveUrl` the user can open to watch you work.
+When browser-execute-guide.md sent you here, the user wants a Browser Use cloud browser (Way 3): a clean isolated Chrome on BU's infrastructure, optionally with a geo-located proxy or a synced profile, with a `liveUrl` the user can open to watch you work.
 
 There is no `browser_open_cloud` tool. You write the HTTP calls yourself in a `browser_execute` snippet. This keeps the connection model symmetric (you also call `session.connect()` for local browsers in Way 1 and Way 2) and gives you full control over the BU API surface — provision, stop, swap profiles, change proxies, anything BU exposes.
 
@@ -78,7 +78,7 @@ await fetch(`https://api.browser-use.com/api/v3/browsers/${id}`, {
 })
 ```
 
-If you'll do this often within one project, save it as `./.bcode/agent-workspace/cloud.ts` (see BROWSER.md "Reusing code") and import it from later snippets.
+If you'll do this often within one project, save it as `./.bcode/agent-workspace/cloud.ts` (see browser-execute-guide.md "Reusing code") and import it from later snippets.
 
 ## Swap
 
diff --git a/packages/bcode-browser/src/browser-execute.ts b/packages/bcode-browser/src/browser-execute.ts
@@ -145,7 +145,7 @@ const serialize = (v: unknown): string => {
 
 // Snippet executor. The CDP Session is resolved per-call from `SessionStore`
 // keyed on `ctx.sessionID`. The agent connects with `await session.connect(...)`
-// in one snippet (Way 1 / Way 2 / Way 3 in BROWSER.md); the Session persists
+// in one snippet (Way 1 / Way 2 / Way 3 in browser-execute-guide.md); the Session persists
 // for follow-up snippets in the same opencode session.
 //
 // `dataDir` is opencode's XDG_DATA_HOME for bcode (~/.local/share/bcode/ on
diff --git a/packages/bcode-browser/src/index.ts b/packages/bcode-browser/src/index.ts
@@ -11,7 +11,7 @@
 //   src/browser-execute.ts — in-process JS-eval browser_execute body
 //   src/session-store.ts   — per-opencode-session CDP Session map
 //   src/skills.ts          — runtime resolver for embedded skills
-//   skills/                — BROWSER.md + cloud-browser.md (embedded into binary)
+//   skills/                — browser-execute-guide.md + cloud-browser.md (embedded into binary)
 //
 // Cloud browser provisioning is intentionally NOT a separate Level-1
 // surface. The agent reads `skills/cloud-browser.md` and writes the
diff --git a/packages/bcode-browser/src/skills.ts b/packages/bcode-browser/src/skills.ts
@@ -2,7 +2,7 @@
 //
 // Materializes the skills tree to `<dataDir>/skills/` and substitutes the
 // `{{SKILLS_DIR}}` placeholder in every file with that absolute path so
-// cross-references inside BROWSER.md (``read `{{SKILLS_DIR}}/cloud-browser.md` ``)
+// cross-references inside browser-execute-guide.md (``read `{{SKILLS_DIR}}/cloud-browser.md` ``)
 // point at a real location.
 //
 // Compiled launches (the user-facing path) read a one-line sentinel at
diff --git a/packages/bcode-browser/test/skills.test.ts b/packages/bcode-browser/test/skills.test.ts
@@ -14,7 +14,7 @@ test("resolveSkillsDir materializes skills with {{SKILLS_DIR}} substituted", asy
   try {
     const dir = await Skills.resolveSkillsDir(dataDir)
     expect(dir).toBe(path.join(dataDir, "skills"))
-    const browser = (await fs.readFile(path.join(dir, "BROWSER.md"), "utf8")).replaceAll("\\", "/")
+    const browser = (await fs.readFile(path.join(dir, "browser-execute-guide.md"), "utf8")).replaceAll("\\", "/")
     expect(browser).not.toContain("{{SKILLS_DIR}}")
     expect(browser).toContain(`${dir.replaceAll("\\", "/")}/cloud-browser.md`)
   } finally {
@@ -29,8 +29,8 @@ test("different dataDirs get their own substituted paths", async () => {
     const dirA = await Skills.resolveSkillsDir(a)
     const dirB = await Skills.resolveSkillsDir(b)
     const [browserA, browserB] = (await Promise.all([
-      fs.readFile(path.join(dirA, "BROWSER.md"), "utf8"),
-      fs.readFile(path.join(dirB, "BROWSER.md"), "utf8"),
+      fs.readFile(path.join(dirA, "browser-execute-guide.md"), "utf8"),
+      fs.readFile(path.join(dirB, "browser-execute-guide.md"), "utf8"),
     ])).map((s) => s.replaceAll("\\", "/"))
     const [a2, b2] = [dirA.replaceAll("\\", "/"), dirB.replaceAll("\\", "/")]
     expect(browserA).toContain(a2)
diff --git a/packages/bcode-browser/test/workspace-import.test.ts b/packages/bcode-browser/test/workspace-import.test.ts
@@ -3,7 +3,7 @@
 // at runtime from a `browser_execute` snippet via
 // `await import("/abs/path?t=" + Date.now())`. We don't run a real
 // `browser_execute` here — the point is to verify the dynamic-import
-// mechanism behaves as the BROWSER.md prompt claims.
+// mechanism behaves as the browser-execute-guide.md prompt claims.
 //
 // All four scenarios run against a real tmp dir, real .ts files, and
 // the real Bun module loader. No mocks.
diff --git a/packages/opencode/src/agent/agent.ts b/packages/opencode/src/agent/agent.ts
@@ -93,7 +93,7 @@ export const layer = Layer.effect(
         const agentWorkspaceGlob = "**/.bcode/agent-workspace/**/*"
         // Browser-skills tree, materialized at runtime to
         // <Global.Path.data>/skills/ in both dev and compiled modes (so the
-        // `{{SKILLS_DIR}}` placeholder in BROWSER.md gets substituted with a
+        // `{{SKILLS_DIR}}` placeholder in browser-execute-guide.md gets substituted with a
         // stable absolute path). Read-only baseline.
         const browserSkillsGlob = path.join(Skills.skillsDir(Global.Path.data), "*")
         const whitelistedDirs = [
diff --git a/packages/opencode/src/tool/browser-execute.ts b/packages/opencode/src/tool/browser-execute.ts
@@ -25,7 +25,7 @@ export const BrowserExecuteTool = Tool.define(
   Effect.gen(function* () {
     const impl = yield* BrowserExecute.make(Global.Path.data)
     return {
-      // Substitute the resolved skills path so BROWSER.md / cloud-browser.md
+      // Substitute the resolved skills path so browser-execute-guide.md / cloud-browser.md
       // references in the description point at concrete locations. Workspace
       // is per-project and agent-discoverable from cwd, so it's not
       // substituted here.
diff --git a/packages/opencode/src/tool/browser-execute.txt b/packages/opencode/src/tool/browser-execute.txt
@@ -1,14 +1,7 @@
-Execute JavaScript against a connected browser via the BrowserCode CDP harness.
+Executes JavaScript in a connected browser.
 
-Use this tool whenever the task requires driving a real browser — automation, scraping, end-to-end testing, or interactive exploration. The snippet runs in-process with one persistent CDP `Session` object that survives across calls in the same opencode session. You connect once and drive many.
-
-Before the first `browser_execute` call of a session, you MUST read `{{SKILLS_DIR}}/BROWSER.md`. It defines the snippet model, the three connection methods (local user Chrome, isolated debug-port Chrome, Browser Use cloud browser), the workspace pattern, the `session` API surface, and gotchas. For cloud-browser specifics, also read `{{SKILLS_DIR}}/cloud-browser.md`.
-
-Always pass a clear, concise `description` of what the snippet does in 3-7 words (e.g. "Connect to local Chrome", "Scrape product titles", "Screenshot homepage"). It surfaces in the TUI as the call's title.
-
-Snippet scope:
-
-- `session` — the live CDP `Session`. You call `session.connect(...)` once at the start of your work; subsequent snippets reuse the same connection. Domain methods follow `session.<Domain>.<method>(params)` and return Promises.
-- standard JS globals (`console.log` etc. stream back to the user; `process.env` is available for reading `BROWSER_USE_API_KEY` etc.).
-
-Top-level `import` is not allowed inside a snippet. To reuse code across calls, save it as a `.ts` file under `./.bcode/agent-workspace/` (per-project, tracked-by-default in git) and `await import("/abs/path?t=" + Date.now())` it from a later snippet.
+Usage:
+- Use this tool whenever the task requires driving a real browser.
+- Use this tool to read webpages that block the webfetch tool.
+- IMPORTANT: you MUST use the Read tool first to read `{{SKILLS_DIR}}/browser-execute-guide.md`. This tool will fail if you did not read these directions first.
+- Always pass a clear, precise, and low verbosity `description` of what the JS snippet does.
