docs: add initial project documentation

AGENTS.md

@@ -0,0 +1,81 @@
+# 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.
+