@ingenx-io/valets-schema-mcp-server 0.2.5 → 0.2.7

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-30T12:42:51.842715+00:00",
+  "generated": "2026-05-30T13:57:29.446011+00:00",
   "schemas": {
     "allowed-user": {
       "type": "object",
@@ -745,16 +745,23 @@
           ]
         },
         "status": {
-          "$ref": "#/definitions/app-status",
-          "description": "Lifecycle status (D41/D44). Clients filter by ACTIVE.",
-          "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.",
+          "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"
             ]
-          },
-          "x-when": "Written by operators via dashboard or by server triggers (expiration). Clients filter by ACTIVE."
+          }
         },
         "deploymentLinks": {
           "type": "array",
@@ -915,7 +922,6 @@
       "required": [
         "companyId",
         "name",
-        "status",
         "deploymentLinks",
         "createdBy",
         "analyticsEnabled"
@@ -1919,6 +1925,192 @@
         "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": [
+            "string",
+            "null"
+          ]
+        },
+        "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,
+          "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",
+        "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 \u2014 query by status. Currency locked to XOF. Milestones use MilestoneStatus enum (no stored OVERDUE).",
+      "example": {
+        "id": null,
+        "companyId": "comp_xyz789",
+        "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": {
@@ -2142,7 +2334,7 @@
         },
         "paymentMethod": {
           "$ref": "#/definitions/payment-method",
-          "description": "Unified payment method set with African + global methods (D02)."
+          "description": "Unified payment method set with African + global methods (D02). Note: the metrics writer historically emits \"OM\" instead of \"ORANGE_MONEY\" as a paymentsByMethod map key \u2014 treat OM as deprecated; canonical value is ORANGE_MONEY (#21)."
         },
         "referenceNumber": {
           "type": "string",
@@ -2540,95 +2732,116 @@
       ],
       "description": "Ticketed event lifecycle (D32). Mobile-only today; Dashboard in Wave 4."
     },
-    "fulfillment-status": {
-      "type": "string",
-      "enum": [
-        "PREPARING",
-        "PARTIALLY_SHIPPED",
-        "SHIPPED",
-        "IN_TRANSIT",
-        "DELIVERED",
-        "PICKED_UP"
-      ],
-      "description": "Delivery/fulfillment lifecycle (D34). Optional \u2014 null for in-person orders."
-    },
-    "loyalty-config": {
+    "expense": {
       "type": "object",
       "properties": {
         "id": {
           "readOnly": true,
-          "description": "(Read-only) Firestore document ID. Singleton doc \u2014 typically \"config\".",
+          "description": "(Read-only) Firestore document ID, auto-generated.",
           "type": [
             "string",
             "null"
           ]
         },
-        "isEnabled": {
-          "type": "boolean"
+        "companyId": {
+          "type": "string",
+          "x-immutable": true,
+          "description": "(Immutable) FK \u2192 Company document ID."
         },
-        "pointSystem": {
+        "title": {
           "type": "string",
-          "enum": [
-            "SPENDING",
-            "PRODUCT",
-            "VISIT"
-          ],
-          "description": "How points are earned: SPENDING (per currency spent), PRODUCT (per product purchased), or VISIT (per visit). SCREAMING_SNAKE per D04."
+          "description": "Human-readable expense title (e.g. \"Loyer mars 2026\", \"Facture EAU\")."
         },
-        "pointsPerCurrency": {
-          "description": "[Deprecated alias: pointsPerCurrencyUnit \u2014 renamed by MIG-06]",
-          "deprecated": true,
+        "description": {
+          "description": "Optional longer description or notes.",
           "type": [
-            "number",
+            "string",
             "null"
           ]
         },
-        "pointsPerVisit": {
-          "description": "Points earned per visit (when pointSystem is visit).",
+        "amount": {
+          "type": "number",
+          "description": "Total expense amount (XOF)."
+        },
+        "currency": {
+          "type": "string",
+          "const": "XOF",
+          "description": "Currency code. Locked to XOF."
+        },
+        "dueDate": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/firestore-timestamp"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "When the expense is due. Used to compute OVERDUE state at read time (not stored in paymentStatus)."
+        },
+        "paymentStatus": {
+          "$ref": "#/definitions/expense-payment-status",
+          "x-note": "OVERDUE is intentionally excluded \u2014 it is never stored in Firestore. Compute it at read time: expense.paymentStatus !== PAID && expense.dueDate < now() (#13). Helper: isExpenseOverdue(expense: Expense): boolean.",
+          "description": "Current payment status. OVERDUE is never stored \u2014 derive from dueDate at read time (#13)."
+        },
+        "amountDue": {
+          "x-note": "Authoritative for simple (non-allocation) expenses. Legacy field maintained for backward compatibility when no OutboundPaymentAllocation records exist (#12).",
+          "description": "Amount still owed. Authoritative when no OutboundPaymentAllocation records exist for this expense.",
           "type": [
             "number",
             "null"
           ]
         },
-        "pointValue": {
-          "description": "Monetary value of one point for redemption.",
+        "amountPaid": {
+          "description": "Amount paid to date (simple tracking, no allocations).",
           "type": [
             "number",
             "null"
           ]
         },
-        "minimumRedeemPoints": {
-          "description": "Minimum points balance required before redemption is allowed.",
+        "allocatedAmount": {
+          "readOnly": true,
+          "x-note": "Server-set \u2014 computed from OutboundPaymentAllocation records. Clients must never write this field (#12).",
+          "description": "(Read-only) Total amount allocated via OutboundPaymentAllocation records. Authoritative when allocations exist.",
           "type": [
-            "integer",
+            "number",
             "null"
-          ],
-          "minimum": -9007199254740991,
-          "maximum": 9007199254740991
+          ]
         },
-        "welcomeBonusPoints": {
-          "description": "One-time points bonus for new loyalty enrollees.",
+        "balance": {
+          "readOnly": true,
+          "x-note": "Server-set \u2014 computed as amount - allocatedAmount. Authoritative remaining amount when allocations exist. Prefer this over amountDue when OutboundPaymentAllocation records are present (#12).",
+          "description": "(Read-only) Remaining balance: amount minus allocatedAmount. Authoritative when OutboundPaymentAllocation records exist.",
           "type": [
-            "integer",
+            "number",
             "null"
-          ],
-          "minimum": -9007199254740991,
-          "maximum": 9007199254740991
+          ]
         },
-        "pointsExpirationDays": {
-          "description": "[Deprecated alias: pointsExpiryMonths \u2014 renamed and converted months*30 to days by MIG-06]",
-          "deprecated": true,
+        "paidDate": {
           "anyOf": [
             {
-              "type": "integer",
-              "minimum": -9007199254740991,
-              "maximum": 9007199254740991
+              "$ref": "#/definitions/firestore-timestamp"
             },
             {
               "type": "null"
             }
+          ],
+          "x-when": "Set when paymentStatus transitions to PAID (fully settled). Null for partially paid or unpaid expenses. For multi-payment history, read OutboundPaymentAllocation records (#19).",
+          "description": "When the expense was fully settled (paymentStatus = PAID). Null otherwise."
+        },
+        "paymentReference": {
+          "x-note": "Reference for the most recent payment transaction (check number, wire ID, Wave ref, etc.). Overwritten on each payment. For full payment history read OutboundPaymentAllocation records (#19).",
+          "description": "Most recent payment transaction reference. Overwritten on each payment; not a full history.",
+          "type": [
+            "string",
+            "null"
           ]
         },
+        "createdBy": {
+          "type": "string",
+          "x-immutable": true,
+          "description": "(Immutable) FK \u2192 User/staff UID who created this expense record."
+        },
         "createdAt": {
           "anyOf": [
             {
@@ -2651,18 +2864,173 @@
             }
           ],
           "readOnly": true,
-          "description": "(Read-only) Server-generated update timestamp."
+          "description": "(Read-only) Server-generated last-update timestamp."
         }
       },
       "required": [
-        "isEnabled",
-        "pointSystem"
+        "companyId",
+        "title",
+        "amount",
+        "currency",
+        "paymentStatus",
+        "createdBy"
       ],
       "additionalProperties": false,
-      "description": "LoyaltyConfig model (D21). Collection: companies/{companyId}/loyaltySettings/config. 1 doc per company. Uses canonical field names per D21 (MIG-06 renames legacy aliases).",
+      "description": "Expense (GH#12/#13/#19 partial). Collection: companies/{companyId}/expenses/{expenseId}. Dual balance tracking: amountPaid/amountDue for simple expenses; allocatedAmount/balance (server-set) for allocation-settled expenses. OVERDUE excluded from stored enum \u2014 derive at read time. Full domain (Payee FK, Contract FK) in #20.",
       "example": {
         "id": null,
-        "isEnabled": true,
+        "companyId": "comp_xyz789",
+        "title": "title",
+        "description": null,
+        "amount": 45000,
+        "currency": "XOF",
+        "dueDate": "dueDate",
+        "paymentStatus": "paymentStatus",
+        "amountDue": null,
+        "amountPaid": null,
+        "allocatedAmount": null,
+        "balance": null,
+        "paidDate": "pai_ref123",
+        "paymentReference": null,
+        "createdBy": "staff_k0f1",
+        "createdAt": "createdAt",
+        "updatedAt": "updatedAt"
+      }
+    },
+    "expense-payment-status": {
+      "type": "string",
+      "enum": [
+        "PENDING",
+        "PARTIALLY_PAID",
+        "PAID",
+        "FAILED"
+      ],
+      "x-note": "OVERDUE is intentionally excluded \u2014 it is never stored in Firestore. Compute it at read time: expense.paymentStatus !== PAID && expense.dueDate < now() (#13). Helper: isExpenseOverdue(expense: Expense): boolean.",
+      "description": "Payment status of an Expense. Stored enum \u2014 OVERDUE is not stored, it is derived at read time from dueDate (#13)."
+    },
+    "fulfillment-status": {
+      "type": "string",
+      "enum": [
+        "PREPARING",
+        "PARTIALLY_SHIPPED",
+        "SHIPPED",
+        "IN_TRANSIT",
+        "DELIVERED",
+        "PICKED_UP"
+      ],
+      "description": "Delivery/fulfillment lifecycle (D34). Optional \u2014 null for in-person orders."
+    },
+    "loyalty-config": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "readOnly": true,
+          "description": "(Read-only) Firestore document ID. Singleton doc \u2014 typically \"config\".",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "isEnabled": {
+          "type": "boolean"
+        },
+        "pointSystem": {
+          "type": "string",
+          "enum": [
+            "SPENDING",
+            "PRODUCT",
+            "VISIT"
+          ],
+          "description": "How points are earned: SPENDING (per currency spent), PRODUCT (per product purchased), or VISIT (per visit). SCREAMING_SNAKE per D04."
+        },
+        "pointsPerCurrency": {
+          "description": "[Deprecated alias: pointsPerCurrencyUnit \u2014 renamed by MIG-06]",
+          "deprecated": true,
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "pointsPerVisit": {
+          "description": "Points earned per visit (when pointSystem is visit).",
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "pointValue": {
+          "description": "Monetary value of one point for redemption.",
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "minimumRedeemPoints": {
+          "description": "Minimum points balance required before redemption is allowed.",
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991
+        },
+        "welcomeBonusPoints": {
+          "description": "One-time points bonus for new loyalty enrollees.",
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991
+        },
+        "pointsExpirationDays": {
+          "description": "[Deprecated alias: pointsExpiryMonths \u2014 renamed and converted months*30 to days by MIG-06]",
+          "deprecated": true,
+          "anyOf": [
+            {
+              "type": "integer",
+              "minimum": -9007199254740991,
+              "maximum": 9007199254740991
+            },
+            {
+              "type": "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."
+        }
+      },
+      "required": [
+        "isEnabled",
+        "pointSystem"
+      ],
+      "additionalProperties": false,
+      "description": "LoyaltyConfig model (D21). Collection: companies/{companyId}/loyaltySettings/config. 1 doc per company. Uses canonical field names per D21 (MIG-06 renames legacy aliases).",
+      "example": {
+        "id": null,
+        "isEnabled": true,
         "pointSystem": "SPENDING",
         "pointsPerCurrency": null,
         "pointsPerVisit": null,
@@ -3170,6 +3538,7 @@
         "orderCompletionRate30d": {
           "type": "number",
           "readOnly": true,
+          "x-note": "Firestore REST API v1 writes integerValue when the stored value is whole (e.g. 0), doubleValue when fractional (e.g. 82.17). Admin SDK smooths this to a JS number; REST clients must coerce the union (#11).",
           "description": "(Read-only) Percentage of orders completed or delivered in the last 30 days. Always full recalc."
         },
         "todayPurchasesCount": {
@@ -3187,11 +3556,13 @@
         "averagePurchaseAmount": {
           "type": "number",
           "readOnly": true,
+          "x-note": "Firestore REST API v1 writes integerValue when whole (e.g. 10070), doubleValue when fractional (e.g. 10006.5). Admin SDK smooths this; REST clients must coerce (#11).",
           "description": "(Read-only) Average purchase value across last 200 purchases (rolling, not time-windowed)."
         },
         "monthlyRevenue": {
           "type": "number",
           "readOnly": true,
+          "x-note": "Observed as integerValue on all sampled tenants (whole XOF amounts). Will be doubleValue if fractional. REST clients must coerce (#11).",
           "description": "(Read-only) Total purchase value in the current calendar month (UTC)."
         },
         "monthlyPurchasesCount": {
@@ -3228,6 +3599,7 @@
         "todayCollectedAmount": {
           "type": "number",
           "readOnly": true,
+          "x-note": "Observed as integerValue \"0\" on all sampled tenants. Will be doubleValue if fractional payments occur. REST clients must coerce (#11).",
           "description": "(Read-only) Sum of totalAmount for bookings where PAYMENT_PAID_AT is today. Resets at midnight."
         },
         "todayRevenue": {
@@ -3273,6 +3645,7 @@
         "averageRating": {
           "type": "number",
           "readOnly": true,
+          "x-note": "Observed as integerValue \"0\" on all tenants (no reviews yet). Will be doubleValue once real ratings exist. REST clients must coerce (#11).",
           "description": "(Read-only) Average rating from the last 200 reviews (rolling). Always full recalc."
         },
         "lowStockItemsCount": {
@@ -3446,6 +3819,7 @@
         "orderCompletionRate30d": {
           "type": "number",
           "readOnly": true,
+          "x-note": "Firestore REST API v1 writes integerValue when the stored value is whole (e.g. 0), doubleValue when fractional (e.g. 82.17). Admin SDK smooths this to a JS number; REST clients must coerce the union (#11).",
           "description": "(Read-only) Percentage of orders completed or delivered in the last 30 days. Always full recalc."
         },
         "todayPurchasesCount": {
@@ -3463,11 +3837,13 @@
         "averagePurchaseAmount": {
           "type": "number",
           "readOnly": true,
+          "x-note": "Firestore REST API v1 writes integerValue when whole (e.g. 10070), doubleValue when fractional (e.g. 10006.5). Admin SDK smooths this; REST clients must coerce (#11).",
           "description": "(Read-only) Average purchase value across last 200 purchases (rolling, not time-windowed)."
         },
         "monthlyRevenue": {
           "type": "number",
           "readOnly": true,
+          "x-note": "Observed as integerValue on all sampled tenants (whole XOF amounts). Will be doubleValue if fractional. REST clients must coerce (#11).",
           "description": "(Read-only) Total purchase value in the current calendar month (UTC)."
         },
         "monthlyPurchasesCount": {
@@ -3504,6 +3880,7 @@
         "todayCollectedAmount": {
           "type": "number",
           "readOnly": true,
+          "x-note": "Observed as integerValue \"0\" on all sampled tenants. Will be doubleValue if fractional payments occur. REST clients must coerce (#11).",
           "description": "(Read-only) Sum of totalAmount for bookings where PAYMENT_PAID_AT is today. Resets at midnight."
         },
         "todayRevenue": {
@@ -3549,6 +3926,7 @@
         "averageRating": {
           "type": "number",
           "readOnly": true,
+          "x-note": "Observed as integerValue \"0\" on all tenants (no reviews yet). Will be doubleValue once real ratings exist. REST clients must coerce (#11).",
           "description": "(Read-only) Average rating from the last 200 reviews (rolling). Always full recalc."
         },
         "lowStockItemsCount": {
@@ -3616,8 +3994,8 @@
         },
         "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.",
+          "x-note": "Map keys use short codes in practice (OM, CASH, WAVE) \u2014 OM is a non-canonical alias for ORANGE_MONEY emitted by the metrics writer (#21). Value shape { total, count } differs from MetricsCurrent.paymentsByMethod (bare number).",
+          "description": "(Read-only, Optional) Payment breakdown by method for the day. Keys are PaymentMethod values (or legacy short code OM). Value is { total: XOF amount, count: number of payments }.",
           "type": [
             "object",
             "null"
@@ -3626,7 +4004,24 @@
             "type": "string"
           },
           "additionalProperties": {
-            "type": "number"
+            "type": "object",
+            "properties": {
+              "total": {
+                "type": "number",
+                "description": "Sum of payment amounts for this method on the given day (XOF)."
+              },
+              "count": {
+                "type": "integer",
+                "minimum": -9007199254740991,
+                "maximum": 9007199254740991,
+                "description": "Number of payments using this method on the given day."
+              }
+            },
+            "required": [
+              "total",
+              "count"
+            ],
+            "additionalProperties": false
           }
         },
         "computedForDay": {
@@ -3674,7 +4069,8 @@
         "date"
       ],
       "additionalProperties": false,
-      "description": "Daily metrics snapshot. Collection: companies/{companyId}/metrics_daily/{YYYY-MM-DD}. Same fields as MetricsCurrent plus `date`. Written by computeDailyCompanyMetrics cron (02:00 UTC) and inline after full recalcs.",
+      "x-note": "Zero-activity behavior (#9): the computeDailyCompanyMetrics cron (02:00 UTC) does NOT write a snapshot for days with no activity. A missing document means either zero activity or the cron did not run \u2014 consumers cannot distinguish the two from the absence alone. To detect cron gaps, compare the latest document date with today; a gap larger than 1 day on an otherwise active tenant indicates a cron failure. Observed: 3 of 4 zahoui tenants had gaps; bingerville (active) had a document every day.",
+      "description": "Daily metrics snapshot. Collection: companies/{companyId}/metrics_daily/{YYYY-MM-DD}. Same fields as MetricsCurrent plus `date`. Written by computeDailyCompanyMetrics cron (02:00 UTC) when the company had activity that day; zero-activity days may produce no document (#9).",
       "example": {
         "todayOrdersCount": 2,
         "pendingOrdersCount": 2,
@@ -3729,6 +4125,7 @@
         "orderCompletionRate30d": {
           "type": "number",
           "readOnly": true,
+          "x-note": "Firestore REST API v1 writes integerValue when the stored value is whole (e.g. 0), doubleValue when fractional (e.g. 82.17). Admin SDK smooths this to a JS number; REST clients must coerce the union (#11).",
           "description": "(Read-only) Percentage of orders completed or delivered in the last 30 days. Always full recalc."
         },
         "todayPurchasesCount": {
@@ -3746,11 +4143,13 @@
         "averagePurchaseAmount": {
           "type": "number",
           "readOnly": true,
+          "x-note": "Firestore REST API v1 writes integerValue when whole (e.g. 10070), doubleValue when fractional (e.g. 10006.5). Admin SDK smooths this; REST clients must coerce (#11).",
           "description": "(Read-only) Average purchase value across last 200 purchases (rolling, not time-windowed)."
         },
         "monthlyRevenue": {
           "type": "number",
           "readOnly": true,
+          "x-note": "Observed as integerValue on all sampled tenants (whole XOF amounts). Will be doubleValue if fractional. REST clients must coerce (#11).",
           "description": "(Read-only) Total purchase value in the current calendar month (UTC)."
         },
         "monthlyPurchasesCount": {
@@ -3787,6 +4186,7 @@
         "todayCollectedAmount": {
           "type": "number",
           "readOnly": true,
+          "x-note": "Observed as integerValue \"0\" on all sampled tenants. Will be doubleValue if fractional payments occur. REST clients must coerce (#11).",
           "description": "(Read-only) Sum of totalAmount for bookings where PAYMENT_PAID_AT is today. Resets at midnight."
         },
         "todayRevenue": {
@@ -3832,6 +4232,7 @@
         "averageRating": {
           "type": "number",
           "readOnly": true,
+          "x-note": "Observed as integerValue \"0\" on all tenants (no reviews yet). Will be doubleValue once real ratings exist. REST clients must coerce (#11).",
           "description": "(Read-only) Average rating from the last 200 reviews (rolling). Always full recalc."
         },
         "lowStockItemsCount": {
@@ -3992,6 +4393,16 @@
         "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": [
@@ -4288,6 +4699,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.",
@@ -4457,7 +4877,7 @@
               "type": "null"
             }
           ],
-          "description": "Unified payment method set with African + global methods (D02)."
+          "description": "Unified payment method set with African + global methods (D02). Note: the metrics writer historically emits \"OM\" instead of \"ORANGE_MONEY\" as a paymentsByMethod map key \u2014 treat OM as deprecated; canonical value is ORANGE_MONEY (#21)."
         },
         "invoiceId": {
           "description": "FK \u2192 Invoice document ID.",
@@ -4874,6 +5294,7 @@
         "companyId": "comp_xyz789",
         "appId": null,
         "orderNumber": "ORD-2026-0042",
+        "followUpUrl": null,
         "status": "status",
         "paymentStatus": "paymentStatus",
         "fulfillmentStatus": "fulfillmentStatus",
@@ -5196,6 +5617,191 @@
       ],
       "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-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"
+      ],
+      "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",
       "enum": [
@@ -5208,9 +5814,10 @@
         "BANK_TRANSFER",
         "PAYPAL",
         "STRIPE",
-        "OTHER"
+        "OTHER",
+        "OM"
       ],
-      "description": "Unified payment method set with African + global methods (D02)."
+      "description": "Unified payment method set with African + global methods (D02). Note: the metrics writer historically emits \"OM\" instead of \"ORANGE_MONEY\" as a paymentsByMethod map key \u2014 treat OM as deprecated; canonical value is ORANGE_MONEY (#21)."
     },
     "payment-proof-status": {
       "type": "string",
@@ -5234,6 +5841,198 @@
       ],
       "description": "Payment lifecycle status (D01 amended). Used by Order, Sale/Purchase, Booking."
     },
+    "payment-webhook-delivery": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "readOnly": true,
+          "description": "(Read-only) Firestore document ID, auto-generated.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "company": {
+          "type": "string",
+          "x-immutable": true,
+          "description": "(Immutable) Company document ID (e.g. \"gerko_studios\"). Resolved from the matched endpoint at delivery time."
+        },
+        "provider": {
+          "type": "string",
+          "x-note": "Observed value: \"jeko\". The inner payload.paymentMethod may differ (e.g. \"wave\") \u2014 provider here is the webhook sender, not the payment rail (#42).",
+          "description": "Payment provider that sent this webhook (e.g. \"jeko\", \"wave\")."
+        },
+        "eventType": {
+          "type": "string",
+          "x-note": "Observed value: \"transaction.payment\". Jeko docs say \"transaction.completed\" \u2014 full set per provider unconfirmed (#42). Use z.string() to avoid rejecting unseen values.",
+          "description": "Provider-defined event type. Observed: \"transaction.payment\". Full set per provider TBD (#42)."
+        },
+        "status": {
+          "type": "string",
+          "x-note": "Observed values: \"success\", \"error\". Indicates whether the webhook was processed without errors.",
+          "description": "Processing outcome. Observed values: \"success\" | \"error\"."
+        },
+        "verified": {
+          "type": "string",
+          "x-note": "Observed value: \"verified\". Indicates HMAC-SHA256 signature verification result. Full set of failure values unconfirmed (#42).",
+          "description": "Signature verification result. Observed: \"verified\". Other values (e.g. \"unverified\", \"error\") may exist but are unconfirmed."
+        },
+        "endpointStatus": {
+          "type": "string",
+          "x-note": "Observed value: \"matched\". Indicates whether the token resolved to a known PaymentWebhookEndpoint. Other values (e.g. \"not_found\", \"inactive\") unconfirmed (#42).",
+          "description": "Endpoint resolution result. Observed: \"matched\". Other values unconfirmed (#42)."
+        },
+        "processed": {
+          "type": "boolean",
+          "x-note": "Set to true once the delivery has been reconciled to the AppPayment ledger (companies/{cid}/apps/{appId}/payments). Back-reference FK not stored on this doc \u2014 reconciliation is tracked on the AppPayment side.",
+          "description": "Whether this delivery has been reconciled to the AppPayment ledger."
+        },
+        "reference": {
+          "type": "string",
+          "x-note": "Equals payload.id (provider transaction ID). Used as dedup key \u2014 the backend checks this before processing (#42 ask 3).",
+          "description": "Provider transaction ID (= payload.id). Canonical dedup key."
+        },
+        "amount": {
+          "type": "number",
+          "description": "Payment amount, denormalized from payload.amount.amount (XOF)."
+        },
+        "currency": {
+          "type": "string",
+          "description": "Currency code, denormalized from payload.amount.currency (e.g. \"XOF\")."
+        },
+        "payload": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {},
+          "x-note": "Parsed provider request body. Contains PII: counterpartIdentifier and counterpartLabel hold customer phone numbers. Retention/TTL policy TBD (#42 ask 5).",
+          "description": "Full parsed provider payload. Shape varies by provider. Contains PII (customer phone). See x-note for retention policy status."
+        },
+        "rawBody": {
+          "type": "string",
+          "x-note": "Verbatim request body string used for HMAC-SHA256 signature verification. Contains same PII as payload. Retention/TTL policy TBD (#42 ask 5).",
+          "description": "Verbatim raw request body \u2014 used for HMAC-SHA256 verification. Contains PII."
+        },
+        "headers": {
+          "x-note": "Request headers including provider signature (e.g. \"jeko-signature\") and tracing headers. Sensitive \u2014 do not expose to clients.",
+          "description": "Incoming HTTP headers. Includes provider signature header and Sentry trace. Sensitive.",
+          "type": [
+            "object",
+            "null"
+          ],
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "receivedAt": {
+          "$ref": "#/definitions/firestore-timestamp",
+          "description": "When the webhook delivery was received by the backend."
+        }
+      },
+      "required": [
+        "company",
+        "provider",
+        "eventType",
+        "status",
+        "verified",
+        "endpointStatus",
+        "processed",
+        "reference",
+        "amount",
+        "currency",
+        "payload",
+        "rawBody",
+        "receivedAt"
+      ],
+      "additionalProperties": false,
+      "x-internal": true,
+      "description": "PaymentWebhookDelivery (GH#42). Collection: payment_webhooks/{deliveryId} (top-level). One document per received provider callback. Contains raw payload + verification outcome. x-internal: written/read only by backend; dashboard reads via admin UI. PII in payload/rawBody \u2014 retention policy TBD.",
+      "example": {
+        "id": null,
+        "company": "company",
+        "provider": "pro_ref123",
+        "eventType": "eventType",
+        "status": "status",
+        "verified": "verified",
+        "endpointStatus": "endpointStatus",
+        "processed": true,
+        "reference": "reference",
+        "amount": 45000,
+        "currency": "XOF",
+        "payload": {},
+        "rawBody": "rawBody",
+        "headers": null,
+        "receivedAt": "receivedAt"
+      }
+    },
+    "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": [
@@ -6431,7 +7230,8 @@
         "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",
@@ -6459,6 +7259,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
         },
@@ -6716,10 +7517,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
         },
@@ -6826,6 +7630,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",
@@ -6936,6 +7741,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
         },