@hanzlaa/rcode 4.3.3 → 4.4.1

package/rcode/skills/seo/seo-audit/references/ai-writing-detection.md

@@ -0,0 +1,200 @@
+# AI Writing Detection
+
+Words, phrases, and punctuation patterns commonly associated with AI-generated text. Avoid these to ensure writing sounds natural and human.
+
+Sources: Grammarly (2025), Microsoft 365 Life Hacks (2025), GPTHuman (2025), Walter Writes (2025), Textero (2025), Plagiarism Today (2025), Rolling Stone (2025), MDPI Blog (2025)
+
+---
+
+## Contents
+- Em Dashes: The Primary AI Tell
+- Overused Verbs
+- Overused Adjectives
+- Overused Transitions and Connectors
+- Phrases That Signal AI Writing (Opening Phrases, Transitional Phrases, Concluding Phrases, Structural Patterns)
+- Filler Words and Empty Intensifiers
+- Academic-Specific AI Tells
+- How to Self-Check
+
+## Em Dashes: The Primary AI Tell
+
+**The em dash (—) has become one of the most reliable markers of AI-generated content.**
+
+Em dashes are longer than hyphens (-) and are used for emphasis, interruptions, or parenthetical information. While they have legitimate uses in writing, AI models drastically overuse them.
+
+### Why Em Dashes Signal AI Writing
+- AI models were trained on edited books, academic papers, and style guides where em dashes appear frequently
+- AI uses em dashes as a shortcut for sentence variety instead of commas, colons, or parentheses
+- Most human writers rarely use em dashes because they don't exist as a standard keyboard key
+- The overuse is so consistent that it has become the unofficial signature of ChatGPT writing
+
+### What To Do Instead
+| Instead of | Use |
+|------------|-----|
+| The results—which were surprising—showed... | The results, which were surprising, showed... |
+| This approach—unlike traditional methods—allows... | This approach, unlike traditional methods, allows... |
+| The study found—as expected—that... | The study found, as expected, that... |
+| Communication skills—both written and verbal—are essential | Communication skills (both written and verbal) are essential |
+
+### Guidelines
+- Use commas for most parenthetical information
+- Use colons to introduce explanations or lists
+- Use parentheses for supplementary information
+- Reserve em dashes for rare, deliberate emphasis only
+- If you find yourself using more than one em dash per page, revise
+
+---
+
+## Overused Verbs
+
+| Avoid | Use Instead |
+|-------|-------------|
+| delve (into) | explore, examine, investigate, look at |
+| leverage | use, apply, draw on |
+| optimise | improve, refine, enhance |
+| utilise | use |
+| facilitate | help, enable, support |
+| foster | encourage, support, develop, nurture |
+| bolster | strengthen, support, reinforce |
+| underscore | emphasise, highlight, stress |
+| unveil | reveal, show, introduce, present |
+| navigate | manage, handle, work through |
+| streamline | simplify, make more efficient |
+| enhance | improve, strengthen |
+| endeavour | try, attempt, effort |
+| ascertain | find out, determine, establish |
+| elucidate | explain, clarify, make clear |
+
+---
+
+## Overused Adjectives
+
+| Avoid | Use Instead |
+|-------|-------------|
+| robust | strong, reliable, thorough, solid |
+| comprehensive | complete, thorough, full, detailed |
+| pivotal | key, critical, central, important |
+| crucial | important, key, essential, critical |
+| vital | important, essential, necessary |
+| transformative | significant, important, major |
+| cutting-edge | new, advanced, recent, modern |
+| groundbreaking | new, original, significant |
+| innovative | new, original, creative |
+| seamless | smooth, easy, effortless |
+| intricate | complex, detailed, complicated |
+| nuanced | subtle, complex, detailed |
+| multifaceted | complex, varied, diverse |
+| holistic | complete, whole, comprehensive |
+
+---
+
+## Overused Transitions and Connectors
+
+| Avoid | Use Instead |
+|-------|-------------|
+| furthermore | also, in addition, and |
+| moreover | also, and, besides |
+| notwithstanding | despite, even so, still |
+| that being said | however, but, still |
+| at its core | essentially, fundamentally, basically |
+| to put it simply | in short, simply put |
+| it is worth noting that | note that, importantly |
+| in the realm of | in, within, regarding |
+| in the landscape of | in, within |
+| in today's [anything] | currently, now, today |
+
+---
+
+## Phrases That Signal AI Writing
+
+### Opening Phrases to Avoid
+- "In today's fast-paced world..."
+- "In today's digital age..."
+- "In an era of..."
+- "In the ever-evolving landscape of..."
+- "In the realm of..."
+- "It's important to note that..."
+- "Let's delve into..."
+- "Imagine a world where..."
+
+### Transitional Phrases to Avoid
+- "That being said..."
+- "With that in mind..."
+- "It's worth mentioning that..."
+- "At its core..."
+- "To put it simply..."
+- "In essence..."
+- "This begs the question..."
+
+### Concluding Phrases to Avoid
+- "In conclusion..."
+- "To sum up..."
+- "By [doing X], you can [achieve Y]..."
+- "In the final analysis..."
+- "All things considered..."
+- "At the end of the day..."
+
+### Structural Patterns to Avoid
+- "Whether you're a [X], [Y], or [Z]..." (listing three examples after "whether")
+- "It's not just [X], it's also [Y]..."
+- "Think of [X] as [elaborate metaphor]..."
+- Starting sentences with "By" followed by a gerund: "By understanding X, you can Y..."
+
+---
+
+## Filler Words and Empty Intensifiers
+
+These words often add nothing to meaning. Remove them or find specific alternatives:
+
+- absolutely
+- actually
+- basically
+- certainly
+- clearly
+- definitely
+- essentially
+- extremely
+- fundamentally
+- incredibly
+- interestingly
+- naturally
+- obviously
+- quite
+- really
+- significantly
+- simply
+- surely
+- truly
+- ultimately
+- undoubtedly
+- very
+
+---
+
+## Academic-Specific AI Tells
+
+| Avoid | Use Instead |
+|-------|-------------|
+| shed light on | clarify, explain, reveal |
+| pave the way for | enable, allow, make possible |
+| a myriad of | many, numerous, various |
+| a plethora of | many, numerous, several |
+| paramount | very important, essential, critical |
+| pertaining to | about, regarding, concerning |
+| prior to | before |
+| subsequent to | after |
+| in light of | because of, given, considering |
+| with respect to | about, regarding, for |
+| in terms of | regarding, for, about |
+| the fact that | that (or rewrite sentence) |
+
+---
+
+## How to Self-Check
+
+1. Read your text aloud. If phrases sound unnatural in speech, revise them
+2. Ask: "Would I say this in a conversation with a colleague?"
+3. Check for repetitive sentence structures
+4. Look for clusters of the words listed above
+5. Ensure varied sentence lengths (not all similar length)
+6. Verify each intensifier adds genuine meaning

package/rcode/skills/seo/seo-content-factory/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: seo-content-factory
+description: Autonomous SEO content-factory for LeadLyze — a 10-agent pipeline (competitor research → keyword expansion → clustering → briefs → writing → interlinking → programmatic page gen → schema → refresh → opportunity finding) that researches, clusters, writes, interlinks, and ships 2,000+ SEO pages into the Next.js marketing site. Runs in AUTO mode via herdr orchestration. Trigger when the user says "run the content factory", "build SEO pages", "content factory", "auto SEO", "generate 2000 pages", "programmatic SEO", "SEO auto mode", or invokes /seo-factory.
+metadata:
+  version: 1.0.0
+  target: "LeadLyze — the canonical `marketing/` site (Next.js 16 App Router, React 19, Tailwind v4). NOT marketing-v2..v5 (rejected redesigns)."
+  composes_with: ["herdr-orchestration", "autonomous-fix-campaign"]
+---
+
+# SEO Content Factory
+
+**You are not writing articles one page at a time. You are running a repeatable content-production *system*** that continuously discovers, clusters, briefs, writes, interlinks, and ships LeadLyze SEO pages — at the scale of 2,000+ pages — using Claude + Semrush MCP + herdr parallel agents.
+
+This skill is the **factory floor**: the conveyor (the 10-agent pipeline), the machines (each agent's contract), and the auto-mode motor (herdr waves + heartbeat). It delegates *parallel-agent mechanics* to `herdr-orchestration` and the *auto-mode loop discipline* to `autonomous-fix-campaign`. **Read both before running in auto mode.**
+
+## When to Use
+
+**HARD-TRIGGER words — activate immediately:**
+- `content factory`, `seo factory`, `/seo-factory`
+- "build SEO pages", "generate 2000 pages", "programmatic SEO", "page factory"
+- "auto SEO", "SEO auto mode", "run the SEO pipeline"
+- "interlink the site", "content briefs at scale", "location/industry/comparison pages"
+
+**Soft-trigger:** the user wants continuous organic-traffic growth for LeadLyze via *produced pages* (not just advice). For pure local-business / GBP / backlink advisory work, use `seo-growth-orchestrator` instead — this skill is the **production line**, that one is the **strategist**.
+
+## Non-Negotiable Hard Rules
+
+1. **Composes with `herdr-orchestration` + `autonomous-fix-campaign`.** Every golden rule of those skills applies verbatim: `cld` not `claude`, one worktree+branch per agent, work locally, **never push/deploy without explicit per-campaign consent**, durable backlog committed before wave 1, heartbeat never silent while agents work. Do not re-implement their mechanics here.
+2. **BRIEFS BEFORE PROSE — hard gate.** The Writer agent (Agent 5) NEVER runs for a page that lacks an approved brief artifact on disk (`content/briefs/<slug>.md`). No brief → no article. This is the firewall against generic AI content. See `rules/quality-gates.md`.
+3. **Evidence before generation.** Every keyword that enters the factory carries *real* Semrush/SERP data (volume, KD, intent, a live-SERP check), not an AI guess. AI-estimated volume is a hypothesis to verify, never ground truth.
+4. **Data-driven for scale, MDX for craft.** 2,000 programmatic pages come from a JSON registry + `generateStaticParams` (100 cities × 20 services = 2,000 from ~5 data files) — NOT 2,000 hand-written MDX files. MDX is reserved for the ~100 editorial pages (alternatives, comparisons, cornerstone blog) where prose quality ranks. See `rules/programmatic-pages.md`.
+5. **No duplicate/thin pages ship.** Every generated page passes the indexability gate (unique title+H1+intro, ≥ the cluster's min word floor, real internal links, valid schema) before it lands in the published set. Thin pages get `noindex` until enriched, not shipped raw. See `rules/quality-gates.md`.
+6. **One source of truth per artifact.** Keywords live in `content/seo/keywords.csv`. Clusters in `content/seo/clusters.json`. The link graph in `content/seo/link-map.json`. Agents read/write these canonical files — never private copies that drift.
+
+## The Pipeline (10 agents, 3 execution shapes)
+
+The 10 agents are **not** 10 equal peers. They form a DAG with three distinct shapes:
+
+```
+   FUNNEL (sequential — each consumes the prior's artifact)
+   A1 Competitor Research ─▶ A2 Keyword Expansion ─▶ A3 Sitemap Architect ─▶ A4 Brief Generator
+                                                                                    │
+   FAN-OUT (parallel per-cluster — the herdr wave engine)                          ▼
+                         ┌──────────────┬──────────────┬──────────────┐
+                    A5 Writer      A6 Interlinker  A7 Programmatic  A8 Schema
+                         └──────────────┴──────────────┴──────────────┘
+                                                  │
+                                                  ▼  MDX + data registry + routes → marketing
+   LOOP (recurring cron — never "done")
+   A9 Content Refresh (weekly)   A10 Opportunity Finder (daily)  ──▶ append to BACKLOG → re-enter A4
+```
+
+| # | Agent | Shape | Consumes | Produces | Detail |
+|---|-------|-------|----------|----------|--------|
+| 1 | Competitor Research | funnel | seed domains | `competitors.csv` (keyword,type,intent,traffic,funnel) | `rules/agents.md` |
+| 2 | Keyword Expansion | funnel | seeds + competitors.csv | `keywords.csv` (thousands) | `rules/agents.md` |
+| 3 | Sitemap Architect | funnel | keywords.csv | `clusters.json` (hub→spoke tree) | `rules/agents.md` |
+| 4 | Brief Generator | funnel | clusters.json | `briefs/<slug>.md` | `rules/agents.md` |
+| 5 | Content Writer | fan-out | one brief | `content/<type>/<slug>.mdx` | `rules/agents.md` |
+| 6 | Internal Linker | fan-out | all pages + link-map | 10 in + 10 out links/page → `link-map.json` | `rules/agents.md` |
+| 7 | Programmatic Generator | fan-out | clusters.json (data type) | `content/data/*.json` + route templates | `rules/programmatic-pages.md` |
+| 8 | Schema Agent | fan-out | each page | JSON-LD via `src/lib/jsonld.ts` | `rules/programmatic-pages.md` |
+| 9 | Content Refresh | loop (weekly) | GSC + live pages | updated stats/links/examples | `rules/weekly-cadence.md` |
+| 10 | Opportunity Finder | loop (daily) | competitor deltas | new briefs → BACKLOG | `rules/weekly-cadence.md` |
+
+Full per-agent prompts (hardened, self-contained, paste-into-pane) live in `templates/agent-prompts/`.
+
+## Auto Mode — the Run Loop
+
+When the user says "auto" / "run the factory", execute this loop. It is `autonomous-fix-campaign`'s wave engine, specialized for content:
+
+**Phase 0 — Setup (orchestrator, once)**
+1. Confirm the heartbeat path with the user (`/loop`, `/schedule` cron, or manual ping) — never claim a wakeup you can't fire. (autonomous-fix-campaign rule 2.)
+2. Confirm push/deploy policy. Default: **local only, no push** until explicitly approved.
+3. Seed the durable backlog: `cp templates/BACKLOG.md <marketing>/.planning/seo-factory/BACKLOG.md`, commit it.
+4. Establish the content layer in marketing if absent (content dirs, route templates, mdx loader) — see `rules/programmatic-pages.md`. Capture `pnpm tsc --noEmit | grep -c "error TS"` baseline.
+
+**Phase 1 — Funnel (sequential, orchestrator-run or single agent)**
+Run A1→A2→A3→A4 in order. These are cheap, Semrush-MCP-bound, and each gates the next. Output: `keywords.csv`, `clusters.json`, and a `briefs/` directory. **Do NOT parallelize the funnel** — A3 needs all of A2, A4 needs all of A3.
+
+> **First-run default (DECIDED 2026-06-14):** start with **editorial money pages**
+> (alternative + comparison clusters — highest commercial intent) in the first waves, THEN
+> the programmatic service×city/industry engine. Editorial channel uses **`next-mdx-remote`**.
+
+**Phase 2 — Fan-out waves (herdr, the volume engine)**
+For each batch of N clusters (3–5 per wave), spin a herdr worktree+pane per cluster and run the **Writer→Interlinker→Schema** sub-chain on that cluster's pages. Programmatic (A7) clusters skip the Writer and run the data-registry path instead. Merge each wave into the integration branch before the next wave forks. Heartbeat every 10–15 min; never go silent. (Full mechanics: `rules/herdr-wave-mapping.md`.)
+
+**Phase 3 — Gate + integrate**
+Run the indexability gate (`rules/quality-gates.md`) across the wave's pages. Failures → `noindex` + re-brief, not ship. `pnpm tsc --noEmit` must not exceed baseline. Merge integration branch → master only with explicit user consent.
+
+**Phase 4 — Loop (recurring)**
+A9 (weekly refresh) + A10 (daily opportunity finder) append new work to BACKLOG → re-enter Phase 1's A4 for the new briefs. The factory never "finishes" — it idles between waves.
+
+## Targets (set expectations honestly)
+
+| Window | Pages | Mix |
+|--------|-------|-----|
+| Month 1 | 200 | programmatic location/industry + 20 cornerstone |
+| Month 2 | 500 | + alternative/comparison pages |
+| Month 3 | 1,000+ | + statistics/template/tool/question pages |
+
+Programmatic pages can index in weeks; cornerstone editorial is a 60–180 day payoff. Say this to the user — don't promise rankings in 30 days.
+
+## Integration (granular skills this factory calls)
+
+- **Keyword/cluster mechanics:** `keyword-research`, `serp-analysis`, `competitor-analysis`, `content-gap-analysis`, `claude-seo:seo-cluster`
+- **Writing/on-page:** `seo-content-writer`, `on-page-seo-auditor`, `meta-tags-optimizer`, `claude-seo:seo-content`
+- **Links/schema/build:** `internal-linking-optimizer`, `schema-markup-generator`, `seo-site-builder`, `claude-seo:seo-schema`, `claude-seo:seo-sitemap`
+- **Data:** **Semrush MCP** (`keyword_research`, `organic_research`, `overview_research`, `backlink_research`, `url_research`), GSC via browser/`browser-harness`.
+- **Strategy layer:** `seo-growth-orchestrator` for the judgment/plays around the production.
+
+## File References
+- **Pipeline DAG + data contracts**: `rules/pipeline.md`
+- **The 10 agent specs (hardened)**: `rules/agents.md`
+- **herdr wave mapping (fan-out engine)**: `rules/herdr-wave-mapping.md`
+- **Programmatic pages + marketing wiring**: `rules/programmatic-pages.md`
+- **Quality gates (briefs-first, anti-thin, indexability)**: `rules/quality-gates.md`
+- **Weekly cadence + 90-day plan + A9/A10 loop**: `rules/weekly-cadence.md`
+- **Artifact templates**: `templates/` (CSV/JSON/MDX/route/schema)
+- **Paste-ready agent prompts**: `templates/agent-prompts/`
+
+## Validation Checklist
+- [ ] Confirmed heartbeat path + push policy with user (Phase 0)
+- [ ] Durable `BACKLOG.md` committed before wave 1
+- [ ] Funnel (A1–A4) ran sequentially; `keywords.csv` + `clusters.json` exist
+- [ ] No Writer ran without a brief on disk (briefs-first gate held)
+- [ ] Programmatic pages use the data registry, not 2,000 MDX files
+- [ ] Every shipped page passed the indexability gate (unique, word floor, links, schema)
+- [ ] `pnpm tsc --noEmit` did not exceed baseline after each wave merge
+- [ ] No push/deploy without explicit user consent

package/rcode/skills/seo/seo-content-factory/rules/agents.md

@@ -0,0 +1,80 @@
+# The 10 Agents (hardened specs)
+
+The user's original prompts were directionally right but too loose to run autonomously.
+These are the hardened versions: each states its **input file**, **output file**, **tools**,
+and **acceptance check**. Paste-ready copies are in `templates/agent-prompts/`.
+
+Every agent prompt ends with the same two lines (the factory's discipline):
+> Pull REAL data from Semrush MCP / live SERP before asserting numbers — never invent volume/KD.
+> Write your output to the canonical file path. Do not print results only to chat.
+
+---
+
+## A1 — Competitor Research (funnel)
+- **In:** seed domains (LeadLyze + 3–5 named competitors, e.g. apollo.io, instantly.ai, lemlist.com).
+- **Tools:** Semrush `organic_research`, `overview_research`, `backlink_research`; `competitor-analysis` skill; web search.
+- **Out:** `.planning/seo-factory/competitors.csv` → `keyword,type,intent,traffic,funnel,source_url,competitor`.
+- **Task:** For each competitor pull top organic pages by traffic. Classify each into `type` ∈ industry / location / alternative / comparison / statistics / template / tool / blog. Tag `intent` and `funnel`. Keep rows where LeadLyze could plausibly compete.
+- **Accept:** ≥200 rows, every row has a real `source_url` and a Semrush-sourced `traffic` estimate.
+
+## A2 — Keyword Expansion (funnel)
+- **In:** seeds + `competitors.csv`.
+- **Tools:** Semrush `keyword_research` (broad match, related, questions); `keyword-research` skill.
+- **Out:** `.planning/seo-factory/keywords.csv` (schema in `pipeline.md`).
+- **Task:** Expand each seed across the 8 modifier axes — industry, location, alternative, comparison, template, statistics, question, tool. Pull volume + KD for each from Semrush. Drop volume<10 OR KD>70 unless it's a money term. De-dupe.
+- **Accept:** thousands of rows, each with real volume+kd, `modifier_type` set, no dupes.
+
+## A3 — Sitemap Architect (funnel)
+- **In:** `keywords.csv`.
+- **Tools:** `claude-seo:seo-cluster` (SERP-overlap clustering), `serp-analysis`.
+- **Out:** `.planning/seo-factory/clusters.json` (schema in `pipeline.md`) + assigns `cluster_id` back into `keywords.csv`.
+- **Task:** Cluster by SERP overlap into hub-and-spoke topics. Mark each spoke `page_kind: programmatic | editorial` and `type: money | supporting | blog`. Programmatic = high-volume templated dimensions (service×city, service×industry). Editorial = where prose ranks (alternatives, comparisons, cornerstone).
+- **Accept:** every keyword belongs to exactly one cluster; each hub has a hub page + ≥3 spokes; programmatic clusters declare their `dimensions`.
+
+## A4 — Content Brief Generator (funnel — the GATE feeder)
+- **In:** one `editorial` cluster from `clusters.json`.
+- **Tools:** `serp-analysis` (read top-5 live SERP pages), `content-gap-analysis`.
+- **Out:** `.planning/seo-factory/briefs/<slug>.md` (template: `content-brief.md`), `status: approved`.
+- **Task:** From the live top-5 SERP, extract the winning structure. Produce: title, meta, search intent, full H2/H3 outline, FAQ block, entities to cover, target internal links (from `link-map`/clusters), CTA, schema type, min word count. **Programmatic clusters skip A4** (they get a data record, not a brief).
+- **Accept:** brief covers every entity the top-5 cover + 1 unique angle LeadLyze can own; marked approved.
+
+## A5 — Content Writer (fan-out)
+- **In:** ONE approved `briefs/<slug>.md`. **Refuses to run without it.**
+- **Tools:** `seo-content-writer`, `on-page-seo-auditor`, `meta-tags-optimizer`.
+- **Out:** `src/content/<type>/<slug>.mdx` (template: `article.mdx`).
+- **Task:** Write strictly to the brief. Requirements: original LeadLyze examples + real use cases, ≥1 data table, real statistics (cited), FAQ section, the brief's internal links inline, the meta + frontmatter. **Anti-generic rules (`quality-gates.md`) are mandatory** — no "in today's fast-paced world", no filler intros, no unsupported claims.
+- **Accept:** matches brief outline 1:1, ≥ brief's min words, passes `on-page-seo-auditor`, frontmatter valid.
+
+## A6 — Internal Linker (fan-out — highest ROI)
+- **In:** all existing pages (`src/content/**`, `src/data/seo/**`) + `link-map.json`.
+- **Tools:** `internal-linking-optimizer`.
+- **Out:** updates `link-map.json` + injects links into pages.
+- **Task:** For each new page propose ≥10 inbound (from relevant existing pages) + ≥10 outbound, with **keyword-varied anchors** (never the same anchor twice). Prefer same-cluster + hub↔spoke links. Apply edits and record in `link-map.json`.
+- **Accept:** every shipped page has ≥10/≥10; no orphan pages; anchor diversity ratio >0.7.
+
+## A7 — Programmatic Page Generator (fan-out — the 2,000-page engine)
+- **In:** `programmatic` clusters from `clusters.json`.
+- **Out:** `src/data/seo/{services,cities,industries}.ts` + route template under `src/app/(seo)/...`. See `programmatic-pages.md`.
+- **Task:** Build the dimension registries (TS, typed) and a single dynamic route per pattern with `generateStaticParams` looping the cross-product. 100 cities × 20 services = 2,000 pages from ~5 files. Each page: Hero, Benefits, Case Studies, Pricing, FAQ, CTA — composed from data, never duplicated boilerplate prose (see thin-content gate).
+- **Accept:** `pnpm build` statically generates the full cross-product; spot-checked pages have unique title/H1/intro; no tsc errors.
+
+## A8 — Schema Agent (fan-out)
+- **In:** each generated page.
+- **Tools:** `schema-markup-generator`, `claude-seo:seo-schema`; existing `src/lib/jsonld.ts`.
+- **Out:** JSON-LD injected per page via `jsonld.ts` helpers.
+- **Task:** Emit the right schema per page type — FAQPage, SoftwareApplication, Product, Review/AggregateRating, BreadcrumbList. Extend `src/lib/jsonld.ts` with typed builders; do not hand-write raw `<script>` blobs.
+- **Accept:** every page validates against schema.org; types match page intent.
+
+## A9 — Content Refresh (loop — weekly)
+- **In:** `gsc-deltas.csv` (pages losing position over 28 days).
+- **Tools:** GSC via `browser-harness`/Chrome ext, Semrush, `serp-analysis`.
+- **Out:** updated pages + refreshed stats/competitors/links/examples; `lastUpdated` bumped.
+- **Task:** Find decaying pages, diff against current top-3 SERP, update stale stats, add new competitors/links/examples, refresh `dateModified`.
+- **Accept:** each refreshed page's `dateModified` updated + a recorded diff of what changed.
+
+## A10 — Opportunity Finder (loop — daily)
+- **In:** competitor organic deltas (keywords they newly rank for that LeadLyze doesn't).
+- **Tools:** Semrush `organic_research` (diff vs last run), web search.
+- **Out:** appends new clusters to `BACKLOG.md` → re-enters A4.
+- **Task:** Daily, find net-new competitor keywords not in `keywords.csv`. Prioritize by volume × intent × winnability. Auto-generate a brief stub for the top N and queue them.
+- **Accept:** new opportunities deduped against `keywords.csv`; top-N briefed and queued, not just listed.

package/rcode/skills/seo/seo-content-factory/rules/herdr-wave-mapping.md

@@ -0,0 +1,80 @@
+# herdr Wave Mapping — the fan-out engine
+
+This is where the factory **composes with `herdr-orchestration` + `autonomous-fix-campaign`**.
+Read both first. This file only adds the *content-specific* mapping: how clusters become
+waves, what each pane runs, and how pages merge back.
+
+## The mapping
+
+- **1 cluster = 1 worktree = 1 branch = 1 pane.** Not 1 page per pane (too granular) and
+  not 1 wave per page-type (too coarse). A cluster is the right unit: it's self-contained
+  (shared keyword theme + internal links stay within it), so two agents on two clusters
+  rarely touch the same files.
+- **Wave = 3–5 clusters** (herdr 2×2 / 2×3 grid). Per `autonomous-fix-campaign`: merge each
+  wave into the **integration branch** (`seo-factory-integration`) before the next forks.
+- **Funnel (A1–A4) is NOT a wave.** It runs once, sequentially, before any fan-out — usually
+  the orchestrator runs it directly or as a single `cld` agent. Fan-out waves consume its
+  `clusters.json` + `briefs/`.
+
+## What a fan-out pane runs (the per-cluster sub-chain)
+
+Each pane gets ONE self-contained prompt that runs A5→A6→A8 (or A7→A6→A8 for programmatic)
+for its assigned cluster, in its own worktree:
+
+```
+Editorial cluster pane:
+  for each spoke in cluster:
+    A5 Writer   → src/content/<type>/<slug>.mdx   (requires briefs/<slug>.md)
+  A6 Interlinker → link the cluster's pages + ≥10/≥10 to existing pages, update link-map.json
+  A8 Schema     → inject JSON-LD via src/lib/jsonld.ts
+  commit each page separately; write progress to .planning/seo-factory/AUDIT-<cluster>.md
+
+Programmatic cluster pane:
+  A7 → build/extend src/data/seo/<dimension>.ts + the route template
+  A6 → wire hub↔spoke + cross-links
+  A8 → schema builders for the templated page type
+  node --check touched files; commit; record page count
+```
+
+Per `feedback_no_build_in_child_agents`: **child panes never run `pnpm build`/`tsc`/`dev`/install** —
+they `node --check` only. The orchestrator runs the single central `pnpm tsc --noEmit` after merge.
+
+## Worktree setup (per herdr-orchestration §2)
+
+```bash
+cd /home/hanzla/development/teaching/schedule-manager/marketing
+mkdir -p ../seo-worktrees
+for C in cluster-a cluster-b cluster-c cluster-d; do
+  git worktree add "../seo-worktrees/$C" -b "seo-$C" seo-factory-integration
+  ln -s "$PWD/node_modules" "../seo-worktrees/$C/node_modules"   # so node --check resolves
+done
+```
+
+## The orchestrator loop (per wave)
+
+1. Pop 3–5 `pending` clusters from `BACKLOG.md`; mark `in_wave`.
+2. Create worktrees + a herdr tab with one pane per cluster (herdr-orchestration §3).
+3. Launch `cld` in each pane, send the matching `templates/agent-prompts/` prompt with the
+   cluster id + slug list filled in.
+4. Heartbeat every 10–15 min (`ScheduleWakeup` under `/loop`, else honest manual ping per
+   autonomous-fix-campaign rule 2). **Never silent while panes are `working`.**
+5. On all-`idle`: commit each worktree's `AUDIT-<cluster>.md`, merge `seo-$C` →
+   `seo-factory-integration` (keep superset side on conflict), mark clusters `linked`.
+6. Run Phase-3 gates (`quality-gates.md`) + central `pnpm tsc --noEmit` (must not exceed
+   baseline). Passing clusters → `shipped`. Failing pages → `noindex` + re-brief.
+7. Next wave forks from the now-updated integration branch.
+
+## Conflict surface (low by design)
+
+Because clusters are file-disjoint (`src/content/<type>/<slug>.mdx` is unique per spoke),
+the only shared files are `link-map.json` and `src/data/seo/*.ts`. Mitigation:
+- **link-map.json:** each pane writes ONLY its own cluster's keys; merge is a JSON object
+  union (orchestrator resolves by keeping both key sets).
+- **src/data/seo/*.ts:** assign each programmatic dimension to ONE pane per wave so two panes
+  never append to `cities.ts` simultaneously. If unavoidable, serialize those clusters.
+
+## Push / deploy
+
+Per all three skills' hard rules + `feedback_no_push_without_consent`: the entire campaign
+runs on local branches. Merge `seo-factory-integration` → `master` and any deploy
+(`make brain`) happen **only on explicit user consent**, never mid-wave.

package/rcode/skills/seo/seo-content-factory/rules/pipeline.md

@@ -0,0 +1,102 @@
+# Pipeline & Data Contracts
+
+The factory is a DAG of artifacts on disk. Agents are stateless — they read canonical
+input files and write canonical output files. The files ARE the pipeline; an agent that
+dies mid-wave is restartable because its inputs survived on disk.
+
+## Canonical files (single source of truth)
+
+Pipeline state lives under `<marketing>/.planning/seo-factory/` (factory working files,
+gitignored except the backlog). Shipped content honors the site's **existing conventions**:
+programmatic data as **typed TS modules in `src/data/`** (the site already stores
+case-studies/faq/features/pricing this way), editorial as **MDX** (the blog `[slug]` shell
+explicitly says "fetch MDX/CMS content by slug").
+
+```
+.planning/seo-factory/                # factory working state (orchestrator-owned)
+  BACKLOG.md           # cluster frontier: pending|briefed|written|linked|shipped
+  competitors.csv      # A1 → keyword,type,intent,traffic,funnel,source_url,competitor
+  keywords.csv         # A2 → keyword,parent_seed,modifier_type,volume,kd,intent,funnel,cluster_id
+  clusters.json        # A3 → hub-and-spoke topic tree (see schema below)
+  link-map.json        # A6 → { slug: { inbound:[{from,anchor}], outbound:[{to,anchor}] } }
+  gsc-deltas.csv       # A9/A10 → page,query,clicks,impressions,position,delta_28d
+  briefs/<slug>.md     # A4 — the brief-before-prose GATE artifact
+
+src/data/seo/                          # A7 programmatic registries (matches src/data convention)
+  services.ts          # [{slug,name,benefits,painPoints,...}]  typed export
+  cities.ts            # [{slug,name,region,population,...}]
+  industries.ts        # [{slug,name,...}]
+src/content/                           # A5 editorial MDX (the blog's stated CMS direction)
+  blog/<slug>.mdx          # cornerstone, statistics, question pages
+  alternatives/<slug>.mdx  # "<competitor> alternative" money pages
+  comparisons/<slug>.mdx   # "<x> vs LeadLyze" pages
+```
+
+**Convention rule:** programmatic dimensions are TS (typed, imported by route templates +
+`generateStaticParams`); editorial bodies are MDX (loaded by a small `src/lib/mdx.ts` loader).
+Do NOT introduce a CMS, contentlayer, or a DB — the site is statically generated.
+
+## Artifact schemas
+
+### keywords.csv (A2 output — the factory's raw material)
+```csv
+keyword,parent_seed,modifier_type,volume,kd,intent,funnel,cluster_id
+lead generation for dentists,lead generation software,industry,720,34,commercial,buy,ind-dentists
+apollo alternative,lead generation software,alternative,2900,61,commercial,buy,alt-apollo
+lead generation dubai,lead generation software,location,480,22,commercial,buy,loc-dubai
+cold email open rate statistics,cold email,statistics,1300,18,informational,learn,stat-coldemail
+```
+- `modifier_type` ∈ `industry | location | alternative | comparison | template | statistics | question | tool | seed`
+- `intent` ∈ `informational | commercial | transactional | navigational`
+- `funnel` ∈ `learn | compare | buy`
+- `cluster_id` assigned by A3, blank from A2.
+
+### clusters.json (A3 output — the architecture)
+```json
+{
+  "hubs": [
+    {
+      "id": "lead-generation",
+      "title": "Lead Generation",
+      "hub_page": { "slug": "lead-generation", "type": "money", "keyword": "lead generation software" },
+      "spokes": [
+        { "slug": "lead-generation-for-roofers", "type": "money", "keyword": "lead generation for roofers",
+          "page_kind": "editorial|programmatic", "min_words": 1200, "cluster_id": "ind-roofers" }
+      ],
+      "page_kind": "programmatic",
+      "dimensions": { "service": "lead-generation", "vary_by": "industries.ts" }
+    }
+  ]
+}
+```
+- `page_kind: programmatic` → A7 generates via TS data registry + route template (no Writer). `editorial` → A4 brief + A5 Writer (MDX).
+- `type` ∈ `money | supporting | blog`.
+
+### .planning/seo-factory/briefs/<slug>.md (A4 output — the GATE)
+See `templates/content-brief.md`. No `<slug>.mdx` may be written by A5 unless its brief exists and is marked `status: approved`.
+
+### article frontmatter (A5 output)
+See `templates/article.mdx`. Required frontmatter: `title, description, slug, cluster_id, type, keyword, intent, published, schema, internalLinks`.
+
+### link-map.json (A6 output — where most SEO wins happen)
+```json
+{
+  "lead-generation-for-roofers": {
+    "inbound":  [{ "from": "lead-generation", "anchor": "lead gen for roofing companies" }],
+    "outbound": [{ "to": "cold-calling-for-roofers", "anchor": "cold calling scripts for roofers" }]
+  }
+}
+```
+Target: ≥10 inbound + ≥10 outbound per page, anchors keyword-varied (never all identical).
+
+## Execution shapes (why the DAG matters)
+
+- **Funnel (A1–A4): strictly sequential.** A3 needs ALL of A2 to cluster correctly; A4 needs ALL of A3. Parallelizing the funnel produces incoherent clusters. Run it as ONE agent (or the orchestrator directly) end-to-end.
+- **Fan-out (A5–A8): embarrassingly parallel per cluster.** This is the herdr wave engine — one worktree per cluster, Writer→Interlinker→Schema sub-chain. See `herdr-wave-mapping.md`.
+- **Loop (A9–A10): recurring, never terminal.** Cron-shaped. Feed deltas back to A4. See `weekly-cadence.md`.
+
+## Restartability
+
+Because every stage persists to a canonical file, a crashed wave resumes by re-reading
+the file. The BACKLOG tracks which clusters are `pending | briefed | written | linked |
+shipped` so the orchestrator always knows the frontier after auto-compact.