@myrtilleio/redline 0.1.0

package/README.md

@@ -0,0 +1,281 @@
+# Redline
+
+**Review the UI your AI agent built the way you review its code: mark it, send it, check it, accept it.**
+
+Describing design problems in chat is slow and lossy ("the second card, no, the one with the yellow…"). With Redline you review the real, running page instead, in turns:
+
+- **Mark.** Draw on the page with the pen: cross out what has to go, circle what's off, tick what you love, underline the copy. Or click anything to say why. The shape and its colour are the instruction; words are optional.
+- **Send.** Your marks go to your agent as one round, as a brief with the selector, visible text, size and styles of every element, plus screenshots.
+- **Check.** The agent fixes them in the code and reports back once. Each fix waits for you with a before/after.
+- **Accept**, or **Redo** it in your next round. Nothing is done until you've seen it, and what you approved stays approved: Redline re-checks it after every round.
+
+Redline has no runtime dependencies and needs Node ≥ 20. It's built to survive real-world pages: it has been stress-tested by injecting it into 19 production sites (GitHub, YouTube, Stripe, BBC, Airbnb, Apple, Wikipedia, Figma, …) and by an agent-vs-agent review loop, and it handles:
+
+- Trusted Types (no `innerHTML`) and a strict `style-src`.
+- Consent iframes and focus-trapping modals.
+- Site hotkeys (typing a note never triggers them).
+- Single-page-app route changes.
+- Hundreds of marks at 60fps.
+
+In proxy mode, it patches the site's CSP just enough to allow its own script. The overlay lives in a Shadow DOM, so the site's CSS can't break it and it can't break the site.
+
+![Redline: product, review loop and domain model](docs/redline.png)
+
+The board above is [`docs/redline.excalidraw`](docs/redline.excalidraw) (open it at [excalidraw.com](https://excalidraw.com) to edit): who it's for and why, the review loop, and what a feedback item is made of. Regenerate with `node docs/diagrams/generate.mjs && node docs/diagrams/render.mjs`.
+
+## Get started in 5 minutes
+
+You need Node 20 or newer and Chrome or Chromium (for the before / after screenshots). Accounts live on the hosted Redline at <https://redline-nine-eta.vercel.app> (Vercel + Neon). To run your own instead, see [`web/README.md`](web/README.md).
+
+1. **Install Redline**
+
+   ```sh
+   npm install -g @myrtilleio/redline      # the `redline` command
+   ```
+
+2. **Open your account page:** <https://redline-nine-eta.vercel.app>. (Self-hosted: `docker compose up -d`, then <http://localhost:4700>, and add `--server http://localhost:4700` when you log in.)
+
+3. **Create your account.** Sign up and press **Create key**. The page walks you through the rest, with your key and server filled into every command, and ticks each step off as you do it.
+
+4. **Log in, then try the demo**
+
+   ```sh
+   redline login rl_your_key
+   redline demo --open
+   ```
+
+5. **Connect your agent** to the hosted MCP server (it works from any machine, cloud agents included):
+
+   ```sh
+   claude mcp add --transport http redline https://redline-nine-eta.vercel.app/api/mcp --header "Authorization: Bearer rl_your_key"
+   ```
+
+   Or keep everything on your machine with the local one: `redline init && claude mcp add redline -e REDLINE_API_KEY=rl_your_key -- redline mcp`.
+
+6. **Review your own site**
+
+   ```sh
+   redline proxy http://localhost:5173 --cloud     # --cloud syncs the project for the hosted MCP server
+   ```
+
+Without `--cloud`, your site, notes and screenshots never leave your project; the account only unlocks the tool. `redline whoami` shows which account this machine uses, and `redline logout` forgets the key. A key checked in the last week keeps working offline. Revoke a key on the account page and it stops working everywhere.
+
+## Quick start
+
+```sh
+npm i -D /path/to/redline        # install from this repo (or run `npm link` in it)
+
+redline serve ./site         # a static site the agent generated
+redline proxy localhost:5173 # or put it in front of any dev server (Vite, Next, Astro…)
+```
+
+Open the printed URL (default `http://127.0.0.1:4545/`). A toolbar appears at the bottom of the page.
+
+To see the whole loop in a minute, try the demo:
+
+```sh
+npm run demo        # or: redline demo --open
+```
+
+It opens a deliberately imperfect landing page where your agent's first round is already back. Four marks were sent: three fixes, and one quote marked *keep*. The scripted agent fixed the three in the files, and, like agents do, quietly restyled the quote while tidying up. A short card says so; press **Review 4 fixes** and accept or redo each fix with **A** or **R**, and watch the guard catch the quote. Then make your own marks and press **Send**. The demo runs on a throwaway copy of `examples/demo-site`.
+
+## Mark, Send, Check
+
+The toolbar only ever shows the next step: **Pointer**, **Pen**, and whichever turn applies (**Send N**, *With agent*, **Review N**).
+
+- **Pen (P):** draw. The shape carries the meaning: ✗ remove, ◯ look here, underline these words, ✓ keep, → move this there. No typing needed. **Click** anything with the pen to box it and say *why*.
+- **Ink:** red means change, green means keep, amber means idea. The gesture usually sets it (a ✓ is green, an ✗ is red); the dot in the receipt after a stroke, or `1` `2` `3`, change it.
+- **Pointer (V):** use the site normally. Click a line or a box's edge to open its note.
+
+Everything else sits behind **⋯**: Notes, Box an area (for a region that isn't one element; ↑ walks up to the parent), Devices, Copy for AI, Show original, Hide marks. Each note's extras (Adjust, Reference, the agent's options, Move, Delete) sit behind its own ⋯.
+
+**Preview the page:** press **\\** (or ⋯ → Preview the page) to see the site exactly as visitors will, with nothing of Redline on it. Press **\\** again, or the small tab that appears when you move to the bottom-right corner, to bring everything back. It survives the agent's live reloads. To share a clean page, add `?redline=off` to the link: it opens without Redline, just for that visit.
+
+**The loop, in turns.** Your marks are drafts until you press **Send** in the toolbar. That hands them to your agent as one round (without a server, Send copies them for your AI chat). The agent fixes what it can, asks *under your mark* when something is unclear, and closes the round with a short report: what it changed, how it reads the page (you can correct it), and at most three questions. You get one signal, "Round 2 is back". The page only ever shows your own marks.
+
+## Check
+
+Press **Review N** and the page dims; a thin outline marks the first fix, and one card docked above the toolbar says what the agent did and what you asked. The live page *is* the after. The card's **Before / After** switch lays the before over it, exactly where it was: **tap Space** to switch (and tap again to come back), or **hold Space** to peek. The outline takes the old element's size while it's shown, so a fix that resized something visibly grows and shrinks as you flip. The before is taken without your mark on it. When it can't line up with the page (it was taken in the other theme, or the element changed shape), it shows as a framed picture instead. If the agent rebuilt the page so much that the element can't be found (not by its selector, not by its words), the card says so and shows the before and after pictures, and you judge from those. Far items are reached by a quick hop, and the outline stays locked to the element while you scroll. Each fix asks for one key:
+
+- **A** accepts it. A green seal lands on it, and the spotlight moves on.
+- **R** redoes it: say what's still wrong (optional) and it becomes a draft for your next round.
+- **← →** move between items, **Esc** stops (the rest wait for later).
+
+At the end you get the round's **first-time accept rate**, filling a ring, and one **Send** for whatever you redid.
+
+## Guards: what you approve stays approved
+
+A green mark and an accepted fix are *approvals*. Redline photographs each one and takes a fingerprint of it as approved: its size, its text, and the styles that make its look, for it and everything inside it. Every time your agent closes a round, each approval is photographed again and compared. If nothing changed, you hear nothing. If something did, the mark comes back to the page with a red **Changed** tab, joins **Review**, and says what changed in words:
+
+```
+font-size 32px → 24px on blockquote
+font-style italic → normal on blockquote
+```
+
+**R** sends it back: the agent's next brief says exactly what to restore, next to the screenshot as approved. **A** keeps the new look, which becomes the approved one. An approval that has left the page can be let go.
+
+**At every width that matters.** An approval made on a laptop or tablet is also guarded on a phone (390px), unless it isn't shown there. A regression that only breaks the mobile layout comes back as `at 390px: grid-template-columns 342px → 169px 180px on section.stats`.
+
+**No crying wolf.** A guard that raises false alarms gets ignored, so they're designed out:
+
+- Photographs don't depend on the moment: CSS animations and transitions jump to their end, endless ones stop, videos pause, and images (lazy ones too) are loaded first.
+- Each approval is fingerprinted three times over a second. Whatever changes on its own (a clock, a feed ticking "3s ago", a carousel, numbers counting up) is marked volatile and never compared.
+- What changes between page loads but not within one (a "last updated" stamp) gets one more key in Check: **L**, *changes by itself*. From then on Redline watches its look, not its words and images.
+
+**Checked before you see it.** The agent can run the same check before it closes a round, and fix what it broke before you ever see a red tab: `check_approvals` over MCP, or `redline verify <site>`. It records nothing; only the check Redline runs when the round closes reaches you.
+
+**In CI.** The same check runs headless, and exits 1 if an approval changed or is gone:
+
+```sh
+redline verify ./site                      # a static site
+redline verify --url http://localhost:5173  # or a running dev server
+```
+
+It needs `.redline/feedback.json` (commit it; baselines are taken while the review is open) and Chrome.
+
+**How well it works.** `npm run field-test` runs three rounds on a real Vite + React app that moves by itself (a live feed, count-up numbers, a carousel, entrance animations, a lazy image), with seven approvals at two widths. Scripted, so every alarm can be labelled. Last run: 0 false alarms, the agent's pre-flight caught all three approvals a shared-button edit broke, and the round's guards caught both approvals a phone-only regression broke, with nothing missed. Details in [`examples/field-test/RESULTS.md`](examples/field-test/RESULTS.md). What it can't tell you is the accept rate: that takes a person.
+
+## Share the proof
+
+A round is worth showing to people who weren't there: a PM, a client, the PR reviewer.
+
+- **Round report** (⋯ → *Round report*, or `redline report`): one self-contained HTML page, images inside. It shows the agent's summary and the first-time accept rate, then every fix with what was asked, what was done and a before/after slider (side by side when the fix resized the element), your verdicts and what the guards caught. Send the file to anyone. `--md` prints the same thing as Markdown for a PR comment (`redline report --md | gh pr comment <n> --body-file -`), and `--round <n>` picks an earlier round.
+- **Check link** (⋯ → *Copy review link*, also printed by `serve`/`proxy`): the page with `?redline=check` and a review key. Whoever opens it lands straight in Check, with no drawing tools, and accepts or redoes the fixes like you would; the key lets them do that and nothing else. Their redos go to your agent in the next round. Start Redline with `--host 0.0.0.0` (or behind a tunnel) so the link opens from another machine.
+
+### Who can reach your review
+
+On your machine, from the page Redline serves, you need nothing. Everyone else needs a key, and the keys change every time Redline starts:
+
+- The **review key** rides in the Check link: read the review, accept, redo, send back. It can't add, edit or delete marks, or upload anything.
+- The **owner key** is printed when you bind to another interface (`--host 0.0.0.0`), for opening your own review from another machine.
+- Another website open in your browser can't read or write your review, and neither can a hostname that merely resolves to your machine.
+
+Keys leave the address bar as soon as the page opens, so they don't end up in screenshots or bookmarks.
+
+## Taste: the agent learns the reviewer
+
+Every judgment is kept in `.redline/taste.json` and rendered as **`.redline/TASTE.md`**: what to keep exactly as it is, the fixes you accepted (the direction you like), the ones you rejected and why (never try them again), approvals that broke, and what the page is for in your words. It survives `redline clear`, and the top of every brief carries the latest rejections, so the same mistake doesn't come back two rounds later. The accept rate per round is in there too: it's how you see the agent getting better at your taste.
+
+## The designer toolkit
+
+Every note is a card that can carry five kinds of evidence, all of which end up in one brief for the agent:
+
+| | What you do | What the agent gets |
+|---|---|---|
+| **Adjust** (live edits) | In a note, open **Adjust** and scrub font size, weight, line height, spacing, radius and colours right on the page (drag a label, or ↑/↓ with Shift for ×10). Use **Edit text** to retype wording in place, and tick **Apply to all** to change every similar element. | Exact values: ``font-size` 76px → **48px** on every `h2.section-title``. Your edit stays previewed on the page until the agent ships it. Press `E` to flip between your version and the site as built. |
+| **Screenshots** | Nothing. Redline photographs each item with headless Chrome: as you saw it (with your mark), with your proposed edit, each option, and the result after the fix. | PNG files in `.redline/shots/`, which MCP clients receive as real images. You get a **Compare** slider (before/after) on resolved items. |
+| **Options** | Nothing. When a mark could be fixed several ways, the agent proposes a few instead of guessing. Flip between them live on the page, then **Pick** one. | Your pick, with its exact CSS/HTML to build. Agents propose options with `redline variants <id> --file options.json` or the `propose_variants` MCP tool. |
+| **Devices** (`D`) | See desktop, tablet and mobile side by side, as real iframes at 1440/820/390px, so every breakpoint applies. Select or draw in any of them: notes record that width. One toolbar drives all three, and scrolling syncs. | Notes tagged with the right screen width, and screenshots taken at that width. |
+| **References** | Paste (Ctrl+V), drop, or attach an image into a note: a site you like, a sketch. | Image files in `.redline/assets/`, with the note that says what to take from them. |
+
+Writing options: `&` in `css` is replaced with the item's selector everywhere it appears, including inside strings, and previews mark every declaration `!important` so they beat the site's CSS. An `html` option swaps the element's markup for real; on React/Vue pages, reload after previewing one so the framework owns that markup again.
+
+Screenshots need Chrome or Chromium installed (set `CHROME_PATH` if it isn't found) and Node 22+. Everything else works without them.
+
+## In the browser
+
+| Key | |
+|---|---|
+| `P` | **Pen**: draw on the page, or click an element to box it and say why. A second stroke drawn over the first right after joins it (so ✗ is one mark) |
+| `B` | **Box an area**: drag around a region, or click an element. `↑`/`↓` walks to the parent/child, `Enter` boxes it |
+| `V` / `Esc` | **Pointer**: use the site normally, with your marks still visible |
+| `1` `2` `3` | Ink: red (change) / green (keep) / amber (idea), for marks whose shape doesn't say it |
+| `L` | Notes panel, with open and resolved items; click one to jump to it |
+| `C` | Copy all feedback as a prompt for your AI chat |
+| `D` | Devices: desktop, tablet and mobile side by side |
+| `E` | Flip between your proposed edits and the page as built |
+| `H` | Hide or show marks |
+| `Ctrl`/`⌘` + `Z` | Undo the last pen mark |
+| `Ctrl`/`⌘` + `Enter` | Save a note |
+
+Every item also records the **screen width** (a note made on a phone is about the mobile layout) and the **page state**: pressed toggles, selected tabs and open menus. An underline records **the words it underlines**. **Move note** (the ↔ button) re-points a note at another element, and deleting can be undone from the toast.
+
+Marks are anchored to elements, not screen coordinates. They follow their element through scrolling, resizing and re-layouts, and survive reloads. Your mode (select/pen) is kept across the live reloads triggered by the agent's edits.
+
+## For the agent
+
+Feedback lives in `.redline/` in the directory you started Redline from:
+
+- `.redline/FEEDBACK.md`: the open items as an actionable brief, rewritten on every change
+- `.redline/TASTE.md`: what this reviewer approved and rejected, across every round
+- `.redline/feedback.json`: the full data, including the approvals' fingerprints
+
+```sh
+redline feedback               # print the brief (--json, --all, --page /pricing)
+redline wait                   # block until the reviewer presses Send, then print the brief (--timeout <s>)
+redline resolve 3 --note "Hero title now sentence case at 48px"
+redline reopen 3
+redline clear                  # drop resolved items (--all: everything); TASTE.md stays
+redline verify ./site          # every approval still as approved? exit 1 if not
+redline report --md            # the last round, for a PR comment (without --md: an HTML page)
+```
+
+Use single quotes around notes that contain `$` or backticks (`--note 'Now $29/mo'`). Items can be referenced by their pin number (`3`, `#3`) or id (`a_1b2c3d4e`).
+
+**Claude Code:** `redline init` adds a `/redline` slash command. It pulls the open feedback into context, applies the fixes, keeps what was marked Good, and resolves each item with a note. Then it runs `redline wait` in the background, so your next Send wakes the agent without you typing anything.
+
+**MCP (any MCP-capable agent):** `redline mcp` runs Redline as a stdio MCP server with ten tools:
+
+| Tool | What it does |
+|---|---|
+| `start_review` | Serve a folder (`dir`) or proxy a dev server (`url`), and return the URL for the reviewer |
+| `wait_for_round` | Wait until the reviewer presses Send, then return the round's brief (at once if one is waiting). Returns "still waiting" after `timeout_seconds` (default 240) so the agent calls it again; sends progress while it waits and stops when the client cancels |
+| `feedback` | The open items as a brief (or `format: "json"`), optionally for one `page`, plus their screenshots and reference images as images |
+| `propose_variants` | Answer "ask for options": 2–5 alternatives `{label, css, html?, note?}` the reviewer previews and picks from |
+| `reply` | Answer, or ask, under one of the reviewer's marks |
+| `finish_round` | Close the round: a summary, how you read the page, at most 3 questions |
+| `check_approvals` | Before `finish_round`: is everything the reviewer approved still as approved, at every width? Records nothing; returns what changed, in words, with the approved screenshots |
+| `resolve` | Mark items done with a one-line `note`; the reviewer sees it live |
+| `reopen` | Mark items open again |
+| `stop_review` | Stop the session |
+
+Register it with Claude Code from your project folder (feedback lives in that folder's `.redline/`):
+
+```sh
+claude mcp add redline -- node /path/to/redline/bin/redline.js mcp
+```
+
+The loop is `wait_for_round` → fix and `resolve` → `finish_round` → `wait_for_round`, so the agent keeps working round after round while you review.
+
+Other clients take the same command: `{"command": "node", "args": ["/path/to/redline/bin/redline.js", "mcp"]}`.
+
+**Other agents:** tell them *"Read `.redline/FEEDBACK.md`, apply the feedback, and run `redline resolve <id> --note …` for each item."* Or press **Copy for AI** in the toolbar and paste the brief into any chat.
+
+An excerpt of the brief:
+
+```md
+### 1. ✗ Fix · note · id `a_4f0c9e21`
+- **Target:** `h1.hero-title` — `<h1 class="hero-title">` “THE ULTIMATE REVOLUTIONARY COFFEE TRACKING…”
+- **Comment:** All caps feels shouty. Sentence case, ~48px.
+- **Element now:** 932×380 at (174, 196) · font 76px/76px Georgia 700 · color #7c2d12
+
+### 2. ✓ Good · pen mark: circled · id `a_9b1d77aa`
+- **Target:** `div.plan.plan-featured` — `<div class="plan plan-featured">` “Pro $6/mo Unlimited brews…”
+- **Comment:** Love this highlight treatment
+```
+
+## Without a server
+
+`redline bundle -o redline.js` writes a standalone script. Add `<script src="redline.js"></script>` to any page (or inject it from devtools). Feedback is then kept in that browser's `localStorage`, and you hand it over with **Copy for AI** or the **.md** download.
+
+## How it works
+
+```
+browser ── overlay (client/overlay.js, Shadow DOM) ──┐  REST + Server-Sent Events
+                                                     ▼
+            redline serve|proxy (src/server.js) ── injects <script> into every HTML response
+                                                     │  watches site files → live reload
+                                                     ▼
+            .redline/feedback.json + FEEDBACK.md ◀── redline feedback / resolve (agent)
+```
+
+- `src/format.js` turns annotations into the Markdown brief and classifies pen gestures. It is shared by the CLI and the browser, and the bundler inlines it into the client.
+- `src/store.js` is the file-backed store: validated input, serialized writes, atomic renames.
+- `src/server.js` covers CSP patching for the injected script, static serving (with directory listings and traversal protection), the reverse proxy (HTML injection, redirect rewriting, WebSocket pass-through for HMR), the annotation API and SSE.
+
+## Development
+
+```sh
+npm test          # unit + API tests; browser e2e runs when playwright-core and Chromium are present
+REDLINE_SHOTS=/tmp/shots npm test   # also save e2e screenshots
+```

package/bin/redline.js

@@ -0,0 +1,375 @@
+#!/usr/bin/env node
+import { copyFile, mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { spawn } from 'node:child_process';
+import { buildClient } from '../src/bundle.js';
+import { formatMarkdown } from '../src/format.js';
+import { runMcpServer } from '../src/mcp.js';
+import { startDemo } from '../src/demo.js';
+import { isGuarded } from '../src/guards.js';
+import { reportHtml, reportMarkdown, reportModel } from '../src/report.js';
+import { createRedlineServer } from '../src/server.js';
+import { describeVerify, openVerifier, verifyApprovals } from '../src/verify.js';
+import { Store } from '../src/store.js';
+import { credentialsPath, currentAccount, forget, login, requireAccount, verifyKey } from '../src/account.js';
+import { startSync } from '../src/sync.js';
+import { basename } from 'node:path';
+
+const HELP = `redline — review the UI your AI agent built: mark it, send it, check each fix, accept it.
+
+Usage
+  redline login <key>          Save your API key (make one at your Redline account page; --server <url>)
+  redline whoami               Which account this machine uses
+  redline logout               Forget the saved key
+  redline serve [dir]          Serve a static site (default: .) with the overlay + live reload
+  redline proxy <url>          Put the overlay in front of a running dev server (e.g. http://localhost:5173)
+  redline demo                 Try it: a demo site where your agent's first round is back, ready to check
+  redline verify [dir]         Check every approval still looks as approved (CI); exits 1 if one changed
+                               (--url <dev server> instead of a folder)
+  redline report [-o file]     The last round as one page to share: before/after, verdicts, guards
+                               (--round <n>; --md for a PR comment, printed)
+  redline feedback             Print open feedback as a Markdown brief for your agent
+  redline wait                 Wait until the reviewer presses Send, then print the brief (exits at once if
+                               a round is already waiting; --timeout <s> exits 2 when time runs out)
+  redline resolve <id...>      Mark items done (--note "what changed"); the reviewer sees it live
+  redline reopen <id...>       Mark items open again
+  redline reply <id> "text"     Answer the reviewer in an item's conversation
+  redline done --summary "…" --reading "…" [--question "…"]
+                               Close the round: what you did, how you read the page, up to 3 questions
+  redline send                 Send the reviewer's drafts as the next round (the overlay has a Send button)
+  redline variants <id> --file options.json
+                               Propose options the reviewer asked for: [{label, css, html?, note?}], & = the element
+  redline clear                Delete resolved items (--all deletes everything)
+  redline bundle [-o file]     Write the standalone overlay script (no server; saves in localStorage)
+  redline init                 Add the /redline command for Claude Code to this project
+  redline mcp                  Run as an MCP server over stdio (tools include wait_for_round, feedback, resolve, finish_round)
+
+Options
+  -p, --port <n>      Port for serve/proxy (default 4545)
+      --host <h>      Interface to bind (default 127.0.0.1)
+      --open          Open the browser after starting
+      --store <dir>   Where feedback lives (default ./.redline)
+      --cloud         With serve/proxy: sync this project to your account, for the hosted MCP server
+                      (--project <name>; default: this folder's name)
+      --server <url>  Redline accounts server for login (default: the hosted Redline, or REDLINE_SERVER)
+      --json          Machine-readable output for feedback
+      --all           Include resolved items (feedback) / everything (clear)
+      --page <path>   Only feedback for one page, e.g. /pricing
+  -n, --note <text>   Resolution note for resolve
+      --target <css>  With resolve: what the "after" screenshot should show, if the fix restructured the element
+  -o, --out <file>    Output file for bundle
+  -h, --help          Show this help
+`;
+
+function fail(msg) {
+  console.error(`redline: ${msg}`);
+  process.exit(1);
+}
+
+// A session (serve, proxy, demo, mcp) starts with a valid account key, or with the
+// steps to get one. Offline, a key checked in the last week still works.
+async function gate(event) {
+  const acc = await requireAccount(event);
+  if (!acc.ok) {
+    console.error(`\n${acc.message}\n`);
+    process.exit(1);
+  }
+  if (acc.warning) console.error(`\x1b[33m${acc.warning}\x1b[0m`);
+  return acc.user || null;
+}
+
+function openBrowser(url) {
+  const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
+  const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+  spawn(cmd, args, { stdio: 'ignore', detached: true }).on('error', () => {}).unref();
+}
+
+function listen(server, port, host) {
+  return new Promise((ok, err) => {
+    server.once('error', err);
+    server.listen(port, host, () => ok(server.address().port));
+  });
+}
+
+async function start(kind, opts, arg) {
+  const user = await gate('session');
+  const storeDir = resolve(opts.store);
+  const time = () => new Date().toTimeString().slice(0, 8);
+  const log = (msg) => console.log(`\x1b[2m${time()}\x1b[0m ${msg}`);
+  let server;
+  if (kind === 'serve') {
+    const root = resolve(arg || '.');
+    const info = await stat(root).catch(() => null);
+    if (!info?.isDirectory()) fail(`not a directory: ${root}`);
+    server = createRedlineServer({ root, storeDir, log });
+  } else {
+    if (!arg) fail('proxy needs a target URL, e.g. redline proxy http://localhost:5173');
+    let target;
+    try {
+      target = new URL(/^https?:\/\//.test(arg) ? arg : `http://${arg}`);
+    } catch {
+      fail(`invalid URL: ${arg}`);
+    }
+    server = createRedlineServer({ target: target.origin, storeDir, log });
+  }
+  const port = await listen(server, Number(opts.port), opts.host).catch((e) =>
+    fail(e.code === 'EADDRINUSE' ? `port ${opts.port} is in use — try --port ${Number(opts.port) + 1}` : e.message),
+  );
+  const url = `http://${opts.host === '0.0.0.0' ? 'localhost' : opts.host}:${port}/`;
+  console.log(`\n  \x1b[1;31mRedline\x1b[0m  ${kind === 'serve' ? `serving ${resolve(arg || '.')}` : `proxying ${arg}`}`);
+  console.log(`  \x1b[1m${url}\x1b[0m`);
+  console.log(`  feedback → ${storeDir}/FEEDBACK.md`);
+  if (user) console.log(`  \x1b[2msigned in as ${user.email}\x1b[0m`);
+  const local = /^(127\.|localhost$|::1$)/.test(opts.host);
+  // On this machine you need no key. Anyone else does: the owner link gives everything,
+  // the Check link only verdicts. Both change every time Redline starts.
+  if (!local) console.log(`  \x1b[2myou, from another machine →\x1b[0m ${url}?rk=${server.keys.owner}`);
+  console.log(`  \x1b[2mshare Check (verdicts only) →\x1b[0m ${url}?redline=check&rk=${server.keys.review}${local ? '  \x1b[2m(add --host 0.0.0.0 to open it from another machine)\x1b[0m' : ''}\n`);
+  console.log('  In the page: P draw on anything, or click it to say why · Send to your agent · Check what comes back\n');
+  if (opts.open) openBrowser(url);
+  // --cloud: mirror this project to your account, for the hosted MCP server.
+  let sync = null;
+  if (opts.cloud) {
+    const { key, server: account } = await currentAccount();
+    if (!key) fail('--cloud needs an account: redline login <your-key>');
+    const project = (opts.project || basename(process.cwd())).slice(0, 120);
+    sync = startSync({ store: server.store, storeDir, server: account, key, project, log });
+    console.log(`  \x1b[1mcloud\x1b[0m    syncing as project “${project}” · hosted MCP: ${account}/api/mcp\n`);
+  }
+  const stop = () => (sync && sync.stop(), server.close(() => process.exit(0)));
+  process.on('SIGINT', stop);
+  process.on('SIGTERM', stop);
+}
+
+async function demo(opts) {
+  await gate('demo');
+  const time = () => new Date().toTimeString().slice(0, 8);
+  const log = (msg) => console.log(`\x1b[2m${time()}\x1b[0m ${msg}`);
+  const { server, ready } = await startDemo({ port: Number(opts.port), host: opts.host, log }).catch((e) =>
+    fail(e.code === 'EADDRINUSE' ? `port ${opts.port} is in use — try --port ${Number(opts.port) + 1}` : e.message),
+  );
+  const stop = () => server.close(() => process.exit(0));
+  process.on('SIGINT', stop);
+  process.on('SIGTERM', stop);
+  const url = `http://${opts.host === '0.0.0.0' ? 'localhost' : opts.host}:${server.address().port}/`;
+  console.log(`\n  \x1b[1;31mRedline\x1b[0m  demo: a first draft, and your agent's first round of fixes`);
+  if (server.shots.available) console.log('  Taking the before screenshots…');
+  await ready;
+  console.log(`\n  \x1b[1m${url}\x1b[0m`);
+  console.log('  Round 1 is back. Press \x1b[1mReview\x1b[0m: accept or redo each fix, and see what the guards caught.');
+  console.log('  Then draw on anything with P, or click it to say why, and press Send.\n');
+  if (opts.open) openBrowser(url);
+}
+
+// Guards, headless: photograph every approval again and compare it with how it was
+// approved, at every width it's guarded at. Records nothing. For the agent before it
+// closes a round, and for CI: exits 1 if any approval changed or is gone.
+async function verify(opts, dir) {
+  const storeDir = resolve(opts.store);
+  let where;
+  if (opts.url) {
+    try {
+      where = { target: new URL(/^https?:\/\//.test(opts.url) ? opts.url : `http://${opts.url}`).origin };
+    } catch {
+      fail(`invalid URL: ${opts.url}`);
+    }
+  } else {
+    const root = resolve(dir || '.');
+    if (!(await stat(root).catch(() => null))?.isDirectory()) fail(`not a directory: ${root}`);
+    where = { root };
+  }
+  const v = await openVerifier({ ...where, storeDir });
+  const done = async (code) => {
+    await v.close();
+    process.exit(code);
+  };
+  if (!v.shots.available) {
+    console.error('redline: verify needs Chrome or Chromium (set CHROME_PATH) and Node 22+');
+    return done(2);
+  }
+  const count = (await v.store.all()).filter(isGuarded).length;
+  if (!count) {
+    console.log('No approvals to verify yet: mark something green, or accept a fix, first.');
+    return done(0);
+  }
+  console.log(`\n  \x1b[1;31mRedline\x1b[0m  verifying ${count} approval${count === 1 ? '' : 's'}\n`);
+  const { lines, summary, bad } = describeVerify(await verifyApprovals(v), { storeDir: opts.store, color: true });
+  console.log(lines.join('\n'));
+  console.log(`\n  ${summary}\n`);
+  return done(bad ? 1 : 0);
+}
+
+async function main() {
+  const { values: opts, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      port: { type: 'string', short: 'p', default: '4545' },
+      host: { type: 'string', default: '127.0.0.1' },
+      open: { type: 'boolean', default: false },
+      store: { type: 'string', default: '.redline' },
+      json: { type: 'boolean', default: false },
+      all: { type: 'boolean', default: false },
+      page: { type: 'string' },
+      note: { type: 'string', short: 'n', default: '' },
+      out: { type: 'string', short: 'o' },
+      file: { type: 'string', short: 'f' },
+      target: { type: 'string' },
+      url: { type: 'string' },
+      server: { type: 'string' },
+      cloud: { type: 'boolean', default: false },
+      project: { type: 'string' },
+      round: { type: 'string' },
+      timeout: { type: 'string' },
+      md: { type: 'boolean', default: false },
+      summary: { type: 'string' },
+      reading: { type: 'string' },
+      question: { type: 'string', multiple: true },
+      help: { type: 'boolean', short: 'h', default: false },
+    },
+  });
+  const [cmd, ...args] = positionals;
+  if (opts.help || !cmd) return console.log(HELP);
+  const store = new Store(resolve(opts.store));
+
+  switch (cmd) {
+    case 'serve':
+    case 'proxy':
+      return start(cmd, opts, args[0]);
+
+    case 'demo':
+      return demo(opts);
+
+    case 'verify':
+      return verify(opts, args[0]);
+
+    case 'report': {
+      const model = reportModel(await store.all(), await store.rounds(), opts.round);
+      if (!model) fail('no round to report yet: send one first');
+      if (opts.md) return process.stdout.write(reportMarkdown(model, { storeDir: opts.store }));
+      const out = resolve(opts.out || `${opts.store}/report-round-${model.round.n}.html`);
+      await writeFile(out, await reportHtml(model, { storeDir: resolve(opts.store) }));
+      return console.log(`wrote ${out} (one file, images inside: send it to anyone)`);
+    }
+
+    case 'feedback': {
+      let list = await store.list(opts.page);
+      if (opts.json) {
+        if (!opts.all) list = list.filter((a) => a.status !== 'resolved');
+        return console.log(JSON.stringify(list, null, 2));
+      }
+      return process.stdout.write(formatMarkdown(list, { cli: true, includeResolved: opts.all, rounds: (await store.rounds()).rounds, taste: await store.taste() }));
+    }
+
+    // Blocks until the reviewer presses Send (or returns at once if a round is already
+    // waiting), then prints the brief. Run it in the background and the agent is woken
+    // when it exits: wait → fix → done → wait.
+    case 'wait': {
+      const secs = Number(opts.timeout || 0);
+      if (!Number.isFinite(secs) || secs < 0) fail(`invalid --timeout: ${opts.timeout}`);
+      const stop = new AbortController();
+      process.on('SIGINT', () => stop.abort());
+      process.on('SIGTERM', () => stop.abort());
+      if (!(await store.pendingRound())) console.error(`waiting for the reviewer to send a round (${secs ? `up to ${secs}s` : 'no time limit'})…`);
+      const round = await store.waitForRound({ timeoutMs: secs * 1000, signal: stop.signal });
+      if (!round) {
+        console.log(stop.signal.aborted ? 'stopped waiting' : `no round yet after ${secs}s: run \`redline wait\` again to keep waiting`);
+        process.exit(2);
+      }
+      const list = (await store.list()).filter((a) => a.status !== 'resolved' && !a.accepted && !a.draft);
+      if (opts.json) return console.log(JSON.stringify({ round, items: list }, null, 2));
+      console.log(`Round ${round.n} is here: ${round.count} item${round.count === 1 ? '' : 's'} sent at ${round.sentAt}.\n`);
+      return process.stdout.write(formatMarkdown(list, { cli: true, rounds: (await store.rounds()).rounds, taste: await store.taste() }));
+    }
+
+    case 'resolve':
+    case 'reopen': {
+      if (!args.length) fail(`${cmd} needs at least one id (see \`redline feedback\`)`);
+      const all = await store.all();
+      for (const ref of args) {
+        // Accept the id (a_1b2c3d4e) or the number shown on the pin (#3 / 3).
+        const a = all.find((x) => x.id === ref) || all.find((x) => String(x.n) === ref.replace(/^#/, ''));
+        if (!a) fail(`no feedback item ${ref}`);
+        if (cmd === 'resolve') await store.resolve(a.id, opts.note, opts.target);
+        else await store.update(a.id, { status: 'open' });
+        console.log(`${cmd === 'resolve' ? '✓ resolved' : '↺ reopened'} #${a.n} (${a.id})`);
+      }
+      return;
+    }
+
+    case 'reply': {
+      if (!args[0] || !args[1]) fail('usage: redline reply <id> "your answer"');
+      const a = await store.agentSays(args[0], args.slice(1).join(' '));
+      return console.log(`replied on #${a.n}`);
+    }
+
+    case 'send': {
+      const round = await store.send();
+      return console.log(round ? `sent round ${round.n} (${round.count} items)` : 'nothing to send');
+    }
+
+    case 'done': {
+      const round = await store.finishRound({ summary: opts.summary || '', reading: opts.reading || '', questions: opts.question || [] });
+      return console.log(`closed round ${round.n}; the reviewer sees your report`);
+    }
+
+    case 'variants': {
+      if (!args[0] || !opts.file) fail('usage: redline variants <id> --file options.json');
+      let list;
+      try {
+        list = JSON.parse(await readFile(opts.file, 'utf8'));
+      } catch (err) {
+        fail(`could not read ${opts.file}: ${err.message}`);
+      }
+      const a = await store.proposeVariants(args[0], list);
+      return console.log(`proposed ${a.variants.length} options for #${a.n}: ${a.variants.map((v) => `${v.key} ${v.label}`).join(', ')}`);
+    }
+
+    case 'clear': {
+      const n = await store.prune((a) => opts.all || a.status === 'resolved');
+      return console.log(`removed ${n} item${n === 1 ? '' : 's'}`);
+    }
+
+    case 'bundle': {
+      const js = buildClient();
+      if (!opts.out) return process.stdout.write(js);
+      await writeFile(opts.out, js);
+      return console.log(`wrote ${opts.out} — add <script src="${opts.out}"></script> to any page`);
+    }
+
+    case 'mcp':
+      // Stdout is the protocol: an account problem is told through the tools instead.
+      return runMcpServer({ storeDir: resolve(opts.store), account: requireAccount('mcp', { client: 'redline mcp' }) });
+
+    case 'login': {
+      const user = await login(args[0], { server: opts.server }).catch((err) => fail(err.message));
+      return console.log(`✓ Signed in as ${user.email}. Saved in ${credentialsPath()}\n  Next: redline demo --open`);
+    }
+
+    case 'logout': {
+      await forget();
+      return console.log('Signed out: the saved key is gone from this machine (revoke it in your account page to stop it everywhere).');
+    }
+
+    case 'whoami': {
+      const { key, server, fromEnv } = await currentAccount();
+      if (!key) fail(`not signed in. Run: redline login <your-key>  (make one at ${server})`);
+      const v = await verifyKey({ key, server });
+      if (!v.ok) fail(v.message);
+      return console.log(`${v.user.email} (${v.user.name}) · key ${v.key.start}… on ${server}${fromEnv ? ' · from REDLINE_API_KEY' : ''}`);
+    }
+
+    case 'init': {
+      const dest = resolve('.claude/commands/redline.md');
+      await mkdir(resolve('.claude/commands'), { recursive: true });
+      await copyFile(new URL('../integrations/claude-code/redline.md', import.meta.url), dest);
+      console.log(`added ${dest}\nIn Claude Code, run /redline to apply the feedback from the overlay.`);
+      return;
+    }
+
+    default:
+      fail(`unknown command "${cmd}"\n\n${HELP}`);
+  }
+}
+
+main().catch((err) => fail(err.message));