@monoes/monomindcli 2.15.3 → 2.15.5

package/org-skills/ad-creative/SKILL.md

@@ -0,0 +1,428 @@
+---
+name: ad-creative
+description: "When the user wants to generate, iterate, or scale ad creative — headlines, descriptions, primary text, or full ad variations — for any paid advertising platform."
+tags: ["marketing","writing"]
+tools: []
+license: MIT
+source: https://github.com/coreyhaines31/marketingskills
+source_path: "skills/ad-creative"
+source_commit: 5b2c0007766c6a1cf1d53fd8fc73e979e0821022
+---
+# Ad Creative
+
+You are an expert performance creative strategist. Your goal is to generate high-performing ad creative at scale — headlines, descriptions, and primary text that drive clicks and conversions — and iterate based on real performance data.
+
+## Before Starting
+
+**Check for product marketing context first:**
+If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
+
+Gather this context (ask if not provided):
+
+### 1. Platform & Format
+- What platform? (Google Ads, Meta, LinkedIn, TikTok, Twitter/X)
+- What ad format? (Search RSAs, display, social feed, stories, video)
+- Are there existing ads to iterate on, or starting from scratch?
+
+### 2. Product & Offer
+- What are you promoting? (Product, feature, free trial, demo, lead magnet)
+- What's the core value proposition?
+- What makes this different from competitors?
+
+### 3. Audience & Intent
+- Who is the target audience?
+- What stage of awareness? (Problem-aware, solution-aware, product-aware)
+- What pain points or desires drive them?
+
+### 4. Performance Data (if iterating)
+- What creative is currently running?
+- Which headlines/descriptions are performing best? (CTR, conversion rate, ROAS)
+- Which are underperforming?
+- What angles or themes have been tested?
+
+### 5. Constraints
+- Brand voice guidelines or words to avoid?
+- Compliance requirements? (Industry regulations, platform policies)
+- Any mandatory elements? (Brand name, trademark symbols, disclaimers)
+
+---
+
+## How This Skill Works
+
+This skill supports four modes:
+
+### Mode 1: Generate from Scratch
+When starting fresh, you generate a full set of ad creative based on product context, audience insights, and platform best practices.
+
+### Mode 2: Iterate from Performance Data
+When the user provides performance data (CSV, paste, or API output), you analyze what's working, identify patterns in top performers, and generate new variations that build on winning themes while exploring new angles.
+
+The core loop:
+
+```
+Pull performance data → Identify winning patterns → Generate new variations → Validate specs → Deliver
+```
+
+### Mode 3: Scaled Static Batches (Grounded)
+For recurring static ad production at volume (e.g., 50 concepts per batch), work from a **grounded inputs corpus** and the [static ad template library](references/static-ad-templates.md). Every concept must trace to real source material — see "Grounded Inputs" below. To run this on a daily or weekly cadence, see the daily-creative-drop loop in **marketing-loops**. To present a batch for client or stakeholder approval, produce a [creative review page](references/creative-review-page.md).
+
+### Mode 4: Creative Strategy Loop
+For deciding **which ads are worth making before making them**: synthesize three signal sources (account performance, customer language, external organic) into evidence-ranked concepts, branch the creative mix on account state (exploration vs. scaling), maintain a capacity-checked roadmap with production tiers, and run a monthly retro that feeds the next slate. The full system lives in [references/creative-roadmap.md](references/creative-roadmap.md); for hook generation and funnel-stage diagnosis inside any mode, load [references/hook-system.md](references/hook-system.md).
+
+---
+
+## Grounded Inputs
+
+Most AI ad generation fails on input grounding, not output quality: ungrounded generation produces plausible-sounding ads based on training data, not on what converts for this brand. For scaled production (Mode 3), maintain a durable inputs corpus:
+
+```
+inputs/
+  winning-ads/   10-20 screenshots of the highest-performing ads from the last 90 days
+  reviews/       50-100 customer reviews (Trustpilot, G2, Amazon, App Store) as .md/.txt
+  comments/      Top comments from existing ad campaigns — objections, unprompted praise, customer-raised angles
+brand/           Brand voice doc, hex codes, logo, product/screenshot assets
+outputs/         Dated batch folders (outputs/YYYY-MM-DD/)
+```
+
+**Why each input matters:**
+- **Winning ads** carry the hooks, structures, and angles already proven for this brand
+- **Reviews** carry the exact language buyers use for pain, transformation, and unexpected benefits — pull copy from them verbatim rather than paraphrasing
+- **Ad comments** are the most-skipped and highest-value input: objections ("but does it work for X?") become FAQ Card ads, and unprompted praise surfaces angles you didn't write
+
+**Grounding rules:**
+- Every concept cites its source (which review, winning ad, or comment it traces to)
+- No invented claims, stats, or testimonials — ever
+- If `inputs/winning-ads/` or `inputs/reviews/` is empty, stop and ask the user to populate it before generating. Do not generate ungrounded concepts as a fallback.
+- Inputs decay: refresh `inputs/winning-ads/` as new ads scale; refresh `inputs/reviews/` and `inputs/comments/` monthly
+
+---
+
+## Platform Specs
+
+Platforms reject or truncate creative that exceeds these limits, so verify every piece of copy fits before delivering.
+
+### Google Ads (Responsive Search Ads)
+
+| Element | Limit | Quantity |
+|---------|-------|----------|
+| Headline | 30 characters | Up to 15 |
+| Description | 90 characters | Up to 4 |
+| Display URL path | 15 characters each | 2 paths |
+
+**RSA rules:**
+- Headlines must make sense independently and in any combination
+- Pin headlines to positions only when necessary (reduces optimization)
+- Include at least one keyword-focused headline
+- Include at least one benefit-focused headline
+- Include at least one CTA headline
+
+### Meta Ads (Facebook/Instagram)
+
+| Element | Limit | Notes |
+|---------|-------|-------|
+| Primary text | 125 chars visible (up to 2,200) | Front-load the hook |
+| Headline | 40 characters recommended | Below the image |
+| Description | 30 characters recommended | Below headline |
+| URL display link | 40 characters | Optional |
+
+### LinkedIn Ads
+
+| Element | Limit | Notes |
+|---------|-------|-------|
+| Intro text | 150 chars recommended (600 max) | Above the image |
+| Headline | 70 chars recommended (200 max) | Below the image |
+| Description | 100 chars recommended (300 max) | Appears in some placements |
+
+### TikTok Ads
+
+| Element | Limit | Notes |
+|---------|-------|-------|
+| Ad text | 80 chars recommended (100 max) | Above the video |
+| Display name | 40 characters | Brand name |
+
+### Twitter/X Ads
+
+| Element | Limit | Notes |
+|---------|-------|-------|
+| Tweet text | 280 characters | The ad copy |
+| Headline | 70 characters | Card headline |
+| Description | 200 characters | Card description |
+
+For detailed specs and format variations, see [references/platform-specs.md](references/platform-specs.md).
+
+---
+
+## Generating Ad Visuals
+
+**To decide *which format to make next*** (before briefing any specific ad), consult the Meta creative format taxonomy in [references/meta-creative-formats.md](references/meta-creative-formats.md) — a prioritized S→F catalog of ~51 formats ranked by one question: is it a *unicorn scaler* that punctures cold net-new audiences, or a *supporting cast* member that only converts mid-funnel? Leads with the persona-based Andromeda context (why creator-fronted formats top the list), S-tier callouts (founder content, partnership ads, VSL), the A-tier bench, and explicit F-tier de-prioritization (press, podcast, notes-app fake-native). Use it to pick a format and build a portfolio; the how-to-build detail lives in the static/video references below. For the account-level kill/keep/scale math once ads are live, cross-reference the `ads` skill's [meta-decision-system.md](../../ads/references/meta-decision-system.md).
+
+**For static ad structure**, use the template library in [references/static-ad-templates.md](references/static-ad-templates.md) — layout frameworks (Us vs. Them, Stat Callout, Review Card, Before/After, Founder Message, FAQ Card, Grid Static, Callout, and more) with copy slots, DTC and SaaS examples, and per-concept output format. Each template carries a **tier (S–F)** and **funnel role** (unicorn cold-scaler vs. mid-funnel supporting cast) so you reach for the right one first. Cycle through templates rather than clustering on favorites — but weight toward the S/A tiers when the goal is cold net-new reach.
+
+**For iOS-native reveal video ads** — iMessage chat reveals (scripted thread unfolds bubble-by-bubble: screenshot hook → friend asks "what app is that?" → brand + promo code reveal → end card), ChatGPT reveals (typed question → streaming answer), Apple Notes reveals (a confessional note typed live), and AirDrop reveals (an incoming share where the accept-tap is the reveal) — see [references/imessage-video-ads.md](references/imessage-video-ads.md) for surface selection, the six concept angles, script and pacing rules, production routes (off-the-shelf, Playwright + ffmpeg pipeline, Remotion), craft details that sell the illusion, and the grounding/compliance rules for dramatized conversations (strictest for fabricated AI answers).
+
+**For faceless motion-style video ads** — fully generated 15–45s concept/explainer videos (styled poster stills → image-to-video "living" motion → TTS narration → word-timed captions; roughly $3–6 and ~15 minutes per finished video) — see [references/motion-video-ads.md](references/motion-video-ads.md) for the provider-agnostic pipeline, a nine-style visual library with fill-in prompt formulas — five characterful looks (screen-print collage, flat vector explainer, papercraft diorama, pop-art comic, claymation) plus four brand-flexible token-driven styles (monoline editorial, Swiss typographic, wireglow, duotone screenprint) driven by a brand-slots contract (FIELD / INK / ACCENT / TYPE FEEL) — the motion prompt formula, and hard-earned QC gotchas (maker-hands intrusion, final-two-seconds drift, caption/label collision, TTS/whisper sound-alikes).
+
+**For creator/UGC short-form video** — a tiered format library (reaction+demo hard cuts, "no yapping" split-screen tutorials, greenscreen reactions, plus Yapper, amateur investigation, David & Goliath, authority, VSL, green-screen commentary, conversation, duet/reaction, ASMR, and street-interview formats, each with a scale-vs-support tier and mechanics) and founder / organic-vlog structures (hero's journey, math, shiny-object, niche-guide, the three-capture shooting system, and the 0.5–1s cut formula) for TikTok/Reels/Shorts growth and paid — see [references/short-form-video-specs.md](references/short-form-video-specs.md). It also carries the **vertical video production spec** that applies to *all* 9:16 video this skill makes: the cross-platform safe-zone band (720×1200 text-safe area — the most-missed constraint), the classic TikTok caption recipe (white fill + black stroke, no pill), static-caption auto-sizing, and the organic-vs-baked-music decision that affects reach. Load it before producing any vertical video.
+
+For image and video generation tools, see [references/generative-tools.md](references/generative-tools.md) for the complete guide covering:
+
+- **Image generation** — Nano Banana Pro (Gemini), Flux, Ideogram for static ad images
+- **Video generation** — Veo, Kling, Runway, Sora, Seedance, Higgsfield for video ads
+- **Voice & audio** — ElevenLabs, OpenAI TTS, Cartesia for voiceovers, cloning, multilingual
+- **Code-based video** — Remotion for templated, data-driven video at scale
+- **Platform image specs** — Correct dimensions for every ad placement
+- **Cost comparison** — Pricing for 100+ ad variations across tools
+
+**Recommended workflow for scaled production:**
+1. Generate hero creative with AI tools (exploratory, high-quality)
+2. Build Remotion templates based on winning patterns
+3. Batch produce variations with Remotion using data feeds
+4. Iterate — AI for new angles, Remotion for scale
+
+---
+
+## Generating Ad Copy
+
+### Step 1: Define Your Angles
+
+Before writing individual headlines, establish 3-5 distinct **angles** — different reasons someone would click. Each angle should tap into a different motivation.
+
+**Common angle categories:**
+
+| Category | Example Angle |
+|----------|---------------|
+| Pain point | "Stop wasting time on X" |
+| Outcome | "Achieve Y in Z days" |
+| Social proof | "Join 10,000+ teams who..." |
+| Curiosity | "The X secret top companies use" |
+| Comparison | "Unlike X, we do Y" |
+| Urgency | "Limited time: get X free" |
+| Identity | "Built for [specific role/type]" |
+| Contrarian | "Why [common practice] doesn't work" |
+
+### Step 2: Generate Variations per Angle
+
+For each angle, generate multiple variations. Vary:
+- **Word choice** — synonyms, active vs. passive
+- **Specificity** — numbers vs. general claims
+- **Tone** — direct vs. question vs. command
+- **Structure** — short punch vs. full benefit statement
+
+### Step 3: Validate Against Specs
+
+Before delivering, check every piece of creative against the platform's character limits. Flag anything that's over and provide a trimmed alternative.
+
+### Step 4: Organize for Upload
+
+Present creative in a structured format that maps to the ad platform's upload requirements.
+
+---
+
+## Iterating from Performance Data
+
+When the user provides performance data, follow this process:
+
+### Step 1: Analyze Winners
+
+Look at the top-performing creative (by CTR, conversion rate, or ROAS — ask which metric matters most) and identify:
+
+- **Winning themes** — What topics or pain points appear in top performers?
+- **Winning structures** — Questions? Statements? Commands? Numbers?
+- **Winning word patterns** — Specific words or phrases that recur?
+- **Character utilization** — Are top performers shorter or longer?
+
+### Step 2: Analyze Losers
+
+Look at the worst performers and identify:
+
+- **Themes that fall flat** — What angles aren't resonating?
+- **Common patterns in low performers** — Too generic? Too long? Wrong tone?
+
+### Step 3: Generate New Variations
+
+Create new creative that:
+- **Doubles down** on winning themes with fresh phrasing
+- **Extends** winning angles into new variations
+- **Tests** 1-2 new angles not yet explored
+- **Avoids** patterns found in underperformers
+
+### Step 4: Document the Iteration
+
+Track what was learned and what's being tested:
+
+```
+## Iteration Log
+- Round: [number]
+- Date: [date]
+- Top performers: [list with metrics]
+- Winning patterns: [summary]
+- New variations: [count] headlines, [count] descriptions
+- New angles being tested: [list]
+- Angles retired: [list]
+```
+
+---
+
+## Writing Quality Standards
+
+### Headlines That Click
+
+**Strong headlines:**
+- Specific ("Cut reporting time 75%") over vague ("Save time")
+- Benefits ("Ship code faster") over features ("CI/CD pipeline")
+- Active voice ("Automate your reports") over passive ("Reports are automated")
+- Include numbers when possible ("3x faster," "in 5 minutes," "10,000+ teams")
+
+**Avoid:**
+- Jargon the audience won't recognize
+- Claims without specificity ("Best," "Leading," "Top")
+- All caps or excessive punctuation
+- Clickbait that the landing page can't deliver on
+
+### Descriptions That Convert
+
+Descriptions should complement headlines, not repeat them. Use descriptions to:
+- Add proof points (numbers, testimonials, awards)
+- Handle objections ("No credit card required," "Free forever for small teams")
+- Reinforce CTAs ("Start your free trial today")
+- Add urgency when genuine ("Limited to first 500 signups")
+
+---
+
+## Output Formats
+
+### Standard Output
+
+Organize by angle, with character counts:
+
+```
+## Angle: [Pain Point — Manual Reporting]
+
+### Headlines (30 char max)
+1. "Stop Building Reports by Hand" (29)
+2. "Automate Your Weekly Reports" (28)
+3. "Reports Done in 5 Min, Not 5 Hr" (31) <- OVER LIMIT, trimmed below
+   -> "Reports in 5 Min, Not 5 Hrs" (27)
+
+### Descriptions (90 char max)
+1. "Marketing teams save 10+ hours/week with automated reporting. Start free." (73)
+2. "Connect your data sources once. Get automated reports forever. No code required." (80)
+```
+
+### Bulk CSV Output
+
+When generating at scale (10+ variations), offer CSV format for direct upload:
+
+```csv
+headline_1,headline_2,headline_3,description_1,description_2,platform
+"Stop Manual Reporting","Automate in 5 Minutes","Join 10K+ Teams","Save 10+ hrs/week on reports. Start free.","Connect data sources once. Reports forever.","google_ads"
+```
+
+### Static Batch Output (Mode 3)
+
+For scaled static batches, save to a dated folder with an index:
+
+```
+outputs/YYYY-MM-DD/
+  INDEX.md        # every concept: template type + grounding source, scannable in 2 min
+  concepts/       # one .md per concept: headline, body, visual description, image prompt, grounding
+  images/         # generated images, if an image tool is configured
+```
+
+Per-concept format is defined in [references/static-ad-templates.md](references/static-ad-templates.md). The human workflow this supports: open the folder, scan INDEX.md, pick the best 5-10 for testing — picking 5 winners from 50 concepts yields better creative than picking 5 from 10.
+
+### Creative Review Page (client / stakeholder approval)
+
+When a person who isn't you needs to review and pick — a client, a partner, a stakeholder — produce a **creative review page**: a self-contained HTML artifact that presents each concept as an in-feed platform mockup (Instagram/Facebook, with a whitelist-handle toggle), breaks carousels into a labeled frame-by-frame storyboard, lets them toggle headline/copy variations, and discloses what's grounded in real assets. It's the visual upgrade to INDEX.md — a decision made off one link instead of by reading markdown. The template ships at [assets/creative-review-template.html](assets/creative-review-template.html) (one file, no build, hostable anywhere); populate its `DATA` object from your generated concepts. Full data model, grounding rules (the disclosure block is required), and delivery in [references/creative-review-page.md](references/creative-review-page.md).
+
+### Iteration Report
+
+When iterating, include a summary:
+
+```
+## Performance Summary
+- Analyzed: [X] headlines, [Y] descriptions
+- Top performer: "[headline]" — [metric]: [value]
+- Worst performer: "[headline]" — [metric]: [value]
+- Pattern: [observation]
+
+## New Creative
+[organized variations]
+
+## Recommendations
+- [What to pause, what to scale, what to test next]
+```
+
+---
+
+## Batch Generation Workflow
+
+For large-scale creative production (Anthropic's growth team generates 100+ variations per cycle):
+
+### 1. Break into sub-tasks
+- **Headline generation** — Focused on click-through
+- **Description generation** — Focused on conversion
+- **Primary text generation** — Focused on engagement (Meta/LinkedIn)
+
+### 2. Generate in waves
+- Wave 1: Core angles (3-5 angles, 5 variations each)
+- Wave 2: Extended variations on top 2 angles
+- Wave 3: Wild card angles (contrarian, emotional, specific)
+
+### 3. Quality filter
+- Remove anything over character limit
+- Remove duplicates or near-duplicates
+- Flag anything that might violate platform policies
+- Ensure headline/description combinations make sense together
+
+---
+
+## Common Mistakes
+
+- **Writing headlines that only work together** — RSA headlines get combined randomly
+- **Ignoring character limits** — Platforms truncate without warning
+- **All variations sound the same** — Vary angles, not just word choice
+- **No CTA headlines** — RSAs need action-oriented headlines to drive clicks; include at least 2-3
+- **Generic descriptions** — "Learn more about our solution" wastes the slot
+- **Iterating without data** — Gut feelings are less reliable than metrics
+- **Generating without grounding** — Ungrounded concepts read like every other ad in the feed; feed the skill winning ads, reviews, and comments first
+- **Skipping the comments input** — Ad comments hold the objections and angles customers raise themselves; those usually convert best
+- **Testing too many things at once** — Change one variable per test cycle
+- **Retiring creative too early** — Allow 1,000+ impressions before judging
+
+---
+
+## Tool Integrations
+
+For pulling performance data and managing campaigns, see the [tools registry](../../tools/REGISTRY.md).
+
+| Platform | Pull Performance Data | Manage Campaigns | Guide |
+|----------|:---------------------:|:----------------:|-------|
+| **Google Ads** | `google-ads campaigns list`, `google-ads reports get` | `google-ads campaigns create` | [google-ads.md](../../tools/integrations/google-ads.md) |
+| **Meta Ads** | `meta-ads insights get` | `meta-ads campaigns list` | [meta-ads.md](../../tools/integrations/meta-ads.md) |
+| **LinkedIn Ads** | `linkedin-ads analytics get` | `linkedin-ads campaigns list` | [linkedin-ads.md](../../tools/integrations/linkedin-ads.md) |
+| **TikTok Ads** | `tiktok-ads reports get` | `tiktok-ads campaigns list` | [tiktok-ads.md](../../tools/integrations/tiktok-ads.md) |
+
+### Workflow: Pull Data, Analyze, Generate
+
+```bash
+# 1. Pull recent ad performance
+node tools/clis/google-ads.js reports get --type ad_performance --date-range last_30_days
+
+# 2. Analyze output (identify top/bottom performers)
+# 3. Feed winning patterns into this skill
+# 4. Generate new variations
+# 5. Upload to platform
+```
+
+---
+
+## Related Skills
+
+- **ads**: For campaign strategy, targeting, budgets, and optimization
+- **marketing-loops**: For running static batch generation on a recurring cadence (the daily-creative-drop loop)
+- **customer-research**: For mining reviews and comments when building the grounded inputs corpus
+- **copywriting**: For landing page copy (where ad traffic lands)
+- **ab-testing**: For structuring creative tests with statistical rigor
+- **marketing-psychology**: For psychological principles behind high-performing creative
+- **copy-editing**: For polishing ad copy before launch

package/org-skills/ad-creative/references/creative-review-page.md

@@ -0,0 +1,106 @@
+# The Creative Review Page
+
+A shareable, self-contained web page that presents generated ad concepts for a client or stakeholder to **review and pick** — the visual upgrade to `INDEX.md`. Where the markdown outputs are built for the operator, the review page is built for the person approving the spend: it shows each concept as an in-feed platform mockup, breaks carousels into a labeled frame-by-frame storyboard, lets them toggle copy variations, and discloses what's grounded in real assets.
+
+The template ships at [assets/creative-review-template.html](../assets/creative-review-template.html). It's one file — inline CSS and JS, no build, no dependencies, no network. Open it locally, host it on any static host (Vercel/Netlify/GitHub Pages), or hand off the `.html` file directly.
+
+## When to produce one
+
+- **Presenting a batch for approval** — after Mode 1 or Mode 3 generation, package the top concepts into a review page instead of (or alongside) `INDEX.md`. Picking 5 of 50 is a *visual* decision; a client shouldn't have to read markdown to make it.
+- **Pitching a whitelist / co-branded partnership** — the format the source pattern was built for: show the partner exactly what the ad looks like under each handle, with the rollout mechanics spelled out.
+- **A monthly slate review** (Mode 4) — render the slate's concepts so the account-state call and the pick happen off one link.
+
+Don't produce one for a single headline tweak or a quick internal gut-check — the markdown output is faster. Reach for the review page when a human who isn't you needs to choose.
+
+## How it's built
+
+The template renders entirely from a JSON block near the top of the file — `<script type="application/json" id="review-data">`. Populate it from your generated concepts and everything else renders — tabs, previews, storyboard, copy panel. You do not edit the render code below the data block. The annotated model below is shown with `//` comments for readability; **the file itself is strict JSON** — no comments, no trailing commas (see "Populating the data safely").
+
+### Data model
+
+```jsonc
+{
+  project: {
+    brand: "Truvani",              // required
+    agency: "Light Labs",          // optional — adds the co-brand line + the default handle fallback (partner label/initials)
+    date: "2026-07-12",            // optional
+    note: "one-line context"       // optional
+  },
+  platforms: ["instagram", "facebook"],   // previews to offer; first is the default. Supported: instagram, facebook
+  concepts: [                              // each concept is one strategic ANGLE (see SKILL.md "Define Your Angles")
+    {
+      name: "Heavy-Metal Proof",           // required — the angle name
+      tagline: "Lifestyle hero, then the lab results",   // one line, what makes this concept distinct
+      handles: [                            // optional. 1 entry = normal post; 2 = whitelist handle toggle
+        { name: "truvani", partner: "Paid partnership with lightlabs", initials: "TV" },
+        { name: "Light Labs", partner: "Paid partnership with truvani", initials: "LL" }
+      ],
+      frames: [                             // 1 frame = single ad; multiple = carousel storyboard
+        {
+          label: "Hook",                    // the frame's job in the narrative arc
+          prompt: "Product bag hero on soft pink, gold-lace overlay",  // image description (shown as placeholder if no image)
+          image: "images/heavy-metal-01.png",   // optional — URL, relative path, or data URI; omit for text-only concepts
+          headline: "Finally — a plant-based protein that's third-party tested for heavy metals.",  // optional per-frame overlay
+          headlineTheme: "dark"             // optional: "dark" (default, white text) or "light" (dark text on light imagery)
+        }
+        // … one object per frame
+      ],
+      headlines: [                          // selectable variations; the picked one overlays frame 1 in the preview
+        "Finally — a plant-based protein that's third-party tested for heavy metals.",
+        "We tested our protein for heavy metals. Here's what an independent lab found.",
+        "Most protein powders are never tested for heavy metals. Ours is."
+      ],
+      primaryText: "The caption / body copy.",
+      destination: { url: "shop.truvani.com", cta: "Shop now", offer: "72% OFF Protein Starter Kit" },
+      rollout: {                            // optional — the mechanics of how this runs (whitelist, launch plan)
+        title: "How the whitelist runs",
+        steps: ["step 1", "step 2", "…"]
+      },
+      grounding: "What in this concept is real — the required disclosure. See below."
+    }
+    // … 2–4 concepts is the sweet spot; more than that and the tabs stop being a decision
+  ]
+}
+```
+
+### The frame storyboard = a carousel narrative arc
+
+A concept's `frames` are its storyboard. Label each frame by the *job it does*, not its content — `Hook`, `The problem`, `The results`, `The ask`. This is the same narrative-arc thinking as the carousel frameworks: a proof-led concept is literally Hook → Problem → Mechanism → Results → Context → Ask. For the five reusable carousel arcs (Value-Stack, Problem-Proof, Hack List, Rant Callout, Demo Walkthrough), see `carousel-frameworks.md` in the **social** skill and pick the arc that fits the angle before writing frames.
+
+### Images vs. placeholders
+
+Every frame renders one of two ways:
+- **`image` provided** — the real creative (from the Mode 3 `images/` folder, a hosted URL, or a data URI) fills the frame.
+- **`image` omitted** — a styled placeholder shows the frame `label` + `prompt`. This is the intended state for concepts that are copy + image-prompt but not yet rendered to image — the review page is useful *before* images exist, and stays useful as they get filled in.
+
+Ship review pages with placeholders freely; they communicate the concept. Swap in images as they're generated.
+
+## Grounding — the disclosure block is required
+
+Every concept must carry a `grounding` line, and it must be true. This is the same rule as the Grounded Inputs corpus, surfaced to the client: state exactly what is real (which lab panel, which review, which product photography) and, by omission, what is illustrative. The source pattern's line is the model — *"Results are Truvani's actual Light Labs panel (Vanilla, tested Nov 13, 2025). Imagery is Truvani's own product & lifestyle photography."*
+
+Never present invented stats, fabricated test results, or stock imagery as the brand's own. If a concept's proof isn't real yet, the grounding line says so ("Results shown are illustrative pending the lab panel") — a review page that launders fiction as fact is worse than no review page.
+
+## Populating the data safely
+
+The `DATA` lives in a `<script type="application/json" id="review-data">` block — it's inert data (parsed with `JSON.parse`), not executable code, so a value can never run as script. Two rules when you write it:
+
+- **Valid JSON only** — double-quoted keys and strings, no comments, no trailing commas. (The page shows a clear error banner if the JSON is malformed, so a typo fails loud, not silent.)
+- **Escape `<` as `\u003c` in every text value.** A value literally containing `</script>` would otherwise close the data block early. Since agents write the JSON, apply this escape mechanically to all string values. All values are HTML-escaped again at render time, so this is defense-in-depth, but the source-level escape is the one that matters — do it.
+
+## Producing and delivering it
+
+1. Copy `assets/creative-review-template.html` into the batch's output folder as `review.html` (e.g. `outputs/YYYY-MM-DD/review.html`).
+2. Replace the `DATA` object with the real project — concepts, frames, copy, grounding. Populate `image` paths for any frames you've rendered (keep them relative to the html file so the folder stays portable).
+3. Verify it renders: open it in a browser, click through every concept tab, both platform and handle toggles, and each frame in the storyboard.
+4. Deliver: hand off the folder (html + `images/`), or host it. For a client link, `vercel deploy` or any static host works — it's a single page with local assets.
+
+Keep the review page next to the markdown outputs, not instead of them: `INDEX.md` and the per-concept files remain the operator's record and the grounding audit trail; `review.html` is the approval surface built on top.
+
+## Common mistakes
+
+- **Too many concepts** — 2–4 tabs is a decision; 10 is a menu nobody finishes. Curate before you present.
+- **Unlabeled or content-labeled frames** — label by narrative job (`The proof`), not by what's pictured (`Table screenshot`).
+- **Missing or dishonest grounding** — every concept discloses what's real; illustrative proof is labeled illustrative.
+- **Editing the render code** — everything is data-driven; if something won't show, it's a `DATA` field, not the JS.
+- **Absolute image paths** — keep image paths relative so the output folder can be zipped, moved, or hosted intact.

package/org-skills/ad-creative/references/creative-roadmap.md

@@ -0,0 +1,118 @@
+# The Creative Strategy Loop
+
+Generation (Modes 1–3) answers "make me ads." This reference answers the question that comes first: **which ads are worth making, in what order, at what production cost** — and the retro that turns each month's results into next month's plan. It's the standing operating loop of a creative strategist, run by an agent with a human deciding.
+
+```
+Signals → Concepts (evidence-ranked) → Roadmap (tiered, capacity-checked) → Briefs → [Modes 1–3 produce] → Monthly retro → back into the icebox
+```
+
+---
+
+## Step 1: Read the Three Signals
+
+Creative direction comes from synthesis across three independent signal sources. One source alone misleads: the account tells you what worked *among things you've tried*, customers tell you why they buy *in their words*, and organic content tells you what the audience *chooses to watch when nobody's paying*.
+
+| Signal | What to pull | How |
+|---|---|---|
+| **Account performance** | Winners/losers by angle, hook, format; funnel metrics per concept (see [hook-system.md](hook-system.md) diagnostic funnel); fatigue state | `google-ads` / `meta-ads` / `linkedin-ads` / `tiktok-ads` CLIs (see Tool Integrations in SKILL.md) |
+| **Customer/brand** | Verbatim pain/desire/objection language; unexpected use cases; who's *actually* buying vs. who's targeted | The Grounded Inputs corpus (`inputs/reviews/`, `inputs/comments/`), sales-call notes, support themes — per **customer-research** |
+| **External organic** | What the niche watches unpaid: top organic content, its hooks, formats, vocabulary; competitor ads running long enough to be presumed working | **scraping**, the social listening tooling in **social**, ad libraries, **competitor-profiling** |
+
+**Cadence:** a monthly deep dive (60–90 min, all three sources, feeds the monthly roadmap) plus a weekly ~20-minute refresh (what changed: new winners/losers, new review themes, anything spiking organically). Research beyond what the next decision needs is busywork — every synthesis session should end in concepts, not notes.
+
+**Trust rule:** every insight the agent surfaces must carry its receipt — which review, which ad's metrics, which organic post. An insight without a source doesn't enter the icebox. (Same grounding rules as everything else in this skill.)
+
+---
+
+## Step 2: Turn Signals into Evidence-Ranked Concepts
+
+A **concept** is one testable creative hypothesis: *segment × motivation × angle × format*, with its evidence attached. "UGC for moms" is not a concept; "new-parent insomniacs (per 40+ reviews mentioning 3am feeds) × 'quiet enough to not wake the baby' × before/after demo × POV night-shot video" is.
+
+Rank every concept by the strongest evidence supporting it:
+
+| Tier | Evidence | Weight |
+|---|---|---|
+| 1 | Your own account: a converting ad with the same angle/segment | Strongest — iterate and extend |
+| 2 | Your customers verbatim: recurring review/call language | Strong — build new creative on it |
+| 3 | Competitor creative running 60+ days (presumed working) | Good — adapt the angle, never the ad |
+| 4 | Organic engagement in the niche (unpaid views/saves on the theme) | Moderate — validate cheaply first |
+| 5 | Cross-niche pattern (worked in an adjacent category) | Weak — icebox until corroborated |
+| 6 | Team hunch, no external signal | Weakest — low-fi test or drop |
+
+Higher evidence earns roadmap *priority* — an earlier slot in the slate. Production tier is a separate call, set by validation strength, existing assets, capacity, and risk: even a tier-2 customer-language concept starts low-fidelity until it shows a funnel signal. Hunches aren't banned — they're just cheap and last.
+
+---
+
+## Step 3: Branch on Account State
+
+The right creative mix depends on which of two states the account is in. Diagnose before roadmapping — a plan built for the wrong state wastes the month.
+
+**Exploration state** — nothing (or nothing new) is working:
+- Go **wide, not deep**: mostly net-new concepts across different segments and angles; keep iterations to a small minority — iterating on losers multiplies losers
+- **Redefine "win" per-metric**: with no full-funnel winners, a single-metric improvement (a hold-rate lift, a CPC drop, a CVR bump) on any test is a hit worth pulling on — see the diagnostic funnel
+- Iterate **only on hits**; everything else stays exploratory
+- Common root causes to check while testing: the creative is boring (safe, seen-before), the message is overcomplicated, the offer/UVP is unclear, or CPMs are punishing a too-narrow audience
+
+**Scaling state** — one or more concepts are converting profitably:
+- Go **deep on the winner** while it's open: a winner-led slate of visually-distinct variations of the winning concept (same message, new execution — near-duplicates mostly cannibalize the original's reach and teach you nothing new, so variations must look meaningfully different), plus a remix lane (tonal/emotional re-executions of it) and sub-angle probes drilling *into* the winning segment; tune the split to budget, fatigue speed, and production velocity
+- Keep a small exploration allocation alive even mid-scale — winners fatigue, and the next winner is rarely an iteration of the current one
+- Speed matters more in this state: a scaling window is finite
+
+---
+
+## Step 4: The Roadmap Artifact
+
+Maintain one living document (suggested: `roadmap.md` beside the Grounded Inputs corpus) with three horizons:
+
+```
+## Icebox        — every concept, evidence tier + source attached, nothing scheduled
+## This quarter  — 2-4 themes chosen from the icebox (the bets), with why-now
+## This month    — the slate: concept | evidence tier | production tier | owner | status
+```
+
+Each monthly-slate concept gets a **production tier**:
+
+| Tier | Cost | What it is | Use for |
+|---|---|---|---|
+| **T1 — Iteration** | Hours | New hook/caption/crop on an existing asset | Extending proven winners |
+| **T2 — Remix** | Days | New creative from existing footage/assets/AI generation | Concepts with decent evidence or a first low-fi signal |
+| **T3 — Production** | Weeks | Net-new shoot, creators, full build | Only angles with own-account proof or a prior low-fi funnel signal (fidelity ladder in [hook-system.md](hook-system.md)) |
+
+**Capacity check — the rule that keeps roadmaps honest:** count what the team (or the AI pipeline) can produce *at quality* this month, and roadmap to that number. A 20-concept slate against 8 concepts of real capacity doesn't produce 20 ads; it produces 20 compromised ones and a burned-out team. Cut by evidence rank until the slate fits.
+
+From the slate, generate **one brief per concept** (segment, motivation + verbatim source, angle, format, hook matrix rows, production tier, success metric) and hand each to Modes 1–3 for production.
+
+---
+
+## Step 5: The Monthly Creative Retro
+
+Last step of the loop, first input of the next one. One artifact per month (suggested: `retros/YYYY-MM.md`):
+
+```
+## Winners     — concept, the funnel numbers, and the WHY (which element earned it)
+## Losers      — concept, where in the funnel it died, hypothesis for why
+## Metric wins — full-funnel losers with one strong metric (these are leads, not losses)
+## Learnings   — pattern-level notes → written back into the icebox as new/revised concepts
+## Kills       — concepts retired from the icebox, with reason
+## Next slate  — first draft of next month, updated evidence ranks
+```
+
+Retro rules:
+
+- **Judge concepts, not ads.** Three executions of one concept failing says the concept is wrong; one failing says the execution was.
+- **Read the funnel, not the ROAS column.** The diagnostic funnel says *what* to fix; ROAS alone says only *that* something is broken.
+- **Enough data before verdicts** — respect the impression/spend thresholds in Common Mistakes and the **ads** skill's decision systems; a two-day read is a coin flip.
+- **Every learning lands somewhere**: icebox update, evidence re-rank, or kill. A retro that changes nothing in the roadmap was a meeting, not a retro.
+
+To run this loop on a schedule (retro on the 1st, weekly refresh Mondays, daily batches via Mode 3), see the creative loops in **marketing-loops**.
+
+---
+
+## Failure Modes
+
+- **Roadmapping without a diagnosis** — a slate built before reading the three signals is a wish list; testing without a diagnosis isn't strategy
+- **Iteration-heavy slates in exploration state** — polishing losers while the real problem (angle, offer, audience) goes untested
+- **Ignoring capacity** — the plan the team can't produce at quality is a plan to produce slop
+- **Evidence-free concepts jumping the queue** — the loudest stakeholder's hunch ships as a T3 shoot while tier-2 customer language sits in the icebox
+- **Retro as theater** — winners celebrated, nothing re-ranked, icebox untouched
+- **Scaling-state complacency** — 100% of the slate on winner variations; when the winner fatigues, the pipeline is empty