PuGa/docs/usage.md

# Usage reference

Every tool runs as `puga <tool> [args]` (or `tools/<tool>.py`). `puga help` lists them, `puga <tool> --help` shows the options. `CLAUDE.md` has the authoritative one-paragraph description of each tool and its caveats; this page is the human-facing index.

## Tools

**Market**
- `price TICKER` bid, ask, 7/30-day VWAP, volume, supply and demand at every exchange; fill price for a quantity.
- `book TICKER` order-book ladder with cumulative depth.
- `sell TICKER QTY [--tight] [--tiers]` where to post an ask, expected time to clear, a tranche split, and whether pricing above market is ever worth the wait.
- `parkcash` where to park idle cash in a buy-low/sell-high position while it has no better use.
- `undervalued` manufactured goods priced below their input cost (buy-and-hold candidates, low return).

**Finding what to build**
- `scan` ranks every recipe with a depth-aware market model: buildings the market can absorb, payback at realistic fill prices, staffed and understaffed variants, freight, planet-specific extraction and COGC (`--planet`).
- `persistence rows.json` re-prices scan rows over 30/90/180 days of history: is the margin a spike?
- `history TICKER` monthly margin history of one recipe.
- `chain TICKER` make-vs-buy cost tree; `--consumers` lists what eats the ticker downstream.
- `planet RESOURCE --from PLANET` ranks planets for a resource by extraction factor, founding cost and jump distance.
- `route A B` jump route between planets or systems.

**Your own position**
- `state sync|show` refreshes `empire/state/company.yaml` from FIO: cash, permits, buildings, efficiency, storage, ships.
- `simulate spec.yaml | --uuid U` replica of the PRUNplanner simulator; reports the real new capex (planned minus built).
- `whatif base.yaml --add CHP:1` marginal payback of adding to a base you already run; flags newly overloaded workforce tiers and charges marginal freight.
- `buy base.yaml --days N` shopping list: construction gap plus N days of net operating stock, checked against cash.
- `runway base.yaml` days per material before the base stalls, including ships already inbound.
- `network chain.yaml` multi-base chain: mine here, ship, process there, with real freight.
- `plan list | pull UUID | spec.yaml [--apply] | delete UUID` read and write plans in your PRUNplanner account. Dry run by default; only `[PuGa]`-named plans are ever written.

**Ships**
- `shiptrip SHIP FROM TO` fuel cost of a trip for one of your ships.
- `shipcost --jumps N ...` the same from explicit physics parameters (gateway routes).
- `lmscan PLANET` live Local Market hauling ads ranked by margin after fuel.

**Legacy**
- `prun_scan`, `prun_cxarb` top-of-book scans kept as a baseline; they overstate thin markets.

## Examples

```sh
puga state sync
puga price BHP --cx AI1
puga scan --cogc METALLURGY --experts METALLURGY=2 --min-n 3 --top 20
puga scan --planet ZV-307d --min-n 3
puga scan --min-n 3 --json rows.json && puga persistence rows.json
puga chain KV --qty 13
puga simulate plans/examples/hwp_buildout.yaml --basis vwap30
puga whatif my_base.yaml --add CHP:1
puga buy my_base.yaml --days 1.5
puga runway my_base.yaml
puga planet FEO --min-factor 0.5 --from ZV-759c

puga plan list
puga plan pull <uuid> -o my_plan.yaml
puga plan my_plan.yaml            # dry run
puga plan my_plan.yaml --apply
puga simulate --uuid <uuid>
```

## Setup

Requires Python 3.12 or newer and git.

```sh
git clone <repo-url> PuGa && cd PuGa
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
source .venv/bin/activate         # once per shell, so `puga` is on your PATH
cp .env.example .env && chmod 600 .env && $EDITOR .env
tools/refresh_refs.sh             # optional: PRUNplanner source as mechanics reference (gitignored)
puga test
puga price BHP --cx AI1
```

### `.env`

Gitignored, never committed. Do not paste keys into chat; edit the file.

| Variable | What it is |
|---|---|
| `FIO_USERNAME` | your in-game / FIO user name |
| `FIO_REST_KEY` | FIO REST key (your sites, storage, production, ships, cash on `rest.fnar.net`) |
| `FIO_API_KEY` | FIO API (web) key; separate from the REST key, currently unused |
| `PRUNPLANNER_API_KEY` | API key from your PRUNplanner account, sent as `Authorization: Api-Key <key>` |
| `COMPANY_CODE` | your company code, used by the first `state sync` |
| `DEFAULT_CX`, `DEFAULT_REGION` | default exchange (`AI1` = Antares) and region |

Public data (prices, recipes, planets) works without keys. Your own data needs the FIO browser extension to have uploaded recently; run `puga state sync` and check `as_of`.

## Layout

```
CLAUDE.md        entry point for Claude: rules, tool index, source-of-truth order
docs/            game and toolkit knowledge: mechanics, market model, decisions, roadmap, this file
puga/            library: data clients, market, economics, saturation, simulator, shipping
tools/           command line tools
plans/examples/  generic plan specs (also test fixtures)
state/           company.example.yaml, the shape of your synced state
tests/           pytest suite
empire/          (gitignored) YOUR empire: PROFILE.md, state/company.yaml, plans/, docs/
data/            (gitignored) fetched data cache
ref/             (gitignored) PRUNplanner source, read-only reference
```

Game knowledge and generic methods go in `docs/`; anything about your own bases, cash, decisions or preferences goes in `empire/`. `puga state sync` creates `empire/state/company.yaml` (set `COMPANY_CODE` in `.env` first). Add `empire/PROFILE.md` yourself: who you are, how you want answers, agreements with Claude.