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

package/data/docs/models/analytics-backfill.md

@@ -391,7 +391,7 @@ Do not include in write requests. This field is set exclusively by the server (F
 | **Required** | No     |
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 12:42:50 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 13:38:44 +0000
 
 :::warning Server-set
 Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.

package/data/docs/models/analytics-daily.md

@@ -344,7 +344,7 @@ Do not include in write requests. This field is set exclusively by the server (F
 | **Maximum**  | ≤ 9007199254740991  |
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 12:42:50 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 13:38:44 +0000
 
 :::warning Server-set
 Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.

package/data/docs/models/analytics-event.md

@@ -530,4 +530,4 @@ Must be one of:
 | **Additional properties** | Any type allowed |
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 12:42:50 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 13:38:44 +0000

package/data/docs/models/analytics-hourly.md

@@ -365,7 +365,7 @@ Do not include in write requests. This field is set exclusively by the server (F
 | **Maximum**  | ≤ 9007199254740991  |
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 12:42:50 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 13:38:44 +0000
 
 :::warning Server-set
 Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.

package/data/docs/models/app-payment.md

@@ -197,4 +197,4 @@ Set at creation only. This field cannot be modified after the document is create
 | **Maximum**  | ≤ 9007199254740991  |
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 12:42:50 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 13:38:44 +0000

package/data/docs/models/app.md

@@ -42,6 +42,8 @@ sidebar_position: 6
 - [3. Property `name`](#name)
 - [4. Property `description`](#description)
 - [5. Property `status`](#status)
+  - [5.1. Property `app-status`](#status_anyOf_i0)
+  - [5.2. Property `item 1`](#status_anyOf_i1)
 - [6. Property `deploymentLinks`](#deploymentLinks)
   - [6.1. deploymentLinks items](#deploymentLinks_items)
     - [6.1.1. Property `label`](#deploymentLinks_items_label)
@@ -81,22 +83,22 @@ sidebar_position: 6
 
 **Description:** App model (D41 / ING-304). Collection: companies/\{companyId\}/apps/\{appId\}. Per-company product surface. Sub-collections (magic_link_requests, allowed_users, payments, analytics_events, analytics_daily, analytics_hourly, analytics_backfills) live under this document per D40/D42.
 
-| Property                                   | Pattern | Type             | Deprecated | Definition                  | Title/Description                                                                                                    |
-| ------------------------------------------ | ------- | ---------------- | ---------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| - [id](#id )                               | No      | string or null   | No         | -                           | (Read-only) Firestore document ID, auto-generated.                                                                   |
-| + [companyId](#companyId )                 | No      | string           | No         | -                           | (Immutable) FK → Company document ID. Scopes all app sub-collections.                                                |
-| + [name](#name )                           | No      | string           | No         | -                           | Human-readable app name shown in dashboards.                                                                         |
-| - [description](#description )             | No      | string or null   | No         | -                           | Optional freeform description.                                                                                       |
-| + [status](#status )                       | No      | enum (of string) | No         | In #/definitions/app-status | Lifecycle status (D41/D44). Clients filter by ACTIVE.                                                                |
-| + [deploymentLinks](#deploymentLinks )     | No      | array of object  | No         | -                           | Ordered list of deployment URLs (web, mobile, PWA, store links).                                                     |
-| - [expiresAt](#expiresAt )                 | No      | Combination      | No         | -                           | Optional expiration timestamp. When set and elapsed, \`isExpired\` flips true and status typically moves to EXPIRED. |
-| - [isExpired](#isExpired )                 | No      | boolean or null  | No         | -                           | (Read-only) Derived — true when \`expiresAt\` is in the past. Maintained by server trigger.                          |
-| - [createdAt](#createdAt )                 | No      | Combination      | No         | -                           | (Read-only) Server-generated creation timestamp.                                                                     |
-| - [updatedAt](#updatedAt )                 | No      | Combination      | No         | -                           | (Read-only) Server-generated update timestamp.                                                                       |
-| + [createdBy](#createdBy )                 | No      | string           | No         | -                           | (Immutable) FK → User/staff UID who created the app.                                                                 |
-| + [analyticsEnabled](#analyticsEnabled )   | No      | boolean          | No         | -                           | Feature flag — when false, clients should not emit analytics events for this app.                                    |
-| - [lastAnalyticsSync](#lastAnalyticsSync ) | No      | Combination      | No         | -                           | (Read-only) Last time the analytics rollup pipeline refreshed \`cachedMetrics\`.                                     |
-| - [cachedMetrics](#cachedMetrics )         | No      | object or null   | No         | -                           | (Read-only, Denormalized) Cached metrics snapshot for quick dashboard rendering.                                     |
+| Property                                   | Pattern | Type            | Deprecated | Definition | Title/Description                                                                                                                       |
+| ------------------------------------------ | ------- | --------------- | ---------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| - [id](#id )                               | No      | string or null  | No         | -          | (Read-only) Firestore document ID, auto-generated.                                                                                      |
+| + [companyId](#companyId )                 | No      | string          | No         | -          | (Immutable) FK → Company document ID. Scopes all app sub-collections.                                                                   |
+| + [name](#name )                           | No      | string          | No         | -          | Human-readable app name shown in dashboards.                                                                                            |
+| - [description](#description )             | No      | string or null  | No         | -          | Optional freeform description.                                                                                                          |
+| - [status](#status )                       | No      | Combination     | No         | -          | Lifecycle status (D41/D44). Optional pending backfill of pre-existing records (#26) — treat absent as ACTIVE. Clients filter by ACTIVE. |
+| + [deploymentLinks](#deploymentLinks )     | No      | array of object | No         | -          | Ordered list of deployment URLs (web, mobile, PWA, store links).                                                                        |
+| - [expiresAt](#expiresAt )                 | No      | Combination     | No         | -          | Optional expiration timestamp. When set and elapsed, \`isExpired\` flips true and status typically moves to EXPIRED.                    |
+| - [isExpired](#isExpired )                 | No      | boolean or null | No         | -          | (Read-only) Derived — true when \`expiresAt\` is in the past. Maintained by server trigger.                                             |
+| - [createdAt](#createdAt )                 | No      | Combination     | No         | -          | (Read-only) Server-generated creation timestamp.                                                                                        |
+| - [updatedAt](#updatedAt )                 | No      | Combination     | No         | -          | (Read-only) Server-generated update timestamp.                                                                                          |
+| + [createdBy](#createdBy )                 | No      | string          | No         | -          | (Immutable) FK → User/staff UID who created the app.                                                                                    |
+| + [analyticsEnabled](#analyticsEnabled )   | No      | boolean         | No         | -          | Feature flag — when false, clients should not emit analytics events for this app.                                                       |
+| - [lastAnalyticsSync](#lastAnalyticsSync ) | No      | Combination     | No         | -          | (Read-only) Last time the analytics rollup pipeline refreshed \`cachedMetrics\`.                                                        |
+| - [cachedMetrics](#cachedMetrics )         | No      | object or null  | No         | -          | (Read-only, Denormalized) Cached metrics snapshot for quick dashboard rendering.                                                        |
 
 ## <a name="id"></a>1. Property `id`
 
@@ -144,13 +146,28 @@ Set at creation only. This field cannot be modified after the document is create
 
 ## <a name="status"></a>5. Property `status`
 
+|                           |                  |
+| ------------------------- | ---------------- |
+| **Type**                  | `combining`      |
+| **Required**              | No               |
+| **Additional properties** | Any type allowed |
+
+**Description:** Lifecycle status (D41/D44). Optional pending backfill of pre-existing records (#26) — treat absent as ACTIVE. Clients filter by ACTIVE.
+
+| Any of(Option)                 |
+| ------------------------------ |
+| [app-status](#status_anyOf_i0) |
+| [item 1](#status_anyOf_i1)     |
+
+### <a name="status_anyOf_i0"></a>5.1. Property `app-status`
+
 |                |                          |
 | -------------- | ------------------------ |
 | **Type**       | `enum (of string)`       |
-| **Required**   | Yes                      |
+| **Required**   | No                       |
 | **Defined in** | #/definitions/app-status |
 
-**Description:** Lifecycle status (D41/D44). Clients filter by ACTIVE.
+**Description:** Lifecycle status for an App (formerly Site — renamed per decision #40 / D44). Drives whether the app is reachable and whether analytics/payments flow.
 
 Must be one of:
 * "ACTIVE"
@@ -158,12 +175,19 @@ Must be one of:
 * "EXPIRED"
 * "ARCHIVED"
 
+### <a name="status_anyOf_i1"></a>5.2. Property `item 1`
+
+|              |        |
+| ------------ | ------ |
+| **Type**     | `null` |
+| **Required** | No     |
+
 :::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.
+Real Firestore documents may be missing this field on pre-backfill records (#26). Treat absent as ACTIVE. A backfill script will populate status=ACTIVE on all existing documents; once confirmed, this field will be promoted to required.
 :::
 
 :::tip When to set
-Written by operators via dashboard or by server triggers (expiration). Clients filter by ACTIVE.
+Written by operators via dashboard or by server triggers (expiration). Clients must not use server-side `where(status == ACTIVE)` until backfill is complete — filter client-side instead, treating absent as ACTIVE.
 :::
 
 :::info See also
@@ -546,7 +570,7 @@ Do not include in write requests. This field is set exclusively by the server (F
 **Description:** Timestamp of the most recent analytics event seen for this app.
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 12:42:50 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 13:38:44 +0000
 
 :::warning Server-set
 Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.

package/data/docs/models/booking-version.md

@@ -270,7 +270,7 @@ Dot-notation paths for nested fields (e.g. "bookingDates.0.status"). Populated b
 | **Additional properties** | Any type allowed |
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 12:42:51 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 13:38:45 +0000
 
 :::warning Server-set
 Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.

package/data/docs/models/booking.md

@@ -1739,7 +1739,7 @@ Set at creation only. This field cannot be modified after the document is create
 **Description:** When true, suppresses Firebase notification triggers (D20/IG-8).
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 12:42:51 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 13:38:45 +0000
 
 ## Related Decisions
 

package/data/docs/models/contract.md

@@ -0,0 +1,454 @@
+---
+title: "Contract"
+sidebar_label: "Contract"
+sidebar_position: 10
+---
+
+# Contract
+
+<details>
+<summary>Example JSON</summary>
+
+```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"
+}
+```
+
+</details>
+
+
+- [1. Property `id`](#id)
+- [2. Property `companyId`](#companyId)
+- [3. Property `payeeId`](#payeeId)
+- [4. Property `title`](#title)
+- [5. Property `description`](#description)
+- [6. Property `status`](#status)
+- [7. Property `currency`](#currency)
+- [8. Property `totalAmount`](#totalAmount)
+- [9. Property `startDate`](#startDate)
+- [10. Property `endDate`](#endDate)
+- [11. Property `milestones`](#milestones)
+  - [11.1. milestones items](#milestones_items)
+    - [11.1.1. Property `id`](#milestones_items_id)
+    - [11.1.2. Property `title`](#milestones_items_title)
+    - [11.1.3. Property `amount`](#milestones_items_amount)
+    - [11.1.4. Property `dueDate`](#milestones_items_dueDate)
+    - [11.1.5. Property `status`](#milestones_items_status)
+    - [11.1.6. Property `invoicedAt`](#milestones_items_invoicedAt)
+      - [11.1.6.1. Property `_seconds`](#milestones_items_invoicedAt__seconds)
+      - [11.1.6.2. Property `_nanoseconds`](#milestones_items_invoicedAt__nanoseconds)
+    - [11.1.7. Property `paidAt`](#milestones_items_paidAt)
+    - [11.1.8. Property `notes`](#milestones_items_notes)
+- [12. Property `notes`](#notes)
+- [13. Property `createdBy`](#createdBy)
+- [14. Property `createdAt`](#createdAt)
+  - [14.1. Property `firestore-timestamp`](#createdAt_anyOf_i0)
+  - [14.2. Property `item 1`](#createdAt_anyOf_i1)
+- [15. Property `updatedAt`](#updatedAt)
+  - [15.1. Property `firestore-timestamp`](#updatedAt_anyOf_i0)
+  - [15.2. Property `item 1`](#updatedAt_anyOf_i1)
+
+|                           |                        |
+| ------------------------- | ---------------------- |
+| **Type**                  | `object`               |
+| **Required**              | No                     |
+| **Additional properties** | Not allowed            |
+| **Defined in**            | #/definitions/contract |
+
+**Description:** Contract model (GH#14/#17/#18). Collection: companies/\{companyId\}/contracts/\{contractId\}. Service/supplier contract between a company and a Payee. No isActive field — query by status. Currency locked to XOF. Milestones use MilestoneStatus enum (no stored OVERDUE).
+
+| Property                       | Pattern | Type                    | Deprecated | Definition                       | Title/Description                                                                                     |
+| ------------------------------ | ------- | ----------------------- | ---------- | -------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| - [id](#id )                   | No      | string or null          | No         | -                                | (Read-only) Firestore document ID, auto-generated.                                                    |
+| + [companyId](#companyId )     | No      | string                  | No         | -                                | (Immutable) FK → Company document ID.                                                                 |
+| + [payeeId](#payeeId )         | No      | string                  | No         | -                                | (Immutable) FK → Payee document ID. Full Payee model tracked in #20.                                  |
+| + [title](#title )             | No      | string                  | No         | -                                | Contract title or reference name shown in dashboards.                                                 |
+| - [description](#description ) | No      | string or null          | No         | -                                | Optional freeform description of the contract scope.                                                  |
+| + [status](#status )           | No      | enum (of string)        | No         | In #/definitions/contract-status | Contract lifecycle status (#14). Query by ACTIVE — do not use an isActive boolean.                    |
+| + [currency](#currency )       | No      | const                   | No         | -                                | Currency code. Locked to XOF (#18). Multi-currency support requires a deliberate schema version bump. |
+| + [totalAmount](#totalAmount ) | No      | number                  | No         | -                                | Total contract value (XOF).                                                                           |
+| + [startDate](#startDate )     | No      | string                  | No         | -                                | Contract start date (ISO 8601 YYYY-MM-DD).                                                            |
+| - [endDate](#endDate )         | No      | string or null          | No         | -                                | Contract end date (ISO 8601 YYYY-MM-DD). Absent for open-ended contracts.                             |
+| - [milestones](#milestones )   | No      | array of object or null | No         | -                                | Ordered list of payment milestones. Embedded in the contract document (#17).                          |
+| - [notes](#notes )             | No      | string or null          | No         | -                                | Optional internal notes.                                                                              |
+| + [createdBy](#createdBy )     | No      | string                  | No         | -                                | (Immutable) FK → User/staff UID who created the contract.                                             |
+| - [createdAt](#createdAt )     | No      | Combination             | No         | -                                | (Read-only) Server-generated creation timestamp.                                                      |
+| - [updatedAt](#updatedAt )     | No      | Combination             | No         | -                                | (Read-only) Server-generated update timestamp.                                                        |
+
+## <a name="id"></a>1. Property `id`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+**Description:** (Read-only) Firestore document ID, auto-generated.
+
+:::warning Server-set
+Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.
+:::
+
+## <a name="companyId"></a>2. Property `companyId`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** (Immutable) FK → Company document ID.
+
+:::info Immutable
+Set at creation only. This field cannot be modified after the document is created. Include it in CREATE payloads; omit it (or leave unchanged) in UPDATE payloads.
+:::
+
+## <a name="payeeId"></a>3. Property `payeeId`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** (Immutable) FK → Payee document ID. Full Payee model tracked in #20.
+
+:::info Immutable
+Set at creation only. This field cannot be modified after the document is created. Include it in CREATE payloads; omit it (or leave unchanged) in UPDATE payloads.
+:::
+
+## <a name="title"></a>4. Property `title`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** Contract title or reference name shown in dashboards.
+
+## <a name="description"></a>5. Property `description`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+**Description:** Optional freeform description of the contract scope.
+
+## <a name="status"></a>6. Property `status`
+
+|                |                               |
+| -------------- | ----------------------------- |
+| **Type**       | `enum (of string)`            |
+| **Required**   | Yes                           |
+| **Defined in** | #/definitions/contract-status |
+
+**Description:** Contract lifecycle status (#14). Query by ACTIVE — do not use an isActive boolean.
+
+Must be one of:
+* "DRAFT"
+* "ACTIVE"
+* "COMPLETED"
+* "TERMINATED"
+
+## <a name="currency"></a>7. Property `currency`
+
+|              |         |
+| ------------ | ------- |
+| **Type**     | `const` |
+| **Required** | Yes     |
+
+**Description:** Currency code. Locked to XOF (#18). Multi-currency support requires a deliberate schema version bump.
+
+Specific value: `"XOF"`
+
+## <a name="totalAmount"></a>8. Property `totalAmount`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `number` |
+| **Required** | Yes      |
+
+**Description:** Total contract value (XOF).
+
+## <a name="startDate"></a>9. Property `startDate`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** Contract start date (ISO 8601 YYYY-MM-DD).
+
+## <a name="endDate"></a>10. Property `endDate`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+**Description:** Contract end date (ISO 8601 YYYY-MM-DD). Absent for open-ended contracts.
+
+## <a name="milestones"></a>11. Property `milestones`
+
+|              |                           |
+| ------------ | ------------------------- |
+| **Type**     | `array of object or null` |
+| **Required** | No                        |
+
+**Description:** Ordered list of payment milestones. Embedded in the contract document (#17).
+
+|                      | Array restrictions |
+| -------------------- | ------------------ |
+| **Min items**        | N/A                |
+| **Max items**        | N/A                |
+| **Items unicity**    | False              |
+| **Additional items** | False              |
+| **Tuple validation** | See below          |
+
+| Each item of this array must be       | Description                                                                           |
+| ------------------------------------- | ------------------------------------------------------------------------------------- |
+| [milestones items](#milestones_items) | ContractMilestone — embedded sub-object on Contract (#17). Not a separate collection. |
+
+### <a name="milestones_items"></a>11.1. milestones items
+
+|                           |             |
+| ------------------------- | ----------- |
+| **Type**                  | `object`    |
+| **Required**              | No          |
+| **Additional properties** | Not allowed |
+
+**Description:** ContractMilestone — embedded sub-object on Contract (#17). Not a separate collection.
+
+| Property                                      | Pattern | Type             | Deprecated | Definition                                          | Title/Description                                                                                                       |
+| --------------------------------------------- | ------- | ---------------- | ---------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| + [id](#milestones_items_id )                 | No      | string           | No         | -                                                   | Client-generated milestone ID (UUID or slug). Unique within the contract.                                               |
+| + [title](#milestones_items_title )           | No      | string           | No         | -                                                   | Milestone description or deliverable name.                                                                              |
+| + [amount](#milestones_items_amount )         | No      | number           | No         | -                                                   | Amount due at this milestone (XOF).                                                                                     |
+| - [dueDate](#milestones_items_dueDate )       | No      | string           | No         | -                                                   | ISO 8601 date string (YYYY-MM-DD) when the milestone is due. OVERDUE is derived at read time from dueDate — not stored. |
+| + [status](#milestones_items_status )         | No      | enum (of string) | No         | In #/definitions/milestone-status                   | Milestone payment status (#17). OVERDUE is derived at read time from dueDate, not stored.                               |
+| - [invoicedAt](#milestones_items_invoicedAt ) | No      | object           | No         | In #/definitions/firestore-timestamp                | When the invoice was issued for this milestone.                                                                         |
+| - [paidAt](#milestones_items_paidAt )         | No      | object           | No         | Same as [invoicedAt](#milestones_items_invoicedAt ) | When payment was received for this milestone.                                                                           |
+| - [notes](#milestones_items_notes )           | No      | string           | No         | -                                                   | Optional notes for this milestone.                                                                                      |
+
+#### <a name="milestones_items_id"></a>11.1.1. Property `id`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** Client-generated milestone ID (UUID or slug). Unique within the contract.
+
+#### <a name="milestones_items_title"></a>11.1.2. Property `title`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** Milestone description or deliverable name.
+
+#### <a name="milestones_items_amount"></a>11.1.3. Property `amount`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `number` |
+| **Required** | Yes      |
+
+**Description:** Amount due at this milestone (XOF).
+
+#### <a name="milestones_items_dueDate"></a>11.1.4. Property `dueDate`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+**Description:** ISO 8601 date string (YYYY-MM-DD) when the milestone is due. OVERDUE is derived at read time from dueDate — not stored.
+
+#### <a name="milestones_items_status"></a>11.1.5. Property `status`
+
+|                |                                |
+| -------------- | ------------------------------ |
+| **Type**       | `enum (of string)`             |
+| **Required**   | Yes                            |
+| **Defined in** | #/definitions/milestone-status |
+
+**Description:** Milestone payment status (#17). OVERDUE is derived at read time from dueDate, not stored.
+
+Must be one of:
+* "PENDING"
+* "INVOICED"
+* "PAID"
+
+#### <a name="milestones_items_invoicedAt"></a>11.1.6. Property `invoicedAt`
+
+|                           |                                   |
+| ------------------------- | --------------------------------- |
+| **Type**                  | `object`                          |
+| **Required**              | No                                |
+| **Additional properties** | Not allowed                       |
+| **Defined in**            | #/definitions/firestore-timestamp |
+
+**Description:** When the invoice was issued for this milestone.
+
+| Property                                                     | Pattern | Type    | Deprecated | Definition | Title/Description |
+| ------------------------------------------------------------ | ------- | ------- | ---------- | ---------- | ----------------- |
+| + [_seconds](#milestones_items_invoicedAt__seconds )         | No      | integer | No         | -          | -                 |
+| + [_nanoseconds](#milestones_items_invoicedAt__nanoseconds ) | No      | integer | No         | -          | -                 |
+
+##### <a name="milestones_items_invoicedAt__seconds"></a>11.1.6.1. Property `_seconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+##### <a name="milestones_items_invoicedAt__nanoseconds"></a>11.1.6.2. Property `_nanoseconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+#### <a name="milestones_items_paidAt"></a>11.1.7. Property `paidAt`
+
+|                           |                                            |
+| ------------------------- | ------------------------------------------ |
+| **Type**                  | `object`                                   |
+| **Required**              | No                                         |
+| **Additional properties** | Not allowed                                |
+| **Same definition as**    | [invoicedAt](#milestones_items_invoicedAt) |
+
+**Description:** When payment was received for this milestone.
+
+#### <a name="milestones_items_notes"></a>11.1.8. Property `notes`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+**Description:** Optional notes for this milestone.
+
+## <a name="notes"></a>12. Property `notes`
+
+|              |                  |
+| ------------ | ---------------- |
+| **Type**     | `string or null` |
+| **Required** | No               |
+
+**Description:** Optional internal notes.
+
+## <a name="createdBy"></a>13. Property `createdBy`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** (Immutable) FK → User/staff UID who created the contract.
+
+:::info Immutable
+Set at creation only. This field cannot be modified after the document is created. Include it in CREATE payloads; omit it (or leave unchanged) in UPDATE payloads.
+:::
+
+## <a name="createdAt"></a>14. Property `createdAt`
+
+|                           |                  |
+| ------------------------- | ---------------- |
+| **Type**                  | `combining`      |
+| **Required**              | No               |
+| **Additional properties** | Any type allowed |
+
+**Description:** (Read-only) Server-generated creation timestamp.
+
+| Any of(Option)                             |
+| ------------------------------------------ |
+| [firestore-timestamp](#createdAt_anyOf_i0) |
+| [item 1](#createdAt_anyOf_i1)              |
+
+### <a name="createdAt_anyOf_i0"></a>14.1. Property `firestore-timestamp`
+
+|                           |                                            |
+| ------------------------- | ------------------------------------------ |
+| **Type**                  | `object`                                   |
+| **Required**              | No                                         |
+| **Additional properties** | Not allowed                                |
+| **Same definition as**    | [invoicedAt](#milestones_items_invoicedAt) |
+
+**Description:** Firestore Timestamp — Admin SDK form: \{ _seconds, _nanoseconds \}. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10).
+
+### <a name="createdAt_anyOf_i1"></a>14.2. Property `item 1`
+
+|              |        |
+| ------------ | ------ |
+| **Type**     | `null` |
+| **Required** | No     |
+
+:::warning Server-set
+Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.
+:::
+
+## <a name="updatedAt"></a>15. Property `updatedAt`
+
+|                           |                  |
+| ------------------------- | ---------------- |
+| **Type**                  | `combining`      |
+| **Required**              | No               |
+| **Additional properties** | Any type allowed |
+
+**Description:** (Read-only) Server-generated update timestamp.
+
+| Any of(Option)                             |
+| ------------------------------------------ |
+| [firestore-timestamp](#updatedAt_anyOf_i0) |
+| [item 1](#updatedAt_anyOf_i1)              |
+
+### <a name="updatedAt_anyOf_i0"></a>15.1. Property `firestore-timestamp`
+
+|                           |                                            |
+| ------------------------- | ------------------------------------------ |
+| **Type**                  | `object`                                   |
+| **Required**              | No                                         |
+| **Additional properties** | Not allowed                                |
+| **Same definition as**    | [invoicedAt](#milestones_items_invoicedAt) |
+
+**Description:** Firestore Timestamp — Admin SDK form: \{ _seconds, _nanoseconds \}. See types/firestore.ts for REST API v1 and client SDK serialization notes (#10).
+
+### <a name="updatedAt_anyOf_i1"></a>15.2. Property `item 1`
+
+|              |        |
+| ------------ | ------ |
+| **Type**     | `null` |
+| **Required** | No     |
+
+----------------------------------------------------------------------------------------------------------------------------
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-30 at 13:38:45 +0000
+
+:::warning Server-set
+Do not include in write requests. This field is set exclusively by the server (Firestore trigger or Admin SDK). Clients that send it will have the value silently ignored or may receive a validation error.
+:::