@jairodri/huckleberry-cli 1.0.1 → 1.1.0

package/skills/seo-machine/references/api-stack-recipes.md

@@ -0,0 +1,230 @@
+# Cross-API Compound Recipes
+
+Single APIs answer single questions. Compound recipes — chaining two or three APIs in one move — answer the questions Ahrefs alone can't. The four recipes here are mktg-native and depend only on tools already in our stack: **Exa MCP**, **last30days** skill, **firecrawl**, **gh CLI**, **mktg-x**, **DeepWiki**, **company-research** skill, **people-research** skill, **Exa Websets MCP**.
+
+Each recipe in this file is a sequence — run the steps in order, accumulate outputs, hand the consolidated result to the parent skill.
+
+---
+
+## Recipe 1 — Pain-Point Cluster Discovery
+
+Finds the *real* complaints the audience has today, not yesterday's keyword data. Drives `/for/` use-case page angles and `/playbooks/` opening hooks. Replaces stale Ahrefs "questions" data.
+
+**APIs chained:** `/last30days` + Exa `deep_search_exa` + `mktg-x` (optional, when X login cookie is configured) + Exa `web_search_advanced_exa`
+
+```
+Step 1 — Aggregate recent organic signal
+  Invoke: /last30days "<product-category> + frustrations OR problems OR struggling with"
+  → Returns Reddit + X + HN + YouTube + TikTok mentions with engagement counts
+  → Filter to posts with >10 engagement (avoid astroturfed noise)
+
+Step 2 — Cluster the complaints
+  For each high-engagement complaint, extract the verb phrase:
+    "I keep losing track of..." → "keep losing track of <object>"
+    "Why is <task> so hard?" → "<task> being hard"
+    "There has to be a better way to..." → "better way to <task>"
+  Cluster phrases by verb-object similarity. 5-10 clusters typical.
+
+Step 3 — Validate via Exa deep search
+  For each cluster, run:
+    mcp__exa__deep_search_exa(
+      objective: "What are people saying about <cluster-phrase> in <product-category>?",
+      type: "deep",
+      numResults: 8
+    )
+  → Confirms cluster is real (not a single noisy post)
+  → Surfaces authoritative articles already covering the pain
+
+Step 4 — Optional X deep-dive (if MKTG_X_AUTH_TOKEN configured)
+  For the top 2-3 clusters, invoke /mktg-x to read a representative thread:
+    /mktg-x https://twitter.com/<user>/status/<id>
+  → Lived-experience quotes for the page's pain section
+  → Three-beat vignette material (scenario / surprise / lesson)
+
+Step 5 — Map to page candidates
+  Each surviving cluster becomes either:
+    - A /for/<audience>/<verb> use-case page (Pattern B)
+    - A /playbooks/<topic> playbook opening hook (Pattern E)
+  Output schema: array of { cluster, sources[], page_type, draft_h1, draft_lede }
+```
+
+**Why this beats Ahrefs question data:** Ahrefs Questions reflects last 30-90 days of search-engine signal aggregated globally. `/last30days` reflects real conversations from the past 30 days, with engagement counts proving they aren't astroturfed. For B2B SaaS and developer-targeted products, the conversation signal leads the search-engine signal by 3-6 months.
+
+---
+
+## Recipe 2 — OSS Competitor Teardown
+
+For competitors that are open source (most agent / dev-tool / Claude-Code-skill competitors are), pull a full profile in one fan-out. Replaces single-source competitor research with a multi-API mosaic.
+
+**APIs chained:** `gh CLI` + `mcp__deepwiki__read_wiki_contents` + `company-research` skill + Exa `web_search_advanced_exa`
+
+```
+Step 1 — GitHub baseline (parallel fan-out)
+  gh repo view <owner/repo> --json description,homepageUrl,stargazerCount,forkCount,createdAt,updatedAt
+  gh api repos/<owner/repo>/contents/README.md --jq '.content' | base64 -d
+  gh api repos/<owner/repo>/contents/skills 2>/dev/null  # Claude Code skills
+  gh api repos/<owner/repo>/releases --jq 'length'      # release cadence
+  gh api repos/<owner/repo>/contributors --jq 'length'  # contributor count
+
+Step 2 — Deep documentation read
+  mcp__deepwiki__read_wiki_structure(repoName: "<owner/repo>")
+  → Get the wiki TOC; identify the architecture/getting-started sections
+  mcp__deepwiki__read_wiki_contents(repoName: "<owner/repo>", path: "<section>")
+  → Read the most informative sections (limit to 3-5 to avoid token bloat)
+
+Step 3 — Business context (company-research)
+  Invoke: /company-research "<competitor-brand-name>"
+  → Returns funding state, team size, positioning, customer list
+  → Note: only meaningful if the OSS project has a parent company
+
+Step 4 — Live SERP context
+  mcp__exa__web_search_advanced_exa(
+    query: "<competitor-brand> review",
+    numResults: 10,
+    enableSummary: true
+  )
+  → What 3rd-party reviewers say (the "weaknesses" most users cite)
+
+Step 5 — Consolidate into competitor profile
+  Output a single block per competitor:
+    {
+      "slug": "<canonical-slug>",
+      "github": { stars, contributors, last_release, release_cadence_days },
+      "positioning": "<from README intro>",
+      "pricing": "<free / freemium / paid + price points>",
+      "weaknesses_cited": ["<from Exa review summaries>"],
+      "differentiators": ["<what they emphasize>"],
+      "our_win_angles": ["<derived by comparison with our brand>"]
+    }
+```
+
+**Where it lands:** the competitor profile goes into `brand/competitors.md` (via the `competitive-intel` skill's writer agent `mktg-competitive-scanner`) AND into `.seo/keyword-research.json` per-competitor block for the alternatives pages.
+
+---
+
+## Recipe 3 — Outreach Prospect Discovery
+
+Turn a backlink target list into an actual person to pitch. Required for Phase 15 (listicle outreach) in the seo-machine roadmap.
+
+**APIs chained:** off-page-seo Recipe F output + Exa `people_search_exa` + Exa `web_search_advanced_exa` + `mktg-x` (optional)
+
+```
+Step 1 — Start from .seo/backlink-targets.json
+  Read the `listicles` and `guest_posts` arrays from the existing target list.
+  These have { domain, dr, url, topic }.
+
+Step 2 — Find the byline author per target
+  For each listicle URL:
+    mcp__exa__web_search_advanced_exa(
+      query: "site:<domain> author <topic>",
+      numResults: 5,
+      enableSummary: true,
+      summaryQuery: "Who wrote this article? What's their role and contact info?"
+    )
+  → Extract: { name, role, twitter/X handle, email pattern if visible }
+
+Step 3 — Enrich with people-research
+  For each name surfaced:
+    Invoke: /people-research "<name> + <company>"
+    → LinkedIn role, recent talks, social handles, areas of focus
+
+Step 4 — Pre-pitch context (optional X dive)
+  If mktg-x configured AND person has an active X handle:
+    /mktg-x https://twitter.com/<handle>
+  → Last 10 tweets → reveals their current focus / recent rants → angle for personalized pitch
+
+Step 5 — Output enriched prospects
+  Schema appended to .seo/backlink-targets.json:
+  {
+    ...listicle entry...,
+    "prospect": {
+      "name": "Jane Doe",
+      "role": "Senior Editor",
+      "linkedin": "...",
+      "x_handle": "@janedoe",
+      "recent_focus": "AI search optimization, December 2025 article series",
+      "pitch_angle": "Her recent series on AI overviews aligns with our /playbooks/ai-citation page; lead with that"
+    }
+  }
+```
+
+**The prospect block is consumed by:** `direct-response-copy` (cold-email mode) when /cmo chains into outreach email writing in Phase 15.
+
+---
+
+## Recipe 4 — Newcomer Surveillance (ongoing competitive radar)
+
+Replaces ad-hoc "I saw a new tool launched on Product Hunt" lookups with continuous monitoring. Refreshes `brand/competitors.md` automatically when new entrants appear.
+
+**APIs chained:** Exa Websets MCP + Exa `web_search_advanced_exa` + `/last30days` + `competitive-intel` skill
+
+```
+Step 1 — Create a webset for the category (one-time setup)
+  mcp__exa-websets__create_webset({
+    criteria: "AI marketing tools launched in the last 90 days targeting <persona>",
+    enrichments: [
+      { type: "company_basics" },
+      { type: "founder_lookup" }
+    ]
+  })
+  → Returns a webset ID. Persist to .seo/config.json as `surveillance_webset_id`.
+
+Step 2 — On every seo-machine Resume invocation
+  mcp__exa-websets__list_webset_items(websetId: "<id>", since: "<last-check>")
+  → Returns new entries since last check
+  Persist `last_surveillance_check` to .seo/config.json.
+
+Step 3 — Validate via /last30days for each new entry
+  For each new tool name:
+    Invoke: /last30days "<new-tool-name>"
+    → Confirms the tool has real organic signal (≥5 mentions in 30d)
+    → Filters out vaporware and stale listings
+
+Step 4 — Triage decision
+  For each surviving entry, /cmo runs the standard /competitive-intel check:
+    - Is this a direct overlap with our positioning? → propose alts page
+    - Is it adjacent? → propose comparison content
+    - Is it tangential? → log to brand/competitors.md "Watching" section, no immediate action
+
+Step 5 — Auto-refresh brand/competitors.md when triggered
+  When a new direct overlap clears triage, /cmo spawns `mktg-competitive-scanner`
+  on just that one competitor, which appends to brand/competitors.md without
+  rewriting the existing entries.
+```
+
+**Cadence:** weekly via `/loop 7d` or on every seo-machine Resume invocation (whichever comes first). Cheap because Exa Websets is incremental — only new items get processed.
+
+---
+
+## When to use which recipe
+
+| You want… | Recipe |
+|---|---|
+| Real audience complaints → use-case page hooks | 1 (Pain-Point Cluster Discovery) |
+| Full competitor profile in one pass | 2 (OSS Competitor Teardown) |
+| Actual humans to email for backlink outreach | 3 (Outreach Prospect Discovery) |
+| Continuous radar on new entrants in the category | 4 (Newcomer Surveillance) |
+
+For numeric volume/KD/TP data → see `references/exa-recipes.md` (the standard 7 recipes for keyword research).
+For the manual fallback when no MCPs are available → `references/manual-research.md`.
+
+---
+
+## Cost discipline
+
+Each compound recipe touches 3-5 APIs. Token discipline:
+
+| Recipe | Heavy API | Budget per run |
+|---|---|---|
+| 1 — Pain-Point | Exa `deep_search_exa` | ~$0.05 (deep) — run weekly, not per session |
+| 2 — OSS Teardown | DeepWiki contents | ~$0.02 per competitor — cache for 30 days |
+| 3 — Outreach Prospect | Exa Websets enrichments | ~$0.10 per 50 prospects — run once per off-page phase |
+| 4 — Newcomer Surveillance | Exa Websets list | ~$0.01 per check — run weekly |
+
+Cache to `.seo/<recipe>-cache.json` per recipe. Re-run only when:
+- Recipe 1: every 7 days (audience pain cycles weekly)
+- Recipe 2: every 30 days per competitor (competitive movement is slower)
+- Recipe 3: per off-page phase (one-shot)
+- Recipe 4: every 7 days (newcomer cadence)
+
+Total monthly research cost stays under $5 for a project running all four recipes on the recommended cadence — orders of magnitude cheaper than Ahrefs Pro ($249/mo) while covering signal Ahrefs doesn't have.

package/skills/seo-machine/references/exa-recipes.md

@@ -0,0 +1,260 @@
+# Exa-Native Research Cookbook
+
+The 7 recipes below replace the Ahrefs-only flow with mktg's native research stack: **Exa MCP** (primary) + **Firecrawl** (SERP scraping) + **gh CLI** (OSS competitor signal) + **last30days** (Reddit/X/HN aggregation) + **mktg-x** (auth-walled Twitter) + **company-research** / **people-research** skills (already in mktg's catalog).
+
+The trade vs Ahrefs: less numeric precision on volume/KD/TP, but live data, broader signal surface, no paid subscription gate, and recipes that compound multiple APIs in ways a single tool can't.
+
+For the Ahrefs path on projects where you *do* have a subscription, see the appendix at the bottom of this file.
+
+---
+
+## Recipe A — Domain baseline (DR proxy + topical authority)
+
+Replaces Ahrefs `site-explorer-domain-rating`. Builds a multi-signal DR estimate from public data.
+
+```
+1. mcp__exa__company_research_exa(companyName: "<user-brand>")
+   → existence + business profile + age signal
+2. mcp__exa__web_search_advanced_exa(
+     query: "site:<user-domain>",
+     numResults: 100,
+     type: "fast"
+   )
+   → indexed page count (Exa proxy for what Google has crawled)
+3. (If OSS) gh repo view <owner/repo> --json stargazerCount,forkCount,createdAt
+   → GitHub-stars-as-authority signal for tech-product competitors
+4. mcp__exa__web_search_advanced_exa(
+     query: "<brand-name> -site:<user-domain>",
+     numResults: 30
+   )
+   → unique referring domains mentioning the brand (DR proxy)
+```
+
+**DR estimate rules:**
+
+| Signal | DR estimate |
+|---|---|
+| < 50 indexed pages AND < 20 mentions | 0–10 (greenfield) |
+| 50–500 indexed pages, 20–100 mentions | 10–25 |
+| 500–5000 indexed pages, 100–500 mentions | 25–45 |
+| 5000+ indexed pages, 500+ mentions | 45+ |
+| GitHub OSS bonus: stars > 1k | +5 |
+| GitHub OSS bonus: stars > 10k | +10 |
+
+Record the DR estimate in `.seo/config.json` under `domain_rating_estimate`. Default to 10 (greenfield) when uncertain — under-estimating is safer than over-estimating (the KD cap stays conservative).
+
+---
+
+## Recipe B — Competitor reverse-lookup (what they rank for)
+
+Replaces Ahrefs `site-explorer-organic-keywords`. Exa surfaces the pages a competitor has indexed; we infer which keywords drive them.
+
+```
+1. mcp__exa__web_search_advanced_exa(
+     query: "site:<competitor-domain>",
+     numResults: 50,
+     type: "auto",
+     enableSummary: true,
+     summaryQuery: "What is this page about? What keyword would search for it?"
+   )
+   → top 50 indexed pages with AI-summarized intent
+2. For each top page that looks like an alts/compare/use-case target:
+   mcp__exa__web_search_advanced_exa(
+     query: "<inferred-keyword>",
+     numResults: 10,
+     enableSummary: true
+   )
+   → Verify the keyword is real (competitor actually ranks for it)
+3. (Bonus, for OSS competitors)
+   gh api repos/<owner/repo>/contents/website 2>/dev/null
+   gh api repos/<owner/repo>/contents/docs 2>/dev/null
+   → Read their actual marketing routes / docs structure
+```
+
+**Output schema (per competitor in `.seo/keyword-research.json`):**
+
+```json
+{
+  "competitor": "<slug>",
+  "indexed_pages_sampled": 50,
+  "high_value_pages": [
+    { "url": "...", "inferred_keyword": "...", "page_type": "alternatives|compare|use-case|playbook" }
+  ],
+  "win_angles_for_our_brand": [...]
+}
+```
+
+---
+
+## Recipe C — Use-case keyword sweep (the `/for/` and `/playbooks/` discovery loop)
+
+Replaces Ahrefs `keywords-explorer-matching-terms`. Three parallel passes for breadth.
+
+```
+PASS 1 — Use-case seed expansion via Exa deep search
+mcp__exa__deep_search_exa(
+  objective: "What are the most-searched 'for [audience]' and 'for [use-case]' queries in <product-category>?",
+  numResults: 12,
+  type: "deep"
+)
+
+PASS 2 — Google autocomplete via Firecrawl
+firecrawl scrape "https://www.google.com/complete/search?q=<seed>&output=toolbar"
+firecrawl scrape "https://www.google.com/complete/search?q=<seed>+for"
+firecrawl scrape "https://www.google.com/complete/search?q=<seed>+vs"
+firecrawl scrape "https://www.google.com/complete/search?q=best+<seed>"
+→ Real query suggestions from Google's autocomplete index
+
+PASS 3 — Pain-point mining (last30days skill)
+Invoke: /last30days "<product-category> problems"
+Invoke: /last30days "<persona> + <pain-point>"
+→ Returns Reddit + X + HN + YouTube + TikTok mentions with engagement counts
+→ Recurring complaints = keyword opportunities ("how to <unblock>")
+```
+
+**What "good" looks like for this recipe:**
+- 30–60 candidate keywords/topics per competitor
+- Filtered to KD ≤ DR + buffer (see DR-cap heuristic in keyword-research/references/dr-cap-and-confidence.md)
+- Grouped by parent topic (cluster header)
+- Tagged with `confidence: high|medium|estimated` per the 3-tier label rule
+
+---
+
+## Recipe D — Comparison volume (`/compare/[a]-vs-[b]` validation)
+
+Replaces Ahrefs `keywords-explorer-overview` on "[a] vs [b]". Confirms volume exists for a comparison page before writing it.
+
+```
+1. mcp__exa__web_search_advanced_exa(
+     query: "<a> vs <b>",
+     numResults: 10,
+     type: "fast"
+   )
+   → If SERP returns 5+ comparison-shaped results, demand exists.
+   → If 0–2 results, defer this comparison.
+
+2. firecrawl scrape "https://www.google.com/search?q=<a>+vs+<b>"
+   → Captures "About X,XXX results" line (rough volume proxy)
+   → Captures featured snippet (signals comparison-page winnability)
+
+3. mcp__exa__deep_search_exa(
+     objective: "Are people actively comparing <a> and <b> on Reddit, HN, X in the last 90 days?",
+     type: "deep"
+   )
+   → Confirms real audience interest, not just SEO ghost demand
+```
+
+**Decision rule:** ship a `/compare/[a]-vs-[b]` page when Pass 1 returns ≥5 results AND Pass 3 surfaces ≥3 organic mentions in the last 90 days. Otherwise defer.
+
+---
+
+## Recipe E — SERP saturation analysis (replaces Ahrefs DR/KD numbers)
+
+Replaces Ahrefs `keywords-explorer-overview` (KD field) and `serp-overview`. Builds a "is this winnable?" verdict from SERP composition.
+
+```
+1. mcp__exa__web_search_advanced_exa(
+     query: "<target-keyword>",
+     numResults: 10,
+     type: "auto"
+   )
+   → Top 10 results
+
+2. For EACH top-10 result, run:
+   mcp__exa__company_research_exa(companyName: "<domain-from-result>")
+   → Returns business signal (size, age, recognition) → DR proxy
+
+3. Classify each top-10 result:
+   | Result type | KD signal |
+   |---|---|
+   | Major SaaS landing page (G2, Capterra, established competitor) | High KD (60+) |
+   | Reddit / Quora / forum thread | LOW KD (10-30) — content gap |
+   | Listicle from DR 30-60 niche site | Medium KD (30-50) |
+   | Generic blog from unknown site | LOW KD (10-30) — winnable |
+   | YouTube video / TikTok at position 5+ | Medium KD + AI-citation surface |
+
+4. Compute SERP-derived KD:
+   - 5+ "high KD" results → KD 60+
+   - 5+ "medium KD" results → KD 30-50
+   - 3+ "low KD" results in top 5 → KD ≤ 20
+```
+
+**Output rule:** record both `serp_signal_kd` (derived) AND `confidence` (`high` if Pass 2 ran on every result, `medium` if sampled, `estimated` if SERP was small).
+
+---
+
+## Recipe F — Backlink prospecting (referring-domains via Exa)
+
+See `skills/off-page-seo/SKILL.md` for the canonical version. Quick reference:
+
+```
+mcp__exa__web_search_advanced_exa(
+  query: "<competitor-domain>",
+  numResults: 50
+  // Note: Exa indexes by content, not by linksTo metadata, so this
+  // surfaces pages mentioning the competitor — proxy for inbound link sources
+)
+
+Then for each top result:
+  - mcp__exa__company_research_exa(companyName: "<result-domain>")
+    → DR proxy + business profile (filters paid networks / PR wires)
+  - Classify into: directories / listicles / guest-post candidates
+```
+
+Output: `.seo/backlink-targets.json` (schema in `off-page-seo` SKILL).
+
+---
+
+## Recipe G — Content gap analysis (what competitors rank for that we don't)
+
+Replaces Ahrefs `site-explorer-organic-keywords` cross-referenced with the user's own indexed pages.
+
+```
+1. Recipe B output per competitor → list of inferred keywords they rank for
+2. mcp__exa__web_search_advanced_exa(
+     query: "site:<our-domain>",
+     numResults: 100
+   )
+   → Our indexed pages (what we already rank for)
+3. Compute set difference: their_keywords − our_keywords = the gap
+4. Filter gap to keywords within our DR-cap (per KD signal from Recipe E)
+5. Rank surviving gaps by traffic_potential proxy:
+   - 1st-page SERP demand (Recipe E) × intent fit (commercial > info)
+```
+
+**Output:** ranked content gap list with the proposed page slug + pattern (A/B/C/D/E) per gap entry. Becomes the input to the roadmap's pending phases.
+
+---
+
+## Cross-API compound recipes
+
+Single APIs are useful; chained APIs are differentiating. The big ones:
+
+- **Pain-point cluster discovery**: `/last30days` + Exa `deep_search_exa` + mktg-x targeted reading → produces the real complaints the audience has today (drives use-case page angles and playbook hooks)
+- **OSS competitor teardown**: `gh repo view` + `gh api repos/<r>/contents` + DeepWiki `read_wiki_contents` + Exa company research → full competitor profile in one fan-out
+- **Outreach prospect list**: Recipe F output + `mcp__exa__people_search_exa` per domain → finds the actual person to pitch (byline author, marketing lead, etc.) for the listicle outreach phase
+- **Newcomer surveillance**: `mcp__exa-websets__create_webset` with "new <category> tools 2026" criteria → ongoing competitive radar; ingest into `brand/competitors.md` updates
+
+Full details for these compound moves: `references/api-stack-recipes.md`.
+
+---
+
+## Ahrefs appendix (when you have a paid subscription)
+
+If `mcp__ahrefs__subscription-info-limits-and-usage` returns data, Ahrefs adds **numeric precision** on top of the Exa-stack recipes above. It does not replace them — Ahrefs has no equivalent for pain-point mining via `/last30days`, no `gh`-style OSS competitor signal, no built-in deep research.
+
+The minimal Ahrefs-augmented flow when available:
+
+| Exa-stack recipe | Ahrefs upgrade for that step |
+|---|---|
+| Recipe A — DR proxy | `site-explorer-domain-rating` returns the real Ahrefs DR (0–100). Replaces the proxy estimate. |
+| Recipe B — Competitor reverse-lookup | `site-explorer-organic-keywords` filtered `kd <= DR_CAP AND volume >= 30` returns numeric KD/volume per keyword. Replaces inferred-keyword step. |
+| Recipe C — Use-case sweep | `keywords-explorer-matching-terms` with seeds → KD/volume/TP per candidate. Replaces deep-search inference. |
+| Recipe D — Comparison volume | `keywords-explorer-overview` on "[a] vs [b]" → exact monthly volume. Replaces "About X results" proxy. |
+| Recipe E — SERP saturation | `serp-overview` → top 10 with DR per row, no per-domain `company_research_exa` lookups needed. |
+| Recipe F — Backlink prospecting | `site-explorer-referring-domains` filtered `DR >= 30 AND traffic_dofollow >= 100` → cleaner target list. |
+| Recipe G — Content gap | `site-explorer-content-gap` (cross-references multiple competitors at once) → faster than the set-difference computation. |
+
+When using Ahrefs, record `research_backend: "ahrefs+exa"` in `.seo/config.json` (both — Ahrefs for numerics, Exa-stack for breadth/qualitative signal). The compound-recipe stack (`api-stack-recipes.md`) still runs in parallel because Ahrefs doesn't replace it.
+
+**Not chained into mktg's ecosystem.** Ahrefs MCP requires a paid Ahrefs subscription. It is intentionally NOT in `CLAUDE.md`'s chained-in CLI table or registered as a catalog. If you want it, configure it in your own MCP config — mktg's recipes will detect it via the probe and switch paths automatically.

package/skills/seo-machine/references/manual-research.md

@@ -0,0 +1,73 @@
+# Manual Research Mode (Ahrefs MCP unavailable)
+
+When `mcp__ahrefs__*` tools aren't available, the skill still works — keyword data quality just drops. The goal of this fallback is to produce *good-enough* keyword research to populate the roadmap, not to pretend Ahrefs-grade data is there.
+
+Be honest with the user: "Ahrefs MCP isn't connected, so I'll work in manual mode. We'll have less precise volume/KD numbers, but we can still ship a roadmap. You can re-run with Ahrefs later to refine it."
+
+## Three substitution patterns
+
+### 1. User pastes data from their UI
+
+If the user has Ahrefs, Semrush, Mangools, Ubersuggest, or similar — ask them to paste:
+
+- Their domain's DR / DA / authority score
+- Top 20 competitor organic keywords (export CSV → paste here)
+- Striking-distance keywords (pos 5-20 in their GSC)
+- Comparison-keyword volumes for the pairs we want to target
+
+Parse the pasted CSV/text into the same `.seo/keyword-research.json` schema you'd build from Ahrefs. Validate columns; warn if KD or volume are missing.
+
+### 2. Web-search-based competitor reverse-lookup
+
+If the user has nothing:
+
+1. **Identify competitors** — ask the user, or pull from their pricing page / about page.
+2. **Web search for each competitor** — use the `firecrawl-search` or built-in WebSearch to query `"<competitor name> alternatives"` and `"<competitor name> vs"`. Look at:
+   - Autocomplete suggestions on Google (use a `google.com/search?q=` URL via firecrawl-scrape)
+   - "People also ask" boxes
+   - Related searches at the bottom of the SERP
+3. **Scrape top-3 ranking competitor-alternative pages** — these are your benchmark. Capture their H1/H2/comparison structure. Lets you understand the intent and quality bar.
+4. **Estimate volume crudely.** Use Google Trends (web search) for relative interest. A comparison keyword with steady Google Trends interest score 10+ is probably worth ≥30 monthly searches.
+
+Document estimated volumes as **ranges** (e.g. "100-500 monthly") and **mark as estimated** in `keyword-research.json` (`"source": "estimated"`). The user can refine later.
+
+### 3. Manual question-driven discovery
+
+Failing all the above, run a structured interview using `AskUserQuestion`:
+
+- "Who are your 3-5 most-known direct competitors?"
+- "What problems do customers tell you they're trying to solve when they sign up?"
+- "What tools did customers tell you they tried before yours?"
+- "What does your ideal customer's job title look like? Industry?"
+
+From those answers, generate hypothesis keywords:
+- Competitor names → `/alternatives/[competitor]` candidates
+- Stated problems → `/for/[use-case]` candidates
+- Industries / personas → `/for/[audience]` candidates
+
+Mark all as unvalidated and **encourage the user to validate volumes via free tools** before deep work:
+- Google Keyword Planner (free with any Google Ads account)
+- Mangools KWFinder free tier (5 queries/day)
+- Keywords Everywhere browser extension (paid, but cheap)
+
+## What's degraded vs Ahrefs mode
+
+Be explicit with the user about what's missing:
+
+| Capability | Ahrefs mode | Manual mode |
+|---|---|---|
+| Keyword volume | Precise monthly searches | Range estimate or "validate before targeting" |
+| Keyword difficulty (KD) | 0-100 score | Heuristic ("competitive" if top-3 are DR>60) |
+| Traffic potential | Per-keyword TP score | Not available — use volume × CTR estimate |
+| Striking-distance | GSC pos 5-20 via MCP | Requires user to paste GSC data manually |
+| Backlink target research | competitor referring-domains | Manual: who links to top-3 competitor results? |
+| SERP overview | Top 10 with DR per result | firecrawl-scrape the SERP page |
+
+## Roadmap impact
+
+In manual mode, the roadmap doc should:
+- Front-load the "validate this volume" step on every phase
+- Use 3-tier confidence labels per row: `high`, `medium`, `estimated`
+- Include a top-of-doc note: "Manual research mode — refine with Ahrefs when available."
+
+When Ahrefs MCP becomes available later, run an "Initialize: refresh" pass to upgrade `estimated` rows to real numbers.

package/skills/seo-machine/references/methodology.md

@@ -0,0 +1,87 @@
+# Methodology
+
+The principles below come from running this playbook across many production phases on a real site. They're not a framework; they're what consistently worked.
+
+## Core mental model
+
+SEO is a compounding asset. Pages need time to age in Google's index before they rank, and the day-0 crawl shapes how Google understands your product for months. So:
+
+1. **Publish early, refine later.** A thin page indexed now ages while you sleep. A perfect page indexed a month from now loses that month of compounding. The age signal is real and one-way.
+2. **Conversion intent before traffic intent.** Most founders publish blog posts first because they're easier. But comparison pages and alternative pages convert at 5-20x the rate of "what is X" blog posts, even at 1/10 the volume. Start with the bottom of the funnel.
+3. **Bet only where you can win.** DR < 10 cannot rank for KD > 30 in any reasonable timeframe. Target KD ≤ DR + 10 while your DR is still climbing. This is non-negotiable math.
+4. **Topical depth beats topical breadth.** Pick a niche slice (e.g. "Twitter monitoring for B2B SaaS") and own it. Don't fan out across 20 unrelated themes.
+
+## The publishing-order inversion (most founders do this backwards)
+
+The instinct is: write educational content first to build "authority," then add product pages later. This is wrong. The actual high-performing order is:
+
+| Order | Page type | Why |
+|---|---|---|
+| 1 | `/alternatives/[competitor]` | Highest conversion intent. User typing "hootsuite alternative" wants to switch tools, today. |
+| 2 | `/compare/[a]-vs-[b]` | High intent. User is deciding between two known tools — be the third option. |
+| 3 | `/for/[use-case]` and `/for/[audience]` | Mid intent. User has a job-to-be-done but doesn't know which tool fits. |
+| 4 | `/playbooks/[topic]` (long-form pillar) | Brand authority + AI-citation surface area. Lower direct conversion but huge inbound link draw and LLM mentions. |
+| 5 | `/blog/...` informational posts | Lowest direct conversion; useful for keyword sweep and internal linking after the conversion pages exist. (Out of scope for this skill — use `blog-article` skill.) |
+
+This sequence matches the 4 patterns this skill bundles. Phase 0 is technical foundations; everything after Phase 0 follows this order by default.
+
+## Five lessons from running this for real
+
+Each one is here because skipping it cost real time on the first try.
+
+### 1. Capture singular AND plural in one URL.
+
+For most competitor brands, `[brand] alternatives` (plural) has 2-3× the volume of `[brand] alternative` (singular). A single URL can rank for both if the H2 reads "Best [Brand] alternatives in 2026" and the meta title hints at plural. **Bake this in from page 1.** Retrofitting later cost an entire phase on the real project.
+
+### 2. The honesty section is non-negotiable.
+
+Every `/alternatives/[competitor]` page must list 3-4 things where the competitor genuinely wins. This is:
+- A brand signal (you're trustworthy)
+- A Google quality signal (genuine comparison > thinly-veiled vendor page)
+- A conversion signal (readers convert when they trust the comparison)
+
+Pages without honesty sections measurably underperform on rankings and conversion.
+
+### 3. Internal-link minimums are quality bars, not nice-to-haves.
+
+A new page nobody links to is invisible. Bake link counts into the quality gate per pattern:
+- `/alternatives/*` → ≥2 sibling alts, ≥1 feature, ≥1 tool
+- `/for/*` → ≥2 features, ≥2 tools, ≥1 sibling `/for/`
+- `/compare/*` → both alt pages + ≥1 `/for/` + pricing
+- `/playbooks/*` → ≥3 features, ≥2 tools, ≥2 `/for/`, ≥1 `/alternatives/`
+- **Every page reachable from ≥2 other pages.**
+
+Verify these mechanically (`scripts/link_audit.py`). Don't ship pages that fail.
+
+### 4. Word-count minimums catch lazy phase work.
+
+Soft floors per pattern:
+- `/alternatives/*`: ≥600 words of unique copy
+- `/for/*`: ≥800 words
+- `/compare/*`: ≥700 words
+- `/playbooks/*`: ≥2,500 words
+
+These aren't about Google word-count algorithms (there isn't one). They're about ensuring the page actually answers the searcher's question. A 200-word "[brand] alternative" page that's just a comparison table will lose to a 1,200-word page that explains tradeoffs.
+
+### 5. Striking-distance is the fastest win on any existing site.
+
+Pages currently ranking position 8-20 in GSC are one push from page 1. Adding 200-400 words of depth + 3-5 new internal links to a position-14 page routinely moves it to position 3-5, **tripling traffic** without writing a new page.
+
+**Run the striking-distance audit at Initialize time on any existing site.** It almost always surfaces 3-8 immediate wins that beat shipping new pages.
+
+## Why this skill writes a persistent roadmap
+
+Multi-phase SEO work spans weeks. Contexts compact, agents change, the user comes and goes. The roadmap doc (`docs/seo-machine.md`) is the **single source of truth** that survives:
+- Conversation compaction
+- New worktree / fresh Claude session
+- Different team members executing different phases
+- Long pauses between phases
+
+The tracker row update lands **in the same commit/PR as the phase work**, never after. This is so every PR review sees the doc-level status change alongside the code change, and the tracker stays in sync with `main` history.
+
+## What this skill explicitly does NOT do
+
+- **Write blog posts.** Use the `blog-article` skill for those. This skill scaffolds the strategy (which topics, what cluster structure) but hands off the writing.
+- **Generate images / OG cards.** Use the `og-image` or `feature-image` skill. This skill specifies which pages need OG images but doesn't make them.
+- **Submit to GSC / IndexNow / directories.** The off-page checklist is informational. The user (or future automation) does the submitting.
+- **Target keywords where DR < KD - 10.** It will refuse to add doomed phases to the tracker. This is a feature.