@ingenx-io/valets-schema-mcp-server 0.1.4 → 0.1.6

package/data/static/schemas.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "description": "@valets/schema \u2014 consolidated schema bundle",
-  "generated": "2026-04-18T21:21:09.696794+00:00",
+  "generated": "2026-05-05T12:09:28.979656+00:00",
   "schemas": {
     "allowed-user": {
       "type": "object",
@@ -74,6 +74,292 @@
         "paidAt": "pai_ref123"
       }
     },
+    "analytics-backfill": {
+      "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."
+        },
+        "siteId": {
+          "type": "string",
+          "x-immutable": true,
+          "description": "(Immutable) FK \u2192 Site document ID (D40)."
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "pending",
+            "running",
+            "completed",
+            "failed",
+            "cancelled"
+          ],
+          "description": "Run status."
+        },
+        "from": {
+          "type": "string",
+          "x-immutable": true,
+          "description": "(Immutable) Inclusive start date (`YYYY-MM-DD`, UTC)."
+        },
+        "to": {
+          "type": "string",
+          "x-immutable": true,
+          "description": "(Immutable) Inclusive end date (`YYYY-MM-DD`, UTC)."
+        },
+        "dryRun": {
+          "type": "boolean",
+          "x-immutable": true,
+          "description": "(Immutable) When true, rollup writes are skipped \u2014 only source counts are returned for diffing."
+        },
+        "processedDates": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Ordered list of `YYYY-MM-DD` dates already processed by this run."
+        },
+        "errors": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "date": {
+                "type": "string",
+                "description": "`YYYY-MM-DD` date that failed."
+              },
+              "message": {
+                "type": "string",
+                "description": "Error message captured at failure."
+              },
+              "at": {
+                "$ref": "#/definitions/firestore-timestamp",
+                "description": "When the error occurred."
+              }
+            },
+            "required": [
+              "date",
+              "message",
+              "at"
+            ],
+            "additionalProperties": false
+          },
+          "description": "Per-date errors collected during the run."
+        },
+        "triggeredBy": {
+          "type": "string",
+          "x-immutable": true,
+          "description": "(Immutable) UID of the admin who triggered the backfill."
+        },
+        "startedAt": {
+          "$ref": "#/definitions/firestore-timestamp",
+          "description": "(Read-only) When the run actually started.",
+          "readOnly": true
+        },
+        "completedAt": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/firestore-timestamp"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "readOnly": true,
+          "description": "(Read-only) When the run reached a terminal status."
+        }
+      },
+      "required": [
+        "companyId",
+        "siteId",
+        "status",
+        "from",
+        "to",
+        "dryRun",
+        "processedDates",
+        "errors",
+        "triggeredBy",
+        "startedAt"
+      ],
+      "additionalProperties": false,
+      "description": "AnalyticsBackfill run (D42 / ING-304). Collection: companies/{companyId}/sites/{siteId}/analytics_backfills/{runId}. Tracks admin-triggered rollup backfill jobs; supports dry-run.",
+      "example": {
+        "id": null,
+        "companyId": "comp_xyz789",
+        "siteId": "sit_ref123",
+        "status": "pending",
+        "from": "from",
+        "to": "to",
+        "dryRun": true,
+        "processedDates": [
+          "example"
+        ],
+        "errors": [
+          {
+            "date": "2026-02-15",
+            "message": "message",
+            "at": "at"
+          }
+        ],
+        "triggeredBy": "triggeredBy",
+        "startedAt": "startedAt",
+        "completedAt": "completedAt"
+      }
+    },
+    "analytics-daily": {
+      "type": "object",
+      "properties": {
+        "totalEvents": {
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991,
+          "description": "Total event count within the bucket."
+        },
+        "pageViews": {
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991,
+          "description": "Count of `page_view` + `screen_view` events."
+        },
+        "sessions": {
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991,
+          "description": "Distinct session count within the bucket (by `sessionId`)."
+        },
+        "uniqueUsers": {
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991,
+          "description": "Distinct identified `userId` count. Anonymous sessions (userId=null) are excluded."
+        },
+        "anonymousSessions": {
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991,
+          "description": "Distinct session count where `userId` was null for the entire session."
+        },
+        "orders": {
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991,
+          "description": "Count of `order_submitted` events (or Order documents scoped to this site, D43) within the bucket."
+        },
+        "paymentsCompleted": {
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991,
+          "description": "Count of `payment_completed` events within the bucket."
+        },
+        "paymentsFailed": {
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991,
+          "description": "Count of `payment_failed` events within the bucket."
+        },
+        "errors": {
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991,
+          "description": "Count of `error_occurred` + `exception_caught` events within the bucket."
+        },
+        "eventCounts": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {
+            "type": "integer",
+            "minimum": -9007199254740991,
+            "maximum": 9007199254740991
+          },
+          "description": "Per-event-name counts \u2014 key is the event name (canonical or custom), value is the count within the bucket."
+        },
+        "id": {
+          "readOnly": true,
+          "description": "(Read-only) Firestore document ID = `YYYY-MM-DD`.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "companyId": {
+          "type": "string",
+          "x-immutable": true,
+          "description": "(Immutable) FK \u2192 Company document ID."
+        },
+        "siteId": {
+          "type": "string",
+          "x-immutable": true,
+          "description": "(Immutable) FK \u2192 Site document ID (D40)."
+        },
+        "date": {
+          "type": "string",
+          "x-immutable": true,
+          "description": "(Immutable) `YYYY-MM-DD` UTC \u2014 matches document ID."
+        },
+        "computedAt": {
+          "$ref": "#/definitions/firestore-timestamp",
+          "description": "(Read-only) When this rollup was last (re)computed. Updated on every set/merge.",
+          "readOnly": true
+        },
+        "sourceEventCount": {
+          "readOnly": true,
+          "description": "(Read-only, Optional) Total source events scanned when producing this rollup. Useful for dry-run diffing.",
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991
+        }
+      },
+      "required": [
+        "totalEvents",
+        "pageViews",
+        "sessions",
+        "uniqueUsers",
+        "anonymousSessions",
+        "orders",
+        "paymentsCompleted",
+        "paymentsFailed",
+        "errors",
+        "eventCounts",
+        "companyId",
+        "siteId",
+        "date",
+        "computedAt"
+      ],
+      "additionalProperties": false,
+      "description": "AnalyticsDaily rollup (D42 / ING-304). Collection: companies/{companyId}/sites/{siteId}/analytics_daily/{YYYY-MM-DD}. Idempotent set/merge \u2014 reruns overwrite. Fall back to raw analytics_events for uncovered slices.",
+      "example": {
+        "totalEvents": 0,
+        "pageViews": 0,
+        "sessions": 0,
+        "uniqueUsers": 0,
+        "anonymousSessions": 0,
+        "orders": 0,
+        "paymentsCompleted": 0,
+        "paymentsFailed": 0,
+        "errors": 0,
+        "eventCounts": {},
+        "id": null,
+        "companyId": "comp_xyz789",
+        "siteId": "sit_ref123",
+        "date": "2026-02-15",
+        "computedAt": "computedAt",
+        "sourceEventCount": null
+      }
+    },
     "analytics-event": {
       "type": "object",
       "properties": {
@@ -277,50 +563,204 @@
         "userTraits": null
       }
     },
-    "attention-status": {
-      "type": "string",
-      "enum": [
-        "ACTIVE",
-        "STALE",
-        "ON_HOLD",
-        "ESCALATED"
-      ],
-      "description": "Operational attention status for Order and Booking (D39). Controls home-page queue assignment. Server-owned \u2014 set via triggers or callable fn only.",
-      "x-note": "ACTIVE = normal urgent queue (default). STALE = idle past threshold, moved to review queue \u2014 excluded from pendingOrdersCount. ON_HOLD = intentionally paused by manager via callable fn. ESCALATED = ignored past second threshold.",
-      "x-see": {
-        "decisions": [
-          "D39"
-        ]
-      },
-      "x-when": "Set by server automation or callable fn. Mobile and Dashboard read this field; never write it directly. ON_HOLD is the only human-initiated transition \u2014 goes through a dedicated callable function.",
-      "x-status": "proposed"
-    },
-    "booking": {
+    "analytics-hourly": {
       "type": "object",
       "properties": {
-        "id": {
-          "type": "string",
-          "readOnly": true,
-          "description": "(Read-only) Firestore document ID."
+        "totalEvents": {
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991,
+          "description": "Total event count within the bucket."
         },
-        "uid": {
-          "type": "string",
-          "readOnly": true,
-          "description": "(Read-only) Entity UID. Often mirrors id."
+        "pageViews": {
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991,
+          "description": "Count of `page_view` + `screen_view` events."
         },
-        "companyId": {
-          "x-immutable": true,
-          "description": "(Immutable) FK \u2192 Company document ID. Note: optional in current schema \u2014 should be required (see ID consistency audit).",
+        "sessions": {
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991,
+          "description": "Distinct session count within the bucket (by `sessionId`)."
+        },
+        "uniqueUsers": {
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991,
+          "description": "Distinct identified `userId` count. Anonymous sessions (userId=null) are excluded."
+        },
+        "anonymousSessions": {
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991,
+          "description": "Distinct session count where `userId` was null for the entire session."
+        },
+        "orders": {
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991,
+          "description": "Count of `order_submitted` events (or Order documents scoped to this site, D43) within the bucket."
+        },
+        "paymentsCompleted": {
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991,
+          "description": "Count of `payment_completed` events within the bucket."
+        },
+        "paymentsFailed": {
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991,
+          "description": "Count of `payment_failed` events within the bucket."
+        },
+        "errors": {
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991,
+          "description": "Count of `error_occurred` + `exception_caught` events within the bucket."
+        },
+        "eventCounts": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {
+            "type": "integer",
+            "minimum": -9007199254740991,
+            "maximum": 9007199254740991
+          },
+          "description": "Per-event-name counts \u2014 key is the event name (canonical or custom), value is the count within the bucket."
+        },
+        "id": {
+          "readOnly": true,
+          "description": "(Read-only) Firestore document ID = `YYYY-MM-DD-HH`.",
           "type": [
             "string",
             "null"
           ]
         },
-        "status": {
-          "$ref": "#/definitions/booking-status",
-          "description": "Booking lifecycle status. COMPLETED_MIXED = some sessions completed, others cancelled/no-show."
-        },
-        "totalAmount": {
+        "companyId": {
+          "type": "string",
+          "x-immutable": true,
+          "description": "(Immutable) FK \u2192 Company document ID."
+        },
+        "siteId": {
+          "type": "string",
+          "x-immutable": true,
+          "description": "(Immutable) FK \u2192 Site document ID (D40)."
+        },
+        "date": {
+          "type": "string",
+          "x-immutable": true,
+          "description": "(Immutable) `YYYY-MM-DD` UTC for the bucket day."
+        },
+        "hour": {
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991,
+          "x-immutable": true,
+          "description": "(Immutable) UTC hour of day, 0\u201323."
+        },
+        "computedAt": {
+          "$ref": "#/definitions/firestore-timestamp",
+          "description": "(Read-only) When this rollup was last (re)computed.",
+          "readOnly": true
+        },
+        "sourceEventCount": {
+          "readOnly": true,
+          "description": "(Read-only, Optional) Total source events scanned when producing this rollup.",
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991
+        }
+      },
+      "required": [
+        "totalEvents",
+        "pageViews",
+        "sessions",
+        "uniqueUsers",
+        "anonymousSessions",
+        "orders",
+        "paymentsCompleted",
+        "paymentsFailed",
+        "errors",
+        "eventCounts",
+        "companyId",
+        "siteId",
+        "date",
+        "hour",
+        "computedAt"
+      ],
+      "additionalProperties": false,
+      "description": "AnalyticsHourly rollup (D42 / ING-304). Collection: companies/{companyId}/sites/{siteId}/analytics_hourly/{YYYY-MM-DD-HH}. Scheduled-CF writer; idempotent set/merge.",
+      "example": {
+        "totalEvents": 0,
+        "pageViews": 0,
+        "sessions": 0,
+        "uniqueUsers": 0,
+        "anonymousSessions": 0,
+        "orders": 0,
+        "paymentsCompleted": 0,
+        "paymentsFailed": 0,
+        "errors": 0,
+        "eventCounts": {},
+        "id": null,
+        "companyId": "comp_xyz789",
+        "siteId": "sit_ref123",
+        "date": "2026-02-15",
+        "hour": 0,
+        "computedAt": "computedAt",
+        "sourceEventCount": null
+      }
+    },
+    "attention-status": {
+      "type": "string",
+      "enum": [
+        "ACTIVE",
+        "STALE",
+        "ON_HOLD",
+        "ESCALATED"
+      ],
+      "description": "Operational attention status for Order and Booking (D39). Controls home-page queue assignment. Server-owned \u2014 set via triggers or callable fn only.",
+      "x-note": "ACTIVE = normal urgent queue (default). STALE = idle past threshold, moved to review queue \u2014 excluded from pendingOrdersCount. ON_HOLD = intentionally paused by manager via callable fn. ESCALATED = ignored past second threshold.",
+      "x-see": {
+        "decisions": [
+          "D39"
+        ]
+      },
+      "x-when": "Set by server automation or callable fn. Mobile and Dashboard read this field; never write it directly. ON_HOLD is the only human-initiated transition \u2014 goes through a dedicated callable function.",
+      "x-status": "proposed"
+    },
+    "booking": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "string",
+          "readOnly": true,
+          "description": "(Read-only) Firestore document ID."
+        },
+        "uid": {
+          "type": "string",
+          "readOnly": true,
+          "description": "(Read-only) Entity UID. Often mirrors id."
+        },
+        "companyId": {
+          "x-immutable": true,
+          "description": "(Immutable) FK \u2192 Company document ID. Note: optional in current schema \u2014 should be required (see ID consistency audit).",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "status": {
+          "$ref": "#/definitions/booking-status",
+          "description": "Booking lifecycle status. COMPLETED_MIXED = some sessions completed, others cancelled/no-show."
+        },
+        "totalAmount": {
           "type": "number",
           "x-note": "Booking uses `totalAmount`; Order uses `amount` for the equivalent field (D05 locked `amount` as canonical for orders). Pending cross-model alignment.",
           "x-see": {
@@ -1624,6 +2064,24 @@
       ],
       "description": "Fulfillment channel for an order. Determines whether the customer comes to the business (ON_SITE), collects their order themselves (PICK_UP), or receives a physical delivery (DELIVERY). Drives whether fulfillmentStatus is relevant."
     },
+    "deployment-link-type": {
+      "type": "string",
+      "enum": [
+        "web",
+        "mobile",
+        "pwa",
+        "app-store",
+        "play-store",
+        "other"
+      ],
+      "description": "Category of a Site deployment link (D41). Used for UI icon/labelling and deep-link handling.",
+      "x-note": "Lowercase by convention \u2014 deployment link types are display-oriented labels, not lifecycle states.",
+      "x-see": {
+        "decisions": [
+          "D41"
+        ]
+      }
+    },
     "event": {
       "type": "object",
       "properties": {
@@ -3037,6 +3495,21 @@
           "x-immutable": true,
           "description": "(Immutable) FK \u2192 Company document ID. Scopes all queries."
         },
+        "siteId": {
+          "x-immutable": true,
+          "x-note": "D43 / ADR-003: optional site attribution. Absent/null means company-wide (legacy). When set, the order is attributed to a specific site for analytics and site-scoped dashboards. No migration \u2014 existing orders keep null. Flat path; Order continues to live at `companies/{companyId}/orders/{orderId}`.",
+          "x-see": {
+            "decisions": [
+              "D43"
+            ]
+          },
+          "x-when": "Set at order creation when the client knows which site the order originated from (e.g. SR Single, Lifesense). Leave null for legacy/company-wide orders. Composite index: (companyId, siteId, createdAt).",
+          "description": "(Immutable, Optional) FK \u2192 Site document ID (D43 / ADR-003). null = company-wide.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
         "orderNumber": {
           "type": "string",
           "readOnly": true,
@@ -3626,6 +4099,7 @@
         "id": "bk_abc123def456",
         "uid": "user_u8x92kqm",
         "companyId": "comp_xyz789",
+        "siteId": null,
         "orderNumber": "ORD-2026-0042",
         "status": "status",
         "paymentStatus": "paymentStatus",
@@ -4121,7 +4595,7 @@
       ],
       "description": "Per-date/per-slot booking session status (D19). Dashboard is sole writer; Mobile is read-only."
     },
-    "site-payment": {
+    "site": {
       "type": "object",
       "properties": {
         "id": {
@@ -4135,69 +4609,767 @@
         "companyId": {
           "type": "string",
           "x-immutable": true,
-          "description": "(Immutable) FK \u2192 Company document ID."
+          "description": "(Immutable) FK \u2192 Company document ID. Scopes all site sub-collections."
         },
-        "siteId": {
+        "name": {
           "type": "string",
-          "x-immutable": true,
-          "description": "(Immutable) FK \u2192 Site document ID (D40 sub-tenant scope)."
+          "description": "Human-readable site name shown in dashboards."
         },
-        "contact": {
-          "type": "string",
-          "description": "Email or E.164 phone number. Matches AllowedUser.contact."
+        "description": {
+          "description": "Optional freeform description.",
+          "type": [
+            "string",
+            "null"
+          ]
         },
-        "sessionId": {
-          "type": "string",
-          "description": "Payment provider checkout session ID (e.g. Wave). Usable for dedup across dual writes."
+        "status": {
+          "$ref": "#/definitions/site-status",
+          "description": "Lifecycle status (D41). 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.",
+          "x-see": {
+            "decisions": [
+              "D41"
+            ]
+          },
+          "x-when": "Written by operators via dashboard or by server triggers (expiration). Clients filter by ACTIVE."
         },
-        "transactionId": {
-          "type": "string",
-          "description": "Payment provider transaction ID."
+        "deploymentLinks": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "label": {
+                "type": "string",
+                "description": "Human-readable label shown in dashboards (e.g. \"Production\", \"Staging\")."
+              },
+              "url": {
+                "type": "string",
+                "description": "Absolute URL or store link."
+              },
+              "type": {
+                "$ref": "#/definitions/deployment-link-type",
+                "description": "Link category \u2014 drives icon/handler selection.",
+                "x-note": "Lowercase by convention \u2014 deployment link types are display-oriented labels, not lifecycle states.",
+                "x-see": {
+                  "decisions": [
+                    "D41"
+                  ]
+                }
+              },
+              "isPrimary": {
+                "description": "If true, this link is used as the canonical deployment URL for the Site.",
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "label",
+              "url",
+              "type"
+            ],
+            "additionalProperties": false,
+            "description": "Deployment link entry embedded on Site.deploymentLinks[] (D41)."
+          },
+          "description": "Ordered list of deployment URLs (web, mobile, PWA, store links)."
         },
-        "tier": {
+        "expiresAt": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/firestore-timestamp"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Optional expiration timestamp. When set and elapsed, `isExpired` flips true and status typically moves to EXPIRED."
+        },
+        "isExpired": {
+          "readOnly": true,
+          "description": "(Read-only) Derived \u2014 true when `expiresAt` is in the past. Maintained by server trigger.",
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "createdAt": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/firestore-timestamp"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "readOnly": true,
+          "description": "(Read-only) Server-generated creation timestamp."
+        },
+        "updatedAt": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/firestore-timestamp"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "readOnly": true,
+          "description": "(Read-only) Server-generated update timestamp."
+        },
+        "createdBy": {
           "type": "string",
-          "description": "Access tier. Free string per site (ING-304 open question)."
+          "x-immutable": true,
+          "description": "(Immutable) FK \u2192 User/staff UID who created the site."
         },
-        "amount": {
-          "type": "number",
-          "description": "Amount paid. Generalized from amount_xof per D40 decision."
+        "analyticsEnabled": {
+          "type": "boolean",
+          "description": "Feature flag \u2014 when false, clients should not emit analytics events for this site."
         },
-        "currency": {
-          "default": "XOF",
-          "description": "Currency code (ISO 4217). Defaults to XOF for legacy SR-Single parity.",
-          "type": "string"
+        "lastAnalyticsSync": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/firestore-timestamp"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "readOnly": true,
+          "description": "(Read-only) Last time the analytics rollup pipeline refreshed `cachedMetrics`."
         },
-        "paidAt": {
-          "$ref": "#/definitions/firestore-timestamp",
-          "description": "RFC3339Nano UTC when payment was completed."
+        "cachedMetrics": {
+          "readOnly": true,
+          "denormalized": true,
+          "x-note": "Updated by the rollup pipeline (D42). Readers should treat this as a hint; authoritative counts live in analytics_daily/analytics_hourly.",
+          "x-see": {
+            "decisions": [
+              "D41",
+              "D42"
+            ]
+          },
+          "description": "(Read-only, Denormalized) Cached metrics snapshot for quick dashboard rendering.",
+          "type": [
+            "object",
+            "null"
+          ],
+          "properties": {
+            "totalEvents": {
+              "type": "integer",
+              "minimum": -9007199254740991,
+              "maximum": 9007199254740991,
+              "description": "All-time event count cached on the Site."
+            },
+            "totalPageViews": {
+              "type": "integer",
+              "minimum": -9007199254740991,
+              "maximum": 9007199254740991,
+              "description": "All-time `page_view` + `screen_view` count."
+            },
+            "totalSessions": {
+              "type": "integer",
+              "minimum": -9007199254740991,
+              "maximum": 9007199254740991,
+              "description": "All-time distinct session count."
+            },
+            "totalOrders": {
+              "type": "integer",
+              "minimum": -9007199254740991,
+              "maximum": 9007199254740991,
+              "description": "All-time order count attributed to this site (via `Order.siteId`, D43)."
+            },
+            "lastEventAt": {
+              "$ref": "#/definitions/firestore-timestamp",
+              "description": "Timestamp of the most recent analytics event seen for this site."
+            }
+          },
+          "required": [
+            "totalEvents",
+            "totalPageViews",
+            "totalSessions",
+            "totalOrders"
+          ],
+          "additionalProperties": false
         }
       },
       "required": [
         "companyId",
-        "siteId",
-        "contact",
-        "sessionId",
-        "transactionId",
-        "tier",
-        "amount",
-        "currency",
-        "paidAt"
+        "name",
+        "status",
+        "deploymentLinks",
+        "createdBy",
+        "analyticsEnabled"
       ],
       "additionalProperties": false,
-      "description": "SitePayment model (D40 / ING-304). Collection: companies/{companyId}/sites/{siteId}/payments/{paymentId}. Immutable append-only transaction ledger. Distinct from AllowedUser (access state) and CustomerPayment (D22 \u2014 customer-level billing).",
+      "description": "Site model (D41 / ING-304). Collection: companies/{companyId}/sites/{siteId}. Per-company product surface. Sub-collections (magic_link_requests, allowed_users, payments, analytics_events, analytics_daily, analytics_hourly, analytics_backfills) live under this document per D40/D42.",
       "example": {
         "id": null,
         "companyId": "comp_xyz789",
-        "siteId": "sit_ref123",
-        "contact": "contact",
-        "sessionId": "ses_ref123",
-        "transactionId": "tra_ref123",
-        "tier": "Gold",
-        "amount": 45000,
+        "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
+      }
+    },
+    "site-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."
+        },
+        "siteId": {
+          "type": "string",
+          "x-immutable": true,
+          "description": "(Immutable) FK \u2192 Site document ID (D40 sub-tenant scope)."
+        },
+        "contact": {
+          "type": "string",
+          "description": "Email or E.164 phone number. Matches AllowedUser.contact."
+        },
+        "sessionId": {
+          "type": "string",
+          "description": "Payment provider checkout session ID (e.g. Wave). Usable for dedup across dual writes."
+        },
+        "transactionId": {
+          "type": "string",
+          "description": "Payment provider transaction ID."
+        },
+        "tier": {
+          "type": "string",
+          "description": "Access tier. Free string per site (ING-304 open question)."
+        },
+        "amount": {
+          "type": "number",
+          "description": "Amount paid. Generalized from amount_xof per D40 decision."
+        },
+        "currency": {
+          "default": "XOF",
+          "description": "Currency code (ISO 4217). Defaults to XOF for legacy SR-Single parity.",
+          "type": "string"
+        },
+        "paidAt": {
+          "$ref": "#/definitions/firestore-timestamp",
+          "description": "RFC3339Nano UTC when payment was completed."
+        }
+      },
+      "required": [
+        "companyId",
+        "siteId",
+        "contact",
+        "sessionId",
+        "transactionId",
+        "tier",
+        "amount",
+        "currency",
+        "paidAt"
+      ],
+      "additionalProperties": false,
+      "description": "SitePayment model (D40 / ING-304). Collection: companies/{companyId}/sites/{siteId}/payments/{paymentId}. Immutable append-only transaction ledger. Distinct from AllowedUser (access state) and CustomerPayment (D22 \u2014 customer-level billing).",
+      "example": {
+        "id": null,
+        "companyId": "comp_xyz789",
+        "siteId": "sit_ref123",
+        "contact": "contact",
+        "sessionId": "ses_ref123",
+        "transactionId": "tra_ref123",
+        "tier": "Gold",
+        "amount": 45000,
         "currency": "XOF",
         "paidAt": "pai_ref123"
       }
     },
+    "site-status": {
+      "type": "string",
+      "enum": [
+        "ACTIVE",
+        "INACTIVE",
+        "EXPIRED",
+        "ARCHIVED"
+      ],
+      "description": "Lifecycle status for a Site (D41). Drives whether the site is reachable and whether analytics/payments flow.",
+      "x-note": "ACTIVE = live and serving traffic. INACTIVE = intentionally disabled by operators. EXPIRED = past expiresAt (derived when isExpired is true; may also be stored explicitly). ARCHIVED = soft-deleted; retained for audit but not listed by default.",
+      "x-see": {
+        "decisions": [
+          "D41"
+        ]
+      },
+      "x-when": "Written by operators via dashboard or by server triggers (expiration). Clients filter by ACTIVE."
+    },
+    "stocktake": {
+      "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. Tenant scope."
+        },
+        "stocktakeNumber": {
+          "type": "string",
+          "description": "Human-readable session number, e.g. \"STK-2026-001\". Embedded as `referenceNumber` on the StockMovement rows the session emits, so the ledger remains traceable to the originating stocktake."
+        },
+        "stocktakeDate": {
+          "$ref": "#/definitions/firestore-timestamp",
+          "description": "Effective date of the count. Distinct from createdAt; can be backdated.",
+          "x-note": "The date the count is FOR. Can be backdated (stocktakeDate < createdAt) \u2014 analytics buckets by stocktakeDate for \"what period was counted\" and by completedAt for \"when adjustments hit the ledger\" (GH#29 Q24)."
+        },
+        "warehouseId": {
+          "description": "FK \u2192 Warehouse document ID. Null = whole-company stocktake (no warehouse partition).",
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "frequency": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/stocktake-frequency"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Recurrence cadence. Optional \u2014 leave unset for ad-hoc sessions, or set to indicate this stocktake is part of a recurring schedule.",
+          "x-note": "Optional today (dashboard does not currently track recurrence). Frequency is a property of the record, not a separate type \u2014 a daily stocktake is a Stocktake with frequency=DAILY, not a distinct DailyStocktake model. If the session was emitted from a recurring schedule, set Stocktake.scheduledStocktakeId; ad-hoc sessions leave it null.",
+          "x-see": {
+            "issues": [
+              "gh#29"
+            ]
+          }
+        },
+        "scheduledStocktakeId": {
+          "description": "FK to a recurring stocktake schedule, if this session was emitted from one. Null for ad-hoc sessions.",
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "status": {
+          "$ref": "#/definitions/stocktake-status",
+          "description": "Lifecycle status. Transitions PENDING \u2192 IN_PROGRESS \u2192 COMPLETED are server-owned (GH#29 \u00a73 / Q25).",
+          "x-note": "PENDING = session created, no items counted yet. IN_PROGRESS = at least one item has been counted. COMPLETED = all items counted and the session was closed; on this transition the server emits one StockMovement(type=INVENTORY) per non-zero delta. CANCELLED = session abandoned without applying adjustments. Status transitions PENDING \u2192 IN_PROGRESS \u2192 COMPLETED are server-owned (Q25) \u2014 clients PATCH item status; the server transitions session status to avoid the concurrent-edit race documented in stockService.ts:1671.",
+          "x-see": {
+            "issues": [
+              "gh#29"
+            ]
+          },
+          "x-when": "Server-managed. Clients write item updates; the trigger transitions session status."
+        },
+        "adjustmentsApplied": {
+          "type": "boolean",
+          "x-note": "Records whether the COMPLETED transition actually mutated stock or was record-only. The dashboard's completeInventory(applyAdjustments) flag was not persisted; this field closes that gap (GH#29 audit Q22).",
+          "description": "True if completing the session actually emitted StockMovement adjustments. False for record-only counts."
+        },
+        "notes": {
+          "description": "Free-text session-level notes.",
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "totalItemsCount": {
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991,
+          "readOnly": true,
+          "x-note": "Server-derived. Recomputed by trigger on each StocktakeItem write; not safe to write client-side under concurrent edits (GH#29 audit Q23).",
+          "description": "(Read-only) Total number of StocktakeItem rows under this session."
+        },
+        "totalDiscrepancies": {
+          "type": "integer",
+          "minimum": -9007199254740991,
+          "maximum": 9007199254740991,
+          "readOnly": true,
+          "x-note": "Server-derived = sum of |item.delta| across COUNTED items. Updated by trigger.",
+          "description": "(Read-only) Sum of absolute deltas across counted items."
+        },
+        "totalDeltaValue": {
+          "type": "number",
+          "readOnly": true,
+          "x-note": "Server-derived = sum of (item.delta \u00d7 item.costPerUnit) across COUNTED items, in XOF integer minor units (D18). Updated by trigger.",
+          "description": "(Read-only) Net valuation impact of the count, in XOF integer minor units."
+        },
+        "startedAt": {
+          "$ref": "#/definitions/firestore-timestamp",
+          "description": "When the counting session physically opened. Typically equal to createdAt for ad-hoc sessions."
+        },
+        "completedAt": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/firestore-timestamp"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "readOnly": true,
+          "x-note": "Server-set on transition to COMPLETED. Distinct from stocktakeDate (the period counted) \u2014 analytics buckets by completedAt to answer \"when did the ledger hit?\".",
+          "description": "(Read-only) When the session transitioned to COMPLETED."
+        },
+        "createdAt": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/firestore-timestamp"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "readOnly": true,
+          "description": "(Read-only) Server-generated creation timestamp."
+        },
+        "createdBy": {
+          "type": "string",
+          "x-immutable": true,
+          "description": "(Immutable) FK \u2192 User UID who created the session."
+        },
+        "createdByName": {
+          "type": "string",
+          "denormalized": true,
+          "x-note": "Read-time hint snapshot of the creator's display name (GH#29 \u00a73 / Q10).",
+          "description": "(Denormalized) Snapshot of the creator's display name at session creation."
+        },
+        "completedBy": {
+          "readOnly": true,
+          "description": "(Read-only) FK \u2192 User UID who completed the session, set by server on COMPLETED.",
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "completedByName": {
+          "denormalized": true,
+          "x-note": "Read-time hint snapshot of the completer's display name (GH#29 \u00a73 / Q10).",
+          "description": "(Denormalized) Snapshot of the completer's display name.",
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "updatedAt": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/firestore-timestamp"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "readOnly": true,
+          "description": "(Read-only) Server-generated update timestamp."
+        }
+      },
+      "required": [
+        "companyId",
+        "stocktakeNumber",
+        "stocktakeDate",
+        "status",
+        "adjustmentsApplied",
+        "totalItemsCount",
+        "totalDiscrepancies",
+        "totalDeltaValue",
+        "startedAt",
+        "createdBy",
+        "createdByName"
+      ],
+      "additionalProperties": false,
+      "description": "Stocktake (GH#29 \u00a74). Collection: companies/{companyId}/stocktakes/{stocktakeId}. A recorded session of physically counting all SKUs at a point in time. Replaces the dashboard's Inventory model; items live in a sub-collection (replaces InventoryItem[] embedded array); InventoryEvolution is dropped \u2014 derivable from the sub-collection. Status transitions and aggregate fields (totalItemsCount/Discrepancies/totalDeltaValue) are server-owned per GH#29 \u00a73.",
+      "example": {
+        "id": null,
+        "companyId": "comp_xyz789",
+        "stocktakeNumber": "stocktakeNumber",
+        "stocktakeDate": "stocktakeDate",
+        "warehouseId": "war_ref123",
+        "frequency": "frequency",
+        "scheduledStocktakeId": "sch_ref123",
+        "status": "status",
+        "adjustmentsApplied": true,
+        "notes": "VIP customer, handle with care",
+        "totalItemsCount": 2,
+        "totalDiscrepancies": 0,
+        "totalDeltaValue": 0,
+        "startedAt": "startedAt",
+        "completedAt": "completedAt",
+        "createdAt": "createdAt",
+        "createdBy": "staff_k0f1",
+        "createdByName": "Kofi Mensah",
+        "completedBy": "completedBy",
+        "completedByName": "completedByName",
+        "updatedAt": "updatedAt"
+      }
+    },
+    "stocktake-frequency": {
+      "type": "string",
+      "enum": [
+        "DAILY",
+        "WEEKLY",
+        "MONTHLY",
+        "AD_HOC"
+      ],
+      "description": "Recurrence cadence of a Stocktake session (GH#29 \u00a74).",
+      "x-note": "Optional today (dashboard does not currently track recurrence). Frequency is a property of the record, not a separate type \u2014 a daily stocktake is a Stocktake with frequency=DAILY, not a distinct DailyStocktake model. If the session was emitted from a recurring schedule, set Stocktake.scheduledStocktakeId; ad-hoc sessions leave it null.",
+      "x-see": {
+        "issues": [
+          "gh#29"
+        ]
+      }
+    },
+    "stocktake-item": {
+      "type": "object",
+      "properties": {
+        "stockItemId": {
+          "type": "string",
+          "description": "FK \u2192 StockItem document ID. Doubles as the item document ID."
+        },
+        "stockItemName": {
+          "type": "string",
+          "denormalized": true,
+          "x-note": "Read-time hint snapshot of StockItem.name. Authoritative value lives at the StockItem record; do not refresh on rename \u2014 the historical name at session time is what the auditor wrote (GH#29 \u00a73 / Q10).",
+          "description": "(Denormalized) Snapshot of StockItem.name at session time."
+        },
+        "theoreticalQuantity": {
+          "type": "number",
+          "x-immutable": true,
+          "description": "(Immutable) System belief at session start, snapshotted when this item row was created."
+        },
+        "actualQuantity": {
+          "description": "Physical count entered by the counter. Null until counted; set when the line moves to status COUNTED.",
+          "anyOf": [
+            {
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "delta": {
+          "type": "number",
+          "readOnly": true,
+          "x-note": "Server-derived = actualQuantity \u2212 theoreticalQuantity. Recomputed on every actualQuantity write; null/zero before counting.",
+          "description": "(Read-only) Signed difference between actual and theoretical. Drives the StockMovement(type=INVENTORY) emitted on session COMPLETED."
+        },
+        "unit": {
+          "type": "string",
+          "x-immutable": true,
+          "description": "(Immutable) Snapshot of StockItem.unit at session start. Locks the unit against later catalog changes."
+        },
+        "costPerUnit": {
+          "type": "number",
+          "x-immutable": true,
+          "x-note": "Snapshot at session time \u2014 locks valuation against future cost changes. Lock to XOF integer minor units per D18 (GH#29 Q16).",
+          "description": "(Immutable) Snapshot of StockItem.costPerUnit at session start, in XOF integer minor units."
+        },
+        "totalValue": {
+          "type": "number",
+          "readOnly": true,
+          "x-note": "Server-derived = actualQuantity \u00d7 costPerUnit. Recomputed when actualQuantity is written.",
+          "description": "(Read-only) Per-line valuation in XOF integer minor units."
+        },
+        "status": {
+          "$ref": "#/definitions/stocktake-item-status",
+          "description": "Per-line workflow status. Server transitions ADJUSTED on parent COMPLETED.",
+          "x-note": "PENDING = line not yet counted. COUNTED = a counter recorded actualQuantity. VERIFIED = a second pair of eyes signed off (verifiedBy fields populated; Q21 \u2014 kept nullable until tenants opt into stricter QA via policy). ADJUSTED = the resulting StockMovement was emitted (server-set on Stocktake.status \u2192 COMPLETED).",
+          "x-see": {
+            "issues": [
+              "gh#29"
+            ]
+          }
+        },
+        "notes": {
+          "description": "Optional per-line note from the counter (e.g. \"damaged carton, 3 unsellable\").",
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "countedBy": {
+          "description": "UID of the staff member who entered actualQuantity.",
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "countedByName": {
+          "denormalized": true,
+          "x-note": "Read-time hint snapshot of the counter's display name (GH#29 \u00a73 / Q10).",
+          "description": "(Denormalized) Snapshot of the counter's display name at count time.",
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "countedAt": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/firestore-timestamp"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "When the line was counted."
+        },
+        "verifiedBy": {
+          "description": "UID of a second staff member who verified the count. Nullable per GH#29 Q21.",
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "verifiedByName": {
+          "denormalized": true,
+          "x-note": "Read-time hint snapshot of the verifier's display name (GH#29 \u00a73 / Q10).",
+          "description": "(Denormalized) Snapshot of the verifier's display name.",
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "verifiedAt": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/firestore-timestamp"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "When the line was verified, if a second-eye flow was used."
+        }
+      },
+      "required": [
+        "stockItemId",
+        "stockItemName",
+        "theoreticalQuantity",
+        "delta",
+        "unit",
+        "costPerUnit",
+        "totalValue",
+        "status"
+      ],
+      "additionalProperties": false,
+      "description": "StocktakeItem (GH#29 \u00a74). Sub-collection path: companies/{companyId}/stocktakes/{stocktakeId}/items/{stockItemId}. Replaces the embedded `InventoryItem[]` array on the dashboard model. Server emits one StockMovement(type=INVENTORY) per non-zero delta when the parent Stocktake transitions to COMPLETED.",
+      "example": {
+        "stockItemId": "sto_ref123",
+        "stockItemName": "stockItemName",
+        "theoreticalQuantity": 2,
+        "actualQuantity": "actualQuantity",
+        "delta": 0,
+        "unit": "unit",
+        "costPerUnit": 15000,
+        "totalValue": 0,
+        "status": "status",
+        "notes": "VIP customer, handle with care",
+        "countedBy": "countedBy",
+        "countedByName": "countedByName",
+        "countedAt": "countedAt",
+        "verifiedBy": "verifiedBy",
+        "verifiedByName": "verifiedByName",
+        "verifiedAt": "verifiedAt"
+      }
+    },
+    "stocktake-item-status": {
+      "type": "string",
+      "enum": [
+        "PENDING",
+        "COUNTED",
+        "VERIFIED",
+        "ADJUSTED"
+      ],
+      "description": "Per-line workflow status inside a Stocktake (GH#29 \u00a74, audit Q21).",
+      "x-note": "PENDING = line not yet counted. COUNTED = a counter recorded actualQuantity. VERIFIED = a second pair of eyes signed off (verifiedBy fields populated; Q21 \u2014 kept nullable until tenants opt into stricter QA via policy). ADJUSTED = the resulting StockMovement was emitted (server-set on Stocktake.status \u2192 COMPLETED).",
+      "x-see": {
+        "issues": [
+          "gh#29"
+        ]
+      }
+    },
+    "stocktake-status": {
+      "type": "string",
+      "enum": [
+        "PENDING",
+        "IN_PROGRESS",
+        "COMPLETED",
+        "CANCELLED"
+      ],
+      "description": "Lifecycle status of a Stocktake session (GH#29 \u00a73, \u00a74).",
+      "x-note": "PENDING = session created, no items counted yet. IN_PROGRESS = at least one item has been counted. COMPLETED = all items counted and the session was closed; on this transition the server emits one StockMovement(type=INVENTORY) per non-zero delta. CANCELLED = session abandoned without applying adjustments. Status transitions PENDING \u2192 IN_PROGRESS \u2192 COMPLETED are server-owned (Q25) \u2014 clients PATCH item status; the server transitions session status to avoid the concurrent-edit race documented in stockService.ts:1671.",
+      "x-see": {
+        "issues": [
+          "gh#29"
+        ]
+      },
+      "x-when": "Server-managed. Clients write item updates; the trigger transitions session status."
+    },
     "ticket": {
       "type": "object",
       "properties": {