@fluentcommerce/ai-skills 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fluent Commerce
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,622 @@
+# @fluentcommerce/ai-skills
+
+[![npm version](https://img.shields.io/npm/v/@fluentcommerce/ai-skills.svg)](https://www.npmjs.com/package/@fluentcommerce/ai-skills)
+[![license](https://img.shields.io/npm/l/@fluentcommerce/ai-skills.svg)](https://opensource.org/licenses/MIT)
+[![node](https://img.shields.io/node/v/@fluentcommerce/ai-skills.svg)](https://nodejs.org/)
+
+> **Alpha** — This package is under active development. Skill content, CLI options, and supported targets may change between releases without notice. Use in non-production environments and pin to a specific version if stability matters.
+
+Modular [Fluent Commerce](https://fluentcommerce.com) AI skill packs for coding assistants.
+Install all groups, or only what each project needs.
+
+**What this does:** AI coding assistants (Claude Code, Cursor, Copilot, etc.) are general-purpose — they don't know Fluent Commerce. This package injects Fluent-specific domain knowledge (workflows, events, rules, GraphQL patterns, CLI commands, deployment procedures) into your assistant so it can analyze workflows, scaffold rules, run E2E tests, debug failed events, and manage settings — all through natural language.
+
+**New here?** See [What Can You Do With Fluent AI Skills?](docs/USE_CASES.md) for scenario-based examples — from debugging stuck orders to building new workflows to go-live readiness checks.
+
+**What is a "skill"?** A skill is a structured instruction file that teaches the AI how to perform a specific Fluent task. For example, `/fluent-workflow-analyzer` teaches the AI how to read workflow JSON, map status graphs, detect orphaned rulesets, and generate Mermaid diagrams. Skills are installed into your assistant's native format (Claude agents/skills, Cursor rules, Copilot instructions, etc.).
+
+## What Can You Do?
+
+| Persona | Example prompt | What happens |
+|---------|---------------|-------------|
+| New developer | "Explain how Home Delivery works" | Feature Architecture Document with diagrams, rules, settings |
+| Debugging | "Why is order HD-001 stuck?" | Event forensics, NO_MATCH analysis, remediation options |
+| Building | "Build an ORDER::RETURN workflow" | Plan mode → state machine → rulesets → deploy → E2E test |
+| Pre-go-live | "Run a Ready For Launch assessment" | Scored report across workflows, rules, settings, integrations |
+| Ops | "Show event failure rates for the last hour" | Metrics anomaly detection with threshold alerts |
+
+See [full scenario guide](docs/USE_CASES.md) for 11 detailed walkthroughs.
+
+## Quick Start
+
+```bash
+# Install all skill groups (default target: Claude Code)
+npx @fluentcommerce/ai-skills install
+
+# Configure MCP server entries for your project
+npx @fluentcommerce/ai-skills mcp-setup --profile YOUR_PROFILE
+
+# Verify what's installed
+npx @fluentcommerce/ai-skills status
+```
+
+### Quick Start by Target
+
+Run from your project root:
+
+Primary target is **Claude**. The adapters below are **beta**.
+
+```bash
+# Cursor
+npx @fluentcommerce/ai-skills install --target cursor
+npx @fluentcommerce/ai-skills status --target cursor
+
+# VS Code (Copilot instructions format)
+npx @fluentcommerce/ai-skills install --target vscode
+npx @fluentcommerce/ai-skills status --target vscode
+
+# GitHub Copilot
+npx @fluentcommerce/ai-skills install --target copilot
+npx @fluentcommerce/ai-skills status --target copilot
+
+# Windsurf
+npx @fluentcommerce/ai-skills install --target windsurf
+npx @fluentcommerce/ai-skills status --target windsurf
+
+# Codex
+npx @fluentcommerce/ai-skills install --target codex
+npx @fluentcommerce/ai-skills status --target codex
+
+# Gemini CLI
+npx @fluentcommerce/ai-skills install --target gemini
+npx @fluentcommerce/ai-skills status --target gemini
+```
+
+Tip: to keep instruction size lighter, install only needed groups (for example `npx @fluentcommerce/ai-skills install --target cursor cli mcp-extn`).
+
+## Requirements
+
+- Node.js 18+
+- Fluent CLI (`npm i -g @fluentcommerce/cli`) — needed for official MCP server
+
+## Supported Targets
+
+Skills install into your coding assistant's native format:
+
+| Target | Output location | Scope | Status |
+|---|---|---|---|
+| `claude` (default) | `~/.claude/agents/` + `~/.claude/skills/` | Global (shared across projects) | **Primary** |
+| `cursor` | `.cursor/rules/*.mdc` | Project | Beta |
+| `copilot` | `.github/copilot-instructions.md` | Project | Beta |
+| `vscode` | `.github/copilot-instructions.md` (alias of `copilot`) | Project | Beta |
+| `windsurf` | `.windsurfrules` | Project | Beta |
+| `codex` | `AGENTS.md` | Project | Beta |
+| `gemini` | `GEMINI.md` | Project | Beta |
+
+> Claude Code is the primary target with full support (agents, skills, slash commands, MCP integration). Other targets receive the same domain knowledge as merged instruction content and are tested where possible, but may have limited functionality compared to Claude Code.
+
+```bash
+# Install for a specific target
+npx @fluentcommerce/ai-skills install --target cursor
+
+# Install specific groups only
+npx @fluentcommerce/ai-skills install --target copilot cli mcp-extn
+```
+
+For non-Claude targets, the installer writes a managed block (`<!-- fluent-ai-skills:start --> ... <!-- fluent-ai-skills:end -->`). Uninstall removes only managed content and preserves anything else in the file.
+
+## Available Groups
+
+| Group | What it provides | Claude Code slash commands |
+|---|---|---|
+| `cli` | Fluent CLI command-family coverage (index routing, reference, account connect, profile, retailer, settings, modules, workflows, MCP/CI-CD, bootstrap) | `/fluent-cli-index` `/fluent-cli-reference` `/fluent-connect` `/fluent-cli-mcp-cicd` `/fluent-bootstrap` `/fluent-cli-retailer` `/fluent-cli-settings` `/fluent-module-deploy` `/fluent-profile` `/fluent-workflow` |
+| `mcp-official` | Official Fluent CLI MCP server operations | `/fluent-mcp-core` |
+| `mcp-extn` | Extension MCP tools (events, transitions, GraphQL, metrics, batch) | `/fluent-mcp-tools` |
+| `rfl` | Ready For Launch assessments | `/fluent-rfl-assess` |
+| `dev` | Feature planning (with universal NEW/EXISTING/MODIFIED/REUSED/OOTB classification), workflow builder, workflow deploy, analyzer, connection analysis (with `--validate` static-vs-dynamic comparison and cross-entity event tracing), custom code analysis, transition API, rule scaffold, module scaffold, data module scaffold, source onboarding, module validation, build, version management, trace, event API (model + causality analysis), system monitoring, batch ingestion, E2E, test data, settings (with Phase 2B value format validation and cascading scope resolution), environment setup, pre-deploy checks, session summary, session audit export, scope decomposition, feature explanation, Mermaid diagram validation | `/fluent-feature-plan` `/fluent-workflow-builder` `/fluent-workflow-deploy` `/fluent-workflow-analyzer` `/fluent-connection-analysis` `/fluent-custom-code` `/fluent-transition-api` `/fluent-rule-scaffold` `/fluent-module-scaffold` `/fluent-data-module-scaffold` `/fluent-source-onboard` `/fluent-module-validate` `/fluent-build` `/fluent-version-manage` `/fluent-trace` `/fluent-event-api` `/fluent-system-monitoring` `/fluent-job-batch` `/fluent-e2e-test` `/fluent-test-data` `/fluent-settings` `/fluent-retailer-config` `/fluent-session-summary` `/fluent-scope-decompose` `/fluent-pre-deploy-check` `/fluent-session-audit-export` `/fluent-feature-explain` |
+
+> Slash commands are Claude Code specific. Other targets receive the same knowledge as merged instruction content.
+
+For detailed command-family and guide-section coverage status (`full/partial/missing`), see [docs/CLI_COVERAGE.md](docs/CLI_COVERAGE.md).
+
+### Group Aliases
+
+| Alias | Resolves to |
+|---|---|
+| `mcp` | `mcp-extn` |
+| `extn` | `mcp-extn` |
+| `extension` | `mcp-extn` |
+| `mcp-core` | `mcp-official` |
+| `official` | `mcp-official` |
+
+## Autonomous Development Workflow
+
+The `dev` skill group enables AI agents to run a full closed-loop development lifecycle with a mandatory planning gate:
+
+```
+ANALYZE → EXPLAIN (if requested) or PLAN → [USER APPROVAL] → IMPLEMENT → BUILD → DEPLOY → TEST → DIAGNOSE → FIX → (loop back)
+```
+
+After analysis, the agent presents a structured implementation plan (workflow changes, settings, rules, Mermaid diagrams, risk assessment, test plan) and waits for explicit user approval before making changes. The agent then continues iterating until all E2E tests pass or an unresolvable blocker is hit.
+
+Event API source docs are curated into skills via selective extraction; they are not mirrored wholesale.
+
+| Phase | Skill / Command | What the agent does |
+|-------|----------------|---------------------|
+| Analyze | `/fluent-workflow-analyzer`, `/fluent-connection-analysis` | Map status graphs, trace event chains, detect orphans, verify connectivity; `--validate` mode compares static workflow paths with runtime events, traces cross-entity propagation, and produces timing analysis |
+| Custom code analysis | `/fluent-custom-code` | Scan custom source, generate reusable analysis artifacts (source-map, workflow-rule-map, constraints, behavior-map, extension-plan) |
+| Discover | `/fluent-transition-api` | Query available user actions at each status, map required attributes |
+| Scope decomposition | `/fluent-scope-decompose` | Parse scope documents into ordered task lists with dependency DAG, skill mappings, and ambiguity detection |
+| Feature plan | `/fluent-feature-plan` | Produce comprehensive implementation plan with universal source classification (NEW/EXISTING/MODIFIED/REUSED/OOTB) across all artifacts — rules, workflows, settings, webhooks, cross-entity flows, deployment sequence |
+| Plan & Approve | *(check gate)* | Present structured implementation plan (workflows, settings, rules, Mermaid diagrams, risks, test plan). **Wait for user approval.** |
+| Implement | `/fluent-workflow-builder`, `/fluent-rule-scaffold` | Edit workflow JSON, scaffold Java rules, update settings |
+| Scaffold module | `/fluent-module-scaffold` | Generate complete Maven module skeleton (POMs, module.json, rule classes, build scripts) |
+| Onboard source | `/fluent-source-onboard` | Restructure existing Java source (loose files, decompiled JARs, non-standard layouts) into proper Fluent module format; validate and build |
+| Validate | `/fluent-module-validate` | Check module structure, version consistency, rule wiring, test coverage; cached report with content hash |
+| Version | `/fluent-version-manage` | Read, bump, sync, and tag versions across POM files, module.json, and CHANGELOG |
+| Build | `/fluent-build` | Version bump, Maven compile, ZIP packaging |
+| Pre-deploy | `/fluent-pre-deploy-check` | 26 quality gates across 8 phases (env, module, workflow, connections, settings, target, risk, completeness) |
+| Deploy module | `/fluent-module-deploy` or `flow-run` | Module install via CLI |
+| Deploy workflow | `/fluent-workflow-deploy` | Workflow upload via MCP tool, REST API fallback, CLI last resort |
+| Test | `/fluent-e2e-test` | Create entities, fire events, poll states, assert transitions |
+| Test data | `/fluent-test-data` | Discover retailer environment and generate valid test entity payloads |
+| Settings | `/fluent-settings` | Manage retailer settings — discover, audit (with Phase 2B value format validation), create/update, migrate; cascading scope resolution (RETAILER -> ACCOUNT) for module-installed settings |
+| Environment | `/fluent-retailer-config` | Configure retailer environments — locations, networks, catalogues, inventory, carriers |
+| Diagnose | `/fluent-trace`, `/fluent-event-api` | Trace failed events, correlate with rulesets, and build causality chains across parent/child events |
+| Fix | (routes back to Implement/Build/Deploy) | Apply fix based on diagnosis, re-test |
+| Explain | `/fluent-feature-explain` | Reverse-engineer existing feature into a Feature Architecture Document with Mermaid diagrams, data flow, and runtime evidence; tiered analysis (plugin.list → decompiled JAR / source code → runtime), auto-discovers entities, JAR decompilation fallback, Analysis Confidence section; saved to `accounts/<PROFILE>/analysis/features/` |
+| Audit | `/fluent-session-summary`, `/fluent-session-audit-export` | Track all changes made during session; export machine-readable JSON audit trail |
+
+Artifacts from custom code analysis are written to `accounts/<PROFILE>/analysis/custom-code/` and reused by other skills (workflow-analyzer, trace, rule-scaffold, etc.). A `fingerprint.json` file is used to detect input changes and skip re-parsing when nothing changed. Module validation reports are written to `accounts/<PROFILE>/analysis/module-validate/` with a content hash — re-validation is skipped when the module source is unchanged.
+
+Account workspace convention — see [Workspace Setup](#workspace-setup) for the full guide.
+
+### Settings Update Quick Recipe
+
+For safe setting updates, use this exact flow with `/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).
+
+See [docs/DEV_WORKFLOW.md](docs/DEV_WORKFLOW.md) for the complete orchestration protocol with decision trees, tool chains, and error recovery patterns.
+
+### Deep Analysis Fallback (Vague Ruleset/Rule Intent)
+
+When workflow/ruleset descriptions are too generic to explain behavior confidently, the skills escalate evidence in this order:
+
+1. Ask focused clarification questions (trigger, expected state, actual outcome).
+2. Request source (`module.json` + Java rule classes).
+3. If source is unavailable, first check for JAR/ZIP already present under `accounts/<PROFILE>/SOURCE/`, then decompile targeted rule classes.
+4. Correlate decompiled logic with workflow props and runtime event/log evidence.
+
+This keeps end-to-end analysis grounded in executable rule logic rather than names/descriptions only.
+
+## Workspace Setup
+
+Skills expect implementation source code, workflows, and analysis artifacts to be organized under an `accounts/` directory in your workspace root, keyed by Fluent CLI profile name.
+
+### Directory Structure
+
+```
+accounts/
+  <PROFILE>/                           # matches your FLUENT_PROFILE name
+    SOURCE/                            # account-level, shared across retailers
+      <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
+    workflows/                         # retailer-scoped workflow definitions
+      <RETAILER_REF>/
+        ORDER__HD.json
+        FULFILMENT__HD_WH.json
+        workflow-context.json          # download metadata
+    analysis/                          # generated analysis artifacts
+      custom-code/source-map.json
+      module-validate/*.report.json
+    plans/                             # persisted implementation plans (audit trail)
+      2026-02-23-rule-scaffold-curbside-pickup.md
+      2026-02-23-workflow-builder-order-hd-returns.md
+    workspace-state.json               # cached state for idempotent re-runs
+  workspace-index.json                 # cross-profile index
+```
+
+**Why this layout:**
+- `SOURCE/` is at the profile (account) level because plugin code is deployed per-account and shared across retailers.
+- `workflows/` are scoped by retailer ref inside subdirectories because workflow definitions can differ per retailer.
+- `analysis/` holds generated artifacts that other skills reuse (source maps, module validation reports, etc.).
+- `plans/` stores implementation plans created by the Planning Gate. Each plan is a markdown file with status tracking (`PENDING` → `APPROVED`/`REJECTED`), Mermaid diagrams, file lists, environment impact, tasks, risks, and test plans. Plans persist across sessions for audit trail and re-use.
+
+### Guided Onboarding (`/fluent-connect`)
+
+The fastest way to set up a workspace is the guided connect wizard. In Claude Code:
+
+```
+/fluent-connect
+```
+
+Or with explicit arguments to skip interactive selection:
+
+```
+/fluent-connect --profile MYPROFILE --retailer MY_RETAILER
+```
+
+The wizard runs through 5 phases:
+
+1. **Profile Discovery** — scans `~/.fluentcommerce/` for CLI profiles, presents a table with account name and environment tier
+2. **Retailer Selection** — reads retailer files for the selected profile, asks which retailer to target
+3. **MCP Wiring** — runs `mcp-setup`, verifies `.mcp.json`, prompts IDE reload, validates connectivity
+4. **Workspace Readiness** — creates directories, downloads workflows, scans source repos, decompiles JARs if needed, builds a deployed rule inventory by cross-referencing `plugin.list` with local source
+5. **Persist & Report** — writes `workspace-state.json` (with content hash for caching), updates `workspace-index.json`, prints a readiness report with next-step suggestions
+
+Re-running `/fluent-connect` is safe and instant if nothing changed (content hash match). Use `--force` to re-run full discovery.
+
+### Adding Source Code
+
+Clone your custom plugin repositories into `accounts/<PROFILE>/SOURCE/`:
+
+```bash
+cd accounts/MYPROFILE/SOURCE
+git clone https://bitbucket.org/yourorg/fc-module-extensions.git
+git clone https://bitbucket.org/yourorg/fc-module-returns.git
+```
+
+Each repo should contain at minimum:
+- `resources/module.json` — module metadata and rule registrations
+- `pom.xml` — Maven build configuration
+- `src/main/java/` — Java rule classes
+
+Skills automatically detect repos by searching recursively for `module.json`, `pom.xml`, or `src/main/java/`. Nested directory structures (including double-nested git clone artifacts like `repo/repo/`) are handled.
+
+### Adding JAR Files
+
+When original source code is not available, place compiled module JARs directly in `SOURCE/`:
+
+```bash
+cp fc-module-extensions-1.2.3.jar accounts/MYPROFILE/SOURCE/
+```
+
+Skills will:
+1. Auto-detect JAR files during workspace setup
+2. Decompile them (using CFR or Fernflower if available) into `SOURCE/.decompiled/<jar-basename>/`
+3. Extract `module.json` from the JAR if present
+4. Create a `DECOMPILED.md` marker noting the source JAR, date, and confidence level
+
+**Decompiled source is read-only.** Skills can analyze it for rule discovery, behavior explanation, and workflow-rule mapping, but will never suggest editing decompiled files. To modify code, provide original source or scaffold a new module.
+
+### Reference Modules
+
+Reference (OOTB) modules that ship as a `module.json` + JAR package can also be placed in `SOURCE/`:
+
+```bash
+cp -r fluent-module-order/ accounts/MYPROFILE/SOURCE/
+# Contains: module.json + assets/rules/*.jar
+```
+
+Skills read rule names, descriptions, and version directly from `module.json` — no decompilation needed for metadata. Decompilation is only triggered if deep analysis of rule implementation logic is requested.
+
+### Adding a New Account
+
+```bash
+# Create the directory structure
+mkdir -p accounts/NEW_PROFILE/SOURCE
+mkdir -p accounts/NEW_PROFILE/workflows
+mkdir -p accounts/NEW_PROFILE/analysis
+
+# Clone plugin repos
+cd accounts/NEW_PROFILE/SOURCE
+git clone <repo-url>
+
+# Download workflows (after setting up profile)
+fluent workflow download -p NEW_PROFILE -r RETAILER_REF -w all \
+  -o accounts/NEW_PROFILE/workflows/RETAILER_REF/
+```
+
+Or let `/fluent-connect` do all of this interactively.
+
+### How Analysis Works
+
+Once the workspace is populated, skills build a holistic view of what's deployed:
+
+1. **Live environment** — `plugin.list` queries all registered orchestration rules
+2. **Local source** — repos with full Java source (modifiable, buildable)
+3. **Local JARs** — decompiled bytecode (analyzable, read-only)
+4. **Workflow definitions** — downloaded JSON files
+
+Cross-referencing these produces a **deployed rule inventory**:
+
+| Status | Meaning | What you can do |
+|--------|---------|-----------------|
+| Full source | Rule class found in a git repo | Analyze, modify, build, redeploy |
+| Decompiled | Rule class found in decompiled JAR | Analyze behavior, cannot modify |
+| Missing | Deployed rule with no local source or JAR | Blind spot — provide source or JAR |
+
+This inventory is persisted in `workspace-state.json` and powers downstream skills like `/fluent-custom-code`, `/fluent-workflow-analyzer`, and `/fluent-rfl-assess`.
+
+### .gitignore
+
+The `accounts/` directory should be in `.gitignore` — it may contain credentials (via profile references), downloaded workflows, and customer-specific source code:
+
+```gitignore
+accounts/
+```
+
+## Setup Guide
+
+### Option A — Fastest (no source clone)
+
+```bash
+npx @fluentcommerce/ai-skills install
+npx @fluentcommerce/ai-skills mcp-setup --profile YOUR_PROFILE
+
+# Multi-retailer profile (retailer ref for extension server)
+npx @fluentcommerce/ai-skills mcp-setup --profile YOUR_PROFILE --profile-retailer YOUR_RETAILER_REF
+```
+
+When `--profile` is provided, both MCP servers are wired with `FLUENT_PROFILE` automatically.
+You can run immediately with profile auth, or override with explicit OAuth/token env vars.
+
+For explicit env auth in `.mcp.json`, fill:
+
+- `FLUENT_BASE_URL` — your tenant API URL
+- `FLUENT_RETAILER_ID` — target retailer ID
+- `FLUENT_CLIENT_ID` / `FLUENT_CLIENT_SECRET` — OAuth credentials
+- `FLUENT_USERNAME` / `FLUENT_PASSWORD` — user credentials (if using password grant)
+- `FLUENT_PROFILE_RETAILER` — optional retailer ref for profile-scoped user overrides
+
+Restart your IDE after editing `.mcp.json`.
+
+### Option B — Extension source clone + local build
+
+```bash
+npx @fluentcommerce/ai-skills mcp-setup --install-extn-source --profile YOUR_PROFILE
+```
+
+This clones the `fluent-mcp-extn` source into your project, builds it, and wires `.mcp.json` to the local build. Use this if you want to debug or customize the extension server.
+
+### Option C — Install from tarball
+
+```bash
+# Create tarball
+cd fluent-ai-skills && npm pack
+
+# Install from tarball on any machine
+npx ./fluentcommerce-ai-skills-0.0.1.tgz install
+```
+
+## End-to-End Validation (Recommended)
+
+Validate the full setup path (skills bootstrap -> MCP config -> extension runtime smoke):
+
+```bash
+# 1) Install skills + generate MCP config
+npx @fluentcommerce/ai-skills install
+npx @fluentcommerce/ai-skills mcp-setup --profile YOUR_PROFILE --profile-retailer YOUR_RETAILER_REF
+
+# 2) Verify generated env in .mcp.json (extension server)
+#    FLUENT_PROFILE=YOUR_PROFILE
+#    FLUENT_PROFILE_RETAILER=YOUR_RETAILER_REF
+
+# 3) Run extension end-to-end smoke
+cd fluent-mcp-extn
+npm install
+npm run build
+npm test
+npm run e2e:smoke -- --wizard
+npm run e2e:smoke -- --profile YOUR_PROFILE
+npm run e2e:smoke -- --profile YOUR_PROFILE --retailer YOUR_RETAILER_REF_OR_ID
+
+# 4) Optional: run one smoke cycle per profile retailer
+npm run e2e:smoke -- --profile YOUR_PROFILE --all-retailers
+```
+
+This verifies both MCP servers are configured and that `fluent-mcp-extn` can execute real API smoke checks in profile mode.
+
+Notes:
+- `--wizard` is for interactive local runs (guided profile/account + retailer selection).
+- `--retailer` accepts retailer ID or retailer ref.
+- CI/non-interactive runs should use explicit flags (`--profile <name> --retailer <id|ref>` or `--profile <name> --all-retailers`).
+- `flow-run` is diagnostics + optional guarded deploy; use `fluent-mcp-extn` smoke for runtime E2E checks.
+
+## CLI Reference
+
+```
+npx @fluentcommerce/ai-skills <command> [--target <target>] [groups...]
+```
+
+| Command | Description |
+|---|---|
+| `install [groups...]` | Install all groups (default) or selected groups |
+| `uninstall [groups...]` | Uninstall all groups or selected groups |
+| `status [groups...]` | Show install status |
+| `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 |
+
+### `mcp-setup` Options
+
+```bash
+# Basic — generates .mcp.json with both servers
+npx @fluentcommerce/ai-skills mcp-setup --profile YOUR_PROFILE
+
+# Profile + retailer ref (for fluent-mcp-extn profile-scoped user overrides)
+npx @fluentcommerce/ai-skills mcp-setup --profile YOUR_PROFILE --profile-retailer YOUR_RETAILER_REF
+
+# Clone and build extension source locally
+npx @fluentcommerce/ai-skills mcp-setup --install-extn-source --profile YOUR_PROFILE
+
+# Custom source location and repo
+npx @fluentcommerce/ai-skills mcp-setup \
+  --install-extn-source \
+  --extn-dir tools/fluent-mcp-extn \
+  --extn-repo https://bitbucket.org/fluentcommerce/fluent-mcp-extn.git
+
+# Custom server names
+npx @fluentcommerce/ai-skills mcp-setup \
+  --official-server-name fluent-mcp \
+  --extn-server-name fluent-mcp-extn
+```
+
+`--profile-retailer` expects a retailer **ref** (for example `RETAILER_REF`), not retailer ID.
+
+### `flow-run` Options
+
+`flow-run` runs pre-deploy diagnostics and optionally deploys a module:
+
+```bash
+# Diagnostics only (no deploy)
+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
+```
+
+Steps executed: config checks, CLI preflight, module/workflow listing, optional deploy, JSON report.
+
+Report output: `./.fluent-ai-skills/flow-run-report-<timestamp>.json`
+
+## Usage Examples
+
+### Claude Code — full install + MCP
+
+```bash
+npx @fluentcommerce/ai-skills install
+npx @fluentcommerce/ai-skills mcp-setup --profile YOUR_PROFILE
+npx @fluentcommerce/ai-skills status
+```
+
+### Cursor — operations focused
+
+```bash
+cd your-project
+npx @fluentcommerce/ai-skills install --target cursor cli mcp-extn
+npx @fluentcommerce/ai-skills status --target cursor
+```
+
+### GitHub Copilot — shared repo instructions
+
+```bash
+cd your-project
+npx @fluentcommerce/ai-skills install --target copilot cli rfl
+```
+
+### Uninstall
+
+```bash
+# Uninstall all groups from default target
+npx @fluentcommerce/ai-skills uninstall
+
+# Uninstall specific groups from specific target
+npx @fluentcommerce/ai-skills uninstall --target windsurf cli
+```
+
+## Size Guidance
+
+Single-file targets (`copilot`, `vscode`, `windsurf`, `codex`, `gemini`) concatenate all content into one file. If prompt size becomes a concern, install only the groups you need:
+
+```bash
+npx @fluentcommerce/ai-skills install --target codex cli mcp-extn
+```
+
+## Advanced
+
+### Override install location
+
+For Claude target, override the default `~/.claude/` location:
+
+```bash
+FLUENT_AI_SKILLS_HOME=/custom/path npx @fluentcommerce/ai-skills install
+```
+
+```powershell
+# PowerShell
+$env:FLUENT_AI_SKILLS_HOME = "C:\custom\path"; npx @fluentcommerce/ai-skills install
+```
+
+```cmd
+# Windows CMD
+set FLUENT_AI_SKILLS_HOME=C:\custom\path && npx @fluentcommerce/ai-skills install
+```
+
+### MCP config locations by client
+
+| Client | Where to put `.mcp.json` |
+|---|---|
+| Claude Code | Workspace root `.mcp.json` |
+| Cursor | Workspace root `.mcp.json` or `.cursor/mcp.json` |
+| VS Code Copilot | `.vscode/mcp.json` |
+| Windsurf | Workspace/app MCP settings |
+
+## Diagrams
+
+### Install Flow
+
+```mermaid
+flowchart TD
+    A["npx @fluentcommerce/ai-skills install"] --> B{"--target"}
+    B -->|"claude (default)"| C["~/.claude/agents + ~/.claude/skills"]
+    B -->|"cursor"| D[".cursor/rules/*.mdc"]
+    B -->|"copilot"| E[".github/copilot-instructions.md"]
+    B -->|"vscode"| F[".github/copilot-instructions.md"]
+    B -->|"windsurf"| G[".windsurfrules"]
+    B -->|"codex"| H["AGENTS.md"]
+    B -->|"gemini"| I["GEMINI.md"]
+    A --> J{"groups specified?"}
+    J -->|"no"| K["install all groups"]
+    J -->|"yes"| L["install selected groups only"]
+```
+
+### flow-run Execution
+
+```mermaid
+flowchart LR
+    subgraph Local
+      A["Check .mcp.json"]
+      B["Scan config placeholders"]
+    end
+    subgraph CLI
+      C["fluent --version"]
+      D["fluent profile active"]
+      E["fluent module describe/list"]
+      F["fluent workflow list"]
+    end
+    subgraph Deploy
+      G{"--deploy --yes?"}
+      H["fluent module install"]
+      I["post-deploy verify"]
+    end
+    A --> B --> C --> D --> E --> F --> G
+    G -->|"yes"| H --> I
+    G -->|"no"| J["write diagnostics report only"]
+```
+
+## Companion Packages
+
+| Package | Purpose |
+|---|---|
+| [`@fluentcommerce/fluent-mcp-extn`](https://www.npmjs.com/package/@fluentcommerce/fluent-mcp-extn) | MCP extension server (events, transitions, GraphQL, metrics, batch, webhooks) |
+| Fluent CLI (`@fluentcommerce/cli`) | Official CLI and built-in MCP server |
+
+## License
+
+MIT