jekyll-theme-zer0 1.28.0 → 1.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b72b3e6bf60fc9df7f31ecd56d157770fede085973db6d2153980c3004bc0fc
-  data.tar.gz: 369c0158b06d41d52c3f737d9a88a44e2cb9265653db55bf376e0651a502980b
+  metadata.gz: 22bc691450211a10284e51255f65418727383515f13a57a8fe8c28d10ac8396d
+  data.tar.gz: 7f0beac42b974ae3b60d43977a4e01c614e03d1936bd50b726e208dfe18f26b0
 SHA512:
-  metadata.gz: 0d89cbf414b78be0b73fd22f8102dfacf8e38f10c561b2cc50fb4b492b8840d15e38f3b83243a589cd32f7fe7d72e4eb009a8dba44f09634e5e6611195971566
-  data.tar.gz: cbcbec935073100919c21c9f3f542124a291529a93212706b8c7e82773a4361d7b272cc60ec966f077213c6c7ae23d36a60ad129c08bfd33506d382172109a88
+  metadata.gz: c101f2069a24c1d0c2745f1230575470492d621bca406d39ae036802ec450c9442d1c738cc949e60fd15dac2a8ced421d51b46a4737c59327038fbecd1a3de43
+  data.tar.gz: 7e019f09b5658412bfb82779b2aa3d94bcc9fd3c0022f97d980aaffdb0ef8b84d02fa2247b085f0d7ebbd23b0d22182f802a77eb25cc1ca892f7bf8c46f872a4

data/CHANGELOG.md

@@ -12,6 +12,398 @@ 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.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]
+
+### Changed
+
+- **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
+
+- **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
+  `{% include core/head.html %}` (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 +434,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 +786,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 +939,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 +1485,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 +1632,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 +1642,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 +2073,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 +3118,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