# Fluent Commerce AI Skills & MCP Extension — Operational Reference

[![ai-skills](https://img.shields.io/npm/v/@fluentcommerce/ai-skills?label=ai-skills)](https://www.npmjs.com/package/@fluentcommerce/ai-skills) [![mcp-extn](https://img.shields.io/npm/v/@fluentcommerce/fluent-mcp-extn?label=mcp-extn)](https://www.npmjs.com/package/@fluentcommerce/fluent-mcp-extn)
> [!CAUTION]
> **🧪 EXPERIMENTAL — LABS PROJECT**
>
> This is **NOT production-ready**. It is an internal labs experiment under active development.
> No stability guarantees, no support, no warranty. Do NOT use in production without review.

> **Audience:** Fluent Commerce consultants, solution architects, and implementation partners.

---

## What this changes for you

| Before | After |
|--------|-------|
| Write workflow JSON by hand, look up field names | "Build an ORDER::RETURN workflow" — done in minutes |
| `grep` through 50 Java files to understand a feature | "Explain how Home Delivery works" — state diagrams + rules table |
| Copy-paste rule class boilerplate, wire annotations manually | "Create a rule called ValidateReturnWindow" — full class + test + module wiring |
| Manually query GraphQL + check event logs to debug an order | "Why is order HD-001 stuck in BOOKED?" — root cause + fix |
| Manually navigate manifest JSON to add a UI page | "Add an appeasement form to the order detail page" — validated JSON diff |
| Run deployment steps from a Confluence runbook by hand | "Deploy ORDER::HD to staging" — pre-flight gates → deploy → verify |

---

## Table of Contents

1. [Overview](#1-overview)
2. [Getting Started](#2-getting-started)
3. [Architecture](#3-architecture)
4. [MCP Server Setup](#4-mcp-server-setup)
5. [What Can You Do? (Quick Reference)](#5-what-can-you-do)
6. [Feature Lifecycle](#6-feature-lifecycle)
7. [Development Workflow](#7-development-workflow)
8. [MCP Extension Tools](#8-mcp-extension-tools)
9. [Deployment & Promotion Runbook](#9-deployment-and-promotion-runbook)
10. [Troubleshooting](#10-troubleshooting)
11. [CLI Reference](#11-cli-reference)
12. [Appendix: Capability Ownership Map](#12-appendix-capability-ownership-map)
13. [Workspace Setup](#13-workspace-setup)

---

## 1. Overview

### What is this?

AI coding assistants are general-purpose — they don't know Fluent Commerce. **Fluent AI Skills** injects Fluent-specific domain knowledge into Claude Code so it can analyze workflows, scaffold rules, run E2E tests, debug failed events, and manage settings — all through natural language.

```mermaid
graph LR
    U["👤 You"] -->|"natural language"| IDE["Claude Code"]
    IDE -->|"skills (domain knowledge)"| AI["AI Agent"]
    AI -->|"MCP tools (live API)"| FC["Fluent Commerce"]
    AI -->|"browser automation"| UI["Fluent UX Apps"]
```

### Where do I get it?

Both packages are on the **public npm registry** — no special tokens or registry config needed:

```bash
# This is all you need:
npx @fluentcommerce/ai-skills install --profile YOUR_PROFILE --profile-retailer "YOUR_RETAILER"
```

| Package | npm |
|---------|-----|
| `@fluentcommerce/ai-skills` | [npmjs.com/package/@fluentcommerce/ai-skills](https://www.npmjs.com/package/@fluentcommerce/ai-skills) |
| `@fluentcommerce/fluent-mcp-extn` | [npmjs.com/package/@fluentcommerce/fluent-mcp-extn](https://www.npmjs.com/package/@fluentcommerce/fluent-mcp-extn) |

### Key terms

| Term | Meaning |
|------|---------|
| **Profile** | A named Fluent CLI configuration pointing to an account (API URL + credentials). Created with `fluent profile create MY_PROFILE --id <id> --username <user> --password <pass> --client-secret <secret> --base-url <url>`. Used throughout as `<PROFILE>`. |
| **Retailer** | A tenant within the Fluent account. Most operations are retailer-scoped. You'll need the retailer reference string (e.g., `"My Retailer"`). |
| **Skill** | A structured instruction file that teaches the AI a specific Fluent task. Installed into Claude Code and usually invoked with `/fluent-<name>`. |
| **MCP** | Model Context Protocol — an open standard letting AI assistants call external tools. Gives the AI live access to Fluent APIs (query GraphQL, send events, read workflows, etc.). |

### What's included

| Component | Description |
|-----------|-------------|
| **@fluentcommerce/ai-skills** | 64 skills across CLI, dev, MCP, and RFL groups, 6 agents, plus packaged platform knowledge docs |
| **@fluentcommerce/fluent-mcp-extn** | MCP extension server — 45 tools for live Fluent API interaction |
| **fluent-mcp** (official) | Official Fluent CLI MCP server — workflows and GraphQL |
| **chrome-devtools** | Browser automation for UI testing (optional) |

**Installable skill groups:** CLI (10) · Dev (51) · RFL (1) · MCP (2)

**Supported IDE:** Claude Code

---

## 2. Getting Started

> **Full walkthrough:** See the [Getting Started Guide](getting-started.md) for a hands-on tutorial with your first debug and first feature build.

```mermaid
graph LR
    A["1. Install Fluent CLI<br/>docs.fluentcommerce.com/building-blocks/fluent-cli-package"] --> B["2. Create profile<br/>fluent profile create MY_PROFILE"]
    B --> C["3. Install skills<br/>npx @fluentcommerce/ai-skills install<br/>--profile MY_PROFILE"]
    C --> D["4. Connect workspace<br/>/fluent-connect"]
    D --> E["5. Start working<br/>Explain how HD works"]
```

**Install** (one command in an empty directory):
```bash
mkdir fluent-ai-workspace && cd fluent-ai-workspace
npx @fluentcommerce/ai-skills install --profile YOUR_PROFILE --profile-retailer "YOUR_RETAILER"
```

**Connect** (in Claude Code): `/fluent-connect` — downloads workflows, scans source, decompiles JARs, builds rule inventory.

**Start working:** `"Explain how Home Delivery works"`, `"Why is order HD-12345 stuck?"`, or `"Help me define use cases for return orders"`.

### Account directory reference

Directories are created by `/fluent-connect` on first connect (with README placeholders), then populated by individual skills.

| Directory | Created by | When | Persistent? | Contents |
|-----------|-----------|------|:-----------:|----------|
| `SOURCE/backend/` | `/fluent-connect`, `/fluent-module-scaffold` | On connect (clones repos) or scaffold | Yes | Java Maven projects: `pom.xml`, `src/main/java/`, `module.json` |
| `SOURCE/frontend/` | `/fluent-mystique-scaffold` | When scaffolding a custom SDK component | Yes | TypeScript/React projects: `package.json`, `src/`, `@types/mystique/` |
| `workflows/<RETAILER>/` | `/fluent-connect`, `fluent workflow download` | On connect or manual download | Yes | One JSON per workflow + `workflow-context.json` (tracks download timestamp) |
| `features/<slug>/` | `/fluent-use-case-discover` | When starting a new feature | Yes | `spec.md`, `plan.md`, `architecture.md`, `status.json` |
| `tasks/` | `/fluent-module-scaffold`, `/fluent-bootstrap` | When planning operational tasks (not features) | Yes | Markdown plans: `<YYYY-MM-DD>-<skill>-<slug>.md` |
| `reports/` | `/fluent-build`, `/fluent-pre-deploy-check`, `/fluent-e2e-test`, `/fluent-ui-test`, `/fluent-ui-record`, `/fluent-frontend-build`, `/fluent-frontend-review` | After each skill run | **Ephemeral** — regenerated each run | Subdirs per skill: `build/`, `pre-deploy/`, `e2e-test/`, `ui-test/`, `ui-record/`, `frontend-build/`, `frontend-review/` |
| `analysis/` | `/fluent-custom-code`, `/fluent-implementation-map`, `/fluent-connection-analysis`, `/fluent-workflow-analyzer` | When analyzing the account | **Persistent** — reused across sessions | Subdirs: `code/`, `modules/`, `topology/`, `settings/`, `scope/`, `mystique/` |
| `feedback/` | Pilot skills (workflow-builder, workflow-deploy, settings, rule-scaffold) | After each skill execution | Yes (append-only) | `<skill>.jsonl` + `index.json` — learnings from past runs |
| `sessions/` | `/fluent-session export` | When user exports a session audit | Yes | JSON audit trail files |
| `settings/backups/` | `/fluent-settings` | Before any non-manifest setting change | Yes | JSON snapshots of previous setting values |
| `manifests/backups/` | `/fluent-mystique-builder`, `/fluent-settings` | Before any manifest setting change | Yes | `<setting-name>_<YYYY-MM-DD>.json` — mandatory safety backup |
| `knowledge/` | `/fluent-knowledge-init`, progressive capture | Account-specific conventions, business rules, test data | Yes | `client/` (business rules, data model, integrations, test data), naming-conventions.md, coding-standards.md |
| `workspace-state.json` | `/fluent-connect` | On first connect | Yes | Profile name, retailer ref, API URL, last connect timestamp |
| `feature-dashboard.html` | `/fluent-feature-dashboard`, auto-start | When feature work begins | Regenerated on every file change | Self-contained HTML with vendor libs inline. Open in browser for live view. |

---

## 3. Architecture

### Three-Agent System

```mermaid
graph TB
    USER["You (natural language)"] --> DEV

    subgraph "AI Agents"
        DEV["fluent-dev<br/><b>Orchestrator</b><br/>Routes, plans, cross-domain"]
        BE["fluent-backend-dev<br/>Workflows, rules, modules,<br/>settings, events, deployment"]
        FE["fluent-frontend-dev<br/>Manifests, SDK components,<br/>UI testing, validation"]
        DEV --> BE
        DEV --> FE
    end

    subgraph "MCP Servers (live API access)"
        M1["fluent-mcp<br/><i>Workflows, GraphQL</i>"]
        M2["fluent-mcp-extn<br/><i>45 tools: events, batch,<br/>metrics, entities, settings, cache</i>"]
        M3["chrome-devtools<br/><i>Browser UI testing</i>"]
    end

    BE --> M1 & M2
    FE --> M1 & M2 & M3
```

**Routing is automatic:** Mention workflows/rules/Java → backend agent. Mention manifests/pages/UI → frontend agent. Both → orchestrator creates unified plan.

### MCP Servers

Three servers auto-configured by the installer (core). Additional servers can be added for specific needs (optional).

| Server | Purpose | Core? |
|--------|---------|:-----:|
| **fluent-mcp** | Official CLI MCP — workflows, GraphQL | Yes |
| **fluent-mcp-extn** | Extension — 45 tools: events, batch, metrics, entities, settings, cache | Yes |
| **chrome-devtools** | Browser automation — screenshots, clicks, DOM inspection. Use `--headless` for CI. | Yes |
| chrome-manual | Attach to existing Chrome sessions with cookies/auth | No |
| bitbucket | Bitbucket code repository access | No |
| vercel / S3 | Frontend hosting/deployment | No |

### Compatibility

| Component | Minimum version |
|-----------|----------------|
| Fluent Commerce platform | v4.80+ |
| Fluent CLI | v2.0+ |
| Node.js | 20+ |

### Six Agents

Need a concise routing view first? See [Agents & Skills Guide](agents-and-skills-guide.md) for the consolidated "what it does, when to invoke it, and where it fits in the SDLC" map.

| Agent | Group | Role | Key skills |
|-------|-------|------|------------|
| `fluent-dev` | dev | Orchestrator — routes to backend or frontend; owns cross-cutting skills | `/fluent-feature-plan`, `/fluent-feature-status`, `/fluent-implementation-map`, `/fluent-e2e-test`, `/fluent-session` |
| `fluent-backend-dev` | dev | Backend — Java rules, Maven modules, workflow JSON, settings, events, deployment | `/fluent-workflow-builder`, `/fluent-rule-scaffold`, `/fluent-module-scaffold`, `/fluent-build`, `/fluent-trace`, `/fluent-settings` |
| `fluent-frontend-dev` | dev | Frontend — Mystique manifests, SDK components, build pipeline, UI testing | `/fluent-mystique-builder`, `/fluent-mystique-scaffold`, `/fluent-mystique-diff`, `/fluent-frontend-build`, `/fluent-ui-test`, `/fluent-ui-record` |
| `fluent-cli` | cli | CLI operations — profile management, module deploy, workflows, retailer config | All 10 CLI skills |
| `fluent-mcp` | mcp-extn | MCP extension + official CLI MCP — events, GraphQL, batch, metrics, entities, workflow list/download, GraphQL build/validate | `/fluent-mcp-tools`, `/fluent-mcp-core` |
| `fluent-rfl` | rfl | Ready For Launch — workflow, rule, settings, architecture audit | `/fluent-rfl-assess` |

**Routing is intent-based:**

```mermaid
graph LR
    U["You"] --> O["fluent-dev<br/>(orchestrator)"]
    O -->|"workflow, rule, module,<br/>event, settings, deploy"| BE["fluent-backend-dev"]
    O -->|"manifest, page, component,<br/>UI, Mystique, SDK"| FE["fluent-frontend-dev"]
    O -->|"CLI, profile, retailer"| CLI["fluent-cli"]
    BE --> MCP1["fluent-mcp<br/>(mcp-extn)"]
    FE --> MCP1 & MCP2["chrome-devtools"]
```

Mention workflows/rules/Java → backend agent. Mention manifests/pages/UI → frontend agent. Cross-domain features → orchestrator creates unified plan.

### Skill Groups

| Group | Skills | What it provides |
|-------|:------:|------------------|
| `cli` | 10 | Fluent CLI command-family coverage: connect, profile, retailer, settings, modules, workflows, MCP/CI-CD, bootstrap |
| `dev` | 51 | **Backend:** workflow builder/analyzer, connection analysis, custom code, transition API, rule scaffold, module scaffold/validate/build, source onboarding, trace, event API, system monitoring, batch, settings, deploy, workflow deploy, rollback. **Frontend:** manifest builder/validator/analyzer, SDK scaffold/component/reference, frontend build (8 gates)/review (9 phases)/readme, UI test, UI record. **Cross-cutting:** feature planning, use-case discover, feature status/explain/dashboard, implementation map, scope decompose, feature phase, E2E test, test data, session, sourcing, knowledge init, workspace tree |
| `rfl` | 1 | Production readiness assessment — scored report across workflows, rules, settings, integrations |
| `mcp-extn` | 2 | MCP extension tools reference (45 tools in 15 categories) + official CLI MCP server reference |

### Workspace Directory Structure

Every artifact is scoped under `accounts/<PROFILE>/`. Directories are created on demand — nothing is pre-created.

```
fluent-ai-workspace/
├── .mcp.json                        ← MCP server config (auto-generated, gitignored)
├── CLAUDE.md                        ← Starter workspace instructions (auto-generated, safe to edit)
└── accounts/<PROFILE>/              ← All data scoped to your Fluent account
    │
    ├── SOURCE/                      ← Implementation source code (shared across retailers)
    │   ├── backend/                 ← Java Maven plugin repos
    │   │   ├── fc-plugin-custom/    ← git-cloned custom plugin repo
    │   │   │   ├── pom.xml
    │   │   │   ├── resources/module.json
    │   │   │   └── src/main/java/com/...
    │   │   ├── fc-module-order/     ← reference module package (module.json + JAR)
    │   │   │   ├── module.json
    │   │   │   └── assets/rules/fc-plugin-order-2.1.0.jar
    │   │   └── .decompiled/         ← auto-generated from JAR decompilation
    │   │       └── fc-plugin-order-2.1.0/
    │   │           ├── DECOMPILED.md
    │   │           └── com/fluentcommerce/...
    │   ├── frontend/                ← Mystique SDK component projects
    │   │   └── mystique-appeasement/
    │   │       ├── package.json
    │   │       ├── src/index.tsx    ← ComponentRegistry.register(...)
    │   │       ├── @types/mystique/ ← SDK type definitions
    │   │       └── webpack.config.js
    │
    ├── workflows/<RETAILER_REF>/    ← Downloaded workflow JSONs (retailer-scoped)
    │   ├── ORDER-HD.json
    │   ├── FULFILMENT-HD_WH.json
    │   └── workflow-context.json    ← tracks profile/retailer/download timestamp
    │
    ├── features/<slug>/             ← Feature artifacts (one dir per feature)
    │   ├── spec.md                  ← Business spec (from /fluent-use-case-discover)
    │   ├── plan.md                  ← Implementation plan (from /fluent-feature-plan)
    │   ├── architecture.md          ← Feature arch doc (from /fluent-feature-explain)
    │   └── status.json              ← Machine-readable lifecycle state
    │
    ├── tasks/                       ← Operational plans (non-feature)
    ├── reports/                     ← Ephemeral: build/, pre-deploy/, e2e-test/, ui-test/
    ├── analysis/                    ← Persistent: code/, modules/, topology/, settings/
    ├── feedback/                    ← Skill feedback JSONL + index.json
    ├── sessions/                    ← Audit trail exports
    ├── settings/backups/            ← Non-manifest setting backups
    ├── manifests/backups/           ← Manifest setting backups (before any change)
    ├── knowledge/                   ← Account-specific conventions, business rules, test data
    └── feature-dashboard.html       ← Live HTML dashboard (auto-refreshes via SSE)
```

### Adding Source Code

**Backend (Java plugins)** — Clone custom plugin repos into `SOURCE/backend/`:

```bash
cd accounts/MY_PROFILE/SOURCE/backend
git clone https://bitbucket.org/yourorg/fc-plugin-custom.git
```

Each repo needs at minimum: `resources/module.json` (rule registrations), `pom.xml` (Maven build), and `src/main/java/` (rule classes). Skills auto-detect repos by searching for these files recursively.

**Frontend (Mystique SDK components)** — Create or clone projects into `SOURCE/frontend/`:

```bash
cd accounts/MY_PROFILE/SOURCE/frontend
# Option A: Scaffold a new project via the AI
#   "Scaffold a custom order tracker component"  →  /fluent-mystique-scaffold
#
# Option B: Clone an existing project
git clone https://bitbucket.org/yourorg/mystique-custom-components.git
```

Each project needs: `package.json`, `src/index.tsx` (with `ComponentRegistry.register()`), `@types/mystique/` (SDK types). Download the SDK from `https://fluent.apps.fluentcommerce.com/_sdk/latest/omx-component-sdk.zip` if you don't have the type definitions.

**JARs (no source available)** — Place compiled module JARs directly in `SOURCE/backend/`:

```bash
cp fc-plugin-custom-1.2.3.jar accounts/MY_PROFILE/SOURCE/backend/
```

Skills auto-decompile JARs into `SOURCE/backend/.decompiled/<jar-basename>/` with a `DECOMPILED.md` marker. Decompiled source is **read-only** — skills can analyze it but will never suggest editing decompiled files. To modify, provide original source or scaffold a new module.

**Reference modules (OOTB)** — Place `module.json` + `assets/rules/*.jar` packages in `SOURCE/backend/`. Skills read rule metadata directly from `module.json` — no decompilation needed unless deep analysis of rule logic is requested.

---

## 4. MCP Server Setup

> **Most users don't need this section.** The installer auto-generates `.mcp.json` for you. Only read this if you need to customize auth or troubleshoot.

### Authentication (recommended: CLI Profile)

The installer configures MCP to reuse your existing Fluent CLI profile — no credentials in config files:

```json
{
  "mcpServers": {
    "fluent-mcp-extn": {
      "type": "stdio",
      "command": "npx",
      "args": ["@fluentcommerce/fluent-mcp-extn"],
      "env": {
        "FLUENT_PROFILE": "YOUR_PROFILE",
        "FLUENT_PROFILE_RETAILER": "YOUR_RETAILER_REF"
      }
    }
  }
}
```

**Alternative auth methods** (for CI/CD or environments without CLI profiles):

| Method | When to use | Key env vars |
|--------|-------------|-------------|
| **OAuth** | Headless environments | `FLUENT_CLIENT_ID` + `FLUENT_CLIENT_SECRET` + `FLUENT_USERNAME` + `FLUENT_PASSWORD` (shell env vars, never in .mcp.json) |
| **Token command** | CI/CD with vault | `TOKEN_COMMAND` (e.g., `vault read -field=token secret/fluent/api`) |
| **Static token** | Quick testing only | `FLUENT_ACCESS_TOKEN` (no auto-refresh) |

Auth priority: Profile → OAuth → Token Command → Static Token (first valid wins).

> **Security rule:** `FLUENT_PASSWORD` and `FLUENT_CLIENT_SECRET` are **shell environment variables only** — never put secrets in `.mcp.json`. The installer's `mcp-setup` auto-strips sensitive values.

### Verify Connection

After setup, ask the AI to run these three checks:

1. `config.validate` → `ok: true` (config valid)
2. `health.ping` → `ok: true` (API reachable)
3. `connection.test` → `ok: true` (auth works, shows user/account)

### Config File Location

| Client | Config file |
|--------|-------------|
| Claude Code | `.mcp.json` (workspace root) |

### Resilience Tuning

| Variable | Default | Description |
|----------|---------|-------------|
| `FLUENT_REQUEST_TIMEOUT_MS` | `30000` | Per-request timeout |
| `FLUENT_RETRY_ATTEMPTS` | `3` | Retry attempts for read operations |
| `FLUENT_RESPONSE_BUDGET_CHARS` | `50000` | Max response size (~12.5k tokens). For large payloads (manifests, workflows), use `outputFile` parameter or CLI commands instead. |

### Chrome DevTools MCP (Browser UI Testing)

[Chrome DevTools MCP](https://www.npmjs.com/package/chrome-devtools-mcp) is auto-configured by the installer. It provides browser automation for `/fluent-ui-test` (verification) and `/fluent-ui-record` (annotated recording).

| Capability | MCP Tool | Used by |
|-----------|----------|---------|
| Navigate to OMS/Store apps | `navigate_page` | `/fluent-ui-test`, `/fluent-ui-record` |
| Read page structure (DOM snapshot) | `take_snapshot` | `/fluent-ui-test`, `/fluent-ui-record` |
| Capture visual evidence | `take_screenshot` | `/fluent-ui-test`, `/fluent-ui-record` |
| Inject DOM annotation overlays | `evaluate_script` | `/fluent-ui-test`, `/fluent-ui-record` |
| Fill login forms | `type_text`, `click` | `/fluent-ui-test`, `/fluent-ui-record` |
| Detect JS/GraphQL errors | `list_console_messages` | `/fluent-ui-test` |
| Monitor API calls | `list_network_requests` | `/fluent-ui-record` |
| Continuous video recording | `--save-video` flag | `/fluent-ui-record` |

**Configuration (auto-generated by `mcp-setup`):**

```json
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"],
      "env": {
        "FLUENT_UI_BASE_URL": "https://<account>.<env>.apps.engineering.fluentcommerce.com"
      }
    }
  }
}
```

| Flag | Purpose |
|------|---------|
| `--browser-url <url>` | Set `FLUENT_UI_BASE_URL` to a specific environment |
| `--no-browser` | Skip Chrome DevTools MCP setup (backend-only workflows) |
| `--save-video [resolution]` | Enable continuous video recording (default: 1920x1080). Optional FFmpeg for trim/convert. |

**Frontend skill chain:** `/fluent-mystique-builder` → `/fluent-mystique-validate` → `/fluent-frontend-build dev` (localhost hot-reload) → `/fluent-ui-test` (local verify) → `/fluent-frontend-build full` (release gates) → deploy → `/fluent-ui-test` (final).

### Environment Variables

Credentials are **shell environment variables only** — never in `.mcp.json`. The installer's `mcp-setup` auto-strips sensitive values.

| Variable | Purpose | Required when |
|----------|---------|---------------|
| `FLUENT_USERNAME` | Fluent account username | UI testing, non-profile MCP auth |
| `FLUENT_PASSWORD` | Fluent account password | UI testing, non-profile MCP auth |
| `FLUENT_CLIENT_ID` | OAuth client ID | OAuth auth (CI/CD environments) |
| `FLUENT_CLIENT_SECRET` | OAuth client secret | OAuth auth (CI/CD environments) |
| `BITBUCKET_USERNAME` | Bitbucket username | Bitbucket MCP server |
| `BITBUCKET_APP_PASSWORD` | Bitbucket app password | Bitbucket MCP server |

**Profile-based auth (recommended):** With `--profile`, MCP servers read tokens from `~/.fluentcommerce/<PROFILE>/` automatically. No credential env vars needed for API access. `FLUENT_USERNAME`/`FLUENT_PASSWORD` are only needed for browser UI testing.

**What goes in `.mcp.json`:** Only non-secret config — `FLUENT_PROFILE`, `FLUENT_PROFILE_RETAILER`, `FLUENT_RETAILER_ID`, `FLUENT_UI_BASE_URL`. The installer manages these automatically.

---

## 5. What Can You Do?

> **Want detailed walkthroughs?** The [Use Cases Guide](use-cases.md) has 21 scenario-based walkthroughs with step-by-step examples and expected outputs. The [Getting Started Guide](getting-started.md) walks through your first debug, first feature build, and session resumption.

### Quick Reference Prompts

| I want to... | Say this | Skill |
|---|---|---|
| **Setup & Connection** | | |
| Connect to a Fluent account | "Set up my workspace" | `/fluent-connect` |
| Create or switch CLI profiles | "Create a profile for production" | `/fluent-profile` |
| Set up a new account | "Bootstrap a new Fluent account" | `/fluent-bootstrap` |
| Set up project knowledge | "Initialize knowledge for this project" | `/fluent-knowledge-init` |
| **Understanding & Analysis** | | |
| Understand how a feature works | "Explain how Home Delivery works" | `/fluent-feature-explain` |
| Map what's been built on an account | "Give me a feature inventory" | `/fluent-implementation-map` |
| Analyze workflow structure | "Analyze ORDER::HD for orphaned rulesets" | `/fluent-workflow-analyzer` |
| Map cross-entity dependencies | "Show how ORDER::HD connects to FULFILMENT" | `/fluent-connection-analysis` |
| Analyze custom plugin source | "Analyze the custom code" | `/fluent-custom-code` |
| Analyze an existing manifest | "What components are used in admin?" | `/fluent-mystique-analyze` |
| Compare manifests against CDN baselines | "What's customized vs default?" | `/fluent-mystique-diff` |
| Understand sourcing | "How does sourcing work?" | `/fluent-sourcing` |
| Understand the event model | "How does event routing work?" | `/fluent-event-api` |
| **Feature Development** | | |
| Gather requirements | "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` |
| Scaffold a new Java rule | "Create a rule called ValidateReturnWindow" | `/fluent-rule-scaffold` |
| Create a new extension module | "Scaffold a module called my-returns" | `/fluent-module-scaffold` |
| Create a data-only module | "Create a data module for reference data" | `/fluent-data-module-scaffold` |
| Onboard existing source | "Refactor this code into a Fluent module" | `/fluent-source-onboard` |
| Build a new workflow | "Build an ORDER::RETURN workflow" | `/fluent-workflow-builder` |
| Build and package a module | "Build the my-extensions module" | `/fluent-build` |
| Bump module version | "Bump the module version to 1.4.0" | `/fluent-version-manage` |
| **UI / Manifest Development** | | |
| Build a Mystique UI page | "Build an order detail page" | `/fluent-mystique-builder` |
| Validate a manifest | "Validate the admin manifest" | `/fluent-mystique-validate` |
| Scaffold a custom SDK component | "Create a custom order tracker component" | `/fluent-mystique-scaffold` |
| Add component/field/helper to SDK project | "Add a currency format helper" | `/fluent-mystique-component` |
| Look up SDK hooks and patterns | "How does useUserActions work?" | `/fluent-mystique-sdk-reference` |
| Build SDK project (TypeScript, lint, tests, webpack) | "Build the mystique-appeasement project" | `/fluent-frontend-build` |
| Review SDK code quality | "Review the frontend code for issues" | `/fluent-frontend-review` |
| Generate SDK project README | "Generate a readme for the component project" | `/fluent-frontend-readme` |
| Build a full-stack feature | "Build order tracking with a dashboard" | `/fluent-feature-plan` → backend → frontend |
| **Deployment** | | |
| Run quality gates | "Run pre-deploy checks for my-extensions" | `/fluent-pre-deploy-check` |
| Deploy a module | "Deploy my extension module to MY_RETAILER" | `/fluent-module-deploy` |
| Deploy a workflow | "Deploy ORDER::HD to MY_RETAILER" | `/fluent-workflow-deploy` |
| Roll back a deployment | "Roll back ORDER::HD to previous version" | `/fluent-rollback` |
| **Testing & Debugging** | | |
| Debug why an order is stuck | "Why is order HD-001 stuck in BOOKED?" | `/fluent-trace` |
| Run an end-to-end test | "Run an E2E test of the HD order flow" | `/fluent-e2e-test` |
| Create test data | "Create a test HD order" | `/fluent-test-data` |
| Verify a deployed page in browser | "Check that OMS orders page loads" | `/fluent-ui-test` |
| Record UI walkthrough | "Record before/after screenshots" | `/fluent-ui-record` |
| Monitor event health | "Show event failure rates for last hour" | `/fluent-system-monitoring` |
| See what actions are available | "What actions can I take on ORDER in BOOKED?" | `/fluent-transition-api` |
| Batch ingest data | "Create batch ingestion job for inventory" | `/fluent-job-batch` |
| **Lifecycle Management** | | |
| Check feature status dashboard | "What features are in progress?" | `/fluent-feature-status` |
| View live feature dashboard (HTML) | "Start the feature dashboard" | `/fluent-feature-dashboard` |
| Show workspace directory tree | "Show me the workspace tree" | `/fluent-workspace-tree` |
| Validate Mermaid diagram syntax | "Validate this mermaid diagram" | See `knowledge/mermaid-syntax-rules.md` |
| Resume a previous feature | "Continue working on return orders" | AI reads `status.json` |
| Check if ready for go-live | "Run an RFL assessment" | `/fluent-rfl-assess` |
| Decompose a scope document | "Break this scope doc into tasks" | `/fluent-scope-decompose` |
| Split feature into delivery phases | "Phase this feature for incremental delivery" | `/fluent-feature-phase` |
| Audit what skills ran | "What skills ran this session?" | `/fluent-session` |
| Export audit trail | "Export a JSON audit trail" | `/fluent-session export` |
| View skill feedback | "Show me the feedback dashboard" | `/fluent-feedback` |
| Configure sourcing profile | "Create HD sourcing profile with distance + stock" | `/fluent-sourcing` |
| 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` |

---

## 6. Feature Lifecycle

### Status Progression

```mermaid
stateDiagram-v2
    direction LR
    [*] --> DISCOVERY : /fluent-use-case-discover
    DISCOVERY --> PLANNING : spec approved
    PLANNING --> APPROVED : plan approved
    APPROVED --> IN_PROGRESS : implementation starts
    IN_PROGRESS --> BUILT : build passes
    BUILT --> DEPLOYED : deploy succeeds
    DEPLOYED --> VERIFIED : E2E tests pass
    PLANNING --> DISCOVERY : plan rejected
    APPROVED --> PLANNING : plan revised
    IN_PROGRESS --> PLANNING : breaking change (regress)
    DEPLOYED --> IN_PROGRESS : rebuild needed
    DEPLOYED --> BUILT : workflow-only change
    VERIFIED --> IN_PROGRESS : re-opened
    VERIFIED --> [*]
    note right of VERIFIED : Feature complete
```

Each feature lives in `accounts/<PROFILE>/features/<slug>/` with four canonical files: `spec.md`, `plan.md`, `architecture.md`, and `status.json`.

### What Gets Created at Each Step

| Step | You say | AI does | Created |
|------|---------|---------|---------|
| 1. Gather requirements | "Help me define use cases for..." | Interactive wizard | `spec.md` + `status.json` |
| 2. Plan the feature | "Plan the X feature" | 18-section plan with diagrams | `plan.md` |
| 3. Approve | "Approved" | Marks plan approved | `status.json` → `plan: "APPROVED"` |
| 4. Scaffold module | "Scaffold the module" | Creates Maven project | `pom.xml`, `module.json` |
| 5. Create rules | "Create rules from the plan" | Java classes + tests | `*.java` + `*Test.java` |
| 6. Build workflow | "Build the workflow" | Workflow JSON + validation | `<WORKFLOW>.json` |
| 7. Build module | "Build the module" | Maven build + packaging | `dist/<module>.zip` |
| 8. Pre-deploy checks | "Run pre-deploy checks" | 26 quality gates | `reports/pre-deploy/*.json` |
| 9. Deploy | "Deploy to MY_RETAILER" | Module + workflow deployment | Live environment changes |
| 10. E2E test | "Run E2E test" | Create entities, fire events, assert | Test report |

### Resuming across sessions

Each feature tracks its own `status.json`. When you open a new session and say "continue working on return orders", the AI reads this file, knows exactly where you left off (including which skill to run next), and resumes automatically. No manual context re-entry needed.

### Approval Gate

The AI never makes changes without asking first:

```mermaid
graph LR
    A["Spec generated"] -->|"auto-critique"| B["Refined spec"]
    B -->|"you review"| C{"Approve?"}
    C -->|"yes"| D["Plan generated"]
    D -->|"auto-critique"| E["Refined plan"]
    E -->|"you review"| F{"Approve?"}
    F -->|"yes"| G["Implementation begins"]
    C -->|"changes needed"| A
    F -->|"changes needed"| D
```

- **Triggers the gate:** Any change to code, workflows, settings, or live environment
- **Skips the gate:** Read-only operations (explain, trace, analyze, audit, diagnose)
- **Override:** Say "just do it" or "skip planning" to bypass

### Feature Dashboard

A live HTML dashboard auto-starts at `http://localhost:3456` when feature work begins. It shows all features with status, spec/plan content rendered as HTML with Mermaid diagrams, file metadata, and session history. Features being actively updated show a pulsing indicator in the sidebar.

Generated by `fluent-ai-skills/tools/generate-feature-dashboard.mjs` — zero dependencies, vendor libs bundled inline. Updates automatically via SSE when any feature file changes.

**Prerequisites:**
1. **Vendor libs** — run `node fluent-ai-skills/tools/generate-feature-dashboard.mjs --setup` once. Downloads `marked.min.js` and `mermaid.min.js` to `fluent-ai-skills/tools/vendor/`.
2. **Features directory** — at least one feature must exist under `accounts/<PROFILE>/features/` (created by `/fluent-use-case-discover`).
3. **Node.js 20+**.

**When does data appear?**

| Skill | What it populates |
|-------|-------------------|
| `/fluent-use-case-discover` | Creates `status.json` (DISCOVERY) + `spec.md` — feature first appears in sidebar |
| `/fluent-feature-plan` | Creates `plan.md`, advances to PLANNING/APPROVED — Plan tab populated |
| `/fluent-workflow-builder`, `/fluent-rule-scaffold`, etc. | Advances to IN_PROGRESS — Status tab shows progress |
| `/fluent-build` | Sets `build: PASSED/FAILED` — build gate indicator updates |
| `/fluent-module-deploy`, `/fluent-workflow-deploy` | Sets `deploy: DEPLOYED` — deploy gate indicator updates |
| `/fluent-e2e-test` | Sets `test: PASSED/FAILED` — test gate indicator, advances to VERIFIED |
| `/fluent-feedback` | Appends to `feedback/<skill>.jsonl` — Feedback tab metrics |
| `/fluent-session` | Writes session audit — session timeline in Status tab |

**Commands:**

```bash
# One-time setup (download vendor libs)
node fluent-ai-skills/tools/generate-feature-dashboard.mjs --setup

# Start live server (auto-refreshes on file changes)
node fluent-ai-skills/tools/generate-feature-dashboard.mjs --profile ACME --serve --port 3456

# Generate static HTML only (no server)
node fluent-ai-skills/tools/generate-feature-dashboard.mjs --profile ACME

# All profiles at once (static only)
node fluent-ai-skills/tools/generate-feature-dashboard.mjs --all
```

**Dashboard tabs per feature:** Status (lifecycle progress bar + gates + sessions), Spec (rendered markdown + Mermaid), Plan (rendered markdown + Mermaid), Architecture (diagrams), Feedback (skill success/failure metrics), Reports (embedded markdown + base64 screenshots), Files (file metadata).

**Output:** `accounts/<PROFILE>/feature-dashboard.html` — self-contained HTML, works offline without server.

### status.json Schema

```json
{
  "$schema": "feature-status-v2",
  "feature": "return-order",
  "summary": "One-sentence description shown in the dashboard — written at spec time.",
  "retailers": ["MY_RETAILER"],
  "status": "DEPLOYED",
  "spec": "APPROVED",
  "plan": "APPROVED",
  "build": "PASSED",
  "deploy": "DEPLOYED",
  "test": null,
  "planRevision": 1,
  "next": "/fluent-e2e-test",
  "basedOn": null,
  "created": "2026-01-15",
  "updated": "2026-01-20",
  "sessions": []
}
```

| Field | Meaning |
|-------|---------|
| `summary` | One-sentence feature description shown in dashboard — written at spec time |
| `status` | Overall: DISCOVERY → PLANNING → APPROVED → IN_PROGRESS → BUILT → DEPLOYED → VERIFIED |
| `spec` / `plan` | Artifact gate: null → DRAFT → APPROVED |
| `build` | Build gate: null → PENDING → PASSED / FAILED |
| `deploy` | Deploy gate: null → PENDING → DEPLOYED / FAILED |
| `test` | Test gate: null → PENDING → PASSED / FAILED |
| `next` | Which skill the AI runs next (auto-determined) |
| `planRevision` | Increments if plan is revised without regression |
| `retailers` | Array of retailer refs this feature applies to |
| `basedOn` | Slug linkage for multi-retailer feature variants |
| `created` / `updated` | ISO date strings |
| `sessions` | Audit trail of session references |

---

## 7. Development Workflow

### The Build Loop

```mermaid
graph TD
    A["1. Connect & Analyze"] --> B["2. Explain or Plan"]
    B -->|"read-only"| DONE["Feature Architecture Doc"]
    B -->|"changes needed"| C["3. User Approval"]
    C --> D["4. Implement"]
    D --> E["5. Validate & Build"]
    E --> F["6. Deploy"]
    F --> G["7. Test (E2E + Browser)"]
    G -->|"pass"| VERIFIED["✓ Verified"]
    G -->|"fail"| H["8. Diagnose & Fix"]
    H --> D
```

### Phase reference

| Phase | What the AI does | Key tools / skills |
|-------|-----------------|-------------------|
| **1. Connect & Analyze** | Verify connectivity, download workflows, query live transitions, scan modules, check event history | `config.validate`, `workflow.transitions`, `event.list` |
| **2. Explain (read-only)** | Produces Feature Architecture Doc with state diagrams, rules tables, settings deps. **No changes.** | `/fluent-feature-explain` |
| **3. Plan & Approve** | Structured plan: business context, proposed changes, Mermaid diagrams, risks, rollback. **Waits for your approval.** | `/fluent-use-case-discover`, `/fluent-feature-plan` |
| **4. Implement** | Edit workflows, scaffold/edit Java rules, update settings, build manifests | `/fluent-workflow-builder`, `/fluent-rule-scaffold`, `/fluent-settings`, `/fluent-mystique-builder` |
| **5. Validate & Build** | 9 structural checks, bump version, Maven build, package ZIP | `/fluent-module-validate`, `/fluent-build` |
| **6. Deploy** | Module + workflow deployment with pre-deploy gates | `/fluent-pre-deploy-check`, `/fluent-module-deploy`, `/fluent-workflow-deploy` |
| **7. Test** | E2E: create entities → fire events → assert states. Browser: navigate → snapshot → verify DOM → screenshot | `/fluent-e2e-test`, `/fluent-ui-test` |
| **8. Diagnose & Fix** | Event FAILED → rule exception. PENDING → queue backlog. No event → wrong ref. Fix and loop back. | `/fluent-trace`, `event.flowInspect` |

### What happens between you and the AI

| You | AI |
|-----|-----|
| Describe what you want in plain language | Asks clarifying questions if needed |
| Confirm the spec | Critiques its own output internally, presents the refined version |
| Approve the plan | Begins implementation, announces each step |
| See intermediate results | Runs validators and reports issues inline |
| Say "deploy" | Runs pre-flight checks, shows what will change, waits for your confirm |

### Frontend Component Quick Matrix

When deciding custom SDK component shape and registration:

| Component `category` | Use when | `data` scope | `<Children />` | Typical API |
|---|---|---|---|---|
| `page` | Replacing a full route-level page shell | Unscoped (full page query result) | Core pattern; usually required | `useData`, `useUserActions`, `<Children />` |
| `layout` | Composing/arranging descendants | Scoped by parent `dataSource` | Core pattern; often required | `<Children />`, `dataOverride`, `descendantsOverride` |
| `content` | Rendering a widget/card/action block (default) | Scoped by parent `dataSource` | Optional | `<DynamicValue />`, `TemplateRegistry.render`, `useData` |
| `filter` | Updating page query variables (search/filter/sort) | Scoped + mutable query variables | Usually not used | `useData().variables.setVariables()` |

**Registry choice:**
- `ComponentRegistry` for page/layout/content/filter components referenced by manifest `"component"`.
- `FieldRegistry` for user action form fields mapped by workflow `attributes[].type`.
- `TemplateRegistry` for `{{helper ...}}` expression helpers.

### Settings Update Quick Recipe

For safe setting updates (via `/fluent-settings`):

1. Resolve by `name` + `context/contextId` to fetch `id`, `valueType`, and current value.
2. Update by `id` (never guessed) using: `value` for `STRING`/`BOOLEAN`, `lobValue` for `LOB`/`JSON`.
3. Re-query the same `name` + scope and confirm the value changed.
4. If no setting exists, create it with the same scope (upsert behavior).

**Manifest settings (non-negotiable):** `valueType: "JSON"`, `context: "ACCOUNT"`, `contextId: 0`, body in `lobValue` (never `value` — silently truncates at 255 chars).

### Step-by-Step Feature Build

Here's what happens at each substep when building a feature end-to-end:

| Sub-step | Skill | Artifacts created |
|----------|-------|-------------------|
| Scaffold rules | `/fluent-rule-scaffold` | `SOURCE/backend/<repo>/src/main/java/.../RuleName.java` + test class + `module.json` updated |
| Build workflow | `/fluent-workflow-builder` | Modified workflow JSON in `workflows/<RETAILER>/` |
| Validate | `/fluent-workflow-analyzer` | Structural analysis (runs automatically after workflow edits) |
| Compile module | `/fluent-build` | `SOURCE/backend/<repo>/dist/<module>.zip` + report in `reports/build/` |
| Pre-deploy gate | `/fluent-pre-deploy-check` | Report in `reports/pre-deploy/` (READY or BLOCKED) |
| Deploy module | `/fluent-module-deploy` | Module installed on live environment |
| Deploy workflow | `/fluent-workflow-deploy` | Workflow uploaded to live environment |
| E2E test | `/fluent-e2e-test` | Test results in `reports/e2e-test/`, entities created on live env |

If a test fails, the AI diagnoses the issue, applies a fix, rebuilds, redeploys, and re-tests — looping until all tests pass or a blocker is hit.

---

## 8. MCP Extension Tools

### At a glance

```mermaid
graph TB
    subgraph "Diagnostics (3)"
        D1["config.validate"]
        D2["health.ping"]
        D3["connection.test"]
    end
    subgraph "Events (5)"
        E1["event.build / send / get / list"]
        E2["event.flowInspect"]
    end
    subgraph "GraphQL (4)"
        G1["graphql.query / queryAll"]
        G2["graphql.batchMutate / introspect"]
    end
    subgraph "Entities (3)"
        N1["entity.create / update / get"]
    end
    subgraph "Workflows (5)"
        W1["workflow.get / list / upload"]
        W2["workflow.diff / simulate"]
    end
    subgraph "Settings (3)"
        S1["setting.get / upsert / bulkUpsert"]
    end
```

### Full reference

| Category | Tool | Description |
|----------|------|-------------|
| **Diagnostics** | `config.validate` | Validate auth and base URL configuration |
| | `health.ping` | Quick connectivity check |
| | `connection.test` | Full auth + GraphQL end-to-end test |
| **Events** | `event.build` | Build event payload without sending |
| | `event.send` | Build and send event (supports `dryRun`) |
| | `event.get` | Fetch a single event by ID |
| | `event.list` | List/filter events with pagination |
| | `event.flowInspect` | One-call root-entity flow forensics (compact ~2-3k tokens, full ~24k) |
| **Metrics** | `metrics.query` | Query Prometheus metrics (instant or range) |
| | `metrics.healthCheck` | One-call anomaly check |
| | `metrics.sloReport` | SLO snapshot (rates + p95 latency) |
| | `metrics.labelCatalog` | Discover metric labels from live series |
| | `metrics.topEvents` | Rank events by name/entity/status |
| **Orchestration** | `workflow.transitions` | Query available user actions/transitions |
| | `plugin.list` | List all registered rules with metadata |
| **GraphQL** | `graphql.query` | Execute any query or mutation |
| | `graphql.queryAll` | Auto-paginated query (follows cursors) |
| | `graphql.batchMutate` | Execute up to 50 mutations in one request |
| | `graphql.introspect` | Inspect schema types, mutations, fields |
| | `graphql.listRoots` | List available root query and mutation fields |
| | `graphql.buildQuery` | Auto-generate a query from entity type |
| | `graphql.validate` | Validate a query against the schema |
| | `graphql.generateFull` | Generate a complete query with all fields |
| **Batch** | `batch.create` | Create an ingestion job |
| | `batch.send` | Send records to a job |
| | `batch.status` | Check job status |
| | `batch.batchStatus` | Check a specific batch |
| | `batch.results` | Get per-record outcomes |
| **Webhook** | `webhook.validate` | Validate payload + optional signature verification |
| **Entities** | `entity.create` | Type-safe creation (12 entity types) |
| | `entity.update` | Status-aware updates with transition validation |
| | `entity.get` | Unified lookup by ID or ref |
| **Workflows** | `workflow.get` | Fetch workflow by entity type/subtype |
| | `workflow.list` | List all workflows (deduped to latest) |
| | `workflow.upload` | Deploy workflow JSON via REST |
| | `workflow.diff` | Compare two workflows (added/removed/modified) |
| | `workflow.simulate` | Static analysis — predict which rulesets fire |
| **Settings** | `setting.get` | Read a setting by name (supports `outputFile`) |
| | `setting.upsert` | Create or update a setting |
| | `setting.bulkUpsert` | Batch create/update up to 50 settings |
| **Environment** | `environment.discover` | Full snapshot (retailer, locations, workflows) |
| | `environment.validate` | Pre-flight validation checks |
| **Cache** | `cache.status` | Check cache status and hit rates |
| | `cache.clear` | Clear server-side caches |
| **Test** | `test.assert` | Assert entity state with optional polling |

### Error handling

All tools return a consistent envelope:

```json
{ "ok": true, "response": { ... } }
{ "ok": false, "error": { "code": "AUTH_ERROR", "message": "...", "retryable": false } }
```

| Code | Meaning | Retryable |
|---|---|---|
| `CONFIG_ERROR` | Missing/invalid env vars | No |
| `AUTH_ERROR` | Authentication failed | No |
| `VALIDATION_ERROR` | Invalid tool arguments | No |
| `TIMEOUT_ERROR` | Request timed out | Yes |
| `RATE_LIMIT` | API rate limit | Yes |
| `UPSTREAM_UNAVAILABLE` | API unreachable | Yes |

---

## 9. Deployment and Promotion Runbook

> **Full runbook:** See the [Deployment & Promotion Runbook](deployment-promotion-runbook.md) for step-by-step instructions, environment promotion sequences, selective deployment recipes, rollback playbook, CI/CD patterns, and `flow-run` command reference.

```mermaid
graph LR
    DEV["dev"] -->|"build + test"| STG["staging"]
    STG -->|"build + test"| PROD["prod"]
```

**Quick deploy sequence:** Build → Validate environment → Back up workflows → Run diagnostics (`flow-run`) → Deploy → Post-deploy verify.

```bash
# Build
cd plugins && mvn clean install && cd .. && ./scripts/build-module.sh

# Deploy
fluent module install dist/<module>.zip \
  --profile <PROFILE> --retailer <RETAILER_REF> \
  --config module.config.<RETAILER>.<env>.json --force

# Verify
fluent module list -p <PROFILE>
fluent workflow list -p <PROFILE> -r <RETAILER_REF>
```

**Selective:** `--include workflows settings` or `--exclude workflows`. **Rollback:** Redeploy previous ZIP or restore workflow backup.

---

## 10. Troubleshooting

### Quick fix

Re-run install:
```bash
npx @fluentcommerce/ai-skills install --profile YOUR_PROFILE --profile-retailer YOUR_RETAILER
```

### Common Issues

| Symptom | Cause | Fix |
|---------|-------|-----|
| `config.validate` fails | Missing/invalid env vars | Check `FLUENT_BASE_URL` + auth method |
| `AUTH_ERROR` on any tool | Bad credentials/expired token | Verify OAuth or regenerate token |
| `connection.test` fails | Network/URL mismatch | Verify API URL, VPN/proxy |
| No workflows found | Not downloaded yet | Run `/fluent-connect` or `fluent workflow download` |
| "Plan required" error | Approval gate working as intended | Say "Plan the X feature" then "approved", or "just do it" to bypass |
| Rule not found in workflow | Module not deployed first | Deploy module before workflow |
| Rule fails with permission error | Rubix user missing roles | Each retailer has `<ACCOUNT>-<RETAILER_ID>-rubix` API user — check it has `ADMIN` + `GRAPHQL` roles |
| Skills not loading | Claude Code needs restart | Restart Claude Code, verify with `npx @fluentcommerce/ai-skills status` |
| Workflow deploy rejected | Same or lower version number | Always bump version before re-deploying — Fluent rejects same/lower |
| Manifest setting not loading | `valueType` wrong or body in `value` not `lobValue` | Use `valueType: "JSON"`, `context: "ACCOUNT"`, `contextId: 0`, body in `lobValue` |
| Chrome DevTools MCP not working | Not configured in `.mcp.json` | Add `chrome-devtools` entry or reinstall with `--with-chrome`, then restart Claude Code |

### MCP debugging steps

```bash
# 1. Verify Fluent CLI
fluent --version

# 2. Verify profile
fluent profile retailers YOUR_PROFILE

# 3. Test MCP extension server (starts on stdio — Ctrl+C to exit)
npx @fluentcommerce/fluent-mcp-extn

# 4. Regenerate MCP config
npx @fluentcommerce/ai-skills mcp-setup --profile YOUR_PROFILE

# 5. Restart Claude Code (MCP servers initialize at startup)
```

### Getting help

- **Upgrade to latest:** `npx @fluentcommerce/ai-skills@latest install --profile YOUR_PROFILE --profile-retailer "YOUR_RETAILER"`
- **Full technical reference (npm/GitHub):** [@fluentcommerce/ai-skills on npmjs.com](https://www.npmjs.com/package/@fluentcommerce/ai-skills) — includes full group descriptions, agent roles, and developer setup
- **Issues or questions:** Raise in the project repository

---

## 11. CLI Reference

```bash
npx @fluentcommerce/ai-skills <command> [--profile <name>] [groups...]
```

### Commands

| Command | Description |
|---|---|
| `install [groups...]` | Install skills. With `--profile`, also configures MCP and checks prerequisites. |
| `uninstall [groups...]` | Uninstall all groups or selected groups. |
| `status [groups...]` | Show install status (checks marketplace and file-copy). |
| `generate` | Generate `.claude-plugin/` marketplace manifests from metadata. |
| `list` | List available groups. |
| `mcp-setup [options]` | Generate `.mcp.json` for official + extension MCP servers. |
| `flow-run [options]` | Run diagnostics and optional guarded module deploy. |
| `--version` | Show package version. |
| `--help` | Show help (includes MCP troubleshooting). |

### Global Options

| Option | Description |
|---|---|
| `--profile <name>` | Fluent CLI profile — auto-configures `.mcp.json` on install |
| `--profile-retailer <ref>` | Retailer ref (requires `--profile`) |
| `--install-mcp-extn` | Pre-install `@fluentcommerce/fluent-mcp-extn` locally for faster MCP startup |
| `--project-root <path>` | Override project root path |

### `mcp-setup` Options

```bash
# Basic — generates .mcp.json
npx @fluentcommerce/ai-skills mcp-setup --profile YOUR_PROFILE

# With retailer ref
npx @fluentcommerce/ai-skills mcp-setup --profile YOUR_PROFILE --profile-retailer YOUR_RETAILER

# Clone and build extension source locally
npx @fluentcommerce/ai-skills mcp-setup --install-extn-source --profile YOUR_PROFILE

# Enable video recording for /fluent-ui-record
npx @fluentcommerce/ai-skills mcp-setup --profile YOUR_PROFILE --save-video
```

| Option | Description |
|---|---|
| `--browser-url <url>` | Set `FLUENT_UI_BASE_URL` for Chrome DevTools MCP |
| `--no-browser` | Skip Chrome DevTools MCP setup (backend-only workflows) |
| `--save-video [resolution]` | Enable browser video recording (default: 1920x1080) |
| `--install-extn-source` | Clone and build extension server locally |

### `flow-run` Options

Runs pre-deploy diagnostics and optionally deploys:

```bash
# Diagnostics only
npx @fluentcommerce/ai-skills flow-run \
  --profile YOUR_PROFILE --retailer YOUR_RETAILER \
  --module dist/module.zip --config config/module.config.json

# Diagnostics + guarded deploy
npx @fluentcommerce/ai-skills flow-run \
  --profile YOUR_PROFILE --retailer YOUR_RETAILER \
  --module dist/module.zip --config config/module.config.json \
  --deploy --yes --exclude-workflows
```

### Environment Variables

Credentials must be set as **shell environment variables** — never in `.mcp.json`.

| Variable | Purpose | Required when |
|---|---|---|
| `FLUENT_USERNAME` | Fluent account username | UI testing, non-profile MCP auth |
| `FLUENT_PASSWORD` | Fluent account password | UI testing, non-profile MCP auth |
| `FLUENT_CLIENT_ID` | OAuth client ID | OAuth auth (alternative to username/password) |
| `FLUENT_CLIENT_SECRET` | OAuth client secret | OAuth auth |
| `BITBUCKET_USERNAME` | Bitbucket username | Bitbucket MCP server |
| `BITBUCKET_APP_PASSWORD` | Bitbucket app password | Bitbucket MCP server |

**What goes in `.mcp.json`:** Only non-secret config — `FLUENT_PROFILE`, `FLUENT_PROFILE_RETAILER`, `FLUENT_RETAILER_ID`, `FLUENT_UI_BASE_URL`. The installer manages these automatically.

### MCP Config Location

| Client | Location |
|---|---|
| Claude Code | Workspace root `.mcp.json` |

---

## 12. Appendix: Capability Ownership Map

### Which Skill Owns What

| Capability | Owner Skill |
|---|---|
| Account connection & workspace setup | `/fluent-connect` |
| CLI profile management | `/fluent-profile` |
| Account bootstrap | `/fluent-bootstrap` |
| Feature reverse-engineering | `/fluent-feature-explain` |
| Feature planning (multi-artifact) | `/fluent-feature-plan` |
| Requirements gathering | `/fluent-use-case-discover` |
| Workflow design & building | `/fluent-workflow-builder` |
| Workflow structural analysis | `/fluent-workflow-analyzer` |
| Workflow deployment | `/fluent-workflow-deploy` |
| Rule scaffolding | `/fluent-rule-scaffold` |
| Module scaffolding | `/fluent-module-scaffold` |
| Module validation | `/fluent-module-validate` |
| Module build & packaging | `/fluent-build` |
| Module deployment | `/fluent-module-deploy` |
| Pre-deploy quality gates | `/fluent-pre-deploy-check` |
| E2E testing | `/fluent-e2e-test` |
| Event tracing & debugging | `/fluent-trace` |
| Event API model reference | `/fluent-event-api` |
| Transition API discovery | `/fluent-transition-api` |
| Settings management | `/fluent-settings` |
| Manifest building & editing | `/fluent-mystique-builder` |
| Manifest validation | `/fluent-mystique-validate` |
| SDK component scaffolding | `/fluent-mystique-scaffold` |
| SDK build pipeline (8 gates) | `/fluent-frontend-build` |
| SDK code quality audit (9 phases) | `/fluent-frontend-review` |
| SDK README generation | `/fluent-frontend-readme` |
| Manifest analysis | `/fluent-mystique-analyze` |
| Manifest CDN vs custom diff | `/fluent-mystique-diff` |
| Browser UI testing | `/fluent-ui-test` |
| UI recording & evidence | `/fluent-ui-record` |
| System monitoring | `/fluent-system-monitoring` |
| Implementation map | `/fluent-implementation-map` |
| Connection topology | `/fluent-connection-analysis` |
| Custom code analysis | `/fluent-custom-code` |
| Source code onboarding | `/fluent-source-onboard` |
| Sourcing framework | `/fluent-sourcing` |
| Test data creation | `/fluent-test-data` |
| Version management | `/fluent-version-manage` |
| Rollback | `/fluent-rollback` |
| Session tracking and audit export | `/fluent-session` |
| Feature status dashboard | `/fluent-feature-status` |
| Feature dashboard (live HTML) | `/fluent-feature-dashboard` |
| Scope decomposition | `/fluent-scope-decompose` |
| Feature delivery phasing | `/fluent-feature-phase` |
| Ready For Launch assessment | `/fluent-rfl-assess` |
| Feedback loop dashboard | `/fluent-feedback` |
| Knowledge initialization | `/fluent-knowledge-init` |
| Data module scaffolding | `/fluent-data-module-scaffold` |
| Mermaid diagram validation | See `knowledge/mermaid-syntax-rules.md` |
| Workspace tree visualization | `/fluent-workspace-tree` |
| Batch job management | `/fluent-job-batch` |
| Retailer configuration | `/fluent-retailer-config` |
| MCP tools reference | `/fluent-mcp-tools` |
| MCP core reference | `/fluent-mcp-core` |
| CLI command reference | `/fluent-cli-reference` |
| CLI cross-family routing | `/fluent-cli-index` |
| CLI MCP and CI/CD setup | `/fluent-cli-mcp-cicd` |
| CLI retailer management | `/fluent-cli-retailer` |
| CLI settings inspection | `/fluent-cli-settings` |
| Workflow CLI operations | `/fluent-workflow` |
| Mystique SDK component addition | `/fluent-mystique-component` |
| Mystique SDK API reference | `/fluent-mystique-sdk-reference` |
| Mystique UI preview | `/fluent-mystique-preview` |
| Virtual inventory catalog | `/fluent-inventory-catalog` |
| Feature archival | `/fluent-archive` |

### Routing Guide

| User says... | Route to |
|---|---|
| "Why did this fail?" / "Entity stuck?" | `/fluent-trace` |
| "Explain feature / how does X work?" | `/fluent-feature-explain` |
| "Plan this feature / implement X" | `/fluent-feature-plan` |
| "What actions available at this status?" | `/fluent-transition-api` |
| "Deploy workflow / upload workflow" | `/fluent-workflow-deploy` |
| "Build manifest / create page / add route" | `/fluent-mystique-builder` |
| "Compare manifests / what's customized / CDN vs custom" | `/fluent-mystique-diff` |
| "Test the page in browser" | `/fluent-ui-test` |
| "Build the SDK project / run tests" | `/fluent-frontend-build` |
| "Review frontend code quality" | `/fluent-frontend-review` |
| "Ready for launch / production audit" | `/fluent-rfl-assess` |
| "Roll back / undo deployment" | `/fluent-rollback` |
| "Bootstrap account / new environment" | `/fluent-bootstrap` |
| "Show feature dashboard" | `/fluent-feature-dashboard` |
| "Generate component README" | `/fluent-frontend-readme` |
| "Validate this mermaid diagram" | See `knowledge/mermaid-syntax-rules.md` |
| "Show workspace tree / directory structure" | `/fluent-workspace-tree` |
| "Phase this feature / break into slices" | `/fluent-feature-phase` |
| "Add component to SDK project" | `/fluent-mystique-component` |
| "Preview UI change / mock component" | `/fluent-mystique-preview` |
| "Archive this feature / mark as done" | `/fluent-archive` |
| "Manage inventory / virtual catalogue" | `/fluent-inventory-catalog` |
| "SDK hooks / registry API / component patterns" | `/fluent-mystique-sdk-reference` |

---

## 13. Workspace Setup

### Directory Layout

Skills organize all implementation artifacts under `accounts/<PROFILE>/`:

```
accounts/
  <PROFILE>/                           # matches your FLUENT_PROFILE name
    SOURCE/                            # account-level, shared across retailers
      backend/                         # Java Maven plugin repos
        <repo-name>/                   # git-cloned custom plugin repo
          resources/module.json
          pom.xml
          src/main/java/...
        <reference-module>/            # reference module package (module.json + JAR)
          module.json
          assets/rules/*.jar
        .decompiled/<jar-basename>/    # auto-generated from JAR decompilation
          DECOMPILED.md                # marker with source JAR, date, decompiler
          com/fluentcommerce/...       # decompiled Java classes
      frontend/                        # Mystique SDK component projects
        <project-name>/               # custom SDK component project
          package.json
          src/index.tsx
    workflows/                         # retailer-scoped workflow definitions
      <RETAILER_REF>/
        ORDER__HD.json
        FULFILMENT__HD_WH.json
        workflow-context.json          # download metadata
    features/                          # feature-axis: one dir per feature
      curbside-pickup/
        spec.md                        # business spec (from use-case-discover)
        plan.md                        # implementation plan (from feature-plan)
        architecture.md                # feature architecture doc (from feature-explain)
        status.json                    # machine-readable lifecycle state
    analysis/                          # generated analysis artifacts
      code/source-map.json
      modules/                         # persistent module inventory
    reports/                           # ephemeral reports
      module-validate/*.report.json
    tasks/                             # operational task plans (non-feature)
      2026-02-23-rule-scaffold-curbside-pickup.md
    feedback/                          # skill execution learnings
      <skill>.jsonl                    # append-only records
      index.json                       # counters
    sessions/                          # audit trail exports
    settings/backups/                  # non-manifest setting backups
    manifests/backups/                 # manifest setting backups
    knowledge/                         # account-level overrides (takes precedence)
    workspace-state.json               # cached state for idempotent re-runs
  workspace-index.json                 # cross-profile index
```

Directories are created on demand by skills (`mkdir -p`) — nothing is pre-created.

### Why this layout

- `SOURCE/` is at the profile (account) level because plugin code is deployed per-account and shared across retailers. Split into `backend/` (Java plugins, reference JARs, `.decompiled/` output) and `frontend/` (Mystique SDK component projects).
- `workflows/` are scoped by retailer ref because workflow definitions can differ per retailer.
- `analysis/` holds generated artifacts reused across skills (source maps, module validation, topology).
- `features/` stores per-feature artifacts with machine-readable `status.json` tracking lifecycle state.
- `reports/` is ephemeral — regenerated on each skill run.
- `feedback/` is append-only — learnings from past skill executions reused in pre-flight.

### Adding Source Code

**Clone Java plugin repos:**

```bash
cd accounts/MY_PROFILE/SOURCE/backend
git clone https://your-org/fc-plugin-custom.git
git clone https://your-org/fc-plugin-returns.git
```

Each repo should contain: `resources/module.json`, `pom.xml`, `src/main/java/`. Skills auto-detect repos by searching for these files recursively.

**Add a JAR (no source available):**

```bash
cp fc-plugin-custom-1.2.3.jar accounts/MY_PROFILE/SOURCE/backend/
```

Skills will auto-decompile it into `SOURCE/backend/.decompiled/<jar-basename>/`, extract `module.json`, and create a `DECOMPILED.md` marker. Decompiled source is **read-only** — skills can analyze but never suggest editing it.

**Add reference/OOTB modules:**

```bash
cp -r fluent-module-order/ accounts/MY_PROFILE/SOURCE/backend/
# Contains: module.json + assets/rules/*.jar
```

Skills read rule names and descriptions from `module.json` — no decompilation needed for metadata.

### Downloading Workflows

Workflows are downloaded per-retailer:

```bash
fluent workflow download -p MY_PROFILE -r "My Retailer" -w all \
  -o accounts/MY_PROFILE/workflows/"My Retailer"/
```

Or let `/fluent-connect` do it automatically during workspace setup.

### How Analysis Works

Skills build a holistic view by cross-referencing four sources:

| Source | What it provides |
|--------|-----------------|
| **Live environment** (`plugin.list`) | All registered orchestration rules |
| **Local source** (git repos) | Full Java source — modifiable, buildable |
| **Local JARs** (decompiled) | Bytecode analysis — analyzable, read-only |
| **Workflow definitions** (downloaded JSON) | Status graphs, rulesets, event chains |

This produces a **deployed rule inventory** — each rule classified as "full source", "decompiled", or "missing":

| Status | What you can do |
|--------|-----------------|
| Full source | Analyze, modify, build, redeploy |
| Decompiled | Analyze behavior, cannot modify |
| Missing | Blind spot — provide source or JAR |

The inventory persists in `workspace-state.json` and powers `/fluent-custom-code`, `/fluent-workflow-analyzer`, `/fluent-rfl-assess`, and other skills.

### Adding a New Account

```bash
mkdir -p accounts/NEW_PROFILE/SOURCE/backend
mkdir -p accounts/NEW_PROFILE/SOURCE/frontend
mkdir -p accounts/NEW_PROFILE/workflows
```

Then clone repos, download workflows, or just run `/fluent-connect` interactively to do it all.

### Chrome DevTools MCP (Browser UI Testing)

[Chrome DevTools MCP](https://www.npmjs.com/package/chrome-devtools-mcp) is auto-configured by `mcp-setup`. It provides browser automation for `/fluent-ui-test` and `/fluent-ui-record`.

| Capability | Tool | Used by |
|-----------|------|---------|
| Navigate to OMS/Store apps | `navigate_page` | ui-test, ui-record |
| Read page structure (DOM snapshot) | `take_snapshot` | ui-test, ui-record |
| Capture visual evidence | `take_screenshot` | ui-test, ui-record |
| Inject DOM annotation overlays | `evaluate_script` | ui-test, ui-record |
| Fill login forms | `type_text`, `click` | ui-test, ui-record |
| Detect JS/GraphQL errors | `list_console_messages` | ui-test, ui-record |
| Continuous video recording | `--save-video` flag | ui-record |

**Enable video recording:**

```bash
npx @fluentcommerce/ai-skills mcp-setup --profile MY_PROFILE --save-video
```

FFmpeg is optional — enables post-processing (trim, convert `.webm` to `.mp4`, generate GIF previews). Install with `winget install ffmpeg` (Windows) or `brew install ffmpeg` (macOS).

### .gitignore

The `accounts/` directory should be in `.gitignore` — it may contain profile references, downloaded workflows, and customer-specific source:

```gitignore
accounts/
.mcp.json
```

---

*This document is part of the `@fluentcommerce/ai-skills` package and is the canonical operational reference.*
