# `accounts.srf` reference

`accounts.srf` describes each account referenced by your portfolio:
its tax treatment, the institution it lives at, and a few flags that
tune analysis and reconciliation. It powers the **By Tax Type** and
**By Account** breakdowns in [`zfin analysis`](../cli/analysis.md), the
umbrella-exposure estimate, the audit staleness checks, and broker
reconciliation.

zfin loads `accounts.srf` from the same directory as the resolved
portfolio file. It is optional -- without it, accounts show up as
"Unknown" in the tax-type breakdown and everything else still works.

## File format

One record per account. The `account` name must match the
`account::` value used on your portfolio lots **exactly**.

```srf
#!srfv1
account::Pat 401k,tax_type::traditional,institution::fidelity,account_number::P401
account::Joint taxable,tax_type::taxable,institution::schwab,account_number::JT01
```

## Fields

| Field                  | Type   | Required | Default   | Description                                                                                                                      |
|------------------------|--------|----------|-----------|----------------------------------------------------------------------------------------------------------------------------------|
| `account`              | string | Yes      | --        | Account name; must match `account::` on lots exactly.                                                                            |
| `tax_type`             | string | Yes      | --        | `taxable`, `roth`, `traditional`, or `hsa`.                                                                                      |
| `institution`          | string | No       | --        | Broker key, e.g. `fidelity`, `schwab`, `vanguard`, `wells_fargo`. Used by [`zfin audit`](../cli/audit.md) to match export files. |
| `account_number`       | string | No       | --        | Account identifier used with `institution` for audit matching. Use a placeholder, not a full real number.                        |
| `update_cadence`       | string | No       | `weekly`  | How often you refresh this account's manual data: `weekly`, `monthly`, `quarterly`, or `none`. Drives the audit staleness nag.   |
| `cash_is_contribution` | bool   | No       | `false`   | When `true`, raw cash-balance increases on this account count as real external contributions (see below).                        |
| `direct_indexing`      | bool   | No       | `false`   | Marks an account whose lots track a benchmark with tracking-error drift (loosens contribution/audit tolerances).                 |
| `shielded`             | bool   | No       | (derived) | Umbrella-exposure override (see below).                                                                                          |

## Tax types

| Value         | Display label         |
|---------------|-----------------------|
| `taxable`     | Taxable               |
| `roth`        | Roth (Post-Tax)       |
| `traditional` | Traditional (Pre-Tax) |
| `hsa`         | HSA (Triple Tax-Free) |

Any other value is shown as-is. Accounts missing from `accounts.srf`
appear as "Unknown".

## `update_cadence` and the audit nag

[`zfin audit`](../cli/audit.md) (run flagless) flags accounts you
haven't refreshed within their cadence window: `weekly` = 7 days,
`monthly` = 30, `quarterly` = 90, `none` = never nag. The default is
`weekly`, so every account reminds you until you silence it -- set
`update_cadence::none` for accounts that update themselves (a live
brokerage feed) or that you simply don't track closely.

## `cash_is_contribution`

Most cash-balance movement is internal noise -- interest postings,
dividend credits, CD coupons, settlement sweeps -- which would inflate
the [`zfin contributions`](../cli/contributions.md) attribution total
if counted as new money. So cash deltas are ignored by default. Set
`cash_is_contribution:bool:true` only on accounts whose cash movement
is dominated by external deposits (payroll ESPP accrual, direct 401k
cash contributions).

## `shielded` (umbrella exposure)

The umbrella-exposure estimate in [`zfin analysis`](../cli/analysis.md)
splits your liquid net worth into "shielded" (retirement accounts,
assumed judgment-protected) and "exposed" (taxable). The default proxy
is "anything not `taxable` is shielded." Override it when that's wrong:

- `shielded:bool:false` on a pre-tax account that is **not**
  ERISA-protected (deferred-comp plans, non-qualified annuities), or on
  IRAs in states with weak IRA protection.
- `shielded:bool:true` to mark a taxable account as shielded (rare;
  e.g. some asset-protection trusts).

IRA protection varies by state and is not modeled automatically; set
this explicitly if it matters to you.

## Example (from `examples/pre-retirement-both`)

```srf
#!srfv1
account::Pat 401k,tax_type::traditional,institution::fidelity,account_number::P401
account::Pat Roth,tax_type::roth,institution::fidelity,account_number::PROTH
account::Sam 401k,tax_type::traditional,institution::vanguard,account_number::S401
account::Sam Roth,tax_type::roth,institution::vanguard,account_number::SROTH
account::Joint taxable,tax_type::taxable,institution::schwab,account_number::JT01
account::Family HSA,tax_type::hsa,institution::fidelity,account_number::HSA01
account::Kids 529,tax_type::taxable,institution::vanguard,account_number::C529
```

## See also

- [Map your accounts](../../guides/set-up-accounts.md) -- the walkthrough.
- [`zfin analysis`](../cli/analysis.md) -- tax-type and account breakdowns.
- [`zfin audit`](../cli/audit.md) -- staleness checks and broker reconciliation.

---

[Documentation home](../../README.md#reference)