Scenario Setup

Data Source

Manual Starting Balances

Property Values

Liabilities

# Net Worth Navigator — Single-Person Sample Plan (Reference Documentation)
#
# This file demonstrates how to configure a single-person household.  It uses
# synthetic starting balances (no Monarch account needed).
#
# Household: Alex (person1, b. 1972). Single, working into their 60s,
# contributing to 401(k)/IRA, owns a home with a mortgage and a car loan.
#
# Key differences from the couples version (sample-couples.toml):
# - No [person2] section — household_type auto-infers as "single"
# - No survivor spending phase — it is not applicable
# - Tax filing status defaults to "single" instead of "married_joint"
# - Social Security survivor benefit logic is not applied
# - All person2-referencing fields are omitted
#
# Scenario files are TOML. Fields can be commented out with #.
# Events can be toggled on/off with enabled = true/false without deleting them.
# All monetary values are in today's USD unless noted.

[scenario]
name        = "Sample Plan (Single-Person)"
slug        = "sample"
description = "Single-person share-safe reference scenario with full inline documentation."
is_default  = false
# household_type is omitted — inferred as "single" from absence of [person2]
# To explicitly set:  household_type = "single"
household_type = "single"

[data_source]
mode = "synthetic" # synthetic | monarch

[synthetic_start]
# Investable buckets
taxable  = 120000
trad_ira = 580000
roth     = 95000
cash     = 45000
# Optional explicit basis seeds (if omitted, defaults to 50% taxable cost basis,
# 100% Roth contribution basis):
# taxable_cost_basis = 84000
# roth_contribution_basis = 70000
# Non-investable balances
home_value = 620000
vehicles   = 0
other      = 0

# Named property balances for SellHome / property-tracking events
[synthetic_start.property_values]
"Town Home" = 620000

# Named liability balances (must match [[liabilities]].name entries)
[synthetic_start.liability_balances]
"Town Home"   = 365000
"RAV4 Hybrid" = 28000

[simulation]
start_year = 2026
end_year   = 2062

# value_basis controls which dollar basis is rendered:
# - "nominal": future/inflated dollars only (default)
# - "real": today's-dollars, inflation-adjusted (today's purchasing power)
# - "both": renders both sets and lets you toggle between them in the UI —
#   costs more render time since every series is computed twice
value_basis = "both"

render_modes = [
   "deterministic",
   "historical",
   "monte_carlo"
] # shell/render pipeline outputs these mode variants
mode = "deterministic" # compatibility/default single-run mode
# num_runs = 250                       # Monte Carlo run count (default 250)
# seed = 12345                         # reproducibility seed
# portfolio_return_volatility = 0.15   # annual stdev for blended investable return
# historical_returns_path     = "config/return_sequences/us_balanced_returns.csv"
num_runs = 250
portfolio_return_volatility = 0.15
clamp_start_year = true

[display]
projection_title = "Single-Person Sample (Synthetic Demo)"

[monte_carlo.success] # success/failure rules for all stochastic modes: monte_carlo and historical
failure_mode = "liquid_depletion"
# Possible values:
# - "net_worth_below_zero"
# - "liquid_depletion"
# - "spending_shortfall"
# - "preserve_home_equity"
# - "custom"
minimum_spending_funded_ratio  = 1.0
allow_home_equity_for_spending = false
allow_debt_for_spending        = false
failure_grace_period_months    = 0

# Additional stochastic risk metrics shown in the UI/sidecars
# (for example Probability of Home Equity Required) are derived
# from these rules and do not require extra TOML fields.

# Optional custom mode controls:
# custom_failure_column = "spending_funded_ratio"
# custom_failure_operator = "<"
# custom_failure_threshold = 1.0
custom_failure_operator = "<"

# ─── Household Members ────────────────────────────────────────────────────────

[person1]
name            = "Alex"
dob             = "1972-03-15" # YYYY-MM-DD
life_expectancy = 90           # modeled terminal age (not a prediction)

# Employment income inputs (annual, nominal dollars)
# ANCHORED AT start_year — known current values, grown forward automatically.
# Refresh: replace with prior year's W-2 actuals each January at tax time.
annual_take_home                                    = 62000 # net-cash wage input (see [taxes].wage_tax_treatment)
annual_take_home_is_net_of_retirement_contributions = true  # true = do NOT subtract payroll contributions again
annual_take_home_real_raise                         = 0.01  # real raise above inflation

# Retirement contributions — percentage of gross income
contribution_method                             = "percent_of_gross"
gross_income                                    = 90000              # gross annual income (used for contribution math only)
gross_income_annual_increase_percent            = 0.04               # combined COLA + performance
retirement_contribution_percent                 = 0.20               # 20% of gross income
retirement_contribution_annual_increase_percent = 0.00               # no auto-escalation
retirement_contribution_max_percent             = 0.30               # never exceed 30% of gross

# Employer match
# annual_401k_employer_match = 6513                   # flat annual employer 401(k) match
annual_401k_employer_match_mode        = "percent_of_gross" # "flat" (default) | "percent_of_gross"
annual_401k_employer_match_rate        = 1.0                # e.g. 0.50 = 50% match on each dollar contributed
annual_401k_employer_match_max_percent = 0.06               # e.g. 0.06 = match applies to first 6% of salary
annual_ira_contribution                = 0                  # direct IRA contribution modeled as cash outflow + bucket deposit

# Optional routing override for explicit contribution deposits
# annual_401k_contribution_bucket = "trad_ira"  # valid: trad_ira | roth
# annual_ira_contribution_bucket  = "roth"      # valid: trad_ira | roth
annual_401k_contribution_bucket = "trad_ira"
annual_ira_contribution_bucket = "roth"

# Share of household traditional retirement balance attributed to this person for RMD math.
# If both shares are omitted/invalid, model defaults to 50/50 while both alive.
rmd_trad_ira_share  = 1.0

# Used when Roth accounts have no owner assignment: splits the pooled opening Roth balance between people and 
# attributes shared Roth flows. Account-level owner assignments override this. Defaults to 50/50 if left blank
# for both people.
roth_share          = 1.0

# Social Security benefit options (from SSA.gov estimates):
[person1.social_security_benefits]
"62" = 1900
"63" = 2040
"64" = 2190
"65" = 2360
"66" = 2540
"67" = 2720
"68" = 2910
"69" = 3110
"70" = 3320

[person1.annual_401k_contribution_split]
trad_ira = 0.70
roth     = 0.30

# NOTE: No [person2] section is present.  The engine auto-infers
# household_type = "single" and skips all person2 logic.

# ─── Spending ─────────────────────────────────────────────────────────────────

[spending]
# Retirement spending baseline (household)
# Units: annual dollars in today's purchasing power when spending_basis = "real".
# With spending_basis = "real", model inflates this forward by CPI each year.
retirement_annual = 60000 # annual spending target (single person)
# spending_basis options:
# - "real": inputs above are interpreted in today's dollars and CPI-adjusted per year
# - "nominal": inputs are treated as fixed nominal dollars (no CPI growth)
spending_basis = "real"
# debt_service_handling controls how mortgage/loan P&I payments interact with retirement_annual:
# - "auto_reduce": retiement_annual is treated as NOT including debt service.
#   While a loan is active in retirement, its P&I (principal + interest, minus
#   escrow) is automatically added on top of retirement_annual each year. Once
#   the loan is paid off, that amount drops back out on its own — no manual
#   spending-target adjustment needed.
# - "included_in_target" (or any other value): retirement_annual is assumed to
#   already bake in debt service as entered. Nothing is added while the loan
#   is active, but once it's paid off the freed P&I shows up as extra surplus
#   cash flow (see the "Debt service freed" row) since the target itself
#   doesn't shrink automatically.
debt_service_handling = "auto_reduce"

# ─── Withdrawal Policy ─────────────────────────────────────────────────────────

[withdrawal_policy]
# Cash reserve targets by phase
# - accumulation: roughly 6 months of essential outflows (child-free, secure jobs, good insurance)
# - retirement:   roughly 8 months — no wage income to replenish
# - survivor:     roughly 6 months — one person, lower spending
accumulation_cash_target = 30000
retirement_cash_target   = 55000

# Withdrawal order when cash is below target (which buckets to sell first)
# cash_above_target uses only dollars above the reserve.
# cash_below_target taps the reserve itself only as a last resort.
accumulation_withdrawal_order = [
   "cash_above_target",
   "taxable",
   "roth",
   "trad_ira",
   "cash_below_target"
]
retirement_withdrawal_order = [
   "cash_above_target",
   "trad_ira",
   "taxable",
   "roth",
   "cash_below_target"
]
# Surplus reinvestment order when cash is above target (which buckets get the extra)
# This is phase-specific and independent from withdrawal order.
# Ordered priority: first non-excluded bucket gets ALL remaining surplus.
# Default order: Roth first (tax-free growth), then taxable brokerage,
# then remaining stays in cash.
# Valid buckets here: taxable, roth, trad_ira (no cash_* steps).
# If first choice is excluded in-year (e.g., trad_ira during forced RMD routing),
# the model automatically falls through to the next bucket in this order.
accumulation_surplus_order = ["taxable", "roth", "trad_ira"]
retirement_surplus_order   = ["taxable", "roth", "trad_ira"]

# survivor_* fields are not applicable and ignored for single-person households
# survivor_cash_target = 30000
# survivor_withdrawal_order = [
#    "cash_above_target",
#    "trad_ira",
#    "taxable",
#    "roth",
#    "cash_below_target"
# ]
# survivor_surplus_order = ["roth", "taxable"]

# ─── Market & Economic Assumptions ───────────────────────────────────────────
survivor_withdrawal_order = ["cash_above_target", "trad_ira", "taxable", "roth", "cash_below_target"]
survivor_surplus_order = ["roth", "taxable"]

[assumptions]
stock_return              = 0.07 # annual nominal return on equities
bond_return               = 0.04 # annual nominal return on bonds
inflation                 = 0.03 # annual inflation rate
cash_return               = 0.03 # annual return on cash buckets (defaults to inflation if omitted)
real_estate_appreciation  = 0.03 # annual home-value appreciation
equity_allocation         = 0.70 # fraction of investable portfolio in equities (rest in bonds)
real_estate_sale_fee_rate = 0.06 # fee deducted from gross sale proceeds

effective_tax_rate_pre_retirement  = 0.22 # legacy flat-tax fallback (see [taxes] for current model)
effective_tax_rate_post_retirement = 0.15 # legacy flat-tax fallback

# Account-mechanics defaults
taxable_withdrawal_taxable_fraction  = 0.50 # 50% of taxable withdrawals are realized gains
trad_ira_withdrawal_taxable_fraction = 1.00 # 100% of traditional withdrawals are taxable
# initial_taxable_cost_basis_fraction = 0.50
# initial_roth_contribution_basis_fraction = 1.00

[taxes]
# Toggle for detailed bracket-based tax model.
enabled   = true
table_set = "2025_us_federal_oregon" # shared tax table reference in config/tax_tables/
# For single-person households, filing status defaults to "single"
# for both pre_retirement and retirement phases (survivor is not applicable)
pre_retirement_filing_status = "single" # single | married_joint
retirement_filing_status     = "single" # single | married_joint
# Wage handling mode:
# - net_cash: annual_take_home is treated as after-tax cashflow only (default/current)
# - taxable_wages: annual_take_home is treated as taxable wage income (not currently implemented)
wage_tax_treatment = "net_cash" # "net_cash" (current) | "taxable_wages" (future)
survivor_filing_status = "single"

[taxes.rmd]
# Required Minimum Distribution modeling controls.
# enabled=true forces annual traditional-account withdrawals at/after start_age.
# Forced RMD withdrawals increase modeled cash flow and taxable ordinary income.
enabled   = true
start_age = 73

# ─── Liabilities ──────────────────────────────────────────────────────────────
# Each liability is amortized year-by-year in the model.
# current_balance is pulled live from Monarch by matching the account name (if using Monarch sync)
# The freed monthly payment is added back to cash flow from the payoff year onward.
# type = "mortgage" means payoff is also reflected in home equity tracking.

[[liabilities]]
name           = "Town Home"     # must match asset account name exactly
annual_rate    = 0.0575
monthly_base   = 2163            # contractual P&I payment
monthly_escrow = 494.54          # escrowed property tax + insurance
monthly_extra  = 200             # voluntary extra principal payment
type           = "mortgage"

[[liabilities]]
name          = "RAV4 Hybrid"
annual_rate   = 0.065
monthly_base  = 550
monthly_extra = 0
type          = "auto"

# ─── Financial Events ─────────────────────────────────────────────────────────
# Each [[events]] block is one event. Set enabled = false to exclude it from
# the current run without deleting configuration.
#
# Event types and required fields:
# ┌─────────────────────┬──────────────────────────────────────────────────────┐
# │ EndOfPlan           │ person, year — zeroes income, triggers SS survivor   │
# │ Retire              │ person, year — permanent stop to wages (runtime)     │
# │ SocialSecurity      │ person, year, monthly_benefit                        │
# │ Expense             │ year, amount (negative), optional expense_kind/      │
# │                     │   repeat_every_years, chart_first_occurrence_only    │
# │ Income              │ year, amount (positive), optional end_year, taxable  │
# │ BuyHome / SellHome  │ year + property/mortgage fields                      │
# │ NewJob / CareerBreak│ person, year/start_year/end_year, income fields      │
# │ Education           │ person, start_year, end_year, annual_cost            │
# │ SpendingShift       │ start_year, mode, optional end_year                  │
# │ ContributionChange  │ year, person + contribution/employer override fields │
# │ Marriage            │ year (informational)                                 │
# └─────────────────────┴──────────────────────────────────────────────────────┘
#
# Recurring controls: repeat_every_years, repeat_until_year, repeat_count
# Chart decluttering:   chart_first_occurrence_only = true (show only first label)
#
# Quick copy/paste templates (required fields first; optional fields commented)
#
# --- EndOfPlan ---
# [[events]]
# enabled = true
# type    = "EndOfPlan"
# label   = "End of Plan (M)"
# person  = "person1"
# year    = 2057
#
# --- Retire (usually auto-generated) ---
# [[events]]
# enabled = true
# type    = "Retire"
# label   = "Retirement (M)"
# person  = "person1"
# year    = 2037
#
# --- SocialSecurity (usually auto-generated) ---
# [[events]]
# enabled         = true
# type            = "SocialSecurity"
# label           = "Social Security (M)"
# person          = "person1"
# year            = 2037
# monthly_benefit = 3698
# # taxable = true
# # taxable_fraction = 0.85
#
# --- Expense ---
# [[events]]
# enabled = true
# type    = "Expense"
# label   = "One-time expense"
# year    = 2032
# amount  = -12000
# # expense_kind = "mandatory"   # or "discretionary"
# # funding      = "cash_reserve_first"  # optional: let this expense tap reserve cash before roth/trad withdrawals
# # repeat_every_years = 1
# # repeat_until_year  = 2036
# # repeat_count       = 5
# # chart_first_occurrence_only = true
#
# --- Income ---
# [[events]]
# enabled = true
# type    = "Income"
# label   = "Consulting"
# year    = 2037
# amount  = 40000
# # end_year = 2041
# # taxable  = true
# # taxable_fraction   = 1.00
# # repeat_every_years = 1
# # repeat_until_year  = 2041
# # chart_first_occurrence_only = false
#
# --- BuyHome ---
# [[events]]
# enabled      = true
# type         = "BuyHome"
# label        = "Condo Purchase"
# year         = 2058
# down_payment = 200000
# # price = 200000
# # property = "Indonesia House"   # optional stable name for later SellHome
# # mortgage_rate = 0.065
# # term_years = 30
#
# --- SellHome ---
# [[events]]
# enabled  = true
# type     = "SellHome"
# label    = "Sell Casa Lemuria"
# year     = 2058
# property = "Casa Lemuria"
# # liability_names = ["Mortgage (5156)"]
# # sale_fee_rate = 0.06
# # reinvest_to = "taxable"
# # reinvest_fraction = 1.0
#
# --- NewJob ---
# [[events]]
# enabled       = true
# type          = "NewJob"
# label         = "New job"
# person        = "person1"
# year          = 2028
# annual_income = 90000
#
# --- CareerBreak ---
# [[events]]
# enabled    = true
# type       = "CareerBreak"
# label      = "Career break"
# person     = "person1"
# start_year = 2030
# end_year   = 2031
#
# --- Education ---
# [[events]]
# enabled     = true
# type        = "Education"
# label       = "Education"
# person      = "person2"
# start_year  = 2028
# end_year    = 2030
# annual_cost = 15000
#
# --- Marriage ---
# [[events]]
# enabled = true
# type    = "Marriage"
# label   = "Marriage"
# year    = 2028
#
# --- SpendingShift ---
# [[events]]
# enabled = true
# type    = "SpendingShift"
# label   = "Spending shift"
# year    = 2047
# mode    = "replace"
# # phase = "retirement_and_survivor"   # retirement | survivor | retirement_and_survivor
# # end_year = 2055
# # retirement_annual = 50000
# # survivor_percent_of_retirement = 0.75
# # survivor_annual = 42000
#
# --- ContributionChange ---
# Override one or more per-person contribution amounts from a given year onward.
# Useful for restoring full 401(k) contributions after an early mortgage payoff,
# or stepping down contributions before a planned career break.
# [[events]]
# enabled = true
# type    = "ContributionChange"
# label   = "401k step-up (mortgage paid off)"
# year    = 2033
# person  = "person1"                     # person1 or person2
# annual_401k_contribution = 24225        # new absolute dollar amount
# annual_401k_contribution_delta = 12000  # new delta dollar amount dollar amount
# annual_ira_contribution  = 7000         # optional: also change IRA contribution
# annual_ira_contribution_delta = -2000   # optional: new delta IRA change
# annual_401k_employer_match = 5688       # optional: also change employer match
# annual_401k_employer_match_delta = 0    # optional: new employer match delta dollar amount
# ──────────────────────────────────────────────────────────────────────────────

# ─── Plan Boundary / Life Expectancy ───────────────────────────────────────

[[events]]
enabled = true
type    = "EndOfPlan"
label   = "End of Plan (Alex)"
person  = "person1"
year    = 2062 # 1972 + 90

# ─── Pre-Retirement / Near-Term Known Events ───────────────────────────────

[[events]]
enabled      = true
type         = "Expense"
label        = "Surgery"
year         = 2026
amount       = -12000
expense_kind = "mandatory"
funding      = "cash_reserve_first"

# ─── Retirement / Social Security ───────────────────────────────

[[events]]
enabled = true
type    = "SocialSecurity"
label   = "SS Begins (A)"
person  = "person1"
year    = 2039


[[events]]
enabled = true
type    = "Retire"
label   = "Retirement (A)"
person  = "person1"
year    = 2040

# Bounded side income during early retirement
[[events]]
enabled  = true
type     = "Income"
label    = "Part-time consulting"
year     = 2038
amount   = 18000
end_year = 2042
taxable  = true

# ─── Lifestyle Before and During Retirement ────────────────────────────────

# Recurring travel (every other year, starting in 2027)
[[events]]
enabled      = true
type         = "Expense"
label        = "Travel"
year         = 2027
amount       = -8000
expense_kind = "discretionary"
funding      = "cash_reserve_first"
repeat_every_years = 2
repeat_until_year  = 2055

chart_first_occurrence_only = true

# ─── Home Ownership / Fixed Housing Costs ──────────────────────────────────

# Annual home maintenance reserve
[[events]]
enabled      = true
type         = "Expense"
label        = "Home maintenance reserve"
year         = 2026
amount       = -3500
expense_kind = "mandatory"
funding      = "cash_reserve_first"
repeat_every_years = 1
chart_first_occurrence_only = true

# ─── Post-Mortgage Housing Costs ────────────────────────────────────────────
# The mortgage's escrow currently covers these costs.  The amortization schedule
# pays off the Town Home during 2049, so begin direct payments in 2050.
[[events]]
enabled      = true
type         = "Expense"
label        = "Property taxes"
year         = 2050
amount       = -4700
expense_kind = "mandatory"
repeat_every_years = 1
chart_first_occurrence_only = true

[[events]]
enabled      = true
type         = "Expense"
label        = "Homeowners insurance"
year         = 2050
amount       = -1250
expense_kind = "mandatory"
repeat_every_years = 1
chart_first_occurrence_only = true

# ─── Retirement Health Coverage ────────────────────────────────────────────

# Alex is Medicare-eligible before retirement.  Use separate recurring events
# so the assumed annual coverage cost can rise in later life.
[[events]]
enabled      = true
type         = "Expense"
label        = "Medicare premiums and supplement"
year         = 2040
amount       = -5400
expense_kind = "mandatory"
repeat_every_years = 1
repeat_until_year  = 2051
chart_first_occurrence_only = true

[[events]]
enabled      = true
type         = "Expense"
label        = "Later-life health coverage"
year         = 2052
amount       = -8400
expense_kind = "mandatory"
repeat_every_years = 1
chart_first_occurrence_only = true

# ─── Major Home and Vehicle Capital Expenses ───────────────────────────────

[[events]]
enabled      = true
type         = "Expense"
label        = "Vehicle purchase"
year         = 2032
amount       = -26000
expense_kind = "mandatory"
funding      = "cash_reserve_first"

[[events]]
enabled      = true
type         = "Expense"
label        = "HVAC replacement"
year         = 2034
amount       = -12000
expense_kind = "mandatory"
funding      = "cash_reserve_first"

# One-time large home repairs
[[events]]
enabled      = true
type         = "Expense"
label        = "Roof replacement"
year         = 2043
amount       = -18000
expense_kind = "mandatory"
funding      = "cash_reserve_first"

[[events]]
enabled      = true
type         = "Expense"
label        = "Vehicle replacement"
year         = 2044
amount       = -30000
expense_kind = "mandatory"
funding      = "cash_reserve_first"

# ─── Elder Care / Parent Death ───────────────────────────────────────

[[events]]
enabled      = true
type         = "Expense"
label        = "Care support"
year         = 2053
amount       = -25000
expense_kind = "mandatory"
funding      = "cash_reserve_first"
repeat_every_years = 1
repeat_until_year  = 2055
chart_first_occurrence_only = true

[[events]]
enabled      = true
type         = "Expense"
label        = "Parent estate and funeral costs"
year         = 2056
amount       = -15000
expense_kind = "mandatory"
funding      = "cash_reserve_first"

[[events]]
enabled = true
type    = "Income"
label   = "Small inheritance"
year    = 2056
amount  = 50000
taxable = false