Closer/Engineering_Reference_Manual_Plan.md

# Engineering Reference Manual Update Plan

**Status: ✅ COMPLETE** — all 9 batches reviewed, corrected, committed, and pushed to `dev`.

Goal: bring `docs/Engineering_Reference_Manual.md` into alignment with the current
relationship-app codebase. Verify every claim, file path, function name,
collection name, and architectural fact. Never assume.

## Approach

- **Batch-based.** Each batch covers one major section or a coherent set of
  subsections. One agent/turn per batch.
- **Evidence-first.** For every factual claim in the manual, verify against the
  repo (grep, read file, run build/test if needed).
- **Log everything.** Each batch updates this plan with findings and
  changes made.
- **Ripley coordinates.** Ripley does not code unless necessary; Bishop or
  subagents may verify builds/docs.

## Batches

### Batch 1 — Front matter + System overview + Repository layout
- Read: `## How to use this document` through `### Shared configuration`.
- Verify all directory paths under `app/src/main/java/app/closer/`,
  `functions/src/`, `functions/dist/`, `res/drawable-*`.
- Flag missing or renamed directories/files.
- Update any stale paths or naming.

### Batch 2 — Authentication, pairing, couples model
- Read: `## Authentication and pairing flow` through `### Key Cloud Functions`.
- Verify auth files, pairing flow files, `couples` collection fields,
  recovery phrase implementation.
- Cross-check `firestore.rules` for the rules described.
- Update if code diverges from doc.

### Batch 3 — E2EE model + Firestore data model
- Read: `## End-to-end encryption model` and `## Firestore data model`.
- Verify crypto files, encryption versions, collection schemas, field names.
- Check `firestore.rules` regex helpers and invariants.
- Update data model tables if collections/fields changed.

### Batch 4 — Daily question lifecycle + Cloud Functions module
- Read: `## Daily question lifecycle` and `## Cloud Functions`.
- Verify function triggers, handlers, schedules, module responsibilities.
- Cross-check `functions/src/` tree.
- Update if functions were added/removed/renamed.

### Batch 5 — Firestore security rules
- Read: `## Firestore security rules`.
- Line-by-line verify against `firestore.rules`.
- Note any rules in the file not documented, or documented rules not in file.

### Batch 6 — Billing + Notifications
- Read: `## Billing` and `## Notifications`.
- Verify RevenueCat integration files, entitlement checks, webhook handler.
- Verify notification classes, quiet hours, deep-link routing.
- Update for quiet-hours server-side suppression if doc still says local-only.

### Batch 7 — iOS-specific + Build and release
- Read: `## iOS-specific notes` and `## Build and release`.
- Verify iOS project state (is it still broken? still exists?).
- Verify build commands, secrets, ProGuard, Functions deploy commands.
- Update stale commands or iOS status.

### Batch 8 — Known landmines and recent fixes (cross-cutting)
- Read: `## Known landmines and recent fixes`.
- Verify each listed issue ID and fix matches git history and current code.
- Add any missing recent landmines (e.g., theme scanner, quiet hours server-side).
- Prune obsolete entries.

### Batch 9 — Final review, TOC update, formatting
- Update `## Table of Contents` if headings changed.
- Run markdown lint / build check if applicable.
- Final pass for consistency.

## Status tracking

| Batch | Status | Findings | Changes made |
|---|---|---|---|
| 1 | ✅ done | `core/feature/` note inaccurate (dir doesn't exist); `data/questions/` listed `QuestionDao` but it's in `data/local/` | Corrected `core/feature/` note; moved `QuestionDao` to `data/local/`; kept `QuestionJsonParser` in `data/questions/`; updated older-description note. |
| 2 | ✅ done | No anonymous sign-in or account linking in code; Android uses legacy Google Sign-In SDK (idToken), not Credential Manager; `encryptionMigrationUsers` field does not exist | Removed anonymous auth and account-linking claims; corrected Google Sign-In description; removed `encryptionMigrationUsers` from couples model and added note that `encryptionVersion` is always `2`. |
| 3 | ✅ done | `/users/{uid}` model missing `sex`, `partnerId`, `plan`, `lastActiveAt`, notification prefs, quiet-hours, `fcmToken`; `hasPremium` is not a real root field (premium lives in `/entitlements/premium`); `/couples/{coupleId}` listed non-existent `encryptionMigrationUsers`; date plan fields wrong; date plan preference fields wrong; bucket list fields wrong; missing `/answers/{userId}/secure/{doc}` for schemaVersion 2 | Updated `/users/{uid}` to full allowlist; removed `hasPremium` root field and added note about `/entitlements/premium`; removed `encryptionMigrationUsers`; corrected date plan, preference, and bucket list fields; added `secure` subdoc to daily-question model. |
| 4 | ✅ done | Handler table missing functions (`syncEntitlement`, `sendDailyQuestionProactiveReminder`, `sendReengagementReminder`, `sendChallengeDayReminders`, `unlockDueMemoryCapsules`, `sendGentleReminderCallable`, `onEntitlementChanged`, `onAnswerRevealed`, `onCoupleLeave`, `leaveCoupleCallable`, `submitOutcomeCallable`, `scheduledOutcomesReminder`, `onGamePartFinished`, `notifyOnDateMatch`); still listed removed `health` endpoint and old name `createDateMatchOnMutualLove`; webhook section said 200-ack-before-process (now process-before-ack); `scheduledOutcomesReminder` timezone wrong | Removed `health`; added all current functions and corrected `notifyOnDateMatch`; updated module responsibilities; corrected webhook to process-before-ack with 500-on-failure; fixed schedule timezones (only `assignDailyQuestion`, `sendDailyQuestionProactiveReminder`, `sendReengagementReminder` use `America/Chicago`). |
| 5 | ✅ done | `users/{uid}` section still described non-existent `hasPremium` root field; `couples/{coupleId}` section said all client writes denied (create is shape-restricted but possible); helper paragraph listed non-existent `isStartingEncryptionMigration`/`isCompletingOwnEncryptionMigration` | Updated `users/{uid}` to clarify `plan` is client-written and premium lives in `/entitlements/premium`; corrected couples create/update description; removed migration-helper references. |
| 6 | ✅ done | Billing Webhook flow still said "ack 200 then process" (process-before-ack was fixed in Batch 4 but Billing section had stale duplicate); missing `CouplePremiumChecker`; Notifications said quiet-hours server-side suppression not implemented (it is, via `recipientInQuietHours`); Notifications said `notification_queue` reads denied for clients (Android reads it for Together feed); `onEntitlementChanged` handler table description said it mirrors `plan` (it notifies partner instead) | Updated Billing webhook flow; added `CouplePremiumChecker` note; corrected quiet-hours to server-side-implemented; corrected `notification_queue` read claim; fixed `onEntitlementChanged` description. |
| 7 | ✅ done | iOS E2EE gap paragraph said iOS create invite writes an invite with null E2EE fields (server now rejects empty data, so no invite is created); ProGuard section claimed Tink reflection paths are kept (they are not in current rules) | Updated iOS create-invite consequence to "rejected by server"; clarified ProGuard does not currently keep Tink. |
| 8 | ✅ done | Theme landmine entry said C-ART-EDGE-002 still open (R13 fixed it); missing the mandatory `theme-scan.sh` Pass C pre-check | Updated theme landmine to mark C-ART-EDGE-002 closed and document `scripts/theme-scan.sh` as mandatory pre-check. |
| 9 | ✅ done | TOC incorrectly nested `Premium-gated features` under Notifications; broken anchor `[iOS E2EE gap](#ios-e2ee-gap)`; Repository layout still claimed iOS creates v0 couples | Removed misplaced TOC nesting; fixed broken anchor; corrected iOS Repository layout claim to "pairing fails". |

## Notes

- If a section is found to be mostly correct, still spot-check a few claims.
- If a section is wildly out of date, rewrite it and note the divergence.
- Commit after each batch (per Git Discipline Rules).