jekyll-theme-zer0 1.28.0 → 1.30.0

data/_data/README.md

@@ -7,6 +7,8 @@ This directory contains YAML data files that power the Zer0-Mistakes Jekyll them
 | File | Purpose | Auto-Generated |
 |------|---------|----------------|
 | `navigation/` | Site navigation menus | No |
+| `ai.yml` | The one place the AI model is configured (read by the hub's `bamr87/bamr87/.github/actions/claude-run@main` runner, consumed by reference) | No |
+| `ai_pricing.yml` | API list prices used to *estimate* AI spend for calls that report tokens but no cost (part of the shared `ai-runner` kit) | No |
 | `authors.yml` | Author profile information | No |
 | `content_statistics.yml` | Site content analytics | **Yes** |
 | `roadmap.yml` | Single source of truth for the project roadmap (drives the README mermaid diagram and the `/roadmap/` Jekyll page) | No |

data/_data/ai.yml

@@ -1,9 +1,11 @@
 # =============================================================================
 # _data/ai.yml — one place the AI model is configured for zer0-mistakes agents
 # -----------------------------------------------------------------------------
-# Read by .github/actions/claude-run (the issue-autopilot's AI step). Change the
-# model here and every autopilot agent call uses it. Auth is NOT here — it comes
-# from the CLAUDE_CODE_OAUTH_TOKEN (preferred) or ANTHROPIC_API_KEY secret.
+# Read by the fleet's ai-runner kit — bamr87/bamr87/.github/actions/claude-run
+# (consumed by reference; the issue-autopilot's AI step). Change the model
+# here and every agent call uses it; AI_MODEL (or the action's `model` input)
+# overrides it for one run. Auth is NOT here — it comes from the
+# CLAUDE_CODE_OAUTH_TOKEN (preferred) or ANTHROPIC_API_KEY secret.
 # =============================================================================
 provider: anthropic
 model: claude-opus-4-8

data/_data/ai_pricing.yml

@@ -0,0 +1,36 @@
+# =============================================================================
+# ai_pricing.yml — API list prices used to ESTIMATE AI spend (per million tokens)
+# -----------------------------------------------------------------------------
+# The telemetry layer (scripts/ai/usage.rb) prefers the cost the Claude Code CLI
+# itself reports (`total_cost_usd`) — that number is authoritative and this file
+# is never consulted for it. This table exists for the paths that report tokens
+# but no dollars: the raw Claude API fallback (scripts/ai/api_call.rb) and any
+# execution log that predates cost reporting. Those records get cost_source:
+# "estimated", computed as
+#
+#   input×in + output×out + cache_read×(0.1×in)
+#     + cache_write_5m×(1.25×in) + cache_write_1h×(2×in)
+#
+# which reproduces the CLI's own arithmetic to the cent (validated 2026-07-14
+# against a live run). Prices are USD per MTok at standard API list rates —
+# subscription (OAuth) runs have no marginal dollar cost, so every published
+# figure is labeled "API-equivalent". Source: platform.claude.com/docs/en/pricing
+# (cached 2026-07-14). Update this file when Anthropic changes list prices;
+# estimates are marked as such everywhere they surface.
+# =============================================================================
+multipliers:
+  cache_read: 0.1        # × input price
+  cache_write_5m: 1.25   # × input price (5-minute TTL — the CLI default)
+  cache_write_1h: 2.0    # × input price (1-hour TTL)
+
+# Matched by longest model-id prefix, so dated snapshots (claude-haiku-4-5-20251001)
+# resolve to their family row. `default` catches unknown models (opus-tier, so an
+# unknown model over- rather than under-estimates).
+models:
+  claude-opus-4-8:   { input: 5.00,  output: 25.00 }
+  claude-opus-4-7:   { input: 5.00,  output: 25.00 }
+  claude-opus-4-6:   { input: 5.00,  output: 25.00 }
+  claude-sonnet-5:   { input: 3.00,  output: 15.00 }
+  claude-sonnet-4-6: { input: 3.00,  output: 15.00 }
+  claude-haiku-4-5:  { input: 1.00,  output: 5.00 }
+  default:           { input: 5.00,  output: 25.00 }

data/_data/backlog.yml

@@ -62,8 +62,8 @@
 
 meta:
   title: "zer0-mistakes Backlog"
-  updated: 2026-06-29
-  next_id: 34
+  updated: 2026-09-05
+  next_id: 52
 
 tasks:
   # --- Housekeeping (seeded so the loop has work on day one) ------------------
@@ -916,3 +916,508 @@ 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: done
+    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:
+      # Scoped to the navbar per the issue's Option A. Criterion 1 was
+      # originally "no transform in any :hover rule under _sass/" — that is 42
+      # rules across ~15 files (card lifts, book tilts, recipe hovers) and a
+      # visual redesign of a published theme, not this defect. It also flagged
+      # `transform: none`, which is the CORRECTIVE pattern this repo already
+      # uses in _post-navigation.scss and the prefers-reduced-motion blocks.
+      # A theme-wide motion policy belongs in its own task.
+      # Stated as the COMPUTED value, not "no matching rule": these controls
+      # are `.btn`s and _ui-enhancements.scss's theme-wide
+      # `.btn:hover { translateY(-2px) }` still matches them and always will.
+      # It is overridden by `transform: none`, not deleted, so a rule-existence
+      # check would be permanently red. That inherited lift is why deleting the
+      # navbar's own translateY was not sufficient on its own.
+      - "getComputedStyle(control).transform is `none` while hovered, for every navbar control."
+      # Direction corrected: translateY(-1px) moves the element UP, so the row
+      # it stops covering is the BOTTOM one. A test parked on the top edge
+      # passes without exercising the bug.
+      - "Pointer parked on the bottom edge of any nav item or utility button does not flicker."
+      # Note: `#bdNavbar .nav-link:hover`, named in the summary as the primary
+      # cause, was dead code — its lift sits inside a container query that never
+      # matches at desktop widths (measured 1040/1140/1200/1280px on the built
+      # site, `none` at every one, on main too). The observable flicker was on
+      # the utility buttons and the FABs.
+      - "regression test added"
+      - "before/after evidence committed"
+    links: { issue: 404, pr: null, roadmap: null }
+    created: 2026-08-18
+    updated: 2026-09-03
+
+  - 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: done
+    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: 406, pr: 431, roadmap: null }
+    created: 2026-08-18
+    updated: 2026-09-01
+  - 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: done
+    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: 408, pr: 432, roadmap: null }
+    created: 2026-08-18
+    updated: 2026-09-01
+  - 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: done
+    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: 425, roadmap: null }
+    created: 2026-08-23
+    updated: 2026-09-01
+
+  - id: T-046
+    title: "Retire the now-dead gotoBeforeScrollSpy fixture and cover the mobile offcanvas TOC spy"
+    status: open
+    priority: P3
+    area: tests
+    risk: low
+    effort: S
+    source: issue
+    route: test-author
+    summary: >-
+      Discovered while fixing the TOC scroll spy: test/visual/fixtures.js
+      exports gotoBeforeScrollSpy(), which strips data-bs-spy/data-bs-target
+      from <body> before Bootstrap auto-initializes so its native ScrollSpy
+      cannot clear server-rendered .active classes off admin sidebar links.
+      That attribute no longer exists — _layouts/root.html dropped it (and
+      _layouts/default.html dropped the second copy on .bd-main) so the theme's
+      own scroll-spy.js is the single owner of .active on TOC links — which
+      makes the fixture a no-op that still reads as load-bearing. Replace its
+      call sites in test/visual/features/admin.spec.js with the plain
+      waitForJekyll/gotoOrSkip helpers and delete it, keeping the admin
+      active-link assertions that motivated it. While there, add the coverage
+      test/visual/features/scroll-spy.spec.js deliberately left out: the mobile
+      offcanvas TOC, where .offcanvas-body rather than .bd-toc is the scroll
+      container the spy keeps the active link visible in.
+    acceptance:
+      - "gotoBeforeScrollSpy is removed from test/visual/fixtures.js and from its call sites; no spec references it."
+      - "The admin specs that used it still pass, asserting the same server-rendered active nav links."
+      - "A spec exercises the TOC scroll spy below the lg breakpoint with the offcanvas TOC open, asserting the active entry tracks scrolling and stays visible inside .offcanvas-body."
+      - "npm run test:smoke is green."
+    links: { issue: null, pr: null, roadmap: null }
+    created: 2026-09-05
+    updated: 2026-09-05
+
+  - id: T-047
+    title: "pages/_docs/features/toc.md documents a TOC API the theme does not implement"
+    status: open
+    priority: P3
+    area: docs
+    risk: low
+    effort: S
+    source: issue
+    route: content-reviewer
+    summary: >-
+      Discovered while correcting the scroll-spy sections of
+      pages/_docs/features/toc.md: the page's Implementation and Configuration
+      halves describe a table of contents this theme does not have. "TOC
+      Generation" shows a Kramdown `{{ content | toc_only }}` snippet and a
+      hand-rolled `page.content | split: '<h'` extractor, neither of which the
+      theme uses — the real TOC comes from _includes/content/toc.html (the
+      allejo/jekyll-toc parser) invoked by _includes/navigation/sidebar-right.html.
+      "Enable TOC" documents front-matter keys that nothing reads; the
+      `toc.min_level` / `toc.max_level` pair in the same section was already
+      corrected (grep confirms no include, layout, plugin or _config.yml
+      references either key). A reader following this page cannot reproduce the
+      theme's behaviour. Rewrite the two sections against the actual include,
+      its parameters, and the front-matter keys that really gate the panel.
+    acceptance:
+      - "Every Liquid snippet in toc.md matches an include the theme actually ships, verified by path."
+      - "Front-matter keys documented on the page are read somewhere in _includes, _layouts, _plugins or _config.yml."
+      - "scripts/content-review.rb still scores the page in the green band."
+      - "Jekyll build with the layered dev configs is green and the page's anchors keep resolving."
+
+  - id: T-048
+    title: "Site-level theme_color re-pins --zer0-color-primary over the active skin"
+    status: open
+    priority: P2
+    area: feat
+    risk: low
+    effort: S
+    source: issue
+    summary: "Discovered while making Mermaid diagrams follow the skin (ZER0-013 rework): the skin mixin (_sass/theme/_skins.scss) writes both --bs-primary and --zer0-color-primary under [data-theme-skin], but _includes/core/tokens-inline.html emits `:root { --zer0-color-primary: <theme_color.main> }` AFTER main.css, and :root ties [data-theme-skin] on specificity, so the later inline rule wins. Result on this site: buttons/links follow the skin (#6fa8dc on air, #8338ec on neon) while every custom component that reads --zer0-color-primary (callouts, code-block accent border, focus rings) stays on the config #007bff regardless of skin. Mermaid works around it by reading --bs-primary first; the token layer should agree with itself instead."
+    acceptance:
+      - "With theme_color.main set, switching skin changes --zer0-color-primary as well as --bs-primary (probe getComputedStyle on <html>)."
+      - "Decide and document the precedence: skin over site theme_color (recommended) or the reverse — one rule, applied to every --zer0-color-* the mixin sets."
+      - "A smoke test asserts --zer0-color-primary === --bs-primary after setSkin('neon')."
+      - "before/after evidence committed"
+    links: { issue: null, pr: null, roadmap: null }
+    created: 2026-09-05
+    updated: 2026-09-05
+
+  - id: T-049
+    title: "test_core.sh: Liquid nested-tag check and gem-content check can never fail"
+    status: open
+    priority: P3
+    area: tests
+    risk: low
+    effort: S
+    source: audit
+    summary: "Found while reviewing CI logs for PR #455: test/test_core.sh prints '[ERROR] Nested Liquid output tags found in _includes/navigation/sidebar-pagetree.html' on every run and still reports the Liquid validation as passed. Two defects: (1) the check is `grep -q \"{{.*{{\"`, which flags any line with two output tags — sidebar-pagetree.html:65 is `{{ _base }}{{ _section }}` inside a capture, valid Liquid — and the `return 1` sits inside a `find | while read` pipeline subshell, so it can never fail the function; (2) the gem-content check runs `tar -tzf` on the .gem, but a gem is an uncompressed tar (metadata.gz, data.tar.gz, checksums.yaml.gz), so gzip prints 'stdin: not in gzip format' four times and both branches always fall through to the 'Gem may not contain…' warnings without inspecting anything."
+    acceptance:
+      - "The nested-tag check only flags a genuinely nested output tag (e.g. `{{ a {{ b }} }}`), not two sibling tags on one line, and a positive match fails the test (no subshell swallowing the return)."
+      - "The gem-content check lists data.tar.gz inside the .gem (`tar -xOf … data.tar.gz | tar -tzf -`) and asserts _layouts/ and assets/ are present; a gem missing them fails the test."
+      - "./test/test_core.sh runs clean: no '[ERROR]' line on a passing run and no gzip/tar noise."
+    links: { issue: null, pr: null, roadmap: null }
+    created: 2026-09-05
+    updated: 2026-09-05
+
+  - id: T-050
+    title: "Visual Snapshots tier: LiveReload reloads the page mid-test because npm ci lands after Jekyll starts watching"
+    status: open
+    priority: P2
+    area: tests
+    risk: low
+    effort: S
+    source: audit
+    summary: "The snapshots project shows a retried test on most CI runs — '[snapshots] › appearance-snapshot.spec.js › skin: <random> › homepage visual snapshot' fails with 'page.evaluate: Execution context was destroyed, most likely because of a navigation' and passes on retry (aqua on PR #455, mint on main 5ff38bf). Nothing on the homepage navigates; the likely trigger is Jekyll's LiveReload. test/update-snapshots.sh runs `docker compose up -d` (jekyll serve --watch --livereload, repo bind-mounted at /site) and only then starts the Playwright container, which runs `npm ci` into the same bind mount. jekyll-watch 2.2.1 registers an ignore pattern only for exclude paths that EXIST when serve starts (`next unless absolute_path.exist?` in listen_ignore_paths), and a fresh CI checkout has no node_modules/, so the thousands of files npm ci writes fire the watcher, the site regenerates, and LiveReload pushes a reload to every open page over localhost:35729 (reachable: the Playwright container uses --network host). Whichever skin is mid-step when the regeneration finishes fails; Playwright's CI retry (retries: 1) masks it, at the cost of one retry per run and a false 'flaky' signal that would hide a real regression."
+    acceptance:
+      - "Jekyll in the snapshot stack cannot reload the browser during a run: either node_modules/ exists before `docker compose up` (run `npm ci` first, or `mkdir -p node_modules`) or the test stack serves without --livereload (compose override or a JEKYLL_LIVERELOAD toggle)."
+      - "Confirmed with the Playwright trace or `docker compose logs jekyll` showing no 'Regenerating' during a run."
+      - "Ten consecutive CI runs of the snapshots project report 0 flaky tests."
+      - "Root cause noted in the header of test/update-snapshots.sh so the ordering is not undone."
+    links: { issue: null, pr: null, roadmap: null }
+    created: 2026-09-05
+    updated: 2026-09-05
+
+  - id: T-051
+    title: "Preview-image engine: the xAI default model grok-2-image is retired — default to grok-imagine-image-2.0"
+    status: open
+    priority: P2
+    area: infra
+    risk: low
+    effort: S
+    source: issue
+    summary: "Discovered while adding the xAI provider to the chat proxy and Site Builder (ZER0-087): scripts/lib/preview_generator.py's XAIProvider.default_model() still returns 'grok-2-image', which xAI has retired in favour of the Grok Imagine family (grok-imagine-image-2.0, per docs.x.ai release notes). A site with preview_images.provider: xai and no explicit model gets an upstream error. The Site Builder now writes preview_images.model explicitly for generated sites, so only the engine default (and the .env.example comment for IMAGE_MODEL) is stale. scripts/lib/ is CODEOWNERS-owned, so this is a human-review change."
+    acceptance:
+      - "XAIProvider.default_model() returns grok-imagine-image-2.0 and the provider table comment in the engine header matches."
+      - "The image request keeps working with the current xAI response shape (data[0].url or b64_json)."
+      - "scripts/lib/README.md / .env.example mention the new default."
+    links: { issue: null, pr: null, roadmap: null }
+    created: 2026-09-07
+    updated: 2026-09-07