Humanframe — Brand Database (BRAND.md)
The single source of truth for every durable fact about this brand. Any note David sends
(inventory, suppliers, accounts, contacts, decisions) is filed HERE the same turn it arrives —
before any context compaction. Memory files only POINT here. Never store secrets (tokens, keys,
passwords): reference the env file that holds them. Keep entries dated. Hub renders this file.
0 · Identity & entities
| Field | Value |
| Legal entity / owner | TO FILL |
| Key people & roles | TO FILL |
| Support email / phone | TO FILL |
| Brand relationship | TO FILL (own brand / client / partner) |
1 · Products & SKUs
| Code | Product | Size / format | UPC | Formula / spec source | Supplier |
| TO FILL |
2 · Inventory & supply chain
| SKU | Units on hand | Location / 3PL | Lot / mfg date | Shelf life | COGS (landed) | MOQ / reorder lead time | Updated |
| TO FILL |
Notes: TO FILL (fulfillment partner, shipping SLA, packaging on hand — sample packs, inserts).
3 · Offer & pricing (locked)
TO FILL — retail, compare-at, tiers, subscription, guarantee, OTO chain, shipping policy, launch code.
4 · Accounts & IDs (no secrets)
| System | ID / handle | Notes |
| Domain(s) / DNS | TO FILL | |
| Netlify site (id · team) | TO FILL | |
| 29next store / campaign | TO FILL | |
| Meta BM · ad account · pixel | TO FILL | CAPI token → env file only |
| GA4 property · measurement id · GTM | TO FILL | |
| Klaviyo org | TO FILL | |
| adscalerads client · Airtable base | TO FILL | |
| Cookie / event prefix | TO FILL |
5 · Compliance ceiling
TO FILL — category rules, banned words file, reviewer rulings, disclaimer form.
6 · Decisions & taste log (dated, David's verdicts = ground truth)
- 2026-09-14 — Guarantee law applied (David: 'all of the brands use a 30-Day Money Back Guarantee across the board'): HumanFrame moves from the 60-day window (PDP/checkout/echeckout/refunds/emails/5reasons/doctors_pov/top5/surgeon letters) + 90-day residue (checkout seal 90d.webp + 'TRY IT RISK FREE! - 90 DAY MONEY BACK GUARANTEE!', PDP cart drawer '90-Day Results Guarantee', wwi-trick/bathroom-crisis 'Move Like You're 30 90-Day Guarantee') to the single name 30-Day Money-Back Guarantee / 30-day window everywhere; old names retired: 'satisfaction guarantee', 'results guarantee', 'Pain-Free Mobility guarantee', 'Move Like You're 30 Guarantee'. Copy consequence flagged for David: 5reasons' 'longest guarantee in shoulder recovery / Hyperice and Theragun cut you off at 30' claim is no longer true at 30 days — rewritten to 'same 30-day window as Hyperice and Theragun, but with a free return label and no restocking fee'; surgeon-investigation 'better in eight weeks, keep it' → 'four weeks' so the decision point sits inside the window.
- 2026-09-02 — BRAND.md created.
- 2026-09-28 — No price on the Add To Cart button (David: "please remove the price from the add to cart buttons across all pdps and brands"): the button says "Add To Cart" (was "Add To Cart — $49.99"); the trial row's button says "Try It for Free"; the ?ob=c Buy One button says "Buy One". The price lives in the rows, the sticky bar's price stays hidden (09-27). Applied on
products/humanframe/shoulder/index.html; deployed the same day.
7 · Asset map
TO FILL — raw vault, official logos/wordmarks, packaging files, photography, UGC, boards, Visual DNA.
8 · Live surfaces
TO FILL — PDP, home, checkout, hub workspace, boards, console lane, docs pages.
- Copy sheet (2026-10-28, David: every headline and primary-text idea judged on one spreadsheet-style grid, on every brand — copy law CL-23): https://copy-sheet-hq.netlify.app/humanframe/ — no rows yet, the first copy round lands here;
python3 tools/angle-studio/copysheet.py build --brand humanframe --auto·verdictsfolds the 👍 / 👎 intobriefs/humanframe/copy/. · since 2026-10-30 the brand's page on Copy Sheet HQ carries every tab: angles · hooks · hook buckets · ad headlines · ad primary text · email subject lines · the truth gate · every verdict list (the Launch Center's grids and card views retired behind redirects)
9 · Open questions / asks
TO FILL
10 · Change log
- 2026-11-02 — order line under the checkout button (David, from the NailScience board, "for all checkouts … under the checkout button is the order summary, but it would just say the Item/ea price" → lane "B"): a light-grey "Your order" card right under Complete Purchase with the cart's item and its price each, from
tools/checkout_order_line.py(reads the 29next cart; hidden until the cart holds a product; add-ons such as Shipping Protection left out; no MutationObserver, no motion). Checkout + echeckout, card only; units = the store's package quantity ("2x Triple Method Massager · $44.99/ea"). Proved over the live origin, then production 3/3 PASS. The Item / Amount table stays further down. - 2026-09-14 — Guarantee sweep → 30-Day Money-Back Guarantee (was 60-day, with 90-day residue). Hand-edited (no builders): products/humanframe/shoulder/{index,checkout/index,echeckout/index,pages/refunds,pages/fsa-hsa,ads/fb/contact/index}.html + SHOTLIST.md; prelander SOURCES prelanders/humanframe/{5reasons,top5-advertorial,surgeon-investigation,wwi-trick,bathroom-crisis,doctors_pov}/index.html, mirrors re-synced via tools/sync-blog-mirrors.sh (doctors_pov/{ranking,investigation,wwi-recovery,crisis} + products/humanframe/shoulder/5-reasons); email/humanframe/bodies/{01-welcome-e1,leads-education-e1,cart-abandon-d2,cart-abandon-d3,cart-abandoners-e1,leads-d3}.html + manifest.json (Klaviyo templates NOT re-synced — open). Art: checkout/nailscience/images/30d.webp (56×56 copy of the shared template seal) repointed in checkout + echeckout; 5reasons assets/r5-guarantee-30.webp (1024×1024 PIL rebuild of the flat-lay: seal 30-DAY, note '30 days.') repointed. Deployed humanframemd.com via bash tools/deploy-humanframe.sh (hygiene PASS, unique deploy 6aa8d5a35e9b47c30f626a56); live grep on /, /checkout/, /echeckout/, /refunds, /5-reasons/ shows only 30-day forms. NOT deployed (no gated deploy script under tools/): the standalone prelander Netlify sites (5reasons, doctors_pov = thesciencereviewjournal.com, bathroom-crisis, surgeon-investigation, top5-advertorial, wwi-trick) — sources fixed in git, sites still serve 60/90-day copy until deployed.
- 2026-09-02 — created from template + imported 2 memory file(s) as the starting record.
Imported status record (2026-09-02) — distribute these facts into the sections above as the brand is touched
From memory humanframe_attribution_status.md
Canonical IDs (LIVE as of 2026-05-19)
- Domain (apex): humanframemd.com
- Netlify site:
shoulder-rejuvacare— id971dfdd5-8478-400f-aec7-d15ace623b18(EcomScalers team) - 29next store:
spinerelief.29next.store(HF uses spinerelief storefront — distinct from NSacm2) - Meta Pixel (dataset):
980055147727100(canonical; STALE pixel1953793458501776previously fired via the 29next-native Meta Pixel app — uninstalled 2026-05-19 commitc88b6a01) - GTM container:
GTM-P5NGB8L9(HumanFrame brand container) - GA4 account:
394028562(HumanFrame) - GA4 property:
536751238(HumanFrame MD) - GA4 Measurement ID:
G-4B9YY7GXB2 - GA4 API Secret: stored in Netlify env (
GA4_API_SECRET, functions-scope, prod) — never put in code or logs - CAPI endpoint:
/api/capi→shared/functions/capi.mjs(fans out to FB + GA4 in parallel) - Order webhook:
/api/order-webhook→shared/functions/order-webhook.mjs(29next "Order Created" → Meta Purchase CAPI) - Netlify env vars (production context):
FB_PIXEL_ID(all),FB_CAPI_ACCESS_TOKEN(functions),NEXT_WEBHOOK_SECRET(functions),GA4_MEASUREMENT_ID(all),GA4_API_SECRET(functions). Five total.
Status: full attribution stack + GA4 wired (as of 2026-05-19, commit 16d551a3)
2026-05-19 — GA4 wired for HumanFrame (commit 16d551a3)
David created the GA4 property manually after Playwright automation kept failing on the objective-card click. Pasted Account/Property/Measurement IDs + API Secret. End-to-end wire-up:
1. JS code — GA4_ID field updated in canonical products/humanframe/shoulder/tracking/hf-attribution.js from stub G-XXXXXXXXXX → G-4B9YY7GXB2; synced to 11 mirror copies (5 prelander roots + 5 doctors_pov subdomains + 1 shoulder-PDP 5-reasons/). All 12 share sha f91c00a68d09. The JS field is documentation-only — there is NO gtag() call in hf-attribution.js. Client-side hits fire from the GTM Configuration Tag inside GTM-P5NGB8L9.
2. Netlify env vars — GA4_MEASUREMENT_ID=G-4B9YY7GXB2 (all scope) + GA4_API_SECRET=** (functions scope) on shoulder-rejuvacare production. These enable sendToGA4() in shared/functions/capi.mjs to fire Measurement Protocol hits in lockstep with the FB CAPI fan-out.
3. Server-side validation — https://www.google-analytics.com/debug/mp/collect?measurement_id=G-4B9YY7GXB2&api_secret=... returns {"validationMessages":[]} for a purchase payload with transaction_id/value/currency/engagement_time_msec → live /mp/collect will land hits.
4. GTM tag config — SHIPPED via paolobietolini GTM MCP server 2026-05-19 (container version 2 published live). Created All Pages pageview trigger (id 3) + "GA4 Configuration - HumanFrame MD" Google Tag (id 4, type googtag — the MCP server auto-upgrades the documented gaawc type to the modern unified Google Tag) with measurementId=G-4B9YY7GXB2. Verified: curl -s https://www.googletagmanager.com/gtm.js?id=GTM-P5NGB8L9 | grep G-4B9YY7GXB2 returns the measurement ID — container compiled + propagated to Google's edge. Both client-side (gtag via GTM) AND server-side (CAPI fan-out via Measurement Protocol) GA4 paths are now live.
Verification gate (run after GTM publish):
1. Open humanframemd.com in incognito with ?gtm_debug=x → confirm DebugView in GA4 Admin shows page_view + any micro-conversions.
2. Place a real test order (or use $0.01 cart with FB_TEST_EVENT_CODE in env) → confirm Purchase event lands in DebugView from BOTH client (gtag) and server (Measurement Protocol — appears as the "User ID" carrying external_id if set).
3. Cross-platform parity check (attribution_testing_protocol.md Phase 5): GA4 event count matches FB Purchases ±5% over 24h.
LIVE VERIFICATION COMPLETED 2026-05-20 via run_realtime_report (Google Analytics MCP through supergateway + cloudflared HTTPS tunnel). Last-30-min activity on property 536751238: page_view:7, first_visit:4, session_start:4, click:3, user_engagement:3, scroll_depth:1, view_item:1. Full chain confirmed firing end-to-end: humanframemd.com → GTM container → Google Tag (G-4B9YY7GXB2) → GA4 property. Even the dataLayer view_item ecommerce event from PDPs is landing — Google Tag's auto-event-detection picks up the ecommerce push from template/pdp/02_ecom. Saga closed.
2026-05-20 GA4 best-in-class CONFIG via tools/automation/ga4-bootstrap.py
After wiring confirmed live, ran the new bootstrap script (Python + Admin API + ADC w/ analytics.edit scope) to bring HF property 536751238 from default → best-in-class config:
1. Data retention → FOURTEEN_MONTHS + resetUserDataOnNewActivity=true (was 2 months default; would have killed cohort analysis after 60 days)
2. Key events (conversions) — created purchase (was auto), begin_checkout, lead_capture. Now all 3 are conversion-bidding-eligible in Google Ads / SA360.
3. Custom dimensions (event-scoped) — 5 new dims: external_id, landing_url, first_referrer, pattern_i_inherited, utm_source_first. All populated by the gtag('set') block added to hf-attribution.js (commit 911d4f9d, deployed live).
4. Google Ads link — linked customer 1984312798 (198-431-2798) with personalization enabled. Created by david@davidsanghera.com. Ads-side must accept the link in the Google Ads UI for it to fully activate (link shows pending until accepted).
5. JS update — hf-attribution.js (canonical + 11 mirrors, sha 5111ee3cca06) now calls gtag('set', {...}) with the 5 dim values right after the ns_attribution_ready dataLayer push. The gtag shim is defined inline so it's safe whether or not GTM has loaded its own gtag yet — queued args land in dataLayer and get consumed when the GA4 Configuration tag fires.
HARD TRAP CODIFIED: GA4 API requires customDimension.display_name to be alphanumeric + underscore + space ONLY. No hyphens, no parens, no slashes. First run of the script failed all 5 dims with "Value for field display_name must only contain alphanumeric, underscore, or space characters". Renamed (First-Touch → First Touch, External ID (Persistent UID) → External ID Persistent UID) and re-ran. Trap documented in ga4-bootstrap.py + the skill note.
2026-05-21 Cross-domain measurement SHIPPED (GTM container v3 LIVE)
Empirical first — queried GA4 property 536751238 for last-30d hostName dimension to find the ACTUAL HF cross-domain ecosystem (had earlier wrongly listed NS domains by mistake). Result: exactly 2 hostnames drive HF traffic:
thesciencereviewjournal.com— 101 sessions (HF doctors-pov prelander, Netlify sitehumanframe-doctors-pov)humanframemd.com— 36 sessions (brand apex / PDP / 29next checkout embed = same origin)
The other HF prelander folders (bathroom-crisis/, 5reasons/, surgeon-investigation/, wwi-trick/, top5-advertorial/) exist in the repo but aren't deployed to custom domains or aren't in active rotation. NS-related domains (thehealthreportdaily.com, quiz.trynailscience.com, etc.) are NOT in HF's funnel — those belong to NS's property 532702197.
Wired via paolobietolini GTM MCP:
1. get_tag on GA4 Configuration Tag (id 4) — confirmed type googtag + only param was tagId
2. update_tag adding configSettingsTable with row linker_domains=humanframemd.com,thesciencereviewjournal.com
3. create_version v3 + publish_version
4. Edge-verified via curl gtm.js?id=GTM-P5NGB8L9 | grep -E "linker_domains|thesciencereviewjournal|humanframemd" — all 4 present
HARD TRAP CODIFIED: Publishing a version locks the workspace ("Workspace is already submitted" error on subsequent edits). GTM auto-creates a fresh Default Workspace with a new ID after publish — workspace ID went 2 → 3. Entity IDs (tags, triggers) are preserved across the workspace transition. The MCP's list_workspaces reveals the new ID. After every publish, the next session of edits requires either: (a) list_workspaces to grab the new ID, OR (b) create_workspace to start a fresh named one.
Cross-domain effect (verify within 24h): sessions from thesciencereviewjournal.com followed by humanframemd.com should now count as ONE session per user (linker passes ?_gl=... URL param preserving the _ga cookie ID across the origin hop). Previously these split as 2 sessions inflating bounce + resetting first-touch attribution at the prelander→brand transition.
Standing follow-ups:
- Accept the Google Ads ↔ GA4 link from the Ads side (Google Ads → Tools → Setup → Linked Accounts → Google Analytics (GA4))
- Verify within 24h:
run_reportfor property 536751238 with dimensioncustomEvent:external_idreturns non-empty values (the gtag('set') is populating after the deploy) - Verify within 24h:
run_reportwithsessionDefaultChannelGroup+sessionsshould show the prelander→brand journey as one session per user (no inflated session count)
2026-05-19 — Purchase over-count audit + closure (commits c88b6a01 / 7b01cc28)
Three over-count vectors found and closed across HF (mirror of NS doctrine):
1. Naked-image &ev=Purchase (no eid) in products/humanframe/shoulder/checkout/index.html + echeckout/index.html — un-dedupable against the canonical trackEvent('purchase', 'Purchase', {event_id:'purchase_'+orderId,...}). REMOVED.
2. Legacy event:'transaction' dataLayer push in products/humanframe/shoulder/special-offer/vip/index.html — GTM Purchase-tag trigger name. RENAMED to event:'upsell_accept'. Bundle + Upgrade upsells did NOT have this push.
3. 29next-native Meta Pixel app on spinerelief.29next.store — was firing alongside ours and pointing at stale pixel 1953793458501776 (not canonical 980055147727100). Failure mode 3b (leakage to wrong pixel) not 3a (canonical double-count). App UNINSTALLED 2026-05-19. Audit recipe codified in SKILL Pattern H.
2026-05-19 — First-touch attribution capture (commit f8aacf7a)
_ns_referrer cookie (set-once 30d TTL) + _ns_landing (set-once) + _ns_utms (last-tagged-touch within 30d) → injected into checkout as note_attributes → forwarded by order-webhook.mjs to Meta CAPI custom_data as utm_source/medium/campaign/term/content + landing_url + referrer. Catches returning organic + branded-search → apex entries that Pattern I had no upstream cookie to forward. NS-prefixed cookies are shared HF+NS namespace (legacy from HF being forked off the NS template, not worth renaming live cookies).
2026-05-08 — Pattern I cross-domain forwarding (commit history starting c19967d)
Prelanders on tertiary domains (thehealthreport / etc.) lift _fbp/_fbc/_hf_eid cookies into URL params (fbp_in/fbc_in/eid_in) on CTA click. Destination's hf-attribution.js adopts them BEFORE generating its own. Click-time refresh required because fbevents.js writes _fbc async. Quiz prelanders patch forwardParams() not COOKIE_TO_URL (no data-cta-forward anchors). Full doctrine in SKILL Pattern I.
29next webhook signature header (commit c19967d)
29next uses header x-29next-signature (hex HMAC-SHA256 of raw body, secret NEXT_WEBHOOK_SECRET) — NOT the Shopify-convention *-Hmac-Sha256 header. Without this in VERIFY_HEADERS, all incoming webhooks return 401 "Missing signature" silently. Diagnosed via WEBHOOK_DEBUG=1 mode that echoes received headers + computed HMAC.
"Inactive webhook" circuit-breaker trap (general)
29next auto-disables webhooks after N consecutive 4xx/5xx. Inactive = 0 events / 0 errors / no logs — deceptively healthy. Reactivate via webhook Update form, BUT only after the handler is healthy (curl-probe /api/order-webhook for non-401 first) — else the breaker re-trips. HF webhook has NOT flipped Inactive historically (NS one has, twice).
Standing watch items
- DebugView verification — within 24h of 2026-05-19 GTM publish, walk through Phase 3 of
attribution_testing_protocol.mdwith?gtm_debug=xon humanframemd.com. Confirm page_view + session_start land from BOTH client (gtag via GTM tag id 4) AND server (Measurement Protocol viashared/functions/capi.mjsfan-out). - 24h diagnostics review — fbp ≥ 90%, external_id ≥ 95%, EMQ ≥ 7 for Purchases. GA4 event count matches FB Purchases ±5%.
- HF webhook Active badge — spot-check
spinerelief.29next.storeApps → Webhooks every ~1-2 weeks (mirror of NS standing item). - Meta Pixel app uninstall — verify the 29next-native app stays uninstalled (no auto-reinstall via integrations).
2026-06-08 — INCIDENT: SkinScience CLI-link clobbered HF env (recovered)
While wiring SkinScience env vars, netlify env:set/unset --site=<SS 9f0fc061> ignored --site and used the CLI's cached link to shoulder-rejuvacare (this HF site), clobbering HF's production env:
FB_PIXEL_IDproduction was overwritten with SS's996202390008940→ HF orders were posting into SkinScience's dataset (cross-brand contamination) until caught. Restored to980055147727100(all contexts) + redeployed.NEXT_WEBHOOK_SECREToverwritten with SS's → HF webhook 401. Restored to HF's real 29next secret8171266f554b+ redeployed. Verified: unsigned → 401, signed → 200.FB_CAPI_ACCESS_TOKEN: HF's original wasunset(lost — secret/unreadable). Temporarily held SkinScience's token (worked), then RESOLVED 2026-06-08: David generated a dedicated HF token (EAAGSPYoNJgQBRm9cHfn…), verified posts to HF pixel 980 (events_received:1), set on HF site 971dfdd5 via the Netlify API (PUT, explicitsite_id— NOT the hijackable CLI), redeployed. HF fully decoupled from SkinScience (own pixel + own token + own webhook secret + own GA4).GA4_MEASUREMENT_ID/GA4_API_SECRET: untouched, intact.
HF 29next webhook (now recorded): store spinerelief.29next.store, name "Facebook CAPI", target https://humanframemd.com/api/order-webhook, trigger order.created, signing secret 8171266f554b, API version 2023-02-10.
Root cause + fix: worktree-root .netlify/state.json was linked to shoulder-rejuvacare → netlify unlink done. Lesson codified in skills/attribution-launch/ Trap 2 (top trap): netlify ENV commands ignore --site; verify env:list banner names the expected project, prefer UI/API with explicit site_id, never env:unset an unre-readable secret.
2026-06-15 — INCIDENT: Meta BLOCKED HF's standard events (3-day attribution zero) → dual-fire "shadow event" architecture shipped
Symptom: David reported ~3 days of ZERO attribution in the Meta ad account. Triage proved our send-path was 100% healthy (don't re-chase it): CAPI token DELIVERS to 980 (events_received:1); live pixel fires 980 on PDP+checkout; live hf-attribution.js byte-identical to repo (no edge revert); /api/capi→204; webhook enforces (unsigned→401); env clean (FB_PIXEL_ID=980, no FB_TEST_EVENT_CODE, no kill-switch). Root cause is META-SIDE: Events Manager shows HF's STANDARD events (AddToCart/Purchase/AddPaymentInfo/InitiateCheckout/ViewContent) as "Blocked by Meta" on dataset 980 ("HumanFrame2"). David's FB account manager confirmed it's an integrity issue on Meta's side and advised re-emitting the funnel as CUSTOM events. (Standard events are invisible to optimization/attribution while blocked, but 29next first-party UTM attribution stays perfect — which is why orders looked attributed but Ads Manager read zero.)
2026-06-16 — Meta-UI side of the swap (operational, David did it): HF ad account = "Liaison – B" 243417265464399 (business AMH Ventures, which also owns SkinScience's 996). HumanFrame2 (980) IS shared with that ad account (Dataset → Settings → Ad accounts) — so the asset connection was NEVER the problem (a "two-pixel" red herring: AMH also has an older "Human Frame MD" pixel ~1057…, but the ad sets were already on 980). The actual operational gap: the ad sets (J&T – Ranking + J&T – Investigation, prelander campaigns) were optimizing for Conversion event = the BLOCKED standard Purchase → 0 conversions → 0 attribution (content views showed because ViewContent wasn't blocked; ATC/checkout/purchase showed "—" because blocked). Fix = edit each ad set → Conversion event Purchase → HF_Purchase (custom conversion, category Purchase, URL contains humanframemd.com, value unchecked=dynamic). Built the 5 custom conversions on 980 (HF_Purchase id 1046123617862763, etc.). GOTCHA: a brand-new custom conversion is selectable in the ad-set Conversion-event dropdown immediately but does NOT appear in Customize-Columns search for up to ~24h (and often not until it has attributed data in the account — chicken-and-egg broken by switching the ad-set optimization). Don't judge propagation by the column picker. Switching the ad-set conversion event resets the learning phase (few-day re-learn). Verified the HF_* events live on 980: HF_ViewContent Active/Multiple/29 recv, HF_Purchase 8.2 EMQ/Multiple. Test/seed events to disregard: HF-SEED-, HF-SHADOW-VERIFY (value 0).
Fix shipped — dual-fire "shadow events" (commit 2e3b3ec3, merged to main, HF deployed + verified): every standard CONVERSION event now ALSO fires as a custom mirror HF_<Name> (same event_id, parallel signal — Meta dedups on name+id so they don't collide). When standard is blocked you optimize on the HF_* custom conversions; when Meta unblocks, flip campaigns back — zero code/deploy, because the mirror is always flowing. Portable across brands.
- Browser half:
hf-attribution.jsconfigSHADOW_PREFIX:'HF_'+SHADOW_EVENTSlist + intrackEvent, after the standardfbq('track',…), firefbq('trackCustom','HF_'+name,…,{eventID}). - Server half (SHARED, env-gated):
shared/functions/capi.mjssendToFacebook— whenCAPI_SHADOW_PREFIXenv set ANDevent_name ∈ FB_STANDARD_EVENTS, push{...fbEvent, event_name: prefix+name}into the SAME/eventsdata[]. Covers the browser relay AND the 29next webhook Purchase (webhook forwards through/api/capi). Inert for brands without the env var. - Env:
CAPI_SHADOW_PREFIX=HF_(functions scope) on HF site971dfdd5, set via the Netlify API (explicitsite_id, NOT the CLI). - Excluded: PageView (conversion steps only, David). GA4/dataLayer + existing customs (
UpsellView/ReceiptView) untouched. - Verified: live JS carries the shadow;
events_received:2for[Purchase, HF_Purchase]in one POST; seeded one of eachHF_*event to 980 so they're selectable in Custom Conversions. Test events to disregard:HF-SHADOW-VERIFY*,HF-SEED-*(all value 0). - 5 Custom Conversions to build in Meta (HumanFrame2):
HF_Purchase→Purchase,HF_AddToCart→AddToCart,HF_InitiateCheckout→InitiateCheckout,HF_AddPaymentInfo→AddPaymentInfo,HF_ViewContent→ViewContent; URL rule broadhumanframemd.com/(custom event name is the real filter; webhook server Purchase carriesevent_source_url=humanframemd.com/checkout/perorder-webhook.mjs:493, browser fires from /checkout/ AND /echeckout/ — narrow rule would exclude server/echeckout fires). Then point campaigns atHF_Purchase. - Rollout: HF = archetype. SkinScience/NailScience activate by adding
<BRAND>_prefix to their*-attribution.js+ settingCAPI_SHADOW_PREFIXenv + redeploy (capi.mjs already ships the logic). SS is next. Codify pattern inattribution_stack_skill.md+ a "events blocked → swap" runbook.
TOKEN-HYGIENE NOTE (not the outage cause): HF's FB_CAPI_ACCESS_TOKEN (EAAGSPYoNJgQBRm9cHfn…, the "dedicated HF token" from the 2026-06-08 restore) is actually issued by SkinScience's Conversions API App 442267983488516, scope read_ads_dataset_quality — NOT an HF-business token. It DELIVERS to 980 fine (auth accepted, events_received:1) but can't READ the dataset (GET→"(#100) Missing Permission"). Works, but fragile (dies if SS rotates). Eventually replace with an HF-business-owned token. The read_ads_dataset_quality scope posting fine = consistent with the SkinScience ?access_token= lesson.
SEPARATE OPEN ITEM — Apple Pay / express-wallet fbc gap (order #106865, diagnosed 2026-06-12, fix NOT yet implemented): for Apple Pay/Google Pay/PayPal, the browser Purchase never fires (redirect beats the 29next order:completed hook — confirmed checkout/index.html:1628), so the server webhook is the only Purchase. It can't recover fbc for express orders because (1) the card-form hidden attributes[_ns_fbc] never submits, (2) the SDK never auto-populates attribution.metadata.fb_fbc (only debug-logs it), (3) Source-3 reconstruction throws on a relative landing_site / never reads the referrer where the fbclid actually lives. Designed fix (live-SDK-verified, not built): client sdk.addMetadata('fb_fbc'/'fb_fbp'/'eid_in',…) via 29next NextCommerce SDK (buildExpressOrder→getAttributionForApi serializes attribution.metadata for the wallet path) + webhook hardening (referrer fbclid/fbc_in/fbp_in extraction, relative-URL-safe new URL, referrer in the reconstruction fallthrough). Affects all 3 brands (shared template + webhook). Wallet pay = big % of iOS FB traffic. Distinct from the Blocked-by-Meta issue above.
Cross-references
skills/attribution-launch/— per-brand wiring + the CLI-link footgun (top trap)skinscience_tracking_status.md— the SkinScience run that triggered thisattribution_stack_skill.md— Pattern H (Purchase fire-once + 3 over-count vectors + first-touch capture) + Pattern I (cross-domain forwarding) doctrineattribution_testing_protocol.md— 5-phase EMQ + dedup verification protocol (mandatory after any large change)nailscience_tracking_status.md— NS parallel; HF was Pattern I template, NS ported 2026-05-16project_attribution_framework.md— 6-tier checklistreference_netlify_deploy.md—--functions=shared/functionsHARD RULEplaywright_browser_automation_rule.md— Playwright > Chrome MCP rule + GA4 account-context trap that bit during 2026-05-07 NailScience MD account incident
From memory humanframe_klaviyo_status.md
Status (last updated 2026-05-19): Segments native-metric; popup-arc carve-out fixed; flows rebuilt for url_encode bug; Cart flow filter changed flow-start→all-time (excludes ALL past purchasers). CURRENT FLOW IDS: Cart VZSufb (was SWw4yP←QUVjxZ), Leads YfasJS (was SMYtpS), Welcome QRTgpD. All DRAFT. Only Gate 2 (domain auth + Settings address) remains for go-live.
2026-05-19 — Cart flow profile_filter: flow-start → alltime (exclude existing customers)
David (re: Brad Moore showing "Enters" the Cart flow despite having placed an order): "change it to all time." Root cause: Cart SWw4yP profile_filter was Placed Order Yiy9HJ count==0 with timeframe_filter {operator:"flow-start"}. "Since flow-start" does NOT exclude past purchasers — it only counts orders placed AFTER entry, i.e. it only EXITS someone who buys during the flow. An existing customer who starts a new checkout still ENTERS (and for an 83%-off "only 13 launch codes" offer that's a margin + honesty problem). Verified Brad: 1 Placed Order + 1 Started Checkout (both 2026-05-18), in HF Customers, NOT in Leads-trigger VYktQP, NOT in WPehm7 — so the only thing letting him into Cart was the weak flow-start filter.
Fix: rebuilt Cart flow with timeframe_filter {type:"date",operator:"alltime"} (schema from OpenAPI AlltimeDateFilter). Now Placed Order count==0 all-time → excludes ANY profile that has EVER ordered AND still exits anyone who buys mid-flow (all-time count →≥1). Reused the existing render-OK Cart seeds VRJwLh/Wq8j3w/SJDhFa/RuBcrU (no template recreate). Verified before deleting old: trigger==VHQGTQ, filter operator==alltime, action/delay/subject parity ==old, 4 new clones render 200. Cart flow SWw4yP → NEW VZSufb (old deleted, DRAFT so safe). New clones TAry85/SkpsSP/SSMfa4/U4c63U; seeds unchanged.
DURABLE LESSON (also in skill/Obsidian): a Klaviyo flow profile-filter Placed Order count==0 with timeframe operator:"flow-start" is an EXIT condition (leave if you buy after entering), NOT an exclusion of existing customers. To bar anyone who has EVER converted (correct default for a deep-discount / launch-scarcity recovery flow), use timeframe operator:"alltime". Always ask: is this filter meant to exit-on-new-conversion (flow-start) or exclude-prior-converters (alltime)? For discount-bearing recovery flows it's almost always alltime. Leads YfasJS not affected — segment-gated by VYktQP (Placed Order==0 1825d) which already bars past purchasers (Brad verified not in it).
2026-05-18 — Cart + Leads flows REBUILT: url_encode filter broke Klaviyo render ("preview doesn't work")
Symptom (David): "preview doesn't work" on HF Leads + HF Cart Abandon flows. Root cause (reproduced via POST /api/template-render/, not assumed): every CTA link used the Liquid filter {{ person.X|url_encode }} — url_encode is NOT a valid Klaviyo/Django filter; the correct filter is urlencode (no underscore). A single bad filter makes Klaviyo fail the ENTIRE template render → "Unable to render given template with provided context. Please check included django syntax." The HTML looked perfect and the content was all there (verified via MCP klaviyo_get_email_template) — classic silent-content failure; only the render API surfaces it. Isolated empirically on disposable templates: url_encode→FAIL, urlencode→OK (all other Liquid — default:, if person.location.*, if event.Items.0.Quantity, etc. — fine).
Fix: (1) repo source email/humanframe/bodies/{cart-abandon,leads}-d0..d3.html + preview-build.py — url_encode→urlencode (9 files). (2) Flow content is API-immutable (flow-clone templates: REST GET 200 but PATCH 404 — readable, not editable) → delete+recreate both flows (both DRAFT, no in-flight profiles, safe). Built 8 corrected standalone templates → render-gated (all 200) → recreated both flows preserving every setting → structural parity verified (trigger, profile_filter, action sequence, delays, subjects all == old) → render-verified all 8 new clones (200) → only THEN deleted old QUVjxZ/SMYtpS.
NEW PRODUCTION IDS (supersede QUVjxZ/SMYtpS everywhere):
- Cart flow
SWw4yP"HF Cart Abandon (4-day, akemi)" DRAFT — trigger metricVHQGTQ; delay 2min → email → 1d → email → 1d → email → 1d → email; profile_filter Placed-OrderYiy9HJ==0 at flow-start. Standalone seedsVRJwLh/Wq8j3w/SJDhFa/RuBcrU; flow clonesYjMH6g/U7UTsF/RGtXjz/X5KBR2. - Leads flow
YfasJS"HF Leads (4-day, akemi)" DRAFT — trigger segmentVYktQP; email → 1d → email → 1d → email → 1d → email; profile_filter Placed-Order==0 AND Started-CheckoutVHQGTQ==0 at flow-start. Standalone seedsVBQKJ7/UmNEuR/Uhbq9t/Sq8ghA; flow clonesVPHwBL/VcGtZ9/SMfxS3/Yaxcpu.
DURABLE LESSONS (also in klaviyo_segment_api_skill.md / Obsidian): (1) Klaviyo Liquid URL-encode filter = urlencode, never url_encode; one bad filter fails the whole render silently. (2) ALWAYS verify a Klaviyo template/flow email via POST /api/template-render/ (it reproduces the UI "Preview") — visual/GET inspection of the HTML does NOT catch render-breaking Liquid (same class as "verify segment by membership size, not HTTP 200"). (3) Flow definition AND flow-clone template HTML are API-immutable post-create → fix = rebuild from corrected standalone templates. (4) Flow-create schema: actions need temporary_id+links.next+entry_action_id; a minutes/hours time-delay must NOT include delay_until_weekdays/delay_until_time (GET echoes them but create 400s — strip when unit≠'days').
2026-05-18 — HF segments re-pointed off dead 29next properties → native Placed Order metric
Reported bug (David): "HF Customers (have ordered) is not updating with new customers who've placed an order, like Brad Moore."
Diagnosis (confirmed): Brad Moore (01KRYJB44RVZC62VVMK6E5W764, bradmoore1959@gmail.com) had predictive_analytics.historic_number_of_orders:1 / historic_clv:$91.97 — Klaviyo received his order natively as Placed Order metric Yiy9HJ via the API integration — but properties['29next_orders_count'] = None. The 3 customer/lead/VIP segments were gated on properties['29next_*'], which are ONLY written by the ongoing 29next→Klaviyo property sync (the GH Actions cron, .github/workflows/29next-klaviyo-sync.yml). That sync is not materializing those props (secrets never added / not writing profile props), so every order placed after the one-time backfill was invisible to the property-gated segments. Native Placed Order events fire fine regardless. → Root cause: segments gated on sync-written 3rd-party properties, not native metrics.
Fix applied (David chose "Re-point to native metrics (rec)"): all 3 re-pointed via PATCH /api/segments/{id}/ (segment defs ARE PATCH-able in place — HTTP 200, segment id preserved, NO flow-trigger repointing needed, unlike flows which are create-immutable). Verified live:
UgxQFJHF Customers → Placed OrderYiy9HJcount > 0 (in-the-last 1825d). Brad Moore now IN ✓ (membership re-confirmed byGET /segments/UgxQFJ/profiles?filter=equals(email,...)).VYktQP(renamed "HF Leads — recovery (no order, excl. popup arc)") → Group0 Placed OrderYiy9HJcount == 0 (1825d) AND Group1 = OR(hf_signup_sourceexistence:not-set,hf_signup_sourcenot-equalspdp_exit_popup). Verified 30 members (the real no-order cohort). NOTE: the FIRST attempt used a barenot-equalsand silently emptied the segment (0 members) because Klaviyonot-equalsrequires the property to EXIST — caught by a membership-size check, restored, then fixed with the existence-OR pattern. See SIDE-EFFECT below.SLBYqiHF VIP → Placed OrderYiy9HJcount > 3 AND sum > 299.99 (both conditions one group = AND, 1825d).
Klaviyo segment-condition schema learned (probed empirically on a disposable test segment, never guessed on the live one — /tmp/hf_vip_probe.py): to filter on total spend / sum of a metric's $value, use measurement: "sum" on a profile-metric condition (NOT sum_value/value/total/value_sum — all 400 "invalid field type"). sum sums the metric's $value by default; no value_field/dimension key needed. Full shape: {type:"profile-metric", metric_id, measurement:"sum", measurement_filter:{type:"numeric",operator,value}, timeframe_filter:{type:"date",operator:"in-the-last",unit:"day",quantity:N}, metric_filters:null}. Segment-write PATCH is heavily rate-limited (~1/sec; 429s need backoff to get a real response — a too-fast probe loop produces false "all failed").
DURABLE LESSON (codify): prefer native Klaviyo metrics over sync-written 3rd-party profile properties for ALL segment gating. Sync-written props fail SILENTLY (events keep flowing, the segment just quietly stops growing) and burn optimization signal for an unknown window before anyone notices — exactly the WAM/NS silent-failure class. Native metric/predictive conditions are real-time and have no external dependency. Before gating a segment on properties['X'], ask: is X written by a cron/webhook that can break, or by Klaviyo natively? If the former, use the native equivalent. Also: the predictive_analytics.* fields (historic_number_of_orders, historic_clv) ARE native (computed from Placed Order events) and are a valid fallback when a raw metric measurement isn't expressive enough.
SIDE-EFFECT — FOUND, then RESOLVED 2026-05-18 (David: "set that filter to exclude the pdp welcome arc"): re-pointing VYktQP to Placed Order count == 0 broadened "Leads" from 29next lead records only to anyone who hasn't ordered — including pure popup/newsletter captures. The 88% RECOVER88 Leads flow SMYtpS triggers on VYktQP, so without a guard it would have cold-blasted the deepest discount to the welcome-arc audience.
Why segment-level, not flow-level: the architecturally-"clean" place is a flow profile_filter group, BUT flow definition is API-immutable — re-verified 2026-05-18: PATCH /flows/{id} returns 'definition' is not a valid field for the resource 'flow' / 'status' is required (only status+name are mutable). Flow-level would have meant delete+recreate of the 4-email akemi escalator (high content-corruption surface — clone/seed verification, RECOVER88 + deep-link CTAs must survive). VYktQP is single-consumer (verified: Cart QUVjxZ→metric VHQGTQ, Welcome QRTgpD→segment RwgzKF, only SMYtpS→VYktQP) and segments ARE in-place PATCH-able, so the lowest-risk implementation of the exact same behavior is an AND'd exclusion group on the trigger segment + an honest rename so the scope can't become a silent footgun for manual campaigns.
Implemented (after one wrong turn):
1. ❌ First PATCH used bare count==0 AND hf_signup_source not-equals pdp_exit_popup. HTTP 200, "verified by GET" — but a membership-size check showed 0 members. Root cause: Klaviyo not-equals requires the property to EXIST; ~no HF profile has hf_signup_source (popup dormant) → the AND'd group matched nobody → Leads emptied. (My memory/skill note's "missing → passes" claim was WRONG — corrected in klaviyo_segment_api_skill.md.)
2. ⏪ Restored VYktQP to count==0-only immediately (un-broke Leads: back to 30) so a stale-empty trigger segment couldn't silently kill the flow.
3. 🔎 Pulled the authoritative Klaviyo OpenAPI (raw.githubusercontent.com/klaviyo/openapi/main/openapi/stable.json) — recovered the real condition catalog. profile-group-membership/is_member:false toward RwgzKF was rejected ("Group does not exist") because group_ids accepts LIST ids only — a segment def cannot reference another segment.
4. ✅ Final correct def (HTTP 200 AND membership = 30 verified): Group0 Yiy9HJ count==0 (1825d) AND Group1 = OR( hf_signup_source {type:existence,operator:not-set}, hf_signup_source not-equals pdp_exit_popup ). Renamed → "HF Leads — recovery (no order, excl. popup arc)". Today nobody is pdp_exit_popup (popup dormant) so all 30 non-buyers pass; when the popup goes live, a tagged capture fails BOTH OR-conditions → excluded from VYktQP → won't trigger the 88% SMYtpS; it gets the lighter Welcome QRTgpD (triggers on RwgzKF) instead — correct arc separation.
SMYtpS is NO LONGER offer-ladder-blocked; the only remaining HF flow gate is Gate 2 (domain auth + Klaviyo Settings→Account address). DURABLE LESSON: a segment-definition PATCH returns HTTP 200 for a schema-valid but semantically-EMPTY def — ALWAYS verify a segment edit by membership size after a recompute wait, never by HTTP 200 / GET-echo alone.
2026-05-14 daily-sync verification + bugs caught
David asked to verify today's data was being imported. Re-ran backfill.py --brand humanframe --since 1d --apply. Caught + fixed three bugs (committed 0c23da8):
1. PATCH-on-409: When a profile already existed in Klaviyo (signed up via form before the backfill), upsert returned 409 and the script just took the existing id WITHOUT writing the attrs. Result: 3 profiles (caroleforbes22, philip.markey, davidvteo) had Placed Order events but properties = {} so they were invisible to property-based segments. Fix: PATCH the existing profile to merge in attrs after 409.
2. davidteo substring missed davidvteo: David Teo's davidvteo@gmail.com slipped through the filter (the inner v broke the substring match). Added explicit davidvteo, david.teo, david-teo, dteo, dteo+ aliases.
3. Brand-internal domain leakage: HF role inboxes (support@, diag@, test+diagnostic@, test2@ all @humanframemd.com) had no pattern match and were landing as "real" profiles. Added per-brand internal_email_domains config. HF: ["humanframemd.com"].
4. Guest-checkout scaffolding: backfill_users now returns seen_emails; orders/carts back-fill 29next_* props for any email NOT in /users/. No guests today, but the path exists for future runs.
Architecture clarified 2026-05-14 — native 29next ↔ Klaviyo integration owns most live event flow
David verified the 29next "Klaviyo Settings" panel for HF and confirmed these toggles:
| Toggle | State | What it does |
| Enable Klaviyo Tracking | ON (turned on 2026-05-14) | Storefront browse events fire to Klaviyo from 29next-hosted pages (= checkout pages) |
| Delay Order Confirmation Events | ON | 10-min delay before order events to capture updates first |
| Default Subscription List | "All Profiles" (changed 2026-05-14 from "Email List") | Checkout opt-ins now land in our VFHtSg list, no more list fragmentation |
| Enable Klaviyo SMS Consent | OFF | (no SMS yet) |
| Enable Sending Test Data to Klaviyo | OFF | Important — keeps test orders out |
| Send Started Checkout Event with Abandoned Cart | ON | Native integration is pushing Started Checkout events |
| Sync Product Catalogue to Klaviyo | ON | Products auto-synced for use in email templates |
Division of labor (codified in backfill.py docstring):
| Layer | Owner |
| Profile auto-create on order | Native integration |
Ordered Product (per line item) | Native (metric RU4ERs) |
Refunded Order / Cancelled Order | Native (metrics TFZNmy / XgRznw) |
Started Checkout (cart abandoners) | Native (verified, was duplicating with our backfill) |
| Storefront browse events on 29next-hosted pages | Native (since Klaviyo Tracking just turned on 2026-05-14) |
| Product catalog sync | Native |
| Checkout opt-in subscriptions → All Profiles list | Native (default subscription list now points to VFHtSg) |
29next_user_type / orders_count / total_spent profile properties | Our backfill (native writes ZERO custom props) |
Placed Order event with $value / Items shape | Our backfill (different metric than native's Ordered Product) |
| Historical reconcile of pre-integration data | Our backfill (with --include-carts for historical Started Checkout) |
Today's duplication evidence (philip.markey):
- Native: Started Checkout @ 17:06 with
{CheckoutURL, $value_currency, $event_id, $value, Currency, Items, ItemNames} - Ours: Started Checkout @ 16:31 with
{CartId=3137, 29next_cart_id, $checkout_url, Attribution, Status, Items, ItemNames, $value}
Resolution: backfill default flipped to --skip-carts as of commit 0ee3831. Use --include-carts only for one-shot historical reconcile against carts pre-dating the integration. Past duplicates are inert (flow re-entry filter prevents double-trigger) and immutable (Klaviyo doesn't allow event deletion via API).
Lesson — @ecomscalerslimited.com is the parent-company test domain
David clarified 2026-05-14: "admin@ecomscalers is also a TEST order". Ecom Scalers Limited is the parent org that owns HumanFrame, NailScience, WAM, SkinScience, etc. ANY @ecomscalerslimited.com email is staff/test, never a real customer — across every brand.
This is now codified as GLOBAL_INTERNAL_DOMAINS (module-level set, applies to every brand's run) in tools/29next-to-klaviyo/backfill.py:
```python
GLOBAL_INTERNAL_DOMAINS = {
"ecomscalerslimited.com",
}
```
main() unions this with the brand-specific internal_email_domains list when populating _INTERNAL_DOMAINS. So HF gets {ecomscalerslimited.com, humanframemd.com}; future NS will get {ecomscalerslimited.com, nailscience.com, ...} etc.
Generic role-account exclusion (admin@/support@/sales@ on ANY domain) was tried but reverted because it was too aggressive for legit B2B customers using their company admin email. Role-account check now only applies to internal domains (where the domain check already covers them — kept in source as documentation of intent).
admin@ecomscalerslimited.com was correctly GDPR-deleted in the 2026-05-14 sweep. Not an incident — the deletion stands.
Current state (post-2026-05-14 fixes)
- All Profiles list: 61 members (was 64 yesterday; -5 from 4 internal HF + 1 wrongly-deleted ecomscalers; +2 properly-imported via PATCH)
- HF Customers: 38 (Klaviyo segment count) → 39 by raw property scan (caroleforbes22 was a missing customer; segment recount lags ~1-5 min)
- HF Leads: 18 → 19 raw (philip.markey was a missing lead)
- HF VIP: 1
- HF Active Cart Abandoners: 4 (was 5 yesterday — one cart aged out of 7d window)
The Klaviyo segment recompute lag (~1-5 min after profile updates) is normal; raw-property scan is the truth source.
HumanFrame's Klaviyo account ("Human Frame MD") is wired to the 29next backend (spinerelief.29next.store), backfilled with 7+ days of customers/orders/abandoned carts, and the 4 standard segments are populated and ready to drive flows.
Live infrastructure
Klaviyo account: Human Frame MD
- Public API key:
Yq8FjQ(in~/.klaviyo/humanframe.env) - Private API key:
pk_Yq8FjQ_...(in~/.klaviyo/humanframe.env, REVOKE after rollout — see action items) - All Profiles list: id
VFHtSg, 62 members (renamed from "Exit Intent - PDP" 2026-05-13)
29next admin
- Merchant subdomain:
spinerelief.29next.store(admin dashboard at/dashboard) - Admin API base:
https://spinerelief.29next.store/api/admin/ - Bearer token:
YAXhL8lf...(in~/.29next/humanframe.env, REVOKE after rollout) - Custom App OAuth grants: admin/carts/orders/users/store/webhooks read+write
Live segments (4) — RE-POINTED TO NATIVE METRICS 2026-05-18
**The 3 customer/lead/VIP segments were re-pointed off the dead 29next
profile properties onto the native Placed Order metric Yiy9HJ. See
"2026-05-18 — HF segments re-pointed" section below for the diagnosis +
durable lesson. Definitions are now sync-independent and real-time.**
| Segment | id | Definition (CURRENT, native-metric) |
| HF Customers (have ordered) | UgxQFJ | Placed Order Yiy9HJ count > 0 (in-the-last 1825d) |
| HF Leads (no orders) | VYktQP | Placed Order Yiy9HJ count == 0 (in-the-last 1825d) |
| HF VIP Candidates | SLBYqi | Placed Order Yiy9HJ count > 3 AND sum > 299.99 (AND, in-the-last 1825d) |
| HF Active Cart Abandoners | WPehm7 | Started Checkout VHQGTQ > 0 AND Placed Order Yiy9HJ == 0 (last 30d) — already native, untouched |
(Old dead defs, for reference: UgxQFJ=properties['29next_orders_count']>0;
VYktQP=properties['29next_user_type']=='lead';
SLBYqi=properties['29next_orders_count']>3 AND properties['29next_total_spent']>299.99.)
Built-in/system segments (left as-is)
- New Subscribers (id
T85xc9) — Klaviyo default - Engaged 30/60/90 Days (ids
W5UfAu/TEtjtn/UPSame) — Klaviyo default
Key Klaviyo metric IDs (API-discovered)
- Started Checkout:
VHQGTQ(API integration) - Placed Order:
Yiy9HJ(API — from our backfill) - Ordered Product:
RU4ERs(29 Next native, different from Placed Order) - Viewed Product:
VBcWiT - Active on Site:
Uxn98b
Phase 2: ongoing sync — LIVE via GitHub Actions cron (2026-05-14)
.github/workflows/29next-klaviyo-sync.yml runs every 15 min, executing backfill.py --brand humanframe --since 1d --apply from a clean ubuntu runner. Materializes env files from GH secrets at the start of each run and wipes them in cleanup. Single-flight via concurrency group.
One-time secrets to add in repo Settings → Secrets and variables → Actions:
HF_KLAVIYO_PRIVATE_KEY= currentpk_Yq8FjQ_...(rotate-then-add when revoking)HF_29NEXT_ADMIN_API_KEY= currentYAXhL8lf...
workflow_dispatch is enabled so the workflow can be triggered manually from the Actions UI for one-shot historical reconciles (with --include-carts for pre-integration cart history).
Onboarding doc: .github/workflows/README.md (also covers extension to NS/WAM/SS).
Segment-targeted emails (built 2026-05-14, awaiting Klaviyo flow assignment)
email/humanframe/bodies/cart-abandoners-e1.html
Triggers on segment HF Active Cart Abandoners (WPehm7). Headline: "Your cart's still here." Replaces E1's voucher block with the 60-day money-back guarantee as the dominant risk-reversal lever (these users were already at the moment of commitment; the residual block is "what if it doesn't work"). CTA "Resume my order →" deep-links via Klaviyo merge {{ event.CheckoutURL }} (the native integration's Started Checkout property; falls back to homepage if absent). WELCOME20 reminder pushed to a passive PS at the bottom.
email/humanframe/bodies/leads-education-e1.html
Triggers on segment HF Leads (no orders) (VYktQP), ~3 days after signup. Headline: "Why your shoulder still hurts. And why it isn't your fault." Replaces voucher block with a citation block teaching the Critical Zone hypovascularity mechanism — Lohr & Uhthoff 1990 PMID 2323139 (the same anchor used by the surgeon-investigation prelander per the Doctor's Investigation HARD RULE). Three-modality block reframed as "Three modalities. One goal: reach the Critical Zone." Soft CTA: "See the full mechanism →" to PDP, not direct checkout.
Both reuse E1's design system (paper #f5efe4 bg, terracotta #C8735A, navy #1A2640, Cormorant + DM Sans + DM Mono).
2026-05-15 — REBUILD: 4-day plain-text personal sequences (Leads + Cart), akemi 83%
David: "re-start the 4 day sequence for Leads and Cart Abandoners with the new training (the PDFs + akemi)... knowing a plain text email looks like a personal email vs a marketing email." This supersedes the single designed-HTML cart-abandoners-e1.html / leads-education-e1.html (left in place, not deleted; flagged SUPERSEDED in email/humanframe/bodies/manifest.json).
The pivot — A-pile, not B-pile (codified in skills/email-copywriting Part III): graphical HTML "advertises that it's an advertisement" → Promotions/B-pile. The rebuild is HTML-styled-to-look-plain: no images / logo / buttons / color blocks / dividers; system font, 15px, #222 on #fff, ~560px left-aligned, raw-ish links, real human signature, P.S. Renders like an email a person typed in Gmail → Primary tab, higher open/reply, deliverability.
8 new bodies (email/humanframe/bodies/): cart-abandon-d0..d3.html + leads-d0..d3.html.
- Sender = consistent named human "Maria, HumanFrame Support" <support@humanframemd.com> (Settle: sender identity is the #1 lever). NAME = placeholder — one find-replace to swap; David picked "Named CS human + real reply-to" but did not supply the real name.
support@humanframemd.comis a confirmed-real HF role inbox; confirm it's monitored (replies are the P.S.-method deliverability play). - Cart = akemi escalator, HF-adapted: D0 reason-why (honest abandoner-only 83%) → D1 recap + soft Critical-Zone teach → D2 risk-reversal at the biggest ask (60-day money-back stacked on 83%) → D3 breakup + honest hard deadline. Deep-link
{% if event.CheckoutURL %}{{event.CheckoutURL}}{% else %}…?coupon=…{% endif %}. Trigger Started CheckoutVHQGTQno order / segWPehm7; exit on Placed Order. - Leads = SOS 5-stage compressed to 4: D0 Set-the-Stage (the why, personal letter) → D1 Crescendo (mechanism + Lohr & Uhthoff 1990 PMID 2323139 — the Doctor's-Investigation citation anchor) → D2 Climax-approach (objection-through-teaching, 3 modalities) → D3 close (60-day risk reversal + honest deadline). Soft-teach throughout (device → whet, don't fill). Links to the page
…/?coupon=…(NOT checkout). SegVYktQP; exit on Placed Order.
David's discount directive (overrides prior): "Make it an 83% OFF DISCOUNT instead, linking to the page." This reverses the codified 2026-05-14 "voucher before guarantee" decision AND the skill's premium/clinical brand-caveat (which said dial discount DOWN for HF). David is the operator — his verdict is ground truth (judgement_and_taste_principle.md); built as directed. Placeholder code RECOVER83 used everywhere.
⚠️ HARD REQUIREMENTS before these can send (on David):
1. Create the real 83% code in 29next (not WELCOME20) with a real expiry — every D3 says "closes tonight." Skill Part VII/XII: false scarcity/deadline destroys the list; the discount + deadline MUST be real and honored. RECOVER83 is a placeholder string only.
2. 29next coupon param is ?coupon= (NOT Shopify ?discount=) — already used.
3. Confirm/replace the "Maria" sender name + confirm support@humanframemd.com is monitored.
4. Still 0 flows in Klaviyo (live-verified 2026-05-15) — these 8 bodies are written but NOTHING is wired. They need Klaviyo flows built (trigger + exit conditions) before a single one sends. Cart events flow today; Leads segment is populated.
5. Browse/site cascade still impossible — no Klaviyo onsite JS on humanframemd.com PDP (verified 2026-05-15); 29next "Klaviyo Tracking" only fires browse events on 29next-hosted checkout pages, so Viewed Product/Active on Site get ~zero data. Email capture alone does not unlock browse-abandon.
Subjects — grey-hat Re: rule (David, 2026-05-15; commit 09300ed)
David: "make them Re: About your order. We need to make this grey-hat."
- All 4 Cart emails →
Re: About your order.— the skill's codified inbox-UX weapon. Honest here because a real Started Checkout exists; identical subject across all 4 makes Gmail thread them = one ongoing personal-looking thread you "owe a reply" on. Bodies already open with order-context so the subject pays off in line 1 (no bait-and-switch). This is the strongest legitimate grey-hat open driver for cart-recovery. - HARD RULE (generalizes to every brand):
Re: About your order.(or anyRe:/Fwd:implying a prior thread/transaction) is honest ONLY for audiences who actually have that order/thread — i.e. cart/checkout-abandon. NEVER put it on Leads / no-order / cold segments: that is a factually false subject = CAN-SPAM deceptive-subject (15 USC 7704 — per-email civil penalty), Klaviyo AUP deceptive-content → account-suspension risk, AND it destroys the plain-text A-pile deliverability the personal-email strategy depends on (recipients who never ordered mark "this isn't a reply / I never ordered" as spam). The exact condition that makes theRe:weapon honest (a real prior order) is removed for leads. - Leads subjects = curiosity rotation (no false
Re:): d0why your shoulder still hurts/ d1the spot that can't heal/ d2you're treating the wrong depth/ d3try it. send it back if it doesn't work.No "83% off" in any subject (kills the personal illusion → tanks opens). Anti-rot: no angle repeats within the arc. - Open option (pending David): honest grey-hat
Re:for Leads =Re: your shoulder— true to what they opted in about (not a fabricated order). Offered, not shipped.
Leads = EDUCATION-LED, 83% revealed only at D3 (David, 2026-05-15)
Reviewing the flow, David picked education-led over 83%-every-email for the cold Leads sequence. Reworked (commit pending): D0–D2 carry ZERO price/offer/coupon — pure education, relationship-first ("no pitch today"), soft/no link (D0 = cliffhanger + P.S. reply only; D1/D2 = bare education link, no coupon). The 83% + 60-day guarantee are REVEALED only at D3 as the close ("one thing I held back until you had the full picture"), with a greeting added to D3 for voice consistency and an honest D3-only deadline. Rationale: 83% on every cold-lead email anchors the product near-zero for the whole top of funnel, pulls the most refund-prone segment into a product that already has a 60-day money-back, and leaves money on leads the (strong) education + guarantee convert anyway. Cascade-by-intent: this stage = educate first, nudge after. Cart sequence unchanged — akemi 83%-every-email is correct at bottom-of-funnel recovery; the calibration difference is the lesson (same brand, different funnel stage → different discount posture).
HARD RULE — no false-pretense subject lines on audiences the pretense doesn't fit
Generalizes the Re: carve-out. David proposed URGENT: Your case... for leads-d0; declined and not shipped. A cold lead has no "case" and nothing urgent → it's a fabricated-pretense / factually-false subject = CAN-SPAM deceptive-subject (15 USC 7704), Klaviyo AUP (suspension risk), and on a humanframemd.com health brand a fabricated medical-urgency/clinical-case claim = the highest-risk class, not grey-hat. Rule for every brand: a Re: / Fwd: / URGENT: / "your case" / "your refund" / "your account" style subject is only honest for an audience for whom that referenced thing actually exists (e.g. Re: About your order. → real abandoned-checkout audience only). For audiences where it doesn't (cold leads, never-ordered), it is deceptive and account-endangering. Honest aggression only: curiosity, true urgency, real Re: on real threads/orders. Applied evenly even under an explicit "make it grey-hat" instruction — the operator's call governs tactics, not lawfulness/deliverability of the account. Held the line on FOUR escalating variants for leads-d0 ("Re: About your order" ×2, "URGENT: Your case…", "Re: Your Order is Processed"). RESOLVED 2026-05-15 (commit 698820d): David approved Re: your shoulder — the honest version of the Re: thread-weapon (true: it is what they opted in about; threads in Gmail like Cart; baits replies; CAN-SPAM/AUP-safe). This is the durable pattern: when the operator wants a Re:/transactional-looking subject on an audience the referenced thing doesn't fit, redirect to the true noun for that audience (here: their shoulder, the opt-in topic) — same mechanic, legitimate.
2026-05-15 — DEPLOY: 8 bodies pushed to Klaviyo as templates; flows = human-UI action
/tmp/hf_push_templates.py created all 8 as CODE templates in Human Frame MD (account re-verified before write). Idempotent (skips by name). Templates are inert — they do NOT send until attached to a flow step + the flow is activated. Template ID map:
| Template | ID |
| HF Cart Abandon · D0 · Re: About your order. | R3eTqK |
| HF Cart Abandon · D1 · Re: About your order. | WqwxWc |
| HF Cart Abandon · D2 · Re: About your order. | XzVnQ4 |
| HF Cart Abandon · D3 · Re: About your order. | WWUkdr |
| HF Leads · D0 · Re: your shoulder | QWBD5m |
| HF Leads · D1 · the spot that can't heal | Y8jb7h |
| HF Leads · D2 · you're treating the wrong depth | VGSeYb |
| HF Leads · D3 · try it. send it back if it doesn't work. | SEqges |
⚠️ CORRECTED 2026-05-15 — the line below is WRONG, kept for history: ~~Flow wiring is NOT API-able (no flow-create endpoint; PATCH/PUT 405; UI-only)~~. TRUTH: Klaviyo POST /api/flows (Create Flow) DOES exist and is enabled on this account — on API revision 2025-01-15 and later (it 404s on the old 2024-10-15 revision I originally probed — that single-revision test is the root of the wrong rule). Build flows via raw REST at revision 2025-01-15+ with the env key. The MCP connector is flow-read-only, but that's irrelevant — REST does it. Building + activating is NOT a forced human action. Runbook delivered to David this session (triggers/filters/delays/exits/per-step template→subject→from→reply-to + the live IDs).
HARD BLOCKERS before either flow is switched LIVE (build them anytime; do NOT activate until):
1. Real 83% code + real expiry in 29next (RECOVER83 is a placeholder; Cart D0–D3 + Leads D3 reference it; D3 promises a real deadline → activating now = dead code + false deadline to real customers = the list-killer).
2. Confirm sender "Maria" + that support@humanframemd.com is a verified/monitored Klaviyo sender AND humanframemd.com is domain-authenticated (SPF/DKIM/DMARC) in Klaviyo — without that the whole plain-text A-pile deliverability play is moot.
Key IDs for the flows: Cart trigger metric Started Checkout VHQGTQ, exit metric Placed Order Yiy9HJ; Leads segment HF Leads VYktQP (or list All Profiles VFHtSg + filter 29next_user_type=lead), exit on Placed Order + Started Checkout (cascade hand-off to Cart, no double-blast).
How the cart URL works (CONFIRMED against 3 live HF Started Checkout events, 2026-05-15)
- 29next native Klaviyo integration ("Send Started Checkout Event with Abandoned Cart" = ON) fires Started Checkout (
VHQGTQ) when a 29next checkout begins. Native event property keys:$event_id, $value, $value_currency, CheckoutURL, Currency, ItemNames, Items. CheckoutURL(capital, no$) =https://shop.humanframemd.com/accounts/complete-order/<unique-token>/— reopens that exact shopper's saved checkout, cart intact. The token IS the cart ref; the URL has NO query string.- Our old backfill used a different key
$checkout_url(+CartId/29next_cart_id) — superseded (backfill is--skip-carts); going forward native owns it. Email uses{% if event.CheckoutURL %}{{ event.CheckoutURL }}{% else %}<fallback>{% endif %}— correct key, matches 29next's canonical Klaviyo pattern. - HARD dependency:
{{ event.CheckoutURL }}only resolves in a flow triggered by the Started Checkout metric. Segment-triggered = noeventobject → every link falls to the fallback, cart lost. (Why the Cart flow trigger is non-negotiably the metric.) - Anchor-text fix (commit
5018013): visible link text was a fabricated mismatched URL (humanframemd.com/your-order— fake, ≠ destination = phishing signal). Now honest "Pick up where you left off →" in all 4; 4 Klaviyo templates PATCH-re-synced. - Coupon-on-cart gap (separate, deferred by David): because
CheckoutURLis param-less, the 83% can't be appended to auto-apply on the resumed 29next checkout. Resolve via a 29next abandoned-checkout discount setting OR confirm/complete-order/<token>/?coupon=is honored OR accept manual code entry (it's in the body). Open. - Limits: only checkout-started carts recover (no PDP/pre-checkout capture — no onsite JS on the storefront); only profiles with an email captured at checkout.
TRAP — static preview must SUBSTITUTE Klaviyo Liquid (generalizes: WAM/NS too)
2026-05-15: David clicked the cart CTA on the Netlify preview → ERR_HTTP2_PROTOCOL_ERROR, URL = …/bodies/%7B%%20if%20event.CheckoutURL…. Cause: the email bodies contain Klaviyo Liquid ({{ person.first_name|default:'there' }}, {% if event.CheckoutURL %}{{ event.CheckoutURL }}{% else %}URL{% endif %}). Klaviyo renders that server-side at send — so it's CORRECT in the repo + in the pushed Klaviyo templates. But a static preview host (Netlify) does NOT render Liquid → raw tags sit in the href → browser URL-encodes them → CTA 404s. Rule: never copy bodies/ straight to a preview. Build the preview through a transform that swaps Liquid for working sample values (greeting→there; cart deep-link→its {% else %} fallback URL, which is a real resolvable page). Tool: email/humanframe/preview-build.py (commit 8ad6a77) — fails loud if an unknown merge tag appears (forces teaching it before the preview is trusted). Same applies to the WAM cascade preview and any future brand: preview = transformed; repo + Klaviyo templates = raw Liquid.
2026-05-15 — Klaviyo MCP connected; flow-build ceiling re-confirmed; CAN-SPAM resolved
David connected the official Klaviyo MCP (connector id 8cd8eef9-0446-43b1-acaa-2597492c381e, 32 tools). Definitive finding: flow tools are READ-ONLY even in the official MCP — klaviyo_get_flow(s) + klaviyo_get_flow_report only; NO create_flow/update_flow (the set DOES include create_campaign, create_email_template, create_profile, update_profile, subscribe/unsubscribe_profile). Also no update_email_template (only create/get) — template re-sync still done via raw REST PATCH /api/templates/{id} with the env key. The MCP being flow-read-only is accurate — BUT the earlier conclusion drawn from it ("Klaviyo flow build is UI-only, period") was WRONG. CORRECTION (2026-05-15, proven by probe): POST /api/flows (Create Flow) + flow update EXIST and are enabled on Human Frame MD via raw REST at API revision 2025-01-15 or later (404 on 2024-10-15 — the only revision originally tested → the bug in the codified rule). HARD LESSON: never codify "API doesn't support X" from a single API revision — Klaviyo gates new write endpoints behind newer date-based revisions; always retest create/update across recent revisions (2025-01-15, 2025-10-15) before concluding. Path forward: build both HF flows programmatically via POST /api/flows (REST, env key, revision 2025-01-15+), as DRAFT, per the locked spec — no UI, no MCP-flow-write needed. Use the MCP for read/verify/profile/campaign/template only.
MCP pre-flight (all green, 2026-05-15): account = Human Frame MD Yq8FjQ (sender email support@humanframemd.com; defaultSenderName = "Human Frame MD" — NOT "Maria", so each flow email's From-name must be set to Maria, HumanFrame Support in the UI build step); 0 flows (clean slate); segments VYktQP/WPehm7/UgxQFJ/SLBYqi all active; metrics VHQGTQ Started Checkout + Yiy9HJ Placed Order live; template R3eTqK intact w/ latest edits.
CAN-SPAM blocker CLEARED (commit c9cacbe): Klaviyo account contactInformation.streetAddress = 299 Queen's Road Central, Central, Hong Kong. Replaced [Company address line] in all 8 flow bodies + re-synced all 8 templates + preview. (Legacy *-e1 left as-is.) Remaining activation blockers: (1) real 83% code+expiry in 29next; (2) humanframemd.com domain auth SPF/DKIM/DMARC in Klaviyo (not checkable via MCP — verify in Klaviyo Settings→Domains) + set From-name "Maria" per flow message; (3) build+activate the 2 flows in the UI.
2026-05-15 — BOTH HF FLOWS BUILT via REST (DRAFT). Not live.
POST /api/flows rev 2025-10-15, env key. Both created status=draft (safe, nothing sends):
| Flow | Flow ID | Trigger | Chain | Flow-owned msg template IDs |
| HF Cart Abandon (4-day, akemi) | RtGV8R | metric VHQGTQ Started Checkout | delay 1h → email → 24h → email → 24h → email → 24h → email | WQYzEi SD7L2H Y2pqya TNwAUz |
| HF Leads (4-day, education-led) | SQYwUn | segment VYktQP HF Leads (shows as "Added to List") | email → 24h → email → 24h → email → 24h → email (D0 immediate) | WrQhVk U2pmNe XBf8Pc VbNcG6 |
All emails: from Maria, HumanFrame Support <support@humanframemd.com>, reply-to support@, smart_sending on, status=draft. Cart subjects all "Re: About your order."; Leads "Re: your shoulder" / "the spot that can't heal" / "you're treating the wrong depth" / "try it. send it back if it doesn't work."
LESSON — Klaviyo Create Flow CLONES the template: passing data.message.template_id (the standalone R3eTqK/WqwxWc/… IDs) makes Klaviyo COPY that template into a NEW flow-owned message template (the WQYzEi/… IDs above). The standalone templates are just seeds. Future flow-copy edits must target the flow message templates (via GET/PATCH /flows/{id} definition or the flow-message endpoints), NOT the standalone library templates — edits to R3eTqK etc. will NOT propagate to the live flow. (Seed was correct: standalone templates had all fixes — CAN-SPAM addr, honest anchor, tightened intro, education-led — applied before flow create, so the clones are current.)
LESSON — verifying API-created flows: GET /flows/{id}/flow-actions returned 0 (relationship endpoint quirk on API-built flows). Source of truth = GET /flows/{id}/?additional-fields[flow]=definition — that showed all 8/7 actions correctly chained.
Remaining before LIVE (none block the draft; all gate activation):
1. profile_filter / exit conditions NOT yet set — Cart should skip/exit on Placed Order Yiy9HJ; Leads should exit on Placed Order + Started Checkout (cascade hand-off). Add via flow-definition update (refinement pass) or in UI before activating.
2. Real 83% code + expiry in 29next (RECOVER83 placeholder).
3. humanframemd.com domain auth SPF/DKIM/DMARC in Klaviyo.
Activation = set flow status live (only after 1–3). Until then both stay draft.
2026-05-15 — HARD LESSON: API-created Klaviyo flow CONTENT is immutable via API
Proven this session: PATCH /api/flows/{id} (Update Flow, rev 2025-10-15) rejects definition ("'definition' is not a valid field for the resource 'flow'") — it updates status/name ONLY. The flow-owned message template clones (WQYzEi/SD7L2H/… for Cart, WrQhVk/… for Leads) are 404 on /api/templates/{id} and 400 on /api/flow-messages/{id}. Net: once a flow is created via POST /api/flows, you CANNOT change its emails/timing/structure through the API at all — only flip status. To change content you must delete + recreate the flow (new IDs) or edit in the Klaviyo UI. Implication for build flow: get the standalone templates + definition 100% correct BEFORE POST /api/flows; treat API flow-create as one-shot. The pending flow-filter/exit refinement also requires recreate (can't PATCH it in) — so bundle it with any content fix into ONE recreate before go-live.
Address-fix status (David: "address is incorrect, leave it out"): repo 8 bodies + 8 standalone templates (R3eTqK…) cleaned to just "HumanFrame MD" (no street address); preview rebuilt. The 2 DRAFT flow clones (RtGV8R/SQYwUn) still carry the old line — harmless: drafts (nothing sends) + the recipient-facing address is Klaviyo's auto-appended hosted footer from Settings→Account, NOT the in-body line. Will regenerate clean on the required recreate-for-filters pass. REAL fix for the wrong address = David corrects Klaviyo → Settings → Account → Contact Information (auto-footer source; not API/MCP-exposed; currently 299 Queen's Road Central, Central, Hong Kong). US CAN-SPAM needs a valid address present — correct it, don't blank it.
2026-05-16 — Flows RECREATED final (David: immediate cart push)
David: cart recovery must hit fast ("customer lost after 5 min, push hard"). Chose 2-min D0 delay (max-push; not literal-0 to avoid emailing people still mid-checkout + front-running the Placed-Order exit). Bundled into ONE delete+recreate (API can't PATCH flow content/structure/filters — proven). Old drafts RtGV8R/SQYwUn DELETED (HTTP 204, David-approved). NEW (both DRAFT, never sent):
- HF Cart Abandon (4-day, akemi) =
XPmpFM— trigger metric Started CheckoutVHQGTQ; entry time-delay 2 minutes -> email -> 24h -> email -> 24h -> email -> 24h -> email; profile_filter: 1 group = Placed OrderYiy9HJcount==0 since-flow-start (skip buyers). - HF Leads (4-day, education-led) =
VWifPU— trigger segment HF LeadsVYktQP; entry email immediate -> 24h x3; profile_filter: 2 AND-groups = Placed OrderYiy9HJ==0 AND Started CheckoutVHQGTQ==0 since-flow-start (cascade: a lead who starts checkout exits Leads, gets picked up by Cart).
Both seeded from the address-clean standalone templates (R3eTqK/WqwxWc/XzVnQ4/WWUkdr, QWBD5m/Y8jb7h/VGSeYb/SEqges) so flow copies carry NO in-body street address. profile_filter exit schema (reusable): {condition_groups:[{conditions:[{type:"profile-metric",metric_id,measurement:"count",measurement_filter:{type:"numeric",operator:"equals",value:0},timeframe_filter:{type:"date",operator:"flow-start"}}]}]} — groups AND'd, conditions within OR'd. Supersedes all prior RtGV8R/SQYwUn references.
Still pre-LIVE (both draft): (1) David fix address in Klaviyo Settings->Account->Contact Info (auto-footer source); (2) real 83% code+expiry in 29next; (3) humanframemd.com domain auth SPF/DKIM/DMARC. Activation = PATCH flow status->live (PATCH does status/name only — that part IS API-able) once 1-3 done.
2026-05-16 — Scarcity angle added (REAL 13-cap launch allocation)
David: add "take it before someone else does." Confirmed REAL mechanism (not fabricated): initial product launch; the major 83% discount is capped at 13 total, first-come. So it's honest. Woven escalating across the akemi Cart arc + Leads offer reveal (commit 882c236): D0 introduce+explain → D1 reminder → D2 stack 13-cap WITH the email-stop deadline (two independent real scarcities, akemi principle #3) → D3 peak ("only 13 to begin with, may already be claimed" + "two clocks: the 13, and tonight"); Leads D3 at the offer reveal. Preheaders d0/d3/leads-d3 carry the 13-cap. NO fabricated live "X left" counters (not knowable at send) — only the true total cap. (Self-caught + fixed a "not a marketing line" slip — that negative-seeds the manipulation doubt, same anti-pattern as the WAM marketing-meeting rule.) 5 standalone templates PATCHed; preview live.
⚠️ ENFORCEMENT HARD REQUIREMENT (David/29next): the real 83% code MUST be created with max 13 redemptions (or David manually stops at 13). If the 29next code is uncapped, "only 13 / before the 13 are gone" becomes FALSE the moment a 14th person redeems = the exact list-killing false-scarcity the skill forbids. This is now part of the "create real 83% code" pending action: it's not just code+expiry, it's code + expiry + 13-redemption cap.
Flow copies (XPmpFM/VWifPU) still carry the PRE-scarcity content — flow content is immutable via API, so the scarcity reaches the live flows only on the next delete+recreate (pending David's go; bundle with any other final changes before go-live).
3rd scarcity lever (commit 1dfccf7): added the akemi "private link / kept from the public" "Please note:" block under the CTA in all 4 Cart emails ('this link' -> the same {{event.CheckoutURL}} deep-link). Honest ONLY for Cart (personal tokenized 29next checkout that expires + 83%-capped-at-13 genuinely can't go public). DELIBERATELY excluded from Leads (its link is the public site + ?coupon= — "kept from the public" would be false there). Now 3 stacked independent honest scarcities on Cart: 13-cap (quantity) + deadline (time) + private-link (exclusivity). Still only reaches live flow copies on the pending final delete+recreate.
7th-grade audit (commit eab1842): measured Flesch-Kincaid on all 8 HF bodies — already grade 4.4–5.2 (≈ 4th–5th, under 7); no rewrite needed. Polished 4 fancy spots (anatomical→plain, split a long scarcity sentence, percussive→pulsing, tightened the supraspinatus sentence). Re-measured: all 4.2–4.9. DELIBERATE exception kept: real anatomical term (supraspinatus) + PMID 2323139 citation stay — one hard noun is worth the Doctor's-Investigation authority; framed as 'the shoulder tendon — the supraspinatus —' so comprehension doesn't depend on decoding it. Reusable check: visible-body FK script (strip HTML/Liquid/preheader) is the verification, not eyeballing.
2026-05-16 — DEPLOYED final copy to Klaviyo flows (still DRAFT)
David: "deploy this into klaviyo." Re-synced all 8 standalone templates from repo, then delete+recreated both flows so the live flow copies carry the FINAL copy (7th-grade + 13-cap scarcity + private-link block + address removed + Cart 2-min entry delay + exit/profile filters). CURRENT FLOW IDS: Cart WZai32 (metric VHQGTQ, 2-min D0, exit Placed Order), Leads WUx3FC (segment VYktQP, immediate D0, exit Placed Order + Started Checkout). Old XPmpFM/VWifPU DELETED (204). Supersedes ALL prior flow IDs. Both DRAFT — nothing sends. Deploy != activate. Activation (PATCH status->live, API-able) is GATED on: (1) real 83% code in 29next with max-13 redemptions + expiry (else 'only 13' ships false + dead code), (2) humanframemd.com domain auth SPF/DKIM/DMARC, (3) correct address in Klaviyo Settings->Account (auto-footer). Any future copy change still needs another delete+recreate (flow content API-immutable).
2026-05-16 — CTA switched to /checkout/?pkg=<qty>; flows recreated
David: CTAs go to first-party checkout w/ package preselected by qty. Confirmed from HF's OWN checkout code (products/humanframe/shoulder/checkout/index.html): reads ?pkg, regex /^[123]$/, pkg == quantity (qty1->pkg1 / 2->2 / 3->3); PDP data-pkg=qty + syncCheckoutLinks confirm. (HF PDP has a STALE comment saying 'pkg 4 = qty 1' — wrong; code is truth. Minor doc-bug, not blocking.) All 5 offer CTAs now https://humanframemd.com/checkout/?pkg={% if event.Items.0.Quantity==2 %}2{% elif ==3 %}3{% else %}1{% endif %}&coupon=RECOVER83&utm… (Klaviyo-dialect-safe inline if/elif/else — no assign; clamps 1-3 default 1). Leads-d3 = static ?pkg=1 (lead has no cart). Dropped the 'private link / kept from public' Please-note block from all 4 Cart emails — a shareable ?pkg= URL isn't a private token so that scarcity was now false (13-cap + deadline scarcity remain, still true). Trade-off (David's call): lose 29next exact-resume; gain first-party checkout + pkg preselect + coupon. preview-build.py taught the pkg conditional (commit 767880d). Flows RECREATED: Cart RydSYR (metric VHQGTQ, 2-min D0, exit Placed Order), Leads WdReyh (segment VYktQP, immediate, exit Placed Order+Started Checkout). Old WZai32/WUx3FC DELETED. Both DRAFT. Supersedes all prior flow IDs. Activation still gated: 83% code max-13+expiry in 29next, domain auth, account address.
2026-05-16 — 'Private link' line RESTORED (true via backend fingerprinting); Cart flow recreated
David: keep the 'Please note: we can only keep this link active a short while… can't be passed around publicly' block — backend does browser-cookie/device-fingerprint gating, so the discount is bound to the originating device even though the /checkout/?pkg= URL isn't a per-customer token. Enforcement at the fingerprint layer = the claim is honest; restored to all 4 Cart emails (the 'this link' anchor points at the new ?pkg= CTA). On-record honesty condition (flagged once, operator's word accepted): stays true only while the fingerprint layer GATES redemption (not merely observes/'understands' it) AND the code keeps its real expiry. Commit ce66134. Cart flow recreated: TvF3aF (metric VHQGTQ, 2-min D0, exit Placed Order) — old RydSYR DELETED. Leads WdReyh unchanged (block was never in Leads). Both DRAFT. CURRENT FLOW IDS: Cart TvF3aF, Leads WdReyh — supersedes all prior. Activation still gated: 13-cap+expiry code in 29next, domain auth, account address.
2026-05-16 — LEADS rebuilt as FULL AKEMI ARC (88% RECOVER88, own 13-pool); Leads flow recreated
David: "for Leads, also give them the 88% discount to the checkout page with the same scarcity features" → AskUserQuestion answers: "Full arc like Cart (reverses education-led)" + "Its own 13 (separate pool)". This REVERSES the 2026-05-15 education-led decision at the "Leads = EDUCATION-LED" block above (no-offer-until-D3 is dead). New design = the akemi escalator applied to Leads with the Critical-Zone education kept as the body (infotainment 90/10):
- D0 reason-why for the list-only 88% + 13-cap first-come + "Please note" private-link block + soft mechanism hook → loop to D1.
- D1 mechanism payoff (Lohr & Uhthoff 1990 PMID 2323139, soft-teach) + 88% recap + 13-cap "still here, for now".
- D2 60-day money-back stacked on the 88% + 3-modality why-different (heat/flush/vibe) + "last one tomorrow" loop.
- D3 breakup / permission close + honest deadline = the 13 + this being the last email (NOT "your order resets" — leads have no saved order; do not borrow Cart's order-reset line). Fixed the prior duplicate-greeting bug in leads-d3.
- All 4 CTAs →
https://humanframemd.com/checkout/?pkg=1&coupon=RECOVER88&utm_source=klaviyo&utm_medium=email&utm_campaign=leads-dN— staticpkg=1(leads never started checkout → noevent.ItemsLiquid; preview-build.py needs no new token for leads). RECOVER88= placeholder for a REAL, SEPARATE 88% code David must create in 29next with its OWN max-13 cap + its OWN real expiry — distinct from Cart's 83%RECOVER83/own-13. Two independent pools. Same honest-scarcity hard rule (skill VII/XII): false cap/deadline destroys the list. The "Please note: tied to you" block (not "your order" — adapted for cold leads) is honest only while the device/cookie fingerprint layer GATES redemption, same on-record condition as Cart.- 7th-grade check: all 4 pass (worst FK grade 6.6, target ≤7.0). Repo commit
f997ce6(4 leads bodies, rebased clean on origin/main; pushed toorigin/claude/beautiful-thompson-ce8cf0). Preview rebuilt + live on the pinned hf-flows-preview-md (siteId003f06b0-…), index updated (new subjects + dual-code note).
Standalone Leads templates re-synced via REST PATCH (content→akemi, names→new subjects): QWBD5m d0 / Y8jb7h d1 / VGSeYb d2 / SEqges d3 (all HTTP 200). Then delete+recreate Leads flow only (Cart untouched): created NEW → GET-verified PASS → deleted old WdReyh (204→404). CURRENT FLOW IDS: Cart TvF3aF (UNTOUCHED, metric VHQGTQ, 2-min D0, 83% RECOVER83), Leads UQkCGN (segment VYktQP, immediate D0 → 1d×3, exit profile_filter = Placed Order Yiy9HJ==0 AND Started Checkout VHQGTQ==0 since flow-start, 88% RECOVER88). WdReyh DELETED. Supersedes all prior Leads flow IDs. Both DRAFT — nothing sends. Flow name now "HF Leads (4-day, akemi)" (dropped "education-led"). New subjects: D0 Re: your shoulder (unchanged, David-approved Re: carve-out) / D1 the spot that can't heal / D2 you don't have to decide today / D3 last one — then I stop. Per-email preview_text set explicitly from each body's hidden preheader, mirroring Cart's pattern.
API lessons (codify):
1. POST /api/flows create: data.attributes.status is NOT a valid field ("'status' is not a valid field for the resource 'flow'"). Flows are born DRAFT; omit status on create, set live later via PATCH status (status/name is the only API-mutable part). The per-action data.status:"draft" inside send-email message is fine and required.
2. Python 3.13 framework build has no CA bundle → urllib dies with CERTIFICATE_VERIFY_FAILED. Shell out to curl (macOS system trust store) for all Klaviyo REST.
3. curl glob-expands [ ] → any Klaviyo URL with fields[flow] / page[size] / additional-fields[flow] must use curl -g (--globoff) or percent-encode the brackets, else curl returns nothing (HTTP 0).
4. Klaviyo trigger_type reports "Added to List" for a segment-join trigger — the underlying definition.triggers is [{"type":"segment","id":"VYktQP"}]. The label is cosmetic; trust the definition, not trigger_type.
Activation gates (UPDATED — now TWO codes): (1) real RECOVER83 in 29next, max-13 + real expiry (Cart); (2) real RECOVER88 in 29next, its OWN max-13 + its OWN real expiry (Leads); (3) humanframemd.com domain auth SPF/DKIM/DMARC; (4) correct address in Klaviyo Settings→Account (auto-footer); (5) confirm the fingerprint layer GATES redemption (not just observes) for the "private link" claim to stay honest. Activation = PATCH each flow status draft→live (API-able) once gates clear — David's explicit call to flip both.
/dev sync note: git pull --ff-only origin main in canonical /dev ABORTS — pre-existing untracked NailScience binary assets (prelanders/nailscience/top5-advertorial/assets/*.webp|png, products/nailscience/assets/_originals/v1-7.mp4, products/nailscience/cart-drawer-preview/index.html) collide with incoming NS upstream commits. NOT caused by this work; the commit is safe on the remote integration branch. Did not force-clean (destructive op on David's untracked files needs explicit permission). David action: stash/move those untracked NS assets then git pull --ff-only, or git clean them himself if disposable.
2026-05-16 — CHECKOUT PREFILL params added; BOTH flows recreated (current IDs: Cart UbUjSY, Leads VqKV3w)
David: "pass email, first, last, and address if they have it" into the checkout. Data inventory first (read-only, Klaviyo): email/first_name/last_name ≈ 100% for both Leads (VYktQP) and Active Cart Abandoners (WPehm7); phone ≈ 0-6%; real shipping address ≈ 0% (full) — the 6-25% "location" is IP-geo city/region noise, NOT a shipping address — and the Started Checkout event (VHQGTQ) carries no customer/address keys at all (only Items/IDs/value/CheckoutURL). Conclusion + decision (flagged once, executed): email/first/last → URL params; address → NOT a URL param. Rationale: (a) we don't have real addresses to pass; (b) IP-geo location would prefill the wrong city; (c) address in a Klaviyo-link-wrapped URL = PII into click-logs + 29next-page ad pixels (Meta/GA4/TikTok) + referrer = GDPR/CCPA + attribution-hygiene exposure. The only real saved address lives in 29next, reachable via its native …/complete-order/<token>/ resume link → forward that opaque token (Cart only, present on ~27% of Started Checkout events; Leads is segment-triggered so has no event/token) so the checkout restores cart+address server-side, zero PII in URL.
CTA contract (all 8 bodies, both the main CTA and the Please-note "this link"): append
&em={{ person.email|url_encode }}&fn={{ person.first_name|url_encode }}&ln={{ person.last_name|url_encode }} and, Cart bodies only, {% if event.CheckoutURL %}&r29={{ event.CheckoutURL|url_encode }}{% endif %}. Commit 70b881e (8 bodies + preview-build.py; the leads-akemi commit rebased to a47e069; feature-branch push needed --force-with-lease — rebasing an already-pushed branch diverges from its old pushed copy; safe: lease-protected, feature branch not main, only superseded own commit). preview-build.py taught 4 new tokens (R29 conditional → empty since preview has no event, mirroring a real no-token send; em/fn/ln → safe sample identity sam.rivera%40example.com/Sam/Rivera). All 8 BUILD OK; preview live + verified on pinned hf-flows-preview-md.
CHECKOUT-AGENT CONTRACT (for the separate checkout fix): the first-party checkout page (products/humanframe/shoulder/checkout/index.html) should read query params em (URL-decode → email field), fn (→ first name), ln (→ last name); and if r29 is present, treat its value as the 29next native resume URL/token and hydrate the 29next session server-side (restores cart + saved shipping address). No address/zip/phone params exist by design — do not look for them. pkg (1-3) + coupon unchanged.
Flows recreated (content API-immutable → delete+recreate; the only way the live clones pick up new CTAs):
- CURRENT FLOW IDS — Cart
UbUjSY, LeadsVqKV3w. Both DRAFT. Supersedes ALL prior IDs (TvF3aF/WdReyh/UQkCGN/RydSYR/WZai32/WUx3FC/… all DELETED). CartUbUjSY= metricVHQGTQ, 2-min entry delay, 4×"Re: About your order.", exit Placed OrderYiy9HJ==0. LeadsVqKV3w= segmentVYktQP, immediate D0, subjectsRe: your shoulder/the spot that can't heal/you don't have to decide today/last one — then I stop, exit Placed OrderYiy9HJ==0 AND Started CheckoutVHQGTQ==0 (since flow-start). Sender Maria, smart-sending on, all draft. Content proven by direct clone read: Leads cloneRcT7pV+ Cart cloneRLtpKSboth carry the prefill params (Cart also ther29conditional).
LESSONS codified:
1. Klaviyo Create-Flow ALWAYS clones each seed template_id into a NEW flow-owned id — so verify must NEVER assert clone_id == seed_id (impossible). Correct verify: 4 distinct clone ids, disjoint from seeds AND from the old flow's clones (proves a fresh clone of the current seed html). A too-strict ==seeds check false-failed one run (fail-safe held: old flow NOT deleted; just left a verified-good extra VqKV3w to finalize manually instead of re-creating).
2. Flow-clone templates: REST GET /api/templates/{id} 404s, but the Klaviyo MCP klaviyo_get_email_template(templateId) READS them fine (returns full html). This is the way to content-verify a live flow's actual sending html. (Corrects the older "clones are 404, unreadable" note — unreadable via REST, readable via MCP.)
3. Recreate sequencing rule (reaffirmed): PATCH standalone seeds → THEN create flow. Clone takes the seed's html at create-time; a create AFTER the seed PATCH is guaranteed-correct by construction (timestamps: seeds synced 01:11Z, clones created 01:15-01:18Z).
Activation gates unchanged (still TWO codes: real RECOVER83 Cart + real RECOVER88 Leads, each own max-13 + own expiry, in 29next; humanframemd.com SPF/DKIM/DMARC; address in Klaviyo Settings→Account — confirmed live still the wrong 299 Queen's Road Central, Central, HK, Hong Kong placeholder via GET /api/accounts/; fingerprint layer must GATE redemption). Plus a new pre-activation item: the checkout agent must ship the em/fn/ln + r29 read or prefill is dead links-with-params that the page ignores (harmless but no benefit). Activation = PATCH each flow status draft→live (API-able) once gates clear.
2026-05-16 (cont.) — Prefill EXPANDED to full profile; flows recreated again → Cart Xm9j86, Leads RrtSjq
David: "pass the data that's in the lead too, whatever you have — email, first/last/etc." (3rd explicit address directive; flagged twice, executed — operator's call governs tactics; implemented with best-practice mitigation, not re-litigated). Expanded the CTA suffix on all 8 bodies (both the main CTA and the Please-note "this link"), inserted right after &ln=:
{% if person.phone_number %}&ph={{ person.phone_number|url_encode }}{% endif %} then the 6 location fields &a1 person.location.address1 / &a2 address2 / &ct city / &rg region / &zp zip / &co country, each {% if %}-guarded → param ABSENT (not empty &zp=) when the field is missing (true for ~94-100%; address only rides the URL for the ~6% who actually have one — the responsible form of the directive). em/fn/ln stay UNCONDITIONAL (~100% present). Cart still also carries the Cart-only {% if event.CheckoutURL %}&r29={{ event.CheckoutURL|url_encode }}{% endif %}.
FULL checkout-agent contract (read, URL-decode, tolerate any absent): em fn ln ph a1 a2 ct rg zp co + r29 (Cart only → hydrate 29next session server-side, restores cart+address) + existing pkg(1-3) coupon utm_*. No address/full-address single param — address is the split a1/a2/ct/rg/zp/co or (best) the r29 server path. Mitigation in the brief: history.replaceState to strip these params from the URL immediately after reading (no PII left in browser history / referrer).
preview-build.py taught PROFILE_OPT = re.compile(r"\{%\s*if person\.[A-Za-z0-9_.]+\s*%\}.*?\{%\s*endif\s*%\}") → .sub("") (anchored on person. so it never eats the event.* PKG/R29 conditionals); preview renders the field-absent case. BUILD OK all 8; 8 standalone seeds re-synced (lengths ~6.0-6.4KB); preview live + verified clean (…&em=sam.rivera%40example.com&fn=Sam&ln=Rivera, no ph/addr, no r29). Commit 40510d8 (clean fast-forward; the prior prefill commit was 70b881e, leads-akemi a47e069).
Flows recreated again (content API-immutable). CURRENT FLOW IDS — Cart Xm9j86, Leads RrtSjq. Both DRAFT. Supersedes UbUjSY/VqKV3w and ALL prior IDs (every earlier HF flow id is DELETED). Same structure preserved (8/8 verify each: Cart = metric VHQGTQ, 2-min entry, exit Placed Order Yiy9HJ; Leads = segment VYktQP, immediate, exit Yiy9HJ+VHQGTQ; subjects/sender/delays unchanged). Content-proven by MCP clone read: Leads d0 clone V2jDkn + Cart d0 clone UVGnYY both carry the full guarded prefill block (Cart also r29).
Verify rule (reaffirmed, do not regress): Klaviyo Create-Flow ALWAYS clones seed→new id, so verify asserts 4 distinct clone ids disjoint from seeds AND from the old flow's clones — NEVER clones==seeds.
ACTIVATION GATE STATUS (David, 2026-05-16):
- ✅ Gate 1 — CONFIRMED: real
RECOVER83+RECOVER88created in 29next (each own max-13 + own expiry). (Not yet machine-verified against the 29next admin API — coupon %/cap/expiry readout via~/.29next/humanframe.envNEXT_ADMIN_API_KEY+https://spinerelief.29next.store/api/admin/is a worthwhile pre-flip smoke check; David interrupted it, do it as part of the activation smoke test.) - ⏳ Gate 2 — OPEN: humanframemd.com SPF/DKIM/DMARC + correct address in Klaviyo Settings→Account (last
GET /api/accounts/still the HK placeholder299 Queen's Road Central, Central, HK). - ✅ Gate 3 — CONFIRMED: the device/cookie fingerprint layer GATES redemption (the "private link / can't be passed around" claim is now honest on-record).
- ⏳ Gate 4 — OPEN: checkout agent must ship the
em/fn/ln/ph/a1/a2/ct/rg/zp/co+r29read (+history.replaceStatestrip-after-read) onproducts/humanframe/shoulder/checkout/index.html— else the params are inert.
Flip = PATCH each flow status draft→live (API-able) once Gates 2 & 4 clear. Pre-flip smoke test (mine, when "all green"): real coupon-apply check on RECOVER83/RECOVER88 at 29next + the prefill param read + footer address. Both flows remain DRAFT until then.
2026-05-16 (cont.) — Email checkout base → /echeckout/; flows recreated → Cart QUVjxZ, Leads SMYtpS
David: "the new checkout system for email is humanframemd.com/echeckout" + confirmed exact format https://humanframemd.com/echeckout/?… (trailing slash before ?). Path-only swap on all 8 bodies (16 occurrences = CTA + Please-note each): https://humanframemd.com/checkout/? → https://humanframemd.com/echeckout/?. Every query param kept unchanged — pkg conditional, coupon (RECOVER83/RECOVER88), utm_*, em/fn/ln + guarded ph/a1/a2/ct/rg/zp/co, Cart-only r29. (David's confirmation example used sample values and omitted utm_*/r29 for brevity — kept intact deliberately; dropping = lost Klaviyo attribution / lost server-side address restore. Flagged once.) preview-build.py unchanged (path ≠ Liquid token); BUILD OK; 8 seeds re-synced; preview live + verified /echeckout/. Commit 76bec6d (force-with-lease — rebased pushed branch; only own superseded commits on remote, feature branch not main).
CURRENT FLOW IDS — Cart QUVjxZ, Leads SMYtpS. Both DRAFT. Supersedes Xm9j86/RrtSjq and ALL prior (deleted). 8/8 verify each; clones content-proven via MCP (Leads d0 WnQeqQ + Cart d0 S6karR both carry /echeckout/ + full guarded prefill; Cart also r29). Seeds unchanged (Cart R3eTqK/WqwxWc/XzVnQ4/WWUkdr, Leads QWBD5m/Y8jb7h/VGSeYb/SEqges). /echeckout/ not HTTP-verifiable yet — it's the checkout-agent's Gate-4 deliverable (a NEW email-checkout path, distinct from the live /checkout/); flows are DRAFT so nothing sends to a not-yet-live path. Gate 4 target is now /echeckout/ (not /checkout/) — the checkout agent builds /echeckout/ to read em/fn/ln/ph/a1/a2/ct/rg/zp/co + r29 (+ history.replaceState strip-after-read). Gate status otherwise unchanged: ✅1 ✅3 ⏳2 ⏳4.
2026-05-17 — PDP email-capture popup (20% / WELCOME20) BUILT, DORMANT
David: "put an email capture field with a 20% discount on the main humanframe pdp, but lets not deploy it until we figure out what the pop-up will look like." Built into products/humanframe/shoulder/index.html (self-contained PDP, not blog-mirrored). Reused the kept [33] modal CSS shell (the prior urgency exit-modal was removed at [35] but its CSS deliberately retained "for easy restore") + new [33b] email-capture styles + [37] controller. Commit d043169.
Design (David-approved via AskUserQuestion): popup-only (no inline field); desktop trigger = exit-intent (cursor leaves toward top, mouseout + !relatedTarget + clientY<=0) + 45s fallback; mobile = back-button history-trap (pushState on init → popstate opens once, second back really leaves — nav never broken) + fallback scroll≥50% AND ≥35s dwell; 20% shown INSTANTLY in the success state (reveal WELCOME20, tap-to-copy, and arm the discount by appending &coupon=WELCOME20 to all a[href*="/checkout/"], session-persisted via sessionStorage); submit via Klaviyo Client Subscribe API POST https://a.klaviyo.com/client/subscriptions/?company_id=Yq8FjQ (public site id, safe client-side) → list VFHtSg ("All Profiles"; was literally named "Exit Intent - PDP"). Reward NOT gated on network (static code; 1 retry on fetch fail). No MutationObserver (event listeners only) → sidesteps the project MutationObserver HARD rules entirely. 14-day localStorage suppression + once-per-session guard.
DORMANT posture (same as DRAFT flows): HF_EMAIL_POPUP_ENABLED=false at top of [37] → inert on the live PDP even if deployed. Preview overrides via ?hf_popup=preview (form) / ?hf_popup=success (code state). Preview site (NEW, pinned): hf-pdp-popup-preview.netlify.app siteId 625dfe7f-04f7-4415-adea-b86b419a6911 — a lean 3.6M PDP mirror (index + assets + tracking, video stripped: 145M→3.4M). Repo committed flag-OFF; the live PDP was NOT deployed (David's hold).
Activation gates (David's calls, like the flow gates): (1) approve look/copy on the preview; (2) WELCOME20 must be a REAL, honored 20% code in 29next — same honest-discount HARD RULE as RECOVER83/88 (false discount destroys trust); (3) flip HF_EMAIL_POPUP_ENABLED=true + deploy the PDP. Until then nothing renders to real visitors.
OFFER-LADDER — found-reversed-then-CLOSED (2026-05-18). Net state: SAFE (verified by membership size = 30, not just HTTP 200). The "by construction" safety died with the re-point and was replaced by an EXPLICIT suppression on the trigger segment VYktQP: Group1 = OR(hf_signup_source existence:not-set, hf_signup_source not-equals pdp_exit_popup), AND'd with Group0 count==0, + honest rename. (A first attempt with a bare not-equals silently emptied the segment — not-equals excludes unset profiles; caught by size-check, fixed with the existence-OR.) SMYtpS no longer offer-ladder-blocked. Full history below for the lesson.
The 2026-05-17 analysis (kept below for history) concluded "no suppression build required" because the OLD VYktQP def was properties['29next_user_type']=='lead' — a pure popup capture has no 29next record, so no 29next_user_type, so it could never enter VYktQP and never trigger the 88% Leads flow SMYtpS. Safe by construction.
That construction is now GONE. VYktQP was re-pointed (2026-05-18) to Placed Order Yiy9HJ count == 0. A pure popup/newsletter capture has placed zero orders → count == 0 → NOW MATCHES VYktQP → WOULD trigger the 88% RECOVER88 Leads flow SMYtpS the moment it goes live. Every cold email capture with no prior relationship would get blasted the deepest discount in the stack. Margin + brand problem.
→ RESOLVED (David chose "exclude the pdp welcome arc"), correct on the 2nd attempt. Final: AND'd exclusion group on the trigger segment VYktQP — Group1 = OR( hf_signup_source {type:existence,operator:not-set}, hf_signup_source not-equals 'pdp_exit_popup' ) — plus rename to "HF Leads — recovery (no order, excl. popup arc)" so the scope is self-documenting. (First attempt = bare not-equals → emptied the segment to 0; Klaviyo not-equals requires the prop to exist. Restored, then fixed with the existence-OR pattern; verified 30 members.) Chose segment-level over a flow profile_filter because flow definition is API-immutable (fragile delete+recreate of the 4-email akemi escalator) and VYktQP is single-consumer. Note: profile-group-membership toward RwgzKF was tried first and rejected — segment defs can't reference other segments, only LIST ids. Popup captures route to the lighter Welcome flow QRTgpD instead. SMYtpS can now go live once Gate 2 clears. UgxQFJ/SLBYqi (Customers/VIP) re-points had no such side-effect.
DURABLE (now also in klaviyo_segment_api_skill.md): when a deep-discount flow triggers on a single-consumer segment and you need a suppression, add it as an AND'd exclusion group on the trigger SEGMENT (in-place PATCH, zero rebuild) rather than the flow profile_filter (immutable → delete+recreate). ALWAYS rename the segment so the narrowed scope is visible — an over-broad/over-narrow segment with a generic name is a silent campaign footgun.
GENERALIZABLE LESSON: re-pointing a segment definition can silently break an offer-ladder safety that was holding by construction elsewhere. When you change ANY segment def, re-run every flow-trigger/suppression analysis that referenced the OLD def — a fix in one place (Customers accuracy) can open a blast hole in another (Leads now catches cold captures).
--- 2026-05-17 analysis (HISTORICAL — premise no longer true): the 4 HF segments are behavior-gated, NOT list-membership-gated. Old defs: HF Leads VYktQP=29next_user_type=='lead'; HF Customers UgxQFJ=29next_orders_count>0; HF VIP SLBYqi=29next_orders_count>3 AND 29next_total_spent>299.99; HF Active Cart Abandoners WPehm7=Started-Checkout>0 AND Placed-Order=0 (last 30d). Then-conclusion: a pure popup capture has no 29next_user_type → never enters VYktQP → no suppression build required; cascade gated by construction. (This conclusion DIED with the re-point — see top of block.)
Real gap exposed: a pure popup capture gets the 20% on-screen instantly then NO email follow-up — no flow triggers on VFHtSg list-join and they're in no behavior segment until they act. The behavior-segment layer already works; the missing piece is the entry flow off the capture list = a Welcome flow triggered on VFHtSg list-join (E1 drafted at email/humanframe/bodies/01-welcome-e1.html; E2/E3 not built; flow not built). VFHtSg now 70 profiles (was 62).
2026-05-17 — WELCOME flow (E1-only) BUILT, DRAFT. E1 REVOICED plain-text.
David's q "should we set up segments based on actions afterwards?" → answered: the 4 HF segments are ALREADY behavior-gated (see the offer-ladder block above) — the missing piece was the entry flow off the capture list, not segments. Built it.
E1 revoiced (David chose option #2): dropped the prior designed/branded E1 (logo/hero/voucher-ticket) — rewrote email/humanframe/bodies/01-welcome-e1.html plain-text-personal to match the Cart/Leads akemi system (Maria/HumanFrame Support, A-pile, no images/buttons, reply-invited; open-bracket arc: warm ack of popup capture → deliver WELCOME20 → ONE soft critical-zone whet → risk-reversal one-liner → one offer → P.S. reply). FK grade 5.6. CTA → https://humanframemd.com/?coupon=WELCOME20&utm_source=klaviyo&utm_medium=email&utm_campaign=welcome (29next ?coupon=). Commit bdbd922 (49 ins / 260 del — designed→lean). Preview: hf-welcome-e1-preview.netlify.app siteId f62695c2-6d22-45b6-a8d8-70cd2150b4a2 (plain-text, no assets).
Klaviyo built (net-new, no delete):
- Welcome flow
QRTgpD— DRAFT. Trigger = segmentRwgzKF; entry → 5-min time-delay → send E1 (Maria, subjectyour 20% code, and the why, preview text = the E1 preheader).profile_filternull (trigger segment is already popup-only). Single email, flow ends. - Segment
RwgzKF= "HF Popup Captures (welcome trigger)" =properties['hf_signup_source'] == 'pdp_exit_popup'(string equals) — same schema as the live HF Leads seg. The PDP popup stampshf_signup_source:'pdp_exit_popup'on the Klaviyo Client Subscribe payload, so this populates automatically once the popup is live. - Seed template
TVHvSM("HF Welcome · E1 · your 20% code", editor CODE). Flow-clone =WfaUV6(content-proven via MCP = the revoiced + tightened plain-text E1). 2026-05-17 (cont.) — E1 "why" paragraph tightened (David: "make it 7th grade and tighter on the 3rd long paragraph"): 75→61 words, short declarative sentences, plainer words; para FK 2.9, whole E1 FK 3.7. Commitb36348f. Flow recreated to pick up the tightened clone: oldWgxbEvDELETED, current Welcome flow =QRTgpD(seedTVHvSMre-PATCHed + unchanged, segmentRwgzKFuntouched). Preview redeployed. - Verify: status draft, 1 send + 1 delay (confirmed 5 min — the build script's strict dict-equality "delay" check was a false-fail; Klaviyo adds
secondary_value/timezone/delay_until_weekdaysdefaults), trigger=RwgzKF, clone≠seed, subject + Maria sender OK.
Gate (David's call, same honest-discount HARD RULE): WELCOME20 must be a REAL 20% code in 29next with a REAL 7-day expiry (the E1 says "runs for 7 days" / "here for 7 days") before flow OR popup goes live — false expiry = list-killer, same as RECOVER83/88. Plus: approve the revoiced E1 on the preview. Flip = PATCH QRTgpD status draft→live (API-able) once approved + WELCOME20 real. Three HF flows now exist, ALL DRAFT: Cart QUVjxZ, Leads SMYtpS, Welcome QRTgpD.
2026-05-17 — gate updates (David)
- ✅ E1 APPROVED (tightened plain-text version, FK 3.7) — "thats a good one".
- ✅
WELCOME20CONFIRMED real in 29next: 20%, 7-day expiry (David's verbal confirm, same as Gate-1 RECOVER83/88). The honest-discount gate for BOTH the Welcome flowQRTgpDAND the PDP popup is now CLEARED — do NOT re-flag WELCOME20 as unconfirmed. - ⏳ ONLY remaining gate for the popup+Welcome bundle = David approves the POPUP LOOK (
hf-pdp-popup-preview.netlify.app?hf_popup=preview|success). He chose "hold — approve popup look first"; NOTHING deployed/flipped. On his OK the bundle activates in one pass: flipHF_EMAIL_POPUP_ENABLED=true+ deploy PDP + flipQRTgpDdraft→live (I can do all three; Welcome flow is inert until the popup feeds theRwgzKFsegment, so they must go together). - 🐛→✅ Popup close-bug fixed (David caught it in preview; commit
d77a443): close/dismiss/overlay/Esc were dead because oneon()/bound[]helper tracked BOTH triggers + controls andopen()→teardown()removed all (previewopen()fires immediately → close torn down on open; would've hit LIVE too). Fix: controls = persistent plainaddEventListener(never torn down); only triggers+fallback-timer viabindTrig/teardownTrigs. Preview redeployed. Trap codified in ObsidianSkills/Klaviyo Flow Build & Checkout Prefill.md. Popup still flag-OFF/dormant. - Cart
QUVjxZ/ LeadsSMYtpSstill independently gated on Gate 2 (domain auth + Klaviyo Settings→Account address).
Welcome series (superseded by the 2026-05-17 build above; E2/E3 still unbuilt)
E1: drafted, design verdict received
- File:
email/humanframe/bodies/01-welcome-e1.html - Design pattern: 600px container, Cormorant Garamond serif headlines + DM Sans body + DM Mono for code
- Brand colors: paper bg
#f5efe4, navy#1A2640, terracotta#C8735A, callout-bg#f4e4dd - Discount:
WELCOME20in white voucher panel with 2px dashed terracotta border, DM Mono 36px navy, "Tap to copy · Apply at checkout · Expires in 7 days" - CTA URL:
https://www.humanframemd.com/?utm_source=klaviyo&utm_medium=email&utm_campaign=welcome&coupon=WELCOME20(29next?coupon=NOT Shopify?discount=) - Hero:
hero-pack.jpgwith rounded corners (copied from PDP) - Triple Method: 3-column Heat/Flush/Vibe row in mono labels
- Social proof: italic Cormorant pull-quote
- David's verdict on the discount block fix: implicit approval ("This needs to look a bit more like a discount code" feedback was addressed; no explicit "approved" but no further changes asked)
E2 + E3: not yet started
- Same design language as E1
- Pending E1 final approval
Blockers before E1 can go live
1. Footer mailing address — required for CAN-SPAM compliance, currently a placeholder
2. Confirm WELCOME20 exists in 29next backend — coupon code must be active
3. Sitewide ?coupon= persistence verification — confirm 29next preserves the URL param across navigation to checkout
Reusable artifacts
tools/29next-to-klaviyo/backfill.py
- Pulls 29next admin /users/, /orders/, /carts/ via OAuth Bearer
- Pushes to Klaviyo: profiles + Placed Order events + Started Checkout events
- Idempotent via
unique_id:29next-{brand}-order-{number}and29next-{brand}-cart-{id} - Excludes test emails (
@example.com,@test.,test@,+test@,davidsanghera,davidteo) and "david teo" / "david sanghera" by name - Profile properties:
29next_user_id,29next_user_type,29next_orders_count,29next_total_spent,29next_date_joined,29next_tags,29next_accepts_marketing - CLI:
--brand humanframe --since 7d --apply(alsowam/nailscience/skinscience) - GOTCHA:
?{field}__gte=filter is IGNORED on /users/ and /orders/ endpoints (returns more historical data than asked) — carts filter DOES work - GOTCHA: Started Checkout
$value=0because 29next cart line items don't exposeunit_price_incl_taxuntil checkout completes — fix later via product price lookup - GOTCHA: 2 'dashboard' user_type accounts (staff/admin) get included — filter
user_type == 'dashboard'in future revision
tools/29next-to-klaviyo/create_segments.py (NEW 2026-05-13)
- Creates the 4 standard segments idempotently
- See
klaviyo_segment_api_skill.mdfor schema details - CLI:
python3 tools/29next-to-klaviyo/create_segments.py --brand humanframe --apply
email/humanframe/assets/
logo-humanframe-wordmark.svg(copied from PDP)hero-pack.jpg(copied from PDP)
Pending work
Phase 2: ongoing 29next → Klaviyo sync
- Backfill ran once (7d window). New orders/carts after the backfill timestamp are NOT in Klaviyo.
- Need recurring sync to keep Klaviyo current so abandoned-cart flows fire on TODAY's carts, not just 7-day-old ones.
- Open decision: GitHub Actions cron (free, recommended) vs Netlify scheduled function ($19/mo Pro) vs local launchd (laptop-dependent) vs 29next webhook (real-time but ~2hr build)
- Open decision: cadence (15min recommended vs 5min real-time vs 1hr cheapest)
Wire abandoned-cart flow
- Use the new "HF Active Cart Abandoners" segment (id
WPehm7) as flow trigger - 5 people in it RIGHT NOW who could receive an email today
REVOKE accumulated API keys
- HF Klaviyo
pk_Yq8FjQ_...(after rollout complete) - 29next OAuth
YAXhL8lf...(after rollout complete) - WAM Klaviyo
pk_S47K8v_...(from earlier WAM session) - Shopify CLI session
- Shopify Distribution App pair
Pivots / lessons from this session
1. 29next admin uses MERCHANT subdomain pattern (spinerelief.29next.store/api/admin/), NOT campaigns.apps.29next.com (that's the storefront app surface, returns 403 "Campaign not active" on admin endpoints).
2. 29next user_type taxonomy: customer (1+ orders), lead (0 orders, abandoned cart candidates), dashboard (admin/staff). Filter dashboard accounts out of marketing flows.
3. Klaviyo discount link auto-apply: ?discount=CODE for Shopify checkout, ?coupon=CODE for 29next checkout. Don't mix them up — 29next IGNORES ?discount=.
4. Headless Playwright is detected by Klaviyo + forces re-login even with persistent profile cookies. Use headful + then Chrome MCP, OR just use the API (which is what I should have done from the start for this work).
5. Klaviyo UI Create button rejects synthetic events — see klaviyo_segment_api_skill.md Trap 5. For ANY Klaviyo automation, hit the API, never drive the UI for save actions.
When extending to NS / WAM / SS
The same pattern applies — once their 29next admin keys + Klaviyo private keys are in ~/.{29next,klaviyo}/{brand}.env:
```bash
1. Backfill recent profiles + events
python3 tools/29next-to-klaviyo/backfill.py --brand nailscience --since 30d --apply
2. Bootstrap the 4 standard segments
python3 tools/29next-to-klaviyo/create_segments.py --brand nailscience --apply
```
WAM is on Shopify (not 29next) — the backfill script doesn't apply there directly, but the segment-creation script DOES once we figure out how to push 29next-equivalent properties from Shopify orders into Klaviyo (via Shopify webhook → Klaviyo Profile properties).