update: add documentation for bot operations and agent guidance

AGENTS.md

@@ -0,0 +1,54 @@
+# AGENTS
+
+Guidance for future coding/automation agents working in this repository.
+
+## Goal
+
+Maintain and improve a Mineflayer bot that automates a spawner and order loop with strict security shutdown behavior.
+
+## Primary Files
+
+- `index.js`: main bot logic, event handlers, security flow, web API.
+- `web/index.html`: local control panel UI.
+- `allowed_players.txt`: allow-list consumed at startup.
+
+## Behavioral Guardrails
+
+- Do not remove or weaken security triggers without explicit user request.
+- On emergency path, preserve order:
+  - stop loop
+  - break/remove spawner
+  - try ender chest stash
+  - send webhook
+  - quit
+- Keep movement guard behavior intact unless asked to modify it.
+
+## Code Change Rules
+
+- Prefer small, focused functions and reuse existing helpers.
+- Keep logs user-readable (`pushLog`) and reserve noisy details for `debugLog`.
+- Avoid introducing new dependencies unless needed.
+- Keep constants near top-level config section.
+
+## Validation Checklist
+
+After edits:
+
+1. Run syntax check:
+   - `node --check index.js`
+2. Start bot locally:
+   - `node index.js`
+3. Verify HTTP server starts on `:3008`.
+4. Verify no regressions in emergency shutdown sequence.
+
+## Common Pitfalls
+
+- GUI slot interactions can desync if cursor item is not returned.
+- Custom server GUIs may use non-standard item labels.
+- `window.inventoryStart` may be missing; use fallback logic already in file.
+
+## Suggested Future Improvements
+
+- Make ender chest search distance configurable via env.
+- Add health/status endpoint with loop and security state.
+- Add integration-safe dry-run mode for UI logic testing.

README.md

@@ -0,0 +1,84 @@
+# mcbot
+
+Mineflayer bot for handling a spawner workflow, placing bone orders, and protecting the area with automatic emergency shutdown logic.
+
+## Features
+
+- Repeating spawner cycle (`/api/spawner`) with a 60-second delay between cycles.
+- GUI automation for:
+  - opening spawner GUI
+  - moving bones to inventory
+  - running `/order ZareMate`
+  - delivering and confirming order
+- Security monitor:
+  - detects unauthorized nearby players (from `allowed_players.txt`)
+  - detects nearby block breaks
+  - triggers emergency routine
+- Emergency routine:
+  - attempts to break/remove the spawner
+  - attempts to stash spawner drops into a nearby ender chest
+  - sends Discord webhook alert
+  - quits bot
+- Simple web UI + API on `http://localhost:3008`.
+
+## Requirements
+
+- Node.js 18+
+- A valid Microsoft-authenticated Minecraft account for the configured bot username
+- Access to target server (`java.donutsmp.net` by default in code)
+
+## Install
+
+```bash
+npm install
+```
+
+## Configure
+
+Create `.env` in project root.
+
+```env
+DISCORD_WEBHOOK_URL=
+ALLOWED_PLAYERS_FILE=allowed_players.txt
+DEBUG_LOGS=0
+```
+
+Notes:
+
+- `ALLOWED_PLAYERS_FILE` can be relative to project root or absolute path.
+- `DEBUG_LOGS=1` enables extra slot/window debug logging.
+
+## Run
+
+```bash
+node index.js
+```
+
+## Web Endpoints
+
+- `GET /` : basic web UI
+- `GET /api/logs` : bot logs as JSON
+- `POST /api/spawner` : start spawner loop
+- `POST /api/stop` : stop spawner loop
+
+## Allow List
+
+Edit `allowed_players.txt`:
+
+- one player name per line
+- case-insensitive matching
+- lines starting with `#` are ignored
+
+## Important Runtime Behavior
+
+- On first spawn, bot stores join position and auto-arms security after 5 seconds.
+- Movement guard pauses loop if bot is moved too far from loop start.
+- If security is triggered, bot now tries to stash spawner items in ender chest before quitting.
+
+## Files
+
+- `index.js` : all bot logic and HTTP server
+- `web/index.html` : web UI
+- `allowed_players.txt` : allow-list for security monitor
+- `AGENTS.md` : guidance for future automation agents
+- `docs/BOT_OPERATIONS.md` : deeper operational notes

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.