Files

Trent Larson 11561991bd rename 'docs' directory to 'doc'

2026-03-14 19:52:40 -06:00

19 KiB

Raw Blame History

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-23
Status: active
Baseline: See doc/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.

Policy & Contracts (Executable)

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

System Invariants: doc/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
Performance Characteristics: doc/PERFORMANCE.md — Performance characteristics and benchmarks
Troubleshooting Guide: doc/TROUBLESHOOTING.md — Common issues and solutions

Progress Tracking (Authoritative)

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

00-STATUS.md — Current status, invariants, next actions
01-CHANGELOG-WORK.md — Development changelog
02-OPEN-QUESTIONS.md — Open questions + closed decisions log
03-TEST-RUNS.md — Canonical record of what ran and when
04-PARITY-MATRIX.md — iOS/Android parity tracking
05-CHATGPT-FEEDBACK-PACKAGE.md — AI collaboration package
P2-DESIGN.md — P2 scope, invariants, and acceptance criteria (design-only)
P2.1-REFACTORING-COMPLETE.md — P2.1 native plugin refactoring complete summary (Android + iOS)
TODO.md — Project TODO and improvement tracking
TODAY_SUMMARY.md — Dated work summaries
SESSION_RECONSTITUTION.md — P2.1 Batch A session reconstitution
BATCH_A_COMPLETION_SUMMARY.md — P2.1 Batch A completion summary

Getting Started

Getting Started Guide — Installation, platform setup, and basic usage

Examples

Quick Start — Minimal working example
Common Patterns — Common integration patterns and best practices

Archive & Reference-only

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

Quick Start

New to the project? Start here:

README.md - Project overview and getting started
ARCHITECTURE.md - System architecture
doc/integration/QUICK_START.md - Quick integration guide
BUILDING.md - Build instructions

Core Documentation

Project Foundation

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

Integration Documentation

Location: doc/integration/

INTEGRATION_GUIDE.md - Complete integration guide
QUICK_START.md - Quick integration path
TROUBLESHOOTING.md - Integration troubleshooting
CHECKLIST.md - Integration checklist
REFACTOR_NOTES.md - Integration refactor context and analysis

Platform-Specific Documentation

iOS

Location: doc/platform/ios/

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

Android

Location: doc/platform/android/

IMPLEMENTATION_DIRECTIVE.md - Primary Android implementation directive
PHASE1_DIRECTIVE.md - Phase 1 directive
PHASE2_DIRECTIVE.md - Phase 2 directive
PHASE3_DIRECTIVE.md - Phase 3 directive
ALARM_PERSISTENCE_DIRECTIVE.md - Alarm persistence directive
APP_ANALYSIS.md - Android app analysis
APP_IMPROVEMENT_PLAN.md - App improvement plan
BUILDING.md - Android build guide
DATABASE_CONSOLIDATION_PLAN.md - Database consolidation plan

Testing Documentation

Location: doc/testing/

General Testing

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

iOS Testing

IOS_PHASE1_TESTING_GUIDE.md - iOS Phase 1 testing guide
IOS_TEST_APP_SETUP.md - iOS test app setup
IOS_LOGGING_GUIDE.md - iOS logging guide
IOS_PREFETCH_TESTING.md - iOS prefetch 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: doc/alarms/

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

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

Design & Research Documentation

Location: doc/design/

STARRED_PROJECTS_POLLING_IMPLEMENTATION.md - Starred projects polling implementation
exploration-findings-initial.md - Initial exploration findings
explore-alarm-behavior-directive.md - Alarm behavior exploration directive
improve-alarm-directives.md - Alarm improvement directives
plugin-behavior-exploration-template.md - Plugin behavior exploration template

Architecture (Storage & Core Tech)

Location: doc/architecture/

CROSS_PLATFORM_STORAGE_PATTERN.md - Cross-platform storage pattern
DATABASE_INTERFACES.md - Database interfaces
DATABASE_INTERFACES_IMPLEMENTATION.md - Database interfaces implementation
NATIVE_FETCHER_CONFIGURATION.md - Native fetcher configuration

Deployment

Location: doc/deployment/

deployment-guide.md - Deployment guide (primary)
DEPLOYMENT_CHECKLIST.md - Deployment checklist

Compliance & Operations

Location: doc/compliance/

accessibility-localization.md - Accessibility and localization
legal-store-compliance.md - Legal and store compliance
observability-dashboards.md - Observability dashboards

Feature-Specific (Integration, Design, Progress)

Integration (`doc/integration/`)

getting-valid-plan-ids.md - Getting valid plan IDs
host-request-configuration.md - Host request configuration
hydrate-plan-implementation-guide.md - Hydrate plan implementation guide
user-zero-stars-implementation.md - User zero stars implementation
capacitor-platform-service-clean-changes.md - Capacitor platform service changes
ACTION_PLAN_INTEGRATION_FIXES.md - Integration fixes action plan

Design (`doc/design/`) — plans, prefetch, recovery

P1.5-CONSOLIDATION-PLAN.md - P1.5 consolidation plan
P1.5-STEP4-CLUSTERS.md - P1.5 step 4 clusters
P1.5-STEP4-DECISIONS.md - P1.5 step 4 decisions
P2.1-NATIVE-REFACTORING-ANALYSIS.md - P2.1 native refactoring analysis
FEEDBACK-RESPONSE-PLAN.md - Feedback response plan
prefetch-scheduling-diagnosis.md - Prefetch scheduling diagnosis
prefetch-scheduling-trace.md - Prefetch scheduling trace
app-startup-recovery-solution.md - App startup recovery solution
plugin-requirements-implementation.md - Plugin requirements implementation

Progress (`doc/progress/`)

DEPLOYMENT_SUMMARY.md - Deployment summary
TODO-CLASSIFICATION.md - TODO classification

Platform — Android (`doc/platform/android/`)

CONSUMING_APP_ANDROID_NOTES.md - Consuming app Android notes
CONSUMING_APP_OPTIONAL_ANDROID_ID_CLEANUP.md - Optional Android ID cleanup
TIMESAFARI_ANDROID_COMPARISON.md - TimeSafari Android comparison

Platform Capabilities (canonical)

01-platform-capability-reference.md - Platform capability reference (canonical; deprecated root copy archived in _archive/)

Utilities (meta)

file-organization-summary.md - File organization summary

AI / Prompting / Automation Artifacts

Location: doc/ai/

These are derived operational artifacts for AI-assisted development:

AI_INTEGRATION_GUIDE.md - AI integration guide
chatgpt-analysis-guide.md - ChatGPT analysis guide
chatgpt-assessment-package.md - ChatGPT assessment package
chatgpt-files-overview.md - ChatGPT files overview
chatgpt-improvement-directives-template.md - Improvement directives template
code-summary-for-chatgpt.md - Code summary for ChatGPT
key-code-snippets-for-chatgpt.md - Key code snippets for ChatGPT

Archive Documentation

Location: doc/archive/2025-legacy-doc/

Historical documentation preserved verbatim. See 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 + `doc/`
Integration	5	`doc/integration/`
Platform (iOS)	10	`doc/platform/ios/`
Platform (Android)	9	`doc/platform/android/`
Testing	13	`doc/testing/`
Alarms	11	`doc/alarms/`
Design & Research	5	`doc/design/`
Architecture	4	`doc/architecture/`
Deployment	2	`doc/deployment/`
Compliance	3	`doc/compliance/`
Feature-Specific (integration, design, progress, platform)	14	`doc/integration/`, `doc/design/`, `doc/progress/`, `doc/platform/android/`
AI Artifacts	7	`doc/ai/`
Test Apps	20+	`test-apps/*/`
Archive	29	`doc/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
Build the project → See BUILDING.md
Understand architecture → Read ARCHITECTURE.md
Test on iOS → See iOS Testing Guide
Test on Android → See Android Test App Docs
Understand alarms → Browse Alarms Documentation
Troubleshoot → Check platform-specific troubleshooting guides
Deploy → See Deployment Guide

By Platform

iOS → doc/platform/ios/
Android → doc/platform/android/
Cross-Platform → doc/alarms/, doc/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 doc/00-INDEX.md or explicitly placed under _archive/ / _reference/.

When adding new documentation:

Place file in appropriate category directory
Add entry to this index in the correct section
Update the "Document Map by Category" table if needed
Update CONSOLIDATION_SOURCE_MAP.md if consolidating

Consolidation Reference

For complete consolidation audit trail, see:

CONSOLIDATION_SOURCE_MAP.md - Complete file mapping

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

19 KiB Raw Blame History