ucu-mcp 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -5,6 +5,54 @@ 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 文档化。
+
+### Added
+
+- **方向4b AXPress verify-then-fallback（clickElement + clickMenuBarExtra）**：解决 Tauri/Electron 控件静默吞 AXPress（不抛异常也不执行）。双层策略：(1) 启发式跳过——对已知静默吞的应用（`AX_SILENT_APP_HINTS = ["tauri"]`，按 appName includes 匹配）直接坐标点击，跳过 AXPress；(2) verify 状态签名——对走 AXPress 的应用，采样前后 `value|focused|selected` 签名，spin 80ms 等异步生效，无变化则降级坐标。`ClickResult { method: "axpress"|"coordinate"; verified: boolean }` 透到 ActionReceipt.result，verified:false 时附 warning 引导模型用 screenshot/get_window_state 复核。无可观测状态的元素（纯按钮）保守判 verified:false 但不降级坐标（避免误伤）。共享 JXA 原语 `stateSignature`/`coordinateClick`/`spinMs`。
+- 返回类型波及链：`clickElement`/`clickMenuBarExtra` `Promise<void>` → `Promise<ClickResult>`（base.ts 接口 + windows/linux stub + element.ts consumer + tools-layer mock）。
+
+### Changed
+
+- **方向5 FocusStealSuppression @deprecated 文档化**：`focus.ts` 的 `saveFocus`/`restoreFocus` 加 `@deprecated` JSDoc，说明 CGEvent 在 HID 层工作不需前台 focus、焦点管理被有意禁用、`tools-layer.test.ts` 的 `not.toHaveBeenCalled()` 锁定禁用态。不删不接线（文档化设计决策，非遗漏）。`base.ts` 接口注释同步。
+
+### Fixed
+
+- 无行为修复（4b/5 是 v0.5.0 的质量强化）。
+
+### 真机验证（2026-06-16）
+
+- ✅ doctor 全绿（3 native helpers + 权限 + 26 工具）。
+- ✅ OCR（方向1）返回非空 elements，无 NSNull 崩溃。
+- ✅ press_key 字母键 Cmd+M（方向2）成功合成，不报 Unknown key。
+- ✅ describe_screen（方向3）结构正确，AX 失败时聚合到 errors[] 不抛出。
+- ✅ focus_app(cc-switch)（方向4a）建立 tray target（windowId:"tray"），不抛 WINDOW_NOT_FOUND。
+- ✅ click_menu_bar_extra（方向4b）返回 `method:"axpress", verified:true`——托盘菜单真实打开（OCR 确认 "About/Hide/Quit CC Switch" 菜单项可见）。
+- ⚠️ 发现：cc-switch 托盘菜单是其**原生应用菜单**（About/Hide/Quit），"使用统计"在 WebView 设置面板内，不在托盘菜单。完整 "设置→使用统计" 流程需先打开设置窗口（非托盘菜单可达），留 follow-up。
+
+### Tests
+
+- 303→310（+7：clickElement ClickResult 解析、JXA stateSignature/spinMs/coordinateClick/sigBefore/sigAfter/preferCoord source 断言、Tauri 启发式 preferCoord=true、tools-layer method/verified 透出 + warnings）。
+
 ## [0.5.0] - 2026-06-15
 
 cc-switch 操控诊断与视觉通道修复：打通 OCR + 字母快捷键 + 托盘 + 视觉降级 fallback + 内置 agent skill。

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/dist/src/mcp/tools/element-tools.js

@@ -36,8 +36,13 @@ export function registerElementTools(registerTool) {
     }, async (params) => {
         const effectiveApp = params.app || getActiveTarget()?.appName;
         const safetyCtx = await getSafetyContext();
-        await withSafety({ action: "click_element", params: { ...safetyCtx }, requiresAccessibility: true, execute: () => getPlatform().clickElement(params.elementId, effectiveApp) });
-        return actionResponse("click_element", { clicked: true, elementId: params.elementId }, { elementId: params.elementId, app: effectiveApp }, params.captureAfter, params.captureFormat, params.captureMaxWidth);
+        const clickResult = await withSafety({ action: "click_element", params: { ...safetyCtx }, requiresAccessibility: true, execute: () => getPlatform().clickElement(params.elementId, effectiveApp) });
+        const warnings = clickResult.verified
+            ? []
+            : [clickResult.method === "coordinate"
+                    ? "AXPress produced no observable state change (or the app is known to silently swallow it); coordinate fallback was used. Re-observe with screenshot/get_window_state to confirm."
+                    : "AXPress completed but the element exposed no observable state to verify against. Re-observe with screenshot/get_window_state to confirm."];
+        return actionResponse("click_element", { clicked: true, elementId: params.elementId, method: clickResult.method, verified: clickResult.verified }, { elementId: params.elementId, app: effectiveApp }, params.captureAfter, params.captureFormat, params.captureMaxWidth, warnings);
     });
     registerTool("set_value", "Set the value of an accessibility element", {
         elementId: z.string().describe("AX element identifier"), value: z.string().describe("Value to set"), app: z.string().optional().describe("Target app"), ...captureAfterFields,
@@ -64,7 +69,12 @@ export function registerElementTools(registerTool) {
         ...captureAfterFields,
     }, async (params) => {
         const safetyCtx = await getSafetyContext();
-        await withSafety({ action: "click_menu_bar_extra", params: { ...safetyCtx }, requiresAccessibility: true, execute: () => getPlatform().clickMenuBarExtra(params.app, { description: params.description, name: params.name, index: params.index }) });
-        return actionResponse("click_menu_bar_extra", { clicked: true, app: params.app }, { app: params.app }, params.captureAfter, params.captureFormat, params.captureMaxWidth);
+        const clickResult = await withSafety({ action: "click_menu_bar_extra", params: { ...safetyCtx }, requiresAccessibility: true, execute: () => getPlatform().clickMenuBarExtra(params.app, { description: params.description, name: params.name, index: params.index }) });
+        const warnings = clickResult.verified
+            ? []
+            : [clickResult.method === "coordinate"
+                    ? "AXPress produced no observable state change; coordinate fallback was used. Use find_element or screenshot to confirm the menu opened."
+                    : "AXPress completed but the status item exposed no observable state to verify against. Use find_element or screenshot to confirm the menu opened."];
+        return actionResponse("click_menu_bar_extra", { clicked: true, app: params.app, method: clickResult.method, verified: clickResult.verified }, { app: params.app }, params.captureAfter, params.captureFormat, params.captureMaxWidth, warnings);
     });
 }

package/dist/src/platform/base.d.ts

@@ -126,6 +126,17 @@ export interface WindowState {
     focusedElement?: ElementInfo;
     tree?: ElementInfo;
 }
+/**
+ * Outcome of an AX-driven click — surfaces whether AXPress was used and whether
+ * its effect was observable. `verified:false` means either the element exposed
+ * no observable state (inconclusive) or the click fell back to coordinates
+ * (silent AXPress swallow on Tauri/Electron). The tool layer surfaces this so
+ * the model can decide whether to re-observe via screenshot/get_window_state.
+ */
+export interface ClickResult {
+    method: "axpress" | "coordinate";
+    verified: boolean;
+}
 /**
  * Structured text description of the screen — a fallback for environments where
  * image content blocks are downgraded to URLs (so the model cannot see screenshots).
@@ -169,7 +180,7 @@ export interface Platform {
     type(text: string, delay?: number): Promise<void>;
     key(keys: string[]): Promise<void>;
     findElement(options: FindElementOptions): Promise<FindElementResponse>;
-    clickElement(elementId: string, app?: string): Promise<void>;
+    clickElement(elementId: string, app?: string): Promise<ClickResult>;
     typeInElement(elementId: string, text: string, app?: string, clearFirst?: boolean): Promise<void>;
     setElementValue?(elementId: string, value: string, app?: string): Promise<void>;
     findMenuBarExtra?(app: string): Promise<unknown[]>;
@@ -177,7 +188,7 @@ export interface Platform {
         description?: string;
         name?: string;
         index?: number;
-    }): Promise<void>;
+    }): Promise<ClickResult>;
     isScreenLocked?(): boolean;
     saveFocus?(): Promise<void>;
     restoreFocus?(): Promise<void>;

package/dist/src/platform/linux.d.ts

@@ -1,4 +1,4 @@
-import type { Platform, ScreenRegion, ScreenSize, CursorPosition, WindowInfo, WindowState, OcrResult, FindElementOptions, FindElementResponse } from "./base.js";
+import type { Platform, ScreenRegion, ScreenSize, CursorPosition, WindowInfo, WindowState, OcrResult, FindElementOptions, FindElementResponse, ClickResult } from "./base.js";
 /**
  * Linux platform adapter (AT-SPI2 + xdotool fallback)
  * TODO: Implement with D-Bus AT-SPI2 bindings
@@ -17,7 +17,7 @@ export declare class LinuxPlatform implements Platform {
     key(keys: string[]): Promise<void>;
     ocr(_display?: number, _region?: ScreenRegion): Promise<OcrResult>;
     findElement(_options: FindElementOptions): Promise<FindElementResponse>;
-    clickElement(_elementId: string, _app?: string): Promise<void>;
+    clickElement(_elementId: string, _app?: string): Promise<ClickResult>;
     typeInElement(_elementId: string, _text: string, _app?: string, _clearFirst?: boolean): Promise<void>;
     readClipboard(): Promise<string>;
     writeClipboard(text: string): Promise<void>;

package/dist/src/platform/macos/element.d.ts

@@ -1,5 +1,6 @@
 import type { MacOSPlatform } from "./base.js";
-export declare function clickElement(this: MacOSPlatform, elementId: string, app?: string): Promise<void>;
+import type { ClickResult } from "../base.js";
+export declare function clickElement(this: MacOSPlatform, elementId: string, app?: string): Promise<ClickResult>;
 export declare function typeInElement(this: MacOSPlatform, elementId: string, text: string, app?: string, clearFirst?: boolean): Promise<void>;
 export declare function setElementValue(this: MacOSPlatform, elementId: string, value: string, app?: string): Promise<void>;
 export interface MenuBarExtraItem {
@@ -21,4 +22,4 @@ export interface MenuBarExtraSelector {
 }
 export declare function findMenuBarExtra(this: MacOSPlatform, app: string): Promise<MenuBarExtraItem[]>;
 export declare function matchMenuBarExtra(items: MenuBarExtraItem[], selector: MenuBarExtraSelector): MenuBarExtraItem | undefined;
-export declare function clickMenuBarExtra(this: MacOSPlatform, app: string, selector?: MenuBarExtraSelector): Promise<void>;
+export declare function clickMenuBarExtra(this: MacOSPlatform, app: string, selector?: MenuBarExtraSelector): Promise<ClickResult>;

package/dist/src/platform/macos/element.js

@@ -2,6 +2,20 @@ import { execFileSync } from "node:child_process";
 import { ElementNotFoundError } from "../../util/errors.js";
 import { rethrowElementActionError } from "./helpers.js";
 import { jxaElementActionHelpers } from "../jxa-helpers.js";
+/**
+ * App-name hints for which AXPress is known to be silently swallowed
+ * (Tauri custom window decorations, some Electron controls). When the target
+ * app matches, clickElement/clickMenuBarExtra skip AXPress and go straight to
+ * a coordinate click. Conservative starting set — extend as more silent-swallow
+ * apps are confirmed.
+ */
+const AX_SILENT_APP_HINTS = ["tauri"];
+function preferCoordinateClick(appName) {
+    if (!appName)
+        return false;
+    const n = appName.toLowerCase();
+    return AX_SILENT_APP_HINTS.some((h) => n.includes(h));
+}
 function prepareCache(elementId) {
     this.evictExpiredCacheEntries();
     const cached = this.elementCache.get(elementId);
@@ -10,22 +24,65 @@ function prepareCache(elementId) {
     }
     return this.elementCache.get(elementId) ?? null;
 }
+/**
+ * Shared JXA snippet: read an observable state signature from an AX element.
+ * Used by clickElement/clickMenuBarExtra to verify whether AXPress actually
+ * changed anything (Tauri/Electron silently swallow AXPress without throwing).
+ * Returns a string concatenation of value/focused/selected (each defensively
+ * read; missing attributes contribute ''). An empty signature means the element
+ * exposes no observable state — verification is inconclusive.
+ */
+const JXA_STATE_SIGNATURE = `
+  function stateSignature(elem) {
+    var parts = [];
+    try { var v = elem.value(); parts.push('v=' + (v === undefined || v === null ? '' : String(v))); } catch(e) { parts.push('v='); }
+    try { parts.push('f=' + (elem.focused ? (elem.focused() ? 1 : 0) : '')); } catch(e) { parts.push('f='); }
+    try { parts.push('s=' + (elem.selected ? (elem.selected() ? 1 : 0) : '')); } catch(e) { parts.push('s='); }
+    return parts.join('|');
+  }
+  // Brief synchronous spin to let an async AXPress propagate state.
+  function spinMs(ms) { var t = Date.now(); while (Date.now() - t < ms) {} }
+`;
+/**
+ * Shared JXA snippet: perform a coordinate click at the element's bounds center.
+ * Returns the {x, y} used, or null if bounds could not be read.
+ */
+const JXA_COORDINATE_CLICK = `
+  function coordinateClick(elem) {
+    var pos = elem.position();
+    var sz = elem.size();
+    var cx = pos[0] + sz[0] / 2;
+    var cy = pos[1] + sz[1] / 2;
+    ObjC.import('CoreGraphics');
+    var src = $.CGEventSourceCreate($.kCGEventSourceStateHIDSystemState);
+    var pt = $.CGPointMake(cx, cy);
+    var down = $.CGEventCreateMouseEvent(src, $.kCGEventLeftMouseDown, pt, $.kCGMouseButtonLeft);
+    $.CGEventPost($.kCGHIDEventTap, down);
+    var up = $.CGEventCreateMouseEvent(src, $.kCGEventLeftMouseUp, pt, $.kCGMouseButtonLeft);
+    $.CGEventPost($.kCGHIDEventTap, up);
+    return {x: cx, y: cy};
+  }
+`;
 export async function clickElement(elementId, app) {
     const elementIdLiteral = JSON.stringify(elementId);
     const effectiveApp = app || this.activeTarget?.appName;
     const appLiteral = JSON.stringify(effectiveApp || "");
     const cachedDescriptor = prepareCache.call(this, elementId);
     const cachedJson = JSON.stringify(cachedDescriptor);
+    const preferCoord = preferCoordinateClick(effectiveApp);
     const jxaScript = `
     var se = Application('System Events');
     var _result = null;
     ${jxaElementActionHelpers()}
+    ${JXA_STATE_SIGNATURE}
+    ${JXA_COORDINATE_CLICK}
     var elemPath = ${elementIdLiteral};
     var appName = ${appLiteral};
     // 容忍大小写/空格/连字符/下划线变体（cc-switch vs CC Switch vs cc_switch）
     var _norm = function(s) { return String(s||'').toLowerCase().split(' ').join('').split('-').join('').split('_').join(''); };
     var appNorm = _norm(appName);
     var cached = ${cachedJson};
+    var preferCoord = ${preferCoord ? "true" : "false"};
 
     var elem = resolveElementInApp(elemPath, appName) || resolveElementByFullPath(elemPath);
     if (elem && !descriptorMatches(elem)) {
@@ -37,27 +94,51 @@ export async function clickElement(elementId, app) {
 
     if (!elem) {
       _result = {success: false, error: "Element not found: " + elemPath};
+    } else if (preferCoord) {
+      // 启发式命中（Tauri 等已知静默吞 AXPress 的应用）：直接坐标点击
+      try {
+        coordinateClick(elem);
+        _result = {success: true, method: "coordinate", verified: false};
+      } catch(e) {
+        _result = {success: false, error: "Could not click element (coordinate): " + String(e.message || e)};
+      }
     } else {
+      // AXPress + verify：采样前后状态签名，无变化则降级坐标
+      var sigBefore = stateSignature(elem);
+      var axpressThrew = false;
       try {
         elem.actions.AXPress.perform();
-        _result = {success: true};
       } catch(e) {
+        axpressThrew = true;
+      }
+      if (axpressThrew) {
+        // AXPress 抛异常 → 坐标 fallback
         try {
-          var pos = elem.position();
-          var sz = elem.size();
-          var cx = pos[0] + sz[0] / 2;
-          var cy = pos[1] + sz[1] / 2;
-          ObjC.import('CoreGraphics');
-          var src = $.CGEventSourceCreate($.kCGEventSourceStateHIDSystemState);
-          var pt = $.CGPointMake(cx, cy);
-          var down = $.CGEventCreateMouseEvent(src, $.kCGEventLeftMouseDown, pt, $.kCGMouseButtonLeft);
-          $.CGEventPost($.kCGHIDEventTap, down);
-          var up = $.CGEventCreateMouseEvent(src, $.kCGEventLeftMouseUp, pt, $.kCGMouseButtonLeft);
-          $.CGEventPost($.kCGHIDEventTap, up);
-          _result = {success: true};
+          coordinateClick(elem);
+          _result = {success: true, method: "coordinate", verified: false};
         } catch(e2) {
           _result = {success: false, error: "Could not click element: " + String(e2.message || e2)};
         }
+      } else {
+        // AXPress 未抛异常：spin 等待异步生效，再采样签名判断是否真的生效
+        spinMs(80);
+        var sigAfter = stateSignature(elem);
+        if (sigBefore !== '' && sigAfter !== sigBefore) {
+          // 状态变化 → AXPress 生效
+          _result = {success: true, method: "axpress", verified: true};
+        } else if (sigBefore === '' && sigAfter === '') {
+          // 无可观测状态（纯按钮无 value/focused/selected）：无法 verify，
+          // 保守认为 AXPress 可能成功（不降级坐标，避免对正常按钮误伤）
+          _result = {success: true, method: "axpress", verified: false};
+        } else {
+          // 有可观测状态但无变化 → 静默吞，降级坐标
+          try {
+            coordinateClick(elem);
+            _result = {success: true, method: "coordinate", verified: false};
+          } catch(e3) {
+            _result = {success: false, error: "Could not click element (coordinate fallback): " + String(e3.message || e3)};
+          }
+        }
       }
     }
     JSON.stringify(_result);
@@ -73,9 +154,14 @@ export async function clickElement(elementId, app) {
                 ? new Error(result.error)
                 : new ElementNotFoundError(elementId);
         }
+        return {
+            method: result.method ?? "axpress",
+            verified: Boolean(result.verified),
+        };
     }
     catch (error) {
         rethrowElementActionError(error, "click_element", elementId);
+        return { method: "axpress", verified: false }; // unreachable — rethrow throws
     }
 }
 export async function typeInElement(elementId, text, app, clearFirst) {
@@ -372,7 +458,8 @@ export async function clickMenuBarExtra(app, selector = {}) {
     const host = target.host;
     const tgtNameLiteral = JSON.stringify(target.name || "");
     const tgtDescLiteral = JSON.stringify(target.description || "");
-    // AXPress，失败则坐标点击中心（与 clickElement 同模式，应对 Tauri 等静默吞）
+    const preferCoord = preferCoordinateClick(app);
+    // AXPress + verify-then-fallback（与 clickElement 同模式，应对 Tauri 等静默吞）。
     // host==="systemuiserver" 时在 SystemUIServer 进程上重定位（托盘 status item 由它托管），
     // SystemUIServer.menuBarItems 顺序不稳定，用保存的 name/description 二次匹配定位具体 item。
     // host==="self" 时按 app 进程的 menuBars()[mb].menuBarItems()[idx] 重定位（稳定）。
@@ -411,11 +498,14 @@ export async function clickMenuBarExtra(app, selector = {}) {
     var appName = ${appLiteral};
     var tgtName = ${tgtNameLiteral};
     var tgtDesc = ${tgtDescLiteral};
+    ${JXA_STATE_SIGNATURE}
+    ${JXA_COORDINATE_CLICK}
     // 容忍大小写/空格/连字符/下划线变体（cc-switch vs CC Switch vs cc_switch）
     var _norm = function(s) { return String(s||'').toLowerCase().split(' ').join('').split('-').join('').split('_').join(''); };
     var appNorm = _norm(appName);
     var tgtNameNorm = _norm(tgtName);
     var tgtDescNorm = _norm(tgtDesc);
+    var preferCoord = ${preferCoord ? "true" : "false"};
     var _matchApp = function(itemNorm) {
       if (!itemNorm) return false;
       return itemNorm === appNorm || itemNorm.indexOf(appNorm) !== -1 || appNorm.indexOf(itemNorm) !== -1;
@@ -430,21 +520,36 @@ export async function clickMenuBarExtra(app, selector = {}) {
       }
       ${resolveItemBlock}
       if (!_result && item) {
-        try {
-          item.actions.AXPress.perform();
-          _result = {success: true, method: "axpress"};
-        } catch(e) {
-          var pos = item.position();
-          var sz = item.size();
-          var cx = pos[0] + sz[0] / 2;
-          var cy = pos[1] + sz[1] / 2;
-          ObjC.import('CoreGraphics');
-          var pt = $.CGPointMake(cx, cy);
-          var down = $.CGEventCreateMouseEvent(null, $.kCGEventLeftMouseDown, pt, $.kCGMouseButtonLeft);
-          $.CGEventPost($.kCGHIDEventTap, down);
-          var up = $.CGEventCreateMouseEvent(null, $.kCGEventLeftMouseUp, pt, $.kCGMouseButtonLeft);
-          $.CGEventPost($.kCGHIDEventTap, up);
-          _result = {success: true, method: "coordinate", x: cx, y: cy};
+        if (preferCoord) {
+          // 启发式命中：直接坐标点击
+          coordinateClick(item);
+          _result = {success: true, method: "coordinate", verified: false};
+        } else {
+          // AXPress + verify
+          var sigBefore = stateSignature(item);
+          var axpressThrew = false;
+          try {
+            item.actions.AXPress.perform();
+          } catch(e) {
+            axpressThrew = true;
+          }
+          if (axpressThrew) {
+            coordinateClick(item);
+            _result = {success: true, method: "coordinate", verified: false};
+          } else {
+            spinMs(80);
+            var sigAfter = stateSignature(item);
+            if (sigBefore !== '' && sigAfter !== sigBefore) {
+              _result = {success: true, method: "axpress", verified: true};
+            } else if (sigBefore === '' && sigAfter === '') {
+              // 托盘 status item 通常无可观测状态（无 value/selected）；AXPress 开菜单的效果
+              // 难以从 item 本身验证。保守认为成功（菜单是否打开由后续 find_element 判断）。
+              _result = {success: true, method: "axpress", verified: false};
+            } else {
+              coordinateClick(item);
+              _result = {success: true, method: "coordinate", verified: false};
+            }
+          }
         }
       }
     } catch(e) {
@@ -458,10 +563,14 @@ export async function clickMenuBarExtra(app, selector = {}) {
     }
     catch (error) {
         rethrowElementActionError(error, "click_menu_bar_extra", app);
-        return; // unreachable
+        return { method: "axpress", verified: false }; // unreachable — rethrow throws
     }
     const result = JSON.parse(out);
     if (!result.success) {
         throw new Error(`click_menu_bar_extra failed in ${app}: ${result.error}`);
     }
+    return {
+        method: result.method ?? "axpress",
+        verified: Boolean(result.verified),
+    };
 }

package/dist/src/platform/macos/focus.d.ts

@@ -1,3 +1,13 @@
 import type { MacOSPlatform } from "./base.js";
+/**
+ * @deprecated Focus management is intentionally disabled. CGEvent input
+ * synthesis (click/type/key) works at the HID layer and does not require the
+ * target app to be frontmost, so stealing/restoring focus is unnecessary and
+ * could disrupt the user. `saveFocus`/`restoreFocus` are retained for API
+ * compatibility but are NOT called from the action pipeline — see the
+ * `not.toHaveBeenCalled()` assertions in `tools-layer.test.ts` that lock this
+ * disabled state. Do not wire these into new code; prefer CGEvent-based input.
+ */
 export declare function saveFocus(this: MacOSPlatform): Promise<void>;
+/** @deprecated See {@link saveFocus} — intentionally disabled, not called from the action pipeline. */
 export declare function restoreFocus(this: MacOSPlatform): Promise<void>;

package/dist/src/platform/macos/focus.js

@@ -1,4 +1,13 @@
 import { execFileSync } from "node:child_process";
+/**
+ * @deprecated Focus management is intentionally disabled. CGEvent input
+ * synthesis (click/type/key) works at the HID layer and does not require the
+ * target app to be frontmost, so stealing/restoring focus is unnecessary and
+ * could disrupt the user. `saveFocus`/`restoreFocus` are retained for API
+ * compatibility but are NOT called from the action pipeline — see the
+ * `not.toHaveBeenCalled()` assertions in `tools-layer.test.ts` that lock this
+ * disabled state. Do not wire these into new code; prefer CGEvent-based input.
+ */
 export async function saveFocus() {
     try {
         const apps = await this.listApps();
@@ -16,6 +25,7 @@ export async function saveFocus() {
         this.savedFocus = undefined;
     }
 }
+/** @deprecated See {@link saveFocus} — intentionally disabled, not called from the action pipeline. */
 export async function restoreFocus() {
     if (!this.savedFocus)
         return;

package/dist/src/platform/windows.d.ts

@@ -1,4 +1,4 @@
-import type { Platform, ScreenRegion, ScreenSize, CursorPosition, WindowInfo, WindowState, OcrResult, FindElementOptions, FindElementResponse } from "./base.js";
+import type { Platform, ScreenRegion, ScreenSize, CursorPosition, WindowInfo, WindowState, OcrResult, FindElementOptions, FindElementResponse, ClickResult } from "./base.js";
 export declare class WindowsPlatform implements Platform {
     screenshot(_display?: number, _region?: ScreenRegion): Promise<Buffer>;
     getScreenSize(_display?: number): ScreenSize;
@@ -13,7 +13,7 @@ export declare class WindowsPlatform implements Platform {
     key(_keys: string[]): Promise<void>;
     ocr(_display?: number, _region?: ScreenRegion): Promise<OcrResult>;
     findElement(_options: FindElementOptions): Promise<FindElementResponse>;
-    clickElement(_elementId: string, _app?: string): Promise<void>;
+    clickElement(_elementId: string, _app?: string): Promise<ClickResult>;
     typeInElement(_elementId: string, _text: string, _app?: string, _clearFirst?: boolean): Promise<void>;
     readClipboard(): Promise<string>;
     writeClipboard(text: string): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucu-mcp",
-  "version": "0.5.0",
+  "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.