@ingenx-io/valets-schema-mcp-server 0.2.4 → 0.2.6

package/data/static/openapi.yaml

@@ -20,6 +20,16 @@ info:
 paths: {}
 components:
   schemas:
+    AppStatus:
+      type: string
+      enum:
+      - ACTIVE
+      - INACTIVE
+      - EXPIRED
+      - ARCHIVED
+      description: 'Lifecycle status for an App (formerly Site — renamed per decision
+        #40 / D44). Drives whether the app is reachable and whether analytics/payments
+        flow.'
     AttentionStatus:
       type: string
       enum:
@@ -41,6 +51,16 @@ components:
       - COMPLETED_MIXED
       description: Booking lifecycle status. COMPLETED_MIXED = some sessions completed,
         others cancelled/no-show.
+    ContractStatus:
+      type: string
+      enum:
+      - DRAFT
+      - ACTIVE
+      - COMPLETED
+      - TERMINATED
+      description: Lifecycle status of a Contract. DRAFT = not yet signed. ACTIVE
+        = in force. COMPLETED = all milestones paid and obligations met. TERMINATED
+        = ended early by either party.
     CustomerPaymentStatus:
       type: string
       enum:
@@ -110,6 +130,14 @@ components:
       - BONUS
       - REFUND
       description: Loyalty point transaction type (D07). SCREAMING_SNAKE past tense.
+    MilestoneStatus:
+      type: string
+      enum:
+      - PENDING
+      - INVOICED
+      - PAID
+      description: Status of a ContractMilestone (#17). PENDING = created, not yet
+        invoiced. INVOICED = invoice issued, awaiting payment. PAID = payment received.
     NotificationChannel:
       type: string
       enum:
@@ -299,8 +327,9 @@ components:
       enum:
       - cmz
       - val
-      description: Human-readable WABA label identifying which Meta business number
-        received the message (GH#36).
+      description: WABA label identifying which Meta Business Account sent/received
+        the message. cmz = Chez Miss Zahoui sender; val = Valets sender. See WhatsApp
+        platform constraints doc (#50).
     WhatsappButtonSubType:
       type: string
       enum:
@@ -345,7 +374,9 @@ components:
       - _seconds
       - _nanoseconds
       additionalProperties: false
-      description: Firestore Timestamp serialized representation
+      description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+        }. See types/firestore.ts for REST API v1 and client SDK serialization notes
+        (#10).'
     AllowedUser:
       type: object
       properties:
@@ -360,10 +391,11 @@ components:
           type: string
           x-immutable: true
           description: (Immutable) FK → Company document ID.
-        siteId:
+        appId:
           type: string
           x-immutable: true
-          description: (Immutable) FK → Site document ID (D40 sub-tenant scope).
+          description: (Immutable) FK → App document ID (D40 sub-tenant scope, renamed
+            per D44).
         contact:
           type: string
           description: Email or E.164 phone number. Canonical identifier for this
@@ -388,7 +420,7 @@ components:
           description: RFC3339Nano UTC when payment was completed.
       required:
       - companyId
-      - siteId
+      - appId
       - contact
       - tier
       - amount
@@ -396,7 +428,7 @@ components:
       - transactionId
       - paidAt
       additionalProperties: false
-      description: 'AllowedUser model (D40 / ING-304). Collection: companies/{companyId}/sites/{siteId}/allowed_users/{contactId}.
+      description: 'AllowedUser model (D40 / ING-304). Collection: companies/{companyId}/apps/{appId}/allowed_users/{contactId}.
         Authoritative paid-access allowlist. Upsert semantics — tier upgrades overwrite.
         Source of truth for access checks and referral code resolution.'
     AllowedUserCreate:
@@ -407,7 +439,7 @@ components:
         may be set once at creation.
       required:
       - companyId
-      - siteId
+      - appId
       - contact
       - tier
       - amount
@@ -433,7 +465,7 @@ components:
           type: string
           x-immutable: true
           description: (Immutable) FK → Company document ID.
-        siteId:
+        appId:
           type: string
           x-immutable: true
           description: (Immutable) FK → Site document ID (D40).
@@ -501,7 +533,7 @@ components:
           description: (Read-only) When the run reached a terminal status.
       required:
       - companyId
-      - siteId
+      - appId
       - status
       - from
       - to
@@ -511,7 +543,7 @@ components:
       - triggeredBy
       - startedAt
       additionalProperties: false
-      description: 'AnalyticsBackfill run (D42 / ING-304). Collection: companies/{companyId}/sites/{siteId}/analytics_backfills/{runId}.
+      description: 'AnalyticsBackfill run (D42 / ING-304). Collection: companies/{companyId}/apps/{appId}/analytics_backfills/{runId}.
         Tracks admin-triggered rollup backfill jobs; supports dry-run.'
     AnalyticsBackfillCreate:
       allOf:
@@ -521,7 +553,7 @@ components:
         may be set once at creation.
       required:
       - companyId
-      - siteId
+      - appId
       - status
       - from
       - to
@@ -607,7 +639,7 @@ components:
           type: string
           x-immutable: true
           description: (Immutable) FK → Company document ID.
-        siteId:
+        appId:
           type: string
           x-immutable: true
           description: (Immutable) FK → Site document ID (D40).
@@ -641,11 +673,11 @@ components:
       - errors
       - eventCounts
       - companyId
-      - siteId
+      - appId
       - date
       - computedAt
       additionalProperties: false
-      description: 'AnalyticsDaily rollup (D42 / ING-304). Collection: companies/{companyId}/sites/{siteId}/analytics_daily/{YYYY-MM-DD}.
+      description: 'AnalyticsDaily rollup (D42 / ING-304). Collection: companies/{companyId}/apps/{appId}/analytics_daily/{YYYY-MM-DD}.
         Idempotent set/merge — reruns overwrite. Fall back to raw analytics_events
         for uncovered slices.'
     AnalyticsDailyCreate:
@@ -666,7 +698,7 @@ components:
       - errors
       - eventCounts
       - companyId
-      - siteId
+      - appId
       - date
     AnalyticsDailyUpdate:
       allOf:
@@ -687,10 +719,11 @@ components:
           type: string
           x-immutable: true
           description: (Immutable) FK → Company document ID.
-        siteId:
+        appId:
           type: string
           x-immutable: true
-          description: (Immutable) FK → Site document ID (D40 sub-tenant scope).
+          description: (Immutable) FK → App document ID (D40 sub-tenant scope, renamed
+            per D44).
         eventId:
           type: string
           x-immutable: true
@@ -806,7 +839,7 @@ components:
           additionalProperties: {}
       required:
       - companyId
-      - siteId
+      - appId
       - eventId
       - eventName
       - timestamp
@@ -816,7 +849,7 @@ components:
       - properties
       - context
       additionalProperties: false
-      description: 'AnalyticsEvent model (D40 / ING-304). Collection: companies/{companyId}/sites/{siteId}/analytics_events/{eventId}.
+      description: 'AnalyticsEvent model (D40 / ING-304). Collection: companies/{companyId}/apps/{appId}/analytics_events/{eventId}.
         Append-only, immutable product/behavior event stream. Event names are free
         strings; canonical vocabulary in CANONICAL_ANALYTICS_EVENT_NAMES.'
     AnalyticsEventCreate:
@@ -827,7 +860,7 @@ components:
         may be set once at creation.
       required:
       - companyId
-      - siteId
+      - appId
       - eventId
       - eventName
       - timestamp
@@ -913,7 +946,7 @@ components:
           type: string
           x-immutable: true
           description: (Immutable) FK → Company document ID.
-        siteId:
+        appId:
           type: string
           x-immutable: true
           description: (Immutable) FK → Site document ID (D40).
@@ -952,12 +985,12 @@ components:
       - errors
       - eventCounts
       - companyId
-      - siteId
+      - appId
       - date
       - hour
       - computedAt
       additionalProperties: false
-      description: 'AnalyticsHourly rollup (D42 / ING-304). Collection: companies/{companyId}/sites/{siteId}/analytics_hourly/{YYYY-MM-DD-HH}.
+      description: 'AnalyticsHourly rollup (D42 / ING-304). Collection: companies/{companyId}/apps/{appId}/analytics_hourly/{YYYY-MM-DD-HH}.
         Scheduled-CF writer; idempotent set/merge.'
     AnalyticsHourlyCreate:
       allOf:
@@ -977,7 +1010,7 @@ components:
       - errors
       - eventCounts
       - companyId
-      - siteId
+      - appId
       - date
       - hour
     AnalyticsHourlyUpdate:
@@ -986,6 +1019,267 @@ components:
       description: Write payload for partial update (PATCH) of a AnalyticsHourly document.
         All fields optional. Fields marked `readOnly` or `x-immutable` must not be
         sent.
+    App:
+      type: object
+      properties:
+        id:
+          readOnly: true
+          description: (Read-only) Firestore document ID, auto-generated.
+          type:
+          - string
+          - 'null'
+        companyId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Company document ID. Scopes all app sub-collections.
+        name:
+          type: string
+          description: Human-readable app name shown in dashboards.
+        description:
+          description: Optional freeform description.
+          type:
+          - string
+          - 'null'
+        status:
+          anyOf:
+          - $ref: '#/components/schemas/AppStatus'
+          - type: 'null'
+          x-note: Real Firestore documents may be missing this field on pre-backfill
+            records (#26). Treat absent as ACTIVE. A backfill script will populate
+            status=ACTIVE on all existing documents; once confirmed, this field will
+            be promoted to required.
+          x-when: Written by operators via dashboard or by server triggers (expiration).
+            Clients must not use server-side `where(status == ACTIVE)` until backfill
+            is complete — filter client-side instead, treating absent as ACTIVE.
+          description: Lifecycle status (D41/D44). Optional pending backfill of pre-existing
+            records (#26) — treat absent as ACTIVE. Clients filter by ACTIVE.
+          x-see:
+            decisions:
+            - D41
+            - D44
+        deploymentLinks:
+          type: array
+          items:
+            type: object
+            properties:
+              label:
+                type: string
+                description: Human-readable label shown in dashboards (e.g. "Production",
+                  "Staging").
+              url:
+                type: string
+                description: Absolute URL or store link.
+              type:
+                $ref: '#/components/schemas/DeploymentLinkType'
+                description: Link category — drives icon/handler selection.
+                x-note: Lowercase by convention — deployment link types are display-oriented
+                  labels, not lifecycle states.
+                x-see:
+                  decisions:
+                  - D41
+              isPrimary:
+                description: If true, this link is used as the canonical deployment
+                  URL for the App.
+                type: boolean
+            required:
+            - label
+            - url
+            - type
+            additionalProperties: false
+            description: Deployment link entry embedded on App.deploymentLinks[] (D41).
+          description: Ordered list of deployment URLs (web, mobile, PWA, store links).
+        expiresAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          description: Optional expiration timestamp. When set and elapsed, `isExpired`
+            flips true and status typically moves to EXPIRED.
+        isExpired:
+          readOnly: true
+          description: (Read-only) Derived — true when `expiresAt` is in the past.
+            Maintained by server trigger.
+          type:
+          - boolean
+          - 'null'
+        createdAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Server-generated creation timestamp.
+        updatedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Server-generated update timestamp.
+        createdBy:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → User/staff UID who created the app.
+        analyticsEnabled:
+          type: boolean
+          description: Feature flag — when false, clients should not emit analytics
+            events for this app.
+        lastAnalyticsSync:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Last time the analytics rollup pipeline refreshed
+            `cachedMetrics`.
+        cachedMetrics:
+          readOnly: true
+          denormalized: true
+          x-note: Updated by the rollup pipeline (D42). Readers should treat this
+            as a hint; authoritative counts live in analytics_daily/analytics_hourly.
+          x-see:
+            decisions:
+            - D41
+            - D42
+          description: (Read-only, Denormalized) Cached metrics snapshot for quick
+            dashboard rendering.
+          type:
+          - object
+          - 'null'
+          properties:
+            totalEvents:
+              type: integer
+              minimum: -9007199254740991
+              maximum: 9007199254740991
+              description: All-time event count cached on the App.
+            totalPageViews:
+              type: integer
+              minimum: -9007199254740991
+              maximum: 9007199254740991
+              description: All-time `page_view` + `screen_view` count.
+            totalSessions:
+              type: integer
+              minimum: -9007199254740991
+              maximum: 9007199254740991
+              description: All-time distinct session count.
+            totalOrders:
+              type: integer
+              minimum: -9007199254740991
+              maximum: 9007199254740991
+              description: All-time order count attributed to this app (via `Order.appId`,
+                D43).
+            lastEventAt:
+              $ref: '#/components/schemas/FirestoreTimestamp'
+              description: Timestamp of the most recent analytics event seen for this
+                app.
+          required:
+          - totalEvents
+          - totalPageViews
+          - totalSessions
+          - totalOrders
+          additionalProperties: false
+      required:
+      - companyId
+      - name
+      - deploymentLinks
+      - createdBy
+      - analyticsEnabled
+      additionalProperties: false
+      description: 'App model (D41 / ING-304). Collection: companies/{companyId}/apps/{appId}.
+        Per-company product surface. Sub-collections (magic_link_requests, allowed_users,
+        payments, analytics_events, analytics_daily, analytics_hourly, analytics_backfills)
+        live under this document per D40/D42.'
+    AppCreate:
+      allOf:
+      - $ref: '#/components/schemas/App'
+      description: Write payload for creating a new App document. Fields marked `readOnly`
+        are server-set and must not be included. Fields marked `x-immutable` may be
+        set once at creation.
+      required:
+      - companyId
+      - name
+      - deploymentLinks
+      - createdBy
+      - analyticsEnabled
+    AppUpdate:
+      allOf:
+      - $ref: '#/components/schemas/App'
+      description: Write payload for partial update (PATCH) of a App document. All
+        fields optional. Fields marked `readOnly` or `x-immutable` must not be sent.
+    AppPayment:
+      type: object
+      properties:
+        id:
+          readOnly: true
+          description: (Read-only) Firestore document ID, auto-generated.
+          type:
+          - string
+          - 'null'
+        companyId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Company document ID.
+        appId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → App document ID (D40 sub-tenant scope, renamed
+            from siteId per D44).
+        contact:
+          type: string
+          description: Email or E.164 phone number. Matches AllowedUser.contact.
+        sessionId:
+          type: string
+          description: Payment provider checkout session ID (e.g. Wave). Usable for
+            dedup across dual writes.
+        transactionId:
+          type: string
+          description: Payment provider transaction ID.
+        tier:
+          type: string
+          description: Access tier. Free string per app (ING-304 open question).
+        amount:
+          type: number
+          description: Amount paid. Generalized from amount_xof per D40 decision.
+        currency:
+          default: XOF
+          description: Currency code (ISO 4217). Defaults to XOF for legacy SR-Single
+            parity.
+          type: string
+        paidAt:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: RFC3339Nano UTC when payment was completed.
+      required:
+      - companyId
+      - appId
+      - contact
+      - sessionId
+      - transactionId
+      - tier
+      - amount
+      - currency
+      - paidAt
+      additionalProperties: false
+      description: 'AppPayment model (D40 / ING-304). Collection: companies/{companyId}/apps/{appId}/payments/{paymentId}.
+        Immutable append-only transaction ledger. Distinct from AllowedUser (access
+        state) and CustomerPayment (D22 — customer-level billing).'
+    AppPaymentCreate:
+      allOf:
+      - $ref: '#/components/schemas/AppPayment'
+      description: Write payload for creating a new AppPayment document. Fields marked
+        `readOnly` are server-set and must not be included. Fields marked `x-immutable`
+        may be set once at creation.
+      required:
+      - companyId
+      - appId
+      - contact
+      - sessionId
+      - transactionId
+      - tier
+      - amount
+      - currency
+      - paidAt
+    AppPaymentUpdate:
+      allOf:
+      - $ref: '#/components/schemas/AppPayment'
+      description: Write payload for partial update (PATCH) of a AppPayment document.
+        All fields optional. Fields marked `readOnly` or `x-immutable` must not be
+        sent.
     Booking:
       type: object
       properties:
@@ -1062,13 +1356,17 @@ components:
                       type: boolean
                     _deletedAt:
                       $ref: '#/components/schemas/FirestoreTimestamp'
-                      description: Firestore Timestamp serialized representation
+                      description: 'Firestore Timestamp — Admin SDK form: { _seconds,
+                        _nanoseconds }. See types/firestore.ts for REST API v1 and
+                        client SDK serialization notes (#10).'
                     _deletedBy:
                       description: FK → User/staff UID who soft-deleted this item.
                       type: string
                     _lastModifiedAt:
                       $ref: '#/components/schemas/FirestoreTimestamp'
-                      description: Firestore Timestamp serialized representation
+                      description: 'Firestore Timestamp — Admin SDK form: { _seconds,
+                        _nanoseconds }. See types/firestore.ts for REST API v1 and
+                        client SDK serialization notes (#10).'
                     _lastModifiedBy:
                       description: FK → User/staff UID who last modified this item.
                       type: string
@@ -1133,7 +1431,9 @@ components:
                   type: string
                 additionalProperties:
                   $ref: '#/components/schemas/FirestoreTimestamp'
-                  description: Firestore Timestamp serialized representation
+                  description: 'Firestore Timestamp — Admin SDK form: { _seconds,
+                    _nanoseconds }. See types/firestore.ts for REST API v1 and client
+                    SDK serialization notes (#10).'
               slotStatusUpdatedBy:
                 type: object
                 propertyNames:
@@ -1145,13 +1445,17 @@ components:
                 type: boolean
               _deletedAt:
                 $ref: '#/components/schemas/FirestoreTimestamp'
-                description: Firestore Timestamp serialized representation
+                description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+                  }. See types/firestore.ts for REST API v1 and client SDK serialization
+                  notes (#10).'
               _deletedBy:
                 description: FK → User/staff UID who soft-deleted this item.
                 type: string
               _lastModifiedAt:
                 $ref: '#/components/schemas/FirestoreTimestamp'
-                description: Firestore Timestamp serialized representation
+                description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+                  }. See types/firestore.ts for REST API v1 and client SDK serialization
+                  notes (#10).'
               _lastModifiedBy:
                 description: FK → User/staff UID who last modified this item.
                 type: string
@@ -1313,13 +1617,17 @@ components:
                 type: boolean
               _deletedAt:
                 $ref: '#/components/schemas/FirestoreTimestamp'
-                description: Firestore Timestamp serialized representation
+                description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+                  }. See types/firestore.ts for REST API v1 and client SDK serialization
+                  notes (#10).'
               _deletedBy:
                 description: FK → User/staff UID who soft-deleted this item.
                 type: string
               _lastModifiedAt:
                 $ref: '#/components/schemas/FirestoreTimestamp'
-                description: Firestore Timestamp serialized representation
+                description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+                  }. See types/firestore.ts for REST API v1 and client SDK serialization
+                  notes (#10).'
               _lastModifiedBy:
                 description: FK → User/staff UID who last modified this item.
                 type: string
@@ -1372,7 +1680,9 @@ components:
           anyOf:
           - $ref: '#/components/schemas/FirestoreTimestamp'
           - type: 'null'
-          description: Firestore Timestamp serialized representation
+          description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+            }. See types/firestore.ts for REST API v1 and client SDK serialization
+            notes (#10).'
         paymentProofUrl:
           description: URL to uploaded payment proof image/document.
           type:
@@ -1388,7 +1698,9 @@ components:
           anyOf:
           - $ref: '#/components/schemas/FirestoreTimestamp'
           - type: 'null'
-          description: Firestore Timestamp serialized representation
+          description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+            }. See types/firestore.ts for REST API v1 and client SDK serialization
+            notes (#10).'
         paymentProofAddedBy:
           description: FK → User/staff UID who uploaded the payment proof.
           type:
@@ -1403,7 +1715,9 @@ components:
           anyOf:
           - $ref: '#/components/schemas/FirestoreTimestamp'
           - type: 'null'
-          description: Firestore Timestamp serialized representation
+          description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+            }. See types/firestore.ts for REST API v1 and client SDK serialization
+            notes (#10).'
         paymentProofRejectionReason:
           type:
           - string
@@ -1426,7 +1740,9 @@ components:
           anyOf:
           - $ref: '#/components/schemas/FirestoreTimestamp'
           - type: 'null'
-          description: Firestore Timestamp serialized representation
+          description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+            }. See types/firestore.ts for REST API v1 and client SDK serialization
+            notes (#10).'
         cancelledByRole:
           type:
           - string
@@ -1587,6 +1903,156 @@ components:
       description: 'BookingVersion model (D18). Collection: companies/{companyId}/bookings/{bookingId}/versions/{versionId}.
         Server-owned audit trail written by Firebase trigger on every Booking mutation.
         Captures writes from all clients.'
+    Contract:
+      type: object
+      properties:
+        id:
+          readOnly: true
+          description: (Read-only) Firestore document ID, auto-generated.
+          type:
+          - string
+          - 'null'
+        companyId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Company document ID.
+        payeeId:
+          type: string
+          x-immutable: true
+          description: '(Immutable) FK → Payee document ID. Full Payee model tracked
+            in #20.'
+        title:
+          type: string
+          description: Contract title or reference name shown in dashboards.
+        description:
+          description: Optional freeform description of the contract scope.
+          type:
+          - string
+          - 'null'
+        status:
+          $ref: '#/components/schemas/ContractStatus'
+          description: Contract lifecycle status (#14). Query by ACTIVE — do not use
+            an isActive boolean.
+        currency:
+          type: string
+          const: XOF
+          description: Currency code. Locked to XOF (#18). Multi-currency support
+            requires a deliberate schema version bump.
+        totalAmount:
+          type: number
+          description: Total contract value (XOF).
+        startDate:
+          type: string
+          description: Contract start date (ISO 8601 YYYY-MM-DD).
+        endDate:
+          description: Contract end date (ISO 8601 YYYY-MM-DD). Absent for open-ended
+            contracts.
+          type:
+          - string
+          - 'null'
+        milestones:
+          description: Ordered list of payment milestones. Embedded in the contract
+            document (#17).
+          type:
+          - array
+          - 'null'
+          items:
+            type: object
+            properties:
+              id:
+                type: string
+                description: Client-generated milestone ID (UUID or slug). Unique
+                  within the contract.
+              title:
+                type: string
+                description: Milestone description or deliverable name.
+              amount:
+                type: number
+                description: Amount due at this milestone (XOF).
+              dueDate:
+                description: ISO 8601 date string (YYYY-MM-DD) when the milestone
+                  is due. OVERDUE is derived at read time from dueDate — not stored.
+                type: string
+              status:
+                $ref: '#/components/schemas/MilestoneStatus'
+                x-note: Existing Firestore documents may have lowercase values (pending,
+                  invoiced, paid) from before this enum was introduced (#17). Normalize
+                  on read or via migration script.
+                description: Milestone payment status (#17). OVERDUE is derived at
+                  read time from dueDate, not stored.
+              invoicedAt:
+                $ref: '#/components/schemas/FirestoreTimestamp'
+                description: When the invoice was issued for this milestone.
+              paidAt:
+                $ref: '#/components/schemas/FirestoreTimestamp'
+                description: When payment was received for this milestone.
+              notes:
+                description: Optional notes for this milestone.
+                type: string
+            required:
+            - id
+            - title
+            - amount
+            - status
+            additionalProperties: false
+            description: ContractMilestone — embedded sub-object on Contract (#17).
+              Not a separate collection.
+        notes:
+          description: Optional internal notes.
+          type:
+          - string
+          - 'null'
+        createdBy:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → User/staff UID who created the contract.
+        createdAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Server-generated creation timestamp.
+        updatedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Server-generated update timestamp.
+      required:
+      - companyId
+      - payeeId
+      - title
+      - status
+      - currency
+      - totalAmount
+      - startDate
+      - createdBy
+      additionalProperties: false
+      description: 'Contract model (GH#14/#17/#18). Collection: companies/{companyId}/contracts/{contractId}.
+        Service/supplier contract between a company and a Payee. No isActive field
+        — query by status. Currency locked to XOF. Milestones use MilestoneStatus
+        enum (no stored OVERDUE).'
+    ContractCreate:
+      allOf:
+      - $ref: '#/components/schemas/Contract'
+      description: Write payload for creating a new Contract document. Fields marked
+        `readOnly` are server-set and must not be included. Fields marked `x-immutable`
+        may be set once at creation.
+      required:
+      - companyId
+      - payeeId
+      - title
+      - status
+      - currency
+      - totalAmount
+      - startDate
+      - createdBy
+    ContractUpdate:
+      allOf:
+      - $ref: '#/components/schemas/Contract'
+      description: Write payload for partial update (PATCH) of a Contract document.
+        All fields optional. Fields marked `readOnly` or `x-immutable` must not be
+        sent.
     Customer:
       type: object
       properties:
@@ -1633,7 +2099,9 @@ components:
             properties:
               timestamp:
                 $ref: '#/components/schemas/FirestoreTimestamp'
-                description: Firestore Timestamp serialized representation
+                description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+                  }. See types/firestore.ts for REST API v1 and client SDK serialization
+                  notes (#10).'
               type:
                 type: string
                 description: Communication channel (e.g. phone, email, meeting).
@@ -1750,7 +2218,9 @@ components:
           description: Currency code. Locked to XOF (West African CFA franc) for now.
         paymentDate:
           $ref: '#/components/schemas/FirestoreTimestamp'
-          description: Firestore Timestamp serialized representation
+          description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+            }. See types/firestore.ts for REST API v1 and client SDK serialization
+            notes (#10).'
         paymentMethod:
           $ref: '#/components/schemas/PaymentMethod'
           description: Unified payment method set with African + global methods (D02).
@@ -1894,7 +2364,9 @@ components:
           anyOf:
           - $ref: '#/components/schemas/FirestoreTimestamp'
           - type: 'null'
-          description: Firestore Timestamp serialized representation
+          description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+            }. See types/firestore.ts for REST API v1 and client SDK serialization
+            notes (#10).'
         createdBy:
           type: string
           x-immutable: true
@@ -1967,12 +2439,16 @@ components:
           - 'null'
         startDate:
           $ref: '#/components/schemas/FirestoreTimestamp'
-          description: Firestore Timestamp serialized representation
+          description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+            }. See types/firestore.ts for REST API v1 and client SDK serialization
+            notes (#10).'
         endDate:
           anyOf:
           - $ref: '#/components/schemas/FirestoreTimestamp'
           - type: 'null'
-          description: Firestore Timestamp serialized representation
+          description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+            }. See types/firestore.ts for REST API v1 and client SDK serialization
+            notes (#10).'
         status:
           $ref: '#/components/schemas/EventStatus'
           description: Event lifecycle status (D32). SCREAMING_SNAKE per D04. MIG-09
@@ -2417,10 +2893,11 @@ components:
           type: string
           x-immutable: true
           description: (Immutable) FK → Company document ID.
-        siteId:
+        appId:
           type: string
           x-immutable: true
-          description: (Immutable) FK → Site document ID (D40 sub-tenant scope).
+          description: (Immutable) FK → App document ID (D40 sub-tenant scope, renamed
+            per D44).
         email:
           type: string
           description: Populated if identifier is email; empty string if phone. Mutually
@@ -2472,7 +2949,7 @@ components:
           description: RFC3339Nano UTC at verify time.
       required:
       - companyId
-      - siteId
+      - appId
       - email
       - phone
       - ip
@@ -2483,7 +2960,7 @@ components:
       - referredBy
       - requestedAt
       additionalProperties: false
-      description: 'MagicLinkRequest model (D40 / ING-304). Collection: companies/{companyId}/sites/{siteId}/magic_link_requests/{requestId}.
+      description: 'MagicLinkRequest model (D40 / ING-304). Collection: companies/{companyId}/apps/{appId}/magic_link_requests/{requestId}.
         Authentication audit log — every request is logged regardless of outcome.
         Two-stage write: Log() then LogVerify().'
     MagicLinkRequestCreate:
@@ -2494,7 +2971,7 @@ components:
         may be set once at creation.
       required:
       - companyId
-      - siteId
+      - appId
       - email
       - phone
       - ip
@@ -2650,8 +3127,64 @@ components:
         monthlyRecurringRevenue:
           type: number
           readOnly: true
-          description: (Read-only) Sum of amount for ACTIVE + MONTHLY recurring payments.
-            Always full recalc.
+          description: (Read-only) Sum of amount for ACTIVE + MONTHLY recurring payments.
+            Always full recalc.
+        escalatedOrdersCount:
+          readOnly: true
+          x-note: Absent on tenants whose metrics/current was last written before
+            aggregator v2. Backfill required for universal presence (#8).
+          description: (Read-only, Optional) Orders currently in an escalated state.
+            Present once the current aggregator rewrites the document.
+          type:
+          - integer
+          - 'null'
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        staleOrdersCount:
+          readOnly: true
+          x-note: Absent on tenants whose metrics/current was last written before
+            aggregator v2. Backfill required for universal presence (#8).
+          description: (Read-only, Optional) Orders that have been in an incomplete
+            status beyond the stale threshold.
+          type:
+          - integer
+          - 'null'
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        staleBookingsCount:
+          readOnly: true
+          x-note: Absent on tenants whose metrics/current was last written before
+            aggregator v2. Backfill required for universal presence (#8).
+          description: (Read-only, Optional) Bookings that have been in an incomplete
+            status beyond the stale threshold.
+          type:
+          - integer
+          - 'null'
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        onHoldOrdersCount:
+          readOnly: true
+          x-note: Absent on tenants whose metrics/current was last written before
+            aggregator v2. Backfill required for universal presence (#8).
+          description: (Read-only, Optional) Orders currently in an on-hold state.
+          type:
+          - integer
+          - 'null'
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        paymentsByMethod:
+          readOnly: true
+          x-note: Always {} until the first real payment is recorded. Present on all
+            tenants once rewritten by current aggregator (#8).
+          description: (Read-only, Optional) Map of PaymentMethod → total amount for
+            the current day. Empty map {} until first payment.
+          type:
+          - object
+          - 'null'
+          propertyNames:
+            type: string
+          additionalProperties:
+            type: number
         computedForDay:
           type: string
           readOnly: true
@@ -2845,6 +3378,62 @@ components:
           readOnly: true
           description: (Read-only) Sum of amount for ACTIVE + MONTHLY recurring payments.
             Always full recalc.
+        escalatedOrdersCount:
+          readOnly: true
+          x-note: Absent on tenants whose metrics/current was last written before
+            aggregator v2. Backfill required for universal presence (#8).
+          description: (Read-only, Optional) Orders currently in an escalated state.
+            Present once the current aggregator rewrites the document.
+          type:
+          - integer
+          - 'null'
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        staleOrdersCount:
+          readOnly: true
+          x-note: Absent on tenants whose metrics/current was last written before
+            aggregator v2. Backfill required for universal presence (#8).
+          description: (Read-only, Optional) Orders that have been in an incomplete
+            status beyond the stale threshold.
+          type:
+          - integer
+          - 'null'
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        staleBookingsCount:
+          readOnly: true
+          x-note: Absent on tenants whose metrics/current was last written before
+            aggregator v2. Backfill required for universal presence (#8).
+          description: (Read-only, Optional) Bookings that have been in an incomplete
+            status beyond the stale threshold.
+          type:
+          - integer
+          - 'null'
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        onHoldOrdersCount:
+          readOnly: true
+          x-note: Absent on tenants whose metrics/current was last written before
+            aggregator v2. Backfill required for universal presence (#8).
+          description: (Read-only, Optional) Orders currently in an on-hold state.
+          type:
+          - integer
+          - 'null'
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        paymentsByMethod:
+          readOnly: true
+          x-note: Always {} until the first real payment is recorded. Present on all
+            tenants once rewritten by current aggregator (#8).
+          description: (Read-only, Optional) Map of PaymentMethod → total amount for
+            the current day. Empty map {} until first payment.
+          type:
+          - object
+          - 'null'
+          propertyNames:
+            type: string
+          additionalProperties:
+            type: number
         computedForDay:
           type: string
           readOnly: true
@@ -3044,6 +3633,62 @@ components:
           readOnly: true
           description: (Read-only) Sum of amount for ACTIVE + MONTHLY recurring payments.
             Always full recalc.
+        escalatedOrdersCount:
+          readOnly: true
+          x-note: Absent on tenants whose metrics/current was last written before
+            aggregator v2. Backfill required for universal presence (#8).
+          description: (Read-only, Optional) Orders currently in an escalated state.
+            Present once the current aggregator rewrites the document.
+          type:
+          - integer
+          - 'null'
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        staleOrdersCount:
+          readOnly: true
+          x-note: Absent on tenants whose metrics/current was last written before
+            aggregator v2. Backfill required for universal presence (#8).
+          description: (Read-only, Optional) Orders that have been in an incomplete
+            status beyond the stale threshold.
+          type:
+          - integer
+          - 'null'
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        staleBookingsCount:
+          readOnly: true
+          x-note: Absent on tenants whose metrics/current was last written before
+            aggregator v2. Backfill required for universal presence (#8).
+          description: (Read-only, Optional) Bookings that have been in an incomplete
+            status beyond the stale threshold.
+          type:
+          - integer
+          - 'null'
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        onHoldOrdersCount:
+          readOnly: true
+          x-note: Absent on tenants whose metrics/current was last written before
+            aggregator v2. Backfill required for universal presence (#8).
+          description: (Read-only, Optional) Orders currently in an on-hold state.
+          type:
+          - integer
+          - 'null'
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        paymentsByMethod:
+          readOnly: true
+          x-note: Always {} until the first real payment is recorded. Present on all
+            tenants once rewritten by current aggregator (#8).
+          description: (Read-only, Optional) Map of PaymentMethod → total amount for
+            the current day. Empty map {} until first payment.
+          type:
+          - object
+          - 'null'
+          propertyNames:
+            type: string
+          additionalProperties:
+            type: number
         computedForDay:
           type: string
           readOnly: true
@@ -3263,9 +3908,11 @@ components:
       - createdAt
       additionalProperties: false
       description: 'NotificationRecord — backend-written, multi-channel notification
-        audit log (GH#48). Paths: companies/{cid}/notifications/{id} (always) and
-        companies/{cid}/orders/{oid}/notifications/{id} (dual-write when relatedEntity.type=order).
-        Consumers read only. Distinct from WhatsappOutboundMessage (GH#43).'
+        audit log (GH#48). Paths: companies/{cid}/notification_records/{id} (always)
+        and companies/{cid}/orders/{oid}/notification_records/{id} (dual-write when
+        relatedEntity.type=order). Consumers read only. Distinct from WhatsappOutboundMessage
+        (GH#43). Collection renamed from notifications → notification_records per
+        decision #55 (2026-05-30).'
     Order:
       type: object
       properties:
@@ -3282,20 +3929,22 @@ components:
           type: string
           x-immutable: true
           description: (Immutable) FK → Company document ID. Scopes all queries.
-        siteId:
+        appId:
           x-immutable: true
-          x-note: 'D43 / ADR-003: optional site attribution. Absent/null means company-wide
-            (legacy). When set, the order is attributed to a specific site for analytics
-            and site-scoped dashboards. No migration — existing orders keep null.
-            Flat path; Order continues to live at `companies/{companyId}/orders/{orderId}`.'
+          x-note: 'D43 / ADR-003: optional app attribution (renamed from siteId per
+            D44). Absent/null means company-wide (legacy). When set, the order is
+            attributed to a specific app for analytics and app-scoped dashboards.
+            No migration — existing orders keep null. Flat path; Order continues to
+            live at `companies/{companyId}/orders/{orderId}`.'
           x-see:
             decisions:
             - D43
-          x-when: 'Set at order creation when the client knows which site the order
+            - D44
+          x-when: 'Set at order creation when the client knows which app the order
             originated from (e.g. SR Single, Lifesense). Leave null for legacy/company-wide
-            orders. Composite index: (companyId, siteId, createdAt).'
-          description: (Immutable, Optional) FK → Site document ID (D43 / ADR-003).
-            null = company-wide.
+            orders. Composite index: (companyId, appId, createdAt).'
+          description: (Immutable, Optional) FK → App document ID (D43 / ADR-003,
+            renamed from siteId per D44). null = company-wide.
           type:
           - string
           - 'null'
@@ -3303,6 +3952,17 @@ components:
           type: string
           readOnly: true
           description: (Read-only) Server-generated order number.
+        followUpUrl:
+          x-note: Standardized casing is followUpUrl (not followUpURL). Mobile legacy
+            code reads both casings for backward compat but writes followUpUrl going
+            forward (#6).
+          x-when: 'Used by mobile to generate QR codes on printed receipts. If absent,
+            the mobile app derives a deterministic fallback: https://zahoui.web.app/reviews?orderNumber={orderNumber}.'
+          description: 'Optional URL for receipt QR code / post-order follow-up. Canonical
+            casing: followUpUrl (#6).'
+          type:
+          - string
+          - 'null'
         status:
           $ref: '#/components/schemas/OrderStatus'
           description: Core lifecycle status (D34, MIG-11). See OrderStatus enum for
@@ -3485,7 +4145,9 @@ components:
           readOnly: true
         orderDate:
           $ref: '#/components/schemas/FirestoreTimestamp'
-          description: Firestore Timestamp serialized representation
+          description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+            }. See types/firestore.ts for REST API v1 and client SDK serialization
+            notes (#10).'
         PROCESSING_ON:
           anyOf:
           - $ref: '#/components/schemas/FirestoreTimestamp'
@@ -3530,7 +4192,9 @@ components:
           anyOf:
           - $ref: '#/components/schemas/FirestoreTimestamp'
           - type: 'null'
-          description: Firestore Timestamp serialized representation
+          description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+            }. See types/firestore.ts for REST API v1 and client SDK serialization
+            notes (#10).'
         shippingCost:
           type:
           - number
@@ -3617,7 +4281,9 @@ components:
                 description: Payment method used (D02).
               paymentDate:
                 $ref: '#/components/schemas/FirestoreTimestamp'
-                description: Firestore Timestamp serialized representation
+                description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+                  }. See types/firestore.ts for REST API v1 and client SDK serialization
+                  notes (#10).'
               referenceNumber:
                 description: Payment reference (receipt number, transaction ID, etc.).
                 type: string
@@ -3831,6 +4497,235 @@ components:
       description: Write payload for partial update (PATCH) of a OrderItem document.
         All fields optional. Fields marked `readOnly` or `x-immutable` must not be
         sent.
+    OutboundPayment:
+      type: object
+      properties:
+        id:
+          readOnly: true
+          description: (Read-only) Firestore document ID, auto-generated.
+          type:
+          - string
+          - 'null'
+        companyId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Company document ID.
+        payeeId:
+          type: string
+          x-immutable: true
+          description: '(Immutable) FK → Payee document ID. Full Payee model tracked
+            in #20.'
+        contractId:
+          x-immutable: true
+          description: (Immutable, Optional) FK → Contract document ID. Absent for
+            ad-hoc payments outside a formal contract.
+          type:
+          - string
+          - 'null'
+        amount:
+          type: number
+          description: Amount paid (XOF).
+        currency:
+          type: string
+          const: XOF
+          description: Currency code. Locked to XOF — consistent with Contract and
+            CustomerPayment.
+        method:
+          $ref: '#/components/schemas/PaymentMethod'
+          description: Payment method used (e.g. BANK_TRANSFER, MOBILE_MONEY, CHECK).
+        reference:
+          description: Optional payment reference — bank transaction number, check
+            number, Wave ref, etc.
+          type:
+          - string
+          - 'null'
+        paidAt:
+          $ref: '#/components/schemas/FirestoreTimestamp'
+          description: When the payment was made.
+        notes:
+          description: Optional internal notes.
+          type:
+          - string
+          - 'null'
+        createdBy:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → User/staff UID who recorded the payment.
+        createdAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Server-generated creation timestamp.
+        updatedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) Server-generated update timestamp.
+      required:
+      - companyId
+      - payeeId
+      - amount
+      - currency
+      - method
+      - paidAt
+      - createdBy
+      additionalProperties: false
+      description: 'OutboundPayment (GH#15). Collection: companies/{companyId}/outboundPayments/{paymentId}.
+        Single outbound transfer to a Payee. Canonical name chosen over SupplierPayment/VendorPayment
+        — direction-based, agnostic of payee type. Currency locked to XOF.'
+    OutboundPaymentCreate:
+      allOf:
+      - $ref: '#/components/schemas/OutboundPayment'
+      description: Write payload for creating a new OutboundPayment document. Fields
+        marked `readOnly` are server-set and must not be included. Fields marked `x-immutable`
+        may be set once at creation.
+      required:
+      - companyId
+      - payeeId
+      - amount
+      - currency
+      - method
+      - paidAt
+      - createdBy
+    OutboundPaymentUpdate:
+      allOf:
+      - $ref: '#/components/schemas/OutboundPayment'
+      description: Write payload for partial update (PATCH) of a OutboundPayment document.
+        All fields optional. Fields marked `readOnly` or `x-immutable` must not be
+        sent.
+    OutboundPaymentAllocation:
+      type: object
+      properties:
+        id:
+          readOnly: true
+          description: (Read-only) Firestore document ID, auto-generated.
+          type:
+          - string
+          - 'null'
+        outboundPaymentId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → OutboundPayment document ID (parent).
+        expenseId:
+          type: string
+          x-immutable: true
+          description: '(Immutable) FK → Expense document ID. Full Expense model tracked
+            in #20.'
+        companyId:
+          type: string
+          x-immutable: true
+          description: (Immutable) FK → Company document ID. Denormalized for collection-group
+            queries.
+        amount:
+          type: number
+          description: Amount of this payment allocated to the referenced expense
+            (XOF).
+        notes:
+          description: Optional notes about this allocation.
+          type:
+          - string
+          - 'null'
+        allocatedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) When this allocation was recorded.
+      required:
+      - outboundPaymentId
+      - expenseId
+      - companyId
+      - amount
+      additionalProperties: false
+      description: 'OutboundPaymentAllocation (GH#15). Subcollection: companies/{companyId}/outboundPayments/{paymentId}/allocations/{allocationId}.
+        Links an OutboundPayment to an Expense. Supports partial and multi-expense
+        allocations.'
+    OutboundPaymentAllocationCreate:
+      allOf:
+      - $ref: '#/components/schemas/OutboundPaymentAllocation'
+      description: Write payload for creating a new OutboundPaymentAllocation document.
+        Fields marked `readOnly` are server-set and must not be included. Fields marked
+        `x-immutable` may be set once at creation.
+      required:
+      - outboundPaymentId
+      - expenseId
+      - companyId
+      - amount
+    OutboundPaymentAllocationUpdate:
+      allOf:
+      - $ref: '#/components/schemas/OutboundPaymentAllocation'
+      description: Write payload for partial update (PATCH) of a OutboundPaymentAllocation
+        document. All fields optional. Fields marked `readOnly` or `x-immutable` must
+        not be sent.
+    PaymentWebhookEndpoint:
+      type: object
+      properties:
+        token:
+          type: string
+          x-immutable: true
+          description: (Immutable) base64url-encoded 24-byte random token. Also the
+            Firestore document ID and the URL path segment.
+        company:
+          type: string
+          x-immutable: true
+          description: (Immutable) Company slug (e.g. gerko_studios). Identifies the
+            tenant that owns this endpoint.
+        provider:
+          type: string
+          enum:
+          - wave
+          - jeko
+          x-immutable: true
+          description: (Immutable) Payment provider whose webhooks this endpoint accepts.
+        secret:
+          type: string
+          x-note: Provider-specific webhook signing secret. Used to verify HMAC-SHA256
+            signatures on inbound payloads. Never expose to clients.
+          readOnly: true
+          description: Webhook signing secret for HMAC verification. Backend-only
+            — never returned to dashboard or mobile clients.
+        active:
+          type: boolean
+          description: Whether this endpoint is currently active. Inactive endpoints
+            reject incoming webhooks.
+        createdAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) When this endpoint was provisioned.
+      required:
+      - token
+      - company
+      - provider
+      - secret
+      - active
+      additionalProperties: false
+      x-internal: true
+      description: 'PaymentWebhookEndpoint (GH#41). Collection: payment_webhook_endpoints/{token}.
+        Top-level, not tenant-scoped. Provisioned by superadmin; used by the backend
+        to verify inbound payment webhooks from Wave and Jeko. The delivery log collection
+        (raw webhook payloads + verification outcomes) is tracked in GH#41 — shape
+        TBD.'
+    PaymentWebhookEndpointCreate:
+      allOf:
+      - $ref: '#/components/schemas/PaymentWebhookEndpoint'
+      description: Write payload for creating a new PaymentWebhookEndpoint document.
+        Fields marked `readOnly` are server-set and must not be included. Fields marked
+        `x-immutable` may be set once at creation.
+      required:
+      - token
+      - company
+      - provider
+      - active
+    PaymentWebhookEndpointUpdate:
+      allOf:
+      - $ref: '#/components/schemas/PaymentWebhookEndpoint'
+      description: Write payload for partial update (PATCH) of a PaymentWebhookEndpoint
+        document. All fields optional. Fields marked `readOnly` or `x-immutable` must
+        not be sent.
     Sale:
       type: object
       properties:
@@ -3895,7 +4790,9 @@ components:
           - 'null'
         purchaseDate:
           $ref: '#/components/schemas/FirestoreTimestamp'
-          description: Firestore Timestamp serialized representation
+          description: 'Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds
+            }. See types/firestore.ts for REST API v1 and client SDK serialization
+            notes (#10).'
         createdAt:
           anyOf:
           - $ref: '#/components/schemas/FirestoreTimestamp'
@@ -4631,6 +5528,86 @@ components:
       description: Write payload for partial update (PATCH) of a Ticket document.
         All fields optional. Fields marked `readOnly` or `x-immutable` must not be
         sent.
+    User:
+      type: object
+      properties:
+        id:
+          readOnly: true
+          description: (Read-only) Firebase Auth UID. Matches the Firestore document
+            ID.
+          type:
+          - string
+          - 'null'
+        displayName:
+          description: User display name from Firebase Auth or manually set.
+          type:
+          - string
+          - 'null'
+        email:
+          description: Email address. Present for email/Google auth users.
+          type:
+          - string
+          - 'null'
+        phoneE164:
+          x-note: 'E.164 format with leading + (e.g. +2250777471485). Canonical phone
+            identity field (decision #27). Distinct from wa_id (Meta conversation
+            key). Server must normalize at write time: 8-digit CI local → prepend
+            +225.'
+          x-when: Set when the user authenticated via phone (WhatsApp OTP) or when
+            a staff member's phone is known. Required for WhatsApp OTP lookup — add
+            a Firestore composite index on phoneE164.
+          description: E.164-normalized phone number (e.g. +2250777471485). Canonical
+            phone identity field; used for WhatsApp OTP lookup via indexed query.
+          type:
+          - string
+          - 'null'
+        companyId:
+          x-immutable: true
+          description: (Immutable) FK → Company document ID. Present for staff accounts
+            scoped to a company.
+          type:
+          - string
+          - 'null'
+        role:
+          description: Staff role within the company (e.g. admin, manager, staff).
+            Application-defined.
+          type:
+          - string
+          - 'null'
+        isActive:
+          description: Whether this user account is active. Inactive accounts are
+            denied access.
+          type:
+          - boolean
+          - 'null'
+        createdAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) When the user document was created.
+        updatedAt:
+          anyOf:
+          - $ref: '#/components/schemas/FirestoreTimestamp'
+          - type: 'null'
+          readOnly: true
+          description: (Read-only) When the user document was last updated.
+      additionalProperties: false
+      description: 'User / staff account. Collection: users/{uid}. Document ID is
+        always the Firebase Auth UID (decision #27). phoneE164 is the canonical E.164
+        phone field for OTP lookup. Legacy phone-keyed documents must be migrated
+        to uid-keyed docs with phoneE164 set.'
+    UserCreate:
+      allOf:
+      - $ref: '#/components/schemas/User'
+      description: Write payload for creating a new User document. Fields marked `readOnly`
+        are server-set and must not be included. Fields marked `x-immutable` may be
+        set once at creation.
+    UserUpdate:
+      allOf:
+      - $ref: '#/components/schemas/User'
+      description: Write payload for partial update (PATCH) of a User document. All
+        fields optional. Fields marked `readOnly` or `x-immutable` must not be sent.
     WhatsappInboundMessage:
       type: object
       properties:
@@ -4647,6 +5624,12 @@ components:
             received the message.
         waba:
           $ref: '#/components/schemas/WabaLabel'
+          x-note: 'cmz = "IngenX - Chez Miss Zahoui", phone number ID 446424085225188,
+            used for chez_miss_zahoui_* companies. val = "IngenX - Valets", phone
+            number ID 425582173979125, used for all other companies. Templates are
+            approved at WABA level — if cmz and val share a WABA ID, all templates
+            are available to both. Routing logic: functions/src/orders/order.ts#isSender2Company.
+            See messaging/whatsapp-platform-constraints (#50).'
           description: (Immutable) Human-readable WABA label (cmz | val). See WabaLabel
             enum.
           x-immutable: true
@@ -4849,10 +5832,26 @@ components:
         to:
           type: string
           x-immutable: true
-          description: (Immutable) Recipient phone number in E.164 format. Must match
-            the inbound `from` for the same conversation.
+          x-note: 'This is the Meta wa_id (digits only, no leading +), NOT a literal
+            E.164 string. Meta normalizes phone numbers in non-obvious ways (e.g.
+            +2250777471485 → wa_id 22577471485, dropping the trunk zero). The only
+            reliable source is Meta''s contacts[].wa_id from the send response — do
+            not derive from E.164 by stripping + alone. The dashboard conversational
+            sends and the whatsapp-server OTP path both use the wa_id form. Confirmed
+            in prod: ING-368.'
+          x-when: Set at enqueue time to the recipient's Meta wa_id. Use inbound WhatsappInboundMessage.from
+            (also wa_id) as the join key for the conversation thread.
+          description: (Immutable) Recipient Meta wa_id — digits only, no leading
+            + (e.g. 22577471485). Equal to the inbound `from` for the same conversation.
+            NOT literal E.164; see x-note (#54).
         waba:
           $ref: '#/components/schemas/WabaLabel'
+          x-note: 'cmz = "IngenX - Chez Miss Zahoui", phone number ID 446424085225188,
+            used for chez_miss_zahoui_* companies. val = "IngenX - Valets", phone
+            number ID 425582173979125, used for all other companies. Templates are
+            approved at WABA level — if cmz and val share a WABA ID, all templates
+            are available to both. Routing logic: functions/src/orders/order.ts#isSender2Company.
+            See messaging/whatsapp-platform-constraints (#50).'
           description: (Immutable) WABA that will send the message. Mirrors inbound
             `waba`.
           x-immutable: true
@@ -4938,6 +5937,9 @@ components:
             after (sent → delivered → read, or failed).
         wamid:
           readOnly: true
+          x-note: Useful for audit and dedup. Does NOT enable reply-threading for
+            template messages — Meta silently ignores context.message_id on templates.
+            Threading only works for kind=text within the 24-hour service window (#50).
           description: (Read-only) WhatsApp message ID returned by Meta once the backend
             sends. Absent while queued or on failure.
           type:
@@ -5017,6 +6019,12 @@ components:
           - 'null'
         waba:
           $ref: '#/components/schemas/WabaLabel'
+          x-note: 'cmz = "IngenX - Chez Miss Zahoui", phone number ID 446424085225188,
+            used for chez_miss_zahoui_* companies. val = "IngenX - Valets", phone
+            number ID 425582173979125, used for all other companies. Templates are
+            approved at WABA level — if cmz and val share a WABA ID, all templates
+            are available to both. Routing logic: functions/src/orders/order.ts#isSender2Company.
+            See messaging/whatsapp-platform-constraints (#50).'
           description: (Read-only) WABA label this template is approved on. Templates
             are WABA-scoped. Mirrors WhatsappOutboundMessage.waba.
           readOnly: true