Household

Import holdings#

Account cash#

Enter uninvested US dollar cash in Account cash for each account. It uses the holdings snapshot date. Enter zero when the account reports no cash. Leave the field blank when the source does not report cash. Money-market and Treasury fund shares remain lots. Do not count their value again as account cash.

Account value, allocation drift, and planner starting balances include cash. Household Rebalancing uses cash before selling lots for withdrawals. Uninvested cash earns no modeled interest until the configured rebalance invests it. Retirement and tax planners apply their account return assumptions to the full starting balance, including cash. Outside cash entered as an outside asset does not fund these accounts.

A CSV can include a cash_balance column. Put one account balance on a separate row with empty ticker, shares, cost, and date fields. A cash-only file needs account_id,cash_balance. Preview shows cash before and after the import. Confirm each reduction or removal before saving. The parser rejects duplicate account cash rows.

A full-household import without a cash row removes the recorded balance after confirmation. Pasting lots inside one account preserves its cash unless the paste includes a cash balance.

Save your household accounts and target first. The setup panel then offers CSV import next to the manual holdings editor.

Import replaces current holdings across the household. Accounts missing from the CSV become empty, and the CSV cannot include option positions. Review these changes before saving.

1. Download the CSV template from the import panel, or choose your broker export format.
2. Replace the example row with your own lots. Include every household account that holds investments.
3. Set the snapshot date to the date those balances describe. Acquisition dates must be on or before that date.
4. Choose the CSV and select Review import.
5. Match each CSV account name to a saved household account. Review the parsed lots and fix any errors.
6. Review the previous and incoming lot counts for every account, then select Save reviewed holdings.

The template columns are account, symbol, shares, cost basis per share, and acquisition date. Use dates in YYYY-MM-DD format. Each row represents one lot. Replace every example value before importing.

The review requires separate confirmation for each previously funded account that becomes empty. It also lists option positions the import will remove and asks for confirmation. Use the manual editor to retain those positions.

Previous snapshots remain in history. If another tab changes your household or holdings, select Review latest snapshot. Your CSV and account choices remain available, and you must confirm the updated review before saving. If a saved account disappears, select Reset account choices and review to match the CSV again.

Setup and planner blockers#

Setup has its own page. Open it from Edit on the household line of any household tool. When you save and select Return, the tool opens again at the saved version of the household.

A planner shows a blocker before Run when the household does not have an input that the calculation needs. Each blocker opens Setup at that input:

• Roth IRA history. Enter the first Roth year and the basis that remains after earlier withdrawals. That basis is the contribution basis and what remains of each conversion by year. Your Form 8606 records carry these amounts. The planners tax a Roth IRA withdrawal by its source.
• First Roth 401(k) year. The year of the first Roth contribution to the plan starts its 5-year clock.
• Prior-year income (MAGI). Medicare premiums for a year use the MAGI of two years before. Open Prior-year income (MAGI) below the tax fields.

An inherited IRA is not a blocker. Open the account in Setup and enter the distribution rule, the beneficiary type, and the year of death. The Roth Conversion Planner uses them to schedule the required withdrawals. Without them, it models no required withdrawal and shows a warning. The Retirement Planner does not model an inherited IRA.

Use Exact annual distributions in the account editor when you have a required amount for a specific year. The Roth Conversion Planner and its spend-down mode use that amount before the distribution rule, up to the account balance. An entered zero sets no required distribution for that year. Removing the year restores the rule for it.

Signed out, Household shows a fictional sample household. Its inputs are read-only.

Choose dates and targets deliberately#

The current holdings snapshot date describes the balances you enter in setup. It is separate from the historical start and end dates in the allocator. A historical run continues to use its selected start date for starting holdings.

A new household starts without a target allocation. Enter your desired weights, which must total 100%, and confirm the target before saving. The target describes your policy. It does not recommend trades.

Read monitor status#

Awaiting first check means you saved a monitor but it has no completed evaluation. Unavailable means the latest status did not load. Neither state means the household is clear.

Monitor rows show the last completed check and data date when available. Drift settings state which absolute or relative bands apply. Absolute bands use percentage points. Relative bands use a percentage of each asset’s target weight.

The Household page shows signals linked to that household. Unlinked strategies remain available from View unlinked strategies in Monitors.

One setup, several tools#

Tax-aware tools use the saved accounts, tax context, and holdings snapshot as defaults. Use each tool's run settings to make allowed overrides.

Household walkthrough#

The Household page shows the items that need a decision first. Each item has one action. The accounts and the allocation drift follow. Tax opportunities, Monitoring, and the review log open when you select them. A monitor email opens Monitoring at the alert that it names.

Read the portfolio overview first

The Household overview uses the latest saved household and holdings snapshot.

1. Portfolio KPIs: Household computes total value, gain/loss, taxable share, and total drift from the current holdings snapshot.
2. Accounts: Each account keeps its tax character visible so the overview never blends taxable and tax-advantaged assets together.
3. Allocation drift: The card shows current and target weights side by side, with signed drift for each asset.

Monitor live strategies from household

Live strategies pinned from the Library appear under Monitoring when you link them to the saved household and holdings snapshot.

1. Signal state: Shows the active state, market-data date, transition eligibility, and latest evaluation time.
2. Check signals: Runs an on-demand signal evaluation against the latest available market data.
3. Pending trades: Account-level guidance lists ticker, side, shares, dollar value, and routing reason.

Features#

• Overview of account values, allocation drift, tax-profile warnings, and inline tax profile editing
• Live strategy status, data-through dates, transition eligibility, and account-level pending trades when you link a household and holdings snapshot
• Model taxable, traditional, Roth, and HSA accounts as a single filing unit with per-account cost basis tracking
• Tax-aware backtesting across accounts with per-lot accounting, realized-gain tracking, and annual tax bills
• Cross-account tax-loss-harvesting candidates with wash-sale risk assessment and possible substitutes
• Asset-location comparisons that rank tickers by modeled tax efficiency across account types
• Required minimum distribution (RMD) shortfall detection for traditional accounts with owner birth-year metadata
• Implementation constraints including rebalance frequency and deviation thresholds, an account preference order, and a taxable drift budget
• Contribution schedule and withdrawal priority per account
• One saved tax profile per user, reusable across backtest runs and revisions (each save creates a new immutable version)

When to use it#

• You want to see how a portfolio of accounts (taxable + Roth + traditional + HSA) would have performed together under a shared target allocation.
• You want per-account trade instructions that respect cost basis, wash-sale rules, and account tax character, not a single blended portfolio result.
• You want to quantify the benefit of better asset location (holding bonds in tax-deferred, equities in taxable and Roth) relative to an ignore-location baseline.
• You want to surface cross-account tax-loss-harvesting opportunities without violating the wash-sale rule across your IRAs.

How it works#

The workflow separates four persistent records. The tax profile holds accounts, tax context, target allocation, and constraints. The holdings snapshot holds the current per-account lots. Each saved analysis holds the immutable references used for its backtest. The fourth record is the live strategy selections pinned from the Library.

Each user owns exactly one tax profile. When you edit and save, the workflow records a new immutable version. The household overview uses the latest saved tax profile and holdings snapshot. Running the allocator persists the current form as a new version before dispatching the simulation. Trade instructions, tax bills, and holdings paths therefore always correspond to a resolvable pair of workspace references.

Live strategy monitoring evaluates saved Strategy Builder definitions against current market data. When you link the live selection to the household and holdings snapshot, account-level pending trades appear in household instead of only target weights.

Account types and tax treatment#

Household Tax Opportunities#

Household Tax Opportunities is a read-only diagnostic over the latest saved holdings snapshot. It surfaces harvestable losses, gain-harvest candidates, embedded gains, and wash-sale risk without running a backtest, and it does not count against any compute quota.

• Snapshot-date anchoring: every calculation uses the holdings snapshot date for holding periods, the wash-sale window, and price lookups. The same snapshot reproduces the report. Capture a new snapshot to refresh it.
• Loss threshold on cost basis: the tax-loss-harvesting percent threshold divides each lot's loss by its cost basis, not its market value. A lot qualifies when the loss is a large enough share of what you paid for it.
• Bracket room and NIIT distance: computed only when the tax profile's federal bracket mode is current-2026 or historical. The custom and flat modes have no statutory bracket edges, so those summary fields stay empty and the report notes why. Loss and gain candidates still appear.
• Review workflow: you can watch, dismiss, snooze until a date, or mark each row reviewed. These decisions persist across visits and new snapshots, so the list tracks what you have already handled.
• Free vs Pro: the diagnostic, the review workflow, and history are free for signed-in users. Per-section CSV exports and the review bundle are Pro.
• Monitoring: the Monitor tax-loss button creates a scheduled monitor that emails you when the opportunity set materially changes. See the Monitors guide.

Household Rebalancing: rebalancing and routing#

Rebalancing runs at the requested frequency (monthly, quarterly, yearly) or whenever the target weight deviates past your threshold. The engine prefers tax-advantaged accounts when buying and taxable last when selling, subject to the account preference order you supply. A taxable drift budget caps how far the taxable-only slice can deviate before forced rebalancing triggers realized gains.

How to get useful results#

• Set up the tax profile once (accounts, tax context, and target allocation) and save it. Subsequent backtests reuse the exact shape.
• Import real per-account holdings via the CSV editor instead of estimating. Per-lot cost basis is what makes the tax-aware output meaningful.
• Enable tax-loss harvesting on taxable accounts that hold correlated substitutes. The engine emits hints, not executed trades, so you can review before acting.
• Watch the dividend-degradation alert. Missing dividend history understates tax drag. Backfill or replace the ticker for a cleaner comparison.

Household Rebalancing: read the outputs#

• Aggregate pre-tax / after-tax values: the portfolio's trajectory with and without unrealized-tax drag, aligned to the same date index.
• Per-account timeseries: same trajectories broken out by account so you can see how the rebalancer loaded each sleeve.
• Trade instructions: chronological list of buys and sells with account, asset, shares, dollars, reason, and realized gain (for sells).
• Annual tax bills: per-year federal and state tax liability, including short- and long-term capital gains, dividend income, and NIIT.
• Asset location scenario notes: each ticker's efficiency class and the preferred account type, with a short rationale.
• Tax-loss-harvest hints: candidate losses, accounts with substantially identical positions, the wash-risk level (low / medium / high), a possible substitute, and a confidence note.
• Final holdings: end-of-run per-account lots, mark-to-market value, cost basis, and unrealized gain.
• RMD shortfall: if the owner did not meet the required distribution during the backtest window, the dollar shortfall (and the 25% excise estimate).
• Dividend degradation alert: the list of tickers with degraded or unavailable dividend history, so you know which results depend on a zero-income substitution.

Common mistakes#

• Entering the same holdings across multiple accounts without considering asset location. Compare the modeled tax effect of other placements.
• Running a backtest with stale holdings. Open Starting holdings and press New snapshot to capture the current state before you test a new scenario. The next run then does not update the prior snapshot in place.
• Treating tax-loss-harvest hints as safe trades. The wash-risk level accounts for identical positions across accounts. You still need to confirm substitutions are not substantially identical to other holdings in your real accounts.
• Ignoring the RMD shortfall alert. Total tax paid includes the estimated 25% excise tax, and the alert shows which owner/account missed a required distribution.

Household Rebalancing: modeling assumptions#

• Prices use unadjusted close series. The engine books dividend income separately, so reinvested dividends do not get double-counted.
• The engine treats missing dividend data as zero income for the affected tickers and surfaces it as a degraded-ticker warning.
• State tax modeling uses a flat rate for the configured resident state. It does not model progressive state brackets.
• Federal bracket mode can be current-2026, flat, custom, or historical. Pick the mode that matches the question you are asking.
• TLH hints are advisory. The engine does not execute substitutions because wash-sale avoidance depends on facts that it cannot see.
• The snapshot captured at run time must cover every account in the tax profile. The run rejects missing accounts instead of silently simulating them from empty portfolios.

NIIT, MAGI, and foreign income#

The optional adjusted gross income field feeds the NIIT MAGI base. When you set Form 1040 AGI, the engine computes NIIT MAGI from that AGI plus excluded foreign income after allocable deductions.

For NIIT, Form 8960 increases AGI by the amount of excluded foreign income that exceeds deductions allocable to it. The adjustment cannot reduce NIIT MAGI below AGI.

When you do not provide AGI, tax opportunities omits NIIT MAGI, NIIT distance, and gain-row NIIT flags.