diff --git a/CHANGELOG.md b/CHANGELOG.md
index c5af090ea..9e3c37dd2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+### ⚠ BREAKING CHANGES
+
+* **browser** — replace the `--session <name>` flag with a `<session>` positional argument that immediately follows `browser`. `opencli browser work click 12` instead of `opencli browser --session work click 12`; `opencli browser work bind` instead of `opencli browser bind --session work`. Required-flag semantics are now encoded structurally as a positional, matching the Docker/git convention for required operation-target identifiers. The internal `--session` flag is preserved for the daemon protocol and for direct `program.parseAsync` callers but is no longer part of the user-facing surface.
+
 ## [1.7.18](https://github.com/jackwener/opencli/compare/v1.7.17...v1.7.18) (2026-05-12)
 
 Hotfix release for the 1.7.17 doctor regression: `opencli doctor` failed connectivity probe with `Browser session is required` because the doctor probe didn't pass a session to the new strict-session browser bridge. Also adds new adapters and adapter fixes that were ready immediately after 1.7.17.
diff --git a/README.md b/README.md
index a793e8eae..070fae6ac 100644
--- a/README.md
+++ b/README.md
@@ -152,7 +152,7 @@ The agent handles all the `opencli browser` commands internally — you just des
 
 Available browser commands include `open`, `state`, `click`, `type`, `fill`, `select`, `keys`, `wait`, `get`, `find`, `extract`, `frames`, `screenshot`, `scroll`, `back`, `eval`, `network`, `tab list`, `tab new`, `tab select`, `tab close`, `init`, `verify`, and `close`.
 
-`opencli browser` commands require `--session <name>`. `opencli browser --session work open <url>` and `opencli browser --session work tab new [url]` both return a target ID. Use `opencli browser --session work tab list` to inspect target IDs, then pass `--tab <targetId>` to route a command to a specific tab. `tab new` creates a new tab without changing the default browser target; only `tab select <targetId>` promotes that tab to the default target for later untargeted commands in the same session.
+`opencli browser` commands require a `<session>` positional immediately after `browser`. `opencli browser work open <url>` and `opencli browser work tab new [url]` both return a target ID. Use `opencli browser work tab list` to inspect target IDs, then pass `--tab <targetId>` to route a command to a specific tab. `tab new` creates a new tab without changing the default browser target; only `tab select <targetId>` promotes that tab to the default target for later untargeted commands in the same session.
 
 ## Core Concepts
 
@@ -160,7 +160,7 @@ Available browser commands include `open`, `state`, `click`, `type`, `fill`, `se
 
 `opencli browser` commands are the low-level primitives that AI Agents use to operate websites. You don't run these manually — instead, install the `opencli-adapter-author` skill into your AI agent, describe what you want in natural language, and the agent handles the browser operations.
 
-For example, tell your agent: *"Help me check my Xiaohongshu notifications"* — the agent will use `opencli browser --session <name> open`, `state`, `click`, etc. under the hood.
+For example, tell your agent: *"Help me check my Xiaohongshu notifications"* — the agent will use `opencli browser <session> open`, `state`, `click`, etc. under the hood.
 
 ### Built-in adapters: stable commands
 
@@ -174,7 +174,7 @@ When the site you need is not yet covered, use the `opencli-adapter-author` skil
 2. Discover the right endpoint — network inspection, initial state, bundle search, token trace, or interceptor fallback.
 3. Decide the auth strategy — `PUBLIC` / `COOKIE` / `INTERCEPT` / `UI` / `LOCAL`.
 4. Decode response fields and design output columns.
-5. `opencli browser --session recon analyze <url>` for one-shot recon, then `opencli browser --session recon init <site>/<name>` → write adapter → `opencli browser --session recon verify <site>/<name>`.
+5. `opencli browser recon analyze <url>` for one-shot recon, then `opencli browser recon init <site>/<name>` → write adapter → `opencli browser recon verify <site>/<name>`.
 6. Persist site knowledge to `~/.opencli/sites/<site>/` so the next adapter for the same site is faster.
 
 ### CLI Hub and desktop adapters
@@ -207,7 +207,7 @@ OpenCLI is not only for websites. It can also:
 | `OPENCLI_VERBOSE` | `false` | Enable verbose logging (`-v` flag also works) |
 | `DEBUG_SNAPSHOT` | — | Set to `1` for DOM snapshot debug output |
 
-`opencli browser *` requires an explicit `--session <name>`, uses a foreground browser window by default, and keeps that session's tab lease until `browser --session <name> close` or idle cleanup. Browser-backed adapters use a background adapter window and release one-shot tab leases by default. Interactive adapters can declare `siteSession: 'persistent'` to keep a stable site tab for continuity; pass `--site-session ephemeral` for a one-shot tab.
+`opencli browser *` requires an explicit `<session>` positional, uses a foreground browser window by default, and keeps that session's tab lease until `opencli browser <session> close` or idle cleanup. Browser-backed adapters use a background adapter window and release one-shot tab leases by default. Interactive adapters can declare `siteSession: 'persistent'` to keep a stable site tab for continuity; pass `--site-session ephemeral` for a one-shot tab.
 
 ## Update
 
@@ -411,10 +411,10 @@ See [Plugins Guide](./docs/guide/plugins.md) for creating your own plugin.
 Before writing any adapter code, read the [`opencli-adapter-author` skill](./skills/opencli-adapter-author/SKILL.md). It takes you end-to-end:
 
 - Recon the site and pick a pattern (SPA / SSR / JSONP / Token / Streaming).
-- Discover the right endpoint via `opencli browser --session <name> network`, `eval`, or the interceptor fallback.
+- Discover the right endpoint via `opencli browser <session> network`, `eval`, or the interceptor fallback.
 - Decide auth strategy (`PUBLIC` / `COOKIE` / `INTERCEPT` / `UI` / `LOCAL`).
-- Run `opencli browser --session recon analyze <url>` for one-shot recon, decode response fields, design columns, scaffold with `opencli browser --session recon init`.
-- Verify with `opencli browser --session recon verify <site>/<name>` before shipping.
+- Run `opencli browser recon analyze <url>` for one-shot recon, decode response fields, design columns, scaffold with `opencli browser recon init`.
+- Verify with `opencli browser recon verify <site>/<name>` before shipping.
 
 For long-lived personal commands that should live in your own Git repo, use a local plugin instead; see [Extending OpenCLI](./docs/guide/extending-opencli.md). Quick private adapters can still live at `~/.opencli/clis/<site>/<name>.js`. Site knowledge (endpoints, field maps, fixtures) accumulates in `~/.opencli/sites/<site>/` so the next adapter for the same site starts from context instead of zero.
 
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 4356a3d1d..19d9c5650 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -136,7 +136,7 @@ Agent 在内部自动处理所有 `opencli browser` 命令——你只需用自
 
 `browser` 可用命令包括：`open`、`state`、`click`、`type`、`fill`、`select`、`keys`、`wait`、`get`、`find`、`extract`、`frames`、`screenshot`、`scroll`、`back`、`eval`、`network`、`tab list`、`tab new`、`tab select`、`tab close`、`init`、`verify`、`close`。
 
-`opencli browser` 命令必须显式传 `--session <name>`。`opencli browser --session work open <url>` 和 `opencli browser --session work tab new [url]` 都会返回 target ID。`opencli browser --session work tab list` 用来查看当前已存在 tab 的 target ID，再通过 `--tab <targetId>` 把命令明确路由到某个 tab。`tab new` 只会新建 tab，不会改变默认浏览器目标；只有显式执行 `tab select <targetId>`，才会把该 tab 设为同一 session 后续未指定 target 的默认目标。
+`opencli browser` 命令必须紧跟一个 `<session>` 位置参数。`opencli browser work open <url>` 和 `opencli browser work tab new [url]` 都会返回 target ID。`opencli browser work tab list` 用来查看当前已存在 tab 的 target ID，再通过 `--tab <targetId>` 把命令明确路由到某个 tab。`tab new` 只会新建 tab，不会改变默认浏览器目标；只有显式执行 `tab select <targetId>`，才会把该 tab 设为同一 session 后续未指定 target 的默认目标。
 
 ## 核心概念
 
@@ -144,7 +144,7 @@ Agent 在内部自动处理所有 `opencli browser` 命令——你只需用自
 
 `opencli browser` 命令是 AI Agent 操作网站的底层原语。你不需要手动运行这些命令——把 `opencli-adapter-author` skill 安装到你的 AI Agent 中，用自然语言描述你想做的事，Agent 会自动处理浏览器操作。
 
-比如你告诉 Agent：*"帮我看看小红书的通知"*——Agent 会在底层调用 `opencli browser --session <name> open`、`state`、`click` 等命令。
+比如你告诉 Agent：*"帮我看看小红书的通知"*——Agent 会在底层调用 `opencli browser <session> open`、`state`、`click` 等命令。
 
 ### 内置适配器：稳定命令
 
@@ -158,7 +158,7 @@ Agent 在内部自动处理所有 `opencli browser` 命令——你只需用自
 2. 发现目标 endpoint——network 精读、initial state、bundle 搜索、token 溯源，或 interceptor 兜底
 3. 定认证策略——`PUBLIC` / `COOKIE` / `INTERCEPT` / `UI` / `LOCAL`
 4. 字段解码 + 设计输出列
-5. `opencli browser --session recon analyze <url>` 一步侦察，再 `opencli browser --session recon init <site>/<name>` → 写适配器 → `opencli browser --session recon verify <site>/<name>`
+5. `opencli browser recon analyze <url>` 一步侦察，再 `opencli browser recon init <site>/<name>` → 写适配器 → `opencli browser recon verify <site>/<name>`
 6. 把站点知识沉到 `~/.opencli/sites/<site>/`，下次写同站点的其他命令直接吃缓存
 
 ### CLI 枢纽与桌面端适配器
@@ -190,7 +190,7 @@ OpenCLI 不只是网站 CLI，还可以：
 | `OPENCLI_VERBOSE` | `false` | 启用详细日志（`-v` 也可以） |
 | `DEBUG_SNAPSHOT` | — | 设为 `1` 输出 DOM 快照调试信息 |
 
-`opencli browser *` 必须显式传 `--session <name>`，默认使用前台窗口，并保留该 session 的 tab lease，直到你手动执行 `opencli browser --session <name> close` 或等空闲超时。浏览器型 adapter 默认使用后台 adapter 窗口并在命令结束后释放一次性 tab lease；如果需要调试最终页面，可以传 `--window foreground --keep-tab true`。
+`opencli browser *` 必须紧跟一个 `<session>` 位置参数，默认使用前台窗口，并保留该 session 的 tab lease，直到你手动执行 `opencli browser <session> close` 或等空闲超时。浏览器型 adapter 默认使用后台 adapter 窗口并在命令结束后释放一次性 tab lease；如果需要调试最终页面，可以传 `--window foreground --keep-tab true`。
 
 ## 更新
 
@@ -510,10 +510,10 @@ opencli plugin uninstall my-tool                            # 卸载
 在动代码前，先读 [`opencli-adapter-author` skill](./skills/opencli-adapter-author/SKILL.md)。它把整个流程串起来：
 
 - 侦察站点，选定 pattern（SPA / SSR / JSONP / Token / Streaming）
-- 用 `opencli browser --session <name> network`、`eval`、interceptor 等找到目标 endpoint
+- 用 `opencli browser <name> network`、`eval`、interceptor 等找到目标 endpoint
 - 定认证策略（`PUBLIC` / `COOKIE` / `INTERCEPT` / `UI` / `LOCAL`）
-- 先用 `opencli browser --session recon analyze <url>` 一步侦察，再字段解码、设计 columns、`opencli browser --session recon init` 生成骨架
-- 交付前用 `opencli browser --session recon verify <site>/<name>` 验证
+- 先用 `opencli browser recon analyze <url>` 一步侦察，再字段解码、设计 columns、`opencli browser recon init` 生成骨架
+- 交付前用 `opencli browser recon verify <site>/<name>` 验证
 
 在仓库外写的私有适配器放到 `~/.opencli/clis/<site>/<name>.js`；每个站点的 endpoint、字段映射、抓包样本会累积在 `~/.opencli/sites/<site>/`，下次写同站点的其他命令可以直接复用。
 
diff --git a/docs/guide/browser-bridge.md b/docs/guide/browser-bridge.md
index 7d701d10a..36c09420f 100644
--- a/docs/guide/browser-bridge.md
+++ b/docs/guide/browser-bridge.md
@@ -27,22 +27,22 @@ opencli doctor            # Check extension + daemon connectivity
 
 ## Tab Targeting
 
-Browser commands require an explicit `--session <name>`. Use the same session name for a multi-step flow, and use different names to isolate parallel work.
+Browser commands require an explicit `<session>` positional immediately after `browser`. Use the same session name for a multi-step flow, and use different names to isolate parallel work.
 
 ```bash
-opencli browser --session baidu open https://www.baidu.com/
-opencli browser --session baidu tab list
-opencli browser --session baidu tab new https://www.baidu.com/
-opencli browser --session baidu eval --tab <targetId> 'document.title'
-opencli browser --session baidu tab select <targetId>
-opencli browser --session baidu get title
-opencli browser --session baidu tab close <targetId>
+opencli browser baidu open https://www.baidu.com/
+opencli browser baidu tab list
+opencli browser baidu tab new https://www.baidu.com/
+opencli browser baidu eval --tab <targetId> 'document.title'
+opencli browser baidu tab select <targetId>
+opencli browser baidu get title
+opencli browser baidu tab close <targetId>
 ```
 
 Key rules:
 
-- `opencli browser --session <name> open <url>` and `opencli browser --session <name> tab new [url]` return a `targetId`.
-- `opencli browser --session <name> tab list` prints the `targetId` values of tabs that already exist.
+- `opencli browser <session> open <url>` and `opencli browser <session> tab new [url]` return a `targetId`.
+- `opencli browser <session> tab list` prints the `targetId` values of tabs that already exist.
 - `--tab <targetId>` routes a single browser command to that specific tab.
 - `tab new` creates a new tab but does not change the default browser target.
 - `tab select <targetId>` makes that tab the default target for later untargeted `opencli browser ...` commands.
diff --git a/docs/zh/guide/browser-bridge.md b/docs/zh/guide/browser-bridge.md
index 3d7180a5a..36e5e006a 100644
--- a/docs/zh/guide/browser-bridge.md
+++ b/docs/zh/guide/browser-bridge.md
@@ -25,22 +25,22 @@ opencli doctor            # 检查扩展 + 守护进程连接
 
 ## 多 Tab 定位
 
-浏览器命令必须显式传 `--session <name>`。同一个多步骤流程使用同一个 session；并行任务使用不同 session 隔离。
+浏览器命令必须紧跟一个 `<session>` 位置参数。同一个多步骤流程使用同一个 session；并行任务使用不同 session 隔离。
 
 ```bash
-opencli browser --session baidu open https://www.baidu.com/
-opencli browser --session baidu tab list
-opencli browser --session baidu tab new https://www.baidu.com/
-opencli browser --session baidu eval --tab <targetId> 'document.title'
-opencli browser --session baidu tab select <targetId>
-opencli browser --session baidu get title
-opencli browser --session baidu tab close <targetId>
+opencli browser baidu open https://www.baidu.com/
+opencli browser baidu tab list
+opencli browser baidu tab new https://www.baidu.com/
+opencli browser baidu eval --tab <targetId> 'document.title'
+opencli browser baidu tab select <targetId>
+opencli browser baidu get title
+opencli browser baidu tab close <targetId>
 ```
 
 规则如下：
 
-- `opencli browser --session <name> open <url>` 和 `opencli browser --session <name> tab new [url]` 都会返回 `targetId`。
-- `opencli browser --session <name> tab list` 会打印当前已存在 tab 的 `targetId`。
+- `opencli browser <session> open <url>` 和 `opencli browser <session> tab new [url]` 都会返回 `targetId`。
+- `opencli browser <session> tab list` 会打印当前已存在 tab 的 `targetId`。
 - `--tab <targetId>` 会把单条 browser 命令路由到对应 tab。
 - `tab new` 只会新建 tab，不会改变默认浏览器目标。
 - `tab select <targetId>` 会把该 tab 设为后续未显式指定 target 的 `opencli browser ...` 命令默认目标。
diff --git a/skills/opencli-browser/SKILL.md b/skills/opencli-browser/SKILL.md
index 3f25ecccd..188724be9 100644
--- a/skills/opencli-browser/SKILL.md
+++ b/skills/opencli-browser/SKILL.md
@@ -24,26 +24,26 @@ Until `doctor` is green, nothing else will work. Typical failures: Chrome not ru
 
 ## Session lifecycle
 
-- `opencli browser *` commands require `--session <name>`. Use the same session name for a multi-step flow; use a different name to isolate parallel browser work.
-- Owned browser sessions keep a tab lease alive between calls. Release it with `opencli browser --session <name> close` or let the idle timeout expire.
-- `opencli browser bind --session <name>` binds the Chrome tab you already have open to that session. Use this for logged-in pages, SSO flows, or pages you manually positioned before handing control to the agent.
+- `opencli browser *` commands require a `<session>` positional immediately after `browser`. Use the same session name for a multi-step flow; use a different name to isolate parallel browser work.
+- Owned browser sessions keep a tab lease alive between calls. Release it with `opencli browser <session> close` or let the idle timeout expire.
+- `opencli browser <session> bind` binds the Chrome tab you already have open to that session. Use this for logged-in pages, SSO flows, or pages you manually positioned before handing control to the agent.
 - `--window foreground|background` (or `OPENCLI_WINDOW=foreground|background`) chooses whether OpenCLI creates/focuses a foreground browser window or uses a background browser window for owned sessions.
 
 ### Bind Tab
 
 ```bash
-opencli browser bind --session gmail
-opencli browser --session gmail state
-opencli browser --session gmail click "Search"
-opencli browser --session gmail network
-opencli browser unbind --session gmail
+opencli browser gmail bind
+opencli browser gmail state
+opencli browser gmail click "Search"
+opencli browser gmail network
+opencli browser gmail unbind
 ```
 
-Binding never owns the user window and never closes the user tab. It fails closed if the tab is closed or becomes non-debuggable. Re-run `bind --session <name>` when you switch to a different real tab.
+Binding never owns the user window and never closes the user tab. It fails closed if the tab is closed or becomes non-debuggable. Re-run `opencli browser <session> bind` when you switch to a different real tab.
 
 Navigation is allowed on bound sessions because the session now represents explicit agent ownership of that tab. Tab mutation (`tab new`, `tab select`, `tab close`) is still blocked for bound sessions. Use an owned session when you want OpenCLI to manage tab lifecycle.
 
-`opencli browser sessions` returns `idleMsRemaining: null` for bound sessions. That means there is no OpenCLI idle-close timer; the binding lasts until `unbind`, tab close, window close, or daemon restart.
+Bound sessions have no OpenCLI idle-close timer; the binding lasts until `unbind`, tab close, window close, or daemon restart.
 
 ---
 
@@ -210,8 +210,8 @@ Default output keeps JSON/XML/plain-text and JS-like API responses, then drops o
 | `browser tab close [targetId]` | Close by `page`. |
 | `browser back` | History back on the active tab. |
 | `browser close` | Release the current owned browser session when done. |
-| `browser bind --session <name>` | Bind the current Chrome tab to a browser session. |
-| `browser unbind --session <name>` | Detach a bound session without closing the user tab/window. |
+| `browser <session> bind` | Bind the current Chrome tab to the named browser session. |
+| `browser <session> unbind` | Detach the named bound session without closing the user tab/window. |
 
 ---
 
@@ -299,9 +299,9 @@ Rule of thumb: **one `state` per page transition, one `find` per follow-up query
 **Good — one shell, live session:**
 
 ```bash
-opencli browser --session hn open "https://news.ycombinator.com" \
-  && opencli browser --session hn state \
-  && opencli browser --session hn click 3
+opencli browser hn open "https://news.ycombinator.com" \
+  && opencli browser hn state \
+  && opencli browser hn click 3
 ```
 
 **Bad — each line is a fresh shell, refs from call 1 are already forgotten when call 2 runs.** (Only a problem if you rely on shell-scoped state; browser refs themselves persist in-page, but interleaving unrelated shells invites races.) Prefer `&&` when the steps are meant to be atomic.
@@ -315,24 +315,24 @@ opencli browser --session hn open "https://news.ycombinator.com" \
 ### Fill a login form
 
 ```bash
-opencli browser --session login open "https://example.com/login"
-opencli browser --session login state                          # find [N] for email, password, submit
-opencli browser --session login type 4 "me@example.com"
-opencli browser --session login type 5 "hunter2"
-opencli browser --session login get value 4                    # verify (autocomplete can eat chars)
-opencli browser --session login click 6                        # submit
-opencli browser --session login wait selector "[data-testid=account-menu]" --timeout 15000
-opencli browser --session login state                          # fresh refs on the logged-in page
+opencli browser login open "https://example.com/login"
+opencli browser login state                          # find [N] for email, password, submit
+opencli browser login type 4 "me@example.com"
+opencli browser login type 5 "hunter2"
+opencli browser login get value 4                    # verify (autocomplete can eat chars)
+opencli browser login click 6                        # submit
+opencli browser login wait selector "[data-testid=account-menu]" --timeout 15000
+opencli browser login state                          # fresh refs on the logged-in page
 ```
 
 ### Pick from a long dropdown
 
 ```bash
-opencli browser --session form state                          # sidebar shows [12] <select name=country>
-opencli browser --session form find --css "select[name=country]"
+opencli browser form state                          # sidebar shows [12] <select name=country>
+opencli browser form find --css "select[name=country]"
 # the compound.options_total is 137, but compound.current is "" — unselected.
-opencli browser --session form select 12 "Uruguay"
-opencli browser --session form get value 12                   # { value: "uy", match_level: "exact" }
+opencli browser form select 12 "Uruguay"
+opencli browser form get value 12                   # { value: "uy", match_level: "exact" }
 ```
 
 ### Pick from a custom React dropdown
@@ -341,13 +341,13 @@ Use this for Radix, shadcn, Material UI, Mercury-style category fields, and
 other controls that are not native `<select>`.
 
 ```bash
-opencli browser --session mercury state                          # find category trigger ref
+opencli browser mercury state                          # find category trigger ref
 # If the trigger/option is not clear, use AX:
-opencli browser --session mercury state --source ax              # look for combobox/button/listbox/option names
-opencli browser --session mercury click 7                        # click category trigger
-opencli browser --session mercury state --source ax              # fresh refs after the portal/listbox opens
-opencli browser --session mercury click 12                       # click option
-opencli browser --session mercury get text 7                     # verify visible selected label
+opencli browser mercury state --source ax              # look for combobox/button/listbox/option names
+opencli browser mercury click 7                        # click category trigger
+opencli browser mercury state --source ax              # fresh refs after the portal/listbox opens
+opencli browser mercury click 12                       # click option
+opencli browser mercury get text 7                     # verify visible selected label
 ```
 
 Do not use `browser select` on these widgets. `browser select` is only for
@@ -360,7 +360,7 @@ When deciding whether AX refs are better for a page, collect metrics without
 sharing page contents:
 
 ```bash
-opencli browser --session compare state --compare-sources
+opencli browser compare state --compare-sources
 ```
 
 Report `sources.dom.refs`, `sources.ax.refs`, `frame_sections`,
@@ -370,28 +370,28 @@ arguing that AX should become the default on a site.
 ### Scrape a list via network instead of DOM
 
 ```bash
-opencli browser --session hn open "https://news.ycombinator.com"
-opencli browser --session hn network --filter "title,score"
+opencli browser hn open "https://news.ycombinator.com"
+opencli browser hn network --filter "title,score"
 # -> find the /topstories entry, note its key
-opencli browser --session hn network --detail topstories-a1b2
+opencli browser hn network --detail topstories-a1b2
 ```
 
 ### Read a long article in chunks
 
 ```bash
-opencli browser --session article open "https://blog.example.com/long-post"
-opencli browser --session article extract --chunk-size 8000
+opencli browser article open "https://blog.example.com/long-post"
+opencli browser article extract --chunk-size 8000
 # -> content + next_start_char: 8000
-opencli browser --session article extract --start 8000 --chunk-size 8000
+opencli browser article extract --start 8000 --chunk-size 8000
 # ...until next_start_char is null
 ```
 
 ### Cross-origin iframe
 
 ```bash
-opencli browser --session checkout frames
+opencli browser checkout frames
 # -> [{"index": 0, "url": "https://checkout.stripe.com/...", ...}]
-opencli browser --session checkout eval "(() => document.querySelector('input[name=cardnumber]')?.value)()" --frame 0
+opencli browser checkout eval "(() => document.querySelector('input[name=cardnumber]')?.value)()" --frame 0
 ```
 
 `browser state --source ax` may omit cross-origin iframe contents or fail to
diff --git a/skills/opencli-usage/SKILL.md b/skills/opencli-usage/SKILL.md
index 54f75957d..048e6bb94 100644
--- a/skills/opencli-usage/SKILL.md
+++ b/skills/opencli-usage/SKILL.md
@@ -12,7 +12,7 @@ OpenCLI turns any website, Electron desktop app, or external CLI into a uniform
 
 - **Adapter commands** — `opencli <site> <command> [...]`. Built-in adapters live in `clis/`, user adapters in `~/.opencli/clis/`. Each is backed by a strategy (`PUBLIC | COOKIE | INTERCEPT | UI | LOCAL`) that tells you whether a Chrome session is needed.
 - **Browser driving** — `opencli browser *` subcommands (`open`, `state`, `click`, `type`, `select`, `find`, `extract`, `network`, …) for ad-hoc interaction and scraping when no adapter covers the task. See `opencli-browser`.
-- **Current-tab binding** — `opencli browser bind --session <name>` attaches the Chrome tab the user already opened/logged into to that browser session. Follow-up commands use `opencli browser --session <name> ...`. See `opencli-browser` before using it; bound sessions still block tab mutation.
+- **Current-tab binding** — `opencli browser <session> bind` attaches the Chrome tab the user already opened/logged into to that browser session. Follow-up commands use `opencli browser <session> ...`. See `opencli-browser` before using it; bound sessions still block tab mutation.
 - **External CLI passthrough** — `opencli gh`, `opencli docker`, `opencli vercel`, etc. Managed via `opencli external install <name>` (auto-install from `external-clis.yaml`) or `opencli external register <name>` (bring your own).
 
 ## Install
diff --git a/src/cli-argv-preprocess.test.ts b/src/cli-argv-preprocess.test.ts
new file mode 100644
index 000000000..d49ebbd7f
--- /dev/null
+++ b/src/cli-argv-preprocess.test.ts
@@ -0,0 +1,142 @@
+import { describe, expect, it } from 'vitest';
+import { getBrowserSubcommandNames, rewriteBrowserArgv } from './cli-argv-preprocess.js';
+
+describe('rewriteBrowserArgv', () => {
+  it('rewrites `browser <session> <subcommand>` into `browser --session <name> <subcommand>`', () => {
+    expect(rewriteBrowserArgv(['browser', 'work', 'state'])).toEqual([
+      'browser',
+      '--session',
+      'work',
+      'state',
+    ]);
+  });
+
+  it('rewrites with subcommand arguments preserved', () => {
+    expect(rewriteBrowserArgv(['browser', 'mercury', 'open', 'https://x.com'])).toEqual([
+      'browser',
+      '--session',
+      'mercury',
+      'open',
+      'https://x.com',
+    ]);
+  });
+
+  it('rewrites `browser <session> bind`', () => {
+    expect(rewriteBrowserArgv(['browser', 'mercury', 'bind'])).toEqual([
+      'browser',
+      '--session',
+      'mercury',
+      'bind',
+    ]);
+  });
+
+  it('leaves argv alone when session omitted and a subcommand follows', () => {
+    // Commander surfaces the required-flag error itself.
+    expect(rewriteBrowserArgv(['browser', 'state'])).toEqual(['browser', 'state']);
+    expect(rewriteBrowserArgv(['browser', 'bind'])).toEqual(['browser', 'bind']);
+  });
+
+  it('leaves argv alone when the token after `browser` is a flag', () => {
+    expect(rewriteBrowserArgv(['browser', '--help'])).toEqual(['browser', '--help']);
+    expect(rewriteBrowserArgv(['browser', '-h'])).toEqual(['browser', '-h']);
+  });
+
+  it('refuses the retired `opencli browser --session foo ...` user form', () => {
+    // The flag form is no longer a public entrance. Tests calling
+    // program.parseAsync directly bypass the preprocessor, so internal
+    // callers still work; but the user-facing pipeline throws.
+    expect(() => rewriteBrowserArgv(['browser', '--session', 'foo', 'state']))
+      .toThrowError(/no longer a public option/i);
+    expect(() => rewriteBrowserArgv(['browser', '--session=foo', 'state']))
+      .toThrowError(/no longer a public option/i);
+  });
+
+  it('leaves argv alone when `browser` is not present', () => {
+    expect(rewriteBrowserArgv(['twitter', 'tweets', '@elonmusk'])).toEqual([
+      'twitter',
+      'tweets',
+      '@elonmusk',
+    ]);
+    expect(rewriteBrowserArgv(['doctor'])).toEqual(['doctor']);
+  });
+
+  it('returns argv unchanged when `browser` is the last token', () => {
+    expect(rewriteBrowserArgv(['browser'])).toEqual(['browser']);
+  });
+
+  it('only rewrites when `browser` is the root command, not deeper in argv', () => {
+    // `opencli adapter init browser/x` — the literal `browser` is a path argument,
+    // not the root command. Must not be touched.
+    expect(rewriteBrowserArgv(['adapter', 'init', 'browser', 'x'])).toEqual([
+      'adapter',
+      'init',
+      'browser',
+      'x',
+    ]);
+    // Same for URLs or arbitrary arg values that happen to contain `browser`.
+    expect(rewriteBrowserArgv(['twitter', 'tweets', 'https://browser.example.com'])).toEqual([
+      'twitter',
+      'tweets',
+      'https://browser.example.com',
+    ]);
+    // First-match heuristic must NOT rewrite when an earlier non-flag token
+    // already established a different root command.
+    expect(rewriteBrowserArgv(['list', 'browser', 'state'])).toEqual([
+      'list',
+      'browser',
+      'state',
+    ]);
+  });
+
+  it('skips leading root flags before identifying the root command', () => {
+    // `--profile` takes a value — the value is not the command.
+    expect(rewriteBrowserArgv(['--profile', 'work', 'browser', 'mercury', 'state'])).toEqual([
+      '--profile',
+      'work',
+      'browser',
+      '--session',
+      'mercury',
+      'state',
+    ]);
+    // Long form with `=` separator consumes one slot only.
+    expect(rewriteBrowserArgv(['--profile=work', 'browser', 'mercury', 'state'])).toEqual([
+      '--profile=work',
+      'browser',
+      '--session',
+      'mercury',
+      'state',
+    ]);
+    // Boolean flags don't consume values.
+    expect(rewriteBrowserArgv(['-v', 'browser', 'mercury', 'state'])).toEqual([
+      '-v',
+      'browser',
+      '--session',
+      'mercury',
+      'state',
+    ]);
+  });
+
+  it('leaves argv alone when the root command is not `browser`, even if `browser` appears later', () => {
+    // The first browser keyword does NOT win — it must be at the root.
+    expect(rewriteBrowserArgv(['twitter', 'browser', 'work', 'state'])).toEqual([
+      'twitter',
+      'browser',
+      'work',
+      'state',
+    ]);
+  });
+
+  it('reserved subcommand list covers every known browser subcommand registered in cli.ts', () => {
+    const names = getBrowserSubcommandNames();
+    const required = [
+      'analyze', 'back', 'bind', 'check', 'click', 'close', 'console', 'dblclick',
+      'dialog', 'drag', 'eval', 'extract', 'fill', 'find', 'focus', 'frames',
+      'get', 'hover', 'init', 'keys', 'network', 'open', 'screenshot', 'scroll',
+      'select', 'state', 'tab', 'type', 'unbind', 'uncheck', 'upload', 'verify',
+      'wait',
+    ];
+    for (const name of required) {
+      expect(names.has(name)).toBe(true);
+    }
+  });
+});
diff --git a/src/cli-argv-preprocess.ts b/src/cli-argv-preprocess.ts
new file mode 100644
index 000000000..567885c21
--- /dev/null
+++ b/src/cli-argv-preprocess.ts
@@ -0,0 +1,132 @@
+/**
+ * argv preprocessing: rewrite `opencli browser <session> <subcommand> ...`
+ * into `opencli browser --session <session> <subcommand> ...` so commander
+ * (which can't combine a parent positional with subcommand dispatch) can parse it.
+ *
+ * The user-facing form is positional; the internal form uses --session. Help text
+ * for the `browser` command is overridden to advertise the positional form.
+ */
+
+/**
+ * Browser subcommand names. If `<session>` would collide with one of these,
+ * we treat it as a missing-positional error and leave argv alone so commander
+ * reports a usable diagnostic.
+ *
+ * Keep in sync with the subcommands declared on the `browser` command in cli.ts.
+ */
+const BROWSER_SUBCOMMAND_NAMES: ReadonlySet<string> = new Set([
+  'analyze',
+  'back',
+  'bind',
+  'check',
+  'click',
+  'close',
+  'console',
+  'dblclick',
+  'dialog',
+  'drag',
+  'eval',
+  'extract',
+  'fill',
+  'find',
+  'focus',
+  'frames',
+  'get',
+  'help',
+  'hover',
+  'init',
+  'keys',
+  'network',
+  'open',
+  'screenshot',
+  'scroll',
+  'select',
+  'state',
+  'tab',
+  'type',
+  'unbind',
+  'uncheck',
+  'upload',
+  'verify',
+  'wait',
+]);
+
+/**
+ * Root program options that consume the following token as their value. Used by
+ * the preprocessor to identify which token is the root command name (so e.g.
+ * `opencli --profile work browser foo state` is recognised as the `browser`
+ * command with `<session>=foo`, not the value of --profile).
+ *
+ * Keep in sync with `program.option(...)` calls in cli.ts.
+ */
+const ROOT_VALUE_FLAGS: ReadonlySet<string> = new Set(['--profile']);
+
+/**
+ * Returns the set of reserved subcommand names (exposed for tests so they stay
+ * synced with the actual registrations in cli.ts).
+ */
+export function getBrowserSubcommandNames(): ReadonlySet<string> {
+  return BROWSER_SUBCOMMAND_NAMES;
+}
+
+/**
+ * Rewrite `argv` to convert the positional `<session>` after `browser`
+ * into the internal `--session <name>` flag form.
+ *
+ * Only acts when `browser` is the root command (i.e. the first non-flag token
+ * after any leading root options), so it can't mis-interpret occurrences of
+ * the literal word `browser` deeper in the argv (e.g. `opencli adapter init
+ * browser/x`, or a URL value containing `browser`).
+ *
+ * Leaves argv unchanged when:
+ *   - root command is not `browser`
+ *   - the token after `browser` is a flag (e.g. `--help`)
+ *   - the token after `browser` is a known subcommand name (session was
+ *     omitted; commander will surface its own required-flag error)
+ */
+export function rewriteBrowserArgv(argv: readonly string[]): string[] {
+  const result = [...argv];
+  // Walk past leading root flags + their values to find the root command token.
+  let i = 0;
+  while (i < result.length) {
+    const tok = result[i];
+    if (!tok.startsWith('-')) break;
+    // `--flag=value` consumes one slot regardless of whether the flag expects a value.
+    if (tok.includes('=')) {
+      i += 1;
+      continue;
+    }
+    if (ROOT_VALUE_FLAGS.has(tok) && i + 1 < result.length) {
+      i += 2;
+    } else {
+      i += 1;
+    }
+  }
+  if (result[i] !== 'browser') return result;
+  const sessionIdx = i + 1;
+  const next = result[sessionIdx];
+  if (next === undefined) return result;
+  // The retired `--session` flag must not be a working public entrance.
+  if (next === '--session' || next === '--session=' || next.startsWith('--session=')) {
+    throw new BrowserSessionArgvError(
+      'The `--session` flag is no longer a public option. Use the positional form: opencli browser <session> <command>',
+    );
+  }
+  if (next.startsWith('-')) return result;
+  if (BROWSER_SUBCOMMAND_NAMES.has(next)) return result;
+  // Splice in --session <name> in place of the positional.
+  result.splice(sessionIdx, 1, '--session', next);
+  return result;
+}
+
+/**
+ * Thrown by the preprocessor when user argv uses a retired/old form that we
+ * intentionally refuse to accept. main.ts catches this and exits with a
+ * usage error so it does not bubble up as an internal stacktrace.
+ */
+export class BrowserSessionArgvError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'BrowserSessionArgvError';
+  }
+}
diff --git a/src/cli.test.ts b/src/cli.test.ts
index 162a8d770..1e7c5f479 100644
--- a/src/cli.test.ts
+++ b/src/cli.test.ts
@@ -378,20 +378,20 @@ describe('createProgram root help descriptions', () => {
       expect(data.command).toBe('opencli browser');
       expect(data.description).toBe('Browser control — navigate, click, type, extract, wait (no LLM needed)');
       expect(data.command_count).toBeGreaterThan(20);
+      // `--session` is now a hidden internal option; user-facing surface is the
+      // <session> positional declared via `.usage()`. Structured help drops
+      // hidden options, so namespace_options shouldn't expose it.
+      expect(data.namespace_options).not.toEqual(expect.arrayContaining([
+        expect.objectContaining({ name: 'session' }),
+      ]));
       expect(data.namespace_options).toEqual(expect.arrayContaining([
-        expect.objectContaining({
-          name: 'session',
-          flags: '--session <name>',
-          takes_value: 'required',
-          required: true,
-          help: expect.stringContaining('required'),
-        }),
         expect.objectContaining({
           name: 'window',
           flags: '--window <mode>',
           takes_value: 'required',
         }),
       ]));
+      expect(data.usage).toBe('opencli browser <session> <command> [options]');
       expect(data.global_options).toEqual(expect.arrayContaining([
         expect.objectContaining({
           name: 'version',
@@ -405,23 +405,26 @@ describe('createProgram root help descriptions', () => {
       ]));
 
       const click = data.commands.find((cmd: any) => cmd.name === 'click');
+      // Structured help command/usage paths include the <session> positional so
+      // agents construct the correct full invocation. `name` is the leaf
+      // identifier (placeholder positionals are stripped).
       expect(click).toMatchObject({
-        command: 'opencli browser click',
-        usage: 'opencli browser click [target] [options]',
+        command: 'opencli browser <session> click',
+        usage: 'opencli browser <session> click [target] [options]',
         positionals: [{ name: 'target' }],
       });
       expect(click.command_options.map((option: any) => option.name)).toEqual(['role', 'name', 'label', 'text', 'testid', 'nth', 'tab']);
 
       const tabList = data.commands.find((cmd: any) => cmd.name === 'tab list');
       expect(tabList).toMatchObject({
-        command: 'opencli browser tab list',
-        usage: 'opencli browser tab list [options]',
+        command: 'opencli browser <session> tab list',
+        usage: 'opencli browser <session> tab list [options]',
         command_options: [],
       });
 
       const getText = data.commands.find((cmd: any) => cmd.name === 'get text');
       expect(getText).toMatchObject({
-        command: 'opencli browser get text',
+        command: 'opencli browser <session> get text',
         positionals: [{ name: 'target' }],
       });
       expect(data.structured_help).toMatchObject({
@@ -447,8 +450,8 @@ describe('createProgram root help descriptions', () => {
       expect(data).toMatchObject({
         namespace: 'browser',
         group: 'tab',
-        command: 'opencli browser tab',
-        usage: 'opencli browser tab <command> [args] [options]',
+        command: 'opencli browser <session> tab',
+        usage: 'opencli browser <session> tab <command> [args] [options]',
         command_count: 4,
       });
       expect(data.commands.map((cmd: any) => cmd.name)).toEqual([
@@ -458,13 +461,15 @@ describe('createProgram root help descriptions', () => {
         'tab select',
       ]);
       expect(data.commands.find((cmd: any) => cmd.name === 'tab close')).toMatchObject({
-        command: 'opencli browser tab close',
-        usage: 'opencli browser tab close [targetId] [options]',
+        command: 'opencli browser <session> tab close',
+        usage: 'opencli browser <session> tab close [targetId] [options]',
         positionals: [{ name: 'targetId', help: 'Target tab/page identity returned by "browser open", "browser tab new", or "browser tab list"' }],
       });
-      expect(data.namespace_options.map((option: any) => option.name)).toEqual(['session', 'window']);
+      // session is now a hidden internal option (consumed from the <session> positional).
+      // namespace_options should only list user-facing options.
+      expect(data.namespace_options.map((option: any) => option.name)).toEqual(['window']);
       expect(data.structured_help).toMatchObject({
-        usage: 'opencli browser tab --help -f yaml',
+        usage: 'opencli browser <session> tab --help -f yaml',
       });
     } finally {
       process.argv = argv;
@@ -485,15 +490,16 @@ describe('createProgram root help descriptions', () => {
       expect(data).toMatchObject({
         namespace: 'browser',
         name: 'click',
-        command: 'opencli browser click',
-        usage: 'opencli browser click [target] [options]',
+        command: 'opencli browser <session> click',
+        usage: 'opencli browser <session> click [target] [options]',
         positionals: [{ name: 'target' }],
         structured_help: {
-          usage: 'opencli browser click --help -f yaml',
+          usage: 'opencli browser <session> click --help -f yaml',
         },
       });
       expect(data.command_options.map((option: any) => option.name)).toEqual(['role', 'name', 'label', 'text', 'testid', 'nth', 'tab']);
-      expect(data.namespace_options.map((option: any) => option.name)).toEqual(['session', 'window']);
+      // session is hidden; only `window` surfaces as a namespace option.
+      expect(data.namespace_options.map((option: any) => option.name)).toEqual(['window']);
       expect(data.global_options.map((option: any) => option.name)).toContain('profile');
     } finally {
       process.argv = argv;
@@ -963,15 +969,14 @@ describe('browser tab targeting commands', () => {
 
   it('requires an explicit session for browser commands', async () => {
     const program = createProgram('', '');
-    program.exitOverride((err) => { throw err; });
-    program.commands.find(cmd => cmd.name() === 'browser')?.exitOverride((err) => { throw err; });
 
-    await expect(program.parseAsync(['node', 'opencli', 'browser', 'state'])).rejects.toMatchObject({
-      code: 'commander.missingMandatoryOptionValue',
-    });
+    // --session is now a hidden internal flag; commander no longer guards it.
+    // The action body throws via getBrowserSession(), surfacing the
+    // <session> positional in the error message.
+    await program.parseAsync(['node', 'opencli', 'browser', 'state']);
 
     expect(mockBrowserConnect).not.toHaveBeenCalled();
-    expect(stderrSpy.mock.calls.flat().join('')).toContain("required option '--session <name>' not specified");
+    expect(stderrSpy.mock.calls.flat().join('')).toContain('<session> is a required positional argument');
   });
 
   it('runs browser commands against an explicit session', async () => {
diff --git a/src/cli.ts b/src/cli.ts
index 7c2c6991a..e93a9235f 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -9,7 +9,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { Command, InvalidArgumentError } from 'commander';
+import { Command, InvalidArgumentError, Option } from 'commander';
 import { styleText } from 'node:util';
 import { findPackageRoot, getBuiltEntryCandidates } from './package-paths.js';
 import { type CliCommand, fullName, getRegistry, strategyLabel } from './registry.js';
@@ -19,7 +19,7 @@ import { PKG_VERSION } from './version.js';
 import { printCompletionScript } from './completion.js';
 import { loadExternalClis, executeExternalCli, installExternalCli, registerExternalCli, isBinaryInstalled } from './external.js';
 import { registerAllCommands } from './commanderAdapter.js';
-import { classifyAdapter, formatRootAdapterHelpText, installCommanderNamespaceStructuredHelp, installStructuredHelp, rootHelpData, type RootAdapterGroups } from './help.js';
+import { classifyAdapter, formatRootAdapterHelpText, installCommanderNamespaceStructuredHelp, installStructuredHelp, leadingPositionalFromUsage, rootHelpData, type RootAdapterGroups } from './help.js';
 import { EXIT_CODES, getErrorMessage, BrowserConnectError } from './errors.js';
 import { TargetError, type TargetErrorCode } from './browser/target-errors.js';
 import { resolveTargetJs, getTextResolvedJs, getValueResolvedJs, getAttributesResolvedJs, selectResolvedJs, isAutocompleteResolvedJs, type ResolveOptions, type TargetMatchLevel } from './browser/target-resolver.js';
@@ -441,9 +441,12 @@ function getCommandOption(command: Command | undefined, option: string): unknown
 }
 
 function getBrowserSession(command?: Command): string {
+  // The CLI surface is `opencli browser <session> <subcommand>`. main.ts rewrites
+  // argv to insert `--session <name>` before commander parses it; this helper
+  // reads back the rewritten flag.
   const raw = getCommandOption(command, 'session');
   if (typeof raw === 'string' && raw.trim()) return raw.trim();
-  throw new Error('--session <name> is required for opencli browser commands');
+  throw new Error('<session> is a required positional argument: opencli browser <session> <command>');
 }
 
 function getBrowserContextId(command?: Command): string | undefined {
@@ -686,9 +689,23 @@ export function createProgram(BUILTIN_CLIS: string, USER_CLIS: string): Command
 
   const browser = program
     .command('browser')
-    .requiredOption('--session <name>', 'Browser session to use (required)')
+    // --session is an internal hidden option used by the daemon protocol and direct
+    // program.parseAsync callers (tests). User-facing surface is the <session>
+    // positional; main.ts argv preprocessor rewrites positional -> --session.
+    .addOption(new Option('--session <name>', 'Internal — set automatically from the <session> positional').hideHelp())
     .option('--window <mode>', 'Browser window mode: foreground or background')
-    .description('Browser control — navigate, click, type, extract, wait (no LLM needed)');
+    .description('Browser control — navigate, click, type, extract, wait (no LLM needed)')
+    .usage('<session> <command> [options]')
+    .addHelpText('after', `
+<session> is a required positional: pass the name of the browser session every subcommand should operate on. Reuse the same name across calls to keep the tab/state alive; pick a different name to isolate parallel browser work.
+
+Examples:
+  $ opencli browser work open https://x.com
+  $ opencli browser work click 12
+  $ opencli browser work state
+  $ opencli browser work bind
+  $ opencli browser work unbind
+`);
   const originalBrowserDescription = browser.description();
 
   /**
@@ -811,8 +828,7 @@ export function createProgram(BUILTIN_CLIS: string, USER_CLIS: string): Command
   }
 
   browser.command('bind')
-    .option('--session <name>', 'Browser session name to bind (required)')
-    .description('Bind the current Chrome tab/window to a browser session')
+    .description('Bind the current Chrome tab/window to the browser session named by <session>')
     .action(async (optsOrCommand, maybeCommand?: Command) => {
       const command = optsOrCommand instanceof Command ? optsOrCommand : maybeCommand;
       const session = getBrowserSession(command);
@@ -841,8 +857,7 @@ export function createProgram(BUILTIN_CLIS: string, USER_CLIS: string): Command
     });
 
   browser.command('unbind')
-    .option('--session <name>', 'Browser session name to detach (required)')
-    .description('Detach a bound browser session without closing the user tab/window')
+    .description('Detach the bound browser session named by <session> without closing the user tab/window')
     .action(async (optsOrCommand, maybeCommand?: Command) => {
       const command = optsOrCommand instanceof Command ? optsOrCommand : maybeCommand;
       const session = getBrowserSession(command);
@@ -3312,6 +3327,28 @@ cli({
   program.configureHelp({
     visibleCommands: (command) => command.commands.filter(child => command !== program || !adapterNameSet.has(child.name())),
   });
+  // When an ancestor command declares a leading positional via `.usage(...)`
+  // (e.g. `browser` -> `<session> <command> [options]`), inject the positional
+  // between that ancestor's name and the next path segment so the help Usage
+  // line is accurate: `Usage: opencli browser <session> click [target] [options]`
+  // instead of `opencli browser click [target] [options]`. Commander does NOT
+  // inherit configureHelp into subcommands, so we walk the descendant tree and
+  // apply the override on each.
+  const ancestorAwareCommandUsage = (cmd: Command): string => {
+    const ancestors: string[] = [];
+    let ancestor: Command | null = cmd.parent;
+    while (ancestor) {
+      const positional = leadingPositionalFromUsage(ancestor);
+      ancestors.unshift(positional ? `${ancestor.name()} ${positional}` : ancestor.name());
+      ancestor = ancestor.parent;
+    }
+    return [...ancestors, cmd.name(), cmd.usage()].filter(Boolean).join(' ').trim();
+  };
+  function applyAncestorAwareUsage(cmd: Command): void {
+    cmd.configureHelp({ commandUsage: ancestorAwareCommandUsage });
+    for (const sub of cmd.commands) applyAncestorAwareUsage(sub);
+  }
+  applyAncestorAwareUsage(browser);
   installStructuredHelp(program, () => rootHelpData(program, adapterGroups), () => formatRootAdapterHelpText(adapterGroups));
 
   // ── Unknown command fallback ──────────────────────────────────────────────
diff --git a/src/help.ts b/src/help.ts
index 2f8cf6930..418a82263 100644
--- a/src/help.ts
+++ b/src/help.ts
@@ -231,12 +231,42 @@ function compactCommanderOptions(options: readonly CommanderOption[]): OptionSpe
     .filter((option): option is OptionSpec => option !== null);
 }
 
+/**
+ * Extracts a positional placeholder that should appear immediately after this
+ * command's name in user-facing path strings. Reads the leading positional
+ * (e.g. `<session>`) from a `.usage()` override; commands without a positional
+ * override return `null` so the path stays as-is.
+ *
+ * Example: `browser` declares `.usage('<session> <command> [options]')`,
+ * so `commanderPath(browserClickCmd)` becomes
+ * `['opencli', 'browser', '<session>', 'click']`.
+ */
+export function leadingPositionalFromUsage(command: Command): string | null {
+  const usage = (command as Command & { _usage?: string })._usage;
+  if (!usage) return null;
+  const match = usage.match(/^\s*(<[^>]+>)/);
+  return match ? match[1] : null;
+}
+
 function commanderPath(command: Command): string[] {
   const parts: string[] = [];
   let current: Command | null = command;
   while (current) {
     const name = current.name();
-    if (name) parts.push(name);
+    if (name) {
+      parts.push(name);
+      // If this command declares a leading-positional usage override AND we
+      // have already collected a child name below it, the positional must
+      // appear between this command and the child (i.e. before the names
+      // already collected). parts is in reverse order, so push to the end.
+      const positional = leadingPositionalFromUsage(current);
+      if (positional && parts.length > 1) {
+        // We collected child names first (reverse order). Move them up by one
+        // and put the positional at index `parts.length - 2` so reverse()
+        // places it between this command and the first child name.
+        parts.splice(parts.length - 1, 0, positional);
+      }
+    }
     current = current.parent;
   }
   return parts.reverse();
@@ -245,7 +275,10 @@ function commanderPath(command: Command): string[] {
 function commandPathFromRoot(namespaceRoot: Command, command: Command): string[] {
   const rootPath = commanderPath(namespaceRoot);
   const commandPath = commanderPath(command);
-  return commandPath.slice(rootPath.length);
+  // Strip placeholder positional segments (e.g. `<session>`) from the relative
+  // name so agents can still address subcommands by their leaf name. Display
+  // paths in `command` / `usage` still include the placeholders.
+  return commandPath.slice(rootPath.length).filter(part => !/^<.+>$/.test(part));
 }
 
 function collectLeafCommands(command: Command): Command[] {
@@ -303,10 +336,19 @@ export function commanderNamespaceHelpData(
   const leaves = collectLeafCommands(namespaceRoot)
     .filter(command => command !== namespaceRoot)
     .sort((a, b) => commandPathFromRoot(namespaceRoot, a).join(' ').localeCompare(commandPathFromRoot(namespaceRoot, b).join(' ')));
+  // Respect commander's `.usage()` override (e.g. `<session> <command> [options]`
+  // on `browser`); fall back to the generic `<command> [args] [options]` form.
+  // Read the private `_usage` field directly because `.usage()` returns the
+  // auto-generated form if no override was set.
+  const commandPath = commanderPath(namespaceRoot).join(' ');
+  const usageOverride = (namespaceRoot as Command & { _usage?: string })._usage;
+  const usage = usageOverride
+    ? `${commandPath} ${usageOverride}`
+    : `${commandPath} <command> [args] [options]`;
   return {
     namespace: namespaceRoot.name(),
-    command: commanderPath(namespaceRoot).join(' '),
-    usage: `${commanderPath(namespaceRoot).join(' ')} <command> [args] [options]`,
+    command: commandPath,
+    usage,
     description: opts.description ?? namespaceRoot.description(),
     command_count: leaves.length,
     commands: leaves.map(command => compactCommanderCommand(namespaceRoot, command, opts)),
@@ -314,7 +356,7 @@ export function commanderNamespaceHelpData(
     ...(opts.globalCommand ? { global_options: compactCommanderOptions(opts.globalCommand.options) } : {}),
     structured_help: {
       formats: ['yaml', 'json'],
-      usage: `${commanderPath(namespaceRoot).join(' ')} --help -f yaml`,
+      usage: `${commandPath} --help -f yaml`,
     },
   };
 }
diff --git a/src/main.ts b/src/main.ts
index 10c385801..a823262af 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -145,5 +145,21 @@ if (getCompIdx !== -1) {
   process.exit(EXIT_CODES.SUCCESS);
 }
 
+// Rewrite `opencli browser <session> <subcommand> ...` so commander (which
+// can't combine a parent positional with subcommand dispatch) sees the internal
+// `--session <name>` flag form. Also refuses the retired `opencli browser
+// --session foo ...` user form with a friendly usage error.
+const { rewriteBrowserArgv, BrowserSessionArgvError } = await import('./cli-argv-preprocess.js');
+try {
+  const rewritten = rewriteBrowserArgv(process.argv.slice(2));
+  process.argv.splice(2, process.argv.length - 2, ...rewritten);
+} catch (err) {
+  if (err instanceof BrowserSessionArgvError) {
+    process.stderr.write(`error: ${err.message}\n`);
+    process.exit(EXIT_CODES.GENERIC_ERROR);
+  }
+  throw err;
+}
+
 await emitHook('onStartup', { command: '__startup__', args: {} });
 runCli(BUILTIN_CLIS, USER_CLIS);
diff --git a/tests/e2e/browser-tabs.test.ts b/tests/e2e/browser-tabs.test.ts
index f4f135ac8..9b69c829e 100644
--- a/tests/e2e/browser-tabs.test.ts
+++ b/tests/e2e/browser-tabs.test.ts
@@ -207,7 +207,7 @@ async function startFakeDaemon(): Promise<FakeDaemon> {
 describe('browser tab CLI e2e', () => {
   const daemons: FakeDaemon[] = [];
   const cacheDirs: string[] = [];
-  const browserArgs = (session: string, ...args: string[]) => ['browser', '--session', session, ...args];
+  const browserArgs = (session: string, ...args: string[]) => ['browser', session, ...args];
 
   afterEach(async () => {
     while (daemons.length > 0) {