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

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
@@ -145,7 +149,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 +162,7 @@ Example:
 {
   "id": null,
   "companyId": "comp_xyz789",
-  "siteId": "sit_ref123",
+  "appId": "app_ref123",
   "contact": "contact",
   "tier": "Gold",
   "amount": 45000,
@@ -175,7 +179,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 +198,7 @@ Example:
 {
   "id": null,
   "companyId": "comp_xyz789",
-  "siteId": "sit_ref123",
+  "appId": "app_ref123",
   "status": "pending",
   "from": "from",
   "to": "to",
@@ -232,7 +236,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 +256,7 @@ Example:
   "eventCounts": {},
   "id": null,
   "companyId": "comp_xyz789",
-  "siteId": "sit_ref123",
+  "appId": "app_ref123",
   "date": "2026-02-15",
   "computedAt": "computedAt",
   "sourceEventCount": null
@@ -266,7 +270,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 +301,7 @@ Example:
 {
   "id": null,
   "companyId": "comp_xyz789",
-  "siteId": "sit_ref123",
+  "appId": "app_ref123",
   "eventId": "eve_ref123",
   "eventName": "eventName",
   "timestamp": "timestamp",
@@ -327,7 +331,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 +352,7 @@ Example:
   "eventCounts": {},
   "id": null,
   "companyId": "comp_xyz789",
-  "siteId": "sit_ref123",
+  "appId": "app_ref123",
   "date": "2026-02-15",
   "hour": 0,
   "computedAt": "computedAt",
@@ -356,6 +360,88 @@ Example:
 }
 ```
 
+### App
+Fields: 14 (6 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 | AppStatus | yes | Lifecycle status (D41/D44). 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 +468,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 +483,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 +515,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. |
@@ -613,7 +699,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 +749,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 +784,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 +965,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 +984,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 +1001,7 @@ Example:
 ```
 
 ### MetricsCurrent
-Fields: 25 (25 required)
+Fields: 30 (25 required)
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
@@ -942,6 +1028,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 +1062,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 +1100,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 +1135,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 +1147,7 @@ Example:
 ```
 
 ### MetricsMonthly
-Fields: 26 (26 required)
+Fields: 31 (26 required)
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
@@ -1068,6 +1174,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 +1209,11 @@ Example:
   "lowStockItemsCount": 2,
   "activeRecurringPaymentsCount": 2,
   "monthlyRecurringRevenue": 0,
+  "escalatedOrdersCount": null,
+  "staleOrdersCount": null,
+  "staleBookingsCount": null,
+  "onHoldOrdersCount": null,
+  "paymentsByMethod": null,
   "computedForDay": "computedForDay",
   "generatedAt": "generatedAt",
   "month": "month"
@@ -1172,7 +1288,7 @@ Fields: 48 (8 required)
 | 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. |
 | 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. |
@@ -1192,14 +1308,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,7 +1340,7 @@ Example:
   "id": "bk_abc123def456",
   "uid": "user_u8x92kqm",
   "companyId": "comp_xyz789",
-  "siteId": null,
+  "appId": null,
   "orderNumber": "ORD-2026-0042",
   "status": "status",
   "paymentStatus": "paymentStatus",
@@ -1323,7 +1439,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 +1684,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)