@retiregolden/planner-ui 0.1.0

package/src/learn/content/pia-aime-and-bend-points.ts

@@ -0,0 +1,103 @@
+/**
+ * "PIA, AIME, and bend points" - a Social Security P0 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const piaAimeBendPointsArticle: LearningArticle = {
+  slug: 'pia-aime-and-bend-points',
+  title: 'PIA, AIME, and bend points',
+  description: 'How your earnings history becomes a base benefit amount.',
+  category: 'social-security',
+  tags: ['social security', 'pia', 'aime', 'bend points', 'earnings record', 'wage indexing'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-06-19',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.ssa.gov/oact/COLA/Benefits.html',
+    'https://www.ssa.gov/oact/COLA/piaformula.html',
+    'https://www.ssa.gov/oact/COLA/bendpoints.html',
+  ],
+  relatedArticles: [
+    'social-security-claiming-age-basics',
+    'earnings-test-before-fra',
+    'break-even-useful-lens',
+    'cola-and-inflation-protection',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/social-security', '/plan/:planId/social-security-analysis'],
+  currentYearSensitive: true,
+  priority: 'P0',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Primary insurance amount (PIA) is the monthly Social Security retirement benefit you would receive if you claim at full retirement age. RetireGolden can take PIA directly from your SSA statement or estimate it from covered earnings.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'AIME means average indexed monthly earnings: a wage-indexed monthly average of your strongest earning years.',
+        'Bend points are the tiers that turn AIME into PIA.',
+        'The first AIME tier is replaced at a higher percentage than later tiers, so extra earnings help most when they replace low or zero years.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Social Security does not simply pay back what you paid in. It first indexes covered earnings to account for national wage growth, averages the strongest years into AIME, then applies a tiered formula.\n\nThe formula is progressive. A dollar of AIME in the first tier counts more than a dollar in the later tiers. That is why replacing a zero year can matter a lot for one person and barely move the answer for another.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/pia-aime-bend-points.webp' },
+      caption:
+        'Covered earnings are indexed and averaged into AIME, then passed through bend-point tiers to produce the base benefit.',
+      alt: 'Many annual earnings tiles flow through a funnel into an average bucket, then through a three-tier bend-point container into a benefit stream.',
+    },
+    { type: 'heading', text: 'The formula path' },
+    {
+      type: 'formula',
+      expression: 'PIA = 90% of the first AIME tier + 32% of the middle tier + 15% of AIME above the second bend point',
+      where: [
+        { symbol: 'PIA', meaning: 'Primary insurance amount, the monthly benefit at full retirement age' },
+        { symbol: 'AIME', meaning: 'Average indexed monthly earnings' },
+        { symbol: 'bend points', meaning: 'Dollar thresholds for the tiered Social Security formula' },
+      ],
+      note:
+        "This is the simplified retirement-benefit formula. SSA applies bend points for the worker's eligibility year, so AIME and PIA are in that formula year's basis, not necessarily current-year or today's dollars.",
+    },
+    { type: 'heading', text: 'What each term means' },
+    {
+      type: 'table',
+      caption: 'The earnings-record path in plain language.',
+      columns: ['Term', 'Plain-language meaning', 'Why it matters'],
+      rows: [
+        ['Covered earnings', 'Wages or self-employment income taxed for Social Security', 'Only covered earnings count toward the retirement benefit'],
+        ['Wage indexing', 'Older earnings are adjusted using national wage growth', 'A dollar earned decades ago is not treated like a current dollar'],
+        ['AIME', 'The monthly average after indexing and selecting the strongest years', 'This is the number fed into the benefit formula'],
+        ['Bend points', 'The tier thresholds for the formula', 'The same extra AIME can have different value depending on the tier'],
+        ['PIA', 'The base monthly benefit at full retirement age', 'Claiming age then reduces or increases this base amount'],
+      ],
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden lets you use **Quick** mode by entering PIA directly, or **Earnings record** mode by pasting or importing covered earnings. Earnings mode computes AIME and PIA, shows whether zero years are dragging the average down, and warns when future SSA tables are not yet published.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Entering the monthly check at a planned claim age instead of PIA at full retirement age.',
+        'Assuming every extra year of work raises the benefit by the same amount.',
+        'Forgetting that an SSA statement may assume future earnings continue if you have not retired yet.',
+        'Treating a future-year PIA estimate as final before SSA publishes the wage and bend-point tables for that year.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Social Security** to enter PIA directly or switch to the earnings-record mode. If you use earnings mode, read the AIME and bend-point explainer below the entry box before comparing claim ages.',
+    },
+  ],
+}

package/src/learn/content/planner-overview.ts

@@ -0,0 +1,106 @@
+/**
+ * "Planner overview: from household to results" - a Using RetireGolden P0 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const plannerOverviewArticle: LearningArticle = {
+  slug: 'planner-overview',
+  title: 'Planner overview: from household to results',
+  description: 'A guided tour of the planner sections and the order to fill them in.',
+  category: 'using-retiregolden',
+  tags: ['planner', 'workflow', 'household', 'accounts', 'results', 'retiregolden'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'stable',
+  sourceUrls: [],
+  relatedArticles: [
+    'about-retiregolden',
+    'what-retiregolden-models',
+    'three-big-questions-spending-time-risk',
+    'reading-the-results-page',
+    'understanding-monte-carlo-success-rate',
+  ],
+  relatedPlannerRoutes: [
+    '/plan/:planId/household',
+    '/plan/:planId/accounts',
+    '/plan/:planId/spending',
+    '/plan/:planId/results',
+    '/plan/:planId/report',
+  ],
+  currentYearSensitive: false,
+  priority: 'P0',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'The planner is organized as a loop: enter the household and money facts, read the result, then explore changes. You do not need every field perfect before the first run. You need the main facts good enough to learn what deserves attention.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Fill the Enter sections first: Household, Social Security, Accounts, Insurance, Income, Spending, Strategy, and Assumptions.',
+        'Use Results as the baseline, then use Monte Carlo, Scenarios, Optimize, and Compare plans for exploration.',
+        'Plans are stored on this device, so download a backup if you want a copy outside the browser.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'RetireGolden turns your inputs into a year-by-year projection. The left rail separates entry screens from exploration screens. Entry screens describe the plan. Exploration screens ask what the plan implies and how it changes under stress.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/planner-overview.webp' },
+      caption:
+        'The planner flows from household facts and account inputs into results, risk views, scenarios, and optimization.',
+      alt: 'A left-to-right workflow shows household, income, accounts, spending, strategy, and assumptions feeding results, then branching to risk, scenarios, optimize, and report outputs.',
+    },
+    {
+      type: 'table',
+      caption: 'A practical first-pass order.',
+      columns: ['Step', 'Section', 'What to get roughly right'],
+      rows: [
+        ['1', 'Household', 'People, filing status, state, retirement ages, and planning ages'],
+        ['2', 'Social Security', 'Claim ages and benefit estimates'],
+        ['3', 'Accounts', 'Balances, account types, owners, cost basis, and contributions'],
+        ['4', 'Income and Spending', 'Non-portfolio income, base expenses, goals, healthcare, and debt'],
+        ['5', 'Strategy and Assumptions', 'Withdrawal order, Roth conversion approach, inflation, returns, and tax assumptions'],
+        ['6', 'Results and Explore screens', 'Whether the baseline works, which risks matter, and which choices to compare'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Avery household',
+      assumptions: [
+        { label: 'First pass', value: '$900,000 savings, $95,000 annual spending, rounded account details' },
+        { label: 'First result', value: 'Money lasts in Results, but Monte Carlo shows 72% success' },
+        { label: 'Next edit', value: 'Refines spending to $88,000 and adds taxable cost basis' },
+      ],
+      summary:
+        'The rough plan is useful because it points to the two biggest inputs: spending and taxable basis. After the edits, the same household can see whether 72% success was a data problem or a real risk.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'The KPI bar updates as the plan changes, and each plan is saved locally in the browser. The deterministic projection feeds Results, while Monte Carlo, Scenarios, and Optimize reuse the same plan data to answer different questions.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Starting with Optimize before the baseline inputs make sense.',
+        'Leaving account types wrong and then trusting tax results.',
+        'Comparing two plans that use different spending or return assumptions without noticing.',
+        'Forgetting to save a downloaded backup before clearing browser data or changing devices.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use this overview when starting a new plan. After the first baseline, move between **Results**, **Monte Carlo**, **Scenarios**, and **Optimize** depending on whether you want to inspect, stress-test, compare, or search for a Roth conversion schedule.',
+    },
+  ],
+}

package/src/learn/content/planning-for-couples-and-survivor-years.ts

@@ -0,0 +1,108 @@
+/**
+ * "Planning for couples and survivor years" - a Start Here P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const planningForCouplesAndSurvivorYearsArticle: LearningArticle = {
+  slug: 'planning-for-couples-and-survivor-years',
+  title: 'Planning for couples and survivor years',
+  description: 'Why the years after one spouse dies deserve their own attention.',
+  category: 'start-here',
+  tags: ['couples', 'survivor', 'widow penalty', 'social security', 'planning horizon'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'rule-change',
+  sourceUrls: [
+    'https://www.ssa.gov/benefits/survivors/',
+    'https://www.irs.gov/filing/federal-income-tax-rates-and-brackets',
+  ],
+  relatedArticles: [
+    'spousal-and-survivor-benefits',
+    'widows-penalty-and-survivor-brackets',
+    'how-assumptions-change-the-answer',
+    'survivor-planning-for-couples',
+    'social-security-claiming-age-basics',
+  ],
+  relatedPlannerRoutes: [
+    '/plan/:planId/household',
+    '/plan/:planId/social-security',
+    '/plan/:planId/insurance',
+    '/plan/:planId/results',
+    '/plan/:planId/scenarios',
+  ],
+  currentYearSensitive: false,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'A couple plan has two phases: the years when both spouses are alive and the years when one person may be managing the household alone. The second phase can look financially different even when the lifestyle feels similar.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'A survivor may keep only the larger Social Security check, not both checks.',
+        'Taxes can rise because the survivor often moves from joint brackets to single brackets.',
+        'Some expenses fall after the first death, but housing, taxes, insurance, and healthcare may not fall by half.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'The surviving spouse is still paying for a household, but with fewer income streams and a different tax shape. This is why a plan that looks comfortable for two people can still deserve a survivor-year check. It is not pessimism. It is protecting the person who may have fewer choices later.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/couples-survivor-years.webp' },
+      caption:
+        'A couple plan should inspect both the joint years and the one-spouse survivor years.',
+      alt: 'Two retirement paths travel together, then one continues alone with Social Security, tax, and spending markers still ahead.',
+    },
+    {
+      type: 'table',
+      caption: 'What often changes after the first death.',
+      columns: ['Item', 'Joint years', 'Survivor years'],
+      rows: [
+        ['Social Security', 'Two checks may be paid', 'Usually the survivor keeps the larger eligible check'],
+        ['Tax filing', 'Married filing jointly may apply', 'Single brackets may apply after transition rules'],
+        ['Spending', 'Two-person household costs', 'Some costs fall, but fixed household costs remain'],
+        ['Healthcare', 'Two people insured', 'One person remains exposed to premiums, care costs, and inflation'],
+        ['Decision load', 'Shared decisions', 'One person may need simpler records and safer liquidity'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Rivera household',
+      assumptions: [
+        { label: 'Joint years', value: '$72,000 of combined Social Security while both spouses are alive' },
+        { label: 'Survivor income', value: '$44,000 larger benefit continues after the smaller check stops' },
+        { label: 'Survivor cost', value: 'Spending falls 25%, not 50%, because housing and insurance remain' },
+      ],
+      summary:
+        'Income falls by about **$28,000**, while spending falls only 25%. The survivor years need their own read because the gap can widen even when the couple-year plan looks comfortable.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden tracks each person in the household, each person\'s planning age, Social Security claim age, account ownership, insurance, and tax filing status. That lets the projection show the years after one spouse dies instead of stopping at the first death.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Planning only to the older spouse or the first life expectancy.',
+        'Assuming expenses fall in half when one spouse dies.',
+        'Ignoring which Social Security benefit protects the survivor.',
+        'Missing the tax effect of moving from joint brackets to single brackets.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Household** to set each planning age, **Social Security** to enter benefits and claim ages, **Insurance** for survivor protection, and **Results** to inspect late years after one spouse is no longer alive.',
+    },
+  ],
+}

package/src/learn/content/privacy-what-stays-in-your-browser.ts

@@ -0,0 +1,99 @@
+/**
+ * "Privacy: what stays in your browser" - a Using RetireGolden P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const privacyWhatStaysInYourBrowserArticle: LearningArticle = {
+  slug: 'privacy-what-stays-in-your-browser',
+  title: 'Privacy: what stays in your browser',
+  description: 'Why your plan data never leaves your device and what that implies.',
+  category: 'using-retiregolden',
+  tags: ['privacy', 'browser storage', 'backup', 'indexeddb', 'local storage'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'stable',
+  sourceUrls: [],
+  relatedArticles: [
+    'planner-overview',
+    'reports-csv-exports-and-sharing',
+    'what-retiregolden-models',
+    'using-assumptions-and-provenance',
+    'troubleshooting-surprising-results',
+  ],
+  relatedPlannerRoutes: ['/', '/plan/:planId/report'],
+  currentYearSensitive: false,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'RetireGolden does not have accounts or server-side plan storage. The plan data you enter stays in this browser on this device. That is good for privacy, but it also means you are responsible for backups.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'V2 plans are stored locally in IndexedDB, with some older/import helper data in localStorage.',
+        'RetireGolden cannot recover a plan after you clear browser data or switch devices without a backup.',
+        'A JSON backup is the way to keep or move editable plans outside the browser.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Local-first storage means the app can save your plan without creating an online account. It also means the browser is the vault. If that browser profile is deleted, reset, or unavailable, RetireGolden has no server copy to restore from.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/browser-privacy.webp' },
+      caption:
+        'Local browser storage protects plan privacy, but backups are how you keep a recoverable copy.',
+      alt: 'A browser window holds a private retirement plan vault, with a backup file placed outside it for safekeeping.',
+    },
+    {
+      type: 'table',
+      caption: 'What this privacy model means in practice.',
+      columns: ['Situation', 'What happens', 'Best habit'],
+      rows: [
+        ['Normal planning', 'The browser saves your plans locally', 'Keep working in the same browser profile'],
+        ['Sharing a computer', 'Anyone with that browser profile may be able to open the plans', 'Use an OS account you control'],
+        ['Clearing site data', 'Plans and older RetireGolden entries may be erased', 'Download a backup first'],
+        ['Moving devices', 'The new device has no copy automatically', 'Import a JSON backup'],
+        ['Asking for support', 'There is no server copy to inspect', 'Share only the report or details you choose'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Singh household',
+      assumptions: [
+        { label: 'Before travel', value: 'Download a JSON backup after updating 2 plans' },
+        { label: 'New laptop', value: 'Import the backup into the new browser and confirm both plans open in 1 browser' },
+        { label: 'Old browser cleanup', value: 'Clear local data from the old browser only after the 2 imported balances match' },
+      ],
+      summary:
+        'Nothing was synced to an account. The Singhs moved **2** plans by carrying **1** backup file themselves, then checked both balances before clearing the old browser.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'The planner home explains that data stays on your device and offers **Download plan backup**, **Import previous backup**, and **Clear all data**. The workspace also reminds you that plans live only in this browser.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Assuming there is an online account behind the scenes.',
+        'Using private browsing for long-term plan storage.',
+        'Clearing browser data before exporting a backup.',
+        'Emailing a full backup when a limited report would be safer.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use the planner home whenever you need to download a backup, import a prior backup, duplicate plans, or clear local RetireGolden data from the current browser.',
+    },
+  ],
+}

package/src/learn/content/qcds-qualified-charitable-distributions.ts

@@ -0,0 +1,101 @@
+/**
+ * "QCDs: qualified charitable distributions" - a Withdrawals and Roth P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const qcdsQualifiedCharitableDistributionsArticle: LearningArticle = {
+  slug: 'qcds-qualified-charitable-distributions',
+  title: 'QCDs: qualified charitable distributions',
+  description: 'Giving from an IRA in a way that can lower taxable income.',
+  category: 'withdrawals-roth',
+  tags: ['qcd', 'qualified charitable distribution', 'rmd', 'charity', 'ira', 'magi'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.irs.gov/retirement-plans/retirement-plans-faqs-regarding-iras-distributions-withdrawals',
+    '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: [
+    'rmds-required-minimum-distributions',
+    'withdrawal-order-basics',
+    'agi-magi-and-taxable-income',
+    'why-roth-conversions-raise-other-costs',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/strategy', '/plan/:planId/results'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'A qualified charitable distribution, or QCD, sends money directly from an IRA to a qualified charity. For people who are eligible, it can satisfy part of an RMD while keeping that donated amount out of taxable income.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'A QCD is a direct IRA-to-charity transfer, not a normal withdrawal followed by a personal donation.',
+        'QCDs can count toward RMDs while reducing taxable income and MAGI.',
+        'RetireGolden models QCDs as a planning-level annual amount routed out of RMDs, capped by the parameter pack.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'If you take an IRA distribution personally and then donate cash, the distribution may still raise AGI or MAGI. A QCD is different: the eligible charitable amount can be excluded from income when done correctly.\n\nThat can matter even for people who do not itemize deductions. Lower income can affect tax brackets, Social Security taxation, Medicare IRMAA, ACA credits before Medicare, and other income-sensitive rules.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/qcds-qualified-charitable-distributions.webp' },
+      caption:
+        'A QCD routes part of an IRA distribution directly to charity, bypassing the taxable-income path for that amount.',
+      alt: 'An RMD ribbon leaves a retirement bucket and splits. One branch goes through a tax gate to spending, while another branch goes directly to a charity basket.',
+    },
+    { type: 'heading', text: 'QCD versus ordinary donation' },
+    {
+      type: 'table',
+      caption: 'The routing is what makes a QCD different.',
+      columns: ['Choice', 'Cash path', 'Planning effect'],
+      rows: [
+        ['Normal IRA withdrawal, then donation', 'Money comes to you first', 'The withdrawal may still raise income'],
+        ['QCD', 'Money goes directly from IRA to charity', 'Eligible amount can be excluded from income'],
+        ['Roth or taxable-account gift', 'Money does not satisfy an IRA RMD', 'May still be charitable, but it is not the same planning lever'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Howard household',
+      assumptions: [
+        { label: 'RMD', value: '$42,000 required distribution for the year' },
+        { label: 'Giving habit', value: '$8,000 annual gift to charity' },
+        { label: 'Two paths', value: 'Take the full RMD into checking, or send $8,000 directly as a QCD' },
+      ],
+      summary:
+        'With the QCD path, only **$34,000** of the RMD flows into income in this simplified example. The gift still happens, but the tax return does not first absorb the full $42,000 distribution.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden has an annual QCD setting on the Strategy screen. The model routes QCD dollars out of RMDs when an eligible-age person is alive, excludes that amount from income, and caps it using the annual QCD limit in the parameter pack. It does not verify charity eligibility, transfer mechanics, receipts, or tax-form reporting.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Taking the IRA withdrawal personally and assuming a later donation is still a QCD.',
+        'Forgetting that QCD rules have eligibility and annual limit details.',
+        'Counting a QCD as both excluded income and an itemized charitable deduction.',
+        'Using the model as proof that a real charity or transfer qualifies.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Strategy** to enter an annual QCD amount. Use **Results** to compare RMD, QCD, tax, MAGI, and healthcare effects across years.',
+    },
+  ],
+}

package/src/learn/content/reading-the-results-page.ts

@@ -0,0 +1,96 @@
+/**
+ * "Reading the Results page" - a Using RetireGolden P0 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const readingResultsPageArticle: LearningArticle = {
+  slug: 'reading-the-results-page',
+  title: 'Reading the Results page',
+  description: 'What each headline number and chart on the Results page means.',
+  category: 'using-retiregolden',
+  tags: ['results', 'projection', 'balances', 'cash flow', 'magi', 'csv'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-19',
+  reviewCadence: 'stable',
+  sourceUrls: [],
+  relatedArticles: [
+    'how-to-read-a-retirement-projection',
+    'todays-dollars-vs-future-dollars',
+    'understanding-monte-carlo-success-rate',
+    'what-retiregolden-models',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/results', '/plan/:planId/report'],
+  currentYearSensitive: false,
+  priority: 'P0',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'The Results page is the deterministic version of your plan: one path, using the assumptions you entered. It is the best place to understand the mechanics before you ask risk questions.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Use the **Today\'s $ / Nominal $** toggle before judging any dollar amount.',
+        'Read the charts from top to bottom: balances, cash flow, taxes, then year-by-year details.',
+        'If a plan depletes, the first shortfall year matters more than the final zero.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Results answers one question: "If these assumptions happen, how does the plan unfold?" The charts summarize the ledger, and the table lets you inspect each year.\n\nThis is different from Monte Carlo. Results does not test hundreds or thousands of market paths. It shows the clean baseline, which makes it easier to find which inputs and cash flows are moving the plan.',
+    },
+    {
+      type: 'table',
+      caption: 'What each Results section is trying to tell you.',
+      columns: ['Section', 'What it shows', 'How to read it'],
+      rows: [
+        ['Dollar toggle', 'Today\'s dollars or nominal dollars', 'Use today\'s dollars for lifestyle comparisons; nominal dollars for ledger and tax-year mechanics.'],
+        ['Investable balances', 'End-of-year account balances by type', 'Watch which buckets empty first and whether a depletion marker appears.'],
+        ['Income vs spending', 'Income beside spending plus tax', 'The wider the gap, the more withdrawals must do.'],
+        ['Tax and MAGI', 'Estimated tax and modified adjusted gross income', 'Look for spikes that may explain Roth conversion, healthcare, or Social Security tax effects.'],
+        ['Year-by-year detail', 'The full annual ledger', 'Use it when a chart surprises you or you need the exact year something changes.'],
+      ],
+    },
+    { type: 'heading', text: 'A worked reading pattern' },
+    {
+      type: 'scenario',
+      name: 'The Chen household',
+      assumptions: [
+        { label: 'Baseline result', value: 'Money lasts through age 95' },
+        { label: 'Chart surprise', value: 'Traditional IRA falls from $700,000 to $420,000 in the early 70s' },
+        { label: 'Detail table clue', value: '$45,000 conversions and RMDs are both active in the same years' },
+      ],
+      summary:
+        'The headline says the plan lasts. The table explains why the IRA falls: conversions and RMDs are moving about **$45,000+** per year out of the pre-tax bucket.',
+    },
+    { type: 'heading', text: 'The year-by-year table' },
+    {
+      type: 'prose',
+      md: 'The table is the audit trail. It includes income, expenses, required minimum distributions, Roth conversions, withdrawals, tax, MAGI, shortfall, investable assets, and net worth. You do not need to read every row every time. Start with the first year that looks unusual.',
+    },
+    {
+      type: 'callout',
+      tone: 'note',
+      md: 'A blank shortfall cell is good news for that year. It means the modeled accounts covered the plan\'s cash needs for that year.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Comparing a today\'s-dollar chart to a nominal-dollar account statement.',
+        'Assuming a higher ending balance is always better without checking taxes, risk, or survivor years.',
+        'Ignoring MAGI because it looks like a tax detail. MAGI can also affect Medicare and ACA modeling in other parts of the plan.',
+        'Assuming the CSV follows the dollar toggle. The export uses the nominal year-by-year ledger, even when the screen is showing today\'s dollars.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Results** after every meaningful input change. Use **View printable report** when you want a clean summary, and **Download CSV** when you want to inspect or archive the nominal annual ledger outside the app.',
+    },
+  ],
+}