chore: streamline agent guidance and refresh upstream skills

.codex/skills/ai-seo/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: ai-seo
-description: "When the user wants to optimize content for AI search engines, get cited by LLMs, or appear in AI-generated answers. Also use when the user mentions 'AI SEO,' 'AEO,' 'GEO,' 'LLMO,' 'answer engine optimization,' 'generative engine optimization,' 'LLM optimization,' 'AI Overviews,' 'optimize for ChatGPT,' 'optimize for Perplexity,' 'AI citations,' 'AI visibility,' 'zero-click search,' 'how do I show up in AI answers,' 'LLM mentions,' 'optimize for Claude/Gemini,' 'llms.txt,' 'llms-full.txt,' 'OKF,' 'Open Knowledge Format,' 'knowledge bundle,' 'agent-readable site,' 'agent readiness,' 'is my site agent-ready,' or 'WebMCP.' Use this whenever someone wants their content to be cited or surfaced by AI assistants and AI search engines. For traditional technical and on-page SEO audits, see seo-audit. For structured data implementation, see schema."
+description: "When the user wants to optimize content for AI search engines, get cited by LLMs, or appear in AI-generated answers. Also use when the user mentions 'AI SEO,' 'AEO,' 'GEO,' 'LLMO,' 'answer engine optimization,' 'generative engine optimization,' 'LLM optimization,' 'AI Overviews,' 'optimize for ChatGPT,' 'optimize for Perplexity,' 'AI citations,' 'AI visibility,' 'zero-click search,' 'how do I show up in AI answers,' 'LLM mentions,' 'optimize for Claude/Gemini,' 'llms.txt,' 'llms-full.txt,' 'OKF,' 'Open Knowledge Format,' 'knowledge bundle,' 'agent-readable site,' 'agent readiness,' 'is my site agent-ready,' 'WebMCP,' 'do listicles still work for AI,' 'ChatGPT stopped citing comparison pages,' or 'AI citation format shift.' Use this whenever someone wants their content to be cited or surfaced by AI assistants and AI search engines. For traditional technical and on-page SEO audits, see seo-audit. For structured data implementation, see schema."
 metadata:
-  version: 2.4.0
+  version: 2.5.0
 ---
 
 # AI SEO
@@ -105,6 +105,8 @@ Google's own example: a user asking "how to fix lawns" triggers fan-out queries
 
 **Action**: when planning content, brainstorm the 5–10 related queries the AI is likely to fan out to and make sure your content (or your site as a whole) covers them.
 
+ChatGPT fans out too — and you can extract its *literal* background queries for your niche via DevTools (method in [references/format-volatility.md](references/format-volatility.md)). Post-5.6, ChatGPT's fan-outs shifted away from "best/vs/top" modifiers toward `site:` and "official" searches — use the extraction to see where your category's fan-outs stand today.
+
 ---
 
 ## AI Visibility Audit
@@ -253,6 +255,7 @@ AI systems don't just cite your website — they cite where you appear.
 - Wikipedia mentions (7.8% of all ChatGPT citations)
 - Reddit discussions (volatile: ~1.8% of ChatGPT citations historically, but nearly wiped from ChatGPT by Aug 2026 retrieval changes — still retrieved elsewhere; see the volatility section in [references/agent-readiness.md](references/agent-readiness.md))
 - Industry publications and guest posts
+- LinkedIn — per LinkedIn's own AEO guide, the most-cited outlet for professional-topic searches; Articles out-cite Posts ~60/40, and a post's first words become its URL slug, so front-load the target phrase (details in [references/format-volatility.md](references/format-volatility.md))
 - Review sites (G2, Capterra, TrustRadius for B2B SaaS)
 - YouTube (frequently cited by Google AI Overviews)
 - Podcasts (episodes get transcribed, show notes published — both get crawled and cited)
@@ -366,24 +369,11 @@ For ecom and local business specifically, Google highlights:
 
 ## Content Types That Get Cited Most
 
-Not all content is equally citable. Prioritize these formats:
-
-| Content Type | Citation Share | Why AI Cites It |
-|-------------|:------------:|----------------|
-| **Comparison articles** | ~33% | Structured, balanced, high-intent |
-| **Definitive guides** | ~15% | Comprehensive, authoritative |
-| **Original research/data** | ~12% | Unique, citable statistics |
-| **Best-of/listicles** | ~10% | Clear structure, entity-rich |
-| **Product pages** | ~10% | Specific details AI can extract |
-| **How-to guides** | ~8% | Step-by-step structure |
-| **Opinion/analysis** | ~10% | Expert perspective, quotable |
-
-**Underperformers for AI citation:**
-- Generic blog posts without structure
-- Thin product pages with marketing fluff
-- Gated content (AI can't access it)
-- Content without dates or author attribution
-- PDF-only content (harder for AI to parse)
+Not all content is equally citable — and the format mix is **volatile**. The long-standing baseline had comparison articles (~33%) and listicles (~10%) among the top citation earners, but **ChatGPT 5.6 (Aug 2026) demoted the exploited formats: listicle citations fell −50.5% and comparison-page citations −32.1%, while `site:` and "official" retrieval surged** — a shift toward primary sources and owned pages. Format strategy is now per-platform (comparisons still work on Google AIO/Gemini/Perplexity). See [references/format-volatility.md](references/format-volatility.md) for the shift data, the per-platform format table, LinkedIn's citation numbers, and the ChatGPT fan-out extraction diagnostic.
+
+**Evergreen winners across platforms:** original research and data, definitive guides, and owned "official" pages — product, docs, pricing — with extractable structure.
+
+**Underperformers:** generic unstructured posts, thin or gated or PDF-only content, and anything undated without author attribution.
 
 **Citation ≠ recommendation.** Getting cited means your content was useful to consult; getting *recommended* — onto the buyer's actual shortlist — is governed by web-wide consensus (reviews, forums, analysts, press) and is largely independent of your own content. Self-promotional "best [category]" listicles can even backfire for emerging brands: in one 100-query B2B study, 69% of the AI Overview citations that self-promotional listicles earned came in answers that recommended competitors instead of the publishing brand. See [references/citations-vs-recommendations.md](references/citations-vs-recommendations.md) for the visibility ladder (retrieved → cited → mentioned → recommended), stage-dependent buyer's-guide strategy, what earns recommendations, and the attribution blind spot.
 
@@ -419,6 +409,8 @@ Monthly manual check:
 3. Record: Are you cited? Who is? What page?
 4. Log in a spreadsheet, track month-over-month
 
+AI answers are **non-deterministic** — one run is an anecdote, not a measurement. Run each query 3–5 times per platform and track the mention *rate* with its sample size ("cited 3/5, n=5"), comparing rates over time rather than single runs. Full rigor checklist in [references/format-volatility.md](references/format-volatility.md).
+
 ### Search Console expectations
 
 Google's guide is explicit: **there is no AI-specific Search Console reporting**. AI Overviews and AI Mode use core Search ranking, so the standard Search Console reports (Performance, Coverage, Core Web Vitals) are still what you measure with for Google. The third-party tools above are the only way to see cross-platform AI citation behavior.

.codex/skills/ai-seo/evals/evals.json

@@ -125,6 +125,11 @@
         "Does not present citation-share statistics as stable facts; recommends verifying against the user's own citation monitoring"
       ],
       "files": []
+    },
+    {
+      "id": 10,
+      "prompt": "We're a B2B SaaS planning our 2026 content roadmap. The plan is 40 comparison pages ('us vs competitor') and 20 'best tools' listicles, mainly to win ChatGPT citations. Also, how do I know if it's working — I checked ChatGPT once last week and we weren't mentioned.",
+      "expected_output": "Should load references/format-volatility.md and push back on the rationale with the ChatGPT 5.6 shift (Aug 2026, Peec AI data): listicle citations fell ~50% and comparison-page citations ~32% post-5.6, with fan-out queries dropping 'best/vs/top/comparison' modifiers in favor of site: and 'official' searches — so 'win ChatGPT citations' no longer justifies scaled comparison/listicle production. Should NOT say comparison pages are dead: they still convert humans and still earn citations on Google AI Overviews, Gemini, and Perplexity — format strategy is per-platform. Should steer investment toward owned 'official' pages (product, docs, pricing, original research), which are rising as the citable class and dominate Gemini (~60% business sites). May suggest extracting ChatGPT's real fan-out queries via the DevTools method for coverage planning (while warning against mass-generating a page per query — scaled content abuse). On measurement: one ChatGPT check is an anecdote — AI answers are non-deterministic; run each query 3–5 times per platform, track mention rate with sample size (e.g. 'cited 3/5'), and compare rates over time. Numbers should be treated as dated snapshots to verify against own monitoring."
     }
   ]
 }

.codex/skills/ai-seo/references/format-volatility.md

@@ -0,0 +1,98 @@
+# Format Volatility — Which Content Formats AI Cites (and How Fast That Changes)
+
+Citation-*source* volatility (Reddit wiped overnight, Gemini favoring owned sites) is covered in [agent-readiness.md](agent-readiness.md). This reference covers the second volatility axis: citation-*format* — which page types AI engines retrieve and cite, and the August 2026 evidence that heavily-exploited formats get demoted.
+
+Read this before recommending comparison pages, listicles, or "best X" content for AI visibility. The advice changed materially with ChatGPT 5.6.
+
+## The ChatGPT 5.6 format shift (August 2026)
+
+Data from Peec AI (shared by Tomek Rudzki via Lily Ray, Aug 2026), comparing ChatGPT retrieval behavior before and after the 5.6 launch:
+
+**Fan-out queries** — the modifiers that declined most as a share of ChatGPT's background searches:
+
+- "vs"
+- "comparison"
+- "top"
+- "best"
+- "reviews"
+
+At the same time: a surge in `site:` searches and modifiers like **"official"**.
+
+**Citations by page type** — share of total ChatGPT citations:
+
+| Page type | Pre-5.6 | Post-5.6 | Change |
+|---|---:|---:|---:|
+| Listicles ("Top 10 X," "8 best Y") | 15.77% | 7.80% | **−50.5%** |
+| Comparison pages ("X vs Y," alternatives) | 9.08% | 6.17% | **−32.1%** |
+
+The interpretation (Lily Ray's, and it fits the fan-out data): these are exactly the two formats companies scaled for GEO over the prior 18 months, and ChatGPT adjusted retrieval to mitigate the spam. The `site:`/"official" surge points the same direction — **toward primary sources and owned domains, away from aggregator formats**.
+
+## What this changes (and what it doesn't)
+
+**It does NOT mean "stop making comparison pages."** Comparison and best-of content still:
+
+- Converts human buyers (its original job)
+- Gets cited by Google AI Overviews (which follow core rankings, not ChatGPT's retrieval)
+- Feeds Gemini and Perplexity, which haven't shown the same demotion
+- Answers real mid-funnel queries on your own site
+
+**It DOES mean:**
+
+1. **Stop justifying scaled listicle/comparison production with "it wins AI citations."** On ChatGPT — the largest AI answer surface — that rationale lost half its force in one release.
+2. **The "official"/primary-source shift favors your owned pages.** Product pages, docs, pricing pages, original research — the pages only you can publish — are rising as the citable class. This compounds the Gemini finding (business-owned sites ≈ 60% of citations).
+3. **Format strategy is now per-platform.** Check which engines matter for your category before choosing formats:
+
+| Format | ChatGPT (post-5.6) | Google AIO | Gemini | Perplexity |
+|---|---|---|---|---|
+| Listicles / best-of | Demoted | Rankings-dependent | OK | OK |
+| Comparison / vs pages | Demoted | Rankings-dependent | OK | OK |
+| Original research + data | Strong | Strong | Strong | Strong |
+| Product/docs/pricing (owned, "official") | **Rising** | Strong | **Dominant** | Strong |
+| How-to / guides | Steady | Strong | OK | Strong |
+
+*(Table caveat: the demotion was measured on ChatGPT only. "OK" for Gemini/Perplexity means no demotion has been reported there — not that stability was measured. Any engine can ship its own 5.6-style shift.)*
+
+4. **Treat every number above as a dated snapshot.** Same doctrine as source volatility: these are Aug 2026 measurements of a moving system. Verify against your own citation monitoring before betting budget.
+
+## LinkedIn as a citation surface (from LinkedIn's own AEO guide)
+
+LinkedIn quietly published its own AEO/AI-search guidance (surfaced by Chris Long, Sep 2026). The platform-reported numbers:
+
+- LinkedIn is the **most-cited outlet for professional-topic searches**
+- **~60% of LinkedIn citations come from Articles**, ~40% from Posts
+- Post URLs use the **first words of the post as the slug**
+
+**Tactics:**
+
+- For professional/B2B topics, LinkedIn Articles are a first-class Presence-pillar surface — treat long-form Articles (not just feed posts) as citable assets with the same extractable structure as blog content.
+- **Front-load the target phrase in a post's opening words** — they become the URL slug, which is retrieval surface.
+- This is platform-reported data (LinkedIn grading its own homework); weight accordingly, but the Articles > Posts split matches the general pattern that long-form structured content out-cites feed content.
+
+## DIY diagnostic: extract ChatGPT's real fan-out queries
+
+You don't need a tool to see what ChatGPT actually searches for in your niche (method circulating publicly, Aug 2026):
+
+1. Run an important query for your category in ChatGPT (with search).
+2. Open DevTools → Network tab, refresh the conversation (URL id after `/c/`).
+3. Find the conversation response payload and search it for `queries`.
+4. You'll see the literal background searches ChatGPT fanned out to.
+
+**Use it for:** building your query-test list from *real* fan-out behavior instead of guesses; checking whether your category's fan-outs still use "best/vs" modifiers or have shifted to `site:`/"official" patterns; finding sub-topics your content doesn't cover.
+
+**Do not use it for:** auto-generating and mass-publishing an article per fan-out query. That's the exact scaled-content pattern 5.6 demoted (and Google's scaled content abuse policy names). The diagnostic is for coverage planning, not content spam.
+
+## Measurement rigor: AI answers are non-deterministic
+
+A single ChatGPT answer is an anecdote, not a measurement — the same prompt returns different sources run-to-run. (The statistical-rigor framing here is popularized by Initial Commit's AEO audit skill, Josh Pigford, Aug 2026; the practice stands on its own.)
+
+When auditing or monitoring:
+
+- **Run each query 3–5 times per platform**, fresh session each time.
+- **Track mention/citation *rate*** ("cited in 3 of 5 runs"), never a yes/no from one run.
+- **Report the sample size** with every number ("40% mention rate, n=5") so future-you knows how much to trust it.
+- **Compare rates over time, not runs.** A drop from 4/5 to 3/5 is noise; a drop from 4/5 to 0/5 sustained across a month is signal.
+- Before diagnosing *why* you're not cited, split causes the way an audit should: **technical** (can't be crawled/parsed — see agent-readiness.md), **comprehension** (AI describes you inaccurately or vaguely), or **trust** (understood but not selected — see citations-vs-recommendations.md).
+
+---
+
+*Sources, all labeled and dated: Peec AI pre/post-5.6 citation data via Tomek Rudzki and Lily Ray (Aug 2026); LinkedIn's AEO guide numbers via Chris Long (Sep 2026, platform-reported); fan-out extraction method as publicly circulated (Aug 2026); measurement-rigor framing credited to Initial Commit's AEO audit skill (Josh Pigford, Aug 2026). All snapshots of a volatile system — verify against your own monitoring.*