From af01cd807a00420e8abb3f7360f5eb6efb517738 Mon Sep 17 00:00:00 2001
From: stanlyzoolo <51911715+stanlyzoolo@users.noreply.github.com>
Date: Sat, 8 Aug 2026 15:16:32 +0300
Subject: [PATCH 1/5] docs: add research note comparing panel [3] preprocessor
 with glow

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/research/glow-comparison.md | 80 ++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)
 create mode 100644 docs/research/glow-comparison.md

diff --git a/docs/research/glow-comparison.md b/docs/research/glow-comparison.md
new file mode 100644
index 0000000..b3553dc
--- /dev/null
+++ b/docs/research/glow-comparison.md
@@ -0,0 +1,80 @@
+# Panel `[3]`'s preprocessor vs glow: what each side does to a README
+
+This is a research snapshot, not a design doc: it records how keepkit's markdown
+preprocessing (`internal/model/readme_clean.go`, `cleanReadmeMarkdown`) differs from what
+glow does before glamour, and why the two tools made opposite choices. It answers one
+question — "why does keepkit carry ~650 lines of cleanup that glow lives without?" — and
+documents nothing the code must keep true. Verified against glow master, glamour v1.0.0
+(the version in `go.mod`) and keepkit as of 2026-08-08.
+
+## The architectural difference
+
+**glow has no content preprocessor.** Its entire pre-glamour surface is
+`utils.RemoveFrontmatter` (the CLI path strips a YAML frontmatter block) and
+`utils.WrapCodeBlock` (a non-markdown file is wrapped in a fence so it renders as one code
+block). Everything else is glamour *options* — `WithWordWrap`, `WithPreservedNewLines`,
+`WithBaseURL`, a style — i.e. decisions about how to show constructs, not rewrites of the
+document.
+
+That works because glow's decisions run **after parsing, on the goldmark AST**: glamour's
+ansi renderer maps each node kind to an element and styles it. keepkit's pass is the
+opposite — a **pre-parse string/regex rewrite** whose output is then handed to glamour.
+The trade is explicit:
+
+- keepkit pays for parser guarantees by hand: `rcSegments` re-derives fenced-block
+  boundaries, `rcMaskSpans` NUL-masks inline spans, and the "code is never rewritten" rule
+  needs its own machinery. glow gets all of that free — a rule that only exists as node
+  styling can never see the inside of a code node.
+- In exchange, keepkit can do what node styling cannot: delete a construct *differently
+  depending on content* (unwrap `[text](url)` but keep `<https://…>` autolinks, which
+  glamour renders through the same Link primitive — the reason a style-level route was
+  rejected in [`readme-pipeline.md`](../design/readme-pipeline.md)), drop whole lines
+  (badge headers, link-reference definitions, the title block), and collapse the blank
+  runs the removals leave behind.
+
+## Construct by construct
+
+"glow" below means bare glamour v1.0.0 behavior, since glow adds nothing of its own.
+
+| Construct | glow (= glamour v1.0.0) | keepkit |
+|---|---|---|
+| `![badge](url)` | alt text **plus the full URL** (`ansi/image.go` renders the `ImageText` format, then the destination) — a ten-badge header becomes a stack of shields.io URLs | removed whole, every form incl. reference/shortcut (`mdImageRe`, `rcRefRe`, `rcShortcutRe`): no image can render in a TTY |
+| `[text](url)` | text **plus the href** (`ansi/link.go`; `SkipHref` exists but only fires for table footnote links) | unwrapped to the text, href dropped — panel `[3]` links are not clickable; autolinks and bare URLs kept (there the URL *is* the content) |
+| Raw HTML | `HTMLBlock`/`RawHTML` nodes pass through `bluemonday.StrictPolicy` (`ansi/context.go`) — tags stripped, inner text kept | own pass: comments whole, `<picture>`/`<video>`/`<audio>`/`<svg>`/`<script>`/`<style>` **with bodies**, every other tag stripped via the `rcHTMLNames` allowlist (unknown names left as written) |
+| Emoji / `:shortcodes:` | real emoji pass through as text; glow does not enable `glamour.WithEmoji()`, so `:rocket:` stays literal | SMP pictographs stripped, `✅→✓` / `❌→✗` / `☑→✓` translated, shortcodes cut only when `definition.Github()` knows the name |
+| Leading H1 + tagline | untouched | `rcDropTitleBlock`: the card already shows the name and description one panel over |
+| Control characters | not cleaned — glow reads trusted local files | `cleanTerminalOutput` runs first: the input is an untrusted API blob headed for a viewport that re-emits it |
+| Frontmatter | removed (`utils.RemoveFrontmatter`) | not handled — GitHub READMEs do not carry it |
+
+## Observations
+
+- **bluemonday is already in keepkit's dependency tree.** glamour v1.0.0 depends on it and
+  sanitizes HTML nodes itself, so `microcosm-cc/bluemonday v1.0.27` sits in `go.mod` as an
+  indirect dependency. The design docs' "no general sanitizer (bluemonday) is pulled in"
+  predates glamour v1.0.0 and is now stale in its implication — still accurate in the
+  narrow sense that keepkit's own pass does not *use* it.
+- **The two HTML passes partially overlap.** For plain tags (`<kbd>`, `<div>`, `<p>`)
+  glamour now does roughly what keepkit's tag strip does. keepkit's pass is still
+  load-bearing for what glamour cannot do: cutting `<picture>`/`<svg>` **bodies** (the
+  StrictPolicy keeps inner text, so an inlined SVG logo would leak its text nodes),
+  removing comments *before* link-reference labels are collected (a commented-out
+  definition must not gate the unwrapping), and running before the parser at all — the
+  label set and the line drops depend on seeing the raw document.
+- **Why glow can afford to print URLs**: it is a full-screen pager where a URL is content
+  the user came to read — and on glamour master (not yet in v1.0.0; no `makeHyperlink`
+  there) links additionally become OSC 8 hyperlinks, i.e. actually clickable. Panel `[3]`
+  is a ~30-column strip beside the card where every href costs two wrapped lines of noise,
+  and `[o]`/`[c]` plus the card's clickable lines already cover "open it".
+- **Different performance budgets.** glow renders inside an async `tea.Cmd` and may take
+  its time; keepkit's pass runs synchronously inside `Update()` — which is where the
+  512 KiB cap, the `rcLineContent` slicing fix (8.4 s → milliseconds on adversarial
+  input) and `readmeRenderCache` memoization come from.
+
+## Why keepkit cannot simply adopt glow's shape
+
+Dropping the preprocessor and leaning on glamour alone would put badge URL stacks, hrefs
+after every link, literal shortcodes and tofu pictographs back on a 30-column panel fed
+untrusted remote content on the UI thread. The pieces glamour v1.0.0 did catch up on (tag
+stripping) are the cheapest part of the pass; the parts that make the panel readable —
+image and href removal, title-block drop, emoji policy, blank-run collapse — are exactly
+the ones that need content-dependent rewriting the AST-styling layer cannot express.

From acd1188beb1cb75094dfd23178c0dfac1f415bdb Mon Sep 17 00:00:00 2001
From: stanlyzoolo <51911715+stanlyzoolo@users.noreply.github.com>
Date: Sat, 8 Aug 2026 23:04:13 +0300
Subject: [PATCH 2/5] docs: add the readme-typography implementation plan

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/plans/20260808-readme-typography.md | 325 +++++++++++++++++++++++
 1 file changed, 325 insertions(+)
 create mode 100644 docs/plans/20260808-readme-typography.md

diff --git a/docs/plans/20260808-readme-typography.md b/docs/plans/20260808-readme-typography.md
new file mode 100644
index 0000000..4438bd9
--- /dev/null
+++ b/docs/plans/20260808-readme-typography.md
@@ -0,0 +1,325 @@
+# Panel [3] README typography: heading ladder, own chroma palette, dividers
+
+*Revised after plan-review (2026-08-08): list-marker coloring and table-separator coloring
+were verified to be inexpressible in glamour v1.0.0's StyleConfig — both are now recorded
+deliberate absences; the review's renderer-confirmation rule, the named breaking tests and
+the two Task-2 traps are folded in below.*
+
+## Overview
+
+Panel `[3]`'s glamour theme (`keepkitStyle`) currently keeps the heading ladder almost
+flat (H1 Accent, H2 Emphasis, H3–H6 Text bold — H3 and H4 are indistinguishable), leaves
+code-block syntax accents on glamour's stock pink/violet palette, and renders `---`
+dividers as a short stock dash run. This plan gives the panel a designed typography:
+
+- a per-level heading color ladder from a user-chosen teal→olive palette, plus `›` depth
+  markers for H3–H6;
+- a keepkit-owned chroma token palette in the same temperature, replacing the stock
+  accents that clash with it;
+- `✓`/`☐` task checkboxes, italic quotes, full-panel-width dividers.
+
+The palettes live in `internal/ui` as the **second sanctioned non-role palette** (the
+`ui.LanguageColor` precedent — with one honest difference stated in the doc comment:
+linguist's colors are externally-defined brand marks, these are keepkit-chosen shades, so
+this file is a deliberate, contained exception to "color is a role, not a shade", not an
+application of the existing one). They are exported var blocks — "easy to change" means
+edit one place + `go build` (decided against a config file and against live reload;
+chroma registration is one-shot per process anyway).
+
+**Contract change, stated up front:** panel `[3]`'s headings and code-fence accents move
+off `Theme` roles onto fixed hexes, so a future theme switch repaints the panel's body,
+links, quotes and inline code but **not** H1–H5 or the fence accents. Three places state
+the old contract ("switching every color in keepkit is switching one Theme value" —
+`internal/ui/theme.go`, `readme_style.go`'s doc comment, `docs/design/readme-pipeline.md`)
+and each is updated **in the task that breaks it**, not at the end.
+
+## Context (from discovery)
+
+- `internal/model/readme_style.go` — `keepkitStyle(t ui.Theme, dark)` clones
+  `styles.DarkStyleConfig`/`LightStyleConfig`, overrides via fresh pointers (`ptrTo`);
+  every new override MUST assign a fresh pointer or it restyles glamour process-wide
+  (`TestKeepkitStyleLeavesGlobalsUntouched`, JSON snapshot).
+- `internal/ui/lang.go` — the existing non-role palette; the new file sits beside it.
+- glamour v1.0.0 `ansi.StyleConfig` fields verified against the module cache **and by
+  rendering** (plan-review):
+  - `H1..H6`/`Heading` StyleBlocks with `Prefix`; `cascadeStylePrimitive` lets a non-nil
+    child field win over the parent, so per-level colors are safe under the `Heading`
+    base — but it only overrides `Prefix` when the child's is **non-empty**, so the stock
+    `"# "`/`"## "` come back if the explicit `H1.Prefix = ""`/`H2.Prefix = ""` lines are
+    lost (no existing test pins them);
+  - `styles.DarkStyleConfig.H6` carries an explicit `Bold: false` that beats inheritance —
+    H6 must keep its own `Bold = ptrTo(true)`;
+  - `Item.Color`/`Enumeration.Color` are **no-ops**: `BaseElement.doRender` paints both
+    the `• ` BlockPrefix and the enumerator with the *enclosing block's* style
+    (confirmed by render — a red `Item.Color` still produced document-gray bullets).
+    List-marker coloring is inexpressible in StyleConfig; recorded deliberate absence;
+  - table separators are drawn by lipgloss/table from glyph strings with **no color
+    call**; `Table`'s StylePrimitive styles **cell content** (header and body alike), so
+    separator coloring and header-only bolding are inexpressible; recorded deliberate
+    absence;
+  - `Task` StyleTask{`Ticked`,`Unticked`} and `HorizontalRule.Format` work as expected
+    (confirmed by render).
+- `renderReadme` (`internal/model/readme.go`) builds the renderer per render; the width
+  it wraps to is its own local **after the `readmeMinWrap` clamp** (readme.go:42-44) —
+  that clamped value, not `helpWrapWidth()` directly, is what the divider must use.
+  `readmeRenderCache` is already keyed by (theme, width), so a width-dependent style
+  re-renders on resize for free. The palettes are package vars — constant per process —
+  so they do not need to join the cache key.
+- Chroma caveat (documented in readme_style.go): glamour registers the built chroma style
+  under the process-global one-shot name `"charm"`; first render wins. Assertions must be
+  struct-level; a mid-session palette change cannot repaint fences — consistent with
+  `m.darkBG` resolved once at construction.
+- `Prefix` renders with the heading's own style — a depth marker cannot be `Dim`
+  separately; it carries the level color, which encodes the same depth twice (accepted).
+
+## Development Approach
+
+- **testing approach**: Regular (code first, then tests in the same task), plus the
+  tui-render mutation check: for every new assertion, revert the production edit, confirm
+  red, restore.
+- **renderer-confirmation rule (from plan-review):** a struct-level mutation check only
+  proves the struct field changed, never that glamour *reads* that field —
+  `Item.Color` passes both and does nothing. So **any override new to this file must be
+  confirmed against glamour's renderer once, in its own task** (read the element's
+  `Render` in the module cache, or do a one-off `forceColorProfile` render in the
+  throwaway vis file) **before** its struct test is written. Do not defer this to the
+  final vis task.
+- complete each task fully before moving to the next; run `go test -race ./internal/model
+  ./internal/ui` after each change, full `go test -race ./...` at the end.
+- every task's struct-level tests must keep `TestKeepkitStyleLeavesGlobalsUntouched`
+  green — that test is the fresh-pointer guard.
+- existing assertions that pin the old look are **updated, never deleted**; the ones this
+  plan breaks are named in their tasks.
+
+## Testing Strategy
+
+- **unit tests**: struct-level assertions on the returned `ansi.StyleConfig` (the
+  `TestKeepkitStyleRepaintsChroma` pattern) — tests have no TTY, rendered-output color
+  assertions are impossible (Ascii profile strips them) — each backed by the
+  renderer-confirmation rule above.
+- **visual check**: throwaway `internal/model/zz_vis_test.go` rendering a fixture README
+  through `renderReadme` at 80 and 120 columns, **in both `dark` and light variants**
+  (`forceColorProfile(t)` + `themeSeq(...)` when checking which color a run got); read
+  the output, then delete the file. This is where the `#08605f` (dark) and
+  `#a2ad59`/`#8e936d` (light, ~2.2:1/~2.9:1 on white) contrast risks are judged.
+- no e2e infrastructure in this project.
+
+## Progress Tracking
+
+- mark completed items with `[x]` immediately when done
+- add newly discovered tasks with ➕ prefix, blockers with ⚠️ prefix
+- update this file if implementation deviates from the design
+
+## Solution Overview
+
+Design decisions (brainstorm + review revisions, all user-approved):
+
+| Element | Decision |
+|---|---|
+| H1 | `#08605f`, bold — shared section (both variants) |
+| H2 | `#177e89`, bold — shared |
+| H3 | `#598381`, bold, prefix `› ` — shared |
+| H4 | `#8e936d`, bold, prefix `›› ` — shared |
+| H5 | `#a2ad59`, bold, prefix `››› ` — shared |
+| H6 | `Theme.Dim`, bold (explicit — stock `Bold:false` trap), prefix `›››› ` — **dark-only** (the file's rule: Theme tints beyond heading accents are dark-only; light keeps its stock H6, prefix still applied shared) |
+| Chroma tokens | Keyword / LiteralString / Comment / LiteralNumber / NameFunction from an own teal/olive var block; all other tokens inherited — dark-only like the existing repaint |
+| Inline code | unchanged (`Text` on `Surface`, shared rule with the card changelog) |
+| List markers | **deliberate absence** — `Item.Color`/`Enumeration.Color` are no-ops in glamour v1.0.0; recorded as a code comment, no override shipped |
+| Task lists | `Ticked: "✓ "`, `Unticked: "☐ "` — shared |
+| Divider `---` | `─` × clamped render width via `HorizontalRule.Format` — Format shared (colorless), color stays `Border` dark-only |
+| Blockquote | `Dim` (existing) + italic — dark-only |
+| Tables | **deliberate absence** — separators are lipgloss-drawn and uncolorable; `Table`'s style colors cell text; no header-only style exists; recorded as a code comment |
+| LinkText / Strong | unchanged (`Link` / `Emphasis`) |
+
+Known risk, accepted: `#08605f` is dark against the dark panel — the ladder reads
+"inverted" (H1 quietest). Judged at the vis step in **both variants**; reversing the
+ladder is a 5-line var edit and the user decides then.
+
+## Technical Details
+
+- New file `internal/ui/readme_palette.go` (shape pinned, not implementer's choice):
+  - `HeadingColors [5]lipgloss.Color` — H1..H5 (H6 is the `Dim` role, dark-only);
+  - `ChromaColors struct { Keyword, String, Comment, Number, Function lipgloss.Color }`
+    as one named var;
+  - doc comment: second sanctioned non-role palette; how it *differs* from
+    `LanguageColor` (invented shades vs external brand marks — a contained exception to
+    "role, not shade", accepted for content typography); the "edit here + go build"
+    contract; the theme-switch consequence (these do not follow a `Theme` change).
+- `keepkitStyle` gains a `width int` parameter (**added in Task 2**, the first task that
+  touches the signature, so later tasks and existing tests are rewritten once):
+  `HorizontalRule.Format = "\n" + strings.Repeat("─", width) + "\n"` set in Task 5;
+  width <= 0 keeps the stock format. `renderReadme` passes its **clamped** width local.
+  The `testReadmeStyle` seam path (`WithStandardStyle`) is unaffected.
+- Chroma overrides extend the existing bounded repaint: the clone stays
+  (`chromaCfg := *cfg.CodeBlock.Chroma`), each overridden token entry sets `Color` and
+  `BackgroundColor = Surface`. Note from review: chroma v2's `Style.Get` likely inherits
+  `Background` from the style's `Background` entry, so the explicit background may be
+  belt-and-braces rather than load-bearing — **verify before writing the rationale
+  comment** (do not copy the existing `Text`-entry comment's reason unverified).
+- Accepted caveat (record in a comment near the Format override): a `---` inside a
+  blockquote or list wraps at `width − indent`, and a run with no breakpoints overflows
+  rather than breaks. Rare (the stock short dash run never hit it), accepted.
+- Depth marker `›` (U+203A) and `☐` (U+2610) are East-Asian-Ambiguous decorative glyphs
+  in wrapped text — the accepted class (`⏺`/`↑`/`•` precedent). Pin in the glyph-width
+  test as documentation of the assumption (they travel through glamour's own wrap, not
+  `wrapText` — the pin documents, it does not cover that path).
+
+## Implementation Steps
+
+### Task 1: Heading + chroma palette var block in internal/ui
+
+**Files:**
+- Create: `internal/ui/readme_palette.go`
+- Create: `internal/ui/readme_palette_test.go`
+
+- [ ] create `readme_palette.go` with `HeadingColors [5]lipgloss.Color`
+      (`#08605f #177e89 #598381 #8e936d #a2ad59`) and `ChromaColors` (five teal/olive
+      token colors picked to sit against `Surface`)
+- [ ] doc comment per Technical Details: non-role palette, the *difference* from
+      `LanguageColor`, theme-switch consequence, edit contract
+- [ ] write tests: every entry parses as `#RRGGBB` (guards a typo'd hex lipgloss would
+      swallow), array length pinned at 5 — note: only the length pin is
+      mutation-checkable; the hex-shape assertion is a smoke guard, not a mutant killer
+- [ ] run tests — must pass before task 2
+
+### Task 2: Per-level heading colors, depth markers, width parameter
+
+**Files:**
+- Modify: `internal/model/readme_style.go`
+- Modify: `internal/model/readme.go`
+- Modify: `internal/model/readme_style_test.go`
+
+- [ ] add `width int` to `keepkitStyle`; thread through `renderReadme` (pass the
+      **clamped** width local) and every existing call site in tests; no Format use yet
+- [ ] renderer-confirmation: re-verify per-level heading color + prefix rendering once
+      via a `forceColorProfile` render (review already confirmed child-wins cascade and
+      prefix styling; this is the rule being followed, cheap here)
+- [ ] shared section: H1–H5 colors from `ui.HeadingColors` + `Bold` via `ptrTo`;
+      **keep the explicit `H1.Prefix = ""` and `H2.Prefix = ""`** (cascade only
+      overrides a non-empty child prefix — losing these silently brings `# `/`## ` back);
+      H3–H5 prefixes `"› "`/`"›› "`/`"››› "`; H6 prefix `"›››› "` shared
+- [ ] dark branch: `H6.Color = Theme.Dim` **and `H6.Bold = ptrTo(true)`** (stock dark H6
+      carries an explicit `Bold: false` that beats inheritance); drop the now-redundant
+      dark-branch `Heading`/`H6` *color* overrides only where the per-level colors
+      replace them
+- [ ] update the named breaking tests rather than deleting them:
+      `TestKeepkitStyleOverrides` (pins H1 Accent / H2 Emphasis → now palette),
+      `TestKeepkitStyleDarkOnlyOverrides` (pins dark Heading/H6 Text → new shape)
+- [ ] write struct tests: each level's Color/Bold/Prefix pinned, **including
+      `H1.Prefix == ""` / `H2.Prefix == ""` and `H6.Bold == true`**; H6 color dark-only
+- [ ] rewrite `keepkitStyle`'s doc comment: the theme-switch claim ("same one-value
+      theme switch") now holds for body/links/quotes/inline code only — say so here, in
+      the task that makes it true
+- [ ] add `›` to the glyph-width test (both runewidth conditions, Ambiguous accepted)
+- [ ] mutation-check each assertion (delete one level's override → red);
+      `TestKeepkitStyleLeavesGlobalsUntouched` stays green
+- [ ] run tests — must pass before task 3
+
+### Task 3: Own chroma token palette for code blocks
+
+**Files:**
+- Modify: `internal/model/readme_style.go`
+- Modify: `internal/model/readme_style_test.go`
+
+- [ ] renderer-confirmation: verify chroma token entries are read for a Go + shell fence
+      (one-off render), and whether the explicit per-token `BackgroundColor` is
+      load-bearing or inherited from the `Background` entry — write the comment from
+      what is observed, not from the plan
+- [ ] extend the bounded repaint (dark branch): `Keyword`, `LiteralString`, `Comment`,
+      `LiteralNumber`, `NameFunction` take `ui.ChromaColors` (+ `Surface` background per
+      the verification above); the fresh-pointer clone stays
+- [ ] **narrow, do not delete, the `reflect.DeepEqual` boundedness guard** in
+      `TestKeepkitStyleRepaintsChroma`: zero out the now-owned seven entries
+      (Background, Text + the five) and assert everything else is inherited verbatim;
+      rewrite its comment — the repaint is no longer "bounded to two entries", it is
+      bounded to a named seven
+- [ ] write struct tests: the five entries carry the palette colors; an untouched token
+      (e.g. `Operator`) still aliases the standard value
+- [ ] mutation-check each new assertion; globals-untouched snapshot stays green
+- [ ] run tests — must pass before task 4
+
+### Task 4: Task checkboxes, blockquote italic, recorded absences
+
+**Files:**
+- Modify: `internal/model/readme_style.go`
+- Modify: `internal/model/readme_style_test.go`
+
+- [ ] shared: `Task.Ticked = "✓ "`, `Task.Unticked = "☐ "` (renderer-confirmed by the
+      review; note the confirmation source in the comment)
+- [ ] dark branch: `BlockQuote.Italic = ptrTo(true)` (color stays `Dim`);
+      renderer-confirm italic is applied before writing the test
+- [ ] record the two deliberate absences as one code comment block on `keepkitStyle`:
+      list markers (`Item.Color`/`Enumeration.Color` are no-ops — BaseElement renders
+      BlockPrefix with the enclosing block's style) and tables (separators are
+      lipgloss-drawn with no color call; `Table`'s style colors cell content; no
+      header-only style)
+- [ ] add `☐` to the glyph-width test
+- [ ] write struct tests for Ticked/Unticked and Italic; mutation-check
+- [ ] run tests — must pass before task 5
+
+### Task 5: Full-width divider
+
+**Files:**
+- Modify: `internal/model/readme_style.go`
+- Modify: `internal/model/readme_style_test.go`
+
+- [ ] shared section: `HorizontalRule.Format = "\n" + strings.Repeat("─", width) + "\n"`
+      guarded on `width > 0` (width <= 0 keeps stock); color stays `Border` dark-only
+- [ ] record the accepted caveat comment: a `---` nested under an indent overflows
+      rather than breaks (no breakpoints in the run)
+- [ ] rewrite the stale half-sentence in the "deliberately missing" paragraph of
+      `keepkitStyle`'s doc comment — "`HorizontalRule` is a fixed string" stops being
+      true here; the injection objection (faking a heading rule needs a `---` the author
+      never wrote) still stands and remains the recorded reason
+- [ ] write struct tests: Format length equals width at two widths; width=0 falls back
+- [ ] mutation-check; run tests — must pass before task 6
+
+### Task 6: Visual check at 80/120 columns, both variants, ladder verdict
+
+**Files:**
+- Create (throwaway): `internal/model/zz_vis_test.go` — deleted in this same task
+
+- [ ] render a fixture README (headings H1–H6, go + shell fences, nested/ordered/task
+      lists, a quote, `---`, a table) through `renderReadme` at 80 and 120 columns,
+      **dark and light**; read the output
+- [ ] judge the `#08605f` contrast on dark and the `#a2ad59`/`#8e936d` contrast on
+      light; if the inverted ladder reads wrong, show the user both orders and let them
+      pick (5-line var edit either way)
+- [ ] confirm the divider spans the wrap width, the fence plate has no punch-throughs
+      around recolored tokens, checkboxes and depth markers align
+- [ ] delete `zz_vis_test.go`
+- [ ] run the full suite: `go test -race ./...`
+
+### Task 7: Verify acceptance criteria
+
+- [ ] every element of the Solution Overview table is implemented or carries its
+      recorded deliberate-absence comment (list markers, tables)
+- [ ] every new assertion has survived its mutation check (Task 1's hex-shape smoke
+      guard exempted, as recorded there)
+- [ ] `go vet ./...` and `golangci-lint run` clean
+- [ ] full suite green: `go test -race ./...`
+
+### Task 8: [Final] Update documentation
+
+- [ ] `docs/design/readme-pipeline.md`: rewrite the `keepkitStyle` section — the heading
+      ladder and its palette, the chroma palette, the width parameter, the divider, the
+      theme-switch contract change, the two deliberate absences; keep the existing
+      rationale style (what broke / why this shape)
+- [ ] `CLAUDE.md`: `internal/ui` package row mentions the second non-role palette beside
+      `LanguageColor`; the readme_style summary line follows the new shape (run
+      docs-sync)
+- [ ] move this plan to `docs/plans/completed/`
+
+## Post-Completion
+
+**Manual verification:**
+- run the real TUI (`go run .`) on a dark terminal with a README-heavy tool selected;
+  eyeball the ladder, fences and dividers at a real 80×24 window
+- preflight before commit/PR (build / vet / race tests / lint — the CI matrix)
+
+**External:**
+- demo-gifs: panel `[3]` is visible in `demo/hero.gif` — ask the user whether to
+  regenerate after merge (never regenerate without asking)
+- light-background terminals keep glamour's standard light chroma and stock H6, and get
+  the H1–H5 ladder as-is; the light render in Task 6 is where that is judged, and the
+  palette file is the one place to touch if it ever needs to fork by background

From ef5197cbfb2fbe5d5f52eb9ad5f61c60549e1329 Mon Sep 17 00:00:00 2001
From: stanlyzoolo <51911715+stanlyzoolo@users.noreply.github.com>
Date: Sun, 9 Aug 2026 00:30:34 +0300
Subject: [PATCH 3/5] feat: add a README colour palette for panel [3]'s
 typography
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Second non-role palette in internal/ui, and an exception for a different
reason than ui.LanguageColor: those are linguist's brand marks, these are
keepkit's own invented shades. A heading level is not a meaning Theme has
a word for, and six levels cannot be six roles, so the ladder lives here
instead of growing Theme by five shades-as-roles.

HeadingColors descends — bright H1 to dark H5. Measured against a dark
background the five run 7.2 : 5.4 : 4.1 : 3.6 : 2.4, so the other order
puts H1 below the 3:1 floor for bold text and below the Dim role used for
captions. TestHeadingColorsDescend pins the direction because reordering
is a one-line edit that breaks nothing else.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../20260808-readme-typography.md             |   0
 internal/ui/readme_palette.go                 |  98 ++++++++++++++++
 internal/ui/readme_palette_test.go            | 110 ++++++++++++++++++
 3 files changed, 208 insertions(+)
 rename docs/plans/{ => completed}/20260808-readme-typography.md (100%)
 create mode 100644 internal/ui/readme_palette.go
 create mode 100644 internal/ui/readme_palette_test.go

diff --git a/docs/plans/20260808-readme-typography.md b/docs/plans/completed/20260808-readme-typography.md
similarity index 100%
rename from docs/plans/20260808-readme-typography.md
rename to docs/plans/completed/20260808-readme-typography.md
diff --git a/internal/ui/readme_palette.go b/internal/ui/readme_palette.go
new file mode 100644
index 0000000..dead526
--- /dev/null
+++ b/internal/ui/readme_palette.go
@@ -0,0 +1,98 @@
+package ui
+
+import "github.com/charmbracelet/lipgloss"
+
+// This file is keepkit's SECOND sanctioned non-role palette, and it is an
+// exception rather than an application of the first one.
+//
+// languageColors (lang.go) is not a role because the colors are somebody
+// else's: linguist publishes them, and a cyan dot beside "go" is only worth
+// anything if it is GitHub's cyan. Nothing here has that excuse. These are
+// keepkit-chosen shades, invented for one panel, and the rule they break —
+// "color is a role, not a shade" (theme.go) — is broken knowingly: panel [3]
+// renders somebody's *document*, and a document needs a heading ladder and
+// syntax accents, which are typographic distinctions with no meaning in
+// Theme's vocabulary. Six heading levels cannot be six meanings. Rather than
+// grow Theme by five roles that mean "one step further down a heading ladder",
+// the ladder lives here, contained to the README pipeline, and Theme keeps
+// naming meanings only.
+//
+// The consequence, stated plainly because it is the price: a future theme
+// switch repaints panel [3]'s body, links, quotes and inline code and does NOT
+// repaint H1-H5 or the code-fence syntax accents. Those follow this file.
+//
+// "Easy to change" therefore means: edit the values below and `go build`.
+// There is deliberately no config file and no live reload — the chroma style is
+// registered once per process under a global name (see keepkitStyle), so a
+// mid-session palette change could not repaint a fence anyway.
+//
+// The two blocks share one temperature (teal running into olive) so a code
+// fence sitting under a heading reads as the same document rather than as two
+// palettes meeting.
+
+// HeadingColors is panel [3]'s heading ladder, H1 through H5, index 0 = H1.
+// It exists because the stock config renders H3 through H6 identically, so a
+// README's own structure was invisible below the second level. H6 is not here —
+// it takes the Theme.Dim role, since by the sixth level the honest statement is
+// "this is a heading and it is the quietest one".
+//
+// THE ORDER IS BRIGHT TO DARK, and that direction is the decision, not the
+// palette. keepkit is a dark-terminal app, and measured against a typical dark
+// background these five run 7.2 : 5.4 : 4.1 : 3.6 : 2.4 in contrast — so the
+// dark-to-bright reading puts the LEAST contrast on H1, below the 3:1 floor
+// for bold text and below the Dim role a caption uses. A document's top
+// heading being the hardest line on the page to read is not a ladder, it is
+// an inverted one. Loud at the top, quiet at the bottom.
+//
+// Accepted consequences of choosing for the dark terminal: on white the ends
+// swap, so H1 measures ~2.4 there and the lowest steps read best — and on
+// dark, H5 (2.4) sits below H6's Dim (4.2), which makes the ladder's last two
+// steps read as one. Both are the price of the ordering, and both were
+// weighed against a top-level heading nobody can find.
+//
+// Both background variants share the ladder: it is content typography, not a
+// tint, and the light variant of keepkitStyle takes these colors while keeping
+// glamour's stock light palette for everything else.
+var HeadingColors = [5]lipgloss.Color{
+	lipgloss.Color("#a2ad59"), // H1 — the loudest step
+	lipgloss.Color("#8e936d"), // H2
+	lipgloss.Color("#598381"), // H3
+	lipgloss.Color("#177e89"), // H4
+	lipgloss.Color("#08605f"), // H5 — the quietest
+}
+
+// ChromaPalette names the code-fence syntax accents keepkit owns. Every other
+// chroma token stays whatever the standard config chose — this is a bounded
+// repaint, not a full syntax theme (see keepkitStyle's comment for what the
+// boundary is and why).
+//
+// The five are the tokens a README's fences actually spend: a shell block is
+// mostly Keyword/LiteralString, a Go block adds NameFunction and Comment.
+type ChromaPalette struct {
+	// Keyword is `func`, `if`, `export` — the structure of the sample.
+	Keyword lipgloss.Color
+	// String is a quoted literal, the loudest thing in a shell fence.
+	String lipgloss.Color
+	// Comment sits below body brightness on purpose: it is the one part of a
+	// sample the reader may skip.
+	Comment lipgloss.Color
+	// Number is a literal count or version.
+	Number lipgloss.Color
+	// Function is a called or declared name.
+	Function lipgloss.Color
+}
+
+// ChromaColors is the code-fence palette, in the heading ladder's temperature
+// so a fence reads as part of the same document. The values are picked against
+// Theme.Surface (the plate a fence renders on), not against the terminal
+// background — Comment is the quietest of the five and still clears the plate.
+//
+// Dark backgrounds only. On white, glamour's stock light chroma stays: these
+// are chosen for a dark plate and three of them would be unreadable on paper.
+var ChromaColors = ChromaPalette{
+	Keyword:  lipgloss.Color("#4FA8A5"),
+	String:   lipgloss.Color("#A2AD59"),
+	Comment:  lipgloss.Color("#7C8577"),
+	Number:   lipgloss.Color("#C4B77A"),
+	Function: lipgloss.Color("#7FC4BE"),
+}
diff --git a/internal/ui/readme_palette_test.go b/internal/ui/readme_palette_test.go
new file mode 100644
index 0000000..14bcf94
--- /dev/null
+++ b/internal/ui/readme_palette_test.go
@@ -0,0 +1,110 @@
+package ui
+
+import (
+	"fmt"
+	"math"
+	"regexp"
+	"testing"
+
+	"github.com/charmbracelet/lipgloss"
+)
+
+// hexColorRe is the shape every value in this palette must have. lipgloss
+// swallows anything else silently — a typo'd digit count or a stray space
+// renders as the terminal default, which on a dark panel reads as "no style
+// applied" rather than as a bug.
+var hexColorRe = regexp.MustCompile(`^#[0-9a-fA-F]{6}$`)
+
+// TestReadmePaletteHexShape is a smoke guard, not a mutation-killable
+// assertion: it cannot fail for any value a careful edit would produce, and
+// that is the point — it catches the careless one. lipgloss.Color("#08605")
+// compiles, runs, and paints nothing.
+func TestReadmePaletteHexShape(t *testing.T) {
+	named := map[string]lipgloss.Color{
+		"ChromaColors.Keyword":  ChromaColors.Keyword,
+		"ChromaColors.String":   ChromaColors.String,
+		"ChromaColors.Comment":  ChromaColors.Comment,
+		"ChromaColors.Number":   ChromaColors.Number,
+		"ChromaColors.Function": ChromaColors.Function,
+	}
+	for i, c := range HeadingColors {
+		named[headingName(i)] = c
+	}
+	for name, c := range named {
+		if !hexColorRe.MatchString(string(c)) {
+			t.Errorf("%s = %q, want a #RRGGBB literal", name, string(c))
+		}
+	}
+}
+
+// headingName spells H1..H5 for a failure message.
+func headingName(i int) string {
+	return string(rune('H')) + string(rune('1'+i))
+}
+
+// TestHeadingColorsLength pins the ladder at five entries. keepkitStyle indexes
+// it by heading level, so a sixth entry (or a lost one) is either dead color or
+// an out-of-range panic on the first README with that heading in it. H6 is
+// deliberately absent — it takes the Theme.Dim role.
+func TestHeadingColorsLength(t *testing.T) {
+	if got := len(HeadingColors); got != 5 {
+		t.Errorf("len(HeadingColors) = %d, want 5 (H1..H5; H6 is the Dim role)", got)
+	}
+}
+
+// TestHeadingColorsAreDistinct pins what the ladder is FOR: the stock config
+// renders H3 and H4 identically, and a ladder with a duplicated step is that
+// bug again under a new name.
+func TestHeadingColorsAreDistinct(t *testing.T) {
+	seen := map[lipgloss.Color]int{}
+	for i, c := range HeadingColors {
+		if prev, dup := seen[c]; dup {
+			t.Errorf("%s and %s are both %q — the ladder has no step there",
+				headingName(prev), headingName(i), string(c))
+		}
+		seen[c] = i
+	}
+}
+
+// TestHeadingColorsDescend pins the ladder's DIRECTION, which is the decision
+// the values encode rather than an accident of which five shades were picked.
+// keepkit is a dark-terminal app, so brightness reads as prominence: the
+// reverse order puts the least contrast on H1, below the floor for bold text
+// and below the Dim role a caption uses, and a top-level heading nobody can
+// find is an inverted ladder rather than a ladder.
+//
+// A reordering is a one-line edit that changes nothing else and breaks no other
+// test — this is what stands in its way.
+func TestHeadingColorsDescend(t *testing.T) {
+	for i := 1; i < len(HeadingColors); i++ {
+		prev, cur := relLuminance(t, HeadingColors[i-1]), relLuminance(t, HeadingColors[i])
+		if cur >= prev {
+			t.Errorf("%s (%.4f) is not quieter than %s (%.4f) — the ladder must descend, loud at the top",
+				headingName(i), cur, headingName(i-1), prev)
+		}
+	}
+}
+
+// relLuminance is WCAG relative luminance, the same measure the contrast ratios
+// in HeadingColors' doc comment were computed with.
+func relLuminance(t *testing.T, c lipgloss.Color) float64 {
+	t.Helper()
+	hex := string(c)
+	if !hexColorRe.MatchString(hex) {
+		t.Fatalf("cannot measure %q — not a #RRGGBB literal", hex)
+	}
+	var ch [3]float64
+	for i := range ch {
+		var v int
+		if _, err := fmt.Sscanf(hex[1+i*2:3+i*2], "%02x", &v); err != nil {
+			t.Fatalf("parse %q: %v", hex, err)
+		}
+		s := float64(v) / 255
+		if s <= 0.03928 {
+			ch[i] = s / 12.92
+		} else {
+			ch[i] = math.Pow((s+0.055)/1.055, 2.4)
+		}
+	}
+	return 0.2126*ch[0] + 0.7152*ch[1] + 0.0722*ch[2]
+}

From bc099f814e82d37c8189573d2c103c58645c0886 Mon Sep 17 00:00:00 2001
From: stanlyzoolo <51911715+stanlyzoolo@users.noreply.github.com>
Date: Sun, 9 Aug 2026 00:30:34 +0300
Subject: [PATCH 4/5] feat: give the README panel a heading ladder, dividers
 and task marks
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The stock glamour config renders H3 through H6 identically, so a README's
own structure was invisible below the second level. Every heading level
now has its own colour plus a › depth marker from H3 down, H6 takes the
Dim role, and `---` becomes a rule across the panel instead of a short
dash run floating mid-line. Task lists get ✓/☐ rather than the source's
reprinted brackets, and a blockquote is italic as well as dim.

Code fences take five syntax colours of keepkit's own — keyword, string,
comment, number, function — bounding the chroma repaint to a named seven
rather than the two it covered before.

Fixes a fence's plate along the way. glamour's chroma formatter defaults
to terminal256 for every profile, ignoring the WithColorProfile next to
it, so Theme.Surface #343945 was quantized to index 237 (#3a3a3a) — one
plate reaching the screen in two colours, since the card's changelog code
line and the panel's own inline code both emit the exact value.
chromaFormatterFor maps the profile onto chroma's formatter instead.

keepkitStyle takes a width, which it spends only on the divider;
renderReadme passes the clamped wrap width so a narrow panel cannot get a
rule wider than itself.

Three things stay unstyled and are recorded as such: list markers
(Item.Color is a no-op — glamour paints the bullet with the enclosing
block's style), tables (separators are lipgloss-drawn with no colour
call), and the fence plate's ragged edge (only highlighted tokens carry a
background, so a wrapped line's remainder sits on the page).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 internal/model/readme.go            |  47 +++-
 internal/model/readme_style.go      | 189 ++++++++++++----
 internal/model/readme_style_test.go | 334 +++++++++++++++++++++++++---
 internal/model/render_test.go       |   9 +-
 4 files changed, 513 insertions(+), 66 deletions(-)

diff --git a/internal/model/readme.go b/internal/model/readme.go
index 2a5c22e..e2cce9c 100644
--- a/internal/model/readme.go
+++ b/internal/model/readme.go
@@ -5,6 +5,7 @@ import (
 
 	"github.com/charmbracelet/glamour"
 	"github.com/charmbracelet/lipgloss"
+	"github.com/muesli/termenv"
 
 	"github.com/stanlyzoolo/keepkit/internal/ui"
 )
@@ -20,6 +21,42 @@ const readmeMinWrap = 20
 // exercised.
 var testReadmeStyle string
 
+// chromaFormatterFor maps lipgloss's resolved color profile onto the chroma
+// formatter glamour should hand a code fence, following the profile the same
+// way WithColorProfile already does — one decision about the terminal's
+// capability, applied to both render paths instead of one.
+//
+// glamour's own default is "terminal256" for every profile, which quantizes the
+// fence's plate into the 256-color cube: Theme.Surface #343945 lands on index
+// 237 (#3a3a3a), a flat gray that has lost the blue cast. That put the SAME
+// plate on screen in two different colors — the card's changelog code line and
+// panel [3]'s inline code both render through lipgloss/termenv at the exact
+// value, while only the fence beside them was off. "terminal16m" emits the hex
+// verbatim and the three agree.
+//
+// It is a mapping rather than a constant because forcing truecolor on a
+// terminal that cannot take it is the same bug one layer down: an ANSI-only
+// session would be sent 24-bit sequences it renders as garbage. Ascii never
+// reaches chroma at all (glamour gates the whole path on
+// ColorProfile != Ascii), so its arm only has to be harmless.
+//
+// Pure, so both branches are table-testable — the shellCommand/planFor idiom;
+// the thin wrapper is the lipgloss.ColorProfile() call in renderReadme.
+func chromaFormatterFor(p termenv.Profile) string {
+	switch p {
+	case termenv.TrueColor:
+		return "terminal16m"
+	case termenv.ANSI256:
+		return "terminal256"
+	case termenv.ANSI:
+		return "terminal16"
+	case termenv.Ascii:
+		return "terminal256"
+	default:
+		return "terminal256"
+	}
+}
+
 // renderReadme turns raw README markdown into the ANSI text panel [3] shows,
 // in two layers. First the text is sanitized with cleanTerminalOutput — a
 // README is remote content that lands in a viewport verbatim, so it gets the
@@ -42,7 +79,10 @@ func renderReadme(raw string, width int, dark bool, t ui.Theme, about string) st
 	if width < readmeMinWrap {
 		width = readmeMinWrap
 	}
-	style := glamour.WithStyles(keepkitStyle(t, dark))
+	// keepkitStyle takes the CLAMPED width, the same number WithWordWrap gets
+	// below: it sizes the full-width divider, and a divider measured against
+	// the caller's raw request would overrun the panel on a narrow terminal.
+	style := glamour.WithStyles(keepkitStyle(t, dark, width))
 	if testReadmeStyle != "" {
 		style = glamour.WithStandardStyle(testReadmeStyle)
 	}
@@ -53,6 +93,11 @@ func renderReadme(raw string, width int, dark bool, t ui.Theme, about string) st
 		// lipgloss instead so a degraded profile (NO_COLOR, dumb term) yields
 		// plain text like every other panel.
 		glamour.WithColorProfile(lipgloss.ColorProfile()),
+		// A code fence renders through chroma, which has its own formatter and
+		// glamour's own default for it ("terminal256") ignores the profile
+		// above — so the fence quantized its plate while the inline code beside
+		// it did not. One capability answer, both paths.
+		glamour.WithChromaFormatter(chromaFormatterFor(lipgloss.ColorProfile())),
 		// A table link renders in its cell rather than as a numbered footnote
 		// under the table. The preprocessor already unwrapped the inline form;
 		// this covers an autolink that survived into a cell.
diff --git a/internal/model/readme_style.go b/internal/model/readme_style.go
index 00f08de..97227c3 100644
--- a/internal/model/readme_style.go
+++ b/internal/model/readme_style.go
@@ -1,6 +1,8 @@
 package model
 
 import (
+	"strings"
+
 	"github.com/charmbracelet/glamour/ansi"
 	"github.com/charmbracelet/glamour/styles"
 
@@ -14,27 +16,52 @@ import (
 // restyle glamour for the whole process.
 func ptrTo[T any](v T) *T { return &v }
 
+// headingPrefixes are the depth markers panel [3] puts in front of H3-H6. H1
+// and H2 get none: a document's top two levels are found by their color and
+// their weight, and a marker on them would only be noise on the lines that
+// need it least.
+//
+// From H3 down, color has run out of room — the ladder's lower steps sit close
+// together by construction — so depth is also spelled, one › per level below
+// H2. The markers are NOT dim: Prefix renders with the heading's own style,
+// which glamour gives no way around, so each marker carries its level's color
+// and states the depth twice. Accepted: saying it twice is the failure mode
+// worth having.
+//
+// › is U+203A, East-Asian Ambiguous like ⏺/↑/•/─ — the accepted class. It
+// travels through glamour's own wrap, not wrapText, and an over-wide
+// measurement there can only wrap a heading early.
+var headingPrefixes = [4]string{"› ", "›› ", "››› ", "›››› "} // H3, H4, H5, H6
+
 // keepkitStyle is panel [3]'s glamour theme: the standard config for the
-// terminal's background, with the accents moved onto the theme's roles so a
-// README reads as part of the app instead of pasted in from another one. It
-// takes the Theme rather than reading colors from a package — that is what puts
-// the readme panel under the same one-value theme switch as everything else
-// (the panel is re-rendered on the existing switchHelpMode path).
+// terminal's background, re-accented so a README reads as part of the app
+// instead of pasted in from another one.
 //
 // It CLONES rather than builds from scratch. StyleConfig has dozens of fields —
 // chroma tokens, table separators, list indents — and inheriting them means a
 // glamour upgrade that adds one cannot leave the panel with a hole in it.
 //
-// The light variant takes only the heading accents and the structural fixes:
-// the rest of the palette is chosen against a dark panel and would be
-// unreadable on white, so there the standard light colors stay.
+// Two palettes meet here, and the split is deliberate. The panel's *chrome* —
+// body text, links, quotes, inline code, the rules — comes from the Theme it is
+// handed, so it stays under the same one-value theme switch as the rest of the
+// app. The panel's *typography* — the H1-H5 heading ladder and (in Task 3) the
+// code-fence syntax accents — comes from ui.HeadingColors/ui.ChromaColors,
+// which are fixed shades and do not follow a Theme change. A heading level is
+// not a meaning Theme has a word for; see internal/ui/readme_palette.go for the
+// whole argument and for what a theme switch will and will not repaint.
+//
+// The light variant takes the heading ladder and the structural fixes: the
+// rest of the palette is chosen against a dark panel and would be unreadable on
+// white, so there the standard light colors stay.
 //
 // One part of the redesign is deliberately missing: a section heading is meant
-// to carry a border-colored rule out to the panel edge. StyleConfig cannot
-// express that — Prefix/Suffix are inline and HorizontalRule is a fixed string,
-// so the only way to fake it is to inject a `---` the author never wrote into
-// their README. Weight and Emphasis carry the heading on their own instead.
-func keepkitStyle(t ui.Theme, dark bool) ansi.StyleConfig {
+// to carry a border-colored rule out to the panel edge. HorizontalRule now IS
+// a full-width rule (see the Format override below), but it is the wrong one —
+// it fires on a `---` the author wrote, and the only way to put one under a
+// heading is to inject a `---` they never wrote into their README. Editing
+// somebody's document to decorate it is where this stops. Weight and the
+// ladder carry the heading on their own instead.
+func keepkitStyle(t ui.Theme, dark bool, width int) ansi.StyleConfig {
 	cfg := styles.LightStyleConfig
 	if dark {
 		cfg = styles.DarkStyleConfig
@@ -44,27 +71,80 @@ func keepkitStyle(t ui.Theme, dark bool) ansi.StyleConfig {
 	// panel frame is the breathing room.
 	cfg.Document.Margin = ptrTo[uint](0)
 
+	// The heading ladder, H1 through H5, one color per level. The stock config
+	// renders H3 through H6 identically, so a README's own structure was
+	// invisible below the second level; this is the fix, and it is why the
+	// colors are shades rather than roles.
+	//
+	// Bold is set per level rather than left to the Heading base: the stock H6
+	// carries an explicit Bold:false that beats inheritance, and a rule that
+	// only holds for five of six levels is not a rule.
+	for i, h := range []*ansi.StyleBlock{&cfg.H1, &cfg.H2, &cfg.H3, &cfg.H4, &cfg.H5} {
+		h.Color = ptrTo(string(ui.HeadingColors[i]))
+		h.Bold = ptrTo(true)
+	}
+
 	// The standard H1 is bright text on a colored plate — the loudest thing on
 	// the screen and the main reason a rendered README looked tasteless here.
-	// Accent and bold carries the same weight; the padding spaces go with the
-	// plate, since without a background they only read as a stray indent. (The
+	// The color and the weight carry it; the padding spaces go with the plate,
+	// since without a background they only read as a stray indent. (The
 	// preprocessor drops a README's leading H1 outright — it repeats the card's
 	// tool name — so this styles the ones further down.)
-	cfg.H1.Color = ptrTo(string(t.Accent))
 	cfg.H1.BackgroundColor = nil
-	cfg.H1.Bold = ptrTo(true)
-	cfg.H1.Prefix = ""
 	cfg.H1.Suffix = ""
 
-	// H2 is the panel's section heading — the brightest text role, matching the
-	// card's own. The "## " prefix goes with it: the standard style reprints the
-	// markdown marker in front of every heading, which is source, not text, and
-	// weight already says the line is a heading.
-	cfg.H2.Color = ptrTo(string(t.Emphasis))
-	cfg.H2.Bold = ptrTo(true)
+	// The prefixes are assigned, never left alone: glamour's cascade overrides
+	// a child's Prefix only when the child's is NON-EMPTY, so dropping these
+	// two lines does not fall back to the Heading base — it brings the stock
+	// "# "/"## " markers back, which are source rather than text.
+	cfg.H1.Prefix = ""
 	cfg.H2.Prefix = ""
-	for _, h := range []*ansi.StyleBlock{&cfg.H3, &cfg.H4, &cfg.H5, &cfg.H6} {
-		h.Prefix = ""
+	for i, h := range []*ansi.StyleBlock{&cfg.H3, &cfg.H4, &cfg.H5, &cfg.H6} {
+		h.Prefix = headingPrefixes[i]
+	}
+
+	// A task list is a README's own checklist — a roadmap, a support matrix —
+	// and the stock markers reprint the source's [ ]/[x] brackets, which is the
+	// same "source, not text" problem the heading prefixes had. ☐/✓ say the two
+	// states as one glyph each. Both are decorative (they carry no width
+	// arithmetic), and ☐ is U+2610, in the accepted Ambiguous class.
+	cfg.Task.Ticked = "✓ "
+	cfg.Task.Unticked = "☐ "
+
+	// Two things this file deliberately does NOT style, recorded so the next
+	// reader does not spend the afternoon finding out why:
+	//
+	//   - LIST MARKERS. Item.Color and Enumeration.Color exist and are no-ops:
+	//     ansi.BaseElement.doRender paints the "• " BlockPrefix and the
+	//     enumerator with the ENCLOSING block's style, so a red Item.Color
+	//     still produces document-gray bullets. Confirmed by render. There is
+	//     no StyleConfig field that reaches them.
+	//   - TABLES. The separators are drawn by lipgloss/table from glyph strings
+	//     with no color call at all, and the Table StylePrimitive styles CELL
+	//     CONTENT — header and body alike — so neither a border tint nor a
+	//     header-only weight is expressible. Confirmed by reading the renderer.
+	//
+	// Both would need a glamour change, not a config one.
+
+	// A `---` in a README is the author dividing their document, and the stock
+	// format answers it with a short dash run floating mid-panel, which reads
+	// as a typo rather than as a division. It becomes the panel's one full-width
+	// rule instead — the same ─ the frame is drawn with, so a divider and a
+	// border are visibly the same kind of thing.
+	//
+	// The width is keepkitStyle's only use of the parameter, and it is the
+	// CLAMPED wrap width renderReadme passes, the same number glamour wraps to.
+	// width <= 0 keeps the stock format: a caller that has no layout yet (a
+	// hand-built model, a test) must get something rather than an empty string.
+	//
+	// Accepted caveat: a `---` nested under a blockquote or a list item is
+	// indented by the enclosing block, so the run is then width−indent cells
+	// wide and, having no breakpoints, OVERFLOWS rather than wraps. Rare enough
+	// to accept — the stock short run could never hit it, so this is a new
+	// failure mode, but it costs one visually long line in a document shape
+	// almost nobody writes.
+	if width > 0 {
+		cfg.HorizontalRule.Format = "\n" + strings.Repeat("─", width) + "\n"
 	}
 
 	if !dark {
@@ -78,12 +158,16 @@ func keepkitStyle(t ui.Theme, dark bool) ansi.StyleConfig {
 	// as "this panel came from another app".
 	cfg.Document.Color = ptrTo(string(t.Text))
 
-	// Heading is the base every Hn cascades onto, so this is the H3-H5 rule;
-	// H6 needs its own, because the standard dark config singles it out with a
-	// green non-bold override.
-	cfg.Heading.Color = ptrTo(string(t.Text))
-	cfg.Heading.Bold = ptrTo(true)
-	cfg.H6.Color = ptrTo(string(t.Text))
+	// H6 is the ladder's floor and the one level that stays a Theme role: by
+	// the sixth heading the honest statement is "this is a heading and it is
+	// the quietest one", which is exactly what Dim means. It needs its own Bold
+	// for the reason stated above — the stock dark H6 is an explicit
+	// Bold:false, green, non-bold override that beats the Heading base.
+	//
+	// Dark only. On white the stock H6 stays: Dim is picked against a dark
+	// panel, and the depth marker assigned in the shared section is enough to
+	// place the level there.
+	cfg.H6.Color = ptrTo(string(t.Dim))
 	cfg.H6.Bold = ptrTo(true)
 
 	// The bold lead of a feature line ("Check agent visibility — …") is the
@@ -118,12 +202,30 @@ func keepkitStyle(t ui.Theme, dark bool) ansi.StyleConfig {
 	cfg.CodeBlock.Color = ptrTo(string(t.Text))
 	cfg.CodeBlock.BackgroundColor = ptrTo(string(t.Surface))
 
-	// The repaint is deliberately bounded to two entries: Background carries the
-	// plate, and Text needs the same background because chroma's formatter emits
-	// one per token — without it the plate is punched through wherever a token
-	// falls back to Text. Every other token entry is inherited unchanged, so the
-	// syntax accents stay the ones the standard config chose and no per-token
-	// judgement call is made here.
+	// The repaint is bounded to a NAMED SEVEN, and the boundary is the point:
+	// two entries carry the plate, five carry the syntax accents keepkit owns,
+	// and every other token is inherited from the standard config, so a glamour
+	// upgrade that retunes the rest arrives for free.
+	//
+	// The plate is Background + Text, and Text is the load-bearing one —
+	// verified by render, not by reading the struct. chroma's formatter emits a
+	// background per token and resolves an unset one up the token hierarchy to
+	// Text (its root), NOT to Background: with Background set and Text's
+	// background unset, the fence comes out with no plate at all. The converse
+	// is why the five accents below set Color only — their background is
+	// inherited from Text, and repeating it would be five more places for the
+	// plate to drift.
+	//
+	// The five are the tokens a README's fences actually spend (a shell block
+	// is mostly Keyword/LiteralString, a Go block adds NameFunction and
+	// Comment), and they come from ui.ChromaColors rather than from the Theme:
+	// "the color of a string literal" is not a meaning Theme has a word for.
+	// Dark only, like the plate — the stock light chroma is chosen for paper.
+	//
+	// Accepted caveat: chroma's terminal formatter downsamples to the 256-color
+	// cube regardless of the profile glamour was given, so what lands is each
+	// value's nearest slot, not the hex. The five were checked to land on five
+	// distinct slots; two near-neighbours would silently collapse into one.
 	//
 	// The clone is a fresh pointer for the reason ptrTo exists: the globals are
 	// aliased by styles.DefaultStyles, and writing through cfg.CodeBlock.Chroma
@@ -140,6 +242,11 @@ func keepkitStyle(t ui.Theme, dark bool) ansi.StyleConfig {
 		chromaCfg.Background.BackgroundColor = ptrTo(string(t.Surface))
 		chromaCfg.Text.Color = ptrTo(string(t.Text))
 		chromaCfg.Text.BackgroundColor = ptrTo(string(t.Surface))
+		chromaCfg.Keyword.Color = ptrTo(string(ui.ChromaColors.Keyword))
+		chromaCfg.LiteralString.Color = ptrTo(string(ui.ChromaColors.String))
+		chromaCfg.Comment.Color = ptrTo(string(ui.ChromaColors.Comment))
+		chromaCfg.LiteralNumber.Color = ptrTo(string(ui.ChromaColors.Number))
+		chromaCfg.NameFunction.Color = ptrTo(string(ui.ChromaColors.Function))
 		cfg.CodeBlock.Chroma = &chromaCfg
 	}
 
@@ -150,7 +257,13 @@ func keepkitStyle(t ui.Theme, dark bool) ansi.StyleConfig {
 	// Rules and quote bars in the panel-frame grays, so they read as structure
 	// rather than as content.
 	cfg.HorizontalRule.Color = ptrTo(string(t.Border))
+
+	// A blockquote is somebody else's voice inside the document — a warning
+	// box, a quoted issue, an upstream note. Dim already steps it back; italic
+	// is what says it is quoted rather than merely less important, and it is
+	// the one emphasis axis the panel has left unspent. Confirmed by render.
 	cfg.BlockQuote.Color = ptrTo(string(t.Dim))
+	cfg.BlockQuote.Italic = ptrTo(true)
 
 	return cfg
 }
diff --git a/internal/model/readme_style_test.go b/internal/model/readme_style_test.go
index 66f2b00..e6d495c 100644
--- a/internal/model/readme_style_test.go
+++ b/internal/model/readme_style_test.go
@@ -3,11 +3,13 @@ package model
 import (
 	"encoding/json"
 	"reflect"
+	"strconv"
 	"strings"
 	"testing"
 
 	"github.com/charmbracelet/glamour/ansi"
 	"github.com/charmbracelet/glamour/styles"
+	"github.com/muesli/termenv"
 
 	"github.com/stanlyzoolo/keepkit/internal/ui"
 )
@@ -22,6 +24,11 @@ func deref(t *testing.T, field string, p *string) string {
 	return *p
 }
 
+// testStyleWidth is the width the style tests build against. keepkitStyle only
+// spends it on the divider, so any positive value does; it is named so a
+// failure about a 60-cell rule is not read as a fixture coincidence.
+const testStyleWidth = 60
+
 // The theme is asserted at the struct level, not on rendered output: tests have
 // no TTY, so lipgloss.ColorProfile() is Ascii and glamour strips every color it
 // would emit. These fields are the only real coverage the theme can get.
@@ -32,18 +39,12 @@ func TestKeepkitStyleOverrides(t *testing.T) {
 			name = "dark"
 		}
 		t.Run(name, func(t *testing.T) {
-			cfg := keepkitStyle(ui.Default, dark)
+			cfg := keepkitStyle(ui.Default, dark, testStyleWidth)
 
-			if got := deref(t, "H1.Color", cfg.H1.Color); got != string(ui.Default.Accent) {
-				t.Errorf("H1.Color = %q, want %q", got, string(ui.Default.Accent))
-			}
 			// The bright plate is the main thing this theme exists to remove.
 			if cfg.H1.BackgroundColor != nil {
 				t.Errorf("H1.BackgroundColor = %q, want none", *cfg.H1.BackgroundColor)
 			}
-			if got := deref(t, "H2.Color", cfg.H2.Color); got != string(ui.Default.Emphasis) {
-				t.Errorf("H2.Color = %q, want %q", got, string(ui.Default.Emphasis))
-			}
 			if cfg.Document.Margin == nil || *cfg.Document.Margin != 0 {
 				t.Errorf("Document.Margin = %v, want 0 — the panel frame is the margin", cfg.Document.Margin)
 			}
@@ -59,17 +60,137 @@ func TestKeepkitStyleOverrides(t *testing.T) {
 	}
 }
 
+// TestKeepkitStyleHeadingLadder pins panel [3]'s typography: one color per
+// heading level from ui.HeadingColors, bold at every level, and a › depth
+// marker from H3 down. The ladder is what makes a README's own structure
+// visible below the second level — the stock config renders H3 through H6
+// identically, which is the bug this replaced.
+//
+// Both variants share it: these are content typography, not a Theme tint, so
+// unlike Document/Code/LinkText they are not gated on a dark background.
+func TestKeepkitStyleHeadingLadder(t *testing.T) {
+	for _, dark := range []bool{true, false} {
+		name := "light"
+		if dark {
+			name = "dark"
+		}
+		t.Run(name, func(t *testing.T) {
+			cfg := keepkitStyle(ui.Default, dark, testStyleWidth)
+			levels := []*ansi.StyleBlock{&cfg.H1, &cfg.H2, &cfg.H3, &cfg.H4, &cfg.H5}
+			for i, h := range levels {
+				lvl := i + 1
+				want := string(ui.HeadingColors[i])
+				if got := deref(t, "H"+string(rune('0'+lvl))+".Color", h.Color); got != want {
+					t.Errorf("H%d.Color = %q, want ui.HeadingColors[%d] = %q", lvl, got, i, want)
+				}
+				if h.Bold == nil || !*h.Bold {
+					t.Errorf("H%d is not bold — every level of the ladder carries weight as well as color", lvl)
+				}
+			}
+
+			// H1/H2 carry NO prefix, and the empty string is an assignment, not
+			// an omission: glamour's cascade overrides a child's Prefix only
+			// when the child's is non-empty, so losing these two lines brings
+			// the stock "# "/"## " markdown markers back rather than falling
+			// through to the Heading base.
+			if cfg.H1.Prefix != "" {
+				t.Errorf("H1.Prefix = %q, want none — the stock marker is source, not text", cfg.H1.Prefix)
+			}
+			if cfg.H2.Prefix != "" {
+				t.Errorf("H2.Prefix = %q, want none — the stock marker is source, not text", cfg.H2.Prefix)
+			}
+			// From H3 down the ladder's steps sit close together, so depth is
+			// also spelled: one › per level below H2.
+			for i, h := range []*ansi.StyleBlock{&cfg.H3, &cfg.H4, &cfg.H5, &cfg.H6} {
+				want := strings.Repeat("›", i+1) + " "
+				if h.Prefix != want {
+					t.Errorf("H%d.Prefix = %q, want %q", i+3, h.Prefix, want)
+				}
+			}
+			// H6 is bold in BOTH variants' intent only on dark; what is shared
+			// is the marker. The color split is asserted below.
+		})
+	}
+}
+
+// TestKeepkitStyleTaskMarkers pins the checklist glyphs. The stock markers
+// reprint the source's [ ]/[x] brackets — the same "source, not text" problem
+// the heading prefixes had — and ☐/✓ say each state in one glyph. Shared:
+// nothing about a checkbox depends on the background.
+func TestKeepkitStyleTaskMarkers(t *testing.T) {
+	for _, dark := range []bool{true, false} {
+		name := "light"
+		if dark {
+			name = "dark"
+		}
+		t.Run(name, func(t *testing.T) {
+			cfg := keepkitStyle(ui.Default, dark, testStyleWidth)
+			if cfg.Task.Ticked != "✓ " {
+				t.Errorf("Task.Ticked = %q, want %q", cfg.Task.Ticked, "✓ ")
+			}
+			if cfg.Task.Unticked != "☐ " {
+				t.Errorf("Task.Unticked = %q, want %q", cfg.Task.Unticked, "☐ ")
+			}
+		})
+	}
+}
+
+// TestKeepkitStyleDividerSpansWidth pins the panel's one full-width rule. The
+// stock format is a short dash run floating mid-panel, which reads as a typo
+// rather than as the author dividing their document.
+//
+// The width comes from the caller — renderReadme passes the CLAMPED wrap width,
+// the same number glamour wraps to — so the rule is asserted at two of them:
+// one number could be a coincidence, two say the parameter is actually used.
+// The Format is shared (colorless); the Border tint is dark-only and asserted
+// in TestKeepkitStyleDarkOnlyOverrides.
+func TestKeepkitStyleDividerSpansWidth(t *testing.T) {
+	for _, dark := range []bool{true, false} {
+		for _, w := range []int{40, 120} {
+			cfg := keepkitStyle(ui.Default, dark, w)
+			want := "\n" + strings.Repeat("─", w) + "\n"
+			if cfg.HorizontalRule.Format != want {
+				t.Errorf("dark=%v width=%d: HorizontalRule.Format = %q, want %d ─ cells",
+					dark, w, cfg.HorizontalRule.Format, w)
+			}
+		}
+
+		// A caller with no layout yet — a hand-built model, a test — keeps the
+		// stock format. A zero-width rule would be an empty string, which is a
+		// divider the author wrote and the panel silently dropped.
+		stock := styles.LightStyleConfig.HorizontalRule.Format
+		if dark {
+			stock = styles.DarkStyleConfig.HorizontalRule.Format
+		}
+		if got := keepkitStyle(ui.Default, dark, 0).HorizontalRule.Format; got != stock {
+			t.Errorf("dark=%v width=0: HorizontalRule.Format = %q, want the stock %q", dark, got, stock)
+		}
+	}
+}
+
 // The palette's text and border tints are chosen against a dark panel; on white
 // the standard light colors stay.
 func TestKeepkitStyleDarkOnlyOverrides(t *testing.T) {
-	dark, light := keepkitStyle(ui.Default, true), keepkitStyle(ui.Default, false)
+	dark, light := keepkitStyle(ui.Default, true, testStyleWidth), keepkitStyle(ui.Default, false, testStyleWidth)
 
-	if got := deref(t, "dark Heading.Color", dark.Heading.Color); got != string(ui.Default.Text) {
-		t.Errorf("dark Heading.Color = %q, want %q", got, string(ui.Default.Text))
+	// H6 is the ladder's floor and the one level that stays a Theme role: by
+	// the sixth heading "this is a heading and it is the quietest one" is the
+	// honest statement, which is what Dim means. Bold is explicit because the
+	// stock dark H6 is a green Bold:false override that beats the Heading base.
+	if got := deref(t, "dark H6.Color", dark.H6.Color); got != string(ui.Default.Dim) {
+		t.Errorf("dark H6.Color = %q, want the quietest role %q", got, string(ui.Default.Dim))
+	}
+	if dark.H6.Bold == nil {
+		t.Error("dark H6.Bold is nil — the stock dark H6 is an explicit Bold:false that beats inheritance")
+	} else if !*dark.H6.Bold {
+		t.Error("dark H6.Bold = false — the stock override was inherited instead of replaced")
 	}
-	if got := deref(t, "dark H6.Color", dark.H6.Color); got != string(ui.Default.Text) {
-		t.Errorf("dark H6.Color = %q, want %q", got, string(ui.Default.Text))
+	// On white the stock H6 stays: Dim is picked against a dark panel, and the
+	// depth marker already places the level there.
+	if light.H6.Color != styles.LightStyleConfig.H6.Color {
+		t.Error("light H6.Color was overridden — the stock light H6 is deliberate")
 	}
+
 	if got := deref(t, "dark LinkText.Color", dark.LinkText.Color); got != string(ui.Default.Link) {
 		t.Errorf("dark LinkText.Color = %q, want %q", got, string(ui.Default.Link))
 	}
@@ -79,6 +200,12 @@ func TestKeepkitStyleDarkOnlyOverrides(t *testing.T) {
 	if got := deref(t, "dark BlockQuote.Color", dark.BlockQuote.Color); got != string(ui.Default.Dim) {
 		t.Errorf("dark BlockQuote.Color = %q, want %q", got, string(ui.Default.Dim))
 	}
+	// Dim says "less important"; italic is what says "somebody else's voice".
+	// A quote needs both, and italic is the one emphasis axis the panel has
+	// left unspent.
+	if dark.BlockQuote.Italic == nil || !*dark.BlockQuote.Italic {
+		t.Error("dark BlockQuote is not italic — Dim alone reads as demoted, not as quoted")
+	}
 
 	// Document is the base every block cascades onto, so this is the panel's
 	// body-text rule: the same Text role the card's changelog notes render in.
@@ -124,14 +251,18 @@ func TestKeepkitStyleDarkOnlyOverrides(t *testing.T) {
 // fence actually looks like in a live session. glamour renders a fence through
 // rules.Chroma whenever ColorProfile != Ascii, and through the CodeBlock
 // StyleBlock fields otherwise — so on every real terminal the StyleBlock plate
-// was never reached and the fence kept the stock charm palette on the terminal's
-// own background. The repaint is bounded on purpose: Background and Text carry
-// the plate (chroma emits a background per token, so Text needs it too), every
-// other token entry stays exactly as the standard config wrote it. Dark only —
-// the light palette deliberately keeps the stock colors, so there the pointer
-// must still ALIAS the global.
+// is never reached and this is what the user sees.
+//
+// The repaint is bounded to a NAMED SEVEN: Background and Text carry the plate
+// (Text is the load-bearing one — chroma resolves an unset token background up
+// to Text, its root, not to Background), and five token entries carry the
+// syntax accents keepkit owns. Everything else is inherited from the standard
+// config, which is what the DeepEqual below is for: it is the guard against
+// the repaint quietly growing into a full syntax theme. Dark only — the light
+// palette deliberately keeps the stock colors, so there the pointer must still
+// ALIAS the global.
 func TestKeepkitStyleRepaintsChroma(t *testing.T) {
-	dark := keepkitStyle(ui.Default, true)
+	dark := keepkitStyle(ui.Default, true, testStyleWidth)
 	if dark.CodeBlock.Chroma == nil {
 		t.Fatal("dark CodeBlock.Chroma is nil")
 	}
@@ -147,19 +278,54 @@ func TestKeepkitStyleRepaintsChroma(t *testing.T) {
 		t.Errorf("dark Chroma.Text.Color = %q, want %q", got, string(ui.Default.Text))
 	}
 	if got := deref(t, "dark Chroma.Text.BackgroundColor", dark.CodeBlock.Chroma.Text.BackgroundColor); got != string(ui.Default.Surface) {
-		t.Errorf("dark Chroma.Text.BackgroundColor = %q, want the %q plate — chroma emits a background per token", got, string(ui.Default.Surface))
+		t.Errorf("dark Chroma.Text.BackgroundColor = %q, want the %q plate — without it the fence has NO plate, since chroma resolves an unset token background up to Text", got, string(ui.Default.Surface))
+	}
+
+	// The five syntax accents keepkit owns. Color only: the background is
+	// inherited from the Text entry above, and repeating it here would be five
+	// more places for the plate to drift.
+	for _, tt := range []struct {
+		name string
+		got  ansi.StylePrimitive
+		want string
+	}{
+		{"Keyword", dark.CodeBlock.Chroma.Keyword, string(ui.ChromaColors.Keyword)},
+		{"LiteralString", dark.CodeBlock.Chroma.LiteralString, string(ui.ChromaColors.String)},
+		{"Comment", dark.CodeBlock.Chroma.Comment, string(ui.ChromaColors.Comment)},
+		{"LiteralNumber", dark.CodeBlock.Chroma.LiteralNumber, string(ui.ChromaColors.Number)},
+		{"NameFunction", dark.CodeBlock.Chroma.NameFunction, string(ui.ChromaColors.Function)},
+	} {
+		if got := deref(t, "dark Chroma."+tt.name+".Color", tt.got.Color); got != tt.want {
+			t.Errorf("dark Chroma.%s.Color = %q, want the palette's %q", tt.name, got, tt.want)
+		}
+		if tt.got.BackgroundColor != nil {
+			t.Errorf("dark Chroma.%s.BackgroundColor = %q — the plate is inherited from Text, not repeated per token",
+				tt.name, *tt.got.BackgroundColor)
+		}
+	}
+
+	// A token the palette does NOT own still aliases the standard value: this
+	// is a bounded repaint, not a syntax theme.
+	want := deref(t, "stock Chroma.Operator.Color", styles.DarkStyleConfig.CodeBlock.Chroma.Operator.Color)
+	if got := deref(t, "dark Chroma.Operator.Color", dark.CodeBlock.Chroma.Operator.Color); got != want {
+		t.Errorf("dark Chroma.Operator.Color = %q, want the inherited %q — the repaint is bounded", got, want)
 	}
 
-	// Everything else is inherited verbatim: no per-token judgement calls.
+	// Everything outside the named seven is inherited verbatim. Zero the seven
+	// and the rest must match the standard config exactly — this is the guard
+	// against the repaint growing one token at a time.
 	stock := *styles.DarkStyleConfig.CodeBlock.Chroma
 	got := *dark.CodeBlock.Chroma
-	stock.Background, got.Background = ansi.StylePrimitive{}, ansi.StylePrimitive{}
-	stock.Text, got.Text = ansi.StylePrimitive{}, ansi.StylePrimitive{}
+	for _, p := range []*ansi.Chroma{&stock, &got} {
+		p.Background, p.Text = ansi.StylePrimitive{}, ansi.StylePrimitive{}
+		p.Keyword, p.LiteralString, p.Comment = ansi.StylePrimitive{}, ansi.StylePrimitive{}, ansi.StylePrimitive{}
+		p.LiteralNumber, p.NameFunction = ansi.StylePrimitive{}, ansi.StylePrimitive{}
+	}
 	if !reflect.DeepEqual(got, stock) {
-		t.Error("a chroma token other than Background/Text was repainted")
+		t.Error("a chroma token outside the named seven was repainted")
 	}
 
-	light := keepkitStyle(ui.Default, false)
+	light := keepkitStyle(ui.Default, false, testStyleWidth)
 	if light.CodeBlock.Chroma != styles.LightStyleConfig.CodeBlock.Chroma {
 		t.Error("light CodeBlock.Chroma was cloned — the light palette deliberately stays stock")
 	}
@@ -184,7 +350,7 @@ func TestKeepkitStyleLeavesGlobalsUntouched(t *testing.T) {
 	}
 
 	wantDark, wantLight := snapshot(t)
-	_, _ = keepkitStyle(ui.Default, true), keepkitStyle(ui.Default, false)
+	_, _ = keepkitStyle(ui.Default, true, testStyleWidth), keepkitStyle(ui.Default, false, testStyleWidth)
 	gotDark, gotLight := snapshot(t)
 
 	if gotDark != wantDark {
@@ -319,3 +485,119 @@ func TestRenderReadmeBadgeOnlyIsEmpty(t *testing.T) {
 		}
 	}
 }
+
+// TestChromaFormatterFollowsProfile pins that a code fence is told the same
+// thing about the terminal as everything else. glamour's own default is
+// "terminal256" for EVERY profile, which quantizes the fence's plate into the
+// 256-color cube — Theme.Surface #343945 lands on index 237 (#3a3a3a), a flat
+// gray with the blue cast gone — so the one plate rendered in two colors: the
+// card's changelog code line and panel [3]'s own inline code emit the exact
+// value through lipgloss/termenv, and only the fence between them was off.
+//
+// The mapping is not a constant "terminal16m", because forcing 24-bit
+// sequences onto an ANSI-only terminal is the same bug one layer down.
+func TestChromaFormatterFollowsProfile(t *testing.T) {
+	for _, tt := range []struct {
+		profile termenv.Profile
+		name    string
+		want    string
+	}{
+		{termenv.TrueColor, "TrueColor", "terminal16m"},
+		{termenv.ANSI256, "ANSI256", "terminal256"},
+		{termenv.ANSI, "ANSI", "terminal16"},
+		// Ascii never reaches chroma — glamour gates the whole path on
+		// ColorProfile != Ascii and falls through to the CodeBlock StyleBlock —
+		// so this arm only has to be harmless, and the stock value is that.
+		{termenv.Ascii, "Ascii", "terminal256"},
+	} {
+		if got := chromaFormatterFor(tt.profile); got != tt.want {
+			t.Errorf("chromaFormatterFor(%s) = %q, want %q", tt.name, got, tt.want)
+		}
+	}
+}
+
+// TestFencePlateMatchesTheCard is the assertion the mapping exists for, and it
+// is deliberately on RENDERED output rather than on the option: passing
+// WithChromaFormatter proves nothing about what chroma then emits, and the
+// whole defect was a value that survived every struct-level check.
+//
+// The comparison is against the card's own plate — ui.Styles.Surface, what
+// renderChangelogBlock paints a code line with — because "the same plate in two
+// panels" is the claim, not "some truecolor background".
+func TestFencePlateMatchesTheCard(t *testing.T) {
+	forceColorProfile(t) // TrueColor; without it the profile is Ascii and no color is emitted at all
+
+	card := ui.NewStyles(ui.Default).Surface.Render("x")
+	want := bgSequence(t, card)
+
+	out := renderReadme("# t\n\n```sh\necho hi\n```\n", 40, true, ui.Default, "")
+	var fence string
+	for _, line := range strings.Split(out, "\n") {
+		if strings.Contains(stripANSI(line), "echo hi") {
+			fence = line
+			break
+		}
+	}
+	if fence == "" {
+		t.Fatalf("no fence line in:\n%s", out)
+	}
+	got := bgSequence(t, fence)
+
+	// Both must be 24-bit. This is the half that actually regresses: drop the
+	// formatter mapping and the fence comes back as "48;5;237", an INDEXED
+	// color, which is the defect stated in its own terms.
+	for _, s := range []string{got, want} {
+		if !strings.HasPrefix(s, "48;2;") {
+			t.Fatalf("background %q is not 24-bit — the plate was quantized", s)
+		}
+	}
+
+	// Tolerance of one unit per channel, and it is termenv's, not ours:
+	// TrueColor.Color("#343945") emits 52;56;69 where the hex says 52;57;69.
+	// chroma writes the hex verbatim, so the card is the side that rounds — it
+	// has done so for every Surface plate in the app since the role existed.
+	// One unit out of 255 is not a disagreement about the color; a jump to a
+	// palette index is.
+	gr, wr := parseRGB(t, got), parseRGB(t, want)
+	for i := range gr {
+		if d := gr[i] - wr[i]; d > 1 || d < -1 {
+			t.Errorf("fence plate %q vs card plate %q — channel %d differs by %d, the two panels disagree about Theme.Surface",
+				got, want, i, d)
+		}
+	}
+}
+
+// bgSequence extracts the background half of the first SGR run that carries
+// one. glamour fuses foreground and background into a single sequence
+// (\x1b[38;2;…;48;2;…m), so a pattern anchored on \x1b[48; finds nothing — a
+// false negative this test was written around once already.
+func bgSequence(t *testing.T, s string) string {
+	t.Helper()
+	i := strings.Index(s, "48;")
+	if i < 0 {
+		t.Fatalf("no background in %q", s)
+	}
+	j := strings.Index(s[i:], "m")
+	if j < 0 {
+		t.Fatalf("unterminated escape in %q", s)
+	}
+	return s[i : i+j]
+}
+
+// parseRGB reads the three channels out of a "48;2;R;G;B" background.
+func parseRGB(t *testing.T, seq string) [3]int {
+	t.Helper()
+	parts := strings.Split(seq, ";")
+	if len(parts) != 5 {
+		t.Fatalf("not a 24-bit background: %q", seq)
+	}
+	var out [3]int
+	for i := range out {
+		v, err := strconv.Atoi(parts[i+2])
+		if err != nil {
+			t.Fatalf("channel %d of %q: %v", i, seq, err)
+		}
+		out[i] = v
+	}
+	return out
+}
diff --git a/internal/model/render_test.go b/internal/model/render_test.go
index 63e990e..88c8421 100644
--- a/internal/model/render_test.go
+++ b/internal/model/render_test.go
@@ -1037,8 +1037,15 @@ func TestVersionMsgsEmptyListNoPanic(t *testing.T) {
 // the removed ▎ status edge was in the same class, so the change is not a
 // regression. A bare lipgloss.Width==1 check cannot detect the ambiguity, so the
 // test measures both conditions explicitly.
+//
+// › (U+203A, panel [3]'s heading depth marker) and ☐ (U+2610, an unticked task
+// list item) join them as DOCUMENTATION rather than as coverage: both travel
+// through glamour's own wrap, which this test does not exercise, so the pin
+// records the assumption their placement was made under — the accepted
+// Ambiguous class, where an over-wide measurement can only wrap a line early
+// and never overflow a fixed-width block.
 func TestMarkerGlyphWidth(t *testing.T) {
-	for _, r := range []rune{'⏺', '↑'} {
+	for _, r := range []rune{'⏺', '↑', '›', '☐'} {
 		def := runewidth.Condition{EastAsianWidth: false}
 		if w := def.RuneWidth(r); w != 1 {
 			t.Errorf("RuneWidth(%q) default = %d, want 1", r, w)

From b4afbfedfc2b87b06600b3d38b55a4931de670e6 Mon Sep 17 00:00:00 2001
From: stanlyzoolo <51911715+stanlyzoolo@users.noreply.github.com>
Date: Sun, 9 Aug 2026 00:31:01 +0300
Subject: [PATCH 5/5] docs: record panel [3]'s typography and its two palettes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CLAUDE.md, ARCHITECTURE.md and docs/design/readme-pipeline.md carried the
old contract — one Theme value switches every colour in keepkit. That now
holds for the panel's chrome only: its headings and fence accents follow
ui/readme_palette.go and do not repaint on a theme switch. Each of the
three states the split where it already stated the old rule.

Also records what the renderer confirmed rather than what was assumed:
Text.BackgroundColor carries the whole fence plate (chroma resolves an
unset token background up to Text, not to Background), H1/H2's empty
Prefix is a load-bearing assignment, and H6 needs its own Bold.

Plan moved to docs/plans/completed/.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 ARCHITECTURE.md                               | 23 +++--
 CLAUDE.md                                     |  6 +-
 docs/design/readme-pipeline.md                | 24 ++++-
 .../completed/20260808-readme-typography.md   | 99 ++++++++++---------
 4 files changed, 93 insertions(+), 59 deletions(-)

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 2007e85..634ad45 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -58,7 +58,7 @@ graph TD
 | `internal/logx` | Session error journal: errors only, one lazily created file per session, imports only the stdlib-only `configdir` leaf. Package-level state — any package can log without threading a logger through |
 | `internal/model` | The entire Bubble Tea model: TUI state, key handling, rendering |
 | `internal/proc` | `DetachTTY` — run probes without a controlling terminal; `KillGroup` — process-group SIGKILL (plain `Kill` on Windows) |
-| `internal/ui` | `Theme` — the app's ten semantic color roles — and `Styles`, the whole style set built from one theme by `NewStyles`; `PlaceOverlay`, `StripANSI` |
+| `internal/ui` | `Theme` — the app's ten semantic color roles — and `Styles`, the whole style set built from one theme by `NewStyles`; the two non-role palettes (`LanguageColor`, and `HeadingColors`/`ChromaColors` for panel `[3]`); `PlaceOverlay`, `StripANSI` |
 | `internal/updater` | Detect the package manager that owns an installed binary and produce an update `Plan{Manager, Argv, Display}` |
 | `internal/version` | Detect the installed version locally — `InstalledVersion(t) (ver, present)`; GitHub API with a 24-hour cache; semver comparison (`IsNewer`) and the card's version spelling (`DisplayVersion`); keepkit's own release check (`SelfRepo`, `SelfLatest`) |
 
@@ -76,9 +76,9 @@ The `model` package is split across files within a single package:
 | `mode.go` | The `inputMode` enum and a handler per input mode |
 | `commands.go` | All `tea.Cmd` constructors (fetch commands, update streaming) and re-fetch predicates |
 | `render.go` | `View`, panel/card/status-bar/gauge/overlay renderers, mouse handling. The two list/card builders return their line index alongside the text: `buildCard` → clickable lines, `buildToolRows` → the tool-index ↔ screen-line maps. Carries the single-entry `changelogRenderCache` — the card is rebuilt on every spinner frame, so the release-notes conversion must not repeat |
-| `readme.go` | `renderReadme` — panel `[3]`'s pipeline: sanitize → preprocess → glamour, with a single-entry render cache |
+| `readme.go` | `renderReadme` — panel `[3]`'s pipeline: sanitize → preprocess → glamour, with a single-entry render cache; `chromaFormatterFor` maps the color profile onto chroma's formatter so a code fence's plate is not quantized away from the card's |
 | `readme_clean.go` | `cleanReadmeMarkdown(text, about)` — the pure README preprocessor. Fenced blocks and inline spans are segmented out first (code is never rewritten), then badges, hrefs, HTML and emoji are removed from what is left, and finally the leading H1 (plus a slogan under it that repeats `about`) is dropped as a title page the card already shows |
-| `readme_style.go` | `keepkitStyle(theme, dark)` — panel `[3]`'s glamour theme: the standard config cloned, its accents replaced from the `ui.Theme` it is handed |
+| `readme_style.go` | `keepkitStyle(theme, dark, width)` — panel `[3]`'s glamour theme: the standard config cloned, its *chrome* re-accented from the `ui.Theme` it is handed and its *typography* (heading ladder, fence accents) taken from `ui`'s fixed README palette; `width` sizes the full-width divider |
 | `textutil.go` | Pure text helpers (`wrapText`, `stripANSI`, `colorizeHelp`, `parseHelpEntries`, `markdownToLines` — the card's release-notes markdown → pre-wrapped tagged lines, …) |
 | `browser.go` | Opening URLs per `GOOS` |
 
@@ -229,8 +229,8 @@ Key invariants:
   it. The same rule governs the language band under it.
 - **The language stack is a picture; the fields below it are not.** A distribution
   gets `languages · ● go 99% · ● shell 1%` and a full-width band under it holding the
-  same shares in GitHub's own colors (`ui.LanguageColor`, the one palette a theme
-  switch must not repaint), closed by a blank row so the band reads as an edge rather
+  same shares in GitHub's own colors (`ui.LanguageColor`, one of the two palettes a
+  theme switch must not repaint), closed by a blank row so the band reads as an edge rather
   than an underline. `status`, `tags` and `note` share one wrapped line under
   it, broken between whole cells — a cell carries ANSI, so a cut inside one would emit
   a broken escape into a viewport that re-emits its content verbatim.
@@ -239,9 +239,16 @@ Key invariants:
   model carries the result in `m.styles`, read through `m.sty()`. No file below
   `internal/ui` carries a hex literal, and `ui.DefaultStyles()` exists only as the
   fallback for a `Model{}` literal — a renderer that reached for it directly would keep
-  painting the default palette after a theme switch. The one deliberate exception is
-  `ui.LanguageColor`: those are linguist's brand marks rather than keepkit's meanings,
-  so they live in the same package but outside `Theme` and never follow a switch.
+  painting the default palette after a theme switch. There are exactly **two**
+  deliberate exceptions, both in `internal/ui` but outside `Theme`, and they are
+  exceptions for different reasons. `ui.LanguageColor` holds linguist's brand marks
+  rather than keepkit's meanings, so keepkit has no standing to restyle them.
+  `ui.HeadingColors`/`ui.ChromaColors` (readme_palette.go) are keepkit's *own*
+  invented shades for panel `[3]`'s heading ladder and code-fence accents — a
+  contained break of "a role names a meaning, not a shade", taken because a heading
+  *level* is not a meaning `Theme` has a word for and six levels cannot be six roles.
+  Neither follows a theme switch, so `[3]`'s headings and fence accents stay put while
+  its body, links, quotes and inline code repaint.
 - **Card links are indexed, not parsed.** `buildCard()` returns the card text plus a
   `line → URL` map recorded while writing (line heights vary with wrapping), so a click
   on the title line (which carries the bare `owner/repo` beside the name, linked as the
diff --git a/CLAUDE.md b/CLAUDE.md
index e65ac82..2358eb2 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -45,7 +45,7 @@ Everything else stays here. **Never re-inline these three sections.** When a cha
 | `internal/logx` | Errors-only session logger (imports only the stdlib-only `configdir` leaf); one lazily-created plain-text file per session under `<configdir.Base>/keepkit/logs`. Package-level state (`mu`/`file`/`path`/`header`), so any package can log without threading a logger through constructors |
 | `internal/model` | Entire Bubble Tea model — all TUI state, key handling, and rendering |
 | `internal/proc` | `DetachTTY` — runs tool probe subprocesses without a controlling terminal (`Setsid` on unix, `DETACHED_PROCESS` on Windows); `KillGroup` — process-group SIGKILL (negative pid; plain `Process.Kill` on Windows) for the update streamer's timeout path |
-| `internal/ui` | `Theme` (theme.go) — the app's ten semantic color roles plus the gauge's dim track — and `Styles` (styles.go), every lipgloss style keepkit renders with, built from one theme by the single `NewStyles(Theme)`. `DefaultStyles()` is the fallback for a `Model{}` literal and nothing else. `LanguageColor` (lang.go) is the one thing here that is **not** a theme role and must not follow a theme switch: linguist's per-language brand colors, keyed case-folded, `(color, false)` for a language it does not know. Plus `PlaceOverlay` (which takes the dim style rather than reading a package var) and `StripANSI` |
+| `internal/ui` | `Theme` (theme.go) — the app's ten semantic color roles plus the gauge's dim track — and `Styles` (styles.go), every lipgloss style keepkit renders with, built from one theme by the single `NewStyles(Theme)`. `DefaultStyles()` is the fallback for a `Model{}` literal and nothing else. **Two** palettes here are **not** theme roles and must not follow a theme switch, and they are exceptions for different reasons: `LanguageColor` (lang.go) is linguist's per-language brand marks, keyed case-folded, `(color, false)` for a language it does not know — somebody else's colors, so keepkit may not restyle them; `HeadingColors`/`ChromaColors` (readme_palette.go) are keepkit-*invented* shades for panel `[3]`'s heading ladder and code-fence accents, a contained exception to "color is a role, not a shade" taken because a heading *level* is not a meaning `Theme` has a word for and six levels cannot be six meanings. The consequence is stated in all three of theme.go, readme_palette.go and `keepkitStyle`: a theme switch repaints `[3]`'s body, links, quotes and inline code and **not** H1–H5 or the fence accents. `HeadingColors` **descends** — bright H1 to dark H5 — and `TestHeadingColorsDescend` pins that direction, because reordering it is a one-line edit that breaks nothing else. Plus `PlaceOverlay` (which takes the dim style rather than reading a package var) and `StripANSI` |
 | `internal/updater` | Detect the package manager that owns an installed binary and produce an update `Plan{Manager, Argv, Display}` (brew → go → cargo → pipx → uv → pnpm → bun → npm chain; `update_cmd` override always wins; on a `LookPath` miss **or an exhausted chain**, a brew-by-name fallback before giving up — see [`docs/design/updating.md`](docs/design/updating.md)). Bottom of the import graph like `version`: no TUI knowledge, depends only on `loader` for `Tool`. Pure `detectFromPath`/`brewNamePlanAt`/`managerDirsFrom`/`pnpmShimTarget` cores + OS-facing `Detect`/`brewNamePlan`/`resolveManagerDirs`/`readPnpmShim` wrappers, plus the wrapper-less goos-parameterized `customPlan(goos, cmd)` (`update_cmd` → `sh -c`, `cmd /c` on Windows so a winget/PowerShell command needs no Git Bash) — **a deliberate duplicate of `model.shellCommand`** for `testBrewPrefix`'s reason (`updater` sits below `model` and may not import it); the cross-reference comments on both copies are the only drift guard, and both carry the same accepted caveat — Go's argv quoting is not cmd.exe-aware, so an `update_cmd` embedding double quotes can misparse under `cmd /c`. Seams: `testHomeDir`, `testBrewPrefix` (a deliberate duplicate of `version`'s — two bottom leaves that may not import each other) and `testGOOS`, which exists because **CI runs `go test` on linux only** (the Windows job cross-compiles), so an expectation derived from `runtime.GOOS` asserts nothing about the Windows branch — `TestDetectUpdateCmdOverride` drives the seam per row and is what catches `Detect` passing a literal goos, the regression this package shipped once |
 | `internal/version` | Detect installed version locally — `InstalledVersion(t) (ver string, present bool)`, the two results independent so the card can tell "installed but won't say its version" from "not installed". Sources in order: `--version`/`-V`, then `brewDirVersion` in `brew.go` (reads the version from the `Caskroom/<name>`/`Cellar/<name>` directory names — no brew subprocess — so casks with no version CLI still resolve), then `cargoListVersion`/`cargoVersionFromList` (same idea one ecosystem over: `cargo install --list` names every cargo-installed crate's version without running its binary; gated on the binary existing, and `LookPath("cargo")` short-circuits before any subprocess). A fallback hit suppresses the anomaly log; `testBrewPrefix` seam. Also: fetch latest release, repo card, changelog and README from the GitHub API with a 24h cache; semver comparison (`IsNewer`) and the card's version spelling (`DisplayVersion`); keepkit's own self-check (`selfcheck.go`: `SelfRepo`, `SelfLatest`) |
 
@@ -59,7 +59,7 @@ The `model` package is split by responsibility (one package, several files):
 | `render.go` | `View`, panel/card/status-bar/gauge/overlay renderers, scrollbar, mouse handling |
 | `readme.go` | `renderReadme` — panel `[3]`'s pipeline (sanitize → preprocess → glamour) + the single-entry `readmeRenderCache`; `testReadmeStyle` seam |
 | `readme_clean.go` | `cleanReadmeMarkdown(text, about)` — the pure README preprocessor: fenced-block/inline-span segmentation first, then the image/link/HTML/emoji/shortcode removal rules on what is left, then `rcDropTitleBlock` |
-| `readme_style.go` | `keepkitStyle(t ui.Theme, dark)` — panel `[3]`'s glamour theme, cloned from the standard config and re-accented from the theme it is handed (including a **bounded repaint of `CodeBlock.Chroma`** — a fence renders through chroma on any color terminal and through the `StyleBlock` fields only on an Ascii one, so both paths carry the plate) |
+| `readme_style.go` | `keepkitStyle(t ui.Theme, dark bool, width int)` — panel `[3]`'s glamour theme, cloned from the standard config; the **chrome** re-accented from the theme it is handed, the **typography** (H1–H5 ladder + `›` depth markers, and five code-fence tokens) from `ui.HeadingColors`/`ui.ChromaColors`. `width` is the caller's **clamped** wrap width and is spent on one thing: the full-width `HorizontalRule.Format`. Includes the **repaint of `CodeBlock.Chroma` bounded to a named seven** — a fence renders through chroma on any color terminal and through the `StyleBlock` fields only on an Ascii one, so both paths carry the plate |
 | `textutil.go` | Pure text/format helpers (`wrapText`/`wrapLine`, `stripANSI`, `colorizeHelp`, `parseHelpEntries`, `markdownToLines`/`mdInline` — the card's release-notes converter, `formatStars`, `renderLangList`/`renderLangBand`/`formatShare` — the card's language block, …) |
 | `browser.go` | `openURLCmd` + per-`GOOS` `browserCommand` |
 
@@ -112,7 +112,7 @@ The model is a three-panel layout with focus cycling via `→/←` between `focu
 - **Refresh (`r` in `focusBrief`)**: `refreshSelectedCmd(t)` force-refreshes the selected tool bypassing the 24h cache TTL — the repo pass (`refreshRemoteCmd` → `version.RefreshRepoData`) + changelog (`refreshChangelogCmd` → `version.RefreshChangelog`) + README (`refreshReadmeCmd` → `version.RefreshReadme`, preceded by a `delete(m.readmeData, name)` so a session-cached 404/rate-limit negative can recover, then a `markReadmeLoading(name)` — the deletion makes `needsReadme` true again for the whole in-flight window, so without the marker leaving and re-entering the tool would spend a second request; `refreshingFor` does *not* cover it, since `remoteMsg` clears that flag as soon as the repo pass lands, which can be well before the README does) + a local installed re-detect (`fetchInstalledCmd`). It emits the same `remoteMsg`/`changelogMsg` as the startup path, so the merge/re-render logic is reused. While the repo pass is in flight `m.refreshingFor` (the tool name) turns the card title into a status line — `refreshing <name> data <spinner>` (`bubbles/spinner`, `MiniDot`; the about is hidden) — with no status-bar takeover; the `remoteMsg` handler clears `refreshingFor` on completion, which reverts the title to name+about and halts the `spinner.TickMsg` loop. **`[r]` answers every press**: on completion the handler returns `setStatus(refreshFailedStatus(msg.err))` whenever **`msg.err != nil`** — every path that actually failed to fetch now carries a named error (see `version.pickFetchErr`), while a pass that fetched something stays silent because the repainted card *is* the answer. The predicate is deliberately **not `!msg.conclusive`**, which is a broader thing: it is also false when the version layer refused the ref outright (an unsupported or spoofed host — a bare `RepoData` with a nil `Err`, no request made), which would report a network failure that never happened, and on a partial pass that fetched a new tag and lost only the repo card, where the bar would contradict a card the user just watched update. Before that, success, a rate limit, a 401, a timeout and a dropped connection were one indistinguishable gesture: the spinner turns, the card does not change. The reason is two-tier — `ErrRateLimited` → `refresh failed: rate limited — press [a]` (the one class with an answer the user can act on), everything else → `refresh failed: network error`. There is deliberately **no token wording**: by the time a fetch fails, `doGH` has already retried a rejected token anonymously, so the refresh did not fail *because of* the token, and the gauge and `[a]` overlay report that state anyway. The write sits inside the `msg.toolName == m.refreshingFor` branch, so the background passes `Init` fires — inconclusive all the time on an offline start — never put a "refresh failed" on the bar for a gesture nobody made. `refreshingFor` doubles as the double-press guard; a tool with no `GitHub` only re-detects the installed version (`m.statusMsg = "no repo to refresh"`, no spinner). Note `case "r"` no longer branches at all: it is refresh in `focusBrief` and unbound everywhere else. Rename went global as `m` and the README source moved to `R`, so the key that once meant three things by focus now means one.
 - **Update (`enter` in `focusBrief`)** — full rationale in **[`docs/design/updating.md`](docs/design/updating.md)**. Installs a newer release from inside the TUI: `enter` is the card's primary action (in `focusTools` the same key runs the tool), requires `hasUpdate(name)`, and reports the shared `updateBusyStatus` while `updatingFor != ""` — one update at a time, no queue. The guard sequence lives in `startToolUpdate()` (**pointer receiver**, it sets a status message). Detection runs off `Update()` in `detectUpdateCmd(t, false)` because it spawns subprocesses. The invariants most often broken (the full list is in the design file): **`updater.Detect`'s chain order is load-bearing twice** — brew before go, pnpm/bun before npm (both layouts carry `node_modules` segments npm claims on sight, and the misdetection installs a duplicate the shadowed copy hides); **an empty manager root disables its own step, enforced inside `underDir`/`segmentUnder`**, never by a repeated `!= ""` guard (`filepath.Rel("", …)` makes a relative path read as living under every disabled root); all five roots come from `managerDirsFrom` and are **symlink-expanded** by the wrapper, because `Detect` compares them against an `EvalSymlinks`-resolved binary path; pnpm needs the cmd-shim's `# cmd-shim-target=` line and an over-cap file is **rejected whole**, never parsed truncated. `update_cmd` always wins; a `LookPath` miss **and** an exhausted chain both fall back to brew-by-name. `acceptsUpdateDetect(msg)` drops a stale result, and `m.updateTarget` is resolved from the *message*, not from the selection at keypress time. Streaming order is fixed by os/exec: scan the pipe to EOF → `cmd.Wait()` → final `updateLine{done:true, err, elapsed}` → `close(ch)`; a `\r` segment sets `replace`; the log caps at ~500 lines; the deadline path uses `proc.KillGroup` (negative pid); `elapsed` is stamped in `startUpdateCmd`, never in `Update()`, where `time.Now()` would make completion non-deterministic in tests. **`showsUpdateLog()` is the single predicate for who owns `[3]`**. A finished session leaves a **terminal block** under the log — `✓ finished · go · 12s` / `✕ failed · brew · 4s`, then the *verified* version once the post-update `installedMsg` lands (`⚠ fd  still v10.2.0` is what catches a manager that exited zero having done nothing), then the way out — and the frame follows it (`[3] update` → `[3] update finished` / `[3] update failed`, words rather than glyphs because `insetPanelTitle` measures runes). It is **model state, not log lines**: the buffer is wrapped at render time and would shred styling. `recordUpdateOutcome` is the single writer, shared with the self path and called on **both** results, so neither the block nor the log format can drift between them. **The phase-2 write in the `installedMsg` handler sits after that handler's cursor remap**, never before: its repaint is gated on `showsUpdateLog()` → `selectedMeta()`, and the version merge above is what re-partitions the list the index reads against, so the pre-remap order both skips the repaint for the tool that just updated and paints its log over the tool sitting at its old row. The **buffer itself renders `Dim`** (`dimUpdateLog`) so the block is the only thing on the panel carrying a verdict; the style lands after the wrap, per whole line, and strips nothing — segments are sanitized at the `updateChunkMsg` boundary.
 - **Self-update (`U`/`X`)** — full rationale in **[`docs/design/self-update.md`](docs/design/self-update.md)**. keepkit watches its own releases and installs one through the very same pipeline as `enter`. **The feature's main case is a keepkit that is not tracked**, so nothing in this path may read `meta.yaml`, the selection or a card — every guard that normally leans on `selectedMeta()` has a self counterpart that does not. The invariants most often broken (the full list is in the design file): **`selfCheckEnabled()` rejects three shapes**, not one — `""` (no `WithAppVersion`), `"dev"`, and anything `isDevVersion` sees as a working copy (a Go pseudo-version tail or any `+` build metadata), which is what keeps `go build .` from offering to `go install …@latest` over itself; **`isSelfUpdate(name)` = the name *and* that gate**, both clauses load-bearing; the `selfCheckMsg` handler writes **only from `selfNone`**, in either direction, so a late message cannot walk back a state the user acted on; `selfState` has **no "updating" member** — that is derived by `selfUpdating()`; **six sites switch on `selfState`** and each enumerates every member and ends in a `default:`, with the `selfStateCount` sentinel driving `TestSelfStateSitesAreExhaustive`; the failure branch of `updateDoneMsg` writes **no `selfState` at all** (the banner returns by itself once `updatingFor` clears, and any write there could only walk a state back); `[U]` checks `selfNone` **before** the busy guard, or a dev build answers `another update is running` for a surface documented as absent. Restart happens strictly **after `p.Run()` returns** (Bubble Tea has restored the terminal by then), and `resolveSelfPath`'s order matters: an argv0 carrying a separator wins when it exists, a bare argv0 goes through `lookPath` **first** because Linux's `/proc/self/exe` can still name the old binary after an upgrade, and `sameProgram` rejects a `PATH` hit whose base differs.
-- **Panel `[3]` modes (`helpMode`)** — full rationale in **[`docs/design/readme-pipeline.md`](docs/design/readme-pipeline.md)**. Three sources: `helpModeReadme = 2` (the **default** set in `New()`), `helpModeHelp = 0`, `helpModeMan = 1`. `helpMode` is a sticky global field, not per tool; `[R]`/`[H]`/`[M]` switch it from `focusBrief || focusHelp` through the shared **`switchHelpMode(mode)`** (sets the mode, dismisses a *completed* update log, `setHelpContent()` + `GotoTop()`, returns the fetch command for the mode's missing source). The trio is **capitals as a set** so none collides with a lowercase verb (`r` is `[2]`'s refresh, `m` the global rename). **`z` shares their gate and nothing else**: it is the fourth key that changes what `[3]` is, so it fires from the same `focusBrief || focusHelp` pair, but it changes the panel's *width* rather than its source — so it does **not** move focus (a width change is not a change of what you are reading), goes through `toggleZoom()` rather than `switchHelpMode`, and fetches nothing. See **Panel widths and the zoom toggle** below. The invariants most often broken (the full list is in the design file): **`m.helpCache` is a `map[string][2]string` indexed by `helpMode`, so mode 2 panics on every index site** — README content lives in `m.readmeData` and each index site (`rawHelpText`, `renderHelpContent`, `autoFetchCmdsForSelected`) carries a readme early-return *before* the array read; a **live** update log keeps `[3]` in every path (its branch sits ahead of both the readme branch and the `No tool selected` guard). Rendering is `cleanTerminalOutput` → **`cleanReadmeMarkdown`** (readme_clean.go) → glamour with `keepkitStyle`, and a glamour failure falls back to the **preprocessed** text, never to the raw one. In the preprocessor: **code is never rewritten** (fenced blocks segmented, inline spans NUL-masked), CRLF is normalized on entry (a `\r`-suffixed closing fence protects the rest of the file), images run before links, autolinks and bare URLs are left alone, both reference forms are gated on labels collected **document-wide after** the HTML rules, HTML tag names come from the fixed `rcHTMLNames` allowlist whose trailing `\b` is what makes the ~80-branch alternation order-independent, and **`rcLineContent` slices rather than `ReplaceAllString`** — the replace form froze the whole TUI for 8.4 s on a 512 KiB adversarial README. `keepkitStyle` **clones** the glamour globals and assigns a **fresh pointer** per override, because `styles.DefaultStyles` aliases the same structs and writing through a cloned one restyles glamour process-wide. Dark/light is resolved **once at construction** into `m.darkBG` — `glamour.WithAutoStyle()` probes the terminal with an OSC query that races Bubble Tea's input reader.
+- **Panel `[3]` modes (`helpMode`)** — full rationale in **[`docs/design/readme-pipeline.md`](docs/design/readme-pipeline.md)**. Three sources: `helpModeReadme = 2` (the **default** set in `New()`), `helpModeHelp = 0`, `helpModeMan = 1`. `helpMode` is a sticky global field, not per tool; `[R]`/`[H]`/`[M]` switch it from `focusBrief || focusHelp` through the shared **`switchHelpMode(mode)`** (sets the mode, dismisses a *completed* update log, `setHelpContent()` + `GotoTop()`, returns the fetch command for the mode's missing source). The trio is **capitals as a set** so none collides with a lowercase verb (`r` is `[2]`'s refresh, `m` the global rename). **`z` shares their gate and nothing else**: it is the fourth key that changes what `[3]` is, so it fires from the same `focusBrief || focusHelp` pair, but it changes the panel's *width* rather than its source — so it does **not** move focus (a width change is not a change of what you are reading), goes through `toggleZoom()` rather than `switchHelpMode`, and fetches nothing. See **Panel widths and the zoom toggle** below. The invariants most often broken (the full list is in the design file): **`m.helpCache` is a `map[string][2]string` indexed by `helpMode`, so mode 2 panics on every index site** — README content lives in `m.readmeData` and each index site (`rawHelpText`, `renderHelpContent`, `autoFetchCmdsForSelected`) carries a readme early-return *before* the array read; a **live** update log keeps `[3]` in every path (its branch sits ahead of both the readme branch and the `No tool selected` guard). Rendering is `cleanTerminalOutput` → **`cleanReadmeMarkdown`** (readme_clean.go) → glamour with `keepkitStyle`, and a glamour failure falls back to the **preprocessed** text, never to the raw one. In the preprocessor: **code is never rewritten** (fenced blocks segmented, inline spans NUL-masked), CRLF is normalized on entry (a `\r`-suffixed closing fence protects the rest of the file), images run before links, autolinks and bare URLs are left alone, both reference forms are gated on labels collected **document-wide after** the HTML rules, HTML tag names come from the fixed `rcHTMLNames` allowlist whose trailing `\b` is what makes the ~80-branch alternation order-independent, and **`rcLineContent` slices rather than `ReplaceAllString`** — the replace form froze the whole TUI for 8.4 s on a 512 KiB adversarial README. `keepkitStyle` **clones** the glamour globals and assigns a **fresh pointer** per override, because `styles.DefaultStyles` aliases the same structs and writing through a cloned one restyles glamour process-wide. Dark/light is resolved **once at construction** into `m.darkBG` — `glamour.WithAutoStyle()` probes the terminal with an OSC query that races Bubble Tea's input reader. In the theme itself: the heading ladder and the fence accents come from `ui.HeadingColors`/`ui.ChromaColors` and **do not follow a theme switch** (the contract change, stated in three places); **`H1.Prefix = ""`/`H2.Prefix = ""` are load-bearing assignments** — glamour's cascade overrides a child prefix only when it is non-empty, so losing them brings the stock `# `/`## ` markers back rather than falling through to `Heading`; **`H6.Bold` must be set explicitly** (the stock dark H6 is an explicit `Bold: false` that beats inheritance); in the chroma repaint **`Text.BackgroundColor` is what carries the whole plate** — chroma resolves an unset token background up to `Text`, its root, not to `Background`, so the five accents set `Color` only; and `HorizontalRule.Format` is guarded on `width > 0`, since a caller with no layout yet must get the stock rule rather than an empty string. **`chromaFormatterFor`** (readme.go) is what keeps a fence's plate the same color as the card's: glamour's default formatter is `terminal256` for *every* profile, ignoring the `WithColorProfile` beside it, which quantized `Surface` `#343945` to index 237 and put one plate on screen in two colors. Two accepted limits stay: chroma's plate covers only the highlighted **tokens** — glamour paints a code block's left indent with the *enclosing* block's style and never paints the pad out to the wrap width, so a wrapped fence line reads as a short smudge — and `TestFencePlateMatchesTheCard` allows one unit per channel, because **termenv** rounds `#343945` to `52;56;69` while chroma writes the hex verbatim. **Any override new to this file must be confirmed against glamour's renderer once before its struct test is written** — a struct assertion only proves the field changed, and `Item.Color` passes one while doing nothing.
 - **Help navigation (`j`/`k` in `focusHelp`)**: `[3]` is navigable per *entry* — a flag or subcommand line plus its indented description block. `parseHelpEntries(raw, width)` (textutil.go) detects entries heuristically on the **pre-wrap source lines** (flag start = the `helpTokenRe` flag core at the trimmed line start; subcommand start = `helpEntrySubcmdRe`, an indented non-dash word + 2+ spaces + text — the word class excludes `.` so justified man prose like `tree.  See also…` doesn't match; continuation = `continuesEntry`: any deeper-indented non-header line — including deeper lines that *begin* with a flag token (`…overridden with\n --no-ignore.`) — plus blank lines whose next non-blank line still continues, so multi-paragraph descriptions stay one entry; the entry ends at a section header or the next line at the entry's own indent or shallower) and maps the ranges to wrapped display-line indices via `wrapLine` — the same code `wrapText` uses, which is the point: `wrapText` rebuilds wrapped lines from `strings.Fields` (indentation is lost), so parsing wrapped output would break the indent heuristic, and sharing the wrap algorithm plus the single `helpWrapWidth()` (`max(helpW-1-2*panelGutter, 20)` — the viewport is a column narrower than the panel and a gutter is held at each end) keeps entry indices in lockstep with what the viewport shows. `isHelpSectionHeader` is the one definition of a header, used by both `colorizeHelp` and the parser. State is `m.helpEntries []entryRange` + `m.helpNavIdx` (−1 = off) + `m.helpBase` — the wrapped+colorized full-color content, cached because cursor moves repaint per keystroke and must not re-run the colorize regex over a whole man page (`helpContent`'s normal path serves `applySpotlight(helpBase)`, and `renderHelpContent` is the one-line wrapper that steps the result in by `panelGutter`; the base is built directly in `setHelpContent`, not via the renderer, which serves that very base back through `applySpotlight`). **`setHelpContent()` is the single recompute point** — every site where the *visible* text changes (selection via `autoFetchCmdsForSelected`, `[R]`/`[H]`/`[M]`, `helpOutputMsg` — gated on `msg.mode == m.helpMode`, a late fetch for the hidden mode must not reset the cursor, `readmeMsg` for the selected tool while in readme mode, resize — only when `helpWrapWidth()` actually changed, so a height-only resize keeps the cursor and a width change re-renders the README, update-log start) goes through it: recompute entries (empty for the update log, readme mode, `helpLoadingFor` and placeholders — `j`/`k` stay plain scroll there), reset the cursor, repaint, never scroll. Style-only repaints (per-chunk log appends, cursor moves) call `SetContent(renderHelpContent())` directly and must not reset the cursor. Interaction: **only the letter keys navigate — `↑`/`↓` keep their 3-line scroll** so prose between/after entries stays keyboard-reachable; the first `j`/`k` lands via `helpNavStart(delta)` on the first entry intersecting the window, or (none visible) the nearest entry in the movement direction; later presses step clamped without wrap; `applySpotlight` (render.go) dims every line outside the current entry (`Styles.Dim.Render(stripANSI(line))` — the `[a]` overlay's strip-then-repaint trick per whole line) while the entry keeps full `colorizeHelp` color; `scrollToNavEntry` keeps it in view with mutually exclusive branches and a `min(end-Height, start)` clamp so a taller-than-window entry pins its start to the top. `esc` is two-stage: cursor off first (scroll kept), focus walk second. `PgUp`/`PgDn`/`g`/`G`/wheel stay pure scroll and never touch the cursor. Every path that deactivates navigation (esc, any `setFocus` move) goes through `clearHelpNav()`, which pairs the reset with the repaint — clearing the index without repainting leaves stale dimming. The `focusHelp` bar shows `[j/k] navigate` alongside `[↑↓] scroll` when entries exist and prepends `[esc] exit nav` while the cursor is on.
 - **Tracking verbs are global**: `t` track (add by GitHub URL or plain name → `modeTrack`), `u` untrack (with confirmation → `modeConfirmUntrack`), `m` rename (fix the binary name when the repo name differs → `modeRename`). All three fire in **every focus** and are three of the six keys `globalHints` puts on the status bar. They used to be `[1]`-only because each collided with a `[2]` action (`t` tags, `u` update, `r` refresh); the redesign moved those onto keys of their own (`#` tags, `enter` update) and freed all three to mean one thing everywhere, which is what lets the bar carry a single focus-independent list instead of three per-focus ones. Rename is **`m`, not `R`**: `R` is panel `[3]`'s readme source now, and the tracker's verbs are the lowercase set. That leaves lowercase `r` meaning **refresh in `[2]` and nothing else** — it used to double as `[3]`'s readme switch, so one key meant "spend three requests" or "swap the panel's source" depending on a focus the `[3]` title did not mention. Each mode has a handler in `mode.go` and a matching branch in `renderStatusBar()`, mirroring the `modeEditNote`/`modeEditTags` input pattern. Mutations go through `loader.UpsertMeta`/`RemoveMeta`, persist via `loader.SaveMeta`, then rebuild `m.tools = loader.ToolsFromMeta(m.meta)` and refresh the viewport.
 - **Run (`enter` in `focusTools`)**: launches the selected tool without leaving keepkit. `enter` fires only in `modeNormal`+`focusTools` (empty list → no-op; in `modeSearch` enter stays the commit key) and opens `modeRunInput` — a one-line prompt (`m.runInput`, its own textinput like `m.search`, not shared with note/tags) prefilled with `m.lastRun[name]` else the tool name, cursor at end; the status bar echoes `run <name>: <input>  [enter] run  [esc] cancel`. `m.lastRun map[string]string` is session-only per-tool memory of the last dispatched command — rename's stale-state cleanup deletes the old-name entry alongside `helpCache` et al.; untrack deliberately leaves it (harmless, session-scoped). Enter with empty/whitespace input cancels like `esc`. On dispatch `launcher.Detect(command, name)` picks the path — env-only, so unlike every probe it is safe inside `Update()`: a tab plan runs its `Argv` via `startLaunchCmd` (`exec.Command` + `proc.DetachTTY`, `launchTimeout` — a 10s **var**, shrunk by the timeout/KillGroup test — with `proc.KillGroup` on expiry, `safeCmd`-wrapped) → `launchDoneMsg{toolName, command, err}`, with `m.launchingFor` (the launch twin of `updatingFor`) as the one-adapter-launch-at-a-time guard and a `launching <name> in <terminal>…` statusMsg as in-flight feedback (this is also `Plan.Terminal`'s consumer); a `Fallback` plan runs `execToolCmd` → `tea.ExecProcess` over `shellCommand(runtime.GOOS, cmd)` (`sh -c` / `cmd /c`; goos-parameterized and spawn-free like `browserCommand`, so both branches are table-testable) — keepkit suspends, Bubble Tea restores the terminal when the tool exits → `execDoneMsg{toolName, err}`. **Auto-fallback**: an adapter failure (kitty remote control off, Automation permission denied) must not strand the launch — the `launchDoneMsg` error handler sets `statusMsg` (`tab open failed — running <name> here`) and returns `execToolCmd(msg.toolName, msg.command)`; `command` rides the msg so the handler never re-reads input state. The auto-fallback is **gated on `modeNormal`**: the result can arrive up to `launchTimeout` after enter (osascript blocked on the macOS Automation dialog), and `tea.ExecProcess` seizing the terminal under an open editor/overlay would route keystrokes to the spawned shell — under any other mode the fallback is **deferred**, not dropped: the gate stores `m.pendingLaunchName`/`Command` and `flushPendingLaunch` (mode.go) dispatches `execToolCmd` with the same statusMsg (single definition: `launchFallbackStatus`, shared with the ungated auto-fallback) on the keystroke that returns the mode to `modeNormal` (every modal return in `Update` funnels through it — the mode-dispatch switch plus the inline `modeSearch` exit; `modeTokenInput`'s esc lands on `modeAPIStatus`, so the flush waits for the overlay to actually close). A statusMsg set at gate time would be dead UI — every open mode's `renderStatusBar` branch outranks the statusMsg branch, and the blanket `statusMsg = ""` reset on `tea.KeyMsg` fires on the very keystroke that closes the mode; setting it in the flush (after both) is what makes the failure visible. The flush goes straight to `execToolCmd` — never back through `launcher.Detect` — so a known-failing adapter plan is never re-run; a new dispatch from `modeRunInput`'s enter drops a pending fallback first (flushing both on one keystroke would run two commands), and confirming untrack of the pending tool itself drops it too — the dialog-closing enter must not exec the now-untracked tool's command (a pending fallback for a *different* tool deliberately survives the untrack and flushes on that keystroke). The handler clears `launchingFor` first in all outcomes. Working directory differs by path: a tab opens in the new shell's default cwd, the ExecProcess fallback inherits keepkit's. The timeout carries one accepted race: an adapter killed after its tab command already executed (osascript stuck post-`write text`) still triggers the fallback, so the command can run twice — narrow, undetectable, and better than stranding genuine failures. This path also serves native Windows: `planFor` is env-only, so WezTerm there yields a doomed `sh -c` plan whose failure lands in the fallback (one noisy attempt accepted; a `GOOS` guard in `planFor` is deliberate YAGNI). Success wording is mode-neutral — `launched <name>` — because Terminal.app and tmux open a *window*, not a tab. **No `logx` anywhere in the flow**: a non-zero tool exit (`statusMsg "<name> exited: <err>"`) is the tool's business, not a keepkit anomaly, and an adapter error is a degraded path, not a malfunction (the auto-fallback still launches the tool). Launch during a running update is deliberately not blocked — independent concerns; ExecProcess pauses rendering of the live update log and the buffer catches up on resume. A not-installed tool launches anyway (no PATH pre-check): in a tab `sh` reports `command not found` inside that tab, while on the ExecProcess path the shell's not-found exit (`notFoundExit`: 127 sh / 9009 cmd.exe) maps to `statusMsg "<name> not found — is it installed?"` instead of the cryptic raw exit status. The `[?]` overlay's tools group carries `enter — run in tab` (desc kept short — the overlay sits at the 76-col edge of its budget).
diff --git a/docs/design/readme-pipeline.md b/docs/design/readme-pipeline.md
index 946efd5..b6241db 100644
--- a/docs/design/readme-pipeline.md
+++ b/docs/design/readme-pipeline.md
@@ -11,4 +11,26 @@ is described in [`updating.md`](updating.md).
   - **Removal rules**, all package-level regexes (the `helpTokenRe` idiom — this runs synchronously inside `Update()` on up to 512 KiB). *Images* go whole in every form (`![alt](url)`, reference `![alt][ref]`/`![alt][]`, and the shortcut `![alt]`), which needs no badge-vs-logo heuristic for the simple reason that **no image can ever render in a TTY**. A *linked* badge collapses for free: image removal turns `[![alt](img)](target)` into `[](target)` and the link unwrap then empties it, which is why images run first. *Links* are unwrapped to their text — panel `[3]` links are not clickable, so the href half is pure noise — and **autolinks and bare URLs are left alone**, since there the URL *is* the content (this is also why the style-level route was rejected: glamour renders both through the same `Link` primitive, so blanking it deletes them). The inline destination pattern is shared with the card's converter as **`mdDest`**, which allows **one level of nested parentheses**: a flat `[^)]*` stopped at the inner `)` of a shields.io badge (`…/badge/a-(b)-blue.svg`) or a Wikipedia link (`…/wiki/Foo_(bar)`) and left the rest of the URL on screen as text — exactly the noise the pass exists to remove. Deeper nesting needs recursion, which RE2 does not have. **Both reference forms are gated on a declared label** — `[text][ref]` and the shortcut `[label]` alike, collected **document-wide** because definitions collect at the bottom of a README while their uses sit at the top and a fence between them puts the two in different segments. Ungated, the rule ate a task list's `[x]`, a prose `[experimental]`, and — the reference form's own case — `arr[i][j]` in prose, which came out as `arri`. The label set is built **after** the HTML rules run, or a definition commented out with `<!-- -->` would gate the unwrapping and eat the very brackets the gate protects. Standalone `[label]: url` definition lines are dropped as the pure metadata they now are, under **two** guards, because deleting a line of someone's README is the most destructive thing this pass does: the destination must be a single token (or `<angled>`) with at most a quoted title, and the line **may not interrupt a paragraph** (CommonMark forbids that anyway) — without them `[1]: first item explained` and a `[note]: this matters` sitting mid-paragraph both silently vanished. *HTML*: comments whole; `<picture>`/`<video>`/`<audio>`/`<svg>`/`<script>`/`<style>` whole **including bodies** (one regex per name — RE2 has no backreference); every other tag stripped keeping its inner text (`<kbd>Ctrl</kbd>` → `Ctrl`, a `<details>`/`<summary>` block keeps its content). The tag name is matched against a **fixed allowlist** (`rcHTMLNames`), not a generic identifier shape — a shape-based pattern cannot tell `<kbd>` from `Vec<String>`, and it is the allowlist that lets `<https://…>`, `<user@host>`, `Vec<String>` and `a < b` through; an unknown name is left as written, the honest degradation, and no general sanitizer (bluemonday) is pulled in. Two details there are load-bearing: the trailing **`\b`** after the name is what makes the ~80-branch alternation order-independent (Go's regexp is leftmost-*first*, so without it `a` would claim `<abbr>` and leave `br>` behind), and the attribute part (**`rcTagAttrs`**) matches quoted values whole, since a flat `[^<>]*` ends the tag at the first `>` — including one inside a value, which left `<img alt="a > b" src="x.png">` rendering as ` b" src="x.png">`. *Emoji*: the pictographic SMP blocks U+1F000–U+1FAFF plus the joiners that would be stranded without them (VS16 U+FE0F, ZWJ U+200D, the combining enclosing keycap U+20E3, which is what makes `1️⃣` leave a bare `1`); BMP symbols a terminal font does carry (`✓ ★ →`, and `✨`, `⭐`, `❗`) are kept, and `✅→✓` / `❌→✗` / `☑→✓` are translated rather than dropped, because a feature table's meaning lives in that column. *Shortcodes* (`:name:`) go only when `name` is in **`definition.Github()`** — goldmark-emoji's dictionary, the same one glamour gets, promoted to a direct dependency for this and adding nothing to `go.sum` — so `:30:` inside `12:30:45` and an unknown `:foo:` survive.
   - **Post-removal tidy-up** is per line and **gated on the line having actually changed**: interior double spaces collapse, the tail is trimmed, and a line whose content removal emptied is dropped (`rcLineContent` strips leading block markers first, so `## 🚀` — which cleans to `##`, a heading with no content glamour would paint as a styled blank row — is recognized as empty). The gate is what keeps an untouched `- - -` thematic break from being mistaken for an emptied bullet. A **hard line break survives explicitly**, not by the gate: `rcTidyLine` carries two trailing spaces over when the original had them, because that is markup and a removal inside the line has no business retiring it. The **indent comes from the original line**, or a leading `🚀 ` would leave an indent the author never wrote — four of them and markdown reads the line as an indented code block. A dropped line takes an **orphaned setext underline** with it (the `=` form only; a `-` run is equally a thematic break and renders as a rule either way), or removal of the title left a visible row of equals signs behind. Runs of blank lines then fold to one (in markdown one break and five are the same break), which is what makes a ten-badge header vanish instead of leaving ten empty rows.
   - **`rcLineContent`'s loop slices, it does not `ReplaceAllString`** — and that is a correctness fix, not a micro-optimization. The pattern is `^`-anchored, so a replace could only ever rewrite the head, yet it copied the whole remaining line every pass: one line of `🚀 ` followed by 262144 `- ` markers (a 512 KiB README, exactly `readmeMaxBytes`) took **8.4 seconds** inside a synchronous `Update()`, i.e. the entire TUI — render loop and keyboard — frozen on untrusted remote input. `TestCleanReadmeMarkdownPathologicalInputIsFast` is the guard; the same input now finishes in single-digit milliseconds. Nothing else in the pass is superlinear: `rcSpanEnd`'s failing forward scan can happen at most once per *distinct* backtick-run length (any later run of the same length pairs with it and consumes the interval), which bounds the total at ~106 ms on a purpose-built worst case, and the regex passes measure 13–51 ms on 512 KiB. A realistic 512 KiB README preprocesses in ~30 ms against glamour's own ~1.2 s, and the whole result is memoized by `readmeRenderCache`.
-  - **The theme (`keepkitStyle(t ui.Theme, dark)`)** **clones** `styles.DarkStyleConfig`/`LightStyleConfig` and overrides accents rather than building from scratch: `StyleConfig` has dozens of fields (chroma tokens, table separators, list indents) and inheriting them means a glamour upgrade that adds one cannot leave the panel with a hole in it. It takes the `Theme` rather than reading colors from a package, which is what puts the readme panel under the same one-value theme switch as everything else (the panel re-renders on the existing `switchHelpMode` path, and the theme is part of `readmeRenderCache`'s key). **The globals hold pointers and `styles.DefaultStyles` aliases the same structs**, so every override assigns a **fresh pointer** (`ptrTo`) — writing through a cloned one would restyle glamour for the whole process, which `TestKeepkitStyleLeavesGlobalsUntouched` guards with a JSON snapshot (a plain struct copy would alias the very pointers the bug corrupts and pass on it). Overrides: **H1** `Accent` bold with **no background plate** (`BackgroundColor = nil`) — the standard style's bright plate was the loudest thing on the screen and the main reason a rendered README read as pasted in from another app; its padding spaces go with it. **H2** `Emphasis` bold, the panel's section heading, matching the card's own. **Every heading loses its reprinted `## ` prefix**: that is source, not text, and weight already says the line is a heading. **Document margin 0** (a fresh `*uint`): glamour's own margin eats 2–4 columns of an already narrow panel, and the panel frame is the breathing room. The rest is **dark-only** — `Heading` (the base every `Hn` cascades onto, so it is the H3–H5 rule) and `H6` in `Text` bold, `Strong` in `Emphasis` (the bold lead of a feature line is the readme's own emphasis peak), **`Document`** — the base every block cascades onto, so it is the panel's body-text rule — in **`Text`**, the very role the card's changelog notes render in: the two sitting side by side at slightly different grays was the last thing that read as "this panel came from another app". **Inline `Code` in `Text` on the `Surface` plate**, exactly like a code span in that changelog: it was `Danger` with no plate, and that was wrong twice — red is the card's one alarm color and a README spends it a dozen times a screen, and the dark red was the *least* legible thing in the panel rather than the most. It then spent a while in `Emphasis`, and that overshot the other way: a README spends dozens of spans per screen while `Emphasis` is meant to peak a few times per frame, so every code span was the loudest thing in the panel. The plate alone does the raising — the text stays at body brightness — and the prefix/suffix spaces the standard style already puts around inline code become the plate's padding for free. **`CodeBlock` on the same `Surface` background** (an install command the user is about to run) — and that one has **two live render paths**, which is what the override missed at first: glamour sends a fence through `rules.Chroma` whenever `ColorProfile != termenv.Ascii`, i.e. in every real session, and only falls back to the `StyleBlock` fields for `NO_COLOR`/dumb terminals — which is also what this package's TTY-less tests exercise. So the `StyleBlock` override stays *and* `CodeBlock.Chroma` is repainted, **bounded to two entries**: `Background` carries the plate and `Text` gets the same background because chroma's formatter emits one per token (without it the plate is punched through wherever a token falls back to `Text`); every other token entry is inherited unchanged, so the syntax accents stay the standard config's and no per-token judgement call is made. The clone is a fresh pointer for `ptrTo`'s reason. One caveat: glamour registers the built chroma style under the **process-global, one-shot name `"charm"`** and skips the registration when the name is taken, so the first render in a process wins the slot — which is why the assertion is struct-level (`TestKeepkitStyleRepaintsChroma`) and why a mid-session theme switch could not repaint a fence anyway, consistent with `m.darkBG` being resolved once at construction. The repaint is **dark-only**, like `LinkText` in `Link`, `HorizontalRule` in `Border` and `BlockQuote` in `Dim` — those tints are chosen against a dark panel and are unreadable on white, where the standard light colors stay (and where `CodeBlock.Chroma` therefore still aliases the global). **One part of the redesign is deliberately missing**: a section heading is meant to carry a border-colored rule out to the panel edge, and `StyleConfig` cannot express that — `Prefix`/`Suffix` are inline and `HorizontalRule` is a fixed string, so the only way to fake it is to inject a `---` the author never wrote into their README. Weight and `Emphasis` carry the heading on their own instead. The theme is covered at the **struct level**, not on rendered output: tests have no TTY, so `lipgloss.ColorProfile()` is Ascii and glamour strips every color it would emit.
+  - **The theme (`keepkitStyle(t ui.Theme, dark bool, width int)`)** **clones** `styles.DarkStyleConfig`/`LightStyleConfig` and overrides rather than building from scratch: `StyleConfig` has dozens of fields (chroma tokens, table separators, list indents) and inheriting them means a glamour upgrade that adds one cannot leave the panel with a hole in it. **The globals hold pointers and `styles.DefaultStyles` aliases the same structs**, so every override assigns a **fresh pointer** (`ptrTo`) — writing through a cloned one would restyle glamour for the whole process, which `TestKeepkitStyleLeavesGlobalsUntouched` guards with a JSON snapshot (a plain struct copy would alias the very pointers the bug corrupts and pass on it). **Two palettes meet here and the split is deliberate.** The panel's *chrome* — body text, links, quotes, inline code, the rules — comes from the `Theme` it is handed, which is what keeps it under the same one-value theme switch as the rest of the app (the panel re-renders on the existing `switchHelpMode` path, and the theme is part of `readmeRenderCache`'s key). The panel's *typography* — the H1–H5 heading ladder and the code-fence syntax accents — comes from **`ui.HeadingColors`/`ui.ChromaColors`** (`internal/ui/readme_palette.go`), which are fixed shades and **do not follow a theme change**: that is the contract change this feature made, and it is stated in three places (`ui/theme.go`'s "switching every color is switching one Theme value" now holds for the chrome, the palette file carries the whole argument, and `keepkitStyle`'s own doc comment names the split). The reason is that a heading *level* is not a meaning `Theme` has a word for — six levels cannot be six meanings — and `Theme` growing five roles that mean "one step further down a ladder" would destroy the vocabulary rule to serve one panel.
+
+    **The heading ladder.** One color per level, H1–H5, plus `Bold` at every level; H6 takes the `Theme.Dim` role, dark-only. It exists because the stock config renders **H3 through H6 identically**, so a README's own structure was invisible below the second level. `Bold` is set per level rather than left to the `Heading` base, because the stock H6 carries an explicit `Bold: false` that beats inheritance — a rule that holds for five of six levels is not a rule. **The ladder descends: bright at H1, dark at H5.** That direction is the decision, not the palette. Measured against a typical dark background the five run 7.2 : 5.4 : 4.1 : 3.6 : 2.4 in contrast, so the dark-to-bright reading (which is what the plan originally specified) put the *least* contrast on H1 — below the 3:1 floor for bold text and below the `Dim` role a caption uses. A document's top heading being the hardest line on the page to read is an inverted ladder rather than a ladder. Two consequences are accepted in exchange: on a white terminal the ends swap (H1 measures ~2.4 there), and on dark H5 (2.4) sits *below* H6's `Dim` (4.2), so the ladder's last two steps read as one. `TestHeadingColorsDescend` pins the direction, because reordering the values is a one-line edit that breaks nothing else.
+
+    **Depth markers.** H3–H6 carry `› `/`›› `/`››› `/`›››› ` prefixes: below H2 the ladder's steps sit close together by construction, so depth is also spelled. They are **not** dim — `Prefix` renders with the heading's own style and glamour gives no way around that, so each marker carries its level's color and states the depth twice; accepted. `›` (U+203A) is East-Asian **Ambiguous**, the accepted class (`⏺`/`↑`/`•`/`─`), and it travels through glamour's own wrap rather than `wrapText`, where an over-wide measurement can only wrap a heading early. **H1 and H2 get `Prefix = ""` explicitly, and that assignment is load-bearing**: glamour's cascade overrides a child's `Prefix` only when the child's is **non-empty**, so losing those two lines does not fall through to the `Heading` base — it brings the stock `"# "`/`"## "` markdown markers back, which are source rather than text. H1 also loses its **background plate** (`BackgroundColor = nil`) and its padding spaces: the standard style's bright plate was the loudest thing on the screen and the main reason a rendered README read as pasted in from another app.
+
+    **Document margin 0** (a fresh `*uint`): glamour's own margin eats 2–4 columns of an already narrow panel, and the panel frame is the breathing room.
+
+    **Dark-only chrome.** `Strong` in `Emphasis` (the bold lead of a feature line is the readme's own emphasis peak); **`Document`** — the base every block cascades onto, so it is the panel's body-text rule — in **`Text`**, the very role the card's changelog notes render in: the two sitting side by side at slightly different grays was the last thing that read as "this panel came from another app". **Inline `Code` in `Text` on the `Surface` plate**, exactly like a code span in that changelog: it was `Danger` with no plate, and that was wrong twice — red is the card's one alarm color and a README spends it a dozen times a screen, and the dark red was the *least* legible thing in the panel rather than the most. It then spent a while in `Emphasis`, and that overshot the other way: a README spends dozens of spans per screen while `Emphasis` is meant to peak a few times per frame. The plate alone does the raising — the text stays at body brightness — and the prefix/suffix spaces the standard style already puts around inline code become the plate's padding for free. `LinkText` in `Link`, `HorizontalRule` in `Border`, `BlockQuote` in `Dim` **plus `Italic`** — `Dim` says "less important", italic is what says "somebody else's voice", and italic was the one emphasis axis the panel had left unspent. All of these tints are chosen against a dark panel and are unreadable on white, where the standard light colors stay.
+
+    **Code fences have two live render paths**, which is what the override missed at first: glamour sends a fence through `rules.Chroma` whenever `ColorProfile != termenv.Ascii`, i.e. in every real session, and only falls back to the `StyleBlock` fields for `NO_COLOR`/dumb terminals — which is also what this package's TTY-less tests exercise. So `CodeBlock`'s `StyleBlock` override stays *and* `CodeBlock.Chroma` is repainted, **bounded to a named seven**: `Background` and `Text` carry the plate, and `Keyword`/`LiteralString`/`Comment`/`LiteralNumber`/`NameFunction` carry the syntax accents keepkit owns (the tokens a README's fences actually spend — a shell block is mostly keyword and string, a Go block adds function and comment). Everything else is inherited, so a glamour upgrade that retunes the rest arrives for free, and `TestKeepkitStyleRepaintsChroma`'s `reflect.DeepEqual` over the zeroed-out seven is the guard against the repaint growing one token at a time. **`Text` is the load-bearing plate entry, verified by render rather than by reading the struct**: chroma's formatter emits a background per token and resolves an unset one up the token hierarchy to `Text` (its root), **not** to `Background` — with `Background` set and `Text`'s background unset, the fence comes out with **no plate at all**. The converse is why the five accents set `Color` only: their background is inherited from `Text`, and repeating it would be five more places for the plate to drift. **The formatter follows the profile** (`chromaFormatterFor`, readme.go — a pure goos-style core with `lipgloss.ColorProfile()` as its thin wrapper, handed to glamour as `WithChromaFormatter`). glamour's own default is `"terminal256"` for *every* profile, ignoring the `WithColorProfile` answer sitting next to it, and that quantized the fence's plate into the 256-color cube: `Theme.Surface` `#343945` landed on index 237 (`#3a3a3a`), a flat gray with the blue cast gone. So the **one** plate reached the screen in two colors — the card's changelog code line and panel `[3]`'s own **inline** code both emit the exact value through lipgloss/termenv, and only the fence between them was off. The mapping is TrueColor → `terminal16m`, ANSI256 → `terminal256`, ANSI → `terminal16`, Ascii → the stock (that arm never runs; glamour gates the whole chroma path on `ColorProfile != Ascii`). It is a mapping and not a constant `terminal16m` because forcing 24-bit sequences onto an ANSI-only terminal is the same bug one layer down. `TestFencePlateMatchesTheCard` asserts this on **rendered output** against `ui.Styles.Surface` — passing the option proves nothing about what chroma then emits, and the whole defect was a value that survived every struct-level check — with a one-unit-per-channel tolerance that is **termenv's**: `TrueColor.Color("#343945")` emits `52;56;69` where the hex says `52;57;69`, so the card is the side that rounds, and has for every `Surface` plate since the role existed. One unit out of 255 is not a disagreement; a jump to a palette index is, which is exactly what the test's 24-bit check catches. The clone is a fresh pointer for `ptrTo`'s reason. One more caveat: glamour registers the built chroma style under the **process-global, one-shot name `"charm"`** and skips the registration when the name is taken, so the first render in a process wins the slot — which is why the assertion is struct-level and why a mid-session theme switch could not repaint a fence anyway, consistent with `m.darkBG` being resolved once at construction. The repaint is **dark-only**; on white `CodeBlock.Chroma` still aliases the global.
+
+    **Task lists** get `Ticked = "✓ "` / `Unticked = "☐ "`, shared by both variants: the stock markers reprint the source's `[ ]`/`[x]` brackets, the same "source, not text" problem the heading prefixes had, and one glyph says each state. `☐` is U+2610, the accepted Ambiguous class again.
+
+    **The divider is the panel's one full-width rule.** `HorizontalRule.Format` becomes `"\n" + strings.Repeat("─", width) + "\n"`, which is what the `width` parameter exists for and its only use — the same `─` the frame is drawn with, so a divider and a border are visibly the same kind of thing. The stock format is a short dash run floating mid-panel, which reads as a typo rather than as the author dividing their document. `renderReadme` passes its **clamped** width local (after the `readmeMinWrap` floor), the same number `WithWordWrap` gets, so a narrow panel cannot be handed a rule wider than itself; `readmeRenderCache` is already keyed by width, so a resize re-renders for free. `width <= 0` keeps the stock format — a caller with no layout yet (a hand-built model, a test) must get something rather than an empty string, which would be a divider the author wrote and the panel silently dropped. Accepted caveat: a `---` nested under a blockquote or a list item is indented by the enclosing block, so the run is then `width − indent` cells wide and, having no breakpoints, **overflows rather than wraps**. New failure mode, rare enough to accept — the stock short run could never hit it.
+
+    **The fence's plate is ragged, and that is glamour's, not a config choice.** Only the highlighted tokens carry a background: the block's left indent is painted by `indent.NewWriterPipe` with the **enclosing block's** `StylePrimitive` (`bs.Current()`, i.e. `Document`), and the padding out to the wrap width is not painted at all. A fence line that fills the width therefore reads as a solid plate while a **wrapped continuation** reads as a short smudge sitting on the page background, flush left and unindented — which is what a long `treemd github:rust-lang/rust  # Read a GitHub repo's README` looks like at a 46-cell panel. The only `StyleConfig` lever is the enclosing block's background, i.e. `Document`, which would flood the entire document with the plate. Recorded as a third deliberate absence rather than worked around.
+
+    **Two more things are deliberately not styled, and both are recorded as code comments so the next reader does not rediscover them.** *List markers*: `Item.Color` and `Enumeration.Color` exist and are **no-ops** — `ansi.BaseElement.doRender` paints the `• ` BlockPrefix and the enumerator with the *enclosing block's* style, so a red `Item.Color` still produces document-gray bullets (confirmed by render). *Tables*: the separators are drawn by lipgloss/table from glyph strings with **no color call at all**, and the `Table` `StylePrimitive` styles **cell content** — header and body alike — so neither a border tint nor a header-only weight is expressible. Both would need a glamour change, not a config one.
+
+    **One part of the redesign is still missing**: a section heading is meant to carry a border-colored rule out to the panel edge. `HorizontalRule` now *is* a full-width rule, but it is the wrong one — it fires on a `---` the author wrote, and the only way to put one under a heading is to inject a `---` they never wrote. Editing somebody's document to decorate it is where this stops; weight and the ladder carry the heading on their own.
+
+    **The theme is covered at the struct level**, not on rendered output: tests have no TTY, so `lipgloss.ColorProfile()` is Ascii and glamour strips every color it would emit. A struct assertion only proves the field changed, never that glamour *reads* it — `Item.Color` passes such a test and does nothing — so every override here was additionally **confirmed against the renderer once** (a `forceColorProfile` render in a throwaway file, each chroma variant in its own process because of the one-shot `"charm"` registration) before its struct test was written.
diff --git a/docs/plans/completed/20260808-readme-typography.md b/docs/plans/completed/20260808-readme-typography.md
index 4438bd9..6f13496 100644
--- a/docs/plans/completed/20260808-readme-typography.md
+++ b/docs/plans/completed/20260808-readme-typography.md
@@ -122,7 +122,7 @@ Design decisions (brainstorm + review revisions, all user-approved):
 | H4 | `#8e936d`, bold, prefix `›› ` — shared |
 | H5 | `#a2ad59`, bold, prefix `››› ` — shared |
 | H6 | `Theme.Dim`, bold (explicit — stock `Bold:false` trap), prefix `›››› ` — **dark-only** (the file's rule: Theme tints beyond heading accents are dark-only; light keeps its stock H6, prefix still applied shared) |
-| Chroma tokens | Keyword / LiteralString / Comment / LiteralNumber / NameFunction from an own teal/olive var block; all other tokens inherited — dark-only like the existing repaint |
+| Chroma tokens | Keyword / LiteralString / Comment / LiteralNumber / NameFunction from an own teal/olive var block; all other tokens inherited — dark-only like the existing repaint. **Verified at Task 3: `Color` only — chroma resolves an unset token background up to the `Text` entry (its root), NOT to `Background`, so no per-token `BackgroundColor` is written. `Text.BackgroundColor` turns out to be what carries the whole plate.** |
 | Inline code | unchanged (`Text` on `Surface`, shared rule with the card changelog) |
 | List markers | **deliberate absence** — `Item.Color`/`Enumeration.Color` are no-ops in glamour v1.0.0; recorded as a code comment, no override shipped |
 | Task lists | `Ticked: "✓ "`, `Unticked: "☐ "` — shared |
@@ -131,9 +131,14 @@ Design decisions (brainstorm + review revisions, all user-approved):
 | Tables | **deliberate absence** — separators are lipgloss-drawn and uncolorable; `Table`'s style colors cell text; no header-only style exists; recorded as a code comment |
 | LinkText / Strong | unchanged (`Link` / `Emphasis`) |
 
-Known risk, accepted: `#08605f` is dark against the dark panel — the ladder reads
-"inverted" (H1 quietest). Judged at the vis step in **both variants**; reversing the
-ladder is a 5-line var edit and the user decides then.
+**Resolved at Task 6 (user decision): the ladder is REVERSED from the table above.**
+Measured on a dark background the five run 7.2 : 5.4 : 4.1 : 3.6 : 2.4, so the
+planned dark-to-bright order put H1 below the 3:1 bold-text floor and below the
+Dim role a caption uses. `ui.HeadingColors` now descends — H1 `#a2ad59`, H2
+`#8e936d`, H3 `#598381`, H4 `#177e89`, H5 `#08605f` — loud at the top. Accepted
+in exchange: on white the ends swap (H1 ~2.4), and on dark H5 (2.4) sits below
+H6's Dim (4.2), so the last two steps read as one. `TestHeadingColorsDescend`
+pins the direction, since reordering breaks no other test.
 
 ## Technical Details
 
@@ -172,15 +177,15 @@ ladder is a 5-line var edit and the user decides then.
 - Create: `internal/ui/readme_palette.go`
 - Create: `internal/ui/readme_palette_test.go`
 
-- [ ] create `readme_palette.go` with `HeadingColors [5]lipgloss.Color`
+- [x] create `readme_palette.go` with `HeadingColors [5]lipgloss.Color`
       (`#08605f #177e89 #598381 #8e936d #a2ad59`) and `ChromaColors` (five teal/olive
       token colors picked to sit against `Surface`)
-- [ ] doc comment per Technical Details: non-role palette, the *difference* from
+- [x] doc comment per Technical Details: non-role palette, the *difference* from
       `LanguageColor`, theme-switch consequence, edit contract
-- [ ] write tests: every entry parses as `#RRGGBB` (guards a typo'd hex lipgloss would
+- [x] write tests: every entry parses as `#RRGGBB` (guards a typo'd hex lipgloss would
       swallow), array length pinned at 5 — note: only the length pin is
       mutation-checkable; the hex-shape assertion is a smoke guard, not a mutant killer
-- [ ] run tests — must pass before task 2
+- [x] run tests — must pass before task 2
 
 ### Task 2: Per-level heading colors, depth markers, width parameter
 
@@ -189,31 +194,31 @@ ladder is a 5-line var edit and the user decides then.
 - Modify: `internal/model/readme.go`
 - Modify: `internal/model/readme_style_test.go`
 
-- [ ] add `width int` to `keepkitStyle`; thread through `renderReadme` (pass the
+- [x] add `width int` to `keepkitStyle`; thread through `renderReadme` (pass the
       **clamped** width local) and every existing call site in tests; no Format use yet
-- [ ] renderer-confirmation: re-verify per-level heading color + prefix rendering once
+- [x] renderer-confirmation: re-verify per-level heading color + prefix rendering once
       via a `forceColorProfile` render (review already confirmed child-wins cascade and
       prefix styling; this is the rule being followed, cheap here)
-- [ ] shared section: H1–H5 colors from `ui.HeadingColors` + `Bold` via `ptrTo`;
+- [x] shared section: H1–H5 colors from `ui.HeadingColors` + `Bold` via `ptrTo`;
       **keep the explicit `H1.Prefix = ""` and `H2.Prefix = ""`** (cascade only
       overrides a non-empty child prefix — losing these silently brings `# `/`## ` back);
       H3–H5 prefixes `"› "`/`"›› "`/`"››› "`; H6 prefix `"›››› "` shared
-- [ ] dark branch: `H6.Color = Theme.Dim` **and `H6.Bold = ptrTo(true)`** (stock dark H6
+- [x] dark branch: `H6.Color = Theme.Dim` **and `H6.Bold = ptrTo(true)`** (stock dark H6
       carries an explicit `Bold: false` that beats inheritance); drop the now-redundant
       dark-branch `Heading`/`H6` *color* overrides only where the per-level colors
       replace them
-- [ ] update the named breaking tests rather than deleting them:
+- [x] update the named breaking tests rather than deleting them:
       `TestKeepkitStyleOverrides` (pins H1 Accent / H2 Emphasis → now palette),
       `TestKeepkitStyleDarkOnlyOverrides` (pins dark Heading/H6 Text → new shape)
-- [ ] write struct tests: each level's Color/Bold/Prefix pinned, **including
+- [x] write struct tests: each level's Color/Bold/Prefix pinned, **including
       `H1.Prefix == ""` / `H2.Prefix == ""` and `H6.Bold == true`**; H6 color dark-only
-- [ ] rewrite `keepkitStyle`'s doc comment: the theme-switch claim ("same one-value
+- [x] rewrite `keepkitStyle`'s doc comment: the theme-switch claim ("same one-value
       theme switch") now holds for body/links/quotes/inline code only — say so here, in
       the task that makes it true
-- [ ] add `›` to the glyph-width test (both runewidth conditions, Ambiguous accepted)
-- [ ] mutation-check each assertion (delete one level's override → red);
+- [x] add `›` to the glyph-width test (both runewidth conditions, Ambiguous accepted)
+- [x] mutation-check each assertion (delete one level's override → red);
       `TestKeepkitStyleLeavesGlobalsUntouched` stays green
-- [ ] run tests — must pass before task 3
+- [x] run tests — must pass before task 3
 
 ### Task 3: Own chroma token palette for code blocks
 
@@ -221,22 +226,22 @@ ladder is a 5-line var edit and the user decides then.
 - Modify: `internal/model/readme_style.go`
 - Modify: `internal/model/readme_style_test.go`
 
-- [ ] renderer-confirmation: verify chroma token entries are read for a Go + shell fence
+- [x] renderer-confirmation: verify chroma token entries are read for a Go + shell fence
       (one-off render), and whether the explicit per-token `BackgroundColor` is
       load-bearing or inherited from the `Background` entry — write the comment from
       what is observed, not from the plan
-- [ ] extend the bounded repaint (dark branch): `Keyword`, `LiteralString`, `Comment`,
+- [x] extend the bounded repaint (dark branch): `Keyword`, `LiteralString`, `Comment`,
       `LiteralNumber`, `NameFunction` take `ui.ChromaColors` (+ `Surface` background per
       the verification above); the fresh-pointer clone stays
-- [ ] **narrow, do not delete, the `reflect.DeepEqual` boundedness guard** in
+- [x] **narrow, do not delete, the `reflect.DeepEqual` boundedness guard** in
       `TestKeepkitStyleRepaintsChroma`: zero out the now-owned seven entries
       (Background, Text + the five) and assert everything else is inherited verbatim;
       rewrite its comment — the repaint is no longer "bounded to two entries", it is
       bounded to a named seven
-- [ ] write struct tests: the five entries carry the palette colors; an untouched token
+- [x] write struct tests: the five entries carry the palette colors; an untouched token
       (e.g. `Operator`) still aliases the standard value
-- [ ] mutation-check each new assertion; globals-untouched snapshot stays green
-- [ ] run tests — must pass before task 4
+- [x] mutation-check each new assertion; globals-untouched snapshot stays green
+- [x] run tests — must pass before task 4
 
 ### Task 4: Task checkboxes, blockquote italic, recorded absences
 
@@ -244,18 +249,18 @@ ladder is a 5-line var edit and the user decides then.
 - Modify: `internal/model/readme_style.go`
 - Modify: `internal/model/readme_style_test.go`
 
-- [ ] shared: `Task.Ticked = "✓ "`, `Task.Unticked = "☐ "` (renderer-confirmed by the
+- [x] shared: `Task.Ticked = "✓ "`, `Task.Unticked = "☐ "` (renderer-confirmed by the
       review; note the confirmation source in the comment)
-- [ ] dark branch: `BlockQuote.Italic = ptrTo(true)` (color stays `Dim`);
+- [x] dark branch: `BlockQuote.Italic = ptrTo(true)` (color stays `Dim`);
       renderer-confirm italic is applied before writing the test
-- [ ] record the two deliberate absences as one code comment block on `keepkitStyle`:
+- [x] record the two deliberate absences as one code comment block on `keepkitStyle`:
       list markers (`Item.Color`/`Enumeration.Color` are no-ops — BaseElement renders
       BlockPrefix with the enclosing block's style) and tables (separators are
       lipgloss-drawn with no color call; `Table`'s style colors cell content; no
       header-only style)
-- [ ] add `☐` to the glyph-width test
-- [ ] write struct tests for Ticked/Unticked and Italic; mutation-check
-- [ ] run tests — must pass before task 5
+- [x] add `☐` to the glyph-width test
+- [x] write struct tests for Ticked/Unticked and Italic; mutation-check
+- [x] run tests — must pass before task 5
 
 ### Task 5: Full-width divider
 
@@ -263,52 +268,52 @@ ladder is a 5-line var edit and the user decides then.
 - Modify: `internal/model/readme_style.go`
 - Modify: `internal/model/readme_style_test.go`
 
-- [ ] shared section: `HorizontalRule.Format = "\n" + strings.Repeat("─", width) + "\n"`
+- [x] shared section: `HorizontalRule.Format = "\n" + strings.Repeat("─", width) + "\n"`
       guarded on `width > 0` (width <= 0 keeps stock); color stays `Border` dark-only
-- [ ] record the accepted caveat comment: a `---` nested under an indent overflows
+- [x] record the accepted caveat comment: a `---` nested under an indent overflows
       rather than breaks (no breakpoints in the run)
-- [ ] rewrite the stale half-sentence in the "deliberately missing" paragraph of
+- [x] rewrite the stale half-sentence in the "deliberately missing" paragraph of
       `keepkitStyle`'s doc comment — "`HorizontalRule` is a fixed string" stops being
       true here; the injection objection (faking a heading rule needs a `---` the author
       never wrote) still stands and remains the recorded reason
-- [ ] write struct tests: Format length equals width at two widths; width=0 falls back
-- [ ] mutation-check; run tests — must pass before task 6
+- [x] write struct tests: Format length equals width at two widths; width=0 falls back
+- [x] mutation-check; run tests — must pass before task 6
 
 ### Task 6: Visual check at 80/120 columns, both variants, ladder verdict
 
 **Files:**
 - Create (throwaway): `internal/model/zz_vis_test.go` — deleted in this same task
 
-- [ ] render a fixture README (headings H1–H6, go + shell fences, nested/ordered/task
+- [x] render a fixture README (headings H1–H6, go + shell fences, nested/ordered/task
       lists, a quote, `---`, a table) through `renderReadme` at 80 and 120 columns,
       **dark and light**; read the output
-- [ ] judge the `#08605f` contrast on dark and the `#a2ad59`/`#8e936d` contrast on
+- [x] judge the `#08605f` contrast on dark and the `#a2ad59`/`#8e936d` contrast on
       light; if the inverted ladder reads wrong, show the user both orders and let them
       pick (5-line var edit either way)
-- [ ] confirm the divider spans the wrap width, the fence plate has no punch-throughs
+- [x] confirm the divider spans the wrap width, the fence plate has no punch-throughs
       around recolored tokens, checkboxes and depth markers align
-- [ ] delete `zz_vis_test.go`
-- [ ] run the full suite: `go test -race ./...`
+- [x] delete `zz_vis_test.go`
+- [x] run the full suite: `go test -race ./...`
 
 ### Task 7: Verify acceptance criteria
 
-- [ ] every element of the Solution Overview table is implemented or carries its
+- [x] every element of the Solution Overview table is implemented or carries its
       recorded deliberate-absence comment (list markers, tables)
-- [ ] every new assertion has survived its mutation check (Task 1's hex-shape smoke
+- [x] every new assertion has survived its mutation check (Task 1's hex-shape smoke
       guard exempted, as recorded there)
-- [ ] `go vet ./...` and `golangci-lint run` clean
-- [ ] full suite green: `go test -race ./...`
+- [x] `go vet ./...` and `golangci-lint run` clean
+- [x] full suite green: `go test -race ./...`
 
 ### Task 8: [Final] Update documentation
 
-- [ ] `docs/design/readme-pipeline.md`: rewrite the `keepkitStyle` section — the heading
+- [x] `docs/design/readme-pipeline.md`: rewrite the `keepkitStyle` section — the heading
       ladder and its palette, the chroma palette, the width parameter, the divider, the
       theme-switch contract change, the two deliberate absences; keep the existing
       rationale style (what broke / why this shape)
-- [ ] `CLAUDE.md`: `internal/ui` package row mentions the second non-role palette beside
+- [x] `CLAUDE.md`: `internal/ui` package row mentions the second non-role palette beside
       `LanguageColor`; the readme_style summary line follows the new shape (run
       docs-sync)
-- [ ] move this plan to `docs/plans/completed/`
+- [x] move this plan to `docs/plans/completed/`
 
 ## Post-Completion