Brand database · briefs/humanframe/BRAND.md · source of truth

Humanframe — Brand Database (BRAND.md)

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

FieldValue
Legal entity / ownerTO FILL
Key people & rolesTO FILL
Support email / phoneTO FILL
Brand relationshipTO FILL (own brand / client / partner)

1 · Products & SKUs

CodeProductSize / formatUPCFormula / spec sourceSupplier
TO FILL

2 · Inventory & supply chain

SKUUnits on handLocation / 3PLLot / mfg dateShelf lifeCOGS (landed)MOQ / reorder lead timeUpdated
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)

SystemID / handleNotes
Domain(s) / DNSTO FILL
Netlify site (id · team)TO FILL
29next store / campaignTO FILL
Meta BM · ad account · pixelTO FILLCAPI token → env file only
GA4 property · measurement id · GTMTO FILL
Klaviyo orgTO FILL
adscalerads client · Airtable baseTO FILL
Cookie / event prefixTO 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)

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.

9 · Open questions / asks

TO FILL

10 · Change log


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)

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:

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:

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

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:

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.

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

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):

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:

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:

ToggleStateWhat it does
Enable Klaviyo TrackingON (turned on 2026-05-14)Storefront browse events fire to Klaviyo from 29next-hosted pages (= checkout pages)
Delay Order Confirmation EventsON10-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 ConsentOFF(no SMS yet)
Enable Sending Test Data to KlaviyoOFFImportant — keeps test orders out
Send Started Checkout Event with Abandoned CartONNative integration is pushing Started Checkout events
Sync Product Catalogue to KlaviyoONProducts auto-synced for use in email templates

Division of labor (codified in backfill.py docstring):

LayerOwner
Profile auto-create on orderNative integration
Ordered Product (per line item)Native (metric RU4ERs)
Refunded Order / Cancelled OrderNative (metrics TFZNmy / XgRznw)
Started Checkout (cart abandoners)Native (verified, was duplicating with our backfill)
Storefront browse events on 29next-hosted pagesNative (since Klaviyo Tracking just turned on 2026-05-14)
Product catalog syncNative
Checkout opt-in subscriptions → All Profiles listNative (default subscription list now points to VFHtSg)
29next_user_type / orders_count / total_spent profile propertiesOur backfill (native writes ZERO custom props)
Placed Order event with $value / Items shapeOur backfill (different metric than native's Ordered Product)
Historical reconcile of pre-integration dataOur backfill (with --include-carts for historical Started Checkout)

Today's duplication evidence (philip.markey):

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)

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

29next admin

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.**

SegmentidDefinition (CURRENT, native-metric)
HF Customers (have ordered)UgxQFJPlaced Order Yiy9HJ count > 0 (in-the-last 1825d)
HF Leads (no orders)VYktQPPlaced Order Yiy9HJ count == 0 (in-the-last 1825d)
HF VIP CandidatesSLBYqiPlaced Order Yiy9HJ count > 3 AND sum > 299.99 (AND, in-the-last 1825d)
HF Active Cart AbandonersWPehm7Started 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)

Key Klaviyo metric IDs (API-discovered)

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:

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.

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."

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:

TemplateID
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 shoulderQWBD5m
HF Leads · D1 · the spot that can't healY8jb7h
HF Leads · D2 · you're treating the wrong depthVGSeYb
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)

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):

FlowFlow IDTriggerChainFlow-owned msg template IDs
HF Cart Abandon (4-day, akemi)RtGV8Rmetric VHQGTQ Started Checkoutdelay 1h → email → 24h → email → 24h → email → 24h → emailWQYzEi SD7L2H Y2pqya TNwAUz
HF Leads (4-day, education-led)SQYwUnsegment 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):

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.

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):

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):

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):

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):

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)

Welcome series (superseded by the 2026-05-17 build above; E2/E3 still unbuilt)

E1: drafted, design verdict received

E2 + E3: not yet started

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

tools/29next-to-klaviyo/create_segments.py (NEW 2026-05-13)

email/humanframe/assets/

Pending work

Phase 2: ongoing 29next → Klaviyo sync

Wire abandoned-cart flow

REVOKE accumulated API keys

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).

Rendered 2026-11-16 from the git-tracked file. Edits happen in the repo (Claude files every fact David sends the same turn); this page is the read view.