bottleship 0.1.0-prototype.1 → 0.1.0-prototype.2

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 Add a section on top with a new version to release it: pushing it to main publishes that version to npm.
 Prerelease versions like `0.1.0-prototype.1` go to the dist-tag named after them (`prototype`), plain versions to `latest`.
 
+## 0.1.0-prototype.2
+
+- `bottleship review <pr>` brings a PR up in a box, with its base and head running side by side. An agent there builds a guided tour that opens in your browser: an overview, chapters that show the change in the running app, and the diff in tour order. Your comments go into your pending review on GitHub, and you submit it from the tour with a summary and a verdict. The Pull request page shows the checks and merges when you are allowed to.
+- `bottleship review` with no PR does the same for your checkout's local changes, and leaves the checkout untouched.
+- The tour has a chat with an agent. It knows the page you are on and takes selections, comments and screenshots as context. In a PR review the box agent answers, and commits fixes to the PR's branch when you ask. In a review of local changes your own agent answers, changes your checkout, and the tour updates.
+- `bottleship init` also sets up the repo you run it in: your local agent works out how the repo runs in a box and writes `.bottleship/`, checking its work in real boxes. On a machine that is already set up, it goes straight to the repo.
+- `bottleship box list` shows the boxes on this machine with their reviews, and `bottleship box rm` removes one.
+- Breaking: the commands for coding agents moved under `bottleship agent`: `new`, `status`, `ask`, `exec` and `rm`, plus the new `list`, `review`, `review next` and `onboard`. `bottleship agent help` is their reference. To update your agent, replace the "## Remote agents with bottleship" section in its instructions file with the one in the README.
+- Providers can have a `list` script, which `box list` uses. The builtin `docker` provider has one.
+
 ## 0.1.0-prototype.1
 
 - The last step of `bottleship init` opens your local agent (Claude Code, Codex, opencode or Cursor) to add bottleship to its global instructions, instead of showing text to copy.

package/README.md

@@ -1,138 +1,92 @@
 # bottleship (prototype)
 
-A small CLI your local coding agent uses to run other coding agents in remote sandboxes ("boxes"), like subagents. Your agent writes the prompt, starts a box, checks on it, follows up, and cleans up. The agent in the box clones the repo, works, commits, pushes, and opens a PR.
+Review a pull request by watching it run. `bottleship review 17` starts the PR in a box, an isolated dev environment with base and head running side by side. An agent there builds a guided tour that opens in your browser: what the PR does, shown in the running app, then the diff in tour order. You comment, chat with the agent, and submit your review to GitHub from the tour.
 
-bottleship is stateless: no daemon, no local task list. The box id is the handle, and everything about a run lives in the box.
+The same boxes let your coding agent hand work to other agents, like subagents that each have their own copy of the app.
 
-This README is written for agents. Humans: run `bottleship init` once, then tell your agent to read this file.
+## Quick start
 
-## Install
-
-```sh
-npm install -g <path or git URL of this package>   # will be `npm i -g bottleship` once published
-```
-
-Needs Node >= 22.18 on this machine. Installing from a git URL or a checkout builds the TypeScript sources (`npm install` runs `npm run build`).
-
-## Onboarding
-
-Once per machine, in a terminal:
+You need Node 22.18 or newer, Docker, and the GitHub CLI logged in (`gh auth login`).
 
 ```sh
+npm install -g bottleship@prototype
+cd your-repo
 bottleship init
+bottleship review 17
 ```
 
-It asks where boxes run (provider), which agent runs in them (`claude`, `codex`, `opencode`, `cursor`), how that agent logs in, and the git name and email for their commits, then collects the secrets boxes need and runs a live check: create a box, run a command, set up the agent, get one reply, destroy the box. Re-running it re-checks everything and only asks for what is missing.
+`bottleship init` asks a few questions, checks that a box can run an agent, then has your local coding agent set up the repo with you. The first box builds the base image, which takes a few minutes.
 
-An agent can run it non-interactively; it never prompts and prints JSON:
+## Commands
 
 ```sh
-bottleship init --yes --provider docker --agent claude --git-name "Ada Lovelace" --git-email ada@example.com
+bottleship init [--reset]          # set up this machine, then the repo you are in
+bottleship review [<pr>]           # review a PR, or this checkout's changes without a PR
+bottleship review --base <ref>     # review the changes against another base
+bottleship box list                # the boxes on this machine, with their reviews
+bottleship box rm [<id>]           # remove a box; without an id, pick one
+bottleship help
 ```
 
-`--provider ssh` also needs `--host <host>`; `--provider custom --name <name>` sets up a custom provider (see below). `local` and `ssh` run agents with no isolation, so init needs the user's explicit OK: a confirm in the terminal, or `--i-understand-no-isolation`. Only pass that flag when the user said so.
-
-For an agent on the device login route (codex by default), the live check stops at the login with `login_needs_human`, since someone has to approve it in a browser. Ask the user to run `bottleship init` in their terminal.
-
-At the end, init opens the user's own agent on this machine (Claude Code, Codex, opencode or Cursor, whichever is installed) with a prompt to add the instructions below to its global instructions (for Cursor, a user rule file `~/.cursor/rules/bottleship.mdc`; Cursor documents that folder, not whether its CLI reads it), so the user only approves the change. With `--yes`, the JSON's `next` asks the calling agent to add `instructions` to its own global instructions file and show the user the change.
-
-Rerunning `bottleship init` only asks what is missing. `bottleship init --reset` starts over: it sets `~/.bottleship/config.json` aside as `config.json.bak` and asks everything again; on a terminal it also offers to forget the saved logins. With `--yes` it never deletes saved logins.
-
-If a secret is missing it fails with `secret_missing`. Then ask the user to run `bottleship init` in their own terminal, where it asks with a hidden prompt. Never ask the user to paste a secret to you.
-
-### Secrets
-
-Box env vars are configured under `env` in `~/.bottleship/config.json` (and per agent). A value is a plain string or a secret source:
-
-| Source | Meaning |
-|---|---|
-| `{ "store": "claude" }` | bottleship's store: macOS Keychain, or a 0600 file under `~/.bottleship/secrets` |
-| `{ "command": "gh auth token" }` | the output of a command on this machine |
-| `{ "env": "CORP_KEY" }` | an environment variable of the bottleship process |
+A PR is a number in the current repo, `owner/name#17`, or a link to the PR.
 
-Defaults: `GH_TOKEN` (git pushes and `gh` both use it) from the store, plus the agent's login (below). Init asks for a [fine-grained personal access token](https://github.com/settings/personal-access-tokens/new) limited to the repos boxes work on, with Contents and Pull requests read and write (Metadata read comes with them), so a box cannot touch the rest of the account. `gh auth token` (every repo the user can reach) is used only if the user picks it in init and confirms a warning. Either way, turn on branch protection for `main` so a box can only reach it through a reviewed PR.
+Your coding agent has its own commands under `bottleship agent`. See [For your coding agent](#for-your-coding-agent).
 
-### Agent logins
+## Reviewing a PR
 
-Each agent preset lists the login routes it offers (`login.routes`) and the one boxes use (`login.use`). Init asks on a first pick; pick another for one agent in `~/.bottleship/config.json`, e.g. `"agents": { "codex": { "login": { "use": "token" } } }`.
+`bottleship review 17` reads the PR from GitHub, starts a box, opens the review in your browser, and shows progress in the terminal until the tour is ready. Ctrl-C stops watching, and the review keeps going.
 
-- `token`: a long-lived token or API key in bottleship's store, set as an env var in every box.
-- `device`: the agent logs in inside each box. `new` (and `ask`, if the box's login expired) starts the login and returns its URL and code for the user to approve in a browser; the task starts once they do. Nothing is stored on this machine.
-- `none`: no login.
+The tour has four parts, in the rail on the left:
 
-| Agent | Routes (default first) | Why |
-|---|---|---|
-| `claude` | token: `CLAUDE_CODE_OAUTH_TOKEN` from `claude setup-token` | Anthropic's documented way to use a Claude subscription headless ([docs](https://code.claude.com/docs/en/authentication)). Boxes never get `ANTHROPIC_API_KEY` unless you configure it, as it would win over the token. |
-| `codex` | device: `codex login --device-auth` per box; token: `CODEX_API_KEY` (an OpenAI API key) | One ChatGPT login (`auth.json`) must not be shared across machines or parallel runs ([docs](https://learn.chatgpt.com/docs/auth/ci-cd-auth)), so each box logs in itself. Once, first: in ChatGPT, Settings, Security, turn on device code login for Codex. |
-| `cursor` (no reply tested yet) | token: `CURSOR_API_KEY` from https://cursor.com/dashboard/api (bills to your Cursor plan); device: `cursor-agent login` per box | API keys are Cursor's documented headless login ([docs](https://cursor.com/docs/cli/reference/authentication)). |
-| `opencode` | none: free models; device: a ChatGPT plan via `opencode auth login openai --method chatgpt-headless` per box; token: `OPENCODE_API_KEY` (OpenCode Zen), `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` | Per-box logins and provider API keys ([docs](https://opencode.ai/docs/)). Never a Claude subscription: Anthropic allows those only in Claude Code. |
-
-On `new`, the `.env*` files at the root of the current repo (not `*.example`, `*.sample`, `*.template`) are copied into the box workspace at the same paths.
+- **Overview.** What the PR does in one sentence, before and after, where it happens, and what deserves a close look. Every claim in the description, comments and reviews is checked in the box.
+- **Chapters.** The change in the running app. Each chapter says what should happen on base and on head, runs a step, and shows the evidence: live instances, screenshots side by side, and flows traced through the code.
+- **Changes.** The diff grouped by chapter, each group with why it exists, then the files no chapter covers.
+- **Finish review** and **Pull request.** Your comments, a summary and a verdict, then the PR's checks and a merge button when you are allowed to merge.
 
-Real tokens are in the box, so the agent there can do anything those tokens allow: keep them narrow (a fine-grained `GH_TOKEN`, branch protection on `main`). A credential proxy that keeps them out of boxes is not built yet.
+Comments work as on GitHub, and land there as you write them. Press the + next to a line, or drag over several lines, to comment or suggest a change. Add single comment posts at once. Start a review puts the comment in your pending review, which you submit from Finish review.
 
-## Providers
+The Agent button in the footer opens a chat with the agent in the box. It knows the page you are on, and takes what you select, any comment, and any screenshot as context. It answers questions, and commits fixes to the PR's branch when you ask. It leaves comments on GitHub only when you ask, and only in your pending review.
 
-Where boxes run. Pick one with `bottleship init` (or `--provider <name>`, and `new --provider <name>` per box):
+Only review PRs you trust. The box runs the PR's code with your GitHub token, so code in the PR could push, comment or approve as you, in every repo the token reaches.
 
-- `docker`: containers on this machine, from the box template (see Templates); without one, from `image` (default exeuntu).
-- `exe`: [exe.dev](https://exe.dev) VMs over ssh; needs `ssh exe.dev` working. No box template: exe.dev boots VMs only from registry images, so boxes install the agent at start.
-- `e2b` (untested): [e2b.dev](https://e2b.dev) cloud sandboxes; API key from https://e2b.dev/dashboard.
-- `daytona` (untested): [daytona.io](https://daytona.io) cloud sandboxes; API key from https://app.daytona.io/dashboard/keys.
-- `modal` (untested): [modal.com](https://modal.com) cloud sandboxes; token id and secret from `modal token new` or https://modal.com/settings/tokens.
-- `ssh` (untested on a real host): any machine you can `ssh` into without a password prompt; each box is a directory `~/bottleship-boxes/<id>` there, used as its `$HOME`. No isolation: agents run as that user with permission prompts off. Options: `host` (required, anything ssh accepts, e.g. a `~/.ssh/config` alias; `init --host`), `root`.
-- `local`: git worktrees on this machine. The box workspace is a `git worktree` of your local repo on branch `bottleship/<id>` (from your `HEAD` commit, without uncommitted changes); `rm` removes the worktree and keeps the branch. No isolation: agents run as you, with your files and logins, with permission prompts off. Boxes stop when the laptop sleeps.
-- `custom`: your company's sandboxes, see below.
+## Reviewing local changes
 
-`local` and `ssh` need the user's OK in `bottleship init` (stored as `acceptNoIsolation` on the provider); without it `new` refuses them. `rm` there kills the box's processes: those marked with the box (`BOTTLESHIP_BOX`), and on macOS those in the box's process groups whose working directory is in the box.
+Run `bottleship review` without a PR to review your checkout's changes: commits, uncommitted and untracked files, against where your branch left the default branch. The box gets a copy, and your checkout stays as it is. `.env` files never go into the diff.
 
-Provider API keys are read on this machine only and never reach a box; `bottleship init` asks for them.
+Your coding agent starts these reviews too, after a big change it made. Then the chat in the tour goes to that agent: it changes your checkout, the box picks up the new state, and the tour updates. When you press Looks good, your agent does what your note says.
 
-"Untested" means built from the provider's docs and SDK and type-checked, with live tests in `test/live/` that run when the provider's keys are set, but never run against the real service yet.
+## Boxes
 
-## Custom providers
+A box is a Docker container by default. Each one has the repo, its dependencies and services, and the app running. `bottleship box list` shows every box with its age and, for reviews, the review link. Boxes stay until you remove them with `bottleship box rm`.
 
-For a company sandbox system with only an API or a CLI. A human runs `bottleship init` and picks `custom` (an agent: `bottleship init --yes --provider custom --name <name>`). That copies [presets/providers/http.example.ts](presets/providers/http.example.ts) to `~/.bottleship/providers/<name>.ts` and adds `"<name>": { "module": "providers/<name>.ts" }` under `providers` in `~/.bottleship/config.json`. Then, as the agent:
+## Setting up a repo
 
-1. Replace every TODO in `~/.bottleship/providers/<name>.ts` with the real API calls, or, if the system has a CLI, run its commands with `kit.run`. Find out how the system creates a sandbox, runs a command in it, and deletes it (its docs, its CLI's `--help`, or ask the user).
-2. Put the module's options in its config entry, with secrets as secret sources, never as plain values:
+A repo describes its box in `.bottleship/`, committed with the repo. `bottleship init` in the repo has your coding agent write it with you and check it in real boxes.
 
-```json
-"providers": {
-  "corp": { "module": "providers/corp.ts", "baseUrl": "https://sandboxes.corp.example/api", "apiKey": { "store": "corp-sandbox" } }
-}
-```
+| File | What it does |
+|---|---|
+| `.bottleship/Dockerfile` | Optional. Lines added to bottleship's base image (Debian bookworm, Node 22, git, gh, curl, ripgrep, a user `box` without sudo), run as root. No `FROM`, `COPY` or `ADD`. `EXPOSE <port>` marks the ports to open; bottleship publishes them on 127.0.0.1 and waits for them. |
+| `.bottleship/setup.sh` | Runs once as `box` in `~/workspace`: dependencies, databases, seed data, build. Must not prompt. |
+| `.bottleship/start.sh` | Starts the services, then the app in the foreground. It must listen on 0.0.0.0. The log is in `~/.bottleship/app.log`. |
 
-3. Ask the user to run `bottleship init` in their terminal. It asks for missing secrets with a hidden prompt, then checks the provider end to end: create a box, run a command, set up the agent, get one reply, destroy the box. Fix what fails and run it again.
+Boxes also get the `.env` files at the root of your checkout, but not `.env.example` and the like. The image is built once per Dockerfile and reused after that.
 
-The contract is `Provider` in [src/types.ts](src/types.ts): `create` (resolves once the box can run commands), `exec` (one-shot `bash -c`, with stdin), `destroy`, and optionally `status`, `openStream` (a binary-clean long-lived exec, for `exec -i`) and `template` (build or find a box template from a `TemplateSpec`, see Templates; `create` then gets its reference). Boxes must stay up until `rm`, since the agent runs in the background between calls. Node runs the `.ts` module directly, no build step. For a system whose CLI fits in shell templates, `"module": "builtin:command"` needs no code, see [presets/providers/command.ts](presets/providers/command.ts).
+## Configuration
 
-## Usage
+`bottleship init` writes `~/.bottleship/config.json`. Run it again to fill in anything missing, or with `--reset` to start over. The old config is kept as `config.json.bak`.
 
-Every command prints JSON; errors are `{ "error", "message", "fix" }` with exit code 1.
+### Agents
 
-```sh
-bottleship new "<task>" [--repo owner/name | --no-repo] [--provider P] [--agent A]
-# { "id": "docker:bs-fix-login-bug-3fa2", "provider": "docker", "agent": "claude", "repo": "acme/web", "next": "..." }
-# device login route: { "id", "provider", "agent", "repo", "login": { "url", "code"?, "agent" }, "next": "show the user this URL and code; ..." }
-
-bottleship status <id> [--wait 600] [--lines 40]
-# { "id", "box": "running", "agent": "running" | "exited" | "stopped", "exitCode"?, "log": "<last lines>", "next" }
-# { "id", "box": "running", "agent": "waiting_for_login", "login": { "url", "code"?, "agent" }, "log", "next" }
-# { "id", "box": "running", "agent": "login_failed", "exitCode", "log": "<the login's output>", "next" }
-# { "id", "box": "gone", "next" }
-
-bottleship ask <id> "<follow-up>"       # continues the same conversation; refused while the agent runs
-# { "id", "agent": "running", "next" }, or with an expired device login { "id", "agent": "waiting_for_login", "login", "next" }
-bottleship exec <id> -- git log --oneline -5
-bottleship exec <id> -- "npm test 2>&1 | tail -20"   # one argument is a script, several are argv
-bottleship exec -i <id> -- <cmd>        # streams stdin/stdout, e.g. for an IDE attaching over ACP
-bottleship rm <id>
-```
+The agent in a box is `claude`, `codex`, `cursor` or `opencode`. Each gets one long-lived login, which init asks for:
 
-`new` returns as soon as the agent has started, or, on the device route, once the login shows its URL: show the user the URL and code, and the task starts after they approve. A login nobody approves within 15 minutes fails (`login_failed`); `ask` then logs in again and, if the task never ran, runs the message as the task. The repo defaults to the current directory's `origin` (with the `local` provider, a worktree of this checkout). The box gets the env, the agent's login, the git identity, a git credential helper that uses `$GH_TOKEN`, and the agent's install commands; then the agent runs detached in `~/workspace` with your prompt.
+| Agent | Env var | Where it comes from |
+|---|---|---|
+| `claude` | `CLAUDE_CODE_OAUTH_TOKEN` | `claude setup-token`, to use a Claude subscription headless ([docs](https://code.claude.com/docs/en/authentication)). Boxes never get `ANTHROPIC_API_KEY` unless you configure it, since it would win over the token. |
+| `codex` | `CODEX_API_KEY` | an OpenAI API key, billed to the API, not a ChatGPT plan |
+| `cursor` | `CURSOR_API_KEY` | an API key from https://cursor.com/dashboard/api, billed to your Cursor plan |
+| `opencode` | `OPENCODE_API_KEY` | an OpenCode Zen key from https://opencode.ai/console |
 
-Agents are configured as shell templates (`{prompt}` is filled in shell-quoted):
+An agent is a set of shell templates. The presets are in [presets/agents](presets/agents), and an entry under `agents` in the config overrides only the fields it names:
 
 ```json
 "agents": {
@@ -142,47 +96,94 @@ Agents are configured as shell templates (`{prompt}` is filled in shell-quoted):
     "resume": "claude -p {prompt} --continue --dangerously-skip-permissions",
     "env": { "IS_SANDBOX": "1" },
     "unset": ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"],
-    "login": { "routes": ["token"], "use": "token", "token": { "env": "CLAUDE_CODE_OAUTH_TOKEN", "store": "claude", "command": "claude setup-token" } }
+    "login": { "env": "CLAUDE_CODE_OAUTH_TOKEN", "store": "claude", "command": "claude setup-token" }
   }
 }
 ```
 
-`unset` drops env vars from the box unless you configure them. A device login is `"device": { "command", "status", "setup"?, "timeout"? }`: `command` prints a URL (and code) and exits 0 once approved, `status` exits 0 when the box is logged in. An entry for a builtin agent only needs the fields it changes. The presets are in [presets/agents](presets/agents).
+### Secrets and tokens
 
-If a box has no Node, bottleship installs it into `~/.bottleship/node` without sudo.
+Boxes get `GH_TOKEN`, which git and gh both use, and the agent's login. Other env vars go under `env` in the config, as a plain string or one of these sources:
 
-## Templates
+| Source | Meaning |
+|---|---|
+| `{ "store": "claude" }` | bottleship's store: the macOS Keychain, or a 0600 file under `~/.bottleship/secrets` |
+| `{ "command": "gh auth token" }` | the output of a command on this machine |
+| `{ "env": "CORP_KEY" }` | an environment variable of the bottleship process |
 
-Boxes start from a prebuilt template when the provider supports one (`docker` builds a local image, `e2b` a template, `daytona` a snapshot, `modal` a named image; `exe`, `local`, `ssh` and custom ones have none). `bottleship init` builds it in the live check ("build the box template", minutes the first time) and records it under `templates.<provider>` in `~/.bottleship/config.json` as `{ "name", "ref" }`.
+Init asks for a [fine-grained personal access token](https://github.com/settings/personal-access-tokens/new) limited to the repos boxes work on, with Contents and Pull requests set to read and write. Your full gh login (`gh auth token`) is used only if you pick it and confirm a warning. Either way, protect `main` so a box reaches it only through a reviewed PR.
 
-The template is one Dockerfile: `node:22-bookworm-slim` with git, curl, ca-certificates, gh and ripgrep, a non-root user `box` (uid 1000, home `/home/box`) whose npm globals go to `~/.bottleship/npm`, plus the configured agent's `install` commands run as `box`. Its name is `bottleship-<hash of the Dockerfile>`, so changing the agent, its install commands or bottleship's Dockerfile makes a new one, built on the next `init`; a rerun with no changes finds the existing one. Templates never hold secrets or logins; those go into each box at start.
+The agent in a box can do anything its tokens allow, so keep them narrow. A box that only runs the repo's scripts, such as a setup check, gets no secrets. A proxy that keeps tokens out of boxes is not built yet.
 
-Only the configured agent is baked in. `new --agent <other>` still uses the template and installs the other agent at start. When the recorded template does not match the current config, `new` starts the box without one (setup installs what it lacks, only slower) and says so in `warning`; run `bottleship init` to rebuild. Providers without `template()` (`local`, `ssh`, custom ones) set boxes up at start as before.
+## Providers
 
-## Instructions for your agent
+A provider decides where boxes run. It is a directory of bash scripts. `docker` ships in [presets/providers/docker](presets/providers/docker). For anything else, such as a company's sandboxes, a cloud sandbox service or a VM over ssh, put the same scripts in `~/.bottleship/providers/<name>/` and pick it in `bottleship init`. A provider there with a builtin's name replaces the builtin.
 
-`bottleship init` prints this block; add it to your agent's global instructions (e.g. `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`).
+| Script | Contract |
+|---|---|
+| `create <id> <dockerfile> <image>` | Build the box from the Dockerfile, cached as `<image>`, which changes whenever the Dockerfile does. Start it with every `EXPOSE`d port reachable from this machine, and exit 0 once it runs commands. The box stays up until `destroy`. |
+| `exec <id> <script>` | Run `bash -c <script>` in the box as its non-root user, with `$HOME` its home. Pass stdin, stdout, stderr and the exit code through, binary-clean and streaming. |
+| `status <id>` | Print `running` or `gone`. |
+| `destroy <id>` | Remove the box and everything it runs. |
+| `url <id> <port>` | Optional. Print a URL on this machine for a port the box exposes. |
+| `list` | Optional. Print the boxes bottleship made, one per line: the id, then optionally a space and the creation time in ISO 8601. Without it, `box list` shows none of this provider's boxes. |
+
+The scripts run on this machine with bottleship's environment. They read the credentials they need themselves, from an env var, the keychain or a CLI's own login, and never hardcode them.
+
+## For your coding agent
+
+`bottleship init` adds this section to your agent's global instructions, such as `~/.claude/CLAUDE.md` or `~/.codex/AGENTS.md`. If you skipped that step, add it yourself:
 
 ```md
 ## Remote agents with bottleship
 
-You can run other coding agents in remote sandboxes ("boxes") with the `bottleship` CLI, like subagents. Every command prints JSON; errors carry a `fix`.
+The `bottleship` CLI runs coding agents in boxes, isolated dev environments for a repo (Docker containers by default), and builds guided reviews of PRs and of local changes, which the user opens in their browser. Your commands are under `bottleship agent`; run `bottleship agent help` before you first use them in a session, for what each does and how to use it.
 
-- Start remote work with `bottleship new "<prompt>"` from inside the repo (or `--repo owner/name`). Write a complete prompt: the task, the context it needs, and what done means, including "work on branch <name>, commit and push as you go, and open a PR when done". The box agent sees nothing of this conversation.
-- Treat each box as a subagent you manage. `new` returns an id; keep track of your ids yourself, bottleship keeps no list.
-- If `new` or `ask` returns a `login`, show the user its URL and code; the box agent starts once they approve it in their browser.
-- `bottleship status <id>` shows whether the agent is still running and the tail of its output; `--wait <seconds>` blocks until it finishes.
-- `bottleship ask <id> "<follow-up>"` continues the same conversation once the agent has finished.
-- `bottleship exec <id> -- <cmd>` inspects the box (git log, test output, files).
-- `bottleship rm <id>` when the work is merged or abandoned. If a box is gone, start a new one on the pushed branch.
-- If the user wants to watch or steer a box from their IDE, find out how their IDE attaches to an agent over a command (ACP) and give it `bottleship exec -i <id> -- <the agent's ACP command>`.
+- Use a box for work that can run on its own while you do something else, and treat it as a subagent you manage.
+- When the user wants to review a PR, start the review for them and give them its url.
+- Reviews of your own work: after a big change you made on your own (many files, or behaviour that is hard to see in the diff), start a local review before you hand over and give the user its url, unless the user has said otherwise. Skip it for small changes.
+- If the user stops or interrupts you while you start a review, or turns one down, ask them once when they want reviews (after every big change, only when they ask, never, or something else). Then rewrite the line above in this section of your instructions file to say exactly what they chose, and follow it from then on.
 - Secrets: never ask the user to paste a secret to you. If bottleship reports one missing, ask them to run `bottleship init` in their terminal.
 ```
 
+`bottleship agent help` is the full reference for agents. Each command prints JSON, errors are `{ "error", "message", "fix" }` with exit code 1, and most results say in `next` what to do next. In short:
+
+- `agent new`, `status`, `ask`, `exec`, `list` and `rm` run another agent in a box and manage it.
+- `agent review` starts a review and returns its link. For local changes, `agent review next` waits for what you send from the tour's chat and sends back the agent's updates.
+- `agent onboard` gives the instructions for setting up a repo, and `agent onboard --check` tries them in a box.
+- `agent init --yes` sets up the machine without prompts.
+
+## How a review works
+
+These details are for working on bottleship or on a tour.
+
+In a review box, `~/workspace` is the PR's head and `~/base` is the commit it branched off. The box environment is the PR's `.bottleship/` if it has one, otherwise your local checkout's, otherwise none and the agent works it out.
+
+The review server listens on port 7777 from the start, so the link works at once and shows that the review is being set up. Ports 7781 to 7784 are free for extra instances, such as base. The server keeps the review's state in the box: `~/review/comments.json`, `verdict.json` and `updates.json`.
+
+`~/review/app` is a copy of [review-app](review-app), a Vite and React app with the PR's data in `src/data`. The agent writes `src/review.tsx`, step scripts in `~/review/steps/<id>.sh`, and screenshots in `~/review/shots`. [review-app/KIT.md](review-app/KIT.md) tells it how to build a tour from the kit, and [review-app/WRITING.md](review-app/WRITING.md) how to write one. `examples/rply-16.tsx` is a complete tour.
+
+Steps and review hooks, which are temporary code in the box's copy of the app, report what happens by posting events to `$BOTTLESHIP_REVIEW_URL/api/events`:
+
+```json
+{ "instance": "base", "kind": "hook", "at": "push/index.ts:47", "text": "setPresence key=…/ada-7f3c",
+  "flow": { "id": "presence", "edge": ["sync", "pres"], "node": "pres", "status": "fail", "label": "…/ada-7f3c → deploys" },
+  "overlay": { "title": "No push for Ada", "status": "fail" } }
+```
+
+`kind` is `request`, `hook`, `ok` or `fail`. `flow` moves a dot along an edge and sets a node's state and label. `overlay` shows a note over that instance. The server tags each event with the step that was running, and answers 400 with the problems when an event is malformed.
+
+For GitHub Enterprise, log gh in to that host (`gh auth login --hostname <host>`) and make `GH_TOKEN` a token for it.
+
 ## Development
 
 ```sh
 npm test                               # build, then all tests
-npx vitest run test/cli.test.ts        # one file (needs a build first)
-grep -rn 'ponytail:' src presets       # deliberate shortcuts and their upgrade paths
+npx vitest run test/cli.test.ts        # one file, after a build
+grep -rn 'ponytail:' src               # deliberate shortcuts and their upgrade paths
+cd review-app && npm run playground    # the review kit against recorded reviews, gallery at #/gallery
 ```
+
+Tests run boxes with the `dir` provider in [test/fixtures/providers/dir](test/fixtures/providers/dir), which uses directories on this machine, so no Docker is needed.
+
+To release, add a section with the new version on top of [CHANGELOG.md](CHANGELOG.md) and set the same version in `package.json`. Merging it to `main` publishes it to npm.

package/dist/src/boxes.d.ts

@@ -1,64 +1,66 @@
-import { BsError } from "./config.ts";
-import type { Config, LoadedProvider, TemplateSpec } from "./types.ts";
-export interface Repo {
-    url: string;
-    label: string;
-}
+import { type Provider } from "./provider.ts";
+import type { Repo, RepoEnv } from "./repo.ts";
+import type { Config } from "./types.ts";
 export interface Box {
     id: string;
-    provider: LoadedProvider;
+    provider: Provider;
     box: string;
-    warning?: string;
-    login?: Login;
-}
-export interface Login {
-    url: string;
-    code?: string;
-    agent: string;
 }
 export type AgentState = {
     agent: "running";
+    env?: string;
     log: string;
 } | {
     agent: "exited";
     exitCode: number;
+    env?: string;
     log: string;
 } | {
     agent: "stopped";
+    env?: string;
     log: string;
-} | {
-    agent: "waiting_for_login";
-    login?: Login;
-    log: string;
-} | {
-    agent: "login_failed";
-    exitCode: number;
-    log: string;
 };
-export declare const goneFix = "the box is gone. Start a new one with `bottleship new \"<task>\"` and tell its agent to continue on the branch the old box pushed";
-export declare function templateSpec(cfg: Config, agentName: string): TemplateSpec;
-export declare function currentTemplate(cfg: Config, provider: string): string | undefined;
+export declare const goneFix = "the box is gone. Start a new one with `bottleship agent new \"<task>\"` and tell its agent to continue on the branch the old box pushed";
+export declare function boxImage(cfg: Config, agentName: string, repoEnv?: RepoEnv, extra?: string): {
+    dockerfile: string;
+    image: string;
+};
 export declare function parseId(cfg: Config, handle: string): {
     provider: string;
     box: string;
 };
-export declare function newBoxId(prompt: string): string;
+export declare function newBoxId(label: string): string;
 export declare function openBox(cfg: Config, handle: string): Promise<Box>;
-export interface SetupOptions {
-    agent: string;
-    prompt: string;
-    repo?: Repo;
+export interface BoxOptions {
+    provider: string;
+    label: string;
+    agent?: string;
+    workspace?: {
+        clone: Repo;
+    } | {
+        tar: Buffer;
+    };
+    repoEnv?: RepoEnv;
     dotenv?: Record<string, string>;
+    pr?: {
+        number: number;
+        base: string;
+    };
+    env?: Record<string, string>;
+    dockerfile?: string;
 }
-export declare function setupAndStart(cfg: Config, b: Box, { agent: agentName, prompt, repo, dotenv }: SetupOptions): Promise<void>;
-export declare function missingSecrets(names: string[]): BsError;
-export declare function newBox(cfg: Config, opts: SetupOptions & {
-    provider: string;
-    source?: string;
-}): Promise<Box>;
-export declare function parseLogin(output: string, agent: string): Login | undefined;
+export declare function createBox(cfg: Config, opts: BoxOptions): Promise<Box>;
+export declare function putTar(b: Box, dir: string, tar: Buffer): Promise<void>;
+export declare function putFiles(b: Box, files: Record<string, string>): Promise<void>;
+export declare const runIn: (b: Box, script: string) => Promise<import("./types.ts").ExecResult>;
+export type Stage = "setup" | "start" | "ready" | "failed";
+export declare function prepare(b: Box, seconds?: number): Promise<{
+    stage: Stage;
+    message?: string;
+    log?: string;
+}>;
+export declare function startAgent(b: Box, prompt: string): Promise<void>;
 export declare function agentState(b: Box, lines?: number): Promise<AgentState>;
-export declare function loginState(b: Box, setup?: string, seconds?: number): Promise<AgentState>;
 export declare function waitAgent(b: Box, seconds: number, lines?: number): Promise<AgentState>;
-export declare function ask(b: Box, prompt: string): Promise<Login | undefined>;
+export declare function ask(b: Box, prompt: string): Promise<void>;
 export declare const inBox: (script: string) => string;