@retiregolden/planner-ui 0.1.0

package/src/learn/content/reading-the-social-security-analysis-page.ts

@@ -0,0 +1,106 @@
+/**
+ * "Reading the Social Security analysis page" - a Using RetireGolden P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const readingSocialSecurityAnalysisPageArticle: LearningArticle = {
+  slug: 'reading-the-social-security-analysis-page',
+  title: 'Reading the Social Security analysis page',
+  description: 'How to interpret break-even and whole-plan claiming results.',
+  category: 'using-retiregolden',
+  tags: ['retiregolden', 'social security', 'claiming age', 'break-even', 'survivor benefits'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'rule-change',
+  sourceUrls: [
+    'https://www.ssa.gov/benefits/retirement/planner/agereduction.html',
+    'https://www.ssa.gov/benefits/survivors/',
+  ],
+  relatedArticles: [
+    'social-security-claiming-age-basics',
+    'break-even-useful-lens',
+    'spousal-and-survivor-benefits',
+    'planning-for-couples-and-survivor-years',
+    'widows-penalty-and-survivor-brackets',
+  ],
+  relatedPlannerRoutes: [
+    '/plan/:planId/social-security-analysis',
+    '/plan/:planId/social-security',
+    '/plan/:planId/results',
+    '/plan/:planId/monte-carlo',
+  ],
+  currentYearSensitive: false,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'The Social Security analysis page is not one calculator. It gives you three lenses on the same claiming decision: the whole retirement plan, the benefits-only insurance value, and the simple break-even chart.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        '**In your plan** ranks claim ages by after-tax estate after rerunning the full projection.',
+        '**Benefits only** isolates Social Security value from the rest of the portfolio.',
+        '**Break-even** is educational, but it ignores taxes, portfolio withdrawals, spousal benefits, and survivor value.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Claiming age is both a cash-flow choice and an insurance choice. Claiming early can bring money sooner. Waiting can raise the monthly check and, for a couple, may raise the survivor check. The best choice depends on the rest of the plan, not only the total Social Security dollars.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/social-security-analysis-page.webp' },
+      caption:
+        'The page compares claiming choices through whole-plan, benefits-only, and break-even lenses.',
+      alt: 'Three illustrated panels compare a household plan ledger, a Social Security benefit stream, and crossing break-even lines.',
+    },
+    {
+      type: 'table',
+      caption: 'How to read the three tabs.',
+      columns: ['Tab', 'What it answers', 'Best use'],
+      rows: [
+        ['In your plan', 'Which claim-age combination leaves the strongest after-tax plan result', 'Primary decision lens for RetireGolden users'],
+        ['Benefits only', 'Which strategy has higher Social Security value before the rest of the portfolio', 'Insurance and longevity context'],
+        ['Break-even', 'When cumulative benefits from one claim age catch up to another', 'Simple teaching lens, not the full decision'],
+        ['Robustness check', 'Whether top whole-plan choices still work across sampled markets', 'Tie-breaker when top choices are close'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Chen household',
+      assumptions: [
+        { label: 'Break-even lens', value: 'Claiming at 62 improves near-term cash flow by about $20,000 a year' },
+        { label: 'Whole-plan lens', value: 'Delaying the higher benefit raises the survivor floor by about $700 a month' },
+        { label: 'Robustness check', value: 'Top strategies have similar estate values, but 82% vs 87% Monte Carlo success' },
+      ],
+      summary:
+        'The simple break-even answer favors near-term cash. The whole-plan view shows the cost of that choice: about **$700** less survivor income and a lower risk score in this example.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'The **In your plan** tab includes taxes, withdrawals, Roth conversions, IRMAA, ACA, RMDs, and ending after-tax estate. For couples, the heatmap helps show how one spouse\'s age and the other spouse\'s age interact. The page can also refine a whole-year choice to the month.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Treating break-even as the final answer.',
+        'Ignoring survivor benefit protection for the lower-income spouse.',
+        'Applying a strategy before checking whether the plan inputs are credible.',
+        'Overreacting to a tiny ranking difference when several claim ages are effectively close.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Enter benefits and claim ages on **Social Security**, then use **Social Security analysis** to sweep claim-age choices. After applying a choice, return to **Results** and **Monte Carlo** to confirm the broader plan still behaves as expected.',
+    },
+  ],
+}

package/src/learn/content/real-estate-home-equity-and-debt.ts

@@ -0,0 +1,100 @@
+/**
+ * "Real estate, home equity, and debt in a plan" - an Accounts and Saving P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const realEstateHomeEquityDebtArticle: LearningArticle = {
+  slug: 'real-estate-home-equity-and-debt',
+  title: 'Real estate, home equity, and debt in a plan',
+  description: 'How a home, rentals, and loans show up in net worth and cash flow.',
+  category: 'accounts-saving',
+  tags: ['real estate', 'home equity', 'debt', 'mortgage', 'property tax', 'net worth'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.irs.gov/forms-pubs/about-publication-523',
+    'https://www.consumerfinance.gov/consumer-tools/reverse-mortgages/',
+  ],
+  relatedArticles: [
+    'account-types-overview',
+    'taxable-brokerage-basis-and-capital-gains',
+    'after-tax-estate',
+    'state-income-taxes-in-retirement',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/accounts', '/plan/:planId/spending', '/plan/:planId/results'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'A home can be both a place to live and a large part of net worth. Debt can be both a balance-sheet liability and a cash-flow obligation. A useful retirement plan keeps those two views separate so the house does not accidentally look like spendable portfolio money.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Property value affects net worth, but it usually does not fund spending unless you sell, borrow, or downsize.',
+        'Mortgage or loan payments are cash-flow expenses until the balance is gone.',
+        'Property tax and insurance can continue after a mortgage is paid off, so they belong with the property, not only inside the loan payment.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'A paid-off home can make retirement easier because the mortgage payment is gone. It can also make planning harder because home equity is not the same as a brokerage account. To spend it, you usually need a transaction: sale, refinance, reverse mortgage, home equity line, or another arrangement with costs and risks.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/real-estate-home-equity-debt.webp' },
+      caption:
+        'Real estate adds value to net worth, while debt service and property carrying costs still flow through annual spending.',
+      alt: 'A home value block sits above a net-worth line while separate ribbons for debt payments, property tax, and insurance flow into yearly spending.',
+    },
+    {
+      type: 'table',
+      caption: 'Separate the balance sheet from the cash flow.',
+      columns: ['Item', 'Balance-sheet role', 'Cash-flow role'],
+      rows: [
+        ['Home or property value', 'Adds to net worth while owned', 'Does not fund spending unless converted to cash'],
+        ['Expected sale proceeds', 'Can become investable cash in the sale year', 'May help fund later spending after sale costs and taxes'],
+        ['Mortgage or other debt', 'Reduces net worth through the remaining balance', 'Creates scheduled debt service until paid off'],
+        ['Property tax and insurance', 'Not a loan balance', 'Recurring cost that can continue after debt payoff'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Nguyen household',
+      assumptions: [
+        { label: 'Home', value: '$420,000 home owned through the early retirement years' },
+        { label: 'Debt', value: '$1,600 monthly mortgage payment ends before age 70' },
+        { label: 'Carrying costs', value: '$7,200 a year of property tax and insurance continue afterward' },
+      ],
+      summary:
+        'When the mortgage ends, spending falls by about **$19,200** a year, not by the full housing line. The $7,200 carrying cost still needs to stay in the plan.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden has separate account types for property and debt. A property account stores value, planned sale year, expected net proceeds, property tax, and insurance. A debt account stores balance, interest rate, monthly principal-and-interest payment, and optional payoff year. In the projection, debt service is funded by the withdrawal waterfall, while property carrying costs are tracked as spending while the property is owned.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Counting home equity as if it were already liquid portfolio money.',
+        'Putting escrowed property tax and insurance inside the debt payment, which can make those costs disappear after payoff.',
+        'Forgetting sale costs, taxes, moving costs, or a replacement housing need when estimating net proceeds.',
+        'Modeling a reverse mortgage or home-equity loan as free liquidity instead of a debt or transaction with terms.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Accounts** for property and debt. Use **Spending** for lifestyle costs that are not tied to the property account. Then use **Results** to inspect net worth, debt service, property costs, and the effect of any planned sale.',
+    },
+  ],
+}

package/src/learn/content/reports-csv-exports-and-sharing.ts

@@ -0,0 +1,101 @@
+/**
+ * "Reports, CSV exports, and sharing results" - a Using RetireGolden P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const reportsCsvExportsAndSharingArticle: LearningArticle = {
+  slug: 'reports-csv-exports-and-sharing',
+  title: 'Reports, CSV exports, and sharing results',
+  description: 'How to get plan results out of the app for review or records.',
+  category: 'using-retiregolden',
+  tags: ['retiregolden', 'report', 'csv', 'backup', 'sharing'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'stable',
+  sourceUrls: [],
+  relatedArticles: [
+    'planner-overview',
+    'reading-the-results-page',
+    'privacy-what-stays-in-your-browser',
+    'using-assumptions-and-provenance',
+    'what-retiregolden-models',
+  ],
+  relatedPlannerRoutes: ['/', '/plan/:planId/results', '/plan/:planId/report'],
+  currentYearSensitive: false,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'RetireGolden has four different ways to get information out of the app: a printable/PDF report, a self-contained HTML report, a CSV ledger, and a JSON plan backup. They are for different jobs, so it helps to choose the right one.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Use the printable report when a person needs a readable plan summary or browser-saved PDF.',
+        'Use the HTML report when you want a portable audit file with assumptions, parameter provenance, warnings, and recommendation evidence.',
+        'Use the CSV when you want the annual ledger in a spreadsheet.',
+        'Use the JSON backup when you want to preserve or move the editable plan itself.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'A report is for communication. A CSV is for analysis. A backup is for restoring the app state. Sending the wrong file can create confusion: a spreadsheet reader cannot reconstruct every planner field from the CSV, and a JSON backup may expose more personal data than a report reviewer needs.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/reports-csv-exports-sharing.webp' },
+      caption:
+        'Reports, CSV ledgers, and backups serve different sharing and recordkeeping needs.',
+      alt: 'Three illustrated output paths leave a retirement plan: a readable report, a spreadsheet ledger, and a secure backup file.',
+    },
+    {
+      type: 'table',
+      caption: 'Which export to use.',
+      columns: ['Output', 'Where it lives', 'Best for'],
+      rows: [
+        ['Printable report', 'Report route from Results', 'A clean summary for review, printing, or saving as PDF'],
+        ['HTML report', 'Download HTML report on Results or Report; recommendation report on Optimize', 'A self-contained audit bundle with assumptions, sources, warnings, annual ledger data, and recommendation evidence when available'],
+        ['CSV ledger', 'Download CSV on Results', 'Spreadsheet inspection of nominal year-by-year income, tax, withdrawals, and balances'],
+        ['JSON backup', 'Planner home', 'Saving or moving editable plans to another browser or device'],
+        ['Duplicate plan', 'Planner home or workspace controls', 'Trying a new version without changing the original'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Lee household',
+      assumptions: [
+        { label: 'Advisor review', value: 'Save a 12-page printable report as PDF' },
+        { label: 'Audit file', value: 'Download the HTML report so assumptions, sources, and recommendation evidence travel with the results' },
+        { label: 'Personal audit', value: 'Download the 35-year CSV and inspect taxes, MAGI, and withdrawals by year' },
+        { label: 'Device move', value: 'Download one JSON backup, then import it in the other browser' },
+      ],
+      summary:
+        'The files are not interchangeable. The PDF reads like a summary, the HTML report carries audit context, the 35-year CSV audits the ledger, and the JSON backup is the only one that preserves the editable inputs.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'The **Results** page has **Download CSV**, **Download HTML report**, and **View printable report**. The **Optimize** page can download a recommendation report once the optimizer has run, including the exact-ledger evidence behind the recommendation. The CSV uses the nominal year-by-year ledger, even if the screen is currently toggled to today\'s dollars. The planner home has **Download plan backup** and **Import previous backup** for moving the underlying plan data.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Sending a JSON backup when the other person only needs a report.',
+        'Assuming the CSV follows the Results today-dollar toggle.',
+        'Clearing browser data before downloading a backup.',
+        'Sharing a file without realizing it may include sensitive household and account details.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Results** for the CSV, HTML report, and printable report. Use **Optimize** for a recommendation report after running the optimizer. Use the planner home for backups, imports, duplicates, and clearing all local data.',
+    },
+  ],
+}

package/src/learn/content/risk-based-guardrails.ts

@@ -0,0 +1,100 @@
+import type { LearningArticle } from '../learningRegistry'
+
+export const riskBasedGuardrailsArticle: LearningArticle = {
+  slug: 'risk-based-guardrails',
+  title: 'Risk-based guardrails',
+  description:
+    'Guardrails triggered by your plan’s probability of success — in dollars — and why they cut less than withdrawal-rate rules in bad markets.',
+  category: 'risk-uncertainty',
+  tags: ['guardrails', 'spending', 'monte carlo', 'probability of success', 'sequence risk', 'flexibility'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-07-08',
+  reviewCadence: 'stable',
+  sourceUrls: [
+    'https://www.kitces.com/blog/probability-of-success-driven-guardrails-advantages-monte-carlo-simulations-analysis-communication/',
+    'https://www.kitces.com/blog/monte-carlo-guardrails-probability-of-adjustment-success-client-communication-dynamic-retirement-spending/',
+    'https://www.kitces.com/blog/renaming-the-outcomes-of-a-monte-carlo-retirement-projection/',
+    'https://www.onefpa.org/journal/Pages/Decision-Rules-and-Portfolio-Management-for-Retirees.aspx',
+  ],
+  relatedArticles: [
+    'dynamic-spending-guardrails',
+    'understanding-monte-carlo-success-rate',
+    'sequence-of-returns-risk',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/spending', '/plan/:planId/monte-carlo', '/plan/:planId/results'],
+  currentYearSensitive: false,
+  priority: 'P1',
+  featured: false,
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Withdrawal-rate guardrails (Guyton–Klinger style) adjust spending when your current withdrawal rate drifts too far from where it started. Risk-based guardrails ask a different question: **has the plan’s probability of success actually left the band I’m comfortable with?** Spending changes only when the answer is yes — and the trigger is expressed in dollars, so you know in advance exactly what portfolio balance calls for a change.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        '**Triggers on plan odds, not a ratio**: A withdrawal rate can look alarming while the plan is still overwhelmingly likely to work — especially late in retirement, when a shorter horizon safely supports a higher rate.',
+        '**Dollar-denominated**: The rule reads like an instruction, not a formula: "if the portfolio falls below $X, trim spending; above $Z, a raise is safe."',
+        '**Usually cuts less in crashes**: Published practitioner research replaying 2007 retirees found withdrawal-rate rules forced cuts an order of magnitude deeper than probability-based triggers, because the rate rule keeps cutting while the ratio stays elevated even when the odds have stabilized.',
+      ],
+    },
+    { type: 'heading', text: 'How the thresholds are found' },
+    {
+      type: 'prose',
+      md: 'You pick a target success band — say 70–95%. RetireGolden then re-runs your plan’s Monte Carlo simulation at progressively lower (and higher) starting balances, on the same seeded market paths each time, and searches for the balance where the probability of success crosses each edge of the band.\n\nBelow the lower threshold, the flexible slice of spending (everything above your required floor) is trimmed in steps; above the upper threshold it is restored, and can rise into ideal/excess layers if you allow raises. The required floor is never cut. The solver also sizes the adjustment: the dollars per month of spending change that would bring the plan back to the middle of your band.',
+    },
+    { type: 'heading', text: 'Why "78% success" was the wrong headline anyway' },
+    {
+      type: 'prose',
+      md: 'A single probability-of-success number reads like a grade, and it hides what actually matters: **what happens in the failing paths**. A plan with flexible spending rarely "fails" outright — it adjusts. The more useful questions are how likely an adjustment is, how big it tends to be, and how long it lasts. RetireGolden’s Monte Carlo page reports exactly that for guardrail plans: the share of paths that ever needed a cut, the median and 90th-percentile depth of the deepest cut, the typical years spent below target, and the probability the plan ends with a surplus (or clears your bequest target).',
+    },
+    {
+      type: 'table',
+      columns: ['Question', 'Old answer', 'Adjustment-focused answer'],
+      rows: [
+        ['Will my plan work?', '"78% success"', 'P(any spending cut), and its typical size and duration'],
+        ['What do I do in a crash?', 'Re-run the plan and guess', 'A pre-agreed dollar threshold and a pre-sized cut'],
+        ['What if things go well?', 'Nothing changes', 'A dollar threshold above which a raise is safe'],
+        ['What is left at the end?', 'Implied by the success %', 'P(surplus) and P(estate clears the bequest target)'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Okafor household',
+      assumptions: [
+        { label: 'Starting portfolio', value: '$1,200,000' },
+        { label: 'Target success band', value: '70–95%' },
+        { label: 'Solved cut threshold', value: '$780,000 (65% of the starting portfolio, today’s dollars)' },
+        { label: 'Solved raise threshold', value: '$1,560,000 (130%)' },
+        {
+          label: 'A 2008-scale drawdown arrives',
+          value: 'The portfolio falls to $850,000. A withdrawal-rate rule would already be cutting — the rate is ~40% above where it started — but the plan’s success probability is still inside the band, so risk-based guardrails hold.',
+        },
+        {
+          label: 'The drawdown deepens',
+          value: 'Below $780,000 the odds genuinely leave the band; flexible spending is trimmed in 10% steps until markets recover.',
+        },
+      ],
+      summary:
+        'Both rules protect the plan. The difference is how often they interrupt your lifestyle to do it: the risk-based trigger tolerates drawdowns the plan can genuinely afford.',
+    },
+    { type: 'heading', text: 'Honest boundaries' },
+    {
+      type: 'list',
+      items: [
+        '**Thresholds are solved for today’s conditions**: They are computed from your current plan, horizon, and market model. Re-solve after meaningful changes (spending, accounts, retirement date) — RetireGolden stores them with your plan and shows when they exist.',
+        '**A model, not a promise**: The probability of success is itself a Monte Carlo estimate under an assumed market model. The dollar thresholds inherit those assumptions.',
+        '**Inside the simulation, thresholds stay fixed in real terms**: A full re-solve every projected year would be another layer of modeling; RetireGolden applies your solved thresholds (inflation-adjusted) across the horizon — a documented simplification.',
+        '**Flexibility has to be real**: The rule only helps if the flexible slice of your budget is genuinely cuttable. Set your required floor honestly.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'On **Spending**, choose *Risk-based guardrails (success band)* as the spending policy, set your band, and press *Solve dollar thresholds*. **Results** shows the thresholds in dollars and marks the years the rule acted. **Monte Carlo** reports the adjustment outlook — probability, size, and duration of cuts, plus the chance of ending with a surplus — alongside the classic success rate.',
+    },
+  ],
+}

package/src/learn/content/rmds-required-minimum-distributions.ts

@@ -0,0 +1,100 @@
+/**
+ * "RMDs: required minimum distributions" - a Withdrawals and Roth P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const rmdsRequiredMinimumDistributionsArticle: LearningArticle = {
+  slug: 'rmds-required-minimum-distributions',
+  title: 'RMDs: required minimum distributions',
+  description: 'The withdrawals the IRS eventually forces from pre-tax accounts.',
+  category: 'withdrawals-roth',
+  tags: ['rmd', 'required minimum distribution', 'traditional ira', '401k', 'secure 2.0', 'withdrawals'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.irs.gov/retirement-plans/retirement-plan-and-ira-required-minimum-distributions-faqs',
+    'https://www.irs.gov/forms-pubs/about-publication-590-b',
+  ],
+  relatedArticles: [
+    'withdrawal-order-basics',
+    'qcds-qualified-charitable-distributions',
+    'roth-conversion-basics',
+    'how-the-optimizer-values-after-tax-estate',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/accounts', '/plan/:planId/strategy', '/plan/:planId/results'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'A required minimum distribution, or RMD, is the minimum amount the tax rules require you to withdraw each year from many pre-tax retirement accounts after a certain age. It can turn a quiet traditional IRA into taxable income whether or not you need the cash.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'RMDs usually apply to traditional pre-tax retirement accounts, not Roth IRAs during the original owner\'s lifetime.',
+        'The basic formula uses the prior year-end balance divided by a life-expectancy factor.',
+        'RMDs happen before Roth conversions in the model because an RMD cannot be converted to Roth.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Traditional retirement accounts often got a tax break on the way in. RMDs are one way the tax system eventually pulls some of that deferred income onto the tax return. The amount generally grows when balances are high or the life-expectancy divisor gets smaller with age.\n\nThis is why Roth conversions before RMD age can matter. If they reduce the future traditional balance, they may reduce future RMD pressure.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/rmds-required-minimum-distributions.webp' },
+      caption:
+        'After the RMD start point, a required flow leaves the traditional bucket each year and enters the taxable cash-flow system.',
+      alt: 'A traditional retirement bucket sits beside a timeline. After a checkpoint, an amber required-flow ribbon moves from the bucket toward a tax building and spending basket.',
+    },
+    { type: 'heading', text: 'A simple formula' },
+    {
+      type: 'formula',
+      expression: 'RMD = prior year-end balance / distribution divisor',
+      where: [
+        { symbol: 'prior year-end balance', meaning: 'the account balance used as the base for the distribution' },
+        { symbol: 'distribution divisor', meaning: 'the IRS life-expectancy factor for the applicable table and age' },
+      ],
+      basis: 'nominal',
+      note: 'This is the simplified annual planning formula. Real administration can include first-year timing, account aggregation rules, inherited-account rules, plan-specific details, and penalties for missed RMDs.',
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Nguyen household',
+      assumptions: [
+        { label: 'Traditional IRA', value: '$900,000 projected balance before RMD age' },
+        { label: 'Estimated first RMD', value: 'About $33,000 if no earlier conversions reduce the balance' },
+        { label: 'Conversion test', value: 'A $40,000 annual conversion for five years lowers future RMD pressure' },
+      ],
+      summary:
+        'Five $40,000 conversions move **$200,000** out of the pre-tax bucket before RMD age. That can lower forced withdrawals later, but only if the earlier tax cost is worth it.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden applies RMDs to traditional accounts using the SECURE 2.0 start ages in the parameter logic and the Uniform Lifetime Table. If a spouse is marked as the sole beneficiary and is more than 10 years younger, the model can use a larger joint-life divisor. RetireGolden takes the RMD in the age-attained year and does not model the first-year April 1 deferral.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Planning withdrawals as if all future traditional-account withdrawals are optional.',
+        'Forgetting that RMDs can raise MAGI, Medicare premiums, Social Security taxation, or survivor-year taxes.',
+        'Trying to convert the RMD itself to Roth.',
+        'Assuming the app is handling every plan-administration detail for a real tax filing.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Accounts** to classify traditional accounts and set spouse beneficiary details when relevant. Use **Results** to inspect the RMD column, traditional withdrawals, tax, and MAGI by year.',
+    },
+  ],
+}

package/src/learn/content/roth-conversion-basics.ts

@@ -0,0 +1,104 @@
+/**
+ * "Roth conversion basics" - a Withdrawals and Roth P0 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const rothConversionBasicsArticle: LearningArticle = {
+  slug: 'roth-conversion-basics',
+  title: 'Roth conversion basics',
+  description: 'What a Roth conversion is and why people do them in retirement.',
+  category: 'withdrawals-roth',
+  tags: ['roth conversion', 'traditional ira', 'taxable income', 'roth ira', 'withdrawals'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-19',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.irs.gov/retirement-plans/roth-iras',
+    'https://www.irs.gov/retirement-plans/plan-participant-employee/rollovers-of-retirement-plan-and-ira-distributions',
+    'https://www.irs.gov/retirement-plans/retirement-plans-faqs-regarding-iras',
+  ],
+  relatedArticles: [
+    'traditional-vs-roth-contributions',
+    'filling-a-tax-bracket-with-roth-conversions',
+    'why-roth-conversions-raise-other-costs',
+    'how-the-optimizer-values-after-tax-estate',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/strategy', '/plan/:planId/optimize', '/plan/:planId/results'],
+  currentYearSensitive: true,
+  priority: 'P0',
+  featured: true,
+  blocks: [
+    {
+      type: 'prose',
+      md: 'A Roth conversion moves money from a pre-tax retirement account into a Roth account. The converted amount usually counts as taxable income now. In exchange, future qualified Roth withdrawals can be tax-free.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'A conversion is a **tax timing trade**: pay tax now to potentially avoid tax later.',
+        'The best conversion year is often a low-income year before required distributions, Medicare surcharges, or survivor-year tax brackets bite.',
+        'More conversion is not automatically better. Extra income can push on other tax and healthcare rules.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Traditional IRA and traditional 401(k) dollars usually have not been taxed yet. A Roth conversion deliberately brings some of those dollars into income now, then moves the after-tax retirement asset into the Roth bucket.\n\nThat can make sense when today\'s tax cost is lower than the tax cost you expect later: future required minimum distributions, survivor tax brackets, higher heir tax rates, or a long runway for Roth growth.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/roth-conversion-flow.webp' },
+      caption:
+        'A Roth conversion moves pre-tax dollars through today\'s tax gate into the Roth bucket, where future qualified withdrawals may be tax-free.',
+      alt: 'A traditional account bucket sends money through a tax gate into a Roth bucket, with a timeline showing tax paid now and future Roth flexibility.',
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Nguyen household',
+      assumptions: [
+        { label: 'Current year', value: 'Retired at 62, before Social Security and RMDs' },
+        { label: 'Traditional IRA', value: '$700,000 balance that could create future RMD pressure' },
+        { label: 'Conversion test', value: '$30,000 conversion while taxable income is relatively low' },
+      ],
+      summary:
+        'The $30,000 conversion raises tax this year, but it also moves $30,000 into Roth and shrinks the account future RMDs are based on. The example is about timing, not free money.',
+    },
+    { type: 'heading', text: 'What changes when you convert' },
+    {
+      type: 'table',
+      caption: 'A simple before-and-after view of a conversion.',
+      columns: ['Part of the plan', 'Before conversion', 'After conversion'],
+      rows: [
+        ['Traditional balance', 'Higher; future withdrawals are usually taxable', 'Lower; future RMD pressure may be smaller'],
+        ['Roth balance', 'Lower or unchanged', 'Higher; qualified withdrawals may be tax-free'],
+        ['Current-year income', 'Lower', 'Higher by the converted amount'],
+        ['Current-year tax', 'Lower', 'Often higher because the conversion is income'],
+        ['Future flexibility', 'More money still trapped in pre-tax form', 'More money available from Roth if rules are met'],
+      ],
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden models Roth conversions in the annual ledger. Conversions raise ordinary income in the conversion year, move dollars from traditional to Roth, and then affect later taxes, RMDs, account balances, and after-tax estate value.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Judging the conversion only by this year\'s tax bill.',
+        'Converting so much that Medicare, ACA, or Social Security tax interactions swamp the intended benefit.',
+        'Forgetting that paying conversion tax from the IRA itself can leave less money invested.',
+        'Assuming a conversion is reversible. Modern Roth conversions generally need to be planned as final decisions.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use the **Strategy** screen for manual or fill-to-target conversion rules. Use **Optimize** when you want RetireGolden to search for a multi-year schedule and then re-check it in **Results** and **Monte Carlo**.',
+    },
+  ],
+}