# ChatGPT project context

This directory is a local mirror of the ChatGPT project “maze32”.

- Treat every file under `sources/` as read-only reference material.
- Do not edit, rename, move, or delete synced project files.
- These files may be replaced the next time a task is created from this ChatGPT project.


## Project instructions

### Language

- Write all canonical documentation in English.
- Write source comments, test names, protocol identifiers, log messages, and
  user-facing diagnostic text in English.

### Canonical documents

- `MVP.md` defines product scope, gameplay rules, and MVP acceptance criteria.
- `ARCHITECTURE.md` defines implementation contracts and technical boundaries.
- `PLANS.md` defines the current implementation milestone and its evidence.
- `docs/BOARD_PASSPORT.md` defines confirmed hardware facts and explicit
  unknowns.
- Files under `sources/` remain read-only references and are never canonical
  implementation files.

When documents disagree, stop and resolve the conflict before implementation.
Do not silently choose one requirement over another.

### Milestone workflow

- Follow `PLANS.md` strictly.
- Milestones may be planned and added to `PLANS.md` in batches.
- Number milestones from 1 without gaps using `Milestone 001`, `Milestone 002`,
  and so on.
- Execute milestones strictly in ascending numerical order.
- Do not start a milestone until every preceding milestone is `COMPLETE`.
- Keep at most one milestone `IN_PROGRESS`.
- Append newly discovered milestones to the end of `PLANS.md`; do not insert or
  renumber existing milestones without explicit project-owner approval.
- Every milestone must include objective, scope, deliverables, acceptance
  criteria, evidence, and status.
- Do not mark a milestone `COMPLETE` without concrete recorded evidence for
  every acceptance criterion.

### Locked platform baseline

- Target ESP32-C6FH4 with 4 MB Flash.
- Do not require PSRAM.
- Use PlatformIO with `espressif32@7.0.1`, ESP-IDF, and the compatible
  `esp32-c6-devkitm-1` board profile.
- Use `partitions.csv` and `sdkconfig.defaults` from the project root.
- Do not add an OTA partition for MVP.
- Do not assume a board GPIO map, built-in LED, or exact commercial PCB model.

### Architectural invariants

- The ESP is the sole authoritative owner of lobby and match state.
- Browsers send commands and render server-approved projections; they do not
  decide movement, inventory, timers, visibility, or results.
- Never serialize hidden maze or object state to player clients.
- Observer sessions are read-only.
- Bound all connection counts, message sizes, queues, retries, and allocations.
- Active game state need not survive reboot; Wi-Fi configuration must persist
  in NVS.

### Build and verification

- Parse the project configuration with
  `/home/sasa/.platformio/penv/bin/pio project config` after changing
  `platformio.ini`.
- Build with `/home/sasa/.platformio/penv/bin/pio run` once firmware sources
  exist.
- Add host-side deterministic tests for portable game logic before relying only
  on device tests.
- Verify the final application and filesystem sizes against `partitions.csv`.
- Test on the physical board before recording hardware acceptance evidence.
- Preserve exact commands and relevant outputs in the active milestone's
  evidence section.