@fluentcommerce/ai-skills 0.1.0 → 0.3.0

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

@@ -1,6 +1,6 @@
 ---
 name: fluent-cli-retailer
-description: Manage Fluent retailer lifecycle via CLI. Use for creating and listing retailers, validating profile context, and safely preparing retailer admin access for module/workflow operations.
+description: Manage Fluent retailer lifecycle via CLI. Use for creating and listing retailers, validating profile context, and safely preparing retailer admin access for module/workflow operations. Triggers on "create retailer", "list retailers", "retailer context", "retailer admin", "fluent retailer".
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <create|list> [retailer-ref] [--profile name]
@@ -10,6 +10,8 @@ argument-hint: <create|list> [retailer-ref] [--profile name]
 
 Create and inspect retailers with Fluent CLI, and ensure follow-up context is valid for deployments.
 
+> **New to Fluent CLI?** Start with `/fluent-cli-index` for a complete command reference and routing guide.
+
 ## When to Use
 
 - New retailer setup
@@ -62,6 +64,15 @@ Or create the file directly:
 
 ## Post-Create Validation
 
+After creating a retailer, verify it is ready for use:
+
+1. List retailers to confirm creation: `fluent retailer list -p <PROFILE>`
+2. Verify workflows are accessible: `fluent workflow list -p <PROFILE> -r <NEW_RETAILER_REF>`
+3. Verify settings context: `fluent setting list -p <PROFILE> -r <NEW_RETAILER_REF>`
+4. If workflow list returns empty, this is expected for new retailers — modules must be installed first
+
+### Detailed steps
+
 1. Confirm retailer appears in `fluent retailer list`.
 2. Set active context:
 
@@ -70,7 +81,21 @@ fluent profile use <profile-name> --retailer <retailer-ref>
 fluent profile active
 ```
 
-3. Proceed with module config/install only after active retailer is correct.
+3. **Verify API access works** — run a lightweight query to confirm the retailer is fully provisioned:
+
+```bash
+fluent workflow list -p <profile-name> -r <retailer-ref>
+```
+
+This confirms the CLI can authenticate against the retailer context and the retailer is ready for operations. A new retailer will return an empty list (no workflows yet), which is expected. An auth error here means the retailer user credentials need to be configured via `fluent profile update`.
+
+4. **Verify settings context** — confirm the settings subsystem is accessible:
+
+```bash
+fluent setting list -p <profile-name> -r <retailer-ref>
+```
+
+5. Proceed with module config/install only after active retailer is correct and API access is verified.
 
 ## Important Operational Note
 

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

@@ -1,6 +1,6 @@
 ---
 name: fluent-cli-settings
-description: Manage Fluent CLI settings operations. Use for listing and reading settings by profile/retailer context, wildcard filtering, and validating missing/incorrect setting values before or after module/workflow changes.
+description: Manage Fluent CLI settings operations. Use for listing and reading settings by profile/retailer context, wildcard filtering, and validating missing/incorrect setting values before or after module/workflow changes. Triggers on "list settings", "read setting", "settings list", "fluent setting", "check settings".
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <list|get> [setting-name-or-pattern] [--profile name] [--retailer ref]
@@ -10,6 +10,8 @@ argument-hint: <list|get> [setting-name-or-pattern] [--profile name] [--retailer
 
 Read and validate Fluent settings using CLI commands, with profile/retailer context safety checks.
 
+> **New to Fluent CLI?** Start with `/fluent-cli-index` for a complete command reference and routing guide.
+
 ## When to Use
 
 - User asks to list current settings
@@ -89,6 +91,24 @@ Value: https://...
 Context: retailer=<retailer-ref>
 ```
 
+## Scope Resolution Cascade
+
+When a setting exists at multiple levels, the most specific scope wins:
+
+```
+RETAILER (most specific) → ACCOUNT (fallback) → Platform default (if any)
+```
+
+**Example:** If `webhook.order.created` exists at both RETAILER (contextId=5) and ACCOUNT level, the RETAILER value is used at runtime for that retailer. The ACCOUNT value applies only to retailers that don't have their own override.
+
+**Debugging unexpected values:** Always check both contexts explicitly:
+```bash
+fluent setting get -n "webhook.order.created" -c RETAILER -p <profile> -r <retailer>
+fluent setting get -n "webhook.order.created" -c ACCOUNT -p <profile>
+```
+
+If both return values and the RETAILER one isn't what you expect, the RETAILER setting is what the rules actually use.
+
 ## Common Checks
 
 - Webhook endpoints