docs(browser-debug): pane-first recipes for dialog/iframe/shadow

Align the shared workflow skill with Octopus pane agents: prefer the
user-visible pane, pre-arm dialogs, use f{seq}/e{n} frame refs, and
dual-leg highlight/locator tools.

core/skills/browser-debug/SKILL.md

@@ -100,6 +100,25 @@ not by familiarity:
 | Keyboard navigation | `browser_press_key` | For tab order, focus rings, escape-to-close. |
 | Record a video / trace | `browser_start_tracing`, `browser_stop_tracing` | Heavy; use only when a bug is timing-sensitive and console+snapshot can't catch it. |
 
+## Pane-first recipe (prefer over headless)
+
+Default to the **user-visible browser pane** unless the task explicitly needs
+an isolated headless Chromium (`surface: "headless"`). Pane agents now match
+or exceed Playwright for the hard cases:
+
+| Need | Pane tool / pattern | Notes |
+| --- | --- | --- |
+| Open / bind pane | `browser_open` (default surface) | Never touch the user's pane from a headless-only intent — pass `surface: "headless"` or `browser_pane_release` first. |
+| Structure + refs | `browser_snapshot` | Open shadow is pierced; cross-origin iframes expose `f{seq}/e{n}` synthetic refs — prefer those over attr ids when acting into child frames. |
+| Act (click/type/…) | `browser_act` / `browser_act_batch` | Locators (`role=` / `text=` / …) walk open shadow. Cross-origin click/type route through CDP trusted events. |
+| Native dialogs | `browser_handle_dialog` **before** the act | Prefer `mode: "arm"` (or `act_batch.dialog_prearm`) so the pane parks the answer before the click that opens confirm/prompt — avoids the 1.5s auto-dismiss / widget-cancel race. Bind with `messageIncludes` when the page can raise multiple dialogs. Call `mode: "disarm"` if the trigger was cancelled. |
+| Highlight / locator | `browser_highlight`, `browser_generate_locator` | Dual-leg: both pane and headless. Use highlight to confirm the ref before a write. |
+| Failure recovery | re-snapshot + path candidates | Act/locator failures may return `pathCandidates` (frame/shadow path hints). Heal scores framePath so sibling iframes do not auto-heal across frames. |
+
+Headless remains the right tool for parallel CI-style isolation and when the
+user must not see the session. For interactive debug of `packages/app`, stay
+on the pane.
+
 ## Standard recipe — reproduce a UI bug
 
 Follow these steps in order. Do not skip the snapshot step: the `ref` it