@retiregolden/planner-ui 0.1.0

package/src/learn/content/hsas-and-qualified-medical-expenses.ts

@@ -0,0 +1,108 @@
+/**
+ * "HSAs and qualified medical expenses" - a Healthcare P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const hsasQualifiedMedicalExpensesArticle: LearningArticle = {
+  slug: 'hsas-and-qualified-medical-expenses',
+  title: 'HSAs and qualified medical expenses',
+  description: 'How to use HSA dollars tax-free for healthcare costs.',
+  category: 'healthcare',
+  tags: ['hsa', 'health savings account', 'qualified medical expenses', 'healthcare', 'tax-free'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.irs.gov/forms-pubs/about-publication-969',
+    'https://www.irs.gov/publications/p969',
+    'https://www.irs.gov/forms-pubs/about-publication-502',
+    'https://www.irs.gov/publications/p502',
+  ],
+  relatedArticles: [
+    'hsas-as-retirement-accounts',
+    'healthcare-before-65',
+    'healthcare-after-65',
+    'withdrawal-order-basics',
+    'account-types-overview',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/accounts', '/plan/:planId/spending', '/plan/:planId/results'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'A health savings account can be powerful because HSA money used for qualified medical expenses can come out tax-free. The word "qualified" is doing real work. Good HSA planning needs both a retirement model and a receipt trail.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Qualified medical expenses are defined by tax rules, not by whether a cost feels health-related.',
+        'Keeping receipts matters if you plan to reimburse yourself later from the HSA.',
+        'RetireGolden models the HSA account bucket, but it does not verify individual medical receipts.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'An HSA is not just another savings account. Contributions can be tax-advantaged, growth can be tax-deferred, and withdrawals for qualified medical expenses can be tax-free. That makes the HSA attractive for future healthcare costs.\n\nThe planning catch is documentation. If you pay a qualified medical bill from cash now and reimburse yourself from the HSA years later, you need records that connect the withdrawal to the eligible expense. RetireGolden can help model the account, but it is not a tax recordkeeping system.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/hsa-qualified-medical-expenses.webp' },
+      caption:
+        'The HSA planning path works best when eligible medical costs, receipts, and future reimbursements stay connected.',
+      alt: 'Medical cost icons create receipt tiles that connect to an HSA bucket and then to a future tax-free reimbursement path.',
+    },
+    {
+      type: 'table',
+      caption: 'Three different HSA questions.',
+      columns: ['Question', 'Planning answer', 'RetireGolden treatment'],
+      rows: [
+        ['Can I contribute?', 'Depends on HSA eligibility and annual limits', 'Contributions are capped by the parameter pack'],
+        ['Can money grow?', 'Yes, depending on the account and investments chosen', 'Balance grows using the account return assumption'],
+        ['Can I withdraw tax-free?', 'Only for qualified medical expenses with proper records', 'The app does not certify expenses or store receipts'],
+        ['What if I use it for non-medical needs?', 'Tax and penalties can apply, especially before age 65', 'Forced pre-65 non-medical HSA withdrawals can trigger a modeled penalty'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Bennett household',
+      assumptions: [
+        { label: 'Current bill', value: '$1,800 qualified dental expense paid from checking' },
+        { label: 'Documentation', value: 'Keeps the receipt and proof of payment with the tax file' },
+        { label: 'Later year', value: 'Can reimburse up to $1,800 from the HSA if rules are still met' },
+      ],
+      summary:
+        'The plan can show the HSA balance staying invested, but it cannot prove the $1,800 withdrawal is qualified. The receipt is what connects the future reimbursement to the old medical expense.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden treats HSA accounts as their own bucket. HSA contributions reduce taxable income in the projection when allowed, and the default withdrawal order keeps HSA dollars last. Healthcare spending is modeled separately from HSA receipt tracking, so do not read the projection as proof that any specific withdrawal is qualified.',
+    },
+    {
+      type: 'callout',
+      tone: 'warn',
+      md: 'Model note: RetireGolden v1 treats HSA dollars spent by the withdrawal engine as non-medical. If the HSA is forced to fund general spending before age 65, the projection can apply a 20% penalty. Use the HSA account to model the bucket, not as a qualified-expense substantiation tool.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Assuming every insurance premium or wellness purchase is qualified.',
+        'Waiting years to reimburse yourself without keeping receipts.',
+        'Counting the same medical expense twice for tax purposes.',
+        'Treating the HSA as automatically tax-free for any retirement expense.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Enter the HSA in **Accounts** and healthcare spending in **Spending**. Use **Results** to see whether the HSA is preserved, depleted, or penalized, then keep real-world HSA tax records outside the app.',
+    },
+  ],
+}

package/src/learn/content/hsas-as-retirement-accounts.ts

@@ -0,0 +1,101 @@
+/**
+ * "HSAs as retirement accounts" - an Accounts and Saving P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const hsasAsRetirementAccountsArticle: LearningArticle = {
+  slug: 'hsas-as-retirement-accounts',
+  title: 'HSAs as retirement accounts',
+  description: 'Why a health savings account can be one of the strongest retirement tools.',
+  category: 'accounts-saving',
+  tags: ['hsa', 'health savings account', 'qualified medical expenses', 'retirement healthcare', 'tax-free'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.irs.gov/forms-pubs/about-publication-969',
+    'https://www.irs.gov/publications/p969',
+  ],
+  relatedArticles: [
+    'account-types-overview',
+    'hsas-and-qualified-medical-expenses',
+    'healthcare-before-65',
+    'healthcare-after-65',
+    'withdrawal-order-basics',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/accounts', '/plan/:planId/spending', '/plan/:planId/results'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'An HSA is a health savings account tied to specific eligibility rules. When used for qualified medical expenses, it can combine tax benefits on the way in, while invested, and on the way out. That is why planners often treat a good HSA as both a healthcare tool and a retirement asset.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'HSA eligibility, contribution limits, and qualified medical expense rules matter every year.',
+        'HSA dollars used for qualified medical expenses can be unusually tax-efficient.',
+        'RetireGolden treats HSA balances as a distinct account bucket and keeps them last in the default spending order.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'A taxable brokerage account is flexible, but it can create taxable investment income and gains. A traditional retirement account can defer tax, but later withdrawals are often ordinary income. A Roth can create tax-free qualified retirement withdrawals. An HSA can be even more targeted: when the HSA rules are met and the withdrawal pays qualified medical expenses, the withdrawal can be tax-free for healthcare.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/hsa-retirement-account.webp' },
+      caption:
+        'An HSA can connect retirement saving directly to future healthcare costs when qualified medical expense rules are met.',
+      alt: 'A health savings account bucket feeds a retirement healthcare path, with medical icons and tax gates showing contribution, growth, and qualified medical spending.',
+    },
+    {
+      type: 'table',
+      caption: 'Why HSAs get special attention.',
+      columns: ['Stage', 'Planning lens', 'Caution'],
+      rows: [
+        ['Contribution', 'Can be tax-advantaged when eligibility rules are met', 'Limits and eligibility depend on coverage and current law'],
+        ['Growth', 'Can compound for future healthcare needs', 'Investment risk still matters'],
+        ['Qualified medical withdrawal', 'Can be tax-free when used under HSA rules', 'Documentation and qualified-expense rules matter'],
+        ['Non-medical withdrawal', 'May lose the special treatment and can face penalties before age 65', 'Do not model it as a generic Roth substitute'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Lee household',
+      assumptions: [
+        { label: 'Coverage', value: 'Eligible for $7,500 of HSA contributions while working' },
+        { label: 'Current medical bills', value: '$2,400 a year, affordable from cash' },
+        { label: 'Later reserve', value: 'Investing the HSA preserves $7,500 plus growth for future healthcare spending' },
+      ],
+      summary:
+        'If the Lees pay the $2,400 bill from cash, the HSA can stay invested. The trade is less cash today in exchange for a healthcare bucket that may be more valuable later.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden models HSA accounts separately from cash, taxable, traditional, and Roth accounts. Annual HSA contributions are capped by the parameter pack and reduce taxable income in the projection. The default withdrawal order spends HSA dollars last, and early non-medical HSA withdrawals can trigger a modeled pre-65 penalty.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Treating the HSA as available without checking annual eligibility.',
+        'Spending HSA dollars first when other accounts could cover non-medical needs.',
+        'Assuming all healthcare-related costs automatically qualify.',
+        'Forgetting that an HSA is still an invested account if you choose investments inside it.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Enter HSA balance and contributions in **Accounts**. Put expected healthcare costs in **Spending** and healthcare assumptions, then use **Results** to see whether the HSA is being preserved or spent.',
+    },
+  ],
+}

package/src/learn/content/inflation-risk.ts

@@ -0,0 +1,98 @@
+/**
+ * "Inflation risk" - a Risk and Uncertainty P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const inflationRiskArticle: LearningArticle = {
+  slug: 'inflation-risk',
+  title: 'Inflation risk',
+  description: 'How rising prices erode buying power over a long retirement.',
+  category: 'risk-uncertainty',
+  tags: ['inflation', 'purchasing power', 'real dollars', 'expenses', 'cola'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'stable',
+  sourceUrls: ['https://www.bls.gov/cpi/'],
+  relatedArticles: [
+    'todays-dollars-vs-future-dollars',
+    'cola-and-inflation-protection',
+    'how-assumptions-change-the-answer',
+    'sequence-of-returns-risk',
+    'healthcare-after-65',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/assumptions', '/plan/:planId/spending', '/plan/:planId/results', '/plan/:planId/monte-carlo'],
+  currentYearSensitive: false,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Inflation risk is the risk that prices rise faster than the plan can comfortably absorb. Even modest yearly inflation can make a long retirement more expensive because expenses compound year after year.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Future dollars and today\'s dollars are different ways to describe the same plan.',
+        'Inflation affects expenses, tax thresholds, healthcare costs, Social Security COLAs, and the real value of fixed income.',
+        'A plan can look comfortable in nominal dollars while still losing buying power if the inflation assumption is too low.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'A dollar amount in the future does not buy the same basket of goods that the same dollar buys today. If retirement spending rises with inflation, the nominal spending number goes up. If an income source does not rise with inflation, its real buying power falls.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/inflation-risk.webp' },
+      caption:
+        'Inflation gradually changes what a fixed dollar amount can buy, while inflation-adjusted spending keeps chasing the basket.',
+      alt: 'A fixed stack of dollars stays the same size while grocery and healthcare baskets get larger along a retirement timeline.',
+    },
+    {
+      type: 'formula',
+      expression: "today's dollars = future dollars / (1 + inflation)^years",
+      where: [
+        { symbol: 'future dollars', meaning: 'the nominal amount shown in a later year' },
+        { symbol: 'inflation', meaning: 'the assumed annual price increase expressed as a decimal' },
+        { symbol: 'years', meaning: 'the number of years between now and the future amount' },
+      ],
+      basis: 'today',
+      note: 'Real inflation varies. This simple formula uses one steady rate so the concept is easy to see.',
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Brooks household',
+      assumptions: [
+        { label: 'Base spending', value: '$80,000 in today\'s dollars' },
+        { label: 'Baseline inflation', value: '3% a year makes that lifestyle cost about $145,000 in 20 years' },
+        { label: 'Stress inflation', value: '4% a year makes it about $175,000 in 20 years' },
+      ],
+      summary:
+        'The 1-point inflation stress adds roughly **$30,000** of annual future-dollar spending by year 20. The lifestyle did not grow; the price tag did.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden stores assumptions in nominal terms, then lets Results show key figures in today\'s dollars for comparison. The projection applies general inflation to spending and other modeled items, while healthcare can also grow with an extra healthcare inflation assumption.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Comparing a future-dollar number to today\'s grocery bill without adjusting for inflation.',
+        'Assuming every income source has a full cost-of-living adjustment.',
+        'Forgetting that healthcare can grow differently from general spending.',
+        'Using one inflation assumption forever without testing a higher path.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Assumptions** to set general inflation and healthcare extra inflation. Use **Results** to toggle today\'s-dollar views, and use **Monte Carlo** or **Scenarios** to test what happens when inflation runs hotter.',
+    },
+  ],
+}

package/src/learn/content/inherited-ira-10-year-rule.ts

@@ -0,0 +1,105 @@
+/**
+ * "Inherited IRA 10-year rule" - a Withdrawals and Roth P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const inheritedIraTenYearRuleArticle: LearningArticle = {
+  slug: 'inherited-ira-10-year-rule',
+  title: 'Inherited IRA 10-year rule',
+  description: 'How most non-spouse heirs must empty an inherited IRA within ten years.',
+  category: 'withdrawals-roth',
+  tags: ['inherited ira', 'beneficiary ira', '10-year rule', 'rmd', 'secure act', 'ordinary income'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.irs.gov/retirement-plans/required-minimum-distributions-for-ira-beneficiaries',
+    'https://www.irs.gov/publications/p590b',
+  ],
+  relatedArticles: [
+    'rmds-required-minimum-distributions',
+    'beneficiaries-and-account-titling',
+    'after-tax-estate',
+    'rule-of-55-and-72t',
+    'widows-penalty-and-survivor-brackets',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/accounts', '/plan/:planId/strategy', '/plan/:planId/results'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'An inherited IRA is a retirement account received as a beneficiary. For many non-spouse beneficiaries, the inherited account must be emptied by the end of the tenth year after the original owner died. That can concentrate taxable income into a short window.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'The 10-year rule is about when the inherited account must be emptied.',
+        'If the original owner had already started RMDs, annual beneficiary RMDs may also apply in years 1 through 9.',
+        'Inherited traditional-account distributions are taxable income, but they are not subject to the 10% early-withdrawal penalty.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'A normal IRA can often be planned around the owner\'s age and required minimum distribution rules. An inherited IRA is different. The beneficiary may have to move the money out much faster, and withdrawals from an inherited traditional IRA can stack on top of wages, Roth conversions, pensions, Social Security taxation, and Medicare-related income.\n\nThe hard part is not only "empty it by year ten." It is choosing when to take taxable income inside that window.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/inherited-ira-10-year-rule.webp' },
+      caption:
+        'The inherited IRA window can force taxable distributions into a shorter timeline than the beneficiary expected.',
+      alt: 'An inherited traditional account bucket drains across a ten-year timeline, with small annual gates and a final empty-the-bucket gate at the end.',
+    },
+    {
+      type: 'table',
+      caption: 'Two inherited-IRA questions to separate.',
+      columns: ['Question', 'If yes', 'Planning effect'],
+      rows: [
+        ['Did the decedent have to take RMDs already?', 'Annual beneficiary RMDs may apply in years 1 through 9', 'The beneficiary may not be able to wait until year 10'],
+        ['Does the 10-year deadline apply?', 'The account must be empty by the end of the tenth year', 'Income may need to be spread across the window'],
+        ['Is the beneficiary young?', 'The 10% early-withdrawal penalty does not apply to inherited IRA distributions', 'Tax still applies; penalty relief is not tax relief'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Kim household',
+      assumptions: [
+        { label: 'Inherited account', value: '$300,000 traditional IRA received after a parent dies' },
+        { label: 'Spread approach', value: '$30,000 a year for 10 years before growth and required details' },
+        { label: 'Delay approach', value: 'Waiting could force a much larger taxable distribution near year 10' },
+      ],
+      summary:
+        'A rough $30,000 annual spread is easier to fit around other income than a large final-year lump. The right schedule still depends on brackets, Medicare exposure, and cash needs.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden lets a traditional account be marked as inherited. The model tracks the original owner\'s death year, whether the decedent had started RMDs, and the beneficiary owner in the plan. It forces taxable, penalty-free distributions when required and empties the account by the tenth year. Inherited accounts are not used as Roth conversion sources.',
+    },
+    {
+      type: 'callout',
+      tone: 'note',
+      md: 'Model note: RetireGolden uses a planning proxy for annual inherited-IRA divisor math. It is meant to show timing pressure, not to prepare a beneficiary RMD calculation.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Assuming the beneficiary can stretch inherited IRA withdrawals over their whole lifetime.',
+        'Waiting until year ten without testing the tax spike.',
+        'Trying to convert an inherited traditional IRA to Roth in the model.',
+        'Confusing penalty-free inherited distributions with tax-free distributions.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Accounts** to mark a traditional account as inherited and enter the original owner death year. Use **Results** to inspect inherited distributions, taxable income, taxes, and ending balances across the ten-year window.',
+    },
+  ],
+}

package/src/learn/content/insurance-in-your-retirement-plan.ts

@@ -0,0 +1,103 @@
+import type { LearningArticle } from '../learningRegistry'
+
+export const insuranceInYourRetirementPlanArticle: LearningArticle = {
+  slug: 'insurance-in-your-retirement-plan',
+  title: 'Insurance in your retirement plan',
+  description: 'How permanent life and long-term-care insurance change retirement cash flows and risks.',
+  category: 'insurance-estate',
+  tags: ['insurance', 'permanent life', 'whole life', 'long-term care', 'ltc', 'risk transfer'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-07-02',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.irs.gov/faqs/interest-dividends-other-types-of-income/life-insurance-disability-insurance-proceeds',
+    'https://www.law.cornell.edu/uscode/text/26/7702',
+    'https://content.naic.org/consumer/life-insurance.htm',
+    'https://content.naic.org/insurance-topics/life-insurance',
+    'https://www.medicare.gov/coverage/long-term-care',
+    'https://www.carescout.com/cost-of-care',
+    'https://investor.genworth.com/news-events/press-releases/detail/1054/carescout-releases-2025-cost-of-care-survey-results',
+  ],
+  relatedArticles: [
+    'permanent-life-insurance-in-a-plan',
+    'long-term-care-insurance-as-risk-transfer',
+    'long-term-care-costs-and-insurance',
+    'after-tax-estate',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/insurance', '/plan/:planId/results'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Insurance belongs in a retirement plan when it changes a risk the household cannot easily carry alone. RetireGolden focuses on two products that can change long-run outcomes: permanent life insurance and long-term-care (LTC) insurance.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Permanent life is both protection and an asset-like cash value, but the premium drag matters.',
+        'LTC insurance is risk transfer: premiums in ordinary years for help if a large care event happens.',
+        'The right question is not whether a product is good or bad; it is what job it does in this plan.',
+      ],
+    },
+    { type: 'heading', text: 'The two products RetireGolden models' },
+    {
+      type: 'table',
+      caption: 'Planning role, upside, and tradeoff.',
+      columns: ['Product', 'Planning role', 'Potential upside', 'Main tradeoff'],
+      rows: [
+        [
+          'Permanent life',
+          'Survivor protection, estate liquidity, or conservative cash-value asset.',
+          'Cash value can support net worth while living; death benefit can support heirs or a survivor.',
+          'Premiums may crowd out saving, and policy cash value is not the same as a simple investment account.',
+        ],
+        [
+          'Long-term-care insurance',
+          'Transfer part of a late-life care shock away from the household.',
+          'Can protect a survivor or estate if care costs arrive.',
+          'Premiums are paid even in no-care paths, and benefits are capped by policy terms.',
+        ],
+      ],
+    },
+    { type: 'heading', text: 'Is permanent life an investment?' },
+    {
+      type: 'prose',
+      md: 'Sometimes, but that label can confuse the decision. A cash-value policy can build value over time, and NAIC consumer guidance describes whole life and universal life as cash-value policies with savings or investment features. But the policy also has insurance costs, fees, surrender rules, loan rules, and a death benefit.\n\nRetireGolden treats permanent life as a planning asset plus an insurance payout. Cash value counts while the insured is alive. At death, the model pays the larger modeled death benefit or cash value into the plan and avoids counting both. The IRS generally excludes death-benefit proceeds paid because of the insured person\'s death from gross income, though interest and some transfer-for-value situations can be taxable.',
+    },
+    { type: 'heading', text: 'What LTC insurance transfers' },
+    {
+      type: 'prose',
+      md: 'Medicare.gov says Medicare does not pay for most non-medical long-term care or custodial care. That is why a care event can be a large household risk. CareScout\'s 2025 national median figures put assisted living at **$6,200 per month**, a semi-private nursing-home room at **$9,581 per month**, and a private nursing-home room at **$10,798 per month**.\n\nAn LTC policy does not make those costs disappear. It offsets costs after the elimination period, up to the monthly benefit, benefit period, and inflation rider. The stress test asks whether that transfer is worth the premiums in this plan.',
+    },
+    {
+      type: 'scenario',
+      name: 'The Alvarez household',
+      assumptions: [
+        { label: 'Permanent life', value: '$250,000 death benefit, $70,000 cash value, $4,800 annual premium' },
+        { label: 'LTC policy', value: '$5,500 monthly benefit, 3-year benefit period, 90-day elimination period' },
+        { label: 'Care event', value: '$110,000 per year for 3 years starting at age 86' },
+        { label: 'Planning question', value: 'Does the insured care path protect the survivor enough to justify no-care premiums?' },
+      ],
+      summary:
+        'The policy values are not judged in isolation. The plan compares the premium drag, survivor protection, care shock, and ending estate together.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Treating permanent-life cash value as if it were a free investment account with no insurance cost.',
+        'Counting both cash value and death benefit after the insured person dies.',
+        'Assuming Medicare broadly covers long-term custodial care.',
+        'Entering an LTC benefit but forgetting the elimination period, benefit period, or inflation rider.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Insurance** to enter permanent-life policies, LTC policies, and care events. Add a care event to turn on the LTC stress test. Use **Results** to see premium spending, insurance cash value, death benefits, care costs, and ending net worth.',
+    },
+  ],
+}

package/src/learn/content/irmaa-two-year-lookback.ts

@@ -0,0 +1,99 @@
+/**
+ * "Medicare, IRMAA, and the two-year lookback" - a Healthcare P0 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const irmaaTwoYearLookbackArticle: LearningArticle = {
+  slug: 'irmaa-two-year-lookback',
+  title: 'Medicare, IRMAA, and the two-year lookback',
+  description: "How income from two years ago can raise this year's Medicare premiums.",
+  category: 'healthcare',
+  tags: ['medicare', 'irmaa', 'magi', 'part b', 'part d', 'roth conversion', 'tax cliff'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-19',
+  reviewCadence: 'annual',
+  sourceUrls: ['https://www.medicare.gov/basics/costs/medicare-costs', 'https://www.ssa.gov/medicare/lower-irmaa'],
+  relatedArticles: [
+    'agi-magi-and-taxable-income',
+    'why-roth-conversions-raise-other-costs',
+    'healthcare-after-65',
+    'roth-conversion-basics',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/results', '/plan/:planId/strategy', '/plan/:planId/assumptions'],
+  currentYearSensitive: true,
+  priority: 'P0',
+  featured: true,
+  blocks: [
+    {
+      type: 'prose',
+      md: 'IRMAA stands for income-related monthly adjustment amount. It is an extra Medicare premium for higher-income households. The tricky part is timing: Medicare usually looks at income from two years earlier.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'IRMAA can raise Medicare Part B and Part D premiums.',
+        'The income test usually uses MAGI from two tax years earlier.',
+        'A Roth conversion or large gain can affect Medicare premiums later, not just tax in the conversion year.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Most Medicare planning starts with the standard Part B premium. IRMAA adds a surcharge when income is above certain brackets. Those brackets work more like steps than a smooth slope: crossing a tier can increase premiums for the year.\n\nBecause the test looks back, a high-income year at 63 can matter at 65. A high-income year at 66 can matter at 68. That delay is why IRMAA can surprise people who focus only on the tax year in front of them.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/irmaa-lookback.webp' },
+      caption:
+        'IRMAA is a delayed cost: a higher-income year can raise Medicare premiums two years later.',
+      alt: 'An income stream crosses a threshold on a timeline, and a delayed arrow points to a later Medicare premium bucket with a surcharge ribbon.',
+    },
+    { type: 'heading', text: 'How the lookback works' },
+    {
+      type: 'table',
+      caption: 'The timing is the part that most often causes surprises.',
+      columns: ['Planning question', 'What Medicare looks at', 'Why it matters'],
+      rows: [
+        ['What premium do I pay this year?', 'Usually MAGI from two tax years ago', 'Current income may not show up in premiums yet'],
+        ['What if my income recently fell?', 'A prior high-income year may still be on record', 'You may need to understand appeal rules or wait for the lookback to roll forward'],
+        ['What if I convert to Roth?', 'The conversion can raise MAGI in the conversion year', 'The premium effect may arrive later'],
+        ['What if I am under 65 now?', 'Income before Medicare can still enter the later lookback', 'A pre-Medicare conversion window is not automatically IRMAA-free'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Carter household',
+      assumptions: [
+        { label: 'Age', value: 'One spouse is 63 and planning Medicare at 65' },
+        { label: 'Strategy', value: 'Considers an $85,000 Roth conversion before Medicare starts' },
+        { label: 'Delayed cost', value: 'The conversion could add about $150 a month of Medicare premium two years later' },
+      ],
+      summary:
+        'The tax bill is only year one of the decision. If the premium increase lasts 12 months, the conversion also carries about **$1,800** of delayed Medicare cost in this simplified estimate.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden models Medicare starting at age 65. It adds the standard Part B premium, applies IRMAA from the parameter pack, and uses a two-year MAGI lookback. The **Recent annual MAGI** assumption seeds years before the projection has its own MAGI history.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Looking only at this year\'s federal tax bracket.',
+        'Forgetting that IRMAA can lag the income spike.',
+        'Treating every IRMAA tier as a reason to avoid conversions, instead of comparing lifetime after-tax results.',
+        'Assuming RetireGolden is a Medicare enrollment or appeal tool. It models planning costs, not the administrative process.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Assumptions** to set recent MAGI and healthcare inflation. Use **Strategy** or **Optimize** for conversion choices, then inspect **Results** for MAGI and healthcare-cost changes in later years.',
+    },
+  ],
+}