docs: apply precise fixes for correctness, consistency, and sprintability

Analysis doc improvements: - Unify runtime naming: fix tree diagram cordova.js → capacitor.js - Make manifest receivers explicit: add exported attributes and intent filters - Surface exact-alarm user rule: add decision rule for QA/ops reasoning - Guard Cordova dependency: add note about Cordova shims requirement - Add error surfacing to runtime flow: show validation and use-case error paths - Add auto-generated note to capacitor.plugins.json section Implementation plan improvements: - Add diagnostics button to Phase 1 DoD - Add Doze/Idle case to Test Matrix for false negative prevention - Make unknown field rejection explicit acceptance criterion - Link receivers export policy to Manifest Hygiene checklist - Add event ID requirement to PR checklist for grep-able logs All changes maintain existing structure with surgical precision edits.
2 days ago · 6eb5d63107
2 changed files with 74 additions and 10 deletions
--- a/docs/android-app-analysis.md
+++ b/docs/android-app-analysis.md
@ -30,6 +30,7 @@ The `/android/app` directory contains a **Capacitor-based Android test applicati
 4. **Documentation**: Live demonstration of plugin capabilities

 ### Architecture Pattern
+
 ```
 ┌─────────────────────────────────────────────────────────────┐
 │                    Android App Container                    │
@ -55,6 +56,7 @@ The `/android/app` directory contains a **Capacitor-based Android test applicati
 ## Directory Structure

 ### Root Android App Structure
+
 ```
 android/app/
 ├── build.gradle                    # App build configuration
@ -68,8 +70,8 @@ android/app/
    │   │   ├── capacitor.plugins.json
    │   │   └── public/             # Web application files
    │   │       ├── index.html      # Main test interface
-    │   │       ├── cordova.js      # Capacitor runtime
-    │   │       ├── cordova_plugins.js
+    │   │       ├── capacitor.js    # Capacitor runtime
+    │   │       ├── capacitor_plugins.js
    │   │       └── plugins/       # Plugin JavaScript files
    │   ├── java/
    │   │   └── com/timesafari/dailynotification/
@ -87,6 +89,7 @@ android/app/
 ## Key Components

 ### 1. MainActivity.java
+
 **Purpose**: Entry point extending Capacitor's BridgeActivity
 **Location**: `src/main/java/com/timesafari/dailynotification/MainActivity.java`

@ -100,16 +103,19 @@ public class MainActivity extends BridgeActivity {
 ```

 **Key Features**:
+
 - Minimal implementation - Capacitor handles most functionality
 - Extends `BridgeActivity` for automatic plugin discovery
 - Provides WebView container for web assets
 - Handles plugin registration and JavaScript bridge

 ### 2. AndroidManifest.xml
+
 **Purpose**: App configuration, permissions, and component declarations
 **Location**: `src/main/AndroidManifest.xml`

 **Key Declarations**:
+
 ```xml
 <!-- App Configuration -->
 <application android:name="com.timesafari.dailynotification">
@ -121,8 +127,23 @@ public class MainActivity extends BridgeActivity {
    </activity>

    <!-- Plugin Components -->
-    <receiver android:name="com.timesafari.dailynotification.DailyNotificationReceiver" />
-    <receiver android:name="com.timesafari.dailynotification.BootReceiver" />
+    <receiver
+        android:name="com.timesafari.dailynotification.DailyNotificationReceiver"
+        android:enabled="true"
+        android:exported="false">
+        <intent-filter>
+            <action android:name="com.timesafari.daily.NOTIFICATION" />
+        </intent-filter>
+    </receiver>
+
+    <receiver
+        android:name="com.timesafari.dailynotification.BootReceiver"
+        android:enabled="true"
+        android:exported="true">
+        <intent-filter android:priority="1000">
+            <action android:name="android.intent.action.BOOT_COMPLETED" />
+        </intent-filter>
+    </receiver>
 </application>

 <!-- Required Permissions -->
@ -134,6 +155,7 @@ public class MainActivity extends BridgeActivity {
 ```

 **Critical Permissions**:
+
 - `POST_NOTIFICATIONS`: Required for Android 13+ notification posting
 - `SCHEDULE_EXACT_ALARM`: Required for precise notification timing
 - `WAKE_LOCK`: Required for background processing
@ -143,7 +165,9 @@ public class MainActivity extends BridgeActivity {
 ### 3. Capacitor Configuration Files

 #### capacitor.config.json
+
 **Purpose**: Capacitor runtime configuration
+
 ```json
 {
    "appId": "com.timesafari.dailynotification",
@ -164,19 +188,23 @@ public class MainActivity extends BridgeActivity {
 ```

 #### capacitor.plugins.json
+
 **Purpose**: Plugin discovery and registration
+**Note**: Auto-generated on `npx cap sync` - should not be manually edited
+
 ```json
 [
-    {
-        "name": "DailyNotification",
-        "classpath": "com.timesafari.dailynotification.DailyNotificationPlugin"
-    }
+  {
+    "name": "DailyNotification",
+    "classpath": "com.timesafari.dailynotification.DailyNotificationPlugin"
+  }
 ]
 ```

 ## Web Asset Integration

 ### /www Directory Structure
+
 The `/www` directory (mapped to `assets/public/`) contains the web application that runs inside the Capacitor WebView:

 ```
@ -196,12 +224,14 @@ assets/public/
 **Features**:

 #### 1. User Interface
+
 - **Modern Design**: Gradient background, responsive layout
 - **Interactive Buttons**: 12 test functions with visual feedback
 - **Status Display**: Real-time feedback with color-coded results
 - **Mobile-Optimized**: Touch-friendly interface

 #### 2. Test Categories
+
 ```javascript
 // Plugin Testing
 - testPlugin()              // Basic plugin availability
@ -225,6 +255,7 @@ assets/public/
 ```

 #### 3. Plugin Integration
+
 ```javascript
 // Plugin Access Pattern
 window.DailyNotification = window.Capacitor.Plugins.DailyNotification;
@ -240,6 +271,7 @@ window.DailyNotification.scheduleDailyNotification({
 ```

 #### 4. Error Handling
+
 - **Visual Feedback**: Color-coded status indicators
 - **Error Messages**: Detailed error reporting
 - **Graceful Degradation**: Fallback behavior for missing features
@ -247,15 +279,18 @@ window.DailyNotification.scheduleDailyNotification({
 ## Plugin Integration

 ### Plugin Discovery Process
+
 1. **Capacitor Startup**: Loads `capacitor.plugins.json`
 2. **Plugin Registration**: Discovers `DailyNotificationPlugin` class
 3. **JavaScript Bridge**: Creates `window.Capacitor.Plugins.DailyNotification`
 4. **Method Exposure**: Exposes `@PluginMethod` annotated methods

 ### Plugin Class Structure
+
 **Location**: `android/plugin/src/main/java/com/timesafari/dailynotification/DailyNotificationPlugin.java`

 **Key Methods** (from `@PluginMethod` annotations):
+
 ```java
@PluginMethod
 public void configure(PluginCall call) { ... }
@ -289,15 +324,18 @@ public void openExactAlarmSettings(PluginCall call) { ... }
 ```

 ### Supporting Classes (34 files)
+
 The plugin includes a comprehensive set of supporting classes:

 **Core Components**:
+
 - `BootReceiver.java` - Handles system boot events
 - `DailyNotificationReceiver.java` - Handles notification events
 - `DailyNotificationScheduler.java` - Manages notification scheduling
 - `DailyNotificationFetcher.java` - Handles content fetching

 **Storage & Database**:
+
 - `DailyNotificationStorage.java` - Storage abstraction
 - `DailyNotificationStorageRoom.java` - Room database implementation
 - `DailyNotificationDatabase.java` - Database definition
@ -305,6 +343,7 @@ The plugin includes a comprehensive set of supporting classes:
 - `entities/` - Database entities (3 files)

 **Management & Utilities**:
+
 - `PermissionManager.java` - Permission handling
 - `ChannelManager.java` - Notification channel management
 - `DailyNotificationExactAlarmManager.java` - Exact alarm management
@ -312,6 +351,7 @@ The plugin includes a comprehensive set of supporting classes:
 - `DailyNotificationPerformanceOptimizer.java` - Performance optimization

 **Workers & Background Tasks**:
+
 - `DailyNotificationWorker.java` - Main background worker
 - `DailyNotificationFetchWorker.java` - Content fetching worker
 - `DailyNotificationMaintenanceWorker.java` - Maintenance tasks
@ -321,9 +361,11 @@ The plugin includes a comprehensive set of supporting classes:
 ## Build Configuration

 ### app/build.gradle
+
 **Purpose**: App-level build configuration and dependencies

 **Key Dependencies**:
+
 ```gradle
 dependencies {
    // Capacitor Core
@ -340,12 +382,13 @@ dependencies {
    implementation "androidx.work:work-runtime-ktx:2.9.0"
    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3"
    
-    // Cordova Compatibility
+    // Cordova Compatibility (only if shipping Cordova shims)
    implementation project(':capacitor-cordova-android-plugins')
 }
 ```

 **Build Configuration**:
+
 ```gradle
 android {
    namespace "com.timesafari.dailynotification"
@ -362,10 +405,12 @@ android {
 ```

 ### capacitor.build.gradle
+
 **Purpose**: Auto-generated Capacitor configuration
 **Note**: Regenerated on each `npx cap sync` - should not be manually edited

 **Manifest Hygiene (Quick Scan)**
+
 - [ ] `<uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>`
 - [ ] `<uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM"/>` (if you truly need exact)
 - [ ] `<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>`
@ -376,6 +421,7 @@ android {
 ## Runtime Behavior

 ### App Startup Sequence
+
 1. **Android System**: Launches `MainActivity`
 2. **Capacitor Initialization**: Loads Capacitor runtime
 3. **Plugin Discovery**: Scans `capacitor.plugins.json` for plugins
@ -385,6 +431,7 @@ android {
 7. **Plugin Availability**: `window.Capacitor.Plugins.DailyNotification` becomes available

 ### Plugin Method Execution Flow
+
 ```
 JavaScript Call
    ↓
@ -400,6 +447,7 @@ JavaScript Promise Resolution
 ```

 ### Background Processing
+
 - **WorkManager**: Handles background content fetching
 - **AlarmManager**: Manages notification scheduling
 - **BootReceiver**: Reschedules notifications after reboot
@ -408,14 +456,17 @@ JavaScript Promise Resolution
 ## Testing Capabilities

 ### Interactive Testing Features
+
 The test app provides comprehensive testing capabilities:

 #### 1. Plugin Availability Testing
+
 - **Basic Detection**: Verify plugin is loaded and accessible
 - **Method Availability**: Check if specific methods are callable
 - **Error Handling**: Test error conditions and edge cases

 #### 2. Notification Testing
+
 - **Immediate Notifications**: Test instant notification display
 - **Scheduled Notifications**: Test time-based notification scheduling
 - **Reminder Testing**: Test daily reminder functionality
@ -545,6 +596,10 @@ This architecture serves as both a practical testing tool and a reference implem

 **Status Matrix MUST include:** `postNotificationsGranted`, `exactAlarmGranted`, `channelEnabled`, `batteryOptimizationsIgnored`, `canScheduleNow`.

+### Exact-Alarm Decision Rule (User-Visible)
+If `SCHEDULE_EXACT_ALARM` is **granted** → schedule with `setExactAndAllowWhileIdle`.
+If **denied or quota-limited** → schedule via WorkManager (exp backoff + jitter) and surface `E_EXACT_ALARM_DENIED` (with "Degraded timing — Doze may delay" hint).
+
 ## Permission & Settings Truth Table

 | Symptom | Likely Cause | Action |
@ -569,6 +624,11 @@ graph TD
    G --> H
    H --> I[NotificationReceiver]
    I --> J[UI Update]
+    
+    %% Error paths
+    C -->|Validation Error| K[Canonical Error]
+    D -->|Use-case Error| K
+    K --> L[JavaScript Promise Rejection]
 ```

 ## Cordova vs Capacitor Assets – Accuracy Note
--- a/docs/android-app-improvement-plan.md
+++ b/docs/android-app-improvement-plan.md
@ -532,7 +532,7 @@ public class SecureNetworkClient {
 ```

 #### Key Features
- **Export Control**: Minimize exported components
+- **Export Control**: Minimize exported components (see Manifest Hygiene checklist)
 - **Permission Requirements**: Require permissions for exported components
 - **Intent Validation**: Validate incoming intents
 - **Security Review**: Regular security audits
@ -862,6 +862,7 @@ interface ScheduleResponse {
 - [ ] Returns stable error codes with hints
 - [ ] Maps native exceptions to canonical errors
 - [ ] Provides user-friendly error messages
+- [ ] Rejects unknown keys with single joined message

 ### Reliability
 - [ ] Reboot scenarios reliably deliver notifications
@ -916,6 +917,7 @@ By following this plan, the test app will become more maintainable, reliable, an
 - Input schema rejects bad `time`, long `title/body`, wrong `priority`.
 - Boot reschedule idempotent (no dup rows, migration fence).
 - @PluginMethod bodies ≤ 25 LOC, delegate to use-cases.
+- "Copy Diagnostics (JSON)" button functional.

 ### Phase 2 DoD
 - Test UI split into modular scenarios with fixtures.
@ -942,6 +944,7 @@ By following this plan, the test app will become more maintainable, reliable, an
 - [ ] Logs include event IDs (start/finish/error)
 - [ ] Status Matrix field(s) updated if capability changed
 - [ ] Runbooks section touched if behavior changed
+- [ ] No new events without ID (keeps logs grep-able)

 ## Test Matrix

@ -951,6 +954,7 @@ By following this plan, the test app will become more maintainable, reliable, an
 | Channel disabled path | isChannelEnabled/openChannelSettings | Disable channel | Canonical `E_CHANNEL_DISABLED` |
 | Exact alarm denied path | openExactAlarmSettings | Revoke exact alarm | Fallback path taken; logged `DOZE_FALLBACK` |
 | Boot reschedule | BootReceiver | Reboot emulator | One (not duplicate) schedule restored |
+| Doze idle window | scheduleDailyNotification | Device in idle | Fallback path taken; logged `EVT_DOZE_FALLBACK_TAKEN`; no crash |

 ## Error Codes (canonical)