Initial extraction from monorepo

README.md

@@ -0,0 +1,51 @@
+# fire-planner
+
+Risk-adjusted, tax-minimised FIRE retirement planner. Consumes today's
+portfolio, savings rate, and RSU vest schedule from sibling services
+(`wealthfolio`, `payslip-ingest`, `hmrc-sync`) and returns the after-tax
+probability of success for each combination of jurisdiction, withdrawal
+strategy, and "year you break UK tax residency".
+
+## Layout
+
+- `fire_planner/` — package
+  - `tax/` — per-jurisdiction tax engines (UK, nomad, Malaysia, Thailand,
+    Cyprus, Bulgaria)
+  - `returns/` — Shiller 1871+ data + block bootstrap sampler
+  - `strategies/` — Trinity 4% SWR, Guyton-Klinger guardrails, VPW
+  - `ingest/` — pulls from `wealthfolio` / `payslip-ingest` / `hmrc-sync`
+  - `simulator.py` — vectorised NumPy MC engine
+  - `scenarios.py` — Cartesian product over (jurisdiction × strategy ×
+    leave-UK-year × glide)
+  - `app.py` — FastAPI on-demand `/recompute`
+  - `__main__.py` — `click` CLI: `ingest`, `simulate`, `recompute-all`,
+    `migrate`
+
+## Common commands
+
+```bash
+poetry install
+pytest -v
+mypy .
+ruff check .
+yapf --recursive .
+
+# Run migrations against the local DB:
+DB_CONNECTION_STRING=postgresql+asyncpg://... alembic upgrade head
+
+# CLI
+DB_CONNECTION_STRING=... python -m fire_planner ingest
+DB_CONNECTION_STRING=... python -m fire_planner simulate --scenario=cyprus-vpw-leave-y3
+DB_CONNECTION_STRING=... python -m fire_planner recompute-all
+```
+
+## Schema
+
+Six tables in `fire_planner` schema on `pg-cluster-rw`:
+
+- `account_snapshot` — daily NW per account (Wealthfolio)
+- `scenario` — Cartesian-product scenario definition
+- `mc_run` — execution metadata + summary stats per (scenario, run_at)
+- `mc_path` — sparse storage (top decile, bottom decile, median)
+- `projection_yearly` — deterministic point projection per scenario
+- `scenario_summary` — denormalised fast-read for Grafana