@fluentcommerce/ai-skills 0.1.0

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

@@ -0,0 +1,1058 @@
+---
+name: fluent-settings
+description: Manage Fluent Commerce settings — discover, audit, create, update, and migrate retailer-scoped settings. Cross-reference workflow rules with settings to find gaps. Triggers on "manage settings", "create setting", "audit settings", "settings migration", "missing settings", "webhook settings".
+user-invocable: true
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+argument-hint: [--audit <workflow-file>] [--context RETAILER|ACCOUNT|LOCATION] [--migrate --from <profile> --to <profile>]
+---
+
+# Settings Lifecycle Management
+
+Manage Fluent Commerce settings that configure how workflow rules behave at runtime. Settings are the critical glue between deployed workflows and working business logic — when a setting is missing, rules fail silently, orders get stuck, and webhooks never fire.
+
+## Planning Gate
+
+**Before creating or updating any settings, write a plan using the template from `PLAN_TEMPLATE.md` in the `fluent-feature-plan` skill.** Every setting row must carry a Source column (NEW/EXISTING/MODIFIED). Read-only operations (audit, discover, list) are exempt.
+
+**Settings-specific emphasis — ensure these are covered:**
+
+1. **Business Context (Section 1)** — why these settings are needed; what workflow behavior they enable
+2. **Settings impact (Section 4.4)** — full table: setting key, context (RETAILER/ACCOUNT/LOCATION), contextId, action (create/update), value/shape, which ruleset reads it. Show **current → new** value for updates
+3. **Webhooks (Section 4.5)** — if creating webhook URL settings: endpoint, HTTP method, payload shape, which ruleset fires it
+4. **Impacted rulesets (Section 4.3)** — which workflow rules depend on each setting; what behavior changes
+5. **Impacted retailers (Section 4.8)** — settings take effect immediately; confirm target environment
+6. **Risks (Section 7)** — wrong values can break live flows; note immediate-effect risk
+
+**Write the plan to:** `accounts/<PROFILE>/plans/<YYYY-MM-DD>-settings-<slug>.md`. Set `Status: PENDING`.
+
+Present the full plan content to the user and wait for approval before sending any `setting.upsert` or `setting.bulkUpsert` calls. On approval, update the file to `Status: APPROVED`. If the user says "just do it", proceed directly (still write the file for audit trail).
+
+## Ownership Boundary
+
+This skill owns Settings CRUD, discovery, audit, and migration.
+
+Workflow rule analysis is owned by `/fluent-workflow-analyzer`.
+MCP tool syntax is owned by `/fluent-mcp-tools`.
+Workflow creation and editing guidance is owned by `/fluent-workflow-builder`.
+Entity test data is owned by `/fluent-test-data`.
+Module deployment is owned by `/fluent-module-deploy`.
+
+## When to Use
+
+- After deploying a workflow or module — verify all required settings exist
+- Setting up a new retailer — create required settings for workflows to function
+- Debugging "rule did nothing" failures — missing settings are the #1 silent failure cause
+- Migrating settings between environments (dev to staging to prod)
+- Auditing settings completeness before go-live (Ready For Launch)
+- Investigating webhook or carrier integration failures — the root cause is almost always a missing or malformed setting
+
+## Settings Model in Fluent
+
+Settings are key-value entities that configure rule behavior at runtime. They are NOT part of the workflow JSON — they live in the Fluent platform as separate entities queried by rules during execution.
+
+### Entity Structure
+
+A Setting has these queryable fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | String | Platform-assigned unique ID |
+| `name` | String | The reference key (e.g., `webhook.order.created`) — this is what rules look up |
+| `value` | String | The setting value (for STRING/INTEGER/BOOLEAN types). Returns empty string for LOB types |
+| `lobValue` | String | Large object value — JSON string (for LOB-type settings only). Empty for non-LOB types |
+| `valueType` | String | `STRING`, `LOB`, `INTEGER`, `BOOLEAN`, or `JSON` |
+| `context` | String | Scope type: `RETAILER`, `ACCOUNT`, `GLOBAL`, `AGENT`, or `CUSTOMER` |
+| `contextId` | Int | ID of the scoped entity (e.g., retailer ID `2` when context is `RETAILER`). `0` for GLOBAL/ACCOUNT |
+
+**Important:** `context` and `contextId` are **separate fields**. The `context` is a plain string like `"RETAILER"` — NOT `"RETAILER:2"`. The entity ID goes in `contextId` as an integer.
+
+### Context Types
+
+Settings are scoped using two separate fields — `context` (scope type string) and `contextId` (scoped entity ID integer):
+
+| Context | `contextId` | Use Case |
+|---------|-------------|----------|
+| `RETAILER` | retailer ID (e.g., `2`) | Most common — webhook URLs, carrier configs, routing strategy |
+| `ACCOUNT` | `0` | Account-wide defaults that apply across retailers |
+| `GLOBAL` | `0` | Platform-wide (e.g., sourcing criteria) |
+| `AGENT` | agent/user ID | Agent-specific settings |
+| `CUSTOMER` | customer ID | Customer-specific preferences |
+
+When a rule reads a setting, it resolves in order of specificity: AGENT > RETAILER > ACCOUNT > GLOBAL. A more specific setting overrides a broader one with the same name.
+
+### How Rules Access Settings
+
+Rules access settings through the `SettingUtils.getSettingByRef(context, settingRef)` API. The rule reads a `setting` prop from the workflow ruleset configuration, then queries the platform for that setting name. If the setting does not exist, the rule typically throws a null pointer exception or silently skips its logic — both result in the entity not advancing.
+
+## Phase 1: Discovery — List All Settings
+
+### List All Settings for a Retailer
+
+Use `graphql.query` for a quick look, or `graphql.queryAll` for retailers with many settings:
+
+```graphql
+query($cursor: String) {
+  settings(first: 100, after: $cursor, context: "RETAILER") {
+    edges {
+      cursor
+      node {
+        id
+        name
+        value
+        valueType
+        context
+        contextId
+        lobValue
+      }
+    }
+    pageInfo { hasNextPage }
+  }
+}
+```
+
+**Important:** The `context` argument is a plain **String** — not an object. Valid values: `"RETAILER"`, `"ACCOUNT"`, `"GLOBAL"`, `"AGENT"`, `"CUSTOMER"`. Using `{ contextType: "..." }` will fail with a `WrongType` validation error.
+
+For auto-pagination across all settings:
+
+```
+graphql.queryAll({
+  query: "query($cursor: String) { settings(first: 100, after: $cursor, context: \"RETAILER\") { edges { cursor node { id name value valueType context contextId lobValue } } pageInfo { hasNextPage } } }",
+  variables: { cursor: null },
+  maxRecords: 5000
+})
+```
+
+### Search Settings by Exact Name
+
+The `name` filter accepts an array of exact names:
+
+```graphql
+{
+  settings(first: 1, name: ["webhook.order.created"], context: "RETAILER") {
+    edges {
+      node {
+        id
+        name
+        value
+        valueType
+        context
+        contextId
+        lobValue
+      }
+    }
+  }
+}
+```
+
+### Search Settings by Name Pattern
+
+Fluent does not support wildcard/regex in the `name` filter. To find settings matching a pattern (e.g., all webhook settings), query all settings and filter client-side:
+
+```
+1. graphql.queryAll to fetch all settings
+2. Filter results where name starts with "webhook." or contains the target pattern
+```
+
+### List Settings at a Specific Context
+
+```graphql
+{
+  settings(first: 50, context: "ACCOUNT") {
+    edges {
+      node {
+        id
+        name
+        value
+        valueType
+        context
+        contextId
+      }
+    }
+  }
+}
+```
+
+Replace `"ACCOUNT"` with `"GLOBAL"`, `"AGENT"`, or `"CUSTOMER"` as needed.
+
+## Phase 2: Audit — Cross-Reference with Workflow Rules
+
+This is the most valuable operation. Missing settings are the number one cause of silent rule failures in Fluent Commerce. After every workflow deployment, run this audit.
+
+### Extraction Algorithm
+
+Parse the workflow JSON file and extract all rule `props` that reference settings:
+
+```
+For each ruleset in workflow JSON:
+  For each rule in ruleset.rules:
+    1. If rule.name contains "SendWebhook" or "SendWebhookWithDynamicAttributes":
+       Extract props["setting"] or props["webhookSettingName"] → required setting name
+       Tag: expectedType=LOB (webhook settings are always JSON with a "url" field)
+    2. If rule.name contains "UpdateEntityFromSetting":
+       Extract props["setting"] or props["settingName"] → required setting name
+       Tag: expectedType=LOB (entity update mappings are JSON)
+    3. If any prop key matches: "setting", "settingName", "settingRef", "settingsKey", "webhookSettingName":
+       Extract the prop value → required setting name
+    4. If rule.name contains "SettingUtils" or "GetSetting":
+       Extract the setting reference from props
+
+  Record: { settingName, referencedBy: rulesetName, ruleName, propKey, expectedType? }
+```
+
+### Parameter-Level Discovery via plugin.list
+
+The prop extraction above catches explicit setting references. To find implicit ones (settings accessed inside rule logic but not named in obvious prop keys), query the live rule registry:
+
+```
+For each unique rule name in the workflow:
+  plugin.list({ name: "<RuleShortName>" })
+  For each parameter in the response:
+    If parameter.description mentions "setting" or "config":
+      → Cross-reference parameter.name with the rule's props in the workflow
+      → If the prop value looks like a setting name: add to extraction list
+    If parameter.name matches: settingName, setting, settingRef, configSetting:
+      → Extract the prop value from the workflow rule → add to extraction list
+```
+
+This catches rules that read settings internally but expose the setting name as a configurable parameter.
+
+### Common Rule Patterns That Depend on Settings
+
+| Rule Pattern | Prop That References Setting | What the Setting Contains |
+|---|---|---|
+| `SendWebhook` | `setting` or `webhookSettingName` | Webhook URL, headers, method |
+| `SendWebhookWithDynamicAttributes` | `setting` | Webhook URL + dynamic attribute mapping |
+| `UpdateEntityFromSetting` | `setting` | Entity field update mapping |
+| `GetSettingValue` | `settingName` | Arbitrary config value |
+| Any rule using `SettingUtils.getSettingByRef` | `setting` / `settingRef` | Rule-specific configuration |
+
+### Verification Query
+
+For each referenced setting name, query the platform to check if it exists:
+
+```graphql
+{
+  settings(first: 1, name: ["<SETTING_NAME>"], context: "RETAILER") {
+    edges {
+      node {
+        id
+        name
+        value
+        lobValue
+        valueType
+      }
+    }
+  }
+}
+```
+
+If the edges array is empty, the setting is **MISSING**.
+
+### Extended Validation (Beyond Existence)
+
+For each setting that exists, perform additional checks:
+
+```
+1. TYPE CHECK — Does the valueType match what the rule expects?
+   - Webhook rules (SendWebhook*) expect LOB → if setting is STRING, flag TYPE_MISMATCH
+   - Config rules (GetSettingValue) can accept STRING, BOOLEAN, or LOB
+   - Entity update rules (UpdateEntityFromSetting) expect LOB → flag if STRING
+
+2. CONTENT CHECK — Is the value meaningful?
+   - LOB webhook settings: lobValue must contain a "url" field → flag if missing
+   - STRING settings: value must be non-empty → flag EMPTY_VALUE if blank
+   - BOOLEAN settings: value must be "true" or "false" → flag INVALID_VALUE otherwise
+
+3. CONTEXT CHECK — Is the setting at the right scope?
+   - Custom rules (e.g., SendWebhookWithDynamicAttributes) typically resolve settings using cascading scope: RETAILER first, then ACCOUNT
+   - Module-installed settings often default to ACCOUNT scope (contextId=0)
+   - **Always use cascading scope resolution when auditing**: query RETAILER first; if empty, query ACCOUNT; report which scope the setting was found at
+   - If setting exists only at ACCOUNT scope, this is typically correct for module-installed settings — flag as INFO, not WRONG_CONTEXT
+   - Query at multiple contexts:
+     settings(name: ["<NAME>"], context: "RETAILER", contextId: <retailerId>)
+     settings(name: ["<NAME>"], context: "ACCOUNT", contextId: 0)
+```
+
+### Audit Report Format
+
+```
+=== Settings Audit: ORDER::HD (v1.50) ===
+
+Ruleset                    Rule                                Setting Name                 Status
+────────────────────────────────────────────────────────────────────────────────────────────────────
+OrderCreatedWebhook        *.SendWebhookWithDynamicAttributes  webhook.order.created        OK (LOB)
+OrderCancelledWebhook      *.SendWebhookWithDynamicAttributes  webhook.order.cancelled      OK (LOB)
+FulfilmentShippedWebhook   *.SendWebhookWithDynamicAttributes  webhook.fulfilment.shipped   MISSING       [HIGH]
+UpdateOrderFromWebhook     *.UpdateEntityFromSetting           order.update.mapping         MISSING       [HIGH]
+ConsignmentCreated         *.GetSettingValue                   consignment.prefix           OK (STRING)
+CarrierRouting             *.GetSettingValue                   carrier.hd.config            TYPE_MISMATCH [MED]
+  → Expected: LOB, Actual: STRING — rule reads lobValue which will be null
+
+Summary: 3/6 valid, 2 MISSING, 1 TYPE_MISMATCH
+Priority: 2 HIGH (silent failures), 1 MEDIUM (wrong type)
+```
+
+### Severity Classification
+
+| Status | Severity | Impact |
+|--------|----------|--------|
+| OK | None | Setting will be read correctly |
+| MISSING | HIGH | Rule will fail silently — entity gets stuck |
+| TYPE_MISMATCH | MEDIUM | Rule reads wrong field (e.g., `lobValue` is null for STRING type) |
+| EMPTY_VALUE | LOW | Setting exists but value is null/empty — behavior depends on rule |
+| WRONG_CONTEXT | MEDIUM | Setting exists at ACCOUNT but rule expects RETAILER scope |
+
+Flag every MISSING setting as HIGH priority. Missing settings cause rules to fail silently — the event processes as SUCCESS but the rule does nothing, leaving the entity stuck.
+
+### Phase 2B: Conformance Mode (Workflow + Runtime Evidence)
+
+Use this mode when you need more than existence checks. It compares:
+
+1. **Static contract**: setting refs extracted from workflow rule props
+2. **Live config**: settings currently stored in Fluent
+3. **Runtime evidence**: what was actually used during orchestration/webhook actions
+
+#### Conformance Statuses
+
+| Status | Meaning |
+|---|---|
+| `FOUND` | Setting exists with plausible value shape |
+| `MISSING` | Setting not found at expected context |
+| `EMPTY` | Setting exists but value/lobValue empty |
+| `INVALID_FORMAT` | Value exists but invalid shape (for example webhook LOB missing `url`) |
+| `CONTRACT_MISMATCH` | Runtime behavior conflicts with configured value (for example observed webhook endpoint differs from setting URL) |
+
+#### Runtime Cross-Check Pattern
+
+After extracting setting refs from the workflow:
+
+1. Query live setting values (`settings(... name: [...])`).
+2. Query orchestration audit for webhook actions on a target entity:
+   ```
+   event.list({
+     "eventType": "ORCHESTRATION_AUDIT",
+     "category": "ACTION",
+     "context.rootEntityRef": "<ENTITY_REF>",
+     "count": 100
+   })
+   ```
+3. Compare configured URL vs observed `Request Endpoint` in audit attributes.
+4. Emit `CONTRACT_MISMATCH` if they differ.
+
+#### Conformance Output Format
+
+```
+=== Settings Conformance: ORDER::MULTI ===
+
+Setting                               Referenced By                               Status               Evidence
+-------------------------------------------------------------------------------------------------------------------
+webhook.order.created                 ORDER.CREATE                                FOUND                id=365, valueType=LOB
+webhook.carrier.shipment.request      FULFILMENT.RequestShipment                  CONTRACT_MISMATCH    configured=https://x, observed=https://y
+update.fulfilment.confirmPick         FULFILMENT.ConfirmPick                      MISSING              no RETAILER setting found
+
+Summary: FOUND=1 MISSING=1 CONTRACT_MISMATCH=1
+```
+
+### Phase 2B: Value Format Validation
+
+Missing settings cause silent failures, but **wrong settings** are equally dangerous. A setting that exists but has the wrong `valueType`, malformed JSON, or a missing required field will also cause rules to fail silently. After confirming a setting exists, validate its value matches the expected format for the rule that references it.
+
+#### Webhook Setting Validation
+
+Settings referenced by `SendWebhook` or `SendWebhookWithDynamicAttributes` rules must meet all of the following:
+
+| Check | Expected | Severity |
+|-------|----------|----------|
+| `valueType` is `LOB` | Required — webhook config is always JSON | HIGH |
+| `lobValue` is valid JSON | Must parse without errors; must not be null or empty string | HIGH |
+| `lobValue` contains `url` field | String, well-formed URL (starts with `http://` or `https://`) | HIGH |
+| `url` uses HTTPS | HTTP URLs in non-dev environments are a security risk | WARN |
+| `url` is not empty | Empty string URL causes silent delivery failure | HIGH |
+| Optional: `headers` field | Object (key-value pairs) if present | INFO |
+| Optional: `method` field | String, typically `POST` (default if absent) | INFO |
+
+Example of a valid webhook setting value:
+
+```json
+{"url": "https://api.example.com/webhook/order-created", "headers": {"X-Api-Key": "key-123"}, "method": "POST"}
+```
+
+Common failures:
+- `valueType` is `STRING` instead of `LOB` — rule reads `lobValue` which returns null
+- `lobValue` is a stringified JSON (`"{\"url\":...}"`) instead of a parsed object — double-encoded
+- `url` field is missing entirely — webhook sends to null endpoint
+- `url` is placeholder (`https://example.com` or `TODO`) — webhook returns 404
+
+#### Entity Update Setting Validation
+
+Settings referenced by `UpdateEntityFromSetting` rules must meet:
+
+| Check | Expected | Severity |
+|-------|----------|----------|
+| `valueType` is `LOB` | Required — field mappings are JSON | HIGH |
+| `lobValue` is valid JSON | Must parse without errors | HIGH |
+| `lobValue` contains field mapping structure | Should have recognizable field names or mapping keys | WARN |
+| `lobValue` is not empty object `{}` | Empty mapping means rule does nothing | WARN |
+
+#### General Format Checks (All Settings)
+
+Apply these checks to every setting regardless of which rule references it:
+
+| valueType | Validation Rule | Severity |
+|-----------|----------------|----------|
+| `STRING` | `value` is non-empty (not null, not `""`) | WARN |
+| `LOB` | `lobValue` is valid JSON (not null, not empty string, not `"null"`) | HIGH |
+| `BOOLEAN` | `value` is exactly `"true"` or `"false"` (case-sensitive) | HIGH |
+| `INTEGER` | `value` is a numeric string (parseable as integer) | HIGH |
+| `JSON` | `lobValue` is valid JSON | HIGH |
+
+**valueType mismatch detection:** If a rule pattern expects LOB (e.g., `SendWebhook*`, `UpdateEntityFromSetting`) but the setting has `valueType: "STRING"`, flag as HIGH. The rule will read `lobValue` which returns null for STRING-type settings.
+
+#### Enhanced Audit Report Format
+
+When value validation is performed, extend the audit report with `valueType` and `Value Check` columns:
+
+```
+=== Settings Audit: ORDER::HD (v1.50) ===
+
+Ruleset                              Rule                                          Setting Name                    Status    valueType  Value Check
+──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+OrderCreatedWebhook                  ACCT.ext.SendWebhookWithDynamicAttributes     webhook.order.created           FOUND     LOB        OK (url=https://api.example.com/order/created)
+OrderCancelledWebhook                ACCT.ext.SendWebhookWithDynamicAttributes     webhook.order.cancelled         FOUND     LOB        WARN: url is HTTP not HTTPS
+FulfilmentShippedWebhook             ACCT.ext.SendWebhookWithDynamicAttributes     webhook.fulfilment.shipped      MISSING   -          -  [HIGH]
+UpdateOrderFromWebhook               ACCT.ext.UpdateEntityFromSetting              order.update.mapping            FOUND     STRING     ERROR: expected LOB for UpdateEntityFromSetting [HIGH]
+ConsignmentCreated                   ACCT.ext.GetSettingValue                      consignment.prefix              FOUND     STRING     OK (value="A_")
+FeatureFlagCheck                     ACCT.ext.GetSettingValue                      feature.express.enabled         FOUND     BOOLEAN    OK (value="true")
+
+Summary: 5/6 settings present, 1 MISSING
+Value issues: 1 ERROR (wrong valueType), 1 WARN (HTTP URL)
+Priority: 2 HIGH — missing setting + valueType mismatch will cause silent rule failures
+```
+
+#### Validation Query
+
+To validate values, the verification query from Phase 2 already returns `value`, `lobValue`, and `valueType`. After checking existence (edges not empty), apply format checks:
+
+```
+For each FOUND setting:
+  1. Read valueType, value, lobValue from query result
+  2. Apply general format checks for the valueType
+  3. If referenced by SendWebhook* rule:
+     - Verify valueType == "LOB"
+     - Parse lobValue as JSON
+     - Check for url field (non-empty, well-formed)
+     - Flag HTTP URLs in non-dev environments
+  4. If referenced by UpdateEntityFromSetting rule:
+     - Verify valueType == "LOB"
+     - Parse lobValue as JSON
+     - Check for non-empty mapping structure
+  5. Record: { settingName, valueType, valueCheck: "OK" | "WARN: ..." | "ERROR: ..." }
+```
+
+#### Cross-Reference with Connection Analysis
+
+When invoked from `/fluent-connection-analysis`, use the webhook/setting dependency inventory from the connection analysis as the extraction source instead of re-parsing the workflow JSON. The connection analysis already identifies which rules depend on which settings and classifies them by type (webhook, entity-update, general). Pass that inventory directly into Phase 2 + 2B to avoid duplicate parsing:
+
+```
+1. Receive dependency inventory from connection analysis:
+   [{ settingName, ruleType, ruleName, rulesetName }]
+2. Skip the extraction algorithm (Phase 2 step 1)
+3. Run existence check (Phase 2 verification query) for each setting
+4. Run value format validation (Phase 2B) for each FOUND setting
+5. Return combined audit report with Value Check column
+```
+
+## Phase 3: CRUD Operations
+
+### Schema Reference (from live introspection)
+
+Both `CreateSettingInput` and `UpdateSettingInput` use `context` (String) + `contextId` (Int) as **separate fields**:
+
+| Field | Create | Update | Type | Description |
+|-------|:------:|:------:|------|-------------|
+| `id` | — | **required** | `ID!` | Setting ID (query first to obtain) |
+| `name` | **required** | optional | `String!` / `String` | Setting reference key |
+| `valueType` | **required** | **required** | `String!` | `LOB`, `STRING`, `INTEGER`, `BOOLEAN`, or `JSON` |
+| `value` | optional | optional | `String` | Use for non-JSON values (STRING, INTEGER, BOOLEAN) |
+| `lobValue` | optional | optional | `Json` | Use for JSON values (LOB, JSON valueTypes). Pass as a JSON object, not a string |
+| `context` | **required** | **required** | `String!` | `RETAILER`, `ACCOUNT`, `AGENT`, or `CUSTOMER` |
+| `contextId` | **required** | **required** | `Int!` | ID of the context entity (e.g., retailer ID as integer) |
+
+**Key differences from what you might expect:**
+- `context` is a plain string (`"RETAILER"`), NOT `"RETAILER:2"` or `{ contextType: "RETAILER" }`
+- `contextId` is a separate **Int** field (e.g., `2`), not embedded in the context string
+- There is NO `retailer: { id }` field on settings — use `context` + `contextId` instead
+- `valueType` is **required even for updates** — you must always specify it
+- `lobValue` accepts a **Json object** on input (not a string) — pass `{"url": "..."}` not `"{\"url\": \"...\"}"`
+
+### Create Setting
+
+```graphql
+mutation($input: CreateSettingInput!) {
+  createSetting(input: $input) {
+    id
+    name
+    value
+    lobValue
+    context
+    contextId
+    valueType
+  }
+}
+```
+
+**Variables for a LOB setting (webhook config):**
+
+```json
+{
+  "input": {
+    "name": "fc.webhook.order.created",
+    "valueType": "LOB",
+    "lobValue": {"url": "https://api.example.com/webhook/order-created", "headers": {"X-Api-Key": "your-api-key"}, "method": "POST"},
+    "context": "RETAILER",
+    "contextId": 2
+  }
+}
+```
+
+**Variables for a STRING setting:**
+
+```json
+{
+  "input": {
+    "name": "consignment.prefix",
+    "valueType": "STRING",
+    "value": "A_",
+    "context": "RETAILER",
+    "contextId": 2
+  }
+}
+```
+
+**Variables for a BOOLEAN setting:**
+
+```json
+{
+  "input": {
+    "name": "GLOBAL_INVENTORY_ENABLED",
+    "valueType": "BOOLEAN",
+    "value": "true",
+    "context": "RETAILER",
+    "contextId": 2
+  }
+}
+```
+
+**Variables for an ACCOUNT-level setting:**
+
+```json
+{
+  "input": {
+    "name": "CANCELLATION_REASONS",
+    "valueType": "JSON",
+    "lobValue": {"active": [{"name": "Wrong Size", "value": "WRONGSIZE"}, {"name": "Broken", "value": "BROKEN"}]},
+    "context": "ACCOUNT",
+    "contextId": 0
+  }
+}
+```
+
+Note: Account-level settings use `contextId: 0`.
+
+### Update Setting
+
+Updates overwrite the value immediately. There is no versioning — the previous value is lost.
+
+**You must supply `id`, `valueType`, `context`, and `contextId` — all four are required for updates.**
+
+```graphql
+mutation($input: UpdateSettingInput!) {
+  updateSetting(input: $input) {
+    id
+    name
+    value
+    lobValue
+    context
+    contextId
+    valueType
+  }
+}
+```
+
+**Update a STRING value:**
+
+```json
+{
+  "input": {
+    "id": "368",
+    "valueType": "STRING",
+    "value": "new-value",
+    "context": "RETAILER",
+    "contextId": 2
+  }
+}
+```
+
+**Update a LOB value (e.g., change webhook URL):**
+
+```json
+{
+  "input": {
+    "id": "365",
+    "valueType": "LOB",
+    "lobValue": {"url": "https://updated-endpoint.com/webhook", "headers": {}, "method": "POST"},
+    "context": "RETAILER",
+    "contextId": 2
+  }
+}
+```
+
+**Important:** You need the setting `id` to update. Always query the setting by name first to get its ID:
+
+```graphql
+{
+  settings(first: 1, name: ["fc.webhook.order.created"]) {
+    edges { node { id name value lobValue valueType context contextId } }
+  }
+}
+```
+
+### Delete Setting
+
+Check `graphql.introspect` for `deleteSetting` availability — not all Fluent versions expose this mutation. If unavailable, update the value to an empty string or a known "disabled" marker.
+
+### Batch Create Settings
+
+Use `graphql.batchMutate` for creating multiple settings at once (up to 50 per batch):
+
+```json
+{
+  "mutation": "createSetting",
+  "inputs": [
+    {
+      "name": "fc.webhook.order.created",
+      "valueType": "LOB",
+      "lobValue": {"url": "https://api.example.com/order/created"},
+      "context": "RETAILER",
+      "contextId": 2
+    },
+    {
+      "name": "fc.webhook.order.cancelled",
+      "valueType": "LOB",
+      "lobValue": {"url": "https://api.example.com/order/cancelled"},
+      "context": "RETAILER",
+      "contextId": 2
+    },
+    {
+      "name": "consignment.prefix",
+      "valueType": "STRING",
+      "value": "A_",
+      "context": "RETAILER",
+      "contextId": 2
+    }
+  ],
+  "returnFields": ["id", "name", "value", "context", "contextId", "valueType"]
+}
+```
+
+### Batch Update Settings
+
+Use `graphql.batchMutate` with `updateSetting` for bulk updates. **All four required fields** (`id`, `valueType`, `context`, `contextId`) must be present on each input:
+
+```json
+{
+  "mutation": "updateSetting",
+  "inputs": [
+    {
+      "id": "365",
+      "valueType": "LOB",
+      "lobValue": {"url": "https://new-endpoint.com/order/created"},
+      "context": "RETAILER",
+      "contextId": 2
+    },
+    {
+      "id": "370",
+      "valueType": "STRING",
+      "value": "B_",
+      "context": "RETAILER",
+      "contextId": 2
+    }
+  ],
+  "returnFields": ["id", "name", "value", "context", "contextId", "valueType"]
+}
+```
+
+### Discover Exact Input Types
+
+Before creating settings, use `graphql.introspect` to discover the exact field requirements for your Fluent version:
+
+```
+graphql.introspect({ type: "CreateSettingInput" })
+graphql.introspect({ type: "UpdateSettingInput" })
+```
+
+Field names and required/optional status can vary across Fluent versions. Always introspect first if a mutation returns a schema error.
+
+## Phase 4: Common Settings Patterns
+
+Document of the most common Fluent settings and their expected value format:
+
+| Setting Pattern | Purpose | valueType | Example Value |
+|---|---|---|---|
+| `webhook.<entity>.<event>` | Webhook URL for SendWebhook rules | LOB | `{"url":"https://api.example.com/webhook","headers":{"X-Api-Key":"..."},"method":"POST"}` |
+| `carrier.<carrier_ref>.config` | Carrier integration config | LOB | `{"apiUrl":"...","apiKey":"...","serviceTypes":["EXPRESS","STANDARD"]}` |
+| `fulfilment.routing.config` | Sourcing/routing strategy | LOB | `{"strategy":"CLOSEST","maxDistance":50,"unit":"KM"}` |
+| `consignment.prefix` | Consignment reference prefix | STRING | `A_` |
+| `cancellation.reasons` | Valid cancellation reasons for UI (served via Transition API) | LOB | `["Out of stock","Customer request","Fraud","Duplicate"]` |
+| `notification.<type>` | Email/SMS notification template config | LOB | `{"templateId":"...","channel":"EMAIL","provider":"sendgrid"}` |
+| `buffer.time.<entity>` | Processing buffer times | LOB | `{"minutes":30}` |
+| `feature.<name>` | Feature flags | STRING | `true` or `false` |
+| `order.update.mapping` | Field mapping for UpdateEntityFromSetting rules | LOB | `{"fields":["status","attributes.customField"]}` |
+| `sourcing.radius` | Maximum distance for inventory sourcing | STRING | `50` |
+| `sourcing.strategy` | Inventory sourcing strategy | STRING | `CLOSEST` or `PRIORITY` |
+
+### HD Workflow Settings Template
+
+A typical Home Delivery workflow requires these settings (add `"context": "RETAILER", "contextId": <retailerId>` to each):
+
+```json
+[
+  { "name": "webhook.order.created", "valueType": "LOB", "lobValue": {"url": "https://api.example.com/order/created", "method": "POST"} },
+  { "name": "webhook.order.booked", "valueType": "LOB", "lobValue": {"url": "https://api.example.com/order/booked", "method": "POST"} },
+  { "name": "webhook.order.cancelled", "valueType": "LOB", "lobValue": {"url": "https://api.example.com/order/cancelled", "method": "POST"} },
+  { "name": "webhook.fulfilment.created", "valueType": "LOB", "lobValue": {"url": "https://api.example.com/fulfilment/created", "method": "POST"} },
+  { "name": "webhook.fulfilment.shipped", "valueType": "LOB", "lobValue": {"url": "https://api.example.com/fulfilment/shipped", "method": "POST"} },
+  { "name": "webhook.consignment.created", "valueType": "LOB", "lobValue": {"url": "https://api.example.com/consignment/created", "method": "POST"} },
+  { "name": "consignment.prefix", "valueType": "STRING", "value": "A_" },
+  { "name": "carrier.default.hd", "valueType": "STRING", "value": "STANDARD" }
+]
+```
+
+### CC Workflow Settings Template
+
+A typical Click & Collect workflow requires these settings (add `"context": "RETAILER", "contextId": <retailerId>` to each):
+
+```json
+[
+  { "name": "webhook.order.created", "valueType": "LOB", "lobValue": {"url": "https://api.example.com/order/created", "method": "POST"} },
+  { "name": "webhook.order.ready_for_pickup", "valueType": "LOB", "lobValue": {"url": "https://api.example.com/order/ready", "method": "POST"} },
+  { "name": "webhook.order.collected", "valueType": "LOB", "lobValue": {"url": "https://api.example.com/order/collected", "method": "POST"} }
+]
+```
+
+## Phase 5: Migration Between Environments
+
+Step-by-step process for migrating settings from one environment (e.g., dev) to another (e.g., staging or prod).
+
+### Step 1: Export from Source Environment
+
+Query all settings from the source environment:
+
+```
+graphql.queryAll({
+  query: "query($cursor: String) { settings(first: 100, after: $cursor, context: \"RETAILER\") { edges { cursor node { id name value valueType context contextId lobValue } } pageInfo { hasNextPage } } }",
+  variables: { cursor: null },
+  maxRecords: 5000
+})
+```
+
+Write the results to a JSON export file:
+
+```json
+{
+  "exportedFrom": "dev.sandbox.api.fluentretail.com",
+  "sourceRetailerId": 2,
+  "exportedOn": "2026-02-20T10:00:00Z",
+  "settingsCount": 42,
+  "settings": [
+    {
+      "name": "webhook.order.created",
+      "valueType": "LOB",
+      "lobValue": {"url": "https://dev-api.example.com/order/created"},
+      "context": "RETAILER",
+      "contextId": 2
+    },
+    {
+      "name": "consignment.prefix",
+      "valueType": "STRING",
+      "value": "A_",
+      "context": "RETAILER",
+      "contextId": 2
+    }
+  ]
+}
+```
+
+**Important:** Strip the `id` field from each setting — IDs are environment-specific and cannot be reused.
+
+### Step 2: Transform for Target Environment
+
+Update environment-specific values:
+
+1. Replace URLs: `dev-api.example.com` to `staging-api.example.com`
+2. Update `contextId` with target retailer ID: `2` to `5`
+3. Update any API keys, credentials, or endpoint-specific configuration
+4. Create a mapping file for repeatable migrations:
+
+```json
+{
+  "urlReplacements": {
+    "dev-api.example.com": "staging-api.example.com",
+    "dev.sandbox.api.fluentretail.com": "staging.sandbox.api.fluentretail.com"
+  },
+  "contextIdMapping": {
+    "2": 5
+  }
+}
+```
+
+### Step 3: Import to Target Environment
+
+For each setting in the export:
+
+1. **Check if it already exists** in the target:
+   ```graphql
+   {
+     settings(first: 1, name: ["<SETTING_NAME>"], context: "RETAILER") {
+       edges { node { id name } }
+     }
+   }
+   ```
+
+2. **If it does NOT exist** — create it:
+   ```
+   graphql.batchMutate with createSetting
+   ```
+
+3. **If it already exists** — update it:
+   ```
+   graphql.batchMutate with updateSetting (using the discovered id)
+   ```
+
+Use `graphql.batchMutate` with `createSetting` for bulk creation (up to 50 per batch):
+
+```json
+{
+  "mutation": "createSetting",
+  "inputs": [
+    {
+      "name": "webhook.order.created",
+      "valueType": "LOB",
+      "lobValue": {"url": "https://staging-api.example.com/order/created"},
+      "context": "RETAILER",
+      "contextId": 5
+    }
+  ],
+  "returnFields": ["id", "name", "value", "context", "contextId"]
+}
+```
+
+### Step 4: Verify Migration
+
+Query the target environment and compare:
+
+```
+1. graphql.queryAll to fetch all settings from target
+2. Compare setting names: source count vs target count
+3. Spot-check critical settings (webhooks, carrier configs) for correct values
+4. Report any settings that failed to create
+```
+
+### Step 5: Handle Conflicts
+
+If a setting already exists in the target and should be overwritten, use `updateSetting` with all required fields:
+
+```json
+{
+  "mutation": "updateSetting",
+  "inputs": [
+    { "id": "<existing_setting_id>", "valueType": "LOB", "lobValue": {"url": "https://new-endpoint.com"}, "context": "RETAILER", "contextId": 5 },
+    { "id": "<existing_setting_id>", "valueType": "STRING", "value": "new_value", "context": "RETAILER", "contextId": 5 }
+  ],
+  "returnFields": ["id", "name", "value", "context", "contextId"]
+}
+```
+
+## Webhook Delivery Monitoring
+
+After configuring webhook settings, verify delivery success using the event audit trail:
+
+```
+event.list({
+  "eventType": "ORCHESTRATION_AUDIT",
+  "category": "ACTION",
+  "name": "Send Webhook",
+  "context.rootEntityRef": "<ENTITY_REF>",
+  "count": 50
+})
+```
+
+Each result's attributes contain:
+- `Request Endpoint` — the URL the webhook was sent to
+- `Response code` — HTTP status code (200 = success, 4xx/5xx = failure)
+- `Response Body` — the response from the webhook receiver
+- `Response Headers` — response headers
+
+**Cross-reference with settings:** Compare the `Request Endpoint` attribute with the `url` field in the webhook setting to confirm the correct endpoint was used. Mismatches indicate the wrong setting was loaded.
+
+For full event query semantics → `/fluent-event-api` Pattern 7.
+
+## Phase 2C: Webhook Payload Reconstruction
+
+Reconstruct the full webhook payload that was sent to external systems by extracting dynamic attributes from ACTION "Send Webhook" audit events. This reveals exactly what data the external system received — useful when debugging webhook receiver failures or verifying integration contracts.
+
+### Data Source
+
+Query ORCHESTRATION_AUDIT events for webhook actions:
+
+```
+event.list({
+  "eventType": "ORCHESTRATION_AUDIT",
+  "context.rootEntityRef": "<ENTITY_REF>",
+  "count": 200
+})
+```
+
+Filter results where `name == "Send Webhook"`. Each webhook ACTION event contains:
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `Request Endpoint` | String | Target URL the webhook was sent to |
+| `Request Headers` | String | HTTP headers sent with the request |
+| `Response code` | String | HTTP status code from the receiver |
+| `Response Body` | String | Full response body |
+| `Response Headers` | String | Response headers from the receiver |
+| `Response reason` | String | HTTP status text |
+| *(dynamic attributes)* | Various | Rule-injected attributes representing the webhook payload data |
+
+### Dynamic Attribute Discovery
+
+`SendWebhookWithDynamicAttributes` rules inject entity data as additional attributes on the ACTION event. These attributes represent the data that was included in the webhook payload body. Common dynamic attributes include:
+
+```
+orderType, orderId, orderRef, orderStatus, orderCreatedOn
+fulfilmentId, fulfilmentRef, fulfilmentStatus, fulfilmentType
+eventName (the triggering event name)
+customerId, customerRef
+locationRef, locationName
+items (serialized item list)
+```
+
+The exact set of dynamic attributes depends on the rule's configuration and the entity type. To discover which attributes a specific webhook rule injects:
+
+1. **Static analysis**: Check the rule's props in the workflow JSON for `dynamicAttributes` or similar configuration
+2. **Runtime evidence**: Extract all non-standard attributes from the ACTION event (exclude `Request Endpoint`, `Request Headers`, `Response *` fields)
+3. **Plugin registry**: `plugin.list({ name: "SendWebhookWithDynamicAttributes" })` → check `parameters` for dynamic attribute configuration
+
+### Payload Reconstruction Algorithm
+
+```
+For each "Send Webhook" ACTION event:
+  1. Extract standard fields: Request Endpoint, Response code, Response Body
+  2. Extract dynamic attributes: all attributes NOT in the standard webhook field set
+  3. Group dynamic attributes by the originating ruleset (infer from causal chain or timing)
+  4. Reconstruct the payload:
+     - Standard webhook body = entity snapshot (if configured by the rule)
+     - Dynamic attributes = additional key-value pairs appended to the body
+  5. Compare with the webhook receiver's expected contract
+```
+
+### Reconstruction Report Format
+
+```
+=== Webhook Payload Reconstruction: ORDER ref=HD-20260222-001 ===
+
+Webhook #1: OrderCreatedWebhook
+  Endpoint: https://api.example.com/order/created
+  Method: POST (from setting lobValue)
+  Response: 200 OK
+
+  Reconstructed Payload:
+    orderType: HD
+    orderId: 143
+    orderRef: HD-20260222-001
+    orderStatus: CREATED
+    eventName: CREATE
+    customerId: 42
+    fulfilmentChoiceRef: FC-HD-20260222-001
+    sourceSystem: E2E_TEST
+
+  Setting: webhook.order.created
+  Setting URL: https://api.example.com/order/created
+  URL Match: YES
+
+---
+
+Webhook #2: FulfilmentShippedWebhook
+  Endpoint: https://api.example.com/fulfilment/shipped
+  Method: POST
+  Response: 404 Not Found
+
+  Reconstructed Payload:
+    orderType: HD
+    fulfilmentId: 201
+    fulfilmentRef: FUL-HD-001
+    fulfilmentStatus: SHIPPED
+    trackingNumber: E2E-TRACK-20260222
+    carrierRef: E2E-CARRIER
+    deliveredAt: (not present)
+
+  Setting: webhook.fulfilment.shipped
+  Setting URL: (MISSING — setting not found)
+  Diagnosis: Webhook sent to URL from stale cache or hardcoded fallback. Create the setting.
+```
+
+### Integration with Settings Audit
+
+Feed webhook payload reconstruction into the Phase 2 audit:
+
+1. **URL validation**: Compare `Request Endpoint` from runtime against `lobValue.url` from settings
+2. **Contract validation**: Compare dynamic attributes against the external system's expected payload schema (if documented)
+3. **Missing setting detection**: If a webhook fired but the corresponding setting is MISSING, the rule may have used a hardcoded fallback URL
+4. **Payload completeness**: Flag webhooks where expected dynamic attributes are missing (e.g., `trackingNumber` absent from a shipment webhook)
+
+### Use Cases
+
+- **Integration debugging**: When an external system reports "missing field X in webhook payload", check if the dynamic attribute was actually sent
+- **Contract documentation**: Generate a webhook payload contract from actual runtime data (more accurate than reading rule source)
+- **Environment comparison**: Compare webhook payloads between dev and prod to find configuration differences
+- **Compliance audit**: Verify that sensitive data (PII, payment info) is not leaked through webhook payloads
+
+## Troubleshooting
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| Rule executes but does nothing | Setting name in rule props does not match any setting | Run audit, create the missing setting |
+| `createSetting` returns schema error | Input field mismatch | Use `graphql.introspect({ type: "CreateSettingInput" })` to discover exact fields |
+| `updateSetting` returns validation error | Missing required fields — `valueType`, `context`, `contextId` are all required even for updates | Always include all four required fields: `id`, `valueType`, `context`, `contextId` |
+| Setting exists but rule still fails | `valueType` mismatch — rule expects LOB but setting is STRING | Check `valueType` and recreate with correct type |
+| Setting value is malformed JSON | `lobValue` contains invalid JSON | Validate JSON before saving; `lobValue` accepts a JSON object on input, not a string |
+| Webhook returns 401/403 | API key or auth header in setting is wrong or expired | Update the setting with fresh credentials |
+| Setting not found despite existing | Context mismatch — setting is ACCOUNT-scoped but rule queries RETAILER | Check context type; create at the correct scope |
+| Migration creates duplicates | Setting already existed in target | Query first, then use `updateSetting` for existing, `createSetting` for new |
+| `lobValue` is null but `value` has data | Setting was created as STRING but rule reads `lobValue` | Recreate with `valueType: "LOB"` |
+| `context: { contextType: "RETAILER" }` fails | `context` is a plain String, not an object | Use `context: "RETAILER"` (string) in queries; use `context: "RETAILER", contextId: 2` in mutations |
+
+## Integration with Other Skills
+
+| Task | Skill |
+|------|-------|
+| Analyze which workflow rules need settings | `/fluent-workflow-analyzer` |
+| Build workflow rulesets that reference settings | `/fluent-workflow-builder` |
+| Discover retailer config before creating settings | `/fluent-test-data` |
+| Deploy module containing rules that read settings | `/fluent-module-deploy` |
+| Run E2E test after settings are configured | `/fluent-e2e-test` |
+| Debug rule failures caused by missing settings | `/fluent-trace` |
+| Query user actions that source options from settings | `/fluent-transition-api` |
+
+## Tips
+
+- **Settings names are case-sensitive** — `webhook.Order.Created` and `webhook.order.created` are different settings
+- **`lobValue` vs `value`** — Use `LOB` for JSON objects, URLs, and any value longer than a few words. Use `STRING` for simple scalar values. If in doubt, use LOB.
+- **`lobValue` is a JSON object on input** — pass `{"url": "..."}` not `"{\"url\": \"...\"}"`. Fluent handles serialization.
+- **Settings do not have versions** — updates overwrite the value immediately with no rollback. Export before updating if you need a backup.
+- **Missing settings cause silent rule failures** — the event may process as SUCCESS but the rule skips its logic entirely. Always audit settings after deploying a new workflow.
+- **Use `graphql.introspect`** to discover exact `CreateSettingInput` and `UpdateSettingInput` fields before writing mutations. Field names can vary across Fluent versions.
+- **Update requires 4 fields** — `id`, `valueType`, `context`, `contextId` are all required even if you only want to change the value. Omitting any will cause a validation error.
+- **Transition API `source` field** references settings — when `source: "settings.cancellationReasons"` appears in a user action attribute, that means a setting named `cancellationReasons` (or similar) must exist for the dropdown to populate.
+- **Always query before creating** during migration — creating a setting with a name that already exists at the same context may fail or create a duplicate depending on the Fluent version.