From 6a50129ece8c2aa43b2e1e7526deafc58a4256f1 Mon Sep 17 00:00:00 2001
From: Aaron Pressey <aaronpressey84@gmail.com>
Date: Wed, 10 Jun 2026 15:18:39 -0500
Subject: [PATCH] docs(wiki): add technical design specs

---
 Home.md                   |   1 +
 Technical-Design-Specs.md | 780 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 781 insertions(+)
 create mode 100644 Technical-Design-Specs.md

diff --git a/Home.md b/Home.md
index a0ee627..1161b16 100644
--- a/Home.md
+++ b/Home.md
@@ -29,6 +29,7 @@ The core fantasy is simple:
 ## Wiki Sections
 
 - [[Gameplay]] — core loop, resources, petitioners, daily seed, world map, consequences, visual style, and design pillars
+- [[Technical-Design-Specs]] — MVP screens, data schemas, resource formulas, save structure, failure states, example day, and build phases
 - [[Lore]] — world-building, factions, and characters
 - [[Story]] — narrative structure, acts, cutscenes, and themes
 - [[Music]] — soundtrack, composers, themes, and audio direction
diff --git a/Technical-Design-Specs.md b/Technical-Design-Specs.md
new file mode 100644
index 0000000..0f2398d
--- /dev/null
+++ b/Technical-Design-Specs.md
@@ -0,0 +1,780 @@
+# Technical Design Specs
+
+## MVP Overview
+
+The MVP should prove the core loop:
+
+1. Player starts a new day.
+2. Three petitioners appear in the throne room.
+3. Player makes one ruling per petitioner.
+4. Rulings change resources, faction trust, settlement stability, or future event tags.
+5. Player takes one world map action.
+6. Day ends with a summary.
+7. Next day seed is generated from current game state.
+
+The MVP does not need full AI generation at first. It should work with hand-written petitioner data, deterministic seed logic, and simple map state.
+
+AI-generated content can be added later as a content-expansion layer.
+
+---
+
+## Core MVP Screens
+
+### 1. Home Screen
+
+Purpose:
+
+- Start game
+- Continue game
+- Open wiki/lore
+- Open settings
+
+Elements:
+
+- Game title
+- BLB throne image or logo
+- Start/continue buttons
+- Cosmic purple-blue background
+
+### 2. Throne Room Screen
+
+Purpose:
+
+Main gameplay hub for daily petitioners.
+
+Elements:
+
+- BLB on throne
+- Current petitioner
+- Petitioner text
+- Ruling choices
+- Resource HUD
+- Day counter
+- Faction/status icons
+- Button to continue after ruling
+
+### 3. Petitioner Modal / Case Panel
+
+Purpose:
+
+Focused decision interface.
+
+Elements:
+
+- Petitioner name
+- Petitioner faction or settlement
+- Problem description
+- 2-4 ruling choices
+- Preview style, depending on design:
+  - Full preview
+  - Partial preview
+  - Hidden consequence
+  - Advisor hint
+
+### 4. Resource HUD
+
+Purpose:
+
+Always show current economic state.
+
+Elements:
+
+- Bone total
+- Minion total
+- Cases of milk
+- Optional later:
+  - Stability
+  - Faction trust
+  - Day
+  - Warnings
+
+### 5. World Map Screen
+
+Purpose:
+
+Allow player to spend resources and assign minions after throne rulings.
+
+Elements:
+
+- BLB territory
+- NPC cities
+- Towns
+- Homesteads
+- Settlement status
+- Available map actions
+- Resource cost preview
+- Expected effect preview
+
+### 6. Daily Summary Screen
+
+Purpose:
+
+Show what happened today and what consequences were created.
+
+Elements:
+
+- Resource changes
+- Faction changes
+- Settlement changes
+- New flags/tags
+- Warnings for tomorrow
+- Button to start next day
+
+---
+
+## Petitioner Data Schema
+
+Recommended format for MVP: JSON.
+
+Example:
+
+```json
+{
+  "id": "petitioner_marrowgate_bad_bones_001",
+  "name": "Foreman Clatter",
+  "type": "settlement_request",
+  "faction": "bone_guild",
+  "settlementId": "marrowgate",
+  "tags": ["bones", "production", "early_game"],
+  "minDay": 1,
+  "maxDay": 10,
+  "weight": 10,
+  "requiresFlags": [],
+  "blocksFlags": ["marrowgate_resolved_bad_bones"],
+  "title": "Bad Bones at Marrowgate",
+  "body": "Foreman Clatter reports that Marrowgate's latest bone shipments are brittle, chalky, and emotionally disappointing.",
+  "choices": [
+    "send_milk_inspection",
+    "blame_the_guild",
+    "ignore_the_problem"
+  ],
+  "onSeenFlags": ["seen_bad_bones_case"]
+}
+```
+
+---
+
+## Ruling / Choice Schema
+
+Each ruling should be a separate reusable object or embedded inside the petitioner.
+
+Recommended choice object:
+
+```json
+{
+  "id": "send_milk_inspection",
+  "label": "Send three cases of milk and a minion inspector.",
+  "tone": "practical",
+  "costs": {
+    "bones": 0,
+    "minions": 1,
+    "milk": 3
+  },
+  "effects": {
+    "resources": {
+      "bones": 0,
+      "minions": -1,
+      "milk": -3
+    },
+    "settlements": {
+      "marrowgate": {
+        "stability": 5,
+        "boneProduction": 2
+      }
+    },
+    "factions": {
+      "bone_guild": {
+        "trust": 3
+      },
+      "milken_order": {
+        "trust": 1
+      }
+    },
+    "flagsAdd": ["marrowgate_milk_audit_started"],
+    "flagsRemove": [],
+    "futureEventWeights": {
+      "petitioner_marrowgate_recovery_001": 5
+    }
+  },
+  "resultText": "The milk inspection begins immediately. The bones do not become less weird, but they do become more useful."
+}
+```
+
+---
+
+## Resource Formula Rules
+
+MVP should start simple and readable.
+
+### Daily Resource Production
+
+Each settlement may produce resources at the end of each day.
+
+Example:
+
+```text
+dailyBones = sum(settlement.boneProduction)
+dailyMilk = sum(settlement.milkProduction)
+dailyMinionUpkeep = floor(minionTotal / 10)
+```
+
+Suggested MVP daily update:
+
+```text
+bones += totalBoneProduction
+milk += totalMilkProduction
+milk -= floor(minions / 10)
+```
+
+Optional:
+
+Minions require milk upkeep. If milk cannot cover upkeep, minion morale or count drops.
+
+---
+
+## Resource Triangle Rules
+
+### Bones -> Minions
+
+Bones create minions.
+
+MVP formula:
+
+```text
+1 minion costs 5 bones
+```
+
+Better minions can come later.
+
+Optional future formula:
+
+```text
+minionQuality = averageBoneQuality
+```
+
+### Minions -> Milk
+
+Minions can be assigned to produce milk.
+
+MVP formula:
+
+```text
+1 assigned minion produces 1 milk per day
+```
+
+Optional improvement:
+
+```text
+milkProduced = assignedMinions * settlement.milkMultiplier
+```
+
+### Milk -> Bones
+
+Milk improves bone production and bone quality.
+
+MVP formula:
+
+```text
+Sending 3 milk to a bone settlement increases boneProduction by +1 for 3 days.
+```
+
+Alternative:
+
+```text
+boneQuality += milkSent * 0.1
+boneProduction += floor(milkSent / 3)
+```
+
+Keep the MVP simple. Use the first version unless deeper simulation is needed.
+
+---
+
+## Settlement / World Map Schema
+
+Recommended settlement object:
+
+```json
+{
+  "id": "marrowgate",
+  "name": "Marrowgate",
+  "type": "city",
+  "owner": "blb",
+  "factionInfluence": ["bone_guild"],
+  "resources": {
+    "boneProduction": 5,
+    "milkProduction": 0,
+    "minionCapacity": 2
+  },
+  "stats": {
+    "stability": 60,
+    "loyalty": 50,
+    "need": 30,
+    "danger": 10
+  },
+  "tags": ["bone_city", "industrial", "early_game"],
+  "statusEffects": [
+    {
+      "id": "milk_boost",
+      "durationDays": 3,
+      "effects": {
+        "boneProduction": 1
+      }
+    }
+  ]
+}
+```
+
+---
+
+## Faction Schema
+
+Recommended faction object:
+
+```json
+{
+  "id": "bone_guild",
+  "name": "The Bone Guild",
+  "trust": 50,
+  "power": 40,
+  "agenda": "Control bone standards and production rights.",
+  "likes": ["bone_investment", "predictable_law", "industrial_expansion"],
+  "dislikes": ["milk_theology", "resource_waste", "minion_labor_rights"],
+  "tags": ["economic", "bones", "industrial"]
+}
+```
+
+---
+
+## Trust and Stability Ranges
+
+Use 0-100 ranges.
+
+### Faction Trust
+
+```text
+0-20: hostile
+21-40: suspicious
+41-60: neutral
+61-80: supportive
+81-100: loyal
+```
+
+### Settlement Stability
+
+```text
+0-20: collapsing
+21-40: unstable
+41-60: strained
+61-80: stable
+81-100: thriving
+```
+
+### Settlement Need
+
+```text
+0-20: comfortable
+21-40: minor need
+41-60: serious need
+61-80: crisis
+81-100: emergency
+```
+
+---
+
+## Minion Assignment Rules
+
+MVP minions can be assigned during the world map phase.
+
+Possible assignments:
+
+- Produce milk
+- Harvest bones
+- Stabilize settlement
+- Guard settlement
+- Repair damage
+- Support faction project
+
+MVP rule:
+
+```text
+Each available minion can be assigned to one task per day.
+Assigned minions return at the end of the day unless the action says otherwise.
+```
+
+Example map action:
+
+```json
+{
+  "id": "assign_minions_to_lacthollow",
+  "label": "Assign minions to Lacthollow dairies",
+  "costs": {
+    "minions": 3
+  },
+  "durationDays": 1,
+  "effects": {
+    "milk": 3,
+    "settlement": {
+      "lacthollow": {
+        "stability": 2
+      }
+    }
+  }
+}
+```
+
+---
+
+## Daily Seed Algorithm
+
+The daily seed should combine randomness with world state.
+
+MVP daily flow:
+
+```text
+1. Start day.
+2. Build eligible petitioner pool.
+3. Filter by minDay, maxDay, required flags, blocked flags.
+4. Increase weights based on current resource shortages.
+5. Increase weights based on unstable settlements.
+6. Increase weights based on low faction trust.
+7. Select 3 petitioners.
+8. Prevent duplicate petitioner IDs in same day.
+9. Save selected petitioner IDs into day history.
+```
+
+Example weighting rules:
+
+```text
+If bones < 20, add +5 weight to bone-related petitioners.
+If milk < 10, add +5 weight to milk-related petitioners.
+If minions < 5, add +5 weight to minion-related petitioners.
+If settlement stability < 40, add +8 weight to that settlement's crisis events.
+If faction trust < 30, add +6 weight to that faction's complaint events.
+```
+
+AI rotation can later generate or modify eligible cases, but the MVP should first prove deterministic seeded selection.
+
+---
+
+## Save Game Structure
+
+Recommended save structure:
+
+```json
+{
+  "saveVersion": "0.1.0",
+  "gameId": "run_001",
+  "day": 4,
+  "resources": {
+    "bones": 32,
+    "minions": 9,
+    "milk": 12
+  },
+  "kingdom": {
+    "stability": 58
+  },
+  "settlements": {},
+  "factions": {},
+  "flags": [
+    "seen_bad_bones_case",
+    "marrowgate_milk_audit_started"
+  ],
+  "history": {
+    "seenPetitioners": [],
+    "rulings": [],
+    "dailySummaries": []
+  },
+  "rng": {
+    "seed": "BLB_RUN_001_DAY_004"
+  }
+}
+```
+
+---
+
+## Failure States
+
+MVP failure states:
+
+```text
+bones <= 0 = Bone Collapse
+minions <= 0 = Workforce Collapse
+milk <= 0 = Milk Famine
+kingdomStability <= 0 = Dominion Collapse
+three settlements collapsed = Map Collapse
+one faction trust <= 0 and faction power >= 70 = Faction Coup
+```
+
+Each failure state should have a unique summary screen.
+
+---
+
+## Example Day
+
+### Starting Resources
+
+```text
+Bones: 25
+Minions: 8
+Milk: 10
+Kingdom Stability: 55
+```
+
+### Petitioner 1
+
+**Foreman Clatter of Marrowgate**
+
+Problem:
+
+Marrowgate's bones are brittle and production is dropping.
+
+Choices:
+
+1. Send 3 milk and 1 minion inspector.
+2. Punish the Bone Guild.
+3. Ignore the problem.
+
+Chosen:
+
+Send milk and inspector.
+
+Result:
+
+```text
+Milk -3
+Minions -1 for the day
+Marrowgate Stability +5
+Marrowgate Bone Production +1 for 3 days
+Bone Guild Trust +3
+```
+
+### Petitioner 2
+
+**Gerald the Minion Clerk**
+
+Problem:
+
+Minions are complaining that milk duty is sticky, humiliating, and "beneath skeleton-adjacent workers of their station."
+
+Choices:
+
+1. Promise hats.
+2. Ignore them.
+3. Spend bones to improve minion tools.
+
+Chosen:
+
+Promise hats.
+
+Result:
+
+```text
+Minion morale flag added: promised_hats
+No immediate resource cost
+Future event unlocked: hat_accountability
+```
+
+### Petitioner 3
+
+**Mayor Pella of Ribcage Crossing**
+
+Problem:
+
+Merchants want lower tariffs in exchange for emergency milk barrels.
+
+Choices:
+
+1. Accept the trade.
+2. Refuse and protect Dominion markets.
+3. Demand bones instead.
+
+Chosen:
+
+Accept trade.
+
+Result:
+
+```text
+Milk +5
+Ribcage Crossing Loyalty +4
+Bone Guild Trust -2
+Future trade event weight +5
+```
+
+### World Map Action
+
+Action:
+
+Assign 3 minions to Lacthollow dairies.
+
+Result:
+
+```text
+Milk +3 at end of day
+Lacthollow Stability +2
+3 minions unavailable until next day
+```
+
+### End of Day Summary
+
+```text
+Bones: 25
+Minions: 8
+Milk: 15
+Marrowgate is recovering.
+The Bone Guild is slightly annoyed by trade concessions.
+The minions remember the promised hats.
+Tomorrow's petitioner pool now includes possible hat-related consequences.
+```
+
+---
+
+## Content Format
+
+Recommended MVP content format:
+
+```text
+Hand-authored JSON for game logic.
+Markdown for lore/wiki pages.
+Cached AI-generated petitioners later.
+Database only after the schema stabilizes.
+```
+
+### MVP Recommendation
+
+Use:
+
+- `/content/petitioners/*.json`
+- `/content/choices/*.json`
+- `/content/settlements/*.json`
+- `/content/factions/*.json`
+- `/wiki/*.md`
+
+Do not start with a database unless the game already needs live editing, user-generated content, or server-side persistence.
+
+---
+
+## AI-Generated Content Rule
+
+AI-generated petitioners should not directly mutate the game state without validation.
+
+Recommended flow:
+
+```text
+AI generates petitioner draft.
+System validates schema.
+System assigns approved tags/effects only from allowed list.
+Generated content is cached.
+Player sees cached petitioner.
+Ruling applies deterministic effects.
+```
+
+The AI may write flavor.
+
+The game engine must control consequences.
+
+---
+
+## UI Wireframe Notes
+
+### Throne Screen
+
+```text
+[Resource HUD]
+
+ [BLB on Throne]
+
+[Petitioner Portrait]
+[Petitioner Text]
+
+[Choice 1]
+[Choice 2]
+[Choice 3]
+
+[Day / Map / Summary Buttons]
+```
+
+### Resource HUD
+
+```text
+Bones: 25 Minions: 8 Milk: 10
+Stability: 55 Day: 4
+```
+
+### Map Screen
+
+```text
+[Resource HUD]
+
+ [World Map]
+
+Marrowgate: Stable, Bone +5
+Lacthollow: Strained, Milk +3
+Ribcage Crossing: Neutral, Trade Active
+Homesteads: Need Rising
+
+[Available Actions Panel]
+```
+
+### Daily Summary
+
+```text
+Day 4 Complete
+
+Resource Changes:
+Bones +0
+Minions +0
+Milk +5
+
+Settlement Changes:
+Marrowgate recovering
+Lacthollow stabilized
+
+New Flags:
+promised_hats
+marrowgate_milk_audit_started
+
+[Begin Day 5]
+```
+
+---
+
+## Build Priority
+
+### Phase 1: Static MVP
+
+- Home screen
+- Throne room screen
+- Resource HUD
+- Three hard-coded petitioners
+- Choice effects
+- Daily summary
+- Basic save state
+
+### Phase 2: Seeded Days
+
+- Petitioner pool
+- Weighted selection
+- Flags
+- Settlement/faction state
+- Map action screen
+
+### Phase 3: Reactive World
+
+- Settlement consequences
+- Faction trust
+- Recurring petitioners
+- Failure states
+- Endings
+
+### Phase 4: AI Layer
+
+- AI-generated petitioner drafts
+- Schema validation
+- Cached event rotation
+- Flavor expansion
+- Dynamic but controlled content
+
+---
+
+*See also: [[Home]] | [[Gameplay]] | [[Lore]] | [[Story]] | [[References]]*