adding data

2025-12-30 14:34:34 +01:00
parent 5f1b2d0474
commit 30a2a13d20
8 changed files with 1454 additions and 0 deletions
--- a/docs.md
+++ b/docs.md
@@ -0,0 +1,713 @@
+# Anno 117: Pax Romana — Sandbox Mode Data Reference (API-Style)
+
+> **Version:** 0.2 (compiled from provided research files; not yet a full extracted DB)  
+> **Focus:** Sandbox / Endless Mode mechanics (no controls/UI bindings)  
+> **Data Sources:** research_1.txt  [oai_citation:0‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64), research_2.txt  [oai_citation:1‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973), research_3.txt  [oai_citation:2‡research_3.txt](sediment://file_00000000e73871f6bf8844e9c7de47e3)  
+>
+> **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).
+
+---
+
+## Table of Contents
+
+- [Schemas](#schemas)
+  - [Schema: Building](#schema-building)
+  - [Schema: Good](#schema-good)
+  - [Schema: PopulationTier](#schema-populationtier)
+  - [Schema: ProductionChain](#schema-productionchain)
+  - [Schema: Specialist](#schema-specialist)
+  - [Schema: ShipHull](#schema-shiphull)
+  - [Schema: ShipModule](#schema-shipmodule)
+- [Entities](#entities)
+  - [Population Tiers](#population-tiers)
+  - [Goods](#goods)
+  - [Buildings](#buildings)
+  - [Production Chains](#production-chains)
+  - [Trade & Logistics](#trade--logistics)
+  - [Ships & Naval](#ships--naval)
+  - [Specialists](#specialists)
+  - [Economy & Diagnostics](#economy--diagnostics)
+  - [Monuments](#monuments)
+- [Troubleshooting Playbooks](#troubleshooting-playbooks)
+- [Glossary](#glossary)
+
+---
+
+## Schemas
+
+### Schema: Building
+
+**Entity Type:** `Building`
+
+| 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 |
+| requiredPopulationTier | string | link to tier |
+| buildCost | object | `{ gold?, goods[] }` |
+| constructionTime | string | usually instant per research |
+| maintenance | object | `{ goldPerMin?, workforce[] }` |
+| workforce | array | `[{ tier, count }]` |
+| placementConstraints | array | coast/marsh/forest/fields/etc |
+| roadRequired | boolean | |
+| warehouseRequired | boolean | implies “in range of Warehouse/Trading Post” |
+| 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 |
+| usagePatterns | string | short |
+| commonPitfalls | string | short |
+
+---
+
+### Schema: Good
+
+**Entity Type:** `Good`
+
+| 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? }` |
+| producedBy | array | building links |
+| consumedBy | array | building/tier links |
+
+---
+
+### Schema: PopulationTier
+
+**Entity Type:** `PopulationTier`
+
+| Field | Type |
+|------|------|
+| id | string |
+| name | string |
+| region | string |
+| workforceFraction | number |
+| needsCategories | array |
+| notes | string |
+| commonPitfalls | string |
+
+---
+
+### Schema: ProductionChain
+
+**Entity Type:** `ProductionChain`
+
+| Field | Type |
+|------|------|
+| id | string |
+| name | string |
+| steps | array | `{ building, in[], out[], cycleSeconds }` |
+| recommendedRatios | array | `{ building, count }` |
+| bottlenecks | array | goods/buildings |
+| notes | string |
+
+---
+
+### Schema: Specialist
+
+**Entity Type:** `Specialist`
+
+| Field | Type |
+|------|------|
+| id | string |
+| name | string |
+| rarity | string |
+| category | string |
+| slotType | string |
+| scope | string |
+| effects | array | `{ type, target, value, scope }` |
+| improvesBuildings | array | building links |
+| stackRules | string |
+| usagePatterns | string |
+| commonPitfalls | string |
+
+---
+
+### Schema: ShipHull
+
+**Entity Type:** `ShipHull`
+
+| Field | Type |
+|------|------|
+| id | string |
+| name | string |
+| sizeClass | string |
+| moduleSlots | number |
+| notes | string |
+
+---
+
+### Schema: ShipModule
+
+**Entity Type:** `ShipModule`
+
+| Field | Type |
+|------|------|
+| id | string |
+| name | string |
+| effect | string |
+| tradeoffs | string |
+| notes | string |
+
+---
+
+## Entities
+
+## Population Tiers
+
+### Tier I — Liberti (Latium) / Waders (Albion) {#tier-i}
+
+- **Entity Type:** PopulationTier
+- **workforceFraction:** `0.50`  [oai_citation:3‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **needsCategories:** Food, Public Service, Fashion  [oai_citation:4‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **notes:** Avoid upgrading all Tier I housing at once; you can lose Tier I workers needed for basic chains.  [oai_citation:5‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **commonPitfalls:** “Everything upgraded” ⇒ fisheries/farms/sawmills understaffed.
+
+### Tier II — Plebeians (Latium) / Mercators or Smiths (Albion) {#tier-ii}
+
+- **Entity Type:** PopulationTier
+- **workforceFraction:** `0.30`  [oai_citation:6‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **notes:** Tier II introduces major upkeep spikes (mills/bakeries/bricks, etc.).  [oai_citation:7‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **commonPitfalls:** Overbuilding production buildings drains gold via maintenance.  [oai_citation:8‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+
+### Tier III — Equites (Latium) / Higher Albion tiers {#tier-iii}
+
+- **Entity Type:** PopulationTier
+- **workforceFraction:** `0.20`  [oai_citation:9‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **notes:** Higher complexity; shortages cascade across chains.  [oai_citation:10‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+
+### Tier IV — Patricians (Latium) {#tier-iv}
+
+- **Entity Type:** PopulationTier
+- **workforceFraction:** `0.00` (reported “no workforce”)  [oai_citation:11‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **notes:** Very high needs; unlock monuments like Amphitheatre.  [oai_citation:12‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+
+---
+
+## Goods
+
+### Sardines {#good-sardines}
+
+- **Entity Type:** Good
+- **category:** Food
+- **usedFor:** Consumption (Tier I Food need)
+- **providesAttributes:** +1 Population, +1 Income (per house when fulfilling Food need)  [oai_citation:13‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **producedBy:** [Fishing Hut](#building-fishing-hut)
+- **consumedBy:** [Tier I](#tier-i)
+
+### Porridge {#good-porridge}
+
+- **Entity Type:** Good
+- **category:** Food
+- **usedFor:** Consumption (Tier I Food need)
+- **providesAttributes:** +2 Population (per house when fulfilling Food need)  [oai_citation:14‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **producedBy:** [Porridge Stand](#building-porridge-stand)
+- **consumedBy:** [Tier I](#tier-i)
+
+### Oats {#good-oats}
+
+- **Entity Type:** Good
+- **category:** Agricultural
+- **usedFor:** Input (Porridge)
+- **producedBy:** [Oat Farm](#building-oat-farm)
+- **consumedBy:** [Porridge Stand](#building-porridge-stand)
+
+### Hemp {#good-hemp}
+
+- **Entity Type:** Good
+- **category:** Agricultural
+- **usedFor:** Input (Tunics)
+- **producedBy:** [Hemp Farm](#building-hemp-farm)
+- **consumedBy:** [Spinner](#building-spinner)
+
+### Tunics {#good-tunics}
+
+- **Entity Type:** Good
+- **category:** Clothing / Fashion
+- **usedFor:** Consumption (Tier I Fashion need)
+- **providesAttributes:** +2 Population (reported)  [oai_citation:15‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **producedBy:** [Spinner](#building-spinner)
+- **consumedBy:** [Tier I](#tier-i)
+
+### Timber (Planks) {#good-timber}
+
+- **Entity Type:** Good
+- **category:** Construction Material
+- **usedFor:** Construction, Inputs
+- **producedBy:** [Sawmill](#building-sawmill)
+- **consumedBy:** Many (construction costs reference Timber widely)  [oai_citation:16‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+
+---
+
+## Buildings
+
+### Woodcutter Hut {#building-woodcutter-hut}
+
+- **Entity Type:** Building
+- **category:** Production / Raw Materials
+- **description:** Produces Logs from forest density.
+- **requiredPopulationTier:** [Tier I](#tier-i)
+- **buildCost:** `{ goods: [{ good: "Timber", amount: 2 }] }`  [oai_citation:17‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **constructionTime:** Instant (reported general rule)  [oai_citation:18‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **maintenance:** `{ goldPerMin: -5, workforce: [{ tier: "Tier I", count: 2 }] }` (approx.)  [oai_citation:19‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **workforce:** `[{ tier: Tier I, count: 2 }]`  [oai_citation:20‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **placementConstraints:** Forest overlap required; low density reduces productivity.  [oai_citation:21‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **roadRequired:** true  [oai_citation:22‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **warehouseRequired:** true  [oai_citation:23‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **inputGoods:** none
+- **outputGoods:** `Unknown (Logs)` (named in text; Good entry not separately defined)
+- **cycleTimeSeconds:** 30  [oai_citation:24‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **productionChain:** [Chain: Timber](#chain-timber)
+- **unlockCondition:** Tier I  [oai_citation:25‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **usagePatterns:** Place deep in dense forest, keep a warehouse in range.
+- **commonPitfalls:** Sparse forest ⇒ “mystery” timber shortages downstream.
+
+---
+
+### Sawmill {#building-sawmill}
+
+- **Entity Type:** Building
+- **category:** Production / Construction Materials
+- **description:** Converts Logs → Timber planks.
+- **requiredPopulationTier:** [Tier I](#tier-i)
+- **buildCost:** `{ goods: [{ good: "Timber", amount: 2 }] }`  [oai_citation:26‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **constructionTime:** Instant  [oai_citation:27‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **maintenance:** `{ goldPerMin: -5, workforce: [{ tier: "Tier I", count: 2 }] }` (approx.)  [oai_citation:28‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **workforce:** `[{ tier: Tier I, count: 2 }]`  [oai_citation:29‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **placementConstraints:** None special (but requires logistics)
+- **roadRequired:** true  [oai_citation:30‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **warehouseRequired:** true  [oai_citation:31‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **inputGoods:** `Unknown (Logs)`
+- **outputGoods:** [Timber](#good-timber)
+- **cycleTimeSeconds:** 30  [oai_citation:32‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **productionChain:** [Chain: Timber](#chain-timber)
+- **unlockCondition:** Tier I
+- **usagePatterns:** Pair 1:1 with Woodcutters (matching cycle times).
+- **commonPitfalls:** Too many sawmills ⇒ upkeep drain without benefit.
+
+---
+
+### Fishing Hut (Latium) {#building-fishing-hut}
+
+- **Entity Type:** Building
+- **category:** Production / Food (Fishery)
+- **description:** Coastal fishery producing Sardines.
+- **requiredPopulationTier:** [Tier I](#tier-i)
+- **buildCost:** `{ goods: [{ good: "Timber", amount: 2 }] }`  [oai_citation:33‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **constructionTime:** Instant  [oai_citation:34‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **maintenance:** `{ goldPerMin: -6, workforce: [{ tier: "Tier I", count: 4 }] }`  [oai_citation:35‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **workforce:** `[{ tier: Tier I, count: 4 }]`  [oai_citation:36‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **placementConstraints:** Coast / Harbor Area required.  [oai_citation:37‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **roadRequired:** true  [oai_citation:38‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **warehouseRequired:** true  [oai_citation:39‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **inputGoods:** none
+- **outputGoods:** [Sardines](#good-sardines)
+- **cycleTimeSeconds:** 60  [oai_citation:40‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **productionChain:** [Chain: Tier I Food](#chain-tier-i-food)
+- **unlockCondition:** Tier I  [oai_citation:41‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **usagePatterns:** Cluster fisheries for specialist + area-effect stacking.
+- **commonPitfalls:** Overbuilt fisheries ⇒ gold bleed; also “need flicker” if storage/transport dips.
+
+---
+
+### Cockle Picker (Albion) {#building-cockle-picker}
+
+- **Entity Type:** Building
+- **category:** Production / Food (Fishery analogue)
+- **description:** Coastal gatherer producing Cockles for Waders.
+- **requiredPopulationTier:** [Tier I](#tier-i)
+- **buildCost:** `Unknown` (research says “similar to Fishing Hut”, but not hard numbers)  [oai_citation:42‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **maintenance:** `Unknown`
+- **workforce:** `Unknown`
+- **placementConstraints:** Coast (Albion)  [oai_citation:43‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **cycleTimeSeconds:** `Unknown (reported ~60s but not asserted)`
+- **usagePatterns:** Albion starter food option.
+- **commonPitfalls:** Confusing coast vs marsh producers in Albion.  [oai_citation:44‡research_3.txt](sediment://file_00000000e73871f6bf8844e9c7de47e3)
+
+---
+
+### Eel Grabber (Albion) {#building-eel-grabber}
+
+- **Entity Type:** Building
+- **category:** Production / Food (Marsh fishery)
+- **description:** Marshland fish producer (Eels).
+- **requiredPopulationTier:** [Tier I](#tier-i)
+- **buildCost:** Unknown
+- **maintenance:** Unknown
+- **workforce:** Unknown
+- **placementConstraints:** Marshland placement required (Albion-specific).  [oai_citation:45‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **cycleTimeSeconds:** `Unknown (likely 60s per research wording; not asserted as fact)`  [oai_citation:46‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **usagePatterns:** Place in marsh; pair with coastal cockles early.
+- **commonPitfalls:** Trying to place on coast; marsh-only building.  [oai_citation:47‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+
+---
+
+### Oat Farm {#building-oat-farm}
+
+- **Entity Type:** Building
+- **category:** Production / Agriculture
+- **description:** Produces Oats; uses field modules; aqueduct optional.
+- **requiredPopulationTier:** [Tier I](#tier-i)
+- **buildCost:** `{ goods: [{ good: "Timber", amount: 3 }] }`  [oai_citation:48‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **constructionTime:** Instant  [oai_citation:49‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **maintenance:** `{ goldPerMin: -4, workforce: [{ tier: "Tier I", count: 3 }] }`  [oai_citation:50‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **workforce:** `[{ tier: Tier I, count: 3 }]`  [oai_citation:51‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **placementConstraints:** Requires fields; requires relevant fertility (oat/grain).  [oai_citation:52‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **roadRequired:** true  [oai_citation:53‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **warehouseRequired:** true  [oai_citation:54‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **inputGoods:** none
+- **outputGoods:** [Oats](#good-oats)
+- **cycleTimeSeconds:** 60  [oai_citation:55‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **productionChain:** [Chain: Porridge](#chain-porridge)
+- **unlockCondition:** Tier I
+- **usagePatterns:** Keep fields compact; warehouse nearby; consider aqueduct support.
+- **commonPitfalls:** Insufficient fields/fertility ⇒ low output; long travel distance ⇒ apparent underproduction.
+
+---
+
+### Porridge Stand {#building-porridge-stand}
+
+- **Entity Type:** Building
+- **category:** Production / Food
+- **description:** Converts Oats → Porridge.
+- **requiredPopulationTier:** [Tier I](#tier-i)
+- **buildCost:** `{ goods: [{ good: "Timber", amount: 2 }] }`  [oai_citation:56‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **constructionTime:** Instant  [oai_citation:57‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **maintenance:** `{ goldPerMin: -8, workforce: [{ tier: "Tier I", count: 2 }] }`  [oai_citation:58‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **workforce:** `[{ tier: Tier I, count: 2 }]`  [oai_citation:59‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **placementConstraints:** Needs road/warehouse.
+- **roadRequired:** true  [oai_citation:60‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **warehouseRequired:** true  [oai_citation:61‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **inputGoods:** [Oats](#good-oats)
+- **outputGoods:** [Porridge](#good-porridge)
+- **cycleTimeSeconds:** 60  [oai_citation:62‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **productionChain:** [Chain: Porridge](#chain-porridge)
+- **unlockCondition:** Tier I
+- **usagePatterns:** Pair 1:1 with Oat Farms for balanced flow (both 60s).
+- **commonPitfalls:** Oats delivered too slowly ⇒ porridge “flicker” and population drops.
+
+---
+
+### Hemp Farm {#building-hemp-farm}
+
+- **Entity Type:** Building
+- **category:** Production / Agriculture
+- **description:** Produces Hemp for Tunics; uses fields; aqueduct optional.
+- **requiredPopulationTier:** [Tier I](#tier-i)
+- **buildCost:** `{ goods: [{ good: "Timber", amount: 2 }] }`  [oai_citation:63‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **maintenance:** `{ goldPerMin: -4, workforce: [{ tier: "Tier I", count: 3 }] }`  [oai_citation:64‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **placementConstraints:** Fields + correct fertility.  [oai_citation:65‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **roadRequired:** true  [oai_citation:66‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **warehouseRequired:** true  [oai_citation:67‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **outputGoods:** [Hemp](#good-hemp)
+- **cycleTimeSeconds:** 60  [oai_citation:68‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **productionChain:** [Chain: Tunics](#chain-tunics)
+- **usagePatterns:** Keep close to Spinner; reduce hauling delays.
+- **commonPitfalls:** Too few fields or long hauling times ⇒ spinner starvation.
+
+---
+
+### Spinner {#building-spinner}
+
+- **Entity Type:** Building
+- **category:** Production / Clothing
+- **description:** Converts Hemp → Tunics; provides local income area effect.
+- **requiredPopulationTier:** [Tier I](#tier-i)
+- **buildCost:** `{ goods: [{ good: "Timber", amount: 2 }] }`  [oai_citation:69‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **maintenance:** `{ goldPerMin: -8, workforce: [{ tier: "Tier I", count: 3 }] }`  [oai_citation:70‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **inputGoods:** [Hemp](#good-hemp)
+- **outputGoods:** [Tunics](#good-tunics)
+- **cycleTimeSeconds:** 30  [oai_citation:71‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **areaEffects:** `[{ type: "IncomeAreaEffect", value: +1, target: "Nearby buildings (incl residences)", radius: "Unknown" }]`  [oai_citation:72‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **productionChain:** [Chain: Tunics](#chain-tunics)
+- **usagePatterns:** Place near residences to maximize income area effect.
+- **commonPitfalls:** Spinner output can be fine while income effect is wasted if placed far from housing.
+
+---
+
+### Bakery {#building-bakery}
+
+- **Entity Type:** Building
+- **category:** Production / Food (Tier II)
+- **description:** Produces Bread (Tier II staple); high upkeep.
+- **requiredPopulationTier:** [Tier II](#tier-ii)
+- **buildCost:** `Unknown in supplied snippets` (but bakery upkeep is explicitly given)  [oai_citation:73‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **maintenance:** `{ goldPerMin: -14, workforce: [{ tier: "Tier II", count: 3 }] }`  [oai_citation:74‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **inputGoods:** `Unknown (Flour + Charcoal implied by chain text)`  [oai_citation:75‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **outputGoods:** `Unknown (Bread)`  [oai_citation:76‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **cycleTimeSeconds:** 60 (from bread chain summary)  [oai_citation:77‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **usagePatterns:** Only scale to actual consumption; bakeries are a common cashflow killer.
+- **commonPitfalls:** Overbuilding bakeries ⇒ negative income swings; missing charcoal ⇒ “mystery” bread shortages.  [oai_citation:78‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+
+---
+
+## Production Chains
+
+### Chain: Timber {#chain-timber}
+
+- **Entity Type:** ProductionChain
+- **steps:**
+  - `{ building: [Woodcutter Hut](#building-woodcutter-hut), in: [], out: ["Logs"], cycleSeconds: 30 }`  [oai_citation:79‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+  - `{ building: [Sawmill](#building-sawmill), in: ["Logs"], out: [Timber](#good-timber), cycleSeconds: 30 }`  [oai_citation:80‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **recommendedRatios:** Woodcutter 1 : Sawmill 1 (matching 30s cycles)  [oai_citation:81‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **bottlenecks:** Forest density (Woodcutter placement)  [oai_citation:82‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+
+### Chain: Tier I Food {#chain-tier-i-food}
+
+- **Entity Type:** ProductionChain
+- **steps:**
+  - `{ building: [Fishing Hut](#building-fishing-hut), in: [], out: [Sardines](#good-sardines), cycleSeconds: 60 }`  [oai_citation:83‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+  - `{ building: [Oat Farm](#building-oat-farm), in: [], out: [Oats](#good-oats), cycleSeconds: 60 }`  [oai_citation:84‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+  - `{ building: [Porridge Stand](#building-porridge-stand), in: [Oats](#good-oats), out: [Porridge](#good-porridge), cycleSeconds: 60 }`  [oai_citation:85‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **notes:** Many Tier I settlements produce both Sardines and Porridge to maximize population.  [oai_citation:86‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+
+### Chain: Porridge {#chain-porridge}
+
+- **Entity Type:** ProductionChain
+- **steps:**
+  - Oat Farm (60s) → Oats  [oai_citation:87‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+  - Porridge Stand (60s) + Oats → Porridge  [oai_citation:88‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **recommendedRatios:** Oat Farm 1 : Porridge Stand 1 (both 60s)
+- **bottlenecks:** Field layout, fertility, hauling distance.  [oai_citation:89‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+
+### Chain: Tunics {#chain-tunics}
+
+- **Entity Type:** ProductionChain
+- **steps:**
+  - Hemp Farm (60s) → Hemp  [oai_citation:90‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+  - Spinner (30s) + Hemp → Tunics  [oai_citation:91‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **recommendedRatios:** `Unknown` (cycle mismatch suggests multiple spinners can consume one farm; exact throughput not given in files)
+- **notes:** Spinner provides an income area effect (+1) near buildings.  [oai_citation:92‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+
+### Chain: Bread (summary) {#chain-bread}
+
+- **Entity Type:** ProductionChain
+- **steps (summary only):**
+  - Wheat Farm (60s) → Grain
+  - Grain Mill (30s) → Flour
+  - Bakery (60s) + (requires Charcoal) → Bread  [oai_citation:93‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **recommendedRatios:** 2 Wheat : 1 Mill : 2 Bakeries  [oai_citation:94‡research_3.txt](sediment://file_00000000e73871f6bf8844e9c7de47e3)
+- **bottlenecks:** Charcoal availability; bakery upkeep.  [oai_citation:95‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)  [oai_citation:96‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+
+---
+
+## Trade & Logistics
+
+### Entity: TradeRoute {#entity-traderoute}
+
+- **Entity Type:** SystemEntity
+- **description:** Automated ship loop moving goods between islands.
+- **configuration:**
+  - Select ship
+  - Enable Trade Route
+  - Assign goods per cargo slot
+  - Assign islands for load/unload
+- **rules:**
+  - Route loops indefinitely
+  - Used to supply production chains across islands
+- **usagePatterns:** Specialize islands (agricultural vs industrial) and route goods accordingly.  [oai_citation:97‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **commonPitfalls:** Under-shipping (not enough cargo throughput) ⇒ need flicker and income oscillation.
+
+### Entity: DiplomaticTrade {#entity-diplomatictrade}
+
+- **Entity Type:** SystemEntity
+- **description:** Passive buy/sell orders at Trading Post with AI via treaties.
+- **configuration:** Set fixed buy/sell orders, price, quantity.  [oai_citation:98‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)
+- **usagePatterns:** Monetize surplus production; import hard-to-get goods.  [oai_citation:99‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)
+
+---
+
+## Ships & Naval
+
+### Shipyard (system) {#system-shipyard}
+
+- **Entity Type:** SystemEntity
+- **description:** Ships are constructed in a Shipyard; construction consumes resources and time.
+- **rule:** Insufficient workforce slows ship construction.  [oai_citation:100‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)
+
+### Hulls {#naval-hulls}
+
+#### Penteconter {#hull-penteconter}
+- **Entity Type:** ShipHull
+- **sizeClass:** Small
+- **moduleSlots:** 2  [oai_citation:101‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)
+- **notes:** Fewer slots; cheaper; likely faster acceleration.
+
+#### Trireme {#hull-trireme}
+- **Entity Type:** ShipHull
+- **sizeClass:** Medium
+- **moduleSlots:** 3  [oai_citation:102‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)
+
+#### Quinquireme {#hull-quinquireme}
+- **Entity Type:** ShipHull
+- **sizeClass:** Large
+- **moduleSlots:** 4  [oai_citation:103‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)
+- **notes:** More capacity and HP; slower acceleration.  [oai_citation:104‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)
+
+### Modules {#naval-modules}
+
+#### Mast {#module-mast}
+- **Entity Type:** ShipModule
+- **effect:** +long-distance speed (wind)  [oai_citation:105‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)
+
+#### Rows (Oars) {#module-rows}
+- **Entity Type:** ShipModule
+- **effect:** +base speed, acceleration, maneuver  [oai_citation:106‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)
+- **tradeoffs:** Consumes more crew than sails.  [oai_citation:107‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)
+
+#### Reinforced Hull {#module-reinforced-hull}
+- **Entity Type:** ShipModule
+- **effect:** +health/durability  [oai_citation:108‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)
+
+#### Archer Tower {#module-archer-tower}
+- **Entity Type:** ShipModule
+- **effect:** short-range multi-arrow attack (all-around)  [oai_citation:109‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)
+- **tradeoffs:** Requires more soldiers/crew.  [oai_citation:110‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)
+
+#### Scorpio {#module-scorpio}
+- **Entity Type:** ShipModule
+- **effect:** side-mounted high-damage spears (medium range)  [oai_citation:111‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)
+
+#### Onager {#module-onager}
+- **Entity Type:** ShipModule
+- **effect:** forward catapult (long range, high damage, low accuracy)  [oai_citation:112‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)
+
+### Ship Design Slots {#naval-design-slots}
+
+- **rule:** Save up to 2 custom designs per hull per shipyard (6 total).  [oai_citation:113‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)
+- **rule:** Ships cannot be refitted after building (per research text).  [oai_citation:114‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)
+
+---
+
+## Specialists
+
+### Specialist System (general) {#system-specialists}
+
+- **Entity Type:** SystemEntity
+- **description:** Specialists slot into certain buildings and modify stats (productivity, workforce, upkeep, etc.).
+- **known effect examples:** +25% productivity, −25% workforce needed (examples referenced)  [oai_citation:115‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **sources:** Obtained via quests, events, or trade.  [oai_citation:116‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+
+### Uiscarix, Hygiean Fishmonger {#specialist-uiscarix-hygiean-fishmonger}
+
+- **Entity Type:** Specialist
+- **rarity:** Epic (from user screenshot)
+- **category:** Finance (from user screenshot)
+- **slotType:** Specialist (from user screenshot)
+- **scope:** Fisheries in range (from user screenshot)
+- **effects:**
+
+| Effect Type | Target | Value | Scope |
+|------------|--------|-------|-------|
+| Income Area Effect | Fisheries | +1.5 | Radius-based |
+
+- **improvesBuildings:**
+  - [Eel Grabber](#building-eel-grabber)
+  - [Oyster Bed](#building-oyster-bed) *(not defined in supplied files; placeholder)*
+  - [Cockle Picker](#building-cockle-picker)
+  - [Scomber's Shack](#building-scombers-shack) *(placeholder)*
+  - [Fishing Hut](#building-fishing-hut)
+  - [Sturgeon Hatchery](#building-sturgeon-hatchery) *(placeholder)*
+
+- **stackRules:** Unknown (not present in supplied files)
+- **usagePatterns:** Slot into a coastal hub building covering many fisheries.
+- **commonPitfalls:** Misplaced radius ⇒ zero value; does not fix overproduction warnings.
+
+---
+
+## Economy & Diagnostics
+
+### Maintenance Model {#system-maintenance}
+
+- **rule:** Nearly every building has ongoing gold + workforce maintenance.  [oai_citation:117‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **example:** Fishing Hut costs −6 gold/min and uses 4 Tier I workers.  [oai_citation:118‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **example:** Bakery costs −14 gold/min and uses 3 Tier II workers.  [oai_citation:119‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **rule:** Deleting buildings stops upkeep and frees workforce.  [oai_citation:120‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+
+### Area Effects {#system-area-effects}
+
+- **rule:** Buildings can give positive/negative proximity modifiers (shown by green/red arrows on placement).  [oai_citation:121‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **example:** Spinner gives income boost near buildings.  [oai_citation:122‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **example:** Polluters (e.g., Charcoal Burner) decrease happiness/health (mentioned).  [oai_citation:123‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+
+### Statistics Screen {#system-statistics-screen}
+
+- **rule:** Use statistics to compare production vs consumption; overproduction flagged (e.g., “too much Sheep”).  [oai_citation:124‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)
+- **diagnostic:**  
+  - Green bar high ⇒ overproduction ⇒ export/demolish/disable  
+  - White bar high ⇒ shortage ⇒ add buildings or fix logistics  [oai_citation:125‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)
+
+---
+
+## Monuments
+
+### Amphitheatre {#monument-amphitheatre}
+
+- **Entity Type:** Building (Monument)
+- **unique:** One per island (reported)  [oai_citation:126‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **unlockCondition:** Patricians exist (Tier IV)  [oai_citation:127‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **construction:** 4 stages; large time + resources; later stages require expensive materials (marble/glass/iron mentioned)  [oai_citation:128‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **effects (complete):** +3 Population, +3 Happiness, +7 Prestige (large radius)  [oai_citation:129‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **events:** Hosts events (local games / grand games / naumachia) consuming goods/workforce for city buffs.  [oai_citation:130‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+- **commonPitfalls:** Starting monument too early can bankrupt you (maintenance + diverted materials).
+
+---
+
+## Troubleshooting Playbooks
+
+### Playbook: “My income is bouncing up and down” {#playbook-income-bouncing}
+
+1. **Check upkeep spikes:** did you place a high-upkeep building (e.g., Bakery)?  [oai_citation:131‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)  
+2. **Check need flicker:** are food/clothing stocks dipping to zero intermittently? (storage/transport)  [oai_citation:132‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)  
+3. **Check workforce:** red hammer / missing tier workers after upgrades.  [oai_citation:133‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)  
+4. **Open Statistics Screen:** verify production vs consumption bars.  [oai_citation:134‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)  
+5. **Fix by priority:** Tier I Food → Tier I Fashion → Tier II staple chains.
+
+### Playbook: “Game says I have too much Sheep” {#playbook-too-much-sheep}
+
+1. Confirm overproduction in Statistics Screen.  [oai_citation:135‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)  
+2. Add/scale downstream processor (Felter) if present in your build.  
+3. Export surplus via trade routes or diplomatic orders.  [oai_citation:136‡research_2.txt](sediment://file_000000005adc71f685d34607bf4d3973)  
+4. Demolish/disable extra farms to stop upkeep drain.  [oai_citation:137‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)  
+
+### Playbook: “Why are my houses not upgrading?” {#playbook-houses-not-upgrading}
+
+1. Ensure at least one need per category is met.  [oai_citation:138‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)  
+2. Ensure service buildings’ area coverage includes houses (roads/range).  [oai_citation:139‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)  
+3. Ensure storage has the goods (not just “producing”, but delivered).  [oai_citation:140‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)  
+
+---
+
+## Glossary
+
+- **Need Flicker:** A need repeatedly turning on/off because storage hits zero intermittently.
+- **Area Effect:** Radius-based modifier from a building or specialist (income, happiness, safety).
+- **Upkeep:** Ongoing gold loss and workforce reservation for a building.
+- **Throughput:** Effective goods per time, impacted by cycle time and logistics.
+- **Warehouse Cloud:** Shared island storage accessible via connected warehouses/trading post.  [oai_citation:141‡research_1.txt](sediment://file_00000000bf1071f69301ec14cba01a64)
+
+---
+
+## Placeholders (defined for linking; no data in supplied files)
+
+### Oyster Bed {#building-oyster-bed}
+- **Entity Type:** Building
+- **status:** Placeholder (no stats in supplied research files)
+
+### Scomber's Shack {#building-scombers-shack}
+- **Entity Type:** Building
+- **status:** Placeholder (no stats in supplied research files)
+
+### Sturgeon Hatchery {#building-sturgeon-hatchery}
+- **Entity Type:** Building
+- **status:** Placeholder (no stats in supplied research files)