chore(release): reorganize docs and pause Wear Play submission

- restructure `documents/` into `guides/`, `planning/`, and `reference/`
- add new guides for setup, contributing, deployment, troubleshooting, and performance
- update `documents/README.md` and add `documents/REORGANIZATION.md`
- temporarily disable Wear artifact validation/release asset/upload steps in `.github/workflows/eas-build.yml`
- bump `apps/mobile` version to `1.1.8` and update root `CHANGELOG.md`

Author: Lalit Sharma

.github/workflows/eas-build.yml

@@ -458,10 +458,11 @@ jobs:
             exit 1
           fi
 
-          if [ ! -f "$artifact_root/$wear_aab_asset" ]; then
-            echo "Missing Wear OS artifact at $artifact_root/$wear_aab_asset."
-            exit 1
-          fi
+          # Wear OS artifact validation disabled for now
+          # if [ ! -f "$artifact_root/$wear_aab_asset" ]; then
+          #   echo "Missing Wear OS artifact at $artifact_root/$wear_aab_asset."
+          #   exit 1
+          # fi
 
       - name: Prepare GitHub release assets
         id: release_assets
@@ -474,7 +475,6 @@ jobs:
             echo "artifacts/submission/${{ steps.artifact_names.outputs.ios }}"
             echo "artifacts/submission/${{ steps.artifact_names.outputs.android_aab }}"
             echo "artifacts/submission/${{ steps.artifact_names.outputs.android_apk }}"
-            echo "artifacts/submission/${{ steps.artifact_names.outputs.wear_aab }}"
             echo "EOF"
           } >> "$GITHUB_OUTPUT"
 
@@ -700,24 +700,25 @@ jobs:
           releaseFiles: artifacts/submission/${{ steps.artifact_names.outputs.android_aab }}
           track: internal
 
-      - name: Upload Wear OS artifact to Google Play (with notes)
-        if: ${{ steps.store_notes.outputs.has_store_notes == 'true' }}
-        uses: r0adkll/upload-google-play@v1
-        with:
-          serviceAccountJsonPlainText: ${{ secrets.GOOGLE_PLAY_SERVICE_ACCOUNT_JSON }}
-          packageName: com.lallimaven.eclipsetimer.wear
-          releaseFiles: artifacts/submission/${{ steps.artifact_names.outputs.wear_aab }}
-          track: internal
-          whatsNewDirectory: ${{ steps.store_notes.outputs.play_whatsnew_dir }}
-
-      - name: Upload Wear OS artifact to Google Play
-        if: ${{ steps.store_notes.outputs.has_store_notes != 'true' }}
-        uses: r0adkll/upload-google-play@v1
-        with:
-          serviceAccountJsonPlainText: ${{ secrets.GOOGLE_PLAY_SERVICE_ACCOUNT_JSON }}
-          packageName: com.lallimaven.eclipsetimer.wear
-          releaseFiles: artifacts/submission/${{ steps.artifact_names.outputs.wear_aab }}
-          track: internal
+      # TODO: Re-enable Wear OS uploads once the package is set up in Google Play Store
+      # - name: Upload Wear OS artifact to Google Play (with notes)
+      #   if: ${{ steps.store_notes.outputs.has_store_notes == 'true' }}
+      #   uses: r0adkll/upload-google-play@v1
+      #   with:
+      #     serviceAccountJsonPlainText: ${{ secrets.GOOGLE_PLAY_SERVICE_ACCOUNT_JSON }}
+      #     packageName: com.lallimaven.eclipsetimer.wear
+      #     releaseFiles: artifacts/submission/${{ steps.artifact_names.outputs.wear_aab }}
+      #     track: internal
+      #     whatsNewDirectory: ${{ steps.store_notes.outputs.play_whatsnew_dir }}
+      #
+      # - name: Upload Wear OS artifact to Google Play
+      #   if: ${{ steps.store_notes.outputs.has_store_notes != 'true' }}
+      #   uses: r0adkll/upload-google-play@v1
+      #   with:
+      #     serviceAccountJsonPlainText: ${{ secrets.GOOGLE_PLAY_SERVICE_ACCOUNT_JSON }}
+      #     packageName: com.lallimaven.eclipsetimer.wear
+      #     releaseFiles: artifacts/submission/${{ steps.artifact_names.outputs.wear_aab }}
+      #     track: internal
 
       - name: Create GitHub release with mobile artifacts
         uses: softprops/action-gh-release@v2

CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.8] — 2026-02-21
+
+### Added
+- Added a new docs guide set under `documents/guides/`: setup and development, contributing, deployment, troubleshooting, and performance optimization.
+- Added `documents/REORGANIZATION.md` to document the new documentation layout and migration summary.
+
+### Changed
+- Reorganized `documents/` into purpose-based sections (`guides/`, `planning/`, `reference/`) and updated `documents/README.md` with quick-start, role-based reading paths, and maintenance standards.
+- Updated `.github/workflows/eas-build.yml` to temporarily disable Wear OS artifact validation, release asset packaging, and Google Play upload steps until the Wear package is ready in Play Console.
+
 ## [1.1.7] — 2026-02-21
 
 ### Changed

apps/mobile/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eclipse-timer/mobile",
-  "version": "1.1.7",
+  "version": "1.1.8",
   "private": true,
   "main": "index.js",
   "scripts": {

documents/README.md

@@ -1,40 +1,113 @@
 # Eclipse Timer Documentation
 
-This folder contains the project documentation for the `eclipse-timer` monorepo.
+This folder contains comprehensive documentation for the Eclipse Timer project—a monorepo for calculating and visualizing eclipse circumstances.
+
+## Quick Start
+
+**New to the project?** Start here:
+
+1. [Setup and Development](guides/setup-and-development.md) – Install and configure your environment
+2. [System Overview](high-level/system-overview.md) – Understand the architecture
+3. [Contributing Guide](guides/contributing.md) – Learn how to make changes
 
 ## Documentation Map
 
-### Planning
-- `documents/01-documentation-plan.md`
-- `documents/CHANGELOG.md`
-- `documents/in-app-alarm-rework-plan.md`
-- `documents/release-plan-eas.md`
-- `documents/self-hosted-macos-runner.md`
-- `documents/wearable-companion-implementation-plan.md`
-
-### High-Level
-- `documents/high-level/system-overview.md`
-  - Includes Mermaid component and sequence architecture diagrams.
-- `documents/high-level/user-flow-and-product-behavior.md`
-- `documents/high-level/development-workflow.md`
-- `documents/high-level/wearable-companion-requirements.md`
-
-### Low-Level
-- `documents/low-level/mobile-app-internals.md`
-- `documents/low-level/engine-algorithm.md`
-- `documents/low-level/data-contracts.md`
-- `documents/low-level/wearable-companion-technical-design.md`
-
-## Reading Order
-1. `documents/high-level/system-overview.md`
-2. `documents/high-level/user-flow-and-product-behavior.md`
-3. `documents/low-level/data-contracts.md`
-4. `documents/low-level/engine-algorithm.md`
-5. `documents/low-level/mobile-app-internals.md`
-6. `documents/high-level/wearable-companion-requirements.md`
-7. `documents/low-level/wearable-companion-technical-design.md`
-
-## Maintenance
-- Update high-level docs when package boundaries, app behavior, or scripts change.
-- Update low-level docs whenever equations, types, or state transitions change.
-- Prefer linking to code paths as source of truth.
+### Guides (How-To)
+- [Setup and Development](guides/setup-and-development.md) – Installation, common commands, monorepo workflow
+- [Contributing Guide](guides/contributing.md) – Code style, testing, submission process
+- [Deployment Guide](guides/deployment.md) – Building for release, EAS, app store submission
+- [Troubleshooting Guide](guides/troubleshooting.md) – Common issues and solutions
+- [Performance Optimization](guides/performance-optimization.md) – Profiling, bottlenecks, and optimization
+
+### High-Level Documentation (Architecture & Behavior)
+- [System Overview](high-level/system-overview.md) – Monorepo structure, package boundaries, data flow
+- [User Flow and Product Behavior](high-level/user-flow-and-product-behavior.md) – User interactions, app states, screens
+- [Wearable Companion Requirements](high-level/wearable-companion-requirements.md) – Requirements and design for wearable integration
+
+### Low-Level Documentation (Implementation Details)
+- [Data Contracts](low-level/data-contracts.md) – TypeScript types, catalog schema, data structures
+- [Engine Algorithm](low-level/engine-algorithm.md) – Eclipse calculations, math, root solving
+- [Mobile App Internals](low-level/mobile-app-internals.md) – React state, handlers, UI integration
+- [Wearable Technical Design](low-level/wearable-companion-technical-design.md) – Implementation details for wearable
+
+### Planning & Tracking
+- [Documentation Plan](planning/01-documentation-plan.md) – Goals, standards, and maintenance triggers
+- [In-App Alarm Rework Plan](planning/in-app-alarm-rework-plan.md) – Alarm system redesign proposal
+- [Wearable Implementation Plan](planning/wearable-companion-implementation-plan.md) – Wearable rollout phases
+- [Release Plan (EAS)](planning/release-plan-eas.md) – EAS build and release strategy
+- [Self-Hosted macOS Runner](planning/self-hosted-macos-runner.md) – CI/CD setup for native builds
+- [Tech Debt](planning/tech-debt.md) – Known issues and improvement areas
+
+### Reference
+- [CHANGELOG](reference/CHANGELOG.md) – Release history and version notes
+- [Store Metadata](reference/store-metadata.md) – App store descriptions, screenshots, keywords
+- [Store Privacy Declarations](reference/store-privacy-declarations.md) – Privacy policy and data handling
+- [Testing Scenarios](reference/testing-scenarios.md) – QA test cases and edge cases
+
+## Reading Paths by Role
+
+### Product Owner / Project Manager
+1. [System Overview](high-level/system-overview.md)
+2. [User Flow and Product Behavior](high-level/user-flow-and-product-behavior.md)
+3. [Wearable Companion Requirements](high-level/wearable-companion-requirements.md)
+4. [Planning documents](planning/) as needed
+
+### Mobile App Developer
+1. [Setup and Development](guides/setup-and-development.md)
+2. [System Overview](high-level/system-overview.md)
+3. [User Flow and Product Behavior](high-level/user-flow-and-product-behavior.md)
+4. [Mobile App Internals](low-level/mobile-app-internals.md)
+5. [Data Contracts](low-level/data-contracts.md)
+
+### Engine / Math Developer
+1. [Setup and Development](guides/setup-and-development.md)
+2. [System Overview](high-level/system-overview.md)
+3. [Engine Algorithm](low-level/engine-algorithm.md)
+4. [Data Contracts](low-level/data-contracts.md)
+
+### Catalog / Data Developer
+1. [Setup and Development](guides/setup-and-development.md)
+2. [Data Contracts](low-level/data-contracts.md)
+3. [Store Metadata](reference/store-metadata.md)
+
+### QA / Tester
+1. [Testing Scenarios](reference/testing-scenarios.md)
+2. [Troubleshooting Guide](guides/troubleshooting.md)
+3. [Deployment Guide](guides/deployment.md) (for release testing)
+
+### Release Manager / DevOps
+1. [Deployment Guide](guides/deployment.md)
+2. [Release Plan (EAS)](planning/release-plan-eas.md)
+3. [Self-Hosted macOS Runner](planning/self-hosted-macos-runner.md)
+
+## Documentation Standards
+
+- **Units are explicit**: Always include units (`hours`, `seconds`, `degrees`, `meters`, `UTC`)
+- **Current behavior first**: Document what is, mark future or placeholder logic clearly
+- **Code is source of truth**: Include direct file/line references to code
+- **Examples are aligned**: Use `packages/catalog/src/catalog.sample.json` for examples
+- **Searchable**: Use clear headings and organization
+
+## When to Update Docs
+
+Update documentation whenever these change:
+
+- **Types**: `packages/shared/src/types.ts`
+- **Engine**: `packages/engine/src/circumstances/compute.ts`, `functions.ts`
+- **Mobile App**: `apps/mobile/src/App.tsx`, navigation, state management
+- **Setup**: Root `package.json` scripts, `pnpm-workspace.yaml`, or `.env` files
+- **User flows**: Major UI changes, new screens, or state transitions
+
+See [Documentation Plan](planning/01-documentation-plan.md) for more details.
+
+## Contributing to Docs
+
+1. Use Markdown formatting for clarity
+2. Link to related sections and external resources
+3. Include code examples where helpful
+4. Update the [Documentation Plan](planning/01-documentation-plan.md) if adding new docs
+5. Keep the main README synchronized
+
+---
+
+**Have questions?** See [Troubleshooting Guide](guides/troubleshooting.md) or check relevant deep-dive documentation.

documents/REORGANIZATION.md

@@ -0,0 +1,123 @@
+# Documentation Reorganization Summary
+
+## What Changed
+
+The `/documents` folder has been reorganized from a flat structure into a logical, category-based hierarchy. This improves discoverability and makes it easier for contributors to find relevant documentation.
+
+### Old Structure
+```
+documents/
+├── README.md
+├── 01-documentation-plan.md
+├── CHANGELOG.md
+├── in-app-alarm-rework-plan.md
+├── release-plan-eas.md
+├── self-hosted-macos-runner.md
+├── store-metadata.md
+├── store-privacy-declarations.md
+├── tech-debt.md
+├── testing-scenarios.md
+├── wearable-companion-implementation-plan.md
+├── high-level/
+└── low-level/
+```
+
+### New Structure
+```
+documents/
+├── README.md (updated with new organization)
+├── guides/                              (NEW)
+│   ├── setup-and-development.md        (NEW)
+│   ├── contributing.md                 (NEW)
+│   ├── deployment.md                   (NEW)
+│   ├── troubleshooting.md              (NEW)
+│   └── performance-optimization.md     (NEW)
+├── high-level/                          (existing)
+│   ├── development-workflow.md
+│   ├── system-overview.md
+│   ├── user-flow-and-product-behavior.md
+│   └── wearable-companion-requirements.md
+├── low-level/                           (existing)
+│   ├── data-contracts.md
+│   ├── engine-algorithm.md
+│   ├── mobile-app-internals.md
+│   └── wearable-companion-technical-design.md
+├── planning/                            (NEW)
+│   ├── 01-documentation-plan.md
+│   ├── in-app-alarm-rework-plan.md
+│   ├── release-plan-eas.md
+│   ├── self-hosted-macos-runner.md
+│   ├── tech-debt.md
+│   └── wearable-companion-implementation-plan.md
+└── reference/                           (NEW)
+    ├── CHANGELOG.md
+    ├── store-metadata.md
+    ├── store-privacy-declarations.md
+    └── testing-scenarios.md
+```
+
+## New Folders
+
+### 📖 `guides/` - How-To Documentation
+Practical guides for developers, maintainers, and contributors:
+
+- **setup-and-development.md** – Installation, common commands, monorepo workflow
+- **contributing.md** – Code style, testing, and submission guidelines
+- **deployment.md** – Building for release, EAS, app store submission
+- **troubleshooting.md** – Common issues and solutions
+- **performance-optimization.md** – Profiling, bottlenecks, and optimization tips
+
+### 📋 `planning/` - Planning & Proposals
+Project planning documents, proposals, and tracking:
+
+- **01-documentation-plan.md** – Documentation goals and standards
+- **in-app-alarm-rework-plan.md** – Alarm system redesign proposal
+- **wearable-companion-implementation-plan.md** – Wearable integration phases
+- **release-plan-eas.md** – EAS build and release strategy
+- **self-hosted-macos-runner.md** – CI/CD setup for native builds
+- **tech-debt.md** – Known issues and improvement areas
+
+### 📚 `reference/` - Reference Material
+Metadata, release notes, and compliance documentation:
+
+- **CHANGELOG.md** – Release history and version notes
+- **store-metadata.md** – App store descriptions and keywords
+- **store-privacy-declarations.md** – Privacy policy and data handling
+- **testing-scenarios.md** – QA test cases and edge cases
+
+## New Stub Documents Created
+
+The following new documents were created as starting points and should be refined over time:
+
+1. **guides/setup-and-development.md** – Refactored from high-level/development-workflow.md
+2. **guides/contributing.md** – New contributor guide with code style and workflow
+3. **guides/deployment.md** – Complete guide for building and releasing
+4. **guides/troubleshooting.md** – Comprehensive troubleshooting for all layers
+5. **guides/performance-optimization.md** – Profiling and optimization strategies
+
+## Benefits
+
+✅ **Better Organization** – Documents are grouped by purpose, not just type  
+✅ **Faster Discovery** – Readers find what they need by category  
+✅ **Clear Paths** – README now provides role-based reading paths  
+✅ **Easier Maintenance** – Related docs live together  
+✅ **Scalable** – New guides/reference docs fit naturally into existing structure  
+✅ **Comprehensive** – Filled gaps in documentation (setup, deployment, troubleshooting)
+
+## What Didn't Change
+
+- **high-level/** – All architecture and behavior docs remain as-is
+- **low-level/** – All implementation and algorithm docs remain as-is
+- **Document content** – No existing content was modified (only organization)
+
+## Next Steps
+
+1. **Review** the new guides to ensure they meet your team's needs
+2. **Update** guides/setup-and-development.md if development workflow differs
+3. **Customize** guides/deployment.md with your team's specific deployment process
+4. **Link** the main README in your root repo if there's one
+5. **Communicate** the new structure to your team
+
+---
+
+For questions or updates to the documentation structure, see [README.md](README.md) and [planning/01-documentation-plan.md](planning/01-documentation-plan.md).