@softspark/ai-toolkit 4.0.1 → 4.2.0

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,70 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## 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.
+
+### Added
+
+- **`app/rules/output-mode.md`** — auto-injected into `~/.claude/CLAUDE.md` (global) and project-local `CLAUDE.md` via the existing `inject_rules()` mechanism on every `ai-toolkit install` / `ai-toolkit update`.
+- **`rule_output_mode()` in `scripts/dir_rules_shared.py`** — registered in `STANDARD_RULES`, so directory-based generators (Cursor `.mdc`, Windsurf, Cline, Roo, Augment, Codex, Antigravity) emit a dedicated `ai-toolkit-output-mode.md` file alongside the other six standard rules.
+- **Output Mode block in `scripts/generator_base.render_generator()`** — single-file editor outputs (`GEMINI.md`, `.github/copilot-instructions.md`, `.cursorrules`, Aider `CONVENTIONS.md`) now include the directive between TOOLKIT markers.
+
+### Directives
+
+The `concise` mode applies these rules to assistant responses:
+
+- No preamble — skip "I'll now…", "Sure, let me…", "Great question!"
+- Lead with the result; explanation only if asked or non-obvious.
+- Max 3 sentences per closed question.
+- Tables and lists over prose for comparisons, steps, values.
+- No trailing summaries when the diff or output already shows what changed.
+- Drop filler adjectives ("nice", "great", "powerful", "robust").
+- Cite as `path:line`, not paragraphs of location prose.
+- Escalate to verbose only for architecture / RFC / ADR / trade-off documents or explicit user request.
+
+### Changed
+
+- **Standard rule count for directory-based generators: 6 → 7**. Tests updated: `tests/test_generators.bats` (count assertions in two cases bumped from 6/8 to 7/9).
+
+### How to opt out
+
+- Per-session: `/brand-voice default` (or `/brand-voice strict` for tighter)
+- Per-project: edit `output-mode:` value in project's `CLAUDE.md` or strip the `<!-- TOOLKIT:output-mode -->` block manually
+- Re-install without rules: `ai-toolkit install --skip rules`
+
+### Why
+
+User feedback after v4.0.x consolidation: asked for a hook-like mechanism to enforce concise responses. The `brand-voice` skill already had `concise`/`strict` modes (shipped v3.2.0) but activation required per-project opt-in. This release flips the default to opt-out — every editor that consumes ai-toolkit configs now sees the directive immediately after install/update.
+
+---
+
 ## v4.0.1 — CI hotfix: README "What You Get" table counts (2026-05-06)
 
 Patch release. Fixes CI failure on v4.0.0 main branch — three `tests/test_metadata_contracts.bats` cases failed because the `What You Get` table in `README.md` and the skill type table in `kb/reference/architecture-overview.md` still referenced pre-consolidation counts (32 task / 32 hybrid / 48 knowledge).

package/README.md

@@ -14,28 +14,14 @@
 
 ---
 
-## What's New in v4.0.1
+## What's New in v4.2.0
 
-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.
+SEO/GEO release focused on AI citation readiness and stricter release gates.
 
-## 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
-
-| 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` |
+- **AI pipeline guidance**: `seo-validate` now includes Google AI pipeline, Query Fan Out, and content citability references.
+- **Topical authority checks**: new `--scope topical` covers cluster structure, internal links, orphan pages, slugs, and cannibalization.
+- **Expanded GEO heuristics**: Category 6 now checks chunk boundaries, hedging, decision frameworks, freshness, and author quality.
+- **Release gate parity**: CI and `prepublishOnly` now run strict validation, and the URL rule test is hermetic.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 

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.0.1",
+  "version": "4.2.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

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/rules/output-mode.md

@@ -0,0 +1,28 @@
+# Output Mode
+
+`output-mode: concise`
+
+Default response mode for this project is **concise**. The `brand-voice` skill (when present in ai-toolkit) auto-loads its `concise` rules; assistants without that skill should still apply the directives below.
+
+## Concise Mode Directives
+
+- **No preamble.** Skip "I'll now...", "Sure, let me...", "Great question!" and similar warm-ups. Start with the answer.
+- **Lead with the result.** Conclusion or output first; explanation only if asked or non-obvious.
+- **Max 3 sentences per closed question.** Yes/no, single-fact, or "where is X" answers stay under three sentences.
+- **Tables and lists over prose** when comparing options, listing steps, or showing values.
+- **No trailing summaries.** If the diff or output already shows what changed, do not restate it.
+- **Drop filler adjectives.** No "nice", "great", "powerful", "robust" unless the user asked for evaluation.
+- **Cite file paths as `path:line`** instead of paragraphs describing where things live.
+- **Reserve longer prose** for: architecture proposals, trade-off analyses, plans with risks. Everything else: terse.
+
+## When to escalate to verbose
+
+- User explicitly asks: "explain in detail", "walk me through", "give me the full picture".
+- Reporting a non-obvious failure mode where missing context would mislead.
+- Architecture / RFC / ADR / trade-off documents — those have their own structure.
+
+## How to override
+
+- Per-session: `/brand-voice default` (or `/brand-voice strict` for even tighter)
+- Per-project: change this rule's `output-mode:` value in the project's `CLAUDE.md`
+- Permanent removal: re-run `ai-toolkit install --skip rules` or strip the `<!-- TOOLKIT:output-mode -->` block manually

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.

package/app/skills/seo-validate/reference/ai-pipeline.md

@@ -0,0 +1,204 @@
+# Google AI Pipeline
+
+Reference for `seo-validate` — understanding how Google processes content for AI Search. Informs Category 6 (GEO) and Category 10 (Topical Authority) findings.
+
+Source: Piotr Smargol, Indygo Agency — SEO Copywriting 2026.
+
+---
+
+## 1. The Four-Stage Pipeline
+
+Every query in Google AI Search (AI Overviews, AI Mode, and classical SERPs) passes through the same pipeline. The presentation layer differs; the engine is the same.
+
+```
+User Query
+    │
+    ▼
+┌─────────────────────────────────────────────────┐
+│  Stage 1: PREPARE                               │
+│  NLU — synonym mapping — intent classification  │
+│  Query Fan Out (synthetic sub-queries)          │
+└─────────────────────────────────────────────────┘
+    │
+    ▼
+┌─────────────────────────────────────────────────┐
+│  Stage 2: RETRIEVE                              │
+│  Content divided into chunks (≤500 tokens)      │
+│  Layout parsed — embeddings computed (Gecko)    │
+└─────────────────────────────────────────────────┘
+    │
+    ▼
+┌─────────────────────────────────────────────────┐
+│  Stage 3: SIGNAL                                │
+│  7 ranking signals applied per chunk candidate  │
+└─────────────────────────────────────────────────┘
+    │
+    ▼
+┌─────────────────────────────────────────────────┐
+│  Stage 4: SERVE                                 │
+│  Gemini 2.5 Flash generates the final answer    │
+│  Inline source citations added                  │
+└─────────────────────────────────────────────────┘
+```
+
+**Key implication for copywriters:** AI does not read your article — it extracts a chunk and pastes it as an answer. Each section must be a self-contained answer unit. If the answer is scattered across the article, AI cannot assemble it.
+
+---
+
+## 2. The Seven Ranking Signals
+
+Google applies seven signals to decide which chunk from which source appears in the answer.
+
+### Signal 1 — Base Ranking
+Classical relevance algorithm (PageRank descendants). SEO fundamentals still matter. High-authority domains get a floor advantage, but content structure can compensate.
+
+**Copywriter implication:** Standard on-page SEO (title, H1, internal linking) remains the foundation.
+
+---
+
+### Signal 2 — Gecko Score (Semantic Embedding Similarity)
+Gecko is Google's embedding model. It measures how semantically close your chunk is to the user's query — not keyword overlap, but meaning overlap. A chunk about "mattress firmness" will score well for "which mattress is best for back pain" even without that exact phrase.
+
+**Copywriter implication:** Cover the topic from multiple angles and personas. Topical depth beats keyword density. A single cluster of related articles scores higher than one over-optimised page.
+
+---
+
+### Signal 3 — Jetstream (Cross-Attention)
+Jetstream is the model's ability to understand context, contrasts, negations, and comparisons within a chunk. It specifically rewards:
+
+- `X vs Y` comparisons
+- Negations: "not recommended for…", "avoid if…", "unlike X…"
+- Conditional statements: "best for…", "ideal for…", "if X, choose Y"
+- Contrast phrases: "in contrast to X, Y does…", "unlike foam, latex…"
+
+**Copywriter implication:** These constructions are not just reader-friendly — they are a direct Jetstream signal. Content with explicit comparisons and decision frameworks is over-represented in AI citations.
+
+---
+
+### Signal 4 — BM25 (Keyword Matching)
+The classic TF-IDF/BM25 algorithm is still active. Exact keyword matches in headings and early paragraphs contribute. Not dominant, but present.
+
+**Copywriter implication:** Include the primary keyword in H2 headings and in the first sentence of each section. Do not keyword-stuff — BM25 has diminishing returns and Gecko penalises unnatural density.
+
+---
+
+### Signal 5 — PCTR (Predicted Click-Through Rate)
+Google estimates how likely users are to click your result based on historical CTR patterns for that title format, topic, and position. High PCTR boosts a chunk's probability of being included in the AI answer.
+
+**Copywriter implication:** Title and meta description quality directly affects AI citation probability — not just traditional click traffic. Use benefit-led titles. Avoid clickbait (Google's AI pipeline detects and suppresses it). Brand at the end of the title.
+
+---
+
+### Signal 6 — Freshness
+Content age is weighted by topic type:
+
+| Topic type | Freshness weight |
+|---|---|
+| Breaking news | Dominant — stale content is excluded |
+| Technology / AI / tools | High — 13-week threshold observed |
+| Evergreen how-to | Moderate — update signals matter |
+| Historical / definitions | Low — accuracy over recency |
+
+**The 13-week rule:** Research across top AI-cited content shows 50% of cited results were published or updated within the last 13 weeks. Evergreen pages that are not refreshed drop out of AI citation pools gradually.
+
+**Copywriter implication:** Add visible `dateModified` to all indexable pages. Refresh key articles before the 13-week threshold. Use "Updated: [date]" visible to users, not just in JSON-LD.
+
+---
+
+### Signal 7 — Boost/Bury Rules
+Manual editorial adjustments applied by Google. Certain sources are systematically boosted (e.g., Reddit, YouTube, Wikipedia, government and academic domains). Certain patterns are buried (AI-generated content without human editing, thin content, pages without authors).
+
+**Copywriter implication:** Named authors with bylines and bios protect content from Bury Rules. Generic AI-generated text without editorial review is actively suppressed.
+
+---
+
+## 3. Query Fan Out
+
+When a user submits a query, the AI does not search only for that query. It generates dozens of synthetic sub-queries internally and retrieves candidate chunks for each.
+
+```
+User query: "which laptop for remote work"
+                      │
+           ┌──────────┴──────────┐
+           ▼                     ▼
+  "best laptops remote work 2026"    "lightweight laptop long battery"
+           │                         │
+           ▼                         ▼
+  "MacBook vs ThinkPad remote"    "quiet fan laptop home office"
+           │                         │
+           ▼                         ▼
+  "budget laptop for Zoom"        "laptop under 1000 remote work"
+           │
+           ▼
+  "best keyboard laptop coding"
+  … (50+ more sub-queries)
+```
+
+### The 95% problem
+
+**95% of these sub-queries have zero Monthly Search Volume** in Semrush, Ahrefs, Senuto, or any keyword tool. Classical keyword research shows only 5% of the actual retrieval surface.
+
+**Copywriter implication:**
+- Stop optimising for a single phrase per page.
+- Cover the topic from multiple persona angles: beginner vs expert, budget vs premium, use case A vs use case B.
+- Answer implicit sub-questions within the same article using H2/H3 sections.
+- Cluster architecture (pillar + cluster articles) is the structural response to Query Fan Out.
+
+---
+
+## 4. Probabilistic Ranking
+
+In classical SEO, "position 1" was deterministic — the same for every user. In AI Search, ranking is probabilistic: two users sending the identical query can receive different answers.
+
+AI personalises based on:
+- Search history and session context
+- Location and language
+- Inferred demographic profile
+- Device type
+- Stochastic variation in model generation
+
+**Implication:** There is no single position to win. There is a **probability of being cited**. Maximise that probability by:
+1. Covering the topic from multiple perspectives (different personas, contexts, formats).
+2. Being present in multiple chunk positions within a long article (each H2 is a citation candidate).
+3. Publishing cluster articles that address sub-queries individually.
+4. Maintaining freshness so your chunk stays in the retrieval pool.
+
+---
+
+## 5. Format Routing
+
+The AI routes queries to content formats. If your format does not match the query type, you lose — even with superior content.
+
+| Query pattern | Optimal content format | Schema signal |
+|---|---|---|
+| `how to X` | Numbered step-by-step tutorial | `HowTo` |
+| `X vs Y` | Side-by-side comparison table | `Article` + table markup |
+| `show me X` | Visual: image gallery or video | Image alt + video schema |
+| `latest / best X in [year]` | Freshly updated article with date | `Article` + `dateModified` |
+| `reviews of X` / `what do people think of X` | UGC aggregation or forum discussion | `Review`, `AggregateRating` |
+| `what is X` | Definition paragraph + entity context | `Article` with entity-first opening |
+| `X for [persona]` | Persona-targeted guide | `Article` + `FAQPage` |
+| `is X worth it` | Opinionated recommendation with evidence | `Article` with author + data |
+
+**Copywriter implication:** Before writing, determine the dominant query pattern for the page's topic. Structure the page to match that format. Mismatched format = invisible to AI routing.
+
+---
+
+## 6. The Two-Audience Reality
+
+| Audience | Wins with | Metric |
+|---|---|---|
+| Fast AI (simple information queries) | Structured chunks, direct answers, semantic triples | AI citation probability |
+| Human readers (purchase decisions, complex topics) | Narrative, trust signals, social proof, UGC | Engagement, conversion |
+
+**Strategy:** Pages must serve both simultaneously. Chunk-optimised structure aids AI extraction without harming human readability — they are the same discipline (clear headings, direct answers, no filler).
+
+---
+
+## References
+
+- Google Search Central — How Google Search works: https://developers.google.com/search/docs/fundamentals/how-search-works
+- Google Gecko embedding model: https://research.google/pubs/gecko-versatile-text-embeddings-distilled-from-large-language-models/
+- Blyskall study — 40M AI Overviews results, backlink vs content signals: referenced in SEO Copywriting 2026 (Smargol, Indygo Agency)
+- Senuto topical authority study — 212K phrases, 7,200 semantic groups
+- Google AI Mode announcement (March 2025): https://blog.google/products/search/google-ai-mode-search/

package/app/skills/seo-validate/reference/content-citability.md

@@ -0,0 +1,372 @@
+# Content Citability Patterns
+
+Reference for `seo-validate` Category 6 (GEO). Covers the structural and linguistic patterns that maximise AI citation probability. Companion to [geo-guidelines.md](geo-guidelines.md) and [ai-pipeline.md](ai-pipeline.md).
+
+Source: Piotr Smargol, Indygo Agency — SEO Copywriting 2026.
+
+---
+
+## 1. Chunk Architecture
+
+### The 500-token boundary
+
+Google's retrieval stage splits content into chunks of **maximum 500 tokens (~375 words)**. AI does not summarise your article — it extracts one chunk and uses it as the answer. If the answer to a question is distributed across multiple sections or buried after a long preamble, AI cannot assemble it.
+
+**Rules:**
+- Each H2 section should stay within ~375 words.
+- If a section exceeds this, split with an H3 sub-heading — each H3 becomes its own chunk candidate.
+- Never put the answer at the end of a section after a long setup.
+
+### Anatomy of a citable chunk
+
+Every section should follow this structure:
+
+```
+H2: [Question or keyword-rich title]
+│
+├── Direct answer — 2–3 sentences. No preamble. The fact first.
+│
+├── Elaboration — data, context, nuance. 3–5 sentences.
+│
+├── Visual element — list, table, or code block.
+│
+└── TL;DR (optional, for long sections) — 1-sentence summary.
+```
+
+### Before / after examples
+
+**Before (unchunkable):**
+```
+H2: Choosing the Right Mattress
+
+When you're looking for a new mattress, there are many factors to consider.
+The market offers a wide variety of options, and it can be overwhelming to
+navigate. Let's explore the key aspects you should think about before making
+a purchase decision, because getting this right is important for your sleep
+quality and long-term health. After all, we spend a third of our lives in bed.
+
+Eventually, firmness is one of the most important factors. For people under
+70 kg, a softer H1–H2 rating works well.
+```
+*Problem: answer buried after 80-word preamble; AI extracts the preamble as the "answer".*
+
+**After (chunk-optimised):**
+```
+H2: How to Choose Mattress Firmness by Body Weight
+
+Match firmness to your weight: under 70 kg → H1 or H2; 70–90 kg → H3;
+over 90 kg → H4. Higher body weight needs firmer support to maintain
+spinal alignment.
+
+| Weight | Recommended firmness |
+|--------|----------------------|
+| < 70 kg | H1–H2 (soft–medium) |
+| 70–90 kg | H3 (medium-firm) |
+| > 90 kg | H4 (firm) |
+
+**TL;DR:** Firmness = body weight ÷ 10, rounded up to the nearest H-rating.
+```
+*Result: AI extracts the first two sentences as the answer; table is bonus precision.*
+
+---
+
+## 2. Semantic Triples
+
+### What they are
+
+A semantic triple is the simplest factual statement AI can parse without inference or guessing:
+
+```
+Subject → Predicate → Object
+```
+
+LLMs are trained on structured knowledge graphs built from triples. Content written as triples is extracted with high confidence and low hallucination risk.
+
+### Triple structure
+
+| Component | Role | Example |
+|---|---|---|
+| Subject | What/who is described | "Premium Mattress" |
+| Predicate | Property or relationship | "has firmness rating" |
+| Object | Value or target | "H3" |
+
+Assembled: "The Premium Mattress has a firmness rating of H3."
+
+### Stacking triples
+
+One product/topic should generate multiple triples covering all queryable properties:
+
+```
+Product X → has firmness → H3
+Product X → measures → 160 × 200 cm
+Product X → has height → 22 cm
+Product X → is ideal for → side sleepers weighing 70–90 kg
+Product X → is not recommended for → stomach sleepers
+Product X → pairs with → slatted base with max 5 cm gap
+```
+
+Each triple answers a different AI sub-query. Six triples = six citation opportunities.
+
+### Marketing prose vs semantic triples
+
+| Style | Example | AI extractable? |
+|---|---|---|
+| Marketing prose | "Our exceptional collection will enchant you with its elegance and superior comfort." | No — zero extractable facts |
+| Semantic triples | "Firmness: H3. Dimensions: 160×200 cm. Height: 22 cm. Ideal for side sleepers, 70–90 kg. Not recommended for stomach sleepers." | Yes — 5 distinct facts |
+
+**Rule:** Every product description, category page, and guide should contain a minimum of three semantic triples in the opening paragraph or a specification table.
+
+### Grep patterns
+
+```
+# Detect marketing filler (high prose density, low factual density)
+Pattern: \b(exceptional|extraordinary|unique|enchant|fascinate|remarkable|unparalleled|outstanding)\b
+Files: *.html, *.md, *.tsx, *.jsx, *.vue, *.svelte, *.astro
+Flag: marketing superlative without associated factual triple
+```
+
+---
+
+## 3. Opinionated Content vs Hedging Language
+
+### Why AI skips hedged claims
+
+AI answer engines extract concrete statements to synthesise answers. A hedged claim ("this might be a good choice for many people") cannot be used as a direct answer to "which mattress should I buy?" AI silently passes over it.
+
+**Google's Jetstream signal explicitly rewards** opinionated, declarative content over neutral, hedged content.
+
+### Hedging patterns to eliminate
+
+| Hedging phrase | Why it fails | Replacement |
+|---|---|---|
+| "may be a good choice" | Cannot be cited as a recommendation | "We recommend X for Y" |
+| "might work well for" | Conditional — AI skips | "Works best for" |
+| "worth considering" | No stance | "Our top pick for Z is X" |
+| "for many people" | Undefined persona | "for side sleepers weighing 70–90 kg" |
+| "could be ideal" | Speculative | "Is ideal for" |
+| "one option is" | Non-committal | "Choose X if you need Y" |
+| "it depends" (without resolution) | No extractable answer | "It depends on your weight: under 70 kg → H2, over 90 kg → H4" |
+
+### Opinionated writing rules
+
+1. **Take a position.** "We recommend X for Y" over "X is worth considering."
+2. **Name the persona.** "Ideal for side sleepers weighing 70–90 kg" over "suitable for most users."
+3. **Justify the claim.** AI cites "best for back pain because H3 stabilises the lumbar spine" — not "best for back pain" alone.
+4. **Use first-person plural for brand voice.** "We tested X and found…" establishes E-E-A-T Experience signal.
+
+### Grep patterns for hedging detection
+
+```
+# High-priority hedging (recommendation context)
+Pattern: \b(may be|might be|could be|worth considering|for many|for most people|it depends)\b
+Files: *.html, *.md, *.tsx, *.jsx, *.vue, *.astro
+Context: within 50 words of product name, category heading, or recommendation heading
+Severity: INFO
+```
+
+---
+
+## 4. Decision Frameworks
+
+### Why they dominate AI citations
+
+"If X → choose Y" is the most frequently cited construction in AI Search. It directly answers the user's decision-making intent, requires no interpretation, and maps cleanly to Query Fan Out sub-queries ("which X for Y?").
+
+### Formats
+
+**Conditional (if/then):**
+```
+If you sleep on your side → choose H2–H3 firmness.
+If you share a bed with a partner of significantly different weight → choose a split mattress.
+If you have chronic lower back pain → choose H3 with lumbar zone reinforcement.
+```
+
+**Use-case mapping:**
+```
+For home office video calls → prioritise battery life and weight under 1.5 kg.
+For graphic design work → prioritise display colour gamut (>95% DCI-P3).
+For travel → prioritise weight and keyboard quality for extended typing.
+```
+
+**Elimination framework (negative definition):**
+```
+NOT for: stomach sleepers, children under 12, anyone over 100 kg.
+```
+
+### Placement
+
+Decision frameworks belong:
+- In H2 "How to Choose" or "Which X for You" sections.
+- In product/category opening paragraphs (chunk position 1).
+- In FAQ answers (each answer = one framework).
+- In comparison tables (column "Best for:").
+
+### Grep patterns
+
+```
+# Detect absence of decision framework in guide/category pages
+Detect: (?i)<h[2-3][^>]*>(how to choose|which .* for|guide to|best .* for)
+Then check: (?i)\bif\b.{1,50}\b(choose|select|pick|go with|opt for)\b  OR  (?i)\bfor .{3,30}\b(choose|recommend|ideal|best)\b
+Flag if: guide heading found, no decision framework pattern within 500 words
+Severity: INFO
+```
+
+---
+
+## 5. Contrast Patterns (Jetstream Signal)
+
+Contrasts and comparisons are a direct Jetstream (cross-attention) signal. Content with explicit "X vs Y" structures is over-represented in AI answers for comparative queries.
+
+### Contrast constructions
+
+| Construction | Example |
+|---|---|
+| `X vs Y` heading | "Foam vs Latex Mattress: Which is Better?" |
+| "Unlike X, Y…" | "Unlike foam, latex responds instantly to movement." |
+| "In contrast to X…" | "In contrast to bonnell springs, pocket springs isolate motion." |
+| "X is better than Y for Z" | "Latex is better than foam for hot sleepers because it has open-cell structure." |
+| "Compared to X, Y offers…" | "Compared to H2 firmness, H3 provides 40% more lumbar support." |
+| Comparison table | Explicit columns for two or more options |
+
+### When to use contrasts
+
+- Every product category page should contain at least one "Category A vs Category B" section or table.
+- Blog guides should compare at least two options before making a recommendation.
+- Product descriptions should contrast with the alternative ("unlike [competitor type], this product…").
+
+### Grep patterns
+
+```
+# Detect comparative content missing contrast constructions
+Detect: (?i)\b(vs|versus|compare|comparison|difference between|X or Y)\b  in headings/titles
+Then check: (?i)(unlike|in contrast|compared to|better than|vs|versus)  in body text
+Then check: <table  present in the content
+Flag if: comparative heading found, no contrast language AND no comparison table
+Severity: INFO
+```
+
+---
+
+## 6. Negative Definitions
+
+Defining who/what a product is NOT for is a high-value signal for two reasons:
+
+1. **AI exclusion queries:** "which mattress is not for stomach sleepers" — only content with explicit negative definitions answers this.
+2. **Targeting precision:** Narrow persona definition increases citation probability for the right audience query.
+
+### Patterns
+
+```
+Not recommended for: stomach sleepers, children under 12, bodyweight over 120 kg.
+Not suitable for: use on adjustable bases without rigid slat support.
+Avoid if: you prefer a cloud-soft feel — this mattress is designed for firm support.
+This product is not designed for: outdoor use, temperatures below 5°C.
+```
+
+### Placement
+
+- Product descriptions: one "Not recommended for:" block near the persona definition.
+- Category pages: "Who this category is NOT for" subsection.
+- FAQ: "Is X right for me?" answer should include negative persona.
+
+### Grep patterns
+
+```
+# Check product/category pages for negative definition
+Detect: (?i)(not recommended for|not suitable for|avoid if|not designed for|not ideal for)
+Flag if: product or category page (detected by Product schema or URL pattern) has no negative definition
+Severity: INFO
+```
+
+---
+
+## 7. Justified Superlatives
+
+Superlatives without justification are ignored by AI ("best mattress" is marketing noise). Superlatives with evidence are cited.
+
+### Formula
+
+```
+[Superlative claim] + [specific reason] + [evidence or data]
+```
+
+### Examples
+
+| Bad (ignored) | Good (citable) |
+|---|---|
+| "The best mattress for back pain" | "The best mattress for back pain because H3 firmness maintains neutral lumbar alignment — validated by our customer data showing 78% pain reduction after 30 days." |
+| "Most durable laptop battery" | "Longest real-world battery life in the under-1.5 kg category — 14.2 hours in our standardised office test." |
+| "Premium quality" | "Premium build: aluminium chassis, ISO military-grade drop rating (MIL-STD-810H), 3-year warranty." |
+
+### Rule
+
+Every superlative must be followed within the same sentence by "because", "with", "achieving", or a colon introducing a specific measurement.
+
+---
+
+## 8. The 13-Week Freshness Threshold
+
+Research shows 50% of top AI-cited content was published or updated within the last 13 weeks (Blyskall, 40M AI Overviews results). After 13 weeks without a visible update, citation probability drops.
+
+### Freshness strategy
+
+| Action | Frequency | Priority pages |
+|---|---|---|
+| Full content review and update | Every 12 weeks | Top-traffic pillar pages |
+| Date + minor fact refresh | Every 13 weeks | High-competition cluster articles |
+| Add new FAQ or data point | On new data availability | Product pages, comparison guides |
+| Update `dateModified` in JSON-LD AND visible text | On every meaningful change | All indexable pages |
+
+### Visible freshness signals
+
+Both are required:
+1. JSON-LD `dateModified` field.
+2. Visible "Updated: [date]" or "Last reviewed: [date]" text near the article byline.
+
+JSON-LD alone is insufficient — AI engines parse visible text; users trust visible dates.
+
+---
+
+## 9. Author E-E-A-T (Experience Signal)
+
+Google's most important E-E-A-T shift in 2025 was elevating **Experience** — content from someone who actually used the product, visited the place, or performed the task. This signal is impossible for pure AI generation to replicate.
+
+### Author requirements for citability
+
+| Requirement | Implementation | AI signal |
+|---|---|---|
+| Real name (not "Admin" or "Team") | `<span class="author">Jane Doe</span>` + `Person` schema | Identity trust |
+| Role/credentials in bio | ≥30 words of bio near author name | Expertise signal |
+| `Person` schema with `sameAs` | LinkedIn, GitHub, ORCID, or personal site URL | Authoritativeness |
+| First-person experience language | "I tested…", "In our lab…", "After 6 months of use…" | Experience signal |
+| Date visible to user | "Published [date] · Updated [date]" | Freshness + trust |
+
+### Author schema
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Article",
+  "author": {
+    "@type": "Person",
+    "name": "Jane Doe",
+    "jobTitle": "Senior Product Tester",
+    "sameAs": [
+      "https://linkedin.com/in/janedoe",
+      "https://github.com/janedoe"
+    ]
+  },
+  "datePublished": "2026-03-01",
+  "dateModified": "2026-04-20"
+}
+```
+
+---
+
+## References
+
+- Blyskall study — 40M AI Overviews, backlinks vs content structure signals
+- Smargol, P. (2026). SEO Copywriting 2026. Indygo Agency. https://indygo.agency
+- Aggarwal et al. (2023). GEO: Generative Engine Optimization. Princeton/Georgia Tech. https://arxiv.org/abs/2311.09735
+- Google E-E-A-T: https://developers.google.com/search/docs/fundamentals/creating-helpful-content
+- See also: [ai-pipeline.md](ai-pipeline.md), [geo-guidelines.md](geo-guidelines.md), [geo-aeo-patterns.md](geo-aeo-patterns.md)

package/app/skills/seo-validate/reference/geo-guidelines.md

@@ -1,8 +1,10 @@
 # GEO — Generative Engine Optimization
 
-Reference for `seo-validate` Category 6. Structuring content so AI answer engines (ChatGPT, Perplexity, Google AI Overviews, Bing Copilot, Claude) can extract, cite, and quote it accurately.
+Reference for `seo-validate` Category 6. Structuring content so AI answer engines (ChatGPT, Perplexity, Google AI Overviews, Bing Copilot, Claude, Google AI Mode) can extract, cite, and quote it accurately.
 
-GEO is emerging practice, not a ranking algorithm with known penalties. **All findings in Category 6 are severity `INFO`** — guidance, not enforcement.
+GEO patterns have measurable impact on AI citation probability. **Category 6 findings are `WARN` (chunk size, author quality, freshness) or `INFO` (hedging, frameworks, contrast, bio)** — guidance based on citation research, not penalty-causing.
+
+See [ai-pipeline.md](ai-pipeline.md) for Google's 4-stage pipeline and 7 ranking signals. See [content-citability.md](content-citability.md) for chunk anatomy, semantic triples, and hedging patterns.
 
 ## Core Principles
 
@@ -224,17 +226,124 @@ These don't render content for crawlers at all. **Category 7 (rendering) superse
 
 ---
 
+## Chunk Architecture
+
+Google's retrieval stage (Stage 2 of the pipeline — see [ai-pipeline.md](ai-pipeline.md)) splits content into chunks of ≤500 tokens (~375 words). AI does not read your article — it extracts one chunk and uses it as the answer. If the answer is distributed across multiple sections or buried after a long preamble, AI cannot assemble it.
+
+**The 375-word rule:** Each H2 section should stay within ~375 words. If a section runs longer, add an H3 — each H3 becomes its own independent chunk candidate.
+
+### Anatomy of a citable chunk
+
+```
+H2: [Question or keyword-rich heading]
+│
+├── Direct answer — 2–3 sentences. Fact first. No preamble.
+│
+├── Elaboration — data, context, nuance. 3–5 sentences.
+│
+├── Visual element — list, table, or code block.
+│
+└── TL;DR (optional) — 1-sentence summary for long sections.
+```
+
+### Before / after
+
+**Before (unchunkable):**
+```
+H2: Choosing the Right Mattress
+
+When you're looking for a new mattress, there are many factors to consider.
+The market offers a wide variety of options, and it can be overwhelming...
+[70 words of preamble]
+Eventually, firmness is one of the most important factors...
+```
+*AI extracts the preamble as the "answer" — zero information.*
+
+**After (chunk-optimised):**
+```
+H2: How to Choose Mattress Firmness by Body Weight
+
+Match firmness to your weight: under 70 kg → H1–H2; 70–90 kg → H3; over 90 kg → H4.
+Higher body weight needs firmer support to maintain spinal alignment.
+
+| Weight    | Firmness  |
+|-----------|-----------|
+| < 70 kg   | H1–H2     |
+| 70–90 kg  | H3        |
+| > 90 kg   | H4        |
+```
+*AI extracts the first two sentences. Table is precision bonus.*
+
+---
+
+## Semantic Triples vs Marketing Prose
+
+AI answer engines parse content as Subject → Predicate → Object triples. Marketing prose requires inference; triples require none — lower hallucination risk, higher citation frequency.
+
+| Style | Example | AI extractable? |
+|---|---|---|
+| Marketing prose | "Our exceptional collection will enchant you with its elegance." | No — zero extractable facts |
+| Semantic triples | "Firmness: H3. Dimensions: 160×200 cm. Ideal for: side sleepers, 70–90 kg. Not for: stomach sleepers." | Yes — 4 distinct facts |
+
+Each triple answers a different AI sub-query. Six triples on a product page = six citation opportunities.
+
+---
+
+## Opinionated Content
+
+AI skips hedged claims. "This may be a good choice for many people" cannot be used as an answer to "which mattress should I buy?" Google's Jetstream signal explicitly rewards declarative, opinionated content.
+
+**Hedging to eliminate → replacement:**
+
+| Hedging | Replacement |
+|---|---|
+| "may be a good choice" | "We recommend X for Y" |
+| "worth considering" | "Our top pick for Z is X" |
+| "for many people" | "for side sleepers weighing 70–90 kg" |
+| "it depends" | "It depends on your weight: under 70 kg → H2, over 90 kg → H4" |
+
+**Rule:** Every guide and product page must take a position. Recommendation + named persona + justification = citable.
+
+---
+
+## The 13-Week Freshness Rule
+
+50% of top AI-cited content was published or updated within the last 13 weeks (Blyskall, 40M AI Overviews results). After 13 weeks without a visible update, citation probability drops.
+
+**Both signals required:**
+1. `dateModified` in JSON-LD — machine-readable freshness signal.
+2. Visible "Updated: [date]" near the byline — AI engines parse visible text; users trust visible dates.
+
+JSON-LD alone is insufficient.
+
+**Refresh strategy:**
+
+| Action | Interval |
+|---|---|
+| Full content review + update | Every 12 weeks for top pillar pages |
+| Date + minor fact refresh | Every 13 weeks for cluster articles |
+| Add new FAQ or data point | On new data availability for product pages |
+
+---
+
 ## Checklist (Category 6 findings)
 
+- [ ] Each H2 section is ≤375 words; sections exceeding this have an H3 sub-heading.
+- [ ] First paragraph under each heading is ≤60 words before a concrete fact or recommendation.
+- [ ] No hedging language ("may be", "worth considering", "for many") in recommendation contexts.
+- [ ] At least one decision framework ("if X → choose Y") per guide or category page.
+- [ ] At least one explicit contrast ("X vs Y", "unlike X") per comparison page.
+- [ ] At least one negative definition ("not recommended for…") per product or category page.
+- [ ] Author block: real name (not "Admin"), ≥30-word bio, `Person` schema with `sameAs`.
+- [ ] `dateModified` in JSON-LD AND visible "Updated: [date]" text present.
 - [ ] FAQ-style content uses `FAQPage` schema.
 - [ ] Summary content uses `speakable` schema.
-- [ ] Paragraphs >400 words are broken up with sub-headings.
 - [ ] Citations use `<cite>` and author bylines.
 - [ ] Quoted content uses `<blockquote>`/`<q>` with `cite` attr.
 - [ ] How-to content uses `<ol>` + `HowTo` schema.
 - [ ] Comparative data uses `<table>` with proper headers.
 - [ ] Glossary content uses `<dl>`/`<dt>`/`<dd>`.
-- [ ] Semantic HTML (`<article>`, `<section>`, `<main>`, `<nav>`, `<aside>`) is used over `<div>`.
+- [ ] Semantic HTML (`<article>`, `<section>`, `<main>`) used over `<div>`.
 - [ ] Critical content is NOT hidden behind tabs/accordions (except native `<details>`).
 
 ---

package/llms-full.txt

@@ -215,7 +215,7 @@
 - **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/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.0.1",
+  "version": "4.2.0",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "4.0.1",
+  "version": "4.2.0",
   "description": "AI coding toolkit: 107 skills, 44 agents, 12-editor write-through (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo, Aider, Augment, Antigravity, Codex, opencode), machine-enforced safety constitution, SARIF audit, signed npm provenance.",
   "keywords": [
     "claude",
@@ -41,7 +41,7 @@
     "ai-toolkit": "bin/ai-toolkit.js"
   },
   "scripts": {
-    "prepublishOnly": "npm run generate:all && python3 scripts/validate.py && npm test",
+    "prepublishOnly": "npm run generate:all && python3 scripts/validate.py --strict && npm test",
     "test": "bats tests/ --jobs 4 --no-parallelize-within-files",
     "validate": "python3 scripts/validate.py",
     "evaluate": "python3 scripts/evaluate_skills.py",

package/scripts/dir_rules_shared.py

@@ -105,6 +105,25 @@ def rule_quality_standards() -> str:
 """
 
 
+def rule_output_mode() -> str:
+    return """\
+# Output Mode
+
+`output-mode: concise`
+
+Default response mode is **concise**. The `brand-voice` skill (when present) auto-loads concise rules; assistants without that skill should still apply the directives below.
+
+* No preamble — skip "I'll now...", "Sure, let me...", "Great question!" Start with the answer.
+* Lead with the result — conclusion or output first; explanation only if asked or non-obvious.
+* Max 3 sentences per closed question — yes/no, single-fact, or "where is X" answers stay under three sentences.
+* Tables and lists over prose — when comparing options, listing steps, or showing values.
+* No trailing summaries — if the diff or output already shows what changed, do not restate it.
+* Drop filler adjectives — no "nice", "great", "powerful", "robust" unless the user asked for evaluation.
+* Cite as `path:line` — instead of paragraphs describing where things live.
+* Escalate to verbose only for: architecture / RFC / ADR / trade-off documents, or when the user asks for detail.
+"""
+
+
 def rule_agents_and_skills() -> str:
     """Full listing of agents and skills — same content all platforms get."""
     agents_count, skills_count = count_agents_and_skills()
@@ -142,6 +161,7 @@ STANDARD_RULES: dict[str, callable] = {
     f"{PREFIX}security.md": rule_security,
     f"{PREFIX}workflow.md": rule_workflow,
     f"{PREFIX}quality-standards.md": rule_quality_standards,
+    f"{PREFIX}output-mode.md": rule_output_mode,
 }
 
 

package/scripts/generator_base.py

@@ -142,6 +142,23 @@ def render_generator(config: dict) -> None:
         print()
         print_toolkit_end()
 
+    # Default output mode directive — applies to every editor that loads this file
+    print()
+    print("<!-- TOOLKIT:output-mode START -->")
+    print("<!-- Auto-injected by ai-toolkit. Re-run to update. -->")
+    print()
+    print("# Output Mode")
+    print()
+    print("`output-mode: concise`")
+    print()
+    print("Default response mode is **concise**. Skip preamble, lead with the result, "
+          "max 3 sentences per closed question, prefer tables/lists over prose, no "
+          "trailing summaries, drop filler adjectives, cite as `path:line`. Escalate "
+          "to verbose only for architecture / RFC / ADR / trade-off documents or when "
+          "the user asks for detail.")
+    print()
+    print("<!-- TOOLKIT:output-mode END -->")
+
     # Registered custom rules from ~/.softspark/ai-toolkit/rules/
     if RULES_DIR.is_dir():
         for rule_file in sorted(RULES_DIR.glob("*.md")):

package/scripts/url_fetch.py

@@ -9,6 +9,9 @@ Stdlib-only — no external dependencies.
 from __future__ import annotations
 
 import ssl
+import json
+import os
+from pathlib import Path
 import urllib.error
 import urllib.request
 
@@ -34,6 +37,13 @@ def fetch_url(url: str) -> bytes:
             f"Only HTTPS URLs are supported (got: {url.split('://')[0]}://)"
         )
 
+    fixture_map = os.environ.get("AI_TOOLKIT_TEST_URL_FIXTURE_MAP")
+    if fixture_map and os.environ.get("AI_TOOLKIT_TEST_MODE") == "1":
+        fixtures = json.loads(fixture_map)
+        fixture_path = fixtures.get(url)
+        if fixture_path:
+            return Path(fixture_path).read_bytes()
+
     ctx = ssl.create_default_context()
     with urllib.request.urlopen(url, timeout=_FETCH_TIMEOUT, context=ctx) as resp:
         data = resp.read(_FETCH_MAX_BYTES)