docs: update documentation plans with wearable companion requirements and current implementation details

Author: Lalit Sharma

documents/planning/01-documentation-plan.md

@@ -22,6 +22,8 @@ Establish a maintainable documentation set that explains:
   - End-user behavior, states, and interaction model.
 - `documents/high-level/development-workflow.md`
   - Setup, scripts, monorepo workflow, and current engineering constraints.
+- `documents/high-level/wearable-companion-requirements.md`
+  - Wearable companion behavior scope, acceptance criteria, and constraints.
 
 ### Low-Level Documentation
 - `documents/low-level/data-contracts.md`
@@ -30,6 +32,8 @@ Establish a maintainable documentation set that explains:
   - Computation stages, math helpers, root solving, and output derivation.
 - `documents/low-level/mobile-app-internals.md`
   - React Native state model, handlers, and UI-to-engine integration details.
+- `documents/low-level/wearable-companion-technical-design.md`
+  - Phone/watch data-layer contracts, payload flow, and renderer behavior.
 
 ## Documentation Standards
 
@@ -49,6 +53,5 @@ Update docs whenever any of these change:
 
 ## Open Gaps Identified
 
-- Test strategy is not yet implemented (`test` scripts are placeholders).
-- Linting strategy is not yet implemented (`lint` scripts are placeholders).
+- Documentation command references can still drift from real root scripts (`dev:mobile`, `typecheck`, `lint`, `test`, `test:ci`, `coverage:gate`).
 - `deltaTSecondsApprox` exists but is not currently used by `computeCircumstances`.

documents/planning/in-app-alarm-rework-plan.md

@@ -1,14 +1,28 @@
 # In-App Alarm Rework Plan (No Native Clock Export)
 
-Last updated: 2026-02-20  
-Status: Proposed
+Last updated: 2026-02-27  
+Status: Implemented in code; focused physical-device QA and final cleanup pending
 
 ## 1. Goal
 
 Use a hybrid model:
 - background local notifications for eclipse-level reminders (`T-1h`, `T-10m`)
 - foreground in-app alarms for fast, second-level event countdown guidance (`a1`, `a2`)
 
+## 1.1 Current Implementation Snapshot (2026-02-27)
+
+Implemented:
+1. `Notification Settings` rename to `Notification/Alarm Settings`.
+2. Persisted `a1`/`a2` settings with range checks and `a2 < a1` validation.
+3. Per-eclipse master toggle (`Enable alarms and reminders for this eclipse`) with per-event toggle preservation.
+4. Foreground in-app alarm engine (`a1` phrase, `a2` countdown, terminal event phrase).
+5. Fixed per-eclipse background reminders (`T-1h`, `T-10m`) anchored to first valid contact.
+6. Automated regression coverage for alarm timing, in-app engine behavior, and reminder scheduling.
+
+Still pending:
+1. Full physical-device manual verification pass for the matrix in `## 10. Test Strategy`.
+2. Final notification-layer hardening called out in tracker items (for example private `expo-notifications/build/*` import cleanup).
+
 ## 2. Requested Behavior
 
 1. Per-eclipse alarm enable/disable toggle.

documents/planning/photography-guide-plan.md

@@ -1,6 +1,6 @@
 # Photography Guide Page Plan
 
-Last updated: 2026-02-26  
+Last updated: 2026-02-27  
 Status: In progress (`Phase 1-3` complete, `Phase 4` partially complete)
 
 ## 1. Goal
@@ -45,7 +45,7 @@ Pending:
 
 ## 4. Distribution Rules
 
-Given selected `n` in `{3,5,7,9,11}`:
+Given selected `n` in `{3,5,7,9}`:
 
 1. `n` is odd and always includes one photo at `MAX`.
 2. Let `k = (n - 3) / 2`.

documents/planning/release-plan-eas.md

@@ -8,11 +8,12 @@
 ## Current Baseline
 
 - First public Android release is manual.
-- App version: `1.0.0`.
+- Current mobile version source is `apps/mobile/package.json` (currently `1.1.40`).
 - EAS project ID: `a29a7662-96be-4509-a79e-fbe4b5dac1ff`.
 - Build profile for stores: `production` in `apps/mobile/eas.json` (`autoIncrement: true`).
-- Runtime policy: `runtimeVersion` is tied to app version in `apps/mobile/app.json`.
+- Runtime policy: `version` and `runtimeVersion` are derived in `apps/mobile/app.config.ts` from `apps/mobile/package.json`.
 - GitHub workflow path for builds is self-hosted macOS (`.github/workflows/eas-build.yml`).
+- Store submit job runs automatically only when `apps/mobile/package.json` semver is greater than the latest `vX.Y.Z` tag.
 
 ---
 
@@ -40,15 +41,15 @@
   - `GOOGLE_MAPS_ANDROID_API_KEY`: Google Cloud -> `APIs & Services -> Credentials -> API key` (restrict to Android app package/SHA-1 and Maps SDK for Android API).
   - `APPSTORE_ISSUER_ID` / `APPSTORE_API_KEY_ID` / `APPSTORE_API_PRIVATE_KEY`: App Store Connect -> `Users and Access -> Integrations -> App Store Connect API` (Team API key; paste full `.p8` contents for private key).
   - `GOOGLE_PLAY_SERVICE_ACCOUNT_JSON`: Play Console -> `Setup -> API access` (link GCP project/service account) + Google Cloud service account JSON key.
-- Detailed acquisition steps for every secret are documented in `documents/self-hosted-macos-runner.md` under `## 5. Repo secrets needed`.
+- Detailed acquisition steps for every secret are documented in `documents/planning/self-hosted-macos-runner.md` under `## 5. Repo secrets needed`.
 - GitHub Release publishing uses workflow `GITHUB_TOKEN` (`contents: write` permission configured in `.github/workflows/eas-build.yml`).
   - You do not create this token manually. GitHub injects it automatically for every workflow run.
   - In workflows it is available as `${{ secrets.GITHUB_TOKEN }}` (or `github.token` context).
   - If release creation fails with permission errors, check: `Settings -> Actions -> General -> Workflow permissions` and allow write access for the repository/organization policy.
   - Only use a PAT secret if org policy prevents write-capable `GITHUB_TOKEN`.
 - Store listing metadata is kept current in:
-  - `documents/store-metadata.md`
-  - `documents/store-privacy-declarations.md`
+  - `documents/reference/store-metadata.md`
+  - `documents/reference/store-privacy-declarations.md`
 - Required checks pass locally: `pnpm typecheck`, `pnpm lint`, `pnpm test`.
 
 ---
@@ -63,12 +64,11 @@
 
 ### 2) Versioning
 
-- Bump `apps/mobile/package.json` -> `version` (for example: `1.0.1`).
-- Bump `apps/mobile/app.json` -> `expo.version` to the same value.
-- Bump `apps/mobile/app.json` -> `expo.runtimeVersion` to the same value.
-- Release workflow enforcement (`submit: true`):
+- Bump `apps/mobile/package.json` -> `version` (for example: `1.1.41`).
+- Do not set `expo.version` or `expo.runtimeVersion` in `apps/mobile/app.json`; both are derived from package version in `apps/mobile/app.config.ts`.
+- Release workflow enforcement (`submit` job):
   - Version must be valid `x.y.z`.
-  - `package.json` version, `expo.version`, and `expo.runtimeVersion` must match.
+  - `apps/mobile/app.json` must not define `expo.version` or `expo.runtimeVersion`.
   - New version must be greater than the latest Git tag in `vX.Y.Z` format.
 - Keep `android.versionCode` and `ios.buildNumber` managed by EAS `production.autoIncrement` unless a manual override is needed.
 
@@ -85,24 +85,31 @@ pnpm test
 From repo root:
 
 ```bash
-pnpm -C apps/mobile exec eas build --profile production --platform ios --local
-pnpm -C apps/mobile exec eas build --profile production --platform android --local
+pnpm -C apps/mobile exec eas build --profile production --platform ios --local --non-interactive
+pnpm -C apps/mobile exec eas build --profile production --platform android --local --non-interactive
+pnpm -C apps/mobile exec eas build --profile production-apk --platform android --local --non-interactive
+pnpm -C apps/mobile exec eas build --profile production-wear --platform android --local --non-interactive
+pnpm -C apps/mobile exec eas build --profile production-wear-apk --platform android --local --non-interactive
 ```
 
 Android-only:
 
 ```bash
-pnpm -C apps/mobile exec eas build --profile production --platform android --local
+pnpm -C apps/mobile exec eas build --profile production --platform android --local --non-interactive
+pnpm -C apps/mobile exec eas build --profile production-apk --platform android --local --non-interactive
+pnpm -C apps/mobile exec eas build --profile production-wear --platform android --local --non-interactive
+pnpm -C apps/mobile exec eas build --profile production-wear-apk --platform android --local --non-interactive
 ```
 
 ### 5) Submit binaries to stores
 
 Option A: via GitHub Actions submit job (default)
-- Run `.github/workflows/eas-build.yml` with `submit: true` and `platform: ios|android|all`.
+- Push release commit to `main` (or run `workflow_dispatch`) after version bump.
 - The submit job uploads:
   - iOS `.ipa` to App Store Connect via `apple-actions/upload-testflight-build@v3`
   - Android `.aab` to Google Play via `r0adkll/upload-google-play@v1`
-- The same job also creates a GitHub Release `vX.Y.Z` and attaches generated artifacts (`ios.ipa`, `android.aab` for selected platform).
+  - Wear OS `.aab` to Google Play internal track (non-blocking; pipeline continues if this upload fails)
+- The same job also creates a GitHub Release `vX.Y.Z` and attaches generated artifacts (`ios.ipa`, phone `android.aab` + `android.apk`, wear `wear.aab` + `wear.apk`).
 
 Option B: manual direct upload from local machine
 - iOS: upload `.ipa` with Transporter or `xcrun altool`.
@@ -126,13 +133,13 @@ pnpm -C apps/mobile exec eas submit --platform android --path /absolute/path/to/
 
 - Use `.github/workflows/eas-build.yml` for repeatable release execution.
 - Workflow runs on your self-hosted macOS runner.
-- Trigger `workflow_dispatch` with:
-  - `platform: android` or `all`
-  - `submit: true` when ready to upload automatically after build
+- Build job runs on every push to `main` and on `workflow_dispatch`.
+- Submit job runs automatically when release gate detects `apps/mobile/package.json` version > latest `vX.Y.Z` tag.
+- Use `workflow_dispatch` for dry-run validation; without a version bump, submit is skipped.
 - Keep required secrets configured:
   - `EXPO_TOKEN` for build
   - `APPSTORE_ISSUER_ID`, `APPSTORE_API_KEY_ID`, `APPSTORE_API_PRIVATE_KEY` for iOS upload
-  - `GOOGLE_PLAY_SERVICE_ACCOUNT_JSON` for Android upload
+  - `GOOGLE_PLAY_SERVICE_ACCOUNT_JSON` for Android + Wear uploads
 - Optional for EAS Submit fallback:
   - `EXPO_APPLE_ID` (iOS only)
 
@@ -172,11 +179,11 @@ Rules:
 ## Quick Checklist (Per Release)
 
 - [ ] Changelog updated
-- [ ] Version updated (`app.json`, `package.json`)
+- [ ] Version updated (`apps/mobile/package.json`)
 - [ ] Typecheck/lint/test passed
 - [ ] Local build completed
-- [ ] Store upload completed (iOS + Android as applicable)
+- [ ] Store upload completed (iOS + Android, and Wear where applicable)
 - [ ] GitHub Release created with downloadable artifacts
 - [ ] Release notes entered in store consoles
 - [ ] Rollout started and monitored
-- [ ] Post-release verification done on physical Android + iOS devices
+- [ ] Post-release verification done on physical Android + iOS devices (and Wear device when applicable)

documents/planning/self-hosted-macos-runner.md

@@ -1,6 +1,6 @@
 # Self-Hosted macOS Runner Setup (Mac mini)
 
-This project can build both iOS and Android on your own Mac mini using GitHub Actions self-hosted runners.
+This project can build iOS, Android (phone), and Android Wear artifacts on your own Mac mini using GitHub Actions self-hosted runners.
 The updated workflows run on the label set:
 
 - `self-hosted`
@@ -202,7 +202,7 @@ Notes:
 
 1. `EXPO_TOKEN` is required for local `eas build --local` in CI.
 2. Store upload credentials are injected via GitHub secrets; no credential files need to live on the runner filesystem for pipeline submit.
-3. Keep `submit` job gated by the `production` environment approval in GitHub.
+3. Submit execution is gated by release version logic (`apps/mobile/package.json` semver must be greater than latest `vX.Y.Z` tag).
 4. GitHub Release creation uses `GITHUB_TOKEN` with `contents: write` permission (set in `.github/workflows/eas-build.yml`).
    - You do not add `GITHUB_TOKEN` as a repo secret; GitHub provides it automatically per workflow run.
    - It is available as `${{ secrets.GITHUB_TOKEN }}` (or `github.token` context).
@@ -215,15 +215,19 @@ Notes:
 - `.github/workflows/eas-build.yml`:
   - Runs CI checks on self-hosted macOS.
   - Builds locally with:
-    - `eas build --local --platform ios`
-    - `eas build --local --platform android`
-  - Uploads local artifacts (`ios.ipa`, `android.aab`) to the workflow run.
-  - Optional submit job uploads:
+    - `eas build --profile production --platform ios --local`
+    - `eas build --profile production --platform android --local`
+    - `eas build --profile production-apk --platform android --local`
+    - `eas build --profile production-wear --platform android --local`
+    - `eas build --profile production-wear-apk --platform android --local`
+  - Uploads local artifacts (`ios.ipa`, phone `android.aab` + `android.apk`, wear `wear.aab` + `wear.apk`) to the workflow run.
+  - Conditional submit job uploads:
     - iOS via `apple-actions/upload-testflight-build@v3`
     - Android via `r0adkll/upload-google-play@v1`
+    - Wear OS via `r0adkll/upload-google-play@v1` (non-blocking)
   - Submit job also:
     - Enforces release version bump (`apps/mobile/package.json` `version` must be greater than latest `vX.Y.Z` tag)
-    - Creates a GitHub Release and attaches uploaded artifacts (`ios.ipa`/`android.aab`)
+    - Creates a GitHub Release and attaches uploaded artifacts (`ios.ipa`, `android.aab`, `android.apk`, `wear.aab`, `wear.apk`)
 
 Trigger conditions:
 
@@ -309,16 +313,17 @@ If this passes, GitHub workflow `eas-build.yml` should pass on the same runner h
 ## 8. First validation run
 
 1. In GitHub Actions, run `Self-Hosted Mobile Build & Submit`.
-2. Inputs:
-   - `platform: ios` first, then `android`.
-   - `submit: false`.
-3. Confirm build artifacts are attached to the run.
-4. Then run once with `submit: true` after all four store-upload secrets are set:
+2. No manual inputs are required for `workflow_dispatch`; run it once as a build validation.
+3. Confirm build artifacts are attached to the run (`ios.ipa`, `android.aab`, `android.apk`, `wear.aab`, `wear.apk`).
+4. Ensure all four store-upload secrets are set:
    - `APPSTORE_ISSUER_ID`
    - `APPSTORE_API_KEY_ID`
    - `APPSTORE_API_PRIVATE_KEY`
    - `GOOGLE_PLAY_SERVICE_ACCOUNT_JSON`
-5. Verify a GitHub Release was created with attached mobile artifacts.
+5. Push a commit to `main` that bumps `apps/mobile/package.json` to a semver greater than the latest `vX.Y.Z` tag, then verify:
+   - submit job runs,
+   - store uploads execute,
+   - a GitHub Release is created with attached mobile artifacts.
 
 ## 9. Common issues
 
@@ -343,7 +348,7 @@ If this passes, GitHub workflow `eas-build.yml` should pass on the same runner h
    - Install JDK 17 on the runner (`brew install temurin@17`).
    - Or rely on workflow-managed Java setup (`actions/setup-java@v4`) and rerun.
 8. Submit job fails with missing secret:
-   - Verify required secrets exist and are available to the selected environment (`production`).
+   - Verify required secrets exist in repository Actions secrets and are readable by workflows.
    - For iOS, ensure `APPSTORE_API_PRIVATE_KEY` is the raw `.p8` key content, not a file path.
 9. Submit job fails on Google Play permissions:
    - Ensure the service account in `GOOGLE_PLAY_SERVICE_ACCOUNT_JSON` has access to app `com.lallimaven.eclipsetimer` and the target track.

documents/planning/tech-debt.md

@@ -84,7 +84,7 @@ These are not implemented yet and would add net-new capability.
 |---|---|---|---|---|
 | IMP-01 | High | Mobile module size concentration | Large files remain: `TimerScreen.tsx` (1523), `EclipsePreviewScreen.tsx` (884), `appState.tsx` (716), `RootNavigator.tsx` (623), `NotificationSettingsScreen.tsx` (582), `useTimerState.ts` (525) | Split by feature slices (compute adapter, map overlays, alarm controls, preview renderer, state reducers/selectors) |
 | IMP-02 | High | Notifications API usage | `apps/mobile/src/services/notifications.ts` imports from `expo-notifications/build/*` internals | Move to public `expo-notifications` exports to reduce SDK break risk |
-| IMP-03 | High | Native/app version consistency | `apps/mobile/android/app/build.gradle` hardcodes `versionCode 3`, `versionName "1.0.0"` while app package is `1.1.29` | Unify version source and remove conflicting hardcoded native values |
+| IMP-03 | High | Native/app version consistency | `apps/mobile/android/app/build.gradle` hardcodes `versionCode 3`, `versionName "1.0.0"` while app package is `1.1.40` | Unify version source and remove conflicting hardcoded native values |
 | IMP-04 | High | Observability configuration | Sentry values remain placeholders across app/native config (`App.tsx`, `app.json`, `android/sentry.properties`) | Move to env/secret-driven config with startup/build validation and docs |
 
 ### 3.2 Data contracts and engine correctness
@@ -122,7 +122,7 @@ These are not implemented yet and would add net-new capability.
 | ID | Priority | Area | Current state | Improvement |
 |---|---|---|---|---|
 | IMP-20 | High | Documentation command drift | Multiple docs still instruct non-existent root scripts (`pnpm dev`, `pnpm build`, `pnpm test:watch`, `pnpm clean`) and these commands fail when executed | Update docs to current script surface and add docs command validation check |
-| IMP-21 | Medium | Documentation path drift | Plain-text references still point to moved paths (for example root `README.md` references `documents/self-hosted-macos-runner.md`; release plan references old store docs paths) | Update stale paths to `documents/planning/*` and `documents/reference/*` |
+| IMP-21 | Medium | Documentation path drift | Plain-text references still point to moved paths (for example root `README.md` references `documents/self-hosted-macos-runner.md`) | Update stale paths to `documents/planning/*` and `documents/reference/*` |
 | IMP-22 | Medium | Duplicate config sources | Root `app.json`/`eas.json` and `apps/mobile` config diverge (including bundle ID/CLI profile details) | Define single source of truth and deprecate duplicates |
 | IMP-23 | Medium | Changelog source-of-truth drift | Both root `CHANGELOG.md` and `documents/reference/CHANGELOG.md` exist with divergent content/version history | Consolidate to one authoritative changelog location and update cross-links |
 | IMP-24 | Low | Environment/tooling enforcement | `packageManager` is pinned, but no strict `engines`/Corepack enforcement gate | Add `engines` and optional install-time guard script |