# Documentation Index (Authoritative)

**Purpose:** Single navigation hub for active documentation; separates contracts, progress truth, guides, and archived/reference-only material.  
**Owner:** Development Team  
**Last Updated:** 2025-12-22  
**Status:** active  
**Baseline Tag:** `v1.0.11-p0-p1.4-complete`

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

---

## Policy & Contracts (Executable)

These are **policy-as-code**. Any gate (push, release, publish) MUST call `./ci/run.sh`.

- **System Invariants:** `docs/SYSTEM_INVARIANTS.md` — Single authoritative document naming and explaining all enforced invariants
- **Local CI Contract:** `./ci/run.sh` — Single source of truth for CI/release gates
- **Verification / Invariants:** `./scripts/verify.sh` — Encodes packaging, core-purity, and build invariants
- **CI Usage & Setup:** `ci/README.md` — Local CI documentation

---

## Progress Tracking (Authoritative)

These files define the current truth about project state, decisions, and verification history.

- **[00-STATUS.md](./progress/00-STATUS.md)** — Current status, invariants, next actions
- **[01-CHANGELOG-WORK.md](./progress/01-CHANGELOG-WORK.md)** — Development changelog
- **[02-OPEN-QUESTIONS.md](./progress/02-OPEN-QUESTIONS.md)** — Open questions + closed decisions log
- **[03-TEST-RUNS.md](./progress/03-TEST-RUNS.md)** — Canonical record of what ran and when
- **[04-PARITY-MATRIX.md](./progress/04-PARITY-MATRIX.md)** — iOS/Android parity tracking
- **[05-CHATGPT-FEEDBACK-PACKAGE.md](./progress/05-CHATGPT-FEEDBACK-PACKAGE.md)** — AI collaboration package
- **[P2-DESIGN.md](./progress/P2-DESIGN.md)** — P2 scope, invariants, and acceptance criteria (design-only)

---

## Archive & Reference-only

- **`docs/_archive/`** — Historical artifacts, preserved for audit trail (not part of active doc surface)
  - `docs/_archive/2025-legacy-doc/` — Legacy documentation from 2025
    - [IMPLEMENTATION_CHECKLIST_LEGACY.md](./_archive/2025-legacy-doc/IMPLEMENTATION_CHECKLIST_LEGACY.md) — iOS Phase 1 checklist (historical)
  - `docs/_archive/2025-12-16-consolidation/` — 2025-12-16 consolidation artifacts (audit trail)
    - [CONSOLIDATION_COMPLETE.md](./_archive/2025-12-16-consolidation/CONSOLIDATION_COMPLETE.md) — Consolidation completion summary
    - [CONSOLIDATION_SOURCE_MAP.md](./_archive/2025-12-16-consolidation/CONSOLIDATION_SOURCE_MAP.md) — Complete file mapping (139 files)
- **`docs/_reference/`** — Reference templates (not used by current workflow)
  - `docs/_reference/github-actions-ci.yml` — GitHub Actions CI template (reference only)

---

## Quick Start

**New to the project?** Start here:

1. **[README.md](../README.md)** - Project overview and getting started
2. **[ARCHITECTURE.md](../ARCHITECTURE.md)** - System architecture
3. **[docs/integration/QUICK_START.md](./integration/QUICK_START.md)** - Quick integration guide
4. **[BUILDING.md](../BUILDING.md)** - Build instructions

---

## Core Documentation

### Project Foundation

- **[README.md](../README.md)** - Main project entry point
- **[ARCHITECTURE.md](../ARCHITECTURE.md)** - System architecture and design
- **[BUILDING.md](../BUILDING.md)** - Build instructions and setup
- **[CHANGELOG.md](../CHANGELOG.md)** - Version history
- **[CONTRIBUTING.md](../CONTRIBUTING.md)** - Contribution guidelines
- **[SECURITY.md](../SECURITY.md)** - Security documentation
- **[API.md](../API.md)** - API reference
- **[USAGE.md](../USAGE.md)** - Usage guide

---

## Integration Documentation

**Location:** `docs/integration/`

- **[INTEGRATION_GUIDE.md](./integration/INTEGRATION_GUIDE.md)** - Complete integration guide
- **[QUICK_START.md](./integration/QUICK_START.md)** - Quick integration path
- **[TROUBLESHOOTING.md](./integration/TROUBLESHOOTING.md)** - Integration troubleshooting
- **[CHECKLIST.md](./integration/CHECKLIST.md)** - Integration checklist
- **[REFACTOR_NOTES.md](./integration/REFACTOR_NOTES.md)** - Integration refactor context and analysis

---

## Platform-Specific Documentation

### iOS

**Location:** `docs/platform/ios/`

- **[IOS_IMPLEMENTATION_CHECKLIST.md](./platform/ios/IOS_IMPLEMENTATION_CHECKLIST.md)** - iOS implementation checklist
- **[IMPLEMENTATION_DIRECTIVE.md](./platform/ios/IMPLEMENTATION_DIRECTIVE.md)** - iOS implementation directive
- **[DOCUMENTATION_REVIEW.md](./platform/ios/DOCUMENTATION_REVIEW.md)** - Documentation review
- **[CORE_DATA_MIGRATION.md](./platform/ios/CORE_DATA_MIGRATION.md)** - Core Data migration guide
- **[RECOVERY_SCENARIO_MAPPING.md](./platform/ios/RECOVERY_SCENARIO_MAPPING.md)** - Recovery scenario mapping
- **[ROLLOVER_EDGE_CASES.md](./platform/ios/ROLLOVER_EDGE_CASES.md)** - Rollover edge cases
- **[ROLLOVER_IMPLEMENTATION_REVIEW.md](./platform/ios/ROLLOVER_IMPLEMENTATION_REVIEW.md)** - Rollover implementation review
- **[ROLLOVER_QA.md](./platform/ios/ROLLOVER_QA.md)** - Rollover Q&A
- **[TROUBLESHOOTING.md](./platform/ios/TROUBLESHOOTING.md)** - iOS troubleshooting guide
- **[PREFETCH_GLOSSARY.md](./platform/ios/PREFETCH_GLOSSARY.md)** - Prefetch terminology

### Android

**Location:** `docs/platform/android/`

- **[IMPLEMENTATION_DIRECTIVE.md](./platform/android/IMPLEMENTATION_DIRECTIVE.md)** - Primary Android implementation directive
- **[PHASE1_DIRECTIVE.md](./platform/android/PHASE1_DIRECTIVE.md)** - Phase 1 directive
- **[PHASE2_DIRECTIVE.md](./platform/android/PHASE2_DIRECTIVE.md)** - Phase 2 directive
- **[PHASE3_DIRECTIVE.md](./platform/android/PHASE3_DIRECTIVE.md)** - Phase 3 directive
- **[ALARM_PERSISTENCE_DIRECTIVE.md](./platform/android/ALARM_PERSISTENCE_DIRECTIVE.md)** - Alarm persistence directive
- **[APP_ANALYSIS.md](./platform/android/APP_ANALYSIS.md)** - Android app analysis
- **[APP_IMPROVEMENT_PLAN.md](./platform/android/APP_IMPROVEMENT_PLAN.md)** - App improvement plan
- **[BUILDING.md](./platform/android/BUILDING.md)** - Android build guide
- **[DATABASE_CONSOLIDATION_PLAN.md](./platform/android/DATABASE_CONSOLIDATION_PLAN.md)** - Database consolidation plan

---

## Testing Documentation

**Location:** `docs/testing/`

### General Testing

- **[COMPREHENSIVE_GUIDE.md](./testing/COMPREHENSIVE_GUIDE.md)** - Comprehensive testing guide
- **[QUICK_REFERENCE.md](./testing/QUICK_REFERENCE.md)** - Testing quick reference
- **[MANUAL_SMOKE_TEST.md](./testing/MANUAL_SMOKE_TEST.md)** - Manual smoke test procedures
- **[NOTIFICATION_PROCEDURES.md](./testing/NOTIFICATION_PROCEDURES.md)** - Notification testing procedures
- **[REBOOT_PROCEDURE.md](./testing/REBOOT_PROCEDURE.md)** - Reboot testing procedure
- **[BOOT_RECEIVER_GUIDE.md](./testing/BOOT_RECEIVER_GUIDE.md)** - Boot receiver testing guide
- **[EMULATOR_GUIDE.md](./testing/EMULATOR_GUIDE.md)** - Standalone emulator guide
- **[LOCALHOST_GUIDE.md](./testing/LOCALHOST_GUIDE.md)** - Localhost testing guide

### iOS Testing

- **[IOS_PHASE1_TESTING_GUIDE.md](./testing/IOS_PHASE1_TESTING_GUIDE.md)** - iOS Phase 1 testing guide
- **[IOS_TEST_APP_SETUP.md](./testing/IOS_TEST_APP_SETUP.md)** - iOS test app setup
- **[IOS_LOGGING_GUIDE.md](./testing/IOS_LOGGING_GUIDE.md)** - iOS logging guide
- **[IOS_PREFETCH_TESTING.md](./testing/IOS_PREFETCH_TESTING.md)** - iOS prefetch testing
- **[IOS_TEST_APP_REQUIREMENTS.md](./testing/IOS_TEST_APP_REQUIREMENTS.md)** - iOS test app requirements

### Test App Documentation

Test app-specific documentation remains with the test apps but is indexed here:

**Android Test App:**
- `test-apps/android-test-app/docs/` - Android test app documentation
- `test-apps/android-test-app/docs/PHASE1_TEST0_GOLDEN.md` - Phase 1 Test 0 golden reference
- `test-apps/android-test-app/docs/PHASE1_TEST1_GOLDEN.md` - Phase 1 Test 1 golden reference

**iOS Test App:**
- `test-apps/ios-test-app/README.md` - iOS test app README
- `test-apps/ios-test-app/BUILD_NOTES.md` - Build notes
- `test-apps/ios-test-app/COMPILATION_SUMMARY.md` - Compilation summary

**Daily Notification Test App:**
- `test-apps/daily-notification-test/README.md` - Test app README
- `test-apps/daily-notification-test/docs/` - Test app documentation

---

## Alarm System Documentation

**Location:** `docs/alarms/`

The alarm system documentation is well-organized and kept in its current location:

- **[000-UNIFIED-ALARM-DIRECTIVE.md](./alarms/000-UNIFIED-ALARM-DIRECTIVE.md)** - Unified alarm directive
- **[01-platform-capability-reference.md](./alarms/01-platform-capability-reference.md)** - Platform capability reference
- **[02-plugin-behavior-exploration.md](./alarms/02-plugin-behavior-exploration.md)** - Plugin behavior exploration
- **[03-plugin-requirements.md](./alarms/03-plugin-requirements.md)** - Plugin requirements
- **[ACTIVATION-GUIDE.md](./alarms/ACTIVATION-GUIDE.md)** - Activation guide
- **[PHASE1-EMULATOR-TESTING.md](./alarms/PHASE1-EMULATOR-TESTING.md)** - Phase 1 emulator testing
- **[PHASE1-VERIFICATION.md](./alarms/PHASE1-VERIFICATION.md)** - Phase 1 verification
- **[PHASE2-EMULATOR-TESTING.md](./alarms/PHASE2-EMULATOR-TESTING.md)** - Phase 2 emulator testing
- **[PHASE2-VERIFICATION.md](./alarms/PHASE2-VERIFICATION.md)** - Phase 2 verification
- **[PHASE3-EMULATOR-TESTING.md](./alarms/PHASE3-EMULATOR-TESTING.md)** - Phase 3 emulator testing
- **[PHASE3-VERIFICATION.md](./alarms/PHASE3-VERIFICATION.md)** - Phase 3 verification

---

## Design & Research Documentation

**Location:** `docs/design/`

- **[STARRED_PROJECTS_POLLING_IMPLEMENTATION.md](./design/STARRED_PROJECTS_POLLING_IMPLEMENTATION.md)** - Starred projects polling implementation
- **[exploration-findings-initial.md](./design/exploration-findings-initial.md)** - Initial exploration findings
- **[explore-alarm-behavior-directive.md](./design/explore-alarm-behavior-directive.md)** - Alarm behavior exploration directive
- **[improve-alarm-directives.md](./design/improve-alarm-directives.md)** - Alarm improvement directives
- **[plugin-behavior-exploration-template.md](./design/plugin-behavior-exploration-template.md)** - Plugin behavior exploration template

---

## Feature-Specific Documentation

**Location:** `docs/`

### Storage & Database

- **[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

- **[NATIVE_FETCHER_CONFIGURATION.md](./NATIVE_FETCHER_CONFIGURATION.md)** - Native fetcher configuration

### Prefetch & Scheduling

- **[prefetch-scheduling-diagnosis.md](./prefetch-scheduling-diagnosis.md)** - Prefetch scheduling diagnosis
- **[prefetch-scheduling-trace.md](./prefetch-scheduling-trace.md)** - Prefetch scheduling trace

### Recovery & Startup

- **[app-startup-recovery-solution.md](./app-startup-recovery-solution.md)** - App startup recovery solution

### Platform Capabilities

- **[platform-capability-reference.md](./platform-capability-reference.md)** - Platform capability reference
- **[plugin-requirements-implementation.md](./plugin-requirements-implementation.md)** - Plugin requirements implementation

### Feature Implementation

- **[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

### Compliance & Operations

- **[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

### Deployment

- **[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

### Utilities

- **[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

---

## AI / Prompting / Automation Artifacts

**Location:** `docs/ai/`

These are derived operational artifacts for AI-assisted development:

- **[AI_INTEGRATION_GUIDE.md](./ai/AI_INTEGRATION_GUIDE.md)** - AI integration guide
- **[chatgpt-analysis-guide.md](./ai/chatgpt-analysis-guide.md)** - ChatGPT analysis guide
- **[chatgpt-assessment-package.md](./ai/chatgpt-assessment-package.md)** - ChatGPT assessment package
- **[chatgpt-files-overview.md](./ai/chatgpt-files-overview.md)** - ChatGPT files overview
- **[chatgpt-improvement-directives-template.md](./ai/chatgpt-improvement-directives-template.md)** - Improvement directives template
- **[code-summary-for-chatgpt.md](./ai/code-summary-for-chatgpt.md)** - Code summary for ChatGPT
- **[key-code-snippets-for-chatgpt.md](./ai/key-code-snippets-for-chatgpt.md)** - Key code snippets for ChatGPT

---

## Archive Documentation

**Location:** `docs/archive/2025-legacy-doc/`

Historical documentation preserved verbatim. See [CONSOLIDATION_SOURCE_MAP.md](./CONSOLIDATION_SOURCE_MAP.md) for complete archive listing.

**Notable archived content:**
- Historical directives (`doc/directives/`)
- Phase 1 summaries and analysis
- Historical build and integration notes
- Test app setup guides (superseded by current testing docs)

> **Note:** Archive documentation is discoverable but not listed in the main navigation. See "Archive & Reference-only" section above for archive locations.

---

## Document Map by Category

### By Purpose

| Category | Count | Location |
|----------|-------|----------|
| **Core Documentation** | 8 | Root + `docs/` |
| **Integration** | 5 | `docs/integration/` |
| **Platform (iOS)** | 10 | `docs/platform/ios/` |
| **Platform (Android)** | 9 | `docs/platform/android/` |
| **Testing** | 13 | `docs/testing/` |
| **Alarms** | 11 | `docs/alarms/` |
| **Design & Research** | 5 | `docs/design/` |
| **Feature-Specific** | 18 | `docs/` |
| **AI Artifacts** | 7 | `docs/ai/` |
| **Deployment** | 3 | `docs/` |
| **Test Apps** | 20+ | `test-apps/*/` |
| **Archive** | 29 | `docs/archive/2025-legacy-doc/` |

### By Status

- **Canonical (Active):** ~95 files
- **Merged:** ~15 files (content preserved in canonical docs)
- **Archived:** ~29 files (preserved verbatim)

---

## Finding Documentation

### By Task

**I want to...**

- **Integrate the plugin** → Start with [Integration Guide](./integration/INTEGRATION_GUIDE.md)
- **Build the project** → See [BUILDING.md](../BUILDING.md)
- **Understand architecture** → Read [ARCHITECTURE.md](../ARCHITECTURE.md)
- **Test on iOS** → See [iOS Testing Guide](./testing/IOS_PHASE1_TESTING_GUIDE.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)

### By Platform

- **iOS** → `docs/platform/ios/`
- **Android** → `docs/platform/android/`
- **Cross-Platform** → `docs/alarms/`, `docs/integration/`

### By Phase

- **Phase 1** → Platform-specific Phase 1 directives
- **Phase 2** → Platform-specific Phase 2 directives
- **Phase 3** → Platform-specific Phase 3 directives

---

## Maintenance

### Updating This Index

**Index-first rule:** New docs must be linked from `docs/00-INDEX.md` or explicitly placed under `_archive/` / `_reference/`.

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

### Consolidation Reference

For complete consolidation audit trail, see:
- **[CONSOLIDATION_SOURCE_MAP.md](./CONSOLIDATION_SOURCE_MAP.md)** - Complete file mapping

---

**Last Updated:** 2025-12-22  
**Maintained By:** Development Team