optbrew 0.0.0-stage → 0.1.2

package/skills/optbrew/modules/magnus-seo/references/content-strategy-seo.md

@@ -0,0 +1,142 @@
+# Content Strategy SEO Reference
+
+Content strategy SEO ensures that what you write positions you to be discovered for the queries your audience actually searches for.
+
+## Topic Clusters & Pillar Pages
+
+The modern SEO content architecture replaces the old model of writing individual articles about individual keywords. Instead, content is organized into **topic clusters** centered on **pillar pages**.
+
+### How It Works
+
+- **Pillar page:** A comprehensive, long-form guide to a broad topic (e.g., "The Complete Guide to AI Agent Memory Systems"). It covers the topic broadly and links out to cluster content.
+- **Cluster content:** Specific articles that dive deep into sub-topics (e.g., "What is a Vector Database?", "How RAG Works", "GraphRAG vs Vector Search"). Each cluster article links BACK to the pillar page.
+- **Internal linking:** Cluster → pillar (always). Pillar → cluster (when relevant).
+
+### Why It Works
+
+- **Topical authority:** A group of pages all linking to each other around a common topic signals deep expertise to search engines
+- **SERP dominance:** Instead of competing for one keyword, you compete for an entire topic area
+- **User experience:** Readers naturally flow from intro content (pillar) to deep dives (clusters)
+
+### Applying to Platform-specific implementation notes
+
+**example.com — Example clusters:**
+- Pillar: "AI Agent Memory Systems"
+- Clusters: "Vector Databases for Agent Memory," "Knowledge Graphs vs Vector Search," "a content inventory Thought-Graph Architecture," "What is GraphRAG?"
+
+**example.com — Example clusters:**
+- Pillar: "Enterprise AI Agent Deployment"
+- Clusters: "RAG at Scale: Lessons from Production," "AI Agent Orchestration," "Security Considerations for Enterprise AI," "Cost Optimization for LLM Inference"
+
+## Keyword Research
+
+### Process
+1. **Identify seed keywords** — the 3-5 core terms that define your site's domain
+2. **Expand via SERP analysis** — search each seed keyword and analyze the "People also ask" box, related searches at page bottom, and the top-ranking pages' headlines
+3. **Identify question-based queries** — "how does X work", "what is Y", "why Z matters" — these are excellent for featured snippet opportunities
+4. **Analyze search intent** — is the query informational (learning), navigational (finding a specific site), commercial (comparing options), or transactional (buying)? Match your content type to intent.
+5. **Assess competition** — are the top 10 results thin blog posts or deep authoritative guides? If the top results are weak, there's an opportunity.
+
+### Keyword Mapping
+
+Map each article to 1 primary keyword and 2-5 secondary/related keywords:
+
+```
+Article: "The Artifact Pyramid: Progressive Disclosure for Agent Outputs"
+Primary:  "artifact pyramid"
+Secondary: "progressive disclosure AI", "multi-agent output structure",
+           "agent collaboration format", "research output pyramid"
+```
+
+### Tools
+- Google Search Console (what queries your site already ranks for)
+- Google "People also ask" / related searches (free, authoritative)
+- AnswerThePublic (question-based query discovery)
+- Ahrefs / Semrush (paid — comprehensive keyword data)
+
+## SERP Feature Targeting
+
+Target specific SERP features by structuring content appropriately:
+
+| SERP Feature | Best for | Content Structure |
+|-------------|----------|-------------------|
+| **Featured Snippet (Paragraph)** | "What is X" questions | Direct answer in first paragraph after H2. 40-50 words. |
+| **Featured Snippet (List)** | "Steps to X", "Types of X" | Numbered or bulleted list in the content. |
+| **Featured Snippet (Table)** | Comparisons, specifications | HTML table with clear headers and data. |
+| **FAQ Rich Result** | Multiple related questions | FAQPage schema with 2+ Q&A pairs visible in content. |
+| **HowTo Rich Result** | Tutorials, guides | HowTo schema with numbered steps. |
+| **People Also Ask** | Question-based queries | Address each question in its own H2 section. |
+| **Knowledge Panel** | Brand/organization queries | Organization schema, Wikipedia entry, verified social profiles. |
+
+## Content Gap Analysis
+
+### Process
+1. **Identify your target keywords** (the terms you WANT to rank for)
+2. **Check your current rankings** (do you already have content for these?)
+3. **Analyze top 10 results** for each keyword:
+   - What content format are they using? (listicle, guide, video, tool)
+   - How long is the content?
+   - What angle do they take?
+   - What's missing from their coverage?
+4. **Identify gaps:** Topics where your site has no content, or where your content is weaker than competitors'
+5. **Prioritize:** Volume × difficulty × relevance — focus on high-volume gaps that you can credibly fill
+
+### Gap Types
+- **Missing topic:** No content exists on your site for a search-worthy topic
+- **Thin content:** Content exists but is significantly weaker than competitors'
+- **Outdated content:** Content exists but is no longer accurate or current
+- **Format gap:** Competitors rank with a format you haven't used (e.g., video, interactive tool, data study)
+
+## Topical Authority
+
+Topical authority is built over time by publishing a breadth and depth of content on a subject. It's the most defensible SEO strategy because it can't be replicated quickly.
+
+### Building Topical Authority
+1. **Publish the pillar page first** — broad, comprehensive, definitive
+2. **Publish cluster content regularly** — 2-3 sub-topic articles per month
+3. **Interlink systematically** — every cluster article links to the pillar; the pillar links to clusters
+4. **Refresh content** — update pillar pages annually, cluster content as needed
+5. **Expand scope** — once you've covered the core topic, expand to adjacent topics
+
+### Signals of Topical Authority
+- Your content ranks for multiple related keywords
+- Your content appears in "People also ask" for the topic
+- Other sites link to your content as a reference
+- Your content is cited in academic or industry publications
+
+## Platform-specific implementation notes — SEO Opportunity Assessment
+
+| Site | Domain Authority | Primary Keyword Focus | Largest Gap |
+|------|-----------------|----------------------|-------------|
+| example.com | Low (newer personal blog) | AI philosophy, neurodiversity, engineering | Few internal links between related posts; no topic cluster structure |
+| example.com | Low (newer enterprise AI blog) | Enterprise AI strategy, agentic AI | Very new — needs pillar pages and cluster strategy from the start |
+| example.org | Very low (community site) | Mesh networking, MeshCore, RDUMesh | Local SEO for Raleigh/Durham; community resource queries |
+| example.net | Minimal | Southeast mesh networking | Mostly informational — just needs proper on-page SEO |
+
+### Recommended Actions by Site
+
+**example.com:**
+- Implement topic clusters retroactively (group existing posts into 3-4 clusters with pillar pages)
+- Ensure every post links to 2-3 other posts
+- Add FAQPage schema to posts that answer multiple questions
+- Optimize for "People also ask" by structuring content around questions
+
+**example.com:**
+- Plan pillar pages first before creating more isolated content
+- Target question-based keywords for featured snippet opportunities
+- Implement TechArticle schema on all technical posts
+- Focus on long-tail, low-competition keywords in the short term
+
+**example.org:**
+- Local SEO: "mesh network Raleigh," "MeshCore North Carolina"
+- Community-Q&A content for FAQ rich results
+- Event pages for meetup/community gathering SEO
+
+## Content Calendar
+
+SEO content strategy produces a **ranked list** of content opportunities, not a dated calendar. Editorial schedules vary; prioritize by evidence rather than a fixed calendar. Prioritize by:
+
+1. **Search volume × relevance** — How many searches × how well it fits the site
+2. **Competition gap** — How much better can we be than the current top results?
+3. **Ease of creation** — Does the research already exist in the vault or is it a new domain?
+4. **Pillar dependency** — Should this be created before or after the pillar page?

package/skills/optbrew/modules/magnus-seo/references/discovery-and-freshness.md

@@ -0,0 +1,47 @@
+# AEO discovery and freshness
+
+## Crawl is not citation
+
+A page must be reachable and eligible before many systems can retrieve it, but a successful fetch is not proof of indexing, retrieval, citation, or traffic. Verify each boundary separately.
+
+## Robots policy
+
+Robots Exclusion Protocol rules are crawler-specific. Build a policy matrix before changing them:
+
+- search crawler and search visibility;
+- training crawler and training use;
+- user-triggered fetch;
+- ad, commercial, or partner crawler;
+- private paths and sensitive data.
+
+OpenAI explicitly separates OAI-SearchBot, GPTBot, and ChatGPT-User. Google uses Googlebot for Search controls and Google-Extended for certain other systems. Other providers have their own semantics. Never copy a universal allowlist from a blog post.
+
+Check robots at the origin, CDN, and public URL. Record propagation expectations. A robots file is a policy control, not an AEO optimization switch.
+
+## Sitemaps and internal links
+
+Use crawlable internal links and an accurate XML sitemap. Include canonical URLs and truthful `lastmod` values. Bing documents sitemaps and IndexNow as discovery/freshness aids; they do not guarantee AI inclusion. Do not set `lastmod` to sitemap generation time when page content did not change.
+
+## Freshness
+
+Freshness means the answer is current for its question. A real update should identify what changed, update visible dates where appropriate, refresh structured data, repair links, and re-run high-risk observations. Date-only edits, “updated” badges without changed content, and stale citations damage trust.
+
+## Access verification
+
+```text
+GET /robots.txt          → expected policy, status, content type
+GET /sitemap.xml         → expected URL and true lastmod
+GET /target              → status, canonical, robots meta, visible answer
+GET /target as crawler   → only where permitted and provider semantics are known
+```
+
+Inspect edge caching and authentication. A browser page that renders content only after a client-side request needs a separate rendered verification.
+
+## Primary references
+
+- [RFC 9309 Robots Exclusion Protocol](https://datatracker.ietf.org/doc/html/rfc9309)
+- [Google robots.txt interpretation](https://developers.google.com/crawling/docs/robots-txt/robots-txt-spec)
+- [Google AI features and your website](https://developers.google.com/search/docs/appearance/ai-features)
+- [OpenAI crawler documentation](https://platform.openai.com/docs/bots)
+- [Bing sitemap and IndexNow guidance](https://blogs.bing.com/webmaster/July-2025/Keeping-Content-Discoverable-with-Sitemaps-in-AI-Powered-Search)
+- [Sitemaps protocol](https://www.sitemaps.org/protocol.html)

package/skills/optbrew/modules/magnus-seo/references/evidence-boundaries.md

@@ -0,0 +1,75 @@
+# AEO evidence boundaries
+
+## Working definition
+
+Answer Engine Optimization is the disciplined work of improving the chance that a useful, attributable answer about a defined entity or topic can be discovered, retrieved, interpreted, and cited by an AI answer surface. The definition is operational, not a claim that providers expose one controllable ranking system.
+
+AEO overlaps with SEO because many answer surfaces retrieve from search indexes. It is narrower because the primary outcome is answer inclusion and citation quality rather than a blue-link position. GEO, LLMO, AI search optimization, and answer optimization are overlapping industry labels; preserve the label used by the target provider or stakeholder, then define the actual outcome.
+
+## Outcome taxonomy
+
+Never collapse these into one metric:
+
+| Outcome | Meaning | Evidence needed |
+|---|---|---|
+| Crawl access | A named crawler could fetch the resource | Server/CDN logs or provider documentation |
+| Index eligibility | A page can enter a provider's index | Provider diagnostics; not guaranteed by a 200 |
+| Retrieval | A page was selected for a query or grounding step | Provider-native data or a reproducible observation |
+| Mention | Entity appears in generated text | Exact answer snapshot |
+| Citation | Answer links or names a source | Exact answer plus URL |
+| Citation correctness | Citation supports the adjacent claim | Read the cited source and compare scope |
+| Share of voice | Entity appears relative to a defined comparator set | Frozen prompts, sampling, date, scoring rules |
+| Click/referral | User visits after an answer interaction | Analytics with known attribution limits |
+| Conversion | User completes a defined outcome | Instrumented funnel and causal design |
+
+## Evidence labels
+
+Use these labels in plans, reports, and references:
+
+- **Primary documentation:** provider, standards body, schema vocabulary, or tool owner documents its own behavior.
+- **Observed:** a recorded answer, crawl, response header, rendered page, dashboard value, or reproducible local result.
+- **Independent study:** a method and dataset are disclosed well enough to assess, but it may not generalize.
+- **Vendor-reported:** a commercial provider reports an analysis, lift, or benchmark. Useful as a hypothesis source, not a universal rule.
+- **Inference:** a reasoned interpretation that goes beyond direct observation. Mark it as such.
+- **Unresolved:** plausible but not verified, provider-dependent, stale, or contradicted.
+
+## What Google establishes
+
+Google's current Search Central guidance says its AI Overviews and AI Mode use existing Search systems and that there are no additional technical requirements or special AI markup required. It recommends ordinary crawlability, index eligibility, helpful people-first content, clear textual content, internal links, accurate structured data, and Search Console measurement. Google also says it does not use `llms.txt` for Google Search visibility and rejects mandatory chunking, exact long-tail rewrites, and inauthentic mentions as universal requirements.
+
+This is not evidence about every other answer engine. Store provider scope beside every tactic.
+
+## Strong claims to reject
+
+Reject or narrow claims such as:
+
+- “Do X and ChatGPT will cite you.”
+- “FAQPage gives a fixed citation multiplier.”
+- “Short paragraphs are required by all LLMs.”
+- “`llms.txt` is a standard adopted by search engines.”
+- “A successful crawl proves indexing or citation.”
+- “More pages or more mentions create authority.”
+- “A before/after citation change proves causation.”
+
+A useful replacement states the target provider, the observed behavior, the evidence source, the date, and what remains unknown.
+
+## Source review card
+
+For every material claim, record:
+
+```text
+claim:
+source_url:
+source_title:
+authority_tier: primary | standard | independent | vendor | discovery-only
+provider_scope:
+accessed_on:
+exact_supporting_observation:
+what_it_does_not_prove:
+confidence: high | medium | low
+refresh_trigger:
+```
+
+## Completion boundary
+
+An AEO implementation is complete only when the requested changes exist, each changed boundary has been verified, and the report separates implemented, observed, inferred, and unresolved outcomes. A citation or traffic improvement is an outcome to measure later, not a completion prerequisite that can be fabricated.

package/skills/optbrew/modules/magnus-seo/references/ghost-metadata.md

@@ -0,0 +1,204 @@
+# Ghost CMS Metadata & Schema Completion
+
+For Ghost CMS sites (example.com, example.org, example.net), the SEO specialist is responsible for completing all metadata on every published or draft article. This covers three distinct layers: Ghost CMS metadata fields, social media cards, and code-injected structured data.
+
+## Layer 1: Ghost CMS Metadata Fields
+
+Every Ghost post and page has a set of metadata fields in the post settings panel (or settable via the Ghost Admin API / ghost-cli). These must be filled for every article.
+
+### Fields
+
+| Field | Required | Purpose | Best Practice |
+|-------|----------|---------|---------------|
+| **Meta Title** | Always | Overrides the post title for SEO. Controls the `<title>` tag. | 50-60 chars, primary keyword front-loaded. If not set, Ghost uses the post title (which may be too long or lack keyword focus). |
+| **Meta Description** | Always | Overrides excerpt for SEO. Controls the meta description tag. | 150-160 chars, includes primary keyword + CTA, reads naturally. |
+| **Custom Excerpt** | Always | Used in card previews, RSS feeds, and as fallback for meta description. | 1-2 sentences capturing the article's core argument. Shorter than meta description (~120 chars). NOT the same as meta description — serves different contexts (card previews, not SERPs). |
+| **OG Title** | Recommended | Overrides the title for social sharing (Facebook, LinkedIn, Discord). | Defaults to meta title. Only needed if the social version should differ. |
+| **OG Description** | Recommended | Overrides the description for social sharing. | Defaults to meta description. Only needed if the social version should differ. |
+| **OG Image** | Always | The image that appears in social card previews. | Should be the article's feature/cover image. If not set, Ghost uses the feature image from the post. Set explicitly to ensure correct crop and fallback. |
+| **Twitter Title** | Recommended | Overrides the title for Twitter/X card previews. | Defaults to OG title. Only needed if the Twitter version should differ. |
+| **Twitter Description** | Recommended | Overrides the description for Twitter/X. | Defaults to OG description. |
+| **Twitter Image** | Recommended | Overrides the image for Twitter/X. | Defaults to OG image. Twitter's card crop differs from OG — set explicitly if the feature image crop doesn't work well as a square. |
+| **Canonical URL** | As needed | Overrides the canonical URL. | Only needed if the post is syndicated or republished from another source. Ghost auto-generates self-referencing canonicals. |
+| **Slug** | As needed | URL path. | Set before publish. Never change after publish without a 301 redirect. |
+
+### Setting via ghost-cli
+
+The `ghost-cli` tool has a `meta set` command for individual fields:
+
+```bash
+# Set meta title and description
+ghost-cli --site example meta set <slug> \
+  --meta-title "Primary Keyword Context | Groktopus" \
+  --meta-description "150-160 char summary with keyword and call to action."
+
+# Set OG and Twitter fields
+ghost-cli --site example meta set <slug> \
+  --og-title "Optional: different from meta title" \
+  --og-description "Optional: different from meta description" \
+  --twitter-title "Optional: different from OG title"
+```
+
+### Setting via Ghost Admin API
+
+For bulk operations or automation, use the Admin API directly. The key fields in the post object are:
+
+```json
+{
+  "posts": [{
+    "id": "post-id",
+    "meta_title": "SEO Title",
+    "meta_description": "SEO Description",
+    "custom_excerpt": "Brief excerpt for cards",
+    "og_image": "https://example.com/image.jpg",
+    "og_title": "Social Title",
+    "og_description": "Social Description",
+    "twitter_image": "https://example.com/twitter-image.jpg",
+    "twitter_title": "Twitter Title",
+    "twitter_description": "Twitter Description",
+    "canonical_url": null,
+    "codeinjection_head": "<script type=\"application/ld+json\">...</script>",
+    "codeinjection_foot": ""
+  }]
+}
+```
+
+**Important:** When updating a post via PUT, you must include `updated_at` from the current post data — Ghost uses it for optimistic locking. Always fetch first, modify, then PUT.
+
+## Layer 2: Social Media Cards
+
+Social media cards control what appears when an article is shared on Facebook, LinkedIn, Discord, Twitter/X, Slack, and other platforms.
+
+### How Ghost Generates Cards
+
+Ghost automatically generates Open Graph and Twitter Card meta tags from the post's metadata fields:
+
+```html
+<meta property="og:site_name" content="Groktopus">
+<meta property="og:type" content="article">
+<meta property="og:title" content="[OG Title or Meta Title or Post Title]">
+<meta property="og:description" content="[OG Description or Meta Description or Excerpt]">
+<meta property="og:image" content="[OG Image or Feature Image]">
+<meta property="og:url" content="[Post URL]">
+<meta name="twitter:card" content="summary_large_image">
+<meta name="twitter:title" content="[Twitter Title or OG Title or Meta Title]">
+<meta name="twitter:description" content="[Twitter Description or OG Description or Meta Description]">
+<meta name="twitter:image" content="[Twitter Image or OG Image or Feature Image]">
+<meta name="twitter:site" content="@example">
+<meta name="twitter:creator" content="@example">
+```
+
+### Fallback Chain
+
+- **OG Title:** OG Title → Meta Title → Post Title
+- **OG Description:** OG Description → Meta Description → Custom Excerpt
+- **OG Image:** OG Image → Feature Image
+- **Twitter Title:** Twitter Title → OG Title → Meta Title → Post Title
+- **Twitter Image:** Twitter Image → OG Image → Feature Image
+
+### Verification
+
+```bash
+# Check what tags are being emitted
+curl -s https://example.com/<slug>/ | grep -E 'og:|twitter:'
+
+# Test with validators
+# Facebook: https://developers.facebook.com/tools/debug/
+# Twitter: https://cards-dev.twitter.com/validator
+# LinkedIn: https://www.linkedin.com/post-inspector/
+```
+
+## Layer 3: Code-Injected Schema
+
+Ghost CMS auto-generates basic Article/BlogPosting schema, but custom schema types (TechArticle, FAQPage, HowTo, Organization with areaServed) must be code-injected.
+
+### Injection Points in Ghost
+
+| Location | Scope | Method |
+|----------|-------|--------|
+| **Site-wide** (`ghost_head`) | Every page on the site | Settings → Code Injection → Site Header |
+| **Per-post** | Single post only | Post Settings → Code Injection → Post Header |
+| **Per-page** | Single page only | Page Settings → Code Injection → Post Header |
+| **ghost-cli** | Per-post via API | `ghost-cli --site <name> schema inject <slug> --file <path>` |
+
+### Per-Page Schema via ghost-cli
+
+The ghost-cli `schema inject` command handles the API call and stores the schema in the post's `codeinjection_head` field:
+
+```bash
+# Validate and inject FAQPage schema
+ghost-cli --site example schema validate --json '{"@context":"https://schema.org","@type":"FAQPage","mainEntity":[{"@type":"Question","name":"Q?","acceptedAnswer":{"@type":"Answer","text":"A."}}]}'
+
+ghost-cli --site example schema inject my-post --file /tmp/faq-schema.json
+```
+
+### Injecting Multiple Schema Types with @graph
+
+When a post benefits from multiple schema types (e.g., TechArticle + FAQPage), wrap them in a `@graph` array:
+
+```json
+{
+  "@context": "https://schema.org",
+  "@graph": [
+    {
+      "@type": "TechArticle",
+      "headline": "Post Title",
+      "proficiencyLevel": "Advanced",
+      "about": {"@type": "Thing", "name": "AI Agent Memory"}
+    },
+    {
+      "@type": "FAQPage",
+      "mainEntity": [
+        {"@type": "Question", "name": "Q1?", "acceptedAnswer": {"@type": "Answer", "text": "A1."}},
+        {"@type": "Question", "name": "Q2?", "acceptedAnswer": {"@type": "Answer", "text": "A2."}}
+      ]
+    }
+  ]
+}
+```
+
+### Schema Coverage by Site
+
+| Site | Required Schema | Injection Method |
+|------|----------------|------------------|
+| **example.com** | Organization (site-wide), TechArticle (per-post), FAQPage (when applicable) | ghost-cli `schema inject` for per-post; Code Injection → Settings for site-wide |
+| **example.org** | Organization + areaServed (site-wide), Article (auto), FAQPage (FAQ content), LocalBusiness if applicable | Same pattern |
+| **example.net** | Organization (site-wide), Article (auto) | Same pattern |
+
+### Validation
+
+Every schema injection must be validated:
+
+1. **Google Rich Results Test:** https://search.google.com/test/rich-results
+2. **Schema.org Validator:** https://validator.schema.org/
+3. **Manual check:** View page source → search for `application/ld+json`
+
+## Completion Checklist
+
+For every article publish:
+
+- [ ] **Meta Title** set (50-60 chars, keyword front-loaded)
+- [ ] **Meta Description** set (150-160 chars, includes keyword + CTA)
+- [ ] **Custom Excerpt** set (1-2 sentence summary for cards)
+- [ ] **OG Image** set (article feature image or explicit OG image)
+- [ ] **OG Title** verified (at minimum, confirm it defaults acceptably)
+- [ ] **OG Description** verified (at minimum, confirm it defaults acceptably)
+- [ ] **Twitter card** type confirmed (summary_large_image)
+- [ ] **Canonical URL** confirmed (self-referencing unless syndicated)
+- [ ] **Schema injected** (TechArticle for example.com, FAQPage if applicable)
+- [ ] **Schema validated** (Google Rich Results Test passes)
+- [ ] **Feature image** has alt text and caption
+- [ ] **Slug** is optimized (30-45 chars, primary keyword, stable)
+
+## Post-Publish Verification
+
+```bash
+# 1. Check meta tags render
+curl -s https://<site>/<slug>/ | grep -E '<title|name="description"|property="og:|name="twitter:'
+
+# 2. Check schema renders
+curl -s https://<site>/<slug>/ | grep 'application/ld+json'
+
+# 3. Validate schema (requires the JSON block)
+# Pipe the extracted JSON-LD to the Rich Results Test API
+```

package/skills/optbrew/modules/magnus-seo/references/implementation-playbook.md

@@ -0,0 +1,114 @@
+# AEO implementation playbook
+
+## Phase 0: Scope the answer surface
+
+Write a one-page scope before editing:
+
+- audience and decision/job to be done;
+- canonical entities, aliases, products, places, and disambiguators;
+- target providers and surfaces, such as Google AI features, Bing Copilot, ChatGPT Search, or Perplexity;
+- question families: definition, comparison, procedure, recommendation, troubleshooting, current status;
+- desired outcome and non-goals;
+- access, privacy, legal, and publication constraints;
+- baseline date and evidence cutoff.
+
+If the target surface is unknown, do not invent provider-specific tactics. Run a discovery pass and label the target as unresolved.
+
+## Phase 1: Build the evidence and question map
+
+1. Gather provider documentation before practitioner advice.
+2. Gather authoritative subject sources and independent corroboration.
+3. Build question clusters. Merge near-duplicates and identify questions that need separate pages because their answer, audience, freshness, or evidence differs.
+4. Assign one canonical answer location to every retained question.
+5. Record claims as source observation, vendor claim, inference, or unresolved conflict.
+6. Identify stale, contradictory, or unsupported existing answers before rewriting them.
+
+Use `templates/question-cluster.md` and the source card in `references/evidence-boundaries.md`.
+
+## Phase 2: Implement the answer asset
+
+For every canonical page or section:
+
+1. State the answer in the opening sentence or compact summary.
+2. Follow with scope, conditions, evidence, examples, and useful next actions.
+3. Use headings that describe the reader's question without turning every keyword permutation into a page.
+4. Use lists, tables, definitions, and examples where they improve human comprehension.
+5. Keep entity names, versions, dates, units, and terminology consistent.
+6. Link to primary evidence at the claim it supports, not only in a distant bibliography.
+7. Distinguish current facts from historical context and forecasts.
+8. Preserve a clear author/reviewer/update record where the subject warrants it.
+9. Add a “what this does not mean” boundary for comparisons, safety, policy, or high-stakes claims.
+
+Do not delete nuance to make a page more extractable. A concise answer followed by a qualification is better than an unqualified slogan.
+
+## Phase 3: Add machine-readable and discovery support selectively
+
+Choose only changes justified by the target provider and page content:
+
+- JSON-LD that matches visible content and the correct Schema.org type;
+- canonical links, crawlable internal links, accurate sitemap entries, and truthful `lastmod`;
+- provider-specific robots controls after an explicit search/training/user-fetch policy decision;
+- optional `llms.txt` when a site wants to publish a curated map for systems that choose to consume the proposal;
+- a Markdown representation or content negotiation only when the site can keep it equivalent to the rendered HTML and the target consumer benefits from it;
+- IndexNow or provider-native submission only through the platform's operational skill and only after the URL is actually ready.
+
+AEO does not authorize publishing, changing robots policy, or sending URLs. Confirm target, scope, and rollback before mutation, then verify the public boundary.
+
+## Phase 4: Verify before measurement
+
+Run the read-only script and platform checks:
+
+- fetch the final URL and inspect status, canonical, robots meta, headings, visible answer text, links, and JSON-LD;
+- parse every JSON-LD block and compare material fields with visible content;
+- check the public robots file and sitemap, including CDN/edge behavior;
+- confirm true modification dates rather than generated-file timestamps;
+- inspect a browser-rendered page when content is client-rendered;
+- record what each check cannot prove: a 200 is not indexing, parsing is not eligibility, and eligibility is not citation.
+
+## Phase 5: Establish a frozen answer baseline
+
+Use a prompt set with:
+
+- stable IDs and exact prompt text;
+- head, mid-tail, long-tail, comparison, and troubleshooting variants;
+- entity disambiguation prompts;
+- prompts where the correct answer should cite the target and prompts where it should not;
+- competitor or alternative entities only when the comparison is fair and evidence-supported.
+
+Record exact output and citations. Do not summarize from memory. Use `templates/citation-observation-log.md`.
+
+## Phase 6: Run bounded experiments
+
+Change one meaningful variable or a coherent bundle whose rationale is documented. Keep the prompt set, observation method, date window, and scoring rubric stable. Re-run enough samples to expose variability, but do not imply statistical certainty without an appropriate design. For platform-native metrics, preserve the dashboard definition and aggregation limits.
+
+A useful decision record says:
+
+```text
+hypothesis → change → expected mechanism → observation window → metric → result → confounders → next decision
+```
+
+## Phase 7: Maintain
+
+Set review triggers based on content risk and volatility:
+
+- source or specification change;
+- product/version release;
+- policy or legal change;
+- answer error or miscitation;
+- provider crawler or dashboard change;
+- meaningful query or conversion shift.
+
+Do not “refresh” a page by changing dates alone. Re-verify the claims, sources, links, schema, and answer observations after material updates.
+
+## Acceptance gate
+
+Pass only when:
+
+- scope and provider boundaries are explicit;
+- every retained question has a canonical answer location and owner;
+- visible content answers accurately before elaborating;
+- evidence, caveats, and dates are preserved;
+- machine-readable fields match visible content;
+- discovery and crawler changes are policy-approved and publicly verified;
+- the prompt baseline and post-change observations are reproducible;
+- the final report distinguishes implementation from observed impact.

package/skills/optbrew/modules/magnus-seo/references/measurement-and-experimentation.md

@@ -0,0 +1,47 @@
+# AEO measurement and experimentation
+
+## Measurement hierarchy
+
+Track outcomes separately: crawl access, index eligibility, retrieval, mention, citation, citation correctness, share of voice, click, and conversion. A citation count cannot establish authority, ranking, correctness, or revenue.
+
+## Frozen prompt set
+
+Store stable IDs, exact prompt text, target entity, intent, expected source boundary, and version. Include disambiguation, definition, comparison, procedure, troubleshooting, current-status, and negative-control prompts. Do not silently rewrite prompts between runs.
+
+## Observation record
+
+For every run preserve date/time, provider, surface, model/version if known, account/location state, prompt ID/hash, exact answer, cited URLs, target-cited status, citation quality, correctness, and notes about provider changes. Normalize URLs for analysis without destroying the original URL.
+
+## Scoring
+
+Use a rubric defined before looking at results:
+
+- target mention: 0/1;
+- target citation: 0/1;
+- citation relevance: 0–2;
+- citation support/correctness: 0–2;
+- answer completeness: 0–2;
+- harmful or misleading claim: 0/1;
+- target answer coverage across the set: percentage, with denominator stated.
+
+Keep human scoring, automated extraction, and provider-native dashboard metrics distinct.
+
+## Experiment design
+
+Write `hypothesis → change → expected mechanism → prompt set → window → metric → result → confounders → decision`. Keep the content change and measurement method stable enough to compare. Repeated model outputs are not independent evidence by default. Provider model, index, UI, location, personalization, and prompt changes can confound the result.
+
+A before/after observation supports “we observed a change under these conditions,” not “the rewrite caused the change,” unless the design supports causal inference.
+
+## Platform-native evidence
+
+Google Search Console reports AI feature traffic within its search reporting and provides a generative AI performance report where available. Bing Webmaster Tools AI Performance reports citations, cited pages, grounding queries, and trends, but its documentation explicitly says aggregate values do not show ranking, authority, placement, or page importance. Preserve those definitions in the report.
+
+## Cadence
+
+Use weekly or monthly checks only when the prompt set and ownership justify them. Re-run after provider changes, high-risk content updates, or observed miscitation. Stop after a bounded experiment when results are inconclusive; do not manufacture a win from more retries.
+
+## References
+
+- [Bing AI Performance](https://blogs.bing.com/webmaster/February-2026/Introducing-AI-Performance-in-Bing-Webmaster-Tools-Public-Preview)
+- [Google AI features measurement](https://developers.google.com/search/docs/appearance/ai-features)
+- `templates/citation-observation-log.md`