@fluentcommerce/ai-skills 0.14.0 → 0.15.0

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
 

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]

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. |

package/content/dev/skills/fluent-workspace-tree/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: fluent-workspace-tree
-description: Read-only directory tree visualization of the workspace file system — renders an annotated tree showing folders, files, artifact counts per directory, and optional status overlays. This is a filesystem structure view (like the Unix `tree` command), not a live account inventory. ROUTING PRIORITY — if the prompt says "directory tree", "workspace tree", "folder layout", "artifact counts per folder", "show directory structure", "show me the tree", or "workspace layout", route HERE — do NOT route to fluent-feature-status. fluent-feature-status scans status.json files and produces a feature lifecycle table; this skill renders the filesystem tree like Unix `tree`. It does NOT handle feature lifecycle status tables (use fluent-feature-status), HTML dashboards (use fluent-feature-status), or account environment snapshots (use fluent-account-snapshot).
+description: Read-only directory tree visualization of the workspace file system with annotated folders, artifact counts, and optional status overlays. Renders a filesystem structure view like the Unix tree command.
 user-invocable: true
 allowed-tools: Bash, Read, Glob, Grep
 argument-hint: [--profile PROFILE] [--section source|workflows|features|reports|analysis|tasks|sessions] [--depth N]
 cursor-tier: auto
 ---
+<!-- routing-notes: ROUTING PRIORITY — if the prompt says "directory tree", "workspace tree", "folder layout", or "workspace layout", route HERE — do NOT route to fluent-feature-status. fluent-feature-status scans status.json files; this skill renders the filesystem tree. Does NOT handle feature lifecycle tables (→ fluent-feature-status) or account snapshots (→ fluent-account-snapshot). -->
 
 # Workspace Tree Visualization
 

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

@@ -555,6 +555,7 @@ event into the workflow engine — enabling automatic rule execution on entity c
 | **Virtual Catalogue** | Virtual Position | `VIRTUAL_CATALOGUE`, `VIRTUAL_POSITION` | Both: No |
 | **Control Group** | Control | `CONTROL_GROUP`, `CONTROL` | Both: No |
 | **Return Order** | Return Fulfilment | `RETURN_ORDER`, `RETURN_FULFILMENT` | Both: Yes |
+| **Job** `[SCHEMA]` | Batch | `JOB`, `BATCH` | JOB: Yes, BATCH: Yes `[SCHEMA: observed in API, not in official docs]` |
 | **Billing Account** | Credit Memo, Invoice, Payment, Payment Transaction | `BILLING_ACCOUNT`, `CREDIT_MEMO`, `INVOICE`, `PAYMENT`, `PAYMENT_TRANSACTION` | All: Yes |
 
 **Key implications:**

package/content/knowledge/platform/workflow-json-structure.md

@@ -107,7 +107,7 @@ Field order inside each ruleset:
 **Key rules:**
 - `rules[]` comes BEFORE `triggers[]`
 - `userActions: []` ALWAYS present (even if empty)
-- NO `subtype` field on rulesets — entity-level `entitySubtype` handles routing
+- NO `subtype` field on event-triggered rulesets — entity-level `entitySubtype` handles routing. Exception: rulesets with `userActions[]` MUST have `subtype` matching `entitySubtype` for UI button visibility (see `user-action-contract.md`).
 - `eventType` is typically `"NORMAL"`
 
 ## Ruleset Matching (4 criteria)

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

@@ -1,11 +1,12 @@
 ---
 name: fluent-mcp-core
-description: Official Fluent Commerce CLI MCP server setup and operations. Configure the built-in MCP server, run health checks, validate GraphQL connectivity, build/validate queries, and manage workflow list/download operations. ROUTING PRIORITY over fluent-bootstrap and fluent-connect when the prompt explicitly mentions "built-in MCP server", "official MCP server", "GraphQL connectivity", "set up the built-in MCP", or "set up the MCP server and test". If the user says "set up" combined with "MCP server" or "GraphQL connectivity", route HERE only when official-server setup/testing is the primary task, not when MCP wiring is just one step inside existing-account onboarding. Do not route send-event, verify-it-landed, Transition API discovery, extension-only GraphQL (`graphql_planOperation`, `graphql_query`, `graphql_queryAll`), runtime connection switching, or extension workflow-get prompts here — those belong to fluent-mcp-tools. Do not prefer this skill when the prompt is about CI/CD, automation pipelines, or non-interactive `fluent mcp server --stdio` rollout patterns — route those to fluent-cli-mcp-cicd instead. HARD NEGATIVE — Do NOT route here for: existing-account connection/onboarding prompts that also ask to discover CLI profiles, choose retailer context, or get the workspace ready to work (→ fluent-connect), 'connection_list' / 'connection_switch' / 'connection management' / 'workflow_get' / 'workflow_transitions' / 'event_send' / 'graphql_query' (→ fluent-mcp-tools for MCP extension server tools). Triggers on "mcp core setup", "built-in mcp server", "official mcp server", "graphql connectivity", "graphql validate", "workflow download", "set up the built-in MCP", "set up mcp server", "test graphql connectivity".
+description: Official Fluent Commerce CLI MCP server setup and operations. Configure the built-in MCP server, run health checks, validate GraphQL connectivity, and manage workflow downloads. Use for built-in MCP server setup or GraphQL connectivity testing.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <operation> [--profile name] [--retailer ref]
 cursor-tier: auto
 ---
+<!-- routing-notes: ROUTING PRIORITY over fluent-bootstrap and fluent-connect when prompt explicitly mentions "built-in MCP server", "official MCP server", "GraphQL connectivity". Route HERE only when official-server setup/testing is the primary task. Do not route send-event, Transition API, extension-only GraphQL, runtime connection switching, or extension workflow-get here (→ fluent-mcp-tools). Do not route CI/CD pipelines or non-interactive stdio setup here (→ fluent-cli-mcp-cicd). HARD NEGATIVE — Do NOT route for existing-account onboarding (→ fluent-connect) or MCP extension tools like connection_list, event_send, graphql_query (→ fluent-mcp-tools). -->
 
 # Fluent MCP Core
 

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

@@ -1,11 +1,12 @@
 ---
 name: fluent-mcp-tools
-description: Fluent Commerce MCP extension server tools reference. Canonical owner of event sending (event_build + event_send), event verification, extension-first GraphQL execution, runtime connection management, extension workflow operations, and all 59 MCP extension tools. Use for "send event", "dispatch event", "verify it landed", event flow forensics, GraphQL operations, batch ingestion, connection switching, or webhook validation. ROUTING PRIORITY over fluent-transition-api for ANY prompt that says "send" + event name (e.g., "send a ConfirmShipment event"), "dispatch event", "verify it landed", or "send and verify". Transition API is read-only action discovery — if the user wants the event SENT or VERIFIED, route HERE. ROUTING PRIORITY over fluent-bootstrap for event/MCP operations. ROUTING PRIORITY for MCP extension server tools — route here instead of fluent-mcp-core or fluent-workflow when prompt mentions MCP extension tools like workflow_get, workflow_transitions, connection_list, event_send, graphql_query, batch_send. HARD NEGATIVE — Do NOT route here for: "which CLI command family" / "mixed CLI question" / "CLI overview" / "work across profiles, retailers, workflows, settings" (→ fluent-cli-reference handles broad CLI triage questions). HARD NEGATIVE — do NOT route conceptual Event API questions here: if the user is asking what event statuses, categories, `sourceEvents`, orchestration routing, run-once semantics, or audit-vs-log actions mean, route to fluent-event-api even if the prompt mentions `event_list` or other MCP tool names. Do not route Prometheus monitoring (use fluent-system-monitoring), pure built-in server setup, official GraphQL connectivity-only, or `workflow_download` prompts (those belong to fluent-mcp-core). Key knowledge — graphql-preflight.md, graphql-query-complexity.md, sync-vs-async-patterns.md. Triggers on "mcp tools", "send fluent event", "send event", "send a ConfirmShipment", "send a", "dispatch event", "verify it landed", "send and verify", "event flow inspect", "trace event payloads", "fluent graphql", "graphql query", "batch ingestion".
+description: Fluent Commerce MCP extension server tools reference covering all 59 tools including event sending, GraphQL execution, batch ingestion, and connection management. Use for sending events, dispatching, or verifying MCP operations.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <operation> [entity-type] [entity-ref]
 cursor-tier: manual
 ---
+<!-- routing-notes: ROUTING PRIORITY over fluent-transition-api for ANY prompt that says "send" + event name, "dispatch event", "verify it landed", or "send and verify". ROUTING PRIORITY over fluent-bootstrap for event/MCP operations. ROUTING PRIORITY for MCP extension server tools — route here instead of fluent-mcp-core or fluent-workflow when prompt mentions extension tools like workflow_get, connection_list, event_send, graphql_query, batch_send. HARD NEGATIVE — Do NOT route here for broad CLI triage questions (→ fluent-cli-reference) or conceptual Event API questions about event statuses, categories, sourceEvents, orchestration routing, run-once semantics (→ fluent-event-api). Do not route Prometheus monitoring (→ fluent-system-monitoring), built-in server setup, or workflow_download (→ fluent-mcp-core). -->
 
 # Fluent MCP Tools
 
@@ -579,7 +580,7 @@ To discover which attributes an entity supports and how they appear in mutations
 
 ### Schema Tool Annotations
 
-All 57 MCP extension tools now advertise MCP `ToolAnnotations` (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`). MCP clients that respect annotations can automatically distinguish read-only operations (queries, introspection, cache status) from write operations (event_send, entity_create, workflow_upload).
+All 59 MCP extension tools now advertise MCP `ToolAnnotations` (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`). MCP clients that respect annotations can automatically distinguish read-only operations (queries, introspection, cache status) from write operations (event_send, entity_create, workflow_upload).
 
 ## Batch Ingestion
 

package/content/rfl/skills/fluent-rfl-assess/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-rfl-assess
-description: Run a Ready For Launch (RFL) assessment on a Fluent Commerce implementation. Analyzes workflows, rules, settings, and integrations for production readiness. Triggers on "rfl assessment", "ready for launch check", "go-live readiness", "production audit".
+description: Run a Ready For Launch (RFL) assessment on a Fluent Commerce implementation analyzing workflows, rules, settings, and integrations. Trigger on go-live readiness or production audit needs.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [--profile name] [--retailer ref]

package/docs/02-prompt-guide.md

@@ -78,7 +78,7 @@ These create or change things — the AI presents a plan and waits for your appr
 
 | Skill | What it does | Try this |
 |-------|-------------|----------|
-| `fluent-pre-deploy-check` | Runs 35+ quality gates across 9 phases — produces GO/NO-GO report | `"Run pre-deploy checks"` |
+| `fluent-pre-deploy-check` | Runs 37 quality gates across 9 phases — produces GO/NO-GO report | `"Run pre-deploy checks"` |
 | `fluent-workflow-deploy` | Uploads workflow JSON to target environment | `"Deploy ORDER::RETURN to staging"` |
 | `fluent-module-deploy` | Deploys compiled module to target environment | `"Deploy the returns module to staging"` |
 | `fluent-e2e-test` | Runs end-to-end test with event firing and assertions | `"Run E2E test of the return flow"` |

package/docs/03-use-cases.md

@@ -132,7 +132,7 @@ This is the flagship use case. The AI follows the mandatory chain: **requirement
 ```
 Help me define the use cases for a Return Order feature
 ```
-The `/fluent-use-case-discover` wizard runs through 10 phases:
+The `/fluent-use-case-discover` wizard runs through 12 phases:
 - Entity types involved (ORDER, RETURN_ORDER, FULFILMENT)
 - Business rules (return window, item eligibility, refund policies)
 - Status lifecycles per entity
@@ -558,20 +558,22 @@ After approval:
 Help me define the use cases for curbside pickup
 ```
 
-`/fluent-use-case-discover` runs an interactive wizard through 10 phases:
+`/fluent-use-case-discover` runs an interactive wizard through 12 phases:
 
 | Phase | What happens | Output |
 |---|---|---|
-| 1. Scope | Define the feature boundary — what's in, what's out | Scope statement |
-| 2. Actors | Identify who interacts (customer, store staff, OMS, WMS) | Actor registry |
-| 3. Use cases | Walk through each user journey step by step | Structured use case list |
-| 4. Environment discovery | Query live environment for existing workflows, rules, entity types (requires connected profile) | Available infrastructure |
-| 5. Entity model | Define entities, subtypes, and relationships | Entity relationship diagram |
-| 6. Status lifecycles | Map statuses per entity with allowed transitions | State machine diagrams |
-| 7. Business rules | Capture validation rules, constraints, edge cases | Rules inventory |
-| 8. Integration points | Webhooks, external systems, scheduled jobs | Integration map |
-| 9. Settings | Required configuration keys and values | Settings inventory |
-| 10. Gap analysis | Compare requirements against existing environment | Completeness score |
+| 0. Mode detection | Detect input mode — vague idea vs structured requirements | Mode selection |
+| 1. Feature identity | Define the feature boundary — what's in, what's out | Scope statement |
+| 2. Actors & triggers | Identify who interacts (customer, store staff, OMS, WMS) | Actor registry |
+| 3. User journeys | Walk through each user journey step by step | Structured use case list |
+| 4. Entities & data | Define entities, subtypes, and relationships | Entity relationship diagram |
+| 5. Business rules | Capture validation rules, constraints, edge cases | Rules inventory |
+| 6. Integrations | Webhooks, external systems, scheduled jobs | Integration map |
+| 7. UI & actions | User interface requirements and user actions | UI requirements |
+| 8. Constraints & risks | Non-functional requirements, risks, edge cases | Risk register |
+| 9. Acceptance criteria | Testable acceptance criteria per use case | Criteria list |
+| 10. Review & gap analysis | Compare requirements against existing environment | Completeness score |
+| 10b. Self-critique | Automated critique loop for spec quality | Refined spec |
 
 **Output:** A Business Spec saved to `accounts/<PROFILE>/features/curbside-pickup/spec.md` with a completeness score (0-100%). Specs scoring >= 75% can proceed directly to `/fluent-feature-plan`.
 
@@ -640,7 +642,7 @@ Build it
 ```
 Run pre-deploy checks
 ```
-35+ quality gates across 9 phases. If all pass → READY. If any critical gate fails → BLOCKED with specific fix instructions.
+37 quality gates across 9 phases. If all pass → READY. If any critical gate fails → BLOCKED with specific fix instructions.
 
 **Step 5: Deploy**
 ```

package/docs/04-onboarding-plan.md

@@ -192,7 +192,7 @@ Now you build the feature planned in Week 1. The AI does the heavy lifting — y
    ```
    Run pre-deploy checks for [module name]
    ```
-   35+ quality gates across 9 phases. Review the GO/NO-GO report. Fix any blocking issues before continuing.
+   37 quality gates across 9 phases. Review the GO/NO-GO report. Fix any blocking issues before continuing.
 
    Then:
    ```

package/docs/chrome-devtools-mcp-reference.md

@@ -82,16 +82,16 @@ Adds `chrome-manual` server. Requires Chrome extension from https://github.com/h
 
 ```typescript
 navigate_page({ url: "https://<account>.test.apps.engineering.fluentcommerce.com/oms" })
-take_snapshot()  // Find login form refs
+take_snapshot()  // Find login form uids
 
 fill_form({
-  fields: [
-    { ref: "username-input-ref", value: process.env.FLUENT_USERNAME },
-    { ref: "password-input-ref", value: process.env.FLUENT_PASSWORD }
+  elements: [
+    { uid: "username-input-uid", value: "YOUR_USERNAME" },
+    { uid: "password-input-uid", value: "YOUR_PASSWORD" }
   ]
 })
-click({ ref: "login-button-ref" })
-wait_for({ condition: "navigation complete" })
+click({ uid: "login-button-uid" })
+wait_for({ text: ["Dashboard", "Orders"] })
 take_snapshot()  // Verify dashboard loaded
 ```
 
@@ -102,7 +102,7 @@ take_snapshot()  // Verify dashboard loaded
 navigate_page({ url: "https://<account>.test.apps.engineering.fluentcommerce.com/oms#/orders" })
 
 // OR click navigation menu
-click({ ref: "orders-menu-item-ref" })
+click({ uid: "orders-menu-item-uid" })
 take_snapshot()  // Verify orders list
 ```
 
@@ -110,9 +110,9 @@ take_snapshot()  // Verify orders list
 
 ```typescript
 take_snapshot()
-type_text({ ref: "search-input-ref", text: "TEST-ORDER-001" })
-press_key({ ref: "search-input-ref", key: "Enter" })
-wait_for({ timeout: 5000 })
+click({ uid: "search-input-uid" })  // Focus the input first
+type_text({ text: "TEST-ORDER-001", submitKey: "Enter" })
+wait_for({ text: ["TEST-ORDER-001"], timeout: 5000 })
 list_network_requests()  // Verify GraphQL query fired
 ```
 
@@ -120,20 +120,22 @@ list_network_requests()  // Verify GraphQL query fired
 
 ```typescript
 fill_form({
-  fields: [
-    { ref: "customer-autocomplete-ref", value: "John Doe" },
-    { ref: "order-type-select-ref", value: "HD" },
-    { ref: "order-ref-input-ref", value: "TEST-ORDER-123" }
+  elements: [
+    { uid: "customer-autocomplete-uid", value: "John Doe" },
+    { uid: "order-type-select-uid", value: "HD" },
+    { uid: "order-ref-input-uid", value: "TEST-ORDER-123" }
   ]
 })
-select_option({ ref: "retailer-select-ref", value: "YOUR_RETAILER" })
-click({ ref: "submit-button-ref" })
+// For dropdowns, use fill_form or click to open then click the option
+click({ uid: "retailer-select-uid" })
+click({ uid: "retailer-option-uid" })
+click({ uid: "submit-button-uid" })
 ```
 
 ### 5. Verify GraphQL API Calls
 
 ```typescript
-click({ ref: "refresh-button-ref" })
+click({ uid: "refresh-button-uid" })
 list_network_requests()
 // Look for: url containing "graphql", method "POST", status 200
 ```
@@ -161,21 +163,21 @@ evaluate_script({
 
 ```typescript
 list_console_messages()
-click({ ref: "problematic-button-ref" })
+click({ uid: "problematic-button-uid" })
 list_console_messages()  // Returns array of { level: "error", text: "..." }
 ```
 
 ### 7. Screenshots for Visual Regression
 
 ```typescript
-take_screenshot({ fullPage: true })          // Full page
-take_screenshot({ ref: "order-card-ref" })   // Element-specific
+take_screenshot({ fullPage: true })           // Full page
+take_screenshot({ uid: "order-card-uid" })   // Element-specific
 ```
 
 ### 8. Mobile Responsive Testing
 
 ```typescript
-browser_resize({ width: 390, height: 844 })
+resize_page({ width: 390, height: 844 })
 take_snapshot()  // Verify mobile layout
 ```
 
@@ -296,7 +298,7 @@ window.__fcTimeline = {
 
 | Symptom | Cause | Fix |
 |---------|-------|-----|
-| "Element not found" | Element not in DOM yet (still loading) | `wait_for({ timeout: 5000 })` then `take_snapshot()` |
+| "Element not found" | Element not in DOM yet (still loading) | `wait_for({ text: ["expected text"], timeout: 5000 })` then `take_snapshot()` |
 | Hash routing not working | Browser treated `#` as fragment | Use full URL: `https://...com/oms#/orders` (not just `#/orders`) |
 | GraphQL mutation payload missing | POST bodies not always captured | Use `evaluate_script` with fetch interceptor (see above) |
 | Flaky tests after navigation | No auto-wait after navigation | Always add `wait_for` after `navigate_page` |
@@ -373,23 +375,22 @@ jobs:
 | Tool | Purpose | Key Parameters |
 |------|---------|----------------|
 | `navigate_page` | Go to URL | `url` |
-| `click` | Click element | `ref`, `button`, `modifiers` |
-| `type_text` | Type text | `ref`, `text` |
-| `press_key` | Press keyboard key | `ref`, `key` |
-| `fill_form` | Fill multiple fields | `fields: [{ref, value}]` |
-| `drag` | Drag and drop | `ref`, `targetRef` |
-| `hover` | Hover over element | `ref` |
-| `select_option` | Select dropdown value | `ref`, `value` |
-| `file_upload` | Upload file | `ref`, `filePath` |
-| `take_snapshot` | Get DOM snapshot | (returns structured JSON) |
-| `take_screenshot` | Capture screenshot | `fullPage`, `ref` |
+| `click` | Click element | `uid`, `dblClick` |
+| `type_text` | Type into focused input | `text`, `submitKey` |
+| `press_key` | Press keyboard key | `key` |
+| `fill_form` | Fill multiple fields | `elements: [{uid, value}]` |
+| `drag` | Drag and drop | `from_uid`, `to_uid` |
+| `hover` | Hover over element | `uid` |
+| `upload_file` | Upload file | `uid`, `filePath` |
+| `take_snapshot` | Get DOM snapshot | (returns structured JSON with uid per element) |
+| `take_screenshot` | Capture screenshot | `fullPage`, `uid`, `filePath`, `format` |
 | `list_console_messages` | Get console logs | (returns array) |
 | `list_network_requests` | Get network activity | (returns array) |
 | `evaluate_script` | Run JavaScript | `code` |
 | `handle_dialog` | Handle alert/confirm | `action`, `text` |
 | `close_page` | Close browser tab | |
 | `resize_page` | Change viewport | `width`, `height` |
-| `wait_for` | Wait for condition | `timeout`, `condition` |
+| `wait_for` | Wait for text to appear | `text` (array of strings), `timeout` |
 
 ---