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>

tests/test_market.py

@@ -0,0 +1,21 @@
+from puga import market, fio
+
+
+def _book(monkeypatch):
+    monkeypatch.setattr(fio, "order_book", lambda m, c, r=False: {
+        "SellingOrders": [{"ItemCount": 10, "ItemCost": 110}, {"ItemCount": 5, "ItemCost": 100}],
+        "BuyingOrders": [{"ItemCount": 4, "ItemCost": 90}, {"ItemCount": 10, "ItemCost": 80}],
+    })
+
+
+def test_buy_walks_asks_ascending(monkeypatch):
+    _book(monkeypatch)
+    r = market.walk("X", "AI1", 10, "buy")
+    assert r["total"] == 5 * 100 + 5 * 110 and r["worst"] == 110 and not r["short"]
+
+
+def test_sell_walks_bids_descending_and_reports_shortfall(monkeypatch):
+    _book(monkeypatch)
+    r = market.walk("X", "AI1", 20, "sell")
+    assert r["filled"] == 14 and r["short"] and r["worst"] == 80
+    assert r["total"] == 4 * 90 + 10 * 80