jekyll-theme-zer0 1.27.0 → 1.29.0

data/CHANGELOG.md

@@ -5,6 +5,805 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+Two kinds of section appear below. `## [X.Y.Z]` headings are generated by
+release-please from Conventional Commits and are the authoritative record of
+what shipped in each release. `## Detailed notes — vX.Y.Z` headings are
+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)
+
+
+### Features
+
+* **books:** children's picture-book collection with immersive layouts and components ([#328](https://github.com/bamr87/zer0-mistakes/issues/328)) ([e059d1a](https://github.com/bamr87/zer0-mistakes/commit/e059d1afdc95073c5ce5bf9d1516b362979ad402))
+* **ci:** deploy the site via Actions so examples reach the live domain ([#353](https://github.com/bamr87/zer0-mistakes/issues/353)) ([959243c](https://github.com/bamr87/zer0-mistakes/commit/959243c0e8e504fe5d8dba44b89016b413bc88da))
+* **docs:** theme-canary reporting contract for downstream theme-scouts (FF-0019) ([#358](https://github.com/bamr87/zer0-mistakes/issues/358)) ([c1c1b30](https://github.com/bamr87/zer0-mistakes/commit/c1c1b309c5504b014602982fc96ec80c3f8f70de))
+* **examples:** add serialized reading-blog example site ([#339](https://github.com/bamr87/zer0-mistakes/issues/339)) ([aca0b53](https://github.com/bamr87/zer0-mistakes/commit/aca0b53b88067bda80fb299f9d5148ccb185d618))
+* **includes:** config-driven favicon, GTM gating, og:image fallback fix, sidebar nav aliases ([#327](https://github.com/bamr87/zer0-mistakes/issues/327)) ([fe8aacc](https://github.com/bamr87/zer0-mistakes/commit/fe8aacc234003f9f170fcb3b8b29c60ac18ed94b))
+* **install:** Claude Code OAuth + multi-provider AI + config-file layer ([#330](https://github.com/bamr87/zer0-mistakes/issues/330)) ([fde414c](https://github.com/bamr87/zer0-mistakes/commit/fde414cce5286f90de1ad02ca6ca40d634be5611))
+* **layouts:** book-abc board-book layout + ABC art-style skins ([#336](https://github.com/bamr87/zer0-mistakes/issues/336)) ([d88038e](https://github.com/bamr87/zer0-mistakes/commit/d88038e806e0d1a492e5d12b4e10e55fd240d692))
+* **navigation:** nav: pages sidebar mode — auto-build the tree from page URLs ([#333](https://github.com/bamr87/zer0-mistakes/issues/333)) ([c0c627d](https://github.com/bamr87/zer0-mistakes/commit/c0c627d5f50051e8f5eb4f0d6681244acaaa8d85))
+* **obsidian:** revamp graph frontend with Obsidian-style controls ([#366](https://github.com/bamr87/zer0-mistakes/issues/366)) ([7143d9c](https://github.com/bamr87/zer0-mistakes/commit/7143d9cd137408ad82981c9f9835204bab3a3db5))
+* **theme:** consumer-adoption hardening — mobile overlay fixes, zero-data resilience, extension hooks ([#338](https://github.com/bamr87/zer0-mistakes/issues/338)) ([84bcce1](https://github.com/bamr87/zer0-mistakes/commit/84bcce15e66b0bc312f513cef4a9dd11f972a049))
+
+
+### Bug Fixes
+
+* **books:** pin abc-demo permalink so its cover lands at /books/abc-demo/ ([#345](https://github.com/bamr87/zer0-mistakes/issues/345)) ([943f463](https://github.com/bamr87/zer0-mistakes/commit/943f463c73081e7cc3d914c28a2ec2eea3d1b5ae))
+* **ci:** give the Dependabot label job an explicit GH_REPO ([#370](https://github.com/bamr87/zer0-mistakes/issues/370)) ([808b20e](https://github.com/bamr87/zer0-mistakes/commit/808b20ebbdcd5b0bc139b90947297cec6d226787))
+* **ci:** prefer CLAUDE_CODE_OAUTH_TOKEN over ANTHROPIC_API_KEY in all AI workflows ([#334](https://github.com/bamr87/zer0-mistakes/issues/334)) ([043848e](https://github.com/bamr87/zer0-mistakes/commit/043848eb84222240efc121e8112ddc12ab959a64))
+* **ci:** unbreak the production Pages build, frozen since 2026-08-05 ([#356](https://github.com/bamr87/zer0-mistakes/issues/356)) ([05465cf](https://github.com/bamr87/zer0-mistakes/commit/05465cfd5480a6bdfb0d164d56a892f2825ec1cf))
+* **i18n:** exclude admin config page from translation to unbreak Pages deploy ([#349](https://github.com/bamr87/zer0-mistakes/issues/349)) ([3f4890c](https://github.com/bamr87/zer0-mistakes/commit/3f4890cee3dd59b7f1cbc6ec235a863017b075fb))
+* **i18n:** normalise generated prose so translation runs keep CI green ([#342](https://github.com/bamr87/zer0-mistakes/issues/342)) ([70a7234](https://github.com/bamr87/zer0-mistakes/commit/70a723425b8cc6a77e1b845b212a8a7d127a7779))
+* **navigation:** mark only the current page active in the sidebar nav-tree ([#331](https://github.com/bamr87/zer0-mistakes/issues/331)) ([3f1b723](https://github.com/bamr87/zer0-mistakes/commit/3f1b723169258993d4530dd5817740e62734ccd4))
+* **sass:** restore mobile navigation in the example, collapsed to a 60px sliver ([#363](https://github.com/bamr87/zer0-mistakes/issues/363)) ([8c7d87a](https://github.com/bamr87/zer0-mistakes/commit/8c7d87af4fd476f06c16ce58ca4d4cd0e2c4169d))
+
+## [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,
+  per-collection toggles generated from the wiki-index (count badge + color
+  swatch, doubling as the legend), show-orphans and show-unresolved switches,
+  node-size / link-thickness / label-fade sliders, repel-force and
+  link-distance sliders with animated re-layout, plus a zoom / fit / fullscreen
+  button stack, an Obsidian-style hover preview card, live dark-mode restyling,
+  and localStorage persistence. The local graph panel gains a depth selector
+  (1–3) and outgoing/incoming direction switches that re-render the subgraph in
+  place. Same vendored cytoscape.js, unchanged `wiki-index.json` contract
+  (evidence:
+  [`test/visual/evidence/obsidian-graph-revamp/`](test/visual/evidence/obsidian-graph-revamp/README.md);
+  regression: `test/visual/features/obsidian-graph.spec.js`).
+
+- **Theme-canary reporting contract** (`docs/systems/theme-canary-contract.md`) —
+  the canonical upstream bug-intake protocol for downstream theme-scout agents
+  (it-journey, lifehacker.dev): required `theme-canary` + `from-<consumer>`
+  labels, a deterministic 12-hex dedupe key + hidden body marker, the mandated
+  open-AND-closed pre-filing search, a 5-issues-per-consumer-per-run cap, and a
+  required evidence format that records the theme version/commit observed (so
+  fixed-in-release triage is mechanical). Ships with the matching
+  `theme-canary.yml` issue form.
+
+### Fixed
+
+- **Mobile navigation opened as an unusable 60px sliver in the Swerve of Shore
+  example.** Its skin set `backdrop-filter` on `.navbar` for a frosted sticky
+  header, which — per the CSS spec, alongside `transform`/`filter`/`perspective`
+  — makes that element the containing block for its `position: fixed`
+  descendants. The theme's main-nav panel (`#bdNavbar`, an `.offcanvas-lg`) is
+  one, so it sized itself against the 60px navbar instead of the viewport:
+  tapping the hamburger dimmed the page and showed a bare title bar with **0 of
+  14 navigation links** reachable. The effect now lives on a `.navbar::before`
+  pseudo-element — visually identical, not an ancestor — restoring the
+  full-height panel with **14 of 14** links (evidence:
+  [`test/visual/evidence/mobile-nav-containing-block/`](test/visual/evidence/mobile-nav-containing-block/README.md)
+  — panel 60px → 780px at 390 and 768). A new smoke-tier spec
+  (`test/visual/features/mobile-nav-containing-block.spec.js`) guards the
+  invariant on the theme and names the offending ancestor when it fails.
+
+- **The example's home and blog pages overflowed and ran edge-to-edge on
+  phones.** Their feed grid used Bootstrap's `.row` gutters without a container
+  to absorb the −12px margins, making the page 13px wider than the screen, and
+  neither section carried an inline padding, so 15 of 30 text blocks sat flush
+  against the bezel. Now `gx-0 gy-4` plus a 0.75rem mobile gutter matching the
+  theme's own 12px inset — zero horizontal overflow at 320–768, banner still
+  full-bleed.
+
+- **GitHub Pages production deploy no longer fails at all — the site had been
+  frozen since 2026-08-05.** Three independent faults, each of which aborted the
+  whole production `jekyll build`, so nothing published after #346:
+  1. `_layouts/collection.html` sorted `site[page.collection]` without checking
+     it resolved. A page can select this layout in front matter while living
+     outside any collection, making that lookup `nil`; Liquid's `sort` then
+     raises `Cannot sort a null object.` and kills the *entire* build, not just
+     the page. It now falls back to an empty list.
+  2. `scripts/translate.rb` copied `layout: collection` into the flat `fr/**`
+     tree, which is exactly the misconfiguration above — `fr/docs/index.md` was
+     the page that took the site down. Collection-only layouts are now dropped
+     from generated translations so the `path: fr` default (`layout: default`)
+     applies, and the affected page is regenerated.
+  3. `CHANGELOG.md` is a published page (`/CHANGELOG/`), so its prose is parsed
+     as Liquid. Two entries quoted Liquid tags without a `raw` guard; one of
+     them genuinely executed `include_relative` on `_config.yml`, which in turn
+     tripped over a literal `mermaid` tag written inside a config comment.
+     Both entries are now guarded and the config comment no longer spells the
+     tag out.
+
+- **Production builds are now verified before merge.** `.github/workflows/pages.yml`
+  builds (never deploys) on pull requests. No other job ran `jekyll build`
+  against the production config, which is why all three faults above reached
+  `main` with CI green.
+
+- **GitHub Pages production deploy no longer fails on the translated config
+  page.** The admin config utility `pages/_about/settings/config.md` embeds a
+  raw `_config.yml` dump via {% raw %}`{% include_relative _config.yml %}`{% endraw %}, but the
+  translation pipeline copied the page into `fr/about/settings/` without its
+  sibling data file, so the production `github-pages` build died with
+  `Could not locate the included file '_config.yml'`. The page is now excluded
+  from translation (`translation.exclude` in `_config.yml`) — it has no
+  prose to translate anyway — and the stale `fr/about/settings/config.md` plus
+  its `_data/i18n/manifest.yml` entry are removed.
+- **Translation runs no longer break the `oneline` check.** `scripts/translate.rb`
+  writes whatever the provider returns, and a provider is free to soft-wrap a
+  translated paragraph across several lines — no prompt instruction reliably
+  prevents it. Wrapped prose then landed in `fr/**`, turned
+  `markdown-oneline.yml` red on the translation PR, and stayed red on `main`
+  after it merged. Two of the currently committed translations were in exactly
+  that state.
+  - `translate.rb` now normalises every page it writes through
+    `tools/unwrap-prose.py` — the same tool CI runs, so the rule has one source
+    of truth instead of a reimplementation that could drift. Best-effort: a
+    missing `python3` warns rather than failing an otherwise good run.
+  - `.github/workflows/translate.yml` runs the same tool as a guaranteed
+    backstop immediately before committing, then `--check`s its own work so a
+    silent failure cannot just move the breakage to the PR's CI run.
+  - The tool is resolved relative to `translate.rb` rather than `--root`;
+    `--root` points at the content tree being translated, so the previous
+    lookup missed the tool whenever the two differed.
+  - Unwrapped the two affected files, so `oneline` passes on `main` again.
+  - Regression test in `test/test_i18n.sh` backed by a new `stub-wrap`
+    provider that soft-wraps at 40 columns. Asserting "output is unwrapped"
+    against the plain stub would have passed whether or not normalisation ran.
+
+### Added
+
+- **`examples/` — self-contained demo sites built on the theme.** New top-level
+  directory (excluded from the theme's own site build and from the gem) for
+  complete Jekyll sites that show the theme configured for a particular kind of
+  site. Each has its own `_config.yml`, `Gemfile`, and content, and builds
+  against the local theme sources via `_config_dev.yml`.
+  - `examples/swerve-of-shore/` — **Swerve of Shore**, a serialized literary
+    reading blog rebuilt from
+    [swerveofshore.com](https://www.swerveofshore.com/) with the site owner's
+    permission. 52 pages, 0 broken internal links. Exercises a `series` output
+    collection with nested per-section paths, a data-driven taxonomy
+    (`_data/episodes.yml`) that generates the sidebar rail, the episode
+    schedule with live entry counts, and a section page for every node — so a
+    nav target resolves even where nothing is written yet. Also covers article
+    hero images (`show_hero`), entries ordered by number rather than date, the
+    shared `post-card` component in a single-column feed, and a full editorial
+    light-mode restyle done entirely through `assets/css/user-overrides.css` —
+    no theme files touched. The site's identity, taxonomy, entry titles/dates,
+    and featured images are reproduced, along with a short quoted excerpt per
+    entry (the opening the original publishes in its own RSS feed), attributed
+    and linked back. The essays themselves are not reproduced.
+  - `examples/README.md` — how to run one and the conventions for adding
+    another.
+- **Theme propagation system — releases now reach the sites built on them.**
+  Releasing ended at RubyGems; nothing told the five downstream consumers a new
+  version existed, so all three pinned sites were still on v1.26.0 when v1.27.0
+  shipped and the two unpinned ones had been silently tracking `main`.
+  - `_data/consumers.yml` — registry of every consumer, its consumption mode
+    (`remote_theme_pinned` / `remote_theme_floating` / `gem` / `path`), and every
+    file that holds a version pin.
+  - `scripts/propagate.rb` — reports pin drift across the registry
+    (`--format text|json|github`, `--strict`) or dispatches a `theme-release`
+    event to each consumer (`--dispatch`).
+  - `.github/workflows/propagate-theme.yml` — dispatches on release publish;
+    weekly drift report. Never pushes to a consumer: each one opens its own PR so
+    its own CI gates the bump.
+  - `templates/consumer/` — the consumer's half of the contract:
+    `bump-theme-pins.sh` (rewrites `remote_theme`, `theme_repo`, and Gemfile gem
+    constraints in one pass; `--check`, `--dry-run`, `--latest`, `--pin`),
+    `theme-bump.yml` (dispatch + weekly schedule + manual), and a
+    `.theme-overrides.yml` starter. The schedule matters most for gem-mode
+    consumers, which have no `remote_theme` and so pick up nothing automatically.
+  - `docs/systems/theme-propagation.md` — how the whole flow fits together.
+- **`./scripts/bin/manifest --check`** — verifies the committed theme manifest
+  matches the working tree, ignoring `generated_at`. `--dry-run` now emits only
+  YAML on stdout (progress logs moved to stderr) so its output can be diffed
+  directly.
+- **Consumer extension hooks (`_includes/custom/`).** Four empty stubs the
+  chrome now includes at fixed points — `custom/head.html` (end of `<head>`),
+  `custom/body-start.html` (right after `<body>`, e.g. GTM noscript),
+  `custom/footer.html` (after the theme footer), `custom/body-end.html` (last
+  thing before `</body>`). A consumer site shadows just the stub to inject
+  JSON-LD, fonts, verification tags, or scripts — no more forking
+  `core/head.html`/`root.html` and drifting from the theme. Documented in
+  `_includes/README.md`.
+- **`components/card-grid.html` + `components/data-card.html`.** A generic,
+  data-driven card grid (title/url/icon/badge/meta-pills/buttons schema) for
+  org hub dashboards, fleet registries, service grids, and link boards —
+  the markup consumer sites have been hand-rolling per page. Includes an
+  optional empty-state message.
+- **`_layouts/404.html` — the 404 page as a theme layout.** The full 404
+  experience (including the unconfigured-site setup guide) now lives in the
+  theme; a consumer's `/404.html` shrinks from a 224-line vendored copy to a
+  4-line front-matter stub (`layout: "404"`). Setup mode is branded with
+  `site.title` instead of a hardcoded theme welcome, and the stub page's body
+  renders below the standard content for site-specific additions.
+- **`color_mode_lock` config.** Pin the site to one color mode: visitor
+  preference and OS scheme are ignored, the light/dark/auto switcher is
+  removed, and `core/color-mode-init.html` + `halfmoon.js` enforce the lock
+  pre-paint. Replaces consumer JS workarounds that re-asserted a mode on every
+  `matchMedia` change.
+- **PostHog privacy options** (`posthog.privacy.*`): `respect_gpc` (honor the
+  Global Privacy Control signal alongside DNT, default on), `require_consent`
+  (start opted out with memory-only persistence until the visitor accepts the
+  cookie-consent "analytics" category), and `geoip_disable` (no IP→location
+  resolution). Upstreams the deltas consumer sites were maintaining in a
+  full fork of `analytics/posthog.html`.
+- **`news:` config surface for the news/section layouts.** `category_base`
+  (e.g. `/categories/` instead of the hardcoded `/news/`), `index_url`,
+  `hero: false`, `archives_url`, and a `newsletter` block (endpoint-or-mailto,
+  or hidden entirely — the old markup shipped a form that submitted nowhere).
+
+### Changed
+
+- **The news/section layouts work with zero `_data`.** Section navigation
+  falls back from `_data/navigation/posts.yml` to `site.categories`; the hero
+  falls back to the newest post when nothing is marked `breaking`/`featured`;
+  tags links render only when a tags page exists (honoring `site.tags_page`);
+  archive month links render only when an archives page exists. A data-less
+  consumer now gets a fully working magazine homepage instead of empty chrome
+  and 404 links.
+- **Zero-`_data` resilience across components.** The skin quick-select and
+  theme customizer fall back to the compiled skin registry when
+  `_data/theme_skins.yml` is absent; the page-feedback widget falls back to a
+  generic four-type taxonomy when `_data/feedback_types.yml` is absent; the
+  landing get-started band (theme install cards) renders only when the site
+  ships a `landing.get_started` block — a data-less consumer no longer
+  advertises the theme's own install methods.
+- **`home` layout accepts `hide_intro` as an alias of `hide_title`**, matching
+  the flag other layouts use for "suppress the generated page header".
+- **`halfmoon.js` honors `color_mode_default`.** The switcher no longer
+  overrides the configured default with the OS preference on first visit
+  (previously the page could flip modes right after load).
+- The default skin fallback is now `air` everywhere (`root.html`,
+  controls bar, customizer) — `dark` was never a compiled skin, so the old
+  fallback selected a skin that doesn't exist.
+
+### Fixed
+
+- **`_data/theme-manifest.yml` was 13 minors stale.** It sat at `1.14.0` while
+  the theme shipped to `1.27.0`, so every SHA-256 in it was wrong and
+  `scripts/bin/audit-consumer` — which reads it to classify consumer files —
+  silently compared against a June snapshot. Root cause: the file's header said
+  it regenerated during `scripts/bin/release`, but release-please became the
+  canonical release path and knows nothing about it. Regenerated, and now held
+  current by a CI gate (`version.rb` ↔ manifest version) plus
+  `manifest-sync.yml`, which regenerates it inside the release PR.
+- **`test/fixtures/consumer-gem/_layouts/default.html` had drifted from the
+  theme layout it mirrors**, so the "`--fix` deletes IDENTICAL files" audit test
+  had been failing since the layout changed in #310 — the fixture was being
+  classified `DIFFERS_UNJUSTIFIED` rather than `IDENTICAL`, testing the opposite
+  of its intent. Re-synced; the audit suite is green again (21/21).
+- **Mobile overlays no longer trap under the page chrome.** The
+  `.zer0-bg-body` background utility isolates the body stacking context and
+  pushes the noise overlay to `z-index: -1` instead of force-elevating every
+  direct child (`position: relative; z-index: 1`). That old rule made `<main>`
+  a stacking context that (a) capped the docs-sidebar offcanvas below the
+  fixed header — its close button was unreachable on mobile — and (b) beat
+  FAB `position: fixed` rules on specificity, dropping them into flow and
+  adding 16px of horizontal scroll on content pages.
+- **Main-nav offcanvas paints above its backdrop on mobile.** The fixed header
+  is lifted over Bootstrap's body-level backdrop only while `#bdNavbar` is
+  opening/open/closing, so the menu is actually tappable instead of rendering
+  dimmed behind the backdrop.
+- **The unified drawer's Search button works.** It targeted `#search-modal`
+  but the modal's id is `#siteSearchModal`; it now uses the shared
+  `data-search-toggle` binding, which also closes the drawer before opening
+  search.
+- The measured header height is published as `--zer0-header-height` on
+  `:root` (set by `auto-hide-nav.js`), so stylesheets can align overlays with
+  the real header instead of hard-coding its pixel height.
+
+### Added
+
+- **ABC board books (`book-abc` layout) — the "ABC & Language" series.** A new
+  immersive, single-scroll toddler alphabet layout (`_layouts/book-abc.html`)
+  driven entirely by an `alphabet:` front-matter list — one big letter, one
+  word, one picture per card, with A–Z quick-jump anchors and a cover hero.
+  The big letter is HTML typography (never baked into the art), and a card
+  whose plate is still `planned` shows a tinted "illustration coming soon"
+  placeholder so a book reads end-to-end before any art renders. New
+  `_includes/components/abc-letter.html` renders each card; `_sass/components/_book.scss`
+  gains `.abc-board` / `.abc-letter-*` styles plus a `.abc-style--<id>` skin per
+  shared art-style id. `components/bookshelf.html` now lists both `book` and
+  `book-abc` books, grouped into series shelves from `_data/series.yml`;
+  `book-card.html` shows a letter count for ABC books. Ships a demo book
+  (`pages/_books/abc-demo/`) + default series metadata (`_data/series.yml`).
+  Regression test [`test/visual/features/book-abc.spec.js`](test/visual/features/book-abc.spec.js)
+  and before/after evidence in
+  [`test/visual/evidence/book-abc/`](test/visual/evidence/book-abc/). Docs:
+  [`docs/features/abc-books.md`](docs/features/abc-books.md).
+- **`nav: pages` sidebar mode — auto-build the left tree from page URLs.** A new
+  sidebar mode (`_includes/navigation/sidebar-pagetree.html`) derives a
+  collapsible section tree purely from page permalinks under a `sidebar.base`
+  prefix — no curated `_data/navigation/*.yml` file to write or keep in sync.
+  Enable per page / collection / site with `sidebar: {nav: pages, base: /docs/,
+  order_by: nav_order, title: …}`. It covers plain pages (`site.html_pages`) and
+  collection documents (`site.documents`) alike, groups them by first path
+  segment, humanizes section labels from the URL (never leaking a generic
+  "Index" title), sorts each section by a numeric `order_by` (natural order),
+  supports per-page `sidebar_label` / `sidebar_exclude`, and marks only the
+  current page active with its section expanded server-side — pure Liquid, so
+  it is GitHub Pages / `remote_theme` safe. Documented at
+  `/docs/features/sidebar-page-tree/`.
+- **Claude Code OAuth in the AI installer** — the spec-driven installer
+  (`scripts/bin/install`) is now multi-provider. `scripts/install/ai/client.sh`
+  resolves a provider via `ZER0_AI_PROVIDER` (default `auto`), preferring the
+  logged-in `claude` CLI (**Claude Code OAuth** — zero key handling), then the
+  Anthropic Messages API (`CLAUDE_CODE_OAUTH_TOKEN` OAuth bearer or
+  `ANTHROPIC_API_KEY`), then OpenAI. `install doctor` reports the active
+  provider; `--ai-provider` / `--ai-model` / `ZER0_AI_MODEL` tune it; `--no-ai`
+  / `ZER0_NO_AI=1` disable it. User context is sanitized before every call.
+- **Config-file layer for the installer** — new `scripts/install/config.sh`
+  discovers and merges `~/.config/zer0/install.yml`, `<target>/zer0.install.yml`,
+  `<target>/.zer0/config.yml`, and `--config FILE` (precedence:
+  defaults < profile < config < env < flags). Recognises site / github / theme /
+  deploy / agents / tasks / ai keys; API keys stay environment-only.
+- **`install suggest`** subcommand — recommend a profile + deploy target
+  (AI-assisted with rule-based fallback) — plus `--yes` as an alias for
+  `--auto-accept`.
+- Installer regression matrix (`test/test_installer.sh`) now covers AI
+  provider resolution, text extraction across provider shapes, the config-file
+  layer + precedence, and the `doctor` AI check (all offline).
+
+### Changed
+
+- Installer spec default `ai.provider` is now `auto` (was `openai`); the AI
+  wizard records the provider that actually served the run.
+- **CI workflows now honor `CLAUDE_CODE_OAUTH_TOKEN`** — `ui-audit.yml`,
+  `ai-content-review.yml`, and `ci-self-repair.yml` previously gated their
+  Claude Code agent tier on `ANTHROPIC_API_KEY` alone, silently ignoring a
+  configured OAuth token. They now follow the same house convention as
+  `claude.yml` / `issue-autopilot.yml`: `CLAUDE_CODE_OAUTH_TOKEN` preferred,
+  `ANTHROPIC_API_KEY` used only when it's absent.
+
+### Fixed
+
+- **Left-sidebar nav highlighted every item as "active".** `nav-tree.html`
+  used {% raw %}`{% assign is_active = page.url == item.url %}`{% endraw %}, but Liquid `assign`
+  does not evaluate `==` — it stored `page.url` (always truthy), so every link
+  rendered with the active style. Replaced the three broken assigns
+  (`is_active`, `child_active`, `gc_active`) with proper conditional assigns so
+  only the current page is marked active.
+- **`install deploy` no longer clobbers site content.** `spec_write` treated an
+  empty `SPEC_TASKS` as "use the full default task list", so a deploy-only run
+  re-ran `config`/`pages`/`nav` and overwrote a customised `_config.yml`,
+  `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 `{% 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
+  `{% 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 `{% 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.
+- **The remote / github-pages Gemfile failed to build on Ruby 3.x.** It paired
+  the legacy `github-pages` gem with a standalone `jekyll-remote-theme`, which
+  bundler resolved to an ancient github-pages 170 (Jekyll 3.6 / kramdown 1.14,
+  `rexml` LoadError). The remote Gemfile now pins modern Jekyll +
+  `jekyll-remote-theme` + `webrick`, and both the Gemfile and the remote
+  `_config.yml` template add `jekyll-include-cache` (required by the theme's
+  layouts).
+
 ## [1.27.0](https://github.com/bamr87/zer0-mistakes/compare/v1.26.0...v1.27.0) (2026-07-22)
 
 
@@ -34,7 +833,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * **feedback:** runtime "Improve this page" capture → GitHub issue (logs + AI triage) ([#286](https://github.com/bamr87/zer0-mistakes/issues/286)) ([f7fb20d](https://github.com/bamr87/zer0-mistakes/commit/f7fb20df74c22df7eb823344121c60617f06c7b6))
 
-## [Unreleased]
+## Detailed notes — v1.27.0
 
 ### Added
 
@@ -140,7 +939,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **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
@@ -222,7 +1021,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * **navigation:** remove redundant entries from navigation menus ([916eca2](https://github.com/bamr87/zer0-mistakes/commit/916eca269726c984c5c0c9dc9533c83d9975f906))
 * **sass:** mobile audit — contain author card, restore consent z-order, grow tap targets ([#275](https://github.com/bamr87/zer0-mistakes/issues/275)) ([8ec9867](https://github.com/bamr87/zer0-mistakes/commit/8ec9867858ff87e9b8a6fcd4a68ec7e50582c3c1))
 
-## [Unreleased]
+## Detailed notes — v1.25.0
 
 ### Changed
 
@@ -332,7 +1131,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * **search:** existence-gate search modal form action for remote-theme consumers ([#257](https://github.com/bamr87/zer0-mistakes/issues/257)) ([b915c4d](https://github.com/bamr87/zer0-mistakes/commit/b915c4dead5eff3d6a2986720ebacdcf2bed5e33))
 * **skins:** map dark + contrast skins to their background assets ([#245](https://github.com/bamr87/zer0-mistakes/issues/245)) ([fb8808e](https://github.com/bamr87/zer0-mistakes/commit/fb8808e5ec754785b8239b01bccfab99569b70fa)), closes [#240](https://github.com/bamr87/zer0-mistakes/issues/240)
 
-## [Unreleased]
+## Detailed notes — v1.24.0–v1.25.0
 
 ### Bug Fixes
 
@@ -423,7 +1222,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * remove Year of AI / org content-hub pivot, restore theme landing page ([#180](https://github.com/bamr87/zer0-mistakes/issues/180)) ([3960f65](https://github.com/bamr87/zer0-mistakes/commit/3960f65b1af4c750216deda0d032a309b0f93b78))
 
-## [Unreleased]
+## Detailed notes — v1.24.0
 
 ### Added
 - **Visual-evidence standard + reusable evidence kit.** UI/behavioural changes
@@ -686,7 +1485,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   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
@@ -833,7 +1632,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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
@@ -843,10 +1642,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   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
 
@@ -1274,7 +2073,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **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`.
@@ -2319,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