@fluentcommerce/ai-skills 0.13.0 → 0.15.0

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

@@ -1,11 +1,12 @@
 ---
 name: fluent-workspace-tree
-description: Read-only directory tree visualization of the workspace file system — renders an annotated tree showing folders, files, artifact counts per directory, and optional status overlays. This is a filesystem structure view (like the Unix `tree` command), not a live account inventory. ROUTING PRIORITY — if the prompt says "directory tree", "workspace tree", "folder layout", "artifact counts per folder", "show directory structure", "show me the tree", or "workspace layout", route HERE — do NOT route to fluent-feature-status. fluent-feature-status scans status.json files and produces a feature lifecycle table; this skill renders the filesystem tree like Unix `tree`. It does NOT handle feature lifecycle status tables (use fluent-feature-status), HTML dashboards (use fluent-feature-status), or account environment snapshots (use fluent-account-snapshot).
+description: Read-only directory tree visualization of the workspace file system with annotated folders, artifact counts, and optional status overlays. Renders a filesystem structure view like the Unix tree command.
 user-invocable: true
 allowed-tools: Bash, Read, Glob, Grep
 argument-hint: [--profile PROFILE] [--section source|workflows|features|reports|analysis|tasks|sessions] [--depth N]
 cursor-tier: auto
 ---
+<!-- routing-notes: ROUTING PRIORITY — if the prompt says "directory tree", "workspace tree", "folder layout", or "workspace layout", route HERE — do NOT route to fluent-feature-status. fluent-feature-status scans status.json files; this skill renders the filesystem tree. Does NOT handle feature lifecycle tables (→ fluent-feature-status) or account snapshots (→ fluent-account-snapshot). -->
 
 # Workspace Tree Visualization
 
@@ -146,7 +147,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 +262,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/domain-model.md

@@ -555,6 +555,7 @@ event into the workflow engine — enabling automatic rule execution on entity c
 | **Virtual Catalogue** | Virtual Position | `VIRTUAL_CATALOGUE`, `VIRTUAL_POSITION` | Both: No |
 | **Control Group** | Control | `CONTROL_GROUP`, `CONTROL` | Both: No |
 | **Return Order** | Return Fulfilment | `RETURN_ORDER`, `RETURN_FULFILMENT` | Both: Yes |
+| **Job** `[SCHEMA]` | Batch | `JOB`, `BATCH` | JOB: Yes, BATCH: Yes `[SCHEMA: observed in API, not in official docs]` |
 | **Billing Account** | Credit Memo, Invoice, Payment, Payment Transaction | `BILLING_ACCOUNT`, `CREDIT_MEMO`, `INVOICE`, `PAYMENT`, `PAYMENT_TRANSACTION` | All: Yes |
 
 **Key implications:**

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

package/content/knowledge/platform/permissions-and-contexts.md

@@ -234,10 +234,10 @@ A single role assignment can carry **multiple contexts** — e.g., one FINANCE_U
 User A1 has ADMIN role at RETAILER context for Retailer 1 → can access Retailer 1 data only.
 
 **Example 2 — Admin access to multiple retailers:**
-User A2 has ADMIN role at RETAILER context for Retailer 1 AND Retailer 2 → can access both. The context switcher in the UI allows filtering by retailer.
+User A2 has ADMIN role at RETAILER context for Retailer 1 AND Retailer 2 → can access both. The context switcher in the UI allows filtering by retailer. See [mystique-routing.md § Context Switching](mystique-routing.md#context-switching--default-location--retailer-via-url-parameter) for URL parameter deep-linking (`user.retailer.ref`) and localStorage persistence.
 
 **Example 3 — Store access to specific locations:**
-User S1 has STORE_ASSISTANT role at AGENT context for Location 1 AND Location 2 under Retailer 1 → can access Retailer 1 data filtered to those two locations. The context switcher filters by retailer-specific data (fulfilments only).
+User S1 has STORE_ASSISTANT role at AGENT context for Location 1 AND Location 2 under Retailer 1 → can access Retailer 1 data filtered to those two locations. The context switcher filters by retailer-specific data (fulfilments only). See [mystique-routing.md § Context Switching](mystique-routing.md#context-switching--default-location--retailer-via-url-parameter) for URL parameter deep-linking (`user.location.ref`) and localStorage persistence.
 
 ### Decision guide: Setting up a new user
 

package/content/knowledge/platform/rule-test-patterns.md

@@ -2,7 +2,7 @@
 name: rule-test-patterns
 description: "Reusable test patterns for Fluent Commerce Rubix backend rules: RuleExecutor, TestExecutor, WorkflowExecutor, Mockito, query mocks, mutation assertions, ApolloUtils, TestUtils API, fixtures, coverage checklist, and POM dependency guidance. Derived from module-core 2.2.1, module-order 2.1.0, and official util-test documentation."
 version: 2.0
-relevant-skills: [fluent-rule-test, fluent-rule-scaffold, fluent-custom-code, fluent-build, fluent-module-scaffold, fluent-source-onboard]
+relevant-skills: [fluent-rule-test, fluent-rule-scaffold, fluent-custom-code, fluent-build, fluent-module-scaffold, fluent-module-convert]
 load: on-demand
 ---
 

package/content/knowledge/platform/workflow-json-structure.md

@@ -107,7 +107,7 @@ Field order inside each ruleset:
 **Key rules:**
 - `rules[]` comes BEFORE `triggers[]`
 - `userActions: []` ALWAYS present (even if empty)
-- NO `subtype` field on rulesets — entity-level `entitySubtype` handles routing
+- NO `subtype` field on event-triggered rulesets — entity-level `entitySubtype` handles routing. Exception: rulesets with `userActions[]` MUST have `subtype` matching `entitySubtype` for UI button visibility (see `user-action-contract.md`).
 - `eventType` is typically `"NORMAL"`
 
 ## Ruleset Matching (4 criteria)

package/content/mcp-extn/skills/fluent-mcp-core/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: fluent-mcp-core
-description: Official Fluent Commerce CLI MCP server setup and operations. Configure the built-in MCP server, run health checks, validate GraphQL connectivity, build/validate queries, and manage workflow list/download operations. ROUTING PRIORITY over fluent-bootstrap and fluent-connect when the prompt explicitly mentions "built-in MCP server", "official MCP server", "GraphQL connectivity", "set up the built-in MCP", or "set up the MCP server and test". If the user says "set up" combined with "MCP server" or "GraphQL connectivity", route HERE only when official-server setup/testing is the primary task, not when MCP wiring is just one step inside existing-account onboarding. Do not route send-event, verify-it-landed, Transition API discovery, extension-only GraphQL (`graphql_planOperation`, `graphql_query`, `graphql_queryAll`), runtime connection switching, or extension workflow-get prompts here — those belong to fluent-mcp-tools. Do not prefer this skill when the prompt is about CI/CD, automation pipelines, or non-interactive `fluent mcp server --stdio` rollout patterns — route those to fluent-cli-mcp-cicd instead. HARD NEGATIVE — Do NOT route here for: existing-account connection/onboarding prompts that also ask to discover CLI profiles, choose retailer context, or get the workspace ready to work (→ fluent-connect), 'connection_list' / 'connection_switch' / 'connection management' / 'workflow_get' / 'workflow_transitions' / 'event_send' / 'graphql_query' (→ fluent-mcp-tools for MCP extension server tools). Triggers on "mcp core setup", "built-in mcp server", "official mcp server", "graphql connectivity", "graphql validate", "workflow download", "set up the built-in MCP", "set up mcp server", "test graphql connectivity".
+description: Official Fluent Commerce CLI MCP server setup and operations. Configure the built-in MCP server, run health checks, validate GraphQL connectivity, and manage workflow downloads. Use for built-in MCP server setup or GraphQL connectivity testing.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <operation> [--profile name] [--retailer ref]
 cursor-tier: auto
 ---
+<!-- routing-notes: ROUTING PRIORITY over fluent-bootstrap and fluent-connect when prompt explicitly mentions "built-in MCP server", "official MCP server", "GraphQL connectivity". Route HERE only when official-server setup/testing is the primary task. Do not route send-event, Transition API, extension-only GraphQL, runtime connection switching, or extension workflow-get here (→ fluent-mcp-tools). Do not route CI/CD pipelines or non-interactive stdio setup here (→ fluent-cli-mcp-cicd). HARD NEGATIVE — Do NOT route for existing-account onboarding (→ fluent-connect) or MCP extension tools like connection_list, event_send, graphql_query (→ fluent-mcp-tools). -->
 
 # Fluent MCP Core
 

package/content/mcp-extn/skills/fluent-mcp-tools/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: fluent-mcp-tools
-description: Fluent Commerce MCP extension server tools reference. Canonical owner of event sending (event_build + event_send), event verification, extension-first GraphQL execution, runtime connection management, extension workflow operations, and all 59 MCP extension tools. Use for "send event", "dispatch event", "verify it landed", event flow forensics, GraphQL operations, batch ingestion, connection switching, or webhook validation. ROUTING PRIORITY over fluent-transition-api for ANY prompt that says "send" + event name (e.g., "send a ConfirmShipment event"), "dispatch event", "verify it landed", or "send and verify". Transition API is read-only action discovery — if the user wants the event SENT or VERIFIED, route HERE. ROUTING PRIORITY over fluent-bootstrap for event/MCP operations. ROUTING PRIORITY for MCP extension server tools — route here instead of fluent-mcp-core or fluent-workflow when prompt mentions MCP extension tools like workflow_get, workflow_transitions, connection_list, event_send, graphql_query, batch_send. HARD NEGATIVE — Do NOT route here for: "which CLI command family" / "mixed CLI question" / "CLI overview" / "work across profiles, retailers, workflows, settings" (→ fluent-cli-reference handles broad CLI triage questions). HARD NEGATIVE — do NOT route conceptual Event API questions here: if the user is asking what event statuses, categories, `sourceEvents`, orchestration routing, run-once semantics, or audit-vs-log actions mean, route to fluent-event-api even if the prompt mentions `event_list` or other MCP tool names. Do not route Prometheus monitoring (use fluent-system-monitoring), pure built-in server setup, official GraphQL connectivity-only, or `workflow_download` prompts (those belong to fluent-mcp-core). Key knowledge — graphql-preflight.md, graphql-query-complexity.md, sync-vs-async-patterns.md. Triggers on "mcp tools", "send fluent event", "send event", "send a ConfirmShipment", "send a", "dispatch event", "verify it landed", "send and verify", "event flow inspect", "trace event payloads", "fluent graphql", "graphql query", "batch ingestion".
+description: Fluent Commerce MCP extension server tools reference covering all 59 tools including event sending, GraphQL execution, batch ingestion, and connection management. Use for sending events, dispatching, or verifying MCP operations.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <operation> [entity-type] [entity-ref]
 cursor-tier: manual
 ---
+<!-- routing-notes: ROUTING PRIORITY over fluent-transition-api for ANY prompt that says "send" + event name, "dispatch event", "verify it landed", or "send and verify". ROUTING PRIORITY over fluent-bootstrap for event/MCP operations. ROUTING PRIORITY for MCP extension server tools — route here instead of fluent-mcp-core or fluent-workflow when prompt mentions extension tools like workflow_get, connection_list, event_send, graphql_query, batch_send. HARD NEGATIVE — Do NOT route here for broad CLI triage questions (→ fluent-cli-reference) or conceptual Event API questions about event statuses, categories, sourceEvents, orchestration routing, run-once semantics (→ fluent-event-api). Do not route Prometheus monitoring (→ fluent-system-monitoring), built-in server setup, or workflow_download (→ fluent-mcp-core). -->
 
 # Fluent MCP Tools
 
@@ -579,7 +580,7 @@ To discover which attributes an entity supports and how they appear in mutations
 
 ### Schema Tool Annotations
 
-All 57 MCP extension tools now advertise MCP `ToolAnnotations` (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`). MCP clients that respect annotations can automatically distinguish read-only operations (queries, introspection, cache status) from write operations (event_send, entity_create, workflow_upload).
+All 59 MCP extension tools now advertise MCP `ToolAnnotations` (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`). MCP clients that respect annotations can automatically distinguish read-only operations (queries, introspection, cache status) from write operations (event_send, entity_create, workflow_upload).
 
 ## Batch Ingestion
 

package/content/rfl/skills/fluent-rfl-assess/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-rfl-assess
-description: Run a Ready For Launch (RFL) assessment on a Fluent Commerce implementation. Analyzes workflows, rules, settings, and integrations for production readiness. Triggers on "rfl assessment", "ready for launch check", "go-live readiness", "production audit".
+description: Run a Ready For Launch (RFL) assessment on a Fluent Commerce implementation analyzing workflows, rules, settings, and integrations. Trigger on go-live readiness or production audit needs.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [--profile name] [--retailer ref]

package/docs/01-first-session.md

@@ -0,0 +1,175 @@
+# Your First Session
+
+> 20 minutes to a productive session, with just enough prompts to get confidence.
+> Works with Claude Code, Codex, and Gemini CLI.
+
+Use this in order, exactly. Ask the next prompt only after the previous one is done.
+
+## 1) First 20 minutes (minimum viable setup)
+
+> **`npm` vs `npx`:** `npm install -g` permanently installs a tool. `npx` runs a package without installing. All `@fluentcommerce/ai-skills` commands use `npx`.
+
+1. Install and connect your workspace (replace placeholders):
+
+```bash
+# Pick your target:
+npx @fluentcommerce/ai-skills install --profile MY_PROFILE                  # Claude Code (default)
+npx @fluentcommerce/ai-skills install --target codex --profile MY_PROFILE   # Codex
+npx @fluentcommerce/ai-skills install --target gemini --profile MY_PROFILE  # Gemini CLI
+
+# Verify everything is working:
+npx @fluentcommerce/ai-skills doctor
+```
+
+2. Connect the workspace to your Fluent account:
+
+| In Claude Code | In Codex or Gemini CLI |
+|---|---|
+| `/fluent-connect --profile MY_PROFILE` | `Use the fluent-connect skill to connect this workspace with profile MY_PROFILE.` |
+
+3. Confirm what was created:
+
+`Show me the workspace tree`
+
+If your output is confusing, try:
+
+`What folders were created for this account?` and share the reply with your teammate.
+
+## 2) Three things newcomers usually ask first
+
+### A. “What can I do with this?”
+
+Use these read-only prompts first:
+
+`What's deployed on this account?`
+- **Triggers:** `fluent-account-snapshot` (read-only, safe)
+- **You get:** workflows, modules, settings, retailers — a full implementation inventory
+- **Artifact:** summary in `accounts/<PROFILE>/analysis/`
+
+`How does Home Delivery work end-to-end?`
+- **Triggers:** `fluent-feature-explain` (read-only, safe)
+- **You get:** state machine diagrams, cross-entity sequence diagrams, rules table, settings dependencies
+- **Artifact:** `accounts/<PROFILE>/features/home-delivery/architecture.md`
+
+### B. “How do I debug?”
+
+`Why is order HD-001 stuck in BOOKED?`
+- **Triggers:** `fluent-trace` (read-only, safe)
+- **You get:** event timeline, which rules fired or failed, root cause, and suggested fix
+- **No artifacts** — output is inline in the conversation
+
+### C. “How do I start building?”
+
+`Help me define use cases for return orders`
+- **Triggers:** `fluent-use-case-discover` (interactive wizard)
+- **You get:** structured business spec with completeness score
+- **Artifact:** `accounts/<PROFILE>/features/return-order/spec.md`
+
+Then, after review:
+
+`Plan the return order feature`
+- **Triggers:** `fluent-feature-plan` (presents plan, waits for approval)
+- **You get:** 18-section implementation plan with diagrams, rules inventory, risk assessment
+- **Artifact:** `accounts/<PROFILE>/features/return-order/plan.md`
+
+**Wait for approval** after plan review before any change. Say `”approved”` to proceed.
+
+## 3) Prompt ladder (don’t memorize anything)
+
+Pick one path and follow it:
+
+**Path 1: Explore only** (all read-only, safe)
+
+| Prompt | Skill triggered |
+|--------|----------------|
+| `Show me what's deployed on this account` | `fluent-account-snapshot` |
+| `Show me the workspace tree` | `fluent-workspace-tree` |
+| `Explain how Home Delivery works end-to-end` | `fluent-feature-explain` |
+| `List all in-progress features` | `fluent-feature-status` |
+
+**Path 2: Investigate one issue** (all read-only, safe)
+
+| Prompt | Skill triggered |
+|--------|----------------|
+| `Why is order HD-001 stuck in BOOKED?` | `fluent-trace` |
+| `Show me the event timeline for that order` | `fluent-trace` (continued) |
+| `What settings does this flow use?` | `fluent-settings` |
+| `What transitions are allowed for ORDER?` | `fluent-transition-api` |
+
+**Path 3: Build one small feature** (creates artifacts, approval required)
+
+| Prompt | Skill triggered |
+|--------|----------------|
+| `Help me define use cases for <feature>` | `fluent-use-case-discover` |
+| `Plan the <feature> feature` | `fluent-feature-plan` |
+| `Approved` | Plan gate clears, implementation begins |
+| `Scaffold the module` | `fluent-module-scaffold` |
+| `Build the workflow from the plan` | `fluent-workflow-builder` |
+
+Pause after each step to check output before continuing.
+
+## 4) Where artifacts land (so you can find them quickly)
+
+- `accounts/<PROFILE>/workflows/<RETAILER>/`
+  - Downloaded workflow JSONs
+  - `workflow-context.json`
+- `accounts/<PROFILE>/features/<slug>/`
+  - `spec.md` (requirements)
+  - `plan.md` (approved implementation plan)
+  - `architecture.md` (feature explain output)
+  - `status.json` (current lifecycle state)
+- `accounts/<PROFILE>/SOURCE/backend/`
+  - Java/Maven sources the skill reads and writes
+- `accounts/<PROFILE>/analysis/`
+  - Persisted reverse-engineering outputs
+- `accounts/<PROFILE>/reports/`
+  - Quality gates, pre-deploy checks, and validation outputs
+- `accounts/<PROFILE>/sessions/`
+  - Audit trail exports from sessions
+
+Use this command-style prompt when you lose track:
+
+`What artifacts were created in the last two hours and where?`
+
+This avoids rebuilding context from scratch.
+
+## 5) What to do when nothing responds
+
+1. `npx @fluentcommerce/ai-skills doctor` in the workspace folder
+2. `Show me the installed skill list`
+3. Ask the specific issue: `What failed when I tried to run ...?`
+4. Retry the same first prompt for the task.
+
+## 6) Keep it beginner-safe
+
+- Start with read-only prompts. No code changes in first 20 minutes.
+- Approve only after the plan is clear.
+- Use explicit nouns in prompts: order ref, workflow name, module name.
+- If a prompt fails, simplify it and retry rather than changing everything.
+
+At the end of the day, copy this into team docs:
+
+- one example of a successful debug (`why is this order stuck`)
+- one example of a successful feature plan approval
+- one artifact map screenshot from `Show me the workspace tree`
+
+That becomes your team memory baseline.
+
+## 7) Setting up a second workspace
+
+Skills, agents, and platform knowledge install **globally** to `~/.claude/` — once installed, they're available in every workspace. A second workspace only needs MCP config (credentials are per-workspace):
+
+```bash
+mkdir client-b && cd client-b
+git init
+npx @fluentcommerce/ai-skills mcp-setup --profile CLIENT_B_PROFILE
+npx @fluentcommerce/ai-skills doctor   # verify everything
+```
+
+That's it — `mcp-setup` wires MCP, generates a starter `CLAUDE.md`, and knowledge falls back to the global copy. If you want a full local copy of knowledge and docs too, run `install` instead of `mcp-setup`.
+
+## 8) Next reading (after this)
+
+- [prompt-guide.md](02-prompt-guide.md) — progressive skill navigator (which of the 60+ skills matter, and when)
+- [Setup Reference & Troubleshooting](05-getting-started.md) — prerequisites, workspace layout, and troubleshooting
+- [onboarding-plan.md](04-onboarding-plan.md) — structured two-week team ramp