rsc-universal 0.1.1

package/skills/market-research/scripts/verify.sh

@@ -0,0 +1,215 @@
+#!/usr/bin/env bash
+#
+# verify.sh — provenance + triangulation gate for the `market-research` skill.
+#
+# WHAT IT DOES (read-only; never edits a file)
+#   Static checks over a produced market memo (Markdown). It validates that the
+#   memo is CROSS-CHECKED AND SOURCED — never whether the market is attractive.
+#   For each memo found:
+#     1. TAM / SAM / SOM all present with a parseable numeric value, AND the
+#        nesting SOM <= SAM <= TAM holds. (Units like $, €, K/M/B/k/m/b/bn are
+#        normalized so 1.4M < 9.5M < 15.8M compares correctly.)
+#     2. Triangulation: evidence of BOTH a top-down and a bottom-up figure, PLUS
+#        a stated convergence/divergence note. A lone method fails.
+#     3. Provenance: a sources section exists, and every figure line in it carries
+#        a citation/URL AND a date (YYYY-MM-DD or a year 19xx/20xx). An undated
+#        load-bearing number fails.
+#
+#   A missing/empty target is a SKIP, never a failure. Floating math uses awk
+#   (POSIX), so no bc needed.
+#
+# HOW TO RUN (inside YOUR project, not the skills repo)
+#   ./verify.sh                      # scan ./ for *memo*/*market*.md
+#   ./verify.sh --path memo.md       # check one memo
+#   ./verify.sh --path research/     # scan a directory of memos
+#   ./verify.sh --strict             # treat warnings as failures (CI gate)
+#
+# EXIT CODES
+#   0  clean, empty target, or warnings only without --strict
+#   1  a real failure (broken nesting, missing method, undated source)
+#   2  bad usage
+#
+# Runs on stock macOS bash 3.2: no mapfile, no associative arrays.
+
+set -euo pipefail
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+ok_count=0; skip_count=0; warn_count=0; fail_count=0
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; }
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; }
+
+usage() { sed -n '2,33p' "$0" | sed 's/^# \{0,1\}//'; }
+
+SCAN_PATH="."
+STRICT=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --path)   SCAN_PATH="${2:?--path needs a value}"; shift 2 ;;
+    --strict) STRICT=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) printf '%sUnknown argument: %s%s\n\n' "$RED" "$1" "$NC"; usage; exit 2 ;;
+  esac
+done
+
+summary() { printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"; }
+
+if [ ! -e "$SCAN_PATH" ]; then
+  skip "path not found: $SCAN_PATH — nothing to check"
+  skip_count=1; summary; exit 0
+fi
+
+have() { command -v "$1" >/dev/null 2>&1; }
+if ! have awk; then
+  skip "awk not found — cannot parse memo; install awk"
+  skip_count=1; summary; exit 0
+fi
+
+# Collect candidate memo files: prefer named memos/market files, else any .md.
+FILES=""
+if [ -f "$SCAN_PATH" ]; then
+  FILES="$SCAN_PATH"
+else
+  FILES="$(find "$SCAN_PATH" -type f -name '*.md' \( -iname '*memo*' -o -iname '*market*' -o -iname '*sizing*' \) 2>/dev/null || true)"
+  if [ -z "$FILES" ]; then
+    FILES="$(find "$SCAN_PATH" -type f -name '*.md' 2>/dev/null || true)"
+  fi
+fi
+
+if [ -z "$FILES" ]; then
+  skip "no market memo found under $SCAN_PATH — nothing to check (clean)"
+  skip_count=1; summary; exit 0
+fi
+
+# check_one <file>: one awk pass emits "LEVEL message" lines; the shell tallies.
+check_one() {
+  f="$1"
+  [ -s "$f" ] || { printf '%s[skip]%s empty file: %s\n' "$YELLOW" "$NC" "$f"; return; }
+  printf '%s—— %s%s\n' "$YELLOW" "$f" "$NC"
+
+  awk '
+    # NOTE: stock macOS BSD awk has no IGNORECASE and no \b — we lowercase with
+    # tolower() and use explicit (^|non-letter) boundaries instead.
+    # parse_num(s): pull first number with optional $/€ and K/M/B/bn suffix -> value, or "" if none.
+    function parse_num(s,   t,mult,num) {
+      t=s
+      # find a numeric token possibly with thousands separators and a magnitude suffix
+      if (match(t, /[0-9][0-9.,]*[ ]*(bn|[kmbKMB])?/)) {
+        num=substr(t, RSTART, RLENGTH)
+        mult=1
+        if (num ~ /bn/)      { mult=1000000000; sub(/bn/,"",num) }
+        else if (num ~ /[bB]$/) { mult=1000000000; sub(/[bB]$/,"",num) }
+        else if (num ~ /[mM]$/) { mult=1000000;    sub(/[mM]$/,"",num) }
+        else if (num ~ /[kK]$/) { mult=1000;       sub(/[kK]$/,"",num) }
+        gsub(/[ ,]/,"",num)
+        if (num ~ /^[0-9.]+$/ && num != "" && num != ".") return num*mult
+      }
+      return ""
+    }
+    {
+      line=$0
+      lc=tolower($0)
+
+      # --- sizing: capture first numeric value on a line that names the metric ---
+      if (tam=="" && lc ~ /(^|[^a-z])tam([^a-z]|$)/) { v=parse_num($0); if(v!="") tam=v }
+      if (sam=="" && lc ~ /(^|[^a-z])sam([^a-z]|$)/) { v=parse_num($0); if(v!="") sam=v }
+      if (som=="" && lc ~ /(^|[^a-z])som([^a-z]|$)/) { v=parse_num($0); if(v!="") som=v }
+
+      # --- method evidence ---
+      if (lc ~ /top[ -]?down/)  topdown=1
+      if (lc ~ /bottom[ -]?up/) bottomup=1
+      if (lc ~ /converg|diverg|within [0-9]|[0-9] *x|triangulat/) converge=1
+
+      # --- sources section detection ---
+      if (lc ~ /^#+.*source|^#+.*provenance|^\| *figure|^sources/) insrc=1
+      else if (lc ~ /^#+ /) insrc=0   # a new heading ends the sources block
+
+      # within sources, a row that carries a number should also carry a date
+      if (insrc) {
+        srcseen=1
+        if ($0 ~ /[0-9]/ && ($0 ~ /http/ || $0 ~ /\|/)) {
+          # does this line carry a date? YYYY-MM-DD or a 4-digit year
+          if ($0 ~ /(19|20)[0-9][0-9]-[0-1][0-9]-[0-3][0-9]/ || $0 ~ /(19|20)[0-9][0-9]/) {
+            datedrows++
+          } else {
+            undated++
+            if (undated <= 3) print "DETAIL undated source line: " substr($0,1,80)
+          }
+        }
+      }
+    }
+    END {
+      # 1. TAM/SAM/SOM present + nesting
+      miss=""
+      if (tam=="") miss=miss" TAM"
+      if (sam=="") miss=miss" SAM"
+      if (som=="") miss=miss" SOM"
+      if (miss!="") print "FAIL missing sizing value(s):"miss
+      else {
+        print "OK TAM/SAM/SOM all present (" tam " / " sam " / " som ")"
+        if (som <= sam+0.0001 && sam <= tam+0.0001) print "OK nesting SOM<=SAM<=TAM holds"
+        else print "FAIL nesting broken: need SOM(" som ")<=SAM(" sam ")<=TAM(" tam ")"
+      }
+
+      # 2. triangulation
+      if (topdown && bottomup) {
+        print "OK both top-down and bottom-up figures present"
+        if (converge) print "OK convergence/divergence note present"
+        else print "FAIL no convergence/divergence note for the two methods"
+      } else {
+        m=""
+        if (!topdown)  m=m" top-down"
+        if (!bottomup) m=m" bottom-up"
+        print "FAIL triangulation incomplete — missing method(s):"m
+      }
+
+      # 3. provenance
+      if (!srcseen) print "FAIL no sources/provenance section found"
+      else if (undated>0) print "FAIL "undated" source line(s) carry a figure with no date"
+      else if (datedrows>0) print "OK "datedrows" dated source line(s); none undated"
+      else print "WARN sources section present but no figure+date rows detected"
+    }
+  ' "$f" 2>/dev/null
+}
+
+printf 'Checking market memos under: %s\n\n' "$SCAN_PATH"
+printf '%s\n' "$FILES" | while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  check_one "$f"
+done > "/tmp/mr_verify.$$" 2>&1 || true
+
+# Render with colored tags.
+while IFS= read -r line; do
+  case "$line" in
+    FAIL*)   printf '%s[fail]%s %s\n' "$RED"    "$NC" "${line#FAIL }" ;;
+    WARN*)   printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "${line#WARN }" ;;
+    OK*)     printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "${line#OK }" ;;
+    DETAIL*) printf '        %s\n' "${line#DETAIL }" ;;
+    *)       printf '%s\n' "$line" ;;
+  esac
+done < "/tmp/mr_verify.$$"
+
+tally() { { grep -c "$1" "/tmp/mr_verify.$$" 2>/dev/null || true; } | tr -dc '0-9'; }
+fail_count=$(tally '^FAIL'); fail_count=${fail_count:-0}
+warn_count=$(tally '^WARN'); warn_count=${warn_count:-0}
+ok_count=$(tally '^OK');     ok_count=${ok_count:-0}
+skip_count=$(tally '\[skip\]'); skip_count=${skip_count:-0}
+rm -f "/tmp/mr_verify.$$" 2>/dev/null || true
+
+summary
+
+cat <<'EOF'
+
+Note: this gate proves the memo is CROSS-CHECKED AND SOURCED (TAM/SAM/SOM nesting,
+both methods + a convergence note, dated sources). It does NOT judge whether the
+market is attractive — that is the capability eval's job. Re-run with --strict to
+gate CI on a clean pass.
+EOF
+
+if [ "$fail_count" -gt 0 ]; then exit 1; fi
+if [ "$STRICT" -eq 1 ] && [ "$warn_count" -gt 0 ]; then exit 1; fi
+exit 0

package/skills/marketing/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: marketing
+description: "Use when writing the WORDS for a landing page, marketing site, or launch — value proposition, hero/headline, section-by-section landing copy, microcopy, CTAs, email and launch sequences, channel-adapted messaging (X/LinkedIn/newsletter), SEO-aware copy structure, and SEO/GEO optimization (technical SEO, JSON-LD schema, and getting cited by AI engines like ChatGPT/Perplexity/Gemini/Claude). Grounds every output in the project's brand study under 02-DOCS; if that study is missing or incomplete, it STOPS and interviews the user first. Triggers: 'write the landing copy', 'write the hero', 'value proposition', 'rewrite this CTA', 'write the launch emails', 'turn features into benefits', 'adapt this for LinkedIn/X', 'this copy sounds like AI', 'marketing copy', 'seo', 'geo', 'ai search', 'schema', 'json-ld', 'get cited by ChatGPT', 'rank on Google', 'keyword research', 'meta description', 'AI Overview'. NOT the pixels (that's `design`) and NOT the build (that's `nextjs`)."
+tags: [marketing, copywriting, landing, content]
+recommends: [presentations, design]
+origin: risco
+---
+
+# Marketing — Conversion Copy for Landings & Web Pages
+
+*The words, not the pixels. Ground in the brand study first, then write copy that is specific, benefit-led, and unmistakably this brand.*
+
+This skill owns **conversion copywriting**: value proposition, headlines, section-by-section landing copy, microcopy, CTAs, email/launch sequences, channel adaptation, and SEO-aware copy structure. The sibling `design` skill owns the visual/UX (type, color, layout, motion); `nextjs` owns the build. When asked for "a landing page", you write the copy; defer composition and tokens to `design` and rendering to `nextjs`.
+
+## When to use / When NOT to use
+
+Use when:
+
+- Writing or rewriting a landing page, marketing site, or pricing page — the copy.
+- Crafting a value proposition or positioning statement.
+- Writing headlines, subheads, section copy, microcopy, or CTAs.
+- Building an email sequence, launch announcement, or nurture flow.
+- Adapting one message across channels (X, LinkedIn, newsletter, ads).
+- Rescuing copy that "sounds like AI" or reads generic.
+
+Do NOT use when (delegate or decline):
+
+- Choosing type/color/spacing/layout/motion, or the section visual anatomy → `design`.
+- Implementing the page in React/Next.js (Metadata API, rendering, components) → `nextjs`.
+- Implementing schema/Metadata in React/Next.js code → `nextjs` (this skill specifies the title/description/JSON-LD; `nextjs` renders it). Technical SEO, GEO, schema, and keyword research themselves are owned here → `references/seo-geo.md`.
+- Capturing or persisting a project's brand/voice profile → that is THIS skill's brand-grounding step, persisted under `02-DOCS` per `harness`.
+- Long-form articles, blog posts, or social content systems with no landing/web surface → that is a content job, not landing copy; this skill stays on landings, web pages, and the launch/email/channel copy around them.
+
+## Brand grounding (read this first)
+
+**Hard rule: never produce landing, web-page, or marketing copy without a complete brand study.** Generic copy is the failure mode this skill exists to prevent, and the cure is grounding every word in a real, persisted brand profile. An incomplete brand study is a hard STOP, not a warning.
+
+Run this gate before writing a single line of copy:
+
+1. **Locate the brand study.** Read the project's root `CLAUDE.md` and look for a `## Brand & voice` section linking into `02-DOCS/wiki/brand/` (the `harness` Karpathy-wiki convention: compiled brand articles live under `02-DOCS/wiki/brand/`, raw inputs the user pastes live under `02-DOCS/raw/brand/`). If `CLAUDE.md` is absent, the link is missing, or it points nowhere, treat the study as ABSENT.
+
+2. **Check completeness** against the checklist in `references/brand-grounding.md`. The study is complete only when every dimension is filled: brand name & one-line positioning; ICP / audience & their pains & desires; value proposition & differentiation; tone & voice WITH do/don't word lists and 3–5 voice samples pasted from the user's real writing; proof/credibility; offers & primary CTA; channels; SEO keywords. **Any empty dimension = INCOMPLETE.**
+
+3. **If ABSENT or INCOMPLETE, STOP and interview the user.** Ask the targeted questions from `references/brand-grounding.md`, **one focused batch at a time** (do not dump all questions at once; ask, wait, then continue). Voice samples are mandatory — request 3–5 pieces of the user's real writing; never fabricate a voice. Then:
+   - **a.** Write/update the brand study into `02-DOCS/wiki/brand/` as wiki articles (one article per dimension or a single `index.md` plus per-dimension articles), following the wiki article format in `references/brand-grounding.md`. Save any raw text the user pastes verbatim into `02-DOCS/raw/brand/` and link to it from the article's `> Raw:` line. Create the directories if they do not exist.
+   - **b.** Add or update a `## Brand & voice` section in the root `CLAUDE.md` linking to the brand study. Create `CLAUDE.md` if absent (additive only — never delete existing sections). The exact snippet to insert is in `references/brand-grounding.md`.
+
+4. **Only once the study exists and is complete, proceed.** Cite which brand articles you used (e.g. "grounded in `02-DOCS/wiki/brand/value-proposition.md` and `voice.md`") so the user can trace every claim back to the study.
+
+If the user explicitly says "skip the brand study, just draft something rough", you may produce a clearly-labelled `DRAFT (ungrounded — not brand-checked)` and still recommend running the gate before anything ships. That is the only exception, and it must be labelled.
+
+Full completeness checklist, the exact question script (batched), and the persistence format → `references/brand-grounding.md`.
+
+## The non-negotiables
+
+These are constraints, not preferences. Violating any one is a defect.
+
+1. **Brand study first.** No copy before the grounding gate passes (above). Cite the articles you used.
+2. **5-second value-prop test.** A stranger reads the hero and can say *what it is, who it's for, why it's better* — within 5 seconds. If not, rewrite before anything else.
+3. **Specificity beats adjectives.** Replace "fast", "powerful", "seamless" with a number, a mechanism, or a receipt. "Fast" is a claim; "30 seconds" is evidence.
+4. **Benefit-led, climbing feature → benefit → proof.** Stop at the rung the reader cares about (the benefit) and back it with proof.
+5. **One primary CTA per viewport**, value on the button ("Start free", not "Submit"). Pair it with friction-reducing microcopy ("No credit card required").
+6. **One claim per asset.** A post, an email, a section each carry one real claim — not five hedged ones.
+7. **Match the voice samples.** Every line must plausibly come from the brand's own writing. If it reads like a different author, rewrite.
+8. **The ban-list is enforced everywhere.** Hype words and AI tells are defects, not style. (See ban-list below; `scripts/verify.sh` greps for them.)
+9. **No invented proof.** Never fabricate metrics, customers, quotes, or credentials. Mark `[[NEEDS PROOF]]` and ask.
+10. **SEO-aware structure, not keyword stuffing.** One `<h1>`, scannable subheads that answer queries, benefit in the first 160 chars. Keyword stuffing *lowers* AI citation — full technical SEO/GEO is in `references/seo-geo.md`.
+
+## Copy workflow (the one pass)
+
+Run in order. Each step feeds the next; skipping one shows up as vague copy downstream.
+
+1. **Ground.** Pass the brand-grounding gate. Load value prop, ICP, voice, proof, offer, channels, keywords from `02-DOCS/wiki/brand/`.
+2. **Lock the value proposition.** Fill the value-proposition canvas (jobs / pains / gains → pain-relievers / gain-creators → headline). → `references/copy-frameworks.md`.
+3. **Pick the framework** by traffic temperature and funnel position: PAS for pain-aware cold traffic; AIDA for broad top-of-funnel; FAB/JTBD for feature → benefit; BAB for transformation/case-study. → `references/copy-frameworks.md`.
+4. **Write section by section.** Each landing section has one job and one framework. Map your copy to the design skill's section anatomy. → `references/landing-copy.md`.
+5. **Write the microcopy and CTAs.** Value verbs on buttons, reassurance under them, human empty/loading/error states. → `references/copy-frameworks.md`.
+6. **Adapt for channels** if the task spans more than the page (email sequence, launch, X/LinkedIn/newsletter). → `references/campaigns-and-channels.md`.
+7. **Run the QA gate** (below) and `scripts/verify.sh`. Fix every flag or justify it.
+
+## Headlines & value proposition in 60 seconds
+
+The headline is the highest-leverage copy on the page. Build it from the canvas, not from a thesaurus.
+
+```text
+VALUE-PROP CANVAS (fill before writing the headline)
+Customer job ....... the outcome they're hired to achieve
+Top pain ........... the friction that blocks the job today
+Top gain ........... what "great" looks like to them
+Pain reliever ...... how the product removes that friction
+Gain creator ....... the upside the product unlocks
+Headline ........... compress the strongest reliever+gain into one line
+Subhead ............ who it's for + how it works in one clause + proof if you have it
+```
+
+Headline formula slots (pick one, fill with brand specifics):
+
+- **Outcome + timeframe** — "Preview every branch in 30 seconds".
+- **X without Y** — "Live previews without a staging queue".
+- **JTBD** — "When you open a PR, get a live URL automatically".
+- **Specificity** — replace an adjective with a number: "Cut review setup from 20 min to 30 sec".
+
+```text
+Bad  — "Revolutionize your workflow with our seamless, cutting-edge platform"
+Good — "Ship a fix in 4 minutes — no YAML, no on-call page"
+```
+
+Full canvas walk-through, PAS/AIDA/FAB/BAB/JTBD with Bad→Good rewrites, headline formulas, microcopy & CTA tables → `references/copy-frameworks.md`.
+
+## Landing copy by section
+
+Each section earns its place by doing one job. Cut any section with no job. This maps 1:1 to the `design` skill's section anatomy — `design` owns the visual treatment, this skill owns the words inside it.
+
+| Section | Copy job | Framework |
+| --- | --- | --- |
+| Hero | State the value prop; pass the 5s test | Outcome + timeframe headline |
+| Social-proof strip | Borrow credibility instantly | Quantified, attributed |
+| Problem / agitation | Name the pain in the reader's words | PAS |
+| Solution | Show the product doing the job | FAB |
+| Features → benefits | Translate each capability into an outcome | FAB / JTBD per item |
+| Objection handling | Preempt the top reason not to buy | "X without Y" |
+| Pricing | Make the choice easy; frame value | Value framing, anchored |
+| FAQ | Answer the real blockers | Question → direct answer |
+| Final CTA | One action, value on the button | CTA verb + reassurance |
+
+```text
+Bad  (features list) — "Includes automated teardown, RBAC, and audit logs."
+Good (benefit-led)   — "Environments tear down on merge, so you never pay for idle infra
+                        or clean up by hand."
+```
+
+Full per-section copy patterns, hero variants, social-proof formats, pricing copy, FAQ writing → `references/landing-copy.md`.
+
+## Campaigns & channels
+
+When the task is bigger than the page — a launch, an email sequence, cross-channel messaging.
+
+- **Email sequences:** welcome email inside 5 minutes of opt-in (highest open rate of the whole flow); 4-touch starter cadence Day 1 welcome → Day 4 educational → Day 8 case study → Day 12 soft pitch; nurture runs 7–10 emails every 1–2 weeks. One purpose per email. Hold promo language ("free", "limited time") out of early emails to protect deliverability and trust.
+- **Launch:** sequence the beats (tease → reveal → proof → urgency → recap), one claim per beat, every claim traceable to the brand study's proof.
+- **Channel adaptation:** adapt the *format* to the platform, never resize the same copy. X opens with the sharpest claim; LinkedIn expands just enough for outsiders; newsletter does real work in the first screen.
+- **SEO-aware structure:** one `<h1>`, scannable subheads as query answers, benefit in the first 160 chars; full technical SEO/GEO in `references/seo-geo.md`.
+
+Full email templates, subject-line patterns, launch arc, X/LinkedIn/newsletter adaptation, SEO-aware structure → `references/campaigns-and-channels.md`.
+
+## SEO & GEO
+
+The skill body keeps copy *SEO-aware* (one `<h1>`, query-answering subheads, benefit in the first
+160 chars). When the task is the visibility layer itself — ranking on Google/Bing **and getting
+cited by AI engines** — go to `references/seo-geo.md`. It owns technical + on-page SEO, JSON-LD
+schema, per-engine GEO, and keyword/SERP research.
+
+- **SEO** = rank in traditional results (**Google, Bing**). **GEO** (Generative Engine
+  Optimization) = get *cited* inside an AI answer (**ChatGPT, Perplexity, Gemini/AI Overviews,
+  Claude, Copilot**). GEO sits on top of SEO; do both.
+- **The insight that reframes it:** AI engines don't rank pages, they **cite sources**. Being one of
+  the few sources an answer is built from is the new "ranking #1" — you optimize to be *quoted and
+  attributed*, not clicked.
+- **GEO and this skill agree.** The top GEO moves (Princeton, KDD 2024) are *cite sources, add
+  statistics, add quotations, authoritative tone* — the same "specificity beats adjectives, no
+  invented proof, one claim per asset" discipline already enforced above. Keyword stuffing *lowers*
+  AI citation (~−10%). The proof rule is absolute: **never fabricate the stat or quote that earns
+  the lift** — mark `[[NEEDS PROOF]]` and source it.
+- **Audit first, free, no API:** `python3 scripts/seo_audit.py "https://yoursite.com"` reports
+  title/description lengths, single-`<h1>`, JSON-LD count, load time, robots/AI-bot access, sitemap.
+- **Crawler reality (2026):** `OAI-SearchBot`/`Claude-SearchBot`/`PerplexityBot` (+ the `*-User`
+  fetchers) earn citations; `GPTBot`/`ClaudeBot` are *training* crawlers — independently
+  controllable. **INP replaced FID** in Core Web Vitals (Mar 2024; ≤ 200 ms good).
+
+Full GEO method table, robots.txt template, schema library, per-engine factors, keyword workflow,
+and SEO/GEO QA gate → `references/seo-geo.md`. Implementing schema/Metadata in code → `nextjs`.
+
+## The ban-list
+
+State once, enforce everywhere. These signal AI-template copy and erode trust. `scripts/verify.sh` greps for them.
+
+`revolutionary` · `game-changer` · `cutting-edge` · `world-class` · `unlock` · `seamless` · `elevate` · `supercharge` · `next-level` · "In today's landscape" · "In today's fast-paced world" · bait questions ("Tired of slow deploys?") · "not X, just Y" / "not just X" · forced lowercase as a style · "Excited to share" · hollow proof ("thousands trust us") · generic CTAs ("Learn more", "Click here", "Submit") · fake urgency with no real deadline.
+
+```text
+Bad  — "Excited to share our game-changing, world-class platform!"
+Good — "We rebuilt deploys around one CLI step. Here's what changed: 22 min → 90 sec."
+```
+
+The brand study's do/don't word lists EXTEND this list per project — always apply both.
+
+## Anti-patterns / rationalizations → STOP
+
+| Rationalization | Reality / Fix |
+| --- | --- |
+| "I know the brand, I'll skip the study" | Your default voice is AI-median. Run the gate; cite the articles. |
+| "The image sells it, the copy can be vague" | Copy carries the value prop. Pass the 5s test in words. |
+| "Adjectives make it sound premium" | They make it sound generic. Replace with a number or mechanism. |
+| "List every feature so they see the value" | Feature dumps bury the benefit. Climb to benefit, back with proof. |
+| "Add a few testimonials, any will do" | A vague rave < one hard number. Quantify and attribute. |
+| "Five CTAs give them options" | Choice kills conversion. One primary action per viewport. |
+| "Hype words test well" | They erode trust and trip the ban-list. Specificity converts. |
+| "I'll invent a plausible metric to fill the gap" | Never. Mark `[[NEEDS PROOF]]` and ask the user. |
+| "Same copy works on X and LinkedIn" | Resize ≠ adapt. Different format per platform, same claim. |
+
+## Copy QA gate
+
+Run before claiming done. `scripts/verify.sh` automates the greppable subset.
+
+- [ ] Brand study located, complete, and cited (which articles grounded this copy).
+- [ ] Hero passes the 5-second test (what / who / why-better legible fast).
+- [ ] Exactly one `<h1>`; subheads scannable and query-answering.
+- [ ] Every claim is specific (number / mechanism / receipt), not an adjective.
+- [ ] Copy climbs feature → benefit → proof; lands on the benefit.
+- [ ] One primary CTA per viewport; value on the button; reassurance microcopy present.
+- [ ] No invented proof; every gap marked `[[NEEDS PROOF]]`.
+- [ ] Voice matches the brand study's samples and do/don't lists.
+- [ ] Ban-list words absent (global list + brand don't-words).
+- [ ] No passive-voice hedging or weasel words where a direct claim belongs.
+- [ ] Email subjects match the body (no bait-and-switch); promo language held out of early emails.
+- [ ] Channel copy adapted per platform, not resized.
+- [ ] Title 50–60 chars, meta description 120–160, benefit in the first 160 chars.
+
+Automate → `scripts/verify.sh` (read-only grep gate; warns by default, `--strict` to gate CI).
+
+## Project grounding (02-DOCS + CLAUDE.md)
+
+This skill's 02-DOCS record is the **brand & voice study** at `02-DOCS/wiki/brand/` — a hard
+gate (see "Brand grounding" above): if the root `CLAUDE.md` lacks the link or the study is
+incomplete (no voice samples, positioning, do/don't lists), ask until complete, persist it, and
+link it from a `## Knowledge map` section in `CLAUDE.md` (create `CLAUDE.md` if absent). Read it
+first on every use and ground all copy in it. Site and visual conventions belong to the sibling
+`design` and `nextjs` articles in the same Knowledge map.
+
+## See Also
+
+- `../design/SKILL.md` — the pixels: visual system, layout, section anatomy, motion, design QA.
+- `../nextjs/SKILL.md` — the build: App Router, Metadata API, React 19 rendering.
+- `../harness/SKILL.md` — the `02-DOCS` Karpathy-wiki convention this skill persists the brand study into.
+- References: `references/brand-grounding.md`, `references/copy-frameworks.md`, `references/landing-copy.md`, `references/campaigns-and-channels.md`, `references/seo-geo.md` (technical SEO + GEO + schema + keyword research).

package/skills/marketing/evals/README.md

@@ -0,0 +1,61 @@
+# Eval harness — `marketing` skill
+
+These evals check two things: that the skill **triggers** on the right prompts
+(and stays quiet on near-misses), and that it **measurably improves** copy/SEO
+output. Cases live in `cases.yaml`. There is no pure shell runner — grading is
+done by an **agent harness** (a Claude Code agent with skills loaded) plus a
+human spot-check, because triggering and copy quality are judgment calls.
+
+## What's in `cases.yaml`
+
+- `should_trigger` — prompts that MUST load `marketing`.
+- `should_not_trigger` — near-misses that must route elsewhere (`route_to`).
+- `capability` — scenarios with a `must_include` rubric to grade with vs without.
+
+## Triggering eval
+
+Goal: the skill fires when it should and never on a near-miss.
+
+1. Configure an agent with the **full catalog of skill descriptions** available
+   for routing (marketing + design, nextjs, postgresdb, secure-coding, go,
+   flutter, presentations, course-storytelling, building-agents, deployment,
+   harness, init) so routing competes realistically.
+2. For each `should_trigger` prompt: feed it cold, record whether `marketing`
+   is the skill the agent loads. Run **3-5 trials** per prompt (fresh context).
+3. For each `should_not_trigger` prompt: confirm `marketing` does NOT load, and
+   that the chosen skill matches `route_to` (or that it correctly declines when
+   `route_to: none`). Same 3-5 trials.
+4. Score: `triggered_correctly / total_trials` across both lists.
+
+**Pass bar: >= 90% trigger accuracy** over all prompts and trials, with **zero
+systematic false-positives** on the `design`/`nextjs` near-misses (those are the
+known traps — a landing-page prompt about pixels or the build must not pull in
+marketing).
+
+## Capability eval
+
+Goal: prove the skill changes the answer, not just the routing.
+
+1. For each `capability` scenario, run it **twice**:
+   - **WITHOUT** the skill (base agent, no `marketing` loaded).
+   - **WITH** the `marketing` skill loaded.
+2. Grade each output against that scenario's `must_include` checklist — one
+   point per checkable item covered. A human or a grading agent marks each
+   item present / absent.
+3. Compute coverage = `items_covered / total_items` for each run.
+
+**Pass bar: WITH the skill covers >= 80% of `must_include`; WITHOUT clearly
+lower** (target a >= 30-point gap). The skill must demonstrably add the
+brand-grounding STOP, specificity-over-adjectives, single-CTA discipline, the
+ban-list, `[[NEEDS PROOF]]`, and the SEO/GEO + JSON-LD spec. If the base answer
+already scores ~80%, the case isn't discriminating — tighten the rubric.
+
+## Notes on honesty
+
+- Trials are stochastic; report the raw fraction, not a rounded "pass".
+- Brand-gate behavior is the highest-signal capability check: a correct answer
+  refuses to write grounded copy with no brand study and interviews instead.
+  Treat a confident, ungrounded full-page draft as a **capability failure** even
+  if the prose reads well.
+- Re-run after any edit to `SKILL.md` or its `references/` — wording changes
+  shift both triggering and rubric coverage.

package/skills/marketing/evals/cases.yaml

@@ -0,0 +1,84 @@
+skill: marketing
+
+# Prompts that MUST load the `marketing` skill. The skill owns the WORDS of a
+# landing/web/launch surface: value prop, hero, section copy, microcopy, CTAs,
+# email/launch sequences, channel adaptation, and SEO/GEO (technical SEO,
+# JSON-LD spec, AI-engine citation). It does NOT own pixels (design) or the
+# build (nextjs).
+should_trigger:
+  - prompt: "Write the hero and section copy for our new pricing page."
+    why: "Section-by-section landing copy and hero headline are the skill's core conversion-copywriting job."
+
+  - prompt: "Our homepage above-the-fold reads generic and sounds like every other AI startup — can you fix it?"
+    why: "Rescuing copy that 'sounds like AI' / reads generic is an explicit trigger; the ban-list and brand-grounding exist for exactly this."
+
+  - prompt: "Turn this feature list into something a customer would actually care about: SSO, audit logs, 99.9% uptime."
+    why: "Translating features into benefits (FAB/JTBD, climbing feature -> benefit -> proof) is a named use, even though the user never says 'marketing' or 'copy'."
+
+  - prompt: "We launch Tuesday — I need a 4-email sequence and a post for X and LinkedIn announcing it."
+    why: "Launch email sequences plus per-channel adaptation are owned by the campaigns-and-channels part of the skill; user names channels, not the skill."
+
+  - prompt: "How do I get our docs page cited by ChatGPT and Perplexity, and what JSON-LD schema should it have?"
+    why: "GEO (getting cited by AI engines) and specifying JSON-LD schema are explicit SEO/GEO triggers owned by references/seo-geo.md (spec, not the React render)."
+
+  - prompt: "What should the button say and what's the reassurance line under it on our signup CTA?"
+    why: "Microcopy and CTAs (value on the button, friction-reducing reassurance) are an explicit copy job, phrased without naming the skill."
+
+  - prompt: "Give me a one-line value proposition and subhead for a tool that previews every PR branch automatically."
+    why: "Locking the value proposition via the canvas and producing the headline/subhead is the highest-leverage copy task the skill defines."
+
+  - prompt: "Our meta titles and descriptions are a mess and the benefit is buried — can you sort out the on-page copy structure so we rank better?"
+    why: "SEO-aware copy structure (one h1, query-answering subheads, title 50-60 / meta 120-160, benefit in first 160 chars) is owned here, not in design or nextjs."
+
+# NEAR-MISS prompts that must NOT load `marketing`. Each routes to the genuinely
+# correct sibling. The recurring trap: anything touching a "landing page" that
+# is actually about pixels (design) or the build (nextjs), and anything that is
+# article/blog content rather than a landing/launch surface.
+should_not_trigger:
+  - prompt: "Pick the type scale, color palette, and spacing for our landing page hero section."
+    route_to: "design"
+    why: "Type/color/spacing/layout is the pixels, explicitly delegated to design; marketing only owns the words inside the section."
+
+  - prompt: "Implement the landing page hero in Next.js with the Metadata API and render the JSON-LD in the page."
+    route_to: "nextjs"
+    why: "Building the page in React/Next and rendering schema/Metadata in code is the build; marketing specifies the title/description/JSON-LD, nextjs renders it."
+
+  - prompt: "Write a 2000-word blog post explaining how our deployment pipeline works."
+    route_to: "none"
+    why: "Long-form article with no landing/web/launch surface is a content job the skill explicitly stays out of; no sibling owns generic blogging, so it declines."
+
+  - prompt: "Write a CHECK constraint and a partial index to enforce one primary CTA row per campaign in Postgres."
+    route_to: "postgresdb"
+    why: "Despite the word 'CTA', this is pure SQL schema/constraint work owned by postgresdb, not conversion copy."
+
+  - prompt: "Add a honeypot field and rate-limit the newsletter signup endpoint to stop spam submissions."
+    route_to: "secure-coding"
+    why: "Abuse prevention / input hardening on a form endpoint is a security concern, not the words on the page."
+
+  - prompt: "Design the motion and scroll-reveal animations for the features section of our marketing site."
+    route_to: "design"
+    why: "Motion and section visual anatomy are design's domain; marketing owns the copy, not the animation."
+
+# Concrete tasks the skill should guide, with a rubric to grade WITH vs WITHOUT
+# the skill loaded. A correct skill-guided answer should hit most must_include
+# points; an ungrounded answer typically misses the brand gate, specificity,
+# and the QA discipline.
+capability:
+  - scenario: "Write the hero (headline + subhead + primary CTA) for a tool that spins up a live preview URL on every pull request. No brand study exists in the repo yet."
+    must_include:
+      - "STOPS on the brand-grounding gate first: notes there is no complete brand study under 02-DOCS/wiki/brand/ and interviews the user (ICP, positioning, voice samples) before writing — or, only if the user explicitly says draft rough, labels output 'DRAFT (ungrounded — not brand-checked)'."
+      - "Headline built from the value-prop canvas using a concrete formula (outcome+timeframe, 'X without Y', or JTBD), e.g. specificity like '30 seconds' rather than adjectives."
+      - "Passes the 5-second test: a stranger can tell what it is, who it's for, and why it's better."
+      - "Specificity over adjectives — no 'fast/powerful/seamless'; uses a number or mechanism, and marks any unverifiable metric as [[NEEDS PROOF]] rather than inventing it."
+      - "Exactly one primary CTA with value on the button ('Start free', not 'Submit'/'Learn more') plus friction-reducing reassurance microcopy ('No credit card required')."
+      - "Avoids every ban-list word (revolutionary, game-changer, seamless, supercharge, unlock, etc.) and matches the brand's voice samples."
+      - "Subhead names who it's for + how it works in one clause, keeping it SEO-aware (benefit in the first 160 chars)."
+
+  - scenario: "Make our product page get cited by AI engines (ChatGPT, Perplexity, Gemini/AI Overviews) and rank better on Google. Tell us exactly what to change."
+    must_include:
+      - "Distinguishes SEO (rank in Google/Bing results) from GEO (get cited inside an AI answer) and states GEO sits on top of SEO — do both."
+      - "Recommends the proven GEO moves: cite sources, add statistics, add quotations, authoritative tone — and warns keyword stuffing LOWERS AI citation."
+      - "Specifies JSON-LD / schema and on-page structure (one <h1>, query-answering subheads, title 50-60 chars, meta description 120-160, benefit in first 160 chars) — as a spec, deferring the React/Metadata render to nextjs."
+      - "Never fabricates the stat/quote that earns the lift; marks gaps [[NEEDS PROOF]] and asks the user to source them."
+      - "Mentions crawler reality: search/citation bots (OAI-SearchBot, Claude-SearchBot, PerplexityBot) vs training crawlers (GPTBot, ClaudeBot) are controlled independently in robots.txt."
+      - "Suggests an audit-first step (e.g. scripts/seo_audit.py on the URL) before prescribing changes."