Configuration Reference

Scenario settings live in scenarios/*.toml files. Each file is a complete self-contained financial plan.

All config keys use snake_case (lowercase with underscores). Section headers are also lowercase or snake_case.

Top-Level Sections

[scenario]

[scenario]
name = "My Retirement Plan"         # Human-readable name
slug = "myplan"                     # URL-friendly ID (used in --scenario flag)
description = "A comfortable retirement with regular travel."
household_type = "couple"           # "single" or "couple" (inferred from [person2] if absent)
is_default = false                  # Marks this as the default scenario
is_template = true                  # Hidden from UI dropdown (for starter templates only)

[simulation]

[simulation]
start_year = 2026
end_year = 2060
render_modes = ["deterministic", "historical", "monte_carlo"]
num_runs = 1000                     # Monte Carlo simulation count
seed = 42                           # Random seed for reproducible MC results
portfolio_return_volatility = 0.12  # Annual return volatility for MC sampling
historical_returns_path = "config/return_sequences/us_balanced_returns.csv"
value_basis = "both"                 # "nominal" (default), "real", or "both"

value_basis — Controls how monetary figures are displayed. "nominal" (default) shows projected future-year dollars, single chart pass. "real" deflates all values to start-year purchasing power (e.g. 2026 dollars), single chart pass. "both" renders both views with a toggle pill (💰 Real | 📊 Nominal) below the KPI strip — your preference is saved across page reloads — but uses two chart passes. For backward compatibility, the old real_dollar_basis = true maps to value_basis = "both".

[data_source]

[data_source]
mode = "synthetic"                  # "monarch", "synthetic", or "csv_import"

[synthetic_start]

Used only when [data_source].mode = "synthetic":

[synthetic_start]
taxable = 120000
trad_ira = 380000
roth = 95000
cash = 45000
home_value = 620000
vehicles = 0
taxable_cost_basis = 0
roth_contribution_basis = 0

[person1] / [person2]

[person1]
name = "Alex"
dob = "1972-06-15"                 # YYYY-MM-DD format

# Income
annual_take_home = 130000          # Net (take-home) income
annual_take_home_real_raise = 0.01 # Annual real raise above inflation
gross_income = 180000              # Gross income (for contribution calculations)
contribution_method = "percent_of_gross"
retirement_contribution_percent = 0.24
annual_401k_contribution_split = { trad_ira = 0.70, roth = 0.30 }
annual_ira_contribution = 0
rmd_trad_ira_share = 0.50          # Person's share for RMD math
roth_share = 0.50                  # Fallback share of pooled Roth balances

# Social Security (age-keyed monthly amounts)
[person1.social_security_benefits]
67 = 2600
70 = 3200

Timeline settings are event-driven in v2. Add Retire, SocialSecurity, and EndOfPlan records under [[events]]; see Event Types. Person-level retirement_year and life_expectancy remain only as legacy compatibility fallbacks.

[spending]

[spending]
retirement_annual = 82000          # Annual spending in retirement (both alive)
survivor_percent_of_retirement = 0.70  # Survivor phase spending as % of retirement
survivor_annual = 60000             # Optional absolute survivor target; takes precedence
debt_service_handling = "auto_reduce"  # "auto_reduce" or "included_in_target"

[withdrawal_policy]

[withdrawal_policy]
accumulation_cash_target = 40000
retirement_cash_target = 50000
survivor_cash_target = 30000

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"]
survivor_withdrawal_order = ["cash_above_target", "trad_ira", "taxable", "roth", "cash_below_target"]

accumulation_surplus_order = ["roth", "taxable"]
retirement_surplus_order = ["roth", "taxable"]
survivor_surplus_order = ["roth", "taxable"]

[assumptions]

[assumptions]
stock_return = 0.07
bond_return = 0.035
inflation = 0.03
equity_allocation = 0.70

[[liabilities]]

[[liabilities]]
name = "Home Mortgage"
annual_rate = 0.065
monthly_base = 1675
monthly_escrow = 420              # Property tax + insurance (subtracted from freed cash)
monthly_extra = 0
type = "mortgage"

[[liabilities]]
name = "RAV4 Hybrid Auto Loan"
annual_rate = 0.049
monthly_base = 495
monthly_extra = 0
type = "auto"

[[events]]

See the Event Types page for the full schema of each event type.

[accounts]

Used only in Monarch or CSV Import mode:

[accounts]
disabled = ["Account Name A", "Account Name B"]

"Vanguard Traditional IRA" = { category = "trad_ira", owner = "person1" }
"Vanguard Roth IRA" = { category = "roth", owner = "person2" }
"Checking" = "cash"