Document RocketSim 16 agent and device updates

docs/astro.config.ts

@@ -77,7 +77,7 @@ export default defineConfig({
         starlightLlmsTxt({
           projectName: "RocketSim",
           description:
-            "RocketSim enhances the iOS Simulator with features for capturing screenshots and recordings, comparing designs, testing push notifications, deep links, location simulation, network speed control, accessibility toggles, and more.",
+            "RocketSim enhances iOS Simulator and physical-device development with screenshots and recordings, design comparison, agentic development through the RocketSim CLI and Agent Skill, push notification testing, deep links, location simulation, network tools, accessibility workflows, and more.",
           rawContent: true,
         }),
       ],
@@ -150,6 +150,10 @@ export default defineConfig({
           label: "Status Bar",
           link: "/docs/features/capturing/statusbar-appearance",
         },
+        {
+          label: "Physical Devices",
+          link: "/docs/features/capturing/physical-device-support",
+        },
         {
           label: "Design Comparison",
           collapsed: true,

docs/src/content/docs/docs/features/agentic-development/agent-skill.md

@@ -1,67 +1,75 @@
 ---
 title: "Agent Skill"
-description: "Install the RocketSim Agent Skill to give AI coding tools a reliable, version-matched way to inspect and interact with iOS Simulator apps through RocketSim."
+description: "Install RocketSim's bundled Agent Skill so AI coding tools can use the version-matched RocketSim CLI safely and reliably."
 sidebar:
   order: 3
 ---
 
-The RocketSim Agent Skill is the only part you need to install. Once installed, it automatically detects the RocketSim version on your machine, connects your agent to RocketSim's built-in interaction layer, and enables reliable Simulator automation through the RocketSim CLI.
+The RocketSim Agent Skill is the recommended way to connect AI coding tools to RocketSim. It teaches your agent how to use the version-matched `rocketsim` CLI, when to read elements, when to interact, how to recover after screen changes, and when to use a screenshot fallback.
 
-## What you install
+Install it from **RocketSim → Settings → CLI & Agent**.
 
-The RocketSim Agent Skill is a lightweight, installable skill that lives in its own repository:
+## Why the skill is recommended
 
-- [RocketSim-Agent-Skill](https://github.com/AvdLee/RocketSim-Agent-Skill)
+You can run the CLI yourself, but agents perform best when they have clear, tool-specific instructions. The RocketSim Agent Skill provides those instructions without requiring you to copy prompts into every project.
 
-It supports popular AI coding tools like Claude Code, Cursor, and Codex. The easiest way to install is through [skills.sh](https://skills.sh):
+The skill helps agents:
 
-```bash
-npx skills add https://github.com/AvdLee/RocketSim-Agent-Skill --skill rocketsim
-```
+- Use RocketSim's compact `--agent` output before deciding what to do
+- Prefer semantic interactions over fragile coordinate taps when possible
+- Work with RocketSim's `rs/1` agent protocol without needing to know its internals
+- Recover when a screen changes between inspection and interaction
+- Use screenshots when accessibility data is sparse or incomplete
+- Run `rocketsim doctor` when setup needs to be checked
 
-For more installation options, see the [RocketSim-Agent-Skill README](https://github.com/AvdLee/RocketSim-Agent-Skill).
+In our internal research, RocketSim's CLI completed the same agent workflows about **19% faster, avoided wrong taps entirely**, and used about **63% fewer estimated tokens** than a popular alternative.
 
-## What happens after installation
+## Install from RocketSim
 
-When an agent triggers the RocketSim skill, the following happens automatically:
+1. Open **RocketSim → Settings → CLI & Agent**
+2. Install the **Command Line Tool** if `rocketsim` is not on your `PATH` yet
+3. In **Agent Skill**, choose **General Agents**
+4. Click **Install** or **Repair**
+5. Restart or refresh your AI coding tool if it does not discover new skills automatically
 
-1. The skill finds a valid RocketSim installation on your machine
-2. It validates that RocketSim includes the built-in skill and CLI
-3. It hands off to the built-in skill, which contains the version-matched CLI reference
-4. The agent can now inspect visible elements and interact with the Simulator
+RocketSim installs the skill as a symlink to the bundled skill inside `RocketSim.app`. When RocketSim updates, the skill keeps pointing at the latest installed app version.
 
-You do not need to configure anything beyond the initial install. The handoff is seamless.
+![CLI & Agent settings showing Agent Skill installation options](./agent-skill/cli-agent-settings.png)
 
-## Why the built-in skill updates automatically
+## Supported destinations
 
-RocketSim ships a built-in skill alongside its CLI inside the app. Every time RocketSim updates, the built-in skill updates with it. That means the CLI reference your agent uses is always accurate for the RocketSim version you have installed.
+We recommend **General Agents** for most setups. It installs the skill into the shared `.agents/skills` location, so multiple AI coding tools can use the same version-matched RocketSim skill instead of each tool needing its own copy.
 
-This is the key advantage of the two-layer architecture:
+Use a tool-specific destination like **Cursor**, **Claude**, or **Codex** if that tool only scans its own skill folder. You can also choose a custom skill folder if your tool stores skills somewhere else.
 
-- **The public skill** (what you install) stays small, stable, and rarely changes
-- **The built-in skill** (inside RocketSim) stays version-matched and ships with every update
+If RocketSim shows **Repair**, the existing symlink points somewhere unexpected or the app has moved. Repairing updates the symlink to the current RocketSim app.
 
-You get a simple installation experience and version-matched accuracy without maintaining anything yourself.
+## Why it stays up to date
 
-## You only install the public skill
+RocketSim ships the CLI and Agent Skill inside the app bundle. The installed files are symlinks, not copied snapshots. That matters because the CLI surface and skill instructions evolve together.
 
-The built-in skill is not something you install separately. It is part of the RocketSim app and is read automatically by the public skill during handoff.
-
-If you see references to a "bundled skill" or "built-in skill" in other documentation, that is the version-matched layer inside RocketSim that the public skill connects to. You do not need to interact with it directly.
+After an App Store update, your `rocketsim` command and installed skill still resolve to the current app bundle. Agents get the guidance that matches the RocketSim version they are controlling.
 
 ## What the agent can do after setup
 
 Once the skill is installed and RocketSim is running, your agent can:
 
-- Read visible accessibility elements before interacting
+- Read visible accessibility elements, including navigation and tab bar items
 - Tap, long-press, swipe, and type using labels or coordinates
 - Press simulator hardware buttons like Home, Lock, or Siri
 - Navigate multi-step app flows with fewer retries
-- Use compact `--agent` output to spend fewer tokens per screen read
+- Use compact screen summaries to spend fewer tokens per screen read
+- Capture a screenshot when visual context is needed
 
 ## How to verify it works
 
-Open an agent and try:
+First, check your setup:
+
+```bash
+rocketsim doctor
+```
+
+Then open your AI coding tool and try:
 
 > Use RocketSim to navigate through `<your_app_name>` in the Simulator
 
@@ -71,3 +79,4 @@ If the skill is installed and RocketSim is running, the agent should detect Rock
 
 - [RocketSim CLI](/docs/features/agentic-development/rocketsim-cli) -- the commands agents use to inspect and interact with the Simulator
 - [Agentic Development with RocketSim](/docs/features/agentic-development/) -- scenarios, example prompts, and why RocketSim is effective for agent-driven Simulator automation
+- [CLI & Agent settings](/docs/settings/cli-and-agent) -- installing and repairing the CLI and skill

docs/src/content/docs/docs/features/agentic-development/index.md

@@ -1,18 +1,19 @@
 ---
 title: "Agentic Development with RocketSim"
-description: "Let AI coding agents see and interact with your running iOS Simulator app. Automate repetitive flows, validate UI states, and navigate faster without re-describing the screen on every step."
+description: "Let AI coding agents see and interact with your running iOS Simulator app through RocketSim's version-matched CLI and Agent Skill."
 sidebar:
   order: 1
 ---
 
-RocketSim helps AI coding agents see and interact with your running Simulator app. That makes it possible to automate repetitive flows, validate UI states, and move through app navigation faster without re-describing the screen on every step.
+RocketSim helps AI coding agents see and interact with your running Simulator app. The RocketSim Mac app stays connected to the Simulator, keeps useful state warm, and exposes a compact CLI that agents can use to inspect screens, tap controls, type text, and verify UI changes.
 
-With the RocketSim Agent Skill installed and RocketSim running, your agent can:
+With the RocketSim Agent Skill installed from **Settings → CLI & Agent**, your agent can:
 
-- Read visible accessibility elements before deciding what to do
+- Read visible accessibility elements, including common navigation and tab bar items
 - Tap, swipe, type, and navigate through your app reliably
-- Stay in a tight interaction loop without losing context between steps
-- Spend fewer tokens by using RocketSim's compact screen summaries
+- Stay in a tight interaction loop without rebuilding context between steps
+- Use compact screen summaries to spend fewer tokens per UI read
+- Fall back to screenshots when accessibility data is not enough
 
 ## What you can do with it
 
@@ -44,6 +45,8 @@ Try these with any AI coding tool that has the RocketSim Agent Skill installed:
 
 > Use RocketSim to inspect the visible elements on screen and tap the primary CTA
 
+> Use RocketSim to take a screenshot if the accessibility snapshot does not expose the web content clearly
+
 > Use RocketSim to navigate to settings and toggle the feature flag for dark mode
 
 > Use RocketSim to reproduce the crash described in this issue by navigating to the affected screen
@@ -54,31 +57,38 @@ Try these with any AI coding tool that has the RocketSim Agent Skill installed:
 
 ### Stateful by design
 
-RocketSim runs continuously alongside the Simulator. It maintains a live connection, so agents work against the current app state rather than reconnecting from scratch on every command. That keeps interaction loops tight and reduces the amount of context agents need to rebuild between steps.
+RocketSim runs continuously alongside the Simulator. Because there is already a Mac app watching the active device, RocketSim can reuse state, cache expensive work, and optimize repeated agent loops in ways one-off commands cannot. In our internal research, RocketSim's CLI completed the same agent workflows about **19% faster, avoided wrong taps entirely**, and used about **63% fewer estimated tokens** than a popular alternative.
 
 ### Compact screen summaries
 
-RocketSim's `--agent` output format gives agents a focused, token-efficient snapshot of visible elements. Instead of processing a full JSON accessibility tree, agents get a compact pipe-delimited summary with just the element type, label, and coordinates they need to act.
+RocketSim's `--agent` output format gives agents a focused, token-efficient snapshot of visible elements. Instead of processing a full JSON accessibility tree, agents get a compact summary with the element type, label, and coordinates they need to act.
+
+RocketSim also recovers many elements that are easy to miss in raw accessibility output, including top bars, navigation bars, tab bars, and visible controls that are needed to move through an app.
 
 ### Selector-based interaction
 
 Agents can target elements by label, type, or value instead of guessing coordinates. RocketSim uses semantic accessibility activation when possible, which is more reliable than coordinate-only approaches for buttons, toggles, and list rows.
 
+### Agent-optimized protocol
+
+The CLI uses RocketSim's `rs/1` protocol for agent workflows. You do not need to learn the protocol details; the important part is that it is designed for compact, reliable interaction through the running RocketSim app.
+
 ### Version-matched automation
 
-RocketSim ships a built-in skill alongside its CLI. That means the interaction instructions agents receive always match the installed RocketSim version. When RocketSim updates, the built-in skill updates with it automatically.
+RocketSim ships the CLI and Agent Skill inside the app. When RocketSim updates, the installed command and the skill instructions can update with it, so your agent keeps using guidance that matches the RocketSim version you have installed.
 
 ## How it works
 
 RocketSim's agentic development support has three layers:
 
-1. **The RocketSim CLI** lets agents inspect visible elements and perform interactions through a stateful connection to the Simulator.
-2. **The built-in skill** ships inside RocketSim and documents the exact CLI for that installed version, so agents always use version-matched guidance.
-3. **The RocketSim Agent Skill** is the installable entry point that discovers RocketSim on your machine and hands off to the built-in layer automatically.
+1. **The RocketSim Mac app** keeps the live Simulator connection, caches state, and performs the optimized work.
+2. **The RocketSim CLI** exposes that running app to agents through commands such as `elements`, `interact`, `wait`, `screenshot`, and `doctor`.
+3. **The RocketSim Agent Skill** teaches your AI coding tool how to use the CLI safely and consistently.
 
-You only install the public Agent Skill. RocketSim handles the rest.
+Install both the command line tool and Agent Skill from **RocketSim → Settings → CLI & Agent**. RocketSim creates symlinks into your chosen folders, so the CLI and skill keep pointing at the latest installed app.
 
 ## Learn more
 
 - [RocketSim CLI](/docs/features/agentic-development/rocketsim-cli) -- how agents inspect and interact with the Simulator
-- [Agent Skill](/docs/features/agentic-development/agent-skill) -- what to install and how the architecture works
+- [Agent Skill](/docs/features/agentic-development/agent-skill) -- how to install the recommended agent workflow
+- [CLI & Agent settings](/docs/settings/cli-and-agent) -- how to install the CLI and skill from RocketSim