docs: establish official design documentation

docs/MODULES.md

@@ -0,0 +1,294 @@
+# Modules
+
+This document defines the intended module model for ships and stations.
+
+Modules are the primary way ships and stations gain capability.
+
+They determine what an entity can do, what goods it can handle, what services it can provide, and how much workforce or support it requires.
+
+## Design Goals
+
+The module system should support:
+
+- X4-style composable stations
+- role-defined ships without excessive hardcoding
+- meaningful logistics and infrastructure requirements
+- clear capability gating
+- future expansion without changing the basic architecture
+
+## Core Principles
+
+- ships and stations gain most capabilities through modules
+- modules should define function, not just stats
+- modules should have real operational requirements
+- modules should interact with workforce, items, and command logic
+- a hull or station frame without the right modules should be meaningfully limited
+
+## Module Ownership
+
+Modules belong to either:
+
+- ships
+- stations
+
+Some module categories conceptually exist on both, but their use may differ.
+
+Examples:
+
+- storage
+- habitat
+- power-related modules
+
+## Capability Gating
+
+Modules should gate real gameplay abilities.
+
+Examples:
+
+- no docking module means no docking service
+- no habitat module means no population growth or human transport
+- no refinery module means no refining
+- no fuel-processing module means no gas-to-fuel conversion
+- no storage module means reduced or absent inventory capability
+- no shipyard-related module means no ship production
+
+This should remain a core rule of the simulation.
+
+## Ship Modules
+
+Ship modules define what a ship can do.
+
+Likely ship-side categories include:
+
+- reactor or power generation
+- capacitor or energy buffer
+- thruster package later if separated
+- warp-capable propulsion support later if needed
+- FTL capability where applicable
+- cargo storage
+- habitat for human transport
+- livestock transport
+- mining equipment
+- gas harvesting equipment
+- weapons
+- support or utility systems later
+
+Ship identity should be influenced by:
+
+- hull class
+- fitted modules
+- commander behavior
+
+Not every industrial role needs a distinct hardcoded hull if modules can express the difference clearly enough.
+
+## Station Modules
+
+Station modules define what a station can do.
+
+Likely station-side categories include:
+
+- power generation
+- docking
+- storage
+- habitat
+- refinery
+- fuel processing
+- manufacturing
+- shipyard or construction support
+- defense
+- trade or logistics support later
+- livestock or food-chain support later
+
+Station identity should largely come from module composition.
+
+This is especially important because your station model is configuration-based rather than having every station type be a wholly separate structure class.
+
+## Structural Rule
+
+Stations are built at one Lagrange point and expanded by adding modules.
+
+That means modules are the main axis of station growth.
+
+A station does not sprawl across multiple sites.
+
+## Module Categories
+
+For design purposes, modules can be grouped into a few major classes:
+
+1. structural modules
+2. operational modules
+3. production modules
+4. logistics modules
+5. population modules
+6. military modules
+
+### Structural Modules
+
+These define physical expansion and attachment capacity.
+
+Examples:
+
+- core station body
+- structural extensions
+- future hardpoint or attachment frames
+
+### Operational Modules
+
+These keep the entity functioning.
+
+Examples:
+
+- reactor
+- capacitor
+- station power core
+- fuel systems
+
+### Production Modules
+
+These convert goods into other goods or into built output.
+
+Examples:
+
+- refinery
+- fuel processor
+- factory
+- shipyard support
+
+### Logistics Modules
+
+These let an entity store, receive, and move goods or people.
+
+Examples:
+
+- cargo storage
+- docking bay
+- transfer systems later
+- habitat transport support
+- livestock handling
+
+### Population Modules
+
+These support humans and long-term station staffing.
+
+Examples:
+
+- habitat
+- civilian support modules later
+
+Population modules are especially important because they connect stations to [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md).
+
+### Military Modules
+
+These allow defense and force projection.
+
+Examples:
+
+- turrets
+- missile systems later
+- shield or defensive utility later
+- station defense platforms as module sets
+
+## Module Requirements
+
+Modules should not be treated as free magic unlocks.
+
+They may require:
+
+- construction materials
+- build time
+- power
+- workforce
+- fuel or energy inputs
+- docking or logistics support
+
+This should let stations and ships fail in believable ways when underbuilt or undersupplied.
+
+## Workforce Interaction
+
+Modules should interact with workforce through a simple rule at first:
+
+- every module contributes to the station's workforce requirement
+- workforce satisfaction scales module effectiveness equally
+
+That keeps the first model simple while preserving the idea that bigger stations need more people.
+
+## Item Interaction
+
+Modules should define which item flows an entity can participate in.
+
+Examples:
+
+- a habitat module enables population support
+- a fuel-processing module consumes gas and produces fuel
+- a refinery consumes raw resources and produces processed goods
+- a storage module determines what volume or class of goods can be held
+- a livestock module participates in the food chain
+
+See [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md) for the item-side vocabulary.
+See [PRODUCTION.md](/home/jbourdon/repos/space-game/docs/PRODUCTION.md) for the recipe-side model.
+
+## Construction And Module Demand
+
+Module construction should use the same economic logic as station construction more broadly.
+
+That means:
+
+- module builds consume real goods
+- construction storage can publish demand
+- expansion creates burst economic pressure
+
+This keeps station growth tied to the market rather than detached from it.
+
+## Operational Failure
+
+Modules should help determine failure modes.
+
+Examples:
+
+- no power means operational modules fail
+- no docking module means the station cannot offer docking service
+- no habitat means no local population growth
+- no storage means goods handling becomes impossible or severely constrained
+
+This helps capability loss emerge from the world state instead of from arbitrary toggles.
+
+## Fitting Philosophy
+
+The intended philosophy should be:
+
+- hulls and station frames define limits
+- modules define capabilities
+
+That means the simulation should avoid making every role a unique special-case entity if a module composition can express it more cleanly.
+
+## Minimum Rules
+
+The following rules should remain true unless deliberately revised:
+
+- modules gate real capabilities
+- stations grow by module addition at one location
+- ships depend on fitted modules for specialized roles
+- modules consume real construction goods
+- modules interact with workforce and power
+- habitat modules are required for population support or human transport
+- storage and logistics modules matter for market participation
+
+## Relationship To Other Documents
+
+- [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md)
+  - station growth and services
+
+- [SHIPS.md](/home/jbourdon/repos/space-game/docs/SHIPS.md)
+  - ship capabilities and specialization
+
+- [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md)
+  - goods consumed or enabled by modules
+
+- [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md)
+  - workforce and habitat interaction
+
+- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md)
+  - market demand created by module construction and operation
+
+- [PRODUCTION.md](/home/jbourdon/repos/space-game/docs/PRODUCTION.md)
+  - recipes executed by production-capable modules