Ad-data-scraper is the paid ad intelligence layer of the system. It runs as Curator-Hermes — an always-on agent, not an operator command — on a bi-weekly delta cadence and a monthly expansion cadence. Every time it runs it does two things in sequence: first it reads the curated Supabase swipe memory (ads the system already knows about), then it performs a fresh market scan via Foreplay (the primary Meta ad intelligence platform), Exa AI, and LinkUp. Reconciling both shots at goal prevents two failure modes: forgetting what works (memory-only), and missing a new entrant (fresh-scan-only). Every ad it collects is scored by how long the advertiser has kept it running — because advertisers kill losing ads fast, so survival is a profitability proxy. The output is a structured Supabase database of competitor paid ads, tier-classified and ready for ad-autopsy and the ideation phase to read from.
Command bridge: The operator drives this skill through /ad-research, which wraps both ad-data-scraper (paid ads) and ad-organic-scraper (YouTube organic) and delivers a reconciled research brief. Curator-Hermes also runs on schedule without an operator command — the /ad-research invocation reads warm swipe memory first, then fires a fresh scan, then reconciles both.
All calls go through OpenRouter and are logged with model name, provider, and cost before the run closes. Counting and maths are always plain code — never a model.
| Task | Model | Why |
|---|---|---|
| Source identification — discovering which competitors and advertisers are worth tracking, and judging whether a new or early-winner ad is genuinely high-signal. This is the foundational selection decision, NOT the mechanical data pull. | Opus 4.8 (claude-opus-4-8) via OpenRouter — and Fable 5 (claude-fable-5) for the single first-time market map of a brand-new expert only | Low volume, highest consequence. This is the garbage-in-garbage-out gate: the entire pipeline's quality is capped by who we chose to learn from. Save cost on the mechanical volume steps; never here. Fable 5 carries a mandatory 30-day data-retention obligation — do not use on any input containing customer personally identifiable information (PII) without explicit operator sign-off, and do not use on subsequent runs. |
| Foreplay API pull — fetching raw ad records, transcripts, and emotional driver scores from the Foreplay platform | Sonnet 4.6 (claude-sonnet-4-6) via OpenRouter | Extraction and structured write to Supabase (the PostgreSQL database that is the system of record), with light reading of transcript and driver fields. The pull is the data foundation — a mangled extract corrupts every downstream skill — so reliability beats raw token cost. Sonnet 4.6 is the floor for this step. |
| Deduplication by Foreplay ad_id and tier threshold lookup (183 days or more = Tier 1, 91 to 182 = Tier 2, 30 to 90 = Tier 3, under 30 = Tier 4) | Plain code — no language model | Deterministic-first rule. Counting and date arithmetic are pure logic. A language model introduces hallucination risk and unnecessary cost. Completeness is never the model's job. |
| PII scrub on raw transcripts before any Supabase write — strips phone numbers, email addresses, and personal names from all transcript fields | Plain code — deterministic regex | Auditable, reproducible pattern matching. Regex is the correct tool. No model. |
| Minimum-length quality gate — checking whether an ad is at least 25 seconds (or 60 words of transcript), and whether it is hook-only or a full ad | Plain code — no language model | Arithmetic comparison against fixed thresholds. Deterministic. |
| Tagging ads against the controlled vocabulary — funnel position (TOF/MOF/BOF), offer type, cross-industry vertical classification | Sonnet 4.6 (claude-sonnet-4-6) via OpenRouter | Classification against a fixed vocabulary with copy-reading context. Mid-tier job; Sonnet 4.6 is the right tier, Opus 4.8 is overkill for a tagging step. |
| NEW CRUSHER compound-signal escalation — deciding whether a young ad (under 60 days old) meets two or more scaling signals simultaneously, when signal data is ambiguous or missing | Sonnet 4.6 (claude-sonnet-4-6) via OpenRouter | Requires reading emotional driver scores, creative velocity data, and copy context together. The compound-signal rules are explicit; Sonnet 4.6 is sufficient. Plain code handles the deterministic signal checks first; Sonnet handles ambiguity only. |
| Paid Ad Analysis narrative — winner/loser classification, matched-pair diagnosis, cross-advertiser pattern summary. Rendered as clean HTML sections in the review surface (no Google Doc). | Opus 4.8 (claude-opus-4-8) via OpenRouter | The hardest synthesis job in the skill. Reads 50 or more ads across advertisers and extracts structural patterns that transfer to scripting. Requires the full reasoning capacity of the top model. |
| Video transcription where Foreplay does not provide a transcript | Whisper (deterministic, OpenAI) | Transcription is a deterministic transform. Whisper is the standard tool. No language model needed. |
What goes in, and what comes out.
| Input | What it is |
|---|---|
| Expert Name and Niche | Who the expert is and what market they are in. For example: "Amelia Fenmore, interior design business coaching." This tells Curator-Hermes which advertisers are relevant and which are not. The expert namespace (e.g. ida, alba, elena) partitions everything in Supabase — a query for IDA reads IN ('ida','shared'). |
| Positioning Memo | A document from the market research phase that describes the expert's target audience, their core pains and desires, and how the expert's offer is positioned against competitors. Without this, Curator-Hermes cannot judge which competitor ads are actually relevant to study. A missing Positioning Memo halts the run immediately. |
| Offer and Curriculum | The price point, the transformation promised, and the mechanism (the expert's unique process or method). This determines which price tiers of competitor ads to prioritise — for a $10,000 coaching program, ads selling $47 courses are not useful comparisons. |
| Deep Research Report | A validated landscape document from the market research phase. Contains confirmed competitor names, voice-of-customer (VOC) language, and a map of the market. This is the starting competitor list for the scrape. |
| Known Competitor List (minimum 3 to 5) | Specific advertiser names or Facebook page names to start from. Usually extracted from the Deep Research Report. Curator-Hermes expands from these into adjacent competitors using Exa AI discovery queries. |
| Curated Swipe Library — Supabase views (Curator-Hermes memory layer) | The always-on Supabase database of ads Curator-Hermes has already approved or flagged as candidates in previous runs. This is the memory layer — it prevents re-discovering ads the system already knows and surfaces proven patterns from past scrapes. Every /ad-research run reads this before touching any external tool. Current materialised exports for human reference: references/swipe-library-winning-ads.md and references/swipe-library-curated-reference.md. |
| Field | What it means |
|---|---|
| ad_id | The unique identifier from Foreplay for this specific ad. This is the deduplication key. If the same ad appears in two scrape runs, the second run updates the existing record rather than inserting a new one. For the rare Apify fallback ads, the key is APIFY-<date>-<index> — never auto-generated. |
| advertiser_name | The brand name of the company running the ad. For example: "Warrior Babe" or "Jenna Kutcher." |
| signal_tier | A number from 1 to 4 assigned by plain-code lookup on running_duration_days. Tier 1 = 183 days or more (approximately 6 months) — proven converter. Tier 4 = under 30 days — skip unless NEW CRUSHER escalation criteria are met. The model never assigns tiers. |
| running_duration_days | How many days the ad has been running at the time of scrape. Pre-calculated by Foreplay from the started_running timestamp. Primary input to tier assignment. |
| funnel_position | Where in the buyer journey this ad is targeting: TOF (top of funnel — cold audience), MOF (middle of funnel — warm), or BOF (bottom of funnel — retargeting). Assigned by Sonnet 4.6 from CTA and copy signals. A TOF ad running 6 months is stronger evidence of profitability than a BOF retargeting ad running the same period. |
| offer_type | What the ad is selling or driving toward: lead magnet, free training, webinar, application, direct purchase, etc. |
| estimated_price_point | The price range of the underlying offer, validated by fetching the landing page via LinkUp. Bucketed as: under $500, $500 to $2K, $2K to $5K, or $5K and above. Only ads in the $2K and above range are kept for analysis. |
| hook_text | The exact opening line of the ad — the first words spoken or shown on screen. Extracted from the timestamped transcript provided by Foreplay. The most important single field for downstream script writing. |
| full_transcript | The complete word-for-word spoken content of the ad, after PII scrub. Provided by Foreplay for video ads. Feeds directly into the Paid Ad Analysis and the ideation phase. |
| emotional_drivers_json | Scores from 1 to 10 for 14 emotional dimensions — including fear, urgency, achievement, belonging, and authority — as detected by Foreplay's analysis engine. Used in NEW CRUSHER escalation checks and in understanding what emotional levers a winning ad is pulling. |
| variation_cluster_id | A grouping identifier for ads that appear to be variations of the same creative concept (same landing page URL, similar body text, different hooks). When multiple variations exist, it signals the advertiser has found something that works and is scaling it aggressively. |
| new_crusher_flag | Boolean (true/false). Set to true when a young ad under 60 days old meets two or more compound scaling signals simultaneously — see NEW CRUSHER in the Glossary. Escalates the ad from Tier 4 to Tier 2 so it is captured before longevity confirms it. |
| industry_match | "direct" (same niche as the expert) or "cross-industry" (adjacent female-facing vertical with transferable emotional architecture — e.g. health coaching, dating coaching, career transition). Cross-industry ads are Tier 2 priority maximum. |
| asset_scope | "full-ad" (default) or "hook-only" (a very short clip, under 25 seconds or under 60 words of transcript). Hook-only clips are tagged and excluded from full-script pattern training. They may still feed the hook swipe bank. |
| asset_status | One of: "active", "incomplete-transcription" (flagged for re-fetch — ad exists but transcript is too short to learn from), "expired" (Apify CDN URL timed out before download), or "video-pending" (N8N download queued). |
| pii_scrubbed | Boolean. Must be true on every row before it leaves the extract stage. Set by the deterministic regex scrub step. A row where this is false must not be promoted. |
| video_cdn_url | Permanent Foreplay R2 content delivery network (CDN) URL for the video file. These URLs do not expire. Open in a browser to watch the ad directly. This is what the operator uses during manual Tier 1 review. |
| created_by_run_id | The agent_run.run_id that first wrote this row. Immutable. Enables tracing any data point back to the exact scrape session that produced it. |
| expert_namespace | The expert config ID for the expert this row belongs to (e.g. "ida", "alba", "elena", "shared"). All Supabase queries for a specific expert filter on this field. |
| gemini_analyzed | Boolean. True once the N8N Batch Video Analyzer has run automated Gemini visual analysis on this ad. Only applies at scale (5 or more experts active, 50 or more Tier 1 ads per cycle). Not active for the current 1 to 2 expert volume. |
| Step | What happens |
|---|---|
| raw_capture (bronze) | Every ad Curator-Hermes pulls from Foreplay, Exa, or Apify lands here first. All rows stamped with created_by_run_id. PII scrub and minimum-length quality gate run at this stage before any promotion. This is the broadest layer — asset type, price tier, and funnel position agnostic. |
| Curator-Hermes flags candidates | The agent evaluates each raw_capture row against the offer-similarity filter, funnel position signals, and tier thresholds, and marks qualifying ads as candidates for promotion. It does not promote — it only flags. |
| Operator approval gate | A human reviews flagged candidates (using the Foreplay permanent CDN video URL and the Foreplay transcript). The operator approves (human_approved) or passes. Curator-Hermes auto-approves nothing at this boundary. |
| swipe_asset (silver) | Approved ads are promoted here. This is the curated memory layer that every /ad-research run reads first. The ad-system curation layer — only ad-system-relevant, quality-gated, operator-approved assets live here. Downstream skills read swipe_asset views, not raw_capture. |
| Field | What it means |
|---|---|
| agent_name | Always "ad-data-scraper." |
| triggered_by | "cron" for scheduled Curator-Hermes runs. "manual" for operator-triggered runs. Both follow the exact same lifecycle — same gates, same audit trail. |
| expert_namespace | Which expert this run is for. Every Supabase write in the run is partitioned by this namespace. |
| status | One of four values, set when the run closes: success (all advertisers scraped, all rows written cleanly); partial (some advertisers failed, others succeeded — at least one row was written); failed (infrastructure failure mid-run, no rows written after the failure point); halted (run detected a configuration problem — missing Positioning Memo, Foreplay or Supabase unreachable at startup — and stopped before producing any output). A halted or failed run is never treated as an empty result. It marks the layer freshness red and alerts. |
| status_detail | Human-readable explanation of any non-success status. Also records which advertisers failed and why. Example: "Foreplay API unreachable at 14:32 UTC; 0 rows written." Or for partial: "Warrior Babe: 12 ads written. Jenna Kutcher: Foreplay timeout, 0 ads written." |
| ads_written | Count of rows written or updated in this run. |
| completed_at | UTC timestamp when the run closed. Together with started_at, shows the wall-clock duration of the scrape. |
| Column / Tab | What it means |
|---|---|
| Ad ID | Always the Foreplay ad_id. Prefixed with APIFY- for the rare Apify fallback ads. Never auto-generated. |
| Signal Tier | 1 through 4, assigned by plain code. Tier 1 is the most valuable — deepest analysis. |
| NEW CRUSHER | Column flagged "YES" when the new-crusher escalation applies. Makes escalated young ads visible during manual review without changing the Tier number. |
| Hook Text | First line of the ad, from the Foreplay timestamped transcript. The single most referenced field downstream. |
| Video CDN URL (HD) | Permanent Foreplay R2 URL. Open in browser to watch the ad. Does not expire. Used during manual Tier 1 review — approximately 45 minutes for 10 ads. |
| Emotional Drivers | Top 3 emotional drivers and their scores (1 to 10) from Foreplay's analysis. Summarised from the full JSON for readability. |
| Scrape Log tab | Mirrors the agent_run table. One row per run with run ID, triggered_by, scrape type, new ads found, ads updated, tier upgrades, status, and status_detail. |
| Advertiser Registry tab | One row per advertiser. Tracks total ads scraped, Tier 1 count, longest running ad, active ads at last scrape, and estimated scale. |
| Variation Clusters tab | Groups ads by variation_cluster_id. Shows what variable is being tested (hook, thumbnail, opening, CTA), which variation is longest-running, and what the winning pattern is. |
| Section | What it covers |
|---|---|
| Winner analyses | Sorted by longevity, longest first. Each winner: exact hook text, hook framework classification, emotional arc of the body, proof type used, call-to-action psychology, and a scorecard (1 to 5) across hook, trust-building, emotional arc, proof, CTA, and production quality. |
| Loser analyses | Ads killed quickly relative to the advertiser's average. Each gets a failure diagnosis: concept failure (wrong angle) or execution failure (right angle, poor delivery). |
| Matched pairs | Side-by-side comparisons of two ads from the same advertiser — one long-running winner, one short-lived loser. The advertiser and offer are held constant, so the difference is purely creative. These are the most instructive data points in the entire analysis. |
| Cross-advertiser pattern summary | Structural patterns that appear consistently across multiple advertisers and niches. Signals that transfer most reliably to new scripts. |
| Tier 3 catalog | Metadata-only log of ads running 30 to 90 days. Not analyzed deeply, but retained in case they graduate to Tier 2 on a future scrape. |
| Variation cluster insights | For each advertiser running multiple variations of the same concept, what is being tested and which variation is winning. |
--- AD INVENTORY SNAPSHOT — competitor_intelligence (source_type = 'paid_ad') ---
--- expert_namespace = 'ida' | run_id = a7f3c2d1 | 2026-06-11T06:14:00Z ---
ROW 1 (Tier 1 — Verified Winner)
ad_id: fp_wb_001984
advertiser_name: Warrior Babe
signal_tier: 1
running_duration_days: 287
funnel_position: TOF
offer_type: Free training → booked call
estimated_price_point: $5K+
industry_match: cross-industry (women's fitness coaching)
hook_text: "If you want to sustainably eat more while building lean muscle
definition without eating pigeon-sized portions, swearing off
your favorite foods or avoiding parties..."
new_crusher_flag: false
asset_scope: full-ad
pii_scrubbed: true
variation_cluster_id: vc_wb_001
video_cdn_url: https://cdn.foreplay.co/r2/fp_wb_001984.mp4
note: Longest-running ad in vc_wb_001 cluster (3 variations). Winner.
ROW 2 (Tier 1 — Verified Winner)
ad_id: fp_jk_004421
advertiser_name: Jenna Kutcher
signal_tier: 1
running_duration_days: 214
funnel_position: TOF
offer_type: Free training → application
estimated_price_point: $2K–$5K
industry_match: cross-industry (business + personal brand coaching, women)
hook_text: "Nobody told me that the moment I stopped trying to look like
a business owner was the moment I actually became one."
new_crusher_flag: false
asset_scope: full-ad
pii_scrubbed: true
variation_cluster_id: NULL
video_cdn_url: https://cdn.foreplay.co/r2/fp_jk_004421.mp4
note: Confession/vulnerability lead. No cluster — single ad, high longevity.
ROW 3 (Tier 2 — NEW CRUSHER escalation)
ad_id: fp_id_009873
advertiser_name: [Interior Design Academy competitor — anonymised]
signal_tier: 2
running_duration_days: 38
funnel_position: TOF
offer_type: Free training → booked call
estimated_price_point: $5K+
industry_match: direct
hook_text: "The design school I went to never once told me I could charge
$15,000 for a single room. Here's what they left out."
new_crusher_flag: true
new_crusher_signals: ["3+ variations running in parallel",
"brand went from 2 active ads to 7 within 22 days",
"ad still active, launched 38 days ago"]
asset_scope: full-ad
pii_scrubbed: true
variation_cluster_id: vc_ida_comp_001
video_cdn_url: https://cdn.foreplay.co/r2/fp_id_009873.mp4
note: Under-60-day ad escalated from Tier 4 to Tier 2. Three compound
scaling signals met. Capture now — do not wait for longevity.
ROW 4 (Tier 3 — Catalog only)
ad_id: fp_ss_012210
advertiser_name: Shelby Sapp
signal_tier: 3
running_duration_days: 61
funnel_position: MOF
offer_type: Free training → webinar
estimated_price_point: $2K–$5K
industry_match: cross-industry (life coaching, women)
hook_text: "I used to think confidence was something you either had or you
didn't. Then I found out it's just a skill."
new_crusher_flag: false
asset_scope: full-ad
pii_scrubbed: true
variation_cluster_id: NULL
note: Metadata only. Flag for re-check at 91-day threshold.
--- RUN SUMMARY ---
agent_run.status: success
ads_written: 47
ads_updated: 19 (existing rows refreshed with new running_duration_days)
tier_upgrades: 3 (ads crossing 91-day or 183-day threshold this cycle)
new_crusher_escalations: 2
variation_clusters: 8
expert_namespace: ida
completed_at: 2026-06-11T06:47:22Z
competitor_intelligence. The signal_tier (assigned by plain-code lookup on running_duration_days — the model never sets this) tells downstream skills how much weight to give the ad. Tier 1 ads go to deep winner/loser analysis in the HTML review surface and feed ad-autopsy. Tier 2 ads — including NEW CRUSHER escalations like Row 3 — are analysed for hook and structure. Tier 3 ads are catalogued only and re-checked on future runs. The new_crusher_flag makes a fast-scaling ad visible despite insufficient longevity — Row 3 is only 38 days old but is already running 7 simultaneous variations, which is a stronger signal than most 90-day ads. The run summary at the bottom mirrors the agent_run table: success/partial/failed/halted status, counts, and timestamp. Agents and the strategist read Supabase views — not the HTML surface — at runtime.Every abbreviation and tool name spelled out in full. A reviewer must understand these cold.
| Term | In full / what it means |
|---|---|
| TOF | Top of Funnel — An ad targeting a cold audience: people who have never heard of the advertiser before. TOF ads must do all the trust-building work from scratch. A TOF ad that has been running profitably for 6 months is the strongest signal in the framework — it proves the creative converts complete strangers. |
| MOF | Middle of Funnel — An ad targeting a warm audience: people who have engaged with the advertiser before (watched a video, visited the website, interacted on social). These ads carry less trust-building load because the audience already has some familiarity. |
| BOF | Bottom of Funnel — An ad targeting a retargeting audience: people who have already shown strong buying intent (visited the sales page, started checkout, watched most of a webinar). BOF ads that run for a long time do not necessarily indicate a converting creative — they may just be profitable retargeting against an already-warm audience. |
| DTC | Direct to Camera — A video ad format where the presenter speaks directly into the camera lens, creating a one-on-one feel. One of the two main video formats in the IDA creative system (the other is Studio DTC with production lighting and backdrop). |
| UGC | User-Generated Content — An ad format that mimics organic, creator-style content: informal, handheld, less polished. Routed through a separate production pathway in ad-production-brief. In the ad context, "UGC-style" usually means an AI-generated actor or a real creator delivering a scripted message in a native social format. |
| VSL | Video Sales Letter — A longer-form video (typically 10 to 60 minutes) designed to make a complete sales argument. Common in high-ticket coaching and course funnels. Ad scripts driving to a VSL use a shorter hook and tease the transformation without giving away the mechanism. |
| VSR | View-to-Subscribe Ratio — Used in the organic scraper (ad-organic-scraper) to detect high-performing YouTube videos relative to a channel's baseline. Not used in paid ad tier assignment. Appears in shared documentation, defined here to avoid confusion. |
| Tier 1 | Signal Tier 1 — Proven Converter — An ad that has been running continuously for 183 days (approximately 6 months) or more. Assigned by plain-code lookup on running_duration_days. These are the primary reference material for script writing. Tier 1 ads go to deep analysis (winner/loser/matched pair). |
| Tier 2 | Signal Tier 2 — Strong Performer — An ad running between 91 and 182 days (approximately 3 to 6 months). Also the tier assigned to NEW CRUSHER escalations — ads under 60 days old that show two or more compound scaling signals. |
| Tier 3 | Signal Tier 3 — Catalogued Only — An ad running between 30 and 90 days. Metadata is captured; no deep analysis. Re-checked on future scrape cycles and upgraded if it crosses the 91-day threshold. |
| Tier 4 | Signal Tier 4 — Skipped — An ad running under 30 days. Skipped in normal analysis. Can be escalated to Tier 2 if NEW CRUSHER compound signals are present. |
| NEW CRUSHER | New Creative Showing Compound Scaling Signals — A label applied to a young ad (under 60 days old) that shows two or more of these signals simultaneously: (1) three or more creative variations running in parallel; (2) a creative velocity spike — brand went from 1 to 2 ads to 5 or more within 30 days; (3) the ad is still active and was launched within the last 45 days; (4) fear plus urgency plus achievement emotional driver scores all at 7 out of 10 or above. Escalates from Tier 4 to Tier 2 because the advertiser is signalling a winner through scaling behaviour before longevity can confirm it. |
| PII | Personally Identifiable Information — Names, phone numbers, email addresses, and other details that identify a specific individual. Foreplay ad transcripts can contain PII spoken aloud in ads (testimonials, contact details). All transcripts are scrubbed with a deterministic regex pattern before being written to Supabase. Every row must have pii_scrubbed = true before leaving the extract stage. |
| LTGP | Lifetime Gross Profit — The total profit generated from a customer across their entire relationship with the business, before expenses but after the cost of delivery. The target ratio is LTGP to CAC (cost to acquire a customer) of 3 to 1 or higher. This ratio determines which advertiser segments are relevant to study — only advertisers likely operating at this margin level are worth reverse-engineering. |
| CAC | Cost to Acquire a Customer — The total spend required — ad spend plus sales costs — to convert one new customer. The profitability benchmark for this system is LTGP at least 3x higher than CAC. |
| VOC | Voice of Customer — Direct language used by customers to describe their problems, desires, and objections. Typically sourced from reviews, forum posts, survey responses, and testimonials. The Deep Research Report contains VOC data, which Curator-Hermes uses to judge which competitor ads are using language that resonates with the target audience. |
| ICP | Ideal Customer Profile — A description of the specific type of person most likely to buy the offer. For Amelia Fenmore (IDA): women who want to start or grow an interior design business, likely mid-career, seeking professional credibility and customer acquisition. |
| IDA | Interior Design Academy — The expert identity for Amelia Fenmore, an interior-design business coach. IDA cold Meta ads drive traffic to a free training, which converts to booked sales calls. The namespace for all IDA Supabase rows is "ida." |
| Curator-Hermes | Curator-Hermes — Always-On Paid Ad Intelligence Agent — The specific Hermes agent that owns the ad-data-scraper skill. Runs on a bi-weekly delta cadence (longevity updates, new ads, tier upgrades) and a monthly expansion cadence (new competitors, cross-industry scan). Also responds to manual operator invocation via /ad-research. Writes directly to Supabase; generates one clean HTML review surface as the human output. |
| Hermes | Hermes — Autonomous Background Agent Layer — The family of always-on agents that maintain the Supabase data layer without operator commands. Curator-Hermes handles paid ads. Organic-Hermes handles YouTube competitor intelligence. Voice-Hermes handles expert voice extraction. Sales-Hermes handles sales call data. Together they keep all seven data layers warm. |
| Foreplay | Foreplay.co — Meta Ad Intelligence Platform — The primary tool for pulling Meta (Facebook and Instagram) ad data. Returns permanent video URLs that never expire, full transcripts, timestamped transcripts, emotional driver scores, persona targeting data, and pre-calculated running duration. Any competitor found on Foreplay must be pulled through Foreplay before Apify is considered. |
| Foreplay R2 CDN URL | Foreplay R2 Content Delivery Network URL — A permanent video file URL hosted on Foreplay's R2 storage. Unlike Meta's own CDN URLs (which expire within hours), these do not expire. You can open one in a browser today or in six months and the video will still be there. |
| CDN | Content Delivery Network — A distributed file hosting system that serves files from servers close to the viewer. Foreplay hosts video files on their own CDN, making them permanently accessible. Meta's own CDN only serves files temporarily. |
| Exa AI | Exa AI — Neural Search Engine — Used in the competitor discovery step to find advertiser Facebook page names and domains using semantic search queries. Identifies entities (who to look for) but does not scrape ad content itself. |
| LinkUp | LinkUp — Web Enrichment Tool — Used to fetch and validate offer landing pages. Confirms the actual price point and offer type for advertisers where this is not clear from the ad copy itself. |
| Apify | Apify — Web Scraping and Automation Platform — A fallback scraping tool used only when a competitor brand cannot be found on Foreplay. Returns raw ad metadata but not transcripts, emotional drivers, or permanent video URLs. Its Meta video CDN URLs expire within hours — immediate download is required. |
| Supabase | Supabase — Managed PostgreSQL Database Platform — The database that is the single source of truth for all ad intelligence data in this system. The HTML review surface is a generated read-only view of Supabase — never a live source. Any query for current data goes to Supabase views, not Drive. |
| Fibery | Fibery — Project Management and Creative CRM — The system of record for all IDA creative entities, their production status, and their Meta performance data. Hermes agents pull Fibery performance data into Supabase views after each daily Meta and Hyros sync. Curator-Hermes reads Fibery as a sync source — never at runtime. Downstream skills read Supabase views only. |
| OpenRouter | OpenRouter — Unified Model API Gateway — The routing layer through which all language model calls in this system are made. Every call is logged with model name, provider, and cost. This log feeds the agent_run audit trail. |
| N8N | N8N — Workflow Automation Platform — Runs the Batch Video Analyzer workflow that processes Tier 1 and Tier 2 video ads through Gemini 2.5 Flash visual analysis (the GP3/GP4/GP5 prompt sequence). Only activated at scale: 5 or more experts active and 50 or more Tier 1 ads per cycle. Not active for the current 1 to 2 expert volume. |
| GP3 / GP4 / GP5 | Gemini Prompt 3 / 4 / 5 — Conditional Video Analysis Sequence — The three visual analysis prompts run by the N8N Batch Video Analyzer (conditional pipeline only). GP3 analyses a winner ad in detail. GP4 analyses a loser ad and produces a failure scorecard plus a "NEVER" constraint. GP5 compares a matched winner/loser pair from the same advertiser to isolate the single differentiating variable — the highest-confidence source for creative constraints. |
| agent_run | agent_run — Supabase Audit Table — The cross-cutting table that records every agent run in the system. Curator-Hermes opens a row before any external call and closes it with a definitive status (success / partial / failed / halted) when the run ends. Every Supabase row written in the run is stamped with the agent_run.run_id as created_by_run_id. |
| HITL | Human in the Loop — In this skill, the operator approval gate between raw_capture and swipe_asset. No ad is auto-promoted to the curated swipe layer — a human reviews and approves. In the broader pipeline: no autonomous execution in the main creative pipeline in V1. The operator approves at every gate. |
| Meta | Meta Platforms — Facebook and Instagram Advertising — The advertising platform used for all paid ads in this system. Meta refers to both Facebook and Instagram ads, managed through the same Ads Manager interface. |
| Voice Book | Voice Book (Expert Voice Book) — The structured voice artifact built by ad-voice-profile for each expert. Captures signature phrases, sentence rhythm, forbidden patterns, and proof delivery style. Used at every script invocation. Previously called "Layer 3 calibration" — that name is deprecated. Do not use it. |