Setup Quick Start

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.

​

First-Time Developer Onboarding

​

Step 1: Clone & Install

# Clone repository
git clone <repository-url>
cd northsight-health-OS

# Install dependencies
npm ci --legacy-peer-deps

​

Step 2: Environment Setup

1. Copy environment template:
   cp .env.example .env.local
   
2. Get Supabase credentials:
   • Go to Supabase Dashboard → Settings → API
   • Copy Project URL → VITE_SUPABASE_URL
   • Copy anon public key → VITE_SUPABASE_PUBLISHABLE_KEY
3. Add to .env.local:
   VITE_SUPABASE_URL=https://your-project.supabase.co
   VITE_SUPABASE_PUBLISHABLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
   
4. Verify setup:
   npm run dev
   
   • Should start dev server without errors
   • Should connect to Supabase successfully

​

Step 3: PWA Setup Verification

1. Check icons exist:
   ls public/pwa-*.png public/favicon.ico
   
   Should show: pwa-64x64.png, pwa-192x192.png, pwa-512x512.png, favicon.ico
2. Verify PWA configuration:
   • Check vite.config.ts has VitePWA plugin configured
   • Check index.html has manifest link and theme-color meta tag
3. Test PWA features:
   npm run dev
   
   • Open browser DevTools → Application → Service Workers
   • Should see service worker registered
   • Check Application → Manifest for PWA manifest

​

Step 4: CodeRabbit Setup

1. Install CodeRabbit CLI:
   npm install -g @coderabbitai/cli
   
2. Authenticate:
   coderabbit auth login
   
3. Verify setup:
   bash docs/development/verify-coderabbit-setup.sh
   
   Should show: ✅ All checks passed
4. Test review:
   cr-uncommitted
   
   Should run review without errors

​

Step 5: Recommended IDE Extensions

1. Open Extensions panel (Ctrl+Shift+X / Cmd+Shift+X)
2. Search for fallow-rs.fallow-vscode
3. Click Install

• Hover over any export to see how many places import it
• Imports and Exports tree views for navigating module usage
• Inline diagnostics for unused files, exports, and dependencies
• Circular dependency detection

​

Step 6: Verify Development Environment

# Full validation gate (format + typecheck + lint + build)
npm run validate

​

Environment Variables Quick Checklist

​

Required Variables

• VITE_SUPABASE_URL - Supabase project URL
• VITE_SUPABASE_PUBLISHABLE_KEY - Supabase anon public key

​

Development/Testing Variables (Optional)

• SUPABASE_SERVICE_ROLE_KEY - For testing only (never commit)

​

Verification

# Check environment variables are loaded
npm run dev
# Should start without "Missing environment variable" errors

​

PWA Setup Quick Checklist

​

Icons

• favicon.ico exists in public/
• pwa-64x64.png exists
• pwa-192x192.png exists
• pwa-512x512.png exists
• maskable-icon-512x512.png exists
• apple-touch-icon-180x180.png exists

​

Configuration

• vite.config.ts has VitePWA plugin configured
• index.html has manifest link
• index.html has theme-color meta tag (#234d72)
• Service worker registers on page load

​

Testing

• Dev server starts without PWA errors
• Service worker appears in DevTools → Application → Service Workers
• Manifest appears in DevTools → Application → Manifest
• Icons display correctly in browser tab
• PWA install prompt appears (if supported)

​

IDE Extensions Quick Checklist

​

Recommended Extensions

• Fallow (fallow-rs.fallow-vscode) installed — inline dead-code diagnostics and module graph navigation

​

Verification

• After installing Fallow extension: run npx fallow dead-code in the workspace and verify diagnostics appear in-editor
• Restart Cursor to activate the Fallow MCP server (configured in .cursor/mcp.json)

​

CodeRabbit Setup Quick Checklist

​

Installation

• CodeRabbit CLI installed globally
• Authenticated with coderabbit auth login
• Convenience aliases configured (if using)

​

Verification

• Run bash docs/development/verify-coderabbit-setup.sh - all checks pass
• Run cr-uncommitted - review completes successfully
• Run cr-lovable - markdown report generates

​

Common Commands

• cr-uncommitted - Review uncommitted changes
• cr-review - Full review
• cr-lovable - Generate markdown report by severity

​

Troubleshooting Common Issues

​

Environment Variables Not Loading

1. Ensure .env.local exists (not .env)
2. Check variable names start with VITE_ for client-side access
3. Restart dev server after changing .env.local

​

PWA Icons Missing

1. Regenerate icons: npx pwa-assets-generator public/icon-512-gold-512x512.png --preset minimal
2. Check vite.config.ts PWA plugin configuration
3. Clear browser cache and service worker

​

CodeRabbit Not Working

1. Reinstall CLI: npm install -g @coderabbitai/cli
2. Re-authenticate: coderabbit auth login
3. Check shell configuration (reload .bashrc or .zshrc)

​

Build Errors

1. Reinstall dependencies with lockfile parity: npm ci --legacy-peer-deps
2. Clear build cache: rm -rf dist .vite
3. Check for TypeScript errors: npm run typecheck

​

Next Steps

1. Read Core Documentation:
   • README.md - Project overview
   • AGENTS.md - AI agent instructions
   • constitution.md - Engineering guardrails
2. Review Development Guides:
   • DEVELOPMENT_QUICK_REFERENCE.md - Common patterns and gotchas
   • UI_UX_STANDARDS.md - UI/UX standards
   • mobile-navigation-guide.md - Mobile navigation patterns
3. Start Developing:
   • Create feature branch: git checkout -b feature/your-feature
   • Follow CODE_REVIEW_PROCESS.md for review workflow
   • Reference DEVELOPMENT_QUICK_REFERENCE.md for common patterns

​

Quick Links

• DEVELOPMENT_QUICK_REFERENCE.md - Common commands and patterns
• ENVIRONMENT_VARIABLES.md - Complete environment guide
• PWA_SETUP.md - Complete PWA guide
• CODERABBIT_GUIDE.md - Complete CodeRabbit guide
• MCP_USAGE.md - MCP server usage guide (Fallow, Supabase, Context7)
• README.md - Development documentation index