@fluentcommerce/ai-skills 0.13.0 → 0.15.0

package/docs/manifest-safety.md

@@ -0,0 +1,79 @@
+# Manifest Settings — Mandatory Safety Protocol
+
+**NEVER create or update a Mystique manifest setting without following ALL these steps.**
+
+## Fixed parameters (non-negotiable)
+- `valueType`: `"JSON"` — always. Never `"LOB"` or `"STRING"`.
+- `context`: `"ACCOUNT"` — always. Never `"RETAILER"`. `contextId`: `0`.
+- Body goes in `lobValue` — NEVER `value` (255 char limit, silently truncates).
+- `lobValue` must be raw JSON, not stringified. **Never `JSON.stringify()` — double-encodes, Mystique rejects with "invalid route".**
+- **MCP `setting_upsert` requires explicit `valueType: "JSON"`** for manifest settings — without it, defaults to LOB which breaks manifests. Preferred paths: CLI `fluent module install --include settings` or GraphQL `createSetting`/`updateSetting`. Use MCP `setting_get` (with `outputFile`) to read/backup existing settings before modification.
+
+## Before ANY setting create/update
+1. **Backup** — Save existing setting to `accounts/<PROFILE>/manifests/backups/<setting-name>_<YYYY-MM-DD>.json`. Non-manifest backups: `accounts/<PROFILE>/settings/backups/`.
+2. **Validate** — Run `/fluent-mystique-assess` on the manifest JSON.
+3. **Ask for approval** — Present: setting name, action (CREATE/UPDATE), changes, backup path, rollback instructions. **DO NOT deploy until user approves.**
+
+## Naming & related settings
+- Main: `fc.mystique.manifest.<app>`, Fragments: `fc.mystique.manifest.<app>.fragment.<name>`
+- **No `fc.mystique.apps` setting exists.** Manifest setting pattern: `fc.mystique.manifest.<appName>` where `<appName>` matches the app. Standard: **OMS App** → `fc.mystique.manifest.oms`, **Store App** → `fc.mystique.manifest.store`. Note: the `modules[]` value in workflow user actions comes from each app's `orchestrationAlias` (e.g., `"adminconsole"` for OMS App, `"servicepoint"` for Store App), NOT from the manifest setting suffix.
+- Legacy settings with `RETAILER`/`LOB` — do NOT change without user approval.
+
+## Manifest architecture: root vs fragments (CRITICAL)
+
+**`plugins[]` go ONLY in the root manifest (`fc.mystique.manifest.<app>`), NEVER in fragments.**
+
+| Setting type | Contains | Example |
+|---|---|---|
+| Root manifest (`fc.mystique.manifest.oms`) | `plugins[]` (JS bundles) + `routes[]` (references to fragments) + app shell config | `{ plugins: [{ type: "url", src: "http://localhost:3001/" }], routes: [{ type: "reference", settingName: "...fragment.ordermanagement" }] }` |
+| Fragment (`fc.mystique.manifest.oms.fragment.*`) | `routes[]` ONLY (sections, pages, descendants) — **NO plugins** | `{ manifestVersion: "2.0", routes: [{ type: "section", ... }] }` |
+
+To load a custom JS bundle (FieldRegistry, ComponentRegistry, TemplateRegistry), add it to the **root manifest's** `plugins[]` array. Fragments inherit the loaded bundles — they do NOT load their own.
+
+## Plugin file precedence (CRITICAL)
+
+OMS loads its main manifest from `/_plugins/oms/manifests/fc.mystique.manifest.oms.json`, NOT from the setting. To add custom sections, add them to an existing fragment loaded from settings (ordermanagement, products, stores, admin). You CANNOT add new fragment references to the main manifest. Fragment settings use same rules: `JSON`/`ACCOUNT`/`0`, deploy via `fluent module install --include settings --force`.
+
+## Deployment methods — choosing the right tool
+
+| Need | Tool | Why |
+|---|---|---|
+| **Deploy manifest fragment (10-120KB)** | `fluent module install --include settings --force` | Reads from file — zero LLM context cost. Package in `assets/settings/manifests.json`. |
+| **Quick update to small setting (<4KB)** | MCP `setting_upsert` with explicit `valueType: "JSON"` | Inline in tool params. Fine for root manifest references, feature flags. |
+| **Read/backup existing manifest** | MCP `setting_get` + `outputFile` | Writes to disk, returns metadata only. Saves 30-100K context tokens. |
+| **GraphQL fallback** | `updateSetting` mutation via CLI MCP `graphql_execute` | When other methods unavailable. No response budget limit. |
+
+**NEVER use MCP extension `graphql_query` for manifest settings** — the 50K `FLUENT_RESPONSE_BUDGET_CHARS` silently truncates them.
+
+## Common mistakes
+
+| Mistake | Symptom | Fix |
+|---|---|---|
+| `valueType: "LOB"` or omitted | Manifest loads but routes fail silently | Always set `valueType: "JSON"` explicitly |
+| `JSON.stringify()` on `lobValue` | `"invalid route"` error in Mystique | Pass raw JSON object, never stringified |
+| Body in `value` instead of `lobValue` | Truncated at 255 chars, partial manifest | Always use `lobValue` for manifest content |
+| `plugins[]` in a fragment setting | Plugins silently ignored, components not registered | Move `plugins[]` to root manifest only |
+| `context: "RETAILER"` | Setting not found by Mystique | Always use `context: "ACCOUNT"`, `contextId: 0` |
+| Deploying without backup | No rollback path | Always backup to `accounts/<PROFILE>/manifests/backups/` first |
+
+## Validation checklist
+
+Before deploying any manifest setting:
+
+- [ ] `valueType` is `"JSON"` (not `"LOB"`, not omitted)
+- [ ] `context` is `"ACCOUNT"` and `contextId` is `0`
+- [ ] Body is in `lobValue`, not `value`
+- [ ] `lobValue` is raw JSON (not stringified)
+- [ ] `plugins[]` appear ONLY in the root manifest, not in fragments
+- [ ] Backup saved to `accounts/<PROFILE>/manifests/backups/<name>_<date>.json`
+- [ ] Run `/fluent-mystique-assess` on the manifest JSON
+- [ ] User has explicitly approved the deployment
+
+## Related skills
+
+| Skill | Use for |
+|---|---|
+| `/fluent-mystique-assess` | Validate and analyze manifest JSON (v2.0 schema, ~50 rules across 6 phases) |
+| `/fluent-mystique-builder` | Build or modify manifest fragments safely |
+| `/fluent-mystique-diff` | Compare manifest against CDN baselines |
+| `/fluent-settings` | Manage non-manifest settings |

package/docs/mcp-servers.md

@@ -0,0 +1,209 @@
+# MCP Servers
+
+Four servers in `.mcp.json` (optionally six with Chrome MCP + hosting, DO NOT commit):
+
+| Server | Purpose | Command |
+|--------|---------|---------|
+| **fluent-mcp** | Official Fluent CLI MCP (workflows, GraphQL) | `fluent mcp server --stdio` |
+| **fluent-mcp-extn** | Extension server (55+ tools: events, batch, metrics, entities, workflows, settings, schema, cache, connections, planning) | `node .../fluent-mcp-extn/dist/index.js` |
+| **chrome-devtools** | Browser automation for UI testing | `npx -y chrome-devtools-mcp@latest` |
+| **chrome-manual** | Chrome MCP Extension for manual debugging (optional, opt-in) | `npx -y mcp-chrome-bridge http://127.0.0.1:12306/mcp` |
+| **bitbucket** | Bitbucket code repository access | `npx -y @nexus2520/bitbucket-mcp-server` |
+| **vercel** (optional) | Hosting/deployment for frontend assets (S3, Netlify, etc. also work) | `https://mcp.vercel.com` (remote HTTP + OAuth) |
+
+First three auto-configured by `fluent-ai-skills install --profile <PROFILE>`. Chrome MCP Extension added with `--with-chrome` flag (requires Chrome extension from https://github.com/hangwin/mcp-chrome). Bitbucket requires manual configuration. Hosting MCP (Vercel/S3/etc.) is optional — see [Optional Hosting MCP Servers](#optional-hosting-mcp-servers) below. Auth: `FLUENT_PROFILE` (recommended) → OAuth → Token Command → Static Token. Never put secrets in `.mcp.json` — use environment variables. `FLUENT_UI_BASE_URL` points to target Fluent UX app; set via `--browser-url` or `--no-browser` to skip.
+
+**Multi-profile auth note:** auth priority is evaluated per connection slot, not once for the whole server. One session can mix CLI-profile, explicit OAuth, and explicit static-token slots. Runtime `connection_add` supports CLI profile, OAuth, and static token; `TOKEN_COMMAND` remains startup-only.
+
+**Naming note:** canonical `fluent-mcp-extn` tool names are underscore-first, such as `health_ping`, `graphql_query`, and `workflow_transitions`. The extension still accepts legacy dotted calls like `health.ping` for backward compatibility, but new docs and prompts should prefer underscore names.
+
+## Generated `.mcp.json` Structure
+
+Running `install --profile MY_PROFILE` or `mcp-setup --profile MY_PROFILE` generates a `.mcp.json` like this:
+
+```json
+{
+  "mcpServers": {
+    "fluent-mcp": {
+      "type": "stdio",
+      "command": "fluent",
+      "args": ["mcp", "server", "--stdio"],
+      "env": {
+        "FLUENT_PROFILE": "MY_PROFILE"
+      }
+    },
+    "fluent-mcp-extn": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@fluentcommerce/fluent-mcp-extn"],
+      "env": {
+        "FLUENT_PROFILE": "MY_PROFILE",
+        "FLUENT_PROFILE_RETAILER": "MY_RETAILER_REF"
+      }
+    },
+    "chrome-devtools": {
+      "command": "npx",
+      "args": ["-y", "chrome-devtools-mcp@latest", "--user-data-dir=/home/user/.chrome-mcp-profile"],
+      "env": {
+        "FLUENT_UI_BASE_URL": "https://account.env.apps.engineering.fluentcommerce.com"
+      }
+    }
+  }
+}
+```
+
+**Key environment variables in `.mcp.json`:**
+
+| Variable | Server | Purpose |
+|----------|--------|---------|
+| `FLUENT_PROFILE` | both | Points to `~/.fluentcommerce/<PROFILE>/` for auth. **Change this to switch environments.** |
+| `FLUENT_PROFILE_RETAILER` | extn | Retailer ref for scoped operations. Optional — omit to select interactively. |
+| `FLUENT_PROFILES_FILE` | extn | Path to `fluent-profiles.json` for multi-profile switching at runtime. |
+| `FLUENT_CACHE_ENABLED` | extn | `"true"` enables in-memory caching (auto-set with multi-profile). Recommended for all setups. |
+| `FLUENT_UI_BASE_URL` | chrome-devtools | Target UX app URL for browser testing. Set via `--browser-url`. |
+| `FLUENT_RESPONSE_BUDGET_CHARS` | extn | Max response size (default 50K). Do not increase — use `outputFile` for large payloads. |
+
+## Switching Environments / Profiles
+
+### Quick switch (single profile)
+
+Edit `.mcp.json` and change `FLUENT_PROFILE` in **both** server entries, then restart your IDE:
+
+```bash
+# Or regenerate entirely:
+npx @fluentcommerce/ai-skills mcp-setup --profile STAGING_PROFILE --profile-retailer STAGING_RETAILER
+```
+
+### Runtime switch (multi-profile)
+
+Set up multi-profile once:
+
+```bash
+# Auto-discover all profiles from ~/.fluentcommerce/:
+npx @fluentcommerce/ai-skills mcp-setup --profile MY_PROFILE --discover-profiles
+
+# Or point to an existing profiles file:
+npx @fluentcommerce/ai-skills mcp-setup --profile MY_PROFILE --profiles-file ./fluent-profiles.json
+```
+
+The `fluent-profiles.json` format:
+
+```json
+[
+  { "profile": "DEV_PROFILE", "retailer": "DEV_RETAILER_REF" },
+  { "profile": "STAGING_PROFILE", "retailer": "STAGING_RETAILER_REF" },
+  { "profile": "PROD_PROFILE" }
+]
+```
+
+Then switch at runtime without restarting the IDE:
+
+```
+List available connections     → MCP connection_list
+Switch to staging             → MCP connection_switch({ profile: "STAGING_PROFILE" })
+```
+
+Multi-profile automatically enables `FLUENT_CACHE_ENABLED: "true"` and wires the profiles file into the extension server.
+
+You can also add slots at runtime:
+
+```
+Add OAuth slot                 → MCP connection_add({ name: "PROD_READONLY", baseUrl: "...", clientId: "...", clientSecret: "..." })
+Add static token slot          → MCP connection_add({ name: "QUICK_TEST", baseUrl: "...", accessToken: "..." })
+```
+
+### Merge behavior
+
+Running `mcp-setup` **merges** into the existing `.mcp.json` — it updates the three managed servers (`fluent-mcp`, `fluent-mcp-extn`, `chrome-devtools`) but preserves any custom servers you added (e.g., `bitbucket`, `vercel`). Safe to re-run.
+
+### Without `--profile`
+
+Running `install` without `--profile` installs skills but generates `.mcp.json` with placeholder values (`YOUR_ACCOUNT`, `YOUR_RETAILER`). You must run `mcp-setup --profile <NAME>` afterwards to wire real credentials.
+
+## Click Telemetry (Visual Click Highlights)
+
+Chrome DevTools MCP clicks are programmatic — no visible cursor appears. Click Telemetry injects JavaScript highlights (pulsing red border + label badge) around elements before interactions. This makes screenshots and screencast recordings self-documenting. Implemented in `/fluent-ui-test` (Phase 4) and `/fluent-ui-record` (full protocol). See `chrome-devtools-mcp-reference.md` (in `@fluentcommerce/ai-skills` docs) for full browser MCP reference.
+
+**Token optimization:** Both skills inject a `__fcTest` helper library once per session (see `BROWSER_OPTIMIZATIONS.md` in the `fluent-ui-test` skill). This replaces `take_snapshot` (~30K tokens) with `pageSummary()` (~500 tokens) for page verification, `scanComponents()` (~400 tokens) for custom component detection, and one-line `highlight()`/`annotate()` calls (~100 tokens each) instead of inline 40-line JS blocks. ~90% token reduction per test session. Component compatibility matrix covers OOTB Mystique components AND custom SDK components.
+
+## Setting & Manifest Fetch — Tool Routing
+
+Choose the right tool based on payload size and purpose:
+
+| Need | Tool | Why |
+|------|------|-----|
+| **Download manifest/large setting** | MCP `setting_get` + `outputFile` | Writes 10-120KB to disk, returns ~200 bytes metadata. Saves 30-100K tokens per call. |
+| **Existence check (does setting exist?)** | MCP `setting_get` (no outputFile) | Returns metadata inline. Do NOT request `lobValue` in GraphQL fallback. |
+| **Bulk discovery (all manifests)** | MCP `setting_get` with `name: "fc.mystique.manifest.%"` + `outputFile` (directory) | One call discovers all, saves each to file. |
+| **GraphQL with large response** | Official CLI MCP `graphql_execute` (no response budget) | Fallback when `setting_get` unavailable. |
+| **Small GraphQL queries** | MCP extension `graphql_query` | Fine for queries under 50K chars response. |
+| **Workflow download** | CLI `fluent workflow download` or MCP `workflow_get` with `outputFile` | Keeps 50K+ workflow JSON out of context. |
+
+**NEVER use MCP extension `graphql_query` for manifest settings** — the 50K `FLUENT_RESPONSE_BUDGET_CHARS` silently truncates them. Use `setting_get` + `outputFile` (preferred) or official CLI MCP `graphql_execute` (fallback).
+
+## Setting & Manifest Write — Tool Routing
+
+Choose the right tool for **writing** settings based on payload size:
+
+| Need | Tool | Why |
+|------|------|-----|
+| **Deploy large setting (>4KB)** | CLI `fluent module install --include settings --force` | Reads JSON from local file — zero LLM context cost. Recommended for manifest fragments (10-120KB). Package in `assets/settings/manifests.json` as JSON array. |
+| **Deploy multiple settings at once** | CLI `fluent module install --include settings --force` | One command, all settings in one `manifests.json` array. Atomic deploy. |
+| **Quick update small setting (<4KB)** | MCP `setting_upsert` | Inline in tool params. Fine for root manifests, feature flags, small configs. Always set `valueType: "JSON"` for manifests. |
+| **CI/CD pipeline deploy** | CLI `fluent module install --include settings` | Versioned, supports `[[token]]` config placeholders, audit trail. |
+| **GraphQL fallback** | `updateSetting` mutation via CLI MCP `graphql_execute` | When CLI module install unavailable. No response budget limit. |
+
+**NEVER use MCP `setting_upsert` for large settings (manifests >4KB)** — stuffing 10-120KB into a tool parameter wastes LLM context tokens. Use CLI `fluent module install` which reads from disk.
+
+**CLI deploy pattern for settings:**
+```bash
+DEPLOY=$(mktemp -d)
+mkdir -p "$DEPLOY/assets/settings"
+# manifests.json = JSON array of setting objects
+cat > "$DEPLOY/assets/settings/manifests.json" << 'SETTINGS'
+[{ "name": "fc.mystique.manifest.oms.fragment.ordermanagement",
+   "valueType": "JSON", "context": "ACCOUNT", "contextId": 0,
+   "lobValue": <content-from-local-file> }]
+SETTINGS
+echo '{"_schema":"1.0.0","name":"settings-deploy","version":"1.0.0"}' > "$DEPLOY/module.json"
+echo '{}' > "$DEPLOY/module.config.json"
+fluent module install "$DEPLOY" -p <PROFILE> -r <RETAILER> --include settings --force
+rm -rf "$DEPLOY"
+```
+
+## Optional Hosting MCP Servers
+
+An optional hosting MCP server can deploy frontend assets (Mystique SDK bundles, static files) to CDN/hosting platforms. **Not required** for core Fluent Commerce work — only needed when you host custom frontend components.
+
+| Provider | MCP URL / Package | Auth |
+|----------|-------------------|------|
+| **Vercel** | `https://mcp.vercel.com` (remote HTTP) | OAuth (browser) |
+| **AWS S3** | Community MCP servers (e.g., `mcp-server-s3`) | AWS credentials |
+| **Netlify** | Community MCP servers | API token |
+| **Cloudflare** | Community MCP servers | API token |
+
+### Vercel Setup
+
+Add to `.mcp.json`:
+```json
+{ "mcpServers": { "vercel": { "type": "http", "url": "https://mcp.vercel.com" } } }
+```
+
+For project-specific access: `"url": "https://mcp.vercel.com/<teamSlug>/<projectSlug>"`. Authenticate via `/mcp` in Claude Code (opens browser OAuth). Find slugs: Vercel Dashboard or `vercel projects ls`.
+
+### S3 Setup
+
+```json
+{ "mcpServers": { "s3": { "type": "stdio", "command": "npx", "args": ["-y", "mcp-server-s3"],
+  "env": { "AWS_ACCESS_KEY_ID": "<from env>", "AWS_SECRET_ACCESS_KEY": "<from env>", "AWS_REGION": "ap-southeast-2", "S3_BUCKET": "your-bucket-name" } } } }
+```
+
+**Notes:** Hosting MCP is optional and gitignored. Each developer configures their own provider. The installer does NOT auto-configure hosting MCPs. Never put secrets in `.mcp.json`.
+
+---
+
+## Related Docs
+
+- [INDEX.md](INDEX.md) — Documentation reading order
+- [Setup Reference & Troubleshooting](05-getting-started.md) — MCP troubleshooting steps
+- [Chrome DevTools MCP](chrome-devtools-mcp-reference.md) — Browser automation server reference

package/docs/workflow-reference.md

@@ -0,0 +1,167 @@
+# Workflow Reference
+
+## Workflow Upload — Strict Reference
+
+**`fluent workflow upload` DOES NOT EXIST.** CLI only has: `workflow list`, `workflow download`, `workflow merge`. Never invent a workflow upload command.
+
+### Method 1 — CLI `fluent module install` (RECOMMENDED)
+
+```bash
+DEPLOY=$(mktemp -d)
+mkdir -p "$DEPLOY/assets/workflows"
+cp <WORKFLOW>.json "$DEPLOY/assets/workflows/"
+echo '{"_schema":"1.0.0","name":"wf-deploy-tmp","version":"1.0.0"}' > "$DEPLOY/module.json"
+echo '{}' > "$DEPLOY/module.config.json"
+fluent module install "$DEPLOY" -p <PROFILE> -r <RETAILER> --include workflows --force
+rm -rf "$DEPLOY"
+```
+
+Updates both live server and workflowlog. Filename uses `-` not `::` (e.g., `ORDER-HD.json`). Use `--config <path>` for `[[token]]` placeholders. **Config keys MUST use `default:` prefix** (e.g., `"default:retailerId": "2"`) — unscoped keys are silently ignored.
+
+### Method 2 — MCP `workflow_upload` (when available)
+
+`workflow_upload({ workflow, retailerId, validate: true, dryRun: false })` — bypasses workflowlog (CLI downloads will be stale).
+
+### Method 3 — REST API direct (last resort)
+
+`POST /api/v4.1/workflow/<retailerId>` with workflow JSON body + `Authorization: Bearer $TOKEN` + `fluent.account: $ACCOUNT_ID`. Also bypasses workflowlog.
+
+### Version rules
+
+Version must always increase — Fluent rejects same or lower. To "rollback," upload old content with a new higher version.
+
+## Workflow User Actions — Strict Reference
+
+User actions link UI buttons to workflow rulesets via `/event/sync`.
+Canonical reference: `knowledge/platform/user-action-contract.md` (copied to your workspace by the installer).
+
+### Mandatory fields (all required for button visibility)
+
+| Field | Description |
+|-------|-------------|
+| `eventName` | Event sent on click. **Without it, button silently invisible.** |
+| Ruleset `subtype` | Must match workflow `entitySubtype`. **#1 cause of missing buttons.** |
+| `context[].label` | Button text |
+| `context[].type` | `"PRIMARY"` or `"SECONDARY"` (uppercase) |
+| `context[].modules` | Target app module aliases. **OMS app uses legacy alias `"adminconsole"`, NOT `"oms"`** (the OMS manifest sets `orchestrationAlias: "adminconsole"`). **Store app uses legacy alias `"servicepoint"`**. These are deprecated internal names — always present as "OMS app" / "Store app" to users. Empty `[]` = invisible. |
+| `context[].confirm` | Boolean, NOT string `"true"` |
+
+### Attribute poisoning (CORRECTED)
+
+Attributes with `source: "OVERRIDE"` and `defaultValue: "{{me.username}}"` work fine on v4.80+. Original breakage was caused by missing `subtype` on the ruleset, NOT attribute values. Safe practice: ensure `source: ""`, `defaultValue: ""` for predictability.
+
+### Settings-driven dropdown contract
+
+When `source: "settings.<KEY>"` is used in a user action attribute, the UI populates a dropdown from the named setting. Three silent-failure gotchas:
+1. **lowercase `settings.`** — `"settings.CANCELLATION_REASON"` works, `"Settings.CANCELLATION_REASON"` (capital S) silently fails. No error.
+2. **`"active"` wrapper key** — Setting value MUST be `{ "active": [{ "name": "Display", "value": "CODE" }] }`. Plain array silently fails.
+3. **Retailer context match** — Setting retailer scope must match the workflow's retailer.
+
+### Edge cases
+- **Transition API parameters**: `module` is required, and `module: "all"` returns NOTHING. `flexType` is required by the API, but MCP `workflow_transitions` auto-derives it from `type` + `subtype` when omitted (e.g., `type: "ORDER"` + `subtype: "HD"` → `flexType: "ORDER::HD"`). `flexVersion` is strongly recommended and required for some entity types. All rules treated equally regardless of plugin origin — NO "OOTB vs custom" distinction.
+- **Multi-entity workflows** (ORDER::MULTI): Transition API works for ORDER::MULTI — specify correct `type: "ORDER"`, `subtype: "MULTI"`, `retailerId`, `module: "adminconsole"` (OMS app legacy alias), `flexType: "ORDER::MULTI"`, and `flexVersion`. If results are empty, debug: (1) missing mandatory params, (2) missing `eventName`, (3) missing `subtype` on ruleset, (4) wrong `modules` value.
+- **Parent-child entities**: Child entities inherit `workflowRef` from parent. The Transition API accepts BOTH the standalone child workflow name AND the parent workflow name as `flexType` — use the matching `flexVersion` for whichever you specify. The UI sends the entity's `workflowRef` (parent workflow) as `flexType`.
+- **Verification**: Always check via `workflow_transitions` after deploy. Debug order: (1) specific module present, (2) flexType present or auto-derived, (3) flexVersion for entity types that need it, (4) eventName, (5) subtype, (6) modules, (7) parent workflow for children. See `/fluent-workflow-builder` for full UA01-UA19 checklist.
+- **Custom component override**: Two patterns: (A) Field-level — custom FieldRegistry type, replaces one field, zero risk. (B) Full-form — replaces entire form, must dispatch ALL `@EventAttribute` names. Backend agnostic if event shape preserved. See `knowledge/platform/user-action-contract.md` §9 (copied to your workspace by the installer).
+
+## Workflow Caching & Staleness
+
+Three independent caching layers affect workflows. Understanding which is stale prevents the most common "my deploy didn't work" confusion.
+
+### Layer 1 — MCP Extension Server Cache (runtime)
+
+The MCP extension server caches workflow reads, settings, and GraphQL schema introspection in-memory/on-disk. Enabled automatically when `FLUENT_CACHE_ENABLED=true` is set (auto-configured during multi-profile `mcp-setup`).
+
+| Tool | What it does |
+|------|-------------|
+| `cache_status` | Shows enabled/disabled, entry count, hit/miss rate, per-category breakdown |
+| `cache_clear` | Clears entries by pattern (omit pattern to clear everything) |
+
+Common clear patterns:
+
+```
+cache_clear({ pattern: "workflow:*" })         # workflow list/get
+cache_clear({ pattern: "setting:get:fc.mystique.*" })  # manifests/settings
+cache_clear({ pattern: "introspect:*" })       # GraphQL schema
+cache_clear()                                  # everything
+```
+
+**When to clear:** After deploying workflows or settings via CLI or REST, and the MCP tools still return old data.
+
+### Layer 2 — Local Workflow Files (workspace)
+
+Workflows downloaded by `/fluent-connect` or `/fluent-workflow` live in `accounts/<PROFILE>/workflows/<RETAILER>/`. These are static files — they do not auto-update when you deploy.
+
+| Mechanism | Details |
+|-----------|---------|
+| **Content hash check** | `/fluent-connect` computes a hash of workspace state. If unchanged since last run, it skips re-downloading. Use `--force` to override. |
+| **7-day staleness hint** | If the most recent workflow file is older than 7 days, `/fluent-connect` suggests re-downloading. |
+| **`workflow-context.json`** | Tracks which profile/retailer the local files belong to. If you switch profiles, workflows are re-downloaded into the correct folder. |
+| **`workflow-file-map.json`** | Maps workflow names (with `::`) to sanitized filenames (with `__`). Used by analyzer and builder skills to resolve files cross-platform. |
+
+**How to refresh local files:**
+
+```bash
+# Option A: Re-run connect with --force
+/fluent-connect --profile MY_PROFILE --force
+
+# Option B: Download specific workflow via MCP (reads live server, not workflowlog)
+# In Claude Code chat:
+Download the ORDER::HD workflow to the local workspace
+
+# Option C: CLI download (reads workflowlog — see Layer 3 caveat)
+fluent workflow download -p MY_PROFILE -r "My Retailer" -w all \
+  -o accounts/MY_PROFILE/workflows/"My Retailer"/
+```
+
+**When to refresh:** After deploying workflow changes (especially via MCP or REST), before running `/fluent-workflow-analyzer` or `/fluent-workflow-builder` on local files.
+
+### Layer 3 — Fluent CLI Workflowlog (server-side)
+
+The Fluent CLI maintains a **workflowlog** — a server-side change history that `fluent workflow download` reads from. This is NOT the live workflow; it's a log of CLI-originated changes.
+
+**Critical gotchas:**
+
+| Scenario | What happens | Fix |
+|----------|-------------|-----|
+| Deploy via MCP `workflow_upload` | Workflowlog not updated. CLI downloads return **stale** pre-upload version. | `fluent workflowlog delete` all positions, then redeploy via CLI. Or use MCP `workflow_get` / `workflow_list` which read live server. |
+| Deploy via REST API | Same as MCP — workflowlog bypassed. | Same fix. |
+| Failed CLI deploy | CLI writes workflowlog entries **even on failure**. Subsequent retries may conflict ("workflowlog poisoning"). | `fluent workflowlog delete` stale positions, then retry. |
+| Deploy via CLI `module install` | Workflowlog updated correctly. CLI downloads are current. | No action needed. |
+
+**How to check if workflowlog is stale:**
+
+```bash
+# Compare live version (MCP) vs workflowlog version (CLI)
+# In Claude Code chat:
+Get the live ORDER::HD workflow version via MCP, then compare with local file version
+```
+
+### Troubleshooting — "My workflow deploy didn't take effect"
+
+Follow this sequence:
+
+1. **Check live server first** — Use MCP `workflow_get` (reads live, not cache). If the change is there, it deployed fine.
+2. **Clear MCP cache** — `cache_clear({ pattern: "workflow:*" })`. Re-query.
+3. **Check local files** — Are your `accounts/<PROFILE>/workflows/` files stale? Re-download with `/fluent-connect --force` or MCP `workflow_list` with `outputDir`.
+4. **Check workflowlog** — If you deployed via MCP/REST but CLI downloads show old data, the workflowlog is stale. Fix with `fluent workflowlog delete`.
+5. **Check Transition API cache** — After rapid deploys, the Transition API may cache a stale `flexVersion`. Always specify the exact deployed version in Transition API queries.
+
+## ORDER::MULTI Workflow — Test Reference
+
+Key points:
+- Canonical `createOrder` contract: `knowledge/platform/create-order-reference.md` (copied to your workspace by the installer)
+- Order `type` must be `"MULTI"` (not `"HD"`)
+- On mutation input, items MUST include `fulfilmentChoiceRef` to link to FC
+- On readback queries, verify the link via `items[].fulfilmentChoice { ... }` — do not expect an `OrderItem.fulfilmentChoiceRef` scalar
+- FC needs `sourcingLocationRef` attribute
+- FC `type` (routing) ≠ fulfilment `type` (created fulfilment)
+- Flow: `CREATE` → `SkipFraudCheck` → `ON_VALIDATION` → `ConfirmValidation` → `ProcessOrder` → `RouteFulfilmentChoice` → `ProcessHDFulfilmentChoice` → `CreateFulfilmentFromSourcingLocation`
+
+---
+
+## Related Docs
+
+- [INDEX.md](INDEX.md) — Documentation reading order
+- [Development Workflow](06-dev-workflow.md) — Full lifecycle protocol including deploy and rollback
+- [Use Cases — Deploy Safely](03-use-cases.md#scenario-8-deploy-a-workflow-change-safely) — Step-by-step deployment scenario

package/lib/fluent-brand.css

@@ -0,0 +1,55 @@
+/*
+ * ═══════════════════════════════════════════════════════════
+ *  FLUENT COMMERCE — OFFICIAL BRAND TOKENS (shared)
+ *
+ *  Source of truth for CSS custom properties used by:
+ *  - presentations/ai-skills-mcp/presentation.html
+ *  - evals/playground (inlined via template.mjs)
+ *
+ *  Palette provenance: fluentcommerce.com logo / site (see presentation deck comment).
+ * ═══════════════════════════════════════════════════════════
+ *
+ *  Cyan (primary):   #00C2EF  — Logo + CTAs
+ *  Purple (accent):  #8F0CF4  — Logo accent + interactive
+ *  Purple (mid):     #552ABB  — Website interactive states
+ *  Dark (deep bg):   #18013A  — Logo dark / deep backgrounds
+ *  Dark (mid bg):    #26005C  — Website dark purple
+ *
+ *  Functional: Coral #FF6B6B | Green #51CF66 | Amber #FFD43B
+ * ═══════════════════════════════════════════════════════════
+ */
+
+:root {
+  /* ── Brand: Cyan (primary accent) ── */
+  --fc-teal: #00C2EF;
+  --fc-teal-dark: #00A3C8;
+  --fc-teal-deeper: #0088A8;
+  /* ── Brand: Dark backgrounds ── */
+  --fc-navy: #18013A;
+  --fc-navy-mid: #26005C;
+  --fc-navy-light: #3A1070;
+  /* ── Functional accents ── */
+  --fc-coral: #FF6B6B;
+  --fc-coral-light: #FF8787;
+  --fc-green: #51CF66;
+  --fc-green-dark: #2B8A3E;
+  --fc-amber: #FFD43B;
+  /* ── Brand: Purple (accent) ── */
+  --fc-purple: #8F0CF4;
+  /* ── Neutrals (dark UI text on navy) ── */
+  --fc-white: #FFFFFF;
+  --fc-ghost: rgba(255,255,255,0.05);
+  --fc-glass: rgba(24,1,58,0.85);
+  --fc-text-dim: rgba(255,255,255,0.5);
+  --fc-text-mid: rgba(255,255,255,0.72);
+  /* ── Light-mode surfaces ── */
+  --fc-paper: #FFFFFF;
+  --fc-paper-soft: #F5F0FD;
+  --fc-lilac: #F7F2FF;
+  --fc-ink: #18013A;
+  --fc-ink-soft: #5A4A78;
+  --fc-border-light: rgba(24,1,58,0.10);
+  /* ── Layout (deck defaults; eval-playground overrides --sidebar-w in its own :root) ── */
+  --sidebar-w: 260px;
+  --section-max: 1100px;
+}

package/metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.12.0",
+  "version": "0.14.0",
   "organization": "Fluent Commerce",
   "date": "March 2026",
   "package": "@fluentcommerce/ai-skills",
@@ -112,7 +112,7 @@
         "fluent-feature-status",
         "fluent-rollback",
         "fluent-workspace-tree",
-        "fluent-source-onboard",
+        "fluent-module-convert",
         "fluent-use-case-discover",
         "fluent-sourcing",
         "fluent-data-module-scaffold",
@@ -166,7 +166,7 @@
         "/fluent-feature-status",
         "/fluent-rollback",
         "/fluent-workspace-tree",
-        "/fluent-source-onboard",
+        "/fluent-module-convert",
         "/fluent-use-case-discover",
         "/fluent-sourcing",
         "/fluent-data-module-scaffold",
@@ -211,7 +211,7 @@
     "fluent-build": "advisory",
     "fluent-frontend-build": "advisory",
     "fluent-pre-deploy-check": "advisory",
-    "fluent-source-onboard": "advisory",
+    "fluent-module-convert": "mandatory",
     "fluent-inventory-catalog": "mandatory",
     "fluent-goal": "mandatory"
   },
@@ -232,7 +232,7 @@
     "fluent-build",
     "fluent-frontend-build",
     "fluent-pre-deploy-check",
-    "fluent-source-onboard",
+    "fluent-module-convert",
     "fluent-inventory-catalog",
     "fluent-goal",
     "fluent-rule-test",
@@ -256,7 +256,8 @@
     "fluent-skill-routing-report": { "target": "fluent-skill-observability", "since": "0.12.0" },
     "fluent-feedback": { "target": "fluent-skill-observability", "since": "0.12.0" },
     "fluent-feature-phase": { "target": "fluent-scope-plan", "since": "0.12.0" },
-    "fluent-scope-decompose": { "target": "fluent-scope-plan", "since": "0.12.0" }
+    "fluent-scope-decompose": { "target": "fluent-scope-plan", "since": "0.12.0" },
+    "fluent-source-onboard": { "target": "fluent-module-convert", "since": "0.13.0" }
   },
   "references": [
     "https://docs.fluentcommerce.com",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluentcommerce/ai-skills",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "[Experimental] Fluent Commerce domain knowledge for Claude Code. Skills, agents, and MCP server configs for workflows, events, rules, and APIs.",
   "keywords": [
     "fluent-commerce",
@@ -33,18 +33,20 @@
     "test:evals:routing": "node evals/harness/runtime.mjs --suite routing --executor evals/executors/replay.mjs",
     "test:evals:routing-live": "node evals/harness/runtime.mjs --suite routing-live --executor evals/executors/codex-live.mjs",
     "test:evals:runtime-live": "node evals/harness/runtime.mjs --suite runtime-live --executor evals/executors/codex-live.mjs",
+    "test:evals:execution": "node evals/harness/runtime.mjs --suite execution --executor evals/executors/codex-live.mjs",
     "test:evals:runtime-live-sandbox": "node evals/harness/runtime.mjs --suite runtime-live-sandbox --executor evals/executors/codex-live.mjs",
     "test:evals:agent-routing": "node evals/harness/runtime.mjs --suite agent-routing --executor evals/executors/replay.mjs",
     "test:evals:agent-routing-live": "node evals/harness/runtime.mjs --suite agent-routing-live --executor evals/executors/codex-live.mjs",
     "test:evals:adversarial": "node evals/harness/runtime.mjs --suite adversarial --executor evals/executors/replay.mjs",
     "test:evals:routing-live:claude": "node evals/harness/runtime.mjs --suite routing-live --executor evals/executors/claude-live.mjs",
+    "test:evals:routing-live:sdk": "node evals/harness/runtime.mjs --suite routing-live --executor evals/executors/claude-sdk.mjs",
     "test:evals:skill-runtime": "node evals/harness/runtime.mjs --suite skill-runtime --executor evals/executors/replay.mjs",
     "test:evals:tool-behavior": "node evals/harness/runtime.mjs --suite tool-behavior --executor evals/executors/replay.mjs",
     "test:evals:chains": "node evals/harness/runtime.mjs --suite chains --executor evals/executors/replay.mjs",
     "test:evals:cases": "npm run test:evals:routing && npm run test:evals:agent-routing && npm run test:evals:adversarial && npm run test:evals:skill-runtime && npm run test:evals:tool-behavior && npm run test:evals:chains",
     "test:evals:core": "npm run test:evals:static && npm run test:evals:runtime && npm run test:evals:cases",
     "test:evals:full": "npm run test:evals:core && npm run test:evals:live",
-    "test:evals:live": "npm run test:evals:routing-live && npm run test:evals:runtime-live",
+    "test:evals:live": "npm run test:evals:routing-live && npm run test:evals:runtime-live && npm run test:evals:execution",
     "test:evals": "npm run test:evals:core",
     "eval:prompt": "node evals/harness/prompt-analyze.mjs",
     "eval:batch": "node evals/harness/prompt-batch.mjs",
@@ -54,9 +56,17 @@
     "eval:run:sandbox": "node evals/scripts/run-live-evals.mjs --suite runtime-live-sandbox --executor evals/executors/codex-live.mjs",
     "eval:run:tools": "FLUENT_EVAL_ENABLE_MCP=1 node evals/scripts/run-live-evals.mjs --suite tool-behavior --executor evals/executors/claude-live.mjs",
     "eval:report": "node evals/scripts/eval-report.mjs",
+    "eval:promptfoo:generate": "node evals/promptfoo/generate.mjs",
+    "eval:promptfoo": "node evals/promptfoo/generate.mjs && npx promptfoo eval -c evals/promptfoo/promptfooconfig.yaml",
+    "eval:promptfoo:view": "npx promptfoo view",
+    "eval:playground": "node evals/playground.mjs",
+    "eval:playground:dev": "node --watch evals/playground.mjs",
+    "playground": "node evals/playground.mjs",
+    "playground:dev": "node --watch evals/playground.mjs",
     "test:parallel": "node scripts/test-parallel.mjs",
     "test:parallel:quick": "node scripts/test-parallel.mjs --quick",
     "test": "npm run test:smoke && npm run test:pack && npm run test:unit && npm run test:evals:core",
+    "postinstall": "node scripts/postinstall.mjs || true",
     "prepublishOnly": "npm test"
   },
   "type": "module",
@@ -72,10 +82,14 @@
     "!content/**/.claude-plugin",
     "docs/",
     "lib/",
+    "scripts/postinstall.mjs",
     "tools/",
     "!tools/vendor/",
     "metadata.json",
     "README.md",
     "LICENSE"
-  ]
+  ],
+  "optionalDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.87"
+  }
 }