Add simulator replica, persistence, planet scan, README; split empire state out of the repo

- tools/simulate.py + puga/simulate.py: replica of PRUNplanner's simulator (flows and
  efficiency verified against screenshots), reports real new capex (planned minus built)
- tools/scan.py: staffing variants, freight, HQ/experts, --planet mode, demolish-later,
  --min-n as a pure market-size filter, --json output
- tools/history.py, tools/persistence.py: margin history and short-horizon payback checks
- tools/plan_push.py: guarded delete; tools/state.py: syncs to empire/
- README with features and setup; CLAUDE.md made generic
- Own-empire material (profile, state, plans, notes) moved to gitignored empire/;
  generic examples in plans/examples and state/company.example.yaml

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

puga/config.py

@@ -24,3 +24,12 @@ def get(key: str, default: str | None = None) -> str | None:
 
 DEFAULT_CX = get("DEFAULT_CX", "AI1")
 CACHE_DIR = ROOT / "data" / "cache"
+
+
+EMPIRE_DIR = ROOT / "empire"                    # gitignored: our empire: player profile, company state, own plans and notes
+
+
+def state_path():
+    """Real company state if synced (empire/), else the tracked example so the tools still run."""
+    real = EMPIRE_DIR / "state" / "company.yaml"
+    return real if real.exists() else ROOT / "state" / "company.example.yaml"