b2c-app-builder 0.221.39

package/catalog/generated/firstparty/knowledge/experience/onboarding-foundations.md

@@ -0,0 +1,264 @@
+# Research-backed onboarding with identity and measurement
+
+Onboarding is the real route to first value, not a slideshow added after the app.
+Research informs its interaction and account decisions. Measurement and attribution
+are implemented in the first runnable prototype, not attached at launch.
+
+Keep the existing owners: ONB-09 owns the research synthesis; ONB-12 owns identity;
+ONB-13 owns its measurement contract; ONB-18 owns the prototype; ONB-22 owns final
+execution proof. `analytics/ANALYTICS.md` remains the business-wide event vocabulary.
+`DESIGN.md` owns global design. References between these artifacts carry SHA-256
+fingerprints so a changed input invalidates its dependent claim. Do not edit reducer
+state or claim a provider result by setting a boolean in a document.
+
+## ONB-09 evidence join
+
+Read the selected onboarding and analytics guidance through the knowledge API.
+Use its exact document hash and heading. Do not substitute remembered advice or a
+provider's generic instructions for the business's accepted promise.
+
+Join actual user/competitor findings, platform and provider constraints, visual and
+interaction references, and internal methods into six explicit decisions:
+`first_value`, `identity`, `measurement`, `attribution`, `consent`, `visual_design`.
+Explain what each decision changes in this app and how it can fail. A source list
+alone is not applied research. Retained source observations must resolve; inaccessible
+screens, expired unretained references, and guessed provider behavior do not count.
+Keep the collection date, original source, permitted evidence and uncertainty.
+
+Each stage packet keeps its explanatory prose and adds exactly one H2 named
+`Foundation contract`, containing exactly one fenced `json` block. Other examples
+are not contracts. The schemas live in `contracts/onboarding/foundations.ts`.
+The research block has `schemaVersion: 1` and these arrays:
+
+- `inputs`: exactly the six source packets ONB-03 through ONB-08 as `{path, sha256}`.
+  Retain the actual findings and explicit source limitations; a changed packet requires
+  reviewing its synthesis again.
+- `knowledge`: `referenceId`, package-relative `path`, `sha256`, exact `section`.
+  Include the selected `reference.experience.onboarding-conversion` and
+  `reference.data.analytics-attribution`; retain their original reference identities.
+- `observations`: unique `id`, original `source`, RFC3339 `observedAt`, `resolution`
+  set to `resolved`, `finding`, `limitation`, and `evidence: {path, sha256}`.
+- `decisions`: unique `id`, one of the six `topic` values, nonempty `knowledgeIds`
+  and `observationIds`, the actual `decision`, `appliesTo` surface, and `verification`.
+
+Every topic occurs exactly once. Every referenced ID resolves. Evidence paths are
+relative to this business; knowledge paths are relative to the selected package.
+A matching hash proves the retained bytes, not that the claim is true or the agent
+understood them. The independent reviewer must judge those things.
+
+## ONB-12 identity and authentication
+
+Decide whether accounts are unnecessary, optional after first value, or required
+for a real product reason. Do not force sign-in merely to make analytics easier.
+Authentication, onboarding progress, profile completion, activation, attribution,
+consent, experiment assignment and entitlement are separate state machines.
+
+Choose a stable opaque app subject identifier. Record the selected auth provider,
+session owner, protected credential storage, and who owns analytics and entitlements.
+Identify or merge only after verified authentication, and only where consent permits.
+A sign-in click, canceled authorization, or analytics identify call is not verified
+sign-in and cannot grant paid access. Do not put raw credentials, email, address,
+phone, quiz answers or tokens in analytics events or durable orchestration receipts.
+
+Handle first open, sign-in, cancel/failure, restoration/expiry, logout, account switch,
+reinstall, deletion and purchase restore. Preserve permitted anonymous first-touch
+context across an authenticated transition, but never merge different users simply
+because they share a device. Clear or isolate identity, attribution, queued events,
+and entitlement state on logout/account switch. Declare identity merge and restore
+semantics for the selected provider and version; do not assume every provider aliases
+or transfers purchases in the same way.
+
+The identity Foundation contract has `schemaVersion`, `research: {path, sha256}`,
+`authMode` (`guest_first`, `account_required`, `no_account`), `authReason`, `authOwner`,
+`subjectOwner`, `analyticsOwner`, `entitlementOwner`, `verifiedSessionRule`,
+`credentialStorage`, `identityMergeRule`, `dataIsolationRule`, and `transitions`.
+Each transition has `scenario`, `applicable`, `reason`, `from`, `to`, `persistence`,
+`recovery`, `verification`. Include exactly one of each:
+`first_open`, `sign_in`, `auth_cancel`, `auth_failure`, `session_restore`,
+`session_expired`, `logout`, `account_switch`, `reinstall`, `account_deletion`,
+`purchase_restore`. Account-only transitions may be inapplicable for `no_account`;
+record a product reason rather than inventing account functionality. Restore may be
+inapplicable when purchases are genuinely outside accepted scope.
+
+## ONB-13 measurement and attribution
+
+This contract follows ONB-10 first value, ONB-12 identity and ONB-14 consent/policy.
+It references their accepted meanings rather than re-deciding them. Global design
+lock and the prototype consume these decisions. Analytics transport failure must
+not block the product, and a denied consent route must still be usable.
+
+The Foundation contract has `schemaVersion`, `identity`, `firstValue`, `blueprint`, and `policy`
+artifact references, `schemaPath`, `initializationPath`, `initialization`,
+`consentRule`, `privacyAllowlist`, `retryPolicy`, `events`, `attribution`,
+`experiments`, and `scenarios`. Planned source/test paths become required real files
+at prototype acceptance. Do not claim schema presence alone proves wiring.
+
+The measurement block's `firstValue: {path, sha256}` refers to
+`product/onboarding/graph/ONB-10-first-value-activation.md`. Changing the value or
+activation definition requires reviewing measurement and rerunning affected proof.
+
+
+`initialization` contains each step exactly once: `restore_consent`,
+`restore_identity`, `configure_collection`, `first_event`, `first_value`.
+Restore *local* consent and identity state before collection configuration. Do not
+wait indefinitely on a remote login to show first value; use the declared anonymous
+or recovering state. Configure collection before emitting the first permitted event.
+Deny or buffer only as permitted by the consent policy. Do not replay disallowed
+pre-consent tracking events after a later opt-in.
+
+Every `events` entry has `role`, canonical `name`, `applicable`, `reason`, `emitter`
+(`client`, `backend`, `provider`), `trigger`, `identity`, `consent`, `deduplication`,
+`implementationPath`, `testPath`. Include each semantic role once:
+`app_opened`, `onboarding_started`, `step_viewed`, `step_completed`,
+`first_value_rendered`, `first_value_engaged`, `onboarding_completed`,
+`auth_started`, `auth_succeeded`, `auth_failed`, `auth_cancelled`, `consent_changed`,
+`attribution_received`, `attribution_selected`.
+Map roles to the existing event vocabulary; do not silently rename live events.
+Auth roles can be inapplicable for an account-free app; the attribution-question
+role can be inapplicable with a justified friction/privacy decision.
+
+The app's typed event schema defines version, event_id, event/received time, app and
+environment, journey/step/session/correlation, opaque subject, acquisition and consent
+fields, property types, deduplication, and authoritative emitter. UI events describe
+actual display or actions. Completion, authenticated sessions, purchase confirmation,
+entitlement and experiment exposure are not interchangeable success events.
+
+Each `attribution` entry has `topic`, `source`, `destination`, `persistence`,
+`joinBasis`, `unknownBehavior`, `verification`. Include `first_touch`, `last_touch`,
+`deep_link`, `deferred_link`, `self_report`, `unknown`, `identity_join`,
+`cross_device`, `consent_denied`, `logout_reset` exactly once.
+Preserve first touch; update last touch intentionally. Keep technical, self-reported
+and modeled attribution distinguishable. Retain UTMs/referrers/referral context across
+permitted handoffs. Missing or prohibited joins stay unknown. A self-report is not
+observed ad attribution. Do not infer cross-device identity or fingerprint around
+tracking denial. Consent to first-party product analytics and cross-company tracking
+are separate decisions; do not equate ATT with every analytics use.
+
+`experiments` has `applicable`, `reason`, `assignmentOwner`, `exposureRule`,
+`primaryMetric`, `guardrails`. Assignment is not exposure. Record actual exposure
+once at the selected unit. No experiment is also a valid explicit decision.
+
+Each scenario has `id`, `applicable`, `reason`, ordered `expectedRoles`, `assertions`
+(the assertion IDs below), and `testPath`. Include every row, even when justifiably
+inapplicable. Required first-session, privacy and failure tests cannot be waived as
+"later". Add app-specific assertions without replacing the required ones.
+
+| Scenario | Required assertion IDs |
+| --- | --- |
+| fresh_install | initial_events_captured, first_value_reachable |
+| returning_user | journey_resumed, identity_restored |
+| guest_upgrade | session_verified, guest_value_preserved, identity_join_permitted, entitlement_not_invented |
+| session_expired | expired_session_rejected, reauth_recoverable |
+| auth_cancel | cancel_is_not_success, journey_recoverable |
+| auth_failure | failure_is_not_success, retry_recoverable |
+| account_switch | no_identity_bleed, no_entitlement_bleed, attribution_isolated |
+| consent_denied | no_disallowed_collection, product_usable |
+| unknown_attribution | unknown_preserved |
+| deep_link | context_retained_through_auth, unsupported_join_stays_unknown |
+| offline_retry | queue_recovers, collector_deduplicates |
+| analytics_unavailable | first_value_not_blocked |
+| account_deletion | session_invalidated, subject_data_erased |
+| purchase_restore | provider_entitlement_confirmed, no_cross_account_transfer |
+
+Auth cancel/failure scenarios must observe `auth_started` then the matching outcome.
+Guest upgrade and account switch observe `auth_started` and `auth_succeeded` from a
+verified session; expiry exercises app open and reauthentication. Returning use and
+analytics outage observe app open and first value. Consent denial observes app open,
+consent change and first value with denied collection. Unknown attribution observes
+app open, attribution resolution and first value; deep-link tests observe attribution
+resolution and first value. Event names are mapped to these roles, never guessed.
+Account-free apps mark account scenarios inapplicable with their product rationale.
+
+Fresh install exercises app open, onboarding start, step display/action, first value
+rendered and engaged, and completion. Account scenarios follow the auth decision;
+no-account is not an excuse to omit first-open instrumentation. Product scope decides
+whether purchase restore and deep links apply; missing provider access is a blocker,
+not a not-applicable result.
+
+## ONB-18 instrumented design prototype
+
+Design the actual journey against the screen/control contract, identity transitions,
+consent routes, event triggers and source-backed decisions. Author those decisions in
+`DESIGN.md`. Git owns revisions. Render the generated Design Room as a read-only review
+page; it is not a mutable design store. Cover the shipping platforms recorded in
+`studio/seed/business.json` `mobileApp.platforms` and `DESIGN.md` accepted surfaces,
+plus small viewports, large text, and reduced motion on those selected surfaces. Do
+not require an unselected platform. A selected platform without a supported adapter
+is an unsupported or missing-implementation hold, not implied parity from a shared
+component contract. The host recipe target, including `host/agent-cli`, is not the
+app's shipping scope. After `DESIGN.md` changes, regenerate the review page and renew
+affected proof. Show empty, loading, permission denial, cancellation, errors, resumed
+use and reduced-motion behavior where applicable. Do not copy another app's branding
+or invent findings.
+
+The Foundation contract has `schemaVersion`, `research`, `identity`, `measurement`,
+`screenContract`, `design` artifact references and `decisions`. Each decision maps
+`decisionId` from ONB-09 to `surface`, `implementedBehavior`, and a real rendered
+`evidence: {path, sha256}`. Cover every research decision, not just visual styling.
+
+Produce `product/onboarding/prototype-evidence.json` by running the instrumented
+prototype. Cover fresh install, consent denial, unknown attribution and analytics
+outage before accepting it. ONB-19 carries these working foundations into production
+implementation. ONB-20 independently reviews ONB-17, ONB-18 and ONB-19; its session
+must differ from the producers. Findings are not self-approval.
+
+## Wiring evidence and final acceptance
+
+ONB-22 produces `product/onboarding/runtime-evidence.json`, covering *every*
+applicable scenario. Existing canonical graph, cutover, provider and design checks
+still apply. This file is an output observation attached to the existing engine's
+acceptance and evidence owner, not another execution-state store.
+
+Both proof files use `schemaVersion: 1`, `stage` (`prototype` or `runtime`), RFC3339
+`capturedAt`, `appId`, `buildId`, `environment`, `measurement: {path, sha256}`,
+`sources: [{path, sha256}]`, and `runs`. Source coverage includes the declared schema,
+initialization code, every applicable emitter implementation and every scenario test.
+Bind the full candidate/build through the existing device/browser proof mechanism;
+the source list here specifically checks the referenced instrumentation files.
+
+Each run has `scenario`, `trace`, `executionEvidence`, and optional `providerReadback`
+artifact references. Retain real command/device execution output separately from the
+normalized trace. Final fresh-install proof also requires collector readback plus an
+observed provider-destination event. Existing provider proof gates establish selected
+connection readiness. Local fake collectors and tests only prove their tested scope.
+
+A trace has `schemaVersion: 1`, `scenario`, `appId`, `buildId`, `environment`,
+`kind` (`instrumented_app` or `provider_readback`), `subjectKind: synthetic`,
+`initialization` (the observed ordered steps), `events` and `assertions`.
+Each event has `eventId`, `name`, `role`, `emitter`, opaque synthetic `subjectKey`,
+`consent` (`allowed`, `denied`, `not_required`), `destination` (`local`, `provider`),
+`attribution` (`known`, `unknown`, `self_reported`) and RFC3339 `occurredAt`.
+Each assertion has `id`, `passed`, and the actual `observation`. Use minimized,
+synthetic test subjects; do not preserve a real user's identity map in receipts.
+
+Check observed order, identity isolation, collector deduplication, consent handling,
+unknown attribution and first value despite unavailable telemetry. A canceled/failed
+auth attempt must not emit success; account switching must exercise both subjects.
+Changed contract or source hashes invalidate old proof. A hash or a typed JSON file
+alone does not establish a real execution: retain execution/readback evidence, and
+have the independent verifier inspect it against the actual build.
+
+
+### Collector observation contract
+
+Final `providerReadback` references a JSON object with `schemaVersion: 1`, `appId`,
+`buildId`, `environment`, `observedAt`, a separate `rawEvidence: {path, sha256}` provider
+export, and `events: [{eventId, name, subjectKey}]`. It must match the sent first-session
+events from the tested candidate. The raw export is not the local test log or the
+normalized trace. Retain only synthetic subject identifiers and permitted fields.
+The independent reviewer inspects that export and execution evidence; these hashes
+establish identity and currency of submitted evidence, not its truth by themselves.
+
+
+## Source guidance
+
+The procedural gate contract above is builder-owned. Verify current selected-provider
+semantics during ONB-07; do not carry vendor-specific assumptions into replacements.
+PostHog's [identification guidance](https://posthog.com/docs/product-analytics/identify)
+describes anonymous-to-identified joins and logout reset. RevenueCat's
+[customer identity guide](https://www.revenuecat.com/docs/customers/identifying-customers)
+distinguishes alias/restore behavior and entitlement ownership. Apple's
+[privacy guidance](https://developer.apple.com/app-store/user-privacy-and-data-use/)
+distinguishes cross-company tracking from permitted first-party uses and rejects
+tracking around permission denial. These sources were reviewed on 2026-09-06;
+that date is provenance, not a claim of future provider compatibility.

package/catalog/generated/firstparty/knowledge/experience/paywall-goal-headline.md

@@ -0,0 +1,99 @@
+# Paywall Goal Headline
+
+Use this after the onboarding quiz collects a goal, and only when
+`product.yaml` records `feature.paywall-goal-headline` as required.
+
+Not selected, selected but unavailable, and unresolved stay different:
+
+- required: interpolate the selected goal as the paywall headline
+- excluded or non-goal: omit the RevenueCat offering-metadata / `customVariables` bind
+- instance absent: hold; do not treat the bind as free or as selected
+- required with a non-RevenueCat present-paywall owner: unavailable; do not invent a RevenueCat pass
+
+A producer sentence that the bind is not applicable cannot override a required feature.
+Do not invent an outcome the user did not choose.
+
+Workflow `providers:` lists and installed SDKs are not selection.
+Declared `b2c.yaml` monetization bindings are.
+
+Load `commitment-funnel.md` for first-session order.
+Load `onboarding-conversion.md` for the ONB graph.
+Load `../money/paywall-pricing-and-experiments.md` for RevenueCat Experiments.
+
+## Contents
+
+- 1. Goal Contract
+- 2. Runtime Bind
+- 3. Ethics
+- 4. Experiment
+- 5. Outputs
+- 6. Common Failure Modes
+
+## 1. Goal Contract
+
+Record a Paywall Goal Headline table in `product/ONBOARDING.md` when the feature is required.
+
+The table must name:
+
+- goal key
+- user-facing prompt
+- headline template
+- fallback when skipped
+
+The quiz writes one durable key: `paywall_headline_key`.
+Each goal key is a closed enum.
+A skip or blank answer uses the fallback key, not a guessed goal.
+
+The headline template may interpolate only that selected key.
+Example: `lose_weight` → "Start losing weight today".
+Example: `build_muscle` → "Start building muscle today".
+The fallback must stay generic. Do not name a body, money, or time outcome the user did not pick.
+
+## 2. Runtime Bind
+
+Keep headline templates in RevenueCat Offering metadata so copy can change without an app release.
+
+See [Offering metadata](https://www.revenuecat.com/docs/tools/offering-metadata).
+
+At paywall present time, bind the selected key through RevenueCat Paywalls custom variables.
+
+See [Displaying Paywalls](https://www.revenuecat.com/docs/tools/paywalls/displaying-paywalls).
+
+Write the same key as a subscriber attribute when Experiments targeting needs it.
+Call `syncAttributesAndOfferingsIfNeeded` after the quiz if targeting depends on that attribute.
+
+The app always fetches the current Offering.
+
+## 3. Ethics
+
+Honest interpolation of the user's answer is required.
+Do not invent a weight, muscle, money, or time result.
+Do not imply a medical or guaranteed outcome.
+Apple Guideline 3.1 still applies: paid service copy must match the real offer.
+
+A skipped goal uses the fallback template.
+A skipped goal must not look like a personalized result.
+
+## 4. Experiment
+
+Adopt this contract as the default starter.
+Run it as a RevenueCat Experiment against a static headline.
+Judge the test on trial-to-paid and refund rate, not day-1 paywall conversion alone.
+
+This is the copy slice of the commitment funnel.
+Do not replace the funnel.
+
+## 5. Outputs
+
+- Paywall Goal Headline table in `product/ONBOARDING.md`
+- `paywall_headline_key` written at quiz or goals
+- Offering metadata template map
+- fallback headline for skip
+- experiment row in `revenue/REVENUE_OPS.md`
+
+## 6. Common Failure Modes
+
+- Paywall headline that names an outcome the user did not choose
+- Missing fallback when the quiz is skipped
+- Hard-coded headline that needs an app release to change
+- Treating a two-day conversion lift as proof without a refund-rate companion

package/catalog/generated/firstparty/knowledge/experience/push-notification-lifecycle.md

@@ -0,0 +1,79 @@
+# Push Notification Lifecycle
+
+Push is the highest-leverage retention channel a mobile app owns: it reaches users who never open email, costs nothing per send, and drives same-session return at a fraction of paid re-acquisition cost. The skill builds a provider-grade email system (`resend-email-ops.md`); this reference is its push sibling, and for in-app engagement it is the primary channel — email carries receipts, digests, and win-back for users who opted out of push. Load it before onboarding hardens (the permission ask lives there), before notification-bearing Experience Cards ship (streaks, fresh-start, at-risk nudges), and again at post-launch when retention work starts.
+
+The ethics line up front: push serves the user's stated goal, never the app's need for a session. Every trigger below must answer "what does the user get by tapping this, right now?" — a notification that only benefits the retention chart is the dark-pattern variant of this channel, and the Streak/Loss-Aversion and Variable Reward guardrails in `ethics-guardrail.md` apply to pushes exactly as they do to in-app mechanics.
+
+## Contents
+
+- 1. Provider Setup
+- 2. Permission Priming
+- 3. Lifecycle Trigger Table
+- 4. Frequency Caps And Quiet Hours
+- 5. Analytics Contract
+- 6. Weekly Operation
+- 7. Anti-Patterns
+
+## 1. Provider Setup
+
+- **Native default:** APNs (iOS) and FCM (Android) direct, via the app's backend. The archetype starters' Supabase backend can schedule and send through an edge function; record the route in `engineering/TECH_SPEC.md`'s data contract.
+- **Provider route:** OneSignal or a comparable push provider is a paid/account-gated tool decision — route it through [`paid-tool-routing.md`](../operations/paid-tool-routing.md) before adopting, and record the choice in `strategy/TOOL_DECISIONS.md`. A provider earns its keep at segmentation/scheduling scale; day one usually does not need one.
+- Keys and certificates (APNs key, FCM service account) are server secrets: route through [`secrets-management.md`](../operations/secrets-management.md), names-only in `SECRETS.md`.
+- Token lifecycle: capture the push token post-permission, refresh on app start, delete on logout and account deletion (the deletion path in `privacy-terms.md` includes push tokens).
+
+## 2. Permission Priming
+
+The raw iOS permission dialog converts poorly when it appears cold; a primed ask converts at multiples of an unprimed one, and a denial is nearly permanent (the user must dig through Settings to reverse it). Treat the ask as a conversion surface with one canonical placement:
+
+- **Prime first.** A pre-permission screen in the app's own UI explains the one concrete job pushes do for this user ("your Wednesday reminder, nothing else") with the user's own goal named. Only after an affirmative tap does the system dialog appear.
+- **Canonical placement:** after the first value moment at an earned point where the benefit is concrete. First-run onboarding may use the push prime when it directly supports the next user action. Native App Review requests are separate: earn eligibility after value, finish first-run onboarding, and request later at a natural success in normal product use. Never stack both interruptions in one step or session moment.
+- **Denial handling:** a soft-prime decline is re-askable at the next earned moment (a streak at risk, a feature that plainly needs it); a hard system-dialog denial is not — record it and fall back to email for lifecycle sends.
+- Provisional/quiet delivery (iOS) is a legitimate first rung for content apps: deliver quietly, earn the upgrade to alerts.
+
+## 3. Lifecycle Trigger Table
+
+Load [`no-slop-writing.md`](../words/no-slop-writing.md) (its §7 covers push/lifecycle subject-line and body limits) before drafting any Content contract copy below, and self-check each trigger's copy against it — the guilt-copy ban in this file's ethics contract is necessary but not sufficient; empty phrases and weasel language are a separate failure mode no-slop-writing.md exists to catch.
+
+Design triggers as a segmentation table, not ad-hoc sends. The standard set, adapted per app:
+
+| Trigger          | Segment                                                      | Timing                                             | Content contract                                                                               |
+| ---------------- | ------------------------------------------------------------ | -------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| Activation nudge | signed up, core action not yet done                          | +24h after install, once                           | name the one action and its payoff; deep-link straight to it                                   |
+| Habit anchor     | activated, opted into a schedule                             | user-chosen time, recurring                        | the user's own commitment mirrored back; skip silently when already done today                 |
+| At-risk save     | usage declining vs own baseline                              | after 2x the user's normal gap                     | one concrete resume point, no guilt copy (ethics contract)                                     |
+| Streak/milestone | earned event just occurred                                   | at the moment it happens                           | celebrate the earned thing; never a fake milestone                                             |
+| Dormant win-back | no session 14–30 days, still subscribed or high prior intent | once at 14d, once at 30d, then stop                | what changed since they left; easy re-entry point                                              |
+| Renewal/billing  | trial ending, payment failed                                 | per `billing-health-and-reactivation.md` §2 timing | plain statement of state and the one action; billing pushes are transactional, not promotional |
+
+Every row deep-links to the exact screen that fulfills the promise; a push that lands on the home screen breaks the contract.
+
+## 4. Frequency Caps And Quiet Hours
+
+- Default cap: **one marketing/lifecycle push per day, three per week**, transactional (billing, security) exempt. Record the chosen caps here and in `operations/POST_LAUNCH_OPS.md`.
+- Quiet hours by default (22:00–09:00 local) unless the user scheduled a time inside them — their explicit schedule always wins.
+- Caps are enforced server-side, not promised in prose: the send path checks the user's recent-send count before dispatch.
+- The notification-disable rate is the counter-metric (`emotional-experience-measurement.md` flags >20% as investigate): a rising disable rate is users telling you the caps are wrong.
+
+## 5. Analytics Contract
+
+Push events live in the `analytics/ANALYTICS.md` Event Contract before any builder prompt names them (`analytics-attribution.md` rule). The standard catalog rows:
+
+- `push_permission_primed` — the soft-prime screen was shown (properties: placement, session_number)
+- `push_permission_granted` / `push_permission_denied` — system dialog outcome
+- `push_sent` — server-side, per send (properties: trigger, campaign_id)
+- `notification_opened` — existing catalog event; properties gain trigger/campaign_id
+- `notification_disabled` — user turned pushes off in Settings or in-app
+
+The funnel that matters weekly: primed → granted rate, per-trigger open rate, opened → same-session core-action rate, and disable rate per trigger. A trigger whose open rate decays across cohorts is retired or rewritten, not louder.
+
+## 6. Weekly Operation
+
+In the Weekly Ops Review (`post-launch-operations.md` §2), push rides the retention step: read per-trigger open and disable rates alongside the D7/D30 cohorts, and treat a retention drop at a known step as a candidate for a new earned trigger — through [`change-cascade.md`](../process/change-cascade.md) like any product change. One trigger experiment at a time; measure against the cohort, not gross opens.
+
+## 7. Anti-Patterns
+
+- **Cold ask.** The system permission dialog on first launch, before any value — converting a majority of installs into permanent opt-outs to make a dashboard move.
+- **Email-only lifecycle.** A full Resend automation suite with zero push strategy — the higher-open channel left unbuilt because the email one had a reference and this one did not.
+- **Guilt copy.** "Your streak is dying 😢" — the ethics contract bans manufactured loss; name the real state and the real action.
+- **Broadcast blasts.** Untargeted sends to the whole install base; every push is segmented by the trigger table or it does not go out.
+- **Unmeasured sends.** Pushes fired without `push_sent`/`notification_opened` wiring — retention spend with no receipt.

package/catalog/generated/firstparty/knowledge/growth/appsflyer-mmp.md

@@ -0,0 +1,99 @@
+# AppsFlyer MMP
+
+Use this when paid user acquisition is in scope.
+AppsFlyer is the default mobile measurement partner.
+A founder MMP waiver is required for any other stack.
+
+RevenueCat stays subscription truth.
+AppsFlyer stays install and campaign attribution.
+Load `paid-user-acquisition.md` for channel, creative, and kill rules.
+Load `hdyhau-blended-roas.md` until this MMP path is spend-ready.
+
+Docs:
+
+- RevenueCat AppsFlyer integration: `https://www.revenuecat.com/docs/integrations/attribution/appsflyer`
+- AppsFlyer iOS SDK: `https://dev.appsflyer.com/hc/docs/ios-sdk`
+
+## Contents
+
+- 1. Spend-Ready Path
+- 2. RevenueCat Bridge
+- 3. Event Map
+- 4. Waiver
+- 5. Outputs
+- 6. Common Failure Modes
+
+## 1. Spend-Ready Path
+
+Finish this path before the first paid dollar.
+
+1. Install the AppsFlyer SDK for iOS or Expo.
+2. Initialize AppsFlyer before RevenueCat configure.
+3. Request ATT after the first value moment, not on first launch only.
+4. Set `$appsflyerId` on the RevenueCat customer before trial or purchase.
+5. Enable the RevenueCat AppsFlyer integration in the dashboard.
+6. Prove install, app_open, and subscribe in the AppsFlyer sandbox.
+
+`check:paid-ua` reads this path when the paid-UA lane is `in_progress` or `done`.
+
+Record the path in `growth/PAID_UA.md` under MMP Before Spend.
+
+## 2. RevenueCat Bridge
+
+Call `Purchases.setAttributes` with `$appsflyerId` before a trial starts.
+
+Also send `$idfa`, `$idfv`, `$gpsAdId`, and `$ip` when the platform allows them.
+
+Server-to-server renewals then reach AppsFlyer without an app open.
+
+Do not treat a network SDK plus a spreadsheet as spend-ready.
+That stack needs a founder MMP waiver.
+
+## 3. Event Map
+
+Map these events before spend:
+
+| B2C App Builder event | AppsFlyer event          | Owner          |
+| --------------------- | ------------------------ | -------------- |
+| install               | install                  | AppsFlyer SDK  |
+| app_open              | af_app_opened            | AppsFlyer SDK  |
+| trial start           | subscribe or start_trial | RevenueCat S2S |
+| purchase              | subscribe                | RevenueCat S2S |
+| renewal               | subscribe                | RevenueCat S2S |
+
+Keep RevenueCat Experiments on offerings.
+Do not move price tests into AppsFlyer.
+
+## 4. Waiver
+
+A founder may waive AppsFlyer for a named replacement stack.
+
+Write a Founder MMP Waiver table in `growth/PAID_UA.md`.
+Record date, founder identity, replacement stack, and approval state.
+
+Approval state must be `approved` or `granted`.
+Pending or unapproved text does not bypass AppsFlyer.
+Prose such as `Founder MMP waiver: pending founder approval` is not a grant.
+
+The founder cell must name a founder or owner.
+It must not name an agent.
+The date must be a past ISO date.
+The stack must be a named replacement.
+
+An empty waiver fails closed.
+
+## 5. Outputs
+
+- MMP Before Spend notes in `growth/PAID_UA.md`
+- `$appsflyerId` bridge evidence, or a dated founder MMP waiver table
+- sandbox event proof in `operations/PROVIDER_PROOF.md` when the lane is done
+
+## 6. Common Failure Modes
+
+- First spend with only a network SDK and a sheet
+- `$appsflyerId` set after the first purchase
+- ATT prompt on first launch with no value
+- Price tests run in AppsFlyer instead of RevenueCat Experiments
+- Empty founder MMP waiver
+- Unstructured founder MMP waiver prose
+- Pending or unapproved founder MMP waiver state

package/catalog/generated/firstparty/knowledge/growth/cro-landing.md

@@ -0,0 +1,86 @@
+# Landing Page CRO (Public Funnel Structure)
+
+Use this before building or auditing the public pre-launch/marketing funnel for conversion: the landing/waitlist page, the web-to-app or app-preview page, a Product Hunt/launch page, or any web surface whose job is to turn a visitor into an install, signup, or purchase. This governs page _structure and conversion mechanics_; it is the web-funnel complement to [`onboarding-conversion.md`](../experience/onboarding-conversion.md), which owns the in-app flow.
+
+Load [`conversion-copy.md`](../words/conversion-copy.md) for the words on the page (hero, CTA, proof copy) — do not rewrite copy craft here. Load [`geo-seo.md`](./geo-seo.md) before editing any landing file, policy page, metadata, `robots.txt`, `llms.txt`, sitemap, or schema — that gate fires before the first edit, not after. Load [`analytics-attribution.md`](../data/analytics-attribution.md) before naming funnel events, and [`design-room.md`](../design/design-room.md) when the page is a Design Room surface (mutate `studio/seed/business.json`, do not hand-author one-off HTML).
+
+> Adapted from Corey Haines' marketingskills (`https://github.com/coreyhaines31/marketingskills`, MIT License, © Corey Haines 2025): the `cro` landing-page conversion discipline. Reframed for B2C mobile waitlist/web-to-app funnels and wired into this skill's funnel proof and traceability contracts.
+
+## Contents
+
+- Sources To Refresh
+- Required Artifacts
+- Page Conversion Structure
+- Trust And Proof Placement
+- Mobile Viewport Rules
+- Friction Audit
+- Analytics Events
+- Gates Before Handoff
+
+## Sources To Refresh
+
+- Corey Haines marketingskills `cro` skill (MIT): `https://github.com/coreyhaines31/marketingskills`
+- Current Core Web Vitals thresholds (LCP/INP/CLS) — slow pages cap conversion: `https://web.dev/articles/vitals`
+- The project's `strategy/RESEARCH.md` competitor landing teardown and `11_STAR_EXPERIENCE.md` for the one promise the page must carry
+- Refero shipped-flow research for current landing/waitlist patterns when access is available (see [`refero-ux-patterns.md`](../design/refero-ux-patterns.md))
+
+## Required Artifacts
+
+Create or update `CRO_AUDIT.md` when a launch ships a public conversion page. It records the page's conversion structure, the friction removed, and the test queue. The `check:landing-funnel` gates still apply. They cover live deploy, a form smoke test, and a frozen per-page CRO hold when a listed studio surface has a conversion job. A static legal or support page must not invent that layer.
+
+`CRO_AUDIT.md` must include:
+
+- the single conversion goal of the page (one primary action) and the secondary action if any
+- the above-the-fold inventory: promise, subhead, primary CTA, one proof element, hero visual
+- the full section order with the job each section does (problem → outcome → how → proof → objection handling → final CTA)
+- trust/proof placement map (where each social-proof, security, and risk-reversal element sits)
+- the friction audit: every required field, every click before conversion, every load-time risk, with the removal decision
+- the test queue: ranked CRO hypotheses (highest-traffic, highest-impact first), each handed to the experiment discipline
+
+## Page Conversion Structure
+
+- **One page, one job.** A landing page that asks for an install _and_ a newsletter signup _and_ a follow converts for none. Pick the primary action; make every section serve it.
+- **Above the fold earns the scroll.** The promise, a clarifying subhead, one CTA, and one proof element must be visible without scrolling. Everything else is permission to keep reading.
+- **Section order follows awareness:** name the problem in the user's words → show the after-state → show how it works in 3 steps → stack proof → handle the top objection → repeat the CTA. Cold mobile traffic rarely reaches a buried CTA.
+- **Repeat the CTA** at each natural decision point (after the value, after the proof, at the end) — same action, same words.
+- **Match the ad to the page.** The hero promise must echo the ad/creative that drove the click ([`paid-user-acquisition.md`](./paid-user-acquisition.md)); a message mismatch is the most common silent conversion killer.
+
+## Trust And Proof Placement
+
+- put one proof element near the fold (rating, user count, recognizable logo, or a single strong quote)
+- cluster richer proof (testimonials, screenshots, press) right before or after the primary CTA, where the decision happens
+- add risk reversal at the CTA (free, no card, cancel anytime, restore purchases) — only claims that are true and honored
+- never fabricate counts, ratings, endorsements, or scarcity; unsupported proof is a claims-ledger and compliance liability (see [`conversion-copy.md`](../words/conversion-copy.md) and [`privacy-terms.md`](../trust/privacy-terms.md))
+
+## Mobile Viewport Rules
+
+Most B2C traffic is mobile — design and QA the small viewport first:
+
+- the promise and CTA fit a phone fold without pinch-zoom; tap targets are thumb-reachable
+- the primary CTA is reachable without hunting (sticky or repeated)
+- forms ask for the minimum (email-only for a waitlist; defer everything else)
+- the page passes Core Web Vitals on a mid-tier device; a slow hero caps every downstream metric
+- verify on real mobile/desktop visual QA, not just a desktop browser
+
+## Friction Audit
+
+Conversion rises faster from removing friction than from adding persuasion. For each step from visit to conversion, ask: is this field required _now_? is this click necessary? does this load fast? Cut every "no". Defer optional data to after the conversion.
+
+## Analytics Events
+
+Declare in `analytics/ANALYTICS.md` first; implement the approved catalog:
+
+- `landing_viewed` (variant_id, traffic_source)
+- `landing_cta_clicked` (variant_id, cta_position)
+- `waitlist_submitted` / `app_store_redirect` / `purchase_started` (the page's primary conversion)
+  Tie every CRO test to the experiment discipline in [`analytics-attribution.md`](../data/analytics-attribution.md): a CRO change is an experiment with a hypothesis, a minimum sample, and a stop rule.
+
+## Gates Before Handoff
+
+- `CRO_AUDIT.md` exists for any public conversion page
+- the page has one primary conversion goal and an above-the-fold promise + CTA + proof
+- [`geo-seo.md`](./geo-seo.md) was loaded before the first file edit; AI-crawler/metadata/schema checks pass
+- `check:landing-funnel` gates (live deploy, form smoke test) pass; record the results in `engineering/PRODUCTION_READINESS.md`
+- mobile viewport and Core Web Vitals verified with visual QA proof
+- the top CRO hypothesis is registered as an experiment with a stop rule
+- copy on the page traces to `product/copy/COPY_BRIEF.md`; the hero matches the driving ad