b2c-app-builder 0.221.39

package/knowledge/growth/viral-growth-loops.md

@@ -0,0 +1,174 @@
+# Viral Growth Loops
+
+Use this before designing referral unlocks, share-to-unlock mechanics, invite systems, creator CTAs, TikTok/Reels/Shorts loops, shareable results, social-comment mechanics, viral onboarding/paywall flows, or launch growth systems that depend on product-led sharing.
+
+This reference factors in the user-provided Glam Up case study PDF, "From 0 to 1 Million Users in 6 Months: How I Built My Viral App" (redacted local PDF). Treat it as a tactical case study, not universal truth: borrow the system shape, verify fit for the current product, and reject dark-pattern or platform-policy risks.
+
+## Contents
+
+- Fit Gate
+- Growth System Thesis
+- Product Loop Contract
+- Content Format Lab
+- Monetization Timing
+- Measurement Plan
+- Outputs
+- Common Failure Modes
+
+## Fit Gate
+
+Viral growth is plausible when the app has:
+
+- a visual, emotional, or identity-based result that can be shown in a short clip, screenshot, or share card
+- a self-referential user moment: "this is about me," "this could be me," or "my friends should react to this"
+- a platform-native category where the target audience already watches, comments, saves, and shares adjacent content
+- a low-friction first session that gets users to curiosity before login, payment, or heavy setup
+- a legitimate value exchange for sharing: result unlock, referral reward, group benefit, social status, or useful artifact
+- enough instrumentation to distinguish attention, installs, referrals, paywall reach, purchases, and retention
+
+Defer or reject viral loops when:
+
+- the product has no visible or emotionally legible moment
+- sharing would expose sensitive data, regulated claims, minors, financial/health details, or private user content
+- the unlock mechanic would be coercive, deceptive, non-compliant, or hostile to users who cannot invite friends
+- the product cannot monetize or retain the traffic spike it might create
+- the acquisition platform does not match the likely paying buyer or device mix
+
+Record the fit decision in `VIRAL_GROWTH.md`, update `state/business-state.json` `lanes.growth`, and trace the decision into `state/LAUNCH_TRACE.md`.
+
+## Growth System Thesis
+
+Do not treat virality as a content-only lane. The Glam Up case study worked because four pieces reinforced each other:
+
+- product curiosity: users wanted a personal result enough to keep moving
+- product loop: users had a reason to share or refer inside the conversion path
+- content loop: TikTok created attention and comment behavior that amplified referral codes
+- monetization timing: the paywall caught users after emotional investment, not before curiosity formed
+
+For each launch, write a product-specific thesis:
+
+```text
+Audience/platform:
+Visible result:
+Emotional trigger:
+Product loop:
+Content loop:
+Conversion moment:
+Why this could compound:
+Why this could fail:
+```
+
+The product loop and content loop should share the same 11-star accepted product experience. If the ad hook promises a different magic than the product delivers, the loop is fragile.
+
+## Product Loop Contract
+
+Define the loop before implementation:
+
+- trigger: what user action creates the share/referral moment
+- reward: what the user earns, unlocks, or receives
+- recipient value: why the recipient would care, not only why the sender cares
+- share artifact: referral code, invite link, generated result, image, video, comparison, checklist, challenge, or group mechanic
+- surface: onboarding, blurred result, personalized plan, post-result screen, waitlist, paywall close, email, push, profile, or settings
+- fallback: what happens when the user cannot or does not want to share
+- abuse controls: rate limits, fraud checks, self-referral prevention, duplicate handling, entitlement limits, and support review
+- policy constraints: platform rules, App Review risk, disclosure, privacy, minors, incentives, and claims
+
+Do not hide the loop in settings if it is essential to growth. Conversely, do not force sharing as the only path when payment, free trial, waitlist, or non-social alternatives are required for fairness, compliance, or brand trust.
+
+## Content Format Lab
+
+Before scaling creators or Fastlane, make formats testable:
+
+- platform and geography
+- format ID
+- hook structure
+- first-frame visual
+- before/after or reveal contrast
+- text placement and size
+- caption and hashtag set
+- product visibility
+- CTA mechanic: comment code, search app name, tap link, tag friend, save, share, waitlist, referral, or store search
+- creator/account type
+- post time and audio
+- result windows: 24h, 72h, 7d, 30d
+- install, branded-search, store-rank, referral, paywall, and purchase signal
+
+Use `ugc-creator-engine.md` when creators, payments, contracts, or UGC operations are in scope; use `influencer-sponsorship-engine.md` when the content comes from paying creators with existing audiences (sponsorship deals, meme-page amplification). Use `fastlane-growth-ops.md` after launch approval or public beta when Fastlane is the generation or scheduling engine. Use `remotion-content-assets.md` when repeatable local video/still variants are needed.
+
+### Share Artifact Production
+
+Personalized share cards (score result, milestone badge, referral-unlock reveal) are social artifacts — they are not store screenshots and do not trigger the real-screenshots-only store-truthfulness guardrail. Produce them via `higgsfield-generate` with the `gpt_image_2` model:
+
+- Embed on-image user data (score, badge label, referral unlock text) in the `--prompt` alongside the full `DESIGN.md` brief (palette, type mood, shapes, texture, banned aesthetics).
+- Generate 9:16 first (Stories/Reels primary surface); produce the 1:1 feed variant via the `mcp__claude_ai_Higgsfield__reframe` MCP tool — do not re-generate a separate 1:1 from scratch. Confirm exact reframe invocation via the `higgsfield-generate` skill or MCP tool help before running; see the **Master → All Platforms (reframe + personal_clipper)** recipe in `tool-recipes/visual-and-motion-production.md`.
+- For referral-reveal carousels, use `higgsfield product-photoshoot` with `--mode social_carousel`; see the `higgsfield-product-photoshoot` skill.
+
+Guardrails:
+
+- `DESIGN.md` brief is required on every generation; generating without it is a named failure mode.
+- Confirm spend with the founder before every paid generation run (reframe included) per [`paid-tool-routing.md`](../operations/paid-tool-routing.md); surface current credit balance first.
+- Record every generated share card in `CONTENT_ASSETS.md` with route, `prompt_brief`, output paths, and QA/approval status.
+- Public posting stays founder-gated; generating share cards for in-app display does not constitute posting.
+
+One viral post is not a format. Treat a format as scale-ready only after repeatable signal: 2-3 hits from the same structure, preferably across more than one account or creator, plus downstream install/referral/revenue evidence.
+
+## Monetization Timing
+
+Load `onboarding-conversion.md` and `revenue-monetization.md` before implementing paywall mechanics.
+
+A viral app must be ready to catch demand before the spike:
+
+- remove unnecessary first-session friction before the product curiosity forms
+- place personalization, demo, scan, result preview, or other emotional investment before the main payment ask when compliant and truthful
+- make the paywall feel like continuing the journey, not a disconnected toll booth
+- test package mix, intro offer, closing offer, trial, or reverse trial with transparent renewal terms
+- keep restore purchases, terms, privacy, cancellation, and support visible
+- avoid fake computation, fake reviews, deceptive scarcity, undisclosed generated claims, or non-compliant review prompts
+
+The transferable lesson from the PDF is timing and framing, not copying manipulative details. If a tactic depends on misleading the user, redesign it into a truthful suspense, preview, demo, or value-reveal moment.
+
+## Measurement Plan
+
+Use `analytics-attribution.md` before implementation. `analytics/ANALYTICS.md` should include:
+
+- technical attribution: UTMs, referrer, deep link, creator/referral code, vanity URL, store context
+- self-reported attribution with stable source keys and `other` free text
+- product-loop events such as `referral_invite_started`, `referral_invite_completed`, `referral_unlock_earned`, `share_started`, `share_completed`, `creator_code_applied`, and `viral_format_signal_detected` when relevant
+- funnel events from first open to onboarding, value preview, referral/share prompt, paywall, purchase, entitlement, activation, and return
+- dashboard cards for attention, install/open, referral/share, paywall reach, conversion, revenue, retention, content format results, and platform/device mix
+- QA proof that referrals or unlocks affect backend/provider truth, not only local UI state
+
+### Loop Economics
+
+Counting shares is not measuring a loop. The one number that distinguishes a compounding engine from an amplifier of paid/organic top-ups is the viral coefficient:
+
+- **k = (invites or shares sent per active user in the period) × (recipient conversion rate to install/activation).** Compute it weekly from the catalog events above (`referral_invite_started` → `referral_invite_completed` → attributed installs), alongside **cycle time** — median days from a user's activation to their referred user's activation.
+- Read k honestly: **k ≥ 1** compounds on its own (rare; most consumer apps never get there); **k 0.3–0.7** is a meaningful acquisition multiplier on other channels (each paid install brings a fraction of a free one); **k < 0.15** means the loop is decoration and the effort belongs elsewhere. Shorter cycle time compounds whatever k you have, faster.
+- Record k, cycle time, and the trend in `VIRAL_GROWTH.md`'s Loop Economics section each week the loop runs. The stop/scale rules key on this number and its trend — not on gross share counts, which can rise while k falls.
+- A worked example: 1,000 weekly actives send 300 invites (0.3/user); 60 convert (20%) → k = 0.06. That loop is not a growth engine yet; it needs a stronger share moment or a better landing conversion before more traffic is poured through it.
+
+Do not call viral growth working from views alone. Views become launch learning only when connected to app opens, attribution, referrals, paywall reach, purchases, retention, or a deliberate awareness-only goal — and never from share counts without the k computation above.
+
+## Outputs
+
+Create or update:
+
+- `VIRAL_GROWTH.md`: fit gate, growth thesis, product loop, content loop, monetization timing, measurement plan, stop/scale rules, founder-only gates, and traceability
+- `growth/format-lab.csv` or `ugc/script-bank.md`: format IDs, hooks, variables, results, and next tests
+- `growth/referral-loop-map.md` when referral or unlock mechanics are non-trivial
+- `analytics/ANALYTICS.md` and `analytics/analytics-plan.html` with growth-loop events and dashboards
+- `product/ONBOARDING.md` and `revenue/REVENUE_OPS.md` when the loop changes onboarding, paywall, intro offer, or closing offer behavior
+- `growth/UGC_PLAYBOOK.md`, `CONTENT_ASSETS.md`, and `growth/FASTLANE_OPS.md` when creator or generated content is in scope
+- `state/LAUNCH_TRACE.md` rows connecting research, 11-star slice, product loop, content format, monetization, analytics, privacy/legal, and proof
+
+## Common Failure Modes
+
+- Treating virality as "post TikToks" instead of designing product, referral, content, paywall, and analytics as one system.
+- Copying a case-study tactic without checking audience, platform, category, device mix, policy risk, or monetization readiness.
+- Hiding referrals in settings while expecting them to drive acquisition.
+- Forcing referrals without a fair fallback, fraud control, or policy review.
+- Optimizing for views while ignoring installs, paywall reach, purchases, retention, or referral quality. (Anti-pattern 11 in the monetization-and-growth digest in [`revenue-monetization.md`](../money/revenue-monetization.md) §3 — a 500K-view post that converts to $400 is a hug, not a business; vanity reach without buying intent does not pay.)
+- Scaling creators from one lucky post before a repeatable format exists.
+- Letting content promise a result the product cannot truthfully produce.
+- Moving a viral unlock into build work without backend entitlement/referral proof.
+- Calling growth "done" while `VIRAL_GROWTH.md`, `analytics/ANALYTICS.md`, `product/ONBOARDING.md`, `revenue/REVENUE_OPS.md`, `growth/UGC_PLAYBOOK.md`, or `state/LAUNCH_TRACE.md` disagree.

package/knowledge/money/billing-health-and-reactivation.md

@@ -0,0 +1,54 @@
+# Billing Health And Reactivation
+
+Part of the [Revenue, Monetization, And Purchase Funnels](./revenue-monetization.md) hub.
+
+Use this for the purchase-events backend/analytics contract, involuntary billing-failure recovery, and reactivation/win-back — the systems that protect and recover revenue after a purchase already happened, as opposed to `paywall-pricing-and-experiments.md`'s job of winning the purchase in the first place.
+
+## Contents
+
+- 1. Backend And Analytics Contract
+- 2. Billing Health And Involuntary Churn (Recovery As A Growth Lever)
+- 3. Reactivation And Win-Back (Plan-Dependent, Mostly Monthly)
+
+## 1. Backend And Analytics Contract
+
+Create or update `analytics/ANALYTICS.md` and backend docs with:
+
+- stable user ID strategy across app, web, RevenueCat, Stripe, Supabase/Firebase, analytics, and support
+- anonymous web purchase and redemption behavior
+- purchase events: paywall viewed, product selected, checkout started, purchase completed, entitlement active, restore started/succeeded/failed, cancellation, refund, renewal, billing issue
+- revenue source dimensions: platform, store, product_id, offering_id, price, currency, intro/trial state, campaign/source/medium
+- webhook events and idempotency keys
+- support lookup path for Apple Hide My Email or anonymous purchases
+
+Acceptance:
+
+- a support agent can find a user by app UID, RevenueCat App User ID, Stripe customer ID, store transaction ID, email, or anonymous redemption path.
+
+## 2. Billing Health And Involuntary Churn (Recovery As A Growth Lever)
+
+Not all churn is a user decision. RevenueCat's **State of Subscription Apps 2026** finds that on **Google Play ~31% of all subscription cancellations are involuntary billing failures** (a ~32.2% billing-error rate) — **more than double the App Store's ~14%** (~15.2%). The report's framing: for Android-heavy apps, _fixing billing is one of the highest-leverage growth levers available_, because recovered payments are retained revenue you already earned with no new acquisition spend. Refund medians cluster around 3–5%; involuntary churn is the larger, more recoverable leak.
+
+This is distinct from the win-the-first-session work in `onboarding-conversion.md` (that is voluntary churn / failure to activate). Billing health is the recovery system for users who already decided to pay and then hit a card decline, expired card, insufficient funds, or grace-period lapse.
+
+Treat billing recovery as a first-class system, not an afterthought:
+
+- **Grace period + account hold (Android):** enable Google Play grace period and account hold so a failed renewal retries instead of revoking access instantly. Handle the Play RTDN states (`SUBSCRIPTION_IN_GRACE_PERIOD`, `SUBSCRIPTION_ON_HOLD`, `SUBSCRIPTION_RECOVERED`) through RevenueCat or the backend so entitlement state tracks the recovery, not just the first failure. Confirm exact state names against current Play billing docs before implementing (`revenuecat-and-store-products.md` §1).
+- **Billing retry (iOS):** Apple retries failed renewals automatically; surface the App Store-managed _Billing Issue_ / update-payment path rather than treating the first decline as a hard cancel.
+- **RevenueCat billing-issue webhook → dunning:** wire the RevenueCat `BILLING_ISSUE` / billing-issue webhook to a recovery sequence — an in-app banner and a push _before_ the grace period ends, plus the `payment.failed` lifecycle email in `resend-email-ops.md`. Give the user one tap to update the payment method (native subscription management deep link), and show the remaining grace period in plain language.
+- **Experience-card alignment:** the Recovery & Trust Repair card (`experience-cards/recovery-and-trust-repair-card.md`) is the UX contract for this — its bright line (name what happened, restore what can be restored, unconditional gesture when the failure was the product's fault) and dark line (no spend prompt inside or immediately after the failure screen) govern the copy; pair them with the grace-period guidance above and keep the copy non-punitive. Full recovery recipe: `retention_get_mechanic("recovery-and-trust-repair")`.
+
+Analytics: emit `billing_issue_detected`, `billing_recovery_prompt_shown`, `payment_method_update_started`, and `billing_recovered` / `billing_issue_churned` with `platform`, `store`, `grace_state`, and `failure_reason` dimensions so involuntary churn and recovery rate are measurable separately from voluntary churn. Do not report retention health without splitting voluntary vs. involuntary churn by platform.
+
+## 3. Reactivation And Win-Back (Plan-Dependent, Mostly Monthly)
+
+Some churn is recoverable later. RevenueCat's **State of Subscription Apps 2026** defines reactivation as the share of churned subscribers who become active again within 12 months, and the headline is that **reactivation is highly plan-dependent**: monthly-plan churners reactivate at ~18–24% across regions (~20% overall), weekly at ~7–10%, and **annual at just ~4–6% — annual churn is largely permanent** regardless of geography or price tier. Category spread is wide (monthly reactivation ranges ~6% to ~36%, highest in Productivity / AI-heavy apps), and high-priced monthly plans win back best (~28.9%) while high-priced annual churners (~4.4%) rarely return.
+
+Design implications:
+
+- **Don't bank win-back on annual churners.** Once an annual subscriber leaves, the data says they almost never come back inside a year. Put win-back energy where it pays off (monthly/weekly cohorts), and price/position annual to _prevent_ the churn rather than chase the return.
+- **Reactivation fires when the problem recurs, not when the email lands.** For cyclical-need categories (dating, fitness, entertainment, seasonal/shopping), the durable move is staying useful after cancellation and making return frictionless — not campaign spam. Pair with the lifecycle/`payment.failed`/win-back sequences in `resend-email-ops.md`, but treat the email as a reminder for users whose need already returned, consistent with `onboarding-conversion.md` anti-pattern #4.
+- **Offer pause instead of cancel, and keep return one tap.** Let users pause a subscription rather than fully cancel, and don't force them to re-enter payment details to come back. Surface this in the cancellation flow alongside the transparent downsell/closing offer (`onboarding-conversion.md`), without dark patterns.
+- **Capture the cancellation reason at the moment of cancellation.** One screen in the in-app cancellation/pause flow — before the store-managed cancel handoff — with a fixed reason-code taxonomy: `too_expensive`, `missing_feature`, `found_alternative`, `not_needed`, `technical_issue`, `other` (free text optional, never required). Emit `cancellation_reason_selected` with `reason_code` and `plan_duration`. A delayed exit-survey email measures who answers email, not why people cancel — same Day-0 logic as the rest of this file. The aggregated mix feeds the Pricing Decision revisit (`paywall-pricing-and-experiments.md` §3 step 5: a `too_expensive` majority is pricing evidence), win-back targeting here (`missing_feature` churners are the reachable cohort when the feature ships), and the kill-or-scale evidence pack. Never gate the actual cancellation on answering — the screen is skippable in one tap, per the ethics guardrail.
+
+Analytics: track `subscription_paused`, `reactivation_offer_shown`, `reactivated`, and `cancellation_reason_selected` with `prior_plan_duration`, `days_since_churn`, `price_tier`, and `reason_code` so reactivation is measured by plan duration (where the real gains are) rather than as a single blended rate. All §2/§3 event names live in the `analytics/ANALYTICS.md` Event Contract first — `check:analytics-catalog` reconciles `revenue/REVENUE_OPS.md` against the catalog the same way it does onboarding and growth docs.

package/knowledge/money/offer-and-pricing-decisions.md

@@ -0,0 +1,33 @@
+# Offer And Pricing Decisions
+
+Use this method when research proposes an offer or a selected monetization workflow locks a
+production price. A pricing hypothesis is useful research input. It is not an approved price.
+
+## Propose an offer
+
+State the audience, problem, outcome, entitlement, candidate amount, currency and billing period.
+Label the amount as a hypothesis. Compare relevant alternatives and their actual offer terms,
+not just which price feels opposite to an unpopular incumbent. Do not infer willingness to pay
+from category revenue, positive comments, or a competitor's nominal price alone.
+
+Record the test contract, dated exposure and response, limits and decision in
+`strategy/OFFER_TEST.md`. Keep observations distinct from inference. A current test may be
+inconclusive. A documented founder waiver records residual risk; it is not invented evidence.
+
+## Lock a production price
+
+Require the current offer evidence and an exact founder pricing decision. The opening mandate to
+build an app does not authorize setting its production price. Keep amount, currency, billing period,
+trial and renewal terms, entitlement, target environment and effective date aligned with the
+approved action. Preserve the host's existing legal/pricing and spending authority checks.
+
+A canonical `class.price` instance denotes an accepted commercial decision. Keep proposed prices
+in the research hypothesis and decision material until approved. `check:product-md` and the active
+revenue gate validate offer evidence for approved pricing. Guidance, a template, or a validator pass
+never grants permission to create a product or change a provider's prices.
+
+## Continue without inventing a decision
+
+Missing evidence or authority leaves the price lock pending. Continue independent research,
+design and local verification that does not depend on a locked price. Do not install a hard paywall
+or promise paid terms as final while the offer is still a hypothesis.

package/knowledge/money/paywall-pricing-and-experiments.md

@@ -0,0 +1,97 @@
+# Paywall, Pricing, And Experiments
+
+Part of the [Revenue, Monetization, And Purchase Funnels](./revenue-monetization.md) hub. Pricing, plan mix, trial length, and paywall-model changes are all founder-approved — see the hub's **Founder-Only Gates**.
+
+Use this for paywall timing/placement/trials/offers, pricing disclosure rules, the price-point decision procedure, and the standing paywall experiment cadence.
+
+## Contents
+
+- 1. Paywall Timing, Plans, Trials, And Offers
+- 2. Pricing And Disclosure Rules
+- 3. Price-Point Decision Procedure
+- 4. Paywall Experiment Cadence
+- 5. Surface To Engine Matrix
+
+## 1. Paywall Timing, Plans, Trials, And Offers
+
+Load `onboarding-conversion.md` when paywall placement is part of the first-session flow.
+Load [`../experience/paywall-goal-headline.md`](../experience/paywall-goal-headline.md) when the paywall headline interpolates an onboarding goal.
+Load `viral-growth-loops.md` when the paywall is paired with referral/share alternatives, creator-code entry, social proof loops, or content-driven impulse purchase timing.
+
+Required decisions:
+
+- hard paywall, soft paywall/freemium, reverse trial, web funnel, or no paywall yet
+- value moment shown before paywall: personalized plan, analysis, preview, product demo, or completed setup
+- paywall placement in onboarding and fallback if offerings fail to load
+- closing offer or reverse-trial behavior after paywall dismissal
+- package mix: weekly/monthly entry, annual recommended, lifetime optional only if sustainable
+- trial duration hypothesis and experiment plan
+- paid UA hypothesis when in scope: target event, CPA/LTV/payback window, selected channel, baseline window, and blended reporting owner
+
+Evidence rules:
+
+- RevenueCat's 2026 report shows hard paywalls materially outperform freemium on Day 35 download-to-paid conversion, but freemium can still be correct when free users drive word of mouth, network effects, UGC, or trust-building.
+- RevenueCat's 2026 report shows longer trials can convert better, while shorter trials can speed learning and cash-flow feedback. Treat trial length as an experiment, not dogma.
+- Trial **placement** is a separate lever from trial length: attaching the trial to the annual package only steers trial-seekers into annual and collects a year of cash up front on conversion — the pattern behind several fast-scaling 2026 consumer apps. Legitimate only with clear renewal price/term/cancellation disclosure on the paywall; run it as a plan-mix experiment (see `onboarding-conversion.md` Plan And Trial Mix).
+- RevenueCat's 2026 report identifies the moment after paywall dismissal as a high-leverage conversion point. Test transparent downsells, reverse trials, or shorter commitments without fake scarcity or unclear renewal terms.
+- Day 0 is the cancellation-risk window. The first session must prove value, explain billing clearly, and route users to the first activation task.
+- RevenueCat's 2026 report shows AI-centric apps earn ~41% more revenue per payer but churn ~30% faster, and LLM-backed features carry real per-subscriber serving cost. Treat AI value as a conversion driver, not a retention guarantee: instrument retention from the first cohort, and follow the report's own unit-economics pattern for AI apps (lead with annual plans, run less-generous freemium, and add a higher-priced AI tier) rather than assuming novelty will keep users. See `billing-health-and-reactivation.md` §2 for the involuntary-churn side of retention.
+- **The first renewal is the retention inflection.** Per the 2026 report, ~half of monthly subscribers and ~three in four yearly subscribers don't make it past the first renewal, but retention jumps ~18–30pp between the first and second renewal across all durations — surviving Renewal #1 is the true filter. Yearly plans retain ~3–10× better than weekly by Y1 (higher upfront commitment filters for stronger need), and access method (freemium vs. hard paywall) barely moves Y1 retention. Y1 retention is also softening year-over-year (annual median ~31%→28%, monthly ~10%→8%). The winning move is not gating harder or charging differently — it's **accelerating time-to-value before the first renewal decision**, so design onboarding/activation to land real value well inside the first billing cycle.
+
+## 2. Pricing And Disclosure Rules
+
+Before publishing pricing:
+
+- founder approves price, trial, intro offer, renewal price, cancellation language, and refund posture
+- paywall, landing page, app metadata, screenshots, terms, privacy, store products, RevenueCat offerings, Stripe prices, and analytics all match
+- App Store Connect pricing, RevenueCat offering/package IDs, Stripe/web funnel prices, screenshots/app previews, custom product pages, In-App Events, and localized metadata all use the same approved price/trial/renewal facts
+- if showing an annual intro offer, keep first-year price, renewal price, and monthly option visible together on direct funnel pages
+- avoid fake scarcity, hidden renewal mechanics, or unsupported savings claims
+- include platform billing caveats: App Store/Google Play manage in-app purchases; Stripe/RevenueCat/Paddle manage web purchases depending on chosen engine
+
+## 3. Price-Point Decision Procedure
+
+§2 governs how an approved price is disclosed; this section is how the price gets chosen. "Do pricing research" is not a procedure — this is, and its output lands in `revenue/REVENUE_OPS.md` under a "Pricing Decision" heading that `check:revenue` requires before the lane is done.
+
+1. **Anchor against the category.** Pull the subscription prices of 5–10 direct competitors from `strategy/RESEARCH.md`'s competitor set — AppKittie app details (IAP lists) plus the live store listings are the sources. Record each competitor's monthly and annual price with the date checked, and compute the category range and median. An anchor table with fewer than five real rows means the research lane is not done enough to price against.
+2. **Choose two or three candidate points, biased high.** The benchmarks in `revenue-monetization.md` §3 (anti-patterns 5–6) are the prior: higher-priced apps show ~5.4x monthly realized LTV and _higher_ download-to-paid conversion, because price reads as a quality signal. Default candidates: the category median, and one point meaningfully above it justified by the 11-star slice. Only go below median with a written reason (deliberate land-grab, network-effect freemium per §1 above). Anchor annual as the highlighted plan per §1 and `revenue-monetization.md` anti-pattern #5.
+3. **Design the trial against the value moment, not the calendar.** Trial length and paywall placement route through `onboarding-conversion.md` (Plan And Trial Mix, Paywall Timing) — the trial must be long enough to reach the magical moment from `11_STAR_EXPERIENCE.md` at a realistic usage cadence, and trial length is an experiment, not a constant.
+4. **Record the decision.** The chosen points, the anchor table, the rationale, and the founder's approval date go in `revenue/REVENUE_OPS.md` ("Pricing Decision"). Pricing is founder-only (see `revenue-monetization.md` §2 Founder-Only Gates); the procedure prepares the decision, it never makes it.
+5. **Revisit on evidence, not anniversaries.** Post-launch price changes are driven by the cancellation-reason mix (`billing-health-and-reactivation.md` §3), realized LTV vs. the anchor assumptions (Economics Snapshot in `revenue/REVENUE_OPS.md`), and the kill-or-scale evidence pack — and every change routes through [`change-cascade.md`](../process/change-cascade.md) so store products, RevenueCat offerings, screenshots, landing, and legal move together.
+6. **Derive territory prices with a dry-run.** Load `subscription-price-derivation.md` before `asc subscriptions pricing derive`.
+
+## 4. Paywall Experiment Cadence
+
+The first paywall is a hypothesis, not a decision. The apps that clear the $1K-to-$10K climb run continuous paywall/pricing experiments — timing, packaging, trial shape, offer — while the ~75% that never clear it typically shipped one reasonable paywall and stopped (anti-pattern #10 in `onboarding-conversion.md` names this; this section is its procedure). The cadence is a standing program, not a launch task:
+
+- **The backlog is a living artifact.** `revenue/REVENUE_OPS.md`'s Paywall Experiment Backlog carries planned/active/completed rows. Each row names hypothesis, surface, variant, engine, primary metric, start date, result, and decision. `check:revenue` requires current activity once the app has been live four weeks with the revenue lane done — an active row, a completed row started within eight weeks, or a dated next experiment. A backlog of empty headers or one fossilized test is the one-and-done plateau wearing a green check. Shipping one reasonable paywall and stopping fails that gate.
+- **The cycle log is the owned recurrence output.** Write `revenue/PAYWALL_EXPERIMENT_PROGRAM.md` on each run. Record Cycle date, Backlog change, and Next experiment. `check:revenue` requires a cycle row dated within 14 days after four live weeks.
+- **One experiment at a time per surface,** measured on cohort economics (trial-start rate × trial-to-paid × early churn — `revenue-monetization.md` §3's guidance), never on day-one conversion alone. Minimum one full renewal-decision window before judging.
+- **The test menu, in rough order of historical lift:** paywall timing/placement in onboarding, packaging mix (annual anchor, lifetime presence), trial length and type (opt-in vs opt-out, reverse trial), price point per §3's revisit procedure, closing offer, and paywall design/copy last.
+- **Route by tooling:** RevenueCat Experiments is the default monetization engine. The app fetches the `current` Offering. Use PostHog only for UX that Offerings cannot express. Use bandit only for continuous allocation. A dated before/after is weaker evidence. Label it as weaker.
+- **Founder gates hold:** price changes and new offers are founder-approved per `revenue-monetization.md` §2 Founder-Only Gates; the experiment program proposes, the founder disposes, and every completed test lands its decision back into §3's pricing record through `change-cascade.md`.
+- **Do not invent social proof.** Experiment copy must not fabricate download counts. Load [`ethics-guardrail.md`](../experience/ethics-guardrail.md) when a variant shows counts, urgency, or scarcity.
+
+## 5. Surface To Engine Matrix
+
+Record this matrix in `revenue/REVENUE_OPS.md` before a live experiment starts.
+
+`check:revenue` reads the matrix heading after four live weeks.
+
+Engine values are exact tokens: `revenuecat_experiments`, `bandit`, `posthog`.
+
+| Surface                                   | Default engine           | Allowed engine           | Rule                                                   |
+| ----------------------------------------- | ------------------------ | ------------------------ | ------------------------------------------------------ |
+| paywall, plan mix, trial, price, offering | `revenuecat_experiments` | `revenuecat_experiments` | Fetch the `current` Offering. Do not use bandit.       |
+| creative, ASA keyword, UA arm             | `bandit`                 | `bandit`                 | Kill on CPA versus LTV. Do not replace RC price tests. |
+| onboarding step order, non-offering copy  | `posthog`                | `posthog`                | Use when Offerings cannot express the variant.         |
+
+A monetization surface with engine `bandit` fails closed.
+
+An allocation surface with engine `revenuecat_experiments` fails closed.
+
+Current activity after four live weeks must include one monetization row on `revenuecat_experiments`.
+
+Creative-only bandit rows do not satisfy the paywall program.
+
+RevenueCat Experiments may need a paid plan. Record that as a founder decision when the Free tier blocks it.

package/knowledge/money/revenue-monetization.md

@@ -0,0 +1,107 @@
+# Revenue, Monetization, And Purchase Funnels
+
+## Tax And Payout Readiness
+
+Record the legal owner for each store and payment provider. Confirm tax forms, banking details, payout currency, payout schedule, reserve or hold state, and reconciliation ownership. Keep sensitive values in the approved provider or secret manager. Record only status and sanitized evidence in the launch workspace. An incomplete tax or payout setup blocks a revenue-readiness claim.
+
+Use this before setting up RevenueCat, Stripe, App Store/Google Play products, web billing, web purchase links, web funnels, paywalls, subscriptions, taxes, webhooks, pricing, entitlement identity, or purchase validation. This is the routing hub — it carries the decision matrix, the founder-only gates, and the anti-pattern digest; the setup and procedure detail live in the spokes below.
+
+This is not a payment approval. Founder approval is required before changing prices, creating live billing products, enabling paid checkout, spending on ads, publishing subscription terms, or submitting store builds with monetization changes.
+
+Load [`paid-tool-routing.md`](../operations/paid-tool-routing.md) before replacing RevenueCat, Stripe, app-store product setup, paid RevenueCat features, tax tooling, or provider dashboards with local mocks or free-tier-only planning. Mock purchases are implementation proof only; they are not live entitlement proof.
+
+Load `viral-growth-loops.md` before using referral unlocks, share rewards, creator codes, closing offers, or viral paywall timing as part of monetization. A growth spike is only useful if the paywall, entitlement, analytics, refund/restore, and abuse controls are ready to catch it.
+
+Load `paid-user-acquisition.md` before using paid ads, Apple Search Ads, web-to-app campaigns, paid creative tests, or custom product pages to drive purchases. A paid campaign is only launch-ready when CPA can be evaluated against RevenueCat LTV/cohorts, trial conversion, payback window, and entitlement proof.
+
+## Contents
+
+- 1. Monetization Decision Matrix
+- 2. Founder-Only Gates
+- 3. Anti-Patterns (Monetization And Growth Decision Traps)
+- 4. Per-Request Cost Model
+
+## Spokes
+
+| Load when                                                                                                                                                                                               | Spoke                                                                        |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| RevenueCat project/product/entitlement/offering setup, App Store/Play product gates, MISSING_METADATA, RevenueCat product-type reconciliation, paywall smoke proof, or promotional IAP/subscription art | [`revenuecat-and-store-products.md`](./revenuecat-and-store-products.md)     |
+| Stripe account/checkout/webhooks/customer-portal setup, or RevenueCat Web Billing, Purchase Links, Web Funnels, Web SDK, or Redemption Links                                                            | [`stripe-and-web-billing.md`](./stripe-and-web-billing.md)                   |
+| paywall timing/placement/trials/offers, pricing disclosure rules, the price-point decision procedure, the paywall experiment cadence, or RevenueCat Experiments vs bandit vs PostHog engine choice      | [`paywall-pricing-and-experiments.md`](./paywall-pricing-and-experiments.md) |
+| the analytics/backend contract for purchase events, involuntary billing-failure recovery, or reactivation and win-back                                                                                  | [`billing-health-and-reactivation.md`](./billing-health-and-reactivation.md) |
+| deriving one subscription's territory prices from another with `asc subscriptions pricing derive`                                                                                                       | [`subscription-price-derivation.md`](./subscription-price-derivation.md)     |
+
+## 1. Monetization Decision Matrix
+
+Choose the smallest reliable monetization path for the current phase:
+
+- **Pre-build validation**: waitlist, pricing page, preorder interest, or non-charging web funnel. Do not imply paid access is active.
+- **Mobile-only app subscription**: App Store/Google Play products, RevenueCat products/entitlements/offerings, in-app paywall, restore purchases, sandbox testing, store submission.
+- **Web-to-app acquisition**: RevenueCat Web Billing or Stripe Billing through RevenueCat Web, Web Purchase Links or Web Funnels, Redemption Links, deep-link redemption, app entitlement validation.
+- **Existing Stripe web business**: Stripe Billing remains billing engine, RevenueCat imports/syncs entitlements, Stripe webhooks and customer portal stay authoritative for billing management.
+- **Direct Stripe without RevenueCat**: only use when the app does not need mobile store entitlements or cross-platform entitlement sync. For digital goods unlocked inside iOS/Android apps, review Apple/Google rules first.
+
+Default for B2C mobile subscriptions: RevenueCat owns entitlements and cross-platform subscription state. Stripe may be the web payment rail or billing engine, but a successful Stripe payment is not launch-ready until it unlocks the correct RevenueCat entitlement in the app.
+
+## 2. Founder-Only Gates
+
+Always ask before:
+
+- creating live Stripe/RevenueCat/Apple/Google products
+- changing prices, trials, discounts, intro offers, renewal terms, tax settings, or billing engine
+- enabling live checkout or publishing purchase links
+- submitting IAP/subscriptions for review
+- enabling external purchase links/calls to action in app
+- changing refund/cancellation/legal language
+- switching from Test Store/sandbox to production
+
+Agents may self-resolve doc organization, sandbox validation sequencing, and which non-live checklist to run first.
+
+## 3. Anti-Patterns (Monetization And Growth Decision Traps)
+
+This skill mostly tells agents what to do. This section names what _not_ to do: the comfortable defaults that feel safe and quietly lose. They share one pattern — founders fall in love with building, then reach for the cozy choice on money and distribution. The losing moves are documented in public benchmarks; the winning moves are slightly uncomfortable.
+
+Every figure below is from the RevenueCat State of Subscription Apps 2026 report. Treat each direction as a strong default to test against your product, not dogma — the existing nuance in `paywall-pricing-and-experiments.md` §1 and `onboarding-conversion.md` still holds (freemium can be right when free users drive network effects; trial length is an experiment). The anti-pattern is reaching for the cozy default _by reflex_ and never surfacing the trade-off.
+
+This is the digest index. Traps 1–2, 5–6, and 13–14 are detailed here; the rest live in their home references.
+
+| #   | Anti-pattern (the cozy default)                                   | Lives in                                             |
+| --- | ----------------------------------------------------------------- | ---------------------------------------------------- |
+| 1   | Assume you are the exception                                      | here                                                 |
+| 2   | Soft paywall by default because a hard paywall "feels pushy"      | here + `onboarding-conversion.md`                    |
+| 3   | Default to a 3-day/short trial because "urgency converts"         | `onboarding-conversion.md`                           |
+| 4   | Ignore the first session and bank on a day-30 win-back email      | `onboarding-conversion.md`                           |
+| 5   | Push monthly, skip annual                                         | here                                                 |
+| 6   | Price low to be "humble"                                          | here                                                 |
+| 7   | Ship English-only; treat localization as optional translation     | `app-store-listing-prep.md`                          |
+| 8   | Run ads before you can read the result                            | `paid-user-acquisition.md`                           |
+| 9   | Optimize ad creative first                                        | `paid-user-acquisition.md`                           |
+| 10  | Run one paywall experiment a year and call it focus               | `onboarding-conversion.md`                           |
+| 11  | Chase views / vanity reach                                        | `paid-user-acquisition.md` + `viral-growth-loops.md` |
+| 12  | Skip the App Preview video because it "feels like a real project" | `app-store-listing-prep.md`                          |
+| 13  | Treat involuntary (billing-failure) churn as inevitable           | here + `billing-health-and-reactivation.md` §2       |
+| 14  | Bank on AI novelty for retention                                  | here + `paywall-pricing-and-experiments.md` §1       |
+
+**1. Assume you are the exception.** Only ~4.6% of newly launched apps reach $10K/month within two years, with roughly a 75% drop-off from the $1K to the $10K milestone. A vision board does not move you into the 4.6%. Do not pick a monetization model that only works if you are an outlier. Choose the path that survives if you are the median app, and instrument the funnel so you learn fast enough to climb.
+
+**2. Soft paywall by default because a hard paywall "feels pushy."** Hard paywalls show a median ~10.7% Day-35 download-to-paid conversion vs ~2.1% for freemium (about 5x), and roughly 8–9x higher D14 revenue per install ($2.32 vs $0.27). Letting everyone in free and gently whispering "maybe upgrade someday" is the cozy choice that leaves most of the money behind. Default to _testing_ a hard paywall after a clear value moment; choose freemium **deliberately** when free users drive network effects, UGC inventory, marketplace value, or word of mouth (see `paywall-pricing-and-experiments.md` §1 and `onboarding-conversion.md` Paywall Timing), not because forcing a decision feels rude.
+
+**5. Push monthly, skip annual.** Apps whose most popular plan is yearly generate the highest realized revenue per install (D14 $0.36, D60 $0.46 — above weekly- and monthly-dominant apps); an annual commitment locks in retention instead of handing the renewal decision back to the store every month. Do not lead with monthly because it "feels honest and low-commitment." Offer annual as the highlighted plan with monthly and any entry plan visible alongside it (see `onboarding-conversion.md` Plan And Trial Mix), and test the mix.
+
+**6. Price low to be "humble."** High-priced apps show ~5.4x the monthly realized LTV of low-priced apps ($35.89 vs $6.67) and ~6x the yearly LTV ($62.19 vs $10.69) — and download-to-paid is _higher_ at higher prices (2.8% vs 1.4%), because price reads as a quality signal. Pricing at $2.99 "to avoid gouging anyone" trains users to value the app at nothing; it is not generous. Set price from delivered value and willingness to pay, then test it. (This is distinct from the App Store **container price**, which must stay Free for subscription/IAP apps — see `revenuecat-and-store-products.md` §2. The anti-pattern here is the _subscription/IAP price_ being anchored low out of timidity.)
+
+**13. Treat involuntary (billing-failure) churn as inevitable.** On Google Play ~31% of cancellations are involuntary billing failures (~32.2% billing-error rate) vs. ~14% (~15.2%) on the App Store — and the report calls fixing billing one of the highest-leverage growth levers for Android apps, because recovered payments are revenue you already earned. Shipping the paywall and then shrugging at declines is the cozy default that quietly leaks retained revenue. Stand up the recovery system in `billing-health-and-reactivation.md` §2 (grace period / account hold, billing-issue webhook → dunning push + in-app banner + `payment.failed` email, one-tap update-payment), and split voluntary vs. involuntary churn by platform in analytics. Do not call retention "healthy" without measuring the involuntary slice.
+
+**14. Bank on AI novelty for retention.** AI-centric apps earn ~41% more revenue per payer but churn ~30% faster (per the 2026 report), and LLM features carry real per-subscriber cost. Assuming the AI wow-factor will keep users — and skipping the retention/unit-economics work — is the trap. Instrument retention from the first cohort, protect margin per the report's AI pattern (annual-led plans, less-generous freemium, a higher-priced AI tier; see `paywall-pricing-and-experiments.md` §1), and judge an AI app on second/third-cycle renewal and reactivation, not just install-day conversion.
+
+Founder-only gate reminder: pricing, plan mix, trial length, and paywall-model changes are all founder-approved (see §2 above). Surface the benchmark trade-off; do not silently apply or silently skip it.
+
+## 4. Per-Request Cost Model
+
+A pack that calls a paid LLM API carries a real per-request cost, not just a subscription price. Size that cost from four token components: input tokens, output tokens, cache-write tokens, and cache-read tokens. Each component has its own rate (`platform.claude.com/docs/en/about-claude/pricing`).
+
+Cost per active user = (input tokens × input rate + output tokens × output rate + cache-write tokens × cache-write rate + cache-read tokens × cache-read rate) × requests per active user.
+
+Count the real token payload, or call the provider's token-counting endpoint. Never estimate token count from character count — a request or output limit sized on a character estimate under- or over-counts real spend.
+
+See `trust/AI_PROVIDER_CONTROLS.md` for the spend boundary that enforces this limit, and `trust/paid-generative-ai-controls.md` for the founder-facing per-request cost-model requirement this section mirrors.