rsc-universal 0.1.1

package/skills/newsletter/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: newsletter
+description: "Use when running an email newsletter as a recurring publication — writing the subject line + preview text, structuring an issue so opens turn into clicks, the welcome/onboarding sequence, send cadence and engagement segmentation, growth loops (referral, signup incentive, double opt-in), and a metric scorecard that survives Apple Mail Privacy Protection. Triggers: 'write the newsletter subject line', 'my newsletter gets opened but nobody clicks', 'set up a welcome sequence', 'grow my newsletter list', 'newsletter referral program', 'how often should I send', 'what metrics matter now that opens are fake', 'click-to-open rate', 'escriu la newsletter d'aquesta setmana', 'campaña de newsletter que convierta'. NOT the one-off product launch or nurture campaign (that is marketing), NOT the SPF/DKIM/DMARC plumbing under the send (that is email-deliverability)."
+tags: [newsletter, email, growth, copywriting, retention-metrics]
+recommends: [marketing, email-deliverability, brand-voice, landing-copy, ab-testing]
+profiles: []
+origin: risco
+---
+
+# newsletter
+
+Run the newsletter as a **product you ship on a cadence**, not a one-off send. The job is the system around the recurring issue: the subject + preview that earns the open, the issue body that earns the click, the welcome sequence that activates a new subscriber, the cadence and segmentation that keep the list healthy, the growth loops that compound it, and a scorecard that still tells the truth after Apple broke open rates. Every send is one episode of an ongoing show — design the show, not the episode.
+
+## When to use
+
+- Writing the subject line + preview text for an issue and fitting them to inbox truncation.
+- Structuring a recurring issue so opens convert: hook on the first screen, scannable body, one CTA.
+- Writing the welcome / onboarding sequence a confirmed subscriber gets.
+- Planning send cadence, frequency, and engagement-based segmentation.
+- Designing a growth loop: referral program, signup incentive / lead magnet, double opt-in.
+- Choosing which metrics to trust now that Apple MPP inflates opens; building the scorecard.
+- Rescuing a newsletter with high opens but no clicks, or a quietly decaying engaged-reader count.
+
+## When NOT to use — route instead
+
+| The ask | Route to |
+|---|---|
+| One-off product launch announcement or campaign drip nurture | `../marketing/SKILL.md` |
+| Mail lands in spam; set up SPF / DKIM / DMARC, tracking domain, reputation | `email-deliverability` |
+| Write the subscribe / opt-in landing page copy | `../landing-copy/SKILL.md` |
+| Define the house voice, tone, and vocabulary the newsletter speaks in | `../brand-voice/SKILL.md` |
+| Win back / reactivate lapsed *paying customers* (lifecycle, not readers) | `retention` |
+| Produce the underlying long-form articles the issue links out to | `../content-engine/SKILL.md` |
+| Sample size / significance / MDE math for the test itself | `ab-testing` |
+| Source or scrape new contacts; prospect an un-opted-in list | `lead-gen`, `../cold-outreach/SKILL.md` |
+| Actually wire the send through an ESP / Gmail API and schedule it | `email-connector`, `google-workspace` |
+
+You own the *recurring opted-in publication and its open/click/growth system*. The plumbing under every send and the page that captures the signup are someone else's.
+
+## The metric truth after Apple MPP
+
+Apple Mail Privacy Protection pre-fetches the tracking pixel, firing an "open" even when nobody read the email. It accounts for **~49% of all tracked opens** and inflates reported open rate by **~15–35%** on iOS-heavy lists — one beehiiv newsletter jumped from a 28% to a 55% open rate with zero behavior change. So **stop steering on open rate.** MPP does not touch link tracking, which is why the click is now the honest signal.
+
+**Rule: make click rate and non-Apple CTOR the north star, because the click is the one event MPP cannot fake.** Leading 2025 programs removed open rate from decision-making entirely and anchor on clicks.
+
+Calibration benchmarks (2025, cross-industry): average open rate ~42–43% (MPP-inflated, treat as noise), average click rate ~2.1% (range 0.83%–4.90%), click-to-open ~6.8%, conversion ~0.08% (top decile ~0.44%). Use the click figures to calibrate; ignore the open figure as a target.
+
+The scorecard — track these, in this order:
+
+| Metric | What it tells you | Trust |
+|---|---|---|
+| Net engaged readers (clicked in last N issues) | The list that actually exists | High — steer on this |
+| Click rate (unique clicks / delivered) | Did the issue earn action | High |
+| CTOR on the **non-Apple** segment | Did the body convert the open | High |
+| Unsubscribe rate | Cadence / relevance pain | Medium |
+| Spam-complaint rate | Inbox placement risk (gate, not vanity) | High — keep < 0.1% |
+| Open rate | Almost nothing post-MPP | Low — do not target |
+
+## Issue anatomy — one job per issue
+
+Each issue gets **exactly one job and exactly one primary CTA.** A second CTA halves the first. Put the hook on the first screen (subject's promise paid off before any scroll), keep the body scannable (short paragraphs, one idea per block, links that read as links), and end at a single button-grade action.
+
+```text
+Bad (rambling, no single job, CTA buried):
+  Hey everyone! Lots going on this week — we shipped some updates, there's a
+  webinar coming, I read a great book, and oh also our pricing changed, plus
+  here are five links I liked. Anyway, check it all out when you get a chance!
+
+Good (one promise, one payoff, one CTA):
+  This week: the 3-line config change that cut our cold-start by 40%.
+  • What it was   • Why the default is wrong   • The exact diff
+  → Read the 4-minute breakdown   [single primary link]
+```
+
+Everything secondary becomes a one-line P.S. or a small "also" block, never a competing button.
+
+## Subject + preview as a pair
+
+The subject and the preview (preheader) ship together and are tested together — they share the inbox row.
+
+- **Payload in the first ~33 characters**; keep the whole subject ~30–50 chars (≈7–9 words) so it survives mobile truncation.
+- **The preview extends the subject, it never repeats it.** Its first ~35–50 chars are prime real estate; waste them on a duplicate and you've burned the line.
+- **≤2 emojis, at the end, never an all-emoji subject** — an all-emoji subject is the one case that actually trips filters.
+- **The "spam trigger words" list is a myth.** "Free", "guarantee", a normal emoji — these do not sink you; authentication and sender reputation dominate deliverability. Police reputation, not vocabulary; the reputation/auth layer lives in `email-deliverability`.
+
+```text
+Bad (payload past char 33, preview repeats subject):
+  Subject:  We are very excited to finally share our big new feature today!!!
+  Preview:  We are very excited to share our big new feature
+
+Good (payload first, preview extends):
+  Subject:  Cut cold-start 40% with 3 lines
+  Preview:  The default config is wrong — here's the exact diff and why
+```
+
+## Cadence & segmentation
+
+Cadence is not one number for the whole list — it branches on how engaged the reader is. This is the decision table:
+
+| Engagement tier | Signal | Frequency | Track |
+|---|---|---|---|
+| Heavy | Clicked most recent 2–3 issues | Full / can increase | Primary issue + occasional bonus |
+| Active | Opened-and-clicked within ~30 days | Full | Primary issue |
+| Cooling | No click in ~30–60 days | Reduce | Best-of / slower nurture |
+| Dormant | No click in ~90+ days | Pause | Re-permission ("still want this?") then **sunset** |
+
+Sunset dormant addresses on purpose — **complaint rate, not list size, gates the inbox.** Mailing a decaying list harder is how a sender torches its reputation.
+
+Send-time default: **Tuesday/Thursday mid-morning (~10am) or early afternoon (1–3pm)** is the cross-industry baseline — but treat it as a *hypothesis to test against your own list's click data*, not a law. Segmented sends earn roughly **100% higher click rates** than blast-to-everyone, so segment before you optimize send time. Tier definitions and the full sunset/re-permission flow live in `references/growth-loops.md`.
+
+## The welcome sequence
+
+A confirmed subscriber gets a **3–5 email sequence**, not silence until the next issue — this window is the highest engagement they'll ever have. One job per email:
+
+1. **Deliver the promise (immediate)** — the thing they signed up for, instantly. Sets the expectation that you ship value.
+2. **Set expectations + best-of (day 1–2)** — what arrives, how often, plus your best past issue so they see the ceiling.
+3. **The referral ask (day 4–5)** — once they've gotten value, ask them to share (the theSkimm pattern: referral ask *inside* the welcome, not bolted on later).
+4–5. Optional: segmentation/preference capture and a feedback prompt.
+
+Full skeleton with timing, subject+preview per email, and the one-job rule: `references/welcome-sequence.md`.
+
+## Growth loops
+
+Three loops compound the list; depth and the dated numbers are in `references/growth-loops.md`.
+
+- **Referral** — referral programs lift subscriber growth ~17% on average and can accelerate growth 20–200% (The Hustle's referral drives ~10%+ of its free-list growth). Put the ask inside the welcome sequence and at the issue footer, gated on tiered rewards.
+- **Signup incentive / lead magnet** — a specific, immediately useful asset converts the subscribe far better than "join our newsletter". The asset is what gets shared.
+- **Double opt-in** — confirm the address before it joins. It protects list quality and keeps the complaint rate down, which is what actually keeps you in the inbox. The subscribe *page* itself is `../landing-copy/SKILL.md`.
+
+## Compliance baseline
+
+A newsletter is the canonical bulk marketing message, so the Gmail/Yahoo bulk-sender rules (enforced since Nov 2025 for 5,000+/day senders) apply to every issue:
+
+- **RFC 8058 one-click unsubscribe** (`List-Unsubscribe` + `List-Unsubscribe-Post` headers) on every send, plus a **visible footer unsubscribe link.** Both, always.
+- **Keep the spam-complaint rate under 0.1%** and never let it reach 0.3%. This is why you sunset, not why you mail harder.
+
+The DNS / authentication side of those rules — SPF, DKIM, DMARC, the sending domain — is **not this skill**; that is `email-deliverability`. This skill applies the rules to the issue and the cadence.
+
+## A/B testing the right way
+
+- **Test exactly one element at a time** — subject vs subject, or preview vs preview. Change two and the winner is uninterpretable.
+- **Put preview text in the rotation**, not just the subject; it's half the inbox row and usually under-tested.
+- The statistical design — sample size, significance, minimum detectable effect — is `ab-testing`. This skill tells you *what* to test; that one tells you whether the result is real.
+
+## Anti-patterns
+
+| Pattern | Why it fails | Fix |
+|---|---|---|
+| Steering on open rate post-MPP | ~49% of opens are bot-fired; the number is fiction | Steer on click rate + non-Apple CTOR |
+| Two or more primary CTAs in one issue | They split attention; the main action loses | One job, one button per issue |
+| Preview text repeats the subject | Burns half the inbox row on a duplicate | Preview extends the subject with new info |
+| Mailing a decaying list harder | Complaints climb; reputation and inbox placement collapse | Sunset / re-permission the dormant tier |
+| All-emoji subject line | The one emoji case that actually trips filters | ≤2 emojis, at the end, around real words |
+| Policing "spam trigger words" | A myth; reputation/auth decide deliverability | Fix auth + reputation in `email-deliverability` |
+| Buying a list / no double opt-in | Spam traps and complaints gate the whole sender | Double opt-in; grow with referral + lead magnet |
+| Testing two variables at once | Winner is uninterpretable | One variable; preview in the rotation |
+| Referral ask bolted on months later | Misses peak engagement | Put the ask inside the welcome sequence |
+| Same cadence for the whole list | Heavy readers under-served, dormant ones complain | Tier the cadence by engagement |
+
+## Verify
+
+`scripts/verify.sh` is a read-only structural linter for a drafted issue file (`subject:` / `preview:` lines, body, footer). It checks subject length and payload position, that the preview exists and differs from the subject, emoji count, a single primary-CTA marker, and a present unsubscribe line. Run it on the draft before you ship — it never edits the file and exits 0 on an empty one.

package/skills/newsletter/evals/README.md

@@ -0,0 +1,12 @@
+# Evals — newsletter
+
+These cases are read by the repo's skill-eval harness. `should_trigger` and
+`should_not_trigger` check routing precision: each prompt is matched against this
+skill's description versus its siblings (the `route_to` ids — `marketing`,
+`email-deliverability`, `landing-copy`, `retention` — must win their cases). The
+`capability` case is scored by a judge against its `must_include` rubric: it
+checks that a generated first issue actually produces a truncation-fit subject +
+extending preview, single-CTA emails, an in-sequence referral ask, a
+click/CTOR-based success metric with an MPP caveat, a present unsubscribe line,
+and that it defers DNS/auth to `email-deliverability`. Run them through the
+repo's eval runner; no live ESP, sending, or network access is required.

package/skills/newsletter/evals/cases.yaml

@@ -0,0 +1,42 @@
+skill: newsletter
+
+should_trigger:
+  - prompt: "Write the subject line and preview text for this week's newsletter issue."
+    why: Core subject + preview pair job, fit to inbox truncation.
+  - prompt: "My newsletter has a 50% open rate but almost nobody clicks — what's wrong?"
+    why: Non-obvious — high opens / no clicks is the post-MPP metric truth plus issue/CTA structure, the signature rescue case.
+  - prompt: "Set up a welcome sequence for new subscribers and work in a referral ask."
+    why: Welcome/onboarding sequence plus the growth-loop referral ask placed inside it.
+  - prompt: "How often should I send my newsletter and how do I segment subscribers by engagement?"
+    why: Cadence + engagement-segmentation decision table and the sunset policy.
+  - prompt: "What metrics should I trust now that Apple makes my open rate fake?"
+    why: Non-obvious — the MPP metric-truth scorecard (clicks / non-Apple CTOR as north star).
+  - prompt: "Escriu la newsletter d'aquesta setmana perquè la gent l'obri i hi faci clic."
+    why: Catalan — recurring-issue subject/body job (open then click).
+
+should_not_trigger:
+  - prompt: "Write the launch announcement email for our new product drop."
+    route_to: marketing
+    why: One-off campaign send, not the recurring opted-in publication.
+  - prompt: "Our newsletter lands in spam — fix our SPF, DKIM and DMARC records."
+    route_to: email-deliverability
+    why: DNS / authentication / reputation plumbing, not the issue or cadence.
+  - prompt: "Write the subscribe landing page that captures newsletter signups."
+    route_to: landing-copy
+    why: The opt-in page copy, not the email or the list system.
+  - prompt: "Win back customers who haven't purchased in 90 days."
+    route_to: retention
+    why: Lifecycle/churn reactivation of paying customers, not newsletter readers.
+
+capability:
+  - scenario: >
+      A B2B SaaS founder is launching a weekly newsletter and asks for the first
+      issue's subject + preview pair, a 3-email welcome sequence, and the success
+      metric they should track.
+    must_include:
+      - "Subject line ≤ ~50 chars with the payload in the first ~33 chars, paired with a preview that EXTENDS rather than repeats the subject."
+      - "The issue and each welcome email have exactly one primary CTA."
+      - "A referral ask is placed inside the welcome sequence (not bolted on later)."
+      - "The success metric is click-rate / CTOR-based (NOT raw open rate) with an explicit Apple MPP caveat."
+      - "A visible unsubscribe line / one-click unsubscribe is noted as required on every send."
+      - "DNS/auth (SPF/DKIM/DMARC) is deferred to email-deliverability rather than attempted here."

package/skills/newsletter/references/growth-loops.md

@@ -0,0 +1,73 @@
+# Growth loops, segmentation, and the sunset policy
+
+The list compounds through three loops and stays healthy through engagement
+tiering. Numbers below are dated; treat them as calibration, not promises.
+
+## Referral program
+
+- **Lift:** referral programs raise subscriber growth ~17% on average and can
+  accelerate growth 20–200%. The Hustle's referral drives ~10%+ of its free-list
+  growth. (beehiiv growth guide; Partnero/Paved referral guides — accessed 2026-06-02.)
+- **Where the ask lives:** inside the welcome sequence (email 3) AND as a
+  persistent footer block on every issue. Asking once, late, wastes the loop.
+- **Reward tiers:** make the first reward cheap and fast to unlock (e.g. 3
+  referrals) so subscribers get an early win, then ladder up. Digital rewards
+  (archive access, a guide, swag) beat cash for newsletters.
+- **Mechanics:** each subscriber gets a unique referral link; track referred
+  signups, not raw shares. Reward only on confirmed (double opt-in) referrals so
+  the loop does not import junk.
+
+## Signup incentive / lead magnet
+
+- A specific, immediately useful asset converts a subscribe far better than a
+  generic "join our newsletter."
+- The asset doubles as shareable bait for the referral loop — make it good
+  enough to forward.
+- The opt-in *page* and its copy are `../landing-copy/SKILL.md`; this skill owns
+  what the incentive is and how it ties into the welcome + referral flow.
+
+## Opt-in: single vs double
+
+| | Single opt-in | Double opt-in |
+|---|---|---|
+| Friction | Lower (one step) | Higher (confirm click) |
+| List quality | Mixed; typos and traps slip in | High; only confirmed addresses |
+| Complaint / spam-trap risk | Higher | Lower |
+| Best for | Low-risk, already-warm audiences | Default for protecting reputation |
+
+Default to **double opt-in.** Complaint rate and spam traps gate the whole
+sender's inbox placement; the confirmation click is cheap insurance. Segmented
+sends earn ~100% higher click rates than blasts, so a clean confirmed list also
+makes every later segmentation gain real. (Moosend segmentation 2025–2026 —
+accessed 2026-06-02.)
+
+## Engagement segmentation tiers
+
+| Tier | Signal | Frequency | Track |
+|---|---|---|---|
+| Heavy | Clicked most recent 2–3 issues | Full / can add bonus sends | Primary + bonus |
+| Active | Opened-and-clicked within ~30 days | Full | Primary issue |
+| Cooling | No click in ~30–60 days | Reduce | Best-of / slow nurture |
+| Dormant | No click in ~90+ days | Pause → re-permission → sunset | Off the main list |
+
+Heavy clickers can take more frequency; cooling readers get less, on a best-of
+track, before they sour.
+
+## Sunset / re-permission policy
+
+Chronically unengaged addresses get a **re-permission** email ("still want
+this? click to stay") and, if no click, a **sunset** off the active list.
+
+- **Why:** complaint rate, not list size, gates the inbox. A big dormant segment
+  drags placement for everyone, including your heavy readers.
+- **Keep the spam-complaint rate under 0.1%** (never reaching 0.3%) — sunsetting
+  is the lever that protects it. (Yahoo Sender Hub best practices; Google
+  Workspace sender guidelines — accessed 2026-06-02.)
+- Re-permission is a newsletter-list hygiene step. Lifecycle reactivation of
+  lapsed *paying customers* is a different job — that is `retention`.
+
+## Send-time hypothesis
+
+Tuesday/Thursday ~10am or 1–3pm is the cross-industry baseline starting point.
+It is a hypothesis to test against your own list's click data, never a fixed law.
+The test design (sample size, significance) is `ab-testing`.

package/skills/newsletter/references/welcome-sequence.md

@@ -0,0 +1,62 @@
+# Welcome sequence skeleton
+
+The 3–5 emails a subscriber gets after they confirm. This window has the highest
+engagement they will ever show — every email earns one job and one CTA. Send the
+first one immediately on confirmation; space the rest over the first week.
+
+## The one-job rule
+
+Each email answers a single question for the new subscriber. If an email is doing
+two jobs, split it or cut the weaker one. Never open the sequence with a sell.
+
+## Email 1 — deliver the promise (immediate, on confirmation)
+
+- **Job:** hand over the exact thing they subscribed for, right now.
+- **Why first:** the confirmation click is peak intent; a fast payoff sets the
+  expectation that every issue ships value.
+- **CTA:** consume the promised asset (read / download / watch) — one link.
+- Subject + preview pair example:
+  - Subject: `Here's the field guide — start here`
+  - Preview: `Plus the one section most people skip first`
+
+## Email 2 — set expectations + best-of (day 1–2)
+
+- **Job:** tell them what arrives, how often, from whom; then show your ceiling
+  with one strong past issue.
+- **Why:** predictable cadence lowers unsubscribes; the best-of proves the bar.
+- **CTA:** read the best-of issue — one link.
+- Subject + preview pair example:
+  - Subject: `What to expect (and our best issue)`
+  - Preview: `Every Thursday, 4-minute read — here's the one to start with`
+
+## Email 3 — the referral ask (day 4–5)
+
+- **Job:** ask them to share, now that they have received value.
+- **Why:** the theSkimm pattern — the referral ask lives *inside* the welcome
+  sequence, not bolted on months later when engagement has decayed.
+- **CTA:** share their referral link — one link.
+- Subject + preview pair example:
+  - Subject: `Know one person who'd want this?`
+  - Preview: `Your link's below — first reward unlocks at 3`
+
+## Email 4 (optional) — segmentation / preferences (day 6–8)
+
+- **Job:** let them pick topics or frequency so you can route them to the right
+  engagement track from day one.
+- **CTA:** set preferences — one link. Skippable; defaults must be sane.
+
+## Email 5 (optional) — feedback prompt (day 9–12)
+
+- **Job:** ask one question ("what made you subscribe?") to mine future angles
+  and surface at-risk subscribers early.
+- **CTA:** reply to the email — replies also help inbox placement.
+
+## Rules across the sequence
+
+- One primary CTA per email; secondary items go in a one-line P.S.
+- Every email carries the visible unsubscribe footer (compliance is not optional
+  in the welcome stream).
+- Subject payload in the first ~33 chars; preview extends, never repeats.
+- If they click in the sequence, they enter the **active/heavy** cadence tier
+  (see `growth-loops.md`); if they never open the welcome stream, they go to the
+  re-permission path before the main list.

package/skills/newsletter/scripts/verify.sh

@@ -0,0 +1,173 @@
+#!/usr/bin/env bash
+#
+# verify.sh — structural guardrail for a drafted newsletter issue.
+#
+# WHAT IT DOES (read-only; never edits or writes a file)
+#   Static, network-free checks over ONE issue draft you point it at. The draft
+#   is plain text / markdown with a `subject:` line, a `preview:` (or
+#   `preheader:`) line, the issue body, and a footer. Checks:
+#     1. Subject present and <= ceiling chars (default 50)        -> FAIL if over.
+#     2. Subject payload position: first non-trivial word starts past char 33
+#        (i.e. the line opens with filler)                        -> warn.
+#     3. Preview/preheader present                                -> FAIL if missing.
+#     4. Preview not byte-identical to the subject text           -> FAIL if same.
+#     5. Emoji count in the subject <= 2, and the subject is not
+#        all-emoji (must contain real word characters)            -> FAIL.
+#     6. Exactly one primary CTA marker in the body. Convention: a single
+#        line containing a "[CTA]" tag, an arrow "->"/"→" call, or a markdown
+#        button-link. Zero -> warn; more than one -> FAIL.
+#     7. An unsubscribe / opt-out line present anywhere           -> FAIL if missing.
+#
+#   A clean OR empty/whitespace-only file exits 0 — never a false failure.
+#
+# HOW TO RUN (inside YOUR project, not the skills repo)
+#   ./verify.sh issue.md                 # run all checks
+#   ./verify.sh issue.md --ceiling 45    # tighten the subject ceiling
+#   ./verify.sh issue.md --strict        # treat warnings as failures (CI gate)
+#
+# EXIT CODES
+#   0  clean, warnings only (without --strict), or empty/missing-content file
+#   1  a hard failure — or any warning under --strict
+#   2  bad usage (no file given, or file does not exist)
+#
+# Runs on stock macOS bash 3.2: no mapfile, no associative arrays, no bc.
+
+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
+
+warn_count=0; fail_count=0
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; warn_count=$((warn_count + 1)); }
+fail() { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; fail_count=$((fail_count + 1)); }
+
+usage() { sed -n '2,40p' "$0" | sed 's/^# \{0,1\}//'; }
+
+FILE=""
+CEILING=50
+STRICT=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -h|--help) usage; exit 0 ;;
+    --ceiling) CEILING="${2:-50}"; shift 2 ;;
+    --strict) STRICT=1; shift ;;
+    -*) printf '%sunknown option: %s%s\n' "$RED" "$1" "$NC" >&2; usage; exit 2 ;;
+    *) if [ -z "$FILE" ]; then FILE="$1"; fi; shift ;;
+  esac
+done
+
+if [ -z "$FILE" ]; then
+  printf '%sno issue file given%s\n' "$RED" "$NC" >&2; usage; exit 2
+fi
+if [ ! -f "$FILE" ]; then
+  printf '%sfile not found: %s%s\n' "$RED" "$FILE" "$NC" >&2; exit 2
+fi
+
+# Empty / whitespace-only file: nothing to check, do not false-fail.
+if [ ! -s "$FILE" ] || ! grep -q '[^[:space:]]' "$FILE" 2>/dev/null; then
+  ok "empty file — nothing to check"
+  exit 0
+fi
+
+printf 'newsletter verify — %s (subject ceiling=%s chars)\n\n' "$FILE" "$CEILING"
+
+# --- extract subject + preview lines ------------------------------------------
+# Take the first matching line for each, strip the label and surrounding space.
+SUBJECT_LINE="$(grep -iE '^[[:space:]]*(subject|asunto|assumpte)[[:space:]]*:' "$FILE" | head -1 || true)"
+PREVIEW_LINE="$(grep -iE '^[[:space:]]*(preview|preheader|prehead|previsualitzaci|vista previa)[^:]*:' "$FILE" | head -1 || true)"
+
+SUBJECT="$(printf '%s' "$SUBJECT_LINE" | sed -E 's/^[[:space:]]*[A-Za-z]+[^:]*:[[:space:]]*//' | sed -E 's/[[:space:]]+$//')"
+PREVIEW="$(printf '%s' "$PREVIEW_LINE" | sed -E 's/^[[:space:]]*[A-Za-z]+[^:]*:[[:space:]]*//' | sed -E 's/[[:space:]]+$//')"
+
+# --- 1. subject present + length (hard) ---------------------------------------
+if [ -z "$SUBJECT" ]; then
+  fail "no subject line found (expected a line like 'subject: ...')"
+else
+  SLEN="$(printf '%s' "$SUBJECT" | wc -m | tr -d '[:space:]')"
+  if [ "${SLEN:-0}" -gt "$CEILING" ]; then
+    fail "subject is ${SLEN} chars (over the ${CEILING} ceiling) — it will truncate on mobile"
+  else
+    ok "subject length ${SLEN} chars (<= ${CEILING})"
+  fi
+
+  # --- 2. payload position (warn) ---------------------------------------------
+  # Strip a leading run of common filler words; if the first "real" word lands
+  # past char 33, the payload is buried.
+  TRIMMED="$(printf '%s' "$SUBJECT" | sed -E 's/^([Tt]he|[Aa]|[Aa]n|[Ww]e|[Oo]ur|[Yy]ou|[Yy]our|[Hh]ey|[Hh]i|[Jj]ust|[Ss]o|[Vv]ery|[Ee]xcited|[Tt]o|[Ff]inally|[Aa]re|[Ii]s|[Tt]his|[Ii]ntroducing|[Aa]nnouncing)([[:space:]]+|$)//g')"
+  ORIGLEN="$(printf '%s' "$SUBJECT" | wc -m | tr -d '[:space:]')"
+  TRIMLEN="$(printf '%s' "$TRIMMED" | wc -m | tr -d '[:space:]')"
+  PAYLOAD_AT=$(( ORIGLEN - TRIMLEN ))
+  if [ "$PAYLOAD_AT" -gt 33 ]; then
+    warn "subject payload appears to start past char ${PAYLOAD_AT} — front-load the hook into the first ~33 chars"
+  else
+    ok "subject payload is in the first ~33 chars"
+  fi
+
+  # --- 5. emoji rule (hard) ---------------------------------------------------
+  # Strip ASCII + common punctuation/space; whatever multibyte remains is
+  # treated as emoji/symbol glyphs. all-emoji => no ASCII word chars survive.
+  WORDCHARS="$(printf '%s' "$SUBJECT" | tr -cd 'A-Za-z0-9' | wc -m | tr -d '[:space:]')"
+  EMOJI_BYTES="$(printf '%s' "$SUBJECT" | LC_ALL=C tr -d '\000-\177' | wc -c | tr -d '[:space:]')"
+  # A UTF-8 emoji is ~3-4 bytes; approximate the count conservatively.
+  EMOJI_APPROX=$(( (EMOJI_BYTES + 3) / 4 ))
+  if [ "${WORDCHARS:-0}" -eq 0 ]; then
+    fail "subject has no real word characters — an all-emoji subject trips spam filters"
+  elif [ "${EMOJI_APPROX:-0}" -gt 2 ]; then
+    fail "subject looks like it has ~${EMOJI_APPROX} emoji (> 2) — keep it to <=2, at the end"
+  else
+    ok "subject emoji within limit (<=2, has real words)"
+  fi
+fi
+
+# --- 3 + 4. preview present + not identical (hard) ----------------------------
+if [ -z "$PREVIEW" ]; then
+  fail "no preview/preheader line found — the preview is half the inbox row"
+elif [ "$PREVIEW" = "$SUBJECT" ]; then
+  fail "preview is identical to the subject — make it EXTEND the subject, not repeat it"
+else
+  ok "preview present and differs from the subject"
+fi
+
+# --- 6. exactly one primary CTA (hard on >1, warn on 0) -----------------------
+# CTA convention: a line bearing a [CTA] tag, an arrow call-to-action, or a
+# markdown button-link [text](url). Count distinct CTA-bearing lines.
+CTA_COUNT="$(grep -cE '\[CTA\]|(->|→)[[:space:]]*[A-Za-z].*\[?https?://|\[[^]]+\]\((https?|mailto):' "$FILE" 2>/dev/null || true)"
+# Fallback: also count plain "[CTA]" markers if the above missed link-less ones.
+if [ "${CTA_COUNT:-0}" -eq 0 ]; then
+  CTA_COUNT="$(grep -cE '\[CTA\]' "$FILE" 2>/dev/null || true)"
+fi
+if [ "${CTA_COUNT:-0}" -gt 1 ]; then
+  fail "found ${CTA_COUNT} primary CTAs — one issue gets exactly one primary CTA"
+elif [ "${CTA_COUNT:-0}" -eq 0 ]; then
+  warn "no primary CTA detected (mark it with [CTA] or a button-link) — every issue needs one action"
+else
+  ok "exactly one primary CTA"
+fi
+
+# --- 7. unsubscribe line present (hard) ---------------------------------------
+if grep -Eiq 'unsubscribe|opt[- ]out|darse de baja|cancelar la suscripci|dar-se de baixa|cancel·la la subscripci' "$FILE"; then
+  ok "unsubscribe / opt-out line present"
+else
+  fail "no unsubscribe line found — one-click unsubscribe + a visible footer link are mandatory"
+fi
+
+# --- summary ------------------------------------------------------------------
+printf '\n'
+if [ "$fail_count" -gt 0 ]; then
+  printf '%s%d hard failure(s), %d warning(s)%s\n' "$RED" "$fail_count" "$warn_count" "$NC"
+  exit 1
+fi
+if [ "$warn_count" -gt 0 ]; then
+  if [ "$STRICT" -eq 1 ]; then
+    printf '%s%d warning(s) — failing under --strict%s\n' "$YELLOW" "$warn_count" "$NC"
+    exit 1
+  fi
+  printf '%s%d warning(s), 0 hard failures%s\n' "$YELLOW" "$warn_count" "$NC"
+  exit 0
+fi
+printf '%sall checks passed%s\n' "$GREEN" "$NC"
+exit 0