@fluentcommerce/ai-skills 0.13.0 → 0.15.0

package/README.md

@@ -12,7 +12,7 @@
 > - **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.12.0`) if you depend on current behavior.
+> 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.
 
@@ -106,6 +106,9 @@ This downloads workflows, scans your account, and sets up the workspace. After t
 >
 > **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
@@ -382,7 +385,7 @@ You can have multiple workspaces (e.g., one per client) each with different prof
 npx @fluentcommerce/ai-skills --version
 ```
 
-This prints the exact package version `npx` resolves for this workspace, for example `fluent-ai-skills v0.12.0`.
+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:**
 
@@ -390,7 +393,7 @@ This prints the exact package version `npx` resolves for this workspace, for exa
 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.
+`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):**
 
@@ -728,7 +731,7 @@ npx @fluentcommerce/ai-skills <command> [--profile <name>] [groups...]
 | Command | Description |
 |---|---|
 | `install [groups...]` | Install skills + configure MCP (with `--profile`) |
-| `doctor` | **Full setup health check** — Node, CLI, Claude Code, skills, MCP, profile, connectivity, versions |
+| `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 |
@@ -754,24 +757,26 @@ For server-by-server MCP details, auth notes, and optional hosting providers, se
 
 ## Eval Coverage
 
-771 eval cases across 12 suites validate skill routing, execution quality, and knowledge grounding:
+803 eval cases across 12 suites validate skill routing, execution quality, and knowledge grounding:
 
 | Suite | Cases | What it tests |
 |---|---:|---|
-| Execution | 169 | All 63 skills produce correct output (plans, code, tool calls) |
+| Execution | 188 | All 63 skills produce correct output (plans, code, tool calls) |
 | Routing | 115 | Prompt → skill selection accuracy (deterministic replay) |
-| Routing-live | 172 | Live model routing against installed skills |
-| Knowledge-grounding | 136 | Trap cases for common misconceptions and anti-patterns |
+| 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 | 18 | Multi-skill workflow execution sequences |
-| Adversarial | 11 | Ambiguous, out-of-scope, and mixed-concern prompts |
+| 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` (1,350 assertions across smoke, pack, and unit suites).
+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.
 
 ---
 
@@ -779,7 +784,7 @@ Run the test suites: `npm test` (1,350 assertions across smoke, pack, and unit s
 
 | Symptom | Fix |
 |---|---|
-| "Fluent CLI not found" | Install from [docs.fluentcommerce.com](https://docs.fluentcommerce.com/building-blocks/fluent-cli-package) then `fluent --version` |
+| "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 |

package/bin/cli.mjs

@@ -9,6 +9,7 @@ import {
   readFileSync,
   writeFileSync,
   statSync,
+  realpathSync,
 } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { join, dirname, basename, isAbsolute, resolve } from "node:path";
@@ -796,6 +797,159 @@ function removeEntry(path, type) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Merge-install: copy source files into a destination directory without
+// removing client-added files.  Tracks installed files in a manifest so
+// uninstall and re-install can clean up precisely.
+// ---------------------------------------------------------------------------
+
+const DIR_MANIFEST_FILENAME = ".fluent-installed-files.json";
+
+/**
+ * Recursively collect all relative file paths under `dir`.
+ */
+function collectRelativePaths(dir, base = dir) {
+  const paths = [];
+  if (!existsSync(dir)) return paths;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      paths.push(...collectRelativePaths(full, base));
+    } else {
+      paths.push(full.slice(base.length + 1).replace(/\\/g, "/"));
+    }
+  }
+  return paths;
+}
+
+/**
+ * Merge-install `src` into `dest`: copy every file from src (overwriting
+ * same-named files) but leave client-added files untouched.  Writes a
+ * manifest of installed files so future installs and uninstalls know
+ * exactly which files are "ours".
+ *
+ * Also removes files that were in the previous manifest but are no longer
+ * in the source (renamed/deleted upstream), then prunes empty directories.
+ *
+ * @param {string} src   - source directory (package content)
+ * @param {string} dest  - target directory (workspace or global)
+ * @param {Object} [options]
+ * @param {string[]} [options.exclude] - relative paths to skip (e.g. [".claude-plugin"])
+ * @returns {number} count of files installed
+ */
+function mergeInstallDir(src, dest, options = {}) {
+  const excludePatterns = (options.exclude || []).map((p) => p.replace(/\\/g, "/"));
+  ensureDir(dest);
+
+  // Read previous manifest to detect removals
+  const manifestPath = join(dest, DIR_MANIFEST_FILENAME);
+  const oldManifest = readJson(manifestPath);
+  const previousFiles = new Set((oldManifest && oldManifest.files) || []);
+
+  // Collect and copy source files
+  const isExcluded = (rel) => excludePatterns.some((pat) =>
+    rel === pat || rel.includes(pat) || rel.split("/").some((seg) => seg === pat)
+  );
+  const srcFiles = collectRelativePaths(src).filter((rel) => !isExcluded(rel));
+
+  for (const rel of srcFiles) {
+    const destFile = join(dest, rel);
+    ensureDir(dirname(destFile));
+    cpSync(join(src, rel), destFile, { force: true });
+  }
+
+  const installedSet = new Set(srcFiles);
+
+  // Remove files from previous install that no longer exist in source
+  for (const rel of previousFiles) {
+    if (!installedSet.has(rel)) {
+      const fullPath = join(dest, rel);
+      if (existsSync(fullPath)) {
+        rmSync(fullPath, { force: true });
+      }
+    }
+  }
+
+  // Prune empty directories (bottom-up) — skip dest root so install always has a target
+  const pruneEmpty = (dir) => {
+    if (!existsSync(dir)) return;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) pruneEmpty(join(dir, entry.name));
+    }
+    try {
+      const remaining = readdirSync(dir);
+      if (remaining.length === 0 && !isSamePath(dir, dest)) {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    } catch { /* dir already gone */ }
+  };
+  pruneEmpty(dest);
+
+  // Write new manifest
+  const manifest = {
+    version: pkg.version,
+    installedAt: new Date().toISOString(),
+    files: srcFiles.sort(),
+  };
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+
+  return srcFiles.length;
+}
+
+/**
+ * Remove only the files we previously installed (per manifest) from `dest`.
+ * Prunes empty directories afterwards.  If no manifest exists, falls back
+ * to removing the entire directory (legacy behavior).
+ *
+ * @param {string} dest - target directory to clean
+ * @returns {boolean} true if anything was removed
+ */
+function mergeUninstallDir(dest) {
+  if (!existsSync(dest)) return false;
+
+  const manifestPath = join(dest, DIR_MANIFEST_FILENAME);
+  const manifest = readJson(manifestPath);
+
+  if (!manifest || !manifest.files) {
+    // Legacy: no manifest — remove everything (matches old behavior)
+    rmSync(dest, { recursive: true, force: true });
+    return true;
+  }
+
+  let removed = 0;
+  for (const rel of manifest.files) {
+    const fullPath = join(dest, rel);
+    if (existsSync(fullPath)) {
+      rmSync(fullPath, { force: true });
+      removed++;
+    }
+  }
+
+  // Remove the manifest itself
+  if (existsSync(manifestPath)) rmSync(manifestPath, { force: true });
+
+  // Remove .version stamp if present
+  const versionFile = join(dest, ".version");
+  if (existsSync(versionFile)) rmSync(versionFile, { force: true });
+
+  // Prune empty directories (bottom-up) — including dest root on uninstall
+  const pruneEmpty = (dir) => {
+    if (!existsSync(dir)) return;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) pruneEmpty(join(dir, entry.name));
+    }
+    try {
+      const remaining = readdirSync(dir);
+      if (remaining.length === 0) {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    } catch { /* dir already gone */ }
+  };
+  pruneEmpty(dest);
+
+  return removed > 0;
+}
+
 // ---------------------------------------------------------------------------
 // Orphan cleanup: remove skills/agents from previous installs that are no
 // longer in the current catalog.  Uses a manifest file written after each
@@ -1231,10 +1385,12 @@ function installKnowledge() {
   if (!existsSync(src)) return 0;
 
   // 1. Local workspace copy (primary — supports account knowledge overrides)
+  //    Merge-install: overwrites our files, preserves client-added files.
   const dest = join(getProjectRoot(), "knowledge");
-  rmSync(dest, { recursive: true, force: true });
-  cpSync(src, dest, { recursive: true, force: true });
-  rmSync(join(dest, ".claude-plugin"), { recursive: true, force: true });
+  let count = mergeInstallDir(src, dest, { exclude: [".claude-plugin"] });
+  // Always clean up .claude-plugin directory if it leaked in
+  const pluginDir = join(dest, ".claude-plugin");
+  if (existsSync(pluginDir)) rmSync(pluginDir, { recursive: true, force: true });
   // Stamp local copy with package version for doctor version comparison
   writeFileSync(join(dest, ".version"), pkg.version, "utf-8");
 
@@ -1242,21 +1398,12 @@ function installKnowledge() {
   const refModSrc = join(CONTENT_ROOT, "dev", "reference-modules");
   if (existsSync(refModSrc)) {
     const refModDest = join(dest, "reference-modules");
-    cpSync(refModSrc, refModDest, { recursive: true, force: true });
+    count += mergeInstallDir(refModSrc, refModDest);
   }
 
   // 3. Global fallback copy (so new workspaces can skip full install)
   installGlobalKnowledge(src);
 
-  // Count copied files for reporting
-  let count = 0;
-  const walk = (dir) => {
-    for (const entry of readdirSync(dir, { withFileTypes: true })) {
-      if (entry.isDirectory()) walk(join(dir, entry.name));
-      else count++;
-    }
-  };
-  walk(dest);
   return count;
 }
 
@@ -1268,15 +1415,12 @@ function installKnowledge() {
 function installGlobalKnowledge(src) {
   if (!src) src = join(CONTENT_ROOT, "knowledge");
   if (!existsSync(src)) return 0;
-  ensureDir(GLOBAL_KNOWLEDGE_DIR);
-  rmSync(GLOBAL_KNOWLEDGE_DIR, { recursive: true, force: true });
-  cpSync(src, GLOBAL_KNOWLEDGE_DIR, { recursive: true, force: true });
-  rmSync(join(GLOBAL_KNOWLEDGE_DIR, ".claude-plugin"), { recursive: true, force: true });
+  // Global dir is fully managed (no client files) — merge-install for consistency
+  mergeInstallDir(src, GLOBAL_KNOWLEDGE_DIR, { exclude: [".claude-plugin"] });
   // Copy reference module catalog alongside global knowledge
   const refModSrc = join(CONTENT_ROOT, "dev", "reference-modules");
   if (existsSync(refModSrc)) {
-    const refModDest = join(GLOBAL_KNOWLEDGE_DIR, "reference-modules");
-    cpSync(refModSrc, refModDest, { recursive: true, force: true });
+    mergeInstallDir(refModSrc, join(GLOBAL_KNOWLEDGE_DIR, "reference-modules"));
   }
   // Stamp with package version so we can detect stale global knowledge
   writeFileSync(join(GLOBAL_KNOWLEDGE_DIR, ".version"), pkg.version, "utf-8");
@@ -1301,19 +1445,10 @@ function installDocs() {
   const src = join(dirname(fileURLToPath(import.meta.url)), "..", "docs");
   if (!existsSync(src)) return 0;
   const dest = join(getProjectRoot(), "docs");
-  // Treat workspace docs/ as installer-managed so re-installs refresh it cleanly.
-  rmSync(dest, { recursive: true, force: true });
-  cpSync(src, dest, { recursive: true, force: true });
-  // Count copied files for reporting
-  let count = 0;
-  const walk = (dir) => {
-    for (const entry of readdirSync(dir, { withFileTypes: true })) {
-      if (entry.isDirectory()) walk(join(dir, entry.name));
-      else count++;
-    }
-  };
-  walk(dest);
-  return count;
+  // Guard: when running from the repo itself, src === dest — skip to avoid self-deletion.
+  if (existsSync(dest) && realpathSync(src) === realpathSync(dest)) return 0;
+  // Merge-install: overwrites our files, preserves client-added files.
+  return mergeInstallDir(src, dest, { exclude: [".tmp."] });
 }
 
 function buildStarterWorkspaceInstructions(fileName, profile, retailer) {
@@ -1427,6 +1562,22 @@ Follow this lifecycle. Each stage has purpose-built skills:
 | **Audit** | \`/fluent-rfl-assess\`, \`/fluent-session\`, \`/fluent-feature-status\`, \`/fluent-skill-observability\` | Go-live readiness, audit trail, status dashboard, skill quality |
 <!-- /ai-skills:managed:sdlc-map -->
 
+<!-- ai-skills:managed:investigation-protocol -->
+## Investigation Protocol
+
+**Tier 1 — Direct execute (no plan):** Single-tool lookups (entity status, setting value, retailer list) and prompts that map to a single skill with its own phases (e.g., fluent-trace, fluent-workflow-builder). Proceed directly — the skill handles its own execution plan. Optionally announce the skill in one line: "Using fluent-trace for this."
+
+**Tier 2 — Micro-plan (multi-step, no approval wait):** When a question needs 2+ MCP tools and doesn't map cleanly to one skill (debugging, cross-entity tracing, analysis, "why is X broken"):
+
+1. Print an **Approach** heading, then a numbered step list with the MCP tool or skill name per step
+2. End with summary lines: \`Tools:\`, \`Skills:\`, \`Est. calls:\`, \`Watch for:\` (one-line risk)
+3. Print "[executing...]" and start immediately — no approval wait
+4. If an earlier step resolves the question, **stop and report**. List skipped steps and why. The user can say "continue with steps X-Y" to resume.
+5. For follow-up additions ("also check permissions"), **append** steps to the existing plan rather than re-planning from scratch.
+
+**Tier 3 — Full planning gate:** Deployments, scaffolding, and feature builds. Present structured plan and wait for approval. (Already enforced by skills with mandatory planning gates.)
+<!-- /ai-skills:managed:investigation-protocol -->
+
 ## Quick Actions
 
 | What you want | Say this |
@@ -1510,7 +1661,7 @@ function generateStarterWorkspaceDoc(fileName, profile, retailer) {
  * Managed section IDs embedded in workspace instruction files.
  * Content between markers is updated on every install; everything else is user-owned.
  */
-const MANAGED_SECTION_IDS = ["reference-docs", "routing-tripwires", "mcp-tools", "sdlc-map"];
+const MANAGED_SECTION_IDS = ["reference-docs", "routing-tripwires", "mcp-tools", "sdlc-map", "investigation-protocol"];
 
 /**
  * Heading patterns for each managed section — used to find and migrate
@@ -1522,6 +1673,7 @@ const MANAGED_SECTION_HEADINGS = {
   "routing-tripwires": /^##\s+Routing\s+Tripwires?\b/im,
   "mcp-tools": /^##\s+MCP\s+Tools?\b/im,
   "sdlc-map": /^##\s+SDLC\s+Skill\s+Map\b/im,
+  "investigation-protocol": /^##\s+Investigation\s+Protocol\b/im,
 };
 
 /**
@@ -1627,16 +1779,15 @@ function generateStarterGeminiMd(profile, retailer) {
 
 function uninstallKnowledge() {
   const dest = join(getProjectRoot(), "knowledge");
-  if (!existsSync(dest)) return false;
-  rmSync(dest, { recursive: true, force: true });
-  return true;
+  // Uninstall nested reference-modules first (has its own manifest)
+  const refModDest = join(dest, "reference-modules");
+  mergeUninstallDir(refModDest);
+  return mergeUninstallDir(dest);
 }
 
 function uninstallDocs() {
   const dest = join(getProjectRoot(), "docs");
-  if (!existsSync(dest)) return false;
-  rmSync(dest, { recursive: true, force: true });
-  return true;
+  return mergeUninstallDir(dest);
 }
 
 function uninstallClaude(groups) {
@@ -4123,6 +4274,27 @@ function listGroups(groups) {
   log("");
 }
 
+function showGetStarted() {
+  log(`
+fluent-ai-skills v${pkg.version}
+
+No skills installed yet. Get started:
+
+  ${"\x1b[36m"}npx @fluentcommerce/ai-skills install${"\x1b[0m"}
+
+First time? Add a Fluent CLI profile for full API access:
+
+  ${"\x1b[36m"}npx @fluentcommerce/ai-skills install --profile MYPROFILE${"\x1b[0m"}
+
+Other targets (Codex, Gemini):
+
+  npx @fluentcommerce/ai-skills install --target codex
+  npx @fluentcommerce/ai-skills install --target gemini
+
+Run ${"\x1b[36m"}npx @fluentcommerce/ai-skills --help${"\x1b[0m"} for all options.
+`);
+}
+
 function showHelp(groups) {
   const groupNames = getInstallableGroups(groups).map((group) => group.name).join(", ");
   log(`
@@ -4303,7 +4475,11 @@ function main() {
   const args = process.argv.slice(2);
 
   if (args.length === 0) {
-    showHelp(groups);
+    if (!hasAnyInstallations(groups)) {
+      showGetStarted();
+    } else {
+      showHelp(groups);
+    }
     process.exit(0);
   }
 
@@ -4443,8 +4619,8 @@ function main() {
         log("");
         targetUninstall(target, selected, { scope });
         if (!hasAnyInstallations(groups)) {
-          if (uninstallKnowledge()) logOk("removed knowledge/");
-          if (uninstallDocs()) logOk("removed docs/");
+          if (uninstallKnowledge()) logOk("removed managed files from knowledge/");
+          if (uninstallDocs()) logOk("removed managed files from docs/");
         }
         if (purge) {
           if (existsSync(GLOBAL_KNOWLEDGE_DIR)) {
@@ -4542,7 +4718,7 @@ function main() {
         break;
       }
       case "dashboard": {
-        const dashboardScript = join(dirname(fileURLToPath(import.meta.url)), "..", "tools", "generate-feature-dashboard.mjs");
+        const dashboardScript = join(dirname(fileURLToPath(import.meta.url)), "..", "tools", "feature-dashboard.mjs");
         const dashArgs = [...commandArgs];
         if (profile && !dashArgs.includes("--profile") && !dashArgs.includes("-p")) {
           dashArgs.push("--profile", profile);

package/content/cli/skills/fluent-bootstrap/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-bootstrap
-description: Complete Fluent Commerce account bootstrap wizard for greenfield environments. Use when setting up a brand-new account from scratch with no existing CLI profile or retailer yet, creating profiles, retailers, and installing reference modules with sample data. Triggers on "bootstrap account", "new fluent account", "brand-new account", "from scratch", "initialize account".
+description: Complete Fluent Commerce account bootstrap wizard for greenfield environments. Use when setting up a brand-new account from scratch with no existing CLI profile or retailer.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [profile-name] [retailer-ref]

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

@@ -1,6 +1,6 @@
 ---
 name: fluent-cli-mcp-cicd
-description: Fluent CLI MCP and CI/CD operations guide. Use for configuring `fluent mcp server --stdio`, validating MCP connectivity, and applying safe module deployment patterns in automation pipelines. Triggers on "mcp cicd", "ci cd pipeline", "automation pipeline", "mcp server setup", "fluent mcp stdio".
+description: Fluent CLI MCP and CI/CD operations guide for MCP server configuration and safe module deployment in automation pipelines. Use for CI/CD pipeline setup or MCP connectivity validation.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [mcp|cicd] [--profile name] [--retailer ref]

package/content/cli/skills/fluent-cli-reference/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-cli-reference
-description: Complete Fluent Commerce CLI v2 command reference and request router. Every command, every flag, every output format. The single source of truth for all CLI operations. Routes broad CLI questions to the right specialist skill. Triggers on "fluent cli help", "cli reference", "cli commands", "how to use fluent cli", "fluent command", "fluent cli", "cli help", "how do I use fluent", "which cli command", "cli overview".
+description: Complete Fluent Commerce CLI v2 command reference with every command, flag, and output format. Use for any CLI question or to find the right specialist skill.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [command] [subcommand]

package/content/cli/skills/fluent-cli-retailer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-cli-retailer
-description: Manage Fluent retailer lifecycle via CLI. Use for creating and listing retailers, validating profile context, and safely preparing retailer admin access for module/workflow operations. Triggers on "create retailer", "list retailers", "retailer context", "retailer admin", "fluent retailer".
+description: Manage Fluent retailer lifecycle via CLI including creation, listing, profile context validation, and retailer admin access. Use for retailer CRUD and deployment context setup.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <create|list> [retailer-ref] [--profile name]

package/content/cli/skills/fluent-connect/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-connect
-description: Guided onboarding wizard to connect this workspace to an existing Fluent Commerce account that already has a CLI profile or retailer context. Discovers existing CLI profiles, selects retailer, wires MCP servers, prepares workspace, downloads workflows, decompiles JARs, and reports readiness with cached state. Do not use for greenfield account creation or first-time retailer provisioning; that belongs to fluent-bootstrap. Triggers on "connect account", "switch account", "existing account", "wire up workspace", "connect to fluent", "change account", "setup workspace", "initialize workspace", "discover profiles".
+description: Guided onboarding wizard to connect this workspace to an existing Fluent Commerce account. Discovers profiles, wires MCP, downloads workflows. Use when connecting to an existing account.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [--profile <name>] [--retailer <ref>] [--force]
@@ -93,7 +93,18 @@ ls ~/.fluentcommerce/
 Get-ChildItem "$env:USERPROFILE\.fluentcommerce"
 ```
 
-Each subdirectory (excluding `.sessions`, `config.json`) is a potential profile. Each contains `profile.json` with `id`, `baseUrl`, `clientSecret`, `user`.
+Each subdirectory (excluding `.sessions`, `config.json`) is a potential profile. Each contains `profile.json`:
+
+```json
+{
+  "id": "<account-id>",
+  "baseUrl": "https://<account>.<tier>.api.fluentretail.com",
+  "clientSecret": "<uuid>",
+  "user": "<username>"
+}
+```
+
+> **IMPORTANT:** The `user` field is a **string** (username reference), NOT an object with credentials. Credentials are stored in a separate `user.<username>.json` file. If `user` is an object like `{ "username": "...", "password": "..." }`, the profile was created manually in the wrong format — fix it with `fluent profile create`.
 
 ### Step 1.2: Present profiles to user
 
@@ -143,6 +154,50 @@ Each file is named `retailer.<REF>.json` and contains:
 { "id": "<retailer_id>", "ref": "<ref>", "user": "<username>" }
 ```
 
+### Step 2.1b: Validate retailer file format
+
+For each `retailer.*.json` file discovered, validate it matches the canonical CLI format. Non-canonical formats can cause silent MCP auth failures and confusing connectivity errors.
+
+**Canonical format** (written by `fluent profile update`):
+```json
+{ "id": "<retailer-numeric-id>", "ref": "<retailer-ref>", "user": "<username-string>" }
+```
+
+**Known bad formats to detect:**
+
+| Pattern | Problem | Likely Cause |
+|---------|---------|-------------|
+| `{ "retailerId": ..., "username": ..., "password": ... }` | Inlined credentials, wrong field names | Manual creation or old skill version |
+| `{ "id": ..., "ref": ..., "user": { "username": ..., "password": ... } }` | `user` is object instead of string | AI wrote file directly instead of using CLI |
+| Missing `ref` field | Incomplete record | Partial manual edit |
+| Missing `user` field | No user binding | Partial creation |
+
+**Validation logic:** For each retailer file, check:
+
+1. Has `id` field (string or number)
+2. Has `ref` field (string)
+3. Has `user` field that is a **string** (not an object)
+4. Does NOT have `retailerId`, `username`, or `password` as top-level keys
+
+**If any file fails validation:**
+
+```
+⚠ Non-canonical retailer file detected:
+  File:   ~/.fluentcommerce/<PROFILE>/retailer.<REF>.json
+  Issue:  <description of what's wrong>
+  Risk:   MCP extension may fail to resolve retailer context
+
+  Fix: Re-register this retailer using the CLI:
+    fluent profile update <PROFILE> --retailer <REF> --id <ID> --username <USER> --password <PASS>
+
+  This will overwrite the file with the correct canonical format.
+  Proceed with current file anyway? [yes/NO]
+```
+
+Wait for user confirmation. If they choose to fix, guide them through the `fluent profile update` command (they must supply their password). If they proceed anyway, log the issue in the feedback record at the end of execution.
+
+**IMPORTANT — Never write retailer or profile JSON files directly.** Always delegate to `fluent profile create` or `fluent profile update` which handle format, encryption, and storage correctly. This applies even if you "know" the correct format — the CLI may add fields or change structure across versions.
+
 ### Step 2.2: Present retailers to user
 
 | # | Retailer Ref | Retailer ID | User |
@@ -346,7 +401,7 @@ const base = path.join('accounts', profile);
 const placeholders = {
   'SOURCE/backend': {
     title: 'Backend Source Code',
-    content: 'Clone Java Maven plugin repos here. Each subdirectory should be one git repo with pom.xml + src/main/java/.\n\nExample:\n  git clone https://your-org/fc-plugin-custom.git\n\nStandalone JARs (no source): place .jar files here — auto-decompiled to .decompiled/\n\nPopulated by: git clone or manual copy\nAnalyzed by: /fluent-custom-code, /fluent-source-onboard'
+    content: 'Clone Java Maven plugin repos here. Each subdirectory should be one git repo with pom.xml + src/main/java/.\n\nExample:\n  git clone https://your-org/fc-plugin-custom.git\n\nStandalone JARs (no source): place .jar files here — auto-decompiled to .decompiled/\n\nPopulated by: git clone or manual copy\nAnalyzed by: /fluent-custom-code, /fluent-module-convert'
   },
   'SOURCE/frontend': {
     title: 'Frontend Source Code',

package/content/cli/skills/fluent-profile/SKILL.md

@@ -68,8 +68,8 @@ fluent profile create cli-b2c \
   --id ABC123 \
   --base-url https://abc123.sandbox.api.fluentretail.com \
   --username admin_user \
-  --password secret123 \
-  --client-secret abc123xyz
+  --password '<your-password>' \
+  --client-secret '<your-client-secret>'
 ```
 
 ### 2. List Profiles
@@ -180,13 +180,43 @@ Profiles stored in: `~/.fluentcommerce/<profile-name>/`
 ```
 ~/.fluentcommerce/
 ├── cli-b2c/
-│   ├── profile.json
-│   ├── user.admin_user.json
-│   └── retailer.b2c.json
+│   ├── profile.json                # { "accountId", "baseUrl", "clientSecret", ... }
+│   ├── user.admin_user.json        # { "username", "password" }
+│   └── retailer.b2c.json           # { "id", "ref", "user": "<username-string>" }
 └── .sessions/
     └── <session-files>
 ```
 
+### Canonical Retailer File Format
+
+The `retailer.<ref>.json` file MUST follow this schema (written by `fluent profile update`):
+
+```json
+{ "id": "<retailer-numeric-id>", "ref": "<retailer-ref>", "user": "<username-string>" }
+```
+
+The `user` field is a **string** referencing a `user.<name>.json` file in the same directory — NOT an object with inlined credentials.
+
+### CRITICAL — Never Write Profile Files Directly
+
+**Always use CLI commands** (`fluent profile create`, `fluent profile update`) to create or modify profile, user, and retailer JSON files. Never use `Write`, `Edit`, or shell redirection (`echo >`, `cat <<EOF >`) to create or modify files under `~/.fluentcommerce/`.
+
+**Why:** The CLI handles format versioning, credential storage, field normalization, and session management. Writing files directly risks:
+- Wrong field names (`retailerId` vs `id`, `username` vs `user`)
+- Wrong value types (`user` as object instead of string reference)
+- Missing cross-references (retailer `user` must match a `user.<name>.json` filename)
+- Breaking future CLI versions that expect new fields
+
+**If you encounter a malformed profile/retailer file**, guide the user to fix it with CLI commands:
+
+```bash
+# Fix a malformed retailer file
+fluent profile update <PROFILE> --retailer <REF> --id <ID> --username <USER> --password <PASS>
+
+# Fix a malformed profile
+fluent profile create <PROFILE> --id <ACCT> --base-url <URL> --username <USER> --password <PASS> --client-secret <SECRET>
+```
+
 ## Error Handling
 
 | Error | Solution |

package/content/cli/skills/fluent-workflow/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: fluent-workflow
-description: Manage Fluent Commerce workflows - list, download, merge fragments, and track modifications. Use for workflow operations, exporting workflow JSON, merging customizations, or viewing workflow logs. HARD NEGATIVE — if the user wants to validate, review, lint, or analyze a workflow after download, route to fluent-workflow-analyzer; this skill owns retrieval and operational manipulation, not validation. Triggers on "list workflows", "download workflow", "merge workflow", "workflow fragment".
+description: List, download, merge fragments, and track workflow modifications via Fluent CLI. Use for workflow retrieval, export, merging customizations, or viewing logs.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <operation> [workflow-name]
 cursor-tier: auto
 ---
+<!-- routing-notes: HARD NEGATIVE — if the user wants to validate, review, lint, or analyze a workflow after download, route to fluent-workflow-analyzer; this skill owns retrieval and operational manipulation, not validation. -->
 
 # Workflow Management