@storelayer/mcp-server 0.3.0 → 0.5.0

package/dist/index.js

@@ -6516,11 +6516,6 @@ var require_dist = __commonJS((exports, module) => {
   exports.default = formatsPlugin;
 });
 
-// src/index.ts
-import { readFileSync } from "node:fs";
-import { resolve, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-
 // ../../node_modules/.bun/zod@4.3.6/node_modules/zod/v4/core/core.js
 var NEVER = Object.freeze({
   status: "aborted"
@@ -13661,16 +13656,91 @@ class StdioServerTransport {
 }
 
 // src/index.ts
-var __dirname2 = dirname(fileURLToPath(import.meta.url));
-var FALLBACK_SKILL_CONTENT;
-try {
-  FALLBACK_SKILL_CONTENT = readFileSync(resolve(__dirname2, "../SKILL.md"), "utf-8");
-} catch {
-  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;
-var PROJECT_ID = process.env.STORE_LAYER_PROJECT_ID;
+var SKILLS_REPO = "storelayer/skills";
+var SKILLS_BASE_PATH = "skills/storelayer";
+var SKILL_REFERENCES = [
+  {
+    name: "architecture",
+    description: "Platform architecture and patterns",
+    path: "references/architecture.md"
+  },
+  {
+    name: "wallet",
+    description: "Wallet/ledger system reference",
+    path: "references/wallet.md"
+  },
+  {
+    name: "promotions",
+    description: "Promotion engine reference",
+    path: "references/promotions.md"
+  },
+  {
+    name: "referral",
+    description: "Referral system reference",
+    path: "references/referral.md"
+  },
+  {
+    name: "events",
+    description: "Events and rules reference",
+    path: "references/events.md"
+  },
+  {
+    name: "external-users",
+    description: "Customer management reference",
+    path: "references/external-users.md"
+  },
+  {
+    name: "discount-scripts",
+    description: "Discount script reference",
+    path: "references/discount-scripts.md"
+  },
+  {
+    name: "conditions",
+    description: "Condition engine reference",
+    path: "references/conditions.md"
+  },
+  {
+    name: "mcp-tools",
+    description: "All MCP tools reference",
+    path: "references/mcp-tools.md"
+  }
+];
+var SKILL_AGENTS = [
+  {
+    name: "loyalty-builder",
+    description: "Design and build complete loyalty programs",
+    path: "agents/loyalty-builder.md"
+  },
+  {
+    name: "promo-engineer",
+    description: "Build promotions, discount scripts, and coupon campaigns",
+    path: "agents/promo-engineer.md"
+  },
+  {
+    name: "integration-dev",
+    description: "Set up event ingestion and external integrations",
+    path: "agents/integration-dev.md"
+  }
+];
+var SKILL_TOOLS = [
+  {
+    name: "setup-project",
+    description: "Step-by-step new project setup",
+    path: "tools/setup-project.md"
+  },
+  {
+    name: "test-promotion",
+    description: "Test promotions before activation",
+    path: "tools/test-promotion.md"
+  },
+  {
+    name: "debug-rules",
+    description: "Debug rules and promotions",
+    path: "tools/debug-rules.md"
+  }
+];
 function apiHeaders() {
   return {
     Authorization: `Bearer ${API_KEY}`,
@@ -13678,8 +13748,8 @@ function apiHeaders() {
   };
 }
 async function fetchToolManifest() {
-  const url = `${API_URL}/projects/${PROJECT_ID}/internal-tools`;
-  const res = await fetch(url, { headers: apiHeaders() });
+  const url = `${API_URL}/public/tools`;
+  const res = await fetch(url);
   if (!res.ok) {
     const body = await res.text().catch(() => "");
     throw new Error(`Failed to fetch tool manifest (${res.status}): ${body}`);
@@ -13687,26 +13757,8 @@ 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 url = `${API_URL}/public/tools/${toolName}/execute`;
   const body = { params };
   if (userId)
     body.userId = userId;
@@ -13724,6 +13776,31 @@ async function executeTool(toolName, params, userId) {
     throw new Error(json.error || "Tool execution failed");
   return json.data;
 }
+var contentCache = new Map;
+var CACHE_TTL_MS = 15 * 60 * 1000;
+async function fetchSkillFile(relativePath) {
+  const cacheKey = relativePath;
+  const cached2 = contentCache.get(cacheKey);
+  if (cached2 && Date.now() - cached2.fetchedAt < CACHE_TTL_MS) {
+    return cached2.content;
+  }
+  const url = `https://raw.githubusercontent.com/${SKILLS_REPO}/main/${SKILLS_BASE_PATH}/${relativePath}`;
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(`Failed to fetch ${relativePath} from GitHub (${res.status})`);
+  }
+  const content = await res.text();
+  contentCache.set(cacheKey, { content, fetchedAt: Date.now() });
+  return content;
+}
+async function fetchSkillGuide() {
+  try {
+    return await fetchSkillFile("SKILL.md");
+  } catch (error2) {
+    console.error("Failed to fetch SKILL.md from GitHub:", error2);
+    return "Storelayer MCP Server — manage loyalty programs, promotions, wallets, users, events, and referrals. Use the available tools to interact with your project. Skill guide unavailable (GitHub unreachable).";
+  }
+}
 function buildInputSchema(tool) {
   const schema = structuredClone(tool.parameters);
   if (!schema.type)
@@ -13752,17 +13829,13 @@ async function main() {
     console.error("Error: STORE_LAYER_API_KEY environment variable is required");
     process.exit(1);
   }
-  if (!PROJECT_ID) {
-    console.error("Error: STORE_LAYER_PROJECT_ID environment variable is required");
-    process.exit(1);
-  }
   console.error(`Connecting to Store Layer API at ${API_URL}...`);
-  const [manifest, skill] = await Promise.all([
+  const [manifest, skillGuide] = await Promise.all([
     fetchToolManifest(),
-    fetchSkillContent()
+    fetchSkillGuide()
   ]);
   console.error(`Loaded ${manifest.length} tools from Store Layer`);
-  console.error(`Skill guide version: ${skill.version}`);
+  console.error(`Skill guide loaded from GitHub (${SKILLS_REPO})`);
   const mcpToRegistry = new Map;
   const mcpToManifest = new Map;
   for (const tool of manifest) {
@@ -13770,7 +13843,12 @@ async function main() {
     mcpToRegistry.set(mcpName, tool.name);
     mcpToManifest.set(mcpName, tool);
   }
-  const server = new Server({ name: "store-layer", version: "0.2.0" }, { capabilities: { tools: {}, prompts: {} } });
+  const allSkillFiles = [
+    ...SKILL_REFERENCES.map((f) => ({ ...f, category: "reference" })),
+    ...SKILL_AGENTS.map((f) => ({ ...f, category: "agent" })),
+    ...SKILL_TOOLS.map((f) => ({ ...f, category: "tool" }))
+  ];
+  const server = new Server({ name: "store-layer", version: "0.5.0" }, { capabilities: { tools: {}, prompts: {}, resources: {} } });
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: manifest.map((tool) => ({
       name: toMcpName(tool.name),
@@ -13821,26 +13899,74 @@ async function main() {
     prompts: [
       {
         name: "store-layer-guide",
-        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.`
-      }
+        description: "Comprehensive guide for using Storelayer tools — covers all domains (promotions, wallets, users, events, referrals, rules), with recipes and best practices."
+      },
+      ...SKILL_AGENTS.map((agent) => ({
+        name: agent.name,
+        description: agent.description
+      }))
     ]
   }));
   server.setRequestHandler(GetPromptRequestSchema, async (request) => {
-    if (request.params.name !== "store-layer-guide") {
-      throw new Error(`Unknown prompt: ${request.params.name}`);
+    const promptName = request.params.name;
+    if (promptName === "store-layer-guide") {
+      return {
+        description: "Storelayer MCP skill guide",
+        messages: [
+          {
+            role: "user",
+            content: { type: "text", text: skillGuide }
+          }
+        ]
+      };
     }
-    return {
-      description: `Store Layer MCP skill guide (v${skill.version})`,
-      messages: [
-        {
-          role: "user",
-          content: {
-            type: "text",
-            text: skill.content
+    const agent = SKILL_AGENTS.find((a) => a.name === promptName);
+    if (agent) {
+      try {
+        const content = await fetchSkillFile(agent.path);
+        return {
+          description: agent.description,
+          messages: [
+            {
+              role: "user",
+              content: { type: "text", text: content }
+            }
+          ]
+        };
+      } catch (error2) {
+        throw new Error(`Failed to fetch agent ${agent.name}: ${error2 instanceof Error ? error2.message : String(error2)}`);
+      }
+    }
+    throw new Error(`Unknown prompt: ${promptName}`);
+  });
+  server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+    resources: allSkillFiles.map((file) => ({
+      uri: `storelayer://${file.category}/${file.name}`,
+      name: file.name,
+      description: file.description,
+      mimeType: "text/markdown"
+    }))
+  }));
+  server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const uri = request.params.uri;
+    const file = allSkillFiles.find((f) => `storelayer://${f.category}/${f.name}` === uri);
+    if (!file) {
+      throw new Error(`Unknown resource: ${uri}`);
+    }
+    try {
+      const content = await fetchSkillFile(file.path);
+      return {
+        contents: [
+          {
+            uri,
+            mimeType: "text/markdown",
+            text: content
           }
-        }
-      ]
-    };
+        ]
+      };
+    } catch (error2) {
+      throw new Error(`Failed to fetch ${file.path}: ${error2 instanceof Error ? error2.message : String(error2)}`);
+    }
   });
   const transport = new StdioServerTransport;
   await server.connect(transport);

package/package.json

@@ -1,14 +1,13 @@
 {
   "name": "@storelayer/mcp-server",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "MCP server for Store Layer — manage loyalty programs, promotions, wallets, and more from Claude Desktop, Claude Code, or Cursor.",
   "type": "module",
   "bin": {
     "store-layer-mcp-server": "dist/index.js"
   },
   "files": [
-    "dist",
-    "SKILL.md"
+    "dist"
   ],
   "scripts": {
     "build": "bun build src/index.ts --target=node --outdir=dist --format=esm",

package/SKILL.md

@@ -1,482 +0,0 @@
-# Store Layer — AI Skill Guide
-
-You have access to the **Store Layer** MCP server. This guide helps you build loyalty programs, promotions, and customer engagement systems effectively.
-
-## Pipeline: How to Build Loyalty Programs
-
-**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.
-
-### 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
-
----
-
-## Recipes
-
-### Recipe 1: Points-for-Purchase (Earn 1 point per dollar)
-
-**Domains:** Rules + Wallet
-
-**Step 1:** Create the rule:
-
-```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 } }
-  }
-})
-```
-
-**Step 3:** Verify wallet (for a test user):
-
-```json
-wallet_get_balance({ "userId": "test-user-123" })
-```
-
----
-
-### Recipe 2: Percentage Discount (10% off everything)
-
-**Domains:** Promotions
-
-**Step 1:** Create promotion in draft:
-
-```json
-promotions_create({
-  "name": "10% Off Everything",
-  "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"
-  }
-})
-```
-
-**Step 2:** Test with a cart:
-
-```json
-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" }
-    ],
-    "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"
-  }
-})
-```
-
-**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"
-  }
-})
-```
-
-**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:
-
-```json
-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
-})
-```
-
-**Step 3:** Test with coupon:
-
-```json
-promotions_evaluate_cart({
-  "cart": { "items": [{ "id": "item-1", "price": 50.00, "quantity": 1 }] },
-  "couponCodes": ["SAVE20"]
-})
-```
-
----
-
-### Recipe 6: Referral Program (Refer a friend, both get 500 points)
-
-**Domains:** Referral + Rules + Wallet
-
-**Step 1:** Check referral config:
-
-```json
-referral_get_config()
-```
-
-**Step 2:** Create referral code for a user:
-
-```json
-referral_create_code({ "referrerId": "user-123" })
-```
-
-**Step 3:** Set up a rule to reward on completed referral:
-
-```json
-project_add_rule({
-  "name": "Referral Reward",
-  "conditions": {
-    "conditions": [
-      { "leftValue": "{{ event.type }}", "operator": "equals", "rightValue": "referral.completed", "rightType": "string" }
-    ],
-    "combinator": "AND"
-  },
-  "actions": [
-    {
-      "type": "reward",
-      "config": {
-        "assetType": "points",
-        "amount": 500,
-        "description": "Referral reward"
-      }
-    }
-  ],
-  "resources": {
-    "event": { "type": "referral.completed" }
-  }
-})
-```
-
----
-
-### Recipe 7: Stacking Promotions (Member discount + seasonal sale)
-
-**Domains:** Promotions (stacking)
-
-Create two stackable promotions:
-
-```json
-// 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 }}`
-
----
-
-## Common Mistakes
-
-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.
-
-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.
-
----
-
-## Feedback
-
-After building a loyalty program, use `skill_submit_feedback` to report the outcome. This helps improve this guide over time.
-
-```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"
-})
-```