@fluentcommerce/ai-skills 0.13.0 → 0.15.0

package/docs/03-use-cases.md

@@ -0,0 +1,1181 @@
+# What Can You Do With Fluent AI Skills?
+
+> [!CAUTION]
+> **🧪 EXPERIMENTAL — LABS PROJECT**
+> This package is not production-ready. No stability guarantees, no support, no warranty. See [README](../README.md) for full disclaimer.
+
+Deep scenario walkthroughs for `@fluentcommerce/ai-skills`. Each scenario shows what to say, what happens behind the scenes, and what you get back.
+
+> **Prerequisites:** Skills installed (`npx @fluentcommerce/ai-skills install`), MCP servers configured (`mcp-setup --profile YOUR_PROFILE`), and workspace connected (`/fluent-connect`).
+>
+> **Codex note:** Slash commands below are Claude Code examples. In Codex, ask the same thing in natural language, for example: `Use the fluent-connect skill to connect this workspace with profile YOUR_PROFILE.`
+
+> **New here?** Start with [Your First Session](01-first-session.md) for a 20-minute guided walkthrough. For a quick skill lookup, see [Prompt Guide](02-prompt-guide.md).
+
+---
+
+## Find Your Scenario
+
+Jump to the scenario that matches your current task. See the [README — Who Is This For?](../README.md#who-is-this-for) for full persona descriptions.
+
+| I need to... | Start here |
+|---|---|
+| **Understand what's built** (new to the project) | [Scenario 1](#scenario-1-i-just-joined-the-project--help-me-understand-whats-built), [Scenario 17](#scenario-17-map-whats-been-built-on-this-account) |
+| **Build a feature** end-to-end | [Scenario 3](#scenario-3-build-a-complete-feature-end-to-end), [Scenario 12](#scenario-12-gather-requirements-before-building) |
+| **Debug a stuck order** or failed event | [Scenario 2](#scenario-2-an-order-is-stuck--help-me-debug-it), [Scenario 6](#scenario-6-monitor-production-event-processing) |
+| **Deploy safely** or roll back | [Scenario 8](#scenario-8-deploy-a-workflow-change-safely), [Scenario 19](#scenario-19-roll-back-a-failed-deployment) |
+| **Audit for go-live** | [Scenario 4](#scenario-4-were-going-live-next-week--are-we-ready), [Scenario 13](#scenario-13-validate-cross-entity-workflow-dependencies) |
+| **Build or change UI** | [Frontend scenarios](#frontend--mystique-ui-scenarios) |
+| **Set up a new environment** | [Scenario 5](#scenario-5-set-up-a-fresh-environment-for-testing) |
+
+---
+
+## How It Works: The Feature Lifecycle
+
+For the full walkthrough of the feature lifecycle — directory structure, `status.json` fields, the approval gate, and workspace layout — see [Getting Started — Workspace Layout](05-getting-started.md#3-workspace-layout).
+
+**Quick summary:** Every feature lives under `accounts/<PROFILE>/features/<slug>/` with `status.json` (lifecycle tracker), `spec.md` (business requirements), `plan.md` (implementation plan), and optionally `architecture.md` (reverse-engineered docs). The AI reads `status.json` to resume where you left off across sessions.
+
+### 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.
+
+---
+
+## Scenario 1: "I just joined the project — help me understand what's built"
+
+**Situation:** You're a new developer onboarding onto an existing Fluent Commerce implementation. You need to understand the workflows, rules, and integrations before making changes.
+
+**Step 1: Connect to the account**
+```
+/fluent-connect
+```
+The wizard discovers your CLI profiles, selects the retailer, downloads all workflows, scans for source code, decompiles any JARs, and reports what's available.
+
+**Step 2: Explain the main feature**
+```
+Explain how the Home Delivery order flow works end-to-end
+```
+This produces a **Feature Architecture Document** with:
+- State machine diagrams (Mermaid) for every entity (ORDER, FULFILMENT_CHOICE, FULFILMENT)
+- Cross-entity sequence diagram showing event propagation
+- Rules & logic table explaining what each ruleset does
+- Settings dependencies with current values
+- Integration points (webhooks, scheduled events)
+- Analysis confidence levels (HIGH/MEDIUM/LOW per rule)
+
+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**
+```
+Analyze ORDER::HD for orphaned rulesets and trigger coverage
+```
+Returns a status graph, event chains, process flow classification, and any structural issues.
+
+**Step 4: Understand custom code**
+```
+Analyze the custom code for this account
+```
+Scans `accounts/<PROFILE>/SOURCE/backend/`, maps rules to workflow rulesets, generates behavior descriptions, and flags any deployed rules without local source.
+
+---
+
+## Scenario 2: "An order is stuck — help me debug it"
+
+**Situation:** A production order `HD-12345` has been in BOOKED status for hours and should have progressed to FULFILLED.
+
+**Step 1: Trace the order**
+```
+Why is order HD-12345 stuck in BOOKED?
+```
+Runs `event_flowInspect` on the order, analyzing all orchestration events to find:
+- Which events fired and which NO_MATCHed
+- Failed webhook deliveries
+- Rulesets that should have triggered but didn't
+- Timeline of every status change
+
+If you want the **combined runtime-vs-workflow report** instead of runtime triage alone, say:
+```
+Compare runtime vs workflow for order HD-12345
+```
+That routes to `/fluent-entity-flow-diagnose`, which reconstructs the dynamic chain, resolves the relevant workflow set, and shows expected vs observed behavior in one report.
+
+**Step 2: Check available actions**
+```
+What actions can I take on this order right now?
+```
+Queries the Transition API for user actions available at the current status — shows event names, required attributes, and button labels.
+
+**Step 3: Fire a remediation event**
+```
+Send a RetryFulfilmentAllocation event to order HD-12345
+```
+Builds and sends the event (with dry-run preview first), then monitors the result.
+
+---
+
+## 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 12 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
+>   assets/          ← screenshots, recordings, visual evidence (linked from spec/plan)
+> ```
+> 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 my-returns
+```
+`/fluent-module-scaffold` generates the full Maven project: POMs, `module.json`, directory structure, build scripts, `.gitignore`.
+
+**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 4b: Generate or repair rule tests**
+```
+Generate tests for ValidateReturnWindow
+```
+`/fluent-rule-test` generates comprehensive JUnit 5 tests for existing rules: happy path, edge cases, error scenarios, and mock setups. If tests already exist but are broken, it diagnoses and repairs them. Uses `RuleExecutor` or `TestExecutor` patterns from `rule-test-patterns.md`.
+
+**Step 5: Build the workflow**
+```
+Build the RETURN_ORDER::DEFAULT workflow from the plan
+```
+`/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.
+
+**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 7: Pre-deploy quality gates**
+```
+Run pre-deploy checks
+```
+`/fluent-pre-deploy-check` runs 35+ gates across 9 phases: environment readiness, module integrity, workflow validity, connection topology, settings completeness, target verification, risk assessment, completeness, and frontend bundle. Reports READY or BLOCKED with specific blockers.
+
+**Step 8: Deploy module + workflow**
+```
+Deploy everything to MY_RETAILER
+```
+`/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 9: End-to-end test**
+```
+Run the E2E test from the plan
+```
+`/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/backend/fc-module-my-returns/
+>     resources/module.json                       ← rule registrations
+>     plugins/rules/my-returns/src/main/java/
+>       .../ValidateReturnWindow.java             ← custom rule
+>       .../ProcessReturnRefund.java              ← custom rule
+>     plugins/rules/my-returns/src/test/java/
+>       .../ValidateReturnWindowTest.java          ← test skeleton
+>     dist/fc-module-my-returns-1.0.0.zip         ← deployed module
+>   workflows/<RETAILER_REF>/
+>     RETURN_ORDER__DEFAULT.json                  ← deployed workflow
+>   reports/module-validate/my-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.
+
+---
+
+## Scenario 4: "We're going live next week — are we ready?"
+
+**Situation:** Pre-production readiness check before go-live.
+
+**Step 1: Run RFL assessment**
+```
+Run a Ready For Launch assessment
+```
+Analyzes:
+- All deployed workflows (structure, orphaned rulesets, trigger coverage)
+- Custom rules (code quality, test coverage, GraphQL usage)
+- Settings (missing keys, invalid values)
+- Integration points (webhook configuration)
+- Architecture (entity relationships, cross-workflow dependencies)
+
+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 (RETAILER vs ACCOUNT).
+
+**Step 3: Check event health**
+```
+Show me event failure rates and NO_MATCH events for the last 24 hours
+```
+Queries Prometheus metrics or Event API, runs anomaly detection, and reports:
+- Failure rate (threshold: >5%)
+- NO_MATCH events (any = critical — means workflow gaps)
+- 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"
+
+**Situation:** You need a clean retailer environment with locations, networks, inventory, and test data.
+
+**Step 1: Bootstrap (new account)**
+```
+Bootstrap a new Fluent account from scratch
+```
+Walks through: profile creation, retailer setup, reference module installation, sample data.
+
+> **Important:** `/fluent-bootstrap` is not the same as `/fluent-connect`. Bootstrap is a high-impact, account-sensitive workflow. Expect planning/approval gates, confirmation prompts for irreversible steps, and pauses while you populate module config values or fix account-specific entitlement issues.
+
+**Or configure an existing retailer:**
+```
+Set up a warehouse location called "Sydney DC" with 24/7 hours
+```
+Creates the location via GraphQL with proper `openingSchedule`.
+
+**Step 2: Create test data**
+```
+Create a test HD order with 2 items
+```
+Auto-discovers available products, locations, and customers from the live environment. Generates a valid order payload — no hardcoded refs.
+
+**Step 3: Run smoke test**
+```
+Run an E2E test of the full HD order flow
+```
+Creates order → fires events through each status → asserts transitions → reports results. On failure, automatically runs event forensics to show exactly where it broke.
+
+---
+
+## Scenario 6: "Monitor production event processing"
+
+**Situation:** Ongoing operational monitoring of event health.
+
+**Quick health check:**
+```
+Run a health check on event processing
+```
+Single call that checks failure rates, NO_MATCH events, pending queues, and event dominance.
+
+**Detailed metrics:**
+```
+Show me the top 20 events by volume in the last 6 hours
+```
+Aggregates events by name + entity type + status, ranks by volume, shows failure rates per event.
+
+**SLO report:**
+```
+Generate an SLO report for the last 24 hours
+```
+Computes event volume, failure/NO_MATCH/pending rates, p95 runtime and inflight latency. Flags any threshold breaches.
+
+**Deep dive on failures:**
+```
+What are the top failing events? Show me details
+```
+Lists top failing events with counts, then drills into specific failures with `event_flowInspect`.
+
+---
+
+## Scenario 7: "I need to understand the event model"
+
+**Situation:** You're new to Fluent's event-driven architecture and need to understand how events work.
+
+```
+How does event routing work in Fluent? What are the event types and statuses?
+```
+Explains:
+- Event types (ORCHESTRATION, API, ORCHESTRATION_AUDIT)
+- Event categories (GENERAL, ACTION, CUSTOMER)
+- Event statuses (SUCCESS, FAILED, NO_MATCH, PENDING, SCHEDULED)
+- The routing model (how events match to workflow rulesets via triggers)
+- Run-once workflows and scheduled events
+- How to query and filter events for debugging
+
+---
+
+## Scenario 8: "Deploy a workflow change safely"
+
+**Situation:** You've modified a workflow and need to deploy it without breaking production.
+
+**Step 1: Diff the changes**
+```
+Compare the current ORDER::HD workflow with my modified version
+```
+Shows added/removed/modified rulesets, risk assessment (removing rulesets = HIGH risk), and before/after state diagrams.
+
+**Step 2: Validate connections**
+```
+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: Run pre-deploy quality gates**
+```
+Run pre-deploy checks for this workflow change
+```
+`/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.
+
+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 MY_RETAILER
+```
+`/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. 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 10,000 inventory positions from an external system.
+
+**Step 1: Create the batch job**
+```
+Create a batch ingestion job for inventory positions
+```
+`/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) 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
+```
+Provide the scope doc (paste it, or point to a file). `/fluent-scope-plan` 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.
+
+---
+
+## Scenario 11: "Onboard existing source into a proper module"
+
+**Situation:** You have Java rule classes from another team or a decompiled JAR, but they're not in Fluent Commerce module format. You need a buildable, deployable module.
+
+**Step 1: Onboard the source**
+```
+Refactor this code into a Fluent module: accounts/MY_PROFILE/SOURCE/backend/.decompiled/fc-module-ext/
+```
+Or for loose Java files:
+```
+/fluent-module-convert ./my-rules/ --module-name my-returns
+```
+
+The skill:
+1. **Analyzes** the existing layout (decompiled JAR? loose files? Gradle project? partial module?)
+2. **Discovers** all rule classes (by `@RuleInfo`, `BaseRule` extension, `run()` methods)
+3. **Plans** the target Maven multi-module structure with a full file operations table
+4. **Waits for your approval** before changing anything
+
+**Step 2: Review the plan**
+
+The plan shows exactly what will happen:
+- Which files move where
+- What code changes are needed (package renames, base class fixes, missing annotations)
+- Risk assessment (package renames breaking imports, decompiled artifacts, key conflicts)
+
+**Step 3: Execute and validate**
+
+After approval:
+- Creates the Maven multi-module directory structure
+- Moves and repackages Java files
+- Fixes structural issues (wrong base class, missing `@RuleInfo`, etc.)
+- Generates `module.json` with all rule registrations
+- Generates build scripts, POMs, `.gitignore`
+- Generates test skeletons for untested rules
+- Runs `/fluent-module-validate` to verify structure
+- Attempts a Maven build to verify compilation
+- Cross-references against deployed rules
+
+**Supports these input types:**
+- Decompiled JAR output (`.decompiled/` directories)
+- Loose Java files (no build system)
+- Non-standard Maven projects
+- Gradle projects (converted to Maven)
+- Existing modules with structural issues (repair mode)
+
+---
+
+## 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 12 phases:
+
+| Phase | What happens | Output |
+|---|---|---|
+| 0. Mode detection | Detect input mode — vague idea vs structured requirements | Mode selection |
+| 1. Feature identity | Define the feature boundary — what's in, what's out | Scope statement |
+| 2. Actors & triggers | Identify who interacts (customer, store staff, OMS, WMS) | Actor registry |
+| 3. User journeys | Walk through each user journey step by step | Structured use case list |
+| 4. Entities & data | Define entities, subtypes, and relationships | Entity relationship diagram |
+| 5. Business rules | Capture validation rules, constraints, edge cases | Rules inventory |
+| 6. Integrations | Webhooks, external systems, scheduled jobs | Integration map |
+| 7. UI & actions | User interface requirements and user actions | UI requirements |
+| 8. Constraints & risks | Non-functional requirements, risks, edge cases | Risk register |
+| 9. Acceptance criteria | Testable acceptance criteria per use case | Criteria list |
+| 10. Review & gap analysis | Compare requirements against existing environment | Completeness score |
+| 10b. Self-critique | Automated critique loop for spec quality | Refined spec |
+
+**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 my-extensions module?
+```
+`/fluent-build` 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 my-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
+```
+37 quality gates across 9 phases. If all pass → READY. If any critical gate fails → BLOCKED with specific fix instructions.
+
+**Step 5: Deploy**
+```
+Deploy to MY_RETAILER
+```
+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-build` 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` 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-my-returns 1.4.0 | Installed to MY_RETAILER |
+
+**Machine-readable export:**
+```
+Export a JSON audit trail
+```
+`/fluent-session 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` 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 my-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 | MY_RETAILER | IN_PROGRESS | APPROVED | APPROVED | 2 | /fluent-build |
+| return-order | MY_RETAILER | VERIFIED | APPROVED | APPROVED | 1 | — |
+| loyalty-points | MY_RETAILER | 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: "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 20: "Preview what the UI will look like before building"
+
+**Situation:** You've planned a new UI component or manifest change and want to verify how it will look in the live app before committing to the full build cycle.
+
+```
+Preview what the appeasement card looks like on the order detail page
+```
+
+`/fluent-mystique-preview` operates in three modes:
+
+| Mode | What it does | When to use |
+|------|-------------|-------------|
+| **ADD** | Injects a new component into the live app via JavaScript | You're building a new section/card |
+| **MODIFY** | Overlays changes on an existing component | You're updating an existing page element |
+| **REMOVE** | Hides an existing component temporarily | You're removing a section |
+
+**What happens:**
+
+1. **AI builds a preview spec** — component type, data sources, layout, and injection point
+2. **Reads live app DOM** — `take_snapshot` maps the current page structure
+3. **Injects preview via JavaScript** — no manifest changes, no deploy required
+4. **Takes before/after screenshots** — annotated with green (ADD), amber (MODIFY), red (REMOVE) glow
+5. **Iterative refinement loop** — you give feedback ("move it above the status bar", "change the label"), AI adjusts and re-injects
+6. **Approval or skip** — `preview: "APPROVED"` in status.json gates the manifest build
+
+**Artifacts created:**
+
+| Artifact | Path |
+|----------|------|
+| Before screenshot | `accounts/<PROFILE>/reports/preview/before-<timestamp>.png` |
+| After screenshot | `accounts/<PROFILE>/reports/preview/after-<timestamp>.png` |
+| Preview spec | `accounts/<PROFILE>/reports/preview/preview-spec.json` |
+| Status updated | `features/<slug>/status.json` → `preview: "APPROVED"` |
+
+**Skill chain:** `fluent-mystique-preview` → (on approval) → `fluent-mystique-builder` → `fluent-mystique-assess`
+
+Read-only phase (preview) has no planning gate. The manifest build that follows requires an approved plan.
+
+---
+
+## 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/MY_PROFILE/
+  SOURCE/                           (2 backend repos)
+    backend/
+      fc-module-my-extensions/      (97 rules, v1.4.0)
+      fc-module-my-returns/         (3 rules, v1.0.0)
+    frontend/                       (SDK component projects)
+  workflows/MY_RETAILER/            (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/my-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-assess` 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-assess` runs ~50 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-assess` 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.
+
+### Scenario: Verify a Deployed Manifest in the Browser
+
+**You say:** "Test the OMS orders page in the browser"
+
+**What happens:**
+1. `/fluent-ui-test` checks that Chrome DevTools MCP is connected (the `chrome-devtools` server must be configured in `.mcp.json`)
+2. Navigates to the OMS app URL, handles login if needed (asks you for credentials)
+3. Navigates to the `/oms/orders` route
+4. Takes a DOM snapshot to verify: page loads without errors, list component renders with data, pagination controls present, search/filter functional
+5. Checks `list_console_messages` for React or GraphQL errors
+6. Captures a screenshot for visual confirmation
+
+**You get:** A pass/fail report with checks (login, page load, data load, component rendering) and screenshot evidence. Issues are reported with severity (CRITICAL for page errors, MEDIUM for missing components, LOW for stale cache).
+
+**Prerequisites:** Chrome DevTools MCP configured in `.mcp.json`, manifest already deployed via `setting_upsert`, `FLUENT_USERNAME` and `FLUENT_PASSWORD` set as environment variables.
+
+### Scenario: Deep-Link to a Specific Location or Retailer Context
+
+**You say:** "Test the Store app waves page for location LOC_SYD_001"
+
+**What happens:**
+1. `/fluent-ui-test` constructs a deep-link URL with the context pre-selection parameter:
+   `store/#/waves?user.location.ref=LOC_SYD_001`
+2. The Mystique app reads the URL parameter (highest priority), resolves the location, and persists the selection to `localStorage["mystique.auth.context.location"]`
+3. All subsequent navigation stays in that location context until the user switches
+
+**Context resolution order** (both Store and OMS apps):
+
+| Priority | Source | Example |
+|----------|--------|---------|
+| 1 (highest) | URL parameter | `?user.location.ref=LOC_SYD_001` (Store) or `?user.retailer.ref=RET_001` (OMS) |
+| 2 | localStorage | `mystique.auth.context.location` (Store) or `mystique.auth.context.retailer` (OMS) |
+| 3 (fallback) | First accessible entity | First location/retailer the user has permission to access |
+
+**Key details:**
+- URL parameters go **after** the hash path: `store/#/waves?user.location.ref=...` (not before the `#`)
+- localStorage stores the entity **ID** (not the ref) — the app resolves the ref to an ID on first use
+- OMS equivalent: `oms/#/orders?user.retailer.ref=RET_001` with `mystique.auth.context.retailer`
+- The manifest must have `context.switcher: true` for the context dropdown to appear in the UI
+
+**Full reference:** `knowledge/platform/mystique-routing.md` § Context Switching
+
+---
+
+## 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:
+
+| Layer | What it does |
+|-------|-------------|
+| **AI Skills** (knowledge layer) | Teach the AI *how* to do Fluent tasks — patterns, decision trees, best practices |
+| **MCP Extension Server** (execution layer) | 55+ tools for real API operations — GraphQL queries, event dispatch, metrics, batch ingestion, workflow fetch, cache, connections, planning |
+| **Official MCP Server** (CLI layer) | Workflow listing, downloading, GraphQL validation via the Fluent CLI |
+| **Chrome DevTools MCP** (browser layer) | Browser automation for UI testing — login, navigate, snapshot, screenshot (optional, for `/fluent-ui-test`) |
+| **Fluent Commerce API** (platform) | The actual REST/GraphQL endpoints being called |
+
+### 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.
+
+---
+
+## Evidence and Confidence
+
+Analysis outputs include confidence levels based on available evidence:
+
+| Evidence available | Confidence | What you get |
+|---|---|---|
+| Workflow JSON + `plugin_list` only | LOW-MEDIUM | Structure is accurate; rule behavior is inferred from descriptions |
+| + Decompiled JAR (bytecode) | MEDIUM-HIGH | Implementation logic visible but variable names may be synthetic |
+| + Original source code | HIGH | Full logic, test coverage, and prop validation |
+| + Runtime evidence (real entity trace) | HIGHEST | Static analysis validated against actual execution |
+
+When evidence is incomplete, the AI flags it explicitly and recommends how to get higher confidence (provide source, run a test entity, etc.).
+
+---
+
+## Known Limitations
+
+| Capability | Status | Workaround |
+|-----------|--------|-----------|
+| 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-module-convert` |
+| 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 profile update YOUR_PROFILE --username <user> --password <new-pass>` to refresh credentials. For OAuth: verify `FLUENT_CLIENT_ID`/`FLUENT_CLIENT_SECRET`/`FLUENT_USERNAME`/`FLUENT_PASSWORD` environment variables are set correctly. |
+| `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.
+
+**"I keep getting permission prompts"**
+- First-run connect/bootstrap flows usually need shell and filesystem access so the AI can run `fluent` / `npx`, read `~/.fluentcommerce/`, and write `.mcp.json` plus `accounts/`
+- That is separate from the planning gate. Tool permissions are IDE sandbox prompts; the approval gate is the skill asking whether it should proceed with a planned change
+
+**"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: see [install guide](https://docs.fluentcommerce.com/building-blocks/fluent-cli-package)
+- The profile must have the retailer associated — verify with `fluent profile retailers 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.
+
+**"Bootstrap got part-way through and then stopped"**
+- That usually means account-specific setup needs attention: missing retailer context, missing credentials, incomplete module config values, or environment permissions
+- Re-run with the exact error and treat `/fluent-bootstrap` as a guided workflow, not a guaranteed one-shot installer
+
+**"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.
+
+---
+
+## Further Reading
+
+- [Prompt Guide](02-prompt-guide.md) — Which skills exist, what to type, agent routing, lifecycle stages
+- [Dev Workflow](06-dev-workflow.md) — Full development lifecycle with all phases
+- [Chrome DevTools MCP](chrome-devtools-mcp-reference.md) — Browser automation and UI testing reference