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

package/data/docs/models/stocktake.md

@@ -0,0 +1,649 @@
+---
+title: "Stocktake"
+sidebar_label: "Stocktake"
+sidebar_position: 25
+---
+
+# Stocktake
+
+<details>
+<summary>Example JSON</summary>
+
+```json
+{
+  "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"
+}
+```
+
+</details>
+
+
+- [1. Property `id`](#id)
+- [2. Property `companyId`](#companyId)
+- [3. Property `stocktakeNumber`](#stocktakeNumber)
+- [4. Property `stocktakeDate`](#stocktakeDate)
+  - [4.1. Property `_seconds`](#stocktakeDate__seconds)
+  - [4.2. Property `_nanoseconds`](#stocktakeDate__nanoseconds)
+- [5. Property `warehouseId`](#warehouseId)
+  - [5.1. Property `item 0`](#warehouseId_anyOf_i0)
+  - [5.2. Property `item 1`](#warehouseId_anyOf_i1)
+- [6. Property `frequency`](#frequency)
+  - [6.1. Property `stocktake-frequency`](#frequency_anyOf_i0)
+  - [6.2. Property `item 1`](#frequency_anyOf_i1)
+- [7. Property `scheduledStocktakeId`](#scheduledStocktakeId)
+  - [7.1. Property `item 0`](#scheduledStocktakeId_anyOf_i0)
+  - [7.2. Property `item 1`](#scheduledStocktakeId_anyOf_i1)
+- [8. Property `status`](#status)
+- [9. Property `adjustmentsApplied`](#adjustmentsApplied)
+- [10. Property `notes`](#notes)
+  - [10.1. Property `item 0`](#notes_anyOf_i0)
+  - [10.2. Property `item 1`](#notes_anyOf_i1)
+- [11. Property `totalItemsCount`](#totalItemsCount)
+- [12. Property `totalDiscrepancies`](#totalDiscrepancies)
+- [13. Property `totalDeltaValue`](#totalDeltaValue)
+- [14. Property `startedAt`](#startedAt)
+- [15. Property `completedAt`](#completedAt)
+  - [15.1. Property `firestore-timestamp`](#completedAt_anyOf_i0)
+  - [15.2. Property `item 1`](#completedAt_anyOf_i1)
+- [16. Property `createdAt`](#createdAt)
+  - [16.1. Property `firestore-timestamp`](#createdAt_anyOf_i0)
+  - [16.2. Property `item 1`](#createdAt_anyOf_i1)
+- [17. Property `createdBy`](#createdBy)
+- [18. Property `createdByName`](#createdByName)
+- [19. Property `completedBy`](#completedBy)
+  - [19.1. Property `item 0`](#completedBy_anyOf_i0)
+  - [19.2. Property `item 1`](#completedBy_anyOf_i1)
+- [20. Property `completedByName`](#completedByName)
+  - [20.1. Property `item 0`](#completedByName_anyOf_i0)
+  - [20.2. Property `item 1`](#completedByName_anyOf_i1)
+- [21. Property `updatedAt`](#updatedAt)
+  - [21.1. Property `firestore-timestamp`](#updatedAt_anyOf_i0)
+  - [21.2. Property `item 1`](#updatedAt_anyOf_i1)
+
+|                           |                         |
+| ------------------------- | ----------------------- |
+| **Type**                  | `object`                |
+| **Required**              | No                      |
+| **Additional properties** | Not allowed             |
+| **Defined in**            | #/definitions/stocktake |
+
+**Description:** Stocktake (GH#29 §4). 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 — derivable from the sub-collection. Status transitions and aggregate fields (totalItemsCount/Discrepancies/totalDeltaValue) are server-owned per GH#29 §3.
+
+| 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. Tenant scope.                                                                                                                                            |
+| + [stocktakeNumber](#stocktakeNumber )           | No      | string           | No         | -                                        | 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](#stocktakeDate )               | No      | object           | No         | In #/definitions/firestore-timestamp     | Effective date of the count. Distinct from createdAt; can be backdated.                                                                                                                        |
+| - [warehouseId](#warehouseId )                   | No      | Combination      | No         | -                                        | FK → Warehouse document ID. Null = whole-company stocktake (no warehouse partition).                                                                                                           |
+| - [frequency](#frequency )                       | No      | Combination      | No         | -                                        | Recurrence cadence. Optional — leave unset for ad-hoc sessions, or set to indicate this stocktake is part of a recurring schedule.                                                             |
+| - [scheduledStocktakeId](#scheduledStocktakeId ) | No      | Combination      | No         | -                                        | FK to a recurring stocktake schedule, if this session was emitted from one. Null for ad-hoc sessions.                                                                                          |
+| + [status](#status )                             | No      | enum (of string) | No         | In #/definitions/stocktake-status        | Lifecycle status. Transitions PENDING → IN_PROGRESS → COMPLETED are server-owned (GH#29 §3 / Q25).                                                                                             |
+| + [adjustmentsApplied](#adjustmentsApplied )     | No      | boolean          | No         | -                                        | True if completing the session actually emitted StockMovement adjustments. False for record-only counts.                                                                                       |
+| - [notes](#notes )                               | No      | Combination      | No         | -                                        | Free-text session-level notes.                                                                                                                                                                 |
+| + [totalItemsCount](#totalItemsCount )           | No      | integer          | No         | -                                        | (Read-only) Total number of StocktakeItem rows under this session.                                                                                                                             |
+| + [totalDiscrepancies](#totalDiscrepancies )     | No      | integer          | No         | -                                        | (Read-only) Sum of absolute deltas across counted items.                                                                                                                                       |
+| + [totalDeltaValue](#totalDeltaValue )           | No      | number           | No         | -                                        | (Read-only) Net valuation impact of the count, in XOF integer minor units.                                                                                                                     |
+| + [startedAt](#startedAt )                       | No      | object           | No         | Same as [stocktakeDate](#stocktakeDate ) | When the counting session physically opened. Typically equal to createdAt for ad-hoc sessions.                                                                                                 |
+| - [completedAt](#completedAt )                   | No      | Combination      | No         | -                                        | (Read-only) When the session transitioned to COMPLETED.                                                                                                                                        |
+| - [createdAt](#createdAt )                       | No      | Combination      | No         | -                                        | (Read-only) Server-generated creation timestamp.                                                                                                                                               |
+| + [createdBy](#createdBy )                       | No      | string           | No         | -                                        | (Immutable) FK → User UID who created the session.                                                                                                                                             |
+| + [createdByName](#createdByName )               | No      | string           | No         | -                                        | (Denormalized) Snapshot of the creator's display name at session creation.                                                                                                                     |
+| - [completedBy](#completedBy )                   | No      | Combination      | No         | -                                        | (Read-only) FK → User UID who completed the session, set by server on COMPLETED.                                                                                                               |
+| - [completedByName](#completedByName )           | No      | Combination      | No         | -                                        | (Denormalized) Snapshot of the completer's display name.                                                                                                                                       |
+| - [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. Tenant scope.
+
+:::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="stocktakeNumber"></a>3. Property `stocktakeNumber`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**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.
+
+## <a name="stocktakeDate"></a>4. Property `stocktakeDate`
+
+|                           |                                   |
+| ------------------------- | --------------------------------- |
+| **Type**                  | `object`                          |
+| **Required**              | Yes                               |
+| **Additional properties** | Not allowed                       |
+| **Defined in**            | #/definitions/firestore-timestamp |
+
+**Description:** Effective date of the count. Distinct from createdAt; can be backdated.
+
+| Property                                       | Pattern | Type    | Deprecated | Definition | Title/Description |
+| ---------------------------------------------- | ------- | ------- | ---------- | ---------- | ----------------- |
+| + [_seconds](#stocktakeDate__seconds )         | No      | integer | No         | -          | -                 |
+| + [_nanoseconds](#stocktakeDate__nanoseconds ) | No      | integer | No         | -          | -                 |
+
+### <a name="stocktakeDate__seconds"></a>4.1. Property `_seconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+### <a name="stocktakeDate__nanoseconds"></a>4.2. Property `_nanoseconds`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+:::note
+The date the count is FOR. Can be backdated (stocktakeDate < createdAt) — analytics buckets by stocktakeDate for "what period was counted" and by completedAt for "when adjustments hit the ledger" (GH#29 Q24).
+:::
+
+## <a name="warehouseId"></a>5. Property `warehouseId`
+
+|                           |                  |
+| ------------------------- | ---------------- |
+| **Type**                  | `combining`      |
+| **Required**              | No               |
+| **Additional properties** | Any type allowed |
+
+**Description:** FK → Warehouse document ID. Null = whole-company stocktake (no warehouse partition).
+
+| Any of(Option)                  |
+| ------------------------------- |
+| [item 0](#warehouseId_anyOf_i0) |
+| [item 1](#warehouseId_anyOf_i1) |
+
+### <a name="warehouseId_anyOf_i0"></a>5.1. Property `item 0`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+### <a name="warehouseId_anyOf_i1"></a>5.2. Property `item 1`
+
+|              |        |
+| ------------ | ------ |
+| **Type**     | `null` |
+| **Required** | No     |
+
+## <a name="frequency"></a>6. Property `frequency`
+
+|                           |                  |
+| ------------------------- | ---------------- |
+| **Type**                  | `combining`      |
+| **Required**              | No               |
+| **Additional properties** | Any type allowed |
+
+**Description:** Recurrence cadence. Optional — leave unset for ad-hoc sessions, or set to indicate this stocktake is part of a recurring schedule.
+
+| Any of(Option)                             |
+| ------------------------------------------ |
+| [stocktake-frequency](#frequency_anyOf_i0) |
+| [item 1](#frequency_anyOf_i1)              |
+
+### <a name="frequency_anyOf_i0"></a>6.1. Property `stocktake-frequency`
+
+|                |                                   |
+| -------------- | --------------------------------- |
+| **Type**       | `enum (of string)`                |
+| **Required**   | No                                |
+| **Defined in** | #/definitions/stocktake-frequency |
+
+**Description:** Recurrence cadence of a Stocktake session (GH#29 §4).
+
+Must be one of:
+* "DAILY"
+* "WEEKLY"
+* "MONTHLY"
+* "AD_HOC"
+
+### <a name="frequency_anyOf_i1"></a>6.2. Property `item 1`
+
+|              |        |
+| ------------ | ------ |
+| **Type**     | `null` |
+| **Required** | No     |
+
+:::note
+Optional today (dashboard does not currently track recurrence). Frequency is a property of the record, not a separate type — 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.
+:::
+
+:::info See also
+**Issues:** `gh#29`
+:::
+
+## <a name="scheduledStocktakeId"></a>7. Property `scheduledStocktakeId`
+
+|                           |                  |
+| ------------------------- | ---------------- |
+| **Type**                  | `combining`      |
+| **Required**              | No               |
+| **Additional properties** | Any type allowed |
+
+**Description:** FK to a recurring stocktake schedule, if this session was emitted from one. Null for ad-hoc sessions.
+
+| Any of(Option)                           |
+| ---------------------------------------- |
+| [item 0](#scheduledStocktakeId_anyOf_i0) |
+| [item 1](#scheduledStocktakeId_anyOf_i1) |
+
+### <a name="scheduledStocktakeId_anyOf_i0"></a>7.1. Property `item 0`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+### <a name="scheduledStocktakeId_anyOf_i1"></a>7.2. Property `item 1`
+
+|              |        |
+| ------------ | ------ |
+| **Type**     | `null` |
+| **Required** | No     |
+
+## <a name="status"></a>8. Property `status`
+
+|                |                                |
+| -------------- | ------------------------------ |
+| **Type**       | `enum (of string)`             |
+| **Required**   | Yes                            |
+| **Defined in** | #/definitions/stocktake-status |
+
+**Description:** Lifecycle status. Transitions PENDING → IN_PROGRESS → COMPLETED are server-owned (GH#29 §3 / Q25).
+
+Must be one of:
+* "PENDING"
+* "IN_PROGRESS"
+* "COMPLETED"
+* "CANCELLED"
+
+:::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 → IN_PROGRESS → COMPLETED are server-owned (Q25) — clients PATCH item status; the server transitions session status to avoid the concurrent-edit race documented in stockService.ts:1671.
+:::
+
+:::tip When to set
+Server-managed. Clients write item updates; the trigger transitions session status.
+:::
+
+:::info See also
+**Issues:** `gh#29`
+:::
+
+## <a name="adjustmentsApplied"></a>9. Property `adjustmentsApplied`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `boolean` |
+| **Required** | Yes       |
+
+**Description:** True if completing the session actually emitted StockMovement adjustments. False for record-only counts.
+
+:::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).
+:::
+
+## <a name="notes"></a>10. Property `notes`
+
+|                           |                  |
+| ------------------------- | ---------------- |
+| **Type**                  | `combining`      |
+| **Required**              | No               |
+| **Additional properties** | Any type allowed |
+
+**Description:** Free-text session-level notes.
+
+| Any of(Option)            |
+| ------------------------- |
+| [item 0](#notes_anyOf_i0) |
+| [item 1](#notes_anyOf_i1) |
+
+### <a name="notes_anyOf_i0"></a>10.1. Property `item 0`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+### <a name="notes_anyOf_i1"></a>10.2. Property `item 1`
+
+|              |        |
+| ------------ | ------ |
+| **Type**     | `null` |
+| **Required** | No     |
+
+## <a name="totalItemsCount"></a>11. Property `totalItemsCount`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+**Description:** (Read-only) Total number of StocktakeItem rows under this session.
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+:::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.
+:::
+
+:::note
+Server-derived. Recomputed by trigger on each StocktakeItem write; not safe to write client-side under concurrent edits (GH#29 audit Q23).
+:::
+
+## <a name="totalDiscrepancies"></a>12. Property `totalDiscrepancies`
+
+|              |           |
+| ------------ | --------- |
+| **Type**     | `integer` |
+| **Required** | Yes       |
+
+**Description:** (Read-only) Sum of absolute deltas across counted items.
+
+| Restrictions |                        |
+| ------------ | ---------------------- |
+| **Minimum**  | &ge; -9007199254740991 |
+| **Maximum**  | &le; 9007199254740991  |
+
+:::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.
+:::
+
+:::note
+Server-derived = sum of |item.delta| across COUNTED items. Updated by trigger.
+:::
+
+## <a name="totalDeltaValue"></a>13. Property `totalDeltaValue`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `number` |
+| **Required** | Yes      |
+
+**Description:** (Read-only) Net valuation impact of the count, in XOF integer minor units.
+
+:::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.
+:::
+
+:::note
+Server-derived = sum of (item.delta × item.costPerUnit) across COUNTED items, in XOF integer minor units (D18). Updated by trigger.
+:::
+
+## <a name="startedAt"></a>14. Property `startedAt`
+
+|                           |                                 |
+| ------------------------- | ------------------------------- |
+| **Type**                  | `object`                        |
+| **Required**              | Yes                             |
+| **Additional properties** | Not allowed                     |
+| **Same definition as**    | [stocktakeDate](#stocktakeDate) |
+
+**Description:** When the counting session physically opened. Typically equal to createdAt for ad-hoc sessions.
+
+## <a name="completedAt"></a>15. Property `completedAt`
+
+|                           |                  |
+| ------------------------- | ---------------- |
+| **Type**                  | `combining`      |
+| **Required**              | No               |
+| **Additional properties** | Any type allowed |
+
+**Description:** (Read-only) When the session transitioned to COMPLETED.
+
+| Any of(Option)                               |
+| -------------------------------------------- |
+| [firestore-timestamp](#completedAt_anyOf_i0) |
+| [item 1](#completedAt_anyOf_i1)              |
+
+### <a name="completedAt_anyOf_i0"></a>15.1. Property `firestore-timestamp`
+
+|                           |                                 |
+| ------------------------- | ------------------------------- |
+| **Type**                  | `object`                        |
+| **Required**              | No                              |
+| **Additional properties** | Not allowed                     |
+| **Same definition as**    | [stocktakeDate](#stocktakeDate) |
+
+**Description:** Firestore Timestamp serialized representation
+
+### <a name="completedAt_anyOf_i1"></a>15.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.
+:::
+
+:::note
+Server-set on transition to COMPLETED. Distinct from stocktakeDate (the period counted) — analytics buckets by completedAt to answer "when did the ledger hit?".
+:::
+
+## <a name="createdAt"></a>16. 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>16.1. Property `firestore-timestamp`
+
+|                           |                                 |
+| ------------------------- | ------------------------------- |
+| **Type**                  | `object`                        |
+| **Required**              | No                              |
+| **Additional properties** | Not allowed                     |
+| **Same definition as**    | [stocktakeDate](#stocktakeDate) |
+
+**Description:** Firestore Timestamp serialized representation
+
+### <a name="createdAt_anyOf_i1"></a>16.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="createdBy"></a>17. Property `createdBy`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** (Immutable) FK → User UID who created the session.
+
+:::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="createdByName"></a>18. Property `createdByName`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | Yes      |
+
+**Description:** (Denormalized) Snapshot of the creator's display name at session creation.
+
+:::note
+Read-time hint snapshot of the creator's display name (GH#29 §3 / Q10).
+:::
+
+## <a name="completedBy"></a>19. Property `completedBy`
+
+|                           |                  |
+| ------------------------- | ---------------- |
+| **Type**                  | `combining`      |
+| **Required**              | No               |
+| **Additional properties** | Any type allowed |
+
+**Description:** (Read-only) FK → User UID who completed the session, set by server on COMPLETED.
+
+| Any of(Option)                  |
+| ------------------------------- |
+| [item 0](#completedBy_anyOf_i0) |
+| [item 1](#completedBy_anyOf_i1) |
+
+### <a name="completedBy_anyOf_i0"></a>19.1. Property `item 0`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+### <a name="completedBy_anyOf_i1"></a>19.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="completedByName"></a>20. Property `completedByName`
+
+|                           |                  |
+| ------------------------- | ---------------- |
+| **Type**                  | `combining`      |
+| **Required**              | No               |
+| **Additional properties** | Any type allowed |
+
+**Description:** (Denormalized) Snapshot of the completer's display name.
+
+| Any of(Option)                      |
+| ----------------------------------- |
+| [item 0](#completedByName_anyOf_i0) |
+| [item 1](#completedByName_anyOf_i1) |
+
+### <a name="completedByName_anyOf_i0"></a>20.1. Property `item 0`
+
+|              |          |
+| ------------ | -------- |
+| **Type**     | `string` |
+| **Required** | No       |
+
+### <a name="completedByName_anyOf_i1"></a>20.2. Property `item 1`
+
+|              |        |
+| ------------ | ------ |
+| **Type**     | `null` |
+| **Required** | No     |
+
+:::note
+Read-time hint snapshot of the completer's display name (GH#29 §3 / Q10).
+:::
+
+## <a name="updatedAt"></a>21. 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>21.1. Property `firestore-timestamp`
+
+|                           |                                 |
+| ------------------------- | ------------------------------- |
+| **Type**                  | `object`                        |
+| **Required**              | No                              |
+| **Additional properties** | Not allowed                     |
+| **Same definition as**    | [stocktakeDate](#stocktakeDate) |
+
+**Description:** Firestore Timestamp serialized representation
+
+### <a name="updatedAt_anyOf_i1"></a>21.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-05 at 12:09:28 +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/ticket.md

@@ -1,7 +1,7 @@
 ---
 title: "Ticket"
 sidebar_label: "Ticket"
-sidebar_position: 21
+sidebar_position: 27
 ---
 
 # Ticket
@@ -388,7 +388,7 @@ Do not include in write requests. This field is set exclusively by the server (F
 **Description:** (Immutable) FK → User/staff UID who created this ticket.
 
 ----------------------------------------------------------------------------------------------------------------------------
-Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-04-18 at 21:21:09 +0000
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-05-05 at 12:09:28 +0000
 
 :::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.