@storelayer/mcp-server 0.2.1 → 0.3.0

package/SKILL.md

@@ -1,274 +1,482 @@
-# Store Layer MCP Server — Skill Guide for Claude Desktop
+# Store Layer — AI Skill Guide
 
-You have access to the **Store Layer** MCP server, which lets you manage loyalty programs, promotions, wallets, users, events, referrals, and more for a specific project.
+You have access to the **Store Layer** MCP server. This guide helps you build loyalty programs, promotions, and customer engagement systems effectively.
 
-## How It Works
+## Pipeline: How to Build Loyalty Programs
 
-All tools are dynamically loaded from the Store Layer API. Tool names use underscores (e.g., `promotions_evaluate_cart`). Tools that require a `userId` parameter operate on a specific external user's data.
+**Always follow this pipeline** when building loyalty features. Do not skip steps.
 
----
+### Step 1: Discover Current State
+
+Before creating anything, understand what exists:
+
+```
+1. project_get_config          → currency, timezone, cart format
+2. project_list_rules          → existing loyalty rules
+3. promotions_get_active       → active promotions
+4. events_get_stats            → event flow (what types come in)
+5. wallet_get_balance (userId) → existing asset types in use
+```
+
+### Step 2: Design the Program
+
+Map the user's intent to domains:
+
+| User wants...                | Domains involved                |
+| ---------------------------- | ------------------------------- |
+| "Earn points on purchase"    | Rules + Wallet                  |
+| "10% off orders over $50"    | Promotions                      |
+| "Buy 2 get 1 free"           | Promotions (script)             |
+| "Refer a friend, get $10"    | Referral + Wallet               |
+| "Double points this weekend" | Rules (with date conditions)    |
+| "Coupon code for 20% off"    | Promotions + Coupons            |
+| "VIP tier discounts"         | Promotions (conditions on user) |
+
+**Propose the full plan before creating anything.** Show the user what you'll create.
 
-## Available Tools by Domain
-
-### External Users (`external_users`)
-| Tool | Description |
-|------|-------------|
-| `external_users_get_user` | Get a user by ID |
-| `external_users_list_users` | List users with pagination |
-| `external_users_lookup_user` | Smart lookup: tries ID match, then email fallback |
-| `external_users_register` | Register a new user |
-| `external_users_update` | Update a user |
-| `external_users_remove` | Remove a user |
-
-### Wallet (`wallet`) — all require `userId`
-| Tool | Description |
-|------|-------------|
-| `wallet_get_balance` | Get balance for all asset types |
-| `wallet_list_transactions` | List transaction history with filters |
-| `wallet_credit` | Add assets (points, tokens, etc.) |
-| `wallet_debit` | Remove assets |
-
-### Loyalty Events (`events`)
-| Tool | Description |
-|------|-------------|
-| `events_get` | Get a single event by ID |
-| `events_list` | List events with filters (type, status, pagination) |
-| `events_get_stats` | Aggregate stats: total, processed, pending |
-
-### Referral (`referral`)
-| Tool | Description |
-|------|-------------|
-| `referral_get_config` | Get referral program config |
-| `referral_list_codes` | List referral codes with filters |
-| `referral_get_code_by_referrer` | Look up code by referrer ID |
-| `referral_validate_code` | Check if a code is valid |
-| `referral_list_referrals` | List referral records |
-| `referral_list_events` | List referral audit events |
-| `referral_get_stats` | Aggregate stats |
-| `referral_get_leaderboard` | Leaderboard ranked by referrals |
-| `referral_create_code` | Create a referral code |
-| `referral_apply_code` | Apply a code for a referee |
-| `referral_deactivate_code` | Deactivate a code |
-
-### Project (`project`)
-| Tool | Description |
-|------|-------------|
-| `project_get_config` | Get project config (currency, timezone, settings) |
-| `project_list_rules` | List loyalty rules |
-| `project_get_rule` | Get a single rule by ID |
-| `project_list_integrations` | List integrations |
-| `project_list_resources` | List resource definitions |
-| `project_add_rule` | Create a loyalty rule |
-| `project_update_rule` | Update a rule |
-| `project_remove_rule` | Delete a rule |
-| `project_test_conditions` | Test conditions against sample data |
-
-### Promotions (`promotions`)
-| Tool | Description |
-|------|-------------|
-| `promotions_list` | List promotions with filters |
-| `promotions_get_active` | Get all active promotions |
-| `promotions_list_coupons` | List coupons |
-| `promotions_list_usage` | List usage/redemption records |
-| `promotions_get_stats` | Stats for a specific promotion |
-| `promotions_get_aggregate_stats` | Aggregate stats across all promotions |
-| `promotions_create` | Create a promotion |
-| `promotions_create_coupon` | Create a coupon for a promotion |
-| `promotions_evaluate_cart` | **Evaluate a cart against active promotions** |
-
-### Support (`support`)
-| Tool | Description |
-|------|-------------|
-| `support_get_ticket` | Get a ticket by ID |
-| `support_list_tickets` | List tickets with filters |
-| `support_get_stats` | Aggregate ticket stats |
-| `support_create_ticket` | Create a ticket |
-| `support_update_ticket` | Update a ticket |
-
-### Surveys (`surveys`)
-| Tool | Description |
-|------|-------------|
-| `surveys_get` | Get a survey by ID |
-| `surveys_list` | List surveys |
-| `surveys_list_responses` | List responses for a survey |
-| `surveys_get_stats` | Survey analytics |
-| `surveys_create` | Create a survey |
-| `surveys_submit_response` | Submit a response |
-
-### Workflows (`workflows`)
-| Tool | Description |
-|------|-------------|
-| `workflows_list` | List workflow executions |
-| `workflows_get` | Get a workflow execution with steps |
-
-### Stores (`stores`)
-| Tool | Description |
-|------|-------------|
-| `stores_get_store` / `stores_list_stores` | Read stores |
-| `stores_create_store` / `stores_update_store` / `stores_remove_store` | Manage stores |
-| `stores_get_facility` / `stores_list_facilities` | Read facilities |
-| `stores_create_facility` / `stores_update_facility` / `stores_remove_facility` | Manage facilities |
-
-### Resources (`resources`)
-| Tool | Description |
-|------|-------------|
-| `resources_list` / `resources_get` | Read resource definitions |
-| `resources_add` / `resources_update` / `resources_remove` | Manage resource definitions |
+### Step 3: Build & Test Incrementally
+
+For **rules**: draft conditions → test with `project_test_conditions` → create rule
+For **promotions**: create as `draft` → test with `promotions_evaluate_cart` → activate
+For **coupons**: create coupon → test cart with coupon code → verify
+
+### Step 4: Verify End-to-End
+
+After building, verify the chain works:
+
+- For rules: event type → conditions → actions → wallet credit
+- For promotions: cart → conditions → script → discounts
+- Summarize what was built and how pieces connect
 
 ---
 
-## Domain Knowledge
+## Recipes
 
-### Promotions Engine
+### Recipe 1: Points-for-Purchase (Earn 1 point per dollar)
 
-Every promotion has an `itemsDiscountComputation` script that computes per-item discounts. There are no predefined discount types — the script IS the discount logic.
+**Domains:** Rules + Wallet
 
-**Script environment:**
-- `$('cart')` — full cart object. `$('cart').items` is the items array. Each item: `{ id, price, quantity, category, tags, ...custom }`
-- `$('cart').total` — cart total
-- `$('user')` — current user (if userId provided)
-- `$('couponCodes')` — applied coupon codes
+**Step 1:** Create the rule:
 
-**Return format:** Array of `{ id: string, amount: number }` where `id` = item ID and `amount` = discount to subtract.
+```json
+project_add_rule({
+  "name": "1 Point Per Dollar",
+  "conditions": {
+    "conditions": [
+      { "leftValue": "{{ event.type }}", "operator": "equals", "rightValue": "purchase", "rightType": "string" }
+    ],
+    "combinator": "AND"
+  },
+  "actions": [
+    {
+      "type": "reward",
+      "config": {
+        "assetType": "points",
+        "amount": "{{ event.payload.amount }}",
+        "description": "Purchase reward: {{ event.payload.amount }} points"
+      }
+    }
+  ],
+  "resources": {
+    "event": { "type": "purchase" }
+  }
+})
+```
+
+**Step 2:** Test conditions:
+
+```json
+project_test_conditions({
+  "conditions": {
+    "conditions": [
+      { "leftValue": "{{ event.type }}", "operator": "equals", "rightValue": "purchase", "rightType": "string" }
+    ],
+    "combinator": "AND"
+  },
+  "context": {
+    "event": { "type": "purchase", "payload": { "amount": 49.99 } }
+  }
+})
+```
 
-**Condition system:**
-- Structure: `{ conditions: [{ leftValue, operator, rightValue, rightType }], combinator: "AND" | "OR" }`
-- Fields: `cart.total`, `cart.itemCount`, `cart.uniqueItemCount`, `cart.items[0].price`, etc.
-- Operators: `equals`, `notEquals`, `gt`, `gte`, `lt`, `lte`, `contains`, `notContains`, `startsWith`, `endsWith`, `exists`, `notExists`, `regex`, `before`, `after`, `isEmpty`, `isNotEmpty`, `hasKey`
+**Step 3:** Verify wallet (for a test user):
 
-**Stacking modes:**
-- `stackable` — combines with other promotions (default)
-- `exclusive` — highest priority wins, all others excluded
-- `exclusive_group` — highest priority within its group wins
+```json
+wallet_get_balance({ "userId": "test-user-123" })
+```
+
+---
 
-**Cart formats:**
-- **Standard:** Items have `quantity` field. Engine expands internally.
-  ```json
-  { "items": [{ "id": "muffin-001", "price": 3.50, "quantity": 2 }] }
-  ```
-- **Sub-items (pre-expanded):** Each unit is a separate entry with a unique ID and a shared logical ID in another field. Pass `itemIdField` to specify which field to use.
-  ```json
-  { "items": [{ "id": "sub-1", "sku": "muffin-001", "price": 3.50 }, { "id": "sub-2", "sku": "muffin-001", "price": 3.50 }] }
-  ```
+### Recipe 2: Percentage Discount (10% off everything)
 
-**Coupon system:** Promotions can require a coupon code (`requiresCoupon: true`). Create coupons with `promotions_create_coupon`, validate them during cart evaluation by passing `couponCodes`.
+**Domains:** Promotions
 
-#### Promotion Examples
+**Step 1:** Create promotion in draft:
 
-**10% off all items:**
 ```json
-{
+promotions_create({
   "name": "10% Off Everything",
-  "status": "active",
+  "status": "draft",
   "conditions": { "conditions": [], "combinator": "AND" },
   "itemsDiscountComputation": {
     "script": "const items = $('cart').items;\nreturn items.map(item => ({ id: item.id, amount: item.price * 0.10 }));",
     "language": "javascript"
   }
-}
+})
 ```
 
-**$5 off orders over $50:**
+**Step 2:** Test with a cart:
+
 ```json
-{
-  "name": "$5 Off Over $50",
-  "status": "active",
+promotions_evaluate_cart({
+  "cart": {
+    "items": [
+      { "id": "item-1", "price": 25.00, "quantity": 1 },
+      { "id": "item-2", "price": 15.00, "quantity": 2 }
+    ]
+  }
+})
+```
+
+**Step 3:** Check results — verify `summary.totalDiscount` is 10% of total. If correct, activate:
+
+```json
+promotions_update({ "promotionId": "promo_xxx", "status": "active" })
+```
+
+---
+
+### Recipe 3: Threshold Discount ($5 off orders over $50)
+
+**Domains:** Promotions
+
+```json
+promotions_create({
+  "name": "$5 Off Orders Over $50",
+  "status": "draft",
   "conditions": {
-    "conditions": [{ "leftValue": "cart.total", "operator": "gte", "rightValue": 50, "rightType": "number" }],
+    "conditions": [
+      { "leftValue": "cart.total", "operator": "gte", "rightValue": 50, "rightType": "number" }
+    ],
     "combinator": "AND"
   },
   "itemsDiscountComputation": {
     "script": "const items = $('cart').items;\nconst total = items.reduce((s, i) => s + i.price, 0);\nreturn items.map(item => ({ id: item.id, amount: (item.price / total) * 5 }));",
     "language": "javascript"
   }
-}
+})
 ```
 
-**BOGO: buy 2+ shoes, cheapest free:**
+**Key:** The script distributes the $5 proportionally across items by their price share.
+
+---
+
+### Recipe 4: BOGO (Buy 2+ shoes, cheapest free)
+
+**Domains:** Promotions
+
 ```json
-{
+promotions_create({
+  "name": "BOGO Shoes",
+  "status": "draft",
+  "conditions": { "conditions": [], "combinator": "AND" },
   "itemsDiscountComputation": {
     "script": "const shoes = $('cart').items.filter(i => i.category === 'shoes');\nif (shoes.length < 2) return [];\nconst sorted = [...shoes].sort((a, b) => a.price - b.price);\nreturn [{ id: sorted[0].id, amount: sorted[0].price }];",
     "language": "javascript"
   }
-}
+})
 ```
 
-#### Cart Evaluation
+**Test cart must include `category` field on items**, or the filter returns nothing.
+
+---
+
+### Recipe 5: Coupon Code (20% off with code SAVE20)
+
+**Domains:** Promotions + Coupons
+
+**Step 1:** Create promotion requiring coupon:
 
-Use `promotions_evaluate_cart` with:
 ```json
-{
-  "cart": {
-    "items": [
-      { "id": "item-1", "price": 25.00, "quantity": 2, "category": "shoes" },
-      { "id": "item-2", "price": 15.00, "quantity": 1, "category": "accessories" }
-    ]
-  },
-  "userId": "user_123",
-  "couponCodes": ["SAVE10"]
-}
+promotions_create({
+  "name": "20% Off with Code",
+  "status": "active",
+  "requiresCoupon": true,
+  "conditions": { "conditions": [], "combinator": "AND" },
+  "itemsDiscountComputation": {
+    "script": "const items = $('cart').items;\nreturn items.map(item => ({ id: item.id, amount: item.price * 0.20 }));",
+    "language": "javascript"
+  }
+})
+```
+
+**Step 2:** Create the coupon:
+
+```json
+promotions_create_coupon({
+  "promotionId": "promo_xxx",
+  "code": "SAVE20",
+  "maxUses": 1000
+})
 ```
 
-Response includes: `summary` (originalTotal, totalDiscount, finalTotal, appliedCount), `items` (per-item discounts), `applied` (matched promotions with discounts), `notApplied` (unmatched promotions with reasons, human-readable messages, and suggestions), `discounts` (flat discount list), `warnings`, and `usageRecords` (when not dry run).
+**Step 3:** Test with coupon:
+
+```json
+promotions_evaluate_cart({
+  "cart": { "items": [{ "id": "item-1", "price": 50.00, "quantity": 1 }] },
+  "couponCodes": ["SAVE20"]
+})
+```
 
 ---
 
-### Loyalty Rules
+### Recipe 6: Referral Program (Refer a friend, both get 500 points)
+
+**Domains:** Referral + Rules + Wallet
+
+**Step 1:** Check referral config:
+
+```json
+referral_get_config()
+```
 
-Rules trigger when events are ingested. Each rule has conditions (evaluated against runtime context) and actions (executed when conditions match).
+**Step 2:** Create referral code for a user:
 
-**Condition expressions** use Handlebars syntax: `{{ event.type }}`, `{{ event.payload.amount }}`, `{{ user.email }}`, `{{ history.amount }}`
+```json
+referral_create_code({ "referrerId": "user-123" })
+```
 
-**Action types:**
-- `reward` — `{ assetType: "points", amount: 10, description: "Purchase reward" }`. Dynamic: `amount: "{{ event.amount }}"`
-- `integration` — `{ integrationId: "intg_xxx" }` — triggers webhook/Telegram/Slack
-- `apply_referral` / `complete_referral` / `mark_code_used` — referral lifecycle actions
+**Step 3:** Set up a rule to reward on completed referral:
 
-**Rule example — 1 point per dollar spent:**
 ```json
-{
-  "name": "Dollar-to-Points",
+project_add_rule({
+  "name": "Referral Reward",
   "conditions": {
-    "conditions": [{ "leftValue": "{{ event.type }}", "operator": "equals", "rightValue": "purchase", "rightType": "string" }],
+    "conditions": [
+      { "leftValue": "{{ event.type }}", "operator": "equals", "rightValue": "referral.completed", "rightType": "string" }
+    ],
     "combinator": "AND"
   },
-  "actions": [{ "type": "reward", "config": { "assetType": "points", "amount": "{{ event.payload.amount }}", "description": "1 point per dollar" } }]
-}
+  "actions": [
+    {
+      "type": "reward",
+      "config": {
+        "assetType": "points",
+        "amount": 500,
+        "description": "Referral reward"
+      }
+    }
+  ],
+  "resources": {
+    "event": { "type": "referral.completed" }
+  }
+})
 ```
 
 ---
 
-### Events & Ingestion
+### Recipe 7: Stacking Promotions (Member discount + seasonal sale)
 
-Events are sent externally via `POST /api/ingest/events` with an API key. The MCP server can read events but not ingest them directly.
+**Domains:** Promotions (stacking)
 
-**Processing flow:** Event stored → queued → resources resolved → conditions evaluated → actions executed → event marked processed.
+Create two stackable promotions:
 
-**Event payload example:**
 ```json
-{ "type": "purchase", "userId": "user123", "payload": { "orderId": "order_abc", "amount": 99.99, "items": [...] } }
+// Always-on member discount (lower priority)
+promotions_create({
+  "name": "Member 5% Discount",
+  "status": "active",
+  "stackingMode": "stackable",
+  "priority": 1,
+  "conditions": { "conditions": [], "combinator": "AND" },
+  "itemsDiscountComputation": {
+    "script": "return $('cart').items.map(i => ({ id: i.id, amount: i.price * 0.05 }));",
+    "language": "javascript"
+  }
+})
+
+// Seasonal sale (higher priority, also stackable)
+promotions_create({
+  "name": "Summer Sale 15%",
+  "status": "active",
+  "stackingMode": "stackable",
+  "priority": 10,
+  "validFrom": "2026-06-01T00:00:00Z",
+  "validTo": "2026-08-31T23:59:59Z",
+  "conditions": { "conditions": [], "combinator": "AND" },
+  "itemsDiscountComputation": {
+    "script": "return $('cart').items.map(i => ({ id: i.id, amount: i.price * 0.15 }));",
+    "language": "javascript"
+  }
+})
 ```
 
+Both apply. Use `exclusive` stacking mode if only the best should win.
+
+---
+
+## Tool Reference
+
+### Promotions (`promotions_*`)
+
+| Tool                             | Type  | Description                      |
+| -------------------------------- | ----- | -------------------------------- |
+| `promotions_list`                | read  | List promotions with filters     |
+| `promotions_get_active`          | read  | Get all active promotions        |
+| `promotions_list_coupons`        | read  | List coupons for a promotion     |
+| `promotions_list_usage`          | read  | List usage/redemption records    |
+| `promotions_get_stats`           | read  | Stats for a specific promotion   |
+| `promotions_get_aggregate_stats` | read  | Global promotion stats           |
+| `promotions_create`              | write | Create a promotion               |
+| `promotions_update`              | write | Update a promotion               |
+| `promotions_remove`              | write | Delete a promotion               |
+| `promotions_duplicate`           | write | Clone a promotion as draft       |
+| `promotions_create_coupon`       | write | Create a coupon                  |
+| `promotions_bulk_create_coupons` | write | Bulk create 1-1000 coupons       |
+| `promotions_evaluate_cart`       | write | Evaluate cart against promotions |
+
+### Wallet (`wallet_*`) — all require `userId`
+
+| Tool                       | Type  | Description                     |
+| -------------------------- | ----- | ------------------------------- |
+| `wallet_get_balance`       | read  | Get balance for all asset types |
+| `wallet_list_transactions` | read  | Transaction history             |
+| `wallet_credit`            | write | Add assets (points, tokens)     |
+| `wallet_debit`             | write | Spend assets (FEFO order)       |
+
+### Rules (`project_*`)
+
+| Tool                        | Type  | Description                         |
+| --------------------------- | ----- | ----------------------------------- |
+| `project_get_config`        | read  | Project configuration               |
+| `project_list_rules`        | read  | List loyalty rules                  |
+| `project_get_rule`          | read  | Get a single rule                   |
+| `project_list_integrations` | read  | List integrations                   |
+| `project_list_resources`    | read  | List resource definitions           |
+| `project_add_rule`          | write | Create a rule                       |
+| `project_update_rule`       | write | Update a rule                       |
+| `project_remove_rule`       | write | Delete a rule                       |
+| `project_test_conditions`   | write | Test conditions against sample data |
+
+### Events (`events_*`)
+
+| Tool               | Type | Description              |
+| ------------------ | ---- | ------------------------ |
+| `events_get`       | read | Get event by ID          |
+| `events_list`      | read | List events with filters |
+| `events_get_stats` | read | Event stats              |
+
+### Referral (`referral_*`)
+
+| Tool                       | Type  | Description             |
+| -------------------------- | ----- | ----------------------- |
+| `referral_get_config`      | read  | Referral program config |
+| `referral_list_codes`      | read  | List referral codes     |
+| `referral_validate_code`   | read  | Check if code is valid  |
+| `referral_get_stats`       | read  | Aggregate stats         |
+| `referral_get_leaderboard` | read  | Top referrers           |
+| `referral_create_code`     | write | Create a referral code  |
+| `referral_apply_code`      | write | Apply code for referee  |
+| `referral_deactivate_code` | write | Deactivate a code       |
+
+### External Users (`external_users_*`)
+
+| Tool                         | Type  | Description                  |
+| ---------------------------- | ----- | ---------------------------- |
+| `external_users_get_user`    | read  | Get user by ID               |
+| `external_users_list_users`  | read  | List users                   |
+| `external_users_lookup_user` | read  | Smart lookup (ID then email) |
+| `external_users_register`    | write | Register a user              |
+| `external_users_update`      | write | Update a user                |
+
+### Skill & Feedback (`skill_*`)
+
+| Tool                       | Type  | Description                  |
+| -------------------------- | ----- | ---------------------------- |
+| `skill_get_content`        | read  | Get this skill guide content |
+| `skill_list_feedback`      | read  | List feedback entries        |
+| `skill_get_feedback_stats` | read  | Feedback analytics           |
+| `skill_update_content`     | write | Update skill guide           |
+| `skill_submit_feedback`    | write | Report tool usage outcome    |
+
+---
+
+## Discount Script Reference
+
+**Available context:**
+
+- `$('cart')` — full cart object. `$('cart').items` = items array
+- `$('cart').items[n]` — `{ id, price, quantity, category, tags, ...custom }`
+- `$('cart').total` — cart total
+- `$('user')` — current user (if userId provided)
+- `$('couponCodes')` — applied coupon codes array
+
+**Return format:** `Array<{ id: string, amount: number }>` where `id` = item ID, `amount` = discount
+
+**Common patterns:**
+
+```javascript
+// Percentage off all items
+return $("cart").items.map((i) => ({ id: i.id, amount: i.price * RATE }));
+
+// Fixed amount distributed proportionally
+const total = $("cart").items.reduce((s, i) => s + i.price, 0);
+return $("cart").items.map((i) => ({
+  id: i.id,
+  amount: (i.price / total) * FIXED_AMOUNT,
+}));
+
+// Category-specific discount
+return $("cart")
+  .items.filter((i) => i.category === "TARGET")
+  .map((i) => ({ id: i.id, amount: i.price * RATE }));
+
+// Cheapest item free
+const sorted = [...$("cart").items].sort((a, b) => a.price - b.price);
+return [{ id: sorted[0].id, amount: sorted[0].price }];
+```
+
+---
+
+## Condition Operators
+
+`equals`, `notEquals`, `gt`, `gte`, `lt`, `lte`, `contains`, `notContains`, `startsWith`, `endsWith`, `exists`, `notExists`, `regex`, `before`, `after`, `isEmpty`, `isNotEmpty`, `hasKey`
+
+**Condition fields for promotions:** `cart.total`, `cart.itemCount`, `cart.uniqueItemCount`, `cart.items[0].price`, `cart.items[0].category`
+
+**Condition expressions for rules:** `{{ event.type }}`, `{{ event.payload.amount }}`, `{{ user.email }}`, `{{ history.amount }}`
+
 ---
 
-### Resources
+## Common Mistakes
 
-Resources provide runtime context for rule evaluation. Types:
-- **event** — incoming event data
-- **http** — external REST API call
-- **database** — PostgreSQL query via integration
-- **internal** — Store Layer entity data (users, wallets, transactions via registry tools)
-- **payload** — request body data
+1. **Script returns empty array** — Usually a field name mismatch. Check the actual cart item fields (e.g., `category` vs `type`). Always test with `promotions_evaluate_cart` first.
 
-Resources are resolved before rule evaluation. Their data is accessible in condition expressions.
+2. **Promotion not applying** — Check `notApplied` array in evaluate response. It tells you exactly which conditions failed and why.
+
+3. **Rule not firing** — Ensure the event type in conditions matches what's being ingested. Use `events_list` to check actual event types.
+
+4. **Forgot to activate** — Promotions created in `draft` won't apply. Update status to `active` after testing.
+
+5. **Coupon not working** — Promotion must have `requiresCoupon: true` AND the coupon must be passed in `couponCodes` array during evaluation.
+
+6. **Stacking conflicts** — `exclusive` promotions block everything else. Use `stackable` for promotions that should combine. Use `exclusive_group` for "best of group" behavior.
+
+7. **Missing event resource in rules** — Rules require `resources: { event: { type: "..." } }`. Without it, the rule won't match any events.
 
 ---
 
-## Best Practices
+## Feedback
+
+After building a loyalty program, use `skill_submit_feedback` to report the outcome. This helps improve this guide over time.
 
-1. **Start by exploring** — use `promotions_get_aggregate_stats`, `project_get_config`, or list tools to understand the current state before making changes.
-2. **Test before activating** — create promotions in `draft` status, use `promotions_evaluate_cart` to test with sample carts, then set to `active`.
-3. **Use `project_test_conditions`** to validate rule conditions against sample data before saving.
-4. **For destructive actions** (delete, debit), always confirm with the user first.
-5. **Cart evaluation** returns detailed match info — check `applied` for matched promotions with discounts, `notApplied` for unmatched promotions with reasons/suggestions, and `warnings` for coupon validation issues.
+```json
+skill_submit_feedback({
+  "toolName": "promotions.create",
+  "action": "created",
+  "context": "Building a BOGO promotion for shoes",
+  "outcome": "success",
+  "details": "Worked on first try with category filter"
+})
+```

package/dist/index.js

@@ -13662,11 +13662,11 @@ class StdioServerTransport {
 
 // src/index.ts
 var __dirname2 = dirname(fileURLToPath(import.meta.url));
-var SKILL_CONTENT;
+var FALLBACK_SKILL_CONTENT;
 try {
-  SKILL_CONTENT = readFileSync(resolve(__dirname2, "../SKILL.md"), "utf-8");
+  FALLBACK_SKILL_CONTENT = readFileSync(resolve(__dirname2, "../SKILL.md"), "utf-8");
 } catch {
-  SKILL_CONTENT = "Store Layer MCP Server — manage loyalty programs, promotions, wallets, users, events, and referrals. Use the available tools to interact with your project.";
+  FALLBACK_SKILL_CONTENT = "Store Layer MCP Server — manage loyalty programs, promotions, wallets, users, events, and referrals. Use the available tools to interact with your project.";
 }
 var API_URL = (process.env.STORE_LAYER_API_URL || "https://api.storelayer.io").replace(/\/$/, "");
 var API_KEY = process.env.STORE_LAYER_API_KEY;
@@ -13687,6 +13687,24 @@ async function fetchToolManifest() {
   const json = await res.json();
   return json.data.tools;
 }
+async function fetchSkillContent() {
+  try {
+    const url = `${API_URL}/projects/${PROJECT_ID}/internal-skill`;
+    const res = await fetch(url, { headers: apiHeaders() });
+    if (!res.ok) {
+      console.error(`Skill content fetch failed (${res.status}), using fallback`);
+      return { content: FALLBACK_SKILL_CONTENT, version: "local" };
+    }
+    const json = await res.json();
+    if (json.success && json.data?.content) {
+      return { content: json.data.content, version: json.data.version };
+    }
+    return { content: FALLBACK_SKILL_CONTENT, version: "local" };
+  } catch (error2) {
+    console.error("Failed to fetch skill content, using fallback:", error2);
+    return { content: FALLBACK_SKILL_CONTENT, version: "local" };
+  }
+}
 async function executeTool(toolName, params, userId) {
   const url = `${API_URL}/projects/${PROJECT_ID}/internal-tools/${toolName}/execute`;
   const body = { params };
@@ -13739,8 +13757,12 @@ async function main() {
     process.exit(1);
   }
   console.error(`Connecting to Store Layer API at ${API_URL}...`);
-  const manifest = await fetchToolManifest();
+  const [manifest, skill] = await Promise.all([
+    fetchToolManifest(),
+    fetchSkillContent()
+  ]);
   console.error(`Loaded ${manifest.length} tools from Store Layer`);
+  console.error(`Skill guide version: ${skill.version}`);
   const mcpToRegistry = new Map;
   const mcpToManifest = new Map;
   for (const tool of manifest) {
@@ -13748,7 +13770,7 @@ async function main() {
     mcpToRegistry.set(mcpName, tool.name);
     mcpToManifest.set(mcpName, tool);
   }
-  const server = new Server({ name: "store-layer", version: "0.1.0" }, { capabilities: { tools: {}, prompts: {} } });
+  const server = new Server({ name: "store-layer", version: "0.2.0" }, { capabilities: { tools: {}, prompts: {} } });
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: manifest.map((tool) => ({
       name: toMcpName(tool.name),
@@ -13799,7 +13821,7 @@ async function main() {
     prompts: [
       {
         name: "store-layer-guide",
-        description: "Comprehensive guide for using Store Layer tools — covers all domains (promotions, wallets, users, events, referrals, rules), with examples and best practices."
+        description: `Comprehensive guide for using Store Layer tools (v${skill.version}) — covers all domains (promotions, wallets, users, events, referrals, rules), with recipes and best practices.`
       }
     ]
   }));
@@ -13808,13 +13830,13 @@ async function main() {
       throw new Error(`Unknown prompt: ${request.params.name}`);
     }
     return {
-      description: "Store Layer MCP skill guide",
+      description: `Store Layer MCP skill guide (v${skill.version})`,
       messages: [
         {
           role: "user",
           content: {
             type: "text",
-            text: SKILL_CONTENT
+            text: skill.content
           }
         }
       ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storelayer/mcp-server",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "MCP server for Store Layer — manage loyalty programs, promotions, wallets, and more from Claude Desktop, Claude Code, or Cursor.",
   "type": "module",
   "bin": {