docs: describe the settled v0.8.0 surface, not the release that made it

CLAUDE.md

@@ -2,28 +2,29 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## Status: past the POC, deliberately small
+## The shape of this repo
 
-`v0.6.0` was the POC snapshot — the widest the command surface ever got, with eight
-`tabs` subcommands around a long-polling bridge. **v0.8.0 is the subtraction** (breaking):
-`tabs watch`, `tabs push`, `tabs check`, `tabs history` and `tabs prompt` are gone, and so
-are the vendored simulator, the delta-log subsystem, the three skill variants, and every
-long poll.
+The command surface is small on purpose, and it has shrunk more often than it has grown.
+The `tabs` half is one loop in three steps: the extension pushes tabs to the bridge
+(`tabs serve`), the agent reads them (`tabs list`), the agent proposes a script the user
+accepts or denies (`tabs suggest`).
 
-`0.7.0` is a version that only exists in the git history: the bump landed on `main` but
-was never tagged, so no user ever received it. Everything it did ships as part of 0.8.0 —
-which is why the jump users see is 0.6.0 → 0.8.0. Don't "restore" a v0.7.0 release; there
-is nothing it would contain that 0.8.0 doesn't.
-
-What's left is the loop those commands existed to serve, in three steps: the extension
-pushes tabs to the bridge (`tabs serve`), the agent reads them (`tabs list`), the agent
-proposes a script the user accepts or denies (`tabs suggest`). Claude Code's `/loop`
-already owns the pacing `tabs watch` was built for, so the CLI doesn't.
-
-The bias stays subtractive: prefer deleting a subsystem's docs along with its code over
+**The bias is subtractive.** Prefer deleting a subsystem's docs along with its code over
 leaving prose describing something that's gone, and treat `registry.ts` (plus `git log`)
 as the authority on what exists — not this file.
 
+**Don't reintroduce these.** Each was removed deliberately, and the reason is recorded
+where the replacement lives: `tabs watch` (Claude Code's `/loop` owns that pacing),
+`tabs push` and `tabs check` (folded into `tabs suggest`, which validates before it
+queues), `tabs history`, `tabs prompt`, the vendored simulator, the delta log, the three
+skill variants, and every long poll. Adding one back needs a reason that didn't exist in
+v0.8.0, not just a use for it.
+
+One release-history trap: **`0.7.0` was never tagged.** The bump landed on `main` but no
+user ever received it, and everything it did shipped as part of 0.8.0 — which is why the
+jump users see is 0.6.0 → 0.8.0. Don't "restore" a v0.7.0 release; there is nothing it
+would contain that 0.8.0 doesn't.
+
 ## What this is
 
 `tabbrew-cli` is a Bun + TypeScript CLI (`tabbrew` binary) that authenticates to a
@@ -348,7 +349,7 @@ is a **hand-written mirror** of this table — a card per command, coloured by h
 command reaches (offline / loopback / account / GitHub Releases). Nothing generates it and
 nothing tests it, so a new command, a *deleted* command, a renamed flag, or a reworded
 summary has to be carried over by hand or the page quietly goes stale. It was rewritten
-for v0.7.0 (the removed commands survive there only as a struck-through "what changed"
+for v0.8.0 (the removed commands survive there only as a struck-through "what changed"
 strip, which is the one thing a returning reader most needs). It is the only file in the
 repo that duplicates `registry.ts`; keep the duplication small enough to be worth it.
 
@@ -395,6 +396,7 @@ src/
   credentials.ts      # token storage (~/.config, chmod 600) + env-var override
   api.ts              # authed fetch wrapper + 401 handling + userinfo + html_files client
   update.ts           # self-update: release lookup, download+checksum, atomic binary swap
+  bridge.ts           # tabs: find the loopback bridge and prove it's ours (/health)
   util.ts             # sleep, which(), safeText, open-browser
   registry.ts         # command surface as data: groups, summaries, per-command flags, env tables
   registry.test.ts    # bun test — help fits 80 cols, groups intact, findCommand precedence

README.md

@@ -5,18 +5,6 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 [![Bun](https://img.shields.io/badge/Bun-%E2%89%A5%201.1-000?logo=bun&logoColor=white)](https://bun.sh)
 
-> **Status: proof of concept.** `v0.6.0` was the high-water mark of the exploration;
-> `v0.8.0` is where the subtraction lands. **`tabs check`, `tabs push`, `tabs watch`,
-> `tabs history` and `tabs prompt` are gone**, and the `--port`, `--out` and `--variant`
-> flags with them — the tab surface is three commands now (`serve` / `list` / `suggest`).
-> `init` follows: it installs one skill instead of two, and deletes the orphaned
-> `tabbrew-auto` it finds. `docs`, `login`/`whoami`/`logout` and `update` are untouched. Pin
-> [`v0.6.0`](https://github.com/colevels/tabbrew-cli/releases/tag/v0.6.0) if you depend
-> on a command that disappeared; some of them may come back in a simpler shape.
->
-> (`0.7.0` exists in the git history but was never tagged, so it never reached anyone —
-> everything it changed ships here.)
-
 The command-line companion to **TabBrew** — it brings your TabBrew account to the
 terminal and to the AI coding agents working there.
 
@@ -38,6 +26,9 @@ The payoff: an AI agent working in your repo generates a report as HTML and push
 straight into your browser's Docs view — or reads your open tabs, writes a validated
 TabBrew Script, and puts it in the sidepanel for you to accept.
 
+The surface is small on purpose — four groups, and it has shrunk more often than it has
+grown ([what changed in v0.8.0](#what-changed-in-v080)).
+
 ## Commands
 
 ```
@@ -460,8 +451,8 @@ and send no `Origin`.
 The saved `tabs.json` is written **`chmod 600`**, like `credentials.json` — it holds the
 URL and title of every open tab, which is browsing history and doesn't become un-leaked
 the way a revoked token does. It is also the *only* thing the CLI keeps: it's overwritten
-on every export and holds just the currently-open tabs. (v0.6.0's `tabs-history.jsonl`
-delta log, which remembered tabs you had since closed, is gone along with `tabs history`.)
+on every export and holds just the currently-open tabs. (An earlier `tabs-history.jsonl`
+delta log, which remembered tabs you had since closed, is gone.)
 
 ## Docs view (`docs push` / `docs list`)
 
@@ -565,6 +556,32 @@ that resolves there), and `GET /suggestion` **pops** — the second call returns
 (it would overwrite `bun` itself) — test that against a compiled `dist/tabbrew`, with
 `TABBREW_REPO` / `TABBREW_RELEASE_URL` pointed at a fork.
 
+## What changed in v0.8.0
+
+`v0.8.0` is a **breaking** release, and the only one so far that removed more than it
+added. If you're coming from `v0.6.0`, this is the list:
+
+- **Five `tabs` commands are gone** — `tabs check`, `tabs push`, `tabs watch`,
+  `tabs history` and `tabs prompt` — leaving the three that are the loop:
+  `serve` / `list` / `suggest`.
+- **Three flags went with them:** `--port` (Chrome only reaches 49227/49228, so any
+  other value could only ever be wrong), `--out` (it moved the writer but not the two
+  readers; `TABBREW_TABS_PATH` moves all three), and `--variant` (there is one skill now).
+- **`init` installs one skill instead of two**, and **deletes an orphaned `tabbrew-auto`
+  directory** if it finds one — on install as well as `--uninstall` — because that skill
+  tells your agent to run `tabs watch`, which no longer exists. If you set this CLI up
+  before v0.8.0, re-run `tabbrew init` (add `--global` if that's how you installed it) so
+  the awareness doc and skill match the commands that actually exist.
+- Behind those: the vendored simulator, the `tabs-history.jsonl` delta log, and every long
+  poll in the bridge. `tabs suggest` returns as soon as the script is queued, and the
+  bridge speaks protocol 3 over five plain request/response routes.
+- **Untouched:** `docs push` / `list` / `open`, `login` / `whoami` / `logout`, and `update`.
+
+Pin [`v0.6.0`](https://github.com/colevels/tabbrew-cli/releases/tag/v0.6.0) if you depend on
+a command that disappeared; some of them may come back in a simpler shape. (`0.7.0` exists
+in the git history but was never tagged, so it never reached anyone — everything it changed
+shipped in `0.8.0`.)
+
 ## Credentials
 
 - Stored at `~/.config/tabbrew/credentials.json` — **not** in the project folder.

package.json

@@ -1,7 +1,7 @@
 {
   "name": "tabbrew-cli",
   "version": "0.8.0",
-  "description": "Push HTML docs into TabBrew from your terminal — a Bun + TypeScript CLI.",
+  "description": "The terminal half of TabBrew: read your Chrome tabs, propose a script, push HTML docs into the sidepanel — a Bun + TypeScript CLI.",
   "type": "module",
   "license": "MIT",
   "author": "Jiho",