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
2026-03-06 19:51:13 +08:00
parent f58eeda8a7
commit 6ad7ff5fe1
42 changed files with 128 additions and 154 deletions
--- a/COMMIT_MESSAGE.txt
+++ b/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
--- a/README.md
+++ b/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
--- a/docs/00-INDEX.md
+++ b/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
- **[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
+### Integration (`docs/integration/`)

-### 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
- **[legal-store-compliance.md](./legal-store-compliance.md)** - Legal and store compliance
- **[observability-dashboards.md](./observability-dashboards.md)** - Observability dashboards
+### Design (`docs/design/`) — plans, prefetch, recovery

-### 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)
- **[DEPLOYMENT_CHECKLIST.md](./DEPLOYMENT_CHECKLIST.md)** - Deployment checklist
- **[DEPLOYMENT_SUMMARY.md](./DEPLOYMENT_SUMMARY.md)** - Deployment summary
+### Progress (`docs/progress/`)

-### 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

 ---

--- a/docs/_archive/platform-capability-reference.md
+++ b/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  
--- a/docs/architecture/CROSS_PLATFORM_STORAGE_PATTERN.md
+++ b/docs/architecture/CROSS_PLATFORM_STORAGE_PATTERN.md
--- a/docs/architecture/DATABASE_INTERFACES.md
+++ b/docs/architecture/DATABASE_INTERFACES.md
--- a/docs/architecture/DATABASE_INTERFACES_IMPLEMENTATION.md
+++ b/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`
--- a/docs/architecture/NATIVE_FETCHER_CONFIGURATION.md
+++ b/docs/architecture/NATIVE_FETCHER_CONFIGURATION.md
--- a/docs/compliance/accessibility-localization.md
+++ b/docs/compliance/accessibility-localization.md
--- a/docs/compliance/legal-store-compliance.md
+++ b/docs/compliance/legal-store-compliance.md
--- a/docs/compliance/observability-dashboards.md
+++ b/docs/compliance/observability-dashboards.md
--- a/docs/deployment/DEPLOYMENT_CHECKLIST.md
+++ b/docs/deployment/DEPLOYMENT_CHECKLIST.md
@@ -139,9 +139,9 @@ npm run deploy

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

 ---

--- a/docs/deployment/deployment-guide.md
+++ b/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
--- a/docs/design/FEEDBACK-RESPONSE-PLAN.md
+++ b/docs/design/FEEDBACK-RESPONSE-PLAN.md
--- a/docs/design/P1.5-CONSOLIDATION-PLAN.md
+++ b/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_GUIDE.md` — Check if duplicate
- `docs/DEPLOYMENT_CHECKLIST.md` — Keep (complementary)
- `docs/DEPLOYMENT_SUMMARY.md` — Keep (complementary)
+- `docs/deployment/deployment-guide.md` — Keep as canonical (if exists)
+- `docs/deployment/DEPLOYMENT_CHECKLIST.md` — Keep (complementary)
+- `docs/progress/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
--- a/docs/design/P1.5-STEP4-CLUSTERS.md
+++ b/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_GUIDE.md` — Check if exists
- `docs/DEPLOYMENT_CHECKLIST.md` — Keep (complementary)
- `docs/DEPLOYMENT_SUMMARY.md` — Keep (complementary)
+- `docs/deployment/deployment-guide.md` — Check if exists
+- `docs/deployment/DEPLOYMENT_CHECKLIST.md` — Keep (complementary)
+- `docs/progress/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_CHECKLIST.md` (complementary)
+- `docs/deployment/deployment-guide.md` (primary)
+- `docs/deployment/DEPLOYMENT_CHECKLIST.md` (complementary)
 - `docs/DEPLOYMENT_SUMMARY.md` (complementary)

 ### Expected Outcome
--- a/docs/design/P1.5-STEP4-DECISIONS.md
+++ b/docs/design/P1.5-STEP4-DECISIONS.md
@@ -84,16 +84,16 @@

 ### Analysis

- **`deployment-guide.md`** (8785 bytes): Main deployment guide
- **`DEPLOYMENT_CHECKLIST.md`** (4096 bytes): Deployment checklist (complementary)
+- **`deployment/deployment-guide.md`** (8785 bytes): Main deployment guide
+- **`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_CHECKLIST.md` is a complementary checklist
+- `deployment/deployment-guide.md` is the main guide
+- `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_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 `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/DEPLOYMENT_CHECKLIST.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

--- a/docs/design/P2.1-NATIVE-REFACTORING-ANALYSIS.md
+++ b/docs/design/P2.1-NATIVE-REFACTORING-ANALYSIS.md
--- a/docs/design/app-startup-recovery-solution.md
+++ b/docs/design/app-startup-recovery-solution.md
--- a/docs/design/exploration-findings-initial.md
+++ b/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))
- **iOS 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](../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)

--- a/docs/design/plugin-behavior-exploration-template.md
+++ b/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

--- a/docs/design/plugin-requirements-implementation.md
+++ b/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
--- a/docs/design/prefetch-scheduling-diagnosis.md
+++ b/docs/design/prefetch-scheduling-diagnosis.md
--- a/docs/design/prefetch-scheduling-trace.md
+++ b/docs/design/prefetch-scheduling-trace.md
--- a/docs/file-organization-summary.md
+++ b/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)
-5. Deploy: deployment-guide.md (production deployment)
+4. Configure: integration/host-request-configuration.md (request patterns)
+5. Deploy: deployment/deployment-guide.md (production deployment)
 6. Test: manual_smoke_test.md (quality assurance)
-7. Monitor: observability-dashboards.md (operational monitoring)
-8. Comply: accessibility-localization.md + legal-store-compliance.md (compliance)
+7. Monitor: compliance/observability-dashboards.md (operational monitoring)
+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`
-4. **Monitor**: `observability-dashboards.md`
+3. **Deploy**: `deployment/deployment-guide.md`
+4. **Monitor**: `compliance/observability-dashboards.md`

 ### For Compliance Teams
-1. **Accessibility**: `accessibility-localization.md`
-2. **Legal**: `legal-store-compliance.md`
+1. **Accessibility**: `compliance/accessibility-localization.md`
+2. **Legal**: `compliance/legal-store-compliance.md`
 3. **Testing**: `manual_smoke_test.md`

 ---
--- a/docs/integration/ACTION_PLAN_INTEGRATION_FIXES.md
+++ b/docs/integration/ACTION_PLAN_INTEGRATION_FIXES.md
--- a/docs/integration/capacitor-platform-service-clean-changes.md
+++ b/docs/integration/capacitor-platform-service-clean-changes.md
--- a/docs/integration/getting-valid-plan-ids.md
+++ b/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
--- a/docs/integration/host-request-configuration.md
+++ b/docs/integration/host-request-configuration.md
--- a/docs/integration/hydrate-plan-implementation-guide.md
+++ b/docs/integration/hydrate-plan-implementation-guide.md
--- a/docs/integration/user-zero-stars-implementation.md
+++ b/docs/integration/user-zero-stars-implementation.md
--- a/docs/platform/android/CONSUMING_APP_ANDROID_NOTES.md
+++ b/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
--- a/docs/platform/android/CONSUMING_APP_OPTIONAL_ANDROID_ID_CLEANUP.md
+++ b/docs/platform/android/CONSUMING_APP_OPTIONAL_ANDROID_ID_CLEANUP.md
--- a/docs/platform/android/IMPLEMENTATION_DIRECTIVE.md
+++ b/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

 ---

--- a/docs/platform/android/TIMESAFARI_ANDROID_COMPARISON.md
+++ b/docs/platform/android/TIMESAFARI_ANDROID_COMPARISON.md
--- a/docs/platform/ios/DOCUMENTATION_REVIEW.md
+++ b/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

--- a/docs/progress/DEPLOYMENT_SUMMARY.md
+++ b/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`
--- a/docs/progress/TODO-CLASSIFICATION.md
+++ b/docs/progress/TODO-CLASSIFICATION.md
--- a/docs/progress/TODO.md
+++ b/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

--- a/docs/testing/LOCALHOST_GUIDE.md
+++ b/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:

--- a/test-apps/daily-notification-test/IMPLEMENTATION_COMPLETE.md
+++ b/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

 ---
--- a/test-apps/daily-notification-test/TODO_NATIVE_FETCHER.md
+++ b/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