Closer/Engineering_Reference_Manual_Plan.md

Engineering Reference Manual Update Plan

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).