bottleship 0.1.0-prototype.0 → 0.1.0-prototype.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bottleship",
-  "version": "0.1.0-prototype.0",
-  "description": "Run coding agents in remote sandboxes, like subagents, from your local coding agent.",
+  "version": "0.1.0-prototype.2",
+  "description": "Coding agents in boxes: isolated dev environments for your repo, run by your local agent.",
   "license": "MIT",
   "author": "Joshua Knauber",
   "type": "module",
@@ -11,21 +11,17 @@
   "files": [
     "bin",
     "dist/src",
-    "dist/presets",
     "presets",
+    "review-app",
+    "!review-app/node_modules",
+    "!review-app/dist",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
-  "exports": {
-    ".": {
-      "types": "./dist/src/types.d.ts",
-      "default": "./dist/src/types.js"
-    }
-  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p review-app/tsconfig.json",
     "test": "npm run build && vitest run",
     "prepare": "npm run build",
     "release": "node scripts/release.mjs"
@@ -39,10 +35,7 @@
     "vitest": "^3.2.7"
   },
   "dependencies": {
-    "@clack/prompts": "^0.11.0",
-    "@daytonaio/sdk": "^0.231.1",
-    "e2b": "^2.63.0",
-    "modal": "^0.11.1"
+    "@clack/prompts": "^0.11.0"
   },
   "publishConfig": {
     "access": "public"

package/presets/agents/claude.json

@@ -4,9 +4,5 @@
   "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", "hint": "paste the long-lived token `claude setup-token` prints; it uses your Claude subscription" }
-  }
+  "login": { "env": "CLAUDE_CODE_OAUTH_TOKEN", "store": "claude", "command": "claude setup-token", "hint": "paste the long-lived token `claude setup-token` prints; it uses your Claude subscription" }
 }

package/presets/agents/codex.json

@@ -2,14 +2,5 @@
   "install": ["command -v codex >/dev/null || npm install -g --silent @openai/codex"],
   "run": "codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check -- {prompt}",
   "resume": "codex exec resume --last --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check -- {prompt}",
-  "login": {
-    "routes": ["device", "token"],
-    "use": "device",
-    "device": {
-      "command": "codex login --device-auth",
-      "status": "codex login status",
-      "setup": "in ChatGPT, open Settings, Security and turn on device code login for Codex"
-    },
-    "token": { "env": "CODEX_API_KEY", "store": "openai", "hint": "create an OpenAI API key at https://platform.openai.com/api-keys and paste it; it bills to the API, not your ChatGPT plan" }
-  }
+  "login": { "env": "CODEX_API_KEY", "store": "openai", "hint": "create an OpenAI API key at https://platform.openai.com/api-keys and paste it; it bills to the API, not your ChatGPT plan" }
 }

package/presets/agents/cursor.json

@@ -2,13 +2,5 @@
   "install": ["command -v cursor-agent >/dev/null || { curl -fsS https://cursor.com/install | bash; command -v cursor-agent >/dev/null; }"],
   "run": "cursor-agent -p --force --trust --sandbox disabled --output-format text -- {prompt}",
   "resume": "cursor-agent -p --continue --force --trust --sandbox disabled --output-format text -- {prompt}",
-  "login": {
-    "routes": ["token", "device"],
-    "use": "token",
-    "token": { "env": "CURSOR_API_KEY", "store": "cursor", "hint": "create an API key at https://cursor.com/dashboard/api and paste it; it bills to your Cursor plan" },
-    "device": {
-      "command": "NO_OPEN_BROWSER=1 cursor-agent login",
-      "status": "! cursor-agent status 2>&1 | grep -qi 'not logged in'"
-    }
-  }
+  "login": { "env": "CURSOR_API_KEY", "store": "cursor", "hint": "create an API key at https://cursor.com/dashboard/api and paste it; it bills to your Cursor plan" }
 }

package/presets/agents/opencode.json

@@ -2,18 +2,5 @@
   "install": ["command -v opencode >/dev/null || npm install -g --silent @opencode/cli"],
   "run": "opencode run --standalone --auto -- {prompt}",
   "resume": "opencode run --standalone --continue --auto -- {prompt}",
-  "login": {
-    "routes": ["none", "device", "token"],
-    "use": "none",
-    "device": {
-      "command": "opencode auth login openai --method chatgpt-headless --standalone",
-      "status": "opencode auth list --standalone --format json | grep -q '\"openai\"'"
-    },
-    "token": { "env": "OPENCODE_API_KEY", "store": "opencode", "hint": "sign in at https://opencode.ai/console, copy your API key (OpenCode Zen) and paste it" },
-    "tokens": [
-      { "env": "OPENCODE_API_KEY", "store": "opencode", "hint": "OpenCode Zen: sign in at https://opencode.ai/console, copy your API key and paste it" },
-      { "env": "ANTHROPIC_API_KEY", "store": "anthropic", "hint": "an Anthropic API key (not a Claude subscription) from https://console.anthropic.com/settings/keys" },
-      { "env": "OPENAI_API_KEY", "store": "openai", "hint": "an OpenAI API key from https://platform.openai.com/api-keys" }
-    ]
-  }
+  "login": { "env": "OPENCODE_API_KEY", "store": "opencode", "hint": "sign in at https://opencode.ai/console, copy your API key (OpenCode Zen) and paste it" }
 }

package/presets/providers/docker/create

@@ -0,0 +1,12 @@
+# create <id> <dockerfile> <image>: builds the image once per Dockerfile, then runs the box as a container that lives until destroy.
+# Ports the image EXPOSEs are published on 127.0.0.1 only, each on a free port of this machine.
+set -euo pipefail
+id=$1 dockerfile=$2 image=$3
+if ! docker image inspect "$image" >/dev/null 2>&1; then
+  docker build -q -t "$image" - < "$dockerfile" >/dev/null
+fi
+publish=()
+for p in $(docker image inspect -f '{{range $p, $_ := .Config.ExposedPorts}}{{$p}} {{end}}' "$image"); do
+  publish+=(-p "127.0.0.1::${p%/*}")
+done
+docker run -d --name "$id" --label bottleship=1 ${publish[@]+"${publish[@]}"} --entrypoint sleep "$image" infinity >/dev/null

package/presets/providers/docker/destroy

@@ -0,0 +1,2 @@
+# destroy <id>: removes the container; the image stays as the cache for the next box
+docker rm -f "$1" >/dev/null 2>&1 || true

package/presets/providers/docker/exec

@@ -0,0 +1,2 @@
+# exec <id> <script>: runs the script in the box as its user, stdin passed through
+exec docker exec -i "$1" bash -c "$2"

package/presets/providers/docker/list

@@ -0,0 +1,4 @@
+# list: the boxes bottleship made here, one per line: <id> <created, ISO 8601>
+set -euo pipefail
+ids=$(docker ps -aq --filter label=bottleship=1)
+[ -z "$ids" ] || docker inspect -f '{{.Name}} {{.Created}}' $ids | sed 's|^/||'

package/presets/providers/docker/status

@@ -0,0 +1,2 @@
+# status <id>: running or gone
+if [ "$(docker inspect -f '{{.State.Running}}' "$1" 2>/dev/null)" = true ]; then echo running; else echo gone; fi

package/presets/providers/docker/url

@@ -0,0 +1,4 @@
+# url <id> <port>: where the box's port is published on this machine
+set -euo pipefail
+hostport=$(docker port "$1" "$2/tcp" | head -1)
+echo "http://127.0.0.1:${hostport##*:}"

package/review-app/KIT.md

@@ -0,0 +1,106 @@
+# The review kit
+
+A review is a tour of one change: the **overview** says what it is about, the **chapters** show it happening, and **changes** show the code in the same order. You write `src/review.tsx`; the frame (`src/App.tsx`) and the kit (`src/kit`) are shared by every review. Every review should look like the same product, so build from the kit and keep to the rules below.
+
+`examples/rply-16.tsx` is a backend change shown with flows; read it before you start.
+
+## The shape
+
+```tsx
+export default defineReview({
+  instances: [
+    { id: "base", label: "Base", detail: "main", port: 7781 },
+    { id: "head", label: "Head", detail: "this PR", port: 8080 },
+  ],
+  overview: () => <Overview>…</Overview>,
+  chapters: [{ id: "blocks-loopback", title: "A loopback page is blocked", page: () => <Chapter …/> }],
+  groups: [{ id: "core", title: "Embedded IPv4 is judged as IPv4", why: "…", chapter: "blocks-loopback", file: "src/unfurl.ts", lines: [[79, 107]] }],
+});
+```
+
+- `label` is always short: `Base`, `Head`, or the name of a variant. Put what sets an instance apart in `detail` ("main", "this PR, Hebrew"), never in the label.
+- `path` opens the instance on a page other than `/`, e.g. `/?lng=he-IL`.
+
+## Overview
+
+In this order, inside `<Overview>` (it adds the title, the PR line, the files and the way into the tour):
+
+1. `<Lead>`: one sentence on what the change does for the people who use it. Not how.
+2. `<BeforeAfter before after>`: the behaviour before and after, in two or three plain sentences each.
+3. One picture of where it happens: a `<Compare title>` of the changed part for a visible change, or a `<Card caption><Flow def/></Card>` for an invisible one.
+4. `<Attention items held>`: 2 to 4 things that deserve a close look, each linked with `to` to the chapter or group that shows it. Check every claim made about the change (description, comments, reviews, bots) in the box. A claim that does not fully hold is an item too, with `claim: { source, quote, status }` instead of `text`: `status` is `fail` (does not hold) or `neutral` (partly, or out of scope; `label` names it, e.g. "Known, out of scope"), and `detail` says what you found. Claims that hold go in `held` as `{ source, quote, to }`.
+
+## Chapters
+
+3 to 6, the core behaviour first, then edge cases, then that nothing else broke. A chapter title says what happens ("A loopback page is blocked"), not what you test ("Test the guard").
+
+No chapter just to run the tests; CI does that. Run the PR's tests against base too and put what you find in `<Attention>`: that they fail on base is a held claim, and a test that checks less than it looks is an item. A test chapter is for a PR without CI, or when the output itself is the evidence.
+
+```tsx
+<Chapter title="…" step="blocks-loopback" expect={{ base: "Returns the internal page.", head: "Returns no title." }} flow={ssrf} here="guard" group="core" evidence={…}>
+  One or two sentences: what the step does and why it matters.
+</Chapter>
+```
+
+- `expect` says what should happen on each instance before the reviewer presses Run. Each instance's last `ok` or `fail` event is shown under it as the result, so make that event's `text` (or its overlay `title`) a short statement of what came out: "Order is − 100% +", "Test fails".
+- `step` is `~/review/steps/<step>.sh`. Leave it out when there is nothing to run.
+- `flow` and `here` list the flow's parts beside the chapter, with a column per instance showing what the step's events did at each part; `here` is the part the chapter is about.
+- `group` links the code behind the chapter.
+
+### Evidence
+
+`evidence` is what fills the right side. Pick by what the change is:
+
+| The change | Evidence |
+|---|---|
+| Visible in the UI | `<Live />` first, then a `<Compare title>` per state that matters (each locale, theme, hover, empty, error, narrow). |
+| Behaviour you cannot see (auth, caching, jobs) | Leave `evidence` out: the live apps fill the side, overlays show what came out, and the chapter's `flow` shows the path. |
+| Tests, scripts, API calls | `<Outcome />`: each instance's output, from the overlay `body`. Use it only when that output is worth reading; the result itself already shows in the guide. |
+| Mixed | `<Live />` or `<Outcome />` first, then screenshots. |
+
+Without `evidence` the live instances fill the side. With it, the side scrolls and keeps the order you give.
+
+## Screenshots
+
+Take them with `node scripts/shot.cjs` (options at the top of the file), into `~/review/shots`.
+
+- Crop to the part that changed (`--selector`, `--pad 24`) and outline it (`--highlight`). Whole pages only when the layout is the point.
+- Take base and head with the same viewport, scheme, locale and actions, so a comparison only shows the change.
+- Name them `base-<what>.png` and `head-<what>.png`.
+- `<Compare base head title caption>`: `title` names the state in two to four words ("Arabic", "Hovering −", "Dark theme"). `caption` is one sentence on what to notice. Use `mode="diff"` to prove nothing changed.
+- `<Shot src title caption>` for a single picture.
+
+## Clips
+
+A clip is a short recording, for what a still cannot show: a flow of several steps (a form across pages, a drag, an undo), motion (a transition, an animation, a loading state), or timing (a debounce, a toast that disappears). If one screenshot of the end state says it, take the screenshot.
+
+Record with `node scripts/clip.cjs` (options at the top of the file): the page, then each action at a person's pace, with a cursor drawn in. It prints the `src` to use.
+
+- 3 to 10 seconds: start where the flow starts, end once the result has shown.
+- Record base and head with the same viewport, scheme, locale and actions, then `<Clip base head title caption>` plays them side by side, in step. `<Clip src title caption>` for one.
+- Name them `base-<what>.webm` and `head-<what>.webm`. Pair a clip with a screenshot of the end state when the reviewer needs to look closely.
+
+## Flows
+
+Nodes sit on a grid (`col`, `row` from 0). Keep a flow to 3 to 6 nodes, in one or two rows, read left to right. Titles are the names in the code (`assertPublic`); `sub` is a detail in mono (`isPrivate(address)`). Mark the nodes the change touches with `changed`. Review hooks light it with events: `flow: { id, edge: [from, to] }` moves a dot, `flow: { id, node, status, label }` colors a node and labels it.
+
+## Groups
+
+The diff, split into the parts the tour talks about, in tour order: the core change first, glue next, tests last. `title` names the part; `why` is one sentence on why it exists; `lines` are new-file line ranges. Files you do not group are listed after the groups on their own.
+
+## Writing
+
+[WRITING.md](WRITING.md) says how to write every piece of text in a review: the overview, chapters, `expect`, step results, captions, Attention, groups, and your answers in the chat. Read it before you write the tour. In short:
+
+- Sentence case everywhere. No exclamation marks, no emoji.
+- Short: a lead is one sentence, a `why` is one sentence, a caption is one sentence.
+- Plain words about behaviour for the people who use it. The real code names, in `<code>`, when the reviewer needs them.
+- Show, do not grade: your view belongs only in Attention.
+
+## When the kit does not fit
+
+Write a component next to `review.tsx` with the kit's classes and tokens (`.card`, `.fig`, `.list`, `.rows`, `var(--line)`). Type has six sizes (`--fs-xl` titles, `--fs-lg` lead, `--fs` body, `--fs-sm` secondary, `--fs-mono` code, `--fs-xs` badge glyphs), two weights (400, 500) and three text colors (`--text`, `--text-2`, `--text-3`); dim with a color, never with opacity. No inline colors, sizes or one-off spacing. If you change `src/App.tsx` or `src/kit`, say what and why in your summary.
+
+## Check
+
+`npm run check` typechecks, builds, opens every page in Chromium and fails on errors and broken images. Look at the page screenshots it saves in `~/review/checks`, as the reviewer will see them, and fix what reads badly.

package/review-app/WRITING.md

@@ -0,0 +1,93 @@
+# Writing the review
+
+Everything you write in a review is read by a reviewer between other work: the overview, chapters, captions, step results, group reasons, your answers in the chat, and any comment the reviewer asks you to leave. Write so they understand it on the first read.
+
+Three rules sit above the rest:
+
+- **Cut every word that does no work.** If the sentence survives without a word, the word goes. "In order to" is "to". "It is important to note that" is nothing.
+- **Use the short, everyday word.** "Use", not "utilize". "Help", not "facilitate". "Do", not "perform".
+- **When a rule makes a sentence worse, fix the sentence another way or leave it alone.** A sentence that follows every rule and sounds machine-written has failed.
+
+## Name things as the code does
+
+The codebase is the word list. Write the real function, file, flag, table, or command, in code font: `emailUnread`, `RPLY_UNREAD_EMAILS`, `unread_emails`. Do not describe it ("the email helper") or rename it.
+
+Do not invent jargon. Use the words a developer says out loud. Call each thing by one name everywhere: if a chapter says "the sweep", the groups and the chat say "the sweep" too.
+
+For the people who use the product (the lead, before and after), describe behaviour in their words instead: "you get one email", not "`emailUnread` sends".
+
+## Give each part of the tour one job
+
+The tour shows the change. It does not grade it. Say what is true, what happens, and what to look at. Your view belongs only in Attention, as what deserves a close look and why.
+
+- **Lead.** One sentence on what the change does for the people who use it. Behaviour, not mechanism: "Users who never turned on notifications get one email a day about unread agent messages."
+- **Before and after.** Two or three plain sentences each, about what a person sees or gets. No code.
+- **Chapter text.** Why this matters and what the step does, in one or two sentences. Name the condition that makes it interesting: "Two messages are 31 minutes old and one is fresh. Only the old ones count."
+- **What should happen (`expect`).** Dry and checkable, one per instance, so the reviewer can compare it with the result: "No email." "One email, subject `You have 2 unread messages in rply`." No hedging and no explanation here.
+- **Step results (overlay title and body).** The result as a fact: the title in a few words ("Blocked, nothing fetched"), the body with what you saw. Quote real output instead of describing it.
+- **Captions and figure titles.** The title names the state in two to four words ("Arabic", "Dark theme"). The caption says what to notice in one sentence: "Base mirrors the controls. Head keeps − 100% +."
+- **Attention.** Specific and concrete: the place, the condition, and the consequence. "A silent message counts as unread, but the app's badge skips it, so the email can say 2 where the badge says 1." For a claim: who said it, what they said, and what you found in the box.
+- **Group `why`.** One sentence on why that part of the diff exists.
+
+## Answer in the chat like a briefing
+
+- Answer first, in the first sentence. Then the evidence: what you ran, what came out, the file and line.
+- Say what you changed and where, with the commit. Say plainly when you changed nothing.
+- Keep it short enough to read in under a minute. Link logs and long output; do not paste them.
+- When the answer is a change to lines in the diff, give it as a suggestion block for those lines.
+- A comment the reviewer asks you to leave on GitHub is in their name: one point per comment, written as they would say it to the author.
+
+## Write sentences to the reader
+
+- Use the present tense. "Will" only for things that happen later.
+- Say who does what: "the sweep skips the user", not "the user is skipped".
+- Put the condition before the result: "If the user has a push subscription, no email goes out."
+- Put the common case first and exceptions after.
+- One thought per sentence. Split a sentence that carries two. Split anything over about 25 words.
+- Keep "the" and "a", and the small words that show structure. Do not compress into fragments or arrows: "Parser rejects bad date → exit 2" is "The parser rejects a bad date and exits with code 2."
+- Keep "only" and "not" next to the word they change.
+- Make every "it", "this", and "they" point at one obvious thing. Repeat the noun when in doubt.
+- Use periods, not semicolons or dashes. No slashes ("a, b, or both", not "a/b"). No "etc.": say up front that a list is partial.
+- Sentence case everywhere: headings, titles, labels. No exclamation marks, no emoji.
+
+## Vary the rhythm and be specific
+
+A text can obey every rule and still read machine-written: every sentence clipped short, nothing specific.
+
+- Mix sentence lengths. Short sentences land a point. Longer ones carry a fact with its condition.
+- Be specific over sterile. Not "edge cases may cause issues" but "a user who reads everything between two sweeps gets no email".
+- Prefer a number to an adverb: "after 31 minutes", "one email a day", "3 of 4 checks pass".
+- If a sentence could appear unchanged in another review, it says nothing about this one. Cut it.
+
+## Cut these on sight
+
+- **AI vocabulary:** additionally, crucial, delve, enhance, robust, seamless, comprehensive, leverage, utilize, pivotal, showcase, underscore, ensure (as filler), landscape, tapestry, testament.
+- **Fancy ways to say "is":** "serves as", "stands as", "boasts", "features". Say "is" or "has".
+- **"Not just X, but Y"**, forced groups of three, and false ranges ("from X to Y" with no scale between them).
+- **Filler and hedging:** "it is worth noting", "basically", "essentially", "could potentially", "might possibly".
+- **Chatbot phrases:** "Great question", "I hope this helps", "Let me know if", "Certainly". Answer directly.
+- **Abstract metaphors:** surface (for API), wedge, vector, primitive, harness, scaffolding, north star, flywheel, ratchet. Name the concrete thing.
+- **Feelings instead of mechanisms:** "the flow feels solid" says nothing. "Each step finished and posted its result on both instances" does.
+- **Bold labels that restate the line** ("**Performance:** Performance improved") and bold on every term.
+
+## Example
+
+Before:
+
+> This chapter essentially showcases how the new unread email functionality robustly handles various edge cases, ensuring that users are only notified when appropriate.
+
+After:
+
+> A user with two 31-minute-old unread messages gets one email. A user whose messages are 5 minutes old, or who has push turned on, gets none.
+
+---
+
+Adapted from the `technical-writing` and `unslop` skills in [cursor/plugins](https://github.com/cursor/plugins) (pstack), under the MIT License:
+
+> Copyright (c) 2026 Lauren Tan
+>
+> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+>
+> The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/review-app/examples/rply-16.tsx

@@ -0,0 +1,98 @@
+// A complete review, for joshuaKnauber/rply#16: a backend fix with no visible UI, so the evidence is flows and overlays.
+// To try it with the sample data in src/data, copy it over src/review.tsx and change the imports to "./kit".
+import { Attention, BeforeAfter, Card, Chapter, defineReview, Flow, Lead, Outcome, Overview, type FlowDef } from "../src/kit";
+
+const UNFURL = "packages/server/src/routes/unfurl.ts";
+
+const ssrf: FlowDef = {
+  id: "ssrf",
+  title: "Link preview request path",
+  nodes: [
+    { id: "route", title: "GET /v1/unfurl", sub: "authenticated member", col: 0, row: 0 },
+    { id: "guard", title: "assertPublic", sub: "isPrivate(address)", col: 1, row: 0 },
+    { id: "internal", title: "Loopback / metadata", sub: "127.0.0.1:9199", col: 2, row: 0 },
+  ],
+  edges: [["route", "guard"], ["guard", "internal"]],
+  changed: ["guard"],
+};
+
+export default defineReview({
+  instances: [
+    { id: "base", label: "Base", detail: "main", port: 7781 },
+    { id: "head", label: "Head", detail: "this PR", port: 8080 },
+  ],
+
+  overview: () => (
+    <Overview>
+      <Lead>Link previews can no longer reach the server's own network through IPv6 spellings of private addresses.</Lead>
+      <BeforeAfter
+        before={<>The guard only stripped a dotted <code>::ffff:</code> prefix. URL parsing turns <code>[::ffff:127.0.0.1]</code> into <code>[::ffff:7f00:1]</code>, which looked public, so the server fetched its own loopback and returned the page.</>}
+        after="The guard reads every address as eight 16-bit groups, judges IPv6 that embeds IPv4 as that IPv4, and blocks private ranges before any fetch. Addresses it cannot parse are blocked too."
+      />
+      <Card caption="Dashed: changed in this PR. The tour lights it up on base and head.">
+        <Flow def={ssrf} />
+      </Card>
+      <Attention
+        items={[
+          { text: "Addresses the parser cannot read now count as private", detail: "Failing closed is right for a guard, but any odd resolver output now blocks a preview.", to: { group: "core" } },
+          { claim: { source: "PR description", quote: "The guard now parses each address and rejects the full loopback, link-local, unique-local, multicast, mapped, and NAT64 ranges before it fetches.", status: "neutral", label: "Mostly true" }, detail: "True for those ranges, but 6to4 (2002::/16), SIIT and 2001:db8::/32 are still treated as public, so \u201creserved\u201d in the title is broader than what is checked. None reach loopback on a normal host.", to: { chapter: "other-forms" } },
+          { text: "DNS rebinding still bypasses the guard", detail: "assertPublic and fetch resolve the host separately. The PR says so and leaves it for later." },
+        ]}
+        held={[
+          { source: "PR description", quote: "A URL whose host is an IPv4-mapped IPv6 address such as ::ffff:7f00:1 passed the private-address check, so the server connected to loopback.", to: { chapter: "mapped-loopback" } },
+          { source: "PR description", quote: "Parsing the address into groups and checking the full ranges classifies all 15 private test addresses as private and keeps the 5 public ones public.", to: { chapter: "unit-tests" } },
+        ]}
+      />
+    </Overview>
+  ),
+
+  chapters: [
+    {
+      id: "mapped-loopback",
+      title: "A loopback page through ::ffff:7f00:1",
+      page: () => (
+        <Chapter
+          title="A loopback page through ::ffff:7f00:1"
+          step="mapped-loopback"
+          expect={{ base: "Returns the internal page, titled “internal”.", head: "Returns no title. The guard blocks before any fetch." }}
+          flow={ssrf}
+          here="guard"
+          group="core"
+        >
+          Signs in as the demo user on each instance and asks for a preview of <code>http://[::ffff:7f00:1]:9199/</code>, a page only reachable on the server's loopback.
+        </Chapter>
+      ),
+    },
+    {
+      id: "other-forms",
+      title: "Other spellings of private addresses",
+      page: () => (
+        <Chapter
+          title="Other spellings of private addresses"
+          step="other-forms"
+          expect={{ base: "The mapped and NAT64 spellings pass the guard.", head: "Every spelling is blocked." }}
+          flow={ssrf}
+          here="guard"
+          group="parse"
+        >
+          Tries the metadata address in mapped hex form, dotted-mapped, the long zero form, <code>fe90::</code>, multicast <code>ff02::</code> and NAT64.
+        </Chapter>
+      ),
+    },
+    {
+      id: "unit-tests",
+      title: "The PR's own tests",
+      page: () => (
+        <Chapter title="The PR's own tests" step="unit-tests" expect={{ head: "15 private and 5 public addresses classified right, and the mapped-loopback test passes." }} group="tests" evidence={<Outcome empty="Press Run: the PR's test file runs against head." />}>
+          Runs the PR's test file against head: the address table and an end-to-end test against a real server on loopback.
+        </Chapter>
+      ),
+    },
+  ],
+
+  groups: [
+    { id: "core", title: "Embedded IPv4 is judged as IPv4", why: "The fix itself. isPrivate first asks for the IPv4 inside an IPv6 address, then checks the IPv6 ranges.", chapter: "mapped-loopback", file: UNFURL, lines: [[79, 107]] },
+    { id: "parse", title: "Addresses become numbers", why: "Prefix string checks are replaced by parsing into eight groups, so every spelling of one address is the same address.", chapter: "other-forms", file: UNFURL, lines: [[109, 128]] },
+    { id: "tests", title: "Tests", why: "An address table, and an end-to-end test against a real server on loopback.", chapter: "unit-tests", file: "packages/server/test/unfurl.test.ts", lines: [[1, 8], [49, 76]] },
+  ],
+});

package/review-app/index.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Review</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&family=Geist+Mono:wght@400;500&display=swap" rel="stylesheet">
+</head>
+<body>
+<div id="root"></div>
+<script type="module" src="/src/main.tsx"></script>
+</body>
+</html>