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

# Encore Health OS – Lovable Workspace Knowledge

> Paste into Workspace Knowledge (Lovable Teams: Settings > Knowledge). Applies to every project. For spec workflow use LOVABLE_CUSTOM_KNOWLEDGE.md as Project Kn…

Paste into **Workspace Knowledge** (Lovable Teams: Settings > Knowledge). Applies to every project. For spec workflow use LOVABLE\_CUSTOM\_KNOWLEDGE.md as Project Knowledge. When in doubt: **ask; default to the safest interpretation.**

**Full reference:** AGENTS.md, constitution.md, docs/tools/lovable/LOVABLE\_REFERENCE\_APPENDIX.md, docs/tools/lovable/LOVABLE\_PROMPTS.md.

***

## 1. Context

Multi-tenant healthcare ERP (behavioral health, recovery housing). React 18 + TypeScript, Vite 8 (Rolldown bundler), Tailwind CSS v4 (CSS-first config), shadcn, TanStack Query, Supabase. **Platform Foundation (PF)** + domain cores (RH, FA, HR, GR, FW, FM, LO, IT, CE, CL, PM). Cores depend only on PF; no core-to-core imports. CL is downstream. Constitution wins on conflict.

***

## 2. Decision order

1. Security & compliance (tenant isolation, PHI, RLS) 2. Architecture boundaries 3. Performance 4. UX 5. Code quality.

***

## 3. Architecture (CRITICAL)

* Every feature: owning core (e.g. RH-01, FA-01). Cores depend ONLY on PF.
* Cross-core: Platform Integration Layer (`@/platform/{feature}`), events, or API contracts only. No direct core imports.
* Do not change auth flow, refactor code, or add deps without explicit instruction.

***

## 4. Non-negotiables (NEVER)

* Missing `organization_id` on mutations → always `.eq('organization_id', orgId)`.
* Reading tenant ID from `user.app_metadata.organization_id` → always use `useOrganization()` hook.
* Direct core-to-core imports → use `@/platform/{feature}`.
* Raw `error.message` to users → `sanitizeErrorMessage(error)`.
* `return null` for loading → `<Skeleton />`.
* Direct route import for pages → `React.lazy(() => import('./Page'))`.
* Hardcoded colors → semantic tokens only (`text-success`, `bg-destructive`).
* Schema outside migrations → all changes in `supabase/migrations/`.
* PHI/PII in prompts or logs → synthetic data only.
* Secrets in code → Lovable Cloud Secrets or env.
* Inline `pf_user_role_assignments` in edge fns → `verifyOrgAccess()`/`verifyOrgRole()` from `_shared/auth.ts`.
* Native dialogs → `Dialog`/`AlertDialog`/toast. Old DataTable → `@/platform/table-v2`. Hard-coded codes → PF-70 library. Dynamic Supabase import → static at file top.
* Modifying the `realtime` schema → strictly prohibited. Enforce RLS on source tables instead.

***

## 5. Patterns (use every time)

* Tenant: `.eq('organization_id', orgId)` on mutations.
* Internal cross-module links: wrap with `prefixPath(path)` so the active organization context is preserved.
* Form dialogs (Radix): use `key={entityId ?? "new"}` to force a full remount; reset state via `onOpenChange`.
* Routes: `React.lazy` + Suspense. Loading: `<Skeleton />`. Queries: `staleTime: 5*60*1000`, `gcTime: 10*60*1000`.
* Auth: `useCurrentUser()` from `@/platform/auth`. Supabase: static `import { supabase } from '@/integrations/supabase/client'`.
* Permissions: `useHasPermission('module.entity.action')` or `<PermissionGate>`; never hardcode roles.
* Dialogs: `sm:max-w-md`/`lg`/`2xl`/`3xl`/`4xl` with `sm:` prefix. Pages: `<PageContainer>`.
* Tables: `DataTable` from `@/platform/table-v2`. Overlays: `*Dialog` or `*Sheet`, never `*Modal`.
* Migrations: CLI (`npx supabase`); MCP for read/schema/types.ts only. Regenerate types.ts after migrations before writing hooks.
* **Tailwind v4:** Use `@import 'tailwindcss'` (not `@tailwind` directives). Token mapping: `@theme inline { ... }`. Dark mode: `@custom-variant dark`. Animations: `tw-animate-css` (not `tailwindcss-animate`). Gradients: prefer `bg-linear-*` over legacy `bg-gradient-*`.

***

## 6. DB & RLS

* All business tables: `organization_id` (and `site_id` where applicable). **`FORCE ROW LEVEL SECURITY` on every table** (defense-in-depth — applies even to table owners). UPDATE policies need `WITH CHECK`. Use SECURITY DEFINER helpers (e.g. `pf_has_org_access()`); every SECURITY DEFINER function must `SET search_path = public, pg_catalog`. Migrations only. `custom_fields JSONB` on business/transaction tables. Soft delete: partial index `WHERE deleted_at IS NULL`; queries `.is('deleted_at', null)`. FK columns (including `created_by`/`updated_by`) must be indexed.

***

## 7. Edge functions

* `Deno.serve()`. Import Supabase via `npm:@supabase/supabase-js@2`. No `@/` or `src/` imports; use `supabase/functions/_shared/`. Auth: `verifyOrgAccess()`/`verifyOrgRole()` from `_shared/auth.ts`. Use `getCorsHeaders()`, `createNotificationIfNew()`, `createCronHandler()` etc. from \_shared. `deno.json`: `"lock": false`; do not commit deno.lock.

***

## 8. Security & UI

* Every mutation: `organization_id` filter. Errors: `sanitizeErrorMessage()`. Secrets: Lovable Cloud Secrets. AI: via edge functions only; no PHI to AI.
* UI: semantic tokens only; `<Skeleton />` for loading; `<EmptyState />` for empty; `<PageContainer>`; mobile-first 44px touch targets.
* Formatting: user-facing dates and currency MUST use `@/platform/formatting` utilities. Do not use raw `toLocaleString` / `toLocaleDateString`.
* Z-index tokens: `--z-base` (0), `--z-sticky` (40), `--z-dropdown` (50), `--z-overlay` (80), `--z-modal` (100), `--z-max` (9999). Don't hardcode arbitrary z values.

***

## 9. Lovable-specific

* Do not edit: client.ts, types.ts, config.toml, .env, `tailwind.config.lov.json` (auto-generated). Secrets in Settings > Cloud > Secrets.
* Supabase reverts: schema does not revert cleanly; after revert validate SQL. Pin version after each working feature; use Visual Edit for small UI tweaks (text, colors, spacing).
* Vite 8 (Rolldown): use inline type signatures for `PreRenderedAsset`/`PreRenderedChunk` (not rollup imports); cast `sourcemap` explicitly.
* **Mode rules:** Lovable's **Chat / Plan mode is strictly read-only** — it cannot edit `.ts`, `.tsx`, `.sql`, OR `.md` files. Any prompt that asks for file edits (including doc fixes) MUST run in **Default mode**. If a prompt says "Chat Mode", it means *analysis only* — never edits.
* **4-chat workflow** for spec implementation: §1 Pre (Chat/Plan, read-only) → §2 Plan+Execute (Default throughout) → §3a Verify+Status (Default) → §3b Browser E2E (Default + browser tools). See LOVABLE\_PROMPTS.md.
* **Scratchpad discipline:** Only `.lovable/rules/` is loaded as project context. Do NOT create `.lovable/plan.md` or `.lovable/scratch/*` — both are gitignored. Pass state between chats via the **handoff block** at the end of each chat (paste it as the first message of the next chat).

***

## 10. Lovable platform features

* Run Lovable security checks before publish: RLS analysis, database security check, and dependency audit.
* Use browser testing for real user-flow verification. Trigger phrases: "verify it works", "test this", "check if it's working".
* Prefer Agent mode for larger end-to-end changes that require implementation plus verification.
* Use frontend tests (Vitest + React Testing Library) for UI rule stability.
* Use edge-function tests (Deno test runner) for backend/business-rule validation.
* Browser-testing limits: unreliable for canvas tools, uploads/downloads, right-click flows, and subtle color-detail verification.

***

## 11. Prompting techniques

* End complex prompts with: "Ask me any questions you need to fully understand this feature before writing code."
* Build by component/workstream, not whole-page rewrites.
* Use real domain content; avoid placeholder text.
* Add explicit guardrails: "Do not edit X or Y; only change Z."
* After 2-3 failed "Try to Fix" attempts, switch to Plan-mode investigation first.
* Avoid combining large implementation and browser verification in one prompt; build first, verify in follow-up.

***

## 12. Brand and copy rules

* Keep user-facing copy professional and clinically appropriate.
* Use sentence case for headings and action labels.
* Do not use placeholder text; use realistic behavioral-health context.
* Use US date presentation (Month Day, Year) unless feature requirements override.
* Use currency/date formatting helpers from `@/platform/formatting` for visible values.