# 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
  - 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.