jekyll-theme-zer0 1.29.0 → 1.30.0

data/CHANGELOG.md

@@ -12,6 +12,92 @@ hand-written prose covering the same releases in more depth; they sit below
 their version because release-please inserts each new release at the top of the
 file. Only `## [Unreleased]` describes work that has not shipped yet.
 
+## [1.30.0](https://github.com/bamr87/zer0-mistakes/compare/v1.29.0...v1.30.0) (2026-09-12)
+
+
+### Features
+
+* **ci:** produce visual evidence and baselines on PRs, not just verify them ([#462](https://github.com/bamr87/zer0-mistakes/issues/462)) ([a377fae](https://github.com/bamr87/zer0-mistakes/commit/a377fae6ea31a0bb015479dea6d1a7c41e141c3f))
+* **includes:** add background-image.html for CSS-painted cover art ([#451](https://github.com/bamr87/zer0-mistakes/issues/451)) ([9b15a67](https://github.com/bamr87/zer0-mistakes/commit/9b15a673f57b8f7f1f9dae9262191742d99d8080))
+* **includes:** Claude or Grok sessions in the Site Builder ([#473](https://github.com/bamr87/zer0-mistakes/issues/473)) ([e1c5753](https://github.com/bamr87/zer0-mistakes/commit/e1c57531fc23be8d071757cd1941e1ae15285da7))
+* **includes:** file the fleet issue contract from the feedback widget ([#472](https://github.com/bamr87/zer0-mistakes/issues/472)) ([24d4e2c](https://github.com/bamr87/zer0-mistakes/commit/24d4e2c6380541a894e9e671f0f0b0b859a29b05))
+* **includes:** make theme-color track the page surface, not the accent ([#447](https://github.com/bamr87/zer0-mistakes/issues/447)) ([f1fda85](https://github.com/bamr87/zer0-mistakes/commit/f1fda857bb0cf5bd64bebfc1215ba0a906f05e5c))
+* **includes:** themed Mermaid figures + toolbar ([#455](https://github.com/bamr87/zer0-mistakes/issues/455)) ([96776fa](https://github.com/bamr87/zer0-mistakes/commit/96776fa48bbe7b63058d1d246962019c745d7b93))
+* **scripts:** adopt the shared ai-runner kit for claude-run; consumers registry fixes; hub baseline ([#475](https://github.com/bamr87/zer0-mistakes/issues/475)) ([feb4133](https://github.com/bamr87/zer0-mistakes/commit/feb41332eb15d2c13fe0c0f6d15b61007e14daa3))
+
+
+### Bug Fixes
+
+* **a11y:** decouple heading size from heading level in theme chrome ([#450](https://github.com/bamr87/zer0-mistakes/issues/450)) ([bb92eb5](https://github.com/bamr87/zer0-mistakes/commit/bb92eb583c955e76339a9c7ab98532b35e226b36))
+* **a11y:** give footer icon links an accessible name, announce search results ([#441](https://github.com/bamr87/zer0-mistakes/issues/441)) ([a1811e8](https://github.com/bamr87/zer0-mistakes/commit/a1811e81ac0c17b0836994be7c48eba51252bae7))
+* **a11y:** stop emitting sidebar/TOC controls on layouts that render no offcanvas ([#443](https://github.com/bamr87/zer0-mistakes/issues/443)) ([619322d](https://github.com/bamr87/zer0-mistakes/commit/619322d8fd7c6e2a700ba154e065bf65caf67461))
+* **ci:** run the autogen lane's tooling from the base branch, not the PR ([#464](https://github.com/bamr87/zer0-mistakes/issues/464)) ([8473050](https://github.com/bamr87/zer0-mistakes/commit/8473050be2b4ddfd994c7bea8a8c35e37a66b7f8))
+* **ci:** stop the UI audit reporting a measurement blackout as a clean run ([#471](https://github.com/bamr87/zer0-mistakes/issues/471)) ([ab92619](https://github.com/bamr87/zer0-mistakes/commit/ab9261946e088417dabe4291590da1c7a964d4fa))
+* **content:** raw-protect Liquid that is written as documentation ([#446](https://github.com/bamr87/zer0-mistakes/issues/446)) ([6123c1f](https://github.com/bamr87/zer0-mistakes/commit/6123c1f1e6ffd167376d4ef421b0a9f78af3985e))
+* **includes:** declare charset inside the 1024-byte window, make the feed discoverable ([#440](https://github.com/bamr87/zer0-mistakes/issues/440)) ([4025205](https://github.com/bamr87/zer0-mistakes/commit/40252050ec21c70aa1d84820fdcde6d564e03478)), closes [#372](https://github.com/bamr87/zer0-mistakes/issues/372) [#371](https://github.com/bamr87/zer0-mistakes/issues/371)
+* **includes:** expose skin-button selected state via aria-pressed ([#469](https://github.com/bamr87/zer0-mistakes/issues/469)) ([6579b16](https://github.com/bamr87/zer0-mistakes/commit/6579b1621a5eff147e224977633728aadc960505)), closes [#467](https://github.com/bamr87/zer0-mistakes/issues/467)
+* **install:** stop seeding the theme's own navigation into consumers ([#449](https://github.com/bamr87/zer0-mistakes/issues/449)) ([232857c](https://github.com/bamr87/zer0-mistakes/commit/232857c66d7c3abccb166b5151a7f80a74dd17ca))
+* **navigation:** scroll spy bolds the section actually being read ([#456](https://github.com/bamr87/zer0-mistakes/issues/456)) ([5ff38bf](https://github.com/bamr87/zer0-mistakes/commit/5ff38bf98faf96cdc3bf63ea3f0e7b10e21f3aab))
+* **sass:** stop navbar controls flickering under a stationary pointer ([#453](https://github.com/bamr87/zer0-mistakes/issues/453)) ([fc84b9a](https://github.com/bamr87/zer0-mistakes/commit/fc84b9a4c714f8e04b8a0f940bed9e3795c144bc)), closes [#404](https://github.com/bamr87/zer0-mistakes/issues/404)
+* **scripts:** restore nested translation placeholders instead of leaking them ([#452](https://github.com/bamr87/zer0-mistakes/issues/452)) ([00cab73](https://github.com/bamr87/zer0-mistakes/commit/00cab73d915f4e116040ef6ca4c0381669ae4eb2))
+
+
+### Performance Improvements
+
+* **ci:** run the critical PR gate on 3 workers instead of 1 ([#481](https://github.com/bamr87/zer0-mistakes/issues/481)) ([b3fcbc7](https://github.com/bamr87/zer0-mistakes/commit/b3fcbc76a1af2a3a5e43eb28fbff7b3057751de6))
+* **includes:** strip developer doc banners from delivered HTML ([#445](https://github.com/bamr87/zer0-mistakes/issues/445)) ([89b10f1](https://github.com/bamr87/zer0-mistakes/commit/89b10f1ff361c919fd631d0e7e664ed6d7c28a14))
+
+## [Unreleased]
+
+### Changed
+
+- **`claude-run` is now the fleet's shared `ai-runner` kit.** The composite
+  action and its new `scripts/ai/run.sh` are byte-identical copies of
+  lifehacker.dev's (the kit source of truth) instead of a hand-rolled variant.
+  What changes for the two callers (`issue-autopilot.yml`,
+  `visual-evidence-autogen.yml`): an AI call that was attempted and rejected —
+  revoked credential, exhausted quota, `is_error` payload, CLI install failure
+  — now fails the step with the reason as a `::error::` annotation, where the
+  old action exited 0 and a dead run read green; the OAuth-first rule is
+  enforced with `env -u ANTHROPIC_API_KEY`; the model override is the canonical
+  `AI_MODEL` (or the new `model` input) rather than `ZER0_AI_MODEL`, and
+  `max-turns` is a new input. Metering (`scripts/ai/usage.rb`,
+  `usage_report.rb`, prices in `_data/ai_pricing.yml`) and the Claude API
+  fallback (`scripts/ai/api_call.rb`) ride along as optional companions. The
+  exit-code contract is pinned by `scripts/ci/test_ai_runner.sh`, wired into
+  `./scripts/bin/test`. The action's six existing inputs are unchanged.
+- **`claude-run` is consumed by reference from the hub.** `issue-autopilot.yml` and `visual-evidence-autogen.yml` now call `bamr87/bamr87/.github/actions/claude-run@main` (identical inputs) instead of a vendored `./.github/actions/claude-run`; the local action, `scripts/ai/run.sh`, and the vendored contract test (`scripts/ci/test_ai_runner.sh` + its `scripts/test/lib/` bridge) are deleted, while the consumer companions the hub runner probes for — `scripts/ai/usage.rb`, `usage_report.rb`, `api_call.rb`, `_data/ai.yml`, `_data/ai_pricing.yml`, `tools/unwrap-prose.py` — stay ([bamr87/bamr87#254](https://github.com/bamr87/bamr87/pull/254)).
+- **Consumer registry corrections.** `ai-world-view/ai-world-view.github.io`
+  is `remote_theme_floating` (both its `_config.yml` and `hub.yml` pins are
+  untagged), not `remote_theme_pinned`; `amr-bash/bash-365.com` is registered
+  as a consumer (floating `remote_theme`, unconstrained gem on Azure, path gem
+  for dev).
+
+### Fixed
+
+- **The weekly UI/UX audit was blind, and reported it as clean.** `sweep.mjs`
+  built its pages with `browser.newPage()`, which `@axe-core/playwright`
+  refuses; the throw was caught by a single per-route `try` that also discarded
+  the overflow, console-error and link-collection data already gathered for
+  that route. Screenshots still succeeded, so the harness looked alive while
+  every accessibility, console, overflow and broken-link result on every route
+  was silently dropped — and the report rendered the absence as "0 axe
+  violations / 0 broken links". Pages are now built from `browser.newContext()`,
+  each measurement fails independently, a scan that errored is reported as
+  UNKNOWN rather than clean, and a measurement that fails on every route turns
+  the sweep red the way a total capture failure already did. On the demo site
+  the sweep goes from 18/21 captured with 21 blackout entries to **21/21
+  captured, 0 harness errors, 191 links crawled and 8 genuinely broken links
+  found** ([#468](https://github.com/bamr87/zer0-mistakes/issues/468)).
+- **Theme-skin buttons now announce which skin is applied.** The Theme Skin
+  group in Settings → Appearance conveyed selection only through the Bootstrap
+  `.active` class, which carries no accessibility semantics, so screen readers
+  announced nine identical unlabelled buttons — WCAG 2.1 SC 4.1.2 (Name, Role,
+  Value). Each button now ships `aria-pressed`, and the click and "Reset
+  background" handlers keep it in sync with `.active` through one shared
+  helper, matching the sibling color-mode group
+  ([#467](https://github.com/bamr87/zer0-mistakes/issues/467)).
+
 ## [1.29.0](https://github.com/bamr87/zer0-mistakes/compare/v1.28.0...v1.29.0) (2026-09-01)
 
 
@@ -48,7 +134,556 @@ file. Only `## [Unreleased]` describes work that has not shipped yet.
 
 ## [Unreleased]
 
-### Changed
+### Added
+
+- **Bring your own AI provider — Claude or Grok — and an open, coding-session-style
+  Site Builder (ZER0-087)** — the chat proxy gains a provider layer
+  (`templates/deploy/chat-proxy/providers.js`): xAI's Grok is a first-class
+  provider (`XAI_API_KEY`, `CHAT_PROVIDER`, `XAI_CHAT_MODEL`) for the chat
+  widget, the feedback triage and the Site Builder, translated server-side to
+  and from the Anthropic Messages dialect so no client changed. The Site
+  Builder's Connect step shows which providers the local dev proxy already has
+  keys for (masked), takes a token for the session (sent once to localhost,
+  kept in the proxy's memory, optionally saved to `.env` with mode 600), offers
+  the model catalog, an image renderer (Grok Imagine / OpenAI Images) and two
+  session modes: the guided nine steps, or an open session that can open an
+  existing site under the target root, read/edit/write/delete its files, run
+  `git status`/`diff`/`log`, generate images into `assets/`, run `jekyll build`
+  inside the container and stop a long tool run. Generated sites are
+  pre-configured for the chosen provider (`ai_chat.provider`, `preview_images`,
+  `.env.example`). The dev proxy now starts without a credential. Also fixes a
+  pre-existing 162px horizontal overflow of the whole `/setup/` page at phone
+  widths (the Connect step's command boxes could not shrink). (evidence:
+  [`test/visual/evidence/site-builder-providers/`](test/visual/evidence/site-builder-providers/README.md)
+  — Connect step: 2 provider cards, 2 session modes, token field is a password
+  input inert offline; mocked proxy: "needs a token" → "Grok connected"; Build:
+  existing sites listed, Open sets the target; mobile overflow 162px → 0px)
+- **CI now produces a UI pull request's visual artifacts instead of only
+  checking for them (ZER0-085)** — `visual-evidence-autogen.yml` renders every
+  same-repo PR in the same jammy Playwright image the snapshot gate uses, runs
+  the PR's `test/visual/*-evidence.mjs` generators (or the new generic
+  base-vs-head generator `test/visual/pr-evidence.mjs`, which renders the base
+  branch and the head side by side), verifies the 9-skin baselines, and pushes
+  the montages + `metrics.json` to the branch. Stale baselines are refreshed
+  **only** when the new `visual-evidence-reviewer` agent, having viewed the
+  expected | actual | diff montage, judges the diff to be the change the PR
+  describes — a code step disposes, the model only proposes ([#417](https://github.com/bamr87/zer0-mistakes/issues/417)
+  is why). The evidence gate now requires generated proof (a README alone no
+  longer passes), `ci-self-repair` leaves a red `Visual Snapshots` job to this
+  lane, and `test/update-snapshots.sh` gained `PRE_TEST_SCRIPT` /
+  `POST_TEST_SCRIPT` / `SKIP_PLAYWRIGHT` hooks. Closes the gap that kept
+  [#454](https://github.com/bamr87/zer0-mistakes/pull/454) red: its authoring
+  agents ran where Docker was gated, and nothing in CI could render what they
+  could not. Kill switch: repo variable `VISUAL_EVIDENCE_AUTOGEN_ENABLED=false`.
+  The lane restores its own tooling from the base branch before it runs, so it
+  works on branches cut before it shipped: without that its first real run on
+  #454 died in 20 seconds (that branch has no copy of the orchestrator), and a
+  branch carrying an older `update-snapshots.sh` would have silently generated
+  nothing at all.
+- **Site Builder — a Claude-guided setup wizard that ends with a running site
+  (ZER0-086, extends ZER0-067)** — `/setup/` (and the `welcome` layout) grew
+  from a five-step `_config.yml` form into a nine-step builder: Connect →
+  Prerequisites → Identity → URLs → Structure → Appearance → Voice →
+  Integrations → Build. An embedded Claude session rides alongside every step
+  through the local dev proxy (Claude Code OAuth, `claude setup-token`; the
+  token never reaches the page). It sees the whole wizard state on every turn
+  and acts on it with tools: fill in fields, override a generated file, run
+  live prerequisite checks (Docker, Git, gh, VS Code, Node, Claude CLI — a
+  fixed command table), read the theme's real source and search the docs,
+  resolve a project folder, write the generated project, run `docker compose
+  up|ps|logs|down`, and check the new site answers — each mutation behind a
+  confirmation card. The form half still works with no proxy at all (GitHub
+  Pages included): it generates `_config.yml`, `_config_dev.yml`, `Gemfile`,
+  `docker-compose.yml`, `index.md`, navigation, about page, welcome post, one
+  index page per collection, `.gitignore`, `zer0.install.yml`, `.env.example`
+  and `README.md`, with per-file download and a self-extracting bash bundle.
+  Forms gained a site brief, a URL **Suggest** button, a site-type quick-pick,
+  a navigation row editor, skin cards with a live **Preview on this page**
+  toggle, tone/audience pickers, integration switches with conditional
+  sub-fields, a copy button on every command, and a toast for feedback. New:
+  `_data/site_builder.yml` (steps, prerequisites mirroring
+  `machine-setup.md`, catalogs, framework brief),
+  `templates/deploy/chat-proxy/wizard-store.mjs` (the dev-only sandbox behind
+  `/api/wizard/*`), `assets/js/site-builder.js`, `_includes/setup/{claude-
+  session,prereq-checklist}.html`, the `site_builder:` config block, a
+  quickstart page and a feature reference. (evidence:
+  [`test/visual/evidence/site-builder/`](test/visual/evidence/site-builder/README.md))
+  A first recorded end-to-end run then shaped the build half: the generated
+  `docker-compose.yml` publishes LiveReload on the site's port + 1 (a fixed
+  35729 collided with the theme's own dev container and the new site never
+  started) and shares one gem cache across generated sites; every enabled
+  collection now ships a valid starter document (a doc, a quickstart step, a
+  note with a wiki-link, a structured recipe) and the cookbook index uses the
+  theme's `cookbook` layout over the real `recipes` collection; `_config.yml`
+  sets `collections_dir: pages` (without it every collection but posts was
+  invisible to Jekyll); each site gets its own `assets/images/logo.svg`
+  monogram and gem-based sites turn the SVG background layers off, because
+  the published gem ships no theme images; a revoked Claude credential now
+  says so and names the fix. Validation is a scenario
+  runner, `test/visual/site-builder-walkthrough.mjs`, that samples random
+  briefs per site type (`test/visual/site-builder-scenarios.mjs`), drives the
+  wizard on video, builds the site with Docker and asserts its routes, title
+  and skin — replayable by seed.
+  The builder then gained a **schema-driven site plan**: `plan_schema` in
+  `_data/site_builder.yml` (a JSON-Schema subset validated in the browser)
+  describes what the agent may produce — a landing page (five templates,
+  nine section types, hero + CTAs), navigation shape (flat or grouped
+  dropdowns, sidebar none/auto/docs tree), theme overrides (nine palettes or
+  custom colours, seven font pairings, three corner radii) and up to twelve
+  example pages with Markdown bodies — and the generators turn it into
+  `index.md` (a Liquid landing engine) + `_data/landing.yml`,
+  `_data/navigation/main.yml` and `docs.yml`, `assets/css/user-overrides.css`
+  + `_includes/custom/head.html`, and one file per page. Claude submits plans
+  with `set_site_plan` behind a confirmation card; the Structure and
+  Appearance steps expose the same choices as controls, with a page planner
+  and a **Preview on this page** toggle that applies the generated overrides
+  to the wizard itself. The scenario runner randomises the plan too and
+  asserts the built site's landing template, palette colour, web fonts and
+  planned routes.
+- **Mermaid diagrams are now accessible figures with a toolbar (ZER0-013)** —
+  every ```` ```mermaid ```` fence (and legacy `<div class="mermaid">`) renders
+  as a `<figure>` with a rendered SVG and a small toolbar: zoom out / in / reset
+  (50–400 %, real layout — the SVG is resized, so the frame scrolls and
+  drag-to-pan, `Ctrl`+wheel and the `+` / `-` / `0` keys all work), **View
+  fullscreen** (a native `<dialog>` — the fix for a wide diagram shrunk to
+  illegibility on a phone; `Esc` closes it and focus returns to the opener),
+  **Copy diagram source**, and **Download as SVG** (page background baked in so
+  a dark-mode export stays readable). On pointer devices the toolbar floats over
+  the top-right corner on hover/focus; on touch devices it is a static row above
+  the diagram so it never covers it. `accTitle` becomes the visible
+  `<figcaption>` and the diagram's accessible name, `accDescr` its `<desc>`,
+  and the scrollable frame is a focusable, labelled region. A syntax error no
+  longer blanks the block: the figure shows the parse message, a hint, and the
+  source in a `<details>`, with *copy* still enabled. Colours are **derived from
+  the live design tokens** (`--bs-primary`, `--bs-body-bg`, `--zer0-color-*`)
+  through Mermaid's `base` theme, so diagrams follow the colour mode, the
+  selected skin and any `theme_color` override, and re-render in place when
+  those change; dark mode is decided by background luminance, so wizard mode and
+  dark skins get legible ink, and a contrast guard keeps nodes visible when the
+  brand equals the page colour. Pie slices, git branches and mind-map branches
+  get a 12-colour series fanned out from the brand hue. `securityLevel` now
+  defaults to `strict` (`mermaid.security_level: loose` restores `click`
+  callbacks / HTML labels); `mermaid.toolbar`, `fullscreen` and `download` can
+  switch the controls off. Implemented as `_includes/components/mermaid.html`
+  (loader: config JSON + two `defer` scripts — the 3.3 MB bundle used to load
+  synchronously in `<head>`) + `assets/js/mermaid-diagrams.js` +
+  `_sass/components/_mermaid.scss`, replacing ~400 lines of inline
+  `<script>`/`<style>` in the include; the `!important` SVG overrides that
+  flattened `classDef`/`style` colours and pie slices are gone. Toolbar strings
+  are `diagram_*` keys in `_data/ui-text.yml`. The docs page
+  (`/docs/features/mermaid-diagrams/`) now renders a live example of every
+  diagram type, the caption directive, per-node styling and the error state.
+  Guarded by `test/visual/features/mermaid.spec.js` (12 tests, smoke tier)
+  (evidence: [`test/visual/evidence/mermaid/`](test/visual/evidence/mermaid/README.md)
+  — dark-mode toggle keeps the SVG (before: SVG lost, stylesheet text on
+  screen); page overflow 0px at 320/390px; 11/12 docs diagrams rendered, 1
+  shown as an error card with its source kept).
+
+### Fixed
+
+- **Generated posts and notes were invisible on GitHub Pages** — every dated
+  document the wizard wrote was stamped `T09:00:00.000Z` on the day it was
+  generated. Jekyll refuses to publish future-dated documents unless
+  `future: true`, and GitHub Pages builds with the default, so a site generated
+  before 09:00 UTC went live with its posts and notes missing: linked from the
+  collection index and listed in the sitemap, but 404 when clicked. Generated
+  content is now stamped with the actual moment it was written, and a
+  regression test fails if any generated document carries a future date.
+  Found by publishing two example sites and clicking the links.
+- **Every page of every generated site 404'd on `user-overrides.js`** — the
+  Site Builder writes `user_overrides: true` so the theme loads the palette and
+  font overrides it generates, but that same flag also makes the theme load
+  `assets/js/user-overrides.js`, which the wizard never created. Generated
+  sites now ship a commented stub, so the request resolves and site owners have
+  an obvious place to put their own JavaScript. Found while publishing example
+  sites built by the wizard.
+- **Every generated landing page shipped an invisible button** —
+  `components/cta-button.html` mapped `variant: outline` to `btn-outline-light`,
+  which is white text on a white border, and the Site Builder's own default
+  call to action uses `outline` on a light hero. `outline` is now an outlined
+  *primary* button; `outline-light` is the explicit variant for a dark surface,
+  and the generated landing engine picks between them from `hero.variant`.
+  The theme's own homepage hero is `bg-primary text-white`, so its two
+  outlined buttons moved to `outline-light` and render exactly as before —
+  a consumer who copied `_data/landing.yml` into a site with a dark hero
+  should make the same one-word change.
+- **A planned `landing.hero.image` was accepted and then thrown away** — the
+  site plan's schema has offered `landing.hero.image` since the Site Builder
+  shipped, but the landing engine it generates never rendered it, so an agent
+  (or a human) could set a hero image, see it validated, watch it land in
+  `_data/landing.yml`, and get a landing page with no picture. `index.md` now
+  renders it inside the hero, decorative (empty `alt`) so a screen reader does
+  not hear the headline twice. Found by building a site end to end through the
+  new Grok path, where the "Hero image with …" shortcut pointed straight at the
+  dead field.
+- **A partial hero patch silently wiped the rest of the hero** —
+  `set_site_plan` replaced `landing.hero` wholesale, so the natural agent move
+  of "write the copy now, add the artwork two turns later"
+  (`{landing: {hero: {image}}}`) discarded the headline, subheadline and every
+  call to action, and the landing page quietly reverted to the site title and
+  the default buttons. The hero now merges field by field; `sections`,
+  `navigation.items` and `pages` still replace, because a shorter list has to
+  mean a shorter list. The tool description says so, and the regression test
+  pins both halves.
+
+- **A new post appeared at its own URL but on no index** — the generated
+  `_config_dev.yml` turned on Jekyll's experimental incremental regeneration,
+  which rebuilds only documents whose own source changed. Adding a post left
+  the collection index, the home page's latest-posts list and the feed showing
+  the old set, with the post reachable only by typing its URL. New sites are
+  now generated with `incremental: false`; a full rebuild of a fresh site takes
+  about a second and is always right.
+
+- **The 15-second status poll handed the composer back mid-turn** — the Site
+  Builder's proxy poll rebuilt the panel's enabled state from the connection
+  alone, so during a long action (a Docker build, an image render) the input
+  and Send button re-enabled themselves and the Stop button vanished, while
+  tools were still running. A second message could then interleave with the
+  first. The poll now respects the busy state.
+- **A newly added post never appeared on the running site** — Jekyll's
+  `--watch` only tracks collection documents that existed when `serve` started,
+  so a page or post the assistant added to a running project stayed invisible
+  with no explanation. `write_project_file` now says so in its result and
+  offers a restart, and `run_compose` gained a `restart` action.
+
+- **Switching colour mode destroyed every Mermaid diagram** — the old include's
+  `MutationObserver` re-render emptied each `.mermaid` div and refilled it with
+  the div's *current* text, which after the first render is the SVG's own
+  stylesheet, and never cleared Mermaid's `data-processed` flag, so
+  `mermaid.run()` skipped the div. Toggling dark mode on `/quickstart/`,
+  `/about/` or `/docs/ruby-101/` replaced the diagram with a wall of
+  `#mermaid-… {font-family: …}` text and a permanent "Loading diagram…" label
+  (reproduced headlessly on `main`: `svgs: 1 → 0` after the toggle). Sources are
+  now kept per figure and every render goes through `mermaid.render()`, so a
+  mode or skin change re-renders from the original definition — asserted by the
+  regression test in `test/visual/features/mermaid.spec.js`.
+- **The Obsidian wiki-link resolver rewrote the inside of inline SVGs** —
+  `assets/js/obsidian-wiki-links.js` skips text under `CODE`/`PRE`/`A`/
+  `SCRIPT`/`STYLE` by comparing `nodeName`, but elements in the SVG namespace
+  report it in lower case (`style`, `text`), so a Mermaid diagram's own
+  `<style>` was walked and every `#id` selector in it was turned into a
+  `<a class="obsidian-tag">` link. The stylesheet lost its scoping: one
+  diagram's `#arrowhead path { fill }` became a bare `path { fill }` for the
+  whole page, and pie slices rendered dark grey while their legend showed the
+  right colours. The old include escaped it only because the resolver
+  special-cases the `.mermaid` class. The name check is now case-insensitive
+  and any `<svg>` subtree (graphics, never prose) is skipped, with
+  `.zer0-diagram` added to the class exemptions. `test/test_resolver.js` gains
+  a fixture with a lower-case `style`/`text` inside `<svg>`, and the Mermaid
+  spec asserts a pie slice's computed fill equals its own attribute and that no
+  unscoped `path` rule exists on the page.
+
+### Changed
+
+- **The page-feedback widget now files the fleet's issue contract, not its own
+  (UPS-FB).** The theme built its own issue body, its own escaping, and its own
+  URL-length trimming — and so did the 404 page and the AI chat, three builders
+  in one repo with three different behaviours. All three now go through
+  `FleetFeedbackCore` in `assets/js/fleet-feedback.js`, vendored byte-identically
+  from the fleet kit (`bamr87/bamr87` `templates/feedback/`, held to the hub's
+  copy by the drift gate). It is the same builder the fleet's `<fleet-feedback>`
+  web component uses, so an issue filed from a page here and one filed from a
+  React app elsewhere are byte-identical to the pipeline that triages them.
+
+  What that adds to every filed issue: sections in a fixed order, a
+  `<!-- fleet-feedback v1 type=... -->` marker the issue pipeline reads to
+  recognise an already-structured report, and a real over-budget path. The AI
+  chat in particular used to `.slice(0, 6000)` its body — silently dropping
+  whatever Claude had written past that point — and now trims by section and
+  hands the full text to the clipboard.
+
+  The theme keeps its Bootstrap modal and its AI triage step; only the body
+  assembly moved. Two UIs, one contract.
+
+- **Request-type labels map onto the fleet issue-pipeline taxonomy.**
+  `enhancement`/`documentation` become `feature`/`docs`; `area:docs`/`area:feat`
+  drop out. Every label the widget applies exists in this repo (GitHub silently
+  drops the ones that do not), and a widget-filed issue is now pipeline-eligible
+  on the next scan. The zero-`_data` fallback taxonomy carries them too, so
+  `remote_theme` consumers benefit the moment those labels exist in their repo.
+
+- **Captured console lines are redacted before they enter the buffer.** Bearer
+  tokens, API keys, JWTs, GitHub tokens and email addresses are masked on the
+  way in, so a secret cannot be previewed, copied, or filed even by accident.
+  Credentials reach the console more often than anyone expects — an
+  `Authorization` header logged by a fetch wrapper, a signed URL in a 403.
+
+- **The capture buffer hooks `console.warn` and `console.error` only.**
+  Previously `log`, `info` and `debug` were captured too. At a 40-entry ring,
+  debug chatter evicts the one line that explains the failure — which is the
+  line a report exists to carry. `_includes/core/console-capture.html` is now a
+  two-line loader for the vendored buffer rather than 60 lines of inline script,
+  which also *shrinks* `<head>` and buys back room for the charset meta that has
+  to land in the first 1024 bytes (#372).
+
+### Fixed
+
+- **The 404 page files a report a maintainer can act on.** "Submit an Issue on
+  GitHub" opened a hand-built form containing two sentences of boilerplate — no
+  page context, no environment, no captured errors. It now opens the feedback
+  widget pre-typed as `fix-page` with the URL that failed (and the page that
+  linked to it) already in the description.
+
+- **The feedback FAB survives its script failing to load.** It was a `<button>`
+  whose only behaviour came from JavaScript; with the widget now depending on a
+  second script, a 404 on either one would have left a decorative circle in the
+  corner. It is an anchor to the issue form, upgraded in place when the script
+  runs — the same progressive enhancement the inline "Improve" link already had.
+
+- **The page-feedback Playwright spec dismisses the cookie-consent banner.** The
+  banner is a full-width bar on a layer above the FAB stack, so it swallowed
+  every click aimed at the FAB. Every other spec that touches lower-screen chrome
+  already seeded the consent choice through the shared fixture; this one never
+  did.
+
+### Changed
+
+- **TOC scroll spy now bolds the section you are actually reading** — the
+  highlighted entry in the right-hand Table of Contents jumped around and sat
+  one to three sections ahead of the viewport. Measured on `/docs/features/toc/`
+  at 1280×820, the wrong entry was bolded at **19–23 of 25 scroll positions**
+  — the count moves between runs because which implementation won depended on
+  callback timing, which is the bug in one sentence.
+
+  Three implementations were toggling `.active` on the same
+  `#TableOfContents a` links, so whichever fired last won. Bootstrap's native
+  ScrollSpy was wired up twice — `data-bs-spy="scroll"
+  data-bs-target="#TableOfContents"` on `<body>` in `_layouts/root.html` *and*
+  on `.bd-main` in `_layouts/default.html` (whose `data-bs-offset="100"` had
+  been dead since Bootstrap 5.2 replaced that option with
+  `data-bs-root-margin`). `assets/js/ui-enhancements.js` ran a third observer
+  over *every* `a[href^="#"]` on the page, clearing `.active` from all of them
+  each time a `section[id]` intersected. Both Bootstrap hooks are removed —
+  the `<body>` one was also stripping server-rendered `.active` classes off
+  admin sidebar links, which `fixtures.gotoBeforeScrollSpy` exists to work
+  around — and the `ui-enhancements.js` observer is now scoped away from TOC
+  and sidebar links.
+
+  The theme's own spy (`assets/js/modules/navigation/scroll-spy.js`) was wrong
+  on its own terms too: it asked IntersectionObserver for the "most visible"
+  heading, but headings are a few pixels tall, so every heading inside the
+  observer band reports the same `intersectionRatio` — the winner was whichever
+  entry happened to be in that callback's batch, and a heading scrolling *out*
+  of the band triggered no re-evaluation at all. It now applies a positional
+  rule: the active heading is the last one whose top has crossed the reading
+  line (the document's `scroll-padding-top`, the same offset anchor navigation
+  uses), with the last heading winning once the page is scrolled to the bottom
+  so trailing sections shorter than the viewport are still reachable. The
+  answer is recomputed from scratch on each rAF-throttled scroll frame from
+  cached heading offsets, re-measured on resize and content reflow
+  (`ResizeObserver`), so it cannot drift out of sync.
+
+  Two smaller fixes ride along. Clicking a TOC entry now holds that entry
+  active while the smooth scroll animates, instead of flashing every heading
+  passed on the way. And keeping the active entry visible inside the TOC no
+  longer calls `scrollIntoView()`, which bubbles up and scrolls the *page* —
+  feeding straight back into the spy; it adjusts the TOC container's own
+  `scrollTop`, resolving that container at call time (`.bd-toc` on desktop,
+  `.offcanvas-body` on mobile) rather than assuming one. The active link also
+  carries `aria-current="true"`.
+
+  `config.scrollSpy.rootMargin`/`threshold` are replaced by
+  `config.scrollSpy.offset` (`null` = derive from `scroll-padding-top`) and
+  `tolerance`. Guarded by `test/visual/features/scroll-spy.spec.js` (smoke
+  tier), which is 5 failed / 1 passed against the pre-fix theme and 6 passed
+  with the fix. (evidence:
+  [`test/visual/evidence/scroll-spy/`](test/visual/evidence/scroll-spy/README.md)
+  — wrong TOC highlight at 19/25 scroll positions → 0)
+- **Navbar controls no longer flicker under a stationary pointer (#404)** —
+  `.nav-link:hover`, the Search/Settings utility buttons and the two sidebar/TOC
+  FABs applied `transform: translateY(-1px)`. A 1px lift moves the element out
+  from under a pointer parked on the row it vacates, so hover exits, the element
+  drops back under the pointer, and hover re-enters — an infinite flicker with
+  no pointer movement at all. Nav items are thin enough for a 1px lift to
+  reliably do it.
+
+  Deleting those declarations was **not sufficient**, and the reason is the
+  substantive finding here: `_sass/components/_ui-enhancements.scss` applies
+  `transform: translateY(-2px)` to `.btn:hover` — *every* button in the theme.
+  The utility buttons and both FABs are `.btn`s, so with the navbar's own 1px
+  lift removed the buttons kept flickering on the inherited 2px one — measured
+  on the built site, the Settings button lost and regained hover 14 times in
+  800ms with the pointer completely still. The fix therefore cancels it
+  explicitly with `transform: none`, the corrective pattern this repo already
+  uses in `_post-navigation.scss` and its `prefers-reduced-motion` blocks. The
+  FABs get the same treatment by the same reasoning — they are the same kind of
+  `.btn` with the same lift — but they were not rendered at any viewport reached
+  during verification, so that half is reasoned, not observed.
+
+  Background, colour and shadow transitions are untouched, and the controls keep
+  a pressed cue as `:active { transform: translateY(1px) }` — safe, because
+  `:active` only holds while the button is held down, so the pointer cannot
+  leave and re-enter in a loop.
+
+  Three corrections to the issue as filed. The vacated row is the **bottom**
+  edge, not the top — a probe parked on the top edge passes without exercising
+  the bug at all. Only a transform on the **hovered element's own box** can
+  flicker: `&:hover i { transform: scale(1.1) }` moves a child and never shrinks
+  the parent's hit box, so those went for consistency, not as causes. And
+  `.nav-link:hover`, named as the primary culprit, was **dead code** — its lift
+  sat inside `@media (min-width: 992px) { @container navbar-main (max-width:
+  75rem) }`, and measured on the built site at 1040/1140/1200/1280px its
+  computed hover transform is `none` at every width, on `main` too. Every
+  flicker actually observed was on the utility buttons.
+
+  Guarded by `test/visual/core/hover-stability.spec.js`: with the pointer on the
+  control's centre the border box must be byte-identical to its resting box and
+  the computed transform must be `none`; with the pointer held half a pixel
+  inside the bottom edge for 800ms, `mouseleave` must stay at zero. The verdict
+  is the *computed* value rather than "no matching rule exists", because
+  `.btn:hover` does still match these controls and always will — it is
+  overridden, not deleted. `mouseleave`, not `mouseout`: the latter also fires
+  when the pointer crosses onto a descendant, which is not the element losing
+  hover, and it produces a false positive on every `.nav-hover-dropdown` parent.
+  Against `main` the spec is 4 failed / 1 passed; with the fix, 5 passed.
+  Evidence in `test/visual/evidence/hover-flicker/` — the Settings button lost
+  hover 14 times in 800ms before, 0 after.
+
+  Scoped to the navbar. The issue's original acceptance criterion — *no
+  transform in any `:hover` rule under `_sass/`* — is 42 rules across ~15 files
+  (card lifts, book-cover tilts, recipe and author hovers) and a visual redesign
+  of a published theme rather than a defect fix; it also flagged
+  `transform: none`, which is the corrective pattern this repo already uses in
+  `_post-navigation.scss` and its `prefers-reduced-motion` blocks. A theme-wide
+  motion policy belongs in its own task.
+- **Mobile browser chrome now tracks the page surface (#281)** — `theme-color`
+  drives the iOS Safari address bar and the Chrome/Android task-switcher card.
+  It fell back to `theme_color.main`, which is the brand **accent** (`#007bff`
+  here), so a dark-first theme advertised a bright blue address bar; and being
+  config-gated it emitted **nothing at all** on `remote_theme` consumers, which
+  do not inherit this repo's `_config.yml` — the case the issue was originally
+  filed about. The include now emits scheme-aware tags sourced from
+  `--bs-body-bg` (light `#ffffff`, dark `#212529`, Bootstrap 5.3.3's own
+  surfaces) **with no configuration required**, and honors new optional
+  `favicon.theme_color_light` / `theme_color_dark` keys. A site that pins its
+  mode (`color_mode_default: dark`/`light`, or `color_mode_lock: true`) gets a
+  single unconditional tag instead, because `media="(prefers-color-scheme: …)"`
+  keys off the OS and a pair would hand light chrome to an OS-light visitor
+  reading a page the site renders dark. `favicon.theme_color` still pins one
+  color for both schemes, so existing consumer config is unchanged. Guarded by
+  four `@critical` tests in `test/visual/core/head-contract.spec.js` that
+  compare each value against the page's computed `--bs-body-bg` rather than a
+  constant, plus `test_theme_color_fallback_without_config` covering the
+  no-config consumer case.
+
+
+- **Consumers no longer inherit the theme's own navigation (#332)** — `install.sh`
+  copied the theme's entire `_data/` into every consumer, so each site's *own*
+  `_data/navigation/*.yml` was a verbatim copy of the theme's and carried the
+  theme's page taxonomy. Measured on a real install: **106 of 129 seeded
+  navigation URLs pointed at pages the installer does not create** — ~47 per
+  doc page from `docs.yml` alone, which htmlproofer on a consumer counted as
+  ~1,598 broken internal links across ~34 docs, none of them removable from
+  consumer content. `_data/navigation/` is now held back from the theme copy
+  and seeded from `templates/data/navigation-*.yml.template`, whose links
+  resolve against the pages the installer actually creates: **0 of 26
+  unresolvable**. All seven files are covered, not just `docs.yml`. Because
+  `create_from_template` skips a file that already exists, a re-run or upgrade
+  preserves navigation a consumer has edited. The sidebar renderer is
+  unchanged — `nav: tree` → `auto` → `page.collection` was always correct, it
+  was being handed the wrong data. Existing consumers are not fixed
+  retroactively (`_data` is not part of Jekyll's theme payload); see
+  [Migrating already-seeded navigation data](docs/systems/theme-propagation.md).
+  Guarded by `test/test_install_navigation_seed.sh`, which fails on the old
+  installer naming all 51 seeded dead links.
+
+- **Translation placeholders leaked into published French pages** — before a
+  line is sent to the model, `scripts/translate.rb` masks every non-translatable
+  span as a `⟦N⟧` token and restores it afterwards. The patterns run in order,
+  coarse first, so a span can be masked **twice**: a Liquid expression inside a
+  link destination becomes `](⟦3⟧)` and is then masked again as a whole, and the
+  same happens to Liquid inside an inline code span. `unmask` used a single
+  `gsub`, and `gsub` never rescans its own replacement text — so the outer span
+  came back and the inner token was stranded as a literal `⟦3⟧` on the page.
+  That is 107 tokens across 23 generated pages on `main` today, and where the
+  masked span was a URL it is a dead link: `[couleurs](⟦3⟧)` in
+  `fr/about/design.md`, `href="⟦24⟧"` in the same file, the whole Liquid
+  variable table in `fr/docs/customization/layouts.md`. `unmask` now substitutes
+  until the text stops changing, and refuses to return anything still holding a
+  placeholder — a corrupt page fails its own job (counted, logged, run exits
+  non-zero) rather than shipping. The existing "no placeholder tokens leak"
+  assertions in `test/test_i18n.sh` were correct but toothless: no fixture line
+  nested a mask. Both shapes are now in the fixture, so the guard fails without
+  the fix.
+
+  The already-generated pages are not repaired by this change. Staleness is
+  decided by source SHA alone, so a masker fix does not make an unchanged page
+  stale; repairing them needs a `--full` re-translation.
+- **`components/background-image.html` — cover art painted as a CSS background,
+  announced correctly (#401)** — the theme had a solid convention for art
+  rendered as {% raw %}`<img>`{% endraw %} (`preview-image.html` always emits an escaped `alt`)
+  and none for art painted as a **background**. A background image is invisible
+  to assistive technology, so such a box announces nothing at all. The correct
+  pattern already existed by hand in three places (`abc-letter.html`, the
+  article rating stars, `theme-customizer.html`) without being a named
+  convention; this generalizes it. Two branches: a real image gets
+  `role="img"` with an escaped `aria-label`, a decorative one gets
+  `aria-hidden="true"` and **neither** `role` nor `aria-label` — combining them
+  announces a graphic and then hides it, which is worse than either alone.
+  Decorative is the **default**, and the real-image branch must earn it with
+  both a `src` and a non-empty `alt`. Path handling follows
+  `preview-image.html`. Purely additive: no in-theme call site, no CSS, no
+  layout change, and `content/intro.html` is deliberately untouched — it paints
+  a background *and* wraps the page `<h1>`, so `role="img"` there would delete
+  the heading from the accessibility tree. Guarded by
+  `test_background_image_include_contract`, which renders the include and
+  checks both branches, the escaping and all three path cases.
+- **Heading outlines no longer skip levels in theme chrome (#436)** — several
+  components picked a heading element for its default **font-size** rather than
+  its position in the document, so an article read
+  `h1 → h2 → h6 → h2 → h5 → h3 → h6` to anyone navigating by heading. Measured
+  across a 415-page build: **391 of 415 pages carried at least one skip, 1,060
+  in total**; now 66 and 173. Size and level are decoupled — `<h3 class="h6">`
+  keeps the small type and states the real depth — in the cookie dialog, the
+  settings offcanvas, the language panel, the author card and the related-posts
+  region. The language panel was not in the report and was doing the same thing
+  on every page. `author-card.html` renders under twelve different call sites,
+  so its level is now `heading_level` (default `5`, unchanged for callers that
+  do not pass it) rather than a guess. Fails **WCAG 1.3.1**. Nothing moves
+  visually. Guarded by `test/visual/core/heading-outline.spec.js`. One offender
+  is injected at **runtime** by `assets/js/modules/theme/appearance.js`, so no
+  grep over `_includes`/`_layouts` could find it — only a rendered assertion
+  does. Still open, deliberately: 66 pages with inline card markup in the news
+  and section index layouts, plus the `palette-generator` and `skin-editor`
+  admin tools — see the evidence bundle.
+
+- **Liquid written as documentation was being executed, not displayed** — Liquid
+  runs before Markdown, so backticks and code fences never escaped it; they only
+  changed how its *output* was displayed. Two pages leaked as a result. The
+  CHANGELOG page carried a **second full copy of `<head>` inside its body**
+  (Bootstrap CSS, Bootstrap Icons and `X-UA-Compatible` all emitted twice, and
+  the Google Tag Manager snippet a second time on a production build) because an
+  {% raw %}`{% include core/head.html %}`{% endraw %} in prose was run rather than shown. The
+  Layout Variables table in `/docs/customization/layouts/` documented nothing:
+  {% raw %}`{{ content }}`{% endraw %} injected the whole rendered page into a table cell and
+  {% raw %}`{{ page.title }}`{% endraw %} rendered as the literal word "Layouts", leaving
+  196 KB of leaked layout output where a five-line code sample belonged. Both are
+  now wrapped in Liquid raw blocks, the idiom the same files already used
+  elsewhere. A `test_content_liquid_is_raw_protected` guard in
+  `test/test_core.sh` fails if injecting Liquid appears unprotected inside a code
+  fence or code span again. The layouts doc also had its layout **names** and
+  **hierarchy** corrected against `_layouts/`: `journals` has not existed since
+  the v1.0 rename to `article`, and three of the four children in the
+  inheritance diagram were wrong — `home` and `landing` inherit `root`, not
+  `default`, which decides whether a layout renders the sidebar and TOC at all.
+
+- **Developer doc banners no longer ship to visitors (#375)** — the 1,065
+  multi-line {% raw %}`<!-- ... -->`{% endraw %} banners documenting `_includes/**` and
+  `_layouts/**` (file paths, dependency lists, design rationale) are now Liquid
+  {% raw %}`{% comment %}`{% endraw %} blocks, which Jekyll strips at build time. The
+  in-source documentation is unchanged; only the delimiters moved. Across a
+  415-page build the delivered HTML drops from 91.5 MB to 71.6 MB — **21.7%** —
+  because an include's banner is re-emitted at every call site, not once:
+  `/authors/default/` alone carried 130,840 bytes of it from `post-card.html`
+  rendering 1,100 times. Per page: 47,898 comment bytes in 344 blocks → 111
+  bytes in 3. The four boundary markers inside Google's own copy-paste
+  analytics snippets are kept verbatim, and comments inside
+  `<script>`, `<style>`, `<pre>` or a Liquid raw block are untouched. A new
+  `test_developer_doc_banners_are_liquid` guard in `test/test_core.sh` fails if
+  any reappear. Two side effects worth knowing: reading-time estimates were
+  counting the banners and are now correct (`/docs/` claimed 63 minutes, really
+  24), and three pages that leak unescaped Liquid emit less as a result — those
+  leaks are pre-existing and filed separately.
 
 - **Setup wizard: live preview, vertical stepper, draft persistence (T-040, #408)** —
   the `_config.yml` preview is now a **persistent sticky panel** shown at every
@@ -196,6 +831,83 @@ file. Only `## [Unreleased]` describes work that has not shipped yet.
 
 ### Fixed
 
+- **Finished work kept reopening its own issues** — `scripts/sync-backlog.rb`
+treats `_data/backlog.yml` as the source of truth and **reopens** any issue whose
+task is not `done`. T-038, T-040 and T-045 shipped in v1.29.0 (#431, #432, #425)
+and their `Closes #NNN` commits duly closed #406, #408 and #417 — then the next
+sync reopened all three, because the backlog still said `open`. Marked done with
+their PR links, which is the only thing that actually closes them.
+- **The nightly sticky issue could be raised but never cleared (#326)** —
+`nightly-extended.yml` files and updates a sticky issue on failure and does
+nothing on recovery, so a fixed failure stayed open indefinitely. #326 sat open
+five days past its own fix, carrying a P1 into every triage pass. A
+`report-recovery` job now comments and closes it when the tier goes green. It is
+gated on `preflight.outputs.go == 'true'` as well as both jobs succeeding: the
+preflight short-circuits on an unchanged `main` and reports `skipped`, so a bare
+`success()` would close the issue on a night that tested nothing.
+- **37 pages shipped dead controls with dangling ARIA references (#373)** —
+`#bdSidebar` and `#tocContents` are emitted by `_layouts/default.html` alone,
+but their toggles live in `core/header.html` and `core/footer-fabs.html`, which
+`_layouts/root.html` includes on **every** layout. On any layout inheriting
+`root` directly (admin, stats, 404, section, home, book-*) the toggle rendered
+pointing at an offcanvas that was never in the document: clicking did nothing,
+and assistive tech followed `aria-controls` to a missing element. Measured
+across a 415-page build: **19 pages with a dangling `#bdSidebar`** (the French
+`/about/**` tree) and **18 with a dangling `#tocContents`** (404, CHANGELOG,
+`_design-system/**`) — **0 after**. `navigation/sidebar-config.html` now
+publishes `sidebar_offcanvas_rendered`, and both controls are gated on it.
+`footer-fabs.html`'s previous **denylist** of layouts to skip is replaced by
+that positive gate: a denylist fails open, and this one had already fallen
+behind (`404` and the `book-*` layouts were missing). The layout list is pinned
+against the real inheritance graph by
+`test/test_core.sh :: test_sidebar_offcanvas_layout_gate`, which walks every
+`_layouts/*.html` and fails if the two disagree in either direction.
+
+- **Seven footer links had no accessible name on mobile (#435)** — the "Follow
+Us" social links and the RSS link render an `<i>` that is `aria-hidden="true"`
+beside a `<span class="d-none d-md-inline">` label. Below the `md` breakpoint
+the span is `display:none`, so it leaves the accessibility tree too and the link
+was announced as a bare "link" — measured: **7 nameless links at 375px**. Each
+now carries an `aria-label` matching its visible text exactly, so the name is
+correct on mobile and still contains the visible label at `md`+ (WCAG 2.5.3
+Label in Name). Covered by `test/visual/core/accessible-names.spec.js`, which
+asserts at **mobile** width — the same assertions pass at desktop on the
+unfixed code, which is why the bug survived the existing suite.
+- **Search results were never announced to screen readers (#279)** — the modal
+rewrites its results container without moving focus, so assistive tech had no
+signal that anything had happened. A visually-hidden `role="status"`
+`aria-live="polite"` region now announces a concise count ("7 results for
+jekyll", or "12 of 40 results…" when the list is truncated), and "No results
+found." The **results list itself is deliberately not live**: announcing eight
+titles and their snippets on every keystroke would be unusable. `aria-atomic`
+keeps the summary a single message, and a repeated string is cleared first so an
+unchanged announcement is not swallowed as a no-op.
+
+- **`<meta charset>` shipped ~26 KB into the document, past the spec's 1024-byte
+window (#372)** — the HTML spec only scans the first 1024 bytes for the
+character-encoding declaration. The tag sat in `_includes/core/head.html` below
+Google Tag Manager, console-capture, page-views, mermaid and nanobar — and below
+two multi-line HTML doc banners that shipped verbatim to production — so a
+served page declared its encoding at byte **26058**. Past the limit a browser
+stops looking and decodes with its locale default, mangling every non-ASCII byte
+until it re-parses; this theme ships UTF-8 throughout (`fr/**` translations,
+em-dashes, curly quotes), so that is a live corruption risk rather than a lint
+nit. The tag now sits at the very top of `_layouts/root.html` — measured at byte
+**318**, verified across all 400 built pages — and `root.html`'s own banner is a
+Liquid comment (stripped at build) rather than an HTML one, which is what freed
+the budget. Regression coverage in `test/visual/core/head-contract.spec.js`
+measures the **served bytes**, since a source-order assertion would have passed
+both before and after.
+- **The Atom feed was undiscoverable (#371)** — `jekyll-feed` generates
+`/feed.xml` but emits no autodiscovery `<link>` unless `feed_meta` is called,
+which the theme never did, so readers and crawlers could not find the feed even
+though the footer linked it. `<head>` now carries
+`<link rel="alternate" type="application/atom+xml">`, honouring `site.feed.path`.
+Written out directly rather than via `feed_meta` so a consumer site that has not
+enabled the plugin does not hard-fail with `Unknown tag`. A test asserts the
+advertised URL actually returns a feed — a discoverable link to a 404 would be
+worse than none.
+
 - **Footer "Info" and "Cookie Preferences" are buttons, not links (#320)** —
   both controls open in-page UI (the `#info-section` offcanvas and the
   `#cookieSettingsModal` modal) but shipped as `<a href="#" data-bs-toggle>`, so
@@ -231,7 +943,8 @@ file. Only `## [Unreleased]` describes work that has not shipped yet.
   `html.no-js .foo {…}` / `html.js .foo {…}` got the no-JS branch for everyone
   — the class advertised a capability the theme did not deliver. An inline
   script is now the **first child of `<head>`**, above
-  `{% include core/head.html %}` (which opens with Google Tag Manager, so
+  {% raw %}`{% include core/head.html %}`{% endraw %} (which opens with Google Tag
+  Manager, so
   "first in that include" is not "first in `<head>`") and deliberately neither
   `defer` nor `async`, since it has to run before the first stylesheet is
   fetched or `html.js` rules would flash. The served HTML still carries