@retiregolden/planner-ui 0.1.0

package/src/learn/content/taxable-brokerage-basis-and-capital-gains.ts

@@ -0,0 +1,99 @@
+/**
+ * "Taxable brokerage cost basis and capital gains" - an Accounts and Saving P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const taxableBrokerageBasisAndCapitalGainsArticle: LearningArticle = {
+  slug: 'taxable-brokerage-basis-and-capital-gains',
+  title: 'Taxable brokerage cost basis and capital gains',
+  description: 'What basis is and why it changes the tax on selling investments.',
+  category: 'accounts-saving',
+  tags: ['taxable brokerage', 'cost basis', 'capital gains', 'realized gains', 'tax lots'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.irs.gov/taxtopics/tc409',
+    'https://www.irs.gov/forms-pubs/about-publication-550',
+  ],
+  relatedArticles: [
+    'account-types-overview',
+    'ordinary-income-vs-capital-gains',
+    'withdrawal-order-basics',
+    'marginal-vs-effective-tax-rate',
+    'tax-loss-and-gain-harvesting',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/accounts', '/plan/:planId/strategy', '/plan/:planId/results'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'A taxable brokerage balance is not all taxed the same way. Part of the balance may be cost basis: money already taxed and invested. The rest may be unrealized gain. When you sell, the gain portion can become taxable capital gain.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Cost basis is the after-tax investment amount that usually comes back tax-free when shares are sold.',
+        'Capital gain is generally the sale value above basis, subject to capital-gain rules.',
+        'RetireGolden uses aggregate cost basis and realizes gains pro-rata when taxable investments are sold.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'If a taxable account is worth $100,000 and its cost basis is $70,000, the account has $30,000 of unrealized gain. Selling part of the account does not mean the whole sale is taxable. It usually means part basis and part gain leave the account together.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/taxable-basis-capital-gains.webp' },
+      caption:
+        'A taxable account contains both basis and gain; selling part of it can realize only the gain portion.',
+      alt: 'A taxable brokerage bucket is split into a basis layer and a gain layer, with a partial sale flowing through a capital-gain tax gate.',
+    },
+    {
+      type: 'formula',
+      expression: 'capital gain = sale proceeds - cost basis sold',
+      where: [
+        { symbol: 'sale proceeds', meaning: 'the amount received from selling the investment' },
+        { symbol: 'cost basis sold', meaning: 'the portion of original after-tax investment assigned to what was sold' },
+      ],
+      note: 'Real portfolios have tax lots and holding periods. RetireGolden uses aggregate basis as a planning simplification.',
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Harris household',
+      assumptions: [
+        { label: 'Taxable account value', value: '$300,000' },
+        { label: 'Aggregate cost basis', value: '$210,000' },
+        { label: 'Sale needed for spending', value: '$30,000' },
+      ],
+      summary:
+        'The account is 70% basis and 30% gain. A pro-rata $30,000 sale would realize about $9,000 of gain in the simplified model, not $30,000 of taxable income.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'The Accounts screen asks for taxable account cost basis. During projection, RetireGolden uses aggregate basis and realizes gains pro-rata as taxable holdings are sold. New taxable contributions add basis. This is useful for planning, but it does not replace brokerage-level tax-lot accounting.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Entering market value as basis when the account has embedded gains.',
+        'Leaving basis at zero, which can overstate taxable gains.',
+        'Assuming every taxable withdrawal is ordinary income.',
+        'Expecting RetireGolden to choose specific tax lots or optimize harvesting automatically.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Accounts** to enter taxable balance and cost basis. Then inspect **Results** for realized gains, MAGI, income tax, and withdrawal flows when taxable assets are sold.',
+    },
+  ],
+}

package/src/learn/content/three-big-questions-spending-time-risk.ts

@@ -0,0 +1,103 @@
+/**
+ * "The three big questions: spending, time, and risk" - a Start Here P0 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const threeBigQuestionsSpendingTimeRiskArticle: LearningArticle = {
+  slug: 'three-big-questions-spending-time-risk',
+  title: 'The three big questions: spending, time, and risk',
+  description: 'The handful of inputs that drive almost every retirement outcome.',
+  category: 'start-here',
+  tags: ['spending', 'retirement timing', 'risk', 'assumptions', 'planning basics'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'stable',
+  sourceUrls: [],
+  relatedArticles: [
+    'how-to-read-a-retirement-projection',
+    'todays-dollars-vs-future-dollars',
+    'what-retiregolden-models',
+    'how-assumptions-change-the-answer',
+    'sequence-of-returns-risk',
+  ],
+  relatedPlannerRoutes: [
+    '/plan/:planId/household',
+    '/plan/:planId/spending',
+    '/plan/:planId/assumptions',
+    '/plan/:planId/results',
+    '/plan/:planId/monte-carlo',
+  ],
+  currentYearSensitive: false,
+  priority: 'P0',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Most retirement planning details eventually point back to three questions: how much you spend, how long the plan must run, and how much uncertainty the plan can absorb. If those three inputs are fuzzy, every later result is fuzzier too.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Spending usually drives the size of the problem more than any single tax detail.',
+        'Time includes retirement age, claim age, planning age, and survivor years.',
+        'Risk is not one number. It includes markets, inflation, longevity, healthcare, taxes, and flexibility.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'A retirement plan is not mainly a prediction. It is a stress test of a lifestyle across time. Spending tells the plan what must be funded. Time tells the plan how many years the funding must last. Risk tells the plan how much bad luck could arrive before the answer breaks.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/three-big-questions.webp' },
+      caption:
+        'Spending, time, and risk form the core triangle underneath the rest of the retirement plan.',
+      alt: 'Three large illustrated pillars for spending, time, and risk support a retirement path with account, tax, and healthcare icons above it.',
+    },
+    {
+      type: 'table',
+      caption: 'The three questions underneath most retirement choices.',
+      columns: ['Question', 'What it controls', 'Where people get tripped up'],
+      rows: [
+        ['Spending', 'How much the plan must fund each year', 'Using a current budget that ignores taxes, healthcare, repairs, travel, or one-time goals'],
+        ['Time', 'How many years income, withdrawals, inflation, and survivor rules run', 'Planning to life expectancy instead of a prudent planning age'],
+        ['Risk', 'How much uncertainty the plan can absorb', 'Looking at a single result and missing weak paths'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Nolan household',
+      assumptions: [
+        { label: 'Spending', value: '$95,000 per year before healthcare surprises' },
+        { label: 'Time', value: 'Retire at 63, plan through one spouse reaching 96' },
+        { label: 'Risk', value: 'Moderate portfolio with 82% Monte Carlo success in the first pass' },
+      ],
+      summary:
+        'Before debating Roth conversions or claim timing, the Nolans need to know whether **$95,000**, a 33-year horizon, and 82% success are a workable starting point.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden lets you edit these three questions directly. Spending lives in **Spending**. Time lives across **Household**, **Social Security**, and account strategy choices. Risk shows up in **Assumptions**, **Monte Carlo**, **Scenarios**, and **Optimize**.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Treating the first plan as the answer instead of a baseline.',
+        'Fine-tuning tax strategy before the spending number is credible.',
+        'Using one planning age for a couple and ignoring survivor years.',
+        'Assuming a good median result means the plan is resilient.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Start with **Household**, **Spending**, and **Accounts**. Then read **Results** for the baseline, **Monte Carlo** for risk, and **Scenarios** for what changes the answer most.',
+    },
+  ],
+}

package/src/learn/content/tips-ladders.ts

@@ -0,0 +1,92 @@
+import type { LearningArticle } from '../learningRegistry'
+
+export const tipsLaddersArticle: LearningArticle = {
+  slug: 'tips-ladders',
+  title: 'TIPS ladders: a guaranteed real income floor',
+  description:
+    'How a ladder of inflation-protected Treasuries turns a lump sum into guaranteed inflation-adjusted income — and how RetireGolden prices, taxes, and stress-tests one inside your plan.',
+  category: 'risk-uncertainty',
+  tags: ['tips', 'income floor', 'inflation', 'bonds', 'safety-first', 'ladder', 'real yield'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-07-08',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://home.treasury.gov/resource-center/data-chart-center/interest-rates',
+    'https://www.treasurydirect.gov/marketable-securities/tips/',
+    'https://www.irs.gov/publications/p550',
+    'https://www.bogleheads.org/wiki/TIPS_ladder',
+  ],
+  relatedArticles: ['social-security-bridge', 'funded-ratio', 'inflation-risk', 'pensions-and-annuities', 'cola-and-inflation-protection'],
+  relatedPlannerRoutes: ['/plan/:planId/income-floor', '/plan/:planId/results'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  featured: false,
+  blocks: [
+    {
+      type: 'prose',
+      md: 'A **TIPS ladder** is a set of Treasury Inflation-Protected Securities chosen so that one bond matures each year, and each maturity (plus the interest the others pay that year) delivers the same amount of **real** — inflation-adjusted — income. Buy the ladder once, and the income arrives on schedule no matter what stocks, rates, or inflation do. It is the closest thing an individual can buy to a DIY inflation-indexed pension, with no insurance company involved.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        '**Guaranteed and inflation-proof**: both principal and coupons index to CPI, and the ladder is backed by the U.S. Treasury — the two risks a bond ladder usually leaves open (inflation and default) are both covered.',
+        '**Priced by real yields**: at a ~2.7% long real yield, a 30-year ladder costs roughly 20½ times its annual payout — about a **4.8–4.9% real withdrawal rate**, comfortably above the ~4% rule of thumb for portfolios. When real yields fall, the same income costs more.',
+        '**The trade**: the money is committed. A ladder rung spent this year cannot also compound in stocks; the ladder ends when its last rung matures (no longevity pooling like an annuity).',
+        '**Tax texture matters**: TIPS interest and the annual inflation adjustment are **federally taxable but exempt from state income tax** — and the inflation adjustment is taxed before you see the cash ("phantom income"), which is why many holders keep TIPS in tax-advantaged accounts. RetireGolden models the taxable-brokerage version, where the state exemption and phantom income actually bite.',
+      ],
+    },
+    { type: 'heading', text: 'How RetireGolden builds one' },
+    {
+      type: 'prose',
+      md: 'On the **Income floor** page you give a target real income, a first payout year, and a last payout year. RetireGolden solves the rung sizes back-to-front — the final year is funded by its maturing bond alone; earlier years by their maturing bond plus the coupons of every rung still outstanding — and prices each rung on an embedded Treasury real-yield curve (the "curve as of" date is shown next to every quote).\n\nThe cost you see is a planning-grade quote, not a brokerage order: coupons pay annually, rungs are par bonds at the interpolated curve yield, and there is no CUSIP-level lot rounding. An optional live-price mode can fetch actual Treasury (FedInvest) closing prices for comparison — it never runs without your click, and the plan itself always works offline on the embedded curve.',
+    },
+    {
+      type: 'formula',
+      expression: 'ladder cost ≈ annual real income × Σ 1 ÷ (1 + r)ᵗ  for t = 1…years',
+      where: [
+        { symbol: 'r', meaning: 'the real (above-inflation) Treasury yield at each maturity' },
+        { symbol: 't', meaning: 'years until each rung matures' },
+      ],
+      basis: 'today',
+      note: 'With a flat curve this is exactly the level-annuity present-value factor; the app uses the full curve shape.',
+    },
+    { type: 'heading', text: 'What happens inside your plan' },
+    {
+      type: 'prose',
+      md: 'The ladder is not a side calculation — its cash flows live inside the same yearly ledger as everything else. The purchase leaves your chosen cash or brokerage account in the purchase year (realizing capital gains pro-rata if it sells appreciated holdings). Each year after that, coupons and any maturing principal arrive as income; the taxable slice (coupons plus that year\'s inflation accretion) flows through federal tax, the Social Security taxability formula, IRMAA, and ACA credits like any other ordinary income — while the state return excludes it. The unmatured rungs ride in your net worth as a dedicated asset the withdrawal engine never raids.',
+    },
+    {
+      type: 'callout',
+      tone: 'note',
+      md: 'RetireGolden models ladders held in **taxable** accounts. TIPS inside an IRA are just part of that account\'s balance — model those with the account\'s own allocation instead. The phantom-income and state-exemption mechanics only exist on the taxable side.',
+    },
+    { type: 'heading', text: 'Ladder, annuity, or portfolio?' },
+    {
+      type: 'table',
+      caption: 'Three ways to fund essential spending',
+      columns: ['', 'TIPS ladder', 'Income annuity (SPIA)', 'Stock/bond portfolio'],
+      rows: [
+        ['Inflation protection', 'Exact (CPI-indexed)', 'Only if you buy a COLA rider', 'Expected, not guaranteed'],
+        ['Longevity protection', 'Ends at the last rung', 'Pays for life', 'Depends on markets'],
+        ['What heirs get', 'Unmatured rungs', 'Usually nothing (life-only)', 'Whatever remains'],
+        ['Guarantee', 'U.S. Treasury', 'Insurer (state guaranty funds)', 'None'],
+        ['Liquidity', 'Sellable, at market prices', 'Irreversible', 'Full'],
+      ],
+    },
+    {
+      type: 'prose',
+      md: 'These are complements, not rivals: a common safety-first shape is a ladder covering the years to 85, a deferred annuity or delayed Social Security covering beyond, and the portfolio funding everything discretionary. The [funded ratio](/learn/funded-ratio) is the lens for deciding how much floor to lock in.',
+    },
+    { type: 'heading', text: 'Honest boundaries' },
+    {
+      type: 'list',
+      items: [
+        '**Planning-grade pricing**: annual coupons, par-bond rungs, no auction/secondary spread. Real quotes (tipsladder.com, your brokerage) will differ by small amounts.',
+        '**Curve staleness**: the embedded curve refreshes with the annual parameter packs; the "curve as of" date is always shown. Real yields move — re-quote before you buy.',
+        '**OID precision**: the phantom-income model (accretion taxed in the year it accrues) is the standard planning simplification of TIPS OID rules, not a Form 1099-OID reproduction.',
+      ],
+    },
+  ],
+}

package/src/learn/content/todays-dollars-vs-future-dollars.ts

@@ -0,0 +1,107 @@
+/**
+ * "Today's dollars vs future dollars" — a Start Here P0 article.
+ *
+ * Evergreen and concept-first: it uses a single illustrative ~3% inflation
+ * example (date-stamped as illustrative, not a rule), so it carries no source or
+ * annual-review obligation. It doubles as the showcase that exercises every
+ * rich content block: figure, formula, scenario, and table.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const todaysDollarsArticle: LearningArticle = {
+  slug: 'todays-dollars-vs-future-dollars',
+  title: "Today's dollars vs future dollars",
+  description: 'Why the same dollar amount means different things over time, and how to read it in your plan.',
+  category: 'start-here',
+  tags: ['inflation', 'real dollars', 'nominal', 'purchasing power', 'today’s dollars'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-19',
+  reviewCadence: 'stable',
+  sourceUrls: [],
+  relatedArticles: ['about-retiregolden', 'how-assumptions-change-the-answer', 'inflation-risk'],
+  relatedPlannerRoutes: ['/plan/:planId/assumptions', '/plan/:planId/results'],
+  currentYearSensitive: false,
+  blocks: [
+    {
+      type: 'prose',
+      md: 'A dollar in 30 years will not buy what a dollar buys today. When a plan shows a big future number, the first question to ask is: **is that in today’s dollars, or future dollars?** The answer changes what the number really means.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        '**Future (nominal) dollars** are the actual dollar amounts in a future year — bigger, but each one buys less.',
+        "**Today's dollars** (also called **real dollars**) strip out inflation so you can compare to prices you know now.",
+        'Neither is “right.” What matters is knowing which one you are looking at.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Inflation is the slow rise in prices over time. As prices rise, each dollar buys a little less. Over a few years the effect is small. Over a multi-decade retirement, it is large.\n\nThe chart below shows what a fixed $50,000 would buy over time if prices rise about 3% a year. The dollar amount on the bill never changes — but its buying power keeps shrinking.',
+    },
+    {
+      type: 'figure',
+      chartId: 'purchasing-power',
+      caption: 'Buying power of a fixed $50,000 over 30 years.',
+      alt: 'A line falling from $50,000 today to roughly $20,600 of buying power after 30 years, because prices rise about 3% a year.',
+      sourceNote: 'Illustrative, assuming about 3% inflation a year. Your plan uses your own inflation assumption.',
+    },
+    { type: 'heading', text: 'A quick formula' },
+    {
+      type: 'prose',
+      md: 'To convert a future amount back into today’s dollars, divide it by inflation compounded over the years between now and then:',
+    },
+    {
+      type: 'formula',
+      expression: "today's dollars = future dollars ÷ (1 + inflation)^years",
+      where: [
+        { symbol: 'future dollars', meaning: 'the nominal amount in some future year' },
+        { symbol: 'inflation', meaning: 'the average yearly price increase, e.g. 0.03 for 3%' },
+        { symbol: 'years', meaning: 'the number of years from now until that future year' },
+      ],
+      note: 'This simple version assumes one steady inflation rate. Real inflation varies year to year, which is why the app lets you set the assumption and re-runs the math each year.',
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Rivera household',
+      assumptions: [
+        { label: 'Spending need', value: '$50,000 a year in today’s dollars' },
+        { label: 'Years until retirement', value: '20 years' },
+        { label: 'Assumed inflation', value: 'about 3% a year' },
+      ],
+      summary:
+        'In 20 years, covering the **same** lifestyle takes about **$90,000** of future dollars — not because the Riveras live larger, but because each dollar buys less.',
+    },
+    {
+      type: 'prose',
+      md: 'So a plan that shows “$90,000 of spending” in year 20 may describe the exact same life as “$50,000 today.” Seeing both framings keeps you from over- or under-reacting to a big number.',
+    },
+    {
+      type: 'table',
+      caption: 'The same retirement, shown two ways.',
+      columns: ['Framing', 'What the number is', 'Good for'],
+      rows: [
+        ["Today's dollars", 'Inflation removed, comparable to prices now', 'Judging whether a plan supports your lifestyle'],
+        ['Future (nominal) dollars', 'Actual dollar amounts in each future year', 'Matching account statements and tax brackets'],
+      ],
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'You set the inflation assumption on the **Assumptions** screen, and the **Results** screen can show key figures in today’s dollars so they stay comparable to prices you recognize. When you read any projection, check which framing it uses before drawing a conclusion.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Treating a large future balance as “rich” without converting it to today’s dollars.',
+        'Comparing a today’s-dollars number against a future-dollars number — an apples-to-oranges mix.',
+        'Assuming inflation is fixed; it is an assumption you can and should test.',
+      ],
+    },
+  ],
+}

package/src/learn/content/traditional-vs-roth-contributions.ts

@@ -0,0 +1,113 @@
+/**
+ * "Traditional vs Roth contributions" - an Accounts and Saving P0 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const traditionalVsRothContributionsArticle: LearningArticle = {
+  slug: 'traditional-vs-roth-contributions',
+  title: 'Traditional vs Roth contributions',
+  description: 'Pay tax now or later, and how to think about the trade-off.',
+  category: 'accounts-saving',
+  tags: ['traditional', 'roth', 'contributions', 'tax timing', '401k', 'ira'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.irs.gov/retirement-plans/plan-participant-employee/retirement-topics-contributions',
+    'https://www.irs.gov/retirement-plans/401k-plans',
+    'https://www.irs.gov/retirement-plans/roth-iras',
+    'https://www.irs.gov/retirement-plans/retirement-plans-faqs-regarding-iras',
+  ],
+  relatedArticles: [
+    'account-types-overview',
+    'roth-conversion-basics',
+    'marginal-vs-effective-tax-rate',
+    'filling-a-tax-bracket-with-roth-conversions',
+    'withdrawal-order-basics',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/accounts', '/plan/:planId/assumptions', '/plan/:planId/results'],
+  currentYearSensitive: true,
+  priority: 'P0',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'A traditional contribution and a Roth contribution are two different tax-timing choices. Traditional usually tries to reduce taxable income now. Roth usually accepts tax now in exchange for more tax-free flexibility later, if the rules for qualified withdrawals are met.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Traditional is often attractive when today\'s marginal tax rate is high compared with the rate you expect in retirement.',
+        'Roth is often attractive when today\'s rate is low, future rates may be higher, or tax-free flexibility is valuable.',
+        'The best answer can change by year, especially around retirement, Social Security, Medicare, RMDs, and survivor years.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Traditional contributions usually move taxable income from today into the future. Roth contributions usually leave today\'s taxable income alone, but future qualified Roth withdrawals may avoid tax. The cleanest comparison asks: would I rather pay tax at today\'s marginal rate, or at the future rate that applies when I withdraw?',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/traditional-vs-roth-contributions.webp' },
+      caption:
+        'Traditional and Roth contributions are two tax-timing paths: tax later versus tax now.',
+      alt: 'A savings dollar reaches a fork. One path enters a traditional account before a future tax gate, and the other passes a current tax gate before reaching a Roth account.',
+    },
+    {
+      type: 'formula',
+      expression: 'better choice = lower lifetime tax cost, not lower tax this year',
+      where: [
+        { symbol: 'traditional', meaning: 'usually lowers taxable income now and creates taxable withdrawals later' },
+        { symbol: 'Roth', meaning: 'usually pays tax now and can create tax-free qualified withdrawals later' },
+      ],
+      note: 'This is a planning lens, not a universal rule. Eligibility, employer plan rules, cash flow, and current law all matter.',
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Moreno household',
+      assumptions: [
+        { label: 'Working years', value: '$180,000 household wages while both spouses work' },
+        { label: 'Contribution choice', value: '$12,000 pre-tax contribution saves current tax; Roth contribution does not' },
+        { label: 'First retirement years', value: 'Lower taxable income creates room to convert some pre-tax dollars later' },
+      ],
+      summary:
+        'The pre-tax contribution can help most in the high-wage year. Later, a planned conversion can move dollars to Roth when the Morenos have more bracket room, so the answer can change by phase.',
+    },
+    { type: 'heading', text: 'Traditional vs Roth in a plan' },
+    {
+      type: 'table',
+      caption: 'The trade-off is mostly about tax timing.',
+      columns: ['Feature', 'Traditional contribution', 'Roth contribution'],
+      rows: [
+        ['Current taxable income', 'Often lower when the contribution is deductible or pre-tax', 'Usually unchanged by the contribution'],
+        ['Future withdrawals', 'Often ordinary income', 'Qualified withdrawals may be tax-free'],
+        ['RMD pressure', 'Traditional balances can create future RMDs', 'Roth IRAs do not create lifetime RMDs for the original owner'],
+        ['Flexibility', 'Can help manage taxes now', 'Can help manage taxes later'],
+      ],
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden applies annual contribution inputs while the account owner has wages and caps modeled contributions by the parameter pack limits. Traditional and HSA contributions reduce taxable income in the projection; Roth contributions add to Roth basis but do not create the same current-year deduction in the ledger.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Choosing Roth because "tax-free" sounds automatically better.',
+        'Choosing traditional because this year\'s tax bill is the only number being watched.',
+        'Comparing contribution amounts without considering whether the tax savings are also invested.',
+        'Ignoring survivor years, when a surviving spouse may file under a smaller bracket structure.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Enter annual traditional and Roth contributions in **Accounts**. Then compare plan versions in **Scenarios**: one with more traditional saving, one with more Roth saving, and one with traditional saving plus later Roth conversions.',
+    },
+  ],
+}

package/src/learn/content/troubleshooting-surprising-results.ts

@@ -0,0 +1,105 @@
+/**
+ * "Troubleshooting surprising results" - a Using RetireGolden P2 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const troubleshootingSurprisingResultsArticle: LearningArticle = {
+  slug: 'troubleshooting-surprising-results',
+  title: 'Troubleshooting surprising results',
+  description: 'Common reasons a projection looks wrong and how to track it down.',
+  category: 'using-retiregolden',
+  tags: ['troubleshooting', 'results', 'inputs', 'projection', 'retiregolden'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'stable',
+  sourceUrls: [],
+  relatedArticles: [
+    'reading-the-results-page',
+    'how-assumptions-change-the-answer',
+    'using-assumptions-and-provenance',
+    'reports-csv-exports-and-sharing',
+    'what-retiregolden-models',
+  ],
+  relatedPlannerRoutes: [
+    '/plan/:planId/results',
+    '/plan/:planId/assumptions',
+    '/plan/:planId/accounts',
+    '/plan/:planId/strategy',
+    '/plan/:planId/report',
+  ],
+  currentYearSensitive: false,
+  priority: 'P2',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'A surprising result is usually a clue, not a verdict. The fastest fix is to trace the result back through the ledger: inputs, assumptions, taxes, withdrawals, and warnings.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Start with modeling notes and the first surprising year, not the final estate number.',
+        'Check account types, owners, cost basis, retirement ages, and spending before tuning strategy.',
+        'Use the CSV when the screen summary is not enough to explain the annual ledger.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Projection errors often come from a small input with a large ripple: an account marked traditional instead of Roth, a retirement age that starts wages too early or too late, a missing cost basis, an aggressive inflation assumption, or a strategy that creates MAGI pressure. Troubleshooting works best when you find the first year the output looks strange.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/troubleshooting-surprising-results.webp' },
+      caption:
+        'Follow the first surprising year back to the inputs, assumptions, and rules that created it.',
+      alt: 'A magnifying glass inspects a retirement ledger, tracing a highlighted year back to account, tax, spending, and assumption controls.',
+    },
+    {
+      type: 'table',
+      caption: 'Common symptoms and first checks.',
+      columns: ['Symptom', 'First check', 'Likely screen'],
+      rows: [
+        ['Portfolio depletes earlier than expected', 'Spending, retirement age, one-time goals, and return assumptions', 'Spending, Household, Assumptions'],
+        ['Taxes spike in one year', 'Roth conversions, RMDs, capital gains, or one-time income', 'Strategy, Results'],
+        ['MAGI looks too high', 'Conversions, taxable gains, Social Security taxation, and recent MAGI seed', 'Results, Assumptions'],
+        ['Healthcare costs jump', 'Age 65 transition, ACA credit setting, IRMAA lookback, healthcare inflation', 'Spending, Assumptions, Results'],
+        ['A report or CSV does not match the screen view', 'Nominal vs today-dollar display', 'Results, Report'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Adams household',
+      assumptions: [
+        { label: 'Surprise', value: 'Taxes jump sharply at age 73' },
+        { label: 'First ledger clue', value: '$48,000 RMD begins in the same year' },
+        { label: 'Next checks', value: '$600,000 traditional balance, conversion strategy, QCD setting, and filing status' },
+      ],
+      summary:
+        'The tax spike is no longer mysterious once the table shows a **$48,000** RMD. The next step is checking why the traditional balance stayed that high.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'The **Results** page combines charts, modeling notes, and a year-by-year table. The **Download CSV** button gives the nominal ledger for deeper inspection. The **Report** route gives a printable summary of inputs, assumptions, headline results, warnings, and the appendix.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Fixing the strategy before checking whether the inputs are wrong.',
+        'Reading today-dollar screen values beside nominal CSV values without noticing the basis.',
+        'Ignoring model warnings because the headline number looks fine.',
+        'Comparing two plans that use different assumptions and treating the strategy as the only change.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Start in **Results**, find the first surprising year, and then move to the screen that owns the line item: **Accounts**, **Spending**, **Strategy**, **Assumptions**, or **Social Security**. Export the CSV when you need to audit the row outside the app.',
+    },
+  ],
+}