@retiregolden/planner-ui 0.1.0

package/src/planner/examples/buildEarlyCareerMatch.ts

@@ -0,0 +1,93 @@
+import { createEmptyPlan, parsePlan, type Plan } from '@retiregolden/engine/model/plan'
+import { exampleEntityId, exampleFixedNow, exampleIdFactory } from './buildContext'
+
+const EXAMPLE_ID = 'early-career-match'
+
+export function buildEarlyCareerMatch(): Plan {
+  const p1 = exampleEntityId(EXAMPLE_ID, 'p1')
+  const plan = createEmptyPlan({ name: 'Just getting started', now: exampleFixedNow, newId: exampleIdFactory(EXAMPLE_ID) })
+  plan.household = {
+    filingStatus: 'single',
+    hasQualifyingDependent: false,
+    state: 'CA',
+    stateMoves: [],
+    capitalLossCarryforward: 0,
+    people: [
+      { id: p1, name: 'Alex', dob: '2001-01-01', sex: 'average', retirementAge: 60, longevity: { planningAge: 90, source: 'manual' } },
+    ],
+  }
+  plan.accounts = [
+    {
+      type: 'cash',
+      id: exampleEntityId(EXAMPLE_ID, 'savings'),
+      name: 'Emergency Fund',
+      ownerPersonId: null,
+      annualReturnPct: 3,
+      balance: 10_000,
+      annualContribution: 0,
+    },
+    {
+      type: 'traditional',
+      id: exampleEntityId(EXAMPLE_ID, 'traditional-401k'),
+      name: 'Employer 401(k)',
+      ownerPersonId: p1,
+      annualReturnPct: 7,
+      kind: 'employer',
+      balance: 5_000,
+      annualContribution: 6_000,
+      employerMatch: {
+        matchPct: 100,
+        capPctOfPay: 4,
+      },
+    },
+    {
+      type: 'roth',
+      id: exampleEntityId(EXAMPLE_ID, 'roth-ira'),
+      name: 'Roth IRA',
+      ownerPersonId: p1,
+      annualReturnPct: 7,
+      kind: 'ira',
+      balance: 2_000,
+      annualContribution: 3_000,
+    },
+  ]
+  plan.incomes = [
+    {
+      type: 'wages',
+      id: exampleEntityId(EXAMPLE_ID, 'wages'),
+      personId: p1,
+      annualGross: 65_000,
+      endAge: null,
+      realGrowthPct: 3,
+    },
+    {
+      type: 'socialSecurity',
+      id: exampleEntityId(EXAMPLE_ID, 'ss'),
+      personId: p1,
+      piaMonthly: 2_000,
+      earnings: null,
+      claimAge: { years: 67, months: 0 },
+    },
+  ]
+  plan.expenses = {
+    baseAnnual: 45_000,
+    phases: [],
+    oneTimeGoals: [],
+    healthcare: { pre65MonthlyPremiumPerPerson: 350, applyAcaCredit: true, medicareExtrasMonthlyPerPerson: 150 },
+  }
+  plan.assumptions = {
+    inflationPct: 2.5,
+    healthcareExtraInflationPct: 2,
+    defaultReturnPct: 6,
+    ssCola: { mode: 'matchInflation' },
+    ssHaircut: null,
+    stateEffectiveTaxPct: 0,
+    localIncomeTaxPct: 0,
+    recentAnnualMagi: 65_000,
+    heirTaxRatePct: 25,
+    safeWithdrawalRatePct: 4,
+  }
+  const parsed = parsePlan(plan)
+  if (!parsed.ok) throw new Error(`early-career-match invalid: ${parsed.issues.join('; ')}`)
+  return parsed.plan
+}

package/src/planner/examples/buildEarlyRetireeAca.ts

@@ -0,0 +1,61 @@
+/** Early retiree and the ACA cliff — pre-65 MAGI vs premium-credit cliff. */
+
+import { createEmptyPlan, parsePlan, type Plan } from '@retiregolden/engine/model/plan'
+import { EXAMPLE_FIXED_YEAR, exampleEntityId, exampleFixedNow, exampleIdFactory } from './buildContext'
+
+const EXAMPLE_ID = 'early-retiree-aca'
+
+export function buildEarlyRetireeAca(): Plan {
+  const p1 = exampleEntityId(EXAMPLE_ID, 'p1')
+  const plan = createEmptyPlan({ name: 'Early retiree & the ACA cliff', now: exampleFixedNow, newId: exampleIdFactory(EXAMPLE_ID) })
+  plan.household = {
+    filingStatus: 'single',
+    hasQualifyingDependent: false,
+    state: 'FL',
+    stateMoves: [],
+    capitalLossCarryforward: 0,
+    people: [
+      { id: p1, name: 'Casey', dob: '1964-01-01', sex: 'female', retirementAge: 58, longevity: { planningAge: 92, source: 'manual' } },
+    ],
+  }
+  plan.accounts = [
+    { type: 'cash', id: exampleEntityId(EXAMPLE_ID, 'cash'), name: 'Cash', ownerPersonId: null, annualReturnPct: 2, balance: 200_000, annualContribution: 0 },
+    { type: 'traditional', id: exampleEntityId(EXAMPLE_ID, 'ira'), name: 'Traditional IRA', ownerPersonId: p1, annualReturnPct: null, kind: 'ira', balance: 450_000, annualContribution: 0 },
+    { type: 'roth', id: exampleEntityId(EXAMPLE_ID, 'roth'), name: 'Roth IRA', ownerPersonId: p1, annualReturnPct: null, kind: 'ira', balance: 120_000, annualContribution: 0 },
+  ]
+  plan.incomes = [
+    { type: 'recurring', id: exampleEntityId(EXAMPLE_ID, 'consulting'), label: 'Consulting', annualAmount: 55_000, startYear: EXAMPLE_FIXED_YEAR, endYear: null, inflationAdjusted: true, taxTreatment: 'ordinary' },
+  ]
+  plan.expenses = {
+    baseAnnual: 48_000,
+    phases: [],
+    oneTimeGoals: [],
+    healthcare: { pre65MonthlyPremiumPerPerson: 1_000, applyAcaCredit: true, medicareExtrasMonthlyPerPerson: 0 },
+  }
+  plan.strategies = {
+    withdrawalOrder: { mode: 'sequential' },
+    rothConversion: {
+      mode: 'fillToTarget',
+      target: 'topOfBracket',
+      targetValue: 12,
+      startYear: EXAMPLE_FIXED_YEAR,
+      endYear: EXAMPLE_FIXED_YEAR + 4,
+    },
+    qcdAnnual: 0,
+  }
+  plan.assumptions = {
+    inflationPct: 2.5,
+    healthcareExtraInflationPct: 3,
+    defaultReturnPct: 5,
+    ssCola: { mode: 'matchInflation' },
+    ssHaircut: null,
+    stateEffectiveTaxPct: 0,
+    localIncomeTaxPct: 0,
+    recentAnnualMagi: 50_000,
+    heirTaxRatePct: 22,
+    safeWithdrawalRatePct: 4,
+  }
+  const parsed = parsePlan(plan)
+  if (!parsed.ok) throw new Error(`early retiree ACA invalid: ${parsed.issues.join('; ')}`)
+  return parsed.plan
+}

package/src/planner/examples/buildExampleCouple.ts

@@ -0,0 +1,103 @@
+/** Example couple — the full picture: accounts, SS, Roth strategy, insurance, scenarios. */
+
+import { createEmptyPlan, parsePlan, type Plan } from '@retiregolden/engine/model/plan'
+import { TRUSTEES_DEFAULT_SS_HAIRCUT } from '@retiregolden/engine/params'
+import { EXAMPLE_FIXED_YEAR, exampleEntityId, exampleFixedNow, exampleIdFactory } from './buildContext'
+
+const EXAMPLE_ID = 'example-couple'
+
+export function buildExampleCouple(): Plan {
+  const meId = exampleEntityId(EXAMPLE_ID, 'alex')
+  const partnerId = exampleEntityId(EXAMPLE_ID, 'sam')
+  const plan = createEmptyPlan({ name: 'Example couple', now: exampleFixedNow, newId: exampleIdFactory(EXAMPLE_ID) })
+  plan.household = {
+    filingStatus: 'marriedFilingJointly',
+    hasQualifyingDependent: false,
+    state: 'KY',
+    stateMoves: [],
+    capitalLossCarryforward: 0,
+    people: [
+      { id: meId, name: 'Alex', dob: '1962-04-15', sex: 'male', retirementAge: 66, longevity: { planningAge: 92, source: 'manual' } },
+      { id: partnerId, name: 'Sam', dob: '1964-09-02', sex: 'female', retirementAge: 64, longevity: { planningAge: 95, source: 'manual' } },
+    ],
+  }
+  plan.accounts = [
+    { type: 'cash', id: exampleEntityId(EXAMPLE_ID, 'savings'), name: 'Savings', ownerPersonId: null, annualReturnPct: 2, balance: 60_000, annualContribution: 0 },
+    { type: 'taxable', id: exampleEntityId(EXAMPLE_ID, 'brokerage'), name: 'Joint brokerage', ownerPersonId: null, annualReturnPct: null, balance: 650_000, costBasis: 420_000, annualContribution: 12_000 },
+    { type: 'equityComp', id: exampleEntityId(EXAMPLE_ID, 'rsu'), name: 'Alex RSUs', ownerPersonId: meId, annualReturnPct: null, balance: 120_000, costBasis: 95_000, annualContribution: 0, vestingMode: 'cliff', vestDate: '2028-03-15' },
+    { type: 'traditional', id: exampleEntityId(EXAMPLE_ID, '401k'), name: 'Alex 401(k)', ownerPersonId: meId, annualReturnPct: null, kind: 'employer', balance: 820_000, annualContribution: 24_000 },
+    { type: 'traditional', id: exampleEntityId(EXAMPLE_ID, 'sam-ira'), name: 'Sam IRA', ownerPersonId: partnerId, annualReturnPct: null, kind: 'ira', balance: 310_000, annualContribution: 0 },
+    { type: 'roth', id: exampleEntityId(EXAMPLE_ID, 'roth'), name: 'Alex Roth IRA', ownerPersonId: meId, annualReturnPct: null, kind: 'ira', balance: 145_000, annualContribution: 7_500, contributionBasis: 80_000 },
+    { type: 'property', id: exampleEntityId(EXAMPLE_ID, 'home'), name: 'Home', ownerPersonId: null, annualReturnPct: null, value: 420_000, plannedSaleYear: null, expectedNetProceeds: null, propertyTaxAnnual: 6_000, insuranceAnnual: 1_800 },
+    { type: 'debt', id: exampleEntityId(EXAMPLE_ID, 'mortgage'), name: 'Mortgage', ownerPersonId: null, annualReturnPct: null, balance: 180_000, interestPct: 3, monthlyPayment: 1_100 },
+  ]
+  plan.insurance = [
+    {
+      kind: 'permanentLife', id: exampleEntityId(EXAMPLE_ID, 'wl'), name: 'Alex whole life', insured: meId, beneficiary: 'estate',
+      annualPremium: 3_600, premiumMode: 'lifetime', deathBenefit: 350_000,
+      cashValue: 85_000, cashValueMode: 'flatRate', cashValueGrowthPct: 4,
+    },
+    {
+      kind: 'ltc', id: exampleEntityId(EXAMPLE_ID, 'ltc-alex'), name: 'Alex LTC', owner: meId,
+      annualPremium: 2_400, premiumMode: 'lifetime', benefitMonthly: 6_000, benefitPeriodYears: 3,
+      eliminationPeriodDays: 90, inflationRiderPct: 3,
+    },
+    {
+      kind: 'ltc', id: exampleEntityId(EXAMPLE_ID, 'ltc-sam'), name: 'Sam LTC', owner: partnerId,
+      annualPremium: 2_200, premiumMode: 'lifetime', benefitMonthly: 6_000, benefitPeriodYears: 3,
+      eliminationPeriodDays: 90, inflationRiderPct: 3,
+    },
+  ]
+  plan.careEvents = [
+    { id: exampleEntityId(EXAMPLE_ID, 'care'), personId: meId, startAge: 88, durationYears: 3, annualCost: 90_000 },
+  ]
+  plan.incomes = [
+    { type: 'wages', id: exampleEntityId(EXAMPLE_ID, 'wages-alex'), personId: meId, annualGross: 140_000, endAge: null, realGrowthPct: 0 },
+    { type: 'wages', id: exampleEntityId(EXAMPLE_ID, 'wages-sam'), personId: partnerId, annualGross: 85_000, endAge: null, realGrowthPct: 0 },
+    { type: 'socialSecurity', id: exampleEntityId(EXAMPLE_ID, 'ss-alex'), personId: meId, piaMonthly: 2_900, earnings: null, claimAge: { years: 70, months: 0 } },
+    { type: 'socialSecurity', id: exampleEntityId(EXAMPLE_ID, 'ss-sam'), personId: partnerId, piaMonthly: 1_950, earnings: null, claimAge: { years: 67, months: 0 } },
+  ]
+  plan.expenses = {
+    baseAnnual: 96_000,
+    phases: [
+      { fromAge: 75, multiplier: 0.9 },
+      { fromAge: 85, multiplier: 0.8 },
+    ],
+    oneTimeGoals: [{ id: exampleEntityId(EXAMPLE_ID, 'remodel'), label: 'Kitchen remodel', year: EXAMPLE_FIXED_YEAR + 3, amount: 45_000 }],
+    healthcare: { pre65MonthlyPremiumPerPerson: 950, applyAcaCredit: true, medicareExtrasMonthlyPerPerson: 180 },
+  }
+  plan.strategies = {
+    withdrawalOrder: { mode: 'sequential' },
+    rothConversion: {
+      mode: 'fillToTarget',
+      target: 'topOfBracket',
+      targetValue: 22,
+      startYear: EXAMPLE_FIXED_YEAR + 2,
+      endYear: EXAMPLE_FIXED_YEAR + 10,
+    },
+    qcdAnnual: 0,
+  }
+  plan.assumptions = {
+    inflationPct: 2.5,
+    healthcareExtraInflationPct: 3,
+    defaultReturnPct: 5.5,
+    ssCola: { mode: 'matchInflation' },
+    ssHaircut: null,
+    stateEffectiveTaxPct: 0,
+    localIncomeTaxPct: 0,
+    recentAnnualMagi: 225_000,
+    heirTaxRatePct: 25,
+    safeWithdrawalRatePct: 4,
+  }
+  plan.scenarios = [
+    {
+      id: exampleEntityId(EXAMPLE_ID, 'ss-cut'),
+      name: `${TRUSTEES_DEFAULT_SS_HAIRCUT.cutPct}% Social Security cut in ${TRUSTEES_DEFAULT_SS_HAIRCUT.fromYear}`,
+      patch: { assumptions: { ssHaircut: { ...TRUSTEES_DEFAULT_SS_HAIRCUT } } },
+    },
+    { id: exampleEntityId(EXAMPLE_ID, 'spend-more'), name: 'Spend 15% more', patch: { expenses: { baseAnnual: Math.round(96_000 * 1.15) } } },
+  ]
+  const parsed = parsePlan(plan)
+  if (!parsed.ok) throw new Error(`example couple invalid: ${parsed.issues.join('; ')}`)
+  return parsed.plan
+}

package/src/planner/examples/buildFixedTargetSpending.ts

@@ -0,0 +1,74 @@
+/** Fixed target spending control (A-B pair for guardrails comparison).
+ * Identical household, balances, and target lifestyle as guardrails-flex-goals,
+ * but uses classic fixed target spending (no required floor, no guardrails policy,
+ * no classified/movable goals). Use with the guardrails example in Compare Plans
+ * to see success rate / depletion differences.
+ */
+
+import { createEmptyPlan, parsePlan, type Plan } from '@retiregolden/engine/model/plan'
+import { EXAMPLE_FIXED_YEAR, exampleEntityId, exampleFixedNow, exampleIdFactory } from './buildContext'
+
+const EXAMPLE_ID = 'fixed-target-spending'
+
+export function buildFixedTargetSpending(): Plan {
+  const p1 = exampleEntityId(EXAMPLE_ID, 'p1')
+  const plan = createEmptyPlan({ name: 'Fixed target spending (control)', now: exampleFixedNow, newId: exampleIdFactory(EXAMPLE_ID) })
+
+  plan.household = {
+    filingStatus: 'single',
+    hasQualifyingDependent: false,
+    state: 'KY',
+    stateMoves: [],
+    capitalLossCarryforward: 0,
+    people: [
+      { id: p1, name: 'Riley', dob: '1963-06-15', sex: 'female', retirementAge: 62, longevity: { planningAge: 92, source: 'manual' } },
+    ],
+  }
+
+  plan.accounts = [
+    { type: 'cash', id: exampleEntityId(EXAMPLE_ID, 'cash'), name: 'Cash reserve', ownerPersonId: null, annualReturnPct: 2.0, balance: 85_000, annualContribution: 0 },
+    { type: 'taxable', id: exampleEntityId(EXAMPLE_ID, 'brokerage'), name: 'Taxable brokerage', ownerPersonId: null, annualReturnPct: null, balance: 420_000, costBasis: 280_000, annualContribution: 0 },
+  ]
+
+  // Classic fixed target spending — no layers, no policy, simple goals
+  plan.expenses = {
+    baseAnnual: 58_000,
+    phases: [
+      { fromAge: 78, multiplier: 0.92 },
+    ],
+    oneTimeGoals: [
+      { id: exampleEntityId(EXAMPLE_ID, 'roof'), label: 'Roof replacement', year: EXAMPLE_FIXED_YEAR + 4, amount: 28_000 },
+      { id: exampleEntityId(EXAMPLE_ID, 'trip'), label: 'Big anniversary trip', year: EXAMPLE_FIXED_YEAR + 2, amount: 18_000 },
+      { id: exampleEntityId(EXAMPLE_ID, 'gift'), label: 'Family gift / remodel', year: EXAMPLE_FIXED_YEAR + 6, amount: 35_000 },
+    ],
+    healthcare: { pre65MonthlyPremiumPerPerson: 720, applyAcaCredit: true, medicareExtrasMonthlyPerPerson: 190 },
+    // No spendingPolicy, no required/ideal/excess
+  }
+
+  plan.incomes = [
+    { type: 'socialSecurity', id: exampleEntityId(EXAMPLE_ID, 'ss'), personId: p1, piaMonthly: 1850, earnings: null, claimAge: { years: 67, months: 0 } },
+  ]
+
+  plan.strategies = {
+    withdrawalOrder: { mode: 'sequential' },
+    rothConversion: { mode: 'none' },
+    qcdAnnual: 0,
+  }
+
+  plan.assumptions = {
+    inflationPct: 2.4,
+    healthcareExtraInflationPct: 3.2,
+    defaultReturnPct: 4.8,
+    ssCola: { mode: 'matchInflation' },
+    ssHaircut: null,
+    stateEffectiveTaxPct: 0,
+    localIncomeTaxPct: 0,
+    recentAnnualMagi: 0,
+    heirTaxRatePct: 24,
+    safeWithdrawalRatePct: 3.8,
+  }
+
+  const parsed = parsePlan(plan)
+  if (!parsed.ok) throw new Error(`fixed-target-spending invalid: ${parsed.issues.join('; ')}`)
+  return parsed.plan
+}

package/src/planner/examples/buildGlidepathAllocation.ts

@@ -0,0 +1,131 @@
+/** Glidepath allocation + rebalancing + MC v2 — positive demonstration of 4-class allocation,
+ * linear glidepath to conservative, annual rebalancing (with taxable realization), class yields,
+ * and improved downside risk metrics vs single-return baseline.
+ * Also surfaces asset-location opportunities via Insights.
+ */
+
+import { createEmptyPlan, parsePlan, type Account, type Plan } from '@retiregolden/engine/model/plan'
+import { EXAMPLE_FIXED_YEAR, exampleEntityId, exampleFixedNow, exampleIdFactory } from './buildContext'
+
+const EXAMPLE_ID = 'glidepath-allocation'
+
+export function buildGlidepathAllocation(): Plan {
+  const p1 = exampleEntityId(EXAMPLE_ID, 'p1')
+  const plan = createEmptyPlan({ name: 'Glidepath allocation retiree', now: exampleFixedNow, newId: exampleIdFactory(EXAMPLE_ID) })
+
+  plan.household = {
+    filingStatus: 'single',
+    hasQualifyingDependent: false,
+    state: 'CA',
+    stateMoves: [],
+    capitalLossCarryforward: 12000,
+    people: [
+      { id: p1, name: 'Morgan', dob: '1962-09-05', sex: 'male', retirementAge: 63, longevity: { planningAge: 91, source: 'manual' } },
+    ],
+  }
+
+  const allocAggressive = { usStocks: 55, intlStocks: 15, bonds: 25, cash: 5 }
+  const allocMid = { usStocks: 40, intlStocks: 10, bonds: 40, cash: 10 }
+  const allocConserv = { usStocks: 25, intlStocks: 5, bonds: 55, cash: 15 }
+
+  plan.accounts = [
+    {
+      type: 'taxable',
+      id: exampleEntityId(EXAMPLE_ID, 'broker'),
+      name: 'Taxable brokerage (gliding)',
+      ownerPersonId: null,
+      annualReturnPct: null,
+      balance: 380_000,
+      costBasis: 195_000,
+      annualContribution: 0,
+      // Linear glide from now-ish to later conservative
+      allocation: {
+        mode: 'linear',
+        rebalancing: 'annual',
+        startYear: EXAMPLE_FIXED_YEAR,
+        endYear: EXAMPLE_FIXED_YEAR + 12,
+        from: allocAggressive,
+        to: allocConserv,
+      },
+    },
+    {
+      type: 'traditional',
+      id: exampleEntityId(EXAMPLE_ID, 't401k'),
+      name: 'Traditional 401(k)',
+      ownerPersonId: p1,
+      annualReturnPct: null,
+      kind: 'employer',
+      balance: 920_000,
+      annualContribution: 0,
+      allocation: {
+        mode: 'staged',
+        rebalancing: 'annual',
+        stages: [
+          { fromYear: EXAMPLE_FIXED_YEAR, weights: allocAggressive },
+          { fromYear: EXAMPLE_FIXED_YEAR + 8, weights: allocMid },
+        ],
+      },
+    },
+    {
+      type: 'roth',
+      id: exampleEntityId(EXAMPLE_ID, 'roth'),
+      name: 'Roth IRA',
+      ownerPersonId: p1,
+      annualReturnPct: null,
+      kind: 'ira',
+      balance: 165_000,
+      annualContribution: 0,
+      allocation: { mode: 'static', rebalancing: 'annual', weights: allocMid },
+    },
+  ]
+
+  plan.expenses = {
+    baseAnnual: 62_000,
+    phases: [],
+    oneTimeGoals: [],
+    healthcare: { pre65MonthlyPremiumPerPerson: 810, applyAcaCredit: true, medicareExtrasMonthlyPerPerson: 175 },
+  }
+
+  plan.incomes = [
+    { type: 'socialSecurity', id: exampleEntityId(EXAMPLE_ID, 'ss'), personId: p1, piaMonthly: 2100, earnings: null, claimAge: { years: 70, months: 0 } },
+  ]
+
+  plan.strategies = {
+    withdrawalOrder: { mode: 'sequential' },
+    rothConversion: { mode: 'fillToTarget', target: 'topOfBracket', targetValue: 22, startYear: EXAMPLE_FIXED_YEAR + 1, endYear: EXAMPLE_FIXED_YEAR + 9 },
+    qcdAnnual: 3000,
+  }
+
+  plan.assumptions = {
+    inflationPct: 2.5,
+    healthcareExtraInflationPct: 3.1,
+    defaultReturnPct: 5.0,
+    ssCola: { mode: 'matchInflation' },
+    ssHaircut: null,
+    stateEffectiveTaxPct: 0,
+    localIncomeTaxPct: 0,
+    recentAnnualMagi: 95000,
+    heirTaxRatePct: 26,
+    safeWithdrawalRatePct: 3.7,
+    // Optional class overrides to highlight drag/returns (additive)
+    assetClassParams: {
+      usStocks: { returnPct: 7.2, volatilityPct: 16 },
+      bonds: { returnPct: 4.1, volatilityPct: 6 },
+    },
+  }
+
+  // Scenario: single-factor (no allocation) to contrast MC risk
+  plan.scenarios = [
+    {
+      id: exampleEntityId(EXAMPLE_ID, 'single-return'),
+      name: 'Single return (no allocation)',
+      patch: {
+        accounts: plan.accounts.map((a: Account) => ({ ...a, allocation: undefined, annualReturnPct: 5.0 })),
+      },
+    },
+  ]
+
+  const parsed = parsePlan(plan)
+  if (!parsed.ok) throw new Error(`glidepath-allocation invalid: ${parsed.issues.join('; ')}`)
+  return parsed.plan
+}

package/src/planner/examples/buildGuardrailsFlex.ts

@@ -0,0 +1,120 @@
+/** Guardrails + flexible goals — positive/negative demonstration of required floor protection,
+ * discretionary cuts, movable/skippable/partial goals, and layered MC success rates.
+ * Exercises spending guardrails enhancement + MC/Insights surfaces.
+ */
+
+import { createEmptyPlan, parsePlan, type Plan } from '@retiregolden/engine/model/plan'
+import { EXAMPLE_FIXED_YEAR, exampleEntityId, exampleFixedNow, exampleIdFactory } from './buildContext'
+
+const EXAMPLE_ID = 'guardrails-flex-goals'
+
+export function buildGuardrailsFlex(): Plan {
+  const p1 = exampleEntityId(EXAMPLE_ID, 'p1')
+  const plan = createEmptyPlan({ name: 'Guardrails and flexible goals', now: exampleFixedNow, newId: exampleIdFactory(EXAMPLE_ID) })
+
+  plan.household = {
+    filingStatus: 'single',
+    hasQualifyingDependent: false,
+    state: 'KY',
+    stateMoves: [],
+    capitalLossCarryforward: 0,
+    people: [
+      { id: p1, name: 'Riley', dob: '1963-06-15', sex: 'female', retirementAge: 62, longevity: { planningAge: 92, source: 'manual' } },
+    ],
+  }
+
+  plan.accounts = [
+    { type: 'cash', id: exampleEntityId(EXAMPLE_ID, 'cash'), name: 'Cash reserve', ownerPersonId: null, annualReturnPct: 2.0, balance: 85_000, annualContribution: 0 },
+    { type: 'taxable', id: exampleEntityId(EXAMPLE_ID, 'brokerage'), name: 'Taxable brokerage', ownerPersonId: null, annualReturnPct: null, balance: 420_000, costBasis: 280_000, annualContribution: 0 },
+  ]
+
+  // Core spending layers for guardrails demo
+  plan.expenses = {
+    baseAnnual: 58_000,
+    requiredAnnual: 34_000, // protected floor
+    idealAnnual: 12_000,    // aspirational layer
+    excessAnnual: 6_000,    // opportunistic
+    phases: [
+      { fromAge: 78, multiplier: 0.92 },
+    ],
+    oneTimeGoals: [
+      // Fixed essential (high priority)
+      {
+        id: exampleEntityId(EXAMPLE_ID, 'roof'),
+        label: 'Roof replacement (required)',
+        year: EXAMPLE_FIXED_YEAR + 4,
+        amount: 28_000,
+        classification: 'required',
+        flexibility: 'fixed',
+        priority: 1,
+      },
+      // Movable target goal (can slide in bad markets)
+      {
+        id: exampleEntityId(EXAMPLE_ID, 'trip'),
+        label: 'Big anniversary trip (target)',
+        year: EXAMPLE_FIXED_YEAR + 2,
+        amount: 18_000,
+        classification: 'target',
+        flexibility: 'movable',
+        earliestYear: EXAMPLE_FIXED_YEAR + 1,
+        latestYear: EXAMPLE_FIXED_YEAR + 5,
+        priority: 10,
+        allowPartialFunding: true,
+        minFundingPct: 60,
+      },
+      // Skippable ideal (low priority)
+      {
+        id: exampleEntityId(EXAMPLE_ID, 'gift'),
+        label: 'Family gift / remodel (ideal)',
+        year: EXAMPLE_FIXED_YEAR + 6,
+        amount: 35_000,
+        classification: 'ideal',
+        flexibility: 'skippable',
+        earliestYear: EXAMPLE_FIXED_YEAR + 3,
+        latestYear: EXAMPLE_FIXED_YEAR + 8,
+        priority: 30,
+      },
+    ],
+    healthcare: { pre65MonthlyPremiumPerPerson: 720, applyAcaCredit: true, medicareExtrasMonthlyPerPerson: 190 },
+    spendingPolicy: {
+      mode: 'withdrawalRateGuardrails',
+      upperGuardrailPct: 125,
+    },
+  }
+
+  plan.incomes = [
+    { type: 'socialSecurity', id: exampleEntityId(EXAMPLE_ID, 'ss'), personId: p1, piaMonthly: 1850, earnings: null, claimAge: { years: 67, months: 0 } },
+  ]
+
+  plan.strategies = {
+    withdrawalOrder: { mode: 'sequential' },
+    rothConversion: { mode: 'none' },
+    qcdAnnual: 0,
+  }
+
+  plan.assumptions = {
+    inflationPct: 2.4,
+    healthcareExtraInflationPct: 3.2,
+    defaultReturnPct: 4.8,
+    ssCola: { mode: 'matchInflation' },
+    ssHaircut: null,
+    stateEffectiveTaxPct: 0,
+    localIncomeTaxPct: 0,
+    recentAnnualMagi: 0,
+    heirTaxRatePct: 24,
+    safeWithdrawalRatePct: 3.8,
+  }
+
+  // Scenario to compare guardrails off (for side-by-side)
+  plan.scenarios = [
+    {
+      id: exampleEntityId(EXAMPLE_ID, 'no-guard'),
+      name: 'No guardrails (full target always)',
+      patch: { expenses: { spendingPolicy: undefined, requiredAnnual: undefined } },
+    },
+  ]
+
+  const parsed = parsePlan(plan)
+  if (!parsed.ok) throw new Error(`guardrails-flex-goals invalid: ${parsed.issues.join('; ')}`)
+  return parsed.plan
+}