From 3776590fa91acc19ca189e96c31d34824afc409a Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Wed, 5 Aug 2026 15:05:45 +0530
Subject: [PATCH 1/3] fix(website): represent changelog indent depth as a
 paragraph inset

Every indented line of a changelog entry rendered at one visual level
whatever its indentation, so a child point and its parent's peer came out
indistinguishable. No text was dropped, which is why the whole-corpus
no-drop guard never saw it; what was lost is structure.

A paragraph now carries the depth it was opened at, expressed purely as a
left inset: no marker, no type-size change, no rule. The single level of
flattening #1233 established is untouched, and no entry body renders a
second level of glyphs at any depth.

The rule both indented branches follow, stated once in the file: a bullet
marker establishes depth, a continuation inherits the open paragraph's.
The corpus decided that second half. It has zero bullets past two spaces
but 37 non-bullet lines at four or more across 10 files, every one wrapped
prose whose author aligned it under the text above, so reading depth off a
continuation would re-render those files today.

Depth clamps at three levels, and the inset comes from a literal lookup
because Tailwind cannot see a computed class name.
---
 .../modules/changelog/utils/render-entry.ts   | 72 +++++++++++++----
 website/test/changelog/render-entry.test.ts   | 81 ++++++++++++++++++-
 2 files changed, 136 insertions(+), 17 deletions(-)

diff --git a/website/modules/changelog/utils/render-entry.ts b/website/modules/changelog/utils/render-entry.ts
index 571127da2..2085122fd 100644
--- a/website/modules/changelog/utils/render-entry.ts
+++ b/website/modules/changelog/utils/render-entry.ts
@@ -28,8 +28,26 @@ function inline(s: string): string {
   return out;
 }
 
-/** One paragraph of an entry's body, as its soft-wrapped source lines. */
-type Para = string[];
+/**
+ * One paragraph of an entry's body, as its soft-wrapped source lines plus the
+ * indent depth it was opened at. Depth 1 is the entry's own level.
+ */
+type Para = { depth: number; lines: string[] };
+
+/**
+ * Depth a bullet's leading indent states. Two spaces per level, clamped at 3
+ * because a release note has no legitimate fourth level and the clamp is what
+ * stops a pathological source file emitting a runaway ladder.
+ */
+function depthOf(indent: number): number { return Math.min(Math.floor(indent / 2), 3); }
+
+/**
+ * Depth as a left inset, from a literal lookup. Tailwind v4 scans this tree
+ * for complete literal class strings, so a computed `pl-${depth * 4}` would
+ * generate no utility at all and the inset would silently do nothing while
+ * every test asserting on the class name still passed.
+ */
+const INSET: Record<number, string> = { 1: '', 2: ' pl-4', 3: ' pl-8' };
 
 /** Render the body of one changelog entry: h1 / h2 / bulleted lists / paragraphs. */
 export function renderEntryBody(md: string): string {
@@ -47,8 +65,21 @@ export function renderEntryBody(md: string): string {
   // changelog is one bullet per released change, and a second level of
   // glyphs under half of them is noise: the generator writes each squashed
   // commit subject as its own `*` line, which restated the entry title above
-  // it in 119 of the corpus's 378 indented bullets. So indentation controls
-  // grouping here, never bullet depth, and no entry body renders a list.
+  // it in 119 of the corpus's 378 indented bullets. So no entry body renders
+  // a list, at any depth.
+  //
+  // Depth is still REPRESENTED, as a left inset on the paragraph and nothing
+  // else (no marker, no type-size change, no rule), so a child point reads as
+  // subordinate to its parent rather than as its parent's peer. The rule both
+  // indented branches follow, stated once: a bullet marker ESTABLISHES depth,
+  // a continuation INHERITS the open paragraph's. The continuation half is
+  // the counter-intuitive one and the corpus decided it. There are zero
+  // bullets at four or more spaces across the 229 entry files, but there are
+  // 37 non-bullet lines at four or more, spread over 10 files, and every one
+  // is wrapped prose whose author aligned the continuation under the text
+  // above it. Reading depth off a continuation line would re-render those 10
+  // files today and lose the argument on the first release note anyone wraps
+  // by hand. Do not "fix" that branch to read its own indent.
   let itemOpen = false;
   let paras: Para[] = [];
   let open: Para | null = null;
@@ -59,14 +90,20 @@ export function renderEntryBody(md: string): string {
   // leaves `open` narrowed to `null` at the read below and the truthiness
   // guard there narrows it to `never`. Assigning at each call site keeps the
   // write in the enclosing function's own control-flow graph.
-  function startPara(text: string): Para { const p: Para = [text]; paras.push(p); return p; }
+  function startPara(text: string, depth: number): Para {
+    const p: Para = { depth, lines: [text] };
+    paras.push(p);
+    return p;
+  }
 
   function renderParas(ps: Para[]): string {
     // The overwhelmingly common entry is a single line with no body. Emit it
-    // bare so its markup is unchanged by the multi-paragraph support.
-    if (ps.length === 1) return inline(ps[0].join(' '));
-    return ps.map((lines) =>
-      `<p class="my-2 first:mt-0 last:mb-0">${inline(lines.join(' '))}</p>`).join('');
+    // bare so its markup is unchanged by the multi-paragraph support. Only
+    // the column-0 branch can open an item's first paragraph, so a lone
+    // paragraph is always depth 1; the guard says so rather than assuming it.
+    if (ps.length === 1 && ps[0].depth === 1) return inline(ps[0].lines.join(' '));
+    return ps.map((p) =>
+      `<p class="my-2 first:mt-0 last:mb-0${INSET[p.depth] ?? ''}">${inline(p.lines.join(' '))}</p>`).join('');
   }
 
   function flushItem() {
@@ -101,17 +138,20 @@ export function renderEntryBody(md: string): string {
       startList();
       itemOpen = true;
       paras = [];
-      open = startPara(line.slice(2).trim());
+      open = startPara(line.slice(2).trim(), 1);
     } else if (itemOpen && /^ {2,}[-*] /.test(line)) {
-      // Its own paragraph, marker dropped. Depth is not read, so a deeper
-      // run groups exactly like a 2-space one instead of nesting.
-      open = startPara(line.trim().slice(2).trim());
+      // Its own paragraph, marker dropped, at the depth its own indent
+      // states. This is the branch that ESTABLISHES depth.
+      const indent = (/^( +)/.exec(line)?.[1] ?? '').length;
+      open = startPara(line.trim().slice(2).trim(), depthOf(indent));
     } else if (itemOpen && /^ {2,}\S/.test(line)) {
       const text = line.trim();
       // Soft-wrapped continuation of the open paragraph, or the start of a
-      // fresh one when a blank line closed the last.
-      if (open) open.push(text);
-      else open = startPara(text);
+      // fresh one when a blank line closed the last. Depth-blind on purpose:
+      // it INHERITS, from the open paragraph or, when a blank line closed
+      // that one, from the last paragraph of the item.
+      if (open) open.lines.push(text);
+      else open = startPara(text, paras.length ? paras[paras.length - 1].depth : 1);
     } else if (line.trim() === '') {
       if (itemOpen) open = null;
       else flushItem();
diff --git a/website/test/changelog/render-entry.test.ts b/website/test/changelog/render-entry.test.ts
index 2da1dd90f..509206c01 100644
--- a/website/test/changelog/render-entry.test.ts
+++ b/website/test/changelog/render-entry.test.ts
@@ -13,7 +13,14 @@
  * that dumps a squashed commit body as indented `*` lines), so asserting
  * across every file is what stops one shape being fixed at the other's cost.
  * No entry body renders a second level of bullets: the page is one bullet
- * per released change, and everything under it is prose.
+ * per released change, and everything under it is prose. Depth is still
+ * represented, as a left inset on the paragraph, so a child point reads as
+ * subordinate rather than as its parent's peer. A bullet marker establishes
+ * that depth and a continuation line inherits the open paragraph's, which is
+ * why the corpus files carrying 4-space wrapped prose gain no inset.
+ *
+ * The corpus has zero bullets past two spaces, so the depth cases below are
+ * necessarily synthetic. A green corpus run proves nothing about them.
  */
 import test from 'node:test';
 import assert from 'node:assert/strict';
@@ -129,6 +136,78 @@ test('blank-separated indented bullets become paragraphs of ONE entry', () => {
   assert.equal(html.match(/<ul/g)?.length, 2, 'one entry list per section heading, and nothing nested');
 });
 
+test('a child point is inset, its parent and its parent peer are not', () => {
+  // Synthetic by necessity: the corpus has no bullet past two spaces, so this
+  // behaviour has no real fixture. Before the inset, `child of parent` and
+  // `sibling of parent` rendered identically and a reader could not tell
+  // which was subordinate to which.
+  const html = renderEntryBody([
+    '- **entry**',
+    '  - parent point',
+    '    - child of parent',
+    '    - second child',
+    '  - sibling of parent',
+  ].join('\n'));
+
+  const para = (text: string) => {
+    const m = new RegExp(`<p class="([^"]*)">${text}</p>`).exec(html);
+    assert.ok(m, `expected a paragraph for "${text}" in ${html}`);
+    return m[1];
+  };
+
+  assert.ok(!para('parent point').includes('pl-'), 'a 2-space bullet keeps the entry level');
+  assert.ok(!para('sibling of parent').includes('pl-'), 'a peer of the parent is at the parent level');
+  assert.ok(para('child of parent').includes('pl-4'), 'a 4-space bullet is inset one level');
+  assert.ok(para('second child').includes('pl-4'));
+  assert.notEqual(para('child of parent'), para('sibling of parent'), 'a child and a peer render differently');
+  // Still no second level of glyphs: the depth is the inset, nothing else.
+  assert.ok(!/<li>/.test(html));
+  assert.equal(html.match(/<ul/g)?.length, 1, 'only the entry list itself');
+});
+
+test('bullet depth clamps at three levels', () => {
+  const html = renderEntryBody([
+    '- **entry**',
+    '      - six spaces',
+    '          - ten spaces',
+    '                - sixteen spaces',
+  ].join('\n'));
+
+  for (const text of ['six spaces', 'ten spaces', 'sixteen spaces']) {
+    const m = new RegExp(`<p class="([^"]*)">${text}</p>`).exec(html);
+    assert.ok(m, `expected a paragraph for "${text}"`);
+    assert.ok(m[1].includes('pl-8'), `${text}: clamped to depth 3`);
+  }
+  // The clamp is what stops a pathological source emitting a runaway ladder,
+  // so nothing deeper than pl-8 is ever generated.
+  assert.ok(!/pl-1[26]|pl-2[04]/.test(html), 'no inset past the depth-3 class');
+});
+
+test('a 4-space continuation line inherits its bullet depth instead of reading its own', () => {
+  // cli/0.10.30.md wraps prose under a 2-space bullet at four spaces. All 37
+  // such lines in the corpus are wrapped prose, not nested points, so the
+  // continuation branch inherits rather than reads.
+  const html = renderEntryBody(bodyOf(`${CHANGELOG_DIR}cli/0.10.30.md`));
+
+  // The captured body spans inline markup (the glob in this line trips the
+  // italic rule), so match through tags rather than up to the first one.
+  const wrapped = /<p class="([^"]*)">#794: Fix block-comment-close bug([\s\S]*?)<\/p>/.exec(html);
+  assert.ok(wrapped, 'the bullet and its wrapped lines are one paragraph');
+  assert.ok(!wrapped[1].includes('pl-'), 'the wrapped continuation gains no inset');
+  assert.ok(wrapped[2].includes('closed the enclosing'), 'the 4-space lines stayed in that paragraph');
+});
+
+test('no corpus entry file renders an inset', () => {
+  // The invariance guard for the 229 files: every indented bullet on disk
+  // sits at exactly two spaces today, so the page must render byte-for-byte
+  // as it did before depth was represented.
+  for (const [label, md] of everyEntryFile()) {
+    const html = renderEntryBody(md);
+    assert.ok(!/class="[^"]*\bpl-4\b/.test(html), `${label}: emitted a depth-2 inset`);
+    assert.ok(!/class="[^"]*\bpl-8\b/.test(html), `${label}: emitted a depth-3 inset`);
+  }
+});
+
 test('no changelog file renders a nested list', () => {
   // Whole-corpus form of the two tests above, and the property the page is
   // meant to have: the only lists are the per-section entry lists, so an

From a0246bca328a10cef4ac19906b572162a896f49c Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Wed, 5 Aug 2026 15:51:50 +0530
Subject: [PATCH 2/3] fix(website): let an unmarked line go shallower than the
 bullet above it

Inheriting the last paragraph's depth outright was half a rule. Closing
prose written back at column 2 after a deeper bullet stayed inset under
that bullet, so a paragraph the author put at the entry level rendered as
a child of the point before it. Reachable from generated output too, since
backfill-changelog indents every commit-body line by two, so a body with
its own nested bullet lands at four and the body paragraph after it stays
at two.

The rule is now stated whole: only a bullet marker ESTABLISHES depth, so an
unmarked line inherits or goes shallower but never deeper. Both halves are
load-bearing and each has its own test. Inheriting keeps the corpus's 37
wrapped-prose lines out of an inset; going shallower is what this fixes.

Also two test corrections. The corpus guard asserted a property of
generated data, so it would have reddened the first release PR whose
squashed commit body carried a nested bullet, for rendering exactly right.
It now asks the weaker durable question, whether a file insets when its own
source has no deep bullet, which still catches a continuation branch that
reads its own indent. And a clamp assertion could not fail, since the inset
lookup can only emit the three classes it holds; the pl-8 loop above it was
already the real guard.
---
 .../modules/changelog/utils/render-entry.ts   | 37 +++++----
 website/test/changelog/render-entry.test.ts   | 77 +++++++++++++++----
 2 files changed, 87 insertions(+), 27 deletions(-)

diff --git a/website/modules/changelog/utils/render-entry.ts b/website/modules/changelog/utils/render-entry.ts
index 2085122fd..207036603 100644
--- a/website/modules/changelog/utils/render-entry.ts
+++ b/website/modules/changelog/utils/render-entry.ts
@@ -71,15 +71,17 @@ export function renderEntryBody(md: string): string {
   // Depth is still REPRESENTED, as a left inset on the paragraph and nothing
   // else (no marker, no type-size change, no rule), so a child point reads as
   // subordinate to its parent rather than as its parent's peer. The rule both
-  // indented branches follow, stated once: a bullet marker ESTABLISHES depth,
-  // a continuation INHERITS the open paragraph's. The continuation half is
-  // the counter-intuitive one and the corpus decided it. There are zero
-  // bullets at four or more spaces across the 229 entry files, but there are
-  // 37 non-bullet lines at four or more, spread over 10 files, and every one
-  // is wrapped prose whose author aligned the continuation under the text
-  // above it. Reading depth off a continuation line would re-render those 10
-  // files today and lose the argument on the first release note anyone wraps
-  // by hand. Do not "fix" that branch to read its own indent.
+  // indented branches follow, stated once: only a bullet marker ESTABLISHES
+  // depth, so an unmarked line can inherit or go shallower but never deeper.
+  // The corpus decided the inheriting half. There are zero bullets at four or
+  // more spaces across the 229 entry files, but there are 37 non-bullet lines
+  // at four or more, spread over 10 files, and every one is wrapped prose
+  // whose author aligned the continuation under the text above it. Letting a
+  // continuation read its own indent outright would re-render those 10 files
+  // today and lose the argument on the first release note anyone wraps by
+  // hand. The shallower half is what stops the opposite failure: closing
+  // prose written back at the entry level after a deeper bullet must not stay
+  // dragged under that bullet.
   let itemOpen = false;
   let paras: Para[] = [];
   let open: Para | null = null;
@@ -146,12 +148,19 @@ export function renderEntryBody(md: string): string {
       open = startPara(line.trim().slice(2).trim(), depthOf(indent));
     } else if (itemOpen && /^ {2,}\S/.test(line)) {
       const text = line.trim();
-      // Soft-wrapped continuation of the open paragraph, or the start of a
-      // fresh one when a blank line closed the last. Depth-blind on purpose:
-      // it INHERITS, from the open paragraph or, when a blank line closed
-      // that one, from the last paragraph of the item.
+      // Soft-wrapped continuation of the open paragraph, which simply joins
+      // it, or the start of a fresh one when a blank line closed the last.
+      // A fresh one can only INHERIT or go shallower, never deeper: an
+      // unmarked line cannot establish a level no bullet marker did, but it
+      // may return to one its own indent states. Both halves are load-bearing.
+      // Inheriting is what keeps the corpus's 37 wrapped-prose lines out of an
+      // inset, and the shallower half is what stops closing prose written back
+      // at the entry level from being dragged under the last deep bullet.
       if (open) open.lines.push(text);
-      else open = startPara(text, paras.length ? paras[paras.length - 1].depth : 1);
+      else {
+        const last = paras.length ? paras[paras.length - 1].depth : 1;
+        open = startPara(text, Math.min(depthOf((/^( +)/.exec(line)?.[1] ?? '').length), last));
+      }
     } else if (line.trim() === '') {
       if (itemOpen) open = null;
       else flushItem();
diff --git a/website/test/changelog/render-entry.test.ts b/website/test/changelog/render-entry.test.ts
index 509206c01..fa0df0dc1 100644
--- a/website/test/changelog/render-entry.test.ts
+++ b/website/test/changelog/render-entry.test.ts
@@ -15,9 +15,11 @@
  * No entry body renders a second level of bullets: the page is one bullet
  * per released change, and everything under it is prose. Depth is still
  * represented, as a left inset on the paragraph, so a child point reads as
- * subordinate rather than as its parent's peer. A bullet marker establishes
- * that depth and a continuation line inherits the open paragraph's, which is
- * why the corpus files carrying 4-space wrapped prose gain no inset.
+ * subordinate rather than as its parent's peer. Only a bullet marker
+ * establishes that depth, so an unmarked line inherits or goes shallower but
+ * never deeper: the corpus files carrying 4-space wrapped prose gain no
+ * inset, and closing prose written back at the entry level is not left
+ * dragged under the last deep bullet.
  *
  * The corpus has zero bullets past two spaces, so the depth cases below are
  * necessarily synthetic. A green corpus run proves nothing about them.
@@ -178,9 +180,47 @@ test('bullet depth clamps at three levels', () => {
     assert.ok(m, `expected a paragraph for "${text}"`);
     assert.ok(m[1].includes('pl-8'), `${text}: clamped to depth 3`);
   }
-  // The clamp is what stops a pathological source emitting a runaway ladder,
-  // so nothing deeper than pl-8 is ever generated.
-  assert.ok(!/pl-1[26]|pl-2[04]/.test(html), 'no inset past the depth-3 class');
+  // The `includes('pl-8')` loop above IS the clamp's guard: drop the clamp
+  // and the 10-space bullet asks for depth 5, which the inset lookup has no
+  // key for, so it renders with no inset at all and the loop reds. An extra
+  // "nothing deeper than pl-8" assertion would add nothing, since the lookup
+  // can only ever emit the three classes it holds.
+});
+
+test('closing prose written back at the entry level is not dragged under a deeper bullet', () => {
+  // The other half of the depth rule. An unmarked line inherits so the
+  // corpus's wrapped prose gains no inset, but it must still be able to go
+  // SHALLOWER, or a paragraph the author wrote at column 2 stays inset under
+  // whatever bullet happened to precede it.
+  const html = renderEntryBody([
+    '- **entry**',
+    '  - parent point',
+    '    - child of parent',
+    '',
+    '  Closing prose written at the entry level.',
+  ].join('\n'));
+
+  const closing = /<p class="([^"]*)">Closing prose written at the entry level\.<\/p>/.exec(html);
+  assert.ok(closing, 'expected the closing paragraph');
+  assert.ok(!closing[1].includes('pl-'), 'a column-2 paragraph sits at the entry level');
+  // The deeper bullet it follows keeps its own inset.
+  assert.match(html, /<p class="[^"]*pl-4[^"]*">child of parent<\/p>/);
+});
+
+test('a paragraph after a blank line cannot invent a level no bullet established', () => {
+  // The inheriting half, as a unit rather than via the corpus. These are the
+  // shape of the corpus's 37 four-plus-space non-bullet lines: wrapped prose
+  // aligned under the text above it, with no bullet at that depth anywhere.
+  const html = renderEntryBody([
+    '- **entry**',
+    '  * commit subject line',
+    '',
+    '    Wrapped prose the author aligned under the subject above it.',
+  ].join('\n'));
+
+  const wrapped = /<p class="([^"]*)">Wrapped prose the author aligned/.exec(html);
+  assert.ok(wrapped, 'expected the wrapped paragraph');
+  assert.ok(!wrapped[1].includes('pl-'), 'no bullet established depth 2, so the prose does not claim it');
 });
 
 test('a 4-space continuation line inherits its bullet depth instead of reading its own', () => {
@@ -197,14 +237,25 @@ test('a 4-space continuation line inherits its bullet depth instead of reading i
   assert.ok(wrapped[2].includes('closed the enclosing'), 'the 4-space lines stayed in that paragraph');
 });
 
-test('no corpus entry file renders an inset', () => {
-  // The invariance guard for the 229 files: every indented bullet on disk
-  // sits at exactly two spaces today, so the page must render byte-for-byte
-  // as it did before depth was represented.
+test('a corpus entry file insets only when its source carries a deep bullet', () => {
+  // The invariance guard for the 229 files. Every indented bullet on disk
+  // sits at exactly two spaces today, so every file must render with no inset
+  // at all, exactly as it did before depth was represented.
+  //
+  // Phrased against the SOURCE rather than as a flat "no file insets",
+  // because the corpus is generated data, not a fixture. backfill-changelog
+  // prefixes each commit-body line with two spaces, so a commit body carrying
+  // its own nested bullet lands at four and legitimately insets. A flat
+  // assertion would red the next release PR for rendering exactly right.
+  // This stays a coarse presence check, never a re-implementation of the
+  // renderer's run-splitting: the counterfactual that proves it still bites
+  // is making the continuation branch read its own indent, which insets files
+  // whose source has no deep bullet at all and reds this.
   for (const [label, md] of everyEntryFile()) {
-    const html = renderEntryBody(md);
-    assert.ok(!/class="[^"]*\bpl-4\b/.test(html), `${label}: emitted a depth-2 inset`);
-    assert.ok(!/class="[^"]*\bpl-8\b/.test(html), `${label}: emitted a depth-3 inset`);
+    const deepBullets = md.split('\n').filter((l) => /^ {4,}[-*] /.test(l)).length;
+    const insets = (renderEntryBody(md).match(/\bpl-[48]\b/g) || []).length;
+    if (deepBullets === 0) assert.equal(insets, 0, `${label}: inset with no deep bullet in its source`);
+    else assert.ok(insets > 0, `${label}: ${deepBullets} deep bullets rendered flat`);
   }
 });
 

From 52a74e486a8db058219e25aef1f0bbe56f8d64a0 Mon Sep 17 00:00:00 2001
From: Vivek <vivek7405@gmail.com>
Date: Wed, 5 Aug 2026 16:02:33 +0530
Subject: [PATCH 3/3] docs(website): state the corpus evidence for the depth
 rule exactly

The comments justifying the inherit-or-shallower rule cited 37 lines
across 10 files as the reason not to let an unmarked line read its own
indent. All 37 do render without an inset, but 31 of them are soft wraps
that join the paragraph above through a branch that reads no indent under
any implementation. Only 6 lines, in 4 files, reach the branch the rule
governs. Measured by rendering the whole corpus both ways.

Those 6 are also not the wrapped prose the shorthand claimed. They are
indented code blocks and one alignment table, which is a weaker and more
honest argument than the one the comment was making, and the next reader
should get the real one.

Also corrected the rule's own wording. It said an unmarked line may return
to a level its own indent states, but the ceiling is the paragraph
immediately before it, not the deepest level any bullet reached, so once an
item steps back out a later line cannot climb back in.

No behaviour change: all 229 corpus files still render byte-identically and
the 15 tests are unchanged in what they assert.
---
 .../modules/changelog/utils/render-entry.ts   | 47 ++++++++++++-------
 website/test/changelog/render-entry.test.ts   | 27 +++++++----
 2 files changed, 48 insertions(+), 26 deletions(-)

diff --git a/website/modules/changelog/utils/render-entry.ts b/website/modules/changelog/utils/render-entry.ts
index 207036603..e7798af13 100644
--- a/website/modules/changelog/utils/render-entry.ts
+++ b/website/modules/changelog/utils/render-entry.ts
@@ -73,15 +73,24 @@ export function renderEntryBody(md: string): string {
   // subordinate to its parent rather than as its parent's peer. The rule both
   // indented branches follow, stated once: only a bullet marker ESTABLISHES
   // depth, so an unmarked line can inherit or go shallower but never deeper.
-  // The corpus decided the inheriting half. There are zero bullets at four or
-  // more spaces across the 229 entry files, but there are 37 non-bullet lines
-  // at four or more, spread over 10 files, and every one is wrapped prose
-  // whose author aligned the continuation under the text above it. Letting a
-  // continuation read its own indent outright would re-render those 10 files
-  // today and lose the argument on the first release note anyone wraps by
-  // hand. The shallower half is what stops the opposite failure: closing
-  // prose written back at the entry level after a deeper bullet must not stay
-  // dragged under that bullet.
+  //
+  // The corpus decided the inheriting half, and the numbers are worth stating
+  // exactly, because the loose version of them ("37 lines, 10 files") reads
+  // as much stronger evidence than it is. There are zero bullets at four or
+  // more spaces across the 229 entry files, and 37 NON-bullet lines at four
+  // or more, spread over 10 files. All 37 render with no inset, but by two
+  // different mechanisms: 31 of them are soft wraps that join the paragraph
+  // above through the depth-blind branch below, which reads no indent under
+  // any implementation. Only 6 lines, in 4 files, actually reach the
+  // fresh-paragraph branch, and letting THAT branch read its own indent
+  // outright is what would re-render them. They are also not the wrapped
+  // prose the shorthand suggests: they are indented code blocks (a component
+  // class, an `export const metadata = {`) and one alignment table. Measured
+  // by rendering the whole corpus both ways, not by reading the sources.
+  //
+  // The shallower half stops the opposite failure: closing prose written back
+  // at the entry level after a deeper bullet must not stay dragged under that
+  // bullet.
   let itemOpen = false;
   let paras: Para[] = [];
   let open: Para | null = null;
@@ -149,13 +158,19 @@ export function renderEntryBody(md: string): string {
     } else if (itemOpen && /^ {2,}\S/.test(line)) {
       const text = line.trim();
       // Soft-wrapped continuation of the open paragraph, which simply joins
-      // it, or the start of a fresh one when a blank line closed the last.
-      // A fresh one can only INHERIT or go shallower, never deeper: an
-      // unmarked line cannot establish a level no bullet marker did, but it
-      // may return to one its own indent states. Both halves are load-bearing.
-      // Inheriting is what keeps the corpus's 37 wrapped-prose lines out of an
-      // inset, and the shallower half is what stops closing prose written back
-      // at the entry level from being dragged under the last deep bullet.
+      // it and reads no indent at all, or the start of a fresh one when a
+      // blank line closed the last.
+      //
+      // A fresh one is capped at the depth of the paragraph BEFORE it, so it
+      // inherits or goes shallower but never deeper. Note the ceiling is that
+      // one paragraph, not the deepest level any bullet in the item reached:
+      // once the item steps back out to the entry level, a later unmarked
+      // line cannot climb back in, which is the conservative direction for a
+      // signal as weak as leading whitespace. Both halves earn their keep,
+      // and each has its own test. The cap keeps the 6 corpus lines that
+      // reach this branch out of an inset; the shallower direction is what
+      // stops closing prose written back at the entry level from being
+      // dragged under the last deep bullet.
       if (open) open.lines.push(text);
       else {
         const last = paras.length ? paras[paras.length - 1].depth : 1;
diff --git a/website/test/changelog/render-entry.test.ts b/website/test/changelog/render-entry.test.ts
index fa0df0dc1..19cda844e 100644
--- a/website/test/changelog/render-entry.test.ts
+++ b/website/test/changelog/render-entry.test.ts
@@ -17,9 +17,10 @@
  * represented, as a left inset on the paragraph, so a child point reads as
  * subordinate rather than as its parent's peer. Only a bullet marker
  * establishes that depth, so an unmarked line inherits or goes shallower but
- * never deeper: the corpus files carrying 4-space wrapped prose gain no
- * inset, and closing prose written back at the entry level is not left
- * dragged under the last deep bullet.
+ * never deeper. Both directions have their own case below, because both are
+ * real: a deep line with no bullet at its depth gains no inset, and closing
+ * prose written back at the entry level is not left dragged under the last
+ * deep bullet.
  *
  * The corpus has zero bullets past two spaces, so the depth cases below are
  * necessarily synthetic. A green corpus run proves nothing about them.
@@ -208,9 +209,13 @@ test('closing prose written back at the entry level is not dragged under a deepe
 });
 
 test('a paragraph after a blank line cannot invent a level no bullet established', () => {
-  // The inheriting half, as a unit rather than via the corpus. These are the
-  // shape of the corpus's 37 four-plus-space non-bullet lines: wrapped prose
-  // aligned under the text above it, with no bullet at that depth anywhere.
+  // The inheriting half, as a unit rather than via the corpus. Deliberately
+  // NOT described as standing for the corpus's 37 deep non-bullet lines: 31
+  // of those are soft wraps that take the join branch instead and would pass
+  // this either way. Only 6 lines, in 4 files, reach the branch under test,
+  // and they are indented code blocks rather than prose. What this pins is
+  // the rule itself, that a line with no bullet at its depth does not claim
+  // that depth.
   const html = renderEntryBody([
     '- **entry**',
     '  * commit subject line',
@@ -223,10 +228,12 @@ test('a paragraph after a blank line cannot invent a level no bullet established
   assert.ok(!wrapped[1].includes('pl-'), 'no bullet established depth 2, so the prose does not claim it');
 });
 
-test('a 4-space continuation line inherits its bullet depth instead of reading its own', () => {
-  // cli/0.10.30.md wraps prose under a 2-space bullet at four spaces. All 37
-  // such lines in the corpus are wrapped prose, not nested points, so the
-  // continuation branch inherits rather than reads.
+test('a 4-space soft wrap joins its bullet paragraph instead of reading its own indent', () => {
+  // cli/0.10.30.md wraps prose under a 2-space bullet at four spaces. This is
+  // the JOIN branch, which reads no indent at all, and it is the shape 31 of
+  // the corpus's 37 deep non-bullet lines take. The fresh-paragraph branch is
+  // covered separately above; conflating the two overstates what either
+  // case proves.
   const html = renderEntryBody(bodyOf(`${CHANGELOG_DIR}cli/0.10.30.md`));
 
   // The captured body spans inline markup (the glob in this line trips the