@retiregolden/planner-ui 0.1.0

package/src/learn/components/PurchasingPowerChart.tsx

@@ -0,0 +1,41 @@
+/**
+ * Illustrative chart: the buying power of a fixed $50,000 over 30 years at about
+ * 3% inflation a year. A teaching aid with simple, round numbers — not a
+ * plan-specific result — kept evergreen (no current-year figures).
+ */
+
+import { CartesianGrid, Line, LineChart, ResponsiveContainer, Tooltip, XAxis, YAxis } from 'recharts'
+import { fmtMoney, fmtMoneyCompact } from '../../planner/format'
+import { chartTooltipStyle } from '../../planner/chartStyle'
+
+export function PurchasingPowerChart() {
+  const start = 50_000
+  const inflation = 0.03
+  const data = Array.from({ length: 31 }, (_, year) => ({
+    year,
+    value: Math.round(start / (1 + inflation) ** year),
+  }))
+
+  return (
+    <div className="learn-chart-wrap">
+      <ResponsiveContainer width="100%" height="100%">
+        <LineChart data={data} margin={{ left: 8, right: 12, top: 8, bottom: 4 }}>
+          <CartesianGrid stroke="var(--border)" strokeDasharray="3 3" />
+          <XAxis
+            dataKey="year"
+            tick={{ fill: 'var(--muted)', fontSize: 12 }}
+            label={{ value: 'Years from now', position: 'insideBottom', offset: -2, fill: 'var(--muted)', fontSize: 12 }}
+            height={40}
+          />
+          <YAxis tickFormatter={fmtMoneyCompact} tick={{ fill: 'var(--muted)', fontSize: 12 }} width={56} />
+          <Tooltip
+            formatter={(v: unknown) => [fmtMoney(Number(v)), 'Buying power']}
+            labelFormatter={(l) => `Year ${l}`}
+            contentStyle={chartTooltipStyle}
+          />
+          <Line dataKey="value" stroke="var(--chart-1)" dot={false} strokeWidth={2} />
+        </LineChart>
+      </ResponsiveContainer>
+    </div>
+  )
+}

package/src/learn/components/RelatedArticles.tsx

@@ -0,0 +1,27 @@
+/**
+ * Renders the "Related" strip for an article. Resolves related slugs to
+ * articles and shows only readable ones, so there are never dead links.
+ * Renders nothing when no related article is readable yet.
+ */
+
+import { getArticle, isReadable, type LearningArticle } from '../learningRegistry'
+import { ArticleCard } from '../LearnCards'
+
+export function RelatedArticles({ slugs }: { slugs: string[] }) {
+  const related = slugs
+    .map(getArticle)
+    .filter((a): a is LearningArticle => a !== undefined && isReadable(a))
+
+  if (related.length === 0) return null
+
+  return (
+    <section className="learn-section" aria-label="Related articles">
+      <h2 className="learn-section-title">Related</h2>
+      <div className="learn-card-grid">
+        {related.map((a) => (
+          <ArticleCard key={a.slug} article={a} />
+        ))}
+      </div>
+    </section>
+  )
+}

package/src/learn/components/ScenarioCard.tsx

@@ -0,0 +1,24 @@
+/**
+ * Renders a `scenario` block: a named example household with its assumptions
+ * laid out as label/value rows, plus an optional plain-language takeaway.
+ */
+
+import { renderInline } from '../inlineMarkdown'
+import type { ScenarioBlockData } from '../learningRegistry'
+
+export function ScenarioCard({ block }: { block: ScenarioBlockData }) {
+  return (
+    <aside className="learn-scenario" aria-label={`Scenario: ${block.name}`}>
+      <p className="learn-scenario-name">{block.name}</p>
+      <dl className="learn-scenario-grid">
+        {block.assumptions.map((a) => (
+          <div key={a.label} className="learn-scenario-row">
+            <dt>{a.label}</dt>
+            <dd>{a.value}</dd>
+          </div>
+        ))}
+      </dl>
+      {block.summary && <p className="learn-scenario-summary">{renderInline(block.summary)}</p>}
+    </aside>
+  )
+}

package/src/learn/components/SourceList.tsx

@@ -0,0 +1,23 @@
+/**
+ * Renders an article's source URLs as a labelled list of external links.
+ * Renders nothing when there are no sources.
+ */
+
+export function SourceList({ urls }: { urls: string[] }) {
+  if (urls.length === 0) return null
+
+  return (
+    <div className="learn-sources">
+      <h2 className="learn-section-title">Sources</h2>
+      <ul className="learn-list">
+        {urls.map((url) => (
+          <li key={url}>
+            <a href={url} target="_blank" rel="noreferrer">
+              {url}
+            </a>
+          </li>
+        ))}
+      </ul>
+    </div>
+  )
+}

package/src/learn/components/charts.tsx

@@ -0,0 +1,21 @@
+/**
+ * Chart registry for `figure` blocks. Articles reference a chart by id; this
+ * helper maps the id to the right (internal) chart component. Defining no
+ * component of its own keeps this module off the Fast Refresh boundary.
+ */
+
+import type { ReactNode } from 'react'
+import { PurchasingPowerChart } from './PurchasingPowerChart'
+
+/** Chart ids articles may reference; used by the registry-integrity test. */
+export const LEARN_CHART_IDS = ['purchasing-power'] as const
+
+/** Render the chart registered under `chartId`, or null if there is no match. */
+export function renderLearnChart(chartId: string): ReactNode {
+  switch (chartId) {
+    case 'purchasing-power':
+      return <PurchasingPowerChart />
+    default:
+      return null
+  }
+}

package/src/learn/content/about-retiregolden.ts

@@ -0,0 +1,100 @@
+/**
+ * The single finished article shipped with the V9 framework (PR1).
+ *
+ * It is intentionally evergreen — no tax brackets, dollar limits, or other
+ * current-year figures — so it can exercise the article renderer end to end
+ * without carrying review-cadence or source obligations.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const aboutRetireGoldenArticle: LearningArticle = {
+  slug: 'about-retiregolden',
+  title: 'About RetireGolden',
+  description: 'What RetireGolden is, how it keeps your data private, and how to start your first plan.',
+  category: 'using-retiregolden',
+  tags: ['overview', 'getting started', 'privacy', 'about'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-19',
+  reviewCadence: 'stable',
+  sourceUrls: [],
+  relatedArticles: ['planner-overview', 'what-retiregolden-models', 'privacy-what-stays-in-your-browser'],
+  relatedPlannerRoutes: ['/'],
+  currentYearSensitive: false,
+  blocks: [
+    {
+      type: 'prose',
+      md: 'RetireGolden helps you see how the choices you make today could shape your retirement — and it does it without sending a single number to anyone.',
+    },
+    {
+      type: 'heading',
+      text: 'Quick takeaways',
+    },
+    {
+      type: 'list',
+      items: [
+        'RetireGolden is an **educational planner**, not personalized financial, tax, or legal advice.',
+        'Everything you enter stays **in your browser** — there are no accounts and no server.',
+        'You build a plan section by section, then explore results, risk, and trade-offs.',
+      ],
+    },
+    {
+      type: 'heading',
+      text: 'What RetireGolden is',
+    },
+    {
+      type: 'prose',
+      md: "RetireGolden is a retirement-planning calculator that models how your savings, income, spending, and taxes might play out over the years ahead. You give it the pieces of your financial picture, and it projects a possible future so you can ask “what if?” questions.\n\nIt is built to **teach**, not to decide for you. The goal is a clearer mental model of how the parts of a plan fit together, so the choices you face feel less like guesswork.",
+    },
+    {
+      type: 'heading',
+      text: 'Everything stays in your browser',
+    },
+    {
+      type: 'prose',
+      md: 'RetireGolden has no accounts and no server-side storage. Every plan you create lives only on this device, in your browser.\n\nThat privacy comes with a trade-off: if you clear your browser data or switch devices, your plans are gone. Use the export option on the planner home to keep a backup you control.',
+    },
+    {
+      type: 'callout',
+      tone: 'note',
+      md: 'Because nothing is uploaded, RetireGolden cannot recover a lost plan for you. A quick plan backup is your safety net.',
+    },
+    {
+      type: 'heading',
+      text: 'What it can and cannot do',
+    },
+    {
+      type: 'prose',
+      md: 'RetireGolden models common retirement realities: account types, Social Security, taxes at planning precision, withdrawals, Roth conversions, healthcare costs, and the role of luck through Monte Carlo simulation.\n\nIt does not file your taxes, give personal advice, or predict the future. Real markets, laws, and lives are messier than any model. Treat the numbers as a way to compare choices, not as promises.',
+    },
+    {
+      type: 'table',
+      caption: 'What RetireGolden is built for — and what it is not.',
+      columns: ['Area', 'What it does', 'What it does not do'],
+      rows: [
+        ['Projections', 'Models savings, income, spending, and taxes over time', 'Predict actual market returns'],
+        ['Taxes', 'Estimates federal and state tax at planning precision', 'Replace a tax return or a tax advisor'],
+        ['Decisions', 'Helps you compare choices side by side', 'Tell you what you personally should do'],
+      ],
+    },
+    {
+      type: 'heading',
+      text: 'How to start',
+    },
+    {
+      type: 'list',
+      ordered: true,
+      items: [
+        'Open the [planner home](/) and create a new plan.',
+        'Work through the sections on the left, from **Household** to **Assumptions**.',
+        'Visit **Results**, **Monte Carlo**, and **Optimize** to explore what your plan implies.',
+        'Come back to the Learning Center whenever a term or screen needs explaining.',
+      ],
+    },
+    {
+      type: 'prose',
+      md: 'You do not need every detail to get value. A rough plan with sensible defaults already tells you a lot — you can refine it over time.',
+    },
+  ],
+}

package/src/learn/content/aca-premium-tax-credits-and-magi.ts

@@ -0,0 +1,103 @@
+/**
+ * "ACA premium tax credits and MAGI" - a Healthcare P0 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const acaPremiumTaxCreditsAndMagiArticle: LearningArticle = {
+  slug: 'aca-premium-tax-credits-and-magi',
+  title: 'ACA premium tax credits and MAGI',
+  description: 'How income controls the subsidy for pre-Medicare health coverage.',
+  category: 'healthcare',
+  tags: ['aca', 'premium tax credit', 'magi', 'marketplace', 'healthcare before 65', 'tax cliff'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-19',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.healthcare.gov/lower-costs/',
+    'https://www.healthcare.gov/income-and-household-information/income/',
+    'https://www.irs.gov/forms-pubs/about-publication-974',
+  ],
+  relatedArticles: [
+    'agi-magi-and-taxable-income',
+    'healthcare-before-65',
+    'why-roth-conversions-raise-other-costs',
+    'filling-a-tax-bracket-with-roth-conversions',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/spending', '/plan/:planId/results', '/plan/:planId/strategy'],
+  currentYearSensitive: true,
+  priority: 'P0',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Before Medicare, many early retirees use an ACA marketplace plan. The premium tax credit can lower the monthly premium, but it depends heavily on household income. In planning, that means MAGI is not just a tax line. It can also be a healthcare-cost line.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'ACA premium tax credits are income-tested.',
+        'Roth conversions, IRA withdrawals, wages, and realized gains can raise MAGI.',
+        'Managing MAGI can matter most in the gap years before Medicare starts.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'The marketplace looks at household income for the coverage year. A lower income can mean a larger credit; a higher income can mean a smaller credit or no credit under the rules being modeled. That is why one extra dollar of income can sometimes cost more than one extra dollar of tax.\n\nThe premium tax credit is not a reason to keep income artificially low at all costs. It is a signal to compare choices carefully: taxable withdrawals, capital gains, part-time wages, and Roth conversions all push on the same income measure.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/aca-magi-premium-credit.webp' },
+      caption:
+        'Marketplace subsidies are driven by household income: income flows into MAGI, and MAGI controls how much premium help remains.',
+      alt: 'Income ribbons flow into a MAGI funnel, which controls an amber subsidy ribbon that lowers a healthcare premium bucket near a cliff edge.',
+    },
+    { type: 'heading', text: 'What raises ACA MAGI in retirement' },
+    {
+      type: 'table',
+      caption: 'Common income sources that can affect the credit.',
+      columns: ['Income source', 'Why it matters', 'Planning note'],
+      rows: [
+        ['Traditional IRA withdrawal', 'Usually raises ordinary income and MAGI', 'Needed spending can reduce subsidy room'],
+        ['Roth conversion', 'Raises income even if you do not spend the converted dollars', 'Often worth testing before choosing a target'],
+        ['Taxable investment sale', 'Realized gains can raise MAGI', 'Basis and gain size matter'],
+        ['Part-time wages', 'Usually raise MAGI', 'May still be worth it for cash flow and benefits'],
+        ['Tax-free Roth withdrawal', 'Usually does not raise MAGI', 'Can be useful flexibility when rules are met'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Patel household',
+      assumptions: [
+        { label: 'Ages', value: 'Both spouses are 62, three years before Medicare' },
+        { label: 'Marketplace estimate', value: '$1,350 monthly premium before a $650 credit' },
+        { label: 'Conversion test', value: 'An extra $20,000 Roth conversion cuts the estimated credit to $350 a month' },
+      ],
+      summary:
+        'The conversion may cost more than the income tax alone. In this estimate, the Patels pay tax on the $20,000 conversion and about **$3,600** more for the year of coverage because the credit is smaller.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden lets you enter a full pre-65 monthly premium per person and choose whether to apply the ACA credit. The projection estimates the credit using MAGI and the parameter pack. To avoid circular math, the current model estimates the credit from the prior year\'s MAGI.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Thinking taxable income and ACA MAGI are always the same number.',
+        'Testing Roth conversions without checking healthcare costs.',
+        'Ignoring realized gains in taxable accounts.',
+        'Treating a marketplace subsidy estimate as a final insurance quote or tax filing result.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Spending** to set pre-65 premiums and the ACA credit option. Use **Results** to watch MAGI and healthcare costs by year. Use **Strategy** when conversion targets should avoid a healthcare cliff.',
+    },
+  ],
+}

package/src/learn/content/account-types-overview.ts

@@ -0,0 +1,106 @@
+/**
+ * "Account types: taxable, traditional, Roth, HSA, cash" - an Accounts and Saving P0 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const accountTypesOverviewArticle: LearningArticle = {
+  slug: 'account-types-overview',
+  title: 'Account types: taxable, traditional, Roth, HSA, cash',
+  description: 'How each account is taxed and why the differences matter in retirement.',
+  category: 'accounts-saving',
+  tags: ['accounts', 'taxable brokerage', 'traditional ira', 'roth ira', 'hsa', 'cash', 'tax treatment'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.irs.gov/retirement-plans/roth-iras',
+    'https://www.irs.gov/retirement-plans/retirement-plans-faqs-regarding-iras',
+    'https://www.irs.gov/forms-pubs/about-publication-969',
+    'https://www.irs.gov/taxtopics/tc409',
+    'https://www.irs.gov/forms-pubs/about-publication-550',
+  ],
+  relatedArticles: [
+    'withdrawal-order-basics',
+    'traditional-vs-roth-contributions',
+    'hsas-as-retirement-accounts',
+    'taxable-brokerage-basis-and-capital-gains',
+    'roth-conversion-basics',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/accounts', '/plan/:planId/strategy', '/plan/:planId/results'],
+  currentYearSensitive: true,
+  priority: 'P0',
+  featured: true,
+  blocks: [
+    {
+      type: 'prose',
+      md: 'A retirement plan is easier to understand when every dollar lives in the right bucket. Cash, taxable brokerage, traditional retirement, Roth, and HSA accounts can hold similar investments, but they do not create the same tax result when money goes in, grows, or comes out.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Account type is about tax treatment, not just where the account is held.',
+        'The same investment can behave differently inside a taxable account, traditional account, Roth account, or HSA.',
+        'RetireGolden uses account type to model contributions, withdrawals, gains, RMDs, penalties, and after-tax estate value.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Think of account type as the rules printed on the side of a bucket. Cash is usually simple. Taxable brokerage can create capital gains when investments are sold. Traditional IRA and 401(k) dollars are usually pre-tax, so later withdrawals often become ordinary income. Roth dollars usually trade a tax cost now for tax-free qualified withdrawals later. HSA dollars can be tax-free for qualified medical expenses when the HSA rules are met.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/account-types-overview.webp' },
+      caption:
+        'Each account bucket can feed the same retirement plan, but the tax gate on each bucket is different.',
+      alt: 'Five labeled-style account buckets for cash, taxable, traditional, Roth, and HSA feed a central retirement path through different tax gates.',
+    },
+    {
+      type: 'table',
+      caption: 'A plain-language map of the main account buckets.',
+      columns: ['Account type', 'Main tax idea', 'What RetireGolden needs from you'],
+      rows: [
+        ['Cash', 'Usually no taxable gain when spent', 'Balance, owner if applicable, and return assumption'],
+        ['Taxable brokerage', 'Sales may realize capital gains based on cost basis', 'Balance, aggregate cost basis, contributions, and return assumption'],
+        ['Traditional IRA or 401(k)', 'Contributions may be pre-tax; withdrawals are often ordinary income', 'Balance, owner, account kind, contributions, and inherited/RMD details when relevant'],
+        ['Roth IRA or Roth 401(k)', 'Qualified withdrawals may be tax-free', 'Balance, owner, account kind, contributions, and contribution basis when early access matters'],
+        ['HSA', 'Tax-free for qualified medical expenses when rules are met', 'Balance, owner, contribution amount, and return assumption'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Patel household',
+      assumptions: [
+        { label: 'Cash', value: '$25,000 emergency reserve and near-term spending buffer' },
+        { label: 'Taxable brokerage', value: '$120,000 account with $80,000 of cost basis' },
+        { label: 'Traditional and Roth', value: '$500,000 traditional IRA and $90,000 Roth IRA' },
+      ],
+      summary:
+        'A $20,000 withdrawal from cash is not a tax event. A $20,000 taxable sale realizes about **$6,700** of gain in this simplified basis mix, while a $20,000 traditional IRA withdrawal is ordinary income.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'The Accounts screen stores the type for each balance. The projection engine then uses that type when it applies IRS contribution limits, realizes taxable gains pro-rata from taxable accounts, forces traditional-account RMDs when applicable, tracks Roth basis and conversion layers, and keeps HSA withdrawals last in the default order.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Entering a Roth 401(k) as traditional because it is held at the same employer plan.',
+        'Leaving taxable cost basis at zero when the account has after-tax investment basis.',
+        'Treating cash and taxable brokerage as interchangeable when one may realize gains.',
+        'Forgetting that an inherited traditional account follows different distribution rules than your own traditional IRA.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Start in **Accounts** and classify each balance before you study **Results**. If the tax picture looks surprising, return to Accounts and check whether the type, cost basis, owner, and annual contribution fields match the real account.',
+    },
+  ],
+}

package/src/learn/content/after-tax-estate.ts

@@ -0,0 +1,111 @@
+/**
+ * "After-tax estate value" - an Insurance and Estate P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const afterTaxEstateArticle: LearningArticle = {
+  slug: 'after-tax-estate',
+  title: 'After-tax estate value',
+  description: 'Measuring what heirs actually keep once taxes are paid.',
+  category: 'insurance-estate',
+  tags: ['after-tax estate', 'heirs', 'traditional ira', 'roth', 'estate value', 'optimizer'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'stable',
+  sourceUrls: [],
+  relatedArticles: [
+    'how-the-optimizer-values-after-tax-estate',
+    'beneficiaries-and-account-titling',
+    'step-up-in-basis',
+    'inherited-ira-10-year-rule',
+    'permanent-life-insurance-in-a-plan',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/results', '/plan/:planId/optimize', '/plan/:planId/report'],
+  currentYearSensitive: false,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Net worth is not always the same as what heirs can spend. A dollar left in a traditional IRA may carry future income tax. A dollar left in Roth, cash, or stepped-up taxable property may be more flexible. RetireGolden uses after-tax estate value to compare those buckets more fairly.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'After-tax estate is a planning metric, not a probate or estate-tax calculation.',
+        'RetireGolden subtracts an assumed heir tax on leftover traditional balances.',
+        'The metric helps Roth conversion and claiming strategies compare what heirs may actually keep.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Imagine two households each end with the same net worth. One has mostly Roth and taxable assets. The other has mostly pre-tax traditional retirement accounts. The second household may leave heirs a larger future tax bill, so the two estates are not equally valuable.\n\nAfter-tax estate value is RetireGolden\'s way to adjust for that difference without pretending to model every estate rule.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/after-tax-estate-value.webp' },
+      caption:
+        'After-tax estate value compares the estate after applying an assumed tax haircut to inherited pre-tax balances.',
+      alt: 'An estate stack separates into Roth, taxable, cash, and traditional buckets, with only the traditional bucket passing through a tax gate before reaching heirs.',
+    },
+    {
+      type: 'formula',
+      expression: 'after-tax estate = ending net worth - traditional balance * heir tax rate',
+      where: [
+        { symbol: 'ending net worth', meaning: 'the modeled end-of-plan net worth' },
+        { symbol: 'traditional balance', meaning: 'remaining pre-tax retirement balance' },
+        { symbol: 'heir tax rate', meaning: 'the assumed income-tax rate heirs pay on inherited pre-tax dollars' },
+      ],
+      basis: 'nominal',
+      note: 'This is a simplified comparison metric. It does not model estate tax, probate costs, state inheritance tax, trust rules, or each heir\'s actual tax return.',
+    },
+    { type: 'heading', text: 'How RetireGolden treats buckets' },
+    {
+      type: 'table',
+      caption: 'The estate comparison uses intentionally simple assumptions.',
+      columns: ['Bucket', 'After-tax estate treatment', 'Why'],
+      rows: [
+        ['Traditional', 'Reduced by the heir tax rate', 'Inherited pre-tax dollars often create taxable income for heirs'],
+        ['Roth', 'Kept whole', 'Qualified Roth dollars are usually more tax-flexible'],
+        ['Taxable', 'Kept whole in the comparison', 'The model assumes a basis step-up for estate comparison'],
+        ['Cash, HSA, property', 'Kept whole in the comparison', 'Simplifies the metric so the main pre-tax/Roth trade is visible'],
+        ['Life insurance death benefit', 'Included once paid into the plan', 'The model treats death benefit as income-tax-free at death'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Brooks household',
+      assumptions: [
+        { label: 'Strategy A', value: '$1,000,000 ending net worth, including $600,000 in traditional accounts' },
+        { label: 'Strategy B', value: '$960,000 ending net worth, including more Roth and taxable assets' },
+        { label: 'Heir tax haircut', value: 'A 25% assumed tax on inherited traditional dollars reduces Strategy A by $150,000' },
+      ],
+      summary:
+        'Strategy A looks $40,000 richer before tax, but the $150,000 heir-tax haircut can make Strategy B the larger after-tax estate. The winning column depends on what heirs keep.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden shows after-tax estate in **Results**, **Social Security analysis**, **Optimize**, and **Report**. The projection applies the plan heir-tax rate internally, while **Optimize** exposes a local heir-tax slider so you can test how sensitive a Roth conversion schedule is to that assumption.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Comparing strategies by ending net worth only.',
+        'Assuming the heir tax rate is a fact instead of a sensitivity assumption.',
+        'Reading after-tax estate as a legal estate plan.',
+        'Ignoring beneficiaries, titling, and real-world estate documents because the metric looks tidy.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Optimize** to compare Roth conversion strategies and test the heir-tax sensitivity used for that optimization run. Use **Results** or **Report** to see ending net worth and after-tax estate side by side.',
+    },
+  ],
+}