@jairodri/huckleberry-cli 1.0.2 → 1.1.0

package/skills/seo-machine/references/off-page.md

@@ -0,0 +1,123 @@
+# Off-Page Strategy (Backlinks + Distribution)
+
+On-page work (everything in the pattern references) only gets you so far. Without inbound links from other domains, even a perfect page caps out around DR + 20 in achievable KD targets. The off-page work expands that ceiling.
+
+This skill does **not** submit links anywhere on the user's behalf. It generates a prioritized checklist and a researched target list — the user (or the user's marketing team) does the outreach.
+
+## The starter stack (universal)
+
+Every new SaaS/app site should be in these by week 4. Most are free; all are worth a one-time submission.
+
+### Directories (just submit and check off)
+
+- **Product Hunt** — single biggest launch-day backlink + traffic source
+- **G2** — high-DR, becomes a destination for "[brand] reviews" searches
+- **Capterra / GetApp / Software Advice** (Gartner Digital Markets — same submission flow)
+- **SaaSHub**
+- **AlternativeTo** — DR 80+, list yourself as an alternative to your top 5 competitors
+- **Betalist** (if pre-launch or recently launched)
+- **Indie Hackers** — products section
+- **TopAlternatives.com / SimilarSiteSearch / Slant.co** — niche but useful
+- **Crunchbase** — even free profile gets DR pass-through
+
+### Community surfaces (selective)
+
+- **Reddit** — niche subreddits ONLY. Find them via Ahrefs site-explorer on `reddit.com` for your keywords. Engage genuinely; never just post a link.
+- **Slack/Discord communities** — for your audience. Join 3-5, contribute for 2 weeks before mentioning the product.
+- **Hacker News** — for technical products. Show HN posts can drive enormous traffic spikes; require a real launch story.
+
+### Founder outreach (the slow-burn channel)
+
+- **Founder link trades** with complementary (non-competitive) products. Reach out to 5-10 founders of products your audience also uses. Offer mutual blog mentions, "tools we love" pages, or guest posts.
+- **Guest posts on DR 30+ blogs** in your niche. Find them via Recipe F (competitor referring-domains). Pitch 1-2 strong posts per month.
+
+## Recipe F — researched target list
+
+Use Ahrefs MCP to surface high-value link opportunities your competitors already have.
+
+For each top-3 competitor:
+
+```
+mcp__ahrefs__site-explorer-referring-domains
+target: <competitor-domain>
+where: domain_rating >= 30 AND traffic_dofollow >= 100
+order_by: domain_rating:desc
+limit: 100
+```
+
+Then for each candidate domain, filter manually into buckets:
+
+| Bucket | Signal |
+|---|---|
+| **Directory candidates** | Site name matches "[category] directory", "best of [category]", "[category] tools", "alternatives to [tool]" |
+| **Listicle candidates** | Blog posts titled "Top X [category] in YYYY" — pitch yourself for inclusion |
+| **Guest-post candidates** | Looks like a blog (`*.com/blog/...` URLs), DR 30+, posts on your niche |
+| **Skip** | PR wires, paid networks, irrelevant niches, sites that link to *everyone* in the space |
+
+Save to `.seo/backlink-targets.json` as:
+
+```json
+{
+  "generated_at": "2026-MM-DD",
+  "directories": [
+    { "domain": "g2.com", "dr": 88, "url_to_submit": "https://www.g2.com/products/new", "competitor_uses": ["hootsuite", "buffer"] }
+  ],
+  "listicles": [
+    { "domain": "thedigitalprojectmanager.com", "dr": 65, "url": "https://...", "topic": "Best Twitter monitoring tools", "competitor_listed": "hootsuite" }
+  ],
+  "guest_posts": [
+    { "domain": "indiehackers.com/blog", "dr": 81, "topic_fit": "founder-led marketing" }
+  ]
+}
+```
+
+## Off-page phase template
+
+Add 2-4 off-page phases near the end of the tracker:
+
+```markdown
+### Phase N — Directory submissions (starter stack)
+
+**Why:** baseline backlinks from high-DR directories. Cap at 2-3 hours of submission work.
+
+**Scope:**
+
+- [ ] Product Hunt — schedule launch (separate launch-strategy work)
+- [ ] G2 — submit product page
+- [ ] Capterra — submit product page
+- [ ] SaaSHub
+- [ ] AlternativeTo — list as alternative to: hootsuite, buffer, sprout-social, agorapulse, later
+- [ ] Indie Hackers — claim product page
+- [ ] Crunchbase — basic profile
+
+**Files modified:** none — this is external work. Track status in `.seo/off-page-status.md`.
+```
+
+```markdown
+### Phase N+1 — Listicle outreach (top 10 targets)
+
+**Why:** "Top X [category]" listicles already rank for our target keywords. Getting added is faster than displacing them.
+
+**Targets (from .seo/backlink-targets.json):**
+
+1. example.com/best-twitter-monitoring-tools (DR 65)
+2. example.com/top-social-listening-tools-2026 (DR 72)
+3. ...
+
+**Action:**
+- [ ] For each, find the author via the byline or about page
+- [ ] Send a personalized note: short pitch + screenshot proof of value + link to demo
+- [ ] Track reply status in `.seo/off-page-status.md`
+
+**Verification:** 3+ listicles update to include the product within 60 days.
+```
+
+## What this skill explicitly does NOT do
+
+- **Auto-submit anything.** Submission flows often need real human review (G2 needs a screenshot + URL + verification email; Product Hunt needs a launch coordinator).
+- **Generate outreach emails.** Use the `cold-email` skill for that.
+- **Track ongoing referring-domain growth.** That's a weekly checking-in task the user owns; the skill just provides the initial target list.
+
+## Honest caveats
+
+Off-page work is slower and more uncertain than on-page work. A great alternatives page ranks within 30-90 days. A great backlink campaign might produce 3 useful links in the first month, 10 in three months. **Don't gate the on-page sprint on off-page progress.** Ship pages; queue outreach in parallel.

package/skills/seo-machine/references/patterns/alternatives.md

@@ -0,0 +1,176 @@
+# Pattern A — `/alternatives/[competitor]`
+
+The single highest-converting page type for SaaS SEO. User typing "[competitor] alternative" is one decision away from signing up for a replacement. Most sprints should start with this pattern and ship 5-15 of these before anything else.
+
+## Target keyword profile
+
+Each `/alternatives/[brand]` page must rank for at least TWO related keywords:
+
+1. **Singular** — `[brand] alternative` (e.g. "hootsuite alternative") — vol typically 100-400
+2. **Plural** — `[brand] alternatives` (e.g. "hootsuite alternatives") — vol typically 2-3× the singular
+
+A single URL captures both if the H2 reads "Best [Brand] alternatives in [Year]" and the meta title hints at plural. **Build for both from day 1.** Retrofitting is wasted work.
+
+Secondary keywords often capturable from the same URL (verify via SERP):
+- `alternative to [brand]` — vol typically 50-150
+- `[brand] pricing` — if their pricing is public and contentious (e.g. price hike, removed free plan)
+- `is [brand] free` — if there's a recent change to their free tier
+- `[brand] review` — captures evaluation-stage searchers
+
+## URL slug rules
+
+- lowercase, hyphenated. `sprout-social` not `sprout_social` and not `SproutSocial`
+- match the competitor's primary brand spelling. "Sprout Social" → `sprout-social`. "MeetEdgar" → `meetedgar` (no internal cap)
+- avoid pluralizing in the URL even though keywords are plural. `/alternatives/buffer` not `/alternatives/buffers`
+
+## Required data shape
+
+Every alternatives page renders from this payload. The shape is the same regardless of stack — only the serialization differs (Ruby hash, JSON, TypeScript interface, frontmatter).
+
+```typescript
+interface AlternativeData {
+  competitor_name: string                    // "Hootsuite" — display form, not slug
+  hero_eyebrow: string                       // e.g. "Hootsuite alternative"
+  hero_h1: string                            // "Looking for a Hootsuite alternative?"
+  hero_lede: string                          // 30-60 word subhead
+
+  // First H2 — CAPTURES PLURAL KEYWORD
+  table_h2: string                           // "Best Hootsuite alternatives in 2026"
+  table_lede: string                         // 30-50 words
+  comparison_rows: ComparisonRow[]           // ≥10 rows: feature + your-cell + competitor-cell
+
+  // Why switch — 4 reasons
+  switch_eyebrow: string                     // "Why switch"
+  switch_h2: string
+  switch_lede: string
+  switch_reasons: SwitchReason[]             // exactly 4 reasons, each ≥40 words
+
+  // HONESTY SECTION — NON-NEGOTIABLE
+  honesty_eyebrow: string
+  honesty_h2: string                         // "Where Hootsuite still wins"
+  honesty_lede: string
+  honesty_rows: HonestyRow[]                 // 3-4 honest tradeoffs, each ≥30 words
+
+  faq_h2: string
+  faqs: AlternativeFAQ[]                     // 4-6 Q/A
+
+  cta_h2: string
+  cta_lede: string
+}
+
+interface ComparisonRow {
+  feature: string
+  yours: { state: "yes" | "no" | "partial" | "text"; note?: string }
+  theirs: { state: "yes" | "no" | "partial" | "text"; note?: string }
+}
+
+interface SwitchReason {
+  icon: SwitchReasonIcon   // bolt | sparkle | check | info | shield | chart | clock | target | flame
+  title: string
+  body: string             // ≥40 words
+}
+
+interface HonestyRow {
+  feature: string
+  body: string             // ≥30 words explaining why they win here
+}
+
+interface AlternativeFAQ {
+  question: string
+  answer: string           // ≥40 words
+}
+```
+
+## Quality bar (verification gate)
+
+A phase is NOT done until all of these pass. Use `scripts/word_count.py` and `scripts/link_audit.py`.
+
+- [ ] **≥600 words of unique rendered copy.** Strip out JSX/Ruby syntax and recount. Anything under is thin.
+- [ ] **First H2 reads "Best [Brand] alternatives in [Year]".** Captures plural.
+- [ ] **Meta title ≤60 chars, includes brand + "Alternative" + a hint at free/price intent.**
+  - Example: `"Hootsuite Alternative — ReplySocial (free, $25/mo Pro)"`
+  - Bad: `"Hootsuite Alternative"` (wasted character budget, no pricing hook)
+- [ ] **Meta description ≤155 chars, has primary keyword + reason to click.**
+- [ ] **Comparison table has ≥10 rows.** Each row honest. Pricing must be one row (even if you do "Free" vs "$249/mo"). Free-tier presence/absence must be one row if either party has free or recently removed it.
+- [ ] **Honesty section present with 3-4 rows.** Acknowledge real competitor strengths. Don't fabricate weakness in yourself; fabricate nothing.
+- [ ] **4-6 FAQs.** At least one answers "is [brand] free" or "[brand] pricing" if there's any volume on those intents.
+- [ ] **Internal links from this page:** ≥2 sibling `/alternatives/*`, ≥1 `/features/*`, ≥1 `/tools/*` (or whatever the user's equivalent of "tools" is in their nav).
+- [ ] **Internal links TO this page:** ≥2 from existing pages. Common spots: homepage marketing block, sibling alts (link cluster), feature pages mentioning the competitor.
+- [ ] **JSON-LD schemas:**
+  - `BreadcrumbList` (auto from meta helper, but verify present)
+  - `FAQPage` (from the FAQ section)
+  - `SoftwareApplication` or `Product` representing the user's product
+- [ ] **OG image generated** (defer to `og-image` skill if not yet wired).
+- [ ] **Sitemap updated** with the new URL + today's lastmod. Never future-date.
+
+## Worked example (skeleton)
+
+```ruby
+# Rails+Inertia example. For other stacks see references/stacks/*.md
+{
+  competitor_name: "Hootsuite",
+  hero_eyebrow: "Hootsuite alternative",
+  hero_h1: "Looking for a Hootsuite alternative?",
+  hero_lede: "ReplySocial is the lightweight social media monitoring and engagement tool that does what most Hootsuite users actually need — without the $249/mo enterprise price tag or the deprecated free plan.",
+
+  table_h2: "Best Hootsuite alternatives in 2026",
+  table_lede: "We built ReplySocial after years of paying Hootsuite for features we never used. Here's how the two compare on the things our users actually care about.",
+  comparison_rows: [
+    { feature: "Free plan",
+      yours:  { state: "yes",  note: "Free forever for 1 X account" },
+      theirs: { state: "no",   note: "Discontinued in 2023" } },
+    { feature: "Starting price",
+      yours:  { state: "text", note: "$25/mo Pro" },
+      theirs: { state: "text", note: "$249/mo Professional" } },
+    # … 8+ more
+  ],
+
+  switch_reasons: [
+    { icon: "bolt",
+      title: "Reply in 30 seconds, not 5 minutes",
+      body: "ReplySocial's unified inbox surfaces every mention…" },  # ≥40 words
+    # 3 more
+  ],
+
+  honesty_eyebrow: "Honest tradeoffs",
+  honesty_h2: "Where Hootsuite still wins",
+  honesty_lede: "We won't pretend we've matched everything Hootsuite does. Here's where their product is still ahead.",
+  honesty_rows: [
+    { feature: "Multi-platform scheduling",
+      body: "Hootsuite supports scheduling to Instagram, TikTok, LinkedIn, and Facebook from one dashboard. ReplySocial is X-first and doesn't schedule to those platforms — if you need cross-platform scheduling, Hootsuite (or Buffer) is the better fit." },
+    # 2-3 more
+  ],
+
+  faqs: [
+    { question: "Why did Hootsuite end its free plan?",
+      answer: "Hootsuite discontinued its free plan in March 2023…" },
+    # …
+  ],
+}
+```
+
+## Sibling-link selection logic
+
+When picking ≥2 sibling alts to link to, prefer:
+1. **Closest substitute** — same audience, similar feature set (e.g. Buffer ↔ Hootsuite, both general SMM)
+2. **Adjacent category** — covers the next-most-likely query (e.g. Hootsuite ↔ Sprout Social, both enterprise-tier)
+3. **Up-funnel** — a more well-known competitor someone might also be searching (e.g. Buffer ↔ Hootsuite, both top-of-mind)
+
+Don't link to obscure alts just to hit the count. Each link should be useful to the reader.
+
+## Anti-patterns
+
+- **Fabricated honesty rows** ("they have a worse UI" is not honest, it's just a fluffy claim with no specifics). Real honest tradeoffs reference concrete features.
+- **Pricing rows with "Contact sales"** if the competitor publishes actual numbers. Use their actual numbers.
+- **"Best" claims in copy.** "ReplySocial is the best Hootsuite alternative" reads like a product page. Let the comparison speak; you provide structure and honesty.
+- **No FAQ schema.** Featured-snippet opportunity wasted.
+- **Sitemap lastmod in the future.** A red flag to crawlers. Use today's date.
+
+## Reference implementation
+
+This pattern's reference implementation is in the `reply-social` repo:
+- Hash entry: `app/controllers/marketing_controller.rb` — search for `ALTERNATIVES = {` then the `'hootsuite'` key
+- Component: `app/frontend/components/AlternativeLayout.tsx`
+- Routing: `get 'alternatives/:slug', to: 'marketing#alternatives_show'`
+
+For non-Rails stacks, see `references/stacks/<framework>.md`.

package/skills/seo-machine/references/patterns/compare.md

@@ -0,0 +1,105 @@
+# Pattern D — `/compare/[a]-vs-[b]`
+
+Third-party comparison pages between two competitors (neither is your product). The funnel:
+
+> User searches "[a] vs [b]" → lands on your page → reads your honest take → sees CTA at the bottom: "If both feel too heavy, try [your product] free."
+
+Volumes per page are usually small (30-500), but commercial intent is the **highest of any pattern** — these searchers are mid-decision and ready to evaluate options.
+
+## When to add a compare page
+
+Each page targets ONE canonical comparison. Add when:
+
+1. Both brands appear in the user's competitor list in `.seo/brand.md`
+2. Combined volume of "a vs b" + "b vs a" ≥ 30 (via Recipe D)
+3. KD ≤ DR + 10
+4. At least one search result in the current SERP for that comparison is a generic listicle (`forbes.com/best...`, `g2.com/categories/...`) — those are weak rankers you can displace with a focused page
+
+## URL slug rules
+
+- **Always alphabetical** for the canonical slug: `buffer-vs-hootsuite`, not `hootsuite-vs-buffer`.
+- Both directional searches ("buffer vs hootsuite" AND "hootsuite vs buffer") will rank for the same URL — Google understands the intent is identical.
+- Internal-link anchor text on each individual alt page should match the canonical slug, but the link text can be either direction ("compare Buffer vs Hootsuite" or "Hootsuite vs Buffer comparison" both fine).
+
+## Required data shape
+
+```typescript
+interface ComparisonData {
+  a_name: string                       // "Buffer"
+  b_name: string                       // "Hootsuite"
+
+  hero_h1: string                      // "Buffer vs Hootsuite: which is better in 2026?"
+  hero_lede: string                    // 40-80 words
+
+  // The verdict goes EARLY — searchers want the answer up front
+  verdict_h2: string                   // "Our take, in one paragraph"
+  verdict_body: string                 // ≥80 words
+
+  comparison_rows: ComparisonRow[]     // ~12 rows. 3 columns: feature / [A] / [B]
+
+  pricing_h2: string
+  pricing_a: { tier: string; price: string; notes: string }[]
+  pricing_b: { tier: string; price: string; notes: string }[]
+
+  winner_h2: string                    // "Pick [A] if… pick [B] if…"
+  winner_a_for: string[]               // 3-5 bullet criteria
+  winner_b_for: string[]
+
+  // The ONLY place your product shows up prominently
+  replysocial_aside_h2: string         // "Neither one fits? Here's what we'd suggest"
+  replysocial_aside_body: string       // 80-120 words; soft pitch with link to /pricing
+
+  faq_h2: string
+  faqs: { question: string; answer: string }[]  // 4-6
+
+  cta_h2: string
+  cta_lede: string
+}
+```
+
+## Quality bar
+
+- [ ] **≥700 words of unique rendered copy.**
+- [ ] **Verdict appears within the first viewport.** Don't make searchers scroll for the answer. The verdict is 80-150 words and states an opinion (with caveats).
+- [ ] **12+ comparison rows.** Each cell concrete and verifiable. Pricing rows must use the brands' actual published numbers.
+- [ ] **Pricing section uses live published pricing.** Re-fetch via web search if data is >60 days old.
+- [ ] **"Pick A if / pick B if" criteria are mutually exclusive and concrete.** "Pick Buffer if you prioritize simplicity" — vague. "Pick Buffer if you manage ≤5 accounts and don't need analytics deeper than 30 days" — concrete.
+- [ ] **Your product mention is honest and short** — 80-120 words, mentioned ONCE in the dedicated aside. Not sprinkled throughout. Google rewards genuine comparison; thinly-veiled vendor pages get demoted.
+- [ ] **Internal links:** to `/alternatives/[a]`, `/alternatives/[b]`, ≥1 relevant `/for/*`, your `/pricing`.
+- [ ] **Inbound links:** both `/alternatives/[a]` and `/alternatives/[b]` link here. Homepage compare-block if you have one.
+- [ ] **JSON-LD:** `BreadcrumbList`, `FAQPage`, `ComparisonReview` if you implement it (rare; FAQ schema is the high-leverage one).
+
+## The verdict paragraph — the most important section
+
+If a reader only reads one paragraph, this is it. It must:
+
+1. Open with the verdict — "Buffer is the better fit for X; Hootsuite is the better fit for Y."
+2. Acknowledge the close-call dimensions — "Both are strong on [shared strength]."
+3. State the situation-dependent factor — "The choice usually comes down to [budget / team size / specific feature]."
+4. Be honest. If they're nearly tied, say so. Don't manufacture differentiation.
+
+A good verdict reads like advice from a friend who's used both. A bad verdict reads like a "best of" listicle with hedge-everything language.
+
+## The "your product aside" — the soft pitch
+
+This is where your product appears. Rules:
+
+- **Tone: humble.** "If you tried both and felt they were overkill" is better than "Or skip both and try us — we're better."
+- **Trigger: when both don't fit.** Don't pitch as a primary recommendation. Pitch as the third option for a specific scenario.
+- **Length: 80-120 words.** Not more. Searchers came for "A vs B" — respect that.
+- **Honest about what you don't do.** If you don't match their scale or feature breadth, say so.
+
+## Anti-patterns
+
+- **Recency disclaimers without recency.** "As of January 2024" on a page written today and never updated will age badly. Either commit to keeping it fresh, or omit the date.
+- **"Our take" without an actual take.** Hedging on every dimension reads like AI-generated comparison content. Pick a side per dimension and defend it.
+- **Pricing tables with "Contact sales" when actual numbers are public.** Look them up. Searchers can.
+- **Both alts treated identically.** Compare pages need editorial direction — usually one tool wins for one audience, the other for a different audience. State it.
+
+## Reference implementation
+
+Reply-social repo:
+- Hash entry: `app/controllers/marketing_controller.rb` — `COMPARISONS = {`
+- Routing: `get 'compare/:slug', to: 'marketing#compare_show'`
+- Component: `app/frontend/components/ComparisonLayout.tsx`
+- Phase 3 PR (`#425`) is the proof-of-concept ship.

package/skills/seo-machine/references/patterns/playbooks.md

@@ -0,0 +1,106 @@
+# Pattern E — `/playbooks/[topic]` (long-form pillar)
+
+Long-form prose guides (2,500+ words) targeting commercial-investigation queries. These are the only pattern where you write long-form custom content per page rather than fan out templated data.
+
+## Why this pattern exists
+
+Three distinct jobs:
+1. **Brand authority.** A genuine 3,000-word guide on "B2B social media strategy" positions the author as a real practitioner, not a tool vendor.
+2. **AI-citation surface area.** LLMs (ChatGPT, Claude, Perplexity, Gemini) cite long-form guides when answering related queries. Long, well-structured playbooks get scraped into training and inference contexts way more than templated pages.
+3. **Inbound link draw.** Other writers cite playbooks. Almost nobody cites an alternatives page.
+
+The tradeoff: each playbook is 2-3 days of real writing work, vs ~4 hours for a `/alternatives/*` page. Ship 2-3 playbooks early in the sprint as pillar content; defer the rest until programmatic patterns are exhausted.
+
+## Target keyword profile
+
+- Volume 50-700 (small head terms)
+- KD ≤ DR + 15 (slightly more aggressive than templated patterns because long-form content can punch above its KD)
+- Strong "commercial investigation" or "informational with commercial sub-intent" — e.g. "b2b social media strategy" (people doing this are buying tools)
+- High traffic potential (≥500 ideal). The keyword cluster matters more than the head term.
+
+Avoid:
+- Pure informational queries with no buying intent ("what is social media")
+- Brand-direct queries (those are alternatives/compare territory)
+- Queries dominated by Wikipedia / how-to listicles in top 5 (you won't displace them at low DR)
+
+## URL slug rules
+
+- lowercase, hyphenated, descriptive
+- 2-5 words
+- Match common phrasing of the keyword: "b2b social media strategy" → `b2b-social-media-strategy` (not `b2bsocialmediastrategy` and not `b2b-social-strategy`)
+
+## Required data shape
+
+Playbooks are written as long-form components, not data hashes. Each playbook has:
+
+```typescript
+interface PlaybookMetadata {
+  slug: string
+  component: string                 // path to the React/Astro/Markdown component
+  headline: string                  // displays on listing
+  summary: string                   // 1-2 sentence summary
+  meta_title: string                // ≤60 chars
+  meta_description: string          // ≤155 chars
+  og_subtitle: string
+  date_published: string            // ISO
+  date_modified: string             // ISO; update when you edit
+  read_time_min: number             // honest estimate; ~140 wpm for operator content
+}
+
+interface PlaybookContent {
+  eyebrow: string
+  title: string
+  lede: string                      // 60-120 word intro
+  toc: TocEntry[]                   // section anchors
+  body: ReactNode | MarkdownAST     // the article itself
+  related: RelatedLink[]            // 4-6 cards: features, tools, /for/, /alternatives/
+  also_useful: InlineLink[]         // 3-6 secondary inline links
+  cta_h2: string
+  cta_lede: string
+}
+```
+
+## Quality bar (the hard one)
+
+Playbooks have the strictest quality gate of any pattern. **Most first-draft playbooks fail this gate and need rewriting.** Set the bar high upfront.
+
+- [ ] **≥2,500 words of original prose** in the article body. Strip JSX/markdown syntax before counting (`scripts/word_count.py --pattern=playbook`).
+- [ ] **8 sections minimum.** Each `<section id="..." className="scroll-mt-24">` with an anchor. No section under ~250 words.
+- [ ] **TOC ordered identically to section order.** Every section has a TOC entry.
+- [ ] **Vignettes/case studies have three beats each:** (1) scenario (what they did), (2) what surprised them (non-obvious outcome), (3) lesson. Single-paragraph vignettes allowed only if all three beats fit.
+- [ ] **Operational sections name actual numbers.** A "30-day plan" with "Week 2: connect monitoring" is a TOC entry, not a plan. Each step needs (a) "what done looks like" measurable outcome and (b) "if you're behind" branch.
+- [ ] **Tooling sections name what NOT to use.** Listing 4 good tools is generic. Listing 4 good tools + 4 categories of tools to avoid (with reasons) is differentiated.
+- [ ] **Internal links (in body, NOT sidebar):** ≥3 features, ≥2 tools, ≥2 `/for/*`, ≥1 `/alternatives/*`.
+- [ ] **Schema:** `Article` JSON-LD with author + datePublished + dateModified.
+- [ ] **Read-time honest.** 2,500 words ≈ 18 min for operator-audience skim. Don't lowball; readers calibrate trust against the displayed read-time.
+- [ ] **Cross-link inbound from ≥2 relevant existing pages.** Don't ship an orphan.
+
+## Section structure pattern
+
+Most successful playbooks follow this shape (8-12 sections, ≥250 words each):
+
+1. **The problem framing** — why this topic, why now, why this is hard
+2. **The mental-model section** — the framework or framing the rest of the playbook hangs on
+3. **3-5 "do this" sections** — concrete actions, with examples
+4. **2-3 "don't do this" sections** — anti-patterns, mistakes, what NOT to use
+5. **An operational plan** — week-by-week or step-by-step, with measurable outcomes per step
+6. **The closing section** — what success looks like, when to know you've made it, what to do next
+
+Don't slavishly copy this structure if a different one fits better, but if you're stuck, use it.
+
+## Writing style notes (specific to playbooks)
+
+- **Operator voice.** First-person plural ("we") is fine if the brand uses it elsewhere. Personal stories are welcome. Detached "best practices" voice loses to lived-experience voice.
+- **Concrete numbers everywhere.** "Many companies struggle" → "73% of B2B SaaS companies under 50 employees post less than once a week." If you don't have a source, use a *bracketed* range: "[somewhere between 50-80% of teams we've worked with]" and source it later.
+- **Counter-arguments inline.** When you make a strong claim, address the obvious counter-argument in the next paragraph. This is what differentiates 2,500 words of *thinking* from 2,500 words of *content*.
+- **No padding.** If a paragraph could be cut without losing meaning, cut it. 2,500 words of real content beats 4,000 words of fluff.
+
+## Reference implementation
+
+Reply-social repo:
+- Hash entry: `app/controllers/marketing_controller.rb` — `PLAYBOOKS = {`
+- Routing: `get 'playbooks/:slug', to: 'marketing#playbooks_show'`
+- Layout: `app/frontend/components/PlaybookLayout.tsx`
+- Reference playbook (highest-quality bar): `app/frontend/pages/Playbooks/B2bSocialMediaStrategy.tsx`
+
+Note `VignetteCard` and `WeekCard` components in that file — clone them for new playbooks.

package/skills/seo-machine/references/patterns/use-case.md

@@ -0,0 +1,109 @@
+# Pattern B+C — `/for/[use-case]` and `/for/[audience]`
+
+Two flavors of the same template, same data shape, same component. The difference is only in framing:
+
+- **Pattern B (use-case):** slug is a verb-or-noun describing what the user is trying to *accomplish* — `social-listening`, `competitor-monitoring`, `crisis-management`, `customer-support`.
+- **Pattern C (audience):** slug is the user's industry or role — `agencies`, `small-business`, `ecommerce`, `freelancers`, `creators`.
+
+Build the infra once; fan out per slug.
+
+## Why this pattern is high-leverage
+
+Pattern B/C pages target keywords with **the highest traffic-potential-to-volume ratio** in the entire roadmap. Examples from a real execution:
+
+- `social media tools for agencies`: vol 150, KD 9, **TP 34,000**
+- `competitor monitoring tool`: vol 150, KD 22, **TP 2,500**
+- `twitter mentions tracker`: vol 50, KD 6, **TP 2,100**
+
+These low-volume head terms gate access to massive long-tail clusters. A `/for/agencies` page that ranks for "social media tools for agencies" will also pick up dozens of long-tail variants and sub-queries — sometimes 50-100 additional ranking keywords per page.
+
+## Target keyword profile
+
+Pick ONE primary keyword per page. Mid-volume (50-500), mid-KD (≤DR+10), high TP (≥500 ideal, ≥150 acceptable).
+
+Good targets:
+- "[category] for [audience]" — e.g. "social media tools for agencies"
+- "[verb] [object] tool" — e.g. "competitor monitoring tool"
+- "[platform] [verb-noun]" — e.g. "twitter mentions tracker"
+
+Validate via SERP overview (Recipe G) before adding to the tracker. If top 5 are all DR > 60 mega-sites with template content, the KD score lied — skip.
+
+## URL slug rules
+
+- lowercase, hyphenated
+- noun or short noun phrase, not a full sentence
+- ≤4 words, ideally 1-2
+- `/for/agencies`, `/for/social-listening`, `/for/competitor-monitoring`
+
+## Required data shape
+
+```typescript
+interface ForData {
+  name: string                         // "Social Listening", "Agencies"
+  hero_eyebrow: string                 // "For agencies" or "For social listening"
+  hero_h1: string                      // e.g. "Social media monitoring built for agencies"
+  hero_lede: string                    // 40-80 words
+
+  pain_h2: string                      // "The agency reality"
+  pain_lede: string
+  pains: { title: string; body: string }[]   // 3-4 specific pains, ≥40 words each
+
+  solution_h2: string                  // "How ReplySocial helps"
+  solution_lede: string
+  solutions: { icon: SwitchReasonIcon; title: string; body: string }[]  // exactly 4
+
+  proof_h2?: string                    // optional but recommended
+  proof_lede?: string
+  proof?: { title: string; body: string }[]  // 2-3 proof points
+
+  related: {
+    features: { slug: string; title: string }[]  // ≥2 internal /features/ links
+    tools: { slug: string; title: string }[]     // ≥2 internal /tools/ links
+    siblings: { slug: string; title: string }[]  // ≥1 sibling /for/ link
+  }
+
+  faq_h2: string
+  faqs: { question: string; answer: string }[]  // 4-6
+
+  cta_h2: string
+  cta_lede: string
+}
+```
+
+## Quality bar
+
+- [ ] **≥800 words of unique rendered copy.**
+- [ ] **Hero H1 contains the primary keyword** (e.g. for `/for/agencies` targeting "social media tools for agencies", H1 should include "social media" + "agencies").
+- [ ] **Meta title ≤60 chars.** Format: "[Primary keyword] — [Product name]" or "[Primary keyword]: [outcome]".
+- [ ] **Meta description ≤155 chars.** Lead with the keyword, end with the conversion hook.
+- [ ] **3-4 pains, 4 solutions.** Each ≥40 words. Pains must be specific to the audience/use-case, not generic ("social media is hard" is generic; "agencies juggle 8-15 brands with no unified inbox" is specific).
+- [ ] **Internal links:** ≥2 features, ≥2 tools, ≥1 sibling `/for/*`.
+- [ ] **Inbound links:** ≥2 existing pages link to this new one. Common spots: homepage, related alts (audience-relevant), `/pricing` page if it mentions the audience.
+- [ ] **JSON-LD:** `BreadcrumbList`, `FAQPage`, `SoftwareApplication` representing your product. Optionally `Service` schema if framing as a service.
+- [ ] **No vague "for everyone" framing.** Audience-specific = better signals. If the page would apply equally to a 1-person solo creator and a 50-person agency, it's not pointed enough.
+
+## Pain section quality bar
+
+The most common failure mode in `/for/*` pages is generic pain copy. Each pain row should have:
+1. **A concrete trigger** (the moment the user notices the pain) — "Every Monday morning you open Hootsuite and see 47 unread mentions across 8 client accounts…"
+2. **The cost** (what they lose) — "…and your most important client expected a reply by 9am."
+3. **The current workaround** (what they do today) — "So you switch tabs frantically, copy-paste from a Google Sheet, and miss two anyway."
+
+Generic: "Agencies have a lot of social media to manage." Useless.
+Specific: "Agency social leads spend 11 hours a week triaging mentions across 8-15 client accounts in tools that don't share an inbox." Concrete + ownable.
+
+## Sibling-link selection
+
+For Pattern B (use-case): link to 1 other use-case in the same audience cluster (e.g. `social-listening` ↔ `competitor-monitoring`, both monitoring-flavored).
+
+For Pattern C (audience): link to 1 other audience that overlaps (e.g. `agencies` ↔ `freelancers`, both service-providers).
+
+If a sibling doesn't exist yet, queue an inbound-link update for when it ships (track in `.seo/link-inventory.md`).
+
+## Reference implementation
+
+Reply-social repo:
+- Hash entry: `app/controllers/marketing_controller.rb` — `USE_CASES = {`
+- Routing: `get 'for/:slug', to: 'marketing#for_show'`
+- Component: `app/frontend/components/ForLayout.tsx`
+- The `/for/agencies` page is the gold-standard reference — TP 34k on KD 9 was the proof-of-concept that validated this pattern.