@retiregolden/planner-ui 0.1.0

package/src/learn/content/how-much-can-i-spend.ts

@@ -0,0 +1,105 @@
+/**
+ * "How much can I spend?" - a Using RetireGolden P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const howMuchCanISpendArticle: LearningArticle = {
+  slug: 'how-much-can-i-spend',
+  title: 'How much can I spend?',
+  description: 'How RetireGolden finds the highest sustainable baseline spending level for a plan.',
+  category: 'using-retiregolden',
+  tags: ['sustainable spending', 'solver', 'spending slack', 'bequest target', 'scenarios'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-07-06',
+  reviewCadence: 'stable',
+  sourceUrls: [],
+  relatedArticles: [
+    'building-a-retirement-spending-budget',
+    'spending-profiles-and-the-retirement-smile',
+    'survivor-spending-in-couple-plans',
+    'using-scenarios-to-compare-choices',
+    'after-tax-estate',
+  ],
+  relatedPlannerRoutes: [
+    '/plan/:planId/spending-solver',
+    '/plan/:planId/spending',
+    '/plan/:planId/optimize',
+    '/plan/:planId/insights',
+    '/plan/:planId/results',
+    '/plan/:planId/scenarios',
+  ],
+  currentYearSensitive: false,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'The "How much can I spend?" page turns a retirement plan around. Instead of asking whether your current spending works, it searches for the highest baseline spending level the exact projection ledger can sustain.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'The answer is annual baseline spending in today\'s dollars.',
+        'The solver reruns the same exact ledger used by Results: taxes, withdrawals, healthcare, Social Security, ACA, IRMAA, survivor years, and spending phases all count.',
+        'A bequest target on the Spending screen becomes an estate floor the answer must preserve.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'RetireGolden tests spending levels by bisection. It tries a baseline spending amount, runs the full projection, and checks whether the portfolio ever depletes or the ending after-tax estate falls below the bequest target. Then it moves the test higher or lower until it finds the highest feasible level within the interactive simulation budget.',
+    },
+    {
+      type: 'formula',
+      expression: 'spending slack = max sustainable baseline spending - current baseline spending',
+      basis: 'today',
+      note: 'Positive slack means the solved level is above the current baseline. Negative slack means the current baseline is higher than the ledger can sustain under the same assumptions.',
+    },
+    {
+      type: 'table',
+      caption: 'What the solver does and does not move.',
+      columns: ['Plan item', 'How the solver treats it', 'Why'],
+      rows: [
+        ['Baseline spending', 'Moves up or down', 'This is the question being solved'],
+        ['Spending phases and survivor percentage', 'Kept and priced into every tested level', 'They shape the baseline spending path'],
+        ['One-time goals', 'Kept as entered', 'A named goal should not become recurring spending'],
+        ['Healthcare, debt, property, insurance, taxes', 'Kept and recalculated through the ledger', 'They affect feasibility but are not the spending answer'],
+        ['Bequest target', 'Used as an ending estate floor', 'A spending level is not sustainable if it violates the floor'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Jordan household',
+      assumptions: [
+        { label: 'Current baseline', value: '$72,000 per year in today\'s dollars' },
+        { label: 'Bequest target', value: '$250,000 in today\'s dollars' },
+        { label: 'Solver answer', value: '$81,500 per year' },
+        { label: 'Spending slack', value: '+$9,500 per year' },
+      ],
+      summary:
+        'The answer means the exact ledger found a higher baseline that still avoids depletion and preserves the bequest floor. It does not mean every future path is risk-free.',
+    },
+    { type: 'heading', text: 'How to use the answer' },
+    {
+      type: 'prose',
+      md: 'Use the answer as a planning boundary. If the solved amount is much higher than current spending, you may have room for a scenario with higher lifestyle spending, earlier retirement, gifts, or a larger bequest target. If it is lower than current spending, the plan needs attention before Roth conversions or other fine tuning matter.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Treating the deterministic answer as a guarantee. Use Monte Carlo to test market variation.',
+        'Forgetting that one-time goals stay fixed. A large goal can reduce sustainable baseline spending without showing up as part of the answer.',
+        'Ignoring the binding constraint. A bequest target can be the limit even when the portfolio never depletes.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **How much can I spend?** from the Optimize rail. Use **Spending** to set the baseline, phases, survivor spending, and bequest target. Use **Add as scenario** to compare the solved spending level without changing the base plan.',
+    },
+  ],
+}

package/src/learn/content/how-social-security-is-taxed.ts

@@ -0,0 +1,95 @@
+/**
+ * "How Social Security is taxed" - a Taxes P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const howSocialSecurityIsTaxedArticle: LearningArticle = {
+  slug: 'how-social-security-is-taxed',
+  title: 'How Social Security is taxed',
+  description: 'Why up to 85% of benefits can become taxable income.',
+  category: 'taxes',
+  tags: ['social security', 'taxable benefits', 'provisional income', 'combined income', 'magi'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'annual',
+  sourceUrls: ['https://www.irs.gov/forms-pubs/about-publication-915'],
+  relatedArticles: [
+    'agi-magi-and-taxable-income',
+    'ordinary-income-vs-capital-gains',
+    'tax-cliffs-and-bracket-edges',
+    'why-roth-conversions-raise-other-costs',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/social-security', '/plan/:planId/results', '/plan/:planId/strategy'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Social Security benefits are not automatically tax-free and they are not automatically fully taxable. Federal tax law uses a formula that looks at benefits plus other income. As other income rises, more of the benefit can become taxable, up to a cap.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'The taxable share of Social Security depends on benefits plus other income.',
+        'Extra IRA withdrawals, Roth conversions, wages, or capital gains can make more benefits taxable.',
+        'RetireGolden models taxable Social Security as part of the federal tax calculation, not as a flat percentage.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'The Social Security tax formula uses a combined-income style calculation: other income plus a portion of benefits. When that measure crosses certain thresholds, part of the benefits enters taxable income. This can make the next dollar of other income cost more than expected, because it may bring some Social Security income along with it.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/social-security-taxation.webp' },
+      caption:
+        'Other income can pull more Social Security benefits into taxable income as the year fills up.',
+      alt: 'A Social Security ribbon runs beside other income streams toward a tax gate, with rising steps showing more of the benefit becoming taxable.',
+    },
+    {
+      type: 'formula',
+      expression: 'provisional income = income excluding Social Security + 50% of Social Security benefits',
+      where: [
+        { symbol: 'income excluding Social Security', meaning: 'ordinary income and gains before adding taxable benefits in RetireGolden\'s planning model' },
+        { symbol: '50% of Social Security benefits', meaning: 'half of the annual Social Security benefit used in the federal formula' },
+      ],
+      note: 'Tax-exempt interest and several form-level details are not separately modeled in RetireGolden.',
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Martin household',
+      assumptions: [
+        { label: 'Benefits', value: 'Social Security begins at 67' },
+        { label: 'Other income', value: '$30,000 traditional IRA withdrawal fills the spending gap' },
+        { label: 'Tax ripple', value: 'The withdrawal also makes about $12,000 more Social Security taxable' },
+      ],
+      summary:
+        'The tax return does not just see a $30,000 IRA withdrawal. It can also pull roughly **$12,000** more benefits into taxable income, so taxable income rises faster than the withdrawal alone.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden computes taxable Social Security inside the federal tax engine each year. The taxable portion feeds AGI, MAGI, deductions, taxable income, and the final tax calculation. The Results ledger shows the pieces so you can see when benefits start affecting taxes.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Assuming no Social Security is taxable because payroll tax was already paid.',
+        'Assuming exactly 85% is always taxable. That is only a maximum federal share.',
+        'Ignoring the effect of capital gains or Roth conversions on taxable benefits.',
+        'Forgetting that state treatment of Social Security can differ from federal treatment.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Social Security** to set claiming assumptions. Use **Results** to inspect Social Security income, taxable Social Security, AGI, MAGI, taxable income, and tax. Use **Strategy** to test whether different withdrawal or conversion choices change the taxable share.',
+    },
+  ],
+}

package/src/learn/content/how-the-optimizer-thinks.ts

@@ -0,0 +1,102 @@
+/**
+ * "How the Optimize tab thinks about Roth conversions" - a Using RetireGolden P0 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const howTheOptimizerThinksArticle: LearningArticle = {
+  slug: 'how-the-optimizer-thinks',
+  title: 'How the Optimize tab thinks about Roth conversions',
+  description: 'How the optimizer searches, how objective modes rank candidates, and how to interpret the result.',
+  category: 'using-retiregolden',
+  tags: ['optimizer', 'roth conversions', 'objective modes', 'after-tax estate', 'linear model', 'strategy'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-07-06',
+  reviewCadence: 'stable',
+  sourceUrls: [],
+  relatedArticles: [
+    'roth-conversion-basics',
+    'how-the-optimizer-values-after-tax-estate',
+    'filling-a-tax-bracket-with-roth-conversions',
+    'why-roth-conversions-raise-other-costs',
+    'understanding-monte-carlo-success-rate',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/optimize', '/plan/:planId/strategy', '/plan/:planId/results', '/plan/:planId/monte-carlo'],
+  currentYearSensitive: false,
+  priority: 'P0',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'The Optimize tab searches for a multi-year Roth conversion schedule, then compares candidate schedules on the exact RetireGolden ledger. The default objective is after-tax estate, but the **Optimize for** selector can rank the same evaluated candidates by other goals.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Optimize starts from a no-conversion baseline, then searches across plan years at once.',
+        'The solver uses a simplified math model to find a raw candidate schedule, then RetireGolden trims it to what the exact ledger can execute and measures the cleaned result.',
+        'Objective modes change what "better" means after candidates have been evaluated; they do not bypass the exact ledger.',
+        'A proposed schedule should still be checked in Results and Monte Carlo before you treat it as a good idea.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Roth conversions have timing effects. A conversion raises income and tax now, but can lower future traditional balances, RMDs, survivor-year pressure, and taxes owed by heirs. Optimize searches years together because the best year for one conversion depends on the conversions before and after it.\n\nAfter candidates are evaluated, the selected objective policy decides how to rank them. The default maximizes after-tax estate. Other modes can favor money lasting longer, lifetime tax savings while preserving an estate floor, survivor-year liquidity, or bridge-year resilience.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/optimizer-thinks-roth-conversions.webp' },
+      caption:
+        'Optimize searches a full conversion schedule, then measures the candidate against the exact RetireGolden ledger.',
+      alt: 'A conversion scheduler machine places bars across a timeline, then sends the proposed schedule through a detailed ledger check before reaching an after-tax estate comparison.',
+    },
+    {
+      type: 'table',
+      caption: 'What happens when Optimize runs.',
+      columns: ['Stage', 'What RetireGolden does', 'Why it matters'],
+      rows: [
+        ['Baseline probe', 'Runs the plan with conversions stripped out to capture spending, income, RMDs, and tax context', 'Gives the solver a clean starting point'],
+        ['Search', 'Uses a linearized model to test conversion amounts across years', 'Makes a multi-year search fast enough for the browser'],
+        ['Exact cleanup', 'Runs the raw schedule through the projection ledger, trims conversions the ledger cannot execute, and re-runs the cleaned schedule', 'Keeps the schedule applyable and tied to the same engine used by Results'],
+        ['Objective ranking', 'Ranks the exact-ledger evaluations under the selected objective policy', 'Lets the same candidates answer different planning questions without a second ranking system'],
+        ['Risk check', 'Runs a Monte Carlo success estimate for the proposed schedule', 'Shows whether the schedule appears to strain the plan under market variation'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Ortega household',
+      assumptions: [
+        { label: 'Early retirement window', value: 'Six low-income years before Social Security and RMDs' },
+        { label: 'Later pressure', value: '$850,000 traditional balance could create large future RMDs' },
+        { label: 'Optimizer result', value: '$35,000 conversions for several early years, then little or none later' },
+      ],
+      summary:
+        'The optimizer may accept higher tax on each $35,000 early conversion if it lowers later RMD pressure and improves after-tax estate. The value comes from the whole timeline, not one year.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'The Optimize tab shows after-tax estate delta, lifetime tax delta, success rate, and proposed conversions by year. When you choose a non-default objective, the page calls out that estate and tax deltas are context rather than the ranking metric. If the raw solver request is larger than the exact ledger can execute, the chart shows the cleaned schedule. "Apply optimized schedule" keeps the cleaned schedule labeled as optimizer output. "Accept as manual" copies the same cleaned amounts into an editable manual schedule under Strategy.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Thinking the optimizer minimizes lifetime tax. It may raise taxes while improving after-tax estate.',
+        'Switching objectives without reading the objective hint; a survivor-liquidity winner may not also be the largest-estate winner.',
+        'Applying a schedule without noticing whether the exact ledger cleaned or rejected part of the raw solver request.',
+        'Ignoring MAGI, IRMAA, ACA, and cash-flow effects in Results.',
+        'Assuming an infeasible result means Optimize is broken; often the plan has a spending shortfall before any conversion strategy matters.',
+        'Forgetting to test the heir tax rate assumption, which changes how valuable leftover traditional dollars appear.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Optimize** after the base plan works in **Results**. Then inspect the proposed years, check any raw-versus-cleaned differences, run **Monte Carlo**, and only then decide whether to apply or copy the schedule into **Strategy**.',
+    },
+  ],
+}

package/src/learn/content/how-the-optimizer-values-after-tax-estate.ts

@@ -0,0 +1,97 @@
+/**
+ * "How RetireGolden's optimizer values after-tax estate" - a Withdrawals and Roth P0 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const optimizerAfterTaxEstateArticle: LearningArticle = {
+  slug: 'how-the-optimizer-values-after-tax-estate',
+  title: "How RetireGolden's optimizer values after-tax estate",
+  description: 'Why the optimizer compares plans on what heirs keep after tax.',
+  category: 'withdrawals-roth',
+  tags: ['optimizer', 'after-tax estate', 'heir tax', 'roth conversion', 'traditional ira'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-06-19',
+  reviewCadence: 'stable',
+  sourceUrls: [],
+  relatedArticles: [
+    'roth-conversion-basics',
+    'filling-a-tax-bracket-with-roth-conversions',
+    'why-roth-conversions-raise-other-costs',
+    'after-tax-estate',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/optimize', '/plan/:planId/assumptions', '/plan/:planId/results'],
+  currentYearSensitive: false,
+  priority: 'P0',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'The optimizer is not trying to minimize this year\'s taxes. It is trying to leave the highest after-tax estate at the end of the plan, after accounting for the tax heirs might owe on inherited pre-tax money.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'A traditional IRA dollar and a Roth dollar are not equally valuable to heirs.',
+        'The optimizer applies a user-controlled heir tax rate to leftover traditional balances.',
+        'The proposed schedule is checked by re-running the exact RetireGolden ledger; if the raw request cannot be fully executed, RetireGolden measures the cleaned schedule instead.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'A pre-tax account can look larger than a Roth account, but some of that balance may really belong to future tax. For estate comparison, RetireGolden treats leftover traditional dollars as partly taxable to heirs, while Roth, taxable, cash, HSA, property, and life-insurance death benefit use simpler pass-through assumptions.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/after-tax-estate.webp' },
+      caption:
+        'The optimizer compares what is left after the assumed tax on inherited pre-tax dollars, not just the largest ending balance.',
+      alt: 'Two ending estate buckets are compared: a traditional bucket loses a slice to a tax gate while a Roth bucket passes through more fully to heirs.',
+    },
+    { type: 'heading', text: 'A quick formula' },
+    {
+      type: 'formula',
+      expression: 'after-tax estate = ending net worth - traditional balance * heir tax rate',
+      where: [
+        { symbol: 'ending net worth', meaning: 'the plan\'s modeled end-of-plan net worth' },
+        { symbol: 'traditional balance', meaning: 'leftover pre-tax retirement balance at the end of the plan' },
+        { symbol: 'heir tax rate', meaning: 'the assumed income-tax rate heirs pay on inherited pre-tax dollars' },
+      ],
+      basis: 'nominal',
+      note: 'This is a planning simplification for comparing strategies. The optimizer uses the assumption you set, then RetireGolden re-runs the full ledger and applies only a cleaned schedule that the ledger can execute.',
+    },
+    { type: 'heading', text: 'Why conversions can help the estate' },
+    {
+      type: 'prose',
+      md: 'A conversion can look bad in the year it happens because it raises tax. It can still help the after-tax estate if it moves money from a future-taxed bucket into a Roth bucket at a lower lifetime cost. The optimizer searches across years because one conversion can change later RMDs, taxes, Medicare costs, and ending balances.',
+    },
+    {
+      type: 'table',
+      caption: 'How the optimizer thinks about account buckets.',
+      columns: ['Bucket', 'How the optimizer treats it', 'Why it matters'],
+      rows: [
+        ['Traditional', 'Haircut by the heir tax rate at the end', 'A larger balance may not all belong to heirs'],
+        ['Roth', 'Kept whole in the estate comparison', 'Future qualified Roth dollars are more flexible'],
+        ['Taxable, cash, HSA, property', 'Simplified as passing through untaxed in the estate comparison', 'Keeps the optimizer focused on the pre-tax vs Roth trade'],
+        ['Current taxes', 'Counted through the exact ledger re-run', 'A good schedule must survive the real plan math'],
+      ],
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Expecting the optimizer to minimize lifetime tax. It may raise lifetime tax while still improving after-tax estate.',
+        'Leaving the heir tax rate at a default that does not match the question you want to test.',
+        'Applying a proposed schedule without checking Monte Carlo risk and yearly cash flow.',
+        'Treating the optimizer\'s math model as the final answer instead of the cleaned exact-ledger re-run shown in the app.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Optimize** to search for a conversion schedule. Use the heir tax rate slider to test sensitivity, then inspect **Results** for taxes, MAGI, RMDs, and ending after-tax estate.',
+    },
+  ],
+}

package/src/learn/content/how-to-model-accumulation.ts

@@ -0,0 +1,67 @@
+import type { LearningArticle } from '../learningRegistry'
+
+export const howToModelAccumulationArticle: LearningArticle = {
+  slug: 'how-to-model-accumulation',
+  title: 'How to model your accumulation in RetireGolden',
+  description: 'A guided tour of using salary growth, contribution schedules, and employer matches to build your plan.',
+  category: 'early-investing-fire',
+  tags: ['accumulation', 'tutorial', 'employer match', 'contribution schedule', 'raise rate'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-29',
+  reviewCadence: 'stable',
+  sourceUrls: [],
+  relatedArticles: [
+    'what-is-fire',
+    'savings-rate-biggest-lever',
+    'fi-number-and-four-percent-rule',
+  ],
+  relatedPlannerRoutes: [
+    '/plan/:planId/income',
+    '/plan/:planId/accounts',
+    '/plan/:planId/assumptions',
+    '/plan/:planId/scenarios',
+    '/plan/:planId/results',
+  ],
+  currentYearSensitive: false,
+  priority: 'P0',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'RetireGolden features robust controls designed specifically to model the wealth accumulation phase. This article walks you through configuring salary growth, matching, and schedules to map your journey to Financial Independence.',
+    },
+    { type: 'heading', text: 'Three key steps' },
+    {
+      type: 'list',
+      items: [
+        'Set up real salary growth on your wages in the Income screen.',
+        'Configure employer matches and custom contribution schedules in the Accounts screen.',
+        'Review the Path to Financial Independence card and SWR under Assumptions and Results.',
+      ],
+    },
+    {
+      type: 'scenario',
+      name: 'Walkthrough: Dana\'s setup',
+      assumptions: [
+        { label: 'Step 1 (Income)', value: 'Dana sets a 3% real raise rate on her $80,000 wages.' },
+        { label: 'Step 2 (Accounts)', value: 'Dana sets a 100% employer match up to 5% of pay on her 401(k), and schedules brokerage contributions.' },
+        { label: 'Step 3 (Results)', value: 'Dana views her FI Number and SWR target (4%) on the Results page.' },
+      ],
+      summary: 'Dana\'s plan now reflects realistic, compounding career growth rather than flat, static savings.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Entering nominal raises in the real raise field. Use the raise above inflation, not the total expected raise.',
+        'Turning on a contribution schedule and forgetting that it replaces the flat annual contribution.',
+        'Putting an employer match on an IRA. Matches belong on employer retirement accounts such as a 401(k) or 403(b).',
+      ],
+    },
+    { type: 'heading', text: 'Where this shows up in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'Each section has context-specific fields: **Real raise rate** in Income, **Employer match** and **Schedule contributions over time** in Accounts, the **Coast check: stop contributing** template in Scenarios, and the **Path to Financial Independence (FIRE)** chart card in Results.',
+    },
+  ],
+}

package/src/learn/content/how-to-read-a-retirement-projection.ts

@@ -0,0 +1,115 @@
+/**
+ * "How to read a retirement projection" - a Start Here P0 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const howToReadProjectionArticle: LearningArticle = {
+  slug: 'how-to-read-a-retirement-projection',
+  title: 'How to read a retirement projection',
+  description: 'What the lines, balances, and end-of-plan numbers in a projection actually tell you.',
+  category: 'start-here',
+  tags: ['projection', 'cash flow', 'results', 'shortfall', 'net worth'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-19',
+  reviewCadence: 'stable',
+  sourceUrls: [],
+  relatedArticles: [
+    'todays-dollars-vs-future-dollars',
+    'reading-the-results-page',
+    'understanding-monte-carlo-success-rate',
+    'what-retiregolden-models',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/results', '/plan/:planId/monte-carlo', '/plan/:planId/assumptions'],
+  currentYearSensitive: false,
+  priority: 'P0',
+  featured: true,
+  blocks: [
+    {
+      type: 'prose',
+      md: 'A retirement projection is not a forecast of what will happen. It is a year-by-year story of what could happen **if your assumptions are close enough**. The useful question is not "is this exact?" It is "what is driving the result?"',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Start with the **spending gap**: what income covers, and what the portfolio must cover.',
+        'Then look for the first stress year: a shortfall, a tax spike, a healthcare jump, or a balance that falls faster than expected.',
+        'Read the final number as a comparison tool, not a promise about your exact future wealth.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'A projection turns your inputs into a ledger. Each year starts with balances, adds income and investment growth, subtracts spending, taxes, premiums, debt, and withdrawals, then carries the remaining balances into the next year.\n\nThat simple rhythm matters because retirement plans usually fail in the middle, not on the last line. A plan can look fine at age 67 and strain at age 74 because Social Security is delayed, healthcare changes, Roth conversions raise income, or early market losses leave fewer dollars to recover.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/projection-flow.webp' },
+      caption:
+        'A projection turns account and income inputs into yearly balances, spending needs, taxes, healthcare costs, and possible stress points.',
+      alt: 'Teal income and account streams flow into stacked account buckets, then branch toward spending, tax, healthcare, and warning symbols across a retirement timeline.',
+    },
+    {
+      type: 'scenario',
+      name: 'The Patel household',
+      assumptions: [
+        { label: 'Spending need', value: '$90,000 a year in today\'s dollars' },
+        { label: 'Income floor', value: '$55,000 from Social Security and a pension' },
+        { label: 'Portfolio role', value: 'Cover the $35,000 annual gap, taxes, and one-time goals' },
+      ],
+      summary:
+        'Their projection is not mainly about the final balance. It is about whether the portfolio can cover a **$35,000** yearly gap plus taxes without creating a shortfall too early.',
+    },
+    { type: 'heading', text: 'Follow the cash gap first' },
+    {
+      type: 'prose',
+      md: 'The most important line is often the gap between spending and income. If income covers most spending, the portfolio has a lighter job. If income starts later or spending is front-loaded, the portfolio has to bridge more years.',
+    },
+    {
+      type: 'formula',
+      expression: 'portfolio gap = spending + taxes + penalties + contributions - income',
+      where: [
+        { symbol: 'spending', meaning: 'base spending, goals, healthcare, insurance premiums, and debt service' },
+        { symbol: 'income', meaning: 'wages, Social Security, pensions, annuities, and other income streams' },
+        { symbol: 'portfolio gap', meaning: 'the rough amount accounts must cover before the withdrawal-order details' },
+      ],
+      basis: 'nominal',
+      note: 'The app uses the full annual ledger, account order, taxable gains, RMDs, Roth conversions, and surplus investing. This quick formula is only a reading aid.',
+    },
+    { type: 'heading', text: 'Read the projection in layers' },
+    {
+      type: 'table',
+      caption: 'A practical order for reading a projection.',
+      columns: ['Layer', 'Question to ask', 'What to look for'],
+      rows: [
+        ['Inputs', 'Does the plan describe the household accurately?', 'Ages, spending, retirement dates, accounts, Social Security, and assumptions'],
+        ['Cash flow', 'Which years need portfolio withdrawals?', 'Income vs spending, taxes, healthcare, goals, and debt'],
+        ['Balances', 'Which account types are doing the work?', 'Taxable, traditional, Roth, HSA, cash, and whether one bucket empties early'],
+        ['Stress points', 'Where does the plan bend?', 'Shortfalls, depletion year, tax spikes, MAGI jumps, or sudden spending increases'],
+        ['Ending value', 'What is left at the end?', 'Ending investable assets, net worth, and after-tax estate for comparisons'],
+      ],
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden gives you both the summary view and the year-by-year detail. The summary tells you whether the plan lasts through the modeled horizon. The detail shows **why**. When the headline result surprises you, the table is usually where the explanation lives.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Treating the final balance as the only grade on the plan.',
+        'Ignoring whether numbers are shown in today\'s dollars or nominal dollars.',
+        'Missing one-time stress years because the long-term ending value still looks comfortable.',
+        'Comparing two plans without checking whether assumptions changed at the same time.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use this reading order on the **Results** screen first. Then use **Monte Carlo** to ask how the same plan behaves when returns and inflation vary, and **Scenarios** to compare deliberate changes side by side.',
+    },
+  ],
+}