@fluentcommerce/ai-skills 0.8.2 → 0.8.3

package/content/cli/skills/fluent-connect/SKILL.md

@@ -1019,7 +1019,7 @@ When the user runs `/fluent-connect` with a different profile than currently con
 |-------|-------|-----------|
 | 0 | workspace-state.json corrupted | Delete and re-run full discovery |
 | 1 | No profiles exist | Delegate to `/fluent-profile` |
-| 1 | `fluent` CLI not found | Install: `npm i -g @fluentcommerce/cli` |
+| 1 | `fluent` CLI not found | Install from [docs.fluentcommerce.com](https://docs.fluentcommerce.com/building-blocks/fluent-cli-package) |
 | 2 | No retailers for profile | Register via `fluent profile update` or `/fluent-cli-retailer` |
 | 3 | mcp-setup fails | Check `npx @fluentcommerce/ai-skills --help` works and retry mcp-setup |
 | 3 | connection.test auth failure | Update credentials: `fluent profile update <PROFILE> --username <user> --password <pass>` |

package/content/dev/skills/fluent-e2e-test/SKILL.md

@@ -11,6 +11,8 @@ cursor-tier: auto
 
 Run automated test sequences against Fluent Commerce workflows. Discover environment configuration, create entities with real refs, fire events in sequence, poll for state transitions, and report pass/fail results.
 
+**Knowledge dependency:** For the full `createOrder` input schema, mutation patterns (HD, CC, MULTI, mixed), fulfilmentChoice wiring, and query gotchas, see `knowledge/platform/create-order-reference.md`.
+
 ## Pre-flight: Feedback Check
 
 Before starting, check for past learnings from this skill:
@@ -325,7 +327,7 @@ After sending an event, the entity status changes asynchronously. Use this patte
 
 **Step 1 — Create Order:**
 
-Run `/fluent-test-data` to generate the `createOrder` mutation with discovered refs. The skill queries locations, products, catalogues, and customers — then builds the mutation payload dynamically. See `/fluent-test-data` for the full discovery and creation flow.
+Run `/fluent-test-data` to generate the `createOrder` mutation with discovered refs. The skill queries locations, products, catalogues, and customers — then builds the mutation payload dynamically. See `knowledge/platform/create-order-reference.md` for the full type tree, patterns (HD, CC, split shipment), and gotchas.
 
 **Step 2 — ConfirmValidation (triggers full cascade):**
 ```

package/content/dev/skills/fluent-event-api/SKILL.md

@@ -924,6 +924,7 @@ Compact patterns for common external system integration event flows.
 - **Event name:** `CREATE` (auto-generated on `createOrder` mutation)
 - **Pattern:** Ecommerce platform → createOrder GraphQL mutation → ORDER workflow auto-triggers
 - **Note:** The `CREATE` event is implicit — no explicit event.send needed. The mutation triggers it.
+- **Full mutation reference:** `knowledge/platform/create-order-reference.md` — type tree, HD/CC/split patterns, fulfilmentChoice linkage, gotchas
 
 ### SendEvent Classification
 

package/content/dev/skills/fluent-feature-explain/SKILL.md

@@ -140,6 +140,7 @@ Check for project-specific knowledge that should inform feature explanation:
 
 3. Read matching knowledge files — typically:
    - `knowledge/platform/domain-model.md` — use for entity edges, cross-domain relationships, valid GraphQL connections
+   - `knowledge/platform/create-order-reference.md` — createOrder input schema, fulfilmentChoice wiring, ORDER::MULTI patterns. Use when explaining order intake flows.
    - `accounts/<PROFILE>/knowledge/client/business-rules.md` — use for business context of rules and workflows
    - `accounts/<PROFILE>/knowledge/client/data-model.md` — use for entity types, subtypes, attribute schemas
 4. Apply knowledge silently — do NOT show raw knowledge to user, just use it to produce better explanations

package/content/dev/skills/fluent-feature-plan/SKILL.md

@@ -92,6 +92,7 @@ Check for project-specific knowledge that should inform feature planning:
    - `accounts/<PROFILE>/knowledge/client/data-model.md` — use for entity types, attribute schemas
    - `accounts/<PROFILE>/knowledge/client/integrations.md` — use for integration touchpoints
    - `knowledge/platform/rule-development-contract.md` — **MANDATORY**: annotation contract (`@ParamString` vs `@EventAttribute`), reading patterns, enhancement protocol for Rules Inventory section
+   - `knowledge/platform/create-order-reference.md` — createOrder/createReturnOrder/createFulfilment input schemas, fulfilmentChoice wiring, ORDER::MULTI patterns. Use when planning features that create or modify orders.
 4. If `accounts/<PROFILE>/memory/index.md` exists, read the top account-specific gotchas and apply them silently while planning.
 5. Also check `accounts/<PROFILE>/knowledge/templates/plan-addendum.md` — if it exists, append its sections to the plan
 6. Apply knowledge throughout the plan — naming, constraints, architecture patterns. Do NOT show raw knowledge to user.

package/content/dev/skills/fluent-mystique-builder/SKILL.md

@@ -827,7 +827,7 @@ Routes come in three types:
   "component": "fc.page",
   "nav": { "label": "i18n:fc.orders.list.nav", "icon": "list" },
   "data": {
-    "query": "query { orders(first: 25) { edges { node { id ref status type createdOn } } pageInfo { hasNextPage endCursor } } }"
+    "query": "query { orders(first: 25) { edges { cursor node { id ref status type createdOn } } pageInfo { hasNextPage } } }"
   },
   "props": { "title": "i18n:fc.orders.list.title" },
   "descendants": [],
@@ -1164,7 +1164,7 @@ The standard paginated list page with filtering:
   "component": "fc.page",
   "nav": { "label": "i18n:fc.orders.list.nav", "icon": "shopping_cart" },
   "data": {
-    "query": "query($retailerId: [Int!], $orders_first: Int, $status: [String], $type: [String], $createdOn: DateRange) { orders(retailerId: $retailerId, first: $orders_first, status: $status, type: $type, createdOn: $createdOn) { edges { node { id ref status type totalPrice createdOn customer { firstName lastName } } } pageInfo { hasNextPage endCursor } } }",
+    "query": "query($retailerId: [Int!], $orders_first: Int, $status: [String], $type: [String], $createdOn: DateRange) { orders(retailerId: $retailerId, first: $orders_first, status: $status, type: $type, createdOn: $createdOn) { edges { node { id ref status type totalPrice createdOn customer { firstName lastName } } } pageInfo { hasNextPage } } }",
     "variables": {
       "orders_first": 25,
       "retailerId": "{{activeRetailer.id}}"
@@ -1594,7 +1594,6 @@ query($first: Int, $after: String) {
     }
     pageInfo {
       hasNextPage
-      endCursor
     }
   }
 }

package/content/dev/skills/fluent-mystique-scaffold/SDK_REFERENCE.md

@@ -90,7 +90,7 @@ if (orderResult.error) return <ErrorDisplay error={orderResult.error} />;
 const order = orderResult.data?.orderById;
 ```
 
-Results follow the Relay connection pattern: `edges[].node`, `pageInfo { hasNextPage, endCursor }`.
+Results follow the Relay connection pattern: `edges[].node`, `edges[].cursor`, `pageInfo { hasNextPage }`. Cursor lives on each edge, not on pageInfo.
 
 **Prefer page query data over useQuery** — only use useQuery for follow-up queries not available in the page data context. Page queries are defined in the manifest `data` block and auto-executed.
 
@@ -612,7 +612,7 @@ Every Relay connection (`edges/node` pattern) in Fluent GraphQL supports paginat
 query { orderById(id: $id) { items { edges { node { ref } } } } }
 
 # GOOD — bounded, paginate if needed
-query { orderById(id: $id) { items(first: 50) { edges { node { ref } } pageInfo { hasNextPage endCursor } } } }
+query { orderById(id: $id) { items(first: 50) { edges { cursor node { ref } } pageInfo { hasNextPage } } } }
 ```
 
 **Guidelines:** `first: 20-50` for on-screen lists. `first: 100-200` only for processing. Implement cursor-based pagination when `hasNextPage` is true.

package/content/dev/skills/fluent-mystique-scaffold/TEMPLATES.md

@@ -742,10 +742,9 @@ export function extractEdgeNodes<T>(connection: { edges?: Array<{ node: T }> } |
 
 /** Standard Relay connection shape from Fluent GraphQL */
 export interface RelayConnection<T> {
-  edges: Array<{ node: T }>;
+  edges: Array<{ cursor?: string; node: T }>;
   pageInfo?: {
     hasNextPage: boolean;
-    endCursor: string | null;
   };
 }
 ```

package/content/dev/skills/fluent-mystique-sdk-reference/SKILL.md

@@ -104,8 +104,8 @@ const OrderDetail = ({ orderId }: { orderId: string }) => {
   const order = data?.orderById;
   // Connection/pagination pattern:
   // data.orders.edges[].node — array of entities
+  // data.orders.edges[].cursor — cursor for pagination (on each edge, not pageInfo)
   // data.orders.pageInfo.hasNextPage — boolean
-  // data.orders.pageInfo.endCursor — cursor for next page
   return <div>{order.ref} — {order.status}</div>;
 };
 ```
@@ -361,7 +361,7 @@ const [result] = useQuery<ResultType>(queryString, { variables });
 // result.error    — CombinedError | undefined
 ```
 
-Results follow the Relay connection pattern: `edges[].node`, `pageInfo { hasNextPage, endCursor }`.
+Results follow the Relay connection pattern: `edges[].node`, `edges[].cursor`, `pageInfo { hasNextPage }`. Note: cursor lives on each edge, not on pageInfo.
 
 **Prefer page query data over useQuery** — only use useQuery for follow-up queries not available in the page data context. Page queries are defined in the manifest `data` block and auto-executed.
 

package/content/dev/skills/fluent-pre-deploy-check/SKILL.md

@@ -418,6 +418,31 @@ workflow.diff({
 
 **Details captured:** Rulesets added, modified, removed. Risk level for each removal.
 
+#### Gate 3.45: Workflow Major Version Impact
+
+**Severity:** HIGH
+
+**Tool:** `workflow.get` or `workflow.list` (MCP fluent-mcp-extn) + Read (local workflow JSON)
+
+**Invocation:**
+For each workflow JSON being deployed:
+1. Read the `version` field from the local workflow JSON (format: `<major>.<minor>`)
+2. Fetch the currently deployed version via `workflow.get({ entityType, entitySubtype })` or `workflow.list`
+3. Parse both versions and compare major components
+
+**Pass criteria (INFO):** Minor version bump only (e.g., 1.2 → 1.3). All existing entities on that major version will use the new workflow immediately. No entity isolation boundary changes.
+
+**Pass criteria (WARN):** Major version bump detected (e.g., 99.10 → 100.0). This is valid but has significant behavioral impact:
+- Existing entities (orders, fulfilments, etc.) stay pinned to the **old major** and will continue using its latest minor — they will **never** execute against the new major's rulesets
+- Only **newly created** entities will be assigned to the new major version
+- If the intent was to update all entities (including in-flight), a **minor bump** is required instead
+
+**Fail criteria:** None — major bumps are valid. But the gate MUST emit a prominent warning so the deployer consciously acknowledges the entity isolation impact.
+
+**Edge case:** First deployment (no deployed version exists) — pass with note "First deployment, no version comparison needed."
+
+**Details captured:** Local version, deployed version, bump type (major/minor), number of major versions apart, explicit impact statement.
+
 #### Gate 3.5: User Action Schema Validity
 
 **Severity:** HIGH

package/content/dev/skills/fluent-sourcing/SKILL.md

@@ -33,6 +33,10 @@ Expert reference for the Fluent Commerce Responsive Sourcing Framework (v2.1+).
 
 This is a **reference skill** — it provides domain knowledge and query patterns but does not modify code or Fluent environments. Use it to understand sourcing concepts, generate configuration JSON, and debug allocation decisions. Implementation changes (workflow edits, rule scaffolding, settings) should be delegated to the appropriate implementation skills listed in the Ownership Boundary above.
 
+## Related Knowledge
+
+- `knowledge/platform/create-order-reference.md` — how FulfilmentChoice entities are created inline with orders, item-to-FC linkage, and ORDER::MULTI patterns. Sourcing operates on FulfilmentChoice entities created by the order intake mutation.
+
 ## When to Use
 
 - **"How does sourcing work?"** — Conceptual Architecture section

package/content/dev/skills/fluent-test-data/SKILL.md

@@ -11,6 +11,8 @@ cursor-tier: auto
 
 Discover retailer configuration (locations, products, catalogues, networks, inventory, customers) via live GraphQL queries and generate valid entity creation payloads. Everything is queried — nothing is hardcoded.
 
+**Knowledge dependency:** For the full `createOrder` input schema, mutation patterns (HD, CC, MULTI, mixed), fulfilmentChoice wiring, and common mistakes, see `knowledge/platform/create-order-reference.md`.
+
 ## Pre-flight: Feedback Check
 
 Before starting, check for past learnings from this skill:
@@ -306,6 +308,8 @@ This summary is the input to entity creation. Every ref comes from live queries
 
 ## Phase 3: Entity Creation
 
+**Full createOrder mutation reference:** `knowledge/platform/create-order-reference.md` — complete type tree, all patterns (HD, CC, split shipment, financials), input-vs-return field differences, and gotchas (wrapper IDs, fulfilmentChoice singular vs plural, AttributeInput.value as Json scalar).
+
 ### Create Test Order (HD)
 
 Use discovered values to build the mutation. The `<TIMESTAMP>` should be generated as `YYYYMMDD_HHmmss` at execution time.

package/content/dev/skills/fluent-trace/SKILL.md

@@ -202,6 +202,13 @@ Use MCP `graphql.query` to fetch the entity's current status and key attributes:
           value
         }
         fulfilmentChoice {
+          id
+          ref
+          type
+          status
+          deliveryType
+        }
+        fulfilmentChoices {
           edges {
             node {
               id
@@ -218,7 +225,13 @@ Use MCP `graphql.query` to fetch the entity's current status and key attributes:
               ref
               quantity
               status
-              fulfilmentChoiceRef
+              fulfilmentChoice {
+                id
+                ref
+                type
+                status
+                deliveryType
+              }
             }
           }
         }
@@ -228,6 +241,8 @@ Use MCP `graphql.query` to fetch the entity's current status and key attributes:
 }
 ```
 
+For `createOrder` input patterns, `items[].fulfilmentChoiceRef` is still the correct join key. For live GraphQL readback on the validated schema, query `items[].fulfilmentChoice { ... }` instead. See `knowledge/platform/create-order-reference.md` for the full input-vs-query contract.
+
 **For a FULFILMENT:**
 ```graphql
 {

package/content/dev/skills/fluent-workflow-builder/SKILL.md

@@ -130,6 +130,10 @@ GraphQL Schema Validation:
 
 If any validation fails → fix before writing workflow JSON. If MCP is unavailable → proceed with warning.
 
+## Knowledge References
+
+- **Order creation patterns:** `knowledge/platform/create-order-reference.md` — createOrder input schema, fulfilmentChoice wiring, ORDER::MULTI patterns. Essential when building ORDER workflows that process items linked to different fulfilment choices.
+
 ## Ownership Boundary
 
 This skill owns workflow structure/design guidance and validation checklists.
@@ -941,7 +945,13 @@ Run through this before uploading any workflow:
 6. **Rule naming** — `<ACCOUNT>.<MODULE>.<RuleName>` format, all referenced rules exist in platform
 7. **Gate logic** — Gate statuses include all terminal states for child entities
 8. **Version bump** — Version is higher than currently deployed version
-9. **Description** — `versionComment` describes what changed
+9. **Major vs minor version choice** — Workflow versions use `<major>.<minor>` format. The choice matters:
+   - **Minor bump** (e.g., 1.2 → 1.3): All existing entities on that major version **immediately** use the new workflow. Use for backward-compatible changes (new rulesets, rule tweaks, prop changes).
+   - **Major bump** (e.g., 1.3 → 2.0): Only **newly created** entities use the new version. Existing entities stay on the old major (latest minor). Use for incompatible structural changes post go-live where in-flight entities must be protected.
+   - **During development:** Almost always use **minor** bumps — you want all test entities to pick up changes immediately.
+   - **Post go-live:** Use **major** bumps only when the change would break in-flight orders/fulfilments. Minor bumps are still preferred when changes are additive.
+   - **The platform always does minor bumps** on update via CLI (`fluent module install`). Major bumps require manual version editing.
+10. **Description** — `versionComment` describes what changed
 
 ## Post-Execution: Feedback Capture
 

package/content/dev/skills/fluent-workflow-deploy/SKILL.md

@@ -174,6 +174,33 @@ Additionally verify:
    - If `attributes` has entries: `source` MUST be empty `""` or `"settings.<key>"` (**lowercase** `settings.` — capital `"Settings."` silently fails). Referenced setting value MUST have `{ "active": [...] }` wrapper (plain array silently fails). `"OVERRIDE"` works on v4.80+. `defaultValue` MUST be empty `""` or literal (`"{{me.username}}"` works on v4.80+).
    - **If ANY of the first two checks fail, STOP deployment and report:** *"User action on ruleset [name] will be invisible in the UI. Fix: add `eventName` / add `subtype` before deploying."*
 
+### Step 1.05: Major Version Impact Check (MANDATORY)
+
+Compare the workflow version being deployed against the currently deployed version. If the **major version** has changed (e.g., 99.x → 100.0), this has significant behavioral impact:
+
+**Detection:**
+1. Read the `version` field from the workflow JSON being deployed
+2. Fetch the currently deployed version via `workflow.get` or `fluent workflow list`
+3. Parse both as `<major>.<minor>` — compare major components
+
+**If major version increased:**
+
+> **MAJOR VERSION WARNING**
+> Deploying `<WORKFLOW_NAME>` from v`<old>` → v`<new>` is a **major version bump**.
+>
+> **Impact on existing entities:**
+> - All entities created before this deploy stay on major `<old_major>` (latest minor of that major)
+> - They will **never** execute against v`<new>` rulesets — even for future events
+> - Only **newly created** entities will use major `<new_major>`
+>
+> **Is this intentional?**
+> - If YES (breaking changes, post go-live protection): proceed
+> - If NO (you want all entities to use the new logic): change the version to `<old_major>.<old_minor + 1>` (minor bump instead)
+
+**Present this warning to the user and wait for confirmation before proceeding.** A minor bump applies changes to all existing entities immediately; a major bump isolates new entities only. Choosing wrong can leave in-flight orders on stale logic or break them with incompatible changes.
+
+**If minor version increased (or first deployment):** Proceed without warning — minor bumps are backward-compatible and apply to all entities on that major version immediately.
+
 ### Step 1.1: Large workflow payload gate (MANDATORY)
 
 Before upload, keep workflow changes file-based and reviewable:

package/content/knowledge/index.md

@@ -24,6 +24,7 @@ Skills read these when relevant (based on `relevant-skills` in frontmatter):
 | File | Load When | Relevant Skills | Status |
 |------|-----------|-----------------|--------|
 | [platform/domain-model.md](platform/domain-model.md) | Entity relationships, GraphQL edges, cross-domain maps. Schema-validated. | workflow-builder, mystique-builder, rule-scaffold, feature-plan, custom-code, settings, trace, implementation-map, feature-explain, connection-analysis, scope-decompose, inventory-catalog | **Active** |
+| [platform/create-order-reference.md](platform/create-order-reference.md) | Building or validating `createOrder` payloads, especially `ORDER::MULTI`, `fulfilmentChoice(s)`, and item-to-FC linkage. | test-data, e2e-test, trace, event-api, workflow-builder, feature-plan, feature-explain | **Active** |
 | [platform/rule-development-contract.md](platform/rule-development-contract.md) | Rubix rule annotation contract, input channels, reading patterns, enhancement protocol. Derived from OOTB analysis (103 rules). | rule-scaffold, custom-code, feature-plan, feature-explain, build, workflow-builder, workflow-analyzer, pre-deploy-check | **Active** |
 | [platform/user-action-contract.md](platform/user-action-contract.md) | Canonical user action contract: visibility fields, rule mapping, FieldRegistry wiring, workflow-vs-manifest override precedence. | workflow-builder, workflow-analyzer, pre-deploy-check, workflow-deploy, mystique-builder, mystique-validate, settings | **Active** |
 | [platform/permissions-and-contexts.md](platform/permissions-and-contexts.md) | RBAC model: users, roles, context types/IDs, accretive scoping, Rubix user, deployment permissions, debugging. | rule-scaffold, custom-code, feature-plan, workflow-builder, settings, trace, implementation-map, bootstrap, pre-deploy-check, module-deploy, workflow-deploy, retailer-config, e2e-test | **Active** |
@@ -35,6 +36,7 @@ Skills read these when relevant (based on `relevant-skills` in frontmatter):
 | [platform/reusability-patterns.md](platform/reusability-patterns.md) | Reusability decision framework, naming, parameterization patterns for rules and components. | rule-scaffold, mystique-component, feature-plan, use-case-discover, mystique-scaffold, custom-code, feature-explain | **Active** |
 | [platform/roles-and-permissions.md](platform/roles-and-permissions.md) | RBAC model: three-layer access control, context types, label-only roles, custom role checking in rules, feature design questions. | use-case-discover, feature-plan, rule-scaffold, workflow-builder, mystique-builder | **Active** |
 | [platform/workflow-design.md](platform/workflow-design.md) | Workflow design principles: boundaries, versioning, flow control, cross-retailer/workflow communication, execution model, rulesets, settings. | workflow-builder, workflow-analyzer, workflow-deploy, feature-plan, use-case-discover, rule-scaffold, feature-explain, connection-analysis, pre-deploy-check | **Active** |
+| [platform/create-order-reference.md](platform/create-order-reference.md) | createOrder mutation patterns: HD, CC, MULTI, mixed-fulfilment, fulfilmentChoice linking, orderItem wiring, return orders, financial transactions. Schema-validated against live introspection. | test-data, e2e-test, event-api, workflow-builder, feature-plan, trace, retailer-config, sourcing | **Active** |
 | [client/business-rules.md](client/business-rules.md) | Building workflows, rules, or sourcing | workflow-builder, rule-scaffold, feature-plan, sourcing | Template |
 | [client/data-model.md](client/data-model.md) | Creating entities, writing GraphQL, building manifests | workflow-builder, mystique-builder, settings | Template |
 | [client/integrations.md](client/integrations.md) | Building rules that call external APIs | rule-scaffold, custom-code, feature-plan | Template |