optbrew 0.0.0-stage → 0.1.2

package/skills/optbrew/modules/seranking-seo/skills/seo-google/references/youtube-api.md

@@ -0,0 +1,49 @@
+# YouTube Data API v3 Reference
+
+YouTube mentions have the strongest correlation with AI visibility (0.737 per GEO research). This API provides authoritative YouTube data directly from Google.
+
+## Endpoints Used
+
+| Method | Quota Cost | Description |
+|--------|-----------|-------------|
+| `search.list` | 100 units | Search for videos matching a query |
+| `videos.list` | 1 unit | Get video details, statistics, content |
+| `channels.list` | 1 unit | Get channel info, subscriber count |
+| `commentThreads.list` | 1 unit | Get top comments on a video |
+
+## Daily Quota
+
+Default: **10,000 units/day** (free). This allows:
+- ~100 searches per day, OR
+- ~10,000 video/channel lookups per day
+
+## Data Available
+
+### Video Search
+- Title, channel, channel ID, published date
+- Description (first 300 chars), thumbnail URL
+- Views, likes, comments count, duration
+
+### Video Details
+- Full description, tags, category ID
+- Duration, definition (HD/SD), has captions
+- Topic categories (Wikipedia URLs)
+- Views, likes, comments, favorites
+- Top 10 relevant comments with likes
+
+### Channel Info
+- Title, description, custom URL
+- Subscriber count, video count, total views
+- Country, published date, thumbnail
+
+## Authentication
+
+**API key only** (read-only public data). No OAuth needed.
+
+## Enable the API
+
+1. Go to [console.cloud.google.com/apis/library](https://console.cloud.google.com/apis/library)
+2. Search for "YouTube Data API v3"
+3. Click Enable
+
+No billing required. The API key you already have for PSI/CrUX works.

package/skills/optbrew/modules/seranking-seo/skills/seo-keyword-niche/GUIDE.md

@@ -0,0 +1,174 @@
+> Example output: examples/seo-keyword-niche-espresso-machine-reviews-20260514/KEYWORD-NICHE-PLAN.md (upstream-only reference; route through optbrew)
+
+# Keyword Niche
+
+Mine the long tail for content opportunities. Pulls longtail variants, question-intent keywords, related keywords, and SERP samples to find under-served niche keywords; clusters them by intent; proposes a content tier (template + URL pattern + sample pages + thin-content quality gates) that can be published programmatically or as a steady editorial cadence.
+
+## Prerequisites
+
+- SE Ranking MCP server connected.
+- User provides: a seed topic (e.g. "running shoes", "tax preparation"), or 2–5 seed keywords. Target country (default `us`). Optional: minimum volume threshold (default: 50/mo for niche skill — lower than `seo-keyword-cluster`'s 100), maximum KD (default: 40 for accessibility).
+
+## Process
+
+1. **Validate & preflight**
+   - Confirm seeds make sense (not too broad, not branded, not single-letter).
+   - `DATA_getCreditBalance` — surface remaining credits. This skill is heavier than most: pulling longtail at depth costs more than pulling head terms.
+
+2. **Longtail expansion** `DATA_getLongTailKeywords`
+   - For each seed: pull longtail variants (typically 3+ words, lower individual volume, lower KD).
+   - Target: 200–500 longtail candidates per seed.
+
+3. **Question expansion** `DATA_getKeywordQuestions`
+   - For each seed: pull question-phrased keywords.
+   - These are gold for content mining — explicit user intent in the keyword.
+
+4. **Related expansion** `DATA_getRelatedKeywords` and `DATA_getSimilarKeywords`
+   - For each seed: pull related + similar keywords.
+   - Catches semantic neighbours that longtail expansion missed.
+
+5. **Filter and clean**
+   - Remove keywords below `min_volume` and above `max_kd`.
+   - Strip branded keywords the seed-domain doesn't own (unless the user supplied a branded seed).
+   - Tag each keyword with detected intent: informational, commercial, transactional, navigational.
+   - De-duplicate across seeds.
+
+6. **SERP sample for representative keywords** `DATA_getSerpResults`
+   - For 5–10 representative keywords (one per emerging cluster), pull top 10.
+   - Identify the dominant page type for each cluster (informs the template proposal in step 8).
+
+7. **Cluster by intent + theme**
+   - Group keywords by semantic similarity + intent.
+   - Each cluster: name, primary keyword, supporting keywords, total volume, weighted KD, dominant page type.
+   - Target 8–20 clusters (more granular than `seo-keyword-cluster`'s 5–12 — this skill is for niche tiers).
+
+8. **Propose a content tier**
+   - Template structure: which fields make each page unique. For `{city} apartment rentals`, the template fields are `{city}`, `{neighborhood}`, `{price_range}`, `{property_count}`. For `{tool} alternatives` it's `{tool}`, `{competitor_count}`, `{primary_use_case}`.
+   - URL pattern: `/{category}/{slug}/` or `/{topic}/{tool}-alternatives/` etc.
+   - Sample pages: 3 fully-spec'd page wireframes for representative cluster keywords.
+   - Internal-linking automation: how to link pages within the tier (hub-spoke from a category page, or peer-to-peer for genuinely flat structures).
+
+9. **Quality gates** (anti-thin-content guardrails)
+   - **Minimum unique data per page:** template fields must produce ≥ 5 unique attributes (counts, prices, names, dates, etc.). Pages without 5+ unique attributes are duplicates in disguise — skip those keyword variants.
+   - **Minimum word count:** 600 words effective content (excludes navigation, footer, boilerplate).
+   - **Schema requirement:** every templated page gets `Article` (or relevant type) + `BreadcrumbList`.
+   - **Index/noindex split:** if the variant doesn't pass the unique-data threshold, generate the page but `noindex` it.
+
+### 9a. Programmatic publishing — extra gates
+
+Most users discover this skill because they want to ship pages at scale (programmatic SEO, data-driven directories, location pages). Programmatic publishing is the highest-risk path for spam-classifier blowback. Apply these *in addition* to the gates above whenever the proposed tier expects to ship 50+ templated pages.
+
+- **Per-row uniqueness threshold (≥ 30% varying fields).** Of the template's content-producing fields (excluding nav/footer boilerplate), **at least 30% must hold values that differ from the median sibling page**. A 12-field template where 9 fields are identical across pages is templated mush — Google's spam systems are well-tuned for this since the 2024 core update. Compute: `varying_fields / content_fields ≥ 0.30` per row vs the cluster median.
+- **Min unique-fact count vs parent + sibling (≥ 5 facts).** Each row carries at least 5 facts that *do not appear on the parent hub page or any sibling page in the same cluster*. Facts = numbers, dates, named entities, original quotes, photos. Synonym shuffles don't count. Sample 10 rows manually before greenlighting the tier.
+- **Data-source independence.** Don't auto-publish from a single source (one CSV, one API, one scrape). If the page's only differentiator is a row from `cities.csv`, the page is a CSV row dressed as content — likely thin. Combine ≥ 2 independent data sources per page.
+- **Index-bloat circuit-breaker.** After the first 50 pages ship, monitor GSC. If the index-coverage rate drops below 60% (Google indexed <60% of submitted), pause the tier and re-audit. Continuing past this signal compounds bloat across the rest of the tier.
+- **Crawl-budget honesty.** Sites under 50k pages can usually crawl whatever you ship. Sites >50k must factor in crawl-budget cost: every thin programmatic page steals attention from the cornerstone content. If the site is in this band and the unique-fact count is borderline, default to noindex.
+
+These gates are not negotiable for the programmatic path. If the proposed tier can't pass them, the right answer is fewer pages, not lower thresholds.
+
+10. **Synthesise** `KEYWORD-NICHE-PLAN.md`
+
+## Output format
+
+Create a folder `seo-keyword-niche-{target-slug}-{YYYYMMDD}/` with:
+
+```
+seo-keyword-niche-{target-slug}-{YYYYMMDD}/
+├── KEYWORD-NICHE-PLAN.md           (synthesised plan — primary deliverable)
+├── keywords.csv                    (all enriched keywords with cluster + intent — load-bearing CSV the publishing team paste into CMS/sheets)
+├── 06-template-spec.md             (fields, URL pattern, sample pages — load-bearing reference writers consult directly)
+├── 07-quality-gates.md             (thin-content guardrails — load-bearing reference release-gate readers consult directly)
+└── evidence/
+    ├── 01-seed-expansion.md        (raw expansion per seed — raw step output)
+    ├── 02-question-keywords.md     (DATA_getKeywordQuestions)
+    ├── 03-filtered-keywords.md     (post min-vol / max-kd filter)
+    ├── 04-cluster-assignment.md    (every keyword and its cluster)
+    └── 05-serp-samples.md          (top 10 for representative cluster keywords)
+```
+
+Top-level: `KEYWORD-NICHE-PLAN.md` + `keywords.csv` + `06-template-spec.md` + `07-quality-gates.md`. Writers consult the template spec directly when authoring; release gates consult the quality gates directly. The 01–05 step files preserve raw API/clustering outputs in `evidence/`.
+
+`KEYWORD-NICHE-PLAN.md` shape:
+
+```markdown
+# Keyword Niche Plan: {topic}
+
+> Generated {YYYY-MM-DD} · Country: {country} · Seeds: {list}
+
+## Inventory
+- Longtail keywords mined: {n}
+- Question keywords: {n}
+- After filter (min-vol {n}, max-kd {n}): {n}
+- Clusters formed: {n}
+- Estimated combined monthly volume: {n}
+
+## Recommended content tier
+
+### Template
+**URL pattern:** `/{category}/{slug}/`
+
+**Required fields per page:**
+- `{slug}` — URL-friendly identifier
+- `{H1}` — page primary heading
+- `{TL;DR}` — first 200 words direct answer
+- `{primary_keyword}` — target keyword
+- `{related_keywords}` — secondary keywords from cluster
+- `{unique_attributes}` — list of ≥ 5 differentiating attributes (numbers, names, dates)
+- `{related_pages}` — internal-link list (3–5 sibling pages)
+- `{schema_type}` — Article/Product/Other
+- `{datestamp}` — last-updated date
+
+**Sample pages:** see `06-template-spec.md` for 3 fully-spec'd wireframes.
+
+## Cluster build order (top 10 by priority)
+
+| Rank | Cluster | Volume (combined) | Weighted KD | Dominant page type | Pages to ship |
+|---|---|---|---|---|---|
+| 1 | {cluster name} | {n} | {kd} | {type} | {n} |
+| ... |
+
+## Quality gates (do not ship pages that fail)
+
+1. **Unique-data threshold:** each page has ≥ 5 unique attributes vs sibling pages in the same cluster.
+2. **Minimum word count:** 600 words effective content.
+3. **Schema:** `Article` + `BreadcrumbList` (or relevant `@type` for the page).
+4. **Internal links:** ≥ 3 outbound to siblings, ≥ 1 inbound from category hub.
+5. **Index/noindex:** noindex pages that don't pass the unique-data threshold.
+
+### Programmatic-only gates (apply when tier ships 50+ pages)
+
+6. **Per-row uniqueness ≥ 30%:** at least 30% of content-producing fields hold values that differ from the cluster median.
+7. **Min unique facts vs parent + sibling (≥ 5):** five facts per row that don't appear on the parent hub or any sibling.
+8. **Data-source independence:** ≥ 2 independent data sources per page (no single-CSV pages).
+9. **Index-bloat circuit-breaker:** pause tier if GSC index-coverage <60% after the first 50 pages.
+
+## Scaling estimate
+- Clusters: {n}
+- Pages per cluster (median): {n}
+- Total pages: {n}
+- At {pages/week} cadence: {n weeks} to ship the tier.
+- Crawl-budget impact (for sites > 10k pages): noindex strategy keeps thin variants out of the index.
+
+## Risks / monitoring
+- **Thin-content penalty:** the quality gates above are the guardrail. Audit at scale via `seo-technical-audit` after first 100 pages ship.
+- **Index bloat:** monitor in GSC; if newly indexed pages don't accrue impressions in 60 days, candidate for noindex/consolidate.
+- **Cannibalization:** monitor with `seo-subdomain` + `seo-page` after first 50 pages.
+
+## Recommended next step
+Build a small pilot — 10 pages from the top cluster — before committing to the full tier. Apply quality gates rigorously to the pilot. Re-audit after 60 days; iterate the template based on which pilot pages indexed and ranked.
+```
+
+`keywords.csv` columns: `keyword,volume,kd,cpc,intent,cluster,role_in_cluster,dominant_page_type,unique_attributes_estimate`
+
+## Tips
+
+- Respect rate limit: 10 req/sec. Steps 2–4 fan out across all seeds; pace sequentially.
+- Cost: ~30–80 credits for 5 seeds, ~150+ for 10–20 seeds. Call `DATA_getCreditBalance` before running and surface the estimate.
+- **Programmatic SEO is risky.** Pages that don't pass the unique-data threshold are dead weight at best, penalty bait at worst. The quality gates in step 9 are not optional.
+- The pilot recommendation is critical. 10 pages with thoughtful templates outperform 1000 pages of templated mush.
+- For e-commerce / inventory-driven content (city pages, product variations), the unique-data threshold is usually easy to hit.
+- For "best X for Y" content (where Y has many variants), pick variants that have genuinely distinct content — don't templatise across near-synonyms.
+- Pair with `seo-keyword-cluster` for the broader pillar+spoke architecture (this skill complements, not replaces).
+- Pair with `seo-content-brief` to expand individual pillar topics into full editor briefs.
+- Pair with `seo-technical-audit` after first 100 pages ship to catch any thin-content / canonicalization issues.
+- Don't auto-publish. The template, URL pattern, and quality gates ship from this skill; the content authoring + review remains a human responsibility.

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

@@ -0,0 +1,174 @@
+> Example output: examples/seo-page-notion-keyboard-shortcuts-20260514/PAGE.md (upstream-only reference; route through optbrew)
+
+# Page Intelligence
+
+Show what a single URL ranks for, what traffic it captures, where its weak and strong points are, and what to do about it. The deliverable is an opinionated verdict — **KEEP**, **REFRESH**, **CONSOLIDATE**, or **KILL** — anchored in objective signals from SE Ranking's URL-level data.
+
+## Prerequisites
+
+- SE Ranking MCP server connected.
+- Claude's `WebFetch` tool available (for the page-level HTML sense-check).
+- User provides: (a) a target URL, optionally (b) target market country (default: `us`), (c) primary topical keyword (auto-inferred from `<title>` + `<h1>` if not supplied).
+
+## 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 the URL is fetchable; derive parent domain. If the user supplied a primary keyword, use it; otherwise infer it in step 3.
+   - Estimated SE Ranking cost for this skill: ~10–15 credits typical (URL overview, ranking keywords, page authority, SERP context for top 3–5 keywords).
+   - Firecrawl: optional with WebFetch fallback, ~1 Firecrawl credit if available. When available, step 6 recovers `og:*`, `twitter:*`, canonical, robots meta, JSON-LD types, and hreflang count from raw `<head>` — WebFetch returns markdown only and strips those fields. Without Firecrawl, the affected lines in `PAGE.md` emit `(skipped — Firecrawl not installed)`. Pass `--no-firecrawl` to treat Firecrawl as unavailable even when installed (credit conservation).
+   - Google APIs: tier 1 (GSC available) unlocks step 4b (GSC URL performance + URL Inspection) after the page-authority step. See `skills/seo-google/references/cross-skill-integration.md` § "seo-page" for the full recipe.
+
+2. **URL-level overview** `DATA_getUrlOverviewWorldwide`
+   - Pull keyword count, organic traffic estimate, paid keyword count, paid traffic estimate, top regions.
+   - Note: traffic estimates are directional — they don't replace Google Search Console.
+
+3. **Ranking keywords** `DATA_getDomainKeywords` (use the `url` param for exact match — not `filter_url`)
+   - Pull every keyword the URL ranks for in the target country, with positions.
+   - Sort by traffic-weighted score: `volume × CTR-by-position` (use a standard CTR curve: 1=28%, 2=15%, 3=11%, 4=8%, 5=7%, 6=5%, 7=4%, 8=3%, 9=2%, 10=2%, 11+=1%).
+   - Take the top 3–5 as the URL's "primary keywords" for SERP work in step 5.
+
+4. **Page authority** `DATA_getPageAuthority` + `DATA_getPageAuthorityHistory`
+   - Current PA score and its 12-month trajectory.
+   - Flag any drop > 5 points in the last 90 days.
+
+4b. **GSC URL performance + URL Inspection** *(only if google-api.json is present, tier ≥ 1)*
+   - Replaces the directional traffic estimate from step 2 with first-party Google data for the exact URL.
+   - Pull GSC search analytics for the URL (last 28 days, by query and page):
+     `upstream script excluded; use optbrew capability routing "{config.default_property}" --url "{target_url}" --days 28 --json`
+   - Pull URL Inspection (real indexation status, canonical Google sees, last crawl date):
+     `upstream script excluded; use optbrew capability routing "{target_url}" --site-url "{config.default_property}" --json`
+   - If the URL's domain isn't a verified GSC property: surface "GSC: {target_domain} not verified — add it in Search Console" and continue with SE Ranking data only.
+   - Surface in `PAGE.md` "## Snapshot": `GSC last 28d: {clicks}/{impressions}/{ctr}% CTR / pos {position}` and `Google sees: {INDEXED|EXCLUDED} · canonical {userCanonical} → {googleCanonical} · last crawled {date}`.
+   - **Feed into the verdict heuristic:** `INDEXED` + impressions > 100 + position 4–10 → harden REFRESH (clear quick-win). `EXCLUDED` (any reason) → harden KILL or CONSOLIDATE. `userCanonical ≠ googleCanonical` → flag as critical issue regardless of verdict.
+   - See `skills/seo-google/references/cross-skill-integration.md` § "seo-page" for the full recipe.
+
+5. **SERP context** `DATA_getSerpResults` and `DATA_getAiOverview`
+   - For each of the 3–5 primary keywords:
+     - Top 10 organic results (URL, title, snippet).
+     - SERP features present (PAA, image carousel, video, shopping, etc.).
+     - AIO presence and citations — is this URL cited in the AIO?
+
+6. **HTML sense-check** `WebFetch` (always) + `mcp__firecrawl-mcp__firecrawl_scrape` (when available)
+   - **WebFetch first** (free, instant): extract `<title>`, meta description, all `<h1..h6>`, lang, word count, internal-link count, image count. WebFetch returns markdown so anything in `<head>` beyond `<title>` is lost — the next bullet recovers it.
+   - **Firecrawl second** (1 Firecrawl credit; pass `formats: ["rawHtml"]`) — recovers what WebFetch can't see. Pin the format to `rawHtml`; the default `html` is post-processed and silently strips canonical, hreflang, and `<script type="application/ld+json">` blocks on many sites. If those head fields come back zero on a site that obviously has them (any major SaaS homepage), you forgot the `rawHtml` flag — re-run.
+     - From `metadata`: `og:title`, `og:description`, `og:image`, `twitter:card`, `viewport`, robots meta, canonical URL.
+     - From the returned `rawHtml`: every `<script type="application/ld+json">` block. Parse each as JSON, list detected `@type`s (Article, BreadcrumbList, Organization, Product, etc.). Note any block that fails to parse.
+     - hreflang: count `<link rel="alternate" hreflang="…">` occurrences in `rawHtml`.
+   - **If Firecrawl unavailable:** the WebFetch portion still runs; populate Page basics' OG / Twitter / canonical / robots / JSON-LD / hreflang lines as `(skipped — Firecrawl not installed)`. Don't infer from markdown.
+   - **Sense-check:** does the page actually talk about its top-ranking keyword in title and H1? If a page ranks for keywords it doesn't address textually, that's a strong consolidation signal.
+
+7. **Domain context** `DATA_getDomainOverviewWorldwide` (parent domain)
+   - Light-weight: parent DA, total keywords, total traffic. Used to contextualise the page's PA against its domain.
+
+8. **Cannibalization check** `DATA_getDomainPages`
+   - Pull the parent domain's pages ranked by organic traffic. Cap at the top 50 — that's where the cannibalization risk concentrates.
+   - For the candidate URL's top-3 traffic-weighted keywords (from step 3), scan the peer-page list: does any other URL on the same domain rank in the top 20 for any of those keywords?
+   - **Cannibalization signal:** any peer URL ranking ≤ 20 for the candidate's top-3 keywords. Record peer URL, keyword, peer position vs candidate position, peer traffic.
+   - **Cheaper than the old approach.** Previous versions cross-checked via `DATA_getDomainKeywords` on the parent domain — that endpoint can return tens of thousands of rows on large sites and is unnecessarily heavy for this question. `DATA_getDomainPages` ranked by traffic surfaces the high-impact peers directly.
+   - If no peer URL competes, this signal is "no cannibalization detected" — pass through to step 9.
+
+9. **Synthesise verdict**
+   - Apply the verdict heuristic (see Tips) to produce KEEP / REFRESH / CONSOLIDATE / KILL.
+   - For REFRESH, identify the top 3 specific changes (e.g., "add an H2 on 'alternatives' which 7 of 10 SERP winners use").
+   - Write `PAGE.md` (output spec below).
+
+## Output format
+
+Create a folder `seo-page-{target-slug}-{YYYYMMDD}/` with:
+
+```
+seo-page-{target-slug}-{YYYYMMDD}/
+├── PAGE.md                       (synthesised verdict + plan — primary deliverable)
+├── keywords.csv                  (full keyword list with positions — load-bearing CSV the auditor walks through row-by-row)
+├── 04-serp-context.md            (top 10 + AIO for top 3–5 keywords — load-bearing reference for SERP-driven REFRESH discussions)
+└── evidence/
+    ├── 01-url-overview.md        (raw DATA_getUrlOverviewWorldwide)
+    ├── 02-keywords.md             (raw DATA_getDomainKeywords filtered)
+    ├── 03-authority.md            (PA + history)
+    ├── 05-page-snapshot.md        (HTML extracts)
+    └── 06-cannibalization.md      (peer pages on the same domain competing for the top-3 keywords)
+```
+
+Top-level: `PAGE.md` + `keywords.csv` + `04-serp-context.md`. The other step files preserve raw API/HTML extracts in `evidence/` for reproducibility — auditors lean on the CSV and SERP context, not the per-call dumps.
+
+`PAGE.md` follows this shape:
+
+```markdown
+# Page Intelligence: {URL}
+
+> Snapshot dated {YYYY-MM-DD} · Country: {country} · Primary keyword: {keyword}
+
+## Snapshot
+- Ranking keywords: {n}
+- Estimated monthly organic traffic: {n}
+- Page authority: {PA} ({↑/↓ trajectory over 90 days})
+- Primary topic: {topic}
+- AIO citations: {n} of {checked} primary-keyword AIOs cite this URL
+- GSC last 28d: {clicks} clicks / {impressions} impressions / {ctr}% CTR / avg position {n}  *(or `not configured` / `property not verified`)*
+- Google sees: {INDEXED|EXCLUDED|...} · canonical {userCanonical} {→ googleCanonical if differ} · last crawled {YYYY-MM-DD}
+
+## Page basics
+- `<title>`: {value}
+- meta description: {value | absent}
+- `og:title`: {value | absent | skipped — Firecrawl required}
+- `og:description`: {value | absent | skipped}
+- `og:image`: {url | absent | skipped}
+- `twitter:card`: {summary | summary_large_image | absent | skipped}
+- `<link rel="canonical">`: {URL | self-referential | absent | skipped}
+- meta robots: {index,follow | noindex,nofollow | absent | skipped}
+- JSON-LD types detected: {Article, BreadcrumbList, Organization | none | skipped}
+- hreflang variants: {n | skipped}
+
+## What this page wins
+- {keyword} — position {n}, ~{volume} monthly searches, ~{traffic} monthly clicks.
+- ... (top 3–5)
+
+## Almost-wins (page-2 refresh opportunities)
+- {keyword} — position {n}, ~{volume} monthly searches. The top 3 SERP winners all do {pattern} that this page doesn't.
+- ... (top 3 examples)
+
+## What this page misses
+- {keyword} — competitors {comp1}, {comp2} rank in top 5; this page is absent.
+- ...
+
+## Same-domain cannibalization
+- {peer URL} — ranks position {n} for "{keyword}" (candidate ranks position {m}). Peer estimated traffic: {n}/mo.
+- ... (only list rows where a peer URL ranks ≤ 20 for one of the candidate's top-3 keywords; if none, write "No same-domain cannibalization detected on top-3 keywords.")
+
+## AI Search angle
+- {n} of {checked} AIO queries on the URL's keywords cite this page.
+- The AIOs that DON'T cite this page tend to cite {pattern} (e.g., comparison tables, step-by-step how-tos).
+- Recommended GEO move: {one specific change}.
+
+## Verdict: {KEEP | REFRESH | CONSOLIDATE | KILL}
+
+Reasoning: {1–2 sentences anchored in objective signals from above}.
+
+### If REFRESH — top 3 changes
+1. {Specific change}
+2. {Specific change}
+3. {Specific change}
+
+## Raw data
+- keywords.csv — full enriched ranking-keyword list
+- 04-serp-context.md — per-keyword SERP top-10 with AIO
+- evidence/05-page-snapshot.md — HTML extracts
+```
+
+`keywords.csv` columns: `keyword,volume,kd,position,intent,traffic_estimate,url`
+
+## Tips
+
+- Respect SE Ranking Data API rate limit: 10 requests per second. The 3–5 SERP queries in step 5 should be paced sequentially.
+- Call `DATA_getCreditBalance` before running. ~10–15 credits is typical for one URL.
+- Verdict heuristic:
+  - **KEEP**: PA stable or up; traffic stable or up; top 3 keywords held in their positions; AIO citations present where AIO appears.
+  - **REFRESH**: any of (PA dropped >5 in 90 days; traffic dropped >20%; a top-3 keyword fell to position 11+; AIO citations missing while competitors get cited). **Hardens** when GSC data (step 4b) shows `INDEXED` + impressions > 100 + average position 4–10 (clear quick-win territory).
+  - **CONSOLIDATE**: cannibalization detected (step 8) — a peer URL on the same domain ranks ≤ 20 for one or more of the candidate's top-3 keywords. CONSOLIDATE harden when the peer outranks the candidate AND captures higher traffic; otherwise CONSOLIDATE recommendation is "merge into the candidate" rather than "kill the candidate."
+  - **KILL**: PA <10 AND traffic <50/mo AND no top-10 keyword AND no internal links pointing to it. **Hardens** when JSON-LD schema is also absent (Firecrawl detected zero blocks) — the page has no signals for any crawler, organic or AI. **Also hardens** when URL Inspection (step 4b) returns `EXCLUDED` for any reason.
+  - **GSC canonical mismatch (any verdict):** if step 4b detects `userCanonical ≠ googleCanonical`, flag this as a critical issue in `PAGE.md` regardless of the verdict — it points at indexing instability that the verdict on its own can't resolve.
+- Don't invent reasons. Anchor every claim in `PAGE.md` to a number from the raw data files.
+- When between KEEP and REFRESH, default to REFRESH — small refreshes compound.
+- The `keywords.csv` is the auditable trail. If a stakeholder questions the verdict, walk them through the CSV row by row.
+- For pages with very low data (new pages, <5 ranking keywords), the verdict is unreliable. Flag as "insufficient data — re-run after 60 days" rather than forcing a verdict.
+- **`DATA_getPageAuthorityHistory` all-zeros caveat:** if the endpoint returns `inlink_rank: 0` (or equivalent) for every date in the history window, treat as "insufficient history" — don't claim a drop or recommend REFRESH based on it. Often happens for very high-authority pages where the metric is saturated, or for URLs that haven't accumulated enough longitudinal data. Cross-check with `DATA_getPageAuthority` (current value) — if current PA is meaningful but history is flat-zero, flag the gap explicitly in `PAGE.md` rather than synthesising a trajectory.

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

@@ -0,0 +1,220 @@
+> Example output: examples/seo-plan-wix-com-20260514/PLAN.md (upstream-only reference; route through optbrew)
+
+# SEO Plan
+
+Produce a phased SEO roadmap for a domain. Output is a single `PLAN.md` plus per-phase deliverable folders, each phase scoped to a quarter (or a 90-day sprint), each with explicit goals, work items, owners, and metrics. The plan is grounded in the site's actual competitive position — not a generic checklist.
+
+This is the "what should we work on next quarter" skill. It does not replace specialist skills — it composes them, then sequences their outputs.
+
+## Prerequisites
+
+- SE Ranking MCP server connected.
+- `seo-firecrawl` available for site mapping and head metadata (optional but recommended).
+- User provides:
+  - Target domain.
+  - Optionally: target country (default `us`), business type (saas / ecommerce / local / publisher / agency / b2b — auto-detected from the domain if not supplied), planning horizon (default 90 days, options: 30 / 90 / 180 / 365).
+  - Optionally: known constraints (engineering capacity, content budget, no JS-render changes allowed, etc.).
+
+## Process
+
+0. **Google data availability check (advisory, not blocking)**
+   - Run `upstream script excluded; use optbrew capability routing`. If `tier >= 0`, the downstream specialist skills (technical-audit, page, content-audit, drift) will enrich their outputs with real Google field data — and `seo-plan` ingests those richer outputs in step 4. The plan itself doesn't dispatch `seo-google` directly; it prints a one-line notice so the user knows the option is on the table:
+   ```
+   > Google APIs detected (tier {n}, available: {comma-list}). Downstream specialist
+   > skills (seo-technical-audit, seo-page, seo-content-audit, seo-drift) will enrich
+   > their outputs with real CrUX / GSC / GA4 / URL Inspection data automatically.
+   ```
+   - If creds are missing, the plan continues with SE Ranking-only data and prints:
+   ```
+   > Google APIs not configured. To enrich downstream phases with real CWV / GSC /
+   > GA4 / indexation data, run `optbrew capability setup (see top-level routing)`. Plan continues
+   > with SE Ranking data only.
+   ```
+   - This is the **lightest possible auto-spawn** — `seo-plan` doesn't run `seo-google` itself (transferring friction to a single command is theirs' anti-pattern we critiqued in `EVAL_RESULT_v2.md`); it surfaces the option so the user can opt in or out before specialist skills run. See `skills/seo-google/references/cross-skill-integration.md` § "seo-plan" for the full rationale.
+
+1. **Detect business type** `DATA_getDomainOverviewWorldwide`, plus a Firecrawl `scrape` of the homepage if available
+   - Inspect title, H1, JSON-LD types, primary nav patterns.
+   - Classify as one of: `saas`, `ecommerce`, `local`, `publisher`, `agency`, `b2b-services`, `marketplace`. If ambiguous, ask the user once.
+   - Business type drives template selection (see step 6).
+
+2. **Domain baseline** `DATA_getDomainOverviewWorldwide`, `DATA_getDomainOverviewHistory`, `DATA_getDomainAuthority`, `DATA_getBacklinksSummary`
+   - Capture: organic keywords, organic traffic estimate, DA, backlink profile health, top countries, traffic trend over the last 12 months.
+   - This sets the "where you are now" anchor.
+
+3. **Competitive frame** `DATA_getDomainCompetitors`
+   - Pull top 5–10 organic competitors.
+   - For each: organic keywords, traffic share, DA, top topical clusters they own.
+   - Identifies who the user is *actually* competing with on the SERP (often different from who they think).
+
+4. **Pull specialist inputs — confirm-then-dispatch pattern**
+   - **4a. Detect existing outputs.** In the current working directory, look for any folder matching the patterns below dated within the last 30 days (treat folders older than 30 days as stale and re-list them as missing):
+     - `seo-technical-audit-*`
+     - `seo-content-audit-*`
+     - `seo-competitor-gap-analysis-*`
+     - `seo-ai-search-share-of-voice-*`
+     - `seo-backlinks-profile-*`
+   - For each present folder, ingest its primary deliverable (`TECH-AUDIT.md`, `VERDICT.md` rollup, `GAPS.md`, `REPORT.md`, `PROFILE.md` respectively).
+   - **4b. Build the missing list.** For each prerequisite that did not have a fresh output, look up its credit-cost figure from the specialist's own GUIDE.md (read those when forming the prompt — figures may drift):
+     - `seo-technical-audit` → varies by page count for a fresh audit; ~6 Firecrawl credits for the modern-signals step. Cite "varies; check page count" if no recent audit cached.
+     - `seo-content-audit` → ~10–15 SE Ranking credits + 1 Firecrawl credit per audited URL (default cap 50; for the seo-plan top-10-pages scope, expect ~10–15 SE Ranking + ~10 Firecrawl).
+     - `seo-competitor-gap-analysis` → ~30–80 credits for 10 seeds.
+     - `seo-ai-search-share-of-voice` → ~10–20 credits (leaderboard + ~20 prompts × N domains).
+     - `seo-backlinks-profile` → ~25–40 SE Ranking credits.
+   - **4c. Print the confirmation prompt** (single block, exactly this shape, with the missing-list filtered to only what is actually missing):
+   ```
+   To produce a defensible plan, seo-plan needs outputs from N specialists not yet
+   run for {domain}:
+   - seo-technical-audit (~{N} credits)
+   - seo-content-audit (~{N} credits)
+   - seo-competitor-gap-analysis (~{N} credits)
+   - seo-ai-search-share-of-voice (~{N} credits)
+   - seo-backlinks-profile (~{N} credits)
+   Total estimated cost: ~{N} credits.
+   Run them now in this session? (y/N — default N preserves the existing v2.6 behavior of asking the user to run them manually first)
+   ```
+   - **4d. If user answers `y`:** dispatch each missing specialist in this order, ingesting each primary deliverable as it completes:
+     - **Parallel batch (independent):** `seo-technical-audit`, `seo-competitor-gap-analysis`, `seo-ai-search-share-of-voice`, `seo-backlinks-profile`.
+     - **Sequential after the batch:** `seo-content-audit` — its top-10-pages scope depends on knowing the top traffic pages from `seo-competitor-gap-analysis` / `DATA_getDomainKeywords`, so it must run after the gap-analysis batch completes.
+     - Each specialist runs its own `DATA_getCreditBalance` preflight and surfaces cost before proceeding (their existing behaviour — `seo-plan` does not bypass it). If any specialist aborts on a credit-balance check, surface that abort to the user and let them decide whether to top up or skip.
+     - After every dispatch, ingest the new folder the same way step 4a does.
+   - **4e. If user answers `N` (or anything else — default `N`):** fall through to the existing v2.6 behaviour — the plan opens with **Phase 0: Discovery**, and running each missing specialist becomes the first sprint's work. This preserves the user's control over credit spend in environments where the specialists should be scheduled or batched separately.
+
+5. **Score the four pillars**
+   - **Technical health** (0–100): from `seo-technical-audit` severity-weighted issue count.
+   - **Content quality** (0–100): average E-E-A-T+CITE score across audited pages.
+   - **Topical authority** (0–100): cluster coverage relative to top 3 competitors.
+   - **AI Search readiness** (0–100): citation share vs SoV competitors.
+   - The lowest pillar becomes the **lead theme** for the first phase.
+
+6. **Apply business-type template** (templates differ — pick one and parameterise)
+   - **saas** → product-led pillars + integration pages + comparison/alternatives + JTBD content.
+   - **ecommerce** → category page hygiene + product schema + faceted-nav indexation rules + review aggregation.
+   - **local** → GBP optimisation + location pages + citation cleanup (note: we don't have a `seo-local` skill yet — flag this as a manual sub-step or external).
+   - **publisher** → topical clusters + author E-E-A-T + freshness cadence + AI-Search citations.
+   - **agency** → service pages + case studies + comparison content + lead-gen LP (use `seo-agency-landing-page`).
+   - **b2b-services** → industry-specific landing pages + thought-leadership clusters + decision-stage content.
+   - Template provides default work-item categories; the lowest-pillar score from step 5 weights them.
+
+7. **Phase the plan** — three phases over the planning horizon, each with goals, work items, owners, metrics
+   - **Phase 1 (weeks 1–4 of horizon): Foundations.** Technical fixes that unblock everything else, baseline drift snapshot, 1–2 quick-win content refreshes from `seo-page` verdicts.
+   - **Phase 2 (weeks 5–8): Build.** Content tier from `seo-keyword-cluster` (1 pillar + 3–7 spokes), schema fixes from `seo-schema`, comparison page from `seo-competitor-pages` if competitive frame supports it.
+   - **Phase 3 (weeks 9–12): Compound + measure.** AI Search readiness pass via `seo-geo` on top pages, backlink-gap outreach starter from `seo-backlink-gap`, second drift comparison via `seo-drift compare`, retro + adjust.
+   - For longer horizons (180/365 days), repeat phases 2+3 with refreshed inputs and a quarterly retro.
+   - Each work item is tagged with the skill that produces it: `seo-content-brief`, `seo-schema`, `seo-page`, etc.
+
+8. **Pick metrics**
+   - **Lagging (quarterly):** organic traffic, organic keywords ranking top-10, organic conversions.
+   - **Leading (weekly/monthly):** technical-issue count, pages with E-E-A-T verdict ≥ 70, AI Search citation count, referring-domain count.
+   - One leading + one lagging per phase. Tie each metric to a current value (from step 2) and a phase-end target. Targets must be defensible — call out base rates.
+
+9. **Sequencing + dependencies**
+   - Build a dependency map: e.g., "rewrite cluster A pillar" depends on "fix `noindex` on /blog templates" depends on "run `seo-technical-audit`."
+   - Surface the critical path. Anything off the critical path is moveable; anything on it blocks the phase.
+
+10. **Synthesise** `PLAN.md`
+
+## Output format
+
+Folder `seo-plan-{domain-slug}-{YYYYMMDD}/`:
+
+```
+seo-plan-{domain-slug}-{YYYYMMDD}/
+├── PLAN.md                              (synthesis — primary deliverable; inlines 01-baseline, 02-competitive-frame, 07-dependencies, 08-metrics as sections)
+├── 04-phase-1-foundations.md            (load-bearing — owners share single phase files in standups)
+├── 05-phase-2-build.md                  (load-bearing — owners share single phase files)
+├── 06-phase-3-compound.md               (load-bearing — owners share single phase files)
+└── evidence/
+    ├── 01-baseline.md                   (where you are now — raw data inlined into PLAN.md)
+    ├── 02-competitive-frame.md          (who you're actually competing with — raw data inlined into PLAN.md)
+    ├── 03-pillar-scores.md              (technical / content / topical / AI Search — scoring math)
+    ├── 07-dependencies-and-critical-path.md  (dependency map — inlined as PLAN.md section)
+    └── 08-metrics.md                    (metric tables — inlined as PLAN.md section)
+```
+
+Top-level: `PLAN.md` + the three phase files (`04`/`05`/`06`). Owners share single phase files in standups, so phase files stay top-level rather than collapsing into PLAN.md. The verbatim-duplicate sections (baseline, competitive frame, dependencies, metrics) are inlined into PLAN.md but the raw step files are preserved in `evidence/` along with the pillar-scoring math.
+
+`PLAN.md` follows this shape:
+
+```markdown
+# SEO Plan: {domain}
+
+> Plan dated {YYYY-MM-DD} · Horizon: {n} days · Business type: {type} · Country: {country}
+
+## Where you are
+- Organic keywords: {n} (trend: {↑↓→ over 12mo})
+- Organic traffic estimate: {n}/mo
+- Domain authority: {n}
+- Referring domains: {n}
+- Pillar scores: Technical {n}/100 · Content {n}/100 · Topical {n}/100 · AI Search {n}/100
+
+## Lead theme
+{The lowest pillar from step 5, plus a one-line "why this is the constraint."}
+
+## Top 5 competitors
+| Domain | DA | Organic kw | Top cluster they own |
+|---|---|---|---|
+| {comp} | {n} | {n} | {cluster} |
+
+## Phase 1 — Foundations (weeks 1–4)
+
+**Goal:** {1-line outcome, e.g. "remove technical debt blocking content investment"}
+
+| # | Work item | Skill / source | Owner | Effort | Phase-end metric |
+|---|---|---|---|---|---|
+| 1.1 | {item} | `seo-technical-audit` follow-up | {role} | {S/M/L} | {metric} |
+| 1.2 | ... | | | | |
+
+**Phase exit criteria:** {what must be true to declare Phase 1 done}
+
+## Phase 2 — Build (weeks 5–8)
+{same shape}
+
+## Phase 3 — Compound + measure (weeks 9–12)
+{same shape}
+
+## Critical path
+{Ordered list of work items that block subsequent phases. Anything not on this list is moveable.}
+
+## Metrics
+
+| Metric | Type | Current | Phase 1 target | Phase 2 target | Phase 3 target |
+|---|---|---|---|---|---|
+| Organic traffic | Lagging | {n} | {n} | {n} | {n} |
+| Pages with E-E-A-T ≥ 70 | Leading | {n} | {n} | {n} | {n} |
+| Technical issue count | Leading | {n} | {n} | {n} | {n} |
+| AI Search citation count | Leading | {n} | {n} | {n} | {n} |
+| Referring domains | Leading | {n} | {n} | {n} | {n} |
+
+## Constraints / caveats
+{User-supplied constraints, plus anything the data flags — e.g., "DA gap to top competitor is 25 points; expect 6+ months for keyword parity."}
+
+## Recommended next step
+Run Phase 1 work items. After week 4, run `seo-drift compare` against the baseline captured today, then adjust Phase 2 scope.
+```
+
+## Tips
+
+- **Default is "no auto-dispatch."** The confirm prompt in step 4c defaults to `N`. If the user just hits Enter (or answers anything other than an explicit `y`), `seo-plan` falls through to the v2.6 Phase-0 behaviour and lists the missing specialists as the first sprint's work. This preserves user control over credit spend — important when the user is on a tight SE Ranking budget or wants to schedule specialists separately.
+- **Auto-dispatch (the `y` path) is the convenience option.** When the user wants a finished plan in one session and is comfortable with the displayed credit estimate, the `y` path runs the missing specialists in the optimal parallel-then-sequential order described in step 4d, ingests their outputs, and proceeds straight into pillar scoring (step 5). No silent re-execution: every dispatch is gated by the single confirmation in step 4c.
+- **Auto-dispatch respects each specialist's own credit-balance preflight.** Each specialist already calls `DATA_getCreditBalance` at its first step and surfaces cost before consuming credits — `seo-plan` does not bypass that gate. If a specialist aborts on its preflight (insufficient credits, user declines its inner cost prompt), `seo-plan` surfaces the abort and lets the user choose to top up, skip that specialist (and let it remain a Phase-0 work item), or cancel the rest of the dispatch.
+- **Auto-detect business type cheaply.** Homepage `<title>`, schema `@type`, and top-nav anchors are usually enough. Ask the user only when truly ambiguous.
+- **The lead theme is the lowest pillar score.** Don't pick the pillar the user is most excited about — pick the one the data says is the constraint. Surface this gap explicitly if they conflict.
+- **Three phases, even for 30-day horizons.** Compress, don't drop. A 30-day plan is foundations (weeks 1–2), build (weeks 2–3), measure (week 4). The structure forces sequencing discipline.
+- **Targets must be defensible.** Don't write "double organic traffic in Q1." Tie each target to a base rate from competitor data or category benchmarks. If the math doesn't support a target, say so and lower it.
+- **Critical path is the deliverable.** Most teams can do *something*; few know what's blocking what. Surface the dependency chain — that's where this skill earns its keep.
+- **Local SEO is a known gap.** If business type is `local`, flag that we don't have a `seo-local` skill yet and recommend manual GBP audit as a Phase 0 item. Don't pretend coverage we don't have.
+- **Don't generate work items the team can't execute.** If the user said "no JS-render changes allowed," drop those items even if they're high-leverage. A plan that won't ship is worse than a smaller plan that does.
+- **Update cadence.** A 90-day plan should be re-run at the 90-day mark with `seo-drift compare` against the original baseline as input. Drift output rewrites the "Where you are" section; everything downstream updates from there.
+
+## Works well with
+
+- **Predecessors:**
+  - `seo-technical-audit`, `seo-content-audit`, `seo-competitor-gap-analysis`, `seo-ai-search-share-of-voice`, `seo-backlinks-profile` — produce inputs.
+  - `seo-drift baseline` — captures the snapshot the plan measures progress against.
+- **Successors:**
+  - `seo-keyword-cluster` — when Phase 2 calls for a content tier.
+  - `seo-content-brief` — for each spoke article in Phase 2.
+  - `seo-schema` — for structured-data work items.
+  - `seo-competitor-pages` — when comparison content is on the plan.
+  - `seo-drift compare` — at end of phase to measure progress.
+  - `seo-page` — for individual URL keep/refresh/consolidate/kill calls in Phase 1.