# 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, and system log
  messages in English.
- Write all player-facing browser UI copy, game messages, and user-visible
  browser errors in Russian.

### 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.
- `docs/UI_STYLE.md` defines the canonical browser visual language, responsive
  layout, controls, and presentation behavior.
- 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.

### Commit message handoff

- After completing every user prompt, provide a proposed commit message for
  the resulting changes. This is mandatory when completing a milestone.
- Use the Conventional Commits format `type(scope): imperative summary`, or
  `type: imperative summary` when no meaningful scope exists.
- Choose exactly one appropriate type from `feat`, `fix`, `refactor`, `perf`,
  `test`, `docs`, `style`, `build`, `ci`, `chore`, or `revert`.
- Write the commit message in English, use an imperative summary beginning
  with a lowercase verb, keep the subject at 72 characters or fewer when
  practical, and do not end it with a period.
- Base the message on the actual completed changes and milestone outcome; do
  not use vague summaries such as `update files` or `make changes`.
- Present the proposed commit message in the final response, but do not create
  the Git commit unless the user explicitly requests it.

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

### Code style

- Follow the repository `.clang-format`.
- Format all modified C and C++ files with `clang-format`.
- Prefer simple, explicit code that is easy for beginners to read.
- Avoid clever one-liners and unnecessary abstractions.
- Use braces for all non-trivial control-flow blocks.
- Prefer descriptive variable and function names.
- Keep functions reasonably small.

### Build and verification

- Parse the project configuration with
  `pio project config` after changing
  `platformio.ini`.
- Build with `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.