Homa LAB Paid Media → Monochrome

1. What you're taking over

Scope of this handoff: everything prefixed [HOMA-LAB] / [HOMA-WILDCAT] / [HOMA-EXT] on Meta and Google, the PostHog-fed automation that powers it, and the measurement conventions. NOT in scope (Monochrome already owns these): the MM_ Meta campaigns and the G_ "High-Intent Buyers"/"Asterisk" Google campaigns — those are already yours.

2. Access & accounts

Credential files (never in this doc — this is a public URL): Meta system-user token, Google Ads OAuth, PostHog keys, Data Manager OAuth all live on the ops machine. Hand these over securely, out of band. Do not paste secrets into any shared page.

3. Meta LAB campaigns — purpose, fuel & setup

Each campaign below: what it's trying to accomplish (Purpose) and the audience/data that feeds it (Fuel), then its live ad sets.

Prospecting — net-new reach

Retargeting — re-engage known visitors

4. Google LAB campaigns — purpose, fuel & setup

Google is the down-funnel engine — it drives the majority of qualified/approved (see §10). Metro Search captures in-market demand; RLSA Warm closes returning users; Brand harvests demand.

Google LAB = the metro Search campaigns (Tampa/Orlando/Jax/Miami + TX metros), RLSA Warm (best-CPA retargeting layer), Brand, Wildcat exploration, Display remarketing, Hero Video, Extension. Google is the down-funnel engine — it drives the majority of qualified/approved (see §10).

5. Audiences (top 30 by size)

All refreshed nightly by workers (§6) — do not treat as static uploads.

Google Customer Match lists

6. ⚙️ The automation fleet — MOST IMPORTANT

The audiences, Customer-Match lists, and conversion signals are refreshed by automation reading PostHog. It is TWO kinds of infra that transfer very differently — the single biggest handoff risk.

A. Cloudflare Workers — deploy in your Cloudflare account

B. Cron jobs on the ops machine — ⚠️ MUST be re-hosted

These do NOT run on Cloudflare. They run as launchd jobs on the Homa ops Mac and stop the moment that machine is off. You cannot share these via Cloudflare — re-host on your own server/scheduler (or port to Workers). See REHOST.md in the bundle.

Decommissioned / do not use: audience-sync (never deployed, dead code).

7. UTM conventions & attribution truth

How to tell LAB from Mono (critical)

"All Google = LAB" is WRONG. Mono runs Google too (the G_ "High-Intent Buyers"/"Asterisk" campaigns). Case-sensitive G_ vs lowercase g_lab is the discriminator.

Attribution reality — do not trust event-UTM

• Only ~8% of qualified_lead events carry a UTM (92% fire in a direct/untagged session). So a per-campaign "qualified by UTM" view under-counts massively and over-credits whatever channel drove the in-session qualify (usually retargeting).
• Person-level first/last/any-touch is the truth. Roughly: ~45% of qualified/approved are direct/untracked, ~40% single-touch, ~20% multi-touch (double-countable across channels).
• Role split: Meta LAB = top-of-funnel volume (drove ~0 approvals last week). Google + direct = the down-funnel closers. Mono Meta opens journeys; LAB Google closes them.
• PostHog is the source of truth. Ignore Google's own conversion column. gclid→click_view recovery + enhanced-conversions gclid backfill are used to reclaim UTM-severed Google.

8. Optimization events & value ladder

Primary optimization event = engaged_lead (2+ distinct property views in a day) — frequent enough to exit learning, unlike the rarer onboarding_completed. Google Smart Bidding is fed the offline value ladder (via Data Manager):

Recent change (8/6): 5 chronically learning-limited ad sets that optimized the rare onboarding_completed were rebuilt to optimize engaged_lead — currently in learning; let them stabilize before judging.

9. Hard-won gotchas

• DPA creative link limit: can't be a macro or >~1,000 chars → use the homa-metro-go redirect worker.
• Catalog ad sets must use the raw pixel-event form in promoted_object ({pixel_id, custom_event_str}), NOT custom_conversion_id — the latter is accepted, shows no error, and silently never serves.
• New catalog needs its pixel connected (external_event_sources) or a conversion-optimized campaign serves 0 impressions with everything reading green.
• promoted_object is locked after publish — to change the optimization event you must build a new ad set (deep-copy then edit works while unpublished).
• Meta learning resets on: budget change >20%, placement change, audience/optimization change, creative content change. url_tags-only (UTM) changes do NOT reset learning (verified via last_sig_edit_ts).
• Customer Match does not serve on GDN display (search sizes populate, display ~0). Use rule-based/pixel lists for display.
• Placements / Reels: 22 Meta ad sets are Feed-only; 9 remain on Advantage+ (incl Reels) — intentionally left to avoid learning resets. Build any NEW ad set Feed-only at creation to avoid the reset entirely.
• OnSpot open-house audiences are partner-provided/shared and not targetable ("custom audience not available / missing perms"), and can't seed lookalikes. Unblock = get the raw address file and upload as first-party. Currently NOT running.
• Housing special-ad-category blocks lookalike audiences; the metro-carousel commerce catalog is deliberately non-housing to keep LALs + Advantage+ available.
• Reddit is fully paused (foreign/low-quality traffic).

10. Current performance baseline

Watch the right metric. CPL has crashed to $2-3 but that's volume dilution — leads grew +240% while qualified grew ~17%, so the lead→qualified rate fell from 7.7% to 2.6%. Optimize toward cost-per-qualified / cost-per-approved, not CPL. Down-funnel is carried by Google + direct; Meta LAB is cheap reach + retargeting-pool fuel.

11. Open items & handoff checklist

In-flight (mid-change)

• 5 ad sets switched onboarding→engaged_lead on 8/6 — in learning, let stabilize.
• Cold v2 (Price-Engaged) launched 8/7 — new, on Advantage+ placements.
• Fleet budgets glided -20% on 8/6 (LAB only; Mono reverted). Revert values on the ops machine.
• OnSpot open-house audiences loaded but blocked (see §9).

Monochrome onboarding checklist

1. Get partner access: Meta act_9501970176547289 + Google MCC 2225490048.
2. Get PostHog project 141181 access (measurement) + review the attribution truth in §7.
3. Decide on the automation fleet (§6): keep the PostHog→audience/CM/CAPI workers running (recommended — receive the repos + credentials) or plan a replacement before decommission, or audiences go stale.
4. Adopt the UTM conventions (§7) so LAB stays distinguishable from your MM_/G_ work in reporting.
5. Re-baseline against §10 and optimize toward cost-per-qualified/approved.

12. How we run it — operating principles

• Leads are the headline; qualified/approved are the scoreboard. CPL is a vanity metric at scale (it crashes as you buy cheap reach). Optimize to cost-per-qualified and cost-per-approved, and track median viewed price & break-even close rate weekly.
• Signal-first, spend-second. The moat is fresh first-party audiences (the worker fleet), not any bought list. Keep spend capped behind campaigns that target those signals. Data thesis: first-party conversion signal fed to the algorithm beats any static list, and the flywheel is more converters → better lookalike seeds.
• Division of labor is real — fund the closers. Meta = cheap top-of-funnel reach + fuel for the retargeting pool (shallow: ~18% engaged, ~0 direct approvals). Google Search + retargeting = the down-funnel closers (Google runs ~2.5× better CAC). Don't over-fund shallow Meta prospecting because CPL looks great.
• Value-based bidding. Feed the platforms the dollar value ladder (Meta CAPI values + Google Data Manager offline conversions) so Smart Bidding optimizes toward $, not raw event counts.
• Respect the learning phase. Budget steps ≤20% every 2-3 days. Avoid placement / audience / optimization-event / creative-content edits on live ad sets — they reset learning. UTM (url_tags-only) changes are safe. Build every NEW ad set with its final placements + optimization event from birth so you never owe a reset.
• Attribution humility. PostHog is the source of truth — ignore Google's own conversion column. ~45% of qualified/approved are direct/untracked. Judge channels person-level (first/last/any touch), never by event-UTM (only ~8% coverage). Keep LAB (homa-lab) vs Mono (MM_/G_) UTM discipline so reporting stays honest.
• Brand posture is non-negotiable. Buyer-trust over any single close — never anti-realtor, always "up to 2% / $10K-$25K+" framing, ads always show tryhoma.com. Homa will tell a buyer not to buy when that's right; the paid program must never undercut that.
• Reversible & gated. Ship reversible changes freely; gate large spend and anything irreversible. Log outcomes and fail loud (Slack alerts on worker failures) — a silently-broken audience feed is the worst failure mode.

13. Tools & stack to maintain

Skills the operator needs: HogQL, Meta & Google Ads APIs, Cloudflare Workers/wrangler, the value-ladder + person-level attribution model, and the DPA catalog + redirect-worker pattern. Credentials (Meta token, Google/Data-Manager OAuth, PostHog keys, Cloudflare) are handed over out of band — never in this page.

14. Roadmap — how to improve the system

Ranked, highest-leverage first:

1. Fix measurement. Move the dashboards off event-UTM (8% coverage) to person-level journey attribution, and put CPQ / CPA next to CPL so the vanity metric stops being the headline.
2. Populate suppression. Fill the empty Closed + In-Escrow and Qualified exclusion lists (source from Attio) — you're currently paying to re-serve people who already transacted.
3. Unblock OnSpot via Google Customer Match. Get the raw open-house address file from OnSpot and upload it as a first-party address CM list (targetable + lookalike-able) — sidesteps the Meta partner-permission block entirely.
4. Close the reg→qualified gap. Registered users browse deep (median 5 homes) but stall before the tour request; Meta-sourced regs qualify at ~13% vs 26-33% for direct/Google. Add a mid-funnel nudge and tighten Meta registration quality.
5. Scale the closers. Google metro Search + RLSA Warm drive the down-funnel; TX metros have been spend-gated/dark. Push budget toward the best-CAC surfaces (Google), not the cheapest-CPL ones (Meta prospecting).
6. Mature value bidding. As approved volume grows, graduate optimization toward the approved event / higher-value targets; keep feeding accurate ladder values.
7. Creative velocity. Systematic angle testing; DPA dynamic for retargeting, static/carousel for cold audiences; scheduled catalog + creative refresh.
8. Harden automation. Failure alerting on every worker (a stale audience feed reads "green" while degrading), and automate the product-set refresh cadence.

15. Managing the workers — operator guide

Once you have Cloudflare access (Manage Account → Members) and the source bundle, here's how to run, edit, and monitor the fleet.

Where the files are

• Cloudflare dashboard: Workers & Pages → each worker by name (signal-audiences, homa-lab-customer-match-sync, etc.).
• Source: the handoff bundle — each worker is a folder with src/worker.js (or worker.js) + wrangler.toml (which carries its cron schedule + KV bindings).

Editing & deploying

• Quick tweak: dashboard → the worker → Edit code → Save & Deploy.
• Proper way (recommended): cd workers/<name> && npm i, edit src/worker.js, then npx wrangler deploy. The wrangler.toml ships the cron + bindings automatically.

Secrets & config

• Secrets are set with npx wrangler secret put <NAME> — never in source. See the SECRETS.md checklist for each worker's required names; get values from Shawn out of band.
• List what's set: npx wrangler secret list. Non-secret config lives in wrangler.toml [vars].
• KV namespaces: bindings are in wrangler.toml. If you redeploy into your OWN account, create the namespace (npx wrangler kv namespace create <BINDING>) and paste the new id into wrangler.toml.

Schedules & manual runs

• Cron is in wrangler.toml under [triggers] crons. Change the schedule → edit → redeploy.
• Most workers expose a manual trigger for testing without waiting for cron: POST /run?token=<MANUAL_TRIGGER_TOKEN> (or /sync with a bearer). The token is a worker secret.

Monitoring & health

• Live logs: npx wrangler tail <name> (or dashboard → worker → Logs).
• Heartbeats: every worker posts a Slack summary + writes a KV heartbeat on each run (silent-failure rule). A missing nightly heartbeat = a broken audience/CM feed — watch that channel.
• Health endpoint: most expose /health or /healthz returning last-run status.

Troubleshooting

• PostHog 504s on heavy queries are common — the workers retry / run sequentially. A one-off 504 is fine; repeated failures mean the query needs narrowing.
• Stale audience (count not growing) → check that worker's heartbeat + wrangler tail; usually a rotated PostHog/Meta/Google token.
• Customer Match not serving on Display is expected — CM only serves Search (see §9).

Hard rules

• Never touch the MM_ Meta or G_ Google campaigns from LAB tooling — those are your own Mono campaigns; keep them separate.
• Do not let capi_sync.py / catalog_sync.py lapse — they're the re-host-required cron jobs (§6.B). If it stops, CAPI conversions degrade silently. catalog_sync.py is the exception — its schedule is deliberately OFF (§18) and the catalog is maintained by hand.
• Keep the lab_ UTM conventions so LAB stays distinguishable from Mono in reporting (§7).

16. Vendor data refresh — Speedeon (mortgage intent, INBOUND)

Direction matters. Speedeon is inbound — they send us a file, we ingest it and build audiences. OnSpot (§17) is the opposite. Conflating the two breaks both.

The weekly loop

1. Request the file. Ask explicitly for NET-NEW ONLY, suppressed against every prior delivery. Without that we pay twice for the same person and re-contact them — the most expensive mistake available here.
2. Approve counts. They return record counts by state and intent tier before posting. Sanity-check against the selects below.
3. File lands on their SFTP in /homa/out.
4. Pull it: python3 fetch.py — idempotent SFTP pull. Repo ~/homa-engagement/speedeon/.
5. Inspect: python3 intake.py — schema, rows, state split, email coverage. Confirm it matches the approved counts.
6. Suppress anyone already registered, in a recovery flow, or unsubscribed.
7. Activate across all three: Instantly drip, Meta multi-key Custom Audience, Google Customer Match (Observation only).

Current selects

• P1 — Mortgage Purchase Intent: 2+ events in the last 60 days, FL + TX.
• P2 — Mortgage General Intent: 2+ events in the last 60 days (widened from 3+ on 2026-07-17 to reach volume).
• Shortfall rule: fill P1 first, top up from P2 to the target quantity. Ship what exists rather than holding. Only call if the total is under roughly half the target.

What's in the file

• Identity: FNAME, LNAME, ADDRESS, City, State, ZIP, ZIP4, SPEEDEONID.
• Contact: DEPLOYMENT_EMAIL (the one to mail) plus DIGITAL_EMAIL_1..5 for ad-platform onboarding.
• Intent depth: MORTGAGE_GENERAL(_EVENTS_TOTAL) and MORTGAGE_PURCHASE(_EVENTS_TOTAL). Prioritise the drip by event count — it is the only intensity signal in the file.

Baseline from the first delivery (2026-07-17)

• 20,000 records — FL 10,472 / TX 9,528.
• 17,055 with a deployment email (85.3% coverage), zero duplicates.
• Intent mix: 1,790 purchase-intent (P1) vs ~18.2K general-only (P2). P1 is the priority tier.

17. Vendor data refresh — OnSpot (open-house geofence, OUTBOUND)

This one runs the other way. We send them a file of open houses. They match devices seen at those locations during those time windows and push Custom Audiences straight into act_9501970176547289.

The weekly loop

1. Pull open houses: python3 oh_fetch_raw.py "<dates>" oh_raw.json — all 16 FL MLS sources. Save raw first, always — a combined fetch+enrich run that dies mid-flight loses the fetch.
2. Export our warehouse: python3 wh_export.py.
3. Backfill the gap: python3 oh_backfill.py — warehouse wins where present, MLS property endpoint fills the rest. Resumable.
4. Split per weekend: python3 split_weekends.py — Sunday buckets to its own Saturday.
5. RUN THE QA GATE (below). Do not skip it.
6. Send the weekend CSVs. Raw CSV is fine.
7. Verify what landed: list all custom audiences sorted by time_created desc. Do not name-match — their naming varies (Open-Houses vs Open_Houses, hyphen vs underscore) and a name filter silently misses real deliveries.
8. Check real reach with a delivery estimate on the union (see the reach trap).
9. Build the adset. Audiences do nothing on their own.

Scripts: ~/homa-engagement/cold-pool-shell/onspot_weekends/scripts/

Root cause: one MLS feed is broken

The bad rows are not random. They cluster in a single source:

• citrus — 264 of 445 rows bad (59.3%). Systemic: it emits a start on one date and an end on the prior date, a date-rollover/timezone bug at the source. Example: start 2026-08-01T02:00:00Z, end 2026-07-31T20:00:00Z — six hours before it began.
• Trace rates elsewhere: stellar 140/20,176 (0.7%), miami 51/2,790 (1.8%), mcrtc 3/190, swfl 3/2,224, paor 1/1,030.
• Zero bad rows: realmls, ftl, nabor, ecar, ftlrmls, dbar, spacecoast, rairc, catrs, cpar.

Fix options: (A) drop invalid rows before sending — cheapest, costs ~1% of volume; (B) repair the citrus rollover by advancing the end date a day, only where local times validate — a wrong window is worse than a dropped row; (C) escalate upstream, since 59% broken is not something to patch forever.

Agreed terms

• Lat/long only going forward. Do not send both address-match and lat/long — that is what created the duplicate-audience confusion. Lat/long is accurate to ~90 ft with a near-100% match rate; address-match is tighter but only ~80%+ matches.
• One cohort per weekend, kept separate. We OR them together in the adset and Meta dedupes, so separation is free and lets us read decay by cohort.
• Turnaround 24–72 hours, partly manual, not guaranteed. A standing schedule was requested (our file Monday AM → audience live end of day Wednesday); unconfirmed.
• Pricing: month 1 is a locked rate; month 2 reverts to a CPM that moves with monthly spend.

18. The listing catalog — maintain by hand, never on a schedule

What happened on 2026-07-29

It was not an outside attack — it was Meta's own crawler (meta-externalads/1.1), and we triggered it. The crawler fetches a listing's landing URL whenever it needs to read that item. The hourly full-feed re-ingest re-validated all ~16,000 listing URLs against /property/, our most expensive render, across two catalogs. On the worst day the crawler accounted for roughly 10,500 of 12,500 apparent Meta-source visitors — it buried the real traffic in analytics and hammered the origin.

The cost model — the whole rule in four lines

Safe operations

• Remove stale items. POST /{catalog}/items_batch, item_type: HOME_LISTING, method: DELETE on home_listing_id. Chunk ≤200 per call; it's async and returns handles. Use DELETE, not an availability update — availability=pending propagated inconsistently, and an UPDATE against an absent item creates bare stubs that throw missing-image/name/address warnings.
• Add new items incrementally. Same endpoint, method: CREATE, only genuinely new on-market ids, a few hundred per call at most. Each new id costs one fetch — a bounded trickle, not a flood.
• Verify: home_listings?filter={home_listing_id:{is_any:[...]}}. An empty result means the item is invalid and will not display.

CREATE payload — two traps that fail silently

• image MUST be an array — image:[{url:...}]. Passing a plain string, or the bracket-key form 'image[0].url', both fail with a generic "invalid values" / "missing image" error and the item quietly never displays.
• Use the RAW MLS photo on create, not the badged URL. The image compositor hasn't run for a brand-new listing, so the badged object doesn't exist yet and the ad renders a broken image.

Then badge the new items

Hand-added items bypass the nightly badger, which reads the frozen feed. Correct order: CREATE with the raw photo → composite → PUT to R2 → items_batch UPDATE the image to the badged URL. That final image swap re-fetches only the image, so it does not trigger a crawl.

Choosing what to add

Don't add everything. Start from demand: a property_viewed CTE over the last 21 days with HAVING viewers >= 2, then INNER JOIN the listings table on that set — the full-table left-join version times out. Diff against a full catalog id dump to find what's genuinely new. Note the analytics query API applies a default limit of ~100, so always set an explicit LIMIT.

Cadence & scale

• Monthly, or when spend shifts: remove off-market listings. The last pass found 476 of 3,562 served listings (13%) were off-market, but they were drawing only ~1% of spend — this is hygiene, not an emergency. Catalog went 16,336 → 16,150 with zero crawl.
• As needed: add in-demand new listings. Last pass added 55.
• Never: full re-upload, or re-enabling the hourly schedule.