docs: reconcile documentation to current code state (#6)

Author: saagpatel

CLAUDE.md

@@ -15,7 +15,7 @@ Free iOS app (iPhone-only): match a photo to a geolocated historical photograph
 ## Build / Test / Run
 See IMPLEMENTATION-ROADMAP.md for full phase details and verification checklist.
 
-Current phase: **Phase 1: Core App — Camera → Match → Slider**
+Current phase: **Phase 3: Confidence UI + Polish** (Phases 0–2 complete)
 
 ## Conventions
 - Use `guard let` or `try?` with explicit fallback — force-unwraps (`!`) only inside `fatalError`/`precondition`
@@ -53,7 +53,7 @@ Afterimage is a free iOS app (iPhone-only) that matches a photo you take — or
 
 ## Current State
 
-**Phase 1: Core App — Camera → Match → Slider**
+**Phase 3: Confidence UI + Polish** (Phases 0–2 complete)
 See IMPLEMENTATION-ROADMAP.md for full phase details and verification checklist.
 
 ## Stack

DOC-RECONCILIATION.md

@@ -1,151 +1,150 @@
 # DOC-RECONCILIATION.md
 
-This file was generated by the `/doc-truth-up` documentation-reconciliation pass, which treats the
-code as read-only ground truth and edits only documentation so it reflects the repo's actual current
-state. No code was changed and no builds or tests were run. It exists so the operator can audit
-every finding in one place.
+This file was generated by the `/doc-truth-up` documentation-reconciliation pass. It treats the
+code as read-only ground truth and edits only documentation (`README.md`, `CLAUDE.md`,
+`DOC-RECONCILIATION.md`) so they reflect the repo's actual current state. No code was changed and
+no builds or tests were run. It exists so the operator can audit every finding in one place.
+
+A prior reconciliation pass ran on 2026-05-30 (HEAD `db25f8b`). That pass corrected README feature
+overclaims and CLAUDE.md stack version numbers. Those fixes are in the tree; this pass picks up
+remaining drift at HEAD `0430ce7`.
 
 ---
 
 ## Per-Claim Findings
 
-### 1. What it is
+### 1. What It Is
+
+**Status: `consistent`**
+**Evidence: verified-by-reading-code**
 
-**Status:** `consistent`
-**Evidence:** `Afterimage/App/AfterimageApp.swift` — `@main struct AfterimageApp`, `RootView`
-navigation confirms the core identity: camera → matching → slider reveal.
-`Afterimage/App/AppState.swift` — navigation state machine (`.camera`, `.matching`, `.comparison`)
-matches the overview in README and CLAUDE.md. `Afterimage/Data/Database/DatabaseManager.swift` —
-opens `photos.db` read-only via `DatabasePool`, confirming the "no backend, bundled SQLite" claim.
+README.md and CLAUDE.md accurately describe Afterimage: a free iPhone-only iOS app that matches a
+user photo to a geolocated historical photograph using a bundled SQLite index, with a draggable
+slider as the core UX. Verified against `Afterimage/App/AfterimageApp.swift` (navigation state
+machine), `Afterimage/Features/Comparison/SliderOverlayView.swift` (drag gesture + overlay),
+`Afterimage/Data/Database/DatabaseManager.swift` (read-only `DatabasePool`).
 
-No changes made.
+One feature was **missing** from README.md — city browse mode — which is fully implemented in
+`Afterimage/Features/Gallery/CitySelectorView.swift` and wired into the navigation state machine
+in `Afterimage/App/AppState.swift:84–91`. Fixed in claim 2 below.
 
 ---
 
-### 2. Current state
+### 2. Current State (Phase / Completeness)
 
-**Status:** `drifted` (three README features not implemented)
+**Status: `drifted` → fixed**
+**Evidence: verified-by-reading-code**
 
-The README Features list claimed three capabilities that do not exist in the source tree:
+Both occurrences of the "Current phase" label in `CLAUDE.md` read **Phase 1: Core App — Camera →
+Match → Slider**. Reading the source tree shows Phases 0, 1, and 2 are entirely complete:
 
-| Claimed feature | Verdict | Evidence |
-|---|---|---|
-| "Three comparison modes — draggable slider (hero), side-by-side, and animated crossfade" | **drifted** | Only `SliderOverlayView.swift` exists in `Afterimage/Features/Comparison/`. No `SideBySideView.swift` or `FadeView.swift` anywhere in the project. `ComparisonView.swift` has no mode-switching UI. |
-| "Multi-match browsing — up to 5 candidates in a horizontal thumbnail strip" | **drifted** | `AppState.swift:124–128` takes only `candidates.first` and passes one `MatchCandidate` to `ComparisonView`. `ComparisonView.swift` accepts a single `match: MatchCandidate`. No thumbnail strip UI exists. |
-| "Share sheet — exports a 1200×800 composite JPEG of then-and-now" | **drifted** | No `ShareCompositor.swift` or `ShareSheetView.swift` in the project. No share button in `ComparisonView.swift`. |
+| Phase | Status | Evidence |
+|-------|--------|----------|
+| Phase 0 — Data Pipeline | **complete** | `DataPipeline/ingest_oldnyc.py`, `ingest_wikimedia.py`, `ingest_flickr.py` (contingency), `build_index.py`, `audit_coverage.py`, `config.py` all present; `DataPipeline/output/photos.db` and staging CSVs exist |
+| Phase 1 — Core App | **complete** | All named source files present and fully implemented: `CameraView`, `CameraViewModel`, `CameraCoordinator`, `LocationService`, `SpatialQuery`, `HeadingFilter`, `ThumbnailFetcher`, `VisionRanker`, `MatchingService`, `SliderOverlayView`, `ComparisonView`; unit tests for all five core components |
+| Phase 2 — Gallery + Expanded Cities | **complete** | `GalleryPickerView.swift`, `LocationPickerView.swift` (GPS-less location picker), `CitySelectorView.swift` (city browse mode), and all 6 city centers hardcoded in `AppState.swift:28–35` |
+| Phase 3 — Confidence UI + Polish | **not started** | `ConfidenceLabel` enum exists in the model (`HistoricalPhoto.swift:66–70`) and is computed in `VisionRanker.swift`, but no badge overlay in `SliderOverlayView.swift` or `ComparisonView.swift`; no multi-match thumbnail strip; no onboarding modal anywhere in the source tree |
+| Phase 4 — Share Sheet | **not started** | No `ShareCompositor.swift` or `ShareSheetView.swift` present; no share button in `ComparisonView.swift` |
 
-Implemented and correctly described features (consistent):
-- Live camera matching — `MatchingService.swift` orchestrates the four-stage pipeline
-- Four-stage pipeline — `SpatialQuery.swift`, `HeadingFilter.swift`, `ThumbnailFetcher.swift`, `VisionRanker.swift` all exist and are wired in `MatchingService.swift`
-- Composite scoring (70%/30%) — `VisionRanker.swift` implements this exactly
-- Camera roll matching — `GalleryPickerView.swift` + `LocationPickerView.swift` handle GPS-present and GPS-absent cases
+**Changes made to `CLAUDE.md` (two occurrences):**
+- `## Build / Test / Run` section:
+  `Current phase: **Phase 1: Core App — Camera → Match → Slider**`
+  → `Current phase: **Phase 3: Confidence UI + Polish** (Phases 0–2 complete)`
+- `## Current State` block (portfolio-context region): same string, same fix.
 
-**Changes made to `README.md`:**
-- Removed: `"Three comparison modes — draggable slider (hero), side-by-side, and animated crossfade"`
-  → replaced with: `"Draggable slider — reveals the historical image beneath the present-day photo"`
-- Removed: `"Multi-match browsing — up to 5 candidates in a horizontal thumbnail strip"` (entire bullet)
-- Removed: `"Share sheet — exports a 1200×800 composite JPEG of then-and-now"` (entire bullet)
-- Updated camera roll bullet to mention the manual location picker (implemented in `LocationPickerView.swift`)
+**Change made to `README.md`:**
+Added missing bullet to Features list:
+`- **City browse mode** — explore historical photos for any of 6 covered US cities (NYC, SF, Chicago, DC, New Orleans, Boston) without taking a photo`
 
 ---
 
 ### 3. Stack
 
-**Status:** `drifted` in CLAUDE.md; `consistent` in README.md
+**Status: `consistent`**
+**Evidence: verified-by-reading-code**
 
 `Afterimage.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved` pins:
-- GRDB.swift → **7.10.0**
-- Kingfisher → **8.8.0**
-
-README.md already said "GRDB.swift 7.x" and "Kingfisher 8.x" — consistent.
+- GRDB.swift → **7.10.0** — README says "GRDB.swift 7.x", CLAUDE.md says "GRDB.swift 7.x" ✓
+- Kingfisher → **8.8.0** — README says "Kingfisher 8.x", CLAUDE.md says "Kingfisher 8.x" ✓
 
-CLAUDE.md (Tech Stack section and Portfolio Context > Stack section) said "GRDB.swift 6.x" and
-"Kingfisher 7.x" in both occurrences — one major version behind in each.
-
-**Changes made to `CLAUDE.md`:**
-- `GRDB.swift 6.x` → `GRDB.swift 7.x` (Tech Stack section, line ~9)
-- `Kingfisher 7.x` → `Kingfisher 8.x` (Tech Stack section, line ~10)
-- `GRDB.swift 6.x` → `GRDB.swift 7.x` (Portfolio Context > Stack section, line ~67)
-- `Kingfisher 7.x` → `Kingfisher 8.x` (Portfolio Context > Stack section, line ~68)
+(These version numbers were corrected by the 2026-05-30 pass and remain accurate.)
 
 ---
 
-### 4. How to run
+### 4. How to Run
 
-**Status:** `consistent`
-**Evidence:** `Afterimage.xcodeproj/` directory confirmed present (Package.resolved lives inside it).
-README Quick Start shows `open Afterimage.xcodeproj` and "Build and run on a physical iPhone."
-No build scripts to verify; build command is Xcode UI only, which is the conventional approach for
-iOS projects without a Makefile or CI script at the root.
+**Status: `consistent`**
+**Evidence: verified-by-reading-code**
 
-No changes made.
+README Quick Start documents `git clone … && open Afterimage.xcodeproj`. The Xcode project
+directory is confirmed present (`Afterimage.xcodeproj/project.xcworkspace/…/Package.resolved`
+exists). No Makefile, CI script, or other build surface exists — Xcode-only is correct for this
+project type. Prerequisites (Xcode 16+, iOS 17, physical iPhone) are unverifiable from source
+alone but are not contradicted by any file.
 
 ---
 
-### 5. Known risks
+### 5. Known Risks
 
-**Status:** `consistent` (where verifiable)
-**Evidence:** `DatabaseManager.swift:13` — `config.readonly = true` confirms the "never write to
-photos.db" rule. `AppState.swift` — no network transmissions of user data. Camera/location
-permission requests are deferred to user action, not app launch (verified in `CameraView.swift` and
-`AppState.onPhotoCaptured`). These match the Do NOT constraints in CLAUDE.md exactly.
+**Status: `consistent`** (where verifiable)
+**Evidence: verified-by-reading-code**
 
-Performance and coverage claims (e.g., "<5s matching", "≥25% grid coverage") are runtime
-assertions not checkable by reading source — marked `unverifiable-because-requires-device-or-data`.
+CLAUDE.md's risk list (read-only `photos.db`, no off-device data, deferred permission requests,
+grayscale Vision pre-processing, no Combine, Phase 0 scope gate) all match code constraints:
+- Read-only database: `DatabaseManager.swift` opens a `DatabasePool` with `readonly = true`
+- Deferred permissions: camera/location requests live in `CameraView` and `AppState.onPhotoCaptured`, not in `AfterimageApp.init()`
+- Grayscale requirement: enforced in `VisionRanker.swift`
 
-No changes made.
+Performance claims ("< 5s matching", "≥ 25% grid coverage") and physical-device behaviour are
+`unverifiable-because-requires-device-or-data` — left unchanged.
 
 ---
 
-### 6. Next move
-
-**Status:** `consistent` (roadmap accurately reflects what is and isn't built)
-**Evidence:** Cross-referencing source files against IMPLEMENTATION-ROADMAP.md phases:
-- Phase 0 (data pipeline): Python scripts not in the repo root — `DataPipeline/` directory not
-  present in the source tree. Marked `unverifiable` — pipeline may have been run externally.
-- Phase 1 (core app): All named Swift files exist and are wired correctly.
-- Phase 2 (gallery + expanded cities): `GalleryPickerView.swift`, `LocationPickerView.swift`,
-  `CitySelectorView.swift` all exist; `GalleryMatchViewModel.swift` does not (replaced by
-  `LocationPickerView.swift` + `AppState` logic — functionally equivalent).
-- Phase 3 (confidence UI, multi-match, onboarding, haptics): **Not implemented.** Confidence
-  labels exist in the data model (`MatchCandidate.confidenceLabel`) but no badge UI in
-  `ComparisonView`. Multi-match UI, onboarding modal, and haptics absent from source.
-- Phase 4 (share sheet, App Store submission): **Not implemented.** No share code present.
+### 6. Next Move
 
-CLAUDE.md says "Current Phase: Phase 1" which is the most honest current description given that
-Phase 1's core flows are built but Phase 3/4 polish items remain. This is `consistent`.
+**Status: `drifted` → addressed by phase-label fix above**
+**Evidence: verified-by-reading-code**
 
-No changes made.
+The corrected phase label in claim 2 is the "next move" signal. Concretely absent from the source
+tree (Phase 3 and 4 work):
+- `Afterimage/Features/Comparison/SideBySideView.swift` — not present
+- `Afterimage/Features/Comparison/FadeView.swift` — not present
+- `Afterimage/Features/Share/ShareCompositor.swift` — not present
+- `Afterimage/Features/Share/ShareSheetView.swift` — not present
+- Confidence badge overlay in `SliderOverlayView` / `ComparisonView` — not present
+- Multi-match thumbnail strip — not present
+- First-launch onboarding modal — not present
 
 ---
 
 ## Contradictions for Manual Review
 
-These are drifts found in files this pass is not permitted to edit. A human should apply the fixes.
+These drifts are in files outside the editable set (`IMPLEMENTATION-ROADMAP.md`,
+`APPSTORE-METADATA.md`). A human should apply the fixes.
 
 ### IMPLEMENTATION-ROADMAP.md
 
 | Location | What is wrong | One-line fix |
-|---|---|---|
-| Line 234 (`from: "6.0.0"` for GRDB.swift) | GRDB.swift is pinned at 7.10.0 in Package.resolved | Change `from: "6.0.0"` to `from: "7.0.0"` |
-| Line 238 (`from: "7.0.0"` for Kingfisher) | Kingfisher is pinned at 8.8.0 in Package.resolved | Change `from: "7.0.0"` to `from: "8.0.0"` |
-| Lines 173–186 (Swift type definitions) | `thumbnailURL: URL` and `fullResURL: URL?` — actual code (`HistoricalPhoto.swift:29,31`) uses `String` for both | Change `URL` → `String` and `URL?` → `String?` in the type definition block |
-| Lines 128–137 (SQL schema) | Schema does not include the `city TEXT` column | Add `city TEXT,` after the `lon REAL NOT NULL,` line |
-| Lines 112–114 (AfterimageTests listing) | Lists 3 test files; actual suite has 6: also `MatchingServiceTests.swift`, `DatabaseManagerTests.swift`, `TestHelpers.swift` | Add the three missing files to the listing |
-| Lines 82–92 (file structure — Comparison/) | Lists `SideBySideView.swift` and `FadeView.swift` as existing files | Remove or mark as `[planned]` — these files do not exist |
-| Lines 88–90 (file structure — Gallery/) | Lists `GalleryMatchViewModel.swift` | Remove or rename to `LocationPickerView.swift` — that is the actual file |
-| Lines 90–92 (file structure — Share/) | Lists `ShareCompositor.swift` and `ShareSheetView.swift` | Remove or mark as `[planned]` — these files do not exist |
+|----------|---------------|--------------|
+| Line ~234 — GRDB dependency | Shows `from: "6.0.0"` | Change to `from: "7.0.0"` — Package.resolved pins 7.10.0 |
+| Line ~238 — Kingfisher dependency | Shows `from: "7.0.0"` | Change to `from: "8.0.0"` — Package.resolved pins 8.8.0 |
+| Line ~63 — file structure | Source dir shown as `afterimage/` (lowercase) | Change to `Afterimage/` — actual Xcode target directory is PascalCase |
+| Lines ~105–109 — file structure | Lists `ingest_loc.py` and `ingest_nypl.py` as DataPipeline scripts | Remove both — neither file exists on disk; both sources were dropped (noted in the API Contracts section of the same document) |
+| Line ~242 — pip install command | Says `pip install aiohttp requests Pillow tqdm geojson` | Remove `Pillow` and `geojson` — `DataPipeline/requirements.txt` contains only `aiohttp`, `requests`, `tqdm` |
+| Lines ~173–180 — Swift type definitions | `thumbnailURL: URL` and `fullResURL: URL?` | Change both to `String` and `String?` — `Afterimage/Data/Models/HistoricalPhoto.swift:32–33` uses `String` |
+| Lines ~172 — Swift type definitions | `HistoricalPhoto` struct is missing `city: String?` | Add `let city: String?` between `lon` and `heading` — present in `HistoricalPhoto.swift:30` and in `DataPipeline/config.py:52` staging columns |
 
 ### APPSTORE-METADATA.md
 
 | Location | What is wrong | One-line fix |
-|---|---|---|
-| Lines 116–120 (App Review Notes) | "Tap 'Gallery' and browse the bundled historical photos" / "pick a historical photo and navigate to its exact location" misdescribes the Gallery button, which opens the user's camera roll (not a browsable historical archive) | Rewrite to: "Tap the photo icon to pick from your camera roll; if the photo has GPS data it matches immediately, otherwise a map picker appears to pin a location." |
+|----------|---------------|--------------|
+| Lines ~116–120 — App Review Notes | "Tap 'Gallery' and browse the bundled historical photos" / "Tap any photo to see its metadata and navigate to its location" — describes the Gallery button as opening a historical photo browser | Rewrite: Gallery opens the user's camera roll via `PHPickerViewController`; selecting a GPS-tagged photo triggers matching immediately; selecting a GPS-less photo shows a map pin picker |
+| Line ~68 — Support URL | `https://github.com/d/Afterimage` is a placeholder | Update to the real repo URL (`https://github.com/saagpatel/Afterimage` per README.md) |
 
 ---
 
 ## Footer
 
-- **Run date/time:** 2026-05-30 19:12:52 PDT
-- **Branch:** docs/truth-up-2026-05-30
-- **HEAD sha reconciled against:** db25f8b46d2ade91d7012dcfb0210b73672a10fb
+**Generated:** 2026-06-02 19:29:42 PDT
+**Branch:** docs/truth-up-2026-06-02
+**HEAD reconciled against:** 0430ce753d8ed96029dd527ac961a8ac6a983b5b

README.md

@@ -13,6 +13,7 @@ Afterimage matches your photo to a geolocated historical photograph from the sam
 - **Draggable slider** — reveals the historical image beneath the present-day photo
 - **Composite scoring** — 70% GPS/heading + 30% Vision similarity; labeled Strong Match, Good Match, or Nearby
 - **Camera roll matching** — any photo with GPS EXIF metadata works; manual location picker for GPS-less images
+- **City browse mode** — explore historical photos for any of 6 covered US cities (NYC, SF, Chicago, DC, New Orleans, Boston) without taking a photo
 
 ## Quick Start