@bastani/atomic 0.9.28-alpha.2 → 0.9.28-alpha.4

package/dist/builtin/subagents/skills/cua-driver/LINUX.md

@@ -1,12 +1,10 @@
-# cua-driver — Linux
+# cua-driver: Linux
 
-The Linux backend drives X11 apps **in the background**: clicks and
-keystrokes are injected to the target window without raising it,
-activating it, or moving the real pointer — the same no-foreground
-contract the macOS and Windows backends hold. The full tool surface is
-supported: `click`, `type_text`, scroll, `press_key`, `screenshot`,
-`launch_app`, `list_apps`, `list_windows`, `get_window_state`, and
-session recording.
+Start with `cua-driver doctor` in the graphical user's session. X11,
+XWayland, and native Wayland expose different capture and input facilities;
+successful discovery does not prove either input delivery or window capture.
+Use [WORKFLOW.md](WORKFLOW.md) for exact targets and verification and
+[RUNTIME.md](RUNTIME.md) for transport and permission ownership.
 
 On X11, `set_window_frame({pid, window_id, x, y, width, height})` sends an
 EWMH window-manager request and confirms it against `list_windows` geometry.
@@ -14,137 +12,166 @@ Wayland has no portable protocol for setting another application's top-level
 geometry, so this tool refuses there unless a future compositor-owned adapter
 can provide exact targeting and readback.
 
-AT-SPI is talked to natively over D-Bus (the `atspi`/zbus crate) — no
+AT-SPI is talked to natively over D-Bus (the `atspi`/zbus crate): no
 `pyatspi` or GObject-introspection typelibs are required at runtime.
 
-## How input is delivered (the no-foreground contract)
-
-- **Pixel click** — `XSendEvent(ButtonPress/Release)` to the resolved
-  target window. No raise, no activate, no real-pointer warp. (It does
-  **not** use `XTestFakeButtonEvent`, which would route through the
-  focused window.)
-- **Element click** (`element_token`, or `element_index` + `snapshot_id`) — AT-SPI `do_action` on the
-  accessible. Toolkit-native, focus-free.
-- **type_text** — AT-SPI EditableText first (focus-free; lands in an
-  *unfocused* window's editable for Qt6 / GTK4). When a **non-editable**
-  widget holds focus — a spreadsheet cell, a terminal, a canvas — it
-  synth-types into the focused widget via XTest, and terminals take a
-  focus-free pty-injection path. So background typing into an editable
-  needs no focus; the XTest path is the foreground "type where I
-  clicked" case.
-- The **agent cursor** is a synthetic overlay showing where the run is
-  acting; it never moves the real pointer (same model as macOS/Windows).
-  It glides on clicks and ordinary `move_cursor` calls; cursor-bearing and
-  keyboard actions re-show it automatically. Only the explicit
-  `move_cursor({x,y,scope:"desktop"})` escape hatch moves the compositor
-  cursor. Do not use desktop scope unless the user asked for real-pointer
-  control.
-
-## `delivery_mode` — the background/foreground ladder
-
-Every input tool (`click`, `type_text`, `press_key`, `hotkey`,
-`double_click`, `right_click`, `scroll`) takes an optional **`delivery_mode`**
-— the per-call rung of the best-effort-background ladder, matching the macOS
-and Windows surface:
-
-- **`background`** (default) — inject **without activating or raising** the
-  target. X11: the no-focus-steal paths above (AT-SPI / `XSendEvent` /
-  XInput2 MPX pointer). This is cua-driver's differentiator and the right
-  default.
-- **`foreground`** — **activate the target first** (X11 EWMH
-  `_NET_ACTIVE_WINDOW`, proper timestamp handling to beat the WM's
-  focus-stealing prevention), inject, then **restore the prior active
-  window**. The explicit escalation when a background inject didn't land —
-  e.g. a GTK dialog button or a widget that only reads input while focused.
-  A brief focus swap unless the target was already active.
-
-Foreground is a user-visible takeover boundary. Never select it automatically.
-Use it only when the user already authorized foreground control for the
-workflow or after asking for approval. If background delivery refuses and that
-authorization is absent, return the refusal instead of changing the user's
-focus, workspace, or compositor cursor.
-
-### Persistent focus-proxy exception
-
-`bring_to_front` is not part of the normal input ladder. After an ordinary
-`background_unavailable` response, and only with foreground authorization,
-retry the refused action with `delivery_mode:"foreground"`; cua-driver activates the target, performs the
-action, and restores the prior active window. Use `bring_to_front` only when a
-focus-proxy surface must remain foreground across multiple calls, such as a
-remote desktop session, or when repeated action-scoped activation prevents the
-remote surface from accepting input. On X11 it uses persistent
-`_NET_ACTIVE_WINDOW` activation (the `wmctrl -a` equivalent).
-
-**Read-back / action effect** — AT-SPI `EditableText.insertText` can return
-`effect:"confirmed"` with `evidence:[{"kind":"value_readback"}]` when the
-accessibility layer reads the inserted value back from the widget model.
-Keystroke / XSendEvent / XTest / foreground rungs return
-`effect:"unverifiable"` unless another publishable readback exists. Confirm
-those through `verify_state` or multimodal reading.
-
-**Escalation** — action responses use the cross-platform closed
-`escalation:{target, reason}` shape. See `SKILL.md` → behavior matrix. On a
-standard Wayland compositor the Linux-specific target is **`foreground`**
-(raw background pixels cannot target an unfocused window without a dedicated
-adapter); the opt-in nested compositor and Hyprland input v3 candidate below
-have separate limits. Use **`pixel` on X11** (an element px
-action — background pixel click — lands via
-AT-SPI `do_action`-at-point off the screenshot already in the snapshot — the
-matrix below).
-
-## Perception and the ax/px action choice
-
-`get_window_state` is **perception-mode-agnostic** — by default it returns
-**both** the AT-SPI tree **and** a screenshot in one call. You ground on both
-and cross-check; the tree **lies** on some surfaces (Electron echo-confirms
-`setValue`, virtualized/off-viewport rows report bogus `h:1` frames), so a
-grounding screenshot is always present by default. There is no capture mode to
-pick.
-
-**Perf opt-out — `include_screenshot`** (boolean, default `true`). Pass
-`include_screenshot:false` to skip the screen grab and return tree-only — the
-cheap path when you're re-indexing before an **element ax action** and don't
-need fresh pixels. It's a **perf** knob, not a modality choice.
-
-**`capture_mode` is DEPRECATED and IGNORED.** It's still *accepted* so old
-callers don't error, but it has **no effect** — both the tree and the
-screenshot come back regardless of what you pass (`ax`/`vision`/`som`). There
-is no `ax`/`vision`/`som` capture choice anymore; drop that vocabulary.
-
-Modality is chosen at **action time**, by how you address the target:
-
-- **element ax action** — `element_token` (preferred), or the matching
-  `element_index` + `snapshot_id` pair → AT-SPI
-  `do_action`. Backgroundable, driver-verifiable.
-- **element px action** — `x,y` → pixel rung, read straight off the screenshot
-  already in the `get_window_state` response. Best-effort; caller-confirmed.
-
-`get_window_state` returning `degraded:true` (empty AT-SPI walk) is the cue to
-do an **element px action** off that same screenshot (X11) or escalate to
-`delivery_mode:"foreground"` when authorized (standard Wayland has no general
-raw background route). The nested compositor and Hyprland input v3 candidate
-have their own experimental per-surface routes; an empty tree does not establish
-eligibility for either route.
-
-## Cross-platform schema residuals (Linux)
-
-The capture/dispatch/addressing params are a shared cross-platform
-contract (see `SKILL.md` → *Cross-platform parameter contract*) — the
-same `session`, `delivery_mode`, `capture_mode`, `scope`, `modifier`,
-`element_index`/`snapshot_id`/`element_token` *shapes* as macOS and Windows, gated in
-CI so the three surfaces can't drift. Linux-relevant notes:
-
-- **`session` is now accepted on every action/cursor tool.** Earlier
-  Linux builds rejected it via `additionalProperties:false` (it was
-  effectively macOS-only); it is now uniformly schema-accepted — Linux
-  glides a per-session cursor on X11 where the overlay is available.
-- **Windowless screen-absolute actions** use
-  `target:{"kind":"desktop","display_id":"primary"}`, uniformly with macOS
-  and Windows. Exact window actions use
-  `target:{"kind":"window","pid":PID,"window_id":WINDOW_ID}`. Legacy flat
-  `scope`, `pid`, and `window_id` fields remain compatibility inputs, but do
-  not combine them with `target`; capture modality no longer changes lifecycle
-  session state.
+## Delivery
+
+Background window input must not activate or raise the target. AT-SPI actions
+can reach semantic controls without raw pointer delivery; X11 pixel dispatch
+can use AT-SPI hit-testing or a virtual-pointer route. Do not assume all input
+uses XSendEvent or that every toolkit accepts it. Inspect the result's public
+route and independently verify the application.
+
+`delivery_mode:"foreground"` is a user-visible takeover. Never select it automatically.
+Use explicitly authorized `delivery_mode:"foreground"` only after evidence
+that the chosen background route is unavailable or ineffective. Target-specific
+activation and restoration depend on the compositor adapter. If activation
+cannot be proven, accept the refusal instead of sending keys to whatever is focused.
+
+The overlay is separate from the physical pointer; cursor-bearing and
+keyboard actions re-show it automatically. Distinct overlays do not isolate
+desktop input. Keep one controller for a global-input workflow.
+
+## Capture recovery
+
+`get_window_state` requests both AT-SPI and a window screenshot by default.
+A valid image is not guaranteed. If `screenshot_error.code` is
+`surface_identity_unproven`, the driver cannot attest that output pixels
+belong to the requested surface. Preserve that distinction from an empty or
+untrusted accessibility tree. Never crop a desktop image and label it an
+attested window capture.
+
+1. Read any returned tree and `degraded_reason`; semantic interaction may still
+   be possible without pixels.
+2. Do not retry a window-pixel action without a valid window image. Changing
+   `capture_mode`, inventing bounds, or repeatedly increasing timeouts cannot
+   establish surface identity.
+3. If the task permits full-display capture and visible desktop control,
+   explain the broader scope and obtain authorization if not already given.
+   Use `get_desktop_state`, then
+   `target:{"kind":"desktop","display_id":"primary"}` on input, and verify
+   through another desktop snapshot. See [the desktop loop](WORKFLOW.md#desktop-loop).
+4. If desktop scope is not admitted, report the limitation and stop that route.
+
+A capture request may be waiting for an OS/portal permission dialog. Inspect
+window discovery for a pending prompt, or ask the user to check the desktop.
+Let the user approve or deny it. Do not repeatedly start captures, automate
+approval, or change security settings as a workaround. After approval, take a
+fresh capture and verify its dimensions/content before continuing. A timeout
+alone does not prove which permission or backend failed.
+
+Supporting smoke evidence: Driver 0.23.2 on KDE/KWin Wayland opened an Electron
+music app, searched, selected an album track, and showed playback through this
+desktop route after user screenshot approval. The window route returned
+`surface_identity_unproven`; desktop actions returned `global_input` and
+`unverifiable`, so screenshots and user confirmation established the result.
+This is not certification of background targeting, other compositors, or video.
+
+## X11 observation and input details
+
+**What is open over the window.** `get_window_state` lists the pid's transient
+dialogs (`dialogs: [{window_id, title, transient_for, modal, bounds}]`) and
+override-redirect popups (`popups: [...]`) that are mapped, with a `follow_up`
+sentence naming the call that targets each one
+(`get_window_state(pid, window_id=<that id>)`). When one overlaps the window
+the screenshot is taken from the screen (`screenshot_composited:true`) so the
+menu or dialog is visible; the window's own drawable never shows them. The
+payload states its frame (`coordinate_frame:"window"`, `frame_note`): `x`/`y`
+of the pointer tools are pixels of THIS screenshot. Closed menus are listed
+with a `description` ("closed menu with N items…") and are not walked;
+click the menu (a real press) and read the popup by its window_id.
+`press_key` / `hotkey` that map a new top-level report it as `window_opened`
+with `window_change` evidence. Action results carry the same text as
+`summary` inside `structuredContent`, for clients that only show that.
+
+**Screenshot scale.** The window screenshot is delivered at or below 1.15
+megapixels (long edge ≤ `max_image_dimension`, 1568 by default): larger
+images are downsized before a model reads them, and its pixel coordinates
+would then be uniformly short. Pointer `x`/`y` and each element's
+`screenshot_frame` are pixels of the delivered image (the element's `frame`
+stays in screen coordinates, as on every platform); `frame_scale` < 1 and
+`screenshot_original_width` report the downsizing, and the driver scales your
+pixels back to the window.
+An explicit per-call `max_image_dimension` (0 = native) replaces this cap.
+
+**Budget the pixels before you aim.** The cap is a pixel budget, so on a
+high-resolution window the delivered image is a small fraction of native and
+fine controls stop being readable. Measured on a 3840x2342 window: `frame_scale`
+0.357, so a 24px toolbar icon arrives at ~8.6px and a 1px border at ~0.36px:
+sub-pixel for any reader, sighted or not. Check `frame_scale` in the
+`get_window_state` payload and, when a target is smaller than roughly 30px, frame
+it with `zoom` before choosing a coordinate. Zooming a 196x728 window-px region
+returned a 235x873 image (about 1.2x native), which restores a 24px icon to
+~29px. `zoom` takes screenshot pixels and the follow-up action needs
+`from_zoom: true`. It also requires a screenshot-owning snapshot from the same
+session first, and refuses with `screenshot_context_missing` otherwise, so
+`get_window_state` with a screenshot must precede the first `zoom`.
+
+**When the active model takes no images.** Some clients drop image content
+entirely, so `get_window_state` and `zoom` return an image the reader never sees.
+The loop still closes for most questions, and none of this needs a vision model:
+`verify_state` proves state and returns a real `satisfied` / `unsatisfied` /
+`unknown` verdict; an out-of-band read such as
+`xprop -root _NET_ACTIVE_WINDOW` proves which window holds focus; and scanning the
+written capture for colour transitions (PIL or equivalent) proves coarse layout.
+What none of them prove is that a specific small control was activated. For that
+use the `cua-perception` extension (see `VISUAL.md`) or an app that exposes a
+usable accessibility tree.
+
+**Windows without `_NET_WM_PID`.** Tk, many Java/AWT builds, Wine, and legacy
+Xlib/Xt clients do not publish `_NET_WM_PID`. On X11, `list_windows` then asks
+the X server's X-Resource extension (XRes 1.2 `LocalClientPID`) which local
+process created the window, so these windows still carry a `pid` and accept
+`get_window_state` / `click` by `pid` + `window_id`. The driver never guesses:
+`pid` stays `null` when XRes is missing or older than 1.2, when the client
+is remote (TCP, or SSH-forwarded with a `WM_CLIENT_MACHINE` naming another
+host), or when the X server cannot report the driver's own PID correctly
+(remote `DISPLAY`, container PID namespace). A `pid: null` window can only be
+reached through desktop scope. An SSH-forwarded client that publishes
+neither `_NET_WM_PID` nor `WM_CLIENT_MACHINE` is attributed to the local
+`ssh` process, because that is the socket peer the server sees.
+
+**Keys while the app's own popup is open.** A Qt combo list / completer or a
+GTK/VCL menu holds a keyboard grab that makes the X server drop keys from the
+virtual keyboard. `press_key` / `hotkey` / `type_text` / `set_value` then go
+through the core keyboard (`path: "xtest_core_grab"`, the result names the
+popup and states that the core focus and active window were verified
+unchanged), or, when another application holds the core focus, are refused
+with `code: "popup_keyboard_grab"` and a hint: dismiss the popup (click
+outside it, or click one of its rows by element_token after
+`get_window_state(pid, window_id=<popup>)`) and retry. Typing an absolute path
+into a Qt file dialog opens its completer after the first `/`; prefer
+`set_value` on the "File name" field, which writes the path in one go.
+
+**Popup walks, labels, descriptions.** `get_window_state(pid, window_id=<popup>)`
+returns the popup's own rows (list / tree / menu items), never the main
+window's menubar. Elements carry `description` when the toolkit publishes one
+(Qt keeps a button's tooltip there: `push button "" (description "Pause")`;
+`label` falls back to it). A control's `label` is never its value: a spin
+button or slider nobody names is `unlabelled: true` with its place in
+`description` (`unlabelled spin button; 3rd of 4 spin buttons in this panel`,
+in visual order). `parent_index` is the nearest indexed real ancestor.
+
+**Grid presses.** After a click that lands on a table cell (LibreOffice Calc),
+the result appends `focus: cell D2` (`focused_cell`, evidence) read from the
+focus log, so a one-row miss is visible before you type.
+
+**Multi-click.** `click` takes `count: 2` (double) or `count: 3` (triple, a
+line/paragraph selection in editors) as one press train with real double-click
+cadence in both delivery modes; there is no `triple_click` tool.
+
+**Typing throughput.** Key-event typing (XTest in foreground, the virtual
+keyboard in background) runs at roughly 45-60 characters per second, so a
+1,300-character script takes about 30 s: scale a client-side `type_text`
+deadline with the text length instead of using a flat one (0.04 s per
+character leaves margin over those rates). A terminal can still be echoing when the call returns; read the
+result again before retyping text that looks truncated.
+
+**Cross-application drops.** A pointer action whose point lies over another
+application's window (a drag dropped onto VLC) reports that window's title
+change and the windows its pid opened as `foreign_window` / `window_change`
+evidence; the focus guard alone only watches the target pid.
 
 ## Native application menus
 
@@ -158,13 +185,13 @@ native `do_action` acknowledgement alone is not task completion.
 
 ## AT-SPI needs the session bus (headless / containers / `runuser`)
 
-AT-SPI — the accessibility tree behind `get_window_state`, element-indexed
-clicks, and focus-free `type_text` — lives **entirely on the desktop
+AT-SPI (the accessibility tree behind `get_window_state`, `element_token`
+clicks, and focus-free `type_text`) lives **entirely on the desktop
 session's D-Bus**. cua-driver reaches it via `DBUS_SESSION_BUS_ADDRESS`. When
-the daemon is started *inside* a normal desktop login that variable is already
-exported and everything works. When it is started **outside** the session —
-a container entrypoint, a headless box, `runuser`/`su` into the desktop user,
-a systemd *system* unit, or a VNC session running its own ad-hoc bus — the
+the daemon is started _inside_ a normal desktop login that variable is already
+exported and everything works. When it is started **outside** the session
+(a container entrypoint, a headless box, `runuser`/`su` into the desktop user,
+a systemd _system_ unit, or a VNC session running its own ad-hoc bus), the
 variable is unset, the AT-SPI registry walk comes back empty, and
 `get_window_state` reports **every** window as having no elements.
 
@@ -175,10 +202,10 @@ process's `/proc/<pid>/environ` (`xfce4-session`, `gnome-session`, …). So the
 common headless cases now "just work". The two things that still must be true:
 
 1. **An accessibility bus must be running** in that session, and
-   **`toolkit-accessibility` must be on** — cua-driver advertises a screen
+   **`toolkit-accessibility` must be on**: cua-driver advertises a screen
    reader at startup to flip it, but a session with no a11y bus at all
    (`/usr/libexec/at-spi-bus-launcher`) can't expose a tree. `cua-driver
-   doctor` now probes `org.a11y.Bus` for real (not just "is there a bus?")
+doctor` now probes `org.a11y.Bus` for real (not just "is there a bus?")
    and tells you which of the two is missing.
 2. The daemon must run **as the desktop user** (so it can read that user's
    session-process environ and the `/run/user/<uid>/bus` socket). Running the
@@ -194,20 +221,26 @@ bridge isn't up / the daemon isn't on the session bus".
 
 Each input rung and its stable public route:
 
-| Modality | `delivery_mode` | `route` | Postcondition proof |
-|---|---|---|---|
-| Element click (`element_index`) | `background` | `accessibility` | Use `verify_state`; invocation alone is not confirmation |
-| **element px action (x,y)** | `background` | `accessibility` when AT-SPI-at-point lands, otherwise `global_input` | Use `verify_state` or multimodal reading |
-| Pixel (px) click, escalated | `foreground` | `global_input` | Use `verify_state` or multimodal reading |
-| `type_text` into editable | `background` | `accessibility` | `confirmed` only with `value_readback` evidence |
-| `type_text`, non-editable focus | `background`/`foreground` | `synthetic_events` or `global_input` | Use `verify_state` or multimodal reading |
+| Modality                        | `delivery_mode`           | `route`                                                              | Postcondition proof                                      |
+| ------------------------------- | ------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------- |
+| Element click (`element_token`) | `background`              | `accessibility`                                                      | Use `verify_state`; invocation alone is not confirmation |
+| **element px action (x,y)**     | `background`              | `accessibility` when AT-SPI-at-point lands, otherwise `global_input` | Use `verify_state` or multimodal reading                 |
+| Pixel (px) click, escalated     | `foreground`              | `global_input`                                                       | Use `verify_state` or multimodal reading                 |
+| `type_text` into editable       | `background`              | `accessibility`                                                      | `confirmed` only with `value_readback` evidence          |
+| `type_text`, non-editable focus | `background`/`foreground` | `synthetic_events` or `global_input`                                 | Use `verify_state` or multimodal reading                 |
 
-**A background element px action does land on X11** — for an AX-exposing app it
+**A background element px action does land on X11**: for an AX-exposing app it
 takes the focus-free AT-SPI `do_action`-at-point path (`x11_atspi`), exactly
 like the macOS/Windows background pixel click. It falls to the MPX
 virtual-pointer path (`x11_pixel`) only for non-AX surfaces, **and that path
-needs a real Xorg + `/dev/uinput`** — under Xvnc / minimal containers without
-uinput, escalate to `delivery_mode:"foreground"`. (`type_text` in the
+needs a real Xorg + `/dev/uinput`**: under Xvnc / minimal containers without
+uinput, escalate to `delivery_mode:"foreground"`. The AT-SPI path only fires
+a control under the point: when the hit test finds nothing deeper than the
+application's own frame or window (Chromium page content before its AT-SPI
+tree is populated), no action is fired. Chromium/Electron targets without a
+real focus-free pointer return `background_unavailable` before the capture is
+consumed, so retry the same capture-bound click with
+`delivery_mode:"foreground"` when foreground input is authorized. (`type_text` in the
 `background` rung is focus-dependent for non-editable widgets; that's the one
 genuine background limitation, and `foreground` is the documented escalation.)
 
@@ -277,12 +310,14 @@ identity refuses. Package eligibility does not certify every LibreOffice
 application or operation.
 
 The plugin separately binds the exact live native surface and checks geometry,
-desktop availability, primary-client and other-lane conflicts, and the compiled
-default `evdev`/`pc105`/`us` keymap. The candidate excludes variants, options,
-remaps, multiple layout groups, missing keyboards, Unicode, IME input,
-arbitrary held-key streams, and modified pointer gestures. Chromium, Electron,
-and XWayland raw background input are outside this scope. AT-SPI routes retain
-their separate behavior.
+desktop availability, and primary-client and other-lane conflicts. Each
+background lane publishes a private canonical `evdev`/`pc105`/`us` keymap, so
+user options such as Caps Lock remapped to Ctrl or Super do not alter agent key
+semantics. A physical keymap transition cancels existing authority; use a fresh
+action afterward. Multiple agent layout groups, Unicode, IME input, arbitrary
+held-key streams, and modified pointer gestures remain outside this scope.
+Chromium, Electron, and XWayland raw background input are outside this scope.
+AT-SPI routes retain their separate behavior.
 
 Two compositor seats, `Cua-Agent` and `Cua-Agent-2`, persist across configuration
 disable/re-enable. Each connection claims one lane, and each admitted action
@@ -302,7 +337,15 @@ native harness covers defined GTK3, Electron, and Tauri foreground cases. It ref
 held physical input, grabs, constraints, drag-and-drop, ambiguous primary seat
 bindings, and non-neutral keyboard modifiers. Background refusal never selects
 this route automatically. Driver expands bounded ASCII text under the exact
-US keymap; Unicode and IME remain outside its raw-input scope.
+US keymap; Unicode and IME remain outside its raw-input scope. Foreground
+pointer-only actions are layout-independent. Foreground keyboard actions leave
+the user's Num Lock and Caps Lock untouched. They work with Num Lock on and with
+keymap options that leave every typing and modifier key unchanged, such as
+`compose:caps`. They refuse before any input under Caps Lock
+(`foreground_keyboard_caps_lock`), for a keypad key that Num Lock changes
+(`foreground_keyboard_numlock_keypad`), and for a different layout or remapped
+key (`foreground_unsupported_layout`). Ask the user to turn Caps Lock off, or
+use the equivalent non-keypad key, instead of retrying the same call.
 
 The retained bounded app evidence at source
 `f180e8828b8f31cc153e3c44eaa89a9c13c5bc68` includes instrumented Calc/Inkscape
@@ -320,45 +363,44 @@ Fleet image.
 
 If a tool call surprises you on Linux:
 
-1. `cua-driver doctor` — reports the display server (X11 / Wayland),
+1. `cua-driver doctor`: reports the display server (X11 / Wayland),
    **whether `org.a11y.Bus` actually answers on the session bus** (not just
    "is there a bus"), the discovered `DBUS_SESSION_BUS_ADDRESS`, and
    `ffmpeg` availability (for recording).
-2. Check `XDG_SESSION_TYPE` — `x11` is fully supported; `wayland`
+2. Check `XDG_SESSION_TYPE`: X11 still has toolkit-specific delivery limits; `wayland`
    needs `CUA_DRIVER_RS_ENABLE_WAYLAND=1` for the native backend,
    else XWayland.
-3. **Empty AT-SPI tree** (`get_window_state` returns `degraded:true`) — in
+3. **Empty AT-SPI tree** (`get_window_state` returns `degraded:true`): in
    order of likelihood: (a) the daemon isn't on the desktop session bus
-   (headless / container / `runuser` / root-against-user-session — see
-   *AT-SPI needs the session bus* above; doctor will say
+   (headless / container / `runuser` / root-against-user-session; see
+   _AT-SPI needs the session bus_ above; doctor will say
    `DBUS_SESSION_BUS_ADDRESS unset`); (b) the a11y bridge is off
    (`gsettings set org.gnome.desktop.interface toolkit-accessibility true`);
-   (c) GTK4 / Qt6 / Chromium populate lazily — re-snapshot after an
+   (c) GTK4 / Qt6 / Chromium populate lazily: re-snapshot after an
    interaction or an AX-enable settle.
 
 ## Forbidden vectors
 
-Same idea as macOS / Windows — don't shell out to anything that
+Same idea as macOS / Windows: don't shell out to anything that
 foregrounds a target:
 
-- `wmctrl -a <window>` / `wmctrl -R <window>` — activates / raises.
-- `xdotool windowactivate <wid>` — activates.
-- `xdotool key --window <wid> alt+Tab` — focus churn.
+- `wmctrl -a <window>` / `wmctrl -R <window>`: activates / raises.
+- `xdotool windowactivate <wid>`: activates.
+- `xdotool key --window <wid> alt+Tab`: focus churn.
 
 Prefer cua-driver tools with an explicit `window_id`. When in doubt,
 ask the user.
 
 ## What to expect
 
-| Environment | Proven baseline | Main limits |
-|---|---|---|
-| X11/Openbox | AT-SPI trees and actions, foreground pointer and keyboard input, window and desktop capture, and video | Raw background delivery remains toolkit-specific; unsupported shapes refuse |
-| Sway/wlroots | AT-SPI, native discovery, full-display and cropped-window screencopy, foreground input, semantic background actions, and video | Raw background pointer and keyboard input remains focus-bound |
-| Hyprland/Omarchy | Experimental source candidate with separate discovery-foundation and bounded two-seat app evidence | Default plugin is discovery-only; raw background v3 qualification is limited to the exact native Calc/Inkscape packages and plain US keymap; complete native harness and release acceptance are separate gates |
-| GNOME/Mutter | AT-SPI, WinRects geometry and activation, capture, and portal/libei foreground input | Requires the helper and portal grant; portal video parity remains open |
-| KDE/KWin | AT-SPI and generic discovery where exposed | Target-specific activation and behavioral coverage remain experimental |
-| Nested `cua-compositor` | Versioned direct per-surface input, native GTK 31/31, capture/scope 5/5, and partial Electron coverage | The complete shared matrix remains experimental; do not infer standard-Wayland support |
-
-See `SKILL.md` for the cross-platform loop (snapshot-before-AND-after,
-pixel-click contract, failure modes) and `RECORDING.md` for session
+| Environment             | Proven baseline                                                                                                                | Main limits                                                                                                                                                                                                    |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| X11/Openbox             | AT-SPI trees and actions, foreground pointer and keyboard input, window and desktop capture, and video                         | Raw background delivery remains toolkit-specific; unsupported shapes refuse                                                                                                                                    |
+| Sway/wlroots            | AT-SPI, native discovery, full-display and cropped-window screencopy, foreground input, semantic background actions, and video | Raw background pointer and keyboard input remains focus-bound                                                                                                                                                  |
+| Hyprland/Omarchy        | Experimental source candidate with separate discovery-foundation and bounded two-seat app evidence                             | Default plugin is discovery-only; raw background v3 qualification is limited to the exact native Calc/Inkscape packages and a private agent US keymap; user Caps-to-Ctrl/Super remaps do not alter agent semantics; complete native harness and release acceptance are separate gates |
+| GNOME/Mutter            | AT-SPI, WinRects geometry and activation, capture, and portal/libei foreground input                                           | Requires the helper and portal grant; portal video parity remains open                                                                                                                                         |
+| KDE/KWin                | AT-SPI and generic discovery where exposed                                                                                     | Target-specific activation and behavioral coverage remain experimental                                                                                                                                         |
+| Nested `cua-compositor` | Versioned direct per-surface input, native GTK 31/31, capture/scope 5/5, and partial Electron coverage                         | The complete shared matrix remains experimental; do not infer standard-Wayland support                                                                                                                         |
+
+See [WORKFLOW.md](WORKFLOW.md) for exact targeting and verification and `RECORDING.md` for session
 recording.