jekyll-theme-zer0 1.22.0 → 1.24.0

data/_data/navigation/docs.yml

@@ -70,6 +70,10 @@
       url: /docs/deployment/
     - title: GitHub Pages
       url: /docs/deployment/github-pages/
+    - title: Remote-Theme Consumer Checklist
+      url: /docs/deployment/remote-theme-checklist/
+    - title: Safe-Mode Build Overlay
+      url: /docs/deployment/build-overlay/
     - title: Netlify
       url: /docs/deployment/netlify/
     - title: Custom Domain

data/_data/theme_backgrounds.yml

@@ -99,3 +99,27 @@ skins:
     gradient: "assets/backgrounds/gradients/sunrise.svg"
     pattern: "assets/backgrounds/patterns/sunrise.svg"
     noise: "assets/backgrounds/noise/sunrise.svg"
+
+  # `dark` is the DEFAULT theme_skin, and `contrast` is advertised as valid, but
+  # neither was mapped here — so the SVG-background feature had no entry for them
+  # (issue #240). The gradient/pattern/noise assets already ship; these entries
+  # wire them up. Colors are taken from each skin's gradient stops.
+  dark:
+    label: "Dark"
+    colors:
+      primary: "#1a1a2e"
+      secondary: "#16213e"
+      accent: "#0f3460"
+    gradient: "assets/backgrounds/gradients/dark.svg"
+    pattern: "assets/backgrounds/patterns/dark.svg"
+    noise: "assets/backgrounds/noise/dark.svg"
+
+  contrast:
+    label: "Contrast"
+    colors:
+      primary: "#111111"
+      secondary: "#333333"
+      accent: "#ffcc00"
+    gradient: "assets/backgrounds/gradients/contrast.svg"
+    pattern: "assets/backgrounds/patterns/contrast.svg"
+    noise: "assets/backgrounds/noise/contrast.svg"

data/_includes/components/component-showcase.html

@@ -25,11 +25,12 @@
   - Bootstrap 5.3 CSS & JS (loaded by theme)
   - Bootstrap Icons (loaded by theme)
 
-  Note: The breadcrumb and list-group links are DEMO links only — they are
-        intentionally inert (href="#" with onclick="return false;") so the
-        showcase never injects site-absolute paths (/docs/, /pages/, ...) that
-        would 404 on consumer sites that lack those exact routes (issue #219).
-        Do not point them at absolute paths.
+  Note: The breadcrumb and list-group demo links are existence-guarded (issue #219).
+        Each target URL is resolved against site.html_pages (and collection docs
+        for collection-backed routes). When the page exists in the build the link
+        is real; when it does not the label renders as plain text. This keeps the
+        showcase safe for remote-theme consumers who may lack /docs/, /posts/,
+        /categories/, /tags/, or /docs/customization/.
   ===================================================================
 -->
 {% assign sections = include.sections | default: "alerts,buttons,badges,cards,accordion,tabs,progress,breadcrumbs,table,tooltips,list-group" %}
@@ -326,11 +327,29 @@ theme: jekyll-theme-zer0</code></pre>
 <!-- ===== BREADCRUMBS ===== -->
 <h3 id="showcase-breadcrumbs">Breadcrumbs</h3>
 <p>Hierarchical navigation trail showing current page position:</p>
+{% comment %} Existence-guard the demo breadcrumb links so they never 404 on
+   remote-theme consumers that lack /docs/ or /docs/customization/. When the
+   target page is in the build the crumb is a real link; otherwise plain text.
+   Home (/) is always present. Pattern mirrors _includes/navigation/breadcrumbs.html. {% endcomment %}
+{% assign _demo_docs_page = site.html_pages | where: "url", "/docs/" | first %}
+{% unless _demo_docs_page %}
+  {% for _col in site.collections %}
+    {% assign _demo_docs_page = _col.docs | where: "url", "/docs/" | first %}
+    {% if _demo_docs_page %}{% break %}{% endif %}
+  {% endfor %}
+{% endunless %}
+{% assign _demo_custom_page = site.html_pages | where: "url", "/docs/customization/" | first %}
+{% unless _demo_custom_page %}
+  {% for _col in site.collections %}
+    {% assign _demo_custom_page = _col.docs | where: "url", "/docs/customization/" | first %}
+    {% if _demo_custom_page %}{% break %}{% endif %}
+  {% endfor %}
+{% endunless %}
 <nav aria-label="breadcrumb example" class="mb-4">
   <ol class="breadcrumb">
-    <li class="breadcrumb-item"><a href="#" class="text-decoration-none" onclick="return false;"><i class="bi bi-house me-1"></i>Home</a></li>
-    <li class="breadcrumb-item"><a href="#" class="text-decoration-none" onclick="return false;">Documentation</a></li>
-    <li class="breadcrumb-item"><a href="#" class="text-decoration-none" onclick="return false;">Customization</a></li>
+    <li class="breadcrumb-item"><a href="{{ '/' | relative_url }}" class="text-decoration-none"><i class="bi bi-house me-1"></i>Home</a></li>
+    <li class="breadcrumb-item">{% if _demo_docs_page %}<a href="{{ '/docs/' | relative_url }}" class="text-decoration-none">Documentation</a>{% else %}Documentation{% endif %}</li>
+    <li class="breadcrumb-item">{% if _demo_custom_page %}<a href="{{ '/docs/customization/' | relative_url }}" class="text-decoration-none">Customization</a>{% else %}Customization{% endif %}</li>
     <li class="breadcrumb-item active" aria-current="page">Theme Colors</li>
   </ol>
 </nav>
@@ -419,25 +438,67 @@ document.addEventListener('DOMContentLoaded', () => {
 <!-- ===== LIST GROUP ===== -->
 <h3 id="showcase-list-group">List Group</h3>
 <p>Organized content lists with icons, badges, and action states:</p>
+{% comment %} Existence-guard the demo list-group links (issue #219). Each target
+   URL is resolved against site.html_pages + collection docs. When present the
+   item is a real <a>; when absent it renders as a non-linking <div> so no 404
+   is injected on remote-theme consumers that lack /posts/, /docs/, /categories/,
+   or /tags/. Pattern mirrors section-sidebar.html and author-bio.html. {% endcomment %}
+{% assign _demo_posts_page = site.html_pages | where: "url", "/posts/" | first %}
+{% unless _demo_posts_page %}
+  {% for _col in site.collections %}
+    {% assign _demo_posts_page = _col.docs | where: "url", "/posts/" | first %}
+    {% if _demo_posts_page %}{% break %}{% endif %}
+  {% endfor %}
+{% endunless %}
+{% assign _demo_cats_page = site.html_pages | where: "url", "/categories/" | first %}
+{% unless _demo_cats_page %}
+  {% for _col in site.collections %}
+    {% assign _demo_cats_page = _col.docs | where: "url", "/categories/" | first %}
+    {% if _demo_cats_page %}{% break %}{% endif %}
+  {% endfor %}
+{% endunless %}
+{% assign _demo_tags_page = site.html_pages | where: "url", "/tags/" | first %}
+{% unless _demo_tags_page %}
+  {% for _col in site.collections %}
+    {% assign _demo_tags_page = _col.docs | where: "url", "/tags/" | first %}
+    {% if _demo_tags_page %}{% break %}{% endif %}
+  {% endfor %}
+{% endunless %}
 <div class="row g-4 mb-4">
   <div class="col-md-6">
     <div class="list-group">
-      <a href="#" onclick="return false;" class="list-group-item list-group-item-action d-flex justify-content-between align-items-center">
+      {% if _demo_posts_page %}
+      <a href="{{ '/posts/' | relative_url }}" class="list-group-item list-group-item-action d-flex justify-content-between align-items-center">
+      {% else %}
+      <div class="list-group-item d-flex justify-content-between align-items-center">
+      {% endif %}
         <span><i class="bi bi-journal-richtext text-primary me-2"></i>Blog Posts</span>
         <span class="badge bg-primary rounded-pill">{{ site.posts.size | default: "12" }}</span>
-      </a>
-      <a href="#" onclick="return false;" class="list-group-item list-group-item-action d-flex justify-content-between align-items-center">
+      {% if _demo_posts_page %}</a>{% else %}</div>{% endif %}
+      {% if _demo_docs_page %}
+      <a href="{{ '/docs/' | relative_url }}" class="list-group-item list-group-item-action d-flex justify-content-between align-items-center">
+      {% else %}
+      <div class="list-group-item d-flex justify-content-between align-items-center">
+      {% endif %}
         <span><i class="bi bi-book text-success me-2"></i>Documentation</span>
         <span class="badge bg-success rounded-pill">{{ site.documents.size | default: "8" }}</span>
-      </a>
-      <a href="#" onclick="return false;" class="list-group-item list-group-item-action d-flex justify-content-between align-items-center">
+      {% if _demo_docs_page %}</a>{% else %}</div>{% endif %}
+      {% if _demo_cats_page %}
+      <a href="{{ '/categories/' | relative_url }}" class="list-group-item list-group-item-action d-flex justify-content-between align-items-center">
+      {% else %}
+      <div class="list-group-item d-flex justify-content-between align-items-center">
+      {% endif %}
         <span><i class="bi bi-collection text-info me-2"></i>Categories</span>
         <span class="badge bg-info rounded-pill">{{ site.categories.size | default: "6" }}</span>
-      </a>
-      <a href="#" onclick="return false;" class="list-group-item list-group-item-action d-flex justify-content-between align-items-center">
+      {% if _demo_cats_page %}</a>{% else %}</div>{% endif %}
+      {% if _demo_tags_page %}
+      <a href="{{ '/tags/' | relative_url }}" class="list-group-item list-group-item-action d-flex justify-content-between align-items-center">
+      {% else %}
+      <div class="list-group-item d-flex justify-content-between align-items-center">
+      {% endif %}
         <span><i class="bi bi-tags text-warning me-2"></i>Tags</span>
         <span class="badge bg-warning text-dark rounded-pill">{{ site.tags.size | default: "24" }}</span>
-      </a>
+      {% if _demo_tags_page %}</a>{% else %}</div>{% endif %}
     </div>
   </div>
   <div class="col-md-6">

data/_includes/components/feature-card.html

@@ -19,6 +19,11 @@
   - compact  (bool)   : Compact mode — hides sub-features list (optional, default: false)
   - features_limit (int) : Max sub-features shown in the list (optional, default: 5)
 
+  Feature fields surfaced (from _data/features.yml): title, description,
+  features[], references (when show_refs), id, version, tags, docs, link, and
+  provenance (provenance.pr / provenance.commit / provenance.issue → GitHub
+  links built from site.github_user + site.repository_name).
+
   Usage:
     {% assign f = site.data.features.features | where: "id", "ZER0-001" | first %}
     {% include components/feature-card.html feature=f style="primary" icon="bi-bootstrap" icon_color="text-primary" %}
@@ -78,6 +83,16 @@
       <span class="badge bg-light text-dark">{{ tag }}</span>
       {% endfor %}
     </div>
+
+    {% if f.provenance %}
+    {% assign gh = "https://github.com/" | append: site.github_user | append: "/" | append: site.repository_name %}
+    <div class="mt-2 small text-muted feature-provenance">
+      <i class="bi bi-clock-history me-1" aria-hidden="true"></i>
+      {% if f.provenance.pr %}<a href="{{ gh }}/pull/{{ f.provenance.pr }}" class="text-decoration-none me-2">PR #{{ f.provenance.pr }}</a>{% endif %}
+      {% if f.provenance.commit %}<a href="{{ gh }}/commit/{{ f.provenance.commit }}" class="text-decoration-none me-2"><code>{{ f.provenance.commit }}</code></a>{% endif %}
+      {% if f.provenance.issue %}<a href="{{ gh }}/issues/{{ f.provenance.issue }}" class="text-decoration-none me-2">#{{ f.provenance.issue }}</a>{% endif %}
+    </div>
+    {% endif %}
   </div>
   {% if f.docs %}
   <div class="card-footer">

data/_includes/components/search-modal.html

@@ -2,19 +2,43 @@
   ===================================================================
   SEARCH MODAL - Site-wide Search Popup
   ===================================================================
-  
+
   File: search-modal.html
   Path: _includes/components/search-modal.html
   Purpose: Provide a modal search experience with keyboard shortcut support
-  
+
   Notes:
-  - Uses /sitemap/ for query-based search results
+  - Form action targets /sitemap/ when that page exists in the build;
+    falls back to /sitemap.xml if available, otherwise '#' (safe no-op).
+    JS (search-modal.js) always intercepts submit and keeps results
+    in-modal, so the action is only a no-JS fallback.  The gate here
+    prevents a dead link on remote-theme Pages builds that lack /sitemap/.
   - Keyboard shortcut handled by navigation keyboard module ("/")
   ===================================================================
 -->
 
 {%- assign ui_text = site.data.ui-text[site.locale] | default: site.data.ui-text.en -%}
 {%- assign search_placeholder = ui_text.search_placeholder_text | default: "Enter your search term..." -%}
+{%- comment -%}
+  Existence-gate the form action to /sitemap/ only when that page is present
+  in the build (mirroring the footer Quick Links guard, and the section-sidebar
+  /tags/ gate).  Remote-theme Pages consumers that haven't committed a /sitemap/
+  stub get a safe '#' fallback; the JS always intercepts submit anyway, so this
+  only affects the no-JS code path.
+{%- endcomment -%}
+{%- assign _search_sitemap_url  = "/sitemap/" -%}
+{%- assign _search_sitemap_page = site.html_pages | where: "url", _search_sitemap_url | first -%}
+{%- unless _search_sitemap_page -%}
+  {%- for col in site.collections -%}
+    {%- assign _search_sitemap_page = col.docs | where: "url", _search_sitemap_url | first -%}
+    {%- if _search_sitemap_page -%}{%- break -%}{%- endif -%}
+  {%- endfor -%}
+{%- endunless -%}
+{%- if _search_sitemap_page -%}
+  {%- assign _search_form_action = "/sitemap/" | relative_url -%}
+{%- else -%}
+  {%- assign _search_form_action = "#" -%}
+{%- endif -%}
 
 <div class="modal fade search-modal" id="siteSearchModal" tabindex="-1" aria-labelledby="siteSearchModalLabel" aria-hidden="true">
     <div class="modal-dialog modal-dialog-centered">
@@ -26,7 +50,7 @@
                 <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
             </div>
             <div class="modal-body">
-                <form action="{{ '/sitemap/' | relative_url }}" method="get" data-search-form>
+                <form action="{{ _search_form_action }}" method="get" data-search-form>
                     <label class="visually-hidden" for="site-search-input">Search</label>
                     <div class="input-group">
                         <span class="input-group-text">

data/_includes/components/zer0-env-var.html

@@ -57,6 +57,12 @@
         document.querySelector('#envTable tbody').appendChild(row);
     });
 
+    // Escape user-entered text before it is interpolated into innerHTML, so a
+    // key/value containing markup cannot inject script (DOM XSS).
+    const escapeHtml = (s) => String(s).replace(/[&<>"']/g, (c) => (
+        { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]
+    ));
+
     document.getElementById('submit').addEventListener('click', function() {
         const rows = document.querySelectorAll('#envTable tbody tr');
         let codeBlockText = '';
@@ -64,7 +70,7 @@
             const key = row.querySelector('td:nth-child(1) input').value;
             const value = row.querySelector('td:nth-child(2) input').value;
             sessionStorage.setItem(key, value);
-            codeBlockText += `<span class="nb">export </span><span class="nv">${key}</span><span class="o">=</span>${value}\n`;
+            codeBlockText += `<span class="nb">export </span><span class="nv">${escapeHtml(key)}</span><span class="o">=</span>${escapeHtml(value)}\n`;
         });
         document.getElementById('codeBlock').innerHTML = codeBlockText;
 

data/_includes/core/color-mode-init.html

@@ -0,0 +1,35 @@
+{%- comment -%}
+  Component:   color-mode-init
+  Path:        _includes/core/color-mode-init.html
+  Purpose:     Early inline script that applies data-bs-theme BEFORE Bootstrap CSS
+               loads, preventing FOUC (flash of unstyled/wrong-themed content).
+  Params:      none — reads data-color-mode-default from the <html> element,
+               which root.html sets from site.color_mode_default.
+  Depends on:  root.html (sets data-color-mode-default attribute server-side)
+  Notes:       Must be included BEFORE any Bootstrap CSS link tag. The script
+               is tiny, synchronous, and runs inline before the browser requests
+               external stylesheets, so the correct theme is already applied
+               when Bootstrap's [data-bs-theme] selectors are first evaluated.
+
+  Priority order (highest → lowest):
+    1. localStorage["theme"]    — user's explicit override via Appearance panel
+    2. data-color-mode-default  — site.color_mode_default config value
+    3. "auto" fallback          — resolves via prefers-color-scheme
+{%- endcomment -%}
+<script>
+(function () {
+  'use strict';
+  try {
+    var root = document.documentElement;
+    var configDefault = root.getAttribute('data-color-mode-default') || 'auto';
+    var stored = window.localStorage.getItem('theme');
+    var mode = stored || configDefault;
+    if (mode === 'auto') {
+      root.setAttribute('data-bs-theme',
+        window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
+    } else {
+      root.setAttribute('data-bs-theme', mode);
+    }
+  } catch (e) { /* localStorage / matchMedia unavailable — server-rendered value stands */ }
+})();
+</script>

data/_includes/core/head.html

@@ -127,6 +127,15 @@ window.MathJax = {
 <!-- CSS FRAMEWORKS AND LIBRARIES   -->
 <!-- ================================ -->
 
+<!-- ========================== -->
+<!-- COLOR MODE INIT (FOUC FIX) -->
+<!-- ========================== -->
+<!-- Must run BEFORE Bootstrap CSS so the correct data-bs-theme is applied
+     when [data-bs-theme=dark/light] selectors are first evaluated.
+     Reads site.color_mode_default (via data-color-mode-default attr on <html>)
+     and falls back to localStorage["theme"] for the user's explicit preference. -->
+{% include core/color-mode-init.html %}
+
 <!-- ========================== -->
 <!-- BOOTSTRAP 5 FRAMEWORK     -->
 <!-- ========================== -->

data/_includes/core/tokens-inline.html

@@ -35,6 +35,11 @@
 {%- endif -%}
 
 {%- comment -%}
+  NOTE: The data-bs-theme FOUC-prevention script lives in
+  _includes/core/color-mode-init.html (included from head.html BEFORE Bootstrap
+  CSS) so the correct theme is applied before any [data-bs-theme] selectors are
+  evaluated. Do not duplicate it here.
+
   Restore any user-saved Appearance overrides before paint to avoid a flash
   of the default palette. The Appearance panel (Track 6) writes JSON like
   {"primary":"#ff5722"} to localStorage["zer0-appearance"].

data/_layouts/author.html

@@ -68,10 +68,31 @@ hide_intro: true
 <!-- ========================== -->
 <!-- BREADCRUMB                 -->
 <!-- ========================== -->
+{%- comment -%}
+  Only link the /authors/ breadcrumb crumb when that index page actually exists
+  in the build. A pure remote-theme Pages consumer doesn't get the
+  plugin-generated /authors/ index, so rendering the link would produce a 404.
+  Mirror the existence guard used in _includes/navigation/breadcrumbs.html
+  and _includes/components/author-bio.html. See issue #204.
+{%- endcomment -%}
+{%- assign _authors_url = '/authors/' -%}
+{%- assign _authors_page = site.html_pages | where: "url", _authors_url | first -%}
+{%- unless _authors_page -%}
+  {%- for _col in site.collections -%}
+    {%- assign _authors_page = _col.docs | where: "url", _authors_url | first -%}
+    {%- if _authors_page -%}{%- break -%}{%- endif -%}
+  {%- endfor -%}
+{%- endunless -%}
 <nav aria-label="breadcrumb" class="mb-3">
   <ol class="breadcrumb">
     <li class="breadcrumb-item"><a href="{{ '/' | relative_url }}">Home</a></li>
-    <li class="breadcrumb-item"><a href="{{ '/authors/' | relative_url }}">Authors</a></li>
+    <li class="breadcrumb-item">
+      {%- if _authors_page -%}
+        <a href="{{ _authors_url | relative_url }}">Authors</a>
+      {%- else -%}
+        Authors
+      {%- endif -%}
+    </li>
     <li class="breadcrumb-item active" aria-current="page">{{ author_name }}</li>
   </ol>
 </nav>

data/_layouts/root.html

@@ -31,7 +31,21 @@
 -->
 
 <!doctype html>
-<html lang="{{ site.locale | slice: 0,2 | default: 'en' }}" class="no-js" data-bs-theme="dark" data-theme-skin="{{ site.theme_skin | default: 'dark' }}" data-zer0-bg="{{ site.theme_background.enabled | default: true }}">
+{%- comment -%}
+  Resolve the server-side data-bs-theme:
+    dark  → dark
+    light → light
+    auto  → dark  (inline script in tokens-inline.html corrects this before first paint)
+  We also store the raw config value in data-color-mode-default so the inline
+  script can read it without a Liquid evaluation.
+{%- endcomment -%}
+{%- assign _cm = site.color_mode_default | default: 'auto' -%}
+{%- if _cm == 'light' -%}
+  {%- assign _bs_theme = 'light' -%}
+{%- else -%}
+  {%- assign _bs_theme = 'dark' -%}
+{%- endif -%}
+<html lang="{{ site.locale | slice: 0,2 | default: 'en' }}" class="no-js" data-bs-theme="{{ _bs_theme }}" data-color-mode-default="{{ _cm }}" data-theme-skin="{{ site.theme_skin | default: 'dark' }}" data-zer0-bg="{{ site.theme_background.enabled | default: true }}">
     <head>
         <!-- =============================================== -->
         <!-- HEAD SECTION: Meta tags, styles, and SEO setup -->

data/scripts/bin/validate

@@ -413,6 +413,7 @@ classified_files = %w[
     _config_secrets_local.yml
     pages/_about/settings/_config.yml
     .github/ISSUE_TEMPLATE/config.yml
+    .issues/config.yml
 ]
 
 # T-018: the admin config page renders pages/_about/settings/_config.yml via
@@ -499,6 +500,19 @@ RUBY
     success "Navigation data is valid"
 }
 
+validate_features_registry() {
+    step "Validating feature registry (features.yml)..."
+
+    # Delegates to the shared canonical checker so this gate and the `features`
+    # test suite never drift. Hard-fails on master/_data drift, schema
+    # violations, stale references, and missing provenance; warns (until
+    # FEATURES_STRICT=1) on missing tests. See
+    # .github/instructions/features.instructions.md.
+    FEATURES_STRICT="${FEATURES_STRICT:-0}" ruby "$REPO_ROOT/scripts/validate-features.rb"
+
+    success "Feature registry is valid"
+}
+
 run_jekyll_build() {
     if [[ "$SKIP_JEKYLL" == "true" ]]; then
         warn "Skipping Jekyll build"
@@ -611,6 +625,9 @@ main() {
     validate_navigation_data
     echo ""
 
+    validate_features_registry
+    echo ""
+
     run_jekyll_build
     echo ""
 
@@ -627,7 +644,7 @@ main() {
     print_summary "Validation Complete" \
         "Repository files: pass" \
         "Version consistency: pass" \
-        "YAML, config contract, and navigation data: pass" \
+        "YAML, config contract, navigation data, and feature registry: pass" \
         "Jekyll build: $([[ "$SKIP_JEKYLL" == "true" ]] && echo skipped || echo pass)" \
         "Jekyll doctor: $([[ "$SKIP_DOCTOR" == "true" ]] && echo skipped || echo pass)" \
         "Compiled assets: $([[ "$SKIP_ASSETS" == "true" ]] && echo skipped || echo pass)" \

data/scripts/ci/classify_changes.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+"""
+classify_changes.py — the auto-merge smuggle guard.
+
+Reads a list of changed file paths (one per line on stdin, e.g. from
+`gh pr diff <n> --name-only`) and prints the distinct CATEGORIES present, one
+per line, from:
+
+  content   — pages/**, _data/{quests,navigation,...}, assets/** (the site)
+  infra     — .github/**, scripts/**, Dockerfile, docker-compose, Gemfile*, Makefile
+  config    — _config*.yml, _data/ai.yml, _data/brand/**, .cms/**, *.json config
+  data      — other _data/**
+
+The content auto-merge workflow refuses to merge any PR whose categories include
+anything other than `content` — so an `auto:content` PR can never quietly carry a
+workflow, dependency, brand-rule, or AI-config change to main without a human.
+Unknown paths classify as `infra` (fail safe — when unsure, require a human).
+
+The content category is deliberately broad (it includes theme files like
+`_layouts/**`, `_includes/**`, `_sass/**`). A caller that needs a TIGHTER scope
+than "any content" — e.g. the issue autopilot, whose resolver may only edit
+`pages/**`, `assets/**`, `_data/quests/**` — adds `--allow-globs` to require that
+every changed path also matches one of the given globs. `--content-only` and
+`--allow-globs` compose: both must pass.
+
+Usage:
+    gh pr diff 123 --name-only | python3 scripts/ci/classify_changes.py
+    python3 scripts/ci/classify_changes.py a.md b.yml      # paths as args
+    ... | python3 scripts/ci/classify_changes.py --content-only   # exit 0 iff content-only
+    ... | python3 scripts/ci/classify_changes.py --content-only \
+              --allow-globs 'pages/**' 'assets/**' '_data/quests/**'  # tighter scope
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from fnmatch import fnmatch
+
+# Order matters: first matching rule wins. Most specific first.
+# THEME REPO: the theme itself (_layouts/_includes/_sass/_plugins/lib/assets) is
+# the PRODUCT, so it is `infra` (never auto-mergeable) — only docs/pages Markdown
+# counts as `content`. This is the key difference from a content site.
+RULES = [
+    ("config", [
+        "_config.yml", "_config*.yml",
+        "_data/ai.yml",
+        ".github/config/*", ".github/config/**",
+        "frontmatter.json", ".frontmatter/*", ".frontmatter/**",
+    ]),
+    ("infra", [
+        ".github/*", ".github/**",
+        ".claude/*", ".claude/**",
+        "scripts/*", "scripts/**",
+        "lib/*", "lib/**",
+        "_layouts/*", "_layouts/**", "_includes/*", "_includes/**",
+        "_sass/*", "_sass/**", "_plugins/*", "_plugins/**",
+        "assets/*", "assets/**",
+        "test/*", "test/**", "templates/*", "templates/**",
+        "Dockerfile", "docker-compose*.yml", "docker-compose*.yaml",
+        "Gemfile", "Gemfile.lock", "Makefile", "Rakefile", "install.sh",
+        "*.gemspec", "package.json", "package-lock.json",
+    ]),
+    ("content", [
+        "docs/*", "docs/**",
+        "pages/*", "pages/**",
+        "index.html", "index.md", "*.md",
+    ]),
+]
+FALLBACK = "infra"   # unknown -> require a human (fail safe)
+
+
+def classify_one(path: str) -> str:
+    p = path.strip()
+    if not p:
+        return ""
+    for category, patterns in RULES:
+        for pat in patterns:
+            if fnmatch(p, pat):
+                return category
+    return "data" if p.startswith("_data/") else FALLBACK
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="Classify changed paths for the auto-merge guard.")
+    ap.add_argument("paths", nargs="*", help="paths (else read stdin, one per line)")
+    ap.add_argument("--content-only", action="store_true",
+                    help="exit 0 iff every path is content; exit 1 otherwise")
+    ap.add_argument("--allow-globs", nargs="*", default=None, metavar="GLOB",
+                    help="require every changed path to match one of these globs "
+                         "(tighter than --content-only); composes with it")
+    args = ap.parse_args(argv)
+
+    raw = [line for line in (args.paths if args.paths else sys.stdin.read().splitlines())
+           if line.strip()]
+    cats = []
+    for line in raw:
+        c = classify_one(line)
+        if c and c not in cats:
+            cats.append(c)
+
+    # When either gate is requested, ALL requested gates must pass (exit 0/1).
+    if args.content_only or args.allow_globs is not None:
+        ok = True
+        if args.content_only:
+            content_ok = bool(cats) and cats == ["content"]
+            if not content_ok:
+                others = [c for c in cats if c != "content"] or ["<empty diff>"]
+                print(f"not content-only: also touches {', '.join(others)}", file=sys.stderr)
+            ok = ok and content_ok
+        if args.allow_globs is not None:
+            offenders = [p.strip() for p in raw
+                         if not any(fnmatch(p.strip(), g) for g in args.allow_globs)]
+            # An empty diff is never "allowed" — there is nothing legitimate to merge.
+            if not raw:
+                print("no changed paths — refusing (nothing to merge)", file=sys.stderr)
+                ok = False
+            elif offenders:
+                print(f"outside allowed scope ({', '.join(args.allow_globs)}): "
+                      f"{', '.join(offenders)}", file=sys.stderr)
+                ok = False
+        return 0 if ok else 1
+
+    for c in cats:
+        print(c)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())