Upgrade skill docs with missing commands, options, and engine semantics (#4)

Both skills were missing documentation for session status/close,
node pick, profiler export, and advanced session open options
(--browser, --channel, --device, --storage-state, --user-data-dir,
--headless). Also adds engine selection semantics (auto/custom/devtools)
to runtime-semantics.md and improves skill descriptions for better
triggering accuracy.

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Ring-wdr

skills/react-devtool-cli-repo/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: react-devtool-cli-repo
-description: Maintain and validate the `react-devtool-cli` repository. Use when working inside this repo to change source, run tests, validate `test-app` browser flows, inspect snapshot-aware node commands, verify profiler behavior, confirm package contents, or align runtime field semantics with the bundled repo references.
+description: Maintain and validate the `react-devtool-cli` repository. Use when working inside this repo to change source, run tests, validate `test-app` browser flows, inspect snapshot-aware node commands, use interactive node picking, verify profiler behavior and export workflows, confirm package contents, or align runtime field semantics with the bundled repo references. Also use when debugging test failures, checking engine selection logic, or reviewing session lifecycle implementation.
 ---
 
 # React Devtool CLI Repo
@@ -29,7 +29,8 @@ Use this skill for repository maintenance and validation. Treat the skill bundle
 4. Treat `test-app/` as the default browser-backed validation target.
 5. Run `node bin/rdt.js session doctor --session <name>` before profiler-heavy or helper-heavy validation.
 6. Prefer built-in `interact` commands before ad hoc Playwright helper scripts.
-7. Keep user-owned working tree changes out of commits unless explicitly requested.
+7. Use `session status` to check session health and `session close` to clean up sessions.
+8. Keep user-owned working tree changes out of commits unless explicitly requested.
 
 ## Core Repo Commands
 
@@ -38,6 +39,8 @@ Use this skill for repository maintenance and validation. Treat the skill bundle
 ```bash
 node bin/rdt.js --help
 node bin/rdt.js session doctor --session app
+node bin/rdt.js session status --session app
+node bin/rdt.js session close --session app
 node bin/rdt.js interact wait --session app --ms 250
 ```
 
@@ -54,6 +57,7 @@ npm run dev -- --host 127.0.0.1 --port 3000
 node bin/rdt.js session open --url http://127.0.0.1:3000 --session app --timeout 10000
 ```
 
+- Advanced session open options: `--browser`, `--engine`, `--channel`, `--device`, `--storage-state`, `--user-data-dir`, `--headless=false`.
 - Use `session attach` only when an external Chromium with CDP is already running.
 
 ## Validate Snapshot Workflows
@@ -62,40 +66,46 @@ node bin/rdt.js session open --url http://127.0.0.1:3000 --session app --timeout
 - Persist the returned `snapshotId`.
 - Pass `--snapshot <id>` to `node search`, `node inspect`, `node highlight`, and `source reveal`.
 - If `snapshot-expired` appears, collect a fresh tree and do not reuse old node ids.
+- Use `node pick` for interactive browser-based node selection (30s default timeout).
 
 Example:
 
 ```bash
 node bin/rdt.js tree get --session app
 node bin/rdt.js node search SlowSearchDemo --session app --snapshot <snapshotId>
 node bin/rdt.js node inspect <nodeId> --session app --snapshot <snapshotId>
+node bin/rdt.js node pick --session app --timeout-ms 30000
 ```
 
 ## Validate Profiler Workflows
 
 - Use the profiler against `test-app/`, especially `SlowSearchDemo`, `ResultList`, and `ResultRow`.
 - Treat profiler output as commit-oriented analysis with explicit limitations.
-- Use the newer drill-down commands for commit analysis:
+- Use the drill-down commands for commit analysis:
 
 ```bash
-node bin/rdt.js profiler start --session app
+node bin/rdt.js profiler start --session app [--profile-id <id>]
 node bin/rdt.js profiler stop --session app
 node bin/rdt.js profiler summary --session app
 node bin/rdt.js profiler commits --session app
 node bin/rdt.js profiler commit <commitId> --session app
 node bin/rdt.js profiler ranked <commitId> --session app --limit 10
 node bin/rdt.js profiler flamegraph <commitId> --session app
 node bin/rdt.js profiler compare --session app --left baseline --right candidate
+node bin/rdt.js profiler export --session app [--output file.jsonl] [--compress]
 node bin/rdt.js node inspect <nodeId> --session app --commit <commitId>
 ```
 
 - Read `measurementMode`, `measuresComponentDuration`, `limitations`, and `runtimeWarnings` literally.
 - Treat rerender reasons as snapshot-diff inference, not changed-fiber truth.
 - Treat `node inspect --commit` node ids as commit-local profiler ids, not general tree snapshot ids.
+- `flamegraph` and `export` do not support `--format yaml`.
+- Exported `.jsonl` / `.jsonl.gz` files can be used as inputs to `profiler compare`.
 
 ## Prefer Built-in Interact Commands
 
 - Use `interact click`, `interact type`, `interact press`, and `interact wait` before ad hoc helper scripts.
+- All interact commands accept optional `--timeout-ms <ms>` for element location timeout.
 - Keep selectors deterministic and CSS-based.
 - Use `session doctor` to confirm `supportsBuiltInInteract` before relying on interaction replay.
 

skills/react-devtool-cli-repo/references/repo-workflows.md

@@ -29,6 +29,33 @@ npm run dev -- --host 127.0.0.1 --port 3000
 node bin/rdt.js session open --url http://127.0.0.1:3000 --session app --timeout 10000
 ```
 
+- Advanced session open options:
+  - `--browser chromium|firefox|webkit` — defaults to chromium
+  - `--engine auto|custom|devtools` — defaults to auto
+  - `--channel <name>` — browser channel variant
+  - `--device <name>` — device emulation profile
+  - `--storage-state <path>` — saved browser state
+  - `--user-data-dir <path>` — persistent browser data directory
+  - `--headless=false` — launch with visible browser window
+
+- Use `session attach` only when an external Chromium with CDP is already running.
+
+## Session Management
+
+- Check session state with `session status`:
+
+```bash
+node bin/rdt.js session status --session app
+```
+
+- Close a session when done:
+
+```bash
+node bin/rdt.js session close --session app
+```
+
+Close attempts graceful shutdown first, then force-kills the process tree as fallback.
+
 ## Validation Lanes
 
 ### Snapshot-aware inspection
@@ -38,17 +65,42 @@ node bin/rdt.js session open --url http://127.0.0.1:3000 --session app --timeout
 - Pass `--snapshot <id>` to `node search`, `node inspect`, `node highlight`, and `source reveal`.
 - If `snapshot-expired` appears, collect a fresh tree and rerun lookup commands before trusting node ids.
 
+### Interactive node selection
+
+- Use `node pick` to let the user click a component in the browser:
+
+```bash
+node bin/rdt.js node pick --session app [--timeout-ms 30000]
+```
+
+Default timeout is 30 seconds. Returns the picked node details.
+
 ### Interaction
 
 - Prefer built-in `interact click`, `interact type`, `interact press`, and `interact wait`.
 - Keep selectors deterministic and CSS-based.
 - Run `session doctor` first to confirm `supportsBuiltInInteract`.
+- All interact commands accept optional `--timeout-ms <ms>` for element location timeout.
 
 ### Profiler
 
 - Treat profiler output as commit-oriented analysis, not full DevTools frontend state.
-- Use `profiler start`, `profiler stop`, `profiler summary`, `profiler commits`, `profiler commit`, `profiler ranked`, `profiler flamegraph`, and `profiler compare` for drill-down.
+- Use `profiler start [--profile-id <id>]`, `profiler stop`, `profiler summary`, `profiler commits`, `profiler commit`, `profiler ranked`, `profiler flamegraph`, and `profiler compare` for drill-down.
 - Use `node inspect --commit <commitId>` only with profiler-local node ids from that commit.
+- `flamegraph` does not support `--format yaml`.
+
+### Profiler export
+
+- Export recorded profiler events to NDJSON:
+
+```bash
+node bin/rdt.js profiler export --session app [--output file.jsonl] [--compress]
+```
+
+- `--compress` produces gzip-compressed `.jsonl.gz`.
+- `--output` sets the file path; defaults to `<session>-<profileId>.jsonl` in the current directory.
+- `export` does not support `--format yaml`.
+- Exported files can be used as `--left` or `--right` inputs to `profiler compare`.
 
 ## Publish Checks
 

skills/react-devtool-cli-repo/references/runtime-semantics.md

@@ -6,19 +6,49 @@
 - `react-devtools-core` is a naming and concept reference, not a runtime dependency.
 - `react-debug-tools` is a weak implementation reference in the current repo state.
 
+## Engine Selection
+
+`rdt` supports multiple inspection engines, selected per-session via `--engine`:
+
+| Engine | Behavior |
+|---|---|
+| `auto` (default) | Resolves the best available engine at runtime; prefers custom, falls back to devtools |
+| `custom` | Uses `rdt`'s own snapshot-diff inspection engine for tree collection and reason attribution |
+| `devtools` | Uses the DevTools-aligned hook-based engine that mirrors `react-devtools-core` conventions |
+
+Engine selection affects:
+- **Tree collection**: Each engine maintains its own snapshot store; snapshots from one engine are not interchangeable with another.
+- **Reason attribution**: The custom engine uses snapshot-diff inference; the devtools engine relies on hook-reported change data.
+- **Profiler capabilities**: The devtools engine may report different `measurementMode` and `measuresComponentDuration` values.
+- **Available metadata fields**: Fields like `engineFallback`, `engineReasons`, and `availableEngines` appear in `session doctor` and `session status` output.
+
+### Engine fields in doctor/status output
+
+| Field | Meaning |
+|---|---|
+| `enginePreference` | The engine requested via `--engine` |
+| `selectedEngine` | The engine actually in use after resolution |
+| `availableEngines` | Engines that the runtime supports for this page |
+| `recommendedEngine` | The engine the runtime considers optimal |
+| `engineFallback` | `true` if the selected engine differs from the preference (auto resolved to a specific engine, or a forced engine was unavailable) |
+| `engineReasons` | Human-readable explanation of why the engine was selected |
+
 ## Concept Mapping
 
 | `rdt` concept | Closest DevTools concept | Meaning |
 | --- | --- | --- |
 | Playwright-managed session | Runtime/backend host process | `rdt` owns browser and session lifecycle directly. |
 | `__REACT_DEVTOOLS_GLOBAL_HOOK__` shim | DevTools global hook | Used for renderer and root discovery without adopting the frontend protocol. |
-| `collectTree()` snapshot | Inspected tree payload | `rdt` serializes a CLI-friendly tree snapshot. |
+| `collectTree()` snapshot | Inspected tree payload | `rdt` serializes a CLI-friendly tree snapshot. Engine-specific. |
 | `snapshotId` | No direct public equivalent | CLI-specific stability layer for follow-up commands. |
-| Snapshot-local node id | Inspector element identity | Only valid within the collected snapshot. |
+| Snapshot-local node id | Inspector element identity | Only valid within the collected snapshot and its engine. |
 | `node inspect` payload | Inspected element details | Snapshot-time serialized element details. |
+| `node pick` | Element picker | Interactive browser-based component selection. |
 | Profiler summary/export | Profiler commit data | Commit-oriented summaries and NDJSON export. |
 | `interact` commands | No direct public equivalent | Playwright-backed deterministic interaction helpers. |
 | `session doctor` | No direct public equivalent | CLI-specific readiness and trust-boundary report. |
+| `session status` | No direct public equivalent | Current session state including transport, engine, and runtime info. |
+| `session close` | No direct public equivalent | Graceful shutdown with force-kill fallback. |
 
 ## Interpretation Rules
 
@@ -27,16 +57,21 @@
 - Treat `hooks` and `context` as simplified serialized views.
 - Expect `source` to be `null` in many builds when `_debugSource` is unavailable.
 - Treat rerender reasons as snapshot-diff inference, not changed-fiber truth.
+- Check `selectedEngine` and `engineFallback` before making claims about what the profiler or inspector can observe.
 
 ## Snapshot Rules
 
 - Persist `snapshotId` from `tree get`.
 - Reuse node ids only with the same snapshot.
 - If a requested snapshot expires, recollect the tree before further node lookup.
+- Snapshots are engine-specific: a snapshot collected under the custom engine cannot be used with the devtools engine, and vice versa.
 
 ## Profiler Rules
 
 - `measurementMode`, `measuresComponentDuration`, and `tracksChangedFibers` are capability flags that limit what can be claimed.
 - `nodeCountMeaning` is `live-tree-size-at-commit`.
+- `profiler start` accepts `--profile-id` to assign a custom identifier.
 - `profiler compare` works with in-memory profile ids or exported `.jsonl` / `.jsonl.gz` files.
+- `profiler export` writes NDJSON with optional gzip compression (`--compress`).
 - `node inspect --commit <commitId>` expects profiler-local node ids, not ids from `tree get`.
+- Exported NDJSON includes engine metadata (`engine`, `enginePreference`, `selectedEngine`, `measurementSource`) in the summary record.

skills/react-devtool-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: react-devtool-cli
-description: Operate and troubleshoot the published `rdt` CLI outside the source repo. Use when a user wants help installing `react-devtool-cli`, opening or attaching sessions, collecting tree snapshots, inspecting nodes, running profiler flows, interpreting `session doctor`, comparing custom vs DevTools-aligned engine output, or understanding CLI trust boundaries.
+description: Operate and troubleshoot the published `rdt` CLI outside the source repo. Use when a user wants help installing `react-devtool-cli`, opening or attaching sessions, checking session status, closing sessions, collecting tree snapshots, inspecting or picking nodes, running profiler flows, exporting profiler data, interpreting `session doctor`, comparing custom vs DevTools-aligned engine output, or understanding CLI trust boundaries. Also use when the user mentions React performance debugging, component tree inspection, or Playwright-based React tooling.
 ---
 
 # React Devtool CLI
@@ -9,6 +9,8 @@ description: Operate and troubleshoot the published `rdt` CLI outside the source
 
 Use this skill for installed-CLI workflows used by real end users after distribution. Prefer published `rdt` commands and bundled references; if the task requires changing source code, validating `test-app/`, or editing repository docs, switch to `react-devtool-cli-repo` instead.
 
+Requires Node.js >= 22.
+
 ## Start Here
 
 - Read [references/cli-workflows.md](references/cli-workflows.md) before giving commands or interpreting output.
@@ -26,8 +28,46 @@ Use this skill for installed-CLI workflows used by real end users after distribu
 4. Prefer `--engine auto` unless the user explicitly wants to force `custom` or `devtools`.
 5. Collect a tree with `tree get` and persist `snapshotId`.
 6. Use snapshot-aware node commands with the same `snapshotId`.
-7. Run profiler commands only after a reproducible user interaction is defined.
-8. Prefer `primaryUpdateCommitId` or `recommendedCommitIds` over blindly drilling into `commit-1`.
+7. For interactive selection, use `node pick` to let the user click a component in the browser.
+8. Run profiler commands only after a reproducible user interaction is defined.
+9. Prefer `primaryUpdateCommitId` or `recommendedCommitIds` over blindly drilling into `commit-1`.
+10. Use `profiler export` with `--compress` to save profiler data for later comparison.
+11. Use `session status` to check session health and `session close` to clean up when done.
+
+## Command Reference
+
+### Session
+- `session open` — Launch a local Playwright-managed browser session
+- `session connect` — Connect to a remote Playwright WebSocket endpoint
+- `session attach` — Connect to an existing Chromium CDP target
+- `session status` — Check current session state
+- `session doctor` — Diagnose runtime readiness and trust boundaries
+- `session close` — Gracefully close or force-kill a session
+
+### Inspection
+- `tree get` — Collect a component tree snapshot (returns `snapshotId`)
+- `node search` — Find nodes by display name within a snapshot
+- `node inspect` — Inspect a specific node (supports `--commit` for profiler context)
+- `node highlight` — Highlight a node in the browser
+- `node pick` — Interactively select a node by clicking in the browser
+- `source reveal` — Open the source file for a node in the editor
+
+### Interaction
+- `interact click` — Click a DOM element by CSS selector
+- `interact type` — Type text into an element
+- `interact press` — Press a keyboard key
+- `interact wait` — Wait for a duration
+
+### Profiler
+- `profiler start` — Begin profiling (accepts `--profile-id`)
+- `profiler stop` — Stop the current profiling session
+- `profiler summary` — Get commit count, node ranges, measurement modes
+- `profiler commits` — List all captured commits
+- `profiler commit` — Detailed analysis for a specific commit
+- `profiler ranked` — Ranked component analysis (accepts `--limit`)
+- `profiler flamegraph` — Flamegraph visualization for a commit
+- `profiler compare` — Compare two profiles by id or exported file path
+- `profiler export` — Export profiler events as NDJSON (accepts `--output`, `--compress`)
 
 ## Interpretation Rules