@fluentcommerce/ai-skills 0.14.0 → 0.15.0

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

@@ -1,12 +1,13 @@
 ---
 name: fluent-frontend-readme
-description: "README.md GENERATOR for SDK projects — reads actual TypeScript/React source code and writes a README.md file with component registrations, build instructions, settings dependencies, and deployment guide. This skill writes documentation files, NOT manifest analysis. Does NOT audit code quality (→ fluent-frontend-review), does NOT analyze manifest JSON health (→ fluent-mystique-assess). ROUTING — This generates README.md documentation for SDK component projects. It does NOT analyze manifest complexity (use fluent-mystique-assess). Triggers on 'generate readme', 'document components', 'SDK readme', 'component documentation'. ROUTING PRIORITY — if the prompt says \"generate README\", \"write readme\", \"document component registrations\", \"SDK readme\", \"README for SDK project\", \"create documentation\", \"build instructions\", \"settings dependencies\", or \"document registrations\", route HERE — do NOT route to fluent-mystique-assess. fluent-mystique-assess reads manifest JSON for complexity scoring; this skill reads .ts/.tsx source files and writes a README.md. Triggers on \"generate readme\", \"document component\", \"frontend readme\", \"sdk readme\", \"component docs\", \"write readme\", \"create documentation\", \"README for SDK project\", \"document registrations\", \"README.md\", \"build instructions\", \"settings dependencies\", \"generate README.md for SDK project\". ROUTING PRIORITY for frontend documentation — route here instead of fluent-mystique-assess when prompt asks about generating README, docs, or documentation for a Mystique/frontend project."
+description: README.md generator for SDK projects that reads TypeScript/React source code and writes documentation with component registrations, build instructions, and deployment guide. Use for generating frontend project README or SDK documentation.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [project-path]
 cursor-tier: auto
 planning-gate: none
 ---
+<!-- routing-notes: ROUTING PRIORITY — if the prompt says "generate README", "write readme", "SDK readme", or "README for SDK project", route HERE — do NOT route to fluent-mystique-assess. fluent-mystique-assess reads manifest JSON for complexity scoring; this skill reads .ts/.tsx source files and writes a README.md. Does NOT audit code quality (→ fluent-frontend-review), does NOT analyze manifest JSON health (→ fluent-mystique-assess). -->
 
 # Frontend README Generator
 

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

@@ -1,12 +1,13 @@
 ---
 name: fluent-frontend-review
-description: "SDK SOURCE CODE quality audit — reviews TypeScript/React .ts/.tsx files for strictness, React anti-patterns, SDK compliance, GraphQL schemas, test quality, and bundle size. Frontend equivalent of /fluent-custom-code. Audits SDK project source files (.ts, .tsx, package.json, webpack config) — does NOT analyze manifest JSON health (→ fluent-mystique-assess) and does NOT validate manifest schema (→ fluent-mystique-assess). ROUTING — This runs code quality review: TypeScript quality, React patterns, SDK compliance, test coverage audit. It does NOT validate manifest JSON schema (use fluent-mystique-assess). Triggers on 'code review', 'quality audit', 'review SDK code', 'frontend code patterns'. ROUTING PRIORITY — if the prompt says \"review frontend\", \"code quality audit\", \"frontend review\", \"TypeScript strictness\", \"React anti-patterns\", \"React patterns\", \"SDK compliance\", \"review source code\", \"audit SDK project\", or \"bundle size\", route HERE — do NOT route to fluent-mystique-assess. fluent-mystique-assess checks manifest JSON schema; this skill audits .ts/.tsx source files for code quality. Triggers on \"review frontend\", \"code quality\", \"frontend review\", \"review component\", \"audit sdk\", \"check quality\", \"TypeScript strictness\", \"React anti-patterns\", \"React patterns\", \"SDK compliance\", \"review source code\", \"bundle size\", \"code review\", \"quality audit\", \"review SDK code\", \"frontend code patterns\". ROUTING PRIORITY for source code quality — route here instead of fluent-mystique-assess when prompt asks about TypeScript/React code quality, code review, or source file auditing."
+description: SDK source code quality audit for TypeScript/React files covering strictness, React anti-patterns, SDK compliance, GraphQL schemas, test quality, and bundle size. Use for frontend code review or SDK project audits.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [project-path]
 cursor-tier: manual
 planning-gate: none
 ---
+<!-- routing-notes: ROUTING PRIORITY — if the prompt says "review frontend", "code quality audit", "frontend review", "TypeScript strictness", "React anti-patterns", "SDK compliance", "review source code", or "bundle size", route HERE — do NOT route to fluent-mystique-assess. fluent-mystique-assess checks manifest JSON schema; this skill audits .ts/.tsx source files for code quality. Does NOT analyze manifest JSON health (→ fluent-mystique-assess). -->
 
 # Frontend Code Review
 

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

@@ -1,6 +1,6 @@
 ---
 name: fluent-goal
-description: "Goal-directed autonomous orchestrator. Takes any Fluent Commerce goal, decomposes into verifiable sub-goals, delegates to existing skills, verifies outcomes via MCP, self-critiques, adjusts approach, and persists until the goal is met or genuinely blocked. Triggers on 'make it work', 'keep going until', 'get this working', 'resolve end to end', 'fix until done', 'goal:', 'achieve', 'pursue goal'."
+description: Goal-directed autonomous orchestrator that decomposes any Fluent Commerce goal into verifiable sub-goals, delegates to skills, and verifies outcomes via MCP. Use when pursuing an end-to-end goal autonomously.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: "<goal in plain English>" [--autonomy guided|gated|autonomous] [--max-attempts 3] [--entity-ref <ref>]

package/content/dev/skills/fluent-implementation-map/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-implementation-map
-description: Reverse-engineer an entire Fluent Commerce implementation into a feature inventory with end-to-end flow diagrams, cross-feature dependency maps, customisation scoring, and gap analysis. Triggers on "implementation map", "what's been built", "analyze implementation", "reverse engineer account", "feature inventory", "end to end flows", "map this account", "what exists", "onboard to account".
+description: Reverse-engineer an entire Fluent Commerce implementation into a feature inventory with flow diagrams, dependency maps, and gap analysis. Use for understanding what has been built across an account.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: --profile PROFILE --retailer RETAILER [--depth summary|detailed] [--focus ENTITY_TYPE] [--include-ootb] [--create-stubs] [--include-runtime]

package/content/dev/skills/fluent-inventory-catalog/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-inventory-catalog
-description: "Manage Fluent Commerce virtual inventory: catalogues, VirtualPositions, VirtualSegments, inventory feeds, and control groups. Schema-gated — only runs when VirtualSegment type exists. Triggers on \"inventory catalog\", \"virtual position\", \"virtual segment\", \"inventory feed\", \"control group\", \"catalogue structure\", \"virtual inventory\". ROUTING — This handles virtual inventory structure queries and management. It does NOT handle account-wide snapshots (use fluent-account-snapshot) or sourcing configuration (use fluent-sourcing)."
+description: Manage Fluent Commerce virtual inventory including catalogues, VirtualPositions, VirtualSegments, inventory feeds, and control groups. Schema-gated and only runs when VirtualSegment type exists.
 user-invocable: true
 trigger-patterns:
   - "inventory catalog"
@@ -38,7 +38,7 @@ graphql_introspect({ type: "VirtualSegment" })
 - **If `VirtualSegment` type exists:** proceed.
 - **If NOT found:** STOP immediately with this message:
 
-> Virtual Segments not available on this account's schema version. This feature requires platform version with segment support (expected April 2026+). Run `graphql_introspect` with `type: 'VirtualSegment'` to check availability.
+> Virtual Segments not available on this account's schema version. Run `graphql_introspect` with `type: 'VirtualSegment'` to check if your platform version supports segments.
 
 Do NOT fall back to non-segment inventory operations. The entire skill is gated on segment support.
 

package/content/dev/skills/fluent-job-batch/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: fluent-job-batch
-description: Diagnose and monitor JOB and BATCH orchestration entities in Fluent Commerce. The dedicated skill for JOB/BATCH workflow status tracking, stuck-job investigation, batch failure triage, and job performance monitoring. Any prompt mentioning JOB or BATCH entity types routes here — not to fluent-entity-flow-diagnose or fluent-trace. Distinct from batch data ingestion API (which is fluent-mcp-tools). ROUTING PRIORITY — Any prompt mentioning "JOB" or "BATCH" entity types MUST route here, even if the prompt also says "stuck" or "diagnose". JOB/BATCH are specialized orchestration entities with unique lifecycle patterns — fluent-entity-flow-diagnose and fluent-trace do NOT understand JOB/BATCH semantics. Triggers on "job batch", "job stuck", "batch stuck", "job lifecycle", "job status", "batch monitoring", "batch operations", "job entity", "JOB/BATCH", "why is the job stuck", "batch failure", "JOB entity is stuck", "job not progressing", "batch not progressing", "job orchestration".
+description: Diagnose and monitor JOB and BATCH orchestration entities in Fluent Commerce including lifecycle tracking, stuck-job investigation, and batch failure triage. Use for any JOB or BATCH entity questions or debugging.
 user-invocable: true
 read-only: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [--job-id <id>] [--batch-id <id>] [--status ACTIVE|COMPLETED|FAILED]
 cursor-tier: auto
 ---
+<!-- routing-notes: ROUTING PRIORITY — Any prompt mentioning "JOB" or "BATCH" entity types MUST route here, even if the prompt also says "stuck" or "diagnose". JOB/BATCH are specialized orchestration entities — fluent-entity-flow-diagnose and fluent-trace do NOT understand JOB/BATCH semantics. Distinct from batch data ingestion API (→ fluent-mcp-tools). -->
 
 # JOB/BATCH Orchestration Lifecycle
 
@@ -37,7 +38,9 @@ The batch ingestion API *creates* JOB and BATCH entities. This skill covers what
 
 ## JOB Entity Lifecycle
 
-JOB is one of the 10 root entity types that can have orchestration workflows.
+> **Note:** JOB and BATCH lifecycle details below are inferred from runtime API evidence and implementation observation. They are not yet documented in the core platform knowledge base (`domain-model.md`). Validate against your environment's actual workflow definitions.
+
+JOB is a root entity type that can have orchestration workflows.
 
 ### Status Flow
 ```
@@ -46,7 +49,7 @@ ACTIVE → FAILED (one or more batches failed)
 ```
 
 ### Key Behaviors
-- **Auto-close:** JOB entities automatically close at midnight UTC
+- **Auto-close:** JOB entities automatically close at midnight UTC (observed behavior — verify via workflow definition in your environment)
 - **Workflow type:** `JOB::<subtype>` (subtype varies by implementation)
 - **Root entity:** JOB is always its own root entity in event context
 

package/content/dev/skills/fluent-knowledge-init/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-knowledge-init
-description: "Interactive wizard to set up project knowledge. Asks plain-English questions, ingests existing docs, or captures progressive learnings — then writes structured knowledge files. Triggers on \"knowledge init\", \"set up knowledge\", \"project knowledge\", \"teach me about your project\", \"knowledge setup\", \"onboard knowledge\"."
+description: Interactive wizard to set up project knowledge by asking questions, ingesting existing docs, or capturing progressive learnings into structured knowledge files. Use for knowledge initialization or onboarding.
 user-invocable: true
 read-only: false
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep

package/content/dev/skills/fluent-module-convert/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-module-convert
-description: Convert existing Java source code into a proper Fluent Commerce extension module. Analyzes non-standard code layouts (loose files, decompiled JARs, plugins, different build systems), restructures into Maven multi-module format with module.json, validates the result, and optionally attempts a build. Triggers on "convert to module", "convert plugin to module", "refactor to module", "restructure module", "onboard source", "migrate to fluent module", "import source code", "convert to module format".
+description: Convert existing Java source code into a proper Fluent Commerce extension module by analyzing non-standard layouts and restructuring into Maven multi-module format. Use for converting or migrating existing code to module format.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <source-path> [--module-name <name>] [--account-prefix <PREFIX>] [--dry-run] [--skip-build]

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

@@ -1,12 +1,13 @@
 ---
 name: fluent-module-scaffold
-description: Scaffold a new Fluent Commerce extension module WITH Java plugins. Generates Maven project structure, module.json, build scripts, initial rule classes, test skeletons, and .gitignore. If the user says "no Java", "no code", "workflow-only", "JSON-only", or "data-only module", route to /fluent-data-module-scaffold instead — those are data modules, not extension modules. HARD NEGATIVE — Do NOT route here for: 'data-only module' / 'no Java' / 'no plugins' / 'workflow-only module' / 'settings-only module' / 'resources-only' (→ fluent-data-module-scaffold for modules without Java plugin code). Triggers on "scaffold module", "new module", "create module", "initialize module", "create Java module", "new extension module".
+description: Scaffold a new Fluent Commerce extension module with Java plugins, Maven structure, module.json, build scripts, and test skeletons. Use for creating new extension modules that include compiled Java code.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <module-name> [--entity-types ORDER,FULFILMENT] [--rules RuleName1,RuleName2] [--account-prefix ACCT]
 cursor-tier: manual
 planning-gate: mandatory
 ---
+<!-- routing-notes: HARD NEGATIVE — Do NOT route here for "data-only module", "no Java", "no plugins", "workflow-only module", "settings-only module", "resources-only" (→ fluent-data-module-scaffold for modules without Java plugin code). -->
 
 # Module Scaffolder
 

package/content/dev/skills/fluent-module-validate/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: fluent-module-validate
-description: MODULE INVENTORY AND STRUCTURAL VALIDATION — Discover, classify, and validate Fluent Commerce modules. Inventories all deployed modules (reference vs custom), validates extension module structure, and maps registered rules to their source. Produces cached JSON artifacts with content hashing. ROUTING PRIORITY — if the prompt says "inventory all deployed modules", "classify modules as reference vs custom", "validate extension module structure", "module health", "list modules", or "what modules are deployed", route HERE — do NOT route to fluent-implementation-map. fluent-implementation-map maps business features and flows; this skill inventories and validates module structures. Triggers on "validate module", "check module structure", "module health", "what modules are deployed", "list modules", "is my module correct", "inventory deployed modules", "classify modules", "reference vs custom".
+description: Discover, classify, and validate Fluent Commerce modules with structural checks, rule-to-source mapping, and reference-vs-custom classification. Use for module inventory, structure validation, or deployment health checks.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [module-root-path | inventory] [--fix] [--force]
 cursor-tier: manual
 ---
+<!-- routing-notes: ROUTING PRIORITY — if the prompt says "inventory modules", "classify modules", "validate module structure", "module health", "list modules", or "what modules are deployed", route HERE — do NOT route to fluent-implementation-map. fluent-implementation-map maps business features and flows; this skill inventories and validates module structures. -->
 
 # Module Inventory and Structure Validator
 

package/content/dev/skills/fluent-mystique-assess/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-mystique-assess
-description: Validate and analyze Mystique manifest JSON. Phase 1 validates against the v2.0 schema, lints component configurations, cross-references aliases, data sources, and i18n keys. Phase 2 scores complexity, analyzes component usage patterns, i18n coverage, query efficiency, and architectural health. Produces structured reports and Mermaid diagrams. Do not use this for TypeScript/React source-code review of .ts/.tsx files; that belongs to fluent-frontend-review. Triggers on "validate manifest", "check mystique", "lint manifest", "analyze manifest", "mystique audit", "ui complexity", "manifest analysis", "component usage", "mystique health", "mystique issues".
+description: Validate and analyze Mystique manifest JSON with schema checks, complexity scoring, component usage patterns, and i18n coverage. Use for manifest validation, lint, or UI architecture health assessment.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <manifest-file-or-directory> [--validate-only] [--analyze-only] [--strict] [--fix-suggestions] [--deep] [--mermaid] [--deployed] [--component <alias>] [--profile <name>]
@@ -257,13 +257,13 @@ Exit codes: `0` = PASS (no CRITICAL/HIGH), `1` = FAIL.
 
 ### Automated Validator
 
-A Node.js linter script is available at `fluent-ai-skills/content/dev/skills/fluent-mystique-assess/validator.mjs`. **Always run this first** before manual review.
+A Node.js linter script is available at `fluent-ai-skills/tools/manifest-validator.mjs`. **Always run this first** before manual review.
 
 ```bash
-node fluent-ai-skills/content/dev/skills/fluent-mystique-assess/validator.mjs <manifest.json>
-node validator.mjs <manifest.json> --strict --fix-suggestions
-node validator.mjs <manifest.json> --component fc.list
-node validator.mjs <manifest.json> --json
+node fluent-ai-skills/tools/manifest-validator.mjs <manifest.json>
+node fluent-ai-skills/tools/manifest-validator.mjs <manifest.json> --strict --fix-suggestions
+node fluent-ai-skills/tools/manifest-validator.mjs <manifest.json> --component fc.list
+node fluent-ai-skills/tools/manifest-validator.mjs <manifest.json> --json
 ```
 
 If `--validate-only` is set, stop here and output the validation report. Otherwise continue to analysis.
@@ -665,6 +665,22 @@ Summary: 2 instances found, 1 FAIL, 1 PASS
 - **Backup**: Existing setting MUST be backed up before overwriting
 - **Approval**: User MUST explicitly approve before any setting update
 
+### Full Deploy Chain (emit after PASS when user wants to deploy)
+
+```
+/fluent-mystique-assess PASS
+    ↓
+Choose deployment method:
+  • Interactive: /fluent-settings (MCP setting_upsert with valueType JSON)
+  • Production:  /fluent-module-deploy --include settings (CLI, repeatable)
+    ↓
+/fluent-ui-test (verify rendered page matches expectations)
+    ↓
+FAIL? → /fluent-trace (diagnose why component isn't rendering)
+```
+
+**First-time app deployment?** Verify: (1) target app entity exists, (2) user has setting write permissions, (3) custom SDK bundle is hosted and accessible. See `/fluent-retailer-config` for entity setup, `/fluent-account-snapshot` for environment state.
+
 ---
 
 ## Graceful Degradation

package/content/dev/skills/fluent-mystique-builder/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: fluent-mystique-builder
-description: Build and edit Mystique manifest JSON definitions. Create pages, routes, component trees, data queries, and fragment compositions using the v2.0 schema. HARD NEGATIVE — if the user is asking for a preview, mockup, visual approval, static mock, or 'show me how it would look before we build', route to fluent-mystique-preview instead. This skill owns real manifest authoring, not pre-build visual approval. Triggers on "build manifest", "create mystique page", "add route", "mystique component", "edit manifest", "build ui", "add page to manifest".
+description: Build and edit Mystique manifest JSON definitions with pages, routes, component trees, data queries, and fragment compositions using the v2.0 schema. Use for manifest authoring or editing UI configuration.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <operation> [manifest-file] [--page <path>] [--section <name>] [--fragment]
 cursor-tier: manual
 planning-gate: mandatory
 ---
+<!-- routing-notes: HARD NEGATIVE — if the user asks for a preview, mockup, visual approval, or "show me how it would look before we build", route to fluent-mystique-preview instead. This skill owns real manifest authoring, not pre-build visual approval. -->
 
 # Mystique Manifest Builder
 
@@ -369,6 +370,36 @@ Before building a manifest that references custom SDK components (non-`fc.*` ali
 
 Understanding how manifests and custom components reach users is critical for correct builder output.
 
+### New App Prerequisites
+
+When building a manifest for a brand-new Fluent UX App (not modifying an existing one), verify these prerequisites before building:
+
+1. **Spec exists (recommended)** — Check `accounts/<PROFILE>/features/<slug>/status.json` for `spec: "APPROVED"`. If no spec exists, recommend `/fluent-use-case-discover` to gather requirements first, or get explicit user acknowledgment to skip. The `fluent-frontend-dev` agent enforces this as a gate at Phase 1.5.
+2. **App entity exists** — The target app (OMS, Store, or custom) must exist in the environment. Check with `/fluent-account-snapshot` or MCP `entity_get`.
+3. **Setting namespace available** — Root manifests use `fc.mystique.manifest.<app-name>`. Confirm no existing setting conflicts. Fragments use `fc.mystique.manifest.<app-name>.<section>`.
+4. **Permissions** — The deploying user/role needs permission to create settings with `context: "ACCOUNT"`, `contextId: 0`. See `knowledge/platform/roles-and-permissions.md` for the three-layer access control model (platform permissions, custom roles, manifest-based visibility).
+5. **Plugin hosting** — If using custom SDK components, the bundle hosting URL must be accessible from end-user browsers. Localhost is fine for development only.
+
+If any prerequisite is missing, recommend: `/fluent-use-case-discover` (gather requirements), `/fluent-retailer-config` (create entities), `/fluent-settings` (manage settings), `/fluent-mystique-scaffold` (set up SDK project).
+
+### Full New App Sequence
+
+For building a complete new Mystique app end-to-end, follow this lifecycle. Each step can be skipped if scope is clear and user acknowledges:
+
+```
+1. /fluent-use-case-discover  → Gather requirements (UI pages, roles, entities, data queries)
+2. /fluent-feature-plan       → Plan with frontend architecture (route map, component tree, settings)
+3. /fluent-mystique-builder   → Create root manifest + fragments (this skill, Operation 1)
+4. /fluent-mystique-scaffold  → Scaffold SDK project (only if custom components needed)
+5. /fluent-mystique-assess    → Validate manifest (49 rules, 6 phases — 0 CRITICAL/HIGH to proceed)
+6. /fluent-mystique-preview   → Visual preview in browser (optional but recommended)
+7. /fluent-frontend-build     → Build SDK bundle (7 gates — only if SDK project exists)
+8. Deploy manifest            → Via GraphQL createSetting or CLI module install (see Safety Guardrails below)
+9. /fluent-ui-test            → Verify in browser (login, navigate, render, user actions, roles)
+```
+
+The `fluent-frontend-dev` agent orchestrates this entire sequence with gates at Phase 1.5 (spec), Phase 2 (plan approval), Phase 4 (validation), and Phase 5 (deploy safety).
+
 ### Manifests are JSON Configuration
 
 Manifests are pure JSON — they are NOT compiled or bundled. They are deployed to Fluent UX Apps through one of:

package/content/dev/skills/fluent-mystique-component/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-mystique-component
-description: Add new components, form fields, or template helpers to an existing Mystique SDK project. Generates component files, registers with the appropriate registry, and wires into the build. Triggers on "add component", "new component", "extend sdk", "add field", "new mystique component".
+description: Add new components, form fields, or template helpers to an existing Mystique SDK project with file generation, registry wiring, and build integration. Use for extending an existing SDK project with new components.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <ComponentName> [--project <project-path>] [--type component|field|template] [--category content|layout|page|filter]

package/content/dev/skills/fluent-mystique-diff/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-mystique-diff
-description: Compare Mystique manifest settings against CDN baselines. Shows which fragments are customized, which use CDN default, which are account-only, and structural diffs (routes, components, queries, plugins). Classifies OOTB vs custom components. All analysis runs locally to minimize token usage. Triggers on "manifest diff", "compare manifests", "cdn vs custom", "manifest baseline", "what's customized", "component inventory".
+description: Compare Mystique manifest settings against CDN baselines showing customized fragments, CDN defaults, account-only additions, and OOTB vs custom component classification. Use for manifest diff or CDN baseline comparison.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Glob, Grep
 argument-hint: --profile <PROFILE> [--app oms|store] [--deep] [--components] [--verbose] [--refresh-cdn]

package/content/dev/skills/fluent-mystique-preview/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: fluent-mystique-preview
-description: "Mock, modify, and preview Mystique UI components in the live Fluent Commerce app before building or deploying. Three modes: ADD (inject new), MODIFY (alter existing), REMOVE (preview without). Highlights all changes with color-coded borders and badges. Supports iterative refinement. ROUTING PRIORITY — if the user asks for a preview, mockup, visual approval, static mock, or 'show me how it would look before we build', route HERE instead of fluent-mystique-builder. This skill owns pre-build visual approval, not real manifest authoring. Triggers on \"preview UI\", \"mock component\", \"preview manifest\", \"how will it look\", \"show me the UI\", \"preview in OMS\", \"preview in store\", \"visual preview\", \"UI mockup\", \"what would it look like if\", \"preview change\", \"modify the page\", \"static mockup\", \"before we build\"."
+description: Mock, modify, and preview Mystique UI components in the live Fluent Commerce app before building or deploying with ADD, MODIFY, and REMOVE modes. Use for visual previews, UI mockups, or pre-build approval.
 user-invocable: true
 read-only: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: "[--mode add|modify|remove] [--app oms|store|servicepoint] [--route /orders] [--manifest <path>] [--component <alias>] [--feature <slug>]"
 cursor-tier: manual
 ---
+<!-- routing-notes: ROUTING PRIORITY — if the user asks for a preview, mockup, visual approval, static mock, or "show me how it would look before we build", route HERE instead of fluent-mystique-builder. This skill owns pre-build visual approval, not real manifest authoring. -->
 
 # Mystique UI Preview & Iteration
 
@@ -1008,7 +1009,7 @@ When a preview is approved, add a visual reference to the feature plan:
 
 #### Embedding in feature dashboard
 
-The dashboard generator (`fluent-ai-skills/tools/generate-feature-dashboard.mjs`) can detect preview reports and embed the flip widget:
+The dashboard generator (`fluent-ai-skills/tools/feature-dashboard.mjs`) can detect preview reports and embed the flip widget:
 
 ```javascript
 // In buildDetailPanel, check for preview report
@@ -1167,6 +1168,22 @@ The approved preview report becomes the visual reference:
 - Width/positioning decided
 - **Change manifest** — exact list of ADD/MODIFY/REMOVE operations to implement
 
+### Full Deploy Chain After Approval
+
+```
+Preview APPROVED
+    ↓
+/fluent-mystique-builder   (build manifest matching approved preview)
+    ↓
+/fluent-mystique-assess    (validate manifest structure before deploy)
+    ↓
+/fluent-settings or /fluent-module-deploy   (deploy manifest as setting)
+    ↓
+/fluent-ui-test            (verify live page matches preview)
+```
+
+If custom SDK components are needed (non-`fc.*` aliases in the preview), insert `/fluent-mystique-scaffold` before the builder step.
+
 ### Verification via `/fluent-ui-test`
 
 After the real manifest is built and deployed, `/fluent-ui-test` can compare the live page against the approved preview screenshots to verify visual fidelity.

package/content/dev/skills/fluent-mystique-scaffold/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-mystique-scaffold
-description: Scaffold a new Mystique SDK component project with webpack, TypeScript, Storybook, Jest, component registration, and i18n — ready to develop and deploy. Triggers on "scaffold component", "new mystique project", "create sdk component", "mystique sdk setup", "new ui plugin".
+description: Scaffold a new Mystique SDK component project with webpack, TypeScript, Storybook, Jest, component registration, and i18n ready to deploy. Use for creating new SDK component projects from scratch.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <project-name> [--components ComponentA,ComponentB] [--category content|layout|page|filter]
@@ -46,6 +46,17 @@ Check for project-specific knowledge that should inform the generated SDK projec
 4. If `accounts/<PROFILE>/memory/index.md` exists, read the top account-specific frontend, Storybook, test, and deployment gotchas and apply them silently.
 5. Apply knowledge silently — do NOT show raw knowledge to user, just follow the conventions in the generated scaffold
 
+## Prerequisites — New App Checklist
+
+Before scaffolding, verify the target environment is ready. Skip items that are already confirmed.
+
+1. **Target app exists** — The Fluent UX app (`oms`, `store`, or custom) must already exist in the environment. Manifests are deployed as settings attached to an app — if the app doesn't exist, deployment will fail silently.
+2. **Permissions configured** — The user or role deploying the manifest must have permission to create/update settings with `context: "ACCOUNT"`. Admin roles have this by default; custom roles may not.
+3. **SDK version compatibility** — Check the deployed app's SDK version (`sdk-version.json` at the app URL). The scaffolded project's `@anthropic-ai/sdk` and `@anthropic-ai/mystique-*` versions must be compatible with the runtime. Mismatches cause silent component registration failures.
+4. **Plugin hosting plan** — Know where the production bundle will be hosted (Vercel, S3, CloudFront, etc.). The scaffold produces `dist/bundle.[hash].js` — it needs a URL accessible from the browser.
+
+If prerequisites are unclear, recommend: `/fluent-retailer-config` (create entities), `/fluent-settings` (verify setting access), `/fluent-account-snapshot` (inspect environment state).
+
 ## OMX Component SDK — Source Template
 
 Every Mystique SDK project starts from the **OMX Component SDK** template zip (or an existing SDK source folder/repo provided by the user).

package/content/dev/skills/fluent-mystique-sdk-reference/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: fluent-mystique-sdk-reference
-description: "Mystique Component SDK API REFERENCE LOOKUP — React hooks, composition primitives, field patterns, and Material-UI constraints. Read-only documentation lookup for building custom Fluent Commerce UI components. This IS a valid platform skill — NEVER classify as 'none' or 'direct knowledge lookup'. ROUTING PRIORITY — if the prompt says '/fluent-mystique-sdk-reference', 'useSettings hook', 'SDK hook signature', 'SDK reference documentation', 'hook API', 'composition API reference', 'SDK hook', or 'look up hook', route HERE. HARD NEGATIVE — Do NOT route here for: 'add component' / 'register component' / 'extend SDK project' (→ fluent-mystique-component). This skill is READ-ONLY reference documentation. Triggers on 'mystique hooks', 'sdk reference', 'component api', 'field registry', 'mystique sdk', 'SDK hook API', 'hook patterns', 'useSettings hook', 'what hook', 'SDK documentation lookup', 'hook signature', '/fluent-mystique-sdk-reference'."
+description: Mystique Component SDK API reference for React hooks, composition primitives, field patterns, and Material-UI constraints. Use for SDK hook lookups, API signatures, or component SDK documentation.
 user-invocable: true
 allowed-tools: Read, Glob, Grep
 argument-hint: [hook-name|pattern-name]
 cursor-tier: manual
 ---
+<!-- routing-notes: ROUTING PRIORITY — if the prompt says "useSettings hook", "SDK hook signature", "SDK reference documentation", "hook API", or "composition API reference", route HERE. HARD NEGATIVE — Do NOT route here for "add component", "register component", "extend SDK project" (→ fluent-mystique-component). This skill is READ-ONLY reference documentation. -->
 
 # Mystique Component SDK Reference
 

package/content/dev/skills/fluent-pre-deploy-check/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-pre-deploy-check
-description: Run a read-only pre-deployment checklist for Fluent Commerce modules and workflows. Validates environment readiness, module structure, workflow integrity, settings, and connection topology before deployment without building, packaging, or deploying artifacts. Triggers on "pre-deploy check", "deployment checklist", "ready to deploy", "deploy gate", "can I deploy", "deploy readiness".
+description: Run a read-only pre-deployment checklist validating environment readiness, module structure, workflow integrity, settings, and connection topology. Use for deploy-readiness checks before pushing artifacts.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [--profile <profile>] [--retailer <ref>] [--module-path <path>] [--skip <phase,...>]
@@ -10,7 +10,7 @@ planning-gate: advisory
 
 # Pre-Deployment Checklist
 
-Structured deployment gate between "build passes" and "deploy to retailer." Runs 9 phases of validation (29 backend gates + 5 frontend gates) producing a machine-readable pass/fail report that blocks deployment on critical failures.
+Structured deployment gate between "build passes" and "deploy to retailer." Runs 9 phases of validation (32 backend gates + 5 frontend gates) producing a machine-readable pass/fail report that blocks deployment on critical failures.
 
 This skill is the final checkpoint in the Agent-Driven Development (ADD) lifecycle, positioned at Phase 6 (Demo Deployment). It aggregates validation from multiple specialized skills and MCP tools into a single, traceable pre-flight report.
 
@@ -1008,7 +1008,7 @@ wc -c accounts/<PROFILE>/SOURCE/frontend/<project>/dist/bundle.*.js
 **Invocation:**
 If manifest settings were saved to disk via `outputFile` in Gate 5.1, run the Mystique validator against them:
 ```bash
-node content/dev/skills/fluent-mystique-assess/validator.mjs accounts/<PROFILE>/settings/backups/fc.mystique.manifest.*.json --json
+node fluent-ai-skills/tools/manifest-validator.mjs accounts/<PROFILE>/settings/backups/fc.mystique.manifest.*.json --json
 ```
 Alternatively, invoke `/fluent-mystique-assess` skill for each manifest file.
 

package/content/dev/skills/fluent-retailer-config/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-retailer-config
-description: Configure Fluent Commerce retailer environments by creating real platform entities — warehouse locations, store locations, networks, catalogues, inventory, carriers, and users via GraphQL. This is the canonical owner for "create warehouse", "create warehouse and store locations for this retailer", "set up locations for this retailer", "create network", or other retailer entity setup. Even if the user says "configure retailer", stay here when the nouns are locations, networks, carriers, or catalogues. Do NOT route key-value settings CRUD here. Triggers on "setup retailer", "create warehouse", "create warehouse and store locations", "create warehouse and store locations for this retailer", "create store location", "create location", "create network", "setup inventory", "retailer config", "environment setup".
+description: Configure Fluent Commerce retailer environments by creating platform entities like locations, networks, catalogues, inventory, carriers, and users via GraphQL. Use for retailer entity setup or environment configuration.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [--retailer <ref>] [--setup-type full|locations|networks|catalogues|inventory]

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

@@ -1,6 +1,6 @@
 ---
 name: fluent-rollback
-description: Roll back workflow and module deployments in Fluent Commerce. Supports workflow version revert, module redeploy of prior versions, and settings restore from audit trail. Triggers on "rollback", "revert deployment", "undo deploy", "roll back workflow", "restore previous version".
+description: Roll back workflow and module deployments in Fluent Commerce with version revert, module redeploy, and settings restore from audit trail. Use for rollback, revert, or restoring previous versions.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <workflow|module|settings> <name> [--profile PROFILE] [--retailer RETAILER_REF] [--to-version VERSION] [--dry-run]

package/content/dev/skills/fluent-rule-lookup/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: fluent-rule-lookup
-description: "OOTB RULE REFERENCE — search and discover out-of-the-box Fluent Commerce reference module rules by keyword, entity type, module, or capability. Queries MCP plugin_list first, falls back to offline catalog. ROUTING PRIORITY — if the prompt asks 'what does [RuleName] rule do', 'what parameters does [rule] accept', 'SendWebhook rule', 'OOTB rule documentation', or 'look up rule [name]', route HERE — do NOT route to fluent-custom-code. fluent-custom-code analyzes custom Java source code; this skill looks up OOTB platform rules. Does NOT reverse-engineer features (→ fluent-feature-explain) and does NOT scaffold new custom rules (→ fluent-rule-scaffold). Triggers on 'find rule', 'search rules', 'OOTB rule', 'what rule does', 'rule lookup', 'available rules', 'which rules', 'list rules', 'rule catalog', 'reference module rules', 'what does the [rule] rule do', 'what parameters does [rule] accept'."
+description: Search and discover out-of-the-box Fluent Commerce reference module rules by keyword, entity type, module, or capability via MCP plugin_list. Use for OOTB rule lookups, parameter reference, or rule catalog searches.
 user-invocable: true
 allowed-tools: Bash, Read, Glob, Grep
 argument-hint: <search-term> [--module core|order|fulfilment|inventory|base|globalinventory] [--entity ORDER|FULFILMENT|...] [--offline]
 cursor-tier: manual
 ---
+<!-- routing-notes: ROUTING PRIORITY — if the prompt asks "what does [RuleName] rule do", "what parameters does [rule] accept", "OOTB rule documentation", or "look up rule", route HERE — do NOT route to fluent-custom-code. fluent-custom-code analyzes custom Java source code; this skill looks up OOTB platform rules. Does NOT reverse-engineer features (→ fluent-feature-explain) and does NOT scaffold new rules (→ fluent-rule-scaffold). -->
 
 # OOTB Rule Lookup
 

package/content/dev/skills/fluent-rule-scaffold/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: fluent-rule-scaffold
-description: Scaffold new Fluent Commerce Rubix rules. Generates Java class, test class, and wires into module.json. Use this for NEW rule creation only. YIELD-BACK — if the prompt says "write tests for", "write unit tests", "generate tests for this rule", "test this rule", or "fix rule test", route to fluent-rule-test instead — that skill owns all test generation and repair for existing rules. YIELD-BACK — if the prompt says "analyze", "explain", or "understand" existing custom code, route to fluent-custom-code instead — this skill only CREATES new rules. Key knowledge — rule-development-contract.md (@ParamString vs @EventAttribute), graphql-in-rules.md (DynamicUtils vs Apollo), rule-test-patterns.md (test harness), module-structure.md (Maven layout). Triggers on "create rule", "new rule", "scaffold rule", "add rule class".
+description: Scaffold new Fluent Commerce Rubix rules with Java class, test class, and module.json wiring for NEW rule creation only. Use for creating new rules, not testing or analyzing existing ones.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <rule-name> [--entity-type ORDER|FULFILMENT|...] [--package common|fulfilment|order|...]
 cursor-tier: manual
 planning-gate: mandatory
 ---
+<!-- routing-notes: YIELD-BACK — if the prompt says "write tests for", "generate tests for this rule", "test this rule", or "fix rule test", route to fluent-rule-test instead. YIELD-BACK — if the prompt says "analyze", "explain", or "understand" existing custom code, route to fluent-custom-code instead — this skill only CREATES new rules. -->
 
 # Rule Scaffolder
 
@@ -288,7 +289,7 @@ If the same event hits twice due to a race condition, the rule should check curr
 ```java
 // GOOD: Idempotent — checks before creating
 @Override
-public void run(RuleContext context) {
+public void run(ContextWrapper context) {
     // Check if child entity already exists
     List<CreditMemo> existing = context.getEntity()
         .getCreditMemos().stream()
@@ -305,7 +306,7 @@ public void run(RuleContext context) {
 
 // BAD: Not idempotent — creates duplicate child entity on retry
 @Override
-public void run(RuleContext context) {
+public void run(ContextWrapper context) {
     // Directly creates without checking existence
     context.action().mutation(createCreditMemoMutation, variables);
 }
@@ -319,7 +320,7 @@ Never trust event payload values without validating against current entity state
 
 ```java
 @Override
-public void run(RuleContext context) {
+public void run(ContextWrapper context) {
     // 1. Validate entity is still in expected state
     String currentStatus = context.getEntity().getStatus();
     if (!"BOOKED".equals(currentStatus)) {
@@ -534,8 +535,8 @@ class <RULE_NAME>Test {
         when(context.action()).thenReturn(action);
         when(action.mutation()).thenReturn(mutationAction);
         when(action.eventAction()).thenReturn(eventAction);
-        when(event_getAccountId()).thenReturn("TEST_ACCOUNT");
-        when(event_getName()).thenReturn("TestEvent");
+        when(event.getAccountId()).thenReturn("TEST_ACCOUNT");
+        when(event.getName()).thenReturn("TestEvent");
     }
 
     @Test

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

@@ -1,12 +1,13 @@
 ---
 name: fluent-rule-test
-description: Generate or repair JUnit 5 unit tests for existing Fluent Commerce Rubix backend rule classes. ROUTING PRIORITY over fluent-rule-scaffold for ANY prompt that says "write tests for", "write unit tests", "generate tests for this rule", "test this rule", or "fix rule test" — even if it does not explicitly say "existing". If the prompt mentions testing or writing tests for a rule, route HERE. Rule scaffold is for creating NEW rule implementations from scratch; this skill owns all test generation and repair work. Use when Codex needs to add tests for an existing rule, backfill rule coverage, update rule fixtures after logic changes, regenerate tests after logic changes, or diagnose rule test failures. Triggers on "test Fluent rule", "write Rubix rule test", "generate backend rule test", "fix rule test", "write unit tests for this rule", "write tests for this", "write tests for", "test this rule", "generate tests".
+description: Generate or repair JUnit 5 unit tests for existing Fluent Commerce Rubix backend rule classes. Use for writing rule tests, backfilling coverage, updating fixtures, or diagnosing test failures.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <RuleName> [--style auto|rule-executor|test-executor|mockito|workflow] [--coverage full|happy-path]
 category: testing
 tags: [rule, test, junit, rubix, ruleexecutor, testexecutor]
 ---
+<!-- routing-notes: ROUTING PRIORITY over fluent-rule-scaffold for ANY prompt that says "write tests for", "write unit tests", "generate tests for this rule", "test this rule", or "fix rule test". Rule scaffold is for creating NEW rule implementations; this skill owns all test generation and repair work. -->
 
 # Rule Test Generator
 

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

@@ -1,6 +1,6 @@
 ---
 name: fluent-scope-plan
-description: Break approved specs into phased delivery plans with dependency-ordered task graphs. Identifies vertical slice delivery phases, then decomposes each phase into ordered tasks with skill mappings. Triggers on "phase this feature", "split into phases", "delivery phases", "decompose scope", "plan from scope", "task breakdown", "scope to tasks", "incremental delivery", "vertical slices".
+description: Break approved specs into phased delivery plans with dependency-ordered task graphs and vertical slice phases decomposed into ordered tasks. Use for delivery phasing, scope decomposition, or task breakdown.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [--profile PROFILE] [--feature SLUG] [--phases N] [--scope <path>] [--output-format json|markdown] [--validate-only] [--batch-features]

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

@@ -1,6 +1,6 @@
 ---
 name: fluent-session
-description: Track session changes and export structured audit trails. Maintains a running change log with text summaries and machine-readable JSON exports for CI/CD pipelines and compliance. Triggers on "session summary", "what did we change", "change summary", "show changes", "export audit", "session audit", "audit trail", "compliance report".
+description: Track session changes and export structured audit trails with text summaries and machine-readable JSON exports for CI/CD and compliance. Use for session summaries, change logs, or audit exports.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Glob, Grep
 argument-hint: [show|reset|export [--format json|jsonl] [--output <path>] [--include-readonly]]

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

@@ -1,6 +1,6 @@
 ---
 name: fluent-settings
-description: Manage Fluent Commerce settings — discover, audit, create, update, and migrate retailer-scoped settings. Cross-reference workflow rules with settings to find gaps. Triggers on "manage settings", "create setting", "audit settings", "settings migration", "missing settings", "webhook settings".
+description: Manage Fluent Commerce retailer-scoped settings with discover, audit, create, update, and migrate operations plus workflow rule cross-referencing. Use for settings management or gap analysis.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [--audit <workflow-file>] [--context RETAILER|ACCOUNT|LOCATION] [--migrate --from <profile> --to <profile>]
@@ -673,7 +673,7 @@ For updates, present a clear diff:
 
 ```
 Setting: fc.webhook.order.created (ID: 365)
-Context: RETAILER:2
+Context: RETAILER, contextId: 2
 Current value: {"url": "https://old-endpoint.com/webhook"}
 New value:     {"url": "https://new-endpoint.com/webhook"}
 Backup: accounts/<PROFILE>/settings/backups/fc.webhook.order.created_2026-02-26_143000.json

package/content/dev/skills/fluent-skill-observability/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-skill-observability
-description: Unified skill system observability — trace execution, analyze routing patterns, and review execution quality. Triggers on "skill trace", "trace skills", "what skills ran", "routing report", "routing analysis", "feedback dashboard", "show feedback", "review feedback", "promote learning", "skill effectiveness", "quality report", "skill quality", "audit skills".
+description: Unified skill system observability for tracing execution, analyzing routing patterns, and reviewing execution quality across all skills. Use for skill trace, routing reports, or quality audits.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: trace [show|analyze|clear|hook-setup] | routing [full|summary|skill <name>|recommendations] | feedback [dashboard|review <skill>|promote <id>|effectiveness [<skill>]|export] | quality [<skill-name>]