docs: bring living project documentation under version control

ANALYSIS.md/ARCHITECTURE.md/PROGRESS.md and the rest of this project's
living docs have always lived one directory above this repo's root
(NFSMW_Online_Claude_workdir/*.md), so they were never actually part of
this git history despite being the authoritative record of every hook,
offset, and RE finding this branch's code is built on.

Mirrors the docs/ layout already used on native-arm32-trace-harness so
both branches reference the same file set by name, pending the actual
code merge (see PROGRESS.md's own "Repo merge pending" note).

Co-Authored-By: Claude <noreply@anthropic.com>

docs/DEBUG_MENU.md

@@ -0,0 +1,31 @@
+# DEBUG_MENU.md — On-map debug menu (Compose)
+
+Living document for the in-app debug menu — a developer-only overlay for poking at mod state while testing, starting with a money editor. Split out as its own file (matching the `LOBBY_UI_DESIGN.md` precedent) so `ARCHITECTURE.md` doesn't accumulate UI-only debug-tooling detail. Update this file whenever the debug menu gains a new panel or its wiring changes.
+
+---
+
+## 1. Purpose and scope
+
+Requested as a debugging aid, not a player-facing feature: a way to poke at mod/game state live on-device without rebuilding. First panel is a money editor. More debug panels are expected to be added here over time (same menu, more entries) rather than each getting its own ad-hoc overlay.
+
+**Explicit enable/disable mechanism**: `DebugFeatures.debugMenuEnabled` (`mpcore/src/main/java/nfs/mod/mpcore/DebugFeatures.kt`) — a single `var` flag, default `true` during active development. `GameActivityMain.onCreate` only adds the debug overlay's `ComposeView` to `mFrameLayout` when this flag is `true`, so flipping it to `false` removes the debug menu from the view hierarchy entirely (not just hidden) ahead of any release build. Chosen to live in `mpcore` (not `app`) per direct instruction, so the one gate for all debug tooling stays in the shared module rather than scattered across Activities.
+
+## 2. Activation — button on the map
+
+Reuses the exact mechanism `CarSelectionBadge` already established (`ARCHITECTURE.md` §4 / `LOBBY_UI_DESIGN.md` §1): a `ComposeView` overlay added to `mFrameLayout` above the game's `GLSurfaceView`, visibility driven by `GameEvents.onMapLoaded()` (fires via the existing, already-proven `MapTrack::HandleEvent` native hook — see `PROGRESS.md`'s `dispatchMapLoaded` history). No new native hook needed: the map-loaded signal already exists and already fires reliably.
+
+- `DebugMenuVisibility` (new, app module) — a `GameEventListener` object exposing `mapLoaded` as Compose state, same shape as `CarSelectionState` in `CarSelectionOverlay.kt`.
+- A small floating button, bottom-end corner (deliberately opposite `CarSelectionBadge`'s top-start corner so the two never overlap), appears once `mapLoaded` is true.
+- Tapping it opens the debug panel as a dialog over whatever screen is currently showing.
+
+## 3. First panel — money editor (stub, not wired to real game state)
+
+**Explicit scope decision (2026-08-19, direct user answer)**: for now this is a **stub** — a plain Compose text field + "Apply" button that only updates local Compose state (`DebugMoneyState.amount`), logged but **not** written into the game's actual memory/save state. Reason: no RE work has located the player's real cash balance (getter/setter/address) yet — `ANALYSIS.md`/`PROGRESS.md` only cover `CashReward` (a *race event's* bronze/silver/gold reward definition, §6aa/6z of `ANALYSIS.md`), not the player's own wallet/balance. Wiring this panel to the real balance is tracked as a **separate, later RE task** (find where `Profile`/`CurrentState` — both named in the `ISaveable` family, `PROGRESS.md` cont. "2026-08-06" save/profile entry — actually stores the spendable cash total, then add a native setter hook), not part of this UI work.
+
+## 4. Screen inventory
+
+| Panel | State | What it does |
+|---|---|---|
+| Money editor | **Stub** | Text field + Apply button; writes to local Compose state only, no game effect yet |
+
+More rows added here as panels are added.