novahiz 0.1.0

package/bundled-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/bundled-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