@fluentcommerce/ai-skills 0.13.0 → 0.15.0

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

@@ -2114,8 +2114,8 @@ The `<namespace>` segment identifies WHO built the component. Choose based on co
 | Context | Namespace Strategy | Example |
 |---------|-------------------|---------|
 | **Fluent Commerce OOTB** | `fc` (reserved — never use) | `fc.list`, `fc.page`, `fc.card.attribute` |
-| **Partner / SI company** | Company abbreviation (2-6 chars, lowercase) | `acme`, `tcs`, `dxc`, `wipro` |
-| **Client / brand** | Brand abbreviation or project code | `nike`, `coles`, `woolies`, `proj1` |
+| **Partner / SI company** | Company abbreviation (2-6 chars, lowercase) | `acme`, `partner1`, `partner2`, `mysi` |
+| **Client / brand** | Brand abbreviation or project code | `brandx`, `retailx`, `storeco`, `proj1` |
 | **Feature-scoped** | Feature or domain name | `appeasement`, `returns`, `sourcing` |
 | **Internal / prototype** | Team or project prefix | `demo`, `poc`, `hackathon` |
 

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

@@ -1,6 +1,6 @@
 ---
 name: fluent-mystique-scaffold
-description: Scaffold a new Mystique SDK component project with webpack, TypeScript, Storybook, Jest, component registration, and i18n — ready to develop and deploy. Triggers on "scaffold component", "new mystique project", "create sdk component", "mystique sdk setup", "new ui plugin".
+description: Scaffold a new Mystique SDK component project with webpack, TypeScript, Storybook, Jest, component registration, and i18n ready to deploy. Use for creating new SDK component projects from scratch.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <project-name> [--components ComponentA,ComponentB] [--category content|layout|page|filter]
@@ -46,6 +46,17 @@ Check for project-specific knowledge that should inform the generated SDK projec
 4. If `accounts/<PROFILE>/memory/index.md` exists, read the top account-specific frontend, Storybook, test, and deployment gotchas and apply them silently.
 5. Apply knowledge silently — do NOT show raw knowledge to user, just follow the conventions in the generated scaffold
 
+## Prerequisites — New App Checklist
+
+Before scaffolding, verify the target environment is ready. Skip items that are already confirmed.
+
+1. **Target app exists** — The Fluent UX app (`oms`, `store`, or custom) must already exist in the environment. Manifests are deployed as settings attached to an app — if the app doesn't exist, deployment will fail silently.
+2. **Permissions configured** — The user or role deploying the manifest must have permission to create/update settings with `context: "ACCOUNT"`. Admin roles have this by default; custom roles may not.
+3. **SDK version compatibility** — Check the deployed app's SDK version (`sdk-version.json` at the app URL). The scaffolded project's `@anthropic-ai/sdk` and `@anthropic-ai/mystique-*` versions must be compatible with the runtime. Mismatches cause silent component registration failures.
+4. **Plugin hosting plan** — Know where the production bundle will be hosted (Vercel, S3, CloudFront, etc.). The scaffold produces `dist/bundle.[hash].js` — it needs a URL accessible from the browser.
+
+If prerequisites are unclear, recommend: `/fluent-retailer-config` (create entities), `/fluent-settings` (verify setting access), `/fluent-account-snapshot` (inspect environment state).
+
 ## OMX Component SDK — Source Template
 
 Every Mystique SDK project starts from the **OMX Component SDK** template zip (or an existing SDK source folder/repo provided by the user).
@@ -444,7 +455,7 @@ Present the full plan content to the user and wait for approval before generatin
 | `-> READY: <path>` | Project directory scaffolded | `-> READY: accounts/MY_PROFILE/SOURCE/frontend/mystique-plugin-curbside/` |
 | `-> NEXT: /fluent-<skill>` | Ready for manifest wiring | `-> NEXT: /fluent-mystique-builder` |
 | `-> BLOCKED: <reason>` | Cannot proceed | `-> BLOCKED: PLAN_REQUIRED -- Write a plan via /fluent-feature-plan` |
-| `-> SKIP: <reason>` | Existing project covers the domain | `-> SKIP: Extend existing project mystique-plugin-hm. Add component files directly` |
+| `-> SKIP: <reason>` | Existing project covers the domain | `-> SKIP: Extend existing project mystique-plugin-acme. Add component files directly` |
 
 ### Error codes
 

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

@@ -500,7 +500,7 @@ console.groupEnd();
 ```
 
 **Alias naming convention:** `<namespace>.<category>.<component-name>` where:
-- `namespace` is the company/project prefix (e.g., `acme`, `hm`, `curbside`)
+- `namespace` is the company/project prefix (e.g., `acme`, `globex`, `curbside`)
 - `category` is one of `page`, `layout`, `content`, `filter`
 - `component-name` is kebab-case (e.g., `order-tracker`, `store-map`)
 

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

@@ -1,11 +1,12 @@
 ---
 name: fluent-mystique-sdk-reference
-description: "Mystique Component SDK API REFERENCE LOOKUP — React hooks, composition primitives, field patterns, and Material-UI constraints. Read-only documentation lookup for building custom Fluent Commerce UI components. This IS a valid platform skill — NEVER classify as 'none' or 'direct knowledge lookup'. ROUTING PRIORITY — if the prompt says '/fluent-mystique-sdk-reference', 'useSettings hook', 'SDK hook signature', 'SDK reference documentation', 'hook API', 'composition API reference', 'SDK hook', or 'look up hook', route HERE. HARD NEGATIVE — Do NOT route here for: 'add component' / 'register component' / 'extend SDK project' (→ fluent-mystique-component). This skill is READ-ONLY reference documentation. Triggers on 'mystique hooks', 'sdk reference', 'component api', 'field registry', 'mystique sdk', 'SDK hook API', 'hook patterns', 'useSettings hook', 'what hook', 'SDK documentation lookup', 'hook signature', '/fluent-mystique-sdk-reference'."
+description: Mystique Component SDK API reference for React hooks, composition primitives, field patterns, and Material-UI constraints. Use for SDK hook lookups, API signatures, or component SDK documentation.
 user-invocable: true
 allowed-tools: Read, Glob, Grep
 argument-hint: [hook-name|pattern-name]
 cursor-tier: manual
 ---
+<!-- routing-notes: ROUTING PRIORITY — if the prompt says "useSettings hook", "SDK hook signature", "SDK reference documentation", "hook API", or "composition API reference", route HERE. HARD NEGATIVE — Do NOT route here for "add component", "register component", "extend SDK project" (→ fluent-mystique-component). This skill is READ-ONLY reference documentation. -->
 
 # Mystique Component SDK Reference
 

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

@@ -1,6 +1,6 @@
 ---
 name: fluent-pre-deploy-check
-description: Run a read-only pre-deployment checklist for Fluent Commerce modules and workflows. Validates environment readiness, module structure, workflow integrity, settings, and connection topology before deployment without building, packaging, or deploying artifacts. Triggers on "pre-deploy check", "deployment checklist", "ready to deploy", "deploy gate", "can I deploy", "deploy readiness".
+description: Run a read-only pre-deployment checklist validating environment readiness, module structure, workflow integrity, settings, and connection topology. Use for deploy-readiness checks before pushing artifacts.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [--profile <profile>] [--retailer <ref>] [--module-path <path>] [--skip <phase,...>]
@@ -10,7 +10,7 @@ planning-gate: advisory
 
 # Pre-Deployment Checklist
 
-Structured deployment gate between "build passes" and "deploy to retailer." Runs 9 phases of validation (29 backend gates + 5 frontend gates) producing a machine-readable pass/fail report that blocks deployment on critical failures.
+Structured deployment gate between "build passes" and "deploy to retailer." Runs 9 phases of validation (32 backend gates + 5 frontend gates) producing a machine-readable pass/fail report that blocks deployment on critical failures.
 
 This skill is the final checkpoint in the Agent-Driven Development (ADD) lifecycle, positioned at Phase 6 (Demo Deployment). It aggregates validation from multiple specialized skills and MCP tools into a single, traceable pre-flight report.
 
@@ -1008,7 +1008,7 @@ wc -c accounts/<PROFILE>/SOURCE/frontend/<project>/dist/bundle.*.js
 **Invocation:**
 If manifest settings were saved to disk via `outputFile` in Gate 5.1, run the Mystique validator against them:
 ```bash
-node content/dev/skills/fluent-mystique-assess/validator.mjs accounts/<PROFILE>/settings/backups/fc.mystique.manifest.*.json --json
+node fluent-ai-skills/tools/manifest-validator.mjs accounts/<PROFILE>/settings/backups/fc.mystique.manifest.*.json --json
 ```
 Alternatively, invoke `/fluent-mystique-assess` skill for each manifest file.
 

package/content/dev/skills/fluent-retailer-config/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-retailer-config
-description: Configure Fluent Commerce retailer environments by creating real platform entities — warehouse locations, store locations, networks, catalogues, inventory, carriers, and users via GraphQL. This is the canonical owner for "create warehouse", "create warehouse and store locations for this retailer", "set up locations for this retailer", "create network", or other retailer entity setup. Even if the user says "configure retailer", stay here when the nouns are locations, networks, carriers, or catalogues. Do NOT route key-value settings CRUD here. Triggers on "setup retailer", "create warehouse", "create warehouse and store locations", "create warehouse and store locations for this retailer", "create store location", "create location", "create network", "setup inventory", "retailer config", "environment setup".
+description: Configure Fluent Commerce retailer environments by creating platform entities like locations, networks, catalogues, inventory, carriers, and users via GraphQL. Use for retailer entity setup or environment configuration.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [--retailer <ref>] [--setup-type full|locations|networks|catalogues|inventory]
@@ -880,8 +880,8 @@ Variables:
 ```json
 {
   "input": {
-    "ref": "CARRIER_DHL",
-    "name": "DHL Express",
+    "ref": "CARRIER_FAST",
+    "name": "Fast Freight Carrier",
     "type": "SHIPPING",
     "retailer": { "id": "<retailerId>" }
   }

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

@@ -1,6 +1,6 @@
 ---
 name: fluent-rollback
-description: Roll back workflow and module deployments in Fluent Commerce. Supports workflow version revert, module redeploy of prior versions, and settings restore from audit trail. Triggers on "rollback", "revert deployment", "undo deploy", "roll back workflow", "restore previous version".
+description: Roll back workflow and module deployments in Fluent Commerce with version revert, module redeploy, and settings restore from audit trail. Use for rollback, revert, or restoring previous versions.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <workflow|module|settings> <name> [--profile PROFILE] [--retailer RETAILER_REF] [--to-version VERSION] [--dry-run]

package/content/dev/skills/fluent-rule-lookup/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: fluent-rule-lookup
-description: "OOTB RULE REFERENCE — search and discover out-of-the-box Fluent Commerce reference module rules by keyword, entity type, module, or capability. Queries MCP plugin_list first, falls back to offline catalog. ROUTING PRIORITY — if the prompt asks 'what does [RuleName] rule do', 'what parameters does [rule] accept', 'SendWebhook rule', 'OOTB rule documentation', or 'look up rule [name]', route HERE — do NOT route to fluent-custom-code. fluent-custom-code analyzes custom Java source code; this skill looks up OOTB platform rules. Does NOT reverse-engineer features (→ fluent-feature-explain) and does NOT scaffold new custom rules (→ fluent-rule-scaffold). Triggers on 'find rule', 'search rules', 'OOTB rule', 'what rule does', 'rule lookup', 'available rules', 'which rules', 'list rules', 'rule catalog', 'reference module rules', 'what does the [rule] rule do', 'what parameters does [rule] accept'."
+description: Search and discover out-of-the-box Fluent Commerce reference module rules by keyword, entity type, module, or capability via MCP plugin_list. Use for OOTB rule lookups, parameter reference, or rule catalog searches.
 user-invocable: true
 allowed-tools: Bash, Read, Glob, Grep
 argument-hint: <search-term> [--module core|order|fulfilment|inventory|base|globalinventory] [--entity ORDER|FULFILMENT|...] [--offline]
 cursor-tier: manual
 ---
+<!-- routing-notes: ROUTING PRIORITY — if the prompt asks "what does [RuleName] rule do", "what parameters does [rule] accept", "OOTB rule documentation", or "look up rule", route HERE — do NOT route to fluent-custom-code. fluent-custom-code analyzes custom Java source code; this skill looks up OOTB platform rules. Does NOT reverse-engineer features (→ fluent-feature-explain) and does NOT scaffold new rules (→ fluent-rule-scaffold). -->
 
 # OOTB Rule Lookup
 

package/content/dev/skills/fluent-rule-scaffold/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: fluent-rule-scaffold
-description: Scaffold new Fluent Commerce Rubix rules. Generates Java class, test class, and wires into module.json. Use this for NEW rule creation only. YIELD-BACK — if the prompt says "write tests for", "write unit tests", "generate tests for this rule", "test this rule", or "fix rule test", route to fluent-rule-test instead — that skill owns all test generation and repair for existing rules. YIELD-BACK — if the prompt says "analyze", "explain", or "understand" existing custom code, route to fluent-custom-code instead — this skill only CREATES new rules. Key knowledge — rule-development-contract.md (@ParamString vs @EventAttribute), graphql-in-rules.md (DynamicUtils vs Apollo), rule-test-patterns.md (test harness), module-structure.md (Maven layout). Triggers on "create rule", "new rule", "scaffold rule", "add rule class".
+description: Scaffold new Fluent Commerce Rubix rules with Java class, test class, and module.json wiring for NEW rule creation only. Use for creating new rules, not testing or analyzing existing ones.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <rule-name> [--entity-type ORDER|FULFILMENT|...] [--package common|fulfilment|order|...]
 cursor-tier: manual
 planning-gate: mandatory
 ---
+<!-- routing-notes: YIELD-BACK — if the prompt says "write tests for", "generate tests for this rule", "test this rule", or "fix rule test", route to fluent-rule-test instead. YIELD-BACK — if the prompt says "analyze", "explain", or "understand" existing custom code, route to fluent-custom-code instead — this skill only CREATES new rules. -->
 
 # Rule Scaffolder
 
@@ -288,7 +289,7 @@ If the same event hits twice due to a race condition, the rule should check curr
 ```java
 // GOOD: Idempotent — checks before creating
 @Override
-public void run(RuleContext context) {
+public void run(ContextWrapper context) {
     // Check if child entity already exists
     List<CreditMemo> existing = context.getEntity()
         .getCreditMemos().stream()
@@ -305,7 +306,7 @@ public void run(RuleContext context) {
 
 // BAD: Not idempotent — creates duplicate child entity on retry
 @Override
-public void run(RuleContext context) {
+public void run(ContextWrapper context) {
     // Directly creates without checking existence
     context.action().mutation(createCreditMemoMutation, variables);
 }
@@ -319,7 +320,7 @@ Never trust event payload values without validating against current entity state
 
 ```java
 @Override
-public void run(RuleContext context) {
+public void run(ContextWrapper context) {
     // 1. Validate entity is still in expected state
     String currentStatus = context.getEntity().getStatus();
     if (!"BOOKED".equals(currentStatus)) {
@@ -534,8 +535,8 @@ class <RULE_NAME>Test {
         when(context.action()).thenReturn(action);
         when(action.mutation()).thenReturn(mutationAction);
         when(action.eventAction()).thenReturn(eventAction);
-        when(event_getAccountId()).thenReturn("TEST_ACCOUNT");
-        when(event_getName()).thenReturn("TestEvent");
+        when(event.getAccountId()).thenReturn("TEST_ACCOUNT");
+        when(event.getName()).thenReturn("TestEvent");
     }
 
     @Test

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

@@ -1,12 +1,13 @@
 ---
 name: fluent-rule-test
-description: Generate or repair JUnit 5 unit tests for existing Fluent Commerce Rubix backend rule classes. ROUTING PRIORITY over fluent-rule-scaffold for ANY prompt that says "write tests for", "write unit tests", "generate tests for this rule", "test this rule", or "fix rule test" — even if it does not explicitly say "existing". If the prompt mentions testing or writing tests for a rule, route HERE. Rule scaffold is for creating NEW rule implementations from scratch; this skill owns all test generation and repair work. Use when Codex needs to add tests for an existing rule, backfill rule coverage, update rule fixtures after logic changes, regenerate tests after logic changes, or diagnose rule test failures. Triggers on "test Fluent rule", "write Rubix rule test", "generate backend rule test", "fix rule test", "write unit tests for this rule", "write tests for this", "write tests for", "test this rule", "generate tests".
+description: Generate or repair JUnit 5 unit tests for existing Fluent Commerce Rubix backend rule classes. Use for writing rule tests, backfilling coverage, updating fixtures, or diagnosing test failures.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <RuleName> [--style auto|rule-executor|test-executor|mockito|workflow] [--coverage full|happy-path]
 category: testing
 tags: [rule, test, junit, rubix, ruleexecutor, testexecutor]
 ---
+<!-- routing-notes: ROUTING PRIORITY over fluent-rule-scaffold for ANY prompt that says "write tests for", "write unit tests", "generate tests for this rule", "test this rule", or "fix rule test". Rule scaffold is for creating NEW rule implementations; this skill owns all test generation and repair work. -->
 
 # Rule Test Generator
 

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

@@ -1,6 +1,6 @@
 ---
 name: fluent-scope-plan
-description: Break approved specs into phased delivery plans with dependency-ordered task graphs. Identifies vertical slice delivery phases, then decomposes each phase into ordered tasks with skill mappings. Triggers on "phase this feature", "split into phases", "delivery phases", "decompose scope", "plan from scope", "task breakdown", "scope to tasks", "incremental delivery", "vertical slices".
+description: Break approved specs into phased delivery plans with dependency-ordered task graphs and vertical slice phases decomposed into ordered tasks. Use for delivery phasing, scope decomposition, or task breakdown.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [--profile PROFILE] [--feature SLUG] [--phases N] [--scope <path>] [--output-format json|markdown] [--validate-only] [--batch-features]
@@ -421,7 +421,7 @@ Perform Kahn's algorithm (BFS-based topological sort). The priority field reflec
 ### Skill Existence Validation
 
 After generating the task list, validate that every `skill` field references a real skill. Known valid skills:
-`fluent-module-scaffold`, `fluent-rule-scaffold`, `fluent-workflow-builder`, `fluent-build`, `fluent-settings`, `fluent-module-deploy`, `fluent-workflow-deploy`, `fluent-e2e-test`, `fluent-pre-deploy-check`, `fluent-custom-code`, `fluent-feature-plan`, `fluent-retailer-config`, `fluent-source-onboard`, `fluent-test-data`, `fluent-job-batch`, `fluent-use-case-discover`, `fluent-module-validate`, `fluent-connection-analysis`, `fluent-mystique-builder`, `fluent-mystique-scaffold`, `fluent-mystique-component`
+`fluent-module-scaffold`, `fluent-rule-scaffold`, `fluent-workflow-builder`, `fluent-build`, `fluent-settings`, `fluent-module-deploy`, `fluent-workflow-deploy`, `fluent-e2e-test`, `fluent-pre-deploy-check`, `fluent-custom-code`, `fluent-feature-plan`, `fluent-retailer-config`, `fluent-module-convert`, `fluent-test-data`, `fluent-job-batch`, `fluent-use-case-discover`, `fluent-module-validate`, `fluent-connection-analysis`, `fluent-mystique-builder`, `fluent-mystique-scaffold`, `fluent-mystique-component`
 
 ## Ambiguity Detection
 

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

@@ -1,6 +1,6 @@
 ---
 name: fluent-session
-description: Track session changes and export structured audit trails. Maintains a running change log with text summaries and machine-readable JSON exports for CI/CD pipelines and compliance. Triggers on "session summary", "what did we change", "change summary", "show changes", "export audit", "session audit", "audit trail", "compliance report".
+description: Track session changes and export structured audit trails with text summaries and machine-readable JSON exports for CI/CD and compliance. Use for session summaries, change logs, or audit exports.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Glob, Grep
 argument-hint: [show|reset|export [--format json|jsonl] [--output <path>] [--include-readonly]]

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

@@ -1,6 +1,6 @@
 ---
 name: fluent-settings
-description: Manage Fluent Commerce settings — discover, audit, create, update, and migrate retailer-scoped settings. Cross-reference workflow rules with settings to find gaps. Triggers on "manage settings", "create setting", "audit settings", "settings migration", "missing settings", "webhook settings".
+description: Manage Fluent Commerce retailer-scoped settings with discover, audit, create, update, and migrate operations plus workflow rule cross-referencing. Use for settings management or gap analysis.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [--audit <workflow-file>] [--context RETAILER|ACCOUNT|LOCATION] [--migrate --from <profile> --to <profile>]
@@ -673,7 +673,7 @@ For updates, present a clear diff:
 
 ```
 Setting: fc.webhook.order.created (ID: 365)
-Context: RETAILER:2
+Context: RETAILER, contextId: 2
 Current value: {"url": "https://old-endpoint.com/webhook"}
 New value:     {"url": "https://new-endpoint.com/webhook"}
 Backup: accounts/<PROFILE>/settings/backups/fc.webhook.order.created_2026-02-26_143000.json

package/content/dev/skills/fluent-skill-observability/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-skill-observability
-description: Unified skill system observability — trace execution, analyze routing patterns, and review execution quality. Triggers on "skill trace", "trace skills", "what skills ran", "routing report", "routing analysis", "feedback dashboard", "show feedback", "review feedback", "promote learning", "skill effectiveness", "quality report", "skill quality", "audit skills".
+description: Unified skill system observability for tracing execution, analyzing routing patterns, and reviewing execution quality across all skills. Use for skill trace, routing reports, or quality audits.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: trace [show|analyze|clear|hook-setup] | routing [full|summary|skill <name>|recommendations] | feedback [dashboard|review <skill>|promote <id>|effectiveness [<skill>]|export] | quality [<skill-name>]

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

@@ -1,6 +1,6 @@
 ---
 name: fluent-sourcing
-description: "Comprehensive reference for the Fluent Commerce Responsive Sourcing Framework. Covers sourcing profiles, strategies, conditions, criteria, scoring algorithms, permutation search, settings schema, workflow integration, custom extensions, and operational GraphQL patterns. Triggers on \"sourcing\", \"sourcing profile\", \"sourcing strategy\", \"sourcing condition\", \"sourcing criteria\", \"fulfilment allocation\", \"location scoring\", \"order sourcing\", \"where to fulfil\"."
+description: Comprehensive reference for the Fluent Commerce Responsive Sourcing Framework covering profiles, strategies, conditions, criteria, scoring algorithms, and workflow integration. Use for sourcing configuration or fulfilment allocation questions.
 user-invocable: true
 read-only: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
@@ -35,7 +35,9 @@ This is a **reference skill** — it provides domain knowledge and query pattern
 
 ## Related Knowledge
 
+- `knowledge/platform/domain-model.md` — authoritative entity definitions for InventoryPosition, VirtualPosition, VirtualCatalogue, ControlGroup, Location, Network. **Read this first** for inventory entity relationships and GraphQL edges.
 - `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.
+- `knowledge/platform/reference-module-versions.md` — OOTB inventory rules (CreateInventoryPosition, ApplyThresholdControlsToVirtualPosition, etc.) and sourcing rule versions.
 - `knowledge/platform/financial-fields.md` — use for financial field naming conventions, tax/price/discount patterns on fulfilment and order entities
 
 ## When to Use
@@ -107,18 +109,28 @@ The `SourcingContext` is the runtime data object passed to conditions and criter
 | `order` | Order | The full order entity |
 | `order.totalPrice` | Float | Order total value |
 | `order.attributes[]` | List | Order-level custom attributes |
-| `fulfilmentChoice` | Object | Selected fulfilment option |
+| `fulfilmentChoice` | Object | Selected fulfilment option (created by the order intake mutation) |
 | `fulfilmentChoice.type` | String | e.g., `HD`, `CC`, `SFS` |
 | `fulfilmentChoice.deliveryAddress` | Address | Delivery destination (lat/lng for distance) |
 | `items[]` | List | Order items to source |
 | `items[].productRef` | String | Product reference |
 | `items[].requestedQuantity` | Integer | Quantity needed |
-| `locations[]` | List | Candidate locations from network |
+| `locations[]` | List | Candidate locations from the profile's network |
 | `locations[].ref` | String | Location reference |
 | `locations[].type` | String | e.g., `WAREHOUSE`, `STORE` |
 | `locations[].address` | Address | Location coordinates |
 | `locations[].attributes[]` | List | Location custom attributes |
-| `inventoryPositions[]` | List | Stock data per location per product |
+| `inventoryPositions[]` | List | **InventoryPosition** records — raw on-hand stock per location per product |
+
+> **IMPORTANT — InventoryPosition vs VirtualPosition:** The SourcingContext uses **InventoryPosition** (raw on-hand stock from the InventoryCatalogue), NOT **VirtualPosition** (available-to-sell after ControlGroup buffers/exclusions are applied). This distinction is critical:
+>
+> | Entity | What it holds | Used by sourcing? |
+> |--------|--------------|-------------------|
+> | **InventoryPosition** | Raw on-hand quantity at a location for a product | **Yes** — loaded into SourcingContext |
+> | **VirtualPosition** | ATS quantity after ControlGroup buffers applied | **No** — used by storefront availability, not sourcing |
+> | **ControlGroup / Control** | Buffer/exclusion rules that adjust ATS | **No** — affects VirtualPosition only, not sourcing decisions |
+>
+> When `inventoryAvailabilityExclusion` and `inventoryAvailability` criteria check stock, they check **InventoryPosition.onHand**, not VirtualPosition.quantity. See `knowledge/platform/domain-model.md` for full entity definitions and GraphQL edges.
 
 Conditions use JSON path expressions to navigate this model. For example, `fulfilmentChoice.type` extracts the delivery type, `order.attributes[?(@.name=='priority')].value` extracts a custom attribute.
 
@@ -134,7 +146,7 @@ A Sourcing Profile is configured as a GraphQL entity and loaded at runtime by th
   "status": "ACTIVE",
   "retailerId": 1,
   "catalogueRef": "DEFAULT:1",
-  "virtualCatalogueRef": "FC:DEFAULT:1",
+  "virtualCatalogueRef": "VC_DEFAULT:1",
   "networkRef": "HD_NETWORK",
   "maxSplit": 2,
   "sourcingStrategies": [
@@ -157,8 +169,8 @@ A Sourcing Profile is configured as a GraphQL entity and loaded at runtime by th
 | `ref` | Yes | Unique identifier for the profile |
 | `status` | Yes | `DRAFT`, `ACTIVE`, or `INACTIVE` |
 | `retailerId` | Yes | Owning retailer ID |
-| `catalogueRef` | No | Product catalogue for inventory lookup |
-| `virtualCatalogueRef` | No | Virtual catalogue (overrides catalogueRef) |
+| `catalogueRef` | No | InventoryCatalogue ref for InventoryPosition lookup |
+| `virtualCatalogueRef` | No | VirtualCatalogue ref — **overrides `catalogueRef`** when both are set. Uses ref-based linking (not id-based edges). |
 | `networkRef` | No | Default network for location candidates |
 | `maxSplit` | No | Maximum number of fulfilment locations (default: 1) |
 | `sourcingStrategies` | Yes | Ordered list of strategies |
@@ -405,16 +417,16 @@ Criteria are classified by tag:
 | `fc.sourcing.criterion.locationDistanceExclusion` | Exclusion | Exclude locations beyond a distance threshold | `value` (max distance), `valueUnit` (`KILOMETRES` or `MILES`) |
 | `fc.sourcing.criterion.locationTypeExclusion` | Exclusion | Exclude locations of specified types | `value` (list of type strings, e.g., `["STORE"]`) |
 | `fc.sourcing.criterion.locationNetworkExclusion` | Exclusion | Exclude locations not in the specified network | `value` (network ref string) |
-| `fc.sourcing.criterion.inventoryAvailabilityExclusion` | Exclusion | Exclude locations with insufficient stock for all order items | *(none)* |
+| `fc.sourcing.criterion.inventoryAvailabilityExclusion` | Exclusion | Exclude locations with insufficient on-hand stock (InventoryPosition) for all order items | *(none)* |
 | `fc.sourcing.criterion.locationDistance` | Sorter | Score by distance from delivery address (closest = highest score) | *(none)* |
 | `fc.sourcing.criterion.locationDistanceBanded` | Sorter | Score by distance using configurable bands | `bands` (list of `{from, to, score}`) |
 | `fc.sourcing.criterion.locationDailyCapacity` | Sorter | Score by remaining daily fulfilment capacity | *(none)* |
 | `fc.sourcing.criterion.networkPriority` | Sorter | Score by the location's network priority field | *(none)* |
-| `fc.sourcing.criterion.inventoryAvailability` | Sorter | Score by stock quantity (more stock = higher score) | *(none)* |
+| `fc.sourcing.criterion.inventoryAvailability` | Sorter | Score by on-hand stock quantity from InventoryPosition (more stock = higher score) | *(none)* |
 | `fc.sourcing.criterion.inventoryAvailabilityBanded` | Sorter | Score by stock quantity using configurable bands | `bands` (list of `{from, to, score}`) |
 | `fc.sourcing.criterion.orderValue` | Sorter | Score by order value handling capability | *(none)* |
 
-> **Note on Parameter Names:** In `util-sourcing-2.1.0`, the JSON parsing logic uses generic keys like `"value"` and `"valueUnit"` (via `params.get("value")`). Newer versions may use descriptive names like `maxDistance`, `distanceUnit`, `excludedTypes`. Always check your specific version.
+> **Note on Parameter Names:** In `util-sourcing-2.1.0`, the JSON parsing logic uses generic keys like `"value"` and `"valueUnit"` (via `params.get("value")`). Newer versions may use descriptive names like `maxDistance`, `distanceUnit`, `excludedTypes`. To discover parameter names for your version, use `/fluent-trace` to inspect a sourcing event's rule execution, or decompile the util-sourcing JAR deployed in your environment.
 
 ### Scoring and Normalization
 
@@ -907,7 +919,10 @@ compact: false
 
 Review the flow inspection output for condition evaluation results.
 
-**3. Verify inventory data exists for candidate locations:**
+**3. Verify InventoryPosition data exists for candidate locations:**
+
+Sourcing reads **InventoryPosition** (raw on-hand), not VirtualPosition (ATS). If locations are excluded for insufficient stock, verify InventoryPosition records exist:
+
 ```
 Tool: graphql_query
 Query: {
@@ -915,12 +930,22 @@ Query: {
     catalogue: { ref: "DEFAULT:1" }
     productRef: "<PRODUCT_REF>"
   ) {
-    edges { node { locationRef quantity status } }
+    edges { node { ref locationRef onHand quantity status } }
   }
 }
 ```
 
-**4. Check settings for custom type registration:**
+If InventoryPosition exists but sourcing still excludes the location, the `onHand` value may be below the requested quantity. Do NOT check VirtualPosition for sourcing issues — VirtualPosition reflects ATS after ControlGroup buffers, which sourcing does not use.
+
+**4. Verify catalogueRef vs virtualCatalogueRef precedence:**
+
+If both are set on the profile, `virtualCatalogueRef` overrides `catalogueRef`. Verify which is active:
+```
+Tool: graphql_query
+Query: { sourcingProfile(ref: "<PROFILE_REF>") { catalogueRef virtualCatalogueRef } }
+```
+
+**5. Check settings for custom type registration:**
 ```
 Tool: graphql_query
 Query: {

package/content/dev/skills/fluent-system-monitoring/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-system-monitoring
-description: Monitor Fluent Commerce event processing health using Prometheus queries and aggregated analytics. Detect failure rate anomalies, triage alert patterns, interpret event volume trends, and identify workflow gaps through deep metric analysis. Specialized in **anomaly detection and alert triage** — NOT for infrastructure monitoring or generic metrics queries. Triggers on "system monitoring", "event analytics", "failure rate anomaly", "event volume trend", "top failing events", "alert triage", "prometheus queries", "latency analysis", "throughput spike", "no-match rate".
+description: Monitor Fluent Commerce event processing health using Prometheus queries and aggregated analytics for anomaly detection and alert triage. Use for failure rate analysis, event volume trends, or workflow gap identification.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [--from <ISO-datetime>] [--entity-type ORDER|FULFILMENT] [--top-n 20]

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

@@ -1,6 +1,6 @@
 ---
 name: fluent-test-data
-description: Discover retailer configuration and generate valid test entity PAYLOADS dynamically via GraphQL. No hardcoded refs — everything is queried from the live environment. Does NOT own event sending — for sending events use /fluent-mcp-tools (event_build + event_send). This skill generates payloads; MCP tools dispatch them. Triggers on "create test order", "test data", "create test entity", "discover products", "discover locations".
+description: Discover retailer configuration and generate valid test entity payloads dynamically via GraphQL with no hardcoded refs. Use for creating test data, discovering products or locations, or generating test entity payloads.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [entity-type] [--type HD|CC|SFS] [--count N]

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

@@ -1,11 +1,12 @@
 ---
 name: fluent-trace
-description: "FIRST-RESPONDER debugging skill — if ANY entity is stuck, broken, or not progressing, route HERE first. Traces and debugs Fluent Commerce event processing. Analyzes failed events, correlates them with workflows and rules, and identifies runtime root causes. ROUTING PRIORITY — this skill MUST win over fluent-entity-flow-diagnose when the prompt says \"stuck\", \"trace why\", \"root cause\", \"not progressing\", \"debug\", \"correlate events with rules\", \"identify root cause\", \"show live state\" WITHOUT comparison language like \"expected vs observed\" or \"compare runtime\". YIELD-BACK — if the prompt ALSO contains \"compare runtime vs expected\", \"compare runtime vs workflow\", \"expected vs observed\", or \"what should have happened\", route to fluent-entity-flow-diagnose instead, even if it also says \"stuck\" or \"diagnose\". Those comparison prompts need full lifecycle reconstruction, not just first-responder debugging. HARD NEGATIVE — do NOT route here for conceptual Event API reference questions like event categories, event statuses, how events are routed to rulesets, run-once behavior, or log action vs audit action when there is no specific entity, failure, or debugging context; those belong to fluent-event-api. Key knowledge — domain-model.md (entity relationships and event flows), sync-vs-async-patterns.md (execution flow), workflow-json-structure.md (status transitions). ROUTING PRIORITY — This skill MUST win over fluent-entity-flow-diagnose when the prompt says \"trace why X is stuck\", \"correlate events with rules\", \"identify root cause\", \"show live state\" WITHOUT comparison language like \"expected vs observed\" or \"compare runtime\". Triggers on \"trace event\", \"event trace\", \"trace why\", \"why did event fail\", \"failed orchestration\", \"debug fulfilment\", \"stuck at [status]\", \"not progressing\", \"not moving\", \"event didn't fire\", \"why is this order stuck\", \"why is this fulfilment stuck\", \"why is this consignment stuck\", \"what happened to order\", \"what happened to fulfilment\", \"order not advancing\", \"entity not changing state\", \"root cause\", \"likely root cause\", \"live state\", \"correlate events with rules\".
+description: First-responder debugging skill that traces and debugs Fluent Commerce event processing by analyzing failed events, correlating with workflows/rules, and identifying root causes. Use when any entity is stuck, broken, or not progressing.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <entity-ref> [--entity-type ORDER|FULFILMENT] [--status FAILED]
 cursor-tier: manual
 ---
+<!-- routing-notes: ROUTING PRIORITY — this skill MUST win over fluent-entity-flow-diagnose when the prompt says "stuck", "trace why", "root cause", "not progressing", "debug" WITHOUT comparison language like "expected vs observed" or "compare runtime". YIELD-BACK — if the prompt ALSO contains "compare runtime vs expected", "expected vs observed", or "what should have happened", route to fluent-entity-flow-diagnose instead. HARD NEGATIVE — do NOT route here for conceptual Event API reference questions (event categories, statuses, run-once, log action vs audit action without a specific entity) — those belong to fluent-event-api. -->
 
 # Event Trace & Debug
 
@@ -448,7 +449,7 @@ When the user asks questions like:
 Use the bundled local analyzer after raw capture:
 
 ```text
-node scripts/analyze-event-capture.mjs \
+node fluent-ai-skills/tools/event-capture-analyzer.mjs \
   accounts/<PROFILE>/analysis/event-captures/<EVENT_ID>.event.json \
   accounts/<PROFILE>/analysis/event-captures/<EVENT_ID>.window.json \
   --root-ref <ORDER_REF> \

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

@@ -1,11 +1,12 @@
 ---
 name: fluent-transition-api
-description: Query the Fluent Commerce Transition API to discover available user actions for entities at any workflow status. This is read-only action discovery ONLY — it does NOT send events. YIELD-BACK — if the prompt says "send" + event name (e.g., "send a ConfirmShipment event"), "dispatch event", "verify it landed", or "send and verify", route to fluent-mcp-tools instead. This skill discovers what actions EXIST; fluent-mcp-tools SENDS the events. ROUTING PRIORITY for prompts like "what user actions are available at BOOKED?", "which actions/buttons should appear for ORDER::HD?", or "what attributes does each action need?" — those belong here, not in fluent-workflow-analyzer. Key knowledge — user-action-contract.md (workflow user action shape), workflow-design.md (status and action placement), permissions-and-contexts.md (module and visibility context). Enables dynamic test sequences and UI action validation. Triggers on "transition api", "user actions", "available actions", "workflow transitions", "what actions", "what attributes each action needs".
+description: Query the Fluent Commerce Transition API to discover available user actions for entities at any workflow status. Read-only action discovery. Use for listing available actions, mapping required attributes, or UI action validation.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <entity-type> <subtype> <status> [--retailer-id <id>]
 cursor-tier: auto
 ---
+<!-- routing-notes: YIELD-BACK — if the prompt says "send" + event name, "dispatch event", "verify it landed", or "send and verify", route to fluent-mcp-tools instead. This skill discovers what actions EXIST; fluent-mcp-tools SENDS the events. ROUTING PRIORITY for prompts like "what user actions are available at BOOKED?" or "what attributes does each action need?" — those belong here, not in fluent-workflow-analyzer. -->
 
 # Transition API — User Action Discovery
 
@@ -397,7 +398,7 @@ event_send({
   "retailerId": "2",
   "attributes": {
     "trackingNumber": "TRACK-001",
-    "carrierRef": "DHL"
+    "carrierRef": "CARRIER_FAST"
   }
 })
 ```

package/content/dev/skills/fluent-ui-record/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-ui-record
-description: "Record annotated UI walkthroughs of Fluent Commerce apps. Captures before/after screenshots with DOM annotations, Chrome DevTools screencast recording, manifest diffs, and generates self-contained HTML evidence reports. Triggers on \"record UI\", \"record walkthrough\", \"capture UI changes\", \"document UI\", \"UI recording\", \"before after\", \"evidence report\", \"annotated recording\"."
+description: Record annotated UI walkthroughs of Fluent Commerce apps with before/after screenshots, DOM annotations, screencast recording, and HTML evidence reports. Use for capturing UI changes or documenting walkthroughs.
 user-invocable: true
 read-only: false
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep

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

@@ -1,6 +1,6 @@
 ---
 name: fluent-ui-test
-description: Browser-based UI testing for Fluent Commerce OMS App and Store App using Chrome DevTools MCP. Verifies manifest deployments render correctly, pages load, components display data, and user actions are functional. Triggers on "test UI", "verify manifest in browser", "browser test", "OMS test", "devtools test", "does the page work", "check OMS", "verify page renders".
+description: Browser-based UI testing for Fluent Commerce OMS and Store apps using Chrome DevTools MCP to verify page rendering, component display, and user action functionality. Use for UI testing or manifest deployment verification.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [--app oms|store|servicepoint] [--route /orders] [--entity-id <id>] [--screenshot] [--login]
@@ -300,17 +300,18 @@ Where:
 - `<env>` — `test`, `sandbox`, `staging`, or `prod` (omitted for prod)
 - `<app>` — `oms`, `store`, or `servicepoint`
 
-### Store App — Location Pre-Selection
+### Context Pre-Selection (Store + OMS)
 
-The Store app operates at `context.level: "location"`. To test a specific store location, append `?user.location.ref=<LOCATION_REF>` **after the hash path**:
+Both apps support pre-selecting a context via URL parameter **appended after the hash path**:
 
-```
-https://<account>.<env>.apps.fluentcommerce.com/store/#/waves?user.location.ref=LOC_SYD_001
-```
+| App | Context Level | URL Parameter | Example |
+|---|---|---|---|
+| **Store** | `location` | `user.location.ref` | `store/#/waves?user.location.ref=LOC_SYD_001` |
+| **OMS** | `retailer` | `user.retailer.ref` | `oms/#/orders?user.retailer.ref=RETAILER_AU` |
 
-Location context resolution order: (1) `user.location.ref` URL param, (2) `localStorage["mystique.auth.context.location"]` (persisted ID from previous selection), (3) first accessible location. The URL param is consumed on load and stripped — localStorage persists across sessions.
+Context resolution order: (1) URL param (consumed on load, then stripped), (2) `localStorage["mystique.auth.context.<type>"]` (persisted ID from previous selection), (3) first accessible context. localStorage persists across sessions.
 
-If the test user lacks AGENT-context permission for that location, the system falls back to the next priority. See `knowledge/platform/mystique-routing.md` §"Store App — Default Location via URL Parameter" for full details.
+If the test user lacks the required role context (AGENT for locations, RETAILER for retailers), the system falls back to the next priority. See `knowledge/platform/mystique-routing.md` §"Context Switching" for full details.
 
 ## Protocol Phases
 

package/content/dev/skills/fluent-use-case-discover/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-use-case-discover
-description: Interactive requirements gathering wizard that produces a structured Business Specification. Walks through use cases, actors, business rules, integrations, and acceptance criteria. Supports interactive mode, document analysis mode, and structured PRD template intake. Triggers on "discover use case", "gather requirements", "business spec", "use case discovery", "what are we building", "requirements gathering", "spec wizard", "analyze requirements", "prd intake", "fill prd".
+description: Interactive requirements gathering wizard that produces a structured Business Specification covering use cases, actors, business rules, integrations, and acceptance criteria. Use for requirements gathering, use case discovery, or PRD intake.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [--analyze <path-or-paste>] [--prd <path>] [--profile PROFILE] [--retailer RETAILER_REF]
@@ -322,7 +322,7 @@ UC-04: [Edge Case] <title> — <one-line summary>
 
 **Rules:**
 - One diagram per primary use case (UC-01) at minimum. Add diagrams for alternative/exception paths only if the flow is materially different (not just a different error message).
-- Keep diagrams HIGH-LEVEL — 5-10 interactions max. Implementation detail (GraphQL fields, attribute names, CSS) belongs in the plan, not the spec.
+- Keep diagrams HIGH-LEVEL — 5-10 interactions max. Prefer business language (e.g., "Trigger StartPick event") over API detail (e.g., `POST /event/sync`). Detailed GraphQL fields, attribute names, and CSS belong in the plan, not the spec.
 - Use Mermaid syntax — validated by `knowledge/mermaid-syntax-rules.md`.
 - Diagrams go in spec §5a (after use cases, before entity model).
 

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

@@ -1,11 +1,12 @@
 ---
 name: fluent-workflow-analyzer
-description: Validate and analyze Fluent Commerce workflow JSON definitions. Structural validation (schema, status graph, triggers, rules, user actions, cross-entity checks), status graph mapping, event chain tracing, orphan detection, dependency reports, and Mermaid diagrams. ROUTING PRIORITY — if the user wants to validate, check, review, lint, or sanity-check a workflow before editing or deployment, route HERE even when the prompt also says "download workflow" or "download it first". Download-plus-validate requests are still validation-led, so prefer this skill over fluent-workflow. Triggers on "analyze workflow", "validate workflow", "check workflow", "lint workflow", "workflow analysis", "workflow graph", "workflow dependencies", "workflow review", "workflow issues", "workflow health", "download and validate workflow", "download workflow and check it".
+description: Validate and analyze Fluent Commerce workflow JSON definitions with structural checks, status graph mapping, event chain tracing, and orphan detection. Use for workflow validation, review, lint, or dependency analysis.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <workflow-file-or-name> [--validate-only] [--strict] [--fix-suggestions] [--deep] [--mermaid] [--explain-rules] [--profile <name>] [--output <path>]
 cursor-tier: manual
 ---
+<!-- routing-notes: ROUTING PRIORITY — if the user wants to validate, check, review, lint, or sanity-check a workflow, route HERE even when the prompt also says "download workflow". Download-plus-validate requests are validation-led, so prefer this skill over fluent-workflow. -->
 
 # Workflow Analyzer
 
@@ -153,7 +154,7 @@ WorkflowDefinition
 |----|-------|----------|--------|
 | G01 | All statuses have `name` | CRITICAL | Every entry in `statuses[]` must have a non-empty `name` string. |
 | G02 | All statuses have `category` | HIGH | Every status should have a `category` from the standard set. Missing category = wrong UI badge rendering. |
-| G03 | Category values are valid | MEDIUM | Category must be one of: `BOOKING`, `FULFILMENT`, `DELIVERY`, `DONE`, `EXCEPTION`. |
+| G03 | Category values are valid | MEDIUM | Category must be one of: `BOOKING`, `FULFILMENT`, `DELIVERY`, `DONE`, `EXCEPTION`, `GENERATION` (FO/FP workflows only). |
 | G04 | No duplicate status names | HIGH | Two statuses with the same `name` (within the same entity type) cause undefined behavior. |
 | G05 | Orphaned statuses | HIGH | A status defined in `statuses[]` but never referenced in any ruleset trigger or as a SetState destination is unreachable dead config. |
 | G06 | Unreachable statuses | HIGH | If a status cannot be reached from the initial status (CREATED or first defined), it is unreachable. |