@fluentcommerce/ai-skills 0.1.0

package/content/dev/skills/fluent-workflow-builder/SKILL.md

@@ -0,0 +1,319 @@
+---
+name: fluent-workflow-builder
+description: Create and edit Fluent Commerce workflow JSON definitions. Build rulesets, states, transitions, and triggers. Validate structure before upload. Triggers on "build workflow", "create workflow", "add ruleset", "edit workflow", "workflow json".
+user-invocable: true
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+argument-hint: <operation> [workflow-name]
+---
+
+# Workflow Builder
+
+Create, edit, and validate Fluent Commerce workflow JSON definitions.
+
+## Planning Gate
+
+**Before creating or modifying any workflow, write a plan using the template from `PLAN_TEMPLATE.md` in the `fluent-feature-plan` skill.** Every table row must carry a Source column (NEW/EXISTING/MODIFIED/REUSED/OOTB).
+
+**If this workflow change is part of a larger feature** (rules + settings + webhooks), use `/fluent-feature-plan` first. Then reference the approved plan during implementation.
+
+**Workflow-builder specific emphasis — ensure these are covered:**
+
+1. **Business Context (§1)** — what business flow this workflow enables or modifies
+2. **State machine (§3.1)** — Mermaid `stateDiagram-v2` with ALL statuses; annotate `:::added`, `:::removed`, `:::modified`. Validate syntax per `/fluent-mermaid-validate`
+3. **Cross-entity flow (§3.2)** — Mermaid `sequenceDiagram` for cross-entity event chains, webhooks, external systems. Validate syntax per `/fluent-mermaid-validate`
+4. **Before/After diff (§3.4)** — if modifying, show changes (or use `workflow.diff`)
+5. **Workflows (§4)** — every workflow created or modified with Source column and current version
+6. **Statuses (§5)** — new/modified statuses with Source column, entity type, which ruleset adds them
+7. **Rulesets (§6)** — rulesets with Source column, trigger event, from/to status, ordered rule list with NEW/OOTB/EXISTING annotations
+8. **Rules Inventory (§7)** — all rules with Source classification
+9. **Settings (§9)** — settings with Source column, context, value type, JSON example for NEW
+10. **Webhooks (§10)** — setting name, method, payload shape, trigger rule
+11. **Scheduled Events (§11)** — event name, delay, purpose
+12. **GraphQL Operations (§12)** — queries/mutations marked as NEW or REUSED pattern
+13. **Deployment Sequence (§17)** — modules before workflows that reference new rules
+
+**Write the plan to:** `accounts/<PROFILE>/plans/<YYYY-MM-DD>-workflow-builder-<slug>.md`. Set `Status: PENDING`.
+
+Present the full plan content to the user and wait for approval before writing any workflow JSON. 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 workflow structure/design guidance and validation checklists.
+
+Operational workflow commands are owned by `/fluent-workflow`:
+
+- `workflow list`
+- `workflow download`
+- `workflow merge`
+- `workflowlog` operations
+
+## Pre-Check: Load Source Analysis
+
+Before adding custom rules to a workflow, check if `/fluent-custom-code` analysis artifacts exist:
+
+```
+accounts/<PROFILE>/analysis/custom-code/workflow-rule-map.json
+accounts/<PROFILE>/analysis/custom-code/source-map.json
+accounts/<PROFILE>/analysis/custom-code/constraints.json
+```
+
+If found, use them to:
+- `source-map.json` → `modules[].rules[]` — available custom rules, their parameters, and entity types
+- `workflow-rule-map.json` → existing rule-to-workflow bindings (avoid duplicates)
+- `constraints.json` → extension constraints and risks
+
+If not found, fall back to workflow JSON analysis only. Treat artifact-gate failures the same as "not found" (for example missing required files, missing hashes, or blocking `missingSources` in `constraints.json`). Suggest running `/fluent-custom-code <PROFILE>` first when adding custom rules.
+
+## When to Use
+
+- Creating a new workflow from scratch
+- Adding rulesets or states to an existing workflow
+- Editing triggers, rules, or gate conditions
+- Validating workflow JSON before upload
+- Generating workflow fragments for merge operations
+
+## Workflow JSON Structure
+
+Every Fluent workflow follows this schema:
+
+```json
+{
+  "retailerId": "<retailer-id>",
+  "version": "<semver>",
+  "entityType": "ORDER | FULFILMENT | RETURN_ORDER | ARTICLE | WAVE | ...",
+  "entitySubtype": "<subtype matching workflow name after ::>",
+  "name": "<ENTITY_TYPE>::<SUBTYPE>",
+  "description": "<human-readable description>",
+  "versionComment": "<what changed in this version>",
+  "createdBy": "<retailer-ref>",
+  "rulesets": [ ... ],
+  "statuses": [ ... ]
+}
+```
+
+### Ruleset Structure
+
+```json
+{
+  "name": "<RulesetName>",
+  "description": "[<ENTITY_TYPE>] What this ruleset does",
+  "type": "<ENTITY_TYPE>",
+  "eventType": "NORMAL",
+  "rules": [
+    {
+      "name": "<ACCOUNT>.<MODULE>.<RuleName>",
+      "props": {
+        "key": "value"
+      }
+    }
+  ],
+  "triggers": [
+    { "status": "<STATUS>" }
+  ],
+  "userActions": []
+}
+```
+
+### Trigger Types
+
+Rulesets are triggered by one of:
+
+| Trigger | When it fires |
+|---------|---------------|
+| `{ "status": "CREATED" }` | Entity enters CREATED status (platform CREATE event) |
+| `{ "status": "ON_VALIDATION" }` | Entity enters ON_VALIDATION status |
+| No status trigger | Ruleset is triggered by a named event matching the ruleset name |
+
+**Convention:** If a ruleset has no `status` trigger, it fires when an event with `name` matching the ruleset name arrives. For example, ruleset `ConfirmValidation` fires on event `ConfirmValidation`.
+
+### Statuses Array
+
+```json
+{
+  "statuses": [
+    { "name": "CREATED", "category": "BOOKING", "entityType": "ORDER" },
+    { "name": "ON_VALIDATION", "category": "BOOKING", "entityType": "ORDER" },
+    { "name": "COMPLETE", "category": "DONE", "entityType": "ORDER" }
+  ]
+}
+```
+
+Categories: `BOOKING`, `FULFILMENT`, `DONE`, `PAYMENT`
+
+## Common Rule Patterns
+
+### Core Rules (provided by Fluent platform)
+
+| Rule | Props | Purpose |
+|------|-------|---------|
+| `<ACCOUNT>.core.SetState` | `status` | Transition entity to new status |
+| `<ACCOUNT>.core.SendEvent` | `eventName` | Fire a named event on current entity |
+| `<ACCOUNT>.core.SendEventOnVerifyingEntityStatus` | `eventName`, `statuses` (comma-separated) | Fire event only if entity is in one of the listed statuses |
+| `<ACCOUNT>.core.SendEventOnVerifyingAllFcStatus` | `eventName`, `statuses` (comma-separated) | Gate: fire event when ALL fulfilment choices reach one of the listed statuses |
+| `<ACCOUNT>.core.ScheduleEvent` | `eventName`, `delay` (seconds) | Schedule a delayed event |
+| `<ACCOUNT>.core.IfEventAttributeValueIsEqual` | `eventAttributeName`, `eventAttributeValue`, `eventName` | Conditional: fire event if attribute matches |
+
+### Extension Rules (from custom extension module)
+
+| Rule | Key Props | Purpose |
+|------|-----------|---------|
+| `<ACCOUNT>.<MODULE>.UpdateStatusHistory` | `toStatus` | Track status transition in attribute |
+| `<ACCOUNT>.<MODULE>.SendWebhookWithDynamicAttributes` | `setting` | Send webhook with config from Setting |
+| `<ACCOUNT>.<MODULE>.UpdateEntityFromSetting` | `setting` | Batch-update entity from event data via Setting |
+| `<ACCOUNT>.<MODULE>.CreateFulfilmentFromSourcingLocation` | *(from event attrs)* | Create fulfilment from sourcing data |
+| `<ACCOUNT>.<MODULE>.UpsertAttribute` | `attributeName`, `attributeType`, `attributeValue` | Set entity attribute |
+| `<ACCOUNT>.<MODULE>.UpsertAttributeFromPath` | `jsonpath`, `attributeName`, `attributeType` | Extract value via JSON path and set as attribute |
+
+## Plan Before Building
+
+**Before creating or editing any workflow, present an implementation plan to the user.** The plan should include:
+
+1. **State machine design** — All statuses and transitions, shown as a Mermaid `stateDiagram-v2`
+2. **Ruleset inventory** — Every ruleset with its trigger condition, rules, and purpose
+3. **Settings dependencies** — Any settings referenced by rules (webhook URLs, thresholds, feature flags)
+4. **Custom rule requirements** — Any new Java rules needed (entity type, parameters, behavior)
+5. **Cross-entity interactions** — How this workflow interacts with other entity workflows (e.g., ORDER → FULFILMENT)
+6. **Deployment sequence** — What gets deployed in what order
+
+For workflow edits, additionally show:
+- **Before/after diff** — What rulesets are being added, removed, or modified
+- **Before/after Mermaid diagrams** — Visual comparison of the state machine changes
+- **Risk assessment** — Impact of changes on existing live entities
+
+**Wait for user approval before making any changes to workflow JSON files.**
+
+## Building a New Workflow
+
+### Step 1: Determine entity type and subtype
+
+```
+Workflow name = <ENTITY_TYPE>::<SUBTYPE>
+Example: ORDER::HD, FULFILMENT::DEFAULT, RETURN_ORDER::DEFAULT
+```
+
+### Step 2: Design the state machine
+
+List all statuses and the events/rules that transition between them. Example:
+
+```
+CREATED → [CREATE ruleset] → ON_VALIDATION
+ON_VALIDATION → [ConfirmValidation event] → IN_PROGRESS
+IN_PROGRESS → [ConfirmShipment event] → SHIPPED
+SHIPPED → [ConfirmDelivery event] → COMPLETE
+```
+
+### Step 3: Build each ruleset
+
+For each transition, create a ruleset with:
+1. The rules to execute (in order — rules run sequentially)
+2. A trigger (status trigger for the first ruleset, event-name trigger for the rest)
+
+### Step 4: Add gate rulesets (if needed)
+
+Gates check child entity statuses before advancing parent. Example:
+
+```json
+{
+  "name": "NotifyFCComplete",
+  "description": "Gate: advance order when all FCs reach terminal status",
+  "type": "ORDER",
+  "eventType": "NORMAL",
+  "rules": [
+    {
+      "name": "ACCT.core.SendEventOnVerifyingAllFcStatus",
+      "props": {
+        "eventName": "SourceOrder",
+        "statuses": "ASSIGNED,CANCELLED,ESCALATED"
+      }
+    }
+  ],
+  "triggers": [],
+  "userActions": []
+}
+```
+
+### Step 5: Validate structure
+
+Before uploading, verify:
+- [ ] Every status referenced in triggers exists in the `statuses` array
+- [ ] Every `SetState` target status exists in the `statuses` array
+- [ ] Every `SendEvent` target has a matching ruleset name (or is handled elsewhere)
+- [ ] Rule names follow `<ACCOUNT>.<MODULE>.<RuleName>` format
+- [ ] No duplicate ruleset names
+- [ ] Version is bumped from previous
+
+## Editing an Existing Workflow
+
+### Get current workflow first
+
+Use `/fluent-workflow` for download/list operations, then apply this skill's structure and validation patterns.
+
+### Make changes
+
+Edit the JSON directly. Common operations:
+
+**Add a new ruleset:**
+```json
+{
+  "name": "NewRulesetName",
+  "description": "[ORDER] What it does",
+  "type": "ORDER",
+  "eventType": "NORMAL",
+  "rules": [ ... ],
+  "triggers": [ { "status": "IN_PROGRESS" } ],
+  "userActions": []
+}
+```
+
+**Add a rule to existing ruleset:**
+Find the ruleset in the `rulesets` array, append to its `rules` array.
+
+**Change a gate condition:**
+Find the gate ruleset, update the `statuses` prop value.
+
+### Upload/merge
+
+Use `/fluent-workflow-deploy` for uploading workflows to environments (MCP tool primary, REST API fallback). Use `/fluent-workflow` for listing, downloading, and merging workflows. Use `/fluent-module-deploy` for deploying full module bundles (JAR + settings + workflows together).
+
+**Important:** If the workflow references new custom rules, deploy the module first via `/fluent-module-deploy` before uploading the workflow. Unregistered rules cause NO_MATCH events at runtime.
+
+## Workflow Fragments
+
+Fragments are partial workflow definitions used with `fluent workflow merge`:
+
+```json
+{
+  "name": "my-customization",
+  "description": "Add custom validation step",
+  "rulesets": [
+    {
+      "name": "CustomValidation",
+      "description": "Custom validation ruleset",
+      "type": "ORDER",
+      "eventType": "NORMAL",
+      "rules": [ ... ],
+      "triggers": [ ... ],
+      "userActions": []
+    }
+  ],
+  "statuses": [
+    { "name": "CUSTOM_VALIDATING", "category": "BOOKING", "entityType": "ORDER" }
+  ]
+}
+```
+
+Merge adds the fragment's rulesets and statuses to the base workflow. Use this for modular customizations.
+
+## Validation Checklist
+
+Run through this before uploading any workflow:
+
+1. **JSON syntax** — Valid JSON (no trailing commas, correct brackets)
+2. **Required fields** — `retailerId`, `version`, `entityType`, `entitySubtype`, `name`, `rulesets`
+3. **Status coverage** — Every SetState target exists in `statuses`
+4. **Event coverage** — Every SendEvent target has a matching ruleset (or is expected inbound)
+5. **Trigger consistency** — Only one ruleset per status trigger (avoid conflicts)
+6. **Rule naming** — `<ACCOUNT>.<MODULE>.<RuleName>` format, all referenced rules exist in platform
+7. **Gate logic** — Gate statuses include all terminal states for child entities
+8. **Version bump** — Version is higher than currently deployed version
+9. **Description** — `versionComment` describes what changed

package/content/dev/skills/fluent-workflow-deploy/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: fluent-workflow-deploy
+description: Deploy Fluent Commerce workflows with validation, MCP tool primary strategy, and automatic REST API fallback. Handles pre-flight checks, upload, version verification, and rollback. Triggers on "deploy workflow", "upload workflow", "push workflow", "workflow deploy".
+user-invocable: true
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+argument-hint: <workflow-file> [--profile <name>] [--retailer <ref>] [--dry-run]
+---
+
+# Workflow Deployer
+
+Deploy Fluent Commerce workflow definitions with validation, multiple upload strategies, and automatic fallback.
+
+## Planning Gate
+
+**Before deploying any workflow, write a plan using the template from `PLAN_TEMPLATE.md` in the `fluent-feature-plan` skill.**
+
+**Workflow-deploy specific emphasis -- ensure these are covered:**
+
+1. **Business Context (Section 1)** -- what change this workflow update delivers
+2. **Scope (Section 2)** -- workflow name (e.g., `ORDER::HD`), current version -> new version
+3. **Rulesets (Section 6)** -- new/modified/removed rulesets with Source classification
+4. **Rules Inventory (Section 7)** -- confirm all referenced rules exist in `plugin.list`
+5. **Deployment Sequence (Section 17)** -- module deploy BEFORE workflow deploy if new custom rules are referenced
+6. **Rollback Plan (Section 18)** -- previous workflow version to restore
+
+**Write the plan to:** `accounts/<PROFILE>/plans/<YYYY-MM-DD>-workflow-deploy-<slug>.md`. Set `Status: PENDING`.
+
+Present the full plan content to the user and wait for approval before uploading. 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 the deployment execution pipeline (validate -> upload -> verify -> rollback).
+
+Workflow structure and editing are owned by `/fluent-workflow-builder`.
+Workflow listing and download are owned by `/fluent-workflow`.
+Workflow analysis is owned by `/fluent-workflow-analyzer`.
+
+## Module-First Deployment — Check Before Using This Skill
+
+**If the workflow is part of a module** (exists in `resources/workflows/` within a module directory), deploy the entire module via `/fluent-module-deploy` using `fluent module install` instead. Module install deploys workflows, settings, and rules as a single atomic unit with proper versioning.
+
+**Use this skill only for standalone workflow uploads** — workflows not bundled in a module, hotfixes to individual workflows, or when module install is not applicable.
+
+| Scenario | Correct Approach |
+|----------|-----------------|
+| Workflow is in `resources/workflows/` of a module | `/fluent-module-deploy` → `fluent module install` |
+| Workflow changed along with Java rules | `/fluent-build` → `/fluent-module-deploy` (module bundles everything) |
+| Standalone workflow JSON not in any module | This skill (`/fluent-workflow-deploy`) |
+| Hotfix to a single workflow in production | This skill (targeted upload) |
+| Module install excluded workflows (`--exclude workflows`) | This skill (deploy workflows separately) |
+
+## When to Use
+
+- Uploading a standalone workflow definition not bundled in a module
+- Deploying after `fluent workflow merge` fails to upload (known `token:undefined` bug)
+- Deploying workflows excluded during module install (`--exclude workflows`)
+- Automating workflow deployment in CI/CD pipelines
+- Rolling back to a previous workflow version
+
+## Deployment Pipeline
+
+### Step 0: Verify CLI Available
+
+```bash
+fluent --version
+```
+
+If CLI is not found, warn the user. The CLI is needed for verification (workflow list/download) but not strictly required for upload -- the MCP `workflow.upload` tool and REST API work independently.
+
+### Step 1: Pre-flight Checks
+
+Before uploading, validate:
+
+1. **Read the workflow JSON file** -- confirm it parses as valid JSON
+2. **Verify required fields:** `name`, `retailerId`, `rulesets`, `statuses`
+3. **Query current deployed version:**
+   ```bash
+   fluent workflow list -p <profile> -r <retailer>
+   ```
+4. **Confirm new version > current version** (warn if same/lower)
+5. **Validate JSON structure** (use `/fluent-workflow-builder` validation checklist)
+6. **Check rule references** -- every rule in `rulesets[].rules[].name` should exist in `plugin.list`. If any are missing, **STOP** and advise deploying the module first.
+
+### Step 1.5: Check Pre-Deploy Report (if available)
+
+Read the pre-deploy checklist report if it exists:
+
+```
+accounts/<PROFILE>/analysis/pre-deploy/<MODULE>-<VERSION>.checklist.json
+```
+
+If found and `overallResult == "BLOCKED"`, warn the user and list the blocking gates. Do not proceed without explicit user confirmation.
+
+### Step 2: Upload (Strategy Selection)
+
+Try upload strategies in order:
+
+#### Strategy 1 (Primary): MCP `workflow.upload` Tool
+
+The `workflow.upload` MCP tool has built-in structure validation and supports dry-run mode:
+
+```
+workflow.upload({
+  workflow: <workflow-json-object>,
+  dryRun: true,     // Validate without deploying
+  validate: true    // Run structure checks
+})
+```
+
+1. First run with `dryRun: true` to validate
+2. If validation passes, run with `dryRun: false` to deploy
+3. Response includes the new version number
+
+**Advantages:** Built-in validation, dryRun mode, no manual auth handling.
+
+**When this fails:** MCP server not configured, connection issues, or MCP tool returns error.
+
+#### Strategy 2 (Fallback): REST API Direct Upload
+
+If MCP tool is unavailable, use the REST API directly:
+
+```bash
+# Extract credentials from CLI profile
+PROFILE_DIR="$HOME/.fluentcommerce/<profile>"
+BASE_URL=$(python3 -c "import json; print(json.load(open('$PROFILE_DIR/profile.json'))['baseUrl'])")
+CLIENT_SECRET=$(python3 -c "import json; print(json.load(open('$PROFILE_DIR/profile.json'))['clientSecret'])")
+ACCOUNT_ID=$(python3 -c "import json; print(json.load(open('$PROFILE_DIR/profile.json'))['id'])")
+
+# Get retailer credentials
+RETAILER_FILE="$PROFILE_DIR/retailer.<retailer-ref>.json"
+USERNAME=$(python3 -c "import json; d=json.load(open('$RETAILER_FILE')); print(d['defaultUser']['username'])")
+PASSWORD=$(python3 -c "import json; d=json.load(open('$RETAILER_FILE')); print(d['defaultUser']['password'])")
+
+# Authenticate (retailer-scoped token required -- account-level tokens return 403)
+TOKEN=$(curl -s -X POST "$BASE_URL/oauth/token" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "username=$USERNAME&password=$PASSWORD&client_id=$ACCOUNT_ID&client_secret=$CLIENT_SECRET&grant_type=password&scope=api" \
+  | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")
+
+# Upload
+curl -s -X PUT "$BASE_URL/api/v4.1/workflow" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "fluent.account: $ACCOUNT_ID" \
+  -d @<workflow-file>
+```
+
+**Success response:**
+```json
+{
+  "entityId": "2-ORDER::HD::1.51",
+  "eventStatus": "COMPLETE"
+}
+```
+
+**Error responses:**
+
+| HTTP Code | Cause | Fix |
+|-----------|-------|-----|
+| 401 | Token expired or invalid | Re-authenticate |
+| 403 | Account-level token, not retailer-scoped | Use retailer user credentials |
+| 400 | Invalid workflow JSON | Check structure with `/fluent-workflow-builder` |
+| 409 | Version conflict | Bump version number |
+| 500 | Server error | Retry after 5 seconds |
+
+#### Strategy 3 (Last Resort): CLI `fluent workflow merge`
+
+```bash
+fluent workflow merge <fragment-or-workflow> <workflow-name> \
+  -p <profile> -r <retailer>
+```
+
+Known issue: The CLI authenticates for the merge but not for the upload step, resulting in `token:undefined`. When this happens, the merged file is still written locally as `<filename>.merged.json`. Proceed to Strategy 2 with the merged file.
+
+### Step 3: Verify Deployment
+
+```bash
+fluent workflow list -p <profile> -r <retailer>
+```
+
+Confirm the version number matches the uploaded version.
+
+Additionally, download and diff to confirm content:
+
+```bash
+fluent workflow download -p <profile> -r <retailer> -w <name> -o /tmp/
+```
+
+Compare ruleset count and status count between uploaded and downloaded versions.
+
+### Step 4: Post-Deploy Validation (Optional)
+
+Send a test event to verify the workflow processes correctly:
+
+1. Find or create a test entity in a suitable status
+2. `event.build` -- preview the test event payload
+3. `event.send` (dryRun: true) -- validate without sending
+4. `event.send` (dryRun: false) -- send real event
+5. `event.list` -- confirm event processed (eventStatus: COMPLETE/SUCCESS)
+6. `graphql.query` -- verify entity status changed as expected
+
+Use `/fluent-e2e-test` for comprehensive post-deploy testing.
+
+## Module Dependency Check
+
+**Critical:** If the workflow references custom rules (rules with `<ACCOUNT>.<context>.<RuleName>` pattern rather than `FLUENTRETAIL.*`), verify the module containing those rules is deployed:
+
+```
+plugin.list({ name: "<RuleName>" })
+```
+
+If any referenced rule is not found in the registry, the module must be deployed first via `/fluent-module-deploy`. Deploying a workflow that references unregistered rules causes NO_MATCH events at runtime.
+
+**Recommended deployment order:**
+1. Deploy module (registers rules) -- `/fluent-module-deploy`
+2. Deploy workflows (references rules) -- `/fluent-workflow-deploy`
+3. Create/update settings (referenced by rules) -- `/fluent-settings`
+4. Run E2E test -- `/fluent-e2e-test`
+
+## Dry Run Mode
+
+With `--dry-run`, the deployer performs all steps except the actual upload:
+
+```
+1. Parse and validate workflow JSON         done
+2. Check current deployed version           done
+3. Verify version bump                      done
+4. Check rule references exist              done
+5. Upload workflow                          SKIPPED
+6. Report what WOULD be deployed
+```
+
+## Rollback
+
+To rollback to a previous version:
+
+1. Download the previous version:
+   ```bash
+   fluent workflow download -p <profile> -r <retailer> -w <name> -o /tmp/
+   ```
+
+2. Edit the downloaded JSON to bump the version number (must be higher than current)
+3. Upload via MCP tool or REST API
+
+Note: Fluent does not support downgrading version numbers. To "rollback," you upload the old content with a new (higher) version number.
+
+## Integration with Other Skills
+
+| Task | Skill |
+|------|-------|
+| Analyze workflow before deploying | `/fluent-workflow-analyzer` |
+| Edit workflow JSON | `/fluent-workflow-builder` |
+| Download current workflow | `/fluent-workflow` |
+| Deploy module (rules must exist first) | `/fluent-module-deploy` |
+| Pre-deployment validation | `/fluent-pre-deploy-check` |
+| Test after deployment | `/fluent-e2e-test` |
+| Debug deployment failures | `/fluent-trace` |
+
+## Tips
+
+- **Always backup the current version** before deploying -- download with `fluent workflow download`
+- **Version must always increase** -- Fluent rejects same or lower version numbers
+- **Use retailer-scoped tokens** for REST API -- Account-level tokens get 403 on workflow API
+- **Check the `eventStatus`** in the upload response -- `COMPLETE` means success
+- **The `entityId` in the response** follows format `<retailerId>-<workflowName>::<version>`
+- **Deploy module before workflow** if the workflow references new custom rules
+- **Windows users**: Use `--json` flag for download to avoid `::` filename issues

package/content/mcp-extn/agents/fluent-mcp.md

@@ -0,0 +1,69 @@
+---
+name: fluent-mcp
+description: Fluent Commerce MCP extension agent. Provides intelligent assistance for event dispatch, transition actions, GraphQL queries, batch ingestion, and webhook validation via the Fluent MCP server. Triggers on "fluent mcp", "send event", "graphql query", "batch ingestion".
+tools: Bash, Read, Write, Edit, Glob, Grep
+model: inherit
+skills: fluent-mcp-tools
+---
+
+# Fluent MCP Extension Agent
+
+You are a Fluent Commerce MCP specialist. You help users with MCP server operations including event dispatch, transition actions, GraphQL queries, batch ingestion, and webhook validation.
+
+## Capabilities
+
+- **Event Dispatch**: Build, validate, and send events via the Fluent Event API
+- **Orchestration**: Query user actions/transitions and list registered rules with metadata
+- **GraphQL Operations**: Execute queries and mutations, auto-paginate, batch mutate
+- **Batch Ingestion**: Create batch jobs, send records, check status, get results
+- **Webhook Validation**: Validate webhook payloads and verify signatures
+- **Schema Introspection**: Discover mutations, input types, and field requirements
+
+## Authentication
+
+Auth strategy priority (first valid method wins):
+
+1. **Profile** — `FLUENT_PROFILE` (recommended). Uses SDK `createClientFromProfile()` for automatic credential and retailer resolution.
+2. **OAuth** — `FLUENT_CLIENT_ID` + `FLUENT_CLIENT_SECRET` (+ optional `FLUENT_USERNAME`/`FLUENT_PASSWORD`)
+3. **Token Command** — `TOKEN_COMMAND` (vault/secret manager integration with auto-refresh)
+4. **Static Token** — `FLUENT_ACCESS_TOKEN` (dev fallback, no refresh)
+
+## Key Behaviors
+
+1. **Always validate config** before operations: use `config.validate` tool
+2. **Use dry-run first** for events: `event.send` with `dryRun: true`
+3. **Prefer `graphql.queryAll`** when fetching all records (auto-pagination)
+4. **Use `graphql.batchMutate`** for bulk updates (up to 50 per request)
+
+## Available MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| `config.validate` | Check auth/base URL/retailer config |
+| `health.ping` | Quick connectivity diagnostics |
+| `connection.test` | Full auth + me query verification |
+| `event.build` | Build event payload (no send) |
+| `event.send` | Send event (supports dryRun) |
+| `event.list` | List/filter events |
+| `event.get` | Fetch single event by ID |
+| `workflow.transitions` | Query available user actions/transitions at any state |
+| `plugin.list` | List registered rules with metadata (supports name filter) |
+| `graphql.query` | Execute single GraphQL query/mutation |
+| `graphql.queryAll` | Auto-paginated query (all records) |
+| `graphql.batchMutate` | Batch mutations (up to 50) |
+| `graphql.introspect` | Schema introspection |
+| `batch.create` | Create batch ingestion job |
+| `batch.send` | Send records to batch job |
+| `batch.status` | Check batch job status |
+| `batch.results` | Get batch job results |
+| `webhook.validate` | Validate webhook payload/signature |
+
+## Cross-References for Event Questions
+
+If a user asks about **event model semantics** (types, categories, statuses, causality, execution model), redirect to `/fluent-event-api`.
+
+If a user asks **why an event failed** or needs **diagnostic help**, redirect to `/fluent-trace`.
+
+If a user asks about **event volume analytics** or **failure rate monitoring**, redirect to `/fluent-system-monitoring`.
+
+This agent owns MCP tool syntax and payload contracts. Event model knowledge and diagnostic logic are owned by the dev skills above.