rsc-universal 0.1.1

package/skills/marketing/references/landing-copy.md

@@ -0,0 +1,191 @@
+# Landing Copy by Section
+
+The words for every landing section, mapped 1:1 to the `design` skill's section anatomy (`../../design/references/landing-anatomy-and-cro.md`). `design` owns the visual treatment and layout; this file owns the copy that goes inside each section. Each section has **one copy job**; cut any section whose job you can't name. Ground every line in the brand study (`brand-grounding.md`) and run the value prop through the canvas (`copy-frameworks.md`) first.
+
+## Section map (copy job + framework)
+
+| Section | Copy job | Framework | Conversion principle |
+| --- | --- | --- | --- |
+| Hero | State the value prop; pass the 5s test | Outcome + timeframe headline | Clarity beats cleverness |
+| Social-proof strip | Borrow credibility instantly | Quantified, attributed | Authority / social proof |
+| Problem / agitation | Name the pain in the reader's words | PAS | Loss aversion |
+| Solution | Show the product doing the job | FAB | Concreteness over claims |
+| Features → benefits | Translate each capability into an outcome | FAB / JTBD per item | Self-relevance |
+| How-it-works | Reduce perceived effort | 3-step sequence | Effort reduction |
+| Testimonials / case study | Prove it works for people like them | Quantified quote | Similarity + proof |
+| Objection handling | Preempt the top "no" | "X without Y" | Risk reduction |
+| Pricing | Make the choice easy; frame value | Value framing, anchored | Anchoring |
+| FAQ | Answer the real blockers | Question → direct answer | Friction removal |
+| Final CTA | One action, value on the button | CTA verb + reassurance | Single decision |
+
+## Hero
+
+The highest-leverage copy on the page. Headline + subhead + one proof signal must answer what/who/why-better in text alone.
+
+```text
+HERO (Driftway)
+Eyebrow ... For platform teams        (optional — qualifies the audience fast)
+Headline .. Preview every branch — no staging queue
+Subhead ... One CLI command gives every pull request its own live URL. Reviewers click a
+            link and test the real change, not a screenshot.
+CTA ....... Start free   ·   reassurance: No credit card · 2-min setup
+Secondary . See a 2-min demo
+```
+
+```text
+Bad  — "The modern platform for seamless environment management."
+Good — "Preview every branch — no staging queue."
+```
+
+Hero variants by traffic temperature:
+
+- **Cold / broad:** lead with the problem or the outcome; secondary CTA is "See how it works".
+- **Warm / category-aware:** lead with the differentiator ("without a staging queue"); primary CTA is "Start free".
+
+## Social-proof strip
+
+One line that borrows credibility. Quantified and attributed beats a logo wall of strangers.
+
+```text
+Bad  — "Trusted by thousands of teams worldwide."
+Good — "Used by 240 platform teams — including Northwind, Acme, and Lumen."
+```
+
+If you have a hard aggregate metric, lead with it: "1.2M previews shipped this year." If you have neither, mark `[[NEEDS PROOF]]` and ask — do not invent logos or counts.
+
+## Problem / agitation
+
+Name the pain in the reader's exact words (pull from the audience article). PAS: state the problem, agitate the cost, hand off to the solution section. Agitate the *consequence*, don't manufacture fake fear.
+
+```text
+Bad  — "Managing environments can be challenging for growing teams."
+Good — "Staging is a shared queue. Your fix is done, but it waits behind someone else's
+        half-broken branch — and the reviewer pings you for the third time today."
+```
+
+## Solution
+
+Show the product doing the job. FAB, led by the benefit. One screenshot's worth of words; `design` supplies the screenshot.
+
+```text
+Bad  — "Driftway is a powerful, flexible environment platform."
+Good — "Run `driftway up` on any branch. In 30 seconds it spins an isolated environment
+        and prints a live URL — the same one your reviewers open."
+```
+
+## Features → benefits
+
+One item per real capability. Each climbs feature → benefit, lands on the benefit, and (where possible) carries a proof fragment. Never a bare feature list.
+
+```text
+Bad  (list)      — "Auto-teardown. RBAC. Audit logs. Parallel environments."
+Good (benefit)   — "Auto-teardown on merge — never pay for idle infra or clean up by hand."
+                   "Role-based access — give contractors a preview without prod keys."
+                   "Parallel environments — every open PR is live at once, no contention."
+```
+
+Keep each to one sentence; the section earns its scannability from parallel structure.
+
+## How-it-works
+
+Reduce perceived effort to as few steps as honestly possible (3 is the sweet spot). Each step is a verb the reader performs, not a feature you have.
+
+```text
+1. Install once — `npm i -g driftway`, link your repo.
+2. Push a branch — Driftway builds an isolated environment automatically.
+3. Share the URL — reviewers test the real change; it tears down on merge.
+```
+
+## Testimonials / case study
+
+A vague rave is worth less than one hard number. Quantify, attribute, make the speaker resemble the reader (same role, same scale).
+
+```text
+Bad  — "This tool is amazing, it changed everything for us!" — Happy Customer
+Good — "Cut our review setup from 22 min to 90 sec across 40 engineers." — Priya R.,
+        Staff Eng, Northwind
+```
+
+Case-study micro-structure (BAB): one line of Before (the pain + a number), one of After (the outcome + a number), attribution.
+
+## Objection handling
+
+Surface the real reason they won't buy — price, migration cost, lock-in, security — and answer it directly. "X without Y" is the workhorse.
+
+```text
+Objection: "Switching CI tools is a project I don't have time for."
+Copy:      "Adopt it without touching your pipeline — Driftway runs as one CLI step inside
+            the CI you already have."
+```
+
+```text
+Objection: "What if I get locked in?"
+Copy:      "No lock-in: environments are plain containers from your existing Dockerfile.
+            Export or leave any time."
+```
+
+## Pricing
+
+Lead each tier with the outcome the buyer gets, then list features. Copy supports the pricing psychology (anchoring, highlighted middle, annual default) that `design` lays out visually.
+
+```text
+Starter  — $0      "Ship solo. Unlimited previews on one repo."
+Team     — $20/mo  "For squads. Parallel previews, RBAC, shared URLs."   ← Most popular
+            (billed annually; "$24 month-to-month")
+Enterprise — Custom "SSO, audit logs, on-prem runners, an SLA."
+```
+
+```text
+Bad  (feature dump)  — "Team: 10 seats, 50 envs, RBAC, SSO add-on, priority support."
+Good (value first)   — "Team — everything a squad needs to review in parallel. Then: 10
+                        seats, RBAC, shared URLs."
+```
+
+Reassurance line near the table: "Cancel anytime · 30-day money-back · no card to start."
+
+## FAQ
+
+Answer the blockers that actually stop the sale, in the reader's words, with a direct first sentence. Skip filler questions. If you add `FAQPage` JSON-LD, the on-page copy must match the markup exactly (the schema itself is in `seo-geo.md` — write the honest answers here). FAQPage is also the single highest-leverage GEO schema for getting cited by AI engines.
+
+```text
+Q: Do I need to change my CI pipeline?
+A: No. Driftway runs as a single CLI step inside your existing pipeline.
+
+Q: Is there a free tier?
+A: Yes. Solo projects are free; paid tiers start at $20/mo billed annually.
+
+Q: What happens to environments after a PR merges?
+A: They tear down automatically. You're never billed for idle infra.
+```
+
+## Final CTA
+
+Restate the core value in one line, then one primary action with the value on the button and a reassurance microcopy line. No new information, no second decision.
+
+```text
+Headline ... Stop babysitting staging.
+Sub ........ Give every pull request a live URL in 30 seconds.
+CTA ........ Start free   ·   No credit card · 2-min setup
+```
+
+```text
+Bad  — "Ready to get started? Learn more about our platform today!"
+Good — "Stop babysitting staging. Start free — no credit card."
+```
+
+## Section QA (copy-only)
+
+- [ ] Each section's copy job is nameable; sections with no job are cut.
+- [ ] Hero passes the 5s test in text alone.
+- [ ] Every feature climbs to a benefit; lands on the benefit.
+- [ ] Proof is quantified and attributed; gaps marked `[[NEEDS PROOF]]`.
+- [ ] One primary CTA per viewport, value on the button + reassurance.
+- [ ] FAQ answers real blockers; first sentence is the direct answer.
+- [ ] Voice matches the brand samples throughout.
+
+## See Also
+
+- `copy-frameworks.md` — the frameworks and headline formulas each section uses.
+- `brand-grounding.md` — the value prop, proof, and voice every line is grounded in.
+- `../../design/references/landing-anatomy-and-cro.md` — the visual anatomy these words fill.
+- `campaigns-and-channels.md` — driving traffic to this page.

package/skills/marketing/references/seo-geo.md

@@ -0,0 +1,391 @@
+# SEO & GEO — Get Found by Google AND Cited by AI Engines
+
+This is the **technical + AI-visibility** layer under the marketing skill. The skill body writes
+SEO-*aware copy structure* (one `<h1>`, query-answering subheads, benefit in the first 160 chars);
+this reference owns the rest: traditional on-page/technical SEO, GEO (getting cited by AI engines),
+JSON-LD schema, per-engine optimization, and the keyword/SERP research workflow.
+
+**Two surfaces, one piece of content:**
+
+- **SEO** — rank in *traditional* search results: **Google, Bing**. The engine returns a list of
+  links; you want to be near the top.
+- **GEO (Generative Engine Optimization)** — get *cited* inside an AI answer: **ChatGPT,
+  Perplexity, Gemini / Google AI Overviews, Claude, Microsoft Copilot**. There is no list of ten
+  blue links — the engine writes one answer and footnotes a handful of sources.
+
+> **The one insight that reframes everything:** AI engines don't rank pages, they **cite sources**.
+> Being one of the 3–5 sources an answer is built from is the new "ranking #1". You optimize not to
+> be clicked, but to be *quoted and attributed*. Most pages are invisible here; a page that is
+> specific, well-sourced, and cleanly structured is disproportionately likely to be the one cited.
+
+GEO does not replace SEO — it sits on top of it. The same page should be crawlable and ranked
+(SEO) *and* quotable and attributed (GEO). The two share ~62% of their signals; the GEO-specific
+~38% is what this reference adds.
+
+---
+
+## Quick start — audit, then decide
+
+Run the free, no-API audit first. It tells you what you already have before you change anything.
+
+```bash
+python3 scripts/seo_audit.py "https://example.com"
+```
+
+It reports: `<title>` + length, meta description + length, presence of OG tags, the `<h1>`, count
+of JSON-LD blocks, load time, whether `robots.txt` exists and which AI bots it names, and whether a
+`sitemap.xml` is served. No API key, no install beyond Python 3 stdlib. (Deeper, API-keyed scripts
+exist upstream — see "Optional tooling" at the end — but you do not need them for an audit.)
+
+Then triage with the priority levels below.
+
+| Level | Meaning | Action |
+| --- | --- | --- |
+| **P0** | Critical — blocks indexing/citation | Fix immediately |
+| **P1** | Important — significant ranking/citation impact | Fix this sprint |
+| **P2** | Recommended — polish, incremental gains | Backlog |
+
+---
+
+## GEO — getting cited by AI engines
+
+The systematic methods come from the Princeton/IIT-Delhi/Georgia-Tech/Allen-AI paper *GEO:
+Generative Engine Optimization* (Aggarwal et al., arXiv:2311.09735, **KDD 2024**). The authors
+A/B-tested content edits against a commercial generative engine (Perplexity) and measured the
+change in a page's share of the cited answer. These are the edits that moved the needle.
+
+> **Read these as a *directional* ordering, not measured numbers.** They come from one 2023–24
+> study on one engine, so treat them as a ranked priority list — what to try first, not a lift you
+> can promise. The *ordering* has held up; the original per-method percentages have **not** been
+> independently reproduced, so they are deliberately omitted here. Lead with the top three.
+
+Listed highest-impact → lowest. Impact is the study's *relative* effect, not a guaranteed number.
+
+| Method | Impact | How to apply |
+| --- | --- | --- |
+| **Cite sources** | strong | Link claims to authoritative references ("According to a 2024 Stanford study…"). Low-ranking pages saw the biggest jump. |
+| **Add statistics** | strong | Replace vague claims with specific, verifiable numbers and a source. |
+| **Add quotations** | strong | Quote a named expert with attribution. |
+| **Authoritative tone** | moderate | State findings with confidence; drop "might", "I think", hedging. |
+| **Easy to understand** | moderate | Explain the hard concept in plain language before the jargon. |
+| **Technical terms** | moderate | Use the correct domain vocabulary so the engine matches specialist queries. |
+| **Unique words / vocabulary diversity** | modest | Avoid repetitive phrasing; vary terminology. |
+| **Fluency optimization** | moderate | Clean grammar, logical flow, short focused paragraphs. |
+| ~~**Keyword stuffing**~~ | **negative** | **Actively hurts GEO.** Unlike old-school SEO, repetition *lowers* citation rate. |
+
+**Best combination:** *Fluency + Statistics* gave the highest overall lift. *Citations +
+Authoritative tone* won for professional/B2B content.
+
+These map cleanly onto the marketing skill's non-negotiables — "specificity beats adjectives",
+"no invented proof", "one claim per asset" are *also* the top GEO moves. **The honest, specific,
+sourced copy this skill already insists on is the same copy AI engines cite.** The marketing
+ban-list applies in full: hype words and keyword stuffing both repel humans and AI.
+
+> **Hard rule carried over from the skill body: never fabricate the statistic, quote, or citation
+> that earns the lift.** A made-up "67% of teams" is a defect, not a GEO tactic. Mark
+> `[[NEEDS PROOF]]` and get a real source — an AI engine that catches an unsourced number stops
+> citing the domain.
+
+### Structure content so it can be extracted
+
+AI engines lift *passages*, not pages. Make the passage trivial to extract:
+
+- **Answer-first.** The direct answer in the first sentence under the heading, then elaborate. Don't
+  bury the lede behind a preamble.
+- **One idea per paragraph**, 2–3 sentences. Atomic paragraphs are quotable; walls of text are not.
+- **Phrase headings as the question** the user actually asks ("How much does X cost?"), then answer
+  it immediately underneath.
+- **Lists for steps, tables for comparisons.** Engines extract these near-verbatim.
+- **Keep content fresh.** Recency is a real citation signal (see per-engine table). Stamp and
+  genuinely update `dateModified`.
+
+### Let the right AI crawlers in (2026 landscape)
+
+A page can't be cited if the engine can't fetch it. As of 2026 the AI-crawler ecosystem splits into
+**three** roles — and you usually want to **allow the retrieval and user fetchers even if you block
+the training crawlers**:
+
+| Role | What it does | Examples | Default stance |
+| --- | --- | --- | --- |
+| **Search / retrieval** | Builds the index the engine cites at answer time | `OAI-SearchBot`, `PerplexityBot`, `Claude-SearchBot`, `Amazonbot` | **Allow** — this is how you get cited |
+| **User-initiated fetch** | Fetches your page live when a user asks | `ChatGPT-User`, `Perplexity-User`, `Claude-User` | **Allow** — blocking kills live citations |
+| **Model training** | Crawls to train the base model | `GPTBot`, `ClaudeBot`, `Google-Extended`, `Applebot-Extended`, `CCBot` | Your call — allow for reach, block to keep content out of training |
+
+Critically, these are **independently controllable**: OpenAI documents allowing `OAI-SearchBot`
+while disallowing `GPTBot`, and `Claude-SearchBot` is separate from `ClaudeBot`. So "I don't want my
+content in training data" does **not** have to mean "I don't want to be cited".
+
+```text
+# robots.txt — allow citation/retrieval, opt out of training (a common 2026 stance)
+User-agent: OAI-SearchBot      # ChatGPT Search retrieval
+Allow: /
+User-agent: ChatGPT-User       # live fetch when a user asks ChatGPT
+Allow: /
+User-agent: PerplexityBot      # Perplexity index
+Allow: /
+User-agent: Perplexity-User    # live fetch
+Allow: /
+User-agent: Claude-SearchBot   # Claude retrieval index
+Allow: /
+User-agent: Claude-User        # live fetch
+Allow: /
+User-agent: Googlebot          # Google Search + AI Overviews
+Allow: /
+User-agent: Bingbot            # Bing + Copilot
+Allow: /
+
+# Training crawlers — uncomment Disallow to opt OUT of training corpora:
+# User-agent: GPTBot
+# Disallow: /
+# User-agent: ClaudeBot
+# Disallow: /
+# User-agent: Google-Extended
+# Disallow: /
+
+Sitemap: https://example.com/sitemap.xml
+```
+
+```text
+Bad  — `User-agent: * / Disallow: /` on a site that wants AI visibility — invisible to every engine.
+Good — Allow the retrieval + user-fetch bots above; decide on training crawlers deliberately.
+```
+
+> The upstream skill lumped all bots into one "allow everything" block and treated `GPTBot` as the
+> way to get cited. That is out of date: `GPTBot` is a *training* crawler; `OAI-SearchBot` is what
+> actually feeds ChatGPT's citations. Allow the search/user bots; the training bots are a separate,
+> optional decision.
+
+---
+
+## Per-engine optimization
+
+Each engine cites from a different index and weights different signals. Optimize the same page for
+all of them, then bias toward wherever your audience actually asks.
+
+| Engine | Index it cites from | What moves citations |
+| --- | --- | --- |
+| **ChatGPT** | Bing-based web + `OAI-SearchBot` | Content-answer fit (match the question's framing), branded/first-party domains over aggregators, recency, a real backlink profile. |
+| **Perplexity** | Own crawl + Google | FAQ schema, clean atomic paragraphs, publicly hosted PDFs, semantic relevance over keyword match, publishing velocity. |
+| **Google AI Overviews / Gemini** | Google | E-E-A-T (Experience, Expertise, Authority, Trust), structured data, topical authority via content clusters + internal links, authoritative citations. |
+| **Microsoft Copilot** | Bing | Be indexed in Bing (use IndexNow), page speed, clear entity definitions, Microsoft-ecosystem signals (LinkedIn, GitHub). |
+| **Claude** | Own retrieval (`Claude-SearchBot`) + web search | High factual density, clean extractable structure, well-sourced claims. Claude crawls far more than it cites — be the quotable, sourced page. |
+
+**Universal moves that help every engine:** allow the retrieval/user bots, ship FAQPage + Article +
+Organization schema, build genuine backlinks, keep content current, structure with clear H1>H2>H3
+and lists/tables, and put specific sourced statistics up front.
+
+---
+
+## Traditional SEO — on-page & technical checklist
+
+### On-page (P0 unless noted)
+
+- [ ] One unique `<title>`, **50–60 chars**, primary keyword toward the front.
+- [ ] One unique `<meta name="description">`, **120–160 chars**, compelling, includes the keyword.
+- [ ] Exactly **one `<h1>`** per page, containing the primary keyword. (The skill's `verify.sh`
+      flags multiple `<h1>`.)
+- [ ] Logical heading hierarchy: H1 > H2 > H3, no skipped levels.
+- [ ] **(P1)** Every `<img>` has descriptive `alt` text; descriptive file names.
+- [ ] **(P1)** Internal links to related content with descriptive anchor text; no 404s.
+- [ ] **(P1)** Canonical tag set; no duplicate-content collisions.
+- [ ] **(P2)** Open Graph (`og:title/description/image` 1200×630 / `og:url` / `og:type`) and
+      Twitter card (`summary_large_image`) tags set.
+- [ ] **(P2)** External links use `rel="noopener noreferrer"`.
+
+```html
+<title>Live PR Previews in 30 Seconds — Driftway</title>
+<meta name="description" content="Get a live preview URL on every pull request in 30 seconds. One CLI step, no staging queue. Start free, no credit card.">
+```
+
+### Technical (P0 unless noted)
+
+- [ ] Site reachable, no 5xx; HTTPS with a valid certificate.
+- [ ] Mobile-responsive (Google indexes mobile-first).
+- [ ] No critical page blocked by `noindex` or by `robots.txt`.
+- [ ] Indexed: check `site:yourdomain.com` on Google **and** Bing (Bing index gates Copilot).
+- [ ] **(P1)** XML sitemap exists and is submitted to Google Search Console + Bing Webmaster Tools.
+- [ ] **(P1)** Core Web Vitals in the green (see below).
+- [ ] **(P2)** Images optimized (WebP, lazy-load), CSS/JS minified, Brotli/GZIP on, CDN in front.
+
+### Core Web Vitals (current thresholds)
+
+Google's three Core Web Vitals as of **2026**. **INP replaced FID on 12 March 2024** — FID is
+retired; do not target it.
+
+| Metric | Measures | Good | Needs work | Poor |
+| --- | --- | --- | --- | --- |
+| **LCP** (Largest Contentful Paint) | Loading | ≤ 2.5 s | 2.5–4 s | > 4 s |
+| **INP** (Interaction to Next Paint) | Responsiveness | ≤ 200 ms | 200–500 ms | > 500 ms |
+| **CLS** (Cumulative Layout Shift) | Visual stability | ≤ 0.1 | 0.1–0.25 | > 0.25 |
+
+Implementing these in a Next.js app (Metadata API, `next/image`, font strategy) belongs to the
+sibling `nextjs` skill — this reference defines the targets; `nextjs` hits them.
+
+### Off-page & E-E-A-T
+
+Backlinks from relevant, diverse referring domains remain Google's strongest off-page signal and a
+top predictor of AI citation too. Demonstrate **E-E-A-T**: author bios with credentials, an about
+page, visible contact info, privacy/terms, and real reviews/testimonials. Brand mentions count even
+without a link. (Acquiring backlinks is outreach/PR work — flag it as a dependency; this skill does
+not buy or fabricate links.)
+
+---
+
+## JSON-LD schema
+
+Schema markup is structured data that tells engines exactly what a page is — and FAQPage in
+particular is a strong GEO signal because it hands the engine pre-extracted Q&A pairs. Put one
+`<script type="application/ld+json">` block in the page `<head>` (in Next.js, render it via the
+Metadata API or a `<Script>` tag). Validate every block before shipping.
+
+**Pick by page type:** `Organization` (homepage/about) · `WebPage` (any page) · `Article`
+(blog/news, with author + `datePublished`/`dateModified`) · `FAQPage` (any Q&A — highest GEO value)
+· `Product` (e-commerce) · `SoftwareApplication` (tools/apps) · `HowTo` (tutorials) ·
+`BreadcrumbList` (navigation) · `LocalBusiness` (physical location). Combine several on one page with
+`@graph`.
+
+**FAQPage — the single highest-leverage schema for GEO:**
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "FAQPage",
+  "mainEntity": [
+    {
+      "@type": "Question",
+      "name": "How fast can I get a preview URL?",
+      "acceptedAnswer": {
+        "@type": "Answer",
+        "text": "In about 30 seconds. Run `driftway up` on any branch and it prints a live URL — no staging queue, no YAML."
+      }
+    }
+  ]
+}
+```
+
+**Article — for blog/tutorial content (author + dates are the GEO-relevant fields):**
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Article",
+  "headline": "Live PR Previews Without a Staging Queue",
+  "datePublished": "2026-01-15T08:00:00+00:00",
+  "dateModified": "2026-05-20T10:30:00+00:00",
+  "author": {
+    "@type": "Person",
+    "name": "Jordan Rivera",
+    "jobTitle": "Staff Engineer",
+    "url": "https://example.com/author/jordan"
+  },
+  "publisher": {
+    "@type": "Organization",
+    "name": "Driftway",
+    "logo": { "@type": "ImageObject", "url": "https://example.com/logo.png" }
+  },
+  "mainEntityOfPage": { "@type": "WebPage", "@id": "https://example.com/blog/previews" }
+}
+```
+
+**Organization — homepage/about (the `sameAs` links tie your entity to its profiles):**
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Organization",
+  "name": "Driftway",
+  "url": "https://example.com",
+  "logo": "https://example.com/logo.png",
+  "sameAs": [
+    "https://github.com/driftway",
+    "https://linkedin.com/company/driftway",
+    "https://x.com/driftway"
+  ]
+}
+```
+
+For Product, SoftwareApplication, HowTo, BreadcrumbList, LocalBusiness, SpeakableSpecification, and
+a combined `@graph` example, the full template set lives in the upstream skill credited above; the
+five types here cover the overwhelming majority of marketing sites.
+
+**Validate before shipping (no fabricated ratings or reviews in schema — same proof rule):**
+
+- Google Rich Results Test — `https://search.google.com/test/rich-results`
+- Schema.org Validator — `https://validator.schema.org/`
+- Google Search Console → *Enhancements* for live errors after deploy.
+
+---
+
+## Keyword & SERP research workflow
+
+You do not need a paid tool to do real keyword work. Use the agent's **WebSearch** plus the free
+audit. Escalate to APIs only when scale demands it.
+
+1. **Seed from the brand study.** The SEO keywords dimension in `02-DOCS/wiki/brand/` is the
+   starting list — never invent keywords the brand hasn't claimed.
+2. **Expand with WebSearch.** Search the seed terms; read the People-Also-Ask questions and the
+   autocomplete-style related queries that surface. Each real question is a candidate FAQ entry and
+   an answer-first heading.
+   ```text
+   WebSearch: "{keyword} 2026"                         # current volume/intent signal
+   WebSearch: "{keyword} vs {alternative}"             # comparison intent → comparison table
+   WebSearch: "how to {job the keyword implies}"       # informational intent → HowTo
+   ```
+3. **Read the SERP for intent.** Look at what already ranks: are the top results how-tos, product
+   pages, or listicles? Match that intent or you won't rank regardless of copy quality.
+4. **Map one primary keyword per page; no cannibalization.** Two pages chasing the same term
+   compete with each other. Assign secondary/long-tail keywords as subheads.
+5. **Check the AI answer too.** Ask the question in ChatGPT/Perplexity and see who gets cited —
+   those citations *are* your GEO competitor set, often different from the Google top 10.
+
+> **Optional paid tooling (no API key required for anything above):** the upstream `seo-geo` skill
+> ships DataForSEO-backed Python scripts — `keyword_research.py`, `related_keywords.py`,
+> `serp_analysis.py`, `backlinks.py`, `domain_overview.py`, `competitor_gap.py`,
+> `autocomplete_ideas.py` — for programmatic volume/difficulty/backlink data. They require
+> `DATAFORSEO_LOGIN` / `DATAFORSEO_PASSWORD` and are **not** vendored here; only the free
+> `seo_audit.py` is. Reach for them when you're running SEO at scale, not for a single site.
+
+---
+
+## Anti-patterns / rationalizations → STOP
+
+| Rationalization | Reality / Fix |
+| --- | --- |
+| "GEO replaces SEO, skip the technical stuff" | GEO sits *on top of* SEO; a page that can't be crawled or ranked can't be cited either. Do both. |
+| "Stuff the keyword everywhere to rank" | Keyword stuffing helps nothing and *lowers* AI citation by ~10%. Write naturally; one primary keyword per page. |
+| "Add a `67% of teams` stat — sounds citable" | Fabricated stats are a defect and get a domain dropped once caught. Mark `[[NEEDS PROOF]]`, source it, then ship. |
+| "Allow `GPTBot` so ChatGPT cites me" | `GPTBot` is a *training* crawler. `OAI-SearchBot` (+ `ChatGPT-User`) is what feeds citations. Allow the right bot. |
+| "Block all AI bots to protect content" | That makes you invisible in AI answers. Block *training* crawlers if you must; keep *retrieval* + *user* fetchers allowed. |
+| "Target FID for responsiveness" | FID was retired 12 Mar 2024. Optimize **INP** (≤ 200 ms good). |
+| "More schema types = better" | Invalid or irrelevant schema is ignored or penalized. Ship the few types that match the page, and validate them. |
+| "One `<h1>` is a copy detail" | It's also a ranking + extraction signal. Exactly one, with the keyword. |
+
+---
+
+## SEO/GEO QA gate
+
+Run before claiming a page is optimized.
+
+- [ ] `scripts/seo_audit.py` run; title/description lengths, single `<h1>`, JSON-LD count, load
+      time, robots/sitemap reviewed.
+- [ ] Title 50–60 chars, meta description 120–160, both with the primary keyword.
+- [ ] Exactly one `<h1>` with the keyword; clean H1>H2>H3 hierarchy.
+- [ ] Answer-first structure; atomic 2–3-sentence paragraphs; lists/tables where they fit.
+- [ ] At least the top-3 GEO methods applied (cite sources, statistics, quotations) — every stat
+      and quote real and sourced, none fabricated.
+- [ ] FAQPage + Article/Organization schema present and **validated**; no fake ratings/reviews.
+- [ ] `robots.txt` allows the retrieval + user-fetch AI bots; training-crawler decision is deliberate.
+- [ ] Core Web Vitals targeted: LCP ≤ 2.5 s, **INP ≤ 200 ms**, CLS ≤ 0.1.
+- [ ] One primary keyword per page; no cannibalization; no keyword stuffing.
+- [ ] Indexed in Google **and** Bing; sitemap submitted to both.
+
+---
+
+## See Also
+
+- `SKILL.md` (`## SEO & GEO`) — the marketing skill that owns this reference and the SEO-aware copy
+  structure rules.
+- `../nextjs/SKILL.md` — implements the technical layer: Metadata API for title/description/OG and
+  JSON-LD, `next/image` and font strategy for Core Web Vitals.
+- `../design/SKILL.md` — the visual/UX layer; CLS and LCP are as much layout as code.
+- `../harness/SKILL.md` — the `02-DOCS/wiki/brand/` study whose SEO-keywords dimension seeds the research above.