@monoes/monomindcli 2.15.3 → 2.15.4

package/org-skills/ad-creative/references/platform-specs.md

@@ -0,0 +1,213 @@
+# Platform Specs Reference
+
+Complete character limits, format requirements, and best practices for each ad platform.
+
+---
+
+## Google Ads
+
+### Responsive Search Ads (RSAs)
+
+| Element | Character Limit | Required | Notes |
+|---------|----------------|----------|-------|
+| Headline | 30 chars | 3 minimum, 15 max | Any 3 may be shown together |
+| Description | 90 chars | 2 minimum, 4 max | Any 2 may be shown together |
+| Display path 1 | 15 chars | Optional | Appears after domain in URL |
+| Display path 2 | 15 chars | Optional | Appears after path 1 |
+| Final URL | No limit | Required | Landing page URL |
+
+**Combination rules:**
+- Google selects up to 3 headlines and 2 descriptions to show
+- Headlines appear separated by " | " or stacked
+- Any headline can appear in any position unless pinned
+- Pinning reduces Google's ability to optimize — use sparingly
+
+**Pinning strategy:**
+- Pin your brand name to position 1 if brand guidelines require it
+- Pin your strongest CTA to position 2 or 3
+- Leave most headlines unpinned for machine learning
+
+**Headline mix recommendation (15 headlines):**
+- 3-4 keyword-focused (match search intent)
+- 3-4 benefit-focused (what they get)
+- 2-3 social proof (numbers, awards, customers)
+- 2-3 CTA-focused (action to take)
+- 1-2 differentiators (why you over competitors)
+- 1 brand name headline
+
+**Description mix recommendation (4 descriptions):**
+- 1 benefit + proof point
+- 1 feature + outcome
+- 1 social proof + CTA
+- 1 urgency/offer + CTA (if applicable)
+
+### Performance Max
+
+| Element | Character Limit | Notes |
+|---------|----------------|-------|
+| Headline | 30 chars (5 required) | Short headlines for various placements |
+| Long headline | 90 chars (5 required) | Used in display, video, discover |
+| Description | 90 chars (1 required, 5 max) | Accompany various ad formats |
+| Business name | 25 chars | Required |
+
+### Display Ads
+
+| Element | Character Limit |
+|---------|----------------|
+| Headline | 30 chars |
+| Long headline | 90 chars |
+| Description | 90 chars |
+| Business name | 25 chars |
+
+---
+
+## Meta Ads (Facebook & Instagram)
+
+### Single Image / Video / Carousel
+
+| Element | Recommended | Maximum | Notes |
+|---------|-------------|---------|-------|
+| Primary text | 125 chars | 2,200 chars | Text above image; truncated after ~125 |
+| Headline | 40 chars | 255 chars | Below image; truncated after ~40 |
+| Description | 30 chars | 255 chars | Below headline; may not show |
+| URL display link | 40 chars | N/A | Optional custom display URL |
+
+**Placement-specific notes:**
+- **Feed**: All elements show; primary text most visible
+- **Stories/Reels**: Primary text overlaid; keep under 72 chars
+- **Right column**: Only headline visible; skip description
+- **Audience Network**: Varies by publisher
+
+**Best practices:**
+- Front-load the hook in primary text (first 125 chars)
+- Use line breaks for readability in longer primary text
+- Emojis: test, but don't overuse — 1-2 per ad max
+- Questions in primary text increase engagement
+- Headline should be a clear CTA or value statement
+
+### Lead Ads (Instant Form)
+
+| Element | Limit |
+|---------|-------|
+| Greeting headline | 60 chars |
+| Greeting description | 360 chars |
+| Privacy policy text | 200 chars |
+
+---
+
+## LinkedIn Ads
+
+### Single Image Ad
+
+| Element | Recommended | Maximum | Notes |
+|---------|-------------|---------|-------|
+| Intro text | 150 chars | 600 chars | Above the image; truncated after ~150 |
+| Headline | 70 chars | 200 chars | Below the image |
+| Description | 100 chars | 300 chars | Only shows on Audience Network |
+
+### Carousel Ad
+
+| Element | Limit |
+|---------|-------|
+| Intro text | 255 chars |
+| Card headline | 45 chars |
+| Card count | 2-10 cards |
+
+### Message Ad (InMail)
+
+| Element | Limit |
+|---------|-------|
+| Subject line | 60 chars |
+| Message body | 1,500 chars |
+| CTA button | 20 chars |
+
+### Text Ad
+
+| Element | Limit |
+|---------|-------|
+| Headline | 25 chars |
+| Description | 75 chars |
+
+**LinkedIn-specific guidelines:**
+- Professional tone, but not boring
+- Use job-specific language the audience recognizes
+- Statistics and data points perform well
+- Avoid consumer-style hype ("Amazing!" "Incredible!")
+- First-person testimonials from peers resonate
+
+---
+
+## TikTok Ads
+
+### In-Feed Ads
+
+| Element | Recommended | Maximum | Notes |
+|---------|-------------|---------|-------|
+| Ad text | 80 chars | 100 chars | Above the video |
+| Display name | N/A | 40 chars | Brand name |
+| CTA button | Platform options | Predefined | Select from TikTok's options |
+
+### Spark Ads (Boosted Organic)
+
+| Element | Notes |
+|---------|-------|
+| Caption | Uses original post caption |
+| CTA button | Added by advertiser |
+| Display name | Original creator's handle |
+
+**TikTok-specific guidelines:**
+- Native content outperforms polished ads
+- First 2 seconds determine if they watch
+- Use trending sounds and formats
+- Text overlay is essential (most watch with sound off)
+- Vertical video only (9:16)
+
+---
+
+## Twitter/X Ads
+
+### Promoted Tweets
+
+| Element | Limit | Notes |
+|---------|-------|-------|
+| Tweet text | 280 chars | Full tweet with image/video |
+| Card headline | 70 chars | Website card |
+| Card description | 200 chars | Website card |
+
+### Website Cards
+
+| Element | Limit |
+|---------|-------|
+| Headline | 70 chars |
+| Description | 200 chars |
+
+**Twitter/X-specific guidelines:**
+- Conversational, casual tone
+- Short sentences work best
+- One clear message per tweet
+- Hashtags: 1-2 max (0 is often better for ads)
+- Threads can work for consideration-stage content
+
+---
+
+## Character Counting Tips
+
+- **Spaces count** as characters on all platforms
+- **Emojis** count as 1-2 characters depending on platform
+- **Special characters** (|, &, etc.) count as 1 character
+- **URLs** in body text count against limits
+- **Dynamic keyword insertion** (`{KeyWord:default}`) can exceed limits — set safe defaults
+- Always verify in the platform's ad preview before launching
+
+---
+
+## Multi-Platform Creative Adaptation
+
+When creating for multiple platforms simultaneously, start with the most restrictive format:
+
+1. **Google Search headlines** (30 chars) — forces the tightest messaging
+2. **Expand to Meta headlines** (40 chars) — add a word or two
+3. **Expand to LinkedIn intro text** (150 chars) — add context and proof
+4. **Expand to Meta primary text** (125+ chars) — full hook and value prop
+
+This cascading approach ensures your core message works everywhere, then gets enriched for platforms that allow more space.

package/org-skills/ad-creative/references/short-form-video-specs.md

@@ -0,0 +1,213 @@
+# Short-Form Vertical Video — Production Spec & Creator Formats
+
+The platform-craft layer beneath any 9:16 video for TikTok, Reels, or Shorts — the constraints that decide whether a good idea survives contact with the feed — plus a tiered library of creator/UGC and founder formats that consistently perform for growth and paid.
+
+Part 1 (the spec) applies to **every** vertical video this skill produces — the iMessage reveals in [imessage-video-ads.md](imessage-video-ads.md), the motion ads in [motion-video-ads.md](motion-video-ads.md), and the creator formats below. Part 2 is the format library.
+
+---
+
+## Part 1 — The Vertical Video Spec
+
+### Canvas
+- **1080×1920 (9:16), 30fps, MP4.** Footage of any resolution/orientation is center-cropped to fill (`object-fit: cover`) — mixed source resolutions are fine.
+
+### Safe zones (the single most-missed constraint)
+Platform UI covers the frame edges — the action rail, caption stack, music button, and account row all sit *on top of* your video. Text or key visuals in those bands get covered. Keep everything inside the **cross-platform safe band** — the worst case of TikTok and IG Reels margins on a 1080×1920 canvas:
+
+| Edge | Keep clear | Why |
+|---|---|---|
+| **Top** | 220px | TikTok tabs + IG account row |
+| **Bottom** | 500px | Caption / music / CTA stack (both platforms) |
+| **Left** | 180px | Symmetry with right |
+| **Right** | 180px | Action rail (like/comment/share/music) |
+
+**Result: a 720×1200 centered text band, from y=220 to y=1420.** Compose all captions and load-bearing visuals inside it. Preview against a safe-zone overlay before a big push. (These numbers drift with app updates — re-verify occasionally; they're a well-sourced worst-case, not a permanent law.)
+
+### Caption style (classic TikTok)
+White fill, black outline, **no background pill** — the native look that reads as organic, not as an ad:
+
+```css
+color: #fff;
+font-family: "TikTok Sans", sans-serif;  /* or a close variable sans; embed it, don't assume it's installed */
+font-weight: 700;
+paint-order: stroke fill;                  /* stroke behind fill — keeps glyphs crisp */
+-webkit-text-stroke: 8px #000;
+text-shadow: 0 2px 10px rgba(0, 0, 0, 0.35);
+```
+
+- **Captions are static** — no entrance/exit transitions. A caption is at full visibility on the first frame of its window, and its window matches its video segment exactly (same start, same end). Animated captions read as "made by a brand."
+- **Auto-size to fit the band.** Start at ~58px and shrink in ~2px steps until the text fits the safe band (fit box ~1150px tall), floor ~26px. Never overflow the band, never clip mid-glyph. Long wall-of-text hooks are a *supported* input, not a failure case — they just shrink. Re-measure after the font actually loads (`document.fonts.ready`) so sizing uses the real face, not a fallback.
+
+### Audio defaults (and the organic-vs-baked decision)
+- **Mute clip audio by default; let one music track carry the sound.** Per-clip audio is opt-in (e.g., keep a creator's voice at full, mute B-roll).
+- **Fade music out over the final ~0.8s** — a hard cut to silence reads as broken.
+- **The organic call:** for organic TikTok/Reels, often post **without baked-in music** and attach the trending sound *in-app* — the platform's algorithm rewards native/trending audio, and an in-app sound is discoverable/attachable by others. **Bake the music in** for paid ads and anywhere you can't attach a native sound (some cross-posting, some platforms). This one decision meaningfully affects organic reach.
+
+### Determinism (if you generate programmatically)
+Renders must be reproducible: no clocks (`Date.now()`), no `Math.random()`, no network fetches at render time. Same inputs → same MP4, every time. (Applies whether you're on Remotion, HyperFrames, or an ffmpeg pipeline — see the `video` skill for framework choice.)
+
+---
+
+## Part 2 — Creator Format Library
+
+UGC- and creator-driven short-form formats that reliably perform for growth and paid. Each is a *structure*, not a script — feed it your own footage and hook. All obey Part 1.
+
+**Tiers** rank a format on one axis: does it *scale a cold ad into net-new audiences* (a "unicorn scaling" format), or does it just *convert people already in mid/low funnel* (a "supporting cast" format)? **S** = the rare formats that both scale cold and carry heavy education. **A** = scales up well. **B** = solid supporting cast under the right conditions. **C** = situational or operationally complex (rights, specific talent, or better faked than captured). Build a *portfolio* across tiers — don't expect every format to scale. Meta's persona-based delivery is why creator-fronted formats (Yapper, Investigation, Authority, VSL) rank so high: they reach personas natively through the creators those personas already follow. For the full 51-format taxonomy and where each sits, see [meta-creative-formats.md](meta-creative-formats.md) (companion reference) and the tier/portfolio logic in [ads/references/meta-decision-system.md](../../ads/references/meta-decision-system.md).
+
+### Format 1 — Reaction + Demo (hard cut) · A
+**Shape:** creator reaction clip with a hook caption → **hard cut** to an app/product demo screen recording. ~9–12s total.
+
+```
+[ reaction · ~3s · hook caption ] → [ demo · full length · optional payoff caption ]
+```
+
+- **When:** you have (or can get) a genuine-feeling creator reaction and a crisp demo. The workhorse UGC format for apps/tools.
+- **The hook caption** rides the reaction segment and does all the selling — it's the ad. Write it as the reaction's inner monologue ("i was about to hit it and this app talked me out of it"), not a product claim.
+- **The hard cut is the mechanic** — no transition. Reaction earns attention, cut delivers the payoff. Optional second caption on the demo lands the result ("12/12 cravings resisted").
+- Sourcing: real UGC reactions are the input bottleneck; the format is only as good as the reaction's authenticity.
+
+### Format 2 — "No Yapping" Split-Screen Tutorial · B
+**Shape:** silent, fast tutorial. Fullscreen intro → **50/50 split** (typing/action on one half, live result on the other), step captions at the seam. The "…but no yapping" promise = pure value, no talking.
+
+```
+[ intro · fullscreen · hook ] → [ split: input | output · ordered step captions at the seam ]
+```
+
+- **When:** a how-to where *showing* beats *narrating* — setup flows, prompt walkthroughs, tool tutorials. The silence is the selling point (people watch muted; "no yapping" filters for high-intent).
+- **Captions carry the steps** — ordered, static, one per beat, placed at the split seam so both halves stay visible. Auto-size per Part 1.
+- No voiceover; music-only (see the organic-sound note). Pace tight — dead air kills retention.
+
+### Format 3 — Greenscreen Reaction · A
+**Shape:** one video plays fullscreen; the creator is **cut out of their background** (greenscreen/segmentation) and composited on top — reacting to or narrating over the underlying content. Optionally start centered, then shrink/drag into a corner so the underlying video takes over.
+
+```
+[ fullscreen video (e.g. a screen recording / another post) + creator cutout overlay · optional hook text ]
+```
+
+- **When:** reacting to a competitor's post, a trend, a screen recording, or your own product — the TikTok-native "let me react to this" format. Reads as commentary, which the algorithm and audience treat as organic.
+- **Both soundtracks can coexist** (underlying video + creator), unlike the mute-by-default rule — the reaction voice is the point here.
+- The corner-drag move (creator starts big to establish presence, then shrinks to let the content breathe) is the signature beat.
+
+### Format 4 — Yapper · A
+**Shape:** one creator talks straight to camera, telling a personal story that lands on your product. No cuts required — the story *is* the ad. ~20–60s.
+
+```
+[ creator talking to camera · hook line first · personal story → product as the resolution ]
+```
+
+- **When:** you have the *right* creator (a person who reads as one level above the viewer, excited and specific) and a *scripted* story with a real narrative arc. Hard to nail — needs creator + script + setting all working — but scales into cold audiences when it lands.
+- **Mechanics:** open on a strong take or a story hook ("I almost cancelled this app three times"), not a product claim. Structure as hook → story → the product entering as the turn, never as a feature list. Captions on (Part 1 style); low-fi setting (car, walk, one spot) reads native. Flat energy kills it — the delivery carries the format.
+- Casting is the bottleneck: the format fails on the wrong creator far more than on the wrong script.
+
+### Format 5 — Amateur Investigation · A
+**Shape:** a creator "investigates" your product, niche, or a question on the viewer's behalf — visiting places, comparing options, testing claims. The discovery arc is the retention engine.
+
+```
+[ creator sets up the question · goes and investigates (real footage) · lands on your product as the finding ]
+```
+
+- **When:** your product wins on comparison or holds up to scrutiny — the investigation earns the recommendation instead of asserting it. Scales cold because it plays as content, not an ad.
+- **Mechanics:** frame a genuine question ("are dealership warranties actually worth it?"), let the creator do legwork on camera, and let your product surface as the *conclusion the investigation reached* — not a sponsor slot. Real-world capture (locations, comparisons) is the credibility.
+
+### Format 6 — David & Goliath · A
+**Shape:** position the brand as the underdog (David) against a big industry, incumbent, or broken status quo (Goliath). Root-for-you storytelling.
+
+```
+[ name the Goliath (the villain / broken norm) · the brand's fight against it · why you win / how you're different ]
+```
+
+- **When:** you have a real antagonist — a bloated incumbent, an industry practice that rips people off, a category default that's worse than yours. The story makes the viewer *want* you to win.
+- **Mechanics:** make the Goliath concrete and the stakes emotional; the brand's origin ("we built this because X was broken") powers it. Pairs naturally with founder delivery. Don't manufacture a villain that isn't real — the format lives or dies on a genuine antagonist.
+
+### Format 7 — Authority · A
+**Shape:** a credentialed expert — doctor, dermatologist, engineer, practitioner — presents or endorses the product on the strength of their expertise.
+
+```
+[ expert on camera (credentials clear) · the problem in their domain · why this product is the right answer ]
+```
+
+- **When:** hyper-competitive, trust-gated niches (supplements, skincare, health, anything regulated) where a credential does the persuading UGC can't. Adds validation and creative diversity beyond creator UGC.
+- **Mechanics:** the expert must be real and the claims must be true and substantiated — this format sits closest to regulatory risk. Route health/medical/financial claims through legal review; never fabricate credentials or put words in an expert's mouth. Follows the skill's Grounded Inputs rules strictly.
+
+### Format 8 — VSL (Video Sales Letter) · S
+**Shape:** long-form (60s to several minutes) direct-response video that educates before it sells — problem → mechanism → proof → offer.
+
+```
+[ hook + problem · why it happens (the mechanism) · the solution + proof · the offer + CTA ]
+```
+
+- **When:** the sale needs *upfront education* — health, wellness, fitness, finance, anything where the buyer must understand the mechanism before they'll convert. One of the few formats that both scales cold and carries heavy teaching, hence S-tier.
+- **Mechanics:** the craft is in the script — a tight problem hook, a believable mechanism, stacked proof, and a clear offer. Retention is engineered beat by beat (open loops, "but here's the thing" turns). Captions throughout; a real person or voiceover-over-broll both work. This is a writing discipline first — invest in the script.
+
+### Format 9 — Green-Screen Commentary · A
+**Shape:** the creator talks *over* full-frame imagery — screenshots, product shots, charts, a competitor's page — pairing an educational take with the visual it references. (Distinct from Format 3's reaction: this is a *teaching* overlay, not a reaction to a post.)
+
+```
+[ creator cutout + full-frame reference imagery behind them · educational narration keyed to what's on screen ]
+```
+
+- **When:** apparel, and anything with an educational angle where *showing the thing while explaining it* beats talking alone. Reads as commentary/teaching, which delivery treats as organic.
+- **Mechanics:** swap the background imagery to match each beat of the narration (the visual should always illustrate the current point). Creator voice carries; keep the take genuinely useful, not a disguised pitch.
+
+### Format 10 — Conversation · B
+**Shape:** two people in a real exchange — interview, dialogue, back-and-forth — where the product surfaces naturally in the conversation.
+
+```
+[ two people talking · a real question/answer exchange · product enters as part of the dialogue ]
+```
+
+- **When:** you can stage a genuine-feeling two-person dynamic and the product fits a natural conversational moment. Solid supporting cast; converts more than it scales cold.
+- **Mechanics:** hard to execute — the chemistry and the naturalness are the whole thing; scripted-sounding dialogue kills it. Best when the exchange surfaces a real objection and answers it in-flow.
+
+### Format 11 — Duet / Reaction · C (rights needed)
+**Shape:** react to, duet, or stitch another creator's video — your commentary alongside or after their clip.
+
+```
+[ original creator's clip · your reaction / duet / stitch responding to it ]
+```
+
+- **When:** there's a specific post worth responding to and it earns net-new pockets of audience. Situational.
+- **Mechanics:** **you need rights** from the original creator to use their footage in a paid ad — this is the operational gate, not the creative. Without cleared rights, don't run it as an ad.
+
+### Format 12 — ASMR · C
+**Shape:** sensory-forward, sound-led video — tapping, unboxing, application, texture — with the product as the sensory object.
+
+```
+[ close-up sensory action · product-forward · ASMR audio carries (no VO) ]
+```
+
+- **When:** pet, beauty, food, or tactile products where the sensory experience *is* the appeal. Situational and needs the right ASMR-native creator.
+- **Mechanics:** breaks the mute-by-default rule — the audio is the point; capture it clean. Requires talent who actually shoots ASMR; a generalist creator can't fake the sensory craft.
+
+### Format 13 — Street Interview · C ("often better to fake")
+**Shape:** person-on-the-street questions — real or recreated — capturing candid reactions to your product or category question.
+
+```
+[ on-the-street setup · question to passersby · candid answers → your angle ]
+```
+
+- **When:** you want the credibility of unscripted public reaction. Situational and operationally heavy to capture honestly.
+- **Mechanics:** honest capture is painful (releases, dead takes, weather, luck), so this format is **often better staged/recreated** with the same visual language — the recreated version is faster, controllable, and reads the same. If you do stage it, keep the claims real (Grounded Inputs still apply).
+
+### Founder / Organic Vlog Structures
+
+For **founder-led video ads** and organic-native brand content, four narrative structures (Oren John) give a founder something to *say*, and a shooting + edit system makes it fast to produce. These aren't a separate tier — they're the story arc *inside* a Yapper, Investigation, or vlog. Founder's content is typically a brand's *first* top performer: telling the story of *why* you built the brand auto-connects with same-problem buyers.
+
+**The four structures (pick the arc, then shoot to it):**
+- **Hero's journey** — run whatever's happening in the business through: problem → backstory → attempt → failure → epiphany → breakthrough → cliffhanger. The reframe matters more than the events. Lets you post *less* — one great story-vlog a week can beat daily content because people follow the journey. (For this arc specifically, it's fine to run the raw situation through an LLM *for the outline only* — feed brand/persona context, ask for a 60–90s hero's-journey outline — then write the words yourself.)
+- **Math** — money as the lever: a cost breakdown or a fixed-budget challenge ("$200 on Meta ads — here's what happened"). *Unexpectedly cheap* outperforms expensive; the affordability question creates intrinsic curiosity. Don't use luxury as the hook — it doesn't scale and reads as a flex.
+- **Shiny object** — anchor on something visually novel the viewer hasn't seen and that you have *access* to (your factory, a machine, a craft process, a trade show). Never money/luxury as the shiny object.
+- **Niche guide with expertise** — narrate the real world through your professional lens ("what I'd avoid as an interior designer," filmed in the store). A *learner* POV works too — just be honest which you are. Getting out into the world is the cheat code while everyone else yaps in their car.
+
+**The three-capture shooting system** (makes any of the above fast):
+- Film every moment **three ways — close / medium / wide (0.5x)** — to maximize usable footage from any moment.
+- **2–3 second clips only** — many small clips, never long roaming takes (easy timeline assembly).
+- **Motion rule:** if the subject is moving, hold the phone static; if nothing's moving, add a slow push-in or side-slide.
+- Do the activity first, then run back through at the end (~5 min) grabbing three angles of 10–12 things — less interrupting.
+- One phone folder per trip; **favorite your single best "hook shot"** so the opener is pre-chosen. Get **≥5 shots of yourself** — you're the through-line.
+
+**The 0.5–1s cut formula** (the edit): every shot is **0.5–1 second** — a 45-second voiceover becomes ~45 one-second shots. Record the voiceover/talk track first, lay clips under it, reorder, trim. Cut in CapCut or Instagram's Edits app — don't reach for Premiere/DaVinci. This cut cadence is the vlog-speed cousin of Format 1's hard cut, and it's what makes the footage read as energetic rather than slow.
+
+---
+
+*Vertical-video spec (safe-zone band, caption recipe, auto-sizing, organic-vs-baked audio) and the first three creator formats are distilled from Daniel Hangan's `reelclaw-templates` (built on HeyGen's HyperFrames; TikTok Sans redistributed under SIL OFL 1.1) — patterns credited, no code vendored. The tiered format library (Yapper, Investigation, David & Goliath, Authority, VSL, and the tier logic) is adapted from Dara Denney's Meta creative-type tier list; the founder / organic-vlog structures, three-capture shooting system, and 0.5–1s cut formula are adapted from Oren John's vlog + yapping playbooks — sources credited, expressed originally. Safe-zone numbers are a cross-platform worst case; re-verify against current app UI. For framework/tooling choices to actually render these, see the `video` skill.*