@levistudio/redline 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to Redline are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+- Node-compatible launcher (`bin/redline.cjs`) so `npx @levistudio/redline <file>` works alongside `bunx`.
+- `ROADMAP.md` and this changelog.
+
+### Changed
+- Package renamed to scoped `@levistudio/redline` for npm publishing.
+- README rewritten around the AI-doc-review use case.
+
+## [0.1.0] - 2026-05-09
+
+Initial public release.
+
+### Added
+- Local review reader (Bun + Hono server, browser UI) for Markdown files.
+- Inline select-to-comment with quote + 32-char-context anchoring.
+- Sidecar JSON at `.review/<filename>.json` as the source of truth for a review.
+- Per-round history snapshots at `.review/history/<file>.<iso>.md`.
+- Real-time conversation with a Claude agent over SSE — the agent replies within seconds of a comment landing.
+- Verdict-aware resolve: every agent reply ships with `requires_revision` so the round-level button auto-defaults to **Revise document** or **Accept as-is**.
+- One-shot revision command: `redline resolve <file> [--model <id>]`.
+- `redline-review` skill for outer-agent handoff (Claude Code etc.).
+- CSRF token on every mutating `/api/*` request.
+- Cross-process file lock around sidecar transactions.
+- `realpath` check on the static-asset route to block symlink escapes.
+- Per-prompt UUID envelopes around user-controlled prompt fields.
+- Auto-restart of the agent subprocess (capped to 5 restarts / 60s).
+- Auto-installs missing dependencies on first CLI run.
+- Initial test suite: server, sidecar, parsing, model-picking, rendering, diff, SSE, integration, happy-dom client.
+
+[Unreleased]: https://github.com/alevi/redline/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/alevi/redline/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alon Levi
+
+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/README.md

@@ -0,0 +1,132 @@
+# Redline
+
+**Inline comments on Markdown files, designed for human-in-the-loop AI doc review.**
+
+Open a Markdown file, highlight text, leave inline comments, discuss changes with Claude, and apply accepted revisions back to the document.
+
+![Redline demo — highlight text, leave a comment, Claude replies, resolve to apply the edit.](docs/assets/demo.gif)
+
+## Try it in 30 seconds
+
+```sh
+bunx @levistudio/redline ./spec.md
+```
+
+(or `npx @levistudio/redline ./spec.md` — Bun is required either way.)
+
+The terminal prints a `localhost` URL. Cmd-click it. Select any text in the document, type a comment, hit reply. Claude responds in the thread within ~2s. Resolve each comment, then click **Revise document** to have Claude apply the agreed edits back to the file on disk.
+
+Requires [Bun](https://bun.sh) ≥ 1.0 and an authenticated [Claude Code](https://claude.com/claude-code) session. The agent inherits your existing Claude Code OAuth — no `ANTHROPIC_API_KEY` needed.
+
+## Why Redline exists
+
+A lot of recent docs start as a Claude draft. Reviewing those drafts in a chat window is awkward. Comments scroll out from under the text. "Fix paragraph 3" loses its anchor as soon as the doc is rewritten. Google-Docs-style tools don't speak the file on disk.
+
+Redline puts an inline-comment layer on top of a local Markdown file, with a Claude agent participating in the review thread. Comments are anchored to the text they're about. The conversation is real-time. Accepted changes are applied back to the file you started with, no copy-paste.
+
+## Who it's for
+
+People shipping docs with the help of AI agents:
+
+- Engineers reviewing **AI-generated PRDs and architecture specs** before they go to a team.
+- PMs and tech leads reviewing **Claude Code / Codex / Cursor output** before merging.
+- Tech writers running a **human-in-the-loop AI doc review** on README drafts.
+- Anyone who wants **inline comments on Markdown** without uploading the file to a SaaS.
+
+## How it works
+
+Two long-lived processes:
+
+- **Server** ([src/server.ts](src/server.ts)) — renders Markdown, serves the review UI, accepts comment / reply / resolve POSTs, broadcasts SSE events.
+- **Agent** ([src/agent.ts](src/agent.ts)) — child process listening to the SSE stream. Calls `claude -p` to compose replies and post them back. When you accept a round, the agent runs the document revision pass and writes the result to disk.
+
+Review state lives in a sidecar JSON file at `.review/<filename>.json` next to the doc. History snapshots of every revision land in `.review/history/<filename>.<iso>.md` *before* the revision is written, so you can roll back from disk if a revision goes sideways. Both should be gitignored unless you want them in the repo.
+
+After each revision, the browser overlays a side-by-side diff against the previous round so you can read the agent's changes in context. From there you either open another round of comments or click **Looks good** to finish.
+
+[CLAUDE.md](CLAUDE.md) has the full architecture tour: sidecar schema, SSE event vocabulary, model picking, frontend gotchas.
+
+## Use cases
+
+- **Reviewing AI-generated PRDs.** Hand Claude Code a one-line brief, let it draft the PRD, then redline it line by line before passing it on.
+- **Reviewing architecture specs.** Mark assumptions you want challenged, ask the agent to expand sections, ship the revised spec.
+- **Reviewing README drafts.** Claude wrote your README — read through, leave inline comments where the framing is off, accept the revision in one click.
+- **Approving Claude Code output before merge.** Use the bundled [redline-review skill](skills/redline-review/SKILL.md) so your outer agent automatically hands you the doc to sign off on.
+- **Human approval loops for agent-written docs.** Anywhere an agent needs your sign-off on prose before continuing, run it through Redline.
+
+## Reviewing for a specific lens
+
+Pass `--context` at startup to tell Claude what you're focused on for the review. The context is shown in a banner above the doc and threaded into both the reply and revision prompts, so the agent can weight its responses accordingly.
+
+```sh
+bunx @levistudio/redline ./spec.md --context "Reviewing for technical accuracy, not prose style."
+bunx @levistudio/redline ./api-rfc.md --context "Looking for missing security considerations and breaking changes."
+```
+
+The context is persisted in the sidecar on first run, so it carries across rounds and is available the next time you reopen the same review.
+
+## Manual annotation (no agent)
+
+If you just want inline comments on a Markdown file without a Claude conversation, pass `--no-agent`:
+
+```sh
+bunx @levistudio/redline ./spec.md --no-agent
+```
+
+The server still runs, you can still leave comments and resolve them, but no agent process is spawned and no `claude` binary is required on your PATH. The header shows a "Manual mode" pill so the absence of replies is intentional, not broken. Useful for:
+
+- Annotating a doc you don't want sent to Claude
+- Trying Redline before configuring Claude Code
+- Quick inline-comment passes where you don't want a revision step
+
+## One-shot revision
+
+If you already have a sidecar with resolved comments and just want to apply the revision without the live UI:
+
+```sh
+bunx @levistudio/redline resolve ./spec.md
+bunx @levistudio/redline resolve ./spec.md --model claude-sonnet-4-6
+```
+
+## Outer-agent handoff (optional)
+
+Want your AI coding agent (Claude Code etc.) to invoke Redline automatically whenever it produces a Markdown doc you need to sign off on? Install the bundled skill:
+
+```sh
+git clone https://github.com/alevi/redline.git && cd redline
+./scripts/install-skill.sh
+```
+
+This copies `skills/redline-review/` into `~/.claude/skills/` with absolute paths baked in. After installation, your outer agent will reach for `redline-review` whenever it has Markdown that needs human review before it can continue.
+
+## Local-first / security
+
+- Single-player. Server binds to `127.0.0.1`. No auth, no audit log, no cloud.
+- Rendered Markdown is sanitized at the render boundary; raw HTML, inline event handlers, and `javascript:` URLs are stripped before the document reaches the browser.
+- The agent inherits your existing Claude Code OAuth session; no `ANTHROPIC_API_KEY` required.
+- **Prompt injection in document content is not defended against.** Run Redline on docs you trust.
+
+Full threat model: [SECURITY.md](SECURITY.md).
+
+## Known limitations
+
+- Markdown only. PDFs, Word docs, raw HTML — out of scope.
+- Single-player. No multi-reviewer mode, no auth, no comment-permalink sharing.
+- Single file per session. No folder mode or repo-wide review.
+- Concurrent `redline` processes on the same `.md` can corrupt the sidecar.
+- Bun required at runtime — there's no plain-Node mode.
+
+## Develop locally
+
+```sh
+git clone https://github.com/alevi/redline.git
+cd redline
+bun install
+bun link            # exposes `redline` on PATH
+redline ./sample.md
+bun test
+```
+
+## License
+
+[MIT](LICENSE).

package/ROADMAP.md

@@ -0,0 +1,39 @@
+# Roadmap
+
+This roadmap captures where Redline is heading. It's directional, not a commitment — items may move, drop, or arrive in a different shape based on what users actually hit. File an [issue](https://github.com/alevi/redline/issues) if any of this matters to you and you want to nudge the order.
+
+## Now
+
+- **Polished launch.** Scoped npm publish (`@levistudio/redline`), `npx` / `bunx` parity, GitHub Release, demo GIF that captures the magic moment, landing page.
+- **Stability under real workloads.** Long-document rendering, large sidecars, many-round sessions.
+
+## Next
+
+- **Folder / multi-doc review.** Open a directory, walk through Markdown files in sequence, share a single agent across the session.
+- **Sharper diff overlay.** Per-paragraph applied-edit indicators in the post-revision view so you can see exactly which comments translated into which edits.
+- **Comment templates.** Optional structured actions layered on top of free-text comments — `expand`, `challenge`, `cut`, `tighten` — so common requests don't need to be retyped each time.
+- **Read-only share link.** Optional, opt-in, ephemeral — lets a teammate spectate a review without write access.
+- **Editor integrations.** VS Code / Cursor / JetBrains panel that opens the review for the active Markdown file.
+
+## Later / wishlist
+
+- **Multi-reviewer mode.** Real names, threaded comments from multiple humans, conflict resolution. Big change to the threat model — explicitly out of scope for now.
+- **Agent-side initiative.** The agent flags weak claims or missing sections proactively, instead of only responding to human comments.
+- **Non-Markdown formats.** PRD review for `.docx` or `.pdf` is a separate product surface; not a near-term direction.
+
+## Known limitations
+
+These are intentional today. They're listed here so you can decide whether Redline fits before you try it.
+
+- **Markdown only.** The renderer, the diff, and the agent prompts all assume Markdown.
+- **Single-player.** No auth, no audit log, no concurrent reviewers. Designed for one human and one agent on a developer's laptop.
+- **Single file per session.** Each `redline <file>` invocation tracks one document.
+- **Local sidecar lock only.** Concurrent `redline` processes on the same `.md` can corrupt review state — don't run two sessions on the same file.
+- **Bun-only at runtime.** The Node launcher exists for `npx` ergonomics, but Bun is required for the server to run.
+- **Prompt injection in document content is not defended against.** Run on docs you trust.
+
+## Want to influence the roadmap?
+
+- Open an issue with the use case you have in mind. Concrete > abstract — "I want to redline a 12-doc spec folder before our quarterly planning" is more useful than "support folders".
+- Comment on existing issues to upvote / disagree.
+- For security issues, use [private vulnerability reporting](https://github.com/alevi/redline/security/advisories/new) instead of an issue.

package/SECURITY.md

@@ -0,0 +1,33 @@
+# Security
+
+Redline is a **single-player, localhost-only** review tool that runs on the operator's machine. Reviewed Markdown is rendered in a browser and fed to a local Claude subprocess. This document describes what is defended against, what is out of scope, and how to report issues.
+
+## Threat model
+
+**In scope.** Two threats Redline actively defends against:
+
+1. **Network exposure of the local server.** The server binds to `127.0.0.1` only — it is not reachable from other machines on the LAN, even when the user is on shared wifi. The printed `localhost` URL matches the actual bind.
+2. **XSS via the rendered Markdown.** A reviewed `.md` may contain raw HTML, inline event handlers, or `javascript:`/`data:` URLs — these are stripped at the render boundary before the document reaches the browser. Sanitization covers both the main reader and the diff overlay.
+
+**Out of scope.** Redline is a developer tool, not a sandbox. It is appropriate to run on documents you authored, generated, or trust. The following are **not** defended against:
+
+- **Adversarial Markdown trying to manipulate the agent via prompt injection.** The agent reads the document text and comment thread as input to Claude; carefully crafted content can attempt to redirect the model. Treat agent output the same way you'd treat any other AI output you didn't fully verify.
+- **Multiple `redline` processes operating on the same file.** The sidecar lock is in-process; concurrent runs on the same `.md` can corrupt review state.
+- **Malicious CLI flags or environment.** `redline` runs with the operator's full file-system permissions and shells out to `claude -p` with the operator's auth.
+- **Sharing reviews across operators.** Redline is single-player — it has no auth, no access control, and no audit log.
+
+## What "single-player, localhost" means in practice
+
+- Run Redline only on documents from sources you trust. The HTML render is sanitized; the content the agent ingests is not.
+- Don't run Redline on a multi-user machine where another user has shell access — they could read the document directly from disk and connect to your loopback port.
+- Don't expose the redline server through tunnels, reverse proxies, or `socat`. It assumes loopback semantics throughout.
+
+## Reporting a vulnerability
+
+If you find a security issue, please **do not** open a public issue. Use GitHub's [private vulnerability reporting](https://github.com/alevi/redline/security/advisories/new) — that opens a private channel for the report and a coordinated fix.
+
+For non-security bugs, regular [issues](https://github.com/alevi/redline/issues) are the right place.
+
+## Supported versions
+
+Redline is built for the latest published `main`. There is no LTS branch and no backport policy — security fixes land on `main` and are picked up by re-pulling.

package/bin/redline.cjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// Node-compatible launcher so `npx @levistudio/redline <file>` works even when the
+// caller doesn't have Bun on PATH yet. Bun is still required at runtime — the
+// server is `Bun.serve()` — but we surface the missing-Bun case as one clean
+// message rather than an opaque shebang/parse failure.
+//
+// On `bunx @levistudio/redline`, this file is also the entry point; it just finds
+// the same Bun that ran it and re-execs `bun run src/cli.ts`. No-op for the
+// caller, single code path for us.
+"use strict";
+
+const { spawn, spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const CLI = path.resolve(__dirname, "..", "src", "cli.ts");
+
+function findBun() {
+  if (process.env.BUN_INSTALL_BIN) {
+    const candidate = path.join(process.env.BUN_INSTALL_BIN, process.platform === "win32" ? "bun.exe" : "bun");
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  const probe = spawnSync(
+    process.platform === "win32" ? "where" : "which",
+    ["bun"],
+    { encoding: "utf8" }
+  );
+  if (probe.status === 0 && probe.stdout) {
+    const first = probe.stdout.split(/\r?\n/)[0].trim();
+    if (first) return first;
+  }
+  const home = process.env.HOME || process.env.USERPROFILE;
+  if (home) {
+    const fallback = path.join(home, ".bun", "bin", process.platform === "win32" ? "bun.exe" : "bun");
+    if (fs.existsSync(fallback)) return fallback;
+  }
+  return null;
+}
+
+const bun = findBun();
+if (!bun) {
+  process.stderr.write(
+    "\nRedline requires Bun. Install it and re-run:\n" +
+    "  https://bun.sh\n\n" +
+    "Then: bunx @levistudio/redline <file.md>   (or rerun the same npx command)\n\n"
+  );
+  process.exit(1);
+}
+
+const child = spawn(bun, ["run", CLI, ...process.argv.slice(2)], { stdio: "inherit" });
+child.on("exit", (code, signal) => {
+  if (signal) {
+    try { process.kill(process.pid, signal); } catch { process.exit(1); }
+  } else {
+    process.exit(code == null ? 0 : code);
+  }
+});
+child.on("error", (err) => {
+  process.stderr.write(`\n[redline] Failed to launch bun: ${err.message}\n`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@levistudio/redline",
+  "version": "0.1.0",
+  "description": "Inline comments on Markdown files, for human-in-the-loop AI doc review.",
+  "keywords": [
+    "markdown",
+    "code-review",
+    "ai",
+    "claude",
+    "bun",
+    "documentation"
+  ],
+  "homepage": "https://github.com/alevi/redline#readme",
+  "bugs": {
+    "url": "https://github.com/alevi/redline/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alevi/redline.git"
+  },
+  "license": "MIT",
+  "author": "Alon Levi <alonlevi@gmail.com>",
+  "bin": {
+    "redline": "bin/redline.cjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "!src/**/*.test.ts",
+    "scripts/install-skill.sh",
+    "skills",
+    "README.md",
+    "SECURITY.md",
+    "ROADMAP.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "bun src/cli.ts",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "hono": "^4.7.0",
+    "marked": "^15.0.0",
+    "proper-lockfile": "^4.1.2",
+    "sanitize-html": "^2.17.3"
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^20.9.0",
+    "@types/bun": "latest",
+    "@types/proper-lockfile": "^4.1.4",
+    "@types/sanitize-html": "^2.16.1",
+    "happy-dom": "^20.9.0"
+  }
+}

package/scripts/install-skill.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# Install the redline-review skill into the user's global Claude skills directory
+# so it's reachable from any project, not just this repo.
+#
+# This is a copy, not a symlink: the repo lives in paths that move (worktrees,
+# renamed projects), and a stale symlink that vanishes is worse than a copy
+# that needs an explicit refresh after pulling skill changes.
+#
+# We also generate a self-contained launcher next to the installed skill,
+# with absolute paths to `bun` and `src/cli.ts` baked in. SKILL.md points
+# at the launcher. This removes every $PATH dependency from the invocation
+# chain — both `redline` itself AND the `#!/usr/bin/env bun` shebang it would
+# otherwise resolve through PATH at runtime. (Real-usage failure: an outside
+# session hit `env: bun: No such file or directory` because ~/.bun/bin isn't
+# on $PATH in non-interactive Claude Bash subprocesses.)
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+SRC="$REPO_ROOT/skills/redline-review"
+DEST="${CLAUDE_HOME:-$HOME/.claude}/skills/redline-review"
+PLACEHOLDER="__REDLINE_BIN__"
+
+if [ ! -d "$SRC" ]; then
+  echo "error: skill source not found at $SRC" >&2
+  exit 1
+fi
+
+CLI_ABS="$REPO_ROOT/src/cli.ts"
+if [ ! -f "$CLI_ABS" ]; then
+  echo "error: redline cli not found at $CLI_ABS" >&2
+  exit 1
+fi
+
+# Resolve bun. Prefer $PATH; fall back to ~/.bun/bin/bun.
+if command -v bun >/dev/null 2>&1; then
+  BUN_ABS="$(command -v bun)"
+elif [ -x "$HOME/.bun/bin/bun" ]; then
+  BUN_ABS="$HOME/.bun/bin/bun"
+else
+  echo "error: bun not found in PATH or at ~/.bun/bin/bun (install: https://bun.sh)" >&2
+  exit 1
+fi
+
+mkdir -p "$(dirname "$DEST")"
+rm -rf "$DEST"
+cp -R "$SRC" "$DEST"
+
+# Generate a self-contained launcher with absolute paths to bun and cli.ts.
+LAUNCHER="$DEST/redline"
+cat > "$LAUNCHER" <<EOF
+#!/bin/bash
+# Auto-generated by scripts/install-skill.sh — re-run that script to refresh.
+exec "$BUN_ABS" run "$CLI_ABS" "\$@"
+EOF
+chmod +x "$LAUNCHER"
+
+# Substitute the launcher path into the installed SKILL.md.
+SKILL_FILE="$DEST/SKILL.md"
+if ! grep -q "$PLACEHOLDER" "$SKILL_FILE"; then
+  echo "error: placeholder '$PLACEHOLDER' not found in $SKILL_FILE — source skill is out of sync" >&2
+  exit 1
+fi
+if [[ "$OSTYPE" == "darwin"* ]]; then
+  sed -i '' "s|$PLACEHOLDER|$LAUNCHER|g" "$SKILL_FILE"
+else
+  sed -i "s|$PLACEHOLDER|$LAUNCHER|g" "$SKILL_FILE"
+fi
+
+echo "Installed redline-review → $DEST"
+echo "  launcher: $LAUNCHER"
+echo "  bun:      $BUN_ABS"
+echo "  cli:      $CLI_ABS"
+echo
+echo "Your AI coding agents (Claude Code, etc.) can now use the redline-review skill."
+echo "Try it: ask your agent to redline a markdown file you'd like feedback on."
+echo
+echo "Re-run this script after pulling skill changes."

package/skills/redline-review/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: redline-review
+description: Hand a markdown file you produced (spec, RFC, brief, plan) to the human for inline review, wait for them to finish, then continue with the approved document. Use whenever the human's sign-off on a document is the next step in the work.
+---
+
+# Handing off a markdown doc for human review
+
+When you've produced a markdown document that the human needs to read, comment on, and approve before you continue, use Redline. It opens a browser-based reader where the human leaves inline comments, an agent subprocess Redline spawns replies to them, the human signs off, and the document on disk is left in its final approved state.
+
+## How to invoke it
+
+The redline binary lives at `__REDLINE_BIN__` (substituted at install time — if you see the literal placeholder string, the skill was installed incorrectly; tell the human to re-run `scripts/install-skill.sh` from the redline repo). Always invoke it by this absolute path. Do not call bare `redline` and do not try to "fix" PATH issues by running `bun link` or guessing where the repo lives.
+
+**Always background the launcher and poll.** Never run `__REDLINE_BIN__` as a foreground/blocking Bash call: the Bash tool buffers stdout until the process exits, so you would never see the URL the human needs to click and your "I'll wait while you review" message would be a lie. Use this pattern:
+
+```bash
+FILE=/abs/path/to/file.md
+DIR=$(dirname "$FILE"); BASE=$(basename "$FILE")
+STARTUP="$DIR/.review/$BASE.startup.json"
+RESULT="$DIR/.review/$BASE.result"
+LOG=/tmp/redline-$BASE.log
+
+# Kick off the review in the background.
+__REDLINE_BIN__ "$FILE" > "$LOG" 2>&1 &
+
+# Step 1: wait for startup, read the URL.
+for i in $(seq 1 60); do [ -f "$STARTUP" ] && break; sleep 0.5; done
+if [ ! -f "$STARTUP" ]; then
+  echo "redline did not start; check $LOG" >&2
+  exit 1
+fi
+URL=$(grep -o '"url": *"[^"]*"' "$STARTUP" | sed 's/.*"\(http[^"]*\)".*/\1/')
+PID=$(grep -o '"pid": *[0-9]*' "$STARTUP" | grep -o '[0-9]*')
+echo "REDLINE_URL: $URL"
+echo "REDLINE_PID: $PID"
+
+# Step 2: surface the URL to the human (you do this after the Bash call returns
+# — see the next section), then wait for the redline process to exit. Watching
+# the PID (essentially free) instead of polling for the result file means you
+# wake up within ~0.5s of the human clicking Done, not up to 30s later.
+while kill -0 "$PID" 2>/dev/null; do sleep 0.5; done
+cat "$RESULT"
+```
+
+The startup file at `.review/<basename>.startup.json` is written synchronously when the server begins listening; it contains `url`, `port`, `file`, `result_file`, `started_at`, `pid`. The result file at `.review/<basename>.result` is written when the session ends (approved, abandoned, or error).
+
+In practice, run the script above as **two separate Bash calls** so you can tell the human the URL between steps:
+1. First call: everything through `echo "REDLINE_PID: $PID"`. Returns in ~1s with the URL and PID on stdout.
+2. Surface the URL to the human in your reply text (see "Surfacing the URL" below).
+3. Second call: just the `while kill -0` loop waiting for the PID, then `cat "$RESULT"`. Long timeout (`timeout: 1800000` = 30 min, or longer).
+
+If invocation fails (binary missing, startup file never appears, etc.), surface the error verbatim and stop — do not try to recover. The human will re-run the install script.
+
+### Pass context with `--context`
+
+```
+__REDLINE_BIN__ /abs/path/file.md --context "Draft of the auth-rewrite RFC — focus on the migration plan in §4."
+```
+
+The context string is shown in the reader's header so the human knows what they're being asked to review and what you'd like them to focus on. Use it whenever the file alone doesn't make the ask obvious. One sentence is plenty.
+
+### Surfacing the URL
+
+After the first Bash call returns with `REDLINE_URL: http://localhost:NNNN`, surface that URL in your reply text. The human has no other signal that something is waiting for them. One short sentence:
+
+> "Opening this in Redline for review at http://localhost:NNNN — cmd-click to open. I'll continue once you click Done."
+
+(There is an `--open` flag that auto-launches the browser, but prefer leaving it off — the human may not be at the keyboard the moment the session starts, and a stolen-focus browser tab is worse than a URL they click when ready.)
+
+## How to interpret the result
+
+When the polling loop's Bash call returns, the `cat "$RESULT"` at the end of it has printed the result JSON to stdout.
+
+```json
+{ "status": "approved", "file": "/abs/path/to/file.md", "rounds": 2, "comments": 5 }
+```
+
+Statuses:
+
+- **`approved`** — Human signed off. Re-read the file from disk and continue. Note: the file may be byte-identical to what you handed off — if every comment was Q&A the agent answered with `accept-as-is`, no revision pass ran. That's still a valid approval, not a no-op.
+- **`abandoned`** — Human closed the tab or Ctrl+C'd without clicking Done. The doc is in whatever state it was last revised to, but has not been signed off. Ask the human what they want to do.
+- **`error`** — A revision pass failed. The result file includes a `reason` field with the failure message; `.review/errors.log` next to the file has more detail. Surface both to the human.
+
+## Outer-agent handoff pattern
+
+The full loop, when you are the outer agent producing the doc:
+
+1. Write the markdown file to disk at an absolute path.
+2. Tell the human in one sentence what's about to happen.
+3. First Bash call: launch `__REDLINE_BIN__ <abs-path> --context "<one-liner>"` in the background and poll for `.startup.json`. Returns in ~1s with the URL.
+4. Surface the URL to the human in your reply text so they can cmd-click to open.
+5. Second Bash call: wait on the redline PID (`while kill -0 "$PID" 2>/dev/null; do sleep 0.5; done`) then `cat "$RESULT"`, with a long timeout (30+ min). While the session runs, you are idle — do not start unrelated work, do not run other tools.
+6. On `approved`: re-read the file from disk (it may have been revised) and continue with whatever required sign-off.
+7. On `abandoned` or `error`: stop and ask the human how to proceed; do not retry automatically.
+
+You do not need to reply to comments — Redline spawns its own agent subprocess for that. You do not need to invoke `redline resolve` separately — revisions happen inside the session when the human accepts.
+
+## When *not* to use this
+
+- The doc doesn't need human sign-off — just commit it.
+- The human is not at the keyboard (e.g. an autonomous run). Redline requires a live browser session.
+- The doc is something other than markdown.