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

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

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.

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.

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.

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.

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.