@fluentcommerce/fluent-mcp-extn 0.2.0 → 0.3.0

package/docs/E2E_TESTING.md

@@ -1,429 +1,739 @@
-# End-to-End Testing Guide
-
-This guide walks through full validation of `fluent-mcp-extn` from startup to
-real Fluent API operations.
-
-## 1) Test levels
-
-- **Level 1: local quality gate** (no network)
-  - `npm run build`
-  - `npm test`
-- **Level 2: MCP runtime check** (server starts, tools load)
-  - `config.validate`
-  - `health.ping`
-  - `connection.test`
-- **Level 3: Fluent API smoke** (real API calls)
-  - `event.send` dry-run and real send
-  - `event.get` on sent event ID
-  - `graphql.query`
-  - `graphql.queryAll` (pagination timeout + aggregation)
-  - optional batch flow (`batch.create` -> `batch.send` -> `batch.status`)
-  - optional webhook verification (`webhook.validate` with `rawBody`)
-
-## 2) Prerequisites
-
-- valid Fluent sandbox/prod API base URL
-- auth configured using one of:
-  - `FLUENT_PROFILE` (optionally `FLUENT_PROFILE_RETAILER`)
-  - OAuth env vars
-  - `TOKEN_COMMAND`
-  - `FLUENT_ACCESS_TOKEN`
-- known retailer ID or retailer ref for your target environment
-
-## 3) Configure `.mcp.json`
-
-Use this as a baseline:
-
-```json
-{
-  "mcpServers": {
-    "fluent-mcp-extn": {
-      "type": "stdio",
-      "command": "node",
-      "args": ["fluent-mcp-extn/dist/index.js"],
-      "env": {
-        "FLUENT_BASE_URL": "https://YOUR_ACCOUNT.sandbox.api.fluentretail.com",
-        "FLUENT_RETAILER_ID": "YOUR_RETAILER_ID",
-        "TOKEN_COMMAND": "vault read -field=token secret/fluent/client-dev",
-        "FLUENT_REQUEST_TIMEOUT_MS": "30000",
-        "FLUENT_RETRY_ATTEMPTS": "3"
-      }
-    }
-  }
-}
-```
-
-After editing `.mcp.json`, reload Cursor so MCP servers restart with new env.
-
-Profile-first setup via AI Skills:
-
-```bash
-npx @fluentcommerce/ai-skills mcp-setup --profile YOUR_PROFILE --profile-retailer YOUR_RETAILER_REF
-```
-
-Then confirm extension env contains:
-
-- `FLUENT_PROFILE=YOUR_PROFILE`
-- `FLUENT_PROFILE_RETAILER=YOUR_RETAILER_REF` (retailer **ref**, not ID)
-
-## 4) Build and test locally
-
-From `fluent-mcp-extn/`:
-
-```bash
-npm install
-npm run build
-npm test
-```
-
-Expected: build succeeds and all unit tests pass.
-
-Optional automated smoke runner:
-
-```bash
-npm run e2e:smoke
-```
-
-This runs: tool discovery, config validation, health, event build, event dry-run,
-GraphQL checks, order lookup, real event send, and event retrieval by ID.
-
-Profile-driven and multi-retailer variants:
-
-```bash
-npm run e2e:smoke -- --wizard
-npm run e2e:smoke -- --profile CLIENT_PROFILE
-npm run e2e:smoke -- --profile CLIENT_PROFILE --retailer RETAILER_REF_OR_ID
-npm run e2e:smoke -- --profile CLIENT_PROFILE --all-retailers
-```
-
-Notes:
-
-- `--wizard` guides profile/account + retailer selection in interactive terminals
-- `--wizard` requires an interactive terminal (TTY); for CI/non-interactive runs use explicit flags (`--profile <name> --retailer <id|ref>` or `--profile <name> --all-retailers`)
-- `--profile` reads from `~/.fluentcommerce/<profile>/`
-- profile defaults are applied only when equivalent env vars are missing
-- `--retailer` accepts retailer ID or retailer ref
-- `--all-retailers` runs one full smoke cycle per retailer file in the profile
-- `--skip-real-send` performs dry-run checks only
-- with `--profile` only (no `--retailer` / `--all-retailers`), smoke may fall back to a retailer that has candidate orders for real-send validation; use `--retailer` for strict retailer scope
-
-### All-retailers run behavior
-
-`--all-retailers` requires `--profile` and executes one smoke cycle per
-`retailer.<ref>.json` file under `~/.fluentcommerce/<profile>/`. Output labels
-use retailer IDs (for example `retailer-5`).
-
-When a retailer has no candidate order, order lookup and real send steps are
-reported as skipped for that retailer (not failed). The command exits non-zero
-only when non-skipped steps fail.
-
-#### Interpreting results
-
-| Status | Meaning | Action |
-|---|---|---|
-| `PASS` | Step completed successfully for that retailer. | No action needed. |
-| `SKIP` | Step was intentionally not executed (for example, no candidate order in `--all-retailers` mode). | Verify preconditions only if you expected execution. |
-| `FAIL` | Step executed and returned an error or unexpected result. | Investigate payload/error details and fix before relying on run output. |
-
-## 5) MCP smoke sequence in Cursor
-
-Run these tools in order from the assistant:
-
-### Step 1: `config.validate`
-
-Request:
-
-```json
-{}
-```
-
-Expected:
-
-- `ok: true`
-- `validation.isReadyForApiCalls: true`
-- no blocking errors
-
-### Step 2: `health.ping`
-
-Request:
-
-```json
-{}
-```
-
-Expected:
-
-- `status: "ok"`
-- `sdkClient: "connected"` (or equivalent ready status)
-- config summary present without secret values
-
-### Step 3: `connection.test`
-
-Request:
-
-```json
-{}
-```
-
-Expected:
-
-- `ok: true`
-- `details` includes user, retailer, and location info
-- confirms end-to-end GraphQL connectivity
-
-### Step 4: `event.build`
-
-Request:
-
-```json
-{
-  "name": "ORDER_CREATED",
-  "entityRef": "E2E-ORDER-1001",
-  "entityType": "ORDER",
-  "attributes": {
-    "sourceSystem": "e2e-test",
-    "testRunId": "run-001"
-  }
-}
-```
-
-Expected:
-
-- `ok: true`
-- complete event payload returned
-- defaults applied (`rootEntityType`, `source`, `type`)
-
-### Step 5: `event.send` dry-run
-
-Request:
-
-```json
-{
-  "name": "ORDER_CREATED",
-  "entityRef": "E2E-ORDER-1001",
-  "entityId": "12345",
-  "entityType": "ORDER",
-  "dryRun": true
-}
-```
-
-Expected:
-
-- `ok: true`
-- `dryRun: true`
-- no API call made
-
-### Step 6: `event.send` real call
-
-Request:
-
-```json
-{
-  "name": "ORDER_CREATED",
-  "entityRef": "E2E-ORDER-1001",
-  "entityId": "12345",
-  "entityType": "ORDER",
-  "retailerId": "YOUR_ENTITY_RETAILER_ID",
-  "mode": "async",
-  "dryRun": false,
-  "attributes": {
-    "sourceSystem": "e2e-test",
-    "testRunId": "run-001"
-  }
-}
-```
-
-Expected:
-
-- `ok: true`
-- response from Fluent event API
-- retailer ID in payload matches the entity's retailer
-- operation executed once (write tools do not auto-retry)
-
-If this fails, investigate before resubmitting to avoid duplicate side effects.
-
-### Step 7: `graphql.query` verification
-
-Use a query valid for your schema. Example shape:
-
-```json
-{
-  "query": "query VerifyOrder($ref: String!) { orders(ref: $ref) { edges { node { id ref status } } } }",
-  "variables": {
-    "ref": "E2E-ORDER-1001"
-  }
-}
-```
-
-Expected:
-
-- `ok: true`
-- Fluent GraphQL response payload returned
-
-> Note: exact query fields differ by tenant schema/version.
-
-### Step 8: `graphql.queryAll` verification
-
-Validate auto-pagination and run-level timeout behavior:
-
-```json
-{
-  "query": "query($cursor: String) { orders(first: 50, after: $cursor) { edges { cursor node { id ref } } pageInfo { hasNextPage } } }",
-  "variables": { "cursor": null },
-  "timeoutMs": 120000
-}
-```
-
-Expected:
-
-- `ok: true`
-- `response.extensions.autoPagination` present
-- `pagination.totalPages` / `pagination.totalRecords` present in tool response
-
-### Step 9: `event.get` verification
-
-Use an event ID from successful `event.send` (or resolve ID via `event.list`).
-
-```json
-{
-  "eventId": "EVENT_ID_FROM_SEND_RESPONSE"
-}
-```
-
-Expected:
-
-- `ok: true`
-- event payload returned from Event API
-- event payload includes expected `name`, `context.entityRef`, and retailer
-
-If `event.send` response does not contain `id`, resolve it first with `event.list`:
-
-```json
-{
-  "name": "ORDER_CREATED",
-  "entityRef": "E2E-ORDER-1001",
-  "retailerId": "YOUR_ENTITY_RETAILER_ID",
-  "count": 1,
-  "start": 1
-}
-```
-
-### Step 10 (optional): `graphql.introspect`
-
-Verify schema introspection access:
-
-```json
-{
-  "listMutations": true
-}
-```
-
-Expected:
-
-- `ok: true`
-- `mutations` array returned
-- `count` reflects available mutations in the schema
-
-## 6) Optional webhook signature validation
-
-Use this when validating webhook integration cryptography:
-
-```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-----"
-}
-```
-
-Expected:
-
-- `ok: true` when payload and signature are valid
-- `signatureValidation.payloadSource` confirms whether `rawBody` was used
-
-## 7) Optional batch E2E
-
-### `batch.create`
-
-```json
-{
-  "name": "e2e-batch-001",
-  "entityType": "INVENTORY_POSITION",
-  "action": "UPSERT"
-}
-```
-
-### `batch.send`
-
-```json
-{
-  "jobId": "JOB_ID_FROM_CREATE",
-  "payload": {
-    "action": "UPSERT",
-    "entityType": "INVENTORY_POSITION",
-    "entities": [
-      {
-        "locationRef": "LOC-1",
-        "skuRef": "SKU-1",
-        "qty": 10,
-        "type": "LAST_ON_HAND",
-        "status": "ACTIVE"
-      }
-    ]
-  }
-}
-```
-
-### `batch.status`
-
-```json
-{
-  "jobId": "JOB_ID_FROM_CREATE"
-}
-```
-
-## 8) Failure triage quick map
-
-- `CONFIG_ERROR`: missing env values -> run `config.validate`
-- `AUTH_ERROR`: invalid creds/token -> verify OAuth or `TOKEN_COMMAND`
-- `VALIDATION_ERROR`: invalid input shape -> fix request payload
-- `TIMEOUT_ERROR` / `NETWORK_ERROR`: tune timeout/retry; verify connectivity
-- `RATE_LIMIT` / `UPSTREAM_UNAVAILABLE`: retry later (built-in retries are applied for read operations; write retries are manual by design)
-
-## 9) Exit criteria for successful E2E
-
-Mark E2E successful only when:
-
-- local build/test passed
-- config/health/connection tools are green
-- at least one real `event.send` succeeded
-- at least one `event.get` succeeded
-- at least one real `graphql.query` succeeded
-- at least one `graphql.queryAll` run succeeded
-- (optional) `graphql.introspect` schema access confirmed
-- (optional) batch cycle completed
-
-## 10) CI-triggered smoke (GitHub Actions)
-
-Workflow: `.github/workflows/ci.yml`
-
-- `build-and-test`: runs on push and pull request
-- `e2e-smoke`: runs on `workflow_dispatch` only
-
-Set repository or environment secrets before running `e2e-smoke`:
-
-- `FLUENT_BASE_URL`
-- `FLUENT_RETAILER_ID` (optional but recommended)
-- `FLUENT_CLIENT_ID`
-- `FLUENT_CLIENT_SECRET`
-- `FLUENT_USERNAME` (optional for client-credentials flow)
-- `FLUENT_PASSWORD` (optional for client-credentials flow)
-
-CI smoke runs are typically env-driven (no `--profile` required). For profile-based runs in CI, pass explicit flags (`--profile <name> --retailer <id|ref>` or `--profile <name> --all-retailers`).
-If real event side effects are not desired, run with `--skip-real-send`.
-
+# End-to-End Testing Guide
+
+This guide walks through full validation of `fluent-mcp-extn` from startup to
+real Fluent API operations.
+
+## Script inventory
+
+| Script | Type | Purpose |
+|--------|------|---------|
+| `e2e-smoke.ts` | E2E | Full MCP smoke cycle: tool discovery, config, health, events, GraphQL |
+| `e2e-negative.ts` | E2E | Validation error and malformed input handling |
+| `e2e-profile-test.mjs` | E2E | Quick FLUENT_PROFILE integration check |
+| `e2e-full-order.ts` | E2E | Single order lifecycle: create, validate, fulfil, ship, deliver |
+| `e2e-full-multi.ts` | E2E | ORDER::MULTI lifecycle with discovery and fulfilment event sequence |
+| `e2e-agentic.ts` | E2E | All 11 agentic tools: entity CRUD, workflow, settings, environment |
+| `e2e-response-shaping.ts` | E2E | Response budget enforcement and auto-summarization proof |
+| `run-flow-inspect.ts` | Utility | FlowInspect forensics with local analysis, LLM packet, and drilldowns |
+| `order-event-inspect.ts` | Utility | Order-specific event deep dive with audit trail extraction |
+| `check-event-status.ts` | Utility | Event status polling by ID, name, or entity ref |
+
+All scripts require a built server (`npm run build`) and valid Fluent credentials.
+
+## 1) Test levels
+
+- **Level 1: local quality gate** (no network)
+  - `npm run build`
+  - `npm test`
+- **Level 2: MCP runtime check** (server starts, tools load)
+  - `config.validate`
+  - `health.ping`
+  - `connection.test`
+- **Level 3: Fluent API smoke** (real API calls)
+  - `event.send` dry-run and real send
+  - `event.get` on sent event ID
+  - `graphql.query`
+  - `graphql.queryAll` (pagination timeout + aggregation)
+  - optional batch flow (`batch.create` -> `batch.send` -> `batch.status`)
+  - optional webhook verification (`webhook.validate` with `rawBody`)
+
+## 2) Prerequisites
+
+- valid Fluent sandbox/prod API base URL
+- auth configured using one of:
+  - `FLUENT_PROFILE` (optionally `FLUENT_PROFILE_RETAILER`)
+  - OAuth env vars
+  - `TOKEN_COMMAND`
+  - `FLUENT_ACCESS_TOKEN`
+- known retailer ID or retailer ref for your target environment
+
+## 3) Configure `.mcp.json`
+
+Use this as a baseline:
+
+```json
+{
+  "mcpServers": {
+    "fluent-mcp-extn": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["fluent-mcp-extn/dist/index.js"],
+      "env": {
+        "FLUENT_BASE_URL": "https://YOUR_ACCOUNT.sandbox.api.fluentretail.com",
+        "FLUENT_RETAILER_ID": "YOUR_RETAILER_ID",
+        "TOKEN_COMMAND": "vault read -field=token secret/fluent/client-dev",
+        "FLUENT_REQUEST_TIMEOUT_MS": "30000",
+        "FLUENT_RETRY_ATTEMPTS": "3"
+      }
+    }
+  }
+}
+```
+
+After editing `.mcp.json`, reload your IDE so MCP servers restart with new env.
+
+Profile-first setup via AI Skills:
+
+```bash
+npx @fluentcommerce/ai-skills mcp-setup --profile YOUR_PROFILE --profile-retailer YOUR_RETAILER_REF
+```
+
+Then confirm extension env contains:
+
+- `FLUENT_PROFILE=YOUR_PROFILE`
+- `FLUENT_PROFILE_RETAILER=YOUR_RETAILER_REF` (retailer **ref**, not ID)
+
+## 4) Build and test locally
+
+From `fluent-mcp-extn/`:
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+Expected: build succeeds and all unit tests pass.
+
+Optional automated smoke runner:
+
+```bash
+npm run e2e:smoke
+```
+
+This runs: tool discovery, config validation, health, event build, event dry-run,
+GraphQL checks, order lookup, real event send, and event retrieval by ID.
+
+Profile-driven and multi-retailer variants:
+
+```bash
+npm run e2e:smoke -- --wizard
+npm run e2e:smoke -- --profile CLIENT_PROFILE
+npm run e2e:smoke -- --profile CLIENT_PROFILE --retailer RETAILER_REF_OR_ID
+npm run e2e:smoke -- --profile CLIENT_PROFILE --all-retailers
+```
+
+Notes:
+
+- `--wizard` guides profile/account + retailer selection in interactive terminals
+- `--wizard` requires an interactive terminal (TTY); for CI/non-interactive runs use explicit flags (`--profile <name> --retailer <id|ref>` or `--profile <name> --all-retailers`)
+- `--profile` reads from `~/.fluentcommerce/<profile>/`
+- profile defaults are applied only when equivalent env vars are missing
+- `--retailer` accepts retailer ID or retailer ref
+- `--all-retailers` runs one full smoke cycle per retailer file in the profile
+- `--skip-real-send` performs dry-run checks only
+- with `--profile` only (no `--retailer` / `--all-retailers`), smoke may fall back to a retailer that has candidate orders for real-send validation; use `--retailer` for strict retailer scope
+
+### All-retailers run behavior
+
+`--all-retailers` requires `--profile` and executes one smoke cycle per
+`retailer.<ref>.json` file under `~/.fluentcommerce/<profile>/`. Output labels
+use retailer IDs (for example `retailer-5`).
+
+When a retailer has no candidate order, order lookup and real send steps are
+reported as skipped for that retailer (not failed). The command exits non-zero
+only when non-skipped steps fail.
+
+#### Interpreting results
+
+| Status | Meaning | Action |
+|---|---|---|
+| `PASS` | Step completed successfully for that retailer. | No action needed. |
+| `SKIP` | Step was intentionally not executed (for example, no candidate order in `--all-retailers` mode). | Verify preconditions only if you expected execution. |
+| `FAIL` | Step executed and returned an error or unexpected result. | Investigate payload/error details and fix before relying on run output. |
+
+## 5) E2E script reference
+
+### `e2e-smoke.ts`
+
+Full MCP client smoke cycle that exercises the core tool chain end to end.
+
+**What it tests:** tool discovery, `config.validate`, `health.ping`, `event.build`,
+`event.send` (dry-run and real), `graphql.query`, `graphql.queryAll`, order lookup,
+`event.get` by ID.
+
+**How to run:**
+
+```bash
+npm run e2e:smoke
+npm run e2e:smoke -- --profile HMDEV
+npm run e2e:smoke -- --profile HMDEV --retailer HM_TEST
+npm run e2e:smoke -- --profile HMDEV --all-retailers
+npm run e2e:smoke -- --skip-real-send
+```
+
+**Environment:** requires `FLUENT_BASE_URL` + auth env vars, or `--profile`.
+
+---
+
+### `e2e-negative.ts`
+
+Validates that the server returns correct error envelopes for invalid inputs.
+
+**What it tests:**
+- `event.send` with missing required `entityRef` field
+- `graphql.query` with malformed GraphQL syntax
+- `event.get` with a nonexistent event ID
+- `graphql.introspect` with a nonexistent mutation name
+- `webhook.validate` with an invalid signature and public key
+
+Each test case asserts: `ok: false`, standard error envelope shape
+(`code` + `message` + `retryable`), and expected error code where applicable
+(e.g., `VALIDATION_ERROR`).
+
+**How to run:**
+
+```bash
+npx tsx scripts/e2e-negative.ts
+npx tsx scripts/e2e-negative.ts --profile HMDEV
+npx tsx scripts/e2e-negative.ts --profile HMDEV --retailer HM_TEST
+```
+
+**Environment:** requires `FLUENT_BASE_URL` + auth env vars, or `--profile`.
+
+---
+
+### `e2e-profile-test.mjs`
+
+Minimal FLUENT_PROFILE integration check. Loads config, creates SDK client, and
+runs four quick API calls to verify profile-based auth works end to end.
+
+**What it tests:**
+1. Config loads correctly with profile auth strategy
+2. GraphQL `me` query returns user and retailer info
+3. `getEvents` returns event results
+4. `getPlugins` returns the plugin registry
+5. `getTransitions` returns user actions for ORDER::HD at CREATED status
+
+**How to run:**
+
+```bash
+FLUENT_PROFILE=HMDEV FLUENT_PROFILE_RETAILER=HM_TEST node scripts/e2e-profile-test.mjs
+```
+
+**Environment:** requires `FLUENT_PROFILE` and optionally `FLUENT_PROFILE_RETAILER`
+set as env vars. Uses compiled `dist/` output directly (not MCP stdio transport).
+
+---
+
+### `e2e-full-order.ts`
+
+Discovery-first single order lifecycle test. Creates an order with
+`sourcingLocationRef`, then drives it through the full fulfilment workflow.
+
+**What it tests:**
+1. Config validation
+2. Discovery: locations, catalogues, products, customers, settings
+3. `createOrder` mutation with sourcing attributes
+4. `ConfirmValidation` event on order
+5. Query order + fulfilments post-validation
+6. Fulfilment events: `ConfirmAllocation`, `CreateInvoice`, `ConfirmPick`,
+   `ConfirmShipment`, `ConfirmDelivery`
+7. Final order/fulfilment state verification
+8. Event trace: counts SUCCESS vs FAILED events for the order
+
+**How to run:**
+
+```bash
+npx tsx scripts/e2e-full-order.ts --profile SAGIRISH --retailer 2
+FLUENT_PROFILE=SAGIRISH FLUENT_RETAILER_ID=2 npx tsx scripts/e2e-full-order.ts
+```
+
+**Environment:** requires `FLUENT_PROFILE` + `FLUENT_RETAILER_ID`, or `--profile`
+and `--retailer` flags. Environment must have warehouse locations, product
+catalogue with active products, and at least one customer entity.
+
+**Note:** this script creates real orders and fires real events. Use a sandbox.
+
+---
+
+### `e2e-full-multi.ts`
+
+ORDER::MULTI lifecycle test. Similar to `e2e-full-order.ts` but targets the
+MULTI order type workflow and includes workflow transition discovery.
+
+**What it tests:**
+1. Config validation
+2. Discovery: retailer, locations, catalogues, products, customers, settings
+3. `workflow.transitions` for ORDER::MULTI at ON_VALIDATION status
+4. `createOrder` mutation with MULTI type
+5. `ConfirmValidation` event
+6. Fulfilment creation verification
+7. Fulfilment event sequence: `ConfirmAllocation`, `CreateInvoice`,
+   `ConfirmPick`, `ConfirmShipment`, `ConfirmDelivery`
+8. Event trace on failure
+
+**How to run:**
+
+```bash
+npx tsx scripts/e2e-full-multi.ts
+```
+
+**Environment:** defaults to `FLUENT_BASE_URL=https://sagirish.test.api.fluentretail.com`
+and `FLUENT_RETAILER_ID=2`. Override with env vars. Requires OAuth or profile
+credentials.
+
+**Note:** creates real orders and fires real events. Use a sandbox.
+
+---
+
+### `e2e-agentic.ts`
+
+Comprehensive smoke test for all 11 agentic tools against a live environment.
+
+**What it tests:**
+- `environment.discover` (retailer + locations, catalogues)
+- `environment.validate` (auth, retailer, locations checks)
+- `entity.create` (dryRun validation, required field rejection, live creation)
+- `entity.get` (by ID, by ref, nonexistent ref)
+- `entity.update` (attribute update)
+- `test.assert` (status match, status mismatch)
+- `setting.upsert` (create new, update existing with previous value)
+- `workflow.diff` (summary format, mermaid format)
+- `workflow.simulate` (status matching, custom rule confidence, no-match)
+- `workflow.upload` (dryRun structure validation)
+
+**How to run:**
+
+```bash
+npx tsx scripts/e2e-agentic.ts --profile SAGIRISH
+```
+
+**Environment:** requires `FLUENT_PROFILE` or `--profile` flag. Defaults to
+`FLUENT_RETAILER_ID=2`.
+
+**Note:** creates real orders and settings. Use a sandbox.
+
+---
+
+### `e2e-response-shaping.ts`
+
+Proves that response shaping (auto-summarization) works correctly on real API
+responses.
+
+**What it proves:**
+1. `event.flowInspect` compact response stays within budget (50k chars)
+2. `event.flowInspect` full mode (`compact: false`) gets auto-summarized, not truncated
+3. `plugin.list` (unfiltered, 500+ rules) gets shaped when large
+4. `event.list` (500 events) gets shaped when large
+5. `_responseMeta` appears with accurate stats (originalChars, shapedChars, reductionPercent)
+6. No `_truncated` markers anywhere (replaced by `_summarized`)
+
+**How to run:**
+
+```bash
+npx tsx scripts/e2e-response-shaping.ts --profile SAGIRISH
+```
+
+**Environment:** requires `FLUENT_PROFILE` or `--profile`. Uses default budget
+(50k chars). The environment must have enough events and plugins to exceed the
+budget threshold.
+
+---
+
+### `run-flow-inspect.ts`
+
+Advanced FlowInspect forensics runner. Calls `event.flowInspect`, then performs
+local analysis: risk scoring, finding extraction, evidence ranking, and optional
+per-event drilldowns via `event.get`.
+
+**Outputs:**
+- Raw JSON: full flowInspect response
+- Summary JSON: risk score, status/entity distributions, anomaly counts, webhook
+  failure breakdown, exception classes, slow rulesets, mismatch reasons
+- LLM packet (Markdown): compact handoff document for AI consumption
+- Drilldown JSON: classified event details (webhook, mutation, sendEvent, mismatch)
+
+**How to run:**
+
+```bash
+npx tsx scripts/run-flow-inspect.ts <ROOT_ENTITY_REF> --profile SAGIRISH
+npx tsx scripts/run-flow-inspect.ts HD-001 --root-type ORDER --profile HMDEV
+npx tsx scripts/run-flow-inspect.ts HD-001 --root-id 12345 --light --no-drilldown
+npx tsx scripts/run-flow-inspect.ts HD-001 --drilldown-classes webhook,mutation --drilldown-limit 20
+```
+
+**Options:**
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--profile <name>` | `SAGIRISH` | Fluent CLI profile |
+| `--root-type <type>` | any | Root entity type (ORDER, FULFILMENT, etc.) |
+| `--root-id <id>` | - | Root entity ID for disambiguation |
+| `--out <path>` | `accounts/<profile>/analysis/EVENT_FLOW_INSPECT_<ref>.json` | Raw output path |
+| `--summary-out <path>` | `<base>.summary.json` | Summary output path |
+| `--packet-out <path>` | `<base>.llm-packet.md` | LLM packet output path |
+| `--drilldown-out <path>` | `<base>.drilldown.json` | Drilldown output path |
+| `--light` | false | Compact mode (fewer audit details) |
+| `--no-drilldown` | false | Skip per-event drilldowns |
+| `--drilldown-limit <n>` | 15 | Max events to drill into |
+| `--drilldown-classes <list>` | all | Comma-separated: webhook,mutation,sendEvent,mismatch,exception,scheduled,slow,status |
+| `--top-n <n>` | 10 | Top-N items per section |
+| `--evidence-limit <n>` | 20 | Max evidence event IDs |
+| `--truncate <n>` | 220 | Max chars for text fields |
+| `--max-pages <n>` | 10 | Max 500-event pages to fetch |
+| `--no-llm-pack` | false | Skip LLM packet generation |
+
+**Environment:** requires `FLUENT_PROFILE` or env vars.
+
+---
+
+### `order-event-inspect.ts`
+
+Order-specific event deep dive. Looks up an order by ref, then fetches all
+ORCHESTRATION and ORCHESTRATION_AUDIT events, classifying them into webhooks,
+mutations, sendEvent actions, scheduled actions, and ruleset durations.
+
+**Outputs:** a single JSON file with:
+- Order entity details (status, attributes, fulfilment choices)
+- Orchestration events (status counts, entity type counts, top event names)
+- Audit trail (webhook actions, mutation actions, sendEvent actions, scheduled
+  actions, ruleset durations, exceptions)
+- Drilldown details for NO_MATCH and PENDING events
+
+**How to run:**
+
+```bash
+npx tsx scripts/order-event-inspect.ts <ORDER_REF> --profile SAGIRISH
+npx tsx scripts/order-event-inspect.ts HD-001 --profile HMDEV --out /tmp/inspect.json
+```
+
+**Environment:** requires `FLUENT_PROFILE` or env vars.
+
+---
+
+### `check-event-status.ts`
+
+Lightweight event status checker. Fetches events by ID or lists events by name
+and entity ref.
+
+**How to run:**
+
+```bash
+# Fetch specific events by ID
+npx tsx scripts/check-event-status.ts --event-id <uuid> --profile SAGIRISH
+
+# List events by name
+npx tsx scripts/check-event-status.ts --event-name ConfirmValidation --profile SAGIRISH
+
+# List events by entity ref
+npx tsx scripts/check-event-status.ts --entity-ref HD-001 --profile SAGIRISH
+
+# Combine filters
+npx tsx scripts/check-event-status.ts --event-name ConfirmValidation --entity-ref HD-001 --count 20 --profile SAGIRISH
+```
+
+**Options:**
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--profile <name>` | - | Fluent CLI profile |
+| `--retailer <id\|ref>` | from profile/env | Retailer filter |
+| `--event-id <uuid>` | - | Fetch specific event (repeatable) |
+| `--event-name <name>` | - | Event name filter for list |
+| `--entity-ref <ref>` | - | Entity ref filter for list |
+| `--count <n>` | 10 | Max list size (max 500) |
+
+**Environment:** requires `FLUENT_BASE_URL` + auth, or `--profile`.
+
+## 6) MCP smoke sequence in your IDE
+
+Run these tools in order from the assistant:
+
+### Step 1: `config.validate`
+
+Request:
+
+```json
+{}
+```
+
+Expected:
+
+- `ok: true`
+- `validation.isReadyForApiCalls: true`
+- no blocking errors
+
+### Step 2: `health.ping`
+
+Request:
+
+```json
+{}
+```
+
+Expected:
+
+- `status: "ok"`
+- `sdkClient: "connected"` (or equivalent ready status)
+- config summary present without secret values
+
+### Step 3: `connection.test`
+
+Request:
+
+```json
+{}
+```
+
+Expected:
+
+- `ok: true`
+- `details` includes user, retailer, and location info
+- confirms end-to-end GraphQL connectivity
+
+### Step 4: `event.build`
+
+Request:
+
+```json
+{
+  "name": "ORDER_CREATED",
+  "entityRef": "E2E-ORDER-1001",
+  "entityType": "ORDER",
+  "attributes": {
+    "sourceSystem": "e2e-test",
+    "testRunId": "run-001"
+  }
+}
+```
+
+Expected:
+
+- `ok: true`
+- complete event payload returned
+- defaults applied (`rootEntityType`, `source`, `type`)
+
+### Step 5: `event.send` dry-run
+
+Request:
+
+```json
+{
+  "name": "ORDER_CREATED",
+  "entityRef": "E2E-ORDER-1001",
+  "entityId": "12345",
+  "entityType": "ORDER",
+  "dryRun": true
+}
+```
+
+Expected:
+
+- `ok: true`
+- `dryRun: true`
+- no API call made
+
+### Step 6: `event.send` real call
+
+Request:
+
+```json
+{
+  "name": "ORDER_CREATED",
+  "entityRef": "E2E-ORDER-1001",
+  "entityId": "12345",
+  "entityType": "ORDER",
+  "retailerId": "YOUR_ENTITY_RETAILER_ID",
+  "mode": "async",
+  "dryRun": false,
+  "attributes": {
+    "sourceSystem": "e2e-test",
+    "testRunId": "run-001"
+  }
+}
+```
+
+Expected:
+
+- `ok: true`
+- response from Fluent event API
+- retailer ID in payload matches the entity's retailer
+- operation executed once (write tools do not auto-retry)
+
+If this fails, investigate before resubmitting to avoid duplicate side effects.
+
+### Step 7: `graphql.query` verification
+
+Use a query valid for your schema. Example shape:
+
+```json
+{
+  "query": "query VerifyOrder($ref: String!) { orders(ref: $ref) { edges { node { id ref status } } } }",
+  "variables": {
+    "ref": "E2E-ORDER-1001"
+  }
+}
+```
+
+Expected:
+
+- `ok: true`
+- Fluent GraphQL response payload returned
+
+> Note: exact query fields differ by tenant schema/version.
+
+### Step 8: `graphql.queryAll` verification
+
+Validate auto-pagination and run-level timeout behavior:
+
+```json
+{
+  "query": "query($cursor: String) { orders(first: 50, after: $cursor) { edges { cursor node { id ref } } pageInfo { hasNextPage } } }",
+  "variables": { "cursor": null },
+  "timeoutMs": 120000
+}
+```
+
+Expected:
+
+- `ok: true`
+- `response.extensions.autoPagination` present
+- `pagination.totalPages` / `pagination.totalRecords` present in tool response
+
+### Step 9: `event.get` verification
+
+Use an event ID from successful `event.send` (or resolve ID via `event.list`).
+
+```json
+{
+  "eventId": "EVENT_ID_FROM_SEND_RESPONSE"
+}
+```
+
+Expected:
+
+- `ok: true`
+- event payload returned from Event API
+- event payload includes expected `name`, `context.entityRef`, and retailer
+
+If `event.send` response does not contain `id`, resolve it first with `event.list`:
+
+```json
+{
+  "name": "ORDER_CREATED",
+  "entityRef": "E2E-ORDER-1001",
+  "retailerId": "YOUR_ENTITY_RETAILER_ID",
+  "count": 1,
+  "start": 1
+}
+```
+
+### Step 10 (optional): `graphql.introspect`
+
+Verify schema introspection access:
+
+```json
+{
+  "listMutations": true
+}
+```
+
+Expected:
+
+- `ok: true`
+- `mutations` array returned
+- `count` reflects available mutations in the schema
+
+## 7) Optional webhook signature validation
+
+Use this when validating webhook integration cryptography:
+
+```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-----"
+}
+```
+
+Expected:
+
+- `ok: true` when payload and signature are valid
+- `signatureValidation.payloadSource` confirms whether `rawBody` was used
+
+## 8) Optional batch E2E
+
+### `batch.create`
+
+```json
+{
+  "name": "e2e-batch-001",
+  "entityType": "INVENTORY_POSITION",
+  "action": "UPSERT"
+}
+```
+
+### `batch.send`
+
+```json
+{
+  "jobId": "JOB_ID_FROM_CREATE",
+  "payload": {
+    "action": "UPSERT",
+    "entityType": "INVENTORY_POSITION",
+    "entities": [
+      {
+        "locationRef": "LOC-1",
+        "skuRef": "SKU-1",
+        "qty": 10,
+        "type": "LAST_ON_HAND",
+        "status": "ACTIVE"
+      }
+    ]
+  }
+}
+```
+
+### `batch.status`
+
+```json
+{
+  "jobId": "JOB_ID_FROM_CREATE"
+}
+```
+
+## 9) Failure triage quick map
+
+- `CONFIG_ERROR`: missing env values -> run `config.validate`
+- `AUTH_ERROR`: invalid creds/token -> verify OAuth or `TOKEN_COMMAND`
+- `VALIDATION_ERROR`: invalid input shape -> fix request payload
+- `TIMEOUT_ERROR` / `NETWORK_ERROR`: tune timeout/retry; verify connectivity
+- `RATE_LIMIT` / `UPSTREAM_UNAVAILABLE`: retry later (built-in retries are applied for read operations; write retries are manual by design)
+
+## 10) Exit criteria for successful E2E
+
+Mark E2E successful only when:
+
+- local build/test passed
+- config/health/connection tools are green
+- at least one real `event.send` succeeded
+- at least one `event.get` succeeded
+- at least one real `graphql.query` succeeded
+- at least one `graphql.queryAll` run succeeded
+- (optional) `graphql.introspect` schema access confirmed
+- (optional) batch cycle completed
+
+## 11) CI-triggered smoke (GitHub Actions)
+
+Workflow: `.github/workflows/ci.yml`
+
+- `build-and-test`: runs on push and pull request
+- `e2e-smoke`: runs on `workflow_dispatch` only
+
+Set repository or environment secrets before running `e2e-smoke`:
+
+- `FLUENT_BASE_URL`
+- `FLUENT_RETAILER_ID` (optional but recommended)
+- `FLUENT_CLIENT_ID`
+- `FLUENT_CLIENT_SECRET`
+- `FLUENT_USERNAME` (optional for client-credentials flow)
+- `FLUENT_PASSWORD` (optional for client-credentials flow)
+
+CI smoke runs are typically env-driven (no `--profile` required). For profile-based runs in CI, pass explicit flags (`--profile <name> --retailer <id|ref>` or `--profile <name> --all-retailers`).
+If real event side effects are not desired, run with `--skip-real-send`.