@ingenx-io/valets-schema-mcp-server 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,65 @@
+# @ingenx-io/valets-schema-mcp-server
+
+MCP server that exposes the [Valets](https://github.com/IngenX-IO/valets-data-architecture) data model documentation to AI agents via the [Model Context Protocol](https://modelcontextprotocol.io).
+
+## Usage
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "valets-schema": {
+      "command": "npx",
+      "args": ["-y", "@ingenx-io/valets-schema-mcp-server"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add valets-schema -- npx -y @ingenx-io/valets-schema-mcp-server
+```
+
+### Other MCP clients
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "@ingenx-io/valets-schema-mcp-server"]
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `schema_overview` | High-level summary of all models and enums — start here |
+| `get_schema` | JSON Schema for a specific model or enum (kebab-case, e.g. `order`, `payment-status`) |
+| `get_doc` | Raw Markdown documentation for a schema page (e.g. `models/order`, `enums/payment-method`) |
+| `search_docs` | Keyword search across all documentation pages |
+| `list_decisions` | All data model decisions (D00–D37+) with status and summary |
+| `get_decision` | Full details for a specific decision by ID (e.g. `D12`) |
+| `get_openapi` | OpenAPI 3.1 spec — full or filtered to a single component (e.g. `Order`, `OrderCreate`) |
+
+## Resources
+
+| URI | Description |
+|-----|-------------|
+| `valets://schemas.json` | Consolidated JSON Schema bundle for all models and enums |
+| `valets://llms.txt` | LLM-optimized summary of the Valets data model |
+| `valets://openapi.yaml` | OpenAPI 3.1 specification |
+| `valets://decisions.json` | Data model decisions metadata |
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `VALETS_SCHEMA_URL` | _(unset)_ | Base URL of a deployed Valets Docusaurus site. When set, the server fetches live data from this URL and falls back to bundled data on failure. |
+| `VALETS_CACHE_TTL` | `300000` | Cache TTL in milliseconds for remotely fetched data (default: 5 minutes). |
+
+When `VALETS_SCHEMA_URL` is not set, the server uses the bundled schema snapshot included in the package.

package/data/docs/collections/firestore-paths.md

@@ -0,0 +1,48 @@
+---
+title: "Firestore Paths"
+sidebar_label: "Firestore Paths"
+sidebar_position: 1
+---
+
+# Firestore Collection Paths
+
+All collections are scoped under a company document.
+
+```
+companies/{companyId}/
+├── orders/{orderId}
+├── customers/{customerId}
+├── bookings/{bookingId}
+│   └── sessions/{sessionId}
+├── events/{eventId}
+│   └── tickets/{ticketId}
+├── sales/{saleId}
+├── purchases/{purchaseId}
+├── customerPayments/{paymentId}
+├── loyaltyTransactions/{transactionId}
+└── loyaltyConfig (singleton document)
+```
+
+## Path conventions
+
+- All paths are **tenant-scoped** under `companies/{companyId}/`
+- Sub-collections (sessions, tickets) are nested under their parent
+- `loyaltyConfig` is a singleton document, not a collection
+- Document IDs are auto-generated Firestore IDs unless specified
+
+## Security rules pattern
+
+```
+rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+    match /companies/{companyId}/{document=**} {
+      // All access requires authenticated user with matching companyId
+      allow read, write: if request.auth != null
+        && request.auth.token.companyId == companyId;
+    }
+  }
+}
+```
+
+> See the Decision Workbook (section 16) for the full path rationale and access patterns.

package/data/docs/decisions/migrations.md

@@ -0,0 +1,56 @@
+---
+title: "Migration Inventory"
+sidebar_label: "Migration Inventory"
+sidebar_position: 2
+---
+
+# Migration Inventory
+
+> Concrete data migrations. All Firestore paths are under `companies/\{companyId\}/`.
+
+## Wave 1 — Foundation (Data Migrations)
+
+| ID | Migration | Collection | Decision | Description |
+|---|---|---|---|---|
+| **MIG-01** | Timestamp field casing | `orders` | `D04` | Rename processingOn → PROCESSING_ON, completedOn → COMPLETED_ON, cancelledOn → CANCELLED_ON, etc. |
+| **MIG-02** | Payment method normalization | `purchases` | `D02` | In payments[] array: CARD → CREDIT_CARD, OM → ORANGE_MONEY, MTN → MTN_MONEY, MOOV → MOOV_MONEY |
+| **MIG-03** | PaymentStatus consolidation | `orders, purchases, bookings` | `D01` | UNPAID → PENDING, PARTIAL → PARTIALLY_PAID (Dashboard's conflicting enum). Bookings also carry payment status. |
+| **MIG-04** | Purchases path consolidation | `customers/*/purchases → purchases` | `D06` | Move customer-scoped purchase docs to company-wide path. Deduplicate. Rewrite references. See IG-5 (§15) for acceptance criteria. |
+| **MIG-05** | Loyalty transaction type normalization | `loyaltyTransactions` | `D07` | earn/earned → EARNED, redeem/redeemed → REDEEMED, adjust/adjusted → ADJUSTED, expire/expired → EXPIRED, bonus → BONUS, refund → REFUND |
+| **MIG-06** | Loyalty config field renaming | `loyaltySettings/config` | `D21` | pointsPerCurrencyUnit → pointsPerCurrency, pointsExpiryMonths → pointsExpirationDays (convert months×30) |
+| **MIG-07** | Booking add-on ID normalization | `bookings (nested slots)` | `D10` | Numeric IDs ('1', '2') → descriptive ('recording', 'photo'). Additive with legacy compat. |
+| **MIG-08** | Booking price field renaming | `bookings (nested slots)` | `D11` | standardPrice → price, fullPrice → notMainPurposePrice |
+| **MIG-09** | Event status casing | `events` | `D32` | draft → DRAFT, active → ACTIVE, cancelled → CANCELLED, completed → COMPLETED |
+| **MIG-10** | Ticket status casing | `events/*/tickets` | `D32` | valid → VALID, used → USED, cancelled → CANCELLED |
+| **MIG-11** | Order status decomposition | `orders` | `D34` | Split extended statuses into orderStatus + paymentStatus + fulfillmentStatus + returnStatus per §10 mapping table |
+| **MIG-12** | Customer points source of truth | `customers, loyalty/status` | `D08` | Verify loyalty/status populated for all customers; flag discrepancies with denormalized customer doc fields |
+
+## Wave 1 — Foundation (Code-Only)
+
+| ID | Change | Platform | Decision | Description |
+|---|---|---|---|---|
+| **COD-01** | Stop writing total | Mobile | `D05` | Mobile stops writing total field on purchases. total becomes read-only getter. |
+| **COD-02** | SalesService alias | All | `D06` | Code-level alias wrapping purchases collection. No Firestore rename. |
+| **COD-03** | Add missing BookingStatus values | Mobile | `—` | Add CANCELLATION_REQUESTED, COMPLETED_MIXED to Mobile enum |
+| **COD-04** | Add SessionStatus awareness | Mobile, Firebase | `D19` | Mobile reads and displays SessionStatus. Read-only first. |
+
+## Wave 5 — Cleanup
+
+| ID | Migration | Collection | Decision | Description |
+|---|---|---|---|---|
+| **MIG-13** | Legacy ticket format migration | `events/*/tickets` | `D31` | Migrate userName/userEmail/userPhone/ticketStatus variants to canonical field names. Run only after audit confirms scope. |
+| **MIG-14** | Remove fallback read paths | `All platforms` | `Various` | Remove old field name readers after fallback removal gate is met (see §1 Transition Protocol). |
+
+---
+
+### Migration Dependencies
+
+```
+MIG-04 (purchases path) → must complete before MIG-02 (payment method normalization)
+MIG-03 (PaymentStatus) → must complete before MIG-11 (order decomposition)
+MIG-11 (order decomposition) → depends on MIG-01 (timestamp casing)
+MIG-05 + MIG-06 (loyalty) → can run independently
+MIG-09 + MIG-10 (event/ticket casing) → can run independently
+MIG-12 (customer points) → should run after MIG-05 (loyalty types)
+```
+

package/data/docs/decisions/summary.md

@@ -0,0 +1,78 @@
+---
+title: "Decision Summary"
+sidebar_label: "Decision Summary"
+sidebar_position: 1
+---
+
+# Decision Summary
+
+> **Status**: 37 of 38 decisions locked; 1 deferred.
+> Source: `DATA_MODEL_DECISION_WORKBOOK.md`.
+
+## All Decisions
+
+| ID | Title | Status | Wave | Schema |
+|---|---|---|---|---|
+| **D00** | Shared schema package approach | 🔒 Locked | 1 | — |
+| **D01** | Canonical PaymentStatus enum set | 🔒 Locked | 1 | `payment-status` |
+| **D02** | Canonical PaymentMethod enum set | 🔒 Locked | 1 | `payment-method` |
+| **D03** | CONFIRMED vs PROCESSING for order lifecycle | 🔒 Locked | 1 | `order-status` |
+| **D04** | Canonical timestamp/status field casing | 🔒 Locked | 1 | `order` |
+| **D05** | Canonical purchase amount field | 🔒 Locked | 1 | `sale` |
+| **D06** | Canonical sales collection path | 🔒 Locked | 1 | `sale` |
+| **D07** | Canonical loyalty transaction type values | 🔒 Locked | 1 | `loyalty-transaction-type` |
+| **D08** | Canonical location for customer points | 🔒 Locked | 1 | `customer`, `loyalty-status` |
+| **D09** | Canonical startDate/endDate type for bookings | 🔒 Locked | 1 | `booking` |
+| **D10** | Canonical booking add-on IDs | 🔒 Locked | 1 | `booking` |
+| **D11** | Canonical price field names in booking slots | 🔒 Locked | 1 | `booking` |
+| **D12** | Payments canonical location model | 🔒 Locked | 2 | `order`, `sale` |
+| **D13** | Mobile order status support breadth | 🔒 Locked | 2 | `order-status` |
+| **D14** | Keep Mobile order override fields (calculatedTotal, manualTotal, totalOverridden) | 🔒 Locked | 2 | `order` |
+| **D15** | Should SaleMargin be server-side | 🔒 Locked | 3 | `sale` |
+| **D16** | Mobile CRM scope | 🔒 Locked | 2 | `customer` |
+| **D17** | Mobile CRDT write behavior for bookings | 🔒 Locked | 2 | `booking` |
+| **D18** | Firebase BookingVersion ownership | 🔒 Locked | 3 | `booking`, `booking-version` |
+| **D19** | Mobile session status transitions | 🔒 Locked | 2 | `session-status` |
+| **D20** | createdFromBackend behavior for dashboard-created bookings | 🔒 Locked | 3 | `booking` |
+| **D21** | Loyalty config canonical field names | 🔒 Locked | 2 | `loyalty-config` |
+| **D22** | Mobile customer payment feature scope | 🔒 Locked | 4 | `customer-payment` |
+| **D23** | Firebase loyalty automation | 🔒 Locked | 3 | `loyalty-transaction` |
+| **D24** | Customer reference naming standardization | 🔒 Locked | 2 | `customer`, `booking`, `order` |
+| **D25** | communicationEntries storage shape | 🔒 Locked | 1 | `customer` |
+| **D26** | Event/Ticket support in dashboard | 🔒 Locked | 4 | `event` |
+| **D27** | Dashboard ticket scanning | 🔒 Locked | 4 | `ticket` |
+| **D28** | Firebase Event/Ticket triggers | 🔒 Locked | 4 | `event`, `ticket` |
+| **D29** | Ticket-to-customer linkage model | 🔒 Locked | 2 | `ticket` |
+| **D30** | Ticket tiers/types support timing | 🔒 Locked | — | `ticket` |
+| **D31** | LegacyTicketMapper deprecation gate | 🔒 Locked | 5 | `ticket` |
+| **D32** | Event/Ticket status casing | 🔒 Locked | 1 | `event-status`, `ticket-status` |
+| **D33** | Deterministic IV in QR encryption | ⏸ Deferred | — | — |
+| **D34** | Order status decomposition into orthogonal fields | 🔒 Locked | 1 | `order`, `order-status`, `payment-status`, `fulfillment-status`, `return-status` |
+| **D35** | Migration framework approach | 🔒 Locked | 1 | — |
+| **D36** | Firebase architectural role: relay vs enforcer | 🔒 Locked | 1 | — |
+| **D37** | Execution wave plan approval | 🔒 Locked | 1 | — |
+
+## Implementation Guidance Gaps
+
+> Identified implementation work items — not decisions, but concrete gaps to address per wave.
+
+| ID | Summary | Wave | Acceptance Criteria |
+|---|---|---|---|
+| **IG-1** | Cross-Platform Contract Testing | 1 | Shared JSON fixtures exist for all models; read/write round-trip tests pass across all 3 platforms |
+| **IG-2** | Firestore Security Rules Generation | 3 | Security rules enforce basic type checks for critical collections; generated or manually aligned with @valets/schema |
+| **IG-3** | Booking Model Convergence (Mobile) | 2 | Single canonical Booking class on Mobile generated from @valets/schema; BookingData page class removed or reduced to UI-only state |
+| **IG-4** | Order Payments Model Ownership | 2 | OrderPayment → PaymentTransaction field mapping documented; sync rules for Sale↔Order denormalized snapshot implemented |
+| **IG-5** | Purchases Collection Path Consolidation | 1 | All purchase documents exist in single purchases/ path; customer-scoped duplicates removed; references rewritten |
+| **IG-6** | Booking CRDT Interoperability | 2 | Mobile fromMap filters _deleted items; conflict resolution documented; timeline for soft-delete parity set |
+| **IG-7** | Customer Payments Rollout Spec | 4 | Trusted roles defined; audit field requirements in @valets/schema; server-side validation rules deployed |
+| **IG-8** | Notification Behavior Policy | 3 | createdFromBackend behavior documented and consistently applied; notification regression tests in CI |
+| **IG-9** | Event/Ticket Crypto + Legacy Cutover | 5 | LegacyTicketMapper removal gate query exists; key rotation policy documented; IV migration plan ready when triggered |
+| **IG-10** | LoyaltyReward / LoyaltyConfig Parity | 2 | Mobile-only loyalty fields catalogued; canonical set defined in @valets/schema; Dashboard config UI spec created |
+| **IG-11** | slotKitTypes Firebase Type Parity | 2 | slotKitTypes field added to Firebase Booking type definition; validated in contract tests |
+| **IG-12** | bookingId Mobile Purchase Parity | 2 | bookingId field added to Mobile Purchase model; links sales to bookings across platforms |
+| **IG-13** | companyId Firebase Quote/Opportunity Parity | 2 | companyId field added to Firebase Quote and Opportunity type definitions; multi-tenant queries work |
+
+---
+
+> For full rationale and context see `DATA_MODEL_DECISION_WORKBOOK.md` in the valets-data-architecture repo.
+

package/data/docs/enums/booking-status.md

@@ -0,0 +1,26 @@
+---
+title: "BookingStatus"
+sidebar_label: "BookingStatus"
+sidebar_position: 1
+---
+
+# BookingStatus
+
+|                |                              |
+| -------------- | ---------------------------- |
+| **Type**       | `enum (of string)`           |
+| **Required**   | No                           |
+| **Defined in** | #/definitions/booking-status |
+
+**Description:** Booking lifecycle status. COMPLETED_MIXED = some sessions completed, others cancelled/no-show.
+
+Must be one of:
+* "PENDING"
+* "CONFIRMED"
+* "COMPLETED"
+* "CANCELLED"
+* "CANCELLATION_REQUESTED"
+* "COMPLETED_MIXED"
+
+----------------------------------------------------------------------------------------------------------------------------
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-03-09 at 13:15:53 +0000

package/data/docs/enums/customer-payment-status.md

@@ -0,0 +1,26 @@
+---
+title: "CustomerPaymentStatus"
+sidebar_label: "CustomerPaymentStatus"
+sidebar_position: 2
+---
+
+# CustomerPaymentStatus
+
+|                |                                       |
+| -------------- | ------------------------------------- |
+| **Type**       | `enum (of string)`                    |
+| **Required**   | No                                    |
+| **Defined in** | #/definitions/customer-payment-status |
+
+**Description:** Customer payment lifecycle status (D22). Tracks allocation progress of received payments.
+
+Must be one of:
+* "PENDING"
+* "CONFIRMED"
+* "PARTIALLY_APPLIED"
+* "FULLY_APPLIED"
+* "REFUNDED"
+* "CANCELLED"
+
+----------------------------------------------------------------------------------------------------------------------------
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-03-09 at 13:15:53 +0000

package/data/docs/enums/customer-payment-target-type.md

@@ -0,0 +1,23 @@
+---
+title: "CustomerPaymentTargetType"
+sidebar_label: "CustomerPaymentTargetType"
+sidebar_position: 3
+---
+
+# CustomerPaymentTargetType
+
+|                |                                            |
+| -------------- | ------------------------------------------ |
+| **Type**       | `enum (of string)`                         |
+| **Required**   | No                                         |
+| **Defined in** | #/definitions/customer-payment-target-type |
+
+**Description:** Target document type for customer payment allocation.
+
+Must be one of:
+* "BOOKING"
+* "ORDER"
+* "PURCHASE"
+
+----------------------------------------------------------------------------------------------------------------------------
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-03-09 at 13:15:53 +0000

package/data/docs/enums/delivery-type.md

@@ -0,0 +1,23 @@
+---
+title: "DeliveryType"
+sidebar_label: "DeliveryType"
+sidebar_position: 4
+---
+
+# DeliveryType
+
+|                |                             |
+| -------------- | --------------------------- |
+| **Type**       | `enum (of string)`          |
+| **Required**   | No                          |
+| **Defined in** | #/definitions/delivery-type |
+
+**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.
+
+Must be one of:
+* "ON_SITE"
+* "PICK_UP"
+* "DELIVERY"
+
+----------------------------------------------------------------------------------------------------------------------------
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-03-09 at 13:15:53 +0000

package/data/docs/enums/event-status.md

@@ -0,0 +1,30 @@
+---
+title: "EventStatus"
+sidebar_label: "EventStatus"
+sidebar_position: 5
+---
+
+# EventStatus
+
+|                |                            |
+| -------------- | -------------------------- |
+| **Type**       | `enum (of string)`         |
+| **Required**   | No                         |
+| **Defined in** | #/definitions/event-status |
+
+**Description:** Ticketed event lifecycle (D32). Mobile-only today; Dashboard in Wave 4.
+
+Must be one of:
+* "DRAFT"
+* "ACTIVE"
+* "CANCELLED"
+* "COMPLETED"
+
+----------------------------------------------------------------------------------------------------------------------------
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-03-09 at 13:15:53 +0000
+
+## Related Decisions
+
+| Decision | Title |
+|---|---|
+| **D32** | Event/Ticket status casing |

package/data/docs/enums/fulfillment-status.md

@@ -0,0 +1,32 @@
+---
+title: "FulfillmentStatus"
+sidebar_label: "FulfillmentStatus"
+sidebar_position: 6
+---
+
+# FulfillmentStatus
+
+|                |                                  |
+| -------------- | -------------------------------- |
+| **Type**       | `enum (of string)`               |
+| **Required**   | No                               |
+| **Defined in** | #/definitions/fulfillment-status |
+
+**Description:** Delivery/fulfillment lifecycle (D34). Optional — null for in-person orders.
+
+Must be one of:
+* "PREPARING"
+* "PARTIALLY_SHIPPED"
+* "SHIPPED"
+* "IN_TRANSIT"
+* "DELIVERED"
+* "PICKED_UP"
+
+----------------------------------------------------------------------------------------------------------------------------
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-03-09 at 13:15:53 +0000
+
+## Related Decisions
+
+| Decision | Title |
+|---|---|
+| **D34** | Order status decomposition into orthogonal fields |

package/data/docs/enums/loyalty-transaction-type.md

@@ -0,0 +1,32 @@
+---
+title: "LoyaltyTransactionType"
+sidebar_label: "LoyaltyTransactionType"
+sidebar_position: 7
+---
+
+# LoyaltyTransactionType
+
+|                |                                        |
+| -------------- | -------------------------------------- |
+| **Type**       | `enum (of string)`                     |
+| **Required**   | No                                     |
+| **Defined in** | #/definitions/loyalty-transaction-type |
+
+**Description:** Loyalty point transaction type (D07). SCREAMING_SNAKE past tense.
+
+Must be one of:
+* "EARNED"
+* "REDEEMED"
+* "ADJUSTED"
+* "EXPIRED"
+* "BONUS"
+* "REFUND"
+
+----------------------------------------------------------------------------------------------------------------------------
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-03-09 at 13:15:53 +0000
+
+## Related Decisions
+
+| Decision | Title |
+|---|---|
+| **D07** | Canonical loyalty transaction type values |

package/data/docs/enums/order-status.md

@@ -0,0 +1,65 @@
+---
+title: "OrderStatus"
+sidebar_label: "OrderStatus"
+sidebar_position: 8
+---
+
+# OrderStatus
+
+|                |                            |
+| -------------- | -------------------------- |
+| **Type**       | `enum (of string)`         |
+| **Required**   | No                         |
+| **Defined in** | #/definitions/order-status |
+
+**Description:** Core order lifecycle status (D03, D34). Universal across all business types. Replaces the Dashboard's legacy 20-value flat enum (MIG-11).
+
+Must be one of:
+* "PENDING"
+* "CONFIRMED"
+* "PROCESSING"
+* "READY"
+* "COMPLETED"
+* "CANCELLED"
+* "EXPIRED"
+
+----------------------------------------------------------------------------------------------------------------------------
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-03-09 at 13:15:53 +0000
+
+## Related Decisions
+
+| Decision | Title |
+|---|---|
+| **D03** | CONFIRMED vs PROCESSING for order lifecycle |
+| **D13** | Mobile order status support breadth |
+| **D34** | Order status decomposition into orthogonal fields |
+
+## Legacy Values — Migration Guide (MIG-11)
+
+This enum replaces the **Dashboard flat 20-value OrderStatus**. Use the table below when migrating existing Firestore documents.
+
+> **Note:** REFUND_PROCESSING and REFUNDED map to paymentStatus, not returnStatus — an order can be refunded without a physical return.
+
+| Legacy value | `status` | `paymentStatus` | `fulfillmentStatus` | `returnStatus` |
+|---|---|---|---|---|
+| `PENDING` | `PENDING` | — | — | — |
+| `CONFIRMED` | `CONFIRMED` | — | — | — |
+| `PROCESSING` | `PROCESSING` | — | — | — |
+| `READY` | `READY` | — | — | — |
+| `COMPLETED` | `COMPLETED` | — | — | — |
+| `CANCELLED` | `CANCELLED` | — | — | — |
+| `EXPIRED` | `EXPIRED` | — | — | — |
+| `AWAITING_PAYMENT` | `PENDING` | `PENDING` | — | — |
+| `SHIPPED` | `PROCESSING` | — | `SHIPPED` | — |
+| `PARTIALLY_SHIPPED` | `PROCESSING` | — | `PARTIALLY_SHIPPED` | — |
+| `ON_THE_WAY` | `PROCESSING` | — | `IN_TRANSIT` | — |
+| `DELIVERED` | `COMPLETED` | — | `DELIVERED` | — |
+| `PICKED_UP` | `COMPLETED` | — | `PICKED_UP` | — |
+| `RETURN_REQUESTED` | `COMPLETED` | — | — | `RETURN_REQUESTED` |
+| `RETURN_PROCESSING` | `COMPLETED` | — | — | `RETURN_PROCESSING` |
+| `RETURNED` | `COMPLETED` | — | — | `RETURNED` |
+| `EXCHANGE_REQUESTED` | `COMPLETED` | — | — | `EXCHANGE_REQUESTED` |
+| `EXCHANGE_PROCESSING` | `COMPLETED` | — | — | `EXCHANGE_PROCESSING` |
+| `EXCHANGE_COMPLETED` | `COMPLETED` | — | — | `EXCHANGE_COMPLETED` |
+| `REFUND_PROCESSING` | `COMPLETED` | `REFUND_PROCESSING` | — | — |
+| `REFUNDED` | `COMPLETED` | `REFUNDED` | — | — |

package/data/docs/enums/payment-method.md

@@ -0,0 +1,36 @@
+---
+title: "PaymentMethod"
+sidebar_label: "PaymentMethod"
+sidebar_position: 9
+---
+
+# PaymentMethod
+
+|                |                              |
+| -------------- | ---------------------------- |
+| **Type**       | `enum (of string)`           |
+| **Required**   | No                           |
+| **Defined in** | #/definitions/payment-method |
+
+**Description:** Unified payment method set with African + global methods (D02).
+
+Must be one of:
+* "CASH"
+* "CREDIT_CARD"
+* "ORANGE_MONEY"
+* "WAVE"
+* "MTN_MONEY"
+* "MOOV_MONEY"
+* "BANK_TRANSFER"
+* "PAYPAL"
+* "STRIPE"
+* "OTHER"
+
+----------------------------------------------------------------------------------------------------------------------------
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-03-09 at 13:15:53 +0000
+
+## Related Decisions
+
+| Decision | Title |
+|---|---|
+| **D02** | Canonical PaymentMethod enum set |

package/data/docs/enums/payment-proof-status.md

@@ -0,0 +1,23 @@
+---
+title: "PaymentProofStatus"
+sidebar_label: "PaymentProofStatus"
+sidebar_position: 10
+---
+
+# PaymentProofStatus
+
+|                |                                    |
+| -------------- | ---------------------------------- |
+| **Type**       | `enum (of string)`                 |
+| **Required**   | No                                 |
+| **Defined in** | #/definitions/payment-proof-status |
+
+**Description:** Payment proof review status. Used by Order and Booking payment proof workflows.
+
+Must be one of:
+* "PENDING"
+* "APPROVED"
+* "REJECTED"
+
+----------------------------------------------------------------------------------------------------------------------------
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-03-09 at 13:15:53 +0000

package/data/docs/enums/payment-status.md

@@ -0,0 +1,34 @@
+---
+title: "PaymentStatus"
+sidebar_label: "PaymentStatus"
+sidebar_position: 11
+---
+
+# PaymentStatus
+
+|                |                              |
+| -------------- | ---------------------------- |
+| **Type**       | `enum (of string)`           |
+| **Required**   | No                           |
+| **Defined in** | #/definitions/payment-status |
+
+**Description:** Payment lifecycle status (D01 amended). Used by Order, Sale/Purchase, Booking.
+
+Must be one of:
+* "PENDING"
+* "PAID"
+* "PARTIALLY_PAID"
+* "FAILED"
+* "REFUND_PROCESSING"
+* "REFUNDED"
+* "PARTIALLY_REFUNDED"
+
+----------------------------------------------------------------------------------------------------------------------------
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-03-09 at 13:15:53 +0000
+
+## Related Decisions
+
+| Decision | Title |
+|---|---|
+| **D01** | Canonical PaymentStatus enum set |
+| **D34** | Order status decomposition into orthogonal fields |

package/data/docs/enums/return-status.md

@@ -0,0 +1,32 @@
+---
+title: "ReturnStatus"
+sidebar_label: "ReturnStatus"
+sidebar_position: 12
+---
+
+# ReturnStatus
+
+|                |                             |
+| -------------- | --------------------------- |
+| **Type**       | `enum (of string)`          |
+| **Required**   | No                          |
+| **Defined in** | #/definitions/return-status |
+
+**Description:** Post-sale return/exchange lifecycle (D34). Optional — null until return or exchange initiated.
+
+Must be one of:
+* "RETURN_REQUESTED"
+* "RETURN_PROCESSING"
+* "RETURNED"
+* "EXCHANGE_REQUESTED"
+* "EXCHANGE_PROCESSING"
+* "EXCHANGE_COMPLETED"
+
+----------------------------------------------------------------------------------------------------------------------------
+Generated using [json-schema-for-humans](https://github.com/coveooss/json-schema-for-humans) on 2026-03-09 at 13:15:53 +0000
+
+## Related Decisions
+
+| Decision | Title |
+|---|---|
+| **D34** | Order status decomposition into orthogonal fields |