Add buy/sell tools, library docs, and permit/HQ fixes

- tools/buy.py: cash-aware shopping list (construction gap vs empire state's built
  buildings, plus N days of NET operating stock via simulate() so self-produced
  inputs net against consumption), priced at real order-book fill cost, checked
  against cash/reserve, flags multi-trip, binary-searches an affordable size when short
- tools/sell.py: where to post an ask vs hitting the bids now, with expected
  clear time from 30-day traded-volume percentiles
- docs/library.md: module map and patterns for using puga.* directly instead of
  the CLI, plus the "simulate() only knows what the plan lists" gotcha that a
  first version of buy.py hit
- tools/simulate.py: fix --no-hq being a no-op; tools/state.py: permits_total_override
  for when the in-game HQ screen disagrees with FIO's MaximumPermits
- docs/mechanics.md: HQ display vs PRUNplanner's HQ flag, workforce arrival sources
- CLAUDE.md, docs/roadmap.md updated

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

tools/state.py

@@ -30,6 +30,8 @@ def sync():
     stores = fio.own(f"/storage/{u}", ttl=0)
     ships = fio.own(f"/ship/ships/{u}", ttl=0)
     st["permits"] = {"used": sites[0]["InvestedPermits"] if sites else 0, "total": sites[0]["MaximumPermits"] if sites else 0}
+    if st.get("permits_total_override"):          # e.g. the HQ screen (base permits x / y) disagrees with FIO's MaximumPermits
+        st["permits"]["total"] = st["permits_total_override"]
     old = {b["planet"]: b for b in st.get("bases", [])}
     bases = []
     for s in sites: