diff --git a/cli/src/commands/mod.rs b/cli/src/commands/mod.rs
index 4c98a5b8..c3f6e15d 100644
--- a/cli/src/commands/mod.rs
+++ b/cli/src/commands/mod.rs
@@ -22,6 +22,7 @@ mod google;
 mod init;
 mod login;
 mod skills;
+mod test;
 mod tui;
 
 #[derive(Debug, Default)]
@@ -101,6 +102,8 @@ pub enum CommandGroup {
     Skills(skills::Skills),
     /// Start TUI session
     Tui,
+    /// This command group contains the commands to drive device simulators/emulators for app testing.
+    Test(test::Test),
 }
 
 impl ClapApp {
@@ -131,6 +134,7 @@ impl ClapApp {
                     .await
             }
             CommandGroup::Tui => handle_tui(channel).await,
+            CommandGroup::Test(test) => test.handle_command().await,
         };
 
         // Check for CLI updates:
@@ -186,7 +190,7 @@ fn get_context_without_application(clap_app: &ClapApp) -> Result<Context, WKCliE
 }
 
 #[cfg(test)]
-mod test {
+mod tests {
     use super::ClapApp;
 
     #[test]
diff --git a/cli/src/commands/test/ios/mod.rs b/cli/src/commands/test/ios/mod.rs
new file mode 100644
index 00000000..922062f1
--- /dev/null
+++ b/cli/src/commands/test/ios/mod.rs
@@ -0,0 +1,472 @@
+use std::path::PathBuf;
+use std::process::Stdio;
+
+use async_trait::async_trait;
+use serde::de::DeserializeOwned;
+use tokio::io::AsyncReadExt;
+use tokio::process::Command;
+
+use crate::error::{TestError, WKCliError};
+
+use super::platform::{Element, LayoutMap, PlatformBackend};
+
+/// The simClaw bash backend is vendored in `simclaw/` as a tree of files:
+/// a `bin/sim` entry point that sources the `lib/simclaw/*.sh` helpers, and
+/// a `swift/` subtree used by the inspection pipeline. We embed every file
+/// at compile time and extract the whole tree to disk before dispatching
+/// so the script's own `$SIM_LIB` resolution works unchanged.
+macro_rules! simclaw_files {
+    ($($rel:literal),+ $(,)?) => {
+        &[$(($rel, include_str!(concat!("simclaw/", $rel)))),+]
+    };
+}
+
+const SIMCLAW_FILES: &[(&str, &str)] = simclaw_files!(
+    "bin/sim",
+    "lib/simclaw/bootstrap.sh",
+    "lib/simclaw/coords.sh",
+    "lib/simclaw/core.sh",
+    "lib/simclaw/device.sh",
+    "lib/simclaw/inspect.sh",
+    "lib/simclaw/layout_map.sh",
+    "lib/simclaw/login.sh",
+    "lib/simclaw/misc.sh",
+    "lib/simclaw/nav.sh",
+    "lib/simclaw/setup.sh",
+    "lib/simclaw/touch.sh",
+    "lib/simclaw/type.sh",
+    "lib/simclaw/wait.sh",
+    "lib/simclaw/wda.sh",
+    "lib/simclaw/swift/pickwindow.swift",
+);
+
+const EXTRACT_SUBDIR: &str = "simclaw";
+const ENTRY_SCRIPT: &str = "bin/sim";
+const VERSION_MARKER: &str = ".wukong-version";
+
+/// Upstream simClaw applies `snapshotMaxDepth=15, snapshotMaxChildren=25` when
+/// creating the WDA session (see `lib/simclaw/wda.sh`). Those caps are too
+/// tight for anything larger than a hello-world screen — Settings.app's root
+/// alone has >25 children and the tree gets truncated before reaching the
+/// cells, so `layout-map` / `find-element` / `tap-on` return empty. Post
+/// permissive settings after the session is live. Remove this workaround
+/// when the upstream script raises (or exposes) the caps.
+const PERMISSIVE_SNAPSHOT_BODY: &str =
+    r#"{"settings":{"snapshotMaxDepth":60,"snapshotMaxChildren":200}}"#;
+
+pub struct IosBackend {
+    device: Option<String>,
+    source_timeout: Option<u32>,
+}
+
+impl IosBackend {
+    pub fn new(device: Option<String>, source_timeout: Option<u32>) -> Self {
+        Self {
+            device,
+            source_timeout,
+        }
+    }
+
+    /// Extract the bundled simClaw tree to `~/.config/wukong/scripts/simclaw/`
+    /// and return the path to its `bin/sim` entry script. A `.wukong-version`
+    /// marker lets us skip the 15 writes when the on-disk tree already matches
+    /// this build — upgrades still force a re-extract because the marker
+    /// disagrees. Only `bin/sim` needs the executable bit; the `.sh` helpers
+    /// are sourced, not invoked.
+    fn script_path() -> Result<PathBuf, WKCliError> {
+        let extract_err = |e: std::io::Error| {
+            WKCliError::TestError(TestError::ScriptExtractionFailed(e.to_string()))
+        };
+
+        let mut root = dirs::home_dir().ok_or_else(|| {
+            WKCliError::TestError(TestError::ScriptExtractionFailed(
+                "could not resolve home directory".into(),
+            ))
+        })?;
+        root.extend([".config", "wukong", "scripts", EXTRACT_SUBDIR]);
+        let entry = root.join(ENTRY_SCRIPT);
+        let marker = root.join(VERSION_MARKER);
+        let expected_version = env!("CARGO_PKG_VERSION");
+
+        if std::fs::read_to_string(&marker).ok().as_deref() == Some(expected_version)
+            && entry.exists()
+        {
+            return Ok(entry);
+        }
+
+        for (rel, contents) in SIMCLAW_FILES {
+            let dest = root.join(rel);
+            if let Some(parent) = dest.parent() {
+                std::fs::create_dir_all(parent).map_err(extract_err)?;
+            }
+            std::fs::write(&dest, contents).map_err(extract_err)?;
+        }
+
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            std::fs::set_permissions(&entry, std::fs::Permissions::from_mode(0o755))
+                .map_err(extract_err)?;
+        }
+
+        std::fs::write(&marker, expected_version).map_err(extract_err)?;
+
+        Ok(entry)
+    }
+
+    fn build_command(&self, subcommand: &str, args: &[String]) -> Result<Command, WKCliError> {
+        let script = Self::script_path()?;
+        let mut cmd = Command::new("bash");
+        cmd.arg(&script);
+        if let Some(device) = &self.device {
+            cmd.arg("--device").arg(device);
+        }
+        if let Some(t) = self.source_timeout {
+            cmd.arg("--source-timeout").arg(t.to_string());
+        }
+        cmd.arg(subcommand);
+        for a in args {
+            cmd.arg(a);
+        }
+        Ok(cmd)
+    }
+
+    /// `run_capture` is for commands whose stdout the Rust layer parses;
+    /// `run_streaming` is for commands whose output goes straight to the
+    /// user. Both forward stderr directly to the terminal.
+    async fn run_capture(&self, subcommand: &str, args: &[String]) -> Result<String, WKCliError> {
+        let mut cmd = self.build_command(subcommand, args)?;
+        cmd.stdout(Stdio::piped());
+        cmd.stderr(Stdio::inherit());
+
+        let mut child = cmd.spawn().map_err(WKCliError::Io)?;
+        let mut stdout = child
+            .stdout
+            .take()
+            .expect("stdout piped when building command");
+        let mut collected = String::new();
+        stdout
+            .read_to_string(&mut collected)
+            .await
+            .map_err(WKCliError::Io)?;
+
+        let status = child.wait().await.map_err(WKCliError::Io)?;
+        if !status.success() {
+            return Err(WKCliError::TestError(TestError::ScriptFailed {
+                subcommand: subcommand.to_string(),
+                exit_code: status.code(),
+            }));
+        }
+        Ok(collected)
+    }
+
+    async fn run_streaming(&self, subcommand: &str, args: &[String]) -> Result<(), WKCliError> {
+        let mut cmd = self.build_command(subcommand, args)?;
+        cmd.stdout(Stdio::inherit());
+        cmd.stderr(Stdio::inherit());
+        let status = cmd.status().await.map_err(WKCliError::Io)?;
+        if !status.success() {
+            return Err(WKCliError::TestError(TestError::ScriptFailed {
+                subcommand: subcommand.to_string(),
+                exit_code: status.code(),
+            }));
+        }
+        Ok(())
+    }
+
+    async fn run_json<T: DeserializeOwned>(
+        &self,
+        subcommand: &str,
+        args: &[String],
+    ) -> Result<T, WKCliError> {
+        let stdout = self.run_capture(subcommand, args).await?;
+        // Some compound script commands (e.g. tap-and-wait) print progress
+        // lines like "READY: <label>" on stdout before emitting the final
+        // JSON payload. Slice from the first `{` or `[` so the caller's
+        // deserializer sees only the structured tail.
+        let json_start = stdout.find(['{', '[']);
+        let payload = json_start
+            .map(|i| stdout[i..].trim())
+            .unwrap_or(stdout.trim());
+        serde_json::from_str::<T>(payload).map_err(|e| {
+            WKCliError::TestError(TestError::InvalidScriptOutput {
+                subcommand: subcommand.to_string(),
+                reason: e.to_string(),
+            })
+        })
+    }
+}
+
+fn opt(value: &Option<f64>) -> Option<String> {
+    value.map(|v| v.to_string())
+}
+
+/// Read the WDA session ID from whichever bootstrap cache the script wrote.
+/// Upstream simClaw occasionally keys the cache by `"default"` instead of the
+/// UDID, so we check both the UDID-keyed file and the `_default` fallback.
+fn read_wda_session() -> Option<String> {
+    let dir = std::path::Path::new("/tmp");
+    let entries = std::fs::read_dir(dir).ok()?;
+    for entry in entries.flatten() {
+        let name = entry.file_name();
+        let name = name.to_string_lossy();
+        if !name.starts_with("sim_bootstrap_cache_") || !name.ends_with(".json") {
+            continue;
+        }
+        let body = std::fs::read_to_string(entry.path()).ok()?;
+        let parsed: serde_json::Value = serde_json::from_str(&body).ok()?;
+        if let Some(session) = parsed.get("wda_session").and_then(|v| v.as_str()) {
+            if !session.is_empty() {
+                return Some(session.to_string());
+            }
+        }
+    }
+    None
+}
+
+/// Best-effort: raise WDA's snapshot caps so `layout-map` returns real trees
+/// on non-trivial apps. Silently no-ops if WDA isn't reachable yet — this is
+/// called as a post-setup nicety, not a hard requirement.
+async fn apply_permissive_snapshot_settings(port: u16) {
+    let Some(session) = read_wda_session() else {
+        return;
+    };
+    let url = format!("http://localhost:{port}/session/{session}/appium/settings");
+    let _ = reqwest::Client::new()
+        .post(&url)
+        .header("Content-Type", "application/json")
+        .body(PERMISSIVE_SNAPSHOT_BODY)
+        .timeout(std::time::Duration::from_secs(3))
+        .send()
+        .await;
+}
+
+#[async_trait]
+impl PlatformBackend for IosBackend {
+    async fn setup(&self, app: &str, port: u16) -> Result<(), WKCliError> {
+        self.run_streaming(
+            "setup",
+            &[app.to_string(), "--port".into(), port.to_string()],
+        )
+        .await?;
+        apply_permissive_snapshot_settings(port).await;
+        Ok(())
+    }
+
+    async fn wda_start(&self, port: u16) -> Result<(), WKCliError> {
+        self.run_streaming("wda-start", &[port.to_string()]).await?;
+        apply_permissive_snapshot_settings(port).await;
+        Ok(())
+    }
+
+    async fn status(&self) -> Result<(), WKCliError> {
+        self.run_streaming("status", &[]).await
+    }
+
+    async fn layout_map(&self) -> Result<LayoutMap, WKCliError> {
+        self.run_json("layout-map", &[]).await
+    }
+
+    async fn tap(&self, x: f64, y: f64) -> Result<(), WKCliError> {
+        self.run_streaming("tap", &[x.to_string(), y.to_string()])
+            .await
+    }
+
+    async fn tap_element(&self, label: &str) -> Result<(), WKCliError> {
+        self.run_streaming("tap-element", &[label.to_string()])
+            .await
+    }
+
+    async fn tap_and_wait(
+        &self,
+        label: &str,
+        expected: Option<&str>,
+        timeout: u32,
+    ) -> Result<LayoutMap, WKCliError> {
+        // nav.sh reads `expected` as `${2:-}`, so an empty string is the
+        // script's "skip expected" sentinel. Timeout must stay in $3.
+        let expected = expected.unwrap_or("");
+        self.run_json(
+            "tap-and-wait",
+            &[label.to_string(), expected.to_string(), timeout.to_string()],
+        )
+        .await
+    }
+
+    async fn swipe(
+        &self,
+        x1: f64,
+        y1: f64,
+        x2: f64,
+        y2: f64,
+        steps: u32,
+        step_ms: u32,
+    ) -> Result<(), WKCliError> {
+        self.run_streaming(
+            "swipe",
+            &[
+                x1.to_string(),
+                y1.to_string(),
+                x2.to_string(),
+                y2.to_string(),
+                steps.to_string(),
+                step_ms.to_string(),
+            ],
+        )
+        .await
+    }
+
+    async fn scroll_up(
+        &self,
+        x: Option<f64>,
+        from_y: Option<f64>,
+        to_y: Option<f64>,
+    ) -> Result<(), WKCliError> {
+        let args: Vec<String> = [opt(&x), opt(&from_y), opt(&to_y)]
+            .into_iter()
+            .flatten()
+            .collect();
+        self.run_streaming("scroll-up", &args).await
+    }
+
+    async fn scroll_down(
+        &self,
+        x: Option<f64>,
+        from_y: Option<f64>,
+        to_y: Option<f64>,
+    ) -> Result<(), WKCliError> {
+        let args: Vec<String> = [opt(&x), opt(&from_y), opt(&to_y)]
+            .into_iter()
+            .flatten()
+            .collect();
+        self.run_streaming("scroll-down", &args).await
+    }
+
+    async fn scroll_to_visible(&self, label: &str, max_swipes: u32) -> Result<(), WKCliError> {
+        self.run_streaming(
+            "scroll-to-visible",
+            &[label.to_string(), max_swipes.to_string()],
+        )
+        .await
+    }
+
+    async fn type_text(&self, text: &str) -> Result<(), WKCliError> {
+        self.run_streaming("type", &[text.to_string()]).await
+    }
+
+    async fn wait_for(&self, label: &str, timeout: u32) -> Result<(), WKCliError> {
+        self.run_streaming("wait-for", &[label.to_string(), timeout.to_string()])
+            .await
+    }
+
+    async fn wait_for_stable(&self, timeout: u32) -> Result<(), WKCliError> {
+        self.run_streaming("wait-for-stable", &[timeout.to_string()])
+            .await
+    }
+
+    async fn screen_title(&self) -> Result<String, WKCliError> {
+        let out = self.run_capture("screen-title", &[]).await?;
+        Ok(out.trim().to_string())
+    }
+
+    async fn find_element(&self, label: &str) -> Result<Element, WKCliError> {
+        self.run_json("find-element", &[label.to_string()]).await
+    }
+
+    async fn describe_point(&self, x: f64, y: f64) -> Result<serde_json::Value, WKCliError> {
+        self.run_json("describe-point", &[x.to_string(), y.to_string()])
+            .await
+    }
+
+    async fn describe(
+        &self,
+        depth: Option<u32>,
+        interactive: bool,
+    ) -> Result<serde_json::Value, WKCliError> {
+        let mut args = Vec::new();
+        if let Some(d) = depth {
+            args.push(d.to_string());
+        }
+        if interactive {
+            args.push("--interactive".into());
+        }
+        self.run_json("describe", &args).await
+    }
+
+    async fn screenshot(&self, output: &str) -> Result<(), WKCliError> {
+        self.run_streaming("screenshot", &[output.to_string()])
+            .await
+    }
+
+    async fn ensure_foreground_app(&self, bundle_id: Option<&str>) -> Result<(), WKCliError> {
+        let args: Vec<String> = bundle_id.map(|b| vec![b.to_string()]).unwrap_or_default();
+        self.run_streaming("ensure-foreground-app", &args).await
+    }
+
+    async fn cleanup(&self) -> Result<(), WKCliError> {
+        self.run_streaming("cleanup", &[]).await
+    }
+
+    async fn health_check(&self) -> Result<(), WKCliError> {
+        self.run_streaming("health-check", &[]).await
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::SIMCLAW_FILES;
+    use std::collections::HashSet;
+    use std::path::{Path, PathBuf};
+
+    /// Guards against re-vendoring drift: every file under `simclaw/` that
+    /// the script needs at runtime must be listed in `SIMCLAW_FILES`.
+    /// Upstream files not in the manifest would compile fine but fail at
+    /// runtime when `bin/sim` tries to source them.
+    #[test]
+    fn manifest_matches_tree() {
+        let root = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("src/commands/test/ios/simclaw");
+        let on_disk: HashSet<String> = collect_tree(&root, &root)
+            .into_iter()
+            .filter(|rel| is_runtime_file(rel))
+            .collect();
+        let in_manifest: HashSet<String> = SIMCLAW_FILES
+            .iter()
+            .map(|(rel, _)| rel.to_string())
+            .collect();
+
+        let missing_from_manifest: Vec<_> = on_disk.difference(&in_manifest).collect();
+        let missing_from_disk: Vec<_> = in_manifest.difference(&on_disk).collect();
+
+        assert!(
+            missing_from_manifest.is_empty() && missing_from_disk.is_empty(),
+            "SIMCLAW_FILES drifted from simclaw/ tree.\n  files on disk but not in manifest: {:?}\n  files in manifest but not on disk: {:?}",
+            missing_from_manifest,
+            missing_from_disk,
+        );
+    }
+
+    fn collect_tree(root: &Path, base: &Path) -> Vec<String> {
+        let mut out = Vec::new();
+        for entry in std::fs::read_dir(root).expect("read simclaw dir") {
+            let path = entry.expect("dir entry").path();
+            if path.is_dir() {
+                out.extend(collect_tree(&path, base));
+            } else {
+                let rel = path
+                    .strip_prefix(base)
+                    .expect("child under base")
+                    .to_str()
+                    .expect("simclaw paths must be valid UTF-8")
+                    .to_string();
+                out.push(rel);
+            }
+        }
+        out
+    }
+
+    /// Metadata files (VENDORED.md, revendor.sh, READMEs) are not runtime
+    /// inputs — they must NOT be in `SIMCLAW_FILES`.
+    fn is_runtime_file(rel: &str) -> bool {
+        rel.starts_with("bin/") || rel.starts_with("lib/")
+    }
+}
diff --git a/cli/src/commands/test/ios/simclaw/VENDORED.md b/cli/src/commands/test/ios/simclaw/VENDORED.md
new file mode 100644
index 00000000..c52f5cac
--- /dev/null
+++ b/cli/src/commands/test/ios/simclaw/VENDORED.md
@@ -0,0 +1,40 @@
+# Vendored simClaw
+
+This directory is a vendored copy of the simClaw bash backend — **do not
+edit files here directly.** Wukong's `test --platform ios` commands
+delegate to `bin/sim`, which is bundled into the Wukong binary via
+`include_str!` (see `../mod.rs`).
+
+## Upstream
+
+- **Repo:** https://github.com/mindvalley/mv-simclaw-ios
+- **Commit:** `572a587935b55acb234cafc969c37b1417b9b408`
+- **Ref:** `[fix] - Stage bundled skills + harden installer against existing symlinks (#2)`
+- **Vendored on:** 2026-05-11
+
+## Updating
+
+When the simClaw team cuts a new release:
+
+1. Pull the upstream repo to a local checkout.
+2. Run `./revendor.sh <path-to-homebrew-simClaw>` from this directory.
+3. Update the **Commit** and **Ref** lines above to the new SHA.
+4. Rebuild Wukong and run the command-group smoke (`wukong test --platform ios --help`) to confirm the manifest still matches the on-disk tree.
+5. If the re-vendor script reports new or removed files, update
+   `SIMCLAW_FILES` in `../mod.rs` to match — the build will fail via the
+   `manifest_matches_tree` test if you forget.
+
+## Contract boundaries
+
+The Rust layer assumes three stable contracts from the upstream script.
+Breaking any of these will silently misbehave or loudly fail, so flag
+them in PR review:
+
+| Contract | Where it's checked |
+|---|---|
+| Subcommand names exactly match the strings passed from `ios/mod.rs` | `PlatformBackend` impl call sites |
+| JSON shapes from `layout-map`, `find-element`, `describe`, `describe-point` match the structs in `../platform.rs` | `run_json` deserialization |
+| Non-zero exit codes mean the operation failed | `TestError::ScriptFailed` |
+
+If upstream changes any of those, fix the Rust side in the same PR that
+re-vendors.
diff --git a/cli/src/commands/test/ios/simclaw/bin/sim b/cli/src/commands/test/ios/simclaw/bin/sim
new file mode 100755
index 00000000..515c2068
--- /dev/null
+++ b/cli/src/commands/test/ios/simclaw/bin/sim
@@ -0,0 +1,449 @@
+#!/bin/bash
+# sim
+#
+# Standalone CLI tool for interacting with a running iOS Simulator.
+# Uses WebDriverAgent (WDA) for touch injection and xcrun simctl.
+# WDA runs inside each simulator via XCUITest, connected via UDID-scoped
+# testmanagerd socket — no window-focus dependency, parallel-tap safe.
+#
+# ── QUICK START FOR AI AGENTS ─────────────────────────────────────────────────
+#
+# STEP 0 — Start WDA (required once per simulator session, before any tap/swipe):
+#   sim --device <UDID> wda-start <port>
+#   WDA (WebDriverAgent) runs inside the simulator as an XCUITest runner.
+#   All taps and swipes are routed through WDA's W3C Actions API →
+#   XCTest → testmanagerd → synthetic IOHIDEvent. This is fully UDID-scoped
+#   (no window focus dependency) so parallel taps to different simulators work.
+#   Each simulator needs its own port (e.g. 8100, 8101). The session ID is
+#   cached automatically in /tmp/sim_bootstrap_cache_<UDID>.json.
+#   You do NOT need a global queue or serialization — taps are already isolated.
+#
+# STEP 1 — Call `layout-map` on any screen — it returns everything you need in
+#   one shot: screen title, back button, tab bar, all interactive elements,
+#   visible text, scroll hints, a context classifier, and suggested_actions
+#   with pre-validated labels ready for your next tap-and-wait call.
+#
+# STEP 2 — Use `tap-and-wait` to navigate in a single tool call:
+#   it finds the element by label, taps it, waits for the next screen,
+#   then returns a fresh layout-map of the resulting screen.
+#   This collapses find-element + tap + wait-for + layout-map into ONE call.
+#
+# STEP 3 — Batch all sequential commands into ONE Bash tool call using &&.
+#   Each separate Bash tool call costs ~10s of API round-trip latency on top
+#   of the ~1–2s the command itself takes. Batching 20 calls into 5 cuts
+#   total time from ~240s to ~60s.
+#
+# ── COMMON MISTAKES TO AVOID ──────────────────────────────────────────────────
+#
+# ✗ WRONG — using `screenshot` to inspect state:
+#   screenshot output is a PNG for human eyes. It tells YOU nothing actionable.
+#   Use `layout-map` instead — it gives structured JSON with labels, coordinates,
+#   scroll hints, and suggested_actions. It's always faster and more useful.
+#
+#   WRONG:  sim screenshot /tmp/s.png   ← then read the image to decide next step
+#   RIGHT:  sim layout-map              ← JSON tells you exactly what's on screen
+#
+# ✗ WRONG — verifying navigation with an intermediate screenshot:
+#   After `tap-element` or `tap-and-wait`, agents often take a screenshot to
+#   confirm the screen changed. This wastes 2 tool calls (Bash + Read).
+#   The tool output IS your confirmation:
+#     tap-element prints "NOTE: 'X' no longer visible — navigation likely succeeded"
+#     tap-and-wait returns the layout-map of the NEW screen directly
+#   No screenshot needed. Trust the output.
+#
+# ✗ WRONG — tapping an element that may not be on screen yet:
+#   `tap-element` searches WDA /source (viewport only). If the element is
+#   scrolled out of view, tap-element will FAIL. Always use `scroll-to-visible`
+#   first when unsure, then `tap-element`.
+#
+#   WRONG:  sim tap-element "Deep Sleep"         ← fails if off-screen
+#   RIGHT:  sim scroll-to-visible "Deep Sleep" && sim tap-element "Deep Sleep"
+#
+# ── OPTIMAL NAVIGATION PATTERN ────────────────────────────────────────────────
+#
+#   Goal: navigate to tab, tap a card that may be scrolled off-screen.
+#
+#   INEFFICIENT (observed: 7–9 tool calls):
+#     call 1: screenshot → Read image                    ← 2 calls wasted
+#     call 2: tap-element "Settings"
+#     call 3: screenshot → Read image                    ← 2 more calls wasted
+#     call 4: scroll-to-visible "Privacy"
+#     call 5: tap-element "Privacy"
+#     call 6: screenshot → Read image                    ← 2 more calls wasted
+#
+#   OPTIMAL (3 tool calls for the same result):
+#     call 1: sim layout-map                             ← see current state
+#     call 2: sim tap-and-wait "Settings" "Settings" 5 && \
+#             sim scroll-to-visible "Privacy" && \
+#             sim tap-and-wait "Privacy"                 ← navigate + scroll + tap, chained
+#     call 3: (only needed if you want to inspect the result screen)
+#             sim layout-map
+#
+#   Taps are UDID-scoped via WDA — no global serialization needed. Two simulators
+#   can receive taps concurrently without interfering with each other.
+#
+#   Use labels from suggested_actions in your tap-and-wait calls — they are
+#   pre-validated as present on screen and will match without fuzzy search.
+#
+# layout-map output schema:
+#   {
+#     "screen": "Account",          -- nav title; "~text" = heuristic; "unknown" = modal/sheet
+#     "modal": false,               -- true when no nav bar + close button present
+#     "navigation": {
+#       "title": "Account",
+#       "back": {"label":"Back","x":27,"y":76},       -- null if no back button
+#       "tabs": [{"label":"Home","x":39,"y":795,"selected":true}, ...]
+#     },
+#     "interactive": [              -- x,y are TOP-LEFT; tap center = x+w/2, y+h/2
+#       {"role":"AXButton","label":"Sign In","x":33,"y":234,"w":121,"h":40,"value":null,"enabled":true}
+#     ],
+#     "content": {
+#       "headings": ["Welcome"],
+#       "texts": ["Jane Smith", "Settings", ...]
+#     },
+#     "scroll": {
+#       "vertical": true,           -- true if scrollable content exists
+#       "horizontal": false,
+#       "above_fold": [],           -- labels of interactive/heading elements above current view
+#       "below_fold": ["Notifications","Privacy","Help"]  -- labels reachable by scrolling down
+#     },
+#     "context": "tab_screen",      -- screen type classifier:
+#                                   --   "media_player" | "modal_sheet" | "search" | "form"
+#                                   --   "tab_screen" | "list" | "detail_screen" | "unknown"
+#     "suggested_actions": [        -- pre-validated labels ready for tap-and-wait; prefer these
+#       "tap 'Sign In' at (93, 254)",
+#       "tap tab 'Home' at (196, 795)",
+#       "scroll down to reveal: Notifications, Help",
+#       "tap back 'Back' at (27, 76) to return"
+#     ]
+#   }
+#
+# Only split into separate Bash tool calls when you need to inspect output to
+# decide what to run next. Otherwise chain everything with &&.
+#
+# ─────────────────────────────────────────────────────────────────────────────
+#
+# Requirements:
+#   - Xcode Simulator running with a booted device
+#   - macOS Accessibility permission granted to Terminal/iTerm (System Settings > Privacy & Security > Accessibility)
+#   - xcrun (Xcode command-line tools)
+#   - jq (brew install jq)
+#   - swift (included with Xcode)
+
+set -euo pipefail
+
+# ── Resolve library directory ────────────────────────────────────────────────
+# Handles Homebrew symlinks, direct repo checkout, and curl install.
+_SIM_SELF="${BASH_SOURCE[0]}"
+while [[ -L "$_SIM_SELF" ]]; do
+  _SIM_LINK="$(readlink "$_SIM_SELF")"
+  if [[ "$_SIM_LINK" == /* ]]; then
+    _SIM_SELF="$_SIM_LINK"
+  else
+    _SIM_SELF="$(dirname "$_SIM_SELF")/$_SIM_LINK"
+  fi
+done
+_SIM_DIR="$(cd "$(dirname "$_SIM_SELF")" && pwd)"
+
+# Try: <bin>/../lib/simclaw (repo layout)
+# Then: <bin>/../share/simclaw/lib (Homebrew layout)
+if [[ -d "$_SIM_DIR/../lib/simclaw" ]]; then
+  SIM_LIB="$(cd "$_SIM_DIR/../lib/simclaw" && pwd)"
+elif [[ -d "$_SIM_DIR/../share/simclaw/lib" ]]; then
+  SIM_LIB="$(cd "$_SIM_DIR/../share/simclaw/lib" && pwd)"
+else
+  echo "ERROR: simclaw library not found. Expected at:" >&2
+  echo "  $_SIM_DIR/../lib/simclaw (repo)" >&2
+  echo "  $_SIM_DIR/../share/simclaw/lib (Homebrew)" >&2
+  exit 1
+fi
+export SIM_LIB
+
+# Always load core helpers (die, _is_integer)
+source "$SIM_LIB/core.sh"
+
+# ── Globals (populated by detect_* functions) ────────────────────────────────
+SIM_UDID=""
+SIM_NAME=""
+SIM_DEVICE_TYPE=""
+SIM_OS=""
+SIM_LOGICAL_W=""
+SIM_LOGICAL_H=""
+SIM_SCALE=""
+SIM_SCREEN_X=""
+SIM_SCREEN_Y=""
+SIM_SCREEN_W=""
+SIM_SCREEN_H=""
+SIM_ZOOM=""
+SIM_TARGET_UDID=""
+WDA_PORT=""
+WDA_SESSION=""
+# layout-map tuning: timeout (s) for the WDA /source fetch.
+# Large AX trees (e.g. Mindvalley) can exceed 8s; raise via --source-timeout N or env.
+LAYOUT_MAP_SOURCE_TIMEOUT="${LAYOUT_MAP_SOURCE_TIMEOUT:-8}"
+
+# ── Usage ────────────────────────────────────────────────────────────────────
+
+usage() {
+  cat <<'EOF'
+Usage: sim [--device <UDID>] <command> [args]
+
+Options:
+  --device <UDID>    Target a specific simulator by UDID (default: most recently booted)
+
+── START HERE (AI agents) ────────────────────────────────────────────────────
+
+  layout-map                              ★ Call this first on any screen. Returns a single
+                                            JSON snapshot: screen title, back button, tab bar,
+                                            all interactive elements (with top-left x,y,w,h),
+                                            visible text, below/above-fold scroll labels,
+                                            a "context" string classifying the screen type
+                                            (e.g. "media_player", "home", "settings"), and
+                                            "suggested_actions": an array of human-readable
+                                            strings like "tap 'Label' at (x, y)" and
+                                            "scroll down to reveal: ...".
+                                            Labels in suggested_actions are pre-validated as
+                                            present on screen — prefer them in your next
+                                            tap-and-wait call over labels you derive yourself.
+                                            Replaces screen-title + describe + find-element.
+
+  tap-and-wait <label> [expected] [secs]  ★ Compound navigation in one call. Finds element by
+                                            label, taps it, optionally waits for <expected>
+                                            element to appear (default timeout 10s), then
+                                            returns a full layout-map of the resulting screen.
+                                            Replaces find-element + tap + wait-for + layout-map
+                                            (4 separate calls → 1 call).
+                                            Usage: tap-and-wait "Sign In" "Home" 10
+                                            Example: tap-and-wait "View Profile" "Profile" 8
+
+── Interaction ───────────────────────────────────────────────────────────────
+
+  tap <x> <y>                             Tap at iOS logical coordinates
+  tap-element <label>                     Tap a UI element by its accessibility label
+  swipe <x1> <y1> <x2> <y2> [steps] [ms] Swipe between two points
+  scroll-up [x] [from_y] [to_y]          Scroll up (finger moves down = reveals content above)
+  scroll-down [x] [from_y] [to_y]        Scroll down (finger moves up = reveals content below)
+  scroll-to-visible <label> [max_swipes]  Scroll until element is visible (default 10 swipes)
+  type <text>                             Type text into focused field. Uses WDA setValue (preferred)
+                                          if WDA is running, else falls back to AX direct-value API
+
+── Waiting ───────────────────────────────────────────────────────────────────
+
+  wait-for <label> [timeout]              Block until element appears (default: 10s, event-driven)
+  wait-for-stable [timeout]              Block until UI stops changing (default: 5s)
+
+── Inspection (use when layout-map isn't enough) ─────────────────────────────
+
+  screen-title                            Current screen/nav title only
+  find-element <label>                    Find element by label → JSON {role,label,x,y,w,h} or exit 1
+  describe-point <x> <y>                  Hit-test AX element at coordinate → JSON (works on tab bars)
+  describe [depth] [--interactive|-i]     Dump AX tree as JSON; --interactive = buttons/links only
+  screenshot <output.png>                 Capture screen to PNG (use sparingly — prefer AX commands)
+
+── WDA (WebDriverAgent) ──────────────────────────────────────────────────────
+
+  setup <app_path_or_bundle_id>           ★ One-shot setup: boots simulator, builds WDA (if
+        [--port <wda_port>]               needed), installs app (if .app path given), starts
+                                          WDA, and launches the app. Run once to go from a
+                                          cold state to a fully interactive session.
+                                          If app_path ends in .app it is installed via simctl;
+                                          otherwise the argument is treated as a bundle ID
+                                          (app assumed already installed). Default port: 8100.
+                                          Requires /tmp/WebDriverAgent to be cloned first.
+                                          Usage: sim --device <UDID> setup /path/to/App.app
+                                                 sim --device <UDID> setup com.example.app --port 8101
+
+  wda-start [port]                        ★ REQUIRED before any tap or swipe command.
+                                          Starts WDA inside the target simulator using a
+                                          pre-built binary from /tmp/WDA_DerivedData_<iOS-X.Y>, then
+                                          creates a W3C session and caches the port + session
+                                          ID in /tmp/sim_bootstrap_cache_<UDID>.json.
+                                          Each simulator needs its own port (default 8100).
+                                          Run once per simulator session; subsequent taps
+                                          reuse the cached session automatically.
+                                          Usage: sim --device <UDID> wda-start 8100
+
+── Diagnostics ───────────────────────────────────────────────────────────────
+
+  status                                  Print booted device info and screen bounds
+  install-skills                          Copy bundled Claude Code skills to ~/.claude/skills/
+
+All x/y coordinates are iOS logical points.
+Tap center of a layout-map element: x + w/2, y + h/2
+
+── Agent pattern (fewest tool calls) ─────────────────────────────────────────
+
+  STARTING FROM SCRATCH (cold simulator or unknown state):
+
+  # Step 0 — one-shot setup: boots sim, builds WDA if needed, installs + launches app:
+  sim --device <UDID> setup /path/to/App.app
+  # or, if app is already installed:
+  sim --device <UDID> setup com.example.myapp --port 8100
+
+  STARTING FROM A WARM SESSION (sim already booted, app installed, WDA may be running):
+
+  # Step 0 — start WDA only (skip if setup was already run):
+  sim --device <UDID> wda-start 8100
+
+  THEN NAVIGATE (applies to both flows above):
+
+  # Step 1 — understand current screen (includes suggested_actions):
+  sim --device <UDID> layout-map
+
+  # Step 2 — navigate using tap-and-wait (find + tap + wait + read = 1 call):
+  sim --device <UDID> tap-and-wait "Sign In" "Home" 10
+
+  # Step 3 — navigate again using a label from the new layout-map's suggested_actions:
+  sim --device <UDID> tap-and-wait "View Profile" "Profile" 8
+
+  # tip: tap-and-wait + layout-map together enable compound navigation steps —
+  # each call does: find element + tap + wait for next screen + read new screen.
+  # This is 1 tool call instead of 4 (find-element + tap + wait-for + layout-map).
+
+  # When tap-and-wait is not suitable (e.g. raw coordinate tap), use:
+  sim --device <UDID> tap 35 81 && sim --device <UDID> wait-for "Next Screen" 10
+
+  RUNNING MULTIPLE SIMULATORS IN PARALLEL:
+
+  # Each simulator needs its own WDA port and its own --device flag:
+  sim --device <UDID1> setup com.example.myapp --port 8100
+  sim --device <UDID2> setup com.example.myapp --port 8101
+  # Tap commands to each simulator are fully independent (no global serialisation needed)
+
+EOF
+}
+
+# ── Main Dispatch ─────────────────────────────────────────────────────────────
+
+# Accept UDID env var as a shorthand for --device (e.g. UDID=<udid> bash sim <cmd>)
+[[ -z "$SIM_TARGET_UDID" && -n "${UDID:-}" ]] && SIM_TARGET_UDID="$UDID"
+
+# Parse optional --device and --source-timeout flags (in any order) before the command name
+while true; do
+  case "${1:-}" in
+    --device)
+      [[ $# -ge 2 ]] || die "Usage: sim --device <UDID> <command> [args]"
+      SIM_TARGET_UDID="$2"
+      shift 2
+      ;;
+    --source-timeout)
+      [[ $# -ge 2 ]] || die "--source-timeout requires a value in seconds"
+      LAYOUT_MAP_SOURCE_TIMEOUT="$2"
+      shift 2
+      ;;
+    *) break ;;
+  esac
+done
+
+CMD="${1:-}"
+shift || true  # 'shift' exits non-zero on empty args under set -e; || true guards this
+
+case "$CMD" in
+  layout-map)
+    source "$SIM_LIB/layout_map.sh"
+    cmd_layout_map "$@"
+    ;;
+  tap-and-wait)
+    source "$SIM_LIB/nav.sh"
+    cmd_tap_and_wait "$@"
+    ;;
+  tap)
+    source "$SIM_LIB/touch.sh"
+    cmd_tap "$@"
+    ;;
+  tap-element)
+    source "$SIM_LIB/nav.sh"
+    cmd_tap_element "$@"
+    ;;
+  swipe)
+    source "$SIM_LIB/touch.sh"
+    cmd_swipe "$@"
+    ;;
+  scroll-up)
+    source "$SIM_LIB/touch.sh"
+    cmd_scroll_up "$@"
+    ;;
+  scroll-down)
+    source "$SIM_LIB/touch.sh"
+    cmd_scroll_down "$@"
+    ;;
+  scroll-to-visible)
+    source "$SIM_LIB/touch.sh"
+    cmd_scroll_to_visible "$@"
+    ;;
+  type)
+    source "$SIM_LIB/type.sh"
+    cmd_type "$@"
+    ;;
+  wait-for)
+    source "$SIM_LIB/wait.sh"
+    cmd_wait_for "$@"
+    ;;
+  wait-for-stable)
+    source "$SIM_LIB/wait.sh"
+    cmd_wait_for_stable "$@"
+    ;;
+  describe)
+    source "$SIM_LIB/inspect.sh"
+    cmd_describe "$@"
+    ;;
+  screen-title)
+    source "$SIM_LIB/inspect.sh"
+    cmd_screen_title "$@"
+    ;;
+  find-element)
+    source "$SIM_LIB/inspect.sh"
+    cmd_find_element "$@"
+    ;;
+  describe-point)
+    source "$SIM_LIB/inspect.sh"
+    cmd_describe_point "$@"
+    ;;
+  screenshot)
+    source "$SIM_LIB/misc.sh"
+    cmd_screenshot "$@"
+    ;;
+  status)
+    source "$SIM_LIB/misc.sh"
+    cmd_status
+    ;;
+  setup)
+    source "$SIM_LIB/setup.sh"
+    cmd_setup "$@"
+    ;;
+  wda-start)
+    source "$SIM_LIB/wda.sh"
+    cmd_wda_start "$@"
+    ;;
+  ensure-foreground-app)
+    source "$SIM_LIB/misc.sh"
+    cmd_ensure_foreground_app "$@"
+    ;;
+  install-skills)
+    source "$SIM_LIB/misc.sh"
+    cmd_install_skills
+    ;;
+  cleanup)
+    source "$SIM_LIB/misc.sh"
+    cmd_cleanup
+    ;;
+  wda-session)
+    source "$SIM_LIB/misc.sh"
+    cmd_wda_session
+    ;;
+  health-check)
+    source "$SIM_LIB/misc.sh"
+    cmd_health_check
+    ;;
+  login)
+    source "$SIM_LIB/login.sh"
+    cmd_login "$@"
+    ;;
+  ""|--help|-h)
+    usage
+    exit 0
+    ;;
+  *)
+    die "Unknown command: $CMD. Run sim --help for usage."
+    ;;
+esac
diff --git a/cli/src/commands/test/ios/simclaw/lib/simclaw/bootstrap.sh b/cli/src/commands/test/ios/simclaw/lib/simclaw/bootstrap.sh
new file mode 100644
index 00000000..ca52d00e
--- /dev/null
+++ b/cli/src/commands/test/ios/simclaw/lib/simclaw/bootstrap.sh
@@ -0,0 +1,144 @@
+# lib/simclaw/bootstrap.sh — bootstrap, cache read/write
+[[ -n "${_SIM_BOOTSTRAP_LOADED:-}" ]] && return 0; _SIM_BOOTSTRAP_LOADED=1
+
+source "$SIM_LIB/device.sh"
+
+# ── Bootstrap Cache ──────────────────────────────────────────────────────────
+
+_write_bootstrap_cache() {
+  local cache_file="/tmp/sim_bootstrap_cache_${SIM_TARGET_UDID:-default}.json"
+  local win_pos
+  win_pos=$(osascript << APPLESCRIPT 2>/dev/null
+tell application "System Events"
+  tell process "Simulator"
+    set targetWindow to missing value
+    set simFullTitle to "${SIM_NAME} – ${SIM_OS}"
+    repeat with w in windows
+      set wName to name of w
+      if wName starts with simFullTitle then
+        set targetWindow to w
+        exit repeat
+      end if
+    end repeat
+    if targetWindow is missing value then set targetWindow to window 1
+    get position of targetWindow
+  end tell
+end tell
+APPLESCRIPT
+  )
+  local wx wy
+  wx=$(echo "$win_pos" | awk -F',' '{print $1}' | tr -d ' ')
+  wy=$(echo "$win_pos" | awk -F',' '{print $2}' | tr -d ' ')
+  # Read existing wda_port/wda_session from cache if present (preserve across re-bootstraps)
+  local existing_wda_port existing_wda_session
+  existing_wda_port=$(jq -r '.wda_port // ""' "$cache_file" 2>/dev/null || true)
+  existing_wda_session=$(jq -r '.wda_session // ""' "$cache_file" 2>/dev/null || true)
+  local wda_port_val="${WDA_PORT:-${existing_wda_port:-}}"
+  local wda_session_val="${WDA_SESSION:-${existing_wda_session:-}}"
+  cat > "$cache_file" << CACHEEOF
+{
+  "udid": "$SIM_UDID",
+  "name": "$SIM_NAME",
+  "device_type": "$SIM_DEVICE_TYPE",
+  "os": "$SIM_OS",
+  "logical_w": $SIM_LOGICAL_W,
+  "logical_h": $SIM_LOGICAL_H,
+  "scale": "$SIM_SCALE",
+  "screen_x": $SIM_SCREEN_X,
+  "screen_y": $SIM_SCREEN_Y,
+  "screen_w": $SIM_SCREEN_W,
+  "screen_h": $SIM_SCREEN_H,
+  "zoom": "$SIM_ZOOM",
+  "window_x": $wx,
+  "window_y": $wy,
+  "wda_port": "$wda_port_val",
+  "wda_session": "$wda_session_val"
+}
+CACHEEOF
+}
+
+_load_bootstrap_cache() {
+  local cache_file="/tmp/sim_bootstrap_cache_${SIM_TARGET_UDID:-default}.json"
+  [[ -f "$cache_file" ]] || return 1
+  # Validate UDID still booted
+  local cached_udid
+  cached_udid=$(jq -r '.udid' "$cache_file" 2>/dev/null)
+  [[ -n "$cached_udid" ]] || return 1
+  # If a specific device was requested, ensure the cache is for that device
+  if [[ -n "$SIM_TARGET_UDID" && "$cached_udid" != "$SIM_TARGET_UDID" ]]; then
+    return 1
+  fi
+  local state
+  state=$(plutil -extract state raw "$HOME/Library/Developer/CoreSimulator/Devices/$cached_udid/device.plist" 2>/dev/null)
+  [[ "$state" == "3" ]] || return 1
+  # Validate window hasn't moved
+  local cached_wx cached_wy
+  cached_wx=$(jq -r '.window_x' "$cache_file")
+  cached_wy=$(jq -r '.window_y' "$cache_file")
+  local cached_name cached_os
+  cached_name=$(jq -r '.name' "$cache_file")
+  cached_os=$(jq -r '.os' "$cache_file")
+  local current_pos
+  current_pos=$(osascript << APPLESCRIPT 2>/dev/null
+tell application "System Events"
+  tell process "Simulator"
+    set targetWindow to missing value
+    set simFullTitle to "${cached_name} – ${cached_os}"
+    repeat with w in windows
+      set wName to name of w
+      if wName starts with simFullTitle then
+        set targetWindow to w
+        exit repeat
+      end if
+    end repeat
+    if targetWindow is missing value then set targetWindow to window 1
+    get position of targetWindow
+  end tell
+end tell
+APPLESCRIPT
+  )
+  local cur_wx cur_wy
+  cur_wx=$(echo "$current_pos" | awk -F',' '{print $1}' | tr -d ' ')
+  cur_wy=$(echo "$current_pos" | awk -F',' '{print $2}' | tr -d ' ')
+  [[ "$cur_wx" == "$cached_wx" && "$cur_wy" == "$cached_wy" ]] || return 1
+  # Load all globals from cache
+  SIM_UDID=$(jq -r '.udid' "$cache_file")
+  SIM_NAME=$(jq -r '.name' "$cache_file")
+  SIM_DEVICE_TYPE=$(jq -r '.device_type' "$cache_file")
+  SIM_OS=$(jq -r '.os' "$cache_file")
+  SIM_LOGICAL_W=$(jq -r '.logical_w' "$cache_file")
+  SIM_LOGICAL_H=$(jq -r '.logical_h' "$cache_file")
+  SIM_SCALE=$(jq -r '.scale' "$cache_file")
+  SIM_SCREEN_X=$(jq -r '.screen_x' "$cache_file")
+  SIM_SCREEN_Y=$(jq -r '.screen_y' "$cache_file")
+  SIM_SCREEN_W=$(jq -r '.screen_w' "$cache_file")
+  SIM_SCREEN_H=$(jq -r '.screen_h' "$cache_file")
+  SIM_ZOOM=$(jq -r '.zoom' "$cache_file")
+  WDA_PORT=$(jq -r '.wda_port // ""' "$cache_file")
+  WDA_SESSION=$(jq -r '.wda_session // ""' "$cache_file")
+  return 0
+}
+
+_bootstrap() {
+  [[ -n "$SIM_UDID" ]] && return 0  # already bootstrapped this invocation
+  if _load_bootstrap_cache; then
+    return 0  # cache hit — skip all detection
+  fi
+  # Cache miss — run full detection and write cache
+  detect_device
+  lookup_logical_resolution
+  detect_screen_bounds
+  _write_bootstrap_cache
+}
+
+# Write only wda_port and wda_session into the existing cache file (patch in-place via jq).
+_wda_write_cache() {
+  local cache_file="/tmp/sim_bootstrap_cache_${SIM_TARGET_UDID:-default}.json"
+  [[ -f "$cache_file" ]] || die "_wda_write_cache: bootstrap cache missing — run bootstrap first"
+  local tmp
+  tmp=$(mktemp /tmp/sim_wda_cache_XXXXXX.json)
+  jq --arg port "$WDA_PORT" --arg session "$WDA_SESSION" \
+    '.wda_port = $port | .wda_session = $session' "$cache_file" > "$tmp" \
+    && mv "$tmp" "$cache_file" \
+    || { rm -f "$tmp"; die "_wda_write_cache: failed to update cache"; }
+}
diff --git a/cli/src/commands/test/ios/simclaw/lib/simclaw/coords.sh b/cli/src/commands/test/ios/simclaw/lib/simclaw/coords.sh
new file mode 100644
index 00000000..ad8c3085
--- /dev/null
+++ b/cli/src/commands/test/ios/simclaw/lib/simclaw/coords.sh
@@ -0,0 +1,43 @@
+# lib/simclaw/coords.sh — iOS logical ↔ macOS screen coordinate mapping
+[[ -n "${_SIM_COORDS_LOADED:-}" ]] && return 0; _SIM_COORDS_LOADED=1
+
+# _ios_to_screen <lx> <ly>
+# Converts iOS logical coordinates to macOS screen coordinates, accounting for device orientation.
+# Reads orientation from com.apple.iphonesimulator.plist using SIM_UDID (set by _bootstrap).
+# Outputs: "<sx> <sy>" space-separated macOS screen coordinates.
+_ios_to_screen() {
+  local lx="$1" ly="$2"
+  local orient
+  orient=$(plutil -extract "DevicePreferences.${SIM_UDID}.SimulatorWindowOrientation" raw \
+    ~/Library/Preferences/com.apple.iphonesimulator.plist 2>/dev/null || echo "Portrait")
+  case "$orient" in
+    PortraitUpsideDown)
+      awk "BEGIN { printf \"%d %d\", \
+        ${SIM_SCREEN_X} + int((${SIM_LOGICAL_W} - ${lx}) * ${SIM_ZOOM} + 0.5), \
+        ${SIM_SCREEN_Y} + int((${SIM_LOGICAL_H} - ${ly}) * ${SIM_ZOOM} + 0.5) }"
+      ;;
+    LandscapeLeft)
+      # iOS (lx, ly) -> macOS: originX + (logicalH - ly)*zoom, originY + lx*zoom
+      awk "BEGIN { printf \"%d %d\", \
+        ${SIM_SCREEN_X} + int((${SIM_LOGICAL_H} - ${ly}) * ${SIM_ZOOM} + 0.5), \
+        ${SIM_SCREEN_Y} + int(${lx} * ${SIM_ZOOM} + 0.5) }"
+      ;;
+    LandscapeRight)
+      # iOS (lx, ly) -> macOS: originX + ly*zoom, originY + (logicalW - lx)*zoom
+      awk "BEGIN { printf \"%d %d\", \
+        ${SIM_SCREEN_X} + int(${ly} * ${SIM_ZOOM} + 0.5), \
+        ${SIM_SCREEN_Y} + int((${SIM_LOGICAL_W} - ${lx}) * ${SIM_ZOOM} + 0.5) }"
+      ;;
+    *)  # Portrait (default)
+      awk "BEGIN { printf \"%d %d\", \
+        ${SIM_SCREEN_X} + int(${lx} * ${SIM_ZOOM} + 0.5), \
+        ${SIM_SCREEN_Y} + int(${ly} * ${SIM_ZOOM} + 0.5) }"
+      ;;
+  esac
+}
+
+# Keep backward-compat wrappers that use _ios_to_screen internally.
+# NOTE: these are only correct for Portrait orientation. Callers that need
+# accurate non-portrait coordinates should use _ios_to_screen directly.
+to_screen_x() { _ios_to_screen "$1" 0 | awk '{print $1}'; }
+to_screen_y() { _ios_to_screen 0 "$1" | awk '{print $2}'; }
diff --git a/cli/src/commands/test/ios/simclaw/lib/simclaw/core.sh b/cli/src/commands/test/ios/simclaw/lib/simclaw/core.sh
new file mode 100644
index 00000000..db2bcc38
--- /dev/null
+++ b/cli/src/commands/test/ios/simclaw/lib/simclaw/core.sh
@@ -0,0 +1,6 @@
+# lib/simclaw/core.sh — leaf helpers (no dependencies)
+[[ -n "${_SIM_CORE_LOADED:-}" ]] && return 0; _SIM_CORE_LOADED=1
+
+die() { echo "ERROR: $*" >&2; exit 1; }
+
+_is_integer() { [[ "$1" =~ ^-?[0-9]+$ ]]; }
diff --git a/cli/src/commands/test/ios/simclaw/lib/simclaw/device.sh b/cli/src/commands/test/ios/simclaw/lib/simclaw/device.sh
new file mode 100644
index 00000000..c03be5a2
--- /dev/null
+++ b/cli/src/commands/test/ios/simclaw/lib/simclaw/device.sh
@@ -0,0 +1,239 @@
+# lib/simclaw/device.sh — simulator device detection and screen bounds
+[[ -n "${_SIM_DEVICE_LOADED:-}" ]] && return 0; _SIM_DEVICE_LOADED=1
+
+# ── Device Detection ──────────────────────────────────────────────────────────
+
+detect_device() {
+  local json
+  json=$(xcrun simctl list devices --json 2>/dev/null) \
+    || die "xcrun simctl failed. Ensure Xcode command-line tools are installed."
+
+  # Find the target device: either by UDID (if --device was given) or the most recently booted.
+  local chosen_json
+  if [[ -n "$SIM_TARGET_UDID" ]]; then
+    chosen_json=$(echo "$json" | jq --arg udid "$SIM_TARGET_UDID" '
+      [
+        .devices
+        | to_entries[]
+        | .key as $runtime
+        | .value[]
+        | select(.udid == $udid)
+        | . + { runtime: $runtime }
+      ]
+      | first // empty
+    ' 2>/dev/null) || die "jq failed parsing simctl output."
+    [[ -n "$chosen_json" ]] && [[ "$chosen_json" != "null" ]] \
+      || die "No simulator found with UDID: $SIM_TARGET_UDID"
+  else
+    chosen_json=$(echo "$json" | jq '
+      [
+        .devices
+        | to_entries[]
+        | .key as $runtime
+        | .value[]
+        | select(.state == "Booted")
+        | . + { runtime: $runtime }
+      ]
+      | if length == 0 then empty
+        else (sort_by(.lastBootedAt // "") | last)
+        end
+    ' 2>/dev/null) || die "jq failed parsing simctl output. Ensure jq is installed (brew install jq)."
+    [[ -z "$chosen_json" ]] && die "No booted simulator found. Boot a simulator in Xcode first."
+  fi
+
+  IFS=$'\t' read -r SIM_UDID SIM_NAME SIM_DEVICE_TYPE < <(
+    echo "$chosen_json" | jq -r '[.udid, .name, .deviceTypeIdentifier] | @tsv'
+  )
+
+  # Convert runtime key to readable OS string: e.g.
+  # "com.apple.CoreSimulator.SimRuntime.iOS-18-2" → "iOS 18.2"
+  local raw_runtime
+  raw_runtime=$(echo "$chosen_json" | jq -r '.runtime')
+  SIM_OS=$(echo "$raw_runtime" \
+    | sed 's/com\.apple\.CoreSimulator\.SimRuntime\.//' \
+    | sed 's/-/ /g' \
+    | awk '{
+        os = $1
+        ver = ""
+        for (i=2; i<=NF; i++) {
+          if (i==2) ver = $i
+          else ver = ver "." $i
+        }
+        print os " " ver
+      }')
+}
+
+# ── Logical Resolution Lookup ─────────────────────────────────────────────────
+
+lookup_logical_resolution() {
+  local profiles_dir="/Library/Developer/CoreSimulator/Profiles/DeviceTypes"
+  [[ -d "$profiles_dir" ]] \
+    || die "CoreSimulator device profiles not found at: $profiles_dir"
+
+  local bundle_path=""
+  local candidate
+  for candidate in "$profiles_dir"/*.simdevicetype; do
+    [[ -d "$candidate" ]] || continue
+    local plist="$candidate/Contents/Info.plist"
+    [[ -f "$plist" ]] || continue
+    local identifier
+    identifier=$(plutil -extract CFBundleIdentifier raw "$plist" 2>/dev/null) || continue
+    if [[ "$identifier" == "$SIM_DEVICE_TYPE" ]]; then
+      bundle_path="$candidate"
+      break
+    fi
+  done
+
+  [[ -n "$bundle_path" ]] \
+    || die "Could not find device type profile for: $SIM_DEVICE_TYPE"
+
+  local profile_plist="$bundle_path/Contents/Resources/profile.plist"
+  [[ -f "$profile_plist" ]] \
+    || die "profile.plist not found in: $bundle_path/Contents/Resources/"
+
+  local px_w px_h scale
+  px_w=$(plutil -extract mainScreenWidth  raw "$profile_plist" 2>/dev/null | tr -d '[:space:]') \
+    || die "Could not read mainScreenWidth from profile.plist"
+  px_h=$(plutil -extract mainScreenHeight raw "$profile_plist" 2>/dev/null | tr -d '[:space:]') \
+    || die "Could not read mainScreenHeight from profile.plist"
+  scale=$(plutil -extract mainScreenScale raw "$profile_plist" 2>/dev/null | tr -d '[:space:]') \
+    || die "Could not read mainScreenScale from profile.plist"
+
+  [[ "$px_w" =~ ^[0-9]+$ ]] || die "mainScreenWidth is not a positive integer: '$px_w'"
+  [[ "$px_h" =~ ^[0-9]+$ ]] || die "mainScreenHeight is not a positive integer: '$px_h'"
+
+  SIM_SCALE="$scale"
+  SIM_LOGICAL_W=$(awk "BEGIN { printf \"%d\", $px_w / $scale }")
+  SIM_LOGICAL_H=$(awk "BEGIN { printf \"%d\", $px_h / $scale }")
+  [[ "$SIM_LOGICAL_W" -gt 0 && "$SIM_LOGICAL_H" -gt 0 ]] \
+    || die "Invalid logical resolution computed: ${SIM_LOGICAL_W}x${SIM_LOGICAL_H}"
+}
+
+# ── Screen Bounds Detection ───────────────────────────────────────────────────
+
+detect_screen_bounds() {
+  pgrep -x Simulator > /dev/null 2>&1 \
+    || die "Simulator.app is not running. Launch the Simulator from Xcode first."
+
+  local applescript_result
+  applescript_result=$(osascript << APPLESCRIPT 2>/dev/null
+tell application "System Events"
+  tell process "Simulator"
+    -- Find the target window by matching the full title "Name – OS" (e.g. "iPhone 16 – iOS 18.1")
+    -- This distinguishes two simulators of the same model running different OS versions.
+    set targetWindow to missing value
+    set simFullTitle to "${SIM_NAME} – ${SIM_OS}"
+    repeat with w in windows
+      set wName to name of w
+      if wName starts with simFullTitle then
+        set targetWindow to w
+        exit repeat
+      end if
+    end repeat
+    if targetWindow is missing value then set targetWindow to window 1
+
+    -- Find screen element: ratio-match direct children, then try to go one level deeper
+    -- to get inside the bezel frame to the actual screen surface
+    -- Support both portrait (W/H) and landscape (H/W) orientations
+    set portraitRatio to ${SIM_LOGICAL_W} / ${SIM_LOGICAL_H}
+    set landscapeRatio to ${SIM_LOGICAL_H} / ${SIM_LOGICAL_W}
+    set bestEl to missing value
+    set bestScore to 999
+
+    repeat with el in UI elements of targetWindow
+      try
+        set elSz to size of el
+        set elW to item 1 of elSz
+        set elH to item 2 of elSz
+        if elW > 100 and elH > 100 then
+          set ratio to elW / elH
+          -- Check against portrait ratio
+          set diff to ratio - portraitRatio
+          if diff < 0 then set diff to -diff
+          -- Also check against landscape ratio
+          set ldiff to ratio - landscapeRatio
+          if ldiff < 0 then set ldiff to -ldiff
+          if ldiff < diff then set diff to ldiff
+          if diff < bestScore then
+            set bestScore to diff
+            set bestEl to el
+          end if
+        end if
+      end try
+    end repeat
+
+    if bestEl is missing value then
+      return "ERROR: Could not find screen element in Simulator accessibility tree"
+    end if
+    if bestScore > 0.05 then
+      return "ERROR: Best matching element ratio diff " & bestScore & " exceeds threshold"
+    end if
+
+    -- Try to descend one level: find a child whose aspect ratio is also within 5%
+    -- This moves us from the bezel frame into the actual screen surface
+    try
+      repeat with child in UI elements of bestEl
+        try
+          set cSz to size of child
+          set cW to item 1 of cSz
+          set cH to item 2 of cSz
+          if cW > 50 and cH > 50 then
+            set cRatio to cW / cH
+            set cDiff to cRatio - portraitRatio
+            if cDiff < 0 then set cDiff to -cDiff
+            set cLDiff to cRatio - landscapeRatio
+            if cLDiff < 0 then set cLDiff to -cLDiff
+            if cLDiff < cDiff then set cDiff to cLDiff
+            if cDiff < 0.05 then
+              set bestEl to child
+              exit repeat
+            end if
+          end if
+        end try
+      end repeat
+    end try
+
+    set screenPos to position of bestEl
+    set screenSz to size of bestEl
+    set px to (item 1 of screenPos) as integer
+    set py to (item 2 of screenPos) as integer
+    set pw to (item 1 of screenSz) as integer
+    set ph to (item 2 of screenSz) as integer
+    return (px as text) & "," & (py as text) & "," & (pw as text) & "," & (ph as text)
+  end tell
+end tell
+APPLESCRIPT
+  )
+
+  if [[ -z "$applescript_result" ]] || [[ "$applescript_result" == ERROR:* ]]; then
+    die "AppleScript failed to detect screen bounds. Ensure Terminal has Accessibility permission in System Settings > Privacy & Security > Accessibility. Detail: ${applescript_result:-empty response}"
+  fi
+
+  SIM_SCREEN_X=$(echo "$applescript_result" | cut -d',' -f1 | tr -d ' ')
+  SIM_SCREEN_Y=$(echo "$applescript_result" | cut -d',' -f2 | tr -d ' ')
+  SIM_SCREEN_W=$(echo "$applescript_result" | cut -d',' -f3 | tr -d ' ')
+  SIM_SCREEN_H=$(echo "$applescript_result" | cut -d',' -f4 | tr -d ' ')
+
+  # In landscape mode (screen_w > screen_h), the device is rotated so the macOS
+  # screen width corresponds to iOS logical height (and vice versa). Compute zoom
+  # from the axis that is larger in both spaces to get the correct scale factor.
+  local orient_for_zoom
+  orient_for_zoom=$(plutil -extract "DevicePreferences.${SIM_UDID}.SimulatorWindowOrientation" raw \
+    ~/Library/Preferences/com.apple.iphonesimulator.plist 2>/dev/null || echo "Portrait")
+  case "$orient_for_zoom" in
+    LandscapeLeft|LandscapeRight)
+      SIM_ZOOM=$(awk "BEGIN { printf \"%.4f\", $SIM_SCREEN_W / $SIM_LOGICAL_H }")
+      ;;
+    *)
+      SIM_ZOOM=$(awk "BEGIN { printf \"%.4f\", $SIM_SCREEN_W / $SIM_LOGICAL_W }")
+      ;;
+  esac
+
+  # Sanity check: screen dimensions must be non-zero and zoom must be plausible
+  [[ "$SIM_SCREEN_W" -gt 0 && "$SIM_SCREEN_H" -gt 0 ]] \
+    || die "AppleScript returned invalid screen size: ${SIM_SCREEN_W}x${SIM_SCREEN_H}. The Simulator window accessibility tree may have changed — try restarting Simulator."
+  local zoom_ok
+  zoom_ok=$(awk "BEGIN { z=${SIM_ZOOM}; print (z >= 0.4 && z <= 6.0) ? \"ok\" : \"bad\" }")
+  [[ "$zoom_ok" == "ok" ]] \
+    || die "Computed zoom factor ${SIM_ZOOM} is outside plausible range (0.4–6.0). Screen bounds detection likely failed."
+}
diff --git a/cli/src/commands/test/ios/simclaw/lib/simclaw/inspect.sh b/cli/src/commands/test/ios/simclaw/lib/simclaw/inspect.sh
new file mode 100644
index 00000000..199cd1ed
--- /dev/null
+++ b/cli/src/commands/test/ios/simclaw/lib/simclaw/inspect.sh
@@ -0,0 +1,711 @@
+# lib/simclaw/inspect.sh — AX tree inspection commands
+[[ -n "${_SIM_INSPECT_LOADED:-}" ]] && return 0; _SIM_INSPECT_LOADED=1
+
+source "$SIM_LIB/bootstrap.sh"
+source "$SIM_LIB/coords.sh"
+
+cmd_describe() {
+  # max_depth arg kept for API compatibility but ignored — Swift AX traversal
+  # uses its own depth limit (25 levels) which is sufficient for all known screens.
+  local interactive_only=false
+  local max_depth="3"
+  for arg in "$@"; do
+    case "$arg" in
+      --interactive|-i) interactive_only=true ;;
+      [0-9]*)           max_depth="$arg" ;;
+    esac
+  done
+  _bootstrap
+
+  # Use Swift + AXUIElement API for fast, reliable UI element enumeration.
+  # This avoids the AppleScript 'entire contents' approach which is O(n) IPC-slow
+  # and degrades severely on deep trees (>100 elements takes minutes in AppleScript).
+  local scrX="$SIM_SCREEN_X"
+  local scrY="$SIM_SCREEN_Y"
+  local zoom="$SIM_ZOOM"
+
+  swift - "$scrX" "$scrY" "$zoom" "$interactive_only" "${SIM_NAME} – ${SIM_OS}" 2>/dev/null << SWIFTEOF
+import ApplicationServices
+import AppKit
+import Foundation
+
+let args = CommandLine.arguments
+let screenX       = Double(args.count > 1 ? args[1] : "-439") ?? -439.0
+let screenY       = Double(args.count > 2 ? args[2] : "148") ?? 148.0
+let zoom          = Double(args.count > 3 ? args[3] : "1.0") ?? 1.0
+let interactiveOnly = (args.count > 4 && args[4] == "true")
+let deviceName    = args.count > 5 ? args[5] : ""
+let interactiveRoles: Set<String> = [
+    "AXButton", "AXTextField", "AXSecureTextField", "AXLink",
+    "AXSwitch", "AXCheckBox", "AXRadioButton", "AXSlider", "AXMenuItem"
+]
+
+// Find Simulator PID
+guard let simApp = NSWorkspace.shared.runningApplications
+    .first(where: { \$0.bundleIdentifier == "com.apple.iphonesimulator" }) else {
+  print("[]"); exit(0)
+}
+let simPID = simApp.processIdentifier
+
+let axApp = AXUIElementCreateApplication(simPID)
+var windowsRef: CFTypeRef?
+AXUIElementCopyAttributeValue(axApp, kAXWindowsAttribute as CFString, &windowsRef)
+guard let windows = windowsRef as? [AXUIElement], !windows.isEmpty else {
+  print("[]"); exit(0)
+}
+
+$(cat "$SIM_LIB/swift/pickwindow.swift")
+
+guard let win = pickWindow(windows, screenX: screenX, screenY: screenY, deviceName: deviceName) else {
+  print("[]"); exit(0)
+}
+
+func getAttr(_ el: AXUIElement, _ attr: String) -> AnyObject? {
+    var val: CFTypeRef?
+    guard AXUIElementCopyAttributeValue(el, attr as CFString, &val) == .success else { return nil }
+    return val as AnyObject
+}
+
+func getPosition(_ el: AXUIElement) -> CGPoint? {
+    guard let val = getAttr(el, kAXPositionAttribute) else { return nil }
+    var pt = CGPoint.zero
+    guard AXValueGetValue(val as! AXValue, .cgPoint, &pt) else { return nil }
+    return pt
+}
+
+func getSize(_ el: AXUIElement) -> CGSize? {
+    guard let val = getAttr(el, kAXSizeAttribute) else { return nil }
+    var sz = CGSize.zero
+    guard AXValueGetValue(val as! AXValue, .cgSize, &sz) else { return nil }
+    return sz
+}
+
+func getLabel(_ el: AXUIElement) -> String {
+    if let d = getAttr(el, kAXDescriptionAttribute) as? String, !d.isEmpty { return d }
+    if let t = getAttr(el, kAXTitleAttribute) as? String, !t.isEmpty { return t }
+    if let v = getAttr(el, kAXValueAttribute) as? String, !v.isEmpty { return v }
+    return ""
+}
+
+func getRole(_ el: AXUIElement) -> String {
+    return (getAttr(el, kAXRoleAttribute) as? String) ?? ""
+}
+
+var results: [String] = []
+
+func enumerate(_ el: AXUIElement, depth: Int = 0) {
+    guard depth < 25 else { return }
+
+    let pos = getPosition(el)
+    let sz  = getSize(el)
+    let label = getLabel(el)
+    let role  = getRole(el)
+
+    if let p = pos, let s = sz, s.width >= 5, s.height >= 5 {
+        let lx = Int(round((p.x - screenX) / zoom))
+        let ly = Int(round((p.y - screenY) / zoom))
+        let lw = Int(round(s.width / zoom))
+        let lh = Int(round(s.height / zoom))
+        if !role.isEmpty || !label.isEmpty {
+            if !interactiveOnly || interactiveRoles.contains(role) {
+                let safeLabel = label
+                    .replacingOccurrences(of: "\\\\", with: "\\\\\\\\")
+                    .replacingOccurrences(of: "\"", with: "\\\\\\"")
+                results.append(
+                    "{\"role\":\"\(role)\",\"label\":\"\(safeLabel)\",\"x\":\(lx),\"y\":\(ly),\"w\":\(lw),\"h\":\(lh)}"
+                )
+            }
+        }
+    }
+
+    // Fetch children — for Tab Bar groups, also probe AXTabs (UITabBarButton items
+    // are not exposed via kAXChildrenAttribute on the iOS Simulator AX bridge)
+    var childrenRef: CFTypeRef?
+    AXUIElementCopyAttributeValue(el, kAXChildrenAttribute as CFString, &childrenRef)
+    var children = (childrenRef as? [AXUIElement]) ?? []
+
+    if children.isEmpty && role == "AXGroup" && label == "Tab Bar" {
+        var tabsRef: CFTypeRef?
+        AXUIElementCopyAttributeValue(el, "AXTabs" as CFString, &tabsRef)
+        if let tabs = tabsRef as? [AXUIElement] {
+            children = tabs
+        }
+    }
+
+    for child in children {
+        enumerate(child, depth: depth + 1)
+    }
+}
+
+enumerate(win)
+print("[\(results.joined(separator: ","))]")
+SWIFTEOF
+}
+
+cmd_screen_title() {
+  _bootstrap
+  swift - "${SIM_SCREEN_X}" "${SIM_SCREEN_Y}" "${SIM_SCREEN_W}" "${SIM_ZOOM}" "${SIM_NAME} – ${SIM_OS}" << SWIFTEOF 2>/dev/null
+import Cocoa
+import ApplicationServices
+
+let args = CommandLine.arguments
+let screenX  = Double(args.count > 1 ? args[1] : "0") ?? 0.0
+let screenY  = Double(args.count > 2 ? args[2] : "0") ?? 0.0
+let screenW  = Double(args.count > 3 ? args[3] : "393") ?? 393.0
+let zoom     = Double(args.count > 4 ? args[4] : "1.0") ?? 1.0
+let deviceName = args.count > 5 ? args[5] : ""
+
+func getAttribute(_ el: AXUIElement, _ attr: String) -> CFTypeRef? {
+    var v: CFTypeRef?
+    AXUIElementCopyAttributeValue(el, attr as CFString, &v)
+    return v
+}
+
+func getRole(_ el: AXUIElement) -> String {
+    return (getAttribute(el, "AXRole") as? String) ?? ""
+}
+
+func getRoleDesc(_ el: AXUIElement) -> String {
+    return (getAttribute(el, "AXRoleDescription") as? String) ?? ""
+}
+
+func getTitle(_ el: AXUIElement) -> String {
+    for attr in ["AXTitle", "AXLabel", "AXDescription", "AXValue"] {
+        if let v = getAttribute(el, attr) as? String, !v.isEmpty { return v }
+    }
+    return ""
+}
+
+func getPosition(_ el: AXUIElement) -> CGPoint? {
+    guard let posVal = getAttribute(el, "AXPosition") else { return nil }
+    var pt = CGPoint.zero
+    guard AXValueGetValue(posVal as! AXValue, .cgPoint, &pt) else { return nil }
+    return pt
+}
+
+func getSize(_ el: AXUIElement) -> CGSize? {
+    guard let sizeVal = getAttribute(el, "AXSize") else { return nil }
+    var sz = CGSize.zero
+    guard AXValueGetValue(sizeVal as! AXValue, .cgSize, &sz) else { return nil }
+    return sz
+}
+
+guard let app = NSRunningApplication.runningApplications(
+    withBundleIdentifier: "com.apple.iphonesimulator").first else {
+    print("unknown"); exit(0)
+}
+let axApp = AXUIElementCreateApplication(app.processIdentifier)
+guard let windows = getAttribute(axApp, "AXWindows") as? [AXUIElement],
+      !windows.isEmpty else {
+    print("unknown"); exit(0)
+}
+
+$(cat "$SIM_LIB/swift/pickwindow.swift")
+
+guard let window = pickWindow(windows, screenX: screenX, screenY: screenY, deviceName: deviceName) else {
+    print("unknown"); exit(0)
+}
+
+// Depth-first search for a navigation bar element.
+// Matches both UIKit (AXNavigationBar) and SwiftUI (AXGroup with AXRoleDescription="Nav bar").
+// Returns the nav bar element if found.
+func findNavBar(_ el: AXUIElement, _ depth: Int) -> AXUIElement? {
+    if depth < 0 { return nil }
+    let role = getRole(el)
+    if role == "AXNavigationBar" { return el }
+    if role == "AXGroup" && getRoleDesc(el) == "Nav bar" { return el }
+    guard let children = getAttribute(el, "AXChildren") as? [AXUIElement] else { return nil }
+    for child in children {
+        if let found = findNavBar(child, depth - 1) { return found }
+    }
+    return nil
+}
+
+// Search up to 25 levels deep for a navigation bar
+if let navBar = findNavBar(window, 25) {
+    // Strategy 1: child AXStaticText or AXHeading of the nav bar via kAXChildrenAttribute
+    if let children = getAttribute(navBar, "AXChildren") as? [AXUIElement] {
+        for child in children {
+            let r = getRole(child)
+            if r == "AXStaticText" || r == "AXHeading" {
+                let t = getTitle(child)
+                if !t.isEmpty { print(t); exit(0) }
+            }
+        }
+    }
+
+    // Strategy 2: probe the center of the nav bar using AXUIElementCopyElementAtPosition.
+    // iOS Simulator's AX bridge sometimes omits nav title children from kAXChildrenAttribute
+    // but the element IS hit-testable at its screen position.
+    if let pos = getPosition(navBar), let sz = getSize(navBar) {
+        // Sample a few points across the center of the nav bar to find the title
+        let centerY = Float(pos.y + sz.height / 2)
+        let sampleXs: [Float] = [
+            Float(pos.x + sz.width * 0.5),   // center
+            Float(pos.x + sz.width * 0.35),  // slight left of center
+            Float(pos.x + sz.width * 0.65),  // slight right of center
+        ]
+        for sampleX in sampleXs {
+            var hitEl: AXUIElement?
+            let err = AXUIElementCopyElementAtPosition(axApp, sampleX, centerY, &hitEl)
+            if err == .success, let el = hitEl {
+                let r = getRole(el)
+                // Accept AXStaticText or AXHeading; skip the nav bar group itself
+                if r == "AXStaticText" || r == "AXHeading" {
+                    let t = getTitle(el)
+                    if !t.isEmpty { print(t); exit(0) }
+                }
+            }
+        }
+    }
+
+    // Strategy 3: nav bar's own AX label (rare but possible)
+    let title = getTitle(navBar)
+    if !title.isEmpty { print(title); exit(0) }
+}
+
+// No nav bar found — probe the top ~100pt band of the screen with hit-testing.
+// This catches screens with inline/large title navigation or custom headers.
+let navBandTop    = Float(screenY + 40 * zoom)
+let navBandBottom = Float(screenY + 110 * zoom)
+let centerX       = Float(screenX + screenW / 2)
+let probeYs: [Float] = [
+    Float((Double(navBandTop) + Double(navBandBottom)) / 2),
+    navBandTop + Float(10 * zoom),
+    navBandBottom - Float(10 * zoom),
+]
+for probeY in probeYs {
+    var hitEl: AXUIElement?
+    let err = AXUIElementCopyElementAtPosition(axApp, centerX, probeY, &hitEl)
+    if err == .success, let el = hitEl {
+        let r = getRole(el)
+        if r == "AXStaticText" || r == "AXHeading" {
+            let t = getTitle(el)
+            if !t.isEmpty && t.count > 1 { print(t); exit(0) }
+        }
+    }
+}
+
+// Last resort: AXHeading in the top-300pt band via tree walk
+func findTopHeading(_ el: AXUIElement, _ depth: Int) -> String? {
+    if depth < 0 { return nil }
+    if getRole(el) == "AXHeading" {
+        if let pos = getPosition(el) {
+            if pos.y < CGFloat(screenY + 300 * zoom) {
+                let t = getTitle(el)
+                if !t.isEmpty { return t }
+            }
+        }
+    }
+    guard let children = getAttribute(el, "AXChildren") as? [AXUIElement] else { return nil }
+    for child in children {
+        if let found = findTopHeading(child, depth - 1) { return found }
+    }
+    return nil
+}
+
+if let title = findTopHeading(window, 25) {
+    print(title)
+    exit(0)
+}
+
+// Strategy 5: Broadened scan — topmost prominent AXStaticText in top 200pt
+// Returns with ~ prefix to signal heuristic match
+func findProminentText(_ el: AXUIElement, _ depth: Int) -> (String, CGFloat, CGFloat)? {
+    if depth < 0 { return nil }
+    let role = getRole(el)
+    if role == "AXStaticText" || role == "AXHeading" {
+        if let pos = getPosition(el), let sz = getSize(el) {
+            if pos.y >= CGFloat(screenY + 40 * zoom) &&
+               pos.y < CGFloat(screenY + 300 * zoom) && sz.height >= 14 {
+                let t = getTitle(el)
+                if !t.isEmpty && t.count >= 3 { return (t, pos.y, sz.height) }
+            }
+        }
+    }
+    guard let children = getAttribute(el, "AXChildren") as? [AXUIElement] else { return nil }
+    var best: (String, CGFloat, CGFloat)? = nil
+    for child in children {
+        if let found = findProminentText(child, depth - 1) {
+            if best == nil || found.1 < best!.1 || (found.1 == best!.1 && found.2 > best!.2) {
+                best = found
+            }
+        }
+    }
+    return best
+}
+
+if let (text, _, _) = findProminentText(window, 25) {
+    print("~\(text)")
+    exit(0)
+}
+
+print("unknown")
+SWIFTEOF
+}
+
+cmd_find_element() {
+  [[ $# -ge 1 ]] || die "Usage: sim find-element <label>"
+  local search_label="$1"
+  _bootstrap
+
+  local resp element_id
+
+  # 1. Try exact accessibility id match
+  resp=$(curl -s -X POST "http://localhost:${WDA_PORT}/session/${WDA_SESSION}/elements" \
+    -H 'Content-Type: application/json' \
+    -d "{\"using\": \"accessibility id\", \"value\": \"${search_label}\"}" 2>/dev/null)
+
+  element_id=$(echo "$resp" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    els = data.get('value', [])
+    if els:
+        print(els[0].get('ELEMENT', ''))
+except: pass
+" 2>/dev/null)
+
+  # 2. If not found, try case-insensitive xpath partial match on @name or @label
+  if [[ -z "$element_id" ]]; then
+    local lower_label
+    lower_label=$(echo "$search_label" | tr '[:upper:]' '[:lower:]')
+    resp=$(curl -s -X POST "http://localhost:${WDA_PORT}/session/${WDA_SESSION}/elements" \
+      -H 'Content-Type: application/json' \
+      -d "{\"using\": \"xpath\", \"value\": \"//*[contains(translate(@name,'ABCDEFGHIJKLMNOPQRSTUVWXYZ','abcdefghijklmnopqrstuvwxyz'),'${lower_label}') or contains(translate(@label,'ABCDEFGHIJKLMNOPQRSTUVWXYZ','abcdefghijklmnopqrstuvwxyz'),'${lower_label}')]\"}" 2>/dev/null)
+    element_id=$(echo "$resp" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    els = data.get('value', [])
+    if els:
+        print(els[0].get('ELEMENT', ''))
+except: pass
+" 2>/dev/null)
+  fi
+
+  if [[ -n "$element_id" ]]; then
+    # Get the element's bounding rect (WDA returns iOS logical coordinates directly)
+    local rect_resp
+    rect_resp=$(curl -s "http://localhost:${WDA_PORT}/session/${WDA_SESSION}/element/${element_id}/rect" 2>/dev/null)
+
+    echo "$rect_resp" | _FIND_LABEL="$search_label" python3 -c "
+import sys, json, os
+data = json.load(sys.stdin)
+r = data.get('value', {})
+x = int(r.get('x', 0))
+y = int(r.get('y', 0))
+w = int(r.get('width', 0))
+h = int(r.get('height', 0))
+label = os.environ.get('_FIND_LABEL', '')
+print(json.dumps({'role': 'XCUIElement', 'label': label, 'x': x, 'y': y, 'w': w, 'h': h}))
+" 2>/dev/null || die "find-element: failed to get rect for '$search_label'"
+    return 0
+  fi
+
+  # ── AX-grid fallback ────────────────────────────────────────────────────────
+  # WDA /source didn't include this label. Same gap that hits cmd_tap_element
+  # on system dialogs, swipe-revealed actions, custom toggles like Settings >
+  # Maps > Air Quality Index, etc. Run the same coarse-grid AX hit-test so
+  # find-element returns a usable rect for those elements too. Picks the best
+  # label match (exact > prefix > contains) over interactive + static-text
+  # roles. Static text is included here because find-element is also used as
+  # a "is this label visible?" probe by callers like scroll-to-visible.
+  local lw="${SIM_LOGICAL_W:-402}"
+  local lh="${SIM_LOGICAL_H:-874}"
+  local grid_input=""
+  local gx gy
+  # 40pt step starting at y=20 / x=20. The 20pt offset puts probes in the
+  # MIDDLE of typical 44pt-tall iOS HIG control bands rather than on their
+  # edges; AX hit-test at the exact rect edge sometimes returns the parent
+  # AXGroup instead of the control (we observed this on the Settings root
+  # search field at y=802-840, which AX returns as AXGroup at y=800/840 but
+  # AXTextField at y=820).
+  for ((gy = 20; gy < lh; gy += 40)); do
+    for ((gx = 20; gx < lw; gx += 40)); do
+      grid_input+="$gx $gy"$'\n'
+    done
+  done
+
+  local grid_results
+  grid_results=$(printf '%s' "$grid_input" | _describe_points_batch)
+
+  local needle_lower
+  needle_lower=$(echo "$search_label" | tr '[:upper:]' '[:lower:]')
+  local ax_match
+  ax_match=$(echo "$grid_results" | NEEDLE="$needle_lower" python3 -c "
+import json, os, sys
+needle = os.environ.get('NEEDLE', '')
+ROLES = {'AXButton', 'AXTextField', 'AXSecureTextField', 'AXSearchField',
+         'AXSwitch', 'AXSlider', 'AXLink', 'AXMenuItem', 'AXCheckBox',
+         'AXStaticText'}
+best = None
+best_score = -1
+seen = set()
+for line in sys.stdin:
+    line = line.strip()
+    if not line or line == 'null': continue
+    try: hit = json.loads(line)
+    except Exception: continue
+    if hit.get('role') not in ROLES: continue
+    lbl = (hit.get('label') or '').lower()
+    if not lbl: continue
+    key = (hit.get('role'), lbl, hit.get('x'), hit.get('y'))
+    if key in seen: continue
+    seen.add(key)
+    if lbl == needle: score = 3
+    elif lbl.startswith(needle): score = 2
+    elif needle in lbl: score = 1
+    else: continue
+    if score > best_score:
+        best_score = score
+        best = hit
+if best:
+    print(json.dumps({
+        'role': best.get('role'),
+        'label': best.get('label'),
+        'x': best.get('x', 0),
+        'y': best.get('y', 0),
+        'w': best.get('w', 0),
+        'h': best.get('h', 0),
+    }))
+" 2>/dev/null)
+
+  if [[ -n "$ax_match" ]]; then
+    echo "$ax_match"
+    return 0
+  fi
+
+  die "find-element: '$search_label' not found in WDA /source or in AX grid scan"
+}
+
+cmd_describe_point() {
+  [[ $# -ge 2 ]] || die "Usage: sim describe-point <x> <y>"
+  _is_integer "$1" || die "describe-point: x must be an integer, got: $1"
+  _is_integer "$2" || die "describe-point: y must be an integer, got: $2"
+  _bootstrap
+  local screen_coords sx sy
+  screen_coords=$(_ios_to_screen "$1" "$2")
+  sx=$(echo "$screen_coords" | awk '{print $1}')
+  sy=$(echo "$screen_coords" | awk '{print $2}')
+
+  local sim_orientation
+  sim_orientation=$(plutil -extract "DevicePreferences.${SIM_UDID}.SimulatorWindowOrientation" raw \
+    ~/Library/Preferences/com.apple.iphonesimulator.plist 2>/dev/null || echo "Portrait")
+
+  local result
+  result=$(swift - "$sx" "$sy" "$SIM_SCREEN_X" "$SIM_SCREEN_Y" "$SIM_ZOOM" "${SIM_NAME} – ${SIM_OS}" "$sim_orientation" "$SIM_LOGICAL_W" "$SIM_LOGICAL_H" 2>/dev/null << 'SWIFTEOF'
+import ApplicationServices
+import AppKit
+import Foundation
+
+let args = CommandLine.arguments
+let screenX    = Double(args[1])!
+let screenY    = Double(args[2])!
+let originX    = Double(args[3])!
+let originY    = Double(args[4])!
+let zoom       = Double(args[5])!
+let deviceName = args.count > 6 ? args[6] : ""
+let orientation = args.count > 7 ? args[7] : "Portrait"
+let logicalW    = Double(args.count > 8 ? args[8] : "390")  ?? 390.0
+let logicalH    = Double(args.count > 9 ? args[9] : "844") ?? 844.0
+
+guard let simApp = NSWorkspace.shared.runningApplications
+    .first(where: { $0.bundleIdentifier == "com.apple.iphonesimulator" }) else {
+    fputs("ERROR: Simulator not running\n", stderr); exit(1)
+}
+let pid = simApp.processIdentifier
+let axApp = AXUIElementCreateApplication(pid)
+
+func getAttr(_ el: AXUIElement, _ attr: String) -> AnyObject? {
+    var v: CFTypeRef?
+    guard AXUIElementCopyAttributeValue(el, attr as CFString, &v) == .success else { return nil }
+    return v as AnyObject
+}
+func getLabel(_ el: AXUIElement) -> String {
+    for a in ["AXDescription", "AXTitle", "AXLabel", "AXValue"] {
+        if let s = getAttr(el, a) as? String, !s.isEmpty { return s }
+    }
+    return ""
+}
+func getRole(_ el: AXUIElement) -> String {
+    return (getAttr(el, kAXRoleAttribute) as? String) ?? ""
+}
+
+var element: AXUIElement?
+let err = AXUIElementCopyElementAtPosition(axApp, Float(screenX), Float(screenY), &element)
+guard err == .success, let el = element else {
+    fputs("ERROR: no element at point (\(Int(screenX)), \(Int(screenY)))\n", stderr)
+    exit(1)
+}
+
+let role  = getRole(el)
+let label = getLabel(el)
+
+var lx = 0, ly = 0, lw = 0, lh = 0
+if let posVal = getAttr(el, kAXPositionAttribute),
+   let sizeVal = getAttr(el, kAXSizeAttribute) {
+    var pt = CGPoint.zero; var sz = CGSize.zero
+    AXValueGetValue(posVal as! AXValue, .cgPoint, &pt)
+    AXValueGetValue(sizeVal as! AXValue, .cgSize, &sz)
+    let wrx = (Double(pt.x) - originX) / zoom
+    let wry = (Double(pt.y) - originY) / zoom
+    let wrw = Double(sz.width)  / zoom
+    let wrh = Double(sz.height) / zoom
+    switch orientation {
+    case "PortraitUpsideDown":
+        lx = Int(logicalW - wrx - wrw + 0.5); ly = Int(logicalH - wry - wrh + 0.5)
+        lw = Int(wrw + 0.5);                  lh = Int(wrh + 0.5)
+    case "LandscapeLeft":
+        lx = Int(wry + 0.5);                            ly = Int(logicalH - wrx - wrw + 0.5)
+        lw = Int(wrh + 0.5);                            lh = Int(wrw + 0.5)
+    case "LandscapeRight":
+        lx = Int(logicalW - wry - wrh + 0.5);           ly = Int(wrx + 0.5)
+        lw = Int(wrh + 0.5);                            lh = Int(wrw + 0.5)
+    default: // Portrait
+        lx = Int(wrx + 0.5); ly = Int(wry + 0.5)
+        lw = Int(wrw + 0.5); lh = Int(wrh + 0.5)
+    }
+}
+
+let safeLabel = label
+    .replacingOccurrences(of: "\\", with: "\\\\")
+    .replacingOccurrences(of: "\"", with: "\\\"")
+print("{\"role\":\"\(role)\",\"label\":\"\(safeLabel)\",\"x\":\(lx),\"y\":\(ly),\"w\":\(lw),\"h\":\(lh)}")
+SWIFTEOF
+  )
+
+  local swift_exit=$?
+  if [[ $swift_exit -ne 0 ]] || [[ -z "$result" ]] || [[ "$result" == ERROR:* ]]; then
+    die "describe-point: ${result:-no element found at ($1, $2)}"
+  fi
+  echo "$result"
+}
+
+# _describe_points_batch
+# Hit-test many points in one swift invocation. Reads "logical_x logical_y"
+# pairs from stdin (one per line) and writes one result per line to stdout —
+# either a {role,label,x,y,w,h} JSON object for hits or the literal string
+# "null" for points where AX returned no element.
+#
+# WHY: every cmd_describe_point call pays ~150ms swift cold-start. Calling it
+# in a loop for 50+ points takes ~7s. Batching amortizes the swift startup
+# across all points so the same workload runs in ~300-800ms (200ms startup +
+# ~5-15ms per AX hit-test). Used by layout-map's verify pass.
+#
+# The output is positional — N input lines produce N output lines, even when
+# some hit-tests fail. Callers can zip input and output by line index.
+_describe_points_batch() {
+  _bootstrap
+
+  local sim_orientation
+  sim_orientation=$(plutil -extract "DevicePreferences.${SIM_UDID}.SimulatorWindowOrientation" raw \
+    ~/Library/Preferences/com.apple.iphonesimulator.plist 2>/dev/null || echo "Portrait")
+
+  # Convert each "logical_x logical_y" line on stdin to a "screen_x screen_y"
+  # line in bash before sending to swift. _ios_to_screen handles the orientation
+  # / zoom / origin transform; doing it here keeps the swift script focused on
+  # just the AX hit-test loop. Note: _ios_to_screen prints without a trailing
+  # newline, so we wrap with echo to ensure one line per pair.
+  local screen_pairs
+  screen_pairs=$(while read -r lx ly; do
+    if [[ -z "$lx" || -z "$ly" ]]; then
+      echo ""
+    else
+      echo "$(_ios_to_screen "$lx" "$ly")"
+    fi
+  done)
+
+  # Stage the swift script in a temp file so the input pipe can deliver coord
+  # pairs to swift's stdin (a heredoc on `swift -` would shadow the pipe).
+  local swift_script
+  swift_script=$(mktemp -t sim_describe_batch).swift
+  : > "$swift_script"
+  cat > "$swift_script" << 'SWIFTEOF'
+import ApplicationServices
+import AppKit
+import Foundation
+
+let args = CommandLine.arguments
+let originX     = Double(args[1])!
+let originY     = Double(args[2])!
+let zoom        = Double(args[3])!
+let orientation = args.count > 4 ? args[4] : "Portrait"
+let logicalW    = Double(args.count > 5 ? args[5] : "390") ?? 390.0
+let logicalH    = Double(args.count > 6 ? args[6] : "844") ?? 844.0
+
+guard let simApp = NSWorkspace.shared.runningApplications
+    .first(where: { $0.bundleIdentifier == "com.apple.iphonesimulator" }) else {
+    fputs("ERROR: Simulator not running\n", stderr); exit(1)
+}
+let pid = simApp.processIdentifier
+let axApp = AXUIElementCreateApplication(pid)
+
+func getAttr(_ el: AXUIElement, _ attr: String) -> AnyObject? {
+    var v: CFTypeRef?
+    guard AXUIElementCopyAttributeValue(el, attr as CFString, &v) == .success else { return nil }
+    return v as AnyObject
+}
+func getLabel(_ el: AXUIElement) -> String {
+    for a in ["AXDescription", "AXTitle", "AXLabel", "AXValue"] {
+        if let s = getAttr(el, a) as? String, !s.isEmpty { return s }
+    }
+    return ""
+}
+func getRole(_ el: AXUIElement) -> String {
+    return (getAttr(el, kAXRoleAttribute) as? String) ?? ""
+}
+
+while let line = readLine() {
+    let trimmed = line.trimmingCharacters(in: .whitespaces)
+    if trimmed.isEmpty { print("null"); continue }
+    let parts = trimmed.split(separator: " ")
+    guard parts.count >= 2,
+          let sx = Double(parts[0]),
+          let sy = Double(parts[1]) else {
+        print("null"); continue
+    }
+    var element: AXUIElement?
+    let err = AXUIElementCopyElementAtPosition(axApp, Float(sx), Float(sy), &element)
+    guard err == .success, let el = element else {
+        print("null"); continue
+    }
+    let role  = getRole(el)
+    let label = getLabel(el)
+    var lx = 0, ly = 0, lw = 0, lh = 0
+    if let posVal = getAttr(el, kAXPositionAttribute),
+       let sizeVal = getAttr(el, kAXSizeAttribute) {
+        var pt = CGPoint.zero; var sz = CGSize.zero
+        AXValueGetValue(posVal as! AXValue, .cgPoint, &pt)
+        AXValueGetValue(sizeVal as! AXValue, .cgSize, &sz)
+        let wrx = (Double(pt.x) - originX) / zoom
+        let wry = (Double(pt.y) - originY) / zoom
+        let wrw = Double(sz.width)  / zoom
+        let wrh = Double(sz.height) / zoom
+        switch orientation {
+        case "PortraitUpsideDown":
+            lx = Int(logicalW - wrx - wrw + 0.5); ly = Int(logicalH - wry - wrh + 0.5)
+            lw = Int(wrw + 0.5);                  lh = Int(wrh + 0.5)
+        case "LandscapeLeft":
+            lx = Int(wry + 0.5);                            ly = Int(logicalH - wrx - wrw + 0.5)
+            lw = Int(wrh + 0.5);                            lh = Int(wrw + 0.5)
+        case "LandscapeRight":
+            lx = Int(logicalW - wry - wrh + 0.5);           ly = Int(wrx + 0.5)
+            lw = Int(wrh + 0.5);                            lh = Int(wrw + 0.5)
+        default:
+            lx = Int(wrx + 0.5); ly = Int(wry + 0.5)
+            lw = Int(wrw + 0.5); lh = Int(wrh + 0.5)
+        }
+    }
+    let safeLabel = label
+        .replacingOccurrences(of: "\\", with: "\\\\")
+        .replacingOccurrences(of: "\"", with: "\\\"")
+    print("{\"role\":\"\(role)\",\"label\":\"\(safeLabel)\",\"x\":\(lx),\"y\":\(ly),\"w\":\(lw),\"h\":\(lh)}")
+}
+SWIFTEOF
+
+  printf '%s\n' "$screen_pairs" | swift "$swift_script" \
+    "$SIM_SCREEN_X" "$SIM_SCREEN_Y" "$SIM_ZOOM" "$sim_orientation" \
+    "$SIM_LOGICAL_W" "$SIM_LOGICAL_H" 2>/dev/null
+  rm -f "$swift_script"
+}
diff --git a/cli/src/commands/test/ios/simclaw/lib/simclaw/layout_map.sh b/cli/src/commands/test/ios/simclaw/lib/simclaw/layout_map.sh
new file mode 100644
index 00000000..c809f4c0
--- /dev/null
+++ b/cli/src/commands/test/ios/simclaw/lib/simclaw/layout_map.sh
@@ -0,0 +1,906 @@
+# lib/simclaw/layout_map.sh — layout-map command (primary navigation tool)
+[[ -n "${_SIM_LAYOUT_MAP_LOADED:-}" ]] && return 0; _SIM_LAYOUT_MAP_LOADED=1
+
+source "$SIM_LIB/bootstrap.sh"
+source "$SIM_LIB/wda.sh"
+source "$SIM_LIB/inspect.sh"
+
+# Each class-name query completes in <1s vs the multi-second /source serialization.
+_layout_map_elements_fallback() {
+  local layout_filter="${1:-all}"
+  local lw="${SIM_LOGICAL_W:-393}"
+  local lh="${SIM_LOGICAL_H:-852}"
+  local base="http://localhost:${WDA_PORT}/session/${WDA_SESSION}"
+
+  # ── Build per-class element-query helper script ───────────────────────────────
+  local tmp_el_py tmp_asm tmp_enrich
+  tmp_el_py=$(mktemp -t sim_el_query)
+  tmp_asm=$(mktemp -t sim_el_asm)
+  tmp_enrich=$(mktemp -t sim_el_enrich)
+
+  # element_query.py: POST /elements by class name, fetch rect+label per element
+  python3 -c "
+import textwrap, sys
+script = textwrap.dedent('''
+    import sys, json, urllib.request
+    base = sys.argv[1]
+    class_name = sys.argv[2]
+    logical_h = int(sys.argv[3]) if len(sys.argv) > 3 else 852
+    max_els = int(sys.argv[4]) if len(sys.argv) > 4 else 40
+
+    def wda_get(path, timeout=5):
+        try:
+            with urllib.request.urlopen(base + path, timeout=timeout) as r:
+                return json.loads(r.read())
+        except Exception:
+            return {}
+
+    def wda_post(path, data, timeout=5):
+        body = json.dumps(data).encode()
+        req = urllib.request.Request(base + path, data=body,
+                                     headers={\"Content-Type\": \"application/json\"})
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as r:
+                return json.loads(r.read())
+        except Exception:
+            return {}
+
+    resp = wda_post(\"/elements\", {\"using\": \"class name\", \"value\": class_name})
+    els = resp.get(\"value\", [])
+    if not isinstance(els, list):
+        print(\"[]\"); sys.exit(0)
+
+    results = []
+    seen = set()
+    for el in els[:max_els]:
+        eid = el.get(\"ELEMENT\") or el.get(\"element-6066-11e4-a52e-4f735466cecf\", \"\")
+        if not eid: continue
+        lbl = (wda_get(f\"/element/{eid}/attribute/label\")).get(\"value\") or \"\"
+        nm  = (wda_get(f\"/element/{eid}/attribute/name\")).get(\"value\") or \"\"
+        label = lbl if lbl else nm
+        r2 = (wda_get(f\"/element/{eid}/rect\")).get(\"value\", {})
+        x = int(r2.get(\"x\", 0)); y = int(r2.get(\"y\", 0))
+        w = int(r2.get(\"width\", 0)); h = int(r2.get(\"height\", 0))
+        if w == 0 or h == 0: continue
+        key = label + f\"|{x},{y}\"
+        if key in seen: continue
+        seen.add(key)
+        if y > logical_h * 1.5: continue
+        results.append({\"label\": label, \"x\": x, \"y\": y, \"w\": w, \"h\": h})
+    print(json.dumps(results))
+''').lstrip()
+sys.stdout.write(script)
+" > "$tmp_el_py"
+
+  # ── Query WDA by class name ──────────────────────────────────────────────────
+  local btn_json tabbar_json navbar_json tf_json sw_json sf_json
+  btn_json=$(python3 "$tmp_el_py" "$base" "XCUIElementTypeButton" "$lh" "50") || btn_json="[]"
+  tabbar_json=$(python3 "$tmp_el_py" "$base" "XCUIElementTypeTabBar" "$lh" "1") || tabbar_json="[]"
+  navbar_json=$(python3 "$tmp_el_py" "$base" "XCUIElementTypeNavigationBar" "$lh" "1") || navbar_json="[]"
+  if [[ "$layout_filter" != "buttons" ]]; then
+    tf_json=$(python3 "$tmp_el_py" "$base" "XCUIElementTypeTextField" "$lh" "10") || tf_json="[]"
+    sw_json=$(python3 "$tmp_el_py" "$base" "XCUIElementTypeSwitch" "$lh" "10") || sw_json="[]"
+    sf_json=$(python3 "$tmp_el_py" "$base" "XCUIElementTypeSearchField" "$lh" "5") || sf_json="[]"
+  else
+    tf_json="[]"; sw_json="[]"; sf_json="[]"
+  fi
+  rm -f "$tmp_el_py"
+
+  # ── Assemble raw layout-map JSON ─────────────────────────────────────────────
+  python3 -c "
+import textwrap, sys
+script = textwrap.dedent('''
+    import sys, json
+    logical_w = int(sys.argv[1])
+    logical_h = int(sys.argv[2])
+    btn_json    = json.loads(sys.argv[3])
+    tabbar_json = json.loads(sys.argv[4])
+    navbar_json = json.loads(sys.argv[5])
+    tf_json     = json.loads(sys.argv[6])
+    sw_json     = json.loads(sys.argv[7])
+    sf_json     = json.loads(sys.argv[8])
+
+    tab_bar_top = logical_h
+    tab_bar_rect = None
+    if tabbar_json:
+        tb = tabbar_json[0]
+        tab_bar_top = tb[\"y\"]
+        tab_bar_rect = tb
+
+    nav_bar_bottom = 0; nav_title = None; back_info = None
+    if navbar_json:
+        nb = navbar_json[0]
+        nav_bar_bottom = nb[\"y\"] + nb[\"h\"]
+        nav_title = nb[\"label\"] if nb[\"label\"] else None
+
+    tabs = []; content_buttons = []
+    for btn in btn_json:
+        bx = btn[\"x\"]; by = btn[\"y\"]; bw = btn[\"w\"]; bh = btn[\"h\"]
+        cy_center = by + bh // 2
+        if tab_bar_rect and cy_center >= tab_bar_top:
+            tabs.append({\"label\": btn[\"label\"], \"selected\": False,
+                         \"x\": bx + bw // 2, \"y\": by + bh // 2})
+        elif nav_bar_bottom > 0 and cy_center < nav_bar_bottom:
+            lbl_lower = btn[\"label\"].lower()
+            if \"back\" in lbl_lower or btn[\"label\"] == \"\":
+                if back_info is None:
+                    back_info = {\"label\": btn[\"label\"] or \"Back\",
+                                 \"x\": bx + bw // 2, \"y\": by + bh // 2}
+        else:
+            if by < tab_bar_top:
+                content_buttons.append(btn)
+
+    if back_info is None and not navbar_json:
+        for btn in btn_json:
+            bx = btn[\"x\"]; by = btn[\"y\"]; bw = btn[\"w\"]; bh = btn[\"h\"]
+            if \"back\" in btn[\"label\"].lower() and by < logical_h * 0.15:
+                back_info = {\"label\": btn[\"label\"] or \"Back\",
+                             \"x\": bx + bw // 2, \"y\": by + bh // 2}; break
+
+    interactive = []; seen_keys = set()
+    def add_interactive(els, role):
+        for el in els:
+            key = role + \"|\" + el[\"label\"] + f\"|{el[chr(120)]},{el[chr(121)]}\"
+            if key in seen_keys: continue
+            seen_keys.add(key)
+            interactive.append({\"role\": role, \"label\": el[\"label\"],
+                \"x\": el[\"x\"], \"y\": el[\"y\"], \"w\": el[\"w\"], \"h\": el[\"h\"],
+                \"value\": None, \"enabled\": True})
+    add_interactive(content_buttons, \"AXButton\")
+    add_interactive(tf_json, \"AXTextField\")
+    add_interactive(sw_json, \"AXSwitch\")
+    add_interactive(sf_json, \"AXSearchField\")
+
+    output = {
+        \"screen\": {\"w\": logical_w, \"h\": logical_h},
+        \"modal\": False,
+        \"navigation\": {\"title\": nav_title, \"back\": back_info, \"tabs\": tabs},
+        \"interactive\": interactive,
+        \"content\": {\"headings\": [], \"texts\": []},
+        \"scroll\": {\"vertical\": True, \"horizontal\": False,
+                   \"above_fold\": [], \"below_fold\": []},
+        \"_source\": \"elements_fallback\",
+    }
+    print(json.dumps(output))
+''').lstrip()
+sys.stdout.write(script)
+" > "$tmp_asm"
+
+  local asm_result
+  asm_result=$(python3 "$tmp_asm" \
+    "$lw" "$lh" \
+    "$btn_json" "$tabbar_json" "$navbar_json" \
+    "$tf_json" "$sw_json" "$sf_json") || asm_result=""
+  rm -f "$tmp_asm"
+
+  if [[ -z "$asm_result" ]]; then
+    echo "ERROR: element-query fallback assembly failed" >&2
+    printf '{"screen":{"w":%s,"h":%s},"navigation":{"title":null,"tabs":[],"back":null},"interactive":[],"content":{"headings":[],"texts":[]},"scroll":{"vertical":true,"horizontal":false,"above_fold":[],"below_fold":[]},"context":"unknown","suggested_actions":[],"_warning":"Both WDA /source and element fallback failed."}\n' \
+      "$lw" "$lh"
+    return 1
+  fi
+
+  # ── Enrich with context + suggested_actions ───────────────────────────────────
+  python3 -c "
+import textwrap, sys
+script = textwrap.dedent('''
+    import json, sys
+    with open(sys.argv[1]) as f: data = json.load(f)
+    interactive = data.get(\"interactive\", [])
+    navigation  = data.get(\"navigation\", {})
+    scroll      = data.get(\"scroll\", {})
+    modal       = data.get(\"modal\", False)
+    tabs        = navigation.get(\"tabs\", [])
+    back        = navigation.get(\"back\")
+    nav_title   = navigation.get(\"title\")
+
+    def has_role(r): return any(el.get(\"role\",\"\") == r for el in interactive)
+    def has_lbl(words):
+        for el in interactive:
+            l = el.get(\"label\",\"\").lower()
+            if any(w.lower() in l for w in words): return True
+        return False
+    def has_close(): return any(k in el.get(\"label\",\"\").lower() for el in interactive for k in [\"close\",\"dismiss\",\"cancel\"])
+
+    context = \"unknown\"
+    has_back = back is not None; has_tabs = len(tabs) >= 1
+    if has_lbl([\"play\",\"pause\"]) or (has_role(\"AXSlider\") and has_back and not has_tabs): context = \"media_player\"
+    elif modal or (not nav_title and has_close()): context = \"modal_sheet\"
+    elif has_role(\"AXSearchField\"): context = \"search\"
+    elif has_role(\"AXTextField\") or has_role(\"AXSecureTextField\"): context = \"form\"
+    elif len(tabs) >= 3: context = \"tab_screen\"
+    elif scroll.get(\"vertical\") and len(interactive) > 3: context = \"detail_screen\" if (has_back and not has_tabs) else \"list\"
+    elif has_back and not has_tabs: context = \"detail_screen\"
+
+    suggested = []
+    for tab in tabs:
+        if tab.get(\"selected\"): continue
+        suggested.append(\"tap tab \" + repr(tab.get(\"label\",\"?\")) + \" at (\" + str(tab.get(\"x\",0)) + \", \" + str(tab.get(\"y\",0)) + \")\")
+    if back: suggested.append(\"tap back \" + repr(back.get(\"label\",\"Back\")) + \" at (\" + str(back.get(\"x\",0)) + \", \" + str(back.get(\"y\",0)) + \") to return\")
+    bl = back.get(\"label\",\"\").lower() if back else None
+    cnt = 0
+    for el in interactive:
+        if cnt >= 6: break
+        lbl = el.get(\"label\",\"\")
+        if not lbl or (bl and lbl.lower() == bl): continue
+        cx = el.get(\"x\",0) + el.get(\"w\",0)//2; cy = el.get(\"y\",0) + el.get(\"h\",0)//2
+        suggested.append(\"tap \" + repr(lbl) + \" at (\" + str(cx) + \", \" + str(cy) + \")\")
+        cnt += 1
+    suggested = suggested[:10]
+    data[\"context\"] = context; data[\"suggested_actions\"] = suggested
+    print(json.dumps(data, indent=2))
+''').lstrip()
+sys.stdout.write(script)
+" > "$tmp_enrich"
+
+  local py_in enriched py_exit
+  py_in=$(mktemp /tmp/sim_layout_py_XXXXXX.json)
+  printf '%s' "$asm_result" > "$py_in"
+  enriched=$(python3 "$tmp_enrich" "$py_in")
+  py_exit=$?
+  rm -f "$py_in" "$tmp_enrich"
+
+  if [[ $py_exit -ne 0 ]] || [[ -z "$enriched" ]]; then
+    echo "$asm_result"
+  else
+    echo "$enriched"
+  fi
+}
+
+cmd_layout_map() {
+  # Optional per-call flags: --source-timeout <seconds>, --filter <buttons|all>
+  local source_timeout="${LAYOUT_MAP_SOURCE_TIMEOUT:-8}"
+  local layout_filter="all"
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --source-timeout) source_timeout="$2"; shift 2 ;;
+      --filter)         layout_filter="$2";  shift 2 ;;
+      *) break ;;
+    esac
+  done
+
+  _bootstrap
+
+  # ── Fetch WDA source XML ──────────────────────────────────────────────────────
+  # Try /wda/accessibleSource first — pre-pruned accessibility-only tree, faster to serialize.
+  # Fall back to full /source if that fails, returns empty, or returns non-XML (JSON dict).
+  local wda_xml curl_rc
+  wda_xml=$(curl -sf --max-time "${source_timeout}" \
+    "http://localhost:${WDA_PORT}/session/${WDA_SESSION}/wda/accessibleSource" 2>/dev/null)
+  curl_rc=$?
+  # accessibleSource may return a JSON dict tree instead of XML — detect and skip
+  if [[ $curl_rc -ne 0 ]] || [[ -z "$wda_xml" ]] || ! echo "$wda_xml" | python3 -c "
+import sys, json
+raw = sys.stdin.read()
+try:
+    d = json.loads(raw)
+    v = d.get('value', raw) if isinstance(d, dict) else raw
+    sys.exit(0 if isinstance(v, str) and v.strip().startswith('<') else 1)
+except: sys.exit(0 if raw.strip().startswith('<') else 1)
+" 2>/dev/null; then
+    # Fall back to full source
+    wda_xml=$(curl -sf --max-time "${source_timeout}" \
+      "http://localhost:${WDA_PORT}/session/${WDA_SESSION}/source" 2>/dev/null); curl_rc=$?; true
+  fi
+
+  if [[ $curl_rc -eq 28 ]]; then
+    # Timeout (exit 28): WDA is alive but the AX tree is too large to serialize.
+    # Fall back to targeted /elements queries — much faster than /source on large trees.
+    echo "WARNING: WDA /source timed out after ${source_timeout}s (AX tree too large). Using element-query fallback." >&2
+    _layout_map_elements_fallback "$layout_filter"
+    return $?
+  fi
+
+  if [[ $curl_rc -ne 0 ]] || [[ -z "$wda_xml" ]]; then
+    # Non-timeout error: session may have expired — if WDA server is still up, create a new session and retry.
+    local wda_status
+    wda_status=$(curl -s -o /dev/null -w "%{http_code}" --max-time 3 \
+      "http://localhost:${WDA_PORT}/status" 2>/dev/null) || true
+    if [[ "$wda_status" == "200" ]]; then
+      local session_resp session_id
+      session_resp=$(curl -s -X POST \
+        -H 'Content-Type: application/json' \
+        -d '{"capabilities":{"alwaysMatch":{"platformName":"iOS"}}}' \
+        --max-time 15 \
+        "http://localhost:${WDA_PORT}/session" 2>/dev/null) || true
+      session_id=$(echo "$session_resp" | python3 -c \
+        "import sys,json; d=json.load(sys.stdin); print(d.get('sessionId') or d.get('value',{}).get('sessionId',''))" \
+        2>/dev/null) || true
+      if [[ -n "$session_id" ]]; then
+        WDA_SESSION="$session_id"
+        _wda_write_cache
+        # Re-pin active application after session recreate to avoid background-window mismatch on iPad
+        if [[ -n "${WDA_APP_BUNDLE_ID:-}" ]]; then
+          curl -s -X POST \
+            -H "Content-Type: application/json" \
+            -d "{\"settings\":{\"defaultActiveApplication\":\"${WDA_APP_BUNDLE_ID}\"}}" \
+            --max-time 5 \
+            "http://localhost:${WDA_PORT}/session/${WDA_SESSION}/appium/settings" \
+            > /dev/null 2>&1 || true
+        fi
+        wda_xml=$(curl -sf --max-time "${source_timeout}" "http://localhost:${WDA_PORT}/session/${WDA_SESSION}/source" 2>/dev/null) || true
+      fi
+    fi
+    if [[ -z "$wda_xml" ]]; then
+      echo '{"error":"WDA unavailable"}' >&2
+      return 1
+    fi
+  fi
+
+  # ── Parse XML with Python, produce intermediate JSON ─────────────────────────
+  local tmp_xml tmp_py_parse result
+  tmp_xml=$(mktemp -t sim_wda_xml)
+  tmp_py_parse=$(mktemp -t sim_pyparse)
+  printf '%s' "$wda_xml" > "$tmp_xml"
+  cat > "$tmp_py_parse" << 'PYPARSE'
+import sys, json, xml.etree.ElementTree as ET
+
+logical_w = int(sys.argv[1]) if len(sys.argv) > 1 else 393
+logical_h = int(sys.argv[2]) if len(sys.argv) > 2 else 852
+layout_filter = sys.argv[4] if len(sys.argv) > 4 else "all"
+
+raw = open(sys.argv[3]).read() if len(sys.argv) > 3 else sys.stdin.read()
+# WDA /source returns JSON {"value": "<xml..."} — unwrap if needed
+try:
+    parsed = json.loads(raw)
+    raw_xml = parsed.get("value", raw) if isinstance(parsed, dict) else raw
+except Exception:
+    raw_xml = raw
+try:
+    root = ET.fromstring(raw_xml)
+except Exception as e:
+    sys.stderr.write("layout-map: XML parse error: " + str(e) + "\n")
+    sys.exit(1)
+
+# ── Helpers ────────────────────────────────────────────────────────────────────
+
+def iattr(el, key, default=0):
+    try:
+        return int(el.get(key, default))
+    except (TypeError, ValueError):
+        return default
+
+def name(el):
+    # Prefer label over name — name often has internal IDs like "TabBar.Settings.Item"
+    lbl = el.get("label", "")
+    nm  = el.get("name", "")
+    return lbl if lbl else nm
+
+def is_visible(el):
+    return iattr(el, "width") > 0 and iattr(el, "height") > 0
+
+def iter_all(node):
+    yield node
+    for child in node:
+        yield from iter_all(child)
+
+# ── Single pass over full tree — cache in list so we don't re-traverse for each type ──
+
+all_nodes = list(iter_all(root))
+
+# ── Screen dimensions ──────────────────────────────────────────────────────────
+
+app_el = next(
+    (e for e in all_nodes if e.tag == "XCUIElementTypeApplication"),
+    root
+)
+screen_w = iattr(app_el, "width", logical_w)
+screen_h = iattr(app_el, "height", logical_h)
+
+# ── Modal detection ────────────────────────────────────────────────────────────
+
+is_modal = any(
+    e.tag in ("XCUIElementTypeSheet", "XCUIElementTypeAlert")
+    for e in all_nodes
+)
+
+# ── Tab bar ────────────────────────────────────────────────────────────────────
+
+tab_bar = next(
+    (e for e in all_nodes if e.tag == "XCUIElementTypeTabBar"),
+    None
+)
+
+tabs = []
+tab_bar_top = screen_h
+tab_bar_elems = set()
+if tab_bar is not None and is_visible(tab_bar):
+    tab_bar_top = iattr(tab_bar, "y")
+    tab_bar_elems = set(id(e) for e in iter_all(tab_bar))
+    for btn in tab_bar:
+        if btn.tag == "XCUIElementTypeButton" and is_visible(btn):
+            bx = iattr(btn, "x")
+            by = iattr(btn, "y")
+            bw = iattr(btn, "width")
+            bh = iattr(btn, "height")
+            tabs.append({
+                "label": name(btn),
+                "selected": btn.get("selected", "false").lower() == "true",
+                "x": bx + bw // 2,
+                "y": by + bh // 2,
+            })
+
+# ── Navigation bar ─────────────────────────────────────────────────────────────
+
+nav_bar = next(
+    (e for e in all_nodes if e.tag == "XCUIElementTypeNavigationBar"),
+    None
+)
+
+nav_title = None
+nav_bar_bottom = 0
+back_info = None
+nav_bar_elems = set()
+
+if nav_bar is not None and is_visible(nav_bar):
+    nav_bar_bottom = iattr(nav_bar, "y") + iattr(nav_bar, "height")
+    nav_bar_elems = set(id(e) for e in iter_all(nav_bar))
+    # Title: first StaticText child or nav bar name
+    for child in nav_bar:
+        n = name(child)
+        if child.tag == "XCUIElementTypeStaticText" and n:
+            nav_title = n
+            break
+    if nav_title is None:
+        n = name(nav_bar)
+        if n:
+            nav_title = n
+    # Back button: first Button in NavBar whose name contains "back" or is empty (chevron)
+    for child in nav_bar:
+        if child.tag == "XCUIElementTypeButton":
+            n_lower = name(child).lower()
+            if "back" in n_lower or n_lower == "":
+                lbl = name(child) or "Back"
+                bx = iattr(child, "x"); by = iattr(child, "y")
+                bw = iattr(child, "width"); bh = iattr(child, "height")
+                back_info = {"label": lbl, "x": bx + bw // 2, "y": by + bh // 2}
+                break
+
+# ── Interactive elements ───────────────────────────────────────────────────────
+
+INTERACTIVE_TAGS = {
+    "XCUIElementTypeButton",
+    "XCUIElementTypeTextField",
+    "XCUIElementTypeSecureTextField",
+    "XCUIElementTypeSwitch",
+    "XCUIElementTypeSlider",
+    "XCUIElementTypeSearchField",
+}
+if layout_filter == "buttons":
+    INTERACTIVE_TAGS = {"XCUIElementTypeButton"}
+
+TAG_TO_ROLE = {
+    "XCUIElementTypeButton":          "AXButton",
+    "XCUIElementTypeTextField":       "AXTextField",
+    "XCUIElementTypeSecureTextField": "AXSecureTextField",
+    "XCUIElementTypeSwitch":          "AXSwitch",
+    "XCUIElementTypeSlider":          "AXSlider",
+    "XCUIElementTypeSearchField":     "AXSearchField",
+}
+
+interactive = []
+seen_interactive = set()
+for el in all_nodes:
+    if el.tag not in INTERACTIVE_TAGS:
+        continue
+    if id(el) in tab_bar_elems or id(el) in nav_bar_elems:
+        continue
+    if not is_visible(el):
+        continue
+    n = name(el)
+    key = el.tag + "|" + n
+    if key in seen_interactive:
+        continue
+    seen_interactive.add(key)
+    interactive.append({
+        "role":    TAG_TO_ROLE.get(el.tag, el.tag),
+        "label":   n,
+        "x":       iattr(el, "x"),
+        "y":       iattr(el, "y"),
+        "w":       iattr(el, "width"),
+        "h":       iattr(el, "height"),
+        "value":   el.get("value"),
+        "enabled": el.get("enabled", "true").lower() != "false",
+    })
+
+# ── Content: headings and texts ────────────────────────────────────────────────
+
+content_top = nav_bar_bottom
+content_h = tab_bar_top - content_top if tab_bar_top > content_top else screen_h - content_top
+heading_threshold_y = content_top + content_h * 0.30
+
+headings = []
+texts = []
+seen_text = set()
+
+if layout_filter != "buttons":
+    for el in all_nodes:
+        if el.tag != "XCUIElementTypeStaticText":
+            continue
+        if not is_visible(el):
+            continue
+        n = name(el)
+        if not n or n in seen_text:
+            continue
+        ey = iattr(el, "y")
+        if ey < content_top or ey > tab_bar_top:
+            continue
+        seen_text.add(n)
+        if ey <= heading_threshold_y and len(headings) < 5:
+            headings.append(n)
+        elif len(texts) < 10:
+            texts.append(n)
+
+# Remove texts that duplicate headings
+heading_set = set(headings)
+texts = [t for t in texts if t not in heading_set][:10]
+
+# ── Scroll awareness ────────────────────────────────────────────────────────────
+
+scroll_views = [e for e in all_nodes if e.tag == "XCUIElementTypeScrollView" and is_visible(e)]
+has_vertical_scroll = len(scroll_views) > 0
+has_horizontal_scroll = any(
+    iattr(sv, "width") > iattr(sv, "height") for sv in scroll_views
+)
+
+visible_bottom = tab_bar_top - 50
+above_fold = []
+below_fold = []
+seen_fold = set()
+
+FOLD_TAGS = {
+    "XCUIElementTypeStaticText",
+    "XCUIElementTypeButton",
+    "XCUIElementTypeCell",
+}
+
+for el in all_nodes:
+    if el.tag not in FOLD_TAGS:
+        continue
+    if not is_visible(el):
+        continue
+    n = name(el)
+    if not n or n in seen_fold:
+        continue
+    if id(el) in tab_bar_elems or id(el) in nav_bar_elems:
+        continue
+    ey = iattr(el, "y")
+    eh = iattr(el, "height")
+    if ey + eh > visible_bottom and len(below_fold) < 8:
+        seen_fold.add(n)
+        below_fold.append(n)
+    elif ey + eh < content_top and len(above_fold) < 8:
+        seen_fold.add(n)
+        above_fold.append(n)
+
+# ── Assemble JSON ──────────────────────────────────────────────────────────────
+
+output = {
+    "screen":     {"w": screen_w, "h": screen_h},
+    "modal":      is_modal,
+    "navigation": {
+        "title": nav_title,
+        "back":  back_info,
+        "tabs":  tabs,
+    },
+    "interactive": interactive,
+    "content": {
+        "headings": headings,
+        "texts":    texts,
+    },
+    "scroll": {
+        "vertical":    has_vertical_scroll,
+        "horizontal":  has_horizontal_scroll,
+        "above_fold":  above_fold,
+        "below_fold":  below_fold,
+    },
+}
+
+print(json.dumps(output))
+PYPARSE
+  result=$(python3 "$tmp_py_parse" "$SIM_LOGICAL_W" "$SIM_LOGICAL_H" "$tmp_xml" "$layout_filter")
+  local py_parse_exit=$?
+  rm -f "$tmp_xml" "$tmp_py_parse"
+  if [[ $py_parse_exit -ne 0 ]] || [[ -z "$result" ]]; then
+    echo '{"error":"WDA XML parse failed"}' >&2
+    return 1
+  fi
+
+  # Write parsed JSON to a temp file for the enrichment script
+  local py_in
+  py_in=$(mktemp /tmp/sim_layout_py_XXXXXX.json)
+  printf '%s' "$result" > "$py_in"
+
+  # ── Enrichment block follows ──────────────────────────────────────────────────
+  local tmp_py_enrich enriched
+  tmp_py_enrich=$(mktemp -t sim_pyenrich)
+  cat > "$tmp_py_enrich" << 'PYEOF'
+import json, sys
+
+input_path = sys.argv[1]
+with open(input_path) as f:
+    raw = f.read()
+
+try:
+    data = json.loads(raw)
+except Exception:
+    print(raw, end="")
+    sys.exit(0)
+
+interactive = data.get("interactive", [])
+navigation  = data.get("navigation", {})
+scroll      = data.get("scroll", {})
+modal       = data.get("modal", False)
+tabs        = navigation.get("tabs", [])
+back        = navigation.get("back")
+nav_title   = navigation.get("title")
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+def has_role(role):
+    return any(el.get("role", "") == role for el in interactive)
+
+def has_label_containing(words):
+    for el in interactive:
+        lbl = el.get("label", "").lower()
+        for w in words:
+            if w.lower() in lbl:
+                return True
+    return False
+
+def has_close_button():
+    for el in interactive:
+        lbl = el.get("label", "").lower()
+        if "close" in lbl or "dismiss" in lbl or "cancel" in lbl:
+            return True
+    return False
+
+# ── Context (first match wins) ────────────────────────────────────────────────
+context = "unknown"
+
+has_play_pause = has_label_containing(["play", "pause", "btnplay", "btnpause"])
+has_slider     = has_role("AXSlider")
+has_back       = back is not None
+has_tabs       = len(tabs) >= 1
+
+if has_play_pause or (has_slider and has_back and not has_tabs):
+    context = "media_player"
+elif modal or (not nav_title and has_close_button()):
+    context = "modal_sheet"
+elif has_role("AXSearchField"):
+    context = "search"
+elif has_role("AXTextField") or has_role("AXSecureTextField"):
+    context = "form"
+elif len(tabs) >= 3:
+    context = "tab_screen"
+elif scroll.get("vertical") and len(interactive) > 3:
+    if has_back and not has_tabs:
+        context = "detail_screen"
+    else:
+        context = "list"
+elif has_back and not has_tabs and scroll.get("vertical"):
+    context = "detail_screen"
+
+# ── Suggested actions ─────────────────────────────────────────────────────────
+suggested = []
+
+# 1. Scroll down
+below_fold = scroll.get("below_fold", [])
+if below_fold:
+    labels = ", ".join(below_fold[:4])
+    suggested.append("scroll down to reveal: " + labels)
+
+# 2. Scroll up
+above_fold = scroll.get("above_fold", [])
+if above_fold:
+    labels = ", ".join(above_fold[:4])
+    suggested.append("scroll up to reveal: " + labels)
+
+# 3. Tabs — x/y from Swift are already center coords
+for tab in tabs:
+    if tab.get("selected"):
+        continue
+    lbl = tab.get("label", "")
+    cx  = tab.get("x", 0)
+    cy  = tab.get("y", 0)
+    suggested.append("tap tab '" + lbl + "' at (" + str(cx) + ", " + str(cy) + ")")
+
+# 4. Back button — x/y from Swift are already center coords
+if back:
+    lbl = back.get("label", "Back")
+    cx  = back.get("x", 0)
+    cy  = back.get("y", 0)
+    suggested.append("tap back '" + lbl + "' at (" + str(cx) + ", " + str(cy) + ") to return")
+
+# 5. Interactive elements (up to 6, skip empty label, skip back)
+back_label_lower = back.get("label", "").lower() if back else None
+count = 0
+for el in interactive:
+    if count >= 6:
+        break
+    lbl = el.get("label", "")
+    if not lbl:
+        continue
+    if back_label_lower and lbl.lower() == back_label_lower:
+        continue
+    cx = el.get("x", 0) + el.get("w", 0) // 2
+    cy = el.get("y", 0) + el.get("h", 0) // 2
+    suggested.append("tap '" + lbl + "' at (" + str(cx) + ", " + str(cy) + ")")
+    count += 1
+
+# Cap at 10
+suggested = suggested[:10]
+
+data["context"]           = context
+data["suggested_actions"] = suggested
+
+print(json.dumps(data, indent=2))
+PYEOF
+  enriched=$(python3 "$tmp_py_enrich" "$py_in")
+  local py_exit=$?
+  rm -f "$py_in" "$tmp_py_enrich"
+
+  if [[ $py_exit -ne 0 ]] || [[ -z "$enriched" ]]; then
+    # Python failed — fall back to original Swift output unchanged
+    echo "$result"
+    return 0
+  fi
+
+  # ── Spot-check WDA's reported coordinates against the live AX hit-test ──────
+  # XCUITest's snapshot() (which feeds WDA /source) returns layout-intended
+  # frames. SwiftUI flex layouts (Spacer, .frame(maxHeight:.infinity), etc.)
+  # collapse at render time, leaving WDA's reported y for elements after the
+  # spacer way below their actual on-screen position. macOS AX hit-test
+  # (describe-point) returns the rendered position, which is what taps
+  # actually need.
+  #
+  # Strategy: ALWAYS hit-test every interactive element via the batched
+  # describe-point helper (one swift invocation, ~300ms even for 50 points).
+  # If WDA's reported center for an element doesn't match the AX hit-test
+  # there, replace its rect with the AX-correct one and mark the response
+  # `"layout_corrected": true` so consumers know we patched it.
+  #
+  # When the initial probe at WDA's cy misses, we look up to ±150pt around it
+  # in the SAME batched call (extra coords appended up front so the swift
+  # invocation count stays at one). This covers both the SwiftUI Spacer-
+  # collapse case (button rendered HIGHER than reported) and rarer cases
+  # where elements render lower than reported.
+  local interactive_count
+  interactive_count=$(echo "$enriched" | python3 -c "
+import json, sys
+try: d = json.loads(sys.stdin.read())
+except Exception: sys.exit(0)
+print(len(d.get('interactive', [])))
+" 2>/dev/null)
+
+  if [[ -z "$interactive_count" || "$interactive_count" -eq 0 ]]; then
+    echo "$enriched"
+    return 0
+  fi
+
+  # ── Phase 1: hit-test each element's WDA-reported center (one batched call)
+  # Cost: N AX hit-tests + 1 swift cold-start ≈ 200-400ms regardless of N.
+  # Output is one JSON-or-"null" per input line, in order.
+  local phase1_input phase1_results
+  phase1_input=$(echo "$enriched" | python3 -c "
+import json, sys
+d = json.loads(sys.stdin.read())
+for el in d.get('interactive', []):
+    cx = int(el.get('x', 0) + el.get('w', 0) / 2)
+    cy = int(el.get('y', 0) + el.get('h', 0) / 2)
+    print(cx, cy)
+" 2>/dev/null)
+
+  phase1_results=$(printf '%s\n' "$phase1_input" | _describe_points_batch)
+
+  # Identify which element indices failed phase 1. Build the phase-2 input
+  # plan: for each failed element, emit 20 walk probes (±30..±300 in 30pt
+  # steps). Skip phase 2 entirely when nothing failed.
+  local need_phase2 phase2_plan
+  need_phase2=$(echo "$enriched" | NEED_RES="$phase1_results" python3 -c "
+import json, os, sys
+data = json.loads(sys.stdin.read())
+results = []
+for line in os.environ.get('NEED_RES', '').split('\n'):
+    line = line.strip()
+    if not line or line == 'null':
+        results.append(None)
+    else:
+        try: results.append(json.loads(line))
+        except Exception: results.append(None)
+
+# Failed = WDA hit-test returned a different label than expected.
+failed = []
+for idx, el in enumerate(data.get('interactive', [])):
+    if idx >= len(results):
+        failed.append(idx); continue
+    expected = (el.get('label') or '').lower()
+    if not expected:
+        continue
+    hit = results[idx]
+    if not hit:
+        failed.append(idx); continue
+    if (hit.get('label') or '').lower() != expected:
+        failed.append(idx)
+
+print(','.join(str(i) for i in failed))
+" 2>/dev/null)
+
+  if [[ -z "$need_phase2" ]]; then
+    # All elements verified clean — return raw enriched (no correction needed).
+    echo "$enriched"
+    return 0
+  fi
+
+  # ── Phase 2: walk ±300pt around each failed element's WDA y in 30pt steps
+  # ±300pt covers SwiftUI Spacer heights up to a full screen third, enough for
+  # every real-world flex layout we've seen (Mindvalley's worst case = 226pt).
+  # 20 probes × failed_element_count, one batched call.
+  local phase2_input phase2_results
+  phase2_input=$(echo "$enriched" | FAILED="$need_phase2" python3 -c "
+import json, os, sys
+data = json.loads(sys.stdin.read())
+failed = set(int(x) for x in os.environ.get('FAILED', '').split(',') if x)
+for idx, el in enumerate(data.get('interactive', [])):
+    if idx not in failed:
+        continue
+    cx = int(el.get('x', 0) + el.get('w', 0) / 2)
+    cy = int(el.get('y', 0) + el.get('h', 0) / 2)
+    for off in (-30, -60, -90, -120, -150, -180, -210, -240, -270, -300,
+                 30,  60,  90, 120, 150, 180, 210, 240, 270, 300):
+        sy = cy + off
+        if sy < 50:
+            print('')
+        else:
+            print(cx, sy)
+" 2>/dev/null)
+
+  phase2_results=$(printf '%s\n' "$phase2_input" | _describe_points_batch)
+
+  # Apply corrections: for each failed element, take the first phase-2 probe
+  # whose label matches and use its AX-reported rect. Mark layout_corrected.
+  local corrected
+  corrected=$(echo "$enriched" | FAILED="$need_phase2" P2RES="$phase2_results" python3 -c "
+import json, os, sys
+data = json.loads(sys.stdin.read())
+failed = [int(x) for x in os.environ.get('FAILED', '').split(',') if x]
+results = []
+for line in os.environ.get('P2RES', '').split('\n'):
+    line = line.strip()
+    if not line or line == 'null':
+        results.append(None)
+    else:
+        try: results.append(json.loads(line))
+        except Exception: results.append(None)
+
+WALKS_PER_ELEMENT = 20
+n_fixed = 0
+interactive = data.get('interactive', [])
+for slot, idx in enumerate(failed):
+    if idx >= len(interactive):
+        continue
+    el = interactive[idx]
+    expected = (el.get('label') or '').lower()
+    if not expected:
+        continue
+    base = slot * WALKS_PER_ELEMENT
+    block = results[base:base + WALKS_PER_ELEMENT]
+    for probe in block:
+        if probe and (probe.get('label') or '').lower() == expected:
+            for k in ('x', 'y', 'w', 'h'):
+                el[k] = probe.get(k, el.get(k, 0))
+            n_fixed += 1
+            break
+
+if n_fixed > 0:
+    data['layout_corrected'] = True
+    data['_layout_correction_count'] = n_fixed
+print(json.dumps(data, indent=2))
+" 2>/dev/null)
+
+  if [[ -n "$corrected" ]]; then
+    echo "$corrected"
+  else
+    echo "$enriched"
+  fi
+}
diff --git a/cli/src/commands/test/ios/simclaw/lib/simclaw/login.sh b/cli/src/commands/test/ios/simclaw/lib/simclaw/login.sh
new file mode 100644
index 00000000..0624a109
--- /dev/null
+++ b/cli/src/commands/test/ios/simclaw/lib/simclaw/login.sh
@@ -0,0 +1,301 @@
+# lib/simclaw/login.sh — sim login command
+# Fills a standard email+password login form in any iOS app running in the simulator.
+#
+# Design rationale:
+#   Login forms vary widely across iOS apps:
+#     - Some use XCUIElementTypeTextField with proper accessibilityLabel.
+#     - Some (especially SwiftUI) wrap the field in XCUIElementTypeOther, with the
+#       visible "Email" / "Password" text rendered by a child SwiftUI Text view —
+#       leaving the tappable button/container with no accessibilityLabel of its own.
+#     - On iPad, class-name search for XCUIElementTypeTextField often returns 0
+#       results regardless of how the field is built.
+#
+#   This command delegates label-search to sim's own `cmd_tap_element`, which
+#   walks the full WDA AX tree and rolls up visible text from descendant elements
+#   into the parent's effective label. That handles all three cases above without
+#   apps needing to add explicit accessibilityLabel annotations. Focus is verified
+#   via /element/active before calling cmd_type, and each field gets up to 3
+#   attempts before the command fails.
+#
+# Usage:
+#   sim --device <UDID> login --email <email> --password <password>
+#
+# Exit codes:
+#   0 = login submitted successfully
+#   1 = could not enter email after 3 attempts
+#   2 = could not enter password after 3 attempts
+
+[[ -n "${_SIM_LOGIN_LOADED:-}" ]] && return 0; _SIM_LOGIN_LOADED=1
+
+source "$SIM_LIB/bootstrap.sh"
+source "$SIM_LIB/wda.sh"
+source "$SIM_LIB/nav.sh"
+source "$SIM_LIB/touch.sh"
+source "$SIM_LIB/type.sh"
+
+# _login_tap_label <label>
+# Tap an element by visible label using sim's AX tree traversal (cmd_tap_element).
+# This handles SwiftUI apps where the visible text lives on a child Text view
+# rather than the parent button's accessibilityLabel — cmd_tap_element rolls up
+# child labels while parsing WDA /source, whereas raw WDA "link text" search
+# (used previously) misses those buttons entirely.
+#
+# cmd_tap_element calls `die` (exit 1) when the label isn't in the current
+# viewport; the subshell here isolates that exit so login.sh can continue to its
+# next fallback label instead of aborting.
+#
+# Returns 0 if the tap succeeded, 1 if the label wasn't found.
+_login_tap_label() {
+  ( cmd_tap_element "$1" >/dev/null 2>&1 )
+}
+
+# _login_tap_button <label>
+# Tap a BUTTON whose label matches (case-insensitive contains).
+#
+# Two-phase strategy to handle a SwiftUI/WDA quirk found in the wild on Mindvalley:
+#
+# Phase 1 (xpath find + hit-test verify):
+#   Find the button via WDA xpath restricted to XCUIElementTypeButton (this
+#   alone disambiguates the form-title vs submit-button case where both share
+#   the same visible label). Then hit-test `describe-point` at the rect's
+#   center. If the hit-test returns the same label, WDA's coords are trustworthy
+#   and we tap there.
+#
+# Phase 2 (vertical AX scan fallback):
+#   When a SwiftUI form uses a Spacer/.frame(maxHeight:.infinity) between the
+#   last input and the submit button, WDA's /source XML reports the button at
+#   its layout-intended y (with the spacer counted at full height) while the
+#   real rendered y is much higher (spacer collapses to fit). Tapping at WDA's
+#   y lands in empty space below the social-buttons row. The AX-based
+#   describe-point hit-test, however, returns the correct rendered position.
+#   So when phase 1's hit-test disagrees with the xpath rect, we walk down the
+#   x-column from the top of the form via describe-point until we find an
+#   AXButton with the matching label, then tap its center.
+#
+# Returns 0 if a tap was sent at a verified position, 1 otherwise.
+_login_tap_button() {
+  local label="$1"
+  local lower
+  lower=$(echo "$label" | tr '[:upper:]' '[:lower:]')
+
+  # ── Phase 1: WDA xpath candidate + hit-test verify ──────────────────────────
+  local resp eid
+  resp=$(curl -sf -X POST -H "Content-Type: application/json" \
+    -d "{\"using\":\"xpath\",\"value\":\"//XCUIElementTypeButton[contains(translate(@label,'ABCDEFGHIJKLMNOPQRSTUVWXYZ','abcdefghijklmnopqrstuvwxyz'),'${lower}')]\"}" \
+    --max-time 5 \
+    "http://localhost:${WDA_PORT}/session/${WDA_SESSION}/elements" 2>/dev/null) || return 1
+  eid=$(echo "$resp" | python3 -c "
+import sys, json
+try:
+    e = json.load(sys.stdin).get('value', [])
+    if e: print(list(e[0].values())[0])
+except Exception: pass
+" 2>/dev/null)
+
+  local cx=""
+  local cy=""
+  if [[ -n "$eid" ]]; then
+    local rect
+    rect=$(curl -sf --max-time 5 \
+      "http://localhost:${WDA_PORT}/session/${WDA_SESSION}/element/${eid}/rect" 2>/dev/null)
+    cx=$(echo "$rect" | python3 -c "
+import sys, json
+try:
+    r = json.load(sys.stdin).get('value', {})
+    print(int(r.get('x', 0) + r.get('width', 0) / 2))
+except Exception: pass
+" 2>/dev/null)
+    cy=$(echo "$rect" | python3 -c "
+import sys, json
+try:
+    r = json.load(sys.stdin).get('value', {})
+    print(int(r.get('y', 0) + r.get('height', 0) / 2))
+except Exception: pass
+" 2>/dev/null)
+  fi
+
+  if [[ -n "$cx" && -n "$cy" ]]; then
+    local hit_label
+    hit_label=$(cmd_describe_point "$cx" "$cy" 2>/dev/null | python3 -c "
+import sys, json
+try:
+    print(json.load(sys.stdin).get('label', ''))
+except Exception: pass
+" 2>/dev/null)
+    if [[ -n "$hit_label" ]] && echo "$hit_label" | tr '[:upper:]' '[:lower:]' | grep -qF "$lower"; then
+      cmd_tap "$cx" "$cy" >/dev/null 2>&1 && return 0
+    fi
+  fi
+
+  # ── Phase 2: targeted AX scan upward from WDA's reported y ──────────────────
+  # The known SwiftUI/WDA quirk only puts the button HIGHER than WDA reports
+  # (Spacer collapses upward at render time). So we don't need to scan the
+  # whole screen — just walk UP from WDA's wrong y in coarse steps until we
+  # find an AXButton with the matching label, then tap its actual rect center.
+  # Bounded to ~10 iterations max (300pt range / 30pt step) so a single call
+  # finishes in under 2 seconds even on a fully-failing scan.
+  if [[ -n "$cx" && -n "$cy" ]]; then
+    local scan_y
+    for ((scan_y = cy; scan_y >= cy - 300 && scan_y > 100; scan_y -= 30)); do
+      local hit hit_role hit_lbl
+      hit=$(cmd_describe_point "$cx" "$scan_y" 2>/dev/null) || continue
+      hit_role=$(echo "$hit" | python3 -c "import sys,json
+try: print(json.load(sys.stdin).get('role',''))
+except Exception: pass" 2>/dev/null)
+      hit_lbl=$(echo "$hit" | python3 -c "import sys,json
+try: print(json.load(sys.stdin).get('label',''))
+except Exception: pass" 2>/dev/null)
+      if [[ "$hit_role" == "AXButton" ]] && \
+         echo "$hit_lbl" | tr '[:upper:]' '[:lower:]' | grep -qF "$lower"; then
+        # Use describe-point's rect (AX-reported, correct) and tap its center.
+        local rx ry rw rh
+        rx=$(echo "$hit" | python3 -c "import sys,json; print(json.load(sys.stdin).get('x',0))")
+        ry=$(echo "$hit" | python3 -c "import sys,json; print(json.load(sys.stdin).get('y',0))")
+        rw=$(echo "$hit" | python3 -c "import sys,json; print(json.load(sys.stdin).get('w',0))")
+        rh=$(echo "$hit" | python3 -c "import sys,json; print(json.load(sys.stdin).get('h',0))")
+        if cmd_tap $((rx + rw / 2)) $((ry + rh / 2)) >/dev/null 2>&1; then
+          return 0
+        fi
+      fi
+    done
+  fi
+
+  return 1
+}
+
+# _login_field_focused
+# Returns 0 if WDA reports a focused active element, 1 otherwise.
+# Must be called after tapping a field and sleeping 0.5s to allow iOS to settle.
+_login_field_focused() {
+  local resp
+  resp=$(curl -sf \
+    --max-time 5 \
+    "http://localhost:${WDA_PORT}/session/${WDA_SESSION}/element/active" 2>/dev/null) || return 1
+  # NOTE: `except Exception` (not bare `except`). Bare `except:` catches
+  # `SystemExit` raised by `sys.exit(0)` itself, which then triggers the
+  # except-branch `sys.exit(1)` and makes the function ALWAYS return 1.
+  # This footgun made the focus check incorrectly fail every login attempt.
+  echo "$resp" | python3 -c "
+import sys, json
+try:
+    val = json.load(sys.stdin).get('value')
+    sys.exit(0 if val else 1)
+except Exception:
+    sys.exit(1)
+" 2>/dev/null
+}
+
+cmd_login() {
+  local email="" password=""
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --email)    email="$2";    shift 2 ;;
+      --password) password="$2"; shift 2 ;;
+      *) die "login: unknown flag '$1'. Usage: sim --device <UDID> login --email <email> --password <password>" ;;
+    esac
+  done
+
+  [[ -n "$email" ]]    || die "login: --email is required"
+  [[ -n "$password" ]] || die "login: --password is required"
+
+  _bootstrap
+  _wda_ensure
+
+  # ── Step 1: Open login form ──────────────────────────────────────────────────
+  echo "login: opening login form..."
+  local opened=0
+  for label in "Log in" "Log In" "Login" "Sign in" "Sign In" "Sign Up" "Continue"; do
+    if _login_tap_label "$label"; then
+      echo "login: tapped '$label'"
+      sleep 1.2
+      opened=1
+      break
+    fi
+  done
+  [[ $opened -eq 1 ]] || echo "login: no login button found — assuming already on login form"
+
+  # ── Step 2: Enter email (max 3 attempts, strategy escalates on failure) ──────
+  echo "login: entering email..."
+  local email_done=0 attempt
+  for attempt in 1 2 3; do
+    for label in "Email" "Email or Username" "Username" "email" "E-mail" "Phone / Email / Username" "Phone, email, or username"; do
+      if _login_tap_label "$label"; then
+        sleep 0.5
+        if _login_field_focused; then
+          cmd_type "$email"
+          echo "login: email entered (attempt ${attempt}, field='${label}')"
+          email_done=1
+          break
+        fi
+      fi
+    done
+    [[ $email_done -eq 1 ]] && break
+
+    echo "login: attempt ${attempt}: email field not focused — escalating"
+    # Escalation: dismiss any stray keyboard/modal then re-open the login form
+    for reset in "Cancel" "cancel" "Close" "Dismiss"; do
+      _login_tap_label "$reset" || true
+    done
+    sleep 0.5
+    for label in "Log in" "Log In" "Login" "Sign in" "Sign In"; do
+      _login_tap_label "$label" && sleep 0.8 && break || true
+    done
+  done
+
+  if [[ $email_done -ne 1 ]]; then
+    echo "login: FATAL — could not enter email after 3 attempts" >&2
+    exit 1
+  fi
+
+  # Dismiss keyboard / advance to password field
+  sleep 0.3
+  for label in "Next" "next" "Return"; do
+    _login_tap_label "$label" && break || true
+  done
+  sleep 0.3
+
+  # ── Step 3: Enter password (max 3 attempts) ───────────────────────────────────
+  echo "login: entering password..."
+  local password_done=0
+  for attempt in 1 2 3; do
+    for label in "Password" "password" "Pass"; do
+      if _login_tap_label "$label"; then
+        sleep 0.5
+        if _login_field_focused; then
+          cmd_type "$password"
+          echo "login: password entered (attempt ${attempt})"
+          password_done=1
+          break
+        fi
+      fi
+    done
+    [[ $password_done -eq 1 ]] && break
+
+    echo "login: attempt ${attempt}: password field not focused — retrying"
+    sleep 0.5
+  done
+
+  if [[ $password_done -ne 1 ]]; then
+    echo "login: FATAL — could not enter password after 3 attempts" >&2
+    exit 2
+  fi
+
+  # ── Step 4: Submit ────────────────────────────────────────────────────────────
+  # Use _login_tap_button (xpath restricted to XCUIElementTypeButton) instead of
+  # _login_tap_label here so we don't accidentally tap a same-text form heading
+  # instead of the actual submit button — see _login_tap_button for the full
+  # rationale and the Mindvalley "Log In" duplicate-label example.
+  echo "login: submitting..."
+  sleep 0.3
+  for label in "Log in" "Log In" "Login" "Sign in" "Sign In" "Continue" "Submit" "Done"; do
+    if _login_tap_button "$label"; then
+      echo "login: tapped submit '${label}'"
+      break
+    fi
+  done
+
+  echo "login: waiting for authentication (3s)..."
+  sleep 3
+  echo "login: done"
+}
diff --git a/cli/src/commands/test/ios/simclaw/lib/simclaw/misc.sh b/cli/src/commands/test/ios/simclaw/lib/simclaw/misc.sh
new file mode 100644
index 00000000..72031154
--- /dev/null
+++ b/cli/src/commands/test/ios/simclaw/lib/simclaw/misc.sh
@@ -0,0 +1,139 @@
+# lib/simclaw/misc.sh — status, screenshot, cleanup, install-skills, health-check, etc.
+[[ -n "${_SIM_MISC_LOADED:-}" ]] && return 0; _SIM_MISC_LOADED=1
+
+source "$SIM_LIB/device.sh"
+source "$SIM_LIB/bootstrap.sh"
+
+# Usage: sim --device <UDID> ensure-foreground-app [bundle_id]
+cmd_ensure_foreground_app() {
+  local bundle_id="${1:-${WDA_APP_BUNDLE_ID:-com.mindvalley.mvacademy}}"
+  _bootstrap
+
+  # Re-pin defaultActiveApplication
+  curl -s -X POST \
+    -H "Content-Type: application/json" \
+    -d "{\"settings\":{\"defaultActiveApplication\":\"${bundle_id}\"}}" \
+    --max-time 5 \
+    "http://localhost:${WDA_PORT}/session/${WDA_SESSION}/appium/settings" \
+    > /dev/null 2>&1 || true
+
+  # Activate the app to ensure it is in the foreground
+  curl -s -X POST \
+    -H "Content-Type: application/json" \
+    -d "{\"bundleId\":\"${bundle_id}\"}" \
+    --max-time 10 \
+    "http://localhost:${WDA_PORT}/session/${WDA_SESSION}/wda/apps/activate" \
+    > /dev/null 2>&1 || true
+
+  echo "Ensured foreground app: ${bundle_id}"
+}
+
+cmd_status() {
+  detect_device
+  lookup_logical_resolution
+
+  echo "Booted Device:"
+  echo "  UDID:        $SIM_UDID"
+  echo "  Name:        $SIM_NAME"
+  echo "  OS:          $SIM_OS"
+  echo "  Device Type: $SIM_DEVICE_TYPE"
+  echo "  Scale:       ${SIM_SCALE}x"
+  echo "  Logical:     ${SIM_LOGICAL_W}x${SIM_LOGICAL_H} pts"
+
+  local bounds_ok=false
+  if pgrep -x Simulator > /dev/null 2>&1; then
+    if detect_screen_bounds 2>/dev/null; then
+      bounds_ok=true
+    fi
+  fi
+
+  if $bounds_ok; then
+    echo ""
+    echo "Screen Bounds (macOS screen coordinates):"
+    echo "  Origin:      (${SIM_SCREEN_X}, ${SIM_SCREEN_Y})"
+    echo "  Size:        ${SIM_SCREEN_W}x${SIM_SCREEN_H} pts"
+    echo "  Zoom factor: ${SIM_ZOOM}x"
+  else
+    echo ""
+    echo "Screen Bounds: [unavailable — Simulator.app not running or Accessibility permission missing]"
+  fi
+}
+
+cmd_screenshot() {
+  [[ $# -ge 1 ]] || die "Usage: sim screenshot <output.png>"
+  local outdir
+  outdir=$(dirname "$1")
+  [[ -d "$outdir" ]] || die "Output directory does not exist: $outdir"
+  detect_device
+  xcrun simctl io "$SIM_UDID" screenshot "$1" \
+    || die "simctl screenshot failed for UDID $SIM_UDID — path: $1"
+  echo "Screenshot saved: $1"
+}
+
+cmd_install_skills() {
+  # Locate pkgshare: resolve via brew if available, else derive from script location
+  local skills_src=""
+  if command -v brew &>/dev/null; then
+    local prefix
+    prefix=$(brew --prefix simclaw 2>/dev/null) || true
+    [[ -n "$prefix" ]] && skills_src="$prefix/share/simclaw/skills"
+  fi
+  # Fallback: derive from SIM_LIB (Homebrew: lib/../skills, repo: lib/simclaw/../../skills)
+  if [[ -z "$skills_src" || ! -d "$skills_src" ]]; then
+    skills_src="$(cd "$SIM_LIB/.." && pwd)/skills"
+  fi
+  if [[ -z "$skills_src" || ! -d "$skills_src" ]]; then
+    skills_src="$(cd "$SIM_LIB/../.." && pwd)/skills"
+  fi
+  [[ -d "$skills_src" ]] \
+    || die "install-skills: skills directory not found at $skills_src"
+
+  local skills_dst="$HOME/.claude/skills"
+  mkdir -p "$skills_dst"
+
+  local installed=0
+  for skill_dir in "$skills_src"/*/; do
+    [[ -d "$skill_dir" ]] || continue
+    local skill_name
+    skill_name=$(basename "$skill_dir")
+    mkdir -p "$skills_dst/$skill_name"
+    cp -f "$skill_dir"/* "$skills_dst/$skill_name/"
+    echo "Installed: $skill_name → $skills_dst/$skill_name"
+    (( installed++ )) || true
+  done
+
+  [[ $installed -gt 0 ]] \
+    || die "install-skills: no skills found in $skills_src"
+  echo ""
+  echo "$installed skill(s) installed. Available in any Claude Code session immediately."
+}
+
+cmd_cleanup() {
+  echo "Cleaning up stale sim state..."
+  # Kill any stale WDA processes
+  pkill -f WebDriverAgentRunner 2>/dev/null || true
+  sleep 1
+  # Remove bootstrap caches
+  rm -f /tmp/sim_bootstrap_cache_*.json
+  # Remove queue artifacts
+  rm -f /tmp/sim_queue.fifo /tmp/sim_queue.pid
+  echo "Cleanup complete"
+}
+
+cmd_wda_session() {
+  _bootstrap
+  echo "$WDA_SESSION"
+}
+
+cmd_health_check() {
+  _bootstrap
+  local resp rc=0
+  resp=$(curl -sf --max-time 5 "http://localhost:${WDA_PORT}/status" 2>/dev/null) || rc=$?
+  if [[ $rc -eq 0 ]] && [[ -n "$resp" ]]; then
+    echo "OK — WDA responding on port ${WDA_PORT}"
+    echo "$resp" | python3 -c "import sys,json; d=json.load(sys.stdin).get('value',{}); print(f'  Session: {d.get(\"sessionId\",\"unknown\")}')" 2>/dev/null || true
+  else
+    echo "FAILED — WDA not responding on port ${WDA_PORT}" >&2
+    return 1
+  fi
+}
diff --git a/cli/src/commands/test/ios/simclaw/lib/simclaw/nav.sh b/cli/src/commands/test/ios/simclaw/lib/simclaw/nav.sh
new file mode 100644
index 00000000..8eb2f1ba
--- /dev/null
+++ b/cli/src/commands/test/ios/simclaw/lib/simclaw/nav.sh
@@ -0,0 +1,349 @@
+# lib/simclaw/nav.sh — tap-element and tap-and-wait compound navigation
+[[ -n "${_SIM_NAV_LOADED:-}" ]] && return 0; _SIM_NAV_LOADED=1
+
+source "$SIM_LIB/bootstrap.sh"
+source "$SIM_LIB/wda.sh"
+source "$SIM_LIB/coords.sh"
+source "$SIM_LIB/inspect.sh"
+source "$SIM_LIB/wait.sh"
+source "$SIM_LIB/layout_map.sh"
+
+cmd_tap_element() {
+  # Parse args: <label> [--role <substring>]
+  # --role disambiguates when the same label exists on multiple element types
+  # on the same screen. Common case: a settings menu row labeled "Search"
+  # plus the search field at the bottom of the screen also labeled "Search"
+  # — without --role the tap target is ambiguous and may pick the wrong one.
+  # The role value is matched as a case-insensitive substring against both
+  # the WDA tag (XCUIElementTypeTextField, etc.) and the AX role
+  # (AXTextField, etc.), so `--role textfield` works regardless of which
+  # path resolves the element.
+  local label=""
+  local role_filter=""
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --role) [[ $# -ge 2 ]] || die "tap-element: --role requires a value"
+              role_filter="$2"; shift 2 ;;
+      *)      [[ -z "$label" ]] || die "tap-element: unexpected argument '$1'"
+              label="$1"; shift ;;
+    esac
+  done
+  [[ -n "$label" ]] || die "Usage: sim tap-element <label> [--role <substring>]"
+  _bootstrap
+
+  # Search WDA /source (viewport only — avoids cross-tab search pollution).
+  # /source returns only elements currently rendered on screen; /elements searches
+  # all loaded app contexts including background tabs, causing wrong-target taps.
+  local wda_xml
+  wda_xml=$(curl -sf --max-time 10 "http://localhost:${WDA_PORT}/session/${WDA_SESSION}/source" 2>/dev/null)
+  [[ -n "$wda_xml" ]] || die "tap-element: WDA /source unavailable"
+
+  local tmp_xml tmp_py
+  tmp_xml=$(mktemp -t sim_tapelement_xml)
+  tmp_py=$(mktemp -t sim_tapelement_py)
+  printf '%s' "$wda_xml" > "$tmp_xml"
+
+  cat > "$tmp_py" << 'PYEOF'
+import sys, json, xml.etree.ElementTree as ET
+
+search_label = sys.argv[1]
+screen_w     = int(sys.argv[2])
+screen_h     = int(sys.argv[3])
+xml_path     = sys.argv[4]
+role_filter  = sys.argv[5].lower() if len(sys.argv) > 5 else ""
+
+raw = open(xml_path).read()
+try:
+    parsed = json.loads(raw)
+    raw_xml = parsed.get("value", raw) if isinstance(parsed, dict) else raw
+except Exception:
+    raw_xml = raw
+
+root = ET.fromstring(raw_xml)
+
+def elem_name(el):
+    lbl = el.get("label", "")
+    nm  = el.get("name", "")
+    return lbl if lbl else nm
+
+lower_search = search_label.lower()
+best = None
+best_score = -1
+
+for el in root.iter():
+    # Apply --role filter if set: tag is e.g. "XCUIElementTypeTextField",
+    # so a substring check against role_filter (already lowercased) lets the
+    # caller pass "textfield", "TextField", "AXTextField", etc. and have it
+    # match the same set of elements regardless of casing or AX/XCUI prefix.
+    if role_filter and role_filter not in el.tag.lower():
+        continue
+    n = elem_name(el)
+    if not n:
+        continue
+    n_lower = n.lower()
+    # Prefer exact match, then prefix, then contains
+    if n_lower == lower_search:
+        score = 3
+    elif n_lower.startswith(lower_search):
+        score = 2
+    elif lower_search in n_lower:
+        score = 1
+    else:
+        continue
+
+    # Parse bounding box
+    try:
+        x = int(el.get("x", -1))
+        y = int(el.get("y", -1))
+        w = int(el.get("width", 0))
+        h = int(el.get("height", 0))
+    except (TypeError, ValueError):
+        continue
+
+    # Must be fully within viewport
+    if x < 0 or y < 0 or w <= 0 or h <= 0:
+        continue
+    if (x + w) > screen_w or (y + h) > screen_h:
+        continue
+
+    if score > best_score:
+        best_score = score
+        best = {"label": n, "x": x, "y": y, "w": w, "h": h,
+                "cx": x + w // 2, "cy": y + h // 2}
+
+if best:
+    print(json.dumps(best))
+else:
+    sys.exit(1)
+PYEOF
+
+  local found
+  found=$(python3 "$tmp_py" "$label" "$SIM_LOGICAL_W" "$SIM_LOGICAL_H" "$tmp_xml" "$role_filter" 2>/dev/null) || true
+  rm -f "$tmp_xml" "$tmp_py"
+
+  local cx cy
+  if [[ -n "$found" ]]; then
+    cx=$(echo "$found" | python3 -c "import sys,json; print(json.load(sys.stdin)['cx'])" 2>/dev/null)
+    cy=$(echo "$found" | python3 -c "import sys,json; print(json.load(sys.stdin)['cy'])" 2>/dev/null)
+  else
+    # ── AX-grid fallback ────────────────────────────────────────────────────
+    # WDA /source didn't include this label. Common cases that hit this path:
+    #   - System dialogs (notification permission, location prompts) live in
+    #     SpringBoard / system UI overlay, not the foreground app's snapshot.
+    #   - Some XCUIElement subclasses are simply missing from XCUITest's
+    #     snapshot() — e.g., the bottom-right `+` button on Reminders main.
+    #   - Dynamically-injected toolbars or overlays may not be captured yet.
+    #
+    # The AX hit-test path (`describe-point`) sees these elements correctly
+    # because it queries the live macOS AX tree from the simulator window
+    # server. We scan a coarse grid (50pt spacing → ~150 probes for a 4-inch
+    # screen) in one batched call, then pick the best label match. The grid
+    # is sparse enough that a single call finishes in ~1-2s — paid only when
+    # the WDA path missed.
+    local lw="${SIM_LOGICAL_W:-402}"
+    local lh="${SIM_LOGICAL_H:-874}"
+    local grid_input=""
+    local gx gy
+    # 40pt step starting at y=20 / x=20. The 20pt offset puts probes in the
+    # MIDDLE of typical 44pt-tall iOS HIG control bands rather than on their
+    # edges; AX hit-test at the exact rect edge sometimes returns the parent
+    # AXGroup instead of the control (we observed this on the Settings root
+    # search field at y=802-840, which AX returns as AXGroup at y=800/840 but
+    # AXTextField at y=820). 40pt step ensures any 44pt control gets at least
+    # one mid-band probe regardless of where it sits.
+    for ((gy = 20; gy < lh; gy += 40)); do
+      for ((gx = 20; gx < lw; gx += 40)); do
+        grid_input+="$gx $gy"$'\n'
+      done
+    done
+
+    local grid_results
+    grid_results=$(printf '%s' "$grid_input" | _describe_points_batch)
+
+    # Pick the best AX hit whose label matches (case-insensitive contains),
+    # restricted to interactive roles. Preference: exact > prefix > contains.
+    local needle_lower
+    needle_lower=$(echo "$label" | tr '[:upper:]' '[:lower:]')
+    local fallback_match
+    local role_lower=""
+    [[ -n "$role_filter" ]] && role_lower=$(echo "$role_filter" | tr '[:upper:]' '[:lower:]')
+    fallback_match=$(echo "$grid_results" | NEEDLE="$needle_lower" ROLE="$role_lower" python3 -c "
+import json, os, sys
+needle = os.environ.get('NEEDLE', '')
+role_filter = os.environ.get('ROLE', '')
+ROLES = {'AXButton', 'AXTextField', 'AXSecureTextField', 'AXSearchField',
+         'AXSwitch', 'AXSlider', 'AXLink', 'AXMenuItem', 'AXCheckBox'}
+best = None
+best_score = -1
+seen = set()
+for line in sys.stdin:
+    line = line.strip()
+    if not line or line == 'null': continue
+    try: hit = json.loads(line)
+    except Exception: continue
+    role = hit.get('role') or ''
+    if role not in ROLES: continue
+    if role_filter and role_filter not in role.lower(): continue
+    lbl = (hit.get('label') or '').lower()
+    if not lbl: continue
+    # Dedupe identical hits (the grid often hits the same large element
+    # multiple times) so the scoring isn't biased by element size.
+    key = (hit.get('role'), lbl, hit.get('x'), hit.get('y'))
+    if key in seen: continue
+    seen.add(key)
+    if lbl == needle: score = 3
+    elif lbl.startswith(needle): score = 2
+    elif needle in lbl: score = 1
+    else: continue
+    if score > best_score:
+        best_score = score
+        best = hit
+if best:
+    cx_ = int(best.get('x', 0) + best.get('w', 0) / 2)
+    cy_ = int(best.get('y', 0) + best.get('h', 0) / 2)
+    print(cx_)
+    print(cy_)
+    print(best.get('label', ''))
+" 2>/dev/null)
+
+    if [[ -z "$fallback_match" ]]; then
+      die "tap-element: '$label' not found in WDA /source or in AX grid scan"
+    fi
+
+    local fallback_label
+    { read -r cx; read -r cy; read -r fallback_label; } <<< "$fallback_match"
+    echo "NOTE: '$label' not in WDA /source — found via AX scan as '$fallback_label' at ($cx, $cy)"
+    _wda_tap "$cx" "$cy"
+    echo "OK: tapped $label at ($cx, $cy)"
+    return 0
+  fi
+
+  # ── Verify WDA's reported center against the live AX hit-test ──────────────
+  # XCUITest's snapshot() (which feeds WDA /source) returns layout-intended
+  # frames. SwiftUI flex layouts (Spacer, .frame(maxHeight:.infinity), etc.)
+  # collapse at render time — so an element WDA reports at y=663 may render
+  # at y=460. Tapping at WDA's coords lands in empty space.
+  #
+  # Same two-phase pattern as layout-map's verify pass, scoped to a single
+  # element: hit-test at WDA's center; if mismatch, walk ±300pt in 30pt steps
+  # via one batched describe-points call to find the rendered position.
+  local verify_lbl_lower
+  verify_lbl_lower=$(echo "$label" | tr '[:upper:]' '[:lower:]')
+  local hit_json hit_lbl
+  hit_json=$(cmd_describe_point "$cx" "$cy" 2>/dev/null)
+  hit_lbl=$(echo "$hit_json" | python3 -c "
+import sys, json
+try: print(json.load(sys.stdin).get('label',''))
+except Exception: pass
+" 2>/dev/null)
+  if [[ -z "$hit_lbl" ]] || \
+     ! echo "$hit_lbl" | tr '[:upper:]' '[:lower:]' | grep -qF "$verify_lbl_lower"; then
+    # WDA's center was wrong. Walk ±300pt to find the rendered position.
+    local walk_input walk_results
+    walk_input=$(for off in -30 -60 -90 -120 -150 -180 -210 -240 -270 -300 \
+                            30  60  90 120 150 180 210 240 270 300; do
+      local sy=$((cy + off))
+      [[ "$sy" -lt 50 ]] && echo "" || echo "$cx $sy"
+    done)
+    walk_results=$(printf '%s\n' "$walk_input" | _describe_points_batch)
+    local correction
+    correction=$(echo "$walk_results" | LBL="$verify_lbl_lower" python3 -c "
+import json, os, sys
+needle = os.environ.get('LBL', '')
+for line in sys.stdin:
+    line = line.strip()
+    if not line or line == 'null': continue
+    try: hit = json.loads(line)
+    except Exception: continue
+    if needle in (hit.get('label') or '').lower():
+        x = hit.get('x', 0); y = hit.get('y', 0)
+        w = hit.get('w', 0); h = hit.get('h', 0)
+        print(int(x + w/2), int(y + h/2))
+        sys.exit(0)
+")
+    if [[ -n "$correction" ]]; then
+      read -r cx cy <<< "$correction"
+      echo "NOTE: WDA reported wrong center for '$label' — corrected via AX hit-test to ($cx, $cy)"
+    fi
+  fi
+
+  _wda_tap "$cx" "$cy"
+  echo "OK: tapped $label at ($cx, $cy)"
+
+  # Post-tap check: see if element is gone (navigation likely succeeded)
+  sleep 0.4
+  local post_xml
+  post_xml=$(curl -sf --max-time 10 "http://localhost:${WDA_PORT}/session/${WDA_SESSION}/source" 2>/dev/null)
+  if [[ -n "$post_xml" ]]; then
+    local tmp_post_xml tmp_post_py still_visible
+    tmp_post_xml=$(mktemp -t sim_tapelement_post)
+    tmp_post_py=$(mktemp -t sim_tapelement_postpy)
+    printf '%s' "$post_xml" > "$tmp_post_xml"
+    cat > "$tmp_post_py" << 'POSTEOF'
+import sys, json, xml.etree.ElementTree as ET
+search_label = sys.argv[1].lower()
+xml_path = sys.argv[2]
+raw = open(xml_path).read()
+try:
+    parsed = json.loads(raw)
+    raw_xml = parsed.get("value", raw) if isinstance(parsed, dict) else raw
+except Exception:
+    raw_xml = raw
+root = ET.fromstring(raw_xml)
+for el in root.iter():
+    lbl = el.get("label", "")
+    nm  = el.get("name", "")
+    n = (lbl if lbl else nm).lower()
+    if search_label in n:
+        sys.exit(0)
+sys.exit(1)
+POSTEOF
+    python3 "$tmp_post_py" "$label" "$tmp_post_xml" 2>/dev/null && still_visible=0 || still_visible=$?
+    rm -f "$tmp_post_xml" "$tmp_post_py"
+    if [[ $still_visible -ne 0 ]]; then
+      echo "NOTE: '$label' no longer visible — navigation likely succeeded"
+    fi
+  fi
+}
+
+cmd_tap_and_wait() {
+  [[ $# -ge 1 ]] || die "Usage: sim tap-and-wait <label> [expected_label] [timeout]"
+  local label="$1"
+  local expected_label="${2:-}"
+  local timeout="${3:-10}"
+  _bootstrap
+
+  # Step 1: locate element via find-element
+  local json=""
+  if ! json=$(cmd_find_element "$label" 2>/dev/null); then
+    die "tap-and-wait: element not found: $label"
+  fi
+
+  # Step 2: compute center coordinates
+  local lx ly lw lh cx cy
+  lx=$(echo "$json" | jq -r '.x')
+  ly=$(echo "$json" | jq -r '.y')
+  lw=$(echo "$json" | jq -r '.w')
+  lh=$(echo "$json" | jq -r '.h')
+  cx=$(awk "BEGIN { printf \"%d\", $lx + $lw / 2 }")
+  cy=$(awk "BEGIN { printf \"%d\", $ly + $lh / 2 }")
+
+  # Step 3: tap at center using CGEvent
+  local screen_coords sx sy
+  screen_coords=$(_ios_to_screen "$cx" "$cy")
+  sx=$(echo "$screen_coords" | awk '{print $1}')
+  sy=$(echo "$screen_coords" | awk '{print $2}')
+  _tap_cgevent "$sx" "$sy" || die "tap-and-wait: tap failed at ($cx, $cy)"
+  echo "OK: tapped '$label' at ($cx, $cy)" >&2
+
+  # Step 4: wait for expected label or settle
+  if [[ -n "$expected_label" ]]; then
+    cmd_wait_for "$expected_label" "$timeout" || \
+      echo "WARNING: timed out waiting for '$expected_label' after ${timeout}s" >&2
+  else
+    sleep 1.5
+  fi
+
+  # Step 5: return layout-map JSON
+  cmd_layout_map
+}
diff --git a/cli/src/commands/test/ios/simclaw/lib/simclaw/setup.sh b/cli/src/commands/test/ios/simclaw/lib/simclaw/setup.sh
new file mode 100644
index 00000000..10999de8
--- /dev/null
+++ b/cli/src/commands/test/ios/simclaw/lib/simclaw/setup.sh
@@ -0,0 +1,199 @@
+# lib/simclaw/setup.sh — one-shot simulator setup
+[[ -n "${_SIM_SETUP_LOADED:-}" ]] && return 0; _SIM_SETUP_LOADED=1
+
+source "$SIM_LIB/bootstrap.sh"
+source "$SIM_LIB/wda.sh"
+
+cmd_setup() {
+  # Parse arguments: <app_path_or_bundle_id> [--port <wda_port>]
+  local app_arg=""
+  local wda_port="8100"
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --port)
+        [[ $# -ge 2 ]] || die "setup: --port requires a value"
+        wda_port="$2"
+        shift 2
+        ;;
+      *)
+        [[ -z "$app_arg" ]] || die "setup: unexpected argument: $1"
+        app_arg="$1"
+        shift
+        ;;
+    esac
+  done
+
+  [[ -n "$app_arg" ]] || die "Usage: sim [--device <UDID>] setup <app_path_or_bundle_id> [--port <wda_port>]"
+
+  # ── Step 1: Detect / boot simulator ─────────────────────────────────────────
+
+  echo "==> [1/5] Detecting simulator..."
+
+  # If a specific UDID was given, verify it exists and boot it if needed.
+  if [[ -n "$SIM_TARGET_UDID" ]]; then
+    local sim_state
+    sim_state=$(xcrun simctl list devices --json 2>/dev/null \
+      | jq -r --arg udid "$SIM_TARGET_UDID" '
+          .devices | to_entries[] | .value[] | select(.udid == $udid) | .state
+        ' 2>/dev/null | head -1) || true
+
+    [[ -n "$sim_state" ]] \
+      || die "setup: no simulator found with UDID: $SIM_TARGET_UDID"
+
+    if [[ "$sim_state" != "Booted" ]]; then
+      echo "    Booting simulator $SIM_TARGET_UDID..."
+      xcrun simctl boot "$SIM_TARGET_UDID" 2>/dev/null || true
+    else
+      echo "    Simulator $SIM_TARGET_UDID already booted."
+    fi
+
+    echo "    Waiting for simulator to fully boot..."
+    xcrun simctl bootstatus "$SIM_TARGET_UDID" -b \
+      || die "setup: simulator failed to reach booted state"
+  fi
+
+  # Open Simulator.app if not already visible.
+  if ! pgrep -x Simulator > /dev/null 2>&1; then
+    echo "    Opening Simulator.app..."
+    open -a Simulator
+    # Give Simulator.app a moment to render its window so AppleScript can see it.
+    sleep 2
+  else
+    echo "    Simulator.app is already running."
+  fi
+
+  # Run _bootstrap to populate all SIM_* globals (uses detect_device if no --device was given).
+  _bootstrap
+  echo "    Target: $SIM_NAME ($SIM_OS) — UDID: $SIM_UDID"
+
+  # ── Step 2: Build WDA if not already built ──────────────────────────────────
+
+  echo "==> [2/5] Checking WDA build..."
+
+  local wda_source="/tmp/WebDriverAgent"
+  local wda_derived
+  wda_derived=$(_wda_derived_path)
+  local wda_runner="$wda_derived/Build/Products/Debug-iphonesimulator/WebDriverAgentRunner-Runner.app"
+  local patch_stamp="$wda_derived/.patch_version"
+
+  if [[ ! -d "$wda_source" ]]; then
+    echo ""
+    echo "Error: WebDriverAgent not found at $wda_source"
+    echo "Clone it first: git clone https://github.com/appium/WebDriverAgent $wda_source"
+    exit 1
+  fi
+
+  # Cache reuse is gated on TWO conditions: the runner app exists AND the cached
+  # patch version matches WDA_PATCH_VERSION. If either fails we rebuild + re-patch
+  # so a stale cache (e.g. built before _wda_patch_ios_compat existed, or against
+  # the wrong iOS SDK) can't silently break WDA launch on the current runtime.
+  local cached_stamp=""
+  [[ -f "$patch_stamp" ]] && cached_stamp=$(cat "$patch_stamp" 2>/dev/null || true)
+
+  if [[ -d "$wda_runner" && "$cached_stamp" == "$WDA_PATCH_VERSION" ]]; then
+    echo "    WDA already built and patched (v$WDA_PATCH_VERSION) for $SIM_OS — skipping build."
+  else
+    if [[ -d "$wda_runner" && "$cached_stamp" != "$WDA_PATCH_VERSION" ]]; then
+      echo "    WDA cache patch version mismatch (cached='$cached_stamp', current='$WDA_PATCH_VERSION') for $SIM_OS — rebuilding."
+      rm -rf "$wda_derived"
+    fi
+    echo "    Building WDA for $SIM_OS (this may take a few minutes)..."
+    xcodebuild build-for-testing \
+      -project "$wda_source/WebDriverAgent.xcodeproj" \
+      -scheme WebDriverAgentRunner \
+      -destination "platform=iOS Simulator,id=${SIM_UDID}" \
+      -derivedDataPath "$wda_derived" \
+      CODE_SIGNING_ALLOWED=NO 2>&1 | tail -5
+    [[ -d "$wda_runner" ]] \
+      || die "setup: WDA build completed but runner app not found at $wda_runner"
+    echo "    WDA build complete."
+
+    # Patch WebDriverAgentLib to weak-link _LocationEssentials so a binary built
+    # against the iOS 26+ SDK still launches on older iOS simulator runtimes
+    # (< 26) where that framework does not exist. Also rewrites LC_BUILD_VERSION
+    # minos to 13.0 so xcodebuild won't reject the binary for older sims.
+    _wda_patch_ios_compat "$wda_derived/Build/Products"
+
+    # Stamp the build with the current patch version so subsequent setup runs
+    # can detect whether a re-patch (or full rebuild) is required.
+    echo "$WDA_PATCH_VERSION" > "$patch_stamp"
+  fi
+
+  # ── Step 3: Install app (if a .app path was given) ──────────────────────────
+
+  echo "==> [3/5] Installing app..."
+
+  local bundle_id=""
+  if [[ "$app_arg" == *.app ]]; then
+    echo "    Installing $app_arg on $SIM_UDID..."
+    xcrun simctl install "$SIM_UDID" "$app_arg" \
+      || die "setup: xcrun simctl install failed for $app_arg"
+    echo "    App installed."
+
+    # Derive bundle ID from the installed .app's Info.plist.
+    local info_plist="$app_arg/Info.plist"
+    [[ -f "$info_plist" ]] \
+      || die "setup: Info.plist not found in $app_arg"
+    bundle_id=$(plutil -extract CFBundleIdentifier raw "$info_plist" 2>/dev/null) \
+      || die "setup: could not read CFBundleIdentifier from $info_plist"
+    echo "    Bundle ID: $bundle_id"
+  else
+    bundle_id="$app_arg"
+    echo "    Bundle ID provided directly ($bundle_id) — skipping install."
+  fi
+
+  # ── Step 4: Start WDA (graceful — setup continues if WDA fails) ─────────────
+
+  echo "==> [4/5] Starting WDA on port $wda_port..."
+  local wda_available="true"
+  # Run cmd_wda_start in a subshell so its internal `die` (exit 1) does not
+  # kill the parent setup process. WDA is expected to fail on older iOS
+  # versions where the WDA xctest binary's MinimumOSVersion exceeds the
+  # simulator's OS version (e.g. WDA built with iOS 26 SDK on an iOS 18 sim).
+  if ( cmd_wda_start "$wda_port" ); then
+    # cmd_wda_start wrote port+session to the bootstrap cache — read them back
+    # into the parent shell (subshell variables don't propagate).
+    local cache_file="/tmp/sim_bootstrap_cache_${SIM_UDID}.json"
+    if [[ -f "$cache_file" ]]; then
+      WDA_PORT=$(python3 -c "import json; print(json.load(open('$cache_file')).get('wda_port',''))" 2>/dev/null) || true
+      WDA_SESSION=$(python3 -c "import json; print(json.load(open('$cache_file')).get('wda_session',''))" 2>/dev/null) || true
+    fi
+  else
+    wda_available="false"
+    WDA_PORT=""
+    WDA_SESSION=""
+    echo ""
+    echo "    WDA failed to start — continuing without WDA."
+    echo "    (Expected on iOS versions with WDA SDK mismatch.)"
+    echo "    Screenshot and AX-based commands (describe, wait-for) still work."
+  fi
+
+  # ── Step 5: Launch app ───────────────────────────────────────────────────────
+
+  echo "==> [5/5] Launching $bundle_id..."
+  xcrun simctl launch "$SIM_UDID" "$bundle_id" \
+    || die "setup: xcrun simctl launch failed for bundle ID: $bundle_id"
+  echo "    App launched."
+
+  # ── Final status ─────────────────────────────────────────────────────────────
+
+  echo ""
+  echo "── Setup complete ───────────────────────────────────────────────────────────"
+  echo "  Simulator:  $SIM_NAME ($SIM_OS)"
+  echo "  UDID:       $SIM_UDID"
+  if [[ "$wda_available" == "true" ]]; then
+    echo "  WDA port:   $WDA_PORT"
+    echo "  WDA session: $WDA_SESSION"
+    echo "  WDA:        ready"
+  else
+    echo "  WDA:        unavailable (screenshot + AX commands only)"
+  fi
+  echo "  App:        $bundle_id"
+  echo ""
+  if [[ "$wda_available" == "true" ]]; then
+    echo "WDA is ready. You can now use tap/swipe/scroll commands."
+  else
+    echo "Setup complete (no WDA). Use screenshot/describe/wait-for commands."
+  fi
+}
diff --git a/cli/src/commands/test/ios/simclaw/lib/simclaw/swift/pickwindow.swift b/cli/src/commands/test/ios/simclaw/lib/simclaw/swift/pickwindow.swift
new file mode 100644
index 00000000..123dec5e
--- /dev/null
+++ b/cli/src/commands/test/ios/simclaw/lib/simclaw/swift/pickwindow.swift
@@ -0,0 +1,25 @@
+func pickWindow(_ windows: [AXUIElement], screenX: Double, screenY: Double, deviceName: String) -> AXUIElement? {
+    // Primary: find the window whose bounds contain the known screen origin.
+    // SIM_SCREEN_X/Y are the macOS screen coords of the iOS screen surface — unique per window.
+    for win in windows {
+        var posRef: CFTypeRef?
+        var sizeRef: CFTypeRef?
+        guard AXUIElementCopyAttributeValue(win, kAXPositionAttribute as CFString, &posRef) == .success,
+              AXUIElementCopyAttributeValue(win, kAXSizeAttribute as CFString, &sizeRef) == .success,
+              let pv = posRef, let sv = sizeRef else { continue }
+        var pt = CGPoint.zero; var sz = CGSize.zero
+        AXValueGetValue(pv as! AXValue, .cgPoint, &pt)
+        AXValueGetValue(sv as! AXValue, .cgSize, &sz)
+        if screenX >= Double(pt.x) && screenX <= Double(pt.x + sz.width) &&
+           screenY >= Double(pt.y) && screenY <= Double(pt.y + sz.height) {
+            return win
+        }
+    }
+    // Fallback: match by title containing device name
+    for win in windows {
+        var titleRef: CFTypeRef?
+        if AXUIElementCopyAttributeValue(win, kAXTitleAttribute as CFString, &titleRef) == .success,
+           let title = titleRef as? String, title.contains(deviceName) { return win }
+    }
+    return windows.first
+}
diff --git a/cli/src/commands/test/ios/simclaw/lib/simclaw/touch.sh b/cli/src/commands/test/ios/simclaw/lib/simclaw/touch.sh
new file mode 100644
index 00000000..7e8b7061
--- /dev/null
+++ b/cli/src/commands/test/ios/simclaw/lib/simclaw/touch.sh
@@ -0,0 +1,108 @@
+# lib/simclaw/touch.sh — tap, swipe, scroll commands
+[[ -n "${_SIM_TOUCH_LOADED:-}" ]] && return 0; _SIM_TOUCH_LOADED=1
+
+source "$SIM_LIB/bootstrap.sh"
+source "$SIM_LIB/wda.sh"
+source "$SIM_LIB/coords.sh"
+source "$SIM_LIB/inspect.sh"
+
+cmd_tap() {
+  local x="${1:?Usage: sim tap <x> <y>}"
+  local y="${2:?Usage: sim tap <x> <y>}"
+  _is_integer "$x" || die "tap: x must be an integer, got: $x"
+  _is_integer "$y" || die "tap: y must be an integer, got: $y"
+
+  # Try WDA pointer action first — works reliably on all devices
+  if _tap_wda "$x" "$y" 2>/dev/null; then
+    return 0
+  fi
+
+  # Fallback: CGEvent injection (requires simulator window position)
+  echo "WDA tap unavailable, falling back to CGEvent injection..." >&2
+  _bootstrap
+  local screen_coords sx sy
+  screen_coords=$(_ios_to_screen "$x" "$y")
+  sx=$(echo "$screen_coords" | awk '{print $1}')
+  sy=$(echo "$screen_coords" | awk '{print $2}')
+  _tap_cgevent "$sx" "$sy"
+}
+
+cmd_swipe() {
+  [[ $# -ge 4 ]] || die "Usage: sim swipe <x1> <y1> <x2> <y2> [steps] [step_ms]"
+  _is_integer "$1" || die "swipe: x1 must be an integer, got: $1"
+  _is_integer "$2" || die "swipe: y1 must be an integer, got: $2"
+  _is_integer "$3" || die "swipe: x2 must be an integer, got: $3"
+  _is_integer "$4" || die "swipe: y2 must be an integer, got: $4"
+  local steps="${5:-25}"
+  local step_ms="${6:-20}"
+  local duration_ms=$(( steps * step_ms ))
+
+  # Try WDA pointer action first — works reliably on all devices
+  if _swipe_wda "$1" "$2" "$3" "$4" "$duration_ms" 2>/dev/null; then
+    return 0
+  fi
+
+  # Fallback: legacy CGEvent-style injection (macOS coord round-trip)
+  echo "WDA swipe unavailable, falling back to CGEvent injection..." >&2
+  _bootstrap
+  local sc1 sc2 sx1 sy1 sx2 sy2
+  sc1=$(_ios_to_screen "$1" "$2")
+  sx1=$(echo "$sc1" | awk '{print $1}')
+  sy1=$(echo "$sc1" | awk '{print $2}')
+  sc2=$(_ios_to_screen "$3" "$4")
+  sx2=$(echo "$sc2" | awk '{print $1}')
+  sy2=$(echo "$sc2" | awk '{print $2}')
+  _swipe_cgevent "$sx1" "$sy1" "$sx2" "$sy2" "$steps" "$step_ms"
+}
+
+cmd_scroll_up() {
+  # finger moves DOWN (from_y=0.27H → to_y=0.75H) — reveals content ABOVE current view
+  _bootstrap
+  local x from_y to_y
+  x="${1:-$(awk "BEGIN { printf \"%d\", $SIM_LOGICAL_W / 2 }")}"
+  from_y="${2:-$(awk "BEGIN { printf \"%d\", $SIM_LOGICAL_H * 0.27 }")}"
+  to_y="${3:-$(awk "BEGIN { printf \"%d\", $SIM_LOGICAL_H * 0.75 }")}"
+  _wda_swipe "$x" "$from_y" "$x" "$to_y"
+}
+
+cmd_scroll_down() {
+  # finger moves UP (from_y=0.75H → to_y=0.27H) — reveals content BELOW current view
+  _bootstrap
+  local x from_y to_y
+  x="${1:-$(awk "BEGIN { printf \"%d\", $SIM_LOGICAL_W / 2 }")}"
+  from_y="${2:-$(awk "BEGIN { printf \"%d\", $SIM_LOGICAL_H * 0.75 }")}"
+  to_y="${3:-$(awk "BEGIN { printf \"%d\", $SIM_LOGICAL_H * 0.27 }")}"
+  _wda_swipe "$x" "$from_y" "$x" "$to_y"
+}
+
+cmd_scroll_to_visible() {
+  [[ $# -ge 1 ]] || die "Usage: sim scroll-to-visible <label> [max_swipes]"
+  local label="$1"
+  local max_swipes="${2:-10}"
+  _bootstrap
+
+  local found=""
+  local swipe_count=0
+
+  while [[ $swipe_count -le $max_swipes ]]; do
+    if found=$( cmd_find_element "$label" 2>/dev/null ); then
+      # Validate the element is actually within the visible viewport.
+      # WDA /element/{id}/rect returns content coordinates — y > SIM_LOGICAL_H
+      # means the element is below the fold and needs more scrolling.
+      local ey eh
+      ey=$(echo "$found" | python3 -c "import sys,json; print(json.load(sys.stdin)['y'])" 2>/dev/null || echo "0")
+      eh=$(echo "$found" | python3 -c "import sys,json; print(json.load(sys.stdin)['h'])" 2>/dev/null || echo "0")
+      if [[ $ey -ge 0 && $(( ey + eh )) -le $SIM_LOGICAL_H ]]; then
+        echo "$found"
+        return 0
+      fi
+      # Element found but outside viewport — keep scrolling
+    fi
+    if [[ $swipe_count -lt $max_swipes ]]; then
+      cmd_scroll_down
+    fi
+    (( swipe_count++ )) || true
+  done
+
+  die "scroll-to-visible: '$label' not found after $max_swipes scrolls"
+}
diff --git a/cli/src/commands/test/ios/simclaw/lib/simclaw/type.sh b/cli/src/commands/test/ios/simclaw/lib/simclaw/type.sh
new file mode 100644
index 00000000..3d1a5dc8
--- /dev/null
+++ b/cli/src/commands/test/ios/simclaw/lib/simclaw/type.sh
@@ -0,0 +1,132 @@
+# lib/simclaw/type.sh — text input commands
+[[ -n "${_SIM_TYPE_LOADED:-}" ]] && return 0; _SIM_TYPE_LOADED=1
+
+source "$SIM_LIB/bootstrap.sh"
+source "$SIM_LIB/wda.sh"
+
+# _type_cgevent <text>
+# Sets text in the currently focused field via the AX API (no keyboard events needed)
+_type_cgevent() {
+  local text="$1"
+  # Pass the text via environment variable so the quoted heredoc can stay static
+  local out
+  out=$(SIM_TYPE_TEXT="$text" swift - "${SIM_NAME} – ${SIM_OS}" "$SIM_SCREEN_X" "$SIM_SCREEN_Y" 2>&1 << SWIFTEOF
+import Cocoa
+import ApplicationServices
+
+let args = CommandLine.arguments
+let deviceName = args.count > 1 ? args[1] : ""
+let screenX    = Double(args.count > 2 ? args[2] : "0") ?? 0.0
+let screenY    = Double(args.count > 3 ? args[3] : "0") ?? 0.0
+
+guard let app = NSRunningApplication.runningApplications(
+    withBundleIdentifier: "com.apple.iphonesimulator").first else {
+  fputs("ERROR: Simulator not running\n", stderr); exit(1)
+}
+
+let axApp = AXUIElementCreateApplication(app.processIdentifier)
+
+func getAttribute(_ el: AXUIElement, _ attr: String) -> CFTypeRef? {
+    var v: CFTypeRef?
+    AXUIElementCopyAttributeValue(el, attr as CFString, &v)
+    return v
+}
+
+let textRoles: Set<String> = ["AXTextField", "AXTextArea", "AXSearchField"]
+
+func isSettableTextField(_ el: AXUIElement) -> Bool {
+    guard let role = getAttribute(el, "AXRole") as? String,
+          textRoles.contains(role) else { return false }
+    var settable: DarwinBoolean = false
+    AXUIElementIsAttributeSettable(el, "AXValue" as CFString, &settable)
+    return settable.boolValue
+}
+
+func findFocusedTextField(_ el: AXUIElement, _ depth: Int) -> AXUIElement? {
+    if depth < 0 { return nil }
+    if let focused = getAttribute(el, "AXFocused") as? Bool, focused,
+       isSettableTextField(el) {
+        return el
+    }
+    guard let children = getAttribute(el, "AXChildren") as? [AXUIElement] else { return nil }
+    for child in children {
+        if let found = findFocusedTextField(child, depth - 1) { return found }
+    }
+    return nil
+}
+
+func findFirstSettableTextField(_ el: AXUIElement, _ depth: Int) -> AXUIElement? {
+    if depth < 0 { return nil }
+    if isSettableTextField(el) { return el }
+    guard let children = getAttribute(el, "AXChildren") as? [AXUIElement] else { return nil }
+    for child in children {
+        if let found = findFirstSettableTextField(child, depth - 1) { return found }
+    }
+    return nil
+}
+
+$(cat "$SIM_LIB/swift/pickwindow.swift")
+
+guard let windows = getAttribute(axApp, "AXWindows") as? [AXUIElement],
+      let window = pickWindow(windows, screenX: screenX, screenY: screenY, deviceName: deviceName) else {
+    fputs("ERROR: no Simulator window\n", stderr); exit(1)
+}
+
+// 1. Try the shortcut focused element if it is itself a settable text field
+var focusedEl: AXUIElement? = nil
+if let f = getAttribute(axApp, "AXFocusedUIElement") {
+    let candidate = f as! AXUIElement
+    if isSettableTextField(candidate) {
+        focusedEl = candidate
+    }
+}
+
+// 2. Walk tree for a focused+settable text field
+if focusedEl == nil {
+    focusedEl = findFocusedTextField(window, 25)
+}
+
+// 3. Fall back: first settable text field anywhere in the tree
+if focusedEl == nil {
+    focusedEl = findFirstSettableTextField(window, 25)
+}
+
+guard let target = focusedEl else {
+    fputs("ERROR: no focused element found — tap the text field first\n", stderr); exit(1)
+}
+
+// Read text from the environment variable
+let text = ProcessInfo.processInfo.environment["SIM_TYPE_TEXT"] ?? ""
+
+// Set the value directly
+let result = AXUIElementSetAttributeValue(target, "AXValue" as CFString, text as CFTypeRef)
+if result != .success {
+    fputs("ERROR: AXUIElementSetAttributeValue failed (code \(result.rawValue)) — field may not support direct value setting\n", stderr)
+    exit(1)
+}
+
+print("OK")
+SWIFTEOF
+  ) || die "type: failed — $out"
+
+  if [[ "$out" == ERROR:* ]]; then
+    die "type: $out"
+  fi
+}
+
+cmd_type() {
+  [[ $# -ge 1 ]] || die "Usage: sim type <text>"
+  local text="$1"
+  _bootstrap
+
+  # Prefer WDA setValue (goes through proper iOS input path, handles Unicode/spaces correctly).
+  # Falls back to AX direct-value setting if WDA is not running or has no active element.
+  if _wda_type "$text"; then
+    echo "Typed (WDA): $text"
+    return 0
+  fi
+
+  # WDA not available or no active element — fall back to AX API
+  _type_cgevent "$text"
+  echo "Typed: $text"
+}
diff --git a/cli/src/commands/test/ios/simclaw/lib/simclaw/wait.sh b/cli/src/commands/test/ios/simclaw/lib/simclaw/wait.sh
new file mode 100644
index 00000000..4ebb6cc7
--- /dev/null
+++ b/cli/src/commands/test/ios/simclaw/lib/simclaw/wait.sh
@@ -0,0 +1,197 @@
+# lib/simclaw/wait.sh — wait-for and wait-for-stable commands
+[[ -n "${_SIM_WAIT_LOADED:-}" ]] && return 0; _SIM_WAIT_LOADED=1
+
+source "$SIM_LIB/bootstrap.sh"
+
+cmd_wait_for() {
+  [[ $# -ge 1 ]] || die "Usage: sim wait-for <label> [timeout_seconds]"
+  local search_label="$1"
+  local timeout="${2:-10}"
+  # Bootstrap to get SIM_NAME for window targeting when multiple simulators are open.
+  _bootstrap
+
+  local out exit_code
+  out=$(swift - "$search_label" "$timeout" "${SIM_NAME} – ${SIM_OS}" "$SIM_SCREEN_X" "$SIM_SCREEN_Y" 2>&1 << SWIFTEOF
+import ApplicationServices
+import AppKit
+import Foundation
+
+let args = CommandLine.arguments
+let searchLabel = args.count > 1 ? args[1] : ""
+let timeoutSec  = Double(args.count > 2 ? args[2] : "10") ?? 10.0
+let deviceName  = args.count > 3 ? args[3] : ""
+let screenX     = Double(args.count > 4 ? args[4] : "0") ?? 0.0
+let screenY     = Double(args.count > 5 ? args[5] : "0") ?? 0.0
+
+guard let simApp = NSWorkspace.shared.runningApplications
+    .first(where: { \$0.bundleIdentifier == "com.apple.iphonesimulator" }) else {
+    fputs("ERROR: Simulator not running\n", stderr); exit(1)
+}
+let pid = simApp.processIdentifier
+let axApp = AXUIElementCreateApplication(pid)
+
+func getAttr(_ el: AXUIElement, _ attr: String) -> AnyObject? {
+    var v: CFTypeRef?
+    guard AXUIElementCopyAttributeValue(el, attr as CFString, &v) == .success else { return nil }
+    return v as AnyObject
+}
+func getLabel(_ el: AXUIElement) -> String {
+    for a in ["AXDescription", "AXTitle", "AXLabel", "AXValue"] {
+        if let s = getAttr(el, a) as? String, !s.isEmpty { return s }
+    }
+    return ""
+}
+func treeContains(_ el: AXUIElement, _ label: String, depth: Int = 0) -> Bool {
+    guard depth < 25 else { return false }
+    if getLabel(el).localizedCaseInsensitiveContains(label) { return true }
+    guard let ch = getAttr(el, "AXChildren") as? [AXUIElement] else { return false }
+    return ch.contains { treeContains(\$0, label, depth: depth + 1) }
+}
+
+$(cat "$SIM_LIB/swift/pickwindow.swift")
+
+func checkTree() -> Bool {
+    var ref: CFTypeRef?
+    AXUIElementCopyAttributeValue(axApp, "AXWindows" as CFString, &ref)
+    guard let wins = ref as? [AXUIElement],
+          let win = pickWindow(wins, screenX: screenX, screenY: screenY, deviceName: deviceName) else { return false }
+    return treeContains(win, searchLabel)
+}
+
+// Immediate check
+if checkTree() { print("READY: \(searchLabel)"); exit(0) }
+
+// Shared found flag
+final class State { var found = false }
+let state = State()
+
+// AXObserver callback
+let callback: AXObserverCallback = { _, _, _, refcon in
+    let s = Unmanaged<State>.fromOpaque(refcon!).takeUnretainedValue()
+    guard !s.found else { return }
+    if checkTree() {
+        s.found = true
+        print("READY: \(searchLabel)")
+        CFRunLoopStop(CFRunLoopGetCurrent())
+    }
+}
+
+var observer: AXObserver?
+guard AXObserverCreate(pid, callback, &observer) == .success, let obs = observer else {
+    fputs("ERROR: AXObserverCreate failed\n", stderr); exit(1)
+}
+let ctxPtr = Unmanaged.passRetained(state).toOpaque()
+CFRunLoopAddSource(CFRunLoopGetCurrent(), AXObserverGetRunLoopSource(obs), .defaultMode)
+AXObserverAddNotification(obs, axApp, kAXLayoutChangedNotification as CFString, ctxPtr)
+
+// Safety-net polling (1.5s interval) catches async changes between AX notifications
+let pollTimer = DispatchSource.makeTimerSource(queue: .main)
+pollTimer.schedule(deadline: .now() + 1.5, repeating: 1.5)
+pollTimer.setEventHandler {
+    guard !state.found else { pollTimer.cancel(); return }
+    if checkTree() {
+        state.found = true
+        print("READY: \(searchLabel)")
+        CFRunLoopStop(CFRunLoopGetCurrent())
+    }
+}
+pollTimer.resume()
+
+// Timeout
+let timeoutTimer = DispatchSource.makeTimerSource(queue: .main)
+timeoutTimer.schedule(deadline: .now() + timeoutSec)
+timeoutTimer.setEventHandler { CFRunLoopStop(CFRunLoopGetCurrent()) }
+timeoutTimer.resume()
+
+CFRunLoopRun()
+pollTimer.cancel()
+timeoutTimer.cancel()
+
+if state.found { exit(0) }
+fputs("ERROR: wait-for timed out after \(Int(timeoutSec))s waiting for: \(searchLabel)\n", stderr)
+exit(1)
+SWIFTEOF
+  )
+  exit_code=$?
+  if [[ $exit_code -eq 0 ]]; then
+    echo "$out"
+  else
+    die "${out#ERROR: }"
+  fi
+}
+
+cmd_wait_for_stable() {
+  local timeout="${1:-5}"
+  _bootstrap
+
+  local out exit_code
+  out=$(swift - "$timeout" "${SIM_NAME} – ${SIM_OS}" "$SIM_SCREEN_X" "$SIM_SCREEN_Y" 2>&1 << SWIFTEOF
+import ApplicationServices
+import AppKit
+import Foundation
+
+let args = CommandLine.arguments
+let timeoutSec = Double(args.count > 1 ? args[1] : "5") ?? 5.0
+let deviceName = args.count > 2 ? args[2] : ""
+let screenX    = Double(args.count > 3 ? args[3] : "0") ?? 0.0
+let screenY    = Double(args.count > 4 ? args[4] : "0") ?? 0.0
+
+guard let simApp = NSWorkspace.shared.runningApplications
+    .first(where: { \$0.bundleIdentifier == "com.apple.iphonesimulator" }) else {
+    fputs("ERROR: Simulator not running\n", stderr); exit(1)
+}
+let pid = simApp.processIdentifier
+let axApp = AXUIElementCreateApplication(pid)
+
+func getAttr(_ el: AXUIElement, _ attr: String) -> AnyObject? {
+    var v: CFTypeRef?
+    guard AXUIElementCopyAttributeValue(el, attr as CFString, &v) == .success else { return nil }
+    return v as AnyObject
+}
+
+$(cat "$SIM_LIB/swift/pickwindow.swift")
+
+func snapshot(_ el: AXUIElement, _ depth: Int) -> String {
+    guard depth >= 0 else { return "" }
+    var parts: [String] = []
+    for attr in ["AXRole", "AXLabel", "AXTitle", "AXDescription", "AXValue"] {
+        if let v = getAttr(el, attr) as? String, !v.isEmpty { parts.append("\(attr)=\(v)") }
+    }
+    if let posVal = getAttr(el, kAXPositionAttribute),
+       let sizeVal = getAttr(el, kAXSizeAttribute) {
+        var pt = CGPoint.zero; var sz = CGSize.zero
+        AXValueGetValue(posVal as! AXValue, .cgPoint, &pt)
+        AXValueGetValue(sizeVal as! AXValue, .cgSize, &sz)
+        parts.append("pos=\(Int(pt.x)),\(Int(pt.y))|sz=\(Int(sz.width)),\(Int(sz.height))")
+    }
+    guard let children = getAttr(el, "AXChildren") as? [AXUIElement] else { return parts.joined(separator: "|") }
+    let childSnaps = children.map { snapshot(\$0, depth - 1) }.joined(separator: ";")
+    return parts.joined(separator: "|") + "{" + childSnaps + "}"
+}
+func takeSnapshot() -> String {
+    var ref: CFTypeRef?
+    AXUIElementCopyAttributeValue(axApp, "AXWindows" as CFString, &ref)
+    guard let wins = ref as? [AXUIElement],
+          let win = pickWindow(wins, screenX: screenX, screenY: screenY, deviceName: deviceName) else { return "" }
+    return snapshot(win, 25)
+}
+
+let deadline = Date().addingTimeInterval(timeoutSec)
+var prev = takeSnapshot()
+repeat {
+    Thread.sleep(forTimeInterval: 0.2)
+    let curr = takeSnapshot()
+    if curr == prev && !curr.isEmpty { print("STABLE"); exit(0) }
+    prev = curr
+} while Date() < deadline
+fputs("ERROR: wait-for-stable timed out after \(Int(timeoutSec))s\n", stderr)
+exit(1)
+SWIFTEOF
+  )
+  exit_code=$?
+  if [[ $exit_code -eq 0 ]]; then
+    echo "$out"
+  else
+    die "${out#ERROR: }"
+  fi
+}
diff --git a/cli/src/commands/test/ios/simclaw/lib/simclaw/wda.sh b/cli/src/commands/test/ios/simclaw/lib/simclaw/wda.sh
new file mode 100644
index 00000000..9a7c6f8d
--- /dev/null
+++ b/cli/src/commands/test/ios/simclaw/lib/simclaw/wda.sh
@@ -0,0 +1,495 @@
+# lib/simclaw/wda.sh — WDA session management and touch primitives
+[[ -n "${_SIM_WDA_LOADED:-}" ]] && return 0; _SIM_WDA_LOADED=1
+
+source "$SIM_LIB/bootstrap.sh"
+source "$SIM_LIB/coords.sh"
+
+# WDA cache version. Bump this whenever `_wda_patch_ios_compat` changes so any
+# existing cached WDA build gets wiped and re-built + re-patched on next setup.
+# Cached builds carry a `.patch_version` stamp inside their derived data dir;
+# a mismatch triggers a clean rebuild in cmd_setup.
+WDA_PATCH_VERSION="2"
+
+# _wda_derived_path
+# Returns the per-iOS-version WDA DerivedData path so each iOS runtime gets its
+# own cache. Without this, a WDA build patched for one runtime (say iOS 26) gets
+# silently reused on a different runtime (say iOS 18), where it either fails to
+# launch or behaves incorrectly. Per-iOS caches also let qa-branch test across
+# multiple iOS versions in parallel without the caches colliding.
+# Requires SIM_OS to be populated (call after `_bootstrap`).
+_wda_derived_path() {
+  local slug="${SIM_OS// /-}"   # "iOS 26.2" → "iOS-26.2"
+  echo "/tmp/WDA_DerivedData_${slug}"
+}
+
+# ── WDA Touch Backend ─────────────────────────────────────────────────────────
+#
+# All touch injection goes through WebDriverAgent (WDA), which runs as an
+# XCUITest runner inside each simulator. The flow is:
+#   curl W3C Actions JSON → WDA HTTP server → XCTest framework →
+#   testmanagerd socket (UDID-scoped) → synthetic IOHIDEvent
+#
+# Because the channel is scoped to a specific simulator UDID via testmanagerd,
+# there is no window-focus dependency and no need for a global serialization
+# queue. Multiple simulators can receive taps concurrently.
+#
+# Coordinate space: WDA accepts iOS UIKit logical points (not pixels, not macOS
+# screen coordinates). The functions below receive macOS screen coordinates
+# (from the internal to_screen_x/to_screen_y mapping) and reverse-map them
+# back to logical points before sending to WDA.
+
+# _tap_cgevent <screen_x> <screen_y>
+# Despite the historical name, this uses WDA W3C pointer actions (not CGEvent).
+# Accepts macOS screen coordinates and reverse-maps to iOS logical UIKit points.
+# Sends a W3C Actions sequence: pointerMove → pointerDown → pause(100ms) → pointerUp.
+# The request is UDID-scoped via the cached WDA session on WDA_PORT.
+_tap_cgevent() {
+  local sx="$1" sy="$2"
+  _wda_ensure
+  # Reverse map macOS screen coords → iOS logical points: logical = (screen - origin) / zoom
+  local lx ly
+  lx=$(awk "BEGIN { printf \"%d\", ($sx - $SIM_SCREEN_X) / $SIM_ZOOM + 0.5 }")
+  ly=$(awk "BEGIN { printf \"%d\", ($sy - $SIM_SCREEN_Y) / $SIM_ZOOM + 0.5 }")
+
+  local body
+  body=$(python3 -c "import json; print(json.dumps({'actions':[{'type':'pointer','id':'f1','parameters':{'pointerType':'touch'},'actions':[{'type':'pointerMove','duration':0,'x':${lx},'y':${ly}},{'type':'pointerDown','button':0},{'type':'pause','duration':100},{'type':'pointerUp','button':0}]}]}))")
+
+  local resp http_code
+  resp=$(curl -s -w "\n%{http_code}" -X POST \
+    -H "Content-Type: application/json" \
+    -d "$body" \
+    --max-time 10 \
+    "http://localhost:${WDA_PORT}/session/${WDA_SESSION}/actions" 2>/dev/null) || \
+    die "WDA tap: curl failed at logical (${lx},${ly})"
+  http_code=$(echo "$resp" | tail -1)
+  [[ "$http_code" == "200" ]] \
+    || die "WDA tap: HTTP ${http_code} at logical (${lx},${ly}). Response: $(echo "$resp" | head -1)"
+}
+
+# _swipe_cgevent <sx1> <sy1> <sx2> <sy2> [steps=25] [step_ms=20]
+# Despite the historical name, this uses WDA W3C pointer actions (not CGEvent).
+# Accepts macOS screen coordinates; reverse-maps to iOS logical UIKit points.
+# Sends a W3C Actions sequence: pointerMove(start) → pointerDown → pointerMove(end,
+# duration=steps*step_ms ms) → pointerUp. The duration parameter is how WDA
+# interpolates the finger movement — longer duration = slower, smoother swipe.
+# Default: 25 steps × 20ms = 500ms total swipe duration.
+# All coordinates are UDID-scoped via testmanagerd — no global queue needed.
+# _wda_swipe <lx1> <ly1> <lx2> <ly2> [duration_ms=500]
+# Sends a WDA W3C pointer swipe directly in iOS logical coordinates.
+# No macOS ↔ iOS coordinate conversion — avoids all orientation issues.
+_wda_swipe() {
+  local lx1="$1" ly1="$2" lx2="$3" ly2="$4"
+  local duration_ms="${5:-500}"
+  _wda_ensure
+
+  local body
+  body=$(python3 -c "import json; print(json.dumps({'actions':[{'type':'pointer','id':'f1','parameters':{'pointerType':'touch'},'actions':[{'type':'pointerMove','duration':0,'x':${lx1},'y':${ly1}},{'type':'pointerDown','button':0},{'type':'pointerMove','duration':${duration_ms},'x':${lx2},'y':${ly2}},{'type':'pointerUp','button':0}]}]}))")
+
+  local resp http_code
+  resp=$(curl -s -w "\n%{http_code}" -X POST \
+    -H "Content-Type: application/json" \
+    -d "$body" \
+    --max-time 15 \
+    "http://localhost:${WDA_PORT}/session/${WDA_SESSION}/actions" 2>/dev/null) || \
+    die "WDA swipe: curl failed from logical (${lx1},${ly1}) to (${lx2},${ly2})"
+  http_code=$(echo "$resp" | tail -1)
+  [[ "$http_code" == "200" ]] \
+    || die "WDA swipe: HTTP ${http_code}. Response: $(echo "$resp" | head -1)"
+}
+
+# _wda_tap <lx> <ly>
+# Sends a WDA W3C pointer tap directly in iOS logical coordinates.
+_wda_tap() {
+  local lx="$1" ly="$2"
+  _wda_ensure
+
+  local body
+  body=$(python3 -c "import json; print(json.dumps({'actions':[{'type':'pointer','id':'f1','parameters':{'pointerType':'touch'},'actions':[{'type':'pointerMove','duration':0,'x':${lx},'y':${ly}},{'type':'pointerDown','button':0},{'type':'pause','duration':100},{'type':'pointerUp','button':0}]}]}))")
+
+  local resp http_code
+  resp=$(curl -s -w "\n%{http_code}" -X POST \
+    -H "Content-Type: application/json" \
+    -d "$body" \
+    --max-time 10 \
+    "http://localhost:${WDA_PORT}/session/${WDA_SESSION}/actions" 2>/dev/null) || \
+    die "WDA tap: curl failed at logical (${lx},${ly})"
+  http_code=$(echo "$resp" | tail -1)
+  [[ "$http_code" == "200" ]] \
+    || die "WDA tap: HTTP ${http_code} at logical (${lx},${ly}). Response: $(echo "$resp" | head -1)"
+}
+
+_swipe_cgevent() {
+  local sx1="$1" sy1="$2" sx2="$3" sy2="$4"
+  local steps="${5:-25}"
+  local step_ms="${6:-20}"
+  local duration_ms=$(( steps * step_ms ))
+  _wda_ensure
+  # Reverse map macOS screen coords → iOS logical points (portrait-only, kept for compat)
+  local lx1 ly1 lx2 ly2
+  lx1=$(awk "BEGIN { printf \"%d\", ($sx1 - $SIM_SCREEN_X) / $SIM_ZOOM + 0.5 }")
+  ly1=$(awk "BEGIN { printf \"%d\", ($sy1 - $SIM_SCREEN_Y) / $SIM_ZOOM + 0.5 }")
+  lx2=$(awk "BEGIN { printf \"%d\", ($sx2 - $SIM_SCREEN_X) / $SIM_ZOOM + 0.5 }")
+  ly2=$(awk "BEGIN { printf \"%d\", ($sy2 - $SIM_SCREEN_Y) / $SIM_ZOOM + 0.5 }")
+  _wda_swipe "$lx1" "$ly1" "$lx2" "$ly2" "$duration_ms"
+}
+
+# _tap_wda <x> <y>
+# Non-fatal WDA tap — returns 1 on failure instead of die-ing.
+# Used by cmd_tap for graceful fallback to _tap_cgevent.
+_tap_wda() {
+  local x="$1" y="$2"
+  # Ensure we have a WDA session
+  _bootstrap || return 1
+
+  local resp rc=0
+  resp=$(curl -sf -X POST \
+    -H "Content-Type: application/json" \
+    -d "{\"actions\":[{\"type\":\"pointer\",\"id\":\"finger\",\"parameters\":{\"pointerType\":\"touch\"},\"actions\":[{\"type\":\"pointerMove\",\"duration\":0,\"x\":${x},\"y\":${y}},{\"type\":\"pointerDown\",\"button\":0},{\"type\":\"pause\",\"duration\":100},{\"type\":\"pointerUp\",\"button\":0}]}]}" \
+    --max-time 10 \
+    "http://localhost:${WDA_PORT}/session/${WDA_SESSION}/actions" 2>/dev/null) || rc=$?
+
+  if [[ $rc -ne 0 ]]; then
+    return 1
+  fi
+
+  # Check for WDA error response
+  local status
+  status=$(echo "$resp" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('status', d.get('value',{}).get('error','')))" 2>/dev/null) || true
+  if [[ -n "$status" ]] && [[ "$status" != "0" ]] && [[ "$status" != "" ]] && [[ "$status" != "None" ]]; then
+    return 1
+  fi
+
+  return 0
+}
+
+# _swipe_wda <x1> <y1> <x2> <y2> [duration_ms=800]
+# Non-fatal WDA swipe — returns 1 on failure instead of die-ing.
+# Used by cmd_swipe for graceful fallback to _swipe_cgevent.
+_swipe_wda() {
+  local x1="$1" y1="$2" x2="$3" y2="$4" duration="${5:-800}"
+  _bootstrap || return 1
+
+  curl -sf -X POST \
+    -H "Content-Type: application/json" \
+    -d "{\"actions\":[{\"type\":\"pointer\",\"id\":\"finger\",\"parameters\":{\"pointerType\":\"touch\"},\"actions\":[{\"type\":\"pointerMove\",\"duration\":0,\"x\":${x1},\"y\":${y1}},{\"type\":\"pointerDown\",\"button\":0},{\"type\":\"pointerMove\",\"duration\":${duration},\"x\":${x2},\"y\":${y2}},{\"type\":\"pointerUp\",\"button\":0}]}]}" \
+    --max-time 15 \
+    "http://localhost:${WDA_PORT}/session/${WDA_SESSION}/actions" \
+    > /dev/null 2>&1 || return 1
+}
+
+# _wda_type <text>
+# Sets text in the currently focused/active element via WDA's setValue endpoint.
+# This goes through the proper iOS input path (unlike the AX direct-value approach).
+# Requires WDA to be running (_wda_ensure must succeed).
+# Returns 0 on success, 1 on failure (caller falls back to _type_cgevent).
+_wda_type() {
+  local text="$1"
+  # Load WDA session — if not running, return 1 so caller can fall back
+  if [[ -z "$WDA_PORT" || -z "$WDA_SESSION" ]]; then
+    return 1
+  fi
+  # Quick liveness check
+  local http_code
+  http_code=$(curl -s -o /dev/null -w "%{http_code}" \
+    --max-time 3 \
+    "http://localhost:${WDA_PORT}/session/${WDA_SESSION}" 2>/dev/null) || true
+  if [[ "$http_code" != "200" ]]; then
+    return 1
+  fi
+
+  # Find the active/focused element
+  local active_resp
+  active_resp=$(curl -s --max-time 5 \
+    "http://localhost:${WDA_PORT}/session/${WDA_SESSION}/element/active" \
+    2>/dev/null) || return 1
+
+  local element_id
+  element_id=$(echo "$active_resp" | python3 -c \
+    "import sys,json; d=json.load(sys.stdin); v=d.get('value',{}); print(v.get('ELEMENT') or v.get('element-6066-11e4-a52e-4f735466cecf',''))" \
+    2>/dev/null) || return 1
+  [[ -n "$element_id" ]] || return 1
+
+  # Set value on the active element — goes through proper iOS input path
+  local body set_resp set_code
+  body=$(python3 -c "import json,sys; print(json.dumps({'value': [sys.argv[1]], 'text': sys.argv[1]}))" "$text" 2>/dev/null) || return 1
+  set_resp=$(curl -s -w "\n%{http_code}" -X POST \
+    -H "Content-Type: application/json" \
+    -d "$body" \
+    --max-time 10 \
+    "http://localhost:${WDA_PORT}/session/${WDA_SESSION}/element/${element_id}/value" \
+    2>/dev/null) || return 1
+  set_code=$(echo "$set_resp" | tail -1)
+  [[ "$set_code" == "200" ]] || return 1
+  return 0
+}
+
+# _wda_ensure — called at the start of every tap and swipe to validate that
+# WDA is running and the cached session is still alive. It checks two things:
+#   1. WDA_PORT and WDA_SESSION are non-empty (loaded from cache or wda-start).
+#   2. The session is live: GET /session/:id returns HTTP 200.
+# If either check fails, it dies with an actionable error telling the agent to
+# run `sim --device <UDID> wda-start <port>` to restart WDA.
+# This guard ensures every tap/swipe is UDID-scoped and routed correctly —
+# there is no fallback to CGEvent or any other global input injection.
+_wda_ensure() {
+  if [[ -z "$WDA_PORT" || -z "$WDA_SESSION" ]]; then
+    local udid_hint="${SIM_TARGET_UDID:-<UDID>}"
+    die "WDA not running. Start with: sim --device ${udid_hint} wda-start <port>"
+  fi
+  # Quick liveness check — GET /session/:id (WDA returns 200 if alive)
+  local http_code
+  http_code=$(curl -s -o /dev/null -w "%{http_code}" \
+    --max-time 3 \
+    "http://localhost:${WDA_PORT}/session/${WDA_SESSION}" 2>/dev/null) || true
+  if [[ "$http_code" != "200" ]]; then
+    # Session dead — clear cached values so the error message is clean
+    WDA_PORT=""
+    WDA_SESSION=""
+    local udid_hint="${SIM_TARGET_UDID:-<UDID>}"
+    die "WDA session is no longer alive (HTTP ${http_code:-timeout}). Restart with: sim --device ${udid_hint} wda-start <port>"
+  fi
+}
+
+# ── WDA Commands ─────────────────────────────────────────────────────────────
+
+# cmd_wda_start [port]
+#
+# _wda_patch_ios_compat <products_dir>
+#
+# Makes a WDA build (compiled with iOS 26+ SDK) backward-compatible with older
+# iOS simulator runtimes (e.g. iOS 18). Two problems are fixed:
+#
+# 1. WebDriverAgentLib links _LocationEssentials.framework, which only exists in
+#    iOS 26+ runtimes. Fix: redirect the load to CoreLocation.framework (which
+#    exports the same symbols on all iOS versions) via install_name_tool -change.
+#
+# 2. WDA binaries have LC_BUILD_VERSION minos=26.x, causing xcodebuild to reject
+#    them for older simulators. Fix: patch minos to 13.0 via xcrun vtool.
+#
+# Both patches are idempotent and preserve iOS 26 compatibility.
+# Runs automatically after WDA is built in cmd_setup.
+_wda_patch_ios_compat() {
+  local products_dir="$1"
+  local runner_app="$products_dir/Debug-iphonesimulator/WebDriverAgentRunner-Runner.app"
+  [[ -d "$runner_app" ]] || return 0
+
+  # Collect all WDA binaries that need patching
+  local -a bins=()
+  while IFS= read -r f; do
+    bins+=("$f")
+  done < <(find "$products_dir/Debug-iphonesimulator" \
+    \( -name "WebDriverAgentLib" -o -name "WebDriverAgentRunner" -o -name "WebDriverAgentRunner-Runner" \) \
+    -not -path "*/_CodeSignature/*" -type f 2>/dev/null)
+
+  [[ ${#bins[@]} -gt 0 ]] || return 0
+
+  local did_patch=false
+
+  for bin in "${bins[@]}"; do
+    local short
+    short=$(echo "$bin" | sed "s|.*/Debug-iphonesimulator/||")
+
+    # --- Redirect _LocationEssentials → CoreLocation ---
+    if otool -L "$bin" 2>/dev/null | grep -q "_LocationEssentials"; then
+      install_name_tool -change \
+        "/System/Library/Frameworks/_LocationEssentials.framework/_LocationEssentials" \
+        "/System/Library/Frameworks/CoreLocation.framework/CoreLocation" \
+        "$bin" 2>/dev/null
+      echo "    $short: redirected _LocationEssentials -> CoreLocation"
+      did_patch=true
+    fi
+
+    # --- Patch minos to 13.0 (keep sdk unchanged) ---
+    local current_minos
+    current_minos=$(xcrun vtool -show-build "$bin" 2>/dev/null \
+      | awk '/minos/{print $2}' | head -1) || true
+    if [[ -n "$current_minos" && "$current_minos" != "13.0" ]]; then
+      local current_sdk
+      current_sdk=$(xcrun vtool -show-build "$bin" 2>/dev/null \
+        | awk '/sdk/{print $2}' | head -1) || true
+      xcrun vtool -set-build-version 7 13.0 "${current_sdk:-26.2}" \
+        -replace -output "${bin}.patched" "$bin" 2>/dev/null
+      mv "${bin}.patched" "$bin"
+      echo "    $short: minos $current_minos -> 13.0"
+      did_patch=true
+    fi
+  done
+
+  if [[ "$did_patch" == "true" ]]; then
+    # Re-sign all modified bundles (inner to outer)
+    local top_wdalib="$products_dir/Debug-iphonesimulator/WebDriverAgentLib.framework"
+    local xctest_dir="$runner_app/PlugIns/WebDriverAgentRunner.xctest"
+    local inner_wdalib="$xctest_dir/Frameworks/WebDriverAgentLib.framework"
+    [[ -d "$top_wdalib" ]]   && codesign --force --sign - "$top_wdalib"   2>/dev/null || true
+    [[ -d "$inner_wdalib" ]] && codesign --force --sign - "$inner_wdalib" 2>/dev/null || true
+    [[ -d "$xctest_dir" ]]   && codesign --force --sign - "$xctest_dir"   2>/dev/null || true
+    [[ -d "$runner_app" ]]   && codesign --force --sign - "$runner_app"   2>/dev/null || true
+    echo "    Re-signed all WDA bundles."
+  else
+    echo "    WDA binaries already compatible — no patch needed."
+  fi
+}
+
+# cmd_wda_start [port]
+#
+# WebDriverAgent (WDA) is an Apple XCUITest-based HTTP server that runs inside
+# the iOS Simulator. It exposes a W3C WebDriver-compatible REST API for touch
+# injection, app control, and other automation primitives. All tap and swipe
+# commands in this tool use WDA as their touch backend.
+#
+# This command uses `xcodebuild test-without-building` against a pre-built WDA
+# binary located at /tmp/WDA_DerivedData_<iOS-X.Y> (per-iOS-version cache). The DerivedData directory must already
+# exist (built once via `xcodebuild build` against the WebDriverAgent project).
+# This avoids re-compiling WDA on every invocation.
+#
+# Port-to-UDID mapping: each running simulator needs its own port number so
+# that multiple simulators can have WDA running simultaneously without conflict.
+# Example: simulator A → port 8100, simulator B → port 8101.
+# Always pass --device <UDID> together with wda-start so the correct simulator
+# is targeted and the port/session are cached under that UDID's cache file.
+#
+# After WDA starts and its HTTP server is ready, this command POSTs to /session
+# to create a W3C session. The resulting session ID and port are cached in
+# /tmp/sim_bootstrap_cache_<UDID>.json so subsequent tap/swipe calls can reuse
+# them without re-running wda-start.
+cmd_wda_start() {
+  local port="${1:-8100}"
+  _bootstrap
+
+  local wda_derived
+  wda_derived=$(_wda_derived_path)
+  # WDA must be pre-built — this path is created by building WebDriverAgent once.
+  [[ -d "$wda_derived" ]] || die "WDA DerivedData not found at $wda_derived — run 'sim setup' first to build WDA for $SIM_OS"
+
+  # Find the WDA test runner app bundle inside the pre-built DerivedData
+  local wda_bundle
+  wda_bundle=$(find "$wda_derived" -name "WebDriverAgentRunner-Runner.app" 2>/dev/null | head -1)
+  [[ -n "$wda_bundle" ]] || die "WebDriverAgentRunner-Runner.app not found in $wda_derived"
+
+  # Find xctestrun — check WDA_DerivedData first, then fall back to Appium's pre-built xctestrun
+  local wda_xctestrun
+  wda_xctestrun=$(find "$wda_derived" -name "*.xctestrun" 2>/dev/null | head -1)
+  if [[ -z "$wda_xctestrun" ]]; then
+    # Appium ships pre-built WDA xctestrun files for each iOS version — use the matching one
+    local appium_wda_dir="$HOME/.appium/node_modules/appium-xcuitest-driver/node_modules/Build/Products"
+    local os_ver
+    os_ver=$(echo "$SIM_OS" | grep -oE '[0-9]+\.[0-9]+' | head -1)
+    wda_xctestrun=$(find "$appium_wda_dir" -name "*iphonesimulator${os_ver}*.xctestrun" 2>/dev/null | head -1)
+    if [[ -n "$wda_xctestrun" ]]; then
+      echo "Using Appium pre-built WDA xctestrun: $wda_xctestrun"
+    fi
+  fi
+  [[ -n "$wda_xctestrun" ]] || die "No .xctestrun file found in $wda_derived or Appium — rebuild WDA with build-for-testing"
+
+  echo "Starting WDA for UDID=${SIM_UDID} on port ${port}..."
+
+  # The xctestrun EnvironmentVariables block contains USE_PORT="" baked in at build time.
+  # That empty-string entry overrides any host-level `env USE_PORT=N` prefix, causing WDA
+  # to always fall back to its hardcoded default port (8100). Fix: patch a temp copy of the
+  # xctestrun with the correct USE_PORT value before launching, so xcodebuild reads it.
+  local patched_xctestrun
+  local wda_products_dir
+  wda_products_dir=$(dirname "$wda_xctestrun")
+  patched_xctestrun="${wda_products_dir}/wda_patched_${port}.xctestrun"
+  cp "$wda_xctestrun" "$patched_xctestrun"
+  /usr/libexec/PlistBuddy -c \
+    "Set :WebDriverAgentRunner:EnvironmentVariables:USE_PORT $port" \
+    "$patched_xctestrun" 2>/dev/null || true
+
+  # Launch WDA in the background using xcodebuild test-without-building.
+  local wda_log="/tmp/wda_${SIM_UDID}.log"
+  xcodebuild test-without-building \
+    -xctestrun "$patched_xctestrun" \
+    -destination "id=${SIM_UDID}" \
+    > "$wda_log" 2>&1 &
+  local wda_pid=$!
+  echo "WDA process PID: $wda_pid (log: $wda_log)"
+
+  # Wait up to 60s for WDA /status to become ready
+  echo -n "Waiting for WDA HTTP server on port ${port}..."
+  local attempts=0
+  local max_attempts=60
+  while [[ $attempts -lt $max_attempts ]]; do
+    local status_code
+    status_code=$(curl -s -o /dev/null -w "%{http_code}" \
+      --max-time 2 "http://localhost:${port}/status" 2>/dev/null) || true
+    if [[ "$status_code" == "200" ]]; then
+      echo " ready."
+      break
+    fi
+    echo -n "."
+    sleep 1
+    (( attempts++ )) || true
+  done
+
+  if [[ $attempts -ge $max_attempts ]]; then
+    die "WDA did not become ready on port ${port} within ${max_attempts}s. Check log: $wda_log"
+  fi
+
+  # Create a W3C WebDriver session. WDA requires an active session before
+  # accepting any /actions (tap/swipe) requests. The session ID is returned
+  # in the response body and cached in the bootstrap cache for reuse.
+  #
+  # If WDA_APP_BUNDLE_ID is set, include it in the session capabilities so
+  # WDA pins its active-application resolution to that specific app. This
+  # prevents the background-window mismatch bug on iPad simulators where
+  # WDA's hit-test heuristic (FBActiveAppDetectionPoint) selects a persistent
+  # background window (e.g. the onboarding/auth flow) instead of the visible
+  # foreground content.
+  echo "Creating WDA session..."
+  local session_caps session_resp
+  if [[ -n "${WDA_APP_BUNDLE_ID:-}" ]]; then
+    session_caps="{\"capabilities\":{\"alwaysMatch\":{\"bundleId\":\"${WDA_APP_BUNDLE_ID}\"}}}"
+  else
+    session_caps='{"capabilities":{"firstMatch":[{}]}}'
+  fi
+  session_resp=$(curl -s -X POST \
+    -H "Content-Type: application/json" \
+    -d "$session_caps" \
+    --max-time 15 \
+    "http://localhost:${port}/session" 2>/dev/null) \
+    || die "Failed to POST /session to WDA on port ${port}"
+
+  local session_id
+  session_id=$(echo "$session_resp" | python3 -c \
+    "import sys,json; d=json.load(sys.stdin); print(d.get('sessionId') or d.get('value',{}).get('sessionId',''))" \
+    2>/dev/null) || true
+
+  [[ -n "$session_id" ]] \
+    || die "WDA session creation failed. Response: $session_resp"
+
+  WDA_PORT="$port"
+  WDA_SESSION="$session_id"
+
+  # Belt-and-suspenders: pin defaultActiveApplication via Appium settings so
+  # that even if the session capability above is ignored, WDA's element queries
+  # resolve against the correct foreground app rather than any background window.
+  if [[ -n "${WDA_APP_BUNDLE_ID:-}" ]]; then
+    curl -s -X POST \
+      -H "Content-Type: application/json" \
+      -d "{\"settings\":{\"defaultActiveApplication\":\"${WDA_APP_BUNDLE_ID}\"}}" \
+      --max-time 5 \
+      "http://localhost:${port}/session/${WDA_SESSION}/appium/settings" \
+      > /dev/null 2>&1 || true
+    echo "WDA: pinned defaultActiveApplication to ${WDA_APP_BUNDLE_ID}"
+  fi
+
+  # Tune WDA serialization performance:
+  # - snapshotMaxDepth 15: prune deep subtrees (default 50), biggest speed win
+  # - snapshotMaxChildren 25: cap sibling count in list views
+  # - pageSourceExcludedAttributes: skip computed-per-element attrs (visible, accessible)
+  #   that WDA must derive rather than just read — confirmed significant speedup
+  curl -s -X POST \
+    -H "Content-Type: application/json" \
+    -d '{"settings":{"snapshotMaxDepth":15,"snapshotMaxChildren":25,"pageSourceExcludedAttributes":"visible,accessible"}}' \
+    --max-time 5 \
+    "http://localhost:${port}/session/${WDA_SESSION}/appium/settings" \
+    > /dev/null 2>&1 || true
+  echo "WDA: applied performance settings (snapshotMaxDepth=15, snapshotMaxChildren=25)"
+
+  # Persist port and session ID to the bootstrap cache so tap/swipe commands
+  # in subsequent invocations can reuse the running WDA without re-starting it.
+  _wda_write_cache
+
+  echo "WDA ready: port=${WDA_PORT} session=${WDA_SESSION}"
+}
diff --git a/cli/src/commands/test/ios/simclaw/revendor.sh b/cli/src/commands/test/ios/simclaw/revendor.sh
new file mode 100755
index 00000000..820ee224
--- /dev/null
+++ b/cli/src/commands/test/ios/simclaw/revendor.sh
@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Re-vendor the simClaw tree from a local checkout of the upstream repo.
+#
+# Usage:
+#   ./revendor.sh <path-to-mv-simclaw-ios>
+#
+# Copies bin/ + lib/simclaw/ from the upstream checkout into this directory,
+# then prints the upstream HEAD SHA and a diff of file names so you know
+# whether SIMCLAW_FILES in ../mod.rs needs updating.
+
+set -euo pipefail
+
+if [[ $# -ne 1 ]]; then
+  echo "Usage: $0 <path-to-mv-simclaw-ios>" >&2
+  exit 2
+fi
+
+UPSTREAM="$1"
+HERE="$(cd "$(dirname "$0")" && pwd)"
+
+[[ -d "$UPSTREAM/bin" && -d "$UPSTREAM/lib/simclaw" ]] \
+  || { echo "ERROR: $UPSTREAM does not look like mv-simclaw-ios (missing bin/ or lib/simclaw/)" >&2; exit 1; }
+
+echo "==> Snapshotting old file list"
+OLD_FILES=$(cd "$HERE" && find bin lib -type f 2>/dev/null | sort)
+
+echo "==> Clearing existing bin/ and lib/"
+rm -rf "$HERE/bin" "$HERE/lib"
+
+echo "==> Copying bin/ and lib/"
+cp -R "$UPSTREAM/bin" "$HERE/bin"
+cp -R "$UPSTREAM/lib" "$HERE/lib"
+
+echo "==> Diffing file list"
+NEW_FILES=$(cd "$HERE" && find bin lib -type f 2>/dev/null | sort)
+ADDED=$(comm -13 <(echo "$OLD_FILES") <(echo "$NEW_FILES"))
+REMOVED=$(comm -23 <(echo "$OLD_FILES") <(echo "$NEW_FILES"))
+
+if [[ -n "$ADDED" ]]; then
+  echo ""
+  echo "NEW files (must be added to SIMCLAW_FILES in ../mod.rs):"
+  echo "$ADDED" | sed 's/^/  + /'
+fi
+if [[ -n "$REMOVED" ]]; then
+  echo ""
+  echo "REMOVED files (must be removed from SIMCLAW_FILES in ../mod.rs):"
+  echo "$REMOVED" | sed 's/^/  - /'
+fi
+if [[ -z "$ADDED" && -z "$REMOVED" ]]; then
+  echo "No file additions or removals — manifest is still correct."
+fi
+
+echo ""
+if command -v git >/dev/null && [[ -d "$UPSTREAM/.git" ]]; then
+  SHA=$(git -C "$UPSTREAM" rev-parse HEAD)
+  SUBJECT=$(git -C "$UPSTREAM" log -1 --format='%s')
+  DATE=$(date -u +%Y-%m-%d)
+  echo "==> Upstream provenance"
+  echo "  Commit: $SHA"
+  echo "  Ref:    $SUBJECT"
+  echo "  Date:   $DATE"
+  echo ""
+  echo "Update these fields in VENDORED.md before committing."
+fi
diff --git a/cli/src/commands/test/mod.rs b/cli/src/commands/test/mod.rs
new file mode 100644
index 00000000..9289c95f
--- /dev/null
+++ b/cli/src/commands/test/mod.rs
@@ -0,0 +1,256 @@
+mod ios;
+mod platform;
+
+use clap::{Args, Subcommand, ValueEnum};
+use serde::Serialize;
+
+use crate::{
+    error::{TestError, WKCliError},
+    output::colored_println,
+};
+
+use platform::PlatformBackend;
+
+#[derive(Debug, Clone, Copy, ValueEnum)]
+pub enum Platform {
+    Ios,
+}
+
+#[derive(Debug, Args)]
+pub struct Test {
+    /// Target platform.
+    #[arg(long, value_enum)]
+    pub platform: Platform,
+
+    /// Target device by ID (UDID for iOS, serial for Android).
+    /// Falls back to the most recently booted device when omitted.
+    #[arg(long)]
+    pub device: Option<String>,
+
+    /// Override the WDA /source fetch timeout (seconds). Raise when working
+    /// with large accessibility trees where layout-map exceeds the default 8s.
+    #[arg(long)]
+    pub source_timeout: Option<u32>,
+
+    #[command(subcommand)]
+    pub subcommand: TestSubcommand,
+}
+
+#[derive(Debug, Subcommand)]
+pub enum TestSubcommand {
+    /// One-shot: boot simulator, build WDA, install app, start WDA, launch app.
+    Setup {
+        /// Path to .app bundle or bundle identifier.
+        app: String,
+        /// Automation server HTTP port.
+        #[arg(long, default_value_t = 8100)]
+        port: u16,
+    },
+    /// Start the automation server (WebDriverAgent on iOS).
+    Start {
+        #[arg(long, default_value_t = 8100)]
+        port: u16,
+    },
+    /// Print booted device info and screen bounds.
+    Status,
+    /// Verify the device, automation server, and host toolchain are healthy.
+    Doctor,
+    /// Kill stale automation server processes and clear cached session state.
+    Teardown,
+    /// Re-pin and activate the target app so it is in the foreground.
+    Activate {
+        /// Bundle identifier. Defaults to the script's configured default.
+        bundle_id: Option<String>,
+    },
+    /// Full structured JSON snapshot of the current screen.
+    LayoutMap,
+    /// Get the current screen title.
+    Title,
+    /// Tap at logical coordinates.
+    Tap { x: f64, y: f64 },
+    /// Tap an element by accessibility label. Waits for the UI to settle and
+    /// returns the resulting layout-map unless --no-wait is set.
+    TapOn {
+        label: String,
+        /// Wait until this label appears before returning.
+        #[arg(long)]
+        wait_for: Option<String>,
+        /// Seconds to wait for the post-tap transition.
+        #[arg(long, default_value_t = 5)]
+        timeout: u32,
+        /// Fire-and-forget: skip the wait and don't return a layout-map.
+        #[arg(long)]
+        no_wait: bool,
+    },
+    /// Swipe between two points.
+    Swipe {
+        x1: f64,
+        y1: f64,
+        x2: f64,
+        y2: f64,
+        #[arg(long, default_value_t = 10)]
+        steps: u32,
+        #[arg(long, default_value_t = 50)]
+        step_ms: u32,
+    },
+    /// Scroll the screen.
+    Scroll {
+        #[command(subcommand)]
+        kind: ScrollKind,
+    },
+    /// Type text into the focused field.
+    Type { text: String },
+    /// Block until a label appears, or (with --stable) until the UI stops changing.
+    Wait {
+        /// Accessibility label to wait for. Required unless --stable is set.
+        label: Option<String>,
+        /// Wait for UI stability instead of a specific label.
+        #[arg(long)]
+        stable: bool,
+        /// Max seconds to wait.
+        #[arg(long, default_value_t = 10)]
+        timeout: u32,
+    },
+    /// Find an element by label.
+    FindElement { label: String },
+    /// Hit-test the element at a coordinate.
+    HitTest { x: f64, y: f64 },
+    /// Dump the accessibility tree as JSON.
+    Describe {
+        depth: Option<u32>,
+        #[arg(short, long)]
+        interactive: bool,
+    },
+    /// Capture a PNG screenshot.
+    Screenshot { output: String },
+}
+
+#[derive(Debug, Subcommand)]
+pub enum ScrollKind {
+    /// Scroll up (reveals content above).
+    Up {
+        #[arg(long)]
+        x: Option<f64>,
+        #[arg(long)]
+        from: Option<f64>,
+        #[arg(long)]
+        to: Option<f64>,
+    },
+    /// Scroll down (reveals content below).
+    Down {
+        #[arg(long)]
+        x: Option<f64>,
+        #[arg(long)]
+        from: Option<f64>,
+        #[arg(long)]
+        to: Option<f64>,
+    },
+    /// Scroll until the given label is visible.
+    To {
+        label: String,
+        #[arg(long, default_value_t = 10)]
+        max_swipes: u32,
+    },
+}
+
+impl Test {
+    pub async fn handle_command(&self) -> Result<bool, WKCliError> {
+        let backend = self.backend();
+        dispatch(backend.as_ref(), &self.subcommand).await
+    }
+
+    fn backend(&self) -> Box<dyn PlatformBackend> {
+        match self.platform {
+            Platform::Ios => Box::new(ios::IosBackend::new(
+                self.device.clone(),
+                self.source_timeout,
+            )),
+        }
+    }
+}
+
+async fn dispatch(
+    backend: &dyn PlatformBackend,
+    subcommand: &TestSubcommand,
+) -> Result<bool, WKCliError> {
+    match subcommand {
+        TestSubcommand::Setup { app, port } => backend.setup(app, *port).await?,
+        TestSubcommand::Start { port } => backend.wda_start(*port).await?,
+        TestSubcommand::Status => backend.status().await?,
+        TestSubcommand::Doctor => backend.health_check().await?,
+        TestSubcommand::Teardown => backend.cleanup().await?,
+        TestSubcommand::Activate { bundle_id } => {
+            backend.ensure_foreground_app(bundle_id.as_deref()).await?
+        }
+        TestSubcommand::LayoutMap => print_json(&backend.layout_map().await?)?,
+        TestSubcommand::Title => println!("{}", backend.screen_title().await?),
+        TestSubcommand::Tap { x, y } => backend.tap(*x, *y).await?,
+        TestSubcommand::TapOn {
+            label,
+            wait_for,
+            timeout,
+            no_wait,
+        } => {
+            if *no_wait {
+                backend.tap_element(label).await?;
+            } else {
+                let layout = backend
+                    .tap_and_wait(label, wait_for.as_deref(), *timeout)
+                    .await?;
+                print_json(&layout)?;
+            }
+        }
+        TestSubcommand::Swipe {
+            x1,
+            y1,
+            x2,
+            y2,
+            steps,
+            step_ms,
+        } => backend.swipe(*x1, *y1, *x2, *y2, *steps, *step_ms).await?,
+        TestSubcommand::Scroll { kind } => match kind {
+            ScrollKind::Up { x, from, to } => backend.scroll_up(*x, *from, *to).await?,
+            ScrollKind::Down { x, from, to } => backend.scroll_down(*x, *from, *to).await?,
+            ScrollKind::To { label, max_swipes } => {
+                backend.scroll_to_visible(label, *max_swipes).await?
+            }
+        },
+        TestSubcommand::Type { text } => backend.type_text(text).await?,
+        TestSubcommand::Wait {
+            label,
+            stable,
+            timeout,
+        } => match (label, *stable) {
+            (Some(l), false) => backend.wait_for(l, *timeout).await?,
+            (None, true) => backend.wait_for_stable(*timeout).await?,
+            (Some(_), true) => {
+                return Err(WKCliError::TestError(TestError::InvalidInvocation(
+                    "wait: --stable is mutually exclusive with a label argument".into(),
+                )));
+            }
+            (None, false) => {
+                return Err(WKCliError::TestError(TestError::InvalidInvocation(
+                    "wait: provide a <label> or pass --stable".into(),
+                )));
+            }
+        },
+        TestSubcommand::FindElement { label } => print_json(&backend.find_element(label).await?)?,
+        TestSubcommand::HitTest { x, y } => print_json(&backend.describe_point(*x, *y).await?)?,
+        TestSubcommand::Describe { depth, interactive } => {
+            print_json(&backend.describe(*depth, *interactive).await?)?
+        }
+        TestSubcommand::Screenshot { output } => backend.screenshot(output).await?,
+    }
+    Ok(true)
+}
+
+fn print_json<T: Serialize>(value: &T) -> Result<(), WKCliError> {
+    let rendered = serde_json::to_string_pretty(value).map_err(|e| {
+        WKCliError::TestError(TestError::InvalidScriptOutput {
+            subcommand: "<serialize>".into(),
+            reason: e.to_string(),
+        })
+    })?;
+    colored_println!("{rendered}");
+    Ok(())
+}
diff --git a/cli/src/commands/test/platform.rs b/cli/src/commands/test/platform.rs
new file mode 100644
index 00000000..1d735301
--- /dev/null
+++ b/cli/src/commands/test/platform.rs
@@ -0,0 +1,65 @@
+use async_trait::async_trait;
+
+use crate::error::WKCliError;
+
+// The JSON schemas from `layout-map`, `find-element`, `describe`, and
+// `describe-point` are owned by the simClaw team and haven't been frozen
+// into a stable contract yet. We pass the JSON through unchanged so the
+// consumer (pipe to `jq`, `from json` in nushell, etc.) can work with
+// whatever shape the script produces today. Tighten to typed structs
+// once the schema is contracted in the simClaw repo.
+pub type LayoutMap = serde_json::Value;
+pub type Element = serde_json::Value;
+
+#[async_trait]
+pub trait PlatformBackend: Send + Sync {
+    async fn setup(&self, app: &str, port: u16) -> Result<(), WKCliError>;
+    async fn wda_start(&self, port: u16) -> Result<(), WKCliError>;
+    async fn status(&self) -> Result<(), WKCliError>;
+    async fn layout_map(&self) -> Result<LayoutMap, WKCliError>;
+    async fn tap(&self, x: f64, y: f64) -> Result<(), WKCliError>;
+    async fn tap_element(&self, label: &str) -> Result<(), WKCliError>;
+    async fn tap_and_wait(
+        &self,
+        label: &str,
+        expected: Option<&str>,
+        timeout: u32,
+    ) -> Result<LayoutMap, WKCliError>;
+    async fn swipe(
+        &self,
+        x1: f64,
+        y1: f64,
+        x2: f64,
+        y2: f64,
+        steps: u32,
+        step_ms: u32,
+    ) -> Result<(), WKCliError>;
+    async fn scroll_up(
+        &self,
+        x: Option<f64>,
+        from_y: Option<f64>,
+        to_y: Option<f64>,
+    ) -> Result<(), WKCliError>;
+    async fn scroll_down(
+        &self,
+        x: Option<f64>,
+        from_y: Option<f64>,
+        to_y: Option<f64>,
+    ) -> Result<(), WKCliError>;
+    async fn scroll_to_visible(&self, label: &str, max_swipes: u32) -> Result<(), WKCliError>;
+    async fn type_text(&self, text: &str) -> Result<(), WKCliError>;
+    async fn wait_for(&self, label: &str, timeout: u32) -> Result<(), WKCliError>;
+    async fn wait_for_stable(&self, timeout: u32) -> Result<(), WKCliError>;
+    async fn screen_title(&self) -> Result<String, WKCliError>;
+    async fn find_element(&self, label: &str) -> Result<Element, WKCliError>;
+    async fn describe_point(&self, x: f64, y: f64) -> Result<serde_json::Value, WKCliError>;
+    async fn describe(
+        &self,
+        depth: Option<u32>,
+        interactive: bool,
+    ) -> Result<serde_json::Value, WKCliError>;
+    async fn screenshot(&self, output: &str) -> Result<(), WKCliError>;
+    async fn ensure_foreground_app(&self, bundle_id: Option<&str>) -> Result<(), WKCliError>;
+    async fn cleanup(&self) -> Result<(), WKCliError>;
+    async fn health_check(&self) -> Result<(), WKCliError>;
+}
diff --git a/cli/src/error.rs b/cli/src/error.rs
index 96e04966..d3a4d16e 100644
--- a/cli/src/error.rs
+++ b/cli/src/error.rs
@@ -46,6 +46,23 @@ pub enum WKCliError {
     UnableToParseYmlFile,
     #[error(transparent)]
     InquireError(#[from] inquire::error::InquireError),
+    #[error(transparent)]
+    TestError(#[from] TestError),
+}
+
+#[derive(Debug, ThisError)]
+pub enum TestError {
+    #[error("Failed to extract the test backend script: {0}")]
+    ScriptExtractionFailed(String),
+    #[error("`wukong test {subcommand}` failed (exit code: {exit_code:?})")]
+    ScriptFailed {
+        subcommand: String,
+        exit_code: Option<i32>,
+    },
+    #[error("`wukong test {subcommand}` produced unparseable output: {reason}")]
+    InvalidScriptOutput { subcommand: String, reason: String },
+    #[error("{0}")]
+    InvalidInvocation(String),
 }
 
 #[derive(Debug, ThisError)]
diff --git a/cli/tests/snapshots/completion__wukong_completion_bash.snap b/cli/tests/snapshots/completion__wukong_completion_bash.snap
index ac218b75..6c9497a3 100644
--- a/cli/tests/snapshots/completion__wukong_completion_bash.snap
+++ b/cli/tests/snapshots/completion__wukong_completion_bash.snap
@@ -1,6 +1,5 @@
 ---
 source: cli/tests/completion.rs
-assertion_line: 26
 expression: "std::str::from_utf8(&output.stdout).unwrap()"
 ---
 _wukong() {
@@ -47,6 +46,9 @@ _wukong() {
             wukong,skills)
                 cmd="wukong__skills"
                 ;;
+            wukong,test)
+                cmd="wukong__test"
+                ;;
             wukong,tui)
                 cmd="wukong__tui"
                 ;;
@@ -254,6 +256,9 @@ _wukong() {
             wukong__help,skills)
                 cmd="wukong__help__skills"
                 ;;
+            wukong__help,test)
+                cmd="wukong__help__test"
+                ;;
             wukong__help,tui)
                 cmd="wukong__help__tui"
                 ;;
@@ -335,6 +340,69 @@ _wukong() {
             wukong__help__skills,update)
                 cmd="wukong__help__skills__update"
                 ;;
+            wukong__help__test,activate)
+                cmd="wukong__help__test__activate"
+                ;;
+            wukong__help__test,describe)
+                cmd="wukong__help__test__describe"
+                ;;
+            wukong__help__test,doctor)
+                cmd="wukong__help__test__doctor"
+                ;;
+            wukong__help__test,find-element)
+                cmd="wukong__help__test__find__element"
+                ;;
+            wukong__help__test,hit-test)
+                cmd="wukong__help__test__hit__test"
+                ;;
+            wukong__help__test,layout-map)
+                cmd="wukong__help__test__layout__map"
+                ;;
+            wukong__help__test,screenshot)
+                cmd="wukong__help__test__screenshot"
+                ;;
+            wukong__help__test,scroll)
+                cmd="wukong__help__test__scroll"
+                ;;
+            wukong__help__test,setup)
+                cmd="wukong__help__test__setup"
+                ;;
+            wukong__help__test,start)
+                cmd="wukong__help__test__start"
+                ;;
+            wukong__help__test,status)
+                cmd="wukong__help__test__status"
+                ;;
+            wukong__help__test,swipe)
+                cmd="wukong__help__test__swipe"
+                ;;
+            wukong__help__test,tap)
+                cmd="wukong__help__test__tap"
+                ;;
+            wukong__help__test,tap-on)
+                cmd="wukong__help__test__tap__on"
+                ;;
+            wukong__help__test,teardown)
+                cmd="wukong__help__test__teardown"
+                ;;
+            wukong__help__test,title)
+                cmd="wukong__help__test__title"
+                ;;
+            wukong__help__test,type)
+                cmd="wukong__help__test__type"
+                ;;
+            wukong__help__test,wait)
+                cmd="wukong__help__test__wait"
+                ;;
+            wukong__help__test__scroll,down)
+                cmd="wukong__help__test__scroll__down"
+                ;;
+            wukong__help__test__scroll,to)
+                cmd="wukong__help__test__scroll__to"
+                ;;
+            wukong__help__test__scroll,up)
+                cmd="wukong__help__test__scroll__up"
+                ;;
             wukong__skills,add)
                 cmd="wukong__skills__add"
                 ;;
@@ -383,6 +451,153 @@ _wukong() {
             wukong__skills__help,update)
                 cmd="wukong__skills__help__update"
                 ;;
+            wukong__test,activate)
+                cmd="wukong__test__activate"
+                ;;
+            wukong__test,describe)
+                cmd="wukong__test__describe"
+                ;;
+            wukong__test,doctor)
+                cmd="wukong__test__doctor"
+                ;;
+            wukong__test,find-element)
+                cmd="wukong__test__find__element"
+                ;;
+            wukong__test,help)
+                cmd="wukong__test__help"
+                ;;
+            wukong__test,hit-test)
+                cmd="wukong__test__hit__test"
+                ;;
+            wukong__test,layout-map)
+                cmd="wukong__test__layout__map"
+                ;;
+            wukong__test,screenshot)
+                cmd="wukong__test__screenshot"
+                ;;
+            wukong__test,scroll)
+                cmd="wukong__test__scroll"
+                ;;
+            wukong__test,setup)
+                cmd="wukong__test__setup"
+                ;;
+            wukong__test,start)
+                cmd="wukong__test__start"
+                ;;
+            wukong__test,status)
+                cmd="wukong__test__status"
+                ;;
+            wukong__test,swipe)
+                cmd="wukong__test__swipe"
+                ;;
+            wukong__test,tap)
+                cmd="wukong__test__tap"
+                ;;
+            wukong__test,tap-on)
+                cmd="wukong__test__tap__on"
+                ;;
+            wukong__test,teardown)
+                cmd="wukong__test__teardown"
+                ;;
+            wukong__test,title)
+                cmd="wukong__test__title"
+                ;;
+            wukong__test,type)
+                cmd="wukong__test__type"
+                ;;
+            wukong__test,wait)
+                cmd="wukong__test__wait"
+                ;;
+            wukong__test__help,activate)
+                cmd="wukong__test__help__activate"
+                ;;
+            wukong__test__help,describe)
+                cmd="wukong__test__help__describe"
+                ;;
+            wukong__test__help,doctor)
+                cmd="wukong__test__help__doctor"
+                ;;
+            wukong__test__help,find-element)
+                cmd="wukong__test__help__find__element"
+                ;;
+            wukong__test__help,help)
+                cmd="wukong__test__help__help"
+                ;;
+            wukong__test__help,hit-test)
+                cmd="wukong__test__help__hit__test"
+                ;;
+            wukong__test__help,layout-map)
+                cmd="wukong__test__help__layout__map"
+                ;;
+            wukong__test__help,screenshot)
+                cmd="wukong__test__help__screenshot"
+                ;;
+            wukong__test__help,scroll)
+                cmd="wukong__test__help__scroll"
+                ;;
+            wukong__test__help,setup)
+                cmd="wukong__test__help__setup"
+                ;;
+            wukong__test__help,start)
+                cmd="wukong__test__help__start"
+                ;;
+            wukong__test__help,status)
+                cmd="wukong__test__help__status"
+                ;;
+            wukong__test__help,swipe)
+                cmd="wukong__test__help__swipe"
+                ;;
+            wukong__test__help,tap)
+                cmd="wukong__test__help__tap"
+                ;;
+            wukong__test__help,tap-on)
+                cmd="wukong__test__help__tap__on"
+                ;;
+            wukong__test__help,teardown)
+                cmd="wukong__test__help__teardown"
+                ;;
+            wukong__test__help,title)
+                cmd="wukong__test__help__title"
+                ;;
+            wukong__test__help,type)
+                cmd="wukong__test__help__type"
+                ;;
+            wukong__test__help,wait)
+                cmd="wukong__test__help__wait"
+                ;;
+            wukong__test__help__scroll,down)
+                cmd="wukong__test__help__scroll__down"
+                ;;
+            wukong__test__help__scroll,to)
+                cmd="wukong__test__help__scroll__to"
+                ;;
+            wukong__test__help__scroll,up)
+                cmd="wukong__test__help__scroll__up"
+                ;;
+            wukong__test__scroll,down)
+                cmd="wukong__test__scroll__down"
+                ;;
+            wukong__test__scroll,help)
+                cmd="wukong__test__scroll__help"
+                ;;
+            wukong__test__scroll,to)
+                cmd="wukong__test__scroll__to"
+                ;;
+            wukong__test__scroll,up)
+                cmd="wukong__test__scroll__up"
+                ;;
+            wukong__test__scroll__help,down)
+                cmd="wukong__test__scroll__help__down"
+                ;;
+            wukong__test__scroll__help,help)
+                cmd="wukong__test__scroll__help__help"
+                ;;
+            wukong__test__scroll__help,to)
+                cmd="wukong__test__scroll__help__to"
+                ;;
+            wukong__test__scroll__help,up)
+                cmd="wukong__test__scroll__help__up"
+                ;;
             *)
                 ;;
         esac
@@ -390,7 +605,7 @@ _wukong() {
 
     case "${cmd}" in
         wukong)
-            opts="-v -q -h -V --verbose --quiet --report --canary --help --version init application deployment dev config login google completion skills tui help"
+            opts="-v -q -h -V --verbose --quiet --report --canary --help --version init application deployment dev config login google completion skills tui test help"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 1 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
@@ -1384,7 +1599,7 @@ _wukong() {
             return 0
             ;;
         wukong__help)
-            opts="init application deployment dev config login google completion skills tui help"
+            opts="init application deployment dev config login google completion skills tui test help"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
@@ -1901,8 +2116,8 @@ _wukong() {
             COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
             return 0
             ;;
-        wukong__help__tui)
-            opts=""
+        wukong__help__test)
+            opts="setup start status doctor teardown activate layout-map title tap tap-on swipe scroll type wait find-element hit-test describe screenshot"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
@@ -1915,9 +2130,9 @@ _wukong() {
             COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
             return 0
             ;;
-        wukong__init)
-            opts="-v -q -h --verbose --quiet --report --canary --help"
-            if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
+        wukong__help__test__activate)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
             fi
@@ -1929,9 +2144,9 @@ _wukong() {
             COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
             return 0
             ;;
-        wukong__login)
-            opts="-v -q -h --verbose --quiet --report --canary --help"
-            if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
+        wukong__help__test__describe)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
             fi
@@ -1943,9 +2158,9 @@ _wukong() {
             COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
             return 0
             ;;
-        wukong__skills)
-            opts="-v -q -h --verbose --quiet --report --canary --help list find init publish add remove update help"
-            if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
+        wukong__help__test__doctor)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
             fi
@@ -1957,9 +2172,9 @@ _wukong() {
             COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
             return 0
             ;;
-        wukong__skills__add)
-            opts="-v -q -h --global --project --verbose --quiet --report --canary --help [NAME]"
-            if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
+        wukong__help__test__find__element)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
             fi
@@ -1971,9 +2186,9 @@ _wukong() {
             COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
             return 0
             ;;
-        wukong__skills__find)
-            opts="-v -q -h --verbose --quiet --report --canary --help <KEYWORD>"
-            if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
+        wukong__help__test__hit__test)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
             fi
@@ -1985,9 +2200,9 @@ _wukong() {
             COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
             return 0
             ;;
-        wukong__skills__help)
-            opts="list find init publish add remove update help"
-            if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
+        wukong__help__test__layout__map)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
             fi
@@ -1999,7 +2214,7 @@ _wukong() {
             COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
             return 0
             ;;
-        wukong__skills__help__add)
+        wukong__help__test__screenshot)
             opts=""
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
@@ -2013,7 +2228,63 @@ _wukong() {
             COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
             return 0
             ;;
-        wukong__skills__help__find)
+        wukong__help__test__scroll)
+            opts="up down to"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__help__test__scroll__down)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 5 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__help__test__scroll__to)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 5 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__help__test__scroll__up)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 5 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__help__test__setup)
             opts=""
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
@@ -2027,7 +2298,7 @@ _wukong() {
             COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
             return 0
             ;;
-        wukong__skills__help__help)
+        wukong__help__test__start)
             opts=""
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
@@ -2041,7 +2312,7 @@ _wukong() {
             COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
             return 0
             ;;
-        wukong__skills__help__init)
+        wukong__help__test__status)
             opts=""
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
@@ -2055,7 +2326,7 @@ _wukong() {
             COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
             return 0
             ;;
-        wukong__skills__help__list)
+        wukong__help__test__swipe)
             opts=""
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
@@ -2069,7 +2340,7 @@ _wukong() {
             COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
             return 0
             ;;
-        wukong__skills__help__publish)
+        wukong__help__test__tap)
             opts=""
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
@@ -2083,7 +2354,7 @@ _wukong() {
             COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
             return 0
             ;;
-        wukong__skills__help__remove)
+        wukong__help__test__tap__on)
             opts=""
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
@@ -2097,7 +2368,7 @@ _wukong() {
             COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
             return 0
             ;;
-        wukong__skills__help__update)
+        wukong__help__test__teardown)
             opts=""
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
@@ -2111,8 +2382,50 @@ _wukong() {
             COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
             return 0
             ;;
-        wukong__skills__init)
-            opts="-v -q -h --verbose --quiet --report --canary --help"
+        wukong__help__test__title)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__help__test__type)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__help__test__wait)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__help__tui)
+            opts=""
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
@@ -2125,9 +2438,9 @@ _wukong() {
             COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
             return 0
             ;;
-        wukong__skills__list)
+        wukong__init)
             opts="-v -q -h --verbose --quiet --report --canary --help"
-            if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
             fi
@@ -2139,8 +2452,36 @@ _wukong() {
             COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
             return 0
             ;;
-        wukong__skills__publish)
+        wukong__login)
             opts="-v -q -h --verbose --quiet --report --canary --help"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__skills)
+            opts="-v -q -h --verbose --quiet --report --canary --help list find init publish add remove update help"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__skills__add)
+            opts="-v -q -h --global --project --verbose --quiet --report --canary --help [NAME]"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
@@ -2153,8 +2494,8 @@ _wukong() {
             COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
             return 0
             ;;
-        wukong__skills__remove)
-            opts="-v -q -h --verbose --quiet --report --canary --help"
+        wukong__skills__find)
+            opts="-v -q -h --verbose --quiet --report --canary --help <KEYWORD>"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
@@ -2167,8 +2508,8 @@ _wukong() {
             COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
             return 0
             ;;
-        wukong__skills__update)
-            opts="-v -q -h --verbose --quiet --report --canary --help"
+        wukong__skills__help)
+            opts="list find init publish add remove update help"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
@@ -2181,6 +2522,956 @@ _wukong() {
             COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
             return 0
             ;;
+        wukong__skills__help__add)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__skills__help__find)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__skills__help__help)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__skills__help__init)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__skills__help__list)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__skills__help__publish)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__skills__help__remove)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__skills__help__update)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__skills__init)
+            opts="-v -q -h --verbose --quiet --report --canary --help"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__skills__list)
+            opts="-v -q -h --verbose --quiet --report --canary --help"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__skills__publish)
+            opts="-v -q -h --verbose --quiet --report --canary --help"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__skills__remove)
+            opts="-v -q -h --verbose --quiet --report --canary --help"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__skills__update)
+            opts="-v -q -h --verbose --quiet --report --canary --help"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test)
+            opts="-v -q -h --platform --device --source-timeout --verbose --quiet --report --canary --help setup start status doctor teardown activate layout-map title tap tap-on swipe scroll type wait find-element hit-test describe screenshot help"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                --platform)
+                    COMPREPLY=($(compgen -W "ios" -- "${cur}"))
+                    return 0
+                    ;;
+                --device)
+                    COMPREPLY=($(compgen -f "${cur}"))
+                    return 0
+                    ;;
+                --source-timeout)
+                    COMPREPLY=($(compgen -f "${cur}"))
+                    return 0
+                    ;;
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__activate)
+            opts="-v -q -h --verbose --quiet --report --canary --help [BUNDLE_ID]"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__describe)
+            opts="-i -v -q -h --interactive --verbose --quiet --report --canary --help [DEPTH]"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__doctor)
+            opts="-v -q -h --verbose --quiet --report --canary --help"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__find__element)
+            opts="-v -q -h --verbose --quiet --report --canary --help <LABEL>"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__help)
+            opts="setup start status doctor teardown activate layout-map title tap tap-on swipe scroll type wait find-element hit-test describe screenshot help"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__help__activate)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__help__describe)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__help__doctor)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__help__find__element)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__help__help)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__help__hit__test)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__help__layout__map)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__help__screenshot)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__help__scroll)
+            opts="up down to"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__help__scroll__down)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 5 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__help__scroll__to)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 5 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__help__scroll__up)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 5 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__help__setup)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__help__start)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__help__status)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__help__swipe)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__help__tap)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__help__tap__on)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__help__teardown)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__help__title)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__help__type)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__help__wait)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__hit__test)
+            opts="-v -q -h --verbose --quiet --report --canary --help <X> <Y>"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__layout__map)
+            opts="-v -q -h --verbose --quiet --report --canary --help"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__screenshot)
+            opts="-v -q -h --verbose --quiet --report --canary --help <OUTPUT>"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__scroll)
+            opts="-v -q -h --verbose --quiet --report --canary --help up down to help"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__scroll__down)
+            opts="-v -q -h --x --from --to --verbose --quiet --report --canary --help"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                --x)
+                    COMPREPLY=($(compgen -f "${cur}"))
+                    return 0
+                    ;;
+                --from)
+                    COMPREPLY=($(compgen -f "${cur}"))
+                    return 0
+                    ;;
+                --to)
+                    COMPREPLY=($(compgen -f "${cur}"))
+                    return 0
+                    ;;
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__scroll__help)
+            opts="up down to help"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__scroll__help__down)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 5 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__scroll__help__help)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 5 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__scroll__help__to)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 5 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__scroll__help__up)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 5 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__scroll__to)
+            opts="-v -q -h --max-swipes --verbose --quiet --report --canary --help <LABEL>"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                --max-swipes)
+                    COMPREPLY=($(compgen -f "${cur}"))
+                    return 0
+                    ;;
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__scroll__up)
+            opts="-v -q -h --x --from --to --verbose --quiet --report --canary --help"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                --x)
+                    COMPREPLY=($(compgen -f "${cur}"))
+                    return 0
+                    ;;
+                --from)
+                    COMPREPLY=($(compgen -f "${cur}"))
+                    return 0
+                    ;;
+                --to)
+                    COMPREPLY=($(compgen -f "${cur}"))
+                    return 0
+                    ;;
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__setup)
+            opts="-v -q -h --port --verbose --quiet --report --canary --help <APP>"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                --port)
+                    COMPREPLY=($(compgen -f "${cur}"))
+                    return 0
+                    ;;
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__start)
+            opts="-v -q -h --port --verbose --quiet --report --canary --help"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                --port)
+                    COMPREPLY=($(compgen -f "${cur}"))
+                    return 0
+                    ;;
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__status)
+            opts="-v -q -h --verbose --quiet --report --canary --help"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__swipe)
+            opts="-v -q -h --steps --step-ms --verbose --quiet --report --canary --help <X1> <Y1> <X2> <Y2>"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                --steps)
+                    COMPREPLY=($(compgen -f "${cur}"))
+                    return 0
+                    ;;
+                --step-ms)
+                    COMPREPLY=($(compgen -f "${cur}"))
+                    return 0
+                    ;;
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__tap)
+            opts="-v -q -h --verbose --quiet --report --canary --help <X> <Y>"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__tap__on)
+            opts="-v -q -h --wait-for --timeout --no-wait --verbose --quiet --report --canary --help <LABEL>"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                --wait-for)
+                    COMPREPLY=($(compgen -f "${cur}"))
+                    return 0
+                    ;;
+                --timeout)
+                    COMPREPLY=($(compgen -f "${cur}"))
+                    return 0
+                    ;;
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__teardown)
+            opts="-v -q -h --verbose --quiet --report --canary --help"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__title)
+            opts="-v -q -h --verbose --quiet --report --canary --help"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__type)
+            opts="-v -q -h --verbose --quiet --report --canary --help <TEXT>"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__test__wait)
+            opts="-v -q -h --stable --timeout --verbose --quiet --report --canary --help [LABEL]"
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 3 ]] ; then
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                --timeout)
+                    COMPREPLY=($(compgen -f "${cur}"))
+                    return 0
+                    ;;
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
         wukong__tui)
             opts="-v -q -h --verbose --quiet --report --canary --help"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
diff --git a/cli/tests/snapshots/completion__wukong_completion_fish.snap b/cli/tests/snapshots/completion__wukong_completion_fish.snap
index 53bbd46a..14d4c114 100644
--- a/cli/tests/snapshots/completion__wukong_completion_fish.snap
+++ b/cli/tests/snapshots/completion__wukong_completion_fish.snap
@@ -1,6 +1,5 @@
 ---
 source: cli/tests/completion.rs
-assertion_line: 52
 expression: "std::str::from_utf8(&output.stdout).unwrap()"
 ---
 # Print an optspec for argparse to handle cmd's options that are independent of any subcommand.
@@ -45,6 +44,7 @@ complete -c wukong -n "__fish_wukong_needs_command" -f -a "google" -d 'This comm
 complete -c wukong -n "__fish_wukong_needs_command" -f -a "completion" -d 'Generate wukong cli completions for your shell to stdout'
 complete -c wukong -n "__fish_wukong_needs_command" -f -a "skills" -d 'This command group contains the commands to manage agent skills locally'
 complete -c wukong -n "__fish_wukong_needs_command" -f -a "tui" -d 'Start TUI session'
+complete -c wukong -n "__fish_wukong_needs_command" -f -a "test" -d 'This command group contains the commands to drive device simulators/emulators for app testing'
 complete -c wukong -n "__fish_wukong_needs_command" -f -a "help" -d 'Print this message or the help of the given subcommand(s)'
 complete -c wukong -n "__fish_wukong_using_subcommand init" -s v -l verbose -d 'Use verbos output. More output per occurrence.  By default, it\'ll only report errors. `-v` show warnings `-vv` show info `-vvv` show debug `-vvvv` show trace'
 complete -c wukong -n "__fish_wukong_using_subcommand init" -s q -l quiet -d 'Do not print log message'
@@ -273,17 +273,168 @@ complete -c wukong -n "__fish_wukong_using_subcommand tui" -s q -l quiet -d 'Do
 complete -c wukong -n "__fish_wukong_using_subcommand tui" -l report -d 'Store the debugging log in the log file, which is located at ~/.config/wukong'
 complete -c wukong -n "__fish_wukong_using_subcommand tui" -l canary -d 'Use the Canary channel API'
 complete -c wukong -n "__fish_wukong_using_subcommand tui" -s h -l help -d 'Print help'
-complete -c wukong -n "__fish_wukong_using_subcommand help; and not __fish_seen_subcommand_from init application deployment dev config login google completion skills tui help" -f -a "init" -d 'Initialize Wukong\'s configurations'
-complete -c wukong -n "__fish_wukong_using_subcommand help; and not __fish_seen_subcommand_from init application deployment dev config login google completion skills tui help" -f -a "application" -d 'This command group contains the commands to interact with an application’s configurations'
-complete -c wukong -n "__fish_wukong_using_subcommand help; and not __fish_seen_subcommand_from init application deployment dev config login google completion skills tui help" -f -a "deployment" -d 'This command group contains the commands to view and interact with the Continuous Delivery pipeline of an application'
-complete -c wukong -n "__fish_wukong_using_subcommand help; and not __fish_seen_subcommand_from init application deployment dev config login google completion skills tui help" -f -a "dev" -d 'This command group contains the commands to interact with the local development environment'
-complete -c wukong -n "__fish_wukong_using_subcommand help; and not __fish_seen_subcommand_from init application deployment dev config login google completion skills tui help" -f -a "config" -d 'This command group contains the commands to view & interact with Wukong\'s configurations'
-complete -c wukong -n "__fish_wukong_using_subcommand help; and not __fish_seen_subcommand_from init application deployment dev config login google completion skills tui help" -f -a "login" -d 'Login to start using wukong command'
-complete -c wukong -n "__fish_wukong_using_subcommand help; and not __fish_seen_subcommand_from init application deployment dev config login google completion skills tui help" -f -a "google" -d 'This command group contains the commands to interact with Google services'
-complete -c wukong -n "__fish_wukong_using_subcommand help; and not __fish_seen_subcommand_from init application deployment dev config login google completion skills tui help" -f -a "completion" -d 'Generate wukong cli completions for your shell to stdout'
-complete -c wukong -n "__fish_wukong_using_subcommand help; and not __fish_seen_subcommand_from init application deployment dev config login google completion skills tui help" -f -a "skills" -d 'This command group contains the commands to manage agent skills locally'
-complete -c wukong -n "__fish_wukong_using_subcommand help; and not __fish_seen_subcommand_from init application deployment dev config login google completion skills tui help" -f -a "tui" -d 'Start TUI session'
-complete -c wukong -n "__fish_wukong_using_subcommand help; and not __fish_seen_subcommand_from init application deployment dev config login google completion skills tui help" -f -a "help" -d 'Print this message or the help of the given subcommand(s)'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and not __fish_seen_subcommand_from setup start status doctor teardown activate layout-map title tap tap-on swipe scroll type wait find-element hit-test describe screenshot help" -l platform -d 'Target platform' -r -f -a "{ios\t''}"
+complete -c wukong -n "__fish_wukong_using_subcommand test; and not __fish_seen_subcommand_from setup start status doctor teardown activate layout-map title tap tap-on swipe scroll type wait find-element hit-test describe screenshot help" -l device -d 'Target device by ID (UDID for iOS, serial for Android). Falls back to the most recently booted device when omitted' -r
+complete -c wukong -n "__fish_wukong_using_subcommand test; and not __fish_seen_subcommand_from setup start status doctor teardown activate layout-map title tap tap-on swipe scroll type wait find-element hit-test describe screenshot help" -l source-timeout -d 'Override the WDA /source fetch timeout (seconds). Raise when working with large accessibility trees where layout-map exceeds the default 8s' -r
+complete -c wukong -n "__fish_wukong_using_subcommand test; and not __fish_seen_subcommand_from setup start status doctor teardown activate layout-map title tap tap-on swipe scroll type wait find-element hit-test describe screenshot help" -s v -l verbose -d 'Use verbos output. More output per occurrence.  By default, it\'ll only report errors. `-v` show warnings `-vv` show info `-vvv` show debug `-vvvv` show trace'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and not __fish_seen_subcommand_from setup start status doctor teardown activate layout-map title tap tap-on swipe scroll type wait find-element hit-test describe screenshot help" -s q -l quiet -d 'Do not print log message'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and not __fish_seen_subcommand_from setup start status doctor teardown activate layout-map title tap tap-on swipe scroll type wait find-element hit-test describe screenshot help" -l report -d 'Store the debugging log in the log file, which is located at ~/.config/wukong'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and not __fish_seen_subcommand_from setup start status doctor teardown activate layout-map title tap tap-on swipe scroll type wait find-element hit-test describe screenshot help" -l canary -d 'Use the Canary channel API'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and not __fish_seen_subcommand_from setup start status doctor teardown activate layout-map title tap tap-on swipe scroll type wait find-element hit-test describe screenshot help" -s h -l help -d 'Print help'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and not __fish_seen_subcommand_from setup start status doctor teardown activate layout-map title tap tap-on swipe scroll type wait find-element hit-test describe screenshot help" -f -a "setup" -d 'One-shot: boot simulator, build WDA, install app, start WDA, launch app'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and not __fish_seen_subcommand_from setup start status doctor teardown activate layout-map title tap tap-on swipe scroll type wait find-element hit-test describe screenshot help" -f -a "start" -d 'Start the automation server (WebDriverAgent on iOS)'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and not __fish_seen_subcommand_from setup start status doctor teardown activate layout-map title tap tap-on swipe scroll type wait find-element hit-test describe screenshot help" -f -a "status" -d 'Print booted device info and screen bounds'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and not __fish_seen_subcommand_from setup start status doctor teardown activate layout-map title tap tap-on swipe scroll type wait find-element hit-test describe screenshot help" -f -a "doctor" -d 'Verify the device, automation server, and host toolchain are healthy'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and not __fish_seen_subcommand_from setup start status doctor teardown activate layout-map title tap tap-on swipe scroll type wait find-element hit-test describe screenshot help" -f -a "teardown" -d 'Kill stale automation server processes and clear cached session state'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and not __fish_seen_subcommand_from setup start status doctor teardown activate layout-map title tap tap-on swipe scroll type wait find-element hit-test describe screenshot help" -f -a "activate" -d 'Re-pin and activate the target app so it is in the foreground'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and not __fish_seen_subcommand_from setup start status doctor teardown activate layout-map title tap tap-on swipe scroll type wait find-element hit-test describe screenshot help" -f -a "layout-map" -d 'Full structured JSON snapshot of the current screen'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and not __fish_seen_subcommand_from setup start status doctor teardown activate layout-map title tap tap-on swipe scroll type wait find-element hit-test describe screenshot help" -f -a "title" -d 'Get the current screen title'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and not __fish_seen_subcommand_from setup start status doctor teardown activate layout-map title tap tap-on swipe scroll type wait find-element hit-test describe screenshot help" -f -a "tap" -d 'Tap at logical coordinates'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and not __fish_seen_subcommand_from setup start status doctor teardown activate layout-map title tap tap-on swipe scroll type wait find-element hit-test describe screenshot help" -f -a "tap-on" -d 'Tap an element by accessibility label. Waits for the UI to settle and returns the resulting layout-map unless --no-wait is set'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and not __fish_seen_subcommand_from setup start status doctor teardown activate layout-map title tap tap-on swipe scroll type wait find-element hit-test describe screenshot help" -f -a "swipe" -d 'Swipe between two points'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and not __fish_seen_subcommand_from setup start status doctor teardown activate layout-map title tap tap-on swipe scroll type wait find-element hit-test describe screenshot help" -f -a "scroll" -d 'Scroll the screen'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and not __fish_seen_subcommand_from setup start status doctor teardown activate layout-map title tap tap-on swipe scroll type wait find-element hit-test describe screenshot help" -f -a "type" -d 'Type text into the focused field'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and not __fish_seen_subcommand_from setup start status doctor teardown activate layout-map title tap tap-on swipe scroll type wait find-element hit-test describe screenshot help" -f -a "wait" -d 'Block until a label appears, or (with --stable) until the UI stops changing'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and not __fish_seen_subcommand_from setup start status doctor teardown activate layout-map title tap tap-on swipe scroll type wait find-element hit-test describe screenshot help" -f -a "find-element" -d 'Find an element by label'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and not __fish_seen_subcommand_from setup start status doctor teardown activate layout-map title tap tap-on swipe scroll type wait find-element hit-test describe screenshot help" -f -a "hit-test" -d 'Hit-test the element at a coordinate'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and not __fish_seen_subcommand_from setup start status doctor teardown activate layout-map title tap tap-on swipe scroll type wait find-element hit-test describe screenshot help" -f -a "describe" -d 'Dump the accessibility tree as JSON'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and not __fish_seen_subcommand_from setup start status doctor teardown activate layout-map title tap tap-on swipe scroll type wait find-element hit-test describe screenshot help" -f -a "screenshot" -d 'Capture a PNG screenshot'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and not __fish_seen_subcommand_from setup start status doctor teardown activate layout-map title tap tap-on swipe scroll type wait find-element hit-test describe screenshot help" -f -a "help" -d 'Print this message or the help of the given subcommand(s)'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from setup" -l port -d 'Automation server HTTP port' -r
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from setup" -s v -l verbose -d 'Use verbos output. More output per occurrence.  By default, it\'ll only report errors. `-v` show warnings `-vv` show info `-vvv` show debug `-vvvv` show trace'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from setup" -s q -l quiet -d 'Do not print log message'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from setup" -l report -d 'Store the debugging log in the log file, which is located at ~/.config/wukong'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from setup" -l canary -d 'Use the Canary channel API'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from setup" -s h -l help -d 'Print help'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from start" -l port -r
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from start" -s v -l verbose -d 'Use verbos output. More output per occurrence.  By default, it\'ll only report errors. `-v` show warnings `-vv` show info `-vvv` show debug `-vvvv` show trace'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from start" -s q -l quiet -d 'Do not print log message'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from start" -l report -d 'Store the debugging log in the log file, which is located at ~/.config/wukong'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from start" -l canary -d 'Use the Canary channel API'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from start" -s h -l help -d 'Print help'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from status" -s v -l verbose -d 'Use verbos output. More output per occurrence.  By default, it\'ll only report errors. `-v` show warnings `-vv` show info `-vvv` show debug `-vvvv` show trace'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from status" -s q -l quiet -d 'Do not print log message'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from status" -l report -d 'Store the debugging log in the log file, which is located at ~/.config/wukong'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from status" -l canary -d 'Use the Canary channel API'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from status" -s h -l help -d 'Print help'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from doctor" -s v -l verbose -d 'Use verbos output. More output per occurrence.  By default, it\'ll only report errors. `-v` show warnings `-vv` show info `-vvv` show debug `-vvvv` show trace'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from doctor" -s q -l quiet -d 'Do not print log message'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from doctor" -l report -d 'Store the debugging log in the log file, which is located at ~/.config/wukong'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from doctor" -l canary -d 'Use the Canary channel API'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from doctor" -s h -l help -d 'Print help'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from teardown" -s v -l verbose -d 'Use verbos output. More output per occurrence.  By default, it\'ll only report errors. `-v` show warnings `-vv` show info `-vvv` show debug `-vvvv` show trace'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from teardown" -s q -l quiet -d 'Do not print log message'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from teardown" -l report -d 'Store the debugging log in the log file, which is located at ~/.config/wukong'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from teardown" -l canary -d 'Use the Canary channel API'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from teardown" -s h -l help -d 'Print help'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from activate" -s v -l verbose -d 'Use verbos output. More output per occurrence.  By default, it\'ll only report errors. `-v` show warnings `-vv` show info `-vvv` show debug `-vvvv` show trace'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from activate" -s q -l quiet -d 'Do not print log message'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from activate" -l report -d 'Store the debugging log in the log file, which is located at ~/.config/wukong'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from activate" -l canary -d 'Use the Canary channel API'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from activate" -s h -l help -d 'Print help'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from layout-map" -s v -l verbose -d 'Use verbos output. More output per occurrence.  By default, it\'ll only report errors. `-v` show warnings `-vv` show info `-vvv` show debug `-vvvv` show trace'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from layout-map" -s q -l quiet -d 'Do not print log message'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from layout-map" -l report -d 'Store the debugging log in the log file, which is located at ~/.config/wukong'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from layout-map" -l canary -d 'Use the Canary channel API'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from layout-map" -s h -l help -d 'Print help'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from title" -s v -l verbose -d 'Use verbos output. More output per occurrence.  By default, it\'ll only report errors. `-v` show warnings `-vv` show info `-vvv` show debug `-vvvv` show trace'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from title" -s q -l quiet -d 'Do not print log message'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from title" -l report -d 'Store the debugging log in the log file, which is located at ~/.config/wukong'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from title" -l canary -d 'Use the Canary channel API'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from title" -s h -l help -d 'Print help'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from tap" -s v -l verbose -d 'Use verbos output. More output per occurrence.  By default, it\'ll only report errors. `-v` show warnings `-vv` show info `-vvv` show debug `-vvvv` show trace'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from tap" -s q -l quiet -d 'Do not print log message'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from tap" -l report -d 'Store the debugging log in the log file, which is located at ~/.config/wukong'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from tap" -l canary -d 'Use the Canary channel API'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from tap" -s h -l help -d 'Print help'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from tap-on" -l wait-for -d 'Wait until this label appears before returning' -r
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from tap-on" -l timeout -d 'Seconds to wait for the post-tap transition' -r
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from tap-on" -l no-wait -d 'Fire-and-forget: skip the wait and don\'t return a layout-map'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from tap-on" -s v -l verbose -d 'Use verbos output. More output per occurrence.  By default, it\'ll only report errors. `-v` show warnings `-vv` show info `-vvv` show debug `-vvvv` show trace'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from tap-on" -s q -l quiet -d 'Do not print log message'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from tap-on" -l report -d 'Store the debugging log in the log file, which is located at ~/.config/wukong'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from tap-on" -l canary -d 'Use the Canary channel API'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from tap-on" -s h -l help -d 'Print help'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from swipe" -l steps -r
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from swipe" -l step-ms -r
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from swipe" -s v -l verbose -d 'Use verbos output. More output per occurrence.  By default, it\'ll only report errors. `-v` show warnings `-vv` show info `-vvv` show debug `-vvvv` show trace'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from swipe" -s q -l quiet -d 'Do not print log message'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from swipe" -l report -d 'Store the debugging log in the log file, which is located at ~/.config/wukong'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from swipe" -l canary -d 'Use the Canary channel API'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from swipe" -s h -l help -d 'Print help'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from scroll" -s v -l verbose -d 'Use verbos output. More output per occurrence.  By default, it\'ll only report errors. `-v` show warnings `-vv` show info `-vvv` show debug `-vvvv` show trace'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from scroll" -s q -l quiet -d 'Do not print log message'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from scroll" -l report -d 'Store the debugging log in the log file, which is located at ~/.config/wukong'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from scroll" -l canary -d 'Use the Canary channel API'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from scroll" -s h -l help -d 'Print help'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from scroll" -f -a "up" -d 'Scroll up (reveals content above)'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from scroll" -f -a "down" -d 'Scroll down (reveals content below)'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from scroll" -f -a "to" -d 'Scroll until the given label is visible'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from scroll" -f -a "help" -d 'Print this message or the help of the given subcommand(s)'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from type" -s v -l verbose -d 'Use verbos output. More output per occurrence.  By default, it\'ll only report errors. `-v` show warnings `-vv` show info `-vvv` show debug `-vvvv` show trace'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from type" -s q -l quiet -d 'Do not print log message'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from type" -l report -d 'Store the debugging log in the log file, which is located at ~/.config/wukong'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from type" -l canary -d 'Use the Canary channel API'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from type" -s h -l help -d 'Print help'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from wait" -l timeout -d 'Max seconds to wait' -r
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from wait" -l stable -d 'Wait for UI stability instead of a specific label'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from wait" -s v -l verbose -d 'Use verbos output. More output per occurrence.  By default, it\'ll only report errors. `-v` show warnings `-vv` show info `-vvv` show debug `-vvvv` show trace'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from wait" -s q -l quiet -d 'Do not print log message'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from wait" -l report -d 'Store the debugging log in the log file, which is located at ~/.config/wukong'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from wait" -l canary -d 'Use the Canary channel API'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from wait" -s h -l help -d 'Print help'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from find-element" -s v -l verbose -d 'Use verbos output. More output per occurrence.  By default, it\'ll only report errors. `-v` show warnings `-vv` show info `-vvv` show debug `-vvvv` show trace'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from find-element" -s q -l quiet -d 'Do not print log message'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from find-element" -l report -d 'Store the debugging log in the log file, which is located at ~/.config/wukong'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from find-element" -l canary -d 'Use the Canary channel API'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from find-element" -s h -l help -d 'Print help'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from hit-test" -s v -l verbose -d 'Use verbos output. More output per occurrence.  By default, it\'ll only report errors. `-v` show warnings `-vv` show info `-vvv` show debug `-vvvv` show trace'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from hit-test" -s q -l quiet -d 'Do not print log message'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from hit-test" -l report -d 'Store the debugging log in the log file, which is located at ~/.config/wukong'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from hit-test" -l canary -d 'Use the Canary channel API'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from hit-test" -s h -l help -d 'Print help'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from describe" -s i -l interactive
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from describe" -s v -l verbose -d 'Use verbos output. More output per occurrence.  By default, it\'ll only report errors. `-v` show warnings `-vv` show info `-vvv` show debug `-vvvv` show trace'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from describe" -s q -l quiet -d 'Do not print log message'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from describe" -l report -d 'Store the debugging log in the log file, which is located at ~/.config/wukong'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from describe" -l canary -d 'Use the Canary channel API'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from describe" -s h -l help -d 'Print help'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from screenshot" -s v -l verbose -d 'Use verbos output. More output per occurrence.  By default, it\'ll only report errors. `-v` show warnings `-vv` show info `-vvv` show debug `-vvvv` show trace'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from screenshot" -s q -l quiet -d 'Do not print log message'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from screenshot" -l report -d 'Store the debugging log in the log file, which is located at ~/.config/wukong'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from screenshot" -l canary -d 'Use the Canary channel API'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from screenshot" -s h -l help -d 'Print help'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from help" -f -a "setup" -d 'One-shot: boot simulator, build WDA, install app, start WDA, launch app'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from help" -f -a "start" -d 'Start the automation server (WebDriverAgent on iOS)'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from help" -f -a "status" -d 'Print booted device info and screen bounds'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from help" -f -a "doctor" -d 'Verify the device, automation server, and host toolchain are healthy'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from help" -f -a "teardown" -d 'Kill stale automation server processes and clear cached session state'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from help" -f -a "activate" -d 'Re-pin and activate the target app so it is in the foreground'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from help" -f -a "layout-map" -d 'Full structured JSON snapshot of the current screen'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from help" -f -a "title" -d 'Get the current screen title'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from help" -f -a "tap" -d 'Tap at logical coordinates'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from help" -f -a "tap-on" -d 'Tap an element by accessibility label. Waits for the UI to settle and returns the resulting layout-map unless --no-wait is set'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from help" -f -a "swipe" -d 'Swipe between two points'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from help" -f -a "scroll" -d 'Scroll the screen'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from help" -f -a "type" -d 'Type text into the focused field'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from help" -f -a "wait" -d 'Block until a label appears, or (with --stable) until the UI stops changing'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from help" -f -a "find-element" -d 'Find an element by label'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from help" -f -a "hit-test" -d 'Hit-test the element at a coordinate'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from help" -f -a "describe" -d 'Dump the accessibility tree as JSON'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from help" -f -a "screenshot" -d 'Capture a PNG screenshot'
+complete -c wukong -n "__fish_wukong_using_subcommand test; and __fish_seen_subcommand_from help" -f -a "help" -d 'Print this message or the help of the given subcommand(s)'
+complete -c wukong -n "__fish_wukong_using_subcommand help; and not __fish_seen_subcommand_from init application deployment dev config login google completion skills tui test help" -f -a "init" -d 'Initialize Wukong\'s configurations'
+complete -c wukong -n "__fish_wukong_using_subcommand help; and not __fish_seen_subcommand_from init application deployment dev config login google completion skills tui test help" -f -a "application" -d 'This command group contains the commands to interact with an application’s configurations'
+complete -c wukong -n "__fish_wukong_using_subcommand help; and not __fish_seen_subcommand_from init application deployment dev config login google completion skills tui test help" -f -a "deployment" -d 'This command group contains the commands to view and interact with the Continuous Delivery pipeline of an application'
+complete -c wukong -n "__fish_wukong_using_subcommand help; and not __fish_seen_subcommand_from init application deployment dev config login google completion skills tui test help" -f -a "dev" -d 'This command group contains the commands to interact with the local development environment'
+complete -c wukong -n "__fish_wukong_using_subcommand help; and not __fish_seen_subcommand_from init application deployment dev config login google completion skills tui test help" -f -a "config" -d 'This command group contains the commands to view & interact with Wukong\'s configurations'
+complete -c wukong -n "__fish_wukong_using_subcommand help; and not __fish_seen_subcommand_from init application deployment dev config login google completion skills tui test help" -f -a "login" -d 'Login to start using wukong command'
+complete -c wukong -n "__fish_wukong_using_subcommand help; and not __fish_seen_subcommand_from init application deployment dev config login google completion skills tui test help" -f -a "google" -d 'This command group contains the commands to interact with Google services'
+complete -c wukong -n "__fish_wukong_using_subcommand help; and not __fish_seen_subcommand_from init application deployment dev config login google completion skills tui test help" -f -a "completion" -d 'Generate wukong cli completions for your shell to stdout'
+complete -c wukong -n "__fish_wukong_using_subcommand help; and not __fish_seen_subcommand_from init application deployment dev config login google completion skills tui test help" -f -a "skills" -d 'This command group contains the commands to manage agent skills locally'
+complete -c wukong -n "__fish_wukong_using_subcommand help; and not __fish_seen_subcommand_from init application deployment dev config login google completion skills tui test help" -f -a "tui" -d 'Start TUI session'
+complete -c wukong -n "__fish_wukong_using_subcommand help; and not __fish_seen_subcommand_from init application deployment dev config login google completion skills tui test help" -f -a "test" -d 'This command group contains the commands to drive device simulators/emulators for app testing'
+complete -c wukong -n "__fish_wukong_using_subcommand help; and not __fish_seen_subcommand_from init application deployment dev config login google completion skills tui test help" -f -a "help" -d 'Print this message or the help of the given subcommand(s)'
 complete -c wukong -n "__fish_wukong_using_subcommand help; and __fish_seen_subcommand_from application" -f -a "info" -d 'Show the application’s relevant informations'
 complete -c wukong -n "__fish_wukong_using_subcommand help; and __fish_seen_subcommand_from application" -f -a "logs" -d 'Getting the logs of the applications from the Google Cloud Logging'
 complete -c wukong -n "__fish_wukong_using_subcommand help; and __fish_seen_subcommand_from application" -f -a "instances" -d 'This command group contains the commands to interact with an application’s instances'
@@ -304,3 +455,21 @@ complete -c wukong -n "__fish_wukong_using_subcommand help; and __fish_seen_subc
 complete -c wukong -n "__fish_wukong_using_subcommand help; and __fish_seen_subcommand_from skills" -f -a "add" -d 'Install one or more skills from the registry locally'
 complete -c wukong -n "__fish_wukong_using_subcommand help; and __fish_seen_subcommand_from skills" -f -a "remove" -d 'Remove installed skills from local and global skill directories'
 complete -c wukong -n "__fish_wukong_using_subcommand help; and __fish_seen_subcommand_from skills" -f -a "update" -d 'Update all outdated installed skills from the registry'
+complete -c wukong -n "__fish_wukong_using_subcommand help; and __fish_seen_subcommand_from test" -f -a "setup" -d 'One-shot: boot simulator, build WDA, install app, start WDA, launch app'
+complete -c wukong -n "__fish_wukong_using_subcommand help; and __fish_seen_subcommand_from test" -f -a "start" -d 'Start the automation server (WebDriverAgent on iOS)'
+complete -c wukong -n "__fish_wukong_using_subcommand help; and __fish_seen_subcommand_from test" -f -a "status" -d 'Print booted device info and screen bounds'
+complete -c wukong -n "__fish_wukong_using_subcommand help; and __fish_seen_subcommand_from test" -f -a "doctor" -d 'Verify the device, automation server, and host toolchain are healthy'
+complete -c wukong -n "__fish_wukong_using_subcommand help; and __fish_seen_subcommand_from test" -f -a "teardown" -d 'Kill stale automation server processes and clear cached session state'
+complete -c wukong -n "__fish_wukong_using_subcommand help; and __fish_seen_subcommand_from test" -f -a "activate" -d 'Re-pin and activate the target app so it is in the foreground'
+complete -c wukong -n "__fish_wukong_using_subcommand help; and __fish_seen_subcommand_from test" -f -a "layout-map" -d 'Full structured JSON snapshot of the current screen'
+complete -c wukong -n "__fish_wukong_using_subcommand help; and __fish_seen_subcommand_from test" -f -a "title" -d 'Get the current screen title'
+complete -c wukong -n "__fish_wukong_using_subcommand help; and __fish_seen_subcommand_from test" -f -a "tap" -d 'Tap at logical coordinates'
+complete -c wukong -n "__fish_wukong_using_subcommand help; and __fish_seen_subcommand_from test" -f -a "tap-on" -d 'Tap an element by accessibility label. Waits for the UI to settle and returns the resulting layout-map unless --no-wait is set'
+complete -c wukong -n "__fish_wukong_using_subcommand help; and __fish_seen_subcommand_from test" -f -a "swipe" -d 'Swipe between two points'
+complete -c wukong -n "__fish_wukong_using_subcommand help; and __fish_seen_subcommand_from test" -f -a "scroll" -d 'Scroll the screen'
+complete -c wukong -n "__fish_wukong_using_subcommand help; and __fish_seen_subcommand_from test" -f -a "type" -d 'Type text into the focused field'
+complete -c wukong -n "__fish_wukong_using_subcommand help; and __fish_seen_subcommand_from test" -f -a "wait" -d 'Block until a label appears, or (with --stable) until the UI stops changing'
+complete -c wukong -n "__fish_wukong_using_subcommand help; and __fish_seen_subcommand_from test" -f -a "find-element" -d 'Find an element by label'
+complete -c wukong -n "__fish_wukong_using_subcommand help; and __fish_seen_subcommand_from test" -f -a "hit-test" -d 'Hit-test the element at a coordinate'
+complete -c wukong -n "__fish_wukong_using_subcommand help; and __fish_seen_subcommand_from test" -f -a "describe" -d 'Dump the accessibility tree as JSON'
+complete -c wukong -n "__fish_wukong_using_subcommand help; and __fish_seen_subcommand_from test" -f -a "screenshot" -d 'Capture a PNG screenshot'
diff --git a/cli/tests/snapshots/completion__wukong_completion_zsh.snap b/cli/tests/snapshots/completion__wukong_completion_zsh.snap
index 64388549..6d36a48c 100644
--- a/cli/tests/snapshots/completion__wukong_completion_zsh.snap
+++ b/cli/tests/snapshots/completion__wukong_completion_zsh.snap
@@ -1,6 +1,5 @@
 ---
 source: cli/tests/completion.rs
-assertion_line: 39
 expression: "std::str::from_utf8(&output.stdout).unwrap()"
 ---
 #compdef wukong
@@ -912,6 +911,480 @@ _arguments "${_arguments_options[@]}" : \
 '--help[Print help]' \
 && ret=0
 ;;
+(test)
+_arguments "${_arguments_options[@]}" : \
+'--platform=[Target platform]:PLATFORM:(ios)' \
+'--device=[Target device by ID (UDID for iOS, serial for Android). Falls back to the most recently booted device when omitted]:DEVICE: ' \
+'--source-timeout=[Override the WDA /source fetch timeout (seconds). Raise when working with large accessibility trees where layout-map exceeds the default 8s]:SOURCE_TIMEOUT: ' \
+'*-v[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'*--verbose[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'(-v --verbose)*-q[Do not print log message]' \
+'(-v --verbose)*--quiet[Do not print log message]' \
+'--report[Store the debugging log in the log file, which is located at ~/.config/wukong]' \
+'--canary[Use the Canary channel API]' \
+'-h[Print help]' \
+'--help[Print help]' \
+":: :_wukong__test_commands" \
+"*::: :->test" \
+&& ret=0
+
+    case $state in
+    (test)
+        words=($line[1] "${words[@]}")
+        (( CURRENT += 1 ))
+        curcontext="${curcontext%:*:*}:wukong-test-command-$line[1]:"
+        case $line[1] in
+            (setup)
+_arguments "${_arguments_options[@]}" : \
+'--port=[Automation server HTTP port]:PORT: ' \
+'*-v[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'*--verbose[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'(-v --verbose)*-q[Do not print log message]' \
+'(-v --verbose)*--quiet[Do not print log message]' \
+'--report[Store the debugging log in the log file, which is located at ~/.config/wukong]' \
+'--canary[Use the Canary channel API]' \
+'-h[Print help]' \
+'--help[Print help]' \
+':app -- Path to .app bundle or bundle identifier:' \
+&& ret=0
+;;
+(start)
+_arguments "${_arguments_options[@]}" : \
+'--port=[]:PORT: ' \
+'*-v[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'*--verbose[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'(-v --verbose)*-q[Do not print log message]' \
+'(-v --verbose)*--quiet[Do not print log message]' \
+'--report[Store the debugging log in the log file, which is located at ~/.config/wukong]' \
+'--canary[Use the Canary channel API]' \
+'-h[Print help]' \
+'--help[Print help]' \
+&& ret=0
+;;
+(status)
+_arguments "${_arguments_options[@]}" : \
+'*-v[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'*--verbose[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'(-v --verbose)*-q[Do not print log message]' \
+'(-v --verbose)*--quiet[Do not print log message]' \
+'--report[Store the debugging log in the log file, which is located at ~/.config/wukong]' \
+'--canary[Use the Canary channel API]' \
+'-h[Print help]' \
+'--help[Print help]' \
+&& ret=0
+;;
+(doctor)
+_arguments "${_arguments_options[@]}" : \
+'*-v[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'*--verbose[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'(-v --verbose)*-q[Do not print log message]' \
+'(-v --verbose)*--quiet[Do not print log message]' \
+'--report[Store the debugging log in the log file, which is located at ~/.config/wukong]' \
+'--canary[Use the Canary channel API]' \
+'-h[Print help]' \
+'--help[Print help]' \
+&& ret=0
+;;
+(teardown)
+_arguments "${_arguments_options[@]}" : \
+'*-v[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'*--verbose[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'(-v --verbose)*-q[Do not print log message]' \
+'(-v --verbose)*--quiet[Do not print log message]' \
+'--report[Store the debugging log in the log file, which is located at ~/.config/wukong]' \
+'--canary[Use the Canary channel API]' \
+'-h[Print help]' \
+'--help[Print help]' \
+&& ret=0
+;;
+(activate)
+_arguments "${_arguments_options[@]}" : \
+'*-v[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'*--verbose[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'(-v --verbose)*-q[Do not print log message]' \
+'(-v --verbose)*--quiet[Do not print log message]' \
+'--report[Store the debugging log in the log file, which is located at ~/.config/wukong]' \
+'--canary[Use the Canary channel API]' \
+'-h[Print help]' \
+'--help[Print help]' \
+'::bundle_id -- Bundle identifier. Defaults to the script'\''s configured default:' \
+&& ret=0
+;;
+(layout-map)
+_arguments "${_arguments_options[@]}" : \
+'*-v[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'*--verbose[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'(-v --verbose)*-q[Do not print log message]' \
+'(-v --verbose)*--quiet[Do not print log message]' \
+'--report[Store the debugging log in the log file, which is located at ~/.config/wukong]' \
+'--canary[Use the Canary channel API]' \
+'-h[Print help]' \
+'--help[Print help]' \
+&& ret=0
+;;
+(title)
+_arguments "${_arguments_options[@]}" : \
+'*-v[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'*--verbose[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'(-v --verbose)*-q[Do not print log message]' \
+'(-v --verbose)*--quiet[Do not print log message]' \
+'--report[Store the debugging log in the log file, which is located at ~/.config/wukong]' \
+'--canary[Use the Canary channel API]' \
+'-h[Print help]' \
+'--help[Print help]' \
+&& ret=0
+;;
+(tap)
+_arguments "${_arguments_options[@]}" : \
+'*-v[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'*--verbose[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'(-v --verbose)*-q[Do not print log message]' \
+'(-v --verbose)*--quiet[Do not print log message]' \
+'--report[Store the debugging log in the log file, which is located at ~/.config/wukong]' \
+'--canary[Use the Canary channel API]' \
+'-h[Print help]' \
+'--help[Print help]' \
+':x:' \
+':y:' \
+&& ret=0
+;;
+(tap-on)
+_arguments "${_arguments_options[@]}" : \
+'--wait-for=[Wait until this label appears before returning]:WAIT_FOR: ' \
+'--timeout=[Seconds to wait for the post-tap transition]:TIMEOUT: ' \
+'--no-wait[Fire-and-forget\: skip the wait and don'\''t return a layout-map]' \
+'*-v[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'*--verbose[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'(-v --verbose)*-q[Do not print log message]' \
+'(-v --verbose)*--quiet[Do not print log message]' \
+'--report[Store the debugging log in the log file, which is located at ~/.config/wukong]' \
+'--canary[Use the Canary channel API]' \
+'-h[Print help]' \
+'--help[Print help]' \
+':label:' \
+&& ret=0
+;;
+(swipe)
+_arguments "${_arguments_options[@]}" : \
+'--steps=[]:STEPS: ' \
+'--step-ms=[]:STEP_MS: ' \
+'*-v[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'*--verbose[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'(-v --verbose)*-q[Do not print log message]' \
+'(-v --verbose)*--quiet[Do not print log message]' \
+'--report[Store the debugging log in the log file, which is located at ~/.config/wukong]' \
+'--canary[Use the Canary channel API]' \
+'-h[Print help]' \
+'--help[Print help]' \
+':x1:' \
+':y1:' \
+':x2:' \
+':y2:' \
+&& ret=0
+;;
+(scroll)
+_arguments "${_arguments_options[@]}" : \
+'*-v[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'*--verbose[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'(-v --verbose)*-q[Do not print log message]' \
+'(-v --verbose)*--quiet[Do not print log message]' \
+'--report[Store the debugging log in the log file, which is located at ~/.config/wukong]' \
+'--canary[Use the Canary channel API]' \
+'-h[Print help]' \
+'--help[Print help]' \
+":: :_wukong__test__scroll_commands" \
+"*::: :->scroll" \
+&& ret=0
+
+    case $state in
+    (scroll)
+        words=($line[1] "${words[@]}")
+        (( CURRENT += 1 ))
+        curcontext="${curcontext%:*:*}:wukong-test-scroll-command-$line[1]:"
+        case $line[1] in
+            (up)
+_arguments "${_arguments_options[@]}" : \
+'--x=[]:X: ' \
+'--from=[]:FROM: ' \
+'--to=[]:TO: ' \
+'*-v[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'*--verbose[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'(-v --verbose)*-q[Do not print log message]' \
+'(-v --verbose)*--quiet[Do not print log message]' \
+'--report[Store the debugging log in the log file, which is located at ~/.config/wukong]' \
+'--canary[Use the Canary channel API]' \
+'-h[Print help]' \
+'--help[Print help]' \
+&& ret=0
+;;
+(down)
+_arguments "${_arguments_options[@]}" : \
+'--x=[]:X: ' \
+'--from=[]:FROM: ' \
+'--to=[]:TO: ' \
+'*-v[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'*--verbose[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'(-v --verbose)*-q[Do not print log message]' \
+'(-v --verbose)*--quiet[Do not print log message]' \
+'--report[Store the debugging log in the log file, which is located at ~/.config/wukong]' \
+'--canary[Use the Canary channel API]' \
+'-h[Print help]' \
+'--help[Print help]' \
+&& ret=0
+;;
+(to)
+_arguments "${_arguments_options[@]}" : \
+'--max-swipes=[]:MAX_SWIPES: ' \
+'*-v[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'*--verbose[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'(-v --verbose)*-q[Do not print log message]' \
+'(-v --verbose)*--quiet[Do not print log message]' \
+'--report[Store the debugging log in the log file, which is located at ~/.config/wukong]' \
+'--canary[Use the Canary channel API]' \
+'-h[Print help]' \
+'--help[Print help]' \
+':label:' \
+&& ret=0
+;;
+(help)
+_arguments "${_arguments_options[@]}" : \
+":: :_wukong__test__scroll__help_commands" \
+"*::: :->help" \
+&& ret=0
+
+    case $state in
+    (help)
+        words=($line[1] "${words[@]}")
+        (( CURRENT += 1 ))
+        curcontext="${curcontext%:*:*}:wukong-test-scroll-help-command-$line[1]:"
+        case $line[1] in
+            (up)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(down)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(to)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(help)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+        esac
+    ;;
+esac
+;;
+        esac
+    ;;
+esac
+;;
+(type)
+_arguments "${_arguments_options[@]}" : \
+'*-v[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'*--verbose[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'(-v --verbose)*-q[Do not print log message]' \
+'(-v --verbose)*--quiet[Do not print log message]' \
+'--report[Store the debugging log in the log file, which is located at ~/.config/wukong]' \
+'--canary[Use the Canary channel API]' \
+'-h[Print help]' \
+'--help[Print help]' \
+':text:' \
+&& ret=0
+;;
+(wait)
+_arguments "${_arguments_options[@]}" : \
+'--timeout=[Max seconds to wait]:TIMEOUT: ' \
+'--stable[Wait for UI stability instead of a specific label]' \
+'*-v[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'*--verbose[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'(-v --verbose)*-q[Do not print log message]' \
+'(-v --verbose)*--quiet[Do not print log message]' \
+'--report[Store the debugging log in the log file, which is located at ~/.config/wukong]' \
+'--canary[Use the Canary channel API]' \
+'-h[Print help]' \
+'--help[Print help]' \
+'::label -- Accessibility label to wait for. Required unless --stable is set:' \
+&& ret=0
+;;
+(find-element)
+_arguments "${_arguments_options[@]}" : \
+'*-v[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'*--verbose[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'(-v --verbose)*-q[Do not print log message]' \
+'(-v --verbose)*--quiet[Do not print log message]' \
+'--report[Store the debugging log in the log file, which is located at ~/.config/wukong]' \
+'--canary[Use the Canary channel API]' \
+'-h[Print help]' \
+'--help[Print help]' \
+':label:' \
+&& ret=0
+;;
+(hit-test)
+_arguments "${_arguments_options[@]}" : \
+'*-v[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'*--verbose[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'(-v --verbose)*-q[Do not print log message]' \
+'(-v --verbose)*--quiet[Do not print log message]' \
+'--report[Store the debugging log in the log file, which is located at ~/.config/wukong]' \
+'--canary[Use the Canary channel API]' \
+'-h[Print help]' \
+'--help[Print help]' \
+':x:' \
+':y:' \
+&& ret=0
+;;
+(describe)
+_arguments "${_arguments_options[@]}" : \
+'-i[]' \
+'--interactive[]' \
+'*-v[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'*--verbose[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'(-v --verbose)*-q[Do not print log message]' \
+'(-v --verbose)*--quiet[Do not print log message]' \
+'--report[Store the debugging log in the log file, which is located at ~/.config/wukong]' \
+'--canary[Use the Canary channel API]' \
+'-h[Print help]' \
+'--help[Print help]' \
+'::depth:' \
+&& ret=0
+;;
+(screenshot)
+_arguments "${_arguments_options[@]}" : \
+'*-v[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'*--verbose[Use verbos output. More output per occurrence.  By default, it'\''ll only report errors. \`-v\` show warnings \`-vv\` show info \`-vvv\` show debug \`-vvvv\` show trace]' \
+'(-v --verbose)*-q[Do not print log message]' \
+'(-v --verbose)*--quiet[Do not print log message]' \
+'--report[Store the debugging log in the log file, which is located at ~/.config/wukong]' \
+'--canary[Use the Canary channel API]' \
+'-h[Print help]' \
+'--help[Print help]' \
+':output:' \
+&& ret=0
+;;
+(help)
+_arguments "${_arguments_options[@]}" : \
+":: :_wukong__test__help_commands" \
+"*::: :->help" \
+&& ret=0
+
+    case $state in
+    (help)
+        words=($line[1] "${words[@]}")
+        (( CURRENT += 1 ))
+        curcontext="${curcontext%:*:*}:wukong-test-help-command-$line[1]:"
+        case $line[1] in
+            (setup)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(start)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(status)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(doctor)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(teardown)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(activate)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(layout-map)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(title)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(tap)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(tap-on)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(swipe)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(scroll)
+_arguments "${_arguments_options[@]}" : \
+":: :_wukong__test__help__scroll_commands" \
+"*::: :->scroll" \
+&& ret=0
+
+    case $state in
+    (scroll)
+        words=($line[1] "${words[@]}")
+        (( CURRENT += 1 ))
+        curcontext="${curcontext%:*:*}:wukong-test-help-scroll-command-$line[1]:"
+        case $line[1] in
+            (up)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(down)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(to)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+        esac
+    ;;
+esac
+;;
+(type)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(wait)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(find-element)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(hit-test)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(describe)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(screenshot)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(help)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+        esac
+    ;;
+esac
+;;
+        esac
+    ;;
+esac
+;;
 (help)
 _arguments "${_arguments_options[@]}" : \
 ":: :_wukong__help_commands" \
@@ -1164,6 +1637,118 @@ esac
 _arguments "${_arguments_options[@]}" : \
 && ret=0
 ;;
+(test)
+_arguments "${_arguments_options[@]}" : \
+":: :_wukong__help__test_commands" \
+"*::: :->test" \
+&& ret=0
+
+    case $state in
+    (test)
+        words=($line[1] "${words[@]}")
+        (( CURRENT += 1 ))
+        curcontext="${curcontext%:*:*}:wukong-help-test-command-$line[1]:"
+        case $line[1] in
+            (setup)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(start)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(status)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(doctor)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(teardown)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(activate)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(layout-map)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(title)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(tap)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(tap-on)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(swipe)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(scroll)
+_arguments "${_arguments_options[@]}" : \
+":: :_wukong__help__test__scroll_commands" \
+"*::: :->scroll" \
+&& ret=0
+
+    case $state in
+    (scroll)
+        words=($line[1] "${words[@]}")
+        (( CURRENT += 1 ))
+        curcontext="${curcontext%:*:*}:wukong-help-test-scroll-command-$line[1]:"
+        case $line[1] in
+            (up)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(down)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(to)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+        esac
+    ;;
+esac
+;;
+(type)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(wait)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(find-element)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(hit-test)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(describe)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+(screenshot)
+_arguments "${_arguments_options[@]}" : \
+&& ret=0
+;;
+        esac
+    ;;
+esac
+;;
 (help)
 _arguments "${_arguments_options[@]}" : \
 && ret=0
@@ -1190,6 +1775,7 @@ _wukong_commands() {
 'completion:Generate wukong cli completions for your shell to stdout' \
 'skills:This command group contains the commands to manage agent skills locally' \
 'tui:Start TUI session' \
+'test:This command group contains the commands to drive device simulators/emulators for app testing' \
 'help:Print this message or the help of the given subcommand(s)' \
     )
     _describe -t commands 'wukong commands' commands "$@"
@@ -1601,6 +2187,7 @@ _wukong__help_commands() {
 'completion:Generate wukong cli completions for your shell to stdout' \
 'skills:This command group contains the commands to manage agent skills locally' \
 'tui:Start TUI session' \
+'test:This command group contains the commands to drive device simulators/emulators for app testing' \
 'help:Print this message or the help of the given subcommand(s)' \
     )
     _describe -t commands 'wukong help commands' commands "$@"
@@ -1819,6 +2406,139 @@ _wukong__help__skills__update_commands() {
     local commands; commands=()
     _describe -t commands 'wukong help skills update commands' commands "$@"
 }
+(( $+functions[_wukong__help__test_commands] )) ||
+_wukong__help__test_commands() {
+    local commands; commands=(
+'setup:One-shot\: boot simulator, build WDA, install app, start WDA, launch app' \
+'start:Start the automation server (WebDriverAgent on iOS)' \
+'status:Print booted device info and screen bounds' \
+'doctor:Verify the device, automation server, and host toolchain are healthy' \
+'teardown:Kill stale automation server processes and clear cached session state' \
+'activate:Re-pin and activate the target app so it is in the foreground' \
+'layout-map:Full structured JSON snapshot of the current screen' \
+'title:Get the current screen title' \
+'tap:Tap at logical coordinates' \
+'tap-on:Tap an element by accessibility label. Waits for the UI to settle and returns the resulting layout-map unless --no-wait is set' \
+'swipe:Swipe between two points' \
+'scroll:Scroll the screen' \
+'type:Type text into the focused field' \
+'wait:Block until a label appears, or (with --stable) until the UI stops changing' \
+'find-element:Find an element by label' \
+'hit-test:Hit-test the element at a coordinate' \
+'describe:Dump the accessibility tree as JSON' \
+'screenshot:Capture a PNG screenshot' \
+    )
+    _describe -t commands 'wukong help test commands' commands "$@"
+}
+(( $+functions[_wukong__help__test__activate_commands] )) ||
+_wukong__help__test__activate_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong help test activate commands' commands "$@"
+}
+(( $+functions[_wukong__help__test__describe_commands] )) ||
+_wukong__help__test__describe_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong help test describe commands' commands "$@"
+}
+(( $+functions[_wukong__help__test__doctor_commands] )) ||
+_wukong__help__test__doctor_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong help test doctor commands' commands "$@"
+}
+(( $+functions[_wukong__help__test__find-element_commands] )) ||
+_wukong__help__test__find-element_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong help test find-element commands' commands "$@"
+}
+(( $+functions[_wukong__help__test__hit-test_commands] )) ||
+_wukong__help__test__hit-test_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong help test hit-test commands' commands "$@"
+}
+(( $+functions[_wukong__help__test__layout-map_commands] )) ||
+_wukong__help__test__layout-map_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong help test layout-map commands' commands "$@"
+}
+(( $+functions[_wukong__help__test__screenshot_commands] )) ||
+_wukong__help__test__screenshot_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong help test screenshot commands' commands "$@"
+}
+(( $+functions[_wukong__help__test__scroll_commands] )) ||
+_wukong__help__test__scroll_commands() {
+    local commands; commands=(
+'up:Scroll up (reveals content above)' \
+'down:Scroll down (reveals content below)' \
+'to:Scroll until the given label is visible' \
+    )
+    _describe -t commands 'wukong help test scroll commands' commands "$@"
+}
+(( $+functions[_wukong__help__test__scroll__down_commands] )) ||
+_wukong__help__test__scroll__down_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong help test scroll down commands' commands "$@"
+}
+(( $+functions[_wukong__help__test__scroll__to_commands] )) ||
+_wukong__help__test__scroll__to_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong help test scroll to commands' commands "$@"
+}
+(( $+functions[_wukong__help__test__scroll__up_commands] )) ||
+_wukong__help__test__scroll__up_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong help test scroll up commands' commands "$@"
+}
+(( $+functions[_wukong__help__test__setup_commands] )) ||
+_wukong__help__test__setup_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong help test setup commands' commands "$@"
+}
+(( $+functions[_wukong__help__test__start_commands] )) ||
+_wukong__help__test__start_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong help test start commands' commands "$@"
+}
+(( $+functions[_wukong__help__test__status_commands] )) ||
+_wukong__help__test__status_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong help test status commands' commands "$@"
+}
+(( $+functions[_wukong__help__test__swipe_commands] )) ||
+_wukong__help__test__swipe_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong help test swipe commands' commands "$@"
+}
+(( $+functions[_wukong__help__test__tap_commands] )) ||
+_wukong__help__test__tap_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong help test tap commands' commands "$@"
+}
+(( $+functions[_wukong__help__test__tap-on_commands] )) ||
+_wukong__help__test__tap-on_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong help test tap-on commands' commands "$@"
+}
+(( $+functions[_wukong__help__test__teardown_commands] )) ||
+_wukong__help__test__teardown_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong help test teardown commands' commands "$@"
+}
+(( $+functions[_wukong__help__test__title_commands] )) ||
+_wukong__help__test__title_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong help test title commands' commands "$@"
+}
+(( $+functions[_wukong__help__test__type_commands] )) ||
+_wukong__help__test__type_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong help test type commands' commands "$@"
+}
+(( $+functions[_wukong__help__test__wait_commands] )) ||
+_wukong__help__test__wait_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong help test wait commands' commands "$@"
+}
 (( $+functions[_wukong__help__tui_commands] )) ||
 _wukong__help__tui_commands() {
     local commands; commands=()
@@ -1937,6 +2657,310 @@ _wukong__skills__update_commands() {
     local commands; commands=()
     _describe -t commands 'wukong skills update commands' commands "$@"
 }
+(( $+functions[_wukong__test_commands] )) ||
+_wukong__test_commands() {
+    local commands; commands=(
+'setup:One-shot\: boot simulator, build WDA, install app, start WDA, launch app' \
+'start:Start the automation server (WebDriverAgent on iOS)' \
+'status:Print booted device info and screen bounds' \
+'doctor:Verify the device, automation server, and host toolchain are healthy' \
+'teardown:Kill stale automation server processes and clear cached session state' \
+'activate:Re-pin and activate the target app so it is in the foreground' \
+'layout-map:Full structured JSON snapshot of the current screen' \
+'title:Get the current screen title' \
+'tap:Tap at logical coordinates' \
+'tap-on:Tap an element by accessibility label. Waits for the UI to settle and returns the resulting layout-map unless --no-wait is set' \
+'swipe:Swipe between two points' \
+'scroll:Scroll the screen' \
+'type:Type text into the focused field' \
+'wait:Block until a label appears, or (with --stable) until the UI stops changing' \
+'find-element:Find an element by label' \
+'hit-test:Hit-test the element at a coordinate' \
+'describe:Dump the accessibility tree as JSON' \
+'screenshot:Capture a PNG screenshot' \
+'help:Print this message or the help of the given subcommand(s)' \
+    )
+    _describe -t commands 'wukong test commands' commands "$@"
+}
+(( $+functions[_wukong__test__activate_commands] )) ||
+_wukong__test__activate_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test activate commands' commands "$@"
+}
+(( $+functions[_wukong__test__describe_commands] )) ||
+_wukong__test__describe_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test describe commands' commands "$@"
+}
+(( $+functions[_wukong__test__doctor_commands] )) ||
+_wukong__test__doctor_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test doctor commands' commands "$@"
+}
+(( $+functions[_wukong__test__find-element_commands] )) ||
+_wukong__test__find-element_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test find-element commands' commands "$@"
+}
+(( $+functions[_wukong__test__help_commands] )) ||
+_wukong__test__help_commands() {
+    local commands; commands=(
+'setup:One-shot\: boot simulator, build WDA, install app, start WDA, launch app' \
+'start:Start the automation server (WebDriverAgent on iOS)' \
+'status:Print booted device info and screen bounds' \
+'doctor:Verify the device, automation server, and host toolchain are healthy' \
+'teardown:Kill stale automation server processes and clear cached session state' \
+'activate:Re-pin and activate the target app so it is in the foreground' \
+'layout-map:Full structured JSON snapshot of the current screen' \
+'title:Get the current screen title' \
+'tap:Tap at logical coordinates' \
+'tap-on:Tap an element by accessibility label. Waits for the UI to settle and returns the resulting layout-map unless --no-wait is set' \
+'swipe:Swipe between two points' \
+'scroll:Scroll the screen' \
+'type:Type text into the focused field' \
+'wait:Block until a label appears, or (with --stable) until the UI stops changing' \
+'find-element:Find an element by label' \
+'hit-test:Hit-test the element at a coordinate' \
+'describe:Dump the accessibility tree as JSON' \
+'screenshot:Capture a PNG screenshot' \
+'help:Print this message or the help of the given subcommand(s)' \
+    )
+    _describe -t commands 'wukong test help commands' commands "$@"
+}
+(( $+functions[_wukong__test__help__activate_commands] )) ||
+_wukong__test__help__activate_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test help activate commands' commands "$@"
+}
+(( $+functions[_wukong__test__help__describe_commands] )) ||
+_wukong__test__help__describe_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test help describe commands' commands "$@"
+}
+(( $+functions[_wukong__test__help__doctor_commands] )) ||
+_wukong__test__help__doctor_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test help doctor commands' commands "$@"
+}
+(( $+functions[_wukong__test__help__find-element_commands] )) ||
+_wukong__test__help__find-element_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test help find-element commands' commands "$@"
+}
+(( $+functions[_wukong__test__help__help_commands] )) ||
+_wukong__test__help__help_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test help help commands' commands "$@"
+}
+(( $+functions[_wukong__test__help__hit-test_commands] )) ||
+_wukong__test__help__hit-test_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test help hit-test commands' commands "$@"
+}
+(( $+functions[_wukong__test__help__layout-map_commands] )) ||
+_wukong__test__help__layout-map_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test help layout-map commands' commands "$@"
+}
+(( $+functions[_wukong__test__help__screenshot_commands] )) ||
+_wukong__test__help__screenshot_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test help screenshot commands' commands "$@"
+}
+(( $+functions[_wukong__test__help__scroll_commands] )) ||
+_wukong__test__help__scroll_commands() {
+    local commands; commands=(
+'up:Scroll up (reveals content above)' \
+'down:Scroll down (reveals content below)' \
+'to:Scroll until the given label is visible' \
+    )
+    _describe -t commands 'wukong test help scroll commands' commands "$@"
+}
+(( $+functions[_wukong__test__help__scroll__down_commands] )) ||
+_wukong__test__help__scroll__down_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test help scroll down commands' commands "$@"
+}
+(( $+functions[_wukong__test__help__scroll__to_commands] )) ||
+_wukong__test__help__scroll__to_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test help scroll to commands' commands "$@"
+}
+(( $+functions[_wukong__test__help__scroll__up_commands] )) ||
+_wukong__test__help__scroll__up_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test help scroll up commands' commands "$@"
+}
+(( $+functions[_wukong__test__help__setup_commands] )) ||
+_wukong__test__help__setup_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test help setup commands' commands "$@"
+}
+(( $+functions[_wukong__test__help__start_commands] )) ||
+_wukong__test__help__start_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test help start commands' commands "$@"
+}
+(( $+functions[_wukong__test__help__status_commands] )) ||
+_wukong__test__help__status_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test help status commands' commands "$@"
+}
+(( $+functions[_wukong__test__help__swipe_commands] )) ||
+_wukong__test__help__swipe_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test help swipe commands' commands "$@"
+}
+(( $+functions[_wukong__test__help__tap_commands] )) ||
+_wukong__test__help__tap_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test help tap commands' commands "$@"
+}
+(( $+functions[_wukong__test__help__tap-on_commands] )) ||
+_wukong__test__help__tap-on_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test help tap-on commands' commands "$@"
+}
+(( $+functions[_wukong__test__help__teardown_commands] )) ||
+_wukong__test__help__teardown_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test help teardown commands' commands "$@"
+}
+(( $+functions[_wukong__test__help__title_commands] )) ||
+_wukong__test__help__title_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test help title commands' commands "$@"
+}
+(( $+functions[_wukong__test__help__type_commands] )) ||
+_wukong__test__help__type_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test help type commands' commands "$@"
+}
+(( $+functions[_wukong__test__help__wait_commands] )) ||
+_wukong__test__help__wait_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test help wait commands' commands "$@"
+}
+(( $+functions[_wukong__test__hit-test_commands] )) ||
+_wukong__test__hit-test_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test hit-test commands' commands "$@"
+}
+(( $+functions[_wukong__test__layout-map_commands] )) ||
+_wukong__test__layout-map_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test layout-map commands' commands "$@"
+}
+(( $+functions[_wukong__test__screenshot_commands] )) ||
+_wukong__test__screenshot_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test screenshot commands' commands "$@"
+}
+(( $+functions[_wukong__test__scroll_commands] )) ||
+_wukong__test__scroll_commands() {
+    local commands; commands=(
+'up:Scroll up (reveals content above)' \
+'down:Scroll down (reveals content below)' \
+'to:Scroll until the given label is visible' \
+'help:Print this message or the help of the given subcommand(s)' \
+    )
+    _describe -t commands 'wukong test scroll commands' commands "$@"
+}
+(( $+functions[_wukong__test__scroll__down_commands] )) ||
+_wukong__test__scroll__down_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test scroll down commands' commands "$@"
+}
+(( $+functions[_wukong__test__scroll__help_commands] )) ||
+_wukong__test__scroll__help_commands() {
+    local commands; commands=(
+'up:Scroll up (reveals content above)' \
+'down:Scroll down (reveals content below)' \
+'to:Scroll until the given label is visible' \
+'help:Print this message or the help of the given subcommand(s)' \
+    )
+    _describe -t commands 'wukong test scroll help commands' commands "$@"
+}
+(( $+functions[_wukong__test__scroll__help__down_commands] )) ||
+_wukong__test__scroll__help__down_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test scroll help down commands' commands "$@"
+}
+(( $+functions[_wukong__test__scroll__help__help_commands] )) ||
+_wukong__test__scroll__help__help_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test scroll help help commands' commands "$@"
+}
+(( $+functions[_wukong__test__scroll__help__to_commands] )) ||
+_wukong__test__scroll__help__to_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test scroll help to commands' commands "$@"
+}
+(( $+functions[_wukong__test__scroll__help__up_commands] )) ||
+_wukong__test__scroll__help__up_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test scroll help up commands' commands "$@"
+}
+(( $+functions[_wukong__test__scroll__to_commands] )) ||
+_wukong__test__scroll__to_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test scroll to commands' commands "$@"
+}
+(( $+functions[_wukong__test__scroll__up_commands] )) ||
+_wukong__test__scroll__up_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test scroll up commands' commands "$@"
+}
+(( $+functions[_wukong__test__setup_commands] )) ||
+_wukong__test__setup_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test setup commands' commands "$@"
+}
+(( $+functions[_wukong__test__start_commands] )) ||
+_wukong__test__start_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test start commands' commands "$@"
+}
+(( $+functions[_wukong__test__status_commands] )) ||
+_wukong__test__status_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test status commands' commands "$@"
+}
+(( $+functions[_wukong__test__swipe_commands] )) ||
+_wukong__test__swipe_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test swipe commands' commands "$@"
+}
+(( $+functions[_wukong__test__tap_commands] )) ||
+_wukong__test__tap_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test tap commands' commands "$@"
+}
+(( $+functions[_wukong__test__tap-on_commands] )) ||
+_wukong__test__tap-on_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test tap-on commands' commands "$@"
+}
+(( $+functions[_wukong__test__teardown_commands] )) ||
+_wukong__test__teardown_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test teardown commands' commands "$@"
+}
+(( $+functions[_wukong__test__title_commands] )) ||
+_wukong__test__title_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test title commands' commands "$@"
+}
+(( $+functions[_wukong__test__type_commands] )) ||
+_wukong__test__type_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test type commands' commands "$@"
+}
+(( $+functions[_wukong__test__wait_commands] )) ||
+_wukong__test__wait_commands() {
+    local commands; commands=()
+    _describe -t commands 'wukong test wait commands' commands "$@"
+}
 (( $+functions[_wukong__tui_commands] )) ||
 _wukong__tui_commands() {
     local commands; commands=()
diff --git a/cli/tests/snapshots/wukong__wukong_help_without_config_file.snap b/cli/tests/snapshots/wukong__wukong_help_without_config_file.snap
index 25c02e7c..2b25656c 100644
--- a/cli/tests/snapshots/wukong__wukong_help_without_config_file.snap
+++ b/cli/tests/snapshots/wukong__wukong_help_without_config_file.snap
@@ -21,6 +21,8 @@ Commands:
   completion   Generate wukong cli completions for your shell to stdout
   skills       This command group contains the commands to manage agent skills locally
   tui          Start TUI session
+  test         This command group contains the commands to drive device simulators/emulators for app
+               testing
   help         Print this message or the help of the given subcommand(s)
 
 Options: