Initial PuGa toolkit: data layer, econ, depth-aware scan, state sync, plan push

- puga/: cached FIO + PRUNplanner clients, market view with order-book walk,
  econ formulas ported from PRUNplanner (tested against its suite and live FIO),
  saturation model v1 (reviewed by Opus)
- tools/: scan (depth-aware), price, book, chain, state sync, plan_push
  (dry run default, [PuGa]-prefixed plans only), legacy prun_scan/prun_cxarb
- docs/: mechanics (PRUNplanner is source of truth), roadmap, decisions,
  saturation design, archived handoff
- secrets stay in .env (gitignored); ref/ holds PRUNplanner source (ignored)

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

tools/state.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""Sync state/company.yaml from live FIO (own data via FIO_REST_KEY) and show it.
+  tools/state.py sync     # overwrite live fields (buildings, production efficiency, storage, ships, cash, permits)
+  tools/state.py show
+Requires the FIO extension to have uploaded recently; check `as_of`. Manual keys (company, notes) are preserved."""
+import sys, datetime
+from collections import Counter
+from pathlib import Path
+import yaml
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+from puga import ROOT, fio
+
+P = ROOT / "state" / "company.yaml"
+
+
+def sync():
+    u = fio.me()
+    st = yaml.safe_load(P.read_text()) if P.exists() else {}
+    company = fio.private(f"/company/code/{(st.get('company') or {}).get('ticker', 'GBI')}", ttl=0)
+    for stale in ("cash_aic",):
+        st.pop(stale, None)
+    st["as_of"] = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%d %H:%MZ")
+    st["cash"] = {b["Currency"]: b["Amount"] for b in company["Balances"] if b["Amount"]}
+    sites = fio.private(f"/sites/{u}", ttl=0)
+    prod = fio.private(f"/production/{u}", ttl=0)
+    stores = fio.private(f"/storage/{u}", ttl=0)
+    ships = fio.private(f"/ship/ships/{u}", ttl=0)
+    st["permits"] = {"used": sites[0]["InvestedPermits"] if sites else 0, "total": sites[0]["MaximumPermits"] if sites else 0}
+    old = {b["planet"]: b for b in st.get("bases", [])}
+    bases = []
+    for s in sites:
+        b = old.get(s["PlanetIdentifier"], {})
+        b.update(name=s["PlanetName"], planet=s["PlanetIdentifier"], buildings=dict(Counter(x["BuildingTicker"] for x in s["Buildings"])),
+                 avg_condition=round(sum(x["Condition"] for x in s["Buildings"]) / len(s["Buildings"]), 4))
+        b["production"] = [dict(type=l["Type"], count=l["Capacity"], efficiency=round(l["Efficiency"], 4), queued_orders=len(l["Orders"]))
+                           for l in prod if l["SiteId"] == s["SiteId"]]
+        bases.append(b)
+    st["bases"] = bases
+    st["storage"] = [dict(type=x["Type"], name=x["Name"], weight=f"{x['WeightLoad']:.0f}/{x['WeightCapacity']:.0f}t",
+                          items={i["MaterialTicker"]: i["MaterialAmount"] for i in x["StorageItems"] if i.get("MaterialTicker")})
+                     for x in stores if x["StorageItems"] or x["Type"] == "SHIP_STORE"]
+    st["ships"] = [dict(name=x["Name"], reg=x["Registration"], mass=x["Mass"], in_flight=bool(x.get("FlightId"))) for x in ships]
+    P.write_text(yaml.safe_dump(st, sort_keys=False, default_flow_style=None, width=140))
+    print("synced", st["as_of"])
+
+
+if __name__ == "__main__":
+    cmd = sys.argv[1] if len(sys.argv) > 1 else "show"
+    if cmd == "sync":
+        sync()
+    print(P.read_text())