From 546087a060c5392f57de77f71abd7c388b6c3b01 Mon Sep 17 00:00:00 2001
From: Jacek Tomaszewski <jacek@fullstack.house>
Date: Wed, 2 Sep 2026 07:48:00 +0200
Subject: [PATCH 1/4] feat(cockpit): every box you type markdown into shows how
 it will read
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A comment goes to GitHub as markdown, so "did that list come out as a
list, and where did my backticks go" is a question the cockpit should
answer before the Send rather than after it. Now it does, in all four
places you write: a comment being edited, a comment being added, the
line composer, and the chat input.

The preview sits under the box with no tab and no toggle — a Write /
Preview pair is two clicks to answer a question you have continuously —
and it appears exactly when it has something to say: when the render
reads back as something other than what was typed. A one-line note, or
two plain paragraphs, get nothing, because a second identical copy of
them is noise. A list, a heading, `code`, **bold**, a [link] all lose or
move characters on the way through, and those are the drafts worth
seeing first.

A comment is previewed with its grade badge, since that is the body
GitHub gets — the same withGrade() the finished comment, the payload and
the export all use. Preview and render share one markdown path for the
same reason: a preview that can drift from the real thing is worse than
none.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 SPEC.md                  | 10 +++++-
 web/src/Detail.tsx       | 24 ++++++++++----
 web/src/Markdown.tsx     | 67 +++++++++++++++++++++++++++++++++++---
 web/src/markdown.test.ts | 69 ++++++++++++++++++++++++++++++++++++++++
 web/src/styles.css       | 16 ++++++++++
 5 files changed, 174 insertions(+), 12 deletions(-)
 create mode 100644 web/src/markdown.test.ts

diff --git a/SPEC.md b/SPEC.md
index f09b98c..e8a2bae 100644
--- a/SPEC.md
+++ b/SPEC.md
@@ -1426,6 +1426,14 @@ one is reported over the next.
   would read as a click the user never made.
 - Opening a review triggers refresh (§13.2); a refresh failure is reported
   softly and the draft still reads.
+- Every box the user types markdown into (a comment being edited, a comment
+  being written, a line composer, the chat input) renders that draft as it
+  will read, below the box, with no switch and no click. The preview MUST be
+  produced by the same markdown path as the finished render, so it cannot
+  drift from it, and a comment's preview MUST carry its grade badge (§7.4) —
+  that is the body GitHub gets. It MUST be suppressed when the render reads
+  back word-for-word as the source (whitespace runs flattened): a plain note
+  is told nothing by a second copy of itself.
 - The review's history renders as a collapsed card at the foot of the review,
   newest first — it is what you open when a review is not where you expected
   it, not part of reading one — with a rail jump that opens it on the way. An
@@ -1712,7 +1720,7 @@ An implementation conforms when all of the following hold:
 | §14 GitHub | `src/core/gh.ts`, `src/core/trust.ts`, `src/core/send.ts` |
 | §15 auto-send | `src/core/autosend.ts` |
 | §16 HTTP API | `src/server/index.ts` |
-| §17 cockpit | `web/src/inbox.ts`, `notify.ts`, `favicon.ts`, `review.ts` |
+| §17 cockpit | `web/src/inbox.ts`, `notify.ts`, `favicon.ts`, `review.ts`, `Markdown.tsx` |
 | §18 CLI | `src/cli/index.ts` |
 
 ## Appendix B. Known Divergences in the Reference Implementation (non-normative)
diff --git a/web/src/Detail.tsx b/web/src/Detail.tsx
index ac6f9aa..676aea9 100644
--- a/web/src/Detail.tsx
+++ b/web/src/Detail.tsx
@@ -21,7 +21,7 @@ import {
 } from "./api";
 import { highlightDiff } from "./highlight";
 import { Icon, IconName, Key } from "./Icon";
-import { Markdown } from "./Markdown";
+import { Markdown, MarkdownPreview } from "./Markdown";
 import { walkFrom } from "./inbox";
 import {
   EVENT_LABEL,
@@ -166,6 +166,7 @@ function LineComposer({
           }
         }}
       />
+      <MarkdownPreview className="comment-body" text={body} />
       <div className="line-composer-actions">
         <button className="btn" disabled={!text} onClick={() => onAdd(text)}>
           <Icon name="plus" />
@@ -508,12 +509,19 @@ function CommentCard({
           ))}
       </div>
       {editing ? (
-        <textarea
-          className="comment-edit"
-          value={draft}
-          onChange={(e) => setDraft(e.target.value)}
-          rows={Math.max(3, draft.split("\n").length)}
-        />
+        <>
+          <textarea
+            className="comment-edit"
+            value={draft}
+            onChange={(e) => setDraft(e.target.value)}
+            rows={Math.max(3, draft.split("\n").length)}
+          />
+          {/* Previewed with its grade, because that is the comment GitHub gets. */}
+          <MarkdownPreview
+            className="comment-body"
+            text={withGrade(draft, comment.severity ?? null)}
+          />
+        </>
       ) : (
         // The grade reads as the first words of the comment, exactly as it will
         // on GitHub — not as a chip that only exists here. Prefixed at render
@@ -564,6 +572,7 @@ function AddComment({
         />
       </div>
       <textarea placeholder="Your comment…" value={body} onChange={(e) => setBody(e.target.value)} rows={3} />
+      <MarkdownPreview className="comment-body" text={body} />
       <div className="add-comment-row">
         <button
           className="btn"
@@ -948,6 +957,7 @@ function ChatPanel({
                 if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) send();
               }}
             />
+            <MarkdownPreview className="chat-turn-body" text={draft} />
             <div className="chat-actions">
               <button className="btn btn-dark" onClick={send} disabled={busy || draft.trim() === ""}>
                 <Icon name="send" />
diff --git a/web/src/Markdown.tsx b/web/src/Markdown.tsx
index 8c0b3f8..a622763 100644
--- a/web/src/Markdown.tsx
+++ b/web/src/Markdown.tsx
@@ -4,12 +4,71 @@ import { useMemo } from "react";
 
 marked.setOptions({ gfm: true, breaks: false });
 
+/** Markdown → sanitized HTML. One path, so a preview can't drift from the real render. */
+export function renderMarkdown(text: string): string {
+  const raw = marked.parse(text ?? "", { async: false }) as string;
+  return DOMPurify.sanitize(raw);
+}
+
 /** Render trusted-ish markdown (AI output / PR content) safely. */
 export function Markdown({ text, className }: { text: string; className?: string }) {
-  const rendered = useMemo(() => {
-    const raw = marked.parse(text ?? "", { async: false }) as string;
-    return DOMPurify.sanitize(raw);
-  }, [text]);
+  const rendered = useMemo(() => renderMarkdown(text), [text]);
   if (!text?.trim()) return null;
   return <div className={`md ${className ?? ""}`} dangerouslySetInnerHTML={{ __html: rendered }} />;
 }
+
+const ENTITY: Record<string, string> = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: " ",
+  "#39": "'",
+};
+
+/**
+ * What a rendered block reads as: tags dropped, entities back to characters,
+ * whitespace runs flattened. Deliberately not DOM-based — this decides whether
+ * to draw a preview, and that decision is worth a test that runs without a
+ * browser.
+ */
+export function readsAs(html: string): string {
+  return html
+    .replace(/<[^>]*>/g, " ")
+    .replace(/&([a-z]+|#\d+);/gi, (m, name: string) => ENTITY[name.toLowerCase()] ?? m)
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * Would this render as something other than what was typed?
+ *
+ * The rule the preview turns on: markdown that reads back word-for-word as its
+ * own source — a one-line note, a plain paragraph, a blank-line-separated pair
+ * of them — is told nothing by a second copy of itself underneath the box. A
+ * list, a heading, `code`, **bold**, a [link] all lose or move characters on
+ * the way through, and those are exactly the drafts worth seeing first.
+ */
+export function rendersDifferently(text: string, html: string): boolean {
+  return readsAs(html) !== text.replace(/\s+/g, " ").trim();
+}
+
+/**
+ * A draft as it will read once posted — under the box you are typing it in.
+ *
+ * It costs no click and has no switch: it appears when it has something to
+ * say and stays out of the way when it doesn't. Comment bodies are sent to
+ * GitHub as markdown, so "what did I actually write" is a question the cockpit
+ * should answer before the Send, not after.
+ */
+export function MarkdownPreview({ text, className }: { text: string; className?: string }) {
+  const html = useMemo(() => (text?.trim() ? renderMarkdown(text) : ""), [text]);
+  if (!html || !rendersDifferently(text, html)) return null;
+  return (
+    <div className="md-preview">
+      <div className="lab">preview</div>
+      <div className={`md prose ${className ?? ""}`} dangerouslySetInnerHTML={{ __html: html }} />
+    </div>
+  );
+}
diff --git a/web/src/markdown.test.ts b/web/src/markdown.test.ts
new file mode 100644
index 0000000..dbfcfb9
--- /dev/null
+++ b/web/src/markdown.test.ts
@@ -0,0 +1,69 @@
+import { marked } from "marked";
+import { describe, expect, it } from "vitest";
+import { readsAs, rendersDifferently } from "./Markdown";
+
+/** The same parse the cockpit does, minus the sanitizer (which needs a DOM). */
+const render = (text: string) => marked.parse(text, { async: false }) as string;
+const worth = (text: string) => rendersDifferently(text, render(text));
+
+describe("readsAs", () => {
+  it("drops tags and flattens whitespace", () => {
+    expect(readsAs("<p>hello <strong>there</strong></p>\n<p>again</p>")).toBe("hello there again");
+  });
+
+  it("puts entities back", () => {
+    expect(readsAs("<p>a &amp; b &lt; c</p>")).toBe("a & b < c");
+  });
+});
+
+describe("when a preview is worth drawing", () => {
+  it("stays away from plain prose", () => {
+    expect(worth("this reads fine as it is")).toBe(false);
+  });
+
+  it("stays away from paragraphs split by a blank line", () => {
+    expect(worth("first thought\n\nsecond thought")).toBe(false);
+  });
+
+  it("stays away from an empty box", () => {
+    expect(worth("")).toBe(false);
+    expect(worth("   \n ")).toBe(false);
+  });
+
+  it("stays away from prose with an ampersand", () => {
+    expect(worth("read & write")).toBe(false);
+  });
+
+  it("shows for a list", () => {
+    expect(worth("- one\n- two")).toBe(true);
+  });
+
+  it("shows for a numbered list", () => {
+    expect(worth("1. one\n2. two")).toBe(true);
+  });
+
+  it("shows for emphasis and inline code", () => {
+    expect(worth("**really** important")).toBe(true);
+    expect(worth("call `parseArgs` first")).toBe(true);
+  });
+
+  it("shows for a heading", () => {
+    expect(worth("# the problem")).toBe(true);
+  });
+
+  it("shows for a link, whose target vanishes from the text", () => {
+    expect(worth("see [the spec](https://example.com)")).toBe(true);
+  });
+
+  it("shows for a fenced code block", () => {
+    expect(worth("```ts\nconst a = 1;\n```")).toBe(true);
+  });
+
+  it("shows for a blockquote", () => {
+    expect(worth("> quoting you")).toBe(true);
+  });
+
+  it("shows for a graded comment, whose badge is markdown of its own", () => {
+    expect(worth("🚨 **blocker** — this leaks")).toBe(true);
+  });
+});
diff --git a/web/src/styles.css b/web/src/styles.css
index c6de226..ef9c35c 100644
--- a/web/src/styles.css
+++ b/web/src/styles.css
@@ -1936,6 +1936,22 @@ button {
 
 /* ---- markdown ---- */
 
+/* The draft as it will read, under the box it is being typed in. It hangs off
+   the editor's left edge rather than sitting in a card of its own: it is the
+   same text once more, not a second comment. */
+.md-preview {
+  display: flex;
+  flex-direction: column;
+  gap: 3px;
+  margin: 6px 0 2px;
+  padding: 2px 0 2px 12px;
+  border-left: 2px solid var(--line-2);
+}
+
+.md-preview .md {
+  color: var(--fg-3);
+}
+
 .md > :first-child {
   margin-top: 0;
 }

From 00d6b5aa3447417f57b51af8d88a8044c729f038 Mon Sep 17 00:00:00 2001
From: Jacek Tomaszewski <jacek@fullstack.house>
Date: Wed, 2 Sep 2026 08:05:58 +0200
Subject: [PATCH 2/4] feat(cockpit): a markdown file the PR adds opens as the
 document it is
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A PR that adds a 1,400-line spec rendered as 1,400 rows of `+ ## Heading`
— the one form in which the document cannot be reviewed, because
reviewing it means reading it. Every line being an addition means the
diff's markers carry no information at all, and cost the reader the
document. So a markdown file the PR creates now opens rendered.

It is not a detour off the review. The file's patch is turned back into
the document in blocks that keep their source line numbers, so the
review's comments sit under the paragraph they point at — the nit about
"three things to adopt" now stands directly above the two bullets it is
counting — and any paragraph takes a comment or a question where it
stands, the same gesture as the diff's gutter `+`.

A markdown file the PR merely edits stays a diff, because there the
change is the point; "read as a document" sits in its own file header.
Read that way it says what it cannot show: the header warns it is the
hunks alone, the lines between them are counted and marked as skipped,
the blocks the PR added carry a stripe, and what the PR removed is not
in a document at all — the diff is one click back.

The chapter fold counted every line as a table row. A document is not
one: measured on a 1,028-line spec, 2,874 nodes against a diff's 12.7 a
row, so a file that opens as a document now counts a quarter, and the
folded label says "lines to draw" rather than claiming they are diff
lines.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md                |   9 +-
 README.md                |   8 +
 SPEC.md                  |  43 ++++-
 web/src/Detail.tsx       | 351 ++++++++++++++++++++++++++++++++++++---
 web/src/Icon.tsx         |   1 +
 web/src/mdblocks.test.ts | 118 +++++++++++++
 web/src/mdblocks.ts      | 137 +++++++++++++++
 web/src/styles.css       | 139 +++++++++++++++-
 8 files changed, 778 insertions(+), 28 deletions(-)
 create mode 100644 web/src/mdblocks.test.ts
 create mode 100644 web/src/mdblocks.ts

diff --git a/CLAUDE.md b/CLAUDE.md
index 67c70d7..adb31a7 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -146,7 +146,14 @@ left unwritten. Code and tests win when they disagree.
   since that machine's tap lands where nobody is looking. `favicon.ts` is the
   quiet half of the same job: a dot on the tab icon while the inbox holds
   anything, re-derived on every read of the queue (`fetchReviews`) so no screen
-  can leave it stale
+  can leave it stale. `mdblocks.ts` turns a markdown file's patch back into the
+  document, in blocks that keep their source line numbers — a file the PR adds
+  opens that way, since there the diff is the file with `+` in front of every
+  line, and the block numbers are what let the review's comments stay where
+  they point. A file the PR edits stays a diff (the change is the point) and
+  says, when read, that it is only the hunks: removals are not in a document,
+  so the reading view marks the changed blocks, counts the lines it skipped,
+  and keeps the diff one click away
 
 ## Conventions
 
diff --git a/README.md b/README.md
index d401a89..8f22811 100644
--- a/README.md
+++ b/README.md
@@ -148,6 +148,14 @@ line and get the answer in the conversation below. A line the PR removes can be
 asked about too; a comment on one posts on the file, since GitHub only takes
 inline comments on the new side of a diff.
 
+A markdown file the PR **adds** opens as the document it is, not as a thousand
+rows of `+ ## Heading` — because reviewing a new spec means reading it, and
+every line being an addition means the diff's markers say nothing. It is still
+the review: the draft comments sit in the document under the paragraph they
+point at, and any paragraph takes a comment or a question where it stands. A
+markdown file the PR only *edits* stays a diff — there the change is the point
+— with "read as a document" in its header when you want the prose instead.
+
 Artifacts are plain JSON you can `cat`, edit, or pipe into anything.
 
 The queue is meant to be walked, not clicked through: `j`/`k` move the cursor
diff --git a/SPEC.md b/SPEC.md
index e8a2bae..4e95e78 100644
--- a/SPEC.md
+++ b/SPEC.md
@@ -1396,13 +1396,15 @@ on every queue fetch so no screen can leave it stale.
 ### 17.5 The Walkthrough
 
 Chapters render open — the walkthrough is the point of the page — with one
-exception: a chapter holding more than 2,000 diff lines opens folded, and its
-header MUST say so and say why ("34,961 diff lines, folded to keep the page
+exception: a chapter with more than 2,000 lines to draw opens folded, and its
+header MUST say so and say why ("34,961 lines to draw, folded to keep the page
 quick"). A rendered diff line is a table row and a dozen DOM nodes, so the
 catch-all chapter of a 368-file PR is 600,000 of them: the browser then spends
-its time on layout rather than on the review, and scrolling collapses. The
-fold MUST be decided while rendering, not corrected afterwards — folding a
-chapter that has already been drawn pays the whole cost it exists to avoid.
+its time on layout rather than on the review, and scrolling collapses. A file
+that opens as a document (§17.7) is counted at a quarter of its lines, being
+drawn a block at a time rather than a row at a time. The fold MUST be decided
+while rendering, not corrected afterwards — folding a chapter that has already
+been drawn pays the whole cost it exists to avoid.
 
 The fold is a default, not a refusal: one click opens it, and the user's
 choice stands for as long as they are on that review. It does not outlive the
@@ -1440,6 +1442,35 @@ one is reported over the next.
   absent history MUST read as "predates cerber keeping one", never as an
   empty log (§5.4).
 
+### 17.7 Markdown Files as Documents
+
+A markdown file in the diff can be read as the document it is, rendered
+through the same markdown path as everything else the cockpit renders. A file
+the PR **creates** MUST open that way: there every line is an addition, so the
+diff's markers carry no information and cost the reader the document. Every
+other file — including a markdown file the PR merely edits — is a diff until
+the reader asks, from a control in that file's own header, and either choice
+stands for as long as they are on the review (like a chapter's fold, §17.5).
+
+A document is not a detour off the review, so the reading view MUST keep what
+the diff view offers:
+
+- The review's comments render in it, under the block holding the line each
+  points at (nearest preceding block for a line that is blank in the source).
+  No comment may be dropped for want of a place — an unplaceable one renders
+  after the document.
+- A block takes a new comment or a question where it stands, anchored to the
+  block's first line.
+
+And it MUST NOT pass off a fragment as the whole:
+
+- A file the PR only edits carries the hunks alone, so its header says so, the
+  lines between hunks are marked as skipped and counted, and the blocks the PR
+  added are marked as changed. In a file the PR creates nothing is marked,
+  since everything is new.
+- What the PR **removed** is not in the document at all. The diff is one click
+  away and is where that question is answered.
+
 ## 18. CLI
 
 `cerber` (version derived from the package — see Appendix B.1):
@@ -1720,7 +1751,7 @@ An implementation conforms when all of the following hold:
 | §14 GitHub | `src/core/gh.ts`, `src/core/trust.ts`, `src/core/send.ts` |
 | §15 auto-send | `src/core/autosend.ts` |
 | §16 HTTP API | `src/server/index.ts` |
-| §17 cockpit | `web/src/inbox.ts`, `notify.ts`, `favicon.ts`, `review.ts`, `Markdown.tsx` |
+| §17 cockpit | `web/src/inbox.ts`, `notify.ts`, `favicon.ts`, `review.ts`, `Markdown.tsx`, `mdblocks.ts` |
 | §18 CLI | `src/cli/index.ts` |
 
 ## Appendix B. Known Divergences in the Reference Implementation (non-normative)
diff --git a/web/src/Detail.tsx b/web/src/Detail.tsx
index 676aea9..8ecb203 100644
--- a/web/src/Detail.tsx
+++ b/web/src/Detail.tsx
@@ -1,5 +1,5 @@
 import { html } from "diff2html";
-import { ReactNode, useEffect, useMemo, useRef, useState } from "react";
+import { Fragment, ReactNode, useEffect, useMemo, useRef, useState } from "react";
 import { createPortal } from "react-dom";
 import { diffLineCounts, patchForFiles, splitDiffByFile, unclaimedFiles } from "../../src/core/diff";
 import { withGrade } from "../../src/core/severity";
@@ -21,7 +21,8 @@ import {
 } from "./api";
 import { highlightDiff } from "./highlight";
 import { Icon, IconName, Key } from "./Icon";
-import { Markdown, MarkdownPreview } from "./Markdown";
+import { Markdown, MarkdownPreview, renderMarkdown } from "./Markdown";
+import { MdBlock, MdDocument, isMarkdownPath, readMarkdown } from "./mdblocks";
 import { walkFrom } from "./inbox";
 import {
   EVENT_LABEL,
@@ -204,7 +205,7 @@ function LineComposer({
  * something about is one click away rather than a file-and-line form at the
  * foot of the chapter.
  */
-function DiffBlock({
+function DiffGroup({
   patch,
   comments,
   renderComment,
@@ -212,6 +213,7 @@ function DiffBlock({
   chatBusy,
   onAddLineComment,
   onAskAboutLine,
+  onRead,
 }: {
   patch: string;
   comments: ReviewComment[];
@@ -221,6 +223,8 @@ function DiffBlock({
   chatBusy: boolean;
   onAddLineComment: (pick: LinePick, body: string) => void;
   onAskAboutLine: (pick: LinePick, message: string) => void;
+  /** Read this markdown file as a document instead of as a diff. */
+  onRead: (path: string) => void;
 }) {
   const rendered = useMemo(
     () =>
@@ -232,6 +236,17 @@ function DiffBlock({
   // The paths as the diff itself spells them: the rendered header shows a
   // rename as "old → new", which is not something to hang a comment on.
   const paths = useMemo(() => splitDiffByFile(patch).map((p) => p.path), [patch]);
+  // Markdown files with a new side to read. A deletion has none, so it is only
+  // ever a diff.
+  const readable = useMemo(
+    () =>
+      new Set(
+        splitDiffByFile(patch)
+          .filter((p) => isMarkdownPath(p.path) && readMarkdown(p.patch).lines > 0)
+          .map((p) => p.path),
+      ),
+    [patch],
+  );
   // Where the comments hang, not what they say. The cockpit re-polls the whole
   // artifact every few seconds while a chat turn runs, and rebuilding the diff
   // on each of those would flicker the page and throw away a composer someone
@@ -241,6 +256,10 @@ function DiffBlock({
     [comments],
   );
   const ref = useRef<HTMLDivElement>(null);
+  // Held in a ref so that a fresh callback from a re-render never rebuilds the
+  // diff underneath the reader.
+  const onReadRef = useRef(onRead);
+  onReadRef.current = onRead;
   const [slots, setSlots] = useState<{ id: string; el: HTMLElement }[]>([]);
   const [pick, setPick] = useState<LinePick | null>(null);
   const [pickSlot, setPickSlot] = useState<HTMLElement | null>(null);
@@ -261,6 +280,18 @@ function DiffBlock({
       if (path) {
         byFile.set(path, wrapper);
         wrapper.dataset.path = path;
+        // A markdown file can be read as the document it is; the offer belongs
+        // in its own header, next to its name, not in a control somewhere else
+        // that the reader has to connect to this file.
+        if (readable.has(path)) {
+          const button = document.createElement("button");
+          button.type = "button";
+          button.className = "btn btn-sm md-read-toggle";
+          button.dataset.readPath = path;
+          button.textContent = "read as a document";
+          button.title = "Render this markdown instead of showing it line by line";
+          wrapper.querySelector(".d2h-file-header")?.appendChild(button);
+        }
       }
     });
 
@@ -281,13 +312,30 @@ function DiffBlock({
     }
     setSlots(placed);
 
+    // Registered before the read-only exit: a sent review takes no comments,
+    // but it is still something to read, so its markdown still swaps.
+    const onClick = (e: MouseEvent) => {
+      const toggle = (e.target as HTMLElement).closest<HTMLElement>(".md-read-toggle");
+      if (toggle?.dataset.readPath) {
+        onReadRef.current(toggle.dataset.readPath);
+        return;
+      }
+      const button = (e.target as HTMLElement).closest<HTMLElement>(".line-add");
+      if (!button) return;
+      const { path, line, side } = button.dataset;
+      if (!path || !line) return;
+      setPick({ path, line: Number(line), side: side === "old" ? "old" : "new" });
+    };
+    root.addEventListener("click", onClick);
+    const stopListening = () => root.removeEventListener("click", onClick);
+
     // A review that was sent while the composer was open has no more comments
     // to take. Dropping the slot alone wouldn't do it — the parking effect
     // would put the composer straight back on the next render.
     if (readOnly) {
       setPick(null);
       setPickSlot(null);
-      return;
+      return stopListening;
     }
 
     // One button per numbered row, sitting invisibly over the line numbers
@@ -322,22 +370,14 @@ function DiffBlock({
       }
     }
 
-    const onClick = (e: MouseEvent) => {
-      const button = (e.target as HTMLElement).closest<HTMLElement>(".line-add");
-      if (!button) return;
-      const { path, line, side } = button.dataset;
-      if (!path || !line) return;
-      setPick({ path, line: Number(line), side: side === "old" ? "old" : "new" });
-    };
-    root.addEventListener("click", onClick);
     // The rendered HTML is about to be replaced, and with it every row the
     // open composer was measured against.
     setPickSlot(null);
-    return () => root.removeEventListener("click", onClick);
+    return stopListening;
     // `comments` is deliberately absent: `anchors` is the part of it this
     // effect renders, and re-running on every poll would flicker the diff.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [rendered, anchors, paths, readOnly]);
+  }, [rendered, anchors, paths, readable, readOnly]);
 
   // Park the composer under the picked row. Separate from the render above so
   // that opening and closing it doesn't rebuild the whole diff.
@@ -368,7 +408,6 @@ function DiffBlock({
     return () => inserted.tr.remove();
   }, [pick, slots, readOnly]);
 
-  if (!rendered) return <p className="muted">No diff for this chapter.</p>;
   const unplaced = comments.filter((c) => !slots.some((s) => s.id === c.id));
   return (
     <>
@@ -401,6 +440,265 @@ function DiffBlock({
   );
 }
 
+/** One block of a markdown file, with the affordance to say something about it. */
+function MdBlockView({
+  block,
+  path,
+  changed,
+  readOnly,
+  onPick,
+}: {
+  block: MdBlock;
+  path: string;
+  changed: boolean;
+  readOnly: boolean;
+  onPick: () => void;
+}) {
+  const rendered = useMemo(() => renderMarkdown(block.raw), [block.raw]);
+  const label = `Say something about ${path}:${block.from}`;
+  return (
+    <div className={`md-block${changed ? " md-block-changed" : ""}`}>
+      {!readOnly && (
+        // Out of the tab order for the same reason the diff's gutter button is:
+        // a document has hundreds of these, and the chapter's own form is the
+        // keyboard path to the same thing.
+        <button
+          type="button"
+          className="md-block-add"
+          title={label}
+          aria-label={label}
+          tabIndex={-1}
+          onClick={onPick}
+        >
+          <Icon name="plus" />
+        </button>
+      )}
+      <div className="md md-doc prose" dangerouslySetInnerHTML={{ __html: rendered }} />
+    </div>
+  );
+}
+
+/**
+ * A markdown file in the diff, read as the document it is.
+ *
+ * A PR that adds a spec renders as a thousand rows of `+ ## Heading` — the one
+ * form in which the document cannot be reviewed, because reviewing it means
+ * reading it. This is the same content through the same markdown renderer the
+ * rest of the cockpit uses, and it is not a detour off the review: the review's
+ * comments sit in it, under the paragraph they point at, and a paragraph you
+ * want to say something about takes a comment where it stands.
+ *
+ * What it cannot show is what a diff shows — the lines the PR took out, and
+ * which of these lines are new. So for a file the PR merely edits, the changed
+ * blocks are marked, the parts the diff never carried are marked as missing,
+ * and the diff itself is one click away.
+ */
+function MarkdownFile({
+  path,
+  doc,
+  comments,
+  renderComment,
+  readOnly,
+  chatBusy,
+  onAddLineComment,
+  onAskAboutLine,
+  onShowDiff,
+}: {
+  path: string;
+  doc: MdDocument;
+  comments: ReviewComment[];
+  renderComment: (c: ReviewComment) => ReactNode;
+  readOnly: boolean;
+  chatBusy: boolean;
+  onAddLineComment: (pick: LinePick, body: string) => void;
+  onAskAboutLine: (pick: LinePick, message: string) => void;
+  onShowDiff: () => void;
+}) {
+  const [pick, setPick] = useState<LinePick | null>(null);
+
+  // Every comment lands under the block that holds its line — or, for a line
+  // that is blank in the source, under the block it follows. None is dropped:
+  // a comment the cockpit can't place would be a comment the reader never
+  // sees, and it still posts at send time.
+  const placed = useMemo(() => {
+    const at = new Map<number, ReviewComment[]>();
+    const blocks = doc.items.flatMap((item, i) => (item.kind === "block" ? [{ item, i }] : []));
+    const rest: ReviewComment[] = [];
+    for (const c of comments) {
+      const hit =
+        c.line == null
+          ? undefined
+          : (blocks.filter((b) => b.item.from <= c.line!).pop() ?? blocks[0]);
+      if (!hit) {
+        rest.push(c);
+        continue;
+      }
+      at.set(hit.i, [...(at.get(hit.i) ?? []), c]);
+    }
+    return { at, rest };
+  }, [doc, comments]);
+
+  return (
+    <div className="md-file">
+      <div className="md-file-head">
+        <Icon name="file" />
+        <span className="md-file-name">{path}</span>
+        {doc.isNew ? (
+          <span className="tag tag-added">new file</span>
+        ) : (
+          <span className="faint" title="A diff carries the lines around a change, not the file.">
+            the diff's lines only — what the PR removed isn't here
+          </span>
+        )}
+        <span className="grow" />
+        <button className="btn btn-sm" onClick={onShowDiff} title="Back to the line-by-line diff">
+          show the diff
+        </button>
+      </div>
+      {doc.items.map((item, i) => (
+        <Fragment key={i}>
+          {item.kind === "gap" ? (
+            <div className="md-gap" title="These lines are in the file but not in the diff.">
+              ⋯ {item.lines.toLocaleString()} line{item.lines === 1 ? "" : "s"} the diff skips
+            </div>
+          ) : (
+            <MdBlockView
+              block={item}
+              path={path}
+              // In a file the PR creates, every line is new, so marking them
+              // all would say nothing.
+              changed={item.changed && !doc.isNew}
+              readOnly={readOnly}
+              onPick={() => setPick({ path, line: item.from, side: "new" })}
+            />
+          )}
+          {(placed.at.get(i) ?? []).map(renderComment)}
+          {item.kind === "block" && pick?.line === item.from && (
+            <LineComposer
+              pick={pick}
+              chatBusy={chatBusy}
+              onAdd={(body) => {
+                onAddLineComment(pick, body);
+                setPick(null);
+              }}
+              onAsk={(message) => {
+                onAskAboutLine(pick, message);
+                setPick(null);
+              }}
+              onClose={() => setPick(null)}
+            />
+          )}
+        </Fragment>
+      ))}
+      {placed.rest.map(renderComment)}
+    </div>
+  );
+}
+
+/**
+ * A chapter's diff: the files in the order the patch lists them, each drawn as
+ * the thing it is.
+ *
+ * Markdown files can be read as documents, and one that the PR *creates* opens
+ * that way — there, the diff markers carry nothing at all (every line is an
+ * addition) and cost the reader the document. Everything else, and every
+ * markdown file the PR merely edits, is a diff until asked otherwise.
+ */
+function DiffBlock({
+  patch,
+  comments,
+  renderComment,
+  readOnly,
+  chatBusy,
+  onAddLineComment,
+  onAskAboutLine,
+}: {
+  patch: string;
+  comments: ReviewComment[];
+  renderComment: (c: ReviewComment) => ReactNode;
+  readOnly: boolean;
+  chatBusy: boolean;
+  onAddLineComment: (pick: LinePick, body: string) => void;
+  onAskAboutLine: (pick: LinePick, message: string) => void;
+}) {
+  const files = useMemo(() => (patch.trim() ? splitDiffByFile(patch) : []), [patch]);
+  const docs = useMemo(
+    () =>
+      new Map(
+        files
+          .filter((f) => isMarkdownPath(f.path))
+          .map((f) => [f.path, readMarkdown(f.patch)] as const)
+          .filter(([, doc]) => doc.lines > 0),
+      ),
+    [files],
+  );
+  // The reader's choices, by path; absent means the default still stands. Kept
+  // for as long as they are on this review, like a chapter's fold.
+  const [choice, setChoice] = useState<Record<string, boolean>>({});
+  const isReading = (path: string) => choice[path] ?? docs.get(path)?.isNew ?? false;
+
+  const groups: { kind: "diff" | "read"; paths: string[]; patch: string }[] = [];
+  for (const file of files) {
+    const last = groups[groups.length - 1];
+    if (docs.has(file.path) && isReading(file.path)) {
+      groups.push({ kind: "read", paths: [file.path], patch: file.patch });
+      continue;
+    }
+    // Consecutive diff files stay in one diff2html render, so the chapter reads
+    // in patch order rather than in "documents first, code after".
+    if (last?.kind === "diff") {
+      last.paths.push(file.path);
+      last.patch += `\n${file.patch}`;
+    } else groups.push({ kind: "diff", paths: [file.path], patch: file.patch });
+  }
+
+  if (files.length === 0) return <p className="muted">No diff for this chapter.</p>;
+
+  const paths = new Set(files.map((f) => f.path));
+  const commentsOn = (of: (path: string) => boolean) => comments.filter((c) => of(c.path));
+
+  return (
+    <>
+      {groups.map((group) => {
+        const mine = new Set(group.paths);
+        if (group.kind === "read") {
+          const path = group.paths[0]!;
+          return (
+            <MarkdownFile
+              key={`read:${path}`}
+              path={path}
+              doc={docs.get(path)!}
+              comments={commentsOn((p) => p === path)}
+              renderComment={renderComment}
+              readOnly={readOnly}
+              chatBusy={chatBusy}
+              onAddLineComment={onAddLineComment}
+              onAskAboutLine={onAskAboutLine}
+              onShowDiff={() => setChoice((c) => ({ ...c, [path]: false }))}
+            />
+          );
+        }
+        return (
+          <DiffGroup
+            key={`diff:${group.paths[0]}`}
+            patch={group.patch}
+            comments={commentsOn((p) => mine.has(p))}
+            renderComment={renderComment}
+            readOnly={readOnly}
+            chatBusy={chatBusy}
+            onAddLineComment={onAddLineComment}
+            onAskAboutLine={onAskAboutLine}
+            onRead={(path) => setChoice((c) => ({ ...c, [path]: true }))}
+          />
+        );
+      })}
+      {/* A comment on a file this chapter's patch doesn't contain has no group
+          to sit in, and dropping it would lose it from the page entirely. */}
+      {commentsOn((p) => !paths.has(p)).map(renderComment)}
+    </>
+  );
+}
+
 function CommentCard({
   comment,
   onUpdate,
@@ -675,7 +973,7 @@ function ChapterSection({
             : " · no comments"}
           {heavy != null && !open && (
             <span title="Drawing this many lines at once would leave the page too slow to scroll. Open it if you want it — nothing else on the page is affected.">
-              {` · ${heavy.toLocaleString()} diff lines, folded to keep the page quick`}
+              {` · ${heavy.toLocaleString()} lines to draw, folded to keep the page quick`}
             </span>
           )}
         </span>
@@ -1509,12 +1807,27 @@ export function Detail({ reviewKey }: { reviewKey: string }) {
       : artifact.chapters;
   }, [artifact]);
 
-  /** How many diff lines each chapter is asking the browser to draw. */
+  /**
+   * How many diff lines each chapter is asking the browser to draw.
+   *
+   * A markdown file the PR creates is not drawn as a diff at all — it opens as
+   * a document, which is a block per paragraph rather than a table row per
+   * line. Measured on a 1,028-line spec: 2,874 nodes as a document against a
+   * diff's 12.7 nodes a row, so it asks for about a quarter of the work and
+   * folding it on the diff's arithmetic would hide a page that draws fine.
+   */
   const weights = useMemo(() => {
     const counts = diffLineCounts(artifact?.diff ?? "");
-    return new Map(
-      chapters.map((ch) => [ch.id, ch.files.reduce((n, f) => n + (counts.get(f) ?? 0), 0)]),
+    const asDocument = new Set(
+      splitDiffByFile(artifact?.diff ?? "")
+        .filter((p) => isMarkdownPath(p.path) && readMarkdown(p.patch).isNew)
+        .map((p) => p.path),
     );
+    const cost = (f: string) => {
+      const lines = counts.get(f) ?? 0;
+      return asDocument.has(f) ? Math.round(lines / 4) : lines;
+    };
+    return new Map(chapters.map((ch) => [ch.id, ch.files.reduce((n, f) => n + cost(f), 0)]));
   }, [artifact?.diff, chapters]);
   /** Lines, when there are enough of them that this chapter opens folded. */
   const heavy = (id: string) => {
diff --git a/web/src/Icon.tsx b/web/src/Icon.tsx
index 04ee863..0d63bb2 100644
--- a/web/src/Icon.tsx
+++ b/web/src/Icon.tsx
@@ -14,6 +14,7 @@ const PATHS: Record<string, string[]> = {
   edit: ["M12 20h9", "M16.5 3.5a2.12 2.12 0 0 1 3 3L7 19l-4 1 1-4Z"],
   drop: ["M3 6h18", "M8 6V4h8v2", "M6 6l1 14h10l1-14"],
   plus: ["M12 5v14", "M5 12h14"],
+  file: ["M14 3H7a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V8Z", "M14 3v5h5"],
   send: ["M22 2 11 13", "M22 2 15 22l-4-9-9-4Z"],
   eye: ["M2 12s3.5-7 10-7 10 7 10 7-3.5 7-10 7-10-7-10-7Z"],
   download: ["M12 3v12", "m7 12 5 5 5-5", "M5 21h14"],
diff --git a/web/src/mdblocks.test.ts b/web/src/mdblocks.test.ts
new file mode 100644
index 0000000..89e2d81
--- /dev/null
+++ b/web/src/mdblocks.test.ts
@@ -0,0 +1,118 @@
+import { describe, expect, it } from "vitest";
+import { isMarkdownPath, isNewFile, readMarkdown } from "./mdblocks";
+
+/** A patch that adds a whole file, the way `gh pr diff` spells one. */
+const added = (path: string, body: string) => {
+  const lines = body.split("\n");
+  return [
+    `diff --git a/${path} b/${path}`,
+    "new file mode 100644",
+    "index 0000000..1111111",
+    "--- /dev/null",
+    `+++ b/${path}`,
+    `@@ -0,0 +1,${lines.length} @@`,
+    ...lines.map((l) => `+${l}`),
+  ].join("\n");
+};
+
+describe("isMarkdownPath", () => {
+  it("takes .md and .markdown, and nothing else", () => {
+    expect(isMarkdownPath("docs/a.md")).toBe(true);
+    expect(isMarkdownPath("README.MARKDOWN")).toBe(true);
+    expect(isMarkdownPath("src/a.ts")).toBe(false);
+    expect(isMarkdownPath("a.mdx")).toBe(false);
+  });
+});
+
+describe("isNewFile", () => {
+  it("reads the file as created", () => {
+    expect(isNewFile(added("a.md", "# hi"))).toBe(true);
+  });
+
+  it("does not claim a modification is one", () => {
+    expect(isNewFile("diff --git a/a.md b/a.md\n--- a/a.md\n+++ b/a.md\n@@ -1 +1 @@\n-a\n+b")).toBe(
+      false,
+    );
+  });
+});
+
+describe("readMarkdown of an added file", () => {
+  const doc = readMarkdown(added("spec.md", "# Title\n\nA paragraph.\n\n- one\n- two\n"));
+
+  it("is the whole document", () => {
+    expect(doc.isNew).toBe(true);
+    expect(doc.items.filter((i) => i.kind === "gap")).toHaveLength(0);
+  });
+
+  it("splits into markdown's own top-level blocks", () => {
+    const blocks = doc.items.flatMap((i) => (i.kind === "block" ? [i] : []));
+    expect(blocks.map((b) => b.raw.trim())).toEqual(["# Title", "A paragraph.", "- one\n- two"]);
+  });
+
+  it("numbers each block with the lines it came from", () => {
+    const blocks = doc.items.flatMap((i) => (i.kind === "block" ? [i] : []));
+    expect(blocks.map((b) => [b.from, b.to])).toEqual([
+      [1, 1],
+      [3, 3],
+      [5, 6],
+    ]);
+  });
+
+  it("keeps a fenced block whole, markers and all", () => {
+    const fenced = readMarkdown(added("a.md", "before\n\n```ts\nconst a = 1;\n```\n\nafter"));
+    const blocks = fenced.items.flatMap((i) => (i.kind === "block" ? [i] : []));
+    expect(blocks[1]!.raw.trim()).toBe("```ts\nconst a = 1;\n```");
+    expect(blocks[1]!.from).toBe(3);
+    expect(blocks[1]!.to).toBe(5);
+  });
+});
+
+describe("readMarkdown of a modified file", () => {
+  const patch = [
+    "diff --git a/spec.md b/spec.md",
+    "--- a/spec.md",
+    "+++ b/spec.md",
+    "@@ -1,3 +1,4 @@",
+    " # Title",
+    " ",
+    "+A new paragraph.",
+    " Old text.",
+    "@@ -40,2 +41,2 @@",
+    "-was this",
+    "+is now this",
+    " trailing",
+  ].join("\n");
+  const doc = readMarkdown(patch);
+
+  it("marks only the blocks the PR touches", () => {
+    const blocks = doc.items.flatMap((i) => (i.kind === "block" ? [i] : []));
+    expect(blocks.map((b) => [b.raw.trim(), b.changed])).toEqual([
+      ["# Title", false],
+      ["A new paragraph.\nOld text.", true],
+      ["is now this\ntrailing", true],
+    ]);
+  });
+
+  it("says where the diff skipped part of the file", () => {
+    expect(doc.items.filter((i) => i.kind === "gap")).toEqual([{ kind: "gap", lines: 36 }]);
+  });
+
+  it("leaves out the lines the PR removes — they are not in the document", () => {
+    expect(doc.items.some((i) => i.kind === "block" && i.raw.includes("was this"))).toBe(false);
+  });
+});
+
+describe("readMarkdown of a deleted file", () => {
+  it("has nothing to read", () => {
+    const patch = [
+      "diff --git a/gone.md b/gone.md",
+      "deleted file mode 100644",
+      "--- a/gone.md",
+      "+++ /dev/null",
+      "@@ -1,2 +0,0 @@",
+      "-# Title",
+      "-body",
+    ].join("\n");
+    expect(readMarkdown(patch).lines).toBe(0);
+  });
+});
diff --git a/web/src/mdblocks.ts b/web/src/mdblocks.ts
new file mode 100644
index 0000000..09045c1
--- /dev/null
+++ b/web/src/mdblocks.ts
@@ -0,0 +1,137 @@
+// Reading a markdown file in the diff as the document it is.
+//
+// A PR that adds a 1,400-line spec renders as 1,400 rows of `+ # Heading`,
+// which is the one form in which nobody can review it: the reviewer's job
+// there is to read a document, and the diff markers carry no information at
+// all when every line is an addition. This turns a file's patch back into the
+// document, in blocks that still know which source lines they came from — so a
+// comment on line 188 can sit where line 188 is, and the parts the PR changed
+// can be marked as changed.
+
+import { marked } from "marked";
+
+export interface MdBlock {
+  kind: "block";
+  /** The markdown of this block alone, parsed by the caller. */
+  raw: string;
+  /** New-side line numbers this block spans, inclusive. */
+  from: number;
+  to: number;
+  /** The PR adds at least one of these lines. */
+  changed: boolean;
+}
+
+/** Lines between two hunks — present in the file, absent from the diff. */
+export interface MdGap {
+  kind: "gap";
+  lines: number;
+}
+
+export type MdItem = MdBlock | MdGap;
+
+export interface MdDocument {
+  items: MdItem[];
+  /** The PR creates this file, so the diff is the whole document. */
+  isNew: boolean;
+  /** New-side lines the diff carries — 0 means there is nothing to read. */
+  lines: number;
+}
+
+const MARKDOWN = /\.(md|markdown)$/i;
+
+export function isMarkdownPath(path: string): boolean {
+  return MARKDOWN.test(path);
+}
+
+/** Does this patch create the file? Then every line of it is in the diff. */
+export function isNewFile(patch: string): boolean {
+  return /^new file mode /m.test(patch) || /^--- \/dev\/null$/m.test(patch);
+}
+
+interface Line {
+  n: number;
+  text: string;
+  added: boolean;
+}
+
+/** The new side of a single file's patch: added and context lines, in order. */
+function newSide(patch: string): Line[] {
+  const out: Line[] = [];
+  let n = 0;
+  let inHunk = false;
+  for (const line of patch.split("\n")) {
+    const hunk = line.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/);
+    if (hunk) {
+      n = Number(hunk[1]);
+      inHunk = true;
+      continue;
+    }
+    if (!inHunk) continue;
+    if (line.startsWith("\\")) continue; // "\ No newline at end of file"
+    if (line.startsWith("-")) continue; // the old side isn't part of the document
+    if (line.startsWith("+") || line.startsWith(" ") || line === "") {
+      out.push({ n, text: line === "" ? "" : line.slice(1), added: line.startsWith("+") });
+      n++;
+    }
+  }
+  return out;
+}
+
+const newlines = (s: string) => (s.match(/\n/g) ?? []).length;
+
+/**
+ * The document a patch's new side reads as, block by block.
+ *
+ * Blocks are markdown's own top-level units (a paragraph, a heading, a fenced
+ * block, a whole list), because those are the units a reader points at — and
+ * because a block is the smallest thing that can be parsed on its own without
+ * changing what it means.
+ */
+export function readMarkdown(patch: string): MdDocument {
+  const lines = newSide(patch);
+  const isNew = isNewFile(patch);
+  const items: MdItem[] = [];
+
+  // Consecutive lines form a run; the holes between runs are the parts of the
+  // file the diff never showed us, and saying so is the honest thing to draw.
+  let run: Line[] = [];
+  const flush = () => {
+    if (run.length === 0) return;
+    const start = run[0]!.n;
+    const added = new Set(run.filter((l) => l.added).map((l) => l.n));
+    const text = run.map((l) => l.text).join("\n") + "\n";
+    // A token's `raw` picks up where the last one left off — concatenated they
+    // are the source again — so counting newlines through them walks the file
+    // exactly, whether or not a token happens to carry its own terminator.
+    let line = start;
+    for (const token of marked.lexer(text)) {
+      const raw = token.raw;
+      const body = raw.trimEnd();
+      if (body === "") {
+        line += newlines(raw);
+        continue;
+      }
+      const lead = raw.length - raw.trimStart().length;
+      const from = line + newlines(raw.slice(0, lead));
+      const to = from + newlines(body.slice(lead));
+      let changed = false;
+      for (let n = from; n <= to && !changed; n++) changed = added.has(n);
+      items.push({ kind: "block", raw: body.slice(lead), from, to, changed });
+      line += newlines(raw);
+    }
+    run = [];
+  };
+
+  for (const line of lines) {
+    const last = run[run.length - 1];
+    if (last && line.n !== last.n + 1) {
+      const gap = line.n - last.n - 1;
+      flush();
+      items.push({ kind: "gap", lines: gap });
+    }
+    run.push(line);
+  }
+  flush();
+
+  return { items, isNew, lines: lines.length };
+}
diff --git a/web/src/styles.css b/web/src/styles.css
index ef9c35c..bf909e1 100644
--- a/web/src/styles.css
+++ b/web/src/styles.css
@@ -1952,11 +1952,117 @@ button {
   color: var(--fg-3);
 }
 
-.md > :first-child {
+/* ---- a markdown file read as a document ---- */
+
+.md-file {
+  border: 1px solid var(--line-2);
+  border-radius: 4px;
+  background: var(--surface);
+  margin: 8px 0;
+  overflow: hidden;
+}
+
+/* Same header the diff gives a file, so the page reads as one list of files
+   whichever way each of them is drawn. */
+.md-file-head {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 12px;
+  border-bottom: 1px solid var(--line);
+  background: var(--bg);
+  font-size: 11.5px;
+}
+
+.md-file-name {
+  color: var(--fg);
+  font-weight: 600;
+}
+
+.md-block {
+  position: relative;
+  padding: 0 16px 0 32px;
+}
+
+.md-block .md {
+  /* The document's own measure. Prose that runs the width of a 1560px console
+     is prose nobody finishes a line of. */
+  max-width: 760px;
+}
+
+/* What the PR changed, in a file it did not create. The stripe is the only
+   thing the rendered document can say that the diff says with colour. */
+.md-block-changed::before {
+  content: "";
+  position: absolute;
+  left: 16px;
+  top: 2px;
+  bottom: 2px;
+  width: 2px;
+  border-radius: 2px;
+  background: var(--accent);
+}
+
+/* Same gesture as the diff's gutter button, in the same place: invisible until
+   the block it belongs to is under the pointer. */
+.md-block-add {
+  position: absolute;
+  left: 4px;
+  top: 4px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 18px;
+  height: 18px;
+  padding: 0;
+  border: none;
+  border-radius: 3px;
+  background: var(--accent);
+  color: #fff;
+  cursor: pointer;
+  opacity: 0;
+  transition: opacity 90ms;
+}
+
+.md-block:hover .md-block-add,
+.md-block-add:focus-visible {
+  opacity: 1;
+}
+
+/* The file continues, the diff doesn't. Saying so keeps the rendered document
+   from reading as the whole of one. */
+.md-gap {
+  margin: 4px 0;
+  padding: 4px 16px;
+  border-top: 1px solid var(--line-3);
+  border-bottom: 1px solid var(--line-3);
+  background: var(--bg);
+  color: var(--faint);
+  font-size: 10.5px;
+}
+
+.md-file .comment {
+  margin: 8px 16px;
+}
+
+.md-file .line-composer {
+  padding-left: 32px;
+  font-family: var(--mono);
+}
+
+/* The offer to stop reading the diff, in the diff's own file header. */
+.d2h-file-header .md-read-toggle {
+  margin-left: auto;
+}
+
+/* A card's markdown sits flush with the card's own padding. A document's does
+   not: it is cut into one `.md` per block, and zeroing the edges of each of
+   them would take away every margin the document has. */
+.md:not(.md-doc) > :first-child {
   margin-top: 0;
 }
 
-.md > :last-child {
+.md:not(.md-doc) > :last-child {
   margin-bottom: 0;
 }
 
@@ -2012,6 +2118,28 @@ button {
   color: var(--fg);
 }
 
+/* Inside a document, headings are the structure the reader navigates by, not
+   an aside in someone else's prose — so here they carry a real hierarchy. */
+.md-doc h1 {
+  font-size: 1.5em;
+  margin-top: 4px;
+}
+
+.md-doc h2 {
+  font-size: 1.22em;
+  margin-top: 22px;
+}
+
+.md-doc h3 {
+  font-size: 1.06em;
+}
+
+.md-doc h1,
+.md-doc h2 {
+  padding-bottom: 4px;
+  border-bottom: 1px solid var(--line);
+}
+
 .md h1 + p,
 .md h2 + p,
 .md h3 + p,
@@ -2197,6 +2325,13 @@ button {
   background: rgba(160, 106, 0, 0.1);
 }
 
+/* The same claim diff2html's own ADDED badge makes, for a file drawn without
+   one. */
+.tag-added {
+  color: var(--green);
+  background: rgba(26, 127, 90, 0.1);
+}
+
 /* "🚨 1 blocker · 🎨 2 nits · 72% sure of the findings" beside the verdict's
    reasoning. The grade of a single finding is not a chip — it opens the
    comment's own text. */

From 84279107ba3ed571e156e53be93509cb6635bfa4 Mon Sep 17 00:00:00 2001
From: Jacek Tomaszewski <jacek@fullstack.house>
Date: Wed, 2 Sep 2026 08:17:55 +0200
Subject: [PATCH 3/4] fix(cockpit): a comment on a removed line stays with its
 file, and says it posts in the body
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Click the diff's gutter `+` on a line the PR removed and the composer
warns that the comment posts on the file rather than the line — GitHub
takes inline comments on the new side only. What it didn't say is that
the card then leaves: with no line to anchor to it floated to the top of
the chapter, unlabelled and indistinguishable from an inline comment
that had lost its place. You wrote it on line 251 and it appeared above
the file.

Now it renders under its own file's header, where GitHub puts a
file-level comment, and carries the same kind of tag a drifted comment
does: "on the file — posts in the body". Only a comment naming no file
in the chapter's patch still floats above the diff, which is the one
case where there is nowhere else to put it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 SPEC.md            |  6 +++++
 web/src/Detail.tsx | 57 ++++++++++++++++++++++++++++++++++++++++------
 web/src/styles.css | 18 +++++++++++++++
 3 files changed, 74 insertions(+), 7 deletions(-)

diff --git a/SPEC.md b/SPEC.md
index 4e95e78..6a4c7ff 100644
--- a/SPEC.md
+++ b/SPEC.md
@@ -1423,6 +1423,12 @@ one is reported over the next.
   or request-changes with none), the cockpit points it out and offers a
   one-click chat turn asking the reviewer to re-true the verdict. It MUST
   NOT rewrite the verdict itself.
+- A comment that cannot post inline — drifted, or with no line at all, which
+  is what a comment on a line the PR *removed* becomes, GitHub taking inline
+  comments on the new side only — MUST say so where it is read; nothing else
+  tells it apart from an inline one. It renders with its file, under that
+  file's header, whenever the chapter's patch contains the file; only a
+  comment naming no file in that patch renders loose above the diff.
 - A sent review renders read-only. Rows filed by cerber are labeled with the
   filing reason ("reviewed on GitHub"), never with a bare "reviewed" that
   would read as a click the user never made.
diff --git a/web/src/Detail.tsx b/web/src/Detail.tsx
index 8ecb203..2b4cf1b 100644
--- a/web/src/Detail.tsx
+++ b/web/src/Detail.tsx
@@ -261,6 +261,8 @@ function DiffGroup({
   const onReadRef = useRef(onRead);
   onReadRef.current = onRead;
   const [slots, setSlots] = useState<{ id: string; el: HTMLElement }[]>([]);
+  /** One per file, for the comments that are about the file and not a line. */
+  const [fileSlots, setFileSlots] = useState<{ path: string; el: HTMLElement }[]>([]);
   const [pick, setPick] = useState<LinePick | null>(null);
   const [pickSlot, setPickSlot] = useState<HTMLElement | null>(null);
 
@@ -271,6 +273,7 @@ function DiffGroup({
     highlightDiff(root);
 
     const byFile = new Map<string, HTMLElement>();
+    const fileHolders: { path: string; el: HTMLElement }[] = [];
     root.querySelectorAll<HTMLElement>(".d2h-file-wrapper").forEach((wrapper, i) => {
       const name = wrapper.querySelector(".d2h-file-name")?.textContent?.trim();
       // diff2html renders the files in the order the patch lists them, so
@@ -280,6 +283,14 @@ function DiffGroup({
       if (path) {
         byFile.set(path, wrapper);
         wrapper.dataset.path = path;
+        // Where a comment about the file rather than a line goes — under the
+        // file's own header, the way GitHub shows one. It used to float to the
+        // top of the chapter, which left a comment you had just written on a
+        // removed line apparently nowhere near the line you wrote it on.
+        const fileHolder = document.createElement("div");
+        fileHolder.className = "file-comments";
+        wrapper.querySelector(".d2h-file-header")?.after(fileHolder);
+        fileHolders.push({ path, el: fileHolder });
         // A markdown file can be read as the document it is; the offer belongs
         // in its own header, next to its name, not in a control somewhere else
         // that the reader has to connect to this file.
@@ -311,6 +322,7 @@ function DiffGroup({
       placed.push({ id: c.id, el: inserted.holder });
     }
     setSlots(placed);
+    setFileSlots(fileHolders);
 
     // Registered before the read-only exit: a sent review takes no comments,
     // but it is still something to read, so its markdown still swaps.
@@ -409,6 +421,12 @@ function DiffGroup({
   }, [pick, slots, readOnly]);
 
   const unplaced = comments.filter((c) => !slots.some((s) => s.id === c.id));
+  // A comment with no row of its own still has a file. Only one that names no
+  // file in this diff has nowhere to go, and that one renders below.
+  const byFileSlot = fileSlots
+    .map((slot) => ({ ...slot, comments: unplaced.filter((c) => c.path === slot.path) }))
+    .filter((slot) => slot.comments.length > 0);
+  const homeless = unplaced.filter((c) => !fileSlots.some((s) => s.path === c.path));
   return (
     <>
       <div className="diff" ref={ref} />
@@ -416,6 +434,9 @@ function DiffGroup({
         const c = comments.find((x) => x.id === id);
         return c ? createPortal(renderComment(c), el, id) : null;
       })}
+      {byFileSlot.map(({ path, el, comments: mine }) =>
+        createPortal(<>{mine.map(renderComment)}</>, el, `file:${path}`),
+      )}
       {pick &&
         pickSlot &&
         createPortal(
@@ -435,7 +456,7 @@ function DiffGroup({
           pickSlot,
           `pick-${pick.path}-${pick.side}-${pick.line}`,
         )}
-      {unplaced.map((c) => renderComment(c))}
+      {homeless.map((c) => renderComment(c))}
     </>
   );
 }
@@ -555,6 +576,11 @@ function MarkdownFile({
           show the diff
         </button>
       </div>
+      {/* About the file rather than a block of it — under the header, where
+          the diff view puts the same thing. */}
+      {placed.rest.length > 0 && (
+        <div className="file-comments">{placed.rest.map(renderComment)}</div>
+      )}
       {doc.items.map((item, i) => (
         <Fragment key={i}>
           {item.kind === "gap" ? (
@@ -590,7 +616,6 @@ function MarkdownFile({
           )}
         </Fragment>
       ))}
-      {placed.rest.map(renderComment)}
     </div>
   );
 }
@@ -730,13 +755,26 @@ function CommentCard({
           {comment.line != null ? `:${comment.line}` : ""}
         </span>
         <span className={`tag tag-${comment.origin === "user" ? "yours" : tag}`}>{tag}</span>
-        {comment.drifted && (
+        {comment.drifted ? (
           <span
             className="tag tag-drift"
             title="The code this comment pointed at is gone from the diff, so it can't post inline."
           >
             drifted — posts in the body
           </span>
+        ) : (
+          comment.line == null && (
+            // Said out loud, because this is where a comment on a line the PR
+            // *removed* lands: GitHub takes inline comments on the new side
+            // only, so it became a comment about the file. Without the label
+            // it would read as an inline comment that lost its line.
+            <span
+              className="tag tag-drift"
+              title="A comment with no line — either about the file as a whole, or on a line the PR removed, which GitHub can't take inline."
+            >
+              on the file — posts in the body
+            </span>
+          )
         )}
         {!comment.drifted && comment.originalLine != null && comment.originalLine !== comment.line && (
           <span className="faint" title="This comment followed its code to a new line.">
@@ -943,10 +981,15 @@ function ChapterSection({
 }) {
   const patch = useMemo(() => patchForFiles(diff, chapter.files), [diff, chapter.files]);
   // Comments that can be anchored render inline under the line they point at
-  // (like GitHub); the rest — off-diff, or drifted — render as cards above it,
-  // which is also where they will end up in the review body.
+  // (like GitHub). One that can't still belongs to its file — a comment on a
+  // line the PR removed, or about the file as a whole — so it goes to the diff
+  // too, to sit under that file's header rather than at the top of the
+  // chapter. Only a comment naming no file in this chapter's patch floats
+  // above, which is also where it will end up in the review body.
   const inline = useMemo(() => inlineComments(patch, comments), [patch, comments]);
-  const floating = comments.filter((c) => !inline.includes(c));
+  const known = useMemo(() => new Set(splitDiffByFile(patch).map((f) => f.path)), [patch]);
+  const floating = comments.filter((c) => !inline.includes(c) && !known.has(c.path));
+  const placed = comments.filter((c) => inline.includes(c) || known.has(c.path));
   const renderComment = (c: ReviewComment) => (
     <CommentCard
       key={c.id}
@@ -997,7 +1040,7 @@ function ChapterSection({
           {floating.map(renderComment)}
           <DiffBlock
             patch={patch}
-            comments={inline}
+            comments={placed}
             renderComment={renderComment}
             readOnly={readOnly}
             chatBusy={chatBusy}
diff --git a/web/src/styles.css b/web/src/styles.css
index bf909e1..9db22cf 100644
--- a/web/src/styles.css
+++ b/web/src/styles.css
@@ -1370,6 +1370,24 @@ button {
   background: var(--surface);
 }
 
+/* Comments about the file rather than a line, under the file's own header —
+   a comment on a line the PR removed lands here, and finding it at the top of
+   the chapter instead would read as having lost it. */
+.file-comments:not(:empty) {
+  padding: 8px 12px 0;
+  border-bottom: 1px solid var(--line);
+  background: #fbfbfc;
+}
+
+.file-comments .comment {
+  margin: 0 0 8px;
+}
+
+.md-file .file-comments:not(:empty) {
+  border-bottom: none;
+  background: none;
+}
+
 /* Comments injected inline under the diff row they point at (GitHub-style). */
 .inline-comment-row td {
   padding: 0;

From 16b050c645a2633f0d9002553f66b09872cefe62 Mon Sep 17 00:00:00 2001
From: Jacek Tomaszewski <jacek@fullstack.house>
Date: Wed, 2 Sep 2026 08:27:51 +0200
Subject: [PATCH 4/4] fix(cockpit): the empty string at the end of a patch is
 not a line of the file
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`split("\n")` on a patch ending in a newline leaves an empty string
behind, and `newSide()` counted it as an empty context line. It is the
last file of a chapter's diff that gets one, so a markdown file the PR
*deleted* — which has no new side at all — came back with one line to
read, enough to clear the `lines > 0` guard and be offered as a
document that would then render empty. Every other file merely counted
one line too many, which the chapter fold's arithmetic reads.

`src/core/diff.ts` drops the same artifact for the same reason; this
helper now does too. The existing tests passed only because their
fixtures had no trailing newline — the two new ones fail without the
fix.

Found by Copilot's review on #49.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 web/src/mdblocks.test.ts | 34 +++++++++++++++++++++++++---------
 web/src/mdblocks.ts      |  9 ++++++++-
 2 files changed, 33 insertions(+), 10 deletions(-)

diff --git a/web/src/mdblocks.test.ts b/web/src/mdblocks.test.ts
index 89e2d81..9f39bd6 100644
--- a/web/src/mdblocks.test.ts
+++ b/web/src/mdblocks.test.ts
@@ -103,16 +103,32 @@ describe("readMarkdown of a modified file", () => {
 });
 
 describe("readMarkdown of a deleted file", () => {
+  const patch = [
+    "diff --git a/gone.md b/gone.md",
+    "deleted file mode 100644",
+    "--- a/gone.md",
+    "+++ /dev/null",
+    "@@ -1,2 +0,0 @@",
+    "-# Title",
+    "-body",
+  ].join("\n");
+
   it("has nothing to read", () => {
-    const patch = [
-      "diff --git a/gone.md b/gone.md",
-      "deleted file mode 100644",
-      "--- a/gone.md",
-      "+++ /dev/null",
-      "@@ -1,2 +0,0 @@",
-      "-# Title",
-      "-body",
-    ].join("\n");
     expect(readMarkdown(patch).lines).toBe(0);
   });
+
+  // `splitDiffByFile` hands the last file of a diff a patch ending in a
+  // newline, so `split` leaves an empty string behind. Counted as a line, it
+  // would give this file something to read and offer it as a document.
+  it("still has nothing to read when its patch ends in a newline", () => {
+    expect(readMarkdown(`${patch}\n`).lines).toBe(0);
+  });
+});
+
+describe("the empty string at the end of a patch", () => {
+  it("is not a line of the file", () => {
+    const doc = readMarkdown(`${added("a.md", "# Hi")}\n`);
+    expect(doc.lines).toBe(1);
+    expect(doc.items).toEqual([{ kind: "block", raw: "# Hi", from: 1, to: 1, changed: true }]);
+  });
 });
diff --git a/web/src/mdblocks.ts b/web/src/mdblocks.ts
index 09045c1..af21809 100644
--- a/web/src/mdblocks.ts
+++ b/web/src/mdblocks.ts
@@ -59,7 +59,9 @@ function newSide(patch: string): Line[] {
   const out: Line[] = [];
   let n = 0;
   let inHunk = false;
-  for (const line of patch.split("\n")) {
+  const lines = patch.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
     const hunk = line.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/);
     if (hunk) {
       n = Number(hunk[1]);
@@ -67,6 +69,11 @@ function newSide(patch: string): Line[] {
       continue;
     }
     if (!inHunk) continue;
+    // The empty string `split` leaves behind on a patch ending in a newline —
+    // not a line of the file. `src/core/diff.ts` drops it for the same reason,
+    // and it is the last file of a diff that gets one: counted, it would give a
+    // deleted markdown file a line to read and offer it as a document.
+    if (line === "" && i === lines.length - 1) continue;
     if (line.startsWith("\\")) continue; // "\ No newline at end of file"
     if (line.startsWith("-")) continue; // the old side isn't part of the document
     if (line.startsWith("+") || line.startsWith(" ") || line === "") {