@fluentcommerce/ai-skills 0.13.0 → 0.14.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.
 
@@ -382,7 +382,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 +390,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 +728,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 +754,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 +781,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";
@@ -1301,9 +1302,18 @@ function installDocs() {
   const src = join(dirname(fileURLToPath(import.meta.url)), "..", "docs");
   if (!existsSync(src)) return 0;
   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 });
-  cpSync(src, 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) => {
@@ -1427,6 +1437,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 +1536,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 +1548,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,
 };
 
 /**

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

@@ -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/dev/agents/fluent-backend-dev.md

@@ -16,7 +16,7 @@ skills:
   - fluent-data-module-scaffold
   - fluent-module-validate
   - fluent-build
-  - fluent-source-onboard
+  - fluent-module-convert
   - fluent-trace
   - fluent-entity-flow-diagnose
   - fluent-event-api
@@ -202,7 +202,7 @@ Execute the approved plan:
 | Scaffold data modules | `/fluent-data-module-scaffold` | Data-only modules |
 | Validate modules | `/fluent-module-validate` | Module structure checks |
 | Build modules | `/fluent-build` | Maven compile + package |
-| Onboard source | `/fluent-source-onboard` | Import non-standard code |
+| Convert to module | `/fluent-module-convert` | Convert plugins/source to module format |
 | Manage settings | `/fluent-settings` | Settings lifecycle |
 | Configure retailer | `/fluent-retailer-config` | Environment bootstrap |
 | Trace events | `/fluent-trace` | Event forensics |

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

@@ -26,7 +26,7 @@ skills:
   - fluent-data-module-scaffold
   - fluent-module-validate
   - fluent-build
-  - fluent-source-onboard
+  - fluent-module-convert
   - fluent-trace
   - fluent-entity-flow-diagnose
   - fluent-event-api

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

@@ -27,7 +27,7 @@ This skill owns source discovery, code mapping, behavior explanation, and extens
 
 **Routing guardrail:** If the user is asking about source-level backend implementation inside a plugin, class, module, or repo, stay on this skill. Do NOT reroute to `/fluent-implementation-map` or `/fluent-feature-explain` unless the request is clearly about a broader feature/account architecture rather than the code itself.
 
-**HARD NEGATIVE — NOT rule-scaffold or source-onboard:** If the prompt says "analyze", "explain", "understand", or "what does this code do" about existing custom code, this is fluent-custom-code, NOT fluent-rule-scaffold (which creates NEW rules) and NOT fluent-source-onboard (which restructures code INTO module format).
+**HARD NEGATIVE — NOT rule-scaffold or module-convert:** If the prompt says "analyze", "explain", "understand", or "what does this code do" about existing custom code, this is fluent-custom-code, NOT fluent-rule-scaffold (which creates NEW rules) and NOT fluent-module-convert (which converts/restructures code INTO module format).
 
 - Workflow structure analysis is owned by `/fluent-workflow-analyzer`.
 - Runtime failure tracing is owned by `/fluent-trace`.

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

@@ -114,9 +114,9 @@ Write the plan file, present it to the user, and wait for explicit approval ("ye
 
 | Parameter | Required | Default | Description |
 |-----------|----------|---------|-------------|
-| `module-name` | Yes | -- | Module identifier (e.g., `hm-infra-data`). Lowercase alphanumeric with hyphens only. Used for directory name and `module.json` name field. |
+| `module-name` | Yes | -- | Module identifier (e.g., `acme-infra-data`). Lowercase alphanumeric with hyphens only. Used for directory name and `module.json` name field. |
 | `--description` | No | Auto-generated | Module description for `module.json` |
-| `--account-prefix` | No | Auto-detect from profile | Account/company prefix for the module name in `module.json` (e.g., `hm`, `acme`) |
+| `--account-prefix` | No | Auto-detect from profile | Account/company prefix for the module name in `module.json` (e.g., `acme`, `globex`) |
 | `--profile` | No | Active profile | Fluent CLI profile for path resolution and prefix detection |
 | `--initial-version` | No | `1.0.0` | Initial version in `module.json` |
 
@@ -150,7 +150,7 @@ The account prefix appears in the `module.json` `name` field as `<prefix>/<modul
 
 2. Else check existing modules under accounts/<PROFILE>/SOURCE/backend/
    Read any module.json and extract the prefix from the "name" field
-   e.g., "name": "hm/infra-data" --> prefix is "hm"
+   e.g., "name": "acme/infra-data" --> prefix is "acme"
 
 3. Else derive from PROFILE name (lowercase)
    MY_PROFILE --> myprofile
@@ -708,9 +708,9 @@ Follow these steps in order when scaffolding a new data module:
 
 4. COMPUTE derived values
    a. MODULE_TITLE = title-case of module-name with hyphens as spaces
-      (e.g., "hm-infra-data" --> "Hm Infra Data")
+      (e.g., "acme-infra-data" --> "Acme Infra Data")
    b. MODULE_DESCRIPTION = description from --description or auto-generated
-      (e.g., "Data module for Hm Infra Data")
+      (e.g., "Data module for Acme Infra Data")
 
 5. CREATE directory structure
    a. Create the root: accounts/<PROFILE>/SOURCE/backend/<module-name>/

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

@@ -854,7 +854,7 @@ Fulfilment updates from Warehouse Management System:
   "rootEntityId": "12345",
   "entityType": "CONSIGNMENT",
   "entityId": "11111",
-  "attributes": { "trackingNumber": "1Z999AA1234567890", "status": "IN_TRANSIT", "carrierRef": "UPS" }
+  "attributes": { "trackingNumber": "TRACK-001-XYZ", "status": "IN_TRANSIT", "carrierRef": "CARRIER_STD" }
 }
 ```