jekyll-theme-zer0 1.27.0 → 1.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3cb4259aa073fce4885f3d87ae9e4d7227b6580eba6599c270b0a98660ba52a8
-  data.tar.gz: 1606cb3f5fe102133fccf84ba7e7f11d3338695b41c1f546f15a4c775b956834
+  metadata.gz: 8b72b3e6bf60fc9df7f31ecd56d157770fede085973db6d2153980c3004bc0fc
+  data.tar.gz: 369c0158b06d41d52c3f737d9a88a44e2cb9265653db55bf376e0651a502980b
 SHA512:
-  metadata.gz: 20b1f33db10f4dde3b0ee980cd481405fc166c765f3ba9c2d740a448aeed77f8aa08f017570d33c8329330009499b4629243e6ea35da3fd635ee87025eae541d
-  data.tar.gz: e7a0a830ea658d6a798ac53001535e849853f177be6e295524289d1e8a41ccb734964ee7d9ce7e85c6811e9409c27c6e922a0c631a26ea63c971a83c4769cfd3
+  metadata.gz: 0d89cbf414b78be0b73fd22f8102dfacf8e38f10c561b2cc50fb4b492b8840d15e38f3b83243a589cd32f7fe7d72e4eb009a8dba44f09634e5e6611195971566
+  data.tar.gz: cbcbec935073100919c21c9f3f542124a291529a93212706b8c7e82773a4361d7b272cc60ec966f077213c6c7ae23d36a60ad129c08bfd33506d382172109a88

data/CHANGELOG.md

@@ -5,6 +5,388 @@ 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.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]
+
+### Added
+
+- **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 `{{GITHUB_REPO}}` to the *site's* repo; it now
+  uses a dedicated `{{THEME_REMOTE}}` 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
+  renderer, so the generated `jekyll-gh-pages.yml` (and docker-prod/azure-swa
+  artifacts) no longer contain literal `{{…}}` 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 +416,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
 
@@ -222,7 +604,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 +714,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 +805,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

data/_data/consumers.yml

@@ -0,0 +1,147 @@
+# ==============================================================================
+# _data/consumers.yml — downstream consumers of this theme
+# ==============================================================================
+#
+# The registry that makes theme releases propagate instead of sitting unnoticed.
+# Every site that renders with zer0-mistakes is listed here together with HOW it
+# consumes the theme and WHICH files hold its version pin.
+#
+# Read by:
+#   - scripts/bin/propagate         report pin drift; dispatch release events
+#   - .github/workflows/propagate-theme.yml   release fan-out
+#
+# Why this exists: nothing connected a release to the sites built on it. When
+# 1.27.0 shipped, all five consumers were still on v1.26.0 (or floating on main)
+# and none of them knew. Bumps were a manual, five-repo chore that nobody
+# remembered, so pins drifted until a site broke.
+#
+# ------------------------------------------------------------------------------
+# Consumption modes
+# ------------------------------------------------------------------------------
+#   remote_theme_pinned    `remote_theme: bamr87/zer0-mistakes@vX.Y.Z` — GitHub
+#                          Pages fetches the tagged theme at build time. Gets a
+#                          bump PR on release.
+#   remote_theme_floating  `remote_theme: bamr87/zer0-mistakes` with no tag —
+#                          tracks main, so every push to this repo reaches
+#                          production immediately. Nothing to bump; what these
+#                          need is a canary, not a PR. See `risk` below.
+#   gem                    `gem "jekyll-theme-zer0", "~> X.Y.Z"` — the theme is
+#                          resolved from RubyGems, not GitHub. Bumping means
+#                          editing a Gemfile and re-locking. This is the mode the
+#                          scheduled updater matters most for: no remote_theme
+#                          means no automatic pickup of anything, ever.
+#   path                   `gem "jekyll-theme-zer0", path: ...` — a local
+#                          checkout for development. Never version-pinned and
+#                          never bumped; listed so audits don't flag it.
+#
+# ------------------------------------------------------------------------------
+# Pin kinds (scripts/bin/propagate knows how to read/rewrite each)
+# ------------------------------------------------------------------------------
+#   remote_theme        `remote_theme: "bamr87/zer0-mistakes@vX.Y.Z"` in a config
+#   hub_registry        `theme_repo: bamr87/zer0-mistakes@vX.Y.Z` in _data/hub.yml
+#   gem_constraint      `gem 'jekyll-theme-zer0', '~> X.Y.Z'` in a Gemfile
+#   theme_name          `theme: "jekyll-theme-zer0"` — names the gem, carries no
+#                       version; tracked so a bump doesn't miss the config that
+#                       activates it
+#   path_gem            local path gem, unversioned (development only)
+# ==============================================================================
+
+version: 1
+
+defaults:
+  branch: main
+  # repository_dispatch event type consumers listen for. Their side of the
+  # contract lives in templates/consumer/theme-bump.yml.
+  dispatch_event: theme-release
+
+consumers:
+  # ---------------------------------------------------------------------------
+  - repo: bamr87/it-journey
+    mode: remote_theme_floating
+    site: https://it-journey.dev
+    dispatch: false
+    risk: >-
+      Unpinned. Every push to this theme's main reaches production with no gate
+      and no rollback. Shadows ~55 theme files (5 layouts, 34 includes, 8 JS, 6
+      CSS, 2 plugins) — the largest override surface in the fleet, including
+      ~75 lines of !important CSS working around the stacking bug fixed in #338.
+      Recommend pinning and joining the fan-out.
+    pins:
+      - file: _config.yml
+        kind: remote_theme
+        note: line 36, no tag — floats main
+
+  # ---------------------------------------------------------------------------
+  - repo: bamr87/lifehacker.dev
+    mode: remote_theme_floating
+    site: https://lifehacker.dev
+    dispatch: false
+    risk: >-
+      Unpinned, same exposure as it-journey. Small override surface (2 includes).
+      Recommend pinning and joining the fan-out.
+    pins:
+      - file: _config.yml
+        kind: remote_theme
+        note: line 40, no tag — floats main
+
+  # ---------------------------------------------------------------------------
+  - repo: bamr87/bashconsultants
+    mode: gem
+    site: https://bashconsultants.com
+    dispatch: true
+    note: >-
+      Three stacks, three theme surfaces: GitHub Pages uses the pinned
+      remote_theme, Azure Static Web Apps resolves the published gem via
+      Gemfile.azure + _config.azure.yml, and local dev mounts a path gem. A bump
+      must move the remote_theme tag and the gem constraint together or the two
+      production stacks render different theme versions.
+    pins:
+      - file: _config.yml
+        kind: remote_theme
+        note: line 31
+      - file: Gemfile.azure
+        kind: gem_constraint
+        note: line 9 — must match the remote_theme tag
+      - file: _config.azure.yml
+        kind: theme_name
+        note: line 3 — activates the gem; no version of its own
+      - file: Gemfile
+        kind: path_gem
+        note: line 40 — dev checkout via ZER0_MISTAKES_PATH; never bumped
+
+  # ---------------------------------------------------------------------------
+  - repo: year-of-ai/year-of-ai.github.io
+    mode: remote_theme_pinned
+    site: https://year-of-ai.github.io
+    dispatch: true
+    fans_out_to_members: true
+    note: >-
+      An org hub, not just a site. Its _data/hub.yml theme_repo is the value
+      stamped into every member repo's _config.yml by scripts/provision-org-sites.rb,
+      so one bump here re-rolls the whole org (12 sites). The hub's own
+      _config.yml and hub.yml must move together — they are read by different
+      code paths and drift silently otherwise.
+    pins:
+      - file: _config.yml
+        kind: remote_theme
+        note: line 40
+      - file: _data/hub.yml
+        kind: hub_registry
+        note: "line 42 (pages.theme_repo) — re-roll members after bumping"
+
+  # ---------------------------------------------------------------------------
+  - repo: ai-world-view/ai-world-view.github.io
+    mode: remote_theme_pinned
+    site: https://ai-world-view.github.io
+    dispatch: true
+    fans_out_to_members: true
+    note: >-
+      Same two-file hub shape as year-of-ai; members join by auto_discover, so
+      the member count grows without this file changing.
+    pins:
+      - file: _config.yml
+        kind: remote_theme
+        note: line 35
+      - file: _data/hub.yml
+        kind: hub_registry
+        note: "line 39 (pages.theme_repo) — re-roll members after bumping"