From 3bb2ef14fddfdd957e1c3b58d6cc7508697e9b90 Mon Sep 17 00:00:00 2001
From: Claude <claude@firefrostgaming.com>
Date: Wed, 15 Apr 2026 17:36:03 +0000
Subject: [PATCH] =?UTF-8?q?REQ:=20Bitch=20Bot=20=E2=80=94=20first-boot=20p?=
 =?UTF-8?q?rovisioning=20mod,=20Holly-approved,=20architecture=20locked?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../requests/REQ-2026-04-15-bitch-bot.md      | 75 +++++++++++++++++++
 1 file changed, 75 insertions(+)
 create mode 100644 docs/code-bridge/requests/REQ-2026-04-15-bitch-bot.md

diff --git a/docs/code-bridge/requests/REQ-2026-04-15-bitch-bot.md b/docs/code-bridge/requests/REQ-2026-04-15-bitch-bot.md
new file mode 100644
index 0000000..332faac
--- /dev/null
+++ b/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`