feat: add install smoke coverage and tarball guidance (#19)

Author: ThomasK33

.github/workflows/ci.yml

@@ -51,6 +51,9 @@ jobs:
       - name: Build
         run: mise run build
 
+      - name: Packaging smoke
+        run: mise run install-smoke
+
   # macOS compilation and static-analysis counterpart to the Ubuntu quality
   # gates above.  Tests are excluded because the macOS GitHub Actions runner
   # has pre-existing issues with PTY spawning and Unix domain sockets that

README.md

@@ -5,20 +5,60 @@ It is built for agent workflows that need both semantic state and visual artifac
 
 ## Installation
 
-### Global installation
+`agent-terminal` currently supports Node `24.x`.
+Released builds install from npm. For prerelease/private use, the guaranteed install path is a built tarball; direct GitHub installs are best-effort and may still fail in some environments.
+
+### npm registry installation
+
+#### Global installation
 
 ```bash
 npm install -g agent-terminal
 agent-terminal version --json
 ```
 
-### Project installation
+#### Project installation
 
 ```bash
 npm install agent-terminal
 ./node_modules/.bin/agent-terminal version --json
 ```
 
+### Direct GitHub installation
+
+```bash
+npm install -g github:coder/agent-terminal
+agent-terminal version --json
+```
+
+GitHub installs attempt to build from source via npm's `prepare` hook.
+Use this when you want the latest default-branch snapshot and your npm/git-dependency environment can build native dependencies cleanly.
+
+Today, the guaranteed prerelease path is still the built tarball route below.
+The repository's install smoke now treats tarball install as the required path and records the current git-install caveat separately, because native dependencies such as `node-pty` can still fail during npm's git-dependency flow in some environments.
+
+If your shell setup injects `mise activate` (or similar trust-checked tooling) into npm lifecycle subprocesses, trust the checkout path first or use the tarball route below.
+
+### Private tarball installation
+
+When you need a deterministic prerelease artifact before the package is published, prefer a built tarball:
+
+```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"/agent-terminal-*.tgz
+"$INSTALL_PREFIX"/bin/agent-terminal version --json
+"$INSTALL_PREFIX"/bin/agent-terminal --home "$(mktemp -d)" doctor --json
+```
+
+`npm run pack:private` always rebuilds `dist/` before packing, so the tarball matches the private artifact reviewers should install.
+Keep the tarball route as the guaranteed private-distribution fallback even when GitHub installs are convenient.
+
+If `doctor --json` reports a missing Playwright browser cache on a fresh machine, run `npx playwright install chromium` once before renderer-backed workflows.
+
 ## Quick start
 
 ```bash
@@ -220,7 +260,7 @@ Useful shortcuts:
 npm run verify
 ```
 
-That runs formatting, linting, typechecking, unit/e2e tests, and the production build.
+That runs formatting, linting, typechecking, unit/e2e tests, the production build, and packaging/install smoke coverage for the required tarball route plus the current git-dependency behavior/caveat check.
 For contributor workflow and release hygiene, see [`docs/CONTRIBUTING.md`](./docs/CONTRIBUTING.md) and [`docs/RELEASE-PROCESS.md`](./docs/RELEASE-PROCESS.md).
 
 ## Design docs

docs/RELEASE-PROCESS.md

@@ -17,6 +17,8 @@ Run the full repo validation command:
 npm run verify
 ```
 
+That command now includes the tarball packaging smoke plus a git-install caveat check, so release candidates exercise the guaranteed private-distribution path and record the current git-dependency behavior before publish.
+
 If the public skill changed, also run:
 
 ```bash

dogfood/CATALOG.md

@@ -5,18 +5,19 @@ Paths below are relative to the repository root.
 
 ## Canonical scenarios
 
-| Scenario         | What it demonstrates                                                             | Bundle                                   |
-| ---------------- | -------------------------------------------------------------------------------- | ---------------------------------------- |
-| Hello prompt     | Basic lifecycle, wait, screenshot, and recording flow                            | `dogfood/20260322-dogfood-hello-prompt/` |
-| Run command      | The higher-level `run` workflow for shell setup and command injection            | `dogfood/run-command/`                   |
-| Color rendering  | ANSI color capture and screenshot review                                         | `dogfood/20260322-dogfood-color/`        |
-| Alternate screen | Entering and leaving an alt-screen TUI while preserving the main screen          | `dogfood/20260322-dogfood-alt-screen/`   |
-| Resize           | PTY resizing and stable-screen verification                                      | `dogfood/20260322-dogfood-resize/`       |
-| Scrollback       | Scrollback-aware snapshots, screenshots, and recording export                    | `dogfood/20260322-dogfood-scrollback/`   |
-| Unicode          | Unicode rendering plus snapshot/export review                                    | `dogfood/20260322-dogfood-unicode/`      |
-| LazyVim          | A real TUI scenario that exercises editor startup and reviewer-visible artifacts | `dogfood/20260322-lazyvim-scenario/`     |
-| Public skill     | The shipped `skills/agent-terminal/` workflow and documentation surface          | `dogfood/20260327-public-skill/`         |
-| Config parity    | Configuration/profile behavior checks that remain useful as a standing scenario  | `dogfood/week5-config-parity/`           |
+| Scenario         | What it demonstrates                                                                | Bundle                                   |
+| ---------------- | ----------------------------------------------------------------------------------- | ---------------------------------------- |
+| Hello prompt     | Basic lifecycle, wait, screenshot, and recording flow                               | `dogfood/20260322-dogfood-hello-prompt/` |
+| Run command      | The higher-level `run` workflow for shell setup and command injection               | `dogfood/run-command/`                   |
+| Color rendering  | ANSI color capture and screenshot review                                            | `dogfood/20260322-dogfood-color/`        |
+| Alternate screen | Entering and leaving an alt-screen TUI while preserving the main screen             | `dogfood/20260322-dogfood-alt-screen/`   |
+| Resize           | PTY resizing and stable-screen verification                                         | `dogfood/20260322-dogfood-resize/`       |
+| Scrollback       | Scrollback-aware snapshots, screenshots, and recording export                       | `dogfood/20260322-dogfood-scrollback/`   |
+| Unicode          | Unicode rendering plus snapshot/export review                                       | `dogfood/20260322-dogfood-unicode/`      |
+| LazyVim          | A real TUI scenario that exercises editor startup and reviewer-visible artifacts    | `dogfood/20260322-lazyvim-scenario/`     |
+| Public skill     | The shipped `skills/agent-terminal/` workflow and documentation surface             | `dogfood/20260327-public-skill/`         |
+| Install flows    | Pre-public tarball install proof plus the current local git-install caveat evidence | `dogfood/install-flows/`                 |
+| Config parity    | Configuration/profile behavior checks that remain useful as a standing scenario     | `dogfood/week5-config-parity/`           |
 
 ## Validation and release gates
 

dogfood/install-flows/README.md

@@ -0,0 +1,32 @@
+# Install flow proof bundle
+
+This bundle captures a 2026-04-07 review pass for the prerelease install paths.
+
+## Environment
+
+- Node runtime used for installed-binary checks: v24.14.0
+- npm used for packaging/install commands: 11.9.0
+- Tarball artifact: /home/coder/.mux/src/agent-terminal/npm-install-5r2j/dogfood/install-flows/tarball-artifact/agent-terminal-0.1.0.tgz
+- Git source revision: 4443b7a66dcf91e9798773abdf363eda746358aa
+- Git source URL: git+file:///tmp/tmp.6ZtZ24ucrQ/src#4443b7a66dcf91e9798773abdf363eda746358aa
+
+## What is included
+
+### Tarball route (`tarball/`)
+
+- `pack.json` records the built package contents.
+- `install.log`, `version.json`, and `doctor.json` capture the successful install + verification outputs.
+- `install.png`, `version.png`, and `doctor.png` are reviewer-facing screenshots.
+- `install-flow.webm` and `install-flow.cast` are the corresponding terminal recordings.
+
+### Git route (`git/`)
+
+- `install.log` captures a representative direct git install attempt from this workspace.
+- `install.png` and `install-flow.webm` render that transcript for review.
+- `blocker.md` documents why this workspace could not produce installed-binary `version --json` / `doctor --json` outputs for the git route.
+
+## Important review note
+
+The tarball route is the fully verified private-distribution path in this bundle.
+The git route evidence is intentionally a blocker transcript rather than a successful install proof: the smoke check now accepts a narrow family of known git-install caveats in environments like this one, while keeping the tarball route as the required passing path.
+That caveat is also reflected in the updated installation docs, which keep the tarball route as the guaranteed fallback.

dogfood/install-flows/commands.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Tarball proof commands used:
+#   MISE_TRUSTED_CONFIG_PATHS="$PWD:/tmp:$HOME/.npm" npx -y npm@11.9.0 run build
+#   MISE_TRUSTED_CONFIG_PATHS="$PWD:/tmp:$HOME/.npm" npx -y npm@11.9.0 pack --json --ignore-scripts --pack-destination dogfood/install-flows/tarball-artifact
+#   MISE_TRUSTED_CONFIG_PATHS="$PWD:/tmp:$HOME/.npm" npx -y npm@11.9.0 install -g --prefix <tarball-prefix> <tarball.tgz>
+#   PATH="$(dirname "/home/coder/.npm/_npx/387698761821791d/node_modules/node/bin/node"):$PATH" <tarball-prefix>/bin/agent-terminal version --json
+#   PATH="$(dirname "/home/coder/.npm/_npx/387698761821791d/node_modules/node/bin/node"):$PATH" <tarball-prefix>/bin/agent-terminal --home <isolated-home> doctor --json
+#   /home/coder/.npm/_npx/387698761821791d/node_modules/node/bin/node --import tsx ./src/cli/main.ts create/run/wait/screenshot/record export ...
+#
+# Git proof commands used:
+#   MISE_TRUSTED_CONFIG_PATHS="$PWD:/tmp:$HOME/.npm" npx -y npm@11.9.0 install -g --prefix <git-prefix> "git+file:///tmp/tmp.6ZtZ24ucrQ/src#4443b7a66dcf91e9798773abdf363eda746358aa"
+#   /home/coder/.npm/_npx/387698761821791d/node_modules/node/bin/node --import tsx ./src/cli/main.ts create/run/wait/screenshot/record export ...
+#
+# See tarball/install-step.sh, tarball/version-step.sh, tarball/doctor-step.sh,
+# and git/install-step.sh for the exact terminal-display commands captured in the screenshots/video.

dogfood/install-flows/git-source-path.txt

@@ -0,0 +1 @@
+/tmp/tmp.6ZtZ24ucrQ/src

dogfood/install-flows/git-source-revision.txt

@@ -0,0 +1 @@
+4443b7a66dcf91e9798773abdf363eda746358aa

dogfood/install-flows/git-source-url.txt

@@ -0,0 +1 @@
+git+file:///tmp/tmp.6ZtZ24ucrQ/src#4443b7a66dcf91e9798773abdf363eda746358aa

dogfood/install-flows/git/agent-terminal-home.txt

@@ -0,0 +1 @@
+/tmp/tmp.vQk7Eo2uSg