@retiregolden/planner-ui 0.1.0

package/src/learn/content/what-changes-when-you-move-states.ts

@@ -0,0 +1,141 @@
+/**
+ * "What changes when you move states" - a Taxes P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const whatChangesWhenYouMoveStatesArticle: LearningArticle = {
+  slug: 'what-changes-when-you-move-states',
+  title: 'What changes when you move states',
+  description: 'How domicile, split-year moves, pension source rules, and model boundaries affect a relocation comparison.',
+  category: 'taxes',
+  tags: ['state tax', 'relocation', 'domicile', 'part-year resident', 'pension', 'retirement income'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-07-09',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.irs.gov/businesses/small-businesses-self-employed/state-government-websites',
+    'https://www.law.cornell.edu/uscode/text/4/114',
+    'https://www.tax.ny.gov/pit/file/pit_definitions.htm',
+    'https://www.ftb.ca.gov/file/personal/residency-status/part-year-and-nonresident.html',
+  ],
+  relatedArticles: [
+    'state-income-taxes-in-retirement',
+    'using-scenarios-to-compare-choices',
+    'assumption-state-tax-override',
+    'real-estate-home-equity-and-debt',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/relocation', '/plan/:planId/household'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Moving to another state can change which state income-tax rules apply to your plan, but it does not turn relocation into a simple tax ranking. This article explains what RetireGolden can price, what depends on legal residency facts, and what belongs outside the model.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'A move changes your state of residence for future years only if your real-world domicile and filing facts support it.',
+        'A split-year move can put part of a calendar year under the old state and part under the new state.',
+        'RetireGolden compares modeled state and local **income tax** effects; property tax, sales tax, insurance, healthcare access, and lifestyle tradeoffs still need separate judgment.',
+      ],
+    },
+    { type: 'heading', text: 'What actually changes' },
+    {
+      type: 'prose',
+      md: 'State income tax is not one universal rule. A state may tax Social Security differently, exclude some retirement income, treat public pensions differently from private retirement income, tax capital gains like wages, or have no broad income tax at all. When you compare states, RetireGolden reruns your actual year-by-year plan through the destination state rules instead of using a generic "tax friendly" list.',
+    },
+    {
+      type: 'table',
+      caption: 'Pieces to separate before treating a move as a tax win.',
+      columns: ['Moving piece', 'Why it matters', 'RetireGolden lens'],
+      rows: [
+        [
+          'Domicile and residence',
+          'States decide who counts as a resident under their own rules. Intent, homes, days, and records can matter.',
+          'You enter the current state and planned state moves; RetireGolden does not prove legal domicile.',
+        ],
+        [
+          'Split-year move',
+          'The move year may be taxed partly by each state, and source income can still belong to the old state.',
+          'A Relocation Compare move year models a July split-year move, matching the Household screen.',
+        ],
+        [
+          'Retirement-income rules',
+          'Social Security, IRA withdrawals, private pensions, and public pensions may not all get the same state treatment.',
+          'Modeled packs price Social Security treatment and retirement-income exclusions through the normal tax ledger.',
+        ],
+        [
+          'Local rate and spending knobs',
+          'City income tax or cost of living can overwhelm a state-tax headline.',
+          'Optional flat inputs let you approximate them, but they are broad assumptions you control.',
+        ],
+        [
+          'Out-of-model costs',
+          'Property tax, sales tax, homeowners insurance, healthcare networks, family support, and climate risk can dominate the decision.',
+          'The comparison names these boundaries instead of pretending income tax chooses the best state.',
+        ],
+      ],
+    },
+    { type: 'heading', text: 'Domicile is more than an address' },
+    {
+      type: 'prose',
+      md: 'For tax purposes, a state move usually turns on facts, not just the mailing address on an account. State guidance commonly describes domicile as your permanent home and the place you intend to return to after being away. Some states also have statutory-residency tests tied to days in the state and a maintained home.',
+    },
+    {
+      type: 'callout',
+      tone: 'note',
+      md: 'Practical translation: if a plan says "move to Florida in 2030," that is a modeling assumption. Your actual filing position may depend on leases or deeds, voter registration, driver license, doctors, professional ties, days present, and records showing where your life is centered.',
+    },
+    { type: 'heading', text: 'Pension source rules have a special federal limit' },
+    {
+      type: 'prose',
+      md: 'A former state generally cannot tax certain retirement income after you are no longer a resident or domiciliary of that state. Federal law covers many common retirement-payment categories, including qualified plans, individual retirement plans, 403(b) arrangements, eligible 457 plans, and governmental plans. That does not mean the old state loses every possible tax claim: real estate income, business income, wages earned there, and other source items can still have their own rules.',
+    },
+    {
+      type: 'callout',
+      tone: 'warn',
+      md: 'RetireGolden models retirement-plan income inside a household projection. It is not a state residency audit tool, and it does not allocate every possible nonresident source-income item.',
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Hill household',
+      assumptions: [
+        { label: 'Current plan', value: 'Resident in a taxed state with IRA withdrawals, Social Security, taxable gains, and a public pension' },
+        { label: 'Candidate A', value: 'Move to a no-broad-income-tax state in 2030' },
+        { label: 'Candidate B', value: 'Move to a state that taxes income but excludes more retirement income' },
+        { label: 'Lifestyle adjustment', value: 'Candidate B is closer to family, but spending is modeled 6% higher' },
+      ],
+      summary:
+        'The lowest state-income-tax row is not automatically the best life choice. The table helps isolate the tax difference, while scenarios and spending assumptions capture the tradeoffs the tax model cannot know.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'The Relocation Compare page takes candidate states and runs each one as a scenario patch over existing plan fields: household state, planned state moves, local income-tax rate, and baseline spending. The row you see is the same kind of plan run you would get by editing the plan by hand, which makes "Add as scenario" a clean way to keep a candidate for side-by-side comparison.',
+    },
+    {
+      type: 'prose',
+      md: 'Driver details explain major state income-tax levers by re-pricing the state tax line with one rule neutralized at a time: Social Security treatment, retirement-income exclusions, separate public-pension rules when modeled, and capital-gain treatment. Those drivers explain the state-tax line; they do not claim to measure housing, healthcare, property tax, or quality of life.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Treating a no-income-tax state as automatically cheaper after housing, property tax, insurance, sales tax, and travel are counted.',
+        'Assuming the old state stops mattering on the exact day you change your address, even when source income or residency facts are complicated.',
+        'Comparing states with different spending assumptions and then reading the result as a pure tax difference.',
+        'Forgetting that a flat state-tax override can mask the modeled state packs. Clear or document the override before relying on a state-by-state comparison.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Household** to set your current state and any planned move already in the baseline plan. Use **Relocation Compare** to test up to five candidate states without changing the plan. Use **Add as scenario** when a candidate is worth keeping, then review **Scenarios** and **Results** for the full plan tradeoff.',
+    },
+  ],
+}

package/src/learn/content/what-is-fire.ts

@@ -0,0 +1,65 @@
+import type { LearningArticle } from '../learningRegistry'
+
+export const whatIsFireArticle: LearningArticle = {
+  slug: 'what-is-fire',
+  title: 'What is FIRE? Lean, Fat, Coast, and Barista',
+  description: 'An overview of the Financial Independence, Retire Early movement and its strategies.',
+  category: 'early-investing-fire',
+  tags: ['fire', 'lean fire', 'fat fire', 'coast fire', 'barista fire', 'early retirement'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-29',
+  reviewCadence: 'stable',
+  sourceUrls: [
+    'https://www.investopedia.com/terms/f/financial-independence-retire-early-fire.asp',
+  ],
+  relatedArticles: [
+    'savings-rate-biggest-lever',
+    'fi-number-and-four-percent-rule',
+    'how-to-model-accumulation',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/results'],
+  currentYearSensitive: false,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'FIRE stands for **Financial Independence, Retire Early**. It is a lifestyle movement defined by high savings rates and intentional living. The ultimate goal is to build a retirement portfolio large enough that paid work becomes completely optional.',
+    },
+    { type: 'heading', text: 'Three key takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Financial independence means your assets generate enough income to cover your expenses.',
+        'Retire early is optional: many people in the movement continue working on their own terms.',
+        'Different flavors of FIRE cater to different spending levels and career transitions.',
+      ],
+    },
+    { type: 'heading', text: 'The four flavors of FIRE' },
+    {
+      type: 'table',
+      caption: 'The main paths to Financial Independence.',
+      columns: ['Flavor', 'Description', 'Lifestyle goal'],
+      rows: [
+        ['Lean FIRE', 'Lower-spending lifestyle with a smaller FI target.', 'Extremely low expenses and maximum savings.'],
+        ['Fat FIRE', 'Higher-spending lifestyle with a larger FI target.', 'More room for comfort, travel, or location flexibility.'],
+        ['Coast FIRE', 'Front-loading savings early, then letting investment compounding carry you to retirement.', 'Work only to cover living expenses, not retirement savings.'],
+        ['Barista FIRE', 'Retiring from a primary high-stress career but keeping a low-stress part-time job.', 'Use part-time income and employer healthcare to bridge the gap.'],
+      ],
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Treating FIRE as one rigid lifestyle instead of a set of planning tradeoffs.',
+        'Ignoring healthcare, taxes, and sequence risk when estimating the portfolio needed.',
+        'Assuming work must stop completely once financial independence is reached.',
+      ],
+    },
+    { type: 'heading', text: 'Where this shows up in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'In RetireGolden, you can view your **FI Target Portfolio** and **Coast-FIRE Target** in the results dashboard. These derived metrics analyze your simulated accounts to pinpoint the year your net worth supports your retirement spending.',
+    },
+  ],
+}

package/src/learn/content/what-monte-carlo-proves.ts

@@ -0,0 +1,98 @@
+/**
+ * "What Monte Carlo does and does not prove" - a Risk and Uncertainty P0 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const whatMonteCarloProvesArticle: LearningArticle = {
+  slug: 'what-monte-carlo-proves',
+  title: 'What Monte Carlo does and does not prove',
+  description: 'How to read a success rate as a model statistic, not a promise.',
+  category: 'risk-uncertainty',
+  tags: ['monte carlo', 'success rate', 'simulation', 'model risk', 'forecasting'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'stable',
+  sourceUrls: ['https://www.investor.gov/introduction-investing/investing-basics/glossary/monte-carlo-simulation'],
+  relatedArticles: [
+    'understanding-monte-carlo-success-rate',
+    'why-95-percent-is-not-a-guarantee',
+    'sequence-of-returns-risk',
+    'historical-vs-random-return-models',
+    'how-to-read-a-retirement-projection',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/monte-carlo', '/plan/:planId/scenarios', '/plan/:planId/optimize'],
+  currentYearSensitive: false,
+  priority: 'P0',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Monte Carlo is a way to ask, "How often does this plan survive under many modeled futures?" It can expose fragility that a single projection hides. It does not prove what will happen in real life.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Monte Carlo proves how the plan behaves inside a chosen model, not how the real world must behave.',
+        'The result is only as good as the inputs, account modeling, tax rules, and market model behind it.',
+        'Use Monte Carlo to compare choices and identify weak spots, then decide what margin of safety feels appropriate.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'A deterministic projection is one path. Monte Carlo runs many paths. In RetireGolden, each path uses the same household, accounts, tax logic, withdrawal strategy, and expenses, but varies market returns and inflation according to the selected market model. The success rate is the share of paths where investable assets do not deplete before the plan ends.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/monte-carlo-does-not-prove.webp' },
+      caption:
+        'Monte Carlo explores many modeled futures; it does not draw a boundary around every real future.',
+      alt: 'Many modeled retirement paths fan across a planning map while a dotted outer region shows unknown real-world outcomes beyond the model.',
+    },
+    {
+      type: 'table',
+      caption: 'A useful split between proves and does not prove.',
+      columns: ['Monte Carlo can show', 'Monte Carlo cannot prove'],
+      rows: [
+        ['How often the plan works under the selected model', 'The exact probability your real life will succeed'],
+        ['Which years tend to fail in modeled bad paths', 'Which market year will happen next'],
+        ['Whether one strategy appears more resilient than another under shared assumptions', 'That the strategy is guaranteed or personally optimal'],
+        ['How sensitive the plan is to volatility, inflation, and longevity settings', 'That the assumptions are correct'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Rivera household',
+      assumptions: [
+        { label: 'Baseline', value: '92% success with lognormal markets' },
+        { label: 'Historical block model', value: '86% success with more clustered bad years' },
+        { label: 'Difference', value: '6 percentage points between two reasonable market lenses' },
+      ],
+      summary:
+        'Neither 92% nor 86% is the true future probability. The useful fact is the **6-point** drop when bad years cluster, which tells the Riveras how much cushion to keep discussing.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden lets you switch market models, re-roll the seed, run more paths, and optionally model longevity and long-term-care shocks. Those controls do not make the future knowable. They help you ask clearer questions about which risks the plan can absorb.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Treating 95% as a promise instead of a model statistic.',
+        'Comparing two plans after changing both the strategy and the assumptions.',
+        'Ignoring whether failures happen early or late.',
+        'Using Monte Carlo before the base inputs are accurate enough to trust.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Monte Carlo** to stress-test the plan after **Results** makes sense. Use **Scenarios** or **Optimize** to compare choices, then return to Monte Carlo with the same assumptions to see whether the better-looking choice is also more resilient.',
+    },
+  ],
+}

package/src/learn/content/what-retiregolden-models.ts

@@ -0,0 +1,103 @@
+/**
+ * "What RetireGolden models and what it does not" - a Start Here P0 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const whatRetireGoldenModelsArticle: LearningArticle = {
+  slug: 'what-retiregolden-models',
+  title: 'What RetireGolden models and what it does not',
+  description: 'A plain map of what the engine simulates and where it stops.',
+  category: 'start-here',
+  tags: ['model', 'scope', 'limitations', 'assumptions', 'privacy'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-19',
+  reviewCadence: 'stable',
+  sourceUrls: [],
+  relatedArticles: [
+    'about-retiregolden',
+    'how-to-read-a-retirement-projection',
+    'reading-the-results-page',
+    'todays-dollars-vs-future-dollars',
+  ],
+  relatedPlannerRoutes: ['/', '/plan/:planId/assumptions', '/plan/:planId/results', '/plan/:planId/report'],
+  currentYearSensitive: false,
+  priority: 'P0',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Every planning tool has a boundary. RetireGolden models the parts of retirement that can be represented as yearly cash flows, taxes, balances, and assumptions. It does not know your preferences, your exact tax return, or the future.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'RetireGolden is strongest when you use it to compare choices under clear assumptions.',
+        'The engine models common retirement mechanics at planning precision, not return-filing precision.',
+        'Anything outside the model should still be considered, especially personal advice, legal documents, health, family obligations, and behavior.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'A model is a simplified version of reality. The simplification is not a flaw by itself. It is what lets you see the moving parts clearly. The important thing is knowing which simplifications are in play before you trust a result too much.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/model-boundary.webp' },
+      caption:
+        'RetireGolden models the planning mechanics inside the boundary; personal judgment, exact filing details, and real-life uncertainty remain outside it.',
+      alt: 'A protected central planning model contains account, tax, healthcare, insurance, and risk tiles, separated from outside personal, legal, tax filing, and uncertainty symbols.',
+    },
+    {
+      type: 'table',
+      caption: 'The main boundary lines in RetireGolden.',
+      columns: ['Area', 'Modeled', 'Not modeled'],
+      rows: [
+        ['Household timeline', 'Ages, retirement timing, planning ages, survivor years, and filing status', 'Personal health diagnosis, family obligations, or exact date-of-death prediction'],
+        ['Cash flow', 'Income streams, spending, goals, debt service, healthcare, insurance premiums, and withdrawals', 'Every possible irregular purchase or emergency unless you add it as a goal or assumption'],
+        ['Accounts', 'Cash, taxable, equity compensation, traditional, Roth, HSA, property, debt, and insurance values', 'Every custodian-specific rule, fee, investment product, or trading detail'],
+        ['Taxes', 'Federal and state estimates at planning precision, including common retirement interactions', 'A tax return, tax advice, audit support, or every deduction and credit edge case'],
+        ['Risk', 'Monte Carlo market paths, optional longevity variation, and optional long-term-care shock', 'A prediction of actual market returns or your personal life span'],
+      ],
+    },
+    { type: 'heading', text: 'How to use the boundary well' },
+    {
+      type: 'scenario',
+      name: 'Mina and Jordan',
+      assumptions: [
+        { label: 'Question', value: 'Should they retire at 62 or 64?' },
+        { label: 'Good model use', value: 'Compare age 62 vs 64 with the same spending, return, inflation, and tax assumptions' },
+        { label: 'Outside the model', value: 'Whether they are emotionally ready to stop working' },
+      ],
+      summary:
+        'RetireGolden can show the money difference between 62 and 64, such as two more saving years and two fewer withdrawal years. It cannot decide how those two work years feel.',
+    },
+    { type: 'heading', text: 'Planning precision, not personal advice' },
+    {
+      type: 'prose',
+      md: 'Planning precision means the model is detailed enough to compare strategies and spot pressure points. It is not a substitute for professional tax, legal, investment, insurance, or healthcare advice. A result can be directionally useful and still need review before you act.',
+    },
+    {
+      type: 'callout',
+      tone: 'warn',
+      md: 'Use RetireGolden to understand trade-offs. Do not use it as the only basis for irreversible tax, investment, insurance, or estate decisions.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Treating a model limitation as a reason to ignore the model entirely.',
+        'Treating a clean chart as proof that real life will be clean too.',
+        'Changing several assumptions at once and then attributing the result to only one change.',
+        'Forgetting that private, browser-only storage also means you control your own backups.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use this article before you interpret **Results**, **Monte Carlo**, **Scenarios**, or **Optimize**. When a screen gives you a strong answer, ask which assumptions made that answer possible and which real-world issues sit outside the model.',
+    },
+  ],
+}

package/src/learn/content/what-retirement-healthcare-really-costs.ts

@@ -0,0 +1,117 @@
+import type { LearningArticle } from '../learningRegistry'
+
+export const whatRetirementHealthcareReallyCostsArticle: LearningArticle = {
+  slug: 'what-retirement-healthcare-really-costs',
+  title: 'What retirement healthcare really costs',
+  description: 'How to source the healthcare numbers you enter in Spending.',
+  category: 'healthcare',
+  tags: ['healthcare costs', 'medicare', 'aca', 'part b', 'part d', 'irmaa', 'premium tax credit'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-07-02',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.cms.gov/newsroom/fact-sheets/2026-medicare-parts-b-premiums-deductibles',
+    'https://www.medicare.gov/basics/costs/medicare-costs',
+    'https://www.medicare.gov/publications/11579-medicare-costs.pdf',
+    'https://www.kff.org/affordable-care-act/state-indicator/marketplace-average-benchmark-premiums/',
+    'https://www.cms.gov/newsroom/fact-sheets/plan-year-2026-marketplace-plans-prices-fact-sheet',
+    'https://www.healthcare.gov/retirees/',
+    'https://www.kff.org/interactive/subsidy-calculator/',
+    'https://newsroom.fidelity.com/pressreleases/fidelity-investments--releases-2025-retiree-health-care-cost-estimate--a-timely-reminder-for-all-gen/s/3c62e988-12e2-4dc8-afb4-f44b06c6d52e',
+  ],
+  relatedArticles: [
+    'healthcare-before-65',
+    'healthcare-after-65',
+    'aca-premium-tax-credits-and-magi',
+    'irmaa-two-year-lookback',
+    'assumption-healthcare-inflation',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/spending', '/plan/:planId/assumptions', '/plan/:planId/results'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Healthcare is one of the easiest retirement costs to understate because the bill is split across premiums, deductibles, copays, drug costs, and income-based surcharges. RetireGolden separates the recurring premium inputs from the costs it can model from published rules.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Before 65, start with the full marketplace or retiree-plan premium before any subsidy.',
+        'At 65 and later, RetireGolden already adds standard Medicare Part B and IRMAA; enter the extra recurring coverage you choose.',
+        'Healthcare cost guidance changes every year, so use current quotes and treat national averages as a check, not a quote.',
+      ],
+    },
+    { type: 'heading', text: 'The current numbers to anchor on' },
+    {
+      type: 'prose',
+      md: 'For 2026, CMS set the standard Medicare Part B premium at **$202.90 per month** and the annual Part B deductible at **$283**. Medicare.gov lists the same Part B premium and notes that Part D, Medicare Advantage, and Medigap costs vary by plan.\n\nFor pre-65 marketplace coverage, KFF reports a **$625 monthly national average benchmark premium for 2026** for a 40-year-old second-lowest-cost Silver plan, weighted by county selections. Older early retirees usually cost more than a 40-year-old, and premiums vary by state and county, so use a quote for your household when you can.',
+    },
+    {
+      type: 'table',
+      caption: 'How to fill the Spending healthcare fields.',
+      columns: ['Spending field', 'What to enter', 'Where the number comes from'],
+      rows: [
+        [
+          'Pre-65 premium / person / month',
+          'The full unsubsidized monthly premium for one person before any premium tax credit.',
+          'Marketplace quote, retiree-plan quote, COBRA bill, or KFF benchmark data as a rough check.',
+        ],
+        [
+          'Apply ACA premium credit',
+          'Turn on only when modeling marketplace coverage that can receive the premium tax credit.',
+          'HealthCare.gov eligibility rules and your household MAGI; the final credit is reconciled on Form 8962.',
+        ],
+        [
+          'Medicare extras / person / month',
+          'Recurring coverage beyond Part B: Part D, Medigap, Medicare Advantage, dental, vision, or similar premiums.',
+          'Medicare Plan Finder, insurer quote, employer retiree plan materials, or current plan notices.',
+        ],
+        [
+          'Baseline annual spending',
+          'Routine out-of-pocket healthcare not entered elsewhere: copays, deductibles, dental, vision, hearing, and over-the-counter costs.',
+          'Your recent spending, HSA records, insurer statements, or a conservative household estimate.',
+        ],
+      ],
+    },
+    { type: 'heading', text: 'Premium tax credits and MAGI' },
+    {
+      type: 'prose',
+      md: 'The ACA premium tax credit lowers marketplace premiums for eligible households. HealthCare.gov explains that retirees who lose job-based coverage can use the Marketplace, and that eligibility for credits depends on income and household size. KFF summarizes the current subsidy schedule as a household contribution toward the benchmark Silver plan, with the government paying the rest through the credit.\n\nThat is why Roth conversions, IRA withdrawals, capital gains, and Social Security taxation can change healthcare costs before 65. They can raise modified adjusted gross income (MAGI), which can reduce or eliminate the credit.',
+    },
+    {
+      type: 'scenario',
+      name: 'The Patel household',
+      assumptions: [
+        { label: 'Ages', value: '63 and 61, not yet on Medicare' },
+        { label: 'Marketplace quote', value: '$1,850 per month for both before credits' },
+        { label: 'Subsidized estimate', value: '$620 per month after projected premium tax credit' },
+        { label: 'Planning entry', value: '$925 per person per month, with Apply ACA premium credit turned on' },
+      ],
+      summary:
+        'They enter the full premium so RetireGolden can test the credit against MAGI. The subsidized premium is useful for budgeting, but the full premium is the right input for the field.',
+    },
+    { type: 'heading', text: 'How this fits healthcare inflation' },
+    {
+      type: 'prose',
+      md: 'RetireGolden\'s healthcare inflation assumption is an extra rate on top of general inflation. The default extra rate is **3%**, so a 2.5% general-inflation assumption means healthcare costs grow at about 5.5% nominal before any rule-specific changes.\n\nThat does not replace current-year values. Start with current quotes and published Medicare values, then let the assumption carry those costs forward in the projection.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Entering the subsidized ACA premium as the full pre-65 premium, then turning on the credit again.',
+        'Adding Part B manually in Medicare extras even though RetireGolden already adds it at 65+.',
+        'Ignoring the two-year IRMAA lookback when planning conversions around age 63 and later.',
+        'Using Fidelity or other lifetime estimates as a monthly premium quote. They are useful scale checks, not a plan-specific bill.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Spending** for pre-65 premiums, the ACA credit switch, and Medicare extras. Use **Assumptions** for healthcare inflation and recent MAGI. Use **Results** to inspect annual healthcare costs, taxes, and MAGI-sensitive premiums together.',
+    },
+  ],
+}

package/src/learn/content/why-95-percent-is-not-a-guarantee.ts

@@ -0,0 +1,98 @@
+/**
+ * "Why a 95% success rate is not a guarantee" - a Risk and Uncertainty P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const why95PercentIsNotGuaranteeArticle: LearningArticle = {
+  slug: 'why-95-percent-is-not-a-guarantee',
+  title: 'Why a 95% success rate is not a guarantee',
+  description: 'What the remaining percentage really represents.',
+  category: 'risk-uncertainty',
+  tags: ['monte carlo', 'success rate', 'risk', 'uncertainty', 'model risk'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'stable',
+  sourceUrls: ['https://www.investor.gov/introduction-investing/investing-basics/glossary/monte-carlo-simulation'],
+  relatedArticles: [
+    'understanding-monte-carlo-success-rate',
+    'what-monte-carlo-proves',
+    'sequence-of-returns-risk',
+    'historical-vs-random-return-models',
+    'sensitivity-testing-what-changes-the-answer',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/monte-carlo', '/plan/:planId/results', '/plan/:planId/scenarios'],
+  currentYearSensitive: false,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'A 95% Monte Carlo success rate is encouraging, but it is not a promise. It means the plan avoided depletion in 95% of the modeled paths using the assumptions and market model you selected.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'The percentage is about modeled paths, not all possible futures.',
+        'The missing 5% still matters because those paths may fail early or fail late for different reasons.',
+        'A high success rate should be paired with judgment about flexibility, spending cuts, insurance, and model limits.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Monte Carlo is a structured stress test. It runs the same plan through many possible market paths, then counts how often investable assets stay above zero through the planning horizon. The number is useful because it summarizes many paths. It is incomplete because real life can include rules, behavior, inflation, care needs, and market regimes that the model did not draw.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/why-95-not-guarantee.webp' },
+      caption:
+        'A high success rate means most modeled paths worked, while the failed paths still deserve inspection.',
+      alt: 'Many illustrated market paths reach the end of a retirement timeline while a small group drops below the finish line.',
+    },
+    {
+      type: 'table',
+      caption: 'What the success rate does and does not say.',
+      columns: ['It can tell you', 'It cannot tell you by itself'],
+      rows: [
+        ['How often the modeled paths avoided depletion', 'Whether the model captured every real-world risk'],
+        ['Whether one strategy is usually more resilient than another', 'Whether a tiny difference is meaningful without more paths'],
+        ['How weak paths behave under selected assumptions', 'Whether future tax law, spending behavior, or healthcare shocks will match the model'],
+        ['Whether market timing risk is material', 'Whether the plan feels acceptable to the household'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Bennett household',
+      assumptions: [
+        { label: 'Monte Carlo', value: '95% success across 1,000 paths' },
+        { label: 'Weak paths', value: 'About 50 paths still fail after a long-term-care shock and poor early markets' },
+        { label: 'Planning response', value: 'Keep the strategy, but add a spending-cut scenario and review insurance' },
+      ],
+      summary:
+        'A 95% result is strong, but it still leaves about **50** failed paths out of 1,000. The failed paths explain what backup moves the household should be ready to use.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'The **Monte Carlo** page shows the success rate, the range of outcomes, ending-balance distributions, and depletion timing. The point is not to chase 100%. The point is to understand whether the plan has enough margin for the risks you care about.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Reading 95% as a guarantee instead of a modeled frequency.',
+        'Comparing two strategies that differ by one percentage point using only 1,000 paths.',
+        'Ignoring whether failures happen early, late, or only in extreme assumptions.',
+        'Treating the model as more certain than the assumptions feeding it.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Monte Carlo** to inspect the weak paths, then use **Scenarios** to test practical responses such as retiring later, spending less, changing returns, or adding a care shock.',
+    },
+  ],
+}