@retiregolden/planner-ui 0.1.0

package/src/learn/content/assumption-recent-magi.ts

@@ -0,0 +1,83 @@
+import type { LearningArticle } from '../learningRegistry'
+
+export const assumptionRecentMagiArticle: LearningArticle = {
+  slug: 'assumption-recent-magi',
+  title: 'Recent MAGI and the IRMAA lookback',
+  description: 'Why RetireGolden asks for your recent Modified Adjusted Gross Income, and how it affects your early retirement Medicare costs.',
+  category: 'assumptions',
+  tags: ['taxes', 'magi', 'irmaa', 'medicare', 'lookback'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-06-30',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.cms.gov/newsroom/fact-sheets/2026-medicare-parts-b-premiums-deductibles',
+  ],
+  relatedArticles: [
+    'irmaa-two-year-lookback',
+    'medicare-part-b-vs-part-d-irmaa',
+    'understanding-your-plan-assumptions',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/assumptions'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: "Medicare premiums for high earners are adjusted upward based on income. These surcharges are called the **Income-Related Monthly Adjustment Amount (IRMAA)**. Because the government determines IRMAA using tax returns from **two years prior**, your plan needs a seed value to model your Medicare costs in the first few years of retirement.",
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'RetireGolden defaults **Recent annual MAGI** to **$0**, meaning no high-income surcharges are modeled for your first two years of Medicare unless you override it.',
+        'Medicare uses a **two-year lookback**: your 2026 premiums are based on the Modified Adjusted Gross Income (MAGI) reported on your 2024 tax return.',
+        'Entering your pre-retirement MAGI here ensures that the initial years of your Medicare projections are accurate, capturing any lag between high employment earnings and retirement.',
+      ],
+    },
+    { type: 'heading', text: 'Why is there a lookback?' },
+    {
+      type: 'prose',
+      md: "When you enroll in Medicare at age 65 (or continue coverage), the Social Security Administration retrieves your tax data from the IRS. Because of processing lag, the most recent finalized tax return is from two years ago. For example:",
+    },
+    {
+      type: 'list',
+      items: [
+        '**2026 Medicare premiums** look back to your **2024 tax return**.',
+        '**2027 Medicare premiums** look back to your **2025 tax return**.',
+      ],
+    },
+    {
+      type: 'table',
+      caption: 'How the seed rolls off.',
+      columns: ['Projection year', 'MAGI source RetireGolden uses', 'What it affects'],
+      rows: [
+        ['First Medicare year', 'Recent annual MAGI seed', 'Initial IRMAA tier and Medicare premium estimate'],
+        ['Second Medicare year', 'Prior-year plan MAGI or the recent seed where applicable', 'The remaining lookback transition'],
+        ['Later years', 'MAGI generated by the projection itself', 'Ongoing IRMAA and tax-driven healthcare costs'],
+      ],
+    },
+    {
+      type: 'prose',
+      md: "This two-year lag means that if you retire at 65 and transition from a high salary to a low retirement income, your Medicare premiums for the first two years will still reflect your high working years. RetireGolden uses the **Recent annual MAGI** field as the input for this two-year-prior income to model the correct premiums for those initial years.",
+    },
+    { type: 'heading', text: 'Life-changing events (Form SSA-44)' },
+    {
+      type: 'prose',
+      md: "If your income drops significantly due to a qualifying \"life-changing event\" (such as retirement, marriage, or loss of income), you can file Form SSA-44 with the Social Security Administration to request a premium reduction. RetireGolden does not automatically model this appeal, but you can simulate it by entering a lower MAGI value in this field if you plan to appeal.",
+    },
+    { type: 'heading', text: 'Watch-outs' },
+    {
+      type: 'list',
+      items: [
+        'Recent MAGI is an input seed, not an ongoing income forecast.',
+        'If you expect a successful SSA-44 appeal, model the lower recent MAGI you expect Medicare to use.',
+      ],
+    },
+    { type: 'heading', text: 'Where this shows up in the app' },
+    {
+      type: 'prose',
+      md: 'You can enter your pre-retirement income under **Recent annual MAGI** on the **Assumptions** screen. This value is used solely as a starting seed for the lookback calculation and does not affect the engine\'s ongoing income projections.',
+    },
+  ],
+}

package/src/learn/content/assumption-social-security-cola.ts

@@ -0,0 +1,89 @@
+import type { LearningArticle } from '../learningRegistry'
+
+export const assumptionSocialSecurityColaArticle: LearningArticle = {
+  slug: 'assumption-social-security-cola',
+  title: 'The Social Security COLA',
+  description: 'How RetireGolden models the Social Security Cost-of-Living Adjustment (COLA) and how it protects your benefits.',
+  category: 'assumptions',
+  tags: ['social security', 'cola', 'inflation', 'cpi-w'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-06-30',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.ssa.gov/cola/',
+    'https://www.ssa.gov/news/en/cola/factsheets/2026.html',
+    'https://www.ssa.gov/oact/TR/2025/2025_Long-Range_Economic_Assumptions.pdf',
+  ],
+  relatedArticles: [
+    'cola-and-inflation-protection',
+    'assumption-general-inflation',
+    'understanding-your-plan-assumptions',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/assumptions', '/plan/:planId/social-security'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: "Social Security is one of the few retirement income sources that is legally guaranteed to rise with inflation. This protection is delivered through the annual **Cost-of-Living Adjustment (COLA)**, which adjusts monthly benefits to keep pace with rising consumer prices.",
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'By default, RetireGolden\'s Social Security COLA is set to **match inflation** (automatically syncing with the general inflation rate, which is 2.5% by default).',
+        'Social Security COLA is statutorily tied to the annual change in the **CPI-W** (Consumer Price Index for Urban Wage Earners and Clerical Workers).',
+        'The official COLA for **2026 is 2.8%**. Over the long term, the Social Security Trustees assume an ultimate COLA of **2.4%**.',
+      ],
+    },
+    { type: 'heading', text: 'How COLA is calculated' },
+    {
+      type: 'prose',
+      md: "Every October, the Social Security Administration measures price changes using the CPI-W. It compares the average CPI-W from the third quarter (July, August, September) of the current year to the third quarter of the prior year. The percentage increase is the COLA applied to benefits starting the following January. If prices do not rise (or fall), the COLA is 0%.",
+    },
+    {
+      type: 'prose',
+      md: "Because COLA is designed to keep your real buying power flat, RetireGolden's neutral default is **Match Inflation**. This means that if you change your plan's general inflation rate, your projected Social Security benefit increases accordingly in nominal terms, keeping its real value in today's dollars constant.",
+    },
+    {
+      type: 'table',
+      caption: 'How the COLA setting changes the projection.',
+      columns: ['Setting', 'What RetireGolden does', 'When it is useful'],
+      rows: [
+        ['Match inflation', 'Benefits grow with the general inflation assumption', 'Neutral baseline; keeps real Social Security buying power flat'],
+        ['Fixed rate', 'Benefits grow at the annual rate you enter', 'Stress-testing policy changes or a gap between benefit COLA and personal inflation'],
+      ],
+    },
+    { type: 'heading', text: 'When to override the default' },
+    {
+      type: 'prose',
+      md: "RetireGolden allows you to set a **Fixed Rate** COLA override. This is useful for modeling specific policy changes or personal expectations:",
+    },
+    {
+      type: 'list',
+      items: [
+        '**Chained CPI Reform:** Some policymakers propose switching to the ' +
+          '"Chained CPI" index, which typically runs about 0.25 percentage points ' +
+          'lower than traditional CPI-W. You can model this by setting a fixed COLA rate ' +
+          'slightly below your inflation assumption (e.g., a 2.2% COLA under 2.5% inflation).',
+        '**Fixed Divergence:** If you believe inflation indexes understate your ' +
+          'personal expenses or that healthcare costs will outpace your benefit growth, ' +
+          'adjusting the COLA mode can reveal the long-term impact on your income.',
+      ],
+    },
+    { type: 'heading', text: 'Watch-outs' },
+    {
+      type: 'list',
+      items: [
+        'A fixed COLA is a scenario assumption, not a forecast of future SSA announcements.',
+        'Changing COLA can matter most for households that rely heavily on Social Security late in retirement.',
+      ],
+    },
+    { type: 'heading', text: 'Where this shows up in the app' },
+    {
+      type: 'prose',
+      md: 'You can adjust the **Social Security COLA** mode on the **Assumptions** screen. It defaults to "Match inflation," but you can toggle it to "Fixed rate" and enter a custom percentage.',
+    },
+  ],
+}

package/src/learn/content/assumption-social-security-trust-fund.ts

@@ -0,0 +1,83 @@
+import type { LearningArticle } from '../learningRegistry'
+
+export const assumptionSocialSecurityTrustFundArticle: LearningArticle = {
+  slug: 'assumption-social-security-trust-fund',
+  title: 'The Social Security trust-fund shortfall',
+  description: 'Why RetireGolden allows you to model a Social Security benefit cut, and the data behind the solvency projections.',
+  category: 'assumptions',
+  tags: ['social security', 'trust fund', 'haircut', 'solvency', 'benefit cut'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-07-08',
+  reviewCadence: 'rule-change',
+  sourceUrls: [
+    'https://www.ssa.gov/news/en/press/releases/2026-06-09.html',
+    'https://www.ssa.gov/oact/TR/2026/',
+    'https://www.everycrsreport.com/reports/IF13256.html',
+  ],
+  relatedArticles: [
+    'trust-fund-haircut-scenarios',
+    'social-security-claiming-age-basics',
+    'understanding-your-plan-assumptions',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/assumptions', '/plan/:planId/social-security'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: "One of the most common anxieties in retirement planning is the long-term solvency of Social Security. RetireGolden includes a built-in toggle that allows you to stress-test your plan against a statutory benefit cut if Congress does not act to resolve the trust fund shortfall.",
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'By default, RetireGolden\'s solvency cut toggle is **off** (modeling scheduled benefits).',
+        'When turned on, the default settings model a **17% cut starting in 2034**, directly matching the findings of the **2026 Social Security Trustees Report**.',
+        'If the retirement-only fund (OASI) is viewed in isolation, reserves deplete in **2032** with a **22% cut** required to match ongoing revenues.',
+      ],
+    },
+    { type: 'heading', text: 'Solvency data from the 2026 Trustees Report' },
+    {
+      type: 'prose',
+      md: "Social Security is funded on a pay-as-you-go basis, supplemented by reserves held in trust funds. Due to demographic shifts (a larger retiree cohort relative to workers), the system is paying out more than it collects. According to the 2026 Trustees Report:",
+    },
+    {
+      type: 'list',
+      items: [
+        '**Combined OASDI Depletion:** The Old-Age and Survivors Insurance (OASI) and Disability Insurance (DI) trust funds, if combined, will exhaust their reserves in **2034**. At that point, ongoing tax revenues will cover **83%** of scheduled benefits, requiring a **17% cut** across the board.',
+        '**Retirement-Only (OASI) Depletion:** If the DI fund is not merged with OASI, the retirement fund alone depletes in **2032** — one quarter earlier than the prior year\'s projection — with ongoing revenues covering **78%** of benefits (a **22% cut**).',
+        '**Year-over-year movement:** the combined depletion year has held at 2034 across recent reports, while the payable share moves a point or two as economic assumptions update — which is why RetireGolden re-verifies these defaults against each annual report.',
+      ],
+    },
+    { type: 'heading', text: 'How to model this in RetireGolden' },
+    {
+      type: 'prose',
+      md: "Many planners choose to model a cut to be conservative. In RetireGolden, you can toggle this on to see how a benefit cut affects your overall retirement success rate. If you turn on the haircut, the engine will pay your full scheduled benefit up to the specified year, then reduce all benefits (including spousal and survivor benefits) by the haircut percentage for the remaining years of your projection.",
+    },
+    {
+      type: 'scenario',
+      name: 'solvency haircut scenarios',
+      assumptions: [
+        { label: 'Standard Plan', value: '100% scheduled benefits' },
+        { label: 'Combined OASDI (Trustees Default)', value: '17% cut starting in 2034' },
+        { label: 'OASI Isolation (Conservative)', value: '22% cut starting in 2032' },
+        { label: 'Custom Stress Test', value: 'e.g., 25% or 30% cut' },
+      ],
+      summary: 'Modeling a 17% or 22% cut helps identify if your plan relies too heavily on Social Security and whether you need to increase savings or delay claiming.',
+    },
+    { type: 'heading', text: 'Watch-outs' },
+    {
+      type: 'list',
+      items: [
+        'The haircut toggle is a stress test, not a prediction of what Congress will do.',
+        'Scheduled benefits remain the default because current law has not changed benefits yet.',
+      ],
+    },
+    { type: 'heading', text: 'Where this shows up in the app' },
+    {
+      type: 'prose',
+      md: 'Under the **Social Security trust fund** heading on the **Assumptions** screen, check "Model a benefit cut." Once checked, you can customize the start year and the cut percentage.',
+    },
+  ],
+}

package/src/learn/content/assumption-state-tax-override.ts

@@ -0,0 +1,79 @@
+import type { LearningArticle } from '../learningRegistry'
+
+export const assumptionStateTaxOverrideArticle: LearningArticle = {
+  slug: 'assumption-state-tax-override',
+  title: 'The state tax override',
+  description: 'How RetireGolden models state income taxes in retirement and when to apply a flat-rate override.',
+  category: 'assumptions',
+  tags: ['taxes', 'state tax', 'effective tax', 'override'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-06-30',
+  reviewCadence: 'stable',
+  sourceUrls: [
+    'https://taxfoundation.org/data/all/state/state-income-tax-rates/',
+  ],
+  relatedArticles: [
+    'state-income-taxes-in-retirement',
+    'marginal-vs-effective-tax-rate',
+    'understanding-your-plan-assumptions',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/assumptions'],
+  currentYearSensitive: false,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: "State income taxes can vary widely. While some states have progressive brackets similar to the federal system, others have flat rates, and several have no income tax at all. In addition, many states exempt or partially exclude retirement income (like Social Security or pensions) from taxation.",
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'RetireGolden defaults the **state effective tax override** to **0%**, which commands the engine to use its modeled, state-specific brackets.',
+        'If you set the override to a rate greater than 0% (e.g., 4%), the engine will ignore the per-state models and apply that flat rate to all taxable income.',
+        'Use the override if you live in a state that is not yet modeled in RetireGolden, or if you want to approximate a complex local tax structure.',
+      ],
+    },
+    { type: 'heading', text: 'How RetireGolden models state taxes' },
+    {
+      type: 'prose',
+      md: "By default, the RetireGolden engine uses the state of residence entered on the **Household** screen to apply the correct progressive tax brackets, standard deductions, and retirement exclusions for that state. This data is updated annually from sources like the Tax Foundation.",
+    },
+    {
+      type: 'table',
+      caption: 'How to choose the state-tax setting.',
+      columns: ['Choice', 'What happens', 'Best use'],
+      rows: [
+        ['Leave at 0%', 'RetireGolden uses the modeled state tax rules', 'Your state is modeled and the built-in rules fit your plan'],
+        ['Enter a flat rate', 'The flat override replaces the modeled state calculation', 'Your state is unmodeled, local taxes matter, or you want a rough move scenario'],
+      ],
+    },
+    { type: 'heading', text: 'When to use the override' },
+    {
+      type: 'prose',
+      md: "A flat rate override is a useful planning shortcut in several scenarios:",
+    },
+    {
+      type: 'list',
+      items: [
+        '**Unmodeled States:** If your state has complex rules that are not yet fully represented in RetireGolden, you can estimate your average state tax burden and enter it as a flat override.',
+        '**Simplifying Moves:** If you plan to move to a different state during retirement and want to approximate the tax change without setting up multi-state movement plans, a flat rate override is a fast way to test the impact.',
+        '**Local Taxes:** The built-in state models do not include county or municipal income taxes (such as city tax in New York or local taxes in Ohio/Pennsylvania). You can add a 1% or 2% override to represent these local levies on top of your state brackets.',
+      ],
+    },
+    { type: 'heading', text: 'Watch-outs' },
+    {
+      type: 'list',
+      items: [
+        'The override is a broad effective rate, not a second state tax layered on top of modeled brackets.',
+        'A flat rate cannot capture brackets, deductions, retirement-income exclusions, or local quirks with precision.',
+      ],
+    },
+    { type: 'heading', text: 'Where this shows up in the app' },
+    {
+      type: 'prose',
+      md: 'You can enter a flat percentage under **State effective tax (override)** on the **Assumptions** screen. Leave this field at 0% to use the built-in state brackets. If you choose to override, keep in mind that the flat rate is applied to ordinary taxable income after federal deductions.',
+    },
+  ],
+}

package/src/learn/content/beneficiaries-and-account-titling.ts

@@ -0,0 +1,99 @@
+/**
+ * "Beneficiaries and account titling basics" - an Insurance and Estate P2 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const beneficiariesAccountTitlingArticle: LearningArticle = {
+  slug: 'beneficiaries-and-account-titling',
+  title: 'Beneficiaries and account titling basics',
+  description: 'Why beneficiary forms and titling can override a will.',
+  category: 'insurance-estate',
+  tags: ['beneficiaries', 'account titling', 'estate planning', 'inherited ira', 'life insurance'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'rule-change',
+  sourceUrls: ['https://www.irs.gov/publications/p559', 'https://www.irs.gov/publications/p590b'],
+  relatedArticles: [
+    'inherited-ira-10-year-rule',
+    'step-up-in-basis',
+    'permanent-life-insurance-in-a-plan',
+    'survivor-planning-for-couples',
+    'after-tax-estate',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/accounts', '/plan/:planId/insurance', '/plan/:planId/household', '/plan/:planId/report'],
+  currentYearSensitive: true,
+  priority: 'P2',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'A retirement plan can show enough money and still fail operationally if assets do not reach the intended people. Beneficiary forms and account titling are the plumbing of an estate plan: quiet when correct, painful when stale or inconsistent.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Beneficiary designations often control retirement accounts and life insurance directly.',
+        'Account titling can affect who can act, what happens at death, and whether probate is involved.',
+        'RetireGolden models ownership and some beneficiaries, but it does not model legal title, probate, trusts, or state law.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'A will is important, but many financial assets pass by contract or account form. Retirement accounts, life insurance, transfer-on-death accounts, joint accounts, and trust-owned assets may follow their own paperwork. If that paperwork is out of date, the math in the retirement plan may not match what actually happens.\n\nBeneficiary and titling reviews are especially important after marriage, divorce, death, births, moves, new accounts, and major tax-law changes.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/beneficiaries-account-titling.webp' },
+      caption:
+        'Beneficiary forms and account titles are routing instructions for where assets go when the owner dies.',
+      alt: 'Account buckets route through beneficiary forms and title gates toward spouse, heirs, estate, and trust containers, with one stale route marked for review.',
+    },
+    {
+      type: 'table',
+      caption: 'Common planning records to keep aligned.',
+      columns: ['Record', 'What it controls', 'Why it matters'],
+      rows: [
+        ['Retirement account beneficiary', 'Who receives IRA or workplace-plan assets', 'Can drive inherited-account rules and tax timing'],
+        ['Life insurance beneficiary', 'Who receives the death benefit', 'Can protect a spouse or flow to the estate in the model'],
+        ['Account owner', 'Whose age, tax, and RMD rules may apply', 'RetireGolden uses ownership for account behavior'],
+        ['Property title', 'Who owns real estate or other titled property', 'May affect control, transfer, and basis treatment'],
+        ['Estate or trust documents', 'Fallback and legal structure', 'Not modeled directly in RetireGolden'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Martin household',
+      assumptions: [
+        { label: 'Old form', value: '$240,000 retirement account still names a prior beneficiary' },
+        { label: 'Current plan', value: 'The surviving spouse needs about $35,000 a year from that account' },
+        { label: 'Risk', value: 'The projection assumes spouse support, but the form could route the asset elsewhere' },
+      ],
+      summary:
+        'RetireGolden can show the spouse needs the $240,000 account to cover a $35,000 annual gap. The beneficiary review makes sure the real-world form sends the money where the plan assumes.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden uses account ownership for RMDs, penalties, HSA limits, Roth basis ordering, and survivor modeling. It also tracks permanent-life beneficiaries as either a person in the plan or the estate. It does not replace actual beneficiary forms, account titles, trusts, wills, or attorney review.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Assuming a will updates every beneficiary form automatically.',
+        'Forgetting old employer plans, old IRAs, or old life policies.',
+        'Ignoring account ownership when modeling RMDs or survivor years.',
+        'Treating RetireGolden\'s estate numbers as proof that legal documents are aligned.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Accounts** to confirm owners, inherited-account status, and account types. Use **Insurance** to set permanent-life beneficiaries. Use **Report** as a checklist prompt, then verify the real documents outside the app.',
+    },
+  ],
+}

package/src/learn/content/break-even-useful-lens.ts

@@ -0,0 +1,94 @@
+/**
+ * "Break-even: useful lens, incomplete answer" - a Social Security P0 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const breakEvenUsefulLensArticle: LearningArticle = {
+  slug: 'break-even-useful-lens',
+  title: 'Break-even: useful lens, incomplete answer',
+  description: 'Why break-even age helps but should not decide the claim alone.',
+  category: 'social-security',
+  tags: ['social security', 'break-even', 'claiming age', 'cumulative benefits', 'longevity'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-19',
+  reviewCadence: 'stable',
+  sourceUrls: [
+    'https://www.ssa.gov/benefits/retirement/planner/agereduction.html',
+    'https://www.ssa.gov/benefits/retirement/planner/delayret.html',
+  ],
+  relatedArticles: [
+    'social-security-claiming-age-basics',
+    'spousal-and-survivor-benefits',
+    'understanding-monte-carlo-success-rate',
+    'planning-for-couples-and-survivor-years',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/social-security-analysis'],
+  currentYearSensitive: false,
+  priority: 'P0',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'A break-even age is the age when a later Social Security claim catches up to an earlier claim in cumulative dollars. It is a helpful picture, but it is not the whole claiming decision.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Break-even compares cumulative benefit dollars for different claim ages.',
+        'The answer changes when you assume cost-of-living adjustments or investment growth on checks already received.',
+        'Break-even usually ignores taxes, portfolio withdrawals, survivor benefits, and risk.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'An early claim has a head start because checks begin sooner. A later claim has a larger monthly check. The break-even question asks when the larger later checks make up for the missed early checks.\n\nThat is useful, but retirement is not only a race between two benefit lines. A household also has spending needs, taxes, market returns, survivor years, and uncertainty about lifespan.',
+    },
+    { type: 'heading', text: 'What break-even shows and misses' },
+    {
+      type: 'table',
+      caption: 'Break-even is a lens, not the whole plan.',
+      columns: ['Question', 'Break-even view', 'Whole-plan view'],
+      rows: [
+        ['How long must I live for the later claim to catch up?', 'Good at this', 'Still relevant, but not the only question'],
+        ['What happens to taxes and withdrawals before the later claim starts?', 'Usually ignored', 'Included in RetireGolden projections'],
+        ['How does a spouse or survivor benefit change the choice?', 'Usually ignored', 'Important for couples and widow(er) years'],
+        ['What if markets are good or bad while I bridge to a later claim?', 'Usually ignored', 'Can be tested in plan results and Monte Carlo'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Patel household',
+      assumptions: [
+        { label: 'Early claim', value: '$1,700 a month starting at 62' },
+        { label: 'Later claim', value: '$2,400 a month starting at 67' },
+        { label: 'Bridge cost', value: 'Waiting five years requires about $102,000 of portfolio withdrawals before checks begin' },
+      ],
+      summary:
+        'The larger $2,400 check catches up only after enough years of payments. The whole-plan question is whether spending the $102,000 bridge is worth the later income and survivor protection.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'The **Social Security analysis** page includes a break-even tab for education. It also includes an **In your plan** tab that runs claim-age combinations through the full projection and a **Benefits-only** tab that uses mortality-weighted expected value. When the views disagree, that disagreement is the lesson.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Treating break-even age as a recommendation.',
+        'Using one life expectancy date as if it were certain.',
+        'Ignoring the cash needed to delay benefits.',
+        'For couples, ignoring the larger survivor check after one spouse dies.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Open **Social Security analysis** and compare the break-even tab with the full-plan ranking. Use break-even to understand the tradeoff, then use the full-plan view to decide what the rest of the plan can support.',
+    },
+  ],
+}

package/src/learn/content/building-a-retirement-spending-budget.ts

@@ -0,0 +1,100 @@
+import type { LearningArticle } from '../learningRegistry'
+
+export const buildingRetirementSpendingBudgetArticle: LearningArticle = {
+  slug: 'building-a-retirement-spending-budget',
+  title: 'Building a retirement spending budget',
+  description: 'What belongs in baseline spending, phases, and one-time goals.',
+  category: 'using-retiregolden',
+  tags: ['spending', 'budget', 'retirement phases', 'one-time goals', 'retirement smile'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-07-02',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.bls.gov/cex/',
+    'https://www.bls.gov/cex/tables.htm',
+    'https://fred.stlouisfed.org/series/CXUTOTALEXPLB0406M',
+    'https://fred.stlouisfed.org/series/CXUTOTALEXPLB0407M',
+    'https://www.financialplanningassociation.org/sites/default/files/2020-09/MAY14%20JFP%20Blanchett_0.pdf',
+  ],
+  relatedArticles: [
+    'dynamic-spending-guardrails',
+    'three-big-questions-spending-time-risk',
+    'todays-dollars-vs-future-dollars',
+    'long-term-care-costs-and-insurance',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/spending', '/plan/:planId/results', '/plan/:planId/scenarios'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'A retirement spending budget is not one giant number. It works better when everyday living costs, planned phases, healthcare premiums, insurance premiums, debt service, and one-time goals each sit in the right place.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Baseline spending should cover recurring lifestyle costs that do not have a separate input.',
+        'Phases let you model a higher early-retirement lifestyle or a later slowdown without changing every year by hand.',
+        'One-time goals belong outside baseline spending so they do not repeat forever.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Start with normal annual living costs in today\'s dollars. Then remove anything RetireGolden already models somewhere else: mortgage payments, property tax, homeowner\'s insurance, health-insurance premiums, life or long-term-care insurance premiums, and care events.\n\nThat separation matters because each item follows a different rule. A mortgage may end. Property carrying costs may continue after the loan is gone. Medicare premiums begin at 65. Insurance premiums may be level instead of inflation-adjusted. One-time goals happen once.',
+    },
+    {
+      type: 'table',
+      caption: 'Where spending belongs in RetireGolden.',
+      columns: ['Cost', 'Where to enter it', 'Why'],
+      rows: [
+        ['Groceries, utilities, transportation, routine travel', 'Baseline annual spending', 'Repeats each year and inflates with the plan'],
+        ['Health-insurance premiums before 65', 'Healthcare', 'Can interact with the ACA premium tax credit'],
+        ['Medicare supplements, Advantage, or Part D premiums', 'Healthcare', 'Part B and IRMAA are modeled separately'],
+        ['Mortgage principal and interest', 'Debt account', 'Can end or be paid off in a specific year'],
+        ['Property tax and homeowner\'s insurance', 'Property account', 'May continue after a mortgage is gone'],
+        ['Life or LTC policy premiums', 'Insurance', 'Policy premiums feed the spending chart and policy value test'],
+        ['Large trips, car replacement, family gifts', 'One-time goals', 'Should not repeat forever unless you add more goals'],
+      ],
+    },
+    { type: 'heading', text: 'Phases and the retirement smile' },
+    {
+      type: 'prose',
+      md: 'Many retirees do not spend the same inflation-adjusted amount every year. Some spend more in the go-go years on travel and projects, less in the slow-go years, and more again if care needs rise later. Research often calls that pattern the retirement spending smile.\n\nA phase multiplier changes baseline spending from a selected age forward. It is a planning input, not a prediction. Use it to test the lifestyle you expect and the backup version you could accept.',
+    },
+    {
+      type: 'scenario',
+      name: 'The Nguyen household',
+      assumptions: [
+        { label: 'Baseline spending', value: '$90,000 per year in today\'s dollars' },
+        { label: 'Slow-go phase', value: 'At age 75, multiplier falls to 0.90' },
+        { label: 'Later phase', value: 'At age 85, multiplier falls to 0.80 before any separate care event' },
+        { label: 'One-time goal', value: '$25,000 family trip in 2029' },
+      ],
+      summary:
+        'The phase at 75 turns the recurring lifestyle line into $81,000 before inflation. The family trip stays separate, so it appears once instead of becoming part of every future year.',
+    },
+    { type: 'heading', text: 'What the data can and cannot tell you' },
+    {
+      type: 'prose',
+      md: 'The Bureau of Labor Statistics Consumer Expenditure Survey shows average spending tends to differ by age. In 2024, the 55-64 age group spent about **$84,946** on average, while the 65-and-older group spent about **$61,432**. Those are broad household averages, not a personal target.\n\nUse outside data as a reasonableness check. Your actual budget should start from your housing, location, family support, travel plans, health needs, and taxes.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Putting mortgage payments in baseline spending, then also entering the mortgage as a debt.',
+        'Forgetting property tax and homeowner\'s insurance after a mortgage payoff.',
+        'Treating every dream trip or car replacement as recurring lifestyle spending.',
+        'Using a spending-smile phase to hide a long-term-care cost that should be stress-tested separately.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Spending** for baseline spending, phases, healthcare premiums, and one-time goals. Use **Accounts** for property and debt costs. Use **Insurance** for life, long-term-care, and care-event modeling. Use **Results** to check the spending-by-category chart for double counting.',
+    },
+  ],
+}