justinthevoid · Oct 9, 2026 · Oct 9, 2026 · Oct 9, 2026 · Oct 9, 2026 · Oct 9, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -14,10 +14,12 @@ swift run xcforge build --help # CLI mode
 ```
 
 **Test timeout defaults** (`build-test`, `test run`, `test_sim`, `build_and_test`):
-- Default timeout: **180s**. Pass `--long` (CLI) or `long: true` (MCP) to use 1800s.
+- Default total limit: **1800s** (`--long` / `long: true`: 7200s). Builds and test runs are also killed
+  after **600s with no output** (`--idle-timeout` / `idleTimeoutSeconds`, 0 disables).
 - Pass `--diagnose` / `diagnose: true` to capture a diagnostic snapshot even on success.
 - On timeout, the result includes a `/tmp/xcf-diag-<pid>-<ts>.txt` path and a summary line.
-- `build_sim` and `build_run_sim` share the same watchdog design; `build` (build-only) remains at 1800s.
+- `build_sim` and `build_run_sim` share the same watchdog design. The watchdog samples at 300s and 540s and
+  only reports a snapshot for a timeout or `diagnose`.
 
 **Formatting** (CI enforces strict lint):
 ```bash
@@ -37,7 +39,7 @@ bun run lint && bun run format            # Biome lint/format
 **Dual-mode single binary**: no args → MCP server (stdio JSON-RPC); with args → CLI (ArgumentParser). Mode detection in `Sources/XCForgeCLI/Main.swift`.
 
 **Two targets** (see `Package.swift`):
-- `XCForgeKit` — shared library containing all 102+ MCP tools
+- `XCForgeKit` — shared library containing all 110+ MCP tools
 - `XCForgeCLI` — CLI layer wrapping the library with ArgumentParser commands
 
 ### Tool Provider System
@@ -73,7 +75,7 @@ MCP tools use snake_case (`build_sim`, `ui_tap`). CLI commands mirror them as su
 2. Register it in `ProviderRegistry`
 3. Add a matching CLI command in `Sources/XCForgeCLI/Commands/`
 4. Add tests in `Tests/XCForgeKitTests/`
-5. Update skill reference in `.claude/skills/xcforge/references/`
+5. Update skill reference in `Skills/xcforge/references/`, then run `python3 scripts/embed-skill.py` so the binary's copy (installed by `xcforge skill install`) matches
 
 ## Dependencies
 

diff --git a/Package.swift b/Package.swift
@@ -5,7 +5,7 @@ let package = Package(
     name: "xcforge",
     platforms: [.macOS(.v13)],
     dependencies: [
-        .package(url: "https://github.com/modelcontextprotocol/swift-sdk.git", from: "0.11.0"),
+        .package(url: "https://github.com/modelcontextprotocol/swift-sdk.git", from: "0.12.0"),
         .package(url: "https://github.com/apple/swift-log.git", from: "1.0.0"),
         .package(url: "https://github.com/apple/swift-argument-parser.git", from: "1.5.0"),
     ],

diff --git a/README.md b/README.md
@@ -12,7 +12,7 @@
 
 An MCP server and CLI for iOS development — build, test, automate, and diagnose from any AI agent or terminal.
 
-**109 MCP tools. 19 CLI command groups. Single native binary (~8 MB stripped, ~18 MB with debug symbols). Zero external runtime dependencies.**
+**104 MCP tools. 19 CLI command groups. Single native binary (~8 MB stripped, ~18 MB with debug symbols). Zero external runtime dependencies.**
 
 ---
 
@@ -191,20 +191,26 @@ File: `~/.config/zed/settings.json` (or `.zed/settings.json` per-project)
 
 ## Claude Code Skill
 
-xcforge includes a Claude Code skill that loads the full tool reference into context when you're working on iOS tasks. Install it globally with:
+xcforge ships an agent skill: the tool reference an agent loads when it works on iOS tasks. The binary carries it, so installing it needs nothing else:
 
 ```bash
-npx skills justinthevoid/xcforge
+xcforge skill install            # this repo: .claude/skills/xcforge (commit it to share with the team)
+xcforge skill install --global   # every project: ~/.claude/skills/xcforge
+xcforge skill install --dir <skills-dir>      # any other agent's skills directory
+xcforge skill status             # where it's installed and whether it matches this xcforge
+xcforge skill show references/test-tools.md   # print one file without installing
 ```
 
+Re-run `xcforge skill install` after upgrading xcforge to refresh the copy; only changed files are rewritten. It won't overwrite an `xcforge` skill directory it didn't create unless you pass `--force`. `xcforge skill uninstall` removes it.
+
 Once installed, Claude will automatically load the right reference files when you use xcforge tools — exact parameters, return values, and usage patterns for each category (build, test, simulator, UI automation, logs, LLDB, diagnosis, and more).
 
 ---
 
 ## Two Modes, Same Tools
 
 ```bash
-xcforge                          # MCP server (stdio JSON-RPC, 109 tools)
+xcforge                          # MCP server (stdio JSON-RPC, 104 tools)
 xcforge build --scheme MyApp     # CLI mode (19 command groups)
 ```
 
@@ -219,7 +225,7 @@ Every tool available over MCP has a matching CLI command. Every CLI command supp
 | **Build**             | 6     | `build_sim`, `build_compile` (fast compile-only), `build_run_sim`, `clean`, project/scheme discovery |
 | **Test**              | 7     | `test_sim` with xcresult parsing, `test_failures`, `test_coverage`, `list_tests`, `test_plan_inspect`, agent output mode, known-failures gating |
 | **Simulator**         | 18    | Full lifecycle + video recording, location simulation, dark mode toggle, status bar override, info |
-| **Physical Devices**  | 7     | Via `devicectl` — list, install, launch, screenshot, pair                                         |
+| **Physical Devices**  | 10    | Via `devicectl` — list, install, launch (deep links, env), screenshot, WebDriverAgent on device   |
 | **UI Automation**     | 20    | WebDriverAgent + native AX bridge — find, tap (point or pixel), swipe, drag, type, alerts        |
 | **Screenshots**       | 3     | Framebuffer capture (0.3s), point-space coordinate alignment, optional grid overlay              |
 | **Visual Regression** | 3     | Pixel-diff baselines, multi-device checks (Dark Mode, Landscape, iPad), `bless` workflow          |
@@ -281,11 +287,11 @@ Use alongside logs and screenshots for systematic root-cause analysis.
 
 ### Diagnosis Workflows
 
-10 tools that chain together into structured diagnostic pipelines — start a session, build, launch, capture runtime signals, collect evidence (screenshots, logs, accessibility state), compare against previous runs, and verify fixes. Designed for agents to systematically debug issues across multiple iterations.
+10 tools (off by default: turn them on with `XCFORGE_TOOL_GROUPS=+diagnose` or `tool_groups`) that chain together into structured diagnostic pipelines — start a session, build, launch, capture runtime signals, collect evidence (screenshots, logs, accessibility state), compare against previous runs, and verify fixes. Designed for agents to systematically debug issues across multiple iterations.
 
 ### Physical Device Support
 
-7 tools wrapping Apple's `devicectl` for real devices — list connected devices, install/launch/terminate apps, take screenshots, and manage pairing.
+Tools wrapping Apple's `devicectl` for real devices: list connected devices, install, launch (with deep links and environment variables) and terminate apps, and take screenshots. `xcforge wda start --device <udid> --team <TEAM>` (MCP `wda_start`) builds, signs and starts WebDriverAgent on the device so the UI automation tools work there too; see [device-tools.md](Skills/xcforge/references/device-tools.md).
 
 ---
 
@@ -334,7 +340,7 @@ There are several iOS-focused MCP servers worth knowing about:
 
 | Server                                                               | Stars | Scope     | Build   | Test | UI Automation | Screenshots | Visual Regression | Accessibility | Physical Devices | SPM | Git | Logs |
 | -------------------------------------------------------------------- | ----- | --------- | ------- | ---- | ------------- | ----------- | ----------------- | ------------- | ---------------- | --- | --- | ---- |
-| **xcforge**                                                          | —     | 109 tools | Yes     | Yes  | Yes           | Yes         | Yes               | Yes           | Yes              | Yes | Yes | Yes  |
+| **xcforge**                                                          | —     | 104 tools | Yes     | Yes  | Yes           | Yes         | Yes               | Yes           | Yes              | Yes | Yes | Yes  |
 | [XcodeBuildMCP](https://github.com/getsentry/XcodeBuildMCP)          | ~5k   | ~15 tools | Yes     | Yes  | Partial       | No          | No                | No            | No               | No  | No  | No   |
 | [ios-simulator-mcp](https://github.com/joshuayoes/ios-simulator-mcp) | ~1.8k | ~10 tools | No      | No   | Yes           | Yes         | No                | No            | No               | No  | No  | No   |
 | [xcode-mcp-server](https://github.com/r-huijts/xcode-mcp-server)     | ~370  | ~8 tools  | Partial | No   | No            | No          | No                | No            | No               | No  | No  | No   |
@@ -394,7 +400,7 @@ Then add `XCFORGE_WDA_DIR` to your MCP config:
 }
 ```
 
-xcforge builds and deploys WDA automatically on the first UI tool call (~30–60s on first run, instant thereafter). See the [full UI Automation Setup guide](https://xcforge.dev/docs/guides/ui-automation-setup) for alternative configurations, custom ports, and troubleshooting.
+xcforge builds and deploys WDA automatically on the first UI tool call on a simulator (~30–60s on first run, instant thereafter). For a physical device run `xcforge wda start --device <udid> --team <TEAM>` (MCP `wda_start`) first, with the device unlocked and Settings > Developer > Enable UI Automation on. See the [full UI Automation Setup guide](https://xcforge.dev/docs/guides/ui-automation-setup) for alternative configurations, custom ports, and troubleshooting.
 
 ---