# zfin documentation

zfin is a financial-data CLI and terminal UI for tracking a real
portfolio, analyzing trailing returns and risk, and running
retirement projections -- all from the terminal.

These docs are **task-first**. Almost every example here is runnable
against the fictional example portfolios that ship in the repo under
[`examples/`](../examples/), so you can follow along verbatim and see
the exact output shown. Set `ZFIN_HOME` to an example directory and
any command reads that portfolio:

```bash
ZFIN_HOME=examples/pre-retirement-both zfin portfolio
ZFIN_HOME=examples/post-retirement     zfin projections
```

If you are reading these on Forgejo, every link below is a relative
path you can click.

## Start here

New to zfin? Read these in order:

1. [Getting started](getting-started.md) -- install, set up API keys,
   create your first portfolio, run your first commands, open the TUI.
2. [Core concepts](explanation/concepts.md) -- the handful of ideas
   (the `.srf` files, `ZFIN_HOME`, live vs. snapshot data) that make
   everything else click.

## The user manual (workflows)

Goal-oriented guides. Each one walks an end-to-end task against a real
example portfolio and links to the reference for exhaustive detail.

| Guide                                                             | What you'll accomplish                                             |
|-------------------------------------------------------------------|--------------------------------------------------------------------|
| [Build your portfolio](guides/set-up-your-portfolio.md)           | Write a `portfolio.srf` from scratch: lots, cash, options, CDs     |
| [Classify your holdings](guides/classify-holdings.md)             | Create `metadata.srf` (by hand or with `enrich`) so analysis works |
| [Map your accounts](guides/set-up-accounts.md)                    | Tag accounts with tax type and institution in `accounts.srf`       |
| [Read your portfolio](guides/read-your-portfolio.md)              | Interpret `portfolio`, `analysis`, `exposure`, `review`, `perf`    |
| [Track contributions](guides/track-contributions.md)              | See money added over time and tag internal transfers               |
| [Snapshots and history](guides/snapshots-and-history.md)          | Record daily snapshots and compare your portfolio over time        |
| [Plan for retirement](guides/plan-retirement.md)                  | Configure `projections.srf` for accumulation and drawdown          |
| [Audit against your brokerage](guides/audit-against-brokerage.md) | Reconcile zfin against Fidelity/Schwab/Wells exports               |
| [A periodic review](guides/periodic-review.md)                    | Reconcile, see what changed, then commit the new baseline          |
| [Customize the TUI](guides/customize-the-tui.md)                  | Rebind keys and recolor the interface                              |
| [Offline use and refreshing data](guides/offline-and-refresh.md)  | Control caching and provider calls                                 |

## Reference

Look-it-up material. Exhaustive, terse, and kept in step with the
shipped binary.

- [CLI command reference](reference/cli/index.md) -- every command,
  its flags, and sample output.
- Configuration files:
  - [`portfolio.srf`](reference/config/portfolio-srf.md) -- positions, lots, cash, options, CDs
  - [`metadata.srf`](reference/config/metadata-srf.md) -- sector / geography / asset-class classification
  - [`accounts.srf`](reference/config/accounts-srf.md) -- tax type and institution per account
  - [`projections.srf`](reference/config/projections-srf.md) -- retirement projection inputs
  - [`watchlist.srf`](reference/config/watchlist-srf.md) -- price-only symbols
  - [`transaction_log.srf`](reference/config/transaction-log-srf.md) -- declared transfers
  - [`keys.srf`](reference/config/keys-srf.md) -- TUI keybindings
  - [`theme.srf`](reference/config/theme-srf.md) -- TUI colors
  - [Environment variables](reference/config/environment.md) -- API keys, `ZFIN_HOME`, `ZFIN_CACHE_DIR`, and more
- [The interactive TUI](reference/tui.md) -- tabs, keybindings, theming.
- [Data providers and API keys](reference/providers.md) -- who supplies
  what, free-tier limits, and where to get keys.

## Explanation

Background and the "why" behind zfin's behavior.

- [Core concepts](explanation/concepts.md)
- [Caching and data freshness](explanation/caching.md)
- [Why multiple data providers](explanation/data-providers.md)
- [Returns and performance](explanation/returns-and-performance.md)
- [The retirement projection model](explanation/projections-model.md)
- [FAQ and troubleshooting](explanation/faq-troubleshooting.md)

## The example portfolios

The guides lean on five bundled, fictional households. They are safe
to read, copy, and run against:

| `ZFIN_HOME=examples/...`         | Household                                | Demonstrates                                                  |
|----------------------------------|------------------------------------------|---------------------------------------------------------------|
| `pre-retirement-both`            | Pat & Sam, ~45, ~$1.3M, contributing     | A target retirement date **and** a target spending level      |
| `pre-retirement-age`             | same household                           | A target retirement **date** only                             |
| `pre-retirement-spending`        | same household                           | A target **spending** level only (earliest-retirement search) |
| `pre-retirement-spending-target` | same household                           | An explicit, deliberately infeasible planning anchor          |
| `post-retirement`                | Robin & Jamie, ~68, ~$2.5M, drawing down | Distribution-only planning, with snapshot history             |

See [`examples/README.md`](../examples/README.md) for the full tour of
what differs between them.

## A note on the examples and your real data

All names, share counts, account numbers, and prices in `examples/`
are fictional. Nothing in these docs is financial advice. When you
point zfin at your own data, keep it outside the repository (set
`ZFIN_HOME` to a private directory) so you never commit real holdings.