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/config.py

@@ -0,0 +1,26 @@
+"""Settings from .env (gitignored) and process environment. Never log secret values."""
+import os
+from . import ROOT
+
+
+def _load_env() -> dict[str, str]:
+    out: dict[str, str] = {}
+    p = ROOT / ".env"
+    if p.exists():
+        for line in p.read_text().splitlines():
+            line = line.split("#", 1)[0].strip()
+            if "=" in line:
+                k, v = line.split("=", 1)
+                out[k.strip()] = v.strip().strip("'\"")
+    return out
+
+
+_ENV = _load_env()
+
+
+def get(key: str, default: str | None = None) -> str | None:
+    return os.environ.get(key) or _ENV.get(key) or default
+
+
+DEFAULT_CX = get("DEFAULT_CX", "AI1")
+CACHE_DIR = ROOT / "data" / "cache"