feat(assessments): layered clinical assessment engine end-to-end

Add a template-driven assessment system with universal intake, clinical
pathways, disease instruments (stroke MVP + extended, diabetes, and ten
specialty packs), scoring, patient outcome trends, REST/API + FHIR
export, and Enterprise org-level assessment analytics. Seed packs and
design/licensing docs ship for deploy and pre-GA review.

docs/assessment-instrument-licensing.md

@@ -0,0 +1,88 @@
+# Assessment instrument licensing review (pre-GA)
+
+**Status:** Working checklist for legal/clinical review before commercial GA packaging  
+**Date:** 2026-07-16  
+**Related:** `docs/layered-clinical-assessment-engine.md`, content packs under `database/data/assessments/`
+
+This document lists third-party and platform-authored instruments shipped as Care content packs. **Shipping code and seed data does not replace a formal legal review** for redistribution, branding, or clinical product claims in your jurisdiction.
+
+## Summary
+
+| Risk tier | Instruments | Guidance |
+|-----------|-------------|----------|
+| **Platform-authored** | universal_intake, stroke_swallow, stroke_clinical, diabetes_core, outcome_core, disease “_core” packs (HF, CKD, HTN, asthma, dementia, cancer, pregnancy, orthopaedics) | Own checklist content; still not a substitute for local clinical governance |
+| **Public domain / widely free clinical tools** | NIHSS (NINDS/NIH origin) | Confirm training/certification requirements for clinical use; attribution in pack `meta.attribution` |
+| **Standard scales — verify commercial rights** | mRS, Barthel, GCS, CAT (if used), mMRC, MMSE, MoCA, UPDRS, Hoehn & Yahr, NYHA, ECOG | Legal review before selling packs as a branded clinical product; some require licenses for electronic redistribution |
+| **Names only / user-entered scores** | MoCA/MMSE/UPDRS fields in dementia/PD packs are **score entry fields**, not full electronic instruments | Prefer facility-owned paper/electronic licensed tools; Care stores the numeric result |
+
+## Pack-by-pack notes
+
+### Platform-authored (lower IP risk)
+
+- `universal_intake`, `outcome_core`, `stroke_clinical`, `stroke_swallow`, `diabetes_core`
+- `heart_failure_core`, `ckd_core`, `hypertension_core`, `asthma_core`, `cancer_core`, `pregnancy_core`, `orthopaedics_core`, `dementia_core` (except MMSE/MoCA entry)
+
+**Action:** Clinical validation by medical lead; no third-party license expected for checklist wording authored by Ladill.
+
+### NIH Stroke Scale (`nihss`)
+
+- Origin: NIH/NINDS public clinical tool  
+- Pack includes item wording adapted for electronic capture  
+- **Action:** Confirm local training; keep attribution; do not claim NIH endorsement  
+
+### Modified Rankin Scale (`mrs`)
+
+- Widely used disability scale  
+- **Action:** Verify electronic redistribution / commercial packaging rights with counsel before GA  
+
+### Barthel Index (`barthel`)
+
+- ADL scale (Mahoney & Barthel lineage)  
+- **Action:** Licensing review for commercial electronic forms  
+
+### Glasgow Coma Scale (`gcs`)
+
+- Teasdale & Jennett  
+- **Action:** Confirm any trademark/use restrictions for branded products; clinical use is standard  
+
+### COPD pack (`copd_core`)
+
+- Includes **mMRC** scored item and free-entry **CAT** total (not full CAT questionnaire)  
+- **Action:** Full CAT electronic form may require GSK/community licensing — current pack only stores a numeric CAT score  
+
+### Parkinson's (`parkinsons_core`)
+
+- Hoehn & Yahr stages; optional **UPDRS total** as a number (not full UPDRS form)  
+- **Action:** Full MDS-UPDRS electronic use requires MDS permission  
+
+### Dementia (`dementia_core`)
+
+- Optional **MMSE** / **MoCA** numeric fields only  
+- **Action:** Do not embed full MMSE/MoCA item banks without licenses; MoCA especially is restricted  
+
+### Heart failure (`heart_failure_core`)
+
+- **NYHA** class as score_item  
+- **Action:** NYHA is a functional classification; low typical IP risk; still document clinical source  
+
+### Cancer (`cancer_core`)
+
+- **ECOG** performance status  
+- **Action:** Standard oncology scale; confirm branding claims  
+
+## Pre-GA checklist
+
+1. [ ] Medical lead signs off clinical appropriateness of each pack for target markets  
+2. [ ] Counsel reviews packs marked “verify commercial rights” above  
+3. [ ] Attribution strings in JSON `meta.attribution` remain accurate  
+4. [ ] Marketing copy does **not** claim “certified NIHSS training” or endorsement by instrument owners without agreement  
+5. [ ] For MoCA/MMSE/UPDRS/CAT: either obtain licenses for full forms or keep score-entry-only fields (current design)  
+6. [ ] Facility BAAs/privacy policies cover export of assessments (including FHIR export)  
+
+## Export & interoperability
+
+FHIR R4 export (`FhirAssessmentExporter`) emits Questionnaire + QuestionnaireResponse for interchange. It does not grant rights to redistribute third-party scale text outside Care; recipients remain responsible for their own compliance.
+
+## Contact
+
+Escalate open license questions to product + legal before enabling assessments engine by default for all production orgs.

docs/openapi/care.yaml

@@ -1,8 +1,11 @@
 openapi: 3.1.0
 info:
   title: Ladill Care API
-  version: 1.0.0
-  description: Healthcare management API at care.ladill.com
+  version: 1.1.0
+  description: |
+    Healthcare management API at care.ladill.com.
+    Assessment and pathway endpoints require organization `settings.rollout.assessments_engine = true`.
+    Public IDs are UUIDs (never internal integer FKs).
 servers:
   - url: https://care.ladill.com/api/v1
 paths:
@@ -16,6 +19,13 @@ paths:
       summary: List patients
     post:
       summary: Register patient
+  /patients/{patient}:
+    get:
+      summary: Patient dashboard
+    put:
+      summary: Update patient
+    delete:
+      summary: Archive patient
   /appointments:
     get:
       summary: List appointments
@@ -29,3 +39,250 @@ paths:
       summary: List pharmacy inventory
     post:
       summary: Add drug
+
+  /assessment-templates:
+    get:
+      summary: List current system assessment templates
+      tags: [Assessments]
+      security: [{ sanctum: [] }]
+      responses:
+        '200':
+          description: Template catalog with questions
+        '404':
+          description: Assessments engine not enabled
+
+  /patients/{patient}/assessments:
+    parameters:
+      - $ref: '#/components/parameters/PatientUuid'
+    get:
+      summary: List assessments for a patient
+      tags: [Assessments]
+      security: [{ sanctum: [] }]
+      parameters:
+        - name: status
+          in: query
+          schema: { type: string, enum: [draft, completed, cancelled] }
+        - name: template_code
+          in: query
+          schema: { type: string }
+        - name: category
+          in: query
+          schema: { type: string }
+      responses:
+        '200':
+          description: Paginated assessments
+    post:
+      summary: Start assessment (idempotent draft)
+      tags: [Assessments]
+      security: [{ sanctum: [] }]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [template_code]
+              properties:
+                template_code: { type: string, example: nihss }
+                consultation_uuid: { type: string, format: uuid, nullable: true }
+                visit_uuid: { type: string, format: uuid, nullable: true }
+      responses:
+        '200':
+          description: Existing draft returned
+        '201':
+          description: New draft created
+        '403':
+          description: Capture not allowed for role/template
+
+  /consultations/{consultation}/assessments:
+    post:
+      summary: Start assessment linked to consultation
+      tags: [Assessments]
+      security: [{ sanctum: [] }]
+      parameters:
+        - $ref: '#/components/parameters/ConsultationUuid'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [template_code]
+              properties:
+                template_code: { type: string }
+      responses:
+        '200':
+          description: Existing draft
+        '201':
+          description: Created
+
+  /assessments/{assessment}:
+    parameters:
+      - $ref: '#/components/parameters/AssessmentUuid'
+    get:
+      summary: Get assessment with answers and score
+      tags: [Assessments]
+      security: [{ sanctum: [] }]
+      responses:
+        '200':
+          description: Assessment detail
+    put:
+      summary: Save draft answers (keyed by question code)
+      tags: [Assessments]
+      security: [{ sanctum: [] }]
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                answers:
+                  type: object
+                  additionalProperties: true
+                  example: { chief_complaint: "Headache", pain_score: 4 }
+                notes: { type: string, nullable: true }
+      responses:
+        '200':
+          description: Updated
+        '422':
+          description: Not draft or validation error
+
+  /assessments/{assessment}/complete:
+    post:
+      summary: Complete assessment (validates required; materializes score if strategy set)
+      tags: [Assessments]
+      security: [{ sanctum: [] }]
+      parameters:
+        - $ref: '#/components/parameters/AssessmentUuid'
+      responses:
+        '200':
+          description: Completed with optional score
+        '422':
+          description: Missing required answers or already completed
+
+  /assessments/{assessment}/cancel:
+    post:
+      summary: Cancel draft assessment
+      tags: [Assessments]
+      security: [{ sanctum: [] }]
+      parameters:
+        - $ref: '#/components/parameters/AssessmentUuid'
+      responses:
+        '200':
+          description: Cancelled
+
+  /assessments/{assessment}/fhir:
+    get:
+      summary: Export assessment as FHIR R4 Bundle (Questionnaire + QuestionnaireResponse)
+      tags: [Assessments]
+      security: [{ sanctum: [] }]
+      parameters:
+        - $ref: '#/components/parameters/AssessmentUuid'
+      responses:
+        '200':
+          description: application/fhir+json Bundle
+          content:
+            application/fhir+json:
+              schema:
+                type: object
+
+  /pathways:
+    get:
+      summary: List active clinical pathway catalog
+      tags: [Pathways]
+      security: [{ sanctum: [] }]
+      responses:
+        '200':
+          description: Pathway catalog with template bindings
+
+  /patients/{patient}/pathways:
+    parameters:
+      - $ref: '#/components/parameters/PatientUuid'
+    get:
+      summary: Active and historical patient pathways
+      tags: [Pathways]
+      security: [{ sanctum: [] }]
+      responses:
+        '200':
+          description: Active + history
+    post:
+      summary: Activate pathway (creates required draft assessments)
+      tags: [Pathways]
+      security: [{ sanctum: [] }]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [pathway_code]
+              properties:
+                pathway_code: { type: string, example: stroke }
+                consultation_uuid: { type: string, format: uuid, nullable: true }
+                activation_diagnosis_text: { type: string, nullable: true }
+      responses:
+        '201':
+          description: Activated (idempotent if already active)
+
+  /patients/{patient}/pathways/{patientPathway}/deactivate:
+    post:
+      summary: Deactivate active pathway
+      tags: [Pathways]
+      security: [{ sanctum: [] }]
+      parameters:
+        - $ref: '#/components/parameters/PatientUuid'
+        - name: patientPathway
+          in: path
+          required: true
+          schema: { type: string, format: uuid }
+      responses:
+        '200':
+          description: Deactivated
+
+  /consultations/{consultation}/pathway-suggestions:
+    get:
+      summary: Suggest pathways from persisted diagnoses only
+      tags: [Pathways]
+      security: [{ sanctum: [] }]
+      parameters:
+        - $ref: '#/components/parameters/ConsultationUuid'
+      responses:
+        '200':
+          description: Ranked suggestions with match reasons
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        pathway_code: { type: string }
+                        pathway_name: { type: string }
+                        rank: { type: integer }
+                        match_reason: { type: string }
+                        already_active: { type: boolean }
+
+components:
+  securitySchemes:
+    sanctum:
+      type: http
+      scheme: bearer
+  parameters:
+    PatientUuid:
+      name: patient
+      in: path
+      required: true
+      schema: { type: string, format: uuid }
+    ConsultationUuid:
+      name: consultation
+      in: path
+      required: true
+      schema: { type: string, format: uuid }
+    AssessmentUuid:
+      name: assessment
+      in: path
+      required: true
+      schema: { type: string, format: uuid }