@retiregolden/planner-ui 0.1.0

package/src/learn/content/moving-to-retiregolden.ts

@@ -0,0 +1,86 @@
+/**
+ * "Moving to RetireGolden" — Using RetireGolden article for the import &
+ * migration wizard (onboarding-import-and-migration step 6).
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const movingToRetireGoldenArticle: LearningArticle = {
+  slug: 'moving-to-retiregolden',
+  title: 'Moving to RetireGolden from another tool',
+  description: 'How the import wizard turns files you already have into a draft plan — and how to leave with your data any time.',
+  category: 'using-retiregolden',
+  tags: ['import', 'migration', 'csv', 'projectionlab', 'broker', 'portability', 'backup'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-07-08',
+  reviewCadence: 'stable',
+  sourceUrls: [],
+  relatedArticles: [
+    'privacy-what-stays-in-your-browser',
+    'planner-overview',
+    'seed-your-plan-from-your-tax-return',
+    'account-types-overview',
+  ],
+  relatedPlannerRoutes: ['/', '/import', '/plan/:planId/accounts'],
+  currentYearSensitive: false,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Retyping a plan you already built somewhere else is the worst part of switching tools. The **Import & migrate** wizard (from the planner home) starts a draft RetireGolden plan from files you already have — and everything is parsed on your device, so no file is ever uploaded anywhere.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Four guided paths: a broker positions CSV (Schwab, Fidelity, Vanguard), a ProjectionLab JSON export, any spreadsheet saved as CSV (including the Bogleheads Retiree Portfolio Model), and last year\'s Form 1040.',
+        'Nothing imports silently: a review checklist shows what mapped, what was assumed for you, and what could not come over.',
+        'Imports create a draft — you review it before saving, and every imported value stays editable like anything you typed.',
+        'Getting out is as supported as getting in: the plan backup is a documented, versioned JSON file.',
+      ],
+    },
+    { type: 'heading', text: 'What each path brings over' },
+    {
+      type: 'table',
+      caption: 'What each import source can and cannot provide.',
+      columns: ['Source', 'What imports', 'What you still enter'],
+      rows: [
+        ['Broker CSV', 'Account balances, cost basis where the file has it, guessed account types', 'Household, income, spending, Social Security'],
+        ['ProjectionLab JSON', 'Accounts, wages and other income, spending total, retirement-age milestone', 'Filing status, state, claim ages, strategies, assumptions'],
+        ['Spreadsheet / RPM CSV', 'One account per row via column mapping (name, type, balance, basis, contribution)', 'Everything except accounts'],
+        ['Form 1040 (guided)', 'Income streams, filing status, state, MAGI context, an estimated taxable balance', 'Spending, real account balances, retirement dates'],
+      ],
+    },
+    { type: 'heading', text: 'The review checklist keeps mapping honest' },
+    {
+      type: 'prose',
+      md: 'Formats differ, so no migration is ever 1:1. Instead of pretending otherwise, every import ends at a checklist with four groups: **Imported** (mapped directly), **Assumed — review** (a default the wizard had to invent, like treating a missing cost basis as "no unrealized gain"), **Not imported** (things the file could not express, with pointers to the right screen), and **Skipped** (unreadable rows). Work through the first two groups before trusting results.',
+    },
+    { type: 'heading', text: 'Updating balances later' },
+    {
+      type: 'prose',
+      md: 'After the first import, you rarely want a whole new plan — just fresh numbers. The Accounts screen has **Update balances from a broker CSV**: download the same positions file at your annual checkup, assign each account in the file to a plan account, and apply. Balances (and cost basis, where present) refresh without retyping.',
+    },
+    { type: 'heading', text: 'And moving out' },
+    {
+      type: 'prose',
+      md: 'Lock-in works both ways, so RetireGolden documents the exit too. **Download plan backup** on the planner home produces a plain JSON file containing every plan in full — a versioned, documented format, and backups made by older versions of the app keep importing through automatic migrations. If you move to another tool someday, your data is already in your hands in a machine-readable form.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Skipping the review checklist — the "Assumed" group is where wrong guesses (account types, cost basis) hide.',
+        'Importing a broker CSV and expecting income or spending — positions files only carry balances.',
+        'Using the import wizard to restore a RetireGolden backup — that lives on the planner home ("Import previous backup").',
+        'Forgetting that a draft is a starting point: results are only as good as the sections you finish afterward.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Open **Import from a file** on the planner home (or go to the Import & migrate page directly). To refresh an existing plan\'s balances, use the panel at the bottom of that plan\'s **Accounts** screen.',
+    },
+  ],
+}

package/src/learn/content/niit-high-income-investment-tax.ts

@@ -0,0 +1,98 @@
+/**
+ * "NIIT and high-income investment tax" - a Taxes P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const niitHighIncomeInvestmentTaxArticle: LearningArticle = {
+  slug: 'niit-high-income-investment-tax',
+  title: 'NIIT and high-income investment tax',
+  description: 'The extra 3.8% tax on investment income above certain thresholds.',
+  category: 'taxes',
+  tags: ['niit', 'net investment income tax', 'capital gains', 'magi', 'high income'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.irs.gov/newsroom/net-investment-income-tax',
+    'https://www.irs.gov/forms-pubs/about-publication-550',
+  ],
+  relatedArticles: [
+    'ordinary-income-vs-capital-gains',
+    'agi-magi-and-taxable-income',
+    'taxable-brokerage-basis-and-capital-gains',
+    'tax-loss-and-gain-harvesting',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/accounts', '/plan/:planId/strategy', '/plan/:planId/results'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'The net investment income tax, often called NIIT, is an extra federal tax that can apply when investment income and modified adjusted gross income are high enough. It is separate from ordinary tax and long-term capital-gain tax.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'NIIT is a 3.8% tax tied to net investment income and MAGI thresholds.',
+        'Realized taxable gains can trigger NIIT even when the capital-gain rate itself looks manageable.',
+        'RetireGolden models NIIT on realized gains as the investment-income piece it currently tracks separately.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Capital gains can face more than one federal layer. First, they stack into the capital-gain brackets. Then, for higher-income households, NIIT can add another 3.8% on the smaller of net investment income or the MAGI amount above the threshold. That extra layer can change the cost of selling taxable investments or harvesting gains.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/niit-high-income-investment-tax.webp' },
+      caption:
+        'NIIT is an added layer that can sit on top of capital-gain tax when MAGI and investment income are high enough.',
+      alt: 'A capital-gain ribbon stacks into a tax tower, then an extra thin investment-tax layer appears above a high-income threshold marker.',
+    },
+    {
+      type: 'formula',
+      expression: 'NIIT = 3.8% x smaller of net investment income or MAGI above the threshold',
+      where: [
+        { symbol: 'net investment income', meaning: 'investment income covered by the NIIT rules' },
+        { symbol: 'MAGI above the threshold', meaning: 'modified adjusted gross income above the filing-status threshold' },
+      ],
+      note: 'RetireGolden currently approximates investment income using realized gains because interest and dividends are not separately tracked in the projection.',
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Shah household',
+      assumptions: [
+        { label: 'Taxable sale', value: '$180,000 stock sale with $70,000 of long-term gain' },
+        { label: 'Other income', value: '$210,000 of pension, wages, and IRA withdrawals already in MAGI' },
+        { label: 'NIIT estimate', value: 'If $30,000 of the gain falls above the threshold, 3.8% adds about $1,140' },
+      ],
+      summary:
+        'The sale is not just a capital-gain-bracket question. The same $70,000 gain can also create a separate **$1,140** NIIT layer when it lands on top of already-high MAGI.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden computes NIIT inside the federal tax detail. In the current model, realized gains are the separately tracked investment-income input. The Results ledger can show when a taxable sale or portfolio withdrawal raises MAGI enough for the NIIT layer to appear.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Looking only at the 0%, 15%, or 20% capital-gain bracket.',
+        'Forgetting that MAGI from pensions, wages, IRA withdrawals, or conversions can help trigger NIIT.',
+        'Assuming NIIT applies to every dollar of income instead of the formula base.',
+        'Expecting RetireGolden to model every category of net investment income separately.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Accounts** to enter taxable cost basis. Use **Strategy** and **Scenarios** to test gain-heavy years, then inspect **Results** for realized gains, MAGI, capital-gain tax, NIIT, and total federal tax.',
+    },
+  ],
+}

package/src/learn/content/ordinary-income-vs-capital-gains.ts

@@ -0,0 +1,103 @@
+/**
+ * "Ordinary income vs capital gains" - a Taxes P0 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const ordinaryIncomeVsCapitalGainsArticle: LearningArticle = {
+  slug: 'ordinary-income-vs-capital-gains',
+  title: 'Ordinary income vs capital gains',
+  description: 'Why two kinds of income are taxed on separate ladders.',
+  category: 'taxes',
+  tags: ['ordinary income', 'capital gains', 'tax brackets', 'taxable brokerage', 'magi'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.irs.gov/filing/federal-income-tax-rates-and-brackets',
+    'https://www.irs.gov/taxtopics/tc409',
+    'https://www.irs.gov/forms-pubs/about-publication-550',
+  ],
+  relatedArticles: [
+    'marginal-vs-effective-tax-rate',
+    'taxable-brokerage-basis-and-capital-gains',
+    'agi-magi-and-taxable-income',
+    'withdrawal-order-basics',
+    'tax-loss-and-gain-harvesting',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/accounts', '/plan/:planId/strategy', '/plan/:planId/results'],
+  currentYearSensitive: true,
+  priority: 'P0',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Ordinary income and long-term capital gains can both raise taxable income, but they do not move through the federal tax system the same way. Ordinary income uses ordinary brackets. Long-term capital gains stack on top and may use preferential capital-gain rates.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Wages, taxable traditional withdrawals, pension income, and many conversions are ordinary income.',
+        'Long-term gains from taxable investments may use a separate 0%, 15%, or 20% federal rate structure.',
+        'Capital gains can still affect MAGI, Social Security taxation, ACA credits, IRMAA, NIIT, and state tax.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'The ordinary-income ladder fills first after deductions. Preferential long-term capital gains then stack on top of ordinary taxable income. That means the same capital gain can land in a lower or higher capital-gain layer depending on how much ordinary income is already in the year.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/ordinary-income-vs-capital-gains.webp' },
+      caption:
+        'Ordinary income fills the first tax ladder, then long-term capital gains stack into their own rate layers above it.',
+      alt: 'An ordinary-income ladder fills from the bottom, while a separate capital-gains ribbon stacks above it through three preferential tax layers.',
+    },
+    {
+      type: 'table',
+      caption: 'Common income types in retirement planning.',
+      columns: ['Income type', 'Usually modeled as', 'Planning note'],
+      rows: [
+        ['Wages, pensions, annuity taxable share', 'Ordinary income', 'Often fills ordinary brackets before portfolio withdrawals'],
+        ['Traditional IRA or 401(k) withdrawals', 'Ordinary income', 'Can raise MAGI and affect brackets, RMDs, and surcharges'],
+        ['Roth conversions', 'Ordinary income', 'Voluntary income that may be timed into lower-bracket years'],
+        ['Taxable brokerage realized long-term gains', 'Capital gains', 'Stacks on top of ordinary income in the federal calculation'],
+        ['Qualified Roth withdrawals', 'Usually outside taxable income', 'Rules matter, especially for early Roth access'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Singh household',
+      assumptions: [
+        { label: 'Ordinary income', value: '$45,000 pension plus a $25,000 traditional IRA withdrawal' },
+        { label: 'Taxable brokerage sale', value: '$30,000 sale with $9,000 of long-term gain' },
+        { label: 'Stacking result', value: 'The IRA withdrawal fills ordinary brackets before the gain uses capital-gain layers' },
+      ],
+      summary:
+        'The $25,000 IRA withdrawal is taxed as ordinary income. Only the **$9,000** gain portion of the brokerage sale goes through capital-gain layers, but both amounts can still raise AGI and MAGI.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden tracks ordinary income and realized gains separately. The federal tax engine applies deductions, ordinary brackets, and long-term capital-gain stacking. The projection also uses AGI and MAGI-style totals for rules such as taxable Social Security, ACA credits, IRMAA, and NIIT.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Assuming capital gains are always tax-free when ordinary income is low.',
+        'Forgetting that capital gains can make more Social Security taxable.',
+        'Ignoring state tax, where gains are often treated more like ordinary income.',
+        'Treating every taxable brokerage withdrawal as a gain instead of separating basis from gain.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Accounts** to enter taxable cost basis and account type correctly. Use **Strategy** to control withdrawals and conversions, then inspect **Results** for ordinary income, realized gains, MAGI, tax, and zero-rate capital-gain headroom.',
+    },
+  ],
+}

package/src/learn/content/paying-conversion-taxes-taxable-vs-ira.ts

@@ -0,0 +1,102 @@
+/**
+ * "Paying conversion taxes from taxable vs IRA dollars" - a Withdrawals and Roth P2 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const payingConversionTaxesTaxableVsIraArticle: LearningArticle = {
+  slug: 'paying-conversion-taxes-taxable-vs-ira',
+  title: 'Paying conversion taxes from taxable vs IRA dollars',
+  description: 'Why where you pay the tax on a conversion changes the outcome.',
+  category: 'withdrawals-roth',
+  tags: ['roth conversion', 'conversion tax', 'taxable account', 'traditional ira', 'roth ira', 'withdrawals'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.irs.gov/retirement-plans/roth-iras',
+    'https://www.irs.gov/retirement-plans/plan-participant-employee/rollovers-of-retirement-plan-and-ira-distributions',
+    'https://www.irs.gov/retirement-plans/retirement-plans-faqs-regarding-iras-distributions-withdrawals',
+  ],
+  relatedArticles: [
+    'roth-conversion-basics',
+    'filling-a-tax-bracket-with-roth-conversions',
+    'why-roth-conversions-raise-other-costs',
+    'withdrawal-order-basics',
+    'how-the-optimizer-values-after-tax-estate',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/strategy', '/plan/:planId/optimize', '/plan/:planId/results'],
+  currentYearSensitive: true,
+  priority: 'P2',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'A Roth conversion creates a tax bill. That tax has to be paid from somewhere. Paying it from cash or taxable assets usually leaves more of the converted retirement dollars inside the Roth, while paying it from the IRA can reduce the amount that stays invested.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'The conversion amount is usually taxable income either way.',
+        'Using taxable dollars for the tax can leave more retirement-account dollars converted to Roth.',
+        'Using IRA dollars for the tax may create extra distribution issues, especially before penalty-free age.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Think of a conversion as moving pre-tax dollars into Roth and then paying the tax cost. If the tax is paid from a separate taxable account, the full converted amount can land in Roth. If the tax is withheld from the IRA distribution, fewer dollars reach Roth, and the withheld amount may be treated as a distribution rather than a conversion.\n\nThat does not mean taxable dollars should always be used. Spending taxable assets has its own opportunity cost and may realize capital gains. The point is to model both paths honestly.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/conversion-tax-source.webp' },
+      caption:
+        'The tax-payment source changes what remains invested: taxable dollars can pay the tax outside the conversion path, while IRA dollars reduce what reaches Roth.',
+      alt: 'Two side-by-side conversion paths move money from a traditional bucket to a Roth bucket. In one path a taxable bucket pays the tax gate separately; in the other the tax gate takes part of the conversion ribbon.',
+    },
+    { type: 'heading', text: 'Two paths to compare' },
+    {
+      type: 'table',
+      caption: 'The conversion tax source changes the shape of the trade.',
+      columns: ['Tax source', 'What happens', 'Main trade-off'],
+      rows: [
+        ['Cash or taxable account', 'Tax is paid outside the converted IRA dollars', 'More reaches Roth, but taxable assets are spent or gains may be realized'],
+        ['Traditional IRA dollars', 'Part of the IRA distribution may pay the tax', 'Less reaches Roth, and extra distribution rules may apply'],
+        ['Roth dollars', 'Usually avoid using Roth to pay conversion tax', 'Spending Roth may defeat part of the reason for converting'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Kim household',
+      assumptions: [
+        { label: 'Conversion goal', value: 'Convert $50,000 from traditional IRA to Roth' },
+        { label: 'Estimated tax', value: '$11,000 due from the conversion year' },
+        { label: 'Comparison', value: 'Pay $11,000 from taxable assets or withhold it from the IRA distribution' },
+      ],
+      summary:
+        'If tax is paid from taxable assets, the full **$50,000** reaches Roth. If tax is withheld from the IRA distribution, only about **$39,000** is converted, but taxable liquidity is preserved.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden models conversion taxes as part of the normal annual cash-flow need. Taxes on conversions ride the withdrawal flow, so cash and taxable assets are used first under the default order. The converted amount itself moves from traditional to Roth and is not reduced for tax withholding inside the conversion transaction.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Comparing conversions without asking where the tax cash comes from.',
+        'Counting the same taxable dollars as both invested and spent on tax.',
+        'Ignoring capital gains created by selling taxable assets to pay the tax.',
+        'Assuming IRA withholding is harmless before checking penalties and how much reaches Roth.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Strategy** for conversion rules, **Accounts** for taxable basis and cash levels, and **Results** to inspect withdrawals, realized gains, tax, Roth balances, and after-tax estate value.',
+    },
+  ],
+}

package/src/learn/content/pensions-and-annuities.ts

@@ -0,0 +1,101 @@
+/**
+ * "Pensions and annuities" - an Accounts and Saving P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const pensionsAndAnnuitiesArticle: LearningArticle = {
+  slug: 'pensions-and-annuities',
+  title: 'Pensions and annuities',
+  description: 'How guaranteed income streams fit into a retirement plan.',
+  category: 'accounts-saving',
+  tags: ['pension', 'annuity', 'guaranteed income', 'cola', 'survivor benefit', 'ordinary income'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.irs.gov/forms-pubs/about-publication-575',
+    'https://www.investor.gov/introduction-investing/investing-basics/investment-products/insurance-products/annuities',
+  ],
+  relatedArticles: [
+    'account-types-overview',
+    'ordinary-income-vs-capital-gains',
+    'planning-for-couples-and-survivor-years',
+    'state-income-taxes-in-retirement',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/accounts', '/plan/:planId/income', '/plan/:planId/results'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'A pension or annuity can change a retirement plan because it pays an income stream instead of sitting in an account balance. The planning question is not only "how much is it worth?" It is also "when does the payment start, how long does it last, how is it taxed, and what happens to a survivor?"',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Guaranteed income can reduce the amount a portfolio must supply each year.',
+        'Pensions and annuities are usually modeled by start age, monthly payment, inflation adjustment, and tax treatment.',
+        'Survivor benefits, taxable share, and cost-of-living adjustments can matter more than the headline monthly amount.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'A portfolio withdrawal is flexible: you choose how much to draw, and the account balance changes. A pension or annuity is different. It creates a scheduled payment that may arrive for life, for a term, or under contract-specific rules. In a plan, that income can cover part of the spending target before the withdrawal order starts selling investments.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/pensions-annuities.webp' },
+      caption:
+        'Pensions and annuities add scheduled income streams that can reduce how much the portfolio must cover.',
+      alt: 'Two steady income ribbons from a pension column and an annuity contract flow into a retirement spending path before the portfolio bucket is tapped.',
+    },
+    {
+      type: 'table',
+      caption: 'Inputs that shape a guaranteed-income stream.',
+      columns: ['Input', 'What it changes', 'Planning question'],
+      rows: [
+        ['Start age', 'The first year payments appear', 'Does the income arrive before or after the portfolio bridge years?'],
+        ['Monthly amount', 'The baseline annual income', 'How much spending does it cover before withdrawals?'],
+        ['Cost-of-living adjustment', 'Whether payments grow over time', 'Does the stream keep up with inflation or shrink in buying power?'],
+        ['Survivor benefit', 'What remains after the owner dies', 'Can the surviving spouse still cover fixed costs?'],
+        ['Taxable share', 'How much annuity income is ordinary income in the model', 'Is the contract fully taxable or partly return of basis?'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Rivera household',
+      assumptions: [
+        { label: 'Pension', value: '$2,500 per month starting at 65 with a survivor percentage' },
+        { label: 'Annuity', value: '$900 per month starting at 70 with a taxable-share estimate' },
+        { label: 'Portfolio role', value: 'Guaranteed income adds $40,800 a year once both streams are active' },
+      ],
+      summary:
+        'Once both streams are active, the portfolio has **$40,800** less annual spending to cover before taxes. The survivor setting tests whether that gap reopens after one death.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden lets you add pension and annuity accounts on **Accounts**. Pension income is modeled as ordinary income once payments start, with an optional survivor percentage. Annuity income is modeled while the owner is alive, and the taxable share controls how much of the payment enters ordinary income. Both can have a cost-of-living adjustment.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Entering only the monthly payment and ignoring whether it grows with inflation.',
+        'Assuming a pension continues at the same amount for the survivor when the plan has a reduced survivor option.',
+        'Treating every annuity payment as fully taxable when part may represent return of basis, or the reverse.',
+        'Comparing an annuity to a portfolio without considering liquidity, fees, guarantees, and insurer risk.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Accounts** to add pensions and annuities. Then use **Results** to inspect pension income, annuity income, ordinary income, taxes, and the spending gap before and after those streams begin.',
+    },
+  ],
+}

package/src/learn/content/permanent-life-insurance-in-a-plan.ts

@@ -0,0 +1,106 @@
+/**
+ * "Permanent life insurance in a retirement plan" - an Insurance and Estate P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const permanentLifeInsurancePlanArticle: LearningArticle = {
+  slug: 'permanent-life-insurance-in-a-plan',
+  title: 'Permanent life insurance in a retirement plan',
+  description: 'How cash-value life insurance interacts with a retirement plan.',
+  category: 'insurance-estate',
+  tags: ['permanent life insurance', 'whole life', 'cash value', 'death benefit', 'estate'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'rule-change',
+  sourceUrls: [
+    'https://www.irs.gov/faqs/interest-dividends-other-types-of-income/life-insurance-disability-insurance-proceeds/life-insurance-disability-insurance-proceeds-1',
+    'https://www.irs.gov/publications/p525',
+  ],
+  relatedArticles: [
+    'after-tax-estate',
+    'beneficiaries-and-account-titling',
+    'survivor-planning-for-couples',
+    'long-term-care-insurance-as-risk-transfer',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/insurance', '/plan/:planId/results'],
+  currentYearSensitive: false,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Permanent life insurance combines an insurance death benefit with a cash-value component. In a retirement plan, that makes it different from term life insurance, which is mostly pure protection for a period of years.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'The premium is a spending drag while the policy is active.',
+        'Cash value can count as an asset while the insured is alive.',
+        'The death benefit can protect a survivor or estate, but RetireGolden uses a planning-level policy model, not a policy illustration engine.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Permanent life can play several roles: survivor protection, estate liquidity, a conservative asset-like cash value, or a legacy tool. Those roles should be separated. A policy that is useful for survivor protection may not be attractive as an investment. A policy with strong cash value may still be expensive if premiums crowd out other saving.\n\nThe planning question is not "Is permanent life good or bad?" It is "What job is this policy doing in this household, and what does it cost?"',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/permanent-life-insurance-plan.webp' },
+      caption:
+        'Permanent life insurance has two modeled paths: cash value while living and a death benefit when the insured dies.',
+      alt: 'A policy container splits into a growing cash-value path during life and a shielded death-benefit path at the insured death point.',
+    },
+    {
+      type: 'table',
+      caption: 'Permanent life inputs in a planning model.',
+      columns: ['Input', 'What it represents', 'Planning caution'],
+      rows: [
+        ['Annual premium', 'The cost of keeping the policy in force', 'Premiums reduce cash flow even if no claim occurs soon'],
+        ['Cash value', 'Policy value while the insured is alive', 'Actual values depend on the policy illustration and contract'],
+        ['Cash-value schedule', 'Age-by-age policy values from an illustration', 'Usually better than assuming a flat growth rate'],
+        ['Death benefit', 'Amount paid at death in the model', 'Real-world tax and estate details can depend on ownership and beneficiary structure'],
+        ['Beneficiary', 'Estate or another person in the plan', 'RetireGolden does not model trusts, probate, or estate tax'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Wallace household',
+      assumptions: [
+        { label: 'Policy purpose', value: '$300,000 death benefit if the higher earner dies first' },
+        { label: 'Cost', value: '$6,000 level annual premium paid for life' },
+        { label: 'Asset side', value: '$85,000 current cash value growing from the policy illustration' },
+      ],
+      summary:
+        'The same policy both costs and supports the plan: $6,000 leaves cash flow each year, while $85,000 of cash value and a $300,000 death benefit can support estate or survivor outcomes.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden models permanent life on the **Insurance** screen. Premiums are level nominal costs. Cash value can grow at a flat rate or follow an age-by-age schedule. In the insured person\'s death year, the model pays the larger of the death benefit or cash value into the plan and zeroes the cash value so it is not counted twice.',
+    },
+    {
+      type: 'callout',
+      tone: 'note',
+      md: 'Model note: RetireGolden does not model policy loans, surrender charges, dividends, modified endowment contract rules, trust ownership, estate tax, or premium funding strategies. Use it to understand plan-level cash flows, not to evaluate a specific policy contract.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Treating cash value as liquid cash without considering policy rules.',
+        'Forgetting the premium drag in no-claim years.',
+        'Counting both cash value and death benefit at death.',
+        'Using a flat growth rate when an actual illustration schedule is available.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Insurance** to enter permanent life policies, cash value, death benefit, premium mode, and beneficiary. Use **Results** to see insurance premiums in the spending chart, and download the **Results CSV** when you need year-by-year insurance cash value and death benefit columns.',
+    },
+  ],
+}