@jairodri/huckleberry-cli 1.0.2 → 1.1.0

package/skills/seo-machine/references/stacks/rails-inertia.md

@@ -0,0 +1,99 @@
+# Stack adapter — Rails + Inertia + React
+
+This adapter mirrors the reference implementation from the repo this skill was built against. It's the most opinionated adapter because it's been pressure-tested over 49 phases.
+
+## Conventions to use
+
+- **Routes:** dispatch-by-slug. `get 'alternatives/:slug', to: 'marketing#alternatives_show'` — one controller action serves many pages from a single hash.
+- **Data lives on the controller** as a frozen Ruby hash constant (e.g. `MarketingController::ALTERNATIVES`). Slug → payload. **No database tables for marketing copy** unless the user already has a CMS pattern.
+- **Components in `app/frontend/components/`**, named `[Pattern]Layout.tsx`. One layout per pattern.
+- **Page wrappers in `app/frontend/pages/[Pattern]/Show.tsx`** — thin wrappers that hydrate the layout from props.
+- **Sitemap** in `app/views/tools/sitemap.xml.erb` (or wherever the sitemap lives) — loop over each pattern's hash and emit `<url>` entries.
+- **SSR enabled** for marketing controllers via `inertia_config ssr_enabled: true` if the app's main controller has SSR disabled. **Marketing pages MUST be SSR or full-HTML so search and AI crawlers see content.**
+
+## Adding a new alternative (Pattern A) — concrete steps
+
+1. **Append to `MarketingController::ALTERNATIVES`** — add an entry with the slug as the key. Reference the existing `'hootsuite'` entry as the gold-standard structure.
+2. **Append to one cluster in `MarketingController::ALTERNATIVES_CLUSTERS`** — without this, the new alt won't appear on `/alternatives` directory page.
+3. **Internal-link updates:**
+   - In ≥2 sibling alt entries' copy, add a reference to the new alt
+   - In `MarketingLayout.tsx`'s "Compare" footer block, swap in the new alt if it's high-priority (replace a lower-volume entry)
+4. **Smoke test:** `bin/rails test test/controllers/alternatives_smoke_test.rb` enforces 1:1 coverage between `ALTERNATIVES` and `ALTERNATIVES_CLUSTERS`.
+5. **Sitemap auto-updates** — `app/views/tools/sitemap.xml.erb` loops `ALTERNATIVES.each_key`.
+6. **Bump `ToolsController::SITEMAP_LASTMOD`** to today's date.
+
+## Adding a new use-case/audience (Pattern B/C) — concrete steps
+
+1. **Append to `MarketingController::USE_CASES`** — slug → `ForData` hash
+2. **Internal-link updates:**
+   - In ≥1 sibling `/for/*` entry's `related.siblings`, add the new slug
+   - In ≥2 `/features/*` entries' related-links, add the new `/for/*`
+3. **Sitemap auto-updates**
+
+## Adding a new comparison (Pattern D) — concrete steps
+
+1. **Append to `MarketingController::COMPARISONS`** with alphabetical slug
+2. **Internal-link updates:**
+   - In `MarketingController::ALTERNATIVES['a']` and `['b']` entries, add a "compare to [b]" link
+   - In one relevant `/for/*` entry (the use-case both compete in), add a related-link to the new compare
+3. **Sitemap auto-updates**
+
+## Adding a new playbook (Pattern E) — concrete steps
+
+1. **Append to `MarketingController::PLAYBOOKS`** with metadata
+2. **Create `app/frontend/pages/Playbooks/[PascalCaseSlug].tsx`** — clone `B2bSocialMediaStrategy.tsx` and rewrite the body
+3. **Internal-link updates:**
+   - In ≥2 sibling playbooks' `related` arrays, add the new one
+   - In `/playbooks` index, ensure auto-discovery works (it should via the hash)
+4. **Sitemap auto-updates**
+
+## Meta tags + schema
+
+Use the existing helper pattern. If `meta_tags_helper.rb` exists:
+
+```ruby
+set_meta_tags(
+  title: data[:meta_title],
+  description: data[:meta_description],
+  canonical: alternatives_show_url(slug: slug),
+  open_graph: { type: 'website', image: og_image_for(slug) }
+)
+add_software_application_schema  # before_action sets this for marketing controllers
+faqpage_jsonld(data[:faqs]) if data[:faqs].present?
+```
+
+If the helper doesn't exist yet, this is **Phase 0** work — build the helper before any pattern phase.
+
+## File-write checklist for any phase
+
+Before declaring a phase complete:
+
+- [ ] Hash entry added (`ALTERNATIVES`, `USE_CASES`, `COMPARISONS`, or `PLAYBOOKS`)
+- [ ] Cluster appended (alternatives only)
+- [ ] Sibling page references added (≥2 spots)
+- [ ] `SITEMAP_LASTMOD` bumped to today
+- [ ] `test/controllers/*_smoke_test.rb` passes if present
+- [ ] `bundle exec rubocop -a` clean
+- [ ] Local server check: visit the URL, view-source confirms full SSR HTML (not just a React shell)
+- [ ] `docs/seo-machine.md` tracker row updated in the same commit
+
+## SSR sanity check (every phase)
+
+After adding a page, visit it locally and run `curl -s http://localhost:3000/<url> | grep -c "<h1"`. If the result is 0, SSR is broken for that route — check:
+
+1. Controller has `inertia_config ssr_enabled: true`
+2. `puma.rb` includes `plugin :inertia_ssr`
+3. `public/vite-ssr/ssr.js` was built (`bundle exec rails assets:precompile` in dev creates this)
+4. Browser-only code (`window`, `document`) at module-init is wrapped in `if (!import.meta.env.SSR)`
+
+A page that renders client-side but blanks in `curl` won't be indexed correctly.
+
+## When this adapter doesn't fit perfectly
+
+If the project is Rails but NOT Inertia (e.g. Rails + Hotwire/Turbo + ERB), most of this still applies — the difference is:
+
+- Skip the React component step
+- Build ERB partials in `app/views/marketing/alternatives/show.html.erb` instead
+- Use `content_tag` helpers or partials for the comparison table
+
+Switch to `rails-erb.md` for that flow.

package/skills/seo-machine/references/striking-distance.md

@@ -0,0 +1,116 @@
+# Striking-Distance Audit
+
+The fastest win on any existing site. Pages currently ranking position 5-20 in GSC are one push from page 1. Boosting a position-14 page to position-3 typically **triples its traffic** without writing a new page.
+
+## Eligibility
+
+This audit only applies to sites with existing GSC data. For greenfield (≤14 days old, no rankings yet), skip — there's no striking-distance to find.
+
+## Recipe
+
+```
+mcp__ahrefs__gsc-keywords
+project_id: <project_id>
+date_from: <90-days-ago>
+date_to: <today>
+where: position >= 5 AND position <= 20 AND impressions >= 50
+order_by: impressions:desc
+limit: 100
+```
+
+Then for each high-value keyword, find the page that owns it:
+
+```
+mcp__ahrefs__gsc-pages
+project_id: <project_id>
+date_from: <90-days-ago>
+date_to: <today>
+where: position >= 5 AND position <= 20
+order_by: clicks:desc
+limit: 50
+```
+
+Cross-reference. Each (page, keyword) pair is a candidate boost phase.
+
+## Prioritization
+
+Rank candidates by **estimated traffic-at-position-3 minus current-traffic**, using rough CTR-by-position:
+
+| Position | CTR |
+|---|---|
+| 1 | 28-32% |
+| 2 | 14-17% |
+| 3 | 9-11% |
+| 4 | 6-8% |
+| 5 | 5-6% |
+| 6-10 | 2-4% |
+| 11-15 | 1-2% |
+| 16-20 | <1% |
+
+So a keyword at position 14 with 1,000 monthly impressions currently gets ~10 clicks/month. At position 3 it would get ~100/month — a 10x bump on a single phase of work.
+
+Skip candidates where:
+- Impressions < 50/month (not enough signal)
+- Top 3 results are all DR > 60 with deep, well-optimized content (you won't displace them)
+- The page already has 1,500+ words on the topic (out of easy depth-adds)
+
+## Boost-phase scope
+
+A striking-distance boost phase is **NOT writing a new page**. It's amplifying an existing one. Specifically:
+
+1. **Add 200-400 words of depth** to the section where the target keyword appears. Common amplifiers:
+   - Add an FAQ if missing (FAQPage schema is a featured-snippet magnet)
+   - Expand a thin section with a worked example
+   - Add a counter-argument paragraph if the existing content is one-sided
+   - Add a how-to subsection if the keyword is procedural
+2. **Add 3-5 new internal links to this page** from related pages. The pages most likely to send useful link equity:
+   - Other pages already ranking for related queries (find via GSC)
+   - Sibling pattern pages (other `/for/*`, other `/alternatives/*`)
+   - Recent playbooks or blog posts on the same topic
+3. **Update meta title/description** if it doesn't include the target keyword prominently. Bump the title's keyword towards the front.
+4. **Update `lastmod` in sitemap** to today. The freshness signal helps the recrawl pick up the changes.
+
+## Phase template for striking distance
+
+```markdown
+### Phase N — Boost /<existing-url> for "<target keyword>"
+
+**Why:** currently ranks position 14 for "<target keyword>" (vol 500, KD 18). Position 3 captures an estimated +40 clicks/month with content depth + 3 new internal links from related pages.
+
+**Scope:**
+
+1. Add a 250-word FAQ section to /<existing-url> answering "<related question>"
+2. Add `FAQPage` JSON-LD with the new FAQ
+3. Add internal links from:
+   - `/<related-page-1>` (anchor: "<anchor text>")
+   - `/<related-page-2>` (anchor: "<anchor text>")
+   - `/<related-page-3>` (anchor: "<anchor text>")
+4. Bump meta title to lead with "<target keyword>"
+5. Bump sitemap lastmod to today
+
+**Files modified:**
+- (stack-specific)
+
+**Verification:**
+- [ ] Page has the new FAQ section (200+ words)
+- [ ] `FAQPage` JSON-LD validates
+- [ ] 3 new inbound links from named pages
+- [ ] Meta title leads with target keyword and is ≤60 chars
+- [ ] After 14 days, GSC shows position improvement (track manually)
+```
+
+## When to schedule striking-distance phases
+
+Front-load them in the tracker. They're faster than new-page phases (a boost typically takes 1-3 hours vs 4-8 for a new page), use existing link equity, and produce measurable traffic gains within 7-21 days.
+
+Suggested ordering on existing sites:
+
+1. Phase 0 — Technical foundations
+2. Phases 1-5 — Striking-distance boosts (the top 5 by estimated traffic gain)
+3. Phases 6+ — New pattern pages, ordered by traffic potential
+
+## Re-running the audit
+
+GSC data is a lagging indicator. Re-run striking-distance every 30 days during the sprint — new keywords enter position 5-20 every cycle as you ship content, and old ones either graduate to page 1 (success!) or fall off (worth investigating).
+
+If a keyword was at position 8 last month and is now position 12, that's regression. Investigate before boosting — usually means a competitor shipped fresh content on the same query.

package/skills/seo-machine/references/technical-audit.md

@@ -0,0 +1,153 @@
+# Technical Foundations Audit (Phase 0)
+
+Always Phase 0. Always. Day-0 crawl shapes how Google understands the site for months — fixing technical foundations later is harder than getting them right the first time.
+
+Four checks: **sitemap**, **robots.txt**, **meta tag uniqueness**, **schema markup**. Run them in order.
+
+Use `scripts/tech_audit.py` for the deterministic parts. The script outputs a JSON report you can read and translate into Phase 0 tasks for the roadmap.
+
+## Check 1 — sitemap.xml
+
+**Goal:** every indexable URL appears in a valid sitemap, with reasonable lastmod, submitted to GSC.
+
+Run:
+
+```bash
+# Local sitemap exists?
+find . -name 'sitemap*.xml*' -not -path './node_modules/*' -not -path './.git/*' | head
+
+# Production sitemap reachable?
+curl -sI https://<domain>/sitemap.xml | head -1
+curl -s https://<domain>/sitemap.xml | xmllint --noout - && echo "Valid XML"
+```
+
+If using Ahrefs MCP:
+```
+mcp__ahrefs__site-audit-issues
+filter: category=indexing AND severity=high
+```
+
+Findings to convert into Phase 0 tasks:
+
+| Finding | Phase 0 task |
+|---|---|
+| No sitemap at all | Generate sitemap (stack-specific path: `app/views/tools/sitemap.xml.erb` for Rails, `app/sitemap.ts` for Next.js, `@astrojs/sitemap` for Astro) |
+| Sitemap exists but missing key URLs | Patch the sitemap generator to include them |
+| `lastmod` dates in the future | Bump to today — future dates are a crawler red flag |
+| `lastmod` dates stale (>180 days) on actively-updated pages | Tie `lastmod` to a build constant that bumps per deploy |
+| Sitemap not referenced in `robots.txt` | Add `Sitemap: https://<domain>/sitemap.xml` to robots.txt |
+| Sitemap not submitted to GSC | Add a checklist item in the off-page section |
+
+## Check 2 — robots.txt + canonicals
+
+```bash
+# robots.txt exists and allows /?
+curl -s https://<domain>/robots.txt
+
+# Spot-check canonical tags on existing marketing pages
+curl -s https://<domain>/ | grep -E 'rel="canonical"' | head
+```
+
+If using Ahrefs MCP:
+```
+mcp__ahrefs__site-audit-issues
+filter: category=crawlability OR category=canonical
+```
+
+Common failures:
+
+- **`User-agent: * Disallow: /`** in robots.txt (often from production-template defaults). Fix immediately.
+- **Marketing routes blocked by accident.** Things like `/marketing/*` being in robots disallow because of a templating leftover.
+- **Missing canonical tags** on pages that have query-param variants (sort, filter, pagination). Add canonical to the param-stripped URL.
+- **Conflicting canonicals** — page points its canonical to a different URL, but that other URL doesn't canonical-point back consistently. Fix one direction.
+- **Trailing-slash inconsistency.** `/alternatives/hootsuite` vs `/alternatives/hootsuite/` — pick one, redirect the other, canonical to the chosen one.
+
+## Check 3 — meta tag uniqueness + length
+
+For each page in the existing sitemap, fetch and extract `<title>` + `<meta name="description">`. Cross-reference.
+
+```bash
+# Get all URLs from sitemap
+curl -s https://<domain>/sitemap.xml | grep -oE '<loc>[^<]+' | sed 's/<loc>//' > /tmp/urls.txt
+
+# Fetch each and capture title + meta description
+while read url; do
+  echo "=== $url ==="
+  curl -s "$url" | grep -E '<title>|name="description"' | head -2
+done < /tmp/urls.txt > /tmp/meta-audit.txt
+```
+
+If using Ahrefs MCP:
+```
+mcp__ahrefs__site-audit-issues
+filter: category=content AND (issue=duplicate_title OR issue=duplicate_description OR issue=title_too_long OR issue=description_too_long)
+```
+
+Failures to fix in Phase 0:
+
+- **Duplicate titles across pages.** Each indexable URL needs a unique title.
+- **Duplicate descriptions.** Same rule. CMS-default descriptions are a common offender.
+- **Title >60 chars.** Get truncated in SERPs.
+- **Description >155 chars.** Same.
+- **Missing description.** Google auto-generates one; usually worse than what you'd write.
+- **Multiple H1 tags on a single page.** Should be exactly 1.
+
+## Check 4 — schema markup
+
+Spot-check what JSON-LD currently exists on existing marketing pages:
+
+```bash
+curl -s https://<domain>/ | grep -oE 'application/ld\+json"[^<]*</script' | head
+```
+
+Common findings:
+- No JSON-LD anywhere → add `SoftwareApplication` to the homepage as table-stakes
+- Only `BreadcrumbList` → fine for nav but missing the page-type schemas
+- Schemas exist but invalid (wrong `@type`, missing required fields) — validate via https://validator.schema.org/
+
+Per-page-type schema requirements this skill enforces from Phase 1 onward:
+
+| Page type | Required schemas |
+|---|---|
+| Homepage | `SoftwareApplication` (or `Product`), `Organization` |
+| `/alternatives/[slug]` | `SoftwareApplication`, `BreadcrumbList`, `FAQPage` |
+| `/for/[slug]` | `SoftwareApplication`, `BreadcrumbList`, `FAQPage` |
+| `/compare/[slug]` | `BreadcrumbList`, `FAQPage` |
+| `/playbooks/[slug]` | `Article`, `BreadcrumbList` |
+| `/blog/[slug]` | `Article`, `BreadcrumbList` |
+| `/tools/[slug]` | `SoftwareApplication` or `WebApplication`, `BreadcrumbList` |
+
+If the user's stack doesn't already have a schema helper, Phase 0 builds one before any pattern phase runs. A helper saves rewriting the same JSON-LD boilerplate 30 times.
+
+## Reporting findings
+
+After running all four checks, write a Phase 0 entry to the roadmap that looks like:
+
+```markdown
+### Phase 0 — Technical foundations
+
+**Why:** the day-0 crawl shapes Google's understanding of the site for months. Fix these before shipping content.
+
+**Scope:**
+
+1. Generate sitemap.xml at `<stack-appropriate-path>` (currently missing)
+2. Add `Sitemap: https://<domain>/sitemap.xml` to robots.txt
+3. Fix 3 duplicate `<title>` tags on `/`, `/pricing`, `/about`
+4. Build `meta_tags_helper` with `add_software_application_schema` and `faqpage_jsonld` (or stack-equivalent)
+5. Add `SoftwareApplication` JSON-LD to homepage
+6. Submit sitemap to Google Search Console + Bing Webmaster Tools
+
+**Files modified:**
+- (auto-populate based on stack)
+
+**Verification:**
+- [ ] curl sitemap.xml returns 200 + valid XML
+- [ ] robots.txt does not disallow marketing routes
+- [ ] No duplicate titles in sitemap-listed URLs
+- [ ] Schema validator returns 0 errors on homepage
+- [ ] Sitemap submitted in GSC (manual; check off when done)
+```
+
+## What NOT to include in Phase 0
+
+Don't try to fix Core Web Vitals or page speed in Phase 0. Those are real issues but they're not foundational; they're optimization. Run a Lighthouse audit in a separate phase after the foundations are right. Otherwise Phase 0 sprawls into a month-long performance pass.

package/skills/seo-machine/scripts/link_audit.py

@@ -0,0 +1,265 @@
+#!/usr/bin/env python3
+"""
+Internal-link audit for SEO-sprint pages.
+
+Counts internal links pointing TO a given slug AND FROM a given slug,
+and asserts they meet per-pattern minimums.
+
+Usage:
+    python link_audit.py --slug hootsuite --pattern A --root .
+    python link_audit.py --pattern A --root . --slug-list slug1,slug2
+    python link_audit.py --orphan-check --root .
+
+The script scans common file extensions for links matching:
+  /alternatives/<slug>
+  /for/<slug>
+  /compare/<slug>
+  /playbooks/<slug>
+  /features/<slug>
+  /tools/<slug>
+
+It does not try to understand framework-specific link helpers. Direct URL
+strings or href= attributes are what it counts. If your code uses a helper
+like `alternatives_show_url(slug)`, this script will undercount — bias
+towards URL strings or augment the script's regex to your helper's pattern.
+"""
+
+import argparse
+import re
+import sys
+from collections import defaultdict
+from pathlib import Path
+
+# Patterns: how many links are required FROM each page-type, broken down by link-target-type
+OUTBOUND_REQUIREMENTS = {
+    "A": {  # /alternatives/[slug]
+        "alternatives": 2,
+        "features":     1,
+        "tools":        1,
+    },
+    "B": {  # /for/[slug] (use-case)
+        "features":     2,
+        "tools":        2,
+        "for":          1,
+    },
+    "C": {  # /for/[slug] (audience) — same as B
+        "features":     2,
+        "tools":        2,
+        "for":          1,
+    },
+    "D": {  # /compare/[slug]
+        "alternatives": 2,  # both /alternatives/[a] and /alternatives/[b]
+        "for":          1,
+        "pricing":      1,
+    },
+    "E": {  # /playbooks/[slug]
+        "features":     3,
+        "tools":        2,
+        "for":          2,
+        "alternatives": 1,
+    },
+}
+
+INBOUND_MINIMUM = 2  # every page must be linked to from at least 2 other pages
+
+LINK_REGEXES = {
+    "alternatives": re.compile(r"/alternatives/([a-z0-9][a-z0-9-]*)"),
+    "for":          re.compile(r"/for/([a-z0-9][a-z0-9-]*)"),
+    "compare":      re.compile(r"/compare/([a-z0-9][a-z0-9-]*)"),
+    "playbooks":    re.compile(r"/playbooks/([a-z0-9][a-z0-9-]*)"),
+    "features":     re.compile(r"/features/([a-z0-9][a-z0-9-]*)"),
+    "tools":        re.compile(r"/tools/([a-z0-9][a-z0-9-]*)"),
+    "pricing":      re.compile(r"/pricing(?:[/'\"\s>?])"),
+}
+
+DEFAULT_EXTENSIONS = {".tsx", ".ts", ".jsx", ".js", ".astro", ".mdx", ".md", ".erb", ".rb", ".html", ".vue", ".svelte"}
+
+
+def scan_links(root: Path, exclude: list = None):
+    """Return {file_path: {target_type: [slugs]}} for every link found."""
+    found = defaultdict(lambda: defaultdict(list))
+    excludes = exclude or []
+    for path in root.rglob("*"):
+        if not path.is_file():
+            continue
+        if path.suffix not in DEFAULT_EXTENSIONS:
+            continue
+        if any(part in path.parts for part in (".git", "node_modules", "dist", "build", ".next", "tmp", "public")):
+            continue
+        if any(str(path).endswith(ex) for ex in excludes):
+            continue
+        try:
+            text = path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        for target_type, rx in LINK_REGEXES.items():
+            for m in rx.finditer(text):
+                slug = m.group(1) if rx.groups else "_pricing"
+                found[str(path)][target_type].append(slug)
+    return found
+
+
+def assert_outbound(slug: str, pattern: str, root: Path):
+    """For a given (slug, pattern), check that the page file linking from it meets requirements."""
+    if pattern not in OUTBOUND_REQUIREMENTS:
+        print(f"unknown pattern: {pattern}", file=sys.stderr)
+        return False
+
+    pattern_dir_map = {"A": "alternatives", "B": "for", "C": "for", "D": "compare", "E": "playbooks"}
+    page_kind = pattern_dir_map[pattern]
+    # Heuristic: page-defining file is one whose path contains the slug AND the pattern dir
+    candidates = []
+    for path in root.rglob("*"):
+        if not path.is_file() or path.suffix not in DEFAULT_EXTENSIONS:
+            continue
+        if slug in path.stem or slug in str(path):
+            if page_kind in str(path).lower() or pattern == "E":
+                candidates.append(path)
+    # For data-driven files (single hash with all slugs), also check the file that *defines* this slug
+    for path in root.rglob("*"):
+        if not path.is_file() or path.suffix not in {".rb", ".ts", ".tsx", ".js"}:
+            continue
+        try:
+            text = path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        if f"'{slug}'" in text or f'"{slug}"' in text:
+            if page_kind in text.lower() or slug in text:
+                if path not in candidates:
+                    candidates.append(path)
+
+    if not candidates:
+        print(f"✗ Could not locate the page definition file for slug={slug} pattern={pattern}", file=sys.stderr)
+        return False
+
+    # Aggregate outbound links across all candidate files
+    aggregated = defaultdict(set)
+    for path in candidates:
+        try:
+            text = path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        # Only count text near this slug (rough proximity heuristic: nearest 4000 chars)
+        i = text.find(slug)
+        snippet = text[max(0, i - 200):i + 4000] if i >= 0 else text
+        for target_type, rx in LINK_REGEXES.items():
+            for m in rx.finditer(snippet):
+                target_slug = m.group(1) if rx.groups else "_pricing"
+                if target_type == page_kind and target_slug == slug:
+                    continue  # self-link doesn't count
+                aggregated[target_type].add(target_slug)
+
+    required = OUTBOUND_REQUIREMENTS[pattern]
+    all_pass = True
+    print(f"\nOutbound link audit — pattern {pattern}, slug={slug}")
+    for target_type, min_count in required.items():
+        found = len(aggregated.get(target_type, set()))
+        ok = found >= min_count
+        mark = "✓" if ok else "✗"
+        print(f"  {mark} {target_type}: {found} / {min_count} required")
+        if not ok:
+            all_pass = False
+    return all_pass
+
+
+def assert_inbound(slug: str, pattern: str, root: Path):
+    """Check that ≥2 other files link to this slug."""
+    pattern_dir_map = {"A": "alternatives", "B": "for", "C": "for", "D": "compare", "E": "playbooks"}
+    target_type = pattern_dir_map[pattern]
+    rx = LINK_REGEXES[target_type]
+
+    inbound_files = set()
+    for path in root.rglob("*"):
+        if not path.is_file() or path.suffix not in DEFAULT_EXTENSIONS:
+            continue
+        if any(p in path.parts for p in (".git", "node_modules", "dist", "build", ".next", "tmp")):
+            continue
+        try:
+            text = path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        for m in rx.finditer(text):
+            if m.group(1) == slug:
+                inbound_files.add(str(path))
+
+    n = len(inbound_files)
+    ok = n >= INBOUND_MINIMUM
+    mark = "✓" if ok else "✗"
+    print(f"\nInbound link audit — slug={slug}")
+    print(f"  {mark} {n} / {INBOUND_MINIMUM} required files link to this page")
+    if n < INBOUND_MINIMUM and inbound_files:
+        for f in sorted(inbound_files):
+            print(f"      → {f}")
+    return ok
+
+
+def orphan_check(root: Path):
+    """Find pattern slugs that have <2 inbound links anywhere in the repo."""
+    print("\nOrphan check — slugs with <2 inbound links")
+    all_slugs_by_type = defaultdict(set)
+    # Discover all slugs from file naming conventions (rough)
+    for path in root.rglob("*"):
+        if not path.is_file() or path.suffix not in DEFAULT_EXTENSIONS:
+            continue
+        try:
+            text = path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        for target_type, rx in LINK_REGEXES.items():
+            for m in rx.finditer(text):
+                if rx.groups:
+                    all_slugs_by_type[target_type].add(m.group(1))
+
+    any_orphans = False
+    for target_type, slugs in all_slugs_by_type.items():
+        rx = LINK_REGEXES[target_type]
+        for slug in sorted(slugs):
+            inbound_files = set()
+            for path in root.rglob("*"):
+                if not path.is_file() or path.suffix not in DEFAULT_EXTENSIONS:
+                    continue
+                try:
+                    text = path.read_text(encoding="utf-8")
+                except (OSError, UnicodeDecodeError):
+                    continue
+                for m in rx.finditer(text):
+                    if m.group(1) == slug:
+                        inbound_files.add(str(path))
+            # subtract files that ARE the page-definition file (we want inbound from elsewhere)
+            external_inbound = [f for f in inbound_files if not slug in Path(f).stem]
+            if len(external_inbound) < INBOUND_MINIMUM:
+                print(f"  ✗ /{target_type}/{slug} — only {len(external_inbound)} inbound link(s)")
+                any_orphans = True
+
+    if not any_orphans:
+        print("  ✓ No orphans")
+    return not any_orphans
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--slug", help="Slug to audit")
+    parser.add_argument("--pattern", choices=["A", "B", "C", "D", "E"])
+    parser.add_argument("--root", default=".", help="Repo root to scan")
+    parser.add_argument("--orphan-check", action="store_true", help="List all orphan pages")
+    args = parser.parse_args()
+
+    root = Path(args.root).resolve()
+    if not root.is_dir():
+        print(f"not a directory: {root}", file=sys.stderr)
+        sys.exit(2)
+
+    if args.orphan_check:
+        ok = orphan_check(root)
+        sys.exit(0 if ok else 1)
+
+    if not args.slug or not args.pattern:
+        parser.error("--slug and --pattern are required unless --orphan-check is used")
+
+    a = assert_outbound(args.slug, args.pattern, root)
+    b = assert_inbound(args.slug, args.pattern, root)
+    sys.exit(0 if (a and b) else 1)
+
+
+if __name__ == "__main__":
+    main()