ucu-mcp 0.5.1 → 0.5.2

package/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.2] - 2026-06-17
+
+Agent Skill 重写为 CLI agent 优先（Claude Code / Codex / OpenCode 都是 stdio CLI 环境）。
+
+### Changed
+
+- **SKILL.md 重写**：Core Workflow 改为"决策循环"状态机视角（observe → decide → act → verify），强调 CLI agent 每次工具调用无状态、必须每次重新观察。新增"Reading click results"表（v0.5.1 的 method/verified 信号解读：axpress+true 放心走 / axpress+false 复核 / coordinate+false 必须重新观察）。工具选择改为 AX-first / vision-fallback / tray 三分法。Operating Rules 第一条改为"Re-observe before every action"。
+- **workflows.md 重写**：所有 playbook 改为 CLI 可执行序列（每步读响应再决定下一步）。cc-switch playbook（#2）补充真实 gotcha：click_menu_bar_extra 打开的是原生应用菜单（About/Hide/Quit），"使用统计"在 WebView 设置窗口内；托盘菜单在独立调用间会自动关闭，必须用 captureAfter 单次捕获。新增 workflow #6（verify click 结果）和 #8（卡住时的诊断顺序）。
+- **troubleshooting.md**：新增"Click result signals (v0.5.1+)"节，解释 method/verified 不是错误而是置信度信号。
+- **README** Agent Skill 节：明确"为 CLI agent 编写"。
+
+### 真机验证（按重写后的 skill workflow 重跑）
+
+- ✅ doctor ready / focus_app(cc-switch) 建 tray target / click_menu_bar_extra 返回 method:axpress verified:true。
+- ✅ 验证了 skill 的核心价值：workflow #2 的 gotcha 指引正确诊断出 cc-switch 托盘菜单只有 About/Hide/Quit（原生应用菜单），"使用统计"需开 WebView 设置窗口。
+- ⚠️ 发现真实 CLI 痛点：cc-switch 托盘菜单在独立 ocr 调用间自动关闭（失焦即关），必须用 captureAfter 在单次 click_menu_bar_extra 调用里捕获——这正是 skill 新 workflow #6 强调的"单次调用捕获"模式。
+
 ## [0.5.1] - 2026-06-16
 
 方向4b AXPress verify-then-fallback + 方向5 FocusStealSuppression @deprecated 文档化。

package/README.md

@@ -421,11 +421,13 @@ The same readiness report is also available as the MCP `doctor` tool.
 
 ## Agent Skill
 
-UCU-MCP ships an installable **agent skill** that gives Codex, Claude Code, and
-other agent runtimes richer guidance than the embedded MCP `instructions:` field
-alone — structured tool-selection rules, task playbooks, and an error-recovery
-reference. The skill lives at [`skills/ucu-mcp/`](skills/ucu-mcp/SKILL.md) and
-is included in the npm tarball.
+UCU-MCP ships an installable **agent skill** written for **CLI agents** (Claude
+Code, Codex, OpenCode) that connect via stdio MCP and drive the desktop one
+tool call at a time. It gives richer guidance than the embedded MCP
+`instructions:` field: a decision loop (observe → decide → act → verify),
+tool-selection rules (AX-first / vision-fallback / tray), click-result signal
+interpretation (`method`/`verified`), task playbooks, and an error-recovery
+reference.
 
 Install it for your agent runtime with the [`skills` CLI](https://www.npmjs.com/package/skills):
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucu-mcp",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "MCP server for Universal Computer Use — desktop automation for AI agents via Model Context Protocol",
   "type": "module",
   "bin": {

package/skills/ucu-mcp/SKILL.md

@@ -5,96 +5,134 @@ description: >-
   click, type, OCR, AX element tools, menu-bar tray support). Use when an
   agent needs to automate macOS desktop apps over MCP — establishing target
   context, reading screen state, interacting with UI elements, operating
-  menu-bar/tray apps, or recovering from AX/permission errors. Covers Claude
-  Code CLI/Desktop, Codex, OpenCode, and other MCP clients.
+  menu-bar/tray apps, or recovering from AX/permission errors. Designed for
+  CLI agents (Claude Code, Codex, OpenCode) that connect via stdio MCP and
+  drive the desktop one tool call at a time.
 ---
 
 # UCU-MCP
 
-UCU-MCP is a cross-client computer-use MCP server for macOS (Windows/Linux are
-explicit stubs). It exposes 26 tools that let an agent see the screen and drive
-native apps through a combination of Accessibility (AX) APIs, CGEvent input
-synthesis, Vision OCR, and ScreenCaptureKit screenshots.
-
-- npm package: `ucu-mcp`
-- Run: `npx -y ucu-mcp` (stdio MCP server) or install globally via `npm i -g ucu-mcp`
-
-## Core Workflow
-
-1. **Check readiness** → `doctor` verifies Accessibility + Screen Recording
-   permissions and native helpers. If anything is missing, follow its guidance
-   (see [troubleshooting](references/troubleshooting.md)).
-2. **Establish target context** → `list_apps` then `focus_app(name)` sets the
-   active window target. Subsequent AX tools operate against that target.
-3. **Prefer AX over coordinates** → `find_element(text/role/value)` →
-   `click_element` / `type_in_element` / `set_value`. AX is precise and survives
-   layout shifts; coordinates are a last resort.
-4. **When AX is opaque (Electron/Tauri/WebView)** → `screenshot` + `ocr` to
-   locate text by bounding box, then `click(x, y)` at the returned coordinates.
-5. **When image content is not visible to you** (relayed/downgraded to a URL) →
-   `screenshot(describe: true)` or the standalone `describe_screen` tool to get a
-   structured text view (OCR blocks + AX tree + foreground window).
-6. **Menu-bar/tray apps** (e.g. cc-switch) → `click_menu_bar_extra(app,
-   description/name/index)` opens the tray menu, then `find_element` inside it.
-7. **Verify actions** → pass `captureAfter: true` on action tools, or call
-   `screenshot` / `get_window_state` afterwards.
-8. **Recover from errors** → every error response carries a `hint` with the
-   next step. See the [error code table](references/troubleshooting.md).
-
-Full tool inventory with parameters: [tool-reference](references/tool-reference.md).
-Common task playbooks: [workflows](references/workflows.md).
+UCU-MCP is a macOS computer-use MCP server for CLI agents. It exposes 26 tools
+that let you see the screen and drive native apps through Accessibility (AX)
+APIs, CGEvent input synthesis, Vision OCR, and ScreenCaptureKit screenshots.
+Windows/Linux are explicit stubs.
 
-## Operating Rules
+- npm: `ucu-mcp` · run: `npx -y ucu-mcp` (stdio MCP server)
+- You are a **CLI agent**: each tool call is one MCP request over stdio. There
+  is no persistent UI session between calls — **always re-observe state before
+  acting**, because the user or the app may have changed the screen since your
+  last call.
 
-- **AX-first.** Use `find_element` → `click_element` / `type_in_element` /
-  `set_value` whenever the AX tree exposes the target. Fall back to coordinates
-  only when AX returns nothing (Electron/WebView) or the control silently
-  swallows AX actions.
-- **Observe before acting.** Call `screenshot` / `get_window_state` /
-  `describe_screen` before destructive or hard-to-reverse actions so you act on
-  current state, not assumptions.
-- **TARGET_STALE is recoverable.** Re-run `focus_app` for the target app, then
-  retry — the element cache refetches equivalent AX nodes.
-- **Tray apps need `click_menu_bar_extra`.** `focus_app` alone cannot reach
-  pure menu-bar (LSUIElement) apps; their status item is hosted by
-  `SystemUIServer` and is not in any app window's AX tree.
-- **Dangerous actions are blocked.** Quit/logout/lock shortcuts (`cmd+q`,
-  `cmd+shift+q`, `cmd+l`, …), sensitive-window URLs, and suspicious injected
-  text are rejected by the safety guard. Choose a safer action or ask the user.
-- **Sensitive fields are masked in `describe_screen`.** Password fields
-  (`AXSecureTextField`, or names matching `/password|secret|token/i`) appear as
-  `[REDACTED]` — never try to read or exfiltrate them.
-- **macOS is locked → actions blocked.** The server refuses to synthesize input
-  while the screen is locked; wait for unlock or ask the user.
-
-## MCP Config
-
-Add UCU-MCP to your MCP client. Stdio transport, no arguments needed.
-
-**Codex / generic TOML:**
-
-```toml
-[mcp_servers.ucu-mcp]
-command = "npx"
-args = ["-y", "ucu-mcp"]
-```
+## The Decision Loop (run this for every action)
 
-**Claude Code CLI / Desktop** — add via `claude mcp add`:
+Think in cycles of **observe → decide → act → verify**. Do not chain actions
+blindly; the desktop is a moving target.
 
-```bash
-claude mcp add ucu-mcp -- npx -y ucu-mcp
 ```
+┌─────────────────────────────────────────────────────────────┐
+│  OBSERVE: what's on screen / what's focused right now?      │
+│    screenshot{}  ·  describe_screen{}  ·  get_window_state{} │
+├─────────────────────────────────────────────────────────────┤
+│  DECIDE: AX-first, coordinates only as fallback              │
+│    AX tree exposes target? → find_element → element tools   │
+│    AX opaque (Electron/Tauri)? → ocr → click(x,y)           │
+│    Tray-only app? → click_menu_bar_extra                    │
+├─────────────────────────────────────────────────────────────┤
+│  ACT: click_element / type_in_element / set_value / click   │
+│    Pass captureAfter:true to get a screenshot in the reply  │
+├─────────────────────────────────────────────────────────────┤
+│  VERIFY: did it work? (see "Reading click results" below)   │
+│    result.verified === true   → proceed                     │
+│    result.verified === false  → screenshot/get_window_state │
+│    result.method === "coordinate" → re-observe, may be off  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Reading click results (v0.5.1+)
+
+`click_element` and `click_menu_bar_extra` return a `result` object with
+`method` and `verified` fields. **Read them every time** — they tell you
+whether your click actually landed:
+
+| `method` | `verified` | Meaning | What you do |
+|---|---|---|---|
+| `"axpress"` | `true` | AXPress changed observable state (value/focused/selected) | Proceed — high confidence it worked |
+| `"axpress"` | `false` | AXPress ran but element had no observable state to verify (e.g. plain button) | Verify via `screenshot` or `get_window_state` |
+| `"coordinate"` | `false` | AXPress was silently swallowed (Tauri/Electron) OR threw; fell back to coordinate click | **Always re-observe** — coordinate clicks can miss, or the app may need a second click |
+
+A `warnings[]` array in the receipt explains the fallback. Never assume a
+coordinate-fallback click succeeded without checking.
+
+## Tool selection — AX vs vision vs tray
+
+**AX-first** (precise, survives layout shifts):
+`find_element` → `click_element` / `type_in_element` / `set_value`. Use when
+the app exposes an AX tree (native macOS apps, most non-Electron apps).
+
+**Vision fallback** (when AX is opaque — Electron/Tauri/WebView return an
+empty `AXGroup` or `find_element` returns 0 with an "app is likely Electron"
+hint):
+`screenshot` → `ocr` → compute click point from the OCR block's bounding box
+→ `click(x, y)` at `block.x + block.width/2, block.y + block.height/2`.
 
-Run `ucu-mcp doctor` once after first connect to verify macOS permissions
-(System Settings → Privacy & Security → Accessibility **and** Screen Recording
-must be granted to the launching terminal/client).
+**Text-only fallback** (when you cannot see image content blocks — relay
+downgrades them to URLs):
+`describe_screen` or `screenshot({describe: true})` → structured text with OCR
+blocks + AX tree. Password fields are masked to `[REDACTED]`.
+
+**Tray apps** (menu-bar-only / LSUIElement apps like cc-switch — no window, no
+AX tree entry):
+`focus_app` (falls back to a tray target) → `click_menu_bar_extra` opens the
+menu → `find_element` inside the menu, or `screenshot`+`ocr` if the menu is
+also opaque.
+
+## First-run setup
+
+1. **Connect the server** to your CLI agent:
+
+   Codex / generic TOML (`.codex/config.toml` or equivalent):
+   ```toml
+   [mcp_servers.ucu-mcp]
+   command = "npx"
+   args = ["-y", "ucu-mcp"]
+   ```
+
+   Claude Code CLI:
+   ```bash
+   claude mcp add ucu-mcp -- npx -y ucu-mcp
+   ```
+
+2. **Grant macOS permissions** — Accessibility **and** Screen Recording must be
+   enabled for your terminal/client in System Settings → Privacy & Security.
+   **Restart the client after granting** (changes don't apply to running
+   processes).
+
+3. **Verify** — call `doctor`. It reports per-permission status, native helper
+   health, and which process to authorize. Green = ready.
+
+## Operating Rules
+
+- **Re-observe before every action.** The screen changes between your calls.
+  A `focus_app` from 5 calls ago may be stale; a window may have closed.
+- **AX-first, coordinates only as fallback.** AX clicks are precise and
+  verifiable; coordinate clicks can drift and are unverifiable.
+- **`verified:false` means re-observe.** Never trust an unverifiable click
+  without a follow-up `screenshot` or `get_window_state`.
+- **TARGET_STALE is recoverable.** Re-run `focus_app` for the target app, then
+  retry. `type_in_element` auto-refetches equivalent AX nodes.
+- **Dangerous actions are blocked.** `cmd+q`, `cmd+shift+q`, `cmd+l`, `alt+f4`,
+  sensitive-window URLs, and suspicious injected text are rejected. Choose a
+  safer action or ask the user.
+- **macOS locked → all input blocked.** Wait for unlock; there is no bypass.
+- **Don't exfiltrate passwords.** `describe_screen` masks them to
+  `[REDACTED]`; respect that.
 
 ## References
 
 - [tool-reference.md](references/tool-reference.md) — all 26 tools, parameters,
   return shapes, and when to use each.
-- [workflows.md](references/workflows.md) — playbooks for common tasks: form
+- [workflows.md](references/workflows.md) — CLI-executable playbooks (form
   filling, tray apps, opaque Electron UIs, vision-degraded environments, stale
-  targets.
+  targets, click-result verification).
 - [troubleshooting.md](references/troubleshooting.md) — error code table with
   recovery steps, permission issues, AX-opacity workarounds, OCR failures.

package/skills/ucu-mcp/references/troubleshooting.md

@@ -30,6 +30,30 @@ to recovery steps (mirrors the runtime `recoveryHint`).
 
 ---
 
+## Click result signals (v0.5.1+)
+
+`click_element` and `click_menu_bar_extra` return `result.method` and
+`result.verified`. These are not errors — they tell you how confident to be:
+
+- **`method:"axpress", verified:true`** — AXPress changed observable state.
+  Proceed normally.
+- **`method:"axpress", verified:false`** — AXPress ran but the element exposed
+  no observable state (plain button, no value/focused/selected). It *probably*
+  worked, but re-observe with `screenshot`/`get_window_state` to be sure. A
+  `warnings[]` entry explains this.
+- **`method:"coordinate", verified:false`** — AXPress was silently swallowed
+  (Tauri/Electron custom controls) or threw; ucu-mcp fell back to a coordinate
+  click at the element's bounds center. **Coordinate clicks can miss** — always
+  re-observe. A `warnings[]` entry says "coordinate fallback was used".
+
+This is not a bug — it's the server telling you it couldn't fully confirm the
+click. The verify-then-fallback logic exists *because* Tauri/Electron controls
+silently swallow AXPress without throwing.
+
+---
+
+---
+
 ## Permission Issues
 
 macOS requires two permissions for full functionality:

package/skills/ucu-mcp/references/workflows.md

@@ -1,146 +1,209 @@
 # Workflows
 
-Common task playbooks. Each shows the preferred tool sequence and the fallback
-path when the primary path is blocked.
+CLI-executable playbooks. Each is a sequence of tool calls you make one at a
+time, reading each response before the next. Coordinates are screen-absolute
+unless noted.
 
 ---
 
-## 1. Fill a form field
+## 1. Fill a form field (native app, AX-visible)
 
-**Primary (AX):**
 ```
-focus_app("Safari")
-find_element({ text: "Email", role: "AXTextField" })
-  → elementId "Safari/w0/42"
+# 1. establish target
+list_apps({})
+focus_app({ app: "Safari" })
+
+# 2. locate the field via AX
+find_element({ text: "Email", role: "AXTextField", app: "Safari" })
+# → response.result.results[0].id  e.g. "Safari/w0/42"
+
+# 3. type into it
 type_in_element({ elementId: "Safari/w0/42", text: "user@example.com" })
-```
 
-**Fallback (AX value set, for non-text controls):**
-```
-set_value({ elementId: "...", value: "option" })
+# 4. verify (captureAfter returns a screenshot in the same reply)
+type_in_element({ elementId: "Safari/w0/42", text: "...", captureAfter: true })
 ```
 
-**Fallback (coordinates, when AX is opaque):**
-```
-screenshot({})
-ocr({})  → blocks[].text === "Email" → {x, y, width, height}
-click({ x: block.x + block.width/2, y: block.y + block.height/2 })
-type_text({ text: "user@example.com" })
-```
+**If `find_element` returns 0** with an "app is likely Electron" hint → switch
+to workflow #3 (vision fallback).
+
+**If `type_in_element` throws TARGET_STALE** → `focus_app("Safari")` then retry
+(it auto-refetches equivalent AX nodes).
 
 ---
 
 ## 2. Operate a menu-bar / tray app (e.g. cc-switch)
 
-Tray apps' status items live in `SystemUIServer`, not the app's own window AX
-tree. `focus_app` alone may return `WINDOW_NOT_FOUND`.
+Tray-only apps (LSUIElement) have no window; their status item is hosted by
+`SystemUIServer`. `focus_app` alone returns `WINDOW_NOT_FOUND` unless ucu-mcp
+finds a tray status item and falls back to a tray target.
 
 ```
-focus_app("cc-switch")           # establishes tray target if status item found
-click_menu_bar_extra({ app: "cc-switch", name: "switch" })  # opens the menu
-# menu is now open — find items inside it:
-find_element({ text: "使用统计", app: "cc-switch" })
-  → elementId
-click_element({ elementId })
-```
+# 1. establish tray target (returns windowId:"tray" on success)
+focus_app({ app: "cc-switch" })
 
-If the menu's AX tree is opaque (some Tauri/Electron menus):
-```
-click_menu_bar_extra({ app: "cc-switch" })
+# 2. open the tray menu — check result.verified!
+click_menu_bar_extra({ app: "cc-switch", name: "switch" })
+# → result: { clicked: true, method: "axpress", verified: true|false }
+
+# 3a. IF the menu exposes AX items, find and click them:
+find_element({ text: "Settings", app: "cc-switch" })
+click_element({ elementId: "..." })
+
+# 3b. IF find_element returns 0 (menu is also opaque), use vision:
 screenshot({})
-ocr({})  → locate "使用统计" by text → coordinates
-click({ x, y })
+ocr({})
+# → find the menu item text in ocr.blocks, compute center, click:
+click({ x: block.x + block.width/2, y: block.y + block.height/2 })
 ```
 
+**Known gotcha (cc-switch and similar Tauri tray apps):** `click_menu_bar_extra`
+may open the app's **native application menu** (About / Hide / Quit) rather than
+a custom tray popup. If OCR shows only About/Hide/Quit, the app's real settings
+live in a **WebView window** — you need to open that window first (via a menu
+item, or `focus_app` once a window exists), then drive it with workflow #3
+(Electron-opaque). Don't keep clicking the tray expecting a custom menu.
+
+**If `click_menu_bar_extra` returns `method:"coordinate"`** (AXPress was
+swallowed) → re-observe with `screenshot` to confirm the menu actually opened
+before searching its contents.
+
 ---
 
-## 3. Electron / WebView opaque UI
+## 3. Electron / Tauri / WebView opaque UI
 
-Electron/Tauri apps often expose only a near-empty `AXGroup`. The runtime `hint`
-on `find_element` and `list_windows` tells you when this is happening.
+Electron/Tauri apps render UI in a composited layer AX cannot introspect.
+`find_element` returns 0; `get_window_state` shows a near-empty `AXGroup`;
+`list_windows` emits an Electron hint.
 
 ```
+# 1. confirm opacity (optional — the hint in the error tells you)
 find_element({ text: "Submit" })
-  → 0 results, hint: "app is likely Electron... screenshot → ocr → click(x,y)"
+# → 0 results, hint: "...likely Electron... screenshot → ocr → click(x,y)"
 
-screenshot({})
-ocr({ region: { x, y, width, height } })  # or full screen
-  → blocks[].text === "Submit" → {x, y, width, height}
+# 2. see the screen via OCR (text + bounding boxes)
+screenshot({})              # for yourself, if you can see images
+ocr({})                     # → blocks[].text with {x, y, width, height}
+
+# 3. locate target text, compute click center, click by coordinate
+#    (OCR coordinates are screen-absolute)
 click({ x: block.x + block.width/2, y: block.y + block.height/2 })
+
+# 4. verify the coordinate click landed (coordinate clicks are unverifiable)
+screenshot({})  # or describe_screen({}) if you can't see images
 ```
 
-For repeated interaction with a known-opaque app, snapshot once with
-`describe_screen` to plan, then drive by coordinates.
+For multi-step interaction with a known-opaque app, call `describe_screen` once
+to plan, then drive by coordinates. Keep re-OCR-ing between steps — WebView
+layouts shift.
 
 ---
 
-## 4. Vision-degraded environment (image content not visible)
+## 4. Vision-degraded environment (you can't see image content)
 
-When the model cannot see `screenshot` image blocks (relay/downgrade to URLs),
-switch to text-based screen reading:
+When `screenshot` image blocks are downgraded to URLs you cannot fetch, switch
+to text-based screen reading:
 
 ```
 describe_screen({ ocr: true, includeAx: true })
-  → { screen, foregroundWindow, ocr:{blocks}, ax:{elements}, errors }
+# → { capturedAt, screen, foregroundWindow, ocr:{blocks, status}, ax:{elements, status}, errors }
 
-# or, if you also want the image for clients that DO support it:
-screenshot({ describe: true })
-  → [image block, text description block]
+# OCR blocks give you text + screen coordinates — drive by click(x,y)
+# AX elements give you a tree you can find_element/click_element on
 ```
 
-`describe_screen` never throws — OCR and AX each try/catch independently, so a
-Vision failure still returns AX state and vice versa. Check `errors[]` to know
-what was skipped/failed.
+`describe_screen` **never throws** — OCR and AX each try/catch independently.
+Check `errors[]` to see what was skipped/failed, and `ocr.status` / `ax.status`
+(`"ok"` / `"skipped"` / `"failed"`). If OCR failed, fall back to AX-only
+(`includeAx: true, ocr: false`); if AX failed, fall back to OCR-only.
+
+`screenshot({ describe: true })` returns both an image (for clients that can
+see it) **and** a text description block — use this when you're unsure whether
+your client renders images.
 
 ---
 
 ## 5. Recover from TARGET_STALE
 
-The active window target can go stale (window closed, app restarted, pid
-changed). AX tools throw `TARGET_STALE`.
+The active window target goes stale when the window closes, the app restarts,
+or the pid changes. AX tools throw `TARGET_STALE` (receipt includes a `hint`).
 
 ```
-# error response includes hint: "Run focus_app again for the target app..."
-focus_app("Safari")              # re-establishes target
-find_element({ text: "Save" })   # retry — cache refetches equivalent nodes
-click_element({ elementId })
+# 1. re-establish the target
+focus_app({ app: "Safari" })
+
+# 2. retry — element cache refetches equivalent AX nodes
+find_element({ text: "Save" })
+click_element({ elementId: "..." })
 ```
 
-`type_in_element` automatically refetches an equivalent AX node if the original
-`elementId` is stale, so a single retry often succeeds without `focus_app`.
+`type_in_element` auto-refetches an equivalent AX node if the `elementId` is
+stale, so a single retry often succeeds without re-running `focus_app`.
 
 ---
 
-## 6. Verify an action succeeded
+## 6. Verify a click succeeded (v0.5.1+)
 
-Always verify after clicks/types — UI may not have updated, or the wrong element
-was hit.
+Every `click_element` / `click_menu_bar_extra` response includes `result.method`
+and `result.verified`. Use them to decide whether to trust the click:
 
 ```
-click_element({ elementId, captureAfter: true })   # screenshot in response
-# or explicitly:
-screenshot({})
-# or check AX state:
-get_window_state({})  → focusedElement / tree reflects the change
-# or wait for a specific change:
-wait_for_element({ text: "Saved", until: "appear", timeout: 3000 })
+click_element({ elementId: "btn1" })
+# → result: { clicked: true, method: "axpress", verified: true }
+#   ✓ AXPress changed observable state — proceed with confidence
+
+# OR
+# → result: { clicked: true, method: "coordinate", verified: false }
+#   warnings: ["AXPress produced no observable state change...coordinate fallback..."]
+#   ⚠ MUST re-observe — coordinate clicks can miss or hit the wrong spot:
+screenshot({})            # see where you are now
+# or
+get_window_state({})      # check AX state changed as expected
+# or
+wait_for_element({ text: "Success", until: "appear", timeout: 3000 })
 ```
 
+**Rule: `verified:false` always triggers a follow-up observation.** Do not chain
+another action on top of an unverifiable click.
+
 ---
 
-## 7. Multi-step task with error recovery
+## 7. Multi-step task with full loop
+
+A realistic CLI sequence with observe → decide → act → verify at each step:
 
 ```
-doctor()                                  # verify permissions first
-list_apps()
-focus_app("Notes")
-find_element({ text: "New Note" }) → id
-click_element({ elementId: id, captureAfter: true })
-
-# if click_element throws ELEMENT_NOT_FOUND:
-find_element({ text: "New Note" }) → id2  # refetch, id may have changed
+# setup
+doctor({})                         # permissions + helpers green?
+list_apps({})
+focus_app({ app: "Notes" })
+
+# step 1: find and click "New Note"
+find_element({ text: "New Note" })        # → id "Notes/w0/3"
+click_element({ elementId: "Notes/w0/3", captureAfter: true })
+# read result.verified; if false → screenshot to confirm a new note opened
+
+# step 2: if ELEMENT_NOT_FOUND (UI shifted), refetch
+find_element({ text: "New Note" })        # → id2 (may differ)
 click_element({ elementId: id2 })
 
-type_in_element({ elementId: bodyId, text: "Hello" })
-screenshot({})                            # confirm content
+# step 3: type into the new note body
+find_element({ role: "AXTextArea" })      # → bodyId
+type_in_element({ elementId: bodyId, text: "Hello", captureAfter: true })
+
+# step 4: confirm
+screenshot({})                            # or describe_screen({}) if vision-degraded
 ```
+
+---
+
+## 8. When you're stuck — diagnostic order
+
+If tools keep failing and you don't know why:
+
+1. `doctor({})` — permissions/helpers still green? (Screen may have re-locked.)
+2. `list_apps({})` + `list_windows({})` — is the target app/window still there?
+3. `screenshot({})` or `describe_screen({})` — what's *actually* on screen right
+   now? (You may be looking at a different app than you think.)
+4. Read the `hint` in the last error response — it names the recovery step.
+5. Check [troubleshooting.md](troubleshooting.md) for the error code.