@retiregolden/planner-ui 0.1.0

package/src/learn/content/fi-number-and-four-percent-rule.ts

@@ -0,0 +1,64 @@
+import type { LearningArticle } from '../learningRegistry'
+
+export const fiNumberAndFourPercentRuleArticle: LearningArticle = {
+  slug: 'fi-number-and-four-percent-rule',
+  title: 'The FI number and the 4% rule',
+  description: 'How to calculate your Financial Independence target portfolio using safe withdrawal rates.',
+  category: 'early-investing-fire',
+  tags: ['fi number', '4% rule', 'swr', 'safe withdrawal rate', 'sequence risk'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-06-29',
+  reviewCadence: 'stable',
+  sourceUrls: [
+    'https://www.retireby40.org/safe-withdrawal-rate-swr-4-rule/',
+  ],
+  relatedArticles: [
+    'what-is-fire',
+    'savings-rate-biggest-lever',
+    'sequence-of-returns-risk',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/results', '/plan/:planId/assumptions'],
+  currentYearSensitive: false,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Your **FI Number** is the total portfolio balance you need to reach financial independence. Once your investable assets reach this target, you can theoretically stop working and live off withdrawals forever.',
+    },
+    { type: 'heading', text: 'Three key takeaways' },
+    {
+      type: 'list',
+      items: [
+        'The 4% rule of thumb states you can safely withdraw 4% of your starting portfolio in year one, and adjust that dollar amount for inflation each year.',
+        'SWR stands for Safe Withdrawal Rate. Lowering your SWR (e.g. to 3.5%) increases your FI number but adds safety.',
+        'The formula to compute the target portfolio size is: FI Target = Annual Spending ÷ SWR.',
+      ],
+    },
+    {
+      type: 'formula',
+      expression: 'FI = S / SWR',
+      where: [
+        { symbol: 'FI', meaning: 'Financial Independence target portfolio (today\'s dollars)' },
+        { symbol: 'S', meaning: 'Annual retirement spending plus taxes and penalties' },
+        { symbol: 'SWR', meaning: 'Safe Withdrawal Rate (expressed as a decimal, e.g. 0.04)' },
+      ],
+      basis: 'today',
+      note: 'This formula assumes a flat withdrawal rate and does not account for variable spending phases.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Treating the 4% rule as a guarantee instead of a planning lens.',
+        'Using spending before taxes when your plan will need taxable withdrawals.',
+        'Forgetting that a 40- or 50-year early retirement can be more fragile than a traditional 30-year horizon.',
+      ],
+    },
+    { type: 'heading', text: 'Where this shows up in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden calculates your **FI Target Portfolio** based on the Safe Withdrawal Rate (SWR) you configure under the Assumptions section. By default, it uses a 4% rate, but you can customize this to see how a more conservative 3.25% or aggressive 4.5% affects your timeline.',
+    },
+  ],
+}

package/src/learn/content/filling-a-tax-bracket-with-roth-conversions.ts

@@ -0,0 +1,98 @@
+/**
+ * "Filling a tax bracket with Roth conversions" - a Withdrawals and Roth P0 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const fillingTaxBracketArticle: LearningArticle = {
+  slug: 'filling-a-tax-bracket-with-roth-conversions',
+  title: 'Filling a tax bracket with Roth conversions',
+  description: 'Converting just enough to use up a low bracket without spilling over.',
+  category: 'withdrawals-roth',
+  tags: ['roth conversion', 'tax bracket', 'taxable income', 'marginal rate', 'fill to target'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-06-19',
+  reviewCadence: 'annual',
+  sourceUrls: ['https://www.irs.gov/filing/federal-income-tax-rates-and-brackets'],
+  relatedArticles: [
+    'roth-conversion-basics',
+    'marginal-vs-effective-tax-rate',
+    'why-roth-conversions-raise-other-costs',
+    'tax-cliffs-and-bracket-edges',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/strategy', '/plan/:planId/results', '/plan/:planId/optimize'],
+  currentYearSensitive: true,
+  priority: 'P0',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Filling a tax bracket means converting enough pre-tax money to use the remaining room in a chosen tax bracket, then stopping before the next bracket starts. It is a controlled way to ask: "How much can I convert before the next dollar gets more expensive?"',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'The target is usually **taxable income**, not gross income.',
+        'The conversion fills the space between your baseline taxable income and the top of the chosen bracket.',
+        'Bracket filling is only one lens. MAGI cliffs, IRMAA, ACA credits, and Social Security taxation can matter more than the bracket line.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Imagine taxable income as a stack of shelves. Your wages, pensions, taxable Social Security, RMDs, and other income already fill part of the stack. A Roth conversion adds more income. Filling a bracket means adding conversion dollars until the current shelf is full, then stopping.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/tax-bracket-fill.webp' },
+      caption:
+        'Bracket filling uses the remaining space in a lower tax bracket before conversion income spills into the next bracket.',
+      alt: 'A stack of tax bracket shelves is partly filled by baseline income, with conversion dollars filling the remaining space below a higher bracket marker.',
+    },
+    { type: 'heading', text: 'A quick formula' },
+    {
+      type: 'formula',
+      expression: 'conversion room = bracket ceiling - baseline taxable income',
+      where: [
+        { symbol: 'bracket ceiling', meaning: 'the top of the tax bracket you are willing to fill' },
+        { symbol: 'baseline taxable income', meaning: 'taxable income before the discretionary conversion' },
+        { symbol: 'conversion room', meaning: 'the rough conversion amount that fits before crossing that ceiling' },
+      ],
+      basis: 'nominal',
+      note: 'The app uses the federal tax engine and year-specific plan details. This formula is only the mental model; Social Security taxation and deductions can make the real result kinked.',
+    },
+    { type: 'heading', text: 'Why RetireGolden sizes it carefully' },
+    {
+      type: 'prose',
+      md: 'RetireGolden\'s fill-to-target strategy sizes conversions by testing the federal tax result, not by using a one-line estimate. That matters because deductions, taxable Social Security, and other inputs can make taxable income move differently than the conversion amount itself.',
+    },
+    {
+      type: 'table',
+      caption: 'What can change the bracket-filling answer.',
+      columns: ['Input', 'Why it matters', 'Where to check'],
+      rows: [
+        ['Filing status', 'Bracket ceilings differ by filing status', 'Household'],
+        ['Existing income', 'Wages, pensions, RMDs, and taxable benefits may already fill the bracket', 'Income and Results'],
+        ['Deductions', 'Taxable income starts after deductions', 'Assumptions and Results'],
+        ['Capital gains', 'They sit on a separate ladder but can still interact with taxable income', 'Results'],
+        ['MAGI-sensitive costs', 'A bracket target can still cross an IRMAA or ACA boundary', 'Results and healthcare inputs'],
+      ],
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Using gross income when the strategy targets taxable income.',
+        'Stopping at the bracket line but ignoring MAGI-based costs.',
+        'Assuming this year\'s best bracket-fill is the best lifetime strategy.',
+        'Forgetting that tax brackets and other thresholds can change over time.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Strategy** to set a fill-to-target Roth conversion rule. Then use **Results** to inspect taxable income, tax, MAGI, conversions, and later RMDs year by year.',
+    },
+  ],
+}

package/src/learn/content/funded-ratio.ts

@@ -0,0 +1,70 @@
+import type { LearningArticle } from '../learningRegistry'
+
+export const fundedRatioArticle: LearningArticle = {
+  slug: 'funded-ratio',
+  title: 'The funded ratio: pension accounting for your household',
+  description:
+    'What share of your essential retirement spending is already guaranteed? Discounting the floor on the TIPS curve answers it the way a pension actuary would.',
+  category: 'risk-uncertainty',
+  tags: ['funded ratio', 'safety-first', 'income floor', 'present value', 'tips', 'essential spending'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-07-08',
+  reviewCadence: 'stable',
+  sourceUrls: [
+    'https://retirementresearcher.com/what-is-a-funded-ratio/',
+    'https://www.financialplanningassociation.org/article/journal/JAN14-safety-first-retirement-planning',
+    'https://home.treasury.gov/resource-center/data-chart-center/interest-rates',
+  ],
+  relatedArticles: ['tips-ladders', 'social-security-bridge', 'understanding-monte-carlo-success-rate', 'building-a-retirement-spending-budget'],
+  relatedPlannerRoutes: ['/plan/:planId/results', '/plan/:planId/income-floor', '/plan/:planId/spending'],
+  currentYearSensitive: false,
+  priority: 'P2',
+  featured: false,
+  blocks: [
+    {
+      type: 'prose',
+      md: 'A pension fund never describes itself with a success percentage. It states a **funded ratio**: the value of what it owns against the present value of what it has promised to pay. Wade Pfau and the safety-first school apply the same lens to a household: treat your essential spending as the pension you have promised *yourself*, value it honestly, and ask how much of it is already covered by income that arrives no matter what markets do.',
+    },
+    {
+      type: 'formula',
+      expression: 'funded ratio = PV(guaranteed real income) ÷ PV(essential spending)',
+      where: [
+        { symbol: 'PV', meaning: 'present value, discounting each future real dollar at the Treasury real-yield curve' },
+        { symbol: 'guaranteed income', meaning: 'Social Security, pensions, annuities, and TIPS-ladder payouts' },
+        { symbol: 'essential spending', meaning: 'the required floor: must-fund lifestyle plus healthcare, debt, property costs' },
+      ],
+      basis: 'today',
+      note: 'Discounting at TIPS yields is the honest rate: it is what a guaranteed real dollar actually costs today.',
+    },
+    { type: 'heading', text: 'Why the TIPS curve is the right discount rate' },
+    {
+      type: 'prose',
+      md: 'Discounting essential spending at an assumed portfolio return (say 6%) quietly assumes the portfolio delivers — which is precisely what cannot be assumed about spending you *must* fund. The defensible question is: **what would it cost today to guarantee this dollar?** That price is set by the Treasury real-yield curve, because a TIPS of matching maturity is the instrument that actually delivers a guaranteed real dollar on that date. Higher real yields make the floor cheaper to defease; lower ones make it dearer. Your funded ratio therefore moves with the bond market even when your spending doesn\'t — exactly like a real pension\'s.',
+    },
+    { type: 'heading', text: 'Reading your number' },
+    {
+      type: 'table',
+      columns: ['Funded ratio', 'What it says', 'Typical response'],
+      rows: [
+        ['≥ 100%', 'The essential floor is fully defeased by guaranteed income', 'Invest the rest for growth/legacy with a clear conscience'],
+        ['80–100%', 'Most of the floor is guaranteed; the gap rides on the portfolio', 'Decide deliberately how much of the gap to lock in (ladder, delayed SS, annuity)'],
+        ['< 80%', 'A large share of essentials depends on market outcomes', 'Look hard at the levers: delay Social Security, trim the floor, or dedicate assets'],
+      ],
+    },
+    {
+      type: 'prose',
+      md: 'RetireGolden computes both sides from your own projection — the same yearly ledger that already knows your Social Security (after any trust-fund haircut you assume), pensions, annuities, TIPS ladders, survivor years, healthcare, and debt — deflates them to today\'s dollars, and discounts on the embedded TIPS curve. The Results page shows the ratio, both present values, and the unfunded gap; the Insights page raises a card when the floor is materially underfunded.',
+    },
+    { type: 'heading', text: 'Funded ratio vs. Monte Carlo success' },
+    {
+      type: 'prose',
+      md: 'The two lenses answer different questions and disagree in useful ways. Monte Carlo asks *"how often does the whole plan work across simulated markets?"* — it rewards expected growth. The funded ratio asks *"how much of the essential part is guaranteed regardless of markets?"* — it ignores expected growth on purpose. A plan can show 95% success and a 60% funded ratio: it will probably work, **and** its essentials lean heavily on that "probably". Neither number is the verdict; together they tell you whether risk is being taken with money that can afford it.',
+    },
+    {
+      type: 'callout',
+      tone: 'note',
+      md: 'The ratio is only as meaningful as your floor definition. If you have not separated required spending from lifestyle on the Spending page, the "floor" is your entire budget and the ratio will read pessimistically low.',
+    },
+  ],
+}

package/src/learn/content/healthcare-after-65.ts

@@ -0,0 +1,103 @@
+/**
+ * "Healthcare after age 65" - a Healthcare P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const healthcareAfter65Article: LearningArticle = {
+  slug: 'healthcare-after-65',
+  title: 'Healthcare after age 65',
+  description: 'How Medicare parts and premiums fit into spending.',
+  category: 'healthcare',
+  tags: ['medicare', 'part b', 'part d', 'medigap', 'medicare advantage', 'irmaa', 'healthcare spending'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-19',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.medicare.gov/basics/get-started-with-medicare/get-more-coverage/your-coverage-options',
+    'https://www.medicare.gov/basics/get-started-with-medicare/sign-up',
+    'https://www.medicare.gov/basics/costs/medicare-costs',
+  ],
+  relatedArticles: [
+    'irmaa-two-year-lookback',
+    'healthcare-before-65',
+    'agi-magi-and-taxable-income',
+    'long-term-care-costs-and-insurance',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/spending', '/plan/:planId/results', '/plan/:planId/assumptions'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'At 65, healthcare planning usually shifts from a pre-Medicare bridge to Medicare. That does not mean healthcare becomes free. Premiums, drug coverage, supplemental coverage, out-of-pocket costs, and IRMAA can still be a major retirement expense.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Medicare has multiple parts and coverage choices, not one single premium.',
+        'IRMAA can raise premiums when MAGI from two years earlier is above a tier.',
+        'RetireGolden models premium pressure, but it does not replace Medicare plan shopping.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Many retirees pay a Part B premium. They may also pay for Part D drug coverage, Medicare Advantage, Medigap, dental, vision, hearing, or other supplemental coverage. Some costs are premiums; others are deductibles, copays, and uncovered services.\n\nA retirement projection does not need to pick the perfect Medicare plan to be useful. It does need a reasonable healthcare spending line, and it needs to understand when income can raise premiums through IRMAA.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/healthcare-after-65.webp' },
+      caption:
+        'After 65, Medicare costs are a stack: base premiums, optional coverage, out-of-pocket assumptions, and possible IRMAA surcharges.',
+      alt: 'Coverage tiles for hospital, medical, drug, and supplemental care flow into a Medicare premium bucket, while an income-threshold marker sends a surcharge ribbon into the same bucket.',
+    },
+    { type: 'heading', text: 'What belongs in the planning estimate' },
+    {
+      type: 'table',
+      caption: 'Post-65 healthcare costs are not all modeled the same way.',
+      columns: ['Cost type', 'How to think about it', 'RetireGolden treatment'],
+      rows: [
+        ['Part B premium', 'Common monthly Medicare premium', 'Added automatically from the parameter pack at 65+'],
+        ['IRMAA', 'Income-related surcharge for higher MAGI', 'Modeled with the two-year lookback'],
+        ['Part D surcharge', 'Drug-plan-related IRMAA surcharge', 'Modeled from the parameter pack where available'],
+        ['Supplemental or Advantage premium', 'Plan-specific monthly cost', 'Enter as Medicare extras'],
+        ['Out-of-pocket medical costs', 'Deductibles, copays, uncovered care', 'Include in broader spending or a separate goal/assumption'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Adams household',
+      assumptions: [
+        { label: 'Age', value: 'Both spouses are 67 and on Medicare' },
+        { label: 'Regular premium line', value: '$520 a month each for Part B, drug coverage, and supplemental coverage' },
+        { label: 'Lookback income event', value: 'A $90,000 Roth conversion two years earlier adds an estimated $180 a month each' },
+      ],
+      summary:
+        'Their medical needs did not change, but the plan-year healthcare cost rises by about **$4,320** for the couple. That delayed premium jump belongs in the conversion trade-off.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden automatically adds Part B and IRMAA for people age 65 and older. The **Medicare extras** input is where you can add monthly amounts for Part D, Medigap, Medicare Advantage, or other recurring coverage costs that are not automatically modeled.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Assuming Medicare removes the need for a healthcare budget.',
+        'Entering only supplemental premiums and forgetting that Part B is added automatically.',
+        'Ignoring IRMAA when planning conversions around ages 63 and later.',
+        'Using RetireGolden as a substitute for Medicare enrollment, provider-network, or drug-formulary research.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Spending** for Medicare extras, **Assumptions** for healthcare inflation and recent MAGI, and **Results** to see annual healthcare costs after Medicare begins.',
+    },
+  ],
+}

package/src/learn/content/healthcare-before-65.ts

@@ -0,0 +1,104 @@
+/**
+ * "Healthcare before age 65" - a Healthcare P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const healthcareBefore65Article: LearningArticle = {
+  slug: 'healthcare-before-65',
+  title: 'Healthcare before age 65',
+  description: 'Covering the gap years before Medicare eligibility.',
+  category: 'healthcare',
+  tags: ['healthcare before 65', 'aca', 'marketplace', 'cobra', 'early retirement', 'magi'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-19',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.healthcare.gov/retirees/',
+    'https://www.healthcare.gov/have-job-based-coverage/cobra/',
+    'https://www.healthcare.gov/lower-costs/',
+  ],
+  relatedArticles: [
+    'aca-premium-tax-credits-and-magi',
+    'agi-magi-and-taxable-income',
+    'why-roth-conversions-raise-other-costs',
+    'healthcare-after-65',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/spending', '/plan/:planId/results', '/plan/:planId/assumptions'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Retiring before 65 often means solving a healthcare bridge. Medicare has not started yet, but employer coverage may have ended. The bridge can be affordable, expensive, or fragile depending on coverage options and income.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'The pre-65 years need their own healthcare plan, not just a spending estimate.',
+        'Marketplace premiums may be reduced by ACA premium tax credits, depending on MAGI.',
+        'Roth conversions and withdrawals can change healthcare costs in the same years they change taxes.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'A pre-65 retiree may use retiree coverage, a spouse\'s employer plan, COBRA continuation, a marketplace plan, or a direct plan outside the marketplace. Those options have different premium costs, networks, deductibles, and subsidy rules.\n\nFor retirement planning, the big question is cash flow: what full premium should the plan assume, and does income qualify the household for a premium tax credit?',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/healthcare-before-65.webp' },
+      caption:
+        'The pre-65 healthcare bridge can use several coverage paths before Medicare begins.',
+      alt: 'A bridge of coverage stations connects work coverage to a later Medicare bucket, with marketplace, continuation, spouse, and household icons along the way.',
+    },
+    { type: 'heading', text: 'Common bridge options' },
+    {
+      type: 'table',
+      caption: 'Pre-65 coverage choices to model or compare.',
+      columns: ['Option', 'What to check', 'Planning pressure'],
+      rows: [
+        ['Spouse or partner employer plan', 'Eligibility, premium share, networks', 'May be simpler if available'],
+        ['Retiree coverage', 'Employer rules and whether it coordinates with Medicare later', 'Can be valuable but is not universal'],
+        ['COBRA continuation', 'Duration and full premium cost', 'Can bridge a short gap but may be expensive'],
+        ['ACA marketplace plan', 'Premium tax credit, networks, deductibles', 'MAGI management can matter'],
+        ['Direct non-marketplace plan', 'Premium and coverage terms', 'May not qualify for marketplace credits'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Lee household',
+      assumptions: [
+        { label: 'Retirement age', value: '62' },
+        { label: 'Bridge length', value: 'Three years before Medicare at age 65' },
+        { label: 'Coverage estimate', value: '$1,200 monthly marketplace premium before any credit' },
+        { label: 'Income choice', value: '$18,000 Roth withdrawal does not raise MAGI, but an $18,000 IRA withdrawal does' },
+      ],
+      summary:
+        'The same $18,000 of spending money can land differently. If it comes from the IRA, the Lees may owe tax and may lose part of the healthcare credit; if it comes from Roth, the premium estimate may stay lower.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden lets you enter the full pre-65 monthly premium per person and decide whether to apply the ACA credit. The model estimates premiums annually, not plan-by-plan. It does not choose networks, deductibles, providers, or drug coverage.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Using today\'s employer payroll deduction as if it were the full retiree premium.',
+        'Ignoring deductibles and out-of-pocket risk.',
+        'Testing Roth conversions without checking MAGI-driven premiums.',
+        'Assuming the same option will be best for every year before Medicare.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Spending** to enter pre-65 premiums and ACA credit settings. Use **Assumptions** for healthcare inflation and recent MAGI. Use **Results** to inspect healthcare costs year by year.',
+    },
+  ],
+}

package/src/learn/content/historical-vs-random-return-models.ts

@@ -0,0 +1,101 @@
+/**
+ * "Historical returns vs random return models" - a Risk and Uncertainty P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const historicalVsRandomReturnModelsArticle: LearningArticle = {
+  slug: 'historical-vs-random-return-models',
+  title: 'Historical returns vs random return models',
+  description: 'Two ways to generate possible futures and how they differ.',
+  category: 'risk-uncertainty',
+  tags: ['historical returns', 'random returns', 'monte carlo', 'market model', 'bootstrap'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'stable',
+  sourceUrls: [
+    'https://www.investor.gov/introduction-investing/investing-basics/glossary/monte-carlo-simulation',
+    'https://www.investor.gov/introduction-investing/investing-basics/what-risk',
+  ],
+  relatedArticles: [
+    'understanding-monte-carlo-success-rate',
+    'what-monte-carlo-proves',
+    'sequence-of-returns-risk',
+    'inflation-risk',
+    'how-assumptions-change-the-answer',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/monte-carlo', '/plan/:planId/assumptions', '/plan/:planId/scenarios'],
+  currentYearSensitive: false,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'A retirement projection needs some way to create possible future market paths. RetireGolden offers a random lognormal model and several historical models. The choice matters because each model preserves different kinds of risk.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'A random model starts from assumptions about expected return, volatility, inflation, and correlation.',
+        'A historical model resamples actual market years, so it can preserve some real-world patterns from the historical record.',
+        'No market model is the truth. The goal is to see whether the plan only works under one narrow version of risk.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'A lognormal model generates new return and inflation paths around your assumptions. A historical model starts from actual years in the embedded data set and resamples them. Historical independent years shuffle the deck one year at a time. Historical blocks keep short streaks together. Full-sequence replay starts in a random historical year and lets the historical order unfold.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/historical-vs-random-return-models.webp' },
+      caption:
+        'Random and historical models are two different machines for turning assumptions into retirement paths.',
+      alt: 'One machine draws smooth random market paths from a bell-shaped source, while another shuffles cards of historical market years into retirement paths.',
+    },
+    {
+      type: 'table',
+      caption: 'How RetireGolden market models differ.',
+      columns: ['Model', 'What it does', 'What to watch'],
+      rows: [
+        ['Lognormal', 'Draws each year around expected returns and inflation, with linked return and inflation shocks', 'Depends heavily on volatility and inflation assumptions'],
+        ['Historical independent years', 'Samples historical years one at a time', 'Can break real-world streaks apart'],
+        ['Historical 5-year blocks', 'Samples blocks so bad or good stretches can stay together', 'Still depends on the historical record available'],
+        ['Historical full-sequence replay', 'Starts in a random historical year and replays the sequence from there', 'Can overemphasize the limited set of historical paths'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Chen household',
+      assumptions: [
+        { label: 'Lognormal result', value: '88% success when returns are sampled around the plan assumptions' },
+        { label: 'Historical block result', value: '74% success when rough market clusters stay together' },
+        { label: 'Difference', value: '14 percentage points of success rate' },
+      ],
+      summary:
+        'The 14-point gap is the lesson. The plan is not simply good or bad; it is sensitive to whether bad market years arrive as isolated shocks or as a streak.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'The **Monte Carlo** screen keeps your expected returns as the center of modeled returns. In lognormal mode, your inflation assumption is also the center of the inflation paths. In historical modes, inflation comes from the sampled historical years, so switching models can change both market variation and the inflation path source. If a strategy only looks good under one model, treat that as a reason to inspect the assumptions more closely.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Calling historical results "more accurate" just because they use real years.',
+        'Calling random results "fake" even though all future paths are unknown.',
+        'Changing equity weight or volatility and then blaming the entire difference on the strategy.',
+        'Ignoring inflation behavior when comparing market models.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'On **Monte Carlo**, run the same plan under lognormal, historical independent years, historical blocks, and historical full-sequence replay. If the conclusion changes materially, use **Scenarios** to test ways to add cushion.',
+    },
+  ],
+}

package/src/learn/content/how-assumptions-change-the-answer.ts

@@ -0,0 +1,105 @@
+/**
+ * "How assumptions change the answer" - a Start Here P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const howAssumptionsChangeAnswerArticle: LearningArticle = {
+  slug: 'how-assumptions-change-the-answer',
+  title: 'How assumptions change the answer',
+  description: 'How small changes to returns, inflation, spending, and longevity move the result.',
+  category: 'start-here',
+  tags: ['assumptions', 'sensitivity', 'inflation', 'returns', 'planning basics'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'stable',
+  sourceUrls: [],
+  relatedArticles: [
+    'three-big-questions-spending-time-risk',
+    'using-assumptions-and-provenance',
+    'sensitivity-testing-what-changes-the-answer',
+    'inflation-risk',
+    'longevity-risk',
+  ],
+  relatedPlannerRoutes: [
+    '/plan/:planId/assumptions',
+    '/plan/:planId/spending',
+    '/plan/:planId/results',
+    '/plan/:planId/scenarios',
+    '/plan/:planId/monte-carlo',
+  ],
+  currentYearSensitive: false,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'A retirement projection can feel precise because the output has exact dollars and exact years. The precision is useful, but the answer is still built from assumptions. When an assumption changes, the projection is answering a different question.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Assumptions are levers, not background decoration.',
+        'The most important tests usually change spending, retirement age, return, inflation, and planning age.',
+        'Change one lever at a time when you want to learn what actually moved the result.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'A plan has two kinds of inputs: facts you can know now and assumptions about the future. Current balances, birth dates, and account types are facts. Future returns, inflation, healthcare inflation, lifespan, tax law, and spending behavior are assumptions. A projection is strongest when you know which inputs are facts, which are estimates, and which are stress tests.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/assumptions-change-answer.webp' },
+      caption:
+        'Changing one major assumption at a time makes it easier to see which lever is driving the result.',
+      alt: 'An illustrated control panel with separate sliders for spending, inflation, return, and time feeding a retirement path.',
+    },
+    {
+      type: 'table',
+      caption: 'Common assumptions and how they tend to move the plan.',
+      columns: ['Assumption', 'What it changes', 'What to inspect'],
+      rows: [
+        ['Spending', 'The annual amount the portfolio must support', 'Shortfalls, depletion year, and withdrawal size'],
+        ['Retirement age', 'Years of saving and years of withdrawals', 'Account balances at retirement and Social Security timing'],
+        ['Return', 'Growth before and during retirement', 'Ending estate and Monte Carlo success rate'],
+        ['Inflation', 'Future cost of the same lifestyle', 'Today-dollar results and late-life spending pressure'],
+        ['Planning age', 'How long the plan must keep working', 'Late-life balances and survivor years'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Kim household',
+      assumptions: [
+        { label: 'Baseline', value: 'Retire at 65, spend $92,000 per year, plan through age 95' },
+        { label: 'First test', value: 'Raise spending by 10%' },
+        { label: 'Second test', value: 'Keep spending unchanged, but lower the default return by 1 point' },
+      ],
+      summary:
+        'If both tests weaken the plan, they should not be mixed together at first. Separate tests show whether the problem is lifestyle cost, return sensitivity, or both.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden lets you use **Assumptions** for the plan-wide levers, **Spending** for lifestyle costs, **Scenarios** for named what-if changes, and **Monte Carlo** for market paths around the same plan. The deterministic Results page tells you what happens under one assumption set. Scenarios and Monte Carlo tell you how fragile that answer is.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Changing several assumptions at once and then not knowing which one mattered.',
+        'Using optimistic returns to compensate for spending that may be too high.',
+        'Looking only at the ending estate and missing a shortfall in an earlier year.',
+        'Treating planning age as a prediction instead of a resilience test.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Start in **Assumptions** and **Spending**, read the baseline in **Results**, then make one named change in **Scenarios**. If the scenario changes the result a lot, it has earned more attention.',
+    },
+  ],
+}