@fluentcommerce/ai-skills 0.8.2 → 0.8.3

package/content/knowledge/platform/domain-model.md

@@ -559,7 +559,7 @@ event into the workflow engine — enabling automatic rule execution on entity c
 
 **Key implications:**
 - **No CREATE event** (Location, Virtual Catalogue, Control Group): Entity creation does NOT trigger workflow rules. You must send an explicit event (e.g., `LOCATION_CREATED`) to kick off processing.
-- **Has CREATE event** (Order, Fulfilment, etc.): The `createOrder`, `createFulfilment`, etc. mutations automatically fire a `CREATE` event. Workflows can have a ruleset triggered by `entityType: "ORDER"`, `eventName: "CREATE"` to begin processing immediately.
+- **Has CREATE event** (Order, Fulfilment, etc.): The `createOrder`, `createFulfilment`, etc. mutations automatically fire a `CREATE` event. Workflows can have a ruleset triggered by `entityType: "ORDER"`, `eventName: "CREATE"` to begin processing immediately. See `knowledge/platform/create-order-reference.md` for full mutation input schemas, fulfilmentChoice wiring, and ORDER::MULTI patterns.
 - **Sub-entities inherit the parent workflow**: A Fulfilment's statuses and rulesets are defined within the Order workflow (or a dedicated Fulfilment workflow). The workflow engine routes events by `entityType` + `entitySubtype`.
 
 ---

package/content/knowledge/platform/workflow-design.md

@@ -106,6 +106,24 @@ When an orchestrable entity is created, it is assigned to the **latest active ma
 
 **Platform behavior:** Fluent no longer auto-bumps major versions. The platform always makes a **minor version bump** on update. Major version bumps are the developer's responsibility.
 
+### Concrete Example: Major Version Boundary in Action
+
+```
+Timeline:
+  1. Workflow ORDER::CC is at v99.10
+  2. Order #A is created → assigned to major 99 (uses v99.10)
+  3. Developer makes breaking ruleset changes and uploads v100.0
+  4. Order #A continues processing on major 99 (still v99.10)
+     — every event on Order #A executes against v99.10, NOT v100.0
+  5. Developer patches v99.11 (minor bump on old major)
+     → Order #A now uses v99.11 immediately
+  6. Order #B is created → assigned to major 100 (uses v100.0)
+  7. Order #A still on major 99, Order #B on major 100
+     — they coexist with different workflow logic
+```
+
+The major version acts as a **hard boundary** protecting in-flight entities. Entities never cross major versions automatically — they stay on the major they were assigned at creation and always use its latest minor.
+
 ### Migration Responsibility
 
 If existing entities need to move to a new major version, the developer must handle migration (state changes, attribute updates, webhooks, etc.). The platform does not auto-migrate.

package/content/mcp-extn/skills/fluent-mcp-core/SKILL.md

@@ -81,7 +81,7 @@ Run `health.ping` to confirm config readiness and SDK adapter status.
 | `health.ping` fails | No active profile | Run `fluent profile active` |
 | Auth error | Expired token | Run `fluent profile update <PROFILE> --password <new-pass>` |
 | Empty workflow list | Wrong retailer ref | Check `fluent profile retailers <PROFILE>` |
-| Server won't start | CLI not in PATH | `npm i -g @fluentcommerce/cli` |
+| Server won't start | CLI not in PATH | Install from [docs.fluentcommerce.com](https://docs.fluentcommerce.com/building-blocks/fluent-cli-package) |
 
 ## Transport Modes
 

package/content/mcp-extn/skills/fluent-mcp-tools/SKILL.md

@@ -231,7 +231,7 @@ Use `graphql.query` for one-off queries with manual pagination. Mutations are no
 
 ```json
 {
-  "query": "{ orders(first: 10, status: \"BOOKED\") { edges { node { id ref status totalPrice } } pageInfo { hasNextPage endCursor } } }"
+  "query": "{ orders(first: 10, status: \"BOOKED\") { edges { cursor node { id ref status totalPrice } } pageInfo { hasNextPage } } }"
 }
 ```
 

package/docs/dev-workflow.md

@@ -204,11 +204,14 @@ Use MCP `graphql.query`:
 { orders(ref: ["<REF>"], first: 1) { edges { node {
   id ref type status createdOn updatedOn
   attributes { name type value }
-  fulfilmentChoice { edges { node { id ref type status deliveryType } } }
-  items { edges { node { ref quantity status fulfilmentChoiceRef } } }
+  fulfilmentChoice { id ref type status deliveryType }
+  fulfilmentChoices { edges { node { id ref type status deliveryType } } }
+  items { edges { node { ref quantity status fulfilmentChoice { id ref type status deliveryType } } } }
 } } } }
 ```
 
+Use `items[].fulfilmentChoiceRef` only on `createOrder` input. For schema-validated `ORDER::MULTI` input and readback patterns, see `content/knowledge/platform/create-order-reference.md`.
+
 **Fulfilments:**
 ```graphql
 { fulfilments(ref: ["<REF>"], first: 1) { edges { node {

package/docs/fluent-ai-skills-reference.md

@@ -100,7 +100,7 @@ npx @fluentcommerce/ai-skills install --profile YOUR_PROFILE --profile-retailer
 
 ```mermaid
 graph LR
-    A["1. Install Fluent CLI<br/>npm i -g @fluentcommerce/cli"] --> B["2. Create profile<br/>fluent profile create MY_PROFILE"]
+    A["1. Install Fluent CLI<br/>docs.fluentcommerce.com/building-blocks/fluent-cli-package"] --> B["2. Create profile<br/>fluent profile create MY_PROFILE"]
     B --> C["3. Install skills<br/>npx @fluentcommerce/ai-skills install<br/>--profile MY_PROFILE"]
     C --> D["4. Connect workspace<br/>/fluent-connect"]
     D --> E["5. Start working<br/>Explain how HD works"]
@@ -231,7 +231,7 @@ Every artifact is scoped under `accounts/<PROFILE>/`. Directories are created on
 ```
 fluent-ai-workspace/
 ├── .mcp.json                        ← MCP server config (auto-generated, gitignored)
-├── CLAUDE.md                        ← Project instructions for the AI (auto-generated)
+├── CLAUDE.md                        ← Starter workspace instructions (auto-generated, safe to edit)
 └── accounts/<PROFILE>/              ← All data scoped to your Fluent account
     │
     ├── SOURCE/                      ← Implementation source code (shared across retailers)

package/docs/getting-started.md

@@ -29,7 +29,7 @@ A hands-on walkthrough for first-time users of `@fluentcommerce/ai-skills`. Foll
 | Requirement | How to check |
 |-------------|-------------|
 | Node.js 18+ | `node --version` |
-| Fluent CLI installed | `fluent --version` (install with `npm i -g @fluentcommerce/cli`) |
+| Fluent CLI installed | `fluent --version` (install from [docs.fluentcommerce.com](https://docs.fluentcommerce.com/building-blocks/fluent-cli-package)) |
 | A Fluent Commerce account | Base URL, credentials, and a retailer to work with |
 | A Fluent CLI profile configured | `fluent profile create YOUR_PROFILE --id <id> --username <user> --password <pass> --client-secret <secret> --base-url <url>` |
 | Claude Code | The supported AI IDE |
@@ -432,7 +432,7 @@ The AI never makes changes without asking first:
 
 ```bash
 # 1. Verify Fluent CLI
-fluent --version                          # should print version; if not: npm i -g @fluentcommerce/cli
+fluent --version                          # should print version; if not: https://docs.fluentcommerce.com/building-blocks/fluent-cli-package
 
 # 2. Verify profile
 ls ~/.fluentcommerce/YOUR_PROFILE/        # should exist; if not: fluent profile create YOUR_PROFILE ...

package/docs/use-cases.md

@@ -1163,7 +1163,7 @@ These errors come from the MCP extension server when calling Fluent Commerce API
 
 **"Workflow download fails or returns empty"**
 - Check you have the right profile and retailer: `fluent workflow list -p YOUR_PROFILE -r YOUR_RETAILER`
-- Fluent CLI must be installed: `npm i -g @fluentcommerce/cli`
+- Fluent CLI must be installed: see [install guide](https://docs.fluentcommerce.com/building-blocks/fluent-cli-package)
 - The profile must have the retailer associated — verify with `fluent profile retailers YOUR_PROFILE`
 
 **"The AI keeps asking me to approve a plan"**

package/docs/workflow-reference.md

@@ -67,8 +67,10 @@ When `source: "settings.<KEY>"` is used in a user action attribute, the UI popul
 ## ORDER::MULTI Workflow — Test Reference
 
 Key points:
+- Canonical `createOrder` contract: `content/knowledge/platform/create-order-reference.md`
 - Order `type` must be `"MULTI"` (not `"HD"`)
-- Items MUST include `fulfilmentChoiceRef` to link to FC
+- On mutation input, items MUST include `fulfilmentChoiceRef` to link to FC
+- On readback queries, verify the link via `items[].fulfilmentChoice { ... }` — do not expect an `OrderItem.fulfilmentChoiceRef` scalar
 - FC needs `sourcingLocationRef` attribute
 - FC `type` (routing) ≠ fulfilment `type` (created fulfilment)
-- Flow: `CREATE` → `SkipFraudCheck` → `ON_VALIDATION` → `ConfirmValidation` → `ProcessOrder` → `RouteFulfilmentChoice` → `ProcessHDFulfilmentChoice` → `CreateFulfilmentFromSourcingLocation`
+- Flow: `CREATE` → `SkipFraudCheck` → `ON_VALIDATION` → `ConfirmValidation` → `ProcessOrder` → `RouteFulfilmentChoice` → `ProcessHDFulfilmentChoice` → `CreateFulfilmentFromSourcingLocation`

package/metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.8.1",
+  "version": "0.8.3",
   "organization": "Fluent Commerce",
   "date": "March 2026",
   "package": "@fluentcommerce/ai-skills",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluentcommerce/ai-skills",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "[Experimental] Fluent Commerce domain knowledge for Claude Code. Skills, agents, and MCP server configs for workflows, events, rules, and APIs.",
   "keywords": [
     "fluent-commerce",