npm - @fluentcommerce/fluent-mcp-extn - Versions diffs - 0.1.0 → 0.2.1 - Mend

@fluentcommerce/fluent-mcp-extn 0.1.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/README.md +823 -818
package/dist/fluent-client.js +12 -12
package/dist/tools.js +17 -0
package/docs/CONTRIBUTING.md +100 -100
package/docs/E2E_TESTING.md +739 -739
package/docs/HANDOVER_ENV.example +29 -29
package/docs/HANDOVER_GITHUB_COPILOT.md +165 -165
package/docs/RUNBOOK.md +312 -312
package/docs/TOOL_REFERENCE.md +1810 -1810
package/package.json +68 -68
package/docs/IMPLEMENTATION_GUIDE.md +0 -299

package/docs/TOOL_REFERENCE.md CHANGED Viewed

@@ -1,1810 +1,1810 @@
-# Tool Reference
-This document describes every MCP tool exposed by `fluent-mcp-extn`, including
-purpose, required inputs, and example requests.
-## Response envelope conventions
-### Success
-```json
-{
-  "ok": true
-}
-```
-Most tools include extra fields like `event`, `response`, `job`, or `status`.
-### Failure
-```json
-{
-  "ok": false,
-  "error": {
-    "code": "VALIDATION_ERROR",
-    "message": "Invalid tool arguments.",
-    "retryable": false,
-    "details": {}
-  }
-}
-```
-`error.retryable` indicates whether a caller can safely retry the same request. Non-idempotent writes intentionally avoid automatic retry behavior.
-## `config.validate`
-Validates configuration and auth readiness without calling Fluent APIs.
-- **Input**: no fields
-- **Use when**: startup checks, CI preflight, environment validation
-Example:
-```json
-{}
-```
-## `health.ping`
-Returns server health, SDK availability, and safe config summary.
-- **Input**: no fields
-- **Use when**: quick readiness checks in clients/agents
-Example:
-```json
-{}
-```
-## `event.build`
-Builds a Fluent event payload only (no API call).
-- **Required**: `name`, `entityRef`, `entityType`
-- **Optional**: `entityId`, `rootEntityId`, `rootEntityType`, `source`, `type`, `attributes`, etc.
-- **Note**: if available in your flow, provide both `entityRef` and `entityId`.
-Example:
-```json
-{
-  "name": "ORDER_CREATED",
-  "entityRef": "ORD-1001",
-  "entityId": "12345",
-  "entityType": "ORDER",
-  "attributes": {
-    "channel": "web"
-  }
-}
-```
-## `event.send`
-Builds and sends an event via SDK adapter.
-- **Required**: `name`, `entityRef`, `entityType`
-- **Optional**: all `event.build` fields plus:
-  - `mode`: `async` or `sync`
-  - `dryRun`: boolean
-- **Important**: `retailerId` must match the target entity's retailer for real sends.
-Example dry-run:
-```json
-{
-  "name": "ORDER_CREATED",
-  "entityRef": "ORD-1001",
-  "entityId": "12345",
-  "entityType": "ORDER",
-  "dryRun": true
-}
-```
-Example send:
-```json
-{
-  "name": "ORDER_CREATED",
-  "entityRef": "ORD-1001",
-  "entityId": "12345",
-  "entityType": "ORDER",
-  "mode": "async",
-  "dryRun": false
-}
-```
-## `event.get`
-Gets one event by ID via SDK-native `getEventById(eventId)`:
-- endpoint: `/api/v4.1/event/{id}`
-- **Required**: `eventId`
-Example:
-```json
-{
-  "eventId": "7815ee32-5985-485f-863a-2643e57b64a2"
-}
-```
-Typical success shape (truncated):
-```json
-{
-  "ok": true,
-  "event": {
-    "id": "7815ee32-5985-485f-863a-2643e57b64a2",
-    "name": "ORDER_CREATED",
-    "entityRef": "ORD-1001",
-    "entityType": "ORDER",
-    "retailerId": "5"
-  }
-}
-```
-## `event.list`
-Lists/filter events via SDK-native `getEvents(params)`:
-- endpoint: `/api/v4.1/event`
-- **Canonical filters**:
-  - `eventId`, `name`, `category`, `retailerId`
-  - `eventType`, `eventStatus`, `from`, `to`
-  - `start`, `count`
-  - `context.rootEntityType`, `context.rootEntityId`, `context.rootEntityRef`
-  - `context.entityType`, `context.entityId`, `context.entityRef`, `context.sourceEvents`
-- **Alias filters** (mapped internally):
-  - `id` -> `eventId`
-  - `entityRef` -> `context.entityRef`
-  - `entityType` -> `context.entityType`
-  - `type` -> `eventType`
-- **`context.sourceEvents` handling**:
-  - accepts array input in tool arguments
-  - serialized for query-string delivery to Event API
-Example:
-```json
-{
-  "eventType": "ORCHESTRATION_AUDIT",
-  "eventStatus": "FAILED",
-  "context.rootEntityType": "ORDER",
-  "context.rootEntityRef": "ORD-1001",
-  "retailerId": "5",
-  "from": "2026-02-01T00:00:00.000Z",
-  "to": "2026-02-15T23:59:59.999Z",
-  "count": 25,
-  "start": 1
-}
-```
-Typical success shape (truncated):
-```json
-{
-  "ok": true,
-  "events": {
-    "start": 1,
-    "count": 25,
-    "hasMore": true,
-    "results": [
-      { "id": "event-id-1", "name": "ORDER_CREATED" }
-    ]
-  }
-}
-```
-If `event.send` does not return an `id`, use `event.list` with `name`,
-`entityRef`, and `retailerId` to resolve the latest event ID, then call
-`event.get`.
-## `event.flowInspect`
-One-call runtime forensics for any root entity.
-- **Required**: `rootEntityRef`
-- **Optional**:
-  - `rootEntityType`: optional entity type filter (for example `ORDER`, `FULFILMENT`, `LOCATION`, `WAVE`, `PRODUCT`)
-  - `rootEntityId`: optional root entity ID (helps disambiguate reused refs)
-  - `compact`: return pre-analyzed summary instead of raw arrays (default `true`). Compact mode returns ~2-3k tokens with an `analysis` section; set to `false` for full ~24k raw data.
-  - `from`, `to`: optional time window
-  - `maxPages`: page cap per event type (`1..50`, default `10`)
-  - `includeEventDetails`: include compact orchestration event rows (default `true`, full mode only)
-  - `includeAuditDetails`: include compact audit action samples (default `false`, full mode only)
-  - `includeScheduled`: fetch SCHEDULED events separately (default `true`)
-  - `inspectStatuses`: statuses to drill via `event.get` (defaults: `["NO_MATCH", "PENDING", "FAILED"]`)
-  - `maxDrilldowns`: cap on individual event.get calls (`0..100`, default `50`)
-  - `actionSampleLimit`: max rows for action-derived sections (`1..200`, default `100`)
-- **Default-on flags:**
-  - `compact`: pre-analyzed summary response (default `true`)
-  - `includeExceptions`: rule exceptions with class, message, ruleset context (default `true`)
-  - `includeNoMatchDetails`: enhanced NO_MATCH diagnostics from ruleSet audit events with closeMatches (default `true`)
-- **Opt-in flags (default false):**
-  - `includeRuleDetails`: per-rule execution trace with class name, props, and timing (durationMs)
-  - `includeCustomLogs`: custom plugin log messages (LogCollection from CUSTOM category)
-  - `includeSnapshots`: entity state snapshots at each processing point
-  - `includeCrossEntity`: fetch child entity events (FULFILMENT_CHOICE, FULFILMENT) using rootEntityRef
-**Compact mode (`compact: true`, the default):**
-Returns a pre-analyzed summary with:
-- `analysis.statusFlow`: ordered unique statuses seen (e.g., `["CREATED", "BOOKED", "SHIPPED"]`)
-- `analysis.findings[]`: anomaly detection — NO_MATCH (CRITICAL), FAILED/webhook errors/exceptions (HIGH), PENDING/slow rulesets (MEDIUM)
-- `analysis.failedWebhookEndpoints`: URLs that returned >= 400
-- `analysis.slowestRulesets`: top 3 by duration
-- `analysis.timespan`: first/last timestamps with durationMs
-- `audit.webhookActions`: only failures (responseCode >= 400)
-- `audit.mutationActions`: top 5 by queryName (name + count only)
-- `audit.sendEventActions`: count + scheduledCount only
-- `diagnostics.inspectedEvents`: summary (id, name, status, closeMatchCount)
-**Full mode (`compact: false`):**
-Returns complete raw arrays:
-- Orchestration timeline counts (`status`, `entityType`, top names)
-- Audit category/action breakdown with ruleset durations
-- Mutation payload evidence from ACTION audit (`DynamicUpdateMutation` request blocks)
-- Webhook diagnostics (`Request Endpoint`, `Response code`, `Response Body`, headers)
-- SendEvent payloads and future-dated scheduling evidence
-- Rule exceptions (when `includeExceptions: true`)
-- NO_MATCH closeMatches with mismatch reasons (when `includeNoMatchDetails: true`)
-- Per-rule execution with props/timing (when `includeRuleDetails: true`)
-- Custom plugin logs (when `includeCustomLogs: true`)
-- Entity snapshots (when `includeSnapshots: true`)
-- Cross-entity events with full events array (when `includeCrossEntity: true`)
-- `NO_MATCH`/`PENDING`/`FAILED` drilldown with full event payload via `event.get`
-- Auto-recommendations based on findings
-Example (compact — recommended first call):
-```json
-{
-  "rootEntityRef": "E2E_MULTI_202602221343",
-  "rootEntityType": "ORDER"
-}
-```
-Example (full data with all sections):
-```json
-{
-  "rootEntityRef": "ORD-001",
-  "rootEntityType": "ORDER",
-  "compact": false,
-  "includeRuleDetails": true,
-  "includeCustomLogs": true,
-  "includeSnapshots": true,
-  "includeCrossEntity": true
-}
-```
-Example (lightweight):
-```json
-{
-  "rootEntityRef": "ORD-001",
-  "rootEntityType": "ORDER",
-  "includeEventDetails": false,
-  "includeExceptions": false,
-  "includeNoMatchDetails": false,
-  "maxDrilldowns": 0
-}
-```
-## `metrics.query`
-Queries Prometheus metrics for Fluent runtime telemetry.
-- **Required**: `query` (PromQL expression)
-- **Optional**:
-  - `type`: `instant` (default) or `range`
-  - `time`: instant query timestamp
-  - `start`, `end`, `step`: required together for range queries
-  - `timeout`: query timeout in seconds (`1..120`)
-- **Execution path**:
-  - instant -> GraphQL `metricInstant(query, time?)`
-  - range -> GraphQL `metricRange(query, start, end, step)`
-- **Note**: `metrics.query` routes PromQL through Fluent's GraphQL proxy. Raw Prometheus REST endpoints are not relied on directly by this tool.
-Label hygiene reminder:
-- `core_event_received_total` does **not** include `status`
-- `rubix_event_runtime_seconds_*` does include `status`
-- histogram bucket series add `le`
-Accurate counter delta pattern for wider windows:
-```promql
-(last_over_time(metric[window]) - metric offset <period>)
-or
-last_over_time(metric[window])
-```
-Use the fallback `or` arm when offset samples are missing.
-Instant example:
-```json
-{
-  "query": "sum(rate(rubix_event_runtime_seconds_count[5m]))",
-  "type": "instant"
-}
-```
-Range example:
-```json
-{
-  "query": "rate(rubix_event_runtime_seconds_count{status=\"FAILED\"}[5m])",
-  "type": "range",
-  "start": "2026-02-20T00:00:00Z",
-  "end": "2026-02-20T01:00:00Z",
-  "step": "1m"
-}
-```
-## `metrics.topEvents`
-Returns ranked event analytics for a time window by aggregating Event API results.
-- **Required**: `from`
-- **Optional**:
-  - `to`: end timestamp (defaults to now)
-  - `entityType`: filter to one entity type
-  - `eventType`: defaults to `ORCHESTRATION`
-  - `topN`: ranked rows to return (`1..100`, default `20`)
-  - `maxPages`: Event API pagination cap (`1..50`, default `10`)
-- **Output summary**:
-  - `totalEvents`, `failureRate`, `statusBreakdown`
-  - `topEvents[]` grouped by `name + entityType + status`
-  - `uniqueEventNames`, `uniqueEntityTypes`
-Example:
-```json
-{
-  "from": "2026-02-22T00:00:00Z",
-  "to": "2026-02-22T12:00:00Z",
-  "topN": 20,
-  "eventType": "ORCHESTRATION"
-}
-```
-## `metrics.healthCheck`
-Runs a compact, one-call anomaly assessment.
-- **Optional**:
-  - `window`: Prometheus/Event API analysis window (`1h`, `6h`, `24h`, `7d`; default `1h`)
-  - `includeTopEvents`: include ranked event list in response (default `true`)
-  - `topN`: max top event rows (`1..100`, default `10`)
-  - `thresholds`: override defaults
-    - `failureRate` (default `5`)
-    - `pendingRate` (default `10`)
-    - `dominanceRate` (default `50`)
-- **Behavior**:
-  - Prometheus-first (`metrics.query` equivalent calls under the hood)
-  - Falls back to Event API aggregation if Prometheus is unavailable
-Example:
-```json
-{
-  "window": "1h",
-  "includeTopEvents": true,
-  "topN": 10
-}
-```
-## `metrics.sloReport`
-Returns a managed-services SLO snapshot with explicit KPI fields and threshold findings.
-- **Optional**:
-  - `window`: KPI window (`30m`, `1h`, `24h`, `7d`; default `1h`)
-  - `includeTopFailingEvents`: include top failed events from Event API (default `true`)
-  - `topN`: top failed rows (`1..100`, default `10`)
-  - `maxPages`: Event API pagination cap for fallback/failed ranking (`1..50`, default `10`)
-  - `thresholds`: override defaults
-    - `failureRate` (default `5`)
-    - `noMatchRate` (default `0`)
-    - `pendingRate` (default `10`)
-    - `runtimeP95Seconds` (default `5`)
-    - `inflightP95Seconds` (default `60`)
-- **Output highlights**:
-  - total/failed/no-match/pending event counts
-  - failure/no-match/pending rates
-  - p95 runtime and inflight latency (null when Prometheus fallback path is used)
-  - findings + recommendations + source (`prometheus` or `event_api`)
-Example:
-```json
-{
-  "window": "1h",
-  "includeTopFailingEvents": true,
-  "topN": 10
-}
-```
-## `metrics.labelCatalog`
-Discovers what labels a metric supports so PromQL groupings are correct.
-- **Required**: `metric`
-- **Optional**:
-  - `window`: live series sampling window (`30m`, `1h`, `24h`, `7d`; default `24h`)
-  - `includeKnownLabels`: include Fluent-known label hints (default `true`)
-  - `maxValuesPerLabel`: max sample values returned per label (`1..50`, default `10`)
-- **Behavior**:
-  - runs `last_over_time(<metric>[window])` as an instant query
-  - extracts label keys from returned vector series
-  - reports presence/cardinality/sample values per label
-  - merges known Fluent label hints when available
-Example:
-```json
-{
-  "metric": "core_event_received_total",
-  "window": "1h",
-  "maxValuesPerLabel": 10
-}
-```
-## `workflow.transitions`
-Query available user actions (transitions) for entities at a given workflow state.
-Calls `POST /api/v4.1/transition` to discover what events can be fired, what attributes they require, and how they appear in the UI.
-- **Required**: `triggers` (array), each trigger requires `retailerId`
-- **Optional per trigger**: `type`, `subtype`, `status`, `module`, `flexType`, `flexVersion`, `name`
-- **Retailer behavior**: `retailerId` is required per trigger. Falls back to `FLUENT_RETAILER_ID` when omitted.
-### Use cases
-- Discover available actions at any workflow status without reading workflow JSON
-- Build dynamic E2E test sequences that adapt to workflow changes
-- Validate that expected user actions are available after deployment
-- Get required event attributes for each action (avoids missing-attribute errors)
-### Integration with event.send
-The `eventName` from each `userAction` maps directly to `event.send`'s `name` parameter. The `attributes[]` tell you what to include in `event.send`'s `attributes` parameter.
-### Example: ORDER at CREATED status
-```json
-{
-  "triggers": [
-    {
-      "type": "ORDER",
-      "subtype": "HD",
-      "status": "CREATED",
-      "retailerId": "5",
-      "flexType": "ORDER::HD"
-    }
-  ]
-}
-```
-### Example: MANIFEST with module filter
-```json
-{
-  "triggers": [
-    {
-      "type": "MANIFEST",
-      "subtype": "DEFAULT",
-      "status": "PENDING",
-      "module": "servicepoint",
-      "flexType": "CARRIER::DEFAULT",
-      "retailerId": "2"
-    }
-  ]
-}
-```
-Typical success shape (truncated):
-```json
-{
-  "ok": true,
-  "response": {
-    "response": [
-      {
-        "trigger": {
-          "type": "MANIFEST",
-          "subtype": "DEFAULT",
-          "status": "PENDING",
-          "module": "servicepoint",
-          "flexType": "CARRIER::DEFAULT",
-          "retailerId": "2"
-        },
-        "userActions": [
-          {
-            "eventName": "UPDATE",
-            "context": [
-              { "label": "SUBMIT", "type": "PRIMARY", "modules": ["servicepoint"], "confirm": false }
-            ],
-            "attributes": []
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-### Dynamic test sequence pattern
-```
-1. Create entity via graphql.query (mutation)
-2. workflow.transitions → get available actions at current status
-3. For each action:
-   a. event.send with eventName and required attributes from response
-   b. Poll entity status until transition completes
-   c. workflow.transitions → get next available actions
-4. Repeat until no more userActions (terminal state)
-```
-## `plugin.list`
-List all registered orchestration rules (standard + custom) with metadata.
-Calls `GET /orchestration/rest/v1/plugin` and returns a map keyed by fully-qualified rule name (e.g. `ACCOUNT.context.RuleName`).
-- **Optional**: `name` (string) — case-insensitive substring filter on rule keys
-- **Requires**: SDK client with `request` method
-### Each entry contains
-- `ruleInfo`: name, description, accepted entity types, produced events
-- `eventAttributes`: attributes the rule reads from events
-- `parameters`: configurable rule parameters (with types and descriptions)
-### Use cases
-- Understand what rules do when analyzing workflows
-- Discover all registered rules (standard + custom) for a given account
-- Find rules by name pattern (e.g. all "SendEvent" variants)
-- Cross-reference deployed rules with local source code for module validation
-### Example: list all rules
-```json
-{}
-```
-### Example: filter by name
-```json
-{
-  "name": "SendEvent"
-}
-```
-Typical success shape (truncated):
-```json
-{
-  "ok": true,
-  "response": {
-    "FLUENTRETAIL.base.SendEvent": {
-      "ruleInfo": {
-        "name": "SendEvent",
-        "description": "Sends an event to a specified entity",
-        "accepts": ["ORDER", "FULFILMENT", "ARTICLE"],
-        "produces": ["SendEvent"]
-      },
-      "eventAttributes": [
-        { "name": "eventName", "type": "STRING", "description": "Name of the event to send" }
-      ],
-      "parameters": [
-        { "name": "eventName", "type": "STRING", "description": "Event name to dispatch" }
-      ]
-    }
-  }
-}
-```
-## `graphql.query`
-Executes a Fluent Commerce GraphQL query or mutation through the SDK.
-- **Required**: `query`
-- **Optional**: `variables`
-- **Retry behavior**:
-  - query operations use configured retry/backoff
-  - mutation operations disable retries automatically to avoid duplicate writes
-### Basic Query
-```json
-{
-  "query": "query { orders(first: 5) { edges { cursor node { id ref status } } pageInfo { hasNextPage } } }"
-}
-```
-### Pagination
-Fluent uses Relay-style connections. Cursors live on each **edge**, not on `pageInfo`. There is no `endCursor` or `startCursor`.
-```json
-{
-  "query": "query($cursor: String) { orders(first: 50, after: $cursor) { edges { cursor node { id ref status } } pageInfo { hasNextPage } } }",
-  "variables": { "cursor": "Y3Vyc29yOi0tLTM2X18xNzcxMTc2MzMyMTc0" }
-}
-```
-To paginate: take the `cursor` from the **last edge** in the response, pass it as the `after` variable. Repeat while `hasNextPage` is `true`.
-Pagination args: `first`/`after` (forward), `last`/`before` (backward).
-### Mutation
-```json
-{
-  "query": "mutation($input: UpdateOrderInput!) { updateOrder(input: $input) { id ref status } }",
-  "variables": { "input": { "id": "36", "status": "RECEIVED" } }
-}
-```
-### Synchronous Fulfilment Options (Live Checkout)
-`graphql.query` supports synchronous fulfilment options orchestration calls,
-commonly used by checkout journeys to get plans in the same response.
-```json
-{
-  "query": "mutation CreateFulfilmentOption($retailerId: Int!, $type: String!, $orderType: String!, $ref: String!, $products: [CreateFulfilmentOptionProductInput!], $longitude: Float!, $latitude: Float!, $radius: Json!) { createFulfilmentOption(input: { retailerId: $retailerId, type: $type, orderType: $orderType, ref: $ref, products: $products, address: { city: \"Kellyville Ridge\", state: \"New South Wales\", country: \"Australia\", postcode: \"2155\", addressLine1: \"Kellyville Ridge NSW, Australia\", latitude: $latitude, longitude: $longitude }, attributes: { name: \"radius\", type: \"DOUBLE\", value: $radius } }, executionMode: AWAIT_ORCHESTRATION) { id createdOn plans { edges { node { ref status eta splitCount fulfilments { locationRef eta items { productRef availableQuantity requestedQuantity } } } } } } }",
-  "variables": {
-    "retailerId": 5,
-    "type": "CC",
-    "orderType": "CC",
-    "ref": "CHECKOUT-FO-12345",
-    "products": [
-      { "productRef": "MP09-34-Blue", "requestedQuantity": 1, "catalogueRef": "" }
-    ],
-    "longitude": 150.9193671,
-    "latitude": -33.7068442,
-    "radius": 50
-  }
-}
-```
-Notes:
-- `executionMode: AWAIT_ORCHESTRATION` makes the call synchronous.
-- The environment must contain a matching workflow for `type` (for example `FULFILMENT_OPTIONS::CC`).
-- If no matching workflow exists, Fluent returns a backend workflow-not-found error.
-### Connection Shape
-All list queries return connections:
-```graphql
-{
-  edges {
-    cursor
-    node { ...fields }
-  }
-  pageInfo { hasNextPage }
-}
-```
-Common query roots: `orders`, `fulfilments`, `fulfilmentChoices`, `locations`, `inventoryPositions`, `products`, `categories`, `settings`, `waves`, `articles`.
-## `batch.create`
-Creates a Fluent ingestion job.
-- **Required**: `name`
-- **Optional**: `retailerId`, `entityType`, `action`
-- **Note**: `retailerId` falls back to `FLUENT_RETAILER_ID` if omitted
-Example:
-```json
-{
-  "name": "inventory-load-2026-02-06",
-  "entityType": "INVENTORY_POSITION",
-  "action": "UPSERT"
-}
-```
-## `batch.send`
-Sends payload records to an existing batch job.
-- **Required**:
-  - `jobId`
-  - `payload.action`
-  - `payload.entityType`
-  - `payload.entities` (non-empty array)
-Example:
-```json
-{
-  "jobId": "JOB-123",
-  "payload": {
-    "action": "UPSERT",
-    "entityType": "INVENTORY_POSITION",
-    "entities": [
-      {
-        "locationRef": "LOC-1",
-        "skuRef": "SKU-1",
-        "qty": 10,
-        "type": "LAST_ON_HAND",
-        "status": "ACTIVE"
-      }
-    ]
-  }
-}
-```
-## `batch.status`
-Reads status for a previously created batch job.
-- **Required**: `jobId`
-Example:
-```json
-{
-  "jobId": "JOB-123"
-}
-```
-## `batch.batchStatus`
-Gets the status of a specific batch within a job. Useful for troubleshooting partial failures in multi-batch jobs.
-- **Required**: `jobId`, `batchId`
-Example:
-```json
-{
-  "jobId": "JOB-123",
-  "batchId": "BATCH-456"
-}
-```
-## `batch.results`
-Gets per-record outcomes for a completed job. Call after `batch.status` reports a terminal state.
-- **Required**: `jobId`
-Example:
-```json
-{
-  "jobId": "JOB-123"
-}
-```
----
-## `graphql.queryAll`
-Executes a GraphQL query with SDK auto-pagination. Automatically follows cursors, merges all edges, and deduplicates by node ID. Use instead of `graphql.query` when you need ALL records from a connection.
-- **Required**: `query`
-- **Optional**:
-  - `variables`: query variables (include cursor variable, usually `null` for first page)
-  - `maxPages`: max pages to fetch (default: 100, max: 500)
-  - `maxRecords`: max total records to accumulate (default: 10000, max: 50000)
-  - `timeoutMs`: hard timeout for entire pagination run (default: 300000ms = 5 min)
-  - `direction`: `forward` (first/after) or `backward` (last/before)
-  - `errorHandling`: `throw` (fail on errors) or `partial` (return partial data + errors)
-- **Timeout behavior**:
-  - uses `timeoutMs` for the whole pagination run
-  - independent from `FLUENT_REQUEST_TIMEOUT_MS` single-call timeout
-### How it works
-1. SDK detects pagination variables (`first`/`after` or `last`/`before`) in your query
-2. Executes the first page
-3. Extracts cursor from the last edge, follows `hasNextPage`
-4. Merges edges across pages, deduplicates by node ID
-5. Stops when: no more pages, maxPages reached, maxRecords reached, or timeout
-### Response
-Includes `extensions.autoPagination`:
-```json
-{
-  "totalPages": 5,
-  "totalRecords": 487,
-  "truncated": false,
-  "direction": "forward"
-}
-```
-If truncated: `truncationReason` will be `"maxPages"`, `"maxRecords"`, or `"timeout"`.
-### Example: Fetch all active orders
-```json
-{
-  "query": "query($cursor: String) { orders(first: 100, after: $cursor, status: \"ACTIVE\") { edges { cursor node { id ref status createdOn } } pageInfo { hasNextPage } } }",
-  "variables": { "cursor": null },
-  "maxRecords": 5000
-}
-```
-### Example: Fetch all locations (backward)
-```json
-{
-  "query": "query($cursor: String) { locations(last: 50, before: $cursor) { edges { cursor node { id ref name type } } pageInfo { hasPreviousPage } } }",
-  "variables": { "cursor": null },
-  "direction": "backward"
-}
-```
-## `graphql.batchMutate`
-Executes multiple GraphQL mutations in a single request using aliased mutations. Sends up to 50 mutations at once, each with its own input.
-- **Required**: `mutation`, `inputs`
-- **Optional**: `returnFields`, `operationName`
-- **Retry behavior**: disabled (non-idempotent write operation)
-### How it works
-1. Builds an aliased mutation query:
-   ```graphql
-   mutation BatchUpdateOrders($input1: UpdateOrderInput!, $input2: UpdateOrderInput!) {
-     updateOrder1: updateOrder(input: $input1) { id ref status }
-     updateOrder2: updateOrder(input: $input2) { id ref status }
-   }
-   ```
-2. Sends as a single GraphQL request
-3. Parses per-mutation results (success/failure for each input)
-### Response
-```json
-{
-  "ok": true,
-  "summary": "All 3 mutations succeeded",
-  "executed": 3,
-  "failed": 0,
-  "allSucceeded": true,
-  "allFailed": false,
-  "results": [
-    { "alias": "updateOrder1", "index": 0, "success": true, "data": { "id": "1", "ref": "ORD-001", "status": "SHIPPED" } },
-    { "alias": "updateOrder2", "index": 1, "success": true, "data": { "id": "2", "ref": "ORD-002", "status": "SHIPPED" } }
-  ]
-}
-```
-On partial failure, `errors` array includes per-mutation error details with `alias`, `index`, `message`, and `inputRef`.
-### Example: Bulk update order statuses
-```json
-{
-  "mutation": "updateOrder",
-  "inputs": [
-    { "id": "36", "status": "SHIPPED" },
-    { "id": "37", "status": "SHIPPED" },
-    { "id": "38", "status": "SHIPPED" }
-  ],
-  "returnFields": ["id", "ref", "status"]
-}
-```
-### Example: Batch create inventory positions
-```json
-{
-  "mutation": "updateInventoryPosition",
-  "inputs": [
-    { "id": "100", "status": "ACTIVE" },
-    { "id": "101", "status": "ACTIVE" }
-  ],
-  "returnFields": ["id", "ref", "status", "onHand"]
-}
-```
-## `graphql.introspect`
-Inspects the Fluent Commerce GraphQL schema via introspection. Fetches the full schema and caches it for 1 hour. Use to discover mutations, input types, and field requirements at runtime.
-- **Optional** (specify one mode):
-  - `type`: name of an INPUT_OBJECT type to inspect (e.g., `UpdateOrderInput`)
-  - `mutation`: name of a mutation to inspect (e.g., `updateOrder`)
-  - `listMutations`: `true` to list all available mutation names
-  - `listQueries`: `true` to list all available query root field names
-### Example: List all mutations
-```json
-{
-  "listMutations": true
-}
-```
-Response:
-```json
-{
-  "ok": true,
-  "mutations": ["createOrder", "updateOrder", "createFulfilment", "..."],
-  "count": 142
-}
-```
-### Example: Inspect a mutation
-```json
-{
-  "mutation": "updateOrder"
-}
-```
-Response:
-```json
-{
-  "ok": true,
-  "mutation": {
-    "name": "updateOrder",
-    "description": "Updates an existing order",
-    "args": [
-      {
-        "name": "input",
-        "type": "UpdateOrderInput!",
-        "required": true
-      }
-    ],
-    "returnType": "Order"
-  }
-}
-```
-### Example: Inspect an input type
-```json
-{
-  "type": "UpdateOrderInput"
-}
-```
-Response:
-```json
-{
-  "ok": true,
-  "inputType": {
-    "name": "UpdateOrderInput",
-    "fields": [
-      { "name": "id", "type": "ID!", "required": true },
-      { "name": "ref", "type": "String", "required": false },
-      { "name": "status", "type": "String", "required": false },
-      { "name": "attributes", "type": "[AttributeInput]", "required": false, "isArray": true }
-    ]
-  }
-}
-```
-### Chaining example
-1. `{ "listMutations": true }` → find `updateOrder`
-2. `{ "mutation": "updateOrder" }` → see it takes `UpdateOrderInput!`
-3. `{ "type": "UpdateOrderInput" }` → see all updatable fields
-4. Use `graphql.query` or `graphql.batchMutate` with the discovered schema
-## `connection.test`
-Comprehensive Fluent Commerce connectivity test. Authenticates, executes a `me` query, and returns the authenticated user's details.
-- **Input**: no fields
-### Response (success)
-```json
-{
-  "ok": true,
-  "duration": 342,
-  "details": {
-    "userId": "12",
-    "username": "admin@hmtest.com",
-    "userType": "RETAILER",
-    "userStatus": "ACTIVE",
-    "retailerId": "5",
-    "retailerRef": "HMTEST",
-    "retailerName": "HM Test",
-    "locationId": "10",
-    "locationRef": "W252",
-    "locationName": "Warehouse 252"
-  }
-}
-```
-### Response (failure)
-```json
-{
-  "ok": false,
-  "duration": 1500,
-  "error": "Authentication failed after 3 retries: 401 Unauthorized"
-}
-```
-More thorough than `health.ping` — actually verifies the GraphQL endpoint works end-to-end. Use when first connecting, debugging auth issues, or verifying retailer/location context.
-## `webhook.validate`
-Validates a Fluent Commerce webhook payload and optionally verifies its signature.
-- **Required**: `payload`
-- **Optional**:
-  - `rawBody`: exact original HTTP request body string for signature checks
-  - `signature`: the `X-Fluent-Signature` header value (base64-encoded)
-  - `publicKey`: the Fluent public key (PEM format) for signature verification
-  - `algorithm`: `SHA512withRSA` (default) or `MD5withRSA`
-### Mode 1: Basic validation
-Checks that required fields (`name`, `id`, `retailerId`) are present in the payload.
-```json
-{
-  "payload": {
-    "name": "OrderCreated",
-    "id": "event-123",
-    "retailerId": "5",
-    "entityType": "ORDER",
-    "entityRef": "ORD-001"
-  }
-}
-```
-Response:
-```json
-{
-  "ok": true,
-  "basicValidation": { "valid": true, "missingFields": [] },
-  "note": "Basic field validation passed. Provide signature + publicKey for signature verification."
-}
-```
-### Mode 2: Signature validation
-Verifies the webhook body against the `X-Fluent-Signature` header using the provided public key.
-Use `rawBody` whenever possible because signature verification is byte-sensitive.
-```json
-{
-  "payload": {
-    "name": "OrderCreated",
-    "id": "event-123",
-    "retailerId": "5"
-  },
-  "rawBody": "{\"name\":\"OrderCreated\",\"id\":\"event-123\",\"retailerId\":\"5\"}",
-  "signature": "base64-encoded-signature-from-header",
-  "publicKey": "-----BEGIN PUBLIC KEY-----\nMIIBI...\n-----END PUBLIC KEY-----",
-  "algorithm": "SHA512withRSA"
-}
-```
-Response:
-```json
-{
-  "ok": true,
-  "basicValidation": { "valid": true, "missingFields": [] },
-  "signatureValidation": {
-    "valid": true,
-    "algorithm": "SHA512withRSA",
-    "payloadSource": "rawBody"
-  }
-}
-```
----
-## `entity.create`
-Type-safe entity creation with built-in validation and gotcha knowledge.
-**Supported entity types:** ORDER, FULFILMENT, LOCATION, NETWORK, CUSTOMER, PRODUCT, INVENTORY_POSITION, VIRTUAL_CATALOGUE, VIRTUAL_POSITION, CATEGORY, CARRIER, SETTING
-- **Required**:
-  - `entityType`: entity type string (see supported list above)
-  - `data`: creation input fields matching the GraphQL create input type
-- **Optional**:
-  - `returnFields`: array of field names to return (defaults to entity type defaults)
-  - `dryRun`: if `true`, builds and validates the mutation without executing (default `false`)
-**Key behaviors:**
-- Validates required fields BEFORE sending (e.g., Location requires `openingSchedule`)
-- Encodes compound key rules (ProductKey needs `ref` + `catalogue.ref`)
-- Auto-resolves `retailerId` from config for retailer-scoped entities
-- Returns the executed mutation string for audit trail
-**Known gotchas (encoded in validation):**
-- No create inputs have a `status` field — status is auto-set to `CREATED`
-- `Customer` has NO `ref` field; `username` is the identifier
-- `Network` uses `name` (not `ref`) in create; `retailers` is a plural array
-- `Location` requires `openingSchedule` even for 24/7 (use `allHours: true`)
-- `Product` `gtin` has a 20-character max
-- `Setting` `context` is a plain String, `contextId` is a separate Int
-**Example** — create a location (dry run):
-```json
-{
-  "entityType": "LOCATION",
-  "data": {
-    "ref": "LOC_WH_01",
-    "type": "WAREHOUSE",
-    "name": "Main Warehouse",
-    "openingSchedule": { "allHours": true }
-  },
-  "dryRun": true
-}
-```
-Response (dry run):
-```json
-{
-  "ok": true,
-  "dryRun": true,
-  "entityType": "LOCATION",
-  "mutation": "mutation CreateLocation($input: CreateLocationInput!) { createLocation(input: $input) { id ref status type name } }",
-  "inputType": "CreateLocationInput",
-  "variables": { "input": { "ref": "LOC_WH_01", "type": "WAREHOUSE", "name": "Main Warehouse", "openingSchedule": { "allHours": true } } },
-  "requiredFields": ["ref", "type", "name", "openingSchedule"],
-  "gotchas": ["Location requires openingSchedule — use { allHours: true } for 24/7"],
-  "note": "No API call made. Set dryRun=false to execute."
-}
-```
-**Example** — create a location (real):
-```json
-{
-  "entityType": "LOCATION",
-  "data": {
-    "ref": "LOC_WH_01",
-    "type": "WAREHOUSE",
-    "name": "Main Warehouse",
-    "openingSchedule": { "allHours": true }
-  }
-}
-```
-Response:
-```json
-{
-  "ok": true,
-  "entityType": "LOCATION",
-  "entity": { "id": "42", "ref": "LOC_WH_01", "status": "CREATED", "type": "WAREHOUSE", "name": "Main Warehouse" },
-  "mutation": "mutation CreateLocation($input: CreateLocationInput!) { ... }"
-}
-```
----
-## `entity.update`
-Status-aware entity updates with optional transition validation.
-- **Required**:
-  - `entityType`: entity type string
-  - `id`: entity ID (required for updates)
-  - `fields`: object of fields to update (matches GraphQL update input type)
-- **Optional**:
-  - `returnFields`: array of field names to return
-  - `validateTransition`: if `true` and `status` is being changed, queries `workflow.transitions` to verify the transition is allowed before executing (default `false`)
-**Key behaviors:**
-- Auto-detects the correct GraphQL mutation name from entity type
-- When `validateTransition` is `true`: fetches current entity state, queries transition API, warns if no workflow transitions exist from the current status
-- Returns the previous status for audit trail when transition validation is used
-- Uses no-retry semantics (write operation)
-**Example** — update order status with transition validation:
-```json
-{
-  "entityType": "ORDER",
-  "id": "12345",
-  "fields": { "status": "COMPLETE" },
-  "validateTransition": true
-}
-```
-Response:
-```json
-{
-  "ok": true,
-  "entityType": "ORDER",
-  "entity": { "id": "12345", "ref": "HD-001", "status": "COMPLETE" },
-  "mutation": "mutation UpdateOrder($input: UpdateOrderInput!) { ... }"
-}
-```
-If no workflow transition exists:
-```json
-{
-  "ok": true,
-  "entityType": "ORDER",
-  "entity": { "id": "12345", "ref": "HD-001", "status": "COMPLETE" },
-  "mutation": "...",
-  "transitionWarning": "No workflow transitions available from status \"BOOKED\" for ORDER. The status update may succeed as a direct mutation but will not trigger workflow orchestration."
-}
-```
----
-## `entity.get`
-Unified entity lookup by ID or ref with optional edge inclusion.
-- **Required**:
-  - `entityType`: entity type string
-  - At least one of `id` or `ref`
-- **Optional**:
-  - `id`: entity ID (preferred lookup method)
-  - `ref`: entity ref (fallback — not available for CUSTOMER)
-  - `fields`: array of field names to return (defaults to entity type defaults: id, ref, status, type, createdOn, etc.)
-  - `includeEdges`: array of related entity edges to fetch (e.g., `["fulfilments", "items", "attributes"]`)
-**Key behaviors:**
-- Prefers ID-based lookup (single entity query) over ref-based lookup (connection query)
-- Ref-based lookup uses the connection query pattern (edges/node)
-- Returns `{ found: false }` when entity is not found (not an error)
-- CUSTOMER entity type does not support ref-based lookup
-**Example** — get order by ref with fulfilments:
-```json
-{
-  "entityType": "ORDER",
-  "ref": "HD-001",
-  "includeEdges": ["fulfilments"]
-}
-```
-Response:
-```json
-{
-  "ok": true,
-  "found": true,
-  "entityType": "ORDER",
-  "entity": {
-    "id": "12345",
-    "ref": "HD-001",
-    "status": "BOOKED",
-    "type": "HD",
-    "fulfilments": {
-      "edges": [
-        { "node": { "id": "67890", "ref": "FUL-001", "status": "CREATED" } }
-      ]
-    }
-  }
-}
-```
----
-## `workflow.upload`
-Deploy a workflow JSON definition to the Fluent environment.
-Uploads via REST API `POST /api/v4.1/workflow/{retailerId}` — the same endpoint the Fluent CLI uses.
-- **Required**:
-  - `workflow`: workflow JSON definition (as object or JSON string)
-- **Optional**:
-  - `retailerId`: target retailer ID (falls back to `FLUENT_RETAILER_ID`)
-  - `validate`: validate structure before uploading (default `true`)
-  - `dryRun`: validate only, do not deploy (default `false`)
-**Validation checks:**
-- `name` field present
-- At least one status defined in `statuses` array
-- All rulesets have `name`, `triggers`, and `rules` (warns if empty)
-**Important:** For production deployments, prefer `fluent module install` via CLI which bundles workflows with settings, rules, and data in a versioned module. Use this tool for interactive editing, hotfixes, or when CLI is unavailable.
-**Example** — dry-run validation:
-```json
-{
-  "workflow": {
-    "name": "ORDER::HD",
-    "type": "ORDER",
-    "subtype": "HD",
-    "statuses": [{ "name": "CREATED" }, { "name": "BOOKED" }],
-    "rulesets": [
-      {
-        "name": "BookOrder",
-        "triggers": [{ "status": "CREATED" }],
-        "rules": [{ "name": "com.fluentretail.rubix.rule.order.SendEventOnVerifyingState", "props": { "status": "BOOKED" } }]
-      }
-    ]
-  },
-  "dryRun": true
-}
-```
-Response (dry run — valid):
-```json
-{
-  "ok": true,
-  "dryRun": true,
-  "valid": true,
-  "workflowName": "ORDER::HD",
-  "retailerId": "5",
-  "note": "Validation passed. Set dryRun=false to deploy."
-}
-```
----
-## `workflow.diff`
-Compare two workflow JSON definitions and identify changes.
-Pure local computation — no API calls.
-- **Required**:
-  - `base`: base workflow JSON (before changes)
-  - `target`: target workflow JSON (after changes)
-- **Optional**:
-  - `format`: output format — `summary` (default), `detailed`, or `mermaid`
-**Comparison scope:**
-- Rulesets: added, removed, modified (trigger changes, rule additions/removals, prop changes)
-- Statuses: added, removed
-- Risk assessment: removing rulesets or statuses = HIGH, modifying props = MEDIUM, adding = LOW
-**Formats:**
-| Format | Returns |
-|---|---|
-| `summary` | Change counts, status changes, risk level |
-| `detailed` | Full `WorkflowDiffResult` object with per-ruleset breakdown |
-| `mermaid` | `stateDiagram-v2` with color-coded added/removed/modified states and transitions |
-**Example** — summary diff:
-```json
-{
-  "base": { "name": "ORDER::HD", "statuses": [...], "rulesets": [...] },
-  "target": { "name": "ORDER::HD", "statuses": [...], "rulesets": [...] },
-  "format": "summary"
-}
-```
-Response:
-```json
-{
-  "ok": true,
-  "summary": "3 ruleset change(s): 1 added, 0 removed, 2 modified. 1 status change(s): 1 added, 0 removed. Risk level: MEDIUM.",
-  "riskLevel": "medium",
-  "rulesetChanges": { "added": 1, "removed": 0, "modified": 2 },
-  "statusChanges": { "added": ["AWAITING_PICKUP"], "removed": [] }
-}
-```
----
-## `workflow.simulate`
-Static prediction of workflow event outcomes from workflow JSON.
-Pure local computation — no API calls. Parses workflow JSON to find matching rulesets and predict state transitions, follow-on events, and webhook side effects.
-- **Required**:
-  - `workflow`: workflow JSON definition (as object or JSON string)
-  - `currentStatus`: entity status to simulate from (e.g., `CREATED`, `BOOKED`)
-- **Optional**:
-  - `eventName`: event name to match against ruleset names (if omitted, returns all rulesets triggered by `currentStatus`)
-  - `entityType`: entity type filter for trigger matching
-  - `entitySubtype`: entity subtype filter for trigger matching
-**What it does:**
-- Finds rulesets whose triggers match `currentStatus` (and optionally `eventName`)
-- Extracts `SetState`/`ChangeState` rules → predicted next status
-- Extracts `SendEvent` rules → predicted follow-on events
-- Extracts `SendWebhook` rules → predicted webhook side effects
-- Identifies custom Java rules that cannot be statically predicted
-**Important limitations (always disclosed in response):**
-- **STATIC ONLY** — cannot evaluate runtime conditions, entity attributes, or settings values
-- **CUSTOM RULES OPAQUE** — Java plugin rules may conditionally execute; behavior unknown without live state
-- **NO CROSS-ENTITY** — does not follow SendEvent chains into child entity workflows
-- Use `workflow.transitions` for **authoritative live validation** of available actions
-**Example** — simulate from CREATED status:
-```json
-{
-  "workflow": { "name": "ORDER::HD", "rulesets": [...] },
-  "currentStatus": "CREATED",
-  "eventName": "BookOrder"
-}
-```
-Response:
-```json
-{
-  "ok": true,
-  "workflowName": "ORDER::HD",
-  "currentStatus": "CREATED",
-  "eventName": "BookOrder",
-  "matchedRulesets": 1,
-  "rulesets": [
-    {
-      "name": "BookOrder",
-      "matchType": "statusAndEvent",
-      "predictedStatus": "BOOKED",
-      "predictedEvents": ["SendToFulfilment"],
-      "predictedWebhooks": [],
-      "ruleCount": 3
-    }
-  ],
-  "prediction": {
-    "likelyNextStatus": "BOOKED",
-    "followOnEvents": ["SendToFulfilment"],
-    "webhookSideEffects": [],
-    "confidence": "low",
-    "note": "Custom rules present — prediction may be incomplete or wrong."
-  },
-  "limitations": [
-    "STATIC PREDICTION ONLY — does not account for runtime conditions, entity attributes, or settings values.",
-    "1 custom rule(s) found whose behavior cannot be predicted statically: ForwardIfOrderCoordinatesPresent.",
-    "Use workflow.transitions for AUTHORITATIVE live validation of available actions."
-  ]
-}
-```
----
-## `setting.upsert`
-Create or update a Fluent Commerce setting with upsert semantics.
-Queries existing settings by `name` + `context` + `contextId` first. Creates if missing, updates if exists.
-- **Required**:
-  - `name`: setting key/name
-  - `value`: setting value (for small values)
-  - `context`: setting scope — `RETAILER`, `ACCOUNT`, `LOCATION`, `NETWORK`, `AGENT`, `CUSTOMER`
-- **Optional**:
-  - `lobValue`: large object value for JSON payloads > 4KB (mutually exclusive with `value`)
-  - `contextId`: context ID (e.g., retailer ID). Defaults to `FLUENT_RETAILER_ID` for `RETAILER` context.
-**Key gotchas:**
-- `context` is a plain String (`"RETAILER"`), NOT an object
-- `contextId` is a separate Int field
-- For large JSON values (> 4KB), use `lobValue` instead of `value`
-- Returns `created: true/false` for audit trail
-**Example** — create a webhook URL setting:
-```json
-{
-  "name": "WEBHOOK_ORDER_NOTIFICATION",
-  "value": "https://api.example.com/webhooks/orders",
-  "context": "RETAILER"
-}
-```
-Response (created):
-```json
-{
-  "ok": true,
-  "created": true,
-  "updated": false,
-  "setting": {
-    "id": "99",
-    "name": "WEBHOOK_ORDER_NOTIFICATION",
-    "value": "https://api.example.com/webhooks/orders",
-    "context": "RETAILER",
-    "contextId": 5
-  }
-}
-```
-Response (updated existing):
-```json
-{
-  "ok": true,
-  "created": false,
-  "updated": true,
-  "setting": { "id": "99", "name": "WEBHOOK_ORDER_NOTIFICATION", "value": "https://api.example.com/webhooks/orders-v2", "context": "RETAILER", "contextId": 5 },
-  "previousValue": "https://api.example.com/webhooks/orders"
-}
-```
----
-## `setting.bulkUpsert`
-Batch create or update multiple settings in one call.
-Processes up to 50 settings sequentially with individual error handling. Each setting is an independent upsert — failures on one setting don't block others.
-- **Required**:
-  - `settings`: array of setting objects (min 1, max 50), each with `name`, `value`, `context`, and optional `lobValue` and `contextId`
-**Example** — bulk create 3 settings:
-```json
-{
-  "settings": [
-    { "name": "WEBHOOK_ORDER_URL", "value": "https://api.example.com/orders", "context": "RETAILER" },
-    { "name": "WEBHOOK_FULFILMENT_URL", "value": "https://api.example.com/fulfilments", "context": "RETAILER" },
-    { "name": "FEATURE_FLAG_RETURNS", "value": "true", "context": "RETAILER" }
-  ]
-}
-```
-Response:
-```json
-{
-  "ok": true,
-  "created": 2,
-  "updated": 1,
-  "failed": 0,
-  "total": 3,
-  "results": [
-    { "name": "WEBHOOK_ORDER_URL", "status": "created" },
-    { "name": "WEBHOOK_FULFILMENT_URL", "status": "created" },
-    { "name": "FEATURE_FLAG_RETURNS", "status": "updated" }
-  ]
-}
-```
----
-## `environment.discover`
-Full environment snapshot in one call.
-Returns everything an agent needs to understand the Fluent environment: retailer details, locations, networks, catalogues, workflows, settings, modules, and user context.
-- **Optional**:
-  - `include`: array of sections to include. Default: `["retailer", "locations", "networks", "catalogues"]`. Available: `retailer`, `locations`, `networks`, `catalogues`, `workflows`, `settings`, `modules`, `users`
-**Limitations:**
-- Locations and settings return the first 100 items only (no auto-pagination)
-- Workflows section uses a transition API probe — may miss workflows with no user actions at the initial state. Use `fluent workflow list` via CLI for definitive listing.
-**Example** — discover retailer, locations, and settings:
-```json
-{
-  "include": ["retailer", "locations", "settings"]
-}
-```
-Response:
-```json
-{
-  "ok": true,
-  "retailer": { "id": "5", "ref": "HM_TEST", "tradingName": "HM Test", "status": "ACTIVE" },
-  "locations": [
-    { "id": "10", "ref": "LOC_WH_01", "type": "WAREHOUSE", "status": "ACTIVE", "name": "Main Warehouse" }
-  ],
-  "settings": [
-    { "name": "WEBHOOK_ORDER_URL", "value": "https://...", "context": "RETAILER", "contextId": 5 }
-  ]
-}
-```
----
-## `environment.validate`
-Pre-flight environment validation. Runs configurable checks before E2E tests or deployments.
-- **Optional**:
-  - `checks`: array of checks to run. Default: `["auth", "retailer", "locations"]`. Available: `auth`, `retailer`, `locations`, `inventory`, `workflows`, `settings`, `modules`
-**Available checks:**
-| Check | What it validates |
-|---|---|
-| `auth` | Token valid, permissions sufficient |
-| `retailer` | Retailer exists and is active |
-| `locations` | At least one warehouse location exists |
-| `inventory` | At least one product with stock |
-| `workflows` | Key workflows deployed (ORDER, FULFILMENT) |
-| `settings` | Critical settings exist |
-| `modules` | Expected modules deployed |
-Returns pass/fail per check with severity and actionable messages.
-**Example** — full pre-flight validation:
-```json
-{
-  "checks": ["auth", "retailer", "locations", "workflows", "settings"]
-}
-```
-Response:
-```json
-{
-  "ok": true,
-  "results": [
-    { "check": "auth", "passed": true, "severity": "critical", "message": "Authenticated as admin@example.com" },
-    { "check": "retailer", "passed": true, "severity": "critical", "message": "Retailer HM_TEST (ID 5) is ACTIVE" },
-    { "check": "locations", "passed": true, "severity": "high", "message": "Found 3 locations (2 warehouses)" },
-    { "check": "workflows", "passed": false, "severity": "high", "message": "Missing workflow: FULFILMENT_OPTIONS::HD" },
-    { "check": "settings", "passed": true, "severity": "medium", "message": "12 retailer settings found" }
-  ],
-  "summary": { "passed": 4, "failed": 1, "total": 5 }
-}
-```
----
-## `test.assert`
-Assert entity state matches expectations with optional polling.
-Deep assertion on entity fields, attributes, and edge counts/statuses with human-readable failure messages.
-- **Required**:
-  - `entityType`: entity type (ORDER, FULFILMENT, etc.)
-  - `assertions`: object with expected values
-- **Optional**:
-  - `id`: entity ID (preferred)
-  - `ref`: entity ref (fallback)
-  - `poll`: if `true`, retry until assertions pass or timeout (default `false`)
-  - `timeoutMs`: polling timeout in ms, 1000–300000 (default `60000`)
-  - `intervalMs`: polling interval in ms, 1000–30000 (default `5000`)
-**Assertion types:**
-| Assertion | Description |
-|---|---|
-| `status` | Exact match on entity status |
-| `type` | Exact match on entity type |
-| `subtype` | Exact match on entity subtype |
-| `attributes` | Key-value pairs that must be present on the entity |
-| `edges` | Min/max count and status on related entities (e.g., fulfilments) |
-**Polling mode:** Set `poll: true` to retry assertions on an interval until they pass or the timeout is reached. Useful after sending events when state changes are asynchronous.
-**Example** — assert order is BOOKED with at least 1 fulfilment (polling):
-```json
-{
-  "entityType": "ORDER",
-  "ref": "HD-001",
-  "assertions": {
-    "status": "BOOKED",
-    "edges": {
-      "fulfilments": { "minCount": 1 }
-    }
-  },
-  "poll": true,
-  "timeoutMs": 60000,
-  "intervalMs": 5000
-}
-```
-Response (pass):
-```json
-{
-  "ok": true,
-  "passed": true,
-  "entityType": "ORDER",
-  "entity": { "id": "12345", "ref": "HD-001", "status": "BOOKED" },
-  "assertions": {
-    "status": { "expected": "BOOKED", "actual": "BOOKED", "passed": true },
-    "edges.fulfilments.minCount": { "expected": 1, "actual": 2, "passed": true }
-  },
-  "polling": { "attempts": 3, "elapsed": 12500 }
-}
-```
-Response (fail after timeout):
-```json
-{
-  "ok": true,
-  "passed": false,
-  "entityType": "ORDER",
-  "entity": { "id": "12345", "ref": "HD-001", "status": "CREATED" },
-  "assertions": {
-    "status": { "expected": "BOOKED", "actual": "CREATED", "passed": false }
-  },
-  "polling": { "attempts": 12, "elapsed": 60000, "timedOut": true },
-  "failureMessage": "Assertion failed: status expected \"BOOKED\" but got \"CREATED\" (timed out after 60000ms)"
-}
-```
----
-## Retry and idempotency matrix
-| Category | Tools | Retry behavior |
-|------|----------|-------------|
-| Read operations | `event.get`, `event.list`, `event.flowInspect`, `metrics.query`, `metrics.healthCheck`, `metrics.sloReport`, `metrics.labelCatalog`, `metrics.topEvents`, `workflow.transitions`, `graphql.query` (query), `graphql.queryAll`, `batch.status`, `batch.batchStatus`, `batch.results`, `graphql.introspect`, `connection.test`, `entity.get`, `environment.discover`, `environment.validate`, `test.assert`, `plugin.list` | retry + backoff |
-| Write operations | `event.send`, `batch.create`, `batch.send`, `graphql.query` (mutation), `graphql.batchMutate`, `entity.create`, `entity.update`, `workflow.upload`, `setting.upsert`, `setting.bulkUpsert` | timeout-only (no automatic retry) |
-| Local validation / no API | `config.validate`, `health.ping`, `event.build`, `webhook.validate`, `workflow.diff`, `workflow.simulate` | not applicable |
-## Tool inventory summary (36 tools)
-| Tool | Category | Requires SDK | Retry | Description |
-|------|----------|:------------:|:-----:|-------------|
-| `config.validate` | Diagnostics | No | — | Validate auth/base URL configuration |
-| `health.ping` | Diagnostics | No | — | Quick health check with config summary |
-| `connection.test` | Diagnostics | Yes | Yes | Full auth + GraphQL end-to-end test (returns user/account context) |
-| `event.build` | Events | No | — | Build event payload (no API call) |
-| `event.send` | Events | Yes | No | Send event (async/sync, supports dryRun) |
-| `event.get` | Events | Yes | Yes | Get single event by ID |
-| `event.list` | Events | Yes | Yes | List/filter events with pagination and optional analysis mode |
-| `event.flowInspect` | Events | Yes | Yes | One-call root-entity flow forensics with compact/full modes |
-| `metrics.query` | Metrics | Yes | Yes | Query Prometheus metrics (instant/range) |
-| `metrics.healthCheck` | Metrics | Yes | Yes | One-call anomaly assessment with Prometheus + Event API fallback |
-| `metrics.sloReport` | Metrics | Yes | Yes | SLO snapshot with rates, latency, and threshold findings |
-| `metrics.labelCatalog` | Metrics | Yes | Yes | Label discovery for a metric (live sampling + known hints) |
-| `metrics.topEvents` | Metrics | Yes | Yes | Ranked event analytics using Event API aggregation |
-| `workflow.transitions` | Orchestration | Yes | Yes | Query available user actions/transitions at any entity state |
-| `plugin.list` | Orchestration | Yes | Yes | List registered rules with optional name filter |
-| `graphql.query` | GraphQL | Yes | Varies | Execute single-page query or mutation (retries for queries only) |
-| `graphql.queryAll` | GraphQL | Yes | Yes | Auto-paginated query — follows cursors across all pages |
-| `graphql.batchMutate` | GraphQL | Yes | No | Execute up to 50 aliased mutations in one request |
-| `graphql.introspect` | GraphQL | Yes | Yes | Schema introspection (types, mutations, queries) |
-| `batch.create` | Batch | Yes | No | Create ingestion job |
-| `batch.send` | Batch | Yes | No | Send records to job |
-| `batch.status` | Batch | Yes | Yes | Check job status |
-| `batch.batchStatus` | Batch | Yes | Yes | Check specific batch within a job |
-| `batch.results` | Batch | Yes | Yes | Get per-record job outcomes |
-| `webhook.validate` | Webhooks | No | — | Validate webhook payload + optional signature verification |
-| `entity.create` | Entity | Yes | No | Type-safe entity creation with field validation and gotcha knowledge (12 entity types) |
-| `entity.update` | Entity | Yes | No | Status-aware entity updates with optional transition validation |
-| `entity.get` | Entity | Yes | Yes | Unified entity lookup by ID or ref with optional edge inclusion |
-| `workflow.upload` | Workflow Mgmt | Yes | No | Deploy workflow JSON via REST API with structure validation |
-| `workflow.diff` | Workflow Mgmt | No | — | Compare two workflows — rulesets, statuses, risk assessment, mermaid output |
-| `workflow.simulate` | Workflow Mgmt | No | — | Static prediction of event outcomes from workflow JSON |
-| `setting.upsert` | Settings | Yes | No | Create or update a setting with upsert semantics |
-| `setting.bulkUpsert` | Settings | Yes | No | Batch create/update up to 50 settings with per-setting error handling |
-| `environment.discover` | Environment | Yes | Yes | Full environment snapshot — retailer, locations, networks, catalogues, settings, modules |
-| `environment.validate` | Environment | Yes | Yes | Pre-flight validation checks: auth, retailer, locations, inventory, workflows |
-| `test.assert` | Test | Yes | Yes | Assert entity state with status, attribute, and edge assertions + polling mode |
+# Tool Reference
+This document describes every MCP tool exposed by `fluent-mcp-extn`, including
+purpose, required inputs, and example requests.
+## Response envelope conventions
+### Success
+```json
+{
+  "ok": true
+}
+```
+Most tools include extra fields like `event`, `response`, `job`, or `status`.
+### Failure
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid tool arguments.",
+    "retryable": false,
+    "details": {}
+  }
+}
+```
+`error.retryable` indicates whether a caller can safely retry the same request. Non-idempotent writes intentionally avoid automatic retry behavior.
+## `config.validate`
+Validates configuration and auth readiness without calling Fluent APIs.
+- **Input**: no fields
+- **Use when**: startup checks, CI preflight, environment validation
+Example:
+```json
+{}
+```
+## `health.ping`
+Returns server health, SDK availability, and safe config summary.
+- **Input**: no fields
+- **Use when**: quick readiness checks in clients/agents
+Example:
+```json
+{}
+```
+## `event.build`
+Builds a Fluent event payload only (no API call).
+- **Required**: `name`, `entityRef`, `entityType`
+- **Optional**: `entityId`, `rootEntityId`, `rootEntityType`, `source`, `type`, `attributes`, etc.
+- **Note**: if available in your flow, provide both `entityRef` and `entityId`.
+Example:
+```json
+{
+  "name": "ORDER_CREATED",
+  "entityRef": "ORD-1001",
+  "entityId": "12345",
+  "entityType": "ORDER",
+  "attributes": {
+    "channel": "web"
+  }
+}
+```
+## `event.send`
+Builds and sends an event via SDK adapter.
+- **Required**: `name`, `entityRef`, `entityType`
+- **Optional**: all `event.build` fields plus:
+  - `mode`: `async` or `sync`
+  - `dryRun`: boolean
+- **Important**: `retailerId` must match the target entity's retailer for real sends.
+Example dry-run:
+```json
+{
+  "name": "ORDER_CREATED",
+  "entityRef": "ORD-1001",
+  "entityId": "12345",
+  "entityType": "ORDER",
+  "dryRun": true
+}
+```
+Example send:
+```json
+{
+  "name": "ORDER_CREATED",
+  "entityRef": "ORD-1001",
+  "entityId": "12345",
+  "entityType": "ORDER",
+  "mode": "async",
+  "dryRun": false
+}
+```
+## `event.get`
+Gets one event by ID via SDK-native `getEventById(eventId)`:
+- endpoint: `/api/v4.1/event/{id}`
+- **Required**: `eventId`
+Example:
+```json
+{
+  "eventId": "7815ee32-5985-485f-863a-2643e57b64a2"
+}
+```
+Typical success shape (truncated):
+```json
+{
+  "ok": true,
+  "event": {
+    "id": "7815ee32-5985-485f-863a-2643e57b64a2",
+    "name": "ORDER_CREATED",
+    "entityRef": "ORD-1001",
+    "entityType": "ORDER",
+    "retailerId": "5"
+  }
+}
+```
+## `event.list`
+Lists/filter events via SDK-native `getEvents(params)`:
+- endpoint: `/api/v4.1/event`
+- **Canonical filters**:
+  - `eventId`, `name`, `category`, `retailerId`
+  - `eventType`, `eventStatus`, `from`, `to`
+  - `start`, `count`
+  - `context.rootEntityType`, `context.rootEntityId`, `context.rootEntityRef`
+  - `context.entityType`, `context.entityId`, `context.entityRef`, `context.sourceEvents`
+- **Alias filters** (mapped internally):
+  - `id` -> `eventId`
+  - `entityRef` -> `context.entityRef`
+  - `entityType` -> `context.entityType`
+  - `type` -> `eventType`
+- **`context.sourceEvents` handling**:
+  - accepts array input in tool arguments
+  - serialized for query-string delivery to Event API
+Example:
+```json
+{
+  "eventType": "ORCHESTRATION_AUDIT",
+  "eventStatus": "FAILED",
+  "context.rootEntityType": "ORDER",
+  "context.rootEntityRef": "ORD-1001",
+  "retailerId": "5",
+  "from": "2026-02-01T00:00:00.000Z",
+  "to": "2026-02-15T23:59:59.999Z",
+  "count": 25,
+  "start": 1
+}
+```
+Typical success shape (truncated):
+```json
+{
+  "ok": true,
+  "events": {
+    "start": 1,
+    "count": 25,
+    "hasMore": true,
+    "results": [
+      { "id": "event-id-1", "name": "ORDER_CREATED" }
+    ]
+  }
+}
+```
+If `event.send` does not return an `id`, use `event.list` with `name`,
+`entityRef`, and `retailerId` to resolve the latest event ID, then call
+`event.get`.
+## `event.flowInspect`
+One-call runtime forensics for any root entity.
+- **Required**: `rootEntityRef`
+- **Optional**:
+  - `rootEntityType`: optional entity type filter (for example `ORDER`, `FULFILMENT`, `LOCATION`, `WAVE`, `PRODUCT`)
+  - `rootEntityId`: optional root entity ID (helps disambiguate reused refs)
+  - `compact`: return pre-analyzed summary instead of raw arrays (default `true`). Compact mode returns ~2-3k tokens with an `analysis` section; set to `false` for full ~24k raw data.
+  - `from`, `to`: optional time window
+  - `maxPages`: page cap per event type (`1..50`, default `10`)
+  - `includeEventDetails`: include compact orchestration event rows (default `true`, full mode only)
+  - `includeAuditDetails`: include compact audit action samples (default `false`, full mode only)
+  - `includeScheduled`: fetch SCHEDULED events separately (default `true`)
+  - `inspectStatuses`: statuses to drill via `event.get` (defaults: `["NO_MATCH", "PENDING", "FAILED"]`)
+  - `maxDrilldowns`: cap on individual event.get calls (`0..100`, default `50`)
+  - `actionSampleLimit`: max rows for action-derived sections (`1..200`, default `100`)
+- **Default-on flags:**
+  - `compact`: pre-analyzed summary response (default `true`)
+  - `includeExceptions`: rule exceptions with class, message, ruleset context (default `true`)
+  - `includeNoMatchDetails`: enhanced NO_MATCH diagnostics from ruleSet audit events with closeMatches (default `true`)
+- **Opt-in flags (default false):**
+  - `includeRuleDetails`: per-rule execution trace with class name, props, and timing (durationMs)
+  - `includeCustomLogs`: custom plugin log messages (LogCollection from CUSTOM category)
+  - `includeSnapshots`: entity state snapshots at each processing point
+  - `includeCrossEntity`: fetch child entity events (FULFILMENT_CHOICE, FULFILMENT) using rootEntityRef
+**Compact mode (`compact: true`, the default):**
+Returns a pre-analyzed summary with:
+- `analysis.statusFlow`: ordered unique statuses seen (e.g., `["CREATED", "BOOKED", "SHIPPED"]`)
+- `analysis.findings[]`: anomaly detection — NO_MATCH (CRITICAL), FAILED/webhook errors/exceptions (HIGH), PENDING/slow rulesets (MEDIUM)
+- `analysis.failedWebhookEndpoints`: URLs that returned >= 400
+- `analysis.slowestRulesets`: top 3 by duration
+- `analysis.timespan`: first/last timestamps with durationMs
+- `audit.webhookActions`: only failures (responseCode >= 400)
+- `audit.mutationActions`: top 5 by queryName (name + count only)
+- `audit.sendEventActions`: count + scheduledCount only
+- `diagnostics.inspectedEvents`: summary (id, name, status, closeMatchCount)
+**Full mode (`compact: false`):**
+Returns complete raw arrays:
+- Orchestration timeline counts (`status`, `entityType`, top names)
+- Audit category/action breakdown with ruleset durations
+- Mutation payload evidence from ACTION audit (`DynamicUpdateMutation` request blocks)
+- Webhook diagnostics (`Request Endpoint`, `Response code`, `Response Body`, headers)
+- SendEvent payloads and future-dated scheduling evidence
+- Rule exceptions (when `includeExceptions: true`)
+- NO_MATCH closeMatches with mismatch reasons (when `includeNoMatchDetails: true`)
+- Per-rule execution with props/timing (when `includeRuleDetails: true`)
+- Custom plugin logs (when `includeCustomLogs: true`)
+- Entity snapshots (when `includeSnapshots: true`)
+- Cross-entity events with full events array (when `includeCrossEntity: true`)
+- `NO_MATCH`/`PENDING`/`FAILED` drilldown with full event payload via `event.get`
+- Auto-recommendations based on findings
+Example (compact — recommended first call):
+```json
+{
+  "rootEntityRef": "E2E_MULTI_202602221343",
+  "rootEntityType": "ORDER"
+}
+```
+Example (full data with all sections):
+```json
+{
+  "rootEntityRef": "ORD-001",
+  "rootEntityType": "ORDER",
+  "compact": false,
+  "includeRuleDetails": true,
+  "includeCustomLogs": true,
+  "includeSnapshots": true,
+  "includeCrossEntity": true
+}
+```
+Example (lightweight):
+```json
+{
+  "rootEntityRef": "ORD-001",
+  "rootEntityType": "ORDER",
+  "includeEventDetails": false,
+  "includeExceptions": false,
+  "includeNoMatchDetails": false,
+  "maxDrilldowns": 0
+}
+```
+## `metrics.query`
+Queries Prometheus metrics for Fluent runtime telemetry.
+- **Required**: `query` (PromQL expression)
+- **Optional**:
+  - `type`: `instant` (default) or `range`
+  - `time`: instant query timestamp
+  - `start`, `end`, `step`: required together for range queries
+  - `timeout`: query timeout in seconds (`1..120`)
+- **Execution path**:
+  - instant -> GraphQL `metricInstant(query, time?)`
+  - range -> GraphQL `metricRange(query, start, end, step)`
+- **Note**: `metrics.query` routes PromQL through Fluent's GraphQL proxy. Raw Prometheus REST endpoints are not relied on directly by this tool.
+Label hygiene reminder:
+- `core_event_received_total` does **not** include `status`
+- `rubix_event_runtime_seconds_*` does include `status`
+- histogram bucket series add `le`
+Accurate counter delta pattern for wider windows:
+```promql
+(last_over_time(metric[window]) - metric offset <period>)
+or
+last_over_time(metric[window])
+```
+Use the fallback `or` arm when offset samples are missing.
+Instant example:
+```json
+{
+  "query": "sum(rate(rubix_event_runtime_seconds_count[5m]))",
+  "type": "instant"
+}
+```
+Range example:
+```json
+{
+  "query": "rate(rubix_event_runtime_seconds_count{status=\"FAILED\"}[5m])",
+  "type": "range",
+  "start": "2026-02-20T00:00:00Z",
+  "end": "2026-02-20T01:00:00Z",
+  "step": "1m"
+}
+```
+## `metrics.topEvents`
+Returns ranked event analytics for a time window by aggregating Event API results.
+- **Required**: `from`
+- **Optional**:
+  - `to`: end timestamp (defaults to now)
+  - `entityType`: filter to one entity type
+  - `eventType`: defaults to `ORCHESTRATION`
+  - `topN`: ranked rows to return (`1..100`, default `20`)
+  - `maxPages`: Event API pagination cap (`1..50`, default `10`)
+- **Output summary**:
+  - `totalEvents`, `failureRate`, `statusBreakdown`
+  - `topEvents[]` grouped by `name + entityType + status`
+  - `uniqueEventNames`, `uniqueEntityTypes`
+Example:
+```json
+{
+  "from": "2026-02-22T00:00:00Z",
+  "to": "2026-02-22T12:00:00Z",
+  "topN": 20,
+  "eventType": "ORCHESTRATION"
+}
+```
+## `metrics.healthCheck`
+Runs a compact, one-call anomaly assessment.
+- **Optional**:
+  - `window`: Prometheus/Event API analysis window (`1h`, `6h`, `24h`, `7d`; default `1h`)
+  - `includeTopEvents`: include ranked event list in response (default `true`)
+  - `topN`: max top event rows (`1..100`, default `10`)
+  - `thresholds`: override defaults
+    - `failureRate` (default `5`)
+    - `pendingRate` (default `10`)
+    - `dominanceRate` (default `50`)
+- **Behavior**:
+  - Prometheus-first (`metrics.query` equivalent calls under the hood)
+  - Falls back to Event API aggregation if Prometheus is unavailable
+Example:
+```json
+{
+  "window": "1h",
+  "includeTopEvents": true,
+  "topN": 10
+}
+```
+## `metrics.sloReport`
+Returns a managed-services SLO snapshot with explicit KPI fields and threshold findings.
+- **Optional**:
+  - `window`: KPI window (`30m`, `1h`, `24h`, `7d`; default `1h`)
+  - `includeTopFailingEvents`: include top failed events from Event API (default `true`)
+  - `topN`: top failed rows (`1..100`, default `10`)
+  - `maxPages`: Event API pagination cap for fallback/failed ranking (`1..50`, default `10`)
+  - `thresholds`: override defaults
+    - `failureRate` (default `5`)
+    - `noMatchRate` (default `0`)
+    - `pendingRate` (default `10`)
+    - `runtimeP95Seconds` (default `5`)
+    - `inflightP95Seconds` (default `60`)
+- **Output highlights**:
+  - total/failed/no-match/pending event counts
+  - failure/no-match/pending rates
+  - p95 runtime and inflight latency (null when Prometheus fallback path is used)
+  - findings + recommendations + source (`prometheus` or `event_api`)
+Example:
+```json
+{
+  "window": "1h",
+  "includeTopFailingEvents": true,
+  "topN": 10
+}
+```
+## `metrics.labelCatalog`
+Discovers what labels a metric supports so PromQL groupings are correct.
+- **Required**: `metric`
+- **Optional**:
+  - `window`: live series sampling window (`30m`, `1h`, `24h`, `7d`; default `24h`)
+  - `includeKnownLabels`: include Fluent-known label hints (default `true`)
+  - `maxValuesPerLabel`: max sample values returned per label (`1..50`, default `10`)
+- **Behavior**:
+  - runs `last_over_time(<metric>[window])` as an instant query
+  - extracts label keys from returned vector series
+  - reports presence/cardinality/sample values per label
+  - merges known Fluent label hints when available
+Example:
+```json
+{
+  "metric": "core_event_received_total",
+  "window": "1h",
+  "maxValuesPerLabel": 10
+}
+```
+## `workflow.transitions`
+Query available user actions (transitions) for entities at a given workflow state.
+Calls `POST /api/v4.1/transition` to discover what events can be fired, what attributes they require, and how they appear in the UI.
+- **Required**: `triggers` (array), each trigger requires `retailerId`
+- **Optional per trigger**: `type`, `subtype`, `status`, `module`, `flexType`, `flexVersion`, `name`
+- **Retailer behavior**: `retailerId` is required per trigger. Falls back to `FLUENT_RETAILER_ID` when omitted.
+### Use cases
+- Discover available actions at any workflow status without reading workflow JSON
+- Build dynamic E2E test sequences that adapt to workflow changes
+- Validate that expected user actions are available after deployment
+- Get required event attributes for each action (avoids missing-attribute errors)
+### Integration with event.send
+The `eventName` from each `userAction` maps directly to `event.send`'s `name` parameter. The `attributes[]` tell you what to include in `event.send`'s `attributes` parameter.
+### Example: ORDER at CREATED status
+```json
+{
+  "triggers": [
+    {
+      "type": "ORDER",
+      "subtype": "HD",
+      "status": "CREATED",
+      "retailerId": "5",
+      "flexType": "ORDER::HD"
+    }
+  ]
+}
+```
+### Example: MANIFEST with module filter
+```json
+{
+  "triggers": [
+    {
+      "type": "MANIFEST",
+      "subtype": "DEFAULT",
+      "status": "PENDING",
+      "module": "servicepoint",
+      "flexType": "CARRIER::DEFAULT",
+      "retailerId": "2"
+    }
+  ]
+}
+```
+Typical success shape (truncated):
+```json
+{
+  "ok": true,
+  "response": {
+    "response": [
+      {
+        "trigger": {
+          "type": "MANIFEST",
+          "subtype": "DEFAULT",
+          "status": "PENDING",
+          "module": "servicepoint",
+          "flexType": "CARRIER::DEFAULT",
+          "retailerId": "2"
+        },
+        "userActions": [
+          {
+            "eventName": "UPDATE",
+            "context": [
+              { "label": "SUBMIT", "type": "PRIMARY", "modules": ["servicepoint"], "confirm": false }
+            ],
+            "attributes": []
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+### Dynamic test sequence pattern
+```
+1. Create entity via graphql.query (mutation)
+2. workflow.transitions → get available actions at current status
+3. For each action:
+   a. event.send with eventName and required attributes from response
+   b. Poll entity status until transition completes
+   c. workflow.transitions → get next available actions
+4. Repeat until no more userActions (terminal state)
+```
+## `plugin.list`
+List all registered orchestration rules (standard + custom) with metadata.
+Calls `GET /orchestration/rest/v1/plugin` and returns a map keyed by fully-qualified rule name (e.g. `ACCOUNT.context.RuleName`).
+- **Optional**: `name` (string) — case-insensitive substring filter on rule keys
+- **Requires**: SDK client with `request` method
+### Each entry contains
+- `ruleInfo`: name, description, accepted entity types, produced events
+- `eventAttributes`: attributes the rule reads from events
+- `parameters`: configurable rule parameters (with types and descriptions)
+### Use cases
+- Understand what rules do when analyzing workflows
+- Discover all registered rules (standard + custom) for a given account
+- Find rules by name pattern (e.g. all "SendEvent" variants)
+- Cross-reference deployed rules with local source code for module validation
+### Example: list all rules
+```json
+{}
+```
+### Example: filter by name
+```json
+{
+  "name": "SendEvent"
+}
+```
+Typical success shape (truncated):
+```json
+{
+  "ok": true,
+  "response": {
+    "FLUENTRETAIL.base.SendEvent": {
+      "ruleInfo": {
+        "name": "SendEvent",
+        "description": "Sends an event to a specified entity",
+        "accepts": ["ORDER", "FULFILMENT", "ARTICLE"],
+        "produces": ["SendEvent"]
+      },
+      "eventAttributes": [
+        { "name": "eventName", "type": "STRING", "description": "Name of the event to send" }
+      ],
+      "parameters": [
+        { "name": "eventName", "type": "STRING", "description": "Event name to dispatch" }
+      ]
+    }
+  }
+}
+```
+## `graphql.query`
+Executes a Fluent Commerce GraphQL query or mutation through the SDK.
+- **Required**: `query`
+- **Optional**: `variables`
+- **Retry behavior**:
+  - query operations use configured retry/backoff
+  - mutation operations disable retries automatically to avoid duplicate writes
+### Basic Query
+```json
+{
+  "query": "query { orders(first: 5) { edges { cursor node { id ref status } } pageInfo { hasNextPage } } }"
+}
+```
+### Pagination
+Fluent uses Relay-style connections. Cursors live on each **edge**, not on `pageInfo`. There is no `endCursor` or `startCursor`.
+```json
+{
+  "query": "query($cursor: String) { orders(first: 50, after: $cursor) { edges { cursor node { id ref status } } pageInfo { hasNextPage } } }",
+  "variables": { "cursor": "Y3Vyc29yOi0tLTM2X18xNzcxMTc2MzMyMTc0" }
+}
+```
+To paginate: take the `cursor` from the **last edge** in the response, pass it as the `after` variable. Repeat while `hasNextPage` is `true`.
+Pagination args: `first`/`after` (forward), `last`/`before` (backward).
+### Mutation
+```json
+{
+  "query": "mutation($input: UpdateOrderInput!) { updateOrder(input: $input) { id ref status } }",
+  "variables": { "input": { "id": "36", "status": "RECEIVED" } }
+}
+```
+### Synchronous Fulfilment Options (Live Checkout)
+`graphql.query` supports synchronous fulfilment options orchestration calls,
+commonly used by checkout journeys to get plans in the same response.
+```json
+{
+  "query": "mutation CreateFulfilmentOption($retailerId: Int!, $type: String!, $orderType: String!, $ref: String!, $products: [CreateFulfilmentOptionProductInput!], $longitude: Float!, $latitude: Float!, $radius: Json!) { createFulfilmentOption(input: { retailerId: $retailerId, type: $type, orderType: $orderType, ref: $ref, products: $products, address: { city: \"Kellyville Ridge\", state: \"New South Wales\", country: \"Australia\", postcode: \"2155\", addressLine1: \"Kellyville Ridge NSW, Australia\", latitude: $latitude, longitude: $longitude }, attributes: { name: \"radius\", type: \"DOUBLE\", value: $radius } }, executionMode: AWAIT_ORCHESTRATION) { id createdOn plans { edges { node { ref status eta splitCount fulfilments { locationRef eta items { productRef availableQuantity requestedQuantity } } } } } } }",
+  "variables": {
+    "retailerId": 5,
+    "type": "CC",
+    "orderType": "CC",
+    "ref": "CHECKOUT-FO-12345",
+    "products": [
+      { "productRef": "MP09-34-Blue", "requestedQuantity": 1, "catalogueRef": "" }
+    ],
+    "longitude": 150.9193671,
+    "latitude": -33.7068442,
+    "radius": 50
+  }
+}
+```
+Notes:
+- `executionMode: AWAIT_ORCHESTRATION` makes the call synchronous.
+- The environment must contain a matching workflow for `type` (for example `FULFILMENT_OPTIONS::CC`).
+- If no matching workflow exists, Fluent returns a backend workflow-not-found error.
+### Connection Shape
+All list queries return connections:
+```graphql
+{
+  edges {
+    cursor
+    node { ...fields }
+  }
+  pageInfo { hasNextPage }
+}
+```
+Common query roots: `orders`, `fulfilments`, `fulfilmentChoices`, `locations`, `inventoryPositions`, `products`, `categories`, `settings`, `waves`, `articles`.
+## `batch.create`
+Creates a Fluent ingestion job.
+- **Required**: `name`
+- **Optional**: `retailerId`, `entityType`, `action`
+- **Note**: `retailerId` falls back to `FLUENT_RETAILER_ID` if omitted
+Example:
+```json
+{
+  "name": "inventory-load-2026-02-06",
+  "entityType": "INVENTORY_POSITION",
+  "action": "UPSERT"
+}
+```
+## `batch.send`
+Sends payload records to an existing batch job.
+- **Required**:
+  - `jobId`
+  - `payload.action`
+  - `payload.entityType`
+  - `payload.entities` (non-empty array)
+Example:
+```json
+{
+  "jobId": "JOB-123",
+  "payload": {
+    "action": "UPSERT",
+    "entityType": "INVENTORY_POSITION",
+    "entities": [
+      {
+        "locationRef": "LOC-1",
+        "skuRef": "SKU-1",
+        "qty": 10,
+        "type": "LAST_ON_HAND",
+        "status": "ACTIVE"
+      }
+    ]
+  }
+}
+```
+## `batch.status`
+Reads status for a previously created batch job.
+- **Required**: `jobId`
+Example:
+```json
+{
+  "jobId": "JOB-123"
+}
+```
+## `batch.batchStatus`
+Gets the status of a specific batch within a job. Useful for troubleshooting partial failures in multi-batch jobs.
+- **Required**: `jobId`, `batchId`
+Example:
+```json
+{
+  "jobId": "JOB-123",
+  "batchId": "BATCH-456"
+}
+```
+## `batch.results`
+Gets per-record outcomes for a completed job. Call after `batch.status` reports a terminal state.
+- **Required**: `jobId`
+Example:
+```json
+{
+  "jobId": "JOB-123"
+}
+```
+---
+## `graphql.queryAll`
+Executes a GraphQL query with SDK auto-pagination. Automatically follows cursors, merges all edges, and deduplicates by node ID. Use instead of `graphql.query` when you need ALL records from a connection.
+- **Required**: `query`
+- **Optional**:
+  - `variables`: query variables (include cursor variable, usually `null` for first page)
+  - `maxPages`: max pages to fetch (default: 100, max: 500)
+  - `maxRecords`: max total records to accumulate (default: 10000, max: 50000)
+  - `timeoutMs`: hard timeout for entire pagination run (default: 300000ms = 5 min)
+  - `direction`: `forward` (first/after) or `backward` (last/before)
+  - `errorHandling`: `throw` (fail on errors) or `partial` (return partial data + errors)
+- **Timeout behavior**:
+  - uses `timeoutMs` for the whole pagination run
+  - independent from `FLUENT_REQUEST_TIMEOUT_MS` single-call timeout
+### How it works
+1. SDK detects pagination variables (`first`/`after` or `last`/`before`) in your query
+2. Executes the first page
+3. Extracts cursor from the last edge, follows `hasNextPage`
+4. Merges edges across pages, deduplicates by node ID
+5. Stops when: no more pages, maxPages reached, maxRecords reached, or timeout
+### Response
+Includes `extensions.autoPagination`:
+```json
+{
+  "totalPages": 5,
+  "totalRecords": 487,
+  "truncated": false,
+  "direction": "forward"
+}
+```
+If truncated: `truncationReason` will be `"maxPages"`, `"maxRecords"`, or `"timeout"`.
+### Example: Fetch all active orders
+```json
+{
+  "query": "query($cursor: String) { orders(first: 100, after: $cursor, status: \"ACTIVE\") { edges { cursor node { id ref status createdOn } } pageInfo { hasNextPage } } }",
+  "variables": { "cursor": null },
+  "maxRecords": 5000
+}
+```
+### Example: Fetch all locations (backward)
+```json
+{
+  "query": "query($cursor: String) { locations(last: 50, before: $cursor) { edges { cursor node { id ref name type } } pageInfo { hasPreviousPage } } }",
+  "variables": { "cursor": null },
+  "direction": "backward"
+}
+```
+## `graphql.batchMutate`
+Executes multiple GraphQL mutations in a single request using aliased mutations. Sends up to 50 mutations at once, each with its own input.
+- **Required**: `mutation`, `inputs`
+- **Optional**: `returnFields`, `operationName`
+- **Retry behavior**: disabled (non-idempotent write operation)
+### How it works
+1. Builds an aliased mutation query:
+   ```graphql
+   mutation BatchUpdateOrders($input1: UpdateOrderInput!, $input2: UpdateOrderInput!) {
+     updateOrder1: updateOrder(input: $input1) { id ref status }
+     updateOrder2: updateOrder(input: $input2) { id ref status }
+   }
+   ```
+2. Sends as a single GraphQL request
+3. Parses per-mutation results (success/failure for each input)
+### Response
+```json
+{
+  "ok": true,
+  "summary": "All 3 mutations succeeded",
+  "executed": 3,
+  "failed": 0,
+  "allSucceeded": true,
+  "allFailed": false,
+  "results": [
+    { "alias": "updateOrder1", "index": 0, "success": true, "data": { "id": "1", "ref": "ORD-001", "status": "SHIPPED" } },
+    { "alias": "updateOrder2", "index": 1, "success": true, "data": { "id": "2", "ref": "ORD-002", "status": "SHIPPED" } }
+  ]
+}
+```
+On partial failure, `errors` array includes per-mutation error details with `alias`, `index`, `message`, and `inputRef`.
+### Example: Bulk update order statuses
+```json
+{
+  "mutation": "updateOrder",
+  "inputs": [
+    { "id": "36", "status": "SHIPPED" },
+    { "id": "37", "status": "SHIPPED" },
+    { "id": "38", "status": "SHIPPED" }
+  ],
+  "returnFields": ["id", "ref", "status"]
+}
+```
+### Example: Batch create inventory positions
+```json
+{
+  "mutation": "updateInventoryPosition",
+  "inputs": [
+    { "id": "100", "status": "ACTIVE" },
+    { "id": "101", "status": "ACTIVE" }
+  ],
+  "returnFields": ["id", "ref", "status", "onHand"]
+}
+```
+## `graphql.introspect`
+Inspects the Fluent Commerce GraphQL schema via introspection. Fetches the full schema and caches it for 1 hour. Use to discover mutations, input types, and field requirements at runtime.
+- **Optional** (specify one mode):
+  - `type`: name of an INPUT_OBJECT type to inspect (e.g., `UpdateOrderInput`)
+  - `mutation`: name of a mutation to inspect (e.g., `updateOrder`)
+  - `listMutations`: `true` to list all available mutation names
+  - `listQueries`: `true` to list all available query root field names
+### Example: List all mutations
+```json
+{
+  "listMutations": true
+}
+```
+Response:
+```json
+{
+  "ok": true,
+  "mutations": ["createOrder", "updateOrder", "createFulfilment", "..."],
+  "count": 142
+}
+```
+### Example: Inspect a mutation
+```json
+{
+  "mutation": "updateOrder"
+}
+```
+Response:
+```json
+{
+  "ok": true,
+  "mutation": {
+    "name": "updateOrder",
+    "description": "Updates an existing order",
+    "args": [
+      {
+        "name": "input",
+        "type": "UpdateOrderInput!",
+        "required": true
+      }
+    ],
+    "returnType": "Order"
+  }
+}
+```
+### Example: Inspect an input type
+```json
+{
+  "type": "UpdateOrderInput"
+}
+```
+Response:
+```json
+{
+  "ok": true,
+  "inputType": {
+    "name": "UpdateOrderInput",
+    "fields": [
+      { "name": "id", "type": "ID!", "required": true },
+      { "name": "ref", "type": "String", "required": false },
+      { "name": "status", "type": "String", "required": false },
+      { "name": "attributes", "type": "[AttributeInput]", "required": false, "isArray": true }
+    ]
+  }
+}
+```
+### Chaining example
+1. `{ "listMutations": true }` → find `updateOrder`
+2. `{ "mutation": "updateOrder" }` → see it takes `UpdateOrderInput!`
+3. `{ "type": "UpdateOrderInput" }` → see all updatable fields
+4. Use `graphql.query` or `graphql.batchMutate` with the discovered schema
+## `connection.test`
+Comprehensive Fluent Commerce connectivity test. Authenticates, executes a `me` query, and returns the authenticated user's details.
+- **Input**: no fields
+### Response (success)
+```json
+{
+  "ok": true,
+  "duration": 342,
+  "details": {
+    "userId": "12",
+    "username": "admin@hmtest.com",
+    "userType": "RETAILER",
+    "userStatus": "ACTIVE",
+    "retailerId": "5",
+    "retailerRef": "HMTEST",
+    "retailerName": "HM Test",
+    "locationId": "10",
+    "locationRef": "W252",
+    "locationName": "Warehouse 252"
+  }
+}
+```
+### Response (failure)
+```json
+{
+  "ok": false,
+  "duration": 1500,
+  "error": "Authentication failed after 3 retries: 401 Unauthorized"
+}
+```
+More thorough than `health.ping` — actually verifies the GraphQL endpoint works end-to-end. Use when first connecting, debugging auth issues, or verifying retailer/location context.
+## `webhook.validate`
+Validates a Fluent Commerce webhook payload and optionally verifies its signature.
+- **Required**: `payload`
+- **Optional**:
+  - `rawBody`: exact original HTTP request body string for signature checks
+  - `signature`: the `X-Fluent-Signature` header value (base64-encoded)
+  - `publicKey`: the Fluent public key (PEM format) for signature verification
+  - `algorithm`: `SHA512withRSA` (default) or `MD5withRSA`
+### Mode 1: Basic validation
+Checks that required fields (`name`, `id`, `retailerId`) are present in the payload.
+```json
+{
+  "payload": {
+    "name": "OrderCreated",
+    "id": "event-123",
+    "retailerId": "5",
+    "entityType": "ORDER",
+    "entityRef": "ORD-001"
+  }
+}
+```
+Response:
+```json
+{
+  "ok": true,
+  "basicValidation": { "valid": true, "missingFields": [] },
+  "note": "Basic field validation passed. Provide signature + publicKey for signature verification."
+}
+```
+### Mode 2: Signature validation
+Verifies the webhook body against the `X-Fluent-Signature` header using the provided public key.
+Use `rawBody` whenever possible because signature verification is byte-sensitive.
+```json
+{
+  "payload": {
+    "name": "OrderCreated",
+    "id": "event-123",
+    "retailerId": "5"
+  },
+  "rawBody": "{\"name\":\"OrderCreated\",\"id\":\"event-123\",\"retailerId\":\"5\"}",
+  "signature": "base64-encoded-signature-from-header",
+  "publicKey": "-----BEGIN PUBLIC KEY-----\nMIIBI...\n-----END PUBLIC KEY-----",
+  "algorithm": "SHA512withRSA"
+}
+```
+Response:
+```json
+{
+  "ok": true,
+  "basicValidation": { "valid": true, "missingFields": [] },
+  "signatureValidation": {
+    "valid": true,
+    "algorithm": "SHA512withRSA",
+    "payloadSource": "rawBody"
+  }
+}
+```
+---
+## `entity.create`
+Type-safe entity creation with built-in validation and gotcha knowledge.
+**Supported entity types:** ORDER, FULFILMENT, LOCATION, NETWORK, CUSTOMER, PRODUCT, INVENTORY_POSITION, VIRTUAL_CATALOGUE, VIRTUAL_POSITION, CATEGORY, CARRIER, SETTING
+- **Required**:
+  - `entityType`: entity type string (see supported list above)
+  - `data`: creation input fields matching the GraphQL create input type
+- **Optional**:
+  - `returnFields`: array of field names to return (defaults to entity type defaults)
+  - `dryRun`: if `true`, builds and validates the mutation without executing (default `false`)
+**Key behaviors:**
+- Validates required fields BEFORE sending (e.g., Location requires `openingSchedule`)
+- Encodes compound key rules (ProductKey needs `ref` + `catalogue.ref`)
+- Auto-resolves `retailerId` from config for retailer-scoped entities
+- Returns the executed mutation string for audit trail
+**Known gotchas (encoded in validation):**
+- No create inputs have a `status` field — status is auto-set to `CREATED`
+- `Customer` has NO `ref` field; `username` is the identifier
+- `Network` uses `name` (not `ref`) in create; `retailers` is a plural array
+- `Location` requires `openingSchedule` even for 24/7 (use `allHours: true`)
+- `Product` `gtin` has a 20-character max
+- `Setting` `context` is a plain String, `contextId` is a separate Int
+**Example** — create a location (dry run):
+```json
+{
+  "entityType": "LOCATION",
+  "data": {
+    "ref": "LOC_WH_01",
+    "type": "WAREHOUSE",
+    "name": "Main Warehouse",
+    "openingSchedule": { "allHours": true }
+  },
+  "dryRun": true
+}
+```
+Response (dry run):
+```json
+{
+  "ok": true,
+  "dryRun": true,
+  "entityType": "LOCATION",
+  "mutation": "mutation CreateLocation($input: CreateLocationInput!) { createLocation(input: $input) { id ref status type name } }",
+  "inputType": "CreateLocationInput",
+  "variables": { "input": { "ref": "LOC_WH_01", "type": "WAREHOUSE", "name": "Main Warehouse", "openingSchedule": { "allHours": true } } },
+  "requiredFields": ["ref", "type", "name", "openingSchedule"],
+  "gotchas": ["Location requires openingSchedule — use { allHours: true } for 24/7"],
+  "note": "No API call made. Set dryRun=false to execute."
+}
+```
+**Example** — create a location (real):
+```json
+{
+  "entityType": "LOCATION",
+  "data": {
+    "ref": "LOC_WH_01",
+    "type": "WAREHOUSE",
+    "name": "Main Warehouse",
+    "openingSchedule": { "allHours": true }
+  }
+}
+```
+Response:
+```json
+{
+  "ok": true,
+  "entityType": "LOCATION",
+  "entity": { "id": "42", "ref": "LOC_WH_01", "status": "CREATED", "type": "WAREHOUSE", "name": "Main Warehouse" },
+  "mutation": "mutation CreateLocation($input: CreateLocationInput!) { ... }"
+}
+```
+---
+## `entity.update`
+Status-aware entity updates with optional transition validation.
+- **Required**:
+  - `entityType`: entity type string
+  - `id`: entity ID (required for updates)
+  - `fields`: object of fields to update (matches GraphQL update input type)
+- **Optional**:
+  - `returnFields`: array of field names to return
+  - `validateTransition`: if `true` and `status` is being changed, queries `workflow.transitions` to verify the transition is allowed before executing (default `false`)
+**Key behaviors:**
+- Auto-detects the correct GraphQL mutation name from entity type
+- When `validateTransition` is `true`: fetches current entity state, queries transition API, warns if no workflow transitions exist from the current status
+- Returns the previous status for audit trail when transition validation is used
+- Uses no-retry semantics (write operation)
+**Example** — update order status with transition validation:
+```json
+{
+  "entityType": "ORDER",
+  "id": "12345",
+  "fields": { "status": "COMPLETE" },
+  "validateTransition": true
+}
+```
+Response:
+```json
+{
+  "ok": true,
+  "entityType": "ORDER",
+  "entity": { "id": "12345", "ref": "HD-001", "status": "COMPLETE" },
+  "mutation": "mutation UpdateOrder($input: UpdateOrderInput!) { ... }"
+}
+```
+If no workflow transition exists:
+```json
+{
+  "ok": true,
+  "entityType": "ORDER",
+  "entity": { "id": "12345", "ref": "HD-001", "status": "COMPLETE" },
+  "mutation": "...",
+  "transitionWarning": "No workflow transitions available from status \"BOOKED\" for ORDER. The status update may succeed as a direct mutation but will not trigger workflow orchestration."
+}
+```
+---
+## `entity.get`
+Unified entity lookup by ID or ref with optional edge inclusion.
+- **Required**:
+  - `entityType`: entity type string
+  - At least one of `id` or `ref`
+- **Optional**:
+  - `id`: entity ID (preferred lookup method)
+  - `ref`: entity ref (fallback — not available for CUSTOMER)
+  - `fields`: array of field names to return (defaults to entity type defaults: id, ref, status, type, createdOn, etc.)
+  - `includeEdges`: array of related entity edges to fetch (e.g., `["fulfilments", "items", "attributes"]`)
+**Key behaviors:**
+- Prefers ID-based lookup (single entity query) over ref-based lookup (connection query)
+- Ref-based lookup uses the connection query pattern (edges/node)
+- Returns `{ found: false }` when entity is not found (not an error)
+- CUSTOMER entity type does not support ref-based lookup
+**Example** — get order by ref with fulfilments:
+```json
+{
+  "entityType": "ORDER",
+  "ref": "HD-001",
+  "includeEdges": ["fulfilments"]
+}
+```
+Response:
+```json
+{
+  "ok": true,
+  "found": true,
+  "entityType": "ORDER",
+  "entity": {
+    "id": "12345",
+    "ref": "HD-001",
+    "status": "BOOKED",
+    "type": "HD",
+    "fulfilments": {
+      "edges": [
+        { "node": { "id": "67890", "ref": "FUL-001", "status": "CREATED" } }
+      ]
+    }
+  }
+}
+```
+---
+## `workflow.upload`
+Deploy a workflow JSON definition to the Fluent environment.
+Uploads via REST API `POST /api/v4.1/workflow/{retailerId}` — the same endpoint the Fluent CLI uses.
+- **Required**:
+  - `workflow`: workflow JSON definition (as object or JSON string)
+- **Optional**:
+  - `retailerId`: target retailer ID (falls back to `FLUENT_RETAILER_ID`)
+  - `validate`: validate structure before uploading (default `true`)
+  - `dryRun`: validate only, do not deploy (default `false`)
+**Validation checks:**
+- `name` field present
+- At least one status defined in `statuses` array
+- All rulesets have `name`, `triggers`, and `rules` (warns if empty)
+**Important:** For production deployments, prefer `fluent module install` via CLI which bundles workflows with settings, rules, and data in a versioned module. Use this tool for interactive editing, hotfixes, or when CLI is unavailable.
+**Example** — dry-run validation:
+```json
+{
+  "workflow": {
+    "name": "ORDER::HD",
+    "type": "ORDER",
+    "subtype": "HD",
+    "statuses": [{ "name": "CREATED" }, { "name": "BOOKED" }],
+    "rulesets": [
+      {
+        "name": "BookOrder",
+        "triggers": [{ "status": "CREATED" }],
+        "rules": [{ "name": "com.fluentretail.rubix.rule.order.SendEventOnVerifyingState", "props": { "status": "BOOKED" } }]
+      }
+    ]
+  },
+  "dryRun": true
+}
+```
+Response (dry run — valid):
+```json
+{
+  "ok": true,
+  "dryRun": true,
+  "valid": true,
+  "workflowName": "ORDER::HD",
+  "retailerId": "5",
+  "note": "Validation passed. Set dryRun=false to deploy."
+}
+```
+---
+## `workflow.diff`
+Compare two workflow JSON definitions and identify changes.
+Pure local computation — no API calls.
+- **Required**:
+  - `base`: base workflow JSON (before changes)
+  - `target`: target workflow JSON (after changes)
+- **Optional**:
+  - `format`: output format — `summary` (default), `detailed`, or `mermaid`
+**Comparison scope:**
+- Rulesets: added, removed, modified (trigger changes, rule additions/removals, prop changes)
+- Statuses: added, removed
+- Risk assessment: removing rulesets or statuses = HIGH, modifying props = MEDIUM, adding = LOW
+**Formats:**
+| Format | Returns |
+|---|---|
+| `summary` | Change counts, status changes, risk level |
+| `detailed` | Full `WorkflowDiffResult` object with per-ruleset breakdown |
+| `mermaid` | `stateDiagram-v2` with color-coded added/removed/modified states and transitions |
+**Example** — summary diff:
+```json
+{
+  "base": { "name": "ORDER::HD", "statuses": [...], "rulesets": [...] },
+  "target": { "name": "ORDER::HD", "statuses": [...], "rulesets": [...] },
+  "format": "summary"
+}
+```
+Response:
+```json
+{
+  "ok": true,
+  "summary": "3 ruleset change(s): 1 added, 0 removed, 2 modified. 1 status change(s): 1 added, 0 removed. Risk level: MEDIUM.",
+  "riskLevel": "medium",
+  "rulesetChanges": { "added": 1, "removed": 0, "modified": 2 },
+  "statusChanges": { "added": ["AWAITING_PICKUP"], "removed": [] }
+}
+```
+---
+## `workflow.simulate`
+Static prediction of workflow event outcomes from workflow JSON.
+Pure local computation — no API calls. Parses workflow JSON to find matching rulesets and predict state transitions, follow-on events, and webhook side effects.
+- **Required**:
+  - `workflow`: workflow JSON definition (as object or JSON string)
+  - `currentStatus`: entity status to simulate from (e.g., `CREATED`, `BOOKED`)
+- **Optional**:
+  - `eventName`: event name to match against ruleset names (if omitted, returns all rulesets triggered by `currentStatus`)
+  - `entityType`: entity type filter for trigger matching
+  - `entitySubtype`: entity subtype filter for trigger matching
+**What it does:**
+- Finds rulesets whose triggers match `currentStatus` (and optionally `eventName`)
+- Extracts `SetState`/`ChangeState` rules → predicted next status
+- Extracts `SendEvent` rules → predicted follow-on events
+- Extracts `SendWebhook` rules → predicted webhook side effects
+- Identifies custom Java rules that cannot be statically predicted
+**Important limitations (always disclosed in response):**
+- **STATIC ONLY** — cannot evaluate runtime conditions, entity attributes, or settings values
+- **CUSTOM RULES OPAQUE** — Java plugin rules may conditionally execute; behavior unknown without live state
+- **NO CROSS-ENTITY** — does not follow SendEvent chains into child entity workflows
+- Use `workflow.transitions` for **authoritative live validation** of available actions
+**Example** — simulate from CREATED status:
+```json
+{
+  "workflow": { "name": "ORDER::HD", "rulesets": [...] },
+  "currentStatus": "CREATED",
+  "eventName": "BookOrder"
+}
+```
+Response:
+```json
+{
+  "ok": true,
+  "workflowName": "ORDER::HD",
+  "currentStatus": "CREATED",
+  "eventName": "BookOrder",
+  "matchedRulesets": 1,
+  "rulesets": [
+    {
+      "name": "BookOrder",
+      "matchType": "statusAndEvent",
+      "predictedStatus": "BOOKED",
+      "predictedEvents": ["SendToFulfilment"],
+      "predictedWebhooks": [],
+      "ruleCount": 3
+    }
+  ],
+  "prediction": {
+    "likelyNextStatus": "BOOKED",
+    "followOnEvents": ["SendToFulfilment"],
+    "webhookSideEffects": [],
+    "confidence": "low",
+    "note": "Custom rules present — prediction may be incomplete or wrong."
+  },
+  "limitations": [
+    "STATIC PREDICTION ONLY — does not account for runtime conditions, entity attributes, or settings values.",
+    "1 custom rule(s) found whose behavior cannot be predicted statically: ForwardIfOrderCoordinatesPresent.",
+    "Use workflow.transitions for AUTHORITATIVE live validation of available actions."
+  ]
+}
+```
+---
+## `setting.upsert`
+Create or update a Fluent Commerce setting with upsert semantics.
+Queries existing settings by `name` + `context` + `contextId` first. Creates if missing, updates if exists.
+- **Required**:
+  - `name`: setting key/name
+  - `value`: setting value (for small values)
+  - `context`: setting scope — `RETAILER`, `ACCOUNT`, `LOCATION`, `NETWORK`, `AGENT`, `CUSTOMER`
+- **Optional**:
+  - `lobValue`: large object value for JSON payloads > 4KB (mutually exclusive with `value`)
+  - `contextId`: context ID (e.g., retailer ID). Defaults to `FLUENT_RETAILER_ID` for `RETAILER` context.
+**Key gotchas:**
+- `context` is a plain String (`"RETAILER"`), NOT an object
+- `contextId` is a separate Int field
+- For large JSON values (> 4KB), use `lobValue` instead of `value`
+- Returns `created: true/false` for audit trail
+**Example** — create a webhook URL setting:
+```json
+{
+  "name": "WEBHOOK_ORDER_NOTIFICATION",
+  "value": "https://api.example.com/webhooks/orders",
+  "context": "RETAILER"
+}
+```
+Response (created):
+```json
+{
+  "ok": true,
+  "created": true,
+  "updated": false,
+  "setting": {
+    "id": "99",
+    "name": "WEBHOOK_ORDER_NOTIFICATION",
+    "value": "https://api.example.com/webhooks/orders",
+    "context": "RETAILER",
+    "contextId": 5
+  }
+}
+```
+Response (updated existing):
+```json
+{
+  "ok": true,
+  "created": false,
+  "updated": true,
+  "setting": { "id": "99", "name": "WEBHOOK_ORDER_NOTIFICATION", "value": "https://api.example.com/webhooks/orders-v2", "context": "RETAILER", "contextId": 5 },
+  "previousValue": "https://api.example.com/webhooks/orders"
+}
+```
+---
+## `setting.bulkUpsert`
+Batch create or update multiple settings in one call.
+Processes up to 50 settings sequentially with individual error handling. Each setting is an independent upsert — failures on one setting don't block others.
+- **Required**:
+  - `settings`: array of setting objects (min 1, max 50), each with `name`, `value`, `context`, and optional `lobValue` and `contextId`
+**Example** — bulk create 3 settings:
+```json
+{
+  "settings": [
+    { "name": "WEBHOOK_ORDER_URL", "value": "https://api.example.com/orders", "context": "RETAILER" },
+    { "name": "WEBHOOK_FULFILMENT_URL", "value": "https://api.example.com/fulfilments", "context": "RETAILER" },
+    { "name": "FEATURE_FLAG_RETURNS", "value": "true", "context": "RETAILER" }
+  ]
+}
+```
+Response:
+```json
+{
+  "ok": true,
+  "created": 2,
+  "updated": 1,
+  "failed": 0,
+  "total": 3,
+  "results": [
+    { "name": "WEBHOOK_ORDER_URL", "status": "created" },
+    { "name": "WEBHOOK_FULFILMENT_URL", "status": "created" },
+    { "name": "FEATURE_FLAG_RETURNS", "status": "updated" }
+  ]
+}
+```
+---
+## `environment.discover`
+Full environment snapshot in one call.
+Returns everything an agent needs to understand the Fluent environment: retailer details, locations, networks, catalogues, workflows, settings, modules, and user context.
+- **Optional**:
+  - `include`: array of sections to include. Default: `["retailer", "locations", "networks", "catalogues"]`. Available: `retailer`, `locations`, `networks`, `catalogues`, `workflows`, `settings`, `modules`, `users`
+**Limitations:**
+- Locations and settings return the first 100 items only (no auto-pagination)
+- Workflows section uses a transition API probe — may miss workflows with no user actions at the initial state. Use `fluent workflow list` via CLI for definitive listing.
+**Example** — discover retailer, locations, and settings:
+```json
+{
+  "include": ["retailer", "locations", "settings"]
+}
+```
+Response:
+```json
+{
+  "ok": true,
+  "retailer": { "id": "5", "ref": "HM_TEST", "tradingName": "HM Test", "status": "ACTIVE" },
+  "locations": [
+    { "id": "10", "ref": "LOC_WH_01", "type": "WAREHOUSE", "status": "ACTIVE", "name": "Main Warehouse" }
+  ],
+  "settings": [
+    { "name": "WEBHOOK_ORDER_URL", "value": "https://...", "context": "RETAILER", "contextId": 5 }
+  ]
+}
+```
+---
+## `environment.validate`
+Pre-flight environment validation. Runs configurable checks before E2E tests or deployments.
+- **Optional**:
+  - `checks`: array of checks to run. Default: `["auth", "retailer", "locations"]`. Available: `auth`, `retailer`, `locations`, `inventory`, `workflows`, `settings`, `modules`
+**Available checks:**
+| Check | What it validates |
+|---|---|
+| `auth` | Token valid, permissions sufficient |
+| `retailer` | Retailer exists and is active |
+| `locations` | At least one warehouse location exists |
+| `inventory` | At least one product with stock |
+| `workflows` | Key workflows deployed (ORDER, FULFILMENT) |
+| `settings` | Critical settings exist |
+| `modules` | Expected modules deployed |
+Returns pass/fail per check with severity and actionable messages.
+**Example** — full pre-flight validation:
+```json
+{
+  "checks": ["auth", "retailer", "locations", "workflows", "settings"]
+}
+```
+Response:
+```json
+{
+  "ok": true,
+  "results": [
+    { "check": "auth", "passed": true, "severity": "critical", "message": "Authenticated as admin@example.com" },
+    { "check": "retailer", "passed": true, "severity": "critical", "message": "Retailer HM_TEST (ID 5) is ACTIVE" },
+    { "check": "locations", "passed": true, "severity": "high", "message": "Found 3 locations (2 warehouses)" },
+    { "check": "workflows", "passed": false, "severity": "high", "message": "Missing workflow: FULFILMENT_OPTIONS::HD" },
+    { "check": "settings", "passed": true, "severity": "medium", "message": "12 retailer settings found" }
+  ],
+  "summary": { "passed": 4, "failed": 1, "total": 5 }
+}
+```
+---
+## `test.assert`
+Assert entity state matches expectations with optional polling.
+Deep assertion on entity fields, attributes, and edge counts/statuses with human-readable failure messages.
+- **Required**:
+  - `entityType`: entity type (ORDER, FULFILMENT, etc.)
+  - `assertions`: object with expected values
+- **Optional**:
+  - `id`: entity ID (preferred)
+  - `ref`: entity ref (fallback)
+  - `poll`: if `true`, retry until assertions pass or timeout (default `false`)
+  - `timeoutMs`: polling timeout in ms, 1000–300000 (default `60000`)
+  - `intervalMs`: polling interval in ms, 1000–30000 (default `5000`)
+**Assertion types:**
+| Assertion | Description |
+|---|---|
+| `status` | Exact match on entity status |
+| `type` | Exact match on entity type |
+| `subtype` | Exact match on entity subtype |
+| `attributes` | Key-value pairs that must be present on the entity |
+| `edges` | Min/max count and status on related entities (e.g., fulfilments) |
+**Polling mode:** Set `poll: true` to retry assertions on an interval until they pass or the timeout is reached. Useful after sending events when state changes are asynchronous.
+**Example** — assert order is BOOKED with at least 1 fulfilment (polling):
+```json
+{
+  "entityType": "ORDER",
+  "ref": "HD-001",
+  "assertions": {
+    "status": "BOOKED",
+    "edges": {
+      "fulfilments": { "minCount": 1 }
+    }
+  },
+  "poll": true,
+  "timeoutMs": 60000,
+  "intervalMs": 5000
+}
+```
+Response (pass):
+```json
+{
+  "ok": true,
+  "passed": true,
+  "entityType": "ORDER",
+  "entity": { "id": "12345", "ref": "HD-001", "status": "BOOKED" },
+  "assertions": {
+    "status": { "expected": "BOOKED", "actual": "BOOKED", "passed": true },
+    "edges.fulfilments.minCount": { "expected": 1, "actual": 2, "passed": true }
+  },
+  "polling": { "attempts": 3, "elapsed": 12500 }
+}
+```
+Response (fail after timeout):
+```json
+{
+  "ok": true,
+  "passed": false,
+  "entityType": "ORDER",
+  "entity": { "id": "12345", "ref": "HD-001", "status": "CREATED" },
+  "assertions": {
+    "status": { "expected": "BOOKED", "actual": "CREATED", "passed": false }
+  },
+  "polling": { "attempts": 12, "elapsed": 60000, "timedOut": true },
+  "failureMessage": "Assertion failed: status expected \"BOOKED\" but got \"CREATED\" (timed out after 60000ms)"
+}
+```
+---
+## Retry and idempotency matrix
+| Category | Tools | Retry behavior |
+|------|----------|-------------|
+| Read operations | `event.get`, `event.list`, `event.flowInspect`, `metrics.query`, `metrics.healthCheck`, `metrics.sloReport`, `metrics.labelCatalog`, `metrics.topEvents`, `workflow.transitions`, `graphql.query` (query), `graphql.queryAll`, `batch.status`, `batch.batchStatus`, `batch.results`, `graphql.introspect`, `connection.test`, `entity.get`, `environment.discover`, `environment.validate`, `test.assert`, `plugin.list` | retry + backoff |
+| Write operations | `event.send`, `batch.create`, `batch.send`, `graphql.query` (mutation), `graphql.batchMutate`, `entity.create`, `entity.update`, `workflow.upload`, `setting.upsert`, `setting.bulkUpsert` | timeout-only (no automatic retry) |
+| Local validation / no API | `config.validate`, `health.ping`, `event.build`, `webhook.validate`, `workflow.diff`, `workflow.simulate` | not applicable |
+## Tool inventory summary (36 tools)
+| Tool | Category | Requires SDK | Retry | Description |
+|------|----------|:------------:|:-----:|-------------|
+| `config.validate` | Diagnostics | No | — | Validate auth/base URL configuration |
+| `health.ping` | Diagnostics | No | — | Quick health check with config summary |
+| `connection.test` | Diagnostics | Yes | Yes | Full auth + GraphQL end-to-end test (returns user/account context) |
+| `event.build` | Events | No | — | Build event payload (no API call) |
+| `event.send` | Events | Yes | No | Send event (async/sync, supports dryRun) |
+| `event.get` | Events | Yes | Yes | Get single event by ID |
+| `event.list` | Events | Yes | Yes | List/filter events with pagination and optional analysis mode |
+| `event.flowInspect` | Events | Yes | Yes | One-call root-entity flow forensics with compact/full modes |
+| `metrics.query` | Metrics | Yes | Yes | Query Prometheus metrics (instant/range) |
+| `metrics.healthCheck` | Metrics | Yes | Yes | One-call anomaly assessment with Prometheus + Event API fallback |
+| `metrics.sloReport` | Metrics | Yes | Yes | SLO snapshot with rates, latency, and threshold findings |
+| `metrics.labelCatalog` | Metrics | Yes | Yes | Label discovery for a metric (live sampling + known hints) |
+| `metrics.topEvents` | Metrics | Yes | Yes | Ranked event analytics using Event API aggregation |
+| `workflow.transitions` | Orchestration | Yes | Yes | Query available user actions/transitions at any entity state |
+| `plugin.list` | Orchestration | Yes | Yes | List registered rules with optional name filter |
+| `graphql.query` | GraphQL | Yes | Varies | Execute single-page query or mutation (retries for queries only) |
+| `graphql.queryAll` | GraphQL | Yes | Yes | Auto-paginated query — follows cursors across all pages |
+| `graphql.batchMutate` | GraphQL | Yes | No | Execute up to 50 aliased mutations in one request |
+| `graphql.introspect` | GraphQL | Yes | Yes | Schema introspection (types, mutations, queries) |
+| `batch.create` | Batch | Yes | No | Create ingestion job |
+| `batch.send` | Batch | Yes | No | Send records to job |
+| `batch.status` | Batch | Yes | Yes | Check job status |
+| `batch.batchStatus` | Batch | Yes | Yes | Check specific batch within a job |
+| `batch.results` | Batch | Yes | Yes | Get per-record job outcomes |
+| `webhook.validate` | Webhooks | No | — | Validate webhook payload + optional signature verification |
+| `entity.create` | Entity | Yes | No | Type-safe entity creation with field validation and gotcha knowledge (12 entity types) |
+| `entity.update` | Entity | Yes | No | Status-aware entity updates with optional transition validation |
+| `entity.get` | Entity | Yes | Yes | Unified entity lookup by ID or ref with optional edge inclusion |
+| `workflow.upload` | Workflow Mgmt | Yes | No | Deploy workflow JSON via REST API with structure validation |
+| `workflow.diff` | Workflow Mgmt | No | — | Compare two workflows — rulesets, statuses, risk assessment, mermaid output |
+| `workflow.simulate` | Workflow Mgmt | No | — | Static prediction of event outcomes from workflow JSON |
+| `setting.upsert` | Settings | Yes | No | Create or update a setting with upsert semantics |
+| `setting.bulkUpsert` | Settings | Yes | No | Batch create/update up to 50 settings with per-setting error handling |
+| `environment.discover` | Environment | Yes | Yes | Full environment snapshot — retailer, locations, networks, catalogues, settings, modules |
+| `environment.validate` | Environment | Yes | Yes | Pre-flight validation checks: auth, retailer, locations, inventory, workflows |
+| `test.assert` | Test | Yes | Yes | Assert entity state with status, attribute, and edge assertions + polling mode |