From 96003b9f0ab09cc677f989aa97e853b1b7009f3b Mon Sep 17 00:00:00 2001
From: Fauzaan <mfauzaan@icloud.com>
Date: Tue, 21 Apr 2026 07:35:32 +0000
Subject: [PATCH 01/11] Add wukong test command group for iOS simulator driving
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Implements `wukong test --platform ios <cmd>` as a Rust CLI layer that
delegates to the simClaw bash backend. The backend script is bundled via
include_str! and extracted to ~/.config/wukong/scripts/sim.sh on each
invocation so a Wukong upgrade always ships the matching script.

Command surface (18 commands): setup, start, status, doctor, teardown,
activate, layout-map, title, tap, tap-on, swipe, scroll {up|down|to}, type,
wait [--stable], find-element, hit-test, describe, screenshot.

Architecture: PlatformBackend async trait with an IosBackend impl. Android
slots in via the same trait and --platform flag without touching the iOS
path. Three run helpers (run_streaming, run_capture, run_json) cover the
output-shape variants; stderr is inherited so the user sees script output
in real time. Script exit codes are surfaced as TestError::ScriptFailed.

The bundled sim.sh is a placeholder today — the real simClaw script
replaces it before release.

Out of scope: Android backend, skills installer (separate RFC), JSON output
for `status` (pending a --json flag from the script team).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 cli/src/commands/mod.rs           |   6 +-
 cli/src/commands/test/ios/mod.rs  | 305 ++++++++++++++++++++++++++++++
 cli/src/commands/test/ios/sim.sh  |  19 ++
 cli/src/commands/test/mod.rs      | 261 +++++++++++++++++++++++++
 cli/src/commands/test/platform.rs |  79 ++++++++
 cli/src/error.rs                  |  17 ++
 6 files changed, 686 insertions(+), 1 deletion(-)
 create mode 100644 cli/src/commands/test/ios/mod.rs
 create mode 100644 cli/src/commands/test/ios/sim.sh
 create mode 100644 cli/src/commands/test/mod.rs
 create mode 100644 cli/src/commands/test/platform.rs

diff --git a/cli/src/commands/mod.rs b/cli/src/commands/mod.rs
index 8b98a93b..417288d4 100644
--- a/cli/src/commands/mod.rs
+++ b/cli/src/commands/mod.rs
@@ -21,6 +21,7 @@ mod dev;
 mod google;
 mod init;
 mod login;
+mod test;
 mod tui;
 
 #[derive(Debug, Default)]
@@ -98,6 +99,8 @@ pub enum CommandGroup {
     },
     /// Start TUI session
     Tui,
+    /// This command group contains the commands to drive device simulators/emulators for app testing.
+    Test(test::Test),
 }
 
 impl ClapApp {
@@ -123,6 +126,7 @@ impl ClapApp {
             CommandGroup::Config(config) => config.handle_command(),
             CommandGroup::Dev(dev) => dev.handle_command(self).await,
             CommandGroup::Tui => handle_tui(channel).await,
+            CommandGroup::Test(test) => test.handle_command().await,
         };
 
         // Check for CLI updates:
@@ -178,7 +182,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..af383d77
--- /dev/null
+++ b/cli/src/commands/test/ios/mod.rs
@@ -0,0 +1,305 @@
+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};
+
+const SIM_SCRIPT: &str = include_str!("sim.sh");
+const SCRIPT_FILENAME: &str = "sim.sh";
+
+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,
+        }
+    }
+
+    /// The bundled sim.sh is rewritten on every call so a Wukong upgrade
+    /// always ships the matching backend — stale copies aren't possible.
+    /// chmod runs only on first creation; overwrites preserve the inode mode.
+    fn script_path() -> Result<PathBuf, WKCliError> {
+        let extract_err =
+            |e: std::io::Error| WKCliError::TestError(TestError::ScriptExtractionFailed(e.to_string()));
+
+        let mut dir = dirs::home_dir().ok_or_else(|| {
+            WKCliError::TestError(TestError::ScriptExtractionFailed(
+                "could not resolve home directory".into(),
+            ))
+        })?;
+        dir.extend([".config", "wukong", "scripts"]);
+        std::fs::create_dir_all(&dir).map_err(extract_err)?;
+
+        let path = dir.join(SCRIPT_FILENAME);
+        let newly_created = !path.exists();
+        std::fs::write(&path, SIM_SCRIPT).map_err(extract_err)?;
+
+        #[cfg(unix)]
+        if newly_created {
+            use std::os::unix::fs::PermissionsExt;
+            std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755))
+                .map_err(extract_err)?;
+        }
+
+        Ok(path)
+    }
+
+    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?;
+        serde_json::from_str::<T>(stdout.trim()).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())
+}
+
+#[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
+    }
+
+    async fn wda_start(&self, port: u16) -> Result<(), WKCliError> {
+        self.run_streaming("wda-start", &[port.to_string()]).await
+    }
+
+    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
+    }
+}
diff --git a/cli/src/commands/test/ios/sim.sh b/cli/src/commands/test/ios/sim.sh
new file mode 100644
index 00000000..56d4bdf2
--- /dev/null
+++ b/cli/src/commands/test/ios/sim.sh
@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Placeholder for the simClaw bash backend.
+#
+# The real script (~3000 lines) is owned and maintained by a separate team and
+# will be dropped in here before the `wukong test` feature ships. The Rust CLI
+# layer (cli/src/commands/test/ios/mod.rs) extracts this file to
+# ~/.config/wukong/scripts/sim.sh on first invocation and delegates every
+# subcommand to it.
+#
+# Contract (see RFC: "iOS backend: bash delegate"):
+#   sim [--device <UDID>] <subcommand> [args...]
+# Exit codes are mapped to WKCliError variants by the Rust layer.
+
+set -euo pipefail
+
+echo "wukong test ios backend is not yet installed." >&2
+echo "This is a placeholder. Replace cli/src/commands/test/ios/sim.sh with" >&2
+echo "the real simClaw script before release." >&2
+exit 127
diff --git a/cli/src/commands/test/mod.rs b/cli/src/commands/test/mod.rs
new file mode 100644
index 00000000..57c34101
--- /dev/null
+++ b/cli/src/commands/test/mod.rs
@@ -0,0 +1,261 @@
+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..0c0fb05a
--- /dev/null
+++ b/cli/src/commands/test/platform.rs
@@ -0,0 +1,79 @@
+use async_trait::async_trait;
+use serde::{Deserialize, Serialize};
+
+use crate::error::WKCliError;
+
+#[derive(Debug, Serialize, Deserialize)]
+pub struct Element {
+    pub role: String,
+    pub label: String,
+    pub x: f64,
+    pub y: f64,
+    pub w: f64,
+    pub h: f64,
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+pub struct LayoutMap {
+    pub screen_title: Option<String>,
+    pub back_button: Option<Element>,
+    pub tab_bar: Vec<serde_json::Value>,
+    pub elements: Vec<Element>,
+    pub visible_text: Vec<String>,
+    pub scroll_hints: serde_json::Value,
+    pub context: Option<String>,
+    pub suggested_actions: Vec<String>,
+}
+
+#[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)]

From 28cebfe1fcf65b53a623f678ec368935b083e9ed Mon Sep 17 00:00:00 2001
From: Fauzaan <mfauzaan@icloud.com>
Date: Tue, 21 Apr 2026 07:42:22 +0000
Subject: [PATCH 02/11] Vendor simClaw iOS backend and wire real integration

Replaces the placeholder sim.sh with the full simClaw tree copied from
the homebrew-simClaw repo: bin/sim + lib/simclaw/*.sh + the swift helper.
The sim script's own SIM_LIB resolution works unchanged because the
extracted layout matches its repo layout exactly.

The iOS backend now embeds every file via a static SIMCLAW_FILES
manifest, extracts the whole tree to ~/.config/wukong/scripts/simclaw/
on each invocation, and returns bin/sim as the entry point. Only bin/sim
gets the executable bit; the helpers are sourced, not invoked.

Smoke-tested against a machine with no booted simulator: the real script
boots, fails cleanly with the expected message, and Wukong maps the
non-zero exit to TestError::ScriptFailed.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 cli/src/commands/test/ios/mod.rs              | 103 ++-
 cli/src/commands/test/ios/sim.sh              |  19 -
 cli/src/commands/test/ios/simclaw/bin/sim     | 445 +++++++++++
 .../test/ios/simclaw/lib/simclaw/bootstrap.sh | 144 ++++
 .../test/ios/simclaw/lib/simclaw/coords.sh    |  43 +
 .../test/ios/simclaw/lib/simclaw/core.sh      |   6 +
 .../test/ios/simclaw/lib/simclaw/device.sh    | 239 ++++++
 .../test/ios/simclaw/lib/simclaw/inspect.sh   | 507 ++++++++++++
 .../ios/simclaw/lib/simclaw/layout_map.sh     | 748 ++++++++++++++++++
 .../test/ios/simclaw/lib/simclaw/misc.sh      | 139 ++++
 .../test/ios/simclaw/lib/simclaw/nav.sh       | 184 +++++
 .../test/ios/simclaw/lib/simclaw/setup.sh     | 181 +++++
 .../lib/simclaw/swift/pickwindow.swift        |  25 +
 .../test/ios/simclaw/lib/simclaw/touch.sh     | 108 +++
 .../test/ios/simclaw/lib/simclaw/type.sh      | 132 ++++
 .../test/ios/simclaw/lib/simclaw/wait.sh      | 197 +++++
 .../test/ios/simclaw/lib/simclaw/wda.sh       | 476 +++++++++++
 17 files changed, 3663 insertions(+), 33 deletions(-)
 delete mode 100644 cli/src/commands/test/ios/sim.sh
 create mode 100755 cli/src/commands/test/ios/simclaw/bin/sim
 create mode 100644 cli/src/commands/test/ios/simclaw/lib/simclaw/bootstrap.sh
 create mode 100644 cli/src/commands/test/ios/simclaw/lib/simclaw/coords.sh
 create mode 100644 cli/src/commands/test/ios/simclaw/lib/simclaw/core.sh
 create mode 100644 cli/src/commands/test/ios/simclaw/lib/simclaw/device.sh
 create mode 100644 cli/src/commands/test/ios/simclaw/lib/simclaw/inspect.sh
 create mode 100644 cli/src/commands/test/ios/simclaw/lib/simclaw/layout_map.sh
 create mode 100644 cli/src/commands/test/ios/simclaw/lib/simclaw/misc.sh
 create mode 100644 cli/src/commands/test/ios/simclaw/lib/simclaw/nav.sh
 create mode 100644 cli/src/commands/test/ios/simclaw/lib/simclaw/setup.sh
 create mode 100644 cli/src/commands/test/ios/simclaw/lib/simclaw/swift/pickwindow.swift
 create mode 100644 cli/src/commands/test/ios/simclaw/lib/simclaw/touch.sh
 create mode 100644 cli/src/commands/test/ios/simclaw/lib/simclaw/type.sh
 create mode 100644 cli/src/commands/test/ios/simclaw/lib/simclaw/wait.sh
 create mode 100644 cli/src/commands/test/ios/simclaw/lib/simclaw/wda.sh

diff --git a/cli/src/commands/test/ios/mod.rs b/cli/src/commands/test/ios/mod.rs
index af383d77..78a741b7 100644
--- a/cli/src/commands/test/ios/mod.rs
+++ b/cli/src/commands/test/ios/mod.rs
@@ -10,8 +10,76 @@ use crate::error::{TestError, WKCliError};
 
 use super::platform::{Element, LayoutMap, PlatformBackend};
 
-const SIM_SCRIPT: &str = include_str!("sim.sh");
-const SCRIPT_FILENAME: &str = "sim.sh";
+/// 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.
+const SIMCLAW_FILES: &[(&str, &str)] = &[
+    ("bin/sim", include_str!("simclaw/bin/sim")),
+    (
+        "lib/simclaw/bootstrap.sh",
+        include_str!("simclaw/lib/simclaw/bootstrap.sh"),
+    ),
+    (
+        "lib/simclaw/coords.sh",
+        include_str!("simclaw/lib/simclaw/coords.sh"),
+    ),
+    (
+        "lib/simclaw/core.sh",
+        include_str!("simclaw/lib/simclaw/core.sh"),
+    ),
+    (
+        "lib/simclaw/device.sh",
+        include_str!("simclaw/lib/simclaw/device.sh"),
+    ),
+    (
+        "lib/simclaw/inspect.sh",
+        include_str!("simclaw/lib/simclaw/inspect.sh"),
+    ),
+    (
+        "lib/simclaw/layout_map.sh",
+        include_str!("simclaw/lib/simclaw/layout_map.sh"),
+    ),
+    (
+        "lib/simclaw/misc.sh",
+        include_str!("simclaw/lib/simclaw/misc.sh"),
+    ),
+    (
+        "lib/simclaw/nav.sh",
+        include_str!("simclaw/lib/simclaw/nav.sh"),
+    ),
+    (
+        "lib/simclaw/setup.sh",
+        include_str!("simclaw/lib/simclaw/setup.sh"),
+    ),
+    (
+        "lib/simclaw/touch.sh",
+        include_str!("simclaw/lib/simclaw/touch.sh"),
+    ),
+    (
+        "lib/simclaw/type.sh",
+        include_str!("simclaw/lib/simclaw/type.sh"),
+    ),
+    (
+        "lib/simclaw/wait.sh",
+        include_str!("simclaw/lib/simclaw/wait.sh"),
+    ),
+    (
+        "lib/simclaw/wda.sh",
+        include_str!("simclaw/lib/simclaw/wda.sh"),
+    ),
+    (
+        "lib/simclaw/swift/pickwindow.swift",
+        include_str!("simclaw/lib/simclaw/swift/pickwindow.swift"),
+    ),
+];
+
+/// Path under `~/.config/wukong/scripts/` where the simClaw tree lives.
+const EXTRACT_SUBDIR: &str = "simclaw";
+
+/// Entry script relative to `EXTRACT_SUBDIR`.
+const ENTRY_SCRIPT: &str = "bin/sim";
 
 pub struct IosBackend {
     device: Option<String>,
@@ -26,33 +94,40 @@ impl IosBackend {
         }
     }
 
-    /// The bundled sim.sh is rewritten on every call so a Wukong upgrade
-    /// always ships the matching backend — stale copies aren't possible.
-    /// chmod runs only on first creation; overwrites preserve the inode mode.
+    /// Extract the bundled simClaw tree to `~/.config/wukong/scripts/simclaw/`
+    /// and return the path to its `bin/sim` entry script. Every file is
+    /// rewritten on each call so a Wukong upgrade always ships the matching
+    /// backend — stale copies aren't possible. 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 dir = dirs::home_dir().ok_or_else(|| {
+        let mut root = dirs::home_dir().ok_or_else(|| {
             WKCliError::TestError(TestError::ScriptExtractionFailed(
                 "could not resolve home directory".into(),
             ))
         })?;
-        dir.extend([".config", "wukong", "scripts"]);
-        std::fs::create_dir_all(&dir).map_err(extract_err)?;
+        root.extend([".config", "wukong", "scripts", EXTRACT_SUBDIR]);
+
+        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)?;
+        }
 
-        let path = dir.join(SCRIPT_FILENAME);
-        let newly_created = !path.exists();
-        std::fs::write(&path, SIM_SCRIPT).map_err(extract_err)?;
+        let entry = root.join(ENTRY_SCRIPT);
 
         #[cfg(unix)]
-        if newly_created {
+        {
             use std::os::unix::fs::PermissionsExt;
-            std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755))
+            std::fs::set_permissions(&entry, std::fs::Permissions::from_mode(0o755))
                 .map_err(extract_err)?;
         }
 
-        Ok(path)
+        Ok(entry)
     }
 
     fn build_command(&self, subcommand: &str, args: &[String]) -> Result<Command, WKCliError> {
diff --git a/cli/src/commands/test/ios/sim.sh b/cli/src/commands/test/ios/sim.sh
deleted file mode 100644
index 56d4bdf2..00000000
--- a/cli/src/commands/test/ios/sim.sh
+++ /dev/null
@@ -1,19 +0,0 @@
-#!/usr/bin/env bash
-# Placeholder for the simClaw bash backend.
-#
-# The real script (~3000 lines) is owned and maintained by a separate team and
-# will be dropped in here before the `wukong test` feature ships. The Rust CLI
-# layer (cli/src/commands/test/ios/mod.rs) extracts this file to
-# ~/.config/wukong/scripts/sim.sh on first invocation and delegates every
-# subcommand to it.
-#
-# Contract (see RFC: "iOS backend: bash delegate"):
-#   sim [--device <UDID>] <subcommand> [args...]
-# Exit codes are mapped to WKCliError variants by the Rust layer.
-
-set -euo pipefail
-
-echo "wukong test ios backend is not yet installed." >&2
-echo "This is a placeholder. Replace cli/src/commands/test/ios/sim.sh with" >&2
-echo "the real simClaw script before release." >&2
-exit 127
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..bb1ed6ee
--- /dev/null
+++ b/cli/src/commands/test/ios/simclaw/bin/sim
@@ -0,0 +1,445 @@
+#!/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, 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
+    ;;
+  ""|--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..228b00e6
--- /dev/null
+++ b/cli/src/commands/test/ios/simclaw/lib/simclaw/inspect.sh
@@ -0,0 +1,507 @@
+# 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
+
+  [[ -n "$element_id" ]] || die "find-element: '$search_label' not found"
+
+  # 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'"
+}
+
+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"
+}
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..d4feec8c
--- /dev/null
+++ b/cli/src/commands/test/ios/simclaw/lib/simclaw/layout_map.sh
@@ -0,0 +1,748 @@
+# 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"
+
+# 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"
+  else
+    echo "$enriched"
+  fi
+}
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..5f281b3d
--- /dev/null
+++ b/cli/src/commands/test/ios/simclaw/lib/simclaw/nav.sh
@@ -0,0 +1,184 @@
+# 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() {
+  [[ $# -ge 1 ]] || die "Usage: sim tap-element <label>"
+  local label="$1"
+  _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]
+
+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():
+    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" 2>/dev/null) || true
+  rm -f "$tmp_xml" "$tmp_py"
+
+  [[ -n "$found" ]] || die "tap-element: '$label' not found in current viewport"
+
+  local cx cy
+  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)
+
+  _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..eb655b59
--- /dev/null
+++ b/cli/src/commands/test/ios/simclaw/lib/simclaw/setup.sh
@@ -0,0 +1,181 @@
+# 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_runner="/tmp/WDA_DerivedData/Build/Products/Debug-iphonesimulator/WebDriverAgentRunner-Runner.app"
+
+  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
+
+  if [[ -d "$wda_runner" ]]; then
+    echo "    WDA already built at $wda_runner — skipping build."
+  else
+    echo "    Building WDA (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 /tmp/WDA_DerivedData \
+      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 WDA works on
+    # older iOS versions (< 26) where that framework does not exist. Without this
+    # patch, dyld crashes on launch because _LocationEssentials is a hard dependency
+    # introduced when CoreLocation is compiled against the iOS 26+ SDK.
+    _wda_patch_ios_compat "/tmp/WDA_DerivedData/Build/Products"
+  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..dd831e14
--- /dev/null
+++ b/cli/src/commands/test/ios/simclaw/lib/simclaw/wda.sh
@@ -0,0 +1,476 @@
+# 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 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. 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="/tmp/WDA_DerivedData"
+  # WDA must be pre-built — this path is created by building WebDriverAgent once.
+  [[ -d "$wda_derived" ]] || die "WDA DerivedData not found at $wda_derived — build WDA first"
+
+  # 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}"
+}

From 09a1e626e4953c41065bfc320c615ae9099d1112 Mon Sep 17 00:00:00 2001
From: Fauzaan <mfauzaan@icloud.com>
Date: Tue, 21 Apr 2026 07:45:58 +0000
Subject: [PATCH 03/11] Add provenance, re-vendor workflow, and manifest drift
 guard
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three safeguards so updates from the simClaw team can't silently break
the iOS integration:

1. VENDORED.md records the upstream repo, the vendored commit SHA, and
   the update procedure. Locks down the version for audit and makes
   provenance obvious to anyone browsing the tree.

2. revendor.sh automates the copy + diff + SHA report. Run it with a
   path to a local homebrew-simClaw checkout; it prints any added or
   removed files so the caller knows exactly what SIMCLAW_FILES in
   ios/mod.rs must change to stay in sync.

3. manifest_matches_tree test in ios::tests fails if the on-disk
   simclaw/ tree contains any bin/ or lib/ file not listed in
   SIMCLAW_FILES (and vice versa). This catches the drift case where
   upstream adds a new lib file and a re-vendor forgets to wire it
   through — compile succeeds but sourcing fails at runtime.

The test explicitly ignores VENDORED.md, revendor.sh, and anything
outside bin/ + lib/ so documentation/tooling doesn't confuse the guard.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 cli/src/commands/test/ios/mod.rs              | 57 +++++++++++++++
 cli/src/commands/test/ios/simclaw/VENDORED.md | 40 +++++++++++
 cli/src/commands/test/ios/simclaw/revendor.sh | 72 +++++++++++++++++++
 3 files changed, 169 insertions(+)
 create mode 100644 cli/src/commands/test/ios/simclaw/VENDORED.md
 create mode 100755 cli/src/commands/test/ios/simclaw/revendor.sh

diff --git a/cli/src/commands/test/ios/mod.rs b/cli/src/commands/test/ios/mod.rs
index 78a741b7..e06497bb 100644
--- a/cli/src/commands/test/ios/mod.rs
+++ b/cli/src/commands/test/ios/mod.rs
@@ -378,3 +378,60 @@ impl PlatformBackend for IosBackend {
         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_string_lossy()
+                    .into_owned();
+                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..ada21222
--- /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/justinchampappilly-mindvalley/homebrew-simClaw
+- **Commit:** `2381b2da5139a49f063a6e0a4d907c113771ecab`
+- **Ref:** `[bump] - Bump formula to v1.0.6`
+- **Vendored on:** 2026-04-21
+
+## 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/revendor.sh b/cli/src/commands/test/ios/simclaw/revendor.sh
new file mode 100755
index 00000000..a5375523
--- /dev/null
+++ b/cli/src/commands/test/ios/simclaw/revendor.sh
@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Re-vendor the simClaw tree from a local checkout of the upstream repo.
+#
+# Usage:
+#   ./revendor.sh <path-to-homebrew-simClaw>
+#
+# 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-homebrew-simClaw>" >&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 homebrew-simClaw (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/"
+mkdir -p "$HERE/bin"
+cp "$UPSTREAM/bin/sim" "$HERE/bin/sim"
+
+echo "==> Copying lib/simclaw/"
+mkdir -p "$HERE/lib/simclaw"
+cp "$UPSTREAM"/lib/simclaw/*.sh "$HERE/lib/simclaw/"
+if [[ -d "$UPSTREAM/lib/simclaw/swift" ]]; then
+  mkdir -p "$HERE/lib/simclaw/swift"
+  cp "$UPSTREAM"/lib/simclaw/swift/*.swift "$HERE/lib/simclaw/swift/" 2>/dev/null || true
+fi
+
+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

From 94b995d89f80e1af58e5c1cd32e04aa0dfa96789 Mon Sep 17 00:00:00 2001
From: Fauzaan <mfauzaan@icloud.com>
Date: Tue, 21 Apr 2026 07:51:14 +0000
Subject: [PATCH 04/11] Simplify simClaw extraction: version-gate, manifest
 macro, minor polish

Five tweaks from a /simplify pass:

- script_path() now skips the 15-file rewrite when a .wukong-version
  marker inside the extracted dir matches CARGO_PKG_VERSION. Agent
  workflows that fire many test subcommands no longer pay extraction
  cost per call; upgrades still force a fresh extract because the
  marker disagrees.

- Collapse the SIMCLAW_FILES manifest with a simclaw_files! macro so
  each entry is a single literal. Removes the hand-typed simclaw/
  prefix duplicated in every tuple and the drift risk where the key
  string and include_str! path could disagree.

- Replace to_string_lossy() in collect_tree with to_str().expect() so
  a non-UTF-8 path fails loudly instead of silently producing a key
  that can't match the manifest.

- revendor.sh uses `cp -R` for whole bin/ and lib/ subtrees instead of
  unquoted globs. Future-proof against upstream adding files whose
  names contain spaces.

- Drop redundant doc comments on EXTRACT_SUBDIR / ENTRY_SCRIPT.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 cli/src/commands/test/ios/mod.rs              | 115 +++++++-----------
 cli/src/commands/test/ios/simclaw/revendor.sh |  14 +--
 2 files changed, 47 insertions(+), 82 deletions(-)

diff --git a/cli/src/commands/test/ios/mod.rs b/cli/src/commands/test/ios/mod.rs
index e06497bb..536e5c64 100644
--- a/cli/src/commands/test/ios/mod.rs
+++ b/cli/src/commands/test/ios/mod.rs
@@ -15,71 +15,33 @@ use super::platform::{Element, LayoutMap, PlatformBackend};
 /// 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.
-const SIMCLAW_FILES: &[(&str, &str)] = &[
-    ("bin/sim", include_str!("simclaw/bin/sim")),
-    (
-        "lib/simclaw/bootstrap.sh",
-        include_str!("simclaw/lib/simclaw/bootstrap.sh"),
-    ),
-    (
-        "lib/simclaw/coords.sh",
-        include_str!("simclaw/lib/simclaw/coords.sh"),
-    ),
-    (
-        "lib/simclaw/core.sh",
-        include_str!("simclaw/lib/simclaw/core.sh"),
-    ),
-    (
-        "lib/simclaw/device.sh",
-        include_str!("simclaw/lib/simclaw/device.sh"),
-    ),
-    (
-        "lib/simclaw/inspect.sh",
-        include_str!("simclaw/lib/simclaw/inspect.sh"),
-    ),
-    (
-        "lib/simclaw/layout_map.sh",
-        include_str!("simclaw/lib/simclaw/layout_map.sh"),
-    ),
-    (
-        "lib/simclaw/misc.sh",
-        include_str!("simclaw/lib/simclaw/misc.sh"),
-    ),
-    (
-        "lib/simclaw/nav.sh",
-        include_str!("simclaw/lib/simclaw/nav.sh"),
-    ),
-    (
-        "lib/simclaw/setup.sh",
-        include_str!("simclaw/lib/simclaw/setup.sh"),
-    ),
-    (
-        "lib/simclaw/touch.sh",
-        include_str!("simclaw/lib/simclaw/touch.sh"),
-    ),
-    (
-        "lib/simclaw/type.sh",
-        include_str!("simclaw/lib/simclaw/type.sh"),
-    ),
-    (
-        "lib/simclaw/wait.sh",
-        include_str!("simclaw/lib/simclaw/wait.sh"),
-    ),
-    (
-        "lib/simclaw/wda.sh",
-        include_str!("simclaw/lib/simclaw/wda.sh"),
-    ),
-    (
-        "lib/simclaw/swift/pickwindow.swift",
-        include_str!("simclaw/lib/simclaw/swift/pickwindow.swift"),
-    ),
-];
-
-/// Path under `~/.config/wukong/scripts/` where the simClaw tree lives.
-const EXTRACT_SUBDIR: &str = "simclaw";
+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/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",
+);
 
-/// Entry script relative to `EXTRACT_SUBDIR`.
+const EXTRACT_SUBDIR: &str = "simclaw";
 const ENTRY_SCRIPT: &str = "bin/sim";
+const VERSION_MARKER: &str = ".wukong-version";
 
 pub struct IosBackend {
     device: Option<String>,
@@ -95,10 +57,11 @@ impl IosBackend {
     }
 
     /// Extract the bundled simClaw tree to `~/.config/wukong/scripts/simclaw/`
-    /// and return the path to its `bin/sim` entry script. Every file is
-    /// rewritten on each call so a Wukong upgrade always ships the matching
-    /// backend — stale copies aren't possible. Only `bin/sim` needs the
-    /// executable bit; the `.sh` helpers are sourced, not invoked.
+    /// 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()));
@@ -109,6 +72,15 @@ impl IosBackend {
             ))
         })?;
         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);
@@ -118,8 +90,6 @@ impl IosBackend {
             std::fs::write(&dest, contents).map_err(extract_err)?;
         }
 
-        let entry = root.join(ENTRY_SCRIPT);
-
         #[cfg(unix)]
         {
             use std::os::unix::fs::PermissionsExt;
@@ -127,6 +97,8 @@ impl IosBackend {
                 .map_err(extract_err)?;
         }
 
+        std::fs::write(&marker, expected_version).map_err(extract_err)?;
+
         Ok(entry)
     }
 
@@ -421,8 +393,9 @@ mod tests {
                 let rel = path
                     .strip_prefix(base)
                     .expect("child under base")
-                    .to_string_lossy()
-                    .into_owned();
+                    .to_str()
+                    .expect("simclaw paths must be valid UTF-8")
+                    .to_string();
                 out.push(rel);
             }
         }
diff --git a/cli/src/commands/test/ios/simclaw/revendor.sh b/cli/src/commands/test/ios/simclaw/revendor.sh
index a5375523..420bfafd 100755
--- a/cli/src/commands/test/ios/simclaw/revendor.sh
+++ b/cli/src/commands/test/ios/simclaw/revendor.sh
@@ -27,17 +27,9 @@ 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/"
-mkdir -p "$HERE/bin"
-cp "$UPSTREAM/bin/sim" "$HERE/bin/sim"
-
-echo "==> Copying lib/simclaw/"
-mkdir -p "$HERE/lib/simclaw"
-cp "$UPSTREAM"/lib/simclaw/*.sh "$HERE/lib/simclaw/"
-if [[ -d "$UPSTREAM/lib/simclaw/swift" ]]; then
-  mkdir -p "$HERE/lib/simclaw/swift"
-  cp "$UPSTREAM"/lib/simclaw/swift/*.swift "$HERE/lib/simclaw/swift/" 2>/dev/null || true
-fi
+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)

From 6830cd8ae0133ce45c8721186370f67f276ed024 Mon Sep 17 00:00:00 2001
From: Fauzaan <mfauzaan@icloud.com>
Date: Tue, 21 Apr 2026 08:23:59 +0000
Subject: [PATCH 05/11] Loosen test JSON schemas to serde_json::Value
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

End-to-end smoke against real Settings.app revealed that the LayoutMap
and Element structs I initially wrote based on the RFC docs don't match
what the simClaw script actually emits — e.g. the script uses
navigation.title / interactive / scroll.above_fold, not the guessed
screen_title / elements / scroll_hints.

Since the schema is owned by the simClaw team and hasn't been frozen
into a stable contract, pass the JSON through as serde_json::Value so
consumers can work with whatever shape the script emits today. Retighten
to typed structs once the upstream schema is contracted.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 cli/src/commands/test/platform.rs | 29 ++++++++---------------------
 1 file changed, 8 insertions(+), 21 deletions(-)

diff --git a/cli/src/commands/test/platform.rs b/cli/src/commands/test/platform.rs
index 0c0fb05a..60ea32cd 100644
--- a/cli/src/commands/test/platform.rs
+++ b/cli/src/commands/test/platform.rs
@@ -3,27 +3,14 @@ use serde::{Deserialize, Serialize};
 
 use crate::error::WKCliError;
 
-#[derive(Debug, Serialize, Deserialize)]
-pub struct Element {
-    pub role: String,
-    pub label: String,
-    pub x: f64,
-    pub y: f64,
-    pub w: f64,
-    pub h: f64,
-}
-
-#[derive(Debug, Serialize, Deserialize)]
-pub struct LayoutMap {
-    pub screen_title: Option<String>,
-    pub back_button: Option<Element>,
-    pub tab_bar: Vec<serde_json::Value>,
-    pub elements: Vec<Element>,
-    pub visible_text: Vec<String>,
-    pub scroll_hints: serde_json::Value,
-    pub context: Option<String>,
-    pub suggested_actions: Vec<String>,
-}
+// 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 {

From d809aed0b7affd3454f6613eb49067eeafc0045b Mon Sep 17 00:00:00 2001
From: Fauzaan <mfauzaan@icloud.com>
Date: Tue, 21 Apr 2026 08:35:34 +0000
Subject: [PATCH 06/11] Fix layout-map emptiness and JSON parse for compound
 commands
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two real-world bugs found while driving Settings.app end-to-end:

1. Upstream simClaw creates the WDA session with snapshotMaxDepth=15 and
   snapshotMaxChildren=25, which truncates Settings.app's tree at exactly
   25 elements (root + nav + title). Every label-based primitive
   (layout-map, tap-on, find-element, scroll-to-visible, wait) came back
   empty. After setup()/wda_start() succeeds, we now POST permissive
   settings (60/200) to /appium/settings via reqwest — transparent to
   the user, best-effort silent no-op if WDA isn't reachable. Read the
   session ID from whichever bootstrap cache the script wrote (UDID-keyed
   or the _default.json fallback).

2. cmd_tap_and_wait prints a "READY: <label>" progress line on stdout
   before cmd_layout_map emits the JSON payload, so serde_json chokes on
   the prefix. Harden run_json to slice from the first `{` or `[`,
   ignoring any leading progress lines. Generally useful — bash scripts
   commonly mix progress and structured output on stdout.

Both workarounds can be removed once the simClaw team raises (or exposes)
the snapshot caps and moves READY/progress lines to stderr.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 cli/src/commands/test/ios/mod.rs | 68 ++++++++++++++++++++++++++++++--
 1 file changed, 65 insertions(+), 3 deletions(-)

diff --git a/cli/src/commands/test/ios/mod.rs b/cli/src/commands/test/ios/mod.rs
index 536e5c64..3a6ee811 100644
--- a/cli/src/commands/test/ios/mod.rs
+++ b/cli/src/commands/test/ios/mod.rs
@@ -43,6 +43,16 @@ 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>,
@@ -176,7 +186,15 @@ impl IosBackend {
         args: &[String],
     ) -> Result<T, WKCliError> {
         let stdout = self.run_capture(subcommand, args).await?;
-        serde_json::from_str::<T>(stdout.trim()).map_err(|e| {
+        // 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(|c: char| c == '{' || c == '[');
+        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(),
@@ -189,15 +207,59 @@ 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
+            .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
+        self.run_streaming("wda-start", &[port.to_string()]).await?;
+        apply_permissive_snapshot_settings(port).await;
+        Ok(())
     }
 
     async fn status(&self) -> Result<(), WKCliError> {

From 278f8719ebda72f8c23d3804e16386ff8fd4b32e Mon Sep 17 00:00:00 2001
From: Fauzaan <mfauzaan@icloud.com>
Date: Tue, 28 Apr 2026 06:47:47 +0000
Subject: [PATCH 07/11] style: cargo fmt

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 cli/src/commands/test/ios/mod.rs | 39 ++++++++++++++++----------------
 cli/src/commands/test/mod.rs     | 13 ++++-------
 2 files changed, 23 insertions(+), 29 deletions(-)

diff --git a/cli/src/commands/test/ios/mod.rs b/cli/src/commands/test/ios/mod.rs
index 3a6ee811..20fb7fff 100644
--- a/cli/src/commands/test/ios/mod.rs
+++ b/cli/src/commands/test/ios/mod.rs
@@ -73,8 +73,9 @@ impl IosBackend {
     /// 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 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(
@@ -132,11 +133,7 @@ impl IosBackend {
     /// `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> {
+    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());
@@ -162,11 +159,7 @@ impl IosBackend {
         Ok(collected)
     }
 
-    async fn run_streaming(
-        &self,
-        subcommand: &str,
-        args: &[String],
-    ) -> Result<(), WKCliError> {
+    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());
@@ -250,8 +243,11 @@ async fn apply_permissive_snapshot_settings(port: u16) {
 #[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?;
+        self.run_streaming(
+            "setup",
+            &[app.to_string(), "--port".into(), port.to_string()],
+        )
+        .await?;
         apply_permissive_snapshot_settings(port).await;
         Ok(())
     }
@@ -276,7 +272,8 @@ impl PlatformBackend for IosBackend {
     }
 
     async fn tap_element(&self, label: &str) -> Result<(), WKCliError> {
-        self.run_streaming("tap-element", &[label.to_string()]).await
+        self.run_streaming("tap-element", &[label.to_string()])
+            .await
     }
 
     async fn tap_and_wait(
@@ -396,7 +393,8 @@ impl PlatformBackend for IosBackend {
     }
 
     async fn screenshot(&self, output: &str) -> Result<(), WKCliError> {
-        self.run_streaming("screenshot", &[output.to_string()]).await
+        self.run_streaming("screenshot", &[output.to_string()])
+            .await
     }
 
     async fn ensure_foreground_app(&self, bundle_id: Option<&str>) -> Result<(), WKCliError> {
@@ -425,14 +423,15 @@ mod tests {
     /// 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 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 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();
diff --git a/cli/src/commands/test/mod.rs b/cli/src/commands/test/mod.rs
index 57c34101..9289c95f 100644
--- a/cli/src/commands/test/mod.rs
+++ b/cli/src/commands/test/mod.rs
@@ -207,11 +207,7 @@ async fn dispatch(
             y2,
             steps,
             step_ms,
-        } => {
-            backend
-                .swipe(*x1, *y1, *x2, *y2, *steps, *step_ms)
-                .await?
-        }
+        } => 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?,
@@ -240,10 +236,9 @@ async fn dispatch(
         },
         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::Describe { depth, interactive } => {
+            print_json(&backend.describe(*depth, *interactive).await?)?
+        }
         TestSubcommand::Screenshot { output } => backend.screenshot(output).await?,
     }
     Ok(true)

From 8b0408ede0b4a1e1a8757d08a721d39ac4d282f4 Mon Sep 17 00:00:00 2001
From: Fauzaan <mfauzaan@icloud.com>
Date: Tue, 28 Apr 2026 07:04:20 +0000
Subject: [PATCH 08/11] style: fix clippy warnings for Rust 1.81
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Drop unused Deserialize/Serialize imports in test/platform.rs (LayoutMap
  and Element are now serde_json::Value aliases — neither derive is needed).
- Replace closure char comparison with array pattern in run_json
  (manual_pattern_char_comparison clippy lint).

Also re-run cargo fmt under the 1.81 toolchain to match CI exactly; 1.90's
rustfmt produced a slightly different layout that CI's 1.81 rejected.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 cli/src/commands/test/ios/mod.rs  | 2 +-
 cli/src/commands/test/platform.rs | 1 -
 2 files changed, 1 insertion(+), 2 deletions(-)

diff --git a/cli/src/commands/test/ios/mod.rs b/cli/src/commands/test/ios/mod.rs
index 20fb7fff..0a143edb 100644
--- a/cli/src/commands/test/ios/mod.rs
+++ b/cli/src/commands/test/ios/mod.rs
@@ -183,7 +183,7 @@ impl IosBackend {
         // 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(|c: char| c == '{' || c == '[');
+        let json_start = stdout.find(['{', '[']);
         let payload = json_start
             .map(|i| stdout[i..].trim())
             .unwrap_or(stdout.trim());
diff --git a/cli/src/commands/test/platform.rs b/cli/src/commands/test/platform.rs
index 60ea32cd..1d735301 100644
--- a/cli/src/commands/test/platform.rs
+++ b/cli/src/commands/test/platform.rs
@@ -1,5 +1,4 @@
 use async_trait::async_trait;
-use serde::{Deserialize, Serialize};
 
 use crate::error::WKCliError;
 

From e3215a3fe6ed70df6a7e4d682aac2d1036b56822 Mon Sep 17 00:00:00 2001
From: Fauzaan <mfauzaan@icloud.com>
Date: Tue, 28 Apr 2026 07:44:52 +0000
Subject: [PATCH 09/11] test(completion): update snapshots for test subcommand

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../completion__wukong_completion_bash.snap   | 1312 ++++++++++++++++-
 .../completion__wukong_completion_fish.snap   |  190 ++-
 .../completion__wukong_completion_zsh.snap    | 1025 +++++++++++++
 3 files changed, 2507 insertions(+), 20 deletions(-)

diff --git a/cli/tests/snapshots/completion__wukong_completion_bash.snap b/cli/tests/snapshots/completion__wukong_completion_bash.snap
index 330c742c..840e309b 100644
--- a/cli/tests/snapshots/completion__wukong_completion_bash.snap
+++ b/cli/tests/snapshots/completion__wukong_completion_bash.snap
@@ -43,6 +43,9 @@ _wukong() {
             wukong,login)
                 cmd="wukong__login"
                 ;;
+            wukong,test)
+                cmd="wukong__test"
+                ;;
             wukong,tui)
                 cmd="wukong__tui"
                 ;;
@@ -247,6 +250,9 @@ _wukong() {
             wukong__help,login)
                 cmd="wukong__help__login"
                 ;;
+            wukong__help,test)
+                cmd="wukong__help__test"
+                ;;
             wukong__help,tui)
                 cmd="wukong__help__tui"
                 ;;
@@ -307,6 +313,216 @@ _wukong() {
             wukong__help__google,login)
                 cmd="wukong__help__google__login"
                 ;;
+            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__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
@@ -314,7 +530,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 tui help"
+            opts="-v -q -h -V --verbose --quiet --report --canary --help --version init application deployment dev config login google completion tui test help"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 1 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
@@ -1308,7 +1524,7 @@ _wukong() {
             return 0
             ;;
         wukong__help)
-            opts="init application deployment dev config login google completion tui help"
+            opts="init application deployment dev config login google completion tui test help"
             if [[ ${cur} == -* || ${COMP_CWORD} -eq 2 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
@@ -1713,8 +1929,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
@@ -1727,9 +1943,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
@@ -1741,9 +1957,191 @@ _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
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__help__test__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__help__test__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__help__test__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__help__test__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__help__test__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__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}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+            return 0
+            ;;
+        wukong__help__test__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__help__test__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__help__test__swipe)
+            opts=""
+            if [[ ${cur} == -* || ${COMP_CWORD} -eq 4 ]] ; then
                 COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                 return 0
             fi
@@ -1755,6 +2153,900 @@ _wukong() {
             COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
             return 0
             ;;
+        wukong__help__test__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__help__test__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__help__test__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__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
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            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
+                COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
+                return 0
+            fi
+            case "${prev}" in
+                *)
+                    COMPREPLY=()
+                    ;;
+            esac
+            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
+                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 68e90c49..72b28b23 100644
--- a/cli/tests/snapshots/completion__wukong_completion_fish.snap
+++ b/cli/tests/snapshots/completion__wukong_completion_fish.snap
@@ -43,6 +43,7 @@ complete -c wukong -n "__fish_wukong_needs_command" -f -a "login" -d 'Login to s
 complete -c wukong -n "__fish_wukong_needs_command" -f -a "google" -d 'This command group contains the commands to interact with Google services'
 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 "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'
@@ -213,16 +214,167 @@ 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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'
@@ -236,3 +388,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 config" -f -a "set" -d 'Set the value of a configuration'
 complete -c wukong -n "__fish_wukong_using_subcommand help; and __fish_seen_subcommand_from config" -f -a "get" -d 'Print the value of a configuration'
 complete -c wukong -n "__fish_wukong_using_subcommand help; and __fish_seen_subcommand_from google" -f -a "login" -d 'Login to Google'
+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 4c7d1b25..9a325c52 100644
--- a/cli/tests/snapshots/completion__wukong_completion_zsh.snap
+++ b/cli/tests/snapshots/completion__wukong_completion_zsh.snap
@@ -751,6 +751,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" \
@@ -959,6 +1433,118 @@ _arguments "${_arguments_options[@]}" : \
 _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
@@ -984,6 +1570,7 @@ _wukong_commands() {
 'google:This command group contains the commands to interact with Google services' \
 'completion:Generate wukong cli completions for your shell to stdout' \
 '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 "$@"
@@ -1394,6 +1981,7 @@ _wukong__help_commands() {
 'google:This command group contains the commands to interact with Google services' \
 'completion:Generate wukong cli completions for your shell to stdout' \
 '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 "$@"
@@ -1564,6 +2152,139 @@ _wukong__help__login_commands() {
     local commands; commands=()
     _describe -t commands 'wukong help login 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=()
@@ -1579,6 +2300,310 @@ _wukong__login_commands() {
     local commands; commands=()
     _describe -t commands 'wukong login 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=()

From 7dbc36a5a086ba899249333335dd2f870373cb9d Mon Sep 17 00:00:00 2001
From: Fauzaan <mfauzaan@icloud.com>
Date: Tue, 28 Apr 2026 08:05:25 +0000
Subject: [PATCH 10/11] test: update wukong help snapshot for test subcommand

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../snapshots/wukong__wukong_help_without_config_file.snap      | 2 ++
 1 file changed, 2 insertions(+)

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 32c6fcd2..09f8a7a3 100644
--- a/cli/tests/snapshots/wukong__wukong_help_without_config_file.snap
+++ b/cli/tests/snapshots/wukong__wukong_help_without_config_file.snap
@@ -20,6 +20,8 @@ Commands:
   google       This command group contains the commands to interact with Google services
   completion   Generate wukong cli completions for your shell to stdout
   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:

From 28a4ac69ca8aa7b2de31336a32b3bc81ca51789f Mon Sep 17 00:00:00 2001
From: Fauzaan <mfauzaan@icloud.com>
Date: Mon, 11 May 2026 10:33:19 +0000
Subject: [PATCH 11/11] chore: re-vendor simClaw from mv-simclaw-ios @ 572a5879
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Switch upstream from homebrew-simClaw to mindvalley/mv-simclaw-ios (which
is now the source of truth — homebrew-simClaw repo carried only the
formula after the migration). Re-vendors bin/sim + lib/simclaw/ and adds
lib/simclaw/login.sh to the SIMCLAW_FILES manifest so the drift-guard
test stays green. login.sh is vendored dormant — IosBackend does not
dispatch to it; login flows belong at the user/skill layer composed from
tap-on/type/wait primitives, not as a wukong CLI verb.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 cli/src/commands/test/ios/mod.rs              |   1 +
 cli/src/commands/test/ios/simclaw/VENDORED.md |   8 +-
 cli/src/commands/test/ios/simclaw/bin/sim     |   6 +-
 .../test/ios/simclaw/lib/simclaw/inspect.sh   | 216 ++++++++++++-
 .../ios/simclaw/lib/simclaw/layout_map.sh     | 158 +++++++++
 .../test/ios/simclaw/lib/simclaw/login.sh     | 301 ++++++++++++++++++
 .../test/ios/simclaw/lib/simclaw/nav.sh       | 179 ++++++++++-
 .../test/ios/simclaw/lib/simclaw/setup.sh     |  38 ++-
 .../test/ios/simclaw/lib/simclaw/wda.sh       |  25 +-
 cli/src/commands/test/ios/simclaw/revendor.sh |   6 +-
 10 files changed, 904 insertions(+), 34 deletions(-)
 create mode 100644 cli/src/commands/test/ios/simclaw/lib/simclaw/login.sh

diff --git a/cli/src/commands/test/ios/mod.rs b/cli/src/commands/test/ios/mod.rs
index 0a143edb..922062f1 100644
--- a/cli/src/commands/test/ios/mod.rs
+++ b/cli/src/commands/test/ios/mod.rs
@@ -29,6 +29,7 @@ const SIMCLAW_FILES: &[(&str, &str)] = simclaw_files!(
     "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",
diff --git a/cli/src/commands/test/ios/simclaw/VENDORED.md b/cli/src/commands/test/ios/simclaw/VENDORED.md
index ada21222..c52f5cac 100644
--- a/cli/src/commands/test/ios/simclaw/VENDORED.md
+++ b/cli/src/commands/test/ios/simclaw/VENDORED.md
@@ -7,10 +7,10 @@ delegate to `bin/sim`, which is bundled into the Wukong binary via
 
 ## Upstream
 
-- **Repo:** https://github.com/justinchampappilly-mindvalley/homebrew-simClaw
-- **Commit:** `2381b2da5139a49f063a6e0a4d907c113771ecab`
-- **Ref:** `[bump] - Bump formula to v1.0.6`
-- **Vendored on:** 2026-04-21
+- **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
 
diff --git a/cli/src/commands/test/ios/simclaw/bin/sim b/cli/src/commands/test/ios/simclaw/bin/sim
index bb1ed6ee..515c2068 100755
--- a/cli/src/commands/test/ios/simclaw/bin/sim
+++ b/cli/src/commands/test/ios/simclaw/bin/sim
@@ -255,7 +255,7 @@ Options:
 
   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, then
+                                          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).
@@ -435,6 +435,10 @@ case "$CMD" in
     source "$SIM_LIB/misc.sh"
     cmd_health_check
     ;;
+  login)
+    source "$SIM_LIB/login.sh"
+    cmd_login "$@"
+    ;;
   ""|--help|-h)
     usage
     exit 0
diff --git a/cli/src/commands/test/ios/simclaw/lib/simclaw/inspect.sh b/cli/src/commands/test/ios/simclaw/lib/simclaw/inspect.sh
index 228b00e6..199cd1ed 100644
--- a/cli/src/commands/test/ios/simclaw/lib/simclaw/inspect.sh
+++ b/cli/src/commands/test/ios/simclaw/lib/simclaw/inspect.sh
@@ -384,13 +384,12 @@ except: pass
 " 2>/dev/null)
   fi
 
-  [[ -n "$element_id" ]] || die "find-element: '$search_label' not found"
+  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)
 
-  # 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 "
+    echo "$rect_resp" | _FIND_LABEL="$search_label" python3 -c "
 import sys, json, os
 data = json.load(sys.stdin)
 r = data.get('value', {})
@@ -401,6 +400,83 @@ 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() {
@@ -505,3 +581,131 @@ SWIFTEOF
   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
index d4feec8c..c809f4c0 100644
--- a/cli/src/commands/test/ios/simclaw/lib/simclaw/layout_map.sh
+++ b/cli/src/commands/test/ios/simclaw/lib/simclaw/layout_map.sh
@@ -3,6 +3,7 @@
 
 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() {
@@ -742,6 +743,163 @@ PYEOF
   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/nav.sh b/cli/src/commands/test/ios/simclaw/lib/simclaw/nav.sh
index 5f281b3d..8eb2f1ba 100644
--- a/cli/src/commands/test/ios/simclaw/lib/simclaw/nav.sh
+++ b/cli/src/commands/test/ios/simclaw/lib/simclaw/nav.sh
@@ -9,8 +9,26 @@ source "$SIM_LIB/wait.sh"
 source "$SIM_LIB/layout_map.sh"
 
 cmd_tap_element() {
-  [[ $# -ge 1 ]] || die "Usage: sim tap-element <label>"
-  local label="$1"
+  # 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).
@@ -32,6 +50,7 @@ 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:
@@ -52,6 +71,12 @@ 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
@@ -93,14 +118,154 @@ else:
 PYEOF
 
   local found
-  found=$(python3 "$tmp_py" "$label" "$SIM_LOGICAL_W" "$SIM_LOGICAL_H" "$tmp_xml" 2>/dev/null) || true
+  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"
 
-  [[ -n "$found" ]] || die "tap-element: '$label' not found in current viewport"
-
   local cx cy
-  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)
+  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)"
diff --git a/cli/src/commands/test/ios/simclaw/lib/simclaw/setup.sh b/cli/src/commands/test/ios/simclaw/lib/simclaw/setup.sh
index eb655b59..10999de8 100644
--- a/cli/src/commands/test/ios/simclaw/lib/simclaw/setup.sh
+++ b/cli/src/commands/test/ios/simclaw/lib/simclaw/setup.sh
@@ -72,7 +72,10 @@ cmd_setup() {
   echo "==> [2/5] Checking WDA build..."
 
   local wda_source="/tmp/WebDriverAgent"
-  local wda_runner="/tmp/WDA_DerivedData/Build/Products/Debug-iphonesimulator/WebDriverAgentRunner-Runner.app"
+  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 ""
@@ -81,25 +84,40 @@ cmd_setup() {
     exit 1
   fi
 
-  if [[ -d "$wda_runner" ]]; then
-    echo "    WDA already built at $wda_runner — skipping build."
+  # 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
-    echo "    Building WDA (this may take a few minutes)..."
+    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 /tmp/WDA_DerivedData \
+      -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 WDA works on
-    # older iOS versions (< 26) where that framework does not exist. Without this
-    # patch, dyld crashes on launch because _LocationEssentials is a hard dependency
-    # introduced when CoreLocation is compiled against the iOS 26+ SDK.
-    _wda_patch_ios_compat "/tmp/WDA_DerivedData/Build/Products"
+    # 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) ──────────────────────────
diff --git a/cli/src/commands/test/ios/simclaw/lib/simclaw/wda.sh b/cli/src/commands/test/ios/simclaw/lib/simclaw/wda.sh
index dd831e14..9a7c6f8d 100644
--- a/cli/src/commands/test/ios/simclaw/lib/simclaw/wda.sh
+++ b/cli/src/commands/test/ios/simclaw/lib/simclaw/wda.sh
@@ -4,6 +4,24 @@
 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
@@ -320,7 +338,7 @@ _wda_patch_ios_compat() {
 # 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. The DerivedData directory must already
+# 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.
 #
@@ -338,9 +356,10 @@ cmd_wda_start() {
   local port="${1:-8100}"
   _bootstrap
 
-  local wda_derived="/tmp/WDA_DerivedData"
+  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 — build WDA first"
+  [[ -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
diff --git a/cli/src/commands/test/ios/simclaw/revendor.sh b/cli/src/commands/test/ios/simclaw/revendor.sh
index 420bfafd..820ee224 100755
--- a/cli/src/commands/test/ios/simclaw/revendor.sh
+++ b/cli/src/commands/test/ios/simclaw/revendor.sh
@@ -2,7 +2,7 @@
 # Re-vendor the simClaw tree from a local checkout of the upstream repo.
 #
 # Usage:
-#   ./revendor.sh <path-to-homebrew-simClaw>
+#   ./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
@@ -11,7 +11,7 @@
 set -euo pipefail
 
 if [[ $# -ne 1 ]]; then
-  echo "Usage: $0 <path-to-homebrew-simClaw>" >&2
+  echo "Usage: $0 <path-to-mv-simclaw-ios>" >&2
   exit 2
 fi
 
@@ -19,7 +19,7 @@ UPSTREAM="$1"
 HERE="$(cd "$(dirname "$0")" && pwd)"
 
 [[ -d "$UPSTREAM/bin" && -d "$UPSTREAM/lib/simclaw" ]] \
-  || { echo "ERROR: $UPSTREAM does not look like homebrew-simClaw (missing bin/ or lib/simclaw/)" >&2; exit 1; }
+  || { 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)