@fluentcommerce/fluent-mcp-extn 0.1.0

package/docs/TOOL_REFERENCE.md

@@ -0,0 +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 |
+