update: add documentation for bot operations and agent guidance

docs/BOT_OPERATIONS.md

@@ -0,0 +1,68 @@
+# Bot Operations
+
+This document describes current control flow and operational expectations.
+
+## Startup Sequence
+
+1. Load `.env` and allow-list.
+2. Create mineflayer bot instance.
+3. On `spawn`, set `joinPosition`.
+4. Start security monitor interval.
+5. Arm security after delay (`SECURITY_ARM_DELAY_MS`).
+
+## Spawner Loop
+
+Loop starts via `POST /api/spawner`.
+
+Per cycle:
+
+1. Locate/face nearby spawner block.
+2. Open spawner GUI.
+3. Move all bones from GUI to inventory.
+4. Close GUI.
+5. Run `/order ZareMate`.
+6. Open order GUI and click bone order item.
+7. Move inventory bones into delivery GUI.
+8. Confirm with lime/green glass pane.
+9. Wait `LOOP_DELAY_MS` (default 60s).
+
+## Security Logic
+
+Security checks run when `securityArmed === true`.
+
+Triggers:
+
+- Unauthorized player within `SECURITY_RADIUS`.
+- Nearby block broken event within `SECURITY_RADIUS`.
+
+On trigger:
+
+1. Stop spawner loop.
+2. Try to break spawner until gone.
+3. Wait briefly for drops.
+4. Attempt to open nearby ender chest.
+5. Shift-move spawner items from inventory into chest.
+6. Send Discord alert with status.
+7. Quit bot.
+
+## Ender Chest Stash Notes
+
+- Looks for `ender_chest` block within 6 blocks.
+- If no chest is found, routine logs and continues to quit.
+- If no spawner items are present in inventory, stash routine is skipped.
+
+## Web API Contract
+
+- `GET /api/logs` returns:
+  - `{ logs: [{ time, message }, ...] }`
+- `POST /api/spawner` returns:
+  - `{ ok: true, running: true }` on success
+- `POST /api/stop` returns:
+  - `{ ok: true, running: false }` when stopped
+
+## Operational Tips
+
+- Keep an accessible ender chest near the bot for emergency stash reliability.
+- Keep `allowed_players.txt` current.
+- Enable `DEBUG_LOGS=1` while diagnosing GUI slot behavior.
+- Confirm webhook mentions are configured as expected in your Discord channel.