@fluentcommerce/ai-skills 0.1.0 → 0.2.0

package/README.md

@@ -1,9 +1,5 @@
 # @fluentcommerce/ai-skills
 
-[![npm version](https://img.shields.io/npm/v/@fluentcommerce/ai-skills.svg)](https://www.npmjs.com/package/@fluentcommerce/ai-skills)
-[![license](https://img.shields.io/npm/l/@fluentcommerce/ai-skills.svg)](https://opensource.org/licenses/MIT)
-[![node](https://img.shields.io/node/v/@fluentcommerce/ai-skills.svg)](https://nodejs.org/)
-
 > **Alpha** — This package is under active development. Skill content, CLI options, and supported targets may change between releases without notice. Use in non-production environments and pin to a specific version if stability matters.
 
 Modular [Fluent Commerce](https://fluentcommerce.com) AI skill packs for coding assistants.
@@ -113,7 +109,7 @@ For non-Claude targets, the installer writes a managed block (`<!-- fluent-ai-sk
 | `mcp-official` | Official Fluent CLI MCP server operations | `/fluent-mcp-core` |
 | `mcp-extn` | Extension MCP tools (events, transitions, GraphQL, metrics, batch) | `/fluent-mcp-tools` |
 | `rfl` | Ready For Launch assessments | `/fluent-rfl-assess` |
-| `dev` | Feature planning (with universal NEW/EXISTING/MODIFIED/REUSED/OOTB classification), workflow builder, workflow deploy, analyzer, connection analysis (with `--validate` static-vs-dynamic comparison and cross-entity event tracing), custom code analysis, transition API, rule scaffold, module scaffold, data module scaffold, source onboarding, module validation, build, version management, trace, event API (model + causality analysis), system monitoring, batch ingestion, E2E, test data, settings (with Phase 2B value format validation and cascading scope resolution), environment setup, pre-deploy checks, session summary, session audit export, scope decomposition, feature explanation, Mermaid diagram validation | `/fluent-feature-plan` `/fluent-workflow-builder` `/fluent-workflow-deploy` `/fluent-workflow-analyzer` `/fluent-connection-analysis` `/fluent-custom-code` `/fluent-transition-api` `/fluent-rule-scaffold` `/fluent-module-scaffold` `/fluent-data-module-scaffold` `/fluent-source-onboard` `/fluent-module-validate` `/fluent-build` `/fluent-version-manage` `/fluent-trace` `/fluent-event-api` `/fluent-system-monitoring` `/fluent-job-batch` `/fluent-e2e-test` `/fluent-test-data` `/fluent-settings` `/fluent-retailer-config` `/fluent-session-summary` `/fluent-scope-decompose` `/fluent-pre-deploy-check` `/fluent-session-audit-export` `/fluent-feature-explain` |
+| `dev` | Feature planning (with universal NEW/EXISTING/MODIFIED/REUSED/OOTB classification), workflow builder, analyzer, connection analysis (with `--validate` static-vs-dynamic comparison and cross-entity event tracing), custom code analysis, transition API, rule scaffold, module scaffold, source onboarding, module validation, build, version management, trace, event API (model + causality analysis), system monitoring, batch ingestion, E2E, test data, settings (with Phase 2B value format validation and cascading scope resolution), environment setup, pre-deploy checks, session summary, session audit export, scope decomposition, feature explanation, sourcing framework reference | `/fluent-feature-plan` `/fluent-workflow-builder` `/fluent-workflow-analyzer` `/fluent-connection-analysis` `/fluent-custom-code` `/fluent-transition-api` `/fluent-rule-scaffold` `/fluent-module-scaffold` `/fluent-source-onboard` `/fluent-module-validate` `/fluent-build` `/fluent-version-manage` `/fluent-trace` `/fluent-event-api` `/fluent-system-monitoring` `/fluent-job-batch` `/fluent-e2e-test` `/fluent-test-data` `/fluent-settings` `/fluent-retailer-config` `/fluent-session-summary` `/fluent-scope-decompose` `/fluent-pre-deploy-check` `/fluent-session-audit-export` `/fluent-feature-explain` `/fluent-sourcing` |
 
 > Slash commands are Claude Code specific. Other targets receive the same knowledge as merged instruction content.
 
@@ -155,9 +151,8 @@ Event API source docs are curated into skills via selective extraction; they are
 | Validate | `/fluent-module-validate` | Check module structure, version consistency, rule wiring, test coverage; cached report with content hash |
 | Version | `/fluent-version-manage` | Read, bump, sync, and tag versions across POM files, module.json, and CHANGELOG |
 | Build | `/fluent-build` | Version bump, Maven compile, ZIP packaging |
-| Pre-deploy | `/fluent-pre-deploy-check` | 26 quality gates across 8 phases (env, module, workflow, connections, settings, target, risk, completeness) |
-| Deploy module | `/fluent-module-deploy` or `flow-run` | Module install via CLI |
-| Deploy workflow | `/fluent-workflow-deploy` | Workflow upload via MCP tool, REST API fallback, CLI last resort |
+| Pre-deploy | `/fluent-pre-deploy-check` | 25 quality gates across 8 phases (env, module, workflow, connections, settings, target, risk, completeness) |
+| Deploy | `/fluent-module-deploy` or `flow-run` | Module install or REST workflow upload |
 | Test | `/fluent-e2e-test` | Create entities, fire events, poll states, assert transitions |
 | Test data | `/fluent-test-data` | Discover retailer environment and generate valid test entity payloads |
 | Settings | `/fluent-settings` | Manage retailer settings — discover, audit (with Phase 2B value format validation), create/update, migrate; cascading scope resolution (RETAILER -> ACCOUNT) for module-installed settings |
@@ -165,6 +160,7 @@ Event API source docs are curated into skills via selective extraction; they are
 | Diagnose | `/fluent-trace`, `/fluent-event-api` | Trace failed events, correlate with rulesets, and build causality chains across parent/child events |
 | Fix | (routes back to Implement/Build/Deploy) | Apply fix based on diagnosis, re-test |
 | Explain | `/fluent-feature-explain` | Reverse-engineer existing feature into a Feature Architecture Document with Mermaid diagrams, data flow, and runtime evidence; tiered analysis (plugin.list → decompiled JAR / source code → runtime), auto-discovers entities, JAR decompilation fallback, Analysis Confidence section; saved to `accounts/<PROFILE>/analysis/features/` |
+| Sourcing | `/fluent-sourcing` | Reference for sourcing profiles, strategies, conditions, criteria, scoring algorithms, permutation search, custom extensions, and GraphQL patterns |
 | Audit | `/fluent-session-summary`, `/fluent-session-audit-export` | Track all changes made during session; export machine-readable JSON audit trail |
 
 Artifacts from custom code analysis are written to `accounts/<PROFILE>/analysis/custom-code/` and reused by other skills (workflow-analyzer, trace, rule-scaffold, etc.). A `fingerprint.json` file is used to detect input changes and skip re-parsing when nothing changed. Module validation reports are written to `accounts/<PROFILE>/analysis/module-validate/` with a content hash — re-validation is skipped when the module source is unchanged.
@@ -390,7 +386,7 @@ This clones the `fluent-mcp-extn` source into your project, builds it, and wires
 cd fluent-ai-skills && npm pack
 
 # Install from tarball on any machine
-npx ./fluentcommerce-ai-skills-0.0.1.tgz install
+npx ./fluentcommerce-ai-skills-0.2.0.tgz install
 ```
 
 ## End-to-End Validation (Recommended)
@@ -577,13 +573,11 @@ flowchart TD
     B -->|"claude (default)"| C["~/.claude/agents + ~/.claude/skills"]
     B -->|"cursor"| D[".cursor/rules/*.mdc"]
     B -->|"copilot"| E[".github/copilot-instructions.md"]
-    B -->|"vscode"| F[".github/copilot-instructions.md"]
-    B -->|"windsurf"| G[".windsurfrules"]
-    B -->|"codex"| H["AGENTS.md"]
-    B -->|"gemini"| I["GEMINI.md"]
-    A --> J{"groups specified?"}
-    J -->|"no"| K["install all groups"]
-    J -->|"yes"| L["install selected groups only"]
+    B -->|"windsurf"| F[".windsurfrules"]
+    B -->|"codex"| G["AGENTS.md"]
+    A --> H{"groups specified?"}
+    H -->|"no"| I["install all groups"]
+    H -->|"yes"| J["install selected groups only"]
 ```
 
 ### flow-run Execution

package/content/cli/skills/fluent-bootstrap/SKILL.md

@@ -12,6 +12,15 @@ Complete account setup from profile creation to sample data installation.
 
 ## Planning Gate
 
+### Pre-flight: Plan Verification
+
+Before proceeding, check for an existing approved plan:
+
+1. **Search** `accounts/<PROFILE>/plans/` for a file with `Status: APPROVED` that covers this bootstrap
+2. **If multi-artifact work** (bootstrap + custom rules + workflows): STOP. Invoke `/fluent-feature-plan` first — this skill cannot be used for multi-artifact work without a feature plan
+3. **If approved plan found:** Skip to implementation, referencing the plan's relevant sections
+4. **If no plan found:** Continue to the Planning Gate below to write a plan for this skill
+
 **Before bootstrapping any account, write a plan using the template from `PLAN_TEMPLATE.md` in the `fluent-feature-plan` skill.** Account bootstrap is a high-impact operation.
 
 **Bootstrap-specific emphasis — ensure these are covered:**

package/content/cli/skills/fluent-cli-reference/SKILL.md

@@ -610,414 +610,6 @@ No `.test.` or `.sandbox.` qualifier = **production** — proceed with caution.
 
 ---
 
-## Module Types
-
-Fluent modules fall into three categories:
-
-| Type | Description | Contains Plugins? | Examples |
-|------|-------------|-------------------|----------|
-| **Reference** | Core Fluent-provided modules that deliver standard OMS functionality. Downloaded by name during `module install`. | Yes (OOTB rules) | `core`, `fulfilment`, `order`, `inventory` |
-| **Extension** | Custom modules built by implementation teams. Contain Java plugin code (business rules), workflow fragments, settings, and data assets. | Yes (custom rules) | `fc-module-custom-extensions`, `fc-module-returns` |
-| **Data** | Modules that carry only data assets (locations, products, inventory, settings) with no plugin code. Used for environment seeding, test data, or retailer-specific configuration. | No | `b2c-sample-data`, `product-catalog-data` |
-
-**Reference modules** are versioned and hosted by Fluent. Install them by name:
-```bash
-fluent module install core -p <profile> -r <retailer>
-```
-
-**Extension and Data modules** are built locally and installed from a path or ZIP:
-```bash
-fluent module install dist/my-module-1.0.0.zip -p <profile> -r <retailer> -c <config>
-```
-
----
-
-## Module Dependencies
-
-Reference modules have a strict install order. Installing out of order causes `Module dependency '<module>' not installed` errors.
-
-| Order | Module | Dependencies | What It Provides |
-|-------|--------|-------------|------------------|
-| 1 | `core` | None | Base entity types, OOTB rules (SetState, SendEvent, etc.), core workflows |
-| 2 | `fulfilment` | `core` | Fulfilment workflows, wave management, pick/pack rules |
-| 3 | `order` | `core`, `fulfilment` | Order workflows (HD, CC), fulfilment options, sourcing |
-| 4 | `inventory` | `core` | Inventory management, catalogue rules, stock adjustments |
-| 5 | Custom extensions | Varies (check `module.json`) | Your business logic, custom rules, workflow fragments |
-
-**Always verify dependencies before install:**
-```bash
-fluent module describe <module-source>   # shows module.json including dependencies
-fluent module list -p <profile>          # shows what is already installed
-```
-
-**Common sequence for a new retailer:**
-```bash
-fluent module install core       -p <profile> -r <retailer> -c <core-config>
-fluent module install fulfilment -p <profile> -r <retailer> -c <fulfilment-config>
-fluent module install order      -p <profile> -r <retailer> -c <order-config>
-fluent module install inventory  -p <profile> -r <retailer> -c <inventory-config>
-fluent module install dist/my-extension.zip -p <profile> -r <retailer> -c <ext-config>
-```
-
----
-
-## Config Prefix System
-
-The CLI uses a **prefix system** in `module.config.<retailer>.<module>.json` files to scope variable values to specific asset contexts. This allows the same variable name to resolve to different values in workflows vs. settings vs. data assets.
-
-### Prefix Format
-
-Config keys follow the pattern: `<prefix>:<variable.name>`
-
-| Prefix | Applies To | Specificity | Example |
-|--------|-----------|-------------|---------|
-| `default:` | All assets (workflows, settings, data) | 0 (lowest, fallback) | `"default:network.ref": "NET_DEFAULT"` |
-| `workflow:` | Workflows only | 0 | `"workflow:notification.enabled": "true"` |
-| `workflow:<type>:` | Workflows matching entity type | 1 | `"workflow:order:network.ref": "NET_ORDER"` |
-| `workflow:<type>:<subtype>:` | Workflows matching type + subtype | 2 (highest) | `"workflow:order:hd:carrier.ref": "HD_CARRIER"` |
-| `setting:` | Settings only | 0 | `"setting:api.timeout": "30000"` |
-
-### Specificity Rules
-
-The CLI counts colons in the prefix to determine specificity. More colons = higher priority. When two keys resolve to the same variable, the most specific wins. On a tie, the first key in the file wins.
-
-**Example resolution for workflow `ORDER::HD`:**
-```json
-{
-  "default:network.ref": "NET1",                    // specificity 0
-  "workflow:network.ref": "NET2",                   // specificity 0 (tie with default)
-  "workflow:order:network.ref": "NET3",             // specificity 1
-  "workflow:order:hd:network.ref": "NET4"           // specificity 2 — WINS
-}
-```
-
-Result: `[[network.ref]]` in the ORDER::HD workflow resolves to `"NET4"`.
-
-### Context-Based Filtering
-
-The CLI filters recognized prefixes based on which asset folder is being processed:
-
-| Asset Folder | Recognized Prefixes |
-|-------------|---------------------|
-| `assets/workflows/` | `default:`, `workflow:`, `workflow:<type>:`, `workflow:<type>:<subtype>:` |
-| `assets/settings/` | `default:`, `setting:` |
-| All other folders (locations, products, etc.) | `default:` only |
-
-**Important:** Data assets (users, locations, networks, products, carriers, etc.) only recognize the `default:` prefix. There is no `location:`, `network:`, or `product:` prefix.
-
-### Built-in Auto-Injected Variables
-
-These variables are always available without defining them in `module.config.json`:
-
-| Variable | Description |
-|----------|-------------|
-| `account.id` | Account identifier (used in rule name prefixes) |
-| `retailer.id` | Retailer numeric ID |
-| `retailer.ref` | Retailer reference string |
-| `retailer.name` | Retailer trading name |
-
-**Note:** `account.host` is NOT auto-injected. Define it in config if needed (e.g., `"default:account.host": "acme.sandbox.api.fluentretail.com"`).
-
-### Config Example
-
-**module.config.RETAILER_A.my-module.json:**
-```json
-{
-  "default:network.ref": "NETWORK_DEFAULT",
-  "default:catalogue.ref": "PC:MASTER:5",
-
-  "workflow:order:network.ref": "NETWORK_FULFILMENT",
-  "workflow:order:hd:carrier.ref": "HD_CARRIER",
-  "workflow:order:cc:carrier.ref": "CC_CARRIER",
-
-  "setting:api.timeout": "30000",
-  "setting:retry.count": "3"
-}
-```
-
----
-
-## Variable Syntax
-
-The CLI uses `[[variable]]` tokens in JSON and CSV asset files for environment-specific substitution during `module install`.
-
-| Syntax | Used In | Example |
-|--------|---------|---------|
-| `[[variable]]` | JSON/CSV assets, workflow fragments | `[[retailer.id]]`, `[[network.ref]]`, `[[account.id]]` |
-
-### Substitution Rules
-
-- **Only `[[...]]` is processed.** Other syntaxes (`${}`, `{{}}`) are NOT recognized.
-- **Unresolved tokens are left as-is.** The CLI does not error on missing values — it silently keeps the `[[token]]` in the output. Always check for unreplaced tokens before installing: `rg '\[\[.*\]\]' module.config.*.json`
-- **`module.config.json` is a values-only template.** Keys must be scoped with prefixes (`default:`, `workflow:`, `setting:`). Unscoped keys do not participate in substitution.
-- **Config values must be scalars** (string, number, boolean). If your template uses metadata objects with `type`/`description` fields, replace them with real values before installing.
-
-### Variable Flow
-
-1. Define variables in `resources/module.config.json` (template)
-2. Use `[[variable]]` tokens in asset files under `resources/assets/`
-3. Run `fluent module config <module> -p <profile> -r <retailer>` to generate a config file
-4. Edit the generated `module.config.<retailer>.<module>.json` with real values
-5. Install with `fluent module install <module> -c <config-file> ...`
-
----
-
-## Module Structure
-
-Complete canonical directory layout for a Fluent CLI module:
-
-```
-my-module/
-|
-+-- resources/                          <- Module content root
-|   |
-|   +-- module.json                     <- Module metadata (name, version, dependencies)
-|   +-- module.config.json              <- Variable template (required; can be empty {})
-|   |
-|   +-- assets/                         <- All deployable assets
-|       +-- workflows/                  <- Workflow JSON files (*.json)
-|       +-- settings/                   <- Settings JSON files (*.json)
-|       +-- locations/                  <- Location JSON files (*.json)
-|       +-- users/                      <- User JSON files (*.json)
-|       +-- roles/                      <- Role JSON files (*.json)
-|       +-- networks/                   <- Network JSON files (*.json)
-|       +-- carriers/                   <- Carrier JSON files (*.json)
-|       +-- product-catalogues/         <- Product catalogue JSON files (*.json)
-|       +-- categories/                 <- Category CSV files (*.csv)
-|       +-- products/                   <- Product CSV files (*.csv)
-|       +-- inventory-catalogues/       <- Inventory catalogue JSON files (*.json)
-|       +-- inventory/                  <- Inventory CSV files (*.csv)
-|       +-- virtual-catalogues/         <- Virtual catalogue JSON files (*.json)
-|       +-- control-groups/             <- Control group JSON files (*.json)
-|       +-- controls/                   <- Control JSON files (*.json)
-|       +-- storage-areas/              <- Storage area JSON files (*.json)
-|       +-- payment-service-providers/  <- PSP JSON files (*.json)
-|       +-- workflow-fragments/         <- Workflow fragment files (optional)
-|           +-- <workflow-name>/        <- Subfolder per target workflow
-|               +-- *.json
-|
-+-- plugins/                            <- Java plugin code (optional, extension modules only)
-|   +-- pom.xml                         <- Maven parent POM
-|   +-- rules/                          <- Business rule Java classes
-|   +-- types/                          <- Model/DTO Java classes
-|   +-- util/                           <- Utility Java classes
-|
-+-- scripts/
-|   +-- build-module.sh                 <- Build script
-|
-+-- dist/                               <- Build output (created after build)
-    +-- my-module-1.0.0.zip             <- Deployable module package
-```
-
-**Key notes:**
-- `module.config.json` is required even if empty (`{}`).
-- `plugins/` is only present in extension modules with custom Java rules.
-- Workflow fragments must be in subfolders under `workflow-fragments/` named after the target workflow. Files placed directly under `workflow-fragments/` are ignored.
-- `module.json` defines `name`, `version`, `title`, `description`, `authors`, `dependencies`, and `contracts`.
-
-**module.json example:**
-```json
-{
-  "_schema": "1.0.0",
-  "name": "sample/custom-extensions",
-  "version": "1.0.0",
-  "title": "Custom Extensions",
-  "description": "Custom business rules and workflow extensions",
-  "authors": [{ "name": "Implementation Team" }],
-  "dependencies": [],
-  "contracts": []
-}
-```
-
----
-
-## Selective Asset Installation
-
-Use `--include` and `--exclude` flags on `module install` to deploy only specific asset types. Paths match folder names inside the module's `assets/` directory.
-
-### Filterable Paths
-
-| Path | Asset Type |
-|------|-----------|
-| `workflows` | Workflow JSON files |
-| `settings` | Settings JSON files |
-| `rules` | Java plugin JARs |
-| `locations` | Location definitions |
-| `users` | User definitions |
-| `roles` | Role definitions |
-| `networks` | Network definitions |
-| `carriers` | Carrier definitions |
-| `products` | Product CSV data |
-| `categories` | Category CSV data |
-| `inventory` | Inventory CSV data |
-| `product-catalogues` | Product catalogue definitions |
-| `inventory-catalogues` | Inventory catalogue definitions |
-| `virtual-catalogues` | Virtual catalogue definitions |
-| `workflow-fragments` | Workflow fragment files |
-
-### Common Scenarios
-
-**Skip workflows for multi-retailer installs** (when each retailer has unique workflows):
-```bash
-fluent module install dist/my-module.zip -p <profile> -r <retailer> --exclude workflows
-```
-
-**Plugin-only update** (recompiled Java rules, workflows/settings unchanged):
-```bash
-fluent module install dist/my-module.zip -p <profile> -r <retailer> --include rules --force
-```
-
-**Workflows + settings only** (common update pattern):
-```bash
-fluent module install dist/my-module.zip -p <profile> -r <retailer> \
-  --include workflows settings --force
-```
-
-**Production install without test data:**
-```bash
-fluent module install dist/my-module.zip -p <profile> -r <retailer> \
-  --exclude products inventory categories
-```
-
-**Large dataset chunking** (avoid timeouts):
-```bash
-# Step 1: Infrastructure (everything except bulk data)
-fluent module install dist/my-module.zip -p <profile> -r <retailer> --exclude products inventory
-
-# Step 2: Products (with increased wait)
-fluent module install dist/my-module.zip -p <profile> -r <retailer> --include products --wait 5000
-
-# Step 3: Inventory
-fluent module install dist/my-module.zip -p <profile> -r <retailer> --include inventory --wait 5000
-```
-
-**Fast dev iteration** (deploy only what changed):
-```bash
-# Full install first time
-fluent module install dist/my-module.zip -p dev -r DEV -c config.json
-
-# Subsequent iterations — only changed assets
-fluent module install dist/my-module.zip -p dev -r DEV --include workflows --force
-```
-
----
-
-## Workflow Fragment Strategies
-
-Workflow fragments use `mergeStrategy` on rulesets, rules, statuses, and triggers to control how they combine with the base workflow during `module install` or `workflow merge`.
-
-| Strategy | Behavior | When to Use |
-|----------|----------|-------------|
-| **`merge`** | Adds or updates rules/triggers/userActions within an existing ruleset. New rulesets are added. Duplicate rules (same name + props) are ignored. Use `index` on rules to control insertion position. | Adding custom logic to reference module rulesets. Extending without breaking existing rules. |
-| **`replace`** | Completely replaces the entire matched ruleset (or rule/status/trigger). The fragment's content becomes the new content. | Replacing obsolete logic. Taking full ownership of a ruleset. |
-| **`keep`** | Preserves the original element from the base workflow. The fragment's element is ignored if a match exists. | Conditional additions — only add if not already present. Safe defaults. |
-| **`delete`** | Removes the matched element from the workflow. No-op if the element does not exist. Processed before `replace` and `merge`. | Removing deprecated rulesets or rules. Cleanup during upgrades. |
-
-### Matching Keys
-
-Elements are matched for strategy resolution using these keys:
-
-| Element | Matching Key |
-|---------|-------------|
-| Rulesets | `name \| type \| subtype \| [trigger statuses]` |
-| Statuses | `name \| entityType` |
-| Triggers | `status` |
-| User Actions | `context[0].label` |
-
-### Fragment Location in Modules
-
-```
-resources/assets/workflow-fragments/<workflow-name>/*.json
-```
-
-Fragments are sorted alphabetically by filename and processed in order. Files directly under `workflow-fragments/` (not in a subfolder) are ignored.
-
-### Fragment Template
-
-```json
-{
-  "name": "ORDER::<SUBTYPE>",
-  "entityType": "ORDER",
-  "entitySubtype": "<SUBTYPE>",
-  "rulesets": [
-    {
-      "name": "<RULESET_NAME>",
-      "type": "ORDER",
-      "mergeStrategy": "merge",
-      "rules": [
-        {
-          "name": "[[account.id]].<module>.<RuleName>",
-          "mergeStrategy": "merge",
-          "index": 0,
-          "props": {
-            "yourProp": "<value>"
-          }
-        }
-      ],
-      "triggers": [{ "status": "CREATED" }],
-      "userActions": []
-    }
-  ]
-}
-```
-
----
-
-## Troubleshooting Quick Reference
-
-Top error messages from the Fluent CLI with causes and fixes.
-
-### Critical Errors
-
-| Error | Cause | Fix |
-|-------|-------|-----|
-| `Auth failed: 401 for <email>` | Invalid credentials or expired password | Update password: `fluent profile update <profile> --username <user> --password <new-pass>`. Purge sessions: `fluent profile purge-sessions`. |
-| `Module dependency '<module>' not installed` | Required module not present on account | Install dependencies in order: `core` -> `fulfilment` -> `order` -> `inventory` -> custom. Check `module.json` dependencies. |
-| `Invalid Module: core - a valid module should contain: assets folder, module.json file` | Module structure invalid or corrupt | Verify with `fluent module describe <module>`. Ensure `resources/module.json` and `resources/assets/` exist. |
-| `Request timeout` / `connect ETIMEDOUT` | Network timeout or API unavailable | Check network connectivity. Verify API endpoint is reachable. Retry command. Use `--wait` to increase delays. |
-
-### High Priority Errors
-
-| Error | Cause | Fix |
-|-------|-------|-----|
-| `Module not found: <module>` | Wrong module name or path | For reference modules use exact names: `core`, `fulfilment`, `order`. For local modules verify the path exists. |
-| `Profile '<name>' not found` | Profile does not exist | List profiles: `fluent profile list`. Create: `fluent profile create <name> ...`. |
-| `Retailer configuration is required but was not provided` | Missing `--retailer` flag or active context | Set active retailer: `fluent profile use <profile> --retailer <ref>`. Or add `--retailer <ref>` to the command. |
-| `Token '<placeholder>' not resolved` | Missing variable in config file | Run `fluent module config <module> -p <profile> -r <retailer>` to regenerate config. Fill all `[[...]]` placeholders before install. |
-| `Missing required option: --id` / `--email` | Required parameter omitted | Check command help: `fluent <command> --help`. Add the required flag. |
-
-### Medium Priority Errors
-
-| Error | Cause | Fix |
-|-------|-------|-----|
-| `Setting '<name>' not found` | Setting does not exist or wrong name | List settings with wildcard: `fluent setting list -p <profile> -r <retailer> --name '%<pattern>%'`. Check spelling and context. |
-| `Workflow '<name>' already exists` | Workflow conflict during install | Use `--exclude workflows` to skip, or `--force` to overwrite. |
-| `Invalid workflow definition` | Workflow JSON has structural errors | Validate JSON syntax. Check required fields: `name`, `entityType`, `statuses`, `rulesets`. |
-| `Workflow '<name>' not found` | Workflow does not exist in retailer | List workflows: `fluent workflow list -p <profile> -r <retailer>`. Verify spelling. |
-| `Fragment workflow file does not exist` | Fragment file path invalid | Verify the file exists at the specified path. Use absolute or correct relative path. |
-
-### Low Priority Warnings
-
-| Error | Cause | Fix |
-|-------|-------|-----|
-| `Command not found: fluent` | CLI not in PATH or not installed | Verify: `npm list -g fluent-cli`. Reinstall if needed. Check PATH includes npm global bin directory. |
-| `No active profile set` | No profile selected | Set active: `fluent profile use <profile> --retailer <retailer>`. |
-| `Module config file not found` | Config file missing or wrong name | Generate: `fluent module config <module> -p <profile> -r <retailer>`. Expected name: `module.config.<retailer>.<module>.json`. |
-| `Workflow log position '<pos>' not found` | Invalid log entry position | List logs: `fluent workflowlog describe <workflow> -p <profile> -r <retailer>`. Positions are 0-based. |
-
-### Quick Diagnostic Commands
-
-```bash
-fluent --version                           # Verify CLI installed
-fluent profile active                      # Check active profile/retailer
-fluent profile purge-sessions              # Clear cached tokens (fixes many auth issues)
-fluent --debug <command>                   # Enable verbose debug output
-fluent module describe <module-path>       # Validate module structure
-fluent module list -p <profile>            # Check installed modules on account
-```
-
----
-
 ## Quick Reference Card
 
 ```