@01.software/cli 0.10.5 → 0.11.0

package/dist/mcp/{chunk-2EPYMNHW.js → chunk-3TIDAOYP.js}

@@ -1,6 +1,75 @@
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
+// src/resource-inventory.ts
+var MCP_RESOURCE_INVENTORY = [
+  { uri: "config://app", label: "config", registeredName: "app-config" },
+  {
+    uri: "collections://schema",
+    label: "collections-schema",
+    registeredName: "collections-schema"
+  },
+  {
+    uri: "docs://sdk/getting-started",
+    label: "getting-started",
+    registeredName: "docs-getting-started"
+  },
+  { uri: "docs://sdk/guides", label: "guides", registeredName: "docs-guides" },
+  { uri: "docs://sdk/api", label: "api", registeredName: "docs-api" },
+  {
+    uri: "docs://sdk/query-builder",
+    label: "query-builder",
+    registeredName: "docs-query-builder"
+  },
+  {
+    uri: "docs://sdk/react-query",
+    label: "react-query",
+    registeredName: "docs-react-query"
+  },
+  {
+    uri: "docs://sdk/server-api",
+    label: "server-api",
+    registeredName: "docs-server-api"
+  },
+  {
+    uri: "docs://sdk/customer-auth",
+    label: "customer-auth",
+    registeredName: "docs-customer-auth"
+  },
+  {
+    uri: "docs://sdk/browser-vs-server",
+    label: "browser-vs-server",
+    registeredName: "docs-browser-vs-server"
+  },
+  {
+    uri: "docs://sdk/file-upload",
+    label: "file-upload",
+    registeredName: "docs-file-upload"
+  },
+  {
+    uri: "docs://sdk/webhook",
+    label: "webhook",
+    registeredName: "docs-webhook"
+  },
+  {
+    uri: "docs://sdk/product-detail",
+    label: "product-detail",
+    registeredName: "docs-product-detail"
+  }
+];
+var MCP_RESOURCE_LABELS = MCP_RESOURCE_INVENTORY.map(
+  (resource) => resource.label
+);
+function mcpResourceUri(registeredName) {
+  const resource = MCP_RESOURCE_INVENTORY.find(
+    (entry) => entry.registeredName === registeredName
+  );
+  if (!resource) {
+    throw new Error(`Unknown MCP resource inventory entry: ${registeredName}`);
+  }
+  return resource.uri;
+}
+
 // src/lib/request-context.ts
 import { AsyncLocalStorage } from "async_hooks";
 var requestContext = new AsyncLocalStorage();
@@ -247,6 +316,38 @@ var transactionStatusSchema = z2.enum([
   "failed",
   "canceled"
 ]);
+var entityIdSchema = z2.union([z2.string(), z2.number()]).transform(String);
+var createOrderItemSchema = z2.object({
+  product: entityIdSchema,
+  variant: entityIdSchema,
+  option: entityIdSchema,
+  quantity: z2.number().int().positive("quantity must be a positive integer"),
+  unitPrice: z2.number().optional(),
+  totalPrice: z2.number().optional()
+});
+var createOrderSchema = z2.object({
+  pgPaymentId: z2.string().min(1).optional(),
+  orderNumber: z2.string().min(1, "orderNumber is required"),
+  customer: entityIdSchema.optional(),
+  customerSnapshot: z2.object({
+    name: z2.string().optional(),
+    email: z2.string().email("Invalid email format"),
+    phone: z2.string().optional()
+  }),
+  shippingAddress: z2.object({
+    postalCode: z2.string().optional(),
+    address: z2.string().optional(),
+    detailAddress: z2.string().optional(),
+    deliveryMessage: z2.string().optional(),
+    recipientName: z2.string().optional(),
+    phone: z2.string().optional()
+  }),
+  orderItems: z2.array(createOrderItemSchema).min(1, "At least one order item is required").max(100, "Maximum 100 items per order"),
+  totalAmount: z2.number().nonnegative("totalAmount must be non-negative"),
+  shippingAmount: z2.number().min(0).optional(),
+  discountCode: z2.string().optional()
+});
+var CreateOrderSchema = createOrderSchema;
 var updateTransactionSchema = z2.object({
   pgPaymentId: z2.string().min(1, "pgPaymentId is required").describe("PG payment ID (required)"),
   status: transactionStatusSchema.describe(
@@ -281,6 +382,7 @@ var confirmPaymentSchema = z2.object({
   ]).optional(),
   metadata: z2.record(z2.string(), z2.unknown()).optional()
 }).strict();
+var ConfirmPaymentSchema = confirmPaymentSchema;
 var returnReasonSchema = z2.enum([
   "change_of_mind",
   "defective",
@@ -410,6 +512,11 @@ var MCP_TOOL_CONTRACT = {
     oauthScope: "mcp:write",
     readOnly: false
   },
+  "confirm-payment": {
+    consoleRole: "tenant-admin",
+    oauthScope: "mcp:write",
+    readOnly: false
+  },
   "update-order": {
     consoleRole: "tenant-admin",
     oauthScope: "mcp:write",
@@ -650,21 +757,29 @@ var TOOL_POLICY_MANIFEST = {
     category: "mutation-order",
     oauthScope: MCP_SCOPES.write,
     consoleRole: "tenant-admin",
-    consoleSurface: "POST /api/checkout",
+    consoleSurface: "POST /api/orders/checkout",
     annotationPolicy: DESTRUCTIVE_NON_IDEMPOTENT_MUTATION_ANNOTATION
   },
   "create-order": {
     category: "mutation-order",
     oauthScope: MCP_SCOPES.write,
     consoleRole: "tenant-admin",
-    consoleSurface: "POST /api/orders",
+    consoleSurface: "POST /api/orders/create",
     annotationPolicy: DESTRUCTIVE_NON_IDEMPOTENT_MUTATION_ANNOTATION
   },
+  "confirm-payment": {
+    category: "mutation-transaction",
+    oauthScope: MCP_SCOPES.write,
+    consoleRole: "tenant-admin",
+    consoleSurface: "POST /api/orders/confirm-payment",
+    annotationPolicy: DESTRUCTIVE_IDEMPOTENT_MUTATION_ANNOTATION,
+    exemptionReason: REASON_IDEMPOTENT_DESTRUCTIVE_UPDATE
+  },
   "update-order": {
     category: "mutation-order",
     oauthScope: MCP_SCOPES.write,
     consoleRole: "tenant-admin",
-    consoleSurface: "PATCH /api/orders/{id}",
+    consoleSurface: "POST /api/orders/update",
     annotationPolicy: DESTRUCTIVE_IDEMPOTENT_MUTATION_ANNOTATION,
     exemptionReason: REASON_IDEMPOTENT_DESTRUCTIVE_UPDATE
   },
@@ -673,14 +788,14 @@ var TOOL_POLICY_MANIFEST = {
     category: "mutation-fulfillment",
     oauthScope: MCP_SCOPES.write,
     consoleRole: "tenant-admin",
-    consoleSurface: "POST /api/orders/{id}/fulfillments",
+    consoleSurface: "POST /api/orders/create-fulfillment",
     annotationPolicy: NON_DESTRUCTIVE_MUTATION_ANNOTATION
   },
   "update-fulfillment": {
     category: "mutation-fulfillment",
     oauthScope: MCP_SCOPES.write,
     consoleRole: "tenant-admin",
-    consoleSurface: "PATCH /api/fulfillments/{id}",
+    consoleSurface: "POST /api/orders/update-fulfillment",
     annotationPolicy: DESTRUCTIVE_IDEMPOTENT_MUTATION_ANNOTATION,
     exemptionReason: REASON_IDEMPOTENT_DESTRUCTIVE_UPDATE
   },
@@ -689,14 +804,14 @@ var TOOL_POLICY_MANIFEST = {
     category: "mutation-return",
     oauthScope: MCP_SCOPES.write,
     consoleRole: "tenant-admin",
-    consoleSurface: "POST /api/returns",
+    consoleSurface: "POST /api/returns/create",
     annotationPolicy: DESTRUCTIVE_NON_IDEMPOTENT_MUTATION_ANNOTATION
   },
   "update-return": {
     category: "mutation-return",
     oauthScope: MCP_SCOPES.write,
     consoleRole: "tenant-admin",
-    consoleSurface: "PATCH /api/returns/{id}",
+    consoleSurface: "POST /api/returns/update",
     annotationPolicy: DESTRUCTIVE_IDEMPOTENT_MUTATION_ANNOTATION,
     exemptionReason: REASON_IDEMPOTENT_DESTRUCTIVE_UPDATE
   },
@@ -704,7 +819,7 @@ var TOOL_POLICY_MANIFEST = {
     category: "mutation-return",
     oauthScope: MCP_SCOPES.write,
     consoleRole: "tenant-admin",
-    consoleSurface: "POST /api/returns/with-refund",
+    consoleSurface: "POST /api/returns/return-refund",
     annotationPolicy: DESTRUCTIVE_NON_IDEMPOTENT_MUTATION_ANNOTATION
   },
   // ── Transaction mutations (mcp:write, tenant-admin) ──
@@ -712,7 +827,7 @@ var TOOL_POLICY_MANIFEST = {
     category: "mutation-transaction",
     oauthScope: MCP_SCOPES.write,
     consoleRole: "tenant-admin",
-    consoleSurface: "PATCH /api/transactions/{id}",
+    consoleSurface: "POST /api/transactions/update",
     annotationPolicy: DESTRUCTIVE_NON_IDEMPOTENT_MUTATION_ANNOTATION
   },
   // ── Field-config mutations (mcp:write, tenant-admin) ──
@@ -753,7 +868,15 @@ var TOOL_POLICY_MANIFEST = {
     annotationPolicy: READ_ONLY_ANNOTATION
   }
 };
-function evaluateToolPolicy(toolName, scopes) {
+var CONSOLE_ROLE_RANK = {
+  "tenant-viewer": 0,
+  "tenant-editor": 1,
+  "tenant-admin": 2
+};
+function hasRequiredConsoleRole(tenantRole, requiredRole) {
+  return CONSOLE_ROLE_RANK[tenantRole] >= CONSOLE_ROLE_RANK[requiredRole];
+}
+function evaluateToolPolicy(toolName, scopes, tenantRole) {
   if (!isMcpToolName(toolName)) {
     return {
       allowed: false,
@@ -769,6 +892,13 @@ function evaluateToolPolicy(toolName, scopes) {
       message: `Tool ${toolName} requires ${entry.oauthScope}`
     };
   }
+  if (!hasRequiredConsoleRole(tenantRole, entry.consoleRole)) {
+    return {
+      allowed: false,
+      reason: "insufficient_role",
+      message: `Tool ${toolName} requires ${entry.consoleRole}`
+    };
+  }
   return { allowed: true, entry };
 }
 
@@ -1261,25 +1391,7 @@ async function getOrder({
 }
 
 // src/tools/create-order.ts
-import { z as z6 } from "zod";
-var schema4 = {
-  pgPaymentId: z6.string().optional().describe("PG payment ID (optional \u2014 omit for free orders)"),
-  orderNumber: z6.string().min(1).describe("Unique order number (required)"),
-  customerSnapshot: z6.object({
-    name: z6.string().optional().describe("Customer name"),
-    email: z6.string().describe("Customer email (required)"),
-    phone: z6.string().optional().describe("Customer phone")
-  }).describe("Customer snapshot at time of order (required)"),
-  shippingAddress: z6.record(z6.string(), z6.unknown()).describe(
-    "Shipping address object (required). Fields: postalCode, address1, address2, deliveryMessage, recipientName, phone"
-  ),
-  orderItems: z6.array(z6.record(z6.string(), z6.unknown())).describe(
-    "Array of order item objects (required). Each: { product, variant, option, quantity, unitPrice?, totalPrice? }"
-  ),
-  totalAmount: z6.number().nonnegative().describe("Total order amount (required, min 0)"),
-  shippingAmount: z6.number().nonnegative().optional().describe("Shipping amount (optional, default 0)"),
-  discountCode: z6.string().optional().describe("Discount code to apply (optional)")
-};
+var schema4 = CreateOrderSchema.shape;
 var metadata4 = {
   name: "create-order",
   description: "Create a new order with products and shipping information. Supports idempotency.",
@@ -1293,9 +1405,8 @@ var metadata4 = {
 async function createOrder(params) {
   try {
     const client = getClient();
-    const result = await client.commerce.orders.create(
-      params
-    );
+    const parsed = CreateOrderSchema.parse(params);
+    const result = await client.commerce.orders.create(parsed);
     return toolSuccess({ data: result });
   } catch (error) {
     return toolError(error);
@@ -1303,10 +1414,10 @@ async function createOrder(params) {
 }
 
 // src/tools/update-order.ts
-import { z as z7 } from "zod";
+import { z as z6 } from "zod";
 var schema5 = {
-  orderNumber: z7.string().min(1).describe("Order number (required)"),
-  status: z7.enum([
+  orderNumber: z6.string().min(1).describe("Order number (required)"),
+  status: z6.enum([
     "pending",
     "paid",
     "failed",
@@ -1316,12 +1427,12 @@ var schema5 = {
     "delivered",
     "confirmed"
   ]).describe(
-    "New order status. Return-related statuses (return_requested, return_processing, returned) must be set via Return endpoints."
+    "New operator-driven order status. The schema keeps SDK status values for compatibility, but the Console update endpoint rejects server-derived statuses (paid, canceled, returned, refunded); those must be set by payment/refund flows, and return-related statuses must be set via Return endpoints."
   )
 };
 var metadata5 = {
   name: "update-order",
-  description: "Update order status. Automatically adjusts stock on status changes (e.g., canceled restores stock).",
+  description: "Update operator-driven order status. Console accepts transitions such as paid\u2192preparing/shipped/delivered/confirmed and rejects server-derived payment/refund statuses such as paid, canceled, returned, and refunded; the MCP schema keeps SDK status values for compatibility.",
   annotations: {
     title: "Update order status",
     readOnlyHint: false,
@@ -1343,15 +1454,15 @@ async function updateOrder({
 }
 
 // src/tools/checkout.ts
-import { z as z8 } from "zod";
+import { z as z7 } from "zod";
 var schema6 = {
-  cartId: z8.string().min(1).describe("Cart ID to convert to order (required)"),
-  pgPaymentId: z8.string().optional().describe("PG payment ID (optional \u2014 omit for free orders)"),
-  orderNumber: z8.string().min(1).describe("Unique order number (required)"),
-  customerSnapshot: z8.record(z8.string(), z8.unknown()).describe(
+  cartId: z7.string().min(1).describe("Cart ID to convert to order (required)"),
+  pgPaymentId: z7.string().optional().describe("PG payment ID (optional \u2014 omit for free orders)"),
+  orderNumber: z7.string().min(1).describe("Unique order number (required)"),
+  customerSnapshot: z7.record(z7.string(), z7.unknown()).describe(
     "Customer snapshot object (required). Fields: { name?, email, phone? }"
   ),
-  discountCode: z8.string().optional().describe("Discount code to apply (optional)")
+  discountCode: z7.string().optional().describe("Discount code to apply (optional)")
 };
 var metadata6 = {
   name: "checkout",
@@ -1376,17 +1487,17 @@ async function checkout(params) {
 }
 
 // src/tools/create-fulfillment.ts
-import { z as z9 } from "zod";
+import { z as z8 } from "zod";
 var schema7 = {
-  orderNumber: z9.string().min(1).describe("Order number (required)"),
-  carrier: z9.string().optional().describe("Shipping carrier name (optional)"),
-  trackingNumber: z9.string().optional().describe(
+  orderNumber: z8.string().min(1).describe("Order number (required)"),
+  carrier: z8.string().optional().describe("Shipping carrier name (optional)"),
+  trackingNumber: z8.string().optional().describe(
     'Tracking number (optional). Setting carrier + tracking triggers "shipped" status'
   ),
-  items: z9.array(
-    z9.object({
-      orderItem: z9.string().min(1).describe("Order item ID"),
-      quantity: z9.number().int().positive().describe("Quantity to fulfill")
+  items: z8.array(
+    z8.object({
+      orderItem: z8.string().min(1).describe("Order item ID"),
+      quantity: z8.number().int().positive().describe("Quantity to fulfill")
     })
   ).describe("Array of items to fulfill (required)")
 };
@@ -1421,16 +1532,16 @@ async function createFulfillment({
 }
 
 // src/tools/update-fulfillment.ts
-import { z as z10 } from "zod";
+import { z as z9 } from "zod";
 var schema8 = {
-  fulfillmentId: z10.string().min(1).describe("Fulfillment ID (required)"),
-  status: z10.enum(["packed", "shipped", "delivered", "failed"]).describe(
+  fulfillmentId: z9.string().min(1).describe("Fulfillment ID (required)"),
+  status: z9.enum(["packed", "shipped", "delivered", "failed"]).describe(
     "New fulfillment status (required). FSM: pending\u2192packed/shipped/failed, packed\u2192shipped/failed, shipped\u2192delivered/failed"
   ),
-  carrier: z10.string().optional().describe(
+  carrier: z9.string().optional().describe(
     "Shipping carrier (optional, changeable only in pending/packed status)"
   ),
-  trackingNumber: z10.string().optional().describe(
+  trackingNumber: z9.string().optional().describe(
     "Tracking number (optional, changeable only in pending/packed status)"
   )
 };
@@ -1501,21 +1612,44 @@ async function updateTransaction({
   }
 }
 
+// src/tools/confirm-payment.ts
+var schema10 = ConfirmPaymentSchema.shape;
+var metadata10 = {
+  name: "confirm-payment",
+  description: "Confirm a provider-verified ecommerce payment through the generic payment confirmation flow.",
+  annotations: {
+    title: "Confirm payment",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true
+  }
+};
+async function confirmPayment(params) {
+  try {
+    const client = getClient();
+    const parsed = ConfirmPaymentSchema.parse(params);
+    const result = await client.commerce.orders.confirmPayment(parsed);
+    return toolSuccess({ data: result });
+  } catch (error) {
+    return toolError(error);
+  }
+}
+
 // src/tools/create-return.ts
-import { z as z11 } from "zod";
-var schema10 = {
-  orderNumber: z11.string().min(1).describe("Order number (required)"),
-  reason: z11.enum(["change_of_mind", "defective", "wrong_delivery", "damaged", "other"]).optional().describe("Return reason (optional)"),
-  reasonDetail: z11.string().optional().describe("Detailed reason text (optional)"),
-  returnItems: z11.array(
-    z11.object({
-      orderItem: z11.string().min(1).describe("Order item ID"),
-      quantity: z11.number().int().positive().describe("Quantity to return")
+import { z as z10 } from "zod";
+var schema11 = {
+  orderNumber: z10.string().min(1).describe("Order number (required)"),
+  reason: z10.enum(["change_of_mind", "defective", "wrong_delivery", "damaged", "other"]).optional().describe("Return reason (optional)"),
+  reasonDetail: z10.string().optional().describe("Detailed reason text (optional)"),
+  returnItems: z10.array(
+    z10.object({
+      orderItem: z10.string().min(1).describe("Order item ID"),
+      quantity: z10.number().int().positive().describe("Quantity to return")
     })
   ).describe("Array of products to return (required)"),
-  refundAmount: z11.number().nonnegative().describe("Refund amount (required, min 0)")
+  refundAmount: z10.number().nonnegative().describe("Refund amount (required, min 0)")
 };
-var metadata10 = {
+var metadata11 = {
   name: "create-return",
   description: "Create a return request for an order. Only works for delivered/confirmed orders. Updates order status to return_requested.",
   annotations: {
@@ -1548,16 +1682,16 @@ async function createReturn({
 }
 
 // src/tools/update-return.ts
-import { z as z12 } from "zod";
-var schema11 = {
-  returnId: z12.string().min(1).describe("Return ID (required)"),
-  status: z12.enum(["processing", "approved", "rejected", "completed"]).describe(
-    "New return status (required). Valid transitions: requested\u2192processing/rejected, processing\u2192approved/rejected, approved\u2192completed"
+import { z as z11 } from "zod";
+var schema12 = {
+  returnId: z11.string().min(1).describe("Return ID (required)"),
+  status: z11.enum(["processing", "approved", "rejected", "completed"]).describe(
+    "New operator-driven return status (required). The schema keeps SDK status values for compatibility, but Console accepts only requested\u2192processing/rejected and processing\u2192approved/rejected here; completed is server-derived and must be set by return-with-refund."
   )
 };
-var metadata11 = {
+var metadata12 = {
   name: "update-return",
-  description: "Update return status with FSM validation. Restores inventory on completion, reverts order status on rejection.",
+  description: "Update operator-driven return status with FSM validation. Rejection can restore the order flow; completion and inventory restoration are handled by return-with-refund after provider-verified refund, while the MCP schema keeps SDK status values for compatibility.",
   annotations: {
     title: "Update return status",
     readOnlyHint: false,
@@ -1571,7 +1705,10 @@ async function updateReturn({
 }) {
   try {
     const client = getClient();
-    const result = await client.commerce.orders.updateReturn({ returnId, status });
+    const result = await client.commerce.orders.updateReturn({
+      returnId,
+      status
+    });
     return toolSuccess({ data: result });
   } catch (error) {
     return toolError(error);
@@ -1579,10 +1716,10 @@ async function updateReturn({
 }
 
 // src/tools/return-with-refund.ts
-var schema12 = ReturnWithRefundSchema.shape;
-var metadata12 = {
+var schema13 = ReturnWithRefundSchema.shape;
+var metadata13 = {
   name: "return-with-refund",
-  description: "Combined return + refund operation. Creates return, restores stock, cancels transaction, updates order status.",
+  description: "Combined provider-verified return + refund operation. Creates a completed return, restores eligible stock, records the refund transaction, and advances the order to the returned state.",
   annotations: {
     title: "Return with refund",
     readOnlyHint: false,
@@ -1596,6 +1733,7 @@ async function returnWithRefund({
   reasonDetail,
   returnItems,
   refundAmount,
+  returnShippingFee,
   pgPaymentId,
   paymentKey,
   refundReceiptUrl
@@ -1608,6 +1746,7 @@ async function returnWithRefund({
       reasonDetail,
       returnItems,
       refundAmount,
+      returnShippingFee,
       pgPaymentId,
       paymentKey,
       refundReceiptUrl
@@ -1620,15 +1759,15 @@ async function returnWithRefund({
 }
 
 // src/tools/add-cart-item.ts
-import { z as z13 } from "zod";
-var schema13 = {
-  cartId: z13.string().min(1).describe("Cart ID (required)"),
-  product: z13.string().min(1).describe("Product ID (required)"),
-  variant: z13.string().min(1).describe("Product variant ID (required)"),
-  option: z13.string().min(1).describe("Product option ID (required)"),
-  quantity: z13.number().int().positive().describe("Quantity to add (required, positive integer)")
+import { z as z12 } from "zod";
+var schema14 = {
+  cartId: z12.string().min(1).describe("Cart ID (required)"),
+  product: z12.string().min(1).describe("Product ID (required)"),
+  variant: z12.string().min(1).describe("Product variant ID (required)"),
+  option: z12.string().min(1).describe("Product option ID (required)"),
+  quantity: z12.number().int().positive().describe("Quantity to add (required, positive integer)")
 };
-var metadata13 = {
+var metadata14 = {
   name: "add-cart-item",
   description: "Add a product to cart. Validates stock, merges quantity if item already exists, recalculates totals.",
   annotations: {
@@ -1661,12 +1800,12 @@ async function addCartItem({
 }
 
 // src/tools/update-cart-item.ts
-import { z as z14 } from "zod";
-var schema14 = {
-  cartItemId: z14.string().min(1).describe("Cart item ID (required)"),
-  quantity: z14.number().int().positive().describe("New quantity (required, positive integer)")
+import { z as z13 } from "zod";
+var schema15 = {
+  cartItemId: z13.string().min(1).describe("Cart item ID (required)"),
+  quantity: z13.number().int().positive().describe("New quantity (required, positive integer)")
 };
-var metadata14 = {
+var metadata15 = {
   name: "update-cart-item",
   description: "Update cart item quantity. Validates stock availability, recalculates cart totals.",
   annotations: {
@@ -1690,11 +1829,11 @@ async function updateCartItem({
 }
 
 // src/tools/remove-cart-item.ts
-import { z as z15 } from "zod";
-var schema15 = {
-  cartItemId: z15.string().min(1).describe("Cart item ID to remove (required)")
+import { z as z14 } from "zod";
+var schema16 = {
+  cartItemId: z14.string().min(1).describe("Cart item ID to remove (required)")
 };
-var metadata15 = {
+var metadata16 = {
   name: "remove-cart-item",
   description: "Remove an item from cart. Recalculates cart totals after removal.",
   annotations: {
@@ -1717,12 +1856,12 @@ async function removeCartItem({
 }
 
 // src/tools/apply-discount.ts
-import { z as z16 } from "zod";
-var schema16 = {
-  cartId: z16.string().min(1).describe("Cart ID (required)"),
-  discountCode: z16.string().describe("Discount code to apply (required)")
+import { z as z15 } from "zod";
+var schema17 = {
+  cartId: z15.string().min(1).describe("Cart ID (required)"),
+  discountCode: z15.string().describe("Discount code to apply (required)")
 };
-var metadata16 = {
+var metadata17 = {
   name: "apply-discount",
   description: "Apply a discount code to a cart. Validates the code, updates cart totals, and sets free shipping if applicable.",
   annotations: {
@@ -1746,11 +1885,11 @@ async function applyDiscount({
 }
 
 // src/tools/remove-discount.ts
-import { z as z17 } from "zod";
-var schema17 = {
-  cartId: z17.string().min(1).describe("Cart ID (required)")
+import { z as z16 } from "zod";
+var schema18 = {
+  cartId: z16.string().min(1).describe("Cart ID (required)")
 };
-var metadata17 = {
+var metadata18 = {
   name: "remove-discount",
   description: "Remove the applied discount code from a cart and recalculate totals.",
   annotations: {
@@ -1773,11 +1912,11 @@ async function removeDiscount({
 }
 
 // src/tools/clear-cart.ts
-import { z as z18 } from "zod";
-var schema18 = {
-  cartId: z18.string().min(1).describe("Cart ID (required)")
+import { z as z17 } from "zod";
+var schema19 = {
+  cartId: z17.string().min(1).describe("Cart ID (required)")
 };
-var metadata18 = {
+var metadata19 = {
   name: "clear-cart",
   description: "Remove all items from a cart, reset discount and amounts. Shipping fee is preserved.",
   annotations: {
@@ -1800,12 +1939,12 @@ async function clearCart({
 }
 
 // src/tools/validate-discount.ts
-import { z as z19 } from "zod";
-var schema19 = {
-  code: z19.string().describe("Discount code to validate (required)"),
-  orderAmount: z19.number().describe("Order amount for validation (required)")
+import { z as z18 } from "zod";
+var schema20 = {
+  code: z18.string().describe("Discount code to validate (required)"),
+  orderAmount: z18.number().describe("Order amount for validation (required)")
 };
-var metadata19 = {
+var metadata20 = {
   name: "validate-discount",
   description: "Validate a discount code. Checks active status, date range, usage limits, minimum order amount, and calculates discount.",
   annotations: {
@@ -1832,13 +1971,13 @@ async function validateDiscount({
 }
 
 // src/tools/calculate-shipping.ts
-import { z as z20 } from "zod";
-var schema20 = {
-  shippingPolicyId: z20.string().optional().describe("Shipping policy ID (uses default policy if omitted)"),
-  orderAmount: z20.number().describe("Order amount for fee calculation (required)"),
-  postalCode: z20.string().optional().describe("Postal code for Jeju surcharge detection (63000-63644)")
+import { z as z19 } from "zod";
+var schema21 = {
+  shippingPolicyId: z19.string().optional().describe("Shipping policy ID (uses default policy if omitted)"),
+  orderAmount: z19.number().describe("Order amount for fee calculation (required)"),
+  postalCode: z19.string().optional().describe("Postal code for Jeju surcharge detection (63000-63644)")
 };
-var metadata20 = {
+var metadata21 = {
   name: "calculate-shipping",
   description: "Calculate shipping fee based on order amount and postal code. Supports free shipping threshold and Jeju surcharge.",
   annotations: {
@@ -1867,18 +2006,18 @@ async function calculateShipping({
 }
 
 // src/tools/stock-check.ts
-import { z as z21 } from "zod";
-var schema21 = {
-  items: z21.array(
-    z21.object({
-      variantId: z21.string().describe("Product variant ID"),
-      quantity: z21.number().int().positive().describe("Requested quantity")
+import { z as z20 } from "zod";
+var schema22 = {
+  items: z20.array(
+    z20.object({
+      variantId: z20.string().describe("Product variant ID"),
+      quantity: z20.number().int().positive().describe("Requested quantity")
     })
   ).describe(
     "Array of items to check stock for (required, max 100). Each: { variantId, quantity }"
   )
 };
-var metadata21 = {
+var metadata22 = {
   name: "stock-check",
   description: "Batch check product option stock availability. Returns per-item availability and an allAvailable flag.",
   annotations: {
@@ -1901,14 +2040,14 @@ async function stockCheck({
 }
 
 // src/tools/product-detail.ts
-import { z as z22 } from "zod";
-var schema22 = {
-  slug: z22.string().optional().describe("Product slug (one of slug or id required)"),
-  id: z22.string().optional().describe("Product id (one of slug or id required)")
+import { z as z21 } from "zod";
+var schema23 = {
+  slug: z21.string().optional().describe("Product slug (one of slug or id required)"),
+  id: z21.string().optional().describe("Product id (one of slug or id required)")
 };
-var metadata22 = {
+var metadata23 = {
   name: "product-detail",
-  description: "Fetch full product detail by slug or id. Returns one resolver-ready product with variants, option slugs, option value slugs/media, brand, categories, tags, images, videos, and listing rollup, or null if missing/unpublished/wrong tenant/feature disabled.",
+  description: "Fetch full product detail by slug or id. Returns one resolver-ready product with variants, option slugs, option value slugs/media, brand, categories, tags, images, videos, and listing rollup, or found:false with a reason if missing/unpublished/feature disabled. Permission/auth errors still throw.",
   annotations: {
     title: "Get product detail",
     readOnlyHint: true,
@@ -1934,66 +2073,66 @@ async function productDetail({
 }
 
 // src/tools/product-upsert.ts
-import { z as z23 } from "zod";
-var optionValueSchema = z23.object({
-  id: z23.string().optional().describe("Stable existing option-value ID for rename-safe updates"),
-  value: z23.string().describe("Display label (e.g. Black, S)"),
-  slug: z23.string().optional().describe(
+import { z as z22 } from "zod";
+var optionValueSchema = z22.object({
+  id: z22.string().optional().describe("Stable existing option-value ID for rename-safe updates"),
+  value: z22.string().describe("Display label (e.g. Black, S)"),
+  slug: z22.string().optional().describe(
     "Optional compatibility value token. The server generates one from value on create when omitted; not canonical identity."
   ),
-  swatchColor: z23.string().nullable().optional(),
-  thumbnail: z23.string().nullable().optional(),
-  images: z23.array(z23.string()).optional(),
-  metadata: z23.unknown().optional()
+  swatchColor: z22.string().nullable().optional(),
+  thumbnail: z22.string().nullable().optional(),
+  images: z22.array(z22.string()).optional(),
+  metadata: z22.unknown().optional()
 });
-var optionSchema = z23.object({
-  id: z23.string().optional().describe("Stable existing option ID for rename-safe updates"),
-  title: z23.string().describe("Option name (e.g. Color, Size)"),
-  slug: z23.string().optional().describe(
+var optionSchema = z22.object({
+  id: z22.string().optional().describe("Stable existing option ID for rename-safe updates"),
+  title: z22.string().describe("Option name (e.g. Color, Size)"),
+  slug: z22.string().optional().describe(
     "Optional compatibility option token. The server generates one from title on create when omitted; not canonical identity."
   ),
-  values: z23.array(optionValueSchema).describe("Allowed option values")
+  values: z22.array(optionValueSchema).describe("Allowed option values")
 });
-var variantOptionValueSchema = z23.object({
-  valueSlug: z23.string().optional(),
-  valueId: z23.string().optional(),
-  value: z23.string().optional()
+var variantOptionValueSchema = z22.object({
+  valueSlug: z22.string().optional(),
+  valueId: z22.string().optional(),
+  value: z22.string().optional()
 });
-var variantSchema = z23.object({
-  id: z23.string().optional().describe("Existing variant ID for updates"),
-  optionValues: z23.union([
-    z23.record(z23.string(), z23.union([z23.string(), variantOptionValueSchema])),
-    z23.array(z23.string())
+var variantSchema = z22.object({
+  id: z22.string().optional().describe("Existing variant ID for updates"),
+  optionValues: z22.union([
+    z22.record(z22.string(), z22.union([z22.string(), variantOptionValueSchema])),
+    z22.array(z22.string())
   ]).optional().describe(
     "Option-value selection. Prefer stable option-value IDs, either as an array or object values using { valueId }. Slug maps and exact { OptionTitle: ValueLabel } maps remain compatibility-only and fail when labels are ambiguous."
   ),
-  sku: z23.string().nullable().optional(),
-  title: z23.string().nullable().optional(),
-  price: z23.number().nonnegative().describe("Selling price (KRW, min 0)"),
-  compareAtPrice: z23.number().nonnegative().nullable().optional(),
-  stock: z23.number().int().nonnegative().optional(),
-  isUnlimited: z23.boolean().optional(),
-  weight: z23.number().nonnegative().nullable().optional(),
-  requiresShipping: z23.boolean().optional(),
-  barcode: z23.string().nullable().optional(),
-  externalId: z23.string().nullable().optional(),
-  isActive: z23.boolean().optional(),
-  thumbnail: z23.string().nullable().optional(),
-  images: z23.array(z23.string()).optional(),
-  metadata: z23.unknown().optional()
+  sku: z22.string().nullable().optional(),
+  title: z22.string().nullable().optional(),
+  price: z22.number().nonnegative().describe("Selling price (KRW, min 0)"),
+  compareAtPrice: z22.number().nonnegative().nullable().optional(),
+  stock: z22.number().int().nonnegative().optional(),
+  isUnlimited: z22.boolean().optional(),
+  weight: z22.number().nonnegative().nullable().optional(),
+  requiresShipping: z22.boolean().optional(),
+  barcode: z22.string().nullable().optional(),
+  externalId: z22.string().nullable().optional(),
+  isActive: z22.boolean().optional(),
+  thumbnail: z22.string().nullable().optional(),
+  images: z22.array(z22.string()).optional(),
+  metadata: z22.unknown().optional()
 });
-var schema23 = {
-  product: z23.record(z23.string(), z23.unknown()).describe(
+var schema24 = {
+  product: z22.record(z22.string(), z22.unknown()).describe(
     "Product fields. Include `id` to update an existing product; omit for create (then `title` is required)."
   ),
-  options: z23.array(optionSchema).optional().describe(
+  options: z22.array(optionSchema).optional().describe(
     "Option definitions. Include stable option/value IDs when updating or renaming existing rows. Slugs are optional compatibility metadata generated from title/value on create when omitted; omitted options on an existing product are deleted (with their values)."
   ),
-  variants: z23.array(variantSchema).optional().describe(
+  variants: z22.array(variantSchema).optional().describe(
     "Variant rows. Prefer stable option-value IDs in optionValues. Slug/title maps are compatibility inputs. Omitted variants on an existing product are deleted, unless referenced by an active cart or non-terminal order \u2014 those are soft-deactivated (isActive: false)."
   )
 };
-var metadata23 = {
+var metadata24 = {
   name: "product-upsert",
   description: "Atomically create or update a product together with its options, option-values, and variants in a single transaction. Mirrors Shopify productSet semantics. Any failure rolls back the entire write.",
   annotations: {
@@ -2030,8 +2169,8 @@ async function getCollectionSchema(collection) {
 }
 
 // src/tools/get-collection-schema.ts
-var schema24 = createCollectionSchemaToolInputSchema(SERVER_COLLECTIONS3).shape;
-var metadata24 = {
+var schema25 = createCollectionSchemaToolInputSchema(SERVER_COLLECTIONS3).shape;
+var metadata25 = {
   name: "get-collection-schema",
   description: "Get the authoritative tenant-aware collection schema from console. Use this before create/update to understand writable fields, hidden fields, required metadata, and collection-level visibility.",
   annotations: {
@@ -2082,8 +2221,8 @@ async function getTenantFeatureProgress(feature, includeEvidence = false) {
 }
 
 // src/tools/get-tenant-context.ts
-var schema25 = tenantContextToolInputSchema.shape;
-var metadata25 = {
+var schema26 = tenantContextToolInputSchema.shape;
+var metadata26 = {
   name: "get-tenant-context",
   description: "Get current tenant features, active collections, and field visibility. Call this at the start of every session. Use includeCounts=true to also get per-collection document counts for setup diagnostics.",
   annotations: {
@@ -2160,8 +2299,8 @@ async function handler({
 }
 
 // src/tools/check-feature-progress.ts
-var schema26 = tenantFeatureProgressInputSchema.shape;
-var metadata26 = {
+var schema27 = tenantFeatureProgressInputSchema.shape;
+var metadata27 = {
   name: "check-feature-progress",
   description: "Check tenant implementation progress for a supported feature. Start with feature=ecommerce to inspect catalog, cart, checkout, payment result, webhook, and operations readiness without mutating tenant data.",
   annotations: {
@@ -2184,7 +2323,7 @@ async function handler2({
 }
 
 // src/tools/list-configurable-fields.ts
-import { z as z24 } from "zod";
+import { z as z23 } from "zod";
 
 // src/lib/field-config.ts
 async function fetchFieldConfigs() {
@@ -2207,12 +2346,12 @@ function invalidateFieldConfigCache() {
 }
 
 // src/tools/list-configurable-fields.ts
-var schema27 = {
-  collection: z24.string().optional().describe(
+var schema28 = {
+  collection: z23.string().optional().describe(
     "Filter by collection slug (optional \u2014 returns all if omitted). Use this filter to reduce response size when you know which collection to check."
   )
 };
-var metadata27 = {
+var metadata28 = {
   name: "list-configurable-fields",
   description: "List all configurable fields for tenant collections with current visibility state. Shows which fields can be shown/hidden and their current status. Returns all collections including inactive features \u2014 cross-reference with get-tenant-context for active features. Response includes ~300 fields across 47 collections \u2014 use collection filter when possible.",
   annotations: {
@@ -2243,17 +2382,17 @@ async function listConfigurableFields(params) {
 }
 
 // src/tools/update-field-config.ts
-import { z as z25 } from "zod";
-var schema28 = {
-  collection: z25.string().min(1).describe("Collection slug (required)"),
-  hiddenFields: z25.array(z25.string().min(1).max(200)).max(300).describe(
+import { z as z24 } from "zod";
+var schema29 = {
+  collection: z24.string().min(1).describe("Collection slug (required)"),
+  hiddenFields: z24.array(z24.string().min(1).max(200)).max(300).describe(
     "Fields to hide (required). This is a FULL REPLACE \u2014 fields NOT in this list will be shown. Pass [] to show all fields. Use list-configurable-fields first to see available field paths."
   ),
-  isHidden: z25.boolean().optional().describe(
+  isHidden: z24.boolean().optional().describe(
     "Hide the entire collection from Admin Panel (optional). When true, individual hiddenFields are irrelevant."
   )
 };
-var metadata28 = {
+var metadata29 = {
   name: "update-field-config",
   description: "Update field visibility configuration for a tenant collection. Hidden fields are removed from the Admin Panel UI. IMPORTANT: hiddenFields is a full replace, not a merge. Always call list-configurable-fields first to see current state.",
   annotations: {
@@ -2281,7 +2420,7 @@ async function updateFieldConfig(params) {
 }
 
 // src/tools/sdk-get-recipe.ts
-import { z as z26 } from "zod";
+import { z as z25 } from "zod";
 
 // src/lib/sdk-recipes.ts
 var recipes = {
@@ -2722,8 +2861,8 @@ function getRecipe(goal, runtime = "both") {
 }
 
 // src/tools/sdk-get-recipe.ts
-var schema29 = {
-  goal: z26.enum([
+var schema30 = {
+  goal: z25.enum([
     "fetch-list",
     "fetch-by-id",
     "create-item",
@@ -2735,11 +2874,11 @@ var schema29 = {
     "file-upload",
     "bulk-operations"
   ]).describe("What the user wants to accomplish"),
-  runtime: z26.enum(["browser", "server", "both"]).default("both").describe("Target runtime environment"),
-  collection: z26.string().optional().describe("Specific collection name if applicable"),
-  includeExample: z26.boolean().default(true).describe("Whether to include a full code example")
+  runtime: z25.enum(["browser", "server", "both"]).default("both").describe("Target runtime environment"),
+  collection: z25.string().optional().describe("Specific collection name if applicable"),
+  includeExample: z25.boolean().default(true).describe("Whether to include a full code example")
 };
-var metadata29 = {
+var metadata30 = {
   name: "sdk-get-recipe",
   description: "Get a complete SDK code recipe for a specific task. Returns recommended approach, code example, and related documentation links. Use this FIRST when the user asks how to do something with the SDK.",
   annotations: {
@@ -2782,7 +2921,7 @@ function handler3({
 }
 
 // src/tools/sdk-search-docs.ts
-import { z as z27 } from "zod";
+import { z as z26 } from "zod";
 
 // src/lib/sdk-doc-index.ts
 var docIndex = [
@@ -2910,8 +3049,19 @@ var docIndex = [
   // Webhooks
   {
     title: "Webhooks",
-    keywords: ["webhook", "hmac", "signature", "WEBHOOK_SECRET", "server-to-server", "event"],
-    summary: "Tenant webhooks deliver server-to-server events such as password reset tokens. Signed with HMAC-SHA256 using PAYLOAD_SECRET.",
+    keywords: [
+      "webhook",
+      "hmac",
+      "signature",
+      "WEBHOOK_SECRET",
+      "server-to-server",
+      "event",
+      "order",
+      "orderChanged",
+      "collection.orderChanged",
+      "isOrderChangedWebhookEvent"
+    ],
+    summary: "Tenant webhooks deliver signed server-to-server events via WEBHOOK_SECRET, including customer password reset and semantic order changes with collection.orderChanged / isOrderChangedWebhookEvent.",
     resourceUri: "docs://sdk/webhook"
   },
   // Order API
@@ -2957,11 +3107,11 @@ function searchDocs(query, limit = 5) {
 }
 
 // src/tools/sdk-search-docs.ts
-var schema30 = {
-  query: z27.string().min(2).describe('Search keyword or phrase (e.g. "infinite scroll", "webhook", "customer login")'),
-  limit: z27.number().min(1).max(10).default(5).describe("Maximum results to return (1-10, default: 5)")
+var schema31 = {
+  query: z26.string().min(2).describe('Search keyword or phrase (e.g. "infinite scroll", "webhook", "customer login")'),
+  limit: z26.number().min(1).max(10).default(5).describe("Maximum results to return (1-10, default: 5)")
 };
-var metadata30 = {
+var metadata31 = {
   name: "sdk-search-docs",
   description: "Search SDK documentation by keyword. Returns matching topics with summaries and resource links. Use when looking for specific SDK features or patterns.",
   annotations: {
@@ -2996,9 +3146,9 @@ function handler4({
 }
 
 // src/tools/sdk-get-auth-setup.ts
-import { z as z28 } from "zod";
-var schema31 = {
-  scenario: z28.enum([
+import { z as z27 } from "zod";
+var schema32 = {
+  scenario: z27.enum([
     "browser-client",
     "server-client",
     "customer-auth",
@@ -3007,7 +3157,7 @@ var schema31 = {
     "webhook-verification"
   ]).describe("Authentication scenario")
 };
-var metadata31 = {
+var metadata32 = {
   name: "sdk-get-auth-setup",
   description: "Get the current authentication setup for a specific scenario. Returns env var names, code snippets, and security notes.",
   annotations: {
@@ -3131,13 +3281,19 @@ export SOFTWARE_SECRET_KEY=sk01_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`,
     envVars: ["WEBHOOK_SECRET"],
     code: `import { handleWebhook, createCustomerAuthWebhookHandler } from '@01.software/sdk/webhook'
 
+function getWebhookSecret(): string {
+  const secret = process.env.WEBHOOK_SECRET
+  if (!secret) throw new Error('WEBHOOK_SECRET is required')
+  return secret
+}
+
 const customerAuthHandler = createCustomerAuthWebhookHandler({
   passwordReset: sendPasswordResetEmail,
 })
 
 export async function POST(request: Request) {
   return handleWebhook(request, customerAuthHandler, {
-    secret: process.env.WEBHOOK_SECRET!,
+    secret: getWebhookSecret(),
   })
 }`,
     notes: [
@@ -3163,14 +3319,14 @@ function handler5({
 }
 
 // src/tools/sdk-get-collection-pattern.ts
-import { z as z29 } from "zod";
+import { z as z28 } from "zod";
 import { COLLECTIONS, SERVER_COLLECTIONS as SERVER_COLLECTIONS4 } from "@01.software/sdk";
-var schema32 = {
-  collection: z29.enum(SERVER_COLLECTIONS4).describe("Collection name"),
-  operation: z29.enum(["read", "write", "full-crud"]).default("read").describe("What operations are needed"),
-  surface: z29.enum(["query-builder", "react-query", "server-api"]).default("query-builder").describe("Preferred API surface")
+var schema33 = {
+  collection: z28.enum(SERVER_COLLECTIONS4).describe("Collection name"),
+  operation: z28.enum(["read", "write", "full-crud"]).default("read").describe("What operations are needed"),
+  surface: z28.enum(["query-builder", "react-query", "server-api"]).default("query-builder").describe("Preferred API surface")
 };
-var metadata32 = {
+var metadata33 = {
   name: "sdk-get-collection-pattern",
   description: "Get the recommended CRUD pattern for a specific collection. Returns code examples for the chosen API surface and operation type.",
   annotations: {
@@ -3366,14 +3522,14 @@ function handler6({
 }
 
 // src/prompts/sdk-usage-guide.ts
-import { z as z30 } from "zod";
-var schema33 = {
-  goal: z30.string().describe('What the user wants to accomplish (e.g., "query product list", "create order")'),
-  runtime: z30.enum(["browser", "server"]).optional().describe("Target runtime: browser (React/Next.js client) or server (Node.js)"),
-  surface: z30.enum(["query-builder", "react-query", "customer-api", "server-api"]).optional().describe("Preferred API surface"),
-  collection: z30.string().optional().describe("Specific collection if relevant")
+import { z as z29 } from "zod";
+var schema34 = {
+  goal: z29.string().describe('What the user wants to accomplish (e.g., "query product list", "create order")'),
+  runtime: z29.enum(["browser", "server"]).optional().describe("Target runtime: browser (React/Next.js client) or server (Node.js)"),
+  surface: z29.enum(["query-builder", "react-query", "customer-api", "server-api"]).optional().describe("Preferred API surface"),
+  collection: z29.string().optional().describe("Specific collection if relevant")
 };
-var metadata33 = {
+var metadata34 = {
   name: "sdk-usage-guide",
   title: "SDK Usage Guide",
   description: "Provides guidance on how to perform a specific task using the 01.software SDK",
@@ -3521,8 +3677,9 @@ You can perform the "${goal}" task by following the patterns above.
 ### Product detail page (slug-based)
 
 \`\`\`typescript
-const product = await client.commerce.product.detail({ slug })
-if (!product) return notFound()
+const result = await client.commerce.product.detail({ slug })
+if (!result.found) return notFound()
+const product = result.product
 // product: { product, variants, options, brand, categories, tags, images, videos, listing }
 \`\`\`
 
@@ -3544,14 +3701,14 @@ const { allAvailable } = await client.commerce.product.stockCheck({
 }
 
 // src/prompts/collection-query-help.ts
-import { z as z31 } from "zod";
+import { z as z30 } from "zod";
 import { COLLECTIONS as COLLECTIONS2, SERVER_COLLECTIONS as SERVER_COLLECTIONS5 } from "@01.software/sdk";
-var schema34 = {
-  collection: z31.enum(SERVER_COLLECTIONS5).describe("Collection name"),
-  operation: z31.enum(["find", "create", "update", "delete"]).describe("Operation to perform (find, create, update, delete)"),
-  filters: z31.string().optional().describe("Filter conditions (JSON string, optional)")
+var schema35 = {
+  collection: z30.enum(SERVER_COLLECTIONS5).describe("Collection name"),
+  operation: z30.enum(["find", "create", "update", "delete"]).describe("Operation to perform (find, create, update, delete)"),
+  filters: z30.string().optional().describe("Filter conditions (JSON string, optional)")
 };
-var metadata34 = {
+var metadata35 = {
   name: "collection-query-help",
   title: "Collection Query Help",
   description: "Provides guidance on how to write queries for a specific collection",
@@ -3648,16 +3805,16 @@ ${operation === "find" ? `- Use \`where\` option for filtering (Payload query sy
 }
 
 // src/prompts/order-flow-guide.ts
-import { z as z32 } from "zod";
-var schema35 = {
-  scenario: z32.enum([
+import { z as z31 } from "zod";
+var schema36 = {
+  scenario: z31.enum([
     "simple-order",
     "cart-checkout",
     "return-refund",
     "fulfillment-tracking"
   ]).describe("Order flow scenario")
 };
-var metadata35 = {
+var metadata36 = {
   name: "order-flow-guide",
   title: "Order Flow Guide",
   description: "Provides step-by-step guidance for ecommerce order flows including creation, checkout, returns, and fulfillment.",
@@ -3672,9 +3829,10 @@ var SCENARIOS = {
    - Provide: orderNumber, customerSnapshot (email required), shippingAddress, orderItems, totalAmount
    - Optional: pgPaymentId (omit for free orders), shippingAmount, discountCode
 
-2. **Payment Confirmation** \u2192 \`update-transaction\` tool
-   - Confirm provider payment with pgPaymentId, paymentKey, and amount
-   - Stock is automatically adjusted (stock -= qty, reservedStock += qty)
+2. **Payment Confirmation** \u2192 ServerClient \`commerce.orders.confirmPayment()\`
+   - Confirm provider payment with pgPaymentId, provider name, and amount
+   - Successful confirmation transitions the order to \`paid\`
+   - Paid orders reserve sellable quantity (reservedStock += qty); physical stock is decremented on delivery
 
 3. **Fulfillment** \u2192 \`create-fulfillment\` tool
    - Provide carrier + trackingNumber for shipped status
@@ -3694,18 +3852,20 @@ const client = createServerClient({
 const order = await client.commerce.orders.create({
   orderNumber: 'ORD-240101-001',
   customerSnapshot: { email: 'user@example.com', name: 'John' },
-  shippingAddress: { postalCode: '06000', address1: '123 Main St' },
+  shippingAddress: { postalCode: '06000', address: '123 Main St' },
   orderItems: [{ product: 'prod-id', variant: 'var-id', option: 'opt-id', quantity: 2 }],
   totalAmount: 59800,
   pgPaymentId: 'pay_xxx' // omit for free orders
 })
 
 // 2. After payment confirmed by provider
-await client.commerce.orders.updateTransaction({
+await client.commerce.orders.confirmPayment({
+  orderNumber: 'ORD-240101-001',
   pgPaymentId: 'pay_xxx',
-  status: 'paid',
-  paymentKey: 'payment_key_xxx',
-  amount: 59800
+  pgProvider: 'provider',
+  amount: 59800,
+  paymentMethod: 'card',
+  confirmationSource: 'provider_api_confirm'
 })
 
 // 3. Ship items
@@ -3724,7 +3884,7 @@ await client.commerce.orders.createFulfillment({
 2. **Apply Discount** (optional) \u2192 \`apply-discount\` tool
 3. **Calculate Shipping** \u2192 \`calculate-shipping\` tool
 4. **Checkout** \u2192 \`checkout\` tool (converts cart to order)
-5. **Payment** \u2192 \`update-transaction\` for provider-verified paid transitions
+5. **Payment** \u2192 ServerClient \`commerce.orders.confirmPayment()\` for provider-verified paid transitions
 
 ### Key Points
 - Cart has a customer linked \u2014 auto-copied to order on checkout
@@ -3755,12 +3915,13 @@ const order = await client.commerce.orders.checkout({
 1. **Create Return** \u2192 \`create-return\` tool
    - Order must be \`delivered\` or \`confirmed\`
    - Specify returnItems and refundAmount
-   - Return status: requested \u2192 processing \u2192 approved \u2192 completed
+   - Operator transitions: requested \u2192 processing/rejected, processing \u2192 approved/rejected
+   - \`completed\` is server-derived and requires \`return-with-refund\`
 
 ### Option B: Return + Refund (atomic, recommended)
 1. **Return with Refund** \u2192 \`return-with-refund\` tool
    - Handles return + stock restoration + transaction update in one call
-   - Return immediately completed (bypasses FSM)
+   - Sets the return to \`completed\` after provider-verified refund
    - Requires pgPaymentId and paymentKey for provider-verified refund
 
 ### Key Points
@@ -3776,8 +3937,9 @@ await client.commerce.orders.returnWithRefund({
   orderNumber: 'ORD-240101-001',
   reason: 'defective',
   reasonDetail: 'Product arrived damaged',
-  returnItems: [{ orderItem: 'oi-id', quantity: 1 }],
+  returnItems: [{ orderItem: 'oi-id', quantity: 1, restockingFee: 500 }],
   refundAmount: 29900,
+  returnShippingFee: 1500,
   pgPaymentId: 'pay_xxx',
   paymentKey: 'payment_key_xxx'
 })
@@ -3837,14 +3999,14 @@ ${SCENARIOS[scenario] || "Unknown scenario."}
 - \`checkout\`
 - \`create-fulfillment\`, \`update-fulfillment\`
 - \`create-return\`, \`update-return\`, \`return-with-refund\`
-- \`update-transaction\`
+- \`confirm-payment\`, \`update-transaction\`
 - \`validate-discount\`, \`calculate-shipping\``;
 }
 
 // src/prompts/feature-setup-guide.ts
-import { z as z33 } from "zod";
-var schema36 = {
-  feature: z33.enum([
+import { z as z32 } from "zod";
+var schema37 = {
+  feature: z32.enum([
     "ecommerce",
     "customers",
     "articles",
@@ -3859,7 +4021,7 @@ var schema36 = {
     "community"
   ]).describe("Feature to get setup guide for")
 };
-var metadata36 = {
+var metadata37 = {
   name: "feature-setup-guide",
   title: "Feature Setup Guide",
   description: "Setup checklist and remediation guide for a tenant feature. Load with check-feature-progress and get-tenant-context to diagnose setup gaps.",
@@ -4067,7 +4229,7 @@ ${FEATURES[feature] || "Unknown feature."}
 }
 
 // src/resources/(config)/app.ts
-var metadata37 = {
+var metadata38 = {
   name: "app-config",
   title: "Application Config",
   description: "01.software SDK and MCP server configuration information"
@@ -4111,7 +4273,7 @@ The hosted HTTP MCP endpoint at https://mcp.01.software/mcp exposes only these O
 - \`sdk-get-auth-setup\` - Get framework-specific auth setup guidance
 - \`sdk-get-collection-pattern\` - Get collection-specific usage patterns
 
-## Local CLI Stdio Surface (30)
+## Local CLI Stdio Surface (33)
 
 For trusted local server-key workflows, start the stdio server:
 
@@ -4119,7 +4281,7 @@ For trusted local server-key workflows, start the stdio server:
 npx @01.software/cli mcp
 \`\`\`
 
-Local stdio can expose generic read, order, return, cart, validation, stock, schema, tenant context, feature progress, field config, and guidance tools. Generic collection write tools (create/update/delete/update-many/delete-many) are intentionally absent on every transport; use the SDK server client for generic writes.
+Local stdio can expose generic read, order, payment confirmation, return, cart, validation, stock, schema, tenant context, feature progress, field config, and guidance tools. Generic collection write tools (create/update/delete/update-many/delete-many) are intentionally absent on every transport; use the SDK server client for generic writes.
 
 ## Rate Limits
 
@@ -4133,7 +4295,7 @@ Rate limits depend on your tenant plan:
 
 // src/resources/(collections)/schema.ts
 import { COLLECTIONS as COLLECTIONS3 } from "@01.software/sdk";
-var metadata38 = {
+var metadata39 = {
   name: "collections-schema",
   title: "Collection Schema Info",
   description: "Available collections and their schema information"
@@ -4270,7 +4432,7 @@ Total available collections: ${COLLECTIONS3.length}`;
 }
 
 // src/resources/(docs)/getting-started.ts
-var metadata39 = {
+var metadata40 = {
   name: "docs-getting-started",
   title: "Getting Started",
   description: "01.software SDK getting started guide"
@@ -4331,7 +4493,7 @@ const result = await client.collections.from('products').find({
 }
 
 // src/resources/(docs)/guides.ts
-var metadata40 = {
+var metadata41 = {
   name: "docs-guides",
   title: "Guides",
   description: "01.software SDK usage guides"
@@ -4544,7 +4706,7 @@ For more implementation guidance, see the [SDK Guide](/developers/sdk).`;
 }
 
 // src/resources/(docs)/api.ts
-var metadata41 = {
+var metadata42 = {
   name: "docs-api",
   title: "API Reference",
   description: "01.software SDK API reference documentation"
@@ -4827,7 +4989,7 @@ For more details, see the [API documentation](/developers/api).`;
 }
 
 // src/resources/(docs)/query-builder.ts
-var metadata42 = {
+var metadata43 = {
   name: "docs-query-builder",
   title: "Query Builder",
   description: "01.software SDK Query Builder API reference (client.collections.from)"
@@ -5021,7 +5183,7 @@ console.log(result.hasNextPage) // true
 }
 
 // src/resources/(docs)/react-query.ts
-var metadata43 = {
+var metadata44 = {
   name: "docs-react-query",
   title: "React Query Hooks",
   description: "01.software SDK React Query hooks reference (@01.software/sdk/query)"
@@ -5253,7 +5415,7 @@ export function ProductList() {
 }
 
 // src/resources/(docs)/server-api.ts
-var metadata44 = {
+var metadata45 = {
   name: "docs-server-api",
   title: "Server-side API",
   description: "01.software SDK server-side API reference (client.commerce) for orders, fulfillments, returns, carts, and validation"
@@ -5291,16 +5453,16 @@ const order = await client.commerce.orders.create({
     recipientName: 'John Doe',
     phone: '+821012345678',
     postalCode: '06234',
-    address1: '123 Main St',
-    address2: 'Apt 4B',
+    address: '123 Main St',
+    detailAddress: 'Apt 4B',
     deliveryMessage?: 'Leave at door',
   },
   orderItems: [
-    { product: 'product-id', variant: 'variant-id', option: 'option-id', quantity: 2, unitPrice: 29900 }
+    { product: 'product-id', variant: 'variant-id', option: 'option-id', quantity: 2 }
   ],
   totalAmount: 59800,
   shippingAmount?: 3000,
-  pgPaymentId?: 'toss-payment-id',  // omit for free orders
+  pgPaymentId?: 'provider-payment-id',  // omit for free orders
 })
 \`\`\`
 
@@ -5312,7 +5474,7 @@ const order = await client.commerce.orders.checkout({
   cartId: 'cart-id',
   orderNumber: 'ORD-20240101-0001',
   customerSnapshot: { name: 'John Doe', email: 'john@example.com' },
-  pgPaymentId?: 'toss-payment-id',
+  pgPaymentId?: 'provider-payment-id',
 })
 \`\`\`
 
@@ -5384,12 +5546,12 @@ const ret = await client.commerce.orders.createReturn({
 \`\`\`
 
 ### updateReturn()
-Update return status.
+Update operator-driven return status. \`completed\` is server-derived and must go through \`returnWithRefund()\`.
 
 \`\`\`typescript
 const ret = await client.commerce.orders.updateReturn({
   returnId: 'return-id',
-  status: 'processing',  // processing | approved | completed | rejected
+  status: 'processing',  // processing | approved | rejected
 })
 \`\`\`
 
@@ -5402,27 +5564,49 @@ const result = await client.commerce.orders.returnWithRefund({
   reason?: 'defective',
   reasonDetail?: 'Screen cracked on arrival',
   returnItems: [
-    { orderItem: 'order-item-id', quantity: 1 }
+    { orderItem: 'order-item-id', quantity: 1, restockingFee?: 500 }
   ],
   refundAmount: 29900,
-  pgPaymentId: 'toss-payment-id',  // required
-  paymentKey: 'toss-payment-key',  // required for provider refund
+  returnShippingFee?: 1500,
+  pgPaymentId: 'provider-payment-id',  // required
+  paymentKey: 'provider-payment-key',  // required for provider refund
   refundReceiptUrl?: 'https://...',
 })
 \`\`\`
 
 ## Transaction API
 
+### confirmPayment()
+Confirm a provider-verified payment and transition the order to paid. Verify the
+payment with the provider first, then call this endpoint with the provider name,
+amount, and an idempotency event ID when available.
+
+\`\`\`typescript
+const result = await client.commerce.orders.confirmPayment({
+  orderNumber: 'ORD-20240101-0001',
+  pgPaymentId: 'provider-payment-id',
+  pgProvider: 'provider-name',
+  amount: 29900,
+  currency: 'KRW',
+  paymentMethod: 'card',
+  providerStatus: 'PAID',
+  providerEventId: 'provider-event-id',
+  confirmationSource: 'provider_api_confirm',
+})
+\`\`\`
+
 ### updateTransaction()
-Confirm or annotate a transaction. Paid transitions require provider
-verification; non-financial annotations can still update pending transactions.
+Lower-level transaction update path. Prefer \`confirmPayment()\` for normal paid
+transitions. Use this only for compatibility paths that still require direct
+transaction annotation after provider verification, or for non-paid pending
+transaction updates.
 
 \`\`\`typescript
 const tx = await client.commerce.orders.updateTransaction({
-  pgPaymentId: 'toss-payment-id',
-  status: 'paid',  // pending | paid | failed | canceled
-  paymentKey: 'toss-payment-key',  // required when status is paid
-  amount: 29900,  // required when status is paid
+  pgPaymentId: 'provider-payment-id',
+  status: 'failed',  // pending | paid | failed | canceled
+  paymentMethod: 'card',
+  receiptUrl: 'https://...',
 })
 \`\`\`
 
@@ -5515,7 +5699,7 @@ const result = await client.commerce.shipping.calculate({
 }
 
 // src/resources/(docs)/customer-auth.ts
-var metadata45 = {
+var metadata46 = {
   name: "docs-customer-auth",
   title: "Customer Auth API",
   description: "01.software SDK Customer Auth API reference (client.customer)"
@@ -5693,7 +5877,7 @@ async function loadProfile() {
 }
 
 // src/resources/(docs)/browser-vs-server.ts
-var metadata46 = {
+var metadata47 = {
   name: "docs-browser-vs-server",
   title: "Client vs ServerClient",
   description: "When to use Client (createClient) vs ServerClient (createServerClient) in the 01.software SDK"
@@ -5859,7 +6043,7 @@ export function ProductList() {
 }
 
 // src/resources/(docs)/file-upload.ts
-var metadata47 = {
+var metadata48 = {
   name: "docs-file-upload",
   title: "File Upload",
   description: "01.software SDK file upload patterns using the images collection"
@@ -6010,7 +6194,7 @@ The platform stores files in Cloudflare R2 and serves via CDN (\`cdn.01.software
 }
 
 // src/resources/(docs)/webhook.ts
-var metadata48 = {
+var metadata49 = {
   name: "docs-webhook",
   title: "Webhooks",
   description: "01.software SDK webhook verification and event handling"
@@ -6018,15 +6202,21 @@ var metadata48 = {
 function handler18() {
   return `# Webhooks
 
-The platform dispatches HMAC-SHA256 signed webhook events to your registered URLs. Tenant developers own routing inside their webhook handler.
+The platform dispatches HMAC-SHA256 signed webhook events to registered URLs. Tenant developers own routing inside their webhook handler.
 
 ## Webhook Handling
 
-Use the SDK \`handleWebhook\` helper to verify signatures. For customer auth events, use \`createCustomerAuthWebhookHandler\` to wire delivery behavior in your app.
+Use the SDK \`handleWebhook\` helper to verify signatures. For customer auth events, use \`createCustomerAuthWebhookHandler\`; for semantic events, use SDK guards before reading event-specific fields.
 
 \`\`\`typescript
 import { handleWebhook, createCustomerAuthWebhookHandler } from '@01.software/sdk/webhook'
 
+function getWebhookSecret(): string {
+  const secret = process.env.WEBHOOK_SECRET
+  if (!secret) throw new Error('WEBHOOK_SECRET is required')
+  return secret
+}
+
 const handler = createCustomerAuthWebhookHandler({
   passwordReset: async (data) => {
     await sendPasswordResetEmail(data)
@@ -6035,7 +6225,7 @@ const handler = createCustomerAuthWebhookHandler({
 
 export async function POST(request: Request) {
   return handleWebhook(request, handler, {
-    secret: process.env.WEBHOOK_SECRET!,
+    secret: getWebhookSecret(),
   })
 }
 \`\`\`
@@ -6048,6 +6238,12 @@ export async function POST(request: Request) {
 // app/api/webhooks/route.ts
 import { handleWebhook, createCustomerAuthWebhookHandler } from '@01.software/sdk/webhook'
 
+function getWebhookSecret(): string {
+  const secret = process.env.WEBHOOK_SECRET
+  if (!secret) throw new Error('WEBHOOK_SECRET is required')
+  return secret
+}
+
 const customerAuthHandler = createCustomerAuthWebhookHandler({
   passwordReset: sendPasswordResetEmail,
 })
@@ -6058,25 +6254,161 @@ export async function POST(request: Request) {
 
     await customerAuthHandler(event)
   }, {
-    secret: process.env.WEBHOOK_SECRET!,
+    secret: getWebhookSecret(),
   })
 }
 \`\`\`
 
+## Commerce Notification Handler Example
+
+\`\`\`typescript
+import {
+  handleWebhook,
+  isCommerceNotificationWebhookEvent,
+} from '@01.software/sdk/webhook'
+
+function getWebhookSecret(): string {
+  const secret = process.env.WEBHOOK_SECRET
+  if (!secret) throw new Error('WEBHOOK_SECRET is required')
+  return secret
+}
+
+export async function POST(request: Request) {
+  return handleWebhook(request, async (event) => {
+    if (!isCommerceNotificationWebhookEvent(event)) return
+
+    const idempotencyKey = \`\${event.notification.intentId}:\${event.notification.dedupeKey}\`
+    const processed = await processOnce(idempotencyKey, async () => {
+      if (event.notification.event === 'orderPaid') {
+        const orderId = event.notification.orderId ?? event.data.orderId
+        if (orderId) await updateOrderWorkflow(orderId)
+      }
+
+      if (event.notification.event === 'fulfillmentShipped') {
+        const fulfillmentId =
+          event.notification.fulfillmentId ?? event.data.fulfillmentId
+        if (fulfillmentId) await updateFulfillmentWorkflow(fulfillmentId)
+      }
+    })
+
+    if (!processed) return
+  }, {
+    secret: getWebhookSecret(),
+  })
+}
+\`\`\`
+
+Back \`processOnce()\` with durable storage such as a database unique key or queue idempotency store; do not use process-local memory for webhook idempotency.
+
+## Headless Commerce Email Workers
+
+For tenant-owned transactional email, use \`commerce.notification\` as the trigger and build a signed worker with \`createCommerceEmailWebhookHandler()\`. 01.software owns event timing, delivery retries, signing, and idempotency signals; the tenant worker owns template rendering, provider credentials, extra order/customer fetches via \`createServerClient\`, and final delivery through a tenant provider such as Resend.
+
+Use \`getCommerceNotificationIdempotencyKey(event)\` or the \`idempotencyKey\` passed by \`createCommerceEmailWebhookHandler()\`, then guard provider sends with durable \`processOnce(idempotencyKey, ...)\` storage. The webhook payload is PII-light and is not enough for recipient data, so fetch recipient/template context with server SDK credentials. In the v1 headless path, do not store tenant ESP secrets in 01.software and do not ask 01.software to send directly through the tenant provider.
+
 ## Webhook Payload Structure
 
 All webhook events share this envelope:
 
 \`\`\`typescript
 {
-  collection: string,    // e.g. 'customers'
-  operation: string,     // e.g. 'password-reset'
-  data: object,          // event-specific payload
+  collection: string,
+  operation: string,
+  data: object,
+  eventType?: string,
+  change?: object,
+  notification?: object,
+  timestamp?: string,
+  deliveryId?: string,
 }
 \`\`\`
 
 ## Event Types
 
+### Commerce Notification
+
+V1 commerce notification webhooks use \`eventType: "commerce.notification"\` and \`operation: "notification"\`. The public SDK exports \`COMMERCE_NOTIFICATION_EVENT_TYPE\`, \`COMMERCE_NOTIFICATION_OPERATION\`, commerce notification types, and \`isCommerceNotificationWebhookEvent()\` from \`@01.software/sdk/webhook\`.
+
+Canonical example (public operational identifiers only; no PII, payment/provider fields, metadata, tracking number, or tracking URL):
+
+\`\`\`json
+{
+  "eventType": "commerce.notification",
+  "collection": "orders",
+  "operation": "notification",
+  "data": {
+    "orderId": "order_123",
+    "orderNumber": "ORD-1001",
+    "status": "paid",
+    "totalAmount": 5000,
+    "currency": "KRW"
+  },
+  "notification": {
+    "event": "orderPaid",
+    "intentId": "intent_123",
+    "dedupeKey": "orderPaid:order_123",
+    "orderId": "order_123"
+  },
+  "timestamp": "2026-05-29T00:00:00.000Z",
+  "deliveryId": "delivery_attempt_123"
+}
+\`\`\`
+
+Use \`notification.intentId\` plus \`notification.dedupeKey\` for semantic idempotency. \`deliveryId\` is per delivery attempt / observability and may not be stable across semantic retries.
+Some normalized deliveries may include \`data.source\` or \`change\` metadata, but handlers should treat those fields as optional. Route from \`notification.orderId\`, \`notification.fulfillmentId\`, \`notification.returnId\`, or the matching typed \`data.*Id\` field.
+
+V1 source subscription semantics:
+
+- \`orderPaid\` and \`orderDelivered\` are delivered through \`orders\`-scoped endpoints.
+- \`fulfillmentShipped\` is delivered through \`fulfillments\`-scoped endpoints.
+- \`returnRequested\` and \`returnCompleted\` are delivered through \`returns\`-scoped endpoints.
+- Empty, unscoped, and all-collection endpoints do not receive v1 semantic commerce notifications.
+
+### Collection Order Changed
+
+Admin Panel manual ordering is delivered as a semantic collection update:
+
+- \`operation\` remains \`"update"\` for compatibility.
+- \`eventType\` is \`"collection.orderChanged"\`.
+- SDK handlers should use \`isOrderChangedWebhookEvent()\` from \`@01.software/sdk/webhook\`.
+- \`change.scope\` identifies collection-level ordering versus join ordering.
+- Route on public semantics such as \`change.scope.collection\`, \`change.scope.field\`, and \`change.moved.id\`.
+- Do not branch on hidden Payload order fields or private backing collections; diagnostic fields may still be present.
+- Customer group member ordering is currently unsupported and does not emit a semantic order-change webhook.
+
+\`\`\`typescript
+import { handleWebhook, isOrderChangedWebhookEvent } from '@01.software/sdk/webhook'
+
+function getWebhookSecret(): string {
+  const secret = process.env.WEBHOOK_SECRET
+  if (!secret) throw new Error('WEBHOOK_SECRET is required')
+  return secret
+}
+
+export async function POST(request: Request) {
+  return handleWebhook(
+    request,
+    async (event) => {
+      if (isOrderChangedWebhookEvent(event)) {
+        if (event.change.scope.kind === 'join') {
+          console.log('Join order changed', {
+            collection: event.change.scope.collection,
+            field: event.change.scope.field,
+            parentId: event.change.scope.id,
+            movedCollection: event.change.moved.collection,
+            movedId: event.change.moved.id,
+          })
+        }
+        return
+      }
+
+      console.log('Content changed', event.collection, event.operation)
+    },
+    { secret: getWebhookSecret() },
+  )
+}
+\`\`\`
+
 ### Customer Password Reset
 
 Dispatched when a customer calls \`client.customer.forgotPassword(email)\`.
@@ -6089,8 +6421,8 @@ Dispatched when a customer calls \`client.customer.forgotPassword(email)\`.
     customerId: string,
     email: string,
     name: string,
-    resetPasswordToken: string,   // raw token to include in reset link
-    resetPasswordExpiresAt: string,  // ISO 8601 expiry (1 hour from dispatch)
+    resetPasswordToken: string,
+    resetPasswordExpiresAt: string,
   }
 }
 \`\`\`
@@ -6105,11 +6437,13 @@ async function sendPasswordResetEmail(data: {
   resetPasswordToken: string
   resetPasswordExpiresAt: string
 }) {
-  const resetUrl = \`https://yourstore.com/reset-password?token=\${data.resetPasswordToken}\`
+  const resetUrl = new URL('https://yourstore.com/reset-password')
+  resetUrl.searchParams.set('token', data.resetPasswordToken)
+
   await emailService.send({
     to: data.email,
     subject: 'Reset your password',
-    body: \`Reset link (expires \${data.resetPasswordExpiresAt}): \${resetUrl}\`,
+    body: \`Reset link (expires \${data.resetPasswordExpiresAt}): \${resetUrl.toString()}\`,
   })
 }
 \`\`\`
@@ -6120,11 +6454,11 @@ Failed webhook deliveries are queued with automatic retries. Ensure your handler
 
 ## Webhook Configuration
 
-Configure webhook URLs in the 01.software console under Tenant Settings > Webhooks. Multiple URLs can be registered; all receive every event.`;
+Configure webhook URLs in the 01.software console under Tenant Settings > Webhooks. Multiple URLs can be registered; scoped endpoints receive events for their configured source collection.`;
 }
 
 // src/resources/(docs)/product-detail.ts
-var metadata49 = {
+var metadata50 = {
   name: "docs-product-detail",
   title: "Product Detail Helper",
   description: "01.software SDK commerce.product.detail helper guide"
@@ -6148,8 +6482,8 @@ const client = createClient({
 })
 
 const detail = await client.commerce.product.detail({ slug: 'my-product' })
-if (!detail) return notFound()
-const selection = resolveProductSelection(detail, {
+if (!detail.found) return notFound()
+const selection = resolveProductSelection(detail.product, {
   search: '?opt.option-color=color-black',
 })
 // selection.selectedVariant, selection.price, selection.stock, selection.media
@@ -6200,23 +6534,41 @@ export default async function ProductPage({ params }: { params: { slug: string }
     publishableKey: process.env.NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY!,
   })
   const detail = await client.commerce.product.detail({ slug: params.slug })
-  if (!detail) return notFound()
-  return <ProductView detail={detail} />
+  if (!detail.found) return notFound()
+  return <ProductView detail={detail.product} />
 }
 \`\`\`
 
-## The \`null\` return contract
+## The \`ProductDetailResult\` return contract
+
+The endpoint returns 404 for \`not_found\`, \`not_published\`, or \`feature_disabled\`. The SDK maps those product-detail 404s to \`{ found: false, reason }\` so consumer UIs can render a standard 404, preview CTA, or feature-gating UI. Permission/auth errors, including 403 tenant mismatches, still throw typed SDK errors.
 
-The endpoint returns 404 for \`not_found\`, \`not_published\`, \`tenant_mismatch\`, or \`feature_disabled\`. The SDK collapses all 404s to \`null\` so consumer UIs render one "not available" path.
+Successful product payloads expose inventory rollups without sentinel values: \`product.totalInventory\` is the tracked stock sum across non-unlimited variants, \`null\` when no variants are tracked, and \`product.hasUnlimitedVariant\` signals whether any variant is unlimited.
 
 ## Backend correlation
 
-Log \`client.lastRequestId\` against backend logs \u2014 the endpoint records the exact 404 code alongside the request ID.`;
+Log \`client.lastRequestId\` against backend logs \u2014 the endpoint records the exact 404 reason alongside the request ID.`;
 }
 
 // src/server.ts
 var REGISTERED_TOOLS_BY_SERVER = /* @__PURE__ */ new WeakMap();
-function registerTool(server, schema37, meta, handler20) {
+function hasToolPolicy(toolName) {
+  return Object.prototype.hasOwnProperty.call(TOOL_POLICY_MANIFEST, toolName);
+}
+function runtimeAnnotationsFor(meta) {
+  if (!hasToolPolicy(meta.name)) {
+    throw new Error(`No tool-policy entry for registered MCP tool ${meta.name}`);
+  }
+  const policy = TOOL_POLICY_MANIFEST[meta.name];
+  return {
+    title: meta.annotations?.title,
+    readOnlyHint: policy.annotationPolicy.readOnly,
+    destructiveHint: policy.annotationPolicy.destructive,
+    idempotentHint: policy.annotationPolicy.idempotent,
+    openWorldHint: policy.annotationPolicy.openWorld
+  };
+}
+function registerTool(server, schema38, meta, handler20) {
   let registered = REGISTERED_TOOLS_BY_SERVER.get(server);
   if (!registered) {
     registered = /* @__PURE__ */ new Set();
@@ -6227,16 +6579,20 @@ function registerTool(server, schema37, meta, handler20) {
     meta.name,
     {
       description: meta.description,
-      inputSchema: schema37,
-      annotations: meta.annotations
+      inputSchema: schema38,
+      annotations: runtimeAnnotationsFor(meta)
     },
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     async (params) => {
       const ctx = tenantAuthContext();
       if (ctx) {
-        const decision = evaluateToolPolicy(meta.name, ctx.scopes);
+        const decision = evaluateToolPolicy(
+          meta.name,
+          ctx.scopes,
+          ctx.tenantRole
+        );
         if (!decision.allowed) {
-          const status = decision.reason === "insufficient_scope" ? 403 : 500;
+          const status = decision.reason === "insufficient_scope" || decision.reason === "insufficient_role" ? 403 : 500;
           return {
             content: [
               {
@@ -6273,13 +6629,13 @@ function registerTool(server, schema37, meta, handler20) {
     }
   );
 }
-function registerPrompt(server, schema37, meta, handler20) {
+function registerPrompt(server, schema38, meta, handler20) {
   server.registerPrompt(
     meta.name,
     {
       title: meta.title,
       description: meta.description,
-      argsSchema: schema37
+      argsSchema: schema38
     },
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     (params) => ({
@@ -6351,211 +6707,232 @@ function createServer(options = {}) {
       server,
       schema10,
       metadata10,
-      createReturn
+      confirmPayment
     );
     registerTool(
       server,
       schema11,
       metadata11,
-      updateReturn
+      createReturn
     );
     registerTool(
       server,
       schema12,
       metadata12,
-      returnWithRefund
+      updateReturn
     );
-    registerTool(server, schema13, metadata13, addCartItem);
     registerTool(
       server,
-      schema14,
-      metadata14,
-      updateCartItem
+      schema13,
+      metadata13,
+      returnWithRefund
     );
+    registerTool(server, schema14, metadata14, addCartItem);
     registerTool(
       server,
       schema15,
       metadata15,
-      removeCartItem
+      updateCartItem
     );
     registerTool(
       server,
       schema16,
       metadata16,
-      applyDiscount
+      removeCartItem
     );
     registerTool(
       server,
       schema17,
       metadata17,
-      removeDiscount
+      applyDiscount
     );
-    registerTool(server, schema18, metadata18, clearCart);
     registerTool(
       server,
-      schema19,
-      metadata19,
-      validateDiscount
+      schema18,
+      metadata18,
+      removeDiscount
     );
+    registerTool(server, schema19, metadata19, clearCart);
     registerTool(
       server,
       schema20,
       metadata20,
+      validateDiscount
+    );
+    registerTool(
+      server,
+      schema21,
+      metadata21,
       calculateShipping
     );
-    registerTool(server, schema21, metadata21, stockCheck);
-    registerTool(server, schema22, metadata22, productDetail);
+    registerTool(server, schema22, metadata22, stockCheck);
     registerTool(
       server,
       schema23,
       metadata23,
+      productDetail
+    );
+    registerTool(
+      server,
+      schema24,
+      metadata24,
       productUpsert
     );
   }
-  registerTool(
-    server,
-    schema24,
-    metadata24,
-    getCollectionSchemaTool
-  );
   registerTool(
     server,
     schema25,
     metadata25,
-    handler
+    getCollectionSchemaTool
   );
   registerTool(
     server,
     schema26,
     metadata26,
-    handler2
+    handler
   );
   registerTool(
     server,
     schema27,
     metadata27,
-    listConfigurableFields
+    handler2
   );
   registerTool(
     server,
     schema28,
     metadata28,
-    updateFieldConfig
+    listConfigurableFields
   );
   registerTool(
     server,
     schema29,
     metadata29,
-    handler3
+    updateFieldConfig
   );
   registerTool(
     server,
     schema30,
     metadata30,
-    handler4
+    handler3
   );
   registerTool(
     server,
     schema31,
     metadata31,
-    handler5
+    handler4
   );
   registerTool(
     server,
     schema32,
     metadata32,
-    handler6
+    handler5
   );
-  registerPrompt(
+  registerTool(
     server,
     schema33,
     metadata33,
-    sdkUsageGuide
+    handler6
   );
   registerPrompt(
     server,
     schema34,
     metadata34,
-    collectionQueryHelp
+    sdkUsageGuide
   );
   registerPrompt(
     server,
     schema35,
     metadata35,
-    orderFlowGuide
+    collectionQueryHelp
   );
   registerPrompt(
     server,
     schema36,
     metadata36,
+    orderFlowGuide
+  );
+  registerPrompt(
+    server,
+    schema37,
+    metadata37,
     featureSetupGuide
   );
   registerStaticResource(
     server,
-    "config://app",
-    metadata37,
+    mcpResourceUri("app-config"),
+    metadata38,
     handler7
   );
   registerStaticResource(
     server,
-    "collections://schema",
-    metadata38,
+    mcpResourceUri("collections-schema"),
+    metadata39,
     handler8
   );
   registerStaticResource(
     server,
-    "docs://sdk/getting-started",
-    metadata39,
+    mcpResourceUri("docs-getting-started"),
+    metadata40,
     handler9
   );
-  registerStaticResource(server, "docs://sdk/guides", metadata40, handler10);
-  registerStaticResource(server, "docs://sdk/api", metadata41, handler11);
   registerStaticResource(
     server,
-    "docs://sdk/query-builder",
+    mcpResourceUri("docs-guides"),
+    metadata41,
+    handler10
+  );
+  registerStaticResource(
+    server,
+    mcpResourceUri("docs-api"),
     metadata42,
-    handler12
+    handler11
   );
   registerStaticResource(
     server,
-    "docs://sdk/react-query",
+    mcpResourceUri("docs-query-builder"),
     metadata43,
-    handler13
+    handler12
   );
   registerStaticResource(
     server,
-    "docs://sdk/server-api",
+    mcpResourceUri("docs-react-query"),
     metadata44,
-    handler14
+    handler13
   );
   registerStaticResource(
     server,
-    "docs://sdk/customer-auth",
+    mcpResourceUri("docs-server-api"),
     metadata45,
-    handler15
+    handler14
   );
   registerStaticResource(
     server,
-    "docs://sdk/browser-vs-server",
+    mcpResourceUri("docs-customer-auth"),
     metadata46,
-    handler16
+    handler15
   );
   registerStaticResource(
     server,
-    "docs://sdk/file-upload",
+    mcpResourceUri("docs-browser-vs-server"),
     metadata47,
-    handler17
+    handler16
   );
   registerStaticResource(
     server,
-    "docs://sdk/webhook",
+    mcpResourceUri("docs-file-upload"),
     metadata48,
-    handler18
+    handler17
   );
   registerStaticResource(
     server,
-    "docs://sdk/product-detail",
+    mcpResourceUri("docs-webhook"),
     metadata49,
+    handler18
+  );
+  registerStaticResource(
+    server,
+    mcpResourceUri("docs-product-detail"),
+    metadata50,
     handler19
   );
   return server;
@@ -6568,6 +6945,7 @@ export {
   MCP_TENANT_CLAIM,
   MCP_TENANT_ROLE_CLAIM,
   MCP_SCOPES,
+  MCP_RESOURCE_LABELS,
   requestContext,
   mcpServicePublicJwks,
   createMcpTelemetrySummary,
@@ -6575,4 +6953,4 @@ export {
   flushMcpTelemetrySummary,
   createServer
 };
-//# sourceMappingURL=chunk-2EPYMNHW.js.map
+//# sourceMappingURL=chunk-3TIDAOYP.js.map