3 files changed, 122 insertions, 2 deletions
diff --git a/.agent/code-map.md b/.agent/code-map.md
index eb2f564..1a36542 100644
--- a/.agent/code-map.md
+++ b/.agent/code-map.md
@@ -359,8 +359,11 @@ CI (`android.yml`) triggers only on pushes to `main`. Firebase App Distribution
 ## 8. Context Tips & Gotchas
 
 ### Navigation / GPS
-- `DeviceGpsProvider` uses `FusedLocationProviderClient`. External GPS comes via NMEA TCP/UDP through `NmeaStreamManager` → `NmeaParser` → `GpsProvider` interface.
-- GPS fix is stale after 10 s — `MainViewModel` shows red "No GPS" banner.
+- `LocationService` (foreground service) uses `FusedLocationProviderClient` for Android GPS. External GPS comes via NMEA TCP/UDP through `NmeaStreamManager` → `NmeaParser`, emitted on `LocationService.nmeaGpsPositionFlow`.
+- `LocationService.recomputeBestPosition()` fuses NMEA + Android GPS: prefers NMEA if < 5 s old, falls back to Android. Result is `bestPosition: StateFlow<GpsPosition?>`.
+- `locationFlow: SharedFlow<GpsPosition>(replay=1)` carries raw Android fixes. **`replay=1` means new subscribers immediately receive the last cached position regardless of age — there is no staleness expiry.** Consumers must check `gpsData.timestampMs` if they care about age.
+- `DeviceGpsProvider` implements `GpsProvider` and has a `fixLostRunnable` (10 s timeout), but is **dead code** — it is never instantiated. `LocationService` does not use the `GpsProvider` interface. There is no "No GPS" banner.
+- Background location: `throttleLocationIfIdle()` (called on `onPause`) sends `ACTION_STOP_UPDATES` to stop `fusedLocationClient` when neither recording nor anchor-watch is active. `restoreLocationMode()` (called on `onResume`) restarts appropriate mode.
 
 ### NMEA
 - `NmeaStreamManager` handles connection lifecycle (reconnect on failure). Don't manage socket lifecycle elsewhere.
diff --git a/.agent/config.md b/.agent/config.md
index 56d9df5..376cd89 100644
--- a/.agent/config.md
+++ b/.agent/config.md
@@ -14,6 +14,7 @@ This is the primary source of truth for all AI agents working on **Nav**. These
 | `mission.md` | **Mission & Values** — Strategic goals and agent personality. |
 | `narrative.md` | **Background** — Historical context and evolution of the project. |
 | `preferences.md` | **User Prefs** — Living record of user-specific likes/dislikes. |
+| `review-intent-reality.md` | **Audit Prompt** — Structured review to find gaps between documented intent and implemented reality. Run after major merges or when a regression reveals a code-map error. |
 
 ## 2. Branch Policy — MANDATORY SESSION START ACTION
 
@@ -48,3 +49,5 @@ The repo ships a pre-commit hook in `scripts/git-hooks/pre-commit` that hard-blo
 1.  **Continuous Capture:** Agents MUST proactively update the files in ".agent/" as new decisions, patterns, or user preferences are revealed.
 2.  **No Stale Instructions:** If a workflow or technical standard evolves, the agent is responsible for reflecting that change in the Master Rulebook immediately.
 3.  **Worklog Integrity:** The ".agent/worklog.md" must be updated at the start and end of EVERY session.
+4.  **Code-Map Accuracy:** `code-map.md` must describe what the code **does**, not what was intended. If a refactor changes a class's role, removes a feature, or leaves dead code, update `code-map.md` in the same commit. Never leave a known-wrong entry — a wrong code-map is worse than no code-map.
+5.  **Intent-Reality Audit:** After any significant merge or refactor, check whether existing code-map entries, comments, and `design.md` still reflect reality. When they don't, fix them immediately. For a full audit, run the prompt in `review-intent-reality.md`.
diff --git a/.agent/review-intent-reality.md b/.agent/review-intent-reality.md
new file mode 100644
index 0000000..7df10f2
--- /dev/null
+++ b/.agent/review-intent-reality.md
@@ -0,0 +1,114 @@
+# Intent-vs-Reality Review
+
+**Purpose:** Find all places where documented intent, comments, or code-map descriptions diverge from what the code actually does. Run this whenever a significant refactor lands, before merging a long-running branch, or whenever a regression reveals a code-map inaccuracy.
+
+**How to run:** paste the prompt below into a new agent session with access to the repo. It is intentionally exhaustive — expect 30–60 min of analysis.
+
+---
+
+## Prompt
+
+You are auditing the Nav Android codebase for gaps between **documented intent** and **implemented reality**. A gap is any case where a comment, doc file, code-map entry, or TODO describes behavior that differs from what the code actually does.
+
+Work through each category below. For each finding, report:
+- **File and line** (or doc file + section)
+- **What it claims** (quote the doc/comment)
+- **What the code does** (cite the relevant lines)
+- **Severity**: `MISLEADING` (wrong, will cause future bugs), `STALE` (was true, no longer is), or `ASPIRATIONAL` (planned but not built)
+
+### Category 1 — Code-map vs implementation
+
+Read `.agent/code-map.md` sections 3 (Source Package Map) and 8 (Context Tips & Gotchas). For every class or behavior mentioned:
+
+1. Verify the class exists at the stated path.
+2. Verify the described role matches the actual implementation.
+3. Flag any class listed with a role that has been superseded or is dead code.
+
+Pay special attention to:
+- Classes listed under `gps/` — `DeviceGpsProvider` has historically been misrepresented
+- The "Navigation / GPS" gotcha section — descriptions of flow and staleness behavior
+- Any mention of flows, StateFlows, or SharedFlows — check `replay` values and whether subscribers actually receive stale data
+- Any mention of UI features (banners, dialogs, buttons) — verify they exist in layouts and are wired up
+
+### Category 2 — Dead code with documented intent
+
+Search for code that is defined but never instantiated or called. These represent features that were planned, partially built, or left behind after a refactor:
+
+1. Run: find all classes implementing an interface — check if any implementation is never constructed anywhere (grep for `= MyClass(` and `MyClass(` across all Kotlin files).
+2. Look specifically at:
+   - `gps/GpsProvider.kt` and its implementations
+   - Any `Handler` with a posted `Runnable` that looks like a timeout/watchdog
+   - Any `companion object` constant named `*_TIMEOUT_MS` or `*_THRESHOLD_MS` — verify the timeout is actually used
+3. For each dead class/method, check git log to understand if it was once wired up and was removed in a refactor (use `git log --all -S 'ClassName'` to find commits that removed references).
+
+### Category 3 — Comments that describe the wrong behavior
+
+Scan for inline comments that assert behavior (`// GPS updates every 1 Hz`, `// always fresh`, `// cleared on pause`, `// foreground only`, etc.) and verify the code around them matches the claim:
+
+1. Search for `// TODO` entries — for each one, determine if the TODO was actually completed elsewhere (the code may have been fixed but the comment not removed).
+2. Search for comments referencing specific class names, method names, or behaviors — verify those classes/methods/behaviors still exist with the described properties.
+3. Look for comments in `MainActivity.kt`, `LocationService.kt`, and `MainViewModel.kt` specifically — these are the highest-churn files.
+
+### Category 4 — Architectural invariants not enforced
+
+Read `.agent/code-map.md` section 5 (Key Architectural Invariants). For each invariant:
+
+1. Verify the invariant holds in the current code.
+2. If it was intended to be enforced by a specific mechanism (e.g., `@Synchronized`, a guard variable, a specific flow), verify that mechanism is actually in place.
+3. Flag any invariant that is stated as a rule but has no enforcement — these are regression risks.
+
+Current invariants to check:
+- Track storage source-of-truth = GPX/SAF (Room is read-cache only)
+- `getExternalFilesDir()` never used for user data
+- `NavLogger` as primary debug tool (not just Android `Log`)
+- MOB button always visible and non-dismissible
+- `InMemoryLogbookRepository` has `@Synchronized` on save/getAll/reload
+- `VoiceLogFragment` passes both `onSelect` and `onReport` to `SavedTrackAdapter`
+- MapLibre speed-color uses `Expression.step()` not `Expression.get("color")`
+- NMEA wind data is apparent, converted to true in `PerformanceViewModel`
+- All display values go through `UnitPrefs`
+
+### Category 5 — Design doc vs shipped code
+
+Read `.agent/design.md`. For any feature described as "implemented" or in a "completed" state:
+
+1. Verify the feature exists in the code.
+2. Verify the implementation matches the described design (API shape, data flow, UI layout).
+3. Flag features described as in-progress that appear to have been abandoned without a code-map update.
+
+### Category 6 — Worklog vs current state
+
+Read `.agent/worklog.md` section "Recently Completed". For each completed item:
+
+1. Spot-check that the described change is actually present in the code.
+2. Look for cases where a "completed" item was later reverted or partially undone by a subsequent merge (use `git log --all --oneline -- <file>` to trace history).
+
+---
+
+## Output format
+
+Group findings by category. Use this structure:
+
+```
+## [Category N] — [Category name]
+
+### Finding: [short title]
+- **Doc claim**: "[exact quote]" — `file:line`
+- **Code reality**: [what the code actually does] — `file:line`
+- **Severity**: MISLEADING / STALE / ASPIRATIONAL
+- **Suggested fix**: [one sentence — update the doc, delete the dead code, or implement the feature]
+```
+
+End with a **Summary** section: total findings by severity, and the top 3 highest-risk gaps (most likely to cause future bugs or agent confusion).
+
+---
+
+## After the review
+
+For each `MISLEADING` finding: fix the code-map or comment immediately in the same session. Do not leave the session with any known-wrong documentation.
+
+For `ASPIRATIONAL` findings: add a note to `.agent/worklog.md` backlog if the feature is still wanted, or delete the dead code if it is not.
+
+For `STALE` findings: update the documentation to match current reality.
+
+Commit all documentation fixes as a single commit: `"docs(agent): intent-reality audit — correct N misleading entries"`.