optbrew 0.0.0-stage → 0.1.2

package/skills/optbrew/modules/marketing-search/skills/site-architecture/references/site-type-templates.md

@@ -0,0 +1,293 @@
+# Site Type Templates
+
+Full page hierarchy templates with ASCII trees, URL maps, and navigation recommendations for common site types.
+
+---
+
+## SaaS Marketing Site
+
+### Page Hierarchy
+
+```
+Homepage (/)
+├── Features (/features)
+│   ├── Feature A (/features/feature-a)
+│   ├── Feature B (/features/feature-b)
+│   └── Feature C (/features/feature-c)
+├── Pricing (/pricing)
+├── Customers (/customers)
+│   ├── Case Study 1 (/customers/company-name)
+│   └── Case Study 2 (/customers/company-name-2)
+├── Resources (/resources)
+│   ├── Blog (/blog)
+│   │   └── [Posts] (/blog/post-slug)
+│   ├── Templates (/resources/templates)
+│   │   └── [Template] (/resources/templates/template-slug)
+│   └── Guides (/resources/guides)
+│       └── [Guide] (/resources/guides/guide-slug)
+├── Integrations (/integrations)
+│   └── [Integration] (/integrations/integration-name)
+├── Docs (/docs)
+│   ├── Getting Started (/docs/getting-started)
+│   ├── Guides (/docs/guides)
+│   └── API Reference (/docs/api)
+├── About (/about)
+│   ├── Careers (/about/careers)
+│   └── Contact (/contact)
+├── Compare (/compare)
+│   └── [Competitor] (/compare/competitor-name)
+├── Privacy (/privacy)
+└── Terms (/terms)
+```
+
+### URL Map
+
+| Page | URL | Nav Location | Priority |
+|------|-----|-------------|----------|
+| Homepage | `/` | Header (logo) | Critical |
+| Features | `/features` | Header | High |
+| Feature pages | `/features/{slug}` | Header dropdown | Medium |
+| Pricing | `/pricing` | Header | Critical |
+| Customers | `/customers` | Header | Medium |
+| Case studies | `/customers/{slug}` | Customers dropdown | Medium |
+| Blog | `/blog` | Header (Resources) | High |
+| Blog posts | `/blog/{slug}` | — | Medium |
+| Integrations | `/integrations` | Header | Medium |
+| Docs | `/docs` | Header | Medium |
+| Compare | `/compare/{slug}` | Footer | High (SEO) |
+| About | `/about` | Footer | Low |
+| Pricing CTA | `/pricing` | Header (CTA button) | Critical |
+
+### Navigation
+
+**Header (6 items + CTA)**: Features | Pricing | Customers | Resources | Integrations | Docs | [Get Started]
+
+**Footer columns**:
+- Product: Features, Pricing, Integrations, Changelog, Security
+- Resources: Blog, Templates, Guides, Case Studies
+- Company: About, Careers, Contact, Press
+- Legal: Privacy, Terms, Security
+
+---
+
+## Content / Blog Site
+
+### Page Hierarchy
+
+```
+Homepage (/)
+├── Blog (/blog)
+│   ├── [Category: Topic A] (/blog/category/topic-a)
+│   ├── [Category: Topic B] (/blog/category/topic-b)
+│   ├── [Category: Topic C] (/blog/category/topic-c)
+│   └── [Posts] (/blog/post-slug)
+├── Newsletter (/newsletter)
+├── Resources (/resources)
+│   ├── Guides (/resources/guides)
+│   │   └── [Guide] (/resources/guides/guide-slug)
+│   └── Tools (/resources/tools)
+│       └── [Tool] (/resources/tools/tool-slug)
+├── About (/about)
+├── Contact (/contact)
+├── Privacy (/privacy)
+└── Terms (/terms)
+```
+
+### URL Map
+
+| Page | URL | Nav Location | Priority |
+|------|-----|-------------|----------|
+| Homepage | `/` | Header (logo) | Critical |
+| Blog index | `/blog` | Header | High |
+| Categories | `/blog/category/{slug}` | Header dropdown | Medium |
+| Posts | `/blog/{slug}` | — | Medium |
+| Newsletter | `/newsletter` | Header (CTA) | High |
+| Guides | `/resources/guides` | Header | Medium |
+| About | `/about` | Header | Low |
+
+### Navigation
+
+**Header (4 items + CTA)**: Blog | Resources | About | Contact | [Subscribe]
+
+**Sidebar** (on blog): Categories, Popular Posts, Newsletter signup
+
+---
+
+## E-Commerce
+
+### Page Hierarchy
+
+```
+Homepage (/)
+├── Shop (/shop)
+│   ├── Category A (/shop/category-a)
+│   │   ├── Subcategory (/shop/category-a/subcategory)
+│   │   │   └── [Product] (/shop/category-a/subcategory/product-slug)
+│   │   └── [Product] (/shop/category-a/product-slug)
+│   ├── Category B (/shop/category-b)
+│   │   └── [Product] (/shop/category-b/product-slug)
+│   └── Category C (/shop/category-c)
+│       └── [Product] (/shop/category-c/product-slug)
+├── Collections (/collections)
+│   └── [Collection] (/collections/collection-slug)
+├── Sale (/sale)
+├── Blog (/blog)
+│   └── [Posts] (/blog/post-slug)
+├── About (/about)
+│   └── Our Story (/about/our-story)
+├── Help (/help)
+│   ├── FAQ (/help/faq)
+│   ├── Shipping (/help/shipping)
+│   ├── Returns (/help/returns)
+│   └── Contact (/contact)
+├── Cart (/cart)
+├── Account (/account)
+├── Privacy (/privacy)
+└── Terms (/terms)
+```
+
+### URL Map
+
+| Page | URL | Nav Location | Priority |
+|------|-----|-------------|----------|
+| Homepage | `/` | Header (logo) | Critical |
+| Shop | `/shop` | Header | Critical |
+| Categories | `/shop/{category}` | Header mega menu | High |
+| Products | `/shop/{category}/{product}` | — | High |
+| Collections | `/collections/{slug}` | Header | Medium |
+| Sale | `/sale` | Header (highlighted) | High |
+| Cart | `/cart` | Header (icon) | Critical |
+| Account | `/account` | Header (icon) | Medium |
+
+### Navigation
+
+**Header (5 items + cart/account)**: Shop (mega menu) | Collections | Sale | Blog | Help | [Cart icon] [Account icon]
+
+**Mega menu under Shop**: Category columns with featured products/images
+
+---
+
+## Documentation Site
+
+### Page Hierarchy
+
+```
+Docs Home (/docs)
+├── Getting Started (/docs/getting-started)
+│   ├── Installation (/docs/getting-started/installation)
+│   ├── Quick Start (/docs/getting-started/quick-start)
+│   └── Configuration (/docs/getting-started/configuration)
+├── Guides (/docs/guides)
+│   ├── Guide A (/docs/guides/guide-a)
+│   ├── Guide B (/docs/guides/guide-b)
+│   └── Guide C (/docs/guides/guide-c)
+├── API Reference (/docs/api)
+│   ├── Authentication (/docs/api/authentication)
+│   ├── Endpoints (/docs/api/endpoints)
+│   └── Webhooks (/docs/api/webhooks)
+├── Examples (/docs/examples)
+│   └── [Example] (/docs/examples/example-slug)
+├── Changelog (/docs/changelog)
+└── FAQ (/docs/faq)
+```
+
+### URL Map
+
+| Page | URL | Nav Location | Priority |
+|------|-----|-------------|----------|
+| Docs home | `/docs` | Header | High |
+| Getting Started | `/docs/getting-started` | Sidebar (top) | Critical |
+| Guides | `/docs/guides` | Sidebar | High |
+| API Reference | `/docs/api` | Sidebar | High |
+| Changelog | `/docs/changelog` | Sidebar (bottom) | Low |
+
+### Navigation
+
+**Header**: Docs | API | Blog | Community | GitHub | [Dashboard]
+
+**Sidebar** (persistent, left): Getting Started, Guides, API Reference, Examples, Changelog — with expandable subsections
+
+**On-page**: Previous/Next navigation at bottom of each doc page
+
+---
+
+## Hybrid SaaS + Content
+
+### Page Hierarchy
+
+```
+Homepage (/)
+├── Product (/product)
+│   ├── Feature A (/product/feature-a)
+│   ├── Feature B (/product/feature-b)
+│   └── Feature C (/product/feature-c)
+├── Solutions (/solutions)
+│   ├── By Use Case (/solutions/use-case-slug)
+│   └── By Industry (/solutions/industry-slug)
+├── Pricing (/pricing)
+├── Blog (/blog)
+│   ├── [Category] (/blog/category/slug)
+│   └── [Posts] (/blog/post-slug)
+├── Resources (/resources)
+│   ├── Guides (/resources/guides)
+│   ├── Templates (/resources/templates)
+│   ├── Webinars (/resources/webinars)
+│   └── Case Studies (/resources/case-studies)
+├── Docs (/docs)
+│   ├── Getting Started (/docs/getting-started)
+│   └── API (/docs/api)
+├── Integrations (/integrations)
+│   └── [Integration] (/integrations/slug)
+├── Compare (/compare)
+│   └── [Competitor] (/compare/competitor-slug)
+├── About (/about)
+│   ├── Careers (/about/careers)
+│   └── Contact (/contact)
+├── Privacy (/privacy)
+└── Terms (/terms)
+```
+
+### Navigation
+
+**Header (7 items + CTA)**: Product | Solutions | Pricing | Resources | Blog | Docs | Integrations | [Start Free Trial]
+
+Use mega menus for Product (features list), Solutions (use cases + industries), and Resources (blog, guides, templates, webinars, case studies).
+
+---
+
+## Small Business / Local
+
+### Page Hierarchy
+
+```
+Homepage (/)
+├── Services (/services)
+│   ├── Service A (/services/service-a)
+│   ├── Service B (/services/service-b)
+│   └── Service C (/services/service-c)
+├── About (/about)
+├── Testimonials (/testimonials)
+├── Blog (/blog)
+│   └── [Posts] (/blog/post-slug)
+├── Contact (/contact)
+├── Privacy (/privacy)
+└── Terms (/terms)
+```
+
+### URL Map
+
+| Page | URL | Nav Location | Priority |
+|------|-----|-------------|----------|
+| Homepage | `/` | Header (logo) | Critical |
+| Services | `/services` | Header | High |
+| Service pages | `/services/{slug}` | Header dropdown | High |
+| About | `/about` | Header | Medium |
+| Testimonials | `/testimonials` | Header | Medium |
+| Blog | `/blog` | Header | Medium |
+| Contact | `/contact` | Header (CTA) | High |
+
+### Navigation
+
+**Header (5 items + CTA)**: Services | About | Testimonials | Blog | [Contact Us]
+
+Keep it simple. Small business sites should be flat (1-2 levels max). Every page should be reachable from the header.

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

@@ -0,0 +1,74 @@
+# SEO
+
+- **IS:** one entry point for search visibility: evidence-led audits, implementation, demand research, writer briefs, and performance measurement across search engines and AI search (AEO for AI answers inside search, GEO for standalone assistants; see `references/answer-engines.md`).
+- **IS NOT:** writing the article or standalone marketing copy (`ghostwriter`), visual redesign (`ui-design`), tenant infrastructure (`multi-tenant-architecture`), or implementing AFDocs / Is Agentic / Is It Agent Ready scorecards (`agent-ready`). Fix SEO copy and markup when they are part of the requested implementation.
+
+## Route the task
+
+| Request | Load | Deliverable |
+|---|---|---|
+| Audit a site, diagnose indexing, review a migration | `references/audit.md` and `references/validation-evidence.md` | Prioritized findings with URLs, observed evidence, impact, and correction |
+| Fix or implement SEO | Audit references, then applicable implementation references below | Code changes, scoped checks, and served-page evidence for the changed behavior |
+| Research demand, choose a target, brief a page | `references/research-protocol.md`; `references/brief-template.md` for a brief | Sourced demand table and decision, or a durable writer brief |
+| Explain traffic movement, measure AI visibility, monitor SEO | `references/monitoring.md` | Property-scoped diagnosis or configured monitoring with explicit data gaps |
+
+For a combined request, reuse one property and URL inventory across modes. An audit request produces findings; a request to fix them proceeds through implementation and verification within the user's authorized scope. A research-only request does not require crawling every URL or changing code.
+
+## Establish the evidence boundary
+
+Identify the exact public host, URL-prefix or domain property, production environment, project/subpath, audience, and business outcome. On a shared domain, filter each project's path separately. In analytics, verify hostname, path, conversion event and attribution window before interpreting a number.
+
+Discover connected tools and existing project bindings first. Prefer the established reporting source, then an available equivalent, then a signed-in browser. No vendor is required. Ownership verification, API consent and a successful scoped query are separate states. An export for a neighboring property is not a fallback.
+
+Use `No data` with its reason for inaccessible, missing, unsupported or unmeasured metrics; distinguish these from a measured zero. Label historical exports by their actual dates. Do useful public checks while an authenticated metric is unavailable.
+
+## Working sequence
+
+For substantial mixed work, track only the applicable steps:
+
+- [ ] Confirm property, scope, baseline and intended outcome.
+- [ ] Inspect live evidence and map affected route patterns or research questions.
+- [ ] Prioritize blocking defects and high-value opportunities; separate observations from hypotheses.
+- [ ] Implement authorized corrections or deliver the requested research/brief.
+- [ ] Recheck the changed behavior, identify the tested environment, and report remaining gaps.
+
+Prioritize crawl/index defects before cosmetic metadata changes. Page titles, headings and content structure follow the page's purpose and reader intent. Descriptive non-brand terms help category discovery; brand-led portfolio and product pages can be appropriate. Neither a fixed title character count nor question-shaped headings are ranking requirements.
+
+For AI visibility, the owner builds crawl access, content and extractable structure; independent reviews, comparisons and coverage are earned, and they supply most of what answers say about a brand. Fix the owned layers first, then say where the remaining leverage sits instead of padding the site. Original evidence, useful comparisons and honest product limitations earn their place ahead of manufactured keyword permutations. Research likely reader questions; do not present invented query fan-outs as engine telemetry or create a page for every variation.
+
+## References
+
+| File | Read when |
+|---|---|
+| [references/audit.md](references/audit.md) | Crawling, diagnosing or prioritizing a site audit; canonicals, redirects, exclusions and programmatic pages; hreflang; CDN, response headers or preview environments affecting discovery |
+| [references/nextjs-implementation.md](references/nextjs-implementation.md) | Implementing App Router metadata, sitemaps, rendering, status codes, Markdown twins, or schema; verify APIs against the installed Next.js docs |
+| [references/answer-engines.md](references/answer-engines.md) | SEO, AEO and GEO terms, AI visibility, crawler policies, owned versus earned coverage, Markdown alternatives or `llms.txt` |
+| [references/validation-evidence.md](references/validation-evidence.md) | Verifying findings, a built page or a deployed correction |
+| [references/research-protocol.md](references/research-protocol.md) | Keyword/prompt metrics, opportunity selection and question maps |
+| [references/brief-template.md](references/brief-template.md) | Producing a writer brief |
+| [references/monitoring.md](references/monitoring.md) | Search/AI performance, attribution, anomalies or recurring work |
+| [references/sources.md](references/sources.md) | A claim depends on current engine behavior, supported reports, or vendor research |
+
+## Delivery
+
+Findings go in chat unless a file is requested. Writer briefs go to the requested project destination; retain prior dated briefs when producing a new revision. Keep scratch crawls and exports out of the repository. No em dashes in authored reports or briefs.
+
+Report what changed, why, exact verification evidence, and what remains unmeasured. A successful local build, ready deployment, public URL probe, Google index record and measured conversion are different evidence. Name the strongest state actually verified.
+
+Sending recaps to others, scheduling recurring work, spending on tools and production deployment follow the user's authorization and host rules. Reuse an existing matching monitor rather than creating another owner or schedule.
+
+## Gotchas
+
+- A sitemap can parse while listing `/studio` that intentionally returns 404. Check its URLs, not just XML validity.
+- A canvas gated on mounted state can leave the homepage and category hubs with only navigation in initial HTML. Inspect those hubs as well as deep pages; `use client` alone does not imply missing server-rendered content.
+- `lastModified: new Date()` or a build timestamp describes generation, not necessarily a significant page update. Use content dates or omit the field.
+- A canonical tag on each URL does not resolve two copies that both self-canonicalize. Compare content and choose the preferred URL.
+- Two consistent JSON-LD scripts are not an error. Verify entity identity, eligible properties and visible supporting content instead of script count.
+- DNS verification needs no invented meta token. Confirm scoped data access separately.
+- A crawler user-agent probe does not authenticate a bot IP or establish index inclusion. Treat CDN logs and engine inspection as separate evidence.
+- Prompt demand, measured citations, mentions, AI impressions and referral sessions are different quantities. Preserve engine, source, match type, scope and window.
+- One prompt run, or one score averaged across engines, is not a visibility measurement. Repeat each prompt, report per engine, and keep recall separate from citations.
+- Schema, `llms.txt` and fixed answer-block lengths are not measured citation levers. Keep them for their real consumers; do not sell them as AI visibility.
+- A vendor Search Console connector may under-report. Reconcile property, filters and aggregation against native Search Console before diagnosing a drop.
+
+Maintenance only: `evals/evals.json` holds behavioral scenarios and routing prompts. It is loaded when changing the skill, not during ordinary SEO work.

package/skills/optbrew/modules/mblode-seo/references/answer-engines.md

@@ -0,0 +1,58 @@
+# AI Search: AEO and GEO
+
+## Terms
+
+The labels are not standardized. Vendors use AEO, GEO, LLMO and "AI SEO" interchangeably, and Perplexity calls itself an answer engine. Map whatever term the user uses to a named list of engines before doing anything, and use these meanings in reports:
+
+| Term | Means here | Engines | Where visibility comes from | Native measurement |
+|---|---|---|---|---|
+| SEO | Search engine optimization. Crawl, index, rank and click in a search engine; in this skill, also the umbrella for every surface people search on | Google Search, Bing | The engine's own index | Search Console, Bing Webmaster Tools |
+| AEO | Answer engine optimization. Being the answer or a cited source in AI answers shown inside a search engine; older usage also covers featured snippets and voice answers | Google AI Overviews and AI Mode, Bing Copilot answers | The same search index as SEO, so SEO foundations carry over | Search Console generative AI report, Bing AI Performance |
+| GEO | Generative engine optimization. Being mentioned and cited when a standalone assistant writes an answer from retrieved sources. The term comes from Aggarwal et al., "GEO: Generative Engine Optimization", KDD 2024 (arXiv 2311.09735), tested on Perplexity | ChatGPT search, Claude, Perplexity, Gemini app | Each vendor's retrieval: its own crawler, a partner index (often Bing) or both; plus what the model recalls from training | None on the site side; repeated prompt panels or a visibility tool (`monitoring.md`) |
+
+"AI search" in this skill means AEO and GEO together. "Answer engine" means any engine that composes an answer rather than a list of links.
+
+They are not separate disciplines with separate tactics. Both rest on the same work as SEO: crawl access, indexable server-rendered text, extractable claims, consistent entity naming and earned third-party coverage. What differs per engine is the crawler to allow, the index it retrieves from, and the report that measures it. Do not sell AEO and GEO as two retainers, and do not report one blended "AI visibility" score across them.
+
+## Surfaces
+
+AI discovery has several surfaces: search retrieval, model training, user-triggered fetching and browser agents. Identify which one the request concerns before changing access or interpreting a metric. Training recall (what a model says without searching) is not retrieval and has no crawler or report to fix; measure it separately.
+
+## Access policy
+
+| Purpose | Examples | Decision |
+|---|---|---|
+| Search retrieval | OAI-SearchBot, Claude-SearchBot, PerplexityBot, Googlebot, Bingbot | Permit discovery where the owner wants search visibility; verify current vendor rules and published IP ranges |
+| User-triggered fetching | ChatGPT-User, Claude-User, Perplexity-User | May have different robots behavior; check current vendor documentation rather than assuming search-bot semantics |
+| Training | GPTBot, ClaudeBot, CCBot | Preserve the owner's training decision independently of search access |
+| Usage controls | Google-Extended, Applebot-Extended | Consult current vendor scope; these are not separate HTTP crawlers |
+
+OpenAI explicitly separates OAI-SearchBot search access from GPTBot training permission. Do not claim that allowing training earns citations or that blocking training removes ChatGPT search visibility. Avoid generalizing one vendor's controls to all engines.
+
+Inspect the served robots file and applicable group selection. A specifically named user-agent group can supersede wildcard rules, so carry forward intended private-path exclusions. Check origin, CDN/WAF challenges and published verified-bot rules separately. Spoofing a user-agent string tests a response path; it does not establish real crawler identity or successful bot access from vendor IPs.
+
+Google's AI search uses ordinary search foundations. Verify current Search Console inclusion settings and snippet controls against official documentation before advising an opt-out; do not hard-code a claim that one robots directive is the only control forever.
+
+## Content and distribution
+
+Make substantive text and links available in the served page. Summaries and question headings are useful when they help readers, not required AI markup. Answer real evaluator questions, show evidence and limitations, and keep public product facts consistent across the site and documentation.
+
+The on-page test is extraction: can a specific, quotable claim be lifted from the page without its context collapsing? A direct answer near the relevant heading usually passes; a word-count band or readability score is house style, not an engine requirement. Name products, plans and entities the same way everywhere and spell out an ambiguous acronym on first use, because inconsistent naming splits the entity. Original data benchmarked against a field is quotable; a lone proprietary figure is not.
+
+Prefer updating the existing page over publishing a new one on the same question. Change the visible and structured dates only when the substance changes; a maintained comparison or guide keeps earning citations, while a dated announcement drops out.
+
+## Owned and earned layers
+
+Split the work before prioritizing it. The owner can build crawl access, indexable content and extractable structure (readable). Independent coverage, named authors with a verifiable record, original evidence and a history of being right are conferred by others (citable). Most brand descriptions in AI answers come from third-party pages, predominantly reviews, comparisons and round-ups, so owned-site fixes are necessary and have a ceiling. Say so when an audit finds the owned layers healthy rather than inventing further on-page work.
+
+Diagnose the category before recommending distribution. Run the buyer's real questions in each relevant engine and classify the cited sources (owned page, review site, forum, publisher, marketplace, retailer, competitor). The mix differs by category and engine; the dominant source type decides whether the next move is an owned page, review velocity, publisher outreach or marketplace presence.
+
+Seek useful independent reviews, demonstrations, research and community contributions when they fit the audience. Do not prescribe fabricated mentions, seeded thin listicles, scaled AI-generated pages, or a quota of backlinks or videos. Correlation studies are dated hypotheses with selection criteria, not causal recipes or promised visibility gains. Identify engine, sample and outcome before applying a study to a small project, and discount research sold by the vendor of the recommended fix.
+
+## Optional machine-readable surfaces
+
+`llms.txt` and Markdown alternatives can help tools that use them. They are not Google ranking requirements or evidence of citations. Add them for a real consumer and keep them aligned with the visible source rather than duplicating a second content system. A Markdown twin carries the same words and facts as the HTML; content served only to bots is cloaking under Google's spam policies. Schema is likewise for rich-result eligibility and entity identity, not a citation lever. Mintlify Agent Score, AFDocs, and Is Agentic scorecards belong to `agent-ready`; this file is crawler policy, canonicals, and how Next.js should cache the twin.
+
+Prefer an explicit Markdown URL when content negotiation adds unnecessary cache complexity. If negotiation is required, honor Accept quality values, including `q=0`, preserve required Vary fields on both representations, and verify actual CDN behavior in both request orders. Next may replace Vary on framework-generated HTML; do not claim cache safety from a header set only on the Markdown response. Keep canonical and indexing policy intentional for alternate URLs.
+
+Measure native AI visibility and referral/conversion outcomes using `monitoring.md`. A successful fetch, an `llms.txt` file or an agent-friendly demo does not establish that an engine cited the site.

package/skills/optbrew/modules/mblode-seo/references/audit.md

@@ -0,0 +1,78 @@
+# Audit
+
+Start with the actual property and public host. Record the environment, URL sample and coverage so a sitemap crawl is not described as a complete index audit.
+
+## Triage
+
+| Area | Inspect | Avoid false positives |
+|---|---|---|
+| Discovery and access | robots groups, sitemap indexes and children, response statuses, CDN challenges, internal links | robots permission is not proof of successful crawling; footer links are crawlable, though contextual links improve discovery and meaning |
+| Index intent | meta/header noindex, canonical destination, duplicate bodies, redirects, missing paths | self-canonicals do not consolidate duplicates; sitemap inclusion is not index inclusion |
+| Rendering | initial HTML versus rendered DOM, main content, headings, anchors, mobile parity | `use client` can still prerender; a JavaScript-dependent page is not automatically absent from Google |
+| Metadata and entities | meaningful titles/descriptions, canonical, social images, JSON-LD consistency and eligibility | no fixed title length or one-script rule; valid JSON is not rich-result eligibility |
+| Experience | field LCP, INP, CLS where available; lab diagnostics and interactions | lab scores cannot substitute for missing field data; low word count alone is not a defect in a functional tool |
+| Content and demand | reader intent, original evidence, comparison accuracy, overlapping pages, conversion path | do not infer demand from a keyword in a title or invent product facts |
+| AI search (AEO, GEO) | crawler groups, retrieval snippet test, extractable claims, consistent entity naming, content freshness, third-party coverage of the category | owned-site readiness does not establish citations; `llms.txt`, schema and answer-block length are not citation requirements |
+| Measurement | native search reports, engine-specific AI reporting, qualified conversions | search impressions, prompt volume, citations and sessions are not interchangeable |
+
+## Crawl scope
+
+Follow sitemap indexes recursively, deduplicate URL entries and preserve which sitemap advertised each URL. Fetch listed destinations with bounded concurrency. Sample every route pattern, host/proxy boundary and locale; expand when a defect affects a pattern. Crawl navigational links as needed to find non-sitemap URLs and compare against the intended route inventory for orphans.
+
+Record requested and final URL, redirect chain, status, MIME type, robots directives, canonical, title, main content and structured-data parse results. Collect HTML metadata from HTML elements, not SVG `title` elements or escaped React payload strings. Inspect actual anchors for discovery, not only strings in JavaScript.
+
+Prioritize systemic exclusions, wrong canonicals and broken destinations before lower-impact duplication. Unknown paths should return genuine missing-page behavior. Check both initial HTML and the rendered page before attributing missing content to rendering.
+
+## Findings contract
+
+Each material finding names the affected URL/pattern, observation, evidence, impact, correction and verification method. Mark inference and missing evidence explicitly. Separate existing baseline failures from regressions introduced by the fix. A checked item can be pass, fail, not applicable or not measured, with the reason.
+
+Prioritization follows business impact, affected scope, confidence and correction cost. Avoid fake numerical precision, fixed finding quotas and reports padded with irrelevant checks. For a healthy site, say which checks passed and which performance questions remain unanswered.
+
+Separate verified defects, optional enhancements and unmeasured state. An owner requesting a crawler policy does not establish the current robots rules; inspect them before claiming they are missing or permissive. Recommend an optional annotation only when the observed site needs its behavior.
+
+## Indexing policy
+
+For changed route patterns, record index intent, preferred URL and reason. Expand to per-URL rows where exceptions matter.
+
+- Index useful public pages that satisfy distinct reader needs. A sitemap should advertise preferred, available URLs intended for search, including eligible non-HTML resources where appropriate.
+- For equivalent public URLs, select a canonical and align internal links and sitemaps. Redirect an obsolete copy when it no longer needs to remain accessible. Canonicals are signals, not guaranteed engine choices.
+- Keep locale equivalents self-canonical and connect them with hreflang instead of canonicalizing every language to English.
+- For previews, private utilities and deliberate exclusions, use appropriate access control and/or crawlable `noindex`. Robots blocking alone does not reliably remove a URL from results. Do not combine conflicting exclusion/consolidation signals as a default duplicate strategy.
+- Return 404 or 410 for permanently missing content, 503 for temporary unavailability, and a real server redirect for moved content. Do not funnel unrelated deleted pages to the homepage.
+- Do not list unavailable studio, login or app-shell routes merely because they exist in source. Share the availability decision with the sitemap generator.
+- `lastmod` reflects significant content, structured-data or link changes. Build/request time is not a substitute; omit an unknown date. Check current sitemap limits before partitioning large inventories.
+
+### Programmatic pages
+
+Validate demand, product fit and a distinct useful result before indexing a new pattern. Reuse, merge or improve an existing page when it already serves the intent. Original data, meaningful local differences, worked examples and genuine comparisons can justify separate pages; swapping a location or adjective alone does not.
+
+Define the indexability gate and lifecycle for empty results, out-of-stock resources and retired entities. Do not generate fan-out permutations primarily to manipulate search or AI answers. See the current spam policy in `sources.md` when a proposed pattern approaches scaled content abuse.
+
+## Internationalisation
+
+Use hreflang for equivalent language or regional pages, not unrelated content that happens to target different countries.
+
+- Use supported language codes with optional region codes and fully qualified URLs. A region by itself is invalid.
+- Include self-reference and reciprocal links among the variants being declared. Missing reciprocity affects those annotations; it does not necessarily invalidate every correctly reciprocal subset on the site.
+- Keep translated pages self-canonical unless they truly duplicate another preferred URL. Do not canonicalize all languages to the source-language page.
+- `x-default` is optional. Its absence alone is neither a defect nor a reason to add it. Recommend it when an actual selector or unmatched-locale destination needs declaring.
+- HTML, HTTP headers and XML sitemaps are equivalent implementation methods. Prefer one maintainable source; using more than one is allowed, but keep them consistent.
+- Translate meaningful titles, descriptions, headings, alt text and user-facing schema values. Preserve the identity of shared organizations and people.
+- Keep locale URLs independently accessible. Avoid mandatory IP/language redirects that prevent a reader or crawler from reaching another language.
+
+Validate representative reciprocal pairs and an unmatched-language visit. Record missing annotations and canonical conflicts precisely rather than reporting the whole set as broken. Check Google's current localized-version documentation in `sources.md` for supported codes and exceptions.
+
+## Delivery and access
+
+Load this when response handling interferes with discovery. Security/privacy work unrelated to the SEO defect belongs to the relevant project workflow.
+
+- Check both the public proxy host and origin where permitted. Correct source code can still serve an auth page, WAF challenge or cached error at the public URL.
+- Verify robots directives in HTML and HTTP headers, including CDN-added fields. Preview deployments on custom domains need an explicit indexing policy; do not assume the platform adds noindex on every hostname.
+- Use 503 plus an appropriate Retry-After for temporary unavailability. A long outage can still affect search visibility; the header does not guarantee retention.
+- Distinguish browser-enforced CSP/CORP/CORS restrictions from server-to-server fetches. Verify the failing consumer and actual resource response before weakening headers.
+- Check static files, redirects and generated metadata under the deployed basePath. Inspect image MIME type and actual content rather than trusting a 200 response.
+- For robots changes, verify group precedence and private-route exclusions. Do not disable the WAF globally to accommodate a crawler; use verified identity and the narrow affected rule.
+- Do not write real credentials, verification tokens or private analytics exports into public artifacts. Preserve existing ownership verification and request the required scoped access through the host's supported authentication flow.
+
+Legal consent and retention requirements vary by property and jurisdiction. Do not turn a generic SEO checklist into a blanket legal compliance assertion or change consent settings to improve measured conversions.

package/skills/optbrew/modules/mblode-seo/references/brief-template.md

@@ -0,0 +1,47 @@
+# Writer Brief
+
+Adapt this shape to the requested page. Keep the decisions and evidence; omit irrelevant sections rather than manufacturing content to fill them. This is a brief, not the article.
+
+A target keyword is not a product claim. Identify our product separately from the competitor named in the keyword. If our product is unnamed, use `<product>` rather than inventing a competitor edition or download. A brief for "Things 3 for Windows" can answer the platform question and evaluate our Windows-capable alternative; it must not claim that Things has a Windows version. Mark missing comparison facts for verification while completing the brief.
+
+```markdown
+# Brief: <reader's topic or decision>
+
+Date: <YYYY-MM-DD>
+
+## Why this page
+
+Audience and intent: <who and what they need>
+Decision: <create, update, consolidate or validate; why>
+Distinct value: <original evidence, useful comparison or experience>
+Gap evidence: <for create: who the current results and answers cite, and the two or three things they miss, with the date read; for update: the decay or ranking evidence>
+Existing coverage: <page to improve or overlap to avoid>
+Desired outcome: <reader action and measurable product outcome>
+
+## Search decisions
+
+Primary query: <intent-led, modifier only if useful>
+Secondary terms and evaluator questions: <relevant supporting demand>
+Title and H1 direction: <accurate page purpose; non-brand discovery terms where appropriate>
+Description: <specific value and accurate limits>
+Canonical: <preferred URL>
+
+<Research evidence table: metric, source, match definition, scope/engine, window, pull date; No data with reason for gaps.>
+
+## Editorial direction
+
+North star: <what the reader should understand or decide>
+Ideas to land: <only the substantive ideas needed>
+Proof and limitations: <what the writer must demonstrate and qualify>
+Questions worth answering: <natural questions with their source (support, forum, review, Search Console query); note existing coverage>
+
+## Sources and validation
+
+Public sources: <URLs the writer can actually cite>
+Facts to verify: <product behavior, comparisons, dates, research limitations>
+Success measurement: <outcome, baseline/window or No data, next check>
+```
+
+Use public product pages, docs and original research for citeable claims. Do not transfer private feature dumps, roadmap promises or internal wiki links into public copy. No invented statistics, quotes or functionality. Leave narrative order and section breaks to the writer unless the user requests an outline.
+
+Save a requested brief at the project/user destination. For a new dated revision, preserve the earlier brief and explain what changed; follow an explicit request to edit an existing document in place.

package/skills/optbrew/modules/mblode-seo/references/monitoring.md

@@ -0,0 +1,56 @@
+# Measurement and Monitoring
+
+Bind each metric to the actual property, hostname and project path. Verify native report access, analytics filters and conversion-event meaning before interpreting a trend.
+
+## Separate the measurements
+
+| Question | Evidence | Limit |
+|---|---|---|
+| Are pages indexed and receiving search traffic? | Native Google/Bing indexing and performance reports | Ownership verification or sitemap submission alone proves neither |
+| Is the site visible in Google's generative AI features? | Search Console generative AI performance, including available impression/page/country/device/date dimensions | Verify current report access and supported dimensions; do not invent AI-specific clicks or CTR from impression-only data. Read it as presence, not position: an AI answer is not a ranked list, so average position and CTR there do not mean what they mean for links |
+| Is Bing/Copilot citing it? | Bing Webmaster AI Performance, available citations, cited pages and grounding-query/topic dimensions | Needs Bing Webmaster verification first, otherwise `No data`; availability and sampling vary; citation counts are not ranking positions or referral visits |
+| Is a tracked prompt producing mentions/citations? | Repeated, documented engine-specific prompt panel or connected visibility tool | Preserve prompts, engine/model, search mode, locale, date, repetitions, sample size and citation URL; a panel is not population-wide demand. Report a rate per engine, never one blended score or a ranking position |
+| How often do people ask the topic? | Vendor Exact prompt demand metric | Demand is not the site's share of visibility |
+| Is AI influence arriving without a referral? | Branded search impressions, direct sessions in the campaign window, and a self-reported "how did you hear" answer | Leading indicators, not proof of AI attribution; keep each as its own series |
+| Does discovery produce useful outcomes? | Analytics landing sessions, qualified visits, signups, activation or revenue | Preserve attribution definitions and windows; missing/referrer-stripped visits prevent complete AI attribution |
+| Do the agent-readable surfaces answer? | Scanner scorecards and `agent-ready`'s `check-surfaces.sh` output | Says whether `llms.txt`, markdown twins and headers work, not whether any engine cites them; agent readership itself needs server logs, and without a log drain it is `No data` |
+
+Inspect current native capabilities using `sources.md`, not a frozen vendor checklist. Google generative AI reports may expose different dimensions for Search and Discover. Where a connector omits a native report, use an available browser/export or report that gap rather than silently substituting overall search data.
+
+## Prompt panels
+
+A single prompt run is a sample of one: answers and cited sources change between identical runs and from week to week. Treat each prompt as a survey question.
+
+- Run each prompt several times (three to five) in clean sessions and report mention and citation rates with the run count, not a point estimate.
+- Keep each engine, and Google AI Overviews versus AI Mode, on its own line; engines retrieve from different indexes and cite different source types.
+- Use real buyer questions with the persona and use case, plus at least one follow-up turn where alternatives or price are asked.
+- Store the raw answer with cited URLs, engine, model, mode, locale, timestamp and collection method. Never mix collection methods (API, SERP provider, browser) in one trend line, and never infer a citation without a URL.
+- Classify cited sources by type (see `answer-engines.md`) and record the attributes the answer associates with the brand; those are what content can change.
+- Record recall without retrieval separately from citations. They measure different things and are never summed.
+
+Third-party rank and AI-visibility tools that scrape results can lose collection without notice. Check the vendor's collection status before trending its data, and prefer native reports.
+
+## Diagnose a change
+
+Use complete, comparable windows with matching filters, data freshness and aggregation. Check reporting lag, weekdays/seasonality, campaigns, releases, migrations and tracking changes before attributing movement to ranking. Segment by brand/non-brand, page group, country, device and search appearance where supported and relevant. Do not average positions across incompatible populations.
+
+Report absolute counts alongside percentage changes. Moving from 5 clicks to 4 is a one-click change, not sufficient evidence of a material incident by itself. Set alert thresholds from baseline volume, normal variance, persistence and business impact; no universal 20% threshold. For sparse data, extend the observation window or report uncertainty rather than inventing significance.
+
+Distinguish loss of visibility, lower click-through, fewer sessions and weaker activation. Verify conversion instrumentation before concluding that SEO traffic quality changed. If authentic scope or outcome data is absent, mark it `No data` and name the smallest next check.
+
+## Decay and refresh queue
+
+Refreshing a page that already ranks usually moves faster than publishing a new one, so review a page-level decay list on the same comparable windows before choosing new work. For each page, compare clicks, impressions, average position and CTR across two complete windows of equal length, and list the pages that lost clicks with the absolute counts beside the change.
+
+Set the entry bar from the property's own volume: a minimum impression count for the current window, and triggers the project has written down (a traffic fall, a position loss, a CTR fall at a steady position, or a material product or source change). Where the project has no written triggers, derive them from normal variance and say so. Before opening a refresh, rule out a redirect or slug change inside either window, a launch, seasonality and brand-query movement. Refresh the stale answer, source, screenshot or step; do not restamp the date for a cosmetic edit.
+
+## Recurring checks
+
+Use an existing matching owner/schedule when recurring work is authorized. A proposed cadence is not a configured monitor. Preserve the configured destination and notification preferences; do not send an unapproved recap elsewhere.
+
+- Anomaly checks report new, material changes supported by the baseline, plus actionable access or delivery failures.
+- Digests summarize completed comparable periods, leading page/query movements, engine-specific AI visibility, conversion outcomes and the next decision.
+- Deduplicate previously reported incidents. An unchanged refresh does not need another notification.
+- Repeated authentication failures should be surfaced through the host's supported reauthentication flow rather than retried indefinitely.
+
+Keep monitoring reads separate from mutations. Store durable reports and alert state in the mapped project system, not inside the installed skill folder.