I love how stupid this project is

si units and redefining speed metric as thrust/weight ratio

LOGIC DOCS/001-speed-metric-to-power-density-scoring.md

@@ -0,0 +1,50 @@
+# Replace "speed" metric with power density scoring
+
+## The problem
+
+After standardizing the database to SI base units, the stub estimator's speed formula was exposed as fundamentally broken:
+
+```python
+raw["speed"] = min(power_density * 0.14, 3e8)  # m/s
+```
+
+An Electric Motor (2000 W/kg) on a Light Personal Vehicle produced 280 m/s (1008 km/h). The old formula had the same issue (1000 km/h) — it was just less visible in km/h with the `|si` filter masking the absurdity.
+
+The root cause: **top speed cannot be derived from power density alone**. Speed depends on drag, rolling resistance, medium, vehicle geometry, and a dozen other factors the stub doesn't know. A linear power-to-speed model can never work across domains spanning e-bikes to spaceships.
+
+## Candidate replacement: thrust-to-weight ratio (N/kg)
+
+N/kg is dimensionally m/s² — a well-understood physical quantity. The actuator already declares `power_density` (W/kg), so the data exists. But three concerns emerged:
+
+1. **Redundant with Pass 1** — The constraint system already checks actuator `power_density` against platform `power_density_required`. Combos that reach scoring have already passed this gate, so scoring on the same axis re-evaluates something the pipeline already filtered.
+
+2. **Actuator-dominated** — Only the actuator declares `power_density`. Every combo sharing the same actuator scores identically, so the metric doesn't capture entity interplay.
+
+3. **Higher isn't always better** — A Rocket Nozzle (10,000 W/kg) on a Light Personal Vehicle has extreme thrust-to-weight, but that's not desirable for urban commuting. The current scorer only does monotonic normalization (higher is better, or lower is better), not "closer to optimal band."
+
+## The insight: `power_density_required` is a scoring concern, not a constraint
+
+Examining what `power_density_required` actually represents on platforms:
+
+- Road Vehicle: "I need >= 5 W/kg"
+- Fixed-Wing Aircraft: "I need >= 100 W/kg"
+- Spaceship: "I need >= 300 W/kg"
+
+These thresholds are arbitrary performance gradients — a car with 4 W/kg still moves, just poorly. There's no hard physics cliff. Compare with genuinely binary constraints:
+
+- **medium mutex** — a boat physically cannot operate in space
+- **energy_form requires/provides** — an electric motor cannot burn gasoline
+- **mass range** — a nuclear reactor won't fit on a bicycle frame
+
+Power density fit is "how well does it work," not "can it work at all." That's scoring territory.
+
+The one edge case — aircraft needing thrust-to-weight > 1 to leave the ground — is already implicitly handled by atmosphere/medium constraints and energy density minimums.
+
+## Decision
+
+Remove `power_density_required` from platform entity constraints and introduce it as a domain-level scoring metric instead. This:
+
+- Removes ~15 arbitrary constraint thresholds from seed data
+- Lets more combos through to scoring for nuanced evaluation
+- Creates a metric that varies by combo (actuator provides vs. platform context)
+- Replaces the broken "speed" heuristic with something directly computable from entity data

LOGIC DOCS/README.md

@@ -0,0 +1,5 @@
+# Logic Docs
+
+A series of thought experiments and design decisions made while developing PhysCom. Each document captures the reasoning behind a specific architectural or modeling choice — the "why" behind the code.
+
+These are living records of the design process, not formal specifications. They preserve context that would otherwise be lost between development sessions.