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

package/data/static/llms.txt

@@ -4,12 +4,16 @@
 > Source of truth: Zod schemas in packages/schema/src/
 > All Firestore documents are scoped under companies/{companyId}/
 
-> Generated: 2026-05-27
+> Generated: 2026-05-30
 
 ---
 
 ## Enums
 
+### AppStatus
+Lifecycle status for an App (formerly Site — renamed per decision #40 / D44). Drives whether the app is reachable and whether analytics/payments flow.
+Values: ACTIVE, INACTIVE, EXPIRED, ARCHIVED
+
 ### AttentionStatus
 Operational attention status for Order and Booking (D39). Controls home-page queue assignment. Server-owned — set via triggers or callable fn only.
 Values: ACTIVE, STALE, ON_HOLD, ESCALATED
@@ -18,6 +22,10 @@ Values: ACTIVE, STALE, ON_HOLD, ESCALATED
 Booking lifecycle status. COMPLETED_MIXED = some sessions completed, others cancelled/no-show.
 Values: PENDING, CONFIRMED, COMPLETED, CANCELLED, CANCELLATION_REQUESTED, COMPLETED_MIXED
 
+### ContractStatus
+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.
+Values: DRAFT, ACTIVE, COMPLETED, TERMINATED
+
 ### CustomerPaymentStatus
 Customer payment lifecycle status (D22). Tracks allocation progress of received payments.
 Values: PENDING, CONFIRMED, PARTIALLY_APPLIED, FULLY_APPLIED, REFUNDED, CANCELLED
@@ -46,6 +54,10 @@ Values: PREPARING, PARTIALLY_SHIPPED, SHIPPED, IN_TRANSIT, DELIVERED, PICKED_UP
 Loyalty point transaction type (D07). SCREAMING_SNAKE past tense.
 Values: EARNED, REDEEMED, ADJUSTED, EXPIRED, BONUS, REFUND
 
+### MilestoneStatus
+Status of a ContractMilestone (#17). PENDING = created, not yet invoiced. INVOICED = invoice issued, awaiting payment. PAID = payment received.
+Values: PENDING, INVOICED, PAID
+
 ### NotificationChannel
 Delivery channel of a NotificationRecord (GH#48).
 Values: email, whatsapp, sms, push
@@ -119,7 +131,7 @@ Event ticket status (D32). VALID = active and unused.
 Values: VALID, USED, CANCELLED
 
 ### WabaLabel
-Human-readable WABA label identifying which Meta business number received the message (GH#36).
+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).
 Values: cmz, val
 
 ### WhatsappButtonSubType
@@ -145,7 +157,7 @@ Fields: 9 (8 required)
 |-------|------|----------|-------------|
 | id | ['string', 'null'] | no | (Read-only) Firestore document ID = contact identifier (email or E.164 phone), URL-escaped. |
 | companyId | string | yes | (Immutable) FK → Company document ID. |
-| siteId | string | yes | (Immutable) FK → Site document ID (D40 sub-tenant scope). |
+| appId | string | yes | (Immutable) FK → App document ID (D40 sub-tenant scope, renamed per D44). |
 | contact | string | yes | Email or E.164 phone number. Canonical identifier for this user within the site. |
 | tier | string | yes | Access tier. Free string per site (ING-304 open question — tier values are site-specific today). |
 | amount | number | yes | Amount paid. Generalized from amount_xof per D40 decision. |
@@ -158,7 +170,7 @@ Example:
 {
   "id": null,
   "companyId": "comp_xyz789",
-  "siteId": "sit_ref123",
+  "appId": "app_ref123",
   "contact": "contact",
   "tier": "Gold",
   "amount": 45000,
@@ -175,7 +187,7 @@ Fields: 12 (10 required)
 |-------|------|----------|-------------|
 | id | ['string', 'null'] | no | (Read-only) Firestore document ID, auto-generated. |
 | companyId | string | yes | (Immutable) FK → Company document ID. |
-| siteId | string | yes | (Immutable) FK → Site document ID (D40). |
+| appId | string | yes | (Immutable) FK → Site document ID (D40). |
 | status | enum(5) | yes | Run status. |
 | from | string | yes | (Immutable) Inclusive start date (`YYYY-MM-DD`, UTC). |
 | to | string | yes | (Immutable) Inclusive end date (`YYYY-MM-DD`, UTC). |
@@ -194,7 +206,7 @@ Example:
 {
   "id": null,
   "companyId": "comp_xyz789",
-  "siteId": "sit_ref123",
+  "appId": "app_ref123",
   "status": "pending",
   "from": "from",
   "to": "to",
@@ -232,7 +244,7 @@ Fields: 16 (14 required)
 | eventCounts | record<string,integer> | yes | Per-event-name counts — key is the event name (canonical or custom), value is the count within the bucket. |
 | id | ['string', 'null'] | no | (Read-only) Firestore document ID = `YYYY-MM-DD`. |
 | companyId | string | yes | (Immutable) FK → Company document ID. |
-| siteId | string | yes | (Immutable) FK → Site document ID (D40). |
+| appId | string | yes | (Immutable) FK → Site document ID (D40). |
 | date | string | yes | (Immutable) `YYYY-MM-DD` UTC — matches document ID. |
 | computedAt | FirestoreTimestamp | yes | (Read-only) When this rollup was last (re)computed. Updated on every set/merge. |
 | sourceEventCount | ['integer', 'null'] | no | (Read-only, Optional) Total source events scanned when producing this rollup. Useful for dry-run diffing. |
@@ -252,7 +264,7 @@ Example:
   "eventCounts": {},
   "id": null,
   "companyId": "comp_xyz789",
-  "siteId": "sit_ref123",
+  "appId": "app_ref123",
   "date": "2026-02-15",
   "computedAt": "computedAt",
   "sourceEventCount": null
@@ -266,7 +278,7 @@ Fields: 12 (10 required)
 |-------|------|----------|-------------|
 | id | ['string', 'null'] | no | (Read-only) Firestore document ID. Equal to eventId. |
 | companyId | string | yes | (Immutable) FK → Company document ID. |
-| siteId | string | yes | (Immutable) FK → Site document ID (D40 sub-tenant scope). |
+| appId | string | yes | (Immutable) FK → App document ID (D40 sub-tenant scope, renamed per D44). |
 | eventId | string | yes | (Immutable) Client-generated UUID. Matches document ID. |
 | eventName | string | yes | Event name. Free string; canonical vocabulary is encouraged (see CANONICAL_ANALYTICS_EVENT_NAMES). |
 | timestamp | string | yes | Client-side ISO 8601 — "when it happened on device". Can diverge from serverTimestamp for queued offline events. |
@@ -297,7 +309,7 @@ Example:
 {
   "id": null,
   "companyId": "comp_xyz789",
-  "siteId": "sit_ref123",
+  "appId": "app_ref123",
   "eventId": "eve_ref123",
   "eventName": "eventName",
   "timestamp": "timestamp",
@@ -327,7 +339,7 @@ Fields: 17 (15 required)
 | eventCounts | record<string,integer> | yes | Per-event-name counts — key is the event name (canonical or custom), value is the count within the bucket. |
 | id | ['string', 'null'] | no | (Read-only) Firestore document ID = `YYYY-MM-DD-HH`. |
 | companyId | string | yes | (Immutable) FK → Company document ID. |
-| siteId | string | yes | (Immutable) FK → Site document ID (D40). |
+| appId | string | yes | (Immutable) FK → Site document ID (D40). |
 | date | string | yes | (Immutable) `YYYY-MM-DD` UTC for the bucket day. |
 | hour | integer | yes | (Immutable) UTC hour of day, 0–23. |
 | computedAt | FirestoreTimestamp | yes | (Read-only) When this rollup was last (re)computed. |
@@ -348,7 +360,7 @@ Example:
   "eventCounts": {},
   "id": null,
   "companyId": "comp_xyz789",
-  "siteId": "sit_ref123",
+  "appId": "app_ref123",
   "date": "2026-02-15",
   "hour": 0,
   "computedAt": "computedAt",
@@ -356,6 +368,88 @@ Example:
 }
 ```
 
+### App
+Fields: 14 (5 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | ['string', 'null'] | no | (Read-only) Firestore document ID, auto-generated. |
+| companyId | string | yes | (Immutable) FK → Company document ID. Scopes all app sub-collections. |
+| name | string | yes | Human-readable app name shown in dashboards. |
+| description | ['string', 'null'] | no | Optional freeform description. |
+| status | any | no | Lifecycle status (D41/D44). Optional pending backfill of pre-existing records (#26) — treat absent as ACTIVE. Clients filter by ACTIVE. |
+| deploymentLinks | array<object> | yes | Ordered list of deployment URLs (web, mobile, PWA, store links). |
+| deploymentLinks[].label | string | yes | Human-readable label shown in dashboards (e.g. "Production", "Staging"). |
+| deploymentLinks[].url | string | yes | Absolute URL or store link. |
+| deploymentLinks[].type | DeploymentLinkType | yes | Link category — drives icon/handler selection. |
+| deploymentLinks[].isPrimary | boolean | no | If true, this link is used as the canonical deployment URL for the App. |
+| expiresAt | any | no | Optional expiration timestamp. When set and elapsed, `isExpired` flips true and status typically moves to EXPIRED. |
+| isExpired | ['boolean', 'null'] | no | (Read-only) Derived — true when `expiresAt` is in the past. Maintained by server trigger. |
+| createdAt | any | no | (Read-only) Server-generated creation timestamp. |
+| updatedAt | any | no | (Read-only) Server-generated update timestamp. |
+| createdBy | string | yes | (Immutable) FK → User/staff UID who created the app. |
+| analyticsEnabled | boolean | yes | Feature flag — when false, clients should not emit analytics events for this app. |
+| lastAnalyticsSync | any | no | (Read-only) Last time the analytics rollup pipeline refreshed `cachedMetrics`. |
+| cachedMetrics | ['object', 'null'] | no | (Read-only, Denormalized) Cached metrics snapshot for quick dashboard rendering. |
+
+Example:
+```json
+{
+  "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
+}
+```
+
+### AppPayment
+Fields: 10 (9 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | ['string', 'null'] | no | (Read-only) Firestore document ID, auto-generated. |
+| companyId | string | yes | (Immutable) FK → Company document ID. |
+| appId | string | yes | (Immutable) FK → App document ID (D40 sub-tenant scope, renamed from siteId per D44). |
+| contact | string | yes | Email or E.164 phone number. Matches AllowedUser.contact. |
+| sessionId | string | yes | Payment provider checkout session ID (e.g. Wave). Usable for dedup across dual writes. |
+| transactionId | string | yes | Payment provider transaction ID. |
+| tier | string | yes | Access tier. Free string per app (ING-304 open question). |
+| amount | number | yes | Amount paid. Generalized from amount_xof per D40 decision. |
+| currency | string | yes | Currency code (ISO 4217). Defaults to XOF for legacy SR-Single parity. |
+| paidAt | FirestoreTimestamp | yes | RFC3339Nano UTC when payment was completed. |
+
+Example:
+```json
+{
+  "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"
+}
+```
+
 ### Booking
 Fields: 52 (7 required)
 
@@ -382,9 +476,9 @@ Fields: 52 (7 required)
 | bookingDates[].selectedTimeSlots[].isNotMainPurposeReason | string | no |  |
 | bookingDates[].selectedTimeSlots[].isNotMainPurposeOtherReason | string | no |  |
 | bookingDates[].selectedTimeSlots[]._deleted | boolean | no | Soft-delete flag. Dashboard writes; Mobile filters (IG-6). |
-| bookingDates[].selectedTimeSlots[]._deletedAt | FirestoreTimestamp | no | Firestore Timestamp serialized representation |
+| bookingDates[].selectedTimeSlots[]._deletedAt | FirestoreTimestamp | no | Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10). |
 | bookingDates[].selectedTimeSlots[]._deletedBy | string | no | FK → User/staff UID who soft-deleted this item. |
-| bookingDates[].selectedTimeSlots[]._lastModifiedAt | FirestoreTimestamp | no | Firestore Timestamp serialized representation |
+| bookingDates[].selectedTimeSlots[]._lastModifiedAt | FirestoreTimestamp | no | Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10). |
 | bookingDates[].selectedTimeSlots[]._lastModifiedBy | string | no | FK → User/staff UID who last modified this item. |
 | bookingDates[].selectedTimeSlots[]._version | number | no | Monotonic version counter for conflict detection. |
 | bookingDates[].slotKitTypes | record<string,string> | yes | Kit type per slot (IG-11). Firebase parity gap — exists in Firestore but Firebase type lacked it. |
@@ -397,9 +491,9 @@ Fields: 52 (7 required)
 | bookingDates[].slotStatusUpdatedAt | record<string,FirestoreTimestamp> | no |  |
 | bookingDates[].slotStatusUpdatedBy | record<string,string> | no |  |
 | bookingDates[]._deleted | boolean | no | Soft-delete flag. Dashboard writes; Mobile filters (IG-6). |
-| bookingDates[]._deletedAt | FirestoreTimestamp | no | Firestore Timestamp serialized representation |
+| bookingDates[]._deletedAt | FirestoreTimestamp | no | Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10). |
 | bookingDates[]._deletedBy | string | no | FK → User/staff UID who soft-deleted this item. |
-| bookingDates[]._lastModifiedAt | FirestoreTimestamp | no | Firestore Timestamp serialized representation |
+| bookingDates[]._lastModifiedAt | FirestoreTimestamp | no | Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10). |
 | bookingDates[]._lastModifiedBy | string | no | FK → User/staff UID who last modified this item. |
 | bookingDates[]._version | number | no | Monotonic version counter for conflict detection. |
 | customerId | ['string', 'null'] | no | FK → Customer.id (Firestore doc ID). Links booking to customer record. |
@@ -429,18 +523,18 @@ Fields: 52 (7 required)
 | purchaseId | ['string', 'null'] | no | FK → Sale.id. Link to associated Sale document. |
 | paymentStatusChangeReason | ['string', 'null'] | no |  |
 | paymentStatusChangedBy | ['string', 'null'] | no | FK → User/staff UID who changed payment status. |
-| paymentStatusChangedAt | any | no | Firestore Timestamp serialized representation |
+| paymentStatusChangedAt | any | no | Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10). |
 | paymentProofUrl | ['string', 'null'] | no | URL to uploaded payment proof image/document. |
 | paymentProofStatus | any | no | Payment proof review status. Used by Order and Booking payment proof workflows. |
-| paymentProofAddedAt | any | no | Firestore Timestamp serialized representation |
+| paymentProofAddedAt | any | no | Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10). |
 | paymentProofAddedBy | ['string', 'null'] | no | FK → User/staff UID who uploaded the payment proof. |
 | paymentProofReviewedBy | ['string', 'null'] | no | FK → User/staff UID who reviewed the payment proof. |
-| paymentProofReviewedAt | any | no | Firestore Timestamp serialized representation |
+| paymentProofReviewedAt | any | no | Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10). |
 | paymentProofRejectionReason | ['string', 'null'] | no |  |
 | cancellationRequestedById | ['string', 'null'] | no | FK → User/staff UID who requested cancellation. |
 | cancellationRequestReason | ['string', 'null'] | no |  |
 | cancellationProcessedById | ['string', 'null'] | no | FK → User/staff UID who processed the cancellation. |
-| cancellationProcessedAt | any | no | Firestore Timestamp serialized representation |
+| cancellationProcessedAt | any | no | Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10). |
 | cancelledByRole | ['string', 'null'] | no |  |
 | cancellationReason | ['string', 'null'] | no |  |
 | createdAt | FirestoreTimestamp | yes | (Read-only) Server-generated creation timestamp. |
@@ -556,6 +650,48 @@ Example:
 }
 ```
 
+### Contract
+Fields: 15 (8 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | ['string', 'null'] | no | (Read-only) Firestore document ID, auto-generated. |
+| companyId | string | yes | (Immutable) FK → Company document ID. |
+| payeeId | string | yes | (Immutable) FK → Payee document ID. Full Payee model tracked in #20. |
+| title | string | yes | Contract title or reference name shown in dashboards. |
+| description | ['string', 'null'] | no | Optional freeform description of the contract scope. |
+| status | ContractStatus | yes | Contract lifecycle status (#14). Query by ACTIVE — do not use an isActive boolean. |
+| currency | string | yes | Currency code. Locked to XOF (#18). Multi-currency support requires a deliberate schema version bump. |
+| totalAmount | number | yes | Total contract value (XOF). |
+| startDate | string | yes | Contract start date (ISO 8601 YYYY-MM-DD). |
+| endDate | ['string', 'null'] | no | Contract end date (ISO 8601 YYYY-MM-DD). Absent for open-ended contracts. |
+| milestones | ['array', 'null'] | no | Ordered list of payment milestones. Embedded in the contract document (#17). |
+| notes | ['string', 'null'] | no | Optional internal notes. |
+| createdBy | string | yes | (Immutable) FK → User/staff UID who created the contract. |
+| createdAt | any | no | (Read-only) Server-generated creation timestamp. |
+| updatedAt | any | no | (Read-only) Server-generated update timestamp. |
+
+Example:
+```json
+{
+  "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"
+}
+```
+
 ### Customer
 Fields: 17 (4 required)
 
@@ -613,7 +749,7 @@ Fields: 17 (12 required)
 | customerName | ['string', 'null'] | no | (Denormalized) From Customer.name at write time. |
 | amount | number | yes |  |
 | currency | string | yes | Currency code. Locked to XOF (West African CFA franc) for now. |
-| paymentDate | FirestoreTimestamp | yes | Firestore Timestamp serialized representation |
+| paymentDate | FirestoreTimestamp | yes | Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10). |
 | paymentMethod | PaymentMethod | yes | Unified payment method set with African + global methods (D02). |
 | referenceNumber | string | yes | Unique payment reference (receipt number, transaction ID, etc.). |
 | allocatedAmount | number | yes | (Read-only) Total amount allocated to bookings/orders/purchases via allocations. Server-calculated. |
@@ -663,7 +799,7 @@ Fields: 14 (8 required)
 | allocatedAmount | number | yes | (Immutable) Amount allocated in this allocation. Set at creation. |
 | transferredToAllocationId | ['string', 'null'] | no | FK → CustomerPaymentAllocation.id. Self-reference for transfer chains. |
 | transferredFromAllocationId | ['string', 'null'] | no | FK → CustomerPaymentAllocation.id. Self-reference for transfer chains. |
-| transferredAt | any | no | Firestore Timestamp serialized representation |
+| transferredAt | any | no | Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10). |
 | createdBy | string | yes | (Immutable) FK → User/staff UID who created this allocation. |
 | createdByName | ['string', 'null'] | no | (Immutable, Denormalized) From User display name at creation time. |
 | createdAt | FirestoreTimestamp | yes | (Read-only) Server-generated creation timestamp. |
@@ -698,8 +834,8 @@ Fields: 15 (9 required)
 | name | string | yes |  |
 | description | ['string', 'null'] | no |  |
 | location | ['string', 'null'] | no |  |
-| startDate | FirestoreTimestamp | yes | Firestore Timestamp serialized representation |
-| endDate | any | no | Firestore Timestamp serialized representation |
+| startDate | FirestoreTimestamp | yes | Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10). |
+| endDate | any | no | Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10). |
 | status | EventStatus | yes | Event lifecycle status (D32). SCREAMING_SNAKE per D04. MIG-09 migrates legacy lowercase values. |
 | maxTickets | ['integer', 'null'] | no |  |
 | ticketsSold | integer | yes | (Read-only) Counter: total tickets sold. Updated by Firebase triggers (D28). |
@@ -879,7 +1015,7 @@ Fields: 15 (11 required)
 |-------|------|----------|-------------|
 | id | ['string', 'null'] | no | (Read-only) Firestore document ID. 16-byte random hex. |
 | companyId | string | yes | (Immutable) FK → Company document ID. |
-| siteId | string | yes | (Immutable) FK → Site document ID (D40 sub-tenant scope). |
+| appId | string | yes | (Immutable) FK → App document ID (D40 sub-tenant scope, renamed per D44). |
 | email | string | yes | Populated if identifier is email; empty string if phone. Mutually exclusive with phone per document. |
 | phone | string | yes | Populated if identifier is E.164 format (starts with +); empty string if email. |
 | ip | string | yes | Client IP from X-Forwarded-For or RemoteAddr. |
@@ -898,7 +1034,7 @@ Example:
 {
   "id": null,
   "companyId": "comp_xyz789",
-  "siteId": "sit_ref123",
+  "appId": "app_ref123",
   "email": "amadou@example.com",
   "phone": "+225 07 00 11 22",
   "ip": "ip",
@@ -915,7 +1051,7 @@ Example:
 ```
 
 ### MetricsCurrent
-Fields: 25 (25 required)
+Fields: 30 (25 required)
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
@@ -942,6 +1078,11 @@ Fields: 25 (25 required)
 | lowStockItemsCount | integer | yes | (Read-only) Active stock items where currentQuantity <= minimumQuantity. Current state, always full recalc. |
 | activeRecurringPaymentsCount | integer | yes | (Read-only) Recurring payments with status ACTIVE. Current state, always full recalc. |
 | monthlyRecurringRevenue | number | yes | (Read-only) Sum of amount for ACTIVE + MONTHLY recurring payments. Always full recalc. |
+| escalatedOrdersCount | ['integer', 'null'] | no | (Read-only, Optional) Orders currently in an escalated state. Present once the current aggregator rewrites the document. |
+| staleOrdersCount | ['integer', 'null'] | no | (Read-only, Optional) Orders that have been in an incomplete status beyond the stale threshold. |
+| staleBookingsCount | ['integer', 'null'] | no | (Read-only, Optional) Bookings that have been in an incomplete status beyond the stale threshold. |
+| onHoldOrdersCount | ['integer', 'null'] | no | (Read-only, Optional) Orders currently in an on-hold state. |
+| paymentsByMethod | ['object', 'null'] | no | (Read-only, Optional) Map of PaymentMethod → total amount for the current day. Empty map {} until first payment. |
 | computedForDay | string | yes | (Read-only) YYYY-MM-DD string indicating which day these metrics reflect. Used to detect day boundaries and trigger midnight resets. |
 | generatedAt | FirestoreTimestamp | yes | (Read-only) Server timestamp of the last metrics write. |
 
@@ -971,13 +1112,18 @@ Example:
   "lowStockItemsCount": 2,
   "activeRecurringPaymentsCount": 2,
   "monthlyRecurringRevenue": 0,
+  "escalatedOrdersCount": null,
+  "staleOrdersCount": null,
+  "staleBookingsCount": null,
+  "onHoldOrdersCount": null,
+  "paymentsByMethod": null,
   "computedForDay": "computedForDay",
   "generatedAt": "generatedAt"
 }
 ```
 
 ### MetricsDaily
-Fields: 26 (26 required)
+Fields: 31 (26 required)
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
@@ -1004,6 +1150,11 @@ Fields: 26 (26 required)
 | lowStockItemsCount | integer | yes | (Read-only) Active stock items where currentQuantity <= minimumQuantity. Current state, always full recalc. |
 | activeRecurringPaymentsCount | integer | yes | (Read-only) Recurring payments with status ACTIVE. Current state, always full recalc. |
 | monthlyRecurringRevenue | number | yes | (Read-only) Sum of amount for ACTIVE + MONTHLY recurring payments. Always full recalc. |
+| escalatedOrdersCount | ['integer', 'null'] | no | (Read-only, Optional) Orders currently in an escalated state. Present once the current aggregator rewrites the document. |
+| staleOrdersCount | ['integer', 'null'] | no | (Read-only, Optional) Orders that have been in an incomplete status beyond the stale threshold. |
+| staleBookingsCount | ['integer', 'null'] | no | (Read-only, Optional) Bookings that have been in an incomplete status beyond the stale threshold. |
+| onHoldOrdersCount | ['integer', 'null'] | no | (Read-only, Optional) Orders currently in an on-hold state. |
+| paymentsByMethod | ['object', 'null'] | no | (Read-only, Optional) Map of PaymentMethod → total amount for the current day. Empty map {} until first payment. |
 | computedForDay | string | yes | (Read-only) YYYY-MM-DD string indicating which day these metrics reflect. Used to detect day boundaries and trigger midnight resets. |
 | generatedAt | FirestoreTimestamp | yes | (Read-only) Server timestamp of the last metrics write. |
 | date | string | yes | (Read-only) YYYY-MM-DD document ID repeated as a field. Identifies the day this snapshot covers. |
@@ -1034,6 +1185,11 @@ Example:
   "lowStockItemsCount": 2,
   "activeRecurringPaymentsCount": 2,
   "monthlyRecurringRevenue": 0,
+  "escalatedOrdersCount": null,
+  "staleOrdersCount": null,
+  "staleBookingsCount": null,
+  "onHoldOrdersCount": null,
+  "paymentsByMethod": null,
   "computedForDay": "computedForDay",
   "generatedAt": "generatedAt",
   "date": "2026-02-15"
@@ -1041,7 +1197,7 @@ Example:
 ```
 
 ### MetricsMonthly
-Fields: 26 (26 required)
+Fields: 31 (26 required)
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
@@ -1068,6 +1224,11 @@ Fields: 26 (26 required)
 | lowStockItemsCount | integer | yes | (Read-only) Active stock items where currentQuantity <= minimumQuantity. Current state, always full recalc. |
 | activeRecurringPaymentsCount | integer | yes | (Read-only) Recurring payments with status ACTIVE. Current state, always full recalc. |
 | monthlyRecurringRevenue | number | yes | (Read-only) Sum of amount for ACTIVE + MONTHLY recurring payments. Always full recalc. |
+| escalatedOrdersCount | ['integer', 'null'] | no | (Read-only, Optional) Orders currently in an escalated state. Present once the current aggregator rewrites the document. |
+| staleOrdersCount | ['integer', 'null'] | no | (Read-only, Optional) Orders that have been in an incomplete status beyond the stale threshold. |
+| staleBookingsCount | ['integer', 'null'] | no | (Read-only, Optional) Bookings that have been in an incomplete status beyond the stale threshold. |
+| onHoldOrdersCount | ['integer', 'null'] | no | (Read-only, Optional) Orders currently in an on-hold state. |
+| paymentsByMethod | ['object', 'null'] | no | (Read-only, Optional) Map of PaymentMethod → total amount for the current day. Empty map {} until first payment. |
 | computedForDay | string | yes | (Read-only) YYYY-MM-DD string indicating which day these metrics reflect. Used to detect day boundaries and trigger midnight resets. |
 | generatedAt | FirestoreTimestamp | yes | (Read-only) Server timestamp of the last metrics write. |
 | month | string | yes | (Read-only) YYYY-MM document ID repeated as a field. Identifies the month this rollup covers. |
@@ -1098,6 +1259,11 @@ Example:
   "lowStockItemsCount": 2,
   "activeRecurringPaymentsCount": 2,
   "monthlyRecurringRevenue": 0,
+  "escalatedOrdersCount": null,
+  "staleOrdersCount": null,
+  "staleBookingsCount": null,
+  "onHoldOrdersCount": null,
+  "paymentsByMethod": null,
   "computedForDay": "computedForDay",
   "generatedAt": "generatedAt",
   "month": "month"
@@ -1165,15 +1331,16 @@ Example:
 ```
 
 ### Order
-Fields: 48 (8 required)
+Fields: 49 (8 required)
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | id | string | yes | (Read-only) Firestore document ID. Note: some models also have uid; see ID conventions. |
 | uid | string | yes | (Read-only) Entity UID. Often mirrors id. |
 | companyId | string | yes | (Immutable) FK → Company document ID. Scopes all queries. |
-| siteId | ['string', 'null'] | no | (Immutable, Optional) FK → Site document ID (D43 / ADR-003). null = company-wide. |
+| appId | ['string', 'null'] | no | (Immutable, Optional) FK → App document ID (D43 / ADR-003, renamed from siteId per D44). null = company-wide. |
 | orderNumber | string | yes | (Read-only) Server-generated order number. |
+| followUpUrl | ['string', 'null'] | no | Optional URL for receipt QR code / post-order follow-up. Canonical casing: followUpUrl (#6). |
 | status | OrderStatus | yes | Core lifecycle status (D34, MIG-11). See OrderStatus enum for the legacy value migration mapping. |
 | paymentStatus | any | no | Payment lifecycle (D34). Null until payment is initiated. |
 | fulfillmentStatus | any | no | Delivery/fulfillment lifecycle (D34). |
@@ -1192,14 +1359,14 @@ Fields: 48 (8 required)
 | amountPaid | ['number', 'null'] | no | Amount of `amount` paid to date. Derived from payment allocations. |
 | total | ['number', 'null'] | no | Mobile-only legacy total field. Deprecated — use `amount`. |
 | createdAt | FirestoreTimestamp | yes | (Read-only) Server-generated creation timestamp. |
-| orderDate | FirestoreTimestamp | yes | Firestore Timestamp serialized representation |
+| orderDate | FirestoreTimestamp | yes | Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10). |
 | PROCESSING_ON | any | no | (Read-only) Timestamp when order entered PROCESSING (D04 SCREAMING_SNAKE). MIG-01 renames from camelCase. |
 | COMPLETED_ON | any | no | (Read-only) Timestamp when order completed (D04 SCREAMING_SNAKE). MIG-01 renames from camelCase. |
 | CANCELLED_ON | any | no | (Read-only) Timestamp when order cancelled (D04 SCREAMING_SNAKE). MIG-01 renames from camelCase. |
 | cancellationReason | ['string', 'null'] | no |  |
 | shippingCarrier | ['string', 'null'] | no |  |
 | trackingNumber | ['string', 'null'] | no |  |
-| estimatedDeliveryDate | any | no | Firestore Timestamp serialized representation |
+| estimatedDeliveryDate | any | no | Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10). |
 | shippingCost | ['number', 'null'] | no |  |
 | paymentProofUrl | ['string', 'null'] | no | URL to uploaded payment proof image/document. |
 | paymentProofStatus | any | no | Payment proof review status. |
@@ -1224,8 +1391,9 @@ Example:
   "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",
@@ -1308,6 +1476,94 @@ Example:
 }
 ```
 
+### OutboundPayment
+Fields: 13 (7 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | ['string', 'null'] | no | (Read-only) Firestore document ID, auto-generated. |
+| companyId | string | yes | (Immutable) FK → Company document ID. |
+| payeeId | string | yes | (Immutable) FK → Payee document ID. Full Payee model tracked in #20. |
+| contractId | ['string', 'null'] | no | (Immutable, Optional) FK → Contract document ID. Absent for ad-hoc payments outside a formal contract. |
+| amount | number | yes | Amount paid (XOF). |
+| currency | string | yes | Currency code. Locked to XOF — consistent with Contract and CustomerPayment. |
+| method | PaymentMethod | yes | Payment method used (e.g. BANK_TRANSFER, MOBILE_MONEY, CHECK). |
+| reference | ['string', 'null'] | no | Optional payment reference — bank transaction number, check number, Wave ref, etc. |
+| paidAt | FirestoreTimestamp | yes | When the payment was made. |
+| notes | ['string', 'null'] | no | Optional internal notes. |
+| createdBy | string | yes | (Immutable) FK → User/staff UID who recorded the payment. |
+| createdAt | any | no | (Read-only) Server-generated creation timestamp. |
+| updatedAt | any | no | (Read-only) Server-generated update timestamp. |
+
+Example:
+```json
+{
+  "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"
+}
+```
+
+### OutboundPaymentAllocation
+Fields: 7 (4 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | ['string', 'null'] | no | (Read-only) Firestore document ID, auto-generated. |
+| outboundPaymentId | string | yes | (Immutable) FK → OutboundPayment document ID (parent). |
+| expenseId | string | yes | (Immutable) FK → Expense document ID. Full Expense model tracked in #20. |
+| companyId | string | yes | (Immutable) FK → Company document ID. Denormalized for collection-group queries. |
+| amount | number | yes | Amount of this payment allocated to the referenced expense (XOF). |
+| notes | ['string', 'null'] | no | Optional notes about this allocation. |
+| allocatedAt | any | no | (Read-only) When this allocation was recorded. |
+
+Example:
+```json
+{
+  "id": null,
+  "outboundPaymentId": "out_ref123",
+  "expenseId": "exp_ref123",
+  "companyId": "comp_xyz789",
+  "amount": 45000,
+  "notes": null,
+  "allocatedAt": "allocatedAt"
+}
+```
+
+### PaymentWebhookEndpoint
+Fields: 6 (5 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| token | string | yes | (Immutable) base64url-encoded 24-byte random token. Also the Firestore document ID and the URL path segment. |
+| company | string | yes | (Immutable) Company slug (e.g. gerko_studios). Identifies the tenant that owns this endpoint. |
+| provider | enum(2) | yes | (Immutable) Payment provider whose webhooks this endpoint accepts. |
+| secret | string | yes | Webhook signing secret for HMAC verification. Backend-only — never returned to dashboard or mobile clients. |
+| active | boolean | yes | Whether this endpoint is currently active. Inactive endpoints reject incoming webhooks. |
+| createdAt | any | no | (Read-only) When this endpoint was provisioned. |
+
+Example:
+```json
+{
+  "token": "token",
+  "company": "company",
+  "provider": "wave",
+  "secret": "secret",
+  "active": true,
+  "createdAt": "createdAt"
+}
+```
+
 ### Sale
 Fields: 12 (1 required)
 
@@ -1323,7 +1579,7 @@ Fields: 12 (1 required)
 | notes | ['string', 'null'] | no |  |
 | orderId | ['string', 'null'] | no | FK → Order.id. Link to associated Order document. |
 | bookingId | ['string', 'null'] | no | FK → Booking.id. Link to associated Booking document (IG-12). |
-| purchaseDate | FirestoreTimestamp | yes | Firestore Timestamp serialized representation |
+| purchaseDate | FirestoreTimestamp | yes | Firestore Timestamp — Admin SDK form: { _seconds, _nanoseconds }. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10). |
 | createdAt | any | no | (Read-only) Server-generated creation timestamp. |
 
 Example:
@@ -1568,6 +1824,36 @@ Example:
 }
 ```
 
+### User
+Fields: 9 (0 required)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | ['string', 'null'] | no | (Read-only) Firebase Auth UID. Matches the Firestore document ID. |
+| displayName | ['string', 'null'] | no | User display name from Firebase Auth or manually set. |
+| email | ['string', 'null'] | no | Email address. Present for email/Google auth users. |
+| phoneE164 | ['string', 'null'] | no | E.164-normalized phone number (e.g. +2250777471485). Canonical phone identity field; used for WhatsApp OTP lookup via indexed query. |
+| companyId | ['string', 'null'] | no | (Immutable) FK → Company document ID. Present for staff accounts scoped to a company. |
+| role | ['string', 'null'] | no | Staff role within the company (e.g. admin, manager, staff). Application-defined. |
+| isActive | ['boolean', 'null'] | no | Whether this user account is active. Inactive accounts are denied access. |
+| createdAt | any | no | (Read-only) When the user document was created. |
+| updatedAt | any | no | (Read-only) When the user document was last updated. |
+
+Example:
+```json
+{
+  "id": null,
+  "displayName": null,
+  "email": null,
+  "phoneE164": null,
+  "companyId": null,
+  "role": null,
+  "isActive": null,
+  "createdAt": "createdAt",
+  "updatedAt": "updatedAt"
+}
+```
+
 ### WhatsappInboundMessage
 Fields: 13 (7 required)
 
@@ -1646,7 +1932,7 @@ Fields: 18 (7 required)
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | id | ['string', 'null'] | no | (Read-only) Firestore document ID — auto-generated at enqueue time. |
-| to | string | yes | (Immutable) Recipient phone number in E.164 format. Must match the inbound `from` for the same conversation. |
+| to | string | yes | (Immutable) Recipient Meta wa_id — digits only, no leading + (e.g. 22577471485). Equal to the inbound `from` for the same conversation. NOT literal E.164; see x-note (#54). |
 | waba | WabaLabel | yes | (Immutable) WABA that will send the message. Mirrors inbound `waba`. |
 | wabaId | string | yes | (Immutable) Meta WABA ID. Mirrors inbound `wabaId`. |
 | kind | OutboundMessageFormat | yes | (Immutable) Message format: `text` or `template`. Set `text` xor `template` to match. |