docs: establish official design documentation

docs/ITEMS.md

@@ -0,0 +1,227 @@
+# Items
+
+This document defines the intended item vocabulary for the simulation.
+
+Items are the goods that move through the economy, sustain population, enable construction, and support logistics.
+
+The goal of this document is not to lock every final item name immediately. It is to define the categories and roles that the economy depends on.
+
+## Design Goals
+
+The item model should support:
+
+- market-driven trade
+- construction demand
+- station operation
+- workforce support
+- transport specialization
+- future industrial depth without immediate overcomplication
+
+## Core Principles
+
+- items should have clear economic purpose
+- items should belong to recognizable categories
+- population needs should be represented with real goods
+- station construction should consume real goods
+- cargo specialization should matter where useful
+
+## Major Item Categories
+
+The intended categories are:
+
+1. raw resources
+2. processed industrial goods
+3. life-support goods
+4. civilian goods
+5. fuel and power-chain goods
+6. construction goods
+7. population-related units
+8. special logistics goods later
+
+## Raw Resources
+
+These are extracted directly from the world or from near-direct processing.
+
+Examples:
+
+- ore
+- gas
+- water if treated as an extractable resource
+- biological feed inputs later if needed
+
+Raw resources are the base of the production chain.
+
+## Processed Industrial Goods
+
+These are materials produced from raw resources and used for further production.
+
+Examples:
+
+- refined metals
+- structural materials
+- electronics later
+- machinery later
+
+These goods should feed construction, station operation, and advanced industry.
+
+## Life-Support Goods
+
+These are required to sustain population.
+
+Core life-support goods:
+
+- food
+- water
+- energy
+
+These are not optional luxuries. They are fundamental operating requirements for workforce survival.
+
+## Civilian Goods
+
+These are goods consumed by population beyond pure survival.
+
+Current important example:
+
+- consumer goods
+
+These goods should matter for workforce health, quality of life, and possibly future growth modifiers.
+
+## Fuel And Power-Chain Goods
+
+These are the goods that keep ships and stations running.
+
+Examples:
+
+- gas as an energy-chain input
+- fuel as a refined operational good
+
+The exact chain may evolve, but the important distinction is:
+
+- some goods are energy inputs
+- some goods are operational fuels
+
+## Construction Goods
+
+These are the goods used to build stations and possibly ships.
+
+Examples:
+
+- station construction materials
+- ship construction materials
+- module construction materials
+
+The exact item split can remain flexible for now, but construction should consume real goods rather than abstract progress only.
+
+Construction storage at a station site should create demand for these goods through the normal market system.
+
+## Population-Related Units
+
+Population itself should be treated as a tracked resource, but not as an ordinary trade good in the same sense as metal or fuel.
+
+Important distinctions:
+
+- workers are population units
+- commanders are population-derived special units
+- workers can be transported
+- commanders are created from population over time
+
+Population transport should remain controlled by workforce and ship rules rather than being treated as a trivial cargo commodity.
+
+## Livestock And Food Loop
+
+Livestock should exist as part of the food loop.
+
+This implies:
+
+- livestock is distinct from workers
+- livestock may require dedicated transport or handling rules later
+- livestock supports food production rather than station staffing
+
+## Item Role Examples
+
+The current design implies at least these roles:
+
+- `ore`
+  - raw industrial input
+
+- `gas`
+  - raw fuel-chain input
+
+- `fuel`
+  - operational energy good
+
+- `food`
+  - workforce life-support
+
+- `water`
+  - workforce life-support
+
+- `consumer-goods`
+  - workforce support / civilian demand
+
+- `workers`
+  - transported population units
+
+- `construction-materials`
+  - station and module building input
+
+The final names can change, but the economic roles should stay stable.
+
+## Storage And Compatibility
+
+Not every item should necessarily fit in every hold type forever.
+
+Useful distinctions later may include:
+
+- bulk industrial cargo
+- liquid cargo
+- gas cargo
+- containerized finished goods
+- human transport capacity
+- livestock capacity
+
+For now, the important rule is simply:
+
+- item class should eventually matter for transport and storage design
+
+## Market Behavior
+
+Items should participate in the market according to their role.
+
+Examples:
+
+- life-support goods generate recurring demand
+- fuel goods generate operational demand
+- construction goods generate burst demand during expansion
+- industrial goods feed production chains
+- worker transport supports station staffing
+
+This should help the economy create natural recurring and temporary market pressures.
+
+## Item Importance To Other Systems
+
+Items are the bridge between major game systems:
+
+- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md)
+  - buy and sell orders are item-driven
+
+- [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md)
+  - population survival depends on specific goods
+
+- [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md)
+  - station construction and operation consume goods
+
+- [SHIPS.md](/home/jbourdon/repos/space-game/docs/SHIPS.md)
+  - ship transport depends on what kind of item is being moved
+
+## Minimum Rules
+
+The following rules should remain true unless deliberately revised:
+
+- workforce depends on real support goods
+- station construction depends on real construction goods
+- fuel and industrial chains are item-based
+- workers are movable population units
+- commanders are not ordinary trade cargo
+- livestock is distinct from workers
+- item categories should eventually matter for storage and transport