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>

.env.example

@@ -0,0 +1,7 @@
+# Copy to .env (gitignored, chmod 600) and fill in. Never paste keys into chat; edit the file.
+FIO_USERNAME=dodox
+FIO_REST_KEY=        # FIO REST key (rest.fnar.net authenticated endpoints)
+FIO_API_KEY=         # FIO API key (same as the FIO web account key); separate from REST, possibly a separate account
+PRUNPLANNER_API_KEY= # api.prunplanner.org key, sent as "Authorization: Api-Key <key>"
+DEFAULT_CX=AI1
+DEFAULT_REGION=antares