@retiregolden/planner-ui 0.1.0

package/src/learn/content/long-term-care-costs-and-insurance.ts

@@ -0,0 +1,103 @@
+/**
+ * "Long-term-care costs and insurance" - a Healthcare P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const longTermCareCostsInsuranceArticle: LearningArticle = {
+  slug: 'long-term-care-costs-and-insurance',
+  title: 'Long-term-care costs and insurance',
+  description: 'The size of the long-term-care risk and ways to plan for it.',
+  category: 'healthcare',
+  tags: ['long-term care', 'ltc', 'insurance', 'care event', 'healthcare spending'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'annual',
+  sourceUrls: ['https://acl.gov/ltc', 'https://acl.gov/ltc/costs-and-who-pays', 'https://www.medicare.gov/coverage/long-term-care'],
+  relatedArticles: [
+    'healthcare-after-65',
+    'longevity-risk',
+    'using-scenarios-to-compare-choices',
+    'long-term-care-insurance-as-risk-transfer',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/insurance', '/plan/:planId/spending', '/plan/:planId/scenarios', '/plan/:planId/monte-carlo'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Long-term care means help with daily living or supervision over an extended period. It can happen at home, in assisted living, or in a nursing facility. The planning problem is that the cost can be large, uneven, and concentrated late in life.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Medicare generally is not a broad long-term custodial-care plan.',
+        'A care event is a stress test: when care starts, how long it lasts, and how much it costs.',
+        'An LTC insurance policy transfers some risk, but premiums, elimination periods, caps, and benefit periods matter.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Most retirement budgets are built around recurring spending: food, housing, taxes, insurance, travel, and healthcare premiums. Long-term care is different. It may not happen, but if it does, it can add a large cost for several years.\n\nInsurance is one way to handle that tail risk. It does not make care free. It trades premiums now for a contract that may pay part of a future care cost, subject to the policy terms.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/long-term-care-costs-insurance.webp' },
+      caption:
+        'Long-term-care planning compares a late-life care-cost spike with the premiums and capped benefits of an LTC policy.',
+      alt: 'A retirement spending path has a late care-cost spike, while an LTC policy bucket pays a capped benefit after a waiting-period gate.',
+    },
+    {
+      type: 'table',
+      caption: 'LTC policy terms that shape the planning result.',
+      columns: ['Term', 'Plain meaning', 'Why it matters'],
+      rows: [
+        ['Annual premium', 'What you pay for the policy', 'Reduces cash flow even if care never happens'],
+        ['Elimination period', 'The waiting period before benefits begin', 'The first part of a care episode may be out of pocket'],
+        ['Monthly benefit', 'The maximum monthly policy benefit', 'Care costs above the cap still hit the plan'],
+        ['Benefit period', 'How long benefits can last', 'A long episode can outlast a limited policy'],
+        ['Inflation rider', 'Growth in the benefit cap', 'Can help the cap keep up with future care costs'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Garcia household',
+      assumptions: [
+        { label: 'Care event', value: '$95,000 a year of extra care costs for three late-retirement years' },
+        { label: 'Policy', value: '$5,000 monthly benefit after a waiting period, paid for up to three years' },
+        { label: 'Premium drag', value: '$3,600 a year of premiums before any care event occurs' },
+      ],
+      summary:
+        'The care event costs about **$285,000** before inflation. The policy can offset part of that shock, but the $3,600 annual premium reduces wealth in years when care never happens.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden models deterministic care events and LTC insurance policies. A care event adds today-dollar annual costs for a chosen person, start age, and duration. An LTC policy on that person can offset the event after the elimination period, up to the monthly benefit cap, inflation rider, and benefit-period limit.',
+    },
+    {
+      type: 'callout',
+      tone: 'note',
+      md: 'Monte Carlo can also sample an optional long-term-care shock. That sampled episode is added as a care event, so the same policy mechanics apply.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Assuming Medicare will cover an extended custodial-care need.',
+        'Comparing an LTC policy only by premium, without modeling benefit caps and waiting periods.',
+        'Forgetting that a couple may face care risk for either spouse.',
+        'Treating one deterministic care event as the only possible future.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Insurance** to enter LTC policies and care events. Use **Scenarios** for a deterministic long-term-care shock, and **Monte Carlo** if you want to include optional sampled LTC shocks in the risk view.',
+    },
+  ],
+}

package/src/learn/content/long-term-care-insurance-as-risk-transfer.ts

@@ -0,0 +1,98 @@
+/**
+ * "Long-term-care insurance as risk transfer" - an Insurance and Estate P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const longTermCareInsuranceRiskTransferArticle: LearningArticle = {
+  slug: 'long-term-care-insurance-as-risk-transfer',
+  title: 'Long-term-care insurance as risk transfer',
+  description: 'When paying premiums to offload tail risk can make sense.',
+  category: 'insurance-estate',
+  tags: ['long-term care', 'ltc insurance', 'risk transfer', 'premiums', 'care event'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'annual',
+  sourceUrls: ['https://acl.gov/ltc', 'https://acl.gov/ltc/costs-and-who-pays', 'https://www.medicare.gov/coverage/long-term-care'],
+  relatedArticles: [
+    'long-term-care-costs-and-insurance',
+    'longevity-risk',
+    'survivor-planning-for-couples',
+    'using-scenarios-to-compare-choices',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/insurance', '/plan/:planId/scenarios', '/plan/:planId/monte-carlo', '/plan/:planId/results'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Long-term-care insurance is not mainly a bet that you will "win" against the insurer. It is a way to transfer some late-life care risk away from the household balance sheet. The right question is often whether the premium buys enough protection against an outcome the household cannot comfortably self-fund.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Insurance can be valuable even when the expected payout is less than total premiums.',
+        'The policy terms decide how much risk is actually transferred.',
+        'RetireGolden compares care with no policy, care with a policy, and a no-care baseline so the premium tradeoff is visible.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'A household can self-insure a risk when it has enough assets to absorb the bad outcome. A household transfers risk when it pays premiums so an insurer absorbs some of that bad outcome instead.\n\nLong-term care is a natural risk-transfer topic because costs can be large, uncertain, and emotionally hard to manage. A policy can protect the estate or the surviving spouse, but only up to its benefit cap, after its waiting period, and for its benefit period.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/long-term-care-insurance-risk-transfer.webp' },
+      caption:
+        'Risk transfer trades steady premiums for a capped insurance response if a large care-cost event occurs.',
+      alt: 'A household balance sheet sends small premium streams to an insurance shield, which later absorbs part of a large care-cost wave.',
+    },
+    {
+      type: 'table',
+      caption: 'Risk transfer questions to ask before modeling a policy.',
+      columns: ['Question', 'Why it matters', 'App input or result'],
+      rows: [
+        ['Can the plan self-fund care?', 'A strong balance sheet may need less transfer', 'Compare care uninsured with no care'],
+        ['Who is protected?', 'Couples may be protecting the survivor more than the first spouse', 'Policy owner and care-event person'],
+        ['What is the cap?', 'A small monthly benefit may leave large costs uncovered', 'Monthly benefit and inflation rider'],
+        ['How long can benefits last?', 'Long episodes can outlast the policy', 'Benefit period'],
+        ['What do premiums cost in paths with no care?', 'Premiums reduce wealth even if no care event happens', 'No-care baseline versus insured case'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Howard household',
+      assumptions: [
+        { label: 'Concern', value: 'One spouse may need $90,000 a year of paid care for four years' },
+        { label: 'Policy', value: '$4,500 annual premium, then up to $6,000 monthly benefit after the waiting period' },
+        { label: 'Survivor lens', value: 'Without benefits, the care path spends down roughly $360,000 before inflation' },
+      ],
+      summary:
+        'The policy may lower the no-care estate because of premiums, but it buys protection against a care path that could consume about **$360,000** and weaken the survivor plan.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'The **Insurance** screen can show an LTC stress test once a care event exists. RetireGolden compares no care with LTC policies held out, care with policies removed, and care with the plan\'s LTC policies included. The difference makes the raw care shock and the policy value net of premiums easier to see.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Judging the policy only by whether it has a positive expected payout.',
+        'Ignoring the elimination period and benefit period.',
+        'Assuming Medicare covers long-term custodial care broadly.',
+        'Forgetting that premiums are paid in the good paths too.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Insurance** to enter LTC policies and care events. Use **Scenarios** and **Monte Carlo** to test care shocks, then inspect **Results** for estate, spending, premiums, and shortfalls.',
+    },
+  ],
+}

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

@@ -0,0 +1,99 @@
+/**
+ * "Longevity risk" - a Risk and Uncertainty P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const longevityRiskArticle: LearningArticle = {
+  slug: 'longevity-risk',
+  title: 'Longevity risk',
+  description: 'The planning challenge of not knowing how long money must last.',
+  category: 'risk-uncertainty',
+  tags: ['longevity', 'life expectancy', 'planning age', 'survivor years', 'monte carlo'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'stable',
+  sourceUrls: ['https://www.ssa.gov/oact/STATS/table4c6.html'],
+  relatedArticles: [
+    'planning-for-couples-and-survivor-years',
+    'spousal-and-survivor-benefits',
+    'widows-penalty-and-survivor-brackets',
+    'what-monte-carlo-proves',
+    'long-term-care-costs-and-insurance',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/household', '/plan/:planId/monte-carlo', '/plan/:planId/results', '/plan/:planId/scenarios'],
+  currentYearSensitive: false,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Longevity risk is the risk of living longer than the plan can support. It is a good problem to have personally, but it is a hard planning problem because nobody knows the exact number of years the portfolio must cover.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Life expectancy is an average, not an expiration date.',
+        'Couples need to plan for survivor years, not just a single shared life span.',
+        'Longer life can increase portfolio withdrawals, RMD years, healthcare exposure, and the value of inflation-protected income.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'A plan that ends at age 85 asks a different question from a plan that ends at age 95 or 100. The longer horizon gives investments more time to compound, but it also gives expenses, inflation, taxes, healthcare, and withdrawals more years to accumulate.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/longevity-risk.webp' },
+      caption:
+        'Longevity risk is an uncertain finish line, not a single known date.',
+      alt: 'A retirement path stretches toward several possible finish lines at later ages, with one household walking through survivor-year markers.',
+    },
+    {
+      type: 'table',
+      caption: 'What longer life can change.',
+      columns: ['Area', 'Why longevity matters', 'Planning response'],
+      rows: [
+        ['Spending', 'More years of expenses must be funded', 'Test later planning ages and flexible spending'],
+        ['Inflation', 'Prices have more years to compound', 'Use today\'s-dollar views and inflation stress tests'],
+        ['Social Security', 'Delayed claiming and survivor benefits can matter more over longer lives', 'Compare household-level claiming outcomes'],
+        ['Taxes', 'More RMD years and survivor filing years can change lifetime tax', 'Inspect Results by year, not only ending balance'],
+        ['Healthcare', 'Later years may include larger healthcare and care costs', 'Model healthcare and long-term-care risk explicitly'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Franklin household',
+      assumptions: [
+        { label: 'Baseline planning ages', value: 'One spouse to 90, one spouse to 94' },
+        { label: 'Stress test', value: 'Both live 5 years longer than the baseline' },
+        { label: 'Extra funding need', value: '$70,000 of annual spending must be covered for 5 more years' },
+      ],
+      summary:
+        'The stress test adds about **$350,000** of before-tax spending need before inflation. It also exposes whether survivor taxes and per-person costs tighten late in the plan.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden uses each person\'s planning age in the deterministic projection. On **Monte Carlo**, you can optionally model longevity so each path draws lifespans from mortality tables instead of assuming everyone lives exactly to the fixed planning age.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Treating life expectancy as the year the plan can safely end.',
+        'Planning only until the first spouse dies.',
+        'Ignoring the tax and benefit changes that happen in survivor years.',
+        'Using a very late planning age without also checking whether spending flexibility is realistic.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Set planning ages in **Household**, inspect year-by-year effects in **Results**, and use **Monte Carlo** with longevity modeling when you want a distribution of possible lifespans instead of one fixed horizon.',
+    },
+  ],
+}

package/src/learn/content/marginal-vs-effective-tax-rate.ts

@@ -0,0 +1,98 @@
+/**
+ * "Marginal vs effective tax rate" - a Taxes P0 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const marginalVsEffectiveTaxRateArticle: LearningArticle = {
+  slug: 'marginal-vs-effective-tax-rate',
+  title: 'Marginal vs effective tax rate',
+  description: 'The difference between your top bracket and your average tax rate.',
+  category: 'taxes',
+  tags: ['marginal tax rate', 'effective tax rate', 'tax bracket', 'income tax', 'roth conversion'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-19',
+  reviewCadence: 'stable',
+  sourceUrls: ['https://www.irs.gov/filing/federal-income-tax-rates-and-brackets'],
+  relatedArticles: [
+    'filling-a-tax-bracket-with-roth-conversions',
+    'ordinary-income-vs-capital-gains',
+    'what-retiregolden-models',
+    'why-roth-conversions-raise-other-costs',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/results', '/plan/:planId/strategy', '/plan/:planId/optimize'],
+  currentYearSensitive: false,
+  priority: 'P0',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Your marginal tax rate is the rate on the next dollar of taxable income. Your effective tax rate is your total tax divided by your total income. They answer different questions.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        '**Marginal rate** helps you judge one more dollar of income, such as one more dollar converted to Roth.',
+        '**Effective rate** helps you understand the average tax burden across the whole year.',
+        'A Roth conversion decision usually cares more about the marginal cost than the average rate.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Tax brackets are layered. Early dollars are taxed at lower rates, later dollars at higher rates. Being "in" a bracket does not mean all your income is taxed at that top rate. It means the next taxable dollar may be taxed at that rate until the next bracket begins.',
+    },
+    {
+      type: 'formula',
+      expression: 'effective tax rate = total tax / total income',
+      where: [
+        { symbol: 'total tax', meaning: 'tax paid for the year' },
+        { symbol: 'total income', meaning: 'the income measure you are using for the comparison' },
+      ],
+      note: 'Different reports may use different income measures. RetireGolden focuses on planning comparisons, not return-filing presentation.',
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Alvarez household',
+      assumptions: [
+        { label: 'Total income', value: '$100,000' },
+        { label: 'Total tax', value: '$12,000' },
+        { label: 'Next-dollar bracket', value: '22%' },
+      ],
+      summary:
+        'Their effective rate is about 12%, but an extra dollar of taxable income may cost about 22 cents before other interactions. A Roth conversion should be judged against the next-dollar cost, not the 12% average.',
+    },
+    {
+      type: 'table',
+      caption: 'Which tax rate answers which question?',
+      columns: ['Rate', 'Question it answers', 'Common use'],
+      rows: [
+        ['Marginal', 'What happens to the next dollar?', 'Sizing Roth conversions, gain harvesting, extra work income'],
+        ['Effective', 'How much tax did the whole year carry on average?', 'Understanding overall tax burden'],
+        ['Blended conversion cost', 'What did this specific conversion actually cost?', 'Comparing conversion strategies after all interactions'],
+      ],
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'The optimizer and fill-to-target strategies care about where extra income lands. A conversion may partly fill a lower bracket and partly spill into a higher one. It may also change how much Social Security is taxable or whether MAGI crosses another threshold.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Thinking every dollar is taxed at the top bracket rate.',
+        'Using effective rate to judge one more dollar of income.',
+        'Ignoring non-bracket interactions that create a higher real marginal cost.',
+        'Comparing plans by tax rate alone instead of after-tax wealth, risk, and cash flow.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Results** to inspect annual tax and MAGI. Use **Strategy** and **Optimize** when you want to test how extra conversion income changes the plan.',
+    },
+  ],
+}

package/src/learn/content/medicare-part-b-vs-part-d-irmaa.ts

@@ -0,0 +1,102 @@
+/**
+ * "Medicare Part B vs Part D IRMAA" - a Healthcare P2 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const medicarePartBVsPartDIrmaaArticle: LearningArticle = {
+  slug: 'medicare-part-b-vs-part-d-irmaa',
+  title: 'Medicare Part B vs Part D IRMAA',
+  description: 'How the income surcharge applies to both premiums.',
+  category: 'healthcare',
+  tags: ['medicare', 'irmaa', 'part b', 'part d', 'magi', 'premium surcharge'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'annual',
+  sourceUrls: ['https://www.medicare.gov/basics/costs/medicare-costs', 'https://www.ssa.gov/medicare/lower-irmaa'],
+  relatedArticles: [
+    'irmaa-two-year-lookback',
+    'healthcare-after-65',
+    'agi-magi-and-taxable-income',
+    'why-roth-conversions-raise-other-costs',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/spending', '/plan/:planId/assumptions', '/plan/:planId/results', '/plan/:planId/optimize'],
+  currentYearSensitive: true,
+  priority: 'P2',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'IRMAA can affect more than one Medicare line item. Higher modified adjusted gross income can raise Part B premiums and can also add a Part D income-related surcharge.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Part B is medical insurance; Part D is prescription drug coverage.',
+        'IRMAA is income-related and generally uses MAGI from two tax years earlier.',
+        'RetireGolden models Part B and Part D IRMAA separately from verified parameter-pack values.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Many people learn IRMAA as "the Medicare surcharge." That shorthand can hide the mechanics. The standard Part B premium can rise at higher income levels. Part D can also have an income-related surcharge, even though the drug plan premium itself depends on the plan chosen.\n\nFor planning, this matters because an income event can create multiple Medicare cost ripples two years later. A Roth conversion, capital gain, or large required distribution might raise federal tax now and Medicare premiums later.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/medicare-part-b-vs-d-irmaa.webp' },
+      caption:
+        'A higher MAGI year can feed separate Part B and Part D surcharge paths after the two-year lookback.',
+      alt: 'An income threshold gate sends two delayed ribbons into separate Medicare Part B and Part D premium buckets.',
+    },
+    {
+      type: 'table',
+      caption: 'Part B and Part D IRMAA in planning terms.',
+      columns: ['Item', 'What it is', 'Planning note'],
+      rows: [
+        ['Part B premium', 'Medical insurance premium', 'RetireGolden adds the standard premium and IRMAA tier effect automatically at 65+'],
+        ['Part D surcharge', 'Income-related surcharge tied to drug coverage', 'Modeled separately from any plan-specific drug premium extras'],
+        ['Medicare extras', 'User-entered recurring coverage costs', 'Use for Medigap, Medicare Advantage, Part D plan premiums, or other recurring coverage estimates'],
+        ['Two-year lookback', 'Prior MAGI drives later premium tiers', 'A current income decision can affect a future premium year'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Simmons household',
+      assumptions: [
+        { label: 'Income event', value: 'Large Roth conversion at age 66' },
+        { label: 'Lookback', value: 'MAGI can affect Medicare premiums two years later' },
+        { label: 'Cost paths', value: 'Estimated surcharge adds $120/month for Part B and $35/month for Part D' },
+      ],
+      summary:
+        'A combined **$155** monthly surcharge is about **$1,860** for the year. The conversion may still win, but the Medicare cost should be counted with the tax bill.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden calls the Medicare premium model for each living person age 65 or older. It uses MAGI from two years earlier, the household filing status, and the parameter pack. The model returns Part B annual premium, Part D surcharge, and the IRMAA tier. User-entered Medicare extras are added separately.',
+    },
+    {
+      type: 'callout',
+      tone: 'note',
+      md: 'Model note: RetireGolden adds published Part D IRMAA surcharges separately from any plan-specific drug premium you enter in Medicare extras.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Entering a Part B estimate in Medicare extras even though Part B is already modeled automatically.',
+        'Forgetting the Part D surcharge when testing income near an IRMAA tier.',
+        'Thinking this year\'s lower income immediately erases a prior-year lookback.',
+        'Treating every IRMAA tier as fatal instead of comparing the whole lifetime plan.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Spending** for Medicare extras, **Assumptions** for recent MAGI, and **Results** to inspect MAGI and healthcare costs. Use **Optimize** carefully around IRMAA tier edges when conversion timing is part of the plan.',
+    },
+  ],
+}

package/src/learn/content/mortality-weighted-social-security.ts

@@ -0,0 +1,113 @@
+/**
+ * "Mortality-weighted Social Security analysis" - a Social Security P2 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const mortalityWeightedSocialSecurityArticle: LearningArticle = {
+  slug: 'mortality-weighted-social-security',
+  title: 'Mortality-weighted Social Security analysis',
+  description: 'Weighing claiming choices by the odds of living to each age.',
+  category: 'social-security',
+  tags: ['social security', 'mortality', 'expected present value', 'claiming age', 'life expectancy'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.ssa.gov/oact/STATS/table4c6.html',
+    'https://www.ssa.gov/benefits/retirement/planner/agereduction.html',
+    'https://www.ssa.gov/benefits/retirement/planner/delayret.html',
+  ],
+  relatedArticles: [
+    'reading-the-social-security-analysis-page',
+    'social-security-claiming-age-basics',
+    'break-even-useful-lens',
+    'longevity-risk',
+    'planning-for-couples-and-survivor-years',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/social-security-analysis', '/plan/:planId/social-security'],
+  currentYearSensitive: true,
+  priority: 'P2',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Mortality-weighted analysis asks: if each future benefit payment is weighted by the chance of being alive to receive it, which claiming age has the strongest expected value? It is an actuarial lens, not a complete retirement-plan answer.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Expected value gives more weight to years you are more likely to reach and less weight to very late years.',
+        'A real discount rate reflects how much you value money sooner versus later.',
+        'RetireGolden shows benefits-only expected present value separately from the full in-your-plan sweep.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'A simple break-even chart treats the future as if you will definitely live to each plotted age. Mortality-weighted analysis is more careful. It says that a payment at age 72 should count more than a payment at age 98 because more people reach 72 than 98.\n\nIt also discounts future dollars. Social Security benefits are inflation-adjusted, so RetireGolden uses a real discount-rate lens for the benefits-only view. A higher real discount rate tends to favor earlier cash flow; a lower rate tends to favor delayed, larger checks.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/mortality-weighted-social-security.webp' },
+      caption:
+        'Mortality-weighted analysis combines benefit size, survival odds, and a real discount rate into one benefits-only lens.',
+      alt: 'Social Security benefit streams flow through a survival-probability curve and a discount-rate filter into an expected-value scale.',
+    },
+    {
+      type: 'formula',
+      expression: 'expected value = sum of each future benefit x survival probability x discount factor',
+      where: [
+        { symbol: 'future benefit', meaning: 'the annual Social Security payment for that future year' },
+        { symbol: 'survival probability', meaning: 'the chance the person is alive to receive that year\'s benefit' },
+        { symbol: 'discount factor', meaning: 'the real-rate adjustment for money received later' },
+      ],
+      basis: 'today',
+      note: 'RetireGolden uses annual cash flows in this lens. Monthly claim precision, taxes, and portfolio effects belong in the full plan sweep.',
+    },
+    { type: 'heading', text: 'Benefits only versus in your plan' },
+    {
+      type: 'table',
+      caption: 'The two Social Security analysis lenses answer different questions.',
+      columns: ['Lens', 'Includes', 'Leaves out'],
+      rows: [
+        ['Benefits only', 'Benefit size, survival odds, real discount rate, simplified spousal and survivor effects', 'Taxes, withdrawals, Roth conversions, IRMAA, ACA, RMDs, estate value'],
+        ['In your plan', 'The full projection and ending after-tax estate', 'It depends on the quality of all plan inputs'],
+        ['Break-even', 'Cumulative benefit timing', 'Mortality odds and most whole-plan interactions'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Rivera household',
+      assumptions: [
+        { label: 'Benefits-only result', value: 'Claiming at 70 is about $18,000 better on expected present value' },
+        { label: 'Whole-plan result', value: 'Claiming at 67 leaves ending estate within about $5,000' },
+        { label: 'Interpretation', value: 'The actuarial winner and the full-plan winner are nearly tied' },
+      ],
+      summary:
+        'The benefits-only view favors delay by about **$18,000**, but the full plan narrows the estate difference to about **$5,000**. That is close enough for household priorities to matter.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'The **Social Security analysis** page separates the benefits-only actuarial view from the full projection. For couples, the benefits-only view includes simplified spousal and survivor effects and assumes independent lifetimes. The full in-your-plan view reruns the actual plan for each claiming strategy.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Treating expected value as a guarantee for one household.',
+        'Using the benefits-only ranking to ignore taxes, IRMAA, and portfolio withdrawals.',
+        'For couples, forgetting that survivor protection can matter more than first-death totals.',
+        'Changing the real discount rate until it confirms a preferred answer.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Open **Social Security analysis** after entering benefits on **Social Security**. Use the benefits-only view for an actuarial read, then compare it with the in-your-plan ranking before changing claim ages.',
+    },
+  ],
+}