Reorganize docs: archive planning, add ADRs, update implementation status

[richardthe3rd]

Summary

This PR reorganizes the documentation structure to improve clarity and maintainability. Planning documents are archived with decisions extracted into Architecture Decision Records (ADRs), implementation status is updated to reflect completed work, and the docs README is streamlined.

Key Changes

Documentation Reorganization

• New docs/adr/ directory with two new ADRs:
  • ADR 0004: Path-Based URL Strategy for Deep Linking (explains festival-scoped URL design)
  • ADR 0005: E2E Testing Strategy (documents decision to use Playwright for URL smoke tests instead of Patrol)
• New docs/planning/archive/ directory containing completed/superseded planning docs:
  • archive/deep-linking/ -- Phase 1 complete, decisions captured in ADR 0004
  • archive/patrol-firebase-testing/ -- not implemented, decision captured in ADR 0005
  • archive/ci-review/ -- implemented, decisions captured in ADRs 0001-0003
• Removed from main planning/ -- Patrol Firebase Testing and deep-linking docs (moved to archive)

Implementation Status Updates

• docs/code/accessibility.md: Updated from "NOT IMPLEMENTED" to "✅ Implemented" with 53+ Semantics widgets and 9 dedicated tests
• docs/code/navigation.md and docs/code/ui-components.md: Renamed (previously unnamed files)
• docs/code/domain-architecture.md: Added to code/ documentation
• docs/code/widget-standards.md: Added to code/ documentation

README Improvements

• docs/README.md: Completely restructured for clarity:
  • Removed verbose descriptions, kept concise summaries
  • Reorganized sections: code/ → adr/ → processes/ → tooling/ → planning/ → archive/
  • Added "Quick Reference" section with common lookup patterns
  • Removed "Documentation Status" section (status now clear from structure)
  • Removed "Alternatives & Conflicting Approaches" section (conflicts now documented in ADRs)
  • Simplified "Contributing to Docs" guidelines
  • Updated last modified date to February 2026

Content Updates

• AGENTS.md: Updated API documentation paths from docs/api/ to docs/code/api/
• README.md:
  • Updated E2E testing description (removed Patrol mention, clarified Playwright scope)
  • Removed links to archived Patrol Firebase Testing docs
  • Added link to ADR 0005 for E2E testing rationale
• docs/processes/ci-cd.md:
  • Renamed "Flutter App CI/CD" workflow to "CI"
  • Updated coverage minimum from 25% to 70%
• docs/todos.md:
  • Added 3 CRITICAL bugs (C1-C3): dart:io import, sequential API fetching, festival selector URL
  • Added 7 HIGH priority items (H3-H7): festival validation, mutable state, clear filters, about screen navigation, favorites sync
  • Added 7 MEDIUM priority items (M1-M7): prefix matching, UTF-8 decoding, app bar display, search debouncing, accessibility hints
  • Updated summary: 33 active issues (up from 18)
  • Updated last modified date to 2026-02-06
• docs/tooling/flutter-web-testing.md: Updated Semantics widget count from 24 to 53+, added reference to accessibility.md

Notable Details

• ADRs follow the standard format with Status, Date, Deciders, Context, Decision, Alternatives, Consequences, and Implementation sections
• Archive directory preserves historical context while keeping main docs focused on current implementation
• All cross-references updated to point to new locations (e.g., docs/planning/ → docs/planning/archive/)
• Todos list now distinguishes CRITICAL bugs (blocking production) from HIGH/MEDIUM priority improvements

https://claude.ai/code/session_01L2cfZXThqbJdZmozMDr4DQ

[github-actions]

LCOV of commit c9a9d74 during CI #30

Summary coverage rate:
  lines......: 77.5% (2228 of 2873 lines)
  functions..: no data found
  branches...: no data found

Files changed coverage rate: n/a

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

This PR reorganizes and updates the project documentation by moving completed planning material into an archive, extracting key decisions into ADRs, and refreshing “current state” docs (accessibility, routing/testing, CI/CD). It also includes a couple of small web-platform metadata tweaks.

Changes:

• Added ADRs for deep-linking URL strategy and E2E testing strategy; archived prior planning/review docs under docs/planning/archive/.
• Updated current docs (docs index, accessibility status, CI/CD coverage requirements, tooling/testing notes, TODO tracking).
• Minor web changes: added PWA manifest id and relaxed the viewport meta tag to allow user scaling.

Reviewed changes

Copilot reviewed 13 out of 31 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
web/manifest.json	Adds a PWA id field to stabilize install identity.
web/index.html	Updates viewport meta tag to improve zoom/accessibility behavior.
docs/tooling/flutter-web-testing.md	Updates Semantics widget count and links to the accessibility inventory doc.
docs/todos.md	Expands/refreshes the tracked bug + improvement backlog and updates last-modified date.
docs/processes/safe-cache-strategy.md	Adds a new guide describing “safe” GitHub Actions caching patterns.
docs/processes/ci-cd.md	Renames the main workflow to “CI” and updates documented coverage minimum to 70%.
docs/planning/archive/patrol-firebase-testing/summary.md	Archives Patrol/Firebase Test Lab evaluation summary.
docs/planning/archive/patrol-firebase-testing/review.md	Archives the detailed Patrol/Firebase Test Lab review.
docs/planning/archive/patrol-firebase-testing/readme-review.md	Archives a meta “documentation review” for the Patrol plan bundle.
docs/planning/archive/patrol-firebase-testing/plan.md	Archives the Patrol/Firebase Test Lab implementation plan.
docs/planning/archive/deep-linking/testing-strategy.md	Archives the deep-linking testing strategy document.
docs/planning/archive/deep-linking/phase-0-guide.md	Archives the deep-linking Phase 0 implementation guide.
docs/planning/archive/deep-linking/design.md	Archives the deep-linking design document.
docs/planning/archive/deep-linking/design-review.md	Archives the deep-linking design review.
docs/planning/archive/deep-linking/PHASE-1-HANDOFF.md	Archives Phase 1 handoff notes for deep linking.
docs/planning/archive/deep-linking/PHASE-1-COMPLETE.md	Archives a Phase 1 completion summary for deep linking.
docs/planning/archive/ci-review/ci-review.md	Archives CI/CD review notes.
docs/planning/archive/ci-review/ci-naming-recommendations.md	Archives CI naming recommendations.
docs/planning/archive/ci-review/ci-improvements-summary.md	Fixes archived CI review links for new doc locations.
docs/code/ui-components.md	Adds “current code” documentation for shared UI components.
docs/code/navigation.md	Adds “current code” documentation for navigation helper utilities.
docs/code/accessibility.md	Updates accessibility status to “implemented” and lists coverage + tests.
docs/adr/README.md	Updates ADR index to include ADR 0004 and 0005.
docs/adr/0004-path-based-url-strategy.md	New ADR documenting path-based, festival-scoped URL strategy.
docs/adr/0005-e2e-testing-strategy.md	New ADR documenting Playwright-only URL smoke testing scope.
docs/README.md	Restructures the docs landing page to match the new organization (code → ADRs → processes → tooling → planning → archive).
README.md	Updates top-level README E2E testing section (removes Patrol mention, links ADR 0005).
AGENTS.md	Updates API documentation links from docs/api/ to docs/code/api/.
.gitignore	Fixes the mock un-ignore pattern and adds screenshots/ to ignored paths.

[github-actions]

🚀 Cloudflare Pages Preview

Your preview deployment is ready!

Preview URL: https://claude-review-flutter-app-u7.staging-cambeerfestival.pages.dev

This preview will be automatically updated when you push new commits to this PR.