docs: establish official design documentation

docs/WORKFORCE.md

@@ -0,0 +1,196 @@
+# Workforce
+
+This document defines population, workforce, habitats, and commander generation.
+
+Workforce is a station-side resource that connects economy, commanders, logistics, and station efficiency.
+
+See [DATA-MODEL.md](/home/jbourdon/repos/space-game/docs/DATA-MODEL.md) for the explicit station-side fields implied by this model.
+
+## Core Principles
+
+- population exists at stations, not only as an abstract total
+- each station tracks its own population
+- factions still have meaningful aggregate population totals
+- habitats are the source of population growth
+- workers consume life-support and civilian goods
+- workforce determines station efficiency
+- commanders are generated from faction population over time
+
+## Population Model
+
+Population should be tracked at two levels:
+
+- per-station population
+- per-faction aggregate population
+
+The station level is the primary simulation truth because population lives, grows, and dies at stations.
+
+The faction level is the strategic aggregate used for:
+
+- faction scale
+- workforce planning
+- commander availability
+- demographic growth
+
+## Habitats
+
+Population growth should happen only at stations for now.
+
+Habitat modules are required for population growth.
+
+Habitats allow stations to:
+
+- house workers
+- grow population
+- sustain future commander generation
+
+Ships do not generate population.
+
+## Worker Needs
+
+Workers consume, per worker:
+
+- food
+- water
+- energy
+- consumer goods
+
+These should be understood using the item roles defined in [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md).
+
+If these needs are not met, workers should die over time.
+
+This should be a gradual attrition model rather than an instant binary failure.
+
+## Workforce Efficiency
+
+A workforce is required for peak station performance.
+
+Each module should have a workforce requirement for `100%` efficiency.
+
+For now:
+
+- workforce scales all modules equally
+- there is no special per-module workforce rule
+
+A station can still operate without workers, but only at a baseline level.
+
+Current intended baseline:
+
+- `10%` efficiency at `0%` workforce
+
+This means:
+
+- `0%` workforce satisfaction gives baseline operation
+- `100%` workforce satisfaction gives peak operation
+- intermediate staffing gives proportional efficiency
+
+## Population Transport
+
+Population can be moved between stations.
+
+This supports strategies such as:
+
+- growing population at a major habitat station
+- feeding workers to industrial stations
+- staffing newly founded frontier stations
+- rebuilding stations after demographic collapse
+
+Population remains a station-side resource, even while being transported.
+
+## Human Transport Requirement
+
+Ships need a habitat module to transport humans.
+
+This keeps population transport distinct from ordinary cargo hauling.
+
+Related note:
+
+- livestock modules also exist as part of the food loop
+
+## Commanders And Population
+
+Commanders are created from a faction's worker base.
+
+The intent is:
+
+- more faction population yields more available commanders over time
+- commanders are rare relative to workers
+
+An approximate working rule is acceptable for now.
+
+Example rule:
+
+- for each `1000` faction population, one commander is generated every `1 hour`
+
+The exact formula can change later. The important rule is that commanders are population-backed rather than free.
+
+## Commander Consumption
+
+Commanders are consumed permanently when created and assigned.
+
+They are not temporarily borrowed and returned to a pool.
+
+If a commander dies:
+
+- that commander is gone
+
+This gives commanders real cost and strategic value.
+
+## Founding And Staffing
+
+A newly founded station may begin with:
+
+- zero workers
+- construction storage
+- no local commander yet
+
+It can still exist and operate at baseline efficiency, but it remains weak until supplied with:
+
+- fuel
+- workers
+- support goods
+- eventually a station commander
+
+## Failure And Attrition
+
+If a station loses required support resources, population should die over time.
+
+Relevant shortages include:
+
+- food shortage
+- water shortage
+- energy shortage
+- consumer goods shortage
+
+This gives logistics failure lasting demographic consequences.
+
+## Ownership And Identity
+
+Station population is the local operational truth.
+
+Faction population is the strategic aggregate.
+
+That distinction is enough for now. It does not require a more complicated ownership doctrine yet.
+
+## Minimum Rules
+
+The following rules should remain true unless deliberately revised:
+
+- population grows only at stations for now
+- habitat modules are required for growth
+- workers consume food, water, energy, and consumer goods
+- workforce affects station efficiency
+- stations retain a small baseline efficiency at zero workforce
+- population can be transported between stations
+- transporting humans requires a habitat-capable ship module
+- commanders are generated from faction population over time
+- commanders are permanently consumed when created
+- dead commanders do not return to the pool
+
+## Relationship To Other Documents
+
+- [COMMANDERS.md](/home/jbourdon/repos/space-game/docs/COMMANDERS.md)
+- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md)
+- [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md)
+- [SHIPS.md](/home/jbourdon/repos/space-game/docs/SHIPS.md)
+- [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md)