docs: reorganize docs into subdirs and fix links

- Keep only index, getting-started, invariants, performance,
  troubleshooting, and file-organization-summary in docs/ root
- Add docs/architecture/ (storage, database interfaces, native fetcher)
- Add docs/deployment/ (deployment-guide, DEPLOYMENT_CHECKLIST)
- Add docs/compliance/ (accessibility, legal, observability)
- Move integration guides and host-app docs to docs/integration/
- Move design/planning and prefetch docs to docs/design/
- Move Android consuming-app and comparison docs to docs/platform/android/
- Move DEPLOYMENT_SUMMARY and TODO-CLASSIFICATION to docs/progress/
- Archive deprecated platform-capability-reference to docs/_archive/
- Point platform-capability links to alarms/01-platform-capability-reference.md
- Update docs/00-INDEX.md with new sections and paths
- Fix cross-references in README, deployment, progress, design, testing,
  and test-app docs
- Remove one-off COMMIT_MESSAGE.txt

COMMIT_MESSAGE.txt

@@ -1,46 +0,0 @@
-docs(building): update BUILDING.md with iOS prerequisites and clean-build script
-
-Updates BUILDING.md to reflect recent changes in build-native.sh, especially
-the Xcode Command Line Tools prerequisite check and the clean-build script.
-
-Problem:
-- BUILDING.md didn't mention Xcode Command Line Tools prerequisite
-  (recently added to build-native.sh)
-- clean-build.sh script exists but wasn't documented
-- iOS build troubleshooting lacked Command Line Tools guidance
-
-Changes:
-- Add Xcode Command Line Tools to Prerequisites section
-  - Document installation command (xcode-select --install)
-  - Include verification steps (xcode-select -p, xcodebuild -version)
-  - Note that build script automatically checks for these tools
-  - Explain that sqlite3 is part of Command Line Tools
-
-- Document clean-build.sh script in Build Scripts section
-  - Basic usage: ./scripts/clean-build.sh
-  - All options: --all, --clean-gradle-cache, --clean-derived-data,
-    --reinstall-node
-  - Explain when to use clean builds
-
-- Enhance iOS Native Build Process section
-  - Add prerequisite note about Command Line Tools
-  - Include troubleshooting commands for pod install issues
-  - Reference prerequisites section for details
-
-- Add comprehensive troubleshooting sections
-  - Clean Build section at start of Troubleshooting
-    - Recommends clean-build as first step for many issues
-    - Lists when to use clean builds
-  - iOS Build Issues section
-    - Command Line Tools configuration errors
-    - SQLite/linker issues and pkgx conflicts
-    - CocoaPods installation problems
-    - All with clear solutions and commands
-
-The documentation now accurately reflects:
-- Xcode Command Line Tools as required iOS prerequisite
-- clean-build.sh as available build tool
-- Complete iOS troubleshooting workflow
-
-Files modified:
-- BUILDING.md

README.md

@@ -111,7 +111,7 @@ The following behaviors are best-effort and may vary by platform:
 - **Error Handling**: Exponential backoff and retry logic
 - **Security**: Encrypted storage and secure callback handling
 - **Database Access**: Full TypeScript interfaces for plugin database access
-  - See [`docs/DATABASE_INTERFACES.md`](docs/DATABASE_INTERFACES.md) for complete API reference
+  - See [`docs/architecture/DATABASE_INTERFACES.md`](docs/architecture/DATABASE_INTERFACES.md) for complete API reference
   - See [docs/00-INDEX.md](docs/00-INDEX.md) for complete documentation index
   - Plugin owns its SQLite database - access via Capacitor interfaces
   - Supports schedules, content cache, callbacks, history, and configuration
@@ -835,7 +835,7 @@ MIT License - see [LICENSE](LICENSE) file for details.
   - [Android Platform Docs](./docs/platform/android/) - Android implementation and directives
 - **Testing**: [Testing Documentation](./docs/testing/) - Comprehensive testing guides and procedures
 - **Alarms**: [Alarm System Docs](./docs/alarms/) - Alarm system documentation
-- **Database Interfaces**: [`docs/DATABASE_INTERFACES.md`](docs/DATABASE_INTERFACES.md) - Complete guide to accessing plugin database from TypeScript/webview
+- **Database Interfaces**: [`docs/architecture/DATABASE_INTERFACES.md`](docs/architecture/DATABASE_INTERFACES.md) - Complete guide to accessing plugin database from TypeScript/webview
 - **Database Implementation**: [`docs/DATABASE_INTERFACES_IMPLEMENTATION.md`](docs/DATABASE_INTERFACES_IMPLEMENTATION.md) - Implementation summary and status
 - **Database Consolidation Plan**: [`docs/platform/android/DATABASE_CONSOLIDATION_PLAN.md`](docs/platform/android/DATABASE_CONSOLIDATION_PLAN.md) - Database schema consolidation roadmap
 - **Building Guide**: [BUILDING.md](BUILDING.md) - Comprehensive build instructions and troubleshooting

docs/00-INDEX.md

@@ -6,7 +6,7 @@
 **Status:** active  
 **Baseline:** See `docs/progress/00-STATUS.md` for current baseline tag
 
-This index provides organized access to all documentation in the repository. For a complete audit trail of file movements, see [CONSOLIDATION_SOURCE_MAP.md](./CONSOLIDATION_SOURCE_MAP.md).
+This index provides organized access to all documentation in the repository. For a complete audit trail of file movements, see [CONSOLIDATION_SOURCE_MAP.md](./_archive/2025-12-16-consolidation/CONSOLIDATION_SOURCE_MAP.md).
 
 ---
 
@@ -213,57 +213,77 @@ The alarm system documentation is well-organized and kept in its current locatio
 
 ---
 
-## Feature-Specific Documentation
+## Architecture (Storage & Core Tech)
 
-**Location:** `docs/`
+**Location:** `docs/architecture/`
 
-### Storage & Database
+- **[CROSS_PLATFORM_STORAGE_PATTERN.md](./architecture/CROSS_PLATFORM_STORAGE_PATTERN.md)** - Cross-platform storage pattern
+- **[DATABASE_INTERFACES.md](./architecture/DATABASE_INTERFACES.md)** - Database interfaces
+- **[DATABASE_INTERFACES_IMPLEMENTATION.md](./architecture/DATABASE_INTERFACES_IMPLEMENTATION.md)** - Database interfaces implementation
+- **[NATIVE_FETCHER_CONFIGURATION.md](./architecture/NATIVE_FETCHER_CONFIGURATION.md)** - Native fetcher configuration
 
-- **[CROSS_PLATFORM_STORAGE_PATTERN.md](./CROSS_PLATFORM_STORAGE_PATTERN.md)** - Cross-platform storage pattern
+---
-- **[DATABASE_INTERFACES.md](./DATABASE_INTERFACES.md)** - Database interfaces
-- **[DATABASE_INTERFACES_IMPLEMENTATION.md](./DATABASE_INTERFACES_IMPLEMENTATION.md)** - Database interfaces implementation
 
-### Native Fetcher
+## Deployment
 
-- **[NATIVE_FETCHER_CONFIGURATION.md](./NATIVE_FETCHER_CONFIGURATION.md)** - Native fetcher configuration
+**Location:** `docs/deployment/`
 
-### Prefetch & Scheduling
+- **[deployment-guide.md](./deployment/deployment-guide.md)** - Deployment guide (primary)
+- **[DEPLOYMENT_CHECKLIST.md](./deployment/DEPLOYMENT_CHECKLIST.md)** - Deployment checklist
 
-- **[prefetch-scheduling-diagnosis.md](./prefetch-scheduling-diagnosis.md)** - Prefetch scheduling diagnosis
+---
-- **[prefetch-scheduling-trace.md](./prefetch-scheduling-trace.md)** - Prefetch scheduling trace
 
-### Recovery & Startup
+## Compliance & Operations
 
-- **[app-startup-recovery-solution.md](./app-startup-recovery-solution.md)** - App startup recovery solution
+**Location:** `docs/compliance/`
 
-### Platform Capabilities
+- **[accessibility-localization.md](./compliance/accessibility-localization.md)** - Accessibility and localization
+- **[legal-store-compliance.md](./compliance/legal-store-compliance.md)** - Legal and store compliance
+- **[observability-dashboards.md](./compliance/observability-dashboards.md)** - Observability dashboards
 
-- **[platform-capability-reference.md](./platform-capability-reference.md)** - Platform capability reference
+---
-- **[plugin-requirements-implementation.md](./plugin-requirements-implementation.md)** - Plugin requirements implementation
 
-### Feature Implementation
+## Feature-Specific (Integration, Design, Progress)
 
-- **[getting-valid-plan-ids.md](./getting-valid-plan-ids.md)** - Getting valid plan IDs
+### Integration (`docs/integration/`)
-- **[host-request-configuration.md](./host-request-configuration.md)** - Host request configuration
-- **[hydrate-plan-implementation-guide.md](./hydrate-plan-implementation-guide.md)** - Hydrate plan implementation guide
-- **[user-zero-stars-implementation.md](./user-zero-stars-implementation.md)** - User zero stars implementation
 
-### Compliance & Operations
+- **[getting-valid-plan-ids.md](./integration/getting-valid-plan-ids.md)** - Getting valid plan IDs
+- **[host-request-configuration.md](./integration/host-request-configuration.md)** - Host request configuration
+- **[hydrate-plan-implementation-guide.md](./integration/hydrate-plan-implementation-guide.md)** - Hydrate plan implementation guide
+- **[user-zero-stars-implementation.md](./integration/user-zero-stars-implementation.md)** - User zero stars implementation
+- **[capacitor-platform-service-clean-changes.md](./integration/capacitor-platform-service-clean-changes.md)** - Capacitor platform service changes
+- **[ACTION_PLAN_INTEGRATION_FIXES.md](./integration/ACTION_PLAN_INTEGRATION_FIXES.md)** - Integration fixes action plan
 
-- **[accessibility-localization.md](./accessibility-localization.md)** - Accessibility and localization
+### Design (`docs/design/`) — plans, prefetch, recovery
-- **[legal-store-compliance.md](./legal-store-compliance.md)** - Legal and store compliance
-- **[observability-dashboards.md](./observability-dashboards.md)** - Observability dashboards
 
-### Deployment
+- **[P1.5-CONSOLIDATION-PLAN.md](./design/P1.5-CONSOLIDATION-PLAN.md)** - P1.5 consolidation plan
+- **[P1.5-STEP4-CLUSTERS.md](./design/P1.5-STEP4-CLUSTERS.md)** - P1.5 step 4 clusters
+- **[P1.5-STEP4-DECISIONS.md](./design/P1.5-STEP4-DECISIONS.md)** - P1.5 step 4 decisions
+- **[P2.1-NATIVE-REFACTORING-ANALYSIS.md](./design/P2.1-NATIVE-REFACTORING-ANALYSIS.md)** - P2.1 native refactoring analysis
+- **[FEEDBACK-RESPONSE-PLAN.md](./design/FEEDBACK-RESPONSE-PLAN.md)** - Feedback response plan
+- **[prefetch-scheduling-diagnosis.md](./design/prefetch-scheduling-diagnosis.md)** - Prefetch scheduling diagnosis
+- **[prefetch-scheduling-trace.md](./design/prefetch-scheduling-trace.md)** - Prefetch scheduling trace
+- **[app-startup-recovery-solution.md](./design/app-startup-recovery-solution.md)** - App startup recovery solution
+- **[plugin-requirements-implementation.md](./design/plugin-requirements-implementation.md)** - Plugin requirements implementation
 
-- **[deployment-guide.md](./deployment-guide.md)** - Deployment guide (primary)
+### Progress (`docs/progress/`)
-- **[DEPLOYMENT_CHECKLIST.md](./DEPLOYMENT_CHECKLIST.md)** - Deployment checklist
-- **[DEPLOYMENT_SUMMARY.md](./DEPLOYMENT_SUMMARY.md)** - Deployment summary
 
-### Utilities
+- **[DEPLOYMENT_SUMMARY.md](./progress/DEPLOYMENT_SUMMARY.md)** - Deployment summary
+- **[TODO-CLASSIFICATION.md](./progress/TODO-CLASSIFICATION.md)** - TODO classification
+
+### Platform — Android (`docs/platform/android/`)
+
+- **[CONSUMING_APP_ANDROID_NOTES.md](./platform/android/CONSUMING_APP_ANDROID_NOTES.md)** - Consuming app Android notes
+- **[CONSUMING_APP_OPTIONAL_ANDROID_ID_CLEANUP.md](./platform/android/CONSUMING_APP_OPTIONAL_ANDROID_ID_CLEANUP.md)** - Optional Android ID cleanup
+- **[TIMESAFARI_ANDROID_COMPARISON.md](./platform/android/TIMESAFARI_ANDROID_COMPARISON.md)** - TimeSafari Android comparison
+
+### Platform Capabilities (canonical)
+
+- **[01-platform-capability-reference.md](./alarms/01-platform-capability-reference.md)** - Platform capability reference (canonical; deprecated root copy archived in `_archive/`)
+
+### Utilities (meta)
 
 - **[file-organization-summary.md](./file-organization-summary.md)** - File organization summary
-- **[capacitor-platform-service-clean-changes.md](./capacitor-platform-service-clean-changes.md)** - Capacitor platform service changes
 
 ---
 
@@ -287,7 +307,7 @@ These are derived operational artifacts for AI-assisted development:
 
 **Location:** `docs/archive/2025-legacy-doc/`
 
-Historical documentation preserved verbatim. See [CONSOLIDATION_SOURCE_MAP.md](./CONSOLIDATION_SOURCE_MAP.md) for complete archive listing.
+Historical documentation preserved verbatim. See [CONSOLIDATION_SOURCE_MAP.md](./_archive/2025-12-16-consolidation/CONSOLIDATION_SOURCE_MAP.md) for complete archive listing.
 
 **Notable archived content:**
 - Historical directives (`doc/directives/`)
@@ -312,9 +332,11 @@ Historical documentation preserved verbatim. See [CONSOLIDATION_SOURCE_MAP.md](.
 | **Testing** | 13 | `docs/testing/` |
 | **Alarms** | 11 | `docs/alarms/` |
 | **Design & Research** | 5 | `docs/design/` |
-| **Feature-Specific** | 18 | `docs/` |
+| **Architecture** | 4 | `docs/architecture/` |
+| **Deployment** | 2 | `docs/deployment/` |
+| **Compliance** | 3 | `docs/compliance/` |
+| **Feature-Specific (integration, design, progress, platform)** | 14 | `docs/integration/`, `docs/design/`, `docs/progress/`, `docs/platform/android/` |
 | **AI Artifacts** | 7 | `docs/ai/` |
-| **Deployment** | 3 | `docs/` |
 | **Test Apps** | 20+ | `test-apps/*/` |
 | **Archive** | 29 | `docs/archive/2025-legacy-doc/` |
 
@@ -339,7 +361,7 @@ Historical documentation preserved verbatim. See [CONSOLIDATION_SOURCE_MAP.md](.
 - **Test on Android** → See [Android Test App Docs](../test-apps/android-test-app/docs/)
 - **Understand alarms** → Browse [Alarms Documentation](./alarms/)
 - **Troubleshoot** → Check platform-specific troubleshooting guides
-- **Deploy** → See [Deployment Guide](./deployment-guide.md)
+- **Deploy** → See [Deployment Guide](./deployment/deployment-guide.md)
 
 ### By Platform
 
@@ -366,12 +388,12 @@ When adding new documentation:
 1. Place file in appropriate category directory
 2. Add entry to this index in the correct section
 3. Update the "Document Map by Category" table if needed
-4. Update [CONSOLIDATION_SOURCE_MAP.md](./CONSOLIDATION_SOURCE_MAP.md) if consolidating
+4. Update [CONSOLIDATION_SOURCE_MAP.md](./_archive/2025-12-16-consolidation/CONSOLIDATION_SOURCE_MAP.md) if consolidating
 
 ### Consolidation Reference
 
 For complete consolidation audit trail, see:
-- **[CONSOLIDATION_SOURCE_MAP.md](./CONSOLIDATION_SOURCE_MAP.md)** - Complete file mapping
+- **[CONSOLIDATION_SOURCE_MAP.md](./_archive/2025-12-16-consolidation/CONSOLIDATION_SOURCE_MAP.md)** - Complete file mapping
 
 ---
 

docs/_archive/platform-capability-reference.md

@@ -1,8 +1,8 @@
 # Platform Capability Reference: Android & iOS Alarm/Notification Behavior
 
-**⚠️ DEPRECATED**: This document has been superseded by [01-platform-capability-reference.md](./alarms/01-platform-capability-reference.md) as part of the unified alarm documentation structure.
+**⚠️ DEPRECATED**: This document has been superseded by [01-platform-capability-reference.md](../alarms/01-platform-capability-reference.md) as part of the unified alarm documentation structure.
 
-**See**: [Unified Alarm Directive](./alarms/000-UNIFIED-ALARM-DIRECTIVE.md) for the new documentation structure.
+**See**: [Unified Alarm Directive](../alarms/000-UNIFIED-ALARM-DIRECTIVE.md) for the new documentation structure.
 
 **Author**: Matthew Raymer  
 **Date**: November 2025  

docs/architecture/DATABASE_INTERFACES_IMPLEMENTATION.md

@@ -36,7 +36,7 @@ Extended DAOs with additional queries:
 - `CallbackDao`: Added `getAll()`, `getByEnabled()`, `getById()`, `update()`
 - `HistoryDao`: Added `getSinceByKind()`, `getRecent()`
 
-### ✅ Comprehensive Documentation (`docs/DATABASE_INTERFACES.md`)
+### ✅ Comprehensive Documentation ([DATABASE_INTERFACES.md](./DATABASE_INTERFACES.md))
 
 Created 600+ line documentation guide:
 - Complete API reference with examples
@@ -127,7 +127,7 @@ daily_notification_plugin.db
 1. **`src/definitions.ts`** - Added database interface methods and types
 2. **`android/src/main/java/com/timesafari/dailynotification/DailyNotificationPlugin.kt`** - Implemented PluginMethods
 3. **`android/src/main/java/com/timesafari/dailynotification/DatabaseSchema.kt`** - Extended DAOs
-4. **`docs/DATABASE_INTERFACES.md`** - Complete documentation
+4. **[DATABASE_INTERFACES.md](./DATABASE_INTERFACES.md)** - Complete documentation
 5. **`android/DATABASE_CONSOLIDATION_PLAN.md`** - Updated with interface requirements
 
 ## Next Steps
@@ -139,7 +139,7 @@ daily_notification_plugin.db
 
 ## Documentation References
 
-- **Complete API Reference**: `docs/DATABASE_INTERFACES.md`
+- **Complete API Reference**: [DATABASE_INTERFACES.md](./DATABASE_INTERFACES.md)
 - **Consolidation Plan**: `android/DATABASE_CONSOLIDATION_PLAN.md`
 - **TypeScript Definitions**: `src/definitions.ts`
 - **Database Schema**: `android/src/main/java/com/timesafari/dailynotification/DatabaseSchema.kt`

docs/deployment/DEPLOYMENT_CHECKLIST.md

@@ -139,9 +139,9 @@ npm run deploy
 
 ### Support
 - **Documentation**: See `docs/` directory
-- **Troubleshooting**: See `docs/deployment-guide.md`
+- **Troubleshooting**: See [deployment-guide.md](./deployment-guide.md)
-- **Monitoring**: See `docs/observability-dashboards.md`
+- **Monitoring**: See [observability-dashboards.md](../compliance/observability-dashboards.md)
-- **Compliance**: See `docs/legal-store-compliance.md`
+- **Compliance**: See [legal-store-compliance.md](../compliance/legal-store-compliance.md)
 
 ---
 

docs/deployment/deployment-guide.md

@@ -4,7 +4,7 @@
 **Version**: 1.0.0  
 **Created**: 2025-10-08 06:24:57 UTC
 
-> **See also:** [DEPLOYMENT_CHECKLIST.md](./DEPLOYMENT_CHECKLIST.md) for checklist | [DEPLOYMENT_SUMMARY.md](./DEPLOYMENT_SUMMARY.md) for summary
+> **See also:** [DEPLOYMENT_CHECKLIST.md](./DEPLOYMENT_CHECKLIST.md) for checklist | [DEPLOYMENT_SUMMARY.md](../progress/DEPLOYMENT_SUMMARY.md) for summary
 
 ## Overview
 
@@ -315,10 +315,10 @@ observability.configure({
 #### Dashboard Setup
 ```bash
 # Import sample dashboards
-# See docs/observability-dashboards.md for Grafana/DataDog configurations
+# See docs/compliance/observability-dashboards.md for Grafana/DataDog configurations
 
 # Set up alerting rules
-# See docs/observability-dashboards.md for Prometheus alerting
+# See docs/compliance/observability-dashboards.md for Prometheus alerting
 ```
 
 ## Troubleshooting

docs/design/P1.5-CONSOLIDATION-PLAN.md

@@ -142,13 +142,12 @@ Create a **single authoritative documentation index** that clearly separates:
 #### 4.4 Deployment Docs
 
 **Files:**
-- `docs/deployment-guide.md` — Keep as canonical (if exists)
+- `docs/deployment/deployment-guide.md` — Keep as canonical (if exists)
-- `docs/DEPLOYMENT_GUIDE.md` — Check if duplicate
+- `docs/deployment/DEPLOYMENT_CHECKLIST.md` — Keep (complementary)
-- `docs/DEPLOYMENT_CHECKLIST.md` — Keep (complementary)
+- `docs/progress/DEPLOYMENT_SUMMARY.md` — Keep (complementary)
-- `docs/DEPLOYMENT_SUMMARY.md` — Keep (complementary)
 
 **Action:**
-- If `deployment-guide.md` and `DEPLOYMENT_GUIDE.md` are duplicates → Keep one, archive other
+- If `deployment/deployment-guide.md` and `DEPLOYMENT_GUIDE.md` are duplicates → Keep one, archive other
 - Ensure all deployment docs are cross-referenced
 
 **Status:** Review and consolidate

docs/design/P1.5-STEP4-CLUSTERS.md

@@ -114,15 +114,14 @@ Review and consolidate duplicate/superseded documentation with explicit "keep /
 
 ### Files to Review
 
-- `docs/deployment-guide.md` — Check if exists
+- `docs/deployment/deployment-guide.md` — Check if exists
-- `docs/DEPLOYMENT_GUIDE.md` — Check if exists
+- `docs/deployment/DEPLOYMENT_CHECKLIST.md` — Keep (complementary)
-- `docs/DEPLOYMENT_CHECKLIST.md` — Keep (complementary)
+- `docs/progress/DEPLOYMENT_SUMMARY.md` — Keep (complementary)
-- `docs/DEPLOYMENT_SUMMARY.md` — Keep (complementary)
 
 ### Decision Process
 
 1. **Check existence:**
-   - If both `deployment-guide.md` and `DEPLOYMENT_GUIDE.md` exist → Compare content
+   - If both `deployment/deployment-guide.md` and `DEPLOYMENT_GUIDE.md` exist → Compare content
    - If one exists → Keep as canonical
    - If neither exists → Skip this cluster
 
@@ -139,8 +138,8 @@ Review and consolidate duplicate/superseded documentation with explicit "keep /
 
 ### Authoritative Doc
 
-- `docs/DEPLOYMENT_GUIDE.md` (preferred) or `docs/deployment-guide.md` (if only one exists)
+- `docs/deployment/deployment-guide.md` (primary)
-- `docs/DEPLOYMENT_CHECKLIST.md` (complementary)
+- `docs/deployment/DEPLOYMENT_CHECKLIST.md` (complementary)
 - `docs/DEPLOYMENT_SUMMARY.md` (complementary)
 
 ### Expected Outcome

docs/design/P1.5-STEP4-DECISIONS.md

@@ -84,16 +84,16 @@
 
 ### Analysis
 
-- **`deployment-guide.md`** (8785 bytes): Main deployment guide
+- **`deployment/deployment-guide.md`** (8785 bytes): Main deployment guide
-- **`DEPLOYMENT_CHECKLIST.md`** (4096 bytes): Deployment checklist (complementary)
+- **`deployment/DEPLOYMENT_CHECKLIST.md`** (4096 bytes): Deployment checklist (complementary)
 - **`DEPLOYMENT_SUMMARY.md`** (1685 bytes): Deployment summary (complementary)
 - **`DEPLOYMENT_GUIDE.md`**: Does not exist (was incorrectly referenced in plan)
 
 ### Decision: **KEEP ALL** (Complementary Documents)
 
 **Rationale:**
-- `deployment-guide.md` is the main guide
+- `deployment/deployment-guide.md` is the main guide
-- `DEPLOYMENT_CHECKLIST.md` is a complementary checklist
+- `deployment/DEPLOYMENT_CHECKLIST.md` is a complementary checklist
 - `DEPLOYMENT_SUMMARY.md` is a complementary summary
 - They serve different purposes and are complementary
 
@@ -101,9 +101,9 @@
 
 - [x] Keep all three files
 - [ ] Add cross-references:
-  - In `deployment-guide.md`: "See [DEPLOYMENT_CHECKLIST.md](./DEPLOYMENT_CHECKLIST.md) for checklist and [DEPLOYMENT_SUMMARY.md](./DEPLOYMENT_SUMMARY.md) for summary"
+  - In `deployment/deployment-guide.md`: "See [DEPLOYMENT_CHECKLIST.md](./DEPLOYMENT_CHECKLIST.md) for checklist and [DEPLOYMENT_SUMMARY.md](../progress/DEPLOYMENT_SUMMARY.md) for summary"
-  - In `DEPLOYMENT_CHECKLIST.md`: "See [deployment-guide.md](./deployment-guide.md) for complete guide"
+  - In `deployment/DEPLOYMENT_CHECKLIST.md`: "See [deployment-guide.md](./deployment-guide.md) for complete guide"
-  - In `DEPLOYMENT_SUMMARY.md`: "See [deployment-guide.md](./deployment-guide.md) for complete guide"
+  - In `progress/DEPLOYMENT_SUMMARY.md`: "See [deployment-guide.md](../deployment/deployment-guide.md) for complete guide"
 - [ ] Update `docs/00-INDEX.md` to list all three (already lists all)
 
 ---
@@ -118,7 +118,7 @@
 
 1. `docs/testing/QUICK_REFERENCE.md` + `QUICK_REFERENCE_V2.md` (add cross-refs)
 2. `docs/integration/REFACTOR_NOTES.md` + `REFACTOR_NOTES_QUICK_START.md` + `REFACTOR_ANALYSIS.md` (add cross-refs)
-3. `docs/deployment-guide.md` + `DEPLOYMENT_CHECKLIST.md` + `DEPLOYMENT_SUMMARY.md` (add cross-refs)
+3. `docs/deployment/deployment-guide.md` + `deployment/DEPLOYMENT_CHECKLIST.md` + `progress/DEPLOYMENT_SUMMARY.md` (add cross-refs)
 
 ### Index Updates
 

docs/design/exploration-findings-initial.md

@@ -641,7 +641,7 @@ private func checkForMissedNotifications() async {
 
 - [Plugin Behavior Exploration Template](./plugin-behavior-exploration-template.md) - Use this for testing
 - [Plugin Requirements & Implementation](./plugin-requirements-implementation.md) - Requirements based on findings
-- [Platform Capability Reference](./platform-capability-reference.md) - OS-level facts
+- [Platform Capability Reference](../alarms/01-platform-capability-reference.md) - OS-level facts
 
 ---
 
@@ -650,8 +650,8 @@ private func checkForMissedNotifications() async {
 After improvements are complete, separate documents by purpose:
 
 - **This file** → Exploration Findings (final) - Code inspection and test results
-- **Android Behavior** → Platform Reference (see [Platform Capability Reference](./platform-capability-reference.md))
+- **Android Behavior** → Platform Reference (see [Platform Capability Reference](../alarms/01-platform-capability-reference.md))
-- **iOS Behavior** → Platform Reference (see [Platform Capability Reference](./platform-capability-reference.md))
+- **iOS Behavior** → Platform Reference (see [Platform Capability Reference](../alarms/01-platform-capability-reference.md))
 - **Plugin Requirements** → Independent document (see [Plugin Requirements & Implementation](./plugin-requirements-implementation.md))
 - **Future Implementation Directive** → Separate document (to be created)
 

docs/design/plugin-behavior-exploration-template.md

@@ -14,15 +14,15 @@ This document provides an **executable template** for exploring and documenting
 3. Identify gaps between current behavior and platform capabilities
 4. Generate findings for the Plugin Requirements document
 
-**Reference**: See [Platform Capability Reference](./platform-capability-reference.md) for OS-level facts.
+**Reference**: See [Platform Capability Reference](../alarms/01-platform-capability-reference.md) for OS-level facts.
 
 ---
 
 ## 0. Quick Reference: Platform Capabilities
 
-**Android**: See [Platform Capability Reference - Android Section](./platform-capability-reference.md#2-android-alarm-capability-matrix)
+**Android**: See [Platform Capability Reference - Android Section](../alarms/01-platform-capability-reference.md#2-android-alarm-capability-matrix)
 
-**iOS**: See [Platform Capability Reference - iOS Section](./platform-capability-reference.md#3-ios-notification-capability-matrix)
+**iOS**: See [Platform Capability Reference - iOS Section](../alarms/01-platform-capability-reference.md#3-ios-notification-capability-matrix)
 
 **Key Differences**:
 * Android: Alarms wiped on reboot; must reschedule
@@ -346,7 +346,7 @@ After completing this exploration, generate:
 
 ## Related Documentation
 
-- [Platform Capability Reference](./platform-capability-reference.md) - OS-level facts
+- [Platform Capability Reference](../alarms/01-platform-capability-reference.md) - OS-level facts
 - [Plugin Requirements & Implementation](./plugin-requirements-implementation.md) - Requirements based on findings
 - [Improve Alarm Directives](./improve-alarm-directives.md) - Improvement directive
 

docs/design/plugin-requirements-implementation.md

@@ -17,7 +17,7 @@ This document defines the **rules the plugin must follow** to behave predictably
 
 **This document should be updated** after exploration findings are documented.
 
-**Reference**: See [Platform Capability Reference](./platform-capability-reference.md) for OS-level facts.
+**Reference**: See [Platform Capability Reference](../alarms/01-platform-capability-reference.md) for OS-level facts.
 
 ---
 
@@ -533,7 +533,7 @@ Non-breaking changes include:
 
 ## Related Documentation
 
-- [Platform Capability Reference](./platform-capability-reference.md) - OS-level facts
+- [Platform Capability Reference](../alarms/01-platform-capability-reference.md) - OS-level facts
 - [Plugin Behavior Exploration Template](./plugin-behavior-exploration-template.md) - Exploration template
 - [Improve Alarm Directives](./improve-alarm-directives.md) - Improvement directive
 - [Boot Receiver Testing Guide](./boot-receiver-testing-guide.md) - Testing procedures

docs/file-organization-summary.md

@@ -51,19 +51,19 @@ After cleanup, we now have a clean, organized set of files with no redundancy or
 
 ### Integration Guides
 
-#### 1. `capacitor-platform-service-clean-changes.md`
+#### 1. `integration/capacitor-platform-service-clean-changes.md`
 - **Purpose**: Summary of exact changes needed to existing TimeSafari PWA code
 - **Content**: File-by-file changes, method modifications, new imports
 - **Use Case**: Implementation checklist for TimeSafari PWA developers
 
-#### 2. `host-request-configuration.md`
+#### 2. `integration/host-request-configuration.md`
 - **Purpose**: Comprehensive guide on how requests are configured in the host application
 - **Content**: Network configuration, TimeSafari-specific settings, security, observability
 - **Use Case**: Understanding how the plugin integrates with host request patterns
 
 ### Operational Documentation
 
-#### 3. `deployment-guide.md`
+#### 3. `deployment/deployment-guide.md`
 - **Purpose**: SSH deployment guide for the plugin
 - **Content**: Setup, build, testing, integration, troubleshooting
 - **Use Case**: Deploying the plugin to production
@@ -75,17 +75,17 @@ After cleanup, we now have a clean, organized set of files with no redundancy or
 
 ### Compliance & Quality
 
-#### 5. `accessibility-localization.md`
+#### 5. `compliance/accessibility-localization.md`
 - **Purpose**: Accessibility and localization guidelines
 - **Content**: WCAG 2.1 AA compliance, screen reader support, i18n system
 - **Use Case**: Ensuring accessibility and internationalization
 
-#### 6. `legal-store-compliance.md`
+#### 6. `compliance/legal-store-compliance.md`
 - **Purpose**: Legal and store compliance guidelines
 - **Content**: GDPR, CCPA, App Store, Play Store compliance requirements
 - **Use Case**: Meeting legal and store requirements
 
-#### 7. `observability-dashboards.md`
+#### 7. `compliance/observability-dashboards.md`
 - **Purpose**: Observability dashboards and monitoring
 - **Content**: Grafana/DataDog examples, alerting rules, SLO definitions
 - **Use Case**: Monitoring and observability setup
@@ -94,14 +94,14 @@ After cleanup, we now have a clean, organized set of files with no redundancy or
 
 ### Integration Flow
 ```
-1. Read: capacitor-platform-service-clean-changes.md (what to change)
+1. Read: integration/capacitor-platform-service-clean-changes.md (what to change)
 2. Reference: capacitor-platform-service-clean-integration.ts (how to change)
 3. Setup: daily-notification-timesafari-setup.ts (configuration)
-4. Configure: host-request-configuration.md (request patterns)
+4. Configure: integration/host-request-configuration.md (request patterns)
-5. Deploy: deployment-guide.md (production deployment)
+5. Deploy: deployment/deployment-guide.md (production deployment)
 6. Test: manual_smoke_test.md (quality assurance)
-7. Monitor: observability-dashboards.md (operational monitoring)
+7. Monitor: compliance/observability-dashboards.md (operational monitoring)
-8. Comply: accessibility-localization.md + legal-store-compliance.md (compliance)
+8. Comply: compliance/accessibility-localization.md + compliance/legal-store-compliance.md (compliance)
 ```
 
 ### Example Usage Flow
@@ -137,20 +137,20 @@ After cleanup, we now have a clean, organized set of files with no redundancy or
 ## Usage Recommendations
 
 ### For TimeSafari PWA Developers
-1. **Start with**: `capacitor-platform-service-clean-changes.md`
+1. **Start with**: `integration/capacitor-platform-service-clean-changes.md`
 2. **Reference**: `capacitor-platform-service-clean-integration.ts`
 3. **Configure**: `daily-notification-timesafari-setup.ts`
-4. **Understand**: `host-request-configuration.md`
+4. **Understand**: `integration/host-request-configuration.md`
 
 ### For Plugin Users
 1. **Learn**: `timesafari-integration-example.ts`
 2. **Test**: `hello-poll.ts` and `stale-data-ux.ts`
-3. **Deploy**: `deployment-guide.md`
+3. **Deploy**: `deployment/deployment-guide.md`
-4. **Monitor**: `observability-dashboards.md`
+4. **Monitor**: `compliance/observability-dashboards.md`
 
 ### For Compliance Teams
-1. **Accessibility**: `accessibility-localization.md`
+1. **Accessibility**: `compliance/accessibility-localization.md`
-2. **Legal**: `legal-store-compliance.md`
+2. **Legal**: `compliance/legal-store-compliance.md`
 3. **Testing**: `manual_smoke_test.md`
 
 ---

docs/integration/getting-valid-plan-ids.md

@@ -78,7 +78,7 @@ Plans are created by importing JWT claims containing a `PlanAction`:
 - JWT must be signed with a valid DID key
 - Response includes `handleId` and `planId` if creation succeeds
 
-**Implementation Guide**: See [`docs/hydrate-plan-implementation-guide.md`](./hydrate-plan-implementation-guide.md) for complete implementation details, including:
+**Implementation Guide**: See [hydrate-plan-implementation-guide.md](./hydrate-plan-implementation-guide.md) for complete implementation details, including:
 - `hydratePlan()` function pattern
 - PlanActionClaim interface structure
 - Helper functions for create/edit operations

docs/platform/android/CONSUMING_APP_ANDROID_NOTES.md

@@ -33,5 +33,5 @@ When logs show "Scheduling OS alarm" and "Updated schedule in database" but the
 
 ## References
 
-- [ACTION_PLAN_INTEGRATION_FIXES.md](./ACTION_PLAN_INTEGRATION_FIXES.md) — plugin and app integration checklist
+- [ACTION_PLAN_INTEGRATION_FIXES.md](../integration/ACTION_PLAN_INTEGRATION_FIXES.md) — plugin and app integration checklist
 - [CONSUMING_APP_OPTIONAL_ANDROID_ID_CLEANUP.md](./CONSUMING_APP_OPTIONAL_ANDROID_ID_CLEANUP.md) — optional cleanup of stale schedule rows

docs/platform/android/IMPLEMENTATION_DIRECTIVE.md

@@ -1489,7 +1489,7 @@ echo "   adb logcat -d | grep DNP-BOOT"
 
 - [Exploration Findings](./exploration-findings-initial.md) - Gap analysis
 - [Plugin Requirements & Implementation](./plugin-requirements-implementation.md) - Requirements
-- [Platform Capability Reference](./platform-capability-reference.md) - Android OS behavior
+- [Platform Capability Reference](../alarms/01-platform-capability-reference.md) - Android OS behavior
 
 ---
 

docs/platform/ios/DOCUMENTATION_REVIEW.md

@@ -192,7 +192,7 @@ This document reviews the Android plugin and test app documentation to ensure th
 - ✅ `testAlarm` - API.md (Android-specific)
 
 **Partially Documented Methods**:
-- ⚠️ Database CRUD methods - Some documented in `docs/DATABASE_INTERFACES.md`
+- ⚠️ Database CRUD methods - Some documented in `docs/architecture/DATABASE_INTERFACES.md`
 - ⚠️ Configuration methods - Limited documentation
 - ⚠️ History/analytics methods - Limited documentation
 

docs/progress/DEPLOYMENT_SUMMARY.md

@@ -1,6 +1,6 @@
 # TimeSafari Daily Notification Plugin - Deployment Summary
 
-> **See also:** [deployment-guide.md](./deployment-guide.md) for complete guide
+> **See also:** [deployment-guide.md](../deployment/deployment-guide.md) for complete guide
 
 **SSH Git Path**: `ssh://git@173.199.124.46:222/trent_larson/daily-notification-plugin.git`
 **Version**: `2.2.0`

docs/progress/TODO.md

@@ -189,7 +189,7 @@
 - [ ] Rollback procedures
 - [ ] Monitoring setup guide
 
-**Reference**: `DEPLOYMENT_CHECKLIST.md`
+**Reference**: [DEPLOYMENT_CHECKLIST.md](../deployment/DEPLOYMENT_CHECKLIST.md)
 
 ---
 
@@ -205,6 +205,6 @@
 **Related Documents**:
 - `docs/android-app-improvement-plan.md` - Detailed improvement plan
 - `doc/implementation-roadmap.md` - Implementation phases
-- `DEPLOYMENT_CHECKLIST.md` - Deployment procedures
+- [DEPLOYMENT_CHECKLIST.md](../deployment/DEPLOYMENT_CHECKLIST.md) - Deployment procedures
 - `test-apps/daily-notification-test/TODO_NATIVE_FETCHER.md` - Native fetcher TODOs
 

docs/testing/LOCALHOST_GUIDE.md

@@ -70,7 +70,7 @@ If you have your own localhost API server, you must create plans first. Plans ar
 
 **Note**: Creating PlanAction JWTs requires DID signing and proper claim structure, which is complex. For quick testing, **Option A (test API server) is recommended**.
 
-**Implementation Reference**: If you need to programmatically create PlanAction JWTs, see [`docs/hydrate-plan-implementation-guide.md`](./hydrate-plan-implementation-guide.md) for the complete implementation pattern, including `hydratePlan()` function and helper utilities.
+**Implementation Reference**: If you need to programmatically create PlanAction JWTs, see [`docs/integration/hydrate-plan-implementation-guide.md`](../integration/hydrate-plan-implementation-guide.md) for the complete implementation pattern, including `hydratePlan()` function and helper utilities.
 
 Then verify your setup:
 

test-apps/daily-notification-test/IMPLEMENTATION_COMPLETE.md

@@ -123,7 +123,7 @@
 - Items #7-11: Unit tests, JWT utility extraction, interceptors, caching, metrics
 
 ### Documentation:
-- Update `docs/NATIVE_FETCHER_CONFIGURATION.md` to reflect token-based approach
+- Update `docs/architecture/NATIVE_FETCHER_CONFIGURATION.md` to reflect token-based approach
 - Document ES256K JWT generation pattern for TimeSafari integration
 
 ---

test-apps/daily-notification-test/TODO_NATIVE_FETCHER.md

@@ -248,7 +248,7 @@ private String getAuthorizationHeader() {
    - [ ] Handle token expiration errors and regenerate tokens
 
 **7. Documentation Updates**:
-   - [ ] Update `docs/NATIVE_FETCHER_CONFIGURATION.md` to reflect token-based approach
+   - [ ] Update `docs/architecture/NATIVE_FETCHER_CONFIGURATION.md` to reflect token-based approach
    - [ ] Document how to generate tokens in TypeScript using TimeSafari infrastructure
    - [ ] Remove references to `jwtSecret` and HMAC-SHA256
 
@@ -639,7 +639,7 @@ Before considering this implementation complete:
 
 ## 📚 Related Documentation
 
-- `docs/NATIVE_FETCHER_CONFIGURATION.md` - Native fetcher configuration guide
+- `docs/architecture/NATIVE_FETCHER_CONFIGURATION.md` - Native fetcher configuration guide
 - `src/types/content-fetcher.ts` - TypeScript type definitions
 - `src/definitions.ts` - `PlansLastUpdatedResponse` and `PlanSummaryWithPreviousClaim` interfaces
 - `examples/native-fetcher-android.kt` - Example Android implementation