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

@@ -58,7 +58,9 @@ def main():
     st = _y.safe_load(config.state_path().read_text())
     faction = None if a.no_faction else (st.get("company") or {}).get("faction")
     perm = (st.get("permits", {}).get("used", 1), st.get("permits", {}).get("total", 2))
-    if not a.no_hq and st.get("hq"):
+    if a.no_hq:
+        plan["plan_corphq"] = False
+    elif st.get("hq"):
         plan["plan_corphq"] = True
     built = next((b.get("buildings", {}) for b in st.get("bases", []) if b.get("planet") == plan["planet_natural_id"]), {})
     if a.cm_free: