From 72b13290874cf8a1636982c330f2810a62c7a6b9 Mon Sep 17 00:00:00 2001
From: stanlyzoolo <51911715+stanlyzoolo@users.noreply.github.com>
Date: Tue, 28 Jul 2026 00:25:06 +0300
Subject: [PATCH 1/5] docs: add README house-style implementation plan

Preprocessor (badges/HTML/emoji removal, link unwrapping) + custom glamour
theme in keepkit palette for panel [3]. Design approved in brainstorm,
hardened by plan review (URL hiding moved from style config to preprocessor
after the review's spike showed autolink deletion).

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

diff --git a/docs/plans/20260728-readme-house-style.md b/docs/plans/20260728-readme-house-style.md
new file mode 100644
index 0000000..9027cd0
--- /dev/null
+++ b/docs/plans/20260728-readme-house-style.md
@@ -0,0 +1,323 @@
+# README house style for panel [3]: markdown preprocessor + custom glamour theme
+
+## Overview
+
+Panel `[3]` renders each tool's README through glamour's standard `dark`/`light` style.
+The result is noisy and inconsistent: badge/logo/HTML junk at the top of a typical
+README, full link URLs bloating paragraphs in a narrow panel, bright standard-theme
+colors that clash with keepkit's palette, and emoji scattered through headings. This
+plan gives every README one calm "house style": a markdown cleanup pass before glamour
+plus a custom glamour theme derived from keepkit's palette.
+
+Key insight driving the cleanup rules: **no image can ever render in a TTY**, so all
+images (badges, logos, screenshots) are removable without any badge-vs-logo heuristics.
+Same for `[text](url)` links: panel `[3]` links are not clickable, so the href half is
+pure noise — the preprocessor unwraps them to their text. Autolinks and bare URLs are
+different: the URL *is* their content, so they stay visible.
+
+All design decisions were approved in a brainstorm session (2026-07-28) and hardened by
+a plan review the same day; do not re-litigate them during implementation.
+
+**Acceptance criteria** (checked in Task 5):
+- badge/logo/screenshot images gone, including reference-style (`![Build][badge]`)
+- HTML junk gone; inline-tag text (`<kbd>Ctrl</kbd>` → `Ctrl`) preserved
+- `[text](url)` renders as `text` with no URL and no double space; autolinks and bare
+  URLs still visible; no table-link footnote stubs
+- emoji and known `:shortcodes:` gone, no double-space/blank-line artifacts; `✅/❌/☑`
+  translated to `✓/✗/✓`
+- headings/rules/blockquotes in keepkit palette, no background plates
+- code blocks and inline spans byte-identical through the preprocessor
+- badge-only README → existing `No README for <name>. Press [h] for --help.` placeholder
+- `styles.DarkStyleConfig`/`LightStyleConfig` globals unmutated
+
+### Decision log
+
+- **URL hiding mechanism — resolved 2026-07-28 by plan review, approved by user.** The
+  style-level route (`Styles.Link.Format` rendering empty) was spiked against glamour
+  v1.0.0 and rejected: glamour routes autolinks and linkified bare URLs through the same
+  `Link` primitive with no separate link text, so blanking it silently deletes them
+  (`See <https://example.com/docs> here` → `See  here`); it also leaves a double space
+  where an inline link's href was, and table links leave footnote stubs. Chosen instead:
+  the preprocessor unwraps `[text](url)` / `[text][ref]` → `text`. `Conceal`/`Faint`
+  exist on `StylePrimitive` but the v1.0.0 renderer never applies them; `SkipHref` is an
+  element field unreachable from styles.
+- **4-space indented code blocks are NOT protected** by the segmentation pass (explicit
+  decision): they are ambiguous with nested-list continuation lines, and modern READMEs
+  overwhelmingly use fences. Accepted limitation, documented here.
+
+## Context (from discovery)
+
+- `internal/model/readme.go` — `renderReadme`: `cleanTerminalOutput` → glamour
+  (`WithStandardStyle(readmeStyleName(dark))`, `WithWordWrap`, `WithColorProfile`);
+  memoized by `readmeRenderCache` keyed `(name, raw, width, dark)`; test seam
+  `testReadmeStyle` (unknown style name → constructor error → plain-text fallback path).
+- `internal/model/readme_test.go` — fallback assertions at lines ~84 and ~147 compare
+  against `cleanTerminalOutput(raw)`; `TestRenderReadmeStyleFollowsBackground` (~line 90)
+  tests `readmeStyleName`'s dark/light branches.
+- `internal/ui/styles.go` — palette vars `ColorPrimary #DA7756`, `ColorCategory
+  #E8A87C`, `ColorMeta #5588AA`, `ColorMuted #AAAAAA`, `ColorDim #888888`, `ColorBorder
+  #555555`, `ColorText #E8E8E8` — the theme derives from these (`string(ui.ColorPrimary)`),
+  never from hex literals.
+- `go.mod` — `glamour v1.0.0` (direct), `goldmark-emoji v1.0.6` (indirect; carries the
+  GitHub shortcode dictionary via `definition.Github()` — note the exported name is
+  `Github`, and it is `sync.Once`-guarded internally, so no caching wrapper is needed).
+- `version.getReadme` truncates at `readmeMaxBytes` (512 KiB) and appends a marker — the
+  cut can land **mid-fence**, so the segmentation pass must handle an unterminated fence.
+- Empty-render guard reused, not extended: a README that cleans down to nothing renders
+  `""` and the `data.content != "" && m.helpBase != ""` placeholder logic already shows
+  `No README for <name>. Press [h] for --help.`.
+- Glamour-side helpers verified present in v1.0.0: `glamour.WithStyles`,
+  `glamour.WithInlineTableLinks`.
+
+## Development Approach
+
+- **testing approach**: Regular (code first, then tests in the same task)
+- complete each task fully before moving to the next
+- make small, focused changes
+- **CRITICAL: every task MUST include new/updated tests** for code changes in that task
+  - tests are not optional — they are a required part of the checklist
+  - table-driven tests for the pure preprocessor; struct-level tests for the theme
+  - tests cover both success and error scenarios
+- **CRITICAL: all tests must pass before starting next task** — no exceptions
+- **CRITICAL: update this plan file when scope changes during implementation**
+- run `go test -race ./...` after each change (version package has real mutex-guarded
+  state — keep `-race`)
+- maintain backward compatibility: the `testReadmeStyle` seam behavior and the
+  glamour-failure fallback path survive (the fallback now returns *preprocessed* text)
+- the preprocessor runs synchronously inside `Update()` on up to 512 KiB of markdown:
+  all regexes are compiled at package level (the `helpTokenRe` idiom in
+  `internal/model/textutil.go`), never per call
+
+## Testing Strategy
+
+- **unit tests**: required for every task (see Development Approach above)
+- no e2e framework in this project; the TUI-level check is manual (see Post-Completion)
+- color assertions on rendered output are deliberately avoided (no TTY in tests →
+  `lipgloss.ColorProfile()` is Ascii → glamour strips colors). The theme is covered at
+  the **struct level** instead: assert `keepkitStyle(...)` field values against
+  `ui.Color*` — the only real coverage the theme can get, and it needs no TTY.
+
+## Progress Tracking
+
+- mark completed items with `[x]` immediately when done
+- add newly discovered tasks with ➕ prefix
+- document issues/blockers with ⚠️ prefix
+- update plan if implementation deviates from original scope
+
+## Solution Overview
+
+Two independent layers, composed in `renderReadme`:
+
+1. **Preprocessor** — pure `cleanReadmeMarkdown(raw string) string` in a new
+   `internal/model/readme_clean.go`, called after `cleanTerminalOutput`, before glamour.
+   Segmentation first (fences and inline spans are inviolable), then removal rules on
+   the cleanable segments only.
+2. **Theme** — `keepkitStyle(dark bool) ansi.StyleConfig` in a new
+   `internal/model/readme_style.go`, built by **cloning** `styles.DarkStyleConfig` /
+   `styles.LightStyleConfig` and overriding accents. Clone-and-override, not
+   from-scratch: StyleConfig has dozens of fields and inheriting defaults protects
+   against "forgotten field = broken render" on glamour upgrades. **The globals hold
+   pointers** (`Color`, `BackgroundColor`, `Margin`, `Chroma`), and `styles.DefaultStyles`
+   aliases them — every override assigns a **fresh pointer**; writing through a cloned
+   pointer would mutate the shared style for the whole process.
+
+`renderReadme` switches to `WithStyles(keepkitStyle(dark))` + `WithInlineTableLinks(true)`;
+a non-empty `testReadmeStyle` keeps routing through `WithStandardStyle(name)` so the
+existing constructor-failure fallback test still works. With production no longer
+choosing a style *name*, `readmeStyleName` degenerates to the test branch — it is
+deleted, `renderReadme` branches on `testReadmeStyle != ""` directly, and
+`TestRenderReadmeStyleFollowsBackground` goes with it (the project removes dead branches
+*and their test rows* — see CLAUDE.md on `restart_unix.go`).
+
+The `readmeRenderCache` key stays `(name, raw, width, dark)` — `raw` is the
+pre-cleanup input and the pipeline is deterministic, so memoization stays correct.
+
+## Technical Details
+
+### Segmentation (the inviolable-code rule)
+
+- Fenced blocks: opener is 3+ backticks or 3+ tildes (info string allowed); the closer
+  is the **same character with length ≥ the opener's** — a ````` ```` ````` fence
+  wrapping ``` examples (how READMEs document markdown itself) stays one block.
+- An **unterminated fence protects to EOF** (real case: the 512 KiB truncation can cut
+  mid-fence).
+- Inline `` `spans` `` are protected within cleanable segments.
+- 4-space indented code blocks are *not* protected (see Decision log).
+
+### Removal rules (cleanable segments only)
+
+- **Images**: inline `![alt](url)`, linked `[![alt](img)](target)`, and
+  reference-style `![alt][ref]` / `![alt][]` removed whole; lines left empty collapse
+  so a 10-badge header vanishes.
+- **Link-reference definitions**: standalone `[label]: url "title"` lines removed —
+  they are pure metadata, and after image removal and link unwrapping nothing uses them.
+- **Links**: `[text](url)` and `[text][ref]` unwrapped to `text`. Autolinks
+  `<https://…>`, `<user@host>` and bare URLs are **left untouched** — their URL is the
+  content (see Decision log).
+- **HTML**: comments `<!-- … -->` removed whole; `<img>`/`<picture>`/`<video>`/
+  `<script>`/`<style>` elements removed whole **including bodies**; other tags stripped
+  keeping inner text (`<kbd>Ctrl</kbd>` → `Ctrl`, `<details><summary>` content
+  survives). The tag pattern is constrained to a plausible HTML tag-name shape so
+  autolinks, `<user@host>`, and prose/type angle brackets (`Vec<String>`, `a < b`)
+  survive. No general sanitizer (bluemonday) — a targeted strip suffices.
+- **Emoji**: pictographic SMP blocks U+1F000–U+1FAFF, VS16 (U+FE0F), ZWJ (U+200D) and
+  the combining enclosing keycap (U+20E3) removed; translation map `✅→✓`, `❌→✗`,
+  `☑→✓` (feature tables keep meaning, in panel style); BMP symbols `✓ ★ →` kept.
+  After removal, doubled spaces collapse and lines emptied by it are dropped —
+  `## 🚀 Getting Started` → `## Getting Started`, an emoji-only heading disappears
+  rather than rendering as a styled blank.
+- **Shortcodes**: `:name:` removed **only when `name` is in `definition.Github()`** —
+  `:30:` inside `12:30:45` and unknown `:foo:` survive.
+
+### Theme overrides
+
+Dark variant (values from `internal/ui/styles.go`, never hex literals); light inherits
+`LightStyleConfig` text colors and takes only the peach accents (`#E8E8E8` text is
+unreadable on white):
+
+- **H1** bold `ui.ColorPrimary`, **no background plate** (`BackgroundColor = nil`) —
+  the standard style's bright plate is the main "tastelessness" source; **H2**
+  `ui.ColorCategory` bold; **H3+** bold text color.
+- **Links**: `LinkText` tinted `ui.ColorMeta`; no `Format` tricks (see Decision log —
+  the preprocessor already removed hrefs; what remains linkified is autolinks/bare
+  URLs, whose text is the URL).
+- **Rules/blockquotes**: `ui.ColorBorder` / `ui.ColorDim`, matching panel frames.
+- **Document margin 0** (fresh `*uint`): glamour's own margin eats 2–4 columns inside
+  the already narrow `helpWrapWidth`; the panel frame provides the breathing room.
+- **Code blocks**: chroma theme untouched (YAGNI — adjustable later as a one-liner).
+
+## What Goes Where
+
+- **Implementation Steps** (`[ ]` checkboxes): code, tests, docs achievable in this repo
+- **Post-Completion** (no checkboxes): manual TUI verification, demo-gif re-recording
+
+## Implementation Steps
+
+### Task 1: Segmentation core — fences and inline spans
+
+**Files:**
+- Create: `internal/model/readme_clean.go`
+- Create: `internal/model/readme_clean_test.go`
+
+- [ ] implement segmentation of raw markdown into protected segments (fenced blocks per
+      the rules above, inline `` ` `` spans) and cleanable segments, plus the
+      `cleanReadmeMarkdown` shell that reassembles them (rules arrive in Tasks 2–3)
+- [ ] handle the edge shapes: fence with info string; `~~~` fence; closer same-char and
+      length ≥ opener (````` ```` ````` wrapping ``` blocks); unterminated fence
+      protects to EOF
+- [ ] write protection tests: junk-shaped content (`![…](…)`, `<div>`, emoji) inside a
+      fence and inside an inline span survives byte-for-byte through the shell
+- [ ] write segmentation edge tests: long fence wrapping short fences; unterminated
+      fence (simulated 512 KiB truncation cut); `~~~` with info string
+- [ ] run tests — must pass before task 2
+
+### Task 2: Removal rules — images, links, HTML
+
+**Files:**
+- Modify: `internal/model/readme_clean.go`
+- Modify: `internal/model/readme_clean_test.go`
+
+- [ ] implement image removal: `![alt](url)`, `[![alt](img)](target)`,
+      reference-style `![alt][ref]` / `![alt][]`; collapse lines left empty
+- [ ] implement link unwrapping `[text](url)` / `[text][ref]` → `text`; remove
+      standalone link-reference definition lines; leave autolinks
+      (`<https://…>`, `<user@host>`) and bare URLs untouched
+- [ ] implement HTML removal: comments whole; `<img>`/`<picture>`/`<video>`/`<script>`/
+      `<style>` whole including bodies; other tags stripped keeping inner text, tag
+      pattern constrained to plausible HTML tag names; package-level regexes only
+- [ ] write table-driven tests: inline/linked/reference badge headers vanish with no
+      orphan definitions; `[text](url)` → `text`; `<kbd>`/`<details>` keep text;
+      `<script>` body gone
+- [ ] write negative tests: autolink, email autolink, `Vec<String>`, `a < b` prose, and
+      bare URLs all survive; `:30:`-style text untouched by these rules
+- [ ] run tests — must pass before task 3
+
+### Task 3: Removal rules — emoji and shortcodes
+
+**Files:**
+- Modify: `internal/model/readme_clean.go`
+- Modify: `internal/model/readme_clean_test.go`
+- Modify: `go.mod` (goldmark-emoji indirect → direct)
+
+- [ ] implement emoji stripping (U+1F000–U+1FAFF, VS16, ZWJ, U+20E3) with the
+      translation map `✅→✓`, `❌→✗`, `☑→✓`; keep BMP symbols (`✓ ★ →`)
+- [ ] implement post-removal cleanup: collapse doubled spaces, drop lines emptied by
+      removal (emoji-only headings disappear)
+- [ ] implement shortcode removal via `definition.Github()` (direct import; no new
+      module in go.sum; no caching wrapper — it is `sync.Once`-guarded)
+- [ ] write tests: emoji stripped from headings/prose without double-space artifacts;
+      emoji-only heading dropped; keycap `1️⃣` leaves no stray U+20E3; translation map
+      applied; BMP symbols survive
+- [ ] write negative tests: `:30:` inside `12:30:45` survives; unknown `:foo:` survives;
+      known `:rocket:` removed; shortcode and emoji inside a fence survive
+- [ ] run tests — must pass before task 4
+
+### Task 4: Theme — keepkitStyle and renderReadme integration
+
+**Files:**
+- Create: `internal/model/readme_style.go`
+- Create: `internal/model/readme_style_test.go`
+- Modify: `internal/model/readme.go`
+- Modify: `internal/model/readme_test.go`
+
+- [ ] implement `keepkitStyle(dark bool) ansi.StyleConfig` per Technical Details:
+      clone the standard config, override headings/links/rules/margin with values
+      derived from `ui.Color*`; every override assigns a **fresh pointer** — never
+      write through a cloned pointer
+- [ ] wire the pipeline in `renderReadme`: `cleanTerminalOutput` →
+      `cleanReadmeMarkdown` (re-check emptiness after it — early return `""`) → glamour
+      with `WithStyles(keepkitStyle(dark))` + `WithInlineTableLinks(true)`; the
+      plain-text fallback returns the *preprocessed* text
+- [ ] collapse the dead seam: branch on `testReadmeStyle != ""` directly in
+      `renderReadme` (→ `WithStandardStyle(testReadmeStyle)`), delete
+      `readmeStyleName`, delete `TestRenderReadmeStyleFollowsBackground`
+- [ ] update the two fallback assertions (`readme_test.go` ~84, ~147) to compare
+      against `cleanReadmeMarkdown(cleanTerminalOutput(raw))`; add one fallback case
+      whose input the preprocessor actually changes
+- [ ] write struct-level theme tests: `H1.Color == string(ui.ColorPrimary)` (deref),
+      `H1.BackgroundColor == nil`, `*Document.Margin == 0`, dark/light differ; plus a
+      regression test that `styles.DarkStyleConfig`/`LightStyleConfig` are deep-equal
+      to their pre-call values after both `keepkitStyle(true)` and `keepkitStyle(false)`
+- [ ] write behavioral tests: `[text](url)` renders as `text` — URL absent, **no double
+      space**; a table with a `[manual](url)` link renders the cell with no footnote
+      stub; autolink and bare URL still visible; both variants render a sample doc
+      without error; badge-only README renders to `""`
+- [ ] run tests — must pass before task 5
+
+### Task 5: Verify acceptance criteria
+
+- [ ] verify every bullet of the **Acceptance criteria** list in the Overview
+- [ ] verify edge cases: README of only badges/HTML → friendly placeholder; README with
+      HTML/markdown examples inside fences → examples intact; truncated-mid-fence input
+- [ ] run full CI matrix locally: `go build .`, `go vet ./...`,
+      `go test -race ./...`, `golangci-lint run` (preflight)
+- [ ] verify go.mod/go.sum changed only by the goldmark-emoji promotion (no new modules)
+
+### Task 6: [Final] Update documentation
+
+- [ ] update CLAUDE.md: `model` package file table (~line 50: add `readme_clean.go`,
+      `readme_style.go`) and the panel `[3]` modes paragraph (~line 111: the "runs
+      glamour with a **fixed** `WithStandardStyle("dark"|"light")`" clause → the new
+      pipeline)
+- [ ] update ARCHITECTURE.md in its three spots: the `model` file table (~line 74,
+      `readme.go` row), the "passed to glamour as a fixed `WithStandardStyle`" clause
+      (~line 134), and the `testReadmeStyle` seam description (~line 399)
+- [ ] check README.md: only the Glamour credit line (~262) touches this area — update
+      only if the rendering description changed
+- [ ] move this plan to `docs/plans/completed/`
+
+## Post-Completion
+
+**Manual verification:**
+- open keepkit in a dark and a light terminal; walk several real READMEs (badge-heavy,
+  HTML-heavy, emoji-heavy, one with code examples containing HTML, one with a
+  links-in-table feature matrix) and confirm the house style reads calmly and nothing
+  legitimate was eaten
+- taste pass on the theme: heading/link tints may need 1–2 iterations by eye — the
+  first values are educated guesses
+
+**External follow-ups:**
+- re-record demo GIFs (`demo-gifs` skill): `hero.gif` shows panel `[3]` with a rendered
+  README and will visibly change
+- this branch lives in worktree `readme-house-style`
+  (branch `worktree-readme-house-style`); merge via PR to `main` as usual

From e1ad93c11809a787950f7f69333cccd84c67fd65 Mon Sep 17 00:00:00 2001
From: stanlyzoolo <51911715+stanlyzoolo@users.noreply.github.com>
Date: Tue, 28 Jul 2026 12:44:46 +0300
Subject: [PATCH 2/5] feat(model): clean up a README before it reaches glamour
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A README is written for a browser. Panel [3] handed glamour whatever the
repo shipped: rows of badge images, a <picture> logo wrapper, full hrefs
bloating paragraphs in a narrow panel, and emoji a terminal font renders
as tofu.

cleanReadmeMarkdown is a pure pass that removes them. No image can ever
render in a TTY, so images go whole in every form and no badge-vs-logo
heuristic is needed; panel [3] links are not clickable, so [text](url) is
unwrapped to its text. Autolinks and bare URLs stay — the URL is their
content.

Code is never rewritten, which is what the segmentation is for: a fenced
block and an inline span are exactly how a README shows the markup these
rules delete. Fences are split out first — an unterminated one protects
to EOF, since version.getReadme truncates at readmeMaxBytes and the cut
can land mid-fence — and inline spans are masked inside a cleanable
segment rather than segmented out, because the block-level rules (a
multi-line comment, a <picture> body) need the segment to stay one
string and a span containing "<!--" has to survive too.

Two gates keep the rules from eating content. The HTML tag strip matches
an allowlist of the elements READMEs actually use, not a generic
identifier shape: by shape there is no telling <kbd> from Vec<String>,
and an unknown name left as written is the honest degradation. Shortcut
references ([label]) are unwrapped only for labels a definition actually
declared, collected document-wide because definitions collect at the
bottom while their uses sit at the top; ungated, the rule would eat a
task list's [x].

The per-line tidy-up is gated on the line having changed, so an
untouched "- - -" is never mistaken for an emptied bullet and a hard
line break keeps its trailing spaces. Its indent comes from the original
line: a leading pictograph that removal turns into a space would
otherwise become an indent the author never wrote, and four of them read
as an indented code block.

Shortcodes go only when the name is in goldmark-emoji's GitHub
dictionary — the one glamour already pulls in, so promoting it to a
direct dependency adds nothing to go.sum.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../20260728-readme-house-style.md            |   0
 go.mod                                        |   2 +-
 internal/model/readme_clean.go                | 486 ++++++++++++++++++
 internal/model/readme_clean_test.go           | 462 +++++++++++++++++
 internal/model/textutil.go                    |   5 +-
 5 files changed, 953 insertions(+), 2 deletions(-)
 rename docs/plans/{ => completed}/20260728-readme-house-style.md (100%)
 create mode 100644 internal/model/readme_clean.go
 create mode 100644 internal/model/readme_clean_test.go

diff --git a/docs/plans/20260728-readme-house-style.md b/docs/plans/completed/20260728-readme-house-style.md
similarity index 100%
rename from docs/plans/20260728-readme-house-style.md
rename to docs/plans/completed/20260728-readme-house-style.md
diff --git a/go.mod b/go.mod
index ca7d794..3afa3ee 100644
--- a/go.mod
+++ b/go.mod
@@ -10,6 +10,7 @@ require (
 	github.com/charmbracelet/x/ansi v0.11.6
 	github.com/mattn/go-runewidth v0.0.19
 	github.com/muesli/termenv v0.16.0
+	github.com/yuin/goldmark-emoji v1.0.6
 	golang.org/x/mod v0.37.0
 	gopkg.in/yaml.v3 v3.0.1
 )
@@ -39,7 +40,6 @@ require (
 	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
 	github.com/yuin/goldmark v1.7.17 // indirect
-	github.com/yuin/goldmark-emoji v1.0.6 // indirect
 	golang.org/x/net v0.38.0 // indirect
 	golang.org/x/sys v0.38.0 // indirect
 	golang.org/x/term v0.36.0 // indirect
diff --git a/internal/model/readme_clean.go b/internal/model/readme_clean.go
new file mode 100644
index 0000000..36cfe4d
--- /dev/null
+++ b/internal/model/readme_clean.go
@@ -0,0 +1,486 @@
+package model
+
+import (
+	"regexp"
+	"strconv"
+	"strings"
+
+	"github.com/yuin/goldmark-emoji/definition"
+)
+
+// README preprocessing — the cleanup pass that runs between cleanTerminalOutput
+// and glamour so panel [3] shows one calm house style instead of whatever
+// badge/HTML/emoji noise the upstream repo happens to ship.
+//
+// The pass rests on one inviolable rule: code is never rewritten. A fenced
+// block and an inline span are exactly how a README *shows* the markup these
+// rules delete, so segmentation runs first and the removal rules only ever see
+// the text between the protected parts.
+
+// rcSegment is one run of consecutive lines, tagged with whether the removal
+// rules may rewrite it. Segments are line runs, so joining every segment's text
+// with "\n" reproduces the input exactly.
+type rcSegment struct {
+	text      string
+	protected bool
+}
+
+var (
+	// A fenced-code opener: 3+ backticks or 3+ tildes, an info string allowed
+	// after them. The indent is deliberately unconstrained, like mdFenceRe's —
+	// 4+ spaces would mean an indented code block, which this pass does not
+	// implement, so CommonMark's 3-space limit would only mis-read a fence
+	// nested under a list item.
+	rcFenceOpenRe = regexp.MustCompile("^[ \t]*(`{3,}|~{3,})")
+	// A closer carries the same marker character, a run at least as long as the
+	// opener's, and nothing but whitespace after it — which is what keeps a
+	// ```` fence wrapping ``` examples (how a README documents markdown itself)
+	// one single block.
+	rcFenceCloseRe = regexp.MustCompile("^[ \t]*(`{3,}|~{3,})[ \t]*$")
+)
+
+// rcFenceCloses reports whether line closes a fence opened with marker.
+func rcFenceCloses(line, marker string) bool {
+	m := rcFenceCloseRe.FindStringSubmatch(line)
+	if m == nil {
+		return false
+	}
+	run := m[1]
+	return run[0] == marker[0] && len(run) >= len(marker)
+}
+
+// rcSegments splits raw README markdown into protected fenced blocks and the
+// cleanable runs between them. An unterminated fence protects everything to
+// EOF: version.getReadme truncates at readmeMaxBytes and the cut can land
+// mid-fence, where half a code sample is still code.
+func rcSegments(s string) []rcSegment {
+	lines := strings.Split(s, "\n")
+	var (
+		segs      []rcSegment
+		cleanable []string
+	)
+	flush := func() {
+		if len(cleanable) > 0 {
+			segs = append(segs, rcSegment{text: strings.Join(cleanable, "\n")})
+			cleanable = nil
+		}
+	}
+	for i := 0; i < len(lines); {
+		open := rcFenceOpenRe.FindStringSubmatch(lines[i])
+		if open == nil {
+			cleanable = append(cleanable, lines[i])
+			i++
+			continue
+		}
+		flush()
+		block := []string{lines[i]}
+		i++
+		for i < len(lines) {
+			line := lines[i]
+			block = append(block, line)
+			i++
+			if rcFenceCloses(line, open[1]) {
+				break
+			}
+		}
+		segs = append(segs, rcSegment{text: strings.Join(block, "\n"), protected: true})
+	}
+	flush()
+	return segs
+}
+
+// rcSpanMark brackets a masked inline code span. NUL is the sentinel because
+// cleanTerminalOutput — which every production caller runs first — drops every
+// control character, so no README text can collide with it.
+const rcSpanMark = "\x00"
+
+var rcSpanMarkRe = regexp.MustCompile("\x00(\\d+)\x00")
+
+// rcMaskSpans replaces every inline code span with an opaque placeholder so the
+// removal rules cannot rewrite what a README meant to show verbatim. The second
+// result is the restore table for rcUnmaskSpans.
+func rcMaskSpans(s string) (string, []string) {
+	if !strings.Contains(s, "`") {
+		return s, nil
+	}
+	var (
+		b     strings.Builder
+		spans []string
+	)
+	for i := 0; i < len(s); {
+		if s[i] != '`' {
+			b.WriteByte(s[i])
+			i++
+			continue
+		}
+		j := i
+		for j < len(s) && s[j] == '`' {
+			j++
+		}
+		if end := rcSpanEnd(s, j, j-i); end > 0 {
+			spans = append(spans, s[i:end])
+			b.WriteString(rcSpanMark + strconv.Itoa(len(spans)-1) + rcSpanMark)
+			i = end
+			continue
+		}
+		// No closing run of the same length: literal backticks, not a span.
+		b.WriteString(s[i:j])
+		i = j
+	}
+	return b.String(), spans
+}
+
+// rcSpanEnd returns the index just past the backtick run that closes a span
+// opened with run backticks at from, or 0 when the span is never closed. The
+// search stops at a blank line, mirroring CommonMark's paragraph boundary:
+// letting one stray backtick pair with another three sections later would
+// exempt half a README from cleaning.
+func rcSpanEnd(s string, from, run int) int {
+	for i := from; i < len(s); {
+		switch s[i] {
+		case '\n':
+			j := i + 1
+			for j < len(s) && (s[j] == ' ' || s[j] == '\t') {
+				j++
+			}
+			if j >= len(s) || s[j] == '\n' {
+				return 0
+			}
+			i = j
+		case '`':
+			j := i
+			for j < len(s) && s[j] == '`' {
+				j++
+			}
+			if j-i == run {
+				return j
+			}
+			i = j
+		default:
+			i++
+		}
+	}
+	return 0
+}
+
+// rcUnmaskSpans puts every masked code span back where its placeholder sits.
+func rcUnmaskSpans(s string, spans []string) string {
+	if len(spans) == 0 {
+		return s
+	}
+	return rcSpanMarkRe.ReplaceAllStringFunc(s, func(m string) string {
+		idx, err := strconv.Atoi(strings.Trim(m, rcSpanMark))
+		if err != nil || idx < 0 || idx >= len(spans) {
+			return ""
+		}
+		return spans[idx]
+	})
+}
+
+// HTML rules that need the whole segment: a comment and a <picture> body
+// routinely span several lines, which a per-line pass could never see.
+var (
+	rcHTMLCommentRe = regexp.MustCompile(`(?s)<!--.*?-->`)
+
+	// Elements dropped with their bodies — a <picture> is a badge/logo wrapper
+	// and an <svg> is the logo itself, neither of which a TTY can show. RE2 has
+	// no backreference, so each name gets its own pattern instead of one
+	// \1-closed alternation. <img> needs no entry here: it is void, so the tag
+	// strip below already removes the whole element.
+	rcHTMLBodyElemRes = rcCompileBodyElems("picture", "video", "audio", "svg", "script", "style")
+
+	// Every other tag is stripped keeping its inner text (<kbd>Ctrl</kbd> →
+	// Ctrl, a <details>/<summary> block keeps its content). The name is matched
+	// against a fixed list rather than a generic identifier shape, which is
+	// what lets autolinks (<https://…>, <user@host>) and prose angle brackets
+	// (Vec<String>, a < b) through untouched — an unknown name is left as
+	// written, the honest degradation.
+	rcHTMLTagRe = regexp.MustCompile(`(?is)</?(?:` + strings.Join(rcHTMLNames, "|") + `)\b(?:\s[^<>]*)?/?>`)
+)
+
+// rcHTMLNames is the tag allowlist for rcHTMLTagRe: the elements READMEs
+// actually use. The bodied names appear here too, so a stray closing tag left
+// by an unbalanced <picture> is still cleaned up.
+var rcHTMLNames = []string{
+	"a", "abbr", "address", "article", "aside", "audio", "b", "blockquote", "br",
+	"caption", "center", "cite", "code", "col", "colgroup", "dd", "del", "details",
+	"dfn", "div", "dl", "dt", "em", "embed", "figcaption", "figure", "font",
+	"footer", "h1", "h2", "h3", "h4", "h5", "h6", "header", "hgroup", "hr", "i",
+	"iframe", "img", "ins", "kbd", "li", "main", "mark", "nav", "nobr", "noscript",
+	"object", "ol", "p", "param", "picture", "pre", "q", "s", "samp", "script",
+	"section", "small", "source", "span", "strike", "strong", "style", "sub",
+	"summary", "sup", "svg", "table", "tbody", "td", "tfoot", "th", "thead",
+	"time", "tr", "track", "tt", "u", "ul", "var", "video", "wbr",
+}
+
+// rcCompileBodyElems builds the open-tag-to-close-tag pattern for each name.
+func rcCompileBodyElems(names ...string) []*regexp.Regexp {
+	res := make([]*regexp.Regexp, 0, len(names))
+	for _, n := range names {
+		res = append(res, regexp.MustCompile(`(?is)<`+n+`\b[^<>]*>.*?</`+n+`\s*>`))
+	}
+	return res
+}
+
+// Line-level patterns. Inline images and links reuse textutil.go's mdImageRe /
+// mdLinkRe — the same grammar fact, a different consumer.
+var (
+	// A link-reference definition line: pure metadata, and after image removal
+	// and link unwrapping nothing points at it any more.
+	rcLinkDefRe = regexp.MustCompile(`^[ \t]{0,3}\[([^\]]+)\]:[ \t]*\S`)
+
+	rcRefImageRe = regexp.MustCompile(`!\[([^\]]*)\]\[([^\]]*)\]`)
+	rcRefLinkRe  = regexp.MustCompile(`\[([^\]]*)\]\[([^\]]*)\]`)
+
+	// The shortcut form, [label] with the definition supplying the URL. It runs
+	// last, when every bracketed construct with a destination is already gone,
+	// and only for labels a definition actually declared — otherwise a task-list
+	// "[x]" or a prose "[experimental]" would lose its brackets.
+	rcShortcutRe = regexp.MustCompile(`(!?)\[([^\]]*)\]`)
+
+	// A leading block marker, stripped only to ask "did removal leave this line
+	// with nothing to say?". The heading and list forms require whitespace (or
+	// end of line) after the marker, so a "#hashtag" keeps its text and a "---"
+	// rule is never mistaken for a bullet.
+	rcBlockMarkerRe = regexp.MustCompile(`^[ \t]*(?:#{1,6}(?:[ \t]+|$)|>[ \t]?|[-*+](?:[ \t]+|$)|\d{1,9}[.)](?:[ \t]+|$))`)
+
+	rcInnerSpacesRe = regexp.MustCompile(`  +`)
+
+	// A GitHub emoji shortcode. The name class is deliberately wide enough for
+	// ":+1:" and ":e-mail:"; what decides a match is the dictionary lookup, not
+	// the shape — ":30:" inside "12:30:45" matches this pattern and survives
+	// because no emoji is named "30".
+	rcShortcodeRe = regexp.MustCompile(`:([a-zA-Z0-9_+-]+):`)
+)
+
+// rcShortcodes is GitHub's shortcode dictionary — the same one goldmark-emoji
+// gives glamour, so keepkit and the renderer agree on what a shortcode is. The
+// package builds it under a sync.Once and only reads it afterwards.
+var rcShortcodes = definition.Github()
+
+// rcEmojiTranslations keep a feature table readable after the pictographs are
+// gone: a ✅/❌ column carries the meaning of the row, so those two (and the
+// ballot-box tick) become the panel's own plain marks instead of vanishing.
+var rcEmojiTranslations = strings.NewReplacer(
+	"✅", "✓",
+	"❌", "✗",
+	"☑", "✓",
+)
+
+// rcStripEmoji drops the pictographic runes a TTY renders as tofu or as a
+// double-width smear, plus the joiners that would otherwise be left stranded:
+// the variation selector (U+FE0F), the zero-width joiner and the combining
+// enclosing keycap that turns "1" into 1️⃣. BMP symbols a terminal font does
+// carry — ✓ ★ → — are deliberately kept.
+func rcStripEmoji(s string) string {
+	s = rcEmojiTranslations.Replace(s)
+	if !strings.ContainsFunc(s, rcIsEmojiRune) {
+		return s
+	}
+	return strings.Map(func(r rune) rune {
+		if rcIsEmojiRune(r) {
+			return -1
+		}
+		return r
+	}, s)
+}
+
+func rcIsEmojiRune(r rune) bool {
+	switch {
+	case r >= 0x1F000 && r <= 0x1FAFF:
+		return true
+	case r == 0xFE0F, r == 0x200D, r == 0x20E3:
+		return true
+	}
+	return false
+}
+
+// rcStripShortcodes removes ":name:" for names GitHub actually defines, so an
+// unknown ":foo:" and a clock reading stay as written.
+func rcStripShortcodes(s string) string {
+	if !strings.Contains(s, ":") {
+		return s
+	}
+	return rcShortcodeRe.ReplaceAllStringFunc(s, func(m string) string {
+		if _, ok := rcShortcodes.Get(strings.Trim(m, ":")); ok {
+			return ""
+		}
+		return m
+	})
+}
+
+// cleanReadmeMarkdown is the whole preprocessing pass: segment, then rewrite
+// only the cleanable segments. It is pure — every rule is a string rewrite — so
+// the tables test it directly.
+func cleanReadmeMarkdown(s string) string {
+	if s == "" {
+		return ""
+	}
+	// The mask sentinel is NUL and production input has none, but dropping any
+	// here keeps a direct caller from smuggling a placeholder into the restore
+	// table.
+	s = strings.ReplaceAll(s, rcSpanMark, "")
+
+	segs := rcSegments(s)
+	labels := rcDefinedLabels(segs)
+	out := make([]string, 0, len(segs))
+	for _, seg := range segs {
+		if seg.protected {
+			out = append(out, seg.text)
+			continue
+		}
+		out = append(out, rcCleanSegment(seg.text, labels))
+	}
+	return strings.Join(out, "\n")
+}
+
+// rcDefinedLabels collects every declared link-reference label, document-wide:
+// definitions collect at the bottom of a README while their shortcut uses sit
+// at the top, and a fence between the two puts them in different segments.
+func rcDefinedLabels(segs []rcSegment) map[string]bool {
+	labels := make(map[string]bool)
+	for _, seg := range segs {
+		if seg.protected {
+			continue
+		}
+		for _, line := range strings.Split(seg.text, "\n") {
+			if m := rcLinkDefRe.FindStringSubmatch(line); m != nil {
+				labels[rcNormalizeLabel(m[1])] = true
+			}
+		}
+	}
+	return labels
+}
+
+// rcNormalizeLabel folds a reference label the way CommonMark matches them:
+// case-insensitively, with internal whitespace collapsed.
+func rcNormalizeLabel(s string) string {
+	return strings.ToLower(strings.Join(strings.Fields(s), " "))
+}
+
+// rcCleanSegment applies every removal rule to one cleanable segment, with
+// inline code spans masked out for the duration.
+func rcCleanSegment(s string, labels map[string]bool) string {
+	masked, spans := rcMaskSpans(s)
+	masked = rcStripHTML(masked)
+	masked = rcCleanLines(masked, labels)
+	masked = rcCollapseBlankRuns(masked)
+	return rcUnmaskSpans(masked, spans)
+}
+
+// rcStripHTML runs the segment-wide HTML rules. Comments go first: a script or
+// style body may well contain "-->" and would otherwise cut a comment short.
+func rcStripHTML(s string) string {
+	if !strings.Contains(s, "<") {
+		return s
+	}
+	s = rcHTMLCommentRe.ReplaceAllString(s, "")
+	for _, re := range rcHTMLBodyElemRes {
+		s = re.ReplaceAllString(s, "")
+	}
+	return rcHTMLTagRe.ReplaceAllString(s, "")
+}
+
+// rcCleanLines applies the per-line rules and drops what removal emptied. Both
+// the tidy-up and the drop are gated on the line having actually changed, so an
+// untouched line keeps its trailing spaces (a hard line break) and a "- - -"
+// thematic break is never mistaken for an emptied bullet.
+func rcCleanLines(s string, labels map[string]bool) string {
+	lines := strings.Split(s, "\n")
+	out := make([]string, 0, len(lines))
+	for _, line := range lines {
+		if rcLinkDefRe.MatchString(line) {
+			continue
+		}
+		cleaned := rcCleanLine(line, labels)
+		if cleaned == line {
+			out = append(out, line)
+			continue
+		}
+		cleaned = rcTidyLine(line, cleaned)
+		if rcLineContent(cleaned) == "" {
+			continue
+		}
+		out = append(out, cleaned)
+	}
+	return strings.Join(out, "\n")
+}
+
+// rcCleanLine removes images, unwraps links and strips emoji. Order is
+// load-bearing twice: an image goes before the link that may wrap it, so a
+// linked badge "[![alt](img)](target)" collapses to nothing instead of leaving
+// a stray "!"; and the emoji pass runs after the unwrapping, so a "[🚀 Go](url)"
+// link is reduced to its text first and the pictograph is then found there.
+func rcCleanLine(line string, labels map[string]bool) string {
+	line = mdImageRe.ReplaceAllString(line, "")
+	line = rcRefImageRe.ReplaceAllString(line, "")
+	line = mdLinkRe.ReplaceAllString(line, "$1")
+	line = rcRefLinkRe.ReplaceAllString(line, "$1")
+	line = rcUnwrapShortcuts(line, labels)
+	line = rcStripEmoji(line)
+	return rcStripShortcodes(line)
+}
+
+// rcUnwrapShortcuts resolves the [label] form for declared labels only.
+func rcUnwrapShortcuts(s string, labels map[string]bool) string {
+	if len(labels) == 0 || !strings.Contains(s, "[") {
+		return s
+	}
+	return rcShortcutRe.ReplaceAllStringFunc(s, func(m string) string {
+		g := rcShortcutRe.FindStringSubmatch(m)
+		if !labels[rcNormalizeLabel(g[2])] {
+			return m
+		}
+		if g[1] == "!" {
+			return ""
+		}
+		return g[2]
+	})
+}
+
+// rcTidyLine repairs the spacing a removal left behind. The indent comes from
+// the ORIGINAL line, not the cleaned one: list nesting depends on it, while a
+// leading "🚀 " that removal turned into a space would otherwise become an
+// indent the author never wrote — four of them and markdown reads the line as
+// an indented code block.
+func rcTidyLine(orig, cleaned string) string {
+	indent := orig[:len(orig)-len(strings.TrimLeft(orig, " \t"))]
+	body := strings.TrimSpace(cleaned)
+	return indent + rcInnerSpacesRe.ReplaceAllString(body, " ")
+}
+
+// rcLineContent strips leading block markers so the caller can ask whether a
+// line still says anything. "## 🚀" cleans to "##", which is a heading with no
+// content — glamour would render it as a styled blank row.
+func rcLineContent(line string) string {
+	for {
+		next := rcBlockMarkerRe.ReplaceAllString(line, "")
+		if next == line {
+			break
+		}
+		line = next
+	}
+	return strings.TrimSpace(line)
+}
+
+// rcCollapseBlankRuns folds consecutive blank lines into one. A badge header
+// wrapped in <p align="center"> leaves a blank line per removed element; in
+// markdown one blank line and five mean the same break, so the fold is free.
+func rcCollapseBlankRuns(s string) string {
+	lines := strings.Split(s, "\n")
+	out := make([]string, 0, len(lines))
+	blank := false
+	for _, line := range lines {
+		if strings.TrimSpace(line) == "" {
+			if blank {
+				continue
+			}
+			blank = true
+			out = append(out, "")
+			continue
+		}
+		blank = false
+		out = append(out, line)
+	}
+	return strings.Join(out, "\n")
+}
diff --git a/internal/model/readme_clean_test.go b/internal/model/readme_clean_test.go
new file mode 100644
index 0000000..3f84d72
--- /dev/null
+++ b/internal/model/readme_clean_test.go
@@ -0,0 +1,462 @@
+package model
+
+import (
+	"strings"
+	"testing"
+)
+
+// segJoin reassembles what rcSegments split, which must reproduce the input
+// byte for byte — segments are line runs, nothing else.
+func segJoin(segs []rcSegment) string {
+	parts := make([]string, len(segs))
+	for i, s := range segs {
+		parts[i] = s.text
+	}
+	return strings.Join(parts, "\n")
+}
+
+func TestRcSegments(t *testing.T) {
+	tests := []struct {
+		name string
+		in   string
+		want []rcSegment
+	}{
+		{
+			name: "no fence",
+			in:   "# Title\n\nbody\n",
+			want: []rcSegment{{text: "# Title\n\nbody\n"}},
+		},
+		{
+			name: "fence with info string",
+			in:   "intro\n```go\ncode\n```\nafter\n",
+			want: []rcSegment{
+				{text: "intro"},
+				{text: "```go\ncode\n```", protected: true},
+				{text: "after\n"},
+			},
+		},
+		{
+			name: "tilde fence with info string",
+			in:   "intro\n~~~sh\ncode\n~~~\nafter",
+			want: []rcSegment{
+				{text: "intro"},
+				{text: "~~~sh\ncode\n~~~", protected: true},
+				{text: "after"},
+			},
+		},
+		{
+			// How a README documents markdown itself: the outer fence must
+			// swallow the inner ``` blocks rather than closing on the first one.
+			name: "long fence wraps short fences",
+			in:   "intro\n````md\n```go\ncode\n```\n````\nafter",
+			want: []rcSegment{
+				{text: "intro"},
+				{text: "````md\n```go\ncode\n```\n````", protected: true},
+				{text: "after"},
+			},
+		},
+		{
+			// A tilde run never closes a backtick fence.
+			name: "closer must match the opener character",
+			in:   "```\ncode\n~~~\nstill code\n```\nafter",
+			want: []rcSegment{
+				{text: "```\ncode\n~~~\nstill code\n```", protected: true},
+				{text: "after"},
+			},
+		},
+		{
+			// version.getReadme truncates at readmeMaxBytes and the cut can land
+			// mid-fence; half a code sample is still code.
+			name: "unterminated fence protects to EOF",
+			in:   "intro\n```go\ncode\n![badge](a.png)",
+			want: []rcSegment{
+				{text: "intro"},
+				{text: "```go\ncode\n![badge](a.png)", protected: true},
+			},
+		},
+		{
+			name: "fence nested under a list item",
+			in:   "1. step\n\n    ```sh\n    run\n    ```\n\ndone",
+			want: []rcSegment{
+				{text: "1. step\n"},
+				{text: "    ```sh\n    run\n    ```", protected: true},
+				{text: "\ndone"},
+			},
+		},
+		{
+			name: "two fences",
+			in:   "a\n```\none\n```\nb\n```\ntwo\n```\nc",
+			want: []rcSegment{
+				{text: "a"},
+				{text: "```\none\n```", protected: true},
+				{text: "b"},
+				{text: "```\ntwo\n```", protected: true},
+				{text: "c"},
+			},
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := rcSegments(tt.in)
+			if len(got) != len(tt.want) {
+				t.Fatalf("got %d segments, want %d\ngot:  %#v\nwant: %#v", len(got), len(tt.want), got, tt.want)
+			}
+			for i := range got {
+				if got[i] != tt.want[i] {
+					t.Errorf("segment %d = %#v, want %#v", i, got[i], tt.want[i])
+				}
+			}
+			if joined := segJoin(got); joined != tt.in {
+				t.Errorf("reassembled = %q, want the input %q", joined, tt.in)
+			}
+		})
+	}
+}
+
+// Junk shaped exactly like what the removal rules delete must survive inside a
+// fence byte for byte — a README showing markdown is the whole reason the
+// segmentation exists.
+func TestCleanReadmeMarkdownProtectsFences(t *testing.T) {
+	const fence = "```md\n![Build](https://img.shields.io/badge.svg)\n<div align=\"center\">🚀 :rocket:</div>\n[docs](https://example.com/docs)\n<!-- a comment -->\n```"
+	got := cleanReadmeMarkdown("intro\n\n" + fence + "\n\nafter\n")
+	if !strings.Contains(got, fence) {
+		t.Errorf("fenced block was rewritten\n--- got ---\n%s\n--- want to contain ---\n%s", got, fence)
+	}
+}
+
+func TestCleanReadmeMarkdownProtectsInlineSpans(t *testing.T) {
+	tests := []struct {
+		name string
+		span string
+	}{
+		{"image", "`![Build](badge.svg)`"},
+		{"link", "`[docs](https://example.com)`"},
+		{"html tag", "`<div align=\"center\">`"},
+		{"html comment", "`<!-- hidden -->`"},
+		{"emoji", "`🚀`"},
+		{"shortcode", "`:rocket:`"},
+		{"double backtick span holding a backtick", "``a ` b``"},
+		{"reference image", "`![Build][badge]`"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := cleanReadmeMarkdown("text " + tt.span + " tail\n")
+			if !strings.Contains(got, tt.span) {
+				t.Errorf("inline span was rewritten\ngot:  %q\nwant to contain: %q", got, tt.span)
+			}
+		})
+	}
+}
+
+func TestRcMaskSpansRoundTrip(t *testing.T) {
+	tests := []struct {
+		name      string
+		in        string
+		wantSpans []string
+	}{
+		{"no backticks", "plain text", nil},
+		{"one span", "use `keepkit --version` now", []string{"`keepkit --version`"}},
+		{"two spans", "`a` and `b`", []string{"`a`", "`b`"}},
+		{"double delimiter", "``a ` b``", []string{"``a ` b``"}},
+		// A run with no closer of the same length is literal text, not a span.
+		{"unclosed", "a ` b", nil},
+		{"closer of a different length", "a ``b` c", nil},
+		// A code span lives inside one paragraph: a stray backtick must not
+		// pair with one in the next section and exempt everything between.
+		{"blank line stops the search", "stray ` here\n\nnext ` section", nil},
+		{"span across one line break", "a `b\nc` d", []string{"`b\nc`"}},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			masked, spans := rcMaskSpans(tt.in)
+			if len(spans) != len(tt.wantSpans) {
+				t.Fatalf("masked %d spans %q, want %d %q", len(spans), spans, len(tt.wantSpans), tt.wantSpans)
+			}
+			for i := range spans {
+				if spans[i] != tt.wantSpans[i] {
+					t.Errorf("span %d = %q, want %q", i, spans[i], tt.wantSpans[i])
+				}
+			}
+			if len(spans) > 0 && strings.Contains(masked, "`") {
+				t.Errorf("masked text still carries a backtick: %q", masked)
+			}
+			if got := rcUnmaskSpans(masked, spans); got != tt.in {
+				t.Errorf("round trip = %q, want %q", got, tt.in)
+			}
+		})
+	}
+}
+
+func TestCleanReadmeMarkdownImagesAndLinks(t *testing.T) {
+	tests := []struct {
+		name string
+		in   string
+		want string
+	}{
+		{
+			name: "inline badge header vanishes",
+			in:   "# Title\n\n![Build](https://img.shields.io/b.svg) ![License](https://img.shields.io/l.svg)\n\nIntro\n",
+			want: "# Title\n\nIntro\n",
+		},
+		{
+			name: "linked badge vanishes whole",
+			in:   "[![Build](https://b.svg)](https://ci.example.com)\n\nIntro\n",
+			want: "\nIntro\n",
+		},
+		{
+			name: "reference badge leaves no orphan definition",
+			in:   "![Build][badge]\n\nIntro\n\n[badge]: https://img.shields.io/b.svg\n",
+			want: "\nIntro\n",
+		},
+		{
+			name: "collapsed reference image",
+			in:   "![Build][]\n\nIntro\n\n[Build]: https://img.shields.io/b.svg\n",
+			want: "\nIntro\n",
+		},
+		{
+			name: "shortcut reference image",
+			in:   "![Build]\n\nIntro\n\n[Build]: https://img.shields.io/b.svg\n",
+			want: "\nIntro\n",
+		},
+		{
+			// The href is the noise; the sentence must close up around it with
+			// exactly one space, not two.
+			name: "inline link keeps its text",
+			in:   "See the [docs](https://example.com/docs) for more.\n",
+			want: "See the docs for more.\n",
+		},
+		{
+			name: "mid-sentence image leaves no double space",
+			in:   "Built ![badge](https://b.svg) with care.\n",
+			want: "Built with care.\n",
+		},
+		{
+			name: "reference link keeps its text",
+			in:   "See the [docs][d] for more.\n\n[d]: https://example.com\n",
+			want: "See the docs for more.\n",
+		},
+		{
+			name: "shortcut link keeps its text",
+			in:   "See [docs] for more.\n\n[docs]: https://example.com\n",
+			want: "See docs for more.\n",
+		},
+		{
+			// A table cell is where the style-level route left a footnote stub;
+			// unwrapping in the source leaves the cell reading as plain text.
+			name: "table link leaves no footnote stub",
+			in:   "| doc | link |\n|---|---|\n| manual | [manual](https://example.com/m) |\n",
+			want: "| doc | link |\n|---|---|\n| manual | manual |\n",
+		},
+		{
+			name: "heading link keeps its text",
+			in:   "## [Installation](#installation)\n",
+			want: "## Installation\n",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := cleanReadmeMarkdown(tt.in); got != tt.want {
+				t.Errorf("cleanReadmeMarkdown(%q)\n = %q\nwant %q", tt.in, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestCleanReadmeMarkdownHTML(t *testing.T) {
+	tests := []struct {
+		name string
+		in   string
+		want string
+	}{
+		{
+			name: "comment removed whole",
+			in:   "a\n\n<!-- hidden\nmultiline -->\n\nb\n",
+			want: "a\n\nb\n",
+		},
+		{
+			name: "script body removed",
+			in:   "a\n<script>\nvar x = 1;\n</script>\nb\n",
+			want: "a\n\nb\n",
+		},
+		{
+			name: "style body removed",
+			in:   "a\n<style>\n.x { color: red }\n</style>\nb\n",
+			want: "a\n\nb\n",
+		},
+		{
+			name: "picture element removed with its body",
+			in:   "<picture>\n  <source srcset=\"d.png\">\n  <img src=\"l.png\" alt=\"logo\">\n</picture>\n\n# Title\n",
+			want: "\n# Title\n",
+		},
+		{
+			name: "img tag removed",
+			in:   "<img src=\"logo.png\" alt=\"logo\">\n\n# Title\n",
+			want: "\n# Title\n",
+		},
+		{
+			name: "inline tag keeps its text",
+			in:   "Press <kbd>Ctrl</kbd>+<kbd>C</kbd> to quit.\n",
+			want: "Press Ctrl+C to quit.\n",
+		},
+		{
+			name: "details block keeps its content",
+			in:   "<details>\n<summary>More</summary>\n\nbody text\n\n</details>\n",
+			want: "\nMore\n\nbody text\n",
+		},
+		{
+			name: "centered html header collapses",
+			in:   "<h1 align=\"center\">keepkit</h1>\n<p align=\"center\">\n  <img src=\"a.svg\">\n  <img src=\"b.svg\">\n</p>\n\nIntro\n",
+			want: "keepkit\n\nIntro\n",
+		},
+		{
+			name: "br keeps the line",
+			in:   "first<br>\nsecond\n",
+			want: "first\nsecond\n",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := cleanReadmeMarkdown(tt.in); got != tt.want {
+				t.Errorf("cleanReadmeMarkdown(%q)\n = %q\nwant %q", tt.in, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestCleanReadmeMarkdownEmojiAndShortcodes(t *testing.T) {
+	tests := []struct {
+		name string
+		in   string
+		want string
+	}{
+		{
+			name: "heading keeps its words",
+			in:   "## 🚀 Getting Started\n",
+			want: "## Getting Started\n",
+		},
+		{
+			// A heading whose only content was a pictograph would render as a
+			// styled blank row.
+			name: "emoji-only heading is dropped",
+			in:   "# Title\n\n## 🚀\n\nbody\n",
+			want: "# Title\n\nbody\n",
+		},
+		{
+			name: "leading emoji leaves no indent",
+			in:   "🎉 Released today.\n",
+			want: "Released today.\n",
+		},
+		{
+			name: "list item keeps its marker",
+			in:   "- 🚀 fast\n- 🔒 safe\n",
+			want: "- fast\n- safe\n",
+		},
+		{
+			name: "keycap leaves no combining mark",
+			in:   "1️⃣ first step\n",
+			want: "1 first step\n",
+		},
+		{
+			name: "zwj sequence goes whole",
+			in:   "by 👩‍💻 the team\n",
+			want: "by the team\n",
+		},
+		{
+			name: "variation selector goes with its symbol untouched",
+			in:   "power ⚡️ mode\n",
+			want: "power ⚡ mode\n",
+		},
+		{
+			// A feature table's meaning lives in the ✅/❌ column.
+			name: "feature table marks are translated",
+			in:   "| feature | linux | windows |\n|---|---|---|\n| tabs | ✅ | ❌ |\n| tags | ☑ | ❌ |\n",
+			want: "| feature | linux | windows |\n|---|---|---|\n| tabs | ✓ | ✗ |\n| tags | ✓ | ✗ |\n",
+		},
+		{
+			name: "known shortcode removed",
+			in:   ":rocket: Fast by default.\n",
+			want: "Fast by default.\n",
+		},
+		{
+			name: "shortcode mid-sentence leaves no double space",
+			in:   "Fast :rocket: by default.\n",
+			want: "Fast by default.\n",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := cleanReadmeMarkdown(tt.in); got != tt.want {
+				t.Errorf("cleanReadmeMarkdown(%q)\n = %q\nwant %q", tt.in, got, tt.want)
+			}
+		})
+	}
+}
+
+// The dictionary lookup, not the ":name:" shape, is what makes a shortcode.
+func TestCleanReadmeMarkdownShortcodeNeedsAKnownName(t *testing.T) {
+	tests := []struct {
+		name    string
+		in      string
+		removed bool
+	}{
+		{"known name", ":rocket: go\n", true},
+		{"known name with plus", ":+1: agreed\n", true},
+		{"unknown name", ":foo: go\n", false},
+		{"clock reading", "at 12:30:45 today\n", false},
+		{"ratio", "a 3:4:5 triangle\n", false},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := cleanReadmeMarkdown(tt.in)
+			if changed := got != tt.in; changed != tt.removed {
+				t.Errorf("cleanReadmeMarkdown(%q) = %q; removed=%v, want removed=%v", tt.in, got, changed, tt.removed)
+			}
+		})
+	}
+}
+
+// What the removal rules must NOT touch. An autolink's URL is its content, and
+// prose angle brackets are not markup — the tag allowlist is what separates
+// them from <kbd>.
+func TestCleanReadmeMarkdownLeavesContentAlone(t *testing.T) {
+	unchanged := []struct {
+		name string
+		in   string
+	}{
+		{"autolink", "See <https://example.com/docs> here.\n"},
+		{"email autolink", "Mail <user@host.com> now.\n"},
+		{"bare url", "See https://example.com/docs here.\n"},
+		{"generic type", "Use Vec<String> for that.\n"},
+		{"less-than in prose", "true when a < b holds\n"},
+		{"unknown tag left as written", "the <Widget> component\n"},
+		{"time is not a shortcode", "at 12:30:45 today\n"},
+		{"unknown shortcode", "the :foo: marker\n"},
+		{"bmp symbols a terminal font carries", "✓ done ★ starred → next\n"},
+		{"task list brackets", "- [x] done\n- [ ] todo\n"},
+		{"undeclared shortcut label", "marked [experimental] for now\n"},
+		{"thematic break", "above\n\n- - -\n\nbelow\n"},
+		{"issue reference", "#123 fixed the crash\n"},
+		{"hard line break", "first  \nsecond\n"},
+		{"list indentation", "- one\n  - nested\n    - deeper\n"},
+	}
+	for _, tt := range unchanged {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := cleanReadmeMarkdown(tt.in); got != tt.in {
+				t.Errorf("cleanReadmeMarkdown(%q) = %q, want it unchanged", tt.in, got)
+			}
+		})
+	}
+}
+
+// The NUL sentinel cannot reach the pass in production (cleanTerminalOutput
+// drops every control character), and a direct caller must not be able to
+// smuggle a placeholder into the restore table either.
+func TestCleanReadmeMarkdownDropsSentinel(t *testing.T) {
+	got := cleanReadmeMarkdown("a\x000\x00b `code` c\n")
+	if strings.Contains(got, "\x00") {
+		t.Errorf("sentinel survived: %q", got)
+	}
+	if !strings.Contains(got, "`code`") {
+		t.Errorf("code span lost: %q", got)
+	}
+}
diff --git a/internal/model/textutil.go b/internal/model/textutil.go
index e75cb6e..59197c8 100644
--- a/internal/model/textutil.go
+++ b/internal/model/textutil.go
@@ -146,7 +146,10 @@ func wrapLine(line string, width int) []string {
 }
 
 // Inline markdown patterns, compiled once — mdInline runs per source line of
-// every release body the card renders.
+// every release body the card renders, and the README preprocessor
+// (readme_clean.go) reuses the image and link patterns: "an inline markdown
+// image" and "an inline markdown link" are one grammar fact, whatever the
+// consumer then does with the match.
 //
 // The link patterns keep their text class free of the closing delimiter
 // ([^\]]* / [^)]*), which is what makes them non-greedy without the RE2 cost

From 259b1e89d56282e041fc9fa97a59f0f95dd3b2ec Mon Sep 17 00:00:00 2001
From: stanlyzoolo <51911715+stanlyzoolo@users.noreply.github.com>
Date: Tue, 28 Jul 2026 12:45:00 +0300
Subject: [PATCH 3/5] feat(model): render the README in keepkit's own palette
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The standard glamour style is another app's design: an H1 on a bright
plate — the loudest thing on the screen — headings and links in colors
that appear nowhere else in keepkit, and a document margin eating 2-4
columns of an already narrow panel.

keepkitStyle clones the standard config and re-accents it from
internal/ui. Cloning rather than building from scratch is deliberate:
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 it clones hold
pointers that styles.DefaultStyles aliases, so every override assigns a
fresh pointer; writing through a cloned one would restyle glamour for
the whole process. TestKeepkitStyleLeavesGlobalsUntouched compares a
JSON snapshot rather than a saved struct, because a struct copy aliases
the very pointers that bug corrupts and would pass on it.

Only the peach heading accents and the structural fixes reach the light
variant: #E8E8E8 body text and #555555 rules are chosen against a dark
panel and would be unreadable on white, so there the standard light
colors stay. The theme is asserted at the struct level — tests have no
TTY, so the color profile is Ascii and glamour strips every color it
would emit.

With production no longer choosing a style *name*, readmeStyleName
degenerated to its test branch and is gone; renderReadme branches on
testReadmeStyle directly and the seam keeps its one job, forcing the
constructor to fail. The fallback now returns the preprocessed text, or
a failed render would be the one path still showing badge and href
noise.

render_test.go's "content that renders to nothing" gets its teeth back
along the way. It used to t.Skipf on a fixture that might or might not
render empty; a badge-only README now cleans down to whitespace and
renderReadme returns "" before glamour is built, so the placeholder path
is a guarantee and the test fails instead of skipping.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 internal/model/readme.go            |  55 +++----
 internal/model/readme_style.go      |  76 ++++++++++
 internal/model/readme_style_test.go | 213 ++++++++++++++++++++++++++++
 internal/model/readme_test.go       |  40 +++---
 internal/model/render_test.go       |  12 +-
 5 files changed, 347 insertions(+), 49 deletions(-)
 create mode 100644 internal/model/readme_style.go
 create mode 100644 internal/model/readme_style_test.go

diff --git a/internal/model/readme.go b/internal/model/readme.go
index 47c6389..f26701e 100644
--- a/internal/model/readme.go
+++ b/internal/model/readme.go
@@ -4,7 +4,6 @@ import (
 	"strings"
 
 	"github.com/charmbracelet/glamour"
-	"github.com/charmbracelet/glamour/styles"
 	"github.com/charmbracelet/lipgloss"
 )
 
@@ -13,47 +12,49 @@ import (
 // instead of a per-character column.
 const readmeMinWrap = 20
 
-// testReadmeStyle overrides the resolved glamour style name in tests (the
-// testConfigDir/testCacheDir seam idiom). An unknown name makes
-// glamour.NewTermRenderer fail, which is how the fallback path is exercised.
+// testReadmeStyle routes the renderer through a named standard style instead of
+// keepkitStyle (the testConfigDir/testCacheDir seam idiom). An unknown name
+// makes glamour.NewTermRenderer fail, which is how the fallback path is
+// exercised.
 var testReadmeStyle string
 
-// readmeStyleName resolves the fixed glamour style. Deliberately NOT
-// glamour.WithAutoStyle(): auto-style probes the live terminal with a termenv
-// OSC background query that reads stdin, which races Bubble Tea's input reader
-// and breaks the project's terminal-sandboxing policy. The caller resolves
-// dark/light once at model construction (lipgloss caches HasDarkBackground)
-// and passes the answer down.
-func readmeStyleName(dark bool) string {
-	if testReadmeStyle != "" {
-		return testReadmeStyle
-	}
-	if dark {
-		return styles.DarkStyle
-	}
-	return styles.LightStyle
-}
-
-// renderReadme turns raw README markdown into the ANSI text panel [3] shows.
-// The input is sanitized with cleanTerminalOutput first — a README is remote
-// content that lands in a viewport verbatim, so it gets the same treatment as
-// a probe capture. Any glamour failure falls back to the sanitized plain text:
-// an unstyled README beats an empty panel.
+// 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
+// same treatment as a probe capture — and then preprocessed by
+// cleanReadmeMarkdown, which strips the badges, hrefs, HTML and emoji a TTY
+// cannot show or does not need. What survives is rendered with keepkitStyle,
+// the palette-matched theme.
+//
+// The style is resolved from the dark/light answer the caller already has, and
+// deliberately NOT by glamour.WithAutoStyle(): auto-style probes the live
+// terminal with a termenv OSC background query that reads stdin, which races
+// Bubble Tea's input reader and breaks the project's terminal-sandboxing
+// policy. Any glamour failure falls back to the preprocessed plain text: an
+// unstyled README beats an empty panel.
 func renderReadme(raw string, width int, dark bool) string {
-	clean := cleanTerminalOutput(raw)
+	clean := cleanReadmeMarkdown(cleanTerminalOutput(raw))
 	if strings.TrimSpace(clean) == "" {
 		return ""
 	}
 	if width < readmeMinWrap {
 		width = readmeMinWrap
 	}
+	style := glamour.WithStyles(keepkitStyle(dark))
+	if testReadmeStyle != "" {
+		style = glamour.WithStandardStyle(testReadmeStyle)
+	}
 	r, err := glamour.NewTermRenderer(
-		glamour.WithStandardStyle(readmeStyleName(dark)),
+		style,
 		glamour.WithWordWrap(width),
 		// glamour defaults to TrueColor regardless of the environment; follow
 		// lipgloss instead so a degraded profile (NO_COLOR, dumb term) yields
 		// plain text like every other panel.
 		glamour.WithColorProfile(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.
+		glamour.WithInlineTableLinks(true),
 	)
 	if err != nil {
 		return clean
diff --git a/internal/model/readme_style.go b/internal/model/readme_style.go
new file mode 100644
index 0000000..bd3c19c
--- /dev/null
+++ b/internal/model/readme_style.go
@@ -0,0 +1,76 @@
+package model
+
+import (
+	"github.com/charmbracelet/glamour/ansi"
+	"github.com/charmbracelet/glamour/styles"
+
+	"github.com/stanlyzoolo/keepkit/internal/ui"
+)
+
+// ptrTo returns a pointer to v. glamour's StyleConfig is pointer-heavy, the
+// package globals keepkitStyle clones share those pointers, and
+// styles.DefaultStyles aliases the same structs — so every override must assign
+// a FRESH pointer. Writing through a cloned one (*cfg.H1.Color = …) would
+// restyle glamour for the whole process.
+func ptrTo[T any](v T) *T { return &v }
+
+// keepkitStyle is panel [3]'s glamour theme: the standard config for the
+// terminal's background, with the accents moved onto keepkit's palette 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 peach heading accents and the structural
+// fixes: the rest of the palette (#E8E8E8 text, #555555 rules) is chosen
+// against a dark panel and would be unreadable on white, so there the standard
+// light colors stay.
+func keepkitStyle(dark bool) ansi.StyleConfig {
+	cfg := styles.LightStyleConfig
+	if dark {
+		cfg = styles.DarkStyleConfig
+	}
+
+	// glamour's own margin eats 2-4 columns of an already narrow panel, and the
+	// panel frame is the breathing room.
+	cfg.Document.Margin = ptrTo[uint](0)
+
+	// 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.
+	// Peach and bold carries the same weight; the padding spaces go with the
+	// plate, since without a background they only read as a stray indent.
+	cfg.H1.Color = ptrTo(string(ui.ColorPrimary))
+	cfg.H1.BackgroundColor = nil
+	cfg.H1.Bold = ptrTo(true)
+	cfg.H1.Prefix = ""
+	cfg.H1.Suffix = ""
+
+	// H2 takes the same color the brief card heads its sections with.
+	cfg.H2.Color = ptrTo(string(ui.ColorCategory))
+	cfg.H2.Bold = ptrTo(true)
+
+	if !dark {
+		return cfg
+	}
+
+	// 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(ui.ColorText))
+	cfg.Heading.Bold = ptrTo(true)
+	cfg.H6.Color = ptrTo(string(ui.ColorText))
+	cfg.H6.Bold = ptrTo(true)
+
+	// What is still a link after the preprocessor is an autolink or a bare URL,
+	// whose text IS the URL — the same blue the help panel gives its meta
+	// tokens.
+	cfg.LinkText.Color = ptrTo(string(ui.ColorMeta))
+
+	// Rules and quote bars in the panel-frame grays, so they read as structure
+	// rather than as content.
+	cfg.HorizontalRule.Color = ptrTo(string(ui.ColorBorder))
+	cfg.BlockQuote.Color = ptrTo(string(ui.ColorDim))
+
+	return cfg
+}
diff --git a/internal/model/readme_style_test.go b/internal/model/readme_style_test.go
new file mode 100644
index 0000000..94185d2
--- /dev/null
+++ b/internal/model/readme_style_test.go
@@ -0,0 +1,213 @@
+package model
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/charmbracelet/glamour/styles"
+
+	"github.com/stanlyzoolo/keepkit/internal/ui"
+)
+
+// deref reports a *string style field's value, naming the field when it is nil
+// so a failure says which override went missing.
+func deref(t *testing.T, field string, p *string) string {
+	t.Helper()
+	if p == nil {
+		t.Fatalf("%s is nil, want a color", field)
+	}
+	return *p
+}
+
+// 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.
+func TestKeepkitStyleOverrides(t *testing.T) {
+	for _, dark := range []bool{true, false} {
+		name := "light"
+		if dark {
+			name = "dark"
+		}
+		t.Run(name, func(t *testing.T) {
+			cfg := keepkitStyle(dark)
+
+			if got := deref(t, "H1.Color", cfg.H1.Color); got != string(ui.ColorPrimary) {
+				t.Errorf("H1.Color = %q, want %q", got, string(ui.ColorPrimary))
+			}
+			// 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.ColorCategory) {
+				t.Errorf("H2.Color = %q, want %q", got, string(ui.ColorCategory))
+			}
+			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)
+			}
+			// Cloned, not built from scratch: a field the theme never mentions
+			// must still carry the standard config's value.
+			if cfg.List.LevelIndent == 0 {
+				t.Error("List.LevelIndent = 0 — the standard config was not inherited")
+			}
+			if cfg.CodeBlock.Chroma == nil {
+				t.Error("CodeBlock.Chroma is nil — the standard config was not inherited")
+			}
+		})
+	}
+}
+
+// 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(true), keepkitStyle(false)
+
+	if got := deref(t, "dark Heading.Color", dark.Heading.Color); got != string(ui.ColorText) {
+		t.Errorf("dark Heading.Color = %q, want %q", got, string(ui.ColorText))
+	}
+	if got := deref(t, "dark H6.Color", dark.H6.Color); got != string(ui.ColorText) {
+		t.Errorf("dark H6.Color = %q, want %q", got, string(ui.ColorText))
+	}
+	if got := deref(t, "dark LinkText.Color", dark.LinkText.Color); got != string(ui.ColorMeta) {
+		t.Errorf("dark LinkText.Color = %q, want %q", got, string(ui.ColorMeta))
+	}
+	if got := deref(t, "dark HorizontalRule.Color", dark.HorizontalRule.Color); got != string(ui.ColorBorder) {
+		t.Errorf("dark HorizontalRule.Color = %q, want %q", got, string(ui.ColorBorder))
+	}
+	if got := deref(t, "dark BlockQuote.Color", dark.BlockQuote.Color); got != string(ui.ColorDim) {
+		t.Errorf("dark BlockQuote.Color = %q, want %q", got, string(ui.ColorDim))
+	}
+
+	if got := deref(t, "light Heading.Color", light.Heading.Color); got == string(ui.ColorText) {
+		t.Errorf("light Heading.Color = %q — the dark body tint is unreadable on white", got)
+	}
+	if got := deref(t, "light Document.Color", light.Document.Color); got == string(ui.ColorText) {
+		t.Errorf("light Document.Color = %q — the dark body tint is unreadable on white", got)
+	}
+}
+
+// keepkitStyle clones structs whose pointer fields alias the package globals
+// (styles.DefaultStyles hands the very same ones out), so an override that
+// wrote THROUGH a cloned pointer would restyle glamour for the whole process.
+// The snapshot is JSON so the comparison follows every pointer.
+func TestKeepkitStyleLeavesGlobalsUntouched(t *testing.T) {
+	snapshot := func(t *testing.T) (string, string) {
+		t.Helper()
+		d, err := json.Marshal(styles.DarkStyleConfig)
+		if err != nil {
+			t.Fatalf("marshal dark: %v", err)
+		}
+		l, err := json.Marshal(styles.LightStyleConfig)
+		if err != nil {
+			t.Fatalf("marshal light: %v", err)
+		}
+		return string(d), string(l)
+	}
+
+	wantDark, wantLight := snapshot(t)
+	_, _ = keepkitStyle(true), keepkitStyle(false)
+	gotDark, gotLight := snapshot(t)
+
+	if gotDark != wantDark {
+		t.Errorf("styles.DarkStyleConfig was mutated\n got: %s\nwant: %s", gotDark, wantDark)
+	}
+	if gotLight != wantLight {
+		t.Errorf("styles.LightStyleConfig was mutated\n got: %s\nwant: %s", gotLight, wantLight)
+	}
+}
+
+// What the whole pipeline does to a README, read off the visible text. Colors
+// are absent here (no TTY), which is exactly why these assertions are about
+// content, not styling.
+func TestRenderReadmeHouseStyle(t *testing.T) {
+	tests := []struct {
+		name    string
+		raw     string
+		want    []string
+		absent  []string
+		noEmpty bool
+	}{
+		{
+			name:   "link keeps its text and drops the href",
+			raw:    "See the [docs](https://example.com/docs) for more.\n",
+			want:   []string{"See the docs for more."},
+			absent: []string{"example.com"},
+		},
+		{
+			name:   "table link leaves no footnote stub",
+			raw:    "| topic | where |\n|---|---|\n| usage | [manual](https://example.com/m) |\n",
+			want:   []string{"manual"},
+			absent: []string{"example.com"},
+		},
+		{
+			// The URL is the content of an autolink, so it stays visible.
+			name: "autolink survives",
+			raw:  "Read <https://example.com/docs> first.\n",
+			want: []string{"https://example.com/docs"},
+		},
+		{
+			name: "bare url survives",
+			raw:  "Read https://example.com/docs first.\n",
+			want: []string{"https://example.com/docs"},
+		},
+		{
+			name:   "badge header vanishes, prose survives",
+			raw:    "# keepkit\n\n[![Build](https://b.svg)](https://ci.example.com) ![License](https://l.svg)\n\nA tracker for CLI tools.\n",
+			want:   []string{"keepkit", "A tracker for CLI tools."},
+			absent: []string{"b.svg", "l.svg", "ci.example.com", "Image:"},
+		},
+		{
+			name:   "emoji heading keeps its words",
+			raw:    "## 🚀 Getting Started\n\nRun it.\n",
+			want:   []string{"Getting Started", "Run it."},
+			absent: []string{"🚀"},
+		},
+		{
+			name: "fenced sample survives whole",
+			raw:  "# T\n\n```md\n![Build](https://b.svg)\n```\n",
+			want: []string{"![Build](https://b.svg)"},
+		},
+	}
+	for _, tt := range tests {
+		for _, dark := range []bool{true, false} {
+			name := tt.name + "/light"
+			if dark {
+				name = tt.name + "/dark"
+			}
+			t.Run(name, func(t *testing.T) {
+				plain := stripANSI(renderReadme(tt.raw, 100, dark))
+				for _, w := range tt.want {
+					if !strings.Contains(plain, w) {
+						t.Errorf("missing %q\n--- rendered ---\n%s", w, plain)
+					}
+				}
+				for _, a := range tt.absent {
+					if strings.Contains(plain, a) {
+						t.Errorf("unexpected %q\n--- rendered ---\n%s", a, plain)
+					}
+				}
+				// The double-space check belongs on the preprocessed source,
+				// where a removal artifact would live — glamour pads table
+				// cells with runs of spaces of its own, which is layout, not
+				// residue.
+				for _, line := range strings.Split(cleanReadmeMarkdown(cleanTerminalOutput(tt.raw)), "\n") {
+					if strings.Contains(strings.TrimSpace(line), "  ") {
+						t.Errorf("removal left a double space: %q", line)
+					}
+				}
+			})
+		}
+	}
+}
+
+// A README that is nothing but badges and HTML cleans down to nothing, and an
+// empty render is what makes readmeContent fall through to the friendly
+// "No README for <name>. Press [h] for --help." placeholder.
+func TestRenderReadmeBadgeOnlyIsEmpty(t *testing.T) {
+	raw := "<p align=\"center\">\n  <img src=\"logo.png\">\n</p>\n\n[![Build](https://b.svg)](https://ci.example.com)\n![License](https://l.svg)\n\n<!-- nothing to see -->\n\n[badge]: https://b.svg\n"
+	for _, dark := range []bool{true, false} {
+		if got := renderReadme(raw, 60, dark); got != "" {
+			t.Errorf("dark=%v: renderReadme = %q, want empty", dark, got)
+		}
+	}
+}
diff --git a/internal/model/readme_test.go b/internal/model/readme_test.go
index 0b229c6..9dca1cd 100644
--- a/internal/model/readme_test.go
+++ b/internal/model/readme_test.go
@@ -74,25 +74,31 @@ func TestRenderReadmeStripsControlChars(t *testing.T) {
 }
 
 // An unrenderable style makes glamour.NewTermRenderer fail; the panel must get
-// the sanitized plain text rather than nothing.
+// the preprocessed plain text rather than nothing.
 func TestRenderReadmeFallsBackToPlainText(t *testing.T) {
-	testReadmeStyle = "no-such-style"
-	t.Cleanup(func() { testReadmeStyle = "" })
-
-	raw := "# Title\n\nbody\x07 text\n"
-	got := renderReadme(raw, 60, true)
-	want := cleanTerminalOutput(raw)
-	if got != want {
-		t.Errorf("fallback = %q, want the sanitized input %q", got, want)
+	tests := []struct {
+		name string
+		raw  string
+	}{
+		{"sanitizer only", "# Title\n\nbody\x07 text\n"},
+		// The fallback must carry the preprocessing too, or a failed render
+		// would be the one path that still shows badge and href noise.
+		{"preprocessed", "# Title\n\n![Build](https://b.svg)\n\nSee the [docs](https://example.com) 🚀\n"},
 	}
-}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			testReadmeStyle = "no-such-style"
+			t.Cleanup(func() { testReadmeStyle = "" })
 
-func TestRenderReadmeStyleFollowsBackground(t *testing.T) {
-	if got := readmeStyleName(true); got != "dark" {
-		t.Errorf("readmeStyleName(true) = %q, want %q", got, "dark")
-	}
-	if got := readmeStyleName(false); got != "light" {
-		t.Errorf("readmeStyleName(false) = %q, want %q", got, "light")
+			got := renderReadme(tt.raw, 60, true)
+			want := cleanReadmeMarkdown(cleanTerminalOutput(tt.raw))
+			if got != want {
+				t.Errorf("fallback = %q, want the preprocessed input %q", got, want)
+			}
+			if got == tt.raw {
+				t.Errorf("fallback returned the raw input unchanged: %q", got)
+			}
+		})
 	}
 }
 
@@ -144,7 +150,7 @@ func TestReadmeRenderCacheInvalidation(t *testing.T) {
 			if got == first {
 				t.Fatalf("%s: cache was reused, want a re-render", tt.name)
 			}
-			if want := cleanTerminalOutput(tt.raw); got != want {
+			if want := cleanReadmeMarkdown(cleanTerminalOutput(tt.raw)); got != want {
 				t.Errorf("%s: re-render = %q, want the fallback %q", tt.name, got, want)
 			}
 		})
diff --git a/internal/model/render_test.go b/internal/model/render_test.go
index b363573..129c353 100644
--- a/internal/model/render_test.go
+++ b/internal/model/render_test.go
@@ -3585,13 +3585,15 @@ func TestReadmePlaceholders(t *testing.T) {
 		}
 	})
 	t.Run("content that renders to nothing", func(t *testing.T) {
-		// glamour renders a README carrying no visible markdown to an empty
-		// string; returning that as real content would paint a blank panel with
-		// no way out, so it must fall through to a placeholder.
+		// A README that is nothing but badges and HTML cleans down to nothing
+		// (cleanReadmeMarkdown removes every one of these), and returning an
+		// empty render as real content would paint a blank panel with no way
+		// out — so it must fall through to a placeholder.
 		m := readmePanelModel(t, repo)
-		m = mustModel(m.Update(readmeMsg{toolName: "rg", content: "<!-- badges only -->\n"}))
+		const badgesOnly = "<!-- badges only -->\n\n<p align=\"center\">\n  <img src=\"logo.png\">\n</p>\n\n[![Build](https://b.svg)](https://ci.example.com)\n"
+		m = mustModel(m.Update(readmeMsg{toolName: "rg", content: badgesOnly}))
 		if m.helpBase != "" {
-			t.Skipf("glamour rendered %q to non-empty output; the empty-render path needs another fixture", "<!-- -->")
+			t.Fatalf("badge-only README rendered to %q, want the empty-render path", m.helpBase)
 		}
 		got := stripANSI(m.renderHelpContent())
 		if strings.TrimSpace(got) == "" {

From b249dae0b17b0de62952b6d58a0af0013d0dbe8f Mon Sep 17 00:00:00 2001
From: stanlyzoolo <51911715+stanlyzoolo@users.noreply.github.com>
Date: Tue, 28 Jul 2026 12:45:08 +0300
Subject: [PATCH 4/5] docs: describe the README house-style pipeline
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CLAUDE.md and ARCHITECTURE.md: the two new model files, and the panel
[3] rendering clause, which still described a fixed WithStandardStyle
over merely sanitized text. The empty-render placeholder note changed
with it — that case used to be a curiosity worth one sentence and is now
a guarantee for any badge-only README.

README.md: the two user-facing panel descriptions say a README is
cleaned up before rendering, and goldmark-emoji joins the Stack, which
is supposed to match go.mod's direct deps.

Plan moved to docs/plans/completed/ with the deviations recorded — the
tag allowlist, span masking, the per-line tidy-up landing a task early,
and the shortcut-reference rule. One thing found while checking a real
README is left out on purpose: a centered <h1 align="center">name</h1>
keeps its text but loses its heading status, because the tag strip is
text-preserving by design. Turning <h1>-<h6> into markdown headings is a
rule nobody approved.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 ARCHITECTURE.md                               |  27 +++-
 CLAUDE.md                                     |  10 +-
 README.md                                     |  12 +-
 .../completed/20260728-readme-house-style.md  | 149 +++++++++++++-----
 4 files changed, 152 insertions(+), 46 deletions(-)

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 1503fad..6637a53 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -71,7 +71,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` — markdown → ANSI via glamour, with a single-entry render cache |
+| `readme.go` | `renderReadme` — panel `[3]`'s pipeline: sanitize → preprocess → glamour, with a single-entry render cache |
+| `readme_clean.go` | `cleanReadmeMarkdown` — 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 |
+| `readme_style.go` | `keepkitStyle(dark)` — panel `[3]`'s glamour theme: the standard config cloned, its accents replaced from `internal/ui`'s palette |
 | `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` |
 
@@ -131,8 +133,22 @@ the `keepkit` screen. The protection has two layers:
 A library that probes the terminal counts as the same hazard: `glamour.WithAutoStyle()`
 is never used, because its termenv OSC background query reads stdin and races Bubble
 Tea's input reader. Dark/light is resolved once at construction via lipgloss's cached
-`HasDarkBackground()` (`m.darkBG`) and passed to glamour as a fixed `WithStandardStyle`.
-The README body itself is bounded (`readmeMaxBytes`) and sanitized before rendering.
+`HasDarkBackground()` (`m.darkBG`) and picks one of `keepkitStyle`'s two variants, which
+glamour receives as a fixed `WithStyles`. The README body itself is bounded
+(`readmeMaxBytes`) and sanitized before rendering.
+
+Between the sanitizer and glamour sits `cleanReadmeMarkdown`, the house-style
+preprocessor: a README is written for a browser, so badges, logos, `<picture>` wrappers,
+hrefs nobody can click in a TTY and emoji a terminal font renders as tofu are removed
+before rendering. It rests on one rule — **code is never rewritten** — because a fenced
+block and an inline span are exactly how a README *shows* the markup being deleted, so
+fences are segmented out (an unterminated one protects to EOF, since the
+`readmeMaxBytes` cut can land mid-fence) and inline spans are masked for the duration.
+Autolinks and bare URLs survive: there the URL *is* the content. `keepkitStyle` then
+clones the standard config rather than building one, so a glamour upgrade that adds a
+field cannot leave the panel with a hole in it — and because the package globals it
+clones hold pointers that `styles.DefaultStyles` aliases, every override assigns a fresh
+pointer instead of writing through a shared one.
 
 ## TUI state machine
 
@@ -429,8 +445,9 @@ packages fails if the isolation is ever dropped.
 Per-test setup still uses the internal seams: `testConfigDir`, `testCacheDir`,
 `testTokenDir`, `testAPIBase`, `testBrewPrefix` (one copy in `version`, a second in
 `updater` — each private to its package), `updater`'s `testHomeDir`, and
-`model`'s `testReadmeStyle` (forces the glamour construction failure so the
-plain-text fallback is covered). `testAPIBase` is private to `version`, so a `model`
+`model`'s `testReadmeStyle` (routes the renderer through a named standard style
+instead of `keepkitStyle`; an unknown name forces the glamour construction failure,
+which is how the plain-text fallback is covered). `testAPIBase` is private to `version`, so a `model`
 test cannot redirect a fetch at an httptest server — a network command is executed
 there only when the cache can answer it (`seedSelfReleaseCache` for the self-check);
 otherwise `Init` batches are asserted by length, never run. The races are real (mutexes
diff --git a/CLAUDE.md b/CLAUDE.md
index 72ba48a..b5d32a2 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -47,7 +47,9 @@ The `model` package is split by responsibility (one package, several files):
 | `mode.go` | `inputMode` enum + per-mode key handlers (`updateNoteEdit`, `updateTagsEdit`, `updateTrackInput`, `updateUntrackConfirm`, `updateRenameInput`, `updateRunInput`, `updateAPIStatus`, `updateConfirmUpdate`, `updateHotkeys`) and the pure `trackTool`/`renameTool` |
 | `commands.go` | Every `tea.Cmd` constructor (`fetchInstalledCmd`, `remoteCmd`, `fetchRateCmd`, `selfCheckCmd`, `changelogCmd`, `fetchHelpCmd`, `readmeCmd`/`fetchReadmeCmd`/`refreshReadmeCmd`, `validateTokenCmd`, `detectUpdateCmd(t, self)` (one command for `[u]` and `[U]` — the flag only tags the message), `startUpdateCmd`, `waitForChunkCmd`, `startLaunchCmd`, `execToolCmd` + the pure per-GOOS `shellCommand`) + fetch predicates (`needsInstalled`, `needsRemote`, `needsReadme`, `refreshSelectedCmd`, `autoFetchCmdsForSelected`) |
 | `render.go` | `View`, panel/card/status-bar/gauge/overlay renderers, scrollbar, mouse handling |
-| `readme.go` | `renderReadme` (glamour) + the single-entry `readmeRenderCache`; `readmeStyleName`/`testReadmeStyle` seam |
+| `readme.go` | `renderReadme` — panel `[3]`'s pipeline (sanitize → preprocess → glamour) + the single-entry `readmeRenderCache`; `testReadmeStyle` seam |
+| `readme_clean.go` | `cleanReadmeMarkdown` — the pure README preprocessor: fenced-block/inline-span segmentation first, then the image/link/HTML/emoji/shortcode removal rules on what is left |
+| `readme_style.go` | `keepkitStyle(dark)` — panel `[3]`'s glamour theme, cloned from the standard config and re-accented from `internal/ui`'s palette |
 | `textutil.go` | Pure text/format helpers (`wrapText`/`wrapLine`, `stripANSI`, `colorizeHelp`, `parseHelpEntries`, `markdownToLines`/`mdInline` — the card's release-notes converter, `findMatches`, `formatStars`, `renderLangBar`, …) |
 | `browser.go` | `openURLCmd` + per-`GOOS` `browserCommand` |
 
@@ -109,7 +111,11 @@ The model is a three-panel layout with focus cycling via `→/←` between `focu
   - **Completion**: the self branch of `updateDoneMsg` runs **before** the `toolByName` early return — for an untracked keepkit that lookup gives `!ok`, the message would be dropped, and `[U] restart` would never appear. The discriminator is **`m.isSelfUpdate(msg.tool)`**: an update of keepkit is a self-update whichever key started it, so on a release build `[u]` on a tracked `keepkit` row ends here too and gets the same restart offer (it used to take the tool path, which left the banner announcing an update the card already showed as installed, with `[U] restart` reachable only by running the whole update again — `TestKeepkitUpdateSelfHandlingGatedOnBuild`'s release row), while on a dev build that same keypress falls through to the plain tool path below (`TestKeepkitUpdateSelfHandlingGatedOnBuild`) — the name alone as the discriminator was what let a build with the feature off announce `keepkit updated — [U] restart` and then re-exec its own working copy. Success → `selfState = selfUpdated` + `statusMsg "updated keepkit"`, plus `fetchInstalledCmd` **only when tracked** (nothing else has a card or a `↑` to refresh); note the success write is legitimate even from `selfNone` — a rate-limited startup check plus `[u]` on a tracked row is exactly that, and the new binary really is on disk. Failure → `statusMsg "update failed — see [3]"` + the shared `recordUpdateFailure` and **no `selfState` write at all**: the banner reappears by itself once `updatingFor` clears, so every write here could only walk a state back — over an `[X]` folded mid-update (a deliberate "not now"), over a pending `[U] restart` from an earlier successful update, or over `selfNone`, where there is no `selfLatest` and the forced `selfOffered` rendered `keepkit  available` with a hole in it that no later `selfCheckMsg` could fill (that handler writes only from `selfNone`). `TestSelfUpdateDoneFailureKeepsPriorState` pins all five prior states. `updatingFor` is cleared unconditionally in both.
   - **Restart**: `[U]` at `selfUpdated`/`selfUpdatedLater` sets `m.restartRequested` and returns `tea.Quit` — `selfState` is deliberately not moved (after `tea.Quit` nothing renders, and a failed exec exits anyway, so a sixth enum member would be dead). `RestartRequested()` is the exported accessor `main` reads off the model `p.Run()` returns, **strictly after** it returned: Bubble Tea has restored the terminal by then, whereas exec'ing from inside `Update` would hand the new process an alt screen it never opened. `restart_unix.go`'s `restartSelf()` delegates to the seam-injected `restartSelfWith(resolve, execve, out)` (the `exists`/`lookPath` idiom again, so both failure paths are testable) = `selfPath()` + `syscall.Exec(path, os.Args, os.Environ())` — same pid, same argv, same env, so the tab/tmux pane survives. Only a failure logs `logx.Errorf("restart self: …")` (a genuine anomaly) and prints the shared `restartHint` (`keepkit updated — run keepkit again`) to **stdout** at exit code 0 — the update did succeed, so this is an instruction, not diagnostics; a successful exec never comes back, so the whole tail is unreachable on success and says nothing. `restart_windows.go` prints the same hint and nothing else: there is no image-replacing exec, and spawning a child from a process about to exit hands the new keepkit a console the old one still owns. It logs nothing — planned degradation, not a malfunction.
   - **Path resolution** (`restart_unix.go`, pure core + thin wrapper): `resolveSelfPath(executable, exists, lookPath, argv0)` mirrors how a shell resolves what the user typed instead of trusting `os.Executable`. An argv0 carrying a path separator (`strings.Contains(argv0, "/")` — the file is `//go:build !windows`, so `/` is the only separator that can reach it; the backslash and the `.exe`-trimming in `sameProgram` that the core carried while it lived in the untagged `restart.go` were dead branches under the tag and are gone, along with the two test rows that exercised them) is already a path the user pointed at and wins when it `exists`, with no `lookPath` call — a same-named binary earlier in `PATH` must not hijack `./keepkit`. A **bare** argv0 goes through `lookPath` **first**, and this order is load-bearing on **Linux**: there `os.Executable()` reads `/proc/self/exe` symlink-*resolved*, so after a keg-style upgrade it can still name the live *old* binary, and exec'ing that would loop the feature (restart → the same banner → restart). Two things disqualify a `PATH` hit: `("", nil)` counts as a miss (an empty string must never reach `syscall.Exec`), and so does a hit whose `filepath.Base` differs from `executable`'s (`sameProgram`) — argv0 comes from the *parent* process, so a wrapper using `exec -a` or a shell that rewrote `argv[0]` would otherwise make the restart exec an unrelated program with keepkit's argv and environment. `executable` is the fallback for both branches and only when it `exists`; nothing left → error → `restartHint`, no exec. **Known asymmetry**: `updater.Detect` resolves the update *target* from `exec.LookPath(t.Name)`, so a release binary launched by path (`./keepkit`) while another keepkit sits on `PATH` updates the `PATH` one and then re-execs the by-path (un-updated) binary — the banner comes back. Fixing it means changing where `Detect` starts, which is shared with `[u]` for every tool and out of this feature's scope; README lists it as a caveat.
-- **Panel `[3]` modes (`helpMode`)**: three sources — `helpModeReadme = 2` (the **default** set in `New()`), `helpModeHelp = 0`, `helpModeMan = 1`. `helpMode` is a sticky global field, not per tool: `[r]` (only in `focusHelp` — `case "r"` branches on focus: `focusTools` rename, `focusBrief` refresh), `[h]` and `[m]` (both fire from `focusBrief || focusHelp`) switch it. All three go through the shared **`switchHelpMode(mode)`** (model.go), which sets the mode, dismisses a *completed* update log (a tool's via `updateLogFor`, keepkit's own via `dismissSelfLog()` — the latter ahead of the `selectedMeta` guard), calls `setHelpContent()` + `GotoTop()` and returns the fetch command for the mode's missing source (README via `needsReadme`, `--help`/`man` via the `helpCache` miss + `helpLoadingFor`); focus stays with the caller, because `[h]`/`[m]` also fire from `[2]` and move it while `[r]` is `focusHelp`-only. A **live** update log keeps `[3]` in every path (the log branch sits ahead of the readme branch *and* the `No tool selected` guard in `renderHelpContent`, `setHelpContent` gates on `showsUpdateLog()`, and the readme case in `autoFetchCmdsForSelected` sits after that same case). **`m.helpCache` is a `map[string][2]string` whose values are indexed by `helpMode`, so mode 2 panics on every index site** — README content lives in `m.readmeData` instead and each index site (`rawHelpText`, `renderHelpContent`, `autoFetchCmdsForSelected`) carries a readme early-return/branch *before* the array read; `helpOutputMsg` indexes `msg.mode`, which only ever carries help/man. Rendering: `renderReadme` (readme.go) sanitizes with `cleanTerminalOutput`, then runs glamour with a **fixed** `WithStandardStyle("dark"|"light")` — resolved once at construction into `m.darkBG` via lipgloss's cached `HasDarkBackground()`, because `glamour.WithAutoStyle()` probes the terminal with a termenv OSC query that reads stdin and races Bubble Tea's input reader — plus `WithWordWrap(helpWrapWidth())` and `WithColorProfile(lipgloss.ColorProfile())` (glamour hardcodes TrueColor and would ignore `NO_COLOR`/dumb terms); a glamour failure falls back to the sanitized plain text, never an empty panel. The result is memoized in the single-entry `readmeRenderCache` keyed by `(name, raw, width, dark)` — `setHelpContent` runs on every selection move and width resize and must not re-parse a large README each time. `parseHelpEntries`/`colorizeHelp` are **not** run in readme mode (glamour output is already ANSI): `helpEntries` stays empty so `j`/`k` are plain scroll, and `/` (help search) is a no-op — guarded at the shared `focusBrief || focusHelp` entry point, so the `[1]` tool-list search is unaffected; the `focusHelp` status bar drops the `[/] search` hint in readme mode rather than advertising a dead key. Placeholders are tool-named (`readmeContent` in render.go): no GitHub ref → `No repo for <name>. Press [h] for --help.`, in-flight → `Loading...`, `ErrNoReadme` → `No README in <owner/repo>. Press [h] for --help.`, `ErrRateLimited` → `rate limited — press [L]`, and a generic fallback `No README for <name>. Press [h] for --help.` for everything else — a network/5xx failure **and** the case where content exists but glamour rendered it to nothing (a badges/HTML-comment-only README). That last one is why the "real content" test is `data.content != "" && m.helpBase != ""`: returning an empty render as content paints a blank panel with no way out.
+- **Panel `[3]` modes (`helpMode`)**: three sources — `helpModeReadme = 2` (the **default** set in `New()`), `helpModeHelp = 0`, `helpModeMan = 1`. `helpMode` is a sticky global field, not per tool: `[r]` (only in `focusHelp` — `case "r"` branches on focus: `focusTools` rename, `focusBrief` refresh), `[h]` and `[m]` (both fire from `focusBrief || focusHelp`) switch it. All three go through the shared **`switchHelpMode(mode)`** (model.go), which sets the mode, dismisses a *completed* update log (a tool's via `updateLogFor`, keepkit's own via `dismissSelfLog()` — the latter ahead of the `selectedMeta` guard), calls `setHelpContent()` + `GotoTop()` and returns the fetch command for the mode's missing source (README via `needsReadme`, `--help`/`man` via the `helpCache` miss + `helpLoadingFor`); focus stays with the caller, because `[h]`/`[m]` also fire from `[2]` and move it while `[r]` is `focusHelp`-only. A **live** update log keeps `[3]` in every path (the log branch sits ahead of the readme branch *and* the `No tool selected` guard in `renderHelpContent`, `setHelpContent` gates on `showsUpdateLog()`, and the readme case in `autoFetchCmdsForSelected` sits after that same case). **`m.helpCache` is a `map[string][2]string` whose values are indexed by `helpMode`, so mode 2 panics on every index site** — README content lives in `m.readmeData` instead and each index site (`rawHelpText`, `renderHelpContent`, `autoFetchCmdsForSelected`) carries a readme early-return/branch *before* the array read; `helpOutputMsg` indexes `msg.mode`, which only ever carries help/man. Rendering: `renderReadme` (readme.go) is a three-stage pipeline — `cleanTerminalOutput` (the same sanitizer every probe capture gets) → **`cleanReadmeMarkdown`** (readme_clean.go, the house-style preprocessor) → glamour with **`WithStyles(keepkitStyle(m.darkBG))`** (readme_style.go), `WithWordWrap(helpWrapWidth())`, `WithColorProfile(lipgloss.ColorProfile())` (glamour hardcodes TrueColor and would ignore `NO_COLOR`/dumb terms) and `WithInlineTableLinks(true)` (a table link in its cell, not a numbered footnote under the table). Dark/light is still resolved **once at construction** into `m.darkBG` via lipgloss's cached `HasDarkBackground()`, because `glamour.WithAutoStyle()` probes the terminal with a termenv OSC query that reads stdin and races Bubble Tea's input reader; what changed is that the answer now picks a *StyleConfig* rather than a style *name*, so `readmeStyleName` is gone and `renderReadme` branches on `testReadmeStyle != ""` (→ `WithStandardStyle`) directly — the seam's only job is to make the constructor fail. A glamour failure falls back to the **preprocessed** text (not the merely sanitized text), or a failed render would be the one path that still shows badge and href noise; never an empty panel. An input that cleans down to whitespace returns `""` early, which is what routes a badge-only README to the placeholder below.
+  - **The preprocessor (`cleanReadmeMarkdown`)** exists because a README is written for a browser: badges, logos, `<picture>` wrappers, hrefs nobody can click in a TTY, emoji a terminal font renders as tofu. It is pure and rests on one inviolable rule — **code is never rewritten**, since a fenced block and an inline span are exactly how a README *shows* the markup these rules delete. So `rcSegments` splits the input into protected fenced blocks (opener = 3+ backticks or tildes at any indent — CommonMark's 3-space limit only ever mis-read a fence nested under a list item; closer = the **same character**, a run **at least as long**, nothing but whitespace after, which keeps a ```` ``` ````-wrapping fence one block; an **unterminated fence protects to EOF**, because `version.getReadme` truncates at `readmeMaxBytes` and the cut can land mid-fence) and the cleanable runs between them, and inline spans are **masked** inside a cleanable segment (`rcMaskSpans`, a NUL-bracketed placeholder — NUL is the sentinel precisely because `cleanTerminalOutput` ran first and drops every control character). Masking rather than segmenting is deliberate: the block-level rules (a multi-line HTML comment, a `<picture>` body) need the segment to stay one string, and a span that *contains* `<!--` must still survive. The span search stops at a blank line, mirroring CommonMark's paragraph boundary — one stray backtick would otherwise pair with another three sections later and exempt half the README from cleaning. **4-space indented code blocks are not protected** (an accepted limitation: they are ambiguous with nested-list continuation lines, and modern READMEs use fences).
+  - **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 — gated on a declared label — 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). Shortcut references (`[label]`) are unwrapped only for labels a definition actually declared, collected **document-wide** — 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 would eat a task list's `[x]` and a prose `[experimental]`. Standalone `[label]: url` definition lines are dropped as the pure metadata they now are. *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. *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 one leading block marker 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 and a hard line break from losing its two trailing spaces. 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. 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.
+  - **The theme (`keepkitStyle(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. **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** peach `ui.ColorPrimary` 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, since without a background they only read as a stray indent. **H2** `ui.ColorCategory`, the color the brief card heads its own sections with. **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` (which the standard dark config singles out with a green non-bold override) in `ui.ColorText` bold, `LinkText` in `ui.ColorMeta`, `HorizontalRule` in `ui.ColorBorder` and `BlockQuote` in `ui.ColorDim` — because those tints are chosen against a dark panel and `#E8E8E8` body text is unreadable on white, where the standard light colors stay. Chroma (code-block syntax) is deliberately untouched. 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 result is memoized in the single-entry `readmeRenderCache` keyed by `(name, raw, width, dark)` — `setHelpContent` runs on every selection move and width resize and must not re-parse a large README each time. `parseHelpEntries`/`colorizeHelp` are **not** run in readme mode (glamour output is already ANSI): `helpEntries` stays empty so `j`/`k` are plain scroll, and `/` (help search) is a no-op — guarded at the shared `focusBrief || focusHelp` entry point, so the `[1]` tool-list search is unaffected; the `focusHelp` status bar drops the `[/] search` hint in readme mode rather than advertising a dead key. Placeholders are tool-named (`readmeContent` in render.go): no GitHub ref → `No repo for <name>. Press [h] for --help.`, in-flight → `Loading...`, `ErrNoReadme` → `No README in <owner/repo>. Press [h] for --help.`, `ErrRateLimited` → `rate limited — press [L]`, and a generic fallback `No README for <name>. Press [h] for --help.` for everything else — a network/5xx failure **and** the case where content exists but rendered to nothing. That last one is why the "real content" test is `data.content != "" && m.helpBase != ""`: returning an empty render as content paints a blank panel with no way out. The preprocessor turned that case from a curiosity into a *guarantee* — a README that is only badges, logos and HTML cleans down to whitespace and `renderReadme` returns `""` before glamour is even built — which is why render_test.go's "content that renders to nothing" now `t.Fatalf`s where it used to `t.Skipf` on an uncertain fixture.
 - **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-2, 20)`) 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 (`renderHelpContent`'s normal path serves `applySpotlight(helpBase)`; the base is built directly in `setHelpContent`, not via `renderHelpContent`, which can be in the search-highlight branch). **`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 (help-search keystrokes, 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 (`ui.HelpDimStyle.Render(stripANSI(line))` — the `[L]` 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, `/` help-search entry, 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 is managed from `focusTools`**: `t` track (add by GitHub URL or plain name → `modeTrack`), `u` untrack (with confirmation → `modeConfirmUntrack`), `r` rename (fix the binary name when the repo name differs → `modeRename`). 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`/`modeHelpSearch` exits; `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/README.md b/README.md
index e2d5f3d..d429f61 100644
--- a/README.md
+++ b/README.md
@@ -47,7 +47,10 @@ Pure TUI, no subcommands; the only flags are `--version` and `--help`.
   after the update one more key restarts keepkit in place, in the same terminal tab
 - **Docs panel** — panel `[3]` switches between the rendered repository README,
   `--help` output and the `man` page by hotkeys; in `--help` / `man` mode `j` / `k`
-  walk flags and subcommands with the current entry spotlighted
+  walk flags and subcommands with the current entry spotlighted. Every README is
+  rendered in one house style: badges, logos, HTML wrappers, unclickable link URLs
+  and emoji are stripped, and the headings follow keepkit's own palette — code
+  samples are left exactly as written
 - **Clickable card** — the repository and release links on the tool card open in the
   browser by mouse click, or by hotkeys for the repo and changelog pages
 - **Tags and grouping** — one tag per tool; `space` regroups the flat list under tag
@@ -119,8 +122,10 @@ Run `keepkit` — a three-panel interface opens:
   versions with the release date, status, note and tag. From here tools are updated,
   the repo or changelog opened in the browser, and the card data force-refreshed.
 - **`[3] Readme / Help / Man`** — the docs panel: the rendered repository README (the
-  default), the tool's `--help` output or its `man` page. While an update runs, this
-  panel shows its live log instead.
+  default), the tool's `--help` output or its `man` page. A README is cleaned up
+  before rendering — badges, logos, HTML and emoji go, link text stays without its
+  URL, and code blocks are untouched. While an update runs, this panel shows its live
+  log instead.
 
 Focus moves with `←` / `→` or the digits `1` / `2` / `3` (each panel's number is in
 its title). Each panel lists its keys in the help bar; press `?` any time for the
@@ -291,6 +296,7 @@ subprocess sandbox — is described in [ARCHITECTURE.md](ARCHITECTURE.md).
 - [Bubbles](https://github.com/charmbracelet/bubbles) — text input, viewport, spinner
 - [Lip Gloss](https://github.com/charmbracelet/lipgloss) — styling
 - [Glamour](https://github.com/charmbracelet/glamour) — markdown rendering for the README panel
+- [goldmark-emoji](https://github.com/yuin/goldmark-emoji) — GitHub's `:shortcode:` dictionary, used to strip them from a README
 - [x/ansi](https://github.com/charmbracelet/x) — stripping escape sequences from captured tool output
 - [termenv](https://github.com/muesli/termenv) — terminal color-profile detection
 - [go-runewidth](https://github.com/mattn/go-runewidth) — glyph width measurement
diff --git a/docs/plans/completed/20260728-readme-house-style.md b/docs/plans/completed/20260728-readme-house-style.md
index 9027cd0..4b1488f 100644
--- a/docs/plans/completed/20260728-readme-house-style.md
+++ b/docs/plans/completed/20260728-readme-house-style.md
@@ -199,17 +199,24 @@ unreadable on white):
 - Create: `internal/model/readme_clean.go`
 - Create: `internal/model/readme_clean_test.go`
 
-- [ ] implement segmentation of raw markdown into protected segments (fenced blocks per
+- [x] implement segmentation of raw markdown into protected segments (fenced blocks per
       the rules above, inline `` ` `` spans) and cleanable segments, plus the
       `cleanReadmeMarkdown` shell that reassembles them (rules arrive in Tasks 2–3)
-- [ ] handle the edge shapes: fence with info string; `~~~` fence; closer same-char and
+- [x] handle the edge shapes: fence with info string; `~~~` fence; closer same-char and
       length ≥ opener (````` ```` ````` wrapping ``` blocks); unterminated fence
       protects to EOF
-- [ ] write protection tests: junk-shaped content (`![…](…)`, `<div>`, emoji) inside a
+- [x] write protection tests: junk-shaped content (`![…](…)`, `<div>`, emoji) inside a
       fence and inside an inline span survives byte-for-byte through the shell
-- [ ] write segmentation edge tests: long fence wrapping short fences; unterminated
+- [x] write segmentation edge tests: long fence wrapping short fences; unterminated
       fence (simulated 512 KiB truncation cut); `~~~` with info string
-- [ ] run tests — must pass before task 2
+- [x] run tests — must pass before task 2
+
+➕ inline spans are masked with a NUL-bracketed placeholder (`rcMaskSpans`/`rcUnmaskSpans`)
+rather than split out as segments: block-level rules (multi-line HTML comments and
+`<picture>` bodies) need the segment to stay one string, and a code span that *contains*
+`<!--` must still survive. The span search stops at a blank line, mirroring CommonMark's
+paragraph boundary — otherwise one stray backtick would exempt everything up to the next
+one from cleaning.
 
 ### Task 2: Removal rules — images, links, HTML
 
@@ -217,20 +224,40 @@ unreadable on white):
 - Modify: `internal/model/readme_clean.go`
 - Modify: `internal/model/readme_clean_test.go`
 
-- [ ] implement image removal: `![alt](url)`, `[![alt](img)](target)`,
+- [x] implement image removal: `![alt](url)`, `[![alt](img)](target)`,
       reference-style `![alt][ref]` / `![alt][]`; collapse lines left empty
-- [ ] implement link unwrapping `[text](url)` / `[text][ref]` → `text`; remove
+- [x] implement link unwrapping `[text](url)` / `[text][ref]` → `text`; remove
       standalone link-reference definition lines; leave autolinks
       (`<https://…>`, `<user@host>`) and bare URLs untouched
-- [ ] implement HTML removal: comments whole; `<img>`/`<picture>`/`<video>`/`<script>`/
+- [x] implement HTML removal: comments whole; `<img>`/`<picture>`/`<video>`/`<script>`/
       `<style>` whole including bodies; other tags stripped keeping inner text, tag
       pattern constrained to plausible HTML tag names; package-level regexes only
-- [ ] write table-driven tests: inline/linked/reference badge headers vanish with no
+- [x] write table-driven tests: inline/linked/reference badge headers vanish with no
       orphan definitions; `[text](url)` → `text`; `<kbd>`/`<details>` keep text;
       `<script>` body gone
-- [ ] write negative tests: autolink, email autolink, `Vec<String>`, `a < b` prose, and
+- [x] write negative tests: autolink, email autolink, `Vec<String>`, `a < b` prose, and
       bare URLs all survive; `:30:`-style text untouched by these rules
-- [ ] run tests — must pass before task 3
+- [x] run tests — must pass before task 3
+
+➕ the "plausible tag name" constraint landed as an **allowlist** of the elements READMEs
+use (`rcHTMLNames`), not a generic identifier shape: a shape-based pattern cannot tell
+`<kbd>` from `Vec<String>`, and an unknown name left as written is the honest degradation.
+`<img>` needs no bodied-element entry — it is void, so the tag strip removes the whole
+element. `<svg>`/`<audio>` were added to the bodied list (an inline SVG logo is the same
+class of noise as a `<picture>`).
+
+➕ the per-line tidy-up ("collapse doubled spaces, drop lines emptied by removal", planned
+for Task 3) had to land here — an image-only badge row needs it to vanish. Both the tidy
+and the drop are gated on the line having actually **changed**, so an untouched `- - -`
+thematic break is never mistaken for an emptied bullet and a hard line break keeps its
+trailing spaces. The indent is taken from the *original* line, or a leading `🚀 ` removed
+in Task 3 would leave an indent the author never wrote.
+
+➕ shortcut reference links (`[label]` with a `[label]: url` definition elsewhere) are
+unwrapped too, gated on a **document-wide** set of declared labels — 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 would eat a task list's `[x]` and a prose
+`[experimental]`.
 
 ### Task 3: Removal rules — emoji and shortcodes
 
@@ -239,18 +266,21 @@ unreadable on white):
 - Modify: `internal/model/readme_clean_test.go`
 - Modify: `go.mod` (goldmark-emoji indirect → direct)
 
-- [ ] implement emoji stripping (U+1F000–U+1FAFF, VS16, ZWJ, U+20E3) with the
+- [x] implement emoji stripping (U+1F000–U+1FAFF, VS16, ZWJ, U+20E3) with the
       translation map `✅→✓`, `❌→✗`, `☑→✓`; keep BMP symbols (`✓ ★ →`)
-- [ ] implement post-removal cleanup: collapse doubled spaces, drop lines emptied by
-      removal (emoji-only headings disappear)
-- [ ] implement shortcode removal via `definition.Github()` (direct import; no new
+- [x] implement post-removal cleanup: collapse doubled spaces, drop lines emptied by
+      removal (emoji-only headings disappear) — landed in Task 2, see the note there
+- [x] implement shortcode removal via `definition.Github()` (direct import; no new
       module in go.sum; no caching wrapper — it is `sync.Once`-guarded)
-- [ ] write tests: emoji stripped from headings/prose without double-space artifacts;
+- [x] write tests: emoji stripped from headings/prose without double-space artifacts;
       emoji-only heading dropped; keycap `1️⃣` leaves no stray U+20E3; translation map
       applied; BMP symbols survive
-- [ ] write negative tests: `:30:` inside `12:30:45` survives; unknown `:foo:` survives;
+- [x] write negative tests: `:30:` inside `12:30:45` survives; unknown `:foo:` survives;
       known `:rocket:` removed; shortcode and emoji inside a fence survive
-- [ ] run tests — must pass before task 4
+- [x] run tests — must pass before task 4
+
+➕ `go mod tidy` moved `goldmark-emoji` to the direct block and touched nothing else —
+`go.sum` is unchanged, as the plan predicted.
 
 ### Task 4: Theme — keepkitStyle and renderReadme integration
 
@@ -260,51 +290,98 @@ unreadable on white):
 - Modify: `internal/model/readme.go`
 - Modify: `internal/model/readme_test.go`
 
-- [ ] implement `keepkitStyle(dark bool) ansi.StyleConfig` per Technical Details:
+- [x] implement `keepkitStyle(dark bool) ansi.StyleConfig` per Technical Details:
       clone the standard config, override headings/links/rules/margin with values
       derived from `ui.Color*`; every override assigns a **fresh pointer** — never
       write through a cloned pointer
-- [ ] wire the pipeline in `renderReadme`: `cleanTerminalOutput` →
+- [x] wire the pipeline in `renderReadme`: `cleanTerminalOutput` →
       `cleanReadmeMarkdown` (re-check emptiness after it — early return `""`) → glamour
       with `WithStyles(keepkitStyle(dark))` + `WithInlineTableLinks(true)`; the
       plain-text fallback returns the *preprocessed* text
-- [ ] collapse the dead seam: branch on `testReadmeStyle != ""` directly in
+- [x] collapse the dead seam: branch on `testReadmeStyle != ""` directly in
       `renderReadme` (→ `WithStandardStyle(testReadmeStyle)`), delete
       `readmeStyleName`, delete `TestRenderReadmeStyleFollowsBackground`
-- [ ] update the two fallback assertions (`readme_test.go` ~84, ~147) to compare
+- [x] update the two fallback assertions (`readme_test.go` ~84, ~147) to compare
       against `cleanReadmeMarkdown(cleanTerminalOutput(raw))`; add one fallback case
       whose input the preprocessor actually changes
-- [ ] write struct-level theme tests: `H1.Color == string(ui.ColorPrimary)` (deref),
+- [x] write struct-level theme tests: `H1.Color == string(ui.ColorPrimary)` (deref),
       `H1.BackgroundColor == nil`, `*Document.Margin == 0`, dark/light differ; plus a
       regression test that `styles.DarkStyleConfig`/`LightStyleConfig` are deep-equal
       to their pre-call values after both `keepkitStyle(true)` and `keepkitStyle(false)`
-- [ ] write behavioral tests: `[text](url)` renders as `text` — URL absent, **no double
+- [x] write behavioral tests: `[text](url)` renders as `text` — URL absent, **no double
       space**; a table with a `[manual](url)` link renders the cell with no footnote
       stub; autolink and bare URL still visible; both variants render a sample doc
       without error; badge-only README renders to `""`
-- [ ] run tests — must pass before task 5
+- [x] run tests — must pass before task 5
+
+➕ `Heading` (the base every `Hn` cascades onto) carries the H3+ rule rather than four
+separate overrides; `H6` still needs its own, because the standard dark config singles it
+out with a green non-bold override. H1's `Prefix`/`Suffix` padding spaces went with the
+plate — without a background they only read as a stray indent.
+
+➕ the globals-untouched regression compares a **JSON snapshot**, not `reflect.DeepEqual`
+against a saved copy: a struct copy aliases the very pointers a write-through would
+corrupt, so the "before" value would change with the "after" and the test would pass on
+the bug it exists to catch.
+
+➕ the "no double space" assertion runs on the **preprocessed source**, not the rendered
+output: glamour pads table cells with runs of spaces of its own, which is layout, not
+removal residue.
 
 ### Task 5: Verify acceptance criteria
 
-- [ ] verify every bullet of the **Acceptance criteria** list in the Overview
-- [ ] verify edge cases: README of only badges/HTML → friendly placeholder; README with
+- [x] verify every bullet of the **Acceptance criteria** list in the Overview
+- [x] verify edge cases: README of only badges/HTML → friendly placeholder; README with
       HTML/markdown examples inside fences → examples intact; truncated-mid-fence input
-- [ ] run full CI matrix locally: `go build .`, `go vet ./...`,
-      `go test -race ./...`, `golangci-lint run` (preflight)
-- [ ] verify go.mod/go.sum changed only by the goldmark-emoji promotion (no new modules)
+- [x] run full CI matrix locally: `go build .`, `go vet ./...`,
+      `go test -race ./...`, `golangci-lint run` (preflight) — plus the cross-compile
+      step (`GOOS=windows build`+`vet`, `GOOS=darwin build`); all green
+- [x] verify go.mod/go.sum changed only by the goldmark-emoji promotion (no new modules)
+      — `go.sum` untouched, `go.mod` moves one line
+
+Where each criterion is pinned: images incl. reference-style →
+`TestCleanReadmeMarkdownImagesAndLinks`; HTML junk / `<kbd>` text →
+`TestCleanReadmeMarkdownHTML`; link unwrapping, autolinks, bare URLs, no footnote stub,
+no double space → `TestRenderReadmeHouseStyle`; emoji, shortcodes and the `✅/❌/☑`
+translation → `TestCleanReadmeMarkdownEmojiAndShortcodes` +
+`TestCleanReadmeMarkdownShortcodeNeedsAKnownName`; palette and the missing H1 plate →
+`TestKeepkitStyleOverrides` + `TestKeepkitStyleDarkOnlyOverrides`; code byte-identity →
+`TestCleanReadmeMarkdownProtectsFences` + `…ProtectsInlineSpans`; badge-only → placeholder
+→ `TestRenderReadmeBadgeOnlyIsEmpty` and render_test.go's "content that renders to
+nothing" (whose `t.Skipf` escape hatch is now a `t.Fatalf` — the preprocessor makes the
+empty render a guarantee, not a hope); globals unmutated →
+`TestKeepkitStyleLeavesGlobalsUntouched`.
+
+➕ **observed on a realistic README, out of this plan's scope, left for the user to
+decide** — a centered HTML title (`<h1 align="center">name</h1>`, very common in
+badge-heavy READMEs) keeps its text but loses its heading status: the tag strip is
+text-preserving by design, and turning `<h1>`–`<h6>` elements into markdown headings is a
+rule nobody approved. Also unchanged (and pre-existing, not caused by this work): a mailto
+autolink still renders as `team@example.com mailto:team@example.com`, because glamour
+prints `LinkText` and `Link` both and the Decision log closed the door on `Link.Format`.
+`✨` and other BMP pictographs survive by design — only the SMP blocks and the three
+translated marks are in scope.
 
 ### Task 6: [Final] Update documentation
 
-- [ ] update CLAUDE.md: `model` package file table (~line 50: add `readme_clean.go`,
+- [x] update CLAUDE.md: `model` package file table (~line 50: add `readme_clean.go`,
       `readme_style.go`) and the panel `[3]` modes paragraph (~line 111: the "runs
       glamour with a **fixed** `WithStandardStyle("dark"|"light")`" clause → the new
-      pipeline)
-- [ ] update ARCHITECTURE.md in its three spots: the `model` file table (~line 74,
+      pipeline). The empty-render placeholder sentence was updated too — the
+      preprocessor turns that case from a curiosity into a guarantee.
+- [x] update ARCHITECTURE.md in its three spots: the `model` file table (~line 74,
       `readme.go` row), the "passed to glamour as a fixed `WithStandardStyle`" clause
       (~line 134), and the `testReadmeStyle` seam description (~line 399)
-- [ ] check README.md: only the Glamour credit line (~262) touches this area — update
-      only if the rendering description changed
-- [ ] move this plan to `docs/plans/completed/`
+- [x] check README.md: the Glamour credit line, plus the two user-facing panel `[3]`
+      descriptions (feature list and panel list) now say a README is cleaned up before
+      rendering, and **goldmark-emoji joined the Stack** as a new direct dependency
+- [x] move this plan to `docs/plans/completed/`
+
+Docs-sync drift check on the other known-drift spots: mermaid package graph — совпадает
+(`model` already imported `ui`, no new internal edge); `inputMode` enum, key tables,
+timeouts/limits, storage-paths table — не затронуты; test seams — `testReadmeStyle`
+исправлен, новых нет; README Stack vs `go.mod` direct deps — расхождение → исправлено
+(README.md, goldmark-emoji added; the two lists now match exactly, 10 entries).
 
 ## Post-Completion
 

From adf98e3cccdda6afaf2c6ff85c7786b6715010b3 Mon Sep 17 00:00:00 2001
From: stanlyzoolo <51911715+stanlyzoolo@users.noreply.github.com>
Date: Tue, 28 Jul 2026 13:59:37 +0300
Subject: [PATCH 5/5] fix(model): nine defects the whole suite passed over
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A review of the finished branch found nine confirmed bugs in the README
preprocessor. Build, vet, race tests and golangci-lint were all green on
every one of them, which is the more useful finding: the suite tested the
rules, not the inputs that break them. Each fix lands with a test row.

1. rcLineContent was quadratic — 8.4 s of frozen TUI. The pattern is
^-anchored, so ReplaceAllString could only ever rewrite the head, yet it
copied the whole remaining line every pass. One line of "🚀 " plus 262144
"- " markers — 512 KiB, exactly readmeMaxBytes — inside a synchronous
Update(), driven by untrusted remote markdown. It slices now, and a perf
test guards the shape.

2. A URL containing ")" leaked its tail on screen. The flat "[^)]*"
destination stopped at the inner paren of a shields.io badge
(…/badge/a-(b)-blue.svg) or a Wikipedia link (…/wiki/Foo_(bar)) and left
the rest as text — the exact noise the pass removes. mdDest now allows
one level of nesting, which fixes the card's converter with it.

3. A paragraph line shaped like a definition was deleted. "[note]: this
matters" sitting mid-paragraph vanished. Deleting a line of someone's
README is the most destructive thing here, so it now takes two guards: a
single-token destination with at most a quoted title, and CommonMark's
rule that a definition cannot interrupt a paragraph.

4. The reference form [text][ref] was ungated while the shortcut form
three lines below it was carefully gated for the identical reason:
"the value arr[i][j] is used" came out as "the value arri is used".

5. A label declared inside an HTML comment gated the unwrapping. The
label set was collected before the HTML rules ran, so a commented-out
"[x]: url" ate a task list's "[x]" — the bracket the gate exists to
protect. Collection moved after stripping; the pass is two phases now.

6. An HTML attribute containing ">" ended the tag early:
<img alt="a > b" src="x.png"> rendered as ` b" src="x.png">`. The
attribute pattern matches quoted values whole.

7. An orphaned setext underline outlived its dropped title, leaving a
visible row of equals signs. Only the "=" form is dropped — a "-" run is
equally a thematic break and renders as a rule either way.

8. CRLF fed straight to cleanReadmeMarkdown disabled the entire pass: a
"```\r" closer never matches, so the first fence protected to EOF.
Production was safe because cleanTerminalOutput drops \r first — but
every unit test calls the function directly, i.e. every test took the
broken path. Normalized on entry, like markdownToLines.

9. The hard-line-break claim was false. Both the comment and CLAUDE.md
said the change-gate preserved two trailing spaces; it dropped them
whenever the line changed. rcTidyLine carries them over explicitly.

Documented rather than fixed: two code spans separated by nothing but a
removed construct come back adjacent (`x`![i](u)`y` → `x``y`), which
CommonMark reads as one span. It needs zero whitespace on both sides, and
any fix invents a separator the author did not write.

Also closed the test gaps the review named: paren URLs, CRLF, the ungated
reference form, definition-in-a-paragraph, the ten-badge fold, the
stray-backtick end-to-end case, and a table-cell autolink row that
actually kills the WithInlineTableLinks mutation — verified by deleting
the option and watching the test fail.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 ARCHITECTURE.md                               |   7 +-
 CLAUDE.md                                     |   7 +-
 README.md                                     |  10 +-
 .../completed/20260728-readme-house-style.md  |  39 ++++
 internal/model/readme_clean.go                | 189 ++++++++++++++----
 internal/model/readme_clean_test.go           |  98 +++++++++
 internal/model/readme_style_test.go           |  53 +++--
 internal/model/textutil.go                    |  12 +-
 8 files changed, 354 insertions(+), 61 deletions(-)

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 6637a53..149cdd0 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -144,7 +144,12 @@ before rendering. It rests on one rule — **code is never rewritten** — becau
 block and an inline span are exactly how a README *shows* the markup being deleted, so
 fences are segmented out (an unterminated one protects to EOF, since the
 `readmeMaxBytes` cut can land mid-fence) and inline spans are masked for the duration.
-Autolinks and bare URLs survive: there the URL *is* the content. `keepkitStyle` then
+Autolinks and bare URLs survive: there the URL *is* the content. Every rule that could
+swallow ordinary prose is gated — a `[label]` form is unwrapped only for labels a
+definition declared (ungated, `arr[i][j]` became `arri`), and a definition line is
+deleted only when it cannot be part of a paragraph. Because the pass runs inside
+`Update()` on up to `readmeMaxBytes`, no step in it may be superlinear;
+`TestCleanReadmeMarkdownPathologicalInputIsFast` is the guard. `keepkitStyle` then
 clones the standard config rather than building one, so a glamour upgrade that adds a
 field cannot leave the panel with a hole in it — and because the package globals it
 clones hold pointers that `styles.DefaultStyles` aliases, every override assigns a fresh
diff --git a/CLAUDE.md b/CLAUDE.md
index b5d32a2..7952e1b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -112,9 +112,10 @@ The model is a three-panel layout with focus cycling via `→/←` between `focu
   - **Restart**: `[U]` at `selfUpdated`/`selfUpdatedLater` sets `m.restartRequested` and returns `tea.Quit` — `selfState` is deliberately not moved (after `tea.Quit` nothing renders, and a failed exec exits anyway, so a sixth enum member would be dead). `RestartRequested()` is the exported accessor `main` reads off the model `p.Run()` returns, **strictly after** it returned: Bubble Tea has restored the terminal by then, whereas exec'ing from inside `Update` would hand the new process an alt screen it never opened. `restart_unix.go`'s `restartSelf()` delegates to the seam-injected `restartSelfWith(resolve, execve, out)` (the `exists`/`lookPath` idiom again, so both failure paths are testable) = `selfPath()` + `syscall.Exec(path, os.Args, os.Environ())` — same pid, same argv, same env, so the tab/tmux pane survives. Only a failure logs `logx.Errorf("restart self: …")` (a genuine anomaly) and prints the shared `restartHint` (`keepkit updated — run keepkit again`) to **stdout** at exit code 0 — the update did succeed, so this is an instruction, not diagnostics; a successful exec never comes back, so the whole tail is unreachable on success and says nothing. `restart_windows.go` prints the same hint and nothing else: there is no image-replacing exec, and spawning a child from a process about to exit hands the new keepkit a console the old one still owns. It logs nothing — planned degradation, not a malfunction.
   - **Path resolution** (`restart_unix.go`, pure core + thin wrapper): `resolveSelfPath(executable, exists, lookPath, argv0)` mirrors how a shell resolves what the user typed instead of trusting `os.Executable`. An argv0 carrying a path separator (`strings.Contains(argv0, "/")` — the file is `//go:build !windows`, so `/` is the only separator that can reach it; the backslash and the `.exe`-trimming in `sameProgram` that the core carried while it lived in the untagged `restart.go` were dead branches under the tag and are gone, along with the two test rows that exercised them) is already a path the user pointed at and wins when it `exists`, with no `lookPath` call — a same-named binary earlier in `PATH` must not hijack `./keepkit`. A **bare** argv0 goes through `lookPath` **first**, and this order is load-bearing on **Linux**: there `os.Executable()` reads `/proc/self/exe` symlink-*resolved*, so after a keg-style upgrade it can still name the live *old* binary, and exec'ing that would loop the feature (restart → the same banner → restart). Two things disqualify a `PATH` hit: `("", nil)` counts as a miss (an empty string must never reach `syscall.Exec`), and so does a hit whose `filepath.Base` differs from `executable`'s (`sameProgram`) — argv0 comes from the *parent* process, so a wrapper using `exec -a` or a shell that rewrote `argv[0]` would otherwise make the restart exec an unrelated program with keepkit's argv and environment. `executable` is the fallback for both branches and only when it `exists`; nothing left → error → `restartHint`, no exec. **Known asymmetry**: `updater.Detect` resolves the update *target* from `exec.LookPath(t.Name)`, so a release binary launched by path (`./keepkit`) while another keepkit sits on `PATH` updates the `PATH` one and then re-execs the by-path (un-updated) binary — the banner comes back. Fixing it means changing where `Detect` starts, which is shared with `[u]` for every tool and out of this feature's scope; README lists it as a caveat.
 - **Panel `[3]` modes (`helpMode`)**: three sources — `helpModeReadme = 2` (the **default** set in `New()`), `helpModeHelp = 0`, `helpModeMan = 1`. `helpMode` is a sticky global field, not per tool: `[r]` (only in `focusHelp` — `case "r"` branches on focus: `focusTools` rename, `focusBrief` refresh), `[h]` and `[m]` (both fire from `focusBrief || focusHelp`) switch it. All three go through the shared **`switchHelpMode(mode)`** (model.go), which sets the mode, dismisses a *completed* update log (a tool's via `updateLogFor`, keepkit's own via `dismissSelfLog()` — the latter ahead of the `selectedMeta` guard), calls `setHelpContent()` + `GotoTop()` and returns the fetch command for the mode's missing source (README via `needsReadme`, `--help`/`man` via the `helpCache` miss + `helpLoadingFor`); focus stays with the caller, because `[h]`/`[m]` also fire from `[2]` and move it while `[r]` is `focusHelp`-only. A **live** update log keeps `[3]` in every path (the log branch sits ahead of the readme branch *and* the `No tool selected` guard in `renderHelpContent`, `setHelpContent` gates on `showsUpdateLog()`, and the readme case in `autoFetchCmdsForSelected` sits after that same case). **`m.helpCache` is a `map[string][2]string` whose values are indexed by `helpMode`, so mode 2 panics on every index site** — README content lives in `m.readmeData` instead and each index site (`rawHelpText`, `renderHelpContent`, `autoFetchCmdsForSelected`) carries a readme early-return/branch *before* the array read; `helpOutputMsg` indexes `msg.mode`, which only ever carries help/man. Rendering: `renderReadme` (readme.go) is a three-stage pipeline — `cleanTerminalOutput` (the same sanitizer every probe capture gets) → **`cleanReadmeMarkdown`** (readme_clean.go, the house-style preprocessor) → glamour with **`WithStyles(keepkitStyle(m.darkBG))`** (readme_style.go), `WithWordWrap(helpWrapWidth())`, `WithColorProfile(lipgloss.ColorProfile())` (glamour hardcodes TrueColor and would ignore `NO_COLOR`/dumb terms) and `WithInlineTableLinks(true)` (a table link in its cell, not a numbered footnote under the table). Dark/light is still resolved **once at construction** into `m.darkBG` via lipgloss's cached `HasDarkBackground()`, because `glamour.WithAutoStyle()` probes the terminal with a termenv OSC query that reads stdin and races Bubble Tea's input reader; what changed is that the answer now picks a *StyleConfig* rather than a style *name*, so `readmeStyleName` is gone and `renderReadme` branches on `testReadmeStyle != ""` (→ `WithStandardStyle`) directly — the seam's only job is to make the constructor fail. A glamour failure falls back to the **preprocessed** text (not the merely sanitized text), or a failed render would be the one path that still shows badge and href noise; never an empty panel. An input that cleans down to whitespace returns `""` early, which is what routes a badge-only README to the placeholder below.
-  - **The preprocessor (`cleanReadmeMarkdown`)** exists because a README is written for a browser: badges, logos, `<picture>` wrappers, hrefs nobody can click in a TTY, emoji a terminal font renders as tofu. It is pure and rests on one inviolable rule — **code is never rewritten**, since a fenced block and an inline span are exactly how a README *shows* the markup these rules delete. So `rcSegments` splits the input into protected fenced blocks (opener = 3+ backticks or tildes at any indent — CommonMark's 3-space limit only ever mis-read a fence nested under a list item; closer = the **same character**, a run **at least as long**, nothing but whitespace after, which keeps a ```` ``` ````-wrapping fence one block; an **unterminated fence protects to EOF**, because `version.getReadme` truncates at `readmeMaxBytes` and the cut can land mid-fence) and the cleanable runs between them, and inline spans are **masked** inside a cleanable segment (`rcMaskSpans`, a NUL-bracketed placeholder — NUL is the sentinel precisely because `cleanTerminalOutput` ran first and drops every control character). Masking rather than segmenting is deliberate: the block-level rules (a multi-line HTML comment, a `<picture>` body) need the segment to stay one string, and a span that *contains* `<!--` must still survive. The span search stops at a blank line, mirroring CommonMark's paragraph boundary — one stray backtick would otherwise pair with another three sections later and exempt half the README from cleaning. **4-space indented code blocks are not protected** (an accepted limitation: they are ambiguous with nested-list continuation lines, and modern READMEs use fences).
-  - **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 — gated on a declared label — 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). Shortcut references (`[label]`) are unwrapped only for labels a definition actually declared, collected **document-wide** — 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 would eat a task list's `[x]` and a prose `[experimental]`. Standalone `[label]: url` definition lines are dropped as the pure metadata they now are. *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. *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 one leading block marker 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 and a hard line break from losing its two trailing spaces. 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. 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.
+  - **The preprocessor (`cleanReadmeMarkdown`)** exists because a README is written for a browser: badges, logos, `<picture>` wrappers, hrefs nobody can click in a TTY, emoji a terminal font renders as tofu. It is pure and rests on one inviolable rule — **code is never rewritten**, since a fenced block and an inline span are exactly how a README *shows* the markup these rules delete. So `rcSegments` splits the input into protected fenced blocks (opener = 3+ backticks or tildes at any indent — CommonMark's 3-space limit only ever mis-read a fence nested under a list item; closer = the **same character**, a run **at least as long**, nothing but whitespace after, which keeps a ```` ``` ````-wrapping fence one block; an **unterminated fence protects to EOF**, because `version.getReadme` truncates at `readmeMaxBytes` and the cut can land mid-fence) and the cleanable runs between them, and inline spans are **masked** inside a cleanable segment (`rcMaskSpans`, a NUL-bracketed placeholder — NUL is the sentinel precisely because `cleanTerminalOutput` ran first and drops every control character). Masking rather than segmenting is deliberate: the block-level rules (a multi-line HTML comment, a `<picture>` body) need the segment to stay one string, and a span that *contains* `<!--` must still survive. The span search stops at a blank line, mirroring CommonMark's paragraph boundary — one stray backtick would otherwise pair with another three sections later and exempt half the README from cleaning. Known limit, documented rather than fixed: two spans separated by *nothing* but a removed construct come back adjacent (`` `x`![i](u)`y` `` → `` `x``y` ``), which CommonMark then reads as one span — it needs zero whitespace on either side, so no real prose hits it, and fixing it means inventing a separator the author did not write. **CRLF is normalized on entry** for `markdownToLines`' reason and one of its own: a `` ```\r `` closing fence never matches, so the first fence would protect everything to EOF and nothing would be cleaned at all. Production is safe without it (`cleanTerminalOutput` drops `\r` first), but every test calls `cleanReadmeMarkdown` directly — which is exactly the path that broke. **4-space indented code blocks are not protected** (an accepted limitation: they are ambiguous with nested-list continuation lines, and modern READMEs use fences).
+  - **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(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. **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** peach `ui.ColorPrimary` 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, since without a background they only read as a stray indent. **H2** `ui.ColorCategory`, the color the brief card heads its own sections with. **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` (which the standard dark config singles out with a green non-bold override) in `ui.ColorText` bold, `LinkText` in `ui.ColorMeta`, `HorizontalRule` in `ui.ColorBorder` and `BlockQuote` in `ui.ColorDim` — because those tints are chosen against a dark panel and `#E8E8E8` body text is unreadable on white, where the standard light colors stay. Chroma (code-block syntax) is deliberately untouched. 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 result is memoized in the single-entry `readmeRenderCache` keyed by `(name, raw, width, dark)` — `setHelpContent` runs on every selection move and width resize and must not re-parse a large README each time. `parseHelpEntries`/`colorizeHelp` are **not** run in readme mode (glamour output is already ANSI): `helpEntries` stays empty so `j`/`k` are plain scroll, and `/` (help search) is a no-op — guarded at the shared `focusBrief || focusHelp` entry point, so the `[1]` tool-list search is unaffected; the `focusHelp` status bar drops the `[/] search` hint in readme mode rather than advertising a dead key. Placeholders are tool-named (`readmeContent` in render.go): no GitHub ref → `No repo for <name>. Press [h] for --help.`, in-flight → `Loading...`, `ErrNoReadme` → `No README in <owner/repo>. Press [h] for --help.`, `ErrRateLimited` → `rate limited — press [L]`, and a generic fallback `No README for <name>. Press [h] for --help.` for everything else — a network/5xx failure **and** the case where content exists but rendered to nothing. That last one is why the "real content" test is `data.content != "" && m.helpBase != ""`: returning an empty render as content paints a blank panel with no way out. The preprocessor turned that case from a curiosity into a *guarantee* — a README that is only badges, logos and HTML cleans down to whitespace and `renderReadme` returns `""` before glamour is even built — which is why render_test.go's "content that renders to nothing" now `t.Fatalf`s where it used to `t.Skipf` on an uncertain fixture.
 - **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-2, 20)`) 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 (`renderHelpContent`'s normal path serves `applySpotlight(helpBase)`; the base is built directly in `setHelpContent`, not via `renderHelpContent`, which can be in the search-highlight branch). **`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 (help-search keystrokes, 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 (`ui.HelpDimStyle.Render(stripANSI(line))` — the `[L]` 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, `/` help-search entry, 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 is managed from `focusTools`**: `t` track (add by GitHub URL or plain name → `modeTrack`), `u` untrack (with confirmation → `modeConfirmUntrack`), `r` rename (fix the binary name when the repo name differs → `modeRename`). 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.
diff --git a/README.md b/README.md
index d429f61..9f21ef7 100644
--- a/README.md
+++ b/README.md
@@ -49,8 +49,8 @@ Pure TUI, no subcommands; the only flags are `--version` and `--help`.
   `--help` output and the `man` page by hotkeys; in `--help` / `man` mode `j` / `k`
   walk flags and subcommands with the current entry spotlighted. Every README is
   rendered in one house style: badges, logos, HTML wrappers, unclickable link URLs
-  and emoji are stripped, and the headings follow keepkit's own palette — code
-  samples are left exactly as written
+  and the pictographic emoji a terminal font cannot draw are stripped, and the
+  headings follow keepkit's own palette — code samples are left exactly as written
 - **Clickable card** — the repository and release links on the tool card open in the
   browser by mouse click, or by hotkeys for the repo and changelog pages
 - **Tags and grouping** — one tag per tool; `space` regroups the flat list under tag
@@ -123,9 +123,9 @@ Run `keepkit` — a three-panel interface opens:
   the repo or changelog opened in the browser, and the card data force-refreshed.
 - **`[3] Readme / Help / Man`** — the docs panel: the rendered repository README (the
   default), the tool's `--help` output or its `man` page. A README is cleaned up
-  before rendering — badges, logos, HTML and emoji go, link text stays without its
-  URL, and code blocks are untouched. While an update runs, this panel shows its live
-  log instead.
+  before rendering — badges, logos, HTML and pictographic emoji go, link text stays
+  without its URL, and code blocks are untouched. While an update runs, this panel
+  shows its live log instead.
 
 Focus moves with `←` / `→` or the digits `1` / `2` / `3` (each panel's number is in
 its title). Each panel lists its keys in the help bar; press `?` any time for the
diff --git a/docs/plans/completed/20260728-readme-house-style.md b/docs/plans/completed/20260728-readme-house-style.md
index 4b1488f..f813e8b 100644
--- a/docs/plans/completed/20260728-readme-house-style.md
+++ b/docs/plans/completed/20260728-readme-house-style.md
@@ -383,6 +383,45 @@ timeouts/limits, storage-paths table — не затронуты; test seams —
 исправлен, новых нет; README Stack vs `go.mod` direct deps — расхождение → исправлено
 (README.md, goldmark-emoji added; the two lists now match exactly, 10 entries).
 
+## Review findings (PR #47, 2026-07-28) — fixed on the branch
+
+A full review of the finished branch found nine confirmed defects that the whole test
+suite, `go vet` and `golangci-lint` all passed over. All are fixed; each has a test row.
+
+1. **`rcLineContent` was quadratic — 8.4 s of frozen TUI.** The `^`-anchored pattern went
+   through `ReplaceAllString`, copying the remaining line once per leading marker. One
+   line of `🚀 ` + 262144 `- ` (512 KiB, exactly `readmeMaxBytes`) inside a synchronous
+   `Update()`, driven by untrusted remote markdown. Now slices; guarded by a perf test.
+2. **A URL containing `)` leaked its tail on screen** — shields.io badges and Wikipedia
+   links routinely carry one. `mdDest` now allows one level of nested parentheses, which
+   fixes the card's converter at the same time.
+3. **A paragraph line shaped like a link definition was deleted.** `[note]: this matters`
+   mid-paragraph vanished. Now needs a plausible destination *and* may not interrupt a
+   paragraph.
+4. **The reference form `[text][ref]` was ungated** while the shortcut form three lines
+   below it was carefully gated for the identical reason: `arr[i][j]` → `arri`.
+5. **A label declared inside an HTML comment gated the unwrapping** — the label set was
+   collected before the HTML rules ran, so a commented-out `[x]: url` ate a task list's
+   `[x]`. Collection moved after stripping.
+6. **An HTML attribute containing `>`** ended the tag early: `<img alt="a > b" src="x">`
+   rendered as ` b" src="x">`. The attribute pattern now matches quoted values whole.
+7. **An orphaned setext underline outlived its dropped title**, leaving a row of equals
+   signs.
+8. **CRLF fed directly to `cleanReadmeMarkdown` disabled the entire pass** (a `` ```\r ``
+   closer never matches, so the first fence protected to EOF). Production was safe;
+   every unit test took the broken path. Normalized on entry, like `markdownToLines`.
+9. **The hard-line-break claim in the code comment and in CLAUDE.md was false** — two
+   trailing spaces were dropped whenever the line changed. `rcTidyLine` now carries them.
+
+Documented rather than fixed: two code spans separated by nothing but a removed
+construct come back adjacent (`` `x`![i](u)`y` `` → `` `x``y` ``). It needs zero
+whitespace on both sides, and any fix invents a separator the author did not write.
+
+Test gaps closed along the way: a pathological-input perf guard, paren URLs, CRLF, the
+ungated reference form, the definition-in-a-paragraph case, the ten-badge fold, the
+stray-backtick end-to-end case, and a table-cell autolink row that actually kills the
+`WithInlineTableLinks` mutation (verified by removing the option — the test fails).
+
 ## Post-Completion
 
 **Manual verification:**
diff --git a/internal/model/readme_clean.go b/internal/model/readme_clean.go
index 36cfe4d..03a69e7 100644
--- a/internal/model/readme_clean.go
+++ b/internal/model/readme_clean.go
@@ -99,6 +99,11 @@ var rcSpanMarkRe = regexp.MustCompile("\x00(\\d+)\x00")
 // rcMaskSpans replaces every inline code span with an opaque placeholder so the
 // removal rules cannot rewrite what a README meant to show verbatim. The second
 // result is the restore table for rcUnmaskSpans.
+//
+// Known limit: two spans separated by nothing but a removed construct come back
+// adjacent (`x`![i](u)`y` → `x``y`), which CommonMark then reads as one span.
+// It needs zero whitespace on either side of the construct, so no real prose
+// hits it; fixing it means inventing a separator the author did not write.
 func rcMaskSpans(s string) (string, []string) {
 	if !strings.Contains(s, "`") {
 		return s, nil
@@ -169,8 +174,11 @@ func rcUnmaskSpans(s string, spans []string) string {
 		return s
 	}
 	return rcSpanMarkRe.ReplaceAllStringFunc(s, func(m string) string {
+		// The index was written by rcMaskSpans and the sentinel is stripped from
+		// the input, so neither branch should ever fire; they are here because a
+		// broken invariant must degrade to a lost span, not panic mid-render.
 		idx, err := strconv.Atoi(strings.Trim(m, rcSpanMark))
-		if err != nil || idx < 0 || idx >= len(spans) {
+		if err != nil || idx >= len(spans) {
 			return ""
 		}
 		return spans[idx]
@@ -194,10 +202,18 @@ var (
 	// against a fixed list rather than a generic identifier shape, which is
 	// what lets autolinks (<https://…>, <user@host>) and prose angle brackets
 	// (Vec<String>, a < b) through untouched — an unknown name is left as
-	// written, the honest degradation.
-	rcHTMLTagRe = regexp.MustCompile(`(?is)</?(?:` + strings.Join(rcHTMLNames, "|") + `)\b(?:\s[^<>]*)?/?>`)
+	// written, the honest degradation. The trailing \b on the name is what makes
+	// the alternation order-independent: Go's regexp picks the leftmost-FIRST
+	// branch, so without it "a" would claim "<abbr>" and leave "br>" behind.
+	rcHTMLTagRe = regexp.MustCompile(`(?is)</?(?:` + strings.Join(rcHTMLNames, "|") + `)\b` + rcTagAttrs + `/?>`)
 )
 
+// rcTagAttrs matches the attribute part of an HTML tag. Quoted values are
+// matched whole, because a flat [^<>]* ends the tag at the first ">" it sees —
+// including one inside a value, which left `<img alt="a > b" src="x.png">`
+// rendering as ` b" src="x.png">`.
+const rcTagAttrs = `(?:\s(?:"[^"]*"|'[^']*'|[^<>"'])*)?`
+
 // rcHTMLNames is the tag allowlist for rcHTMLTagRe: the elements READMEs
 // actually use. The bodied names appear here too, so a stray closing tag left
 // by an unbalanced <picture> is still cleaned up.
@@ -217,7 +233,7 @@ var rcHTMLNames = []string{
 func rcCompileBodyElems(names ...string) []*regexp.Regexp {
 	res := make([]*regexp.Regexp, 0, len(names))
 	for _, n := range names {
-		res = append(res, regexp.MustCompile(`(?is)<`+n+`\b[^<>]*>.*?</`+n+`\s*>`))
+		res = append(res, regexp.MustCompile(`(?is)<`+n+`\b`+rcTagAttrs+`>.*?</`+n+`\s*>`))
 	}
 	return res
 }
@@ -226,11 +242,19 @@ func rcCompileBodyElems(names ...string) []*regexp.Regexp {
 // mdLinkRe — the same grammar fact, a different consumer.
 var (
 	// A link-reference definition line: pure metadata, and after image removal
-	// and link unwrapping nothing points at it any more.
-	rcLinkDefRe = regexp.MustCompile(`^[ \t]{0,3}\[([^\]]+)\]:[ \t]*\S`)
-
-	rcRefImageRe = regexp.MustCompile(`!\[([^\]]*)\]\[([^\]]*)\]`)
-	rcRefLinkRe  = regexp.MustCompile(`\[([^\]]*)\]\[([^\]]*)\]`)
+	// and link unwrapping nothing points at it any more. Deleting a line of
+	// someone's README is the most destructive thing this pass does, so the
+	// shape is strict — a single-token destination (or an <angle> one) and at
+	// most a quoted title, nothing else. A looser "[label]: <non-space>" ate
+	// "[1]: first item explained", an ordinary line of prose.
+	rcLinkDefRe = regexp.MustCompile(`^[ \t]{0,3}\[([^\]]+)\]:[ \t]*(?:<[^<>]*>|\S+)(?:[ \t]+(?:"[^"]*"|'[^']*'|\([^()]*\)))?[ \t]*$`)
+
+	// The reference forms, [text][label] and ![alt][label], plus their collapsed
+	// [text][] variants whose label is the text. Gated on a declared label for
+	// the same reason the shortcut form below is: ungated, prose carrying two
+	// bracket pairs in a row — "the value arr[i][j] is used" — came out as
+	// "the value arri is used".
+	rcRefRe = regexp.MustCompile(`(!?)\[([^\]]*)\]\[([^\]]*)\]`)
 
 	// The shortcut form, [label] with the definition supplying the URL. It runs
 	// last, when every bracketed construct with a destination is already gone,
@@ -238,6 +262,11 @@ var (
 	// "[x]" or a prose "[experimental]" would lose its brackets.
 	rcShortcutRe = regexp.MustCompile(`(!?)\[([^\]]*)\]`)
 
+	// A setext underline, kept for one job only: dropping the one left orphaned
+	// when removal emptied the title above it. Only the "=" form — a "-" run is
+	// equally a thematic break, and leaving it renders a rule either way.
+	rcSetextRe = regexp.MustCompile(`^[ \t]{0,3}=+[ \t]*$`)
+
 	// A leading block marker, stripped only to ask "did removal leave this line
 	// with nothing to say?". The heading and list forms require whitespace (or
 	// end of line) after the marker, so a "#hashtag" keeps its text and a "---"
@@ -320,16 +349,38 @@ func cleanReadmeMarkdown(s string) string {
 	// here keeps a direct caller from smuggling a placeholder into the restore
 	// table.
 	s = strings.ReplaceAll(s, rcSpanMark, "")
+	// CRLF is normalized for markdownToLines' reason, and this pass needs it
+	// just as badly: a "```\r" closing fence never matches rcFenceCloseRe, so
+	// the first fence protects everything to EOF and nothing is cleaned at all.
+	// Production is safe (cleanTerminalOutput drops \r first) but every test
+	// calls this function directly, which is exactly the path that broke.
+	s = strings.ReplaceAll(s, "\r\n", "\n")
+	s = strings.ReplaceAll(s, "\r", "\n")
 
 	segs := rcSegments(s)
+
+	// Two phases, because the label set has to be right before a single line is
+	// rewritten. Masking and the segment-wide HTML rules run first — collecting
+	// labels ahead of them let a "[x]: url" commented out with <!-- --> gate the
+	// unwrapping, and eat the task-list "[x]" the gate exists to protect.
+	spans := make([][]string, len(segs))
+	for i, seg := range segs {
+		if seg.protected {
+			continue
+		}
+		masked, sp := rcMaskSpans(seg.text)
+		segs[i].text = rcStripHTML(masked)
+		spans[i] = sp
+	}
+
 	labels := rcDefinedLabels(segs)
-	out := make([]string, 0, len(segs))
-	for _, seg := range segs {
+	out := make([]string, len(segs))
+	for i, seg := range segs {
 		if seg.protected {
-			out = append(out, seg.text)
+			out[i] = seg.text
 			continue
 		}
-		out = append(out, rcCleanSegment(seg.text, labels))
+		out[i] = rcUnmaskSpans(rcCollapseBlankRuns(rcCleanLines(seg.text, labels)), spans[i])
 	}
 	return strings.Join(out, "\n")
 }
@@ -343,8 +394,12 @@ func rcDefinedLabels(segs []rcSegment) map[string]bool {
 		if seg.protected {
 			continue
 		}
-		for _, line := range strings.Split(seg.text, "\n") {
-			if m := rcLinkDefRe.FindStringSubmatch(line); m != nil {
+		lines := strings.Split(seg.text, "\n")
+		for i, isDef := range rcDefinitionLines(lines) {
+			if !isDef {
+				continue
+			}
+			if m := rcLinkDefRe.FindStringSubmatch(lines[i]); m != nil {
 				labels[rcNormalizeLabel(m[1])] = true
 			}
 		}
@@ -352,22 +407,34 @@ func rcDefinedLabels(segs []rcSegment) map[string]bool {
 	return labels
 }
 
+// rcDefinitionLines marks which lines are link-reference definitions. Matching
+// the shape is not enough: CommonMark forbids a definition from interrupting a
+// paragraph, so a line only counts when what sits above it is the start of the
+// segment, a blank line, or another definition. Without that rule a paragraph
+// reading "Some prose here / [note]: this matters / more prose" silently lost
+// its middle line.
+func rcDefinitionLines(lines []string) []bool {
+	defs := make([]bool, len(lines))
+	inParagraph := false
+	for i, line := range lines {
+		switch {
+		case strings.TrimSpace(line) == "":
+			inParagraph = false
+		case !inParagraph && rcLinkDefRe.MatchString(line):
+			defs[i] = true
+		default:
+			inParagraph = true
+		}
+	}
+	return defs
+}
+
 // rcNormalizeLabel folds a reference label the way CommonMark matches them:
 // case-insensitively, with internal whitespace collapsed.
 func rcNormalizeLabel(s string) string {
 	return strings.ToLower(strings.Join(strings.Fields(s), " "))
 }
 
-// rcCleanSegment applies every removal rule to one cleanable segment, with
-// inline code spans masked out for the duration.
-func rcCleanSegment(s string, labels map[string]bool) string {
-	masked, spans := rcMaskSpans(s)
-	masked = rcStripHTML(masked)
-	masked = rcCleanLines(masked, labels)
-	masked = rcCollapseBlankRuns(masked)
-	return rcUnmaskSpans(masked, spans)
-}
-
 // rcStripHTML runs the segment-wide HTML rules. Comments go first: a script or
 // style body may well contain "-->" and would otherwise cut a comment short.
 func rcStripHTML(s string) string {
@@ -382,14 +449,23 @@ func rcStripHTML(s string) string {
 }
 
 // rcCleanLines applies the per-line rules and drops what removal emptied. Both
-// the tidy-up and the drop are gated on the line having actually changed, so an
-// untouched line keeps its trailing spaces (a hard line break) and a "- - -"
-// thematic break is never mistaken for an emptied bullet.
+// the tidy-up and the drop are gated on the line having actually changed, so a
+// "- - -" thematic break is never mistaken for an emptied bullet.
 func rcCleanLines(s string, labels map[string]bool) string {
 	lines := strings.Split(s, "\n")
+	defs := rcDefinitionLines(lines)
 	out := make([]string, 0, len(lines))
-	for _, line := range lines {
-		if rcLinkDefRe.MatchString(line) {
+	// A setext title is two lines, and removal only ever empties the first;
+	// without this the underline outlives it as a visible row of equals signs.
+	dropUnderline := false
+	for i, line := range lines {
+		if dropUnderline {
+			dropUnderline = false
+			if rcSetextRe.MatchString(line) {
+				continue
+			}
+		}
+		if defs[i] {
 			continue
 		}
 		cleaned := rcCleanLine(line, labels)
@@ -399,6 +475,7 @@ func rcCleanLines(s string, labels map[string]bool) string {
 		}
 		cleaned = rcTidyLine(line, cleaned)
 		if rcLineContent(cleaned) == "" {
+			dropUnderline = true
 			continue
 		}
 		out = append(out, cleaned)
@@ -413,14 +490,36 @@ func rcCleanLines(s string, labels map[string]bool) string {
 // link is reduced to its text first and the pictograph is then found there.
 func rcCleanLine(line string, labels map[string]bool) string {
 	line = mdImageRe.ReplaceAllString(line, "")
-	line = rcRefImageRe.ReplaceAllString(line, "")
 	line = mdLinkRe.ReplaceAllString(line, "$1")
-	line = rcRefLinkRe.ReplaceAllString(line, "$1")
+	line = rcUnwrapRefs(line, labels)
 	line = rcUnwrapShortcuts(line, labels)
 	line = rcStripEmoji(line)
 	return rcStripShortcodes(line)
 }
 
+// rcUnwrapRefs resolves [text][label] and ![alt][label] — and the collapsed
+// [text][] form, whose label is its own text — for declared labels only. An
+// undeclared one is left as written, which is also what a browser shows.
+func rcUnwrapRefs(s string, labels map[string]bool) string {
+	if len(labels) == 0 || !strings.Contains(s, "][") {
+		return s
+	}
+	return rcRefRe.ReplaceAllStringFunc(s, func(m string) string {
+		g := rcRefRe.FindStringSubmatch(m)
+		label := g[3]
+		if strings.TrimSpace(label) == "" {
+			label = g[2]
+		}
+		if !labels[rcNormalizeLabel(label)] {
+			return m
+		}
+		if g[1] == "!" {
+			return ""
+		}
+		return g[2]
+	})
+}
+
 // rcUnwrapShortcuts resolves the [label] form for declared labels only.
 func rcUnwrapShortcuts(s string, labels map[string]bool) string {
 	if len(labels) == 0 || !strings.Contains(s, "[") {
@@ -442,23 +541,39 @@ func rcUnwrapShortcuts(s string, labels map[string]bool) string {
 // the ORIGINAL line, not the cleaned one: list nesting depends on it, while a
 // leading "🚀 " that removal turned into a space would otherwise become an
 // indent the author never wrote — four of them and markdown reads the line as
-// an indented code block.
+// an indented code block. A hard line break is carried over for the same
+// reason: two trailing spaces are markup, and removal inside the line has no
+// business retiring them.
 func rcTidyLine(orig, cleaned string) string {
 	indent := orig[:len(orig)-len(strings.TrimLeft(orig, " \t"))]
 	body := strings.TrimSpace(cleaned)
-	return indent + rcInnerSpacesRe.ReplaceAllString(body, " ")
+	if body == "" {
+		return indent
+	}
+	body = rcInnerSpacesRe.ReplaceAllString(body, " ")
+	if strings.HasSuffix(orig, "  ") {
+		body += "  "
+	}
+	return indent + body
 }
 
 // rcLineContent strips leading block markers so the caller can ask whether a
 // line still says anything. "## 🚀" cleans to "##", which is a heading with no
 // content — glamour would render it as a styled blank row.
+//
+// The loop slices rather than calling ReplaceAllString, and that is not a
+// micro-optimization: the pattern is ^-anchored, so each replace could only
+// ever rewrite the head, yet it copied the whole remaining line every pass.
+// One line of "🚀 " + 262144 "- " markers — a 512 KiB README, exactly the cap
+// version.getReadme enforces — took 8.4 s of a synchronous Update(), i.e. the
+// whole TUI frozen on untrusted remote input. Slicing makes it linear.
 func rcLineContent(line string) string {
 	for {
-		next := rcBlockMarkerRe.ReplaceAllString(line, "")
-		if next == line {
+		loc := rcBlockMarkerRe.FindStringIndex(line)
+		if loc == nil {
 			break
 		}
-		line = next
+		line = line[loc[1]:]
 	}
 	return strings.TrimSpace(line)
 }
diff --git a/internal/model/readme_clean_test.go b/internal/model/readme_clean_test.go
index 3f84d72..da6ffa9 100644
--- a/internal/model/readme_clean_test.go
+++ b/internal/model/readme_clean_test.go
@@ -3,6 +3,7 @@ package model
 import (
 	"strings"
 	"testing"
+	"time"
 )
 
 // segJoin reassembles what rcSegments split, which must reproduce the input
@@ -252,6 +253,44 @@ func TestCleanReadmeMarkdownImagesAndLinks(t *testing.T) {
 			in:   "## [Installation](#installation)\n",
 			want: "## Installation\n",
 		},
+		{
+			// A flat "[^)]*" destination stopped at the inner ")" and left the
+			// rest of the URL on screen — the exact noise this pass removes.
+			name: "badge url carrying parentheses goes whole",
+			in:   "![alt](https://img.shields.io/badge/a-(b)-blue.svg)\n",
+			want: "",
+		},
+		{
+			name: "link url carrying parentheses",
+			in:   "See [Foo](https://en.wikipedia.org/wiki/Foo_(bar)) here.\n",
+			want: "See Foo here.\n",
+		},
+		{
+			name: "ten-badge header folds to one blank line",
+			in:   "# T\n\n![a](x)\n![b](y)\n![c](z)\n\nbody\n",
+			want: "# T\n\nbody\n",
+		},
+		{
+			// Two trailing spaces are markup; a removal inside the line has no
+			// business retiring them.
+			name: "hard line break survives a removal",
+			in:   "see [docs](https://example.com)  \nsecond\n",
+			want: "see docs  \nsecond\n",
+		},
+		{
+			// Removal empties the title, and the underline must go with it
+			// rather than staying behind as a row of equals signs.
+			name: "orphaned setext underline goes with its title",
+			in:   "\U0001F680\n=====\n\nbody\n",
+			want: "\nbody\n",
+		},
+		{
+			// A stray backtick must not pair with one further down and exempt
+			// everything between from cleaning.
+			name: "stray backtick does not protect the rest of the document",
+			in:   "stray ` here\n\n![b](https://b.svg)\n\ntail\n",
+			want: "stray ` here\n\ntail\n",
+		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
@@ -313,6 +352,21 @@ func TestCleanReadmeMarkdownHTML(t *testing.T) {
 			in:   "first<br>\nsecond\n",
 			want: "first\nsecond\n",
 		},
+		{
+			// A flat [^<>]* ends the tag at the ">" inside the quoted value and
+			// leaves the tail of the tag on screen.
+			name: "attribute value carrying a greater-than",
+			in:   "<img alt=\"a > b\" src=\"x.png\">\n\n# Title\n",
+			want: "\n# Title\n",
+		},
+		{
+			// The label set is collected AFTER the HTML rules run: gathering it
+			// first let a commented-out definition gate the unwrapping and eat
+			// the task-list bracket the gate exists to protect.
+			name: "label declared inside a comment gates nothing",
+			in:   "<!--\n[x]: https://example.com\n-->\n\n- [x] done\n",
+			want: "\n- [x] done\n",
+		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
@@ -434,6 +488,12 @@ func TestCleanReadmeMarkdownLeavesContentAlone(t *testing.T) {
 		{"bmp symbols a terminal font carries", "✓ done ★ starred → next\n"},
 		{"task list brackets", "- [x] done\n- [ ] todo\n"},
 		{"undeclared shortcut label", "marked [experimental] for now\n"},
+		{"undeclared reference link", "see [text][nope] here\n"},
+		// Two bracket pairs in a row are an array index far more often than a
+		// reference link, which is why the reference form is label-gated too.
+		{"array index in prose", "the value arr[i][j] is used\n"},
+		{"definition-shaped line inside a paragraph", "Some prose here\n[note]: this matters\nmore prose\n"},
+		{"numbered prose line", "[1]: first item explained\n"},
 		{"thematic break", "above\n\n- - -\n\nbelow\n"},
 		{"issue reference", "#123 fixed the crash\n"},
 		{"hard line break", "first  \nsecond\n"},
@@ -448,6 +508,44 @@ func TestCleanReadmeMarkdownLeavesContentAlone(t *testing.T) {
 	}
 }
 
+// CRLF is normalized on entry. Without it a "```\r" closing fence never
+// matches, the first fence protects everything to EOF, and nothing is cleaned
+// at all — invisible to a suite that only ever feeds LF.
+func TestCleanReadmeMarkdownNormalizesCRLF(t *testing.T) {
+	const lf = "# T\n\n```go\ncode\n```\n\n![b](https://b.svg)\n\ntail\n"
+	crlf := strings.ReplaceAll(lf, "\n", "\r\n")
+
+	want := cleanReadmeMarkdown(lf)
+	if got := cleanReadmeMarkdown(crlf); got != want {
+		t.Errorf("CRLF input\n = %q\nwant the LF result %q", got, want)
+	}
+	if strings.Contains(want, "b.svg") {
+		t.Fatalf("fixture is not exercising the badge removal: %q", want)
+	}
+}
+
+// The pass runs synchronously inside Update() on up to readmeMaxBytes of
+// untrusted remote markdown, so a pathological input must not freeze the TUI.
+// The shape that did: one line of leading block markers, which made
+// rcLineContent copy the remaining line once per marker — 8.4 s at the cap.
+func TestCleanReadmeMarkdownPathologicalInputIsFast(t *testing.T) {
+	const budget = 2 * time.Second
+	inputs := map[string]string{
+		"leading bullets":  "\U0001F680 " + strings.Repeat("- ", 262144),
+		"leading quotes":   "\U0001F680 " + strings.Repeat("> ", 262144),
+		"leading headings": "\U0001F680 " + strings.Repeat("# ", 262144),
+	}
+	for name, in := range inputs {
+		t.Run(name, func(t *testing.T) {
+			start := time.Now()
+			cleanReadmeMarkdown(in)
+			if elapsed := time.Since(start); elapsed > budget {
+				t.Errorf("%d bytes took %v, want under %v", len(in), elapsed, budget)
+			}
+		})
+	}
+}
+
 // The NUL sentinel cannot reach the pass in production (cleanTerminalOutput
 // drops every control character), and a direct caller must not be able to
 // smuggle a placeholder into the restore table either.
diff --git a/internal/model/readme_style_test.go b/internal/model/readme_style_test.go
index 94185d2..33ce6f9 100644
--- a/internal/model/readme_style_test.go
+++ b/internal/model/readme_style_test.go
@@ -121,11 +121,13 @@ func TestKeepkitStyleLeavesGlobalsUntouched(t *testing.T) {
 // content, not styling.
 func TestRenderReadmeHouseStyle(t *testing.T) {
 	tests := []struct {
-		name    string
-		raw     string
-		want    []string
-		absent  []string
-		noEmpty bool
+		name   string
+		raw    string
+		want   []string
+		absent []string
+		// sameLine[0] must render on the same line as sameLine[1] — the only way
+		// to pin a table cell's content against glamour's footnote layout.
+		sameLine [2]string
 	}{
 		{
 			name:   "link keeps its text and drops the href",
@@ -145,6 +147,16 @@ func TestRenderReadmeHouseStyle(t *testing.T) {
 			raw:  "Read <https://example.com/docs> first.\n",
 			want: []string{"https://example.com/docs"},
 		},
+		{
+			// What WithInlineTableLinks is actually for: the preprocessor
+			// unwrapped every inline link already, so only an autolink can still
+			// reach a cell — and without the option glamour moves it to a
+			// numbered footnote under the table instead of leaving it in place.
+			name:     "table autolink stays in its cell",
+			raw:      "| topic | where |\n|---|---|\n| usage | <https://example.com/m> |\n",
+			want:     []string{"https://example.com/m"},
+			sameLine: [2]string{"usage", "https://example.com/m"},
+		},
 		{
 			name: "bare url survives",
 			raw:  "Read https://example.com/docs first.\n",
@@ -169,6 +181,17 @@ func TestRenderReadmeHouseStyle(t *testing.T) {
 		},
 	}
 	for _, tt := range tests {
+		// The double-space check belongs on the preprocessed source, where a
+		// removal artifact would live — glamour pads table cells with runs of
+		// spaces of its own, which is layout, not residue. It is also
+		// background-independent, so it runs once rather than per variant.
+		t.Run(tt.name+"/no removal residue", func(t *testing.T) {
+			for _, line := range strings.Split(cleanReadmeMarkdown(cleanTerminalOutput(tt.raw)), "\n") {
+				if strings.Contains(strings.TrimSpace(line), "  ") {
+					t.Errorf("removal left a double space: %q", line)
+				}
+			}
+		})
 		for _, dark := range []bool{true, false} {
 			name := tt.name + "/light"
 			if dark {
@@ -186,20 +209,24 @@ func TestRenderReadmeHouseStyle(t *testing.T) {
 						t.Errorf("unexpected %q\n--- rendered ---\n%s", a, plain)
 					}
 				}
-				// The double-space check belongs on the preprocessed source,
-				// where a removal artifact would live — glamour pads table
-				// cells with runs of spaces of its own, which is layout, not
-				// residue.
-				for _, line := range strings.Split(cleanReadmeMarkdown(cleanTerminalOutput(tt.raw)), "\n") {
-					if strings.Contains(strings.TrimSpace(line), "  ") {
-						t.Errorf("removal left a double space: %q", line)
-					}
+				if tt.sameLine[0] != "" && !sharesLine(plain, tt.sameLine[0], tt.sameLine[1]) {
+					t.Errorf("%q and %q are not on one line\n--- rendered ---\n%s", tt.sameLine[0], tt.sameLine[1], plain)
 				}
 			})
 		}
 	}
 }
 
+// sharesLine reports whether some line of s carries both needles.
+func sharesLine(s, a, b string) bool {
+	for _, line := range strings.Split(s, "\n") {
+		if strings.Contains(line, a) && strings.Contains(line, b) {
+			return true
+		}
+	}
+	return false
+}
+
 // A README that is nothing but badges and HTML cleans down to nothing, and an
 // empty render is what makes readmeContent fall through to the friendly
 // "No README for <name>. Press [h] for --help." placeholder.
diff --git a/internal/model/textutil.go b/internal/model/textutil.go
index 59197c8..0c81010 100644
--- a/internal/model/textutil.go
+++ b/internal/model/textutil.go
@@ -158,9 +158,17 @@ func wrapLine(line string, width int) []string {
 // CommonMark flanking rule in miniature), so "2 * 3 * 4" keeps its asterisks;
 // the underscore pair additionally requires a non-word rune outside both
 // delimiters, or an identifier like update_cmd would lose its underscore.
+// mdDest matches an inline link destination. It allows ONE level of nested
+// parentheses, which is what a flat "[^)]*" got wrong: a shields.io badge
+// (…/badge/a-(b)-blue.svg) or a Wikipedia article (…/wiki/Foo_(bar)) stopped at
+// the inner ")" and left the rest of the URL on screen as text. Deeper nesting
+// needs recursion, which RE2 does not have; an unbalanced "(" matches nothing
+// and the construct is left as written.
+const mdDest = `[^()]*(?:\([^()]*\)[^()]*)*`
+
 var (
-	mdImageRe    = regexp.MustCompile(`!\[([^\]]*)\]\([^)]*\)`)
-	mdLinkRe     = regexp.MustCompile(`\[([^\]]*)\]\([^)]*\)`)
+	mdImageRe    = regexp.MustCompile(`!\[([^\]]*)\]\(` + mdDest + `\)`)
+	mdLinkRe     = regexp.MustCompile(`\[([^\]]*)\]\(` + mdDest + `\)`)
 	mdAutolinkRe = regexp.MustCompile(`<((?:https?|ftp|mailto):[^>\s]+)>`)
 	mdHTMLTagRe  = regexp.MustCompile(`<[^<>]*>`)