REQ: Bitch Bot — first-boot provisioning mod, Holly-approved, architecture locked

docs/code-bridge/requests/REQ-2026-04-15-bitch-bot.md

@@ -0,0 +1,75 @@
+# REQ-2026-04-15-bitch-bot
+
+**From:** Chronicler #92  
+**Date:** 2026-04-15  
+**Priority:** MEDIUM — post-launch, Holly-approved  
+**Status:** PENDING
+
+## Summary
+
+Build Bitch Bot — a lightweight Forge/NeoForge mod that runs once on first server boot to provision a new Firefrost server. Named by Holly (The Catalyst). Full architecture locked via 4-round Gemini consultation — see `docs/consultations/gemini-modpack-installer-followup-2026-04-15.md`.
+
+## What Bitch Bot Does (First Boot Only)
+
+On `ServerStartedEvent`, the mod:
+
+1. Checks for `provision.json` in the server root — if not present, does nothing
+2. Reads `level.dat` to get original spawn XYZ
+3. Downloads + verifies schematic from `schematic_url` (SHA-256 check against `schematic_hash`)
+4. Pastes schematic at `spawn_coords` (centered on `paste_origin`)
+5. Places 4 command blocks at positions in `command_blocks[]` with `/tp @p [original_spawn_x] [original_spawn_y] [original_spawn_z]` baked into NBT, `facing` as specified
+6. Sets worldspawn to `spawn_coords` + `worldspawn_offset`
+7. Sets gamerule `doFireTick false`
+8. Places rules signs at spawn (sign content from `provision.json`)
+9. Drops YAWP config file into `world/serverconfig/` using `yawp_region` bounding box and flags
+10. If `self_destruct_on_success: true` — renames itself to `BitchBot.jar.disabled`
+
+## provision.json Structure
+
+```json
+{
+  "version": "1.0",
+  "schematic_name": "firefrost-spawn-v1.schem",
+  "schematic_url": "https://downloads.firefrostgaming.com/...",
+  "schematic_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+  "spawn_type": "standard",
+  "spawn_coords": { "x": -5000, "y": 64, "z": -5000 },
+  "paste_origin": "center",
+  "worldspawn_offset": { "x": 0, "y": 0, "z": 0 },
+  "command_blocks": [
+    { "position": { "x": -4998, "y": 65, "z": -4998 }, "facing": "up" },
+    { "position": { "x": -5002, "y": 65, "z": -4998 }, "facing": "up" },
+    { "position": { "x": -4998, "y": 65, "z": -5002 }, "facing": "up" },
+    { "position": { "x": -5002, "y": 65, "z": -5002 }, "facing": "up" }
+  ],
+  "rules_signs": [
+    { "position": { "x": -4999, "y": 65, "z": -5005 }, "lines": ["Line 1", "Line 2", "Line 3", "Line 4"] }
+  ],
+  "yawp_region": {
+    "name": "spawn",
+    "min": { "x": -5050, "y": 0, "z": -5050 },
+    "max": { "x": -4950, "y": 255, "z": -4950 },
+    "flags": ["no-pvp", "no-mob-spawning", "break-blocks", "place-blocks"]
+  },
+  "self_destruct_on_success": true
+}
+```
+
+## Key Architecture Notes (from Gemini)
+
+- **Do NOT write to `.mca` region files directly** — corruption-prone on 1.20+
+- Mod handles everything via `ServerStartedEvent` — no RCON, no WorldEdit console
+- YAWP config is a dropped file in `world/serverconfig/` — no commands needed
+- Schematic pasting via standard Forge schematic API (not region file manipulation)
+- Self-destructs by renaming jar to `.jar.disabled` after successful first boot
+
+## Target Versions
+
+- NeoForge 1.21.1 (primary — matches most FFG servers)
+- Forge 1.20.1 (secondary if feasible)
+
+## Deliverable
+
+Single jar: `BitchBot-1.0.0-neoforge-1.21.1.jar`
+
+Full spec in: `docs/consultations/gemini-modpack-installer-followup-2026-04-15.md`