> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Development Documentation Index

> Index of development guides, setup, and conventions for the Encore OS Platform.

**Version:** 1.1.0
**Last Updated:** 2026-04-11
**Status:** Active

Index of development guides, setup, and conventions for the Encore OS Platform.

***

## Quick Start

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

1. **[SETUP\_QUICK\_START.md](/development/SETUP_QUICK_START)** ⭐ **First-Time Setup**
   * Environment variables checklist
   * PWA setup verification
   * CodeRabbit setup
   * First-time developer onboarding

2. **[DEVELOPMENT\_QUICK\_REFERENCE.md](/development/DEVELOPMENT_QUICK_REFERENCE)** ⭐ **Daily Reference**
   * Common commands (CodeRabbit, build, test)
   * Common patterns (spacing, colors, icons)
   * Common components (PageContainer, ResponsiveFormLayout)
   * Common gotchas (React.lazy, loading states, permissions)

***

## Common Tasks

### Setup & Configuration

* **[SETUP\_QUICK\_START.md](/development/SETUP_QUICK_START)** - Quick setup checklists
* **[ENVIRONMENT\_VARIABLES.md](/development/ENVIRONMENT_VARIABLES)** - Environment configuration
* **[PWA\_SETUP.md](/development/PWA_SETUP)** - PWA configuration
* **[CODERABBIT\_GUIDE.md](/development/CODERABBIT_GUIDE)** - CodeRabbit setup

### Code Review Workflow

* **[CODE\_REVIEW\_PROCESS.md](/development/CODE_REVIEW_PROCESS)** - Complete review process with quick start
* **[DEVELOPMENT\_QUICK\_REFERENCE.md](/development/DEVELOPMENT_QUICK_REFERENCE)** - CodeRabbit commands
* **[PR-313-DEEP-REVIEW.md](https://github.com/Encore-OS/encoreos/blob/development/docs/development/PR-313-DEEP-REVIEW.md)** - Forensic review template for large/conflicting PRs
* **[PR-313-SPLIT-RELEASE-PLAN.md](https://github.com/Encore-OS/encoreos/blob/development/docs/development/PR-313-SPLIT-RELEASE-PLAN.md)** - Example wave-based decomposition of oversized production PRs

### Security & dependencies

* **[DEPENDENCY\_SECURITY.md](/development/DEPENDENCY_SECURITY)** - npm audit, lockfile workflow, `overrides`, Deno `npm:` review cadence (not covered by `npm audit`), Dependabot

### CI & quality gates

* **[CI\_PIPELINE.md](/development/CI_PIPELINE)** — Maps [.github/workflows/build.yml](https://github.com/Encore-OS/encoreos/blob/development/.github/workflows/build.yml) to local commands (debug red PRs)
* **[RLS\_CI\_CD\_GUIDE.md](/development/RLS_CI_CD_GUIDE)** — RLS tests in CI and local parity
* **[REPO\_SYNC\_WORKFLOW.md](/development/REPO_SYNC_WORKFLOW)** — Two-way reconciliation between canonical `encoreos` and the `encoreos_lovable` fork (drift check, sync commands, automation)
* **Full test matrix:** [TESTING\_SETUP\_AND\_RUN.md](/testing/TESTING_SETUP_AND_RUN)
* **Doc link/version health:** `npm run validate-docs` and `npm run check-doc-versions`

### Spacing & Layout

* **[SPACING\_AND\_UX\_STANDARDS.md](/development/SPACING_AND_UX_STANDARDS)** - Complete spacing guide (includes quick reference)
* **[DEVELOPMENT\_QUICK\_REFERENCE.md](/development/DEVELOPMENT_QUICK_REFERENCE)** - Quick spacing patterns

### Icons & Colors

* **[ICON\_GUIDE.md](/development/ICON_GUIDE)** - Icon design and usage
* **[SEMANTIC\_COLORS.md](/development/SEMANTIC_COLORS)** - Color token reference

### Navigation

**Start Here:** [Constitution §6.3](https://github.com/Encore-OS/encoreos/blob/development/constitution.md) (current: see docs/VERSIONS.md) defines the core navigation requirements.

* **[mobile-navigation-guide.md](/development/mobile-navigation-guide)** - Mobile navigation patterns (bottom nav, safe areas, touch targets, mobile breadcrumbs)
* **[breadcrumb-implementation-guide.md](/development/breadcrumb-implementation-guide)** - Breadcrumb implementation (route labels, auto-generation, customization)
* **[NAVIGATION\_STANDARD.md](/architecture/standards/NAVIGATION_STANDARD)** - Navigation standard (policies, sub-modules, route taxonomy)

**Component Documentation:** [src/platform/navigation/README.md](https://github.com/Encore-OS/encoreos/blob/development/src/platform/navigation/README.md)

***

## Setup & Configuration

### PWA & Mobile Setup

* **[PWA Setup](/development/PWA_SETUP)** ⭐ **Start Here**
  * Complete PWA configuration guide
  * Icon generation and setup
  * Service worker configuration
  * Performance optimization
  * Mobile safe area support
  * Testing checklist

* **[Mobile Navigation Guide](/development/mobile-navigation-guide)**
  * Mobile navigation architecture
  * Bottom navigation bar implementation
  * Mobile menu patterns
  * Safe area insets guide
  * Touch target guidelines
  * Accessibility requirements
  * Navigation review findings
  * Dashboard standards integration
  * Quick actions pattern

### Development Tools

* **[CodeRabbit Guide](/development/CODERABBIT_GUIDE)** ⭐ **Complete Reference**
  * Setup and installation
  * Configuration details
  * CLI commands and output modes
  * Workflow patterns (CodeRabbit + Lovable)
  * Reporting guide
  * Best practices
  * Troubleshooting

* **[CODERABBIT\_CURSOR\_REVIEW\_CONTEXT.md](/development/CODERABBIT_CURSOR_REVIEW_CONTEXT)** — CodeRabbit-oriented PR review context for Cursor. For CodeRabbit setup and YAML, use **CodeRabbit Guide** above.

* **[CODE\_REVIEW\_PROCESS.md](/development/CODE_REVIEW_PROCESS)** ⭐ **Review Workflow**
  * Quick start workflow
  * Daily commands reference
  * Pattern identification
  * Documentation update process

### Environment & Configuration

* **[Environment Variables](/development/ENVIRONMENT_VARIABLES)** — Canonical list of env vars; required vs optional, local vs production.
* **[ENVIRONMENT\_CONFIG.md](/development/ENVIRONMENT_CONFIG)** — Supabase project IDs and per-environment credentials (dev, production) and how build-time creds resolve.

### Supabase (hub)

All Supabase-related setup, CLI, and troubleshooting in one place. For required variables, see [ENVIRONMENT\_VARIABLES.md](/development/ENVIRONMENT_VARIABLES) and [integrations/SUPABASE\_SETUP.md](/integrations/SUPABASE_SETUP).

| Doc                                                                                                      | Purpose                                          |
| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| [SUPABASE\_SETUP](/integrations/SUPABASE_SETUP)                                                          | Production Supabase configuration, project setup |
| [SUPABASE\_MULTI\_ENV\_SETUP.md](/development/supabase/SUPABASE_MULTI_ENV_SETUP)                         | Local, staging, production env config            |
| [SUPABASE\_CLI\_LOCAL\_WORKFLOW.md](/development/supabase/SUPABASE_CLI_LOCAL_WORKFLOW)                   | Migrations, `supabase start`, `db reset`, link   |
| [Troubleshooting Guide](/development/TROUBLESHOOTING_GUIDE#supabase-remote-migration-versions-not-found) | Fix "Remote migration versions not found"        |
| [MCP Usage Guide](/development/MCP_USAGE#supabase-mcp-usage-required)                                    | When to use Supabase MCP vs CLI                  |
| [SUPABASE\_AUTH\_401\_TROUBLESHOOTING.md](/development/supabase/SUPABASE_AUTH_401_TROUBLESHOOTING)       | 401 auth errors and fixes                        |

See also [supabase/README.md](/development/supabase/index) for a short index in this tree.

***

## Patterns & Standards

### UI/UX Standards

* **[UI/UX Standards](/development/UI_UX_STANDARDS)** ⭐ **Canonical Standards**
  * Complete UI/UX patterns and requirements
  * Design system tokens and usage
  * Page templates and required states
  * Navigation and information architecture
  * Mobile-first requirements
  * Performance UX patterns
  * Accessibility standards
* **[UI Consistency Review](https://github.com/Encore-OS/encoreos/blob/development/docs/development/UI_CONSISTENCY_REVIEW.md)** — Spec/PR checklist for dialogs, `PageContainer`, skeletons, `EmptyState`, semantic tokens
* **[Spec Command Cheat Sheet](/development/SPEC_COMMAND_CHEATSHEET)** — Tiered map of Cursor spec commands (`eos-spec next`, validate, review, tasks, complete)

### Navigation

* **[Navigation Guide Index](/development/NAVIGATION_GUIDE_INDEX)** ⭐ **Start Here**
  * Central index for all navigation documentation
  * Quick navigation by topic
  * Common use cases and workflows
  * Links to all navigation guides

### UI Patterns

* **[Icon Style Guide](/development/ICON_GUIDE)**
  * Icon design guidelines
  * Icon usage patterns
  * Icon generation process

* **[SPACING\_AND\_UX\_STANDARDS.md](/development/SPACING_AND_UX_STANDARDS)** ⭐ **Complete Guide**
  * Quick reference section at top
  * Spacing and layout patterns
  * Responsive spacing guidelines
  * Safe area considerations
  * Page container patterns
  * Grid and form spacing

* **[Settings Pattern Guide](/development/settings-pattern-guide)**
  * Settings page implementation
  * Module settings pattern
  * Organization-level settings
  * Upsert pattern and compliance status

**Note:** `settings-page-pattern.md` has been consolidated into `settings-pattern-guide.md` and archived.

### Component Development

* **[STORYBOOK\_AI\_BEST\_PRACTICES.md](https://github.com/Encore-OS/encoreos/blob/development/docs/development/STORYBOOK_AI_BEST_PRACTICES.md)** ⭐ **Storybook + AI conventions**
  * Storybook 10.4 with `@storybook/addon-mcp` is the canonical workshop for `src/shared/ui/` primitives.
  * JSDoc, manifest-tag curation, story file template, play functions, PHI hygiene.
  * Chromatic is still out-of-scope; visual regression continues to live in `tests/e2e/visual/`.

### Migration & Adoption

* Use module specs and `specs/_templates/` checklists for migration/adoption tracking.

***

## Development Guides

### Core Development Guides

* **[TROUBLESHOOTING\_GUIDE.md](/development/TROUBLESHOOTING_GUIDE)** ⭐ **Problem Solving**
  * Diagnostic workflow for common issues
  * Build & dependency troubleshooting
  * TypeScript errors
  * Supabase connection issues
  * Authentication problems
  * Performance debugging
  * Mobile-specific issues
  * Cross-browser compatibility
  * Quick reference table

* **[DATABASE\_DEVELOPMENT\_GUIDE.md](/development/DATABASE_DEVELOPMENT_GUIDE)** ⭐ **Database Development**
  * Multi-tenant architecture & RLS
  * RLS policy patterns
  * Migration creation and testing
  * Custom fields implementation
  * Multi-tenant query patterns
  * Database debugging
  * Code examples and best practices

* **[TESTING\_SETUP\_AND\_RUN.md](/testing/TESTING_SETUP_AND_RUN)** ⭐ **Testing**
  * Canonical test execution runbook
  * Unit, integration, RLS, baseline, and E2E guidance
  * Environment variables and CI notes

* **[API\_DEVELOPMENT\_GUIDE.md](/development/API_DEVELOPMENT_GUIDE)** ⭐ **API Development**
  * API patterns (PostgREST, Edge Functions)
  * Creating API endpoints
  * Authentication & authorization
  * Error handling
  * Response formatting
  * API testing strategies

* **[PERFORMANCE\_OPTIMIZATION\_GUIDE.md](/development/PERFORMANCE_OPTIMIZATION_GUIDE)** ⭐ **Performance**
  * Performance debugging workflow
  * Bundle size optimization
  * Query optimization
  * Image optimization
  * Lazy loading patterns
  * Caching strategies
  * Performance targets & metrics

**Note:** Module-specific documentation has been moved to appropriate locations:

* FW module tables → `docs/fw/module-tables.md`
* PF adoption tracker → `specs/pf/adoption-tracker.md`
* Permissions V2 migration → `specs/pf/permissions-v2-migration.md`
* Permissions V2 rollout → `specs/pf/permissions-v2-rollout.md`

***

## Scripts & Utilities

* **[verify-coderabbit-setup.sh](/development/verify-coderabbit-setup.sh)**
  * CodeRabbit setup verification script
  * Automated setup checking

***

## Documentation Structure

### File Organization

* **Setup Guides:** `*-SETUP.md` or `*-setup.md`
* **Pattern Guides:** `*-pattern.md` or `*-PATTERN.md`
* **Quick References:** `*-quick-reference.md` or `*-QUICK_REFERENCE.md`
* **Style Guides:** `*-STYLE_GUIDE.md` or `*-style-guide.md`
* **Checklists:** `*-CHECKLIST.md` or `*-checklist.md`

### Related Documentation

**Architecture:**

* [Architecture Overview](/architecture/index) (v1.0.0) - Complete architecture documentation
* [Integration Patterns](/architecture/integrations/index) (v2.1.0) - Cross-core integration patterns
* [Navigation Standard](/architecture/standards/NAVIGATION_STANDARD) - Navigation standards and patterns
* [Navigation Guide Index](/development/NAVIGATION_GUIDE_INDEX) - Navigation documentation index
* [Spacing & UX Standards](/development/SPACING_AND_UX_STANDARDS) (v1.0.0) - Spacing and layout patterns

**Module Guides:**

* FW Guides
* FA Guides
* FM Guides

**Platform Foundation:**

* [PF Documentation](/pf/overview)

## See Also

**Architecture Documentation:**

* [Architecture Overview](/architecture/index) (v1.0.0) - System architecture and design principles
* [Integration Patterns](/architecture/integrations/index) (v2.1.0) - How cores integrate with each other
* [Navigation Standard](/architecture/standards/NAVIGATION_STANDARD) - Navigation implementation standards
* [Navigation Guide Index](/development/NAVIGATION_GUIDE_INDEX) - Navigation documentation index

**Standards & Patterns:**

* [UI/UX Standards](/development/UI_UX_STANDARDS) - Complete UI/UX design system
* [SPACING\_AND\_UX\_STANDARDS.md](/development/SPACING_AND_UX_STANDARDS) - Spacing patterns and responsive design (includes quick reference)
* [DEVELOPMENT\_QUICK\_REFERENCE.md](/development/DEVELOPMENT_QUICK_REFERENCE) - Quick reference for common patterns

**Platform Foundation:**

* [PF Documentation](/pf/overview) - Platform Foundation specifications

***

## Quick Start Workflow

**New developers:** README, Architecture, then [SETUP\_QUICK\_START.md](/development/SETUP_QUICK_START). Patterns: [DEVELOPMENT\_QUICK\_REFERENCE.md](/development/DEVELOPMENT_QUICK_REFERENCE), [UI\_UX\_STANDARDS.md](/development/UI_UX_STANDARDS), [SPACING\_AND\_UX\_STANDARDS.md](/development/SPACING_AND_UX_STANDARDS).

**Daily:** [DEVELOPMENT\_QUICK\_REFERENCE.md](/development/DEVELOPMENT_QUICK_REFERENCE), [CODE\_REVIEW\_PROCESS.md](/development/CODE_REVIEW_PROCESS). Before commit: run review, verify PWA and nav per their checklists.

***

## Documentation Maintenance

**Last Major Update:** 2025-12-31

Recent consolidations and improvements (2025-01-27 to 2025-01-28):

* ✅ Archived review/analysis files (13 files → archive)
  * All DEVELOPMENT\_DOCS\_\* review/analysis files
  * CONSOLIDATION\_ACTION\_PLAN.md (plan implemented)
  * settings-page-pattern.md (consolidated)
* ✅ Moved module-specific docs to appropriate locations (4 files)
* ✅ Consolidated spacing documentation (2 files → 1)
* ✅ Consolidated code review documentation (3 files → 1)
* ✅ Consolidated settings pattern files (2 files → 1)
* ✅ Created DEVELOPMENT\_QUICK\_REFERENCE.md for daily use
* ✅ Created SETUP\_QUICK\_START.md for onboarding
* ✅ Created NAVIGATION\_GUIDE\_INDEX.md for navigation documentation
* ✅ Created guides: TROUBLESHOOTING\_GUIDE.md,
  * DATABASE\_DEVELOPMENT\_GUIDE.md
  * API\_DEVELOPMENT\_GUIDE.md
  * PERFORMANCE\_OPTIMIZATION\_GUIDE.md
* ✅ Enhanced README.md with Quick Start and Common Tasks sections
* ✅ Added metadata, TOCs, quick references, and cross-references across all files
* ✅ Fixed broken links and updated references to archived files

**File Count:** \~26 active files (down from 39 files - 33% reduction)

**Note:** Historical review/analysis files were removed during docs consolidation. Recover any needed snapshots from Git history.

**For adding new development docs:**

* Follow file naming conventions above
* Add entry to relevant section in this README
* Link from main Documentation Hub if needed
* Update "Last Updated" date

***

## Historical Notes

Historical plans and one-off reviews were intentionally removed from active docs navigation to reduce noise. Use Git history for retrieval when needed.

***

**Questions?** Check the relevant guide above or search the development documentation directory.