jekyll-theme-zer0 1.11.0 → 1.11.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bbe0013679e3fd31006811bfaafd9a011e3e21c2acdc892cefabc2968e5cc542
-  data.tar.gz: 678d6fba0883cbb6228d601d11880909ecbb34bf12c861d0ec9f0535ceeccf34
+  metadata.gz: 9501bcc820ec7514f9b42ebe63e0541de0287933c388facb2b6eaec3bac2e4e3
+  data.tar.gz: 4d756e820a18743a6a7fc391b52fd40fa606493d60d2854d2d377cdede74d496
 SHA512:
-  metadata.gz: 8ae41e18796c02009349411e1e9ea45723fd383004560d781a4fcfa266db4fbc6f246755b275b6aabfc86abde0482dcc11380b7065cff0c7a945276f7b48797a
-  data.tar.gz: 28b154eda3a2405e6b0e506fb9a293c53956d731d7a4c8239cd1ca3d58a10b6ec28195640d2a8da96853ccd3ea0c5b2c13476ac28f422650bec5259412178ff5
+  metadata.gz: b617c07bb328bcebf4be86fd0fdd8a3bc3cd513cdcf5fb6e6a1ebb564e39f318e245411a382eceeec0746549f6eb40b177682167f488a6b450e7d073042b9cb2
+  data.tar.gz: 1fab63085e0fc3be064120316e61b840c705e551e19c08a7329dc2290b682bbbb475e935917822c1538c9ca76b0a9ee7aa730e4cd5973d1e45a92addda390a40

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [1.11.2] - 2026-06-03
+
+### Changed
+- Version bump: patch release
+
+### Commits in this release
+- 452022ae chore(backlog): audit 2026-06-01 (#121)
+
+
+## [1.11.1] - 2026-06-01
+
+### Changed
+- Version bump: patch release
+
+### Commits in this release
+- d4a53d51 docs: consolidate, standardize, and add maintenance system (#112)
+
+
 ## [1.11.0] - 2026-06-01
 
 ### Changed

data/README.md

@@ -2,7 +2,7 @@
 title: zer0-mistakes
 sub-title: AI-Native Jekyll Theme
 description: AI-native Jekyll theme for GitHub Pages — Docker-first development, AI-powered installation, multi-agent integration (Copilot, Codex, Cursor, Claude), AI preview-image generation, and AIEO content optimization with Bootstrap 5.3.
-version: 1.11.0
+version: 1.11.2
 layout: landing
 tags:
   - jekyll
@@ -20,7 +20,7 @@ categories:
   - bootstrap
   - ai-tooling
 created: 2024-02-10T23:51:11.480Z
-lastmod: 2026-06-01T03:33:27.000Z
+lastmod: 2026-06-03T01:19:09.000Z
 draft: false
 permalink: /
 slug: zer0
@@ -901,7 +901,7 @@ git push origin feature/awesome-feature
 
 | Metric | Value |
 |--------|-------|
-| **Current Version** | 1.11.0 ([RubyGems](https://rubygems.org/gems/jekyll-theme-zer0), [CHANGELOG](/CHANGELOG)) |
+| **Current Version** | 1.11.2 ([RubyGems](https://rubygems.org/gems/jekyll-theme-zer0), [CHANGELOG](/CHANGELOG)) |
 | **Documented Features** | 43 ([Feature Registry](https://github.com/bamr87/zer0-mistakes/blob/main/_data/features.yml)) |
 | **Setup Time** | 2-5 minutes ([install.sh benchmarks](https://github.com/bamr87/zer0-mistakes/blob/main/install.sh)) |
 | **Documentation Pages** | 70+ ([browse docs](https://zer0-mistakes.com/pages/)) |
@@ -956,6 +956,6 @@ And these AI partners that make zer0-mistakes truly AI-native:
 
 **Built with ❤️ — and a little help from our AI partners — for the Jekyll community**
 
-**v1.11.0** • [Changelog](CHANGELOG.md) • [License](LICENSE) • [Contributing](CONTRIBUTING.md) • [AI Agent Guide](AGENTS.md)
+**v1.11.2** • [Changelog](CHANGELOG.md) • [License](LICENSE) • [Contributing](CONTRIBUTING.md) • [AI Agent Guide](AGENTS.md)
 
 

data/_data/backlog.yml

@@ -55,8 +55,8 @@
 
 meta:
   title: "zer0-mistakes Backlog"
-  updated: 2026-05-31
-  next_id: 7
+  updated: 2026-06-01
+  next_id: 12
 
 tasks:
   # --- Housekeeping (seeded so the loop has work on day one) ------------------
@@ -159,3 +159,116 @@ tasks:
     links: { issue: null, pr: null, roadmap: "1.0" }
     created: 2026-05-31
     updated: 2026-05-31
+
+  # --- 2026-06-01 audit -------------------------------------------------------
+
+  - id: T-007
+    title: "Fix global navbar WCAG 2.1 AA violations to enable axe-core full-audit tests"
+    status: open
+    priority: P1
+    area: a11y
+    risk: standard
+    effort: M
+    source: audit
+    summary: >-
+      Three tests in `test/visual/accessibility.spec.js` are frozen with `test.fixme`
+      because four WCAG 2.1 AA violations in the global navbar prevent them from passing:
+      `aria-required-children` (menubar/button nesting), `link-name` (icon-only nav links),
+      `list` (footer list structure), and `scrollable-region-focusable` (code blocks).
+      Fix the HTML/ARIA in `_includes/` and `_layouts/` to make the full axe-core audit green.
+    acceptance:
+      - "All four violations listed in the `test.fixme` comment are resolved in `_includes/` / `_layouts/`."
+      - "The three `test.fixme` blocks in `test/visual/accessibility.spec.js` are changed to live `test()` calls and pass in CI."
+      - "`bundle exec ./scripts/bin/validate --quick` still passes."
+      - "No visual regression in smoke snapshot tests."
+    links: { issue: null, pr: null, roadmap: "1.9" }
+    created: 2026-06-01
+    updated: 2026-06-01
+
+  - id: T-008
+    title: "Fix theme-customizer YAML export to quote hex color values"
+    status: open
+    priority: P2
+    area: feat
+    risk: standard
+    effort: S
+    source: audit
+    summary: >-
+      The JS theme-customizer export serialises CSS custom-property values directly into
+      YAML without quoting strings that start with `#`. Unquoted `#RRGGBB` is treated as a
+      YAML comment by parsers, silently dropping colour values. A regression guard in
+      `test/visual/theme-colors.spec.js` is frozen as `test.fixme` until the bug is fixed.
+    acceptance:
+      - "JS export wraps every hex colour value (matching `/#[0-9a-fA-F]{3,8}/`) in double quotes in the generated YAML."
+      - "The `test.fixme` in `test/visual/theme-colors.spec.js` is promoted to a live `test()` and passes in CI."
+      - "Exported YAML is valid when parsed by `yaml.safe_load` in Ruby."
+    links: { issue: null, pr: null, roadmap: null }
+    created: 2026-06-01
+    updated: 2026-06-01
+
+  - id: T-009
+    title: "Sanitize sensitive config keys from admin config-page DOM injection"
+    status: open
+    priority: P1
+    area: infra
+    risk: standard
+    effort: S
+    source: audit
+    summary: >-
+      The admin config page injects raw `_config.yml` content into a hidden
+      `<pre id="cfg-full-yaml">` element. If the config contains secrets
+      (`api_key`, `token`, PostHog `phc_*` keys, etc.) they are exposed in the page
+      DOM. A regression test in `test/visual/security.spec.js` is frozen as
+      `test.fixme` until a sanitisation pass is in place.
+    acceptance:
+      - "The Liquid/Ruby that populates `<pre id=\"cfg-full-yaml\">` strips or masks keys matching `api_key`, `secret`, `password`, `token`, and `phc_` prefix before DOM injection."
+      - "The `test.fixme` in `test/visual/security.spec.js` is promoted to a live `test()` and passes in CI."
+      - "The visible config display in the admin UI is unaffected (only the raw hidden element is sanitised)."
+    links: { issue: null, pr: null, roadmap: null }
+    created: 2026-06-01
+    updated: 2026-06-01
+
+  - id: T-010
+    title: "Complete v1.9 quickstart docs rewrite with getting-started guide and screenshots"
+    status: open
+    priority: P2
+    area: docs
+    risk: low
+    effort: M
+    source: roadmap
+    summary: >-
+      The v1.9 milestone lists "Quickstart documentation rewrite with screenshots"
+      as a deliverable, but `pages/_docs/quickstart/` contains only `bare-minimum.md`.
+      Add a proper quickstart index page and at least one full getting-started guide
+      (covering the standard GitHub Pages workflow) with annotated screenshots.
+    acceptance:
+      - "`pages/_docs/quickstart/index.md` exists with a nav overview linking to available quickstart guides."
+      - "At least one guide beyond `bare-minimum.md` covers the standard fork/remote-theme workflow."
+      - "Each guide includes at least one screenshot stored under `assets/images/docs/quickstart/`."
+      - "All new pages pass `docs-validate.yml` front-matter and link checks."
+    links: { issue: null, pr: null, roadmap: "1.9" }
+    created: 2026-06-01
+    updated: 2026-06-01
+
+  - id: T-011
+    title: "Add Ruby unit tests for uncovered _plugins/ generators"
+    status: open
+    priority: P2
+    area: tests
+    risk: standard
+    effort: M
+    source: audit
+    summary: >-
+      Three Jekyll plugins have no dedicated unit tests: `content_statistics_generator.rb`,
+      `preview_image_generator.rb`, and `admin_page_urls.rb`. The quality suite has
+      URL-pattern checks (`test_preview_image_urls`) but no specs that exercise the
+      generator logic in isolation. This is a concrete gap on the path to the
+      3.0-milestone 90% coverage target.
+    acceptance:
+      - "`test/test_ruby_converter.rb`-style RSpec or Minitest specs exist for all three plugins."
+      - "Each spec runs independently without a running Jekyll server (`bundle exec ruby -Itest`)."
+      - "`./scripts/bin/test` continues to pass with the new specs included."
+      - "Edge cases covered: empty collections, missing front-matter keys, and duplicate slug detection."
+    links: { issue: null, pr: null, roadmap: "3.0" }
+    created: 2026-06-01
+    updated: 2026-06-01

data/_includes/components/theme-preview-gallery.html

@@ -442,7 +442,7 @@ docker-compose up
       <div class="card-body d-flex flex-column gap-4">
         <div>
           <p class="small text-body-secondary mb-1">Breadcrumb</p>
-          <nav aria-label="breadcrumb">
+          <nav aria-label="Breadcrumb example">
             <ol class="breadcrumb mb-0">
               <li class="breadcrumb-item"><a href="#">Home</a></li>
               <li class="breadcrumb-item"><a href="#">Settings</a></li>

data/scripts/docs/check-freshness.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+# =========================================================================
+# scripts/docs/check-freshness.sh — Staleness detector for docs/
+# =========================================================================
+# Flags docs where the lastmod front matter field is more than THRESHOLD
+# days behind the file's most recent git commit. This surfaces docs that
+# describe code that has since changed without a corresponding doc update.
+#
+# Usage:
+#   ./scripts/docs/check-freshness.sh
+#   ./scripts/docs/check-freshness.sh --threshold 90   # custom days (default: 60)
+#   ./scripts/docs/check-freshness.sh --verbose
+# =========================================================================
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+source "$SCRIPT_DIR/../lib/common.sh"
+source "$SCRIPT_DIR/../lib/frontmatter.sh"
+
+THRESHOLD_DAYS=60
+STALE_COUNT=0
+FILES_CHECKED=0
+STALE_FILES=""
+
+parse_args() {
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --threshold) shift; THRESHOLD_DAYS="$1" ;;
+            --verbose)   export VERBOSE=true ;;
+            --help|-h)   show_usage; exit 0 ;;
+            *) warn "Unknown option: $1" ;;
+        esac
+        shift
+    done
+}
+
+show_usage() {
+    cat << EOF
+Freshness Checker for docs/
+
+USAGE:
+    ./scripts/docs/check-freshness.sh [OPTIONS]
+
+OPTIONS:
+    --threshold N   Days of drift before flagging as stale (default: $THRESHOLD_DAYS)
+    --verbose       Show all files, not just stale ones
+
+A doc is stale when:
+  git log -1 date for that file > (lastmod front matter + THRESHOLD days)
+
+This catches docs describing code that changed but whose lastmod wasn't updated.
+EOF
+}
+
+# Returns seconds since epoch for a date string, or empty on failure
+date_to_epoch() {
+    local d="$1"
+    ruby -rtime -e "puts Time.parse('$d').to_i" 2>/dev/null || true
+}
+
+parse_args "$@"
+
+THRESHOLD_SECS=$(( THRESHOLD_DAYS * 86400 ))
+
+log "Checking freshness of docs (threshold: ${THRESHOLD_DAYS} days)..."
+echo ""
+
+for filepath in $(find "$REPO_ROOT/docs" -name "*.md" -not -name "README.md" -not -path "*/archive/*" | sort); do
+    relpath="${filepath#$REPO_ROOT/}"
+
+    # Skip files without front matter
+    local_first=""
+    IFS= read -r local_first < "$filepath" || true
+    if [[ ! "$local_first" =~ ^--- ]]; then
+        debug "  SKIP (no front matter): $relpath"
+        continue
+    fi
+
+    lastmod_str="$(get_frontmatter_field "$filepath" "lastmod" 2>/dev/null || true)"
+    if [[ -z "$lastmod_str" ]]; then
+        debug "  SKIP (no lastmod field): $relpath"
+        continue
+    fi
+
+    lastmod_epoch="$(date_to_epoch "$lastmod_str")"
+    [[ -z "$lastmod_epoch" ]] && continue
+
+    # Get last git commit date for this file
+    git_date_str="$(git -C "$REPO_ROOT" log -1 --format="%aI" -- "$relpath" 2>/dev/null || true)"
+    [[ -z "$git_date_str" ]] && continue
+
+    git_epoch="$(date_to_epoch "$git_date_str")"
+    [[ -z "$git_epoch" ]] && continue
+
+    drift=$(( git_epoch - lastmod_epoch ))
+
+    if [[ $drift -gt $THRESHOLD_SECS ]]; then
+        drift_days=$(( drift / 86400 ))
+        warn "  STALE (${drift_days}d behind): $relpath"
+        warn "         lastmod: $lastmod_str"
+        warn "         git:     $git_date_str"
+        STALE_FILES="$STALE_FILES $relpath"
+        STALE_COUNT=$((STALE_COUNT + 1))
+    else
+        debug "  FRESH: $relpath"
+    fi
+
+    FILES_CHECKED=$((FILES_CHECKED + 1))
+done
+
+echo ""
+log "Results: $FILES_CHECKED files checked, $STALE_COUNT stale"
+
+if [[ $STALE_COUNT -gt 0 ]]; then
+    echo ""
+    info "Stale files (update lastmod after reviewing content):"
+    for f in $STALE_FILES; do
+        echo "  - $f"
+    done
+    exit 1
+fi

data/scripts/docs/check-links.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+# =========================================================================
+# scripts/docs/check-links.sh — Internal link checker for docs/
+# =========================================================================
+# Validates that relative markdown links in docs/**/*.md resolve to files
+# that actually exist in the repository. Does not validate external URLs.
+#
+# Usage:
+#   ./scripts/docs/check-links.sh
+#   ./scripts/docs/check-links.sh --verbose
+# =========================================================================
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+source "$SCRIPT_DIR/../lib/common.sh"
+
+ERRORS=0
+FILES_CHECKED=0
+
+parse_args() {
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --verbose) export VERBOSE=true ;;
+            --help|-h) show_usage; exit 0 ;;
+            *) warn "Unknown option: $1" ;;
+        esac
+        shift
+    done
+}
+
+show_usage() {
+    cat << 'EOF'
+Internal Link Checker for docs/
+
+USAGE:
+    ./scripts/docs/check-links.sh [--verbose]
+
+Checks relative markdown links ([text](path)) in docs/**/*.md to verify
+the target file exists. The contributor docs under docs/ use filesystem
+relative links between markdown files, so they can be resolved on disk.
+
+Not covered here:
+  - pages/_docs/**: the user-facing Jekyll site uses permalink URLs and
+    the relative_url filter, which are not filesystem paths; those links
+    are validated by htmlproofer against the built _site in CI.
+  - External URLs (http://, https://, mailto:, etc.)
+  - Anchor-only links (#section)
+  - Absolute site URLs (/docs/..., /faq/, ...)
+EOF
+}
+
+# Extract relative markdown links from a file, excluding external, anchor-only,
+# and absolute site URLs. Uses Ruby (already required by this repo) so the
+# extraction is portable across GNU and BSD/macOS environments.
+extract_relative_links() {
+    local filepath="$1"
+    ruby -e '
+        in_fence = false
+        File.foreach(ARGV[0], encoding: "UTF-8") do |line|
+            # Toggle fenced code blocks (``` or ~~~); skip their contents,
+            # which are examples rather than real links.
+            if line =~ /\A\s*(```|~~~)/
+                in_fence = !in_fence
+                next
+            end
+            next if in_fence
+            # Ignore inline code spans so `[x](y)` written as code is skipped.
+            scrubbed = line.gsub(/`[^`]*`/, "")
+            scrubbed.scan(/\]\(([^)]+)\)/) do |m|
+                link = m[0].strip
+                next if link.empty?
+                next if link.include?("{{") || link.include?("{%")  # Liquid template
+                next if link =~ %r{\A[a-z][a-z0-9+.-]*:}i            # scheme: http:, mailto:, etc.
+                next if link.start_with?("#")                        # anchor-only
+                next if link.start_with?("/")                        # absolute site URL (Jekyll permalink)
+                link = link.split("#", 2).first                      # strip anchor fragment
+                puts link unless link.nil? || link.empty?
+            end
+        end
+    ' "$filepath" 2>/dev/null || true
+}
+
+parse_args "$@"
+
+log "Checking internal links in docs/..."
+echo ""
+
+# archive/ holds superseded historical docs; templates/ holds scaffolding with
+# intentional placeholder links (link-to-config, etc.) — neither is "live" docs.
+for filepath in $(find "$REPO_ROOT/docs" -name "*.md" \
+        -not -path "*/archive/*" -not -path "*/templates/*" 2>/dev/null | sort); do
+    relpath="${filepath#$REPO_ROOT/}"
+    filedir="$(dirname "$filepath")"
+    file_errors=0
+
+    while IFS= read -r link; do
+        [[ -z "$link" ]] && continue
+
+        # Resolve relative to the file's directory (absolute site URLs are
+        # filtered out in extract_relative_links)
+        target="$filedir/$link"
+
+        # Normalize (remove ./ and resolve ..)
+        target="$(cd "$(dirname "$target")" 2>/dev/null && pwd)/$(basename "$target")" 2>/dev/null || target="$filedir/$link"
+
+        if [[ ! -f "$target" && ! -d "$target" ]]; then
+            warn "  BROKEN: $relpath → $link"
+            file_errors=$((file_errors + 1))
+            ERRORS=$((ERRORS + 1))
+        else
+            debug "  OK: $relpath → $link"
+        fi
+    done < <(extract_relative_links "$filepath")
+
+    FILES_CHECKED=$((FILES_CHECKED + 1))
+done
+
+echo ""
+log "Results: $FILES_CHECKED files checked, $ERRORS broken links"
+
+[[ $ERRORS -eq 0 ]] || exit 1

data/scripts/docs/lint-frontmatter.sh

@@ -0,0 +1,197 @@
+#!/usr/bin/env bash
+# =========================================================================
+# scripts/docs/lint-frontmatter.sh — Front matter validator for docs/
+# =========================================================================
+# Checks every content .md file under docs/ (excluding READMEs and archive/)
+# for the required front matter fields defined in the schema.
+#
+# Usage:
+#   ./scripts/docs/lint-frontmatter.sh           # validate
+#   ./scripts/docs/lint-frontmatter.sh --fix     # inject skeleton where missing
+#   ./scripts/docs/lint-frontmatter.sh --verbose # show per-file results
+# =========================================================================
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+source "$SCRIPT_DIR/../lib/common.sh"
+source "$SCRIPT_DIR/../lib/frontmatter.sh"
+
+FIX_MODE=false
+REQUIRED_FIELDS=(title description date lastmod categories tags author)
+ERRORS=0
+FILES_OK=0
+FILES_MISSING=0
+
+# Bash 3.2-compatible file-list builder (no mapfile)
+list_docs_files() {
+    find "$REPO_ROOT/docs" -name "*.md" \
+        -not -name "README.md" \
+        -not -path "*/archive/*" \
+        | sort
+}
+
+parse_args() {
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --fix)     FIX_MODE=true ;;
+            --verbose) export VERBOSE=true ;;
+            --help|-h) show_usage; exit 0 ;;
+            *) warn "Unknown option: $1" ;;
+        esac
+        shift
+    done
+}
+
+show_usage() {
+    cat << 'EOF'
+Front Matter Linter for docs/
+
+USAGE:
+    ./scripts/docs/lint-frontmatter.sh [OPTIONS]
+
+REQUIRED FIELDS (per .github/instructions/documentation.instructions.md):
+    title, description, date, lastmod, categories, tags, author
+
+EXCLUDES:
+    - README.md files (directory indexes)
+    - docs/archive/** (historical docs)
+EOF
+}
+
+# Determine tags from directory name
+dir_tags() {
+    local dir="$1"
+    case "$dir" in
+        ui)             echo "[ui, styling, theme]" ;;
+        architecture)   echo "[architecture, design]" ;;
+        development)    echo "[development, contributing]" ;;
+        systems)        echo "[systems, automation]" ;;
+        installation)   echo "[installation, setup]" ;;
+        features)       echo "[features]" ;;
+        implementation) echo "[implementation, changelog]" ;;
+        releases)       echo "[releases]" ;;
+        templates)      echo "[templates]" ;;
+        *)              echo "[docs]" ;;
+    esac
+}
+
+# Inject skeleton front matter at the top of a file
+inject_frontmatter() {
+    local filepath="$1"
+    local relpath="${filepath#$REPO_ROOT/}"
+    local subdir
+    subdir="$(echo "$relpath" | cut -d'/' -f2)"
+
+    # Extract title from first H1 heading
+    local title
+    title="$(grep -m1 "^# " "$filepath" 2>/dev/null | sed 's/^# //' || true)"
+    [[ -z "$title" ]] && title="$(basename "$filepath" .md | tr '-' ' ' | sed 's/\b./\u&/g')"
+
+    # Dates from git history
+    local date lastmod now
+    now="$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")"
+    date="$(git -C "$REPO_ROOT" log --diff-filter=A --follow --format="%aI" -- "$relpath" 2>/dev/null | tail -1 || true)"
+    lastmod="$(git -C "$REPO_ROOT" log -1 --format="%aI" -- "$relpath" 2>/dev/null || true)"
+    [[ -z "$date" ]]    && date="$now"
+    [[ -z "$lastmod" ]] && lastmod="$now"
+
+    # Normalize to ISO 8601 with milliseconds
+    date="$(echo "$date" | ruby -rtime -e 'puts Time.parse(STDIN.read.strip).utc.strftime("%Y-%m-%dT%H:%M:%S.000Z")' 2>/dev/null || echo "$now")"
+    lastmod="$(echo "$lastmod" | ruby -rtime -e 'puts Time.parse(STDIN.read.strip).utc.strftime("%Y-%m-%dT%H:%M:%S.000Z")' 2>/dev/null || echo "$now")"
+
+    local tags
+    tags="$(dir_tags "$subdir")"
+
+    local skeleton
+    skeleton="---
+title: \"${title}\"
+description: \"TODO: Add a 120-160 character description of this document.\"
+date: ${date}
+lastmod: ${lastmod}
+categories: [docs]
+tags: ${tags}
+author: bamr87
+---"
+
+    # Prepend skeleton to file
+    local tmpfile
+    tmpfile="$(mktemp)"
+    printf '%s\n\n' "$skeleton" | cat - "$filepath" > "$tmpfile"
+    mv "$tmpfile" "$filepath"
+    info "  Injected front matter: $relpath"
+}
+
+parse_args "$@"
+
+total_files=0
+for f in $(list_docs_files); do total_files=$((total_files + 1)); done
+log "Checking $total_files docs files for required front matter..."
+echo ""
+
+for filepath in $(list_docs_files); do
+    relpath="${filepath#$REPO_ROOT/}"
+    missing=()
+
+    # Check if front matter exists at all
+    local_first_line=""
+    IFS= read -r local_first_line < "$filepath" || true
+
+    if [[ ! "$local_first_line" =~ ^--- ]]; then
+        if [[ "$FIX_MODE" == "true" ]]; then
+            inject_frontmatter "$filepath"
+            FILES_OK=$((FILES_OK + 1))
+            continue
+        else
+            warn "  MISSING front matter: $relpath"
+            FILES_MISSING=$((FILES_MISSING + 1))
+            ERRORS=$((ERRORS + 1))
+            continue
+        fi
+    fi
+
+    # Check each required field
+    fm="$(extract_frontmatter "$filepath" 2>/dev/null || true)"
+    missing_list=""
+    for field in "${REQUIRED_FIELDS[@]}"; do
+        if ! echo "$fm" | grep -q "^${field}:"; then
+            missing_list="$missing_list $field"
+        fi
+    done
+
+    # Description quality: presence alone is not enough. Reject the --fix
+    # skeleton placeholder and obvious stubs so a "compliant" run can't ship
+    # docs with a TODO description. Schema target is a 120-160 char sentence.
+    desc_problem=""
+    if echo "$fm" | grep -q "^description:"; then
+        desc_value="$(echo "$fm" | grep -m1 "^description:" | sed -E 's/^description:[[:space:]]*//; s/^"(.*)"$/\1/; s/^'"'"'(.*)'"'"'$/\1/')"
+        if echo "$desc_value" | grep -qi "TODO"; then
+            desc_problem="placeholder TODO description"
+        elif [[ "${#desc_value}" -lt 40 ]]; then
+            desc_problem="description too short (${#desc_value} chars; aim for 120-160)"
+        fi
+    fi
+
+    if [[ -n "$missing_list" || -n "$desc_problem" ]]; then
+        local_msg="  INCOMPLETE ($relpath):"
+        [[ -n "$missing_list" ]] && local_msg="$local_msg missing:$missing_list"
+        [[ -n "$desc_problem" ]] && local_msg="$local_msg $desc_problem"
+        warn "$local_msg"
+        ERRORS=$((ERRORS + 1))
+    else
+        debug "  OK: $relpath"
+        FILES_OK=$((FILES_OK + 1))
+    fi
+done
+
+incomplete=$((ERRORS - FILES_MISSING))
+echo ""
+log "Results: ${FILES_OK} OK, ${FILES_MISSING} missing front matter, ${incomplete} incomplete"
+
+if [[ $ERRORS -gt 0 ]]; then
+    if [[ "$FIX_MODE" == "false" ]]; then
+        info "Run with --fix to inject skeleton front matter into missing files."
+    fi
+    exit 1
+fi

data/scripts/docs/validate.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# =========================================================================
+# scripts/docs/validate.sh — Docs validation orchestrator
+# =========================================================================
+# Runs all docs health checks: front matter, links, and freshness.
+#
+# Usage:
+#   ./scripts/docs/validate.sh              # run all checks
+#   ./scripts/docs/validate.sh --lint       # front matter only
+#   ./scripts/docs/validate.sh --links      # links only
+#   ./scripts/docs/validate.sh --freshness  # freshness only
+#   ./scripts/docs/validate.sh --fix        # inject missing front matter
+#   ./scripts/docs/validate.sh --verbose    # detailed output
+# =========================================================================
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/../lib/common.sh"
+
+RUN_LINT=true
+RUN_LINKS=true
+RUN_FRESHNESS=true
+FIX_MODE=false
+OVERALL_STATUS=0
+
+parse_args() {
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --lint)       RUN_LINKS=false; RUN_FRESHNESS=false ;;
+            --links)      RUN_LINT=false;  RUN_FRESHNESS=false ;;
+            --freshness)  RUN_LINT=false;  RUN_LINKS=false ;;
+            --fix)        FIX_MODE=true ;;
+            --verbose)    export VERBOSE=true ;;
+            --help|-h)    show_usage; exit 0 ;;
+            *) warn "Unknown option: $1" ;;
+        esac
+        shift
+    done
+}
+
+show_usage() {
+    cat << 'EOF'
+Docs Validation Suite for zer0-mistakes
+
+USAGE:
+    ./scripts/docs/validate.sh [OPTIONS]
+
+OPTIONS:
+    --lint        Front matter compliance only
+    --links       Link checking only
+    --freshness   Staleness check only
+    --fix         Inject skeleton front matter into files that lack it
+    --verbose     Detailed output
+    --help        Show this message
+
+CHECKS:
+    lint        Every docs/**/*.md (non-README, non-archive) has required
+                front matter: title, description, date, lastmod, categories,
+                tags, author
+    links       Internal markdown links resolve to existing files
+    freshness   Files where lastmod trails the last git commit by > 60 days
+EOF
+}
+
+run_check() {
+    local name="$1"; local script="$2"; shift 2
+    log "Running: $name"
+    if "$script" "$@"; then
+        log "  PASS: $name"
+    else
+        warn "  FAIL: $name"
+        OVERALL_STATUS=1
+    fi
+}
+
+parse_args "$@"
+
+[[ "$FIX_MODE" == "true" ]] && EXTRA="--fix" || EXTRA=""
+
+[[ "$RUN_LINT"      == "true" ]] && run_check "Front matter lint" "$SCRIPT_DIR/lint-frontmatter.sh" $EXTRA
+[[ "$RUN_LINKS"     == "true" ]] && run_check "Link check"        "$SCRIPT_DIR/check-links.sh"
+[[ "$RUN_FRESHNESS" == "true" ]] && run_check "Freshness check"   "$SCRIPT_DIR/check-freshness.sh"
+
+if [[ $OVERALL_STATUS -eq 0 ]]; then
+    log "All docs checks passed."
+else
+    error "One or more docs checks failed."
+    exit 1
+fi

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-theme-zer0
 version: !ruby/object:Gem::Version
-  version: 1.11.0
+  version: 1.11.2
 platform: ruby
 authors:
 - Amr Abdel
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-01 00:00:00.000000000 Z
+date: 2026-06-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -368,6 +368,10 @@ files:
 - scripts/build
 - scripts/convert-notebooks.sh
 - scripts/docker-publish
+- scripts/docs/check-freshness.sh
+- scripts/docs/check-links.sh
+- scripts/docs/lint-frontmatter.sh
+- scripts/docs/validate.sh
 - scripts/example-usage.sh
 - scripts/features/generate-preview-images
 - scripts/features/install-preview-generator