@fluentcommerce/ai-skills 0.13.0 → 0.14.0

package/content/dev/skills/{fluent-source-onboard → fluent-module-convert}/SKILL.md

@@ -1,22 +1,22 @@
 ---
-name: fluent-source-onboard
-description: Onboard existing Java source code into a proper Fluent Commerce extension module. Analyzes non-standard code layouts (loose files, decompiled JARs, different build systems), restructures into Maven multi-module format with module.json, validates the result, and optionally attempts a build. Triggers on "onboard source", "refactor to module", "convert to module format", "restructure module", "import source code", "migrate to fluent module".
+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".
 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]
 cursor-tier: manual
-planning-gate: advisory
+planning-gate: mandatory
 ---
 
-# Source Onboarder
+# Module Converter
 
-Take existing Java source code — whether loose files, a non-standard project layout, a decompiled JAR, or a project using a different build system — and restructure it into a proper Fluent Commerce extension module that passes `/fluent-module-validate` and builds with `/fluent-build`.
+Convert existing Java source code — whether loose files, a non-standard project layout, a decompiled JAR, a plugin, or a project using a different build system — into a proper Fluent Commerce extension module that passes `/fluent-module-validate` and builds with `/fluent-build`.
 
 ## Pre-flight: Feedback Check
 
 Before starting, check for past learnings from this skill:
 
-1. Check if `accounts/<PROFILE>/feedback/fluent-source-onboard.jsonl` exists
+1. Check if `accounts/<PROFILE>/feedback/fluent-module-convert.jsonl` exists
 2. If yes, read last 20 records
 3. Filter to: FAILURE or USER_CORRECTED outcomes, confidence = CONFIRMED or PROMOTED
 4. Extract top 3 relevant learnings — use as internal guidance during execution
@@ -25,14 +25,16 @@ Before starting, check for past learnings from this skill:
 ## When to Use
 
 - "I have Java rule classes but they're not in a Fluent module structure"
+- "Convert this existing plugin to a proper module"
 - "Onboard this decompiled JAR into a buildable module"
 - "Convert this Gradle project to Fluent Commerce module format"
 - "I have source code from another team — make it a proper module"
 - "Restructure this code into the standard Maven multi-module layout"
 - "Import these rule classes into a deployable module"
+- "Analyze this plugin and convert it to module format"
 - Code exists in `accounts/<PROFILE>/SOURCE/backend/` but doesn't pass `/fluent-module-validate`
 - Decompiled output exists in `accounts/<PROFILE>/SOURCE/backend/.decompiled/` and needs to become a buildable module
-- `/fluent-scope-plan` generated a `SOURCE_ONBOARD` task
+- `/fluent-scope-plan` generated a `MODULE_CONVERT` task
 
 ## When NOT to Use
 
@@ -88,11 +90,62 @@ This skill does **not** own:
 
 ## Execution Protocol
 
-**Phase ordering note:** Unlike most implementation skills, source-onboard runs analysis (Phase 1) BEFORE the planning gate (Phase 2). This is intentional — you must understand what exists before you can plan the restructuring. Phase 1 is read-only analysis. Phase 2 is the mandatory approval gate before any files are modified.
+**Phase ordering note:** Unlike most implementation skills, module-convert has TWO user checkpoints before any files are modified:
 
-### Phase 1: Source Analysis (read-only)
+1. **Phase 0** — Intake triage: resolve ambiguity (source path, intent, namespace, module name)
+2. **Phase 1** — Source analysis (read-only): scan, classify, present findings → **user confirms or corrects**
+3. **Phase 2** — Planning gate (mandatory): present restructuring plan → **user approves before execution**
 
-**Goal:** Understand what exists, classify its state, and identify all rule classes. **No files are modified in this phase.**
+This two-checkpoint flow is intentional. The user knows their code better than the AI — they can catch misclassified rules, wrong namespaces, or deprecated code at the analysis stage, before the plan is built on top of potentially wrong assumptions.
+
+### Phase 0: Intake Triage
+
+Before scanning any files, resolve critical unknowns. Ask these **only if the answer is not already clear** from the user's prompt, arguments, or workspace context. Do not ask questions you can answer by reading the filesystem.
+
+#### 0.1 Source Path
+
+If the user did not provide a `source-path`:
+1. Check `accounts/<PROFILE>/SOURCE/backend/` for candidate directories
+2. If exactly one candidate, confirm: _"Found `accounts/ACME/SOURCE/backend/legacy-plugin/` — convert this?"_
+3. If multiple candidates, list them and ask which one
+4. If none, ask: _"Where is the source code you want to convert? Provide a path relative to the workspace root."_
+
+#### 0.2 Intent Check
+
+If the prompt uses ambiguous language ("analyze", "look at", "check") without clear conversion intent ("convert", "restructure", "module format", "onboard"):
+- Ask: _"Do you want to **analyze** this code (understand what it does → `/fluent-custom-code`) or **convert** it into a Fluent module (restructure + build infrastructure)?"_
+
+If the source path already contains a valid `module.json` + `pom.xml` + standard Maven layout:
+- Ask: _"This already looks like a valid Fluent module. Do you want to **repair** structural issues, or **re-convert** from scratch?"_
+
+#### 0.3 Plugin Namespace (Account Prefix)
+
+The plugin namespace determines rule registration keys (e.g., `ACME.order.ValidateReturnWindow`). This MUST be correct — a wrong namespace means workflows can't find the rules at runtime.
+
+**Auto-detection order:**
+1. `--account-prefix` argument → use as-is
+2. Existing `module.json` in the source → extract from rule keys (the prefix before the first `.`)
+3. `plugin_list` from the live environment → extract common prefix from deployed rules
+4. Active profile name from CLI context
+
+**If auto-detection fails or finds conflicting prefixes**, ask:
+_"What plugin namespace should I use for rule registration? This becomes the prefix in rule keys like `<NAMESPACE>.order.ValidateReturnWindow`."_
+
+**If auto-detected prefix differs from deployed prefix**, warn and confirm:
+_"The source uses prefix `ACME` but deployed rules use `MY_COMPANY`. Which should the converted module use?"_
+- **Use deployed prefix** (recommended) — zero-disruption, workflows keep working
+- **Use source prefix** — requires workflow redeployment to update rule references
+
+#### 0.4 Module Name
+
+If `--module-name` was not provided and cannot be derived from the source directory name or existing `module.json`:
+- Ask: _"What should the module be called? This sets the Maven artifact ID and module.json name (e.g., `my-returns`)."_
+
+**Skip Phase 0 entirely** when the user provides a clear `source-path`, conversion intent, and the source contains enough context to auto-detect namespace and module name.
+
+### Phase 1: Source Analysis (read-only, results shown to user)
+
+**Goal:** Understand what exists, classify its state, and identify all rule classes. **No files are modified in this phase.** Analysis results are presented to the user at the end of this phase — the user can correct misclassifications before the plan is built.
 
 #### Step 1.1: Classify Source Layout
 
@@ -123,12 +176,19 @@ source-path/
 For each Java file found, determine if it's a Fluent rule class:
 
 **Detection patterns** (check in order):
-1. Extends `BaseRule` or `Rule` (from Rubix SDK)
+1. Extends `BaseRule` or `Rule` (from Rubix SDK) — **check transitively**: if a class extends a project-local base class (e.g., `com.puma.common.BaseRule`) that itself implements `Rule` or extends SDK `BaseRule`, treat it as a rule. Read the base class source to confirm.
 2. Has `@RuleInfo` annotation
-3. Implements `run(ContextWrapper context)` or `run(Context context)` method
-4. Contains `context.getProp(...)` or `context.getEvent()` calls
+3. Implements `run(...)` or a custom `execute(...)` method that is called from `run()` — projects often wrap the SDK `run(Context)` in a custom base class that delegates to `execute(ContextWrapper)`
+4. Contains `context.getProp(...)`, `context.getEvent()`, or equivalent calls through a project-specific context wrapper
 5. Is registered in a `module.json` (if one exists)
 
+**Custom base class / context wrapper detection:**
+Many production plugins define their own `BaseRule` and `ContextWrapper` that wrap the SDK classes. When detected:
+- Classify the custom base class as `FRAMEWORK` (not rule, not utility)
+- Move it to `plugins/util/` alongside other framework-level classes
+- Do NOT rewrite rules to use SDK classes directly — preserve the custom wrapper
+- Note the inheritance chain in the analysis output so the user can verify
+
 **For each detected rule, extract:**
 - Class name (e.g., `ValidateReturnWindow`)
 - Package name (e.g., `com.fluentcommerce.rule.order`)
@@ -143,6 +203,26 @@ For each Java file found, determine if it's a Fluent rule class:
 - Missing Javadoc/comments
 - Confidence level: decompiled vs original
 
+#### Step 1.2b: Discover Non-Java Assets
+
+Scan for non-Java files that need special handling:
+
+**GraphQL operations** (`*.graphql` files):
+- Typically in `src/main/graphql/` — used by Apollo code generation at build time
+- These must stay alongside the rules submodule (Apollo plugin wires them during compile)
+- Count mutations vs queries, note the GraphQL package path
+
+**Settings and manifest JSONs:**
+- Look for `settings/`, `manifests/`, or directories containing Mystique manifest JSON files (`fc.mystique.manifest.*`)
+- These are **NOT part of the extension module** — they belong in a separate data module
+- Flag to the user: _"Found N settings/manifest files. These should be deployed as a separate data module (`/fluent-data-module-scaffold`), not bundled with the extension module."_
+
+**Other non-Java resources:**
+- `reviewTools/`, `scripts/`, documentation, Python files — flag as non-module assets that won't be included in the restructured module
+- Config files (`.properties`, `.yml`, `.xml` other than POM) — may need to move to `src/main/resources/`
+
+Present the asset inventory in the Phase 1.5 findings so the user can decide what to include.
+
 #### Step 1.3: Detect Existing module.json
 
 If a `module.json` exists in the source path:
@@ -166,6 +246,77 @@ plugin_list (compact: true)
 - Identify rules that are deployed but have different versions or parameters
 - Flag any namespace conflicts
 
+#### Step 1.5: Present Analysis Findings
+
+**Before proceeding to the plan, present a structured summary of what was found.** This gives the user a chance to correct misclassifications, flag deprecated rules, or adjust the namespace before the restructuring plan is built on top of these findings.
+
+```markdown
+## Source Analysis — What I Found
+
+| Property | Value |
+|----------|-------|
+| Source path | `accounts/<PROFILE>/SOURCE/backend/rubix-plugin-<name>/` |
+| Layout category | MAVEN_NONSTANDARD (flat single-POM, not multi-module) |
+| Java files found | 469 |
+| Rule classes detected | 346 (across 17 domains) |
+| Framework classes | 4 (custom BaseRule, ContextWrapper, Guard, LogJsonSerializer) |
+| Model/DTO classes | 86 |
+| Service classes | 12 |
+| Utility classes | 17 |
+| Exception classes | 4 |
+| Test classes found | 126 |
+| Existing module.json | No |
+| Existing pom.xml | Yes (flat, v1.0.36) |
+| Plugin namespace | <ACCOUNT_PREFIX>.<namespace> (from POM properties) |
+
+### Non-Java Assets
+
+| Asset Type | Count | Location | Recommendation |
+|-----------|-------|----------|----------------|
+| GraphQL operations | N (.graphql files) | src/main/graphql/ | Keep with rules submodule (Apollo build-time) |
+| Mystique manifests | N JSON files | settings/UI Settings/ | **Separate data module** — not part of extension |
+| Other settings | N JSON files | settings/ | **Separate data module** |
+| Dev tooling | Scripts, docs | reviewTools/ etc. | Exclude from module (not deployable) |
+
+### Custom Framework Classes
+
+| Class | Purpose | Impact |
+|-------|---------|--------|
+| `com.<org>.common.BaseRule` | Wraps SDK `Rule`, adds execute/logging/exception pattern | **All N rules extend this** — must preserve |
+| `com.<org>.common.ContextWrapper` | Wraps SDK `Context` with convenience methods | **All rules use this** — must preserve |
+| Other framework classes | Validation, serialization, etc. | Used by rules — move to util |
+
+### Discovered Rules (top domains by count)
+
+| Domain | Rules | Entity Type | Examples |
+|--------|-------|-------------|---------|
+| order | N | ORDER | (list top 2-3 class names) |
+| fulfilment | N | FULFILMENT | (list top 2-3 class names) |
+| consignment | N | CONSIGNMENT | (list top 2-3 class names) |
+| *(+ more domains)* | N | — | — |
+
+### Issues & Decisions Needed
+
+- ⚠ **No module.json** — N rule registrations will be generated. Confirm namespace `<ACCOUNT_PREFIX>.<namespace>` is correct.
+- ⚠ **N rules have no tests** — skeletons will be generated for untested rules
+- ⚠ **Custom BaseRule wrapper** — rules extend project-local BaseRule, not SDK BaseRule. Will preserve as-is.
+- ❓ **Package rename?** Source uses `com.<org>.*`. Recommend keeping as-is for large codebases (massive import churn, no runtime benefit). Want to repackage to `com.fluentcommerce.*`?
+- ❓ **Settings/manifests** — N JSON files found. Deploy as separate data module? Or include in extension?
+- ❓ **GraphQL operations** — N `.graphql` files found. Keep with rules submodule for Apollo build? Or separate?
+
+Does this look correct? Any classes I misclassified? Any rules to exclude?
+```
+
+**Wait for the user to confirm or correct.** Common corrections:
+- _"ReturnHelper is actually a rule, not a utility"_ → reclassify
+- _"NotifyWarehouse is deprecated, exclude it"_ → remove from plan
+- _"The namespace should be MY_COMPANY, not ACME"_ → update prefix
+- _"Keep the package as com.puma"_ → skip repackaging
+- _"Yes, separate data module for settings"_ → flag for `/fluent-data-module-scaffold`
+- _"Looks good, proceed"_ → move to Phase 2
+
+If the user says nothing controversial or confirms, proceed to Phase 2. If they correct something, update the analysis and re-present if the change is significant (e.g., namespace change affects all rule keys).
+
 ### Phase 2: Planning Gate
 
 #### Pre-flight Chain (Three-Level)
@@ -177,14 +328,14 @@ Before restructuring any source code, run the three-level pre-flight check:
    - Check `plan: "APPROVED"` — If missing, BLOCK: `→ BLOCKED: PLAN_REQUIRED — Run /fluent-feature-plan first`
    - If both approved, skip to implementation referencing the plan's relevant sections
 2. **Multi-artifact work** (onboarding as part of larger feature): STOP. Invoke `/fluent-feature-plan` first
-3. **Standalone source-onboard work** (no feature context):
+3. **Standalone module-convert work** (no feature context):
    - Check `accounts/<PROFILE>/tasks/` for a task plan with `Status: APPROVED`
    - If approved task plan found, skip to implementation
    - If no plan, continue to the Planning Gate below
 
-**MANDATORY: Present a restructuring plan before making ANY changes.** Use the template from `PLAN_TEMPLATE.md` in the `fluent-feature-plan` skill as the base structure. Every table row must carry a Source column (NEW/EXISTING/MODIFIED/REUSED/OOTB). Extend with the source-onboard-specific sections below.
+**MANDATORY: Present a restructuring plan before making ANY changes.** Use the template from `PLAN_TEMPLATE.md` in the `fluent-feature-plan` skill as the base structure. Every table row must carry a Source column (NEW/EXISTING/MODIFIED/REUSED/OOTB). Extend with the module-convert-specific sections below.
 
-Write the plan to: `accounts/<PROFILE>/tasks/<YYYY-MM-DD>-source-onboard-<slug>.md`. Set `Status: PENDING`.
+Write the plan to: `accounts/<PROFILE>/tasks/<YYYY-MM-DD>-module-convert-<slug>.md`. Set `Status: PENDING`.
 
 **Source-onboard specific sections** (in addition to the standard template):
 
@@ -342,11 +493,19 @@ For each discovered rule class:
    - Classes that are rule implementations --> `plugins/rules/<alias>/src/main/java/`
 
 **Classification heuristics:**
-- Extends `BaseRule`/`Rule` or has `@RuleInfo` --> rule
+- Extends `BaseRule`/`Rule` (SDK or project-local) or has `@RuleInfo` --> rule
+- Is a custom base class that wraps SDK `Rule`/`BaseRule` (e.g., project-local `BaseRule`, `ContextWrapper`) --> **framework** (goes to `plugins/util/`)
+- Is a custom exception class --> **framework** (goes to `plugins/util/`)
 - Is an `enum`, has only getters/setters, or has `@Data`/`@Builder` --> type
 - Is a helper/utility (static methods, service patterns, no rule inheritance) --> util
+- Is a service class (dependency injection, API calls, no rule inheritance) --> util
 - Unclear --> ask user, default to rules
 
+**Package rename decision (ask in Phase 1.5 findings):**
+- If the project uses a custom package (e.g., `com.puma.*`), ask: _"The source uses package `com.puma.*`. Do you want to keep this or repackage to `com.fluentcommerce.*`?"_
+- **Recommend keeping the original** for large codebases (100+ files) — repackaging causes massive import churn with no runtime benefit
+- Only repackage if the user explicitly requests it or the package conflicts with another deployed module
+
 #### Step 3.3: Fix Common Structural Issues
 
 Apply these fixes automatically (all tracked in the plan):
@@ -473,6 +632,43 @@ plugin_list (name filter: <ACCOUNT_PREFIX>)
 | Rule key format matches deployed format | PASS/FAIL per rule |
 | Account prefix is consistent | PASS/FAIL |
 
+#### Step 4.3b: Workflow Rule Cross-Reference (like-for-like proof)
+
+The restructured module must be functionally equivalent — every rule that workflows reference must still be registered under the **exact same key**. Structure changes; behavior must not.
+
+1. **Collect rule keys** from the new `module.json` → `newKeys[]`
+2. **Collect deployed rule keys** from `plugin_list` that match the module's account prefix → `deployedKeys[]`
+3. **Download workflows** that reference any of the deployed keys:
+   ```
+   workflow_list → for each workflow:
+     workflow_get (entityType, entitySubtype)
+   ```
+4. **Extract workflow rule references**: Grep each workflow JSON for rule keys in `rulesets[].rules[].name`
+5. **Cross-reference table:**
+
+```markdown
+## Workflow Rule Cross-Reference
+
+| Rule Key | In New module.json? | In Deployed module? | Referenced In Workflows | Status |
+|----------|--------------------|--------------------|------------------------|--------|
+| MY_PROFILE.order.ValidateOrder | Yes | Yes (v2.1) | ORDER::HD (ruleset: ON_VALIDATION) | MATCH |
+| MY_PROFILE.order.CreateFulfilment | Yes | Yes (v2.1) | ORDER::HD (ruleset: FULFIL) | MATCH |
+| MY_PROFILE.webhook.NotifyWarehouse | Yes | No (new) | — | NEW (no workflow ref yet) |
+| OLD_PREFIX.order.LegacyCheck | No | Yes (v1.0) | ORDER::HD (ruleset: ON_VALIDATION) | BREAK — workflow references key not in new module |
+```
+
+6. **Verdicts:**
+   - **MATCH**: Same key in new module.json, deployed, AND workflow → safe
+   - **NEW**: In new module.json but not deployed or in workflows → safe (new rule, not yet wired)
+   - **BREAK**: In workflow but NOT in new module.json → **FAIL** — deployment would break this workflow ruleset
+   - **ORPHAN**: In new module.json but not in any workflow → WARN (registered but unused)
+
+7. **If any BREAK found:** STOP. Present the breaks to the user with the old key → new key mapping and ask whether to:
+   - Preserve the old key format in module.json (recommended for zero-disruption)
+   - Accept the key change and update the workflow JSON to match (requires workflow redeployment)
+
+**This step is the "like-for-like" proof**: if all workflow-referenced rules show MATCH, the converted module is a drop-in replacement. Deploy the module and workflows continue working without changes.
+
 #### Step 4.4: Functional Checklist
 
 Present a manual verification checklist to the user:
@@ -665,19 +861,22 @@ fc-module-ext/
 
 ```bash
 # Onboard decompiled JAR output into a module
-/fluent-source-onboard accounts/MY_PROFILE/SOURCE/backend/.decompiled/fc-module-ext/
+/fluent-module-convert accounts/MY_PROFILE/SOURCE/backend/.decompiled/fc-module-ext/
 
 # Onboard loose Java files with explicit module name
-/fluent-source-onboard ./my-rules/ --module-name my-returns
+/fluent-module-convert ./my-rules/ --module-name my-returns
 
 # Dry run — analyze and plan only, don't modify anything
-/fluent-source-onboard accounts/MY_PROFILE/SOURCE/backend/legacy-project/ --dry-run
+/fluent-module-convert accounts/MY_PROFILE/SOURCE/backend/legacy-project/ --dry-run
 
 # Onboard without attempting build (e.g., missing SDK locally)
-/fluent-source-onboard accounts/MY_PROFILE/SOURCE/backend/old-module/ --skip-build
+/fluent-module-convert accounts/MY_PROFILE/SOURCE/backend/old-module/ --skip-build
+
+# Convert an existing plugin to module format
+/fluent-module-convert accounts/MY_PROFILE/SOURCE/backend/my-legacy-plugin/
 
 # Repair an existing module with structural issues
-/fluent-source-onboard accounts/MY_PROFILE/SOURCE/backend/fluentcommerce-fc-module-ext/
+/fluent-module-convert accounts/MY_PROFILE/SOURCE/backend/fluentcommerce-fc-module-ext/
 ```
 
 ## Post-Execution: Feedback Capture
@@ -686,13 +885,13 @@ After completing this skill (whether success or failure), write a feedback recor
 
 1. **Classify outcome:** `SUCCESS` (completed cleanly), `PARTIAL_SUCCESS` (completed after fixing issues), `FAILURE` (could not complete), `BLOCKED` (prereq missing), `USER_CORRECTED` (user overrode approach)
 2. **Build record:** Create a `feedback-record-v1` JSON object with:
-   - `skill`: `"fluent-source-onboard"`
+   - `skill`: `"fluent-module-convert"`
    - `feature`: feature slug if applicable, null otherwise
    - `phases`: trace of each phase with PASS/FAIL/SKIP
    - `learnings`: any gotchas discovered during execution
    - `userCorrections`: any corrections the user provided
 3. **Redact secrets:** Strip tokens, passwords, API keys. Keep business identifiers.
-4. **Append** one JSON line to `accounts/<PROFILE>/feedback/fluent-source-onboard.jsonl`
+4. **Append** one JSON line to `accounts/<PROFILE>/feedback/fluent-module-convert.jsonl`
 5. **Update** `accounts/<PROFILE>/feedback/index.json` counters (create with `mkdir -p` if missing)
 
 **Skip capture if:** The execution was trivially simple (e.g., user asked a question, no actual write operation happened).

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

@@ -136,8 +136,8 @@ servicepoint, wave, returns, b2c-sample-data, b2c-sample-data-inventory
 |------|-------------|-----------|-------------|---------|
 | **REFERENCE** | Standard Fluent Commerce modules from repository. Deployed via `fluent module install <name>`. | Yes (OOTB rules) | No (closed-source) | `fluent-commerce/core`, `fluent-commerce/order` |
 | **CUSTOM_EXTENSION** | Account-specific modules with custom Rubix rules. Built from Java source. | Yes (custom rules) | Yes (under `accounts/<PROFILE>/SOURCE/backend/`) | `fluent-commerce/fc-module-custom-extension` |
-| **CUSTOM_WORKFLOW** | Workflow definitions packaged as deployable modules. | No | Workflow JSON in module ZIP | `fluent-commerce/fc-workflow-order-hm-updated` |
-| **CUSTOM_DATA** | Configuration, settings, sample data, access control. No executable rules. | No | JSON/config files in module ZIP | `HM`, `hm-inventory-data`, `hm/global-access` |
+| **CUSTOM_WORKFLOW** | Workflow definitions packaged as deployable modules. | No | Workflow JSON in module ZIP | `fluent-commerce/fc-workflow-order-acme-updated` |
+| **CUSTOM_DATA** | Configuration, settings, sample data, access control. No executable rules. | No | JSON/config files in module ZIP | `ACME`, `acme-inventory-data`, `acme/global-access` |
 
 **All types must be deployed** — even reference modules are deployed per-retailer via `fluent module install`.
 
@@ -236,10 +236,10 @@ console.log(age > 3600 ? 'stale' : 'fresh');
       }
     ],
     "customWorkflow": [
-      { "name": "fluent-commerce/fc-workflow-order-hm-updated", "version": "1.0.0" }
+      { "name": "fluent-commerce/fc-workflow-order-acme-updated", "version": "1.0.0" }
     ],
     "customData": [
-      { "name": "HM", "version": "1.0.13" }
+      { "name": "ACME", "version": "1.0.13" }
     ]
   },
   "referenceArtifacts": [
@@ -254,10 +254,10 @@ console.log(age > 3600 ? 'stale' : 'fresh');
   ],
   "undeployedModules": [
     {
-      "name": "fluent-commerce/fc-module-hm-return",
+      "name": "fluent-commerce/fc-module-acme-return",
       "version": "0.0.6",
       "moduleType": "configuration_only",
-      "sourcePath": "accounts/<PROFILE>/SOURCE/backend/fluentcommerce-fc-module-hm-return",
+      "sourcePath": "accounts/<PROFILE>/SOURCE/backend/fluentcommerce-fc-module-acme-return",
       "deploymentStatus": "not_deployed"
     }
   ],

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

@@ -852,7 +852,7 @@ Every Mystique manifest follows this top-level structure:
 | `plugins` | `MystiquePlugin[]` | `[]` | External component bundle URLs or setting references |
 | `orchestrationAlias` | `string` | none | Overrides the `module` value the app sends to the Transition API. OMS App uses `"adminconsole"` so `modules: ["adminconsole"]` in workflow user actions. Store App uses `"servicepoint"` as its orchestration alias (distinct from the manifest setting name `fc.mystique.manifest.store`). |
 
-**Store App context & location switching:** When `context.level` is `"location"`, the app scopes all queries to the active location. Set `"switcher": true` and `"role": ["STORE", "STORE_ASSISTANT"]` to enable the OOTB location dropdown. The switcher only appears when the user has roles at multiple locations. Location is persisted in `localStorage["mystique.auth.context.location"]` (stores ID, not ref). Deep-link to a specific location with `?user.location.ref=<LOC_REF>` after the hash path. See `knowledge/platform/mystique-routing.md` §"Store App — Default Location via URL Parameter" for full resolution order and permission enforcement.
+**Context switching (Store + OMS):** When `context.level` is `"location"` (Store) or `"retailer"` (OMS), the app scopes queries to the active context. Set `"switcher": true` and the appropriate `"role"` array to enable the OOTB dropdown. The switcher only appears when the user has roles at multiple contexts. Context is persisted in `localStorage` — `mystique.auth.context.location` (Store, stores ID) or `mystique.auth.context.retailer` (OMS, stores ID). Deep-link with `?user.location.ref=<REF>` (Store) or `?user.retailer.ref=<REF>` (OMS) after the hash path. See `knowledge/platform/mystique-routing.md` §"Context Switching" for full resolution order and permission enforcement.
 
 ### Route Types
 

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

@@ -2114,8 +2114,8 @@ The `<namespace>` segment identifies WHO built the component. Choose based on co
 | Context | Namespace Strategy | Example |
 |---------|-------------------|---------|
 | **Fluent Commerce OOTB** | `fc` (reserved — never use) | `fc.list`, `fc.page`, `fc.card.attribute` |
-| **Partner / SI company** | Company abbreviation (2-6 chars, lowercase) | `acme`, `tcs`, `dxc`, `wipro` |
-| **Client / brand** | Brand abbreviation or project code | `nike`, `coles`, `woolies`, `proj1` |
+| **Partner / SI company** | Company abbreviation (2-6 chars, lowercase) | `acme`, `partner1`, `partner2`, `mysi` |
+| **Client / brand** | Brand abbreviation or project code | `brandx`, `retailx`, `storeco`, `proj1` |
 | **Feature-scoped** | Feature or domain name | `appeasement`, `returns`, `sourcing` |
 | **Internal / prototype** | Team or project prefix | `demo`, `poc`, `hackathon` |
 

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

@@ -444,7 +444,7 @@ Present the full plan content to the user and wait for approval before generatin
 | `-> READY: <path>` | Project directory scaffolded | `-> READY: accounts/MY_PROFILE/SOURCE/frontend/mystique-plugin-curbside/` |
 | `-> NEXT: /fluent-<skill>` | Ready for manifest wiring | `-> NEXT: /fluent-mystique-builder` |
 | `-> BLOCKED: <reason>` | Cannot proceed | `-> BLOCKED: PLAN_REQUIRED -- Write a plan via /fluent-feature-plan` |
-| `-> SKIP: <reason>` | Existing project covers the domain | `-> SKIP: Extend existing project mystique-plugin-hm. Add component files directly` |
+| `-> SKIP: <reason>` | Existing project covers the domain | `-> SKIP: Extend existing project mystique-plugin-acme. Add component files directly` |
 
 ### Error codes
 

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

@@ -500,7 +500,7 @@ console.groupEnd();
 ```
 
 **Alias naming convention:** `<namespace>.<category>.<component-name>` where:
-- `namespace` is the company/project prefix (e.g., `acme`, `hm`, `curbside`)
+- `namespace` is the company/project prefix (e.g., `acme`, `globex`, `curbside`)
 - `category` is one of `page`, `layout`, `content`, `filter`
 - `component-name` is kebab-case (e.g., `order-tracker`, `store-map`)
 

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

@@ -880,8 +880,8 @@ Variables:
 ```json
 {
   "input": {
-    "ref": "CARRIER_DHL",
-    "name": "DHL Express",
+    "ref": "CARRIER_FAST",
+    "name": "Fast Freight Carrier",
     "type": "SHIPPING",
     "retailer": { "id": "<retailerId>" }
   }

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

@@ -421,7 +421,7 @@ Perform Kahn's algorithm (BFS-based topological sort). The priority field reflec
 ### Skill Existence Validation
 
 After generating the task list, validate that every `skill` field references a real skill. Known valid skills:
-`fluent-module-scaffold`, `fluent-rule-scaffold`, `fluent-workflow-builder`, `fluent-build`, `fluent-settings`, `fluent-module-deploy`, `fluent-workflow-deploy`, `fluent-e2e-test`, `fluent-pre-deploy-check`, `fluent-custom-code`, `fluent-feature-plan`, `fluent-retailer-config`, `fluent-source-onboard`, `fluent-test-data`, `fluent-job-batch`, `fluent-use-case-discover`, `fluent-module-validate`, `fluent-connection-analysis`, `fluent-mystique-builder`, `fluent-mystique-scaffold`, `fluent-mystique-component`
+`fluent-module-scaffold`, `fluent-rule-scaffold`, `fluent-workflow-builder`, `fluent-build`, `fluent-settings`, `fluent-module-deploy`, `fluent-workflow-deploy`, `fluent-e2e-test`, `fluent-pre-deploy-check`, `fluent-custom-code`, `fluent-feature-plan`, `fluent-retailer-config`, `fluent-module-convert`, `fluent-test-data`, `fluent-job-batch`, `fluent-use-case-discover`, `fluent-module-validate`, `fluent-connection-analysis`, `fluent-mystique-builder`, `fluent-mystique-scaffold`, `fluent-mystique-component`
 
 ## Ambiguity Detection
 

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

@@ -397,7 +397,7 @@ event_send({
   "retailerId": "2",
   "attributes": {
     "trackingNumber": "TRACK-001",
-    "carrierRef": "DHL"
+    "carrierRef": "CARRIER_FAST"
   }
 })
 ```

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

@@ -300,17 +300,18 @@ Where:
 - `<env>` — `test`, `sandbox`, `staging`, or `prod` (omitted for prod)
 - `<app>` — `oms`, `store`, or `servicepoint`
 
-### Store App — Location Pre-Selection
+### Context Pre-Selection (Store + OMS)
 
-The Store app operates at `context.level: "location"`. To test a specific store location, append `?user.location.ref=<LOCATION_REF>` **after the hash path**:
+Both apps support pre-selecting a context via URL parameter **appended after the hash path**:
 
-```
-https://<account>.<env>.apps.fluentcommerce.com/store/#/waves?user.location.ref=LOC_SYD_001
-```
+| App | Context Level | URL Parameter | Example |
+|---|---|---|---|
+| **Store** | `location` | `user.location.ref` | `store/#/waves?user.location.ref=LOC_SYD_001` |
+| **OMS** | `retailer` | `user.retailer.ref` | `oms/#/orders?user.retailer.ref=RETAILER_AU` |
 
-Location context resolution order: (1) `user.location.ref` URL param, (2) `localStorage["mystique.auth.context.location"]` (persisted ID from previous selection), (3) first accessible location. The URL param is consumed on load and stripped — localStorage persists across sessions.
+Context resolution order: (1) URL param (consumed on load, then stripped), (2) `localStorage["mystique.auth.context.<type>"]` (persisted ID from previous selection), (3) first accessible context. localStorage persists across sessions.
 
-If the test user lacks AGENT-context permission for that location, the system falls back to the next priority. See `knowledge/platform/mystique-routing.md` §"Store App — Default Location via URL Parameter" for full details.
+If the test user lacks the required role context (AGENT for locations, RETAILER for retailers), the system falls back to the next priority. See `knowledge/platform/mystique-routing.md` §"Context Switching" for full details.
 
 ## Protocol Phases
 

package/content/dev/skills/fluent-workspace-tree/SKILL.md

@@ -146,7 +146,7 @@ accounts/<PROFILE>/
 |   |-- topology/                        (N files) [connection topology maps]
 |   +-- settings/                        (N files) [settings audit]
 |-- tasks/                               (N operational plans)
-|   +-- 2026-02-23-module-scaffold-hm-curbside.md
+|   +-- 2026-02-23-module-scaffold-acme-curbside.md
 +-- sessions/                            (N audit exports)
     +-- session-abc123.json
 ```
@@ -261,7 +261,7 @@ After rendering the tree, suggest next actions based on what's present:
 
 - **No features exist:** "Run /fluent-use-case-discover to create your first feature"
 - **No workflows downloaded:** "Run workflow download to get workflows from the live environment"
-- **No source repos:** "Clone plugin repos into SOURCE/backend/ (or SDK projects into SOURCE/frontend/) or run /fluent-source-onboard"
+- **No source repos:** "Clone plugin repos into SOURCE/backend/ (or SDK projects into SOURCE/frontend/) or run /fluent-module-convert"
 - **Features ready to build:** "Feature <name> is APPROVED -- start with /fluent-rule-scaffold"
 - **Reports exist:** "Recent build report found -- check /fluent-pre-deploy-check status"
 

package/content/knowledge/index.md

@@ -46,16 +46,16 @@ These files are copied into the workspace `knowledge/` directory and are safe fo
 | [platform/interaction-design-patterns.md](platform/interaction-design-patterns.md) | **Decision guide:** given a requirement, asks guided questions → recommends the right Fluent interaction pattern (7 patterns, quick-reference table, guided questions checklist) | `feature-plan`, `use-case-discover`, `workflow-builder`, `mystique-builder`, `custom-code`, `rule-scaffold` |
 | [platform/graphql-in-rules.md](platform/graphql-in-rules.md) | Decision framework and gotchas for GraphQL inside rules | `rule-scaffold`, `custom-code`, `feature-plan`, `feature-explain`, `build`, `module-scaffold` |
 | [platform/graphql-in-rules-reference.md](platform/graphql-in-rules-reference.md) | Detailed DynamicUtils and Apollo usage patterns | `rule-scaffold`, `custom-code`, `feature-plan`, `feature-explain`, `build`, `module-scaffold` |
-| [platform/module-structure.md](platform/module-structure.md) | Module anatomy — types (extension, data, workflow, reference), directory layout, module.json, Maven POM hierarchy, config variables, build, deploy, selective install | `module-scaffold`, `data-module-scaffold`, `module-validate`, `build`, `module-deploy`, `source-onboard`, `custom-code`, `rule-scaffold` |
+| [platform/module-structure.md](platform/module-structure.md) | Module anatomy — types (extension, data, workflow, reference), directory layout, module.json, Maven POM hierarchy, config variables, build, deploy, selective install | `module-scaffold`, `data-module-scaffold`, `module-validate`, `build`, `module-deploy`, `module-convert`, `custom-code`, `rule-scaffold` |
 | [platform/reference-modules.md](platform/reference-modules.md) | OOTB rule catalog by module, rule categories, context mappings, OOTB vs custom decision guide, offline catalog | `rule-scaffold`, `workflow-builder`, `feature-plan`, `module-validate`, `custom-code`, `rule-lookup`, `implementation-map`, `feature-explain`, `rfl-assess`, `trace`, `pre-deploy-check` |
 | [platform/graphql-preflight.md](platform/graphql-preflight.md) | GraphQL validation lifecycle, Relay connection pattern, `first` vs `last` disambiguation, cursor pagination (`after`/`before`), DynamicUtils field-path validation | `mcp-tools`, `mcp-core`, `trace`, `rule-scaffold`, `custom-code`, `e2e-test`, `mystique-builder`, `mystique-assess`, `feature-plan`, `workflow-builder` |
 | [platform/graphql-query-complexity.md](platform/graphql-query-complexity.md) | Query complexity calculator algorithm, 11,111 max limit, optimization strategies | `trace`, `test-data`, `mcp-tools`, `mcp-core`, `e2e-test`, `workflow-builder`, `rule-scaffold`, `custom-code`, `rfl-assess` |
 | [platform/financial-fields.md](platform/financial-fields.md) | Financial field schema — legacy Float vs precise BigDecimal, per-entity field map, mutation input shapes, currency patterns | `rule-scaffold`, `custom-code`, `test-data`, `mystique-builder`, `mystique-component`, `mystique-scaffold`, `feature-plan`, `implementation-map`, `entity-flow-diagnose`, `e2e-test`, `trace` |
 | [platform/reusability-patterns.md](platform/reusability-patterns.md) | Rule/component reuse, naming, parameterization patterns | `rule-scaffold`, `mystique-component`, `feature-plan`, `use-case-discover`, `mystique-scaffold`, `custom-code`, `feature-explain` |
-| [platform/rule-test-patterns.md](platform/rule-test-patterns.md) | RuleExecutor, TestExecutor, WorkflowExecutor, Mockito patterns, ApolloUtils/TestUtils API, query mocks, mutation assertions, fixtures, coverage checklist | `rule-test`, `rule-scaffold`, `custom-code`, `build`, `module-scaffold`, `source-onboard`, `e2e-test`, `pre-deploy-check` |
+| [platform/rule-test-patterns.md](platform/rule-test-patterns.md) | RuleExecutor, TestExecutor, WorkflowExecutor, Mockito patterns, ApolloUtils/TestUtils API, query mocks, mutation assertions, fixtures, coverage checklist | `rule-test`, `rule-scaffold`, `custom-code`, `build`, `module-scaffold`, `module-convert`, `e2e-test`, `pre-deploy-check` |
 | [platform/roles-and-permissions.md](platform/roles-and-permissions.md) | RBAC design questions and runtime permission model | `use-case-discover`, `feature-plan`, `rule-scaffold`, `workflow-builder`, `mystique-builder` |
 | [platform/mystique-manifest-components.md](platform/mystique-manifest-components.md) | Core manifest components and props | `mystique-builder`, `mystique-validate`, `mystique-analyze`, `mystique-diff`, `ui-test`, `feature-plan`, `implementation-map` |
-| [platform/mystique-routing.md](platform/mystique-routing.md) | HashRouter routing, params, link patterns, back buttons | `mystique-builder`, `mystique-validate`, `mystique-preview`, `mystique-analyze`, `mystique-diff`, `ui-test`, `ui-record`, `feature-plan`, `implementation-map` |
+| [platform/mystique-routing.md](platform/mystique-routing.md) | HashRouter routing, params, link patterns, back buttons, context switching (location/retailer URL params, localStorage persistence) | `mystique-builder`, `mystique-assess`, `mystique-preview`, `mystique-diff`, `ui-test`, `ui-record`, `feature-plan`, `implementation-map`, `retailer-config`, `connect`, `e2e-test`, `account-snapshot` |
 | [mermaid-syntax-rules.md](mermaid-syntax-rules.md) | Diagram syntax rules and guardrails | `workflow-analyzer`, `feature-explain`, `implementation-map`, `connection-analysis`, `entity-flow-diagnose`, `feature-plan` |
 
 ### Frontend / SDK docs

package/content/knowledge/platform/module-structure.md

@@ -4,11 +4,11 @@ scope: platform
 description: "Fluent Commerce module anatomy — types (extension, data, workflow, reference), directory structures, module.json format, Maven POM hierarchy, assets, config variables, build process, deployment, and selective install"
 load: on-demand
 priority: high
-relevant-skills: [fluent-module-scaffold, fluent-module-validate, fluent-build, fluent-module-deploy, fluent-source-onboard, fluent-custom-code]
+relevant-skills: [fluent-module-scaffold, fluent-module-validate, fluent-build, fluent-module-deploy, fluent-module-convert, fluent-custom-code]
 version: 1.0
 last-updated: 2026-03-27
 author: user
-evidence: extracted from fluent-module-scaffold, fluent-data-module-scaffold, fluent-module-validate, fluent-build, fluent-module-deploy, fluent-source-onboard SKILL.md files
+evidence: extracted from fluent-module-scaffold, fluent-data-module-scaffold, fluent-module-validate, fluent-build, fluent-module-deploy, fluent-module-convert SKILL.md files
 ---
 
 # Module Structure
@@ -22,8 +22,8 @@ A **module** is the unit of deployment in Fluent Commerce. Everything shipped to
 | Type | Has Java? | Has Assets? | Built with Maven? | Example |
 |------|-----------|-------------|-------------------|---------|
 | **Extension** | Yes (custom Rubix rules) | Optional (workflows, settings) | Yes | `fc-module-my-extensions` |
-| **Data** | No | Yes (locations, networks, carriers, settings, workflows, catalogues) | No | `hm-infra-data` |
-| **Workflow** | No | Workflow JSON only | No | `fc-workflow-order-hm-updated` |
+| **Data** | No | Yes (locations, networks, carriers, settings, workflows, catalogues) | No | `acme-infra-data` |
+| **Workflow** | No | Workflow JSON only | No | `fc-workflow-order-acme-updated` |
 | **Reference** | Yes (OOTB rules, closed-source) | Yes | No (pre-built by Fluent) | `core`, `order`, `fulfilment`, `inventory` |
 
 ### Known Reference Module Names
@@ -802,6 +802,6 @@ public class MyRule implements Rule {
 | Validate module structure | `/fluent-module-validate` |
 | Build and package | `/fluent-build` |
 | Deploy to environment | `/fluent-module-deploy` |
-| Onboard existing source code | `/fluent-source-onboard` |
+| Convert source/plugin to module | `/fluent-module-convert` |
 | Analyze existing custom code | `/fluent-custom-code` |
 | Add a rule to an existing module | `/fluent-rule-scaffold` |

package/content/knowledge/platform/mystique-routing.md

@@ -1,17 +1,20 @@
 ---
 name: mystique-routing
-description: "Mystique routing architecture: HashRouter URL mapping, manifest structure, page params, link patterns, backButtons, homePath. Derived from repo and manifest evidence."
+description: "Mystique routing architecture: HashRouter URL mapping, manifest structure, page params, link patterns, backButtons, homePath, context switching (location/retailer URL params and localStorage persistence). Derived from repo and manifest evidence."
 load: on-demand
 relevant-skills:
   - mystique-builder
-  - mystique-validate
+  - mystique-assess
   - mystique-preview
-  - mystique-analyze
   - mystique-diff
   - ui-test
   - ui-record
   - feature-plan
   - implementation-map
+  - retailer-config
+  - connect
+  - e2e-test
+  - account-snapshot
 ---
 
 # Mystique Routing Architecture