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>

plans/deimos_bhp.yaml

@@ -0,0 +1,13 @@
+# Deimos as it stands (FIO 2026-09-18) plus the BHP thesis: 1 HWP (STL variant) and 1 HB2 for its 40 settlers.
+# Technicians left unstaffed (no HB3): workforce factor 40/50 = 0.8.
+name: "[PuGa] Deimos BHP (HWP + HB2)"
+planet: ZV-759c
+permits: 1
+cogc: METALLURGY
+hq: false
+experts: {METALLURGY: 2}
+infrastructure: {HB1: 4, HB2: 1}
+buildings:
+  - {building: EXT, amount: 2, recipes: ["EXT#ALO"]}
+  - {building: SME, amount: 5, recipes: ["ALO,FLX,C,O=>AL"]}
+  - {building: HWP, amount: 1, recipes: ["AL,STL,HE=>BHP"]}