<div align="center">

📱 Paywall Pilot Framework

A framework for designing App Store-compliant<br>subscription paywalls that convert.

<!-- meta:block readme_hero -->

_{AI skill + knowledge base + executable tool. For iOS + Android. Built on 88 sourced 2026 benchmarks and platform changes (Adapty 16K apps · RevenueCat 115K apps · AppsFlyer 1.7B installs · Superwall 32M paywall views · Apple/Google store updates) and a 20-concept academic foundation (Kahneman + Layer 2). Flagship domain is Paywall; expansion to Onboarding / Retention / Growth / Pricing on the roadmap.}

<br>

<!-- /meta:block -->

🚀 Get Started • 🏗️ Architecture • 🧩 Modules • 💡 Use Cases • 📊 What You Get • 🗺️ Roadmap • 🤝 Contributing

</div>

---

🏗️ Architecture

Paywall Pilot is not just a Claude Code skill (though it works as one). It's a 4-layer framework, designed to be used whole or per-layer.

Runtime behavior is intentionally smaller than this README: agents should start from SKILL.md, then use runtime/ for input contracts, routing, and source lookup rules.

┌─────────────────────────────────────────────────────────────┐
│  🤖 SKILL LAYER          SKILL.md + modules/*.md            │
│  Entry point for AI assistants (Claude / GPT / Cursor)      │
│  Thin core + lazy modules + runtime contracts               │
├─────────────────────────────────────────────────────────────┤
│  📚 KNOWLEDGE LAYER      sources.json + outputs/            │
│  Every numeric claim sourced. Research briefs.              │
│  Use standalone or referenced by Skill layer.               │
├─────────────────────────────────────────────────────────────┤
│  🔧 TOOL LAYER           tools/ltv-calculator.py            │
│  Executable utilities. CLI + JSON I/O.                      │
│  Callable by Skill layer OR from Bash.                      │
├─────────────────────────────────────────────────────────────┤
│  📘 REFERENCE LAYER      docs/ + examples/                  │
│  Human-readable playbooks, checklists, migrations, examples │
│  Works without any AI tool.                                 │
└─────────────────────────────────────────────────────────────┘

Which layer do you need?

| You want to… | Use layer | |--------------|-----------| | Get an AI paywall audit | Skill (install into Claude Code / paste into ChatGPT) | | Look up a specific benchmark with source | Knowledge (sources.json) | | Calculate LTV / ROAS / breakeven | Tool (python3 tools/ltv-calculator.py) | | Read a printable pre-ship checklist | Reference (docs/audit-checklist.md) | | Migrate from a banned pattern | Reference (docs/migrations/) | | See a worked audit example | Reference (examples/) |

---

---

⚡ Use this when…

Concrete jobs-to-be-done. Match your situation; the framework activates the relevant modules automatically.

| 👤 Your situation | 💬 Ask your AI… | 🧩 What activates | |------------------|-----------------|-------------------| | You're designing your first paywall. | "Help me design the paywall for my new fitness app." | Full audit · taxonomy · screen anatomy · copy library · category benchmarks | | Apple just rejected you. | "I got rejected for Guideline 3.1.2. Help me fix it." | Compliance triage · toggle-paywall migration playbook · field-report decision tree | | You don't know if your numbers are good. | "Install→trial 9%, trial→paid 22%, refund 6%. Are these OK?" | Indie Dev FAQ · category benchmarks · performance grading | | You need to know if you'll be profitable. | "I have 40k installs, $3 CPI, annual $79.99 / monthly $9.99 (50/50). Will I break even?" | Unit Economics Calculator (Python + module) · ROAS projection · what-if scenarios | | You don't know what to test next. | "I have 2 weeks before launch. What's the highest-leverage test?" | Decision-tree #7 (test priority) · Adapty 2026 win rates · sample-size minimums | | You want to copy what big apps do. | "How does Calm/Noom/Cal AI/Tinder structure their paywall?" | Annotated big-app teardowns with sources | | Your trial-to-paid is low. | "Trial-to-paid is 18% — why?" | Decision-tree #3 · Blinkist Trial Timeline pattern · notifications-lifecycle | | You're expanding to new markets. | "I'm US-only at $79.99/yr. Where should I expand and at what price?" | Localization · pricing index US=1.0 · AppsFlyer 2026 emerging-markets data | | You need better paywall copy. | "Write 3 headline variants for my running app paywall." | Copy library: 12 headline formulas · Copy Ladder · weak/risky words · locale notes | | Your refund rate is high. | "Annual refund rate is 7% — what's wrong?" | Refund management · Apple Consumption API · channel-level diagnostic |

If your situation isn't on this list, just send a screenshot and say "Audit my paywall". You get a concise screenshot-first audit by default; ask for a deep audit when you want the full breakdown.

---

🎁 What you get

| 🎯 Output | 📦 What's inside | 🔧 Powered by | |-----------|-----------------|----------------| | Pareto paywall audit (default) | Observed issues · top 3 fixes · missing context · next test · short sources | SKILL.md + runtime Pareto cards | | Deep paywall audit (on request) | Current state · main problem · access model + placement + presentation · screen content · copy variants · localization notes · ranked test plan · iOS review risks · Android delta | SKILL.md deep output | | Paywall design spec | Recommended model · screen spec · copy draft · compliance watchouts · first A/B test · short sources | SKILL.md design mode + runtime Pareto cards | | Unit-economics projection | LTV / ARPU / ROAS / breakeven across 8 horizons (7d → 4yr) · performance grading vs benchmarks · top-3 actions · what-if scenarios | unit-economics-calculator.md + Python script | | Direct answers to single questions | "Should I add a weekly plan?" → verdict + reason + one action. 35+ pre-answered scenarios. | indie-dev-faq.md | | Big-app pattern reference | Annotated teardowns with structure / copy / pricing / takeaway / source | teardowns.md | | Compliance triage | Apple Rule vs Field Report distinction · 7-level evidence ladder · printable 50+ item checklist | SKILL.md + audit-checklist.md | | Migration playbooks | Step-by-step migration from banned patterns (trial-toggle paywall today; future bans tomorrow) | docs/migrations/ |

---

🚫 The problem this solves

Most paywall advice is one of three things, all of them broken in 2026:

1. Generic web CRO — ignores App Store rules and gets your app rejected.
2. Hype-driven single-app case studies — no methodology, no sample size, may not transfer.
3. Outdated tactics — toggle paywalls were the 2024 gold standard; Apple started rejecting trial-toggle purchase screens under Guideline 3.1.2 in January 2026. Treat them as banned on iOS.

And most AI assistants compound the problem: they recommend whatever pattern they saw most often in 2023 training data, with no source, no compliance check, and no awareness of category economics.

✅ The fix

Paywall Pilot Framework grounds every recommendation in published evidence with confidence labels, never invents data, and explicitly states when to ignore benchmarks (e.g., when N<1,000 subs/variant or when your category is niche).

| Principle | How | |-----------|-----| | 🛡️ Compliance first | Every recommendation checked against Apple App Store Review Guidelines. Apple Rule > vendor data, always. | | 📊 7-level evidence ladder | Every claim labeled from Apple Rule down to Hypothesis — no unmarked assertions. | | 🔗 Sourced data | Every benchmark carries source + date + sample size. Canonical manifest lives in sources.json and is validated locally. | | 🏛️ Big-app teardowns | 11 annotated paywall analyses (Calm, Duolingo, Noom, Cal AI, Tinder, Strava, Headspace, Blinkist, Flo, ChatGPT, AI companions). | | 🎓 Academic foundations | Pricing psychology grounded in Tversky-Kahneman 1981 (Science), Anderson-Simester 2003, Thomas-Morwitz 2005, Ariely 2008, Cialdini — not just blog posts. | | ♻️ Full lifecycle | 10 stages from first purchase through win-back. Notifications, refunds, cohorts. | | 🧩 Modular | Core SKILL.md plus deep-dive modules loaded on demand by topic. | | 🧠 Common-sense overrides | Explicit "WHEN TO IGNORE BENCHMARKS" guidance for small N, niche category, recent launch. | | 🤖 LLM-agnostic | Works with Claude Code, Codex, ChatGPT, Cursor, Windsurf, Gemini — any AI tool with custom instructions. |

---

Modules

The Skill layer is split into a core SKILL.md plus deep-dive modules under modules/, an executable Python calculator, worked examples, and migration playbooks. Load on demand based on the task.

| Module | What's inside | |--------|---------------| | copy-library.md | The Copy Ladder (Outcome > Benefit > Feature), 12 headline formulas, benefit-bullet patterns, CTA templates with action+benefit pattern, weak/risky words list, length expansion factors and formality cheatsheet for 12+ locales, loading-screen copy, pricing-block templates | | teardowns.md | Annotated paywall breakdowns for Calm, Duolingo, Noom, Cal AI, Tinder, Strava, Headspace, Blinkist, Flo, ChatGPT, AI companions -- structure, copy, pricing, takeaway, source for each | | pricing-psychology.md | Tversky & Kahneman 1981 (framing, Science), Anderson & Simester 2003 ($9 endings, field experiment), Thomas & Morwitz 2005 (left-digit), Ariely 2008 (decoy with replication caveats), Cialdini 7 principles + 2024 Springer mobile-app strength data, anchor / decoy / charm / per-day / PPP frameworks, Hollow Middle 2026 trend, Apple monthly subscriptions with 12-month commitment, Apple SBP explainer | | decision-trees.md | 10 diagnostic flowcharts: access model choice, low-conversion triage, plan architecture, surface choice, when-to-test priority, compliance triage, refund diagnosis, vendor-data conflict resolution | | category-deep-dives.md | Per-category economics for Health & Fitness, Gaming, Productivity, Lifestyle, Education, AI, Photo & Video, Travel, Shopping, B2B; geography cuts NA / Western Europe / IN-SEA | | screen-anatomy.md | Visual hierarchy, F-pattern layout, thumb zone, spacing rhythm, pricing block anatomy, accessibility (WCAG AA, Dynamic Type, VoiceOver), dark mode,