start-vibing-stacks 2.29.0 → 2.30.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/dist/setup.js +15 -1
  2. package/package.json +1 -1
  3. package/stacks/_shared/ads-agents/README.md +452 -0
  4. package/stacks/_shared/ads-agents/RESEARCH-REPORT.md +157 -0
  5. package/stacks/_shared/ads-agents/SKILL.md +210 -0
  6. package/stacks/_shared/ads-agents/SKILLS-UPDATE-REPORT.md +255 -0
  7. package/stacks/_shared/ads-agents/agents/audit-budget.md +116 -0
  8. package/stacks/_shared/ads-agents/agents/audit-compliance.md +131 -0
  9. package/stacks/_shared/ads-agents/agents/audit-creative.md +127 -0
  10. package/stacks/_shared/ads-agents/agents/audit-google.md +113 -0
  11. package/stacks/_shared/ads-agents/agents/audit-meta.md +112 -0
  12. package/stacks/_shared/ads-agents/agents/audit-tracking.md +134 -0
  13. package/stacks/_shared/ads-agents/agents/copy-writer.md +188 -0
  14. package/stacks/_shared/ads-agents/agents/creative-strategist.md +199 -0
  15. package/stacks/_shared/ads-agents/agents/format-adapter.md +175 -0
  16. package/stacks/_shared/ads-agents/agents/visual-designer.md +245 -0
  17. package/stacks/_shared/ads-agents/references/additional-platforms.md +106 -0
  18. package/stacks/_shared/ads-agents/references/benchmarks.md +257 -0
  19. package/stacks/_shared/ads-agents/references/bidding-strategies.md +333 -0
  20. package/stacks/_shared/ads-agents/references/brand-dna-template.md +190 -0
  21. package/stacks/_shared/ads-agents/references/budget-allocation.md +150 -0
  22. package/stacks/_shared/ads-agents/references/compliance.md +280 -0
  23. package/stacks/_shared/ads-agents/references/conversion-tracking.md +246 -0
  24. package/stacks/_shared/ads-agents/references/copy-frameworks.md +187 -0
  25. package/stacks/_shared/ads-agents/references/funnel-content-copy-rules.md +44 -0
  26. package/stacks/_shared/ads-agents/references/gaql-notes.md +49 -0
  27. package/stacks/_shared/ads-agents/references/google-audit.md +217 -0
  28. package/stacks/_shared/ads-agents/references/google-creative-specs.md +119 -0
  29. package/stacks/_shared/ads-agents/references/image-providers.md +133 -0
  30. package/stacks/_shared/ads-agents/references/linkedin-audit.md +141 -0
  31. package/stacks/_shared/ads-agents/references/linkedin-creative-specs.md +129 -0
  32. package/stacks/_shared/ads-agents/references/mcp-integration.md +125 -0
  33. package/stacks/_shared/ads-agents/references/meta-audit.md +141 -0
  34. package/stacks/_shared/ads-agents/references/meta-creative-specs.md +134 -0
  35. package/stacks/_shared/ads-agents/references/microsoft-audit.md +158 -0
  36. package/stacks/_shared/ads-agents/references/microsoft-creative-specs.md +123 -0
  37. package/stacks/_shared/ads-agents/references/platform-specs.md +276 -0
  38. package/stacks/_shared/ads-agents/references/scoring-system.md +169 -0
  39. package/stacks/_shared/ads-agents/references/tiktok-audit.md +165 -0
  40. package/stacks/_shared/ads-agents/references/tiktok-creative-specs.md +139 -0
  41. package/stacks/_shared/ads-agents/references/voice-to-style.md +87 -0
  42. package/stacks/_shared/ads-agents/references/youtube-creative-specs.md +134 -0
  43. package/stacks/_shared/ads-agents/skills/ads-apple/SKILL.md +225 -0
  44. package/stacks/_shared/ads-agents/skills/ads-audit/SKILL.md +108 -0
  45. package/stacks/_shared/ads-agents/skills/ads-budget/SKILL.md +198 -0
  46. package/stacks/_shared/ads-agents/skills/ads-competitor/SKILL.md +198 -0
  47. package/stacks/_shared/ads-agents/skills/ads-create/SKILL.md +198 -0
  48. package/stacks/_shared/ads-agents/skills/ads-creative/SKILL.md +208 -0
  49. package/stacks/_shared/ads-agents/skills/ads-dna/SKILL.md +245 -0
  50. package/stacks/_shared/ads-agents/skills/ads-generate/SKILL.md +173 -0
  51. package/stacks/_shared/ads-agents/skills/ads-google/SKILL.md +192 -0
  52. package/stacks/_shared/ads-agents/skills/ads-landing/SKILL.md +186 -0
  53. package/stacks/_shared/ads-agents/skills/ads-linkedin/SKILL.md +200 -0
  54. package/stacks/_shared/ads-agents/skills/ads-math/SKILL.md +216 -0
  55. package/stacks/_shared/ads-agents/skills/ads-meta/SKILL.md +167 -0
  56. package/stacks/_shared/ads-agents/skills/ads-microsoft/SKILL.md +163 -0
  57. package/stacks/_shared/ads-agents/skills/ads-photoshoot/SKILL.md +220 -0
  58. package/stacks/_shared/ads-agents/skills/ads-plan/SKILL.md +176 -0
  59. package/stacks/_shared/ads-agents/skills/ads-test/SKILL.md +199 -0
  60. package/stacks/_shared/ads-agents/skills/ads-tiktok/SKILL.md +190 -0
  61. package/stacks/_shared/ads-agents/skills/ads-youtube/SKILL.md +199 -0
  62. package/stacks/_shared/memories/funnel-content-copy.md +81 -0
  63. package/templates/CLAUDE-python.md +6 -0
@@ -0,0 +1,333 @@
1
+ # Bidding Strategy Decision Trees
2
+
3
+ <!-- Updated: 2026-05-14 | v1.6: corrected AI Max conversion lift + DSA migration timing -->
4
+ <!-- Sources: Google Research PDF 2, Claude Research, Gemini Research, 2026 Verification Pass -->
5
+
6
+ ## Google Ads Bidding Decision Engine
7
+
8
+ ### Strategy Selection Flow
9
+
10
+ ```
11
+ START → How many conversions in last 30 days?
12
+
13
+ ┌─ < 15 conversions ──────────────────────────┐
14
+ │ → Maximize Clicks (cold start) │
15
+ │ → Set Max CPC = Target_CPA / (CVR × 1.5) │
16
+ │ → Learning: 3-5 days │
17
+ │ → Monitor until 15+ conversions achieved │
18
+ │ → OR use Manual CPC if full control needed │
19
+ │ → NOTE: eCPC fully removed March 2025 │
20
+ └──────────────────────────────────────────────┘
21
+
22
+ ┌─ 15-29 conversions ─────────────────────────┐
23
+ │ → Maximize Conversions (uncapped) │
24
+ │ → Learning: 7-14 days │
25
+ │ → Transition when CPA SD < 20% over 14d │
26
+ │ → THEN switch to Target CPA │
27
+ └──────────────────────────────────────────────┘
28
+
29
+ ┌─ 30+ conversions, NO dynamic values ────────┐
30
+ │ → Target CPA │
31
+ │ → Strict: 30+ (Google says 15, but 30+ │
32
+ │ for reliable performance, 50+ ideal) │
33
+ │ → Set at: 1.1x-1.2x historical CPA │
34
+ │ → Adjust: Max 10% change every 14 days │
35
+ │ → Never lower by more than 15% at once │
36
+ └──────────────────────────────────────────────┘
37
+
38
+ ┌─ 50+ conversions WITH dynamic values ───────┐
39
+ │ → Target ROAS │
40
+ │ → Requires dynamic conversion values │
41
+ │ → Set at: EXACT historical ROAS │
42
+ │ → Formula: Bid = P(conv) × Value × 1/tROAS│
43
+ │ → Adjust: Same rules as tCPA │
44
+ └──────────────────────────────────────────────┘
45
+
46
+ ### Smart Bidding Exploration (Google, 2025+)
47
+
48
+ Allows flexible ROAS targets to discover new traffic. Delivers 18% more
49
+ unique search query categories + 19% more conversions.
50
+
51
+ - **How it works**: Algorithm temporarily relaxes ROAS constraints to
52
+ enter auctions it would normally skip, testing new user segments
53
+ - **When to enable**: Stable tROAS campaigns with 50+ conversions/month
54
+ seeking incremental growth beyond current query coverage
55
+ - **When to avoid**: Tight-margin accounts or campaigns already spending
56
+ full budget (exploration adds volume, not just efficiency)
57
+ - **Available on**: Target ROAS bid strategies only
58
+
59
+ ### AI Max for Search (Google, 2025+)
60
+
61
+ AI Max for Search layers broad match + keywordless targeting on existing
62
+ Search campaigns. Google reports 7% more conversions or conversion value
63
+ at comparable CPA/ROAS when the full feature suite is enabled (search
64
+ term matching + text customization + final URL expansion). DSA officially
65
+ being consolidated into AI Max with automatic upgrades starting September
66
+ 2026; new DSA campaign creation ends September 2026. Requires strong
67
+ negative keyword lists.
68
+
69
+ - **How it works**: Automatically expands keyword coverage using AI to
70
+ match user intent beyond exact keyword matches
71
+ - **When to enable**: Established Search campaigns with healthy conversion
72
+ volume and comprehensive negative keyword lists
73
+ - **When to avoid**: Low-budget campaigns without negative keyword hygiene;
74
+ accounts with strict brand safety requirements
75
+ - **Migration note**: Migrate DSA campaigns to AI Max before September 2026 auto-upgrade
76
+
77
+ ┌─ Brand Protection campaigns ────────────────┐
78
+ │ → Target Impression Share │
79
+ │ → Target: 95-100% on brand keywords │
80
+ │ → No conversion data requirement │
81
+ │ → Search only (not available elsewhere) │
82
+ └──────────────────────────────────────────────┘
83
+
84
+ SPECIAL CASES:
85
+ - PMax: Always uses Maximize Conversions or Maximize Conv Value
86
+ - Demand Gen: Supports Target CPC (new), tCPA, tROAS, Max Clicks
87
+ - Display Pay per Conversion: Eligibility required
88
+ ```
89
+
90
+ ### Attribution Model (Google)
91
+ - **DDA (Data-Driven Attribution) is now MANDATORY default** (September 2025)
92
+ - Only two models remain: DDA and Last Click
93
+ - All rule-based models deprecated (first-click, linear, time decay, position-based)
94
+ - No minimum data threshold for DDA
95
+ - Impact on bidding: DDA distributes conversion credit across touchpoints, affecting Smart Bidding signals
96
+
97
+ ### Portfolio Bid Strategies
98
+
99
+ When to use portfolios:
100
+ - Multiple campaigns each with <15 conv, but combined >30
101
+ - Need cross-campaign budget optimization
102
+ - **CPC Cap Hack**: Only way to set max CPC bid on tCPA/tROAS
103
+
104
+ Rules:
105
+ - Minimum 3 campaigns per portfolio for meaningful data
106
+ - Group campaigns with similar target CPAs/ROAS
107
+ - Never mix brand and non-brand in same portfolio
108
+
109
+ ### Transition Triggers (Google)
110
+
111
+ | From | To | Trigger |
112
+ |------|----|---------|
113
+ | Maximize Clicks | Maximize Conversions | 15+ conversions in 30 days |
114
+ | Maximize Conversions | Target CPA | CPA SD <20% over 14 days + 30+ conv |
115
+ | Target CPA | Target ROAS | 50+ conv + dynamic values available |
116
+ | Manual CPC | Maximize Clicks | Ready to test automation |
117
+ | Any | Target Impression Share | Brand protection need identified |
118
+
119
+ ---
120
+
121
+ ## Meta Ads Bidding Decision Engine
122
+
123
+ ### Auction Formula
124
+
125
+ ```
126
+ Total Value = Bid × Estimated Action Rate + User Value
127
+ ```
128
+
129
+ ### Strategy Selection
130
+
131
+ ```
132
+ DEFAULT (90% of campaigns):
133
+ → Lowest Cost (no cap)
134
+ → Best for: Most campaigns, volume maximization
135
+ → Risk: CPA can spike during high-competition (Q4)
136
+
137
+ IF need cost predictability:
138
+ → Cost Cap
139
+ → Set at: 1.2x - 1.5x target CPA
140
+ → Best for: Scaling with margin protection
141
+ → Risk: Under-delivery if cap too aggressive
142
+
143
+ IF need strict cost control:
144
+ → Bid Cap
145
+ → Set at: 2x - 3x target CPA
146
+ → Best for: Experienced advertisers with clear unit economics
147
+ → Risk: Significant under-delivery if too low
148
+
149
+ IF e-commerce with revenue tracking:
150
+ → ROAS Goal
151
+ → Best for: Advantage+ Sales Campaigns
152
+ → Requires: Purchase event + dynamic values
153
+
154
+ IF high-value diverse products:
155
+ → Highest Value
156
+ → Prioritizes high-value conversions
157
+ → Best for: Wide AOV range
158
+ ```
159
+
160
+ ### Andromeda Context
161
+
162
+ Under Andromeda, creative diversity matters more than bid strategy.
163
+ Focus budget on creative testing, not micro-optimizing bids.
164
+
165
+ ### CBO vs ABO Decision
166
+
167
+ ```
168
+ IF daily_budget < $100:
169
+ → ABO (manual control for testing)
170
+
171
+ IF daily_budget $100-$500:
172
+ → Test both; CBO if similar audiences, ABO if diverse
173
+
174
+ IF daily_budget > $500:
175
+ → CBO (Advantage+ Campaign Budget)
176
+ → Let Meta optimize distribution
177
+
178
+ NOTE: Advantage+ Sales/Leads auto-enable CBO
179
+ ```
180
+
181
+ ### Learning Phase Rules
182
+
183
+ **Exit criteria:** 50 conversions per week per ad set
184
+
185
+ **Reset triggers (avoid during learning):**
186
+ - Budget change >20%
187
+ - Any targeting change
188
+ - Creative edit (even text)
189
+ - Bid strategy change
190
+ - Pausing >7 days
191
+
192
+ **If "Learning Limited":**
193
+ 1. Broaden audience
194
+ 2. Increase budget
195
+ 3. Switch to higher-funnel event (AddToCart instead of Purchase)
196
+ 4. Consolidate ad sets
197
+ 5. Ensure daily budget ≥5× target CPA
198
+
199
+ ---
200
+
201
+ ## LinkedIn Ads Bidding
202
+
203
+ ### Strategy Selection
204
+
205
+ ```
206
+ Sponsored Content:
207
+ → Start with Manual CPC for cost control (recommended default)
208
+ → Test automated bidding only with established data
209
+ → Maximum Delivery is the most expensive option
210
+ → Minimum daily budget: $10/day (recommend $50+)
211
+
212
+ Message Ads:
213
+ → CPS (Cost Per Send): bid aggressively
214
+ → Frequency cap: 1 per 30-45 days per user
215
+ → Win the auction for limited inbox slot
216
+
217
+ Lead Gen Forms:
218
+ → Lowest Cost or Manual CPC
219
+ → 13% CVR benchmark (3.25× landing pages)
220
+
221
+ Conversation Ads:
222
+ → CPS: similar to Message Ads
223
+ → 10-12% CTR benchmark
224
+
225
+ TLA (Thought Leader Ads):
226
+ → Allocate ≥30% budget
227
+ → CPC $2.29-$4.14 (vs $13.23 standard)
228
+
229
+ Accelerate Campaigns:
230
+ → AI-powered end-to-end
231
+ → 42% lower CPA, 21% lower CPL
232
+ ```
233
+
234
+ ---
235
+
236
+ ## TikTok Ads Bidding
237
+
238
+ ### Strategy Selection
239
+
240
+ ```
241
+ DEFAULT:
242
+ → Lowest Cost (volume maximization)
243
+ → Most common, good starting point
244
+
245
+ IF margin protection needed:
246
+ → Cost Cap
247
+ → Set target CPA, system tries to stay near
248
+
249
+ IF strict cost control needed:
250
+ → Bid Cap
251
+ → Controls maximum bid per auction (not average CPA)
252
+ → Set at 2-3x target CPA initially
253
+ → Best for: retargeting, competitive niches (Q4/BFCM)
254
+ → Risk: significant under-delivery if set too aggressively
255
+
256
+ IF Smart+ campaign:
257
+ → Modular automation (choose per module)
258
+ → Up to 30 ad groups, 50 creatives per asset group
259
+ → Smart+ now supports modular control (2025). Lock
260
+ targeting/creative/budget/placement independently
261
+ while automating others
262
+
263
+ GMV Max (TikTok Shop):
264
+ → Default/only for Shop campaigns (July 2025)
265
+ → Optimizes for Gross Merchandise Value
266
+ ```
267
+
268
+ ### Budget Rules
269
+ - Campaign minimum: $50/day
270
+ - Ad group minimum: $20/day
271
+ - Budget should be ≥50× target CPA per ad group (provides sufficient learning room)
272
+ - Learning phase: ~50 conversions in 7 days
273
+
274
+ ---
275
+
276
+ ## Microsoft Ads Bidding
277
+
278
+ ### Strategy Selection
279
+
280
+ ```
281
+ IF importing from Google:
282
+ → Match Google bid strategy
283
+ → Validate settings transferred correctly
284
+ → Adjust targets (typically 20-35% lower CPC on Bing)
285
+
286
+ IF native campaign:
287
+ → Same strategy framework as Google
288
+ → Lower CPC targets (expect $1.20-$1.55 avg)
289
+ → Enable Copilot placement for PMax
290
+
291
+ PMax on Microsoft:
292
+ → Enable "Target New Customers" (Beta 2026)
293
+ → Copilot chat placement: 73% higher CTR
294
+ → LinkedIn profile targeting (unique)
295
+ ```
296
+
297
+ ---
298
+
299
+ ## Apple Ads Bidding
300
+
301
+ ### Maximize Conversions (GA Feb 26, 2026)
302
+
303
+ AI-powered auto-bidder using Search Match. Currently only optimizes for installs.
304
+
305
+ ```
306
+ Strategy Selection:
307
+ → Maximize Conversions (recommended for most campaigns)
308
+ → Target CPA (weekly average target) replaces CPA Cap (being deprecated)
309
+ → Daily budget >= 5x target CPA
310
+ → Two-week learning period before evaluating performance
311
+
312
+ Key Rules:
313
+ → Set realistic target CPA based on historical install cost
314
+ → Avoid budget or target changes during the 2-week learning period
315
+ → Currently only optimizes for installs (not post-install events)
316
+ → Pair with strong Search Match negative keywords to control relevance
317
+ ```
318
+
319
+ ---
320
+
321
+ ## Cross-Platform Bidding Red Flags
322
+
323
+ | Red Flag | Severity | Platform | Action |
324
+ |----------|----------|----------|--------|
325
+ | Broad Match + Manual CPC | Critical | Google | Switch to Smart Bidding or Exact Match |
326
+ | tCPA <50% of actual CPA | Critical | Google | Unrealistic target; set at 1.1-1.2× historical |
327
+ | Smart Bidding with <15 conv/month | High | Google | Use Manual CPC or Maximize Clicks |
328
+ | >50% ad sets "Learning Limited" | Critical | Meta | Consolidate, broaden audience, increase budget |
329
+ | Cost Cap below historical CPA | High | Meta | Set at 1.2-1.5× target, not below |
330
+ | Daily budget <5× CPA | High | Meta | Increase budget or switch to higher-funnel event |
331
+ | Budget < $50/day campaign | High | TikTok | Increase to minimum or consolidate |
332
+ | No negative keywords with Broad Match | Critical | Google | Add themed negative lists immediately |
333
+ | No Portfolio strategy for low-vol campaigns | Medium | Google | Group <15 conv campaigns into portfolio |
@@ -0,0 +1,190 @@
1
+ # Brand DNA Template
2
+
3
+ <!-- Updated: 2026-03-12 -->
4
+ <!-- Used by: ads-dna (extraction), ads-create (consumption), ads-generate (style injection) -->
5
+
6
+ ## Purpose
7
+
8
+ Defines the canonical schema for `brand-profile.json`. All agents that produce or
9
+ consume brand data must use these exact field names and value types.
10
+
11
+ ---
12
+
13
+ ## JSON Schema
14
+
15
+ ```json
16
+ {
17
+ "schema_version": "1.0",
18
+ "brand_name": "string",
19
+ "website_url": "string (full URL including https://)",
20
+ "extracted_at": "ISO-8601 timestamp (e.g. 2026-03-12T14:30:00Z)",
21
+
22
+ "voice": {
23
+ "formal_casual": 7,
24
+ "rational_emotional": 4,
25
+ "playful_serious": 5,
26
+ "bold_subtle": 8,
27
+ "traditional_innovative": 6,
28
+ "expert_accessible": 5,
29
+ "descriptors": ["authoritative", "warm", "direct"]
30
+ },
31
+
32
+ "colors": {
33
+ "primary": "#1A2E4A",
34
+ "secondary": ["#F4A623", "#FFFFFF"],
35
+ "forbidden": ["#FF0000"],
36
+ "background": "#F9F9F9",
37
+ "text": "#1A1A1A"
38
+ },
39
+
40
+ "typography": {
41
+ "heading_font": "Inter",
42
+ "body_font": "Source Sans Pro",
43
+ "pairing_descriptor": "modern sans-serif, clean and readable"
44
+ },
45
+
46
+ "imagery": {
47
+ "style": "professional photography",
48
+ "subjects": ["people using product", "clean product shots", "diverse workforce"],
49
+ "composition": "clean backgrounds, good negative space",
50
+ "forbidden": ["stock photo clichés", "corporate handshakes", "cheesy smiles"]
51
+ },
52
+
53
+ "aesthetic": {
54
+ "mood_keywords": ["trustworthy", "modern", "approachable"],
55
+ "texture": "minimal, flat",
56
+ "negative_space": "generous"
57
+ },
58
+
59
+ "brand_values": ["transparency", "innovation", "customer-first"],
60
+
61
+ "target_audience": {
62
+ "age_range": "28-45",
63
+ "profession": "marketing managers and small business owners",
64
+ "pain_points": ["time-consuming reporting", "unclear ROI"],
65
+ "aspirations": ["grow efficiently", "look professional"]
66
+ },
67
+
68
+ "screenshots": {
69
+ "homepage": "./brand-screenshots/example_com_desktop.png",
70
+ "secondary": ["./brand-screenshots/example_com_pricing_desktop.png"]
71
+ }
72
+ }
73
+ ```
74
+
75
+ ---
76
+
77
+ ## Field Reference
78
+
79
+ ### Voice Axes (1-10 scale)
80
+
81
+ Score interpretation: 1 = extreme left pole, 10 = extreme right pole, 5 = neutral.
82
+
83
+ | Field | 1 (Left) | 10 (Right) | Ad Implication |
84
+ |-------|----------|------------|----------------|
85
+ | `formal_casual` | Very formal, corporate | Very casual, conversational | Headlines tone |
86
+ | `rational_emotional` | Data-driven, logical | Emotionally evocative | Story vs stats |
87
+ | `playful_serious` | Fun, humorous | Serious, no-nonsense | CTA phrasing |
88
+ | `bold_subtle` | Big claims, loud | Understated, nuanced | Visual hierarchy |
89
+ | `traditional_innovative` | Classic, established | Cutting-edge, disruptive | Imagery style |
90
+ | `expert_accessible` | Deep expertise, jargon | Everyone can understand | Copy complexity |
91
+
92
+ `descriptors` (array of 3-5 strings): Free-form adjectives capturing tone not covered by axes.
93
+
94
+ ### Colors
95
+
96
+ - `primary`: Main brand color. **Always inject into image generation prompts.**
97
+ - `secondary`: Supporting palette. Use for accents in generation prompts.
98
+ - `forbidden`: Colors to explicitly exclude from prompts (e.g., competitor brand colors).
99
+ - `background` / `text`: Digital UI colors (less relevant for ad image generation).
100
+
101
+ **Null handling:** If extraction fails for a color, set to `null`. Agents must skip null
102
+ color injection rather than defaulting to arbitrary colors.
103
+
104
+ ### Typography
105
+
106
+ Used by `copy-writer` agent for tone calibration. Not injected into image prompts
107
+ (typography is handled by ad platform copy fields, not image generation).
108
+
109
+ ### Imagery
110
+
111
+ - `style`: Main descriptor passed to image generation (e.g., "professional photography",
112
+ "illustration", "flat design").
113
+ - `subjects`: Array injected as subject guidance in prompts.
114
+ - `composition`: Passed verbatim as a composition constraint.
115
+ - `forbidden`: Converted to negative prompt modifiers (e.g., "no corporate handshakes").
116
+
117
+ ### Aesthetic
118
+
119
+ - `mood_keywords`: Injected directly into generation prompts as atmosphere descriptors.
120
+ - `texture`: Passed as texture preference.
121
+ - `negative_space`: "generous" → "plenty of white space, uncluttered composition".
122
+
123
+ ### Screenshots (optional, populated by `/ads dna`)
124
+
125
+ - `homepage`: Desktop screenshot of homepage. **Primary visual style reference** for
126
+ `visual-designer` agent. When present, generation auto-uses `gemini-3.1-flash-image-preview`
127
+ (Nano Banana 2) for better brand style-transfer.
128
+ - `secondary`: Additional pages (pricing, about, product). Supplemental context.
129
+ - **If field absent**: `visual-designer` falls back to text-only generation (`gemini-2.5-flash-image`).
130
+ - **If field present but file missing on disk**: `visual-designer` logs a warning and falls back gracefully.
131
+ - Set by `ads-dna` Step 2b. Omitted entirely if screenshot capture failed or `--quick` was used.
132
+
133
+ ---
134
+
135
+ ## Extraction Guide
136
+
137
+ ### Pages to scan (in order)
138
+
139
+ 1. **Homepage**: Primary brand impression, dominant colors, hero headline tone
140
+ 2. **About / Our Story**: Brand values, voice descriptors, team photography style
141
+ 3. **Product / Service page**: Imagery style, composition, subject matter
142
+ 4. **Existing ads** (if accessible via Meta Ad Library or Google Ads Transparency): Override
143
+
144
+ ### CSS extraction targets
145
+
146
+ ```
147
+ background-color, color → colors.primary / secondary
148
+ font-family → typography.heading_font / body_font
149
+ @import url (Google Fonts) → typography (font name from URL path)
150
+ og:image meta tag → imagery.style (analyze dominant visual)
151
+ ```
152
+
153
+ ### Voice scoring heuristics
154
+
155
+ | Signal | Scoring |
156
+ |--------|---------|
157
+ | Uses "you" and "your" frequently | formal_casual +2 (casual) |
158
+ | Industry jargon in hero text | expert_accessible -2 (expert) |
159
+ | Short sentences (≤10 words) | bold_subtle +1 (bold) |
160
+ | Testimonials lead with emotion | rational_emotional +2 (emotional) |
161
+ | "Trusted by 10,000+ companies" | traditional_innovative -1 (traditional) |
162
+
163
+ ### Fallback heuristics
164
+
165
+ - **No Google Fonts detected**: Set `typography.heading_font` to "system-ui"
166
+ - **Sparse content (< 200 words)**: Mark `extracted_at` note: "low confidence extraction"
167
+ - **Dark mode site**: If background is dark (#333 or darker), swap `background` and `text`
168
+ - **Cannot extract primary color**: Use most prominent color from og:image analysis
169
+
170
+ ---
171
+
172
+ ## Usage in Generation Prompts
173
+
174
+ When building image generation prompts, inject brand DNA as:
175
+
176
+ ```
177
+ "[subject], [imagery.style], [imagery.composition],
178
+ brand colors [colors.primary] and [colors.secondary[0]],
179
+ [aesthetic.mood_keywords joined by comma] atmosphere,
180
+ [aesthetic.texture] texture, [aesthetic.negative_space] composition,
181
+ no [imagery.forbidden joined by comma]"
182
+ ```
183
+
184
+ Example output:
185
+ ```
186
+ "person using laptop, professional photography, clean backgrounds good negative space,
187
+ brand colors #1A2E4A and #F4A623, trustworthy modern approachable atmosphere,
188
+ minimal flat texture, generous white space composition,
189
+ no stock photo clichés, no corporate handshakes"
190
+ ```
@@ -0,0 +1,150 @@
1
+ # Budget Allocation & Scaling Framework
2
+
3
+ <!-- Updated: 2026-02-10 -->
4
+ <!-- Sources: Google Research PDF 2, Claude Research, Gemini Research -->
5
+
6
+ ## Platform Selection Matrix by Business Type
7
+
8
+ | Business Type | Platform 1 | Platform 2 | Platform 3 | Other | Min Monthly | Primary KPI | Time to Profit |
9
+ |--------------|------------|------------|------------|-------|-------------|-------------|---------------|
10
+ | SaaS B2B | Google 35-45% | LinkedIn 30-40% | Meta 15-25% | YouTube 10% | $5,000 | Pipeline ROI, LTV:CAC | 3-6 months |
11
+ | E-commerce DTC | Meta 50-68% | Google PMax 23-30% | TikTok 5-15% | Email 5% | $3,000 | ROAS, MER, POAS | 0-2 months |
12
+ | Local Service | Google LSA/Search 60% | Meta 30% | Bing 10% | N/A | $1,500 | Cost Per Lead/Booking | 1 month |
13
+ | B2B Enterprise | LinkedIn 39-60% | Google 20-35% | ABM Display 15-20% | Programmatic 11% | $10,000 | Pipeline, SQLs | 6-12 months |
14
+ | Info Products | YouTube 40% | Meta 40% | Email 20% | N/A | $2,000 | ROAS, Webinar CPL | 1-3 months |
15
+ | Mobile App | Apple Search 30% | Google App 30% | Meta/TikTok 40% | N/A | $5,000 | CPI, LTV, D7 Retention | 3-6 months |
16
+ | Real Estate | Meta Lead Forms 50% | Google Search 40% | LinkedIn 10% | N/A | $2,500 | Cost Per Lead | 2-4 months |
17
+ | Healthcare | Google Search 55% | Meta 20% | Microsoft 10% | YouTube/Display 15% | $4,000 | Cost Per Patient | 2-5 months |
18
+ | Finance/Fintech | Google Search 40-50% | LinkedIn 20-30% | Meta 15% | YouTube/Display 10% | $8,000 | CAC, LTV:CAC | 4-8 months |
19
+ | Agency (Own) | LinkedIn 50% | Meta 30% | Google 20% | N/A | $1,500 | Cost Per Lead | 1-3 months |
20
+ | B2C / DTC | Meta 50% | Google 20% | TikTok 30% | N/A | $2,000 | ROAS, CAC | 1-3 months |
21
+
22
+ ## Budget Distribution Rule: 70/20/10
23
+
24
+ ```
25
+ 70% → Proven performers (campaigns with established positive ROAS/CPA)
26
+ 20% → Promising growth (campaigns showing traction, need scale)
27
+ 10% → Experiments (new platforms, audiences, formats)
28
+ ```
29
+
30
+ ## Scaling Decision Tree
31
+
32
+ ### 20% Rule (Scale Up)
33
+ ```
34
+ IF actual_CPA < target_CPA by > 10%
35
+ AND conversions_last_7d >= learning_threshold
36
+ AND campaign NOT in learning phase
37
+ THEN increase budget by 20%
38
+ → Wait 3-5 days before next increase
39
+ → Never increase more than 20% at once on Meta (triggers learning reset)
40
+ ```
41
+
42
+ ### 3× Kill Rule (Pause)
43
+ ```
44
+ IF spend > 3× target_CPA
45
+ AND conversions == 0
46
+ THEN pause ad/ad set/campaign immediately
47
+ → Review: creative, targeting, landing page, tracking
48
+ → Don't restart without changes
49
+ ```
50
+
51
+ ### Decreasing Returns Detection
52
+ ```
53
+ IF CPA increased > 15% after last budget increase
54
+ THEN roll back to previous budget level
55
+ → Wait 7 days
56
+ → Try horizontal scaling instead (new audiences, platforms)
57
+ ```
58
+
59
+ ### Saturation Signals
60
+ | Platform | Signal | Threshold | Action |
61
+ |----------|--------|-----------|--------|
62
+ | Google | Impression Share | >80% | Diminishing returns; diversify |
63
+ | Meta | Frequency (7-day) | >4.0 | Audience exhausted; refresh creative or expand |
64
+ | TikTok | Frequency | >3.0 | Creative fatigue; replace assets |
65
+ | LinkedIn | Audience penetration | >50% | Audience exhausted; expand targeting |
66
+
67
+ ## Marketing Efficiency Ratio (MER)
68
+
69
+ ```
70
+ MER = Total Revenue / Total Ad Spend (all platforms combined)
71
+ ```
72
+
73
+ | Business Type | Healthy MER | Excellent MER | Danger Zone |
74
+ |--------------|-------------|---------------|-------------|
75
+ | E-commerce | 3.0-5.0 | >5.0 | <2.0 |
76
+ | SaaS | Use LTV:CAC (3:1 target) | >4:1 | <2:1 |
77
+ | Lead Gen | Revenue/Lead × CVR / CPL | N/A | <1.5 |
78
+
79
+ **Why MER over ROAS:**
80
+ - ROAS is platform-reported (overclaims by 20-40%)
81
+ - MER captures true business economics
82
+ - Cross-platform; not inflated by attribution overlap
83
+
84
+ ## Seasonality Adjustments
85
+
86
+ ### Q4 (October-December)
87
+ - CPMs increase 30-50%
88
+ - Reduce ROAS targets by 20%
89
+ - Front-load creative testing in September
90
+ - Increase budgets 40-60% for Black Friday / Cyber Monday
91
+ - Meta: Advantage+ Sales performs best during peaks
92
+
93
+ ### Q1 (January-March)
94
+ - CPMs decrease 20-30% post-holiday
95
+ - Best time for new campaign testing
96
+ - Aggressive customer acquisition (lower competition)
97
+ - Meta Jan 2026 CPC: $0.85 (24% below prior January)
98
+
99
+ ### Q2 (April-June)
100
+ - Steady CPMs, good testing window
101
+ - Mother's Day / Father's Day spikes for retail
102
+
103
+ ### Q3 (July-September)
104
+ - LinkedIn CPC peaks in Q3 ($15.72 average)
105
+ - Back-to-school surge for education
106
+ - Good time to build retargeting pools for Q4
107
+
108
+ ## Incrementality Testing (Geo-Lift)
109
+
110
+ ### Setup
111
+ - Duration: 2-4 weeks minimum
112
+ - Holdout: 10% of geographic regions (matched pairs)
113
+ - Method: Compare conversion rates exposed vs holdout
114
+ - Statistical significance: p < 0.05
115
+
116
+ ### Tools
117
+ - Meta: Robyn (R-based, open source), best for ~80% of orgs
118
+ - Google: Meridian (Python, Bayesian, geo-level)
119
+ - Advanced: PyMC-Marketing (fully customizable)
120
+ - Budget: Significant; allocate 10% of monthly spend for testing
121
+
122
+ ### Post-Purchase Surveys
123
+ - Fill ~30% of attribution gap that digital tracking misses
124
+ - Question: "How did you first hear about us?"
125
+ - Implement on order confirmation page
126
+ - Weight responses against platform-reported data
127
+
128
+ ## Minimum Viable Budgets
129
+
130
+ | Platform | Minimum Monthly | Rationale |
131
+ |----------|----------------|-----------|
132
+ | Google Ads | $1,000 | 15+ conv/month minimum for Smart Bidding |
133
+ | Meta Ads | $600-$800 | 50 conv/week/ad set × $CPA |
134
+ | LinkedIn Ads | $3,000 | High CPCs; $10/day minimum × multiple campaigns |
135
+ | TikTok Ads | $300 | $50/day campaign min × creative testing needs |
136
+ | Microsoft Ads | $200-$300 | 20-30% of Google budget |
137
+
138
+ ## Cross-Platform Attribution Hierarchy
139
+
140
+ ```
141
+ Source of Truth (best → worst):
142
+ 1. CRM Data (actual revenue, closed deals, LTV)
143
+ 2. MER (total revenue / total ad spend)
144
+ 3. Post-Purchase Surveys ("How did you hear about us?")
145
+ 4. Google Analytics 4 (cross-channel, multi-touch)
146
+ 5. Platform-Reported Data (always overclaims 20-40%)
147
+
148
+ RULE: Never trust platform-reported ROAS alone.
149
+ Always cross-reference with ≥2 other data sources.
150
+ ```