# Roadmap

Open work only - what's already built/fixed is discoverable from `CLAUDE.md`'s Tools list,
`docs/library.md`, `docs/decisions.md`, and module docstrings, not repeated here.

## Todo
- [ ] `tools/network.py`/`puga/network.py`'s `combine()` doesn't pass `planet` into `simulate()`
  yet (environment-extra construction materials, `puga/planet.py::environment_extras()`) -
  `whatif.py`/`buy.py`/`scan.py` already do.
- [ ] `tools/arb.py`: inter-CX arbitrage at real fill size (replaces `prun_cxarb.py`, which
  overstated profit 7-11x on 2/4 top hits).
- [ ] `tools/haul.py`: fuel cost / profit per trip (route.py has the jump graph).
- [ ] `tools/portfolio.py`: profit-maximizing set of 1-building opportunities under shared
  housing/capex/permits. Ties into backlog #2 (profit/permit ranking, needs this tool to mean
  anything - permits bind at the whole-base level, not per-recipe).
- [ ] Docs to fill: `docs/apex.md`, `docs/fio.md`, `docs/playbook.md`.

## Backlog: review findings, still open (spot-checked against code)
1. [ ] `scan.py` payback ignores working capital (input stock/output inventory/consumables) - can
   rival building capex for smelting-type recipes. `buy.py` already computes this number.
2. [ ] No profit/permit ranking (permits bind at the base level, not per-recipe) - needs
   `tools/portfolio.py`'s cross-recipe/whole-base view.
3. [ ] `scan.py` doesn't charge degradation (capex/180/day) like `simulate.py` does - small but real
   inconsistency between tools ranking the same thing.
4. [ ] No input-side flow cap (buying a big share of an input's flow should price-impact like
   selling output does) - documented as absent, not modelled.
5. [ ] `persistence.py --lag 3` default is too low given `docs/mechanics.md`'s weekly workforce
   distribution - real lag is 3-10 days.
6. [ ] Possible forward-fill bias if any tool reindexes `daily_prices()` onto a full calendar grid
   (it only emits trade days) - would understate volatility for sparse tickers. Not yet confirmed
   whether `persistence.py`/`undervalued.py` actually do this.
7. [ ] `undervalued.py`'s backtest (+21.3%/3mo) has no control group - meaningless without the
   universe's unconditional return over the same window.
8. [ ] `persistence.py` measures past margin variance of a market we were NOT in - can't see the
   dominant real risk (our own entry + the next player's compressing margin).
9. [ ] `undervalued.py::manufacturing_candidates()` keeps the first recipe seen per output, not
   the cheapest (`seen.setdefault`).
10. [ ] `scan.py` hab cost ignores combined habs (HBB/HBC/HBM/HBL), which can be cheaper per head.
11. [ ] `scan.py --trip-cost` still defaults to the flat 9250 placeholder despite the real
    `puga/shipping.py` model existing and already used by `whatif.py`.
12. [ ] `sell.py`'s `s0` is the day's VWAP, not its high - `--tiers` touch probability is slightly
    pessimistic (same discretization conservatism as `empirical_touch()`, see `docs/decisions.md`).
13. [ ] `empirical_touch()`'s optional `horizon` (fixed-window right-censoring) exists but isn't
    wired into any tool's default call yet.

## Open questions
- FIO REST and FIO API are separate services/keys (`.env`). FIO_REST_KEY works on rest.fnar.net;
  FIO_API_KEY's host is unknown; PRUNplanner's Api-Key works. `doc.fnar.net/api.json` has no
  securitySchemes.