npm package: @fluentcommerce/ai-skills
Description: [Experimental] Fluent Commerce domain knowledge for Claude Code. Skills, agents, and MCP server configs for workflows, events, rules, and APIs.
Author: Fluent Commerce
Latest version: 0.15.0

# @fluentcommerce/ai-skills

[![npm](https://img.shields.io/npm/v/@fluentcommerce/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 package is **NOT production-ready**. It is an internal labs experiment under active development.
>
> - **No stability guarantees** — skills, CLI options, MCP tool contracts, and config may change or break between any release
> - **No support** — this is not an officially supported Fluent Commerce product
> - **No warranty** — provided as-is for experimentation and internal evaluation only
> - **Do NOT use in production** without thorough review and explicit sign-off from your team
>
> Pin to an exact version (`@0.13.0`) if you depend on current behavior.

Teach your AI assistant to work with [Fluent Commerce](https://fluentcommerce.com) (distributed order management) — analyze workflows, scaffold rules, debug events, build manifests, and deploy — all through natural language.

**63 skills** · 6 agents · Claude Code first, Codex + Gemini CLI supported as experimental targets

---

## Quick Start (copy-paste)

> **`npm` vs `npx` — which do I use?**
> - `npm install -g <package>` permanently installs a CLI tool on your machine (use for Claude Code, Gemini CLI)
> - `npx <package>` runs a package once without installing it (use for `@fluentcommerce/ai-skills` commands)
>
> **Rule of thumb:** `npm install -g` for tools you keep. `npx` for everything else in this guide.

```bash
# 1. Install prerequisites (skip any you already have)
# Node.js 20+: https://nodejs.org
# Fluent CLI: https://docs.fluentcommerce.com/building-blocks/fluent-cli-package
# Claude Code, Codex, OR Gemini CLI — at least one is required:
npm install -g @anthropic-ai/claude-code   # Claude Code (primary)
# npx codex                                # Codex (alternative — see note below)
# npm install -g @google/gemini-cli        # Gemini CLI (experimental custom-command target)

# 2. Create a Fluent CLI profile (get values from your Fluent account team)
fluent profile create MY_PROFILE \
  --id my-account-id \
  --username admin@example.com \
  --password "your-password" \
  --client-secret "your-client-secret" \
  --base-url "https://my-account-id.sandbox.api.fluentcommerce.com"

# 3. Create workspace, install skills + MCP
mkdir my-workspace && cd my-workspace
git init
# If you know the retailer ref already, add: --profile-retailer MY_RETAILER_REF
# If you only know the trading/display name, omit that flag and let /fluent-connect pick the retailer interactively
npx @fluentcommerce/ai-skills install --profile MY_PROFILE

# 4. Verify everything is set up correctly
npx @fluentcommerce/ai-skills doctor

# 5. Launch Claude Code (MUST be in the workspace folder)
claude
```

Then type this as your **first prompt** in Claude Code (in the chat input, not a terminal):

```
/fluent-connect --profile MY_PROFILE
```

This downloads workflows, scans your account, and sets up the workspace. After that, just talk naturally:

```
"What's deployed on this account?"
"Help me build a return order workflow"
"Why is order HD-001 stuck?"
```

> **Using Codex instead of Claude Code?** Replace steps 3-5 above with:
> ```bash
> npx @fluentcommerce/ai-skills install --target codex --profile MY_PROFILE
> npx @fluentcommerce/ai-skills doctor
> # Open Codex in this workspace folder, then ask:
> ```
> `Use the fluent-connect skill to connect this workspace with profile MY_PROFILE.`
> If you already know the retailer ref, include it in the prompt. The rest of the docs use Claude Code slash commands — in Codex, use natural language equivalents (e.g., "Build an ORDER::RETURN workflow" instead of `/fluent-workflow-builder`).
>
> **Using Gemini CLI instead?** Replace steps 3-5 above with:
> ```bash
> npx @fluentcommerce/ai-skills install --target gemini --scope project --profile MY_PROFILE
> npx @fluentcommerce/ai-skills doctor
> # Open Gemini CLI in this workspace folder, then run:
> ```
> `/fluent-connect --profile MY_PROFILE`
> Gemini support is currently **experimental** and uses Gemini custom commands in `.gemini/commands/` plus an installer-managed skill mirror in `.gemini/skills/`. Project scope is recommended.
>
> **Expect first-run permission prompts:** `fluent-connect` and `fluent-bootstrap` run `fluent` / `npx`, read `~/.fluentcommerce/`, and write `.mcp.json` plus `accounts/` workspace files. In tool-sandboxed IDEs, that usually triggers shell/filesystem permission questions on the first run.
>
> **Common mistake:** If skills don't work, run `npx @fluentcommerce/ai-skills doctor` in the workspace folder. It checks every prerequisite and tells you exactly what to fix.

> **What goes where:** Skills, agents, and platform knowledge install **globally** to `~/.claude/` — once installed, they're available in every workspace automatically. `.mcp.json` and `CLAUDE.md` install **locally** because they contain workspace-specific credentials and context.
>
> **Setting up a second workspace?** You only need MCP config — skills and knowledge are already global:
> ```bash
> mkdir client-b && cd client-b && git init
> npx @fluentcommerce/ai-skills mcp-setup --profile CLIENT_B
> ```
> Or run `install` again for a full setup (copies local knowledge + docs too).
>
> **How to verify:** `npx @fluentcommerce/ai-skills doctor` checks everything (skills, MCP, knowledge, docs, profile connectivity). `npx @fluentcommerce/ai-skills status` checks just the skill installation.

> [!IMPORTANT]
> **`knowledge/` and `docs/` are merge-safe.** The installer copies platform knowledge and reference docs into your workspace but **never deletes your own files**. Only files originally installed by the package are overwritten or removed on reinstall/uninstall. If you add custom notes, architecture docs, or team knowledge to these directories, they will be preserved across upgrades. A `.fluent-installed-files.json` manifest in each directory tracks which files are managed by the package.

---

## How It Works

AI coding assistants are general-purpose — they don't know Fluent Commerce. This package injects Fluent-specific domain knowledge so Claude Code, and in the skills-first path Codex, can understand workflows, events, rules, GraphQL patterns, CLI commands, and deployment procedures.

```
  You ──► Claude Code
              │
              │  skills inject domain knowledge
              ▼
          AI Agent
           ╱    ╲
          ▼      ▼
   Fluent Commerce    Fluent UX Apps
     Platform           OMS / Store
   (fluent-mcp +      (chrome-devtools
    fluent-mcp-extn    browser automation)
    live API access)
```

The AI doesn't just know what to say — it calls live APIs via [MCP](https://modelcontextprotocol.io) (Model Context Protocol — the standard for connecting AI assistants to external tools) to query your workflows, fire events, check metrics, inspect manifests, and verify deployments in real time.

---

## Who Is This For?

<table>
<tr>
<td width="80" align="center"><h3>🔨</h3><b>Builder</b></td>
<td>
<b>Implementation consultants &amp; developers</b> building Fluent Commerce for clients. You touch workflows, rules, manifests, and deployments daily.
<br/><br/>
<b>Try these:</b><br/>
<code>"Help me define use cases for return orders"</code> → interactive wizard producing spec.md<br/>
<code>"Plan the return order feature"</code> → 18-section plan with diagrams, waits for approval<br/>
<code>"Build an ORDER::RETURN workflow"</code> → scaffolds rules, builds JSON, compiles, deploys<br/>
<code>"Add an appeasement form to the order page"</code> → builds manifest fragment, validates, deploys<br/>
<code>"Deploy ORDER::HD to staging"</code> → 37 pre-flight gates, deploy, verify
<br/><br/>
<b>Your skills:</b> The full lifecycle — <code>use-case-discover</code> → <code>feature-phase</code> (complex) → <code>feature-plan</code> → <code>rule-scaffold</code> → <code>workflow-builder</code> → <code>mystique-builder</code> → <code>module-deploy</code> → <code>e2e-test</code>
</td>
</tr>
<tr>
<td width="80" align="center"><h3>🔍</h3><b>Investigator</b></td>
<td>
<b>Support engineers &amp; debuggers</b> troubleshooting production issues — stuck orders, failed events, missing buttons, broken workflows.
<br/><br/>
<b>Try these:</b><br/>
<code>"Why is order HD-12345 stuck in BOOKED?"</code> → traces event history, finds root cause + fix<br/>
<code>"Show event failure rates for the last hour"</code> → metrics anomaly detection with alerts<br/>
<code>"The approve button is missing on credit memos"</code> → checks Transition API, modules, subtype<br/>
<code>"Trace event ON_SEND_FULFILMENT for this order"</code> → rule-by-rule execution breakdown
<br/><br/>
<b>Your skills:</b> <code>trace</code>, <code>transition-api</code>, <code>workflow-analyzer</code>, <code>system-monitoring</code>, MCP event &amp; metrics tools
</td>
</tr>
<tr>
<td width="80" align="center"><h3>📋</h3><b>Reviewer</b></td>
<td>
<b>Tech leads &amp; architects</b> assessing quality, auditing implementations, and running go-live readiness checks.
<br/><br/>
<b>Try these:</b><br/>
<code>"Run a Ready For Launch assessment"</code> → scored audit across workflows, rules, settings<br/>
<code>"Map the entire implementation"</code> → feature inventory with dependency graphs<br/>
<code>"Explain how Home Delivery works end-to-end"</code> → state diagrams, rules table, architecture.md<br/>
<code>"Analyze workflow connection topology"</code> → cross-entity dependency maps
<br/><br/>
<b>Your skills:</b> <code>rfl-assess</code>, <code>implementation-map</code>, <code>feature-explain</code>, <code>connection-analysis</code>, <code>custom-code</code>
</td>
</tr>
<tr>
<td width="80" align="center"><h3>🚀</h3><b>New Starter</b></td>
<td>
<b>Just joined the project.</b> Need to understand what's deployed before you can contribute. Don't know where anything is yet.
<br/><br/>
<b>Try these:</b><br/>
<code>"Set up my workspace"</code> → connects account, downloads workflows, scans code<br/>
<code>"What's deployed on this account?"</code> → full implementation inventory<br/>
<code>"Explain the custom rules"</code> → annotated analysis of all plugin code<br/>
<code>"Show me the feature dashboard"</code> → live status of all features in progress
<br/><br/>
<b>Your path:</b> <code>/fluent-connect</code> → <code>implementation-map</code> → <code>feature-explain</code> → <code>custom-code</code> → start building
</td>
</tr>
</table>

> **Don't see yourself?** These personas overlap. A builder debugs. A reviewer onboards. An investigator ships hotfixes. Start with whatever matches your current task — the AI routes to the right skills automatically.

---

## What Can You Do?

The [persona examples above](#who-is-this-for) show common prompts for each role. Here are additional capabilities:

| What you say | What happens |
|---|---|
| "Preview what the appeasement card looks like" | Three modes (ADD/MODIFY/REMOVE) with color-coded glow highlights, iterative refinement, before/after GIF generation |
| "Verify the OMS orders page works" | Browser login, navigate, DOM snapshot, screenshot evidence report |
| "Show event failure rates for the last hour" | Metrics anomaly detection with threshold alerts |
| "Trace event ON_SEND_FULFILMENT for this order" | Rule-by-rule execution breakdown with timing and error details |
| "Add an appeasement form to the order page" | Builds Mystique manifest fragment, validates against 86 components, deploys to OMS app |
| "What features are in progress?" | Reads `status.json` across all features, shows lifecycle state, resumes where you left off |

See all 21 scenarios with exact prompts: [docs/03-use-cases.md](docs/03-use-cases.md)

---

## Getting Started

**You don't need to clone a repository.** This is an npm package — you run it with `npx` in any empty folder and it sets up everything.

### Prerequisites

| Requirement | How to install | Verify |
|---|---|---|
| **Node.js `>=20.0.0 <23.0.0`** | [nodejs.org](https://nodejs.org) | `node --version` |
| **npm `>=10.5.0`** | Included with Node.js LTS | `npm --version` |
| **git** | [git-scm.com](https://git-scm.com) | `git --version` |
| **Fluent CLI** | `npm install -g https://downloads.fluentcommerce.com/v1.0.0/fluent-cli/release/latest` | `fluent --version` |
| **Claude Code** | `npm install -g @anthropic-ai/claude-code` | `claude --version` |
| **Anthropic account** | [console.anthropic.com](https://console.anthropic.com) | Claude Code prompts on first launch |
| **A Fluent Commerce account** | Contact your Fluent account team | You'll need the 5 values below |

> **Node.js version note:** The Fluent CLI supports Node `>=20.0.0 <23.0.0` and npm `>=10.5.0`. Use those versions to avoid confusing startup errors when Claude Code tries to connect MCP servers.

> **Admin permissions required:** Before installing the Fluent CLI, make sure you are signed in as an Administrator user on your local machine and have permission to install new software.

> **`npm install` vs `npx` — when to use which:**
> - `npm install -g <package>` installs a tool **permanently** as a global command (used for Claude Code, Fluent CLI, Gemini CLI — tools you want always available).
> - `npx <package>` downloads and runs a package **on the fly** without installing globally. This guide uses `npx` for `ai-skills` so you always get the latest version.
> - **Prefer a permanent install?** Run `npm install -g @fluentcommerce/ai-skills` once, then replace every `npx @fluentcommerce/ai-skills` command in this guide with just `ai-skills`. This avoids the repeated download and is faster for daily use.

> **Default target: Claude Code.** Codex and Gemini CLI are also supported with `--target codex` and `--target gemini`, but both are still experimental.
>
> **Codex note:** The docs below use Claude Code slash commands for the primary examples. In Codex, use natural-language prompts such as `Use the fluent-connect skill to connect this workspace with profile MY_PROFILE.` instead of slash commands.
>
> **Gemini CLI note:** Install with `npx @fluentcommerce/ai-skills install --target gemini --scope project` when possible. That keeps Gemini commands and MCP config inside the workspace. Run `/commands reload` after reinstalling commands in an active Gemini session.

**Before you start, gather these 5 values from your Fluent account team:**

| Value | Example | Where it's used |
|---|---|---|
| Account ID | `my-account-id` | Profile creation (`--id`) |
| API Base URL | `https://my-account-id.sandbox.api.fluentcommerce.com` | Profile creation (`--base-url`) |
| Username | `admin@example.com` | Profile creation (`--username`) |
| Password | `your-password` | Profile creation (`--password`) |
| Client Secret | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Profile creation (`--client-secret`) — required for API auth |

> **Windows users:** All commands in this guide use Unix shell syntax. They work as-is in **Git Bash** ([git-scm.com](https://git-scm.com)) and **WSL**. For **PowerShell**, make these translations:
> - Line continuations: `\` → `` ` ``
> - Environment variables: `export VAR=val` → `$env:VAR="val"`
> - Home paths: `~/.fluentcommerce/` → `C:\Users\<you>\.fluentcommerce\`
> - Home paths: `~/.claude/` → `C:\Users\<you>\.claude\`
>
> **Recommended:** Use Git Bash (bundled with Git for Windows) or WSL to follow this guide with minimal translation.

> **First-run permission prompts:** When you first run `/fluent-connect` inside Claude Code, it will ask permission to run shell commands (`fluent`, `mkdir`, `npx`), read your `~/.fluentcommerce/` profile, and write workspace files. This is normal Claude Code sandbox behavior. Say "Yes" to each prompt, or use `claude --dangerously-skip-permissions` during initial evaluation to bypass them. See [Onboarding Plan](docs/04-onboarding-plan.md) for details.

---

### Step 1 — Create a Fluent CLI profile

A **profile** is a named connection to your Fluent account stored securely in `~/.fluentcommerce/`.

```bash
fluent profile create MY_PROFILE \
  --id my-account-id \
  --username admin@example.com \
  --password "your-password" \
  --client-secret "your-client-secret" \
  --base-url "https://my-account-id.sandbox.api.fluentcommerce.com"
```

> Your Fluent account team provides the account ID, API base URL, and credentials. The `--client-secret` is required for API authentication.

Verify the profile and identify the retailer you want to work with:

```bash
fluent profile retailers MY_PROFILE
# Output example:
#   ACME Retail        (id: 2)
#   My Retailer        (id: 5)
```

If you already know the **retailer ref**, you can use it with `--profile-retailer MY_RETAILER_REF` in Step 2. If you only know the trading/display name, skip `--profile-retailer` and let `/fluent-connect` discover the retailer interactively.

---

### Step 2 — Create a workspace and install skills

A **workspace** is just an empty directory where all your Fluent development work lives. You can name it anything:

```bash
mkdir my-fluent-workspace && cd my-fluent-workspace
git init    # recommended — tracks your work and enables .gitignore

# Replace MY_PROFILE with your profile name from Step 1
# Optional: if you know the retailer ref already, add --profile-retailer MY_RETAILER_REF
npx @fluentcommerce/ai-skills install --profile MY_PROFILE
```

This single command:
1. Installs the current Fluent skill catalog into the selected IDE target (Claude Code by default, Codex with `--target codex`, Gemini CLI with `--target gemini`)
2. Configures MCP for that target (`.mcp.json`, `~/.codex/config.toml`, or Gemini `settings.json` depending on target/scope)
3. Checks prerequisites and reports any issues

**Alternative install paths:**

- **Skills only first:** `npx @fluentcommerce/ai-skills install`
- **Codex user install:** `npx @fluentcommerce/ai-skills install --target codex`
- **Codex project-local install:** `npx @fluentcommerce/ai-skills install --target codex --scope project` (skills stay in `.agents/skills`; add the separate Codex MCP setup below when you want live API tools)
- **Codex global MCP setup:** `npx @fluentcommerce/ai-skills mcp-setup --target codex --scope user --profile MY_PROFILE`
- **Gemini CLI install (experimental):** `npx @fluentcommerce/ai-skills install --target gemini`
- **Gemini CLI project-local install (recommended):** `npx @fluentcommerce/ai-skills install --target gemini --scope project`
- **Gemini CLI MCP setup:** `npx @fluentcommerce/ai-skills mcp-setup --target gemini --scope project --profile MY_PROFILE`
- **Add MCP later:** `npx @fluentcommerce/ai-skills mcp-setup --profile MY_PROFILE`
- **Faster MCP startup:** `npx @fluentcommerce/ai-skills install --profile MY_PROFILE --install-mcp-extn`
- **Optional browser / hosting MCPs:** see [`docs/mcp-servers.md`](docs/mcp-servers.md)

Use `install --profile ... --profile-retailer ...` when you already know the **retailer ref** and want everything wired immediately. Use `install --profile ...` plus `mcp-setup` or `/fluent-connect` when you want the workspace to discover the retailer interactively.

> **Codex project-scope note:** `install --target codex --scope project` copies skills into `.agents/skills`, but Codex MCP config is still user-scoped today. Pair it with `npx @fluentcommerce/ai-skills mcp-setup --target codex --scope user --profile MY_PROFILE` when you want live API-backed tools. If you skip that step, `doctor` will report `MCP config not found`.

> **Using Codex instead of Claude Code?** Use `--target codex` to install Codex skills. This is currently **skills-only**: Claude-specific agents and slash commands like `/fluent-connect` are not installed for Codex. For live MCP-backed tools in Codex, run `mcp-setup --target codex --scope user`.
>
> **Using Gemini CLI instead?** Use `--target gemini`. This installs Gemini custom commands and writes Gemini MCP config. This path is **experimental**, and project scope is recommended.
>
> **First-run permissions:** In Claude Code, Codex, or Gemini CLI, the initial connect/bootstrap flow may ask for permission to run shell commands, read `~/.fluentcommerce/`, and write MCP/workspace files. That is expected — these skills perform real CLI and filesystem work.

After a default Claude install, your folder contains:

```
my-fluent-workspace/
├── .mcp.json      <- MCP server config (tells your MCP-capable IDE how to reach Fluent APIs)
├── knowledge/     <- Platform knowledge docs (domain model, SDK reference, patterns)
└── docs/          <- Reference docs (use-cases, onboarding, agents guide, capability map)
```

For other targets:

- **Codex user scope:** skills live in `~/.codex/skills`; MCP config lives in `~/.codex/config.toml`
- **Codex project scope:** skills live in `.agents/skills`; MCP config still lives in `~/.codex/config.toml` after `mcp-setup --target codex --scope user`
- **Gemini project scope:** commands, mirrored skills, and MCP config live in `.gemini/`

**What's global vs what's local:**

> **TL;DR:** Skills + agents + platform knowledge = global (install once, works everywhere). MCP config + CLAUDE.md = local (per workspace). A second workspace only needs `mcp-setup --profile NEW_PROFILE`.

| Installed where | What | Persists across workspaces? |
|---|---|---|
| **Global** (`~/.claude/`) | Fluent skills, agents, and platform knowledge (fallback) | Yes — available in every workspace |
| **Global** (`~/.codex/skills`) | Fluent Codex skills (experimental, skills-only; mirrored to `~/.agents/skills`) | Yes — available in every workspace |
| **Global** (`~/.gemini/commands`) | Fluent Gemini custom commands (experimental) | Yes — available in every workspace |
| **Global** (`~/.gemini/skills`) | Installer-managed Gemini skill mirror for companion files | Yes — available in every workspace |
| **Local** (`.agents/skills`) | Fluent Codex skills for this workspace only (`--target codex --scope project`) | No — one per workspace |
| **Local** (`.gemini/commands`) | Fluent Gemini custom commands for this workspace only (`--target gemini --scope project`) | No — one per workspace |
| **Local** (`.gemini/skills`) | Installer-managed Gemini skill mirror for this workspace | No — one per workspace |
| **Local** (this folder) | `.mcp.json` — MCP server config pointing to your Fluent account | No — one per workspace |
| **Local** (this folder) | `knowledge/` — platform knowledge (domain model, SDK patterns, rule contracts) | No — managed by installer, refreshed on reinstall |
| **Local** (this folder) | `docs/` — reference docs (use-cases, onboarding, agents guide, capability map) | No — managed by installer, refreshed on reinstall |
| **Local** (this folder) | `CLAUDE.md` — starter workspace instructions for Claude Code (auto-generated, safe to edit; [details](#workspace-instruction-files)) | No — one per workspace |
| **Local** (this folder) | `AGENTS.md` — starter workspace instructions for Codex/agentic tooling (auto-generated when missing, safe to edit; [details](#workspace-instruction-files)) | No — one per workspace |
| **Local** (this folder) | `GEMINI.md` — starter workspace instructions for Gemini CLI (generated on Gemini installs, safe to edit; [details](#workspace-instruction-files)) | No — one per workspace |
| **Local** (this folder) | `accounts/` — workflows, features, source code (created in Step 3) | No — one per workspace |

You can have multiple workspaces (e.g., one per client) each with different profiles and retailers. Skills are shared; everything else is workspace-specific.

### Verify the installation

**Check which `ai-skills` version is installed:**

```bash
npx @fluentcommerce/ai-skills --version
```

This prints the exact package version `npx` resolves for this workspace, for example `fluent-ai-skills v0.13.0`.

**Run `doctor` — it checks everything in one shot:**

```bash
npx @fluentcommerce/ai-skills doctor
```

`doctor` validates: Node.js version, Fluent CLI installed, IDE detected (Claude Code, Codex, and/or Gemini CLI — warns if none found), skills installed, MCP config present with correct server config, local `knowledge/` and `docs/` present, workspace instruction files present, Fluent CLI profile exists and can authenticate, and MCP extension reachable. It also compares versions across four layers — running package, local knowledge, global knowledge (`~/.claude/fluent-knowledge/`), and npm registry — warning on any mismatches. Fix anything it flags before proceeding. Use `--fix` to auto-install the Fluent CLI if missing (requires Node >=20 and npm >=10.5).

**Quick status check (skills only):**

```bash
npx @fluentcommerce/ai-skills status
```

Shows which skill groups are installed and their install method (marketplace or file-copy). If something is missing, re-run `npx @fluentcommerce/ai-skills install --profile MY_PROFILE`.

**If you need to wire MCP separately** (e.g., changed profile, new workspace, or skipped `--profile` during install), use the command that matches your target:

```bash
# Claude Code / default workspace MCP
npx @fluentcommerce/ai-skills mcp-setup --profile MY_PROFILE

# Codex global MCP (used by both Codex user installs and Codex project-scope installs)
npx @fluentcommerce/ai-skills mcp-setup --target codex --scope user --profile MY_PROFILE

# Gemini CLI project MCP
npx @fluentcommerce/ai-skills mcp-setup --target gemini --scope project --profile MY_PROFILE
```

For Claude Code, this generates `.mcp.json` in the current folder. For Codex, it updates `~/.codex/config.toml`. For Gemini project scope, it updates `.gemini/settings.json`. Without the matching MCP config, the AI has no live API access. If you know the retailer ref, include `--profile-retailer MY_RETAILER_REF` here too. For the full MCP config structure, environment variables, and multi-profile switching, see [`docs/mcp-servers.md`](docs/mcp-servers.md).

To verify MCP servers are actually **reachable** (run inside Claude Code chat, not in terminal):
```
"Test my MCP connection"    → AI calls health_ping, confirms live API access
```

> **IMPORTANT — Restart required:** If Claude Code was already running, **quit and relaunch it** before Step 3. MCP servers only connect at startup. Without a restart, Claude Code won't see the MCP tools and API calls will fail.

---

### Step 3 — Open Claude Code and connect

> **Restart required:** If Claude Code was already running during install, **quit and relaunch it** now. MCP servers only connect at startup — without a restart, API calls will fail.

Launch Claude Code **in your workspace folder**:

```bash
claude    # starts Claude Code in the current directory
```

Then type this **slash command** in the Claude Code chat:

```
/fluent-connect --profile MY_PROFILE
```

> Slash commands like `/fluent-connect` are typed in the AI chat, not in a terminal. Claude Code recognizes them and runs the corresponding skill.

> **Note:** The slash command uses `--retailer` while the CLI install uses `--profile-retailer`. They're different tools — the CLI is a Node.js command; the slash command runs inside the AI session.

If you already know the retailer ref, you can be explicit:

```
/fluent-connect --profile MY_PROFILE --retailer MY_RETAILER_REF
```

If you're using Codex instead of Claude Code, open Codex in this workspace and ask:

```
Use the fluent-connect skill to connect this workspace with profile MY_PROFILE.
```

If you're using Gemini CLI, open Gemini CLI in this workspace and run:

```text
/fluent-connect --profile MY_PROFILE
```

This creates the full `accounts/` directory tree, downloads all workflows from your Fluent account, scans any source repos you've placed, decompiles deployed JARs, and builds a full picture of what's deployed.

#### Workspace directory layout

Legend: **[auto]** = created by CLI/skills, **[you]** = you create/populate, **[ai]** = AI generates during sessions

```
<project-root>/                       <- any directory where you run the installer
+-- .mcp.json                   [auto] MCP server config (generated by install/mcp-setup)
+-- CLAUDE.md                   [auto] Starter workspace instructions for Claude Code (auto-generated, safe to edit)
+-- AGENTS.md                   [auto] Starter workspace instructions for Codex/agentic tooling (auto-generated if missing, safe to edit)
+-- GEMINI.md                   [auto] Starter workspace instructions for Gemini CLI (generated on Gemini installs, safe to edit)
+-- knowledge/                  [auto] Platform knowledge docs — copied from package on install
|                                      (domain model, SDK patterns, rule contracts, order patterns)
+-- docs/                        [auto] Reference docs — copied from package on install
|                                      (use-cases, onboarding, agents guide, capability map)
+-- accounts/
    +-- MY_PROFILE/             [auto] Created by /fluent-connect or install --profile
        |
        +-- SOURCE/              [you] YOUR implementation source code
        |   +-- backend/         [you] Clone or copy your Java plugin repos here
        |   |   +-- fc-plugin-custom/     <- your repo (git clone or cp)
        |   |   |   +-- pom.xml
        |   |   |   +-- resources/module.json
        |   |   |   +-- src/main/java/...
        |   |   +-- .decompiled/ [auto] Auto-generated from deployed JARs by /fluent-connect
        |   |
        |   +-- frontend/        [you] Clone or copy your Mystique SDK component projects here
        |       +-- mystique-appeasement/  <- your repo
        |           +-- package.json
        |           +-- src/index.tsx
        |
        +-- knowledge/           [you] Account-specific conventions (via /fluent-knowledge-init)
        |   +-- naming-conventions.md
        |   +-- coding-standards.md
        |   +-- client/
        |
        +-- workflows/          [auto] Downloaded from Fluent by /fluent-connect
        |   +-- My Retailer/
        |       +-- ORDER__HD.json       <- live workflow JSON from your account
        |       +-- workflow-context.json
        |
        +-- features/             [ai] Created by AI during feature development
        |   +-- return-order/
        |       +-- spec.md              <- from /fluent-use-case-discover
        |       +-- plan.md              <- from /fluent-feature-plan
        |       +-- architecture.md      <- from /fluent-feature-explain
        |       +-- status.json          <- lifecycle tracker (auto-updated)
        |       +-- assets/              <- screenshots, recordings, evidence
        |
        +-- memory/               [ai] Auto-accumulated learnings from your sessions
        +-- feedback/             [ai] Skill execution feedback (success/failure patterns)
        +-- reports/              [ai] Ephemeral: build/, pre-deploy/, e2e-test/
        +-- analysis/             [ai] Persistent: code/, modules/, topology/
        +-- tasks/                [ai] Operational plans (non-feature work)
        +-- sessions/             [ai] Audit trail exports
```

#### Where to put your code

| What you have | Where it goes |
|---|---|
| **Java plugin repo** (pom.xml + src/) | Clone or copy into `accounts/MY_PROFILE/SOURCE/backend/` |
| **Module JAR or reference module** (module.json + JAR) | Copy into `accounts/MY_PROFILE/SOURCE/backend/` — auto-decompiled on connect |
| **Mystique SDK project** (package.json + TypeScript) | Clone or copy into `accounts/MY_PROFILE/SOURCE/frontend/` |

You can either **clone from a Git repository** or **copy the source folder directly** — both work:

```bash
# Option A: Clone from any Git host (Bitbucket, GitHub, GitLab, etc.)
cd accounts/MY_PROFILE/SOURCE/backend
git clone <your-repo-url>

# Option B: Copy an existing source folder
cp -r /path/to/fc-plugin-custom accounts/MY_PROFILE/SOURCE/backend/
```

The workspace `.gitignore` excludes `accounts/`, so cloned repos keep their own `.git` independently.

**Adding a JAR (no source):**

```bash
cp fc-plugin-custom-1.2.3.jar accounts/MY_PROFILE/SOURCE/backend/
# Skills will auto-decompile it to .decompiled/ and extract module.json
```

**Downloading workflows (if not using /fluent-connect):**

```bash
# Note: -r takes the retailer display name (from `fluent profile retailers`), not the ref
fluent workflow download -p MY_PROFILE -r "My Retailer" -w all \
  -o accounts/MY_PROFILE/workflows/"My Retailer"/
```

---

### Step 4 — Set credentials for browser UI testing (optional)

Needed for `/fluent-ui-test`, `/fluent-ui-record`, and `/fluent-mystique-preview` to log into OMS/Store apps. Add to your shell profile (`~/.bashrc`, `~/.zshrc`, or PowerShell `$PROFILE`):

```bash
export FLUENT_USERNAME=your-username
export FLUENT_PASSWORD=your-password
```

Profile-based auth handles all Fluent API calls automatically. These are only needed for browser automation.

---

### Step 5 — Start working

Pick a starting prompt based on [who you are](#who-is-this-for):

| Persona | First prompt |
|---|---|
| 🚀 **New Starter** | `Map the implementation — what workflows, rules, and settings are deployed?` |
| 🔨 **Builder** | `Help me define use cases for return orders` |
| 🔍 **Investigator** | `Why is order HD-001 stuck in BOOKED?` |
| 📋 **Reviewer** | `Run a Ready For Launch assessment` |

The AI invokes the right skills automatically and guides you through each step.

**Which skill for what?** [docs/02-prompt-guide.md](docs/02-prompt-guide.md) — progressive skill navigator with "If I'm building X" flows.

**Detailed scenarios:** [docs/03-use-cases.md](docs/03-use-cases.md) — 21 scenarios with exact prompts and what happens.

---

### Step 6 — Skill observability (optional)

Want to see which skills ran, audit routing accuracy, or check skill authoring quality? `/fluent-skill-observability` has four sub-commands:

| Sub-command | What it does | Requires setup? |
|---|---|---|
| `quality` | Static analysis of SKILL.md authoring (scores 10 dimensions) | No — works immediately |
| `trace show` | Shows which skills fired this session | Yes — needs trace data (see below) |
| `trace analyze` | Cross-session routing accuracy report | Yes — needs 10+ trace records |
| `feedback dashboard` | Per-skill success/failure rates and learnings | Yes — accumulates over sessions |

**Zero-config check** — run this right away in Claude Code:
```
/fluent-skill-observability quality workflow-builder
```
Or audit all installed skills at once: `/fluent-skill-observability quality` (no argument).

**To enable trace capture**, ask Claude Code to set up hooks:
```
/fluent-skill-observability trace hook-setup
```
This generates a PostToolUse hook config for `.claude/settings.json`. Once active, every skill invocation is logged to `accounts/<PROFILE>/traces/skill-trace.jsonl`. After a few sessions, `trace analyze` and `feedback dashboard` produce meaningful reports.

> Tracing is opt-in and lightweight. Without hook setup, skills still work normally — you just don't get execution telemetry.

---

## Feature Lifecycle

Every feature follows a structured lifecycle tracked in `status.json`. The AI reads this automatically and resumes where you left off across sessions.

```
DISCOVERY ──► PLANNING ──► APPROVED ──► IN_PROGRESS ──► BUILT ──► DEPLOYED ──► VERIFIED
(spec.md)    (plan.md)    (you approve)  (building)    (build ok) (deployed)  (e2e pass)
```

**Key rule:** The AI will never make changes before presenting a plan and waiting for your approval. Say "approved" or "go ahead" to proceed; ask questions or "reject" to revise.

**Resuming work:** Say `"What features are in progress?"` or `"Continue working on return-order"` — the AI reads `status.json` and picks up exactly where it left off.

**Full lifecycle details:** [Dev Workflow](docs/06-dev-workflow.md)

### Feature Dashboard

A live HTML dashboard shows all your features with status, specs, plans, architecture diagrams, feedback metrics, and session history — updating in real-time as the AI works.

**Via AI (easiest):** Say `"Show me the feature dashboard"` — the AI sets it up and launches it automatically.

**Manual setup:**

```bash
# One-time: download vendor libs (marked.js + mermaid.js from CDN)
npx @fluentcommerce/ai-skills dashboard --setup

# Start live dashboard (auto-refreshes when files change)
npx @fluentcommerce/ai-skills dashboard --profile MY_PROFILE --serve --port 3456

# Static HTML only (no server)
npx @fluentcommerce/ai-skills dashboard --profile MY_PROFILE
```

Open `http://localhost:3456` — features appear as soon as you run `/fluent-use-case-discover`.

**Full details:** Say `"Show me the feature dashboard"` or run `npx @fluentcommerce/ai-skills dashboard --help`

---

## Skill Groups

| Group | What it provides | Commands |
|---|---|---|
| `dev` | Full dev lifecycle — workflows, rules, modules, Mystique manifests, SDK components, UI preview, E2E testing, feature planning, debugging, monitoring | `/fluent-feature-plan`, `/fluent-workflow-builder`, `/fluent-mystique-builder`, `/fluent-e2e-test`, `...` |
| `cli` | Fluent CLI families — profile, retailer, settings, modules, workflows, bootstrap | `/fluent-connect`, `/fluent-profile`, `/fluent-workflow`, `/fluent-module-deploy`, `...` |
| `rfl` | Ready For Launch assessments | `/fluent-rfl-assess` |
| `mcp-extn` | MCP server operations — extension tools plus official CLI MCP utilities | `/fluent-mcp-tools`, `/fluent-mcp-core` |

All groups install by default. To install selectively:

```bash
npx @fluentcommerce/ai-skills install cli mcp-extn
```

### Agent Architecture

Six agents route requests automatically — you don't need to pick one:

| Agent | Role |
|---|---|
| `fluent-dev` | Orchestrator — routes to backend or frontend and owns cross-cutting lifecycle work such as planning, explain, status, E2E, and session tracking |
| `fluent-backend-dev` | Workflows, rules, modules, settings, events, deployment |
| `fluent-frontend-dev` | Manifests, SDK components, UI preview, browser UI testing |
| `fluent-cli` | CLI operations — profiles, modules, workflows, retailers |
| `fluent-mcp` | MCP tools — events, GraphQL, batch, metrics, official CLI MCP workflows |
| `fluent-rfl` | Ready For Launch assessments |

Mention "workflow", "rule", "module" for backend agent. Mention "manifest", "page", "component" for frontend agent. Both routes through the orchestrator.

Need the full routing guide? See [Prompt Guide](docs/02-prompt-guide.md) for which skills exist, what to type, agent routing, and lifecycle stages.

---

## Experimental Features

### `/fluent-goal`

`/fluent-goal` is an experimental persistent orchestrator that decomposes a business goal into sub-goals, delegates to existing skills, verifies each step, critiques failures, and keeps going until the goal is achieved or genuinely blocked.

What is validated today:

- Static wiring: registered in `metadata.json`, routed by `fluent-dev`, and protected by a mandatory planning gate
- Content contract: covered by repo skill-quality tests and an explicit `test/fluent-goal.test.mjs` documentation check
- Acceptance scenarios: documented for stuck entity recovery, workflow hotfix + resend, user-action visibility, and webhook/integration recovery

What is **not** yet fully automated in CI:

- A live account loop that mutates workflows/settings/modules, sends real events, retries, and proves end-to-end success against a real Fluent tenant

### Gemini target

Gemini CLI support is experimental and currently works through:

- Gemini custom commands in `~/.gemini/commands` or `.gemini/commands`
- A local installer-managed skill mirror in `~/.gemini/skills` or `.gemini/skills`
- MCP wiring in `~/.gemini/settings.json` or `.gemini/settings.json`

Use `--scope project` where possible. It keeps commands, mirrored skill content, and Gemini settings together inside the workspace, which is the most reliable path for companion files and MCP setup.

---

## CLI Quick Reference

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

| Command | Description |
|---|---|
| `install [groups...]` | Install skills + configure MCP (with `--profile`) |
| `doctor [--fix]` | **Full setup health check** — Node, CLI, Claude Code, skills, MCP, profile, connectivity, versions. `--fix` auto-installs Fluent CLI if missing |
| `status [groups...]` | Check what's installed |
| `uninstall [groups...]` | Remove installed skills (`--purge` also removes global knowledge) |
| `mcp-setup [options]` | Generate `.mcp.json` separately |
| `flow-run [options]` | Pre-deploy diagnostics + optional guarded deploy ([details](docs/06-dev-workflow.md)) |
| `list` | List available skill groups |
| `--version` | Show version |

### Key Options

| Option | Applies to | What it does |
|---|---|---|
| `--install-mcp-extn` | `install` | Pre-install MCP extension locally (faster IDE startup — avoids npx download each time) |
| `--purge` | `uninstall` | Also remove global knowledge fallback (`~/.claude/fluent-knowledge/`) — without this flag, global knowledge is preserved for other workspaces |
| `--target gemini` | `install`, `status`, `uninstall`, `mcp-setup` | Experimental Gemini CLI target using custom commands + Gemini settings |
| `--scope project` | `codex`, `gemini` targets | Keep skills/commands and MCP config inside the workspace instead of the user home directory |
| `--with-chrome` | `mcp-setup` | Add Chrome MCP Extension for manual browser debugging |
| `--save-video` | `mcp-setup` | Enable video recording for UI walkthroughs |
| `--no-browser` | `mcp-setup` | Skip Chrome DevTools setup (backend-only workflows) |

For server-by-server MCP details, auth notes, and optional hosting providers, see [`docs/mcp-servers.md`](docs/mcp-servers.md).

---

## Eval Coverage

803 eval cases across 12 suites validate skill routing, execution quality, and knowledge grounding:

| Suite | Cases | What it tests |
|---|---:|---|
| Execution | 188 | All 63 skills produce correct output (plans, code, tool calls) |
| Routing | 115 | Prompt → skill selection accuracy (deterministic replay) |
| Routing-live | 175 | Live model routing against installed skills |
| Knowledge-grounding | 140 | Trap cases for common misconceptions and anti-patterns |
| Runtime-live | 54 | MCP tool integration (GraphQL, events, settings) |
| Skill-runtime | 51 | Skill execution contracts and output validation |
| Tool-behavior | 30 | Tool call contracts and argument validation |
| Chains | 19 | Multi-skill workflow execution sequences |
| Adversarial | 16 | Ambiguous, out-of-scope, and mixed-concern prompts |
| Agent-routing | 6 | Agent delegation accuracy (deterministic replay) |
| Agent-routing-live | 6 | Live model agent delegation |
| Runtime-live-sandbox | 3 | Sandbox-only profile context verification |

Run the test suites: `npm test` (smoke, pack, unit, and evals:core — replay-based eval cases included).

**Interactive prompt probing:** `npm run eval:playground` opens a browser UI at `http://localhost:3457` where you can type any prompt and see which skill gets picked, which knowledge docs are referenced, and the LLM's reasoning. Supports Claude Agent SDK (fastest — direct API, no subprocess), Claude Code CLI, and Codex executors. The SDK executor uses compact routing prompts (~4K tokens vs ~100K+), cost safety caps, and live SSE progress streaming. Requires `claude` or `codex` CLI to be installed and authenticated; the SDK executor inherits Bedrock SSO auth from environment variables.

---

## Troubleshooting

| Symptom | Fix |
|---|---|
| "Fluent CLI not found" | `npx @fluentcommerce/ai-skills doctor --fix` (auto-installs), or install manually from [docs.fluentcommerce.com](https://docs.fluentcommerce.com/building-blocks/fluent-cli-package) |
| "Profile directory not found" | `fluent profile create MY_PROFILE --id ... --username ... --password ... --client-secret ... --base-url ...` |
| `.mcp.json` not created | `npx @fluentcommerce/ai-skills mcp-setup --profile MY_PROFILE` |
| MCP tools return connection errors | Restart IDE, then `fluent profile retailers MY_PROFILE` to verify connectivity |
| Skills not loading in Claude Code | `npx @fluentcommerce/ai-skills doctor` (full setup health check) |
| "npx not found" | Install Node.js 20+ from [nodejs.org](https://nodejs.org) — npx is bundled with npm 5.2+ |
| 401 Unauthorized on API calls | Password or client-secret may have expired. Re-create profile: `fluent profile create ...` |
| Network error / ENOTFOUND / ETIMEDOUT | Check `--base-url` in your profile is correct. Check VPN if behind a corporate firewall |
| fluent-mcp-extn not reachable | Check npm registry access (VPN may block it). Try: `npm view @fluentcommerce/fluent-mcp-extn version` |
| MCP server startup error on Node 18 | MCP extension requires Node 20+. Upgrade Node.js: `nvm install 20` or download from [nodejs.org](https://nodejs.org) |
| I ran install but nothing seems different | Check: `npx @fluentcommerce/ai-skills --version` first, then `npx @fluentcommerce/ai-skills doctor` |
| Workflow deploy rejected (same version) | Always bump module version before re-deploying |
| Workflow changes not visible after deploy | Three cache layers — see [Workflow Caching & Staleness](docs/workflow-reference.md#workflow-caching--staleness) |
| Manifest setting not loading | Must use `valueType: "JSON"`, `context: "ACCOUNT"`, body in `lobValue` |


More detailed troubleshooting with MCP debugging steps: [Getting Started — Troubleshooting](docs/05-getting-started.md#6-troubleshooting)

---

## Knowledge, Memory & Skills — Three Data Layers

The AI draws from three distinct data layers. Each has a different purpose, owner, and loading strategy:

```
┌──────────────────────────────────────────────────────────────┐
│  KNOWLEDGE (prescriptive) — "How things SHOULD work"         │
│  Owner: humans   Location: knowledge/ + accounts/<PROFILE>/knowledge/ │
│  Loading: always (workspace instruction refs) or on-demand (skill reads) │
├──────────────────────────────────────────────────────────────┤
│  MEMORY (descriptive) — "How things DO work"                 │
│  Owner: AI       Location: accounts/<PROFILE>/memory/        │
│  Loading: session start (index.md) + on-demand (topic files) │
├──────────────────────────────────────────────────────────────┤
│  SKILLS (executable) — "How to DO things"                    │
│  Owner: package  Location: fluent-ai-skills/content/         │
│  Loading: on invocation (/fluent-<name>)                     │
└──────────────────────────────────────────────────────────────┘
```

**When they conflict:** Knowledge wins over memory. Account knowledge (`accounts/<PROFILE>/knowledge/`) wins over generic platform knowledge (`knowledge/`).

### What goes where

| You want to capture... | Layer | File | Example |
|---|---|---|---|
| Team naming convention | **Knowledge** | `accounts/<PROFILE>/knowledge/naming-conventions.md` | "All order refs: `ORD-{storeCode}-{seq}`" |
| Platform entity model | **Knowledge** | `knowledge/platform/domain-model.md` | "ORDER has edges to fulfilments, items, customer" |
| Client routing rules | **Knowledge** | `accounts/<PROFILE>/knowledge/client/business-rules.md` | "Always warehouse-first, store fallback" |
| Deploy gotcha for this account | **Memory** | `accounts/<PROFILE>/memory/learnings.md` | "Store app needs `servicepoint` in workflow user action modules[]" |
| User working preferences | **Memory** | Global `MEMORY.md` | "User prefers concise responses" |

### How to populate

```
/fluent-knowledge-init              # Wizard asks questions, writes knowledge files
"Extract knowledge from this PDF"   # AI reads docs, writes after you confirm
Just work normally                  # AI captures corrections progressively into memory
```

**Rule of thumb:** If you'd put it in a team wiki → knowledge. If you'd tell a colleague "watch out for this" → memory. Skills are the package itself — you don't edit them.

**Full guide with format specs, loading chains, and examples:** [Data Architecture](knowledge/DATA-ARCHITECTURE.md) | [Knowledge Guidelines](knowledge/GUIDELINES.md)

### Workspace Instruction Files

The installer auto-generates starter workspace handbooks when they do not already exist:

- **`CLAUDE.md`** — Claude Code reads this automatically at the start of each session
- **`AGENTS.md`** — Codex and other agentic tooling can use this as the workspace instruction file
- **`GEMINI.md`** — Gemini CLI reads this automatically when present (generated on Gemini installs)

These files point to the same local `knowledge/` directory. They include:

- **Account context** — profile and retailer (pre-filled if you used `--profile`)
- **First steps** — doctor, connect, explore
- **SDLC skill map** — which skills to use at each stage (setup → discover → plan → build → deploy → test → diagnose → audit)
- **Quick actions** — common prompts and slash commands
- **Knowledge & memory** — three-layer data system with account-specific file guide and population instructions
- **Conventions placeholder** — add your team-specific rules here

#### Upgrade behaviour (re-install)

The file has two kinds of sections:

| Section type | Examples | On upgrade |
|---|---|---|
| **Managed** (between `<!-- ai-skills:managed:* -->` markers) | SDLC skill map, routing tripwires, MCP tools, reference docs | **Refreshed automatically** with the latest content from the package |
| **User-owned** (everything outside markers) | Account context, First steps, Conventions, Knowledge & Memory | **Never touched** — yours to customize freely |

On **first install**: the full file is generated with both managed and user-owned sections.

On **re-install / upgrade**: only the four managed sections are replaced in-place. Your customizations outside those markers are preserved exactly as-is.

**Pre-marker files** (generated by versions before managed sections were introduced): the installer cannot find the markers, so it skips the update and prints a warning. Delete the old file and re-run `install` to get a fresh copy with markers.

**What to add:**

```markdown
## Conventions
- Order refs: ORD-{storeCode}-{seq}
- All custom rules use prefix `com.client.`
- Workflow subtypes: HD, CC, SFS (no custom types)
- Always use MCP tools for GraphQL — never hardcode queries
```

**What NOT to put in them:** Don't duplicate what's already in `knowledge/` or skills. These workspace instruction files are for workspace-level overrides and team preferences.

---

## Further Reading

| Document | What's in it |
|---|---|
| [Your First Session](docs/01-first-session.md) | 20 minutes to productive — start here |
| [Prompt Guide](docs/02-prompt-guide.md) | Which skills exist, what to type, agent routing, lifecycle stages |
| [Use Cases](docs/03-use-cases.md) | 21 scenarios with exact prompts and what happens |
| [Docs Index](docs/INDEX.md) | Where to go based on what you need |
| [Getting Started](docs/05-getting-started.md) | Prerequisites, workspace layout, troubleshooting |
| [Onboarding Plan](docs/04-onboarding-plan.md) | Structured two-week plan for teams |
| [Dev Workflow](docs/06-dev-workflow.md) | Full lifecycle protocol, deployment, rollback |
| [Data Architecture](knowledge/DATA-ARCHITECTURE.md) | Three-layer data system: knowledge vs memory vs skills |
| [Knowledge Guidelines](knowledge/GUIDELINES.md) | How to set up, populate, and verify knowledge files |

---

## Companion Packages

| Package | Purpose |
|---|---|
| [`@fluentcommerce/fluent-mcp-extn`](https://www.npmjs.com/package/@fluentcommerce/fluent-mcp-extn) | MCP extension server — 59 tools for live API access (events, batch, metrics, settings, entities, workflows, cache, connections, planning) |
| [Fluent CLI](https://docs.fluentcommerce.com/building-blocks/fluent-cli-package) | Official CLI + built-in MCP server. See [install guide](https://docs.fluentcommerce.com/building-blocks/fluent-cli-package) |
| [`chrome-devtools-mcp`](https://www.npmjs.com/package/chrome-devtools-mcp) | Browser automation — auto-configured for `/fluent-ui-test`, `/fluent-ui-record`, and `/fluent-mystique-preview` |

---

## License

MIT