# Brand + themes: the Found-line mark, and base × accent

Status: SHIPPED to main 2026-09-25 (S0 `7c9e3bdf`, S1 `575ae1d4`, S2 `b9772e53`, S3 `85cf6e81` + its
`plans:` records), not rolled out. Worked on `brand/found-line` (worktree `../brand-found-line`,
pnpm wt block #1), with S1 and S2 as `brand/mark` and `brand/themes` off S0's tip. The release is
[`release-10.md`](release-10.md); the operator's runbook is `~/reports/release-10/RUNBOOK.html`.
S4 (Archilyzer Media, the YouTube channel) was built after the release-10 cut on `brand/media`
(worktree `../brand-media`, block #3) and is not part of the site rollout; see "Slice S4, as shipped".

Design canvas: https://claude.ai/artifact/UsUxwgRkP5a3m4jZXucAvG (boards *Family*, *In context*,
*Themes · base × accent*, and the rejected directions A–C). Read it with Artifact
`action:"read"`; republish by staging under the primary checkout's gitignored
`node_modules/.brand-canvas/project/` (Artifact publish only accepts paths inside the repo).
**Where this plan and the canvas differ, the plan wins** — notably the contrast-corrected
on-light and on-sepia accent values below.

## What the operator asked for (2026-09-25)

1. One logo and brand for Archilyzer and every official child site.
2. A reader theme made of two independent choices: a **base** (Light / Sepia / Dark, plus
   System) and an **accent**. Every site defaults to its own accent; a reader can pick any other.

## Decisions (final)

- **Mark D · Found line.** Four transcript lines on a rounded square; the second is lit and
  carries a play head.
- **The wordmark splits on the subject's name,** not on "lyzer".
- **The dark base is warm ink,** not graphite.
- **Accent swaps:** Anilyzer takes Sakura and Jasolyzer takes Green, because Archilyzer keeps
  its teal ("Signal").
- **All five theme families retire:** base, archive, selenized, swiss and archilyzer.
- **No new dependencies expected.** `rsvg-convert`, `magick` and `inkscape` are on the machine,
  and `next/og` bundles satori and resvg. sharp's native build failed in the worktree; nothing
  here needs it.

## The design (source of truth)

### Mark

Everything is in a 512 viewBox. The shapes, back to front:

| Part | Shape | Colour |
|---|---|---|
| ground | rect, `rx=112` | ground |
| line 1 | rect x112 y128 w288 h44 rx22 | dim |
| play head | polygon `112,210 172,234 112,258` | lit |
| line 2 (the found line) | rect x188 y212 w212 h44 rx22 | lit |
| line 3 | rect x112 y296 w232 h44 rx22 | dim |
| line 4 | rect x112 y380 w152 h44 rx22 | dim |

Icon palettes:
- **Child site:** ground `#0c0a08`, dim `#6b5d47`, lit = the site accent's on-dark value.
- **Archilyzer** (homepage, hub, editor): ground `#151b20`, dim `#586977`, lit `#e7edf1`
  (bone). The parent mark is achromatic.

The dims were raised on 2026-09-27 (release 10, slice MC; `release-10.md`), from `#3b3327` (1.59:1
on ink) and `#3f4c56` (1.97:1 on slate), which the operator found too faint: on the dark base the
ink tile merges into the page and the mark read as one lit line. Two rules now hold every icon
palette (`brand.ts`, enforced in `brand.test.ts`): **a dim reaches 3:1 on its ground** (WCAG
1.4.11) and **every named lit value stands 2:1 above its dim**. The new dims keep the old hue and
saturation and sit just over 3:1 (3.09, 3.06), because the two rules multiply to lit-on-ground and
the darkest lit values leave little room: Vermilion is 2.28:1 over the child dim, and Signal on
the Media slate 2.05:1.

**On the dark base the in-page mark's tile has a 1px ring** (2026-09-28, release 10, slice MR;
`release-10.md`): the operator asked for "a thin outline to the tile on dark", because the child's
ink tile is the dark page itself and the slate is 1.14:1 on it. `BrandMark` draws it outside the
tile, following its corner (`border-radius` 21.875% = rx 112 of 512), in the palette's own dim
(`#6b5d47`, `#586977`: 3.09:1 and 3.48:1 on the ink page), as a box-shadow under `.dark` only, so no
layout moves and light and sepia are unchanged. The icon files carry no ring.

**Under forced colours the tile has a 1px `CanvasText` outline, on every base** (2026-09-28,
release 11, slice O2; `release-11.md`): the reader's Canvas replaces the page there and may be as
dark as the tile. Same place and corner as the ring (outline offset 0); outside forced colours the
classes match nothing, and the marks render pixel-identical on light, sepia and dark.

Icon variants:
- `any`: `rx=112`.
- `maskable`: full-bleed ground, the mark scaled 0.8 about (256,256).
- `apple`: full-bleed ground at scale 1.

### Wordmark

Archivo at `font-stretch:118%`. The lead is weight 720 in `--foreground`; the suffix is weight
380 in `--muted-foreground`. Two adjacent spans with no whitespace between them; the link's
accessible name is the full title.

| Site | Lead | Suffix |
|---|---|---|
| Archilyzer | Archi | lyzer |
| Jeralyzer | Jer | alyzer |
| Rekietalyzer | Rekieta | lyzer |
| Hasanalyzer | Hasan | alyzer |
| Anilyzer | Ani | lyzer |
| Bonnellyzer | Bonnell | yzer |
| Jasolyzer | Jaso | lyzer |

### Accents

The on-light and on-sepia values are contrast-corrected: each must reach ≥4.5:1 against its
ground and with white ink. A unit test enforces it.

| id | Name | Site default | On dark | On light | On sepia |
|---|---|---|---|---|---|
| `signal` | Signal | Archilyzer (homepage, hub, editor) | `#5fa8a0` | `#2e7b73` | `#2b756e` |
| `brass` | Brass | jeralyzer | `#e3b15c` | `#95661a` | `#8e6119` |
| `vermilion` | Vermilion | rekietalyzer | `#ec7a52` | `#b3431f` | `#b3431f` |
| `violet` | Violet | hasanalyzer | `#b49cf2` | `#6a4bc4` | `#6a4bc4` |
| `sakura` | Sakura | anilyzer | `#ee8fb5` | `#a83a6a` | `#a83a6a` |
| `blue` | Blue | bonnellyzer | `#74a9f2` | `#2d5fb8` | `#2d5fb8` |
| `green` | Green | jasolyzer | `#7cc46a` | `#3f7a2c` | `#3d772b` |

### Bases

Each base declares all 48 colour tokens listed in `homepage/e2e/theme.spec.ts:63-112`, plus
`color-scheme`. (2026-09-28: 50 now — `REQUIRED_TOKENS` in `common/components/themeConfig.ts`, which
the spec reads; `--chart-6` came in release 11, slice O2. Each base also declares the non-colour
flags `--base-light|sepia|dark`.)

| Base | Source | Values |
|---|---|---|
| Light | today's `archilyzer` light block | bg `#f3f6f7`, surface `#e8edef`, fg `#161c21`, muted-fg `#55646e`, border `#d2dade`, border-strong `#aeb9c0`, faint `#78868f` |
| Sepia | new | bg `#f4ecd8`, card `#faf4e6`, fg `#33281a`, muted-fg `#6b5c43`, border `#dccdaa` |
| Dark | today's `archive` dark (ink) | bg `#0c0a08`, surface `#141009`, fg `#efe7d8`, muted-fg `#a39a86`, border `rgba(233,220,197,.1)` |

- **Sepia** derives its status, panel and chart values from the archive paper block, darkened
  for a light ground.
- **Dark** adds the `--destructive-soft` and `--state-gone(-soft)` it lacks today.
- **Charts do not follow the accent:** each base has its own fixed `--chart-1..5` (`--chart-6`, a
  rust, since release 11: light and sepia `#823c10`, dark `#a54a08`; `release-11.md`, slice O2). Re-validate
  chart-3 against `--state-gone` with the dataviz skill's validator (FACTS.md ~6442 records a
  real past collision), and keep chart-1 ≠ Signal.

### Type and radius

Three faces everywhere:
- Archivo as `--font-display`, with the `wdth` axis. `.font-display` gets `font-stretch:112%`.
- IBM Plex Sans as `--font-sans`, weights 400–700, normal + italic.
- IBM Plex Mono as `--font-mono`.

`--radius: 0.375rem` on `:root`.

## Slices

```
S0 palette + data ──┬──> S1 brand (mark, icons, wordmark) ──┐
                    └──> S2 themes (tokens, runtime, picker) ┴──> S3 integrate + gates ──> operator rollout
```

Cadence: the planner/reviewer orchestrates; one Opus general-purpose implementer per slice
writes the code, under [`tools/implementer-rules.md`](tools/implementer-rules.md). S1 and S2 run
as two parallel implementers, each in its own worktree cut from S0's tip
(`pnpm wt add brand/mark --from brand/found-line`, `pnpm wt add brand/themes --from brand/found-line`).
Review fixes go back to the same agent. Sonnet or Haiku do exploration and extraction.

**Conflict avoidance between S1 and S2:**
- In `export/app/layout.tsx` and `homepage/app/layout.tsx`, S1 edits only the `icons` metadata;
  S2 edits only the theme constants, `generateViewport` and the `RootLayout` `<html>`.
- `Header.tsx` and `Footer.tsx` belong to S1; `ThemeMenu`, `MobileMenu` and `ThemeToggle` belong
  to S2.
- S1 colours the header mark with `var(--brand-mark, var(--brand))`, so it works before S2 lands.
- S1 puts new assertions in a new `export/e2e/brand.spec.ts`; S2 owns
  `site-branding.spec.ts:75-86`.
- Whichever of S1/S2 merges second merges `main` and re-gates.
- Release 9 slice C2 (`one-core/c2-federated-search`) is in flight on the hub search
  components; neither slice touches `SearchResults.tsx`, `FiltersPanel.tsx` or
  `ArchiveShelf.tsx` (they receive hexes and keep working unchanged).

### S0 — palette + data (`brand/found-line`, alone)

**New `common/lib/brand.ts` (pure):**
- `ACCENT_IDS` and an `ACCENTS` table, `{id, name, onDark, onLight, onSepia}` per accent.
- `DEFAULT_ACCENT = "signal"`.
- `BASE_GROUNDS = {light: "#f3f6f7", sepia: "#f4ecd8", dark: "#0c0a08"}`.
- `ICON_PALETTES` for child sites and for Archilyzer.
- The `MARK` shape list and `markSvg(palette, {variant})`.
- `splitWordmark(title, lead?)`.

`common/lib/project.ts` gains `PROJECT_WORDMARK_LEAD = "Archi"`.

**`common/lib/accent.ts`:**
- Keep `parseAccent`.
- Add `parseAccentSetting(v)`: an accent id, a `"#rrggbb"`, or undefined.
- Add `resolveAccent(v)`: `{id | "custom", light, sepia, dark}`. A custom hex is darkened or
  lightened per ground until it reaches 4.5:1.
- Add `accentHex(v)`. The published value is always a hex: an id becomes its on-dark value.
- Add `customAccentVars()`.
- `siteAccentVars` is deleted in S2.

**`common/lib/siteSchema.ts`:**
- `accent` parses through `parseAccentSetting` (around :238, :302, :321), with new doc text
  (:110).
- New optional `wordmarkLead`, after `headerTitle`. Stored only when it is a proper prefix of
  `headerTitle`; needs type, `SITE_FIELD_DOCS`, schema and `siteToDisk` entries.
- Regenerate SITE.md: `pnpm --filter yt-dlp-transcript-common exec tsx bin/file-schemas-docs.ts`,
  checked with `--check`.

**The published accent stays a hex.** Third-party hubs read other sites' `/site.json`, so these
route through `accentHex`:
- `common/lib/siteDescriptor.ts:~87`
- `common/bin/compose-hub.ts:~94`
- `common/lib/homepageSummary.ts:~431`

**Editor form** (`editor/app/sites/components/SiteForm.tsx:229-234`,
`editor/app/sites/actions.ts:~45-51,169-191`):
- "Brand accent" becomes a native radio group of the 7 swatches plus "Custom", with a hex field.
- A "Wordmark lead" field. The single writer is `writeSite` in `common/lib/site.ts`.
- `Field` puts the hint inside the `<label>`, so the new labels and hints must not contain
  "header title", "site title", "site id" or "public url" — `sites-crud`'s `getByLabel` would hit
  strict-mode violations.
- `hubSite()` (`export/app/lib/site.ts:~29`) sets `wordmarkLead: PROJECT_WORDMARK_LEAD`.

**Tests:** `brand.test.ts` (contrast ≥4.5 everywhere, `markSvg` geometry); `accent.test.ts`; a
siteSchema round-trip with an id and `wordmarkLead`; siteDescriptor publishes a hex for an id;
`fileSchemaDocs.test.ts` passes on the regenerated SITE.md.

**e2e:** editor `sites-crud` and `branding` (the root `pnpm e2e` is the editor suite); export
`site-branding`; `pnpm --filter export run e2e:hub`.

### S1 — mark, icons, wordmark (`brand/mark`)

**Step 1 is a spike, timeboxed to about an hour:**
1. Seed the `export/public` symlinks (implementer-rules.md, under `sh`).
2. Build a PNG icon via `app/icons/[file]/route.ts`.
3. `pnpm --filter export exec next build`.
4. Check `out/icons/icon-192.png`: PNG magic, a 192×192 IHDR, and look at it.
5. Check `out/favicon.ico` starts with `00 00 01 00`.
6. Repeat for the homepage.

**If the spike fails:**
- The PNG route fails: call the same renderer from compose-site / compose-hub /
  compose-homepage and write into `public/icons`. The last resort is `rsvg-convert`.
- Only the ICO fails: check in a `public/favicon.ico` family mark generated once by
  `common/bin/brand-icons.ts`. Next reserves `/favicon.ico` as a metadata route
  (`is-metadata-route.js:114`).

**Static route handlers are safe under static export.** Under `output:"export"` a GET route
handler with `generateStaticParams` is copied byte-for-byte to its exact path
(`next/dist/export/index.js:~722-737`). `app/icon.tsx` is unusable: its URLs are always hashed.

**`common/lib/brandIcons.ts`:**
- `ICON_FILES`: `icon.svg`, `maskable.svg`, `icon-32.png`, `icon-192.png`, `icon-512.png`,
  `maskable-512.png`, `apple-touch-icon.png`.
- `renderIconPng()` — `ImageResponse` from `next/og` on the node runtime, with an `<img>` SVG
  data URI via `createElement`.
- `pngToIco()` — a 6-byte header, 16-byte entries, then the PNG payloads.

**Routes:** `export/app/icons/[file]/route.ts` and a homepage twin.
- `dynamic = "force-static"`, `dynamicParams = false`; never read the request.
- The palette is Archilyzer in hub mode (`instanceMode()`), otherwise the site's resolved accent
  via `currentSite()`.
- Delete `export/public/icons/*`, `homepage/public/icons/*` and both `app/favicon.ico`.
- Metadata declares `icon.svg` (type `image/svg+xml`), `icon-32.png`, 192, 512 and apple.
- The homepage OG image keeps `/icons/icon-512.png`.

**Manifest** (`export/app/manifest.ts`): `theme_color = BASE_GROUNDS.dark`; `background_color` is
the icon ground; add `icon.svg` with sizes "any". `pwa.spec` requires the 192/512/maskable
entries and the four PNG paths.

**Service workers:** in `export/service-worker/site-sw.js:~28` and `sw-hub.js:~20`, rename
**only** the `SHELL` cache to `shell-v2`. Bumping `VERSION` would make activate delete readers'
offline channel downloads.

**Components:**
- New `common/components/BrandMark.tsx`: inline SVG, `aria-hidden`, `focusable="false"`, colours
  through `style`, not `fill="var()"`.
- New `common/components/Wordmark.tsx`.
- `export/app/components/Header.tsx:68-73`: the rotated square becomes an ink tile plus
  `var(--brand-mark)` — the header follows the reader's accent while the favicon keeps the site
  default. The Wordmark uses `site.wordmarkLead`. The hub reuses this header and gets the
  Archilyzer mark.
- `homepage/app/components/Header.tsx:39-51`: the CSS triangle becomes the bone mark, and
  "Archilyzer" becomes the split wordmark, no longer tracked uppercase. Keep
  `aria-label="Archilyzer home"`.
- `export/app/components/Footer.tsx`: a small Archilyzer mark before the credit, outside the
  link. The link's name stays exactly "Archilyzer".
- Editor sidebar (`editor/app/layout.tsx:~133-144`): a mark beside `adminTitle`, not split.
- Editor favicon: a static `editor/app/icon.svg`, with a parity test against `markSvg`.

**Fixture:** `"wordmarkLead":"Fixture"` in `export/e2e/fixtures/sites/testsite/site.json`.

**Tests:** new `export/e2e/brand.spec.ts` (split spans, link name, mark present, footer credit);
`pwa.spec.ts:30-42` adds content-type, PNG magic, `icon.svg` and `favicon.ico`; the hub's
`/icons/icon.svg` contains `#151b20` / `#e7edf1`; unit tests for the ICO header, and the PNG IHDR
if `next/og` runs under tsx.

### S2 — base × accent (`brand/themes`)

**`common/styles/tokens.css`:**
- Keep `@custom-variant dark (&:where(.dark, .dark *))` (:28). `.dark` is on `<html>` iff the
  resolved base is dark, so the 47 `dark:` usages keep working and sepia styles as light.
- Delete every `[data-theme=…]` block, the `.dark{}` token block and the per-family font/radius
  rules (:99-141).
- Base blocks, each declaring all 48 tokens: `:root, html[data-base="light"]`,
  `html[data-base="sepia"]`, `html[data-base="dark"]`. Each also declares:
  - `--swatch-<id>`: that ground's value for each of the 7 accents;
  - `--swatch-custom: var(--accent-custom-<base>, var(--swatch-signal))`;
  - `--brand: var(--swatch-signal)` as the default;
  - `--brand-strong`: `color-mix` toward white on dark, toward black on light/sepia;
  - `--brand-soft`: `color-mix` at 16% on dark, 12% on light/sepia;
  - `--brand-ink`: `#0c0a08` on dark, `#fff` on light/sepia.
- **After** the base blocks (same specificity, so later wins):
  `html[data-accent="<id>"]{--brand:var(--swatch-<id>); --brand-mark:<onDark>}` for each of the
  7, and `html[data-accent="custom"]{--brand:var(--swatch-custom); --brand-mark:var(--accent-custom-dark)}`.
- `--primary` stays **neutral**, not the accent: light `#202a31`, sepia `#33281a`, dark
  `#efe7d8`, each with a ground-coloured foreground. `--ring: var(--brand)`.

**`common/styles/fonts.ts`:** Archivo, Plex Sans and Plex Mono only — Source Serif, Source Sans,
Source Code and JetBrains Mono go. Update the comments in both `globals.css` files.

**`common/components/themeConfig.ts`:**
- `BASE_KEY = "ytdlp-tb:base"`; `ACCENT_KEY` now stores an accent id; `LEGACY_THEME_KEY` /
  `LEGACY_MODE_KEY` are the old theme/mode keys.
- `ThemeBase = light | sepia | dark | system`.
- `REQUIRED_TOKENS`, which the homepage spec imports.
- A pure `migrateLegacy({theme, mode})`, after which both legacy keys are deleted:

  | Stored mode | Result |
  |---|---|
  | light | `light`, or `sepia` when the old theme was `archive` |
  | dark | `dark` |
  | system | `system` |
  | absent | nothing stored |

- `buildThemeScript({defaultBase})`.

**Pre-paint `ThemeScript.tsx`** (replacing :27-56), in this order:
1. Migrate if needed.
2. Validate the base, falling back to the default.
3. Set `data-base` to the resolved light/sepia/dark and toggle `.dark`.
4. Set `data-accent` only from a valid stored id; otherwise the server-rendered default stays.
5. Update `meta[name=theme-color]`.
6. Last: `data-theme-ready="1"`, the e2e no-flash marker.

A unit test runs the script string in `node:vm` over the whole migration matrix.

**`ThemeProvider.tsx`:**
- Props `{defaultBase = "system", siteAccent = DEFAULT_ACCENT}`.
- Context `{base, resolvedBase, isDark, accent, siteAccent, setBase, cycleBase, setAccent}`.
- A `useLayoutEffect` re-asserts `data-base`, `.dark`, `data-accent` and theme-color. Hydration
  can reset `<html>` attributes; without it the site default overwrites a reader's pick.
- A live `systemDark` state from the `matchMedia` listener (today `isDark` goes stale after an
  OS change).
- `setAccent(<site default>)` **removes** the stored key, so the reader follows the site default.
- `cycleBase`: system → light → sepia → dark.

**Consumers:**
- `ThemeMenu.tsx`: keeps `aria-label="Choose theme"`. A "Base" radio group of `menuitemradio`s
  named exactly System, Light, Sepia and Dark. An "Accent" radio group: a swatch dot
  (`background: var(--swatch-<id>)`), the name, and a visible "default" tag on the site's own
  option. A custom-hex site adds a first "Site colour" option.
- `ThemeToggle.tsx`: labels "Switch to …" (the `/switch to/i` selector keeps working); icons
  Monitor / Sun / BookOpen / Moon.
- `export/app/components/MobileMenu.tsx:~121-141`: native radio groups "Base" and "Accent".
- `common/components/ui/sonner.tsx:17`: `theme={isDark ? "dark" : "light"}`.

**Layout defaults:**

| App | Base | Accent | Where |
|---|---|---|---|
| Export site | system | from site.json | `<html data-accent>` rendered server-side; a custom hex adds the inline `--accent-custom-*` style |
| Hub | dark | signal | export layout |
| Homepage | dark | signal | homepage layout |
| Editor | system | signal | no layout change |

**Browser chrome colour** (`generateViewport`): sites get
`[{media: light, BASE_GROUNDS.light}, {media: dark, BASE_GROUNDS.dark}]`; the hub and homepage
get `BASE_GROUNDS.dark`. `FALLBACK_THEME_COLOR`, `HUB_THEME_COLOR` and the homepage
`THEME_COLOR` go.

**Tests:**

| Spec | Change |
|---|---|
| export `theme.spec.ts` | Rewrite: default `data-base`, live `emulateMedia`, cycling through 4 states, persistence across a `commit` reload plus `data-theme-ready`. |
| export `theme-family.spec.ts` | Delete; new `theme-accent.spec.ts`. Pick Violet: it persists and the computed `--brand` is correct. Picking the default removes the key. Also pick Sepia. |
| export `site-branding.spec.ts:75-86` | `data-accent="custom"`, and the computed `--brand` is `#cc3366` on light. |
| export `responsive.spec.ts:~95` | "Archive" becomes "Sepia". |
| homepage `theme.spec.ts` | Dark + signal defaults; `REQUIRED_TOKENS` complete across all 3 bases; the backgrounds differ. |
| editor `theme.spec.ts` | Seed `BASE_KEY`; migration cases selenized+dark → dark (legacy keys removed) and archive+light → sepia. |
| unit | Tokens completeness and parity: parse tokens.css; every base declares every token; `--swatch-*` / `--brand-mark` equal `ACCENTS`. |

**Leftover copy:** `homepage/content/docs/operate.md:~84` and the comment at
`export/playwright.config.ts:~29` still describe the old accent and the committed icons.

### S3 — integrate (after S1 + S2 merge to `main`)

- Full gates.
- Verified facts appended to `plans/FACTS.md`; `plans/STATE.md` rewritten.
- `export/CHANGELOG.md` and `homepage/CHANGELOG.md` `[Unreleased]` bullets.
- The release recorded in the next `plans/release-N.md`.
- The operator runbook as **generated HTML** (operator rule).

## Verification

**Gates, every slice:**
- `pnpm -r --no-bail --workspace-concurrency=1 exec tsc --noEmit`.
- `pnpm --filter yt-dlp-transcript-common test`.
- Editor unit: `pnpm exec tsx --test "app/**/*.test.ts"` in `editor/`.
- `pnpm test:scripts`; mcp tests.
- `pnpm --filter export exec next build`, the homepage `next build` and the editor `next build`.
- `ls out/icons` plus the PNG/ICO magic checks.

**e2e** is queue-locked machine-wide; run it detached (`setsid nohup … &`). The parent session
holds a Monitor; a subagent waits in foreground loops of ≤100 s.
- `pnpm --filter export run e2e`, `e2e:hub`, `e2e:2origin`.
- `pnpm --filter homepage run e2e`.
- The root `pnpm e2e` (the editor suite).

**Visual check:** build one site, serve `out/`, and screenshot the header, the picker open, and
each base × two accents at 390 px and 1280 px (use `localhost`, not 127.0.0.1). Compare with the
canvas's *In context* and *Themes* boards.

**Caution:** `export/out` belongs to the checkout, and an e2e run can start a real deploy
(release-7 lessons). Never deploy from a worktree without the operator.

## As shipped

(Each slice appends its "### Slice S<n>, as shipped" record here.)

### Slice S0, as shipped — palette + data (2026-09-25)

Branch `brand/found-line` off the plan commit `d8dd98b8`. S0 lays the data S1 (mark, icons, wordmark)
and S2 (base × accent tokens, runtime, picker) build on: the palette and mark as pure data, the
`site.json` keys, the one mapping that keeps every *published* accent a hex, and the editor form that
writes both keys. No `common/styles/**`, `common/components/**`, layout, manifest, header, footer,
icon, service-worker or theme-spec file was touched, and nothing a reader sees changes until an
operator picks an accent or a lead.

**`common/lib/brand.ts` (new, pure: zero imports).**
- `ACCENT_IDS` (picker order) and `ACCENTS: Record<AccentId, {id, name, onDark, onLight, onSepia}>`,
  the plan's table verbatim; `DEFAULT_ACCENT = "signal"`; `isAccentId`.
- `BASE_GROUNDS` (+ `BASE_GROUND_IDS`), `ACCENT_INK` (`#ffffff` on light and sepia, the dark ground on
  dark), `MIN_ACCENT_CONTRAST = 4.5`, and the WCAG `relativeLuminance` / `contrastRatio` the rule and
  its tests use. **The rule as coded:** an accent's value on a base reaches 4.5:1 against that base's
  ground AND its ink. On dark the ink is the ground, so it is one check there. Every value in the
  plan's table passes: the tightest are Signal and Brass on light and on sepia (4.60–4.61) and Green on
  sepia (4.61). `brand.test.ts` makes 42 checks (7 accents × 3 bases × 2).
- `MARK`: six shapes back to front, the ground first (`part`, `kind`, geometry, `tone` =
  ground | dim | lit), plus `MARK_VIEWBOX`, `MARK_GROUND_RX` and `MARK_MASKABLE_SCALE`.
  `markSvg(palette, {variant})` returns a standalone SVG string:
  - `any`: ground `rx=112`;
  - `maskable`: full-bleed ground (no rx), the lines inside `<g transform="translate(51.2 51.2) scale(0.8)">`,
    which is 0.8 about (256,256);
  - `apple`: full-bleed ground at scale 1.

  Every palette colour must be `#rrggbb` or it throws, so a stored value cannot inject markup into an
  icon.
- `ICON_PALETTES` has `child` (ground `#0c0a08`, dim `#3b3327`) and `archilyzer` (`#151b20` / `#3f4c56`
  / `#e7edf1`). `childIconPalette(lit)` adds the lit value: **S1 passes
  `resolveAccent(site.accent).dark`.** brand.ts cannot import accent.ts; accent.ts imports brand.ts.
- `wordmarkLeadFor(title, lead)` returns the trimmed lead when it is a PROPER prefix of the title
  (case-sensitive, non-empty, shorter than it), else undefined. `splitWordmark(title, lead?)` returns
  `{lead, suffix}`, and without a usable lead that is `{lead: title, suffix: ""}`. There is no
  heuristic: `splitWordmark("Rekietalyzer")` is the whole title, and the test pins that. The test
  splits all seven family titles.
- `common/lib/project.ts`: `PROJECT_WORDMARK_LEAD = "Archi"`.

**`common/lib/accent.ts`.**
- `parseAccent` is unchanged and stays hex-only.
- `parseAccentSetting(v)` takes an id (trimmed, any case, stored lowercase) or `parseAccent`'s hex, else
  undefined. A hex equal to a named accent's value stays a custom hex and is never mapped to an id.
- `resolveAccent(v)` returns `{id | "custom", light, sepia, dark}`:
  - a named id reads its row;
  - absent or malformed reads Signal;
  - a custom hex is fitted per base. It is kept if it already meets the rule; otherwise it is mixed in
    sRGB toward black (light, sepia) or white (dark) in 1 % steps until it does. Full black or white
    always passes, so the loop ends.

  The fixture's `#cc3366` resolves to light `#cc3366` (kept, 4.57), sepia `#c43162` (4.50) and dark
  `#d14574` (4.53). **So S2's `site-branding` expectation, `--brand` = `#cc3366` on light, holds.**
- `accentHex(v)` is the published value: an id becomes its `onDark`, a custom hex goes out as stored
  (normalized, not fitted), and absent or malformed gives undefined.
- `customAccentVars(v)` returns `{--accent-custom-light|sepia|dark}` for a custom hex, and null for an
  id or no accent. It takes the setting as its argument; the plan wrote `customAccentVars()`.
- **`siteAccentVars` (legacy, which S2 deletes) now goes through `accentHex`.** A hex gives the same
  output as before (the `site-branding` spec's `--brand: #cc3366` passes). An id paints its on-dark
  hex in both modes, the old one-colour contract.

**`site.json` (`common/lib/siteSchema.ts`).**
- `accent` parses through `parseAccentSetting`; the doc text is new.
- `wordmarkLead?` sits after `headerTitle` in the type, `SITE_FIELD_DOCS`, the schema (trim, else
  undefined) and `siteToDisk`.
- The object step resolves it with `wordmarkLeadFor(headerTitle, …)`, beside `defaultGroupId`, so a
  non-prefix lead reads as undefined. `siteToDisk` re-checks it, so a caller's stale lead after a
  retitle is not written.
- `SITE.md` was regenerated and `--check` is clean.
- A stored `"signal"` round-trips as `"signal"`. The schema keeps any valid setting; only the FORM
  stores the default as absent.

**Published accents stay hex.** `siteDescriptor.ts` (public `/site.json`), `compose-hub.ts`
(`hub-sites.json`) and `homepageSummary.ts` (homepage summary, and through `toHubSummary` the hub's
`hub-summary.json`) emit `accentHex(site.accent)`, omitting the key when there is no accent, as before.
`wordmarkLead` is not added to the public descriptor, so the contract is unchanged. **Every reader of an
`accent`, and what it now receives:**

| Reader | Receives |
|---|---|
| `common/lib/siteDescriptor.ts:~89` | hex (`accentHex`) |
| `common/bin/compose-hub.ts:~96` → `hub-sites.json` | hex (`accentHex`) |
| `common/lib/homepageSummary.ts:~433` → `homepage-summary.json` | hex (`accentHex`) |
| `common/lib/hubSummary.ts:67,122` | the homepage summary's value → hex |
| `common/components/siteRegistry.ts:144,206,305` | `hub-sites.json` / a member's `/site.json` → hex |
| `common/components/SearchDataContext.tsx:274,442`, `SearchSessionContext.tsx:899,926,960` | registry → hex |
| `common/components/SearchResults.tsx:573`, `FiltersPanel.tsx:324` (C2's files, untouched) | `group.accent` from the registry → hex |
| `export/app/components/hub/ArchiveShelf.tsx:69` (C2's, untouched), `HubHome.tsx:39`, `HubOfflineManager.tsx:97`, `export/app/ask/AskHub.tsx:33` | registry / hub summary → hex |
| `export/app/layout.tsx:86` `siteAccentVars(currentSite().accent)` | id or hex → hex via `accentHex` (legacy, S2 deletes) |
| **`export/app/layout.tsx:64`** `generateViewport` themeColor | `parseAccent(id)` = undefined → falls back to `#2563eb` (S2's file; S2 replaces it with `BASE_GROUNDS`) |
| **`export/app/manifest.ts:19`** `theme_color` | `parseAccent(id)` = undefined → falls back to `#2563eb` (S1's file; S1 sets `BASE_GROUNDS.dark`) |
| `editor/app/sites/actions.ts`, `SiteForm.tsx` | the setting (id or hex), by design |
| `common/lib/channelGroups.ts:28` | a hub-mode group's provenance accent from the registry → hex; not a `site.json` read |
| homepage `ArchiveCards.tsx` | does not read it (its comment says so) |
| mcp, umtool | none (umtool's `pal.accent` is a video palette, unrelated) |

**Editor form** (`editor/app/sites/components/SiteForm.tsx`, `actions.ts`):
- **Brand accent** is a `<fieldset>`/`<legend>` group of 8 native radios named `accent`: the 7 named
  (each with a dot of its on-light / on-dark value, and "Signal (default)") plus **Custom**. A
  **Custom hex** text field (`accentCustom`) sits below; typing in it selects Custom. The radios are
  controlled, so the choice survives the reset React does after the action.
- The action stores the chosen id, but **Signal is stored as absent** (the two read the same). Custom
  requires a valid hex. A bare hex posted in `accent` (an old tab from before the restart) is taken as
  custom.
- **Wordmark lead** is a `Field` after Header title. The action REFUSES a non-prefix lead with an error
  rather than letting the schema drop it silently.
- `writeSite` is still the one writer.
- No new label or hint contains "header title", "site title", "site id" or "public url"; the lead's
  hint says "header text".
- Shots: `$T/s0-accent-{light,dark}.png`, `$T/s0-form-{light,dark}.png`.

**Changed locators: none.** No editor spec referenced "Brand accent" or the accent field. New test
`sites-crud.spec.ts` "brand accent radio group + wordmark lead round-trip to site.json" covers:
- the default checked, and 8 radios in the "Brand accent" group;
- Brass + lead `Brandy` → `"accent":"brass","wordmarkLead":"Brandy"`;
- typing `#CC3366` selects Custom and stores `#cc3366`;
- a lowercase lead is refused (alert) with the file unchanged;
- Signal + blank lead → both keys absent.

**`hubSite()`** (`export/app/lib/site.ts`) sets `wordmarkLead: PROJECT_WORDMARK_LEAD`. The live
`homepage.json` header title is "Archilyzer", so it is kept.

| sha | what |
|---|---|
| `e85c1fd2` | `common/lib/brand.ts` (+ test) and `accent.ts` (+ test): the palette, rule, mark, wordmark split; `parseAccentSetting` / `resolveAccent` / `accentHex` / `customAccentVars`; `siteAccentVars` through `accentHex`; `PROJECT_WORDMARK_LEAD` |
| `3b634248` | `siteSchema.ts`: `accent` id-or-hex, `wordmarkLead` (proper prefix only) + tests; `SITE.md` regenerated |
| `31ff873a` | `siteDescriptor` / `compose-hub` / `homepageSummary` publish `accentHex` + tests (new `siteDescriptor.test.ts`) |
| `17c874ca` | `export/app/lib/site.ts` `hubSite()` carries `wordmarkLead: "Archi"` |
| `4fce889d` | editor site form: the accent radio group + Custom hex, the Wordmark lead field, the action; the sites-crud test |
| `9775bd22` | sites-crud's new test filters its alert from Next's route announcer |

**Gates.**
- tsc clean before each code commit (four runs), plus a fifth on the final tree, which covers `9775bd22`, a spec-only change.
- Unit and script tests:
  - common **1,874/1,874**: C1b's 1,845 + 29 new — brand 12, accent 9, siteSchema 3, siteDescriptor 3,
    homepageSummary 1, compose-hub 1;
  - editor unit **78/78**;
  - `test:scripts` **162 + 1 skip**;
  - mcp **219/219**.
- `file-schemas-docs.ts --check` clean.
- Builds:
  - `pnpm --filter editor exec next build` ok (50 s);
  - `pnpm --filter export exec next build` ok (31 s, the known Turbopack warning), with the
    `export/public` links seeded, `sw.js` a plain copy, and no dangling links;
  - `pnpm --filter homepage exec next build` ok (16 s), with `homepage/public`'s four data entries
    COPIED from the primary.
- e2e, no queue wait:
  - editor `sites-crud.spec.ts branding.spec.ts`: run 1 **15 passed, 1 failed** (1.2 min). The failure
    was the new test's own `getByRole("alert")`: Next's route announcer is a second, empty
    `role=alert`. Run 2 on `9775bd22`: **16 passed, 0 failed**, 58.7 s.
  - export `site-branding.spec.ts`: **7 passed**, 16.1 s.
  - `e2e:hub`: **12 passed**, 28.4 s.
- The primary's `export/public/sw.js` was untouched: 10,027 B, mtime 20:47:37, before and after.
- Numbers tools: none.

**Found and left.**
- **The browser-chrome colour falls back for a named accent until S1/S2.**
  - `export/app/layout.tsx:64` and `export/app/manifest.ts:19` call the hex-only `parseAccent`, so a
    site set to an id gets `#2563eb` there instead of its colour.
  - Both files belong to S1/S2, which replace those lines with `BASE_GROUNDS`. They were left alone.
  - No live site sets an accent (all six read `null`), so nothing live changes.
- **The legacy `siteAccentVars` paints an id's on-dark value in both modes.** On the light base that is
  below 4.5:1 (Brass `#e3b15c` on `#f3f6f7` ≈ 1.9). This is transitional: S2 deletes it, and S0 is not
  rolled out alone.
- **"Signal (default)" is only literally true once S2 lands.** At S0's tip an absent accent is still
  the base family's blue.
- The worktree is port block **#1** (editor 3101, test 3111, export 3110), not #2:
  `pnpm wt list` sorts, and `diet-series` is #2.

### Slice S1, as shipped — mark, icons, wordmark (2026-09-25)

Branch `brand/mark` off S0's tip `02295a94` (worktree `../brand-mark`, port block #2). S1 draws the
Found-line mark everywhere the family shows itself: every icon file is rendered from `markSvg` at
build instead of committed, the site header is the mark plus the split wordmark, the hub, homepage
and editor wear the parent mark, and the footer credit carries it. No `common/styles/**`, theme
component, `MobileMenu`, theme spec, `site-branding` spec or C2 file was touched. In the two layouts
only the `icons` metadata changed.

**The spike passed on the plan's primary path in about 15 minutes; no fallback was taken**
(`$T/s1-spike.md`).
- `next/og` runs under tsx, so the unit tests check the PNG IHDR as well as the ICO directory. A
  probe script needs `.mts`: tsx refuses top-level await in a `.ts` it compiles to CJS.
- `app/icons/[file]/route.ts` (force-static, `dynamicParams = false`, `generateStaticParams` over
  `ICON_FILES`) and `app/favicon.ico/route.ts` (force-static) emit the right files for both export
  and homepage:
  - `out/icons/*`: icon-192 is `8950 4e47 0d0a 1a0a … 4948 4452 0000 00c0 0000 00c0`, a 192×192
    IHDR;
  - `out/favicon.ico`: starts `0000 0100 0300`, three PNG entries.
  - Both were looked at.
- The favicon route is missing from the build's route table, because Next files `/favicon.ico` as a
  metadata route, but it IS emitted.
- `next dev`, which every e2e server runs, serves all of them too. `/icons/nope.png` is a 404.

**`common/lib/brandIcons.ts` (new, server-only).**
- `ICON_FILES`: the seven `/icons/` names, each with its format, variant, size and content type.
  `iconFile(name)` looks one up.
- `ICON_METADATA`: the one `<head>` link list both layouts use: `icon.svg` first, then `icon-32.png`,
  192, 512, and apple.
- `FAVICON_SIZES`: 16, 32 and 48.
- `siteIconPalette(accent)` = `childIconPalette(resolveAccent(accent).dark)`.
- `renderIconPng(palette, {variant, size})`: an `ImageResponse` of a single `<img>` whose `src` is a
  base64 data URI of `markSvg`, built with `createElement`, so the raster IS the SVG's geometry.
- `pngToIco(images)`: a 6-byte ICONDIR, 16-byte entries (256 is written as 0), then the PNG payloads
  verbatim. `renderFaviconIco(palette)` packs the three sizes.
- `renderIconFile(name, palette)` returns null for any name not in the set; `iconResponse(body, type)`
  wraps the result.

**Routes.**
- Export: `app/icons/[file]/route.ts` + `app/favicon.ico/route.ts`. The palette is `iconPalette()`
  (`export/app/lib/brand.ts`): `ICON_PALETTES.archilyzer` when `instanceMode() === "hub"`, else
  `siteIconPalette(currentSite().accent)`.
- Homepage: the same two routes, always the parent palette.
- Neither reads the request.
- Deleted: `export/public/icons/*`, `homepage/public/icons/*`, and both `app/favicon.ico`.
- Next no longer adds its own `/favicon.ico` link, which it did for the static file, so `<head>` is
  exactly `ICON_METADATA`.
- The homepage OG image is still `/icons/icon-512.png`.

**Manifest** (`export/app/manifest.ts`):
- `theme_color` = `BASE_GROUNDS.dark` (`#0c0a08`) on sites and the hub;
- `background_color` = `iconPalette().ground` (`#0c0a08` on a site, `#151b20` on the hub);
- a new first icon `{src:"/icons/icon.svg", sizes:"any", type:"image/svg+xml", purpose:"any"}`;
- the 192/512/maskable PNG entries kept.

The hex-only `parseAccent` fallback, which S0 flagged at `:19`, is gone.

**Service workers.** `site-sw.js` and `sw-hub.js`: `const SHELL = "shell-v2"`, with a comment on why.
`VERSION` stays `"v1"`, so `pages-v1` / `meta-v1`, the readers' offline downloads, survive activate.
`contract.test.ts` still reads both files green.

**Components.**
- `common/components/BrandMark.tsx`:
  - maps `MARK` (the list `markSvg` walks) to `<rect>`/`<polygon>`;
  - `aria-hidden`, `focusable="false"`, `data-brand-mark`, and `data-tone` on each shape;
  - every fill goes in `style`, so a slot can be `var(…)`;
  - its palette type is `BrandMarkPalette` (any CSS colour).
- `common/components/Wordmark.tsx`:
  - `splitWordmark(title, lead)`: the lead at weight 720 in `var(--foreground)`, the suffix at 380 in
    `var(--muted-foreground)`, `font-stretch: 118%`;
  - two adjacent INLINE spans with no whitespace node, so the link's name is the title exactly;
  - `data-wordmark(-lead|-suffix)` hooks;
  - the face is `var(--font-grotesk, var(--font-display))`, which is Archivo both before S2 (the
    grotesk variable) and after (S2 makes Archivo `--font-display`). S3 can drop the first term.
- Export `Header.tsx`:
  - `<BrandMark palette={headerMarkPalette()} className="size-7">` + `<Wordmark title={site.headerTitle}
    lead={site.wordmarkLead}>`, truncating as before;
  - `headerMarkPalette()` is the child ink tile with `lit: "var(--brand-mark, var(--brand))"` on a
    site, and the parent mark on the hub.
- Export `Footer.tsx`: `<span class="inline-flex …"><BrandMark archilyzer size-4/><span>Built with
  <a>Archilyzer</a></span></span>`. The mark is outside the link.
- Homepage `Header.tsx`: the parent mark + `Archi|lyzer` (`PROJECT_WORDMARK_LEAD`), no uppercase or
  tracking; `aria-label="Archilyzer home"` kept.
- Editor sidebar (`editor/app/layout.tsx`): the parent mark (`size-8`) before the title block,
  outside the title link. The title is not split.
- **Editor favicon:** `editor/app/icon.svg` = `markSvg(ICON_PALETTES.archilyzer)`. Next links it as
  `/icon.svg?icon.<hash>.svg`. `editor/app/lib/brandIcon.test.ts` pins it byte for byte.
  **There was no `editor/app/favicon.ico`** (the editor had no favicon at all), so nothing was
  deleted.

**Fixture:** `"wordmarkLead": "Fixture"` in `export/e2e/fixtures/sites/testsite/site.json`.

**Tests.**
- New `export/e2e/brand.spec.ts` (5 tests):
  - the header link `{name:"Fixture Header", exact}` → `href="/"`, exactly two inline spans
    `Fixture`/` Header` at 720/380, and an aria-hidden, non-focusable mark;
  - the header mark's ground and dim are the ink tile, and its lit fill equals whatever
    `var(--brand-mark, var(--brand))` resolves to, so it survives S2;
  - the footer mark is the parent mark, the credit link has no svg, and `svg + span` holds the credit;
  - `<head>` icon links in order;
  - `/icons/icon.svg` and `maskable.svg` = `markSvg(childIconPalette(resolveAccent("#cc3366").dark))`
    (`#d14574`).
- `pwa.spec.ts`:
  - the manifest carries the `icon.svg` entry, `theme_color` = `BASE_GROUNDS.dark` and
    `background_color` = the child ground;
  - each of the five PNGs has `content-type: image/png`, the PNG magic and its IHDR size;
  - both SVGs have `image/svg+xml`;
  - `favicon.ico` is `image/x-icon`, starts `00 00 01 00`, and its first entry is a PNG;
  - `/icons/icon-64.png` is a 404.
- New `export/e2e-hub/brand.spec.ts` (2 tests):
  - `/icons/icon.svg` contains `fill="#151b20"` and `fill="#e7edf1"` and equals the parent markSvg;
  - the hub PNG, ICO and manifest (`background_color` `#151b20`);
  - the header `Archi|lyzer`, with mark fills slate / slate-dim / bone.
- New `homepage/e2e/brand.spec.ts` (2 tests): the header (name, split, no uppercase, fills) and the
  icon set.
- Editor `branding.spec.ts` +1: the sidebar mark sits outside the "Cypress HQ" link, and the linked
  `/icon.svg…` carries the parent colours.
- Unit tests:
  - `common/lib/brandIcons.test.ts` (7): ICON_FILES, ICON_METADATA, siteIconPalette, the pngToIco
    header, entries and offsets, 256→0 and range errors, the renderIconPng IHDR for all three
    variants, the renderFaviconIco directory ↔ IHDR, renderIconFile;
  - `editor/app/lib/brandIcon.test.ts` (1).

| sha | what |
|---|---|
| `446be496` | `common/lib/brandIcons.ts` (+ test): ICON_FILES, ICON_METADATA, siteIconPalette, renderIconPng (next/og), pngToIco, renderFaviconIco, renderIconFile |
| `d69cf1b1` | export `app/icons/[file]` + `app/favicon.ico` routes, `lib/brand.ts` iconPalette, layout `icons: ICON_METADATA`, manifest (BASE_GROUNDS.dark / icon ground / icon.svg); committed icons + favicon.ico deleted |
| `cee051f2` | homepage twin routes (parent palette), layout `icons: ICON_METADATA`; committed icons + favicon.ico deleted |
| `fa7823fe` | `site-sw.js`, `sw-hub.js`: `SHELL = "shell-v2"`, VERSION unchanged |
| `fee7394c` | `common/components/BrandMark.tsx`, `Wordmark.tsx` |
| `4c90c7fc` | export Header (mark + Wordmark, `headerMarkPalette`), Footer (parent mark before the credit), fixture `wordmarkLead`, new `e2e/brand.spec.ts` + `e2e-hub/brand.spec.ts`, `pwa.spec.ts` extended |
| `e1df9815` | homepage Header (parent mark + the Archi · lyzer split), new `e2e/brand.spec.ts` |
| `adcd9482` | editor sidebar mark, `app/icon.svg` + parity test, `branding.spec` +1 |

**Gates.**
- tsc: clean before each code commit (runs 2 and 3; run 1 is under "Found and left"), and run 4 on the final tree.
- Unit and script tests:
  - common **1,881/1,881** (S0's 1,874 + 7);
  - editor unit **79/79** (+1);
  - `test:scripts` **162 + 1 skip**;
  - mcp **219/219**.
- Builds, all with `export/public` seeded (`sw.js` a copy, no dangling links) and `homepage/public`
  data copied:
  - `pnpm --filter editor exec next build`: ok, 46 s. `/icon.svg` is emitted and linked.
  - `pnpm --filter export exec next build` (site mode, the worktree's default site): ok, 27 s. The
    seven `out/icons` files plus `out/favicon.ico`, PNG magic and IHDR per file (180, 192, 32, 512,
    512), ICO `0000 0100 0300 1010`, icon.svg lit Signal `#5fa8a0`, manifest as above.
  - `pnpm --filter homepage exec next build`:
    - run 1 failed in 8 s, 24 Turbopack errors in `next/font/google` for IBM Plex Sans ("queries have
      exactly one entry") from the untouched `fonts.ts`, while another worktree built at the same
      time;
    - the retry was ok, 16 s. Same file set and magic; icon.svg is the parent mark; og:image still
      `/icons/icon-512.png`.
  - Hub mode (`INSTANCE_MODE=hub pnpm --filter export exec next build`, the build step of
    `build:hub` without compose): ok, 31 s. `out/icons/icon.svg` holds `#151b20` / `#3f4c56` /
    `#e7edf1`; the manifest's `background_color` is `#151b20`.
  - A demo site (`SITES_DIR=$T/s1-demo-sites`, "Jeralyzer", lead "Jer", accent brass): ok, 33 s;
    icon.svg lit `#e3b15c`. Used for the shots.
- e2e (`$T/s1-e2e.sh`, one run, 21:37–21:56):
  - export full: **199 passed, 1 failed**, 11.2 min. The failure is `theme-family.spec.ts:18`, see
    "Found and left". Rerun alone, `theme-family.spec.ts theme.spec.ts --repeat-each 3`: **6 passed**, 32.6 s (after a ~7.5 min queue wait behind `brand-themes`).
  - `e2e:hub`: **14 passed**, 32 s (12 + the new 2).
  - homepage full: **26 passed**, 1.0 min.
  - editor `branding auto-refresh dashboard navigation widget`: **48 passed**, 4.0 min.
  - `e2e:2origin` (`TWO_ORIGIN_REBUILD=1`): **3 passed**, 48 s. Before it, the seven entries compose
    writes (`hub-sites.json site.json corpus.json llms.txt robots.txt sitemap.xml _headers`) were
    swapped for copies; afterwards they and `hub-summary.json` were relinked and the seed re-run.
- **The primary's `export/public` was never written:**
  - `sw.js` is 10,027 B, mtime 20:47:37, before and after;
  - `corpus.json`, `hub-sites.json`, `llms.txt`, `robots.txt`, `_headers`, `hub-summary.json` and
    `sitemap.xml` kept their pre-run mtimes.
- Screenshots (`$T/s1-*.png`, from served `out/` on localhost, all looked at):
  - `site-header-{390,1280}-{light,dark}`: brass Jer|alyzer;
  - `site-footer-light`, `site-footer-390-dark`;
  - `hub-header-{1280,390}`, `hub-footer`;
  - `homepage-header-{1280,390}`.

  They match the canvas's *In context* board. On light the ink tile is a real icon tile; on the
  dark base it coincides with the page ground and the lines carry the mark, as the canvas draws
  Jeralyzer on dark and the parent mark on slate.
- Numbers tools: none.

**Found and left.**
- **Importing the `next` root types into `common/` breaks common's tsc.** tsc run 1 put 10 errors in
  existing tests (`bin/_cli.test.ts`, `publish/build.test.ts`: "Property 'NODE_ENV' is missing …
  ProcessEnv"). The cause was `import type { Metadata } from "next"` in `brandIcons.ts`: `next/index.d.ts`
  references `types/global`, which makes `NODE_ENV` required on every `ProcessEnv` in the program.
  So `ICON_METADATA` is untyped; the layouts type-check it against `Metadata`. `next/og` does not
  carry that reference.
- **`theme-family.spec.ts:18` timed out** waiting for `menuitemradio "Swiss"`, in the second
  `pickFamily`, right after `page.reload({waitUntil:"commit"})` + `themeReady`. The shot shows
  Selenized applied and the menu closed: the click landed before hydration. `themeReady` is set by
  the pre-paint script, not by React.
  - It is the same reload timing `plans/deflake-e2e.md` §2 fixed for the read, which still races the
    click after it.
  - S1 touches no theme code.
  - S2 deletes this spec.
- **`export/playwright.config.ts:29` still says "exactly like the committed public/icons/*".** The
  plan lists that comment under S2's leftover copy, so it was left for S2/S3.
- **`export/.2origin/hubA`** is a hub build (gitignored, about 2.5 GB, because `out/` copies the
  linked public data). It stays in the worktree for the next 2origin run.

**Review fixes** (review verdict SHIP, `$T/s1-review.md`; review nit 5, the `layout.tsx` import
conflict with S2, is left for the merge).
- `541a46e0`, should-fix 1 + nit 2:
  - both service workers serve `/icons/` network-first into shell-v2 (fresh online, cached
    offline), so a redeployed accent reaches readers;
  - `/_next/static/` stays cache-first; `SHELL` stays `"shell-v2"` and `VERSION` `"v1"`;
  - the `SHELL` comment now says the rename also drops the cached HTML and chunks, so the installed
    app opens offline again only after one more online visit.
  - No test covered the strategy (`contract.test.ts` pins only the URL families). The new
    `lib/archive/serviceWorkerRouting.test.ts` runs each worker in `node:vm` with a fake
    `self`/`caches`/`fetch` and drives its fetch handler. Reverting site-sw's routing turns its icon
    test red.
- `405fccd5`, nits 3 + 7:
  - `ICON_FILES`, `iconFile`, `ICON_METADATA`, `FAVICON_SIZES` and `siteIconPalette` moved to the pure
    `common/lib/brandIconFiles.ts` (no `next` import);
  - `lib/brandIcons.ts` keeps the renderers beside `next/og`, and its only importers are the four
    icon/favicon routes; the layouts and `export/app/lib/brand.ts` read the pure module. A test pins
    the importer set and the purity.
  - The variant test: pixel (0,0) is transparent on the `any` 512 and the opaque ground on the
    maskable 512 and the apple 180. A variant-ignoring `renderIconPng` turns it red.
- `951a0ff5`, nit 6: the `accentHex` comment says the published hex is the icon's lit line only for a
  named accent.
- `4a7641af`, nit 4: `pwa.spec`'s 404 probe names the dev log line it causes as expected.
- Gates:
  - tsc clean before each commit;
  - common **1,887** (+6), editor unit **79**;
  - export build ok (23 s), homepage build ok (14 s), with the same seven `out/icons` files + favicon
    and the same PNG/ICO magic;
  - export `pwa.spec.ts brand.spec.ts`: **8 passed**, 15 s; `e2e:hub`: **14 passed**, 24 s;
  - the worktree's `sw.js` stayed a copy, and the primary's `sw.js` is unchanged (10,027 B,
    20:47:37).

### Slice S2, as shipped — base × accent (2026-09-25)

Branch `brand/themes` off S0's tip `02295a94`. S2 replaces the five theme families with two independent
reader choices: a **base** (Light / Sepia / Dark, plus System) and an **accent** (the seven named accents of
`lib/brand.ts`, defaulting to the site's own). No S1 file was touched: not the header, footer, mark,
wordmark, manifest, icons, service workers or the `icons` metadata, and not C2's hub search components.

**`common/styles/tokens.css`.**
- The `dark` custom variant stays. Every `[data-theme=…]` block, the `.dark{}` token block and the per-family
  font/radius rules are gone.
- `:root` carries `--radius: 0.375rem` and a default `--brand-mark` (Signal's on-dark `#5fa8a0`), so a page
  with no `data-accent` (the editor) still has one. `.font-display { font-stretch: 112% }`.
- Three base blocks: `:root, html[data-base="light"]`, `html[data-base="sepia"]`, `html[data-base="dark"]`.
  Each declares:
  - all **49** colour tokens of `homepage/e2e/theme.spec.ts`'s list (the plan said 48; lines 64–112 are
    49) and `color-scheme`;
  - `--swatch-<id>` for the seven accents on that ground and
    `--swatch-custom: var(--accent-custom-<base>, var(--swatch-signal))`;
  - `--brand: var(--swatch-signal)`, a `color-mix` `--brand-strong` (78 % toward black on light/sepia,
    toward white on dark), `--brand-soft` (12 % / 16 %), `--brand-ink` (`#fff` / `#0c0a08`);
  - a neutral `--primary` (`#202a31` / `#33281a` / `#efe7d8` on a ground-coloured foreground) and
    `--ring: var(--brand)`.
- Then one `html[data-accent="<id>"]` rule per accent (`--brand: var(--swatch-<id>)`, `--brand-mark: <onDark>`)
  and `html[data-accent="custom"]` (`--brand: var(--swatch-custom)`,
  `--brand-mark: var(--accent-custom-dark, #5fa8a0)`), after the bases at the same specificity.
- **Light** is the old archilyzer light block. **Dark** is the archive ink block plus
  `--destructive-soft`, `--state-gone: #d9644f` and `--state-gone-soft`; the gone red sits inside the
  validator's dark lightness band. **Sepia** is new: the plan's five values
  (the canvas holds no more), with status, panel and chart values from the archive paper block, darkened
  for the ground. `themeTokens.test.ts` holds every text token (foreground, muted, destructive, success,
  warning, info, state-gone) at ≥ 4.5:1 on each ground and card.
- **Charts** are fixed per base, one hue order everywhere (blue, green, violet, amber, magenta):

  | Base | chart-1..5 | surface | gone |
  |---|---|---|---|
  | Light | `#3a7de0 #2f8a57 #5e3aa8 #a8741a #c24a8a` | `#ffffff` | `#a8412d` |
  | Sepia | `#3574d6 #2a7d4f #5e3aa8 #a8741a #bb4585` | `#faf4e6` | `#a3392a` |
  | Dark | `#3561c8 #3fa577 #9a7ee6 #b98a2a #c24c8a` | `#16110a` | `#d9644f` |

  The dataviz skill's `validate_palette.js` ran on each base's surface:
  - Adjacent pairs pass every check. Adjacent is the rule for stacks, bars and lines.
  - All pairs also exit 0, but one non-adjacent pair per base sits in the CVD 6–8 **floor band** (WARN,
    legal only with a legend or direct labels): green ↔ amber on light (6.2) and sepia (6.1), and green ↔
    magenta on dark (6.9).
  - chart-3 against `--state-gone` (all pairs) passes every check on every base: normal ΔE 24.3 / 23.7 /
    22.9, and protan or deutan ΔE ≥ 21.
  - chart-1 is a blue, ΔE 17.3 / 16.8 / 23.3 from Signal.

  Output: `$T/s2-dataviz.log`.

**`common/styles/fonts.ts`.** Archivo (`wdth` axis, variable weight) as `--font-display`, IBM Plex Sans
400–700 normal + italic as `--font-sans`, IBM Plex Mono as `--font-mono`. Source Serif/Sans/Code and
JetBrains Mono are gone. The comments in all three `globals.css` files describe the bases and accents.

**`common/components/themeConfig.ts`.**
- `BASE_KEY` (`ytdlp-tb:base`), `ACCENT_KEY` (an id), `LEGACY_THEME_KEY` and `LEGACY_MODE_KEY`.
- `ThemeBase`, `ResolvedBase`, `ThemeAccent` (an id or `"custom"`), `THEME_BASES`, `nextBase`, `resolveBase`
  and `REQUIRED_TOKENS`.
- `accentOptions(siteAccent)`, which both pickers read. A custom-hex site gets "Site colour" first.
- The pure `migrateLegacy`, following the plan's table.
- `buildThemeScript({defaultBase})`, which runs in the plan's order and sets `data-theme-ready` last. It
  guards every storage touch, so a throwing `localStorage` still paints the default base and sets the
  marker.
- `themeConfig.test.ts` runs the string in `node:vm` over 7 legacy themes × 5 modes × 6 stored bases ×
  3 defaults × OS light/dark (1,260 cases). It checks:
  - the stored base, and that both legacy keys are deleted;
  - `data-base`, `.dark` and `theme-color`;
  - that the marker is the last mutation.

  It also covers the accent, a throwing storage and a throwing matchMedia.

**`ThemeProvider`.**
- Props `{defaultBase = "system", siteAccent = DEFAULT_ACCENT}`. The context is exactly the plan's:
  `{base, resolvedBase, isDark, accent, siteAccent, setBase, cycleBase, setAccent}`.
- A `useLayoutEffect` adopts the stored choice. It runs the same one-time migration, then re-asserts
  `data-base`, `.dark`, `data-accent` and `theme-color`. Nothing is written before adoption.
- `systemDark` follows a live `matchMedia` listener.
- `setAccent(siteAccent)` removes the key. `"custom"` is never stored.

**Consumers ported.** Everything else that read the old context (`theme`, `mode`, `setTheme`, `setMode`,
`cycleMode`, `THEME_FAMILIES`, `THEME_MODES`) moved over:
- `ThemeMenu`:
  - `aria-label="Choose theme"`;
  - a "Base" group of `menuitemradio`s: System, Light, Sepia, Dark;
  - an "Accent" group: a swatch dot of `var(--swatch-<id>)`, the name, and a visible "default" tag.

  The tag is part of the item's accessible name ("Brass default"), so the specs match by prefix.
- `ThemeToggle`: "Switch to <next>", Monitor/Sun/BookOpen/Moon. `data-theme-mode` became
  `data-theme-base`; nothing read it.
- `export/app/components/MobileMenu.tsx`: native radio groups "Base" and "Accent".
- `ui/sonner.tsx`: `theme={isDark ? "dark" : "light"}`.
- The three layouts.

A grep for the old names finds only S1's `manifest.ts` (`parseAccent`, S1 replaces it) and
`editor/app/sites/actions.ts` (`parseAccent` of the custom hex, by design).

**Layouts.**
- The export site renders `<html data-accent={resolveAccent(site.accent).id}>`, plus `customAccentVars`
  inline for a custom hex. It opens on the system base.
- The hub opens dark in Signal. The homepage opens dark with `data-accent="signal"`.
- The editor layout is unchanged: system base, Signal from `:root`.
- `generateViewport`: a site gets the light/dark `BASE_GROUNDS` media pair; the hub and the homepage get
  `BASE_GROUNDS.dark`.
- `FALLBACK_THEME_COLOR`, `HUB_THEME_COLOR`, the homepage `THEME_COLOR` and the hex-only `parseAccent`
  read at `export/app/layout.tsx:64` are gone.
- `siteAccentVars` and its test are deleted.

**Tests.**
- The export `theme.spec` is rewritten. `theme-family.spec` is deleted and `theme-accent.spec` is new.
- `site-branding` checks `data-accent="custom"`, the inline `--accent-custom-light` and a computed
  `--brand` of `#cc3366` on light.
- In `responsive`, the "Archive" radio is now "Sepia".
- The homepage `theme.spec` and the editor `theme.spec`: see the commits.
- `themeTokens.test.ts` (12 tests) parses `tokens.css`. It checks completeness, and that the swatches and
  `--brand-mark` equal `ACCENTS`, the accent rules follow the bases, and `customAccentVars`' names match.

**Copy.** `homepage/content/docs/operate.md` describes the accent and the reader's menu. The hub's
AddArchive comment no longer points at the retired archilyzer block. `export/playwright.config.ts:29` only
describes the committed icons, which is S1's, so it was left.

| sha | what |
|---|---|
| `7ba8258b` | `tokens.css`: three bases × seven accents, fixed validated charts; `fonts.ts`: Archivo / Plex Sans / Plex Mono; `globals.css` comments; `themeTokens.test.ts`; `REQUIRED_TOKENS` |
| `ef56f3cf` | `themeConfig.ts`: keys, types, `migrateLegacy`, `buildThemeScript`; the node:vm matrix test |
| `639fd1ff` | ThemeScript / ThemeProvider / ThemeMenu / ThemeToggle / sonner / MobileMenu; the export and homepage layouts (data-accent, defaults, `BASE_GROUNDS` chrome); the retired exports removed |
| `553733c1` | `siteAccentVars` and its test deleted |
| `93b963a0` | export specs: `theme` rewritten, `theme-accent` new, `theme-family` deleted, `site-branding`, `responsive` |
| `6d179081` | homepage `theme.spec`: dark + Signal, `REQUIRED_TOKENS` on all three bases |
| `b0fefda7` | editor `theme.spec`: seeds `BASE_KEY`; migration cases |
| `b82f8e02` | `operate.md` copy; AddArchive comment |
| `996d763d` | `tokens.css` chart comments: all pairs pass with one CVD floor-band pair per base (comments only) |

**Gates.**
- tsc was clean before each code commit: six runs, with the three spec commits sharing one. A run on the
  final tree also covers `b82f8e02`, which changed only markdown and a comment.
- Unit and script tests:
  - common **1,893/1,893**: S0's 1,874, minus the `siteAccentVars` test, plus 12 token and 8 themeConfig
    tests;
  - editor unit **78/78**;
  - `test:scripts` **162 + 1 skip**;
  - mcp **219/219**.
- Builds, with the `export/public` links seeded, `sw.js` a plain copy, no dangling links, and
  `homepage/public`'s four data entries copied from the primary:
  - `pnpm --filter editor exec next build` ok (80 s);
  - `pnpm --filter export exec next build` ok (50 s, the known Turbopack warning);
  - `pnpm --filter homepage exec next build` ok (23 s).
  - The built `<html>` carries `data-accent`, the site's two theme-color metas are
    `#f3f6f7` / `#0c0a08`, and the homepage's is `#0c0a08`.
- e2e:
  - export in full: **199 passed, 0 failed**, 8.1 min, after 44 s in the queue behind `brand-mark`;
  - `e2e:hub`: **12 passed**, 23 s;
  - homepage in full: **24 passed**, 56 s, with no skips because the data was copied;
  - editor `theme.spec.ts sites-crud.spec.ts branding.spec.ts`: **22 passed**, 1.1 min. No other editor
    spec mentions theme, `data-theme` or the theme keys.
- The primary's `export/public/sw.js` was untouched: 10,027 B, mtime 20:47:37, before and after.
- The dataviz validator exited 0 on every run listed above. The only WARNs are the three all-pairs
  floor-band pairs.
- Numbers tools: none.
- Visual check: a brass site (`SITE_ID=shotsite`, a copy of the fixture with `"accent":"brass"`) was
  built to `export/out` and served on `localhost:3310`. Shots:
  - each base × {brass, violet} at 390 and 1280;
  - the menu open on light and on dark;
  - the phone sheet on sepia and dark.

  They are in `$T/s2-*.png`. Sepia reads as paper. The dark ink ground carries brass and violet cleanly.
  Contrast, computed: sepia fg 12.2, muted 5.5 (5.9 on card), faint 3.6, brass-on-sepia 4.6, white on
  brass 5.4; dark fg 16.1, muted 7.1, faint 3.5, brass 10.1, gone 5.5.

**Found and left.**
- **chart-4 (amber) and chart-5 (magenta) sit near the gone red.** Normal ΔE to `--state-gone` is 11.8–14.5
  on the three bases, below the validator's floor of 15 for a pair. The gate the plan asked for is chart-3,
  and it clears widely. Every warm hue flanks red, and gone never draws inside a chart. The homepage's five
  official instances do reach slots 4 and 5. **The review accepted this:** gone is drawn only as labelled
  text.
- **No-JS readers get the light block.** The server renders no `data-base`, so a page no script has run on
  shows the light base, as the old base family's light look did before. **Fixed in review for the hub and
  the homepage**, which now render dark on the server; a site's "system" base still cannot be.
- **theme-color after client navigation is not asserted.** Next may re-render its head metas on client
  navigation; the provider re-asserts theme-color only on a theme change.
- **Two changelogs gained an `[Unreleased]` section:** `export/CHANGELOG.md` and `homepage/CHANGELOG.md`
  had none. The export one shows under /sites "Release notes" and on every site's /changelog until it is
  cut.
- **`export/out` holds the brass shot build**, not a gate build, and this worktree's `homepage/public`
  holds copied data (gitignored).

**Review fixes** (review verdict SHIP AFTER FIXES: `$T/s2-review.md`; no must-fix).

| sha | fix |
|---|---|
| `4c78c16a` | Sepia status text now reads at 4.5:1 on its own soft fill over the ground and a card: warning `#8c4c00` (4.65 / 4.96), info `#1858bc` (4.74 / 5.07), and success `#256829` (4.73 / 5.05; the new test found it at 4.49). Dark gone-soft alpha drops to 0.12 (4.94 / 4.60; it was 4.37 over a card). `themeTokens.test` checks text-on-soft for five pairs on sepia and dark. Light's success and warning (4.18 / 3.89) predate S2 and are left. |
| `712257e0` | The homepage growth chart stacks in palette order, `STACK_ORDER = [0,1,2,3,4]`. The old interleave put green against magenta in the CVD floor band (6.3 / 7.2 / 6.9). In stack order every touching pair passes on all three bases (worst CVD 13.1 / 13.5 / 15.5; `$T/s2-dataviz-stack.log`). |
| `e80af0b8` | The homepage and the hub (export with `defaultBase === "dark"` only) server-render `class="… dark"` and `data-base="dark"`. A new homepage spec runs with `javaScriptEnabled: false` and checks `data-base`, `.dark`, `data-accent`, that there is no ready marker, `--background` `#0c0a08` and the body's background. The Light reader's reload is re-checked after load. |
| `38b03890` | Accent text on its soft tint is `text-brand-strong` (≥ 6.48:1 on every base; plain `text-brand` went as low as 3.96). Six places use it: the Badge `brand` variant, the editor's SidebarBadges, export ContextPanel, OfflineManager ×2, HubOfflineManager and `downloads/page.tsx`. None of C2's files had one. |
| `1c72eda1` | `site-branding` reads the raw HTML of `/` and finds `<html … data-accent="custom">` and the inline `--accent-custom-light`. `tone.ts`'s header names the three bases. |
| `86a8dfa7`, `16e3d2c1` | Glyph gaps at 390 px. They persisted after `document.fonts.ready`, appear at DPR 2 and 3 with or without mobile emulation, and are absent at DPR 1. **The cause is font hinting**, not letter-spacing, font-stretch or justification. IBM Plex Sans ships TrueType hinting, and Chromium on Linux (FreeType) rounds each hinted advance to a whole CSS pixel: at 14px the `g` of "Light" measured 9px against a 7.41px design width. `text-rendering: geometricPrecision` fixes it, on `html` and on `button, input, select, textarea`, because the UA sheet resets form controls to `auto` ("Res ults"). `themeTokens.test` pins the rule. |
| `e3e3fb26` | The no-flash specs' ready-marker wait is `document.documentElement?.…`. Right after a `commit` reload the new document can have no root, and one post-merge run failed on exactly that (`theme.spec.ts:96`). |

- **Pre-merge gates:**
  - tsc clean (two runs);
  - common 1,894, editor unit 78;
  - export build ok (24 s), homepage build ok (17 s); the homepage's `<html>` is
    `antialiased dark" data-base="dark" data-accent="signal"`;
  - e2e: export `theme`, `theme-accent` and `site-branding`, **13 passed** (37 s); homepage full,
    **25 passed** (39 s); hub, **12 passed** (29 s).
- **Merge of `main` (`575ae1d4`, S0 + S1 + release 9 C2/C3), `6456ac6c`.** Conflicts were the export
  layout's import block (both sides kept), the three `[Unreleased]` changelogs (every bullet) and this file
  (records in slice order). `accent.ts` merged cleanly. `33344d66` ports S1's leftovers:
  - Wordmark's font is `var(--font-display)`; `--font-grotesk` is gone;
  - the header mark's comment no longer says `--brand-mark` is undefined. Its
    `var(--brand-mark, var(--brand))` picks up the token.
  - Nothing else of S1's or C2's reads the old theme API. `manifest.ts` and the icon routes compile
    against the new `accent.ts`.
- **Post-merge gates:**
  - tsc clean before each commit;
  - common **1,907**, editor unit **79**, `test:scripts` **162 + 1 skip**, mcp **219**.
  - Builds:
    - editor ok (38 s);
    - export site ok (23 s), and hub mode (`INSTANCE_MODE=hub`) ok (25 s);
    - homepage ok (14 s).
    - Each export/homepage build has the seven `out/icons` files with PNG magic and IHDR
      180/192/32/512/512, and `favicon.ico` starts `00 00 01 00 03 00`. The site icon is lit Signal
      `#5fa8a0`; the hub and homepage icons are the parent mark `#151b20 / #3f4c56 / #e7edf1`. The hub
      and homepage `<html>` carry `dark` and `data-base="dark"`; the site's carries neither.
  - e2e:
    - export full, **203 passed, 1 failed**, 7.0 min. The failure is the ready-marker race above; after
      `e3e3fb26`, `theme`, `theme-accent` and `site-branding` `--repeat-each 3` gave **39 passed**
      (1.4 min).
    - `e2e:hub` **19 passed** (38 s).
    - `e2e:2origin` (`TWO_ORIGIN_REBUILD=1`) **3 passed** (37 s). The composed entries in
      `export/public` were swapped for copies first, then relinked.
    - homepage full **27 passed** (39 s).
    - editor `theme`, `branding` and `sites-crud` **23 passed** (53 s).
  - The primary checkout's `export/public` was never written: `sw.js` is 10,027 B, mtime 20:47:37, and
    the seven composed files kept their mtimes.
  - `16e3d2c1` (the CSS rule extended to form controls) came after the e2e runs. It was gated by tsc,
    common 1,907, the token test and a rebuild.
- **Post-merge shots** (`$T/s2-merged-*.png`, served `out/` on localhost, all looked at):
  - the site on light + brass, sepia + violet and dark + brass at 1280. S1's mark sits on its ink tile,
    lit by `--brand-mark`: `#e3b15c` for brass, `#b49cf2` for violet. The wordmark is Archivo;
  - the hub on its dark default: the parent mark, and `data-accent="signal"`;
  - the 390 px phone menus on sepia and dark at DPR 2, after `fonts.ready`: no glyph gaps.

### Slice S3, as shipped — integrate (2026-09-25)

Branch `brand/found-line`, fast-forwarded to `main` at `b9772e53` (S0 + S1 + S2 merged), worktree
`../brand-found-line`, port block #1. S3 is the integrated tree: the review carry-overs
(`$T/s3-carry.md`), a coherence pass over the merged code and docs, the full gates, the records and
the operator's runbook. Nothing was rolled out.

**Carry-overs, all done.**
- **Test pins** (S0 review). `brand.test.ts` pins the bar as a literal (`MIN_ACCENT_CONTRAST === 4.5`,
  and both contrast loops compare against `4.5`), the sRGB curve at its boundary pair on white
  (`#767676` 4.54 passes, `#777777` 4.48 fails — a naive gamma 2.2 would not land there), and the whole
  21-value `ACCENTS` table as literals. `accent.test.ts` pins the literal too.
- **`export/app/lib/site.ts`**: `hubSite()`'s comment re-wrapped at ~80 columns.
- **Service-worker test** (S1 re-read). `serviceWorkerRouting.test.ts`'s fake response gained `ok`, and
  both workers get two cases: an online non-ok `/icons/` response is passed through but never replaces
  the cached icon (and the next offline launch still gets it), and a failed fetch falls back to the
  cached icon. Removing `if (res.ok)` from `site-sw.js`'s `networkFirst` turns the first red.
- **Light base status colours** (S2 left). On their own `-soft` fills over the ground and a card:
  success `#1f7a4d` → **`#1c7046`** (4.18 / 4.52 → **4.74 / 5.12**), warning `#96650b` → **`#825809`**
  (3.89 / 4.18 → **4.75 / 5.14**); the `-soft` rgba values follow; info (5.20 / 5.62), destructive and
  gone (4.69 / 5.08) already passed. On the plain ground they read 5.60 and 5.77. `themeTokens.test`'s
  text-on-soft check now runs on all three bases (30 checks). No other file used the old hexes.
- **`text-rendering: geometricPrecision` scoped to high density** — at **1.5dppx**, not the 2dppx the
  review suggested. A probe of the built hub (`$T/s3-probe*.log`, `s3-probe-montage*.png`) measured the
  `g` of "Signal" at 9 px against its 7.41 px design width at every DPR without the rule. At 1x and 1.25x
  the hinted glyph fills the advance and the word reads clean; at 1.5x and 1.75x (150 % and 175 %
  desktop scaling) it already reads "Sig nal", as at 2x and 3x. `@media (min-resolution: 1.5dppx)`
  (built as `(min-resolution:1.5x)`) keeps 1x/1.25x screens hinted and fixes every density that split;
  re-probed clean at 1, 1.25, 1.5, 1.75 and 2. `themeTokens.test` pins the media rule, its selector list,
  and that no top-level rule sets `text-rendering`.
- **`export/playwright.config.ts`**: the `sw.js` staging comment sat above an unrelated block and said
  "exactly like the committed public/icons/*". It now sits on the copy it explains and says the icons
  need no staging (route handlers render them).
- **The absent-accent contract** (S0 review "consider"; parent decision): no change — recorded in
  `release-10.md` and FACTS, not in code.

**Coherence pass.** A grep of code, specs, docs and the editor UI for the retired families (`archive`,
`selenized`, `swiss`, `archilyzer` as a theme, `data-theme`), the retired fonts, `siteAccentVars`,
`FALLBACK_THEME_COLOR`, `HUB_THEME_COLOR` and `public/icons` found only legitimate uses (the
migration's legacy keys and tests, the `data-theme-ready` marker, the no-retired-family test) plus four
stale comments and one hint, fixed: `ui/alert.tsx` and `WorkersView.tsx` ("every theme family"),
`views/laneState.ts` ("four theme families × light/dark", and a `flow/tone.ts` path that is
`pipeline/tone.ts`), and the site form's accent hint ("per theme" → "on each base (light, sepia,
dark)"). `homepage/content/docs/**`, the root `*.md` and SITE.md were already right.
**Changelogs:** the three `[Unreleased]` sections now read as one release. The editor's S1 bullet
promised the header mark would follow the reader's accent "once the theme picker lands" and S0's
promised the header, icons and picker "with the rest of the brand work" — both stale; they now state
what shipped. The icons' network-first refresh and the one-visit offline gap are in the editor and
export bullets; the light status contrast and the homepage chart's stack order are named. Release 9's
bullets are untouched.

**A build defect the gates found: IBM Plex Sans is now requested variable.** The first homepage e2e run
never started. `next dev` failed on every IBM Plex Sans `@font-face` with `next/font/google queries have
exactly one entry` → `Module not found: '@vercel/turbopack-next/internal/font/google/font'`, and the
webServer timed out at 120 s. The generated CSS (`homepage/.next/dev/static/chunks/…ibm_plex_sans…css`)
held `https://fonts.gstatic.com/l/font?kit=…&skey=…&v=v23` URLs: Google had cut the four static weights
through its dynamic instancer, and Turbopack carries the font URL in a one-entry import query that the
`&` splits. It is the error that failed S1's first homepage build too; 26 static-weight requests made
afterwards all got `/s/` files, so it is intermittent upstream, and a site build during the rollout
could fail the same way. `fonts.ts` now asks for Plex Sans with no `weight` (variable, `wght`
100–700): the variable file is always a pre-built `/s/` URL, and its `wght=400` instance has the static
file's advances and outlines exactly (fontTools, 54 glyphs; both files carry no TrueType instructions
and the same `gasp`). The UI's 400–700 are unchanged; the build now emits 12 Plex Sans faces
(`font-weight: 100 700`) instead of 48, and no `l/font` URL. The glyph probe after the change reads the
same advances at every DPR. Archivo was already requested variable; IBM Plex Mono is static-only on
Google and never goes through the instancer. While there, the `tokens.css` comment is corrected: S2
wrote "IBM Plex Sans ships TrueType hinting", but the Google-served font has no instructions; its
`gasp` table asks for grid-fitting and FreeType hints it.

| sha | what |
|---|---|
| `6497439d` | brand tests: the literal 4.5 bar, the sRGB boundary pair, all 21 accent values; `accent.test` the literal bar |
| `53a692ac` | `serviceWorkerRouting.test`: a non-ok and a failed online icon fetch leave the cached icon, both workers |
| `1da6a265` | light success `#1c7046` / warning `#825809` (+ soft fills); `themeTokens.test` text-on-soft on every base |
| `408120a3` | `geometricPrecision` under `@media (min-resolution: 2dppx)` + the test (superseded by `dc7ff1cf`) |
| `58e71a88` | `export/app/lib/site.ts` comment wrap; `playwright.config.ts`'s sw.js comment by its code, no committed icons |
| `a0790d39` | stale "theme family" comments (`ui/alert`, `laneState`, `WorkersView`) and the site form's accent hint |
| `25952f12` | the editor/export/homepage `[Unreleased]` brand bullets as one coherent release |
| `dc7ff1cf` | the scope starts at 1.5dppx (measured), test updated |
| `a4542721` | `fonts.ts`: IBM Plex Sans requested variable (the `l/font` build failure) |
| `2c76f6b2` | the `tokens.css` comment: why Plex hints on Linux, why the scope starts at 1.5x |
| `5a433aa9` | `plans:` this record, `release-10.md`, FACTS, STATE, the rollout section |
| `85cf6e81` | review nits: the token parser comment; the SW test's no-cache network-error case |
| _this_ | `plans:` the review fixes |

**Gates** (the code tip is `2c76f6b2`).
- **tsc** clean before every code commit (four runs: `s3-tsc-1..4.log`; the changelog commit is markdown).
- **Unit and script tests** on `25952f12`: common **1,913/1,913** (1,907 + 6: brand +1, service worker
  +4, tokens +1), editor unit **79/79**, `test:scripts` **162 + 1 skip**, mcp **219/219**;
  `file-schemas-docs.ts --check` clean. On `2c76f6b2`: common **1,913/1,913** again (the font request
  touches nothing the other three test).
- **Builds**, `export/public` seeded under sh with `sw.js` a plain copy and no dangling links,
  `homepage/public` data copied from the primary:
  - on `25952f12` (`s3-gates.log`): editor ok (33 s), export site ok (22 s), export hub ok (19 s),
    homepage ok (13 s);
  - on `2c76f6b2` (`s3-regate.log`): editor ok (43 s), export site ok (26 s), homepage ok (14 s), export
    hub ok (27 s);
  - every export/homepage build: `out/icons` = the seven files, PNG magic `89504e470d0a1a0a` and IHDR
    180/192/32/512/512, `favicon.ico` `00 00 01 00 03 00`; the site's `icon.svg` lit Signal `#5fa8a0`,
    the hub's and homepage's the parent mark; the site `<html>` carries `data-accent="signal"` and no
    `data-base` (theme-color pair `#f3f6f7` / `#0c0a08`), the hub and homepage `dark
    data-base="dark" data-accent="signal"`; the built CSS has `@media (min-resolution:1.5x){html,button,
    input,select,textarea{text-rendering:geometricprecision}}`.
- **e2e, the full sequence on `dc7ff1cf`** (`s3-e2e.log`, 23:22 → 00:10, no queue wait):
  - export full **204 passed**, 6.4 min;
  - `e2e:hub` **19 passed**, 37 s;
  - `e2e:2origin` (`TWO_ORIGIN_REBUILD=1`, the seven compose outputs + `sw.js` swapped for copies,
    relinked after) **3 passed**, 33 s;
  - homepage full: **did not start** — the webServer timed out at 120 s on the font defect above;
  - **editor full (`pnpm e2e`) 638 passed, 1 failed, 12 skipped, 38.2 min** (651 tests). The failure
    is `pipeline.spec.ts:164` "channel list sync button runs the platform-queue sync", 355 ms:
    `EEXIST: file already exists, mkdir '…/editor/test-transcripts/channels'` inside `resetData`'s
    fixture copy (`editor/e2e/helpers.ts`), before the test touched the page. **Pre-existing,
    flaky:** it is the fixture-reset race the helper's own comment describes (a server runner
    re-creating a path while the tree is reset; the same class hit `channel-work.spec` and
    `pipeline.spec:106` before), and the brand diff touches no helper, runner, channel list or job
    code (`git diff --stat c9223978 HEAD -- editor/e2e/helpers.ts editor/app/channels common/jobs
    common/controller` is empty). Rerun alone ×3 on the final tree: **3 passed**.
- **e2e re-gate on `2c76f6b2`** (`s3-regate.log`, 00:14 → 00:26, after the font fix):
  - homepage full **27 passed**, 42 s;
  - editor `pipeline.spec.ts:164 --repeat-each 3` **3 passed**, 39 s;
  - editor `theme.spec.ts branding.spec.ts sites-crud.spec.ts` **23 passed**, 58 s;
  - export full **204 passed**, 7.2 min;
  - `e2e:hub` **19 passed**, 43 s;
  - `e2e:2origin` (copies swapped in and relinked as above) **3 passed**, 41 s.
  - The full editor suite was not re-run after `a4542721`/`2c76f6b2`: they change only which
    Google Fonts URL `next/font` requests (same outlines) and a CSS comment. The suites that compile
    those fonts in `next dev` (export, homepage) ran in full on the final tree.
- **The primary checkout's `export/public` was never written:** `sw.js` 10,027 B, mtime 20:47:37, and
  `hub-summary.json`, `hub-sites.json`, `corpus.json`, `llms.txt`, `robots.txt`, `sitemap.xml` and
  `_headers` kept their sizes and mtimes before, between and after every run.
- Numbers tools: none.

**Visual set** (`$T/s3-*.png`, served `out/` on localhost, all looked at; embedded in the runbook). A
brass site (`$T/s3-sites/shotsite`, the fixture copy titled Jeralyzer with lead `Jer`): light + brass
(`--brand #95661a`, mark `#e3b15c`), sepia + violet (`#6a4bc4` / `#b49cf2`), dark + brass, the theme
menu open (Base + Accent, Brass tagged DEFAULT), the 390 px phone sheet on sepia at DPR 2 (no split
words); the hub on dark (`data-accent="signal"`, the parent mark, Archi|lyzer; built in the worktree,
so it read the primary's `hub-sites.json` through the link and loaded the live members); the homepage
header. They match the S2 post-merge shots and the canvas.

**Found and left.**
- **The absent-accent contract stays as it is** (decided; `release-10.md`).
- **The release-10 lows are unstarted**, including `playwright.config.ts` copying over `public/sw.js`
  without unlinking it: S3 replaced the worktree's link with a copy before every run instead.
- **The 1.5dppx threshold was measured on Linux Chromium only.** Chromium on Windows (DirectWrite) and
  macOS were not probed; the rule changes nothing where text is not hinted.
- **`e2e:2origin` builds the hub twice per run**: `stageTwoOrigins()` runs at config load, and
  Playwright loads the config in the runner and again in the worker (two `compose-hub … Compiled`
  passes in `s3-e2e-2origin.log`). Pre-existing; it costs ~30 s.
- **Worktree state:** `export/out` holds the last shot build (the hub, reading the primary's
  `hub-sites.json` through the link); `export/.2origin/` holds a hub build (~2.5 GB, gitignored);
  `homepage/public` holds copied data (gitignored). The worktree's `export/public` links are intact
  and `sw.js` is a copy.

**Review fixes** (review verdict SHIP AFTER FIXES, `$T/s3-review.md`; the code was approved, the
must-fix and should-fix were in the runbook). `main` was fast-forwarded to `5a433aa9` first.
- **Must-fix, the ancestor check.** The runbook checked that `b9772e53` (S2's merge) was on `main`, so
  it passed while S3 was not merged, and step 1.2's `git log -1` could not tell the two apart. It now
  checks that the brand's FINAL commit (this record's tip) is an ancestor of the primary's HEAD, at the
  top of step 0 and in step 1.2, with a STOP banner when it is not; every rollout script refuses to run
  without it.
- **Should-fix, fail-stop scripts.** Every script is `set -eu` with an explicit guard on each step that
  must stop the run, and prints its real status (no unconditional `exit=0`). `r10-home.sh` never deploys
  after a failed build (`homepage/out` still holds release 9's build, and `deployHomepage` only checks
  `out/index.html` exists) and refuses a `homepage/out` without `data-accent`. `r10-sites.sh` stops
  before the hub when the sites run fails, and names a skipped site's `"reason"` (exit 1).
  `r10-restart.sh` refuses while `editor/.next` is still the pre-brand `P0VMdKX7gbdsaiS5GvorF` unless
  `--force`, and fails on a non-200 or any ZodError. Step 1.4 says: `BUILD_FAILED` → stop, do not
  restart; and restart right after the build (a build into the live `.next` can break chunks the old
  server has not loaded). A new `r10-rollback-editor.sh` (after `git switch --detach 0213f6c8`) shares
  the restart checks.
- **Runbook nits.** The smoke's ZodError line (it reads the r8 log name) is explained;
  step 2's md5 check filters to `site.json` (a runner may stamp a `config.json`); the hand commit covers
  `editor/CHANGELOG.md` when the editor notes are cut too, and the homepage's `/changelog` renders the
  export changelog; the settings table says "unset", not `None`.
- **Test nits** (`85cf6e81`). `themeTokens.test.ts`'s parser comment names the nested `@media` rule. The
  service-worker test's "failed online icon fetch" case duplicated the first test's offline half; it
  now covers the other branch, a failed fetch with nothing cached, which answers `Response.error()`.
  Common stays **1,913**; tsc clean.

**Runbook:** `~/reports/release-10/RUNBOOK.html`, generated by `~/reports/release-10/make-runbook.py`
(the release 8/9 generator's shape; screenshots embedded as base64). It writes the rollout scripts to
`~/reports/release-10/scripts/` (`r10-build`, `r10-restart`, `r10-preview`, `r10-sites`, `r10-home`,
`r10-live-check`), release 9's procedure parameterised, logging to `~/reports/release-10/tmp/`.

## Operator rollout (after merge)

The runbook is `~/reports/release-10/RUNBOOK.html` (generated by `make-runbook.py` beside it, which
also writes the rollout scripts to `scripts/`); the release record is
[`release-10.md`](release-10.md). The commands below were checked against the repo (S3).

0. Cut `export/CHANGELOG.md`'s `[Unreleased]`: it is rendered on every site's public `/changelog`.
   `/sites` → Release notes → Cut release; untick "Commit changelog" while the primary has untracked
   files (it refuses a dirty tree) and commit `export/CHANGELOG.md` by hand.
1. Restart the live :3001 editor on the new `main` (release 9's procedure: md5 before / pre-restart /
   after-boot, one editor restart, smoke; umtool untouched); it needs S0's form.
2. In the editor's site form (`/sites/<id>`, the one writer; never hand-edit `transcripts/`), set
   accent and wordmark lead:

   | Site | Accent | Wordmark lead |
   |---|---|---|
   | jeralyzer | brass | Jer |
   | rekietalyzer | vermilion | Rekieta |
   | hasanalyzer | violet | Hasan |
   | anilyzer | sakura | Ani |
   | bonnellyzer | blue | Bonnell |
   | jasolyzer | green | Jaso |

3. Preview Anilyzer: `pnpm ops build-deploy --json
   '{"siteId":"anilyzer","skipArchives":true,"preview":"brand"}' --wait` →
   `https://brand.anilyzer.pages.dev` (`deploy-site` / `archilyzer deploy site` ship an ALREADY-built
   `export/out`, so they need a build first). Check the favicon, the picker, and the migration from a
   stored old theme (on the preview origin, seed the legacy keys in the console; the real phone test
   is on the production origin after step 4). The installed PWA's icon updates only on production.
4. Build and deploy every site by name: `pnpm ops build-deploy --json
   '{"siteIds":["jeralyzer","anilyzer","bonnellyzer","hasanalyzer","rekietalyzer"],"skipArchives":true}'
   --wait --wait-timeout 7200`; then the hub (`pnpm ops build-hub --json '{"deploy":true}' --wait`)
   and the homepage (`pnpm --filter yt-dlp-transcript-common exec tsx bin/archilyzer.ts build
   homepage`, then `… deploy homepage`). `pnpm ops` needs `WORKER_TOKEN` from `editor/.env`.

## S4 — Archilyzer Media, the YouTube channel (approved 2026-09-26)

On 2026-09-25 the operator asked for branding for **Archilyzer Media**, their YouTube channel for
the videos, and approved the design on 2026-09-26. It is on the canvas (version 14):
https://claude.ai/artifact/UsUxwgRkP5a3m4jZXucAvG, in the row "Archilyzer Media · the YouTube
channel". The generators are `node_modules/.brand-canvas/{gen,gen_media}.py` in the primary checkout.

S4 ships after release 10's cut and is **not part of the site rollout**: it touches only a CLI in
`common/bin` and umtool.

### Decisions (operator, 2026-09-26)

- **Mark M2 · Signal.** The parent mark's geometry, lit in Signal: ground `#151b20`, dim `#3f4c56`,
  lit `#5fa8a0`. (Dim `#586977` since 2026-09-27, with the parent mark's; see "The design".) The avatar uses the maskable variant (scale 0.8 on full-bleed ground).
- **Lockup "flush · caps matched".** The `Archi|lyzer` wordmark sits over `MEDIA`:
  - Both are Archivo at wdth 118. The wordmark is 720 / 380 at -0.01em; MEDIA is 700, in Signal.
  - MEDIA's size is **1.035×** the wordmark's, and it is letter-spaced to exactly the wordmark's
    width.
  - Measured with fontTools on `Archivo[wdth,wght]`: "Archilyzer" is 5.334 em and "MEDIA" is
    3.953 em. So MEDIA's capitals match the wordmark's cap height (0.686 em), with 0.30 em between
    letters.
  - The mark's height equals the text block's (wordmark cap top to MEDIA baseline), about 1.70× the
    wordmark size, with a 0.46× gap.
  - On the banner at 2560 px: wordmark 124 px, MEDIA 128 px, text width 661, mark 210. The block
    is centred on the safe area.
- **Unchanged from the proposal:** the banner (a field of dim transcript lines wrapping around a
  clear gutter round the safe area, the lockup centred in it, one lit found line with a play head in
  the desktop strip right of the safe area); the Studio watermark (`any` variant); the burned-in mark
  leading the clip header; the title card, end card and thumbnail layouts of the *in the video*
  board.

### What S4 delivers

1. **`common/lib/brandMedia.ts` (pure).**
   - `MEDIA_PALETTE`, `MEDIA_RATIO = 1.035`.
   - `mediaLockupSvg({px, palette})`: a standalone SVG with **the text as outlined paths**, so
     rendering the lockup needs no font (rsvg-convert, satori `<img>`, ImageMagick).
   - The outlines come from a checked-in, generated `common/lib/brandMediaGlyphs.ts` (do-not-edit
     header): glyph paths and advances at wdth 118 for `Archi` 720, `lyzer` 380 and `MEDIA` 700,
     plus kerning pairs if the font has them.
   - The generator is `common/bin/gen-media-glyphs.py` (fontTools instancer; the repo already has
     Python tools). It downloads `Archivo[wdth,wght].ttf` from google/fonts; the font is not
     committed.
2. **The YouTube channel assets:** `common/bin/brand-media.ts --out <dir>`. The default dir is
   `~/reports/archilyzer-media/brand/`. It writes, each with its SVG source:
   - `avatar-800.png`;
   - `watermark-150.png`, with transparent corners;
   - `banner-2560x1440.png`, ≤ 6 MB;
   - `banner-safe-1546x423.png`, the part every device shows.

   It also writes `INDEX.html` (operator rule: handoffs are HTML), with a preview of each asset,
   its size, and the YouTube Studio upload steps: Customization → Profile (formerly Branding) →
   Picture / Banner image / Video watermark → Change (or Upload).
3. **The umtool report-to-video brand preset: opt-in, and nothing else moves.**
   - **How it's enabled:** a manifest opts in (e.g. `render.brand: "archilyzer-media"`). The preset
     sets `render.palette` (bg `#151b20`, fg `#e7edf1`, muted `#8496a2`, accent `#5fa8a0`, amber
     `#e3b15c`) and the fonts: Archivo at wdth 118 for display, Plex Sans for body, Plex Mono for
     the header and meta lines.
   - **Title card:** the lockup top-left; the title in Archivo 118% 720; the found line (play head
     + lit bar) under it; a Plex Mono meta line.
   - **Clip header:** the mark leads the existing `Channel · title · date @ time` header, burned in.
   - **End card:** new, and only with the preset. The lockup and `archilyzer.pages.dev` on the
     left; the right half kept clear for YouTube's end-screen elements (nothing drawn there). The
     duration is configurable, default 20 s.
   - **Thumbnail step:** 1280×720 from a clip still plus a headline, per the board. The mark is
     top-left, and the bottom-right is kept clear for the duration badge.
   - **Fonts are vendored (OFL), not system-installed.** Archivo variable, IBM Plex Sans and IBM
     Plex Mono go under `umtool/report-to-video/fonts/` with `OFL.txt` and a `fonts.conf`.
     - The preset points `FONTCONFIG_FILE` at that conf for its `magick`/`rsvg-convert` children.
     - Pango takes `@wght=…,wdth=118` variations (Pango 1.58 here).
     - ffmpeg `drawtext` takes `fontfile=` paths, and needs static fonts only.
     - Fallback: `fonts/install-user-fonts.sh` into `~/.local/share/fonts`, which needs no sudo.
   - **Surface:** if umtool has a render/project settings surface, the preset is a choice there
     (operator rule: umtool evolves with the video); otherwise it is manifest-only, and the report
     says so.
   - **Hard rule: byte-identical when not opted in.** The live umtool (:3050) spawns
     report-to-video scripts from disk, so a manifest that does not opt in must render
     **byte-identical** cards before and after. Prove it on an existing manifest's cards.

### Gates

- tsc.
- Unit tests: common, editor, `test:scripts`, mcp, and the report-to-video tests.
- **The lockup's geometry:** the MEDIA advance equals the wordmark advance within 0.5%, and the
  block sits inside the banner's safe area.
- **The PNGs:** the IHDR sizes are right, and the banner is ≤ 6 MB.
- **The before/after card diff** for a manifest that does not opt in.
- **A rendered sample:** title card, a clip header frame, end card and thumbnail for a small
  fixture manifest. Look at each one.
- umtool e2e if umtool's code is touched (`SONG_DIR=~/reports/quartering-uh-song/data pnpm
  --filter umtool run e2e`, queued).

### Slice S4, as shipped — Archilyzer Media (2026-09-26)

Branch `brand/media` off `main` at `4e5630aa` (worktree `../brand-media`, port block #3). S4 gives the
operator's YouTube channel its assets and gives umtool's report videos an opt-in brand: a pure
`common/lib/brandMedia.ts` (the lockup with its letters as outlines, the banner, mark M2), a CLI that
renders the channel's four PNGs and an `INDEX.html` handoff, and a report-to-video preset behind one
manifest key. **A manifest without the key renders byte-identical** (334 files compared, below). No
site, export, homepage or editor app file changed; `common/lib/brandIcons.ts` gained
`renderSvgPng`, which `renderIconPng` now calls (the nine icon PNGs checked, byte-identical).

**The lockup, measured rather than drawn.**
- `common/bin/gen-media-glyphs.py` (fontTools instancer; reads the Archivo umtool vendors, or
  `--download`) writes `common/lib/brandMediaGlyphs.ts` (do-not-edit header, font sha256): per glyph
  the advance, the ink box and the outline (y down, baseline 0), for `Archi` 720, `lyzer` 380 and
  `MEDIA` 700 at wdth 118, plus GPOS pair kerning inside each run (`rc` -14, `ze` -20; none in MEDIA).
  The instanced cap height is 686 for all three weights.
- The spec's 5.334 em is Σ advances − 0.01 em × 10 letters **without** kerning; a browser kerns, which
  gives 5.300. `mediaLockupGeometry` keeps the spec's width (the canvas's `textLength`) and places the
  kerned glyphs with one uniform adjustment per gap (−7.33 units), exactly what
  `lengthAdjust="spacing"` did on the canvas. MEDIA at 1.035× then gets **0.3002 em** between letters,
  matching "0.30 em".
- Block = cap line to MEDIA's baseline = (0.686 + 0.30 + 0.686 × 1.035) px = 1.696 px; the mark is that
  tall, 0.46 px from the text. At the banner's 124 px: MEDIA 128.34, text 661.4, mark 210.3, block
  centred on the safe area at (815.6, 614.8) — the canvas had (817, 615) from hand-rounded numbers.
  `h`, `i`, `l` rise 0.038 em above the cap line; the SVG adds that on top (`inkTop`) so nothing clips.
- The banner's field is a **port** of the canvas generator, not a transcription: `PyRandom` is
  CPython's MT19937 + `init_by_array` + `_randbelow`, and the test pins its first uint32s, the first
  `choice`s and the 87 lines against the Python output of `gen_media.py`'s `banner()`.

**`common/lib/brandMedia.ts`** (pure; imports `brand.ts` and the glyphs): `MEDIA_PALETTE`
(ground `#151b20`, dim `#3f4c56`, lit/media Signal `#5fa8a0`, fg `#e7edf1`, muted `#8496a2`, amber
`#e3b15c`), `MEDIA_MARK_PALETTE`, `MEDIA_RATIO = 1.035`, `mediaLockupGeometry(px)`,
`mediaLockupSvg({px, palette})` (reuses `markSvg`, re-rooted as a nested `<svg>`), `MEDIA_BANNER`,
`mediaBannerField`, `mediaBannerLayout`, `mediaBannerSvg({view?})`, `mediaMarkSvg(variant)`, and
`mediaVideoKit()` — the JSON the umtool preset reads, since its scripts are plain `node`.

**`common/bin/brand-media.ts`** (`--out`, default `~/reports/archilyzer-media/brand/`; `--video-kit`
rewrites `umtool/report-to-video/brands/archilyzer-media.json`). Rendered through `renderSvgPng`
(next/og) under tsx with no trouble, so rsvg-convert was not needed. Run for real:

| file | IHDR | bytes |
|---|---|---|
| `avatar-800.png` (maskable) | 800 × 800 | 19,730 |
| `watermark-150.png` (`any`, transparent corners) | 150 × 150 | 2,753 |
| `banner-2560x1440.png` | 2560 × 1440 | 117,254 (limit 6 MB) |
| `banner-safe-1546x423.png` | 1546 × 423 | 33,534 |

plus `avatar.svg`, `watermark.svg`, `banner.svg`, `banner-safe.svg` (the same drawing with viewBox
`507 508.5 1546 423`), `lockup.svg` and `INDEX.html` (previews, sizes, Customization → Profile
(formerly Branding) → Picture / Banner image / Video watermark → Change, then Publish). All four PNGs
and the page were looked at.

**The umtool preset** (`render.brand: "archilyzer-media"`; README "The Archilyzer Media preset").
- `brand.mjs`: `resolveBrandRender` (owns `palette` and `fontRegular` = vendored Plex Mono; resolves
  `render.endCard` — default 20 s, a number, `{seconds, url}` or `false`), `brandManifest` (appends
  `{type:"card", id:"end", style:"end", hideRail:true, chapter:"End"}` unless the timeline has its own
  end card; an unrelated `end` id is an error), `brandFaces`, `childOpts` (FONTCONFIG_FILE on the
  preset's own `magick`/`rsvg-convert` children), `brandHeaderGeometry`. Every one returns its input
  object itself when there is no brand. `brand-ids.mjs` holds the ids alone, because umtool's
  registry is read by client components and must not pull `node:fs`.
- The hook is **the end of `selectVariant`**, the one door the build, verify-build, compose-chrome and
  umtool's export all use — so all of them agree the end card exists.
- `brand-cards.mjs`: the title card (lockup top-left at the board's 34 × 2.424; the title in
  `Archivo @wght=720,wdth=118` at 97 px, line height 1.08, from y 412; `sub` in Plex Sans; the found
  line; a Plex Mono `meta ?? foot` line), the end card (lockup at 68 px + `archilyzer.pages.dev`,
  centred with room for the subscribe element; a guard throws if the column reaches the right half),
  the header mark PNG, and `renderThumbnail` (still cover-cropped into the left 711 px, the headline
  in Archivo 800 from 78 px shrinking by 8 % until it clears the duration badge and no word overflows,
  refused below 44 px; the mark at 29,29).
- `render-cards.mjs`: `renderCard` routes title/end to the preset when branded; `span` takes a Pango
  `face` (only ever passed when branded), so chapter / bullets / sources / timeline / footer labels
  take the preset's faces with their layouts unchanged.
- `build-video.mjs`: `headerFilters` (the unbranded tick + drawtext, verbatim; branded: two drawtexts
  in Plex Mono 20 px, the channel drawn again in the foreground over the line's head — same glyphs,
  same origin, no measuring); the mark (34 px in the 56 px header, at x 90 where the tick was) is the
  LAST ffmpeg input, so every unbranded input index is unchanged; `--thumbnail` and a thumbnail after a
  full branded build when `manifest.thumbnail` is set (`{headline, clip?, at?, still?}`; the frame
  comes from the cached window, never the network; `.jpg` too if the PNG passes 2 MB).
- **Surface:** umtool has no render settings UI; the new-project form is where a report video's
  render block is born, so the brand is a select there (declared in the registry as a scaffold field
  with `brands`, the menu renders it from data) and `umtool new --brand archilyzer-media`. No brand
  writes the skeleton it always did.
- **Not branded, on purpose:** the rail, `ledger`, `scroll` and `chart` SVG text stays Fira Sans —
  `fit()` truncates against Fira's measured 0.50 em average, and swapping the face without
  re-measuring would overrun columns. The palette does apply.
  *(CLOSED 2026-09-28 by release 11 slice O5, `main` `15d5d646`: under the preset the rail, ledger,
  scroll and chart are IBM Plex Sans, fitted by the face's own advances — `svg-faces.mjs`,
  `face-metrics.mjs`; an unbranded render is byte-identical. `release-11.md`, "Slice O5, as
  shipped".)*

**Fonts** (`umtool/report-to-video/fonts/`, committed unmodified from google/fonts; Plex carries the
Reserved Font Name "Plex", so it may not ship subset or modified):

| file | bytes | source |
|---|---|---|
| `Archivo[wdth,wght].ttf` | 658,596 | `ofl/archivo` @ `95f4904f` |
| `IBMPlexSans[wdth,wght].ttf` | 537,244 | `ofl/ibmplexsans` @ `0b58fb37` |
| `IBMPlexMono-Regular.ttf` (static, for drawtext) | 135,580 | `ofl/ibmplexmono` @ `0b58fb37` |
| `OFL.txt` (both upstream OFL files, verbatim) | 8,846 | |

1.33 MB of fonts in all. No italics, no other Plex Mono weights: nothing draws them. `fonts.conf`
adds the directory and includes the system config (fallback for emoji / CJK, and its cache dir);
`install-user-fonts.sh` is the no-sudo fallback.
*(2026-09-28, release 11 O5: the table gains `IBMPlexMono-Bold.ttf`, 137,784 B, `ofl/ibmplexmono` @
`0b58fb37`, unmodified; the fonts are about 1.5 MB in all, and `fonts.conf` resolves `IBM Plex
Mono:bold` to it.)*

**The byte-identity proof** (`$T/s4-identity.mjs`, `$T/s4-idiff.mjs`). Before any report-to-video
change, the harness rendered, into `$T/s4-before/`: every card, footer, rail, ledger, scroll and chart
asset of five real manifests (`elfpire-eva-lawyer`, `quartering-christian`,
`quartering-employee-count`, `ferret-rescue`, `destinys-child`; both variants; 70 render calls; the
manifests read, never written) plus each resolved `render` block, and a full offline build of a
fixture (local corpus, cached windows made with `ffmpeg -f lavfi`: title / chapter / sources cards,
two clips with header, footer, marker and QR, an image entry, xfade, chapters) — **334 files**. The
same harness after the preset, on the final tip `782eb48e`: **334 files, 201 raw byte-identical, 133
identical but for ImageMagick's three `tEXt date:*` chunks, 0 different, none missing or extra.**
- ImageMagick stamps the wall clock into every PNG and ignores `SOURCE_DATE_EPOCH`, so the control —
  the UNCHANGED code run twice — already differs in exactly those 133 files in exactly those chunks
  (`$T/s4-before` vs `$T/s4-before2`: 201 / 133 / 0). The diff drops only `tEXt` chunks whose key
  starts `date:` and `tIME`; IHDR, IDAT and every other byte are compared.
- The seven mp4s (six segments and the cut) are raw byte-identical: x264 is deterministic here.

**Samples** (the branded fixture, `$T/s4-fixture/brand`, built offline): `$T/s4-sample-title.png`,
`s4-sample-clip-header.png` (+ `-zoom`), `s4-sample-image-header.png`, `s4-sample-end.png`,
`s4-sample-thumbnail.png`, `s4-sample-chapter.png`, `s4-sample-sources.png`. Each was looked at
against the canvas's *in the video* board. The first header had the mark 5 px low and small beside the
text; it is now 0.6 of the header, the capitals centred on it (drawtext `y` is the top of the tallest
glyph, so it is set from Plex Mono's 0.74 em ascender and 0.698 em cap height).

**Tests.**
- `common/lib/brandMedia.test.ts` (7): the palette and mark M2 = `markSvg`; the measured widths
  (5.334 / 3.953 / 686); **MEDIA's advance = the wordmark's within 0.5 %** at 18/28/64/124 px, 0.30 em
  spacing, block ≈ 1.70×, both lines flush; **the lockup's block and ink boxes inside the banner's safe
  area**, centred, and every field line clear of the gutter; `PyRandom` = CPython; SVG shape; **the
  glyph file = a fresh `gen-media-glyphs.py --stdout`** (skips without python3 + fontTools).
- `common/bin/brand-media.test.ts` (3): the asset list; `writeMediaAssets` into a temp dir — every
  IHDR, the banner ≤ 6 MB, sources and INDEX; the committed video kit = `--video-kit`'s output.
- `umtool/report-to-video/brand.test.mjs` (10): no brand → the same objects back from every hook,
  `selectVariant`'s pre-preset shape, the unbranded header strings pinned literally; the preset's
  render, `endCardConfig`, the end card rules, the branded header, the fonts and OFL, the kit; a guarded
  render (title and end at 1920 × 1080, the end card's right half one colour, the thumbnail 1280 × 720
  with the badge corner one colour).
- `umtool/e2e/projects.spec.ts` +1: `umtool new --brand` writes `render.brand` (and still the palette),
  no brand writes none, a bad brand exits non-zero; the form's brand select defaults to "no brand",
  offers "Archilyzer Media", and creating with it writes `render.brand`.

| sha | what |
|---|---|
| `fe053e74` | umtool: vendor Archivo, IBM Plex Sans, IBM Plex Mono Regular + `OFL.txt`, `fonts.conf`, `install-user-fonts.sh` |
| `598fe502` | common: `brandMedia.ts`, `brandMediaGlyphs.ts` (generated), `bin/gen-media-glyphs.py`, tests |
| `6d27814f` | common: `bin/brand-media.ts` (+ test), `renderSvgPng` in `brandIcons.ts`, the video kit JSON |
| `a91d6527` | umtool: the report-to-video preset (`brand.mjs`, `brand-ids.mjs`, `brand-cards.mjs`, render-cards / build-video hooks, README, tests) |
| `c2483ebf` | umtool: the brand choice in the new-project form and `umtool new --brand`, e2e +1 |
| `782eb48e` | common: INDEX.html's timestamp says UTC |

**Gates.**
- tsc (`pnpm -r … tsc --noEmit`): clean before the common commits (59 s) and on the umtool tree (88 s);
  common's own tsc before the two later common commits.
- common **1,923/1,923** (1,913 + 10); editor unit **79/79**; `test:scripts` **172 + 1 skip** (162 +
  10); mcp **219/219**.
- Builds: `pnpm --filter editor exec next build` ok (69 s); `pnpm --filter umtool run build` ok (22 s).
  The umtool bundle keeps `brand.mjs`'s `import.meta.url` as the source path
  (`file://${P("umtool/report-to-video/brand.mjs")}`), so the kit and fonts resolve in the server too.
- umtool e2e, full suite (`SONG_DIR=~/reports/quartering-uh-song/data node scripts/worktree.mjs run --
  pnpm --filter umtool run e2e`, from the worktree): **175 passed, 2 failed, 45 skipped**, 4.5 min
  after 17.5 min in the queue. The new `projects.spec.ts:506` passed. The two failures are
  `mix.spec.ts:166` and `:201`, the pair FACTS.md ("The umtool suite skips instead of going red…")
  records as failing in every full run on main (order-dependent clip windows in the fixture); the 45
  skips are the song-data capabilities this machine lacks.
  Alone, `mix.spec.ts`: **12 passed**, 24 s (after 1.5 min in the queue), `:110`, `:166` and `:201`
  included.- The identity diff: 334 files, 0 different (above).
- Numbers tools: none.

**Found and left.**
- `render-cards.mjs` sets `-define pango:width=…`, which this ImageMagick (7.1.2) ignores; the wrap
  comes from `-size`. Harmless, and untouched (it is in the unbranded path).
- ImageMagick's pango coder lays out at 96 dpi: `-density 72` makes 1 pt = 1 px but wraps at ¾ of the
  `-size` width. The preset sizes in px through `pt(px) = 0.75 px`.
- `render.fontBold` is left as the manifest has it under the preset: only compose-chrome's HyperFrames
  band reads it, and no Plex Mono bold is vendored.
  *(CLOSED 2026-09-28 by release 11 O5: `fonts/IBMPlexMono-Bold.ttf` is vendored, from the same
  google/fonts commit, and `resolveBrandRender` sets `fontBold` to it.)*
- umtool's project page lists the raw timeline, so the appended end card is built and chaptered but
  not listed there.

**Review fixes** (verdict SHIP AFTER FIXES, `$T/s4-review.md`; the three rulings — automatic end card,
rail/ledger/chart on Fira, no bold Plex Mono yet — stand; the last two were closed on 2026-09-28 by
release 11 O5).
- `387a8233`, should-fix + nit 4:
  - INDEX.html's Studio steps now say **Customization → Profile (formerly Branding)**, then the
    asset's **Change** (Upload if it has none), linking YouTube Help "Manage your channel branding"
    (answer 10456525): Branding was folded into Profile. The test pins the new words; this plan's
    two mentions are corrected.
  - `brandMediaGlyphs.ts` records the fontTools it was generated with (`4.65.0`); the parity test
    skips, with the reason in the output, when another version is installed (checked with a fake
    `python3` on PATH: `# SKIP fontTools 0.0-fake is installed; … generated with 4.65.0`).
- `fde57d46`, nits 2, 3, 5:
  - `endCardConfig(null)` is off, like `false`, so resolving a render block twice keeps an
    ended-off card off (test +1);
  - the header mark is `_mark-<size>-<sha256(kit svg)[:12]>.png`, so a regenerated kit is never
    answered by a stale PNG (asserted in the guarded render test);
  - `umtool doctor` lists `rsvg-convert` as needed by the brand preset too.
- Nit 6: `release-10.md` says S4 *merges* after the cut.
- Gates: tsc clean (49 s); common **1,923/1,923**, editor unit **79/79**, `test:scripts` **173 + 1
  skip**, mcp **219/219**; `pnpm --filter umtool run build` ok. The identity diff re-run on the fixed
  tree anyway (the non-brand path is untouched): **334 files, 201 raw + 133 date-chunk-only, 0
  different**. The branded fixture rebuilt (same 3,631,785-byte cut). The real assets were
  regenerated: every PNG and SVG byte-identical to the first run, only `INDEX.html` changed. No e2e:
  the one umtool app line is a `neededBy` label no spec reads.

**Merged** to `main` 2026-09-26 as `dcb04f61` (S4, then L2, then L1), and gated with L1 and L2 on the
merged tree: [`release-10.md`](release-10.md), "Integration (S4 + L1 + L2), as merged". Its rollout step
is the optional umtool rebuild (`~/reports/release-10/scripts/r10-umtool.sh`).