@retiregolden/planner-ui 0.1.0

package/src/learn/content/cola-and-inflation-protection.ts

@@ -0,0 +1,102 @@
+/**
+ * "COLA and inflation protection" - a Social Security P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const colaInflationProtectionArticle: LearningArticle = {
+  slug: 'cola-and-inflation-protection',
+  title: 'COLA and inflation protection',
+  description: 'How annual cost-of-living adjustments protect benefit buying power.',
+  category: 'social-security',
+  tags: ['social security', 'cola', 'inflation', 'purchasing power', 'benefits'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.ssa.gov/cola/',
+    'https://www.ssa.gov/benefits/retirement/planner/agereduction.html',
+    'https://www.ssa.gov/benefits/retirement/planner/delayret.html',
+  ],
+  relatedArticles: [
+    'social-security-claiming-age-basics',
+    'pia-aime-and-bend-points',
+    'inflation-risk',
+    'break-even-useful-lens',
+    'trust-fund-haircut-scenarios',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/social-security', '/plan/:planId/assumptions', '/plan/:planId/results'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'COLA stands for cost-of-living adjustment. It is the annual Social Security increase meant to help benefits keep up with inflation. Without that adjustment, a benefit that looks comfortable at the start of retirement could lose buying power over a long life.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'A Social Security COLA raises the benefit amount after claiming; it is not a separate account balance.',
+        'COLA protection can make a later, larger benefit especially valuable in very long lives.',
+        'RetireGolden can model Social Security COLA as matching inflation or as a fixed annual rate.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Inflation raises the cost of the same lifestyle. A grocery basket, insurance premium, or utility bill may cost more in later years than it costs today. A benefit with a cost-of-living adjustment grows over time, so the income stream has some built-in inflation protection.\n\nThat does not mean Social Security perfectly matches every retiree\'s real expenses. Your personal spending may rise faster or slower than the index used for the COLA. Healthcare can also behave differently from general inflation. But the feature still matters: a COLA-adjusted check is different from a fixed pension check that never rises.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/cola-inflation-protection.webp' },
+      caption:
+        'A COLA-adjusted benefit can rise with the price path, helping a Social Security check keep more of its buying power over time.',
+      alt: 'A benefit stream follows an upward inflation path while a fixed check falls behind, with a retirement timeline and a protected income bucket.',
+    },
+    {
+      type: 'table',
+      caption: 'Why COLA changes the claiming-age conversation.',
+      columns: ['Planning lens', 'What COLA changes', 'What it does not solve'],
+      rows: [
+        ['Monthly check', 'The starting benefit can grow after claiming', 'It does not remove the early-claim reduction'],
+        ['Long life', 'Later years receive inflation-adjusted dollars', 'It does not guarantee your full lifestyle is covered'],
+        ['Couples', 'The larger survivor check can keep growing', 'It does not replace survivor tax planning'],
+        ['Stress tests', 'You can compare fixed COLA and inflation-matched assumptions', 'It is still an assumption, not a promise about future law'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Nolan household',
+      assumptions: [
+        { label: 'Claim-now base', value: '$2,000 monthly benefit' },
+        { label: 'Delayed base', value: '$2,640 monthly benefit before future COLAs' },
+        { label: 'Illustrative COLA', value: 'At 3% for 20 years, those bases grow to about $3,600 vs $4,800 a month' },
+      ],
+      summary:
+        'Both checks receive the same percentage COLA, but the larger base compounds into about **$1,200** more monthly income 20 years later in this simplified example.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden applies Social Security COLA inside the projection. In **Assumptions**, the Social Security COLA setting can match the general inflation assumption or use a fixed annual rate. That choice affects Results, Social Security analysis, and any scenario that relies heavily on benefits in later years.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Comparing claim ages only by the first monthly check.',
+        'Treating a fixed pension and a COLA-adjusted Social Security benefit as if they carry the same inflation risk.',
+        'Assuming the official COLA will match your household\'s exact spending inflation.',
+        'For couples, ignoring that the surviving spouse may keep the larger benefit.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Social Security** to enter each person\'s benefit and claim age. Use **Assumptions** to set the Social Security COLA behavior, then check **Results** and **Social Security analysis** for the long-run effect.',
+    },
+  ],
+}

package/src/learn/content/divorced-spousal-and-survivor-records.ts

@@ -0,0 +1,104 @@
+/**
+ * "Divorced-spousal and survivor records" - a Social Security P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const divorcedSpousalSurvivorRecordsArticle: LearningArticle = {
+  slug: 'divorced-spousal-and-survivor-records',
+  title: 'Divorced-spousal and survivor records',
+  description: "When benefits can be based on an ex-spouse's record.",
+  category: 'social-security',
+  tags: ['social security', 'divorced spouse', 'survivor benefit', 'former spouse', 'claiming'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.ssa.gov/benefits/retirement/planner/applying7.html',
+    'https://www.ssa.gov/benefits/survivors/',
+  ],
+  relatedArticles: [
+    'spousal-and-survivor-benefits',
+    'social-security-claiming-age-basics',
+    'planning-for-couples-and-survivor-years',
+    'reading-the-social-security-analysis-page',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/social-security', '/plan/:planId/social-security-analysis'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'A former spouse can matter in Social Security planning even when that person is not part of your household today. In some cases, a divorced-spousal benefit or survivor benefit can be based on a former spouse\'s record.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'A long marriage to a living ex-spouse may support a divorced-spousal benefit if the claimant is currently unmarried.',
+        'A deceased former spouse may support a survivor benefit, subject to survivor and remarriage rules.',
+        'RetireGolden lets a single-person plan enter former-spouse records, then compares the eligible former-spouse benefit against the person\'s own benefit.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Social Security is based on work records, but not every benefit has to be based only on your own record. A current spouse, former spouse, or deceased spouse can sometimes create a higher benefit.\n\nThis is easiest to misunderstand after divorce or widowhood. A person may have their own retirement benefit and also a possible benefit tied to a former spouse. The planning question is usually not "Can I add both together?" It is "Which eligible benefit is larger, and when can it begin?"',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/divorced-spousal-survivor-records.webp' },
+      caption:
+        'Former-spouse records act like additional benefit paths; the modeled household uses the largest eligible path instead of stacking all paths together.',
+      alt: 'A person has three possible Social Security paths from their own record, a living former spouse record, and a deceased former spouse record, with the largest eligible path flowing into one benefit bucket.',
+    },
+    {
+      type: 'table',
+      caption: 'How RetireGolden separates former-spouse records.',
+      columns: ['Record type', 'Main eligibility idea', 'Modeled benefit idea'],
+      rows: [
+        ['Living ex-spouse', 'A marriage of at least ten years and a currently unmarried claimant', 'Up to half of the former spouse PIA, reduced for early claiming'],
+        ['Deceased former spouse', 'Survivor eligibility and remarriage rules', 'A survivor-style benefit compared with the claimant\'s own benefit'],
+        ['Current spouse', 'A current two-person household', 'Handled separately through the current-spouse top-up and survivor step-up'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Morgan plan',
+      assumptions: [
+        { label: 'Household', value: 'Single retiree with one former-spouse record' },
+        { label: 'Own benefit estimate', value: '$1,100 a month at full retirement age' },
+        { label: 'Former-spouse estimate', value: '$1,450 a month if eligibility is confirmed' },
+      ],
+      summary:
+        'The former-spouse record matters only after eligibility is confirmed. If the $1,450 estimate applies, it adds about **$350** a month compared with Morgan\'s own modeled benefit.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'On the **Social Security** screen, a Social Security income stream can include former spouses. RetireGolden asks for the relationship type, former spouse date of birth, their estimated primary insurance amount, years married, and remarriage age when relevant. The projection then uses the larger eligible benefit rather than adding all benefits together.',
+    },
+    {
+      type: 'callout',
+      tone: 'note',
+      md: 'Model note: RetireGolden uses planning-level simplifications. Divorced-spousal benefits require the claimant to be single in the modeled household. Survivor benefits on a former spouse use simplified reductions and should be checked against SSA before making a filing decision.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Assuming a divorce always erases Social Security spousal rights.',
+        'Adding your own benefit and a spousal benefit together instead of comparing the larger eligible benefit.',
+        'Forgetting remarriage rules for survivor benefits.',
+        'Entering a former spouse record in RetireGolden without verifying the real SSA eligibility facts.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Open **Social Security**, expand the person\'s Social Security entry, and add former-spouse records only when they may apply. Then use **Social Security analysis** to compare claiming ages with the former-spouse record included.',
+    },
+  ],
+}

package/src/learn/content/dynamic-spending-guardrails.ts

@@ -0,0 +1,90 @@
+import type { LearningArticle } from '../learningRegistry'
+
+export const dynamicSpendingGuardrailsArticle: LearningArticle = {
+  slug: 'dynamic-spending-guardrails',
+  title: 'Dynamic spending guardrails',
+  description: 'How flexible spending rules can reduce sequence risk without pretending risk disappears.',
+  category: 'risk-uncertainty',
+  tags: ['guardrails', 'spending', 'sequence risk', 'monte carlo', 'flexibility'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-07-06',
+  reviewCadence: 'stable',
+  sourceUrls: [
+    'https://www.onefpa.org/journal/Pages/Decision-Rules-and-Portfolio-Management-for-Retirees.aspx',
+    'https://www.onefpa.org/journal/Pages/COLA-Rules-and-Portfolio-Management-for-Retirees.aspx',
+  ],
+  relatedArticles: [
+    'risk-based-guardrails',
+    'sequence-of-returns-risk',
+    'understanding-monte-carlo-success-rate',
+    'three-big-questions-spending-time-risk',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/insights', '/plan/:planId/spending', '/plan/:planId/monte-carlo'],
+  currentYearSensitive: false,
+  priority: 'P1',
+  featured: false,
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Dynamic spending guardrails are rules for temporarily adjusting retirement spending when a portfolio is under stress or running ahead. Rather than taking the same inflation-adjusted withdrawal every year, you define ahead of time when you would trim flexible spending and when you would allow raises.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        '**Can reduce sequence risk**: Spending less during weak markets can reduce the need to sell investments after losses.',
+        '**Makes flexibility explicit**: Guardrails turn "we could cut back if needed" into a rule you can test and discuss before stress arrives.',
+        '**Does not remove risk**: A flexible plan can still fail if spending is too high, markets are unusually poor, or large care costs arrive.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'In a fixed-spending retirement plan, you choose a starting budget and increase it by inflation every year. If markets fall early in retirement, the plan may need to sell more shares from a smaller portfolio to fund that same budget.\n\nGuardrail methods set rules before that happens. A capital-preservation rule might trim spending when the current withdrawal rate climbs too far above the starting rate. A prosperity rule might allow a raise when the portfolio grows enough that the withdrawal rate falls.',
+    },
+    {
+      type: 'table',
+      columns: ['Strategy', 'During a market drop', 'Monte Carlo success rate', 'Lifetime spending'],
+      rows: [
+        ['Fixed spending', 'Withdraw the same amount from a smaller portfolio', 'Often lower', 'Steadier lifestyle, higher depletion risk'],
+        ['Dynamic guardrails', 'Temporarily trim flexible spending', 'Often higher', 'More variable, but with more built-in response'],
+      ],
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: "RetireGolden models guardrails directly inside the same annual ledger used by Results and Monte Carlo. In Spending, you can enter a required floor, target spending, optional ideal/excess annual upside, and flexible goals with earliest/latest windows, priority, and partial-funding rules. When withdrawal-rate guardrails are active, the engine cuts flexible layers before the required floor and can restore target spending or fund upside layers in strong paths.",
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Ortiz household',
+      assumptions: [
+        { label: 'Starting portfolio', value: '$1,000,000' },
+        { label: 'Baseline spending', value: '$50,000 / year' },
+        { label: 'Market drop', value: 'Portfolio drops to $750,000 in year 2' },
+        { label: 'Current withdrawal rate', value: '$50,000 / $750,000 = 6.67% (originally 5.0%)' },
+        {
+          label: 'Guardrail trigger',
+          value: 'Because 6.67% is more than 20% above the starting 5% rate, they trim spending by 10% to $45,000 until the portfolio recovers.',
+        },
+      ],
+      summary: 'The rule does not predict markets. It defines a response the household is willing to take if weak markets arrive early.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        '**Waiting too long to cut**: Cuts are most effective when made soon after the guardrail is crossed, not years later.',
+        '**Pretending all spending is flexible**: A temporary 10% cut is easier when it comes from travel, gifts, dining, or upgrades than from housing, insurance, or medical needs.',
+        '**Treating a research rule as a promise**: Guardrails can improve modeled resilience, but they still depend on market returns, taxes, inflation, health costs, and whether the household can follow the rule.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Spending** to set the required floor, upside layers, flexible goals, and guardrail policy. Use **Results** to audit annual guardrail actions and layer shortfalls. Use **Monte Carlo** to compare required-floor success, target-lifestyle success, target attainment, and flexible-goal outcomes across many market paths.',
+    },
+  ],
+}

package/src/learn/content/earnings-test-before-fra.ts

@@ -0,0 +1,100 @@
+/**
+ * "Earnings test before full retirement age" - a Social Security P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const earningsTestBeforeFraArticle: LearningArticle = {
+  slug: 'earnings-test-before-fra',
+  title: 'Earnings test before full retirement age',
+  description: 'How working while claiming early can temporarily reduce benefits.',
+  category: 'social-security',
+  tags: ['social security', 'earnings test', 'full retirement age', 'working while claiming', 'wages'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-19',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.ssa.gov/benefits/retirement/planner/whileworking.html',
+    'https://www.ssa.gov/oact/COLA/rtea.html',
+  ],
+  relatedArticles: [
+    'social-security-claiming-age-basics',
+    'pia-aime-and-bend-points',
+    'break-even-useful-lens',
+    'how-social-security-is-taxed',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/social-security', '/plan/:planId/social-security-analysis'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'If you claim Social Security before full retirement age and keep working, the retirement earnings test can temporarily withhold part of your benefit. This is about earned wages, not investment income or withdrawals.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'The earnings test applies before full retirement age when wages are above the annual exempt amount.',
+        'Different withholding rates apply before the year you reach full retirement age and during that year.',
+        'After full retirement age, the earnings test no longer withholds benefits, and withheld months can raise the later benefit calculation.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'The earnings test is easy to misread as a permanent tax. It is better to think of it as temporary withholding. If early benefits are withheld because you worked, Social Security later adjusts the benefit as if some of those early months had not been claimed.\n\nThat does not mean the timing is painless. You still have less cash in the years when benefits are withheld, and that can change portfolio withdrawals, taxes, and Roth conversion room.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/earnings-test-before-fra.webp' },
+      caption:
+        'Before full retirement age, wages can cause temporary benefit withholding; later, withheld months can be credited back.',
+      alt: 'A work-income ribbon crosses a checkpoint, part of the benefit stream is held in a reserve bucket, and a later stream continues after full retirement age.',
+    },
+    { type: 'heading', text: 'What changes when you work and claim early' },
+    {
+      type: 'table',
+      caption: 'Earnings-test treatment by timing.',
+      columns: ['Timing', 'What SSA looks at', 'What can happen'],
+      rows: [
+        ['Before the year you reach full retirement age', 'Wages above the annual exempt amount', 'Part of the benefit can be withheld'],
+        ['During the year you reach full retirement age', 'A higher exempt amount before the FRA month', 'Withholding can still happen, but under a different rule'],
+        ['After full retirement age', 'The earnings test no longer applies', 'Working does not withhold retirement benefits under this test'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Rivera household',
+      assumptions: [
+        { label: 'Claim choice', value: 'Starts a $22,000 annual benefit before full retirement age' },
+        { label: 'Work choice', value: '$35,000 of part-time wages for several years' },
+        { label: 'Cash-flow effect', value: 'Illustrative earnings-test withholding reduces the first-year benefit by about $5,000' },
+      ],
+      summary:
+        'Even if withheld months are later credited, the Rivera plan still needs about **$5,000** more from wages, cash, or the portfolio in that early year.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden runs wages before Social Security in each projection year, applies the annual earnings-test limits from the parameter pack, withholds benefits when needed, and credits whole withheld months back at full retirement age. This is an annual planning approximation, not a month-by-month SSA filing model.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Thinking the earnings test applies after full retirement age.',
+        'Applying it to investment income, IRA withdrawals, pensions, or Roth conversions instead of wages.',
+        'Ignoring the cash-flow strain in the years when benefits are withheld.',
+        'Assuming the RetireGolden annual approximation will match SSA month-by-month administration exactly.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Social Security** to set claim age and **Income** to enter wages. Then inspect **Results** and **Social Security analysis** to see whether early claiming while working helps or hurts the whole plan.',
+    },
+  ],
+}

package/src/learn/content/employer-match-and-contribution-order.ts

@@ -0,0 +1,104 @@
+/**
+ * "Employer match and contribution order" - an Accounts and Saving P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const employerMatchAndContributionOrderArticle: LearningArticle = {
+  slug: 'employer-match-and-contribution-order',
+  title: 'Employer match and contribution order',
+  description: 'A common priority order for where each saved dollar should go.',
+  category: 'accounts-saving',
+  tags: ['employer match', 'contribution order', '401k', 'hsa', 'ira', 'saving priority'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.irs.gov/retirement-plans/plan-participant-employee/retirement-topics-contributions',
+    'https://www.irs.gov/retirement-plans/401k-plans',
+    'https://www.irs.gov/forms-pubs/about-publication-969',
+  ],
+  relatedArticles: [
+    'traditional-vs-roth-contributions',
+    'hsas-as-retirement-accounts',
+    'account-types-overview',
+    'fees-expense-ratios-and-compounding-drag',
+    'taxable-brokerage-basis-and-capital-gains',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/accounts', '/plan/:planId/scenarios', '/plan/:planId/results'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Contribution order is the order in which a household directs new savings. It is not only about return. It is also about employer match, tax treatment, fees, liquidity, contribution limits, and whether the money may be needed before retirement.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'An employer match is often the first retirement-savings target because it can add money you would otherwise leave behind.',
+        'Tax-advantaged accounts have rules, limits, and access constraints, so the best order depends on the household.',
+        'After the match, compare HSA, IRA, employer plan, debt payoff, cash reserves, and taxable brokerage by purpose and flexibility.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'A common savings order starts with enough cash to avoid forced bad decisions, then captures the full employer match, then weighs high-interest debt, HSA eligibility, IRA or 401(k) contributions, and taxable brokerage. That order is a framework. A household with unstable income, large medical expenses, or unusually good employer-plan options may reasonably choose a different path.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/employer-match-contribution-order.webp' },
+      caption:
+        'A contribution order helps each saved dollar climb from urgent needs toward long-term investment buckets.',
+      alt: 'A savings dollar climbs a staircase from cash reserve to employer match, HSA, retirement accounts, and taxable brokerage, with a small employer match marker near the bottom.',
+    },
+    {
+      type: 'table',
+      caption: 'One practical order to test, not a universal rule.',
+      columns: ['Priority', 'Why it often comes early', 'Why it might move'],
+      rows: [
+        ['Cash buffer', 'Prevents emergencies from becoming expensive withdrawals or debt', 'A household with secure income may need a smaller buffer'],
+        ['Employer match', 'Can add employer dollars on top of your own contribution', 'Vesting, plan quality, and cash-flow limits still matter'],
+        ['High-interest debt', 'A guaranteed avoided cost can beat risky investment return', 'Low-rate debt may be less urgent'],
+        ['HSA if eligible', 'Can combine tax benefits with healthcare flexibility', 'Only available with qualifying coverage and rules'],
+        ['IRA or 401(k)', 'Tax-advantaged compounding and payroll simplicity', 'Fees, investment menu, tax rate, and access rules vary'],
+        ['Taxable brokerage', 'Flexible and not tied to retirement-account withdrawal rules', 'Less tax-sheltered than retirement accounts'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Wilson household',
+      assumptions: [
+        { label: 'Employer plan', value: 'Matches 100% of the first 4% of pay' },
+        { label: 'Pay', value: '$100,000 salary, so the first $4,000 contribution earns a $4,000 match' },
+        { label: 'Next dollars', value: 'After the match, compare HSA contributions and taxable bridge savings' },
+      ],
+      summary:
+        'The first $4,000 contribution effectively adds **$8,000** to retirement savings before investment returns. After that, unmatched 401(k), HSA, and taxable bridge dollars need a normal plan comparison.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden does not currently calculate an employer match from a payroll formula. Enter only the employee contribution you expect to make in the account\'s annual contribution field. Do not add future employer match there: the engine treats that field as an employee contribution subject to contribution limits and, for pre-tax accounts, as a deduction from taxable income. Include already-vested match dollars in the current balance instead.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Missing the match while contributing elsewhere first.',
+        'Maxing an account with poor investment options while ignoring an HSA or IRA that better fits the plan.',
+        'Putting every dollar into retirement accounts and leaving no flexible bridge money.',
+        'Forgetting that contribution limits apply across account groups, not always one account at a time.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Accounts** for annual contribution inputs. Create one scenario with the current savings order and another with the next dollar redirected to HSA, Roth, traditional, or taxable savings. Then compare taxes, depletion year, and Monte Carlo results.',
+    },
+  ],
+}