@soleur/opencode 0.0.0-stage → 1.0.0

package/skills/seo-aeo/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: seo-aeo
+description: "This skill should be used when auditing, fixing, or validating SEO and AEO (AI Engine Optimization) for Eleventy documentation sites. It provides sub-commands for running audits, applying fixes, and validating build output."
+---
+
+<!-- soleur-cloud-mode:start -->
+**Cloud Mode (Devin):** before pipeline work run `bash "${CLAUDE_PLUGIN_ROOT}/scripts/cloud-detect.sh"`. If `CLAUDE_PLUGIN_ROOT` is unset (cloud exec shells do not export it), resolve the root by IDENTITY, never by script basename: for `d` in `"$HOME/.local/share/devin/cli/plugins/cache"` and `/opt/.devin/plugins`, skip unless `[ -d "$d" ]`, then `MANIFEST="$(find "$d" -path '*/.claude-plugin/plugin.json' -exec grep -l '"name"[[:space:]]*:[[:space:]]*"soleur"' {} + 2>/dev/null | head -1)"`, `ROOT="${MANIFEST%/.claude-plugin/plugin.json}"` — one resolution, two consumers: `$ROOT/scripts/cloud-detect.sh` and `$ROOT/scripts/precommit-guard.sh`. (Shape check, not authentication: a planted `{"name":"soleur"}` dir passes — ADR-179 A11.) `local` or `not-local:no-devin-env` proceeds normally; any other `not-local:<reason>` applies `<plugin-root>/devin/INSTRUCTIONS.md` §Cloud Mode: emit the `--banner`, fan out sequentially with `Reviewed-Coverage: sequential-fallback` disclosure (never claim an independent review ran), `message_user` ack before any secrets read or production mutation, and run `precommit-guard.sh` before any `git commit` — hooks do not fire in cloud.
+<!-- soleur-cloud-mode:end -->
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+# SEO & AEO for Eleventy Docs
+
+Audit, fix, and validate SEO and AEO (AI Engine Optimization) for Eleventy documentation sites. This skill routes to sub-commands for analysis, remediation, and CI validation.
+
+## Sub-commands
+
+| Command | Description |
+|---------|-------------|
+| `seo-aeo audit` | Audit the site for SEO/AEO issues and produce a report |
+| `seo-aeo fix` | Analyze gaps and apply fixes to source files |
+| `seo-aeo validate` | Run the validation script against built output |
+
+If no sub-command is provided, display the table above and ask which sub-command to run.
+
+---
+
+## Phase 0: Prerequisites
+
+<critical_sequence>
+
+Before executing any sub-command, verify the Eleventy site structure exists.
+
+**Required: Eleventy config**
+
+```bash
+if [[ ! -f "eleventy.config.js" ]] && [[ ! -f ".eleventy.js" ]]; then
+  echo "No Eleventy config found. This skill works with Eleventy documentation sites."
+  # Stop execution
+fi
+```
+
+**Required for validate: Built output**
+
+The `validate` sub-command requires a built `_site/` directory. If missing:
+
+> No `_site/` directory found. Run `npx @11ty/eleventy` first, then re-run validate.
+
+</critical_sequence>
+
+---
+
+## Sub-command: audit
+
+Run a comprehensive SEO/AEO audit using the soleur:marketing:seo-aeo-analyst agent.
+
+### Steps
+
+1. Launch the soleur:marketing:seo-aeo-analyst agent via the Task tool:
+
+   ```
+   Task soleur:marketing:seo-aeo-analyst: "Audit this Eleventy documentation site for SEO and AEO issues.
+   Read the site configuration, templates, and data files. Produce a structured report
+   with critical issues, warnings, and passed checks. Do NOT make any changes."
+   ```
+
+2. Present the agent's report to the user
+3. Offer next steps: "Run `seo-aeo fix` to apply recommended fixes, or `seo-aeo validate` to check the built output."
+
+---
+
+## Sub-command: fix
+
+Analyze gaps and apply targeted fixes to source files.
+
+### Steps
+
+1. Launch the soleur:marketing:seo-aeo-analyst agent via the Task tool with fix instructions:
+
+   ```
+   Task soleur:marketing:seo-aeo-analyst: "Audit this Eleventy documentation site for SEO and AEO issues.
+   For each issue found, apply a fix to the source files. Read each file before editing.
+   After all fixes, build the site with `npx @11ty/eleventy` and run
+   `bash "${CLAUDE_PLUGIN_ROOT}/skills/seo-aeo/scripts/validate-seo.sh" _site` and
+   `bash "${CLAUDE_PLUGIN_ROOT}/skills/seo-aeo/scripts/validate-csp.sh" _site` to verify.
+   Report what was changed and whether validation passed."
+   ```
+
+2. Present the agent's report showing changes made
+3. If validation failed, show the failing checks and offer to re-run fix
+
+---
+
+## Sub-command: validate
+
+Run the standalone validation script against built output.
+
+### Steps
+
+1. Verify `_site/` exists. If not, build first:
+
+   ```bash
+   npx @11ty/eleventy
+   ```
+
+2. Run the validation scripts:
+
+   ```bash
+   bash "${CLAUDE_PLUGIN_ROOT}/skills/seo-aeo/scripts/validate-seo.sh" _site
+   bash "${CLAUDE_PLUGIN_ROOT}/skills/seo-aeo/scripts/validate-csp.sh" _site
+   ```
+
+3. Report results:
+   - **Exit 0 on both:** All SEO and CSP checks passed
+   - **Exit 1:** Show failing checks and recommend running `seo-aeo fix`
+
+Validation scripts:
+
+- [validate-seo.sh](./scripts/validate-seo.sh) -- SEO/AEO element checks
+- [validate-csp.sh](./scripts/validate-csp.sh) -- Content-Security-Policy hash integrity checks
+
+**Known limitations:**
+
+- validate-seo.sh only checks named AI bot entries -- wildcard `User-agent: *` blocks are not detected. A site blocking all bots via wildcard will pass validation.
+- validate-csp.sh requires Python 3 for reliable multi-line HTML parsing and SHA-256 hash computation.
+
+## Sharp edges
+
+- **Bare-relative href sweep target list.** When dropping `<base href="/">` (or any change that defeats relative-href resolution), the sweep file list is `pages/**/*.njk`, `_includes/**/*.njk`, `index.njk`, **`404.njk`**, `llms.txt.njk`, `sitemap.njk`, and `blog/**/*.md` (`page-redirects.njk` was deleted in #3328 — the meta-refresh redirect machinery now lives entirely at the Cloudflare edge). Siblings of `index.njk` at the docs root are easy to miss because they don't live under `pages/`. Verify post-sweep: `grep -rnE 'href="[a-z][a-z-]*/' plugins/soleur/docs/ | grep -vE 'https?:|mailto:|//'` must be empty. Inline `@font-face` `url('fonts/...')` and preload `href="css/..."` resolve against the document URL too — convert those to absolute in the same edit. See PR #2973.
+- **Bulk URL change in `_data/site.json` requires Nunjucks consumer sweep.** Root-slashing nav URLs breaks any template predicate that concatenates `'/' + item.url` (silent — `aria-current` simply stops activating). Grep `_includes/**/*.njk` for every place the field is consumed (`item.url`, `link.url`) and verify each comparison still computes against the new shape. Same class as the sweep rules in AGENTS.md (`cq-raf-batching-sweep-test-helpers` et al). See PR #2973.
+- **Eleventy custom date filters must guard falsy input.** `new Date(undefined).toISOString()` throws `RangeError`. Any custom Eleventy filter that delegates to the Date constructor must return null on falsy input AND the calling template must wrap its JSON-LD line in `{% if page.date %}` so a null result does not emit invalid schema.org. Example: `dateToRfc3339` in `eleventy.config.js`.
+- **`validate-seo.sh` per-page substitutions need `|| true`.** Inside the per-page loop under `set -euo pipefail`, `count=$(grep -oE 'X' "$f" | wc -l)` aborts the script on zero matches because pipefail propagates grep's exit 1. Use `count=$(grep -cE 'X' "$f" || true)` — `grep -c` returns the count (0 on no match) and the rescue keeps the script alive.
+- **A GSC "Page with redirect" cluster is usually Google's historical memory, not a live sitemap leak.** The affected-URL list is dominated by URLs Google learned before a canonicalization (www→apex, `.html`→clean, `?ref=` query forms) that now 3xx **correctly** — it self-heals server-side as Google re-crawls; there is no repo defect to chase. The only actionable repo condition is a *redirecting* URL present in the *built `sitemap.xml`*. Verify THAT specific condition against a fresh `npx @11ty/eleventy` build (`grep -oE '<loc>[^<]+</loc>' _site/sitemap.xml | grep -E '(\.html$|/pages/)'` must be empty); do not treat the GSC URL list as a bug list. The redirect-stub gate in `validate-seo.sh` enforces it at deploy/CI time. See `knowledge-base/project/learnings/2026-06-01-gsc-page-with-redirect-is-historical-memory-verify-against-build.md`.
+- **A GSC "Duplicate, Google chose different canonical than user" report on a `www` (or other non-canonical-variant) URL is the same benign class** — Google followed the variant's 301 to the apex, read the apex page's correct self-canonical, and consolidated the variant onto it (working correctly). Verify via live `curl`: variant → `301` → apex, apex → `200`, apex canonical self-referential. The fix is operator **VALIDATE FIX** in GSC + wait ~2-4 weeks, NOT a code change — and never "correct" `site.url` to `www` (the inverse of the #4573 apex flip; would emit a redirecting canonical site-wide). The per-page canonical-host gate in `validate-seo.sh` asserts each page's canonical host matches the sitemap host (catches a template regression; a uniform `site.url` flip is covered by NEITHER uptime monitor, and saying otherwise is the defect #7798 exists to fix. A flip changes the canonical tags the site EMITS; it does not touch the Cloudflare Bulk Redirect, so `betteruptime_monitor.soleur_www_redirect` still sees www 301 to the apex and stays green, as does the Sentry reachability probe. The predecessor claim named `sentry_uptime_monitor.soleur_www`, which additionally could never pass at all. A uniform flip is caught at review, not by an alarm). See `knowledge-base/project/learnings/2026-06-12-gsc-duplicate-canonical-on-www-variant-is-benign-consolidation.md`.
+- **Cloudflare Bulk Redirects match `http.request.full_uri` exactly — enumerate every client-reachable shape, not the shapes the replaced machinery emits.** Migrating an origin redirect to `seo-bulk-redirects.tf` needs one item per form: `/<path>/`, `/<path>/index.html`, AND the bare `/<path>` (no trailing slash). The origin's trailing-slash normalization masks a missing bare item today; deleting the origin stub removes the mask and that form 404s. See `knowledge-base/project/learnings/2026-09-18-exact-match-bulk-redirects-need-the-bare-shape-too.md`.
+- **Deleting a build input does not delete its output — verify stub/template removal on a clean `_site`, and fence the emitted signature, not the file size.** Eleventy incremental builds never prune removed templates, so a deleted `articles.njk` still served `_site/articles/index.html` until `rm -rf _site && bunx @11ty/eleventy`. The oracle for "no stubs remain" is a semantic grep over a fresh build (`grep -rl 'http-equiv="refresh"' _site` must be empty) at any size — a byte-threshold predicate lets a layout-wrapped meta refresh escape, and a plan's enumerated file list missed a fifth stub the grep found. See `knowledge-base/project/learnings/workflow-issues/guard-content-not-mechanism-stub-deletion-20260919.md`.
+- **Run every suite that asserts on a marketing surface BEFORE shipping its edit — a plan's verification list is not the gate set.** `plugins/soleur/test/seo-aeo-drift-guard.test.ts` pins marketing prose by *literal*: the `#4410`/`#4754` AEO contract needs a `docs.claude.com` href **inside `.page-citations`**; `#9584` Guard 1 flags any marketing sentence with Claude-plan wording that is not both self-host-scoped and free of a hosted token; `#9582`/`#9579` pin the hero line to open `Self-hosted runs inside your own Claude Code` (committed wireframe `.pen` + counsel audit). A de-monopolizing rewrite can satisfy a sentence's *intent* and still red all three. `grep -rl '<filename>' plugins/soleur/test/` before editing, run those suites, and repair the CONTENT — never the assertion. See `knowledge-base/project/learnings/2026-10-20-docs-edits-regressed-a-guarded-prose-gate.md`.

package/skills/seo-aeo/scripts/validate-csp.sh

@@ -0,0 +1,233 @@
+#!/usr/bin/env bash
+# validate-csp.sh -- Verify inline script SHA-256 hashes match the CSP meta tag.
+# Usage: bash validate-csp.sh <site-dir>
+# Exit 0 = all hashes match, Exit 1 = mismatch or missing CSP.
+#
+# Scans all HTML pages in the site directory. Each page with a CSP meta tag
+# has its inline scripts extracted and hashed, then compared against the
+# hashes declared in the CSP script-src directive.
+#
+# Depends on: python3 (for reliable multi-line HTML parsing and SHA-256 hashing)
+
+set -euo pipefail
+
+SITE_DIR="${1:?Usage: validate-csp.sh <site-dir>}"
+FAILURES=0
+
+fail() {
+  echo "FAIL: $1"
+  FAILURES=$((FAILURES + 1))
+}
+
+pass() {
+  echo "PASS: $1"
+}
+
+# ── Collect HTML files ───────────────────────────────────────────────────────
+
+html_files=()
+while IFS= read -r -d '' f; do
+  html_files+=("$f")
+done < <(find "$SITE_DIR" -name '*.html' -not -name '404.html' -print0)
+
+if [[ ${#html_files[@]} -eq 0 ]]; then
+  fail "no HTML files found in $SITE_DIR"
+  exit 1
+fi
+
+pass "found ${#html_files[@]} HTML page(s)"
+
+# ── Validate each page ──────────────────────────────────────────────────────
+
+PAGES_WITH_CSP=0
+
+for html_file in "${html_files[@]}"; do
+  page="${html_file#"$SITE_DIR"/}"
+
+  # NOTE: no meta-refresh skip here — the instant-refresh exemption was the
+  # evasion class deleted in #3328 PR-B (edge 301s serve every legacy URL now;
+  # a reintroduced stub must fail CSP validation like every other page).
+
+  # Use Python for all HTML parsing: extract CSP hashes, inline script hashes, AND
+  # detect inline event-handler attributes (`onload=`, `onclick=`, etc.) that the
+  # CSP would block but no static gate previously caught — see PR #2966 / learning
+  # at knowledge-base/project/learnings/best-practices/ for the silent-failure class.
+  # Passing the file path via sys.argv[1] avoids shell injection.
+  RESULT=$(python3 -c "
+import hashlib, base64, re, sys
+from html.parser import HTMLParser
+
+with open(sys.argv[1], 'r') as f:
+    content = f.read()
+
+# Extract CSP meta tag
+csp_match = re.search(
+    r'<meta\s+http-equiv=\"Content-Security-Policy\"\s+content=\"([^\"]*)\"',
+    content
+)
+if not csp_match:
+    print('NO_CSP')
+    sys.exit(0)
+
+csp_content = csp_match.group(1)
+
+# Extract script-src directive
+src_match = re.search(r'script-src\s+([^;]+)', csp_content)
+if not src_match:
+    print('NO_SCRIPT_SRC')
+    sys.exit(0)
+
+script_src = src_match.group(1)
+
+# Extract sha256 hashes from CSP
+csp_hashes = set(re.findall(r\"'(sha256-[A-Za-z0-9+/=]+)'\", script_src))
+
+# Detect whether the CSP allows inline event handlers.
+allows_unsafe_inline = bool(re.search(r\"'unsafe-inline'\", script_src))
+allows_unsafe_hashes = bool(re.search(r\"'unsafe-hashes'\", script_src))
+
+# Extract inline scripts (excluding ld+json and src= scripts)
+scripts = re.findall(
+    r'<script(?![^>]*(?:type=\"application/ld\+json\"|src=))[^>]*>(.*?)</script>',
+    content,
+    re.DOTALL
+)
+
+# Compute hashes
+computed_hashes = set()
+for script in scripts:
+    h = hashlib.sha256(script.encode('utf-8')).digest()
+    b64 = base64.b64encode(h).decode()
+    computed_hashes.add(f'sha256-{b64}')
+
+# Output: CSP_HASHES|COMPUTED_HASHES (pipe-separated sets, comma-separated within)
+print(','.join(sorted(csp_hashes)) + '|' + ','.join(sorted(computed_hashes)))
+
+# Check for prohibited directives in meta tags
+prohibited = ['strict-dynamic', 'report-uri', 'report-to', 'frame-ancestors', 'sandbox']
+found_prohibited = [d for d in prohibited if re.search(r'(^|;\s*)' + d + r'(\s|;|$)', csp_content)]
+if found_prohibited:
+    print('PROHIBITED:' + ','.join(found_prohibited))
+
+# Inline event-handler scan. Use html.parser so we naturally skip <script>
+# content and HTML comments — both contained false-positives in earlier regex
+# attempts (e.g., 'window.onload =' inside a <script>, or 'onload=' inside a
+# <!-- comment -->).
+class EventHandlerFinder(HTMLParser):
+    def __init__(self):
+        super().__init__()
+        self.violations = []
+    def handle_starttag(self, tag, attrs):
+        for name, value in attrs:
+            if name and name.lower().startswith('on') and len(name) > 2 and name[2:].isalpha():
+                line, col = self.getpos()
+                self.violations.append((line, tag, name, (value or '')[:80]))
+    handle_startendtag = handle_starttag
+
+if not (allows_unsafe_inline or allows_unsafe_hashes):
+    finder = EventHandlerFinder()
+    try:
+        finder.feed(content)
+    except Exception as e:
+        print(f'INLINE_HANDLER_PARSE_ERROR:{e}')
+    for line, tag, attr, value in finder.violations:
+        # One violation per line. Bash splits on newlines.
+        print(f'INLINE_HANDLER:{line}:{tag}:{attr}={value}')
+" "$html_file" || true)
+
+  # Skip pages without CSP
+  if [[ "$RESULT" == "NO_CSP" ]]; then
+    continue
+  fi
+
+  if [[ "$RESULT" == "NO_SCRIPT_SRC" ]]; then
+    fail "$page: CSP meta tag found but no script-src directive"
+    continue
+  fi
+
+  PAGES_WITH_CSP=$((PAGES_WITH_CSP + 1))
+
+  # Parse Python output
+  HASH_LINE=$(echo "$RESULT" | head -1)
+  CSP_HASHES_STR="${HASH_LINE%%|*}"
+  COMPUTED_HASHES_STR="${HASH_LINE#*|}"
+
+  # Check for prohibited directives
+  PROHIBITED_LINE=$(echo "$RESULT" | grep '^PROHIBITED:' || true)
+  if [[ -n "$PROHIBITED_LINE" ]]; then
+    directives="${PROHIBITED_LINE#PROHIBITED:}"
+    fail "$page: CSP contains unsupported meta tag directive(s): $directives"
+  fi
+
+  # Check for inline event-handler attributes that CSP would silently block.
+  # See PR #2966 — `<link onload="...">` was blocked by `script-src` lacking
+  # `'unsafe-inline'`/`'unsafe-hashes'`, and the swap never fired in production.
+  while IFS= read -r handler_line; do
+    [[ -z "$handler_line" ]] && continue
+    detail="${handler_line#INLINE_HANDLER:}"
+    fail "$page: inline event-handler attribute '$detail' is silently blocked by script-src (no 'unsafe-inline'/'unsafe-hashes'). Move the handler into a hashed <script> block, or add 'unsafe-hashes' + a hash."
+  done < <(echo "$RESULT" | grep '^INLINE_HANDLER:' || true)
+
+  PARSE_ERR=$(echo "$RESULT" | grep '^INLINE_HANDLER_PARSE_ERROR:' || true)
+  if [[ -n "$PARSE_ERR" ]]; then
+    fail "$page: inline-handler parse error: ${PARSE_ERR#INLINE_HANDLER_PARSE_ERROR:}"
+  fi
+
+  # Convert to arrays
+  IFS=',' read -ra csp_hashes <<< "$CSP_HASHES_STR"
+  IFS=',' read -ra computed_hashes <<< "$COMPUTED_HASHES_STR"
+
+  # Skip if no inline scripts on this page
+  if [[ ${#computed_hashes[@]} -eq 0 ]] || [[ -z "${computed_hashes[0]}" ]]; then
+    continue
+  fi
+
+  # Verify every inline script hash is in the CSP
+  for computed in "${computed_hashes[@]}"; do
+    [[ -z "$computed" ]] && continue
+    found=false
+    for csp_hash in "${csp_hashes[@]}"; do
+      if [[ "$computed" == "$csp_hash" ]]; then
+        found=true
+        break
+      fi
+    done
+    if $found; then
+      pass "$page: inline script hash $computed matches CSP"
+    else
+      fail "$page: inline script hash $computed NOT in CSP -- add '$computed' to script-src"
+    fi
+  done
+
+  # Verify no orphan hashes in CSP
+  for csp_hash in "${csp_hashes[@]}"; do
+    [[ -z "$csp_hash" ]] && continue
+    found=false
+    for computed in "${computed_hashes[@]}"; do
+      if [[ "$csp_hash" == "$computed" ]]; then
+        found=true
+        break
+      fi
+    done
+    if ! $found; then
+      fail "$page: orphan CSP hash $csp_hash matches no inline script -- remove from script-src"
+    fi
+  done
+done
+
+if [[ $PAGES_WITH_CSP -eq 0 ]]; then
+  fail "no pages with CSP meta tag found in $SITE_DIR"
+else
+  pass "validated CSP on $PAGES_WITH_CSP page(s)"
+fi
+
+# ── Summary ──────────────────────────────────────────────────────────────────
+
+echo ""
+if [[ $FAILURES -eq 0 ]]; then
+  echo "All CSP checks passed."
+  exit 0
+else
+  echo "$FAILURES CSP check(s) failed."
+  exit 1
+fi

package/skills/seo-aeo/scripts/validate-seo.sh

@@ -0,0 +1,262 @@
+#!/usr/bin/env bash
+# validate-seo.sh -- Check built Eleventy output for required SEO/AEO elements.
+# Usage: bash validate-seo.sh <site-dir>
+# Exit 0 = all checks pass, Exit 1 = one or more checks failed.
+
+set -euo pipefail
+
+SITE_DIR="${1:?Usage: validate-seo.sh <site-dir>}"
+FAILURES=0
+# Bare host (no scheme) the per-page canonical-href gate expects. DERIVED from the
+# sitemap's single <loc> host once it is validated below — there is no second literal
+# pin to drift from _data/site.json. Empty until the sitemap host is established (or
+# if the sitemap is missing/multi-host, in which case the per-page host check is
+# skipped — those failures are already reported by the sitemap gates).
+CANONICAL_HOST_EXPECTED=""
+
+fail() {
+  echo "FAIL: $1"
+  FAILURES=$((FAILURES + 1))
+}
+
+pass() {
+  echo "PASS: $1"
+}
+
+# ── llms.txt ──────────────────────────────────────────────────────────────────
+
+if [[ -f "$SITE_DIR/llms.txt" ]]; then
+  pass "llms.txt exists"
+else
+  fail "llms.txt missing"
+fi
+
+# ── robots.txt AI bot access ──────────────────────────────────────────────────
+# Limitation: checks only the line immediately after User-agent for Disallow.
+# Multi-line stanzas with comments between directives may be misdetected.
+
+if [[ -f "$SITE_DIR/robots.txt" ]]; then
+  pass "robots.txt exists"
+  for bot in GPTBot PerplexityBot ClaudeBot Google-Extended; do
+    if grep -qi "User-agent: $bot" "$SITE_DIR/robots.txt" && \
+       grep -qiE "Disallow: /\s*$" < <(grep -A1 -i "User-agent: $bot" "$SITE_DIR/robots.txt"); then
+      fail "robots.txt blocks $bot"
+    else
+      pass "robots.txt does not block $bot"
+    fi
+  done
+else
+  fail "robots.txt missing"
+fi
+
+# ── sitemap.xml ───────────────────────────────────────────────────────────────
+
+if [[ -f "$SITE_DIR/sitemap.xml" ]]; then
+  pass "sitemap.xml exists"
+  if grep -q '<lastmod>' "$SITE_DIR/sitemap.xml"; then
+    pass "sitemap.xml contains lastmod dates"
+  else
+    fail "sitemap.xml missing lastmod dates"
+  fi
+  # NON_HTML answers "is each <loc> a page URL at all?" (allows trailing-slash OR
+  # .html). This is a DIFFERENT axis from the redirect-stub gate below, which forbids
+  # the redirecting .html / /pages/ shape. Leave the `.html` allowance here intact.
+  NON_HTML=$(grep -oP '(?<=<loc>)[^<]+' "$SITE_DIR/sitemap.xml" | grep -vE '(/|\.html)$' || true)
+  if [[ -n "$NON_HTML" ]]; then
+    fail "sitemap.xml contains non-HTML entries: $NON_HTML"
+  else
+    pass "sitemap.xml contains only HTML entries"
+  fi
+
+  # Redirect-stub gate: redirect stubs used to live at /pages/*.html (meta-refresh
+  # + canonical-to-clean-URL, generated by page-redirects.njk — machinery deleted
+  # in #3328; every legacy URL is now served by a Cloudflare edge 301). The stub
+  # shape MUST NEVER appear here — Google indexes them as "Page with redirect" (the
+  # GSC cluster this gate guards on the PATH axis; the canonical-host gate below
+  # guards the HOST axis). Canonical pages all use trailing-slash directory URLs;
+  # no canonical page ends in .html. See the 2026-06-01 GSC sitemap-redirect-leak plan.
+  # `|| true` absorbs grep's exit-1 (no matches = the PASS case) under pipefail.
+  REDIRECTING=$(grep -oP '(?<=<loc>)[^<]+' "$SITE_DIR/sitemap.xml" \
+    | grep -E '(\.html$|/pages/)' || true)
+  if [[ -n "$REDIRECTING" ]]; then
+    fail "sitemap.xml contains redirecting URLs (must be canonical clean URLs only): $(echo "$REDIRECTING" | tr '\n' ' ')"
+  else
+    pass "sitemap.xml contains no redirecting URLs (.html / /pages/)"
+  fi
+
+  # Canonical-host gate (#3297): every <loc> must use a single canonical host,
+  # and that host must match the one declared in robots.txt's `Sitemap:` line
+  # (only if robots.txt actually has a Sitemap line — fixtures may omit it).
+  # This catches the GSC `Page with redirect` cluster cause: sitemap on www
+  # while live infra 301s www→apex (the canonical host is the bare apex
+  # https://soleur.ai; GitHub Pages enforces the CNAME apex). See the GSC
+  # indexing-fixes brainstorm and the 2026-05-29 host flip.
+  # `|| true` absorbs grep's exit-1 when sitemap has zero <loc> entries —
+  # pipefail would otherwise short-circuit before the empty-guard below.
+  SITEMAP_HOSTS=$(grep -oP '(?<=<loc>)[^<]+' "$SITE_DIR/sitemap.xml" \
+    | sed -E 's|^(https?://[^/]+).*|\1|' | sort -u || true)
+  HOST_COUNT=$(echo "$SITEMAP_HOSTS" | grep -c . || true)
+  if [[ -z "$SITEMAP_HOSTS" ]]; then
+    fail "sitemap.xml has no <loc> entries"
+  elif [[ "$HOST_COUNT" -gt 1 ]]; then
+    fail "sitemap.xml mixes multiple hosts: $(echo "$SITEMAP_HOSTS" | tr '\n' ' ')"
+  else
+    pass "sitemap.xml uses a single canonical host: $SITEMAP_HOSTS"
+    # Establish the per-page canonical-href host expectation from this single,
+    # validated sitemap host (strip the scheme to a bare host for comparison).
+    # $SITEMAP_HOSTS is already a single sort -u'd line in this HOST_COUNT==1 branch.
+    CANONICAL_HOST_EXPECTED=$(echo "$SITEMAP_HOSTS" | sed -E 's|^https?://||')
+    # Closing branch is below this if-fi block — the host comparison only
+    # runs when robots.txt exists AND has a `Sitemap:` line. Fixtures that
+    # omit the Sitemap line still pass the sitemap-internal consistency
+    # check above; production robots.txt always has the line.
+    if [[ -f "$SITE_DIR/robots.txt" ]] && grep -qiE '^Sitemap:' "$SITE_DIR/robots.txt"; then
+      ROBOTS_HOST=$(grep -iE '^Sitemap:' "$SITE_DIR/robots.txt" \
+        | sed -E 's|^[Ss]itemap:[[:space:]]*(https?://[^/]+).*|\1|' | head -1)
+      if [[ "$SITEMAP_HOSTS" != "$ROBOTS_HOST" ]]; then
+        fail "sitemap host ($SITEMAP_HOSTS) does not match robots.txt Sitemap line ($ROBOTS_HOST)"
+      else
+        pass "sitemap host matches robots.txt Sitemap line"
+      fi
+    fi
+  fi
+else
+  fail "sitemap.xml missing"
+fi
+
+# ── HTML pages ────────────────────────────────────────────────────────────────
+
+html_files=()
+while IFS= read -r -d '' f; do
+  html_files+=("$f")
+done < <(find "$SITE_DIR" -name '*.html' -not -name '404.html' -print0)
+
+if [[ ${#html_files[@]} -eq 0 ]]; then
+  fail "no HTML files found in $SITE_DIR"
+else
+  pass "found ${#html_files[@]} HTML page(s)"
+fi
+
+for f in "${html_files[@]}"; do
+  page="${f#"$SITE_DIR"/}"
+
+  # Canonical URL
+  if grep -q 'rel="canonical"' "$f"; then
+    pass "$page has canonical URL"
+  else
+    fail "$page missing canonical URL"
+  fi
+
+  # Canonical-href host gate (2026-06-12 GSC duplicate-canonical plan): EVERY page
+  # <link rel="canonical"> absolute-host MUST match the sitemap's single canonical host
+  # (CANONICAL_HOST_EXPECTED, derived above). A page emitting a different host (e.g. a
+  # www variant while the sitemap/apex is canonical) 301-redirects in prod and induces
+  # the GSC "Duplicate, Google chose different canonical than user" cluster — the
+  # per-page sibling of the sitemap host-axis gate above. ALL canonical tags are
+  # checked (a rogue second tag with a different host is the exact failure mode), not
+  # just the first. Only ABSOLUTE-host canonicals are extracted; a relative href leaves
+  # the host list empty and is skipped (the presence check above covers absence). The
+  # `|| true` absorbs grep's exit-1 on no-match under `set -euo pipefail`, mirroring the
+  # sitemap gates above (lines ~80/~96).
+  if [[ -n "$CANONICAL_HOST_EXPECTED" ]]; then
+    canon_hosts=$(grep -oiE '<link[^>]+rel="canonical"[^>]*>' "$f" \
+      | grep -oiE 'href="https?://[^/"]+' | sed -E 's|.*href="https?://||' || true)
+    if [[ -n "$canon_hosts" ]]; then
+      bad_host=$(printf '%s\n' "$canon_hosts" | grep -vxF "$CANONICAL_HOST_EXPECTED" | head -1 || true)
+      if [[ -n "$bad_host" ]]; then
+        fail "$page canonical host '$bad_host' differs from sitemap canonical host '$CANONICAL_HOST_EXPECTED' — a redirecting/other-host canonical induces GSC 'Google chose different canonical than user'"
+      else
+        pass "$page canonical host matches sitemap host ($CANONICAL_HOST_EXPECTED)"
+      fi
+    fi
+  fi
+
+  # JSON-LD
+  if grep -q 'application/ld+json' "$f"; then
+    pass "$page has JSON-LD"
+  else
+    fail "$page missing JSON-LD structured data"
+  fi
+
+  # OG tags
+  if grep -q 'property="og:title"' "$f"; then
+    pass "$page has og:title"
+  else
+    fail "$page missing og:title"
+  fi
+
+  # Twitter card
+  if grep -q 'name="twitter:card"' "$f"; then
+    pass "$page has Twitter card"
+  else
+    fail "$page missing Twitter card meta tag"
+  fi
+
+  # No <base> tag (per #2945) — root-domain site uses absolute root-relative paths
+  # Anchor on tag boundary to avoid false positives in prose / code blocks
+  if grep -qE '<base[[:space:]>]' "$f"; then
+    fail "$page contains <base> tag (must be removed for root-domain site)"
+  else
+    pass "$page has no <base> tag"
+  fi
+
+  # Exactly one <h1> per page (per #2943)
+  # grep -c exits 1 on zero matches under pipefail; `|| true` keeps the script alive
+  h1_count=$(grep -cE '<h1[ >]' "$f" || true)
+  if [[ "$h1_count" -ne 1 ]]; then
+    fail "$page has $h1_count <h1> tags (expected exactly 1)"
+  else
+    pass "$page has exactly 1 <h1>"
+  fi
+
+  # Non-empty meta description (per #2942)
+  if grep -q 'name="description" content=""' "$f"; then
+    fail "$page has empty meta description"
+  else
+    pass "$page has non-empty meta description"
+  fi
+
+  # FAQPage existence when visible FAQ markup is rendered (per #2948).
+  # This check verifies the JSON-LD block is PRESENT alongside the visible
+  # FAQ, not that every Q/A pair has parity — see the FAQPage parity learning
+  # for the codepoint-exact check (run via /soleur:review's data-integrity
+  # agent, not this CI gate).
+  if grep -qE 'class="faq-(item|question|answer|list)\b' "$f"; then
+    if grep -q '"@type": "FAQPage"' "$f"; then
+      pass "$page has FAQPage JSON-LD alongside visible FAQ"
+    else
+      fail "$page renders faq- class but lacks FAQPage JSON-LD"
+    fi
+  fi
+done
+
+# ── Homepage-specific: SoftwareApplication ────────────────────────────────────
+
+if [[ -f "$SITE_DIR/index.html" ]]; then
+  if grep -q '"SoftwareApplication"' "$SITE_DIR/index.html"; then
+    pass "homepage has SoftwareApplication JSON-LD"
+  else
+    fail "homepage missing SoftwareApplication JSON-LD"
+  fi
+fi
+
+# ── Changelog: build-time content ─────────────────────────────────────────────
+
+if [[ -f "$SITE_DIR/pages/changelog.html" ]]; then
+  if grep -q 'Loading changelog' "$SITE_DIR/pages/changelog.html"; then
+    fail "changelog page still has client-side loading placeholder"
+  else
+    pass "changelog page has build-time content"
+  fi
+fi
+
+# ── Summary ───────────────────────────────────────────────────────────────────
+
+echo ""
+if [[ $FAILURES -eq 0 ]]; then
+  echo "All SEO checks passed."
+  exit 0
+else
+  echo "$FAILURES check(s) failed."
+  exit 1
+fi