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

package/data/static/schemas.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "description": "@valets/schema \u2014 consolidated schema bundle",
-  "generated": "2026-05-27T15:51:06.117627+00:00",
+  "generated": "2026-05-30T13:38:45.949066+00:00",
   "schemas": {
     "allowed-user": {
       "type": "object",
@@ -19,10 +19,10 @@
           "x-immutable": true,
           "description": "(Immutable) FK \u2192 Company document ID."
         },
-        "siteId": {
+        "appId": {
           "type": "string",
           "x-immutable": true,
-          "description": "(Immutable) FK \u2192 Site document ID (D40 sub-tenant scope)."
+          "description": "(Immutable) FK \u2192 App document ID (D40 sub-tenant scope, renamed per D44)."
         },
         "contact": {
           "type": "string",
@@ -52,7 +52,7 @@
       },
       "required": [
         "companyId",
-        "siteId",
+        "appId",
         "contact",
         "tier",
         "amount",
@@ -61,11 +61,11 @@
         "paidAt"
       ],
       "additionalProperties": false,
-      "description": "AllowedUser model (D40 / ING-304). Collection: companies/{companyId}/sites/{siteId}/allowed_users/{contactId}. Authoritative paid-access allowlist. Upsert semantics \u2014 tier upgrades overwrite. Source of truth for access checks and referral code resolution.",
+      "description": "AllowedUser model (D40 / ING-304). Collection: companies/{companyId}/apps/{appId}/allowed_users/{contactId}. Authoritative paid-access allowlist. Upsert semantics \u2014 tier upgrades overwrite. Source of truth for access checks and referral code resolution.",
       "example": {
         "id": null,
         "companyId": "comp_xyz789",
-        "siteId": "sit_ref123",
+        "appId": "app_ref123",
         "contact": "contact",
         "tier": "Gold",
         "amount": 45000,
@@ -90,7 +90,7 @@
           "x-immutable": true,
           "description": "(Immutable) FK \u2192 Company document ID."
         },
-        "siteId": {
+        "appId": {
           "type": "string",
           "x-immutable": true,
           "description": "(Immutable) FK \u2192 Site document ID (D40)."
@@ -180,7 +180,7 @@
       },
       "required": [
         "companyId",
-        "siteId",
+        "appId",
         "status",
         "from",
         "to",
@@ -191,11 +191,11 @@
         "startedAt"
       ],
       "additionalProperties": false,
-      "description": "AnalyticsBackfill run (D42 / ING-304). Collection: companies/{companyId}/sites/{siteId}/analytics_backfills/{runId}. Tracks admin-triggered rollup backfill jobs; supports dry-run.",
+      "description": "AnalyticsBackfill run (D42 / ING-304). Collection: companies/{companyId}/apps/{appId}/analytics_backfills/{runId}. Tracks admin-triggered rollup backfill jobs; supports dry-run.",
       "example": {
         "id": null,
         "companyId": "comp_xyz789",
-        "siteId": "sit_ref123",
+        "appId": "app_ref123",
         "status": "pending",
         "from": "from",
         "to": "to",
@@ -297,7 +297,7 @@
           "x-immutable": true,
           "description": "(Immutable) FK \u2192 Company document ID."
         },
-        "siteId": {
+        "appId": {
           "type": "string",
           "x-immutable": true,
           "description": "(Immutable) FK \u2192 Site document ID (D40)."
@@ -335,12 +335,12 @@
         "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}. Idempotent set/merge \u2014 reruns overwrite. Fall back to raw analytics_events for uncovered slices.",
+      "description": "AnalyticsDaily rollup (D42 / ING-304). Collection: companies/{companyId}/apps/{appId}/analytics_daily/{YYYY-MM-DD}. Idempotent set/merge \u2014 reruns overwrite. Fall back to raw analytics_events for uncovered slices.",
       "example": {
         "totalEvents": 0,
         "pageViews": 0,
@@ -354,7 +354,7 @@
         "eventCounts": {},
         "id": null,
         "companyId": "comp_xyz789",
-        "siteId": "sit_ref123",
+        "appId": "app_ref123",
         "date": "2026-02-15",
         "computedAt": "computedAt",
         "sourceEventCount": null
@@ -376,10 +376,10 @@
           "x-immutable": true,
           "description": "(Immutable) FK \u2192 Company document ID."
         },
-        "siteId": {
+        "appId": {
           "type": "string",
           "x-immutable": true,
-          "description": "(Immutable) FK \u2192 Site document ID (D40 sub-tenant scope)."
+          "description": "(Immutable) FK \u2192 App document ID (D40 sub-tenant scope, renamed per D44)."
         },
         "eventId": {
           "type": "string",
@@ -536,7 +536,7 @@
       },
       "required": [
         "companyId",
-        "siteId",
+        "appId",
         "eventId",
         "eventName",
         "timestamp",
@@ -547,11 +547,11 @@
         "context"
       ],
       "additionalProperties": false,
-      "description": "AnalyticsEvent model (D40 / ING-304). Collection: companies/{companyId}/sites/{siteId}/analytics_events/{eventId}. Append-only, immutable product/behavior event stream. Event names are free strings; canonical vocabulary in CANONICAL_ANALYTICS_EVENT_NAMES.",
+      "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.",
       "example": {
         "id": null,
         "companyId": "comp_xyz789",
-        "siteId": "sit_ref123",
+        "appId": "app_ref123",
         "eventId": "eve_ref123",
         "eventName": "eventName",
         "timestamp": "timestamp",
@@ -645,7 +645,7 @@
           "x-immutable": true,
           "description": "(Immutable) FK \u2192 Company document ID."
         },
-        "siteId": {
+        "appId": {
           "type": "string",
           "x-immutable": true,
           "description": "(Immutable) FK \u2192 Site document ID (D40)."
@@ -690,13 +690,13 @@
         "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}. Scheduled-CF writer; idempotent set/merge.",
+      "description": "AnalyticsHourly rollup (D42 / ING-304). Collection: companies/{companyId}/apps/{appId}/analytics_hourly/{YYYY-MM-DD-HH}. Scheduled-CF writer; idempotent set/merge.",
       "example": {
         "totalEvents": 0,
         "pageViews": 0,
@@ -710,13 +710,342 @@
         "eventCounts": {},
         "id": null,
         "companyId": "comp_xyz789",
-        "siteId": "sit_ref123",
+        "appId": "app_ref123",
         "date": "2026-02-15",
         "hour": 0,
         "computedAt": "computedAt",
         "sourceEventCount": null
       }
     },
+    "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 \u2192 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": "#/definitions/app-status"
+            },
+            {
+              "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 \u2014 filter client-side instead, treating absent as ACTIVE.",
+          "description": "Lifecycle status (D41/D44). Optional pending backfill of pre-existing records (#26) \u2014 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": "#/definitions/deployment-link-type",
+                "description": "Link category \u2014 drives icon/handler selection.",
+                "x-note": "Lowercase by convention \u2014 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": "#/definitions/firestore-timestamp"
+            },
+            {
+              "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 \u2014 true when `expiresAt` is in the past. Maintained by server trigger.",
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "createdAt": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/firestore-timestamp"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "readOnly": true,
+          "description": "(Read-only) Server-generated creation timestamp."
+        },
+        "updatedAt": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/firestore-timestamp"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "readOnly": true,
+          "description": "(Read-only) Server-generated update timestamp."
+        },
+        "createdBy": {
+          "type": "string",
+          "x-immutable": true,
+          "description": "(Immutable) FK \u2192 User/staff UID who created the app."
+        },
+        "analyticsEnabled": {
+          "type": "boolean",
+          "description": "Feature flag \u2014 when false, clients should not emit analytics events for this app."
+        },
+        "lastAnalyticsSync": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/firestore-timestamp"
+            },
+            {
+              "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": "#/definitions/firestore-timestamp",
+              "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.",
+      "example": {
+        "id": null,
+        "companyId": "comp_xyz789",
+        "name": "Amadou Diallo",
+        "description": null,
+        "status": "status",
+        "deploymentLinks": [
+          {
+            "label": "label",
+            "url": "https://storage.example.com/url.jpg",
+            "type": "phone"
+          }
+        ],
+        "expiresAt": "expiresAt",
+        "isExpired": null,
+        "createdAt": "createdAt",
+        "updatedAt": "updatedAt",
+        "createdBy": "staff_k0f1",
+        "analyticsEnabled": true,
+        "lastAnalyticsSync": "lastAnalyticsSync",
+        "cachedMetrics": null
+      }
+    },
+    "app-payment": {
+      "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 \u2192 Company document ID."
+        },
+        "appId": {
+          "type": "string",
+          "x-immutable": true,
+          "description": "(Immutable) FK \u2192 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": "#/definitions/firestore-timestamp",
+          "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 \u2014 customer-level billing).",
+      "example": {
+        "id": null,
+        "companyId": "comp_xyz789",
+        "appId": "app_ref123",
+        "contact": "contact",
+        "sessionId": "ses_ref123",
+        "transactionId": "tra_ref123",
+        "tier": "Gold",
+        "amount": 45000,
+        "currency": "XOF",
+        "paidAt": "pai_ref123"
+      }
+    },
+    "app-status": {
+      "type": "string",
+      "enum": [
+        "ACTIVE",
+        "INACTIVE",
+        "EXPIRED",
+        "ARCHIVED"
+      ],
+      "description": "Lifecycle status for an App (formerly Site \u2014 renamed per decision #40 / D44). Drives whether the app is reachable and whether analytics/payments flow.",
+      "x-note": "ACTIVE = live and serving traffic. INACTIVE = intentionally disabled by operators. EXPIRED = past expiresAt (derived when isExpired is true; may also be stored explicitly). ARCHIVED = soft-deleted; retained for audit but not listed by default.",
+      "x-see": {
+        "decisions": [
+          "D41",
+          "D44"
+        ]
+      },
+      "x-when": "Written by operators via dashboard or by server triggers (expiration). Clients filter by ACTIVE."
+    },
     "attention-status": {
       "type": "string",
       "enum": [
@@ -826,7 +1155,7 @@
                     },
                     "_deletedAt": {
                       "$ref": "#/definitions/firestore-timestamp",
-                      "description": "Firestore Timestamp serialized representation"
+                      "description": "Firestore Timestamp \u2014 Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10)."
                     },
                     "_deletedBy": {
                       "description": "FK \u2192 User/staff UID who soft-deleted this item.",
@@ -834,7 +1163,7 @@
                     },
                     "_lastModifiedAt": {
                       "$ref": "#/definitions/firestore-timestamp",
-                      "description": "Firestore Timestamp serialized representation"
+                      "description": "Firestore Timestamp \u2014 Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10)."
                     },
                     "_lastModifiedBy": {
                       "description": "FK \u2192 User/staff UID who last modified this item.",
@@ -916,7 +1245,7 @@
                 },
                 "additionalProperties": {
                   "$ref": "#/definitions/firestore-timestamp",
-                  "description": "Firestore Timestamp serialized representation"
+                  "description": "Firestore Timestamp \u2014 Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10)."
                 }
               },
               "slotStatusUpdatedBy": {
@@ -934,7 +1263,7 @@
               },
               "_deletedAt": {
                 "$ref": "#/definitions/firestore-timestamp",
-                "description": "Firestore Timestamp serialized representation"
+                "description": "Firestore Timestamp \u2014 Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10)."
               },
               "_deletedBy": {
                 "description": "FK \u2192 User/staff UID who soft-deleted this item.",
@@ -942,7 +1271,7 @@
               },
               "_lastModifiedAt": {
                 "$ref": "#/definitions/firestore-timestamp",
-                "description": "Firestore Timestamp serialized representation"
+                "description": "Firestore Timestamp \u2014 Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10)."
               },
               "_lastModifiedBy": {
                 "description": "FK \u2192 User/staff UID who last modified this item.",
@@ -1151,7 +1480,7 @@
               },
               "_deletedAt": {
                 "$ref": "#/definitions/firestore-timestamp",
-                "description": "Firestore Timestamp serialized representation"
+                "description": "Firestore Timestamp \u2014 Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10)."
               },
               "_deletedBy": {
                 "description": "FK \u2192 User/staff UID who soft-deleted this item.",
@@ -1159,7 +1488,7 @@
               },
               "_lastModifiedAt": {
                 "$ref": "#/definitions/firestore-timestamp",
-                "description": "Firestore Timestamp serialized representation"
+                "description": "Firestore Timestamp \u2014 Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10)."
               },
               "_lastModifiedBy": {
                 "description": "FK \u2192 User/staff UID who last modified this item.",
@@ -1243,7 +1572,7 @@
               "type": "null"
             }
           ],
-          "description": "Firestore Timestamp serialized representation"
+          "description": "Firestore Timestamp \u2014 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.",
@@ -1272,7 +1601,7 @@
               "type": "null"
             }
           ],
-          "description": "Firestore Timestamp serialized representation"
+          "description": "Firestore Timestamp \u2014 Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10)."
         },
         "paymentProofAddedBy": {
           "description": "FK \u2192 User/staff UID who uploaded the payment proof.",
@@ -1297,7 +1626,7 @@
               "type": "null"
             }
           ],
-          "description": "Firestore Timestamp serialized representation"
+          "description": "Firestore Timestamp \u2014 Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10)."
         },
         "paymentProofRejectionReason": {
           "type": [
@@ -1334,7 +1663,7 @@
               "type": "null"
             }
           ],
-          "description": "Firestore Timestamp serialized representation"
+          "description": "Firestore Timestamp \u2014 Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10)."
         },
         "cancelledByRole": {
           "type": [
@@ -1544,58 +1873,244 @@
             "UNKNOWN"
           ]
         },
-        "fieldsChanged": {
-          "x-immutable": true,
-          "readOnly": true,
-          "x-note": "Dot-notation paths for nested fields (e.g. \"bookingDates.0.status\"). Populated by diff in Firebase trigger. Null for CREATE versions.",
-          "description": "(Immutable, Read-only) List of field paths that changed in this write. Populated by the Firebase trigger diff. Null for CREATE records.",
+        "fieldsChanged": {
+          "x-immutable": true,
+          "readOnly": true,
+          "x-note": "Dot-notation paths for nested fields (e.g. \"bookingDates.0.status\"). Populated by diff in Firebase trigger. Null for CREATE versions.",
+          "description": "(Immutable, Read-only) List of field paths that changed in this write. Populated by the Firebase trigger diff. Null for CREATE records.",
+          "type": [
+            "array",
+            "null"
+          ],
+          "items": {
+            "type": "string"
+          }
+        },
+        "snapshot": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {},
+          "x-immutable": true,
+          "readOnly": true,
+          "x-note": "Full Booking document at the time of write. Typed as a string-keyed record to avoid circular schema reference. Consumers cast to Booking at runtime.",
+          "x-see": {
+            "decisions": [
+              "D18"
+            ]
+          },
+          "description": "(Immutable, Read-only) Full snapshot of the Booking document immediately after the write. Untyped to avoid circular schema dependency \u2014 cast to Booking at runtime."
+        }
+      },
+      "required": [
+        "id",
+        "bookingId",
+        "companyId",
+        "changeType",
+        "changedAt",
+        "snapshot"
+      ],
+      "additionalProperties": false,
+      "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.",
+      "example": {
+        "id": "bk_abc123def456",
+        "bookingId": "boo_ref123",
+        "companyId": "comp_xyz789",
+        "changeType": "CREATE",
+        "changedAt": "changedAt",
+        "changedBy": null,
+        "changedByRole": "DASHBOARD",
+        "fieldsChanged": null,
+        "snapshot": {}
+      }
+    },
+    "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 \u2192 Company document ID."
+        },
+        "payeeId": {
+          "type": "string",
+          "x-immutable": true,
+          "description": "(Immutable) FK \u2192 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": "#/definitions/contract-status",
+          "description": "Contract lifecycle status (#14). Query by ACTIVE \u2014 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 \u2014 not stored.",
+                "type": "string"
+              },
+              "status": {
+                "$ref": "#/definitions/milestone-status",
+                "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": "#/definitions/firestore-timestamp",
+                "description": "When the invoice was issued for this milestone."
+              },
+              "paidAt": {
+                "$ref": "#/definitions/firestore-timestamp",
+                "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 \u2014 embedded sub-object on Contract (#17). Not a separate collection."
+          }
+        },
+        "notes": {
+          "description": "Optional internal notes.",
           "type": [
-            "array",
+            "string",
             "null"
-          ],
-          "items": {
-            "type": "string"
-          }
+          ]
         },
-        "snapshot": {
-          "type": "object",
-          "propertyNames": {
-            "type": "string"
-          },
-          "additionalProperties": {},
+        "createdBy": {
+          "type": "string",
           "x-immutable": true,
+          "description": "(Immutable) FK \u2192 User/staff UID who created the contract."
+        },
+        "createdAt": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/firestore-timestamp"
+            },
+            {
+              "type": "null"
+            }
+          ],
           "readOnly": true,
-          "x-note": "Full Booking document at the time of write. Typed as a string-keyed record to avoid circular schema reference. Consumers cast to Booking at runtime.",
-          "x-see": {
-            "decisions": [
-              "D18"
-            ]
-          },
-          "description": "(Immutable, Read-only) Full snapshot of the Booking document immediately after the write. Untyped to avoid circular schema dependency \u2014 cast to Booking at runtime."
+          "description": "(Read-only) Server-generated creation timestamp."
+        },
+        "updatedAt": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/firestore-timestamp"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "readOnly": true,
+          "description": "(Read-only) Server-generated update timestamp."
         }
       },
       "required": [
-        "id",
-        "bookingId",
         "companyId",
-        "changeType",
-        "changedAt",
-        "snapshot"
+        "payeeId",
+        "title",
+        "status",
+        "currency",
+        "totalAmount",
+        "startDate",
+        "createdBy"
       ],
       "additionalProperties": false,
-      "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.",
+      "description": "Contract model (GH#14/#17/#18). Collection: companies/{companyId}/contracts/{contractId}. Service/supplier contract between a company and a Payee. No isActive field \u2014 query by status. Currency locked to XOF. Milestones use MilestoneStatus enum (no stored OVERDUE).",
       "example": {
-        "id": "bk_abc123def456",
-        "bookingId": "boo_ref123",
+        "id": null,
         "companyId": "comp_xyz789",
-        "changeType": "CREATE",
-        "changedAt": "changedAt",
-        "changedBy": null,
-        "changedByRole": "DASHBOARD",
-        "fieldsChanged": null,
-        "snapshot": {}
+        "payeeId": "pay_ref123",
+        "title": "title",
+        "description": null,
+        "status": "status",
+        "currency": "XOF",
+        "totalAmount": 45000,
+        "startDate": "2026-02-15",
+        "endDate": null,
+        "milestones": null,
+        "notes": null,
+        "createdBy": "staff_k0f1",
+        "createdAt": "createdAt",
+        "updatedAt": "updatedAt"
       }
     },
+    "contract-status": {
+      "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."
+    },
     "customer": {
       "type": "object",
       "properties": {
@@ -1656,7 +2171,7 @@
             "properties": {
               "timestamp": {
                 "$ref": "#/definitions/firestore-timestamp",
-                "description": "Firestore Timestamp serialized representation"
+                "description": "Firestore Timestamp \u2014 Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10)."
               },
               "type": {
                 "type": "string",
@@ -1815,7 +2330,7 @@
         },
         "paymentDate": {
           "$ref": "#/definitions/firestore-timestamp",
-          "description": "Firestore Timestamp serialized representation"
+          "description": "Firestore Timestamp \u2014 Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10)."
         },
         "paymentMethod": {
           "$ref": "#/definitions/payment-method",
@@ -1983,7 +2498,7 @@
               "type": "null"
             }
           ],
-          "description": "Firestore Timestamp serialized representation"
+          "description": "Firestore Timestamp \u2014 Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10)."
         },
         "createdBy": {
           "type": "string",
@@ -2112,7 +2627,7 @@
         },
         "startDate": {
           "$ref": "#/definitions/firestore-timestamp",
-          "description": "Firestore Timestamp serialized representation"
+          "description": "Firestore Timestamp \u2014 Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10)."
         },
         "endDate": {
           "anyOf": [
@@ -2123,7 +2638,7 @@
               "type": "null"
             }
           ],
-          "description": "Firestore Timestamp serialized representation"
+          "description": "Firestore Timestamp \u2014 Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10)."
         },
         "status": {
           "$ref": "#/definitions/event-status",
@@ -2727,10 +3242,10 @@
           "x-immutable": true,
           "description": "(Immutable) FK \u2192 Company document ID."
         },
-        "siteId": {
+        "appId": {
           "type": "string",
           "x-immutable": true,
-          "description": "(Immutable) FK \u2192 Site document ID (D40 sub-tenant scope)."
+          "description": "(Immutable) FK \u2192 App document ID (D40 sub-tenant scope, renamed per D44)."
         },
         "email": {
           "type": "string",
@@ -2796,7 +3311,7 @@
       },
       "required": [
         "companyId",
-        "siteId",
+        "appId",
         "email",
         "phone",
         "ip",
@@ -2808,11 +3323,11 @@
         "requestedAt"
       ],
       "additionalProperties": false,
-      "description": "MagicLinkRequest model (D40 / ING-304). Collection: companies/{companyId}/sites/{siteId}/magic_link_requests/{requestId}. Authentication audit log \u2014 every request is logged regardless of outcome. Two-stage write: Log() then LogVerify().",
+      "description": "MagicLinkRequest model (D40 / ING-304). Collection: companies/{companyId}/apps/{appId}/magic_link_requests/{requestId}. Authentication audit log \u2014 every request is logged regardless of outcome. Two-stage write: Log() then LogVerify().",
       "example": {
         "id": null,
         "companyId": "comp_xyz789",
-        "siteId": "sit_ref123",
+        "appId": "app_ref123",
         "email": "amadou@example.com",
         "phone": "+225 07 00 11 22",
         "ip": "ip",
@@ -2971,6 +3486,65 @@
           "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 \u2192 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,
@@ -3035,6 +3609,11 @@
         "lowStockItemsCount": 2,
         "activeRecurringPaymentsCount": 2,
         "monthlyRecurringRevenue": 0,
+        "escalatedOrdersCount": null,
+        "staleOrdersCount": null,
+        "staleBookingsCount": null,
+        "onHoldOrdersCount": null,
+        "paymentsByMethod": null,
         "computedForDay": "computedForDay",
         "generatedAt": "generatedAt"
       }
@@ -3183,6 +3762,65 @@
           "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 \u2192 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,
@@ -3253,6 +3891,11 @@
         "lowStockItemsCount": 2,
         "activeRecurringPaymentsCount": 2,
         "monthlyRecurringRevenue": 0,
+        "escalatedOrdersCount": null,
+        "staleOrdersCount": null,
+        "staleBookingsCount": null,
+        "onHoldOrdersCount": null,
+        "paymentsByMethod": null,
         "computedForDay": "computedForDay",
         "generatedAt": "generatedAt",
         "date": "2026-02-15"
@@ -3402,6 +4045,65 @@
           "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 \u2192 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,
@@ -3472,11 +4174,26 @@
         "lowStockItemsCount": 2,
         "activeRecurringPaymentsCount": 2,
         "monthlyRecurringRevenue": 0,
+        "escalatedOrdersCount": null,
+        "staleOrdersCount": null,
+        "staleBookingsCount": null,
+        "onHoldOrdersCount": null,
+        "paymentsByMethod": null,
         "computedForDay": "computedForDay",
         "generatedAt": "generatedAt",
         "month": "month"
       }
     },
+    "milestone-status": {
+      "type": "string",
+      "enum": [
+        "PENDING",
+        "INVOICED",
+        "PAID"
+      ],
+      "x-note": "OVERDUE is intentionally excluded \u2014 due-date derivation should be computed at read time from dueDate, not stored. Stored OVERDUE would require a cron to keep it consistent. Existing lowercase values (pending, invoiced, paid) from pre-schema documents need normalization on read or via migration (#17).",
+      "description": "Status of a ContractMilestone (#17). PENDING = created, not yet invoiced. INVOICED = invoice issued, awaiting payment. PAID = payment received."
+    },
     "notification-channel": {
       "type": "string",
       "enum": [
@@ -3702,7 +4419,7 @@
         "createdAt"
       ],
       "additionalProperties": false,
-      "description": "NotificationRecord \u2014 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).",
+      "description": "NotificationRecord \u2014 backend-written, multi-channel notification 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 \u2192 notification_records per decision #55 (2026-05-30).",
       "example": {
         "id": null,
         "type": "phone",
@@ -3752,16 +4469,17 @@
           "x-immutable": true,
           "description": "(Immutable) FK \u2192 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 \u2014 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 \u2014 existing orders keep null. Flat path; Order continues to live at `companies/{companyId}/orders/{orderId}`.",
           "x-see": {
             "decisions": [
-              "D43"
+              "D43",
+              "D44"
             ]
           },
-          "x-when": "Set at order creation when the client knows which site 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 \u2192 Site document ID (D43 / ADR-003). null = company-wide.",
+          "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, appId, createdAt).",
+          "description": "(Immutable, Optional) FK \u2192 App document ID (D43 / ADR-003, renamed from siteId per D44). null = company-wide.",
           "type": [
             "string",
             "null"
@@ -3772,6 +4490,15 @@
           "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": "#/definitions/order-status",
           "description": "Core lifecycle status (D34, MIG-11). See OrderStatus enum for the legacy value migration mapping.",
@@ -4039,7 +4766,7 @@
         },
         "orderDate": {
           "$ref": "#/definitions/firestore-timestamp",
-          "description": "Firestore Timestamp serialized representation"
+          "description": "Firestore Timestamp \u2014 Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10)."
         },
         "PROCESSING_ON": {
           "anyOf": [
@@ -4113,7 +4840,7 @@
               "type": "null"
             }
           ],
-          "description": "Firestore Timestamp serialized representation"
+          "description": "Firestore Timestamp \u2014 Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10)."
         },
         "shippingCost": {
           "type": [
@@ -4243,7 +4970,7 @@
               },
               "paymentDate": {
                 "$ref": "#/definitions/firestore-timestamp",
-                "description": "Firestore Timestamp serialized representation"
+                "description": "Firestore Timestamp \u2014 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.).",
@@ -4356,8 +5083,9 @@
         "id": "bk_abc123def456",
         "uid": "user_u8x92kqm",
         "companyId": "comp_xyz789",
-        "siteId": null,
+        "appId": null,
         "orderNumber": "ORD-2026-0042",
+        "followUpUrl": null,
         "status": "status",
         "paymentStatus": "paymentStatus",
         "fulfillmentStatus": "fulfillmentStatus",
@@ -4667,18 +5395,203 @@
         "adhoc",
         "conversational"
       ],
-      "description": "Business purpose of an outbound WhatsApp message \u2014 orthogonal to its format (see OutboundMessageFormat). `otp`/`review_request`/`adhoc` are system-originated; `conversational` is a human agent reply from the dashboard inbox. Optional signal carried for analytics/triggers (GH#43; supersedes the GH#38 OutboundMessageKind)."
+      "description": "Business purpose of an outbound WhatsApp message \u2014 orthogonal to its format (see OutboundMessageFormat). `otp`/`review_request`/`adhoc` are system-originated; `conversational` is a human agent reply from the dashboard inbox. Optional signal carried for analytics/triggers (GH#43; supersedes the GH#38 OutboundMessageKind)."
+    },
+    "outbound-message-status": {
+      "type": "string",
+      "enum": [
+        "queued",
+        "sent",
+        "delivered",
+        "read",
+        "failed"
+      ],
+      "description": "Outbound WhatsApp message delivery status. Lifecycle: queued \u2192 sent \u2192 delivered \u2192 read, or queued \u2192 failed. The dashboard creates the message with status `queued`; the whatsapp-server backend owns every transition after, updating in place from Meta delivery callbacks (GH#43)."
+    },
+    "outbound-payment": {
+      "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 \u2192 Company document ID."
+        },
+        "payeeId": {
+          "type": "string",
+          "x-immutable": true,
+          "description": "(Immutable) FK \u2192 Payee document ID. Full Payee model tracked in #20."
+        },
+        "contractId": {
+          "x-immutable": true,
+          "description": "(Immutable, Optional) FK \u2192 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 \u2014 consistent with Contract and CustomerPayment."
+        },
+        "method": {
+          "$ref": "#/definitions/payment-method",
+          "description": "Payment method used (e.g. BANK_TRANSFER, MOBILE_MONEY, CHECK)."
+        },
+        "reference": {
+          "description": "Optional payment reference \u2014 bank transaction number, check number, Wave ref, etc.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "paidAt": {
+          "$ref": "#/definitions/firestore-timestamp",
+          "description": "When the payment was made."
+        },
+        "notes": {
+          "description": "Optional internal notes.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "createdBy": {
+          "type": "string",
+          "x-immutable": true,
+          "description": "(Immutable) FK \u2192 User/staff UID who recorded the payment."
+        },
+        "createdAt": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/firestore-timestamp"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "readOnly": true,
+          "description": "(Read-only) Server-generated creation timestamp."
+        },
+        "updatedAt": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/firestore-timestamp"
+            },
+            {
+              "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 \u2014 direction-based, agnostic of payee type. Currency locked to XOF.",
+      "example": {
+        "id": null,
+        "companyId": "comp_xyz789",
+        "payeeId": "pay_ref123",
+        "contractId": null,
+        "amount": 45000,
+        "currency": "XOF",
+        "method": "method",
+        "reference": null,
+        "paidAt": "pai_ref123",
+        "notes": null,
+        "createdBy": "staff_k0f1",
+        "createdAt": "createdAt",
+        "updatedAt": "updatedAt"
+      }
     },
-    "outbound-message-status": {
-      "type": "string",
-      "enum": [
-        "queued",
-        "sent",
-        "delivered",
-        "read",
-        "failed"
+    "outbound-payment-allocation": {
+      "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 \u2192 OutboundPayment document ID (parent)."
+        },
+        "expenseId": {
+          "type": "string",
+          "x-immutable": true,
+          "description": "(Immutable) FK \u2192 Expense document ID. Full Expense model tracked in #20."
+        },
+        "companyId": {
+          "type": "string",
+          "x-immutable": true,
+          "description": "(Immutable) FK \u2192 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": "#/definitions/firestore-timestamp"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "readOnly": true,
+          "description": "(Read-only) When this allocation was recorded."
+        }
+      },
+      "required": [
+        "outboundPaymentId",
+        "expenseId",
+        "companyId",
+        "amount"
       ],
-      "description": "Outbound WhatsApp message delivery status. Lifecycle: queued \u2192 sent \u2192 delivered \u2192 read, or queued \u2192 failed. The dashboard creates the message with status `queued`; the whatsapp-server backend owns every transition after, updating in place from Meta delivery callbacks (GH#43)."
+      "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.",
+      "example": {
+        "id": null,
+        "outboundPaymentId": "out_ref123",
+        "expenseId": "exp_ref123",
+        "companyId": "comp_xyz789",
+        "amount": 45000,
+        "notes": null,
+        "allocatedAt": "allocatedAt"
+      }
     },
     "payment-method": {
       "type": "string",
@@ -4718,6 +5631,70 @@
       ],
       "description": "Payment lifecycle status (D01 amended). Used by Order, Sale/Purchase, Booking."
     },
+    "payment-webhook-endpoint": {
+      "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 \u2014 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": "#/definitions/firestore-timestamp"
+            },
+            {
+              "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 \u2014 shape TBD.",
+      "example": {
+        "token": "token",
+        "company": "company",
+        "provider": "wave",
+        "secret": "secret",
+        "active": true,
+        "createdAt": "createdAt"
+      }
+    },
     "pending-issue": {
       "type": "string",
       "enum": [
@@ -4834,7 +5811,7 @@
         },
         "purchaseDate": {
           "$ref": "#/definitions/firestore-timestamp",
-          "description": "Firestore Timestamp serialized representation"
+          "description": "Firestore Timestamp \u2014 Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10)."
         },
         "createdAt": {
           "anyOf": [
@@ -5814,13 +6791,109 @@
       ],
       "description": "Event ticket status (D32). VALID = active and unused."
     },
+    "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 \u2192 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 \u2014 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 \u2192 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": "#/definitions/firestore-timestamp"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "readOnly": true,
+          "description": "(Read-only) When the user document was created."
+        },
+        "updatedAt": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/firestore-timestamp"
+            },
+            {
+              "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.",
+      "example": {
+        "id": null,
+        "displayName": null,
+        "email": null,
+        "phoneE164": null,
+        "companyId": null,
+        "role": null,
+        "isActive": null,
+        "createdAt": "createdAt",
+        "updatedAt": "updatedAt"
+      }
+    },
     "waba-label": {
       "type": "string",
       "enum": [
         "cmz",
         "val"
       ],
-      "description": "Human-readable WABA label identifying which Meta business number received the message (GH#36)."
+      "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 \u2014 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": "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)."
     },
     "whatsapp-button-sub-type": {
       "type": "string",
@@ -5848,6 +6921,7 @@
         },
         "waba": {
           "$ref": "#/definitions/waba-label",
+          "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 \u2014 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
         },
@@ -6105,10 +7179,13 @@
         "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 \u2192 wa_id 22577471485, dropping the trunk zero). The only reliable source is Meta's contacts[].wa_id from the send response \u2014 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 \u2014 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": "#/definitions/waba-label",
+          "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 \u2014 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
         },
@@ -6215,6 +7292,7 @@
         },
         "wamid": {
           "readOnly": true,
+          "x-note": "Useful for audit and dedup. Does NOT enable reply-threading for template messages \u2014 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": [
             "string",
@@ -6325,6 +7403,7 @@
         },
         "waba": {
           "$ref": "#/definitions/waba-label",
+          "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 \u2014 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
         },