docs: establish official design documentation

docs/PRODUCTION.md

@@ -0,0 +1,271 @@
+# Production
+
+This document defines the intended production model for the simulation.
+
+Production is how modules consume inputs over time and turn them into useful outputs.
+
+It connects items, modules, workforce, and market behavior into a continuous economic loop.
+
+## Design Goals
+
+The production model should support:
+
+- clear input-to-output conversion
+- station specialization through module choice
+- real supply-chain pressure
+- visible bottlenecks
+- workforce-sensitive throughput
+- construction as part of the same economic logic
+
+## Core Principles
+
+- production should consume real goods
+- production should take time
+- production should depend on module capability
+- production should be affected by workforce and power state
+- shortages should halt or degrade output naturally
+
+## Production Units
+
+The core production concepts should be:
+
+- `recipe`
+- `production module`
+- `input inventory`
+- `output inventory`
+- `cycle time`
+- `throughput`
+
+This is enough to define most of the industrial simulation at a high level.
+
+## Recipes
+
+A recipe is a conversion rule from one set of goods to another.
+
+A recipe should conceptually define:
+
+- required input items
+- produced output items
+- cycle time
+- valid producing module types
+- optional workforce requirement
+- optional power or fuel requirement
+
+Recipes should be first-class design objects, not hidden assumptions inside modules.
+
+## Production Modules
+
+Recipes are executed by production-capable modules.
+
+Examples:
+
+- refinery module
+- fuel processing module
+- factory module
+- food-chain module later
+- shipyard support module
+
+Modules define what recipes an entity can run.
+
+Recipes define what actual transformation occurs.
+
+## Production Flow
+
+The intended production flow is:
+
+1. a station has the required production module
+2. required inputs exist in inventory
+3. the module has enough power and operational support
+4. the recipe runs for its cycle time
+5. outputs are added to station inventory
+6. the station commander updates market behavior based on new shortages or surpluses
+
+This keeps production grounded in world state rather than in abstract magic conversion.
+
+## Time And Throughput
+
+Production should be time-based.
+
+That means:
+
+- recipes take time to complete
+- modules have finite throughput
+- more modules should generally mean more production capacity
+- better staffing should improve effective throughput
+
+Throughput should be visibly affected by:
+
+- module count
+- workforce percentage
+- input availability
+- power availability
+
+## Workforce Interaction
+
+Production should respect the workforce rules in [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md).
+
+For now:
+
+- workforce scales production effectiveness the same way it scales other module effectiveness
+- zero-workforce stations still retain baseline production
+- full staffing yields peak production
+
+This keeps the initial system consistent and simple.
+
+## Power Interaction
+
+Production should also respect power and fuel state.
+
+Without power:
+
+- production stops
+
+This is especially important for stations because no-fuel means no-power, and no-power means no normal operation.
+
+## Input Shortage Behavior
+
+If inputs are missing:
+
+- the recipe cannot complete
+
+This should naturally create market demand rather than needing a special shortage system layered on top.
+
+Input shortage should be one of the primary reasons station commanders publish buy orders.
+
+## Output And Inventory Pressure
+
+Production also depends on output handling.
+
+If output storage is full or constrained:
+
+- production should stop or stall
+
+This gives storage modules and logistics real importance.
+
+## Example Production Chains
+
+The exact recipes can evolve, but the intended shape includes chains like:
+
+1. raw extraction
+   - ore
+   - gas
+   - water later if extracted directly
+
+2. refining or processing
+   - ore -> refined goods
+   - gas -> fuel
+   - food-loop conversions later
+
+3. industrial use
+   - refined goods -> construction goods
+   - processed goods -> module or ship build inputs
+
+4. population support
+   - food, water, energy, consumer goods -> workforce survival and growth support
+
+These chains should create meaningful interdependence between station roles.
+
+## Construction As Production
+
+Construction should be treated as a special production form rather than a completely unrelated system.
+
+This applies to:
+
+- station founding
+- station module expansion
+- ship construction later
+
+The same general pattern should hold:
+
+1. desired build target defines required goods
+2. required goods are delivered
+3. build progress consumes those goods over time
+4. build output becomes a completed structure, module, or ship
+
+This keeps construction inside the same economic language as the rest of the simulation.
+
+## Construction Storage
+
+Construction storage should act as the temporary industrial interface for building.
+
+It should:
+
+- hold required construction goods
+- publish demand through buy orders
+- allow delivery by traders or support ships
+- feed the actual building process
+
+This is especially important during station founding at claimed Lagrange points.
+
+## Production Queues
+
+Stations should eventually be able to run more than one productive concern at once.
+
+The exact queue model can stay simple for now, but the design should support:
+
+- one recipe per module at a time
+- multiple modules running independently
+- commander-controlled production priorities
+
+That is enough to express useful industrial behavior without needing a fully complex factory UI yet.
+
+## Commander Interaction
+
+Production should feed directly into station commander behavior.
+
+Station commanders should observe:
+
+- current recipe needs
+- input shortages
+- output surpluses
+- workforce limitations
+- power limitations
+
+Based on that, they should:
+
+- create buy orders
+- create sell orders
+- reprioritize station activity
+- request logistics support
+
+## Profit And Production
+
+Production is not only about self-sufficiency.
+
+Stations should produce when it is useful because:
+
+- they need the output internally
+- the output can be sold profitably
+- the output supports faction strategy
+
+This lets industrial behavior emerge from a mix of necessity and opportunity.
+
+## Minimum Rules
+
+The following rules should remain true unless deliberately revised:
+
+- production consumes real inputs
+- production takes time
+- modules determine what recipes can run
+- workforce affects production throughput
+- lack of power stops normal production
+- lack of inputs halts recipe completion
+- storage limits can bottleneck output
+- construction is a specialized form of production
+
+## Relationship To Other Documents
+
+- [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md)
+  - defines what goods flow through recipes
+
+- [MODULES.md](/home/jbourdon/repos/space-game/docs/MODULES.md)
+  - defines which modules can execute production
+
+- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md)
+  - defines how production shortages and surpluses affect the market
+
+- [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md)
+  - defines station roles that host production
+
+- [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md)
+  - defines workforce scaling and survival constraints