rsc-universal 0.1.1

package/skills/case-studies/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: case-studies
+description: "Use when turning a real customer win into a case study or testimonial — a metrics-anchored success story or an attributed quote a prospect can act on, including when a great result reads like a brochure and needs to convert. Triggers: 'turn this customer win into a case study', 'we cut their churn 40% — write it up', 'draft a testimonial quote from this customer-interview transcript', 'we have a 40% drop but the write-up sounds like marketing fluff — make it convert', 'build a reusable customer-story template plus an intake/consent form', 'escríbeme un caso de éxito de este cliente con métricas y una cita', 'redacta un cas d'èxit amb mètriques'. NOT the deck that pitches the vision to a room (that is pitch-deck), NOT a long thought-leadership article with no single named customer (that is article-writing)."
+tags: [case-study, testimonial, social-proof, customer-story, conversion]
+recommends: [pitch-deck, article-writing, retention, review-management, brand-voice, landing-copy]
+origin: risco
+---
+
+# case-studies
+
+You write the consent-cleared, metrics-anchored story of a customer who already won — and the short attributed quote that travels with it. Your reader is the *next* skeptical buyer, not your own marketing team. Every line either advances that buyer's decision or it is cut.
+
+A case study is a proof artifact, not a brochure. B2B buyers rank customer testimonials (55%) and case studies (54%) as top trust formats, just behind original research and peer insight (CMI/MarketingProfs, *B2B Content Marketing: 2025 Benchmarks, Budgets & Trends*, Oct 2024). They are reading to de-risk a purchase. A page that praises the vendor and hides the numbers fails that job no matter how polished the prose.
+
+You produce two linked things: the **case study** (the full Challenge → Solution → Result story) and the **portable testimonial quote** (named, titled, one claim) that gets lifted onto a landing page, a slide, or a 30-second clip.
+
+## What this produces / route out first
+
+If the request is not a single customer's measured outcome, hand it off before you write a word.
+
+| The ask | Owner |
+| --- | --- |
+| Document one customer's measured win as proof for the next buyer | **THIS skill** |
+| Sell the company vision/story to a room or investors | `../pitch-deck/SKILL.md` |
+| Long-form / SEO thought-leadership with no single named customer | `../article-writing/SKILL.md` |
+| Keep an existing customer happy — QBR, expansion, churn-save | `../retention/SKILL.md` |
+| Solicit or reply to public reviews / ratings | `../review-management/SKILL.md` |
+| The reusable cross-channel tone-of-voice rules | `../brand-voice/SKILL.md` |
+| Drop the proven quote into a converting page | `../landing-copy/SKILL.md` |
+| Price the offer this win justifies | `pricing` |
+
+The one-sentence call: it is a case study if a real, named customer already got a measured result and consented to be quoted. Vision-to-a-room is `pitch-deck`; no-single-customer is `article-writing`.
+
+## The intake gate — STOP if any of these is missing
+
+Do not start prose until you have all three. A missing piece is a gathering task or an anonymization decision, never an invention.
+
+- **The metric set** — baseline, result, timeframe, and a money figure if the customer permits it. Why: a number with no baseline or timeframe is a claim, not a result. "Increased revenue" is unfalsifiable; "€420k → €1.6M in 11 months" is proof.
+- **The named source** — a real person with title and company for the quote. Why: an anonymous "— a happy client" reads as fabricated and a same-industry, named quote lifts lead quality far more than a generic one.
+- **The consent status** — written sign-off to publish the name, quote, logo, and numbers. Why: publishing an un-consented named customer is the legal failure mode, not a style miss (see below).
+
+If you lack a metric → ask for it or do not claim it. If you lack consent → anonymize honestly ("a 200-seat logistics SaaS") or do not ship. Never round a vague number up to look better.
+
+## The legal + consent floor
+
+This is the hard floor, not a nicety. The FTC Consumer Reviews and Testimonials Rule has been in force since 21 October 2024, with penalties up to ~$53,088 per violation (the FTC's max is inflation-adjusted annually — this is the figure effective 17 Jan 2025; re-check FTC.gov before quoting it as current).
+
+- **Real customer, honest statement.** No fabricated, scripted, or insider testimonial presented as an ordinary customer. If the speaker is an employee, investor, or affiliate, you must add a clear-and-conspicuous material-connection disclosure or drop the quote.
+- **Substantiation.** You may not publish a metric you cannot back with a source. If you cannot point to the data, the number does not go in.
+- **Written consent, kept.** Get sign-off before publishing the name, exact quote, logo, image, and figures. An email confirmation suffices, but it must be retained.
+- **Edit the quote only with approval.** You may tighten a quote for clarity, but the customer must approve the edited wording — you cannot change what they meant.
+
+Carry the consent state in the artifact's front-matter so it is impossible to ship a story whose status is unknown:
+
+```yaml
+---
+customer: "Acme Logistics"
+consent: signed          # signed | pending | anonymized
+approved: 2026-05-28     # date the customer signed off on the exact quote
+quote_source: "interview-2026-05-20.txt"
+---
+```
+
+`consent: pending` means draft-only. `consent: anonymized` means no name/logo/identifying detail ships. Only `consent: signed` may publish a named, quoted, imaged customer. Full intake form, approval-email wording, and substantiation notes live in `references/consent-and-substantiation.md`.
+
+## Case-study anatomy
+
+Write the sections in this order. Each earns its place; cut anything that does not advance the buyer's decision. Target **600–1,200 words** — long enough to prove the result, short enough that a busy buyer finishes it.
+
+1. **Results headline** — one KPI, the single most important number. Why: it is the only line many readers see. "Fraud cut to 0.10% in 8 weeks," not the customer's company name.
+2. **Snapshot box** — above the fold: industry, region, products used, and the headline KPIs. Why: a skeptical buyer self-qualifies in seconds ("same industry as us? same size?").
+3. **Challenge** — the measurable pain before, in the customer's words. Why: the buyer must see their own problem to care about the fix.
+4. **Solution** — what was implemented and how, concrete and specific. Why: vague "we partnered closely" proves nothing; "migrated 1,200 SKUs to the new pricing engine in two sprints" proves capability.
+5. **Result** — the before/after numbers with timeframe, as Context-Achievement-Relevance lines (below). Why: this is the proof the whole piece exists to deliver.
+6. **Attributed quote** — named + title + company, one specific claim. Why: the human voice is the conversion lever, and the quote is what travels onto other surfaces.
+7. **Decision-stage CTA** — one next step matched to where the reader now is ("See pricing," "Book a 20-min fit call"). Why: proof with no next step wastes the intent it just built.
+
+The ordered skeleton and a filled mini-example with real-shaped numbers are in `references/case-study-skeleton.md`.
+
+## Metrics-first
+
+Collect the numbers before you write any prose. The story is built around the data, not decorated with it.
+
+Write each result as a **Context → Achievement → Relevance** line: what changed, the measured lift, and what it was worth.
+
+```text
+Bad:  "The new workflow improved efficiency significantly and the team is much happier."
+Good: "Restructuring lead nurturing (context) drove a 43% conversion lift (achievement),
+       generating €1.2M in additional annual revenue (relevance)."
+
+Bad:  "We helped them process invoices faster."
+Good: "Cut invoice-processing time from 6 days to 4 hours (−97%) within the first quarter."
+```
+
+A result that lacks a baseline or a timeframe is not a result — it is an unfalsifiable claim. Always pair before with after, and always state the window.
+
+## Testimonial / quote craft
+
+The quote is the conversion lever, so make it carry weight. Specific beats glowing. One claim per quote — a quote that says three things says nothing.
+
+```text
+Bad:  "Great product, the team is amazing, highly recommend! — a happy customer"
+Good: "We cut new-hire onboarding from 3 weeks to 2 days — my team stopped dreading
+       every new starter. — Ana Pérez, COO, Acme Logistics"
+```
+
+Rules:
+
+- **Named + title + company.** Attribution is what makes it believable. Anonymous quotes read as invented.
+- **Same industry wins.** A quote from the prospect's own sector lifts lead quality; match where you can.
+- **One concrete claim.** Tie the quote to a number or a felt change, not to adjectives.
+- **The customer's voice, not yours.** If it sounds like your marketing, the buyer discounts it. Approve any edit with the customer.
+
+## Format leverage — write once, cut many
+
+Default to a repurposable structure, because video is now the top-rated B2B content format (58% rate it most effective, with case studies/customer stories close behind at 53% — CMI/MarketingProfs *2025 Benchmarks*, Oct 2024) and testimonials are a measured conversion lever, not decoration: a three-line testimonial block lifted landing-page conversion 34% in VWO's WikiJob A/B test, and Unbounce reported swapping static reviews for video testimonials lifted conversion up to 80%. From one signed-off case study you should be able to cut, with no new approval needed:
+
+- a **pull-stat card** (the headline KPI on its own),
+- a **quote card** (the attributed testimonial),
+- a **30–60s video script** (challenge in one line, result in one line, the quote read aloud).
+
+Write the prose so these fall out cleanly; do not produce a separate brochure for each. (This is the cut, not a full video-production guide — that craft lives elsewhere.)
+
+## Anti-patterns
+
+| Bad | Good |
+| --- | --- |
+| Hero headline is the customer's company name | Hero is the result + a number ("Churn cut 40% in one quarter") |
+| "Increased revenue" with no baseline or window | baseline → result → timeframe, every time |
+| Publish the quote before the customer signs off | Exact-quote written approval first, retained |
+| Anonymous "— a satisfied client" | Named + title + company, or anonymize the whole story honestly |
+| Superlatives: "revolutionary", "seamless", "best-in-class" | Verifiable specifics with units |
+| Insider/employee quote presented as a customer | Clear material-connection disclosure, or drop it |
+| Vendor-praise narrative ("we are proud to...") | Buyer-serving proof ("here is what changed for them") |
+| One 2,500-word wall of prose | 600–1,200 words, snapshot box up top, scannable |
+| A metric you cannot source | Only published numbers you can substantiate on demand |
+
+## Verify + handoffs
+
+`scripts/verify.sh <case-study.md>` is a read-only structural and legal lint. It checks for a quantified hero metric, the required Challenge/Solution/Result sections and snapshot box, an attributed quote, a before→after signal, a CTA, and the `consent:` / `approved:` marker — and it warns on the superlative banlist. It **fails hard** when the hero has no metric, a core section is missing, or consent is unmarked, because shipping an un-consented named quote is the legal risk. It is structural lint only; persuasion quality is the capability eval's job and yours.
+
+Hand off when the piece is done: the proven quote → `../landing-copy/SKILL.md`, the broader narrative → `../article-writing/SKILL.md`, the slide version → `../pitch-deck/SKILL.md`, the public-review angle → `../review-management/SKILL.md`.
+
+## References
+
+- `references/case-study-skeleton.md` — the full ordered template (results headline, snapshot box, C-S-R sections with Context-Achievement-Relevance metric lines, attributed quote block, CTA) plus a filled mini-example with consent front-matter.
+- `references/consent-and-substantiation.md` — intake-form fields, consent/release checklist, exact-quote-approval email wording, FTC substantiation and insider-disclosure notes, anonymization fallback rules.

package/skills/case-studies/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — case-studies
+
+These cases are run by the catalog harness or read by hand. `should_trigger` asserts that the description plus body would route a request to `case-studies` (including the non-obvious "reads like a brochure" symptom and the Spanish phrasing). `should_not_trigger` asserts that the named real sibling — `pitch-deck`, `article-writing`, `retention`, `review-management`, `brand-voice` — owns the request instead. `capability` is a rubric-scored generation: produce a case study from the brief and score it against the `must_include` list (results headline with a number, snapshot box, Challenge→Solution→Result spine, a baseline→result→timeframe metric line, a named attributed quote, a decision-stage CTA, a consent marker, 600–1,200 words, no banned superlatives). There is no bundled automated runner beyond `scripts/verify.sh`, which statically lints a generated case-study markdown for the structural and legal contract.

package/skills/case-studies/evals/cases.yaml

@@ -0,0 +1,63 @@
+skill: case-studies
+
+# Prompts that MUST load `case-studies`. The skill owns one customer's
+# consent-cleared, metrics-anchored success story AND the portable attributed
+# testimonial quote that travels with it. It does NOT pitch the company vision to
+# a room (pitch-deck) or write a long thought-leadership piece with no single
+# named customer (article-writing).
+should_trigger:
+  - prompt: "Turn this customer win into a case study — they cut churn 40% in one quarter."
+    why: "Core job: a single named customer's measured outcome, written up as proof for the next buyer."
+
+  - prompt: "We have a great result but the case study reads like a brochure — make it convert."
+    why: "Non-obvious. The buyer-serving, metrics-first rewrite is this skill's signature; the user names the symptom (brochure, won't convert), not the craft."
+
+  - prompt: "Draft a testimonial quote from this customer-interview transcript."
+    why: "The attributed testimonial quote is the skill's portable sub-artifact, lifted straight from a real customer source."
+
+  - prompt: "Escríbeme un caso de éxito de este cliente con métricas y una cita."
+    why: "Spanish for 'write me a case study of this customer with metrics and a quote' — a direct request for the core artifact plus its quote."
+
+  - prompt: "Build a reusable customer-story template plus the intake/consent form we can reuse."
+    why: "The ordered skeleton and the consent/substantiation intake are both things this skill defines and owns."
+
+  - prompt: "We landed a 97% faster invoicing result for a client and want proof a prospect will actually believe — what do we publish?"
+    why: "Non-obvious. No keyword 'case study'; the ask is buyer-believable proof from one customer win, which is exactly this skill's output and consent gate."
+
+should_not_trigger:
+  - prompt: "Build the investor deck that tells our company story and vision."
+    route_to: pitch-deck
+    why: "Selling the vision/story to a room or investors is pitch-deck, not documenting one customer's measured outcome."
+
+  - prompt: "Write a long SEO thought-leadership article on churn reduction with no single customer."
+    route_to: article-writing
+    why: "General long-form/SEO content with no single named customer is article-writing; case-studies is one customer's story."
+
+  - prompt: "This customer is unhappy — plan the QBR and a churn-save play."
+    route_to: retention
+    why: "Managing the live relationship, QBRs, and churn-saves is retention; case-studies tells the story of one who already won."
+
+  - prompt: "We got a 2-star Google review — draft a public reply and a review-solicitation campaign."
+    route_to: review-management
+    why: "Soliciting and replying to public reviews/ratings is review-management, not authoring a consent-cleared customer story."
+
+  - prompt: "Define our reusable brand tone of voice and writing style guide."
+    route_to: brand-voice
+    why: "The reusable cross-channel voice rules are brand-voice; case-studies writes one story in that voice, it does not define it."
+
+capability:
+  - scenario: >
+      Write a full case study from this brief: B2B SaaS client, support tickets down
+      from 1,200/mo to 300/mo over 90 days, CSAT 72 → 94, one named quote available
+      with the customer's written consent. Industry HR tech, products Helpdesk AI and
+      Knowledge Base.
+    must_include:
+      - "A results headline that leads with a number/KPI, not the customer's company name."
+      - "A snapshot box above the fold: industry, region, products used, and the headline KPIs."
+      - "The Challenge → Solution → Result spine, in that order."
+      - "At least one metric line pairing baseline → result → timeframe (e.g. 1,200/mo → 300/mo over 90 days)."
+      - "A named + titled + company attributed quote making one specific claim."
+      - "A decision-stage CTA matched to the reader's funnel stage."
+      - "A consent/approval marker present (consent: signed / approved date in front-matter)."
+      - "Total length 600–1,200 words."
+      - "No unsubstantiated superlatives (no 'revolutionary', 'seamless', 'best-in-class', 'game-changer', 'world-class')."

package/skills/case-studies/references/case-study-skeleton.md

@@ -0,0 +1,90 @@
+# Case-study skeleton
+
+The ordered template, then a filled mini-example. Keep the whole piece 600–1,200 words.
+
+## Front-matter (carries the legal state)
+
+```yaml
+---
+customer: "<company name, or anonymized descriptor>"
+industry: "<sector>"
+region: "<market/geography>"
+products: ["<product or module used>"]
+consent: signed          # signed | pending | anonymized
+approved: 2026-05-28     # date customer signed off on the exact quote
+quote_source: "<file or link to interview/email the quote came from>"
+---
+```
+
+## Ordered template
+
+```text
+# <RESULTS HEADLINE — one KPI, the single most important number>
+   e.g. "Fraud losses cut to 0.10% in 8 weeks"
+
+> Snapshot
+> Industry: <sector>   Region: <market>   Products: <modules>
+> KPIs: <metric 1>, <metric 2>, <metric 3>   Timeframe: <window>
+
+## The challenge
+<The measurable pain before. 1–2 short paragraphs, ideally with the
+ customer's own framing and a baseline number. Make the buyer recognize
+ their own problem.>
+
+## The solution
+<What was implemented and how — concrete and specific. Name the modules,
+ the rollout, the integration. "Migrated 1,200 SKUs in two sprints," not
+ "partnered closely.">
+
+## The result
+<The proof. Each result as a Context → Achievement → Relevance line, every
+ number paired with a baseline and a timeframe.>
+- <Context>: <Achievement (lift)> → <Relevance ($ or strategic value)>
+- ...
+
+> "<One specific claim tied to a number or a felt change.>"
+> — <Full name>, <Title>, <Company>
+
+## What's next
+<One decision-stage CTA matched to the reader's stage:
+ "See pricing", "Book a 20-min fit call", "Read the implementation guide".>
+```
+
+## Filled mini-example (real-shaped numbers)
+
+```text
+# Support tickets down 75% in 90 days
+
+> Snapshot
+> Industry: B2B SaaS (HR tech)   Region: Iberia   Products: Helpdesk AI, Knowledge Base
+> KPIs: tickets 1,200/mo → 300/mo, CSAT 72 → 94, first-response 9h → 40min
+> Timeframe: 90 days
+
+## The challenge
+By Q1 the support team was fielding 1,200 tickets a month with a 9-hour
+first-response time. CSAT had slipped to 72, and two of five agents were
+at risk of burnout. "We were drowning in repeat questions," the VP of
+Operations said. Every new customer cohort made it worse.
+
+## The solution
+We deployed the Helpdesk AI deflection layer on top of a rebuilt Knowledge
+Base — 140 articles re-tagged and connected to the in-app widget — across
+two sprints. Tier-1 questions were auto-answered; anything unresolved
+routed to a human with full context attached.
+
+## The result
+- Deflecting repeat tier-1 questions cut monthly tickets from 1,200 to 300
+  (−75%) within 90 days → freeing two FTEs to move to onboarding.
+- Faster routing dropped first-response time from 9 hours to 40 minutes
+  → CSAT climbed from 72 to 94.
+- Lower agent load → zero support-team attrition over the following two quarters.
+
+> "We went from drowning in repeat questions to answering the hard ones in
+> under an hour. My team stopped dreading Monday mornings."
+> — María Soler, VP Operations, NorthPeak HR
+
+## What's next
+See how the deflection layer fits your stack — book a 20-minute fit call.
+```
+
+Notes on the example: the headline is the result, not the company; the snapshot lets a buyer self-qualify; every result line pairs before → after → window → value; the quote makes one claim tied to the felt change; the CTA matches a mid-funnel reader. Word count sits inside 600–1,200.

package/skills/case-studies/references/consent-and-substantiation.md

@@ -0,0 +1,80 @@
+# Consent & substantiation
+
+The legal floor for any named, quoted, or imaged customer. No consent → anonymize or do not ship.
+
+## Why this is non-negotiable
+
+The FTC Consumer Reviews and Testimonials Rule has been in force since 21 October 2024. It bans fake and insider testimonials and unsubstantiated claims, with penalties up to ~$53,088 per violation (figure effective 17 Jan 2025 — the FTC inflation-adjusts the statutory max every January, so confirm the current number on FTC.gov before quoting it). A testimonial must be a real customer's honest statement; an insider/employee/affiliate endorsement needs a clear-and-conspicuous material-connection disclosure; you cannot publish a metric you cannot substantiate.
+
+## Intake form — fields to capture at the win
+
+Capture this immediately after the customer wins, while the result is fresh.
+
+- **Customer**: company, contact name, title, email.
+- **Baseline metric(s)**: the number(s) before, with date.
+- **Result metric(s)**: the number(s) after, with date.
+- **Timeframe**: the window between baseline and result.
+- **Money figure**: revenue/cost impact, only if the customer permits publishing it.
+- **Products used**: modules/features in the win.
+- **The quote**: their own words, with the source (interview file, email, review).
+- **Permissions**: may we publish name? title? company? logo? photo? the dollar figure?
+- **Source of every number**: where each metric can be substantiated on demand.
+
+## Consent / release checklist
+
+- [ ] Written consent obtained **before** publishing (email confirmation is enough — keep it).
+- [ ] The **exact quote** as it will appear was sent to the customer and approved.
+- [ ] Permission scope is explicit: name, title, company, logo, image, dollar figure.
+- [ ] Any quote edit for clarity was re-approved by the customer.
+- [ ] Every metric has a retained source.
+- [ ] Front-matter `consent:` set to `signed` (only then may a named version publish).
+- [ ] The consent record is stored where the team can retrieve it later.
+
+## Exact-quote-approval email (wording)
+
+```text
+Subject: Quick approval — your quote for our customer story
+
+Hi <Name>,
+
+Thank you again for the results we achieved together. We'd love to feature
+<Company> in a customer story. Below is the exact quote we'd publish,
+attributed to you as <Title>, <Company>:
+
+  "<the exact quote>"
+
+We'd also like to publish: <name / title / company / logo / the figure $X>.
+
+Could you reply "approved" if this is accurate and you're happy for us to
+publish it as written? If you'd like any wording changed, just send the edit
+and we'll confirm the final version with you before anything goes live.
+
+Thanks,
+<You>
+```
+
+A reply of "approved" (or an approved edit) is the record. Retain it.
+
+## Insider / material-connection disclosure
+
+If the speaker is an employee, founder, investor, reseller, or anyone paid or otherwise connected, you may not present them as an ordinary customer. Either drop the quote, or add a clear, conspicuous disclosure adjacent to it:
+
+```text
+> "<quote>"
+> — <Name>, <Title> (<Name> is an employee of <Company>.)
+```
+
+The disclosure must be impossible to miss — same proximity and prominence as the quote, not buried in a footer.
+
+## Substantiation
+
+You may publish a number only if you can point to its source on request. If the data does not exist or the customer will not let you cite it, the number does not appear. A plausible-sounding figure with no backing is exactly what the rule prohibits.
+
+## Anonymization fallback
+
+When consent is `pending` or refused but the result is still worth telling:
+
+- Strip the name, logo, and any identifying detail (exact headcount, named region if it pinpoints them).
+- Use a truthful descriptor: "a 200-seat logistics SaaS in Iberia."
+- Keep the metrics only if they remain substantiated and non-identifying.
+- Set front-matter `consent: anonymized`. Never attach a real name to an anonymized story later without fresh sign-off.

package/skills/case-studies/scripts/verify.sh

@@ -0,0 +1,161 @@
+#!/usr/bin/env bash
+#
+# verify.sh — structural + legal lint for a `case-studies` markdown artifact.
+#
+# WHAT IT DOES (read-only; never edits a file)
+#   Static, network-free checks on a single generated case-study markdown file.
+#     1. Quantified hero — at least one number+unit / `%` in the first heading
+#        or the lines just under it (HARD FAIL if absent).
+#     2. Required sections — a snapshot/at-a-glance box AND challenge, solution,
+#        result headings (HARD FAIL on a missing core section).
+#     3. Consent marker — a `consent:` or `approved:` flag, ideally in front-matter
+#        (HARD FAIL if unmarked: publishing an un-consented named quote is the legal risk).
+#     4. Attributed quote — a blockquote followed by an attribution line with a name
+#        (warn if a quote is present but unattributed).
+#     5. Before/after signal — a `from X to Y`, `->`, `→`, or `X% ` comparative
+#        (warn if no comparative metric is found).
+#     6. CTA — a call-to-action line near the end (warn if absent).
+#     7. Superlative banlist — revolutionary, best-in-class, game-changer,
+#        world-class, seamless, cutting-edge (warn each).
+#
+#   Hard failures exit 1. A missing/empty file (or no target) is reported and
+#   exits 0 — no false failure on a clean/empty target. Pure bash + grep/awk.
+#   It is a lint, not a persuasion oracle: it gates structure and the legal
+#   contract, nothing about whether the story actually converts.
+#
+# HOW TO RUN
+#   ./verify.sh path/to/case-study.md     # lint one case study
+#   ./verify.sh                           # no target -> nothing to check, exit 0
+#
+# EXIT CODES
+#   0  clean, or nothing to check
+#   1  a hard structural/legal failure
+#   2  bad usage
+#
+# Runs on stock macOS bash 3.2.
+
+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; warn_count=0; fail_count=0
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; ok_count=$((ok_count + 1)); }
+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,38p' "$0" | sed 's/^# \{0,1\}//'; }
+
+# --- arg parse --------------------------------------------------------------
+TARGET=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -h|--help) usage; exit 0 ;;
+    -*) printf 'unknown flag: %s\n' "$1" >&2; usage >&2; exit 2 ;;
+    *) TARGET="$1"; shift ;;
+  esac
+done
+
+# No target, or empty/missing file -> nothing to check, clean exit (no false fail).
+if [ -z "$TARGET" ]; then
+  ok "no case-study path given — nothing to lint"
+  printf '\nok=%d warn=%d fail=%d\n' "$ok_count" "$warn_count" "$fail_count"
+  exit 0
+fi
+if [ ! -f "$TARGET" ]; then
+  warn "file not found: $TARGET — nothing to lint"
+  printf '\nok=%d warn=%d fail=%d\n' "$ok_count" "$warn_count" "$fail_count"
+  exit 0
+fi
+if [ ! -s "$TARGET" ]; then
+  warn "file is empty: $TARGET — nothing to lint"
+  printf '\nok=%d warn=%d fail=%d\n' "$ok_count" "$warn_count" "$fail_count"
+  exit 0
+fi
+
+# --- 1. quantified hero -----------------------------------------------------
+# The hero = first H1 plus the next ~5 non-blank content lines under it.
+HERO="$(awk '
+  /^# [^#]/ { grab=1; print; n=0; next }
+  grab && NF { print; n++; if (n>=5) grab=0 }
+' "$TARGET")"
+if [ -z "$HERO" ]; then
+  fail "no H1/hero heading found (need a results headline)"
+elif printf '%s' "$HERO" | grep -qE '[0-9]+([.,][0-9]+)?[[:space:]]*(%|x|×|k|K|M|min|h|hours?|days?|weeks?|months?|€|\$|£)|[€\$£][0-9]'; then
+  ok "hero carries a quantified metric"
+else
+  fail "hero headline has no number+unit (lead with the result, e.g. 'Churn cut 40% in one quarter')"
+fi
+
+# --- 2. required sections ---------------------------------------------------
+sect() { grep -qiE "^#{1,4}[[:space:]].*(${1})" "$TARGET"; }
+# Snapshot box: a heading OR a blockquote labelled snapshot/at-a-glance.
+if sect 'snapshot|at[ -]?a[ -]?glance|overview' \
+   || grep -qiE '^>[[:space:]]*(snapshot|at[ -]?a[ -]?glance|overview)' "$TARGET"; then
+  ok "snapshot / at-a-glance box present"
+else
+  fail "no snapshot/at-a-glance box (need industry/region/products/KPIs above the fold)"
+fi
+if sect 'challenge|problem|reto|desafí'; then ok "challenge section present"; else fail "no challenge section"; fi
+if sect 'solution|solució|solucion';    then ok "solution section present";  else fail "no solution section";  fi
+if sect 'result|outcome|resultat|resultado'; then ok "result section present"; else fail "no result section"; fi
+
+# --- 3. consent marker (HARD) ----------------------------------------------
+if grep -qiE '^[[:space:]]*(consent|approved)[[:space:]]*:' "$TARGET"; then
+  ok "consent/approval marker present"
+else
+  fail "no consent: or approved: marker — un-consented named quotes are the legal risk; add the front-matter flag"
+fi
+
+# --- 4. attributed quote ----------------------------------------------------
+# A blockquote line, then somewhere a `— Name, Title` attribution.
+if grep -qE '^>[[:space:]]*"' "$TARGET" || grep -qE '^>[[:space:]]*[A-Za-z]' "$TARGET"; then
+  if grep -qE '^>?[[:space:]]*[—-][[:space:]]*[A-Z]' "$TARGET"; then
+    ok "attributed quote present (blockquote + attribution line)"
+  else
+    warn "quote present but no attribution line found (need '— Name, Title, Company')"
+  fi
+else
+  warn "no blockquote testimonial found"
+fi
+
+# --- 5. before/after signal -------------------------------------------------
+if grep -qiE 'from[[:space:]]+[^ ]+[[:space:]]+to[[:space:]]|->|→|[0-9]+([.,][0-9]+)?[[:space:]]*%' "$TARGET"; then
+  ok "before/after or comparative metric signal found"
+else
+  warn "no baseline→result signal (pair every number with a baseline and a timeframe)"
+fi
+
+# --- 6. CTA -----------------------------------------------------------------
+if grep -qiE "(book|schedule|get started|see pricing|request|contact|talk to|sign up|learn more|demo|read the|what's next|próxim|next step)" "$TARGET"; then
+  ok "a CTA-shaped line is present"
+else
+  warn "no decision-stage CTA found near the end"
+fi
+
+# --- 7. superlative banlist -------------------------------------------------
+# Scan body outside fenced code blocks (Bad/Good examples sit in fences).
+BODY="$(awk '/^```/{f=!f; next} !f{print}' "$TARGET")"
+ban_hits=0
+for phrase in "revolutionary" "best-in-class" "game-changer" "game changer" \
+              "world-class" "world class" "seamless" "cutting-edge" "cutting edge"; do
+  if printf '%s\n' "$BODY" | grep -iqF "$phrase"; then
+    warn "unsubstantiated superlative: \"$phrase\" — replace with a verifiable specific"
+    ban_hits=$((ban_hits + 1))
+  fi
+done
+[ "$ban_hits" -eq 0 ] && ok "superlative banlist clean"
+
+# --- summary ----------------------------------------------------------------
+printf '\nok=%d warn=%d fail=%d\n' "$ok_count" "$warn_count" "$fail_count"
+cat <<'EOF'
+
+Note: this lints structure and the legal contract only — it does not judge whether
+the story actually persuades. That is the capability eval's job, and yours.
+EOF
+
+if [ "$fail_count" -gt 0 ]; then exit 1; fi
+exit 0