split data in separate files

docs/buildings/_index.md

@@ -0,0 +1,38 @@
+# Buildings
+
+All production, service, and infrastructure buildings in Anno 117.
+
+## Categories
+
+### Raw Materials Production
+- [Woodcutter Hut](./woodcutter-hut.md) - Produces Logs from forest
+- [Oat Farm](./oat-farm.md) - Produces Oats
+- [Hemp Farm](./hemp-farm.md) - Produces Hemp
+- [Flax Farm (Albion)](./flax-farm-albion.md) - Produces Flax
+
+### Fisheries
+- [Fishing Hut (Latium)](./fishing-hut-latium.md) - Produces Sardines
+- [Mackerel Fishing Hut (Latium)](./mackerel-fishing-hut-latium.md) - Produces Mackerel
+- [Cockle Picker (Albion)](./cockle-picker-albion.md) - Produces Cockles
+- [Eel Grabber (Albion)](./eel-grabber-albion.md) - Produces Eels
+
+### Processing
+- [Sawmill](./sawmill.md) - Logs to Timber
+- [Porridge Stand](./porridge-stand.md) - Oats to Porridge
+- [Spinner](./spinner.md) - Hemp to Tunics
+- [Salt Gardens (Latium)](./salt-gardens-latium.md) - Produces Salt
+- [Garum Maker (Latium)](./garum-maker-latium.md) - Produces Garum
+
+### Food Production (Tier II)
+- [Bakery](./bakery.md) - Produces Bread
+
+## Placement Rules
+
+Most buildings require:
+- **Road connection** for goods transport
+- **Warehouse in range** for storage access
+- Some have **special constraints** (coast, marsh, forest, fields, fertility)
+
+## Schema Reference
+
+See [Building Schema](../schemas/building.md) for the complete field definitions.

docs/buildings/bakery.md

@@ -0,0 +1,39 @@
+# Bakery
+
+**Entity Type:** Building
+
+## Properties
+
+| Field | Value |
+|-------|-------|
+| Category | Production / Food (Tier II) |
+| Required Tier | [Tier II](../population-tiers/tier-ii.md) |
+| Cycle Time | 60 seconds |
+
+## Description
+
+Produces Bread (Tier II staple); high upkeep.
+
+## Costs
+
+**Build Cost:** Unknown in supplied snippets
+
+**Maintenance:** -14 gold/min, 3 Tier II workers
+
+## Production
+
+**Input:** Flour + Charcoal (implied by chain text)
+
+**Output:** Bread
+
+## Production Chain
+
+[Bread Chain](../production-chains/bread.md)
+
+## Usage Patterns
+
+Only scale to actual consumption; bakeries are a common cashflow killer.
+
+## Common Pitfalls
+
+Overbuilding bakeries leads to negative income swings; missing charcoal leads to "mystery" bread shortages.

docs/buildings/cockle-picker-albion.md

@@ -0,0 +1,35 @@
+# Cockle Picker (Albion)
+
+**Entity Type:** Building
+
+## Properties
+
+| Field | Value |
+|-------|-------|
+| Region | Albion |
+| Category | Production / Food (Fishery analogue) |
+| Required Tier | [Tier I](../population-tiers/tier-i.md) |
+
+## Description
+
+Coastal gatherer producing Cockles for Waders.
+
+## Costs
+
+**Build Cost:** Unknown (research says "similar to Fishing Hut")
+
+**Maintenance:** Unknown
+
+## Placement
+
+| Requirement | Value |
+|-------------|-------|
+| Constraints | Coast (Albion) |
+
+## Usage Patterns
+
+Albion starter food option.
+
+## Common Pitfalls
+
+Confusing coast vs marsh producers in Albion.

docs/buildings/eel-grabber-albion.md

@@ -0,0 +1,36 @@
+# Eel Grabber (Albion)
+
+**Entity Type:** Building
+
+## Properties
+
+| Field | Value |
+|-------|-------|
+| Region | Albion |
+| Category | Production / Food (Marsh fishery) |
+| Required Tier | [Tier I](../population-tiers/tier-i.md) |
+| Cycle Time | Unknown (likely 60s per research wording; not asserted) |
+
+## Description
+
+Marshland fish producer (Eels).
+
+## Costs
+
+**Build Cost:** Unknown
+
+**Maintenance:** Unknown
+
+## Placement
+
+| Requirement | Value |
+|-------------|-------|
+| Constraints | Marshland placement required (Albion-specific) |
+
+## Usage Patterns
+
+Place in marsh; pair with coastal cockles early.
+
+## Common Pitfalls
+
+Trying to place on coast; this is a marsh-only building.

docs/buildings/fishing-hut-latium.md

@@ -0,0 +1,64 @@
+# Fishing Hut (Latium)
+
+**Entity Type:** Building
+
+## Properties
+
+| Field | Value |
+|-------|-------|
+| Region | Latium |
+| Category | Production / Fishery |
+| Required Tier | [Liberti](../population-tiers/tier-i.md) |
+| Dimensions | 3x8 (base), 4x11 (with roads) |
+| Cycle Time | 60 seconds |
+
+## Description
+
+Coastal fishery producing Sardines.
+
+## Costs
+
+**Build Cost:** 2 Planks
+
+**Maintenance:** -6 gold, 4 Liberti workers
+
+## Placement
+
+| Requirement | Value |
+|-------------|-------|
+| Constraints | Harbor Area required |
+
+## Production
+
+**Input:** None
+
+**Output:** [Sardines](../goods/sardines.md)
+
+## Attributes Provided
+
+| Attribute | Value |
+|-----------|-------|
+| Population | +1 |
+| Income | +1 |
+
+## Production Chain
+
+[Tier I Food Chain](../production-chains/tier-i-food.md)
+
+## Specialists
+
+| Specialist | Effects |
+|------------|---------|
+| Servia Bellia | +25% productivity, +1 income area effect |
+| Netzangler | +10% productivity |
+| Umdenkerin | -25% workforce |
+| Venator der Artemis | -33% workforce, -66% maintenance |
+| Uiscarix | +1.5 income area effect |
+
+## Usage Patterns
+
+Cluster fisheries for specialist + area-effect stacking.
+
+## Common Pitfalls
+
+Overbuilt fisheries lead to gold bleed; also "need flicker" if storage/transport dips.

docs/buildings/flax-farm-albion.md

@@ -0,0 +1,46 @@
+# Flax Farm (Albion)
+
+**Entity Type:** Building
+
+## Properties
+
+| Field | Value |
+|-------|-------|
+| Region | Albion |
+| Category | Production / Farm |
+| Required Tier | Nobles (Tier 5 Celtic) |
+| Dimensions | 4x5 (base), 6x7 (with roads) |
+| Cycle Time | 90 seconds |
+| Aqueduct Support | Yes |
+
+## Description
+
+Produces Flax for clothing production chains.
+
+## Costs
+
+**Build Cost:** 1 Planks, 2 Bricks, 2 Concrete
+
+**Maintenance:** -8 gold, 3 Waders workers
+
+## Placement
+
+| Requirement | Value |
+|-------------|-------|
+| Constraints | Fields required |
+
+## Production
+
+**Input:** None
+
+**Output:** [Flax](../goods/flax.md)
+
+## Specialists
+
+| Specialist | Effects |
+|------------|---------|
+| Irrigator | -50% water consumption |
+| Excellent Hair Artist | +20% productivity for Wigs chain |
+| Princeps of Porphyry | +20% productivity for Togas chain |
+| Tullus Caecilius Cornutus | -40% workforce, -80% maintenance |
+| Casponia Casta | +25% productivity, +1 Flax every 10 cycles, +1 Faith area effect (requires Ceres as island god) |

docs/buildings/garum-maker-latium.md

@@ -0,0 +1,27 @@
+# Garum Maker (Latium)
+
+**Entity Type:** Building
+
+## Properties
+
+| Field | Value |
+|-------|-------|
+| Region | Latium |
+| Category | Production / Food Processing |
+| Required Tier | [Plebeians](../population-tiers/tier-ii.md) |
+
+## Description
+
+Produces Garum fish sauce from Mackerel and Salt.
+
+## Production
+
+**Input:** [Mackerel](../goods/mackerel.md), [Salt](../goods/salt.md)
+
+**Output:** [Garum](../goods/garum.md)
+
+## Specialists
+
+| Specialist | Effects |
+|------------|---------|
+| Fischdozentin | +10% productivity for Garum chain |

docs/buildings/hemp-farm.md

@@ -0,0 +1,47 @@
+# Hemp Farm
+
+**Entity Type:** Building
+
+## Properties
+
+| Field | Value |
+|-------|-------|
+| Category | Production / Agriculture |
+| Required Tier | [Tier I](../population-tiers/tier-i.md) |
+| Cycle Time | 60 seconds |
+
+## Description
+
+Produces Hemp for Tunics; uses fields; aqueduct optional.
+
+## Costs
+
+**Build Cost:** 2 Timber
+
+**Maintenance:** -4 gold/min, 3 Tier I workers
+
+## Placement
+
+| Requirement | Value |
+|-------------|-------|
+| Road Required | Yes |
+| Warehouse Required | Yes |
+| Constraints | Fields + correct fertility |
+
+## Production
+
+**Input:** None
+
+**Output:** [Hemp](../goods/hemp.md)
+
+## Production Chain
+
+[Tunics Chain](../production-chains/tunics.md)
+
+## Usage Patterns
+
+Keep close to Spinner; reduce hauling delays.
+
+## Common Pitfalls
+
+Too few fields or long hauling times leads to spinner starvation.

docs/buildings/mackerel-fishing-hut-latium.md

@@ -0,0 +1,45 @@
+# Mackerel Fishing Hut (Latium)
+
+**Entity Type:** Building
+
+## Properties
+
+| Field | Value |
+|-------|-------|
+| Region | Latium |
+| Category | Production / Fishery |
+| Required Tier | [Plebeians](../population-tiers/tier-ii.md) |
+| Dimensions | 4x9 (base), 6x13 (with roads) |
+| Cycle Time | 60 seconds |
+
+## Description
+
+Coastal fishery producing Mackerel for Garum production.
+
+## Costs
+
+**Build Cost:** 2 Planks, 1 Bricks
+
+**Maintenance:** -8 gold, 4 Liberti workers
+
+## Placement
+
+| Requirement | Value |
+|-------------|-------|
+| Constraints | Harbor Area required, Fish Population required |
+
+## Production
+
+**Input:** None
+
+**Output:** [Mackerel](../goods/mackerel.md)
+
+## Specialists
+
+| Specialist | Effects |
+|------------|---------|
+| Servia Bellia | +25% productivity |
+| Fischdozentin | +10% productivity for Garum chain |
+| Umdenkerin | -25% workforce, changes to Plebeian workforce |
+| Venator der Artemis | -33% workforce, -66% maintenance |
+| Uiscarix | +1.5 income area effect |

docs/buildings/oat-farm.md

@@ -0,0 +1,48 @@
+# Oat Farm
+
+**Entity Type:** Building
+
+## Properties
+
+| Field | Value |
+|-------|-------|
+| Category | Production / Agriculture |
+| Required Tier | [Tier I](../population-tiers/tier-i.md) |
+| Construction Time | Instant |
+| Cycle Time | 60 seconds |
+
+## Description
+
+Produces Oats; uses field modules; aqueduct optional.
+
+## Costs
+
+**Build Cost:** 3 Timber
+
+**Maintenance:** -4 gold/min, 3 Tier I workers
+
+## Placement
+
+| Requirement | Value |
+|-------------|-------|
+| Road Required | Yes |
+| Warehouse Required | Yes |
+| Constraints | Requires fields; requires relevant fertility (oat/grain) |
+
+## Production
+
+**Input:** None
+
+**Output:** [Oats](../goods/oats.md)
+
+## Production Chain
+
+[Porridge Chain](../production-chains/porridge.md)
+
+## Usage Patterns
+
+Keep fields compact; warehouse nearby; consider aqueduct support.
+
+## Common Pitfalls
+
+Insufficient fields/fertility leads to low output; long travel distance leads to apparent underproduction.

docs/buildings/porridge-stand.md

@@ -0,0 +1,48 @@
+# Porridge Stand
+
+**Entity Type:** Building
+
+## Properties
+
+| Field | Value |
+|-------|-------|
+| Category | Production / Food |
+| Required Tier | [Tier I](../population-tiers/tier-i.md) |
+| Construction Time | Instant |
+| Cycle Time | 60 seconds |
+
+## Description
+
+Converts Oats to Porridge.
+
+## Costs
+
+**Build Cost:** 2 Timber
+
+**Maintenance:** -8 gold/min, 2 Tier I workers
+
+## Placement
+
+| Requirement | Value |
+|-------------|-------|
+| Road Required | Yes |
+| Warehouse Required | Yes |
+| Constraints | Needs road/warehouse |
+
+## Production
+
+**Input:** [Oats](../goods/oats.md)
+
+**Output:** [Porridge](../goods/porridge.md)
+
+## Production Chain
+
+[Porridge Chain](../production-chains/porridge.md)
+
+## Usage Patterns
+
+Pair 1:1 with Oat Farms for balanced flow (both 60s).
+
+## Common Pitfalls
+
+Oats delivered too slowly leads to porridge "flicker" and population drops.

docs/buildings/salt-gardens-latium.md

@@ -0,0 +1,34 @@
+# Salt Gardens (Latium)
+
+**Entity Type:** Building
+
+## Properties
+
+| Field | Value |
+|-------|-------|
+| Region | Latium |
+| Category | Production / Raw Materials |
+| Required Tier | [Plebeians](../population-tiers/tier-ii.md) |
+
+## Description
+
+Coastal salt extraction facility.
+
+## Placement
+
+| Requirement | Value |
+|-------------|-------|
+| Constraints | Harbor Area required |
+
+## Production
+
+**Input:** None
+
+**Output:** [Salt](../goods/salt.md)
+
+## Specialists
+
+| Specialist | Effects |
+|------------|---------|
+| Servia Bellia | +25% productivity |
+| Fischdozentin | +10% productivity for Garum chain |

docs/buildings/sawmill.md

@@ -0,0 +1,48 @@
+# Sawmill
+
+**Entity Type:** Building
+
+## Properties
+
+| Field | Value |
+|-------|-------|
+| Category | Production / Construction Materials |
+| Required Tier | [Tier I](../population-tiers/tier-i.md) |
+| Construction Time | Instant |
+| Cycle Time | 30 seconds |
+
+## Description
+
+Converts Logs to Timber planks.
+
+## Costs
+
+**Build Cost:** 2 Timber
+
+**Maintenance:** -5 gold/min, 2 Tier I workers
+
+## Placement
+
+| Requirement | Value |
+|-------------|-------|
+| Road Required | Yes |
+| Warehouse Required | Yes |
+| Constraints | None special (but requires logistics) |
+
+## Production
+
+**Input:** Logs
+
+**Output:** [Timber](../goods/timber.md)
+
+## Production Chain
+
+[Timber Chain](../production-chains/timber.md)
+
+## Usage Patterns
+
+Pair 1:1 with Woodcutters (matching 30s cycles).
+
+## Common Pitfalls
+
+Too many sawmills leads to upkeep drain without benefit.

docs/buildings/spinner.md

@@ -0,0 +1,45 @@
+# Spinner
+
+**Entity Type:** Building
+
+## Properties
+
+| Field | Value |
+|-------|-------|
+| Category | Production / Clothing |
+| Required Tier | [Tier I](../population-tiers/tier-i.md) |
+| Cycle Time | 30 seconds |
+
+## Description
+
+Converts Hemp to Tunics; provides local income area effect.
+
+## Costs
+
+**Build Cost:** 2 Timber
+
+**Maintenance:** -8 gold/min, 3 Tier I workers
+
+## Production
+
+**Input:** [Hemp](../goods/hemp.md)
+
+**Output:** [Tunics](../goods/tunics.md)
+
+## Area Effects
+
+| Type | Value | Target |
+|------|-------|--------|
+| Income Area Effect | +1 | Nearby buildings (incl residences) |
+
+## Production Chain
+
+[Tunics Chain](../production-chains/tunics.md)
+
+## Usage Patterns
+
+Place near residences to maximize income area effect.
+
+## Common Pitfalls
+
+Spinner output can be fine while income effect is wasted if placed far from housing.

docs/buildings/woodcutter-hut.md

@@ -0,0 +1,48 @@
+# Woodcutter Hut
+
+**Entity Type:** Building
+
+## Properties
+
+| Field | Value |
+|-------|-------|
+| Category | Production / Raw Materials |
+| Required Tier | [Tier I](../population-tiers/tier-i.md) |
+| Construction Time | Instant |
+| Cycle Time | 30 seconds |
+
+## Description
+
+Produces Logs from forest density.
+
+## Costs
+
+**Build Cost:** 2 Timber
+
+**Maintenance:** -5 gold/min, 2 Tier I workers
+
+## Placement
+
+| Requirement | Value |
+|-------------|-------|
+| Road Required | Yes |
+| Warehouse Required | Yes |
+| Constraints | Forest overlap required; low density reduces productivity |
+
+## Production
+
+**Input:** None
+
+**Output:** Logs (Unknown Good entry)
+
+## Production Chain
+
+[Timber Chain](../production-chains/timber.md)
+
+## Usage Patterns
+
+Place deep in dense forest, keep a warehouse in range.
+
+## Common Pitfalls
+
+Sparse forest leads to "mystery" timber shortages downstream.

docs/glossary.md

@@ -0,0 +1,29 @@
+# Glossary
+
+Key terms and definitions used throughout the documentation.
+
+## Terms
+
+### Area Effect
+Radius-based modifier from a building or specialist (income, happiness, safety). Shown by green/red arrows during building placement.
+
+### Need Flicker
+A need repeatedly turning on/off because storage hits zero intermittently. Often caused by transport delays or production imbalance.
+
+### Throughput
+Effective goods per time, impacted by cycle time and logistics. Higher throughput means more goods delivered per minute.
+
+### Upkeep
+Ongoing gold loss and workforce reservation for a building. Most buildings have both gold and worker maintenance costs.
+
+### Warehouse Cloud
+Shared island storage accessible via connected warehouses/trading post. All buildings in range share access to stored goods.
+
+### Cycle Time
+The time in seconds for a building to complete one production cycle. Used to calculate building ratios in production chains.
+
+### Fertility
+Terrain property that determines what crops can be grown. Farms require specific fertility types to operate.
+
+### Placement Constraints
+Special requirements for where buildings can be placed (coast, marsh, forest, fields, etc.).

docs/goods/_index.md

@@ -0,0 +1,31 @@
+# Goods
+
+All tradeable and consumable items in Anno 117. Goods are categorized by their primary use.
+
+## Categories
+
+### Food
+Basic consumption goods that satisfy population food needs.
+- [Sardines](./sardines.md) - Liberti food (Latium)
+- [Porridge](./porridge.md) - Tier I food
+- [Garum](./garum.md) - Plebeians food (Latium)
+
+### Agricultural / Raw Materials
+Base materials harvested from the land.
+- [Oats](./oats.md) - Input for Porridge
+- [Hemp](./hemp.md) - Input for Tunics
+- [Flax](./flax.md) - Input for Wigs and Togas chains
+- [Mackerel](./mackerel.md) - Input for Garum
+- [Salt](./salt.md) - Input for Garum
+
+### Construction Materials
+Materials used for building construction.
+- [Timber](./timber.md) - Basic construction material
+
+### Clothing / Fashion
+Goods that satisfy population clothing needs.
+- [Tunics](./tunics.md) - Tier I fashion
+
+## Schema Reference
+
+See [Good Schema](../schemas/good.md) for the complete field definitions.

docs/goods/flax.md

@@ -0,0 +1,20 @@
+# Flax
+
+**Entity Type:** Good
+
+## Properties
+
+| Field | Value |
+|-------|-------|
+| Category | Raw Material / Agricultural |
+| Used For | Input (Wigs production chain, Togas production chain) |
+
+## Production
+
+**Produced By:**
+- [Flax Farm (Albion)](../buildings/flax-farm-albion.md)
+- Flax Farm (Latium)
+
+**Consumed By:**
+- Hairnet Weaver
+- Weaver

docs/goods/garum.md

@@ -0,0 +1,22 @@
+# Garum
+
+**Entity Type:** Good
+
+## Properties
+
+| Field | Value |
+|-------|-------|
+| Category | Need / Food |
+| Used For | Consumption (Plebeians Food need) |
+| Available From | Plebeians |
+
+## Production
+
+**Produced By:** [Garum Maker (Latium)](../buildings/garum-maker-latium.md)
+
+**Consumed By:** [Plebeians](../population-tiers/tier-ii.md)
+
+## Inputs Required
+
+- [Mackerel](./mackerel.md)
+- [Salt](./salt.md)

docs/goods/hemp.md

@@ -0,0 +1,20 @@
+# Hemp
+
+**Entity Type:** Good
+
+## Properties
+
+| Field | Value |
+|-------|-------|
+| Category | Agricultural |
+| Used For | Input (Tunics) |
+
+## Production
+
+**Produced By:** [Hemp Farm](../buildings/hemp-farm.md)
+
+**Consumed By:** [Spinner](../buildings/spinner.md)
+
+## Related Chain
+
+[Tunics Chain](../production-chains/tunics.md)

docs/goods/mackerel.md

@@ -0,0 +1,19 @@
+# Mackerel
+
+**Entity Type:** Good
+
+## Properties
+
+| Field | Value |
+|-------|-------|
+| Category | Raw Material / Agricultural |
+| Used For | Input (Garum production) |
+| Buy Price | 16 Dinare |
+| Sell Price | 6 Dinare |
+| Available From | Plebeians |
+
+## Production
+
+**Produced By:** [Mackerel Fishing Hut (Latium)](../buildings/mackerel-fishing-hut-latium.md)
+
+**Consumed By:** [Garum Maker (Latium)](../buildings/garum-maker-latium.md)

docs/goods/oats.md

@@ -0,0 +1,20 @@
+# Oats
+
+**Entity Type:** Good
+
+## Properties
+
+| Field | Value |
+|-------|-------|
+| Category | Agricultural |
+| Used For | Input (Porridge) |
+
+## Production
+
+**Produced By:** [Oat Farm](../buildings/oat-farm.md)
+
+**Consumed By:** [Porridge Stand](../buildings/porridge-stand.md)
+
+## Related Chain
+
+[Porridge Chain](../production-chains/porridge.md)

docs/goods/porridge.md

@@ -0,0 +1,26 @@
+# Porridge
+
+**Entity Type:** Good
+
+## Properties
+
+| Field | Value |
+|-------|-------|
+| Category | Food |
+| Used For | Consumption (Tier I Food need) |
+
+## Attributes
+
+| Attribute | Value |
+|-----------|-------|
+| Population | +2 (per house when fulfilling Food need) |
+
+## Production
+
+**Produced By:** [Porridge Stand](../buildings/porridge-stand.md)
+
+**Consumed By:** [Tier I](../population-tiers/tier-i.md)
+
+## Related Chain
+
+[Porridge Chain](../production-chains/porridge.md)

docs/goods/salt.md

@@ -0,0 +1,17 @@
+# Salt
+
+**Entity Type:** Good
+
+## Properties
+
+| Field | Value |
+|-------|-------|
+| Category | Raw Material |
+| Used For | Input (Garum production) |
+| Available From | Plebeians |
+
+## Production
+
+**Produced By:** [Salt Gardens (Latium)](../buildings/salt-gardens-latium.md)
+
+**Consumed By:** [Garum Maker (Latium)](../buildings/garum-maker-latium.md)

docs/goods/sardines.md

@@ -0,0 +1,26 @@
+# Sardines
+
+**Entity Type:** Good
+
+## Properties
+
+| Field | Value |
+|-------|-------|
+| Category | Need / Food |
+| Used For | Consumption (Liberti Food need) |
+| Buy Price | 12 Dinare |
+| Sell Price | 4 Dinare |
+| Available From | Liberti |
+
+## Attributes
+
+| Attribute | Value |
+|-----------|-------|
+| Population | +1 |
+| Income | +1 |
+
+## Production
+
+**Produced By:** [Fishing Hut (Latium)](../buildings/fishing-hut-latium.md)
+
+**Consumed By:** [Liberti](../population-tiers/tier-i.md)

docs/goods/timber.md

@@ -0,0 +1,20 @@
+# Timber (Planks)
+
+**Entity Type:** Good
+
+## Properties
+
+| Field | Value |
+|-------|-------|
+| Category | Construction Material |
+| Used For | Construction, Inputs |
+
+## Production
+
+**Produced By:** [Sawmill](../buildings/sawmill.md)
+
+**Consumed By:** Many buildings (construction costs reference Timber widely)
+
+## Related Chain
+
+[Timber Chain](../production-chains/timber.md)

docs/goods/tunics.md

@@ -0,0 +1,26 @@
+# Tunics
+
+**Entity Type:** Good
+
+## Properties
+
+| Field | Value |
+|-------|-------|
+| Category | Clothing / Fashion |
+| Used For | Consumption (Tier I Fashion need) |
+
+## Attributes
+
+| Attribute | Value |
+|-----------|-------|
+| Population | +2 (reported) |
+
+## Production
+
+**Produced By:** [Spinner](../buildings/spinner.md)
+
+**Consumed By:** [Tier I](../population-tiers/tier-i.md)
+
+## Related Chain
+
+[Tunics Chain](../production-chains/tunics.md)

docs/index.md

@@ -0,0 +1,45 @@
+# Anno 117: Pax Romana - Game Data Reference
+
+> **Version:** 0.2 (compiled from provided research files; not yet a full extracted DB)
+> **Focus:** Sandbox / Endless Mode mechanics (no controls/UI bindings)
+>
+> **Scope Warning (important):**
+> This document only includes **entities and numeric stats explicitly present** in the supplied research files.
+> Where a field is unknown, it is marked `Unknown` (not guessed).
+
+---
+
+## Categories
+
+### [Schemas](./schemas/_index.md)
+Entity type definitions and field specifications for all game elements.
+
+### [Population Tiers](./population-tiers/_index.md)
+The four population tiers: Liberti/Waders, Plebeians/Smiths, Equites, and Patricians.
+
+### [Goods](./goods/_index.md)
+All tradeable and consumable goods in the game, including food, materials, and luxury items.
+
+### [Buildings](./buildings/_index.md)
+Production facilities, service buildings, and infrastructure.
+
+### [Production Chains](./production-chains/_index.md)
+How goods are produced and the recommended building ratios.
+
+### [Ships & Naval](./ships/_index.md)
+Ship hulls, modules, and naval combat systems.
+
+### [Specialists](./specialists/_index.md)
+Characters that can be slotted into buildings to modify stats.
+
+### [Systems](./systems/_index.md)
+Core game mechanics including trade, maintenance, and area effects.
+
+### [Monuments](./monuments/_index.md)
+Large-scale constructions with island-wide effects.
+
+### [Troubleshooting](./troubleshooting/_index.md)
+Common issues and their solutions.
+
+### [Glossary](./glossary.md)
+Key terms and definitions.

docs/monuments/_index.md

@@ -0,0 +1,20 @@
+# Monuments
+
+Large-scale constructions that provide powerful island-wide effects.
+
+## Available Monuments
+
+- [Amphitheatre](./amphitheatre.md) - Unlocked with Patricians, hosts events
+
+## Monument Mechanics
+
+- **Unique:** One per island (reported)
+- **Construction:** Multiple stages, requires expensive materials
+- **Effects:** Large radius bonuses to Population, Happiness, Prestige
+- **Events:** Can host special events consuming goods for city buffs
+
+## Construction Tips
+
+- Start monuments only when economy is stable
+- Plan for expensive materials (marble, glass, iron)
+- Consider the maintenance + diverted materials cost

docs/monuments/amphitheatre.md

@@ -0,0 +1,35 @@
+# Amphitheatre
+
+**Entity Type:** Building (Monument)
+
+## Properties
+
+| Field | Value |
+|-------|-------|
+| Unique | One per island |
+| Unlock Condition | Patricians exist (Tier IV) |
+
+## Construction
+
+- 4 stages
+- Large time + resources required
+- Later stages require expensive materials (marble/glass/iron mentioned)
+
+## Effects (Complete)
+
+| Effect | Value | Radius |
+|--------|-------|--------|
+| Population | +3 | Large |
+| Happiness | +3 | Large |
+| Prestige | +7 | Large |
+
+## Events
+
+Hosts events consuming goods/workforce for city buffs:
+- Local games
+- Grand games
+- Naumachia
+
+## Common Pitfalls
+
+Starting monument too early can bankrupt you (maintenance + diverted materials).

docs/population-tiers/_index.md

@@ -0,0 +1,25 @@
+# Population Tiers
+
+Anno 117 features a tiered population system where citizens can upgrade to higher tiers as their needs are met. Each tier provides different workforce capabilities and has unique needs.
+
+## Overview
+
+| Tier | Latium Name | Albion Name | Workforce Fraction | Notes |
+|------|-------------|-------------|-------------------|-------|
+| I | Liberti | Waders | 50% | Base workers for farms, fisheries, sawmills |
+| II | Plebeians | Mercators/Smiths | 30% | Intermediate production |
+| III | Equites | Higher Albion tiers | 20% | Complex production chains |
+| IV | Patricians | - | 0% | No workforce, high consumption |
+
+## Tiers
+
+- [Tier I - Liberti / Waders](./tier-i.md)
+- [Tier II - Plebeians / Smiths](./tier-ii.md)
+- [Tier III - Equites](./tier-iii.md)
+- [Tier IV - Patricians](./tier-iv.md)
+
+## Key Mechanics
+
+- **Workforce Balance:** Avoid upgrading all Tier I housing at once; you can lose workers needed for basic chains.
+- **Needs Categories:** Each tier has Food, Public Service, and Fashion needs that must be met for upgrades.
+- **Cascading Effects:** Higher tier shortages cascade across production chains.

docs/population-tiers/tier-i.md

@@ -0,0 +1,24 @@
+# Tier I - Liberti (Latium) / Waders (Albion)
+
+**Entity Type:** PopulationTier
+
+## Stats
+
+| Field | Value |
+|-------|-------|
+| Workforce Fraction | 50% |
+| Needs Categories | Food, Public Service, Fashion |
+
+## Notes
+
+Avoid upgrading all Tier I housing at once; you can lose Tier I workers needed for basic chains.
+
+## Common Pitfalls
+
+"Everything upgraded" leads to fisheries/farms/sawmills being understaffed.
+
+## Related
+
+- [Sardines](../goods/sardines.md) - Food need (Latium)
+- [Porridge](../goods/porridge.md) - Food need
+- [Tunics](../goods/tunics.md) - Fashion need

docs/population-tiers/tier-ii.md

@@ -0,0 +1,22 @@
+# Tier II - Plebeians (Latium) / Mercators or Smiths (Albion)
+
+**Entity Type:** PopulationTier
+
+## Stats
+
+| Field | Value |
+|-------|-------|
+| Workforce Fraction | 30% |
+
+## Notes
+
+Tier II introduces major upkeep spikes (mills/bakeries/bricks, etc.).
+
+## Common Pitfalls
+
+Overbuilding production buildings drains gold via maintenance.
+
+## Related
+
+- [Garum](../goods/garum.md) - Food need (Latium)
+- [Bread Chain](../production-chains/bread.md) - Key production chain

docs/population-tiers/tier-iii.md

@@ -0,0 +1,13 @@
+# Tier III - Equites (Latium) / Higher Albion Tiers
+
+**Entity Type:** PopulationTier
+
+## Stats
+
+| Field | Value |
+|-------|-------|
+| Workforce Fraction | 20% |
+
+## Notes
+
+Higher complexity; shortages cascade across chains.

docs/population-tiers/tier-iv.md

@@ -0,0 +1,17 @@
+# Tier IV - Patricians (Latium)
+
+**Entity Type:** PopulationTier
+
+## Stats
+
+| Field | Value |
+|-------|-------|
+| Workforce Fraction | 0% (no workforce) |
+
+## Notes
+
+Very high needs; unlock monuments like Amphitheatre.
+
+## Unlocks
+
+- [Amphitheatre](../monuments/amphitheatre.md)

docs/production-chains/_index.md

@@ -0,0 +1,27 @@
+# Production Chains
+
+Production chains define how raw materials are processed into finished goods.
+
+## Chains
+
+### Basic Chains (Tier I)
+- [Timber Chain](./timber.md) - Woodcutter -> Sawmill -> Timber
+- [Tier I Food Chain](./tier-i-food.md) - Fish and Porridge production
+- [Porridge Chain](./porridge.md) - Oat Farm -> Porridge Stand
+- [Tunics Chain](./tunics.md) - Hemp Farm -> Spinner
+
+### Intermediate Chains (Tier II)
+- [Bread Chain](./bread.md) - Wheat -> Flour -> Bread
+
+## Understanding Ratios
+
+Production chains work best when buildings are matched by their cycle times:
+- **Same cycle time:** 1:1 ratio (e.g., Woodcutter 30s : Sawmill 30s)
+- **Different cycle times:** Calculate based on output/input rates
+- **Bottlenecks:** Usually at raw material gathering or logistics
+
+## Common Issues
+
+1. **Transport delays:** Long distances between buildings reduce effective throughput
+2. **Storage overflow:** Downstream buildings can't keep up
+3. **Resource starvation:** Upstream buildings can't supply enough

docs/production-chains/bread.md

@@ -0,0 +1,20 @@
+# Chain: Bread
+
+**Entity Type:** ProductionChain
+
+## Steps (Summary)
+
+| Step | Building | Input | Output | Cycle Time |
+|------|----------|-------|--------|------------|
+| 1 | Wheat Farm | None | Grain | 60s |
+| 2 | Grain Mill | Grain | Flour | 30s |
+| 3 | [Bakery](../buildings/bakery.md) | Flour + Charcoal | Bread | 60s |
+
+## Recommended Ratios
+
+2 Wheat : 1 Mill : 2 Bakeries
+
+## Bottlenecks
+
+- Charcoal availability
+- Bakery upkeep

docs/production-chains/porridge.md

@@ -0,0 +1,20 @@
+# Chain: Porridge
+
+**Entity Type:** ProductionChain
+
+## Steps
+
+| Step | Building | Input | Output | Cycle Time |
+|------|----------|-------|--------|------------|
+| 1 | [Oat Farm](../buildings/oat-farm.md) | None | [Oats](../goods/oats.md) | 60s |
+| 2 | [Porridge Stand](../buildings/porridge-stand.md) | Oats | [Porridge](../goods/porridge.md) | 60s |
+
+## Recommended Ratios
+
+Oat Farm 1 : Porridge Stand 1 (both 60s)
+
+## Bottlenecks
+
+- Field layout
+- Fertility
+- Hauling distance

docs/production-chains/tier-i-food.md

@@ -0,0 +1,15 @@
+# Chain: Tier I Food
+
+**Entity Type:** ProductionChain
+
+## Steps
+
+| Step | Building | Input | Output | Cycle Time |
+|------|----------|-------|--------|------------|
+| 1a | [Fishing Hut](../buildings/fishing-hut-latium.md) | None | [Sardines](../goods/sardines.md) | 60s |
+| 1b | [Oat Farm](../buildings/oat-farm.md) | None | [Oats](../goods/oats.md) | 60s |
+| 2b | [Porridge Stand](../buildings/porridge-stand.md) | Oats | [Porridge](../goods/porridge.md) | 60s |
+
+## Notes
+
+Many Tier I settlements produce both Sardines and Porridge to maximize population.

docs/production-chains/timber.md

@@ -0,0 +1,18 @@
+# Chain: Timber
+
+**Entity Type:** ProductionChain
+
+## Steps
+
+| Step | Building | Input | Output | Cycle Time |
+|------|----------|-------|--------|------------|
+| 1 | [Woodcutter Hut](../buildings/woodcutter-hut.md) | None | Logs | 30s |
+| 2 | [Sawmill](../buildings/sawmill.md) | Logs | [Timber](../goods/timber.md) | 30s |
+
+## Recommended Ratios
+
+Woodcutter 1 : Sawmill 1 (matching 30s cycles)
+
+## Bottlenecks
+
+- Forest density (Woodcutter placement)

docs/production-chains/tunics.md

@@ -0,0 +1,18 @@
+# Chain: Tunics
+
+**Entity Type:** ProductionChain
+
+## Steps
+
+| Step | Building | Input | Output | Cycle Time |
+|------|----------|-------|--------|------------|
+| 1 | [Hemp Farm](../buildings/hemp-farm.md) | None | [Hemp](../goods/hemp.md) | 60s |
+| 2 | [Spinner](../buildings/spinner.md) | Hemp | [Tunics](../goods/tunics.md) | 30s |
+
+## Recommended Ratios
+
+Unknown (cycle mismatch suggests multiple spinners can consume one farm; exact throughput not given)
+
+## Notes
+
+Spinner provides an income area effect (+1) near buildings.

docs/schemas/_index.md

@@ -0,0 +1,13 @@
+# Schemas
+
+Entity type definitions that describe the structure of all game elements.
+
+## Available Schemas
+
+- [Building](./building.md) - Production, service, and infrastructure buildings
+- [Good](./good.md) - Tradeable and consumable items
+- [PopulationTier](./population-tier.md) - Citizen classes and their needs
+- [ProductionChain](./production-chain.md) - Manufacturing sequences
+- [Specialist](./specialist.md) - Characters that modify building stats
+- [ShipHull](./ship-hull.md) - Ship base types
+- [ShipModule](./ship-module.md) - Ship equipment and upgrades

docs/schemas/building.md

@@ -0,0 +1,32 @@
+# Schema: Building
+
+**Entity Type:** `Building`
+
+## Fields
+
+| Field | Type | Notes |
+|------|------|------|
+| id | string | stable anchor id |
+| name | string | display name |
+| category | string | Production / Service / Safety / Monument / etc. |
+| description | string | 1-2 lines max |
+| region | string | Latium / Albion (if region-specific) |
+| requiredPopulationTier | string | link to tier |
+| buildCost | object | `{ gold?, goods[] }` |
+| constructionTime | string | usually instant per research |
+| maintenance | object | `{ goldPerMin?, workforce[] }` |
+| workforce | array | `[{ tier, count }]` |
+| dimensions | string | base size, size with roads |
+| placementConstraints | array | coast/marsh/forest/fields/etc |
+| roadRequired | boolean | |
+| warehouseRequired | boolean | implies "in range of Warehouse/Trading Post" |
+| aqueductSupport | boolean | can be improved with aqueduct connection |
+| inputGoods | array | links to goods |
+| outputGoods | array | links to goods |
+| cycleTimeSeconds | number | production cycle time |
+| areaEffects | array | `{ type, value, target, radius? }` |
+| productionChain | array | links to chain(s) |
+| unlockCondition | string | tier, research, count, etc |
+| specialists | array | compatible specialists with their effects |
+| usagePatterns | string | short |
+| commonPitfalls | string | short |

docs/schemas/good.md

@@ -0,0 +1,18 @@
+# Schema: Good
+
+**Entity Type:** `Good`
+
+## Fields
+
+| Field | Type | Notes |
+|------|------|------|
+| id | string | stable anchor id |
+| name | string | |
+| category | string | Food / Construction / Intermediate / etc |
+| usedFor | array | Construction, Consumption, Input, Trade |
+| providesAttributes | array | `{ attribute, value, consumer? }` |
+| buyPrice | number | purchase price in Dinare |
+| sellPrice | number | sale price in Dinare |
+| producedBy | array | building links |
+| consumedBy | array | building/tier links |
+| availableFrom | string | tier when good becomes available |

docs/schemas/population-tier.md

@@ -0,0 +1,15 @@
+# Schema: PopulationTier
+
+**Entity Type:** `PopulationTier`
+
+## Fields
+
+| Field | Type | Notes |
+|------|------|------|
+| id | string | stable anchor id |
+| name | string | tier name (e.g., Liberti, Plebeians) |
+| region | string | Latium / Albion |
+| workforceFraction | number | percentage of population providing labor (0.0-1.0) |
+| needsCategories | array | Food, Public Service, Fashion, etc. |
+| notes | string | general guidance |
+| commonPitfalls | string | common mistakes |

docs/schemas/production-chain.md

@@ -0,0 +1,14 @@
+# Schema: ProductionChain
+
+**Entity Type:** `ProductionChain`
+
+## Fields
+
+| Field | Type | Notes |
+|------|------|------|
+| id | string | stable anchor id |
+| name | string | chain name |
+| steps | array | `{ building, in[], out[], cycleSeconds }` |
+| recommendedRatios | array | `{ building, count }` |
+| bottlenecks | array | goods/buildings that commonly limit throughput |
+| notes | string | general guidance |

docs/schemas/ship-hull.md

@@ -0,0 +1,13 @@
+# Schema: ShipHull
+
+**Entity Type:** `ShipHull`
+
+## Fields
+
+| Field | Type | Notes |
+|------|------|------|
+| id | string | stable anchor id |
+| name | string | hull name |
+| sizeClass | string | Small / Medium / Large |
+| moduleSlots | number | number of module slots available |
+| notes | string | characteristics and tradeoffs |

docs/schemas/ship-module.md

@@ -0,0 +1,13 @@
+# Schema: ShipModule
+
+**Entity Type:** `ShipModule`
+
+## Fields
+
+| Field | Type | Notes |
+|------|------|------|
+| id | string | stable anchor id |
+| name | string | module name |
+| effect | string | what the module does |
+| tradeoffs | string | costs or downsides |
+| notes | string | additional information |

docs/schemas/specialist.md

@@ -0,0 +1,19 @@
+# Schema: Specialist
+
+**Entity Type:** `Specialist`
+
+## Fields
+
+| Field | Type | Notes |
+|------|------|------|
+| id | string | stable anchor id |
+| name | string | specialist name |
+| rarity | string | Common / Rare / Epic / Legendary |
+| category | string | Finance / Production / etc. |
+| slotType | string | type of slot required |
+| scope | string | what buildings/areas are affected |
+| effects | array | `{ type, target, value, scope }` |
+| improvesBuildings | array | building links |
+| stackRules | string | how effects stack with others |
+| usagePatterns | string | best practices |
+| commonPitfalls | string | common mistakes |

docs/ships/_index.md

@@ -0,0 +1,36 @@
+# Ships & Naval
+
+Ship construction, modules, and naval mechanics.
+
+## Ship Construction
+
+Ships are built in Shipyards. Construction consumes resources and time.
+- Insufficient workforce slows ship construction
+- Ships cannot be refitted after building
+
+## Hulls
+
+| Hull | Size Class | Module Slots | Notes |
+|------|------------|--------------|-------|
+| [Penteconter](./hulls/penteconter.md) | Small | 2 | Cheaper, faster acceleration |
+| [Trireme](./hulls/trireme.md) | Medium | 3 | Balanced |
+| [Quinquireme](./hulls/quinquireme.md) | Large | 4 | More capacity/HP, slower acceleration |
+
+## Modules
+
+### Movement
+- [Mast](./modules/mast.md) - +long-distance speed (wind)
+- [Rows (Oars)](./modules/rows.md) - +base speed, acceleration, maneuver
+
+### Defense
+- [Reinforced Hull](./modules/reinforced-hull.md) - +health/durability
+
+### Weapons
+- [Archer Tower](./modules/archer-tower.md) - Short-range multi-arrow attack
+- [Scorpio](./modules/scorpio.md) - Side-mounted high-damage spears
+- [Onager](./modules/onager.md) - Forward catapult, long range
+
+## Ship Design Slots
+
+- Save up to 2 custom designs per hull per shipyard (6 total)
+- Ships cannot be refitted after building

docs/ships/hulls/penteconter.md

@@ -0,0 +1,14 @@
+# Penteconter
+
+**Entity Type:** ShipHull
+
+## Properties
+
+| Field | Value |
+|-------|-------|
+| Size Class | Small |
+| Module Slots | 2 |
+
+## Notes
+
+Fewer slots; cheaper; likely faster acceleration.

docs/ships/hulls/quinquireme.md

@@ -0,0 +1,14 @@
+# Quinquireme
+
+**Entity Type:** ShipHull
+
+## Properties
+
+| Field | Value |
+|-------|-------|
+| Size Class | Large |
+| Module Slots | 4 |
+
+## Notes
+
+More capacity and HP; slower acceleration.

docs/ships/hulls/trireme.md

@@ -0,0 +1,14 @@
+# Trireme
+
+**Entity Type:** ShipHull
+
+## Properties
+
+| Field | Value |
+|-------|-------|
+| Size Class | Medium |
+| Module Slots | 3 |
+
+## Notes
+
+Balanced hull suitable for various purposes.

docs/ships/modules/archer-tower.md

@@ -0,0 +1,11 @@
+# Archer Tower
+
+**Entity Type:** ShipModule
+
+## Effect
+
+Short-range multi-arrow attack (all-around)
+
+## Tradeoffs
+
+Requires more soldiers/crew.

docs/ships/modules/mast.md

@@ -0,0 +1,7 @@
+# Mast
+
+**Entity Type:** ShipModule
+
+## Effect
+
++long-distance speed (wind)

docs/ships/modules/onager.md

@@ -0,0 +1,7 @@
+# Onager
+
+**Entity Type:** ShipModule
+
+## Effect
+
+Forward catapult (long range, high damage, low accuracy)

docs/ships/modules/reinforced-hull.md

@@ -0,0 +1,7 @@
+# Reinforced Hull
+
+**Entity Type:** ShipModule
+
+## Effect
+
++health/durability

docs/ships/modules/rows.md

@@ -0,0 +1,11 @@
+# Rows (Oars)
+
+**Entity Type:** ShipModule
+
+## Effect
+
++base speed, acceleration, maneuver
+
+## Tradeoffs
+
+Consumes more crew than sails.

docs/ships/modules/scorpio.md

@@ -0,0 +1,7 @@
+# Scorpio
+
+**Entity Type:** ShipModule
+
+## Effect
+
+Side-mounted high-damage spears (medium range)

docs/specialists/_index.md

@@ -0,0 +1,28 @@
+# Specialists
+
+Specialists are characters that slot into certain buildings and modify stats.
+
+## Overview
+
+- **Sources:** Obtained via quests, events, or trade
+- **Effects:** Can include +productivity, -workforce, -maintenance, area effects
+- **Slot Type:** Buildings have specialist slots that accept specific categories
+
+## Known Specialists
+
+- [Uiscarix, Hygiean Fishmonger](./uiscarix.md) - Epic, Finance category, +1.5 income area effect for fisheries
+
+## Common Effect Types
+
+| Effect Type | Example Value | Description |
+|-------------|---------------|-------------|
+| Productivity | +25% | Increases production output |
+| Workforce | -25% | Reduces worker requirements |
+| Maintenance | -66% | Reduces gold upkeep |
+| Income Area Effect | +1.5 | Bonus income for buildings in radius |
+
+## Usage Tips
+
+- **Placement matters:** Area effects only apply to buildings within radius
+- **Stack rules:** Some specialists may have stacking limitations
+- **Building match:** Ensure specialist is compatible with target building

docs/specialists/uiscarix.md

@@ -0,0 +1,39 @@
+# Uiscarix, Hygiean Fishmonger
+
+**Entity Type:** Specialist
+
+## Properties
+
+| Field | Value |
+|-------|-------|
+| Rarity | Epic |
+| Category | Finance |
+| Slot Type | Specialist |
+| Scope | Fisheries in range |
+
+## Effects
+
+| Effect Type | Target | Value | Scope |
+|------------|--------|-------|-------|
+| Income Area Effect | Fisheries | +1.5 | Radius-based |
+
+## Improves Buildings
+
+- [Eel Grabber](../buildings/eel-grabber-albion.md)
+- Oyster Bed *(placeholder)*
+- [Cockle Picker](../buildings/cockle-picker-albion.md)
+- Scomber's Shack *(placeholder)*
+- [Fishing Hut](../buildings/fishing-hut-latium.md)
+- Sturgeon Hatchery *(placeholder)*
+
+## Stack Rules
+
+Unknown (not present in supplied files)
+
+## Usage Patterns
+
+Slot into a coastal hub building covering many fisheries.
+
+## Common Pitfalls
+
+Misplaced radius leads to zero value; does not fix overproduction warnings.

docs/systems/_index.md

@@ -0,0 +1,30 @@
+# Game Systems
+
+Core mechanics that govern how the game economy and logistics work.
+
+## Trade & Logistics
+- [Trade Routes](./trade-routes.md) - Automated ship loops between islands
+- [Diplomatic Trade](./diplomatic-trade.md) - Passive buy/sell with AI via treaties
+
+## Economy
+- [Maintenance Model](./maintenance.md) - Building upkeep and workforce costs
+- [Area Effects](./area-effects.md) - Proximity bonuses and penalties
+- [Statistics Screen](./statistics-screen.md) - Production vs consumption diagnostics
+
+## Infrastructure
+- [Shipyard](./shipyard.md) - Ship construction system
+- [Warehouse Cloud](./warehouse-cloud.md) - Shared island storage
+
+## Key Concepts
+
+### Maintenance
+Nearly every building has ongoing gold + workforce maintenance:
+- Fishing Hut: -6 gold/min, 4 Tier I workers
+- Bakery: -14 gold/min, 3 Tier II workers
+- Deleting buildings stops upkeep and frees workforce
+
+### Area Effects
+Buildings can give positive/negative proximity modifiers:
+- Shown by green/red arrows on placement
+- Spinner gives income boost near buildings
+- Polluters (e.g., Charcoal Burner) decrease happiness/health

docs/systems/area-effects.md

@@ -0,0 +1,15 @@
+# Area Effects
+
+**Entity Type:** SystemEntity
+
+## Rules
+
+- Buildings can give positive/negative proximity modifiers
+- Shown by green/red arrows on placement
+
+## Examples
+
+| Building | Effect |
+|----------|--------|
+| Spinner | Income boost near buildings |
+| Charcoal Burner | Decreases happiness/health (polluter) |

docs/systems/diplomatic-trade.md

@@ -0,0 +1,16 @@
+# Diplomatic Trade
+
+**Entity Type:** SystemEntity
+
+## Description
+
+Passive buy/sell orders at Trading Post with AI via treaties.
+
+## Configuration
+
+Set fixed buy/sell orders, price, quantity.
+
+## Usage Patterns
+
+- Monetize surplus production
+- Import hard-to-get goods

docs/systems/maintenance.md

@@ -0,0 +1,15 @@
+# Maintenance Model
+
+**Entity Type:** SystemEntity
+
+## Rules
+
+- Nearly every building has ongoing gold + workforce maintenance
+- Deleting buildings stops upkeep and frees workforce
+
+## Examples
+
+| Building | Gold/min | Workforce |
+|----------|----------|-----------|
+| Fishing Hut | -6 | 4 Tier I |
+| Bakery | -14 | 3 Tier II |

docs/systems/shipyard.md

@@ -0,0 +1,13 @@
+# Shipyard
+
+**Entity Type:** SystemEntity
+
+## Description
+
+Ships are constructed in a Shipyard; construction consumes resources and time.
+
+## Rules
+
+- Insufficient workforce slows ship construction
+- Save up to 2 custom designs per hull per shipyard (6 total)
+- Ships cannot be refitted after building

docs/systems/statistics-screen.md

@@ -0,0 +1,16 @@
+# Statistics Screen
+
+**Entity Type:** SystemEntity
+
+## Description
+
+Use statistics to compare production vs consumption; overproduction flagged.
+
+## Diagnostic
+
+- **Green bar high:** Overproduction - export/demolish/disable
+- **White bar high:** Shortage - add buildings or fix logistics
+
+## Examples
+
+"Too much Sheep" warning indicates overproduction.

docs/systems/trade-routes.md

@@ -0,0 +1,27 @@
+# Trade Routes
+
+**Entity Type:** SystemEntity
+
+## Description
+
+Automated ship loop moving goods between islands.
+
+## Configuration
+
+1. Select ship
+2. Enable Trade Route
+3. Assign goods per cargo slot
+4. Assign islands for load/unload
+
+## Rules
+
+- Route loops indefinitely
+- Used to supply production chains across islands
+
+## Usage Patterns
+
+Specialize islands (agricultural vs industrial) and route goods accordingly.
+
+## Common Pitfalls
+
+Under-shipping (not enough cargo throughput) leads to need flicker and income oscillation.

docs/systems/warehouse-cloud.md

@@ -0,0 +1,9 @@
+# Warehouse Cloud
+
+**Entity Type:** SystemEntity
+
+## Description
+
+Shared island storage accessible via connected warehouses/trading post.
+
+All buildings within range of a warehouse share access to the island's stored goods.

docs/troubleshooting/_index.md

@@ -0,0 +1,23 @@
+# Troubleshooting
+
+Common gameplay issues and their solutions.
+
+## Playbooks
+
+- [Income Bouncing](./income-bouncing.md) - "My income is bouncing up and down"
+- [Too Much Sheep](./too-much-sheep.md) - "Game says I have too much Sheep"
+- [Houses Not Upgrading](./houses-not-upgrading.md) - "Why are my houses not upgrading?"
+
+## Quick Diagnostics
+
+### Income Problems
+1. Check upkeep spikes (new high-upkeep buildings)
+2. Check need flicker (food/clothing stocks hitting zero)
+3. Check workforce (red hammer = missing workers)
+4. Open Statistics Screen for production vs consumption
+
+### Production Issues
+1. Verify raw material supply
+2. Check transport distances
+3. Ensure warehouse coverage
+4. Match building ratios to chain requirements

docs/troubleshooting/houses-not-upgrading.md

@@ -0,0 +1,9 @@
+# Playbook: "Why are my houses not upgrading?"
+
+## Diagnostic Steps
+
+1. Ensure at least one need per category is met.
+
+2. Ensure service buildings' area coverage includes houses (roads/range).
+
+3. Ensure storage has the goods (not just "producing", but delivered).

docs/troubleshooting/income-bouncing.md

@@ -0,0 +1,17 @@
+# Playbook: "My income is bouncing up and down"
+
+## Diagnostic Steps
+
+1. **Check upkeep spikes:** Did you place a high-upkeep building (e.g., Bakery)?
+
+2. **Check need flicker:** Are food/clothing stocks dipping to zero intermittently? (storage/transport issue)
+
+3. **Check workforce:** Look for red hammer / missing tier workers after upgrades.
+
+4. **Open Statistics Screen:** Verify production vs consumption bars.
+
+## Fix Priority
+
+1. Tier I Food
+2. Tier I Fashion
+3. Tier II staple chains

docs/troubleshooting/too-much-sheep.md

@@ -0,0 +1,11 @@
+# Playbook: "Game says I have too much Sheep"
+
+## Diagnostic Steps
+
+1. Confirm overproduction in Statistics Screen.
+
+2. Add/scale downstream processor (Felter) if present in your build.
+
+3. Export surplus via trade routes or diplomatic orders.
+
+4. Demolish/disable extra farms to stop upkeep drain.