@retiregolden/planner-ui 0.1.0

package/src/learn/content/social-security-claiming-age-basics.ts

@@ -0,0 +1,113 @@
+/**
+ * "Social Security claiming age basics" - a Social Security P0 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const socialSecurityClaimingAgeArticle: LearningArticle = {
+  slug: 'social-security-claiming-age-basics',
+  title: 'Social Security claiming age basics',
+  description: 'How the age you claim changes your monthly benefit for life.',
+  category: 'social-security',
+  tags: ['social security', 'claiming age', 'full retirement age', 'delayed credits', 'retirement benefit'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-19',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.ssa.gov/benefits/retirement/planner/agereduction.html',
+    'https://www.ssa.gov/benefits/retirement/planner/delayret.html',
+  ],
+  relatedArticles: [
+    'pia-aime-and-bend-points',
+    'break-even-useful-lens',
+    'spousal-and-survivor-benefits',
+    'cola-and-inflation-protection',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/social-security', '/plan/:planId/social-security-analysis'],
+  currentYearSensitive: true,
+  priority: 'P0',
+  featured: true,
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Your Social Security claiming age is the age you start retirement benefits. It does not change the work record that created your benefit, but it does change the monthly check built from that record.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Claiming before full retirement age starts checks sooner, but with a permanent monthly reduction.',
+        'Claiming at full retirement age gives your base retirement benefit, also called your primary insurance amount.',
+        'Waiting after full retirement age can add delayed retirement credits until age 70.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Social Security has a timing tradeoff. An earlier claim can help cash flow now. A later claim can raise the monthly benefit for the rest of your life.\n\nThat tradeoff is not only about one person living to a certain age. Taxes, portfolio withdrawals, Roth conversions, survivor years, and inflation protection can all change which claiming age fits the full plan.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/social-security-claiming-age.webp' },
+      caption:
+        'Claiming age trades smaller checks sooner against larger checks later, with full retirement age as the base checkpoint.',
+      alt: 'A timeline with three gates showing early, base, and later claiming choices, where the later path produces a larger benefit stream.',
+    },
+    { type: 'heading', text: 'Before, at, and after full retirement age' },
+    {
+      type: 'table',
+      caption: 'How claiming age changes the retirement benefit.',
+      columns: ['Claim timing', 'What happens', 'Planning question'],
+      rows: [
+        [
+          'Before full retirement age',
+          'Checks begin sooner, but the monthly benefit is reduced.',
+          'Do you need income now, and what does the smaller lifetime check cost later?',
+        ],
+        [
+          'At full retirement age',
+          'The monthly benefit equals the base benefit from your earnings record.',
+          'Is the base check a good balance between current cash flow and later protection?',
+        ],
+        [
+          'After full retirement age',
+          'Delayed credits raise the monthly benefit until age 70.',
+          'Can the portfolio bridge the gap, and does the larger check help survivor years?',
+        ],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Harris household',
+      assumptions: [
+        { label: 'Age 62 claim', value: '$1,700 a month, starting sooner' },
+        { label: 'Age 67 claim', value: '$2,400 a month, but requires five bridge years' },
+        { label: 'Age 70 claim', value: '$3,000 a month, but uses even more portfolio before checks begin' },
+      ],
+      summary:
+        'The age 70 check is $1,300 more per month than age 62, but the Harrises must fund the waiting years first. RetireGolden compares both the bridge cost and the later income floor.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'On the **Social Security** screen, you enter each person\'s benefit source and claim age. On the **Social Security analysis** screen, RetireGolden sweeps claim-age combinations through the full plan and ranks them by ending after-tax estate. It also has a benefits-only view that isolates the Social Security value of the choice.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Assuming the largest monthly check is always the best plan choice.',
+        'Ignoring the years before the later claim starts, when the portfolio must cover more spending.',
+        'For couples, looking only at the first spouse instead of the survivor check after one death.',
+        'Using break-even age as the whole answer instead of one useful lens.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Start on **Social Security** to enter the benefit and claim age. Then open **Social Security analysis** to compare claim ages in the full plan, the benefits-only view, and the break-even view.',
+    },
+  ],
+}

package/src/learn/content/social-security-taxes-vs-benefits.ts

@@ -0,0 +1,76 @@
+/**
+ * "Social Security taxes vs. benefits" - a Social Security article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const socialSecurityTaxesVsBenefitsArticle: LearningArticle = {
+  slug: 'social-security-taxes-vs-benefits',
+  title: 'Social Security taxes vs. benefits',
+  description: 'What you paid in (OASDI) versus what you get back — and why the comparison is imperfect.',
+  category: 'social-security',
+  tags: ['social security', 'fica', 'oasdi', 'payroll tax', 'self-employment', 'taxable wage base', 'return'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-06-29',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.ssa.gov/news/en/cola/factsheets/2026.html',
+    'https://www.ssa.gov/oact/ProgData/taxRates.html',
+    'https://www.ssa.gov/benefits/retirement/planner/applying7.html',
+  ],
+  relatedArticles: [
+    'pia-aime-and-bend-points',
+    'social-security-claiming-age-basics',
+    'mortality-weighted-social-security',
+    'how-social-security-is-taxed',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/social-security-analysis', '/plan/:planId/social-security'],
+  currentYearSensitive: true,
+  priority: 'P2',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'A natural question: "Did I get back what I put into Social Security?" The answer is more nuanced than dividing your benefits by your taxes, because Social Security is **insurance**, not an investment. A "what you paid in vs. what you get back" view is still a useful illustration, as long as you know what it does and does not capture.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'You paid the **OASDI** payroll tax (6.2% as an employee, 12.4% if self-employed) on covered earnings up to each year’s **taxable wage base**.',
+        'The "get back" side is the **survival-weighted expected value** of your lifetime benefits — not a literal account balance.',
+        'The ratio is an **individual-level illustration**, not the program’s actuarial return, and it excludes the value of disability and survivor insurance, spousal benefits, and Medicare.',
+      ],
+    },
+    { type: 'heading', text: 'What you paid in' },
+    {
+      type: 'prose',
+      md: 'Each paycheck, 6.2% of your covered wages (up to the annual taxable wage base — $184,500 in 2026) goes to the OASDI part of FICA. Your employer pays another 6.2%; the self-employed pay both halves (12.4%) as SECA. This view sums the OASDI tax over your earnings history and **intentionally excludes the 1.45% Medicare HI tax**, because the "get back" side is the retirement benefit, not Medicare. The employer share is shown as context, not added to what you paid.',
+    },
+    { type: 'heading', text: 'What you get back' },
+    {
+      type: 'prose',
+      md: 'The "get back" figure is the **mortality-weighted expected present value** of your lifetime retirement benefits at your chosen claim age — the same method used by the actuarial "Benefits only" view. Each future year’s benefit is multiplied by the probability you survive to receive it and discounted to today’s dollars at a real rate. This is the *expected* value, not a guarantee; living longer raises it, dying sooner lowers it.',
+    },
+    { type: 'heading', text: 'What the ratio does not capture' },
+    {
+      type: 'list',
+      items: [
+        '**Insurance value:** the payroll tax also buys disability and survivor protection you may never draw but that has real expected value.',
+        '**Spousal and family benefits:** a non-working or lower-earning spouse can receive benefits on your record, which the individual ratio ignores.',
+        '**Employer share:** if you’re an employee, your employer paid half the OASDI tax — not "your" contribution, but part of the cost of your labor.',
+        '**Medicare:** the HI tax funds Medicare, which is excluded from both sides here.',
+      ],
+    },
+    {
+      type: 'callout',
+      tone: 'note',
+      md: 'This is why a low lifetime ratio doesn’t mean Social Security is a "bad deal" for you — the program transfers value toward lower earners, the disabled, survivors, and longer-lived spouses in ways a single ratio can’t show.',
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'On **Social Security analysis** (the Benefits-only tab), expand "What you paid in vs. what you get back." It uses the earnings history you entered on the Social Security step, so enter an earnings record (or import your mySSA statement) to see it. A self-employed toggle applies the 12.4% rate.',
+    },
+  ],
+}

package/src/learn/content/spending-profiles-and-the-retirement-smile.ts

@@ -0,0 +1,92 @@
+/**
+ * "Spending profiles and the retirement smile" - a Using RetireGolden P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const spendingProfilesAndRetirementSmileArticle: LearningArticle = {
+  slug: 'spending-profiles-and-the-retirement-smile',
+  title: 'Spending profiles and the retirement smile',
+  description: 'How flat, smile, and front-loaded spending profiles become editable phase rows.',
+  category: 'using-retiregolden',
+  tags: ['spending', 'retirement smile', 'phases', 'travel', 'budget'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-07-06',
+  reviewCadence: 'stable',
+  sourceUrls: [
+    'https://www.financialplanningassociation.org/sites/default/files/2020-09/MAY14%20JFP%20Blanchett_0.pdf',
+    'https://www.bls.gov/cex/',
+  ],
+  relatedArticles: [
+    'building-a-retirement-spending-budget',
+    'dynamic-spending-guardrails',
+    'using-scenarios-to-compare-choices',
+    'three-big-questions-spending-time-risk',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/spending', '/plan/:planId/results', '/plan/:planId/scenarios'],
+  currentYearSensitive: false,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'A spending profile is a starting shape for recurring lifestyle spending. Instead of asking you to enter every future year, RetireGolden can write a few phase rows that change baseline spending at selected ages.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'Profiles are shortcuts, not hidden model settings: they write ordinary Spending phase rows.',
+        'The retirement smile preset lowers recurring lifestyle spending at ages 75 and 85.',
+        'Front-loaded travel raises early retirement spending, then returns to baseline at 75.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Many retirement plans are easier to understand as phases. Some households want a flat real budget. Others expect higher go-go spending early in retirement, lower slow-go spending later, or a front-loaded travel window before age 75.\n\nRetireGolden keeps this simple: choosing a profile replaces the current phase rows with visible rows you can edit or remove. The engine still sees only baseline spending plus phase multipliers.',
+    },
+    {
+      type: 'table',
+      caption: 'What each Spending profile writes.',
+      columns: ['Profile', 'Rows RetireGolden creates', 'Use when'],
+      rows: [
+        ['Flat', 'No phase rows', 'You want recurring lifestyle spending to stay level in real terms'],
+        ['Retirement smile', '0.90 from age 75, then 0.80 from age 85', 'You want to test lower slow-go and no-go lifestyle spending'],
+        ['Front-loaded travel', '1.10 from retirement until age 75, then 1.00 from age 75', 'You want a larger early travel or project budget that later settles back'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Patel household',
+      assumptions: [
+        { label: 'Baseline spending', value: '$100,000 per year in today\'s dollars' },
+        { label: 'Profile', value: 'Retirement smile' },
+        { label: 'Age 75 phase', value: 'Recurring lifestyle spending becomes $90,000 before inflation' },
+        { label: 'Age 85 phase', value: 'Recurring lifestyle spending becomes $80,000 before inflation' },
+      ],
+      summary:
+        'The profile changes only recurring lifestyle spending. Healthcare premiums, debt payments, property costs, insurance premiums, and one-time goals keep their own schedules.',
+    },
+    { type: 'heading', text: 'Why this is not a prediction' },
+    {
+      type: 'prose',
+      md: 'The retirement smile is a planning pattern, not a promise that your spending will decline. Travel may fall, but gifts, housing, taxes, healthcare, or care needs may not. Use profiles to test a version of the plan, then check Results and Monte Carlo to see whether the plan still has room if the shape is wrong.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Treating the smile preset as automatic advice instead of a scenario to test.',
+        'Forgetting that a new profile replaces existing phase rows.',
+        'Using a lower phase multiplier to hide a known healthcare, debt, insurance, or long-term-care cost that belongs in its own input.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Spending** to choose a profile or edit the phase rows directly. Use **Scenarios** to compare flat, smile, and front-loaded versions side by side before changing the base plan.',
+    },
+  ],
+}

package/src/learn/content/spousal-and-survivor-benefits.ts

@@ -0,0 +1,120 @@
+/**
+ * "Spousal and survivor benefits" - a Social Security P0 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const spousalSurvivorBenefitsArticle: LearningArticle = {
+  slug: 'spousal-and-survivor-benefits',
+  title: 'Spousal and survivor benefits',
+  description: 'How a couple\'s benefits interact while both live and after one dies.',
+  category: 'social-security',
+  tags: ['social security', 'spousal benefit', 'survivor benefit', 'couples', 'widow', 'widower'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-29',
+  reviewCadence: 'rule-change',
+  sourceUrls: [
+    'https://www.ssa.gov/benefits/retirement/planner/applying7.html',
+    'https://www.ssa.gov/benefits/survivors/',
+    'https://www.ssa.gov/oact/ProgData/nra.html',
+    'https://secure.ssa.gov/poms.nsf/lnx/0300615100',
+  ],
+  relatedArticles: [
+    'social-security-claiming-age-basics',
+    'break-even-useful-lens',
+    'planning-for-couples-and-survivor-years',
+    'widows-penalty-and-survivor-brackets',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/social-security', '/plan/:planId/social-security-analysis'],
+  currentYearSensitive: false,
+  priority: 'P0',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'For a couple, Social Security is not just two separate checks. Spousal and survivor rules can change the household income while both spouses are alive and after one spouse dies.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'A lower earner may receive a spousal top-up while both spouses are alive.',
+        'After the first death, the survivor generally keeps the larger benefit, not both checks.',
+        'Delaying the higher earner can protect the person who lives longest, even if it looks less attractive for one person alone.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'While both spouses are alive, each person may have their own retirement benefit. If one benefit is much smaller, a spousal rule can lift the lower earner toward a share of the higher earner\'s base benefit.\n\nAfter one spouse dies, the household usually does not keep both checks. The survivor benefit can replace the smaller check with the larger one. That is why a high earner\'s claiming age can be a survivor-protection decision, not just an individual decision.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/spousal-survivor-benefits.webp' },
+      caption:
+        'A couple may have two benefit streams while both are alive; after one death, the survivor keeps one protected larger stream.',
+      alt: 'Two benefit ribbons flow through a couple-years gate, then one larger protected ribbon continues through a survivor checkpoint.',
+    },
+    { type: 'heading', text: 'Two phases to think about' },
+    {
+      type: 'table',
+      caption: 'How couple benefits can change across a retirement.',
+      columns: ['Phase', 'What to watch', 'Why it matters'],
+      rows: [
+        ['Both spouses alive', 'Own benefits plus possible spousal top-up', 'The lower earner may receive more than their own record alone would pay'],
+        ['First spouse dies', 'The smaller check may disappear', 'Household income can fall while many expenses remain'],
+        ['Survivor years', 'Survivor keeps the larger benefit stream', 'A larger delayed high-earner check can become long-life protection'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Morgan household',
+      assumptions: [
+        { label: 'Higher earner', value: '$2,800 monthly benefit at full retirement age' },
+        { label: 'Lower earner', value: '$900 own benefit, with a possible top-up toward $1,400 while both are alive' },
+        { label: 'Survivor concern', value: 'After one death, the survivor keeps one larger benefit, not both checks' },
+      ],
+      summary:
+        'The spousal top-up can raise couple-year income by about **$500** a month. Later, the survivor floor depends heavily on the higher earner\'s benefit, so claim timing affects more than the first check.',
+    },
+    { type: 'heading', text: 'Survivor precision: early-claim reduction and the widow\u2019s limit' },
+    {
+      type: 'prose',
+      md: 'A survivor benefit is not always 100% of what the deceased would have received. Two SSA rules shape the amount, and RetireGolden models both:',
+    },
+    {
+      type: 'list',
+      items: [
+        '**Early-claim widow(er) reduction.** A survivor can claim as early as age 60, but claiming before the survivor\u2019s own full retirement age reduces the benefit by up to 28.5% at 60 (a floor of 71.5%). The survivor FRA is a separate, earlier schedule than the worker FRA \u2014 it tops out at 66 years and 8 months for those born 1960+, not 67.',
+        '**RIB-LIM (the widow\u2019s limit).** If the deceased claimed reduced benefits early, the survivor is capped at the larger of the deceased\u2019s actual reduced benefit or 82.5% of the deceased\u2019s PIA. This usually lifts the survivor above the deceased\u2019s reduced amount but below 100% of the PIA.',
+        '**The base is the deceased\u2019s actual benefit.** If the deceased delayed past FRA, those delayed retirement credits pass through to the survivor.',
+      ],
+    },
+    {
+      type: 'callout',
+      tone: 'note',
+      md: 'Example: a deceased worker with a $2,400 PIA who claimed at 62 was receiving 70% ($1,680). At the survivor FRA, the widow\u2019s limit floors the survivor at 82.5% of PIA \u2014 $1,980 \u2014 even though the deceased only got $1,680. If instead the deceased had delayed to 70, the survivor would receive the full delayed amount (about 124% of PIA).',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden models a current-spouse top-up while both spouses are alive and both have claimed. It also models a survivor step-up so the surviving spouse keeps the larger benefit, computed with full precision \u2014 the deceased\u2019s claim-age-adjusted base, the RIB-LIM widow\u2019s-limit cap, and the early-claim widow(er) reduction. The Social Security entry screen can store former-spouse records (including the deceased ex\u2019s claim age) for divorced-spousal or survivor cases.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Optimizing each spouse as if they were single.',
+        'Forgetting that one check can disappear after the first death.',
+        'Assuming a spousal benefit earns delayed retirement credits the same way a worker benefit does.',
+        'Leaving out former-spouse records that may matter for a single divorced or widowed person.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Social Security** to enter both spouses and any former-spouse records that may apply. Use **Social Security analysis** to compare claim-age combinations and read the couple strategy notes.',
+    },
+  ],
+}

package/src/learn/content/ssdi-and-retirement-planning.ts

@@ -0,0 +1,72 @@
+/**
+ * "SSDI and retirement planning" - a Social Security article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const ssdiAndRetirementPlanningArticle: LearningArticle = {
+  slug: 'ssdi-and-retirement-planning',
+  title: 'SSDI and retirement planning',
+  description: 'How Social Security disability bridges to retirement at full retirement age.',
+  category: 'social-security',
+  tags: ['social security', 'ssdi', 'disability', 'full retirement age', 'sga', 'pia'],
+  audience: 'intermediate',
+  status: 'ready',
+  lastReviewed: '2026-06-29',
+  reviewCadence: 'annual',
+  sourceUrls: [
+    'https://www.ssa.gov/benefits/disability/',
+    'https://www.ssa.gov/oact/cola/sga.html',
+    'https://www.ssa.gov/oact/ProgData/nra.html',
+  ],
+  relatedArticles: [
+    'social-security-claiming-age-basics',
+    'pia-aime-and-bend-points',
+    'spousal-and-survivor-benefits',
+    'earnings-test-before-fra',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/social-security'],
+  currentYearSensitive: true,
+  priority: 'P2',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Social Security Disability Insurance (SSDI) is a separate benefit from retirement, but it matters to a retirement planner for one key reason: **at full retirement age, SSDI converts to the retirement benefit at the same dollar amount.** If you become disabled before your retirement-claim age, SSDI is the bridge that pays you until then.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'SSDI pays your **full PIA** — the benefit you would get at full retirement age — with no early-retirement reduction, even if your disability began years before 62.',
+        'At full retirement age it **converts automatically** to the retirement benefit at the same dollar amount (no jump, no paperwork).',
+        'Before FRA, earning over the **Substantial Gainful Activity (SGA)** limit suspends SSDI; this is not the same as the retirement earnings test.',
+        'Because SSDI pays the full PIA, you do **not** earn delayed-retirement credits by "waiting" — the benefit is already being paid.',
+      ],
+    },
+    { type: 'heading', text: 'Why SSDI pays the full PIA' },
+    {
+      type: 'prose',
+      md: 'When you claim *retirement* benefits before full retirement age, your benefit is permanently reduced. SSDI is different: a disabled worker receives their full Primary Insurance Amount (PIA) regardless of age at onset. The PIA is computed the same way (your average indexed monthly earnings through the bend-point formula), but the early reduction does not apply. In practice this means someone disabled at 55 receives the same monthly amount they would have gotten by waiting until FRA.',
+    },
+    {
+      type: 'callout',
+      tone: 'note',
+      md: 'A "disability freeze" excludes low or zero-earning months during the disability period from the AIME average, so time out of the workforce does not drag your PIA down. RetireGolden uses the PIA you enter or derive from earnings and does not recompute the freeze.',
+    },
+    { type: 'heading', text: 'The SGA gate (before FRA)' },
+    {
+      type: 'prose',
+      md: 'While receiving SSDI before FRA, earning above the Substantial Gainful Activity limit generally stops the benefit. In 2026, SGA is $1,620 per month for non-blind work ($2,700 if statutorily blind). SSA also offers a trial work period and extended Medicare, which RetireGolden does not model — the planner applies a simple annual check: if your wages exceed SGA × 12, SSDI is suspended for that year.',
+    },
+    { type: 'heading', text: 'Conversion at FRA' },
+    {
+      type: 'prose',
+      md: 'In the month you reach full retirement age, SSDI automatically becomes a retirement benefit. The dollar amount is unchanged — both are the PIA — so there is no discontinuity in your income. From FRA onward, the usual retirement rules apply: no earnings test (it ends at FRA), but also no further delayed credits, because you are already receiving the benefit.',
+    },
+    { type: 'heading', text: 'How to use this in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'On the Social Security step, expand **Disability (SSDI)** and enter your disability onset age. The planner pays your full PIA from that age (instead of your retirement claim age), applies the SGA gate before FRA, and continues the same amount through FRA conversion — flowing into the normal tax, IRMAA, and ACA cascade like any other Social Security income.',
+    },
+  ],
+}

package/src/learn/content/standard-deduction-senior-deduction-and-itemizing.ts

@@ -0,0 +1,97 @@
+/**
+ * "Standard deduction, senior deduction, and itemizing" - a Taxes P1 article.
+ */
+
+import type { LearningArticle } from '../learningRegistry'
+
+export const standardDeductionSeniorDeductionItemizingArticle: LearningArticle = {
+  slug: 'standard-deduction-senior-deduction-and-itemizing',
+  title: 'Standard deduction, senior deduction, and itemizing',
+  description: 'How deductions lower taxable income and when itemizing wins.',
+  category: 'taxes',
+  tags: ['standard deduction', 'senior deduction', 'itemized deductions', 'salt', 'taxable income'],
+  audience: 'beginner',
+  status: 'ready',
+  lastReviewed: '2026-06-20',
+  reviewCadence: 'annual',
+  sourceUrls: ['https://www.irs.gov/filing/federal-income-tax-rates-and-brackets'],
+  relatedArticles: [
+    'agi-magi-and-taxable-income',
+    'marginal-vs-effective-tax-rate',
+    'ordinary-income-vs-capital-gains',
+    'tax-cliffs-and-bracket-edges',
+  ],
+  relatedPlannerRoutes: ['/plan/:planId/strategy', '/plan/:planId/assumptions', '/plan/:planId/results'],
+  currentYearSensitive: true,
+  priority: 'P1',
+  blocks: [
+    {
+      type: 'prose',
+      md: 'Deductions do not erase income. They reduce the income that federal brackets apply to. In retirement, deductions matter because they can change the tax cost of withdrawals, Roth conversions, capital gains, and Social Security taxation.',
+    },
+    { type: 'heading', text: 'Quick takeaways' },
+    {
+      type: 'list',
+      items: [
+        'The standard deduction is the default deduction amount based on filing status and age.',
+        'Itemizing can win when deductible expenses are larger than the standard deduction.',
+        'RetireGolden compares standard and itemized deductions, then applies the modeled senior deduction when current-law rules allow it.',
+      ],
+    },
+    { type: 'heading', text: 'The basic idea' },
+    {
+      type: 'prose',
+      md: 'Taxable income is generally income after deductions. The standard deduction is simple and available to many households. Itemized deductions are specific expenses, such as deductible state and local taxes, mortgage interest, and charitable giving. The better choice is usually the larger deduction, but the exact rules and limits change over time.',
+    },
+    {
+      type: 'figure',
+      image: { src: '/learn/images/deductions-itemizing.webp' },
+      caption:
+        'Deductions sit between income and taxable income; the larger standard or itemized base wins before brackets apply.',
+      alt: 'Income flows into a deduction filter with two competing paths, one standard and one itemized, before a smaller stream reaches a tax-bracket ladder.',
+    },
+    {
+      type: 'table',
+      caption: 'How deduction pieces affect the modeled tax year.',
+      columns: ['Deduction piece', 'What it means', 'Planning note'],
+      rows: [
+        ['Standard deduction', 'A filing-status amount with age-based additions', 'Often wins when itemized expenses are modest'],
+        ['Itemized deductions', 'Specific deductible expenses entered in the plan', 'Can win in high property-tax, mortgage-interest, or giving years'],
+        ['SALT cap', 'A limit on deductible state and local tax in the itemized total', 'RetireGolden caps the SALT component using the year\'s parameter pack'],
+        ['Senior deduction', 'A current-law extra deduction for eligible older taxpayers', 'Modeled with phaseout and expiration rules from the parameter pack'],
+      ],
+    },
+    { type: 'heading', text: 'A worked example' },
+    {
+      type: 'scenario',
+      name: 'The Alvarez household',
+      assumptions: [
+        { label: 'Retirement income', value: 'Pension, IRA withdrawals, and $12,000 of taxable gains' },
+        { label: 'Itemized total', value: '$21,000 of property tax, mortgage interest, and giving' },
+        { label: 'Standard deduction estimate', value: '$30,000 for their filing status and ages' },
+      ],
+      summary:
+        'Because $21,000 is below the $30,000 standard deduction estimate, itemizing would not lower taxable income here. A later year with a larger gift could flip that comparison.',
+    },
+    { type: 'heading', text: 'Why it matters in RetireGolden' },
+    {
+      type: 'prose',
+      md: 'RetireGolden uses the federal parameter pack for the standard deduction, age-65 additions, SALT cap, and senior deduction. The tax engine compares standard and itemized deductions, adds the modeled senior deduction when applicable, and then applies ordinary-income and capital-gain tax rules to taxable income.',
+    },
+    { type: 'heading', text: 'Common mistakes' },
+    {
+      type: 'list',
+      items: [
+        'Using AGI or MAGI as if deductions had already been applied.',
+        'Assuming itemizing wins just because one deductible expense is large.',
+        'Forgetting that deduction rules can expire or change.',
+        'Expecting RetireGolden to replace tax-preparation software for every form-level limitation.',
+      ],
+    },
+    { type: 'heading', text: 'Where to use this in the app' },
+    {
+      type: 'prose',
+      md: 'Use **Strategy** for itemized-deduction inputs such as deductible state and local tax, mortgage interest, and charitable giving. Use **Results** to inspect deduction, taxable income, ordinary tax, and capital-gain tax by year.',
+    },
+  ],
+}