@fluentcommerce/ai-skills 0.13.0 → 0.15.0

package/docs/fluent-ai-skills-reference.md

@@ -0,0 +1,1351 @@
+# 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.
+
+> **This is the comprehensive single-document reference.** It covers architecture, MCP tools, feature lifecycle, and deployment in one file. If you prefer a guided path, start with [Your First Session](01-first-session.md) (20 min) then [Prompt Guide](02-prompt-guide.md) (10 min). See [INDEX.md](INDEX.md) for the full reading order.
+
+> **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 and, in the skills-first path, Codex so the assistant can analyze workflows, scaffold rules, generate rule tests, 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
+# Optional: add --profile-retailer YOUR_RETAILER_REF if you know the retailer ref
+# (find it with: fluent profile retailers YOUR_PROFILE)
+```
+
+| 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. The Fluent CLI accepts either a retailer **ref** (e.g., `MY_RETAILER`) or a **display name** (e.g., `"My Retailer"`) — it resolves both. Find yours with `fluent profile retailers YOUR_PROFILE`. |
+| **Skill** | A structured instruction file that teaches the AI a specific Fluent task. Installed into Claude Code by default, or into Codex with `--target codex`. Claude commonly uses `/fluent-<name>` slash commands; Codex uses the same skills through natural-language prompts. |
+| **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** | 60+ skills across CLI, dev, MCP, and RFL groups, 6 agents, plus packaged platform knowledge docs |
+| **@fluentcommerce/fluent-mcp-extn** | MCP extension server — 55+ 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 (8) · Dev (52) · RFL (1) · MCP (2)
+
+**Supported IDE:** Claude Code (primary) and Codex (experimental skills-first flow)
+
+---
+
+## 2. Getting Started
+
+> **Full walkthrough:** See the [Getting Started Guide](05-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
+```
+
+If you already know the retailer ref, add `--profile-retailer YOUR_RETAILER_REF`. If you only know the trading/display name, omit that flag and let `fluent-connect` discover the retailer interactively.
+
+**Connect** (in Claude Code): `/fluent-connect` — downloads workflows, scans source, decompiles JARs, builds rule inventory.
+
+**Connect** (in Codex): `Use the fluent-connect skill to connect this workspace with profile YOUR_PROFILE.`
+
+> **Expect first-run permission prompts.** The initial connect/bootstrap flow runs shell commands, reads `~/.fluentcommerce/`, and writes `.mcp.json` plus `accounts/` workspace files.
+
+**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.
+
+Install also prepares workspace-root references outside `accounts/<PROFILE>/`: packaged `knowledge/`, packaged `docs/`, plus starter `CLAUDE.md` and `AGENTS.md` instruction files.
+
+| 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 |
+| `accounts/<PROFILE>/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-status`, 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, rule tests,<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>55+ 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 — 55+ tools: events, batch, metrics, entities, settings, cache, connections, planning | 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 | 18+ (20+ recommended) |
+
+### 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, rule tests, Maven modules, workflow JSON, settings, events, deployment | `/fluent-workflow-builder`, `/fluent-rule-scaffold`, `/fluent-rule-test`, `/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 8 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, rule test, 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` | 8 | Fluent CLI command-family coverage: connect, profile, retailer, modules, workflows, MCP/CI-CD, bootstrap |
+| `dev` | 52 | **Backend:** workflow builder/analyzer, connection analysis, custom code, transition API, rule scaffold, rule test generation/repair, module scaffold/validate/build, source onboarding, trace, entity-flow diagnose, event API, system monitoring, batch, settings, deploy, workflow deploy, rollback. **Frontend:** mystique assess (validate + analyze), manifest builder, SDK scaffold/component/reference, manifest diff, frontend build (7 gates)/review (9 phases)/readme, UI test, UI record. **Cross-cutting:** feature planning, use-case discover, feature status/explain, implementation map, scope plan, E2E test, test data, session, sourcing, knowledge init, workspace tree, skill observability, account snapshot, goal |
+| `rfl` | 1 | Production readiness assessment — scored report across workflows, rules, settings, integrations |
+| `mcp-extn` | 2 | MCP extension tools reference (55+ tools in 15 categories) + official CLI MCP server reference |
+
+### Workspace Directory Structure
+
+Account-specific artifacts are scoped under `accounts/<PROFILE>/`. The installer also creates workspace-root reference files and docs. Directories are created on demand — nothing is pre-created beyond those installer-managed references.
+
+```
+fluent-ai-workspace/
+├── .mcp.json                        ← MCP server config (auto-generated, gitignored)
+├── CLAUDE.md                        ← Starter workspace instructions for Claude Code
+├── AGENTS.md                        ← Starter workspace instructions for Codex/agentic tooling
+├── knowledge/                       ← Packaged platform knowledge copied locally
+├── docs/                            ← Packaged reference docs copied locally
+└── accounts/<PROFILE>/              ← All account-specific implementation artifacts
+    │
+    ├── 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-assess` → `/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](03-use-cases.md) has 21 scenario-based walkthroughs with step-by-step examples and expected outputs. The [Getting Started Guide](05-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 or validate a manifest | "What components are used in admin?" | `/fluent-mystique-assess` |
+| 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` |
+| Write or repair a rule test | "Generate tests for ValidateReturnWindow" | `/fluent-rule-test` |
+| 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-module-convert` |
+| 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-build` |
+| **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-assess` |
+| 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-status` |
+| 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 scope or phase a feature | "Break this scope doc into tasks" | `/fluent-scope-plan` |
+| Audit what skills ran | "What skills ran this session?" | `/fluent-session` |
+| Export audit trail | "Export a JSON audit trail" | `/fluent-session export` |
+| Trace skill invocations, routing, feedback | "What skills fired and why?" | `/fluent-skill-observability` |
+| 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` |
+| Pursue a goal autonomously | "Make the return flow work end to end" | `/fluent-goal` |
+
+---
+
+## 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" | 37 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/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/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 18+** (20+ recommended).
+
+**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-skill-observability` | 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/feature-dashboard.mjs --setup
+
+# Start live server (auto-refreshes on file changes)
+node fluent-ai-skills/tools/feature-dashboard.mjs --profile ACME --serve --port 3456
+
+# Generate static HTML only (no server)
+node fluent-ai-skills/tools/feature-dashboard.mjs --profile ACME
+
+# All profiles at once (static only)
+node fluent-ai-skills/tools/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 "Connection (4)"
+        C1["connection_add / list / remove / switch"]
+    end
+    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 (9)"
+        G1["graphql_query / queryAll / batchMutate"]
+        G2["graphql_introspect / listRoots / buildQuery"]
+        G3["graphql_validate / generateFull / planOperation"]
+    end
+    subgraph "Metrics (10)"
+        MR1["metrics_query / healthCheck / sloReport"]
+        MR2["metrics_labelCatalog / metricCatalog / topEvents"]
+        MR3["metrics_compare / mutationAudit / planQuery / snapshot"]
+    end
+    subgraph "Entities (5)"
+        N1["entity_create / update / get"]
+        N2["entity_planCreate / planUpdate"]
+    end
+    subgraph "Batch (6)"
+        B1["batch_create / send / status"]
+        B2["batch_batchStatus / results / describePayload"]
+    end
+    subgraph "Workflows (6)"
+        W1["workflow_get / list / upload"]
+        W2["workflow_diff / simulate / transitions"]
+    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_metricCatalog` | List available metric names and types |
+| | `metrics_topEvents` | Rank events by name/entity/status |
+| | `metrics_compare` | Compare metrics across time windows |
+| | `metrics_mutationAudit` | Audit write operations via metrics |
+| | `metrics_planQuery` | Plan a metrics query from natural language |
+| | `metrics_snapshot` | Point-in-time metrics snapshot |
+| **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 |
+| | `graphql_planOperation` | Plan a GraphQL operation from natural language |
+| **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 |
+| | `batch_describePayload` | Describe expected payload schema for an entity type |
+| **Webhook** | `webhook_validate` | Validate payload + optional signature verification |
+| **Connection** | `connection_add` | Add a runtime connection slot (CLI profile, OAuth, or static token) |
+| | `connection_list` | List all configured connection slots |
+| | `connection_remove` | Remove a runtime connection slot |
+| | `connection_switch` | Switch active connection at runtime |
+| **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 |
+| | `entity_planCreate` | Plan an entity creation from natural language |
+| | `entity_planUpdate` | Plan an entity update from natural language |
+| **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 |
+| **Time** | `time_resolveWindow` | Resolve relative time expressions to absolute ranges |
+| **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 [Dev Workflow — Deploy, Promote, and Rollback](06-dev-workflow.md) for step-by-step instructions, environment promotion sequences, selective deployment recipes, rollback playbook, 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 | IDE has stale runtime state | Restart Claude Code or open a new Codex session, then 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 |
+| Workflow changes not visible after deploy | Three cache layers (MCP server, local files, CLI workflowlog) | See [Workflow Caching & Staleness](workflow-reference.md#workflow-caching--staleness) for layer-by-layer diagnosis |
+| 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 your IDE/session |
+
+### 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 your IDE or open a new Codex session (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. Use `--purge` to also remove global knowledge (`~/.claude/fluent-knowledge/`). |
+| `doctor` | Full setup health check — Node, CLI, IDE, skills, MCP, knowledge, profile, connectivity, and version comparison (local/global/npm). |
+| `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` |
+| Codex (user scope) | `~/.codex/config.toml` |
+| Codex (project scope) | 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` |
+| Rule unit test generation and repair | `/fluent-rule-test` |
+| 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` |
+| Entity-ref runtime vs workflow diff | `/fluent-entity-flow-diagnose` |
+| 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 & analysis | `/fluent-mystique-assess` |
+| SDK component scaffolding | `/fluent-mystique-scaffold` |
+| SDK build pipeline (7 gates) | `/fluent-frontend-build` |
+| SDK code quality audit (9 phases) | `/fluent-frontend-review` |
+| SDK README generation | `/fluent-frontend-readme` |
+| 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-module-convert` |
+| Sourcing framework | `/fluent-sourcing` |
+| Test data creation | `/fluent-test-data` |
+| Version management | `/fluent-build` |
+| Rollback | `/fluent-rollback` |
+| Session tracking and audit export | `/fluent-session` |
+| Feature status dashboard | `/fluent-feature-status` |
+| Feature dashboard (live HTML) | `/fluent-feature-status` |
+| Scope decomposition & feature phasing | `/fluent-scope-plan` |
+| Ready For Launch assessment | `/fluent-rfl-assess` |
+| Skill observability (tracing, routing, feedback) | `/fluent-skill-observability` |
+| 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 MCP and CI/CD setup | `/fluent-cli-mcp-cicd` |
+| CLI retailer management | `/fluent-cli-retailer` |
+| 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` |
+| Goal-directed autonomous orchestration | `/fluent-goal` |
+| Account environment snapshot | `/fluent-account-snapshot` |
+| Rule lookup and discovery | `/fluent-rule-lookup` |
+
+### Routing Guide
+
+| User says... | Route to |
+|---|---|
+| "Why did this fail?" / "Entity stuck?" | `/fluent-trace` |
+| "What happened vs what should have happened for this entity ref?" | `/fluent-entity-flow-diagnose` |
+| "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` |
+| "Write tests for a rule / generate rule tests / fix rule test" | `/fluent-rule-test` |
+| "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-status` |
+| "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-scope-plan` |
+| "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>/`:
+
+Workspace root also contains installer-managed reference material:
+
+```
+<project-root>/
+├── .mcp.json                        ← MCP server config
+├── CLAUDE.md                        ← Starter workspace instructions for Claude Code
+├── AGENTS.md                        ← Starter workspace instructions for Codex/agentic tooling
+├── knowledge/                       ← Packaged platform knowledge copied locally
+├── docs/                            ← Packaged reference docs copied locally
+└── accounts/<PROFILE>/              ← Account-specific implementation artifacts
+```
+
+```
+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
+# -r accepts either the retailer ref or display name
+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.*