jekyll-theme-zer0 1.27.0 → 1.29.0

data/_data/backlog.yml

@@ -62,8 +62,8 @@
 
 meta:
   title: "zer0-mistakes Backlog"
-  updated: 2026-06-29
-  next_id: 34
+  updated: 2026-08-18
+  next_id: 46
 
 tasks:
   # --- Housekeeping (seeded so the loop has work on day one) ------------------
@@ -916,3 +916,357 @@ tasks:
     links: { issue: 302, pr: null, roadmap: null }
     created: 2026-07-12
     updated: 2026-07-16
+
+  - id: T-035
+    title: "Adopt --zer0-radius-* and display-size tokens across the remaining Sass partials"
+    status: open
+    priority: P2
+    area: feat
+    risk: low
+    effort: M
+    source: issue
+    route: theme-ui
+    summary: >-
+      The design-system alignment PR #389 (ZER0-081) introduced --zer0-radius-* and
+      --zer0-text-display-* tokens and adopted them in the partials the Claude
+      Design system names (callout, landing, ui-enhancements). Hardcoded radii
+      remain in _navbar.scss (~15 sites), notebooks.scss, code-copy.scss,
+      _docs-code-examples.scss, and others; hero .display-4 mobile overrides in
+      _ui-enhancements.scss (2rem and 1.75rem blocks — the two @media blocks
+      overlap, later wins) predate the fluid clamp tokens. Sweep them onto the
+      tokens value-preservingly where values match the scale, and reconcile the
+      duplicate hero override blocks; anything intentionally off-scale keeps a
+      literal plus a comment.
+    acceptance:
+      - "No border-radius literal in _sass/** that duplicates a --zer0-radius-* value (grep-clean or commented as intentional)."
+      - "Hero display sizing states one rule set; duplicate @media blocks reconciled."
+      - "scripts/design-system-check.rb still green; compiled CSS visually identical (evidence or skip-evidence rationale)."
+      - "regression test added"
+      - "before/after evidence committed"
+    links: { issue: null, pr: null, roadmap: null }
+    created: 2026-08-14
+    updated: 2026-08-14
+
+  # --- UI/UX fix list intake (hand-written review, 2026-08-18) ----------------
+
+  - id: T-036
+    title: "Remove hover transforms that cause pointer-edge flicker in the navbar"
+    status: open
+    priority: P1
+    area: feat
+    risk: standard
+    effort: S
+    source: user
+    route: theme-ui
+    summary: >-
+      .nav-link:hover, .nav-search-button:hover and .nav-settings-button:hover in
+      _sass/core/_navbar.scss apply transform: translateY(-1px) (icons scale 1.1,
+      chevron :hover::after translateY(2px)), so the element moves out from under
+      a pointer parked on its edge, hover exits, it returns — infinite flicker.
+      Delete every transform from :hover rules (keep background/color
+      transitions; a pressed cue may use :active translateY(1px) only) and audit
+      _sass/components/_ui-enhancements.scss and card hover styles for the same
+      pattern.
+    acceptance:
+      - "No transform in any :hover rule under _sass/ (grep for translateY/scale in hover context returns nothing)."
+      - "Pointer parked on the top edge of any nav item or utility button does not flicker."
+      - "regression test added"
+      - "before/after evidence committed"
+    links: { issue: null, pr: null, roadmap: null }
+    created: 2026-08-18
+    updated: 2026-08-18
+
+  - id: T-037
+    title: "Navbar width recovery: two clean label tiers, merged chevron, centered grid, no subtitle"
+    status: open
+    priority: P2
+    area: feat
+    risk: standard
+    effort: M
+    source: user
+    route: theme-ui
+    summary: >-
+      Top nav is cramped and truncates labels ("Quicksta…"). Keep per-item icons
+      at every tier but only two states — icon + full label (wide container) and
+      the existing icon-only tier (narrow) — removing the intermediate ellipsized
+      state (_includes/navigation/navbar.html + _sass/core/_navbar.scss container
+      queries). Merge each dropdown's separate 22-24px chevron button into the
+      parent link's padding box (position:absolute overlay, shared hover
+      background on the li, button kept for a11y). Use grid-template-columns:
+      1fr auto 1fr on .navbar-main so the menu stays optically centered. Retire
+      the navbar subtitle (_includes/core/branding.html — home hero only).
+      Clarify the three toggles: labeled "Menu" text button below lg, gear moves
+      into the unified drawer on mobile so only two toggles coexist.
+    acceptance:
+      - "At 1024px and 1280px with 5 nav items every label is fully visible or the whole row is icon-only — no ellipses anywhere."
+      - "Dropdown chevron shares the parent row's hover zone; no dead zone between link and chevron."
+      - "Navbar carries logo + title only; subtitle appears on the home hero."
+      - "regression test added"
+      - "before/after evidence committed"
+    links: { issue: null, pr: null, roadmap: null }
+    created: 2026-08-18
+    updated: 2026-08-18
+
+  - id: T-038
+    title: "Language switcher: icon-only trigger and a compact, positive menu"
+    status: open
+    priority: P2
+    area: feat
+    risk: standard
+    effort: S
+    source: user
+    route: theme-ui
+    summary: >-
+      _includes/components/language-toggle.html: drop the EN text span and the
+      Bootstrap caret (38-40px square icon button; title + aria-label carry the
+      name). In the menu, mark the current language with a check icon + tint
+      (not .active primary fill); keep untranslated languages clickable
+      (navigate to source page, set zer0-lang); mark machine translations with a
+      small "auto" chip; replace per-row "(Not yet translated)" with one
+      footnote line under a divider; menu width <= 220px.
+    acceptance:
+      - "Menu shows no disabled rows; widest row <= 220px; current language visually distinct without primary fill."
+      - "Trigger is icon-only at all widths with an accessible name."
+      - "regression test added"
+      - "before/after evidence committed"
+    links: { issue: null, pr: null, roadmap: null }
+    created: 2026-08-18
+    updated: 2026-08-18
+
+  - id: T-039
+    title: "Eliminate page-transition layout shift (fixed-nav offset, scrollbar gutter, server-rendered slots)"
+    status: open
+    priority: P1
+    area: perf
+    risk: standard
+    effort: M
+    source: user
+    route: theme-ui
+    summary: >-
+      Navigation between pages visibly bounces. Define --zer0-nav-height in
+      :root, derive body padding-top and every sticky offset (admin.html's
+      top: 5rem, TOC, sidebars) and scroll-margin-top from it (no JS
+      measurement). Add html { scrollbar-gutter: stable }. Render banner/nanobar
+      slots server-side with fixed height (nanobar 3px strip always present;
+      setup banner via Liquid when site_needs_setup, not JS insert). Verify
+      explicit width/height on content images and font-display: swap + preload
+      for bootstrap-icons woff2. Progressive enhancement: @view-transition
+      { navigation: auto } with a 120ms root fade.
+    acceptance:
+      - "Lighthouse CLS < 0.02 on landing, docs, and admin pages."
+      - "No visible reflow when navigating between short and long pages (scrollbar gutter stable)."
+      - "All sticky offsets derive from --zer0-nav-height (no hardcoded top: 5rem)."
+      - "regression test added"
+      - "before/after evidence committed"
+    links: { issue: null, pr: null, roadmap: null }
+    created: 2026-08-18
+    updated: 2026-08-18
+
+  - id: T-040
+    title: "Setup wizard: live YAML preview, vertical stepper, draft persistence, stable panel height, inline validation"
+    status: open
+    priority: P2
+    area: feat
+    risk: standard
+    effort: M
+    source: user
+    route: theme-ui
+    summary: >-
+      _includes/setup/wizard.html + assets/js/setup-wizard.js: replace the
+      step-5-only <pre> with a persistent sticky preview panel regenerated on
+      every input (copy/download always enabled); replace nav-pills tabs with a
+      left vertical stepper showing done/active/upcoming state (steps unlock on
+      validation, Back always allowed, remove the "N% complete" math); persist
+      the draft to localStorage under zer0-setup-draft (debounced 300ms, restore
+      on load, "Draft saved" chip, clear on download); give the panel container
+      a min-height equal to the tallest step so Back/Next never move vertically;
+      validate email/URL on blur with is-invalid + message and list unfilled
+      recommended fields as warnings on the Review step.
+    acceptance:
+      - "YAML preview visible and live at lg+; Back/Next buttons never shift vertically between steps."
+      - "Reload mid-wizard restores the draft; invalid email/URL flagged on blur."
+      - "regression test added"
+      - "before/after evidence committed"
+    links: { issue: null, pr: null, roadmap: null }
+    created: 2026-08-18
+    updated: 2026-08-18
+
+  - id: T-041
+    title: "Admin layout: actions reachable on mobile, grouped sidebar, shared sticky offset, single heading"
+    status: open
+    priority: P2
+    area: feat
+    risk: standard
+    effort: M
+    source: user
+    route: theme-ui
+    summary: >-
+      _layouts/admin.html + _includes/navigation/admin-nav.html: the
+      admin_actions wrapper is d-none d-md-flex so actions are unreachable on
+      phones — render the first action as a visible button at all widths with
+      the rest in a "..." dropdown. Group sidebar items under small-caps headers
+      (Configure / System / Links) via a group: key in
+      _data/navigation/admin.yml; counts as plain numerals, statuses as colored
+      dot + word; active item = tint + semibold, not solid primary fill. Replace
+      style="top: 5rem" with top: calc(var(--zer0-nav-height) + 1rem) (depends
+      on T-039). Keep the "Administration" heading in the offcanvas header only.
+    acceptance:
+      - "Every admin action reachable at 375px width."
+      - "Sidebar grouped; no solid-primary active fill; sticky offset uses the shared variable."
+      - "regression test added"
+      - "before/after evidence committed"
+    links: { issue: null, pr: null, roadmap: null }
+    created: 2026-08-18
+    updated: 2026-08-18
+    depends_on: [T-039]
+
+  - id: T-042
+    title: "Skin contrast sweep: AA link params, tertiary meta text, per-skin badge/button audit"
+    status: open
+    priority: P1
+    area: a11y
+    risk: standard
+    effort: M
+    source: user
+    route: a11y
+    summary: >-
+      _sass/theme/_skins.scss: several skins omit the zer0-skin-palette mixin's
+      $link-light/$link-dark params and fall back to $brand/$accent, which fail
+      4.5:1 (yellow/orange/cyan brands on white, saturated brands on #212529) —
+      pass explicit AA-checked values for every skin with a comment table of
+      measured ratios. text-body-tertiary on 11-12px meta text (admin header
+      "Updated…", wizard hints) falls below AA — use --bs-secondary-color at
+      small sizes, tertiary only >= 16px. Audit .btn-primary text per skin
+      (auto-switch to dark text when brand luminance > 0.55 via color-contrast()
+      or a precomputed token).
+    acceptance:
+      - "axe/Lighthouse contrast passes on light + dark for all skins."
+      - "Every skin passes explicit link colors; measured-ratio table committed as comments."
+      - "regression test added"
+      - "before/after evidence committed"
+    links: { issue: null, pr: null, roadmap: null }
+    created: 2026-08-18
+    updated: 2026-08-18
+
+  - id: T-043
+    title: "Mermaid diagrams: render-in-place (no CLS), token-driven theming, figure shell, flash-free theme switch"
+    status: open
+    priority: P2
+    area: feat
+    risk: standard
+    effort: L
+    source: user
+    route: theme-ui
+    summary: >-
+      _includes/components/mermaid.html: the hidden pre > code is replaced by a
+      min-height:100px div that grows to 300-500px on render, shifting the page —
+      render in place with the placeholder inheriting the code block's height
+      and animate the swap. Delete the ~20 !important SVG overrides that fight
+      JS themeVariables (forced white text breaks colored nodes; light mode uses
+      #007bff vs site primary #0d6efd; skins don't affect diagrams) — build
+      themeVariables at init from live tokens (getComputedStyle on --bs-primary
+      / --bs-body-bg / --bs-border-color / --bs-body-color), re-run on
+      data-bs-theme AND data-theme-skin change. Wrap each diagram in a
+      figure.mermaid-figure with type chip, optional title, copy-source /
+      download-SVG / fullscreen toolbar (reuse the code-copy button pattern) and
+      figcaption. On theme switch render the new SVG off-DOM and cross-fade
+      120ms (instant under prefers-reduced-motion). Builds on T-039.
+    acceptance:
+      - "CLS contribution from a page with 3 diagrams < 0.01."
+      - "No !important SVG overrides remain; diagrams follow theme AND skin tokens live."
+      - "Theme switch shows no blank flash."
+      - "regression test added"
+      - "before/after evidence committed"
+    links: { issue: null, pr: null, roadmap: null }
+    created: 2026-08-18
+    updated: 2026-08-18
+    depends_on: [T-039]
+
+  - id: T-044
+    title: "Playwright suite aborts: duplicate openDialog declaration in accessibility.spec.js"
+    status: done
+    priority: P1
+    area: tests
+    risk: low
+    effort: S
+    source: issue
+    route: test-author
+    summary: >-
+      test/visual/core/accessibility.spec.js declares `async function
+      openDialog` twice — at line 172 (page, selector) and again at line 425
+      (page, selector, kind), the latter added by 98fd6f9 (#387) without
+      removing the former. Two function declarations of the same name in one
+      module scope is a SyntaxError, so Playwright fails to parse the file and
+      the WHOLE run aborts before any test executes: "Identifier 'openDialog'
+      has already been declared. (425:15)". This takes down the critical and
+      smoke tiers together, on every branch, and has been red on main since
+      2026-08-14. Discovered during #414, whose own new spec
+      (test/visual/features/recipes.spec.js) therefore cannot run in CI. The
+      three-argument version is a strict superset — with `kind` undefined it
+      resolves to Ctor='Modal' and 'shown.bs.modal', exactly what the
+      two-argument one does — so deleting the earlier declaration (lines
+      165-184, comment included) is behaviour-preserving.
+    acceptance:
+      - "test/visual/core/accessibility.spec.js parses; `npx playwright test --project=critical` runs to completion."
+      - "Only one openDialog declaration remains, and its callers all still pass."
+      - "No behavioural change to the modal/offcanvas a11y tests."
+    links: { issue: 416, pr: null, roadmap: null }
+    created: 2026-08-23
+    updated: 2026-08-23
+
+  - id: T-045
+    title: "Homepage snapshot baselines were regenerated without the 1967px drift being diagnosed"
+    status: open
+    priority: P2
+    area: tests
+    risk: low
+    effort: S
+    source: issue
+    route: test-author
+    summary: >-
+      The Visual Snapshots tier fails all 9 `Theme skins > homepage visual
+      snapshot` cases with the SAME diff — 1967 pixels (ratio 0.01) — against
+      test/visual/snapshots/features/appearance-snapshot.spec.js-snapshots/homepage-*-snapshots-linux.png,
+      well over the maxDiffPixels 150 budget. The count being identical across
+      air/aqua/contrast/dark/dirt/neon/mint/plum/sunrise points at one shared,
+      skin-independent region rather than a palette regression. Verified during
+      #414 that it is NOT that PR's doing: building origin/main and the PR
+      branch and screenshotting the homepage at the spec's own 1280x720
+      viewport produced BYTE-IDENTICAL PNGs (same md5), so the branch renders
+      the homepage exactly as main does and the drift is between the committed
+      baselines and what main itself now renders. Note while investigating:
+      _includes/components/theme-info.html renders a minute-resolution build
+      stamp, site.time | date "%b %d, %H:%M" — it currently sits in a collapsed
+      offcanvas (measured 0x0, not in the viewport) so it is not the cause
+      today, but it is a live non-determinism hazard the moment that panel is
+      shown by default, and worth masking regardless. UPDATE 2026-08-23: #413
+      regenerated all 9 baselines when it merged, so the check is green again —
+      resolved by re-blessing rather than by diagnosis, which is what the first
+      acceptance criterion was meant to prevent. Diffing the old vs new CI
+      baselines (homepage-air, 2596f866 vs e488c4c) puts the whole 5016px delta
+      in two bands: y21-41 (a wide navbar strip, 4688px) and y626 (328px).
+      page-views does render on the homepage so part of that is legitimately
+      #413, but a navbar strip is not where a view-count badge belongs.
+      Separating the two needs the diff artifact from a pre-#413 failing run,
+      which has rolled off. What remains is confirming the y21-41 band is
+      accounted for. UPDATE 2026-08-25: the y21-41 band is the navbar
+      reflowing, and the reason it RECURS is structural — a path-filter gap.
+      ci.yml's `styling` filter (which gates the snapshots job) lists only code
+      paths; `_data/**` appears solely under `content`, which gates no visual
+      job. So #419's nav item changed the chrome of every page with Visual
+      Snapshots SKIPPED on both the PR and the main push, and the drift
+      surfaced on #420, an unrelated PR. The y626 band is now UNRECOVERABLE:
+      both artifact uploads use 14-day retention (ci.yml, nightly-extended.yml)
+      and every pre-#413 failing run is past that window. Recording that rather
+      than leaving it open — no evidence survives to diagnose it from.
+    acceptance:
+      - "_data/** (or at minimum _data/navigation/**) is covered by the `styling` filter in ci.yml, so a nav/chrome data change runs Visual Snapshots instead of skipping it."
+      - "A CI guard pins that coverage, so the gap cannot silently reopen (lint-workflows.yml)."
+      - "A PR touching only _data/navigation/main.yml runs Visual Snapshots — demonstrated on the checks list, not asserted."
+      - "Visual Snapshots passes on main and on a fresh branch with no source changes."
+      - "Any genuinely time- or build-varying content inside the snapshot region is masked or stubbed, so the tier cannot drift again."
+      - "No baseline PNG is regenerated as part of this work; any diff is diagnosed in the PR before it is blessed."
+      - "The y626 band is explained, or recorded as unrecoverable with the reason. (Recorded: artifacts past 14-day retention.)"
+    links: { issue: 417, pr: null, roadmap: null }
+    created: 2026-08-23
+    updated: 2026-08-25

data/_data/consumers.yml

@@ -0,0 +1,252 @@
+# ==============================================================================
+# _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 — that part is the real exposure. Recommend pinning and
+      joining the fan-out. NOTE: this entry previously claimed it "shadows ~55
+      theme files … ~75 lines of !important CSS working around #338", which
+      audit-consumer does not support. Only 2 files actually shadow a theme
+      file (_includes/content/giscus.html, assets/js/particles-source.js); the
+      other ~52 are it-journey's own quest-system layouts and includes that
+      share no filename with anything in this theme, so they carry no drift
+      risk at all. The !important CSS is real but is 31 lines in
+      assets/css/user-overrides.css — this theme's own documented extension
+      hook, enabled by `user_overrides: true`, not a shadow — and no fix
+      numbered #338 could be substantiated in that repo. Keep this field
+      derived from audit-consumer output, not hand-maintained estimates.
+    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"
+
+  # ---------------------------------------------------------------------------
+  # The four entries below were missing entirely until the 2026-08 fleet audit.
+  # Unregistered consumers are invisible to propagate.rb in BOTH directions: no
+  # release dispatch reaches them, and they never appear in the weekly drift
+  # report — so their pins can rot indefinitely with nothing to notice. That is
+  # exactly what happened to zer0-pages, which sat three minors behind on a gem
+  # constraint that already permitted the current release.
+  # ---------------------------------------------------------------------------
+  - repo: bamr87/zer0-pages
+    mode: gem
+    site: https://bamr87.github.io/zer0-pages/
+    dispatch: true
+    note: >-
+      Dual Obsidian-vault / Jekyll repo. Two things make it unlike every other
+      consumer. (1) It sets `source: pages`, so the whole themable tree lives
+      under pages/ — audit-consumer follows `source:` for this reason; auditing
+      the repo root reports a falsely clean result. (2) It is gem mode with no
+      remote_theme anywhere, so NOTHING is picked up automatically: the
+      scheduled bump is its only path to a new version.
+    risk: >-
+      Gemfile.lock resolved 1.25.0 while the Gemfile constraint (~> 1.25)
+      already permitted 1.28.0 — stale purely because nothing was nudging it.
+      Keeps two deliberate include forks, declared in its .theme-overrides.yml.
+    pins:
+      - file: Gemfile
+        kind: gem_constraint
+        note: 'line 11 — `gem "jekyll-theme-zer0", "~> 1.25"`'
+      - file: Gemfile.lock
+        kind: resolved_lockfile
+        note: "line 86 — re-lock with `bundle lock --update jekyll-theme-zer0`"
+      - file: _config.yml
+        kind: theme_name
+        note: "line 29 — `theme: jekyll-theme-zer0`; activates the gem, no version of its own"
+
+  # ---------------------------------------------------------------------------
+  - repo: bamr87/irony-works
+    mode: remote_theme_floating
+    site: https://bamr87.github.io/irony-works/
+    dispatch: false
+    note: >-
+      Vault + Node engine; engine/scripts/transplant.mjs converts vault/ into
+      the _entries/ collection before Jekyll runs. Has NO Gemfile at all — it
+      builds via actions/jekyll-build-pages (the github-pages image), so it can
+      only ever be tracked as remote_theme_floating; there is no gem constraint
+      surface for a bump to rewrite.
+    risk: >-
+      Unpinned, and with no local preview path a contributor cannot see a theme
+      break before pushing. Keeps three deliberate overrides, declared in its
+      .theme-overrides.yml.
+    pins:
+      - file: _config.yml
+        kind: remote_theme
+        note: line 4, no tag — floats main
+
+  # ---------------------------------------------------------------------------
+  - repo: bamr87/wargames
+    mode: remote_theme_floating
+    site: https://bamr87.github.io/wargames/
+    dispatch: false
+    note: >-
+      Content-only vendored mirror of the OverTheWire challenges. Zero local
+      theme files — one of the cleanest consumers in the fleet. Its _config.yml
+      uses column-aligned YAML (`remote_theme             : "..."`), the style
+      that used to defeat audit-consumer's mode detection.
+    risk: >-
+      Unpinned, and its only build runs on push to main (jekyll-gh-pages.yml),
+      so a break ships before anyone sees it.
+    pins:
+      - file: _config.yml
+        kind: remote_theme
+        note: line 44, no tag — floats main
+
+  # ---------------------------------------------------------------------------
+  - repo: bamr87/zer0-pages-remote
+    mode: remote_theme_floating
+    site: https://bamr87.github.io/zer0-pages-remote/
+    dispatch: false
+    note: >-
+      The minimal reference consumer: _config.yml + Gemfile + index.md, no
+      local theme files and no _data at all, still showing the onboarding
+      wizard by design. Useful as the canary for what a stock remote_theme
+      consumer gets with zero customisation — if the theme breaks a bare site,
+      it breaks here first.
+    private: true
+    risk: >-
+      Unpinned. Low stakes (a demo, not a content site), but it has already
+      caught one real integration break: PR #8 fixed a Liquid `include_cached`
+      failure caused by a Gemfile plugin missing from the safe-mode whitelist.
+      This repo is PRIVATE, so an unauthenticated `propagate.rb` run reports it
+      "unreachable" rather than reading its pin — drift reporting needs a token
+      here even though it is read-only. CI already supplies one; a bare local
+      run will not.
+    pins:
+      - file: _config.yml
+        kind: remote_theme
+        note: line 12, no tag — floats main