rsc-universal 0.1.1

package/skills/marketing/references/brand-grounding.md

@@ -0,0 +1,197 @@
+# Brand Grounding — Checklist, Question Script & Persistence
+
+The brand study is the source of truth every piece of marketing copy is grounded in. This file holds the **completeness checklist** (what "complete" means), the **question script** (how to interview the user, batched), and the **persistence format** (how to write it into `02-DOCS` and link it from `CLAUDE.md`). The runtime mechanism that invokes this — the hard STOP on an incomplete study — lives in `SKILL.md` under "Brand grounding (read this first)".
+
+## Where the brand study lives
+
+Following the `harness` Karpathy-wiki convention:
+
+```text
+02-DOCS/
+├── raw/brand/         ← immutable: voice samples + raw inputs pasted verbatim by the user
+│   ├── voice-sample-1.md
+│   ├── voice-sample-2.md
+│   └── …
+└── wiki/brand/        ← compiled brand study, one article per dimension
+    ├── index.md            ← positioning one-liner + links to every dimension article
+    ├── audience.md         ← ICP, pains, desires
+    ├── value-proposition.md← value prop, differentiation
+    ├── voice.md            ← tone, do/don't word lists, links to raw voice samples
+    ├── proof.md            ← credibility, metrics, customers, guarantees
+    ├── offers.md           ← offers + primary/secondary CTA
+    ├── channels.md         ← active channels + per-channel notes
+    └── seo.md              ← target keywords + intent
+```
+
+Small projects may collapse this into a single `index.md` with all eight sections as `##` headings — but every dimension must still be present and filled.
+
+## Completeness checklist
+
+The study is **COMPLETE** only when every dimension below is filled with real, specific content. Any empty, placeholder, or "TBD" dimension = **INCOMPLETE** = hard STOP, interview the user.
+
+- [ ] **1. Brand name & one-line positioning** — the name, and one sentence: "[Brand] helps [audience] [achieve outcome] by [mechanism]." No jargon, no feature list.
+- [ ] **2. ICP / audience, pains & desires** — who exactly (role, context, sophistication); the top 2–3 pains in their own words; the top 2–3 desires/gains; the alternatives they use today.
+- [ ] **3. Value proposition & differentiation** — the core benefit in one sentence; what makes it different from the named alternatives; the one thing only this brand can credibly say.
+- [ ] **4. Tone & voice** — tone descriptors (3–5 adjectives); a **do-words** list; a **don't-words** list; and **3–5 voice samples pasted from the user's real writing** (posts, emails, docs, prior copy). Samples are mandatory; a voice cannot be inferred without them.
+- [ ] **5. Proof & credibility** — real metrics, named customers/logos, quantified testimonials, certifications, guarantees, or traction the brand can stand behind. Mark anything aspirational as `[[NEEDS PROOF]]`, never present it as fact.
+- [ ] **6. Offers & primary CTA** — what the visitor is being asked to do (sign up, book a demo, buy, join waitlist); the primary CTA verb; any secondary CTA; pricing model if relevant.
+- [ ] **7. Channels** — where this brand actually publishes (landing page, X, LinkedIn, newsletter, email, ads); the priority order; any per-channel constraints.
+- [ ] **8. SEO keywords** — the primary keyword/theme and 3–5 secondary keywords or query phrases the audience actually searches. (This captures intent only; the keyword/SERP workflow and technical SEO/GEO live in `seo-geo.md`.)
+
+## Question script (ask in batches, never all at once)
+
+Ask **one batch at a time**. Send the batch, wait for the answer, persist what you learned, then send the next batch. Skip questions a located-but-incomplete study already answers — only fill the gaps. Stop interviewing the moment all eight dimensions are complete.
+
+### Batch 1 — identity & audience
+
+```text
+1. What's the brand/product name, and in one sentence: who is it for and what outcome does it deliver?
+2. Describe your ideal customer precisely — their role, context, and how sophisticated they are about this problem.
+3. In THEIR words, what are the top 2–3 pains that make them look for something like you?
+4. What does "great" look like to them — the top 2–3 things they actually want?
+5. What do they use today instead of you (tools, workarounds, "doing nothing")?
+```
+
+### Batch 2 — value & proof
+
+```text
+6. In one sentence, what's the core benefit — no feature list, no jargon?
+7. What makes you genuinely different from the alternatives you just named?
+8. What's the one thing only YOU can credibly claim?
+9. What proof can you stand behind right now? (metrics, named customers, testimonials with
+   numbers, certifications, guarantees). If something is aspirational, say so — I'll mark it
+   as needing proof rather than state it as fact.
+```
+
+### Batch 3 — voice (samples are mandatory)
+
+```text
+10. Pick 3–5 adjectives for how the brand should sound (e.g. direct, dry, warm, technical).
+11. Give me a DO list and a DON'T list of words/phrases — things you always say, and things
+    you never want to see.
+12. Paste 3–5 samples of your REAL writing — posts, emails, docs, prior copy. This is how I
+    match your voice instead of inventing a generic one. (I'll save these verbatim under
+    02-DOCS/raw/brand/.)
+```
+
+### Batch 4 — offer, channels, SEO
+
+```text
+13. What's the single action you want visitors to take? (sign up, book a demo, buy, join a
+    waitlist…) And is there a secondary action?
+14. What's your pricing model, if any?
+15. Which channels do you actually publish on, and in what priority? (landing page, X,
+    LinkedIn, newsletter, email, ads)
+16. What 1 primary + 3–5 secondary keywords or phrases does your audience actually search?
+```
+
+If the user can't answer a question, that dimension stays incomplete — note the gap, keep the STOP in place for that dimension, and offer to draft a hypothesis they can confirm rather than fabricating an answer.
+
+## Persistence format
+
+### Brand wiki article template
+
+Each `02-DOCS/wiki/brand/*.md` article follows the harness wiki format:
+
+```markdown
+# Brand — Value Proposition
+
+> Sources: {user interview, YYYY-MM-DD}
+> Raw: [voice-sample-1](../../raw/brand/voice-sample-1.md)
+
+## Overview
+
+One paragraph: the core benefit and what makes it different.
+
+## Core benefit
+
+[Brand] helps [audience] [achieve outcome] by [mechanism].
+
+## Differentiation
+
+- vs [alternative A]: …
+- vs [alternative B]: …
+
+## The one credible claim
+
+…
+
+## See Also
+
+- [Audience](audience.md)
+- [Proof](proof.md)
+```
+
+### Voice article specifics
+
+`voice.md` must contain the do/don't word lists and link to every raw sample:
+
+```markdown
+# Brand — Tone & Voice
+
+> Sources: {user interview, YYYY-MM-DD}
+> Raw: [sample-1](../../raw/brand/voice-sample-1.md); [sample-2](../../raw/brand/voice-sample-2.md)
+
+## Tone
+
+direct · dry · technical · respects the reader's time
+
+## Do-words
+
+ship, concrete, mechanism, receipt, in <time>
+
+## Don't-words
+
+revolutionary, seamless, unlock, leverage, synergy, "excited to share"
+
+## Voice fingerprint (extracted from samples)
+
+- Sentence rhythm: short, declarative; one idea per sentence.
+- Specifics over adjectives; numbers and mechanisms appear often.
+- Parentheticals used for qualification, not for jokes.
+- Never opens with a bait question.
+
+## Voice samples
+
+Stored verbatim under `02-DOCS/raw/brand/` — see Raw links above.
+```
+
+### Raw samples
+
+Paste each user-provided writing sample verbatim into its own `02-DOCS/raw/brand/voice-sample-N.md` with a one-line provenance header:
+
+```markdown
+> Source: user-pasted, YYYY-MM-DD, origin: "LinkedIn post about the v2 launch"
+
+<the sample text, unedited>
+```
+
+### CLAUDE.md link
+
+Add (or update) this section in the root `CLAUDE.md`. Additive only — never delete existing sections. Create `CLAUDE.md` if absent.
+
+```markdown
+## Brand & voice
+
+Marketing and landing copy is grounded in the brand study under
+`02-DOCS/wiki/brand/`. Read it before writing any user-facing copy:
+
+- [Positioning](02-DOCS/wiki/brand/index.md)
+- [Audience](02-DOCS/wiki/brand/audience.md)
+- [Value proposition](02-DOCS/wiki/brand/value-proposition.md)
+- [Voice & tone](02-DOCS/wiki/brand/voice.md)
+- [Proof](02-DOCS/wiki/brand/proof.md)
+- [Offers & CTA](02-DOCS/wiki/brand/offers.md)
+- [Channels](02-DOCS/wiki/brand/channels.md)
+- [SEO keywords](02-DOCS/wiki/brand/seo.md)
+
+Raw voice samples and inputs: `02-DOCS/raw/brand/`.
+The `marketing` skill maintains this study and stops to interview the user
+if any dimension is missing.
+```
+
+## See Also
+
+- `../SKILL.md` — the runtime grounding mechanism (hard STOP) that uses this checklist.
+- `copy-frameworks.md` — turns the value proposition and voice into headlines and copy.
+- `harness` — the canonical `02-DOCS` wiki protocol and article templates.

package/skills/marketing/references/campaigns-and-channels.md

@@ -0,0 +1,151 @@
+# Campaigns & Channels — Email, Launch, X/LinkedIn/Newsletter, SEO-Aware Structure
+
+The copy beyond the page. When the task is a launch, an email flow, or cross-channel messaging, the same brand study and value prop drive it — but the format adapts per channel. One claim per asset; every claim traceable to the brand study's proof. Adapt the *format* to the platform; never resize the same copy across channels.
+
+## Email sequences
+
+Email is the highest-intent channel you own. Defaults below reflect current (2026) deliverability and engagement data.
+
+### Welcome flow (fires on opt-in)
+
+- **Send the welcome email within 5 minutes of opt-in.** It has the highest open rate of the whole flow (60–80%), and every hour of delay costs roughly 10% of opens.
+- **4-touch starter cadence:** Day 1 welcome → Day 4 educational → Day 8 case study → Day 12 soft pitch.
+- **One purpose per email.** Don't stack welcome + pitch + survey into one send.
+- **Hold promo language out of early emails.** Words like "free", "guarantee", "limited time" in emails 1–3 hurt both trust and deliverability; save them for the later soft-pitch send once trust is built.
+
+```text
+EMAIL 1 — Welcome (Day 1, send within 5 min)
+Subject ... You're in. Here's the 30-second start.   (short, plain, no promo words)
+Preview ... One command and your first preview URL.
+Body ......
+  You signed up to stop babysitting staging — let's get you a win in 30 seconds.
+  1. Install: npm i -g driftway
+  2. Run `driftway up` on any branch.
+  3. Open the URL it prints. That's your first live preview.
+  Reply if it doesn't work — a human reads these.
+CTA ....... Open the quickstart   (single, low-friction)
+```
+
+```text
+EMAIL 3 — Case study (Day 8)
+Subject ... How Northwind cut review setup from 22 min to 90 sec
+Preview ... 40 engineers, one CLI step, zero staging queue.
+Body ...... Before/After/Bridge: the queue problem → the 90-second outcome → how Driftway
+            got them there (one CLI step in their existing CI). End with their number.
+CTA ....... See the full story
+```
+
+### Subject-line patterns
+
+| Pattern | Example | Use |
+| --- | --- | --- |
+| Specific number | "3 ways to cut review setup to 90 seconds" | educational sends |
+| Curiosity (honest) | "The staging queue problem nobody names" | top-of-flow |
+| Named-outcome | "How Northwind shipped 40% faster" | case study |
+| Plain & short (2–5 words) | "Your first preview" | Day-1 welcome |
+
+Avoid all-caps, excessive punctuation, and `free`/`guarantee`/`limited time` in early sends. The subject must match the body — no bait-and-switch (it trips the QA gate and trains unsubscribes).
+
+### Deliverability note (hand the technical work to ops/infra)
+
+Authentication is not optional: SPF, DKIM (2048-bit), DMARC starting at `p=none` with reporting, tightening to quarantine/reject once aligned. Warm a new domain gradually. This skill writes the copy; flag the technical setup as a dependency rather than owning it.
+
+## Launch sequence
+
+A launch is a sequence of beats, one claim per beat, every claim traceable to the brand study's proof.
+
+```text
+LAUNCH ARC
+1. Tease   — signal something's coming; create a small information gap (no hype).
+2. Reveal  — the value prop, stated plainly; the one credible claim up front.
+3. Proof   — the demo, the number, the named customer; show, don't assert.
+4. Urgency — a REAL reason to act now (a deadline, a cohort, a price change) — never fake.
+5. Recap   — for those who missed it; restate the value + the single CTA.
+```
+
+```text
+REVEAL post
+Bad  — "Excited to share our game-changing new launch! 🚀"
+Good — "Driftway is live. Every pull request now gets its own live URL in 30 seconds —
+        no staging queue. Here's a 40-second demo:"
+```
+
+Sequence the beats across channels: reveal on the landing page + email + X thread; proof in the case study + a LinkedIn post; urgency in the final email. The same claim, formatted per channel.
+
+## Channel adaptation
+
+Adapt the format to the platform; keep the claim constant. One source asset → distinct native drafts, never one draft resized.
+
+### X
+
+- Open with the sharpest claim, artifact, or tension — no warm-up.
+- Keep the compression if the brand voice is compressed; one claim per post.
+- In a thread, every post advances the argument; don't pad for length.
+- No bait questions, no engagement-farming closers (ban-list).
+
+```text
+Bad  — "Tired of slow deploys? 🧵 Here's why this matters... (1/12)"
+Good — "Staging is a shared queue. We removed it. Every PR now gets its own live URL in
+        30s. How it works ↓"
+```
+
+### LinkedIn
+
+- Expand just enough for people one ring outside the niche to follow.
+- No corporate-inspiration cadence, no fake "journey" arc, no praise-stacking.
+- Lead with the concrete outcome or number; the lesson, if any, comes after the proof.
+
+```text
+Bad  — "I'm humbled and excited to announce a game-changing journey... 🙏"
+Good — "Northwind's 40 engineers were losing 22 minutes per review to the staging queue.
+        We gave every PR its own environment. New number: 90 seconds. Here's how."
+```
+
+### Newsletter
+
+- The first screen does real work — open with the point, the conflict, or the artifact.
+- No warm-up paragraph; every section adds something new.
+- Section labels only when they improve scanning.
+
+```text
+Bad  — "Hope you're having a great week! Lots of exciting updates to share..."
+Good — "We deleted the staging queue. Below: how per-PR environments work, the number
+        from Northwind, and how to try it in 30 seconds."
+```
+
+### Ads
+
+- 3–4 variants, each testing ONE different angle (pain vs. outcome vs. differentiator) — not random wording.
+- Short headline + long headline + one-line body, each self-contained.
+- Ad claims must match the landing page exactly (mismatched claims tank Quality Score and trust).
+
+## SEO-aware structure
+
+A structural constraint on the copy, not a keyword program — the keyword/SERP workflow and technical audits live in `seo-geo.md`.
+
+- Exactly one `<h1>`; linear heading order (`h1` → `h2` → `h3`, no skips).
+- `<h2>`/`<h3>` subheads double as answers to likely search queries.
+- Primary keyword in the `<h1>` naturally; secondary keywords in subheads, never stuffed.
+- Title 50–60 characters; meta description 120–160; benefit in the first ~160 chars so the snippet reads well.
+
+```text
+Title formula           — Primary Topic - Specific Modifier | Brand
+Meta description formula — Action + topic + value proposition + one supporting detail
+```
+
+## Cross-channel consistency QA
+
+- [ ] One claim per asset; every claim traceable to the brand study's proof.
+- [ ] Ad/email/social claims match the landing page exactly.
+- [ ] Email subject matches the body; promo words held out of early sends.
+- [ ] Welcome email fires within 5 minutes of opt-in.
+- [ ] Each channel is adapted in format, not resized from one draft.
+- [ ] Urgency, if used, is backed by a real deadline.
+- [ ] Voice matches the brand samples on every channel.
+
+## See Also
+
+- `copy-frameworks.md` — frameworks and headline formulas reused across channels.
+- `landing-copy.md` — the page these campaigns drive traffic to.
+- `brand-grounding.md` — the proof and voice every channel inherits.
+- `seo-geo.md` — technical SEO, GEO (AI-engine citation), JSON-LD schema, keyword research.

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

@@ -0,0 +1,166 @@
+# Copy Frameworks — Value Prop, PAS/AIDA/FAB/BAB/JTBD, Headlines, Microcopy & CTAs
+
+The copy engine. The value proposition and voice come from the brand study (`brand-grounding.md`); this file turns them into headlines, section copy, microcopy, and CTAs. Every example pairs a `Bad` (generic / hype / vague) line with a `Good` (specific / benefit-led / human) rewrite — that contrast is the lesson.
+
+## The 5s value-prop test
+
+A stranger reads the hero and, within 5 seconds, can answer: **what is it, who is it for, why is it better?** If any answer is missing, the copy fails — rewrite the words before touching layout. The product image is `design`'s job; the answer must survive in text alone.
+
+## Value-proposition canvas
+
+Map the customer side, then your side, then compress the strongest match into a headline. Pull jobs/pains/gains straight from the brand study's audience article.
+
+```text
+VALUE-PROP CANVAS — Driftway (preview-environment CLI)
+Customer jobs ...... ship a branch for review without breaking shared staging
+Customer pains ..... staging is a shared queue; manual env setup eats an afternoon
+Customer gains ..... reviewers click a link and see the real change, not a diff
+Pain relievers ..... one CLI command spins an isolated env; auto-teardown on merge
+Gain creators ...... every PR gets a live preview URL automatically
+Headline ........... "Preview every branch — no staging queue"
+Subhead ............ "One command gives every pull request a live URL. For platform
+                      teams done babysitting staging."
+```
+
+The subhead's three jobs: state **who** it's for, **how** it works in one clause, and **proof** if you have it.
+
+## Frameworks with a picker
+
+Pick by traffic temperature and funnel position.
+
+| Framework | Use when | Shape |
+| --- | --- | --- |
+| **PAS** (Problem-Agitate-Solution) | pain-aware cold traffic that already feels the problem | name pain → twist the knife → resolve |
+| **AIDA** (Attention-Interest-Desire-Action) | broad / top-of-funnel; must earn attention first | hook → relevance → want → act |
+| **FAB** (Feature-Advantage-Benefit) | feature sections; translate capability into outcome | what it is → what it does → why you care |
+| **BAB** (Before-After-Bridge) | transformation stories, case studies | today's pain → the better world → the product as bridge |
+| **JTBD** (Jobs To Be Done) | frame the product as the tool that finishes a job | when [trigger], [product] [gets job done] |
+
+```text
+PAS rewrite
+Bad  — "Our platform streamlines environment management."
+Good — "Staging is a queue. Every merge waits behind someone else's broken branch.
+        Driftway gives each PR its own environment — no queue, no waiting."
+```
+
+```text
+AIDA rewrite
+Bad  — "Sign up for our developer tool today."
+Good — "See your branch live in 30 seconds (Attention). It runs as one CLI step in your
+        existing pipeline (Interest). Reviewers click a real URL, not a screenshot
+        (Desire). Start free — no credit card (Action)."
+```
+
+```text
+FAB rewrite
+Bad  — "Includes automatic environment teardown."
+Good — "Environments tear down automatically when the PR merges (Feature → Advantage),
+        so you never pay for idle infra or clean up by hand (Benefit)."
+```
+
+```text
+BAB rewrite
+Bad  — "Improve your review workflow."
+Good — "Before: reviewers guess from a diff. After: they click a live URL and test the
+        real thing. Driftway builds that URL on every push (Bridge)."
+```
+
+```text
+JTBD rewrite
+Bad  — "A powerful preview platform for modern teams."
+Good — "When a teammate opens a PR, you want to test the actual change in seconds —
+        Driftway gives that PR a live environment automatically."
+```
+
+## Headline formulas
+
+| Formula | Pattern | Example |
+| --- | --- | --- |
+| Outcome + timeframe | `<Outcome> in <time>` | "Preview every branch in 30 seconds" |
+| X without Y | `<Gain> without <pain>` | "Live previews without a staging queue" |
+| JTBD | `When <trigger>, <product> <gets job done>` | "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" |
+| Negation of the cliché | name the thing they expect, then deny it | "No YAML. No on-call page. Just a deploy." |
+
+Specificity beats cleverness — a clear claim outconverts a clever pun every time. Run every headline through the ban-list in `SKILL.md` plus the brand study's don't-words.
+
+```text
+Bad  — "Revolutionize your workflow with our seamless platform"
+Good — "Ship a fix in 4 minutes — no YAML, no on-call page"
+```
+
+## Benefit-led specificity (the feature → benefit → proof ladder)
+
+Climb feature → benefit → proof. Stop at the rung the visitor cares about (the benefit), and back it with proof.
+
+```text
+Feature ... "Isolated per-branch environments."
+Benefit ... "Reviewers test the real change, not a screenshot."
+Proof ..... "Northwind cut review setup from 20 min to 30 sec across 40 engineers."
+```
+
+The 2026 Feature-Benefit Transformation pattern, applied:
+
+```text
+Bad  — "Our platform has advanced encryption."
+Good — "Encrypt customer data with AES-256, so your security team signs off in days,
+        not months."
+```
+
+Numbers and receipts outperform adjectives. "Fast" is a claim; "30 seconds" is evidence. If you have no number, mark `[[NEEDS PROOF]]` and ask the user — never invent one.
+
+## Microcopy & CTA copy
+
+Buttons carry value verbs; reassurance sits under them; form labels are explicit; states stay human. (Pairing a CTA with a one-line reassurance — "No credit card required" — measurably lifts conversion.)
+
+| Context | Bad | Good |
+| --- | --- | --- |
+| Primary CTA | "Submit" / "Learn more" | "Start free" / "Get my estimate" |
+| Secondary CTA | "Click here" | "See a 2-min demo" |
+| CTA reassurance | (none) | "No credit card required · Cancel anytime" |
+| Form label | "Email" placeholder only | "Work email" with a persistent visible label |
+| Field hint | (silence) | "We'll send the export here — no marketing." |
+| Empty state | "No data" | "No previews yet — push a branch to create one." |
+| Loading | "Loading…" | "Spinning up your environment…" |
+| Success | "Success" | "Live. Your preview URL is ready below." |
+| Error | "Something went wrong" | "Couldn't reach the API. Retry, or check status.acme.example." |
+| Disabled CTA | (no reason) | "Add a work email to continue" (say why it's blocked) |
+
+CTA rules:
+
+- **Value on the button**, never the mechanic ("Start free", not "Submit").
+- **One primary action per viewport.** A secondary ghost link may accompany it; never two equal-weight primaries.
+- **Match the funnel stage** — cold traffic gets "See how it works", warm traffic gets "Start free".
+- **Reassurance under the button** removes the last hesitation (risk, price, lock-in).
+
+## Voice/tone application
+
+The brand study's `voice.md` is the source of truth. Consume it; do not re-derive a voice here. A quick application checklist while drafting:
+
+```text
+APPLY VOICE (from 02-DOCS/wiki/brand/voice.md)
+[ ] Tone descriptors honored (e.g. direct, dry, technical).
+[ ] Do-words present where natural; don't-words absent.
+[ ] Sentence rhythm matches the samples (compression vs. expansion).
+[ ] Claims are made as sharply as the samples make them — no softer, no harder.
+[ ] Reads like the same author wrote the samples AND this copy.
+```
+
+If a line would be out of character for the brand's samples, rewrite it — matching the voice is non-negotiable.
+
+## SEO-aware copy structure
+
+A structural constraint on the words, not a keyword strategy — full technical SEO/GEO depth in `seo-geo.md`.
+
+- Put the primary keyword in the `<h1>` naturally, not stuffed.
+- `<h2>`/`<h3>` subheads double as answers to likely search queries.
+- Front-load the benefit in the first ~160 characters so the search snippet reads well.
+- Title 50–60 characters; meta description 120–160 characters (one honest sentence + the value).
+
+## See Also
+
+- `brand-grounding.md` — where the value prop, voice, and proof come from.
+- `landing-copy.md` — where each piece of copy lands on the page.
+- `campaigns-and-channels.md` — the copy beyond the page (email, launch, channels).
+- `../../design/SKILL.md` — the visual treatment of every section.
+- `seo-geo.md` — technical SEO, GEO (AI-engine citation), JSON-LD schema, keyword research.