optbrew 0.0.0-stage → 0.1.2

package/skills/optbrew/licenses/firecrawl-seo-audit.txt

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Firecrawl
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/skills/optbrew/licenses/magnus-seo.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Magnus Hedemark
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/optbrew/licenses/marketing-search.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Corey Haines
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/optbrew/licenses/mblode-seo.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Blode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/optbrew/licenses/naver-searchadvisor.txt

@@ -0,0 +1,29 @@
+MIT License
+
+Copyright (c) 2026 JaceProgramming
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+NOTE: This MIT license covers the original work in this repository only —
+SKILL.md, scripts/, tools/, README.md, NOTICE.md, and references/INDEX.md.
+
+The documents under references/guide/ are the copyrighted property of
+NAVER Corporation and are NOT covered by this license. See NOTICE.md.

package/skills/optbrew/licenses/seranking-seo.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SE Ranking
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/optbrew/modules/firecrawl-seo-audit/GUIDE.md

@@ -0,0 +1,64 @@
+# Firecrawl SEO Audit
+
+Use this to turn a website into a specific, prioritized SEO audit.
+
+## Onboarding Interview
+
+Infer the site, target keywords, and output format from context. If the site is clear, proceed immediately.
+
+Ask at most 1-3 concise questions only if blocked, such as the site URL, required target keywords, or whether a specific page/competitor set matters.
+
+## Firecrawl Collection Plan
+
+1. Map the site with Firecrawl to understand URL structure.
+2. Scrape key pages: homepage, product/service pages, pricing, docs, blog, about, and high-value landing pages.
+3. Extract title tags, meta descriptions, headings, internal links, content structure, canonical signals when visible, and image alt text when available.
+4. Search target keywords when provided; scrape top ranking pages for comparison.
+
+## Parallel Work
+
+If appropriate, use sub-agents or equivalent parallel task runners:
+
+- Site Structure: URL patterns, sitemap health, internal linking, orphan/broken pages.
+- On-Page SEO: titles, meta descriptions, H1/H2 hierarchy, content quality.
+- Keyword And SERP: target keywords, ranking pages, competitor page patterns.
+- Technical Issues: broken links, duplicate content signals, missing metadata.
+
+## Final Deliverable
+
+```markdown
+# SEO Audit: [Site]
+
+## Executive Summary
+[Top risks and opportunities]
+
+## Site Structure
+[Pages found, URL quality, sitemap/internal-link notes]
+
+## On-Page SEO
+[Per-page title, meta, headings, content, linking notes]
+
+## Keyword Opportunities
+[Target keywords, missing pages, content gaps]
+
+## Competitor/SERP Comparison
+[Who outranks the site and why]
+
+## Prioritized Recommendations
+[High/medium/low impact fixes with exact changes]
+
+## Sources
+[URLs scraped and what was checked]
+
+## Rerun Inputs
+workflow: firecrawl-seo-audit
+site: [url]
+keywords: [list]
+output: [markdown/json]
+```
+
+## Quality Bar
+
+- Make recommendations specific, not generic.
+- Show the page or source behind each issue.
+- Distinguish technical findings from content strategy guesses.

package/skills/optbrew/modules/magnus-seo/GUIDE.md

@@ -0,0 +1,79 @@
+# SEO
+
+A full-spectrum search visibility skill. It treats traditional SEO, Answer Engine Optimization (AEO), and Generative Engine Optimization (GEO) as overlapping work across different search and answer surfaces, not as separate collections of ranking hacks.
+
+## Operating model
+
+1. **Scope the surface and outcome.** Name the provider, product or search surface, audience, entity, questions, business outcome, and exclusions. Define whether success means crawl access, index eligibility, retrieval, mention, citation, citation correctness, share of voice, referral, or conversion.
+2. **Inspect and research.** Audit the public/rendered page and technical delivery. Read current first-party provider guidance and authoritative subject sources. Treat practitioner claims and vendor studies as hypotheses unless methods and scope support more.
+3. **Map intent to canonical content.** Use topics and question clusters, but avoid manufacturing near-duplicate pages. Assign one canonical answer location, entity ownership, evidence, freshness owner, and internal links.
+4. **Improve people-first content and structure.** Put a concise answer near the relevant heading, then supporting evidence, qualifications, and useful detail. Preserve natural prose, distinct point of view, accessibility, and human value.
+5. **Implement only supported controls.** Fix crawlability, indexability, metadata, internal links, page experience, textual content, structured-data parity, sitemaps, freshness, and provider-specific crawler or preview controls. Optional files such as `llms.txt` or Markdown representations are provider-scoped proposals, not universal requirements.
+6. **Measure at the correct boundary.** Freeze prompts and versions, capture exact answers and citations, score citation correctness, and use provider-native reports where available. Separate implementation evidence from observed visibility and causal claims.
+7. **Verify and learn.** Recheck the rendered/public boundary, validate structured data, inspect search-console or provider evidence, and run bounded one-variable experiments. Do not declare success from HTTP 200, parseable JSON-LD, a single answer, or a third-party score.
+
+## Terminology and boundaries
+
+- **SEO** is the umbrella: improving a site's eligibility, discoverability, interpretation, and useful visibility in search systems.
+- **AEO** is a stakeholder label for answer-oriented work, including direct answers, snippets, knowledge surfaces, and answer-engine inclusion.
+- **GEO** is a stakeholder label for visibility in generated answers, especially being selected, cited, or factually absorbed into a synthesized response. The term originated in the 2024 KDD paper by Aggarwal et al.; it does not establish a universal algorithm.
+- **LLMO** and **AI-search optimization** are overlapping labels. Preserve the target organization's term, then define the measurable outcome and provider scope.
+- These terms do not guarantee ranking, inclusion, citation, traffic, recommendation, or conversion. A mention is not a citation, a citation is not proof of correctness, and a citation is not a click.
+
+## Evidence rules
+
+Use these labels in plans and reports:
+
+- **Primary documentation:** provider, standards body, schema vocabulary, or tool owner describes its own behavior.
+- **Observed:** recorded crawl, rendered page, provider dashboard, exact answer, URL, or reproducible local result.
+- **Independent study:** disclosed method and dataset, with generalization limits stated.
+- **Vendor-reported:** useful for hypothesis generation, not a universal rule.
+- **Inference:** reasoned interpretation beyond direct observation.
+- **Unresolved:** provider-dependent, stale, contradicted, or not verified.
+
+Reject claims such as “FAQ schema guarantees citations,” “short paragraphs are required by all engines,” “`llms.txt` is a search standard,” or “allowing a crawler guarantees inclusion.” Record source URL, access date, provider scope, exact support, what it does not prove, confidence, and refresh trigger for every material claim.
+
+## Reference routing
+
+| Need | Read |
+|---|---|
+| Crawlability, indexability, robots, sitemaps, performance, canonicals, mobile, HTTPS | `references/technical-seo.md` |
+| Titles, descriptions, headings, content quality, links, images | `references/onpage-seo.md` |
+| Schema.org, JSON-LD, rich-result eligibility, visible parity | `references/schema-markup.md` and `references/structured-data.md` |
+| Topics, question clusters, entities, answer blocks, evidence architecture | `references/content-and-entity-architecture.md` |
+| Full answer/generative implementation sequence and completion gate | `references/implementation-playbook.md` |
+| Provider guidance, crawler identities, robots and preview controls | `references/platform-guidance.md` and `references/discovery-and-freshness.md` |
+| `llms.txt`, Markdown delivery, content negotiation, provider support | `references/agent-readable-content.md` |
+| Outcome definitions, confidence, and rejected claims | `references/evidence-boundaries.md` |
+| Prompt sets, citation logs, metrics, experiments, and confounders | `references/measurement-and-experimentation.md` |
+| Ghost metadata and injection | `references/ghost-metadata.md` |
+| Content strategy, topic clusters, keywords, gaps, SERP features | `references/content-strategy-seo.md` |
+| Source URLs, access dates, authority tiers, and refresh notes | `references/source-index.md` |
+
+## Scripts and templates
+
+Run from the skill directory:
+
+```bash
+python3 scripts/aeo_audit.py <local-page.html> --json
+python3 scripts/build_prompt_matrix.py <topics.json> --output prompt-matrix.json
+```
+
+The upstream script tests are source-maintenance material and are not part of this distributed bundle. The scripts are read-only and use the Python standard library. The direct URL option is disabled in optbrew. Use `node skills/optbrew/scripts/audit.mjs --context <run-context.json> --modules magnus-seo --output-dir <run-dir>` to inspect collector-preserved HTML. The parser can also read that HTML from stdin with `--stdin --source-url <collected-url>`. It does not execute JavaScript, call an LLM, publish, submit URLs, or change crawler policy. Templates cover implementation plans, question clusters, citation observations, optional `llms.txt`, and crawler-policy decisions.
+
+## Audit output
+
+Use `assets/audit-report-template.md` and distinguish:
+
+- **Observed findings:** what the inspected page, response, dashboard, or answer actually shows.
+- **Recommended changes:** proposed actions with owner, risk, expected mechanism, and verification.
+- **Provider scope:** which engine or search surface the evidence applies to.
+- **Status:** implemented, verified, observed, inferred, or unresolved.
+
+## When not to use
+
+Do not use this skill alone for only mechanical copy-editing, ordinary article writing, CMS administration, or a generic request to “rank better” without a defined target, evidence boundary, or measurable outcome. Route those to the relevant writing, copy-editing, CMS, or product skill.
+
+## Portability
+
+Use the host agent's normal mechanisms to load references, templates, and scripts. Do not assume a particular profile system, orchestrator, memory service, CMS, search console, or provider API.

package/skills/optbrew/modules/magnus-seo/README.md

@@ -0,0 +1,45 @@
+# SEO
+
+One umbrella skill for technical SEO, on-page optimization, Answer Engine Optimization (AEO), and Generative Engine Optimization (GEO). It helps an agent improve search discoverability and AI-answer visibility without confusing provider-specific evidence with universal ranking rules.
+
+## Why Install This Skill
+
+Search visibility now spans ranked results, direct answers, AI Overviews, conversational search, and generated answers. This skill consolidates the former SEO audit and AEO workflows so an agent can inspect the technical foundation, improve human-useful content, implement supported controls, and measure citations and referrals with explicit evidence boundaries.
+
+## What You Get
+
+| Path | Purpose |
+|---|---|
+| `GUIDE.md` | Umbrella routing, terminology, workflow, evidence rules, and completion boundary |
+| `references/` | Technical SEO, on-page SEO, schema, content strategy, AEO/GEO implementation, provider guidance, agent-readable content, and measurement |
+| `templates/` | Implementation plan, question cluster, citation observation, optional `llms.txt`, and crawler-policy templates |
+| `scripts/aeo_audit.py` | Read-only structural audit of local HTML or a URL |
+| `scripts/build_prompt_matrix.py` | Deterministic prompt-set generation |
+| `scripts/test_aeo_scripts.py` | Offline regression tests for the scripts |
+| `evals/evals.json` | Output-quality evaluation cases |
+
+## Quick Start
+
+```bash
+python3 scripts/aeo_audit.py https://example.com/article --json
+python3 scripts/build_prompt_matrix.py topics.json --output prompt-matrix.json
+python3 -m pytest scripts/test_aeo_scripts.py
+```
+
+The scripts are read-only and use Python's standard library. They do not call an LLM, publish, submit URLs, or modify robots policy.
+
+## Triggers
+
+- Audit or improve technical SEO, on-page SEO, schema, content discoverability, or search visibility
+- Implement or assess AEO, GEO, LLMO, AI-search optimization, or generative search visibility
+- Make content easier for people and answer systems to understand, retrieve, cite, and verify
+- Build question clusters, answer-first content, evidence blocks, entity architecture, or canonical topic maps
+- Assess AI crawler controls, preview controls, sitemaps, freshness, `llms.txt`, Markdown delivery, or content negotiation
+- Design frozen prompt sets, citation logs, share-of-voice checks, or bounded AI-search experiments
+- Complete Ghost metadata, social cards, or schema injection in support of search visibility
+
+## Requirements
+
+- Python 3.9+ for bundled scripts
+- Network access when auditing a URL; local HTML works offline
+- Provider dashboards, CMS credentials, and Search Console access are optional and belong to the relevant platform workflow

package/skills/optbrew/modules/magnus-seo/assets/audit-report-template.md

@@ -0,0 +1,76 @@
+# SEO Audit Report Template
+
+Scaffold for new SEO audit projects. Copy this into your pyramid root.
+
+```markdown
+# SEO Audit: [Site/Page URL]
+
+**Audit date:** YYYY-MM-DD
+**Auditor:** seo-specialist profile
+**Scope:** [Full site / Single page / Content strategy]
+
+---
+
+## L1 Summary
+
+### Overall Health: [Good / Fair / Poor]
+### Score: [N/100]
+
+### Priority Findings
+1. [Critical] → [Action]
+2. [Critical] → [Action]
+
+### Moderate Findings
+1. [Important] → [Action]
+
+### Quick Wins
+1. [Low effort, high impact] → [Action]
+
+---
+
+## L2 Analysis Files
+
+### Technical SEO
+- Crawlability and indexability
+- Page speed / Core Web Vitals
+- Mobile-friendliness
+- HTTPS and security
+- Canonical URLs and hreflang
+- Sitemap and robots.txt
+
+### On-Page SEO
+- Title tags and meta descriptions
+- Heading structure
+- Keyword usage
+- Content quality and length
+- Internal linking
+- Image optimization
+- URL structure
+
+### Schema Validation
+- JSON-LD structure
+- Schema.org types used
+- Rich result eligibility
+- Validation results
+
+### Content Gap Analysis
+- Target keywords
+- Current rankings
+- Competitor analysis
+- Gap identification
+- Priority recommendations
+
+---
+
+## L3 Dossiers
+
+### Raw Data
+- Full crawl results
+- Schema validation output
+- Keyword research data
+- Competitor SERP data
+
+### Methodology Notes
+- Tools used
+- Assumptions and limitations
+- Data collection dates

package/skills/optbrew/modules/magnus-seo/references/aeo-methodology.md

@@ -0,0 +1,105 @@
+# Search, Answer, and Generative Engine Optimization
+
+## Working definition
+
+SEO is the umbrella discipline for improving a site's eligibility, discovery, interpretation, and useful visibility in search systems. AEO and GEO are overlapping labels for work on answer-producing surfaces. Use the stakeholder's label, but define the actual provider, mechanism, and measurable outcome.
+
+- **AEO** commonly emphasizes direct answers, featured snippets, knowledge surfaces, and answer-engine inclusion.
+- **GEO** commonly emphasizes generated answers, source selection, citation, and whether source evidence is reflected in the answer. The term was formalized as Generative Engine Optimization in Aggarwal et al.'s KDD 2024 paper.
+- **LLMO** and **AI-search optimization** are overlapping industry labels, not standardized disciplines.
+
+None of these labels identifies a universal ranking algorithm or guarantees inclusion, citation, recommendation, traffic, or conversion.
+
+## Generative search model
+
+Many current systems combine search or retrieval with generation, but their indexes, ranking systems, crawlers, models, interfaces, and policies differ. A useful working decomposition is:
+
+1. query interpretation or fan-out;
+2. candidate retrieval;
+3. source selection or reranking;
+4. answer synthesis;
+5. citation, link, or attribution rendering;
+6. user click, action, or conversion.
+
+This model helps locate evidence. It is not a provider specification. A publisher can improve the quality and accessibility of its content and observe outcomes, but cannot directly control a provider's retrieval or generation decision.
+
+## What the strongest evidence supports
+
+### Academic evidence
+
+Aggarwal et al. (KDD 2024, arXiv:2311.09735) introduced GEO and evaluated content transformations in a controlled benchmark of generative engines. The paper reports that some transformations, including adding citations, quotations, and statistics, improved its benchmark visibility metrics, while effects varied by domain and method. Its metrics account for the amount and position of answer text associated with a citation, rather than treating every citation as an equivalent blue-link impression. This is evidence for testable hypotheses in that benchmark, not a cross-provider ranking recipe.
+
+Liu et al. (2023, arXiv:2304.09848) found substantial citation-support and sentence-support failures in generative search answers. Citation presence therefore cannot substitute for checking whether the cited source supports the adjacent claim.
+
+Later papers and surveys may provide useful hypotheses, but check version, venue, dataset, engine, prompt set, and reproducibility before treating a reported lift as portable.
+
+### First-party guidance
+
+Google says its AI Overviews and AI Mode use core Search systems and that ordinary SEO fundamentals remain relevant. It states that there are no additional technical requirements or special AI markup, and that Google Search does not use `llms.txt` for visibility. It recommends useful people-first content, clear technical structure, textual content, relevant media, internal links, accurate structured data, and truthful business or product data. Google also warns against scaled, inauthentic, or query-variant content created to manipulate AI responses.
+
+Bing's AI Performance report exposes citations, cited pages, grounding queries, and trends across supported Microsoft AI experiences. Bing explicitly limits those metrics: they show citation activity, not ranking, authority, page importance, or placement.
+
+OpenAI documents separate crawler controls for OAI-SearchBot, GPTBot, and ChatGPT-User. Allowing a search crawler can make a page eligible for consideration, but OpenAI does not guarantee placement. Anthropic and Perplexity publish their own crawler and robots guidance. Never transfer one provider's crawler semantics to another.
+
+## Implementation principles
+
+- Answer the user's question near the relevant heading, then provide evidence, scope, caveats, and useful detail. This is a usability and extraction hypothesis, not a universal formatting rule.
+- Use clear headings, descriptive titles, coherent entity names, accessible text, links, tables, and lists where they help people. Do not reduce prose to fragments or duplicate pages for every query variant.
+- Support material claims with primary sources, dates, methods, first-hand experience, or clearly labeled analysis. Preserve uncertainty.
+- Keep visible content, metadata, JSON-LD, feeds, Markdown representations, and summaries semantically consistent. Structured data describes visible facts; it does not create them.
+- Treat robots directives as access and preview policy controls. Separate search access, training use, user-triggered fetching, and commercial permissions where the provider supports those distinctions.
+- Use sitemaps, truthful `lastmod`, IndexNow, and recrawl requests as discovery or freshness mechanisms where supported. None guarantees retrieval or citation.
+- Treat `llms.txt` as an optional community proposal. It may be useful to a consumer that chooses to read it, but it is not a W3C, IETF, or universal search requirement, and Google says it ignores it for Search visibility.
+
+## Outcome taxonomy
+
+Track these separately:
+
+| Outcome | Meaning | Evidence |
+|---|---|---|
+| Crawl access | A named crawler fetched a resource | Logs, headers, provider documentation |
+| Index eligibility | A resource can enter a provider index | Provider diagnostics; a 200 is insufficient |
+| Retrieval | A resource was selected for a query or grounding step | Provider-native data or reproducible observation |
+| Mention | The entity appears in generated text | Exact answer snapshot |
+| Citation | The answer links or names the source | Exact answer and URL |
+| Citation correctness | The source supports the adjacent claim | Source-to-claim comparison |
+| Share of voice | Visibility relative to a defined comparator set | Frozen prompts and scoring rules |
+| Referral | A user visits after an answer interaction | Analytics with attribution limits |
+| Conversion | A defined downstream action occurs | Instrumented funnel and causal design |
+
+## Measurement protocol
+
+Freeze a prompt matrix with stable IDs, exact text, intent, target entity, expected source boundary, and version. Include definition, comparison, procedure, troubleshooting, current-status, disambiguation, and negative-control prompts.
+
+For each observation preserve the date, provider, surface, model/version if known, account/location state, prompt ID, exact answer, cited URLs, mention and citation status, relevance, support, completeness, misleading claims, and provider changes. Normalize URLs for analysis without discarding originals.
+
+Define a rubric before looking at results. A practical record can score target mention (0/1), target citation (0/1), citation relevance (0-2), citation support (0-2), answer completeness (0-2), and harmful or misleading claims (0/1). Keep human scoring, automated extraction, and provider-native dashboards distinct.
+
+For experiments record: `hypothesis -> change -> expected mechanism -> prompt set -> window -> metric -> result -> confounders -> decision`. A before/after change supports an observation under stated conditions, not causal attribution, unless the design supports it. Repeated model outputs are not automatically independent observations.
+
+## Claims to reject or narrow
+
+Do not publish or encode as rules:
+
+- fixed citation or conversion multipliers from an opaque vendor study;
+- “FAQPage guarantees AI citations” or any universal schema multiplier;
+- “short paragraphs,” exact-match questions, keyword variants, or chunking are required by all engines;
+- allowing every AI crawler guarantees inclusion or citation;
+- `llms.txt` is a universal standard or a Google ranking signal;
+- a citation count proves authority, ranking, correctness, traffic, or revenue;
+- a passing structural audit proves retrieval or citation.
+
+Record authority tier, provider scope, access date, exact supporting observation, non-proof, confidence, and refresh trigger for every material claim.
+
+## Sources
+
+- Google, [Optimizing your website for generative AI features on Google Search](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide), accessed 2026-08-26.
+- Google, [AI features and your website](https://developers.google.com/search/docs/appearance/ai-features), accessed 2026-08-26.
+- Microsoft Bing, [Introducing AI Performance in Bing Webmaster Tools](https://blogs.bing.com/webmaster/February-2026/Introducing-AI-Performance-in-Bing-Webmaster-Tools-Public-Preview), accessed 2026-08-26.
+- OpenAI, [Overview of OpenAI Crawlers](https://developers.openai.com/api/docs/bots), accessed 2026-08-26.
+- OpenAI, [ChatGPT search](https://help.openai.com/en/articles/9237897), accessed 2026-08-26.
+- Perplexity, [Perplexity Crawlers](https://docs.perplexity.ai/docs/resources/perplexity-crawlers), accessed 2026-08-26.
+- Anthropic, [Does Anthropic crawl data from the web?](https://support.anthropic.com/en/articles/8896518-does-anthropic-crawl-data-from-the-web-and-how-can-site-owners-block-the-crawler), accessed 2026-08-26.
+- Aggarwal et al., [GEO: Generative Engine Optimization](https://arxiv.org/html/2311.09735v3), KDD 2024, accessed 2026-08-26.
+- Liu et al., [Evaluating Verifiability in Generative Search Engines](https://arxiv.org/abs/2304.09848), 2023, accessed 2026-08-26.
+- [llms.txt proposal](https://llmstxt.org/), accessed 2026-08-26.

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

@@ -0,0 +1,28 @@
+# Agent-readable content
+
+## `llms.txt`
+
+`llms.txt` is a community proposal for a concise Markdown map of a site: identity, scope, and links to useful pages or Markdown documents. It is not a universal standard and is not required for Google Search or Google AI features; Google says it ignores the file for those systems. Use it only when the site wants to offer an optional curated context surface to consumers that choose to read it.
+
+Keep it factual, short, maintained, and consistent with public pages. Do not put secrets, private URLs, unsupported claims, or a duplicate site map that nobody owns. A link in `llms.txt` does not bypass robots, authentication, indexing, or provider policy.
+
+## Markdown delivery
+
+A site may offer a Markdown representation or content negotiation, but this is an implementation choice, not a universal AEO requirement. Keep HTML and Markdown semantically equivalent, preserve links and dates, and test caching, canonical behavior, content type, and access controls. Do not assume an AI client sends `Accept: text/markdown` or that a provider will prefer it.
+
+## Provider selection
+
+Before implementing an agent-readable surface, answer:
+
+- Which consumer is expected to use it?
+- Is there current provider documentation or only a proposal?
+- Who maintains parity with HTML?
+- What content is intentionally excluded?
+- How will stale links and claims be detected?
+- What does success mean, and how will it be observed?
+
+## Primary references
+
+- [llms.txt proposal](https://llmstxt.org/)
+- [llms.txt repository](https://github.com/AnswerDotAI/llms-txt)
+- [Google AI optimization guide](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide)

package/skills/optbrew/modules/magnus-seo/references/content-and-entity-architecture.md

@@ -0,0 +1,100 @@
+# AEO content and entity architecture
+
+## Page model
+
+Treat a page as an answer asset with explicit contracts:
+
+```text
+entity/topic → audience → question cluster → canonical page → answer blocks
+            → evidence → qualifiers → related links → owner → review trigger
+```
+
+A page should have one primary subject. A cluster may contain related questions, but do not create a page for every phrasing variant. Split when the audience, answer, evidence, freshness, or decision differs materially.
+
+## Question cluster design
+
+Collect questions from real user language, support tickets, sales calls, site search, forums, interviews, and observed answer prompts. Normalize them into intents:
+
+- definition and disambiguation;
+- “how does it work?” and procedure;
+- comparison and alternatives;
+- recommendation and fit;
+- troubleshooting and failure recovery;
+- current status, price, compatibility, policy, or availability.
+
+For every question record:
+
+- exact wording and normalized intent;
+- named entities and aliases;
+- expected answer type and confidence;
+- canonical page/section;
+- evidence and date boundary;
+- caveat or non-answer condition;
+- next useful internal link;
+- owner and review trigger.
+
+## Answer block pattern
+
+```markdown
+## [Reader's question]
+
+[Direct answer in one or two sentences, including the scope or key qualification.]
+
+[Evidence, mechanism, examples, trade-offs, and exceptions.]
+
+[Primary source link at the claim it supports.]
+
+[What this does not establish, if omission could mislead.]
+```
+
+The opening answer should stand alone when extracted, but it must not become falsely absolute. Put the entity, version, geography, date, and condition in the answer when they change its truth.
+
+## Entity clarity
+
+Use one canonical name consistently, then introduce legitimate aliases once. Disambiguate names that collide with other products, companies, people, places, or concepts. Link to authoritative identity pages where useful, but do not create `sameAs` links merely because a name looks similar.
+
+Maintain a small entity record:
+
+```text
+canonical_name:
+aliases:
+entity_type:
+identifier:
+official_url:
+related_entities:
+not_this_entity:
+last_verified:
+owner:
+```
+
+Do not infer identity from a search snippet. Verify official URLs, identifiers, ownership, and version scope.
+
+## Evidence placement
+
+Place evidence beside the claim it supports. Prefer:
+
+1. official specification, documentation, filing, policy, or source code;
+2. independent reproduction or reputable reporting;
+3. first-hand observation with method and date;
+4. vendor claim, explicitly attributed;
+5. inference, explicitly marked.
+
+A bibliography cannot repair a source mismatch. A source can support a fact without supporting the causal explanation drawn from it.
+
+## Comparison pages
+
+Comparisons need a shared evaluation frame. Record artifact/version, scope, criteria, test conditions, missing capabilities, and who measured the result. Separate fit, task success, latency, cost, reliability, and qualitative judgment. If conditions are not comparable, present parallel evidence and a decision framework instead of a ranking.
+
+## Anti-patterns
+
+- exact-match question pages with no distinct answer;
+- a glossary that repeats a definition without sources or disambiguation;
+- “answer-first” copy that hides material qualifications below the fold;
+- inconsistent names, versions, dates, and units across pages;
+- entity links chosen for SEO rather than identity confidence;
+- a generic FAQ bolted onto an article solely to justify FAQPage markup;
+- citations that support a neighboring claim but not the sentence they follow.
+
+## Review gate
+
+A content architecture passes when a reviewer can answer: what question is this page for, what entity does it describe, where is the canonical answer, what source proves each material claim, what would make it stale, and where should a reader go next?