@fluentcommerce/ai-skills 0.8.2 → 0.8.3

package/README.md

@@ -23,8 +23,9 @@ Teach your AI assistant to work with [Fluent Commerce](https://fluentcommerce.co
 ## Quick Start (copy-paste)
 
 ```bash
-# 1. Install Fluent CLI + Claude Code (skip if already installed)
-npm install -g @fluentcommerce/cli @anthropic-ai/claude-code
+# 1. Install prerequisites (skip if already installed)
+# Fluent CLI: https://docs.fluentcommerce.com/building-blocks/fluent-cli-package
+npm install -g @anthropic-ai/claude-code
 
 # 2. Create a Fluent CLI profile (get values from your Fluent account team)
 fluent profile create MY_PROFILE \
@@ -178,7 +179,7 @@ See all 27 scenarios with exact prompts: [docs/use-cases.md](docs/use-cases.md)
 | Requirement | How to install | Verify |
 |---|---|---|
 | **Node.js 20+** | [nodejs.org](https://nodejs.org) | `node --version` |
-| **Fluent CLI 2.0+** | `npm install -g @fluentcommerce/cli` | `fluent --version` |
+| **Fluent CLI 2.0+** | [Install guide](https://docs.fluentcommerce.com/building-blocks/fluent-cli-package) | `fluent --version` |
 | **Claude Code** | `npm install -g @anthropic-ai/claude-code` | `claude --version` |
 | **A Fluent Commerce account** | Contact your Fluent account team | You'll need the 5 values below |
 
@@ -274,19 +275,37 @@ my-fluent-workspace/
 | **Local** (`.agents/skills`) | Fluent Codex skills for this workspace only (`--target codex --scope project`) | 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 |
-| **Optional local** (this folder) | `CLAUDE.md` — repo/workspace instructions you maintain | No — one per workspace |
+| **Local** (this folder) | `CLAUDE.md` — starter workspace instructions (auto-generated, safe to edit; [details](#claudemd-workspace-instructions)) | 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
 
+**Run `doctor` — it checks everything in one shot:**
+
+```bash
+npx @fluentcommerce/ai-skills doctor
+```
+
+`doctor` validates: Node.js version, Fluent CLI installed, Claude Code installed, skills installed, `.mcp.json` present with correct server config, `knowledge/` docs present, Fluent CLI profile exists and can authenticate, and MCP extension reachable. Fix anything it flags before proceeding.
+
+**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 --profile-retailer "My Retailer"`.
 
+**If you need to wire MCP separately** (e.g., changed profile, new workspace, or skipped `--profile` during install):
+
+```bash
+npx @fluentcommerce/ai-skills mcp-setup --profile MY_PROFILE
+```
+
+This generates `.mcp.json` in the current folder pointing to your Fluent account. Without it, the AI has no live API access.
+
 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
@@ -316,48 +335,54 @@ This creates the full `accounts/` directory tree, downloads all workflows from y
 
 #### 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                         <- MCP server config (auto-generated, gitignored)
-+-- knowledge/                        <- Platform knowledge docs (domain model, SDK, patterns) — copied on install
++-- .mcp.json                   [auto] MCP server config (generated by install/mcp-setup)
++-- CLAUDE.md                   [auto] Starter workspace instructions (auto-generated, safe to edit)
++-- knowledge/                  [auto] Platform knowledge docs — copied from package on install
+|                                      (domain model, SDK patterns, rule contracts, order patterns)
 +-- accounts/
-    +-- MY_PROFILE/
+    +-- MY_PROFILE/             [auto] Created by /fluent-connect or install --profile
         |
-        +-- SOURCE/                   <- All implementation source code
-        |   +-- backend/              <- Java plugins: source repos, reference JARs, decompiled
-        |   |   +-- fc-plugin-custom/
+        +-- 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-generated from JAR decompilation
+        |   |   +-- .decompiled/ [auto] Auto-generated from deployed JARs by /fluent-connect
         |   |
-        |   +-- frontend/             <- Mystique SDK component projects
-        |       +-- mystique-appeasement/
+        |   +-- frontend/        [you] Clone or copy your Mystique SDK component projects here
+        |       +-- mystique-appeasement/  <- your repo
         |           +-- package.json
         |           +-- src/index.tsx
         |
-        +-- knowledge/                <- Account-specific conventions and client knowledge
+        +-- knowledge/           [you] Account-specific conventions (via /fluent-knowledge-init)
         |   +-- naming-conventions.md
         |   +-- coding-standards.md
         |   +-- client/
         |
-        +-- workflows/
-        |   +-- My Retailer/          <- Downloaded workflow JSONs (one per workflow)
-        |       +-- ORDER__HD.json
+        +-- workflows/          [auto] Downloaded from Fluent by /fluent-connect
+        |   +-- My Retailer/
+        |       +-- ORDER__HD.json       <- live workflow JSON from your account
         |       +-- workflow-context.json
         |
-        +-- features/                 <- One subdir per feature
+        +-- features/             [ai] Created by AI during feature development
         |   +-- return-order/
-        |       +-- spec.md           <- Business requirements
-        |       +-- plan.md           <- Implementation plan
-        |       +-- architecture.md   <- Reverse-engineered doc
-        |       +-- status.json       <- Lifecycle tracker
-        |       +-- assets/           <- Screenshots, recordings, evidence
+        |       +-- 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
         |
-        +-- reports/                  <- Ephemeral: build/, pre-deploy/, e2e-test/
-        +-- analysis/                 <- Persistent: code/, modules/, topology/
-        +-- tasks/                    <- Operational plans (non-feature work)
-        +-- sessions/                 <- Audit trail exports
+        +-- 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
@@ -539,7 +564,7 @@ For server-by-server MCP details, auth notes, and optional hosting providers, se
 
 | Symptom | Fix |
 |---|---|
-| "Fluent CLI not found" | `npm install -g @fluentcommerce/cli` then `fluent --version` |
+| "Fluent CLI not found" | Install from [docs.fluentcommerce.com](https://docs.fluentcommerce.com/building-blocks/fluent-cli-package) then `fluent --version` |
 | "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 |
@@ -596,6 +621,31 @@ Just work normally                  # AI captures corrections progressively into
 
 **Full guide with format specs, loading chains, and examples:** [Data Architecture](content/knowledge/DATA-ARCHITECTURE.md) | [Knowledge Guidelines](content/knowledge/GUIDELINES.md)
 
+### CLAUDE.md — Workspace Instructions
+
+The installer auto-generates a starter `CLAUDE.md` in your workspace root. Claude Code reads it automatically at the start of every session. It includes:
+
+- **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 pointers** — where platform and account-specific knowledge lives
+- **Conventions placeholder** — add your team-specific rules here
+
+**The installer never overwrites an existing CLAUDE.md** — so once generated, it's yours to customize.
+
+**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 it:** Don't duplicate what's already in `knowledge/` or skills. CLAUDE.md is for workspace-level overrides and team preferences.
+
 ---
 
 ## Further Reading
@@ -621,7 +671,7 @@ Just work normally                  # AI captures corrections progressively into
 | Package | Purpose |
 |---|---|
 | [`@fluentcommerce/fluent-mcp-extn`](https://www.npmjs.com/package/@fluentcommerce/fluent-mcp-extn) | MCP extension server — 45 tools for live API access (events, batch, metrics, settings, entities, workflows, cache) |
-| Fluent CLI (`@fluentcommerce/cli`) | Official CLI + built-in MCP server. `npm i -g @fluentcommerce/cli` |
+| [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` |
 
 ---

package/bin/cli.mjs

@@ -10,7 +10,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { spawnSync } from "node:child_process";
-import { join, dirname, basename, isAbsolute } from "node:path";
+import { join, dirname, basename, isAbsolute, resolve } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 
@@ -975,6 +975,106 @@ function installKnowledge() {
   return count;
 }
 
+/**
+ * Generate a starter CLAUDE.md in the workspace if one doesn't exist.
+ * Never overwrites — user's CLAUDE.md is always preserved.
+ */
+function generateStarterClaudeMd(profile, retailer) {
+  const dest = join(getProjectRoot(), "CLAUDE.md");
+  if (existsSync(dest)) return false; // never overwrite user's file
+
+  const profileLine = profile ? `- Profile: \`${profile}\`` : "- Profile: `YOUR_PROFILE` (update after creating a profile)";
+  const retailerLine = retailer ? `- Retailer: \`${retailer}\`` : "- Retailer: `YOUR_RETAILER` (update after selecting a retailer)";
+  const profileRef = profile || "MY_PROFILE";
+  const retailerRef = retailer || "My Retailer";
+
+  const content = `# CLAUDE.md — Fluent Commerce AI Skills Workspace
+
+> Auto-generated by \`@fluentcommerce/ai-skills install\`. Safe to edit — the installer never overwrites this file.
+
+## Account
+
+${profileLine}
+${retailerLine}
+
+## First Steps
+
+1. **Verify setup:** run \`npx @fluentcommerce/ai-skills doctor\` in terminal — checks skills, MCP, knowledge, profiles
+2. **Connect to account:** type \`/fluent-connect\` as your first prompt — downloads workflows, scans source, wires workspace
+3. **Explore:** ask \`What can you do?\` or \`Show me the SDLC skill map\`
+
+## Reference Docs
+
+When the user asks about capabilities, available skills, "what can you do", or needs help choosing a skill:
+- Read \`knowledge/index.md\` for the knowledge file registry
+- The SDLC skill map below covers all 64 skills organized by lifecycle stage
+- For scenario-based examples with exact prompts and outcomes, see:
+  https://bitbucket.org/fluentcommerce/fluent-ai-skills/src/main/docs/use-cases.md
+- For agent routing and skill invocation guide:
+  https://bitbucket.org/fluentcommerce/fluent-ai-skills/src/main/docs/agents-and-skills-guide.md
+- All docs: https://bitbucket.org/fluentcommerce/fluent-ai-skills/src/main/docs/index.md
+
+## MCP Tools
+
+Configured in \`.mcp.json\` — use MCP tools for ALL live API operations:
+- **fluent-mcp** — Official Fluent CLI MCP (workflows, profiles, modules)
+- **fluent-mcp-extn** — Extension MCP with 45+ tools (GraphQL, events, batch, metrics, settings, entities)
+- **chrome-devtools** — Browser automation for UI testing and preview
+
+Run \`/fluent-mcp-tools\` for the full tool reference.
+
+## SDLC Skill Map
+
+Follow this lifecycle. Each stage has purpose-built skills:
+
+| Stage | Skills | When |
+|---|---|---|
+| **Setup** | \`/fluent-connect\`, \`/fluent-bootstrap\`, \`/fluent-profile\` | First-time workspace setup, account onboarding |
+| **Discover** | \`/fluent-implementation-map\`, \`/fluent-feature-explain\`, \`/fluent-workflow-analyzer\`, \`/fluent-mystique-analyze\` | Understand what exists before changing anything |
+| **Requirements** | \`/fluent-use-case-discover\` | Turn business needs into an approved spec |
+| **Plan** | \`/fluent-feature-phase\`, \`/fluent-feature-plan\` | Break specs into phases, produce implementation contract |
+| **Build (backend)** | \`/fluent-workflow-builder\`, \`/fluent-rule-scaffold\`, \`/fluent-module-scaffold\`, \`/fluent-settings\` | Workflows, rules, modules, settings |
+| **Build (frontend)** | \`/fluent-mystique-builder\`, \`/fluent-mystique-scaffold\`, \`/fluent-mystique-component\` | Manifests, SDK components, pages |
+| **Validate** | \`/fluent-pre-deploy-check\`, \`/fluent-module-validate\`, \`/fluent-mystique-validate\`, \`/fluent-build\` | Quality gates before deploy |
+| **Deploy** | \`/fluent-module-deploy\`, \`/fluent-workflow-deploy\` | Push changes to environment |
+| **Test** | \`/fluent-test-data\`, \`/fluent-e2e-test\`, \`/fluent-ui-test\`, \`/fluent-transition-api\` | Create test data, run E2E, verify UI |
+| **Diagnose** | \`/fluent-trace\`, \`/fluent-system-monitoring\`, \`/fluent-connection-analysis\`, \`/fluent-rollback\` | Debug failures, monitor health, roll back |
+| **Audit** | \`/fluent-rfl-assess\`, \`/fluent-session\`, \`/fluent-feature-status\` | Go-live readiness, audit trail, status dashboard |
+
+## Quick Actions
+
+| What you want | Say this |
+|---|---|
+| Connect to account | \`/fluent-connect --profile ${profileRef}\` |
+| What's deployed? | \`Map the implementation\` |
+| Build a feature | \`Help me define use cases for ...\` → \`Plan it\` → \`Build it\` |
+| Debug stuck order | \`Why is order HD-001 stuck?\` |
+| Create test data | \`Create a test HD order\` |
+| Build a workflow | \`Build an ORDER::RETURN workflow\` |
+| Edit a manifest | \`Add an appeasement form to the order page\` |
+| Scaffold a rule | \`Create a rule for ...\` |
+| Deploy | \`Deploy to staging\` |
+| Go-live audit | \`Run a Ready For Launch assessment\` |
+
+## Knowledge
+
+- \`knowledge/\` — Platform knowledge (domain model, SDK reference, rule contracts, order patterns). Managed by installer.
+- \`accounts/<PROFILE>/knowledge/\` — Account-specific conventions. Create via \`/fluent-knowledge-init\`.
+- \`accounts/<PROFILE>/memory/\` — Auto-accumulated learnings from your sessions.
+
+## Conventions
+
+<!-- Add your team-specific conventions below. Examples: -->
+<!-- - 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 -->
+`;
+
+  writeFileSync(dest, content, "utf-8");
+  return true;
+}
+
 function uninstallKnowledge() {
   const dest = join(getProjectRoot(), "knowledge");
   if (!existsSync(dest)) return false;
@@ -1297,7 +1397,7 @@ function runVerify(profile) {
   if (fluentVer) {
     pass("Fluent CLI", fluentVer);
   } else {
-    fail("Fluent CLI not found", "npm install -g @fluentcommerce/cli");
+    fail("Fluent CLI not found", "Install from https://docs.fluentcommerce.com/building-blocks/fluent-cli-package");
   }
 
   // 3. Claude Code
@@ -1452,7 +1552,7 @@ function runVerify(profile) {
   if (existsSync(claudeMdPath)) {
     pass("CLAUDE.md", "workspace instructions present");
   } else {
-    warn("CLAUDE.md not found", "Create repo/workspace instructions manually if needed");
+    warn("CLAUDE.md not found", "Re-run install to generate a starter, or create one manually");
   }
 
   // 8. Fluent CLI profile (if --profile provided or detected from MCP config)
@@ -1678,6 +1778,8 @@ function parseMcpSetupArgs(args) {
     extnRepo: DEFAULT_MCP_EXTN_REPO,
     profile: "",
     profileRetailer: "",
+    profilesFile: "",
+    discoverProfiles: false,
     officialServerName: "fluent-mcp",
     extnServerName: "fluent-mcp-extn",
     browserServerName: "chrome-devtools",
@@ -1765,6 +1867,15 @@ function parseMcpSetupArgs(args) {
       case "--save-video":
         options.saveVideo = args[++i] || "1920x1080";
         break;
+      case "--profiles-file":
+        options.profilesFile = args[++i];
+        if (!options.profilesFile) {
+          throw new Error("Missing value for --profiles-file");
+        }
+        break;
+      case "--discover-profiles":
+        options.discoverProfiles = true;
+        break;
       default:
         throw new Error(`Unknown option for mcp-setup: ${arg}`);
     }
@@ -1774,9 +1885,80 @@ function parseMcpSetupArgs(args) {
     throw new Error("--profile-retailer requires --profile");
   }
 
+  if (options.discoverProfiles && options.profilesFile) {
+    throw new Error("--discover-profiles and --profiles-file are mutually exclusive");
+  }
+
   return options;
 }
 
+/**
+ * Scan ~/.fluentcommerce/ for CLI profile directories and their retailer overrides.
+ * Returns an array of { profile, retailer? } entries suitable for fluent-profiles.json.
+ */
+function discoverFluentProfiles() {
+  const fluentDir = join(homedir(), ".fluentcommerce");
+  if (!existsSync(fluentDir)) {
+    throw new Error(`No Fluent CLI profiles found: ${fluentDir} does not exist`);
+  }
+
+  const entries = [];
+  const dirs = readdirSync(fluentDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && !d.name.startsWith("."))
+    .map((d) => d.name)
+    .sort();
+
+  for (const dirName of dirs) {
+    const profileJsonPath = join(fluentDir, dirName, "profile.json");
+    if (!existsSync(profileJsonPath)) continue;
+
+    // Find retailer override files: retailer.<REF>.json
+    const profileDir = join(fluentDir, dirName);
+    const retailerFiles = readdirSync(profileDir)
+      .filter((f) => f.startsWith("retailer.") && f.endsWith(".json") && !f.endsWith(".bak"))
+      .sort();
+
+    if (retailerFiles.length === 0) {
+      // Profile with no retailer overrides — add as profile-only entry
+      entries.push({ profile: dirName });
+    } else {
+      for (const rf of retailerFiles) {
+        // Extract retailer ref from filename: retailer.<REF>.json
+        const ref = rf.slice("retailer.".length, -".json".length);
+        if (ref) {
+          entries.push({ profile: dirName, retailer: ref });
+        }
+      }
+    }
+  }
+
+  if (entries.length === 0) {
+    throw new Error(`No valid profiles found in ${fluentDir} (no profile.json files)`);
+  }
+
+  return entries;
+}
+
+/**
+ * Read and validate a profiles JSON file. Returns the parsed array.
+ */
+function readProfilesFile(filePath) {
+  const resolved = resolve(filePath);
+  if (!existsSync(resolved)) {
+    throw new Error(`Profiles file not found: ${resolved}`);
+  }
+  const parsed = JSON.parse(readFileSync(resolved, "utf-8"));
+  if (!Array.isArray(parsed) || parsed.length === 0) {
+    throw new Error(`Profiles file must be a non-empty JSON array: ${resolved}`);
+  }
+  for (const entry of parsed) {
+    if (!entry.profile || typeof entry.profile !== "string") {
+      throw new Error(`Each entry in profiles file must have a "profile" string: ${JSON.stringify(entry)}`);
+    }
+  }
+  return parsed;
+}
+
 function buildManagedMcpConfigs(options, settings = {}) {
   const codexGlobal = Boolean(settings.codexGlobal);
   const startup_timeout_sec = codexGlobal ? 30.0 : undefined;
@@ -1826,6 +2008,14 @@ function buildManagedMcpConfigs(options, settings = {}) {
       FLUENT_RETAILER_ID: "YOUR_RETAILER",
     };
   }
+  // Multi-profile: wire profiles file into extn server for connection.list/switch
+  if (options.resolvedProfilesFile) {
+    extnDesired.env = {
+      ...extnDesired.env,
+      FLUENT_PROFILES_FILE: options.resolvedProfilesFile,
+      FLUENT_CACHE_ENABLED: "true",
+    };
+  }
 
   let browserDesired = null;
   if (!options.noBrowser) {
@@ -2030,6 +2220,41 @@ function setupMcp(options) {
   // lands in the workspace root, not inside a sub-package that happens to
   // have its own .git directory.
   const projectRoot = getProjectRoot();
+
+  // --- Multi-profile: discover or validate profiles file ---
+  if (options.discoverProfiles) {
+    const profiles = discoverFluentProfiles();
+    const profilesPath = join(projectRoot, "fluent-profiles.json");
+    writeFileSync(profilesPath, `${JSON.stringify(profiles, null, 2)}\n`);
+    logOk(`discovered ${profiles.length} profile/retailer entries → fluent-profiles.json`);
+    options.resolvedProfilesFile = "./fluent-profiles.json";
+    // Use first entry as default profile if --profile not explicitly provided
+    if (!options.profile && profiles[0]) {
+      options.profile = profiles[0].profile;
+      if (profiles[0].retailer && !options.profileRetailer) {
+        options.profileRetailer = profiles[0].retailer;
+      }
+      log(`  Default profile: ${options.profile}${options.profileRetailer ? ` / ${options.profileRetailer}` : ""}`);
+    }
+  } else if (options.profilesFile) {
+    const profiles = readProfilesFile(options.profilesFile);
+    // Store relative path for .mcp.json (relative to project root)
+    const absPath = resolve(options.profilesFile);
+    const relPath = absPath.startsWith(projectRoot)
+      ? "./" + absPath.slice(projectRoot.length + 1).replace(/\\/g, "/")
+      : absPath.replace(/\\/g, "/");
+    options.resolvedProfilesFile = relPath;
+    logOk(`validated profiles file: ${relPath} (${profiles.length} entries)`);
+    // Use first entry as default profile if --profile not explicitly provided
+    if (!options.profile && profiles[0]) {
+      options.profile = profiles[0].profile;
+      if (profiles[0].retailer && !options.profileRetailer) {
+        options.profileRetailer = profiles[0].retailer;
+      }
+      log(`  Default profile: ${options.profile}${options.profileRetailer ? ` / ${options.profileRetailer}` : ""}`);
+    }
+  }
+
   const mcpConfigPath = join(projectRoot, ".mcp.json");
   const mcpConfig = readJsonObjectOrDefault(mcpConfigPath, {});
 
@@ -2062,6 +2287,14 @@ function setupMcp(options) {
         : {}),
     };
   }
+  // Preserve profiles file env from buildManagedMcpConfigs
+  if (options.resolvedProfilesFile) {
+    extnMerged.env = {
+      ...(extnMerged.env || {}),
+      FLUENT_PROFILES_FILE: options.resolvedProfilesFile,
+      FLUENT_CACHE_ENABLED: "true",
+    };
+  }
   stripSensitiveEnv(extnMerged);
 
   mcpConfig.mcpServers[options.officialServerName] = officialMerged;
@@ -2098,8 +2331,11 @@ function setupMcp(options) {
   log("");
   log("MCP bootstrap complete.");
   log(`Updated: ${mcpConfigPath}`);
-  logOk(`official server: ${options.officialServerName}`);
-  logOk(`extension server: ${options.extnServerName}`);
+  logOk(`official server: ${options.officialServerName}${options.profile ? ` (profile: ${options.profile})` : ""}`);
+  logOk(`extension server: ${options.extnServerName}${options.resolvedProfilesFile ? " (multi-profile)" : ""}`);
+  if (options.resolvedProfilesFile) {
+    logOk(`profiles file: ${options.resolvedProfilesFile} → connection.list / connection.switch`);
+  }
   if (!options.noBrowser) {
     logOk(`chrome-devtools server: ${options.browserServerName} (for /fluent-ui-test, /fluent-ui-record)`);
     if (options.saveVideo) {
@@ -2825,6 +3061,8 @@ GLOBAL OPTIONS
   --scope <name>           Codex scope: user (default) or project
   --profile <name>         Fluent CLI profile — auto-configures .mcp.json on install
   --profile-retailer <ref> Retailer ref (requires --profile)
+  --profiles-file <path>   Path to fluent-profiles.json for multi-profile switching
+  --discover-profiles      Scan ~/.fluentcommerce/ and generate fluent-profiles.json
   --install-mcp-extn       npm install @fluentcommerce/fluent-mcp-extn locally (faster startup)
 
 GROUPS
@@ -2840,6 +3078,9 @@ EXAMPLES
   npx @fluentcommerce/ai-skills generate
   npx @fluentcommerce/ai-skills mcp-setup --profile MYPROFILE
   npx @fluentcommerce/ai-skills mcp-setup --profile MYPROFILE --profile-retailer MY_RETAILER
+  npx @fluentcommerce/ai-skills mcp-setup --discover-profiles
+  npx @fluentcommerce/ai-skills mcp-setup --profiles-file ./fluent-profiles.json
+  npx @fluentcommerce/ai-skills mcp-setup --profile MYPROFILE --profiles-file ./fluent-profiles.json
   npx @fluentcommerce/ai-skills mcp-setup --with-chrome
   npx @fluentcommerce/ai-skills mcp-setup --install-extn-source
   npx @fluentcommerce/ai-skills flow-run --profile MYPROFILE --retailer MY_RETAILER --module dist/module.zip
@@ -2854,6 +3095,8 @@ NOTES
   - Use --save-video [resolution] to enable browser video recording via experimentalScreencast (default: 1920x1080).
   - Chrome MCP Extension is opt-in for manual debugging with existing Chrome sessions. Use --with-chrome to add it alongside Chrome DevTools MCP. Requires Chrome extension from https://github.com/hangwin/mcp-chrome
   - mcp-setup writes/merges .mcp.json in the project root and preserves existing servers.
+  - Multi-profile: --discover-profiles scans ~/.fluentcommerce/ for CLI profiles and retailer overrides, generates fluent-profiles.json, and wires it into the extension server. Use --profiles-file to point to an existing file instead. The first entry becomes the default profile. Switch profiles at runtime via connection.list / connection.switch MCP tools.
+  - When --profiles-file or --discover-profiles is combined with --profile, the explicit --profile takes precedence as the default (overriding the first-entry default).
   - Aliases: mcp -> mcp-extn, mcp-core -> mcp-official.
 
 ENVIRONMENT VARIABLES (optional overrides — profile-based auth is primary)
@@ -2884,6 +3127,8 @@ function parseArgs(argv) {
   let scope = "user";
   let profile = "";
   let profileRetailer = "";
+  let profilesFile = "";
+  let discoverProfilesFlag = false;
   const rest = [];
 
   for (let i = 0; i < argv.length; i++) {
@@ -2917,6 +3162,14 @@ function parseArgs(argv) {
         throw new Error("Missing value for --profile-retailer");
       }
       i++;
+    } else if (argv[i] === "--profiles-file") {
+      profilesFile = argv[i + 1] || "";
+      if (!profilesFile) {
+        throw new Error("Missing value for --profiles-file");
+      }
+      i++;
+    } else if (argv[i] === "--discover-profiles") {
+      discoverProfilesFlag = true;
     } else {
       rest.push(argv[i]);
     }
@@ -2928,6 +3181,8 @@ function parseArgs(argv) {
     scope: normalizeCodexScope(scope),
     profile,
     profileRetailer,
+    profilesFile,
+    discoverProfiles: discoverProfilesFlag,
     command: rest[0],
     commandArgs: rest.slice(1),
     groupArgs: rest.slice(1).filter((v) => !v.startsWith("--")).map((v) => v.toLowerCase()),
@@ -2954,7 +3209,7 @@ function main() {
     process.exit(1);
   }
 
-  const { projectRoot, target, scope, profile, profileRetailer, command, commandArgs, groupArgs } = parsed;
+  const { projectRoot, target, scope, profile, profileRetailer, profilesFile, discoverProfiles, command, commandArgs, groupArgs } = parsed;
 
   try {
     setProjectRoot(resolveProjectRoot(projectRoot));
@@ -2981,18 +3236,25 @@ function main() {
           logOk(`knowledge: ${knowledgeCount} file(s) → knowledge/`);
         }
 
+        // Generate starter CLAUDE.md if not present (never overwrites)
+        if (generateStarterClaudeMd(profile, profileRetailer)) {
+          logOk("CLAUDE.md: starter workspace instructions created");
+        }
+
         log("");
         log(`Done. Groups: ${selected.map((g) => g.name).join(", ")}`);
 
-        // Auto-configure MCP when --profile is provided
-        if (profile) {
+        // Auto-configure MCP when --profile or --discover-profiles or --profiles-file is provided
+        if (profile || discoverProfiles || profilesFile) {
           log("");
           log("Configuring MCP servers...");
           log("==========================");
           try {
             const mcpOptions = parseMcpSetupArgs([
-              "--profile", profile,
+              ...(profile ? ["--profile", profile] : []),
               ...(profileRetailer ? ["--profile-retailer", profileRetailer] : []),
+              ...(profilesFile ? ["--profiles-file", profilesFile] : []),
+              ...(discoverProfiles ? ["--discover-profiles"] : []),
             ]);
             if (target === "codex" && scope === "user") {
               setupCodexGlobalMcp(mcpOptions);
@@ -3061,7 +3323,7 @@ function main() {
       case "mcp-setup":
       case "setup-mcp":
       case "init-mcp": {
-        // Re-inject --profile/--profile-retailer if parsed at top level
+        // Re-inject top-level args if not already in command-specific args
         const mcpArgs = [...commandArgs];
         if (profile && !mcpArgs.includes("--profile") && !mcpArgs.includes("-p")) {
           mcpArgs.push("--profile", profile);
@@ -3069,6 +3331,12 @@ function main() {
         if (profileRetailer && !mcpArgs.includes("--profile-retailer")) {
           mcpArgs.push("--profile-retailer", profileRetailer);
         }
+        if (profilesFile && !mcpArgs.includes("--profiles-file")) {
+          mcpArgs.push("--profiles-file", profilesFile);
+        }
+        if (discoverProfiles && !mcpArgs.includes("--discover-profiles")) {
+          mcpArgs.push("--discover-profiles");
+        }
         const options = parseMcpSetupArgs(mcpArgs);
         if (target === "codex" && scope === "user") {
           setupCodexGlobalMcp(options);

package/content/cli/skills/fluent-cli-mcp-cicd/SKILL.md

@@ -97,7 +97,8 @@ jobs:
         with: { node-version: 20 }
 
       - name: Install Fluent CLI
-        run: npm i -g @fluentcommerce/cli
+        # Install method: https://docs.fluentcommerce.com/building-blocks/fluent-cli-package
+        run: echo "Replace with your org's Fluent CLI install step"
 
       - name: Create profile
         run: |
@@ -134,7 +135,8 @@ fluent-deploy:
   only:
     changes: [plugins/**, resources/**]
   before_script:
-    - npm i -g @fluentcommerce/cli
+    # Install method: https://docs.fluentcommerce.com/building-blocks/fluent-cli-package
+    - echo "Replace with your org's Fluent CLI install step"
     - apt-get update && apt-get install -y maven
   script:
     - fluent profile create deploy-target --id $FLUENT_ACCOUNT_ID --base-url $FLUENT_BASE_URL --username $FLUENT_USERNAME --password $FLUENT_PASSWORD --client-secret $FLUENT_CLIENT_SECRET
@@ -167,7 +169,8 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with: { node-version: '20' }
-      - run: npm install -g @fluentcommerce/cli
+      # Install method: https://docs.fluentcommerce.com/building-blocks/fluent-cli-package
+      - run: echo "Replace with your org's Fluent CLI install step"
       - name: Validate
         run: fluent module validate --path ${{ github.workspace }}/modules/$MODULE_NAME
       - name: Pre-deploy check