optbrew 0.0.0-stage → 0.1.1

package/skills/optbrew/modules/seranking-seo/skills/seo-content-audit/references/core-eeat.md

@@ -0,0 +1,147 @@
+# E-E-A-T scoring rubric (60 items)
+
+> **Sept-2025 QRG generalisation.** Updated for the September 2025 Quality Rater Guidelines and December 2025 core update — E-E-A-T applies broadly, not only to YMYL topics. The dimension definitions below, the 4 vetoes, and the AI-content-markers checklist are framed as defaults across all topics; the YMYL-specific calibrations are called out where they differ.
+
+15 items per dimension × 4 dimensions = 60 total. Score each: ✓ (full credit), ~ (partial), ✗ (fail). Dimension score = ✓ ÷ 15 × 100%. E-E-A-T composite = average of dimension scores.
+
+## Veto items (any one triggers automatic NO PUBLISH)
+
+1. **Anonymous authorship on a YMYL topic** (Your Money or Your Life: medical, financial, legal, safety). Author bylines required for these.
+2. **Factual claims with no sources cited.** A piece that asserts statistics, study findings, or expert positions without inline citations.
+3. **Undisclosed affiliate / sponsored relationships.** Required by FTC and Google's Helpful Content guidelines.
+4. **AI-generated YMYL content with no human-review markers.** Trips when ≥4 of the 8 AI-content markers below are present *and* the topic is YMYL *and* the page lacks all of: a named human editor byline, a "reviewed by" credit, a "last reviewed" or "fact-checked on" date. AI assistance is fine; AI assistance on health/finance/legal/safety with no human accountability surface is not.
+
+---
+
+## 1. Experience (15 items)
+
+First-hand engagement with the topic. Did the author actually do this?
+
+1. The author has personally used / tested / experienced the product / service / process being discussed.
+2. The piece includes original photos, screenshots, or video the author captured.
+3. Original data the author collected (survey, A/B test, log analysis) is presented.
+4. Specific, verifiable details only an experienced practitioner would know (numbers, edge cases, quirks).
+5. Process documentation (step-by-step accounts) reflects real execution, not hypothetical steps. (see Word-count floors by page type — automatic ✗ if materially below floor without explicit auditor justification)
+6. Comparative observations across multiple instances (e.g., "across 12 client engagements, 8 saw…").
+7. The piece acknowledges trade-offs and failure modes the author encountered.
+8. Specific dates, locations, or contexts ground the experience claims.
+9. Hands-on demonstrations (live code, working artifacts, before/after evidence).
+10. Customer / user / patient quotes attributed to a real source (with permission).
+11. Time-based observations (e.g., "after 6 months of using X, the result was…").
+12. Process improvements or tweaks the author made along the way.
+13. Tools / specific configurations / version numbers mentioned (signals real use).
+14. Pricing / cost specifics from real engagements (not a price list).
+15. Failures or rejected approaches described, not just successes.
+
+## 2. Expertise (15 items)
+
+Author's qualifications and depth on the topic.
+
+1. Author byline visible with full name, not "Admin" or pseudonym.
+2. Author bio includes credentials relevant to the topic (degree, certification, professional title).
+3. Author bio includes years of experience in the topic domain.
+4. Author has a linkable profile (LinkedIn, professional homepage, ORCID for academic).
+5. Author publishes consistently in this topic area (link to other articles).
+6. Citations to authoritative primary sources (peer-reviewed papers, government data, original research).
+7. Industry-specific terminology used correctly and consistently.
+8. Counter-arguments addressed and engaged, not strawmanned.
+9. Methodology section if the piece presents data or analysis. (see Word-count floors by page type — automatic ✗ if materially below floor without explicit auditor justification)
+10. Disclosure of limitations of the analysis or recommendations.
+11. Up-to-date with current developments in the field (recent references, current best practices).
+12. Distinguishes correlation from causation when discussing data.
+13. Avoids absolute claims where the field is genuinely contested.
+14. Editorial review credit (e.g., "reviewed by Dr. X").
+15. Author responds to comments / corrections (signals ongoing engagement).
+
+## 3. Authoritativeness (15 items)
+
+Reputation of the author and publishing entity in the topic domain.
+
+1. The publisher has an "About" page describing its mission, history, team.
+2. Editorial guidelines / standards page is publicly available.
+3. The publisher is referenced or cited by other authoritative sources in the same field.
+4. Wikipedia or industry-association mentions of the publisher (a strong signal).
+5. The author has spoken at industry events, been quoted in trade press, or published in authoritative venues.
+6. Awards or recognitions from peer institutions (with verifiable links).
+7. The publisher's contact information is real and discoverable (physical address, named team).
+8. Domain age and consistency (publishing in this topic for years, not weeks).
+9. Other articles by this author cluster around the same topic (topical authority).
+10. Internal links from cornerstone content on this site point to this piece (it's part of a hub).
+11. External backlinks to this piece from authoritative sites (assess via `seo-backlink-gap` or `seo-backlinks-profile`).
+12. The publisher is a recognised authority for its topic per industry consensus (not just self-description).
+13. Press release / news coverage of the publisher's research or position on this topic.
+14. Citations from peer publications to the publisher's previous work.
+15. Inclusion in expert lists, "best of" roundups, awards lists by external bodies.
+
+## 4. Trustworthiness (15 items)
+
+Signals that the page and publisher are honest, accurate, and accountable.
+
+1. HTTPS, valid certificate, no mixed-content issues.
+2. Privacy policy and terms of service accessible from the page footer.
+3. The publisher's name, registered business address, and contact route published.
+4. Last-updated date visible and recent (within freshness window for the topic).
+5. Original publish date visible.
+6. Editorial standards / fact-check policy linked.
+7. Corrections / updates log (visible if substantive corrections were made).
+8. Comment moderation visible (no spam, signs of engagement).
+9. Affiliate / sponsored / paid-content disclosures clear and prominent (if applicable).
+10. Author bio prevents impersonation (recognisable photo, social proof links).
+11. Schema.org `Article` (or sub-type) with `author` (Person), `publisher` (Organization), `datePublished` valid.
+12. Site-wide trust signals: customer reviews, testimonials linked to real names/orgs.
+13. The piece doesn't contain known misinformation about the topic (cross-check with authoritative sources).
+14. Sources cited are themselves trustworthy (not Wikipedia → Wikipedia → Wikipedia chains).
+15. Pricing, claims, and guarantees are clearly stated and not buried.
+
+---
+
+## AI-content markers (8 items — feeds veto #4)
+
+A 2025-09 Search Quality Rater Guidelines update made "low-effort AI-generated content" an explicit demotion signal. These markers don't ban AI use — they identify pieces where AI was clearly the *only* hand on the page. Score each marker as **fired** or **not-fired** during the audit (record the decision and the evidence in `03-eeat-scoring.md`); count how many fire and combine with the YMYL + human-review-credit check in veto #4.
+
+1. **Generic LLM phrasing without specificity.** Multiple instances of formulaic transitions and filler. Examples: "in today's world", "it's important to note that", "let's dive in", "navigating the landscape of", "in conclusion", "when it comes to", "at the end of the day". Detection: keyword-search the body for the phrase set; **three or more matches = fired**.
+2. **Repetitive structural template across the site.** Five or more recently published pieces on the same domain share the identical H2 → H2 → H2 → H2 → FAQ structure with similar word counts and identical section labels (e.g., every post has "What is X?", "Benefits of X", "How to use X", "FAQ"). Smells like a single prompt template. Detection: spot-check 5 sibling posts via `WebFetch` or `seo-firecrawl` site map; **identical skeleton on ≥4 of 5 = fired**.
+3. **No original insight or first-hand evidence.** Every claim paraphrases something already on the SERP top-10; no original photo, no proprietary data, no specific anecdote. A 0/15 or 1/15 score on the Experience dimension is a strong corroborator. Detection: pick 3 non-trivial claims and check whether each appears (often verbatim or near-verbatim) in the SERP top-10 for the target keyword; **3/3 paraphrased without attribution = fired**.
+4. **Em-dash density + bolded-phrase peppering.** Heavy use of em-dashes mid-sentence + every 2–3 paragraphs has a bolded summary phrase. Common output of GPT-4-class models. Detection: count em-dashes per 1,000 words; **>15 em-dashes per 1,000 words combined with bolded-phrase pattern in ≥30% of paragraphs = fired**.
+5. **Hallucinated or unverifiable citations.** Inline citations exist but the linked source doesn't contain the cited claim, or the URL 404s, or the cited "study" can't be located via Google Scholar / publisher's site. Detection: spot-check 3 random inline citations; **≥1 of 3 fails verification = fired**.
+6. **AI-shaped author byline.** Byline reads "Editorial Team", "Staff Writer", "{SiteName} Team" with no linked profile; OR the byline links to a profile page with no other articles, no LinkedIn, no real-world footprint. Detection: click the byline; check for a real bio with linked social or LinkedIn profile; **generic-team byline OR ghost profile = fired**.
+7. **No "reviewed by" or "fact-checked on" credit.** Especially for YMYL topics, absence of any human-accountability surface is itself a signal — combined with markers 1–6, suggests AI-only authorship. Detection: search the page for "reviewed by", "fact-checked", "medically reviewed", "edited by", "last reviewed"; **none found = fired**.
+8. **Suspiciously round publishing cadence.** Same site shipped 20+ pieces on different topics in a week with no obvious editorial arc, or a brand-new domain published 50+ articles in its first month. Use `site:domain.com` search or `seo-content-brief`-style topic clustering on the domain to corroborate. Detection: list the most recent 30 published-date timestamps on the domain; **≥20 articles within a 7-day span across unrelated topics = fired**.
+
+**Counting rule:** mark each marker as fired (1) or not-fired (0); record the evidence inline. **≥4 fired = AI-content suspected.** Combine with veto #4's YMYL + missing-human-review check before triggering the veto.
+
+---
+
+## Word-count floors by page type
+
+Detect the page type from URL pattern, H1 phrasing, and JSON-LD `@type`, then apply the floor below.
+
+| Page type | Floor | Rationale |
+|---|---|---|
+| Ultimate guide / pillar | 2,500 | Comprehensive coverage of a topic |
+| How-to | 1,200 | Step-by-step depth |
+| Listicle / best-of | 1,500 | Per-item description depth |
+| Comparison (X vs Y) | 1,800 | Feature matrix + verdict + rationale |
+| Explainer | 1,200 | Concept depth + examples |
+| Review (single product) | 1,500 | Pros / cons / verdict + evidence |
+| Landing page (commercial) | 600 | Conversion-led, less depth-driven |
+
+These are floors, not targets. A 1,000-word how-to that's deeply original outperforms a 2,000-word how-to padded with generic intro/conclusion. Use the floors as a thin-content tripwire — anything materially below the floor for its page type fails the "depth" E-E-A-T item by default unless the auditor explicitly justifies the exception.
+
+---
+
+## How to score
+
+For each item, mark ✓ (1), ~ (0.5), or ✗ (0). Dimension score = sum / 15 × 100%. E-E-A-T composite = average of 4 dimensions.
+
+## Threshold
+
+- E-E-A-T composite ≥ 75% AND no veto = pass.
+- 60–74% = "publish with fixes" (top 5 fixes from lowest-scoring items).
+- < 60% OR any veto = no publish.
+
+## Calibration tips
+
+- For YMYL topics, raise the bar: composite ≥ 85%, individual dimensions ≥ 75%.
+- For purely informational content (e.g., a how-to on a hobby), Authoritativeness can be slightly lower if Experience and Expertise are strong.
+- For brand / product content, Buyer-relevant Trust items dominate (transparent pricing, clear claims, social proof).

package/skills/optbrew/modules/seranking-seo/skills/seo-content-audit/templates/verdict.md

@@ -0,0 +1,63 @@
+# Content Audit: {URL or title}
+
+> Audited {YYYY-MM-DD} · Target keyword: "{keyword}" · Country: {country}
+
+## Verdict: {PUBLISH | PUBLISH WITH FIXES | NO PUBLISH}
+
+{One sentence summary of why}
+
+## Scores
+
+| Dimension | Score | Threshold | Status |
+|---|---|---|---|
+| Experience | {n}% | 75% | {✓/✗} |
+| Expertise | {n}% | 75% | {✓/✗} |
+| Authoritativeness | {n}% | 75% | {✓/✗} |
+| Trustworthiness | {n}% | 75% | {✓/✗} |
+| **E-E-A-T composite** | {n}% | 75% | {✓/✗} |
+| Clear answer | {n}% | 70% | {✓/✗} |
+| Include stats | {n}% | 70% | {✓/✗} |
+| Timestamp | {n}% | 70% | {✓/✗} |
+| Entity authority | {n}% | 70% | {✓/✗} |
+| **CITE composite** | {n}% | 70% | {✓/✗} |
+
+## Veto checks
+
+- Anonymous authorship on YMYL topic: {triggered / not triggered}
+- Factual claims without sources: {triggered / not triggered}
+- Undisclosed affiliate/sponsored relationships: {triggered / not triggered}
+- AI-generated YMYL with no human review: {triggered / not triggered} ({n}/8 AI-content markers fired)
+- Answer in first 300 words: {present / missing}
+- Datestamp on time-sensitive content: {present / missing}
+- Entity disambiguation for proper nouns: {present / missing}
+
+## AI Search readiness
+
+- AIO present for "{keyword}": {yes/no}
+- Top citation patterns observed: {bullet list of patterns}
+- Candidate URL cited in any sampled AIO: {yes/no}
+- Specific gaps vs cited sources:
+  - {gap 1}
+  - {gap 2}
+  - {gap 3}
+
+## Top 5 fixes (impact-ranked)
+
+1. {Specific fix linked to a low-scored item or veto}
+2. {Specific fix}
+3. {Specific fix}
+4. {Specific fix}
+5. {Specific fix}
+
+## Detailed scoring
+
+See:
+- `03-eeat-scoring.md` — item-by-item E-E-A-T (60 items)
+- `04-cite-scoring.md` — item-by-item CITE (30 items)
+- `05-aio-winner-comparison.md` — gap analysis vs cited sources
+
+## Recommended next step
+
+- If PUBLISH: ship; capture a `seo-drift` baseline so you can track post-publish performance.
+- If PUBLISH WITH FIXES: hand the top-5 fix list to the writer; re-audit after fixes.
+- If NO PUBLISH: rework the piece against the failing dimensions; re-audit before re-considering publication.

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

@@ -0,0 +1,141 @@
+> Example output: examples/seo-firecrawl-stripe-com-20260514/scrape/FIRECRAWL.md (upstream-only reference; route through optbrew)
+
+# Firecrawl Orchestrator
+
+A direct interface to Firecrawl MCP for tasks that fall outside the data-driven SE Ranking skills. Use when:
+
+- You need raw HTML, `<head>` metadata, JSON-LD, or post-JS DOM that WebFetch's markdown conversion strips.
+- You need a list of all URLs on a domain without pulling each one.
+- You need to crawl a site and audit each page's metadata.
+- You need to search within a known domain.
+- A higher-level skill (`seo-page`, `seo-schema`, `seo-content-audit`, etc.) called you as a sub-step.
+
+## Prerequisites
+
+- **Required:** the `firecrawl-mcp` MCP server. If `mcp__firecrawl-mcp__firecrawl_scrape` is unavailable, abort with the install command — `optbrew capability setup (see top-level routing)` from this plugin repo, plus the firecrawl.dev signup URL (free tier 500 credits/month). Don't attempt fallbacks; this skill exists for the cases WebFetch can't cover.
+- User provides: a target URL or domain, plus optionally a mode (`scrape` / `map` / `crawl` / `search`). If mode unspecified, infer from input shape (single URL → `scrape`, single domain → `map`).
+
+## Process
+
+1. **Preflight.** Confirm `firecrawl-mcp` is connected. If not, surface the install command and stop.
+2. **Mode selection.** Resolve user intent into one of:
+   - `scrape` — single URL, full data (default if user supplies one URL).
+   - `map` — single domain, list of URLs only (cheap reconnaissance).
+   - `crawl` — single domain, fetch each discovered page (expensive; require explicit confirm).
+   - `search` — query within a domain.
+3. **Cost estimation + confirmation.**
+   - `scrape` (1 credit), `map` (~0.5 credit per discovered URL — estimate using a `map` first if scope unclear), `crawl` (1 credit per page crawled), `search` (1 credit per result returned).
+   - For `crawl` and for `map` of >50 expected URLs, surface the estimate and require explicit go-ahead before calling.
+   - Always read remaining credits implicitly via Firecrawl's response metadata (`creditsUsed` / `creditsRemaining` in `metadata`).
+4. **Execute.** Call the matching `mcp__firecrawl-mcp__firecrawl_*` tool.
+   - `scrape`: pass `formats: ["markdown", "html"]` by default (markdown for prose, html for `<head>` + JSON-LD). Add `formats: ["screenshot"]` only if the deliverable visibly uses one. SPAs: pass `waitFor: 2000` (or a CSS selector) so the JS-rendered DOM is captured. Default `onlyMainContent: true` to drop nav/footer noise — override only on explicit request.
+   - `map`: default `limit: 500` (hard cap). Pass `excludePaths: ["/admin/*", "/api/*", "/wp-admin/*", "/feed/*"]` as a sane default.
+   - `crawl`: default `limit: 50` (default cap), hard cap `limit: 200`. Always pass `excludePaths` to prune. Poll `firecrawl_check_crawl_status` if the job returns asynchronously.
+   - `search`: default `limit: 20`.
+5. **Parse + structure output.** Don't dump the raw API response. Per-mode:
+   - `scrape` → `RAW.md` (markdown body), `META.md` (og / twitter / canonical / robots / headers + parsed JSON-LD `@type` list with hashes), `links.csv`, optional `screenshot.png`.
+   - `map` → `URLS.md` with pattern-grouped list (e.g., `/blog/* — 128 (37%)`, `/products/* — 84 (24%)`), plus `urls.csv`.
+   - `crawl` → folder per page under `pages/{slugified-url}/` with `RAW.md` + `META.md`, plus a top-level `INDEX.md` summarising every page (URL, status, key signals).
+   - `search` → `MATCHES.md` with hit excerpts + URLs ranked by relevance.
+6. **Synthesise** `FIRECRAWL.md` at the root: target, mode, credits used, key findings (5 bullets max), open loops, recommended next skill.
+
+## Output format
+
+Folder `seo-firecrawl-{slug}-{YYYYMMDD}/`:
+
+### Mode = scrape
+```
+seo-firecrawl-{slug}-{YYYYMMDD}/
+├── RAW.md            (markdown body)
+├── META.md           (og / twitter / canonical / robots / headers + parsed JSON-LD)
+├── links.csv         (every <a href> on the page)
+├── screenshot.png    (optional; only if requested)
+└── FIRECRAWL.md      (synthesis + handoff payload)
+```
+
+### Mode = map
+```
+seo-firecrawl-{slug}-{YYYYMMDD}/
+├── URLS.md           (pattern-grouped URL list)
+├── urls.csv          (every URL with discovery depth, if available)
+└── FIRECRAWL.md
+```
+
+### Mode = crawl
+```
+seo-firecrawl-{slug}-{YYYYMMDD}/
+├── INDEX.md          (every page + status code + key signals)
+├── pages/
+│   ├── {slug-1}/RAW.md
+│   ├── {slug-1}/META.md
+│   ├── {slug-2}/RAW.md
+│   └── ...
+└── FIRECRAWL.md
+```
+
+### Mode = search
+```
+seo-firecrawl-{slug}-{YYYYMMDD}/
+├── MATCHES.md        (hit excerpts + URLs ranked by relevance)
+└── FIRECRAWL.md
+```
+
+`FIRECRAWL.md` follows this shape:
+
+```markdown
+# Firecrawl: {target}
+
+> Run dated {YYYY-MM-DD} · Mode: {scrape | map | crawl | search} · Credits used: {n}
+
+## Summary
+
+{One-paragraph what-came-back. Example: "Scraped https://example.com/article. og:title and og:image present, JSON-LD Article schema with author + datePublished. 12 outbound links. Page is server-rendered (no JS-render divergence). Robots: index,follow."}
+
+## Key findings
+
+1. {Finding anchored in concrete data}
+2. ...
+5. ...
+
+## Open loops
+
+- {What this run did NOT answer}
+- ...
+
+## Recommended next step
+
+{One of: `seo-page` (when a single URL was scraped and now wants performance analysis) | `seo-schema` (when JSON-LD audit needs follow-up generation) | `seo-technical-audit` (when crawl revealed broken pages) | `seo-content-audit` (when crawl produced a corpus to audit) | `seo-drift baseline` (when the user wants to track this URL over time) | "this completes the user's ask".}
+
+## Handoff payload
+
+- **Produced by:** seo-firecrawl
+- **Target:** {url or domain}
+- **Mode:** {scrape | map | crawl | search}
+- **Credits used:** {n}
+- **Key findings:** {5 bullets — e.g., "twitter:card present (summary_large_image)", "JSON-LD types: Article + Organization + BreadcrumbList", "robots: index,follow", "canonical self-referencing", "404s: 0 of 50 pages crawled"}
+- **Open loops:** {what this didn't answer}
+- **Recommended next skill:** {seo-page | seo-schema | seo-technical-audit | seo-content-audit | …} — {one-line why}
+```
+
+## Tips
+
+- **Free tier 500 cr/month.** `map` is 0.5 cr/URL; `scrape` is 1 cr each; `crawl` 1 cr/page. Surface cost up front; warn when a single run will eat >100 credits.
+- **Default `onlyMainContent: true`** for `scrape` to drop nav/footer noise. Override only if the user explicitly asks for full-page DOM.
+- **Use `waitFor`** (CSS selector or ms) for SPAs that lazy-load content. 2000ms is a sensible default; selectors are more reliable than time waits.
+- **`firecrawl_map` before `firecrawl_crawl`** when crawl scope is unclear — discover first, decide what to crawl, then crawl. Saves credits.
+- **`includePaths` / `excludePaths`** dramatically cut crawl cost. Always pass `excludePaths: ["/admin/*", "/api/*", "/wp-admin/*", "/feed/*"]` as a default.
+- **Don't request `formats: ["screenshot"]`** unless the deliverable visibly uses it. It doubles per-page cost.
+- **Don't use `firecrawl_extract` or `firecrawl_deep_research`.** Both overlap with our own LLM analysis; `firecrawl_extract` has opaque pricing on the free tier; both are explicitly out of scope for `seo-skills`.
+- **Cloudflare / anti-bot:** some sites (especially e-commerce, banking) block Firecrawl's scraper. Surface the error cleanly; defeating WAFs is not a goal of this skill.
+- **Sub-step usage.** When invoked from another skill (`seo-page`, `seo-schema`, etc.), drop the `FIRECRAWL.md` synthesis — the caller wants the raw `META.md` / `RAW.md`. Skip mode-2's `URLS.md` summary too if the caller wants the raw `urls.csv`.
+- **This is the entry point** when you need raw HTML and don't have a more specific skill in mind. If you do — `seo-page` for keyword/traffic verdicts on one URL, `seo-schema` for JSON-LD work, `seo-technical-audit` for crawl-wide issues — use those instead. They orchestrate Firecrawl plus SE Ranking data automatically.
+
+## Works well with
+
+- **Predecessors:** none (entry point) or invoked as a sub-step from another skill.
+- **Successors:**
+  - `seo-page` — when a single URL was scraped and now wants keyword/traffic verdicts.
+  - `seo-schema` — when JSON-LD audit produced gaps that need generation.
+  - `seo-technical-audit` — when a crawl revealed broken pages or noindex issues at scale.
+  - `seo-content-audit` — when a crawl produced a corpus to E-E-A-T-audit.
+  - `seo-drift baseline` — when the user wants to track this URL or domain over time.

package/skills/optbrew/modules/seranking-seo/skills/seo-firecrawl/references/preflight.md

@@ -0,0 +1,73 @@
+# Shared preflight contract for analysis skills
+
+> Shared preflight contract for analysis skills. v2.7.1+. Mirror this pattern; don't reimplement.
+
+Every analysis skill in this catalogue runs the same 3-stage preflight at the start of its Process section. This file is the single source of truth — skills should reference it from their step 1 (or Prerequisites) rather than inlining the full prose.
+
+The pattern was duplicated 6+ times across GUIDE.md files until v2.7.0; centralised in v2.7.1 so a doc fix lands in one place.
+
+## The 3-stage preflight
+
+### Stage A — SE Ranking credit balance (`DATA_getCreditBalance`)
+
+Call `DATA_getCreditBalance` before running anything that costs SE Ranking credits. Surface the result and the per-skill estimate to the user before continuing, in this canonical shape:
+
+```
+Remaining: {n} credits. Estimated cost: ~{n} credits. Continue? (y/N)
+```
+
+The estimate is skill-specific — each skill cites its own figure in its step 1 reference (see "How to reference this from a skill" below).
+
+If the remaining balance is below the estimate, surface the shortfall and stop — don't run a partial pass.
+
+### Stage B — Firecrawl availability (`mcp__firecrawl-mcp__firecrawl_scrape`)
+
+Check whether `mcp__firecrawl-mcp__firecrawl_scrape` is connected. The branch is the same in every skill that uses Firecrawl:
+
+- **If available → enriched path.** Run the Firecrawl-using steps as documented in the skill. Surface the projected Firecrawl cost (typically 1 credit per URL scraped, varies by mode — see `seo-firecrawl/GUIDE.md` § "Cost estimation").
+- **If unavailable → degraded path.** The skill still runs on WebFetch + SE Ranking data. The Firecrawl-only deliverable lines emit `(skipped — Firecrawl not installed)` notes; skill-specific caveats (lower-confidence schema detection, missing canonical/robots/og:* recovery, etc.) are documented in the skill's own step descriptions.
+- **`--no-firecrawl` flag.** User may pass `--no-firecrawl` to force the degraded path even when Firecrawl is available — useful for credit conservation.
+
+When unavailable, also surface the install hint: `optbrew capability setup (see top-level routing)` (free tier 500 credits/month — see `seo-firecrawl/GUIDE.md`).
+
+### Stage C — Google APIs (`upstream script excluded; use optbrew capability routing`)
+
+Run `upstream script excluded; use optbrew capability routing` and parse the result.
+
+- **If `tier >= 0`** (any creds present): the skill branches into the per-tier enrichment recipes documented in `skills/seo-google/references/cross-skill-integration.md`. Each enrichment-aware skill has its own section there listing which tier unlocks which step.
+- **If `tier == -1`** or the file is missing: the skill proceeds without Google enrichment and notes `Google enrichment: not configured (run `optbrew capability setup (see top-level routing)`)` in the deliverable.
+
+This stage **defers entirely** to `skills/seo-google/references/cross-skill-integration.md` for per-tier branches, failure handling, and the per-skill enrichment recipes — don't duplicate that contract here.
+
+## Failure-mode table
+
+Mirror the cross-skill-integration table for the Google stage; the Firecrawl + credit-balance rows are this skill's own additions.
+
+| Failure | Detection | Skill response |
+|---|---|---|
+| Credit balance call fails | `DATA_getCreditBalance` returns error or non-200 | Note "SE Ranking credit balance unavailable — proceeding without preflight cost estimate; surface actual cost in deliverable" and continue. **Never** fail the run on this — credit data is a courtesy, not a gate. |
+| Credit balance below estimate | `remaining < estimated_cost` | Surface the shortfall; ask the user whether to proceed with a reduced scope (e.g. lower URL cap, lite mode) or top up credits before re-running. |
+| Firecrawl MCP not installed | `mcp__firecrawl-mcp__firecrawl_scrape` not in available tools | Note "Firecrawl not installed — degraded path active; install via `optbrew capability setup (see top-level routing)`" and run the WebFetch-only path. |
+| Firecrawl rate-limit hit | Firecrawl response 429 | Note "Firecrawl rate-limit reached — falling back to WebFetch for remaining URLs" and continue degraded for the rest of the run. Do not retry in a tight loop. |
+| Firecrawl Cloudflare/anti-bot block | Firecrawl response 403 / "blocked by WAF" | Note the affected URL and the block reason in the deliverable, then continue. Defeating WAFs is out of scope. |
+| Google config file missing | `google_auth.py --check` exits non-zero | Note "Google field data: not configured" and skip enrichment. |
+| Google API key invalid | Script returns `{"error": "API_KEY_INVALID"}` | Note "Google API key rejected — re-check `~/.config/seo-skills/google-api.json`" and skip. |
+| GSC property not verified | `gsc_query.py` returns `{"error": "PROPERTY_NOT_VERIFIED"}` | Note "GSC property `{x}` not verified for this account" and skip GSC enrichment only. |
+| GA4 property not configured | `ga4_property_id` empty in config | Note "GA4: property ID not configured (Tier 2 setup required)" and skip GA4 only. |
+| Insufficient CrUX data | `pagespeed_check.py --crux-only` returns `{"crux": null}` | Note "CrUX: insufficient field data for `{url}` (low traffic)" and skip CrUX only. |
+| Google API rate-limit hit | Script returns HTTP 429 | Note "Google API rate-limit reached — try again in 1h" and skip the affected enrichment. |
+
+A skill **never** fails the run because preflight enrichment failed. Enrichment is optional uplift; the SE Ranking-based deliverable always ships.
+
+## How to reference this from a skill
+
+In the skill's Prerequisites or Process step 1, replace the verbose 3-block preflight prose with this canonical reference:
+
+```
+1. **Validate target & preflight.** See `skills/seo-firecrawl/references/preflight.md` for the canonical 3-stage preflight (credit balance, Firecrawl availability, Google APIs). Skill-specific notes:
+   - Estimated SE Ranking cost for this skill: ~{N} credits ({describe scope}).
+   - Firecrawl: {required | optional with WebFetch fallback | not used}, ~{N} credits if available.
+   - Google APIs: {tier required for which enrichment step, or "not used"}.
+```
+
+Skill-specific notes preserve the bits that vary per skill (cost figures, Firecrawl scope, Google API tier) — the verbose preflight prose is centralised here.

package/skills/optbrew/modules/seranking-seo/skills/seo-geo/GUIDE.md

@@ -0,0 +1,159 @@
+> Example output: examples/seo-geo-notion-share-pages-20260514/GEO.md (upstream-only reference; route through optbrew)
+
+# Page-Level GEO (Generative Engine Optimization)
+
+For one URL, surface its AI-search citation footprint and recommend the page-level changes that would improve citability across AI Overview, Perplexity, ChatGPT, and other LLM-powered search engines. Different from the domain-level brand-vs-brand share-of-voice — this is page-level diagnosis.
+
+## Prerequisites
+
+- SE Ranking MCP server connected.
+- Claude's `WebFetch` tool available.
+- User provides: a target URL. Optional: target country (default `us`), specific keywords to focus on (defaults: the URL's top-5 traffic-weighted keywords from SE Ranking).
+
+## Process
+
+1. **Validate target & preflight.** See `skills/seo-firecrawl/references/preflight.md` for the canonical 3-stage preflight (credit balance, Firecrawl availability, Google APIs). Skill-specific notes:
+   - Confirm URL is fetchable before continuing.
+   - Estimated SE Ranking cost for this skill: ~10–20 credits typical (URL keyword footprint, AIO presence + leaderboard for top 5 keywords).
+   - Firecrawl: optional, ~3 Firecrawl credits if available. When available, the JSON-LD parse in step 7 and the AI-protocol-files step 8 use it. Without it, those steps emit `(skipped — Firecrawl not installed; install via optbrew capability setup (see top-level routing))` notes in `GEO.md` rather than failing the run. Pass `--no-firecrawl` to skip Firecrawl even when available (saves credits).
+   - Google APIs: not used.
+
+2. **URL keyword footprint** `DATA_getUrlOverviewWorldwide` and `DATA_getDomainKeywords` (URL-filtered)
+   - Pull URL's overview (keywords, traffic).
+   - Pull all keywords the URL ranks for. Sort by traffic-weighted score.
+   - Take the top 5 as the GEO investigation set (or use user-supplied keywords).
+
+3. **AIO presence per keyword** `DATA_getAiOverview`
+   - For each keyword, query AIO presence + citation list.
+   - Flag: AIO present? Is the candidate URL cited?
+   - Capture the AIO answer text — it tells you what passage shape Google's models prefer.
+
+4. **AIO leaderboard per keyword** `DATA_getAiOverviewLeaderboard`
+   - Full ranked list of cited sources per AIO query.
+   - Identify patterns: domain-level (which sites consistently cited?), passage-level (what structure?).
+
+5. **Page passage-level audit** `WebFetch`
+   - Pull the page HTML.
+   - Identify "passages" — paragraphs that could be extracted standalone (TL;DR boxes, definition paragraphs, summary sentences after H2s).
+   - For each passage, score citability:
+     - Has it a complete thought in 1–3 sentences?
+     - Does it answer a specific question (i.e., the question its parent H2 implies)?
+     - Has it a stat / number / named entity?
+     - Has it a clear timestamp or freshness signal?
+   - This is the citability layer.
+
+6. **Compare candidate to cited sources**
+   - For each AIO query where candidate is NOT cited, identify the cited sources.
+   - WebFetch 2–3 of them.
+   - Extract the cited passage (often a snippet from the AIO answer).
+   - Compare passage shape: candidate vs cited. Surface specific structural / content / freshness gaps.
+
+7. **Schema check** `mcp__firecrawl-mcp__firecrawl_scrape`
+   - WebFetch in step 5 returned markdown — JSON-LD blocks were stripped before parsing. The schema check requires Firecrawl to recover them.
+   - **If Firecrawl available:** scrape the target URL once (1 Firecrawl credit), parse the returned `html` for every `<script type="application/ld+json">` block. Specifically check for: `Article`/`BlogPosting` with valid `author` + `datePublished` + `dateModified`; `FAQPage` if Q&A blocks present; `BreadcrumbList`; `mainEntityOfPage` self-canonical.
+   - **If Firecrawl unavailable:** write `Schema check: skipped — Firecrawl required to parse JSON-LD blocks (WebFetch returns markdown only).` into `evidence/06-schema-check.md`, mirror the same line in the GEO.md "Schema check" section. Don't infer from markdown — that's the bug this section closes.
+   - Schema isn't a direct citation signal but it correlates strongly with citation rates in Google's AIO.
+
+8. **AI-protocol files** `mcp__firecrawl-mcp__firecrawl_scrape`
+   - **If Firecrawl available:** scrape `https://{domain}/llms.txt` and `https://{domain}/.well-known/rsl.json` (and the legacy `/RSL.txt` location as a fallback). Cost: 2 Firecrawl credits (one per file).
+   - For each file: capture HTTP status (200 / 404 / other), full body if present, and a parsed summary (declared content categories, allow/deny scope, attribution requirements).
+   - Surface in `evidence/07-ai-protocol-files.md` and in GEO.md as a new "AI-protocol files" section. These signal the domain's stance on LLM training and citation — present-and-permissive correlates with higher AIO citation rates.
+   - **If Firecrawl unavailable:** write `AI-protocol files: skipped — Firecrawl not installed.` Don't fall back to WebFetch (it would work for plain text but the integration stays uniform; runtime savings are negligible).
+
+9. **Synthesise** `GEO.md`
+
+## Output format
+
+Create a folder `seo-geo-{target-slug}-{YYYYMMDD}/` with:
+
+```
+seo-geo-{target-slug}-{YYYYMMDD}/
+├── GEO.md                            (synthesised report + recommendations — primary deliverable)
+├── 04-page-passages.md               (extracted passages + citability scores — load-bearing reference editors consult)
+├── 05-cited-source-comparison.md     (gap vs cited sources — load-bearing reference)
+└── evidence/
+    ├── 01-url-keyword-footprint.md   (URL overview + top keywords — raw step output)
+    ├── 02-aio-by-keyword.md          (AIO presence + citation per keyword)
+    ├── 03-leaderboards.md            (full leaderboards per keyword)
+    ├── 06-schema-check.md            (JSON-LD audit for GEO-relevant types — requires Firecrawl)
+    └── 07-ai-protocol-files.md       (llms.txt + RSL status and content — requires Firecrawl)
+```
+
+Top-level: `GEO.md` + `04-page-passages.md` + `05-cited-source-comparison.md`. The other step files preserve raw API/scrape outputs in `evidence/` for reproducibility — editors and writers don't open them in the normal flow.
+
+`GEO.md` follows this shape:
+
+```markdown
+# GEO Analysis: {URL}
+
+> Snapshot dated {YYYY-MM-DD} · Country: {country} · Keywords analysed: {n}
+
+## Citation footprint
+
+| Keyword | AIO present | Candidate cited | Citers |
+|---|---|---|---|
+| {keyword 1} | ✓ | ✗ | {3 cited sources} |
+| {keyword 2} | ✓ | ✓ | {includes candidate + 2 others} |
+| ... |
+
+**Citation rate: {n}/{checked} ({%}) of AIOs where candidate could appear actually cite it.**
+
+## Where the candidate IS cited
+- {keyword X} — passage cited: "{passage text}"
+- ...
+
+## Where the candidate is NOT cited (and AIO is present)
+- {keyword Y} — cited sources tend to share these patterns:
+  - {pattern 1: short definitive answer in first 100 words}
+  - {pattern 2: numbered stat with date}
+  - {pattern 3: schema-marked Article with author bio}
+- The candidate is missing: {specific gap}.
+
+## Page passage-level audit
+
+Top-scoring passages on the candidate (by citability score):
+1. {passage at H2 "X" — score 8/10. Strong: definitive sentence, named stat. Weak: no date.}
+2. ...
+
+Lowest-scoring passages (refresh candidates):
+1. {passage at H2 "Y" — score 3/10. Weak: vague generalities, no specific data.}
+2. ...
+
+## Schema check
+- `Article` (or sub-type) present and valid: {✓/✗ | skipped — Firecrawl required}
+- `author` populated with `@type: Person` and `url`: {✓/✗}
+- `datePublished` + `dateModified` ISO 8601: {✓/✗}
+- `FAQPage` for visible Q&A: {✓/✗/N-A}
+- `BreadcrumbList`: {✓/✗}
+
+## AI-protocol files
+- `/llms.txt` present: {✓ status 200 / ✗ status {n} / skipped — Firecrawl required}
+- `/.well-known/rsl.json` (or `/RSL.txt`) present: {✓ / ✗ / skipped}
+- Stance summary: {permissive / restrictive / mixed / unknown — based on declared categories and allow/deny scope}
+
+## Recommendations (top 5 to improve citability)
+
+1. {Specific change — e.g., "Add a 60-word TL;DR after the H1 that directly answers '{primary keyword}' — current page buries the answer below 800 words of preamble"}
+2. {Specific change}
+3. {Specific change}
+4. {Specific change}
+5. {Specific change}
+
+## Recommended next step
+Re-run `seo-geo` on this URL in 30 days after applying the recommendations. AIO indexes update on a monthly cadence — citation changes show up there first.
+```
+
+## Tips
+
+- Respect rate limit. ~5 keywords × 2 AIO calls = ~10 calls; plus 2–3 WebFetch on cited sources. Easy.
+- Cost: ~10–20 SE Ranking credits typical, plus ~3 Firecrawl credits when the extension is installed (1 for target-URL JSON-LD, 2 for AI-protocol files). The skill degrades gracefully without Firecrawl — the schema and AI-protocol sections emit explicit "skipped" notes rather than silently dropping.
+- **Citation isn't ranking.** A page can rank well organically and still not be cited in AIO. The opposite happens too — cited pages often rank below their citation rate.
+- The biggest GEO levers are usually:
+  1. Definitive answer in the first 200 words.
+  2. Specific stats with dates and sources.
+  3. Schema with author + dates.
+  4. Passage-level structure (each H2 is a question; first paragraph after H2 is the answer).
+- Pair with `seo-ai-search-share-of-voice` for domain-level brand-vs-brand visibility (this skill is page-level).
+- Pair with `seo-content-audit` to apply the CITE rubric to the page (which has more citation-readiness items).
+- Pair with `seo-schema` to fix schema issues identified in step 7.
+- Don't optimize for AIO at the expense of human readability. The two reinforce each other when done right.