brand-research

# brand-research

## Purpose

Given a brand (name and/or URL) and a product, produce the full creative-prep package for
it: research the product, analyze the brand's running ads, measure their editorial DNA,
source logos and reference photos, generate brand-anchored product + lifestyle imagery, and
write the brand-context documents a downstream ad/video pipeline consumes.

The output is a **brand-context pack** — a self-contained set of artifacts:

- `brand-summary`, `visual-identity`, `competitors`, `audience` — the core brand context.
- `existing-ads` — what the brand's running ads reveal that web research misses.
- `brand-grammar` — the brand's editorial DNA (archetype, pacing, caption style).
- an **asset manifest** cataloging every sourced + generated asset with its kind, name, and
  usage note, plus the binary assets themselves (logos, reference photos, generated stills).
- a **concept brief** of brand-level ad concept seeds.

Everything is written into a single brand-pack directory under `output_dir`.

## Inputs

- `brand` (required) — the brand, used as the pack's folder name, e.g. `amex`, `liquid-death`.
- `product` (required) — the specific product / SKU / offer to research, e.g. "Platinum
  Card", "Sparkling Water". Disambiguates brands with many SKUs.
- `brand_url` (optional) — canonical homepage. Strongly recommended to avoid wrong-entity
  confusion (e.g. Apple band vs. Apple Inc.).
- `output_dir` (optional) — directory to write the brand pack into. Defaults to `./<brand>/`.
  Resolve the location from this input; never hardcode a path.
- `max_existing_ads` (optional, default 10) — cap on how many of the brand's running Meta
  ads to pull for analysis.
- `brand_video_urls` (optional) — the brand's own video URLs (launch films, demos). If
  provided, run `build-brand-clip-library` afterward to cut them into a reusable clip library.
- `concept_count` (optional, default 6–10) — number of social-ad concepts to draft.
- `skip_generation` (optional, default false) — skip image generation and ship research +
  brief only (useful when no image budget is available).

## Composed Atoms

- `source-company-existing-ads` — download the brand's running ads from the **Meta Ad
  Library** (via the Apify FB Ad Library scraper) into a `raw/` folder with provenance.
- `rename-and-index-ads` — watch each downloaded ad, semantically rename it, and write an
  `INDEX.md` (per-ad strategy + cross-ad patterns).
- `analyze-reference-grammar` — measure each ad's editorial DNA (cut points, pacing curve,
  archetype, audio mode) into a per-ad `grammar-profile.json`.
- `source-brand-assets` — scrape logos + reference hero photos from the brand's site / press kit.
- `understand-brand-assets` — distill web research + reference photos into the visual-identity
  content (colors, typography, photography style).
- `analyze-ad-hooks` — extract recurring hooks/motifs from the downloaded ads.
- `generate-ad-concepts` — produce the concept list for the concept brief.
- `create-product-images-higgsfield-product-photoshoot` — 4–6 hero/end-card product stills
  (Higgsfield product-photoshoot on `gpt_image_2`).
- `create-product-images-nanobanana` — 8–12 vertical 9:16 lifestyle stills (Nano Banana Pro).
- External tools: a video-watching capability (frame extraction + transcription — e.g.
  `yt-dlp` + `ffmpeg` + Whisper), and web search + fetch.

## Workflow

1. **Disambiguate.** Confirm `brand` + `product` resolves to one entity. If `brand_url` is
   missing and the name is ambiguous, stop and ask.
2. **Scaffold the brand pack** under `<output_dir>` — a `brand-research/` folder for the
   markdown docs, a `brand-assets/` folder for the asset manifest + binaries (`logos/`,
   `reference-photos/`, `generated-product-shots/`, `generated-lifestyle/`, `songs/`), and an
   `existing-ads/` folder (`raw/` + renamed copies + a `grammar/` subfolder). Only create
   subfolders that will be populated.
3. **Web research** via web search + fetch. Priority order: brand site → trade press
   (Adweek/AdAge/Campaign) → reputable category reviewers. Capture: product overview,
   mechanics/pricing, benefits, target audience, current named campaigns with dates, core
   positioning, voice/tone. Record every URL with its access date.
4. **Pull and study the brand's running ads.** Mandatory — research without watching real
   ads misses how the product is actually shown and talked about.
   - Run `source-company-existing-ads` (`max_ads=max_existing_ads`) to pull the brand's Meta
     Ad Library ads into the `existing-ads/raw/` folder. Manual fallback per that atom's docs.
   - Run `rename-and-index-ads` to produce semantically named copies + an `INDEX.md` (per-ad
     strategy + cross-ad patterns synthesis).
   - **Product deep-dive pass.** Re-watch (or reuse the frame grids) specifically to extract
     product mechanics the website doesn't show: how the product is held, used, applied,
     opened, paired; in-app UI flows that appear on-screen; physical form factors and
     packaging; claims/proof the brand leans on; demographics and contexts of the people
     shown; objections the ads pre-empt. These feed `existing-ads.md` in step 7.
   - **Editorial grammar pass.** Run `analyze-reference-grammar` on each renamed ad. Each run
     emits a `grammar-profile.json` carrying the ad's archetype match + confidence,
     `cuts_per_10s[]`, mean shot length, payoff-hold ratio, audio mode, and aspect. These
     per-ad profiles are the input to `brand-grammar.md` in step 7 — the brand's editorial
     DNA, so a from-scratch ad can inherit the brand's cut rhythm and archetype defaults.
   - If no live ads are found, write the "No live Meta ads found" stub in BOTH
     `existing-ads.md` AND `brand-grammar.md` ("No live Meta ads found as of <date> — grammar
     defaults will be picked at design-brief time") and continue.
5. **Source brand assets** via `source-brand-assets`:
   - Logos: brand press kit or Wikipedia SVG → `brand-assets/logos/`.
   -