# Setup Verification Matrix

Verification checks return `PASS`, `WARNING`, or `FAIL`.

| Check ID | Area | Check Name | Purpose | Required For | Method | Pass Condition | Warning Condition | Fail Condition | Suggested Fix | API / Service |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| `ENV_AUTH_SECRET` | Environment | Auth secret present | Ensure Auth.js can sign sessions. | first login | Read server env. | `AUTH_SECRET` exists and length is acceptable. | Weak-looking local/dev secret. | Missing secret. | Set `AUTH_SECRET` in `.env.local` or deployment secrets. | `setup/readiness.service.ts` |
| `ENV_DATABASE_URL` | Environment | Database URL present | Ensure app can connect to PostgreSQL. | all setup | Read server env. | `DATABASE_URL` exists. | Host appears local in non-local environment. | Missing value. | Set `DATABASE_URL`. | `setup/readiness.service.ts` |
| `DB_CONNECTIVITY` | Database | Database connectivity | Prove DB is reachable. | all setup | Open DB connection and `select 1`. | Query succeeds. | High latency. | Connection/query fails. | Verify database host, network, credentials. | `src/lib/db.ts` |
| `DB_MIGRATIONS` | Database | Migration status | Prevent setup against stale schema. | all setup | Check Drizzle migration metadata/schema tables where available. | Schema matches expected tables. | Migration metadata unavailable but required tables exist. | Required tables missing. | Run `npm run db:migrate`. | setup readiness + Drizzle |
| `STORAGE_PROVIDER` | Storage | Storage provider smoke test | Prove seed/document storage can write. | document library/PDF | Write/read/delete test object under setup prefix. | All operations succeed. | Delete cleanup fails but object tracked. | Write/read fails. | Fix local directory/S3 credentials. | `src/features/foundation/storage/**` |
| `UPLOAD_DIRECTORY` | Storage | Upload directory readiness | Prove local provider path is writable. | local storage | Check directory exists/create/write/delete. | Directory writable. | Directory created during check. | Not writable. | Create/fix permissions. | storage provider |
| `PDF_TEMPLATE_ASSET` | PDF | PDF template assets exist | Ensure quotation PDF can render. | quotation | Check active template version/file/schema. | Active version and schema exist. | Template exists but preview asset missing. | No active template version. | Run foundation/PDF template seed. | document-template/pdf foundations |
| `PDF_MAPPING_COVERAGE` | PDF | PDF mappings exist | Ensure placeholders can resolve. | quotation | Count required mappings for active version. | Required mappings present. | Optional mappings missing. | Required mapping missing. | Run PDF mapping seed/audit. | PDF audit services/scripts |
| `EMAIL_CONFIG` | Email | Email configuration | Confirm optional email readiness. | optional notifications | Read env/provider config; optional dry-run. | Provider configured and dry-run succeeds. | Email not configured but in-app notifications are available. | Provider configured but dry-run fails. | Fix SMTP/provider settings. | future notification/email service |
| `ADMIN_USER` | Auth | First administrator exists | Ensure first login actor exists. | first login | Query `users` by setup admin email. | User exists. | User exists but inactive semantics added later. | Missing user. | Create administrator step. | user/auth service |
| `ADMIN_MEMBERSHIP` | Auth | Administrator membership exists | Ensure admin can enter organization. | first login | Query `memberships`. | Membership exists with admin role. | Membership role is user but CRM assignment admin. | Missing membership. | Create membership. | organization/session helpers |
| `ADMIN_CRM_ASSIGNMENT` | Authorization | Administrator CRM assignment resolves | Ensure CRM admin permissions resolve. | CRM | Resolve CRM access. | `crm_admin` or equivalent permissions resolve. | Compatibility business role only, no assignment. | No CRM access. | Seed role profiles and assignment. | `resolveCrmAccess()` |
| `ORG_ACTIVE` | Organization | Organization active/resolvable | Ensure active org context works. | all setup | Resolve organization and active org for admin. | Organization exists and admin active org set. | Organization exists but active org missing. | Organization missing. | Update `users.active_organization_id`. | `requireOrganizationAccess()` |
| `BRANCH_OPTION` | Scope | Branch option exists | Ensure branch scope can resolve. | CRM/quotation | Query `ms_options` category `crm_branch`. | At least one active branch. | Branch exists but no default convention. | No active branch. | Configure branch step. | master-options foundation |
| `PRODUCT_TYPE_OPTION` | Scope | Product type option exists | Ensure product scope can resolve. | CRM/quotation | Query `ms_options` category `crm_product_type`. | At least one active product type. | Product type exists but no document prefix metadata. | No active product type. | Configure product types. | master-options foundation |
| `SEQUENCE_CUSTOMER` | Document sequence | Customer sequence preview | Ensure customer codes can generate. | CRM | Call sequence preview for customer. | Preview returns code. | Generic branch/product scope only. | Preview fails. | Configure document sequence. | document-sequence foundation |
| `SEQUENCE_LEAD` | Document sequence | Lead sequence preview | Ensure lead codes can generate. | CRM | Call sequence preview for `crm_lead`. | Preview returns code. | Generic scope only. | Preview fails. | Configure lead sequence. | document-sequence foundation |
| `SEQUENCE_OPPORTUNITY` | Document sequence | Opportunity sequence preview | Ensure opportunity codes can generate. | CRM | Call sequence preview for `crm_opportunity`. | Preview returns code. | Generic scope only. | Preview fails. | Configure opportunity sequence. | document-sequence foundation |
| `SEQUENCE_QUOTATION` | Document sequence | Quotation sequence preview | Ensure quotation codes can generate. | quotation | Preview by branch/product type. | Preview returns code for each configured product type. | Missing some branch/product combinations. | No quotation sequence works. | Configure quotation sequences. | document-sequence foundation |
| `APPROVAL_WORKFLOW` | Approval | Quotation workflow resolves | Ensure quotation approval can start. | quotation | Query active workflow for quotation. | Active workflow exists. | Multiple active candidates. | Missing workflow. | Configure approval workflow. | approval foundation |
| `APPROVAL_MATRIX` | Approval | Approval matrix resolves | Ensure quotation can select workflow by scope/amount. | quotation | Resolve matrix for sample quotation amount. | Matrix resolves. | Default-only fallback. | No matrix resolves. | Configure approval matrix. | approval foundation |
| `NOTIFICATION_TEMPLATES` | Notifications | Approval notification templates exist | Ensure in-app approval notifications can render. | CRM/quotation | Query `app_notification_templates`. | Required approval templates active. | Some optional templates missing. | Required templates missing. | Run foundation seed. | notification foundation |
| `REPORT_DEFINITIONS` | Reports | Report definitions exist | Ensure report catalog works. | CRM reports | Query `crm_report_definitions`. | Required definitions active. | Definitions exist but categories missing. | No definitions. | Run report foundation seed. | report foundation |
| `CSV_PREVIEW` | Import | CSV preview integrity | Ensure uploaded files were validated before commit. | CSV import | Check latest preview hash/status. | Preview exists and matches commit input hash. | Preview stale after dependency change. | Missing preview for commit. | Re-run CSV preview. | setup import service |
| `SETUP_MANIFEST` | Setup | Seed manifest recorded | Ensure lifecycle tracking exists. | setup completion | Query proposed manifest tables once implemented. | Manifest recorded with checksums. | Manifest not implemented in early slice. | Manifest required but missing. | Implement D.7.8. | setup manifest service |

## Required Completion Rule

Setup can complete only when all required checks for selected setup mode pass:

- Production foundation mode: all first-login, CRM, quotation, storage/PDF required checks must pass except optional email may warn.
- Demo/UAT mode: production required checks plus UAT user/data checks must pass.
- Dry-run mode: failures do not write setup completion, but report can be exported.
