User Guide

Everything you need to build your portfolio file: all parameters, account types, and worked examples.

Quick Start

Three steps to your first report:

1. Open the sample portfolio file — it generates a Full Report with real estate, analytics, and performance sections. Copy the text into any text editor.

2. Replace the sample values with your own holdings, ticker symbols, and share counts. Add as many accounts as you like.

3. Use your custom file to generate your own PDF report.

Share count is all you need. Just enter the number of shares you hold. We fetch the latest market price automatically to calculate dollar amounts.
Want just rebalancing recommendations? Change report_type to rebalance — you only need your holdings and target equity/debt ratio, no date of birth or income required. See Report Types below.

File Structure Overview

A portfolio file has this top-level shape:

target_equity_debt_ratio: 70/30     # e.g. 80/20, 70/30, 60/40
taxable_sales_allowed: true         # true or false
annual_income: 180000               # for STCG / LTCG tax estimates

target_equity:
  VTI:
    pct: 50

target_debt:
  AGG:
    pct: 20

accounts:
  - name: Individual
    ...

Fields Reference

FieldDescription
target_equity_debt_ratio Target split between equity and bonds, written as equity%/debt%. Example: 70/30. Both sides must sum to 100.
taxable_sales_allowed true or false. Whether the engine can recommend selling in taxable accounts. Set to false to avoid triggering capital gains — the engine will only suggest buys and tax-free trades.
annual_income Your gross annual income. Used to calculate your federal tax bracket for STCG and LTCG estimates in the Tax Notes section. Without it, tax cost columns show ??. Accepts commas and $: $180,000. Required for report_type: full.
target_equity Map of equity tickers to their target percentage of the total investable portfolio. See target_equity / target_debt.
target_debt Map of bond tickers to target percentages. Same structure as target_equity. Omit only if you hold no bonds.
accounts List of brokerage accounts with holdings. At least one account required. See accounts.
drift_band_taxfree Optional. Minimum drift % before the engine trades in tax-advantaged (Roth / deferred) accounts. Default: 2. Minimum: 0.5. See Drift Bands.
drift_band_taxable Optional. Minimum drift % before the engine sells in taxable accounts. Default: 5. Minimum: 0.5. See Drift Bands.
report_type Optional. rebalance (default) or full. See Report Types for what each includes and which extra fields are required.
dob_year Your birth year as a 4-digit number. Example: 1985. Used for age-based risk scoring. Required for report_type: full.
retirement_age Optional. Your planned retirement age. Defaults to 67 if not set — the report will show a notice when the default is assumed. Used for risk capacity scoring.
name_initials Optional. Your initials, shown on the report cover. Example: NC.

target_equity / target_debt

Both maps have identical structure: a ticker symbol key and a pct value.

FieldTypeDescription
pctnumberTarget percentage of the total investable portfolio this ticker should represent. All equity pcts + all debt pcts must sum to 100 (or match the ratio in target_equity_debt_ratio).
target_equity:
  VTI:   pct: 50    # 50% total portfolio in VTI
  VEA:   pct: 15
  VWO:   pct: 5
  QQQ:   pct: 10

target_debt:
  AGG:   pct: 15
  SCHR:  pct: 5
The equity percentages (50+15+5+10 = 80) plus debt percentages (15+5 = 20) equal 100, matching target_equity_debt_ratio: 80/20.

accounts

A list of all your brokerage and investment accounts. Each account must have at minimum: name, type, company, and either holdings or cash_holding.

FieldRequiredDescription
namerequiredDisplay name shown in the report. e.g. Roth IRA, Individual Taxable.
typerequiredAccount tax type. One of: taxable, roth, deferred. See Account Types.
companyrequiredBroker name for display. e.g. Fidelity, Schwab, Vanguard.
holdingsoptional*List of ticker holdings in this account. Required unless cash_holding is used instead.
cash_holdingoptionalDollar amount of cash or cash-equivalent in this account. Use for CD or cash-only accounts. Can be combined with holdings.
cash_to_deployoptionalAmount of cash within this account to deploy into investments. The engine will recommend buys for this amount. Must be ≤ available cash in the account.
accounts:
  - name: Individual Taxable
    type: taxable
    company: Fidelity
    cash_to_deploy: 5000
    holdings:
      - ticker: VTI
        shares: 200
      - ticker: SPAXX
        shares: 12000

other_assets

Use other_assets for assets you want tracked in net worth but that are not part of rebalancing — CDs, 529 education funds, I-bonds, and similar cash-equivalent holdings.

FieldRequiredDescription
namerequiredDisplay name. e.g. 529 Education Fund, 18-Month CD.
descriptionoptionalFree-text note shown in the net worth table. e.g. Fidelity CD, matures 2026-12.
cash_holdingrequiredCurrent dollar value. Accepts commas: 85,000.
other_assets:
  - name: 529 Education Fund
    description: College savings plan (Fidelity)
    cash_holding: 85000

  - name: 18-Month CD
    description: Certificate of Deposit (Marcus), matures 2026-12
    cash_holding: 50000
other_assets appear as individual line items in the Net Worth table (Full Report only). They do not affect debt/equity allocation calculations.

holdings

Each entry in a holdings list represents one ticker position within the account.

FieldRequiredDescription
tickerrequiredTicker symbol. e.g. VTI, SPAXX, QQQ. Money market tickers (SPAXX, VMFXX, FDRXX, FZFXX, FMPXX, CORE, FCASH) are automatically treated as cash at $1.00.
sharesrequiredNumber of shares held. Decimals are accepted for fractional shares.
holdings:
  - ticker: VTI
    shares: 200
  - ticker: QQQ
    shares: 50.5    # decimals OK for fractional shares
  - ticker: SPAXX   # money market — always $1.00, treated as cash
    shares: 12000

Account Types

The type field on each account controls how the engine treats it for tax purposes and asset placement rules.

type valueAccount ExamplesBehavior
taxable Individual brokerage, joint account Selling triggers capital gains. Buys and sells here are subject to STCG/LTCG rules. Broad equity (VTI, VEA) is ideally placed here for qualified dividend treatment.
roth Roth IRA, Roth 401(k) Tax-free growth. Ideal for high-growth tickers (QQQ, VUG, MGK). The engine prioritizes growth ETFs in Roth accounts.
deferred Traditional IRA, 401(k), Rollover IRA, SEP-IRA Tax-deferred. Ideal for bonds and fixed income (AGG, BND, SCHR). No capital gains on internal trades.

Report Types

Set report_type at the top of your YAML file. The value controls which sections appear in the PDF and which fields are mandatory.

report_typeSections includedRequired fields
rebalance (default) Executive Summary · Recommended Swaps · Tax Notes · Step-by-Step Trades · Asset Location · Expense Ratio · Overlap · Concentration · Engine Philosophy · Disclaimer target_equity_debt_ratio
target_equity
accounts
full Everything in Rebalance, plus:
Net Worth · Risk Deep Dive · 5-Year Performance · Monte Carlo Simulation · Compound Growth Projections 		Everything above, plus:
dob_year — birth year for age & risk scoring
annual_income — income for tax bracket & risk scoring

Generating a Rebalance Report (minimum fields)

report_type: rebalance             # optional — this is the default
target_equity_debt_ratio: 70/30
taxable_sales_allowed: true

target_equity:
  VTI:   pct: 50
  QQQ:   pct: 20

target_debt:
  AGG:   pct: 30

accounts:
  - name: Individual
    type: taxable
    company: Fidelity
    holdings:
      - ticker: VTI
        shares: 100

Generating a Full Report (extra mandatory fields)

report_type: full                   # unlocks Net Worth, Risk, Performance
dob_year: 1985                      # REQUIRED for full — birth year
annual_income: 180000              # REQUIRED for full — gross income
retirement_age: 65                  # optional — defaults to 67 if omitted
name_initials: NC                   # optional — appears on report cover
target_equity_debt_ratio: 70/30
taxable_sales_allowed: true

target_equity:
  VTI:   pct: 50
  QQQ:   pct: 20

target_debt:
  AGG:   pct: 30

other_assets:                       # optional — shown in Net Worth only
  - name: 529 Education Fund
    cash_holding: 85000

accounts:
  - name: Individual
    type: taxable
    company: Fidelity
    holdings:
      - ticker: VTI
        shares: 100
If you set report_type: full but omit dob_year or annual_income, the engine will return an error listing exactly which fields are missing rather than generating a report with gaps.

Tips & Common Patterns

Money Market / Cash Tickers

The following tickers are automatically recognized as cash and valued at $1.00 per share:

SPAXX   VMFXX   FDRXX   FZFXX   FMPXX   CORE   FCASH

Dollar Formatting

Any dollar amount field accepts commas and $ signs:

annual_income: $180,000       # same as 180000
cash_holding: $50,000.00

Deploying Cash

Use cash_to_deploy on an account when you have cash sitting uninvested and want the engine to include it in buy recommendations. Do not include the cash amount separately as a holding, as it will be double-counted.

- name: Individual
  type: taxable
  company: Fidelity
  cash_to_deploy: 10000        # $10k to invest
  holdings:
    - ticker: SPAXX
      shares: 15000             # $15k total cash — $10k will be deployed

Tracking CDs, 529s, and Other Non-Investable Assets

Use the top-level other_assets list for any asset you want tracked in net worth but not included in rebalancing — CDs, education funds, I-bonds, etc.:

other_assets:
  - name: 529 Education Fund
    description: College savings plan (Fidelity)
    cash_holding: 85000

  - name: 18-Month CD
    description: Certificate of Deposit (Marcus)
    cash_holding: 50000

Blocking Taxable Sales

If you want to avoid triggering capital gains (e.g., late in the tax year), set taxable_sales_allowed: false. The engine will only recommend buys and tax-free account trades:

taxable_sales_allowed: false

Adjusting Drift Bands

The engine uses two separate drift thresholds to decide when a holding is far enough off-target to trigger a trade recommendation:

ParameterDefaultApplies toDescription
drift_band_taxfree 2% Tax-advantaged accounts (Roth IRA, Traditional IRA, 401k, etc.) Tighter band — trades in these accounts are tax-free, so the engine acts sooner.
drift_band_taxable 5% Taxable brokerage accounts Wider band — the engine waits for a larger drift before triggering a potentially taxable sale.

Add these optional fields at the top level of your YAML to override the defaults:

drift_band_taxfree: 3    # default 2 — raise to tolerate more drift in tax-advantaged accounts
drift_band_taxable: 7    # default 5 — raise to further reduce taxable trades
Minimum value for either band is 0.5%. Values below 0.5% cannot be closed by whole-share trades and will trigger false warnings.

Full Examples

Download any of these pre-built examples from the home page, or copy the file directly:

Minimal Valid Portfolio

The absolute minimum. Prices fetched live from Yahoo Finance.

target_equity_debt_ratio: 80/20

taxable_sales_allowed: true

annual_income: 120000

target_equity:
  VTI:
    pct: 80

target_debt:
  AGG:
    pct: 20

accounts:
  - name: Individual
    type: taxable
    company: Fidelity
    holdings:
      - ticker: VTI
        shares: 100
      - ticker: AGG
        shares: 50

Sample File

Open a ready-to-edit starting point:

  • sample_full.yaml: 6 accounts (Taxable, Roth IRA, Traditional IRA, Rollovers) + real estate + other assets, 90/10 target — Full Report