coder · ThomasK33 · Apr 24, 2026 · Apr 24, 2026
diff --git a/README.md b/README.md
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -1,6 +1,6 @@
 # agent-tty roadmap
 
-`RELEASE.md` defines what `0.1.0` ships today. This roadmap tracks intentionally deferred work and post-release direction so the repository front door separates shipped scope from future scope.
+`RELEASE.md` defines what the current `0.1.x` line supports. This roadmap tracks intentionally deferred work and post-release direction so the repository front door separates shipped scope from future scope.
 For historical week-by-week planning and status context, see [`design/archive/`](./design/archive/). For the stable design overview, see [`design/ARCHITECTURE.md`](./design/ARCHITECTURE.md).
 
 ## Near-term refinements

diff --git a/design/ARCHITECTURE.md b/design/ARCHITECTURE.md
@@ -19,9 +19,9 @@ It is designed to let an agent:
 
 This design intentionally describes a **general product**, not a Mux-specific implementation. A future Mux integration should consume `agent-tty` as an external CLI/runtime rather than baking Mux-specific assumptions into the design.
 
-## Current shipped status (2026-03-26)
+## Current shipped status
 
-Update (2026-03-26): Week 9 is now complete as the pre-`0.1.0` release-readiness milestone. The shipped surface now includes the new `run` command for robust in-session command execution, renderer/browser-path handling that respects isolated-home workflows, and isolation-aware `doctor --json` diagnostics on top of the earlier lifecycle, snapshot, screenshot, and export work. With the explicit release contract captured in [`../RELEASE.md`](../RELEASE.md), the repository is ready for `0.1.0` once maintainers are satisfied with the documented proof bundles and release checklist; larger asks such as native renderers, mouse input, remote/network sessions, MCP wrapping, and broader semantic TUI automation remain intentionally deferred.
+The current `0.1.x` line is centered on reliable, isolated, reviewable terminal and TUI automation. The shipped surface includes `run` for robust in-session command execution, renderer/browser-path handling that respects isolated-home workflows, and isolation-aware `doctor --json` diagnostics on top of lifecycle, snapshot, screenshot, and export work. Larger asks such as native renderers, mouse input, remote/network sessions, MCP wrapping, and broader semantic TUI automation remain intentionally deferred and tracked in [`../ROADMAP.md`](../ROADMAP.md).
 
 The repository now ships the first three milestones of this design plus Weeks 4–7 of CLI/artifact/lifecycle hardening, config/rendering/platform closeout, contract/introspection reconciliation, and Week 7 contract/doc ratification:
 
@@ -68,6 +68,8 @@ This shape optimizes for the constraints discussed so far:
 - it avoids committing v1 to one terminal emulator forever,
 - and it preserves a clean path to a later Rust rewrite of hot paths.
 
+The product is inspired by `agent-browser`'s stateful, inspectable automation model, applied to terminal sessions instead of browser pages.
+
 ## Primary goals
 
 ### Product goals
@@ -191,9 +193,8 @@ V1 is successful when an AI agent can:
 5. fetch a semantic snapshot of the screen,
 6. capture a PNG screenshot,
 7. destroy the session,
-8. and leave behind an artifact bundle that a human reviewer can inspect.
-
-Asciicast and replay-video export remain intended follow-on capabilities rather than current success criteria for the shipped slice.
+8. export asciicast or WebM replay artifacts,
+9. and leave behind an artifact bundle that a human reviewer can inspect.
 
 ## Deliverables in this design set
 

diff --git a/docs/AGENT-SKILLS.md b/docs/AGENT-SKILLS.md
@@ -0,0 +1,83 @@
+# Agent Skills
+
+`agent-tty` ships two related skill trees in the npm package and GitHub Release tarball:
+
+- `skills/agent-tty/` is the thin public bootstrap used by TanStack Intent and other skill loaders that discover files directly.
+- `skill-data/` contains canonical runtime skills served by the CLI.
+- `agent-tty skills list` discovers the bundled runtime skills, including `agent-tty` and `dogfood-tui`.
+
+Install `agent-tty` first, then either copy the bootstrap skill into your agent config or let the CLI print the canonical runtime skill on demand.
+
+For coding agents that can ingest instructions on demand:
+
+```bash
+agent-tty skills get agent-tty
+agent-tty skills list
+agent-tty skills get dogfood-tui
+```
+
+`dogfood-tui` is the built-in TUI dogfooding skill for exploratory testing, bug hunting, release-readiness validation, and UX review of terminal applications.
+
+## TanStack Intent
+
+After installing `agent-tty` in the project, let Intent wire the bootstrap from `skills/agent-tty/` into `AGENTS.md`, `CLAUDE.md`, or another supported agent config file.
+
+```bash
+PACKAGE_VERSION=<version>
+npm install "agent-tty@${PACKAGE_VERSION}"
+npx @tanstack/intent@latest list
+npx @tanstack/intent@latest install
+```
+
+That workflow keeps the skill version aligned with the installed `agent-tty` package, while the bootstrap stays small and points agents back to the CLI-served runtime skill.
+
+## Mux
+
+After installing the npm package globally, copy the bootstrap skill from `skills/agent-tty/`:
+
+```bash
+mkdir -p ~/.mux/skills/agent-tty
+cp -R "$(npm root -g)/agent-tty/skills/agent-tty/." ~/.mux/skills/agent-tty/
+```
+
+Mux can then discover the bootstrap normally, and the bootstrap instructs the agent to load the canonical runtime skill with `agent-tty skills get agent-tty`.
+
+## Direct Skill Copy
+
+For loaders that read skill files directly:
+
+```bash
+mkdir -p ~/.claude/skills/agent-tty
+cp -R "$(npm root -g)/agent-tty/skills/agent-tty/." ~/.claude/skills/agent-tty/
+```
+
+If your assistant supports repository-backed skills, point it at `coder/agent-tty` and select the `skills/agent-tty/` bootstrap directory.
+
+## Suggested Agent Config Snippet
+
+```markdown
+## Terminal Automation
+
+Use `agent-tty` for terminal and TUI automation instead of `tmux`, ad hoc PTY wrappers, or external screenshot tools.
+
+Preferred workflow:
+
+1. Create an isolated home and session with `agent-tty --home "$AGENT_HOME" create --json -- /bin/bash`.
+2. Use `agent-tty run` for setup and bootstrap commands.
+3. Use `agent-tty wait` for observable readiness instead of blind sleeps.
+4. Use `agent-tty snapshot` to inspect the current terminal state.
+5. Use `agent-tty screenshot` or `agent-tty record export` for reviewer-facing artifacts.
+6. Destroy the session when the task is done.
+```
+
+Maintainers can validate the shipped bootstrap skill locally with:
+
+```bash
+npm run intent:validate
+```
+
+## Public Example Rule
+
+Keep public skill and public-facing skill docs binary-first.
+Use `agent-tty ...` in committed examples, not repo-local `npx`, `tsx`, or `src/cli/main.ts` invocations.
+When executing those examples from a source checkout, translate them locally.
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -50,6 +50,7 @@ npm run intent:validate
 ## Documentation and proof expectations
 
 - Keep the root docs split clear: `README.md` for overview, `RELEASE.md` for supported scope, `ROADMAP.md` for future scope.
+- Put detailed user-facing instructions in focused docs under `docs/`: `INSTALL.md`, `USAGE.md`, `AGENT-SKILLS.md`, and `TROUBLESHOOTING.md`.
 - Update [`design/README.md`](../design/README.md) when the active vs archived design split changes.
 - Keep the skill split clear in docs and packaging notes: `skills/` contains the thin public bootstrap, while `skill-data/` contains the canonical runtime skills served by `agent-tty skills get`.
 - Update [`dogfood/CATALOG.md`](../dogfood/CATALOG.md) when you add or promote a reviewer-facing proof bundle.

diff --git a/docs/INSTALL.md b/docs/INSTALL.md
@@ -0,0 +1,124 @@
+# Installation
+
+`agent-tty` requires Node `>=24 <26`.
+The recommended install path is the npm package `agent-tty`.
+GitHub Release tarballs are the registry-independent fallback, and direct git dependency installs remain best-effort because they build from source.
+
+After any install, verify the binary and local environment:
+
+```bash
+agent-tty version --json
+agent-tty --home "$(mktemp -d)" doctor --json
+```
+
+If `doctor --json` reports a missing Playwright browser cache on a fresh machine, run:
+
+```bash
+npx playwright install chromium
+```
+
+## npm
+
+### Global install
+
+```bash
+npm install -g agent-tty
+agent-tty version --json
+agent-tty --home "$(mktemp -d)" doctor --json
+```
+
+For automation, pin an exact version:
+
+```bash
+PACKAGE_VERSION=<version>
+npm install -g "agent-tty@${PACKAGE_VERSION}"
+agent-tty version --json
+```
+
+To follow a prerelease channel, use a dist-tag such as `@beta` or `@rc`:
+
+```bash
+npm install -g agent-tty@beta
+```
+
+### Project-local install
+
+```bash
+npm install agent-tty
+./node_modules/.bin/agent-tty version --json
+```
+
+With an exact version:
+
+```bash
+PACKAGE_VERSION=<version>
+npm install "agent-tty@${PACKAGE_VERSION}"
+./node_modules/.bin/agent-tty version --json
+```
+
+## GitHub Release Tarballs
+
+### Direct release asset install
+
+```bash
+VERSION=<version>
+RELEASE_TAG="v${VERSION}"
+RELEASE_TGZ="agent-tty-${VERSION}.tgz"
+TARBALL_URL="https://github.com/coder/agent-tty/releases/download/${RELEASE_TAG}/${RELEASE_TGZ}"
+
+npm install -g "$TARBALL_URL"
+agent-tty version --json
+```
+
+### Authenticated or private release install
+
+```bash
+VERSION=<version>
+RELEASE_TAG="v${VERSION}"
+RELEASE_TGZ="agent-tty-${VERSION}.tgz"
+
+gh release download "$RELEASE_TAG" --repo coder/agent-tty --pattern "$RELEASE_TGZ"
+npm install -g "./$RELEASE_TGZ"
+agent-tty version --json
+agent-tty --home "$(mktemp -d)" doctor --json
+```
+
+### Project-local tarball install
+
+```bash
+VERSION=<version>
+RELEASE_TGZ="./agent-tty-${VERSION}.tgz"
+
+npm install "$RELEASE_TGZ"
+./node_modules/.bin/agent-tty version --json
+```
+
+## Local Tarball From Source
+
+When you need a deterministic local artifact before publishing a GitHub Release, build a tarball from a checkout:
+
+```bash
+TARBALL_DIR=$(mktemp -d)
+npm ci
+npm run pack:private -- --pack-destination "$TARBALL_DIR"
+
+INSTALL_PREFIX=$(mktemp -d)
+npm install -g --prefix "$INSTALL_PREFIX" "$TARBALL_DIR"/*.tgz
+"$INSTALL_PREFIX"/bin/agent-tty version --json
+"$INSTALL_PREFIX"/bin/agent-tty --home "$(mktemp -d)" doctor --json
+```
+
+`npm run pack:private` rebuilds `dist/` before packing.
+Release automation uses `npm run pack:release` after the CI-quality build step so GitHub Releases and npm publishing reuse the same verified tarball plus checksum.
+
+## Git Source Install
+
+```bash
+npm install -g github:coder/agent-tty
+agent-tty version --json
+```
+
+Git installs run npm's `prepare` hook and build from source.
+Use this only when you explicitly want the latest default-branch snapshot and your npm/git-dependency environment can build native dependencies such as `node-pty`.
+
+If your shell setup injects `mise activate` or another trust-checked tool into npm lifecycle subprocesses, trust the checkout path first or prefer the npm package or release tarball route.
diff --git a/docs/README.md b/docs/README.md
@@ -1,12 +1,28 @@
-# Contributor and maintainer docs
+# Documentation
 
-Use this directory when you need project workflow guidance rather than product-facing documentation.
+Use the root [`README.md`](../README.md) as the product-facing front door.
+Use this directory for focused user, contributor, and maintainer guides.
+
+## Users
+
+- [`INSTALL.md`](./INSTALL.md) — npm, release tarball, source tarball, and git install paths.
+- [`USAGE.md`](./USAGE.md) — CLI workflows, command groups, examples, and anti-patterns.
+- [`AGENT-SKILLS.md`](./AGENT-SKILLS.md) — packaged agent skill usage and loader-specific installation notes.
+- [`TROUBLESHOOTING.md`](./TROUBLESHOOTING.md) — environment, Playwright/Chromium, renderer, and platform troubleshooting.
+
+## Product Scope
+
+- [`../RELEASE.md`](../RELEASE.md) — supported product contract for the current release line.
+- [`../ROADMAP.md`](../ROADMAP.md) — intentionally deferred work and post-release direction.
+- [`../CHANGELOG.md`](../CHANGELOG.md) — per-release changes.
+
+## Contributors
 
-- [`../README.md`](../README.md) — product overview and quick start.
-- [`../RELEASE.md`](../RELEASE.md) — supported product contract.
-- [`../ROADMAP.md`](../ROADMAP.md) — deferred work and post-release direction.
-- [`../design/README.md`](../design/README.md) — architecture and design references.
 - [`CONTRIBUTING.md`](./CONTRIBUTING.md) — setup, validation, and day-to-day contribution flow.
+- [`../design/README.md`](../design/README.md) — architecture and design references.
+- [`../dogfood/CATALOG.md`](../dogfood/CATALOG.md) — curated proof bundles and recommended review paths.
+
+## Maintainers
+
 - [`RELEASE-PROCESS.md`](./RELEASE-PROCESS.md) — maintainer release checklist and proof expectations.
 - [`../.agents/skills/release-maintainer/SKILL.md`](../.agents/skills/release-maintainer/SKILL.md) — thin internal agent wrapper around the canonical release process.
-- [`../dogfood/CATALOG.md`](../dogfood/CATALOG.md) — curated proof bundles for review.
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
@@ -0,0 +1,83 @@
+# Troubleshooting
+
+Start with `doctor --json` against the same home you will use for the workflow:
+
+```bash
+AGENT_HOME="$(mktemp -d)"
+agent-tty --home "$AGENT_HOME" doctor --json
+```
+
+The `doctor` command checks runtime, filesystem, PTY, socket, artifact, event-log, Playwright, browser-cache, `ghostty-web`, and screenshot viability.
+
+## Chromium Or Browser Cache Missing
+
+Screenshots and WebM exports require Playwright/Chromium.
+Install Chromium once in the environment:
+
+```bash
+npx playwright install chromium
+```
+
+If your environment uses a custom browser cache, expose it with `PLAYWRIGHT_BROWSERS_PATH` and rerun:
+
+```bash
+PLAYWRIGHT_BROWSERS_PATH=<path> agent-tty --home "$AGENT_HOME" doctor --json
+```
+
+## Renderer-Backed Commands Fail
+
+Affected commands usually include:
+
+- `screenshot`
+- `record export --format webm`
+- renderer-dependent `wait` modes
+- semantic `snapshot` paths that need rendered terminal state
+
+Check `doctor --json` for:
+
+- `playwright_available`
+- `browser_cache_accessible`
+- `browser_launch`
+- `ghostty_web_available`
+- `screenshot_viable`
+
+If these fail in CI or a container, install Chromium during setup and make sure the cache is readable by the process running `agent-tty`.
+
+## Isolated Homes
+
+Use `--home <path>` for automation, tests, CI, and agent workflows:
+
+```bash
+AGENT_HOME="$(mktemp -d)"
+agent-tty --home "$AGENT_HOME" doctor --json
+```
+
+Pass the same `--home` value to every command in the workflow.
+Do not mix `--home` and `AGENT_TTY_HOME` values unless you intentionally want separate session stores.
+
+## Native Dependency Build Failures
+
+`agent-tty` depends on `node-pty`.
+The npm package and release tarball are the preferred install routes because they use packaged artifacts.
+Direct git installs build from source through npm's `prepare` hook and are best-effort.
+
+If a git install fails because native dependencies cannot build, use:
+
+```bash
+npm install -g agent-tty
+```
+
+or install a GitHub Release tarball as described in [`INSTALL.md`](./INSTALL.md).
+
+## Platform Notes
+
+- Linux is tier-1 and CI-tested on `ubuntu-latest`.
+- macOS is tier-1 and CI-tested on `macos-latest`.
+- Windows is tier-2 and not CI-tested. PTY behavior uses ConPTY when available, and rendering or terminal behavior may differ.
+
+## Reference Rendering Caveat
+
+`ghostty-web` is the reference renderer for snapshots, screenshots, and replay video.
+It gives repeatable artifacts for review and automation, but it does not guarantee exact native-terminal pixel parity.
+
+If a bug depends on a specific native terminal emulator, keep the `agent-tty` artifact as reference evidence and capture native-terminal evidence separately when needed.