update wording

Author: thymikee

CONTRIBUTING.md

@@ -5,6 +5,7 @@ Thanks for your interest in contributing to agent-device.
 ## Development
 
 Requirements:
+
 - Node.js 22+
 - pnpm
 - Android SDK tools (`adb`) for Android support
@@ -16,25 +17,35 @@ Setup:
 pnpm install
 ```
 
+Build all CLIs and Xcode projects:
+
+```bash
+pnpm build:all
+```
+
 Run tests:
 
 ```bash
 pnpm test
 ```
 
 Optional device selectors for tests:
+
 - `ANDROID_DEVICE=Pixel_9_Pro_XL` or `ANDROID_SERIAL=emulator-5554`
 - `IOS_DEVICE="iPhone 17 Pro"` or `IOS_UDID=<udid>`
 
 ## Guidelines
+
 - Keep dependencies minimal.
 - Preserve the CLI’s agent-friendly JSON output.
 - Ensure tests open and close sessions explicitly.
 - Add/adjust integration tests when introducing new commands.
 - Prefer built-in Node APIs over new packages.
 
 ## Reporting issues
+
 Please include:
+
 - OS and Node version
 - Xcode/Android SDK versions (if relevant)
 - Exact command and output

website/docs/docs/introduction.md

@@ -24,3 +24,29 @@ If you know `agent-browser`, this is the mobile-native counterpart focused on si
 2. The daemon manages sessions and dispatches to platform drivers.
 3. iOS uses XCTest runner for snapshots and input; AX is optional fallback.
 4. Android uses ADB-based tooling.
+
+## Example
+
+```bash
+# Navigate and get snapshot
+agent-device open Settings --platform ios
+agent-device snapshot -i
+# Output
+# Page: Contacts
+# App: com.apple.MobileAddressBook
+# Snapshot: 44 nodes
+# @e1 [application] "Contacts"
+#  @e2 [window]
+#    @e3 [other]
+#  @e4 [other] "Lists"
+#    @e5 [navigation-bar] "Lists"
+#      @e6 [button] "Lists"
+#      @e7 [text] "Contacts"
+#    @e8 [other] "John Doe"
+
+# Click and fill
+agent-device click @e8
+agent-device snapshot -i
+agent-device fill @e5 "Doe 2"
+agent-device close
+```

website/docs/docs/quick-start.md

@@ -4,15 +4,73 @@ title: Quick Start
 
 # Quick Start
 
+Every device automation follows this pattern:
+
 ```bash
-agent-device open Contacts --platform ios
+# 1. Navigate
+agent-device open SampleApp --platform ios # or android
+
+# 2. Snapshot to get element refs
 agent-device snapshot -i
-agent-device click @e5
-agent-device fill @e6 "John"
+# Output:
+# @e1 [heading] "Sample App"
+# @e2 [button] "Settings"
+
+# 3. Interact using refs
+agent-device click @e2
+
+# 4. Re-snapshot before next interactions
+agent-device snapshot -i
+```
+
+## Common commands
+
+```bash
+agent-device open SampleApp
+agent-device snapshot -i                 # Get interactive elements with refs
+agent-device click @e2                   # Click by ref
+agent-device fill @e3 "test@example.com" # Fill input by ref
+agent-device get text @e1                # Get text content
+agent-device screenshot --out page.png   # Save to specific path
 agent-device close
 ```
 
-Tips:
+## Semantic selectors
+
+Use `find` for human-readable targeting without refs:
+
+```bash
+agent-device find "Sign In" click
+agent-device find label "Email" fill "user@example.com"
+agent-device find role button click
+```
+
+## Scrolling
+
+Navigate content that extends beyond the viewport:
+
+```bash
+agent-device scroll down 0.5            # Scroll down half screen
+agent-device scroll up 0.3              # Scroll up 30%
+```
+
+## Settings helpers
+
+Toggle device settings directly:
+
+```bash
+agent-device settings wifi on
+agent-device settings airplane on
+agent-device settings location off
+```
+
+## JSON output
+
+For programmatic parsing in scripts:
+
+```bash
+agent-device snapshot --json
+agent-device get text @e1 --json
+```
 
-- Re-snapshot after navigation.
-- Use `find` when you want semantic targeting instead of raw refs.
+Note: The default text output is more compact and preferred for AI agents.

website/docs/docs/sessions.md

@@ -9,10 +9,18 @@ Sessions keep device state and snapshots consistent across commands.
 ```bash
 agent-device open Settings --platform ios
 agent-device session list
-agent-device open Contacts --session default
+agent-device open Contacts          # change app while reusing the default session
 agent-device close
 ```
 
+Open another session independently (for parallel work):
+
+```bash
+agent-device open Contacts --platform ios --session my-session
+agent-device snapshot -i
+agent-device close --session my-session
+```
+
 Notes:
 
 - `open <app>` within an existing session switches the active app and updates the session bundle id.

website/docs/docs/snapshots.md

@@ -7,19 +7,41 @@ title: Snapshots
 Snapshots provide a structured view of the UI and generate stable refs.
 
 ```bash
-agent-device snapshot -i
-agent-device snapshot --backend xctest
-agent-device snapshot --backend ax
+agent-device snapshot                    # Full accessibility tree
+agent-device snapshot -i                 # Interactive elements only (recommended)
+agent-device snapshot -c                 # Compact (remove empty elements)
+agent-device snapshot -d 3               # Limit depth to 3 levels
+agent-device snapshot -s "Contacts"      # Scope to label/identifier
+agent-device snapshot -i -c -d 5         # Combine options
 ```
 
-Backends:
+| Option       | Description               |
+| ------------ | ------------------------- |
+| `-i`         | Interactive-only output   |
+| `-c`         | Compact structural noise  |
+| `-d <depth>` | Limit tree depth          |
+| `-s <scope>` | Scope to label/identifier |
+
+Note: If XCTest returns 0 nodes (foreground app changed), agent-device falls back to AX when available.
+
+## Example output:
 
-- `xctest` (default): full fidelity, no Accessibility permission required.
-- `ax`: fast accessibility tree, may miss details.
+```bash
+agent-device snapshot -i
+# Output:
+# Snapshot: 44 nodes
+# @e1 [application] "Contacts"
+#   @e2 [window]
+#     @e3 [other]
+#   @e4 [other] "Lists"
+#     @e5 [navigation-bar] "Lists"
+#       @e6 [button] "Lists"
+#       @e7 [text] "Contacts"
+#     @e8 [other] "John Doe"
+#       @e9 [other] "John Doe"
+```
 
-Tips:
+## Backends (iOS):
 
-- Use `-i` for interactive-only output.
-- Use `-c` to compact structural noise.
-- Use `-d <depth>` to limit depth.
-- If XCTest returns 0 nodes (foreground app changed), agent-device falls back to AX when available.
+- `xctest` (default): full fidelity, fast, no Accessibility permission required.
+- `ax`: fast accessibility tree, may miss details, requires Accessibility permission.

website/rspress.config.ts

@@ -19,6 +19,13 @@ export default withCallstackPreset(
         discord: 'https://discord.gg/eYapw6F3',
       },
     },
+    theme: {
+      content: {
+        outlineCTAHeadline: 'Curious about developing mobile apps with AI agents?',
+        outlineCTADescription: 'We can help you take your agentic workflows to the next level and ship faster.',
+        outlineCTAButtonText: "Book a call",
+      },
+    },
   },
   defineConfig({
     base: process.env.RSPRESS_BASE || '/agent-device',