@retiregolden/planner-ui 0.1.0

package/src/learn/content/agi-magi-and-taxable-income.ts

@@ -0,0 +1,112 @@
+/**
+ * "What AGI, MAGI, and taxable income mean" - a Taxes P0 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const agiMagiAndTaxableIncomeArticle: LearningArticle = {
+  slug: 'agi-magi-and-taxable-income',
+  title: 'What AGI, MAGI, and taxable income mean',
+  description: 'Three income numbers that drive different costs in a plan.',
+  category: 'taxes',
+  tags: ['agi', 'magi', 'taxable income', 'deductions', 'irmaa', 'aca', 'tax planning'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-19',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.irs.gov/e-file-providers/definition-of-adjusted-gross-income',
+    'https://www.irs.gov/filing/federal-income-tax-rates-and-brackets',
+    'https://www.healthcare.gov/income-and-household-information/income/',
+    'https://www.medicare.gov/basics/costs/medicare-costs',
+  ],
+  relatedArticles: [
+    'marginal-vs-effective-tax-rate',
+    'why-roth-conversions-raise-other-costs',
+    'irmaa-two-year-lookback',
+    'aca-premium-tax-credits-and-magi',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/results', '/plan/:planId/strategy', '/plan/:planId/assumptions'],
+  currentYearSensitive: true,
+  priority: 'P0',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Retirement planning uses several income numbers. They sound similar, but they answer different questions. AGI, MAGI, and taxable income can move together, but they are not interchangeable.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'AGI is a tax-return building block before standard or itemized deductions.',
+        'MAGI means AGI with certain items added back, but the exact add-backs depend on the rule.',
+        'Taxable income is what federal tax brackets apply to after deductions.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Start with income. Some adjustments can reduce it to adjusted gross income, or AGI. Some programs then add certain items back to create modified adjusted gross income, or MAGI. Finally, deductions reduce income to taxable income, which is the number used for federal tax brackets.\n\nA Roth conversion can raise all three measures in different ways. A deduction can lower taxable income but may not lower MAGI for every program. That is why a plan can show a modest tax bracket while still crossing a healthcare or Medicare threshold.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/agi-magi-income-map.webp' },
+      caption:
+        'Income measures are related layers: deductions can reduce taxable income, while program-specific add-backs can still keep MAGI high.',
+      alt: 'A broad income stream enters stacked containers, deductions branch away, add-backs loop toward MAGI, and a smaller stream reaches a tax-bracket ladder.',
+    },
+    { type: 'heading', text: 'A simple map' },
+    {
+      type: 'formula',
+      expression: 'taxable income = AGI - deductions',
+      where: [
+        { symbol: 'AGI', meaning: 'adjusted gross income after certain adjustments' },
+        { symbol: 'deductions', meaning: 'standard or itemized deductions and other applicable deductions' },
+      ],
+      note: 'This is a planning simplification. Tax forms have details, ordering rules, credits, and special cases that RetireGolden does not try to reproduce line by line.',
+    },
+    {
+      type: 'table',
+      caption: 'Which income number answers which question?',
+      columns: ['Income measure', 'Plain-language meaning', 'Common planning use'],
+      rows: [
+        ['AGI', 'Income after selected adjustments', 'Starting point for many tax and benefit rules'],
+        ['MAGI', 'AGI plus rule-specific add-backs', 'ACA credits, IRMAA, and other income tests'],
+        ['Taxable income', 'Income after deductions', 'Federal ordinary-income brackets'],
+        ['Gross income', 'Broad income before adjustments', 'A rough starting point, not usually the final planning measure'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Morgan household',
+      assumptions: [
+        { label: 'Income event', value: '$20,000 Roth conversion plus $8,000 realized long-term gain' },
+        { label: 'Taxable-income effect', value: 'A $30,000 standard deduction lowers the income used for brackets' },
+        { label: 'MAGI effect', value: 'The full $28,000 income event can still count for ACA or IRMAA-style tests' },
+      ],
+      summary:
+        'The deduction can reduce the tax-bracket bill, but it does not make the income event disappear. A plan can show lower taxable income while MAGI-sensitive costs still react to the $28,000 increase.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden records MAGI in the annual ledger because it drives several planning interactions. In the current projection, MAGI is a planning approximation built from realized ordinary income, realized gains, and taxable Social Security. It is meant to capture the big levers, not replace tax-preparation software.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Using taxable income as if it were always MAGI.',
+        'Assuming a deduction prevents IRMAA or ACA effects.',
+        'Forgetting that realized capital gains can raise MAGI.',
+        'Treating one program\'s MAGI definition as universal.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Results** to inspect MAGI, tax, conversions, withdrawals, and realized gains by year. Use **Strategy** and **Optimize** when you want to test how extra income changes both tax and income-sensitive costs.',
+    },
+  ],
+}

package/src/learn/content/appealing-irmaa-ssa-44.ts

@@ -0,0 +1,95 @@
+/**
+ * "Appealing IRMAA after a life change (Form SSA-44)" - a Healthcare P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const appealingIrmaaSsa44Article: LearningArticle = {
+  slug: 'appealing-irmaa-ssa-44',
+  title: 'Appealing IRMAA after a life change (Form SSA-44)',
+  description: 'How a retirement or the death of a spouse can qualify you to have Medicare premiums re-priced on current income.',
+  category: 'healthcare',
+  tags: ['medicare', 'irmaa', 'ssa-44', 'life-changing event', 'widow penalty', 'survivor', 'retirement', 'magi'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-07-09',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.ssa.gov/medicare/lower-irmaa',
+    'https://www.ssa.gov/forms/ssa-44.pdf',
+    'https://www.medicare.gov/basics/costs/medicare-costs',
+  ],
+  relatedArticles: [
+    'irmaa-two-year-lookback',
+    'medicare-part-b-vs-part-d-irmaa',
+    'widows-penalty-and-survivor-brackets',
+    'healthcare-after-65',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/spending', '/plan/:planId/survivor', '/plan/:planId/results'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: "Medicare's income surcharge (IRMAA) is normally based on your tax return from two years earlier. When your income has just dropped because of a major life change — you stopped working, or your spouse died — that lookback can charge you a premium your current income no longer justifies. Form SSA-44 is the one-page form that asks Social Security to use this year's estimated income instead.",
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'IRMAA usually looks at MAGI from two tax years ago, so an income drop takes two years to show up in premiums.',
+        'After a qualifying life-changing event, Form SSA-44 lets you request a redetermination based on the current year\'s estimated income.',
+        'Work stoppage (retirement) and the death of a spouse are two of the eight qualifying events — and the two most common in retirement planning.',
+        'The request only helps: if your estimate is not lower, Social Security keeps the normal determination.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'The two-year lookback exists because Social Security prices premiums from the most recent tax return the IRS has on file. That works fine when income is steady, and badly when it just fell.\n\nCongress anticipated this: when one of eight **life-changing events** reduces your income, you can report the event and your current-year income estimate on Form SSA-44 (or by calling or visiting Social Security). If granted, that year\'s premium is re-priced on the estimate instead of the two-year-old return. The events include marriage, divorce or annulment, death of a spouse, work stoppage, work reduction, loss of income-producing property, loss of pension income, and an employer settlement payment.\n\nTwo of these are routine retirement-planning moments. Someone who retires at 66 with a strong final salary would otherwise pay two years of IRMAA priced on paychecks that have stopped. A surviving spouse faces the same lag on top of the single-filer thresholds — part of the "widow\'s penalty."',
+    },
+    { type: 'heading', text: 'What a redetermination is worth' },
+    {
+      type: 'table',
+      caption: 'The surcharge tiers are cliffs, so relief is worth the whole tier, not a sliver.',
+      columns: ['Situation', 'Without SSA-44', 'With a granted SSA-44'],
+      rows: [
+        ['Retired last year, final-salary MAGI on record', 'Premiums priced on working income for up to two years', 'Premiums priced on this year\'s (retirement) income'],
+        ['Widowed, joint income on record, single thresholds now', 'Lookback MAGI from joint years meets single-filer tiers', 'Premiums priced on the survivor\'s own income'],
+        ['Income did not actually fall', 'Normal determination', 'No change — the request cannot raise your premium'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Alvarez household',
+      assumptions: [
+        { label: 'Event', value: 'One spouse dies in 2030; the survivor files as single from 2031' },
+        { label: 'On record', value: 'Joint MAGI of roughly $150,000 from 2029, over the single-filer IRMAA threshold' },
+        { label: 'Current income', value: 'The survivor\'s own 2031 income is about $60,000, under every tier' },
+      ],
+      summary:
+        'Without a redetermination, the 2031 premium is priced on the couple\'s 2029 income against single-filer thresholds — a surcharge tier the survivor\'s actual income never touches. Reporting the death of spouse on Form SSA-44 with the 2031 estimate removes the surcharge for that year, and the same logic applies in 2032.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'On the **Spending** screen, the healthcare section has opt-in toggles to model SSA-44 relief in survivor years and in retirement years. When enabled, the projection prices IRMAA in the two years after the event on the *lower* of the normal lookback MAGI and the prior year\'s MAGI (the planning-grade stand-in for a current-year estimate). The Roth & Tax Optimizer sees the same treatment, so conversion advice accounts for it.\n\nThe stand-in makes the model deliberately conservative in the **first** year after the event: its estimate still references the event year itself (a death year is a full joint year), where a real filing could use the survivor\'s own current income. It also leaves the event year on the plain lookback. So the modeled relief is a floor, not a ceiling — an actual redetermination can do somewhat better.\n\nRetireGolden models the *effect* of a granted redetermination. Actually filing Form SSA-44 — with the event date and your income estimate — is your task, and Social Security decides each request.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Assuming the premium relief is automatic. Social Security does not know your income dropped until you tell them.',
+        'Waiting out the lookback instead of filing. Each affected year can be worth a full surcharge tier per person.',
+        'Forgetting the second year. The lookback can reference pre-event income for two premium years, and each can be redetermined.',
+        "Treating a Roth conversion as a qualifying event. Only the eight listed life-changing events qualify — a conversion that raised MAGI doesn't.",
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Turn the toggles on under **Spending → Healthcare**, then compare premiums by year in **Results**. For couples, the **Survivor transition** view shows the IRMAA difference with and without SSA-44 for each death timing.',
+    },
+  ],
+}

package/src/learn/content/assumption-general-inflation.ts

@@ -0,0 +1,82 @@
+import type { LearningArticle } from '../learningRegistry'
+
+export const assumptionGeneralInflationArticle: LearningArticle = {
+  slug: 'assumption-general-inflation',
+  title: 'General inflation',
+  description: 'Why RetireGolden assumes a 2.5% general inflation rate, and how it impacts your retirement buying power.',
+  category: 'assumptions',
+  tags: ['inflation', 'cpi', 'buying power', 'purchasing power'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-06-30',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.ssa.gov/oact/TR/2025/2025_Long-Range_Economic_Assumptions.pdf',
+    'https://www.cbo.gov/publication/62105',
+    'https://www.philadelphiafed.org/surveys-and-data/real-time-data-research/spf-q2-2026',
+  ],
+  relatedArticles: [
+    'todays-dollars-vs-future-dollars',
+    'understanding-your-plan-assumptions',
+    'inflation-risk',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/assumptions'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: "Inflation is the quiet force that erodes the purchasing power of your money over time. RetireGolden's projection engine runs in future nominal dollars, then the Results view can deflate those figures back into **today's dollars** so you can compare them to prices you recognize.",
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'RetireGolden defaults to a **2.5%** annual inflation rate, representing a long-term economic baseline.',
+        'This default is aligned with the Social Security Trustees long-range CPI-W estimate of 2.4% and professional forecaster surveys (~2.4%).',
+        "The engine grows future cash flows in nominal dollars, while today's-dollar displays discount those results back to true buying power.",
+      ],
+    },
+    { type: 'heading', text: 'Why 2.5%?' },
+    {
+      type: 'prose',
+      md: "No one can predict inflation over a 30-year horizon, but we can look to primary economic anchors for a sensible starting point. RetireGolden's default is built on three key benchmarks:",
+    },
+    {
+      type: 'list',
+      items: [
+        '**Social Security Trustees:** In their 2025 report, the Trustees assume an ultimate long-range annual increase in the CPI-W of **2.4%** under their intermediate cost scenario.',
+        '**Congressional Budget Office (CBO):** The CBO\'s long-term economic outlook projects PCE inflation to settle at the Federal Reserve\'s **2.0%** target, with CPI-U averaging roughly **2.2%** to **2.3%** annually.',
+        '**Survey of Professional Forecasters:** The Philadelphia Fed\'s Q2 2026 survey indicates a 10-year median CPI expectation of **2.4%**.',
+      ],
+    },
+    {
+      type: 'prose',
+      md: "RetireGolden adopts **2.5%** as a rounded, slightly conservative default. It sits just above the official long-term forecasts, providing a small safety margin.",
+    },
+    { type: 'heading', text: 'How inflation affects your plan' },
+    {
+      type: 'prose',
+      md: "If you have fixed income sources that do not adjust for inflation (like many traditional pensions or fixed annuities), a 2.5% inflation rate will cut their purchasing power in half in approximately 29 years. Conversely, cost-of-living adjustments (like Social Security COLA) help protect your buying power by rising in tandem with inflation.",
+    },
+    {
+      type: 'formula',
+      expression: 'Buying Power = Nominal Amount / (1 + Inflation Rate)^Years',
+      basis: 'today',
+      note: 'This formula calculates how much today\'s money is worth in the future under a constant inflation rate.',
+    },
+    { type: 'heading', text: 'Watch-outs' },
+    {
+      type: 'list',
+      items: [
+        "Do not compare a nominal future balance directly against today's spending.",
+        'A single long-run average can hide short inflation bursts, which is why Scenarios and Monte Carlo still matter.',
+      ],
+    },
+    { type: 'heading', text: 'Where this shows up in the app' },
+    {
+      type: 'prose',
+      md: "You can adjust the inflation rate on the **Assumptions** screen. The default of 2.5% is applied plan-wide. When you run Monte Carlo simulations, RetireGolden varies the inflation rate around this average to model inflation volatility and the way inflation interacts with market returns.",
+    },
+  ],
+}

package/src/learn/content/assumption-healthcare-inflation.ts

@@ -0,0 +1,85 @@
+import type { LearningArticle } from '../learningRegistry'
+
+export const assumptionHealthcareInflationArticle: LearningArticle = {
+  slug: 'assumption-healthcare-inflation',
+  title: 'Healthcare cost inflation',
+  description: 'Why RetireGolden assumes healthcare costs rise faster than general inflation, and how it impacts your plan.',
+  category: 'assumptions',
+  tags: ['healthcare', 'inflation', 'medicare', 'medical costs'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-06-30',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://hvsfinancial.com/wp-content/uploads/2026/02/2026-Data-Report.pdf',
+    'https://www.cms.gov/newsroom/fact-sheets/2026-medicare-parts-b-premiums-deductibles',
+  ],
+  relatedArticles: [
+    'medicare-part-b-vs-part-d-irmaa',
+    'healthcare-after-65',
+    'understanding-your-plan-assumptions',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/assumptions', '/plan/:planId/spending'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: "Healthcare is one of the largest expenses in retirement, and historically, medical costs have risen significantly faster than general consumer prices. To prevent planners from underestimating their future expenses, RetireGolden applies a separate, higher inflation rate to healthcare costs.",
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'RetireGolden defaults to a **+3.0%** healthcare extra inflation rate over the general CPI (totaling 5.5% annual growth at 2.5% inflation).',
+        'Studies indicate long-term retiree healthcare inflation will average **5.8%** per year, which is roughly twice the general inflation rate.',
+        'Medicare Part B premiums alone are projected to increase by about **7%** annually over the long term.',
+      ],
+    },
+    { type: 'heading', text: 'Sourcing the healthcare premium spread' },
+    {
+      type: 'prose',
+      md: "According to the **HealthView Services 2026 Retirement Healthcare Costs Data Report**, long-term retiree healthcare inflation is projected to average **5.8%** per year. HealthView describes this as 'approximately twice the rate of CPI.' The report highlights key drivers:",
+    },
+    {
+      type: 'list',
+      items: [
+        '**Medicare Part B and D Premiums:** Driven by healthcare utilization and clinical advancements, Part B premiums are expected to increase at a long-term rate of ~7.0% per year.',
+        '**Age-Rating Surcharges:** Private supplemental policies (Medigap) typically include age-rating adjustments that add ~3.5% per year as you age.',
+      ],
+    },
+    {
+      type: 'prose',
+      md: "RetireGolden uses a spread approach: `General Inflation + Healthcare Extra Inflation`. With a 2.5% general inflation default, adding a **+3.0%** extra inflation default yields a total healthcare growth rate of **5.5%** per year. This approximately doubles general CPI, matching the consensus long-term projections.",
+    },
+    { type: 'heading', text: 'The compounding impact' },
+    {
+      type: 'prose',
+      md: "Because healthcare inflation compounds, a premium that seems manageable at age 65 can become a substantial cash-flow demand by age 85. For instance, a $5,000 annual healthcare premium growing at 5.5% will more than double to $14,500 (in future nominal dollars) in 20 years, representing a significant real-dollar increase.",
+    },
+    {
+      type: 'scenario',
+      name: 'The healthcare spread comparison',
+      assumptions: [
+        { label: 'General Inflation', value: '2.5%' },
+        { label: 'Healthcare Premium at Age 65', value: '$6,000 / year' },
+        { label: 'Option A: Grows at CPI (+0% extra)', value: 'Age 85 Premium: $6,000 (today\'s dollars)' },
+        { label: 'Option B: Grows at CPI + 3% default', value: 'Age 85 Premium: $10,837 (today\'s dollars)' },
+      ],
+      summary: 'Under the default +3.0% extra inflation assumption, your projected age-85 premium is 80% higher in real buying power than if you assumed it only matched general inflation.',
+    },
+    { type: 'heading', text: 'Watch-outs' },
+    {
+      type: 'list',
+      items: [
+        'Healthcare extra inflation applies on top of general inflation, so 3% means 5.5% total when general inflation is 2.5%.',
+        'The default is a planning baseline, not a prediction of your own premiums, carrier, supplement, or care needs.',
+      ],
+    },
+    { type: 'heading', text: 'Where this shows up in the app' },
+    {
+      type: 'prose',
+      md: 'You can adjust the **Healthcare extra inflation** rate on the **Assumptions** screen. The default is +3.0%. This rate is automatically applied to all healthcare expenses entered under the **Spending** step, including base premiums and Medicare supplemental costs.',
+    },
+  ],
+}

package/src/learn/content/assumption-heir-tax-rate.ts

@@ -0,0 +1,79 @@
+import type { LearningArticle } from '../learningRegistry'
+
+export const assumptionHeirTaxRateArticle: LearningArticle = {
+  slug: 'assumption-heir-tax-rate',
+  title: 'The heir tax rate',
+  description: 'Why RetireGolden assumes a 25% tax rate on inherited traditional balances, and how the SECURE Act affects your estate.',
+  category: 'assumptions',
+  tags: ['estate', 'heir', 'taxes', 'traditional ira', 'secure act', '10-year rule'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-06-30',
+  reviewCadence: 'stable',
+  sourceUrls: [
+    'https://www.irs.gov/retirement-plans/retirement-plan-and-ira-required-minimum-distributions-faqs',
+  ],
+  relatedArticles: [
+    'inherited-ira-10-year-rule',
+    'after-tax-estate',
+    'understanding-your-plan-assumptions',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/assumptions'],
+  currentYearSensitive: false,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: "When planning your legacy, it is important to realize that not all accounts are inherited equally. While taxable accounts receive a step-up in basis and Roth accounts pass to heirs tax-free, traditional tax-deferred accounts (like traditional IRAs and 401ks) carry a built-in income tax liability for your beneficiaries.",
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'RetireGolden defaults the **heir tax rate** to **25%** for the after-tax estate metric.',
+        'This default reflects the typical tax bracket of adult beneficiaries who are forced to withdraw inherited tax-deferred funds under the SECURE Act.',
+        'Roth accounts and taxable accounts are modeled as passing to heirs with **0%** tax drag (taxable accounts receive a step-up in basis to eliminate capital gains).',
+      ],
+    },
+    { type: 'heading', text: 'The SECURE Act 10-year rule' },
+    {
+      type: 'prose',
+      md: "Prior to 2020, heirs could stretch withdrawals from inherited IRAs over their own lifetimes, keeping tax bills minimal. Under the **SECURE Act (and SECURE 2.0)**, most non-spouse beneficiaries (like adult children) must fully distribute and pay tax on the entire inherited traditional account within **10 years** of the owner's death.",
+    },
+    {
+      type: 'prose',
+      md: "Because these distributions are treated as ordinary income and must occur within a tight 10-year window—often during the heirs' peak earning years—the tax rate can be substantial. A flat **25%** assumption represents a typical mid-range federal tax bracket (22% or 24%) plus a modest buffer for state income taxes.",
+    },
+    {
+      type: 'formula',
+      expression: 'After-Tax Estate = Taxable + Roth + [Traditional * (1 - Heir Tax Rate)]',
+      basis: 'today',
+      note: 'RetireGolden applies the heir tax rate ONLY to traditional pre-tax balances when estimating the after-tax value of your estate.',
+    },
+    { type: 'heading', text: 'Estate planning implications' },
+    {
+      type: 'prose',
+      md: "If you have a large pre-tax balance, your heirs may face a significant \"tax bomb.\" To optimize your legacy, you might consider:",
+    },
+    {
+      type: 'list',
+      items: [
+        '**Roth Conversions:** Converting traditional balances to Roth during your lifetime, particularly if you are in a lower bracket than your heirs will be.',
+        '**Charitable Bequests:** Leaving traditional accounts to tax-exempt charities, which pay 0% tax, and leaving tax-free taxable or Roth accounts to heirs.',
+      ],
+    },
+    { type: 'heading', text: 'Watch-outs' },
+    {
+      type: 'list',
+      items: [
+        'The heir tax rate affects the after-tax estate metric; it does not change your lifetime income-tax bill.',
+        'A single flat rate is a simplification. Actual heirs may face different federal, state, and timing outcomes.',
+      ],
+    },
+    { type: 'heading', text: 'Where this shows up in the app' },
+    {
+      type: 'prose',
+      md: 'You can customize the **Heir tax rate** on the **Assumptions** screen. This percentage is used to compute the after-tax estate metric shown on the **Results** page, letting you compare the legacy impact of different withdrawal strategies.',
+    },
+  ],
+}

package/src/learn/content/assumption-investment-returns.ts

@@ -0,0 +1,90 @@
+import type { LearningArticle } from '../learningRegistry'
+
+export const assumptionInvestmentReturnsArticle: LearningArticle = {
+  slug: 'assumption-investment-returns',
+  title: 'Investment returns and volatility',
+  description: 'How RetireGolden models investment growth, historical averages, and forward-looking returns.',
+  category: 'assumptions',
+  tags: ['returns', 'investing', 'volatility', 'stocks', 'bonds', 'monte carlo'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-06-30',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://corporate.vanguard.com/content/corporatesite/us/en/corp/vemo/2026-outlook-economic-upside-stock-market-downside.html',
+    'https://am.jpmorgan.com/us/en/asset-management/adv/insights/portfolio-insights/ltcma/',
+  ],
+  relatedArticles: [
+    'sequence-of-returns-risk',
+    'historical-vs-random-return-models',
+    'inflation-risk',
+    'understanding-your-plan-assumptions',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/assumptions', '/plan/:planId/accounts'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: "Retirement assets grow through compounding investment returns, but the future rate of return is highly uncertain. To build a reliable plan, planners must balance the long-term historical records with forward-looking capital-market expectations.",
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'RetireGolden defaults to a **5.5%** blended plan-wide nominal return rate.',
+        'This represents a balanced, slightly conservative return that sits below long-run historical averages but aligns with forward-looking institutional outlooks.',
+        'For individual asset classes, RetireGolden\'s UI estimator uses illustrative nominal returns of **7% for stocks**, **4% for bonds**, and **2.5% for cash**.',
+        'Volatility (standard deviation) is modeled around **16%** for stocks and **6%** for bonds, which drives the Monte Carlo uncertainty analysis.',
+      ],
+    },
+    { type: 'heading', text: 'Historical averages vs. forward outlooks' },
+    {
+      type: 'prose',
+      md: "Over the last century (1926–present), a classic US 60/40 balanced portfolio (60% large-cap stocks, 40% intermediate bonds) has averaged nominal returns of **8% to 9%** per year. However, institutional forecasters warn that forward-looking returns over the next 10–15 years may be lower due to higher equity valuations and moderate interest rates:",
+    },
+    {
+      type: 'table',
+      caption: '2026 Capital Market Assumptions (Nominal 10-15 Yr Outlook)',
+      columns: ['Asset Class', 'Vanguard VEMO 2026', 'J.P. Morgan LTCMA 2026', 'Historical Average'],
+      rows: [
+        ['**US Large-Cap Equity**', '4.0% – 5.0%', '6.7%', '~10.0%'],
+        ['**US Aggregate Bonds**', '~4.0%', '4.6%', '~5.0%'],
+        ['**60/40 Balanced Portfolio**', '4.0% – 4.6%', '6.4%', '~8.5%'],
+      ],
+    },
+    {
+      type: 'prose',
+      md: "RetireGolden's **5.5%** blended default sits at a sensible midpoint. It accounts for potential fees, investment drags, and the possibility of lower-than-average returns over your specific retirement horizon.",
+    },
+    { type: 'heading', text: 'The role of volatility and sequence risk' },
+    {
+      type: 'prose',
+      md: "Returns never arrive in a smooth, linear fashion. Volatility is the measure of how much returns deviate from the average in any given year. In RetireGolden, the Monte Carlo engine applies standard deviations (σ) representing typical historical swings:",
+    },
+    {
+      type: 'list',
+      items: [
+        '**US Stocks:** Volatility is modeled at **σ ≈ 16%** (returns generally fall between −9% and +25% in 2 out of 3 years).',
+        '**US Bonds:** Volatility is modeled at **σ ≈ 6%** (safer, tighter range of fluctuations).',
+      ],
+    },
+    {
+      type: 'prose',
+      md: "This volatility is critical because of **sequence-of-returns risk**: suffering a market downturn early in retirement, while you are actively withdrawing money, can deplete a portfolio much faster than experiencing the same downturn later in life.",
+    },
+    { type: 'heading', text: 'Watch-outs' },
+    {
+      type: 'list',
+      items: [
+        'Do not read the 5.5% default as a forecast for your portfolio.',
+        'If account-level return assumptions differ from the plan default, those account-level values take precedence.',
+      ],
+    },
+    { type: 'heading', text: 'Where this shows up in the app' },
+    {
+      type: 'prose',
+      md: 'You can adjust the **Default return** on the **Assumptions** screen. This rate applies to any account that does not specify its own expected return. In the **Accounts** step, you can customize returns for individual accounts, or use the estimator to blend returns based on your allocation (using the Stocks/Bonds/Cash returns listed above).',
+    },
+  ],
+}

package/src/learn/content/assumption-longevity-planning-age.ts

@@ -0,0 +1,78 @@
+import type { LearningArticle } from '../learningRegistry'
+
+export const assumptionLongevityPlanningAgeArticle: LearningArticle = {
+  slug: 'assumption-longevity-planning-age',
+  title: 'How long to plan for (longevity)',
+  description: 'Why RetireGolden defaults to planning ages in the mid-to-late 90s, and the difference between life expectancy and planning horizon.',
+  category: 'assumptions',
+  tags: ['longevity', 'life expectancy', 'planning age', 'planning horizon'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-30',
+  reviewCadence: 'stable',
+  sourceUrls: [
+    'https://www.longevityillustrator.org/',
+    'https://www.ssa.gov/oact/STATS/table4c6.html',
+    'https://www.soa.org/resources/announcements/press-releases/2024/actuaries-longevity-illustrator-new-look/',
+  ],
+  relatedArticles: [
+    'longevity-risk',
+    'planning-for-couples-and-survivor-years',
+    'understanding-your-plan-assumptions',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/assumptions', '/plan/:planId/household'],
+  currentYearSensitive: false,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: "One of the most difficult questions in retirement planning is: *How long will my money need to last?* Planning to your average \"life expectancy\" is a common trap—it is merely a median, meaning you have a 50% chance of outliving your assets. A secure retirement plan requires planning for a much longer horizon.",
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'RetireGolden defaults your planning age to a floor of **95** per person.',
+        'Life expectancy is a 50/50 midpoint. Actuarial guidance is to plan for the **75th to 90th percentile** of survival to protect against outliving your savings.',
+        'For couples, joint survival (the probability that at least one partner is still alive) is significantly higher than individual survival, commonly reaching age 95 or 98.',
+      ],
+    },
+    { type: 'heading', text: 'Life expectancy vs. planning horizon' },
+    {
+      type: 'prose',
+      md: "According to the **Actuaries Longevity Illustrator** (sponsored by the American Academy of Actuaries and the Society of Actuaries), a 65-year-old non-smoking male has a median life expectancy of about age 86. However, that means half of all 65-year-old men will live *past* 86. To build a safe plan, you must look at the tail end of the survival curve:",
+    },
+    {
+      type: 'table',
+      caption: 'Survival probabilities for 65-year-olds (Non-smokers)',
+      columns: ['Percentile of Survival', '65yo Male', '65yo Female', 'Couple (At least one alive)'],
+      rows: [
+        ['**50% (Median)**', 'Age 86', 'Age 89', 'Age 92'],
+        ['**25% (75th percentile)**', 'Age 91', 'Age 93', 'Age 96'],
+        ['**10% (90th percentile)**', 'Age 95', 'Age 97', 'Age 99'],
+      ],
+    },
+    {
+      type: 'prose',
+      md: "As shown, there is a **10% chance** that a couple will have at least one partner live to **age 99**. Planning to age 90 or 95 leaves a significant risk of running out of money in your final years. That is why RetireGolden floors all planning age defaults at **95**.",
+    },
+    { type: 'heading', text: 'Modeling couples and survivor years' },
+    {
+      type: 'prose',
+      md: "When planning for a couple, the plan must account for the **survivor period**—the years after one spouse passes. This period often sees a drop in household income (losing the smaller of the two Social Security checks) while fixed expenses (like housing and utilities) remain mostly flat. Tying the planning horizon to the longer joint life expectancy ensures the surviving partner is not left underfunded.",
+    },
+    { type: 'heading', text: 'Watch-outs' },
+    {
+      type: 'list',
+      items: [
+        'Life expectancy is not the same as a planning horizon; half of similar people may live longer.',
+        'For couples, the relevant horizon is often the last survivor, not either person alone.',
+      ],
+    },
+    { type: 'heading', text: 'Where this shows up in the app' },
+    {
+      type: 'prose',
+      md: 'Your planning age is set per household member on the **Household** step (under the edit icon for each person). While the app defaults to age 95, you can override this manually if you have specific family history or health indications that suggest a different target.',
+    },
+  ],
+}