start-vibing-stacks 2.28.0 → 2.30.0

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

@@ -0,0 +1,129 @@
+# LinkedIn Creative Specs: Generation Guide
+
+<!-- Updated: 2026-03-12 -->
+<!-- Source: platform-specs.md + LinkedIn Campaign Manager requirements -->
+<!-- Used by: ads-generate, visual-designer agent -->
+
+## Purpose
+
+Generation-ready specifications for LinkedIn ad creative. LinkedIn is a professional
+platform; tone, imagery style, and composition constraints differ significantly from
+Meta and TikTok.
+
+---
+
+## Single Image Ad Specs
+
+| Ratio | Dimensions | Priority | Notes |
+|-------|-----------|----------|-------|
+| 1:1 (square) | 1080×1080 | **Primary target** | Better engagement than landscape |
+| 1.91:1 (landscape) | 1200×628 | Secondary | Legacy placements, desktop sidebar |
+
+**File requirements:** PNG or JPG, max 5MB.
+
+**Primary generation target: 1080×1080 (1:1)**
+Square performs better in the LinkedIn feed because it takes up more vertical space
+on mobile, increasing scroll-stop rate.
+
+---
+
+## Copy Limits
+
+| Component | Recommended | Max |
+|-----------|------------|-----|
+| Intro text | 150 chars | 600 chars |
+| Headline | 70 chars | 200 chars |
+| Description | 100 chars |: (desktop only) |
+| CTA button | Predefined list | N/A |
+
+**Copy generation rule:** Write intro text ≤150 chars (truncated on mobile beyond this).
+Headline ≤70 chars. The description only shows on desktop; treat as supplementary.
+
+---
+
+## Video Ad Specs
+
+| Component | Requirement |
+|-----------|------------|
+| Format | MP4 (required) |
+| File size | 75KB - 500MB |
+| Duration | 3s - 30min (rec 15-30s) |
+| Resolution | 360p min; 720p+ recommended |
+| Aspect ratios | 16:9 (landscape), 1:1 (square), 9:16 (mobile only) |
+
+For video thumbnail generation: use 1:1 (1080×1080) as the primary thumbnail size.
+
+---
+
+## Document Ad Specs
+
+- Formats: PDF, DOC, DOCX, PPT, PPTX
+- Max: 100MB, 300 pages (10-20 pages recommended)
+- Cover image: 1200×628 (1.91:1); generate this as the document cover visual
+
+---
+
+## Audience Network / Programmatic
+
+When LinkedIn Audience Network is enabled, ads run on partner sites.
+Supported sizes for network: 300×250, 728×90, 160×600, 300×600.
+These are not generation targets; LinkedIn resizes from your primary assets.
+
+---
+
+## B2B Tone Constraints
+
+LinkedIn is a professional context. Apply these constraints to every generation prompt:
+
+**Always include:**
+- `"professional photography"` or `"B2B professional context"`
+- `"clean, uncluttered background"`
+- `"business-appropriate attire if people present"`
+- `"high quality, corporate-grade visual"`
+
+**Avoid in prompts:**
+- `"casual"`, `"fun"`, `"playful"` (unless brand voice explicitly requires it)
+- Lifestyle photography in non-work contexts
+- Overly saturated or high-contrast styles (looks out of place in LinkedIn feed)
+- Celebrity or influencer aesthetic
+
+**Target audience contexts (use one per generation):**
+- Person in office setting, focused on screen/work
+- Abstract product/service visualization (SaaS dashboards, data viz)
+- Clean product shot on neutral background
+- Team collaboration scene (diverse, professional)
+
+---
+
+## Lead Gen Form Integration
+
+LinkedIn Lead Gen Forms auto-populate from member profiles. When generating creative
+that promotes lead gen forms:
+- Image should visually represent the offer (e.g., whitepaper cover, webinar slide)
+- For document/guide offers: generate a stylized cover image at 1200×628
+- Avoid "download now" styled images (LinkedIn discourages heavy promotional aesthetics)
+
+---
+
+## Aspect Ratio Priority
+
+When generating a single image for LinkedIn (time-constrained):
+1. `1080×1080` (1:1); covers Feed (best engagement)
+2. `1200×628` (1.91:1); covers legacy + desktop placements
+
+Always generate both for full coverage.
+
+---
+
+## Image Generation Prompt Modifiers
+
+**For Feed (1:1):**
+- `"square composition, subject centered"`
+- `"professional B2B photography style"`
+- `"clean neutral background"`
+- `"no lifestyle elements, business context"`
+
+**For Landscape (1.91:1):**
+- `"horizontal composition"`
+- `"wide framing with subject left or center"`
+- `"ample negative space on right for text overlay area"`

package/stacks/_shared/ads-agents/references/mcp-integration.md

@@ -0,0 +1,125 @@
+# MCP Integration Guide
+
+<!-- Updated: 2026-05-14 | v1.6: added Google's official MCP server + TikTok/LinkedIn/Meta community MCPs -->
+<!-- Purpose: How to pair claude-ads with live ad platform MCP servers -->
+
+## Overview
+
+claude-ads works with manually provided data by default (exports, screenshots, pasted metrics). For live API access, pair it with MCP servers that connect Claude Code directly to ad platform APIs.
+
+## Available MCP Servers
+
+### Google Ads — Server Options (2026)
+
+Three viable options exist as of 2026:
+
+1. **Google's Official MCP Server** (released early 2026): Free, self-hosted, designed with Gemini in mind. Supports Google Ads API v21, OAuth 2.0, 40+ automation tools (`list_accessible_customers`, GAQL `search`, etc.). Read-only in current release.
+2. **cohnen/mcp-google-ads** (community): 29 GAQL-based tools, friendlier developer experience than Google's official. Read-only.
+3. **Ryze AI MCP** (commercial, hosted): Adds safe write access, multi-account, OAuth-managed. Best for teams that want write operations.
+
+### Google Ads: cohnen/mcp-google-ads (community)
+
+**Repo:** https://github.com/cohnen/mcp-google-ads
+**Tools:** 29 GAQL-based tools (read-only)
+
+**Setup:**
+1. Install: `pip install mcp-google-ads` (or clone repo)
+2. Configure Google Ads API credentials (OAuth2 or service account)
+3. Add to `.mcp.json`:
+```json
+{
+  "mcpServers": {
+    "google-ads": {
+      "command": "python",
+      "args": ["-m", "mcp_google_ads"],
+      "env": {
+        "GOOGLE_ADS_DEVELOPER_TOKEN": "your-token",
+        "GOOGLE_ADS_CLIENT_ID": "your-client-id",
+        "GOOGLE_ADS_CLIENT_SECRET": "your-client-secret",
+        "GOOGLE_ADS_REFRESH_TOKEN": "your-refresh-token",
+        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "your-mcc-id"
+      }
+    }
+  }
+}
+```
+
+**What becomes automated:**
+- Search term data for G13, G16, G17, G18, G19 (wasted spend checks)
+- Quality Score data for G20-G25
+- Campaign structure for G01-G12
+- Conversion tracking status for G42-G49
+- PMax asset group data for G31-G34, G-PM1 through G-PM6
+- Budget and bidding data for G36-G41
+
+**What stays manual:**
+- Landing page analysis (G59-G61): use `analyze_landing.py`
+- Creative quality assessment (subjective)
+- Consent Mode V2 verification (requires GTM/tag audit)
+
+### Meta Ads: Adspirer MCP
+
+**Docs:** https://www.adspirer.com/blog/connect-claude-meta-ads
+**Type:** Commercial MCP server
+
+**Setup:**
+1. Sign up at adspirer.com
+2. Connect Meta Business Manager account
+3. Add MCP server config per their docs
+
+**What becomes automated:**
+- Campaign performance data for M11-M18 (structure)
+- Creative metrics for M25-M32 (fatigue detection)
+- Audience overlap for M19 (overlap check)
+- EMQ scores for M04 (requires Events Manager access)
+
+**Alternative: Direct Meta API:**
+Use the included `scripts/fetch_meta_ads.py` with Meta Marketing API credentials for a free, self-hosted option.
+
+### LinkedIn Ads: Multiple Options
+
+**GrowthSpree MCP:** https://www.growthspreeofficial.com/blogs/connect-linkedin-ads-to-claude-mcp
+**Adzviser MCP:** https://adzviser.com/mcp/linkedin-ads
+
+Both provide campaign data access for LinkedIn Ads analysis. Setup follows standard MCP patterns.
+
+### TikTok Ads
+
+Community MCPs now available as of mid-2026:
+- `ysntony/tiktok-ads-mcp`: read-only access for TikTok Ads
+- Pipeboard (commercial): TikTok Ads MCP alongside Meta and Google
+- Loomstack MCP Gateway: includes TikTok Ads access in unified gateway
+
+Manual fallback: TikTok Ads Manager exports (CSV) or TikTok Business API custom integration.
+
+### Microsoft Ads
+
+No dedicated MCP server available as of April 2026. Use:
+- Microsoft Ads Editor exports
+- Google Ads import data (if mirrored)
+- Microsoft Advertising API (custom integration)
+
+### Apple Ads
+
+No dedicated MCP server available as of April 2026. Use:
+- Apple Ads dashboard exports
+- Apple Ads API (custom integration)
+
+## Hybrid Workflow
+
+The recommended approach combines MCP live data with claude-ads structured analysis:
+
+```
+1. Connect MCP server(s) for available platforms
+2. Run /ads audit (claude-ads auto-detects MCP data sources)
+3. For platforms without MCP, provide exports manually
+4. claude-ads merges all data into unified audit
+5. Health Score calculated across all platforms regardless of data source
+```
+
+## Security Notes
+
+- MCP servers run locally; no data leaves your machine (except API calls to ad platforms)
+- Credentials stored in `.mcp.json` or environment variables
+- Read-only access recommended for audit purposes
+- For write operations (campaign changes), see the CEP safety protocol discussion in the itallstartedwithaidea/google-ads-skills repo

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

@@ -0,0 +1,141 @@
+# Meta Ads Audit Checklist
+
+<!-- Updated: 2026-05-14 | v1.6: Threads GA confirmed, EMQ tier guidance refined -->
+<!-- Sources: Google Research PDF 1 (M01-M40), Claude Research (42-item extended), Gemini Research, 2026 Verification Pass -->
+<!-- Total Checks: 50 | Categories: 5 | See scoring-system.md for weights and algorithm -->
+
+## Quick Reference
+
+| Category | Weight | Check Count |
+|----------|--------|-------------|
+| Pixel / CAPI Health | 30% | M01-M10 (10 checks) |
+| Creative (Diversity & Fatigue) | 30% | M25-M32 (8 checks) + M-CR1 through M-CR4 (4 extended) |
+| Account Structure | 20% | M11-M18 + M33-M40 (16 checks) + M-ST1, M-ST2 (2 extended) |
+| Audience & Targeting | 20% | M19-M24 (6 checks) |
+
+---
+
+## Pixel / CAPI Health (30% weight)
+
+| ID | Check | Severity | Pass | Warning | Fail |
+|----|-------|----------|------|---------|------|
+| M01 | Meta Pixel installed | Critical | Pixel firing on all pages | Firing on most pages (>90%) | Pixel not firing |
+| M02 | Conversions API (CAPI) active | Critical | Server-side events sending alongside pixel. Note: Offline Conversions API permanently discontinued May 2025. All offline tracking now uses CAPI with action_source="physical_store". Flag any accounts still configured for Offline Conversions API as FAIL | CAPI planned but not deployed | No CAPI (30-40% data loss post-iOS 14.5) OR still configured for discontinued Offline Conversions API |
+| M03 | Event deduplication | Critical | event_id matching between pixel and CAPI events; ≥90% dedup rate | event_id present but <90% dedup rate | Missing event_id (double-counting) |
+| M04 | Event Match Quality (EMQ) | Critical | Tiered EMQ targets: Purchase ≥8.5, AddToCart ≥6.5, PageView ≥5.5. Case study: EMQ 8.6→9.3 = CPA -18%, match rate +24%, ROAS +22% | EMQ 6.0-7.9 (Purchase) | EMQ <6.0 (Purchase) |
+| M05 | Domain verification | High | Business domain verified in Business Manager | N/A | Domain not verified |
+| M06 | Aggregated Event Measurement (AEM) | High | Top 8 events configured and prioritized correctly | Events configured but not prioritized | AEM not configured |
+| M07 | Standard events vs custom | High | Using standard events (Purchase, AddToCart, Lead, etc.) | Mix of standard and custom | Custom events replacing standard events |
+| M08 | CAPI Gateway | Medium | CAPI Gateway deployed for simplified server-side | Direct CAPI integration active | N/A |
+| M09 | iOS attribution window | High | 7-day click / 1-day view configured | 1-day click only | Attribution not configured |
+| M10 | Data freshness | Medium | Events firing in real-time (no >1hr lag in Events Manager) | <4hr lag | >4hr lag or intermittent firing |
+
+---
+
+## Creative: Diversity & Fatigue (30% weight)
+
+| ID | Check | Severity | Pass | Warning | Fail |
+|----|-------|----------|------|---------|------|
+| M25 | Creative format diversity | Critical | ≥3 formats active (static image, video, carousel) | 2 formats | Only 1 format used |
+| M26 | Creative volume per ad set | High | ≥10 creatives for Advantage+ Sales campaigns, ≥5 for standard. Research: 25 diverse creatives = 17% more conversions at 16% lower cost | 3-4 creatives | <3 creatives per ad set |
+| M27 | Video aspect ratios | High | 9:16 vertical video present for Reels/Stories | Only 1:1 or 4:5 video | No video assets |
+| M28 | Creative fatigue detection | Critical | No creatives with CTR drop >20% over 14 days while active. Andromeda compressed lifespan to 2-4 weeks (was 6-8). Creative Similarity Score: ads >60% similar get retrieval suppression by Andromeda | CTR drop 10-20% | CTR drop >20% + frequency >3 (fatigue confirmed) |
+| M29 | Hook rate (video) | High | Video ads: <50% skip rate in first 3 seconds | 50-70% skip rate | >70% skip rate in first 3s |
+| M30 | Social proof utilization | Medium | Top organic posts boosted as partnership/Spark ads | Some organic boosting | No organic content leveraged |
+| M31 | UGC / social-native content | High | ≥30% of creative assets are UGC or social-native | 10-30% UGC content | <10% UGC (all polished/corporate) |
+| M32 | Advantage+ Creative | Medium | Advantage+ enhancements enabled (test vs control) | N/A | Not tested |
+| M-CR1 | Creative freshness | High | New creative tested within last 14-21 days (tightened from 30d due to Andromeda acceleration) | New creative 21-45 days ago | No new creative in >45 days |
+| M-CR2 | Frequency: Prospecting (ad set) | High | Ad set frequency <3.0 in last 7 days | Frequency 3.0-5.0 | Frequency >5.0 (audience exhausted) |
+| M-CR3 | Frequency: Retargeting | Medium | Ad set frequency <8.0 in last 7 days | Frequency 8.0-12.0 | Frequency >12.0 |
+| M-CR4 | CTR benchmark | High | CTR ≥1.0% | CTR 0.5-1.0% | CTR <0.5% |
+
+---
+
+## Account Structure (20% weight)
+
+| ID | Check | Severity | Pass | Warning | Fail |
+|----|-------|----------|------|---------|------|
+| M11 | Campaign count | High | 1-3 campaigns total recommended. Jon Loomer: "One campaign per goal. Rarely need multiple ad sets for targeting" | 4-5 campaigns | >5 campaigns (over-fragmented) |
+| M12 | CBO vs ABO appropriateness | High | CBO for >$500/day; ABO for testing <$100/day | Mismatched but functional | CBO on <$100/day OR ABO on >$500/day |
+| M13 | Learning phase status | Critical | <30% of ad sets in "Learning Limited" | 30-50% Learning Limited | >50% ad sets "Learning Limited" |
+| M14 | Learning phase resets | High | No unnecessary edits during learning phase | 1-2 minor resets | Frequent resets from edits during learning |
+| M15 | Advantage+ Sales campaign | Medium | Advantage+ Sales (renamed from ASC early 2025) active for e-commerce with catalog. Existing customer budget cap eliminated Feb 2025. Research: 22% higher ROAS, 11.7% CPA improvement | Advantage+ Sales tested but paused | Not tested despite eligible catalog |
+| M16 | Ad set consolidation | High | No overlapping ad sets targeting same audience | Minor overlap (<20%) | Significant audience overlap (>30%) |
+| M17 | Budget distribution | High | All ad sets getting ≥$10/day | Some ad sets $5-$10/day | Ad sets getting <$5/day |
+| M18 | Campaign objective alignment | High | Objective matches actual business goal | N/A | Objective mismatched (e.g., Traffic for Sales) |
+| M33 | Advantage+ Placements | Medium | Advantage+ Placements enabled (unless exclusion needed) | Manual placements (justified) | Manual placements limiting delivery without reason |
+| M34 | Placement performance review | Medium | Breakdown reviewed monthly; underperformers excluded | Reviewed quarterly | Never reviewed |
+| M35 | Attribution setting | High | Attribution windows verified post-Jan 2026 changes (7-day and 28-day view-through windows REMOVED January 2026). 7-day click / 1-day view configured where available | 1-day click only | Attribution not configured or still expecting removed view-through windows |
+| M36 | Bid strategy appropriateness | High | Cost Cap for margin protection; Lowest Cost for volume | N/A | Bid Cap set below historical CPA |
+| M37 | Frequency cap monitoring (campaign) | High | Campaign-level prospecting frequency <4.0 (7-day) | Frequency 4.0-6.0 | Frequency >6.0 |
+| M38 | Breakdown reporting | Medium | Age, gender, placement, platform reviewed monthly | Reviewed quarterly | Never reviewed |
+| M39 | UTM parameters | Medium | UTM parameters on all ad URLs for GA4 attribution | UTMs on some ads | No UTM parameters |
+| M40 | A/B testing active | Medium | At least 1 active A/B test (Experiments) | Test planned | No testing infrastructure |
+| M-ST1 | Budget adequacy | High | Daily budget ≥5× target CPA per ad set | Budget 2-5× CPA | Budget <2× target CPA |
+| M-ST2 | Budget utilization | Medium | >80% of daily budget being utilized | 60-80% utilization | <60% utilization |
+
+---
+
+## Audience & Targeting (20% weight)
+
+| ID | Check | Severity | Pass | Warning | Fail |
+|----|-------|----------|------|---------|------|
+| M19 | Audience overlap | High | <20% overlap between active ad sets | 20-40% overlap | >40% overlap between ad sets |
+| M20 | Custom Audience freshness | High | Website Custom Audiences refreshed within 180 days | 180-365 days old | >365 days old or not created |
+| M21 | Lookalike source quality | Medium | Lookalike source ≥1,000 users from high-value events | 500-1,000 users | <500 users or low-value source |
+| M22 | Advantage+ Audience testing | Medium | Advantage+ Audience tested vs manual | N/A | Not tested |
+| M23 | Exclusion audiences | High | Purchasers/converters excluded from prospecting | Partial exclusions | No purchaser exclusions from prospecting |
+| M24 | First-party data utilization | High | Customer list uploaded for Custom Audience + Lookalike | List uploaded but not refreshed | No first-party data uploaded |
+
+---
+
+## Andromeda & Platform Changes (v1.5)
+
+| ID | Check | Severity | Pass | Warning | Fail |
+|----|-------|----------|------|---------|------|
+| M-AN1 | Andromeda creative diversity | Critical | Ads genuinely diverse across creative concepts, messaging motivators, visual styles. Creative Similarity Score <60% across ad set. Different motivators unlock new audiences 89% of the time | Some diversity but similar visual templates or minor copy variations | All ads are minor variations (Andromeda clusters similar ads with Entity IDs; 100 minor variations = no better than 10) |
+| M-AT1 | Attribution window post-Jan 2026 | High | Attribution windows verified and aligned with business model after Jan 2026 removal of 7-day/28-day view-through options | Using default settings without review | Attribution settings not configured or still expecting removed windows |
+| M-IA1 | Incremental Attribution testing | Medium | Meta Incremental Attribution (launched April 2025) evaluated or active for measuring real causal impact via AI-powered holdout testing | N/A | Not evaluated despite sufficient budget (>$5K/month) |
+| M-TH1 | Threads placement evaluation | Low | Threads placement reviewed. Timeline: limited test Jan 2025 (US/Japan) → global access April 2025 → expanded formats Oct 2025 (Advantage+ catalog, carousel) → fully GA Jan-Feb 2026 worldwide. Observed CPMs $2-$8 (40-60% lower than Instagram feed). Default placement in Advantage+ and Manual Placements. Worth testing for incremental reach | N/A | Not evaluated |
+
+---
+
+## Context Notes
+
+- **Detailed targeting exclusions removal (2025-2026)**: Meta phased out detailed targeting exclusions starting March 2025, with full removal by January 2026. Advertisers must now use Custom Audience exclusions or Advantage+ Audience instead.
+- **Flexible Ads (2024)**: Format launched mid-2024 that automatically optimizes creative elements (headline, image, video) per placement. Evaluate adoption alongside Advantage+ Creative enhancements.
+- **Financial Products Special Ad Category (Jan 2025)**: Financial products (loans, insurance, credit cards, investment services) are now enforced as a Special Ad Category with the same targeting restrictions as Housing/Employment/Credit.
+- **Andromeda (Oct 2025)**: Meta's AI retrieval engine filters tens of millions of ads down to ~1,000 candidates using 10,000x more complex models. Creative diversity is now the #1 performance lever.
+- **Offline Conversions API (May 2025)**: Permanently discontinued. Use CAPI with action_source="physical_store" for offline tracking.
+- **Link clicks redefinition (Feb 2025)**: Meta redefined "link clicks" to exclude social engagement clicks. Accounts comparing pre/post Feb 2025 data may see apparent CTR drops. This is a metric change, not a performance decline.
+- **Meta Shops checkout (June-August 2025)**: Native checkout phased out, redirects to website.
+- **Advantage+ Sales**: Renamed from ASC early 2025. Customer budget cap eliminated Feb 2025.
+
+---
+
+## Quick Wins (Meta)
+
+| Check | Fix | Time |
+|-------|-----|------|
+| M02: CAPI setup | Deploy via CAPI Gateway (simplified) or direct integration | 15 min (Gateway) |
+| M05: Domain verification | Verify domain in Business Manager | 5 min |
+| M09: Attribution window | Set to 7-day click / 1-day view in ad set settings | 2 min |
+| M23: Exclusion audiences | Create Custom Audience of purchasers, exclude from prospecting | 10 min |
+| M25: Format diversity | Add video or carousel to single-image-only ad sets | 15 min |
+| M39: UTM parameters | Add UTM template at campaign level | 5 min |
+| M35: Attribution setting | Switch from 1-day click to 7-day click / 1-day view | 2 min |
+
+---
+
+## Special Ad Categories Compliance
+
+If running ads in restricted categories, these ADDITIONAL checks apply:
+
+| Category | Requirement | Enforcement |
+|----------|-------------|-------------|
+| Housing | No ZIP code targeting, age 18-65+ only, no Lookalike | Campaign disapproval |
+| Employment | Same as Housing | Campaign disapproval |
+| Credit | Same as Housing | Campaign disapproval |
+| Financial Products | New Jan 2025: enforced as Special Category | Campaign disapproval |
+
+Must declare Special Ad Category BEFORE campaign creation. See `compliance.md` for full details.

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

@@ -0,0 +1,134 @@
+# Meta Creative Specs: Generation Guide
+
+<!-- Updated: 2026-03-12 -->
+<!-- Source: platform-specs.md + Meta Ads Manager requirements -->
+<!-- Used by: ads-generate, visual-designer agent -->
+
+## Purpose
+
+Generation-ready specifications for Meta (Facebook + Instagram) ad creative. Includes
+safe zone diagrams, copy limits, and prompt modifiers for each placement type.
+
+---
+
+## Image Specs by Placement
+
+| Placement | Ratio | Dimensions | Priority |
+|-----------|-------|-----------|----------|
+| Feed (preferred) | 4:5 | 1080×1350 | **Primary target** |
+| Feed (square) | 1:1 | 1080×1080 | High |
+| Stories | 9:16 | 1080×1920 | High |
+| Reels | 9:16 | 1080×1920 | High |
+| Right Column | 1:1 | 1080×1080 | Low |
+| Max file size: 30MB. Min width: 600px (1080px recommended).
+
+**Primary generation target: 1080×1350 (4:5)**
+This ratio performs best in Feed and covers Instagram Feed.
+Always generate this first. Generate 9:16 for Stories/Reels campaigns.
+
+---
+
+## Safe Zones: Reels and Stories (1080×1920)
+
+```
+┌─────────────────────────────────┐ ← Top (Y:0)
+│         STATUS BAR              │ ← Y:0-120 (avoid)
+│                                 │
+│      ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓   │ ← SAFE START Y:120
+│      ▓                     ▓   │
+│      ▓   SAFE CONTENT ZONE  ▓   │
+│      ▓      1080×1300px     ▓   │
+│      ▓  (center of frame)   ▓   │
+│      ▓                     ▓   │
+│      ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓   │ ← SAFE END Y:1420
+│                                 │
+│   CTA BUTTON / CAPTION AREA     │ ← Y:1420-1920 (avoid)
+│   REACTIONS / PROFILE INFO      │
+└─────────────────────────────────┘ ← Bottom (Y:1920)
+```
+
+**Bottom 35% (~670px) is UI overlay.** Keep all critical text, faces, and product
+in the center 1080×1300px zone.
+
+**Generation instruction for 9:16 prompts:**
+- Subject and key visual elements in top 60% of frame
+- Bottom 450px should be background only (solid color or soft gradient)
+- Vertical composition only; horizontal crops are rejected at upload
+
+---
+
+## Safe Zone: Feed (1080×1350, 4:5)
+
+No hard safe zone required. The full frame is visible. However:
+- Bottom 120px may be covered by the like/comment bar on mobile
+- Keep primary subject in upper 80% of frame
+
+---
+
+## Copy Limits
+
+| Component | Recommended | Platform Max |
+|-----------|------------|-------------|
+| Primary Text | 40-125 chars | 2,200 |
+| Headline | 27-40 chars | N/A |
+| Description | 20 chars (carousel) | N/A |
+| Reels Primary Text | 72 chars max visible | N/A |
+| CTA Button | Predefined list | N/A |
+
+**Copy generation rule:** Write primary text ≤125 chars. Anything over 125 chars
+gets truncated with "See More" on mobile; the critical message must land in 125.
+
+---
+
+## Carousel Specs
+
+- 2-10 cards per carousel
+- All cards: 1:1 (1080×1080)
+- Per card: Headline ≤40 chars, Description ≤20 chars
+- Generate each card as a separate image prompt
+- Maintain consistent visual style across all cards (same background, same lighting)
+
+---
+
+## Advantage+ Creative
+
+When Advantage+ Creative enhancements are enabled, Meta may:
+- Crop the image to different aspect ratios
+- Adjust brightness/contrast
+- Add music to static images
+- Generate text variations from your primary text
+
+**Implication for generation:** Generate a "base" image that looks good at both
+1:1 and 4:5 ratios. Avoid placing critical elements near edges.
+
+---
+
+## Video Specs (for storyboard reference)
+
+| Placement | Ratio | Resolution | Duration |
+|-----------|-------|-----------|----------|
+| Feed | 4:5 | 1080×1350 | Up to 241 min |
+| Reels | 9:16 | 1080×1920 | ≤90s (rec 15-30s) |
+| Stories | 9:16 | 1080×1920 | ≤120s |
+| In-Stream | 16:9 | 1920×1080 | ≤15 min |
+
+---
+
+## Image Generation Prompt Modifiers
+
+**For Feed (4:5 and 1:1):**
+- `"vertical composition"` or `"square composition"`
+- `"subject fills upper portion of frame"`
+- `"clean, scroll-stopping visual"`
+- `"no text overlay"` (text added via ad copy fields)
+
+**For Stories/Reels (9:16):**
+- `"vertical composition, subject in top 60% of frame"`
+- `"bottom third is clear background or soft gradient"`
+- `"bold, high-contrast visual"`
+- `"mobile-first, designed for small screen viewing"`
+
+**Always avoid:**
+- Cluttered backgrounds (compete with feed content)
+- Low contrast (thumb-stop requires visual pop)
+- Faces cropped at edges (Instagram crops aggressively on some placements)