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

# Engineering Onboarding

> Day-one orientation for engineers joining Encore OS. Read this once, then keep the cheat-sheets bookmarked.

Welcome to Encore OS engineering. This page is the entry point — read it top-to-bottom on day one, then come back to specific links as you need them.

<Note>
  Encore OS is a multi-tenant healthcare ERP for behavioral health and recovery housing operations. Platform version `0.9.0-alpha`. 12 cores: PF + 11 domain cores. Your work will live in one or two of them; the architecture keeps you from accidentally breaking the others.
</Note>

## Day one (45 minutes)

<Steps>
  <Step title="Get the repo running">
    Follow [Setup Quick Start](/development/SETUP_QUICK_START) end-to-end. You'll clone, install (`npm ci` — `legacy-peer-deps` is preset), configure `.env`, start Supabase locally, and run `npm run dev`. Don't skip the Supabase step; nothing works without it.
  </Step>

  <Step title="Read the constitution">
    [`/governance/canonical/constitution`](/governance/canonical/constitution) is non-negotiable guardrails. Skim §1 (Architecture), §3 (Security), §5 (Database), §7 (Testing). When in doubt about anything, the constitution wins.
  </Step>

  <Step title="Skim AGENTS">
    [`/governance/canonical/agents`](/governance/canonical/agents) is the always-loaded quick reference. It documents patterns, the regulatory decision tree, and the list of things AI agents (and humans) must never do. You'll re-read this dozens of times.
  </Step>

  <Step title="Learn the boundary rules">
    [Core Boundary Rules](/architecture/core-boundary-rules) — what's allowed across the 12 cores. The single most common review comment is "core X is importing from core Y; route through PF." Internalize this on day one.
  </Step>

  <Step title="Run the tests">
    [`Testing setup and run`](/testing/TESTING_SETUP_AND_RUN) is the canonical test reference. Run `npm run test:baseline` once to see the full pyramid (unit + integration + RLS smoke + E2E smoke) execute. If it fails locally, fix it before writing any code — the environment is wrong.
  </Step>
</Steps>

## Daily commands

The cheat-sheet you'll actually use: [Development Quick Reference](/development/DEVELOPMENT_QUICK_REFERENCE).

| Need to...           | Command                                                                           |
| -------------------- | --------------------------------------------------------------------------------- |
| Run the app          | `npm run dev` (port 8080)                                                         |
| Type-check           | `npm run typecheck`                                                               |
| Fast lint            | `npm run lint` / `npm run lint:fix`                                               |
| Format on save       | configured via Biome; `npm run format` to apply                                   |
| Run unit tests       | `npm run test`                                                                    |
| Run RLS tests        | `npm run test:rls -- <path>`                                                      |
| Run E2E for one core | `npm run test:e2e:{cl,pm,fa,hr,fw}`                                               |
| Full pre-PR check    | `npm run validate` (Turbo: format + typecheck + lint + build)                     |
| Add a DB table       | follow [Migration Workflow](/database/migration-workflow)                         |
| Find a symbol        | use the `encore-api-surface` MCP server (see [MCP Usage](/development/MCP_USAGE)) |

## How specs become code

Encore OS is spec-driven. Every shippable change traces to a spec. The pipeline:

```
stub → drafted → validated → researched → compliance_reviewed → tasks_generated → implemented → complete
```

Each gate has a skill that helps you advance. The fastest way to know what's next is `eos-spec next --spec <ID>`. See [`SPEC_COMMAND_CHEATSHEET`](/development/SPEC_COMMAND_CHEATSHEET) for the full taxonomy and [`SPEC_WORKFLOW`](/development/SPEC_WORKFLOW) for the canonical workflow doc.

You won't always touch every stage — many specs are inherited mid-pipeline. But you do need to know what the current status means before you commit.

## How AI fits in

This codebase is co-authored with AI assistants (Claude Code, Cursor, Lovable, GitHub Copilot). The rules they follow are the rules you follow. The hierarchy:

```
constitution.md → AI_GUIDE.md → AGENTS.md → .cursor/rules/* / .claude/skills/*
```

* [`/governance/canonical/ai-guide`](/governance/canonical/ai-guide) — workflow, decision framework, implementation log protocol.
* [`/governance/canonical/agents`](/governance/canonical/agents) — quick-reference and "AI must never" list.
* [`MCP Usage`](/development/MCP_USAGE) — Model Context Protocol servers we use (Supabase, Fallow, Context7, encore-api-surface).
* [`AGENTS_BEST_PRACTICES_CURSOR`](/development/AGENTS_BEST_PRACTICES_CURSOR) — when you're driving with Cursor.

## Where things live

| Path                                               | What                                                                              |
| -------------------------------------------------- | --------------------------------------------------------------------------------- |
| `src/`                                             | Root Vite app — root path alias `@/*` → `./src/*`                                 |
| `packages/platform`                                | Platform Foundation (PF)                                                          |
| `packages/core-{ce,cl,fa,fm,fw,gr,hr,it,lo,pm,rh}` | 11 domain cores. Depend on PF only                                                |
| `packages/shared`                                  | Cross-cutting utilities                                                           |
| `supabase/`                                        | Supabase config, migrations, declarative schemas, seed data                       |
| `specs/`                                           | Product specs by core                                                             |
| `docs/`                                            | This documentation site                                                           |
| `tests/`                                           | Vitest (unit / integration / rls) + Playwright (e2e)                              |
| `scripts/`                                         | Tooling — docs/, audit/, registry/, supabase/ — usually invoked through `npm run` |
| `automation/`                                      | Canonical skill/agent/command definitions (`.claude/` and `.cursor/` symlink in)  |

## Common reviewer pushbacks

| What the reviewer will say                | What it means                                                 | Fix                                                                                                           |
| ----------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| "Use PF instead of importing from core X" | You imported `@encore-os/core-pm` from `@encore-os/core-fa`   | Route through `@encore-os/platform/<area>` — see [Core Boundary Rules](/architecture/core-boundary-rules)     |
| "Where's the RLS test?"                   | New table without RLS coverage                                | Add `tests/rls/{core}/{table}.rls.test.ts` — see [Migration Workflow](/database/migration-workflow)           |
| "This needs a spec ID"                    | Change isn't traceable to a validated spec                    | Open the spec first, then implement. Don't ship undocumented behavior in regulated cores (CL, PM, HR, RH, GR) |
| "Tenant leak"                             | Query doesn't include `org_id` predicate or RLS isn't enabled | Verify the policy. Run `npm run test:rls -- <table>`                                                          |
| "Type mismatch with generated types"      | You forgot `npm run generate-types` after a schema change     | Reset DB, regenerate types, commit them                                                                       |

## Where to go from here

* Architecture deep-dive: [`/architecture/index`](/architecture/index) and the 22 [ADRs](/architecture/decisions/index)
* Spec governance: [`/governance/index`](/governance/index)
* All dev guides: [`/development/index`](/development/index)
* Testing: [`/testing/TESTING_SETUP_AND_RUN`](/testing/TESTING_SETUP_AND_RUN)
* Database: [`/database/migration-workflow`](/database/migration-workflow)
* Operations: [`/operations/docs-health`](/operations/docs-health) (live coverage scorecard)

If you get stuck and can't find the answer, ping #engineering with your spec ID and what you've tried. Pretty much everything is documented; finding it is half the skill.