> ## 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.

# Setup Quick Start

> Version: 1.0.0 Last Updated: 2025-01-27 Status: Active Target Audience: Developers

**Version:** 1.0.0\
**Last Updated:** 2025-01-27\
**Status:** Active\
**Target Audience:** Developers

Quick setup checklists for first-time developers and environment verification.

***

## First-Time Developer Onboarding

### Step 1: Clone & Install

```bash theme={null}
# 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:**
   ```bash theme={null}
   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`:**
   ```env theme={null}
   VITE_SUPABASE_URL=https://your-project.supabase.co
   VITE_SUPABASE_PUBLISHABLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
   ```

4. **Verify setup:**
   ```bash theme={null}
   npm run dev
   ```
   * Should start dev server without errors
   * Should connect to Supabase successfully

**See:** [ENVIRONMENT\_VARIABLES.md](./ENVIRONMENT_VARIABLES.md) for complete guide

### Step 3: PWA Setup Verification

1. **Check icons exist:**
   ```bash theme={null}
   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:**
   ```bash theme={null}
   npm run dev
   ```
   * Open browser DevTools → Application → Service Workers
   * Should see service worker registered
   * Check Application → Manifest for PWA manifest

**See:** [PWA\_SETUP.md](./PWA_SETUP.md) for complete guide

### Step 4: CodeRabbit Setup

1. **Install CodeRabbit CLI:**
   ```bash theme={null}
   npm install -g @coderabbitai/cli
   ```

2. **Authenticate:**
   ```bash theme={null}
   coderabbit auth login
   ```

3. **Verify setup:**
   ```bash theme={null}
   bash docs/development/verify-coderabbit-setup.sh
   ```
   Should show: ✅ All checks passed

4. **Test review:**
   ```bash theme={null}
   cr-uncommitted
   ```
   Should run review without errors

**See:** [CODERABBIT\_GUIDE.md](./CODERABBIT_GUIDE.md) for complete guide

### Step 5: Recommended IDE Extensions

These extensions are recommended for all developers using **Cursor** or **VS Code**:

| Extension  | Marketplace ID            | Purpose                                                                    |
| ---------- | ------------------------- | -------------------------------------------------------------------------- |
| **Fallow** | `fallow-rs.fallow-vscode` | Inline dead-code detection, duplication insights, and complexity hotspots. |

**Install via Cursor/VS Code:**

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

Or install via the marketplace: [https://marketplace.visualstudio.com/items?itemName=fallow-rs.fallow-vscode](https://marketplace.visualstudio.com/items?itemName=fallow-rs.fallow-vscode)

**What you get:**

* 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

**Note:** The extension's built-in MCP server is already configured in `.cursor/mcp.json`. Restart Cursor after installing to activate both the extension and the MCP server.

### Step 6: Verify Development Environment

```bash theme={null}
# Full validation gate (format + typecheck + lint + build)
npm run validate
```

The command should complete without errors.

***

## 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

```bash theme={null}
# Check environment variables are loaded
npm run dev
# Should start without "Missing environment variable" errors
```

**See:** [ENVIRONMENT\_VARIABLES.md](./ENVIRONMENT_VARIABLES.md) for complete reference

***

## 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)

**See:** [PWA\_SETUP.md](./PWA_SETUP.md) for complete guide

***

## 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

**See:** [CODE\_REVIEW\_PROCESS.md](./CODE_REVIEW_PROCESS.md) for daily workflow\
**See:** [CODERABBIT\_GUIDE.md](./CODERABBIT_GUIDE.md) for complete setup

***

## Troubleshooting Common Issues

### Environment Variables Not Loading

**Problem:** `Missing environment variable` errors

**Solution:**

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

**Problem:** Icons not displaying or service worker errors

**Solution:**

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

**Problem:** `cr` command not found or authentication errors

**Solution:**

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

### Build Errors

**Problem:** `npm run build` fails

**Solution:**

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

After completing setup:

1. **Read Core Documentation:**
   * README.md - Project overview
   * [AGENTS.md](../../AGENTS.md) - AI agent instructions
   * [constitution.md](../../constitution.md) - Engineering guardrails

2. **Review Development Guides:**
   * [DEVELOPMENT\_QUICK\_REFERENCE.md](./DEVELOPMENT_QUICK_REFERENCE.md) - Common patterns and gotchas
   * [UI\_UX\_STANDARDS.md](./UI_UX_STANDARDS.md) - UI/UX standards
   * [mobile-navigation-guide.md](./mobile-navigation-guide.md) - Mobile navigation patterns

3. **Start Developing:**
   * Create feature branch: `git checkout -b feature/your-feature`
   * Follow [CODE\_REVIEW\_PROCESS.md](./CODE_REVIEW_PROCESS.md) for review workflow
   * Reference [DEVELOPMENT\_QUICK\_REFERENCE.md](./DEVELOPMENT_QUICK_REFERENCE.md) for common patterns

***

## Quick Links

* [DEVELOPMENT\_QUICK\_REFERENCE.md](./DEVELOPMENT_QUICK_REFERENCE.md) - Common commands and patterns
* [ENVIRONMENT\_VARIABLES.md](./ENVIRONMENT_VARIABLES.md) - Complete environment guide
* [PWA\_SETUP.md](./PWA_SETUP.md) - Complete PWA guide
* [CODERABBIT\_GUIDE.md](./CODERABBIT_GUIDE.md) - Complete CodeRabbit guide
* [MCP\_USAGE.md](./MCP_USAGE.md) - MCP server usage guide (Fallow, Supabase, Context7)
* README.md - Development documentation index

***