jekyll-theme-zer0 1.26.0 → 1.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af7de9769f05880ab652483a7ff6109e79d04ff6404c71163822ce4cecac3d23
-  data.tar.gz: 7c968f45cbba4655ad0eb5aa25a55e7b5f178957d65036d47236ba7809592733
+  metadata.gz: 8b72b3e6bf60fc9df7f31ecd56d157770fede085973db6d2153980c3004bc0fc
+  data.tar.gz: 369c0158b06d41d52c3f737d9a88a44e2cb9265653db55bf376e0651a502980b
 SHA512:
-  metadata.gz: 3ec2a5423346be22b17120fc586396501218877b70373eae7df03395b4b91211e8d03cf45d79ec71ad717344eae248b967dd5e810092cbf045f0d796ffad1c61
-  data.tar.gz: 55ec85fa55c7ca9c918413e16c86d3a275301a0282a989039face47fad9b9e3dc27f5fcda6ff7eb5e74faf0a557e8307c43a059e2e2bd1ebf8df011e46e82b9c
+  metadata.gz: 0d89cbf414b78be0b73fd22f8102dfacf8e38f10c561b2cc50fb4b492b8840d15e38f3b83243a589cd32f7fe7d72e4eb009a8dba44f09634e5e6611195971566
+  data.tar.gz: cbcbec935073100919c21c9f3f542124a291529a93212706b8c7e82773a4361d7b272cc60ec966f077213c6c7ae23d36a60ad129c08bfd33506d382172109a88

data/CHANGELOG.md

@@ -5,6 +5,410 @@ 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)
+
+
+### Features
+
+* **analytics:** wire posthog.html into head.html ([#317](https://github.com/bamr87/zer0-mistakes/issues/317)) ([7977fe1](https://github.com/bamr87/zer0-mistakes/commit/7977fe189dec3b62eb9779feac56ec27e513f2c3))
+* **article:** show_hero front-matter flag opts standard posts into the hero image ([#309](https://github.com/bamr87/zer0-mistakes/issues/309)) ([6344473](https://github.com/bamr87/zer0-mistakes/commit/6344473c14c613825ab7ac9083b87f17a2a1e858))
+* **i18n:** AI-generated multilingual support with language toggle ([#316](https://github.com/bamr87/zer0-mistakes/issues/316)) ([72b2ab6](https://github.com/bamr87/zer0-mistakes/commit/72b2ab6980742e26305a22e3aff535f465ade084))
+* **scripts:** Claude-orchestrated preview images — Claude analyzes & reviews, image models render ([#296](https://github.com/bamr87/zer0-mistakes/issues/296)) ([acac205](https://github.com/bamr87/zer0-mistakes/commit/acac2051ec79a81c04efb1af76fb4031e106a852))
+
+
+### Bug Fixes
+
+* **a11y:** keep a single &lt;main&gt; landmark per page ([#310](https://github.com/bamr87/zer0-mistakes/issues/310)) ([fae920e](https://github.com/bamr87/zer0-mistakes/commit/fae920eb5c60b5e792e9842c9b112bd5eb60e391)), closes [#299](https://github.com/bamr87/zer0-mistakes/issues/299)
+* **author:** build avatar path with relative_url, never protocol-relative ([#306](https://github.com/bamr87/zer0-mistakes/issues/306)) ([ac597d2](https://github.com/bamr87/zer0-mistakes/commit/ac597d2c029157bb47da5a336812f764a3946da4))
+* **ci:** secret scan matches added lines only, not context/removals/hunk headers ([#301](https://github.com/bamr87/zer0-mistakes/issues/301)) ([1b7175d](https://github.com/bamr87/zer0-mistakes/commit/1b7175ddece3d95aefc406f3b59df682db9fd0f2))
+* **includes:** gate Quick Links Dev row on is_production ([#308](https://github.com/bamr87/zer0-mistakes/issues/308)) ([03b6877](https://github.com/bamr87/zer0-mistakes/commit/03b687713b8552c6ceb6b2ab30ac8caea0d6632d))
+* **obsidian:** graph reads OBSIDIAN_CONFIG.wikiIndexUrl that js-cdn.html emits ([#305](https://github.com/bamr87/zer0-mistakes/issues/305)) ([2875912](https://github.com/bamr87/zer0-mistakes/commit/28759128b7b352a054e642d153e5e38e16aa1e48))
+* **sass:** stack left-side FABs to prevent obsidian/feedback overlap ([#289](https://github.com/bamr87/zer0-mistakes/issues/289)) ([6cc4596](https://github.com/bamr87/zer0-mistakes/commit/6cc4596dff28d164386a16a6637420f84b4571bf))
+* **test:** repoint ZER0-003 to test_install_legacy_flags.sh after retirement ([#292](https://github.com/bamr87/zer0-mistakes/issues/292)) ([fd7a2ce](https://github.com/bamr87/zer0-mistakes/commit/fd7a2ce256e32d2f630bd82732227b54ba13d3dd))
+* **theme:** apply relative_url to preview_path exactly once ([#307](https://github.com/bamr87/zer0-mistakes/issues/307)) ([012e577](https://github.com/bamr87/zer0-mistakes/commit/012e577fe3131e0be42f7d33a6f5161dc666cc81))
+
 ## [1.26.0](https://github.com/bamr87/zer0-mistakes/compare/v1.25.0...v1.26.0) (2026-07-07)
 
 
@@ -12,10 +416,159 @@ 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
 
-### Changed
+### Added
+
+- **Multilingual support via AI-generated translations** (ZER0-078) — the
+  theme now serves alternate-language versions of the site without storing
+  hand-written translations in source. English under `pages/**` +
+  `_data/ui-text.yml` `en` is the only human-maintained language; a
+  build-time utility ([`scripts/translate.rb`](scripts/translate.rb),
+  Claude Code OAuth with API-key fallback, stdlib-only Ruby) generates the
+  alternates and the
+  [`translate.yml`](.github/workflows/translate.yml) workflow commits them
+  via PR — one large `mode=full` dispatch job for the initial conversion,
+  plus bounded incremental runs whenever English content changes on `main`:
+  - Generated artifacts: `fr/**` page files (plain Jekyll pages with
+    explicit `/fr<en-url>` permalinks — GitHub Pages safe-mode friendly, no
+    plugin required), `_data/i18n/<lang>.yml` UI strings, and
+    `_data/i18n/manifest.yml` (en URL → translations map + SHA-based
+    incremental change detection with pruning of deleted sources).
+  - Markdown safety by construction: per-line segment translation with
+    `⟦N⟧` masking of code, Liquid, wiki-links and URLs, placeholder
+    set-equality validation with one retry, code fences never sent.
+  - Frontend: navbar **language toggle**
+    ([`language-toggle.html`](_includes/components/language-toggle.html))
+    with per-page availability states and `localStorage` preference,
+    `hreflang` alternates in `<head>`, per-page `<html lang>`, and a
+    machine-translation disclosure banner linking back to the original.
+  - Refactor: UI-string lookup centralized in
+    [`core/i18n.html`](_includes/core/i18n.html) and made per-page-language
+    aware (cached chrome includes take a `lang` parameter so each language
+    gets its own `include_cached` entry); the hand-maintained es/fr/de/ar
+    blocks in `_data/ui-text.yml` were **removed** in favor of the
+    generated pipeline.
+  - Offline test suite `test/test_i18n.sh` (stub provider, no network),
+    registered as the `i18n` suite in `test_runner.sh`, plus the
+    `language-toggle` Playwright smoke spec; docs in
+    [`docs/systems/multilingual-translation.md`](docs/systems/multilingual-translation.md).
+    (evidence:
+    [`test/visual/evidence/language-toggle/`](test/visual/evidence/language-toggle/README.md)
+    and
+    [`test/visual/evidence/language-toggle-fr/`](test/visual/evidence/language-toggle-fr/README.md)
+    — toggle at 6 widths + generated French page with 0px overflow, code
+    blocks byte-identical)
+
+- **`show_hero` front-matter flag** — a post of any `post_type` can now opt
+  its `preview:` image into the top-of-article hero with `show_hero: true`,
+  without being promoted to `featured`/`breaking` (layout width, sidebar,
+  typography, and the post-type badge keep their `post_type` defaults);
+  existing posts are unchanged by construction — the flag is falsy everywhere
+  it isn't set ([#303](https://github.com/bamr87/zer0-mistakes/issues/303)).
+  (evidence:
+  [`test/visual/evidence/show-hero/`](test/visual/evidence/show-hero/README.md)
+  — hero renders only on the opted-in demo post; whole-build before/after
+  diff: exactly 1 page differs)
+
+- **Claude-orchestrated preview-image engine** (ZER0-004) — the three
+  divergent implementations (1,404-line Bash engine, drifted Python
+  duplicate, dead Jekyll plugin) are consolidated into ONE Python engine,
+  [`scripts/lib/preview_generator.py`](scripts/lib/preview_generator.py).
+  Claude directs; an image model renders:
+  - **Analyze** (`prompt_engine: claude`, default) — Claude reads each
+    article and writes a subject-specific art-direction brief, replacing the
+    generic template prompt that produced unrepresentative banners.
+  - **Produce** — the configured renderer executes the brief: `openai`
+    (gpt-image-2 / DALL-E, default), `xai` (grok-2-image), `stability`,
+    **`gemini` (new)** — or `local`, upgraded from a `.txt` stub to a real
+    deterministic SVG/PNG banner (sanitized, rasterized via `rsvg-convert` →
+    `inkscape` → `magick` → the new Playwright helper
+    [`scripts/dev/rasterize-svg.js`](scripts/dev/rasterize-svg.js)).
+  - **Review** (`review_engine: claude`, default) — Claude inspects the
+    rendered image with vision against the article and style; when it
+    misrepresents the subject or contains text artifacts, Claude writes a
+    corrected prompt and the engine regenerates once.
+  - Claude credential chain: `CLAUDE_CODE_OAUTH_TOKEN` (`claude setup-token`)
+    → `ANTHROPIC_AUTH_TOKEN` → `ANTHROPIC_API_KEY` → a logged-in `claude` CLI
+    (zero-setup for Claude Code users); orchestration degrades gracefully to
+    template prompts without one.
+  - New unit suite [`test/test_preview_generator.py`](test/test_preview_generator.py)
+    (83 tests, zero network) wired into `test_core.sh`.
 
+### Fixed
+
+- **Obsidian graph loads its wiki index on project sites** — the full-graph
+  renderer (`assets/js/obsidian-graph.js`) now reads the baseurl-aware
+  `window.OBSIDIAN_CONFIG.wikiIndexUrl` that `js-cdn.html` emits (falling back
+  to the legacy `OBSIDIAN_WIKI_INDEX_URL` override, then the `<base>`-relative
+  path), instead of only the never-set legacy global — whose fallback dropped
+  the baseurl and 404'd the `wiki-index.json` fetch on GitHub Pages project
+  sites, leaving `/docs/obsidian/graph/` a "Failed to load graph data" alert
+  ([#294](https://github.com/bamr87/zer0-mistakes/issues/294)). (evidence:
+  [`test/visual/evidence/obsidian-graph-index/`](test/visual/evidence/obsidian-graph-index/README.md)
+  — wiki-index fetch 404 → 200, alert → rendered graph, on a baseurl'd build)
+
+- **Quick Links no longer ships a dead `localhost:4000` Dev row to production
+  visitors** — the env-switcher's Development URL row (rendered in the
+  site-wide Settings offcanvas on every page) is now wrapped in
+  {% raw %}`{% unless is_production %}`{% endraw %}, using the same `env-detect.html` flag the card
+  already keys its badge on; serving locally with `JEKYLL_ENV=production`
+  still counts as dev context, so the row stays available for Docker workflows
+  ([#298](https://github.com/bamr87/zer0-mistakes/issues/298)). (evidence:
+  [`test/visual/evidence/env-switcher-prod/`](test/visual/evidence/env-switcher-prod/README.md)
+  — production Settings-chrome `localhost:4000` occurrences 5 → 0, Dev row
+  intact in development)
+- **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 }}`
+  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
+  ([#297](https://github.com/bamr87/zer0-mistakes/issues/297)). (evidence:
+  [`test/visual/evidence/author-avatar-url/`](test/visual/evidence/author-avatar-url/README.md)
+  — 4 protocol-relative avatars → 0, all avatars loading, on a misconfigured
+  consumer build)
+
+- **Intro hero banner renders on project sites** — `content/intro.html` now
+  applies `relative_url` to the banner image exactly once (in the
+  `preview_path` assignment logic), instead of a second time at the point of
+  use, which doubled the baseurl segment on any site with a non-empty
+  `baseurl` (`url('/reponame/reponame/assets/…')` → 404 → gradient-only hero)
+  and mangled absolute preview URLs
+  ([#293](https://github.com/bamr87/zer0-mistakes/issues/293)). (evidence:
+  [`test/visual/evidence/intro-banner-baseurl/`](test/visual/evidence/intro-banner-baseurl/README.md)
+  — background fetch 404 → 200 on both preview branches of a baseurl'd build)
+
+- **Preview-image config keys `enabled`, `assets_prefix`, `auto_prefix` and
+  `collections` are now honored by the generator** (the Bash engine ignored
+  them), and front-matter `preview:` updates are scoped to the front-matter
+  block only — the previous file-wide `sed` could corrupt body lines starting
+  with `preview:`. External-URL previews are no longer silently regenerated,
+  and a configured model from the wrong vendor family falls back to the
+  provider default instead of a guaranteed API error.
+
+- **Left-side FAB overlap** — the Obsidian local-graph button and the
+  page-feedback "Improve this page" button were both positioned at
+  `bottom: 1rem; left: 1rem` and completely overlapped each other. The
+  Obsidian FAB is now at slot 2 (`bottom: offset + size + gap`), stacking
+  above the feedback FAB — the same pattern the TOC FAB uses above
+  back-to-top on the right side. The docs-sidebar restore-mode FAB was
+  also offset to slot 2 so it cannot overlap the feedback FAB on mobile.
+  Closes #288. (evidence:
+  [`test/visual/evidence/fab-stack/`](test/visual/evidence/fab-stack/README.md)
+  — feedback↔obsidian FAB overlap 3136px² → 0; regression test
+  [`test/visual/features/fab-stack.spec.js`](test/visual/features/fab-stack.spec.js)).
+
+### Changed
+
+- **Preview-image generation is now Claude-orchestrated by default**
+  (`prompt_engine: claude` + `review_engine: claude`; disable with
+  `--prompt-engine template --review none`). The renderer default stays
+  `openai`. `scripts/features/generate-preview-images` is now a thin wrapper
+  delegating to the Python engine (full CLI flag surface preserved;
+  `rake preview:*` and the VS Code tasks work unchanged).
 - **CI test tiering** — the PR-blocking Playwright gate is now the new
   `critical` project (118 `@critical`-tagged, user-facing tests: navigation,
   search, mobile survival, theming baseline, security) instead of the full
@@ -51,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
 
@@ -161,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
 
@@ -252,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