Add AGENTS guidance referencing SSOT

AGENTS.md

@@ -0,0 +1,21 @@
+# AGENTS (Repository Guidance)
+
+## Repository Intent
+- The `web/desktop` and `web/mobile` folders host the live HUD demo (Desktop and mobile). Keep everything that should be served from a webserver inside those folders.
+- `docs/game_rulebook.md` is the **Single Source of Truth (SSOT)** for Galaxy Forge’s game logic, builder system, resources, and requirements. Any UI work, game behavior, or rules must align with — not contradict — that document unless a new decision is logged.
+- `docs/` stores documentation while `planning/` holds sketches/notes that are not meant for deployment.
+
+## Key Instructions for Agents
+1. **Reference SSOT first.** When implementing features or answering questions related to game balance, resources, blueprints, buildings, or world generation, open `docs/game_rulebook.md` and confirm compliance. Note any missing detail needs a Decision Log entry (see section 13).
+2. **Respect folder intent.** Changes to web assets go in `web/desktop` or `web/mobile` only. Use `planning/` for drafts and `docs/` for textual explanations.
+3. **Document assumptions.** If you must deviate from `docs/game_rulebook.md`, append an entry to the Decision Log (section 13) explaining the why/when.
+4. **Keep mobile/desktop aligned.** When adjusting UI/partials, mirror updates in both `web/desktop` and `web/mobile` unless the change is explicitly mobile-only or desktop-only and documented.
+
+## When touching docs
+- Expand `docs/game_rulebook.md` if you update core rules, flow, or systems described there. Keep numbering/sections intact; append entries in the Decision Log (section 13) with dates.
+- The root `README.md` should mention where to find the SSOT and purpose of each folder.
+
+## Decision Log Reminder
+- Section 13 of `docs/game_rulebook.md` is the Decision Log. Add a dated entry whenever:
+  - You introduce a new rule variant or exception.
+  - The implementation deviates from the documented defaults.

docs/game_rulebook.md

@@ -0,0 +1,384 @@
+# Galaxy Forge — game_rulebook.md (SSOT) v1.0
+*Single Source of Truth für Game-Logik, Baukasten-Systeme und Generator-Regeln*
+
+---
+
+## 0) Zweck & Arbeitsweise (SSOT)
+Dieses Dokument ist die **Single Source of Truth (SSOT)**.  
+**Codex/Entwicklung darf nichts implementieren, was dem widerspricht.**
+
+**Wenn etwas fehlt oder unklar ist:**
+1) **Default-Regeln** in diesem Dokument anwenden,  
+2) Entscheidung im **Decision Log** (am Ende) festhalten,  
+3) danach erst implementieren.
+
+---
+
+## 1) High-Level Vision
+Galaxy Forge ist ein persistentes Weltraum-Browsergame, dessen Inhalte **datengetrieben** sind:
+- Spieler (und später ggf. User-Designer) erstellen **Blueprints** (Gebäude, Schiffe, Forschung, Rassen, Spezialisierungen) über einen **Baukasten**.
+- Blueprints bestehen aus **Capabilities (Flags)**, **Effects (standardisierte Bausteine)**, **Requirements**, **Access Rules**.
+- Balance soll möglichst **automatisch** über ein **Punkte-/Budget-System** + **Auto-Cost** funktionieren, um Admin-Aufwand zu minimieren.
+
+---
+
+## 2) Kernbegriffe
+
+### 2.1 Blueprint (universell)
+Ein Blueprint ist ein datengetriebenes Objekt mit einheitlichem Schema:
+
+- `kind`: `building | ship | research | race | specialization | space_object` (erweiterbar)
+- `key`: eindeutiger String
+- `name`: Anzeigename
+- `tags`: freie Taxonomie-Strings
+- `capabilities`: freie Taxonomie-Strings (Flags)
+- `effects`: Liste standardisierter Effekt-Bausteine (kleine, feste Bibliothek)
+- `requirements`: Liste standardisierter Requirements (kleine, feste Bibliothek)
+- `access`: Whitelist/Blacklist nach Race/Specialization (und später ggf. weitere Dimensionen)
+- `balance`: Budget/Punkte/Auto-Cost (für usergenerierte Inhalte)
+
+**Wichtig:** Neue Tags/Capabilities/Blueprints müssen ohne Codeänderung möglich sein.  
+Neue **Effect-Typen** oder **Requirement-Typen** erfordern ggf. Code (Engine-Erweiterung) und sind bewusst klein zu halten.
+
+---
+
+## 3) Ressourcenmodell
+
+### 3.1 Ressourcenarten (SSOT)
+Galaxy Forge verwendet diese Ressourcen (erweiterbar, aber stabil halten):
+- `metal` (Metall)
+- `alloy` (Legierung)
+- `crystals` (Kristalle)
+- `energy` (Energie)
+- `credits` (Credits)
+- `population` (Einwohner)
+- `water` (Wasser)
+- `deuterium` (Deuterium)
+- `food` (Nahrungsgüter)
+
+### 3.2 Zeitbasierte Simulation (serverseitig, authoritative)
+Der Server speichert pro Planet:
+- aktuelle Mengen pro Ressource
+- `last_resource_update_at`
+
+Beim Lesen oder bei Aktionen (Bauen, Abholen, Missionen etc.) muss der Server Ressourcen **nachziehen**:
+
+1) `dt = now - last_resource_update_at`  
+2) `net_rates_per_hour = calc_net_rates(planet)` (Produktion − Verbrauch, inkl. Drossel)  
+3) `amount += net_rates * dt/3600`  
+4) optional: clamping auf `0..cap` (siehe 3.3)  
+5) `last_resource_update_at = now`
+
+### 3.3 Caps (Speicherlimits)
+Caps sind optional pro Ressource und entstehen über Effects (z.B. `capacity_add`).  
+Wenn Cap für eine Ressource nicht definiert ist, gilt `cap = infinity` (Default).  
+Caps dürfen auch für `energy` existieren (Batterien).
+
+---
+
+## 4) Multiplikatoren-System (Planet + Race + Spec + Research + …)
+
+### 4.1 Grundsatz
+Blueprints definieren **Grundwerte** (z.B. Mine produziert 50/h).  
+Der tatsächliche Effekt entsteht durch eine **Multiplikator-Kette**.
+
+Für eine Ressource `r` gilt:
+
+`effective_value(r) = base_value(r) × Π (1 + bonus_i(r))`
+
+- +10% = `+0.10`, −15% = `−0.15`
+- Multiplikation ist Absicht (Synergien, komplexeres Wirtschaften)
+
+### 4.2 Quellen der Boni (Standard-Kette)
+Boni werden gesammelt (Reihenfolge nur für Debug/Anzeige):
+1) Planet (konkrete Planet-Modifier)
+2) Race (Rassenmodifier)
+3) Specialization (Spezialisierungsmodifier)
+4) Research (Forschungsmodifier)
+5) optional später: Events, Artefakte, Offiziere, Allianzboni …
+
+### 4.3 Separate Behandlung von Produktion & Verbrauch
+- Produktion (`produce`, `convert outputs`) und Verbrauch (`consume`, `convert inputs`) können getrennte Boni haben.
+- Default: Wenn kein spezieller Bonus existiert, wirkt ein Bonus nur auf das passende Feld (prod vs consume).
+
+### 4.4 Debug-Breakdown (Pflicht für UI)
+Die UI soll optional einen Breakdown anzeigen:
+- Base
+- Planet
+- Race
+- Spec
+- Research
+- Result
+
+Das ist essenziell für Transparenz & Balancing.
+
+---
+
+## 5) Weltmodell & Space Objects
+
+### 5.1 Koordinaten
+Koordinaten sind `galaxy:system:position` (G:S:P).
+
+### 5.2 Space Objects (Mehrfachobjekte pro Koordinate)
+An einer Koordinate können mehrere Space Objects existieren:
+- planet
+- wormhole
+- blackhole
+- station
+- anomaly
+- mission_marker
+- debris_field
+- beacon
+- … (erweiterbar)
+
+Ein Planet ist ein Space Object vom Typ `planet`.
+
+### 5.3 Targeting für Flotten/Missionen
+Ein Ziel kann sein:
+- `target_object_id` (bevorzugt) oder
+- `(coords + target_type)`
+
+Dadurch kann die UI z.B. „anfliegen: Planet / Wurmloch / Station“ auswählen.
+
+---
+
+## 6) Planetklassen & Universum-Generator (Constraints + Budget)
+
+### 6.1 Planetklasse ist „Vorgabe-Regelwerk“
+Planetklassen (ice/desert/rock/…) geben dem Generator:
+- **Constraints (MUSS):** harte Min/Max-Bedingungen für bestimmte Resource-Modifier
+- **Bias (SOLL):** Verteilungspräferenzen, welche Ressourcen eher hoch/runter gehen
+
+Beispiel (Ice):
+- water immer >= +50%
+- energy immer <= −60%
+
+### 6.2 Planet-Modifier werden pro Planet gezogen und sind stabil
+Jeder Planet hat:
+- `planet_class_key`
+- `planet_seed`
+- **konkrete** Modifier-Werte pro Ressource (werden gespeichert)
+
+Warum speichern?
+- Balancing-Änderungen sollen nicht rückwirkend alte Planeten verändern.
+
+### 6.3 Budget-/Score-System für Vergleichbarkeit
+Planeten sollen trotz Spezialisierung **vergleichbar** sein.
+
+Definiere:
+- Gewichte `W[r]` pro Ressource (Wertigkeit)
+- Modifier `m[r]` pro Ressource (z.B. +2.0 = +200%, −1.0 = −100%)
+- Planet-Score `S = Σ(W[r] × m[r])`
+
+Jeder Planet gehört zu einem Tier mit `target_score`:
+- normal: `S ≈ 0`
+- rich: `S ≈ +0.4`
+- legendary: `S ≈ +1.0`
+(Spawnwahrscheinlichkeiten per weight)
+
+**Generator-Regel:**  
+Nach Anwenden der Klassen-Constraints werden die restlichen Modifier so ergänzt/justiert, dass `S` im Zielbereich liegt (epsilon).
+
+### 6.4 Ablauf Planetgenerierung (deterministisch)
+1) planet_class anhand spawn_weight wählen  
+2) alle `m[r] = 0` initialisieren  
+3) Constraints anwenden (min/max + ggf. random within range)  
+4) aktuellen Score S berechnen  
+5) Rest-Modifier verteilen (unter Einhaltung globaler Bounds + Bias), bis Zielscore erreicht  
+6) Falls unmöglich: re-roll oder Tier wechseln (SSOT-Default: re-roll bis max N; dann Tier switch)
+
+---
+
+## 7) Baukasten-System: Capabilities, Effects, Requirements, Access
+
+### 7.1 Capabilities (Flags) — frei erweiterbar (Formular-Add)
+Capabilities sind freie Strings, z.B.:
+- `menu:research`
+- `menu:bank`
+- `menu:spy`
+- `menu:black_market`
+- `menu:lottery`
+- `shipyard:small|medium|large|mega`
+- `defense:orbital`
+- `terraforming`
+- `ground:cloning`
+- `stargate`
+
+**Regel (Feature Unlock):**  
+Ein Menüpunkt/Feature ist verfügbar, wenn der Spieler **mindestens einen Besitz/State** hat, der die Capability liefert:
+- meist: mindestens ein Gebäude mit `capabilities` enthält `menu:xyz`
+- alternativ: Forschung kann Capability gewähren (`grant_capability`)
+
+### 7.2 Effects (kleine, feste Bibliothek)
+Der Baukasten erlaubt nur diese Effect-Typen (v1):
+1) `produce` — +X pro Stunde Ressource  
+2) `consume` — −X pro Stunde Ressource  
+3) `convert` — Inputs/h → Outputs/h (z.B. 20 metal + 5 energy → 5 alloy)  
+4) `capacity_add` — Cap +X für Ressource (z.B. Lager, Batterie)  
+5) `queue_slots_add` — zusätzliche Bau-/Queue-Slots (z.B. Bauzentrum)  
+6) `points_add` — +X pro Stunde für Punkt-Ressourcen (z.B. research_points, spy_points)  
+7) `modifier_add` — Additiver Bonus (z.B. +0.02 metal prod) auf Ziel (by_resource/by_tag/by_key)  
+8) `grant_capability` — schaltet Capability frei (v.a. Forschung)
+
+**Hinweis:** Neue Effect-Typen sind möglich, aber erfordern Code-Erweiterung und SSOT-Update.
+
+### 7.3 Requirements (kleine, feste Bibliothek)
+Der Baukasten erlaubt diese Requirements (v1):
+- `building_count` (min count eines bestimmten Gebäudes)
+- `building_tag_count` (min count aller Gebäude mit Tag)
+- `research_level` (min Level einer Forschung)
+- `has_capability` (z.B. `menu:research` muss vorhanden sein)
+- `player_race_in` / `player_race_not_in`
+- `player_spec_in` / `player_spec_not_in`
+
+### 7.4 Access Rules (Whitelist/Blacklist) — überall gleich
+Zusätzlich oder alternativ zu Requirements können Blueprints `access` definieren:
+
+- `allowed_races`, `blocked_races`
+- `allowed_specializations`, `blocked_specializations`
+
+**Regeln:**
+- Wenn `allowed_*` nicht leer → muss enthalten sein.
+- Wenn in `blocked_*` enthalten → verboten.
+
+Beispiel: Roboter dürfen keine Klonfabrik, aber dürfen Robotik-Werkstatt:
+- clone_factory: blocked_races=["robot"]
+- robot_workshop: allowed_races=["robot"]
+
+---
+
+## 8) Gebäude (Buildings) — stackable/levelable und Bauzentren-Queues
+
+### 8.1 Gebäude-Modelle
+Gebäude unterstützen mindestens:
+- `stackable`: man baut N Instanzen (Count)
+- `levelable`: ein Gebäude hat Level L (Upgrade)
+(hybrid ist optional später)
+
+### 8.2 Paralleles Bauen über Bauzentren
+Es gibt ein Gebäude (Blueprint) mit Capability/Effect, das **Queue-Slots** liefert.
+Standard: `build_center` ist stackable und hat Effect `queue_slots_add: +1 je count`.
+
+**Regel:**  
+`queue_slots = base_slots + Σ(queue_slots_add effects)`  
+SSOT-Default: `base_slots = 0` und mindestens 1 Bauzentrum im Startpaket.
+
+### 8.3 Bauauftrag (Build Job)
+Ein Bauauftrag enthält:
+- planet_id
+- building_key
+- mode:
+  - stackable: delta_count
+  - levelable: target_level
+- started_at, finish_at
+- slot_index (0..queue_slots-1)
+
+### 8.4 Start eines Bauauftrags
+1) update_resources(planet)  
+2) freie Slots prüfen (active_jobs < queue_slots)  
+3) Requirements + Access prüfen  
+4) Auto-Cost berechnen (oder config cost)  
+5) Ressourcen sofort abziehen  
+6) Job anlegen (finish_at)
+
+### 8.5 Abschluss
+Wenn `now >= finish_at`:
+- stackable: count += delta_count  
+- levelable: level = target_level  
+- Job entfernen  
+- optional: Report/Event
+
+---
+
+## 9) Zerstörbarkeit & Bombardierung (Gebäude können zerstört werden)
+
+### 9.1 Gebäude-Property: destroyable
+Gebäude können `properties.destroyable` haben:
+- Default: `true`
+- Wenn `false`, darf Bombardierung dieses Gebäude nicht reduzieren.
+
+Optional:
+- `structure` (Robustheit)
+- `bombard_priority` (Zielgewicht)
+- `debris_yield` (Ressourcenanteil der Kosten als Trümmer)
+
+### 9.2 Minimalregel (v1)
+Bombardierung reduziert direkt:
+- stackable: count sinkt
+- levelable: level sinkt
+Kein separater Damage-State im v1.
+
+---
+
+## 10) Balance für usergenerierte Inhalte: Punkte + Auto-Cost (Anti-Exploit)
+
+### 10.1 Ziel
+User sollen Inhalte bauen können, ohne das Spiel zu brechen.
+Admin soll nicht jedes Ding manuell balancen müssen.
+
+### 10.2 Grundregel (Anti-Exploit)
+**User wählen Effekte, nicht frei Kosten/Zeit.**  
+Kosten/Zeit/Upkeep werden **automatisch** aus Effekten abgeleitet (Auto-Cost).
+
+Optional gibt es einen Tradeoff-Slider (z.B. „billiger vs schneller“), aber nur in engem Korridor:
+- Default: max ±2 Budgetpunkte oder max ±20% Abweichung.
+
+Damit ist „0 Kosten + lange Zeit“ nicht ausnutzbar, weil Kosten nicht frei sind.
+
+### 10.3 Budget pro Blueprint-Kategorie
+Jede Kategorie hat ein Budget (Startwerte v1, später balancen):
+- building: z.B. 15
+- ship: z.B. 20
+- research: z.B. 12
+- race: z.B. 0 (Summe Traits muss nahe 0)
+- specialization: z.B. 0 (nahe 0)
+
+### 10.4 Scoring (Power Score)
+Jeder Effect trägt Punkte bei, abhängig von:
+- Ressource (über Werttabelle)
+- Art des Effekts (produce/convert/stats/modifier)
+- Inputs (consume) reduzieren Score
+- Constraints/Exklusivität kann Score reduzieren (z.B. „nur race robot“ erlaubt -> leichter Preisabschlag möglich)
+
+**Werttabelle (v1, grob):**
+- metal: 1.0
+- crystals: 1.2
+- deuterium: 1.3
+- water: 1.1
+- food: 0.9
+- energy: 0.8
+- alloy: 2.5
+- credits: 0.7
+(population/points separat)
+
+Die konkrete Score-Formel ist ein Implementierungsdetail, muss aber:
+- deterministisch
+- transparent (UI zeigt Score)
+- nicht trivialisierbar
+
+### 10.5 Auto-Cost Ableitung (Grundsatz)
+`cost` und `build_time` steigen monoton mit Score.
+Optional zusätzlich: `upkeep` (consume) als natürliche Bremse, statt Hardcaps.
+
+---
+
+## 11) Start-Defaults (v1)
+- Universe: 9 Galaxien, 499 Systeme, 15 Positionen (anpassbar per config)
+- Start: 1 Planet pro Spieler
+- Start: 1 Bauzentrum (damit mindestens 1 Queue-Slot existiert)
+- Planetklasse: temperate (oder nach Race preference), aber Generatorregel gilt
+- Gebäudeanzahl: keine Hardcaps (Balance über Kosten/Zeit/Upkeep)
+
+---
+
+## 12) Konfig-Dateien (Empfehlung)
+- `config/universe.json` (Seeds, Dimensionen, Tier-Weights)
+- `config/resources.json` (Werttabelle, caps defaults)
+- `config/planet_classes.json` (spawn_weight, constraints, bias)
+- `config/blueprints/*.json` (Gebäude, Schiffe, Forschung, Rassen, Specs)
+- `config/taxonomy_capabilities.json` (optional UI-Hilfe/Labels)
+
+---
+
+## 13) Decision Log
+- [2026-02-03] v1.0 erstellt: Baukasten-Blueprint-System + Planet-Generator (Constraints+Budget) + Build-Center-Queues + destroyable Flag + Auto-Cost Prinzip.