@softspark/ai-toolkit 4.1.0 → 4.2.1

package/AGENTS.md

@@ -348,7 +348,7 @@ Security expert. Use for OWASP Top 10, CVE analysis, security audits, penetratio
 
 ### `seo-specialist`
 
-Search engine + generative engine optimization specialist. Trigger words: SEO, GEO, AEO, search engine, meta tags, structured data, Core Web Vitals, sitemap, robots.txt, schema.org, llms.txt, ChatGPT visibility, Claude citation, Perplexity ranking, AI Overviews
+Search engine + generative engine optimization specialist. Trigger words: SEO, GEO, AEO, search engine, meta tags, structured data, Core Web Vitals, sitemap, robots.txt, schema.org, llms.txt, ChatGPT visibility, Claude citation, Perplexity ranking, AI Overviews, topical authority, chunk architecture, semantic triples, query fan out
 
 **Tools:** `Read, Write, Edit, Bash, Grep, Glob`
 
@@ -436,7 +436,7 @@ Specialized agent personas — apply their expertise for relevant tasks:
 - **search-specialist**: Information retrieval and search optimization specialist. Trigger words: search, query, semantic search, information retrieval, relevance, ranking, search optimization
 - **security-architect**: Proactive security design expert. Use for Threat Modeling, architecture security reviews, and designing secure systems (AuthN/AuthZ, Crypto).
 - **security-auditor**: Security expert. Use for OWASP Top 10, CVE analysis, security audits, penetration testing, vulnerability assessment, hardening. Triggers: security, owasp, cve, vulnerability, audit, hardening, penetration, pentest, injection test, api security.
-- **seo-specialist**: Search engine + generative engine optimization specialist. Trigger words: SEO, GEO, AEO, search engine, meta tags, structured data, Core Web Vitals, sitemap, robots.txt, schema.org, llms.txt, ChatGPT visibility, Claude citation, Perplexity ranking, AI Overviews
+- **seo-specialist**: Search engine + generative engine optimization specialist. Trigger words: SEO, GEO, AEO, search engine, meta tags, structured data, Core Web Vitals, sitemap, robots.txt, schema.org, llms.txt, ChatGPT visibility, Claude citation, Perplexity ranking, AI Overviews, topical authority, chunk architecture, semantic triples, query fan out
 - **system-governor**: The Guardian of the Constitution. Validates all evolutionary changes and enforces immutable rules. Has VETO power.
 - **tech-lead**: Technical authority for code quality, architecture patterns, and stack decisions. Use for code reviews, technological disputes, and standards enforcement.
 - **technical-researcher**: Deep technical investigation and multi-source research synthesis specialist. Trigger words: technical research, feasibility study, root cause analysis, API investigation, compatibility research, comparison matrix, synthesize, aggregate, report, executive summary, gap analysis, findings, multi-source, cross-reference

package/CHANGELOG.md

@@ -7,6 +7,60 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.2.1 - Claude Code hook enforcement and README cleanup (2026-05-12)
+
+Patch release. Tightens Claude Code runtime enforcement, fixes duplicated hook cleanup during install/update, and removes the README hero image for release.
+
+### Changed
+
+- **Stop quality gate** - Registered `quality-gate.sh` for `Stop` in addition to `TaskCompleted`, so final Claude Code responses are blocked when supported lint/type checks fail.
+- **README release surface** - Removed the README hero image block while keeping badges and release notes intact.
+- **Runtime guidance** - Clarified in `CLAUDE.md` that Claude Code consumes `CLAUDE.md`, settings, hooks, skills, and agents, while `AGENTS.md` is generated for Codex/OpenCode/Gemini compatibility.
+
+### Fixed
+
+- **Quality gate exit codes** - Reworked shell pipelines so `ruff`, `tsc`, `dart analyze`, `phpstan`, and `go test` failures are not masked by output truncation.
+- **Hook merge cleanup** - `scripts/merge-hooks.py` now removes legacy untagged ai-toolkit hook entries matching current toolkit hook signatures while preserving custom hooks.
+
+### Ecosystem
+
+- Refreshed `benchmarks/ecosystem-doctor-snapshot.json` for current editor/runtime docs. Claude Code now exposes `Stop` in docs; the toolkit already supported `Stop` hooks, and this release registers the strict quality gate there.
+
+### Verification
+
+- `python3 scripts/ecosystem_doctor.py --offline --check`: no drift.
+- `python3 scripts/validate.py --strict`: 0 errors, 0 warnings.
+- `python3 scripts/audit_skills.py --ci`: HIGH 0, WARN 0.
+- `npm test`: 1049/1049 passing.
+- `npm --cache /tmp/ai-toolkit-npm-cache pack --dry-run`: `softspark-ai-toolkit-4.2.1.tgz`.
+
+---
+
+## v4.2.0 - SEO GEO pipeline and release gate hardening (2026-05-07)
+
+Minor release. Adds AI pipeline, content citability, and topical authority guidance to `seo-validate` from PR #9 by @fakenso, and keeps the release gate fixes prepared for v4.1.1 in the same unreleased train.
+
+### Added
+
+- **SEO AI pipeline reference** - Added `app/skills/seo-validate/reference/ai-pipeline.md` covering the Prepare/Retrieve/Signal/Serve pipeline, ranking signals, Query Fan Out, and format routing.
+- **Content citability reference** - Added `app/skills/seo-validate/reference/content-citability.md` covering chunk architecture, semantic triples, hedging patterns, decision frameworks, contrast patterns, negative definitions, freshness, and E-E-A-T.
+- **Topical authority scope** - Added `--scope topical` to `seo-validate`, with checks for pillar/cluster structure, internal link density, generic anchors, orphan pages, ID-based slugs, and keyword cannibalization.
+- **Expanded GEO guidance** - Expanded Category 6 from INFO-only guidance to INFO/WARN heuristics for chunk boundaries, author quality, and freshness. Updated `seo-specialist` with AI pipeline, multi-platform SEO, and topical authority responsibilities.
+
+### Fixed
+
+- **URL rule registration test** - Replaced the live `raw.githubusercontent.com` dependency with a local fixture path guarded by `AI_TOOLKIT_TEST_MODE=1`, keeping production URL fetching HTTPS-only while making the full Bats suite hermetic.
+- **Release validation gate** - Updated CI and `prepublishOnly` to run `python3 scripts/validate.py --strict`, matching the release preparation SOP.
+
+### Verification
+
+- `npm test`: 1047/1047 passing.
+- `python3 scripts/validate.py --strict`: 0 errors, 0 warnings.
+- `python3 scripts/audit_skills.py --ci`: HIGH 0, WARN 0.
+- `python3 scripts/evaluate_skills.py`: 107/107 passing.
+
+---
+
 ## v4.1.0 — Default `output-mode: concise` propagated to all editors (2026-05-06)
 
 Minor release. Adds a global `output-mode: concise` directive that propagates to every editor config produced by ai-toolkit. Reduces token usage and removes preamble/filler from assistant responses across Claude Code, Cursor, Windsurf, Cline, Roo Code, Augment, Codex, Antigravity, GitHub Copilot, Gemini CLI, and Aider.

package/README.md

@@ -6,43 +6,16 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-107-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-1047%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-1049%20passing-success)](tests/)
 
-<p align="center">
-  <img src="assets/ai-toolkit-readme-hero.png" alt="ai-toolkit 3 README hero showing one toolkit for 12 AI editors" width="900">
-</p>
+## What's New in v4.2.1
 
----
-
-## What's New in v4.1.0
-
-Default `output-mode: concise` directive now propagates to every editor config (Claude Code global + project-local CLAUDE.md, Cursor `.mdc` rules, Windsurf, Cline, Roo, Augment, Codex `.agents/rules`, Antigravity, GitHub Copilot, Gemini CLI, Aider). Auto-installed on every `ai-toolkit install` / `ai-toolkit update`. The `brand-voice` skill (shipped v3.2.0) auto-loads concise rules; assistants without that skill still see the directive in their config.
-
-- **No preamble**, lead with the result, max 3 sentences per closed question, tables over prose, no trailing summaries.
-- **Opt out**: `/brand-voice default` (session) or strip `<!-- TOOLKIT:output-mode -->` block from CLAUDE.md (permanent).
-
-## What's New in v4.0.1
-
-CI hotfix for v4.0.0. Corrects skill subtype counts in `README.md` "What You Get" table and `kb/reference/architecture-overview.md` (hybrid 32 → 30, knowledge 48 → 45). The metadata contract tests caught the drift on CI; v4.0.0 release path missed three count locations. No skill catalog changes — see v4.0.0 below for the actual consolidation.
-
-## What's New in v4.0.0
-
-**Breaking release.** Skill catalog consolidated from 112 → 107: removes 5 redundant skills, merges their substantive knowledge into the surviving targets. Eliminates `/skills` truncation and removes overlap that confused agent dispatch.
-
-- **`/search` removed** — `/research-mastery` is the superset (KB → MCP/Context7 → web with hierarchy of truth). Local Grep/Glob fallback is now part of `/research-mastery`.
-- **`/teams` removed** — `/workflow` covers the same scenarios without the experimental `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` flag.
-- **`plan-writing` knowledge skill removed** — estimation patterns (T-shirt sizing, cone of uncertainty) and pre-mortem rules are now part of `/plan`.
-- **`debugging-tactics` knowledge skill removed** — Iron Law, 4-phase methodology, and "5 Whys" are now part of `/debug`.
-- **`hive-mind` knowledge skill removed** — consensus voting and aggregation merged into `/swarm`.
-
-### Migration
+Patch release focused on making Claude Code rule enforcement harder to bypass and cleaning the release-facing README.
 
-| Before | After |
-|--------|-------|
-| `/search <query>` | `/research-mastery <query>` |
-| `/teams <preset>` | `/workflow <type>` |
-| Agent `skills: plan-writing` | Agent `skills: plan` |
-| Agent `skills: debugging-tactics` | Agent `skills: debug` |
+- **Stop quality gate**: `quality-gate.sh` now runs on `Stop` as well as `TaskCompleted`, blocking final responses when lint/type checks fail.
+- **Reliable hook failures**: shell pipelines in the quality gate now preserve the failing tool exit code instead of hiding errors behind `head`.
+- **Cleaner installs**: hook merging now strips legacy untagged ai-toolkit duplicates while preserving user-owned hooks.
+- **README cleanup**: removed the hero image block for a lighter release README.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -152,7 +125,7 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 | `skills/` (hybrid) | 30 | Slash commands with agent knowledge base |
 | `skills/` (knowledge) | 45 | Domain knowledge auto-loaded by agents (includes 13 `<lang>-rules` skills) |
 | `agents/` | 44 | Specialized agents across 10 categories |
-| `hooks/` | 21 global + 5 skill-scoped | Quality gates, path safety, prompt governance, session lifecycle |
+| `hooks/` | 22 global + 5 skill-scoped | Quality gates, path safety, prompt governance, session lifecycle |
 | `plugins/` | 11 packs | Opt-in domain bundles (security, research, frontend, enterprise, 6 language packs) |
 | `constitution.md` | 6 articles | Machine-enforced safety rules |
 | `rules/` | auto-injected | Language-specific and custom rules injected into your configs |
@@ -168,14 +141,14 @@ ai-toolkit/
 │   ├── agents/          # 44 agent definitions
 │   ├── skills/          # 107 skills (task / hybrid / knowledge)
 │   ├── rules/           # Auto-injected into your CLAUDE.md
-│   ├── hooks/           # Hook scripts (21 entries, 12 lifecycle events)
+│   ├── hooks/           # Hook scripts (22 entries, 12 lifecycle events)
 │   ├── plugins/         # 11 experimental plugin packs (opt-in)
 │   ├── output-styles/   # System prompt output style overrides
 │   ├── constitution.md  # 6 immutable safety articles
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (1047 tests)
+├── tests/               # Bats test suite (1049 tests)
 └── CHANGELOG.md
 ```
 
@@ -187,7 +160,7 @@ ai-toolkit/
 
 **Machine-enforced constitution** — 6-article safety constitution enforced via `PreToolUse` hooks that actually block `rm -rf`, `DROP TABLE`, and irreversible operations. Not just documentation.
 
-**21 lifecycle hooks** — Executable scripts across 12 events (SessionStart → SessionEnd). Guards, governance, quality gates, session persistence, MCP health checks. See [Hooks Catalog](kb/reference/hooks-catalog.md).
+**22 lifecycle hooks** — Executable scripts across 12 events (SessionStart → SessionEnd). Guards, governance, quality gates, session persistence, MCP health checks. See [Hooks Catalog](kb/reference/hooks-catalog.md).
 
 **Security scanning** — `/skill-audit` for code-level risks, `/cve-scan` for dependency CVEs. Both CI-ready with exit codes.
 

package/app/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-toolkit",
   "description": "Professional-grade Claude Code toolkit with persona presets, skill security auditor, expanded lifecycle hooks, experimental opt-in plugin packs, benchmark harvesting, and multi-tool support.",
-  "version": "4.1.0",
+  "version": "4.2.1",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/ARCHITECTURE.md

@@ -8,7 +8,7 @@ Universal multi-agent system for software development. Works across all reposito
 |-----------|-------|
 | Agents | See agents catalog |
 | Skills | See skills catalog |
-| Hooks | 12 events / 21 entries (SessionStart ×3, Notification ×1, PreToolUse ×4, UserPromptSubmit ×2, PostToolUse ×2, Stop ×2, TaskCompleted ×1, TeammateIdle ×1, SubagentStart ×1, SubagentStop ×1, PreCompact ×2, SessionEnd ×1) |
+| Hooks | 12 events / 22 entries (SessionStart ×3, Notification ×1, PreToolUse ×4, UserPromptSubmit ×2, PostToolUse ×2, Stop ×3, TaskCompleted ×1, TeammateIdle ×1, SubagentStart ×1, SubagentStop ×1, PreCompact ×2, SessionEnd ×1) |
 
 ---
 

package/app/agents/seo-specialist.md

@@ -1,6 +1,6 @@
 ---
 name: seo-specialist
-description: "Search engine + generative engine optimization specialist. Trigger words: SEO, GEO, AEO, search engine, meta tags, structured data, Core Web Vitals, sitemap, robots.txt, schema.org, llms.txt, ChatGPT visibility, Claude citation, Perplexity ranking, AI Overviews"
+description: "Search engine + generative engine optimization specialist. Trigger words: SEO, GEO, AEO, search engine, meta tags, structured data, Core Web Vitals, sitemap, robots.txt, schema.org, llms.txt, ChatGPT visibility, Claude citation, Perplexity ranking, AI Overviews, topical authority, chunk architecture, semantic triples, query fan out"
 tools: Read, Write, Edit, Bash, Grep, Glob
 model: sonnet
 color: cyan
@@ -9,7 +9,7 @@ skills: clean-code, seo-validate
 
 # SEO + GEO Specialist
 
-Optimization for both classical search engines AND generative engines (ChatGPT, Claude, Perplexity, Google AI Overviews, Gemini).
+Optimization for both classical search engines AND generative engines (ChatGPT, Claude, Perplexity, Google AI Overviews, Gemini, Google AI Mode).
 
 ## Expertise
 - Technical SEO
@@ -18,6 +18,10 @@ Optimization for both classical search engines AND generative engines (ChatGPT,
 - Structured data (Schema.org)
 - SEO auditing
 - **Generative Engine Optimization (GEO)** — being cited by LLM-based answer engines
+- **Google AI pipeline** — understanding the 4-stage Prepare/Retrieve/Signal/Serve pipeline and 7 ranking signals
+- **Query Fan Out** — 95% of AI retrieval sub-queries have zero MSV; topical coverage matters more than keyword volume
+- **Probabilistic ranking** — no deterministic "position 1"; optimize for citation probability across personas and contexts
+- **Topical authority** — pillar + cluster architecture, orphan page detection, keyword cannibalization
 
 ## Responsibilities
 
@@ -39,6 +43,28 @@ Optimization for both classical search engines AND generative engines (ChatGPT,
 - Knowledge graph
 - Breadcrumbs
 
+### AI Pipeline Optimization
+- **Chunk architecture** — design each H2 section as a self-contained ~375-word answer unit (≤500 tokens); each H3 is a separate chunk candidate
+- **Semantic triple authoring** — Subject → Predicate → Object factual statements over marketing prose ("toughness: H3, dimensions: 160×200 cm" vs "exceptional quality")
+- **Opinionated content** — clear declarative recommendations over hedged language ("we recommend X for Y" not "X may be worth considering")
+- **Decision frameworks** — "if X → choose Y" constructions, the most-cited AI pattern
+- **Contrast and comparison** — Jetstream signal: explicit "X vs Y", "unlike X, Y does…" patterns boost AI citation probability
+- **Negative definitions** — "not recommended for Z" covers AI exclusion sub-queries
+- **Freshness management** — refresh key pages before the 13-week threshold; update `dateModified` in JSON-LD AND visible text
+
+### Topical Authority & Cluster Design
+- **Pillar + cluster architecture** — one comprehensive pillar page linking to focused cluster articles per topic
+- **Internal linking** — ~1 contextual link per 800 chars, descriptive anchor text (never "click here")
+- **Orphan page detection** — every content page needs at least one inbound internal link
+- **Keyword cannibalization** — identify and consolidate pages competing for the same primary keyword
+- **Natural-language URLs** — 5–7 descriptive words; ID-based slugs lose ~11.4% AI citation rate
+
+### Multi-Platform SEO
+- **Video metadata** — YouTube title, description, and chapters function as SEO signals; shorts/Reels appear in Google SERP carousels
+- **Visual search** — unique product images + contextual alt text for Google Lens and Circle to Search; avoid stock-only imagery
+- **Social SEO** — Reddit, Quora, Wykop presence for Google's Hidden Gems algorithm; authentic participation, not spam
+- **Hook-first video** — first 3 seconds determine retention (Instagram measures it explicitly); no logo intros or "hi, my name is…" openings
+
 ## Technical Checklist
 
 ### Meta Tags
@@ -155,13 +181,18 @@ Goal: get cited by ChatGPT, Claude, Perplexity, Gemini, and Google AI Overviews
 
 ### GEO audit checklist
 - [ ] First sentence of every page answers the page's title as a question
+- [ ] Each H2 section is ≤375 words (chunk boundary); longer sections split with H3
+- [ ] No hedging language ("may be", "worth considering", "for many people") in recommendation contexts — replaced with declarative stance
+- [ ] At least one decision framework ("if X → choose Y") per guide or category page
+- [ ] At least one explicit contrast ("X vs Y", "unlike X, Y…") per comparison page
+- [ ] At least one negative definition ("not recommended for…") per product or category page
 - [ ] At least one comparison table OR numbered list per long-form page
-- [ ] Author block with name + role + LinkedIn / GitHub / ORCID
-- [ ] Schema.org `Article` with `author`, `datePublished`, `dateModified`
+- [ ] Author block with real name (not "Admin"), role, and ≥30 words of bio
+- [ ] Schema.org `Article` with `author` (`Person` + `sameAs`), `datePublished`, `dateModified`
 - [ ] Schema.org `FAQPage` for any page with Q/A structure
+- [ ] `dateModified` updated AND visible "Updated: [date]" text present
 - [ ] `llms.txt` at site root with curated canonical URLs
 - [ ] Page contains at least 3 unique data points (numbers, dates, version strings)
-- [ ] Date visible to the user, not just in metadata
 - [ ] No paywall / login wall on indexable content
 - [ ] No JavaScript-only content for primary value (LLM crawlers often skip JS)
 - [ ] Internal links use claim-as-anchor, not "click here"

package/app/hooks/quality-gate.sh

@@ -1,48 +1,60 @@
 #!/usr/bin/env bash
 # quality-gate.sh — Block task completion if lint/type errors found.
 #
-# Fires on: TaskCompleted
-# Exit 2 = block completion. Skipped when TOOLKIT_HOOK_PROFILE=minimal.
+# Fires on: Stop, TaskCompleted
+# Exit 2 = block completion/stop. Skipped when TOOLKIT_HOOK_PROFILE=minimal.
 # Strict profile also runs mypy.
 
 # shellcheck source=_profile-check.sh
 source "$(dirname "$0")/_profile-check.sh"
 
-if [ -f pyproject.toml ] || [ -f setup.py ]; then
-    ruff check . 2>&1 | head -30
-    exit_code=$?
+run_required() {
+    local label="$1"
+    local preview_cmd="$2"
+    shift 2
+
+    local tmp
+    tmp="$(mktemp "${TMPDIR:-/tmp}/ai-toolkit-quality.XXXXXX")"
+    "$@" >"$tmp" 2>&1
+    local exit_code=$?
+    eval "$preview_cmd" <"$tmp"
+    rm -f "$tmp"
+
     if [ $exit_code -ne 0 ]; then
-        echo "QUALITY GATE FAILED: ruff found errors. Fix them before completing." >&2
+        echo "QUALITY GATE FAILED: ${label}. Fix it before completing." >&2
         exit 2
     fi
+}
+
+require_command() {
+    local command_name="$1"
+    if command -v "$command_name" >/dev/null 2>&1; then
+        return 0
+    fi
+    echo "QUALITY GATE SKIPPED: ${command_name} is not installed." >&2
+    return 1
+}
+
+if [ -f pyproject.toml ] || [ -f setup.py ]; then
+    if require_command ruff; then
+        run_required "ruff found errors" "head -30" ruff check .
+    fi
     if [ -d src ] && [ "$PROFILE" = "strict" ]; then
-        mypy --strict src/ 2>&1 | tail -5
-        exit_code=$?
-        if [ $exit_code -ne 0 ]; then
-            echo "QUALITY GATE FAILED: mypy found type errors." >&2
-            exit 2
+        if require_command mypy; then
+            run_required "mypy found type errors" "tail -5" mypy --strict src/
         fi
     fi
 elif [ -f package.json ] && [ -f tsconfig.json ]; then
-    npx tsc --noEmit 2>&1 | tail -10
-    exit_code=$?
-    if [ $exit_code -ne 0 ]; then
-        echo "QUALITY GATE FAILED: TypeScript compilation errors." >&2
-        exit 2
+    if require_command npx; then
+        run_required "TypeScript compilation errors" "tail -10" npx tsc --noEmit
     fi
 elif [ -f pubspec.yaml ]; then
-    dart analyze 2>&1 | tail -10
-    exit_code=$?
-    if [ $exit_code -ne 0 ]; then
-        echo "QUALITY GATE FAILED: Dart analysis issues." >&2
-        exit 2
+    if require_command dart; then
+        run_required "Dart analysis issues" "tail -10" dart analyze
     fi
 elif [ -f go.mod ]; then
-    go vet ./... 2>&1 | tail -10
-    exit_code=$?
-    if [ $exit_code -ne 0 ]; then
-        echo "QUALITY GATE FAILED: Go vet issues." >&2
-        exit 2
+    if require_command go; then
+        run_required "Go vet issues" "tail -10" go vet ./...
     fi
 fi
 

package/app/hooks.json

@@ -150,6 +150,16 @@
                         "command": "\"$HOME/.softspark/ai-toolkit/hooks/save-session.sh\""
                     }
                 ]
+            },
+            {
+                "_source": "ai-toolkit",
+                "matcher": "",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "\"$HOME/.softspark/ai-toolkit/hooks/quality-gate.sh\""
+                    }
+                ]
             }
         ],
         "TaskCompleted": [

package/app/skills/seo-validate/SKILL.md

@@ -6,7 +6,7 @@ effort: medium
 disable-model-invocation: true
 context: fork
 agent: seo-specialist
-argument-hint: "[path] [--scope full|technical|content|performance|geo|rendering] [--severity high|warn|info] [--framework auto|next|nuxt|astro|gatsby|sveltekit|remix|angular|vue|react-spa|vite-spa|cra|static] [--rendering auto|csr|ssr|ssg|isr|hybrid] [--output markdown|json]"
+argument-hint: "[path] [--scope full|technical|content|performance|geo|rendering|topical] [--severity high|warn|info] [--framework auto|next|nuxt|astro|gatsby|sveltekit|remix|angular|vue|react-spa|vite-spa|cra|static] [--rendering auto|csr|ssr|ssg|isr|hybrid] [--output markdown|json]"
 allowed-tools: Read, Grep, Glob, Bash
 ---
 
@@ -14,7 +14,7 @@ allowed-tools: Read, Grep, Glob, Bash
 
 $ARGUMENTS
 
-Scan a codebase for SEO issues using pattern-matching heuristics. Detects W3C/HTML violations, meta tag gaps, structured data problems, hreflang errors, Core Web Vitals risks (LCP/INP/CLS), resource-hint misuse, above-the-fold anti-patterns, GEO gaps, SPA/CSR/SSG crawlability problems, technical SEO misconfigurations, and accessibility-for-SEO issues. Read-only — never modifies files.
+Scan a codebase for SEO issues using pattern-matching heuristics. Detects W3C/HTML violations, meta tag gaps, structured data problems, hreflang errors, Core Web Vitals risks (LCP/INP/CLS), resource-hint misuse, above-the-fold anti-patterns, GEO gaps (chunk architecture, hedging language, decision frameworks, semantic triples, freshness), topical authority gaps (pillar/cluster structure, orphan pages, cannibalization), SPA/CSR/SSG crawlability problems, technical SEO misconfigurations, and accessibility-for-SEO issues. Read-only — never modifies files.
 
 **Standards basis**: W3C HTML5 Recommendation, W3C WCAG 2.2, Schema.org vocabulary, IETF RFC 5646 (BCP 47 language tags) for hreflang, web.dev Core Web Vitals thresholds (LCP <2.5s, INP <200ms, CLS <0.1), Google Search Central crawlability guidelines, and emerging GEO (Generative Engine Optimization) practices.
 
@@ -26,6 +26,7 @@ Scan a codebase for SEO issues using pattern-matching heuristics. Detects W3C/HT
 /seo-validate --scope rendering              # Only SPA/CSR/SSG crawlability checks
 /seo-validate --scope performance            # Only Core Web Vitals static signals
 /seo-validate --scope geo                    # Only GEO (Generative Engine Optimization)
+/seo-validate --scope topical               # Only topical authority and cluster architecture
 /seo-validate --severity high                # Filter to HIGH findings only
 /seo-validate --framework next               # Force framework (skip auto-detection)
 /seo-validate --rendering csr                # Force rendering-mode interpretation
@@ -33,12 +34,13 @@ Scan a codebase for SEO issues using pattern-matching heuristics. Detects W3C/HT
 ```
 
 **Scopes:**
-- `full` (default) — all 9 categories
+- `full` (default) — all 10 categories
 - `technical` — HTML semantics, hreflang, CWV, rendering, technical SEO (categories 1, 4, 5, 7, 8)
 - `content` — meta/OG, structured data, GEO, a11y-for-SEO (categories 2, 3, 6, 9)
 - `performance` — only CWV static signals (category 5)
-- `geo` — only GEO (category 6)
+- `geo` — only GEO / citability checks (category 6)
 - `rendering` — only category 7 (SPA/CSR/SSG crawlability) — useful for migration audits
+- `topical` — only topical authority and cluster architecture (category 10)
 
 **Severity filtering:** `--severity high` shows only HIGH, `--severity warn` shows HIGH+WARN, `--severity info` shows all. Default: all.
 
@@ -273,20 +275,30 @@ See: [reference/core-web-vitals.md](reference/core-web-vitals.md)
 
 ### Category 6: GEO (Generative Engine Optimization)
 
-Content structure for AI answer engines (ChatGPT, Perplexity, Google AI Overviews, Bing Copilot). **All findings here are severity `INFO`** — emerging practice, not penalty-causing.
+Content structure for AI answer engines (ChatGPT, Perplexity, Google AI Overviews, Bing Copilot, Google AI Mode). **Most findings here are severity `INFO` or `WARN`** — guidance based on measured citation patterns, not penalty-causing.
+
+Google's retrieval stage splits content into chunks of ≤500 tokens (~375 words). Each section must be a self-contained answer unit. See [reference/ai-pipeline.md](reference/ai-pipeline.md) for the full 4-stage pipeline and 7 ranking signals. See [reference/content-citability.md](reference/content-citability.md) for chunk anatomy, semantic triples, and hedging patterns.
 
 | Pattern | Severity | Confidence | Description |
 |---------|----------|------------|-------------|
 | No `FAQPage` schema on FAQ-style content | INFO | heuristic | Highly extractable by LLMs |
 | No `speakable` schema on summary content | INFO | heuristic | Voice/audio answer engines |
-| Long paragraphs (>400 words) without sub-headings | INFO | heuristic | Harder for LLMs to extract |
+| H2 section body exceeds ~375 words without an H3 sub-heading | WARN | heuristic | Exceeds single chunk boundary (~500 tokens); AI cannot extract cleanly — split with H3 |
+| First paragraph under a heading exceeds 60 words before a concrete fact, number, or direct recommendation | INFO | heuristic | AI extracts first 2–3 sentences as the answer; preamble displaces the answer |
+| Hedging language in recommendation or product context: "may be", "might be", "could be", "worth considering", "for many", "for most people" | INFO | heuristic | AI skips hedged claims; Jetstream signal rewards declarative recommendations (see [content-citability.md](reference/content-citability.md)) |
+| No decision framework ("if X → choose Y" / "for X, use Y") in guide or category content | INFO | heuristic | Decision frameworks are the most-cited AI construction; covers Jetstream cross-attention signal |
+| No contrast or comparison ("X vs Y", "unlike X", "in contrast to X") in content with comparative headings | INFO | heuristic | Jetstream directly rewards explicit contrasts; absence reduces AI citation probability |
+| No negative definition ("not recommended for", "not suitable for", "avoid if") on product or category pages | INFO | heuristic | Covers AI exclusion sub-queries ("which product is not for stomach sleepers?") |
+| Author name uses generic placeholder: "Admin", "Team", "Staff", "Editor", or no author at all | WARN | heuristic | E-E-A-T Experience signal requires a real named author; generic names suppressed by Google Bury Rules |
+| Author block contains fewer than 30 words of bio text near the author name | INFO | heuristic | LLM answer engines use author credentials as an authority signal; stub bios do not qualify |
+| Article `dateModified` (JSON-LD or `<time>`) is older than 13 weeks with no visible update notice | WARN | heuristic | 50% of top AI-cited content updated within 13 weeks (Blyskall, 40M AI Overviews study); stale content drops from citation pools |
 | Missing explicit citation/source markup (`<cite>`, author bylines) | INFO | heuristic | LLM answer engines prefer attributable sources |
 | No `<q>` or quote schema on quoted content | INFO | heuristic | Aids AI extraction |
 | No Q&A structure on how-to content | INFO | heuristic | LLMs favor structured Q&A |
 | Heavy reliance on `<div>` over semantic HTML | INFO | heuristic | Semantic HTML improves AI parsing |
 | Key facts hidden behind JS interactions (tabs, accordions) | INFO | heuristic | LLMs see initial DOM only |
 
-See: [reference/geo-guidelines.md](reference/geo-guidelines.md)
+See: [reference/geo-guidelines.md](reference/geo-guidelines.md), [reference/content-citability.md](reference/content-citability.md), [reference/ai-pipeline.md](reference/ai-pipeline.md)
 
 ---
 
@@ -385,6 +397,23 @@ Accessibility ↔ SEO overlap. WCAG compliance improves ranking signals.
 
 ---
 
+### Category 10: Topical Authority & Cluster Architecture
+
+Topical authority is the degree to which a domain is recognised as an expert source across an entire topic, not just individual pages. AI retrieval (Gecko Score / semantic embedding) rewards domains with deep, interlinked coverage. Classical SEO also benefits — Senuto's study of 212K phrases across 7,200 semantic groups showed topical coverage dominates top-10 rankings independently of individual technical metrics.
+
+| Pattern | Severity | Confidence | Description |
+|---------|----------|------------|-------------|
+| Long-form page (>800 words) has internal link density below 1 link per 800 characters of body text | WARN | heuristic | Google's internal linking guideline: ~1 contextual internal link per 800 chars; low density = weak cluster signal |
+| Internal link uses generic anchor text: "click here", "read more", "here", "this page", "learn more" | WARN | definitive | Anchor text is a topical signal; descriptive claim-based anchors transfer semantic context to the linked page |
+| Page >2,000 words with no outbound internal links to topically related pages | INFO | heuristic | Pillar pages must link out to cluster articles; absence breaks the pillar→cluster signal and reduces Gecko relevance |
+| Page has >500 words of indexable content with zero detected inbound internal links (orphan page) | WARN | heuristic | Orphan pages receive minimal crawl budget and no authority pass-through; every content page needs at least one inbound link |
+| Content page URL slug contains numeric IDs, UUIDs, or is purely numeric (e.g., `/post/12345`, `/p/abc-uuid`) | WARN | heuristic | Natural-language slugs (5–7 descriptive words) show +11.4% AI citation rate vs. ID-based URLs (Blyskall study) |
+| Two or more pages on the same domain target the same primary keyword in H1 and title | WARN | heuristic | Keyword cannibalization: pages compete against each other, diluting authority; consolidate into pillar + cluster |
+
+**Topical authority strategy note:** Query Fan Out means AI generates 50+ sub-queries per user question, 95% of which have zero Monthly Search Volume in any keyword tool. Covering a topic with a pillar + cluster architecture answers the full sub-query space that keyword tools cannot see. See [reference/ai-pipeline.md](reference/ai-pipeline.md).
+
+---
+
 ## Output Format
 
 ```markdown
@@ -393,7 +422,7 @@ Accessibility ↔ SEO overlap. WCAG compliance improves ranking signals.
 ### Summary
 | Metric | Value |
 |--------|-------|
-| Scope | full / technical / content / performance / geo / rendering |
+| Scope | full / technical / content / performance / geo / rendering / topical |
 | Framework detected | next / nuxt / astro / gatsby / sveltekit / remix / angular / vue / react-spa / vite-spa / cra / static |
 | Rendering mode | csr / ssr / ssg / isr / hybrid |
 | Files scanned | N |
@@ -445,7 +474,7 @@ See: reference/spa-ssg-patterns.md#react-spa-migration
 - **Standards citation**: Every HIGH/WARN finding must cite a W3C/Schema.org/RFC/web.dev reference.
 - **Skip non-source files**: Binary files, lock files (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`), vendored directories (`node_modules/`, `vendor/`, `.git/`, `dist/`, `build/`, `out/`, `.next/`, `.nuxt/`, `.svelte-kit/`, `public/build/`).
 - **No false confidence**: Label heuristic findings clearly; above-the-fold detection is always heuristic.
-- **GEO is INFO-only**: Never flag GEO findings as HIGH/WARN — it is emerging practice.
+- **GEO severity**: Category 6 findings may be WARN (chunk size, author quality, freshness) or INFO (hedging, frameworks, contrast, bio) — see table. Never raise GEO findings to HIGH.
 - **SPA HIGH bar**: Only flag Category 7 HIGH when the app is clearly a content site (has public routes with meaningful content). Auth-gated apps (dashboards, admin panels) should stay at WARN/INFO since SEO is not a concern.
 - **Noscript is not a substitute for SSR/SSG**: `<noscript>` catches only the "no-JS" case, not the "crawler without JS execution" case — don't upgrade a CSR HIGH to WARN just because noscript exists.
 - **No auto-fix in v1**: Fixing SEO issues requires design/content decisions beyond pattern matching.
@@ -454,7 +483,9 @@ See: reference/spa-ssg-patterns.md#react-spa-migration
 
 - [reference/w3c-guidelines.md](reference/w3c-guidelines.md) — HTML5 semantic requirements, meta tag specs, language tag rules.
 - [reference/core-web-vitals.md](reference/core-web-vitals.md) — LCP/INP/CLS thresholds, resource hints, above-the-fold heuristic, per-framework image components.
-- [reference/geo-guidelines.md](reference/geo-guidelines.md) — GEO principles, `speakable` schema, citation/source markup, AI-extractable content structure.
+- [reference/geo-guidelines.md](reference/geo-guidelines.md) — GEO principles, `speakable` schema, citation/source markup, AI-extractable content structure, chunk anatomy, 13-week freshness strategy.
 - [reference/geo-aeo-patterns.md](reference/geo-aeo-patterns.md) — AEO (Answer Engine Optimization): `FAQPage`/`HowTo`/`QAPage` schema, `llms.txt`, AI bot `robots.txt` directives, E-E-A-T signals, automated grep patterns for Category 6.
+- [reference/content-citability.md](reference/content-citability.md) — Chunk architecture, semantic triples, opinionated vs hedging language, decision frameworks, contrast patterns, negative definitions, justified superlatives, grep patterns.
+- [reference/ai-pipeline.md](reference/ai-pipeline.md) — Google's 4-stage AI pipeline (Prepare/Retrieve/Signal/Serve), 7 ranking signals (Gecko, Jetstream, PCTR, Freshness, BM25, Base, Boost/Bury), Query Fan Out, probabilistic ranking, format routing.
 - [reference/schema-types.md](reference/schema-types.md) — Schema.org JSON-LD templates (Article, FAQ, BreadcrumbList, Organization, Product, LocalBusiness) with required properties.
 - [reference/spa-ssg-patterns.md](reference/spa-ssg-patterns.md) — Rendering-mode decision tree, SPA pitfalls, per-framework detection patterns, prerendering strategies.