docs: name bot-bottle, not ./cli.py, in every instruction

`doctor` told users to run `./cli.py backend setup`. cli.py is a four-line wrapper at the repo root that calls bot_bottle.cli:main, and it does not ship — [tool.setuptools.packages.find] includes only bot_bottle*, so anyone who installed rather than cloned has no such file. Confirmed against a real install: the user's tree contains exactly one executable, `bot-bottle`, and no cli.py anywhere, while doctor recommended `./cli.py` three times. Invisible in development, where ./cli.py works fine from a checkout, which is why only a clean-install test surfaced it. The two entry points are the same code, so the fix is to name the one that always exists. 141 replacements across 45 files: the runtime messages that caused this, plus README, docs, PRDs, research notes and test prose, so nothing teaches the invocation a user cannot run. scripts/demo.sh is deliberately untouched — it *executes* ./cli.py from a checkout, where that is the correct and available path. Verified end to end: a sandbox install now reports "Run: bot-bottle backend setup --backend=firecracker", and bot-bottle is on that user's PATH. Unit suite unchanged against the pre-existing baseline. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WEfZZhakx13bxTfXcZCoS5
2026-07-27 10:20:17 -04:00
parent 5c499d290b
commit cd9f023f3d
45 changed files with 135 additions and 135 deletions
@@ -14,8 +14,8 @@
 Today the dashboard is read-only: it surfaces pending proposals
 and active agents (PRD 0019) but can't *start* an agent or
 *re-enter* one. The operator's path is split — they launch
-agents from one terminal (`./cli.py start <name>`), and watch
-them from another (`./cli.py dashboard`).
+agents from one terminal (`bot-bottle start <name>`), and watch
+them from another (`bot-bottle dashboard`).

 This PRD collapses that split. The dashboard becomes the
 operator's single surface: pressing a key opens an agent picker,
@@ -31,7 +31,7 @@ claude session AND the dashboard process. Exit claude → back to
 dashboard, bottle still running. Start another agent → two
 bottles up at once. Quit the dashboard → bottles continue
 running. Teardown is **always explicit**: the operator presses
-`x` on an agent, or runs `./cli.py cleanup` later.
+`x` on an agent, or runs `bot-bottle cleanup` later.

 ## Problem

@@ -45,7 +45,7 @@ Two real frictions today:
   open and the dashboard's "active agents" pane is hopelessly
   behind reality because they just spawned three in a row.

-2. **`./cli.py start` ties the bottle to a single claude
+2. **`bot-bottle start` ties the bottle to a single claude
   session.** The start command's `ExitStack` brings the bottle
   up, runs claude, and tears down on Ctrl-D — fine for a one-
   shot session, wrong for "let me bounce in and out of this
@@ -60,7 +60,7 @@ captures full-merged logs per bottle (PRD 0018). It already

 ## Goals / Success Criteria

-1. From inside `./cli.py dashboard`, pressing `n` (new) opens
+1. From inside `bot-bottle dashboard`, pressing `n` (new) opens
   an agent picker listing every agent defined in the manifest.
   Selecting one runs `prepare → preflight → launch`.
 2. The preflight Y/N summary renders cleanly — either as a
@@ -83,7 +83,7 @@ captures full-merged logs per bottle (PRD 0018). It already
   state cleanup) without quitting the dashboard.
 7. Quitting the dashboard (`q`) leaves every running bottle
   running. Bottle teardown is always explicit (per-bottle `x`
-   or `./cli.py cleanup`). The next `./cli.py dashboard`
+   or `bot-bottle cleanup`). The next `bot-bottle dashboard`
   invocation re-discovers them via `list_active_slugs()` and
   surfaces re-attach for any it can reconstruct context for
   (see "Cross-dashboard re-attach" below).
@@ -94,13 +94,13 @@ captures full-merged logs per bottle (PRD 0018). It already
  embedded-emulator option from the research doc is out of
  scope. The handoff (option 1) is the v1; option 2 is a
  separate PRD if and when handoff is observably insufficient.
- **Adopting bottles started by an out-of-dashboard `./cli.py
+- **Adopting bottles started by an out-of-dashboard `bot-bottle
  start` invocation.** Those have their own ExitStack-owner and
  the dashboard treats them as read-only-watch (already does
  today). Re-attach only applies to bottles the *current
  dashboard process* started.
 - **Resurrecting an out-of-process bottle into a new dashboard
-  with full re-attach.** A bottle started by `./cli.py start`
+  with full re-attach.** A bottle started by `bot-bottle start`
  in another terminal — or by a previous dashboard run, now
  exited — appears in the agents pane (already does, PRD 0019)
  and can be re-attached via `docker exec -it claude` because
@@ -109,12 +109,12 @@ captures full-merged logs per bottle (PRD 0018). It already
  context object to drive teardown — e.g., the
  ExitStack-tracked CA + state cleanup `_settle_state` performs
  today. Cross-dashboard re-attach uses the existing
-  `./cli.py cleanup` for teardown, not an `x` keypress (see
+  `bot-bottle cleanup` for teardown, not an `x` keypress (see
  open questions).
 - **Multi-window UI.** Single curses window, two existing
  panes (proposals + agents); the agent picker is a modal, not
  a third pane.
- **Removing `./cli.py start`.** Stays as the script-friendly /
+- **Removing `bot-bottle start`.** Stays as the script-friendly /
  legacy entry point. The dashboard is the new default.

 ## Scope
@@ -140,7 +140,7 @@ captures full-merged logs per bottle (PRD 0018). It already

 ### Out of scope

- Changes to `./cli.py start` itself. It keeps its current
+- Changes to `bot-bottle start` itself. It keeps its current
  shape; the dashboard reuses its internal pieces (backend.
  prepare / backend.launch) without reaching through the CLI
  layer.
@@ -157,7 +157,7 @@ captures full-merged logs per bottle (PRD 0018). It already
 Today's flow:

 ```
-./cli.py start agent
+bot-bottle start agent
  └─ with backend.launch(plan) as bottle:        ← bottle alive while inside `with`
       bottle.exec_agent([...], tty=True)       ← blocks until claude exits
     # context exits → compose down → state cleanup
@@ -166,7 +166,7 @@ Today's flow:
 The proposed dashboard-driven flow:

 ```
-./cli.py dashboard
+bot-bottle dashboard
  └─ bottles: dict[str, tuple[ContextManager, DockerBottle]] = {}

     # operator presses `n`, picks agent
@@ -205,7 +205,7 @@ Two shifts:
   evaluation, state-dir reap) doesn't fire on a quit-while-
   running bottle. It DOES fire when the operator explicitly
   stops via `x`, because that calls `cm.__exit__`. For
-   bottles a previous dashboard quit on, `./cli.py cleanup`
+   bottles a previous dashboard quit on, `bot-bottle cleanup`
   is the path — its compose-down + state-reap logic
   already covers the case.

@@ -213,7 +213,7 @@ Two shifts:

 When the dashboard discovers a bottle in `discover_active_agents`
 that it didn't itself start (a previous-dashboard or external
-`./cli.py start` bottle), Enter still attaches via `docker exec
+`bot-bottle start` bottle), Enter still attaches via `docker exec
 -it … claude` — the agent container is running `sleep infinity`
 exactly the same way regardless of who started it. The only
 thing the current dashboard lacks for those bottles is the
@@ -221,8 +221,8 @@ launch-context object needed to drive a clean teardown via
 `x`.

 For v1 we surface this honestly: pressing `x` on a non-owned
-agent shows a status hint pointing at `./cli.py cleanup` (or
-`./cli.py cleanup` targeted at the slug if we add that flag
+agent shows a status hint pointing at `bot-bottle cleanup` (or
+`bot-bottle cleanup` targeted at the slug if we add that flag
 later). The agent stays alive; the operator handles teardown
 out-of-band. Enter (re-attach) works for both owned and
 non-owned bottles.
@@ -288,7 +288,7 @@ agents pane.

 `x` on a non-owned agent (discovered via `list_active_slugs`
 but not in `bottles` dict): no-op with status hint pointing
-at `./cli.py cleanup` (the existing path that tears down
+at `bot-bottle cleanup` (the existing path that tears down
 ANY bot-bottle compose project plus reaps state dirs).

 ### Dashboard quit
@@ -300,7 +300,7 @@ the `docker compose` project keeps running. The next dashboard
 invocation discovers the bottles via `list_active_slugs` and
 surfaces re-attach.

-This is a real departure from today's `./cli.py start`
+This is a real departure from today's `bot-bottle start`
 semantics (which couples bottle lifetime to the process via
 ExitStack). It's intentional: the dashboard is a watching +
 acting surface, not a lifetime owner.
@@ -322,7 +322,7 @@ Sized for one PR each.
   dashboard's ExitStack; handoff invokes `attach_agent`.
 3. **Re-attach via Enter on owned agents-pane row.** Looks up
   the slug in the dashboard's `bottles` map; if present →
-   handoff; else → status-line hint pointing at `./cli.py
+   handoff; else → status-line hint pointing at `bot-bottle
   resume`.
 4. **Explicit per-bottle stop (`x` keybinding).** Pop the
   bottle's `close` callback off the stack, call it, refresh.
@@ -369,7 +369,7 @@ Sized for one PR each.
   bottles dict goes out of scope without invoking `__exit__`,
   so the `docker compose` projects keep running. Bottle
   teardown is always explicit: per-bottle `x` (for
-   dashboard-owned), or `./cli.py cleanup` (for everything).
+   dashboard-owned), or `bot-bottle cleanup` (for everything).

 ## Open questions