@fluentcommerce/ai-skills 0.14.0 → 0.15.0

package/README.md

@@ -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

package/bin/cli.mjs

@@ -797,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
@@ -1232,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");
 
@@ -1243,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;
 }
 
@@ -1269,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");
@@ -1304,26 +1447,8 @@ function installDocs() {
   const dest = join(getProjectRoot(), "docs");
   // Guard: when running from the repo itself, src === dest — skip to avoid self-deletion.
   if (existsSync(dest) && realpathSync(src) === realpathSync(dest)) return 0;
-  // Treat workspace docs/ as installer-managed so re-installs refresh it cleanly.
-  rmSync(dest, { recursive: true, force: true });
-  mkdirSync(dest, { recursive: true });
-  // Copy file-by-file to avoid cpSync issues with Windows temp paths.
-  for (const entry of readdirSync(src)) {
-    if (entry.includes(".tmp.")) continue; // skip transient editor files
-    try {
-      cpSync(join(src, entry), join(dest, entry), { recursive: true, force: true });
-    } catch { /* skip files that vanish between readdir and copy */ }
-  }
-  // 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;
+  // Merge-install: overwrites our files, preserves client-added files.
+  return mergeInstallDir(src, dest, { exclude: [".tmp."] });
 }
 
 function buildStarterWorkspaceInstructions(fileName, profile, retailer) {
@@ -1654,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) {
@@ -4150,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(`
@@ -4330,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);
   }
 
@@ -4470,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)) {
@@ -4569,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]

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
 

package/content/dev/agents/fluent-frontend-dev.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-frontend-dev
-description: Fluent Commerce frontend development agent for Mystique UI framework. Builds, validates, scaffolds, and analyzes Mystique manifests and SDK component projects. Triggers on "build manifest", "create page", "validate UI", "scaffold component", "analyze manifest", "mystique", "frontend", "ui component".
+description: Fluent Commerce frontend development agent for Mystique UI framework. Builds, validates, scaffolds, and analyzes Mystique manifests and SDK component projects. Triggers on "build manifest", "create page", "validate UI", "scaffold component", "analyze manifest", "mystique", "frontend", "ui component", "new app", "build app", "create app".
 tools: Bash, Read, Write, Edit, Glob, Grep
 model: inherit
 skills:

package/content/dev/skills/fluent-account-snapshot/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-account-snapshot
-description: Lightweight account state snapshot — retailers, workflows, modules, catalogues, settings, UI customizations. MCP-first data collection with LLM summary. Triggers on "account snapshot", "account state", "account inventory", "what's in this account", "environment summary".
+description: Lightweight account state snapshot covering retailers, workflows, modules, catalogues, settings, and UI customizations with MCP-first data collection. Use for account inventory or environment summary.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [--profile <name>] [--retailer <ref>] [--include <sections>] [--json] [--refresh]

package/content/dev/skills/fluent-archive/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: fluent-archive
-description: Archive completed or abandoned features by transitioning status.json to ARCHIVED state, generating a closeout archive summary, and optionally cleaning up ephemeral reports. This is a lifecycle state-machine transition, not a session audit or change log, and it should win whenever the user wants a feature formally closed out. Triggers on "archive feature", "mark as archived", "close feature". ROUTING PRIORITY — if the prompt says "archive", "ARCHIVED", "closeout summary", "close feature", "mark as archived", or "feature done", route HERE — do NOT route to fluent-session. This skill transitions status.json and generates closeout summaries. fluent-session tracks file changes, which is completely different. Triggers also on "archive this feature", "generate closeout", "formally close". It does NOT handle session summaries (use fluent-session), feature status tables (use fluent-feature-status), or change audits.
+description: Archive completed or abandoned features by transitioning status.json to ARCHIVED state and generating a closeout summary. Use when formally closing out a feature or marking it as archived.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <feature-slug> [--profile PROFILE] [--reason completed|abandoned|superseded] [--cleanup] [--force]
 cursor-tier: auto
 ---
+<!-- routing-notes: ROUTING PRIORITY — if the prompt says "archive", "ARCHIVED", "closeout summary", "close feature", "mark as archived", or "feature done", route HERE — do NOT route to fluent-session. This skill transitions status.json and generates closeout summaries. fluent-session tracks file changes, which is completely different. Does NOT handle session summaries (use fluent-session), feature status tables (use fluent-feature-status), or change audits. -->
 
 # Feature Archival
 

package/content/dev/skills/fluent-build/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-build
-description: Build, version, and package Fluent Commerce extension modules. Handles Maven compilation, version bumping, version sync, CHANGELOG updates, git tagging, and module packaging. Use this when the user wants to compile, package, prepare, or release an artifact; do not use it for read-only deploy-readiness checks, which belong to fluent-pre-deploy-check. Triggers on "build module", "bump version", "package module", "maven build", "version status", "tag release", "version sync", "what version", "prepare release".
+description: Build, version, and package Fluent Commerce extension modules with Maven compilation, version bumping, CHANGELOG updates, and git tagging. Use when compiling, packaging, or preparing a module release.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [build|version|package|deploy|full|status|bump|sync|tag] [--skip-tests] [--level patch|minor|major] [--dry-run]
@@ -78,7 +78,7 @@ This skill does **not** own deployment runbooks. For deployment:
 
 | Signal | Condition | Example |
 |--------|-----------|---------|
-| `-> READY: <path>` | Build successful, artifact produced | `-> READY: accounts/MY_PROFILE/SOURCE/backend/fc-module-my-extensions/dist/module-0.0.30.jar` |
+| `-> READY: <path>` | Build successful, artifact produced | `-> READY: accounts/MY_PROFILE/SOURCE/backend/fc-module-my-extensions/dist/fluent-commerce-my-extensions-0.0.30.zip` |
 | `-> NEXT: /fluent-<skill>` | Ready for pre-deploy check | `-> NEXT: /fluent-pre-deploy-check` |
 | `-> BLOCKED: <reason>` | Build failed | `-> BLOCKED: VALIDATION_FAILED — Compilation error in CancelOrderRule.java:45` |
 

package/content/dev/skills/fluent-connection-analysis/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: fluent-connection-analysis
-description: Analyze workflow connection topology across multiple rulesets and workflows. Produces internal/cross-entity/cross-workflow edge maps, static-vs-dynamic runtime diffs, orphaned ruleset detection across workflow boundaries, and webhook/setting conformance inventories with Mermaid output. Use this when the question involves connection topology, cross-entity hops, cross-workflow dependencies, orphaned rulesets, runtime-vs-static drift, or mapping how work flows between rulesets/workflows. NOT for single-workflow internal structure — that stays on fluent-workflow-analyzer. ROUTING PRIORITY — if the prompt says "connection analysis", "cross-entity hops", "orphaned rulesets across workflows", "internal edges", "cross-workflow dependencies", "runtime-vs-static topology", or "connection topology", route HERE — do NOT route to fluent-workflow-analyzer. fluent-workflow-analyzer handles a SINGLE workflow's internal graph; this skill maps topology ACROSS multiple workflows and entities. Triggers on "connection analysis", "workflow connections", "map connections", "cross workflow dependencies", "cross-entity hops", "orphaned rulesets", "process flow classification", "webhook dependency map", "expected vs observed rulesets", "runtime workflow diff", "internal edges", "connection topology".
+description: Analyze workflow connection topology across multiple rulesets and workflows with edge maps, runtime diffs, and orphan detection. Use for cross-entity hops, cross-workflow dependencies, or connection topology analysis.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <workflow-file-or-name> [--deep] [--mermaid] [--output <path>] [--validate <entity-ref> --entity-type ORDER|FULFILMENT] [--from <iso> --to <iso>]
 cursor-tier: auto
 ---
+<!-- routing-notes: ROUTING PRIORITY — if the prompt says "connection analysis", "cross-entity hops", "orphaned rulesets across workflows", "internal edges", "cross-workflow dependencies", "runtime-vs-static topology", or "connection topology", route HERE — do NOT route to fluent-workflow-analyzer. fluent-workflow-analyzer handles a SINGLE workflow's internal graph; this skill maps topology ACROSS multiple workflows and entities. -->
 
 # Fluent Connection Analysis
 

package/content/dev/skills/fluent-custom-code/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: fluent-custom-code
-description: Analyze custom Fluent implementation source code under accounts/<PROFILE>/SOURCE/backend, explain behavior, and prepare safe extension plans even when repo/module layout is non-standard. ROUTING PRIORITY — source-level backend questions like "which class handles X", "which rule implements Y", "explain this custom Java plugin", or "understand this backend code before we change it" belong here, not in fluent-implementation-map or fluent-feature-explain. Workflow-name or feature-name prompts like "explain ORDER::HD end-to-end" stay on fluent-feature-explain unless the user explicitly asks about a class, plugin, module, or source file. Triggers on "analyze custom code", "explain this plugin", "extend rule logic", "understand source", "custom backend code", "which class handles", "non-standard module structure".
+description: Analyze custom Fluent implementation source code under accounts/PROFILE/SOURCE/backend, explain behavior, and prepare safe extension plans. Use for source-level backend questions about custom Java plugins, classes, or rule implementations.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <PROFILE> [--retailer <RETAILER_REF>] [--objective "<what to change>"]
 cursor-tier: manual
 ---
+<!-- routing-notes: ROUTING PRIORITY — source-level backend questions like "which class handles X", "which rule implements Y", "explain this custom Java plugin" belong here, not in fluent-implementation-map or fluent-feature-explain. Workflow-name or feature-name prompts like "explain ORDER::HD end-to-end" stay on fluent-feature-explain unless the user explicitly asks about a class, plugin, module, or source file. -->
 
 # Custom Code Intelligence
 

package/content/dev/skills/fluent-data-module-scaffold/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: fluent-data-module-scaffold
-description: Scaffold a new Fluent Commerce data module (no Java plugins). Generates module structure with assets directories, module.json, config template, and build script. ROUTING PRIORITY over fluent-module-scaffold when the user says "no Java", "no code", "workflow-only module", "JSON-only module", "data-only module", or "no compiled plugins". Any constraint that eliminates Java compilation means data module, not extension module. ROUTING PRIORITY for data-only modules — route here instead of fluent-module-scaffold when the module has no Java plugins, only workflows/settings/resources. Triggers on "create data module", "scaffold data module", "new data module", "data module", "no Java module", "workflow only module", "module without Java", "module that only has workflow JSON".
+description: Scaffold a new Fluent Commerce data module (no Java plugins) with assets directories, module.json, config template, and build script. Use for workflow-only, settings-only, or data-only modules without compiled code.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <module-name> [--profile <profile>]
 cursor-tier: auto
 planning-gate: mandatory
 ---
+<!-- routing-notes: ROUTING PRIORITY over fluent-module-scaffold when the user says "no Java", "no code", "workflow-only module", "JSON-only module", "data-only module", or "no compiled plugins". Any constraint that eliminates Java compilation means data module, not extension module. -->
 
 # Data Module Scaffolder
 

package/content/dev/skills/fluent-e2e-test/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-e2e-test
-description: Run end-to-end test sequences for Fluent Commerce workflows. Discover environment, create entities dynamically, fire events, poll statuses, assert state transitions, and report results. Use this when the user explicitly wants a test scenario or verification run, not when they want an autonomous orchestrator to keep pursuing a broad goal across multiple skills. Triggers on "run e2e test", "test order flow", "test workflow", "e2e test", "integration test".
+description: Run end-to-end test sequences for Fluent Commerce workflows by creating entities, firing events, polling statuses, and asserting state transitions. Use for explicit test scenarios or workflow verification runs.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [scenario-name] [--order-ref <ref>] [--entity-type ORDER|FULFILMENT]

package/content/dev/skills/fluent-entity-flow-diagnose/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: fluent-entity-flow-diagnose
-description: "HARD NEGATIVE FIRST — Do NOT route here for JOB/BATCH entities: \"JOB entity stuck\", \"BATCH stuck\", \"job lifecycle\", \"batch monitoring\", \"JOB/BATCH orchestration\", \"job not progressing\", \"batch not progressing\" → ALL go to fluent-job-batch, NOT here. JOB/BATCH are specialized orchestration entities this skill does not understand. Reconstruct the full lifecycle of a real Fluent Commerce entity (ORDER, FULFILMENT, ARTICLE, etc. — NOT JOB/BATCH) from its ref or id — rebuild the complete dynamic event sequence, resolve root and child workflows, and compare observed runtime behavior against the static workflow definition to produce an expected-vs-observed diff. ROUTING PRIORITY over fluent-trace when the prompt asks to \"compare runtime vs expected workflow path\", \"expected vs observed\", \"what should have happened\", or \"diagnose and compare runtime vs workflow\". Use ONLY when the user explicitly asks to reconstruct the complete lifecycle, compare runtime vs workflow definition, or perform expected-vs-observed analysis across root and sub-entities. HARD NEGATIVE for fluent-trace confusion — Do NOT route here when the prompt says \"trace why\", \"stuck\", \"root cause\", \"not progressing\", \"correlate events with rules\", \"identify root cause\", \"show live state\", or \"debug\" WITHOUT ALSO saying \"compare runtime\", \"expected vs observed\", or \"what should have happened\". Pure first-responder debugging ALWAYS goes to fluent-trace first. Triggers on \"reconstruct lifecycle\", \"compare runtime vs workflow\", \"compare runtime vs expected\", \"full entity history\", \"expected vs observed\", \"what should have happened\", \"lifecycle reconstruction\", \"diagnose and compare\"."
+description: Reconstruct the full lifecycle of a Fluent Commerce entity and compare observed runtime behavior against the static workflow definition. Use when comparing expected vs observed entity flow or reconstructing complete lifecycle history.
 user-invocable: true
 read-only: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <entity-ref-or-id> [--entity-type <TYPE>] [--identifier-kind ref|id|auto] [--from <iso> --to <iso>] [--output <path>] [--deep]
 cursor-tier: auto
 ---
+<!-- routing-notes: HARD NEGATIVE — Do NOT route here for JOB/BATCH entities (→ fluent-job-batch). ROUTING PRIORITY over fluent-trace when the prompt asks to "compare runtime vs expected", "expected vs observed", or "what should have happened". HARD NEGATIVE for fluent-trace confusion — Do NOT route here when the prompt says "trace why", "stuck", "root cause", "not progressing", "debug" WITHOUT comparison language. Pure first-responder debugging goes to fluent-trace. -->
 
 # Entity Flow Diagnose
 

package/content/dev/skills/fluent-event-api/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: fluent-event-api
-description: "EVENT API knowledge and conceptual reference — the canonical skill for understanding the Fluent Commerce event data model, the Fluent event model, event types, event categories, event statuses, orchestration routing, how events are routed to rulesets, run-once execution model, log actions vs audit actions, and event context model. This IS a valid, actionable platform skill that reads real knowledge documents and produces structured output — NEVER classify as 'none', 'direct knowledge', or 'direct knowledge lookup'. Even if the question sounds conceptual, this skill loads knowledge/platform docs and synthesizes a referenced answer. ROUTING PRIORITY — if the prompt asks about 'event model', 'the Fluent event model', 'event types', 'event categories', 'event statuses', 'how events are routed to rulesets', 'event execution model', 'log action vs audit action', 'log actions and audit actions', 'run-once', 'sourceEvents semantics', or 'deep-dive on Event API', route HERE — do NOT route to fluent-feature-explain, fluent-workflow-analyzer, or fluent-mcp-tools. Even if the prompt mentions workflows, rulesets, `event_list`, or `sourceEvents`, semantic questions about event statuses, categories, routing, audit-vs-log actions, or execution belong HERE. fluent-feature-explain is for explaining business features; fluent-workflow-analyzer is for analyzing one workflow definition; fluent-mcp-tools is for sending events and running MCP operations; this skill owns the Event API data model itself. Triggers on 'event api', 'event types', 'event categories', 'query events', 'event model', 'the fluent event model', 'event status', 'event history', 'run once', 'log action', 'audit action', 'event execution model', 'how events are routed to rulesets', 'orchestration engine routes events', 'sourceEvents'."
+description: Event API knowledge and conceptual reference covering the Fluent Commerce event data model, event types, categories, statuses, orchestration routing, run-once execution, and log vs audit actions. Use for event model questions or API semantics.
 user-invocable: true
 read-only: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [--entity-ref <ref>] [--entity-type ORDER|FULFILMENT] [--status FAILED|SUCCESS|SCHEDULED] [--type ORCHESTRATION|ORCHESTRATION_AUDIT]
 cursor-tier: manual
 ---
+<!-- routing-notes: ROUTING PRIORITY — if the prompt asks about "event model", "event types", "event categories", "event statuses", "how events are routed to rulesets", "run-once", "sourceEvents semantics", or "log action vs audit action", route HERE — do NOT route to fluent-feature-explain, fluent-workflow-analyzer, or fluent-mcp-tools. Even if the prompt mentions workflows, rulesets, event_list, or sourceEvents, semantic questions about the event data model belong HERE. fluent-mcp-tools is for sending events; this skill owns the Event API data model itself. -->
 
 # Fluent Commerce Event API
 

package/content/dev/skills/fluent-feature-explain/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: fluent-feature-explain
-description: Reverse-engineer and explain an existing Fluent Commerce feature. Synthesizes workflow analysis, custom code logic, connection topology, and live runtime evidence into a comprehensive, visually rich Feature Architecture Document saved to accounts/<PROFILE>/features/<slug>/architecture.md. ROUTING PRIORITY — if the prompt names a specific existing workflow or feature such as "ORDER::HD", "FULFILMENT::CC", "Home Delivery", or asks "how does this work", "reverse-engineer this feature", or "document this flow", route HERE rather than fluent-implementation-map or fluent-feature-plan. Use this for feature/flow architecture such as "how does Home Delivery work", "explain ORDER::HD end-to-end", or "document this fulfilment flow", not for source-level plugin/class questions inside custom backend code; those belong to /fluent-custom-code. Key knowledge — domain-model.md (entity relationships), workflow-json-structure.md (status machines), sync-vs-async-patterns.md (event flows). HARD NEGATIVE — Do NOT route here for: 'event lifecycle' / 'event API' / 'event flow' / 'event payload' / 'send event' / 'event attributes' (→ fluent-event-api for event-centric questions), broad account-wide inventory or "what's been built" requests (→ fluent-implementation-map), or future-change planning requests like "can we add" / "plan this change" (→ fluent-feature-plan). Triggers on "explain feature", "how does this work", "reverse engineer", "feature architecture", "document this flow", "what does this workflow do", "ORDER::HD", "FULFILMENT::CC".
+description: Reverse-engineer and explain an existing Fluent Commerce feature by synthesizing workflow analysis, custom code, connection topology, and runtime evidence into an architecture document. Use when explaining how a specific feature or workflow works.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <feature-name-or-workflow> [--depth shallow|full] [--include-runtime] [--output <path>]
 cursor-tier: manual
 ---
+<!-- routing-notes: ROUTING PRIORITY — if the prompt names a specific existing workflow or feature such as "ORDER::HD", "FULFILMENT::CC", or asks "how does this work" or "reverse-engineer this feature", route HERE rather than fluent-implementation-map or fluent-feature-plan. HARD NEGATIVE — Do NOT route here for event-centric questions (→ fluent-event-api), broad account-wide inventory (→ fluent-implementation-map), future-change planning (→ fluent-feature-plan), or source-level plugin/class questions (→ fluent-custom-code). -->
 
 # Feature Explainer
 

package/content/dev/skills/fluent-feature-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-feature-plan
-description: Produce comprehensive feature implementation plans with universal NEW/EXISTING/MODIFIED/REUSED/OOTB classification across all artifacts. Covers rules, workflows, settings, webhooks, GraphQL operations, cross-entity flows, and deployment. Triggers on "plan feature", "feature plan", "plan implementation", "design feature", "plan this feature", "what do I need to build".
+description: Produce comprehensive feature implementation plans with NEW/EXISTING/MODIFIED/REUSED/OOTB classification across all artifacts including rules, workflows, and settings. Use for planning a feature implementation.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <feature-description> [--profile PROFILE] [--retailer RETAILER_REF]
@@ -96,6 +96,7 @@ Check for project-specific knowledge that should inform feature planning:
    - `knowledge/platform/reference-modules.md` — use for OOTB capabilities before planning new custom assets
    - `knowledge/platform/reusability-patterns.md` — use for deciding when to reuse patterns, extend them, or introduce new artifacts
    - `knowledge/platform/sync-vs-async-patterns.md` — use for event choreography, sequencing, and long-running orchestration choices
+   - `knowledge/platform/interaction-design-patterns.md` — use for user action patterns, module visibility, and strict action contracts (eventName, context[], modules[], attributes[])
    - `knowledge/platform/rule-development-contract.md` — **MANDATORY**: annotation contract (`@ParamString` vs `@EventAttribute`), reading patterns, enhancement protocol for Rules Inventory section
    - `knowledge/platform/create-order-reference.md` — createOrder/createReturnOrder/createFulfilment input schemas, fulfilmentChoice wiring, ORDER::MULTI patterns. Use when planning features that create or modify orders.
 4. If `accounts/<PROFILE>/memory/index.md` exists, read the top account-specific gotchas and apply them silently while planning.

package/content/dev/skills/fluent-feature-status/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-feature-status
-description: Dashboard view of all features and their lifecycle status. Scans accounts/<PROFILE>/features/*/status.json and presents a consolidated table with filtering, sorting, and workspace tree view. Triggers on "feature status", "show features", "what features", "feature dashboard", "where am I", "what's in progress".
+description: Dashboard view of all features and their lifecycle status by scanning status.json files and presenting a consolidated table with filtering and sorting. Use for feature status overview or progress tracking.
 user-invocable: true
 allowed-tools: Bash, Read, Glob, Grep
 argument-hint: [--profile PROFILE] [--filter STATUS] [--format table|json] [--tree]

package/content/dev/skills/fluent-frontend-build/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-frontend-build
-description: Build, test, and validate a Mystique SDK component project. Local dev mode starts a hot-reload server on localhost:3001, wires it into the Fluent manifest, and supports live iteration. Production mode runs 7 quality gates (TypeScript, lint, tests, webpack, bundle, externals, GraphQL schema validation). Frontend equivalent of /fluent-build. Triggers on "build frontend", "build component", "yarn build", "frontend build", "sdk build", "build bundle", "test locally", "local dev", "start dev server", "run locally".
+description: Build, test, and validate a Mystique SDK component project with local dev server and 7 production quality gates. Use for frontend builds, local dev mode, or SDK bundle validation.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [project-path] [full|build|test|lint|check]