docs: restructure agent-device skill docs

[thymikee]

Summary

Restructure the agent-device skill docs around the decisions an agent makes during a run instead of the old mixed reference buckets.

What changed:

• Turn skills/agent-device/SKILL.md into a thin router with a short default route and one problem-keyed chooser section.
• Keep the detailed docs grouped under skills/agent-device/references/:
  • bootstrap-install.md for target selection, install/relaunch, named sessions, session binding, scoped isolation, TV targets, and startup/security guidance.
  • exploration.md for snapshot, refs, selectors, get, is, wait, find, and fuller batch guidance including payload shape, response fields, and recovery patterns.
  • debugging.md for logs, network, alerts, setup issues, common failure patterns, crash triage, and retained operational log details such as paths, rotation, redaction, and retention knobs.
  • verification.md for screenshots, diff snapshot, recording, replay maintenance, perf checks, and the verification-specific batch recording use case.
  • macos-desktop.md for macOS-only surface differences, raw snapshot guidance, selector guidance, and desktop-specific troubleshooting.
  • remote-tenancy.md for remote daemon transport, tenant admission, lease lifecycle, session-locked RPC examples, and lease tuning knobs.
  • coordinate-system.md for the small raw-coordinate reference that was previously lost.
• Add a short AGENTS.md rule to keep future skill refactors router-first while preserving the references/ folder and high-value operational guidance.

Why:

• The issue asked for a router-first skill that is cheaper to load and easier for weaker agents to follow.
• Keeping the references grouped preserves the repo convention while still giving agents a short default path.
• This version restores the operational details that reviewers flagged as important: session-lock and bound-session flows, scoped isolation, TV targets, batch payload and recovery details, remote lease heartbeat/release and host knobs, log retention/redaction details, coordinate rules, and higher-value troubleshooting guidance.

Touched files: 19. Scope stayed within skills/agent-device and AGENTS.md.

Validation

• No tests run (docs/skills and AGENTS.md changes only)
• pnpm format (fails in this worktree: prettier is not installed because node_modules is missing)

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://callstackincubator.github.io/agent-device/pr-preview/pr-260/
Built to branch gh-pages at 2026-03-25 15:00 UTC. Preview will be ready when the GitHub Pages deployment is complete.