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>

puga/fio.py

@@ -0,0 +1,39 @@
+"""Public FIO REST (rest.fnar.net). Static game data caches long; market data short."""
+from .cache import get_json
+
+BASE = "https://rest.fnar.net"
+STATIC, MARKET = 24 * 3600, 15 * 60
+
+
+def _g(path: str, ttl: int, refresh: bool = False):
+    return get_json(BASE + path, ttl, refresh=refresh)
+
+
+def exchange_all(refresh=False):      return _g("/exchange/all", MARKET, refresh)
+def order_book(mat: str, cx: str, refresh=False):
+    """Full book: BuyingOrders / SellingOrders lists (price + quantity). Short TTL."""
+    return _g(f"/exchange/{mat}.{cx}", 5 * 60, refresh)
+def cxpc(mat: str, cx: str, refresh=False):
+    return _g(f"/exchange/cxpc/{mat}.{cx}", 3600, refresh)
+def materials(refresh=False):         return _g("/material/allmaterials", STATIC, refresh)
+def recipes(refresh=False):           return _g("/recipes/allrecipes", STATIC, refresh)
+def buildings(refresh=False):         return _g("/building/allbuildings", STATIC, refresh)
+def planets_full(refresh=False):      return _g("/planet/allplanets/full", STATIC, refresh)
+def workforce_needs(refresh=False):   return _g("/global/workforceneeds", STATIC, refresh)
+def systems(refresh=False):           return _g("/systemstars", STATIC, refresh)
+def stations(refresh=False):          return _g("/exchange/station", STATIC, refresh)
+
+
+def private(path: str, ttl: int = 300, refresh: bool = False):
+    """Authenticated FIO REST (own data: /sites/{user}, /storage/{user}, /production/{user}, /ship/ships/{user}...).
+    Auth: `Authorization: <FIO_REST_KEY>` (verified 2026-09-18). FIO_API_KEY does NOT work on rest.fnar.net."""
+    from . import config
+    key = config.get("FIO_REST_KEY")
+    if not key:
+        raise RuntimeError("FIO_REST_KEY missing in .env")
+    return get_json(BASE + path, ttl, headers={"Authorization": key}, refresh=refresh)
+
+
+def me() -> str:
+    from . import config
+    return config.get("FIO_USERNAME", "")