Encore OS — Documentation

Version: 2.0.0
Last Updated: 2026-01-15
Purpose: Complete documentation and tooling for migrating from Lovable Cloud to Supabase Cloud

Quick Start Verification Checklist

Before starting the migration, verify your setup:

✅ 1. MCP Connection

mcp_supabase_get_project_url()
// Expected: https://<project-ref>.supabase.co

✅ 2. CLI Installation

supabase --version
# Expected: Supabase CLI 1.x.x or higher

✅ 3. Project Linked

supabase status
# Expected: Shows linked project details

✅ 4. Migration Files Present

Get-ChildItem "supabase/migrations/*.sql" | Measure-Object
# Expected: Count >= 393

✅ 5. Staging Branch Available

mcp_supabase_list_branches()
// Expected: Shows 'staging' branch

All checks passed? See the live Migration Workflow. The original 2026-01 Completion Plan is archived at ../archive/migration-2026-01/COMPLETION_PLAN.md.

Migration Status Tracker

Current Phase: Phase 6 - Documentation Updates

Phase	Status	Notes
Phase 0: Pre-Setup Verification	✅ Complete	MCP connection verified
Phase 1: Staging Branch Setup	✅ Complete	Staging branch created
Phase 2: Apply Migrations	✅ Complete	393+ migrations applied
Phase 3: Run SQL Audits	✅ Complete	Audits executed, issues documented
Phase 4: Create Fix Migrations	✅ Complete	Templates prepared
Phase 5: Apply and Validate Fixes	✅ Complete	Fixes validated
Phase 6: Documentation Updates	🔄 In Progress	Updating AGENTS.md, guides
Phase 7: Application Testing	⏳ Pending
Phase 8: Pre-Production Checklist	⏳ Pending
Phase 9: Production Migration	⏳ Pending

Issue Tracker

Issue	Priority	Status	Fix Migration
UPDATE policies missing WITH CHECK	P0	Template Ready	`TEMPLATE_fix_rls_with_check.sql`
Storage bucket naming	P1	Template Ready	`TEMPLATE_fix_storage_bucket_names.sql`
Missing audit columns	P1	Template Ready	`TEMPLATE_fix_missing_audit_columns.sql`
TypeScript types empty	P0	Pending	Generate after migrations

Documentation Index

Primary Guides

Document	Purpose	When to Use
Migration Workflow	Live migration workflow	Primary migration guide
Completion Plan (archived 2026-01)	Original step-by-step migration plan	Historical reference
Pre-Production Checklist (archived 2026-01)	Final validation checklist	Historical reference
MCP Usage Guide	MCP vs CLI decision matrix	When using Supabase tools

Migration plans (feature-specific)

Document	Purpose
MIGRATION_SUMMARY.md (archived 2026-01)	HR-09-P5 phase summary and status
plans/MIGRATION_PLAN_HR-09-P5.md	HR-09-P5 detailed migration guide
plans/PRE_MIGRATION_CODE_CHECKLIST.md	Developer checklist before migration day

Setup Guides

Document	Purpose
Staging Setup Guide (archived 2026-01)	Create and configure staging branch
SQL Audit Instructions (archived 2026-01)	Run audit scripts against database
Type Generation Guide	Generate TypeScript types

Reports

Report	Location	Purpose
Migration Readiness Report	`reports/MIGRATION_READINESS_REPORT.md`	Overall assessment
RLS Policy Inventory	`reports/audits/RLS_POLICY_INVENTORY.md`	RLS policy analysis
Column Compliance Report	`reports/audits/COLUMN_COMPLIANCE_REPORT.md`	Column standards
Migration Inventory	`reports/audits/migration-inventory.json`	Raw analysis data

Tool Usage Quick Reference

When to Use MCP

Task	MCP Tool
Get project URL	`mcp_supabase_get_project_url()`
List branches	`mcp_supabase_list_branches()`
List tables	`mcp_supabase_list_tables()`
List migrations	`mcp_supabase_list_migrations()`
Search docs	`mcp_supabase_search_docs()`
Run SQL queries	`mcp_supabase_execute_sql()`
Check advisors	`mcp_supabase_get_advisors()`
Generate types	`mcp_supabase_generate_typescript_types()`

When to Use CLI

Task	CLI Command
Create migration	`supabase migration new <name>`
Apply migrations	`supabase db push`
Generate types	`supabase gen types typescript`
Start local	`supabase start`
Create branch	`supabase --experimental branches create`
Link project	`supabase link --project-ref <id>`
Deploy functions	`supabase functions deploy`

Full Guide: MCP Usage Guide

Scripts Reference

Analysis Scripts (Local)

# Parse migration files and generate inventory
npx tsx scripts/lint-migrations.ts

# Generate markdown reports from inventory
npx tsx scripts/generate-migration-reports.ts

# Count tables by module
npx tsx scripts/count-tables-by-module.ts

SQL Audit Scripts (Run in Supabase)

Script	Purpose	Run Via
`scripts/audit-rls-policies.sql`	Find UPDATE policies missing WITH CHECK	Dashboard SQL Editor or MCP
`scripts/audit-table-columns.sql`	Find missing audit columns	Dashboard SQL Editor or MCP
`scripts/audit-storage-buckets.sql`	Find non-compliant bucket names	Dashboard SQL Editor or MCP

Utility Scripts

# Generate TypeScript types (use CLI)
./scripts/generate-types.sh

# Or manually:
supabase gen types typescript --project-id <id> > src/integrations/supabase/types.ts

Migration Templates

Templates for creating fix migrations (in supabase/migrations/):

Template	Purpose
`TEMPLATE_fix_rls_with_check.sql`	Add WITH CHECK to UPDATE policies
`TEMPLATE_fix_storage_bucket_names.sql`	Rename non-compliant buckets
`TEMPLATE_fix_missing_audit_columns.sql`	Add missing audit columns

Usage:

Copy template with timestamp: supabase migration new fix_<issue>
Fill with generated SQL from audit scripts
Apply: supabase db push

Key Statistics

Metric	Count	Verification
Migration Files	393+	`Get-ChildItem "supabase/migrations/*.sql" \| Measure-Object`
Total Tables	~465	`mcp_supabase_list_tables()`
RLS Policies	~1,685	See RLS Policy Inventory
Database Functions	~575	See migration inventory
Storage Buckets	7	`mcp_supabase_execute_sql()` on storage.buckets
Triggers	~762	See migration inventory

Tables by Module

Module	Prefix	Expected Tables
Platform Foundation	pf_	74
Human Resources	hr_	94
Finance & Accounting	fa_	46
Forms & Workflow	fw_	54
Recovery Housing	rh_	51
Governance & Risk	gr_	49
Facilities Management	fm_	22
Leadership OS	lo_	29
IT Service Management	it_	35
Other	-	11
Total		~465

Critical Issues Summary

P0 (Must Fix Before Migration)

Issue	Impact	Status
UPDATE policies missing WITH CHECK	Security vulnerability - multi-tenant breach	Template Ready
TypeScript types empty	No type safety for database operations	Pending type generation

P1 (Should Fix Before Migration)

Issue	Impact	Status
SECURITY DEFINER functions missing search_path	Security best practice	15 functions identified
Non-compliant storage buckets	Naming convention violation	4 buckets need renaming
Missing audit columns	Data governance gap	~60 tables need `updated_by`

Migration Workflow

Helpful Links

Supabase Documentation

Project Documentation

AGENTS.md - AI Agent Instructions (includes Supabase MCP section)
Supabase Setup - Full setup guide with branching
MCP Usage Guide - MCP vs CLI decision matrix

Support

For questions or issues:

Review the Migration Workflow (original Completion Plan archived at ../archive/migration-2026-01/COMPLETION_PLAN.md)
Check the Pre-Production Checklist (archived 2026-01)
Search Supabase docs via MCP: mcp_supabase_search_docs()
Review audit reports in reports/audits/

Last Updated: 2026-01-15
Version: 2.0.0

​Quick Start Verification Checklist

​✅ 1. MCP Connection

​✅ 2. CLI Installation

​✅ 3. Project Linked

​✅ 4. Migration Files Present

​✅ 5. Staging Branch Available

​Migration Status Tracker

​Current Phase: Phase 6 - Documentation Updates

​Issue Tracker

​Documentation Index

​Primary Guides

​Migration plans (feature-specific)

​Setup Guides

​Reports

​Tool Usage Quick Reference

​When to Use MCP

​When to Use CLI

​Scripts Reference

​Analysis Scripts (Local)

​SQL Audit Scripts (Run in Supabase)

​Utility Scripts

​Migration Templates

​Key Statistics

​Tables by Module

​Critical Issues Summary

​P0 (Must Fix Before Migration)

​P1 (Should Fix Before Migration)

​Migration Workflow

​Helpful Links

​Supabase Documentation

​Project Documentation

​Support