@fluentcommerce/ai-skills 0.1.0 → 0.3.0

package/docs/USE_CASES.md

@@ -4,32 +4,191 @@ A scenario-based guide to everything your AI assistant can do after installing `
 
 > **Prerequisites:** Skills installed (`npx @fluentcommerce/ai-skills install`), MCP servers configured (`mcp-setup --profile YOUR_PROFILE`), and workspace connected (`/fluent-connect`).
 
+> **New here?** Start with the [Getting Started Guide](GETTING_STARTED.md) for a step-by-step walkthrough before diving into specific scenarios.
+
 ---
 
 ## Quick Reference: "I want to..."
 
 | I want to... | Say this | Skill |
 |---|---|---|
+| Connect to a Fluent account | "Set up my workspace" | `/fluent-connect` |
+| Create or switch CLI profiles | "Create a profile for production" | `/fluent-profile` |
 | Understand how a feature works | "Explain how Home Delivery works" | `/fluent-feature-explain` |
+| Gather requirements for a feature | "Help me define use cases for curbside pickup" | `/fluent-use-case-discover` |
+| Plan a multi-artifact feature | "Plan the curbside pickup feature" | `/fluent-feature-plan` |
 | Debug why an order is stuck | "Why is order HD-001 stuck in BOOKED?" | `/fluent-trace` |
-| Build a new workflow from scratch | "Build an ORDER::RETURNS workflow" | `/fluent-workflow-builder` |
+| Build a new workflow from scratch | "Build an ORDER::RETURN workflow" | `/fluent-workflow-builder` |
+| Analyze workflow structure | "Analyze ORDER::HD for orphaned rulesets" | `/fluent-workflow-analyzer` |
+| Map cross-entity dependencies | "Show me how ORDER::HD connects to FULFILMENT workflows" | `/fluent-connection-analysis` |
+| Scaffold a new Java rule | "Create a rule called ValidateReturnWindow" | `/fluent-rule-scaffold` |
+| Create a new extension module | "Scaffold a new module called hm-returns" | `/fluent-module-scaffold` |
+| Create a data-only module | "Create a data module for reference data" | `/fluent-data-module-scaffold` |
+| Onboard existing source into module format | "Refactor this code into a Fluent module" | `/fluent-source-onboard` |
+| Check module health | "What modules are deployed? Are they valid?" | `/fluent-module-validate` |
+| Analyze custom plugin source | "Analyze the custom code for this account" | `/fluent-custom-code` |
+| Build and package a module | "Build the hm-extensions module" | `/fluent-build` |
+| Bump module version | "Bump the module version to 1.4.0" | `/fluent-version-manage` |
+| Run quality gates before deploying | "Run pre-deploy checks for hm-extensions" | `/fluent-pre-deploy-check` |
+| Deploy a module | "Deploy my extension module to HM_TEST" | `/fluent-module-deploy` |
+| Deploy a workflow | "Deploy ORDER::HD to HM_TEST" | `/fluent-workflow-deploy` |
 | Run an end-to-end test | "Run an E2E test of the HD order flow" | `/fluent-e2e-test` |
-| Check if we're ready for go-live | "Run an RFL assessment" | `/fluent-rfl-assess` |
 | Create test data | "Create a test HD order" | `/fluent-test-data` |
-| Scaffold a new Java rule | "Create a new rule called ValidateReturnWindow" | `/fluent-rule-scaffold` |
-| Deploy a module | "Deploy my extension module to HM_TEST" | `/fluent-module-deploy` |
+| Check if we're ready for go-live | "Run an RFL assessment" | `/fluent-rfl-assess` |
 | Audit settings | "What settings are missing for ORDER::HD?" | `/fluent-settings` |
+| Create a location or network | "Set up a warehouse location for testing" | `/fluent-retailer-config` |
 | Monitor event health | "Show me event failure rates for the last hour" | `/fluent-system-monitoring` |
-| Set up a new account | "Bootstrap a new Fluent account" | `/fluent-bootstrap` |
-| Analyze workflow structure | "Analyze ORDER::HD for orphaned rulesets" | `/fluent-workflow-analyzer` |
 | See what actions are available | "What actions can I take on an ORDER in BOOKED status?" | `/fluent-transition-api` |
 | Understand the event model | "How does event routing work in Fluent?" | `/fluent-event-api` |
-| Create a location or network | "Set up a warehouse location for testing" | `/fluent-retailer-config` |
-| Check module health | "What modules are deployed? Are they valid?" | `/fluent-module-validate` |
-| Plan a multi-artifact feature | "Plan the curbside pickup feature" | `/fluent-feature-plan` |
-| Onboard existing source into module format | "Refactor this code into a Fluent module" | `/fluent-source-onboard` |
-| Deploy a workflow to an environment | "Deploy the updated ORDER::HD workflow" | `/fluent-workflow-deploy` |
-| Create a data-only module (no Java) | "Scaffold a data module for locations and settings" | `/fluent-data-module-scaffold` |
+| Batch ingest data | "Create a batch ingestion job for inventory positions" | `/fluent-job-batch` |
+| Set up a new account | "Bootstrap a new Fluent account" | `/fluent-bootstrap` |
+| Decompose a scope document | "Break this scope doc into tasks with dependencies" | `/fluent-scope-decompose` |
+| Understand sourcing configuration | "How does sourcing work? What criteria are available?" | `/fluent-sourcing` |
+| Configure a sourcing profile | "Create an HD sourcing profile with distance + stock criteria" | `/fluent-sourcing` |
+| Debug sourcing decisions | "Why was this location selected for the order?" | `/fluent-sourcing` → `/fluent-trace` |
+| Audit what skills and tools ran | "What skills ran this session? Show the decision chain" | `/fluent-session-summary` |
+| Export audit trail for CI/CD | "Export a JSON audit trail with full provenance" | `/fluent-session-audit-export` |
+| Map what's been built on an account | "What has been built here? Give me a feature inventory" | `/fluent-implementation-map` |
+| Check feature status dashboard | "What features are in progress? Show the dashboard" | `/fluent-feature-status` |
+| Archive a completed feature | "Archive the return-order feature" | `/fluent-archive` |
+| Roll back a deployment | "Roll back ORDER::HD to the previous version" | `/fluent-rollback` |
+| See the workspace structure | "Show me the workspace tree" | `/fluent-workspace-tree` |
+| Build a Mystique UI page | "Build an order detail page" | `/fluent-mystique-builder` |
+| Validate a manifest before deploying | "Validate the admin manifest" | `/fluent-mystique-validate` |
+| Scaffold a custom SDK component | "Create a custom order tracker component" | `/fluent-mystique-scaffold` |
+| Analyze an existing manifest | "What components are used in the admin app?" | `/fluent-mystique-analyze` |
+| Build a full-stack feature (backend + UI) | "Build order tracking with a dashboard" | `/fluent-feature-plan` → backend → frontend |
+
+---
+
+## How It Works: The Feature Lifecycle
+
+When you build a feature with AI Skills, artifacts are organized in a predictable structure under your `accounts/<PROFILE>/` directory. This section explains what gets created, where it goes, and how the AI tracks progress across sessions.
+
+### The Feature Directory
+
+Every feature gets its own directory at `accounts/<PROFILE>/features/<slug>/` with up to four files:
+
+```
+features/
+  return-order/
+    status.json        ← lifecycle tracker (always present, created first)
+    spec.md            ← business requirements (from /fluent-use-case-discover)
+    plan.md            ← implementation plan (from /fluent-feature-plan)
+    architecture.md    ← reverse-engineered docs (from /fluent-feature-explain)
+```
+
+The **slug** is a short kebab-case name (e.g., `return-order`, `curbside-pickup`). Set once by the first skill that creates the directory. Not all files are always present — `spec.md` only exists if you ran requirements gathering, `architecture.md` only exists if you ran feature explain.
+
+### status.json — How the AI Tracks Progress
+
+Every feature directory has a `status.json` that the AI reads to know where you left off:
+
+```json
+{
+  "$schema": "feature-status-v1",
+  "feature": "return-order",
+  "retailer": "HM_TEST",
+  "status": "PLANNING",
+  "spec": "APPROVED",
+  "plan": "PENDING",
+  "planRevision": null,
+  "architecture": false,
+  "next": "/fluent-feature-plan"
+}
+```
+
+**What the fields mean:**
+
+| Field | What it tells the AI |
+|-------|---------------------|
+| `status` | Overall progress: `DISCOVERY` → `PLANNING` → `APPROVED` → `IN_PROGRESS` → `VERIFIED` → `ARCHIVED` |
+| `spec` | Business spec state: `null` → `DRAFT` → `APPROVED` |
+| `plan` | Implementation plan state: `null` → `PENDING` → `APPROVED` |
+| `architecture` | Whether a feature architecture doc exists (`true`/`false`) |
+| `next` | Which skill to run next — the AI reads this to continue automatically |
+| `planRevision` | How many times the plan has been revised (increments on changes) |
+
+**Why this matters to you:** If you close your IDE and come back tomorrow, the AI checks `status.json` and picks up exactly where you left off. You don't need to re-explain context.
+
+### What Gets Created at Each Step
+
+Here's the full lifecycle — what you say, what the AI does, and what appears on disk:
+
+| Step | You say | Skill | Artifact created | Where |
+|------|---------|-------|-----------------|-------|
+| 1 | "Define use cases for return orders" | `/fluent-use-case-discover` | Business Spec | `features/return-order/spec.md` |
+| 2 | "Plan the return order feature" | `/fluent-feature-plan` | 18-section plan with diagrams | `features/return-order/plan.md` |
+| 3 | *(you review and say "approved")* | — | status.json updated | `plan: "APPROVED"` |
+| 4 | "Scaffold the module" | `/fluent-module-scaffold` | Maven project skeleton | `SOURCE/fc-module-hm-returns/` |
+| 5 | "Create the rules from the plan" | `/fluent-rule-scaffold` | Java classes + tests | `SOURCE/.../src/main/java/...` |
+| 6 | "Build the workflow from the plan" | `/fluent-workflow-builder` | Workflow JSON | `workflows/HM_TEST/RETURN_ORDER__DEFAULT.json` |
+| 7 | "Build the module" | `/fluent-build` | Compiled ZIP | `SOURCE/.../dist/fc-module-hm-returns-1.0.0.zip` |
+| 8 | "Run pre-deploy checks" | `/fluent-pre-deploy-check` | Readiness report | `reports/pre-deploy/...` |
+| 9 | "Deploy to HM_TEST" | `/fluent-module-deploy` | *(deployed remotely)* | Module + workflow installed on Fluent |
+| 10 | "Run E2E test" | `/fluent-e2e-test` | Test results | Pass/fail per step in the plan's test plan |
+
+### The Approval Gate
+
+The AI never makes changes without asking. Here's how approval works:
+
+1. **Plan is presented** — full markdown with architecture diagrams, rules inventory, risk assessment, deployment steps, test plan
+2. **You review** — ask questions ("what does rule X do?"), request changes ("add error handling for empty carts"), or reject ("wrong approach")
+3. **You approve** — say "yes", "approved", "go ahead", or "do it"
+4. **Implementation begins** — the AI follows the approved plan step by step
+
+You can also say **"just do it"** to skip the approval gate entirely (logged as auto-skip).
+
+### Your Workspace After a Full Feature Build
+
+After completing all steps for a return order feature, your directory looks like this:
+
+```
+accounts/HMDEV/
+  features/
+    return-order/
+      status.json                                    ← status: VERIFIED
+      spec.md                                        ← business requirements
+      plan.md                                        ← approved implementation plan
+  SOURCE/
+    fc-module-hm-returns/
+      resources/module.json                          ← rule registrations
+      plugins/rules/hm-returns/
+        src/main/java/.../ValidateReturnWindow.java  ← scaffolded rule
+        src/test/java/.../ValidateReturnWindowTest.java
+      dist/fc-module-hm-returns-1.0.0.zip            ← built module
+  workflows/
+    HM_TEST/
+      RETURN_ORDER__DEFAULT.json                     ← workflow definition
+      workflow-context.json                          ← download metadata
+  reports/
+    module-validate/hm-returns.report.json           ← validation report
+  analysis/
+    code/source-map.json                             ← rule-to-file mapping
+```
+
+### Non-Feature Tasks
+
+Not everything is a "feature." One-off tasks (single rule scaffold, quick workflow edit, settings change) use `tasks/` instead:
+
+```
+accounts/HMDEV/
+  tasks/
+    2026-02-24-rule-scaffold-cancel-order.md
+    2026-02-24-settings-webhook-urls.md
+```
+
+These are standalone plan files — no `status.json`, no lifecycle tracking. They're for work that doesn't span multiple artifact types.
+
+### Reading an Existing Feature (No Plan Needed)
+
+If you want to **understand** a feature rather than **build** one, the AI produces an architecture document instead:
+
+```
+Explain how Home Delivery works end-to-end
+```
+
+This creates `features/home-delivery/architecture.md` — a read-only document with state machine diagrams, cross-entity sequence diagrams, rules tables, and settings dependencies. No planning gate, no implementation.
 
 ---
 
@@ -55,7 +214,9 @@ This produces a **Feature Architecture Document** with:
 - Integration points (webhooks, scheduled events)
 - Analysis confidence levels (HIGH/MEDIUM/LOW per rule)
 
-Output saved to `accounts/<PROFILE>/analysis/features/Home_Delivery.md`.
+Output saved to `accounts/<PROFILE>/features/home-delivery/architecture.md`.
+
+> **Artifact:** `accounts/<PROFILE>/features/home-delivery/architecture.md` — a Feature Architecture Document you can share with your team. Includes Mermaid diagrams that render in GitHub, Confluence, and most markdown viewers.
 
 **Step 3: Analyze specific workflows**
 ```
@@ -99,43 +260,131 @@ Builds and sends the event (with dry-run preview first), then monitors the resul
 
 ---
 
-## Scenario 3: "Build a new workflow for Returns"
+## Scenario 3: "Build a complete feature end-to-end"
+
+**Situation:** Product asks for a new Return Order capability. You need new workflows, custom rules, settings, and deployment — the full lifecycle.
+
+This is the flagship use case. The AI follows the mandatory chain: **requirements → plan → implement → build → deploy → test**. See [How It Works: The Feature Lifecycle](#how-it-works-the-feature-lifecycle) above for the full artifact map.
+
+**Step 1: Gather requirements (if unclear)**
+```
+Help me define the use cases for a Return Order feature
+```
+The `/fluent-use-case-discover` wizard runs through 10 phases:
+- Entity types involved (ORDER, RETURN_ORDER, FULFILMENT)
+- Business rules (return window, item eligibility, refund policies)
+- Status lifecycles per entity
+- Integration points (WMS, ERP, payment gateway)
+- Environment discovery (if profile connected)
+
+Produces a **Business Spec** saved to `accounts/<PROFILE>/features/return-order/spec.md` with a completeness score.
+
+**Step 2: Plan the feature**
+```
+Plan the Return Order feature
+```
+`/fluent-feature-plan` checks the spec (must be >= 75% completeness), then produces an 18-section plan:
+- Architecture diagrams (Mermaid state machines + sequence diagrams)
+- Workflow changes with before/after
+- Rules inventory: NEW rules get pseudo-logic contracts, OOTB rules get prop configuration
+- Settings, webhooks, cross-entity impacts
+- Every artifact tagged as NEW / EXISTING / MODIFIED / REUSED / OOTB
+- Deployment sequence, risk assessment, test plan
+
+Plan saved to `accounts/<PROFILE>/features/return-order/plan.md`.
+
+**Waits for your approval.** You can ask questions, request changes, or approve.
+
+> **Your workspace after steps 1-2:**
+> ```
+> accounts/<PROFILE>/features/return-order/
+>   status.json      ← status: PLANNING, plan: PENDING (or APPROVED after you approve)
+>   spec.md          ← business requirements with completeness score
+>   plan.md          ← 18-section implementation plan with Mermaid diagrams
+> ```
+> You can close your IDE here. When you come back, the AI reads `status.json`, sees `plan: "APPROVED"` and `next: "/fluent-rule-scaffold"`, and picks up at Step 3.
+
+**Step 3: Scaffold the module (if new)**
+```
+Create a new module called hm-returns
+```
+`/fluent-module-scaffold` generates the full Maven project: POMs, `module.json`, directory structure, build scripts, `.gitignore`.
 
-**Situation:** You need to implement a Return Order flow that doesn't exist yet.
+**Step 4: Scaffold custom rules**
+```
+Create the rules from the plan
+```
+`/fluent-rule-scaffold` generates each rule from the plan: Java class with SDK boilerplate, test skeleton, wired into `module.json`. Each rule emits `-> READY: <path>` and `-> NEXT: /fluent-build` on completion.
 
-**Step 1: Plan the workflow**
+**Step 5: Build the workflow**
 ```
-Build an ORDER::RETURN workflow with states: CREATED, APPROVED, ITEMS_RECEIVED, REFUNDED, COMPLETE, CANCELLED
+Build the RETURN_ORDER::DEFAULT workflow from the plan
 ```
-The agent enters **plan mode** — presents:
-- State machine diagram (Mermaid `stateDiagram-v2`)
-- Ruleset inventory (what triggers each transition)
-- Settings dependencies
-- Cross-entity interactions
-- Risk assessment
+`/fluent-workflow-builder` creates the workflow JSON with rulesets, states, triggers, and validates all references. Then `/fluent-workflow-analyzer` runs automatically to catch orphaned rulesets or trigger conflicts.
 
-**Waits for your approval** before writing any JSON.
+**Step 6: Build and package**
+```
+Build the module
+```
+`/fluent-build` bumps the version, runs `mvn clean install`, packages the ZIP. If compilation fails, reports the error and suggests fixes.
 
-**Step 2: Scaffold custom rules**
+**Step 7: Pre-deploy quality gates**
 ```
-Create a rule called ValidateReturnWindow that checks if the return is within 30 days
+Run pre-deploy checks
 ```
-Generates:
-- Java rule class with Fluent SDK boilerplate
-- Test class skeleton
-- Wires the rule into `module.json`
+`/fluent-pre-deploy-check` runs 26 gates across 8 phases: environment reachability, module structure, workflow validity, connection integrity, settings completeness, target environment checks, risk assessment, completeness verification. Reports READY or BLOCKED with specific blockers.
 
-**Step 3: Build and deploy**
+**Step 8: Deploy module + workflow**
 ```
-Build the module and deploy to HM_TEST
+Deploy everything to HM_TEST
 ```
-Runs Maven compile, packages the module ZIP, validates structure, and deploys.
+`/fluent-module-deploy` installs the module ZIP. `/fluent-workflow-deploy` uploads the workflow JSON (tries MCP first, falls back to REST API). Both verify the deployed version matches.
 
-**Step 4: Test it**
+**Step 9: End-to-end test**
 ```
-Run an E2E test: create a return order, approve it, receive items, process refund
+Run the E2E test from the plan
 ```
-Creates test entities dynamically, fires events at each step, polls for status transitions, and reports pass/fail per step.
+`/fluent-e2e-test` creates test entities dynamically (using `/fluent-test-data` discovery), fires events at each step, polls for status transitions, and reports pass/fail per step. On failure, automatically traces the failed event to find the root cause.
+
+**Step 10: Fix loop (if needed)**
+
+If a test fails, the agent diagnoses the issue (wrong prop value? missing setting? rule bug?), applies the fix, rebuilds, redeploys, and re-tests. This loop continues until all tests pass or an unresolvable blocker is hit.
+
+> **Your workspace after all steps:**
+> ```
+> accounts/<PROFILE>/
+>   features/return-order/
+>     status.json                                 ← status: VERIFIED, plan: APPROVED
+>     spec.md                                     ← business requirements
+>     plan.md                                     ← approved implementation plan
+>   SOURCE/fc-module-hm-returns/
+>     resources/module.json                       ← rule registrations
+>     plugins/rules/hm-returns/src/main/java/
+>       .../ValidateReturnWindow.java             ← custom rule
+>       .../ProcessReturnRefund.java              ← custom rule
+>     plugins/rules/hm-returns/src/test/java/
+>       .../ValidateReturnWindowTest.java          ← test skeleton
+>     dist/fc-module-hm-returns-1.0.0.zip         ← deployed module
+>   workflows/<RETAILER_REF>/
+>     RETURN_ORDER__DEFAULT.json                  ← deployed workflow
+>   reports/module-validate/hm-returns.report.json
+> ```
+
+**Common issues:**
+- "PLAN_REQUIRED" — you tried to scaffold rules without approving the plan first. Say "approved" to continue.
+- "PREREQ_MISSING" — the module doesn't exist yet. Run `/fluent-module-scaffold` first.
+- Build fails — check the error message. Common causes: missing imports, wrong SDK version, typo in `@ParamString` name.
+- Deploy blocked — pre-deploy check found issues. Run `/fluent-pre-deploy-check` to see what's blocking.
+
+### Resuming This Feature
+
+If you close your IDE at any point and come back later:
+
+```
+"Continue working on return orders"
+```
+
+The AI reads `features/return-order/status.json`, sees the current state and `next` skill, and picks up exactly where you left off. No need to re-explain context.
 
 ---
 
@@ -156,11 +405,20 @@ Analyzes:
 
 Produces a scored report with risk ratings and prioritized recommendations.
 
+The RFL assessment produces a scored report covering:
+- Workflow health score (0-100)
+- Code quality score (0-100)
+- Settings completeness score (0-100)
+- Integration risk rating (LOW/MEDIUM/HIGH/CRITICAL)
+- Prioritized remediation recommendations
+
+Each finding includes severity, affected entity, and a specific fix recommendation.
+
 **Step 2: Audit settings**
 ```
 Audit all settings for ORDER::HD — find any gaps
 ```
-Cross-references workflow rule parameters against deployed settings. Flags missing settings, wrong value formats, and cascading scope issues.
+Cross-references workflow rule parameters against deployed settings. Flags missing settings, wrong value formats, and cascading scope issues (RETAILER vs ACCOUNT).
 
 **Step 3: Check event health**
 ```
@@ -172,6 +430,12 @@ Queries Prometheus metrics or Event API, runs anomaly detection, and reports:
 - PENDING queue buildup
 - Single-event dominance (possible runaway loops)
 
+**Step 4: Validate cross-entity connections**
+```
+Run connection analysis on ORDER::HD with --validate against a real order
+```
+Compares the static workflow paths (what should happen) against actual runtime events for a real entity (what did happen). Shows gaps, unexpected events, and timing analysis. Flags any rulesets that never fired in production.
+
 ---
 
 ## Scenario 5: "Set up a fresh environment for testing"
@@ -267,43 +531,103 @@ Run connection analysis on ORDER::HD — check for broken cross-entity links
 ```
 Maps all internal, cross-entity, and cross-workflow connections. Flags any rulesets that emit events with no matching triggers.
 
-**Step 3: Deploy**
+**Step 3: Run pre-deploy quality gates**
 ```
-Deploy the updated ORDER::HD workflow
+Run pre-deploy checks for this workflow change
 ```
-Uses `/fluent-workflow-deploy` — validates structure, uploads via MCP `workflow.upload` tool (with dry-run first), falls back to REST API if needed, returns new version number.
+`/fluent-pre-deploy-check` validates: environment is reachable, workflow structure is valid, no orphaned rulesets, all rule references resolve to deployed modules, settings exist for referenced keys. Reports READY or BLOCKED.
 
-**Step 4: Verify**
+If BLOCKED, shows exactly what to fix (e.g., "Rule `ACCT.returns.ValidateReturnWindow` not found in any deployed module — deploy the module first").
+
+**Step 4: Deploy the workflow**
+```
+Deploy ORDER::HD to HM_TEST
+```
+`/fluent-workflow-deploy` uploads the workflow. Tries MCP `workflow.upload` first; if that fails (auth issue, size limit), falls back to REST API with automatic token acquisition. Verifies the deployed version matches the uploaded version.
+
+**Step 5: Verify with E2E test**
 ```
 Run an E2E test of the HD flow to verify the deployment
 ```
-Exercises the deployed workflow end-to-end and reports pass/fail.
+Exercises the deployed workflow end-to-end and reports pass/fail. On failure, traces the specific event to pinpoint whether the new workflow change caused the issue.
+
+**Common issues:**
+- Diff shows "removed rulesets" — HIGH risk. Verify these rulesets are truly unused before deploying. Run connection analysis to check for incoming triggers from other workflows.
+- Pre-deploy reports BLOCKED on rule references — the module containing those rules isn't deployed yet. Deploy the module first.
+- Workflow upload fails with 413 — workflow JSON exceeds size limit. The skill automatically falls back to REST API upload.
 
 ---
 
 ## Scenario 9: "Batch ingest inventory data"
 
-**Situation:** You need to load inventory positions in bulk.
+**Situation:** You need to load 10,000 inventory positions from an external system.
 
+**Step 1: Create the batch job**
 ```
 Create a batch ingestion job for inventory positions
 ```
-Walks through: creating the job, sending records in batches, polling status, and checking per-record results.
+`/fluent-job-batch` walks through the setup:
+- Creates a JOB entity scoped to INVENTORY_POSITION
+- Confirms the target catalogue and location refs
+
+**Step 2: Send records in batches**
+```
+Send the inventory records — here's the CSV/JSON data
+```
+Splits records into batches (default 100 per batch), sends each via `batch.send`, tracks progress. Shows a running count: "Sent 3,200 / 10,000 records (32%)".
+
+**Step 3: Monitor job status**
+```
+Check the job status
+```
+Polls `batch.status` and `batch.batchStatus` to show:
+- Overall job progress (PENDING → IN_PROGRESS → COMPLETE)
+- Per-batch results (success count, error count, error details)
+- Records that failed with specific validation errors
+
+**Step 4: Retry failures**
+```
+Show me the failed records and retry them
+```
+Fetches `batch.results` for failed batches, shows the specific records and error messages (e.g., "Location ref WAREHOUSE_99 not found"), and offers to re-send corrected records.
+
+**Common failure patterns:**
+| Error | Cause | Fix |
+|---|---|---|
+| "Entity not found" | Location or catalogue ref doesn't exist | Create the entity first via `/fluent-retailer-config` |
+| "Duplicate ref" | Record already exists | Use update mode or skip duplicates |
+| "Validation error" | Missing required fields | Fix the source data and resend |
+| "Rate limited" | Too many concurrent batches | Reduce batch size or add delays |
 
 ---
 
 ## Scenario 10: "Decompose a scope document into tasks"
 
-**Situation:** You have a structured scope document (ADD format) and need an executable task plan.
+**Situation:** You have a structured scope document (ADD format) describing a new feature and need an executable task plan before writing any code.
 
+**Step 1: Feed the scope document**
 ```
 Decompose this scope document into tasks with dependencies
 ```
-Parses the scope, generates an ordered task list with:
-- Dependency DAG (which tasks block which)
-- Skill mappings (which skill handles each task)
-- Ambiguity flags (where the scope is unclear)
-- SCAFFOLD vs EXTEND vs SOURCE_ONBOARD decisions
+Provide the scope doc (paste it, or point to a file). `/fluent-scope-decompose` parses it and produces:
+
+- **Ordered task list** with IDs (T-001, T-002, ...) and descriptions
+- **Dependency DAG** — which tasks block which (e.g., T-003 depends on T-001 and T-002)
+- **Skill mappings** — which skill handles each task (e.g., T-001 → `/fluent-module-scaffold`, T-003 → `/fluent-rule-scaffold`)
+- **Decision classifications** — SCAFFOLD (new), EXTEND (modify existing), SOURCE_ONBOARD (restructure), CONFIGURE (settings/data)
+- **Ambiguity flags** — where the scope is unclear and needs clarification ("T-005: scope says 'custom validation' but doesn't specify what fields to validate")
+
+**Step 2: Resolve ambiguities**
+```
+For T-005, validate that the return is within 30 days of order completion
+```
+Clarification updates the task and clears the ambiguity flag.
+
+**Step 3: Generate the feature plan**
+```
+Now generate a feature plan from these tasks
+```
+The task list feeds directly into `/fluent-feature-plan`, which produces the full 18-section plan with architecture diagrams, rules inventory, deployment sequence, and test plan. Each plan section cross-references the task IDs.
 
 ---
 
@@ -355,6 +679,403 @@ After approval:
 
 ---
 
+## Scenario 12: "Gather requirements before building"
+
+**Situation:** Product says "we need curbside pickup" but there are no structured requirements, use cases, or entity definitions.
+
+```
+Help me define the use cases for curbside pickup
+```
+
+`/fluent-use-case-discover` runs an interactive wizard through 10 phases:
+
+| Phase | What happens | Output |
+|---|---|---|
+| 1. Scope | Define the feature boundary — what's in, what's out | Scope statement |
+| 2. Actors | Identify who interacts (customer, store staff, OMS, WMS) | Actor registry |
+| 3. Use cases | Walk through each user journey step by step | Structured use case list |
+| 4. Environment discovery | Query live environment for existing workflows, rules, entity types (requires connected profile) | Available infrastructure |
+| 5. Entity model | Define entities, subtypes, and relationships | Entity relationship diagram |
+| 6. Status lifecycles | Map statuses per entity with allowed transitions | State machine diagrams |
+| 7. Business rules | Capture validation rules, constraints, edge cases | Rules inventory |
+| 8. Integration points | Webhooks, external systems, scheduled jobs | Integration map |
+| 9. Settings | Required configuration keys and values | Settings inventory |
+| 10. Gap analysis | Compare requirements against existing environment | Completeness score |
+
+**Output:** A Business Spec saved to `accounts/<PROFILE>/features/curbside-pickup/spec.md` with a completeness score (0-100%). Specs scoring >= 75% can proceed directly to `/fluent-feature-plan`.
+
+> **Offline limitation:** If no Fluent profile is connected, Phase 4 (environment discovery) is skipped. The spec may contain assumptions. Connect a profile via `/fluent-profile` before running the wizard for best results.
+
+---
+
+## Scenario 13: "Validate cross-entity workflow dependencies"
+
+**Situation:** Your ORDER::HD workflow sends events that trigger FULFILMENT and FULFILMENT_OPTIONS workflows. You need to verify all the cross-entity connections are wired correctly.
+
+**Step 1: Map static connections**
+```
+Run connection analysis on ORDER::HD
+```
+`/fluent-connection-analysis` maps:
+- **Internal connections** — rulesets within ORDER::HD that SendEvent to other ORDER::HD rulesets
+- **Cross-entity connections** — SendEvent calls targeting FULFILMENT, FULFILMENT_OPTIONS, ARTICLE entities
+- **Cross-workflow connections** — events that leave ORDER::HD and enter another workflow
+- **Orphaned rulesets** — rulesets with no incoming trigger
+- **Dead-end events** — SendEvent calls with no matching target ruleset
+
+Output includes Mermaid flowcharts showing the full event graph across workflows.
+
+**Step 2: Compare against runtime (--validate)**
+```
+Run connection analysis on ORDER::HD --validate HD-12345 --entity-type ORDER
+```
+Compares the static workflow paths against actual runtime events for a real entity. Shows:
+- **Expected but not fired** — rulesets that should have triggered but didn't (possible bug)
+- **Fired but not expected** — events that occurred outside the static model (dynamic behavior, scheduled events)
+- **Timing analysis** — how long each transition took
+- **Cross-entity propagation** — traces events across ORDER → FULFILMENT → FULFILMENT_OPTIONS
+
+This is the most thorough validation — it proves the workflow works as designed for real entities.
+
+---
+
+## Scenario 14: "Bump version and prepare a release"
+
+**Situation:** You've finished development and need to version, build, validate, and deploy a module.
+
+**Step 1: Check current version**
+```
+What version is the hm-extensions module?
+```
+`/fluent-version-manage` reads the version from `module.json`, `pom.xml` (parent + child), and CHANGELOG. Reports any inconsistencies (e.g., POM says 1.3.0 but module.json says 1.2.9).
+
+**Step 2: Bump the version**
+```
+Bump hm-extensions to 1.4.0
+```
+Updates ALL version references in sync:
+- `plugins/pom.xml` (parent version)
+- `plugins/rules/<module>/pom.xml` (module + parent version)
+- `resources/module.json` (version field)
+- `CHANGELOG.md` (moves [Unreleased] entries to [1.4.0])
+
+**Step 3: Build**
+```
+Build it
+```
+`/fluent-build` runs `mvn clean install`, packages the ZIP, verifies the output artifact.
+
+**Step 4: Pre-deploy gates**
+```
+Run pre-deploy checks
+```
+26 quality gates across 8 phases. If all pass → READY. If any critical gate fails → BLOCKED with specific fix instructions.
+
+**Step 5: Deploy**
+```
+Deploy to HM_TEST
+```
+Module install + post-deploy verification.
+
+**Common issues:**
+- Version mismatch — `module.json` says 1.4.0 but `pom.xml` still says 1.3.0. Run `/fluent-version-manage` to sync all version references.
+- Build fails after version bump — stale `dist/` artifacts from the old version. Clean build (`mvn clean install`) resolves this.
+- Pre-deploy gate fails on "module already deployed at same version" — bump the version again or use a `-SNAPSHOT` suffix for testing.
+
+---
+
+## Scenario 15: "Audit what happened in this session"
+
+**Situation:** You've been working for an hour — scaffolded rules, edited workflows, deployed a module, ran tests. Now you need to know exactly what changed and what tools were called.
+
+**Quick summary:**
+```
+What did we change this session?
+```
+`/fluent-session-summary` shows three tables:
+
+**Skill Invocations:**
+| # | Skill | Gate | Outcome | Next |
+|---|---|---|---|---|
+| 1 | fluent-rule-scaffold | PASS | completed | fluent-build |
+| 2 | fluent-build | PASS | completed | fluent-pre-deploy-check |
+| 3 | fluent-pre-deploy-check | — | completed (READY) | fluent-module-deploy |
+| 4 | fluent-module-deploy | PASS | completed | fluent-e2e-test |
+
+**MCP Tool Calls:**
+| # | Tool | Target | Write? | Outcome | Skill |
+|---|---|---|---|---|---|
+| 1 | entity.create | ORDER/E2E_HD_001 | Yes | ok | fluent-e2e-test |
+| 2 | event.send | ORDER/E2E_HD_001 | Yes | ok | fluent-e2e-test |
+| 3 | test.assert | ORDER/E2E_HD_001 status=BOOKED | No | ok | fluent-e2e-test |
+
+**Changes:**
+| # | Action | File/Entity | Details |
+|---|---|---|---|
+| 1 | CREATE | src/.../ValidateReturnWindow.java | New rule class |
+| 2 | MODIFY | resources/module.json | Registered ValidateReturnWindow |
+| 3 | DEPLOY | fc-module-hm-returns 1.4.0 | Installed to HM_TEST |
+
+**Machine-readable export:**
+```
+Export a JSON audit trail
+```
+`/fluent-session-audit-export` writes a JSON file to `accounts/<PROFILE>/sessions/` with:
+- `skillInvocations[]` — full decision chain with gate results, handoff signals, cross-references
+- `toolCalls[]` — every MCP tool call with target, outcome, triggering skill
+- `changes[]` — every state mutation with rollback commands
+- `decisionTrail[]` — explicit branch decisions with rationale and confidence
+- `compliance` — scope traceability matrix, task completion status
+
+The JSON is designed for CI/CD consumption — parse it as a deployment gate, feed it into Jira work logs, or attach to Confluence release pages.
+
+> **Tip:** Run `/fluent-session-summary` regularly during long sessions. The AI tracks changes as they happen — it's easier to review incrementally than reconstruct everything at the end.
+
+---
+
+## Scenario 16: "Create a data module (no Java)"
+
+**Situation:** You need to deploy reference data, workflow fragments, or configuration assets — no custom Java rules.
+
+```
+Create a data module called hm-reference-data
+```
+`/fluent-data-module-scaffold` generates:
+- `module.json` with module metadata (no `rules` array)
+- `assets/` directory structure for workflows, settings, and data files
+- `config/` template for module configuration
+- Build script that packages the module ZIP without Maven compilation
+
+Data modules are lighter than extension modules — no POMs, no Java source, no test skeletons. They're deployed the same way (`fluent module install`) but only carry assets.
+
+---
+
+## Scenario 17: "Map what's been built on this account"
+
+**Situation:** You're onboarding to a new Fluent Commerce account and need to understand the full implementation — what features exist, how they connect, and where the gaps are.
+
+```
+What has been built here? Give me a feature inventory
+```
+
+`/fluent-implementation-map` runs a 5-phase analysis:
+
+1. **Inventory Collection** — queries workflows (`workflow.list`), custom rules (`plugin.list`), settings (`graphql.query`), and local source code to build the raw inventory
+2. **Feature Identification** — clusters workflows into logical features using subtype alignment, cross-entity events, shared custom rules, and naming conventions
+3. **Flow Mapping** — traces cross-feature dependencies and generates Mermaid diagrams (feature dependency graph + entity lifecycle sequence)
+4. **Gap Analysis** — identifies missing workflows, orphaned rules, webhook health issues, dead-end risks, and OOTB coverage gaps
+5. **Report Generation** — produces the master document plus per-feature summaries
+
+**Output at `accounts/<PROFILE>/analysis/implementation-map/`:**
+
+```
+implementation-map.md              ← Master document with executive summary, feature table, diagrams
+inventory.json                     ← Machine-readable inventory (workflows, features, gaps, modules)
+gaps.md                            ← All identified gaps with severity and remediation
+features/
+  home-delivery.md                 ← Per-feature summary with workflows, rules, webhooks
+  click-collect.md
+  inventory-management.md
+  ...
+diagrams/
+  feature-dependency.mmd           ← Cross-feature dependency flowchart
+  entity-flow.mmd                  ← Entity lifecycle sequence diagram
+```
+
+Each feature gets a **customisation depth score** (0-4: OOTB → Configured → Extended → Custom → Bespoke) and a **confidence rating** (HIGH/MEDIUM/LOW) based on evidence quality.
+
+Read-only — no planning gate, no environment changes. Great as a first step before `/fluent-feature-explain` on specific features.
+
+---
+
+## Scenario 18: "Check feature status across the workspace"
+
+**Situation:** You have multiple features in various lifecycle stages and need a dashboard view.
+
+```
+What features are in progress? Show the dashboard
+```
+
+`/fluent-feature-status` scans all `accounts/<PROFILE>/features/*/status.json` files and presents a consolidated table:
+
+| Feature | Retailer | Status | Spec | Plan | Rev | Next Step |
+|---------|----------|--------|------|------|-----|-----------|
+| curbside-pickup | HM_TEST | IN_PROGRESS | APPROVED | APPROVED | 2 | /fluent-build |
+| return-order | HM_TEST | VERIFIED | APPROVED | APPROVED | 1 | — |
+| loyalty-points | HM_TEST | PLANNING | APPROVED | DRAFT | 1 | /fluent-feature-plan |
+
+**Filtering:** Ask for specific states:
+```
+Show only IN_PROGRESS features
+```
+
+**Attention items** are highlighted automatically:
+- Features stuck in PLANNING for more than 7 days
+- Features with `plan: "PENDING"` but `status: "IN_PROGRESS"` (skipped approval?)
+- Features with `basedOn` links to non-existent features
+
+Read-only — no planning gate, no environment changes. Use this when resuming a session to see where you left off.
+
+---
+
+## Scenario 19: "Archive a completed feature"
+
+**Situation:** The return-order feature is verified and deployed. You want to mark it as done and remove it from the active dashboard.
+
+```
+Archive the return-order feature
+```
+
+`/fluent-archive` performs:
+1. **Status check** — verifies the feature exists and reads `status.json`
+2. **Safety gate** — if status is `IN_PROGRESS`, archival is **blocked** (use `--force` to override)
+3. **Confirmation** — presents current status and asks for explicit approval
+4. **Update** — sets `status: "ARCHIVED"` and `archivedOn` timestamp in `status.json`
+
+**After archival:**
+- The feature directory and all artifacts remain intact (specs, plans, architecture docs)
+- `/fluent-feature-status` excludes archived features from the default view (use `--filter ARCHIVED` to see them)
+- There is no "unarchive" — to resume, manually edit `status.json`
+
+**Force archive an in-progress feature:**
+```
+Archive curbside-pickup --force
+```
+Bypasses the safety gate. Use when abandoning a feature that won't be completed.
+
+---
+
+## Scenario 20: "Roll back a failed deployment"
+
+**Situation:** You deployed a new workflow version and it's causing event failures. You need to revert to the previous version.
+
+```
+Roll back ORDER::HD to the previous version
+```
+
+`/fluent-rollback` follows a structured process:
+
+**Step 1: Planning gate** — presents a rollback plan showing:
+- Current deployed version vs target version
+- Source of the rollback artifact (pre-deploy backup, local cache, or git history)
+- What will change and what won't
+- Irreversible operations that can't be rolled back (already-processed events, sent webhooks)
+
+**Step 2: Dry run** (recommended for production):
+```
+Roll back ORDER::HD --dry-run
+```
+Shows exactly what would happen without making changes.
+
+**Step 3: Execute** — after plan approval, uploads the previous workflow version as a new version.
+
+**Three artifact types supported:**
+
+| Artifact | Rollback method | Source resolution |
+|----------|----------------|-------------------|
+| Workflow | Re-upload previous JSON as new version | Pre-deploy backup → local cache → git history |
+| Module | Redeploy prior module ZIP | Local dist → git tag → artifact repository |
+| Settings | Restore prior values via GraphQL | Session export → settings audit → pre-deploy report |
+
+**Cannot roll back:** Entity state changes, sent events, batch ingestion data, webhook deliveries. The skill refuses these and suggests compensating alternatives.
+
+---
+
+## Scenario 21: "Show me the workspace structure"
+
+**Situation:** You want to see what's in the workspace — features, workflows, source code, reports — with counts and annotations.
+
+```
+Show me the workspace tree
+```
+
+`/fluent-workspace-tree` produces an annotated directory listing:
+
+```
+accounts/HMDEV/
+  SOURCE/                           (2 repos)
+    fc-module-hm-extensions/        (97 rules, v1.4.0)
+    fc-module-hm-returns/           (3 rules, v1.0.0)
+  workflows/HM_TEST/                (17 workflows)
+    ORDER__HD.json                  (v1.51, 64 rulesets)
+    ORDER__CC.json                  (v1.12, 50 rulesets)
+    ...
+  features/                         (4 features)
+    curbside-pickup/                IN_PROGRESS (plan rev 2)
+    return-order/                   VERIFIED
+    home-delivery/                  architecture only
+    loyalty-points/                 PLANNING
+  reports/                          (3 reports)
+    pre-deploy/hm-returns.json      2026-02-24
+  analysis/
+    implementation-map/             (11 features mapped)
+    code/                           (source-map, behavior-map)
+```
+
+Read-only — no planning gate, no environment changes. Useful for orientation when starting a new session or after running multiple skills.
+
+---
+
+## Frontend / Mystique UI Scenarios
+
+### Scenario: Build a New UI Page
+
+**You say:** "Build an order detail page showing order summary, customer info, items, and fulfilments"
+
+**What happens:**
+1. `/fluent-mystique-builder` analyzes the requirement against OOTB components
+2. Presents a plan: route structure, component tree, data query, composition pattern
+3. On approval: generates manifest JSON with `fc.page` → `fc.card.attribute` (summary) + `fc.card.attribute` (customer) + `fc.tabs.card` (items/fulfilments)
+4. Auto-runs `/fluent-mystique-validate` to verify structure
+
+**You get:** A complete manifest JSON page definition ready to deploy as a Fluent setting.
+
+### Scenario: Validate Before Deploying
+
+**You say:** "Validate the admin manifest before I deploy it"
+
+**What happens:**
+1. `/fluent-mystique-validate` runs 49 rules across 6 phases
+2. Checks schema compliance, component aliases, GraphQL queries, template strings, prop completeness, cross-manifest references
+3. Reports issues by severity (CRITICAL/HIGH/MEDIUM/LOW)
+
+**You get:** A validation report with pass/fail and specific fix suggestions for any issues found.
+
+### Scenario: Custom Component When OOTB Falls Short
+
+**You say:** "I need a drag-and-drop pick list interface for warehouse staff"
+
+**What happens:**
+1. `/fluent-mystique-builder` evaluates the Build vs Configure decision framework
+2. Determines OOTB components can't handle drag-and-drop → escalates to Step 4 (custom component)
+3. `/fluent-mystique-scaffold` creates a complete SDK project: webpack config, TypeScript setup, component boilerplate, Storybook stories, Jest tests
+4. Manifest is updated with `plugins[]` reference to the custom bundle
+
+**You get:** A buildable SDK project with `ComponentRegistry.register()` wiring and a manifest referencing the custom component.
+
+### Scenario: Analyze What's Built in an App
+
+**You say:** "What components are used in the admin manifest? Any complexity issues?"
+
+**What happens:**
+1. `/fluent-mystique-analyze` runs 7-dimension analysis: component census, route mapping, complexity scoring (weighted 0-100), data query analysis, i18n coverage, pattern detection, Mermaid diagrams
+
+**You get:** A comprehensive analysis report with component counts, unused components, complexity hotspots, and optimization recommendations.
+
+### Scenario: Full-Stack Feature (Backend + Frontend)
+
+**You say:** "Build order tracking with a customer-facing status page"
+
+**What happens:**
+1. `/fluent-feature-plan` creates a unified plan covering both backend (workflow rules, settings) and frontend (manifest pages, components)
+2. On approval: backend agent builds rules → workflows → settings first
+3. Then frontend agent builds manifest → validates → deploys
+4. `/fluent-e2e-test` runs cross-cutting tests
+
+**You get:** Complete backend logic AND UI pages deployed and verified end-to-end.
+
+---
+
 ## What Happens Behind the Scenes
 
 When you ask your AI assistant to perform these tasks, it doesn't just generate text — it **executes real operations** against your Fluent environment:
@@ -366,7 +1087,60 @@ When you ask your AI assistant to perform these tasks, it doesn't just generate
 | **Official MCP Server** (CLI layer) | Workflow listing, downloading, GraphQL validation via the Fluent CLI |
 | **Fluent Commerce API** (platform) | The actual REST/GraphQL endpoints being called |
 
-The AI plans its approach, calls the right tools in the right order, handles errors, and reports results — all through natural conversation.
+### Planning Gate
+
+Before any implementation work, the AI presents a structured plan and **waits for your explicit approval**. This isn't optional — it's enforced by every implementation skill. You can ask questions, request changes, or reject the plan entirely. No code is written, no entities are created, and no deployments happen without your say-so.
+
+### Progress Visualization
+
+Multi-phase skills show a live progress block as they work, so you always know where the AI is in the process:
+
+```
+▸ /fluent-pre-deploy-check [3/8]
+  ✓ Environment              ✓ Module structure
+  ✓ Workflow validity         → Connections
+  ○ Settings                  ○ Target environment
+  ○ Risk assessment           ○ Completeness
+```
+
+- `✓` completed — `→` currently running — `○` pending
+- The block updates at each phase transition
+
+Available on the 10 most-used skills: `/fluent-feature-plan`, `/fluent-trace`, `/fluent-e2e-test`, `/fluent-implementation-map`, `/fluent-feature-explain`, `/fluent-build`, `/fluent-pre-deploy-check`, `/fluent-connection-analysis`, `/fluent-use-case-discover`, `/fluent-workflow-builder`.
+
+### Skill Chains and Handoff Signals
+
+Skills communicate via handoff signals:
+- `-> READY: <path>` — "I'm done, here's what I produced"
+- `-> NEXT: /fluent-build` — "The next step is this skill"
+- `-> BLOCKED: No module found` — "I can't proceed; here's why and what to do"
+- `-> SKIP: No settings changes` — "This step doesn't apply"
+
+These signals chain skills together automatically. When `/fluent-rule-scaffold` finishes, it emits `-> NEXT: /fluent-build`. The agent follows the chain without you having to spell out each step.
+
+### Error Taxonomy
+
+When something goes wrong, skills report structured error codes:
+- `PLAN_REQUIRED` — you tried to implement without an approved plan
+- `PREREQ_MISSING` — a dependency doesn't exist yet (e.g., no module to add rules to)
+- `VALIDATION_FAILED` — input failed structural or semantic checks
+- `ENV_UNREACHABLE` — can't connect to the Fluent environment
+- `DEPLOYMENT_BLOCKED` — pre-deploy gates failed
+
+Each error code comes with a recovery action (which skill to run to fix it).
+
+### Three-Level Pre-Flight Chain
+
+For multi-artifact features, enforcement happens at three levels:
+1. **Requirements check** — `/fluent-feature-plan` verifies a Business Spec exists (or structured requirements are provided). If not → redirects to `/fluent-use-case-discover`.
+2. **Plan verification** — each implementation skill checks for an approved plan. If not → redirects to `/fluent-feature-plan`.
+3. **Dependency checks** — each skill checks that its prerequisites exist (e.g., rule-scaffold checks the module exists). If not → redirects to the prerequisite skill.
+
+This creates an enforced chain: **requirements → plan → implementation**. No step can be skipped without explicit user override.
+
+### Session Tracking
+
+Every skill invocation, MCP tool call, and state change is tracked during the session. At any point you can ask "what did we change?" for a structured report, or export a JSON audit trail for CI/CD pipelines.
 
 ---
 
@@ -389,9 +1163,92 @@ When evidence is incomplete, the AI flags it explicitly and recommends how to ge
 
 | Capability | Status | Workaround |
 |-----------|--------|-----------|
-| Refactor loose source into module format | **Supported** via `/fluent-source-onboard` | Analyzes, plans, restructures, validates, and builds in one flow (see Scenario 11) |
 | Live log tailing / real-time event streaming | Not supported | Use `event.list` with time filters for polling |
 | Multi-retailer operations in single command | Not supported | Switch retailer context between operations |
+| Visual workflow editor (GUI) | Not supported | Edit workflow JSON directly via `/fluent-workflow-builder` |
+| Anonymous mode (no credentials) | Not supported | MCP tools require profile auth or OAuth credentials |
+| Decompiled source modification | Read-only | Analyze decompiled code but can't edit it; provide original source or scaffold a new module via `/fluent-source-onboard` |
+| Windows `::` in workflow filenames | Auto-handled | CLI and skills auto-sanitize to `__` and maintain `workflow-file-map.json` |
+| `fluent workflow merge` upload bug | Known CLI bug | Skills use REST API upload as fallback automatically |
+| `workflow.simulate` runtime execution | Static only | Simulates by matching status + event + subtype; does not execute Java rules or check runtime state |
+| Java rule execution | Not supported | Skills can scaffold, build, and deploy rules but cannot execute them locally; use E2E tests against the live environment |
+
+---
+
+## Troubleshooting
+
+### Skill Gate Errors
+
+These errors come from the skill enforcement chain. Each one tells you exactly what's missing and which skill to run.
+
+| Error code | What happened | Fix |
+|---|---|---|
+| `PLAN_REQUIRED` | You asked a skill to implement something but there's no approved plan | Run `/fluent-feature-plan` (multi-artifact) or let the skill create a task plan (single artifact). Approve it, then retry. |
+| `PREREQ_MISSING` | A skill needs something that doesn't exist yet | Follow the redirect. Common cases: `/fluent-rule-scaffold` needs a module → run `/fluent-module-scaffold`. `/fluent-workflow-builder` needs deployed rules → run `/fluent-build` then `/fluent-module-deploy`. `/fluent-build` needs a validation report → run `/fluent-module-validate`. |
+| `VALIDATION_FAILED` | Input data failed structural or semantic checks | Read the error details — they specify which field or structure is wrong. Fix and retry. |
+| `ENV_UNREACHABLE` | Can't connect to the Fluent environment | Run `config.validate` and `connection.test` via MCP to diagnose. Common causes: expired credentials, wrong profile, VPN not connected. |
+| `DEPLOYMENT_BLOCKED` | Pre-deploy quality gates failed | Run `/fluent-pre-deploy-check` to see the full gate report. Each blocked gate explains what to fix. |
+
+If you want to bypass a gate, say **"skip planning"** or **"just do it"** — the override is logged as `USER_OVERRIDE`.
+
+### MCP Tool Errors
+
+These errors come from the MCP extension server when calling Fluent Commerce APIs. Every tool response includes `ok: true` or `ok: false` with a typed error code.
+
+| Error code | What it means | What to do |
+|---|---|---|
+| `CONFIG_ERROR` | Environment variables are missing or invalid | Check `.mcp.json` — verify `FLUENT_PROFILE` is set (or OAuth credentials if not using profile auth). Restart IDE after editing `.mcp.json`. |
+| `AUTH_ERROR` | Credentials are wrong or expired | For profile auth: run `fluent auth login -p YOUR_PROFILE` to refresh. For OAuth: verify client ID/secret/username/password in `.mcp.json`. |
+| `TIMEOUT_ERROR` | Request took longer than 30 seconds (default) | For large queries, increase `FLUENT_REQUEST_TIMEOUT_MS` in `.mcp.json` env block (e.g., `"60000"` for 60s). |
+| `RATE_LIMIT` | Too many API requests | Wait a moment and retry. The server uses exponential backoff automatically for read operations. |
+| `UPSTREAM_UNAVAILABLE` | Fluent API returned 502/503/504 | The platform may be under maintenance. Check Fluent status page. Reads retry automatically (up to 3 attempts with backoff). |
+| `NETWORK_ERROR` | Can't reach the API endpoint at all | Check VPN, network connectivity, firewall. Verify the base URL in your profile is correct. |
+| `SDK_ERROR` | Fluent SDK returned an unexpected error | Usually a bug or unsupported operation. Check the error message for details. |
+
+### Common Setup Problems
+
+**"I typed a slash command but nothing happened"**
+- Skills must be installed first: `npx @fluentcommerce/ai-skills install`
+- Slash commands (`/fluent-*`) only work in Claude Code. Other IDEs use natural language prompts that trigger the same skills.
+
+**"MCP tools aren't available"**
+- Run `npx @fluentcommerce/ai-skills mcp-setup --profile YOUR_PROFILE` to generate `.mcp.json`
+- Restart your IDE after creating or editing `.mcp.json` — MCP servers are loaded at startup
+- Verify with `config.validate` → `health.ping` → `connection.test` (in that order)
+
+**"Workflow download fails or returns empty"**
+- Check you have the right profile and retailer: `fluent workflow list -p YOUR_PROFILE -r YOUR_RETAILER`
+- Fluent CLI must be installed: `npm i -g @fluentcommerce/cli`
+- The profile must have the retailer associated — verify with `fluent retailer list -p YOUR_PROFILE`
+
+**"The AI keeps asking me to approve a plan"**
+- This is by design — the planning gate prevents unreviewed changes. Say **"approved"**, **"yes"**, or **"go ahead"** to proceed. Or say **"just do it"** or **"skip planning"** to bypass.
+
+**"I came back to a session and the AI lost context"**
+- Check `accounts/<PROFILE>/features/*/status.json` — the AI reads these to resume where you left off
+- If `status.json` shows `next: "/fluent-rule-scaffold"`, the AI knows to continue with that skill
+- If files are missing, re-run `/fluent-connect` to rebuild workspace state
+
+**"Response is truncated or summarized"**
+- Large API responses are auto-summarized (not truncated) when they exceed 50,000 characters. The summary includes record counts, field inventory, distributions, and sample records.
+- To get full raw data, set `FLUENT_RESPONSE_BUDGET_CHARS=0` in `.mcp.json` env block. This disables the budget and returns everything.
+
+---
+
+## IDE Target Differences
+
+Claude Code is the primary target with full feature support. Other IDEs receive the same domain knowledge but in different formats with some limitations.
+
+| Capability | Claude Code | Cursor | Copilot / VS Code / Windsurf / Codex / Gemini |
+|---|---|---|---|
+| **Slash commands** (`/fluent-*`) | Yes — each skill is a slash command | No — use natural language prompts | No — use natural language prompts |
+| **Agent routing** | Full — agents route to skills by task type | Partial — rules loaded per-file, no agent hierarchy | Partial — all content in one file, relies on IDE's own routing |
+| **MCP tool access** | Full — 36 tools via MCP servers | Full — if `.mcp.json` or `.cursor/mcp.json` is configured | Varies by IDE — check IDE docs for MCP support |
+| **Session resumption** | Yes — reads `status.json` to continue | Yes — same `status.json` mechanism | Yes — same `status.json` mechanism |
+| **Skill content** | Full markdown with frontmatter | `.mdc` files with Cursor frontmatter (one per skill) | Merged into single instruction file (managed block) |
+| **Install scope** | Global (`~/.claude/`) | Project (`.cursor/rules/`) | Project (`.github/`, `.windsurfrules`, `AGENTS.md`, `GEMINI.md`) |
+
+**Prompt equivalence:** The same natural language works across all IDEs. Instead of `/fluent-trace`, say "trace why order HD-001 is stuck". Instead of `/fluent-feature-plan`, say "plan the curbside pickup feature". The AI recognizes the intent from the domain knowledge injected by the skills.
 
 ---