@fluentcommerce/ai-skills 0.1.0

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

@@ -0,0 +1,886 @@
+---
+name: fluent-connect
+description: Guided onboarding wizard to connect to an existing Fluent Commerce account. Discovers CLI profiles, selects retailer, wires MCP servers, prepares workspace, downloads workflows, decompiles JARs, and reports readiness with cached state. Triggers on "connect account", "switch account", "onboard", "wire up", "get started", "setup environment", "connect to fluent", "change account", "setup workspace", "initialize workspace", "discover profiles".
+user-invocable: true
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+argument-hint: [--profile <name>] [--retailer <ref>] [--force]
+---
+
+# Fluent Account Connect
+
+Guided wizard to connect this workspace to an existing Fluent Commerce account. Discovers CLI profiles, selects a retailer target, wires MCP servers, prepares workspace directories, downloads workflows, decompiles JARs, validates connectivity, and persists cached state so subsequent runs are instant.
+
+## Ownership Boundary
+
+This skill owns the "connect to existing account" workflow: profile discovery, retailer selection, MCP wiring, workspace directory setup, JAR decompilation, state caching, and readiness reporting.
+
+- Profile creation from scratch is owned by `/fluent-profile`.
+- Full new-account bootstrap is owned by `/fluent-bootstrap`.
+- MCP tool reference is owned by `/fluent-mcp-tools`.
+- Workflow analysis is owned by `/fluent-workflow-analyzer`.
+- Source code analysis is owned by `/fluent-custom-code`.
+- Module validation is owned by `/fluent-module-validate`.
+
+## When to Use
+
+- "Connect me to an existing Fluent account"
+- "Switch to a different account / retailer"
+- "Set up my workspace for this profile"
+- "Get me ready to work on [account]"
+- "Onboard me" / "get started"
+- "Setup workspace" / "initialize workspace"
+- Re-running to validate an already-connected workspace
+
+## Inputs
+
+| Parameter | Required | Source | Description |
+|-----------|----------|--------|-------------|
+| `--profile <name>` | No | Argument or interactive | CLI profile name. If omitted, wizard discovers and asks. |
+| `--retailer <ref>` | No | Argument or interactive | Retailer ref within the profile. If omitted, wizard discovers and asks. |
+| `--force` | No | Argument | Ignore cached state, re-run full discovery even if nothing changed. |
+
+If both `--profile` and `--retailer` are provided, skip the interactive selection phases and proceed directly to wiring and validation.
+
+---
+
+## Phase 0: Cache Check
+
+Before doing any work, check if workspace state is already current.
+
+### Steps
+
+1. Read `accounts/<PROFILE>/workspace-state.json` — if missing, proceed to Phase 1.
+2. Compute a content hash (see Content Hash section) and compare with `contentHash` in the stored state.
+3. If hashes match and `--force` is NOT set:
+   - Print the stored summary (profile, retailer, workflow count, source repo count, entity counts).
+   - Print "Workspace state is current. Use --force to re-run."
+   - **Stop here.**
+4. If hashes differ or `--force` is set: continue to Phase 1.
+
+If `--profile` was not given, skip cache check and go to Phase 1 (need to discover profiles first).
+
+---
+
+## Phase 1: Profile Discovery
+
+### Step 1.1: List CLI profiles
+
+```bash
+fluent profile list
+```
+
+Also scan the filesystem for profile directories:
+
+```bash
+ls ~/.fluentcommerce/
+```
+
+```powershell
+# PowerShell
+Get-ChildItem "$env:USERPROFILE\.fluentcommerce"
+```
+
+Each subdirectory (excluding `.sessions`, `config.json`) is a potential profile. Each contains `profile.json` with `id`, `baseUrl`, `clientSecret`, `user`.
+
+### Step 1.2: Present profiles to user
+
+Read each `~/.fluentcommerce/<PROFILE>/profile.json` and build a summary table:
+
+| # | Profile | Account | Environment | Base URL |
+|---|---------|---------|-------------|----------|
+| 1 | PROFILE_A | acme | sandbox | acme.sandbox.api.fluentretail.com |
+| 2 | PROFILE_B | globex | test | globex.test.api.fluentretail.com |
+
+**Account identification from base URL:**
+- Pattern: `https://<account>[.<environment>].api.fluentretail.com`
+- `.test.` = test environment
+- `.sandbox.` = sandbox environment
+- No qualifier = **production** (flag with warning)
+
+### Step 1.3: Select profile
+
+If `--profile` was provided, validate it exists in the list. If not, **ask the user** to pick from the discovered profiles.
+
+**If no profiles exist at all:**
+
+> No CLI profiles found. You need to create one first.
+> Use `/fluent-profile` to create a profile, or `/fluent-bootstrap` for a complete new account setup.
+
+Stop and delegate.
+
+---
+
+## Phase 2: Retailer Selection
+
+### Step 2.1: Discover retailers for selected profile
+
+Read retailer files from the profile directory:
+
+```bash
+ls ~/.fluentcommerce/<PROFILE>/retailer.*.json
+```
+
+```powershell
+# PowerShell
+Get-ChildItem "$env:USERPROFILE\.fluentcommerce\<PROFILE>\retailer.*.json"
+```
+
+Each file is named `retailer.<REF>.json` and contains:
+```json
+{ "id": "<retailer_id>", "ref": "<ref>", "user": "<username>" }
+```
+
+### Step 2.2: Present retailers to user
+
+| # | Retailer Ref | Retailer ID | User |
+|---|-------------|-------------|------|
+| 1 | MY_RETAILER | 5 | retailer_admin |
+| 2 | OTHER_RETAILER | 3 | other_admin |
+
+### Step 2.3: Select retailer
+
+If `--retailer` was provided, validate it matches a known retailer file. If not, **ask the user** to pick.
+
+**If no retailers are configured:**
+
+> No retailers found for profile `<PROFILE>`. You can:
+> 1. Register an existing retailer: `fluent profile update <PROFILE> --retailer <REF> --id <ID>`
+> 2. Create a new retailer: use `/fluent-cli-retailer`
+> 3. Full account setup: use `/fluent-bootstrap`
+
+### Step 2.4: Confirm target
+
+Display the confirmed target before proceeding:
+
+```
+Target environment:
+  Profile:     <PROFILE>
+  Account:     <account>
+  Environment: <tier>
+  Base URL:    https://<account>.<tier>.api.fluentretail.com
+  Retailer:    <RETAILER_REF> (ID: <RETAILER_ID>)
+  User:        <username>
+```
+
+> **WARNING: PRODUCTION ENVIRONMENT** — If the base URL has no `.test.` or `.sandbox.` qualifier, display a prominent warning. All operations may affect live data. Ask for explicit confirmation before continuing.
+
+---
+
+## Phase 3: MCP Wiring
+
+### Step 3.1: Check current configuration
+
+Read `.mcp.json` in the workspace root. Check if it already targets the selected profile and retailer:
+
+- `mcpServers["fluent-mcp"].env.FLUENT_PROFILE` matches selected profile?
+- `mcpServers["fluent-mcp-extn"].env.FLUENT_PROFILE` matches selected profile?
+- `mcpServers["fluent-mcp-extn"].env.FLUENT_PROFILE_RETAILER` matches selected retailer ref?
+
+**If already configured correctly:** Report "Already connected to <PROFILE>/<RETAILER>. Validating connectivity..." and skip to Step 3.4.
+
+**If switching from a different profile:** Warn the user: "Currently connected to <OLD_PROFILE>. Switching to <NEW_PROFILE>."
+
+### Step 3.2: Update .mcp.json
+
+Run the existing mcp-setup command:
+
+```bash
+npx @fluentcommerce/ai-skills mcp-setup --profile <PROFILE> --profile-retailer <RETAILER_REF>
+```
+
+This updates `.mcp.json` with:
+- `fluent-mcp` server: `FLUENT_PROFILE=<PROFILE>`
+- `fluent-mcp-extn` server: `FLUENT_PROFILE=<PROFILE>`, `FLUENT_PROFILE_RETAILER=<RETAILER_REF>`
+
+The command uses merge semantics — it preserves existing non-conflicting env vars.
+
+### Step 3.3: Read and verify .mcp.json
+
+After mcp-setup completes, read `.mcp.json` and verify the three env vars from Step 3.1 are set correctly. Display the verified config to the user.
+
+### Step 3.4: Prompt IDE reload
+
+> **ACTION REQUIRED:** The MCP servers read environment variables at startup.
+> You must reload the MCP servers for the new configuration to take effect.
+>
+> - **VS Code:** Restart the extension host or reload window
+> - **Claude Code CLI:** Restart the session
+> - **Cursor:** Cmd+Shift+P -> "MCP: Restart Servers"
+>
+> After reloading, confirm you are back and I will validate connectivity.
+
+**WAIT for user to confirm they have reloaded before proceeding.**
+
+### Step 3.5: Validate connectivity
+
+After user confirms reload:
+
+1. Run `config.validate` (MCP tool) — verify auth strategy is "profile" and no errors
+2. Run `connection.test` (MCP tool) — verify authenticated user, retailer ID, and retailer ref match expectations
+
+**If config.validate returns errors:**
+- Profile load failure: check `~/.fluentcommerce/<PROFILE>/profile.json` exists and is valid JSON
+- Auth not configured: check `.mcp.json` env vars are correct
+- Missing retailer scope: check `FLUENT_PROFILE_RETAILER` is set
+
+**If connection.test fails:**
+- Auth error: credentials may be expired. Suggest `fluent profile update <PROFILE> --username <user> --password <pass>`
+- Network error: check base URL and connectivity
+
+Report the connection status:
+
+```
+MCP Connectivity: OK
+  Auth strategy: profile
+  User:          <username>
+  Retailer:      <RETAILER_REF> (ID: <RETAILER_ID>)
+  Base URL:      https://<account>.<tier>.api.fluentretail.com
+```
+
+---
+
+## Phase 4: Workspace Readiness
+
+### Step 4.1: Ensure workspace directories exist
+
+```bash
+mkdir -p accounts/<PROFILE>/SOURCE
+mkdir -p accounts/<PROFILE>/workflows/<RETAILER_REF>
+mkdir -p accounts/<PROFILE>/analysis
+```
+
+```powershell
+# PowerShell
+New-Item -ItemType Directory -Force -Path "accounts\<PROFILE>\SOURCE", "accounts\<PROFILE>\workflows\<RETAILER_REF>", "accounts\<PROFILE>\analysis"
+```
+
+Directory structure:
+
+```
+accounts/
+  <PROFILE>/
+    SOURCE/                          <- account-level, shared across retailers
+      <repo-name>/
+      .decompiled/<jar-basename>/
+    workflows/                       <- retailer-scoped workflow JSONs
+      <RETAILER_REF>/
+        ORDER__HD.json
+    analysis/                        <- generated reusable artifacts
+    workspace-state.json
+```
+
+SOURCE is at the profile level because plugin code is deployed per-account (shared across retailers). Workflows are scoped by retailer ref inside the `workflows/` directory because they can differ per retailer.
+
+These are idempotent. On Windows with Git Bash, forward slashes and `mkdir -p` work correctly.
+
+### Step 4.2: Check and download workflows
+
+Check if workflows directory has content:
+
+```bash
+ls accounts/<PROFILE>/workflows/<RETAILER_REF>/*.json 2>/dev/null | wc -l
+```
+
+```powershell
+# PowerShell
+(Get-ChildItem "accounts\<PROFILE>\workflows\<RETAILER_REF>\*.json" -ErrorAction SilentlyContinue).Count
+```
+
+**If empty (count is 0):**
+
+**Preferred: MCP-based download (cross-platform, avoids `::` filename issue):**
+
+```
+1. workflow.list(profile: "<PROFILE>", retailer: "<RETAILER_REF>")
+   → get all workflow names (e.g., ORDER::HD, FULFILMENT::HD_WH)
+
+2. For each workflow name:
+   a. workflow.download(profile: "<PROFILE>", retailer: "<RETAILER_REF>", workflow: "<NAME>")
+      → returns full JSON content in response (no file written)
+   b. Sanitize filename: replace :: with __ (e.g., ORDER::HD → ORDER__HD.json)
+   c. Write JSON content to accounts/<PROFILE>/workflows/<RETAILER_REF>/<SANITIZED_NAME>.json
+
+3. Write workflow-file-map.json mapping original names to sanitized filenames:
+   { "ORDER::HD": "ORDER__HD.json", "FULFILMENT::HD_WH": "FULFILMENT__HD_WH.json" }
+```
+
+This approach works identically on Windows, macOS, and Linux because `::` never appears in a filename.
+
+**Fallback: CLI download (if MCP servers not yet connected):**
+
+On macOS/Linux (`::` is valid in filenames):
+
+```bash
+fluent workflow list -p <PROFILE> -r <RETAILER_REF>
+fluent workflow download -p <PROFILE> -r <RETAILER_REF> -w all -o accounts/<PROFILE>/workflows/<RETAILER_REF>/
+```
+
+On Windows (both `-w <name>` and `-w all` fail because the CLI writes `ORDER::HD.json` and `:` is reserved):
+
+```bash
+fluent workflow download -p <PROFILE> -r <RETAILER_REF> -w all --json > accounts/<PROFILE>/workflows/<RETAILER_REF>/workflows-raw.json
+```
+
+Then split into one file per workflow with sanitized names (replace `::` with `__`) and persist `workflow-file-map.json` mapping original workflow name to filename.
+
+Write/update workflow context:
+
+`accounts/<PROFILE>/workflows/<RETAILER_REF>/workflow-context.json`
+
+```json
+{
+  "profile": "<PROFILE>",
+  "retailerRef": "<RETAILER_REF>",
+  "retailerId": "<RETAILER_ID>",
+  "downloadedAt": "<ISO-8601>"
+}
+```
+
+Note: `-r` expects retailer **ref** (e.g., `MY_RETAILER`), not retailer ID.
+
+**If workflows already exist:**
+
+Report count and freshness. If most recent file is older than 7 days, suggest re-downloading:
+
+```bash
+ls -lt accounts/<PROFILE>/workflows/<RETAILER_REF>/*.json | head -5
+```
+
+```powershell
+# PowerShell
+Get-ChildItem "accounts\<PROFILE>\workflows\<RETAILER_REF>\*.json" | Sort-Object LastWriteTime -Descending | Select-Object -First 5
+```
+
+If `workflow-context.json` exists, verify `profile` + `retailerRef` match the active target. If mismatched, re-download workflows into the correct retailer folder and overwrite context.
+
+### Step 4.3: Check source code
+
+```bash
+ls accounts/<PROFILE>/SOURCE/ 2>/dev/null
+```
+
+```powershell
+# PowerShell
+Get-ChildItem "accounts\<PROFILE>\SOURCE" -ErrorAction SilentlyContinue
+```
+
+**If repos with Java source found:**
+
+Report discovered repos. Validate each has expected structure (`module.json`, `pom.xml`, or `src/main/java/`).
+
+**Extract module identity (version + symbolic name):**
+
+For each discovered repo, extract identity using this precedence:
+
+`symbolicName`:
+1. `resources/module.json` → `name` field (preferred)
+2. JAR `META-INF/MANIFEST.MF` → `Bundle-SymbolicName` (if present)
+3. POM fallback → `<groupId>/<artifactId>` (or `<artifactId>` alone if `groupId` missing)
+
+`version`:
+1. `resources/module.json` → `version` field (preferred)
+2. POM → `<project><version>` (fallback to `<project><parent><version>` if module version is omitted or inherited)
+3. JAR manifest → `Implementation-Version` or `Bundle-Version`
+
+POM extraction examples:
+
+```xml
+<!-- Direct version -->
+<project>
+  <groupId>com.fluentcommerce</groupId>
+  <artifactId>fc-module-extensions</artifactId>
+  <version>1.2.3</version>
+  <name>FC Module Extensions</name>
+</project>
+
+<!-- Inherited version (no <version> at project level) -->
+<project>
+  <parent>
+    <version>1.2.3</version>
+  </parent>
+  <artifactId>fc-module-extensions</artifactId>
+</project>
+```
+
+Record where each value came from (e.g., `versionSource: "module.json"` or `versionSource: "pom.parent.version"`) for traceability.
+
+Report format (classify each by type):
+
+```
+Source code:
+  Custom Extension (editable, buildable):
+    - <repo-name-1>/  <symbolic-name> v<X.Y.Z> (N rules, Maven)
+  Configuration-Only (editable, not buildable):
+    - <repo-name-2>/  <symbolic-name> v<X.Y.Z> (workflows + settings, no rules)
+  Reference Modules (read-only):
+    - <module-name>/  <symbolic-name> v<X.Y.Z> (N OOTB rules, JAR)
+```
+
+**Handle double-nested git clone directories:**
+If a directory under SOURCE contains only one subdirectory with a similar name (e.g., `<repo>/<repo>/`), treat the inner directory as the actual module root. This is a common git clone artifact.
+
+**If reference module packages found (module.json + JAR):**
+
+Reference modules have both `module.json` (with full rule metadata) and compiled JARs under `assets/rules/`. Read rule names, descriptions, and version from `module.json` directly — no decompilation needed for metadata. Only decompile if deep analysis of rule implementation logic is requested.
+
+**If only standalone JAR files found (no module.json alongside):**
+
+When a module is deployed but the original source code is not available, look for `.jar` files under `SOURCE/`. If a JAR is found, decompile it to produce browsable source for analysis:
+
+1. **Locate JARs:**
+
+Use `Glob` with pattern `accounts/<PROFILE>/SOURCE/**/*.jar` for cross-platform file discovery. Exclude `target/dependency/` results.
+
+```bash
+find accounts/<PROFILE>/SOURCE/ -name "*.jar" -not -path "*/target/dependency/*" 2>/dev/null
+```
+
+```powershell
+# PowerShell
+Get-ChildItem "accounts\<PROFILE>\SOURCE" -Recurse -Filter "*.jar" | Where-Object { $_.FullName -notlike "*\target\dependency\*" }
+```
+
+2. **Auto-download CFR decompiler if not present, then decompile:**
+
+> **Cross-platform note:** The decompilation commands below use bash syntax (`mkdir -p`, `curl`). On Windows, use Git Bash, WSL, or the PowerShell equivalents shown where available. The `java -jar` and `jar tf` commands work identically on all platforms.
+
+```bash
+# Auto-download CFR (~2MB single JAR, no installation needed)
+if [ ! -f tools/cfr.jar ]; then
+  mkdir -p tools
+  curl -L -o tools/cfr.jar "https://github.com/leibnitz27/cfr/releases/download/0.152/cfr-0.152.jar"
+fi
+
+# Create deterministic decompiled output directory
+mkdir -p accounts/<PROFILE>/SOURCE/.decompiled/<jar-basename>
+
+# Option A: CFR with --jarfilter to extract only rule classes (preferred)
+java -jar tools/cfr.jar "<jar-file>.jar" \
+  --outputdir "accounts/<PROFILE>/SOURCE/.decompiled/<jar-basename>" \
+  --jarfilter "com.fluentcommerce.rule"
+
+# Option B: CFR full decompilation (all classes)
+java -jar tools/cfr.jar "<jar-file>.jar" \
+  --outputdir "accounts/<PROFILE>/SOURCE/.decompiled/<jar-basename>"
+
+# Option C: Fernflower (IntelliJ's built-in decompiler)
+java -jar fernflower.jar <jar-file>.jar accounts/<PROFILE>/SOURCE/.decompiled/<jar-basename>
+
+# Option D: If neither is available, use javap for class listing
+jar tf <jar-file>.jar | grep "\.class$"
+```
+
+```powershell
+# PowerShell — auto-download CFR
+if (-not (Test-Path "tools\cfr.jar")) {
+  New-Item -ItemType Directory -Force -Path "tools"
+  Invoke-WebRequest -Uri "https://github.com/leibnitz27/cfr/releases/download/0.152/cfr-0.152.jar" -OutFile "tools\cfr.jar"
+}
+
+# CFR with --jarfilter
+java -jar tools/cfr.jar "<jar-file>.jar" --outputdir "accounts\<PROFILE>\SOURCE\.decompiled\<jar-basename>" --jarfilter "com.fluentcommerce.rule"
+```
+
+The `--jarfilter` flag restricts decompilation to classes matching the package prefix, keeping output focused on rule logic. If no decompiler is available and `curl`/Java is missing, log a warning and skip decompilation. Record JAR paths for later.
+
+3. **Extract module.json from the JAR** (if present):
+
+```bash
+unzip -p <jar-file>.jar module.json > accounts/<PROFILE>/SOURCE/.decompiled/<jar-basename>/module.json
+```
+
+```powershell
+# PowerShell
+Add-Type -AssemblyName System.IO.Compression.FileSystem
+$jar = [System.IO.Compression.ZipFile]::OpenRead("<jar-file>.jar")
+$entry = $jar.GetEntry("module.json")
+if ($entry) {
+  $stream = $entry.Open()
+  $reader = New-Object System.IO.StreamReader($stream)
+  $reader.ReadToEnd() | Set-Content "accounts\<PROFILE>\SOURCE\.decompiled\<jar-basename>\module.json"
+  $reader.Close(); $stream.Close()
+}
+$jar.Dispose()
+```
+
+4. **Create a `DECOMPILED.md` marker file** in the decompiled output directory:
+
+```markdown
+# Decompiled Source
+
+- **Source JAR:** <jar-filename>.jar
+- **Decompiled on:** <date>
+- **Decompiler:** CFR / Fernflower / javap
+- **Note:** This is decompiled bytecode, not original source. Variable names may be synthetic. Comments and annotations may be incomplete.
+```
+
+After decompilation, `/fluent-custom-code` can analyze the decompiled classes for rule discovery, workflow-rule mapping, and behavior explanation.
+
+> **Decompilation limitations:**
+> - Local variable names may be replaced with synthetic names (`var1`, `var2`)
+> - Comments, Javadoc, and some annotations may be lost
+> - Generic type information may be partially erased
+> - Confidence label should be "low-medium" for decompiled source vs "high" for original
+
+**If neither source nor JAR found:**
+
+> No custom source code or JAR files found under `accounts/<PROFILE>/SOURCE/`.
+> This is not blocking — it means no custom plugins are available for analysis.
+>
+> Options:
+> 1. Clone source repos: `git clone <repo-url>` into `accounts/<PROFILE>/SOURCE/`
+> 2. Copy module JARs: place `.jar` files in `accounts/<PROFILE>/SOURCE/` for decompilation
+> 3. Download from Fluent: if the module is deployed, the JAR may be retrievable from the build artifacts
+
+### Step 4.4: Build deployed rule inventory
+
+Query the live environment for the complete picture of what's deployed.
+
+**4.4a: Query deployed custom rules**
+
+Use the MCP `plugin.list` tool to get all registered orchestration rules. Filter for account-specific rules (prefixed with the account context, not `FLUENTRETAIL.*`):
+
+```
+plugin.list → N total rules
+  - FLUENTRETAIL.*  → platform rules (standard, no source needed)
+  - <ACCOUNT>.*     → custom rules (these need source or JARs)
+```
+
+**4.4b: Cross-reference deployed vs local**
+
+For each custom rule discovered in the live registry:
+
+| Deployed Rule | Local Source? | Local JAR? | Status |
+|---------------|--------------|------------|--------|
+| `<ACCOUNT>.<module>.<RuleName>` | `SOURCE/<repo>/...RuleName.java` | - | Full source |
+| `<ACCOUNT>.<module>.<OtherRule>` | - | `SOURCE/<module>.jar` | Decompiled |
+| `<ACCOUNT>.<module>.<UnknownRule>` | - | - | **Missing** |
+
+**4.4c: Report the inventory**
+
+```
+Deployed Rule Inventory:
+  Total custom rules deployed:     N
+  With full source code:           X  (modifiable)
+  With decompiled source (JAR):    Y  (read-only, can analyze)
+  Missing (no source or JAR):      Z  (cannot analyze)
+```
+
+**4.4d: Recommendations based on inventory**
+
+- **Full source** modules: ready for analysis, modification, and redeployment. Use `/fluent-custom-code` for deep analysis, `/fluent-rule-scaffold` to add new rules, `/fluent-build` to compile.
+- **JAR-only** modules: can analyze behavior via decompiled source. Cannot modify directly. Recommend cloning original source or scaffolding a new extension module.
+- **Missing** modules: flag as a gap. Ask the user to provide the source or JAR.
+
+> **Important:** JAR-decompiled source is read-only for analysis. Never suggest editing decompiled files.
+
+### Step 4.5: Entity count queries
+
+Run lightweight discovery queries to understand what's configured:
+
+```graphql
+{ locations(first: 1) { edges { node { id } } pageInfo { hasNextPage } } }
+{ networks(first: 1) { edges { node { id } } pageInfo { hasNextPage } } }
+{ inventoryCatalogues(first: 1) { edges { node { id } } pageInfo { hasNextPage } } }
+{ productCatalogues(first: 1) { edges { node { id } } pageInfo { hasNextPage } } }
+```
+
+Record presence/absence and approximate counts.
+
+### Step 4.6: Check analysis artifacts
+
+```bash
+ls accounts/<PROFILE>/analysis/ 2>/dev/null
+```
+
+```powershell
+# PowerShell
+Get-ChildItem "accounts\<PROFILE>\analysis" -ErrorAction SilentlyContinue
+```
+
+If artifacts exist (e.g., `custom-code/source-map.json`, `module-validate/*.report.json`), report their age and freshness. If no artifacts exist, note it as a future step.
+
+If the user explicitly asked for source analysis/readiness artifacts, run `/fluent-custom-code <PROFILE> --retailer <RETAILER_REF>` now instead of deferring.
+
+---
+
+## Phase 5: Persist State and Report
+
+### Step 5.1: Write per-profile state
+
+Write `accounts/<PROFILE>/workspace-state.json`:
+
+```json
+{
+  "schema": "workspace-state-v1",
+  "profile": "<PROFILE>",
+  "contentHash": "<sha256-hex>",
+  "createdAt": "<ISO-8601>",
+  "updatedAt": "<ISO-8601>",
+  "environment": {
+    "account": "<account-name>",
+    "tier": "<test|sandbox|production>",
+    "baseUrl": "<base-url>",
+    "retailerRef": "<RETAILER_REF>",
+    "retailerId": "<RETAILER_ID>"
+  },
+  "discovery": {
+    "workflows": { "count": 0, "downloaded": true, "path": "accounts/<PROFILE>/workflows/<RETAILER_REF>" },
+    "modules": { "installed": [], "count": 0 },
+    "sourceRepos": [
+      { "name": "<repo-name>", "symbolicName": "<symbolic-name>", "version": "<X.Y.Z>", "versionSource": "<module.json|pom|pom.parent>", "hasModuleJson": true, "ruleCount": 0 }
+    ],
+    "decompiledRepos": [],
+    "entities": { "locations": 0, "networks": 0, "inventoryCatalogues": 0, "productCatalogues": 0 },
+    "ruleInventory": { "total": 0, "withSource": 0, "withJar": 0, "missing": 0 },
+    "connectivity": { "status": "OK", "user": "<username>", "retailer": "<tradingName>" }
+  },
+  "mcpConfig": { "exists": true, "hasOfficialServer": true, "hasExtensionServer": true, "profileMatch": true },
+  "nextSteps": []
+}
+```
+
+### Step 5.2: Write/merge workspace index
+
+Write or merge into `accounts/workspace-index.json`:
+
+```json
+{
+  "schema": "workspace-index-v1",
+  "updatedAt": "<ISO-8601>",
+  "profiles": {
+    "<PROFILE>": {
+      "status": "READY",
+      "retailer": "<RETAILER_REF>",
+      "account": "<account-name>",
+      "tier": "<tier>",
+      "stateHash": "<sha256-hex>"
+    }
+  }
+}
+```
+
+If the index already exists, read it first and merge the new profile entry. Do not overwrite other profiles.
+
+### Step 5.3: Readiness report
+
+Present a comprehensive summary:
+
+```
+================================================================
+  FLUENT CONNECT: Readiness Report
+================================================================
+
+  Profile:      <PROFILE>
+  Account:      <account> (<tier>)
+  Retailer:     <RETAILER_REF> (ID: <RETAILER_ID>)
+  User:         <username>
+
+  MCP Status:
+    fluent-mcp       [OK] Profile auth
+    fluent-mcp-extn  [OK] Profile auth + retailer scope
+
+  Workspace:
+    Workflows        [OK] N files
+    Source code      [OK] X repos (Y rules with full source)
+    JARs             [OK] Z decompiled (W rules, read-only)
+    Analysis         [--] No artifacts yet
+
+  Modules:
+    <symbolic-name-1>   v<X.Y.Z>  (N rules, source)
+    <symbolic-name-2>   v<X.Y.Z>  (M rules, decompiled)
+
+  Deployed Rule Inventory:
+    Custom rules deployed:   N
+    With full source:        X  [modifiable]
+    With decompiled JAR:     Y  [analyzable, read-only]
+    Missing source:          Z  [blind spot]
+
+  Entities:
+    Locations:       N
+    Networks:        N
+    Catalogues:      N (inventory) / N (product)
+
+  Suggested Next Steps:
+    1. Full analysis:         /fluent-custom-code
+    2. Workflow deep-dive:    /fluent-workflow-analyzer
+    3. Create test data:      /fluent-test-data
+    4. Run E2E tests:         /fluent-e2e-test
+    5. RFL assessment:        /fluent-rfl-assess
+
+  Workspace:      accounts/<PROFILE>/ (source shared, retailer content under <RETAILER_REF>/)
+  State saved to: accounts/<PROFILE>/workspace-state.json
+================================================================
+```
+
+### Capability Matrix
+
+| Capability | Requires | Status Logic |
+|-----------|----------|-------------|
+| GraphQL operations | MCP connected | `connection.test` OK |
+| Event dispatch | MCP connected + retailer scope | connection OK + retailerId present |
+| Workflow analysis | Workflows downloaded | workflow JSON count > 0 |
+| Full code analysis | Source repos present | `SOURCE/` has repos with `src/main/java/` |
+| JAR-based analysis | Decompiled JARs present | `SOURCE/.decompiled/*/` exists |
+| Code + workflow cross-ref | Workflows + any source | workflows + (source or decompiled) |
+| Rule modification | Full source available | repo has original Java + pom.xml |
+| Analysis reuse | Artifacts exist + fresh | `analysis/` has files and not stale |
+| Complete rule coverage | All deployed rules have source | no "missing" in inventory |
+
+### Blocked Capabilities
+
+If any capability is blocked, explain what's needed and how to fix it.
+
+---
+
+## Content Hash
+
+The content hash determines whether workspace state is current. Recompute on every run and compare with the stored hash.
+
+### What to hash
+
+1. **Profile config:** `~/.fluentcommerce/<PROFILE>/profile.json`
+2. **Retailer configs:** all `~/.fluentcommerce/<PROFILE>/retailer.*.json` files
+3. **Source repo listing:** sorted list of directory names under `accounts/<PROFILE>/SOURCE/`
+4. **Workflow file listing:** sorted list of `.json` filenames in `accounts/<PROFILE>/workflows/<RETAILER_REF>/`
+5. **JAR/ZIP listing:** sorted list of `.jar` and `.zip` files under `accounts/<PROFILE>/SOURCE/`
+
+### How to compute
+
+Use Node.js (always available):
+
+```bash
+node -e "
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const h = crypto.createHash('sha256');
+const profile = process.argv[1];
+const home = process.env.HOME || process.env.USERPROFILE;
+
+// 1. Profile config
+const profFile = path.join(home, '.fluentcommerce', profile, 'profile.json');
+if (fs.existsSync(profFile)) h.update(fs.readFileSync(profFile));
+
+// 2. Retailer configs
+const profDir = path.join(home, '.fluentcommerce', profile);
+if (fs.existsSync(profDir)) {
+  fs.readdirSync(profDir).filter(f => f.startsWith('retailer.') && f.endsWith('.json')).sort()
+    .forEach(f => h.update(fs.readFileSync(path.join(profDir, f))));
+}
+
+// 3. Source repo listing
+const srcDir = path.join('accounts', profile, 'SOURCE');
+if (fs.existsSync(srcDir)) {
+  fs.readdirSync(srcDir, {withFileTypes:true}).filter(e => e.isDirectory()).map(e => e.name).sort()
+    .forEach(n => h.update('src:' + n));
+}
+
+// 4. Workflow file listing (retailer-scoped)
+const retailer = process.argv[2];
+const wfDir = path.join('accounts', profile, 'workflows', retailer);
+if (fs.existsSync(wfDir)) {
+  fs.readdirSync(wfDir).filter(f => f.endsWith('.json')).sort()
+    .forEach(f => h.update('wf:' + f));
+}
+
+// 5. JAR/ZIP listing
+if (fs.existsSync(srcDir)) {
+  const jars = [];
+  function findJars(d) {
+    for (const e of fs.readdirSync(d, {withFileTypes:true})) {
+      if (['target','dist','node_modules','.git'].includes(e.name)) continue;
+      const f = path.join(d, e.name);
+      if (e.isDirectory()) findJars(f);
+      else if (e.name.endsWith('.jar') || e.name.endsWith('.zip')) jars.push(f.replace(/\\\\/g,'/'));
+    }
+  }
+  findJars(srcDir);
+  jars.sort().forEach(j => h.update('jar:' + j));
+}
+
+console.log(h.digest('hex'));
+" <PROFILE> <RETAILER_REF>
+```
+
+Any change (new workflow download, new repo clone, profile update, new JAR file) produces a new hash and triggers a re-run.
+
+---
+
+## Idempotency
+
+This skill is designed to be run multiple times safely:
+
+1. **Cached state matches:** If content hash hasn't changed, print summary and stop immediately.
+2. **Already configured:** If `.mcp.json` already targets the correct profile/retailer, skip mcp-setup. Still validate connectivity.
+3. **Directories exist:** `mkdir -p` is idempotent.
+4. **Workflows downloaded:** Report count and freshness. Do not re-download unless user requests or `--force` is used.
+5. **Source cloned:** Report repos found. Do not modify.
+6. **Artifacts exist:** Report age. Do not regenerate.
+
+### Switching Accounts
+
+When the user runs `/fluent-connect` with a different profile than currently configured:
+
+1. Detect the mismatch by reading `.mcp.json` first
+2. Warn: "Currently connected to <OLD_PROFILE>. Switching to <NEW_PROFILE>."
+3. Run mcp-setup with the new profile
+4. Require IDE reload
+5. Validate the new connection
+6. Persist new workspace state
+7. Report readiness for the new account
+
+---
+
+## Error Handling
+
+| Phase | Error | Resolution |
+|-------|-------|-----------|
+| 0 | workspace-state.json corrupted | Delete and re-run full discovery |
+| 1 | No profiles exist | Delegate to `/fluent-profile` |
+| 1 | `fluent` CLI not found | Install: `npm i -g @fluentcommerce/cli` |
+| 2 | No retailers for profile | Register via `fluent profile update` or `/fluent-cli-retailer` |
+| 3 | mcp-setup fails | Check `npx @fluentcommerce/ai-skills --help` works and retry mcp-setup |
+| 3 | connection.test auth failure | Update credentials: `fluent profile update <PROFILE> --username <user> --password <pass>` |
+| 3 | connection.test network error | Verify base URL and network access |
+| 4 | Workflow download fails | Check profile/retailer context. May need `fluent profile use <PROFILE> --retailer <REF>` first |
+| 4 | Decompiler not found | Log warning with install instructions. Skip decompilation, record JAR paths for later. |
+| 4 | Permission error on mkdir | Check workspace write permissions |
+
+## Delegation Table
+
+| Situation | Delegate To |
+|-----------|------------|
+| No profiles exist | `/fluent-profile` |
+| Need to create new account | `/fluent-bootstrap` |
+| Need to create retailer | `/fluent-cli-retailer` |
+| MCP tool reference | `/fluent-mcp-tools` |
+| Workflow deep analysis | `/fluent-workflow-analyzer` |
+| Source code analysis | `/fluent-custom-code` |
+| Settings management | `/fluent-settings` |
+| Test data creation | `/fluent-test-data` |
+
+## Cross-Platform Compatibility
+
+All commands in this skill are shown in both **Bash** (macOS/Linux/Git Bash on Windows) and **PowerShell** (native Windows) where they differ. Commands that are identical on all platforms (e.g., `fluent profile list`, `node -e`, `npx`) are shown once.
+
+**Shell detection:** AI agents should check `process.platform` (Node.js) or `$PSVersionTable` (PowerShell) to pick the right variant. In Claude Code on Windows, the shell is Git Bash so POSIX syntax works.
+
+### Path reference
+
+| Bash | PowerShell | Notes |
+|------|-----------|-------|
+| `~/.fluentcommerce/` | `$env:USERPROFILE\.fluentcommerce\` | Home directory |
+| `2>/dev/null` | `-ErrorAction SilentlyContinue` | Suppress errors |
+| `mkdir -p <path>` | `New-Item -ItemType Directory -Force -Path <path>` | Create nested dirs |
+| `ls <path>` | `Get-ChildItem <path>` | List directory |
+| `ls <path> \| wc -l` | `(Get-ChildItem <path>).Count` | Count files |
+| `ls -lt <path> \| head -5` | `Get-ChildItem <path> \| Sort-Object LastWriteTime -Descending \| Select-Object -First 5` | Most recent files |
+| `find <path> -name "*.jar"` | `Get-ChildItem <path> -Recurse -Filter "*.jar"` | Recursive file search |
+| `unzip -p file.jar entry` | `[System.IO.Compression.ZipFile]::OpenRead(...)` | Extract from JAR/ZIP |
+
+### Windows-specific notes
+
+- The `fluent` CLI must be in PATH.
+- Workflow filenames may fail on Windows when names include reserved characters (for example `::`); use `--json` export + filename normalization fallback.
+- `java`, `mvn`, and `jar` commands work identically on all platforms if installed and in PATH.