jekyll-theme-zer0 1.28.0 → 1.30.0

data/CHANGELOG.md

@@ -12,6 +12,1111 @@ 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)
+
+
+### Features
+
+* **analytics:** track and display per-page view counts ([#413](https://github.com/bamr87/zer0-mistakes/issues/413)) ([e488c4c](https://github.com/bamr87/zer0-mistakes/commit/e488c4c3101da78e98eecbf8299ce7c8705ed281))
+* **design:** fill Fab, PostCard, Skeleton + motion/layers gaps in the design-system mirror ([#391](https://github.com/bamr87/zer0-mistakes/issues/391)) ([3b49741](https://github.com/bamr87/zer0-mistakes/commit/3b497417564b4c5e3d71eaa113cb136d2cdaf15c))
+* **includes:** icon-only language trigger and a compact, positive menu ([#431](https://github.com/bamr87/zer0-mistakes/issues/431)) ([353bfa5](https://github.com/bamr87/zer0-mistakes/commit/353bfa5f3a8dd949ca6e513213a155d648218642)), closes [#406](https://github.com/bamr87/zer0-mistakes/issues/406)
+* **includes:** live preview, vertical stepper and draft persistence in the setup wizard ([#432](https://github.com/bamr87/zer0-mistakes/issues/432)) ([73bdc55](https://github.com/bamr87/zer0-mistakes/commit/73bdc5547350c448e1617ec6cf5b9f49b10d65fb)), closes [#408](https://github.com/bamr87/zer0-mistakes/issues/408)
+* **layouts:** add cookbook collection with recipe scaling and unit conversion ([#414](https://github.com/bamr87/zer0-mistakes/issues/414)) ([bb8eefa](https://github.com/bamr87/zer0-mistakes/commit/bb8eefa2beea0104fec28d173a1e57f369acada8))
+* **pages:** publish the design system and page canvas on the live site ([#392](https://github.com/bamr87/zer0-mistakes/issues/392)) ([6cf73cd](https://github.com/bamr87/zer0-mistakes/commit/6cf73cdf2cca9ec02394b6ae1ba7e39c19969134))
+* **sass:** align design tokens with the Claude Design system ([#389](https://github.com/bamr87/zer0-mistakes/issues/389)) ([7fc2fe0](https://github.com/bamr87/zer0-mistakes/commit/7fc2fe02683d652c0326536158bd48b3690df51f))
+
+
+### Bug Fixes
+
+* **a11y:** dialog titles use a bare <h5>, skipping heading levels ([#387](https://github.com/bamr87/zer0-mistakes/issues/387)) ([98fd6f9](https://github.com/bamr87/zer0-mistakes/commit/98fd6f9e63dfb75c58efc3b15a642fb3e4c4095b))
+* **ci:** fail the content review when it did not actually run ([#424](https://github.com/bamr87/zer0-mistakes/issues/424)) ([f048cb2](https://github.com/bamr87/zer0-mistakes/commit/f048cb22e565b3122d6682c026e13521b6fe52d9)), closes [#418](https://github.com/bamr87/zer0-mistakes/issues/418)
+* **ci:** fail the Pages build on Liquid errors, unmangle two live pages ([#439](https://github.com/bamr87/zer0-mistakes/issues/439)) ([afd2ec8](https://github.com/bamr87/zer0-mistakes/commit/afd2ec83879a793d77dfac21b41d74d5204126c4))
+* **ci:** make the pixel gate see the data files that move pixels ([#425](https://github.com/bamr87/zer0-mistakes/issues/425)) ([02ea639](https://github.com/bamr87/zer0-mistakes/commit/02ea639b3152900682ca298bd172925133d10dea)), closes [#417](https://github.com/bamr87/zer0-mistakes/issues/417)
+* **ci:** stop discarding good translations when one page fails ([#388](https://github.com/bamr87/zer0-mistakes/issues/388)) ([19cea46](https://github.com/bamr87/zer0-mistakes/commit/19cea462a7822d6db536fc9c23218abd4a13d830))
+* **ci:** wait past the cold bundle install for Jekyll in the snapshot gate ([#426](https://github.com/bamr87/zer0-mistakes/issues/426)) ([de1d1ca](https://github.com/bamr87/zer0-mistakes/commit/de1d1ca426ce7a25d5a8548c4a696c0002877200))
+* **cookie-consent:** text-dark on bg-body made privacy rights invisible in dark mode ([#386](https://github.com/bamr87/zer0-mistakes/issues/386)) ([9bde7df](https://github.com/bamr87/zer0-mistakes/commit/9bde7dfa13f426908e00e53f8e4013a049fd928d))
+* **giscus:** comments were broken sitewide — add an end-to-end health check and correct the docs ([#378](https://github.com/bamr87/zer0-mistakes/issues/378)) ([45e222c](https://github.com/bamr87/zer0-mistakes/commit/45e222c3c2c5b7c507af4df2f5f0b48bc783801e))
+* **includes:** footer Info/Cookie Preferences are buttons, not anchors ([#427](https://github.com/bamr87/zer0-mistakes/issues/427)) ([f9041b9](https://github.com/bamr87/zer0-mistakes/commit/f9041b98b8a267be59f560724821fd941090f52d)), closes [#320](https://github.com/bamr87/zer0-mistakes/issues/320)
+* **layouts:** match section topic filters on whole tags, not substrings ([#420](https://github.com/bamr87/zer0-mistakes/issues/420)) ([338ad1d](https://github.com/bamr87/zer0-mistakes/commit/338ad1ddfb71c8d1dd9c48b36fb4634daf93f2de))
+* **layouts:** move keyboard focus to the skip-link target (tabindex="-1") ([#395](https://github.com/bamr87/zer0-mistakes/issues/395)) ([f5db650](https://github.com/bamr87/zer0-mistakes/commit/f5db65048e48ca71eedebc04d02d051e0b3152a6)), closes [#278](https://github.com/bamr87/zer0-mistakes/issues/278)
+* **layouts:** stop emitting dead sub-topic anchors in section sidebars ([#402](https://github.com/bamr87/zer0-mistakes/issues/402)) ([f50e790](https://github.com/bamr87/zer0-mistakes/commit/f50e790c4bfd56fefa4a74d7876de90c9776c689))
+* **layouts:** upgrade the no-js class to "js" so the hook works ([#428](https://github.com/bamr87/zer0-mistakes/issues/428)) ([a2d31f5](https://github.com/bamr87/zer0-mistakes/commit/a2d31f5533a4fb4793042e32326c1a78c9954268)), closes [#319](https://github.com/bamr87/zer0-mistakes/issues/319)
+* **navigation:** fit all nav items, full-bleed bar, language into Settings ([#423](https://github.com/bamr87/zer0-mistakes/issues/423)) ([689006e](https://github.com/bamr87/zer0-mistakes/commit/689006e7654e900a4509c30539fcf12bd7f397c6))
+* **scripts:** correct consumer auditor, plugin contract, and JSON-LD scope ([#400](https://github.com/bamr87/zer0-mistakes/issues/400)) ([b466cad](https://github.com/bamr87/zer0-mistakes/commit/b466cad526501e7e7a0eef5f24a12c5bbd181dc7))
+* **scripts:** recover from a rejected Anthropic credential, and link the cookbook ([#419](https://github.com/bamr87/zer0-mistakes/issues/419)) ([fac6bee](https://github.com/bamr87/zer0-mistakes/commit/fac6beeb7af7dcae96f727bf0cf581b080e95f15))
+* **ui-audit:** serve without --detach so the sweep can capture, and fail loudly when it cannot ([#434](https://github.com/bamr87/zer0-mistakes/issues/434)) ([fac6415](https://github.com/bamr87/zer0-mistakes/commit/fac641574c951b2887d94f8b39561fb8b6f8fe8c)), closes [#321](https://github.com/bamr87/zer0-mistakes/issues/321)
+
+## [Unreleased]
+
+### 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
+  step rather than an element inside step 5, regenerated on every keystroke,
+  with Copy and Download always enabled. The nav-pills tab row is replaced by a
+  left **vertical stepper** with done/active/upcoming state: a step is locked
+  until every earlier step validates, and Back is always allowed. The form is
+  mirrored to `localStorage` under `zer0-setup-draft` (debounced 300ms),
+  restored on load with a "Draft saved" chip, and cleared once the file is
+  downloaded. Email and URL fields are validated **on blur** with `is-invalid`
+  and an explanatory message, cleared as soon as you retype; the Review step
+  lists any unfilled recommended fields as warnings. Every step pane shares one
+  CSS grid cell, so the container is always as tall as the tallest step, and the
+  nav row is pinned to the bottom — **Back/Next no longer move vertically**
+  between steps. New
+  `_sass/components/_setup-wizard.scss`, and the wizard gains its first
+  automated coverage in `test/visual/features/setup-wizard.spec.js`.
+
+  Holding the container's height turned out to be only half of "Back/Next no
+  longer move": the nav row's own height still varied. Step 1's row was a block
+  box, so its button sat on a baseline and rode ~2px high, and in the real
+  ~270px middle column `Review & Download` wrapped to a second line, pushing
+  that button's top up a further 16px. The row is now always a flex box and its
+  buttons never wrap. Draft persistence gained a matching fix: the 300ms
+  debounce meant the last edit before a reload was still only a queued timer and
+  was lost, so a pending write is now flushed on `pagehide` and on a hidden
+  `visibilitychange`. Before/after measurements are in
+  `test/visual/evidence/setup-wizard-nav-alignment/`.
+
+- **Language switcher: icon-only trigger and a compact, positive menu (T-038, #406)** —
+  the navbar trigger drops its `EN` text span and the Bootstrap caret for a
+  38px square icon button, with `title` and `aria-label` carrying the language
+  name. In the menu (both the navbar dropdown and the Settings panel variant),
+  the current language is now marked with a tint and a check icon instead of
+  Bootstrap's `.active` primary fill, which read as a selected nav item rather
+  than "you are here". **Untranslated languages are no longer disabled rows** —
+  they link to the source page and still record the `zer0-lang` preference, so
+  the menu has no dead ends. Machine-generated translations carry a small
+  `auto` chip, and the per-row "(Not yet translated)" text — the main driver of
+  menu width — collapses into one footnote under a divider, referenced from
+  each marked row via `aria-describedby`. The dropdown menu is capped at 220px.
+  New `ui` keys `lang_machine_translated`, `lang_machine_translated_title` and
+  `lang_untranslated_note` in `_data/ui-text.yml`; each use carries a literal
+  fallback, because `core/i18n.html` replaces the `ui` map wholesale on a
+  translated page and `_data/i18n/<lang>.yml` will not have them until
+  `scripts/translate.rb` next runs.
+
+### Added
+
+- **Cookbook & recipes collection (ZER0-084)** — a `recipes` collection that
+  renders structured front matter as a working recipe page: `layout: recipe`
+  builds a fact bar (prep/cook/rest/total, yield, difficulty, cuisine, oven),
+  a grouped ingredient checklist, a numbered method with per-step timings and
+  temperatures, a baker's-percentage ratio table computed at build time, a
+  per-serving nutrition panel, and one `schema.org/Recipe` JSON-LD block.
+  `assets/js/recipe-scaler.js` adds serving scaling and live US↔metric
+  conversion — including volume↔weight via `_data/ingredient_densities.yml`
+  — as progressive enhancement, so every amount is still rendered exactly as
+  authored with JavaScript disabled. `layout: cookbook` indexes recipes into
+  course sections from `_data/recipe_courses.yml`. Twelve new
+  `components/recipe-*.html` includes, `_sass/components/_recipe.scss` (with
+  print styles), a demo cookbook at `/recipes/`, and docs at
+  [Cookbook collection](pages/_docs/features/cookbook-collection.md). Regression
+  coverage: `test/visual/features/recipes.spec.js` (smoke tier) and "Cookbook
+  Recipe Collection" in `test/test_core.sh` (evidence:
+  [`test/visual/evidence/recipes-collection/`](test/visual/evidence/recipes-collection/README.md)
+  — 0px page overflow across 320–1440px; 1 cup butter → 227 g, 500 g flour →
+  4 cups; ratio percentages identical at 1× and 3×).
+
+- **Page-view counter (ZER0-083)** — the theme now tracks a view for the page
+  being read and displays the count in the article meta row, next to the
+  reading time (`👁 12 views`). Two providers, configured under `page_views:`
+  in `_config.yml`: `local` (the default — counts live in the visitor's
+  `localStorage`, so it works on GitHub Pages with no server, no network, and
+  no third party) and `remote` (counts come from an HTTP counter endpoint you
+  control, with `{path}` substitution, a configurable method, and a dotted
+  `count_key` for the response shape). Privacy gates mirror the `posthog:`
+  block — Do Not Track, Global Privacy Control, and an optional
+  `require_consent` tie-in to the cookie-consent "analytics" category — and
+  they suppress *recording* only, never the display of a count that is already
+  known; a view blocked pending consent is recorded when consent arrives.
+  `dedupe: session` counts one view per page per browser session so reloads do
+  not inflate it. The badge include (`components/page-views.html`) ships hidden
+  and is revealed only once a count exists, carrying its own leading separator
+  so a page with no data leaves no dangling bullet. New:
+  `_includes/components/page-views.html`,
+  `_includes/components/page-views-init.html`, `assets/js/page-views.js`,
+  `_sass/components/_page-views.scss`. Regression spec:
+  `test/visual/features/page-views.spec.js`. Docs:
+  [`docs/features/page-views.md`](docs/features/page-views.md)
+  (evidence: [`test/visual/evidence/page-views/`](test/visual/evidence/page-views/README.md)).
+
+- **Search shortcut affordances (ZER0-032)** — the navbar search button now
+  advertises its keyboard shortcuts, matching the design-system navbar
+  pattern: a quiet `/` kbd chip (xl-up), a hover title ("Search — press / or
+  Ctrl+K", shown as `⌘K` on macOS), and `aria-keyshortcuts`; the sidebar (`b`)
+  and table-of-contents (`t`) hide toggles gained shortcut hover hints, and
+  the keyboard-shortcuts modal now lists `⌘/Ctrl+K`
+  (evidence: [`test/visual/evidence/search-shortcut-hint/`](test/visual/evidence/search-shortcut-hint/README.md)).
+
+- **Live design-system pages (ZER0-082)** — the design system is now
+  part of the site itself: `_design-system/` is force-included in the Jekyll
+  build so `styles.css`, every token file, specimen cards, and component
+  sources get real URLs under `/_design-system/`; a new `/design/` hub page
+  renders the foundation specimens in live iframes (colors, skins, type,
+  spacing, radii, motion, layers, iconography), catalogs the component twins,
+  and links the Claude Design page canvas (all 24 layouts as a browsable
+  presentation). Navbar: About → Design System. Regression spec:
+  `test/visual/features/design-hub.spec.js`.
+
+- **Claude Design system round-trip (ZER0-081)** — the design-token layer is now
+  aligned with the zer0-mistakes Claude Design project
+  (`claude.ai/design/p/e75121c0-9210-42d1-ade3-2c8af9111cbe`): new
+  `--zer0-radius-*`, `--zer0-logo-*`, and `--zer0-text-display-*` tokens in
+  `_sass/tokens/`; the design project vendored as a git mirror under
+  `_design-system/` (plain-CSS tokens, React component specs, guideline cards,
+  website UI kit — sync contract in `_design-system/SYNC.md`); and
+  `scripts/design-system-check.rb` wired into the core test suite so the theme
+  and the mirror cannot drift silently. Callouts, landing feature cards, mobile
+  nav, tables, and focus rings now consume the radius tokens (value-preserving —
+  rendered output unchanged, pinned by a new runtime token assertion in
+  `test/visual/core/styling.spec.js`).
+- **Design-system component twins (PR #391)** — `Fab`/`FabStack`, `PostCard`,
+  and `Skeleton` join Button/Badge/Card/FeatureCard/Callout/Input in
+  `_design-system/components/`, plus new Motion and Layers foundation cards;
+  all pushed live to the Claude Design project. The feature registry is
+  re-synced (`features/features.yml` ↔ `_data/features.yml` — #389's ZER0-081
+  entry had landed in the `_data` mirror only, which the registry validator
+  rejects) and `docs/ui/components.md` gains a theme-source →
+  design-system-twin map.
+
+### Changed
+
+- **Language selector moved from the navbar into Settings → Appearance** — the
+  header utility cluster is now Search + Settings only, returning ~70px to the
+  menubar. `components/language-toggle.html` grew a `variant` parameter: the new
+  `panel` variant (shipped) renders a self-contained **Language** section — an
+  always-visible list of languages with the active one checked and
+  untranslated targets disabled — as the first block of the Settings
+  Appearance tab, next to Color Mode and Theme Skin. The original header
+  dropdown remains available as `variant="navbar"` for consumers that prefer
+  it. Same data, same `localStorage("zer0-lang")` preference, same
+  never-a-dead-link contract; `test/visual/features/language-toggle.spec.js`
+  was updated to exercise it through the Settings panel.
+
+### 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
+  assistive tech announced them as links — WCAG 4.1.2 Name, Role, Value — and
+  whenever Bootstrap's toggle did not fire the browser followed `href="#"` and
+  jumped the page to the top. All three occurrences are now
+  `<button type="button">`: the Info trigger is emitted **twice** by
+  `_includes/core/footer.html`, once in each branch of the powered-by loop, and
+  a site with no `powered_by` credits configured renders the branch a
+  single-site fix would have missed. `.powered-by-link` is now element-agnostic
+  (it already styled `<a>`, `<span>` and now `<button>`) and carries the
+  `<button>` reset Bootstrap Reboot does not supply — `appearance`,
+  `background`, `border`, `colour` — with the new `.footer-inline-button` doing
+  the same for a button in running text, so the swap is visually inert. The
+  back-to-top control keeps its `<a href="#">`: scrolling to the top is its
+  actual behaviour, not a side effect. Regression coverage: "Accessibility —
+  footer in-page toggles are buttons" in
+  `test/visual/core/accessibility.spec.js`, which asserts the element identity
+  directly — axe-core has no rule that fires on an anchor used as a button, so
+  an axe-based assertion passes on the broken markup too. "powered-by credits
+  are real links" in `test/visual/core/layout-chrome.spec.js` already banned
+  `href="#"` but sampled only the first five links, and `site.powered_by` pushed
+  the offending Info anchor past index 4; it now checks every credit link.
+  (evidence:
+  [`test/visual/evidence/footer-button-semantics/`](test/visual/evidence/footer-button-semantics/README.md)
+  — shipped vs. reset-stripped at 1280px, footer overflow 0px at 375/768/1280)
+
+- **`<html class="no-js">` is upgraded to `js` again (#319)** — `_layouts/root.html`
+  shipped the standard progressive-enhancement hook but nothing ever swapped
+  it: the string `no-js` occurred in exactly one file in the repository, and in
+  no SCSS, JS, test or doc. Every page on every downstream site permanently
+  carried `no-js` with JavaScript fully enabled, so a consumer writing
+  `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
+  {% 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
+  `class="no-js"`, so the JS-disabled branch stays correct and the change is
+  purely additive for consumers already styling against the served markup.
+  Regression coverage: `test/visual/core/progressive-enhancement.spec.js`
+  (smoke tier) pins both directions of the contract — `js` with scripts on,
+  `no-js` with them off — plus the delivery mechanism, because a fix that
+  simply deleted `class="no-js"` would satisfy a naive one-sided assertion
+  while removing the hook entirely.
+
+- **Pages build: Liquid errors no longer ship mangled pages silently.** The
+  `github-pages` gem renders every non-excluded Markdown file through Liquid, so
+  prose that merely *looks* like a template is executed as one. Jekyll 3 reports
+  that as a `Liquid Warning`, drops the expression, and still exits 0 — so the
+  Pages workflow stayed green while publishing damaged pages. Two were live:
+  `/CHANGELOG/` rendered "Added `,,` and to the template renderer" because
+  `{% raw %}{{DEFAULT_BRANCH}}{% endraw %}` and its siblings were evaluated to
+  nothing, and `/_design-system/components/feedback/Skeleton.prompt/` rendered
+  `<div style=>` because the JSX `style={% raw %}{{ … }}{% endraw %}` was a
+  Liquid syntax error. A third defect was invisible: a literal
+  `{% raw %}{% raw %}{% endraw %}` written as prose in a changelog entry opened a
+  real block that swallowed the next 945 lines of the published page. All the
+  affected spans are now escaped, `pages.yml` fails the build on
+  `Liquid Warning`/`Liquid Exception` for both the theme and the example site,
+  and `scripts/lint-liquid-raw.rb` (wired into the `quality` suite) catches the
+  silent half — an unbalanced raw block never raises a warning to gate on.
+
+- **Navbar: every top-level item now fits, at every desktop width** — the bar
+  was pinned inside a centred `.container-xl` (max 1140–1320px), so the menubar
+  track never got more than ~740px against the ~815px the theme's seven items
+  need. Every label rendered truncated — `Quick …`, `N…`, `Note…`, `A…` — while
+  the page had 100+px of unused margin on either side, and below ~1050px the
+  whole menu collapsed to bare icons. Four changes give the labels their room:
+  the bar is now `.container-fluid` and spans the full screen width (opt back
+  into a cap with `--zer0-navbar-max-width`); the brand cluster is capped at
+  `30cqi` of the bar so a long title cannot starve the menubar; label density
+  degrades in three measured tiers instead of two (icon + label ≥ 51rem →
+  label-only 41–50.99rem → icon-only < 41rem), each boundary set to the width
+  the tier below it actually needs; and the home-link icons wait for 86rem,
+  where they no longer cost the menubar more than it can spare. Measured on the
+  demo site: **0 truncated labels from 992px to 2560px** (was: all 7 truncated
+  at 1440px, all 7 icon-only at 992px). Regression coverage: "no nav label is
+  CSS-truncated at any desktop width" / "the bar spans the full viewport width"
+  / "the brand title stays legible next to the menubar" in
+  `test/visual/features/navbar.spec.js` — the pre-existing label test only
+  checked for a literal `...` in `textContent`, which CSS `text-overflow` never
+  writes, so it passed throughout (evidence:
+  [`test/visual/evidence/navbar-fit/`](test/visual/evidence/navbar-fit/README.md)
+  — up to 7 truncated labels and 300px of dead bar margin → 0 across 8 widths).
+
+- **Settings no longer opens behind the mobile nav menu** — on phones, tapping
+  **Settings** inside the open navigation menu appeared to do nothing: the
+  Settings offcanvas and the nav menu are both `offcanvas-end` panels at
+  Bootstrap's `$zindex-offcanvas`, and `_navbar.scss` lifts the fixed header
+  (which contains the nav menu) to 1046 while that menu is open — so Settings
+  painted underneath it, fully hidden. `navbar.js` now intercepts the offcanvas
+  `show` event and closes the host panel first, opening Settings once it has
+  finished sliding out; `_navbar.scss` releases the header lift, and raises
+  `#info-section` above it, for browsers without `:has()`. Covered by "Settings
+  opened from the nav menu paints ABOVE it" in
+  `test/visual/features/mobile-overlay-stacking.spec.js` (evidence:
+  [`test/visual/evidence/navbar-fit/`](test/visual/evidence/navbar-fit/README.md)
+  — `03-settings-stacking.png`: top element at the panel centre `a.nav-link`
+  → the panel's own content; header `z-index` 1046 → 1030).
+
+- **Section topic filters match whole tags, not substrings** — filtering a
+  section by a topic silently revealed posts that did not carry it. `data-tags`
+  was built as `tags | join: ' ' | slugify`, which slugifies *after* joining and
+  so turns the separators into hyphens — making a tag boundary indistinguishable
+  from a hyphen inside a slug — and the click handler then matched with
+  `String.includes`. Filtering `/news/technology/` by **ai** returned 6 cards
+  while the sidebar badge for that topic said 5, because a post tagged `edge-ai`
+  matched too. `_layouts/section.html` now slugifies each tag separately into a
+  space-separated list and matches whole tokens, so the rendered count always
+  agrees with the badge (which Liquid computes with exact `contains` membership).
+  Regression coverage in `test/visual/features/section-topic-controls.spec.js`
+  asserts token membership and pins the filtered count to the badge (evidence:
+  [`test/visual/evidence/section-topic-filter/`](test/visual/evidence/section-topic-filter/README.md)
+  — filtering /news/technology/ by "ai" showed 6 cards against a badge of 5, now
+  5; topics whose badge disagrees with what is shown: 2 → 0).
+
+- **Nightly smoke tier is green again** — three `smoke` tests had been failing
+  every night since 2026-08-15 (the tier the PR gate does not run, so `main`
+  stayed green). Two were the topic-filter bug above; the third asserted the
+  sidebar's "All Articles" control only as an `<a href="#all-posts">`, but the
+  sidebar renders a `<button data-filter="all">` for the grid/list styles —
+  currently every section — so it could never pass. The topic-button selector
+  also used `.filter({ hasNot })`, which excludes elements *containing* a match
+  rather than matching elements themselves, so it selected the "All Articles"
+  button and asserted against an unfiltered list; it now uses `:not()`.
+
+- **A rejected Anthropic credential now falls back to the next one** — the
+  translation pipeline picked the first credential that was *set* and never
+  reconsidered, so a revoked `CLAUDE_CODE_OAUTH_TOKEN` shadowed a working
+  `ANTHROPIC_API_KEY` and took the whole run down with a `401 OAuth access
+  token has been revoked`. `scripts/translate.rb` now treats 401/403 as a
+  credential failure rather than a request failure and retries with the next
+  configured credential, rebuilding the payload so the OAuth-only Claude Code
+  identity block is not sent with an API key. The switch is sticky, so a dead
+  credential costs one rejection per run rather than one per chunk.
+
+- **A failed translation run no longer opens a PR containing nothing** —
+  `_data/i18n/manifest.yml` stamped `updated_at` on every save, so a run in
+  which *every* page failed still produced a one-line diff. That was enough
+  for `translate.yml` to open (and keep updating) a PR that read like a routine
+  translation refresh and contained no translations. The manifest is now
+  written only when the mapping itself changed; a partially successful run
+  still pushes the pages that succeeded, and the run still exits non-zero.
+
+- **The cookbook is reachable from the navbar** — the `recipes` collection
+  (ZER0-084) shipped with a landing page at `/recipes/` that nothing linked to,
+  so the deployed cookbook could only be found by typing the URL.
+  `_data/navigation/main.yml` now carries a Recipes entry with the demo
+  recipes and the feature docs.
+
+- **Section sidebars no longer emit dead sub-topic anchors** — the sidebar
+  produced `<a href="#tag">` for every tag, but the matching
+  `<section id="tag">` target exists only in the `magazine` branch of
+  `_layouts/section.html`, and only for the first 5 sub-categories that keep a
+  post once the featured hero is excluded. `grid` and `list` sections (and
+  `grid` is the default) therefore emitted one dead anchor per tag, and
+  `magazine` emitted them for tags 6–15 — 64 of them on this repo's own demo
+  site. Dead anchors are invalid markup, a dead click for keyboard/AT users,
+  and they left the sidebar scrollspy unable to activate. Anchors are now
+  emitted only where a target provably exists; every other style renders
+  `<button data-filter>`, which the layout's existing handler already wires to
+  the `[data-tags]` cards. The `list` branch gained the `data-tags` attribute
+  it was missing (without it those buttons would have been inert), and the
+  filter handler now applies pill colours only to actual pills, so the pills
+  and the sidebar stay in sync instead of fighting over each other's classes.
+  Regression cover: `test/visual/features/section-topic-controls.spec.js`
+- **Consumer homepages no longer claim to be this theme** — the
+  `SoftwareApplication` JSON-LD in `_includes/content/jsonld-software.html` is
+  now opt-in via `jsonld_software_application` (set on this site only). The
+  block hardcodes this theme's RubyGems URL, GitHub repository, MIT licence,
+  feature list and author, but was wired unconditionally into every consumer's
+  homepage — so a consulting firm's site was telling search engines it was a
+  free open-source Ruby gem. Consumers need no action: absent config is falsey.
+  Evidence: [`test/visual/evidence/jsonld-software-optin/`](test/visual/evidence/jsonld-software-optin/README.md).
+- **`audit-consumer` misread most consumers' theme mode** — `detect_consumer_mode()`
+  matched `^remote_theme:` with no tolerance for whitespace before the colon, so
+  the column-aligned YAML style that 6 of 9 fleet consumers use never matched and
+  every one of them was silently reported as `gem` mode. That skipped the plugin
+  checks entirely, with no warning that they had been skipped.
+- **`audit-consumer --format json` emitted unparseable JSON** — every entry
+  carried a trailing comma, so the array always closed on `},\n]}`. The
+  human-readable log lines also went to stdout, mixing into the payload. Entries
+  are now comma-separated correctly and logging moves to stderr under
+  `--format json`, so the output pipes straight into `jq`.
+- **`audit-consumer` ignored Jekyll's `source:`** — a consumer that relocates its
+  site tree (e.g. `source: pages`) was audited at the repo root, reporting a
+  falsely clean "no overrides, no unique files". It now follows `source:` for the
+  file scan while still reading config and `.theme-overrides.yml` from the root.
+- **The Obsidian plugin was demanded of consumers that cannot run it** — the
+  manifest listed `_plugins/obsidian_links.rb` as required for every
+  `remote_theme` consumer, contradicting `obsidian.instructions.md`, which
+  documents it as opt-in and "skipped under the `github-pages` gem". GitHub Pages
+  builds in safe mode and loads no local plugins, so nothing the theme ships is
+  mandatory; `required_plugin_paths` is now empty and the plugin is optional.
+
+### Changed
+
+- **`_data/consumers.yml` now covers the whole fleet** — added `zer0-pages`,
+  `irony-works`, `wargames` and `zer0-pages-remote`, which were unregistered and
+  therefore invisible to `propagate.rb` in both directions (no release dispatch,
+  never in the drift report). The `it-journey` risk note was corrected: its
+  "~55 shadowed files / ~75 lines of !important CSS working around #338" claim
+  is not supported by `audit-consumer` — only 2 files shadow a theme file, the
+  CSS is 31 lines in this theme's own documented `user_overrides` hook, and no
+  fix numbered #338 could be substantiated in that repo.
+
 ## [1.28.0](https://github.com/bamr87/zer0-mistakes/compare/v1.27.0...v1.28.0) (2026-08-09)
 
 
@@ -42,8 +1147,33 @@ file. Only `## [Unreleased]` describes work that has not shipped yet.
 
 ## [Unreleased]
 
+### Fixed
+
+- **The skip link never moved keyboard focus (#278)** — `_layouts/root.html`
+rendered `<main id="main-content">` with no `tabindex`, and `<main>` is not natively focusable, so activating "Skip to main content" scrolled the page while focus stayed on `<body>`: the next `Tab` returned the user to the header nav they had just skipped. That defeats WCAG 2.4.1 (Bypass Blocks) on every consuming site, and the theme's own docs already prescribed the fix (`skip-to-content.md` → *Focus Not Moving* → "Add `tabindex=\"-1\"` to target") while the shipped layout omitted it. Now `<main id="main-content" tabindex="-1">`, paired with `#main-content:focus { outline: none; }` in `_sass/utilities/_focus.scss` so the container does not paint a ring — descendants keep theirs, and the rule is safe only because `-1` keeps the container out of the sequential `Tab` order. Measured across all three engines: focus lands on `#main-content` in Chromium, Firefox **and WebKit** (the engine the report named), where before it moved in none of them. The stale `<div id="main-content">` example in the English and French docs now matches the shipped markup.
+- **Seven theme dialogs labelled themselves with a bare `<h5>`** — the search
+modal, cookie settings modal, statistics help modal and the settings / background / section / admin offcanvases each opened with `<h5 class="modal-title">` or `<h5 class="offcanvas-title">`, so anyone navigating by heading met a level-5 heading as the dialog's title, skipping h3 and h4. Six other dialogs already used the correct `<h2 class="…-title h5">` form, so the theme contradicted itself half the time. All seven now match. `.h5` reproduces the exact sizing, so the change is visually inert. `_includes/docs/bootstrap-docs.html` and the docs prose examples are deliberately untouched — they reproduce upstream Bootstrap's own markup and should keep doing so. (evidence: [`test/visual/evidence/dialog-heading-levels/`](test/visual/evidence/dialog-heading-levels/README.md) — heading walk h2 → h5 becomes h2 → h2 on all six live dialogs, renders byte-identical)
+- **Cookie modal's "Your Privacy Rights" list was invisible in dark mode** — the
+list used Bootstrap's fixed `text-dark` utility inside a `bg-body` panel. `.text-dark` resolves to `rgba(var(--bs-dark-rgb), 1)`, and `--bs-dark-rgb` is **not** remapped by `[data-bs-theme=dark]` — it stays `33,37,41`, which is byte-for-byte the dark `--bs-body-bg` (`#212529`). Measured in a browser: **1.00:1**, against WCAG 1.4.3 (AA)'s 4.5:1 minimum. Not "hard to read" — the same colour as its background, on the one dialog a visitor is most likely forced to read, in the theme's default colour mode, shipped to every consumer. Now `text-body` (**11.85:1** dark, 15.43:1 light, unchanged). `.cookie-category`'s hardcoded `#dee2e6` border became `var(--bs-border-color)`, which is the identical colour in light mode and a visible one in dark. A regression test opens the dialog and asserts the measured contrast ratio — `axe` cannot catch this class of bug on this theme, because the skin system's `body::after` background image makes axe report every contrast check in the dialog as `incomplete` rather than a violation. (evidence: [`test/visual/evidence/cookie-consent-contrast/`](test/visual/evidence/cookie-consent-contrast/README.md) — dark-mode contrast 1.00:1 → 11.85:1, light mode unchanged)
+- **`--page` lookups never matched a real Giscus thread** — `normalize_page()`
+prepended a leading slash to build the discussion title, but Giscus's `pathname` mapping searches for `location.pathname` with the leading slash **removed** (verified live: `/posts/2025/01/21/remote-work-revolution/` requests `term=posts/2025/01/21/remote-work-revolution/`). So `seed` created discussions Giscus would never find, and `thread`/`draft`/`post --page` missed every thread Giscus created itself — the entire "build conversations from page comments" workflow was inoperable against real data. Lookups now match all four title spellings (with/without leading and trailing slash) so both new and legacy/hand-made threads resolve.
+- **`discussion_number_for_page` silently ignored pagination** — the query
+declared `$after` and selected `pageInfo`, but never used either, so on a site with more than 100 discussions no thread past the first page could ever be found. Now uses `gh api graphql --paginate`.
+- **`set -e` aborted the script on the success path** — `[[ -z "$NUMBER" ]] &&
+error ...` as the last statement of a branch returns 1 when the lookup *succeeds*, which `set -e` turned into a silent exit with no output at all. Latent and unreachable while lookups always failed; the fix above exposed it immediately. Rewritten as `if` blocks in `resolve_number_arg` and `cmd_post`.
+- **Giscus comments were broken sitewide** — every page rendering the comment
+widget showed `An error occurred: giscus is not installed on this repository` instead of a comment box, on `zer0-mistakes.com` and locally, because the [giscus GitHub App](https://github.com/apps/giscus) was never installed on the repository. The `_config.yml` values were all correct (`data-repo-id` and `data-category-id` both verified against the live GitHub API, repo public, Discussions enabled, `Announcements` category), which is exactly why it went unnoticed: **no check in the repo could see it**. The `Giscus Comments Configuration` core test only inspects config keys and Liquid, and `test/visual/features/comments.spec.js` stubs `giscus.app/client.js` out entirely — so all 16 core tests passed at 100% against a completely non-functional feature. **Resolved**: the app is now installed and `doctor` reports the chain healthy; comments render and accept sign-in on production. Verified with a seeded demo thread ([#379](https://github.com/bamr87/zer0-mistakes/discussions/379)) that the widget correctly resolves and displays.
+- **Docs claimed the widget "won't load on localhost"** — it does. Giscus keys
+off the `data-repo` attribute, not the page origin, so the iframe renders and reports real errors locally. The false claim told developers to expect a non-working widget in dev, which is precisely what hid this bug. `pages/_docs/features/giscus-comments.md` now documents localhost as a genuine end-to-end check, with a table mapping each rendered state to its cause.
+
 ### Added
 
+- **`giscus-discussions doctor`** — a new subcommand that verifies the entire
+comment chain end-to-end: repository public, Discussions enabled, `giscus.enabled: true`, `data-repo-id` actually belonging to this repo (the fork trap), `data-category-id` resolving to a real category, and — the part nothing else could check — whether the giscus GitHub App is installed, by asking the Giscus API itself. Exits non-zero with a specific remediation line per failure.
+- **Giscus health check in CI** — `.github/workflows/giscus-digest.yml` (already
+scheduled weekly) now runs `doctor` and fails the job with a summary when comments are down, so a sitewide comment outage surfaces on its own instead of waiting for a reader to report it.
+- **Troubleshooting: "The giscus app is not installed"** — a new section in the
+feature docs with captured screenshots of both the broken widget and the giscus.app configurator rejecting the repo, an explanation of why this step is uniquely easy to skip, a fork-specific warning, and a copy-pasteable `curl` health check.
 - **Obsidian graph frontend revamp** — the graph views now mirror the Obsidian
   desktop experience. The full graph page gains a floating **Graph settings**
   card (Filters / Display / Forces): search with `tag:`/`path:` operators,
@@ -369,13 +1499,13 @@ file. Only `## [Unreleased]` describes work that has not shipped yet.
   `index.md`, and navigation. Empty now serialises to `[]`; `deploy` is
   deploy-only and also skips agent-file rewrites.
 - **github-pages / remote profile emitted a broken `remote_theme`.** The remote
-  `_config.yml` template resolved `{{GITHUB_REPO}}` to the *site's* repo; it now
-  uses a dedicated `{{THEME_REMOTE}}` variable (default `bamr87/zer0-mistakes`,
+  `_config.yml` template resolved `{% raw %}{{GITHUB_REPO}}{% endraw %}` to the *site's* repo; it now
+  uses a dedicated `{% raw %}{{THEME_REMOTE}}{% endraw %}` variable (default `bamr87/zer0-mistakes`,
   overridable via `THEME_REMOTE`).
 - **Deploy workflow templates had unsubstituted variables.** Added
-  `{{DEFAULT_BRANCH}}`, `{{RUBY_VERSION}}`, and `{{SITE_NAME}}` to the template
+  `{% raw %}{{DEFAULT_BRANCH}}{% endraw %}`, `{% raw %}{{RUBY_VERSION}}{% endraw %}`, and `{% raw %}{{SITE_NAME}}{% endraw %}` to the template
   renderer, so the generated `jekyll-gh-pages.yml` (and docker-prod/azure-swa
-  artifacts) no longer contain literal `{{…}}` tokens. Regression tests assert
+  artifacts) no longer contain literal `{% raw %}{{…}}{% endraw %}` tokens. Regression tests assert
   no unresolved tokens survive in any deploy artifact.
 - **Agent files were written twice** when `agents` appeared in both the task
   list and `SPEC_AGENTS`; `apply.sh` now runs the agents task at most once.
@@ -522,7 +1652,7 @@ file. Only `## [Unreleased]` describes work that has not shipped yet.
 - **Author avatars never render as protocol-relative `//assets/…` URLs** —
   `author-avatar-url.html` now builds the relative-path branch in a capture,
   collapses doubled slashes, and applies `relative_url` exactly once, instead
-  of the manual `{{ site.baseurl }}/{{ site.public_folder }}{{ avatar }}`
+  of the manual `{% raw %}{{ site.baseurl }}/{{ site.public_folder }}{{ avatar }}{% endraw %}`
   concatenation that produced `src="//assets/…"` (a URL browsers resolve
   against a host named `assets`) on consumer sites where `public_folder` is
   unset or carries a leading slash
@@ -1068,7 +2198,7 @@ file. Only `## [Unreleased]` describes work that has not shipped yet.
   to it from the Bootstrap, Layouts, and Styles docs.
 - **Bylines now use the shared author component.** The `article`, `note`,
   `notebook`, `news`, and `section` layouts plus `components/post-card.html`
-  previously printed `{{ page.author }}` as bare text; they now render
+  previously printed `{% raw %}{{ page.author }}{% endraw %}` as bare text; they now render
   `components/author-card.html` (`inline`), so a known author key resolves to a
   display name, avatar, and a link to their profile page. The inline
   "About the Author" block that was hard-coded in `_layouts/article.html` was
@@ -1215,7 +2345,7 @@ file. Only `## [Unreleased]` describes work that has not shipped yet.
 - Version bump: patch release
 
 ### Commits in this release
-- ae76a61f fix(content-review): correct code-fence detection (closing fences + {% raw %}) (#155)
+- ae76a61f fix(content-review): correct code-fence detection (closing fences + {% raw %}{% raw %}{% endraw %}) (#155)
 - f00fb654 docs(seo): strengthen SEO docs index metadata + fix agent-tier workflow (#154)
 
 ### Fixed
@@ -1225,10 +2355,10 @@ file. Only `## [Unreleased]` describes work that has not shipped yet.
   a file's score (e.g. `pages/_about/features/jekyll.md` scored 0/100 almost
   entirely from this false positive). The check now tracks fence open/close state
   and only validates opening fences.
-- **content-review: ignore Liquid `{% raw %}` blocks** in the quality and style
-  checks. Code fences, headings, images, and terminology inside `{% raw %}…
-  {% endraw %}` are literal display examples, not page structure, and were being
-  counted as real findings.
+- **content-review: ignore Liquid `{% raw %}{% raw %}{% endraw %}` blocks** in the quality and style
+  checks. Code fences, headings, images, and terminology inside a Liquid
+  `{% raw %}{% raw %}{% endraw %}` block are literal display examples, not page
+  structure, and were being counted as real findings.
 
 ## [1.18.0] - 2026-06-13
 
@@ -1656,7 +2786,7 @@ file. Only `## [Unreleased]` describes work that has not shipped yet.
 - **Sidebar collapse — VS Code style**: Left sidebar (`#bdSidebar`) and right TOC (`#tocContents`) now collapse to a slim 36 px rail (`--zer0-sidebar-rail-width`) instead of being fully hidden on desktop. The visibility toggle icon (`bi-layout-sidebar-inset` / `bi-layout-sidebar-inset-reverse`) stays mounted on the rail so users can re-expand the panel with a single click — the floating action buttons (`.bd-sidebar-fab`, `.bd-toc-fab`) are now hidden at `≥992 px` since the rail toggle replaces them. `_sass/core/_docs-layout.scss`, `_sass/layouts/_navbar-extras.scss`.
 - **Smooth transitions**: `.bd-layout` and `.bd-main` now animate `grid-template-columns` and `gap` over `--zer0-motion-duration-base` (0.3 s) with `--zer0-motion-ease-standard`; sidebar contents cross-fade via `opacity` + delayed `visibility`. Honors `@media (prefers-reduced-motion: reduce)` by disabling all related transitions.
 - **Toggle behavior**: `sidebar-visibility.js` and `toc-visibility.js` no longer set `button.hidden = true` on the rail toggle when collapsed, keeping it interactive in the collapsed state. Aria labels (`Hide…` / `Show…`) update on each toggle.
-- **Cache-bust**: Added `?v={{ site.time | date: '%s' }}` to the navigation ES-module `<script type="module">` tag in `_includes/components/js-cdn.html` to force re-fetch on rebuild (browsers cache ES modules indefinitely by URL).
+- **Cache-bust**: Added `{% raw %}?v={{ site.time | date: '%s' }}{% endraw %}` to the navigation ES-module `<script type="module">` tag in `_includes/components/js-cdn.html` to force re-fetch on rebuild (browsers cache ES modules indefinitely by URL).
 - **Navbar dropdown**: Dropdown toggle button set to `align-self: stretch` so it spans the full navbar height, making it easier to invoke on touch/small screens; chevron icon `font-size` increased to `1em` for better legibility. `_sass/core/_navbar.scss`.
 - **Syntax highlighting**: Dual-palette system — `_sass/core/_syntax.scss` now uses a GitHub Light palette for `.highlight` (light mode) and scopes the Material Dark base16 palette to `[data-bs-theme="dark"] .highlight`, fixing near-invisible token colors on light backgrounds.
 - **Theme preview gallery**: Expanded to 20 sections with 6 new components: Callouts (5 types), Accordion, Progress & Spinners, Breadcrumb & Pagination, Tooltips & Popovers, and Icons showcase. TOC updated accordingly; Bootstrap tooltip/popover JS initializer added. `_includes/components/theme-preview-gallery.html`, `pages/_about/settings/theme-preview.md`.
@@ -2701,7 +3831,7 @@ See [`docs/installation/migration-from-0.x.md`](docs/installation/migration-from
 - **Troubleshooting Guide**: Added sections for Docker issues, Jekyll build errors, front matter problems, performance optimization
 - **Jekyll Guide**: Added directory structure, configuration files, content collections, essential commands, topic index
 - **Bootstrap Guide**: Added CDN loading patterns, key components, responsive breakpoints, custom styles, icons
-- **Liquid Guide**: Added syntax examples with `{% raw %}` tags, filters, control flow, includes
+- **Liquid Guide**: Added syntax examples with `{% raw %}{% raw %}{% endraw %}` tags, filters, control flow, includes
 - **Ruby Guide**: Added version commands, common commands, key files, Docker usage, troubleshooting
 - **Front Matter Guide**: Added required/optional fields, layout options, collection-specific fields, complete examples
 - All documentation pages now include `sidebar: nav: docs` for consistent navigation