@retiregolden/planner-ui 0.1.0

package/src/learn/content/trust-fund-haircut-scenarios.ts

@@ -0,0 +1,101 @@
+/**
+ * "Trust fund haircut scenarios" - a Social Security P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const trustFundHaircutScenariosArticle: LearningArticle = {
+  slug: 'trust-fund-haircut-scenarios',
+  title: 'Trust fund haircut scenarios',
+  description: 'How to model a possible future reduction in scheduled benefits.',
+  category: 'social-security',
+  tags: ['social security', 'trust fund', 'haircut', 'scenario', 'stress test'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'annual',
+  sourceUrls: ['https://www.ssa.gov/OACT/TR/'],
+  relatedArticles: [
+    'cola-and-inflation-protection',
+    'social-security-claiming-age-basics',
+    'using-scenarios-to-compare-choices',
+    'how-assumptions-change-the-answer',
+  ],
+  relatedPlannerRoutes: [
+    '/plan/:planId/assumptions',
+    '/plan/:planId/scenarios',
+    '/plan/:planId/social-security',
+    '/plan/:planId/results',
+  ],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'A Social Security trust fund haircut scenario asks a practical question: what if scheduled benefits were reduced in a future year? It is a stress test, not a prediction of what Congress or SSA will do.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Scheduled benefits and payable benefits can be different policy questions.',
+        'A haircut scenario reduces modeled Social Security benefits starting in a chosen year.',
+        'The point is to test dependency on Social Security, not to forecast the exact law.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Social Security is not a personal account with your name on a trust-fund balance. It is a national program funded by taxes, trust funds, and law. Trustees reports discuss program finances and projected shortfalls, but the final outcome depends on future policy choices.\n\nFor planning, the useful move is to separate opinion from resilience. You can run the plan once using scheduled benefits, then run a second version with a future benefit reduction. If both plans work, the household is less exposed to Social Security policy risk. If the haircut plan fails, the result tells you where the plan depends on benefits most.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/trust-fund-haircut-scenarios.webp' },
+      caption:
+        'A trust fund haircut scenario draws a future boundary, then tests whether the plan can absorb a reduced Social Security stream after that point.',
+      alt: 'A Social Security income ribbon crosses a timeline and becomes narrower after a warning boundary, while portfolio and spending buckets show the plan absorbing the change.',
+    },
+    {
+      type: 'table',
+      caption: 'How to use a haircut scenario without overclaiming precision.',
+      columns: ['Question', 'Good use', 'Weak use'],
+      rows: [
+        ['How dependent is the plan?', 'Compare scheduled benefits with a reduced-benefit scenario', 'Assume the exact cut and year are known'],
+        ['Which years are fragile?', 'Look for depletion or tax changes after the cut year', 'Focus only on the first year of retirement'],
+        ['What can I change?', 'Test spending, retirement age, saving, or claiming alternatives', 'Treat the scenario as a personal recommendation'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Patel household',
+      assumptions: [
+        { label: 'Base case', value: '$50,000 a year of scheduled Social Security benefits' },
+        { label: 'Stress case', value: '23% reduction starting in a future year' },
+        { label: 'Income gap', value: 'Benefits fall by about $11,500 a year after the haircut starts' },
+      ],
+      summary:
+        'The haircut scenario does not predict a cut. It asks whether the Patels could absorb an **$11,500** annual income gap with spending flexibility, later work, or portfolio withdrawals.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden has an optional Social Security haircut assumption. You choose a start year and a cut percentage. The projection applies that reduction to modeled Social Security benefits from that year forward, including benefits used in Results and scenario comparisons.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Reading one scenario as a forecast instead of a stress test.',
+        'Only testing the headline cut and ignoring the year it starts.',
+        'Forgetting that a benefit cut can change taxes, withdrawals, and estate value.',
+        'Assuming the correct response is always to claim early. The full plan still matters.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Assumptions** to turn on a Social Security haircut, or use **Scenarios** to create a side-by-side case. Then inspect **Results** for spending coverage, taxes, withdrawals, and ending estate.',
+    },
+  ],
+}

package/src/learn/content/understanding-monte-carlo-success-rate.ts

@@ -0,0 +1,118 @@
+/**
+ * "Understanding Monte Carlo success rate" - a Using RetireGolden P0 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const understandingMonteCarloArticle: LearningArticle = {
+  slug: 'understanding-monte-carlo-success-rate',
+  title: 'Understanding Monte Carlo success rate',
+  description: 'How to read the success-rate number without over-trusting it.',
+  category: 'using-retiregolden',
+  tags: ['monte carlo', 'success rate', 'simulation', 'risk', 'sequence risk'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-19',
+  reviewCadence: 'stable',
+  sourceUrls: ['https://www.investor.gov/introduction-investing/investing-basics/glossary/monte-carlo-simulation'],
+  relatedArticles: [
+    'how-to-read-a-retirement-projection',
+    'reading-the-results-page',
+    'what-monte-carlo-proves',
+    'sequence-of-returns-risk',
+    'why-95-percent-is-not-a-guarantee',
+  ],
+  relatedPlannerRoutes: [
+    '/plan/:planId/monte-carlo',
+    '/plan/:planId/results',
+    '/plan/:planId/scenarios',
+    '/plan/:planId/optimize',
+  ],
+  currentYearSensitive: false,
+  priority: 'P0',
+  featured: true,
+  blocks: [
+    {
+      type: 'prose',
+      md: 'A Monte Carlo success rate is a model statistic. It tells you how often the plan survived across many simulated market paths. It does not tell you the exact probability that your real life will work out.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Success means investable assets did not run out before the end of the modeled plan.',
+        'A higher success rate usually means more cushion, but the inputs and model choice matter.',
+        'Use Monte Carlo to compare risk between choices, not to declare that a plan is guaranteed.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'The deterministic Results page uses one return and inflation path. Monte Carlo runs the same plan many times with different market paths. Some paths are friendly. Some are rough. The success rate is the share of paths where the plan makes it through.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/monte-carlo-paths.webp' },
+      caption:
+        'Monte Carlo starts from one plan and explores many possible paths; some reach the end comfortably and some fall short.',
+      alt: 'Many teal and green paths flow from one plan bucket toward a finish area, while a few amber and coral paths fade or dip before the end of the timeline.',
+    },
+    {
+      type: 'formula',
+      expression: 'success rate = successful paths / total paths',
+      where: [
+        { symbol: 'successful paths', meaning: 'simulated futures where investable assets never deplete before the plan ends' },
+        { symbol: 'total paths', meaning: 'the number of simulated market paths RetireGolden ran' },
+      ],
+      note: 'RetireGolden runs 1,000 paths automatically and can run 10,000 paths on demand for a tighter estimate.',
+    },
+    { type: 'heading', text: 'What the number means' },
+    {
+      type: 'table',
+      caption: 'A plain-language way to read success rates.',
+      columns: ['Result', 'What it says', 'What to do next'],
+      rows: [
+        ['90%+', 'The plan survived in nearly all modeled paths.', 'Check whether the assumptions are realistic and whether the remaining risk is acceptable.'],
+        ['75%-89%', 'The plan often works, but bad markets can matter.', 'Look at depletion years, spending flexibility, and timing choices.'],
+        ['Below 75%', 'Many modeled paths run out of investable assets.', 'Use Scenarios to test spending, retirement date, income timing, or risk changes.'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Garcia household',
+      assumptions: [
+        { label: 'Baseline deterministic result', value: 'Money lasts through the full plan' },
+        { label: 'Monte Carlo result', value: '78% success over 1,000 paths' },
+        { label: 'Key clue', value: 'About 220 paths deplete, usually in the first decade after retirement' },
+      ],
+      summary:
+        'A 78% success rate means roughly **220 out of 1,000** tested paths fail. Because failures cluster early, the Garcias should test spending flexibility, later retirement, or a different claim/investment mix.',
+    },
+    { type: 'heading', text: 'Model controls change the question' },
+    {
+      type: 'list',
+      items: [
+        '**Lognormal** paths vary around your expected return and inflation assumptions.',
+        '**Historical** paths resample market history in different ways, which can preserve more real-world clustering.',
+        '**Seed** changes the random draw. If one seed changes the conclusion a lot, run more paths or test scenarios.',
+        '**Model longevity** and **LTC shock** add life-span and long-term-care uncertainty when you want a wider stress test.',
+      ],
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Reading 95% as "I am safe." It means 95% of modeled paths worked under the assumptions used.',
+        'Treating a one-point difference as meaningful when only 1,000 paths were run.',
+        'Ignoring the depletion-year chart. A 78% success rate with failures at age 93 feels different from failures at age 72.',
+        'Comparing two strategies with different assumptions and calling the success-rate change a strategy effect.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Monte Carlo** after the Results page makes sense. Use **Scenarios** or **Optimize** when you want to compare choices, then come back to Monte Carlo to see whether the better-looking choice also holds up under market variation.',
+    },
+  ],
+}

package/src/learn/content/understanding-your-plan-assumptions.ts

@@ -0,0 +1,134 @@
+import type { LearningArticle } from '../learningRegistry'
+
+export const understandingYourPlanAssumptionsArticle: LearningArticle = {
+  slug: 'understanding-your-plan-assumptions',
+  title: "Understanding your plan's assumptions",
+  description: 'How RetireGolden uses assumptions to project your retirement success, and where they come from.',
+  category: 'using-retiregolden',
+  tags: ['assumptions', 'inflation', 'returns', 'longevity', 'rules'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-30',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.ssa.gov/oact/TR/2025/2025_Long-Range_Economic_Assumptions.pdf',
+    'https://hvsfinancial.com/wp-content/uploads/2026/02/2026-Data-Report.pdf',
+    'https://corporate.vanguard.com/content/corporatesite/us/en/corp/vemo/2026-outlook-economic-upside-stock-market-downside.html',
+    'https://www.longevityillustrator.org/',
+  ],
+  relatedArticles: [
+    'using-assumptions-and-provenance',
+    'assumption-general-inflation',
+    'assumption-healthcare-inflation',
+    'assumption-investment-returns',
+    'assumption-social-security-cola',
+    'assumption-social-security-trust-fund',
+    'assumption-longevity-planning-age',
+    'assumption-state-tax-override',
+    'assumption-recent-magi',
+    'assumption-heir-tax-rate',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/assumptions'],
+  currentYearSensitive: true,
+  priority: 'P0',
+  blocks: [
+    {
+      type: 'prose',
+      md: "A retirement plan is a model of the future. While some numbers in your plan are **facts** (like your current age or account balances) and others are **rules** (like the 2026 tax brackets), the engine also needs **forward-looking assumptions** to project how your money will grow and what it will buy decades from now.",
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Assumptions are the levers that drive your projection: inflation, healthcare costs, returns, Social Security behavior, taxes, MAGI seeds, longevity, and estate-tax treatment.',
+        'RetireGolden starts you with research-backed defaults, but every retirement plan is unique—you can override any default to fit your views.',
+        "No single number is a guarantee. RetireGolden's Monte Carlo simulation varies returns and inflation around these assumptions to stress-test your plan.",
+      ],
+    },
+    { type: 'heading', text: 'The assumption library' },
+    {
+      type: 'prose',
+      md: 'Each planner-facing assumption has a focused deep dive. Use this table as the index:',
+    },
+    {
+      type: 'table',
+      caption: 'Assumption defaults in RetireGolden',
+      columns: ['Assumption', 'Default Value', 'Sourced Basis', 'Deep Dive'],
+      rows: [
+        [
+          '**General Inflation**',
+          '2.5%',
+          'SSA long-range estimate (2.4%), Philly Fed SPF (2.4%), Fed long-run goal (2.0%).',
+          '[Read more](/learn/assumption-general-inflation)',
+        ],
+        [
+          '**Healthcare Inflation**',
+          '+3.0% over CPI',
+          'HealthView Services 2026 projections of 5.8% total long-term retiree healthcare inflation.',
+          '[Read more](/learn/assumption-healthcare-inflation)',
+        ],
+        [
+          '**Investment Returns**',
+          '5.5% blended',
+          "Vanguard's 2026 outlook (4–5% equity) and J.P. Morgan's 2026 LTCMA (6.4% balanced 60/40).",
+          '[Read more](/learn/assumption-investment-returns)',
+        ],
+        [
+          '**Longevity (Planning Age)**',
+          '95 (floor)',
+          'Society of Actuaries guidance to plan for the 75th to 90th percentile of joint survival.',
+          '[Read more](/learn/assumption-longevity-planning-age)',
+        ],
+        [
+          '**Social Security COLA**',
+          'Match inflation',
+          'Social Security COLA is tied to CPI-W; matching general inflation keeps real benefits flat.',
+          '[Read more](/learn/assumption-social-security-cola)',
+        ],
+        [
+          '**Social Security Trust Fund**',
+          'Off; 2034 / 17% when on',
+          '2026 Trustees report: combined OASDI depletion in 2034 with 83% payable.',
+          '[Read more](/learn/assumption-social-security-trust-fund)',
+        ],
+        [
+          '**State Tax Override**',
+          '0%',
+          '0% means use modeled state tax rules; a positive value replaces them with a flat effective rate.',
+          '[Read more](/learn/assumption-state-tax-override)',
+        ],
+        [
+          '**Recent MAGI**',
+          '$0',
+          'Input seed for Medicare IRMAA two-year lookback; 0 means no initial surcharge from recent income.',
+          '[Read more](/learn/assumption-recent-magi)',
+        ],
+        [
+          '**Heir Tax Rate**',
+          '25%',
+          'A mid-bracket estimate for inherited pre-tax retirement balances under the 10-year rule.',
+          '[Read more](/learn/assumption-heir-tax-rate)',
+        ],
+      ],
+    },
+    { type: 'heading', text: 'Why defaults matter' },
+    {
+      type: 'prose',
+      md: "A minor change in an assumption can compound into a massive difference over 30 or 40 years. For example, assuming healthcare costs grow at CPI + 3% instead of CPI + 2% can add tens of thousands of dollars in projected lifetime expenses, potentially shifting your plan's success rate. RetireGolden defaults to slightly conservative, source-backed values so you don't build a plan on overly optimistic foundations.",
+    },
+    { type: 'heading', text: 'Watch-outs' },
+    {
+      type: 'list',
+      items: [
+        'Do not treat a default as personal advice; it is a starting point you can override.',
+        'Change one major assumption at a time when testing sensitivity, or it becomes hard to know what moved the result.',
+        'Dated rule packs, such as tax brackets and Medicare thresholds, are different from user-overridable assumptions.',
+      ],
+    },
+    { type: 'heading', text: 'Where to manage these in the app' },
+    {
+      type: 'prose',
+      md: 'You can view and override all forward-looking assumptions on the **Assumptions** screen. For planning ages, you can adjust these per household member under the **Household** step, which feeds into the longevity module. The dated rule packs (like tax brackets and Medicare thresholds) are non-overridable and can be reviewed via the **Disclaimer** page.',
+    },
+  ],
+}

package/src/learn/content/using-assumptions-and-provenance.ts

@@ -0,0 +1,98 @@
+/**
+ * "How to use assumptions and provenance" - a Using RetireGolden P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const usingAssumptionsAndProvenanceArticle: LearningArticle = {
+  slug: 'using-assumptions-and-provenance',
+  title: 'How to use assumptions and provenance',
+  description: 'Where each default comes from and how to override it responsibly.',
+  category: 'using-retiregolden',
+  tags: ['retiregolden', 'assumptions', 'provenance', 'defaults', 'parameter pack'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'stable',
+  sourceUrls: ['https://www.irs.gov/', 'https://www.ssa.gov/', 'https://www.medicare.gov/', 'https://www.healthcare.gov/'],
+  relatedArticles: [
+    'how-assumptions-change-the-answer',
+    'what-retiregolden-models',
+    'inflation-risk',
+    'irmaa-two-year-lookback',
+    'aca-premium-tax-credits-and-magi',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/assumptions', '/plan/:planId/results', '/plan/:planId/monte-carlo'],
+  currentYearSensitive: false,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Assumptions are the bridge between your plan and the rules RetireGolden applies. Some assumptions are choices you set directly. Others come from dated parameter packs, such as tax brackets, contribution limits, RMD factors, Medicare, IRMAA, ACA, and Social Security figures.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Use plan assumptions for the household-specific future: inflation, returns, recent MAGI, state override, and Social Security COLA.',
+        'Use provenance to see where the app\'s rule defaults came from.',
+        'Override a default when you have better household-specific information, not just because the output is uncomfortable.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'A parameter pack is a snapshot of published rules and dollar values. It helps the engine apply tax and benefit rules consistently without asking you to enter every bracket, limit, premium, and threshold yourself. Provenance is the record of where those inputs came from and when they were compiled.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/assumptions-provenance.webp' },
+      caption:
+        'Household assumptions and sourced parameter packs meet inside the projection engine.',
+      alt: 'Two streams labeled by icons for household choices and official sources flow into a structured projection ledger.',
+    },
+    {
+      type: 'table',
+      caption: 'Where to look when a number feels surprising.',
+      columns: ['Question', 'Where to check', 'What to do next'],
+      rows: [
+        ['Is this my input?', 'The planner entry screen that owns the field', 'Correct the fact if it is wrong'],
+        ['Is this a plan-wide assumption?', 'Assumptions', 'Adjust it and rerun Results or Monte Carlo'],
+        ['Is this a rule default?', 'Disclaimer and provenance table', 'Verify against the official source if it matters'],
+        ['Is this beyond the latest published pack?', 'Report notes or modeling warnings', 'Treat projected future thresholds as planning approximations'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Jordan household',
+      assumptions: [
+        { label: 'Question', value: 'Medicare costs rise by about $1,900 after a Roth conversion year' },
+        { label: 'First check', value: 'MAGI increased from $170,000 to $240,000 on the Results page' },
+        { label: 'Second check', value: 'Provenance shows which Medicare and IRMAA values the estimate used' },
+      ],
+      summary:
+        'The higher cost is not a random output. The Jordans can connect the $70,000 MAGI increase to the sourced Medicare rule and decide whether the conversion is still worth it.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'The **Assumptions** screen is where you set plan-wide levers. The **Disclaimer** page includes the provenance table for dated rule defaults. Results and reports may also show modeling notes when a value is a planning approximation or a future-year stand-in.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Changing returns or inflation to make a preferred strategy look better.',
+        'Forgetting that future years may use indexed or stand-in values when official figures are not published yet.',
+        'Treating a provenance source as tax advice instead of a place to verify the rule input.',
+        'Leaving a state override at zero when the modeled state treatment does not fit your situation.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Assumptions** when you want to change the plan. Use the **Disclaimer** and provenance table when you want to understand the source of the default. Then rerun **Results** and **Monte Carlo** to see what changed.',
+    },
+  ],
+}

package/src/learn/content/using-scenarios-to-compare-choices.ts

@@ -0,0 +1,99 @@
+/**
+ * "Using Scenarios to compare choices" - a Using RetireGolden P0 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const usingScenariosToCompareChoicesArticle: LearningArticle = {
+  slug: 'using-scenarios-to-compare-choices',
+  title: 'Using Scenarios to compare choices',
+  description: 'How to stress-test and compare plan variations side by side.',
+  category: 'using-retiregolden',
+  tags: ['scenarios', 'what if', 'comparison', 'stress test', 'monte carlo'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'stable',
+  sourceUrls: [],
+  relatedArticles: [
+    'planner-overview',
+    'how-assumptions-change-the-answer',
+    'three-big-questions-spending-time-risk',
+    'understanding-monte-carlo-success-rate',
+    'sequence-of-returns-risk',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/scenarios', '/plan/:planId/results', '/plan/:planId/monte-carlo'],
+  currentYearSensitive: false,
+  priority: 'P0',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Scenarios help you compare one decision at a time without losing the base plan. A scenario is a set of overrides layered on top of the current plan: retire earlier, spend more, skip Roth conversions, model a Social Security cut, or add a care shock.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Use scenarios when the question starts with "what if?"',
+        'A good scenario changes only the few inputs needed to test the question.',
+        'The Scenarios table compares ending estate, lifetime tax, depletion year, changed fields, and optional Monte Carlo success with shared markets.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'The base plan remains the source of truth. Each scenario stores a patch, and RetireGolden merges that patch over the base plan for comparison. If the scenario is invalid, the table shows an error instead of silently simulating a broken plan.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/scenarios-compare-choices.webp' },
+      caption:
+        'Scenarios keep the base plan intact while testing alternate choices side by side.',
+      alt: 'A base retirement plan branches into several side-by-side paths for earlier retirement, higher spending, lower returns, and care costs, then returns to a comparison table.',
+    },
+    {
+      type: 'table',
+      caption: 'When to use Scenarios instead of editing the base plan directly.',
+      columns: ['Question', 'Scenario idea', 'What to compare'],
+      rows: [
+        ['Can I retire sooner?', 'Retire earlier or later', 'Depletion year, estate, taxes, and success rate'],
+        ['What if I spend more?', 'Spend more or less', 'How quickly the margin disappears'],
+        ['What if Social Security is cut?', 'Benefit haircut from a future year', 'Whether portfolio withdrawals fill the gap'],
+        ['Do Roth conversions help?', 'Skip conversions or compare a different strategy', 'Lifetime tax, estate, and Monte Carlo risk'],
+        ['What if care costs hit?', 'Add long-term-care shock years', 'Whether assets survive a concentrated expense'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Kim household',
+      assumptions: [
+        { label: 'Base plan', value: 'Retire at 65, spend $90,000 per year' },
+        { label: 'Scenario A', value: 'Retire two years earlier and reduce ending estate by $140,000' },
+        { label: 'Scenario B', value: 'Retire at 65 but spend 15% more, reducing success from 88% to 73%' },
+      ],
+      summary:
+        'The early-retirement scenario mostly costs estate value. The higher-spending scenario damages risk more, dropping success by **15 percentage points** in this example.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'The Scenarios screen can include a 200-path Monte Carlo success rate for each row, using the same seed so every scenario faces the same market paths. That makes comparisons cleaner than re-running separate plans with unrelated random draws.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Changing the base plan and the scenario at the same time.',
+        'Packing too many changes into one scenario and then not knowing what caused the result.',
+        'Comparing estate value without checking whether one path depletes earlier.',
+        'Treating the 200-path scenario success rate as a final Monte Carlo answer; use the full Monte Carlo screen for a deeper run.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Scenarios** after the base plan is credible in **Results**. If a scenario looks promising, either edit the base plan intentionally or duplicate the plan for a larger comparison.',
+    },
+  ],
+}