@retiregolden/planner-ui 0.1.0

package/src/learn/content/rsus-and-espp.ts

@@ -0,0 +1,101 @@
+/**
+ * "RSUs and ESPP in retirement planning" - an Accounts and Saving P2 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const rsusAndEsppArticle: LearningArticle = {
+  slug: 'rsus-and-espp',
+  title: 'RSUs and ESPP in retirement planning',
+  description: 'How equity compensation translates into retirement savings.',
+  category: 'accounts-saving',
+  tags: ['rsu', 'espp', 'equity compensation', 'vesting', 'cost basis', 'concentration risk'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.irs.gov/taxtopics/tc427',
+    'https://www.irs.gov/forms-pubs/about-publication-525',
+  ],
+  relatedArticles: [
+    'account-types-overview',
+    'taxable-brokerage-basis-and-capital-gains',
+    'ordinary-income-vs-capital-gains',
+    'tax-loss-and-gain-harvesting',
+    'fees-expense-ratios-and-compounding-drag',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/accounts', '/plan/:planId/strategy', '/plan/:planId/results'],
+  currentYearSensitive: true,
+  priority: 'P2',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Equity compensation can become a powerful retirement asset, but it is rarely as simple as a plain brokerage balance. Vesting, taxes, cost basis, concentration risk, and selling decisions all affect how much of the award really supports the plan.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Restricted stock units (RSUs) and employee stock purchase plan (ESPP) shares can turn compensation into investable assets.',
+        'The retirement-plan value depends on what is already vested, what may vest later, and what tax basis the shares carry.',
+        'RetireGolden models equity comp as a taxable-like account with an availability date, not as payroll, withholding, or grant-level tax accounting.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Once company shares are vested and available, they can often be sold like taxable investments. Before that point, they may be promised but not spendable. A good plan distinguishes confirmed assets from future compensation, and it asks whether too much of the household balance sheet depends on one employer or one stock.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/rsus-espp.webp' },
+      caption:
+        'Equity compensation moves from future vesting to taxable-like investable wealth only after it becomes available.',
+      alt: 'Company-share tiles move along a vesting path into an available investment bucket, with a caution badge for concentration risk beside the path.',
+    },
+    {
+      type: 'table',
+      caption: 'Planning lens for equity compensation.',
+      columns: ['Question', 'Why it matters', 'RetireGolden input'],
+      rows: [
+        ['What is already available?', 'Available shares can be sold to fund the plan', 'Balance and cost basis'],
+        ['What vests later?', 'Unvested value may not be spendable yet', 'Vesting mode and vest date'],
+        ['What is the tax basis?', 'Basis affects capital gains when shares are sold', 'Aggregate cost basis'],
+        ['How concentrated is the position?', 'Employer stock can add job and portfolio risk at the same time', 'Return and scenario assumptions'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Brooks household',
+      assumptions: [
+        { label: 'Equity comp', value: '$120,000 expected to vest near retirement' },
+        { label: 'Bridge need', value: '$55,000 of spending before pension and Social Security begin' },
+        { label: 'Risk check', value: 'A 40% stock decline would cut the vesting value to about $72,000' },
+      ],
+      summary:
+        'At $120,000, the award covers the $55,000 bridge with room left over. At $72,000, it still covers one year but leaves far less cushion for taxes, delays, or another weak market year.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden includes an **Equity comp** account type on **Accounts**. It stores balance, aggregate cost basis, annual contribution, vesting mode, and vest date. When cliff vesting is selected, the balance is unavailable for spending before the vest date. After it is available, withdrawals realize gains pro-rata like a taxable account.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Counting unvested awards as fully spendable today.',
+        'Leaving cost basis blank when shares have basis that affects taxable gains.',
+        'Ignoring the risk of holding a large employer-stock position near retirement.',
+        'Expecting the planner to model grant-by-grant withholding, disqualifying ESPP dispositions, or tax-lot selection.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Accounts** to add equity comp and its vesting assumption. Use **Scenarios** to test a lower stock value or delayed availability, then use **Results** to inspect withdrawals, gains, MAGI, and taxes.',
+    },
+  ],
+}

package/src/learn/content/rule-of-55-and-72t.ts

@@ -0,0 +1,107 @@
+/**
+ * "Rule of 55 and 72(t) basics" - a Withdrawals and Roth P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const ruleOf55And72tArticle: LearningArticle = {
+  slug: 'rule-of-55-and-72t',
+  title: 'Rule of 55 and 72(t) basics',
+  description: 'Penalty-free ways to reach retirement money before age 59 1/2.',
+  category: 'withdrawals-roth',
+  tags: ['rule of 55', '72(t)', 'sepp', 'early withdrawals', 'traditional ira', '401(k)', 'penalty'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.irs.gov/retirement-plans/plan-participant-employee/retirement-topics-exceptions-to-tax-on-early-distributions',
+    'https://www.irs.gov/retirement-plans/substantially-equal-periodic-payments',
+    'https://www.irs.gov/publications/p590b',
+  ],
+  relatedArticles: [
+    'withdrawal-order-basics',
+    'roth-conversion-basics',
+    'paying-conversion-taxes-taxable-vs-ira',
+    'inherited-ira-10-year-rule',
+    'rmds-required-minimum-distributions',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/accounts', '/plan/:planId/strategy', '/plan/:planId/results'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'The Rule of 55 and 72(t) substantially equal periodic payments are two ways early retirees may reach retirement money before the usual 59 1/2 penalty age. They can remove the extra penalty, but they do not make taxable retirement money tax-free.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'The Rule of 55 generally applies to an employer plan tied to the job you leave at 55 or later.',
+        'A 72(t) SEPP series can apply to IRA or plan money, but the payment schedule must be respected.',
+        'Penalty-free does not mean tax-free. Traditional-account distributions are still usually ordinary income.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Early retirement often creates a bridge problem. You may have enough money on paper, but much of it may sit in traditional retirement accounts. Taking that money too early can create income tax plus an extra 10% early-distribution tax unless an exception applies.\n\nThe Rule of 55 is a narrow employer-plan exception. A 72(t) SEPP is a more formal payment series. Both are planning tools with strings attached. They can help bridge a gap, but they should be compared against cash, taxable accounts, Roth contribution basis, conversion ladders, and delaying spending.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/rule-of-55-72t.webp' },
+      caption:
+        'Early-access rules are bridges across the pre-59 1/2 gap, but each bridge has its own gate and commitment.',
+      alt: 'A retirement timeline before age 60 shows two gated bridges from traditional accounts to spending: one employer-plan bridge and one scheduled-payment bridge.',
+    },
+    {
+      type: 'table',
+      caption: 'Two penalty exceptions are often confused.',
+      columns: ['Path', 'What it can do', 'Main caution'],
+      rows: [
+        ['Rule of 55', 'May waive the 10% penalty for an employer plan after separating from service at 55 or later', 'Usually does not apply to IRAs or old plans from earlier jobs'],
+        ['72(t) SEPP', 'May create penalty-free periodic payments before 59 1/2', 'Changing the series too early can create retroactive penalties'],
+        ['Roth basis', 'Direct Roth contributions may be accessible without tax or penalty', 'Conversions and earnings have their own ordering and timing rules'],
+        ['Cash or taxable', 'Can fund the bridge without retirement-account penalty rules', 'May reduce liquidity or realize capital gains'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Ortiz household',
+      assumptions: [
+        { label: 'Retirement age', value: 'One spouse retires at 56' },
+        { label: 'Largest account', value: '$480,000 employer plan from the job just left' },
+        { label: 'Bridge need', value: '$40,000 a year for four years before the normal penalty age' },
+      ],
+      summary:
+        'The bridge need is about **$160,000** before taxes. Keeping the employer-plan bucket available may matter more than rolling everything into an IRA right away.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden approximates the 59 1/2 penalty boundary as age 60. It can waive the traditional early-withdrawal penalty for an employer plan when the owner separates at age 55 or later, using the person\'s retirement age as the separation-age proxy. It can also model 72(t) SEPP distributions on non-inherited traditional accounts, using either an RMD-style method or an amortization-style method.',
+    },
+    {
+      type: 'callout',
+      tone: 'warn',
+      md: 'Model note: RetireGolden assumes the 72(t) series is honored. It does not model busting a SEPP schedule, retroactive penalties, plan-specific distribution limits, or every IRS exception.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Rolling an employer plan to an IRA without checking whether the Rule of 55 would have helped.',
+        'Treating 72(t) as flexible spending money instead of a payment commitment.',
+        'Forgetting that traditional distributions still raise taxable income and MAGI.',
+        'Assuming every early-withdrawal exception is modeled in RetireGolden.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Household** for retirement ages, **Accounts** to mark traditional accounts as IRA or employer plan and add 72(t) settings, and **Results** to inspect penalties, withdrawals, tax, and MAGI year by year.',
+    },
+  ],
+}

package/src/learn/content/savings-rate-biggest-lever.ts

@@ -0,0 +1,66 @@
+import type { LearningArticle } from '../learningRegistry'
+
+export const savingsRateBiggestLeverArticle: LearningArticle = {
+  slug: 'savings-rate-biggest-lever',
+  title: 'Your savings rate is the biggest lever',
+  description: 'Why the percentage of income you save determines your path to financial freedom.',
+  category: 'early-investing-fire',
+  tags: ['savings rate', 'accumulation', 'leverage', 'fire math'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-29',
+  reviewCadence: 'stable',
+  sourceUrls: [
+    'https://www.mrmoneymustache.com/2012/01/13/the-shockingly-simple-math-behind-early-retirement/',
+  ],
+  relatedArticles: [
+    'what-is-fire',
+    'fi-number-and-four-percent-rule',
+    'how-to-model-accumulation',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/results', '/plan/:planId/spending'],
+  currentYearSensitive: false,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Your **savings rate** is the single most dominant variable in early retirement planning. It determines two things simultaneously: how much money you are adding to your portfolio, and how much money you need to live on.',
+    },
+    { type: 'heading', text: 'Three key takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Savings rate is calculated as: (Employee Contributions + Employer Match + Surplus Invested) ÷ Gross Income.',
+        'Increasing your savings rate has a dual effect: it speeds up growth and shrinks your retirement budget.',
+        'At a 50% savings rate, you buy one year of freedom for every year you work.',
+      ],
+    },
+    { type: 'heading', text: 'Savings rate vs. years to FI' },
+    {
+      type: 'table',
+      caption: 'Years to achieve financial independence assuming a 5% real return and 4% safe withdrawal rate.',
+      columns: ['Savings rate', 'Years to FI', 'Working years per year of retirement funded'],
+      rows: [
+        ['10%', '51 years', '9 years of work funds 1 year of retirement'],
+        ['20%', '37 years', '4 years of work funds 1 year of retirement'],
+        ['30%', '28 years', '2.3 years of work funds 1 year of retirement'],
+        ['50%', '17 years', '1 year of work funds 1 year of retirement'],
+        ['70%', '8.5 years', '0.4 years of work funds 1 year of retirement'],
+      ],
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Mixing take-home-pay savings rates with gross-income savings rates without labeling which one you mean.',
+        'Counting the same dollar twice, such as counting a brokerage contribution and the surplus that funded it.',
+        'Forgetting that a higher savings rate also usually means a smaller spending target.',
+      ],
+    },
+    { type: 'heading', text: 'Where this shows up in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden calculates your annual savings rate on the Results page. You can see the **Average Savings Rate** KPI, representing the average percentage of gross wages saved before your target retirement age.',
+    },
+  ],
+}

package/src/learn/content/seed-your-plan-from-your-tax-return.ts

@@ -0,0 +1,93 @@
+/**
+ * "Seed your plan from your tax return" — Using RetireGolden article for the
+ * 1040 guided seed flow (onboarding-import-and-migration step 6).
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const seedYourPlanFromYourTaxReturnArticle: LearningArticle = {
+  slug: 'seed-your-plan-from-your-tax-return',
+  title: 'Seed your plan from your tax return',
+  description: 'A dozen lines off last year\'s Form 1040 give a new plan its income, filing, and bracket context in minutes.',
+  category: 'using-retiregolden',
+  tags: ['1040', 'tax return', 'import', 'onboarding', 'agi', 'magi'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-07-08',
+  reviewCadence: 'annual',
+  sourceUrls: ['https://www.irs.gov/forms-pubs/about-form-1040'],
+  relatedArticles: [
+    'moving-to-retiregolden',
+    'agi-magi-and-taxable-income',
+    'assumption-recent-magi',
+    'irmaa-two-year-lookback',
+    'how-social-security-is-taxed',
+  ],
+  relatedPlannerRoutes: ['/import', '/plan/:planId/income', '/plan/:planId/accounts'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'The single richest snapshot of your financial life is a document you already have: last year\'s Form 1040. The **start from your tax return** path in the Import & migrate wizard asks for about a dozen line values — typed by you, no PDF upload, nothing leaving your device — and turns them into a draft plan with the income picture and tax context already in place.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'You type the values yourself off the printed lines — guided entry, not document scanning.',
+        'The flow prefills income streams, filing status, state, and the MAGI that Medicare\'s IRMAA surcharge looks back at.',
+        'Everything prefigured is labeled "from your 1040" on the review checklist and stays editable.',
+        'A tax return shows income, not spending or balances — the checklist tells you exactly what to add next.',
+      ],
+    },
+    { type: 'heading', text: 'What each line becomes' },
+    {
+      type: 'table',
+      caption: 'How the 1040 lines map into the draft plan.',
+      columns: ['1040 line', 'What it becomes', 'Watch for'],
+      rows: [
+        ['Header — filing status, state', 'Household filing status and state of residence', 'Move planned? Set it on the Household screen'],
+        ['1a — wages', 'A wages income stream until retirement', 'Joint filers: split wages between spouses afterward'],
+        ['2b + 3a/3b — interest & dividends', 'An estimated taxable account sized so those yields make sense', 'An estimate — replace with your real balance and basis'],
+        ['4b — IRA distributions', 'A pointer to add your IRA/401(k) balances', 'Withdrawals are modeled from balances, not history'],
+        ['5b — pensions & annuities', 'A pension paying that amount monthly', 'Check the COLA and survivor percentage'],
+        ['6a — Social Security benefits', 'A benefit basis, assuming a claim at 67', 'Claimed earlier or later? Fix the claim age'],
+        ['7 — capital gain or loss', 'Guidance only (a loss points at the carryforward field)', 'Last year\'s gains are not projected forward'],
+        ['11 + 2a — AGI + tax-exempt interest', 'The recent-MAGI assumption for IRMAA\'s two-year lookback', 'This is why early-year Medicare premiums look right'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Okafor household',
+      assumptions: [
+        { label: 'Return in hand', value: 'Joint return: $12,500 of interest + dividends, $40,000 of IRA distributions, $36,000 of Social Security, $110,000 AGI' },
+        { label: 'Ten minutes of typing', value: 'Draft plan with pension-free income streams, an estimated ~$500,000 taxable account, and MAGI context set' },
+        { label: 'Checklist follow-ups', value: 'Add the real IRA balances, correct the estimated taxable balance, set the real Social Security claim ages' },
+      ],
+      summary:
+        'The 1040 seeds the shape of the plan in one sitting; the checklist turns "what do I enter next?" into three concrete follow-ups.',
+    },
+    { type: 'heading', text: 'Why the estimates are estimates' },
+    {
+      type: 'prose',
+      md: 'A tax return reports income *from* assets, not the assets themselves. The wizard sizes the estimated taxable account by asking what balance would plausibly produce your interest and dividends at a typical yield — useful scaffolding, but the real number is on your statements. The same honesty applies to Social Security: line 6a shows what you received, so the wizard assumes a full-retirement-age claim and tells you to correct the claim age if that\'s wrong.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Treating the estimated taxable balance as real — replace it with the statement value.',
+        'Leaving combined wages on one spouse in a joint plan (retirement dates then apply to the wrong person).',
+        'Forgetting spending: nothing on a 1040 says what you spend — the Spending screen is the next stop.',
+        'Using this flow to re-enter a plan you already have in RetireGolden — restore the backup instead.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'From the planner home, choose **Import from a file → Your tax return (Form 1040)**. After saving the draft, the review checklist\'s "Not imported" group is your to-do list, starting with the Accounts and Spending screens.',
+    },
+  ],
+}

package/src/learn/content/sensitivity-testing-what-changes-the-answer.ts

@@ -0,0 +1,104 @@
+/**
+ * "Sensitivity testing: what changes the answer most" - a Risk and Uncertainty P2 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const sensitivityTestingWhatChangesAnswerArticle: LearningArticle = {
+  slug: 'sensitivity-testing-what-changes-the-answer',
+  title: 'Sensitivity testing: what changes the answer most',
+  description: 'Finding which assumptions move the outcome the most.',
+  category: 'risk-uncertainty',
+  tags: ['sensitivity', 'scenarios', 'assumptions', 'risk', 'comparison'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'stable',
+  sourceUrls: [],
+  relatedArticles: [
+    'how-assumptions-change-the-answer',
+    'using-scenarios-to-compare-choices',
+    'understanding-monte-carlo-success-rate',
+    'inflation-risk',
+    'historical-vs-random-return-models',
+  ],
+  relatedPlannerRoutes: [
+    '/plan/:planId/scenarios',
+    '/plan/:planId/assumptions',
+    '/plan/:planId/results',
+    '/plan/:planId/monte-carlo',
+  ],
+  currentYearSensitive: false,
+  priority: 'P2',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Sensitivity testing asks a simple question: if one assumption changes, how much does the answer move? It is one of the fastest ways to find which parts of a plan deserve better data or a backup plan.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'A sensitivity test changes one assumption while holding the rest of the plan steady.',
+        'Rank tests by the size and seriousness of the change, not by which one is easiest to edit.',
+        'Good sensitivity tests turn vague worry into a specific planning question.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'A baseline projection can hide which assumptions are doing the heavy lifting. Sensitivity tests separate those levers. For example, lowering returns, raising inflation, extending planning age, or increasing spending may all weaken the plan, but one or two may explain most of the fragility.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/sensitivity-testing.webp' },
+      caption:
+        'Sensitivity testing compares one changed lever at a time against the same baseline.',
+      alt: 'A baseline retirement path is compared with separate colored paths for lower returns, higher spending, higher inflation, and longer life.',
+    },
+    {
+      type: 'table',
+      caption: 'A practical sensitivity-testing sequence.',
+      columns: ['Test', 'Change', 'Question it answers'],
+      rows: [
+        ['Spending', 'Raise or lower annual spending by a set percentage', 'How much lifestyle flexibility protects the plan?'],
+        ['Retirement date', 'Move retirement one or two years', 'How valuable is more saving time and fewer withdrawal years?'],
+        ['Return', 'Lower expected return or use a different market model', 'Is the plan dependent on optimistic growth?'],
+        ['Inflation', 'Raise general or healthcare inflation', 'Does late-life purchasing power break?'],
+        ['Longevity', 'Extend one or both planning ages', 'Does the plan survive a long life or survivor years?'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Morgan household',
+      assumptions: [
+        { label: 'Baseline', value: 'Money lasts through the full plan with a $180,000 estate' },
+        { label: 'Largest sensitivity', value: 'A 12% spending increase causes depletion' },
+        { label: 'Smaller sensitivity', value: 'A 1 point lower return reduces the estate to $95,000 but does not deplete' },
+      ],
+      summary:
+        'Spending is the bigger lever here: one test depletes the plan, while the return test still leaves about **$95,000**. That points the first conversation toward spending flexibility.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'The **Scenarios** page is built for sensitivity testing. Each scenario stores a small patch on top of the base plan, so you can keep editing the baseline without rebuilding every comparison. **Monte Carlo** then adds market variation around the same assumptions.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Testing only pleasant upside cases.',
+        'Changing several inputs at once and calling it sensitivity testing.',
+        'Ranking tests only by ending estate and missing depletion year or success rate.',
+        'Ignoring whether the changed assumption is controllable by the household.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Scenarios** for named one-at-a-time tests, **Assumptions** for plan-wide levers, and **Monte Carlo** when you want the same scenario exposed to many market paths.',
+    },
+  ],
+}

package/src/learn/content/sequence-of-returns-risk.ts

@@ -0,0 +1,98 @@
+/**
+ * "Sequence-of-returns risk" - a Risk and Uncertainty P0 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const sequenceOfReturnsRiskArticle: LearningArticle = {
+  slug: 'sequence-of-returns-risk',
+  title: 'Sequence-of-returns risk',
+  description: 'Why the order of good and bad years matters once you withdraw.',
+  category: 'risk-uncertainty',
+  tags: ['sequence risk', 'returns', 'withdrawals', 'monte carlo', 'retirement risk'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'stable',
+  sourceUrls: ['https://www.investor.gov/introduction-investing/investing-basics/what-risk'],
+  relatedArticles: [
+    'understanding-monte-carlo-success-rate',
+    'what-monte-carlo-proves',
+    'withdrawal-order-basics',
+    'historical-vs-random-return-models',
+    'inflation-risk',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/monte-carlo', '/plan/:planId/results', '/plan/:planId/scenarios'],
+  currentYearSensitive: false,
+  priority: 'P0',
+  featured: true,
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Sequence-of-returns risk is the risk that bad market years arrive at the wrong time. The average return can look fine, but the order of returns can still decide whether withdrawals recover or permanently damage the portfolio.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Before retirement, bad early returns can be helped by later contributions.',
+        'After retirement, bad early returns combine with withdrawals, so fewer dollars remain to recover.',
+        'Monte Carlo and scenarios are useful because the deterministic result shows only one return order.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Imagine two retirements with the same average return. In one, the good years arrive first. In the other, the bad years arrive first. The average may match, but the lived result can be very different because withdrawals are happening along the way. Selling investments after a decline leaves fewer shares available for the rebound.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/sequence-returns-risk.webp' },
+      caption:
+        'Two paths can have the same average return, but early losses during withdrawals can leave a lasting gap.',
+      alt: 'Two retirement balance paths start together. One rises before dipping, while the other dips early during withdrawals and never fully catches up.',
+    },
+    {
+      type: 'table',
+      caption: 'Why the same average can feel different.',
+      columns: ['Timing', 'During saving', 'During withdrawals'],
+      rows: [
+        ['Bad returns early', 'New contributions may buy lower prices', 'Withdrawals sell more shares at lower values'],
+        ['Good returns early', 'Helpful, but still followed by later risk', 'Builds cushion before withdrawals stress the portfolio'],
+        ['Bad returns late', 'Portfolio may have more years to recover first', 'Often less damaging if the plan already built cushion'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Adams household',
+      assumptions: [
+        { label: 'Plan A', value: '+8% average in the first decade, -1% average in the second' },
+        { label: 'Plan B', value: '-1% average in the first decade, +8% average in the second' },
+        { label: 'Withdrawal need', value: '$60,000 a year from the portfolio in both examples' },
+      ],
+      summary:
+        'Both paths can have a similar long-run average, but Plan B sells investments during the weak first decade. The rebound applies to a smaller balance after years of $60,000 withdrawals.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'The **Results** page is deterministic: it uses the expected return and inflation path. The **Monte Carlo** page keeps the same annual ledger but varies market paths, so sequence risk shows up as a fan of outcomes and as depletion-year counts. The **Scenarios** page lets you pair that risk view with spending, claiming, and strategy changes.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Looking only at the average return assumption.',
+        'Assuming a high long-run return eliminates early-retirement risk.',
+        'Ignoring the years when failures happen; early failures usually call for a different response than late failures.',
+        'Comparing strategies under different assumptions instead of holding the assumptions constant.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Monte Carlo** after the baseline plan works in Results. Look at the success rate, percentile fan, and depletion-year chart together. If weak paths fail early, test spending flexibility, later retirement, bridge income, or a different withdrawal strategy.',
+    },
+  ],
+}

package/src/learn/content/social-security-bridge.ts

@@ -0,0 +1,67 @@
+import type { LearningArticle } from '../learningRegistry'
+
+export const socialSecurityBridgeArticle: LearningArticle = {
+  slug: 'social-security-bridge',
+  title: 'The Social Security bridge',
+  description:
+    'Delaying Social Security is the cheapest inflation-protected annuity you can buy — a bridge account pays you the forgone benefit until the bigger check starts.',
+  category: 'social-security',
+  tags: ['claiming age', 'bridge', 'delay', 'longevity insurance', 'tips', 'gap years'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-07-08',
+  reviewCadence: 'stable',
+  sourceUrls: [
+    'https://bipartisanpolicy.org/report/how-to-help-americans-claim-social-security-at-the-right-age/',
+    'https://www.ssa.gov/benefits/retirement/planner/delayret.html',
+    'https://crr.bc.edu/how-best-to-annuitize-defined-contribution-assets/',
+  ],
+  relatedArticles: ['social-security-claiming-age-basics', 'tips-ladders', 'funded-ratio', 'break-even-useful-lens', 'mortality-weighted-social-security'],
+  relatedPlannerRoutes: ['/plan/:planId/social-security-analysis', '/plan/:planId/income-floor'],
+  currentYearSensitive: false,
+  priority: 'P1',
+  featured: false,
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Most people claim Social Security early — and researchers estimate the habit costs retirees **trillions of dollars of lifetime benefits** in aggregate. The usual reason is immediate and human: *"I retired, the paycheck stopped, and I need income now."* The **bridge** is the standard fix. Instead of claiming at 62, you pay yourself the benefit you would have received — the same monthly amount, inflation-adjusted — out of a dedicated pot of savings, until your delayed claim starts at 67 or 70.',
+    },
+    { type: 'heading', text: 'Why delaying is worth bridging' },
+    {
+      type: 'list',
+      items: [
+        '**The delay "buys" an annuity at government prices**: every year of delay permanently raises the benefit (roughly 7–8% per year, plus COLAs on the bigger base). No insurer sells inflation-indexed lifetime income that cheaply.',
+        '**It is longevity insurance**: the bigger check lasts exactly as long as you do. If you live to 95, the age-70 claim pays enormously more; if you die early, the bridge money you did not spend stays in your estate.',
+        '**It protects the survivor**: for couples, the higher earner\'s delayed benefit becomes the survivor benefit. Delaying is often worth more to the widow(er) than to the worker.',
+      ],
+    },
+    { type: 'heading', text: 'What the bridge looks like' },
+    {
+      type: 'scenario',
+      name: 'Maria bridges to 70',
+      assumptions: [
+        { label: 'PIA (benefit at full retirement age 67)', value: '$2,400/mo' },
+        { label: 'Age-62 benefit (70% of PIA)', value: '$1,680/mo → $20,160/yr' },
+        { label: 'Retires at 62, claims at 70', value: '8 gap years' },
+        { label: 'Bridge', value: 'Pays herself $20,160/yr (inflation-adjusted) from 62 to 69' },
+        { label: 'Age-70 benefit (124% of PIA)', value: '$2,976/mo — 77% larger than claiming at 62, for life' },
+      ],
+      summary:
+        'Maria\'s lifestyle never dips in the gap years — the bridge replaces exactly what claiming early would have paid — and from 70 on she holds the largest inflation-indexed life annuity she could get.',
+    },
+    {
+      type: 'prose',
+      md: 'The bridge can be a cash bucket, but the natural instrument is a **[TIPS ladder](/learn/tips-ladders)** maturing across the gap years: the income is then guaranteed in real terms, exactly matching the inflation-indexed benefit it replaces. RetireGolden\'s Social Security Optimizer sizes the bridge from your own numbers — the forgone age-62 benefit, your retirement year, and your chosen claim age — quotes the ladder cost on the current real-yield curve, and can add it to your plan as a funded artifact you can see, stress-test, and compare.',
+    },
+    { type: 'heading', text: 'Bridge vs. claim early — how to compare honestly' },
+    {
+      type: 'prose',
+      md: 'The right comparison is not "delay vs. claim early" in isolation — it is **bridge + delayed claim vs. claim early and keep the savings invested**, run through your full plan on the same market paths. The claim-early path keeps more money compounding but locks in the smaller check forever; the bridge path spends savings now to buy a much larger guaranteed floor later. RetireGolden runs both through the same ledger and Monte Carlo so the success-rate and estate differences are priced, not asserted. Break-even ages are a useful sanity check, but the plan-level comparison is the decision-grade one.',
+    },
+    {
+      type: 'callout',
+      tone: 'warn',
+      md: 'A bridge only makes sense with money to bridge from: if funding it would leave you without a liquid reserve, or push you into selling assets at depressed prices, the early claim can genuinely be the better plan. Health and family longevity matter too — the delayed claim is insurance against a *long* life, and insurance you may reasonably decline.',
+    },
+  ],
+}