jekyll-theme-zer0 1.27.0 → 1.29.0

data/scripts/install/config.sh

@@ -0,0 +1,167 @@
+#!/bin/bash
+# =============================================================================
+# scripts/install/config.sh — User config-file layer
+# =============================================================================
+# Lets a site persist its installer choices in a small YAML file instead of
+# re-typing flags every run. Discovered files are merged low→high precedence:
+#
+#   1. ~/.config/zer0/install.yml        (user-global defaults)
+#   2. <target>/zer0.install.yml         (project-local)
+#   3. <target>/.zer0/config.yml         (project-local, hidden)
+#   4. $ZER0_CONFIG  /  --config FILE    (explicit — wins over the rest)
+#
+# In the plan pipeline this sits between profile defaults and env/flag
+# overrides:  defaults < profile < CONFIG FILE < env vars < CLI flags.
+#
+# Recognised keys (nested or flat/dotted both work):
+#   profile
+#   site.title|description|author|email|url|timezone|locale
+#   github.user|repo|pages_branch|enable_pages
+#   theme.source|version
+#   deploy            (scalar or list → space-joined)
+#   agents            (scalar or list → space-joined)
+#   tasks             (scalar or list → space-joined)
+#   ai.provider       (auto|claude-cli|anthropic|openai|none)
+#   ai.model
+#
+# API keys are deliberately NOT read from config files — they stay in the
+# environment only (see ai/client.sh).
+#
+# Bash 3.2 compatible. No `declare -A`, no `set -euo pipefail` here.
+# =============================================================================
+[[ -n "${_HAS_CONFIG_LIB:-}" ]] && return 0
+_HAS_CONFIG_LIB=1
+
+# ---------------------------------------------------------------------------
+# config_discover TARGET_DIR → print existing config files, low→high priority.
+# ---------------------------------------------------------------------------
+config_discover() {
+    local target="${1:-$(pwd)}"
+    local f
+    for f in \
+        "${HOME:-/nonexistent}/.config/zer0/install.yml" \
+        "${target}/zer0.install.yml" \
+        "${target}/zer0.install.yaml" \
+        "${target}/.zer0/config.yml" \
+        "${_FLAG_CONFIG:-}" \
+        "${ZER0_CONFIG:-}" ; do
+        [[ -n "$f" && -f "$f" ]] && printf '%s\n' "$f"
+    done
+}
+
+# ---------------------------------------------------------------------------
+# _config_flatten FILE → emit `key=value` for a small YAML subset:
+#   - top-level scalars           foo: bar          → foo=bar
+#   - one level of nested maps     site:\n  title: x → site.title=x
+#   - block lists                  deploy:\n  - a    → deploy=a b
+#   - inline flow lists            deploy: [a, b]    → deploy=a b
+# Quotes and inline comments are stripped. Not a full YAML parser — just
+# enough for installer config, mirroring plan.sh's awk profile reader.
+# ---------------------------------------------------------------------------
+_config_flatten() {
+    local file="$1"
+    [[ -f "$file" ]] || return 0
+    awk '
+        function strip(s) {
+            sub(/[[:space:]]*#.*$/, "", s)               # trailing comment
+            sub(/^[[:space:]]+/, "", s); sub(/[[:space:]]+$/, "", s)
+            gsub(/^["'"'"']|["'"'"']$/, "", s)           # surrounding quotes
+            return s
+        }
+        # blank / comment lines
+        /^[[:space:]]*$/ { next }
+        /^[[:space:]]*#/ { next }
+        {
+            indent = 0
+            tmp = $0
+            while (substr(tmp,1,1) == " ") { indent++; tmp = substr(tmp,2) }
+        }
+        # list item under the current parent key
+        indent > 0 && tmp ~ /^-[[:space:]]+/ {
+            if (listkey != "") {
+                item = tmp; sub(/^-[[:space:]]+/, "", item); item = strip(item)
+                vals[listkey] = (vals[listkey] == "" ? item : vals[listkey] " " item)
+            }
+            next
+        }
+        # key: value  (any depth we care about is 0 or 1)
+        match(tmp, /^[A-Za-z0-9_.-]+[[:space:]]*:/) {
+            key = tmp; sub(/[[:space:]]*:.*$/, "", key)
+            val = tmp; sub(/^[A-Za-z0-9_.-]+[[:space:]]*:/, "", val); val = strip(val)
+
+            if (indent == 0) {
+                parent = key
+                listkey = ""
+                if (val == "") { listkey = key; next }        # map/list header
+                # inline flow list?  key: [a, b, c]
+                if (val ~ /^\[.*\]$/) {
+                    gsub(/^\[|\]$/, "", val); gsub(/[[:space:],]+/, " ", val)
+                    val = strip(val)
+                }
+                print key "=" val
+            } else {
+                # nested child of the last top-level parent
+                if (parent != "") print parent "." key "=" val
+            }
+            next
+        }
+        END {
+            for (k in vals) print k "=" vals[k]
+        }
+    ' "$file"
+}
+
+# ---------------------------------------------------------------------------
+# config_apply_file FILE → map recognised keys onto SPEC_* globals + AI env.
+# ---------------------------------------------------------------------------
+config_apply_file() {
+    local file="$1"
+    [[ -f "$file" ]] || return 0
+    log_debug "config: loading ${file}"
+
+    local line key val
+    while IFS= read -r line; do
+        key="${line%%=*}"
+        val="${line#*=}"
+        [[ -z "$key" || "$key" == "$line" ]] && continue
+        case "$key" in
+            profile)              SPEC_PROFILE="$val" ;;
+            site.title|site_title)             SPEC_SITE_TITLE="$val" ;;
+            site.description|site_description) SPEC_SITE_DESCRIPTION="$val" ;;
+            site.author|site_author)           SPEC_SITE_AUTHOR="$val" ;;
+            site.email|site_email)             SPEC_SITE_EMAIL="$val" ;;
+            site.url|site_url)                 SPEC_SITE_URL="$val" ;;
+            site.timezone|site_timezone)       SPEC_SITE_TIMEZONE="$val" ;;
+            site.locale|site_locale)           SPEC_SITE_LOCALE="$val" ;;
+            github.user|github_user)           SPEC_GITHUB_USER="$val" ;;
+            github.repo|github_repo)           SPEC_GITHUB_REPO="$val" ;;
+            github.pages_branch)               SPEC_GITHUB_PAGES_BRANCH="$val" ;;
+            github.enable_pages)               SPEC_GITHUB_ENABLE_PAGES="$val" ;;
+            theme.source|theme_source)         SPEC_THEME_SOURCE="$val" ;;
+            theme.version|theme_version)       SPEC_THEME_VERSION="$val" ;;
+            deploy|deploy_targets)             SPEC_DEPLOY="$val" ;;
+            agents|agent_files)                SPEC_AGENTS="$val" ;;
+            tasks)                             SPEC_TASKS="$val" ;;
+            ai.provider|ai_provider)
+                SPEC_AI_PROVIDER="$val"
+                export ZER0_AI_PROVIDER="${ZER0_AI_PROVIDER:-$val}" ;;
+            ai.model|ai_model)
+                SPEC_AI_MODEL="$val"
+                export ZER0_AI_MODEL="${ZER0_AI_MODEL:-$val}" ;;
+            *) log_debug "config: ignoring unknown key '${key}'" ;;
+        esac
+    done < <(_config_flatten "$file")
+    return 0
+}
+
+# ---------------------------------------------------------------------------
+# config_load TARGET_DIR → apply every discovered config file in order.
+# ---------------------------------------------------------------------------
+config_load() {
+    local target="${1:-$(pwd)}"
+    local f
+    while IFS= read -r f; do
+        [[ -n "$f" ]] && config_apply_file "$f"
+    done < <(config_discover "$target")
+    return 0
+}

data/scripts/install/doctor.sh

@@ -118,6 +118,43 @@ doctor_check_gh() {
     _doctor_pass "GitHub CLI $ghver"
 }
 
+# ---------------------------------------------------------------------------
+# doctor_check_ai — report which AI provider (if any) will serve wizard/
+# suggest/diagnose. Warn-only: AI is always opt-in and never blocks install.
+# ---------------------------------------------------------------------------
+doctor_check_ai() {
+    if [[ "$(type -t ai_client_provider)" != "function" ]]; then
+        local _d
+        _d="${_CLI_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" 2>/dev/null && pwd)}"
+        [[ -f "${_d}/ai/client.sh" ]] && source "${_d}/ai/client.sh"
+    fi
+    if [[ "$(type -t ai_client_provider)" != "function" ]]; then
+        _doctor_warn "AI: client module unavailable (wizard/suggest/diagnose disabled)"
+        return 0
+    fi
+
+    if [[ "${ZER0_NO_AI:-0}" == "1" ]]; then
+        _doctor_pass "AI: disabled via ZER0_NO_AI (rule-based fallbacks only)"
+        return 0
+    fi
+    case "${ZER0_AI_PROVIDER:-}" in
+        none|off|disabled)
+            _doctor_pass "AI: disabled by choice (rule-based fallbacks only)"
+            return 0 ;;
+    esac
+
+    local provider
+    provider="$(ai_client_provider)"
+    if [[ "$provider" == "none" ]] || ! ai_client_available; then
+        _doctor_warn "AI: no provider available — install the 'claude' CLI (Claude Code OAuth), or set CLAUDE_CODE_OAUTH_TOKEN / ANTHROPIC_API_KEY / OPENAI_API_KEY"
+        return 0
+    fi
+
+    local model
+    model="$(ai_client_model "$provider")"
+    _doctor_pass "AI: ${provider} via $(ai_client_auth_source)${model:+ (model ${model})}"
+}
+
 # ---------------------------------------------------------------------------
 # doctor_check_writable TARGET_DIR
 # ---------------------------------------------------------------------------
@@ -155,6 +192,7 @@ doctor_run() {
     doctor_check_docker
     doctor_check_git      || failures=$(( failures + 1 ))
     doctor_check_gh
+    doctor_check_ai
     [[ -n "$target" ]] && { doctor_check_writable "$target" || failures=$(( failures + 1 )); }
 
     if [[ $failures -eq 0 ]]; then

data/scripts/install/plan.sh

@@ -144,6 +144,8 @@ plan_apply_flags() {
     [[ -n "${_FLAG_DEPLOY:-}" ]]      && SPEC_DEPLOY="$_FLAG_DEPLOY"
     [[ -n "${_FLAG_AGENTS:-}" ]]      && SPEC_AGENTS="$_FLAG_AGENTS"
     [[ -n "${_FLAG_TASKS:-}" ]]       && SPEC_TASKS="$_FLAG_TASKS"
+    [[ -n "${_FLAG_AI_PROVIDER:-}" ]] && SPEC_AI_PROVIDER="$_FLAG_AI_PROVIDER"
+    [[ -n "${_FLAG_AI_MODEL:-}" ]]    && SPEC_AI_MODEL="$_FLAG_AI_MODEL"
 
     # Booleans — flags are set to "1" when present
     [[ "${_FLAG_DRY_RUN:-0}" == "1" ]]     && SPEC_OPT_DRY_RUN=true
@@ -231,12 +233,19 @@ plan_build() {
     # Layer 1: Profile defaults
     [[ -n "$profile_file" ]] && plan_load_profile "$profile_file"
 
+    # Layer 1.5: User config file(s) — override profile, sit below env/flags.
+    if [[ "$(type -t config_load)" == "function" ]]; then
+        config_load "$target_dir"
+    fi
+
     # Layer 2: Environment variable overrides (ZER0_SITE_* etc.)
     [[ -n "${ZER0_SITE_TITLE:-}" ]]  && SPEC_SITE_TITLE="$ZER0_SITE_TITLE"
     [[ -n "${ZER0_SITE_AUTHOR:-}" ]] && SPEC_SITE_AUTHOR="$ZER0_SITE_AUTHOR"
     [[ -n "${ZER0_SITE_EMAIL:-}" ]]  && SPEC_SITE_EMAIL="$ZER0_SITE_EMAIL"
     [[ -n "${ZER0_GITHUB_USER:-}" ]] && SPEC_GITHUB_USER="$ZER0_GITHUB_USER"
     [[ -n "${ZER0_GITHUB_REPO:-}" ]] && SPEC_GITHUB_REPO="$ZER0_GITHUB_REPO"
+    [[ -n "${ZER0_AI_PROVIDER:-}" ]] && SPEC_AI_PROVIDER="$ZER0_AI_PROVIDER"
+    [[ -n "${ZER0_AI_MODEL:-}" ]]    && SPEC_AI_MODEL="$ZER0_AI_MODEL"
 
     # Layer 3: CLI flags (highest priority)
     plan_apply_flags
@@ -271,6 +280,7 @@ plan_build() {
         SPEC_OPT_DRY_RUN SPEC_OPT_FORCE SPEC_OPT_BACKUP \
         SPEC_OPT_NON_INTERACTIVE SPEC_OPT_OUTPUT SPEC_OPT_AUTO_ACCEPT \
         SPEC_OPT_SKIP_DOCTOR SPEC_OPT_VERBOSE \
+        SPEC_AI_PROVIDER SPEC_AI_MODEL \
         SITE_TITLE SITE_DESCRIPTION SITE_AUTHOR SITE_EMAIL SITE_URL \
         SITE_TIMEZONE SITE_LOCALE GITHUB_USER GITHUB_REPO \
         GITHUB_PAGES_BRANCH THEME_SOURCE REPOSITORY_NAME INSTALL_PROFILE

data/scripts/install/spec.sh

@@ -85,7 +85,7 @@ spec_default() {
   },
   "ai": {
     "used": false,
-    "provider": "openai",
+    "provider": "auto",
     "model": "",
     "tokens_estimated": 0,
     "spec_hash": ""
@@ -108,10 +108,18 @@ spec_write() {
     local out_file="$1"
     local dry_run="${_FS_DRY_RUN:-0}"
 
-    # Build tasks array from space-separated SPEC_TASKS
+    # Build tasks array from space-separated SPEC_TASKS.
+    # Distinguish UNSET (→ default task list) from EMPTY (→ [], e.g. a
+    # deploy-only run). Using `${SPEC_TASKS:-default}` here would turn an
+    # intentional empty list back into the full default and clobber content.
     local tasks_json=""
-    local t
-    for t in ${SPEC_TASKS:-config gemfile docker pages nav data gitignore readme marker}; do
+    local t _tasks_src
+    if [[ -z "${SPEC_TASKS+set}" ]]; then
+        _tasks_src="config gemfile docker pages nav data gitignore readme marker"
+    else
+        _tasks_src="${SPEC_TASKS}"
+    fi
+    for t in ${_tasks_src}; do
         tasks_json="${tasks_json}\"${t}\","
     done
     tasks_json="[${tasks_json%,}]"
@@ -168,7 +176,7 @@ spec_write() {
   },
   "ai": {
     "used": ${SPEC_AI_USED:-false},
-    "provider": "${SPEC_AI_PROVIDER:-openai}",
+    "provider": "${SPEC_AI_PROVIDER:-auto}",
     "model": "${SPEC_AI_MODEL:-}",
     "tokens_estimated": ${SPEC_AI_TOKENS:-0},
     "spec_hash": ""
@@ -248,7 +256,7 @@ _spec_read_jq() {
     SPEC_OPT_SKIP_DOCTOR=$(jq -r '.options.skip_doctor // false' "$f")
     SPEC_OPT_VERBOSE=$(jq -r '.options.verbose // false' "$f")
     SPEC_AI_USED=$(jq -r '.ai.used // false' "$f")
-    SPEC_AI_PROVIDER=$(jq -r '.ai.provider // "openai"' "$f")
+    SPEC_AI_PROVIDER=$(jq -r '.ai.provider // "auto"' "$f")
     SPEC_AI_MODEL=$(jq -r '.ai.model // ""' "$f")
     SPEC_AI_TOKENS=$(jq -r '.ai.tokens_estimated // 0' "$f")
     SPEC_SCRAPE_SOURCE_URL=$(jq -r '.scrape.source_url // ""' "$f")
@@ -369,7 +377,7 @@ _spec_read_awk() {
     SPEC_OPT_SKIP_DOCTOR="${SPEC_OPT_SKIP_DOCTOR:-false}"
     SPEC_OPT_VERBOSE="${SPEC_OPT_VERBOSE:-false}"
     SPEC_AI_USED="${SPEC_AI_USED:-false}"
-    SPEC_AI_PROVIDER="${SPEC_AI_PROVIDER:-openai}"
+    SPEC_AI_PROVIDER="${SPEC_AI_PROVIDER:-auto}"
     SPEC_AI_MODEL="${SPEC_AI_MODEL:-}"
     SPEC_AI_TOKENS="${SPEC_AI_TOKENS:-0}"
     SPEC_SCRAPE_SOURCE_URL="${SPEC_SCRAPE_SOURCE_URL:-$(awk '/"source_url"/ { gsub(/.*"source_url"[[:space:]]*:[[:space:]]*"/, ""); gsub(/".*/, ""); print; exit }' "$f" 2>/dev/null)}"

data/scripts/install/template.sh

@@ -61,6 +61,7 @@ tmpl_render() {
         -e "s|{{THEME_DISPLAY_NAME}}|${THEME_DISPLAY_NAME:-Zer0-Mistakes}|g" \
         -e "s|{{THEME_VERSION}}|${THEME_VERSION:-}|g" \
         -e "s|{{THEME_SOURCE}}|${THEME_SOURCE:-gem}|g" \
+        -e "s|{{THEME_REMOTE}}|${THEME_REMOTE:-bamr87/zer0-mistakes}|g" \
         -e "s|{{GITHUB_USER}}|${GITHUB_USER:-}|g" \
         -e "s|{{FORK_GITHUB_USER}}|${GITHUB_USER:-}|g" \
         -e "s|{{GITHUB_REPO}}|${GITHUB_REPO:-}|g" \
@@ -72,6 +73,7 @@ tmpl_render() {
         -e "s|{{REMOTE_BRANCH}}|${REMOTE_BRANCH:-${GITHUB_PAGES_BRANCH:-gh-pages}}|g" \
         -e "s|{{REPOSITORY_NAME}}|${REPOSITORY_NAME:-${GITHUB_REPO:-my-site}}|g" \
         -e "s|{{SITE_TITLE}}|${SITE_TITLE:-My Jekyll Site}|g" \
+        -e "s|{{SITE_NAME}}|${SITE_TITLE:-My Jekyll Site}|g" \
         -e "s|{{SITE_DESCRIPTION}}|${SITE_DESCRIPTION:-A Jekyll site built with zer0-mistakes}|g" \
         -e "s|{{SITE_AUTHOR}}|${SITE_AUTHOR:-Site Author}|g" \
         -e "s|{{SITE_EMAIL}}|${SITE_EMAIL:-}|g" \
@@ -87,6 +89,8 @@ tmpl_render() {
         -e "s|{{COMMONMARKER_MACOS_VERSION}}|${COMMONMARKER_MACOS_VERSION:-~> 0.23}|g" \
         -e "s|{{GITHUB_PAGES_MAX_VERSION}}|${GITHUB_PAGES_MAX_VERSION:-232}|g" \
         -e "s|{{RUBY_MIN_VERSION_MACOS}}|${RUBY_MIN_VERSION_MACOS:-2.6.0}|g" \
+        -e "s|{{DEFAULT_BRANCH}}|${DEFAULT_BRANCH:-main}|g" \
+        -e "s|{{RUBY_VERSION}}|${RUBY_VERSION:-3.3}|g" \
         -e "s|{{INSTALL_PROFILE}}|${INSTALL_PROFILE:-default}|g" \
         -e "s|{{INSTALL_MODE}}|${INSTALL_MODE:-full}|g" \
         -e "s|{{CURRENT_DATE}}|$(date +%Y-%m-%d)|g" \

data/scripts/lib/audit.sh

@@ -205,13 +205,45 @@ detect_consumer_mode() {
         return
     fi
 
-    if grep -qE '^remote_theme:' "$config"; then
+    # Match a top-level `remote_theme` key. The whitespace class before the
+    # colon is load-bearing: most fleet consumers write column-aligned YAML
+    # (`remote_theme             : "bamr87/zer0-mistakes"`), which a bare
+    # `^remote_theme:` never matches — every one of them was silently
+    # misreported as gem mode, skipping the plugin checks entirely.
+    # `|| true` keeps a no-match grep from tripping the caller's `set -o pipefail`.
+    local line value
+    line=$(grep -m1 -E '^remote_theme[[:space:]]*:' "$config" 2>/dev/null || true)
+    value=$(printf '%s' "$line" \
+            | sed -E 's/^remote_theme[[:space:]]*:[[:space:]]*//; s/[[:space:]]*(#.*)?$//; s/^"(.*)"$/\1/; s/^'\''(.*)'\''$/\1/')
+
+    # `remote_theme: false` (or an empty value) is how a consumer turns the
+    # remote theme OFF and resolves the theme as a gem instead.
+    if [[ -n "$value" && "$value" != "false" ]]; then
         echo "remote_theme"
     else
         echo "gem"
     fi
 }
 
+# detect_consumer_source <consumer_root>
+# Echoes the Jekyll `source:` value from _config.yml (relative path), or empty.
+#
+# Jekyll's `source:` relocates the whole site tree — zer0-pages keeps every
+# theme-shadowing file under `pages/`. Auditing the repo root there reports a
+# falsely clean "0 overrides, 0 unique files"; the real surface only appears
+# when the scan follows `source:`.
+detect_consumer_source() {
+    local consumer_root="$1"
+    local config="$consumer_root/_config.yml"
+
+    [[ -f "$config" ]] || return 0
+
+    local line
+    line=$(grep -m1 -E '^source[[:space:]]*:' "$config" 2>/dev/null || true)
+    printf '%s' "$line" \
+        | sed -E 's/^source[[:space:]]*:[[:space:]]*//; s/[[:space:]]*(#.*)?$//; s/^"(.*)"$/\1/; s/^'\''(.*)'\''$/\1/; s#^\./##; s#/$##'
+}
+
 # ---------------------------------------------------------------------------
 # Output helpers
 # ---------------------------------------------------------------------------
@@ -277,7 +309,15 @@ print_classification() {
                 echo "::notice file=$relpath::OPTIONAL_PLUGIN (not required)" ;;
         esac
     elif [[ "$format" == "json" ]]; then
-        echo "  {\"path\":\"$relpath\",\"status\":\"$classification\"},"
+        # Separator goes BEFORE each entry but the first, so the array never
+        # ends on a dangling comma. Emitting a trailing comma per entry (the
+        # previous behaviour) produced `...},\n]}` — which no JSON parser
+        # accepts, making --format json unusable for any CI consumer.
+        if [[ "${JSON_ENTRY_EMITTED:-0}" == "1" ]]; then
+            printf ',\n'
+        fi
+        JSON_ENTRY_EMITTED=1
+        printf '  {"path":"%s","status":"%s"}' "$relpath" "$classification"
     else
         echo -e "${color}[$classification]${NC} $relpath"
     fi

data/scripts/lint-liquid-raw.rb

@@ -0,0 +1,137 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# ---------------------------------------------------------------------------
+# lint-liquid-raw — guard the Markdown the Pages build renders through Liquid
+#
+# `github-pages` ships jekyll-optional-front-matter, so EVERY non-excluded
+# Markdown file in the repo becomes a page — CHANGELOG.md and the
+# _design-system/ mirror included — and every one of them is run through Liquid
+# before Markdown. Two failure modes follow, and neither is loud:
+#
+#   1. An unbalanced `{% raw %}`. Liquid's raw block swallows everything up to
+#      the FIRST `{% endraw %}`, so a stray opener silently eats the rest of the
+#      document. CHANGELOG.md carried one that consumed 945 lines while the
+#      build stayed green.
+#
+#   2. A literal `{% raw %}` / `{% endraw %}` written as documentation prose.
+#      It reads like text but parses as a tag, which is how (1) happens. To show
+#      the tag, escape it: `{% raw %}{% raw %}{% endraw %}`.
+#
+# A Liquid *syntax* error (e.g. `{{…}}`) is caught by the Pages workflow, which
+# fails on "Liquid Warning" in the build output. This script catches the class
+# the build cannot report, because swallowed text is not an error to Liquid.
+#
+# Usage:
+#   scripts/lint-liquid-raw.rb            # scan the rendered Markdown surface
+#   scripts/lint-liquid-raw.rb PATH...    # scan specific files
+#   scripts/lint-liquid-raw.rb --verbose  # list every file scanned
+# ---------------------------------------------------------------------------
+
+ROOT = File.expand_path('..', __dir__)
+TAG = /\{%-?\s*(raw|endraw)\s*-?%\}/.freeze
+
+# The escape form: a raw block whose entire body is one raw/endraw tag, which
+# is how you render the tag as text. Blanked before scanning so the literal it
+# carries is not mistaken for a real tag.
+ESCAPED = /\{%-?\s*raw\s*-?%\}\{%-?\s*(?:raw|endraw)\s*-?%\}\{%-?\s*endraw\s*-?%\}/.freeze
+
+# Directories Jekyll never reads, plus the ones _config.yml excludes. Kept in
+# sync with the `exclude:` list; a path missing here only costs a false
+# positive, never a missed one.
+SKIP_DIRS = %w[
+  .git .github .claude .cursor .devcontainer .frontmatter .vscode .obsidian
+  .jekyll-cache .sass-cache _site node_modules vendor pkg logs
+  docs scripts templates test tests examples submodules gemfiles docker lib
+].freeze
+
+# True when `pos` sits inside a single-backtick code span: an odd number of
+# backtick runs precede it on its own line.
+def in_code_span?(text, pos)
+  bol = text.rindex("\n", pos - 1)
+  line = text[(bol ? bol + 1 : 0)...pos]
+  line.scan(/`+/).size.odd?
+end
+
+def scan(path)
+  # Blank the escape form (keeping byte offsets and newlines) so the literal
+  # tag it renders is not read as a tag itself.
+  text = File.read(path, encoding: 'UTF-8')
+             .gsub(ESCAPED) { |m| ' ' * m.length }
+  problems = []
+  in_raw = false
+  opened_at = nil
+  opened_in_span = false
+
+  text.to_enum(:scan, TAG).each do
+    match = Regexp.last_match
+    line = text[0, match.begin(0)].count("\n") + 1
+    if in_raw
+      # Inside a raw block every tag is literal text — nothing to check.
+      if match[1] == 'endraw'
+        if opened_in_span && line != opened_at
+          problems << "#{path}:#{opened_at}: `{% raw %}` inside a code span " \
+                      "opens a block that only closes at line #{line} — " \
+                      'escape it to show the tag as text'
+        end
+        in_raw = false
+        opened_at = nil
+        opened_in_span = false
+      end
+      next
+    end
+
+    if match[1] == 'raw'
+      in_raw = true
+      opened_at = line
+      # `{% raw %}` inside an inline code span is the documentation-mention
+      # trap: it reads as text but opens a real block. Legitimate inline use
+      # (`{% raw %}{{ x }}{% endraw %}`) closes on the same line; a mention
+      # does not, and swallows everything up to the next `{% endraw %}`.
+      opened_in_span = in_code_span?(text, match.begin(0))
+    else
+      problems << "#{path}:#{line}: `{% endraw %}` with no matching `{% raw %}`"
+    end
+  end
+
+  if in_raw
+    problems << "#{path}:#{opened_at}: `{% raw %}` is never closed — " \
+                'Liquid will swallow the rest of the file'
+  end
+  problems
+rescue ArgumentError, Encoding::InvalidByteSequenceError => e
+  ["#{path}: could not read as UTF-8 (#{e.class})"]
+end
+
+def markdown_files
+  Dir.chdir(ROOT) do
+    Dir.glob('**/*.{md,markdown}', File::FNM_DOTMATCH).reject do |p|
+      p.split(File::SEPARATOR).any? { |seg| SKIP_DIRS.include?(seg) }
+    end.sort
+  end
+end
+
+verbose = ARGV.delete('--verbose')
+targets = ARGV.empty? ? markdown_files : ARGV
+
+problems = []
+Dir.chdir(ROOT) do
+  targets.each do |path|
+    next unless File.file?(path)
+
+    warn "  scanning #{path}" if verbose
+    problems.concat(scan(path))
+  end
+end
+
+if problems.empty?
+  puts "✓ lint-liquid-raw: #{targets.size} Markdown files, all " \
+       '`{% raw %}` blocks balanced'
+  exit 0
+end
+
+warn '✗ lint-liquid-raw: unbalanced Liquid raw blocks'
+problems.each { |p| warn "  #{p}" }
+warn ''
+warn 'To display a literal tag, escape it: `{% raw %}{% raw %}{% endraw %}`'
+exit 1