tauri-agent-tools 0.5.1 → 0.7.0

package/.agents/skills/tauri-agent-tools/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: tauri-agent-tools
-description: CLI for inspecting Tauri desktop apps — DOM queries, screenshots, IPC/console monitoring, storage, and page state
-version: 0.5.1
-tags: [tauri, desktop, debugging, screenshot, dom, inspection, diff, mutations, snapshot]
+description: CLI for inspecting and interacting with Tauri desktop apps — DOM queries, screenshots, interaction (click/type/scroll), IPC monitoring, store inspection, structured assertions, plus bridge-free diagnostics (OS logs, app paths, sidecar NDJSON tap/replay, forensic bundles) and the `diagnose` super-command for one-shot triage
+version: 0.7.0
+tags: [tauri, desktop, debugging, screenshot, dom, inspection, diff, mutations, snapshot, interaction, click, type, scroll, invoke, probe, capture, check, store-inspect, forensics, os-logs, app-paths, sidecar, config-inspect, diagnose]
 ---
 
 # tauri-agent-tools
 
-CLI tool for agent-driven inspection of Tauri desktop applications. All commands are **read-only** — no input injection, no writes, no side effects.
+CLI tool for agent-driven inspection and interaction with Tauri desktop applications. Inspection commands are read-only. Interaction commands (click, type, scroll, etc.) are debug-only — they only work when the app runs with the dev bridge enabled.
 
 ## Prerequisites
 
@@ -33,13 +33,40 @@ npm install -g tauri-agent-tools
 Some commands require the Rust dev bridge running inside the Tauri app. Others work standalone.
 
 **Bridge required** (needs running Tauri app with bridge):
-`screenshot --selector`, `dom`, `eval`, `wait --selector`, `wait --eval`, `ipc-monitor`, `console-monitor`, `rust-logs`, `storage`, `page-state`, `mutations`, `snapshot`
+`screenshot --selector`, `dom`, `eval`, `wait --selector`, `wait --eval`, `ipc-monitor`, `console-monitor`, `rust-logs`, `storage`, `page-state`, `mutations`, `snapshot`, `click`, `type`, `scroll`, `focus`, `navigate`, `select`, `invoke`, `capture`, `check`, `store-inspect`, `process-tree` *(v0.7+)*, `capabilities audit` *(v0.7+)*, `webview attach` *(v0.7+)*, `health` *(v0.7+)*
 
 **Standalone** (no bridge needed):
-`screenshot --title` (full window only), `wait --title`, `list-windows`, `info`, `diff`
+`screenshot --title` (full window only), `wait --title`, `list-windows`, `info`, `diff`, `app-paths`, `config inspect`, `os-logs`, `sidecar tap`, `sidecar replay`, `forensics`
+
+**Optional bridge:**
+`probe` (works standalone to discover bridges, richer output with bridge)
 
 The bridge auto-discovers via token files in `/tmp/tauri-dev-bridge-*.token`. No manual port/token configuration needed.
 
+## Don't know where to start? `diagnose`
+
+When something's wrong and you're not sure why, run:
+
+```bash
+tauri-agent-tools diagnose --config ./src-tauri -o ./diagnose-out
+```
+
+`diagnose` is a best-effort super-command. It always runs the bridge-free forensics half; if a dev bridge is reachable it also layers `/process`, `/capabilities`, `/devtools`, `/health` data. The master `summary.md` lists "Next steps" pointing at the right deeper command. See the [`tauri-debug-quickstart`](../tauri-debug-quickstart/SKILL.md) skill for a full symptom-to-command decision tree.
+
+## Debugging decision tree (precision form)
+
+When you know what you're looking at, jump straight to:
+
+| Symptom | First command |
+|---------|---------------|
+| Don't know — give me everything | `tauri-agent-tools diagnose -o ./diag` |
+| App is running and bridge is responding | Use the bridge-mediated commands listed above (`screenshot`, `dom`, `eval`, …) |
+| Bridge isn't responding (release build, app crashed, pre-webview boot failure) | `tauri-agent-tools forensics -o ./forensics-out` |
+| You only have the bundle id, no source tree | `tauri-agent-tools app-paths --identifier com.example.app --platform all --exists` |
+| Need a structured snapshot of `tauri.conf.json` + capabilities | `tauri-agent-tools config inspect --json` |
+| Suspicion: a sidecar process is emitting malformed/unexpected NDJSON | Run the sidecar under `tauri-agent-tools sidecar tap --schema <path> -- <cmd>` instead of under Tauri |
+| OS-level error visible in Console.app/journalctl but not in app logs | `tauri-agent-tools os-logs --identifier com.example.app --level error --duration 30000` |
+
 ## Core Workflows
 
 ### Inspect DOM then screenshot an element
@@ -117,6 +144,60 @@ tauri-agent-tools rust-logs --source sidecar --duration 10000 --json
 tauri-agent-tools rust-logs --source sidecar:ffmpeg --duration 5000 --json
 ```
 
+### Bridge-extended diagnostics (process tree, capabilities, devtools, health — requires bridge v0.7.0+)
+
+Four commands that talk to new endpoints on the dev bridge. Each calls `GET /version` first to feature-detect and emits a clear "requires bridge v0.7.0+ — re-copy dev_bridge.rs" error against older bridges.
+
+```bash
+# Tauri PID + registered sidecars (uses /process)
+tauri-agent-tools process-tree --json
+
+# Devtron-style live capability audit (uses /capabilities)
+tauri-agent-tools capabilities audit --json
+# findings[] flag wildcard "*", over-broad shell:/fs:/http: scopes,
+# capabilities that reference window labels not actually registered, etc.
+
+# Inspector URL or platform hint (uses /devtools)
+tauri-agent-tools webview attach              # human-readable with hint
+tauri-agent-tools webview attach --print-url  # URL alone (empty if none)
+tauri-agent-tools webview attach --open       # launch in default browser
+
+# "Is this app sick" check (uses /health). Exits non-zero on unhealthy.
+tauri-agent-tools health --json
+```
+
+Sidecars only appear in `process-tree` / `health` if integrators register them — either by passing `Some(&registry)` to `dev_bridge::spawn_sidecar_monitored`, or by calling `dev_bridge::register_sidecar` after their own spawn.
+
+### Bridge-free diagnostics (post-mortem & sidecar workflows)
+
+These six commands need no live bridge — useful for release builds, dead apps, and sidecar processes.
+
+```bash
+# Resolve the app's OS data/log/cache/config dirs from tauri.conf.json
+tauri-agent-tools app-paths --config ./src-tauri --json
+# All three platforms (handy for cross-OS forensics)
+tauri-agent-tools app-paths --config ./src-tauri --platform all --exists
+
+# Structured snapshot of the app config + capability/permission audit
+tauri-agent-tools config inspect --config ./src-tauri --json
+# warnings[] flags wildcard "*" perms, fs:allow-all, capabilities referencing
+# plugins not declared in Cargo.toml, sidecars declared without tauri-plugin-shell.
+
+# OS-level log tail, filtered to a Tauri bundle id (NDJSON one-per-line)
+tauri-agent-tools os-logs --identifier com.example.app --duration 5000
+tauri-agent-tools os-logs --level error --source main --duration 30000
+
+# Run a sidecar under a tap to see its stdio + validate against a JSON Schema
+tauri-agent-tools sidecar tap --schema ./schema.json --record /tmp/run.ndjson -- node my-sidecar.js
+# Replay deterministically
+tauri-agent-tools sidecar replay /tmp/run.ndjson --to-exec node my-sidecar.js --rate 100
+
+# One-shot forensic bundle for post-crash analysis. Works on a DEAD app.
+tauri-agent-tools forensics --config ./src-tauri -o ./forensics-out
+# → ./forensics-out/{summary.md,summary.json,project.json,app-log-tail.txt,live-os-log.ndjson}
+# summary.md includes detected panic markers + suggested next commands.
+```
+
 ### Watch DOM mutations
 
 ```bash
@@ -134,13 +215,84 @@ tauri-agent-tools mutations ".sidebar" --attributes --duration 5000
 tauri-agent-tools dom --text "Settings" --first --json
 ```
 
+### Interact with the app
+
+```bash
+# Click a button
+tauri-agent-tools click ".submit-btn" --json
+
+# Type into an input
+tauri-agent-tools type "#search" "hello world" --json
+
+# Clear and retype
+tauri-agent-tools type "#email" "new@email.com" --clear --json
+
+# Scroll to bottom
+tauri-agent-tools scroll --to-bottom --json
+
+# Scroll element into view
+tauri-agent-tools scroll --selector "#item-42" --into-view
+
+# Focus an element
+tauri-agent-tools focus "#username" --json
+
+# Navigate to a route
+tauri-agent-tools navigate "/settings" --json
+
+# Select a dropdown value
+tauri-agent-tools select "#country" "US" --json
+
+# Toggle a checkbox
+tauri-agent-tools select "input[type=checkbox]" --toggle --json
+
+# Invoke a Tauri IPC command
+tauri-agent-tools invoke get_release_context --json
+tauri-agent-tools invoke save_item '{"id": 42}' --json
+```
+
+### Probe, capture, and check (workflow commands)
+
+```bash
+# Discover targets and check bridge health
+tauri-agent-tools probe --json
+
+# Capture a full debug evidence bundle
+tauri-agent-tools capture -o /tmp/debug --json
+# Produces: manifest.json, screenshot.png, dom.json, page-state.json, storage.json, console-errors.json, rust-logs.json
+
+# Run structured assertions
+tauri-agent-tools check --selector ".app-ready" --no-errors --json
+tauri-agent-tools check --eval "document.querySelectorAll('.block').length > 0" --json
+tauri-agent-tools check --text "Workflow loaded" --json
+```
+
+### Inspect reactive stores
+
+```bash
+# Auto-detect framework and list all stores
+tauri-agent-tools store-inspect --json
+
+# Inspect a specific store
+tauri-agent-tools store-inspect --store executionStore --json
+```
+
+### Target specific apps and windows
+
+```bash
+# Target a specific app by PID
+tauri-agent-tools page-state --pid 12345 --json
+
+# Target a specific window in a multi-window app
+tauri-agent-tools eval "document.title" --window-label overlay --json
+```
+
 ## Command Reference
 
 | Command | Key Flags | Bridge? | Description |
 |---------|-----------|---------|-------------|
 | `screenshot` | `--selector <css>`, `--title <regex>`, `-o <path>`, `--max-width <n>` | selector: yes, title: no | Capture window or DOM element screenshot |
 | `dom` | `[selector]`, `--depth <n>`, `--styles`, `--text <pattern>`, `--mode accessibility`, `--json` | yes | Query DOM structure or find elements by text |
-| `eval` | `<js-expression>` | yes | Evaluate JavaScript in webview |
+| `eval` | `<js-expression>`, `--file <path>` | yes | Evaluate JavaScript in webview |
 | `wait` | `--selector <css>`, `--eval <js>`, `--title <regex>`, `--timeout <ms>` | selector/eval: yes | Wait for a condition |
 | `list-windows` | `--tauri`, `--json` | no | List visible windows |
 | `info` | `--title <regex>`, `--json` | no | Window geometry and display info |
@@ -149,14 +301,44 @@ tauri-agent-tools dom --text "Settings" --first --json
 | `rust-logs` | `--level <lvl>`, `--target <regex>`, `--source <src>`, `--duration <ms>`, `--json` | yes | Monitor Rust logs and sidecar output |
 | `storage` | `--type <local\|session\|cookies\|all>`, `--key <name>`, `--json` | yes | Inspect browser storage |
 | `page-state` | `--json` | yes | URL, title, viewport, scroll, document size |
-| `diff` | `<image1> <image2>`, `-o <path>`, `--threshold <pct>`, `--json` | no | Compare two screenshots with difference metrics |
-| `mutations` | `<selector>`, `--attributes`, `--duration <ms>`, `--json` | yes | Watch DOM mutations on a CSS selector |
-| `snapshot` | `-o <prefix>`, `-s <css>`, `--dom-depth <n>`, `--eval <js>`, `--json` | yes | Capture screenshot + DOM + page state + storage in one shot |
+| `diff` | `<image1> <image2>`, `-o <path>`, `--threshold <pct>`, `--json` | no | Compare two screenshots |
+| `mutations` | `<selector>`, `--attributes`, `--duration <ms>`, `--json` | yes | Watch DOM mutations |
+| `snapshot` | `-o <prefix>`, `-s <css>`, `--dom-depth <n>`, `--eval <js>`, `--json` | yes | Screenshot + DOM + page state + storage |
+| `click` | `<selector>`, `--double`, `--right`, `--wait <ms>`, `--json` | yes | Click a DOM element |
+| `type` | `<selector> <text>`, `--clear`, `--json` | yes | Type text into an input |
+| `scroll` | `--selector <css>`, `--by <px>`, `--to-top`, `--to-bottom`, `--into-view`, `--json` | yes | Scroll window or element |
+| `focus` | `<selector>`, `--json` | yes | Focus a DOM element |
+| `navigate` | `<target>`, `--json` | yes | Navigate within the app |
+| `select` | `<selector> [value]`, `--toggle`, `--json` | yes | Select dropdown or toggle checkbox |
+| `invoke` | `<command> [args-json]`, `--json` | yes | Invoke a Tauri IPC command |
+| `probe` | `--pid <n>`, `--json` | optional | Discover targets and bridge health |
+| `capture` | `-o <dir>`, `-s <css>`, `--logs-duration <ms>`, `--json` | yes | Full debug evidence bundle |
+| `check` | `--selector`, `--text`, `--eval`, `--no-errors`, `--json` | yes | Structured assertions (exit 0/1) |
+| `store-inspect` | `--framework`, `--store <name>`, `--depth <n>`, `--json` | yes | Inspect reactive store state |
+| `app-paths` | `--config <path>`, `--identifier <id>`, `--platform <os>`, `--exists`, `--json` | no | Resolve Tauri 2 app's OS data/log/cache/config dirs |
+| `config inspect` | `--config <path>`, `--capabilities-dir <path>`, `--cargo-toml <path>`, `--json` | no | Structured `tauri.conf.json` snapshot + capability audit |
+| `os-logs` | `--identifier <id>`, `--level <lvl>`, `--source <src>`, `--since <dur>`, `--duration <ms>`, `--json` | no | Tail host OS log stream filtered to a Tauri bundle id |
+| `sidecar tap` | `-- <cmd...>`, `--schema <path>`, `--record <path>`, `--raw`, `--json` | no | Wrap-and-run a sidecar, frame NDJSON, validate envelopes |
+| `sidecar replay` | `<file>`, `--to-exec <cmd>`, `--rate <lps>`, `--loop` | no | Replay a recorded NDJSON sidecar stream |
+| `forensics` | `--config <path>`, `--identifier <id>`, `-o <dir>`, `--since <dur>`, `--json` | no | One-shot forensic bundle (works on dead apps) |
+| `process-tree` | `--json` | yes (v0.7+) | Tauri PID + registered sidecars with alive/DEAD status |
+| `capabilities audit` | `--json` | yes (v0.7+) | Live Devtron-style audit of declared Tauri capabilities |
+| `webview attach` | `--print-url`, `--open`, `--json` | yes (v0.7+) | Print webview inspector URL or platform hint |
+| `health` | `--json` | yes (v0.7+) | Uptime + webview/sidecar liveness (exit non-zero if unhealthy) |
+| `diagnose` | `--config <path>`, `-o <dir>`, `--since <dur>`, `--no-bridge`, `--json` | optional | Best-effort super-bundle (forensics + live bridge enrichment) |
+
+## Targeting Flags
+
+All bridge-dependent commands support these flags:
+- `--port <n>` / `--token <s>` — explicit bridge config (skips auto-discovery)
+- `--pid <n>` — target a specific app by PID
+- `--window-label <label>` — target a specific webview window (default: main)
 
 ## Important Notes
 
-- **All read-only.** No commands modify app state, inject input, or write to storage.
+- **Inspection commands are read-only.** They don't modify app state.
+- **Interaction commands are debug-only.** They only work with the dev bridge (debug builds).
 - **Use `--json`** for structured, parseable output in automation.
-- **Always use `--duration`** with `ipc-monitor`, `console-monitor`, `rust-logs`, and `mutations` — without it, they run indefinitely.
+- **Always use `--duration`** with `ipc-monitor`, `console-monitor`, `rust-logs`, and `mutations`.
 - **`screenshot --selector`** requires both the bridge AND platform screenshot tools (`imagemagick`).
-- **One bridge at a time.** Auto-discovery picks the first token file found. If multiple Tauri apps run simultaneously, use `--port` and `--token` explicitly.
+- **Multi-app targeting:** Use `--pid` to target a specific app. Use `probe` to discover all running bridges.

package/.agents/skills/tauri-bridge-setup/SKILL.md

@@ -1,16 +1,35 @@
 ---
 name: tauri-bridge-setup
 description: How to add the tauri-agent-tools Rust dev bridge to a Tauri application
-version: 0.4.0
-tags: [tauri, rust, bridge, setup, integration]
+version: 0.7.0
+tags: [tauri, rust, bridge, setup, integration, multi-window, process-tree, capabilities, devtools, health]
 ---
 
 # Tauri Dev Bridge Setup
 
-Add the dev bridge to a Tauri app so `tauri-agent-tools` can inspect DOM, evaluate JS, monitor IPC, and take element screenshots.
+Add the dev bridge to a Tauri app so `tauri-agent-tools` can inspect DOM, evaluate JS, monitor IPC, take element screenshots, and interact with the UI. Bridge v0.7 also exposes process tree, capability audit, devtools URL, and health endpoints.
 
 The bridge runs **only in debug builds** and is stripped from release builds automatically.
 
+## Re-copying for v0.7
+
+> **Upgrading from v0.6:** The bridge surface grew with four new endpoints (`/process`, `/capabilities`, `/devtools`, `/health`) and `start_bridge` now returns a third tuple element (the sidecar registry). **Re-copy `dev_bridge.rs` from the latest `examples/tauri-bridge/src/dev_bridge.rs`** and adjust your `main.rs` to destructure the new return shape (see Step 3 below). The CLI's new commands (`process-tree`, `capabilities audit`, `webview attach`, `health`) feature-detect via `GET /version` and emit a clear "requires v0.7.0+" error when the bridge is older — so partial upgrades fail loudly rather than silently.
+
+## Bridge Endpoints
+
+The bridge exposes eight HTTP endpoints on a random localhost port:
+
+| Endpoint | Method | Auth | Purpose |
+|----------|--------|------|---------|
+| `/eval` | POST | token | Evaluate JS in a webview (supports `window` param for multi-window) |
+| `/logs` | POST | token | Drain Rust tracing logs and sidecar output |
+| `/describe` | POST | token | Report PID, window labels, and capabilities |
+| `/version` | GET | none | Bridge version and available endpoints (used for feature detection) |
+| `/process` | POST | token | Tauri PID + registered sidecars (powers `process-tree`) — **v0.7+** |
+| `/capabilities` | POST | token | Declared Tauri capability set + live window labels (powers `capabilities audit`) — **v0.7+** |
+| `/devtools` | POST | token | Webview inspector URL or platform hint (powers `webview attach`) — **v0.7+** |
+| `/health` | POST | token | Uptime + webview readiness + sidecar liveness (powers `health`) — **v0.7+** |
+
 ## Step 1 — Add Cargo dependencies
 
 Add to your Tauri app's `src-tauri/Cargo.toml` under `[dependencies]`:
@@ -24,8 +43,13 @@ rand = "0.8"
 uuid = { version = "1", features = ["v4"] }
 tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["registry"] }
+
+[target.'cfg(unix)'.dependencies]
+libc = "0.2"
 ```
 
+(`libc` is used for the cheap `kill(pid, 0)` aliveness probe powering `/process` and `/health` sidecar reporting. Windows is supported but skips the liveness check in v0.7.)
+
 ## Step 2 — Copy the bridge module
 
 Copy `dev_bridge.rs` from the tauri-agent-tools package into your project:
@@ -63,6 +87,9 @@ fn main() {
     builder
         .setup(|app| {
             if cfg!(debug_assertions) {
+                // start_bridge returns (port, LogBuffer, SidecarRegistry).
+                // Hold onto the registry if you plan to spawn sidecars; otherwise
+                // the bound `let _` keeps it alive for the app's lifetime.
                 if let Err(e) = dev_bridge::start_bridge(app.handle()).map(|_| ()) {
                     eprintln!("Warning: Failed to start dev bridge: {e}");
                 }
@@ -91,34 +118,71 @@ If you already have a `.setup()` call, add the `if cfg!(debug_assertions) { ...
 Build and run the Tauri app in dev mode, then:
 
 ```bash
-# Should show your app with a bridge indicator
-tauri-agent-tools list-windows --tauri
+# Discover the bridge and check health
+tauri-agent-tools probe --json
 
 # Should return DOM tree
 tauri-agent-tools dom --depth 2
 ```
 
-Both commands succeeding confirms the bridge is working.
+Both commands succeeding confirms the bridge is working. The `probe` output shows bridge version, available endpoints, window labels, and PID.
+
+## Multi-Window Apps
+
+The bridge supports evaluating JS in any named webview window. The `/eval` endpoint accepts an optional `window` field (defaults to `"main"`). The `/describe` endpoint reports all registered window labels.
+
+From the CLI, use `--window-label` to target a specific window:
+
+```bash
+# Eval in a secondary window
+tauri-agent-tools eval "document.title" --window-label overlay --json
+
+# Screenshot a specific window's element
+tauri-agent-tools screenshot --selector ".content" --window-label settings -o /tmp/settings.png
+```
+
+Use `probe` to discover available windows:
+
+```bash
+tauri-agent-tools probe --json
+# → { "bridges": [{ "windows": ["main", "overlay", "settings"], ... }] }
+```
 
-## Optional: Sidecar Log Capture
+## Optional: Sidecar Log Capture + Process Visibility
 
-To capture stdout/stderr from sidecar processes (external binaries), use `spawn_sidecar_monitored()`:
+To capture stdout/stderr from sidecar processes (external binaries) AND have them show up in `process-tree`/`health`, use `spawn_sidecar_monitored()` and pass the registry returned by `start_bridge`:
 
 ```rust
 if cfg!(debug_assertions) {
-    let (_port, log_buffer) = dev_bridge::start_bridge(app.handle())?;
+    let (_port, log_buffer, sidecar_registry) = dev_bridge::start_bridge(app.handle())?;
 
-    // Spawn a sidecar with monitored output
+    // Spawn a sidecar with monitored output AND registry tracking
     dev_bridge::spawn_sidecar_monitored(
-        "ffmpeg",           // name (appears as source: "sidecar:ffmpeg")
-        "ffmpeg",           // command
-        &["-i", "input.mp4", "-f", "null", "-"],  // args
+        "ffmpeg",                                     // name (source: "sidecar:ffmpeg")
+        "ffmpeg",                                     // command
+        &["-i", "input.mp4", "-f", "null", "-"],      // args
         &log_buffer,
+        Some(&sidecar_registry),                      // register for /process + /health
     )?;
 }
 ```
 
-Then monitor with: `tauri-agent-tools rust-logs --source sidecar --duration 10000`
+Pass `None` for the registry argument to opt out of process tracking (useful for ephemeral one-shot helpers).
+
+If you spawn children with your own mechanism, register them after the fact so they appear in `process-tree`:
+
+```rust
+let child = my_own_spawn(...)?;
+dev_bridge::register_sidecar(
+    &sidecar_registry,
+    "my-helper",
+    child.id(),
+    Some("/path/to/binary".to_string()),
+    vec!["--mode=watch".to_string()],
+);
+```
+
+Then monitor with: `tauri-agent-tools rust-logs --source sidecar --duration 10000`, view the tree with `tauri-agent-tools process-tree`, and check liveness with `tauri-agent-tools health`.
 
 ## Troubleshooting
 
@@ -134,3 +198,7 @@ Then monitor with: `tauri-agent-tools rust-logs --source sidecar --duration 1000
 **Port conflicts:**
 - The bridge picks a random port. If it fails, check the app's stderr for "Failed to start dev bridge".
 - Ensure no firewall blocks localhost connections.
+
+**Multi-window eval fails:**
+- Verify the window label matches exactly (case-sensitive). Use `probe --json` to list available labels.
+- The default label is `"main"` — omit `--window-label` to target it.

package/.agents/skills/tauri-debug-quickstart/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: tauri-debug-quickstart
+description: First-30-seconds triage for a broken Tauri desktop app. Pick the right command for the symptom you're seeing, with one-line escalations to deeper skills.
+version: 0.7.0
+tags: [tauri, debugging, triage, quickstart, decision-tree, forensics, diagnose]
+---
+
+# Tauri Debug Quickstart
+
+When something is wrong with a Tauri app, the first 30 seconds matter — they decide whether you spend the next hour reading the right logs or the wrong ones. This skill points you at the right `tauri-agent-tools` command for the symptom you're seeing.
+
+## The single-command answer
+
+If you don't know where to start, run this first:
+
+```bash
+tauri-agent-tools diagnose --config ./src-tauri -o ./diagnose-out
+```
+
+`diagnose` is a best-effort super-command that:
+
+1. Resolves the app's config + OS data/log paths
+2. Runs a forensics bundle (works even on dead apps — tails app logs for panics, pulls macOS DiagnosticReports, lists app-data files)
+3. If a live dev bridge is reachable, layers `/process`, `/capabilities`, `/devtools`, `/health` data on top
+4. Writes a master `summary.md` with detected anomalies and suggested next steps
+
+Then open `./diagnose-out/summary.md` and follow the "Next steps" section.
+
+## Symptom → command (when you need precision)
+
+Pick the row that matches what's broken. Each command works without the bridge unless noted.
+
+| Symptom | First command | Why |
+|---|---|---|
+| Don't know what's wrong | `tauri-agent-tools diagnose -o ./diag` | Everything-bundle; graceful on dead apps |
+| App crashed at startup | `tauri-agent-tools forensics --config ./src-tauri -o ./forensics` | Reads app log + DiagnosticReports without needing a live process |
+| App is running but bridge isn't responding | `tauri-agent-tools probe` | Detects whether the bridge process is up and shows token-file state |
+| App is running, bridge is up, but webview looks wrong | `tauri-agent-tools health --json` *(needs bridge v0.7+)* | Returns webview_ready + sidecar liveness in one call |
+| A sidecar process is the suspect | `tauri-agent-tools sidecar tap --schema ./schema.json -- <cmd>` | Wrap-and-run the sidecar standalone; frame NDJSON; validate envelopes |
+| Need to know exactly which files the app touches | `tauri-agent-tools app-paths --config ./src-tauri --exists` | Resolves Tauri 2's per-platform `app_data_dir`/`app_log_dir`/etc. + checks existence |
+| Need to audit Tauri capabilities for over-broad permissions | `tauri-agent-tools config inspect --config ./src-tauri` (static) **or** `tauri-agent-tools capabilities audit` (live, needs bridge v0.7+) | Flags `*`, `fs:allow-all`, `shell:allow-spawn`, etc. |
+| OS-level error visible in Console.app or journalctl | `tauri-agent-tools os-logs --identifier com.example.app --level error --duration 30000` | Filters platform log stream to the Tauri bundle id |
+| Inspector / webview attach | `tauri-agent-tools webview attach` *(needs bridge v0.7+)* | Returns inspector URL or platform-specific hint |
+| What sidecars did this app spawn? | `tauri-agent-tools process-tree --json` *(needs bridge v0.7+)* | Tauri PID + registered sidecars with alive/dead per-PID |
+
+## Decision tree
+
+```
+The app is...
+│
+├── crashed / not running ────────► forensics
+│   └─ no source on hand? ────────► forensics --identifier com.foo.bar
+│
+├── running but bridge down ──────► probe → fix bridge → retry
+│
+└── running, bridge up
+    ├── webview misbehaving ──────► health → snapshot → capabilities audit
+    ├── sidecar suspected ────────► sidecar tap (run sidecar under it standalone)
+    ├── IPC slow / wrong ─────────► ipc-monitor → check
+    └── DOM / UI inspection ──────► dom → screenshot → eval
+```
+
+When in doubt, escalate to `diagnose` — its `summary.md` will tell you which deeper command to use.
+
+## Output conventions
+
+- All commands accept `--json` for machine-readable output.
+- Bundle commands (`forensics`, `diagnose`) write a `summary.md` agents can open directly and a `summary.json` agents can parse.
+- Streaming commands (`os-logs`, `rust-logs`, `sidecar tap`) emit one NDJSON envelope per line on stdout.
+- Bridge v0.7+ commands feature-detect via `GET /version` and emit a clear "re-copy dev_bridge.rs" error against older bridges.
+
+## When this skill is wrong
+
+This guidance assumes the agent is inspecting a Tauri 2 desktop app on macOS or Linux. Caveats:
+
+- **Tauri 1 apps** — the `dirs`/`directories-next` path semantics that `app-paths` encodes match Tauri 2's `PathResolver`. Tauri 1's paths differ; some derived paths will be slightly off.
+- **Windows** — `os-logs` is stubbed in v0.7 (the Windows event log adapter is planned). `forensics` and `diagnose` still produce useful bundles on Windows; they just skip the live OS-log tail.
+- **The dev bridge requires `cfg!(debug_assertions)`** — release builds strip it, so bridge-dependent commands won't work against signed/notarized release artifacts. Use bridge-free commands (`forensics`, `app-paths`, `os-logs`, `config inspect`, `sidecar tap`) for those.
+
+For deeper how-tos see the [`tauri-agent-tools`](../tauri-agent-tools/SKILL.md) skill. For bridge integration setup (Rust side), see [`tauri-bridge-setup`](../tauri-bridge-setup/SKILL.md).

package/AGENTS.md

@@ -1,6 +1,6 @@
 # tauri-agent-tools
 
-CLI tool for agent-driven inspection of Tauri desktop applications. **Not an MCP server** — invoke commands directly via shell.
+CLI tool for agent-driven inspection and interaction with Tauri desktop applications. **Not an MCP server** — invoke commands directly via shell.
 
 ## Agent Skills
 
@@ -8,23 +8,25 @@ This package includes two [Agent Skills](https://agentskills.io):
 
 | Skill | Path | Purpose |
 |-------|------|---------|
-| `tauri-agent-tools` | `.agents/skills/tauri-agent-tools/SKILL.md` | Using the 14 CLI commands to inspect Tauri apps |
+| `tauri-agent-tools` | `.agents/skills/tauri-agent-tools/SKILL.md` | Using all 25 CLI commands to inspect and interact with Tauri apps |
 | `tauri-bridge-setup` | `.agents/skills/tauri-bridge-setup/SKILL.md` | Adding the Rust dev bridge to a Tauri project |
 
 ## Quick Reference
 
 **Install:** `npm install -g tauri-agent-tools`
 
-**All commands are read-only.** No input injection, no writes, no side effects.
+**Inspection commands are read-only.** Interaction commands (click, type, scroll, etc.) are debug-only — they only work with the dev bridge.
 
 **Standalone commands** (no bridge needed):
-`list-windows`, `info`, `screenshot --title`, `wait --title`
+`list-windows`, `info`, `screenshot --title`, `wait --title`, `diff`
 
 **Bridge-required commands** (Tauri app must have dev bridge running):
-`dom`, `eval`, `screenshot --selector`, `wait --selector/--eval`, `ipc-monitor`, `console-monitor`, `rust-logs`, `storage`, `page-state`, `mutations`, `snapshot`
+`dom`, `eval`, `screenshot --selector`, `wait --selector/--eval`, `ipc-monitor`, `console-monitor`, `rust-logs`, `storage`, `page-state`, `mutations`, `snapshot`, `click`, `type`, `scroll`, `focus`, `navigate`, `select`, `invoke`, `capture`, `check`, `store-inspect`
 
-**Local-only commands** (no bridge needed):
-`diff`
+**Optional bridge:**
+`probe` (works standalone to discover bridges, richer output with bridge)
+
+**Multi-app targeting:** Use `--pid <n>` to target a specific app. Use `--window-label <label>` for multi-window apps.
 
 **Bridge auto-discovery:** The CLI finds the running bridge via token files in `/tmp/tauri-dev-bridge-*.token`. No manual configuration needed.