docs: establish official design documentation

docs/DESIGN.md

@@ -0,0 +1,108 @@
+# Design Documents
+
+This repository uses a small set of official design documents to define intended gameplay and simulation behavior.
+
+These documents are design-first. They describe target structure and rules, not temporary implementation status.
+
+For the implementation migration path from the current codebase to this design set, see [ROADMAP.md](/home/jbourdon/repos/space-game/docs/ROADMAP.md).
+
+## Core Documents
+
+- [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.md)
+  - spatial layers
+  - nodes and local bubbles
+  - movement regimes
+  - viewer scale expectations
+  - replication and interest management implications
+
+- [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md)
+  - commander roles for factions, stations, and ships
+  - command hierarchy
+  - orders, doctrine, and delegation
+  - minimum autonomy rules
+
+- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md)
+  - market-driven simulation
+  - buy and sell orders
+  - station market behavior
+  - logistics and production incentives
+
+- [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md)
+  - item categories
+  - life-support goods
+  - construction goods
+  - fuel-chain goods
+  - population-related units
+
+- [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md)
+  - population
+  - habitats
+  - workforce efficiency
+  - worker transport
+  - commander generation
+
+- [MODULES.md](/home/jbourdon/repos/space-game/docs/MODULES.md)
+  - ship and station module categories
+  - capability gating
+  - workforce and power interaction
+  - module-driven growth and specialization
+
+- [PRODUCTION.md](/home/jbourdon/repos/space-game/docs/PRODUCTION.md)
+  - recipes and conversion logic
+  - module-driven processing
+  - throughput and queues
+  - construction as production
+
+- [POLICIES.md](/home/jbourdon/repos/space-game/docs/POLICIES.md)
+  - trade and docking permissions
+  - construction access
+  - territorial and regional restrictions
+  - policy-based behavior limits
+
+- [COMBAT.md](/home/jbourdon/repos/space-game/docs/COMBAT.md)
+  - local-space combat
+  - piracy and station defense
+  - claim destruction and contest
+  - commander-driven engagement behavior
+
+- [DATA-MODEL.md](/home/jbourdon/repos/space-game/docs/DATA-MODEL.md)
+  - core entities and IDs
+  - major enums
+  - runtime fields implied by the design
+  - replication-friendly entity vocabulary
+
+- [EVENTS.md](/home/jbourdon/repos/space-game/docs/EVENTS.md)
+  - typed world events
+  - lifecycle and replication visibility
+  - market, construction, and combat event families
+  - human-readable summaries for logs and UI
+
+- [TASKS.md](/home/jbourdon/repos/space-game/docs/TASKS.md)
+  - goals, orders, behaviors, tasks, and states
+  - planner precedence
+  - executable ship and station work
+  - safety and policy-aware tasking
+
+- [SHIPS.md](/home/jbourdon/repos/space-game/docs/SHIPS.md)
+  - ship roles
+  - movement capabilities
+  - onboard command requirements
+  - ship behavior expectations
+
+- [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md)
+  - station roles
+  - local bubble functions
+  - station command requirements
+  - station services, docking, and market responsibilities
+
+## Document Rules
+
+These documents should aim to:
+
+- define durable game concepts
+- avoid temporary work logs
+- avoid implementation changelists
+- avoid short-lived task lists
+- reference each other where concepts overlap
+
+If a note is only about current runtime state, active experiments, or a one-off migration, it should not live in the official design set.