# 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.