Add simulator replica, persistence, planet scan, README; split empire state out of the repo

- tools/simulate.py + puga/simulate.py: replica of PRUNplanner's simulator (flows and
  efficiency verified against screenshots), reports real new capex (planned minus built)
- tools/scan.py: staffing variants, freight, HQ/experts, --planet mode, demolish-later,
  --min-n as a pure market-size filter, --json output
- tools/history.py, tools/persistence.py: margin history and short-horizon payback checks
- tools/plan_push.py: guarded delete; tools/state.py: syncs to empire/
- README with features and setup; CLAUDE.md made generic
- Own-empire material (profile, state, plans, notes) moved to gitignored empire/;
  generic examples in plans/examples and state/company.example.yaml

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

README.md

@@ -6,7 +6,113 @@
   <br><br>
 </h1>
 
-A set of tools to be used by humans and/or llms to plan for th egame Prosperous Universe.
+A set of tools and know-how for Claude (Claude Code) to assist in the game [Prosperous Universe](https://prosperousuniverse.com), usable by humans too. You ask questions in plain language; Claude answers by running the tools in this repo against live market data and your own company data, instead of guessing.
 
 Name origin:
 Plutonium–gallium alloy (Pu–Ga) is a specialized metallic blend of plutonium and gallium primarily used to stabilize the desirable delta (δ) phase of plutonium at room temperature.
+
+## How it is meant to be used
+
+Open Claude Code in this folder. `CLAUDE.md` is loaded automatically: it tells Claude who the player is, which tools exist, which numbers to trust, and how to answer. Claude also reads `empire/PROFILE.md` (who you are, how you want answers) if you have one. Then just ask, e.g. *"what should I build on Sunday?"*, *"is BHP still worth it?"*, *"simulate my HWP plan"*. Every tool is also a normal command line script, so you can run them yourself.
+
+Everything the tools print is an **estimate** from public and personal game data. Prices move; re-run before acting.
+
+## Features
+
+**Data layer**
+- Cached clients for the FIO REST API and the PRUNplanner API (public game data, order books, price history, your own sites, storage, production, ships, cash).
+
+**Market tools**
+- `price`: bid, ask, 7/30-day VWAP, daily volume, supply and demand at every exchange; fill price for a quantity.
+- `book`: order-book ladder with cumulative depth (market-maker orders handled).
+
+**Economics engine** (`puga/econ.py`, ported from the PRUNplanner source, which is treated as the source of truth and checked against its own tests and live FIO values)
+- Building efficiency: COGC, HQ, experts, faction bonus, fertility, building condition.
+- Workforce satisfaction and consumption, extraction rates, production per day, housing optimizer.
+
+**Finding opportunities**
+- `scan`: ranks every recipe with a depth-aware market model, so it does not recommend recipes whose whole market fits one or two buildings. Fully staffed and understaffed variants, freight cost, HQ/COGC/experts, `--min-n` filter for real markets, a `--planet` mode (extraction, fertility, COGC of a specific planet) and a demolish-later cost.
+- `persistence` and `history`: how long has a margin lasted? Re-prices any opportunity over the exchange history (30/90/180 days), with payback and expected net gain over 7 and 14 days.
+- `chain`: make-versus-buy cost tree with sourcing depth of every input.
+- `arb` (planned) and the legacy `prun_scan` / `prun_cxarb` (kept as a baseline, they overstate thin markets).
+
+**Your own position**
+- `state`: syncs `empire/state/company.yaml` from FIO: cash, permits, buildings, real production efficiency, storage and ships.
+- `simulate`: a Python replica of the PRUNplanner simulator (workforce, efficiency, material I/O, profit), verified against screenshots of it. Reads a local plan or a saved plan from your account, and reports the real new capex (planned minus already built).
+- `plan_push`: creates, updates and deletes plans in your PRUNplanner account from small YAML files (examples in `plans/examples/`). Dry run by default; only plans named `[PuGa] ...` can be written or deleted.
+
+**Knowledge for Claude** (`CLAUDE.md`, `docs/`)
+- Verified game mechanics, the market-saturation design, a decision log and a roadmap (`docs/`). Everything specific to your own empire (profile, state, plans, notes) lives in the gitignored `empire/` folder, so this repo can stay public.
+
+## Setup
+
+Requires Python 3.12 or newer and git.
+
+```sh
+git clone <repo-url> PuGa
+cd PuGa
+
+# 1. virtual environment
+python3 -m venv .venv
+.venv/bin/pip install -r requirements.txt
+
+# 2. keys
+cp .env.example .env
+chmod 600 .env
+$EDITOR .env          # fill in the values below
+
+# 3. optional: the PRUNplanner source used as reference for game mechanics (gitignored)
+tools/refresh_refs.sh
+
+# 4. check it works
+.venv/bin/python -m pytest
+.venv/bin/python tools/price.py BHP --cx AI1
+```
+
+### `.env`
+
+`.env` is gitignored and 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` | your FIO REST key (used for your own sites, storage, production, ships, cash on `rest.fnar.net`) |
+| `FIO_API_KEY` | your 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 `tools/state.py` for the first sync) |
+| `DEFAULT_CX`, `DEFAULT_REGION` | default exchange (`AI1` = Antares) and region |
+
+Only the public data works without keys (prices, recipes, planets). Your own data needs the FIO extension for the browser client to have uploaded it recently: run `tools/state.py sync` and check the `as_of` time.
+
+## Usage
+
+```sh
+.venv/bin/python tools/state.py sync                               # refresh your company state from FIO
+.venv/bin/python tools/scan.py --cogc METALLURGY --experts METALLURGY=2 --min-n 3 --top 20
+.venv/bin/python tools/scan.py --planet ZV-307d --min-n 3          # a specific planet
+.venv/bin/python tools/scan.py --min-n 3 --json rows.json && .venv/bin/python tools/persistence.py rows.json
+.venv/bin/python tools/chain.py KV --qty 13
+.venv/bin/python tools/simulate.py plans/examples/hwp_buildout.yaml --basis vwap30
+.venv/bin/python tools/plan_push.py plans/examples/hwp_buildout.yaml # dry run; add --apply to write
+```
+
+## Layout
+
+```
+CLAUDE.md      entry point for Claude: rules, tool index, source-of-truth order
+docs/          game and toolkit knowledge: mechanics, market model, decisions, roadmap
+puga/          library: data clients, market, economics, saturation, simulator
+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/ (notes, build plans)
+data/          (gitignored) fetched data cache
+ref/           (gitignored) PRUNplanner source, read-only reference
+```
+
+### The `empire/` folder
+
+Game knowledge and generic methods go in `docs/`; anything about your own bases, cash, decisions or preferences goes in `empire/`, which is gitignored. `tools/state.py sync` creates `empire/state/company.yaml` (on first use set `COMPANY_CODE` in `.env`). Add `empire/PROFILE.md` yourself: your name, company, how you want answers, agreements with Claude.
+
+Not affiliated with Prosperous Universe, FIO or PRUNplanner.