@retiregolden/planner-ui 0.1.0

package/src/learn/content/state-income-taxes-in-retirement.ts

@@ -0,0 +1,97 @@
+/**
+ * "State income taxes in retirement" - a Taxes P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const stateIncomeTaxesRetirementArticle: LearningArticle = {
+  slug: 'state-income-taxes-in-retirement',
+  title: 'State income taxes in retirement',
+  description: 'How state rules on retirement income vary and why they matter.',
+  category: 'taxes',
+  tags: ['state tax', 'retirement income', 'capital gains', 'social security', 'state residence'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'annual',
+  sourceUrls: ['https://www.irs.gov/filing/state-government-websites'],
+  relatedArticles: [
+    'ordinary-income-vs-capital-gains',
+    'how-social-security-is-taxed',
+    'tax-cliffs-and-bracket-edges',
+    'real-estate-home-equity-and-debt',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/household', '/plan/:planId/assumptions', '/plan/:planId/results'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Federal tax gets most of the attention, but state income tax can change the after-tax value of withdrawals, pensions, Social Security, capital gains, and a possible move. Two households with the same federal plan can see different results because they live in different states.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Some states have no broad income tax, while others tax retirement income in different ways.',
+        'State rules can treat Social Security, pensions, IRA withdrawals, and capital gains differently from federal rules.',
+        'RetireGolden uses state parameter packs when available and lets you enter a flat override when your situation needs a manual correction.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'State income tax is not just a smaller version of federal tax. A state may exempt Social Security, offer a retirement-income exclusion, tax capital gains as ordinary income, use different deductions, or have no income tax at all. Moving in retirement can also change which rules apply in later years.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/state-income-taxes-retirement.webp' },
+      caption:
+        'The same retirement income stream can pass through different state tax filters depending on where the household lives.',
+      alt: 'A retirement income ribbon splits through several state-shaped tax filters, with some paths narrowing and others passing through mostly unchanged.',
+    },
+    {
+      type: 'table',
+      caption: 'State tax questions to check before relying on a result.',
+      columns: ['Question', 'Why it matters', 'RetireGolden lens'],
+      rows: [
+        ['Does the state tax retirement income?', 'Pensions and IRA withdrawals may not all be treated the same', 'Modeled retirement-income exclusions where available'],
+        ['Does the state tax Social Security?', 'Federal taxable benefits may not match state treatment', 'State pack determines whether taxable benefits are included'],
+        ['How are gains treated?', 'Many states tax capital gains like ordinary income', 'State pack setting for capital gains as ordinary income'],
+        ['Will you move?', 'Later years may use different rules', 'Household residence by year and plan assumptions'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Garcia household',
+      assumptions: [
+        { label: 'Current state', value: 'About $4,800 of state tax on IRA withdrawals and gains' },
+        { label: 'Possible move', value: 'Move near family at age 68, reducing state tax by about $3,200 a year' },
+        { label: 'Other cost change', value: 'Housing and insurance rise by about $2,400 a year in the new location' },
+      ],
+      summary:
+        'The move is not a pure $3,200 tax win. After the $2,400 cost increase, the plan improves by only about **$800** a year before considering lifestyle and family reasons.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden combines the federal tax calculator with a state tax calculator. The state model starts from ordinary income, capital gains when the state taxes gains as ordinary, and federally taxable Social Security when the state taxes Social Security. It then applies major retirement-income exclusions, state standard deductions, and brackets from the state pack. A flat effective-rate override in **Assumptions** takes precedence when you need a manual approximation.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Assuming state tax follows federal taxable income exactly.',
+        'Forgetting that a no-income-tax state may still have property tax, sales tax, insurance, or housing tradeoffs.',
+        'Modeling a move only as a tax change without changing spending and property assumptions.',
+        'Treating a planning pack as a state tax return. Always verify unusual facts with state guidance or a tax professional.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Household** and **Assumptions** to set residence and any state-tax override. Use **Scenarios** to compare a move, then inspect **Results** for state tax, total tax, spending, and ending assets.',
+    },
+  ],
+}

package/src/learn/content/step-up-in-basis.ts

@@ -0,0 +1,102 @@
+/**
+ * "Step-up in basis" - an Insurance and Estate P2 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const stepUpInBasisArticle: LearningArticle = {
+  slug: 'step-up-in-basis',
+  title: 'Step-up in basis',
+  description: 'How inherited investments can reset their taxable cost basis.',
+  category: 'insurance-estate',
+  tags: ['step-up in basis', 'cost basis', 'taxable brokerage', 'inheritance', 'capital gains'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'rule-change',
+  sourceUrls: ['https://www.irs.gov/publications/p551', 'https://www.irs.gov/publications/p559'],
+  relatedArticles: [
+    'taxable-brokerage-basis-and-capital-gains',
+    'after-tax-estate',
+    'beneficiaries-and-account-titling',
+    'ordinary-income-vs-capital-gains',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/accounts', '/plan/:planId/results', '/plan/:planId/report'],
+  currentYearSensitive: true,
+  priority: 'P2',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Cost basis is the tax starting point for measuring capital gain or loss. A step-up in basis means an inherited asset may get a new basis tied to its value around the owner\'s death, reducing the gain an heir would report if they sell soon after inheriting.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'A step-up can make taxable brokerage assets more estate-friendly than their embedded gain suggests.',
+        'Step-up rules are different from traditional IRA inheritance rules.',
+        'RetireGolden uses a simplified step-up assumption in its after-tax estate comparison.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'If you bought an investment for less than it is worth today, selling it during life can create capital gain. If heirs inherit that investment and receive a stepped-up basis, the old unrealized gain may not follow them in the same way.\n\nThat distinction matters when comparing lifetime tax moves. Selling appreciated taxable assets during life is not the same as leaving them to heirs. Converting a traditional IRA is not the same as leaving taxable stock. Each bucket has a different tax shape.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/step-up-in-basis.webp' },
+      caption:
+        'A basis step-up can reset the tax starting line for inherited taxable assets, while pre-tax retirement accounts keep a different tax character.',
+      alt: 'An appreciated taxable asset path reaches an inheritance checkpoint where the basis line resets upward, while a traditional account path continues through an income-tax gate.',
+    },
+    {
+      type: 'table',
+      caption: 'Step-up is one reason account type matters for heirs.',
+      columns: ['Asset type', 'Common heir tax lens', 'RetireGolden simplification'],
+      rows: [
+        ['Taxable brokerage', 'Basis may reset at inheritance under step-up rules', 'Kept whole in the after-tax estate metric'],
+        ['Traditional IRA or 401(k)', 'Heirs may owe income tax on distributions', 'Reduced by the heir tax rate'],
+        ['Roth', 'Often more tax-flexible for heirs when qualified', 'Kept whole in the estate comparison'],
+        ['Property', 'May involve basis, sale costs, and local law', 'Modeled at projected net value, not detailed estate tax basis'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Allen household',
+      assumptions: [
+        { label: 'Taxable account', value: '$250,000 brokerage account with $140,000 of cost basis' },
+        { label: 'During life sale', value: 'A full sale would realize about $110,000 of capital gain' },
+        { label: 'Inherited asset', value: 'A step-up could reset basis near the date-of-death value' },
+      ],
+      summary:
+        'During life, the embedded gain is about **$110,000**. As an inheritance, the taxable account may avoid that same gain layer, unlike a same-size traditional IRA that remains taxable to heirs.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden tracks cost basis for taxable brokerage accounts during the projection, so lifetime sales can realize gains. For the after-tax estate metric, it uses a simplified assumption that taxable assets pass through without the same heir income-tax haircut applied to traditional balances.',
+    },
+    {
+      type: 'callout',
+      tone: 'warn',
+      md: 'Step-up rules can depend on ownership, state law, community property rules, estate structure, and law changes. RetireGolden does not replace estate or tax advice.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Treating taxable brokerage and traditional IRA dollars as equally taxable to heirs.',
+        'Assuming step-up applies to every asset or every transfer.',
+        'Selling highly appreciated assets during life without comparing the estate tradeoff.',
+        'Using RetireGolden\'s simplified estate metric as a legal estate plan.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Accounts** to enter taxable cost basis. Use **Results** to inspect realized gains during life, and use **Report** or **Optimize** to compare ending net worth with after-tax estate value.',
+    },
+  ],
+}

package/src/learn/content/survivor-planning-for-couples.ts

@@ -0,0 +1,110 @@
+/**
+ * "Survivor planning for couples" - an Insurance and Estate P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const survivorPlanningForCouplesArticle: LearningArticle = {
+  slug: 'survivor-planning-for-couples',
+  title: 'Survivor planning for couples',
+  description: 'Making sure the surviving spouse is financially secure.',
+  category: 'insurance-estate',
+  tags: ['survivor planning', 'couples', 'life insurance', 'social security', 'widow penalty', 'beneficiaries'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.ssa.gov/benefits/survivors/',
+    'https://www.irs.gov/forms-pubs/about-publication-501',
+    'https://www.irs.gov/filing/federal-income-tax-rates-and-brackets',
+  ],
+  relatedArticles: [
+    'planning-for-couples-and-survivor-years',
+    'widows-penalty-and-survivor-brackets',
+    'spousal-and-survivor-benefits',
+    'permanent-life-insurance-in-a-plan',
+    'beneficiaries-and-account-titling',
+  ],
+  relatedPlannerRoutes: [
+    '/plan/:planId/household',
+    '/plan/:planId/social-security',
+    '/plan/:planId/insurance',
+    '/plan/:planId/survivor',
+    '/plan/:planId/results',
+    '/plan/:planId/report',
+  ],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Survivor planning asks whether the plan still works after the first spouse dies. It is not only about life insurance. It includes Social Security, pensions, account ownership, beneficiaries, taxes, spending, healthcare, and how easy the plan is for one person to manage.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'The surviving spouse may keep less income but still carry many fixed expenses.',
+        'Social Security claiming can affect the survivor income floor.',
+        'Insurance and beneficiary choices should be tested against the survivor years, not only the couple years.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'A couple plan can look strong while both people are alive because two Social Security checks, two pensions, or two work histories support one household. After the first death, income may fall and tax brackets may narrow. The survivor may also have less capacity or desire to manage a complex withdrawal strategy.\n\nGood survivor planning turns that vague worry into a checklist: income floor, tax shape, liquidity, insurance, beneficiaries, and simplicity.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/survivor-planning-couples.webp' },
+      caption:
+        'Survivor planning follows the plan after one spouse dies, checking income, tax, liquidity, and protection for the remaining spouse.',
+      alt: 'A couple retirement path splits after one spouse dies, with the survivor path supported by Social Security, insurance, liquidity, and beneficiary markers.',
+    },
+    {
+      type: 'table',
+      caption: 'A practical survivor-planning checklist.',
+      columns: ['Area', 'Question', 'RetireGolden lens'],
+      rows: [
+        ['Income floor', 'What income continues after the first death?', 'Social Security, pensions, annuities, wages'],
+        ['Taxes', 'Does the survivor face narrower brackets?', 'Filing status, RMDs, MAGI, after-tax estate'],
+        ['Liquidity', 'Can the survivor pay near-term bills without forced sales?', 'Cash, taxable accounts, withdrawal order'],
+        ['Insurance', 'Does a death benefit or LTC policy protect the weak point?', 'Permanent life, LTC stress test'],
+        ['Beneficiaries', 'Will assets reach the intended person efficiently?', 'Account ownership and policy beneficiary fields'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Nguyen household',
+      assumptions: [
+        { label: 'Higher earner', value: '$3,100 monthly Social Security benefit and a $250,000 life policy' },
+        { label: 'Survivor risk', value: 'The surviving spouse keeps the house and about 75% of spending' },
+        { label: 'Policy cost', value: '$4,000 annual premium lowers couple-year cash flow' },
+      ],
+      summary:
+        'The policy costs $4,000 a year while both are alive, but the $250,000 death benefit can protect survivor years when one Social Security check stops and tax brackets narrow.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden continues the projection through each person\'s planning age. It models the Social Security survivor step-up, survivor filing status, insurance premiums and death benefits, account ownership, and spending through the later years. That makes survivor years visible in **Results** and **Report**.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Stopping the analysis when the first spouse dies.',
+        'Assuming one spouse\'s death cuts spending by half.',
+        'Ignoring the survivor effect when deciding Social Security claiming ages.',
+        'Treating beneficiary forms as paperwork instead of part of the plan.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Household** for planning ages, **Social Security** for benefits and claiming, **Insurance** for life and LTC protection, and **Results** to read the survivor years after the first death.',
+    },
+  ],
+}

package/src/learn/content/survivor-spending-in-couple-plans.ts

@@ -0,0 +1,98 @@
+/**
+ * "Survivor spending in couple plans" - a Using RetireGolden P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const survivorSpendingInCouplePlansArticle: LearningArticle = {
+  slug: 'survivor-spending-in-couple-plans',
+  title: 'Survivor spending in couple plans',
+  description: 'How the survivor spending percentage changes recurring lifestyle costs after the first death.',
+  category: 'using-retiregolden',
+  tags: ['survivor', 'couples', 'spending', 'widow penalty', 'budget'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-07-06',
+  reviewCadence: 'rule-change',
+  sourceUrls: [
+    'https://www.ssa.gov/benefits/survivors/',
+    'https://www.irs.gov/filing/federal-income-tax-rates-and-brackets',
+    'https://www.bls.gov/cex/',
+  ],
+  relatedArticles: [
+    'planning-for-couples-and-survivor-years',
+    'survivor-planning-for-couples',
+    'widows-penalty-and-survivor-brackets',
+    'spousal-and-survivor-benefits',
+    'building-a-retirement-spending-budget',
+  ],
+  relatedPlannerRoutes: [
+    '/plan/:planId/spending',
+    '/plan/:planId/household',
+    '/plan/:planId/insurance',
+    '/plan/:planId/survivor',
+    '/plan/:planId/results',
+    '/plan/:planId/scenarios',
+  ],
+  currentYearSensitive: false,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'A couple plan can look strong while both spouses are alive and still deserve a separate survivor-year check. Income often falls, filing status may change, and household costs usually do not fall in half.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Survivor spending applies only in years when exactly one spouse is alive.',
+        'It scales baseline spending and phase-adjusted lifestyle spending, not every cost in the ledger.',
+        'One-time goals, healthcare premiums, debt payments, property costs, and insurance premiums keep their own schedules.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'The survivor spending field answers a practical question: what share of the couple lifestyle budget would one spouse still need? A value of 100% means no change. A value of 75% means the recurring lifestyle portion falls by one quarter in survivor years.\n\nThis is separate from Social Security survivor benefits, tax filing status, pensions, insurance, and healthcare. RetireGolden models those items through their own inputs so the survivor percentage does not double-count them.',
+    },
+    {
+      type: 'table',
+      caption: 'What survivor spending changes.',
+      columns: ['Cost type', 'Scaled by survivor spending?', 'Why'],
+      rows: [
+        ['Baseline lifestyle spending', 'Yes', 'It is the recurring household lifestyle budget'],
+        ['Spending phases', 'Yes', 'The phase multiplier applies first, then the survivor percentage scales the result'],
+        ['One-time goals', 'No', 'A named goal happens on its own schedule unless you edit or remove it'],
+        ['Healthcare premiums', 'No', 'Healthcare is per-person or rule-driven elsewhere in the model'],
+        ['Debt, property, and insurance costs', 'No', 'Those costs follow the account or policy inputs you entered'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Moreno household',
+      assumptions: [
+        { label: 'Couple baseline spending', value: '$88,000 per year in today\'s dollars' },
+        { label: 'Survivor spending setting', value: '75%' },
+        { label: 'Survivor-year lifestyle spending', value: '$66,000 before inflation and before separate costs' },
+        { label: 'Still separate', value: 'Medicare, property tax, debt service, and a planned car replacement' },
+      ],
+      summary:
+        'The survivor setting lowers the recurring lifestyle budget, but the ledger still includes separate costs that may not fall just because one person has died.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Assuming one-person spending should be exactly 50% of couple spending.',
+        'Lowering survivor spending and also manually removing costs that RetireGolden already stops or changes elsewhere.',
+        'Forgetting that a surviving spouse may face smaller Social Security income and different tax brackets at the same time.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Spending** to set the survivor percentage. Use **Results** to inspect survivor years in the ledger, and use **Scenarios** if you want to compare 100%, 80%, and 70% survivor-spending assumptions before deciding what belongs in the base plan.',
+    },
+  ],
+}

package/src/learn/content/tax-cliffs-and-bracket-edges.ts

@@ -0,0 +1,105 @@
+/**
+ * "Tax cliffs and bracket edges" - a Taxes P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const taxCliffsBracketEdgesArticle: LearningArticle = {
+  slug: 'tax-cliffs-and-bracket-edges',
+  title: 'Tax cliffs and bracket edges',
+  description: 'Where one more dollar of income triggers an outsized cost.',
+  category: 'taxes',
+  tags: ['tax cliffs', 'tax brackets', 'magi', 'irmaa', 'aca', 'social security taxation'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.irs.gov/filing/federal-income-tax-rates-and-brackets',
+    'https://www.irs.gov/affordable-care-act/individuals-and-families/the-premium-tax-credit-the-basics',
+    'https://www.medicare.gov/basics/costs/medicare-costs',
+    'https://www.healthcare.gov/income-and-household-information/income/',
+  ],
+  relatedArticles: [
+    'why-small-tax-cliffs-can-matter',
+    'marginal-vs-effective-tax-rate',
+    'why-roth-conversions-raise-other-costs',
+    'irmaa-two-year-lookback',
+    'aca-premium-tax-credits-and-magi',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/strategy', '/plan/:planId/optimize', '/plan/:planId/results'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'A bracket edge is where the next dollars of taxable income enter a higher marginal bracket. A cliff is harsher: crossing a threshold can change a premium, credit, surcharge, or taxable-benefit calculation. Retirement planning has both.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Higher tax brackets usually apply only to the next slice of taxable income.',
+        'Some rules behave more like steps, where a little extra MAGI can change a larger cost.',
+        'Good planning tests the years near an edge instead of assuming the optimizer target is the whole answer.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Edges are not automatically bad. Filling a low bracket with Roth conversions can be wise if it avoids larger RMDs later. Harvesting gains in a low-income year can also make sense. The goal is to know what else moves when income rises: Social Security taxation, ACA credits, Medicare IRMAA, NIIT, state tax, and capital-gain layers.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/tax-cliffs-bracket-edges.webp' },
+      caption:
+        'Bracket edges are slopes; cliff-like thresholds can add ledges that deserve extra testing.',
+      alt: 'A retirement income path climbs a stepped tax landscape with smooth bracket slopes, sudden ledges, and small warning markers near thresholds.',
+    },
+    {
+      type: 'table',
+      caption: 'Common edges to inspect in a retirement projection.',
+      columns: ['Edge or cliff', 'Income measure', 'What to inspect'],
+      rows: [
+        ['Ordinary bracket edge', 'Taxable income', 'Ordinary tax on withdrawals, pensions, and conversions'],
+        ['Capital-gain layer', 'Taxable income after ordinary income stacks first', '0%, 15%, and 20% gain-room interactions'],
+        ['Social Security taxation', 'Provisional-income style formula', 'Taxable benefit share as other income rises'],
+        ['ACA credit change', 'Marketplace income measure', 'Net pre-65 healthcare premium'],
+        ['IRMAA tier', 'MAGI with a two-year lookback', 'Later Medicare Part B and Part D premiums'],
+        ['NIIT threshold', 'MAGI and investment income', 'Extra 3.8% investment-income layer'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Ellis household',
+      assumptions: [
+        { label: 'Plan', value: 'Convert $45,000 of traditional IRA dollars up to a federal bracket edge' },
+        { label: 'Second edge', value: 'A $50,000 conversion may cross an IRMAA-style premium tier two years later' },
+        { label: 'Comparison', value: '$45,000 conversion saves future RMD tax; $50,000 conversion adds about $900 of later premium' },
+      ],
+      summary:
+        'The extra $5,000 conversion is not automatically bad, but its price is not just federal tax. The comparison needs the bracket result plus the roughly **$900** delayed premium effect.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden shows annual MAGI, taxable income, ordinary tax, capital-gain tax, NIIT, healthcare costs, and Social Security taxation in the projection. The Roth optimizer can find useful conversion targets, but the Results ledger is where you inspect whether an income-sensitive edge was crossed.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Calling every bracket edge a cliff.',
+        'Avoiding every threshold without measuring the lifetime benefit of crossing it.',
+        'Checking federal tax but not healthcare, state tax, or taxable Social Security.',
+        'Forgetting the IRMAA lookback when testing conversions before or during Medicare years.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Strategy**, **Optimize**, and **Scenarios** to test nearby income levels. Use **Results** to compare the year of the income event and the following years when delayed effects can appear.',
+    },
+  ],
+}

package/src/learn/content/tax-loss-and-gain-harvesting.ts

@@ -0,0 +1,99 @@
+/**
+ * "Tax-loss harvesting and gain harvesting" - a Taxes P2 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const taxLossGainHarvestingArticle: LearningArticle = {
+  slug: 'tax-loss-and-gain-harvesting',
+  title: 'Tax-loss harvesting and gain harvesting',
+  description: 'Deliberately realizing losses or gains to manage lifetime tax.',
+  category: 'taxes',
+  tags: ['tax-loss harvesting', 'gain harvesting', 'capital gains', 'cost basis', 'wash sale', 'taxable brokerage'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.irs.gov/taxtopics/tc409',
+    'https://www.irs.gov/forms-pubs/about-publication-550',
+  ],
+  relatedArticles: [
+    'taxable-brokerage-basis-and-capital-gains',
+    'ordinary-income-vs-capital-gains',
+    'niit-high-income-investment-tax',
+    'tax-cliffs-and-bracket-edges',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/accounts', '/plan/:planId/strategy', '/plan/:planId/results'],
+  currentYearSensitive: true,
+  priority: 'P2',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Harvesting means deliberately realizing a tax result instead of waiting for a sale to happen by accident. Tax-loss harvesting realizes losses that may offset gains or other income under the rules. Gain harvesting realizes gains in a year when the tax cost may be low enough to be worth locking in.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Tax-loss harvesting can create useful losses, but wash-sale and replacement-investment rules matter.',
+        'Gain harvesting can use low-income years or 0% capital-gain room to reset basis.',
+        'RetireGolden estimates realized gains from taxable withdrawals and reports zero-rate gain headroom; it does not choose tax lots or execute harvesting trades.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'A taxable account contains basis and unrealized gain or loss. Harvesting changes the tax record by selling something. If you sell at a loss, the loss may offset gains and potentially a limited amount of other income. If you sell at a gain in a low-tax year, you may increase basis and reduce future gain. Both strategies depend on current law, holding period, tax lots, state tax, and what you buy next.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/tax-loss-gain-harvesting.webp' },
+      caption:
+        'Harvesting chooses when gains or losses leave the taxable account instead of letting tax timing happen by accident.',
+      alt: 'A taxable account splits into two planned harvest paths, one collecting a loss leaf and one collecting a gain tile, before both rejoin a future basis path.',
+    },
+    {
+      type: 'table',
+      caption: 'Two different harvesting goals.',
+      columns: ['Strategy', 'Typical goal', 'Planning caution'],
+      rows: [
+        ['Tax-loss harvesting', 'Use losses to offset gains or create a deduction under limits', 'Wash-sale and replacement rules can undo the intended tax result'],
+        ['Gain harvesting', 'Realize gains in a low-tax year and increase basis', 'The gain can still raise MAGI, taxable Social Security, ACA costs, IRMAA, NIIT, or state tax'],
+        ['Do nothing', 'Keep tax deferral and avoid transaction complexity', 'Future sales may happen in a higher-tax year'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Kim household',
+      assumptions: [
+        { label: 'Harvested loss', value: '$12,000 loss from selling one taxable fund lot' },
+        { label: 'Realized gain', value: '$8,000 long-term gain from rebalancing another holding' },
+        { label: 'Leftover loss', value: '$4,000 remains after offsetting the gain; about $3,000 can offset ordinary income' },
+      ],
+      summary:
+        'The loss does not create $12,000 of immediate tax savings. It first wipes out the $8,000 gain, then about **$3,000** can reduce ordinary income this year, leaving roughly **$1,000** to carry forward.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden models taxable and equity-comp withdrawals using aggregate cost basis, so realized gains appear when those accounts are sold for spending. The federal tax detail also calculates advisory 0% long-term capital-gain headroom. RetireGolden does not model individual tax lots, wash sales, short-term gain timing, or broker-level harvesting transactions.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Harvesting a loss and accidentally creating a wash sale.',
+        'Harvesting gains because the federal rate is low while ignoring ACA, IRMAA, NIIT, state tax, or Social Security taxation.',
+        'Assuming a modeled average cost basis can replace tax-lot records.',
+        'Letting tax savings drive an investment change that no longer fits the portfolio plan.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Accounts** to keep taxable basis realistic. Use **Results** to inspect realized gains and zero-rate gain headroom. Use **Scenarios** or one-time capital-gain inputs to approximate a planned harvest year, then verify the real transaction details outside the planner.',
+    },
+  ],
+}