start-vibing-stacks 2.28.0 → 2.30.0

package/stacks/_shared/ads-agents/references/scoring-system.md

@@ -0,0 +1,169 @@
+# Ad Account Audit Scoring System
+
+<!-- Updated: 2026-05-14 | v1.6: refreshed counts, cross-platform checks, ID convention -->
+<!-- Sources: Google Research PDF 1, Claude Research, Gemini Research, 2026 Platform Research, 2026 Verification Pass -->
+
+## Check ID Convention
+
+- **Sequential IDs** (G01, M01, L01, T01, MS01): Original v1.0 checks
+- **Hyphenated IDs** (G-AI1, M-AN1, L-CRM1, T-SR1, MS-SI1, X-PI1): v1.5+ additions
+- **Platform prefixes**: G = Google, M = Meta, L = LinkedIn, T = TikTok, MS = Microsoft, ASA = Apple, X = Cross-platform
+
+## Weighted Scoring Algorithm
+
+```
+S_total = Σ(C_pass × W_sev × W_cat) / Σ(C_total × W_sev × W_cat) × 100
+```
+
+- `C_pass` = check passed (1) or failed (0); WARNING = 0.5
+- `W_sev` = severity multiplier of the individual check
+- `W_cat` = category weight for that platform
+- Result: 0-100 Health Score
+
+## Severity Multipliers
+
+| Severity | Multiplier | Criteria |
+|----------|-----------|----------|
+| Critical | 5.0 | Immediate revenue/data loss risk. Remediation urgent. |
+| High | 3.0 | Significant performance drag. Fix within 7 days. |
+| Medium | 1.5 | Optimization opportunity. Fix within 30 days. |
+| Low | 0.5 | Best practice, minor impact. Nice to have. |
+
+## Scoring Per Check Item
+
+| Result | Points Earned |
+|--------|--------------|
+| PASS | Full severity × category weight |
+| WARNING | 50% of full points |
+| FAIL | 0 points |
+| N/A | Excluded from total possible |
+
+## Category Weights by Platform
+
+### Google Ads
+| Category | Weight | Rationale |
+|----------|--------|-----------|
+| Conversion Tracking | 25% | Foundation for all optimization; Enhanced Conv + Consent Mode V2 + CTV tracking (12 checks) |
+| Wasted Spend / Negatives | 20% | Direct money leak; search terms, negative lists (8 checks) |
+| Account Structure | 15% | Campaign organization, brand/non-brand separation (12 checks) |
+| Keywords & Quality Score | 15% | QS as diagnostic, not KPI; keyword-ad alignment (8 checks) |
+| Ads & Assets | 15% | RSA strength, PMax assets, AI Max, Demand Gen (12 checks + PMax 6 + AI/DG 4) |
+| Settings & Targeting | 10% | Location, network, audiences, landing pages (12 checks) |
+
+### Meta Ads
+| Category | Weight | Rationale |
+|----------|--------|-----------|
+| Pixel / CAPI Health | 30% | 87% of advertisers have poor EMQ; foundational signal (10 checks) |
+| Creative (Diversity & Fatigue) | 30% | Andromeda makes creative the #1 targeting lever (12 checks) |
+| Account Structure | 20% | Learning phase, Advantage+ Sales, consolidation (18 checks) |
+| Audience & Targeting | 20% | Overlap, exclusions, Advantage+ Audience (6 checks) |
+| Andromeda & Platform Changes | N/A | v1.5 checks scored within above categories (4 checks) |
+
+### LinkedIn Ads
+| Category | Weight | Rationale |
+|----------|--------|-----------|
+| Technical Setup | 25% | Insight Tag + CAPI essential for B2B attribution (2 checks) |
+| Audience Quality | 25% | LinkedIn's targeting precision is its differentiator (7 checks) |
+| Creative & Formats | 20% | TLA + format diversity; video efficiency varies (4 checks) |
+| Lead Gen Forms | 15% | 13% CVR (3.25x landing pages); CRM integration (2 checks) |
+| Bidding & Budget | 15% | Manual CPC first for cost control (2 checks) |
+| CRM & Compliance | 10% | v1.5: CRM revenue attribution, EU messaging compliance (2 checks) |
+
+### TikTok Ads
+| Category | Weight | Rationale |
+|----------|--------|-----------|
+| Creative Quality | 30% | Native-feel content is #1 success factor (10 checks) |
+| Technical Setup | 25% | Pixel + Events API Gateway + ttclid passback (2 checks) |
+| Bidding & Learning | 20% | 50 conv/week to exit learning; budget sufficiency (3 checks) |
+| Structure & Settings | 15% | Smart+ modular control, Search Toggle, Shop integration (6 checks) |
+| Performance | 10% | CTR, CPA, completion rate benchmarks (3 checks) |
+| Search, Commerce & Tracking | N/A | v1.5 checks scored within above categories (3 checks) |
+
+### Microsoft Ads
+| Category | Weight | Rationale |
+|----------|--------|-----------|
+| Technical Setup | 25% | UET tag, import validation, Enhanced Conv (3 checks) |
+| Syndication & Bidding | 20% | Partner network control (High severity), Copilot placement (4 checks) |
+| Structure & Audience | 20% | LinkedIn targeting (16% CTR lift), campaign structure (3 checks) |
+| Creative & Extensions | 20% | Multimedia, Video (9:16 Apr 2025), Action/Filter Link (5 checks) |
+| Settings & Performance | 15% | CPC advantage tracking, conversion rate comparison (5 checks) |
+| Import Safety, Compliance & Video | N/A | v1.5: scheduled imports, Consent Mode, CTV, video (4 checks) |
+
+## Grading Thresholds
+
+| Grade | Score | Label | Action Required |
+|-------|-------|-------|-----------------|
+| A | 90-100 | Excellent | Minor optimizations only |
+| B | 75-89 | Good | Some improvement opportunities |
+| C | 60-74 | Needs Improvement | Notable issues need attention |
+| D | 40-59 | Poor | Significant problems present |
+| F | <40 | Critical | Urgent intervention required |
+
+## Quick Wins Logic
+
+```
+IF severity == "Critical" OR severity == "High"
+AND estimated_remediation_time < 15 minutes
+THEN flag as "Quick Win"
+PRIORITY: Quick Wins sorted by (severity × estimated_impact) DESC
+```
+
+Quick Win examples:
+- Enable Enhanced Conversions (Critical, 5 min)
+- Turn on Search Ads Toggle in TikTok (High, 2 min)
+- Add negative keyword lists (Critical, 10 min)
+- Fix location targeting method (Critical, 2 min)
+- Enable Advantage+ Placements (Medium, 2 min)
+
+## Weighting Rationale
+
+Category weights are calibrated for paid advertising accounts where conversion tracking infrastructure is the highest-impact factor (25-30% weight across platforms). This differs from generic scoring systems because:
+- Broken tracking invalidates all optimization decisions downstream
+- Creative and targeting quality follow tracking in priority
+- Settings and compliance are important but have lower direct revenue impact
+- Weights sum to 100% per platform, enabling direct cross-platform comparison
+
+The grading thresholds (A=90-100, B=75-89, C=60-74, D=40-59, F=<40) use wider bands than academic-style scoring because ad account health is typically distributed lower; a score of 75+ represents genuinely well-managed accounts.
+
+---
+
+## Cross-Platform Checks (v1.5)
+
+These checks apply across all platforms during full audits:
+
+| ID | Check | Severity | Description |
+|----|-------|----------|-------------|
+| X-PI1 | Privacy infrastructure completeness | Critical | Consent Mode V2 (Google/MS) + CAPI (Meta) + Events API (TikTok) + AdAttributionKit (Apple). Without proper signals, no optimization works |
+| X-CD1 | Creative diversity audit | High | Andromeda, Smart+, and PMax all use creative signals for targeting. Flag accounts with <5 genuinely distinct creative concepts |
+| X-RF1 | Platform-appropriate refresh cadence | High | TikTok 7-10d, Meta 14-21d, LinkedIn 4-6w, Google/MS 8-12w. Flag overdue refreshes |
+
+Cross-platform checks are scored at 100% weight in the aggregate score (not within any single platform).
+
+---
+
+## Total Check Counts (v1.5)
+
+| Platform | v1.0 | v1.5 | Change |
+|----------|------|------|--------|
+| Google | 74 | 80 | +6 (AI Max, Demand Gen, CTV, PMax negatives) |
+| Meta | 46 | 50 | +4 (Andromeda, attribution, Incremental, Threads) |
+| LinkedIn | 25 | 27 | +2 (CRM, EU compliance) |
+| TikTok | 25 | 28 | +3 (Search, GMV Max, Events API) |
+| Microsoft | 20 | 24 | +4 (imports, Consent Mode, CTV, video) |
+| Cross-platform | 0 | 3 | +3 (privacy, creative diversity, refresh cadence) |
+| **Total** | **190** | **212** | **+22 new checks** |
+
+Note: Apple and YouTube checks are scored within their respective SKILL.md files, not in the reference audit checklists.
+
+---
+
+## Cross-Platform Aggregate Score
+
+When auditing multiple platforms, calculate per-platform scores then aggregate:
+
+```
+Aggregate Score = Σ(Platform_Score × Platform_Budget_Share)
+
+Example: Google (82) × 40% + Meta (71) × 35% + LinkedIn (90) × 25%
+       = 32.8 + 24.85 + 22.5 = 80.15 → Grade B
+```

package/stacks/_shared/ads-agents/references/tiktok-audit.md

@@ -0,0 +1,165 @@
+# TikTok Ads Audit Checklist
+
+<!-- Updated: 2026-05-14 | v1.6 -->
+<!-- Sources: Google Research PDF 1 (T01-T25), Claude Research, Gemini Research, 2026 Verification Pass -->
+<!-- Total Checks: 28 | Categories: 6 | See scoring-system.md for weights and algorithm -->
+
+## Quick Reference
+
+| Category | Weight | Check Count |
+|----------|--------|-------------|
+| Creative Quality | 30% | T05-T10 + T20-T25 (12 checks) |
+| Technical Setup | 25% | T01-T02 (2 checks) |
+| Bidding & Learning | 20% | T11-T13 (3 checks) |
+| Structure & Settings | 15% | T03-T04 + T14-T16 (5 checks) |
+| Performance | 10% | T17-T19 (3 checks) |
+| Search, Commerce & Tracking | N/A | T-SR1, T-GM1, T-EA1 (3 checks, v1.5) |
+
+---
+
+## Creative Quality (30% weight)
+
+| ID | Check | Severity | Pass | Warning | Fail |
+|----|-------|----------|------|---------|------|
+| T05 | Creative volume | Critical | ≥6 creative assets per ad group | 3-5 creatives | <3 creatives per ad group |
+| T06 | Vertical video format | Critical | All video assets 9:16 (1080x1920) | Mixed ratios with some vertical | No vertical video (landscape only) |
+| T07 | Native-looking content | High | Ads look organic / creator-style (not polished corporate) | Semi-native style | Clearly corporate/polished ads |
+| T08 | Hook strategy | High | First 1-2 seconds have attention-grabbing hook | Decent hook but not optimized | No clear hook in opening |
+| T09 | Creative lifespan | High | No creative active >7 days with declining CTR (7-10 day avg lifespan). Frequency <2.5x. Campaigns with 10+ unique creatives achieve 1.3x higher ad recall, 3.0x purchase intent, 1.5x higher awareness vs <5 | 7-14 days with minor decline; frequency approaching 2.5x | >14 days with significant CTR decline. Frequency >2.5x causes 30-40% CVR drops |
+| T10 | Spark Ads utilization | High | Spark Ads tested and active (+30% completion rate, +142% engagement rate, +43% CVR, -4% CPM vs non-Spark). Profile landing page = 69% higher CVR and 37% lower CPA. Strategy: test with dark ads first, identify top performers, convert winners to Spark | Tested but paused | No Spark Ads tested (~3% CTR vs ~2% standard) |
+| T20 | TikTok Shop integration | Medium | Shop catalog connected (for e-commerce) | N/A | Eligible but not connected |
+| T21 | Video Shopping Ads (VSA) | Medium | VSA tested for product catalog accounts | N/A | Not tested despite eligible catalog |
+| T22 | Caption SEO | High | Captions include high-intent keywords for search discovery | Some keywords in captions | No keyword optimization in captions |
+| T23 | Sound/music usage | Medium | Trending or engaging audio used | Licensed audio but not trending | Silent ads (TikTok is sound-on platform) |
+| T24 | CTA button | Medium | Appropriate CTA button selected (not default) | N/A | Default CTA without customization |
+| T25 | Safe zone compliance | High | Key content within safe zone (X:40-940, Y:150-1470) | Minor elements outside safe zone | Key text/CTA in UI overlay zones |
+
+---
+
+## Technical Setup (25% weight)
+
+| ID | Check | Severity | Pass | Warning | Fail |
+|----|-------|----------|------|---------|------|
+| T01 | TikTok Pixel installed | Critical | Pixel firing on all relevant pages | Firing on most pages (>90%) | Pixel not installed or broken |
+| T02 | Events API + ttclid | High | Server-side events via Events API with ttclid passback | Events API active but no ttclid passback | No server-side tracking |
+
+### ttclid Critical Note
+The TikTok Click ID (`ttclid`) comes in landing page URL parameters and MUST be:
+1. Captured on first page load
+2. Stored in session/cookie
+3. Sent back with ALL conversion events
+
+Without ttclid, attribution breaks for many conversions. This is TikTok's key technical difference from other platforms.
+
+---
+
+## Bidding & Learning (20% weight)
+
+| ID | Check | Severity | Pass | Warning | Fail |
+|----|-------|----------|------|---------|------|
+| T11 | Bid strategy | High | Lowest Cost for volume; Cost Cap for efficiency | N/A | Bid Cap set too aggressively (severe under-delivery) |
+| T12 | Budget sufficiency | High | Daily budget ≥50x target CPA per ad group. GMV Max mandatory for all Shop Ads (July 2025). For first-time VSA campaigns, budget ≥50x target CPA. Evaluate holistically: Shop total GMV / (Ads cost + affiliate commission) | 20-49x CPA | <20x CPA per ad group |
+| T13 | Learning phase | High | Ad groups achieving ≥50 conversions/week | 25-50 conversions/week | <25 conversions/week (stuck in learning) |
+
+### Learning Phase Rules
+- Exit criteria: ~50 conversions in 7 days per ad group
+- Campaign minimum budget: $50/day
+- Ad group minimum budget: $20/day
+- Daily budget should be ≥50x target CPA for sufficient learning room
+- Avoid changes during learning (resets the phase)
+
+---
+
+## Structure & Settings (15% weight)
+
+| ID | Check | Severity | Pass | Warning | Fail |
+|----|-------|----------|------|---------|------|
+| T03 | Campaign structure | High | Separate campaigns for prospecting vs retargeting | N/A | Prospecting and retargeting mixed |
+| T04 | Smart+ utilization | Medium | Smart+ campaigns tested with modular control. Advertisers can lock specific modules (targeting, creative, budget, placement) while automating others. Supports up to 30 ad groups/campaign, 30 asset groups/ad group, 50 creatives/asset group | N/A | Not tested (42% adoption, 1.41-1.67 median ROAS; modular control since 2025) |
+| T14 | Search Ads Toggle | High | Search Ads Toggle enabled for all campaigns (20% increase in conversions when combined with In-Feed; 18% of in-feed non-converters convert via Search Ad; 2x higher purchase lift; 57% of TikTok users use search). Max 1,000 keywords per ad group | N/A | Search Ads Toggle OFF (missing significant incremental conversions) |
+| T15 | Placement selection | Medium | Appropriate placements selected (TikTok, Pangle, etc.) | Default placements without review | N/A |
+| T16 | Dayparting | Low | Ad schedule aligned with target audience activity | N/A | No schedule despite clear patterns |
+
+---
+
+## Performance (10% weight)
+
+| ID | Check | Severity | Pass | Warning | Fail |
+|----|-------|----------|------|---------|------|
+| T17 | CTR benchmark | High | CTR ≥1.0% for in-feed ads | CTR 0.5-1.0% | CTR <0.5% |
+| T18 | CPA target | High | CPA within target range | CPA 1.5-3x target | CPA >3x target (trigger 3x Kill Rule) |
+| T19 | Video completion rate | Medium | Average video watch time ≥6 seconds | 3-6 seconds | <3 seconds average watch time |
+
+---
+
+## Quick Wins (TikTok)
+
+| Check | Fix | Time |
+|-------|-----|------|
+| T14: Search Ads Toggle | Enable Search Ads Toggle in campaign settings | 2 min |
+| T06: Vertical video | Convert existing assets to 9:16 format | 10 min |
+| T24: CTA button | Select appropriate CTA (not default) | 2 min |
+| T10: Spark Ads | Whitelist top creator/organic content as Spark Ads | 10 min |
+| T22: Caption SEO | Add high-intent keywords to ad captions | 5 min |
+| T25: Safe zone | Verify key content within X:40-940, Y:150-1470 | 5 min |
+
+---
+
+## TikTok-Specific Context
+
+| Fact | Value |
+|------|-------|
+| Smart+ adoption | 42% of US TikTok performance campaigns (surged from 9% in early 2025) |
+| Smart+ capacity | 30 ad groups/campaign, 30 asset groups/ad group, 50 creatives/asset group |
+| GMV Max | Default for TikTok Shop Ads (July 2025) |
+| TikTok Shop CVR | >10% (vs 0.46-2.4% standard) |
+| CPM advantage | 40-60% cheaper than Meta |
+| Spark Ads CTR | ~3% vs ~2% standard In-Feed |
+| Spark Ads CPA | ~$60 vs ~$100 standard |
+| Engagement rate | 5-16% (far exceeds FB 0.09%, IG 1.22%) |
+| Search Ads | Launched 2025; available in ~12 markets (US, UK, Canada, Germany, France, Italy, Spain, Mexico, Brazil, Australia, Saudi Arabia, Japan). Lead Generation: US only |
+| Safe zone | X:40-940px, Y:150-1470px (900x1320px usable) |
+| Available markets | 12 countries (US, UK, key Asian/European) |
+
+---
+
+## Search, Commerce & Tracking (v1.5)
+
+| ID | Check | Severity | Pass | Warning | Fail |
+|----|-------|----------|------|---------|------|
+| T-SR1 | Search Ads alongside In-Feed | High | Search Ads enabled alongside In-Feed campaigns (20% conversion uplift when combined; 18% of non-converters from in-feed convert via Search; 2x purchase lift). Supports keyword targeting with exact/phrase/broad, negative keywords, search term reports | N/A | Search Ads not enabled despite available budget (missing 18-20% incremental conversions) |
+| T-GM1 | GMV Max for Shop campaigns | Critical | All TikTok Shop campaigns use GMV Max (mandatory since July 2025). Three ad types: Video Shopping Ads, LIVE Shopping Ads, Product Shopping Ads | Non-GMV Max Shop campaigns still transitioning | Non-GMV Max Shop campaigns active (non-compliant with July 2025 mandate) |
+| T-EA1 | Events API Gateway setup | High | Events API Gateway configured for simplified server-side tracking (recovers 13%+ of missed conversions vs pixel-only). SKAN 4 integration with coarse conversion values active for iOS | Events API planned but not deployed | No server-side tracking (pixel-only, missing 13%+ of conversions) |
+
+---
+
+## Context Notes
+
+- **Smart+ modular control (2025)**: Lock targeting/creative/budget/placement independently
+- **GMV Max (July 2025)**: Mandatory for all Shop Ads campaigns
+- **Symphony Automation**: AI-powered creative variations from product URLs, which impacts creative refresh evaluation
+- **Events API Gateway**: Simplified server-side setup for conversion recovery
+- **Search Ads maturity**: Now supports Sales, Traffic, and Lead Generation objectives in 12 markets
+- **Creative lifespan**: 7-10 days average. Refresh weekly minimum. High-spend ($1K+/day) needs variations every 3-4 days
+
+---
+
+## TikTok Safe Zone Diagram
+
+```
+┌──────────────────────────────┐
+│  0-150px: Status bar, account│  ← TOP UNSAFE
+├──────────────────────────────┤
+│                         │    │
+│    SAFE ZONE            │140 │  ← RIGHT: Like, comment,
+│    X: 40-940px          │ px │     share, profile icons
+│    Y: 150-1470px        │    │
+│    (900×1320px)         │    │
+│                         │    │
+├──────────────────────────────┤
+│  0-450px: Caption, music,    │  ← BOTTOM UNSAFE
+│  CTA, navigation bar         │
+└──────────────────────────────┘
+```
+
+All critical text, logos, and CTAs MUST be within the safe box.

package/stacks/_shared/ads-agents/references/tiktok-creative-specs.md

@@ -0,0 +1,139 @@
+# TikTok Creative Specs: Generation Guide
+
+<!-- Updated: 2026-03-12 -->
+<!-- Source: platform-specs.md + TikTok Ads Manager requirements -->
+<!-- Used by: ads-generate, visual-designer agent -->
+
+## Purpose
+
+Generation-ready specifications for TikTok ad creative. TikTok is vertical-only and
+sound-on. Horizontal or square creatives are **rejected at upload**. Safe zone
+compliance is critical; UI elements cover significant portions of the frame.
+
+---
+
+## Required Format
+
+| Ratio | Dimensions | Notes |
+|-------|-----------|-------|
+| **9:16 (ONLY)** | **1080×1920** | **Only accepted format for In-Feed and TopView** |
+
+**There is no alternative.** Horizontal (16:9) or square (1:1) compositions are
+rejected by TikTok Ads Manager. Always generate vertically.
+
+**File requirements:** MP4 or MOV, H.264, AAC audio required, max 500MB.
+**For image-based static ads:** PNG or JPG at 1080×1920.
+
+---
+
+## TikTok Safe Zone Diagram
+
+```
+┌─────────────────────────────────┐ ← Top (Y:0)
+│  STATUS BAR + ACCOUNT INFO      │ ← Y:0-150 (AVOID)
+├─────────────────────────────────┤
+│                      │LIKE      │ ← RIGHT EDGE: X:940-1080
+│                      │COMMENT   │    (AVOID; UI icons)
+│   ██████████████████ │SHARE     │
+│   █                █ │PROFILE   │
+│   █  SAFE CONTENT  █ │          │
+│   █     ZONE       █ │          │
+│   █  X:40 to X:940 █ │          │
+│   █  Y:150 to Y:1470█ │         │
+│   █  (900×1320px)  █ │          │
+│   ██████████████████ │          │
+│                                 │
+│  CAPTION + MUSIC + CTA + NAV    │ ← Y:1470-1920 (AVOID)
+└─────────────────────────────────┘ ← Bottom (Y:1920)
+```
+
+**Safe Box: X:40-940, Y:150-1470 (900×1320px)**
+
+All critical text, logos, faces, CTAs, and key product elements MUST be within
+the safe box. Anything outside this zone will be hidden behind UI overlays.
+
+---
+
+## Content Area Guidelines
+
+| Zone | Y Range | X Range | Action |
+|------|---------|---------|--------|
+| Status bar | 0-150 | full | Keep clear |
+| Right side icons | 150-1470 | 940-1080 | Keep clear |
+| Caption/CTA bar | 1470-1920 | full | Keep clear |
+| **Safe content zone** | **150-1470** | **40-940** | **Place all key content here** |
+
+**Subject placement rule:** Main subject (person, product) should be centered in the
+upper 60% of the safe zone (Y:150-900). This ensures visibility even on smaller screens.
+
+---
+
+## Copy Limits
+
+| Component | Max | Notes |
+|-----------|-----|-------|
+| Ad text | 100 chars | Appears below video |
+| Display name | 25 chars | Brand name shown |
+| CTA button | Predefined list | Auto-placed in safe zone |
+
+---
+
+## Ad Format Types
+
+### In-Feed Ads (Non-Spark)
+- Appears in For You Page (FYP) between organic videos
+- Duration: 5-60 seconds (rec 9-15s for highest completion)
+- Must have audio; silent video severely underperforms
+- Generate: static thumbnail at 1080×1920 within safe zone
+
+### Spark Ads
+- Promotes existing organic TikTok posts
+- Use organic video content; generate only the **thumbnail frame**
+- Thumbnail: 1080×1920, subject centered in safe zone
+
+### TopView
+- First ad seen when app opens (premium placement)
+- Specs: 720×1280 minimum (1080×1920 recommended), 5-60s
+- Higher production quality expected
+
+---
+
+## Generation Constraints
+
+**Always include in prompts:**
+- `"vertical composition, 9:16 aspect ratio"`
+- `"subject centered in upper portion of frame"`
+- `"bottom third is clear or minimal background"` (caption overlay area)
+- `"bold, eye-catching visual designed for mobile fullscreen"`
+
+**Forbidden in prompts:**
+- `"horizontal"`, `"landscape"`, `"widescreen"`; will generate wrong orientation
+- `"text in bottom third"`: will be covered by caption UI
+- `"logo in bottom corner"`: will be covered by TikTok navigation
+
+**Text in safe zone only:** If asking for text rendered into the image (not ad copy),
+specify `"text in upper center of frame, within 900px wide safe zone"`.
+
+---
+
+## Sound-On Platform Rule
+
+**Never run silent video on TikTok.** Audio is expected.
+- All video assets must have audio track
+- For static image ads: no audio required, but platform may add music
+- For generation: this constraint applies to video, not static image generation
+
+---
+
+## Aspect Ratio Priority
+
+TikTok has one option: **1080×1920 (9:16)**. No alternatives.
+
+---
+
+## Smart+ Specs
+
+Smart+ campaigns auto-generate creative variations:
+- Up to 50 creatives per asset group
+- Symphony AI generates variations from your base asset
+- Generate 1 high-quality base image; Smart+ handles variations

package/stacks/_shared/ads-agents/references/voice-to-style.md

@@ -0,0 +1,87 @@
+# Brand Voice to Visual Style Mapping
+
+> Updated: 2026-04-01
+> Source: Used by creative-strategist and visual-designer agents
+
+## Purpose
+
+Brand voice scores (1 to 10 scale) from `brand-profile.json` translate directly
+into visual style descriptors for image generation prompts. Each axis maps to
+specific aesthetic attributes that become the [STYLE] component in banana prompts.
+When multiple axes combine, their descriptors merge into a cohesive style string.
+
+## Axis Mappings
+
+### 1. formal_casual
+
+| Range     | Score | Visual Descriptors                                      |
+|-----------|-------|---------------------------------------------------------|
+| Low       | 1-3   | Clean lines, symmetrical, muted palette, serif type     |
+| Mid       | 4-6   | Balanced layout, neutral tones, modern sans-serif       |
+| High      | 7-10  | Organic shapes, warm palette, hand-drawn elements       |
+
+### 2. rational_emotional
+
+| Range     | Score | Visual Descriptors                                      |
+|-----------|-------|---------------------------------------------------------|
+| Low       | 1-3   | Data overlays, charts, structured grids, cool tones     |
+| Mid       | 4-6   | Infographic style, balanced data and imagery            |
+| High      | 7-10  | Expressive color, human faces, dynamic motion blur      |
+
+### 3. bold_subtle
+
+| Range     | Score | Visual Descriptors                                      |
+|-----------|-------|---------------------------------------------------------|
+| Low       | 1-3   | Soft focus, pastel tones, whitespace, thin strokes      |
+| Mid       | 4-6   | Medium contrast, standard weight type, clear hierarchy  |
+| High      | 7-10  | High contrast, saturated color, heavy type, full bleed  |
+
+### 4. traditional_innovative
+
+| Range     | Score | Visual Descriptors                                      |
+|-----------|-------|---------------------------------------------------------|
+| Low       | 1-3   | Classic compositions, heritage textures, earth tones    |
+| Mid       | 4-6   | Contemporary layouts, balanced modern and classic cues  |
+| High      | 7-10  | Futuristic gradients, 3D renders, neon accents, glass   |
+
+### 5. friendly_authoritative
+
+| Range     | Score | Visual Descriptors                                      |
+|-----------|-------|---------------------------------------------------------|
+| Low       | 1-3   | Rounded shapes, illustration style, bright accents      |
+| Mid       | 4-6   | Mixed photography and illustration, approachable layout |
+| High      | 7-10  | Editorial photography, dark backgrounds, gold accents   |
+
+### 6. playful_serious
+
+| Range     | Score | Visual Descriptors                                      |
+|-----------|-------|---------------------------------------------------------|
+| Low       | 1-3   | Whimsical patterns, cartoon elements, candy colors      |
+| Mid       | 4-6   | Lifestyle photography, natural color grading            |
+| High      | 7-10  | Cinematic lighting, desaturated palette, minimal decor  |
+
+## How to Apply
+
+1. Read `brand-profile.json` and extract the six voice axis scores.
+2. For each axis, look up the matching range (Low, Mid, High) in the table above.
+3. Collect one or two descriptors per axis that best fit the brand context.
+4. Combine all selected descriptors into a single [STYLE] string, separated by commas.
+5. Append the [STYLE] string to the banana prompt template before generation.
+
+## Example
+
+Given a brand with these scores:
+
+- formal_casual: 7 (High; organic shapes, warm palette)
+- bold_subtle: 8 (High; high contrast, saturated color)
+- playful_serious: 3 (Low; whimsical patterns, candy colors)
+
+The resulting [STYLE] component:
+
+```
+[STYLE]: organic shapes, warm palette, high contrast, saturated color,
+whimsical patterns, candy colors
+```
+
+This creates a vibrant, approachable visual identity that feels energetic
+and playful while maintaining strong visual impact.