docs: add initial project documentation

PLANS.md

@@ -0,0 +1,499 @@
+# maze32 Implementation Plan
+
+## Plan rules
+
+1. Milestones may be planned and added in batches.
+2. Milestone numbering starts at 1 and increases without gaps. Headings use the
+   zero-padded form `Milestone 001`, `Milestone 002`, and so on.
+3. Milestones are executed strictly in ascending numerical order. Work on a
+   milestone may begin only after every preceding milestone is `COMPLETE`.
+4. At most one milestone may have status `IN_PROGRESS`.
+5. A newly discovered milestone is appended to the end of the plan. Existing
+   milestone numbers and execution order are not changed without explicit
+   project-owner approval.
+6. Every milestone contains an objective, scope, deliverables, acceptance
+   criteria, evidence, and status.
+7. Allowed statuses are `NOT_STARTED`, `IN_PROGRESS`, `BLOCKED`, and `COMPLETE`.
+8. A milestone may be marked `COMPLETE` only when every acceptance criterion is
+   satisfied and concrete evidence is recorded in the milestone.
+9. Evidence must identify the command, test result, inspected artifact, or
+   hardware observation that demonstrates completion. Statements such as
+   "implemented" or "looks correct" are not sufficient evidence.
+10. A `NOT_STARTED` milestone explicitly records that completion evidence is
+    not yet available. Expected evidence may be listed in advance.
+11. If later work invalidates recorded evidence, reopen the affected milestone
+   and change its status before continuing.
+12. All project documentation, milestone text, source comments, test names, and
+   user-facing diagnostic messages are written in English.
+
+## Milestone 001 — Requirements and technical baseline
+
+**Status:** `COMPLETE`
+
+### Objective
+
+Establish a consistent, implementation-ready product specification,
+architecture, board passport, build profile, and Flash layout without modifying
+the read-only project sources.
+
+### Scope
+
+- Consolidate the agreed gameplay, browser, lobby, observer, reconnection, and
+  Wi-Fi provisioning requirements.
+- Establish the ESP32-C6/ESP-IDF/PlatformIO baseline inherited from Battleship.
+- Resolve the stale 2 MB versus confirmed 4 MB Flash configuration.
+- Define the authoritative-server architecture and verification boundaries.
+- Establish the sequential milestone and evidence policy.
+
+### Deliverables
+
+- `MVP.md`
+- `ARCHITECTURE.md`
+- `PLANS.md`
+- `AGENTS.md`
+- `docs/BOARD_PASSPORT.md`
+- `platformio.ini`
+- `partitions.csv`
+- `sdkconfig.defaults`
+
+### Acceptance criteria
+
+1. All canonical project documentation is in English.
+2. `MVP.md` captures all agreed roles, gameplay rules, networking behavior,
+   technical constraints, exclusions, and acceptance criteria.
+3. `ARCHITECTURE.md` defines server authority, component boundaries, state
+   machines, role-specific projection, protocol direction, storage, and
+   verification strategy.
+4. The build profile pins PlatformIO `espressif32@7.0.1`, ESP-IDF, the compatible
+   `esp32-c6-devkitm-1` profile, and 4 MB Flash.
+5. The partition layout is contiguous and ends exactly at `0x400000`.
+6. `sdkconfig.defaults` explicitly selects 4 MB Flash and 16 LwIP sockets.
+7. The board passport matches the canonical configuration and does not claim an
+   unverified physical board model, GPIO mapping, LED, or PSRAM.
+8. No file under `sources/` is modified.
+9. PlatformIO can parse and resolve the canonical project configuration.
+
+### Evidence
+
+- `MVP.md` contains the complete English product and acceptance specification.
+- `ARCHITECTURE.md` contains the English runtime, component, state-machine,
+  protocol, memory, failure, and verification contracts.
+- `platformio.ini` resolves the environment `esp32-c6-mini` with
+  `espressif32@7.0.1`, ESP-IDF, explicit 4 MB build/upload size, `partitions.csv`,
+  LittleFS, and `sdkconfig.defaults`.
+- Running `/home/sasa/.platformio/penv/bin/pio project config` successfully
+  parsed and printed the canonical configuration. PlatformIO subsequently
+  emitted a sandbox-local telemetry cache permission warning during process
+  shutdown; it did not prevent configuration parsing.
+- Static partition arithmetic verified that the 2 MiB factory application ends
+  at `0x210000` and the 1,984 KiB LittleFS partition ends at `0x400000`.
+- `sdkconfig.defaults` contains `CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y` and
+  `CONFIG_LWIP_MAX_SOCKETS=16`.
+- `docs/BOARD_PASSPORT.md` records the confirmed ESP32-C6FH4, 4 MB Flash,
+  no-required-PSRAM baseline and the remaining explicit hardware unknowns.
+- Canonical files were created outside `sources/`; the reference files under
+  `sources/` were not edited.
+
+### Completion note
+
+Milestone 001 establishes documentation and configuration only. It does not
+claim that firmware source code exists, that a firmware image builds, or that
+the target board has passed runtime tests. Those claims require evidence in
+later milestones.
+
+## Milestone 002 — Firmware skeleton and reproducible build
+
+**Status:** `NOT_STARTED`
+
+### Objective
+
+Create the smallest maintainable ESP-IDF firmware and web-asset skeleton that
+builds reproducibly with the locked platform and partition configuration.
+
+### Scope
+
+- Establish firmware, component, test, web, and script directories.
+- Add startup logging, version information, and a minimal health state.
+- Mount LittleFS and serve a minimal static page.
+- Implement deterministic compression and filesystem-image packaging for web
+  assets.
+- Add build-time application and filesystem size checks.
+
+### Deliverables
+
+- Minimal bootable firmware source tree.
+- Minimal static web application.
+- Web-asset compression and LittleFS packaging script.
+- Host-test entry point for portable code.
+- Documented build, filesystem-build, upload, and monitor commands.
+
+### Acceptance criteria
+
+1. A clean PlatformIO build succeeds with the locked environment.
+2. The application image fits the 2 MiB factory partition.
+3. The LittleFS image fits the 1,984 KiB filesystem partition.
+4. Web-asset generation is deterministic and does not require manual edits.
+5. The firmware boots on the target board, mounts LittleFS, and reports its
+   version and health state.
+
+### Evidence
+
+Completion evidence is not yet available because this milestone has not
+started. Required evidence includes clean build output, image sizes, asset
+reproducibility checks, and a target-board boot log.
+
+## Milestone 003 — Wi-Fi provisioning and persistent configuration
+
+**Status:** `NOT_STARTED`
+
+### Objective
+
+Implement station-first Wi-Fi operation with NVS persistence and a fallback
+access-point provisioning flow.
+
+### Scope
+
+- Versioned NVS configuration storage.
+- Station connection using saved credentials.
+- Fallback access point when configuration is missing or connection fails.
+- Browser flow to scan, configure, save, and retry an existing network.
+- Safe handling of invalid credentials and configuration reset.
+
+### Deliverables
+
+- Persistent configuration component.
+- Network manager and provisioning state machine.
+- Provisioning HTTP interface.
+- Automated configuration tests and on-device recovery procedure.
+
+### Acceptance criteria
+
+1. First boot exposes the fallback provisioning interface.
+2. Valid credentials are stored in NVS and used after reboot.
+3. Failed station connection returns to a usable fallback access point.
+4. Invalid requests cannot corrupt stored configuration.
+5. Network reconfiguration cannot leave an active game silently running.
+
+### Evidence
+
+Completion evidence is not yet available because this milestone has not
+started. Required evidence includes NVS tests and target-board logs for first
+boot, successful station connection, reboot persistence, and fallback recovery.
+
+## Milestone 004 — HTTP, WebSocket, sessions, and lobby
+
+**Status:** `NOT_STARTED`
+
+### Objective
+
+Provide the bounded network and session layer required for two players, four
+observers, and an owner-controlled lobby.
+
+### Scope
+
+- HTTP application delivery and diagnostic endpoint.
+- Versioned WebSocket envelope, parser, validation, and bounded queues.
+- Temporary session-token creation and browser refresh restoration.
+- Unique player names and humorous name suggestions.
+- Two player slots, four observer slots, and Player 1 start authority.
+- Lobby snapshots, readiness, and the authoritative `3-2-1` countdown.
+
+### Deliverables
+
+- HTTP and WebSocket gateway components.
+- Session and lobby services.
+- Protocol schemas and protocol tests.
+- Minimal browser lobby UI and non-browser protocol test client.
+
+### Acceptance criteria
+
+1. Two players and four observers can connect concurrently within fixed limits.
+2. Duplicate player names and excess role claims are rejected safely.
+3. Page refresh restores the same session and player slot.
+4. Only Player 1 can start, and only with both player slots occupied.
+5. Malformed, oversized, unauthorized, and stale messages do not mutate state.
+6. Both players receive one authoritative countdown and activation instant.
+
+### Evidence
+
+Completion evidence is not yet available because this milestone has not
+started. Required evidence includes protocol-test output, six-client connection
+results, session restoration tests, and lobby authorization tests.
+
+## Milestone 005 — Symmetric maze generation and validation
+
+**Status:** `NOT_STARTED`
+
+### Objective
+
+Generate connected, cyclic, reproducible, 180-degree symmetric mazes with fair
+object placement and bounded memory use.
+
+### Scope
+
+- Compact configurable maze representation.
+- Seeded generation for the default `128 x 64` map.
+- Cycles, alternative paths, and multiple cross-half passages.
+- Symmetric starts, keys, exits, compass cells, landmarks, and vision artifacts.
+- Reachability, symmetry, collision, and fairness validation.
+- Bounded regeneration when a candidate fails validation.
+
+### Deliverables
+
+- Portable maze generator and validator.
+- Deterministic host-side test suite over a large seed set.
+- Diagnostic generation metrics and failure reports.
+
+### Acceptance criteria
+
+1. The same configuration and seed always produce the same valid maze.
+2. Every tested map is fully reachable and rotationally symmetric.
+3. Every tested map contains cycles and multiple cross-half connections.
+4. Player-relative starts and required objects have equal symmetric metrics.
+5. Keys are outside their owners' initial views.
+6. Default generation fits the agreed RAM and runtime budgets without per-cell
+   heap allocation.
+
+### Evidence
+
+Completion evidence is not yet available because this milestone has not
+started. Required evidence includes deterministic seed-test results, validator
+statistics, memory measurements, and representative generated maps.
+
+## Milestone 006 — Authoritative movement and visibility core
+
+**Status:** `NOT_STARTED`
+
+### Objective
+
+Implement deterministic player movement, command ordering, cooldowns, and
+server-enforced role-specific visibility.
+
+### Scope
+
+- Serial authoritative command queue and sequence numbers.
+- Orthogonal one-cell movement and wall rejection.
+- Independent player actions with configurable server cooldown.
+- Shared-cell occupancy and meeting detection.
+- Chebyshev-radius visibility with walls that do not occlude.
+- Player-specific projections and complete observer projections.
+
+### Deliverables
+
+- Portable game-state and movement engine.
+- View projector with fog-of-war security tests.
+- Movement, cooldown, ordering, collision, and visibility tests.
+
+### Acceptance criteria
+
+1. Accepted inputs move exactly one valid orthogonal cell.
+2. Invalid, premature, or rate-limited commands do not mutate state.
+3. Both players may occupy the same cell and generate one meeting event.
+4. Player payloads contain no hidden cells, objects, or stale opponent state.
+5. Observer payloads contain the complete current state.
+6. Radius-three and radius-six projections match the documented formula at
+   walls and map boundaries.
+
+### Evidence
+
+Completion evidence is not yet available because this milestone has not
+started. Required evidence includes host-test output, serialized payload
+inspection, and deterministic command-order tests.
+
+## Milestone 007 — Keys, artifacts, compasses, exits, and results
+
+**Status:** `NOT_STARTED`
+
+### Objective
+
+Complete the authoritative gameplay mechanics and terminal match outcomes.
+
+### Scope
+
+- One-slot key inventory, pickup, voluntary drop, and sabotage.
+- Automatic return of keys to their owners when players meet.
+- Owner-only key and exit restrictions.
+- One-use vision artifacts lasting ten successful moves.
+- Stationary compass activation and exit-direction hints.
+- Exit opening, outward victory move, 200 ms draw window, and result state.
+
+### Deliverables
+
+- Gameplay object and result systems.
+- Deterministic edge-case and simultaneous-event tests.
+- Role-specific events for inventory, hints, effects, and results.
+
+### Acceptance criteria
+
+1. Inventory and ground-key state never duplicate or lose a key.
+2. Meeting behavior returns or swaps carried keys atomically.
+3. A player cannot use the opponent's key or exit to win.
+4. Vision effects last exactly ten successful moves and ignore failed moves.
+5. Compass activation points toward only the activating player's own exit.
+6. Victory requires the outward move, and exits within 200 ms produce a draw.
+
+### Evidence
+
+Completion evidence is not yet available because this milestone has not
+started. Required evidence includes complete mechanic tests and timestamped
+result-window tests.
+
+## Milestone 008 — Player browser experience
+
+**Status:** `NOT_STARTED`
+
+### Objective
+
+Deliver the complete responsive player interface without moving game authority
+into the browser.
+
+### Scope
+
+- Name selection, lobby, countdown, running, paused, and result screens.
+- Maze viewport and visual landmarks.
+- Keyboard movement and touchscreen swipes.
+- Accessible drop-key action.
+- Inventory, vision duration, compass hint, connection, and error feedback.
+- Session restoration after page refresh.
+
+### Deliverables
+
+- Responsive browser application and compressed production assets.
+- Browser interaction tests for desktop and mobile input.
+- Accessibility and viewport behavior checks.
+
+### Acceptance criteria
+
+1. Keyboard and swipe actions produce equivalent server commands.
+2. The client renders only state received in the player projection.
+3. Hidden and previously seen cells are not retained on screen.
+4. Inventory, effects, hints, pause, and results are unambiguous.
+5. Refresh restores the active player without changing position or inventory.
+6. The production asset image fits its LittleFS partition.
+
+### Evidence
+
+Completion evidence is not yet available because this milestone has not
+started. Required evidence includes browser-test output, desktop/mobile visual
+checks, refresh recovery results, and filesystem image size.
+
+## Milestone 009 — Observer mode and disconnect recovery
+
+**Status:** `NOT_STARTED`
+
+### Objective
+
+Complete the read-only full-map observer experience and reliable player pause
+and reconnect behavior.
+
+### Scope
+
+- Full-map observer rendering with player and object updates.
+- Observer access without a password and strict read-only authorization.
+- Player disconnect detection and authoritative pause.
+- Session reattachment and 60-second monotonic deadline.
+- Timeout draw and observer-independent match continuity.
+
+### Deliverables
+
+- Observer browser mode.
+- Pause/reconnect state-machine integration.
+- Authorization, reconnect, refresh, and timeout tests.
+
+### Acceptance criteria
+
+1. Four observers can view the complete live state without control authority.
+2. Observer disconnects do not pause or mutate a match.
+3. Either player disconnect immediately pauses gameplay and effect progression.
+4. Reconnection within 60 seconds restores and resumes the same state.
+5. Reconnection timeout ends the match in a draw.
+6. Observer attempts to send mutation commands are rejected and audited.
+
+### Evidence
+
+Completion evidence is not yet available because this milestone has not
+started. Required evidence includes role-authorization tests, four-observer
+browser evidence, and timed reconnect/timeout scenarios.
+
+## Milestone 010 — On-device integration and resource hardening
+
+**Status:** `NOT_STARTED`
+
+### Objective
+
+Demonstrate that the integrated system remains correct and responsive within
+the ESP32-C6 Flash, RAM, socket, and network limits.
+
+### Scope
+
+- Full firmware and LittleFS production build.
+- Two-player plus four-observer load testing.
+- Heap, largest-block, socket, queue, latency, and disconnect measurements.
+- Slow-client backpressure and malformed-message stress.
+- Station and fallback-access-point integration tests.
+- Long-running match and repeated-match stability.
+
+### Deliverables
+
+- On-device integration test procedure and results.
+- Resource budget report.
+- Fixed limits and defensive failure behavior.
+
+### Acceptance criteria
+
+1. Application and filesystem images fit their partitions with recorded margin.
+2. Six simultaneous clients remain connected and responsive on target hardware.
+3. Slow or malformed clients cannot exhaust memory or block player processing.
+4. Heap and largest free block remain stable across repeated matches.
+5. Station reconnect, provisioning fallback, and browser recovery work on the
+   physical device.
+6. No test relies on PSRAM or an unverified GPIO.
+
+### Evidence
+
+Completion evidence is not yet available because this milestone has not
+started. Required evidence includes production build reports, physical-device
+logs, six-client load results, memory graphs or samples, and repeated-match
+stress results.
+
+## Milestone 011 — Gameplay tuning and MVP acceptance
+
+**Status:** `NOT_STARTED`
+
+### Objective
+
+Tune the game to its target experience and demonstrate every MVP acceptance
+criterion on the release candidate.
+
+### Scope
+
+- Tune movement cooldown, maze balance thresholds, landmarks, artifact density,
+  and compass placement.
+- Measure key-search and exit-search difficulty.
+- Run representative human playtests targeting approximately five minutes.
+- Execute the complete MVP acceptance suite and document known limitations.
+- Produce the reproducible release image and matching web filesystem image.
+
+### Deliverables
+
+- Locked MVP gameplay configuration.
+- Playtest and balance report.
+- MVP acceptance report mapped to `MVP.md`.
+- Release build artifacts and version record.
+
+### Acceptance criteria
+
+1. Key discovery is demonstrably no easier than the subsequent exit search
+   under the agreed metrics and playtest evidence.
+2. Representative completed matches normally target approximately five minutes
+   without a hard match timer.
+3. Every acceptance criterion in `MVP.md` has recorded passing evidence or an
+   explicitly approved deviation.
+4. The final firmware and web images build reproducibly and fit the target.
+5. No unresolved defect prevents the two-player or observer MVP flows.
+
+### Evidence
+
+Completion evidence is not yet available because this milestone has not
+started. Required evidence includes playtest data, the mapped acceptance report,
+final build hashes and sizes, and project-owner approval of any deviations.