start-vibing-stacks 2.28.0 → 2.30.0

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

@@ -0,0 +1,217 @@
+# Google Ads Audit Checklist
+
+<!-- Updated: 2026-05-14 | v1.6: corrected AI Max DSA timeline, conversion lift, VAC migration dates -->
+<!-- Sources: Google Research PDF 1 (G01-G61), Claude Research (74-item extended), Gemini Research, 2026 Verification Pass (Search Engine Land, Google Ads Blog) -->
+<!-- Total Checks: 80 | Categories: 7 | See scoring-system.md for weights and algorithm -->
+
+## Quick Reference
+
+| Category | Weight | Check Count |
+|----------|--------|-------------|
+| Conversion Tracking | 25% | G42-G49 (8) + G-CT1 through G-CT3 (3) + G-CTV1 (1) = 12 |
+| Wasted Spend / Negatives | 20% | G13-G19 (7) + G-WS1 (1) = 8 |
+| Account Structure | 15% | G01-G12 (12) |
+| Keywords & Quality Score | 15% | G20-G25 (6) + G-KW1, G-KW2 (2) = 8 |
+| Ads & Assets | 15% | G26-G35 (10) + G-AD1, G-AD2 (2) = 12 |
+| Settings & Targeting | 10% | G50-G61 (12) |
+| Performance Max | N/A | G-PM1 through G-PM6 (6, scored within Ads & Assets) |
+| AI & Demand Gen | N/A | G-AI1 (1) + G-DG1 through G-DG3 (3, scored within Ads & Assets) |
+
+---
+
+## Conversion Tracking (25% weight)
+
+| ID | Check | Severity | Pass | Warning | Fail |
+|----|-------|----------|------|---------|------|
+| G42 | Conversion actions defined | Critical | ≥1 primary conversion action configured | N/A | No active conversion actions |
+| G43 | Enhanced conversions enabled | Critical | Enhanced conversions active AND verified for primary conversions (~10% uplift, free setup) **[Quick Win: 5 min]** | Enabled but not verified (check verification status in settings) | Not enabled |
+| G44 | Server-side tracking | High | Server-side GTM or Google Ads API conversion import active | Planned but not deployed | No server-side tracking |
+| G45 | Consent Mode v2 | Critical | Advanced Consent Mode v2 implemented (enforcement began July 21, 2025 for EEA/UK; recommended globally for signal recovery). Requires 700+ ad clicks/day over 7 days per country/domain for behavioral modeling to activate. Recovers 15-25% of lost conversions | Basic mode only (huge data loss. Upgrade to Advanced immediately) | Not implemented |
+| G46 | Conversion window appropriate | Medium | Window matches sales cycle (7d ecom, 30-90d B2B, 30d lead gen) | Default 30d without validation | Window mismatched to sales cycle |
+| G47 | Micro vs macro separation | High | Only macro conversions (Purchase, Lead) set as "Primary" for bidding | Some micro events as Primary | All events including micro (AddToCart, TimeOnSite) as Primary |
+| G48 | Attribution model | Medium | Data-driven attribution (DDA) selected | Last Click (intentional, document reasoning) | Rule-based model active (first click, linear, time decay, position-based were ALL auto-upgraded to DDA. Any remaining rule-based is a legacy misconfiguration) |
+
+**G48/CT-FL5 accuracy notes:** Exclude Smart Campaign system-managed conversions (e.g., 'Smart campaign map clicks to call') from DDA and counting-type checks. Their attribution model and counting type are locked by Google; advertisers cannot change them. Only evaluate advertiser-controlled conversion actions.
+| G49 | Conversion value assignment | High | Dynamic values for ecom; value rules for lead gen | Static values assigned | No conversion values |
+| G-CT1 | No duplicate counting | Critical | GA4 + Google Ads not double-counting same conversion | N/A | Both GA4 import and native tag counting same action |
+
+**G-CT1 accuracy notes:** Only check ENABLED conversion actions for duplicates. Exclude HIDDEN and REMOVED conversion actions; these are already disabled and cannot cause double-counting. When reporting duplicates, include the conversion action ID, type, origin, category, status, primary/secondary flag, counting type, and attribution model for easy resolution.
+| G-CT2 | GA4 linked and flowing | High | GA4 property linked, data flowing correctly | Linked but data discrepancies | Not linked |
+| G-CT3 | Google Tag firing | Critical | gtag.js or GTM firing correctly on all pages | Firing on most pages (>90%) | Tag missing or broken on key pages |
+
+---
+
+## Wasted Spend / Negatives (20% weight)
+
+| ID | Check | Severity | Pass | Warning | Fail |
+|----|-------|----------|------|---------|------|
+| G13 | Search term audit recency | Critical | Search terms reviewed within last 14 days | Reviewed within 30 days | Not reviewed in >30 days |
+| G14 | Negative keyword lists exist | Critical | ≥3 theme-based lists (Competitor, Jobs, Free, Irrelevant) | 1-2 lists exist | No negative keyword lists |
+| G15 | Account-level negatives applied | High | Negative lists applied at account or all-campaign level | Applied to some campaigns only | Not applied |
+
+**G14/G15 accuracy notes:** Count both campaign-level negatives AND Shared Negative Keyword Lists when evaluating coverage. Campaigns covered by shared lists should NOT be flagged as "missing negatives." Report per-campaign breakdown showing direct negatives vs. shared list assignments for clear remediation paths.
+| G16 | Wasted spend on irrelevant terms | Critical | <5% of spend on irrelevant search terms (last 30d) | 5-15% on irrelevant terms | >15% on irrelevant terms |
+
+**G16/G-WS1 accuracy notes:** Only flag search terms as "wasted" if they have >$10 spend AND 0 conversions. Long-tail terms with minimal spend (<$10) are normal exploration, not waste. When reporting, show top 10 wasters with spend and click details.
+| G17 | Broad match + smart bidding pairing | Critical | No Broad Match keywords running on Manual CPC. Note: Google reports exact-to-broad upgrades in tCPA campaigns see 35% more conversions on average, but ONLY with solid conversion data, Smart Bidding, and aggressive negative keyword management | N/A | Broad Match + Manual CPC active (wastes budget without algorithmic bid control) |
+
+**G17/FL04 legacy BMM heuristic:** Google stripped '+' prefixes from Broad Match Modified keywords during the 2021 migration but kept `matchType=BROAD` in the API. BROAD + Manual CPC almost always indicates legacy BMM (behaves as phrase match), NOT intentional broad match. True intentional broad match is always paired with Smart Bidding (tCPA, tROAS, Maximize Conversions/Value). Only flag BROAD keywords in Smart Bidding campaigns as needing review. Skip BROAD + Manual CPC; these are legacy BMM and should not be flagged as failures.
+| G18 | Close variant pollution | High | Exact/Phrase match not triggering irrelevant close variants | Minor close variant issues | Significant irrelevant close variant spend |
+| G19 | Search term visibility | Medium | >60% of search term spend is visible (not hidden) | 40-60% visible | <40% visible |
+
+**G19 accuracy notes:** When computing `totalVisibleSpend`, use ALL fetched search terms before any truncation or top-N limiting. A common error is summing cost from a truncated subset (e.g., top 500 of 2000 terms) which understates visibility. Fetch terms ordered by cost descending to ensure the highest-spend terms are captured first.
+| G-WS1 | Zero-conversion keywords | High | No keywords with >100 clicks and 0 conversions | 1-3 such keywords | >3 keywords with >100 clicks, 0 conversions |
+
+---
+
+## Account Structure (15% weight)
+
+| ID | Check | Severity | Pass | Warning | Fail |
+|----|-------|----------|------|---------|------|
+| G01 | Campaign naming convention | Medium | Consistent pattern (e.g., [Brand]_[Type]_[Geo]_[Target]) | Partially consistent | No naming convention |
+| G02 | Ad group naming convention | Medium | Matches campaign naming pattern | Partially consistent | No naming convention |
+| G03 | Single theme ad groups | High | Each ad group targets 1 keyword theme (≤10 keywords) | 11-20 keywords with consistent theme | Ad groups with 20+ unrelated keywords (theme drift) |
+
+**G03 accuracy notes:** When evaluating theme coherence: (1) Only count keywords with impressions > 0; dormant zero-impression keywords don't affect ad serving and shouldn't inflate counts. (2) Exclude paused ad groups: `ENABLED` ad groups only (paused groups can have enabled keywords at criterion level but aren't visible in UI). (3) Deduplicate keywords by text per ad group; the same keyword with BROAD + PHRASE match types is one keyword, not two. (4) Exclude stopword-only keywords (e.g., 'attorney', 'lawyers') from coherence scoring; they carry no thematic signal and dilute coherence scores.
+| G04 | Campaign count per objective | High | ≤5 campaigns per funnel stage/objective | 6-8 campaigns per objective | >8 campaigns per objective (fragmented) |
+
+**G04 accuracy notes:** For multi-location businesses, strip geographic identifiers (city names, state abbreviations, zip codes, metro areas, directional qualifiers like "North"/"South") from campaign names before counting unique objectives. A firm running "Divorce - Chicago", "Divorce - Schaumburg", "Divorce - Naperville" has 1 objective across 3 geos, not 3 separate objectives. Preserve PPC-meaningful terms (brand, nonbrand, pmax, remarketing, etc.).
+| G05 | Brand vs Non-Brand separation | Critical | Brand and non-brand in separate campaigns | N/A | Brand and non-brand mixed in same campaign |
+
+**G05/G07/G-PM3 brand detection:** Don't rely solely on campaign naming conventions. Derive brand tokens from the account/business name and scan actual keyword text for brand terms. Classify campaigns by keyword composition: >50% brand keywords = brand campaign. This catches mislabeled campaigns and provides accurate brand vs. non-brand separation.
+| G06 | PMax present for eligible accounts | Medium | PMax active for accounts with conversion history. Note: brand exclusions and campaign-level negative keywords are now available for ALL PMax advertisers (2025). Customer match lists are the strongest audience signal | PMax tested but paused | No PMax tested despite eligibility |
+| G07 | Search + PMax overlap | High | Brand exclusions configured in PMax when Search brand campaign exists | Partial brand exclusions | No brand exclusions in PMax alongside brand Search |
+| G08 | Budget allocation matches priority | High | Top-performing campaigns not budget-limited | Minor budget constraints on top performers | Top performers severely budget-limited |
+| G09 | Campaign daily budget vs spend | Medium | No campaigns hitting budget cap before 6PM | 1-2 campaigns hitting cap early | Multiple campaigns capped before noon |
+| G10 | Ad schedule configured | Low | Ad schedule set if business has operating hours | N/A | No schedule despite clear business hours |
+| G11 | Geographic targeting accuracy | High | "People in" (not "People in or interested in") for local | N/A | "People in or interested in" for local business |
+| G12 | Network settings | High | Search Partners enabled for additional reach; Display Network disabled for Search (unless intentional) | Search Partners OFF (missing incremental reach) | Display Network ON for Search campaign |
+
+**G12 note:** Search Partners typically provides incremental reach at comparable CPA. Flag Search Partners OFF as a missed opportunity (Warning), not ON. Display Network on Search campaigns remains a Fail.
+
+---
+
+## Keywords & Quality Score (15% weight)
+
+| ID | Check | Severity | Pass | Warning | Fail |
+|----|-------|----------|------|---------|------|
+| G20 | Average Quality Score | High | Account-wide impression-weighted QS ≥7 | QS 5-6 | QS ≤4 |
+| G21 | Critical QS keywords | Critical | <10% of keywords with QS ≤3 | 10-25% with QS ≤3 | >25% with QS ≤4 |
+| G22 | Expected CTR component | High | <20% of keywords with "Below Average" expected CTR | 20-35% Below Average | >35% Below Average |
+| G23 | Ad relevance component | High | <20% of keywords with "Below Average" ad relevance | 20-35% Below Average | >35% Below Average |
+| G24 | Landing page experience | High | <15% of keywords with "Below Average" landing page exp. | 15-30% Below Average | >30% Below Average |
+| G25 | Top keyword QS | Medium | Top 20 spend keywords all have QS ≥7 | Some top keywords at QS 5-6 | Top keywords with QS ≤4 |
+| G-KW1 | Zero-impression keywords | Medium | No keywords with 0 impressions in last 30 days | <10% zero-impression | >10% of keywords with 0 impressions |
+| G-KW2 | Keyword-to-ad relevance | High | Headlines contain primary keyword variants | Partial keyword inclusion | No keyword variants in ad headlines |
+
+---
+
+## Ads & Assets (15% weight)
+
+| ID | Check | Severity | Pass | Warning | Fail |
+|----|-------|----------|------|---------|------|
+| G26 | RSA per ad group | High | ≥1 RSA per ad group (≥2 recommended) | 1 RSA per ad group | Ad groups without any RSA |
+| G27 | RSA headline count | High | ≥8 unique headlines per RSA (ideal: 12-15) | 3-7 headlines | <3 headlines |
+| G28 | RSA description count | Medium | ≥3 descriptions per RSA (ideal: 4) | 2 descriptions | <2 descriptions |
+| G29 | RSA Ad Strength | High | All RSAs "Good" or "Excellent" | Some "Average" | Any RSA with "Poor" Ad Strength |
+| G30 | RSA pinning strategy | Medium | Strategic pinning (1-2 positions, 2-3 variants each) | Over-pinned (all positions) | N/A |
+| G31 | PMax asset group density | Critical | ≥20 images, ≥5 logos, ≥5 native videos per group (maximum density). PMax needs 30-50+ conversions/month minimum to optimize effectively. Flag auto-generated video from images as WARNING (typically poor quality. Upload native video) | 5-19 images, 1-4 logos, or 1-4 videos; OR <30 conv/month (insufficient data for PMax) | <5 images OR 0 logos OR 0 video |
+| G32 | PMax video assets present | High | Native video in all formats (16:9, 1:1, 9:16) | 1-2 formats only | No native video (auto-generated only) |
+| G33 | PMax asset group count | Medium | ≥2 asset groups per PMax (intent-segmented) | 1 asset group | N/A |
+| G34 | PMax final URL expansion | High | Configured intentionally (ON for discovery, OFF for control) | N/A | Default ON without review |
+| G35 | Ad copy relevance to keywords | High | Headlines contain primary keyword variants | Partial keyword inclusion | No keyword relevance in headlines |
+| G-AD1 | Ad freshness | Medium | New ad copy tested within last 90 days | N/A | No new ads in >90 days |
+| G-AD2 | CTR vs industry benchmark | High | CTR ≥ industry average | CTR 50-100% of industry average | CTR <50% of industry average |
+
+---
+
+## Settings & Targeting (10% weight)
+
+| ID | Check | Severity | Pass | Warning | Fail |
+|----|-------|----------|------|---------|------|
+| G50 | Sitelink extensions | High | ≥4 sitelinks per campaign | 1-3 sitelinks | No sitelinks |
+| G51 | Callout extensions | Medium | ≥4 callouts per campaign | 1-3 callouts | No callouts |
+| G52 | Structured snippets | Medium | ≥1 structured snippet set | N/A | No structured snippets |
+| G53 | Image extensions | Medium | Image extensions active for search campaigns | N/A | No image extensions |
+| G54 | Call extensions (if applicable) | Medium | Call extensions with call tracking for phone-based businesses | Call extension without tracking | No call extension for phone-based business |
+| G55 | Lead form extensions | Low | Lead form tested for lead gen accounts | N/A | Not tested |
+| G56 | Audience segments applied | High | Remarketing + in-market audiences in Observation mode | Some audiences applied | No audience signals |
+| G57 | Customer Match lists | High | Customer Match list uploaded, refreshed <30 days | List >30 days old | No Customer Match lists |
+| G58 | Placement exclusions | High | Account-level placement exclusions (games, apps, MFA sites) | Campaign-level only | No placement exclusions |
+| G59 | Landing page mobile speed | High | Mobile LCP <2.5s (ideal <2.0s) | LCP 2.5-4.0s | LCP >4.0s |
+| G60 | Landing page relevance | High | Landing page H1/title matches ad group theme | Partial relevance | No relevance to ad group |
+| G61 | Landing page schema markup | Medium | Product/FAQ/Service schema present | N/A | No schema markup |
+
+---
+
+## Performance Max Extended (scored within Ads & Assets)
+
+| ID | Check | Severity | Pass | Warning | Fail |
+|----|-------|----------|------|---------|------|
+| G-PM1 | Audience signals configured | High | Custom audience signals per asset group | Generic signals only | No audience signals |
+| G-PM2 | PMax Ad Strength | High | "Good" or "Excellent" | "Average" | "Poor" |
+| G-PM3 | Brand cannibalization | High | <15% of PMax conversions from brand terms | 15-30% from brand terms | >30% from brand terms |
+| G-PM4 | Search themes | Medium | Search themes configured (up to 50 per asset group) | <5 search themes | No search themes |
+| G-PM5 | Negative keywords | High | Brand + irrelevant negatives applied (up to 10,000) | Some negatives applied | No negative keywords in PMax |
+| G-PM6 | PMax negative keywords active | High | Campaign-level negative keywords configured (now available for ALL PMax advertisers). One client reported 15% immediate cost reduction after adding negatives **[Quick Win: 10 min]** | Account-level negatives only, no campaign-level | No negative keywords in PMax despite availability |
+
+---
+
+## AI Max & Demand Gen (v1.5, scored within Ads & Assets)
+
+| ID | Check | Severity | Pass | Warning | Fail |
+|----|-------|----------|------|---------|------|
+| G-AI1 | AI Max for Search evaluation | High | AI Max evaluated or active for accounts with sufficient conversion data. Google reports an average of 7% more conversions/conversion value at comparable CPA/ROAS when full feature suite is enabled (search term matching, text customization, final URL expansion). Strong negative keyword lists in place before enabling | N/A | AI Max not evaluated despite eligible account (>50 conv/month, established negative lists) |
+| G-DG1 | Demand Gen image assets | High | Demand Gen campaigns include BOTH video AND image assets (20% more conversions at same CPA vs video-only). DoorDash case study: 15x higher CVR, 50% lower CPA | Video assets only (missing image uplift) | No Demand Gen campaigns despite eligible account |
+| G-DG2 | VAC migration status | Critical | All Video Action Campaigns migrated to Demand Gen. Timeline: VAC creation blocked April 2025 → auto-upgrades began July 2025 → most VACs upgraded September 2025 → final force-upgrade for remaining campaigns April 2026 (errored ones deleted, replacement DG campaign created paused) | Migration in progress | VAC campaigns still active (deprecated; force-migrated by April 2026) |
+| G-DG3 | Demand Gen frequency capping loss | High | Former VAC campaigns with frequency caps: alternative measurement strategy in place (Video Frequency Groups alpha, or manual frequency monitoring) | Frequency not monitored post-migration | Former VAC campaigns relied on frequency caps now lost in DG with no replacement strategy |
+
+## CTV & Video Tracking (v1.5, scored within Conversion Tracking)
+
+| ID | Check | Severity | Pass | Warning | Fail |
+|----|-------|----------|------|---------|------|
+| G-CTV1 | CTV Floodlight tracking limitation | High | CTV campaigns use non-Floodlight measurement (Google Ads conversion tracking, GA4). Note: Floodlight conversion measurement DOES NOT work on CTV devices | CTV campaigns active but measurement not verified | CTV campaigns relying on Floodlight for conversion measurement (will not capture CTV conversions) |
+
+---
+
+## Context Notes
+
+- **ECPC deprecation (March 2025)**: Fully deprecated. Flag any remaining ECPC campaigns as FAIL with immediate migration to tCPA, tROAS, or Maximize Conversions.
+- **Call Campaigns sunset (Feb 2026)**: Google stopped allowing creation of new Call campaigns in February 2026; existing Call campaigns continue serving until February 2027. Migrate to Search campaigns with call assets before the serving deadline.
+- **Power Pack framework**: Google recommends running PMax + Demand Gen + AI Max for Search as a unified campaign stack for maximum coverage across all inventory.
+- **AI Max for Search (2025+)**: Layers broad match tech and keywordless targeting onto existing Search campaigns. Google reports 7% more conversions/conversion value at comparable CPA/ROAS with full feature suite enabled (vs search term matching alone). DSA officially being consolidated into AI Max: automatic upgrades begin September 2026; creation of new DSA campaigns via Google Ads, Google Ads Editor, and the Google Ads API ends September 2026. Requires strong negative keyword lists before adoption.
+- **Video Action Campaigns → Demand Gen**: VAC creation blocked April 2025; auto-upgrades began July 2025; most VACs upgraded September 2025; final force-upgrade for remaining campaigns April 2026. Display & Video 360 video action line items paused/archived February 28, 2026. Flag any remaining VAC campaigns as deprecated.
+- **Demand Gen limitations**: Frequency capping is NOT supported in Demand Gen (significant loss from VAC). Only workaround: Video Frequency Groups (alpha). Multi-format (video + image) delivers 20% more conversions at same CPA vs video-only.
+- **Smart Bidding Exploration (2025)**: Allows flexible ROAS targets to discover new traffic. Delivers 18% more unique search query categories + 19% more conversions.
+- **Meridian (2025)**: Google's open-source Marketing Mix Model for incrementality measurement. Useful for advanced accounts evaluating cross-channel contribution.
+- **Ads in AI Overviews**: Now showing globally. Requires high ad relevance to appear.
+
+---
+
+## Bidding & Budget (scored within Settings & Targeting)
+
+| ID | Check | Severity | Pass | Warning | Fail |
+|----|-------|----------|------|---------|------|
+| G36 | Smart bidding strategy active | High | All campaigns with ≥15 conv/30d use automated bidding. ECPC fully deprecated March 2025. Flag any ECPC campaigns for immediate migration to tCPA/tROAS/Max Conversions. Consider Smart Bidding Exploration: allows flexible ROAS targets to discover new traffic, delivering 18% more unique search query categories with conversions and 19% more total conversions | Partially automated, or ECPC campaigns still present (migrate immediately) | Manual CPC on campaigns with sufficient data |
+| G37 | Target CPA/ROAS reasonableness | Critical | Targets within 20% of historical performance | Targets 20-50% off historical | Target CPA <50% of actual CPA |
+| G38 | Learning phase status | High | <25% of campaigns in "Learning" or "Learning Limited" | 25-40% in learning | >40% in learning |
+| G39 | Budget constrained campaigns | High | Top performers show "Eligible" not "Limited by Budget" | Minor budget limitation | Top performers severely budget-limited |
+| G40 | Manual CPC justification | Medium | Manual CPC only on campaigns with <15 conv/month | Manual CPC with 15-30 conv/month | Manual CPC with >30 conv/month |
+| G41 | Portfolio bid strategies | Medium | Low-volume campaigns grouped into portfolios | N/A | Multiple <15 conv campaigns running independently |
+
+---
+
+## Quick Wins (Google)
+
+Items flagged as Quick Win when severity is Critical or High AND fix takes <15 minutes:
+
+| Check | Fix | Time |
+|-------|-----|------|
+| G43: Enhanced conversions | Enable in Google Ads conversion settings | 5 min |
+| G11: Location targeting | Switch to "People in" your targeted locations | 2 min |
+| G14: Negative keyword lists | Create initial themed negative lists | 10 min |
+| G17: Broad match + Manual CPC | Switch to Smart Bidding or Exact Match | 5 min |
+| G12: Network settings | Disable Display Network on Search campaigns | 2 min |
+| G05: Brand separation | Split brand keywords into separate campaign | 10 min |
+| G50: Sitelink extensions | Add 4+ sitelinks to campaigns | 10 min |
+| G-PM6: PMax negative keywords | Add campaign-level negatives to PMax | 10 min |

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

@@ -0,0 +1,119 @@
+# Google Creative Specs: Generation Guide
+
+<!-- Updated: 2026-05-14 | v1.6 -->
+<!-- Source: platform-specs.md + Google Ads asset requirements + 2026 Verification Pass -->
+<!-- Used by: ads-generate, visual-designer agent -->
+
+## Purpose
+
+Generation-ready specifications for Google Ads creative assets. Use these when
+constructing image prompts for PMax asset groups, RSA companion images, Demand Gen,
+and YouTube thumbnails.
+
+---
+
+## Performance Max Asset Group
+
+### Image Assets (required for full coverage)
+
+| Asset Type | Dimensions | Ratio | Priority |
+|-----------|-----------|-------|----------|
+| Marketing image (landscape) | 1200×628 | 1.91:1 | **Required** |
+| Square image | 1200×1200 | 1:1 | **Required** |
+| Portrait image | 960×1200 | 4:5 | High |
+| Logo (landscape) | 1200×300 | 4:1 | Required |
+| Logo (square) | 1200×1200 | 1:1 | Required |
+
+**Max per asset group:** 20 images total across marketing + square + portrait.
+**File requirements:** JPG or PNG, max 5MB, min 128×128.
+
+### Generation targets per campaign
+
+Minimum viable set (3 images):
+1. `1200×628` landscape: primary ad creative
+2. `1200×1200` square: feed placements
+3. `960×1200` portrait: mobile-optimized
+
+Full coverage set (5 images): add `1080×1920` vertical for YouTube Shorts placements.
+
+---
+
+## Demand Gen (formerly Discovery)
+
+| Placement | Ratio | Recommended Size |
+|-----------|-------|-----------------|
+| Google Discover | 1:1 | 1080×1080 |
+| Google Discover | 4:5 | 1080×1350 |
+| Gmail Promotions | 1.91:1 | 1200×628 |
+| YouTube In-Feed | 1:1 | 1080×1080 |
+
+Generate both 1:1 and 4:5 variants for maximum placement coverage.
+
+---
+
+## YouTube Thumbnails
+
+| Type | Dimensions | Notes |
+|------|-----------|-------|
+| Standard thumbnail | 1280×720 (16:9) | Used for in-feed, search results |
+| Square thumbnail | 1080×1080 (1:1) | Shorts feed |
+
+**Thumbnail generation guidelines:**
+- High contrast between subject and background
+- Face or product in center-left position (text overlays go right)
+- Avoid busy backgrounds; viewer scans at thumbnail size
+- Bright, saturated colors outperform muted palettes for CTR
+- Include product or person; abstract imagery underperforms
+
+---
+
+## RSA Copy Limits (for copy-writer agent)
+
+| Component | Min | Max | Character Limit |
+|-----------|-----|-----|-----------------|
+| Headlines | 3 | 15 | 30 chars each |
+| Descriptions | 2 | 4 | 90 chars each |
+| Display paths | N/A | 2 | 15 chars each |
+
+Best practice: 8+ headlines, 2+ descriptions.
+
+---
+
+## Image Generation Prompt Modifiers
+
+Apply these modifiers to every Google ad image prompt:
+
+**Always include:**
+- `"horizontal composition"` (for 1.91:1 and 16:9 assets)
+- `"clean background"` (PMax images compete for attention in content feeds)
+- `"product or subject centered with breathing room"`
+- `"no text overlay"` (text is applied by the ad platform, not baked into the image)
+- `"high contrast, vibrant colors"`
+
+**Avoid in prompts:**
+- Extreme close-ups (PMax crops images across many placements)
+- Complex scene layouts (will crop poorly to 1:1 and 4:5)
+- Text or logos embedded in the image (violates Google policy for some ad types)
+
+---
+
+## AI Max for Search (2026)
+
+AI Max is Google's broad match + AI-generated creative system. When active:
+- Headlines may be auto-generated from landing page content
+- URL expansion sends traffic to best-fit page (not just Final URL)
+- Image generation for PMax applies AI selection from asset pool
+
+**Implication for generation:** Provide diverse asset pool (3+ aspect ratios,
+3+ visual angles) to give AI Max more to work with.
+
+---
+
+## Aspect Ratio Priority
+
+When generating a single image for Google (time-constrained):
+1. `1200×628` (1.91:1): covers most placements
+2. `1200×1200` (1:1): adds feed placements
+3. `960×1200` (4:5): adds mobile portrait placements
+
+Always generate 1 and 2 at minimum.

package/stacks/_shared/ads-agents/references/image-providers.md

@@ -0,0 +1,133 @@
+# Image Generation Providers
+
+<!-- Updated: 2026-05-14 | v1.6: corrected FLUX.1 Pro / Replicate pricing -->
+<!-- Used by: ads-generate, ads-photoshoot, visual-designer agent -->
+
+## Default Provider: banana-claude
+
+banana-claude (v1.4.1) is the default image generation provider. It acts as a Creative Director
+layer on top of Google Gemini, providing 5-component prompt engineering, 9 domain modes,
+brand presets, cost tracking, and post-processing.
+
+### Prerequisites
+- banana-claude installed (`/banana setup` to verify)
+- nanobanana-mcp configured with GOOGLE_AI_API_KEY
+- No additional pip packages needed (banana uses stdlib only)
+
+### MCP Tools (Primary Method)
+
+| Tool | Purpose | Key Parameters |
+|------|---------|----------------|
+| `set_aspect_ratio` | Configure ratio for next generation | ratio: "16:9", "1:1", "9:16", etc. |
+| `set_model` | Switch Gemini model | model: "gemini-3.1-flash-image-preview" (default) |
+| `gemini_generate_image` | Text-to-image generation | prompt: (string) |
+| `gemini_edit_image` | Modify existing image | imagePath, prompt |
+| `get_image_history` | Review session generations | (none) |
+
+### Domain Modes for Ad Creative
+
+| Mode | Use For | Ad Type |
+|------|---------|---------|
+| Product | E-commerce packshots, product ads | Shopping, PMax, Meta catalog |
+| Editorial | Brand awareness, lifestyle campaigns | Meta Feed, YouTube, LinkedIn |
+| Cinema | Dramatic storytelling, video thumbnails | YouTube, TikTok, Demand Gen |
+| Portrait | People-centric ads, testimonials | Meta, LinkedIn, Google Display |
+| UI/Web | App install ads, SaaS screenshots | Google UAC, Meta app install |
+| Logo | Brand identity, favicon generation | All platforms (identity assets) |
+| Landscape | Environment, travel, real estate | Google Display, YouTube |
+| Infographic | Data-driven ads, comparison charts | LinkedIn, Google Display |
+| Abstract | Background textures, patterns | All (supporting assets) |
+
+### 5-Component Prompt Formula
+
+Banana constructs optimized prompts using:
+1. [SUBJECT]: Physical details, appearance, material
+2. [ACTION]: What it's doing, pose, state
+3. [LOCATION/CONTEXT]: Where, when, atmosphere
+4. [COMPOSITION]: Camera angle, framing, perspective
+5. [STYLE]: Camera/lens specs, lighting, brand voice mapped attributes
+
+Visual-designer agent builds these components from campaign brief + brand profile.
+
+### Pricing (Gemini via banana)
+
+| Resolution | Cost/Image | Use Case |
+|------------|-----------|----------|
+| 512px | $0.020 | Quick drafts, concepts |
+| 1K | $0.039 | Standard web assets |
+| 2K (recommended) | $0.078 | Quality ad creatives |
+| 4K | $0.156 | Print, hero images |
+| Batch API | 50% off | Bulk campaign generation |
+
+### Aspect Ratios (14 supported)
+
+| Ratio | Dimensions | Platform Use |
+|-------|-----------|-------------|
+| 1:1 | 1080x1080 | Meta Feed, LinkedIn, Carousel |
+| 4:5 | 1080x1350 | Meta Feed (preferred), Instagram |
+| 9:16 | 1080x1920 | TikTok, Reels, Shorts, Stories |
+| 16:9 | 1920x1080 | YouTube, Google Display, LinkedIn |
+| 3:2 | 1200x800 | DSLR standard, photo prints |
+| 2:3 | 800x1200 | Pinterest, posters |
+| 21:9 | Cinematic | Ultra-wide banners |
+| 4:1 | 1200x300 | Website banners |
+| 1:4 | Vertical banner | Mobile banners |
+
+Note: Gemini does not natively support 1.91:1. Use 16:9 and crop to 1200x628 for Google PMax/LinkedIn.
+
+### Brand Presets
+
+banana supports brand presets stored at `.banana/presets/NAME.json`.
+The ads-generate skill auto-creates a preset from brand-profile.json before generation.
+
+Preset schema:
+- colors: array of hex values from brand DNA
+- style: visual style description from brand aesthetic
+- mood: mood keywords from brand voice
+- default_ratio: "16:9" (or platform-specific)
+- default_resolution: "2K"
+
+### Cost Tracking
+
+banana logs all generations to `.banana/costs.json`.
+ads-generate reads this after generation and includes cost summary in generation-manifest.json.
+
+---
+
+## Fallback Providers
+
+If banana is not installed, these providers can be used directly via generate_image.py (deprecated).
+
+### OpenAI (gpt-image-1)
+- Env: `OPENAI_API_KEY`
+- Price: ~$0.040/image (1024x1024), ~$0.060 (1024x1536)
+- Package: `openai>=1.75.0`
+
+### Stability AI (stable-diffusion-3.5-large)
+- Env: `STABILITY_API_KEY`
+- Price: ~$0.065/image flat
+- Package: `stability-sdk>=0.8.4`
+
+### Replicate (FLUX.1.1 Pro)
+- Env: `REPLICATE_API_TOKEN`
+- Price: $0.04/output image (black-forest-labs/flux-1.1-pro, billed per image)
+- Package: `replicate>=1.0.4`
+
+---
+
+## Error Reference
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| banana MCP not found | nanobanana-mcp not configured | Run `/banana setup` |
+| IMAGE_SAFETY | Safety filter triggered | Rephrase; use abstraction or artistic framing |
+| 429 Too Many Requests | Rate limit | banana auto-retries with exponential backoff |
+| FAILED_PRECONDITION | Billing not enabled | Enable billing in Google AI Studio |
+
+### Rate Limits (Gemini via banana)
+
+| Tier | RPM | Daily Images |
+|------|-----|-------------|
+| Free | 5-15 | 20-500 |
+| Tier 1 (<$250 spend) | 150 | 1,500 |
+| Tier 2 (>$250 spend) | 1,000+ | Unlimited |

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

@@ -0,0 +1,141 @@
+# LinkedIn Ads Audit Checklist
+
+<!-- Updated: 2026-05-14 | v1.6 -->
+<!-- Sources: Google Research PDF 1 (L01-L25), Claude Research, Gemini Research, 2026 Verification Pass -->
+<!-- Total Checks: 27 | Categories: 6 | See scoring-system.md for weights and algorithm -->
+
+> **Note:** LinkedIn renamed Campaign Groups to Campaigns and Campaigns to Ad Sets in September 2025 (announced by LinkedIn / Social Media Today).
+
+## Quick Reference
+
+| Category | Weight | Check Count |
+|----------|--------|-------------|
+| Technical Setup | 25% | L01-L02 (2 checks) |
+| Audience Quality | 25% | L03-L09 (7 checks) |
+| Creative & Formats | 20% | L10-L13 (4 checks) |
+| Lead Gen Forms | 15% | L14-L15 (2 checks) |
+| Bidding & Budget | 15% | L16-L17 (2 checks) |
+| Structure & Performance | N/A | L18-L25 (8 checks, scored across categories) |
+| CRM & Compliance | 10% | L-CRM1, L-EU1 (2 checks) |
+
+---
+
+## Technical Setup (25% weight)
+
+| ID | Check | Severity | Pass | Warning | Fail |
+|----|-------|----------|------|---------|------|
+| L01 | Insight Tag installed | Critical | LinkedIn Insight Tag firing on all pages | Firing on most pages (>90%) | Tag not installed or broken |
+| L02 | Conversions API (CAPI) | High | Server-side conversion tracking active (launched 2025) | Planned but not deployed | No server-side tracking |
+
+---
+
+## Audience Quality (25% weight)
+
+| ID | Check | Severity | Pass | Warning | Fail |
+|----|-------|----------|------|---------|------|
+| L03 | Job title targeting precision | High | Specific job titles matching ICP (not just functions) | Broad function targeting only | No job title targeting |
+| L04 | Company size filtering | Medium | Company size matches ICP | Includes all sizes | N/A |
+| L05 | Seniority level targeting | High | Seniority appropriate for offer (C-suite for enterprise, Manager for mid-market) | Broad seniority targeting | Mismatched seniority level |
+| L06 | Matched Audiences | High | Website retargeting + contact list audiences active | One type active | No matched audiences |
+| L07 | ABM company lists | Medium | Target company lists uploaded (up to 300,000) for ABM | Partial list uploaded | No ABM lists for enterprise campaigns |
+| L08 | Audience expansion setting | Medium | OFF for precise targeting, ON for scale (intentional). **CRITICAL: Always uncheck Audience Expansion for ABM campaigns.** ABM budget distribution can be wildly uneven. One case showed 96% of budget going to just 3 accounts out of 400 targeted (AJ Wilcox, B2Linked) | N/A | Default ON without review |
+| L09 | Predictive audiences | Medium | Predictive audiences tested (replaced Lookalike Audiences 2024; 21% CPL reduction). Now accepts company lists and retargeting sources as inputs (March 2025) | N/A | Not tested for eligible campaigns |
+
+---
+
+## Creative & Formats (20% weight)
+
+| ID | Check | Severity | Pass | Warning | Fail |
+|----|-------|----------|------|---------|------|
+| L10 | Thought Leader Ads (TLAs) | High | TLAs active, receiving ≥30% of budget for B2B. TLAs expanded to non-employee members March 2025 (customer testimonial UGC possible). Engagement 2-5x higher than standard | TLAs tested but <30% budget | No TLAs (CPC $2.29-4.14 vs $13.23 standard) |
+| L11 | Ad format diversity | High | ≥2 formats tested (single image, video, document, carousel) | 1 format only | N/A |
+| L12 | Video ads present | Medium | Video ads tested | N/A | No video tested |
+| L13 | Creative refresh cadence | Medium | Creative refreshed every 4-6 weeks | Refreshed every 6-10 weeks | Same creative >10 weeks |
+
+---
+
+## Lead Gen Forms (15% weight)
+
+| ID | Check | Severity | Pass | Warning | Fail |
+|----|-------|----------|------|---------|------|
+| L14 | Lead Gen Form optimization | High | ≤5 fields (reduce friction); 13% CVR benchmark | 6-8 fields | >8 fields (high friction) |
+| L15 | Lead Gen Form CRM integration | High | Form synced to CRM in real-time | Synced within 24hrs | Manual CSV download only |
+
+---
+
+## Bidding & Budget (15% weight)
+
+| ID | Check | Severity | Pass | Warning | Fail |
+|----|-------|----------|------|---------|------|
+| L16 | Bid strategy appropriate | High | Manual CPC or Cost Cap for cost control; start manual, then test automated bidding with established data | N/A | Maximum Delivery left as default without cost analysis (most expensive option) |
+| L17 | Budget sufficiency | High | Daily budget ≥$50 for Sponsored Content | $25-$50/day | <$25/day ($10 minimum, insufficient for learning) |
+
+---
+
+## Structure & Performance (scored across categories)
+
+| ID | Check | Severity | Pass | Warning | Fail |
+|----|-------|----------|------|---------|------|
+| L18 | Ad Set objective alignment | High | Objective matches funnel stage | N/A | Objective mismatched to goal |
+| L19 | A/B testing active | Medium | Active A/B test on creative or audience | Test planned | No testing |
+| L20 | Frequency monitoring | High | Message frequency ≤1 per 30-45 days per user | 1 per 20-30 days | >1 per 20 days (inbox fatigue) |
+| L21 | CTR benchmark | High | Sponsored Content CTR ≥0.44% | CTR 0.30-0.44% | CTR <0.30% |
+| L22 | CPC benchmark | Medium | CPC within industry benchmark ($5-7 avg, senior $6.40+) | CPC 20-50% above benchmark | CPC >50% above benchmark |
+| L23 | Lead quality tracking | High | Lead-to-opportunity rate tracked (not just CPL) | CPL tracked only | No lead quality metrics |
+| L24 | Conversion tracking attribution | Medium | 30-day click / 7-day view window configured | Default window without review | Attribution not configured |
+| L25 | Demographics report review | Medium | Job title and company breakdown reviewed monthly | Reviewed quarterly | Never reviewed |
+
+---
+
+## CRM & Compliance (v1.5)
+
+| ID | Check | Severity | Pass | Warning | Fail |
+|----|-------|----------|------|---------|------|
+| L-CRM1 | CRM integration for revenue attribution | High | Salesforce or HubSpot CRM integration configured (launched June 2025) enabling closed-loop reporting from impression to revenue | CRM available but not integrated with LinkedIn | No CRM integration despite having Salesforce/HubSpot (missing revenue attribution loop) |
+| L-EU1 | EU Sponsored Messaging compliance | Medium | No Message Ads or Conversation Ads targeting EU audiences (EU Sponsored Messaging discontinued since January 2022) | N/A | Message/Conversation Ads targeting EU audiences (will not deliver; discontinued) |
+
+---
+
+## Quick Wins (LinkedIn)
+
+| Check | Fix | Time |
+|-------|-----|------|
+| L01: Insight Tag | Install/verify Insight Tag on all pages | 10 min |
+| L10: Thought Leader Ads | Create TLA using employee organic posts | 10 min |
+| L14: Lead Gen Form fields | Reduce form to ≤5 fields | 5 min |
+| L08: Audience expansion | Review and set intentionally (OFF for precision) | 2 min |
+| L20: Message frequency | Set frequency cap to 1 per 30-45 days | 2 min |
+| L24: Attribution window | Configure 30-day click / 7-day view | 2 min |
+
+---
+
+## Context Notes
+
+- **September 2025 naming**: Campaign Groups renamed to "Campaigns"; Campaigns renamed to "Ad Sets" (aligns LinkedIn with Meta/Google terminology — cosmetic change, no functional impact)
+- **CRM integration (June 2025)**: Salesforce/HubSpot closed-loop reporting from impression to revenue
+- **TLA expansion (March 2025)**: Non-employee members can now be featured in Thought Leader Ads
+- **Predictive Audiences (March 2025)**: Now accept company lists and retargeting sources
+- **LinkedIn Audience Network**: Expert consensus (AJ Wilcox, $200M+ spend): turn it OFF. Quality is poor. It's enabled by default
+- **Document Ads**: 7.00% engagement rate (14% YoY increase), leading all LinkedIn content formats
+- **Conversation Ads**: 50-60% open rates, 2-5% CTR (far exceeds feed benchmarks of 0.3-0.5%)
+- **Connected TV Ads (2025)**: LinkedIn extended reach to CTV inventory via partnerships, allowing B2B brand campaigns on streaming platforms.
+- **BrandLink (2025)**: Premium video placement alongside trusted publisher content on LinkedIn. Ideal for awareness-stage B2B campaigns.
+- **Live Event Ads (2025)**: Sponsored LinkedIn Live events with built-in registration and reminder flows. Effective for webinar-driven lead gen.
+- **Accelerate ad sets**: LinkedIn's AI-optimized ad set type delivers 42% lower CPA and 21% lower CPL on average. Recommended for advertisers with sufficient conversion history.
+
+---
+
+## LinkedIn-Specific Context
+
+| Fact | Value |
+|------|-------|
+| Minimum audience for delivery | 500 members |
+| Recommended audience size | 50,000-300,000 |
+| Predictive Audiences seed | 300+ members |
+| Company list upload limit | 300,000 |
+| Lookalike audiences | Discontinued Feb 29, 2024 |
+| Lead Gen Form CVR benchmark | 13% (3.25x landing pages) |
+| B2B ROAS benchmark | 113% ($1.13 per $1 spent) |
+| Accelerate ad sets | 42% lower CPA, 21% lower CPL |
+| TLA CPC advantage | $2.29-4.14 vs $13.23 standard |
+| Hierarchy naming (Sept 2025) | "Campaigns" (formerly Campaign Groups) → "Ad Sets" (formerly Campaigns) |