@01.software/cli 0.12.0 → 0.13.0

package/dist/mcp/vercel.js

@@ -26,49 +26,79 @@ var MCP_RESOURCE_INVENTORY = [
   {
     uri: "docs://sdk/getting-started",
     label: "getting-started",
-    registeredName: "docs-getting-started"
+    registeredName: "docs-getting-started",
+    canonicalDocsSlug: ["developers", "sdk"],
+    canonicalDocsKeywords: ["Install the package", "@01.software/sdk"]
+  },
+  {
+    uri: "docs://sdk/guides",
+    label: "guides",
+    registeredName: "docs-guides",
+    canonicalDocsSlug: ["developers", "sdk"],
+    canonicalDocsKeywords: ["Setup Flow", "Next Actions"]
+  },
+  {
+    uri: "docs://sdk/api",
+    label: "api",
+    registeredName: "docs-api",
+    canonicalDocsSlug: ["developers", "api"],
+    canonicalDocsKeywords: ["/api/openapi", "OpenAPI"]
   },
-  { 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"
+    registeredName: "docs-query-builder",
+    canonicalDocsSlug: ["developers", "sdk"],
+    canonicalDocsKeywords: ["query helpers", "@01.software/sdk/query"]
   },
   {
     uri: "docs://sdk/react-query",
     label: "react-query",
-    registeredName: "docs-react-query"
+    registeredName: "docs-react-query",
+    canonicalDocsSlug: ["developers", "sdk"],
+    canonicalDocsKeywords: ["React", "@tanstack/react-query"]
   },
   {
     uri: "docs://sdk/server-api",
     label: "server-api",
-    registeredName: "docs-server-api"
+    registeredName: "docs-server-api",
+    canonicalDocsSlug: ["developers", "api"],
+    canonicalDocsKeywords: ["Server writes", "trusted server credentials"]
   },
   {
     uri: "docs://sdk/customer-auth",
     label: "customer-auth",
-    registeredName: "docs-customer-auth"
+    registeredName: "docs-customer-auth",
+    canonicalDocsSlug: ["developers", "authentication"],
+    canonicalDocsKeywords: ["Publishable Key", "Secret Key"]
   },
   {
     uri: "docs://sdk/browser-vs-server",
     label: "browser-vs-server",
-    registeredName: "docs-browser-vs-server"
+    registeredName: "docs-browser-vs-server",
+    canonicalDocsSlug: ["developers", "sdk"],
+    canonicalDocsKeywords: ["browser client", "server client"]
   },
   {
     uri: "docs://sdk/file-upload",
     label: "file-upload",
-    registeredName: "docs-file-upload"
+    registeredName: "docs-file-upload",
+    canonicalDocsSlug: ["developers", "api"],
+    canonicalDocsKeywords: ["direct HTTP", "machine-readable contract"]
   },
   {
     uri: "docs://sdk/webhook",
     label: "webhook",
-    registeredName: "docs-webhook"
+    registeredName: "docs-webhook",
+    canonicalDocsSlug: ["developers", "webhooks"],
+    canonicalDocsKeywords: ["Webhook", "commerce.notification"]
   },
   {
     uri: "docs://sdk/product-detail",
     label: "product-detail",
-    registeredName: "docs-product-detail"
+    registeredName: "docs-product-detail",
+    canonicalDocsSlug: ["recipes", "product-detail"],
+    canonicalDocsKeywords: ["Product detail page", "commerce.product.detail"]
   }
 ];
 var MCP_RESOURCE_LABELS = MCP_RESOURCE_INVENTORY.map(
@@ -460,6 +490,29 @@ var transactionStatusSchema = z3.enum([
   "failed",
   "canceled"
 ]);
+var financialStatusSchema = z3.enum([
+  "pending",
+  "paid",
+  "failed",
+  "canceled",
+  "partially_refunded",
+  "refunded"
+]);
+var confirmationStatusSchema = z3.enum(["unconfirmed", "confirmed"]);
+var fulfillmentOrderStatusSchema = z3.enum([
+  "open",
+  "in_progress",
+  "on_hold",
+  "canceled",
+  "closed"
+]);
+var shipmentStatusSchema = z3.enum([
+  "pending",
+  "shipped",
+  "delivered",
+  "canceled",
+  "failed"
+]);
 var orderStatusSchema = z3.enum([
   "pending",
   "paid",
@@ -474,7 +527,7 @@ var orderStatusSchema = z3.enum([
   "return_processing",
   "returned"
 ]);
-var entityIdSchema = z3.union([z3.string(), z3.number()]).transform(String);
+var entityIdSchema = z3.union([z3.string().min(1), z3.number()]).transform(String);
 var createOrderItemSchema = z3.object({
   product: entityIdSchema,
   variant: entityIdSchema,
@@ -482,7 +535,7 @@ var createOrderItemSchema = z3.object({
   quantity: z3.number().int().positive("quantity must be a positive integer"),
   unitPrice: z3.number().optional(),
   totalPrice: z3.number().optional()
-});
+}).strict();
 var createOrderSchema = z3.object({
   pgPaymentId: z3.string().min(1).optional(),
   orderNumber: z3.string().min(1, "orderNumber is required"),
@@ -491,7 +544,7 @@ var createOrderSchema = z3.object({
     name: z3.string().optional(),
     email: z3.string().email("Invalid email format"),
     phone: z3.string().optional()
-  }),
+  }).strict(),
   shippingAddress: z3.object({
     postalCode: z3.string().optional(),
     address: z3.string().optional(),
@@ -499,12 +552,12 @@ var createOrderSchema = z3.object({
     deliveryMessage: z3.string().optional(),
     recipientName: z3.string().optional(),
     phone: z3.string().optional()
-  }),
+  }).strict(),
   orderItems: z3.array(createOrderItemSchema).min(1, "At least one order item is required").max(100, "Maximum 100 items per order"),
   totalAmount: z3.number().nonnegative("totalAmount must be non-negative"),
   shippingAmount: z3.number().min(0).optional(),
   discountCode: z3.string().optional()
-});
+}).strict();
 var CreateOrderSchema = createOrderSchema;
 var updateTransactionSchema = z3.object({
   pgPaymentId: z3.string().min(1, "pgPaymentId is required").describe("PG payment ID (required)"),
@@ -553,7 +606,7 @@ var returnReasonSchema = z3.enum([
 ]);
 var restockActionSchema = z3.enum(["return_to_stock", "discard"]);
 var returnWithRefundItemSchema = z3.object({
-  orderItem: z3.union([z3.string(), z3.number()]).transform(String),
+  orderItem: z3.union([z3.string().min(1), z3.number()]).transform(String),
   quantity: z3.number().int().positive("quantity must be a positive integer"),
   restockAction: restockActionSchema.default("return_to_stock"),
   restockingFee: z3.number().min(0, "restockingFee must be non-negative").optional().describe("Restocking fee charged for this line (ADR 0005 \xA7Gap 1)")
@@ -567,10 +620,29 @@ var returnWithRefundSchema = z3.object({
   returnShippingFee: z3.number().min(0, "returnShippingFee must be non-negative").optional().describe(
     "Return shipping fee charged to the customer (ADR 0005 \xA7Gap 1)"
   ),
+  initialShippingRefundAmount: z3.number().min(0, "initialShippingRefundAmount must be non-negative").optional().describe("Initial order shipping amount refunded to the customer"),
+  initialShippingRefundOverrideNote: z3.string().min(1).optional().describe(
+    "Operator audit note required when overriding policy suggestion"
+  ),
   pgPaymentId: z3.string().min(1, "pgPaymentId is required").describe("PG payment ID for refund (required)"),
   paymentKey: z3.string().min(1).optional().describe("Provider payment key for verified refund"),
   refundReceiptUrl: z3.string().optional().describe("Refund receipt URL (optional)")
 }).strict();
+var createReturnSchema = z3.object({
+  orderNumber: z3.string().min(1, "orderNumber is required").describe("Order number (required)"),
+  reason: returnReasonSchema.optional().describe("Return reason (optional)"),
+  reasonDetail: z3.string().optional().describe("Detailed reason text (optional)"),
+  returnItems: z3.array(returnWithRefundItemSchema).min(1, "At least one return item is required").max(100, "Too many return items").describe("Array of products to return (required)"),
+  refundAmount: z3.number().min(0, "refundAmount must be non-negative").describe(
+    "Line refund amount before initial shipping refund (required, min 0)"
+  ),
+  returnShippingFee: z3.number().min(0, "returnShippingFee must be non-negative").optional().describe("Return shipping fee charged to the customer"),
+  initialShippingRefundAmount: z3.number().min(0, "initialShippingRefundAmount must be non-negative").optional().describe("Initial order shipping amount refunded to the customer"),
+  initialShippingRefundOverrideNote: z3.string().min(1).optional().describe(
+    "Operator audit note required when overriding policy suggestion"
+  )
+}).strict();
+var CreateReturnSchema = createReturnSchema;
 var ReturnWithRefundSchema = returnWithRefundSchema;
 var cancelReasonCodeSchema = z3.enum([
   "customer",
@@ -844,6 +916,11 @@ var MCP_TOOL_CONTRACT = {
     oauthScope: "mcp:write",
     readOnly: false
   },
+  "prepare-fulfillment-order": {
+    consoleRole: "tenant-admin",
+    oauthScope: "mcp:write",
+    readOnly: false
+  },
   "update-fulfillment": {
     consoleRole: "tenant-admin",
     oauthScope: "mcp:write",
@@ -1116,6 +1193,13 @@ var TOOL_POLICY_MANIFEST = {
     consoleSurface: "POST /api/orders/create-fulfillment",
     annotationPolicy: NON_DESTRUCTIVE_MUTATION_ANNOTATION
   },
+  "prepare-fulfillment-order": {
+    category: "mutation-fulfillment",
+    oauthScope: MCP_SCOPES.write,
+    consoleRole: "tenant-admin",
+    consoleSurface: "POST /api/fulfillment-orders/prepare-fulfillment-order",
+    annotationPolicy: NON_DESTRUCTIVE_MUTATION_ANNOTATION
+  },
   "update-fulfillment": {
     category: "mutation-fulfillment",
     oauthScope: MCP_SCOPES.write,
@@ -1742,22 +1826,13 @@ async function createOrder(params) {
 import { z as z7 } from "zod";
 var schema5 = {
   orderNumber: z7.string().min(1).describe("Order number (required)"),
-  status: z7.enum([
-    "pending",
-    "paid",
-    "failed",
-    "canceled",
-    "preparing",
-    "shipped",
-    "delivered",
-    "confirmed"
-  ]).describe(
-    "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."
+  status: z7.enum(["confirmed"]).describe(
+    "Order confirmation status mutation. Shipping/display statuses are derived from fulfillment orders and shipments; financial/refund states are set by payment/refund flows."
   )
 };
 var metadata5 = {
   name: "update-order",
-  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.",
+  description: "Confirm an order after delivery. Financial, fulfillment-order, shipment, return, and display statuses are explicit server-derived axes and are not writable through this tool.",
   annotations: {
     title: "Update order status",
     readOnlyHint: false,
@@ -1815,20 +1890,19 @@ async function checkout(params) {
 import { z as z9 } 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(
-    'Tracking number (optional). Setting carrier + tracking triggers "shipped" status'
-  ),
+  fulfillmentOrderId: z9.string().optional().describe("Fulfillment order ID to ship (optional)"),
+  carrier: z9.string().min(1).optional().describe("Shipping carrier name"),
+  trackingNumber: z9.string().min(1).optional().describe("Tracking number"),
   items: z9.array(
     z9.object({
       orderItem: z9.string().min(1).describe("Order item ID"),
       quantity: z9.number().int().positive().describe("Quantity to fulfill")
     })
-  ).describe("Array of items to fulfill (required)")
+  ).optional().describe("Array of items to fulfill (optional)")
 };
 var metadata7 = {
   name: "create-fulfillment",
-  description: "Create a shipment/fulfillment for order items. Auto-updates order status (paid \u2192 preparing \u2192 shipped).",
+  description: "Create a shipment for fulfillment order items. Tracking information can be supplied now or updated later with update-fulfillment.",
   annotations: {
     title: "Create fulfillment",
     readOnlyHint: false,
@@ -1838,6 +1912,7 @@ var metadata7 = {
 };
 async function createFulfillment({
   orderNumber,
+  fulfillmentOrderId,
   carrier,
   trackingNumber,
   items
@@ -1846,8 +1921,9 @@ async function createFulfillment({
     const client = getClient();
     const result = await client.commerce.orders.createFulfillment({
       orderNumber,
-      carrier,
-      trackingNumber,
+      fulfillmentOrderId,
+      ...carrier ? { carrier } : {},
+      ...trackingNumber ? { trackingNumber } : {},
       items
     });
     return toolSuccess({ data: result });
@@ -1856,23 +1932,48 @@ async function createFulfillment({
   }
 }
 
-// src/tools/update-fulfillment.ts
+// src/tools/prepare-fulfillment-order.ts
 import { z as z10 } from "zod";
 var schema8 = {
-  fulfillmentId: z10.string().min(1).describe("Fulfillment ID (required)"),
-  status: z10.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(
-    "Shipping carrier (optional, changeable only in pending/packed status)"
-  ),
-  trackingNumber: z10.string().optional().describe(
-    "Tracking number (optional, changeable only in pending/packed status)"
-  )
+  orderNumber: z10.string().min(1).describe("Order number (required)")
 };
 var metadata8 = {
+  name: "prepare-fulfillment-order",
+  description: "Prepare starts fulfillment work and does not require carrier/tracking.",
+  annotations: {
+    title: "Prepare fulfillment order",
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false
+  }
+};
+async function prepareFulfillmentOrder({
+  orderNumber
+}) {
+  try {
+    const client = getClient();
+    const result = await client.commerce.orders.prepareFulfillmentOrder({
+      orderNumber
+    });
+    return toolSuccess({ data: result });
+  } catch (error) {
+    return toolError(error);
+  }
+}
+
+// src/tools/update-fulfillment.ts
+import { z as z11 } from "zod";
+var schema9 = {
+  fulfillmentId: z11.string().min(1).describe("Fulfillment ID (required)"),
+  status: z11.enum(["shipped", "delivered", "failed"]).optional().describe(
+    "New shipment status. Shipment lifecycle: shipped\u2192delivered/failed"
+  ),
+  carrier: z11.string().optional().describe("Shipping carrier (optional; can be added or corrected later)"),
+  trackingNumber: z11.string().optional().describe("Tracking number (optional; can be added or corrected later)")
+};
+var metadata9 = {
   name: "update-fulfillment",
-  description: "Update fulfillment status, carrier, and tracking number. Auto-updates order status when all fulfillments are delivered.",
+  description: "Update shipment status, carrier, or tracking number. Tracking can be added after shipment creation.",
   annotations: {
     title: "Update fulfillment",
     readOnlyHint: false,
@@ -1888,11 +1989,16 @@ async function updateFulfillment({
 }) {
   try {
     const client = getClient();
+    if (status === void 0 && carrier === void 0 && trackingNumber === void 0) {
+      return toolError(
+        new Error("status, carrier, or trackingNumber is required")
+      );
+    }
     const result = await client.commerce.orders.updateFulfillment({
       fulfillmentId,
-      status,
-      carrier,
-      trackingNumber
+      ...status ? { status } : {},
+      ...carrier ? { carrier } : {},
+      ...trackingNumber ? { trackingNumber } : {}
     });
     return toolSuccess({ data: result });
   } catch (error) {
@@ -1901,8 +2007,8 @@ async function updateFulfillment({
 }
 
 // src/tools/update-transaction.ts
-var schema9 = UpdateTransactionSchema.shape;
-var metadata9 = {
+var schema10 = UpdateTransactionSchema.shape;
+var metadata10 = {
   name: "update-transaction",
   description: "Update transaction status, payment method, and receipt URL.",
   annotations: {
@@ -1938,8 +2044,8 @@ async function updateTransaction({
 }
 
 // src/tools/confirm-payment.ts
-var schema10 = ConfirmPaymentSchema.shape;
-var metadata10 = {
+var schema11 = ConfirmPaymentSchema.shape;
+var metadata11 = {
   name: "confirm-payment",
   description: "Confirm a provider-verified ecommerce payment through the generic payment confirmation flow.",
   annotations: {
@@ -1966,10 +2072,10 @@ var CancelOrderToolSchema = CancelOrderSchema.extend({
     "Optional X-Idempotency-Key forwarded to the Console cancel endpoint"
   )
 }).strict();
-var schema11 = CancelOrderToolSchema.shape;
-var metadata11 = {
+var schema12 = CancelOrderToolSchema.shape;
+var metadata12 = {
   name: "cancel-order",
-  description: "Cancel an eligible pre-fulfillment order through the provider-verified cancellation flow. Paid captured orders are refunded before the local order moves to canceled; shipped, delivered, active-return, and fulfilled orders are rejected.",
+  description: "Cancel an eligible order through the server-derived local cancellation flow. Paid captured orders move to canceled locally and require separate storefront PG refund resolution; preparation fulfillment orders are voided when no shipment exists, while shipped, delivered, active-return, and fulfilled orders are rejected.",
   annotations: {
     title: "Cancel order",
     readOnlyHint: false,
@@ -1994,20 +2100,8 @@ async function cancelOrder(params) {
 }
 
 // src/tools/create-return.ts
-import { z as z11 } from "zod";
-var schema12 = {
-  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")
-    })
-  ).describe("Array of products to return (required)"),
-  refundAmount: z11.number().nonnegative().describe("Refund amount (required, min 0)")
-};
-var metadata12 = {
+var schema13 = CreateReturnSchema.shape;
+var metadata13 = {
   name: "create-return",
   description: "Create a return request for an order. Only works for delivered/confirmed orders. Updates order status to return_requested.",
   annotations: {
@@ -2022,7 +2116,10 @@ async function createReturn({
   reason,
   reasonDetail,
   returnItems,
-  refundAmount
+  refundAmount,
+  returnShippingFee,
+  initialShippingRefundAmount,
+  initialShippingRefundOverrideNote
 }) {
   try {
     const client = getClient();
@@ -2031,7 +2128,10 @@ async function createReturn({
       reason,
       reasonDetail,
       returnItems,
-      refundAmount
+      refundAmount,
+      returnShippingFee,
+      initialShippingRefundAmount,
+      initialShippingRefundOverrideNote
     });
     return toolSuccess({ data: result });
   } catch (error) {
@@ -2041,13 +2141,13 @@ async function createReturn({
 
 // src/tools/update-return.ts
 import { z as z12 } from "zod";
-var schema13 = {
+var schema14 = {
   returnId: z12.string().min(1).describe("Return ID (required)"),
   status: z12.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 metadata13 = {
+var metadata14 = {
   name: "update-return",
   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: {
@@ -2074,8 +2174,8 @@ async function updateReturn({
 }
 
 // src/tools/return-with-refund.ts
-var schema14 = ReturnWithRefundSchema.shape;
-var metadata14 = {
+var schema15 = ReturnWithRefundSchema.shape;
+var metadata15 = {
   name: "return-with-refund",
   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: {
@@ -2092,6 +2192,8 @@ async function returnWithRefund({
   returnItems,
   refundAmount,
   returnShippingFee,
+  initialShippingRefundAmount,
+  initialShippingRefundOverrideNote,
   pgPaymentId,
   paymentKey,
   refundReceiptUrl
@@ -2105,6 +2207,8 @@ async function returnWithRefund({
       returnItems,
       refundAmount,
       returnShippingFee,
+      initialShippingRefundAmount,
+      initialShippingRefundOverrideNote,
       pgPaymentId,
       paymentKey,
       refundReceiptUrl
@@ -2118,14 +2222,14 @@ async function returnWithRefund({
 
 // src/tools/add-cart-item.ts
 import { z as z13 } from "zod";
-var schema15 = {
+var schema16 = {
   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)")
 };
-var metadata15 = {
+var metadata16 = {
   name: "add-cart-item",
   description: "Add a product to cart. Validates stock, merges quantity if item already exists, recalculates totals.",
   annotations: {
@@ -2159,11 +2263,11 @@ async function addCartItem({
 
 // src/tools/update-cart-item.ts
 import { z as z14 } from "zod";
-var schema16 = {
+var schema17 = {
   cartItemId: z14.string().min(1).describe("Cart item ID (required)"),
   quantity: z14.number().int().positive().describe("New quantity (required, positive integer)")
 };
-var metadata16 = {
+var metadata17 = {
   name: "update-cart-item",
   description: "Update cart item quantity. Validates stock availability, recalculates cart totals.",
   annotations: {
@@ -2188,10 +2292,10 @@ async function updateCartItem({
 
 // src/tools/remove-cart-item.ts
 import { z as z15 } from "zod";
-var schema17 = {
+var schema18 = {
   cartItemId: z15.string().min(1).describe("Cart item ID to remove (required)")
 };
-var metadata17 = {
+var metadata18 = {
   name: "remove-cart-item",
   description: "Remove an item from cart. Recalculates cart totals after removal.",
   annotations: {
@@ -2215,11 +2319,11 @@ async function removeCartItem({
 
 // src/tools/apply-discount.ts
 import { z as z16 } from "zod";
-var schema18 = {
+var schema19 = {
   cartId: z16.string().min(1).describe("Cart ID (required)"),
   discountCode: z16.string().describe("Discount code to apply (required)")
 };
-var metadata18 = {
+var metadata19 = {
   name: "apply-discount",
   description: "Apply a discount code to a cart. Validates the code, updates cart totals, and sets free shipping if applicable.",
   annotations: {
@@ -2244,10 +2348,10 @@ async function applyDiscount({
 
 // src/tools/remove-discount.ts
 import { z as z17 } from "zod";
-var schema19 = {
+var schema20 = {
   cartId: z17.string().min(1).describe("Cart ID (required)")
 };
-var metadata19 = {
+var metadata20 = {
   name: "remove-discount",
   description: "Remove the applied discount code from a cart and recalculate totals.",
   annotations: {
@@ -2271,10 +2375,10 @@ async function removeDiscount({
 
 // src/tools/clear-cart.ts
 import { z as z18 } from "zod";
-var schema20 = {
+var schema21 = {
   cartId: z18.string().min(1).describe("Cart ID (required)")
 };
-var metadata20 = {
+var metadata21 = {
   name: "clear-cart",
   description: "Remove all items from a cart, reset discount and amounts. Shipping fee is preserved.",
   annotations: {
@@ -2298,11 +2402,11 @@ async function clearCart({
 
 // src/tools/validate-discount.ts
 import { z as z19 } from "zod";
-var schema21 = {
+var schema22 = {
   code: z19.string().describe("Discount code to validate (required)"),
   orderAmount: z19.number().describe("Order amount for validation (required)")
 };
-var metadata21 = {
+var metadata22 = {
   name: "validate-discount",
   description: "Validate a discount code. Checks active status, date range, usage limits, minimum order amount, and calculates discount.",
   annotations: {
@@ -2330,12 +2434,12 @@ async function validateDiscount({
 
 // src/tools/calculate-shipping.ts
 import { z as z20 } from "zod";
-var schema22 = {
+var schema23 = {
   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)")
 };
-var metadata22 = {
+var metadata23 = {
   name: "calculate-shipping",
   description: "Calculate shipping fee based on order amount and postal code. Supports free shipping threshold and Jeju surcharge.",
   annotations: {
@@ -2365,7 +2469,7 @@ async function calculateShipping({
 
 // src/tools/stock-check.ts
 import { z as z21 } from "zod";
-var schema23 = {
+var schema24 = {
   items: z21.array(
     z21.object({
       variantId: z21.string().describe("Product variant ID"),
@@ -2375,7 +2479,7 @@ var schema23 = {
     "Array of items to check stock for (required, max 100). Each: { variantId, quantity }"
   )
 };
-var metadata23 = {
+var metadata24 = {
   name: "stock-check",
   description: "Batch check product option stock availability. Returns per-item availability and an allAvailable flag.",
   annotations: {
@@ -2399,11 +2503,11 @@ async function stockCheck({
 
 // src/tools/product-detail.ts
 import { z as z22 } from "zod";
-var schema24 = {
+var schema25 = {
   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)")
 };
-var metadata24 = {
+var metadata25 = {
   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 found:false with a reason if missing/unpublished/feature disabled. Permission/auth errors still throw.",
   annotations: {
@@ -2431,7 +2535,7 @@ async function productDetail({
 }
 
 // src/tools/product-upsert.ts
-var schema25 = {
+var schema26 = {
   productId: ProductUpsertObjectSchema.shape.productId.describe(
     "Existing product id for graph-only updates. Prefer this for an existing product on edit after loading GET /api/products/:id/composer-draft."
   ),
@@ -2448,7 +2552,7 @@ var schema25 = {
     "Full desired variant graph. On edit, omitted variants are deleted or deactivated according to server references. Prefer stable option-value IDs."
   )
 };
-var metadata25 = {
+var metadata26 = {
   name: "product-upsert",
   description: "Create a product or update an existing product graph. Existing products should load composer-draft first, send productId plus graphRevision, and include the full desired options/variants graph.",
   annotations: {
@@ -2489,8 +2593,8 @@ async function getCollectionSchema(collection) {
 }
 
 // src/tools/get-collection-schema.ts
-var schema26 = createCollectionSchemaToolInputSchema(SERVER_COLLECTIONS3).shape;
-var metadata26 = {
+var schema27 = createCollectionSchemaToolInputSchema(SERVER_COLLECTIONS3).shape;
+var metadata27 = {
   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: {
@@ -2541,8 +2645,8 @@ async function getTenantFeatureProgress(feature, includeEvidence = false) {
 }
 
 // src/tools/get-tenant-context.ts
-var schema27 = tenantContextToolInputSchema.shape;
-var metadata27 = {
+var schema28 = tenantContextToolInputSchema.shape;
+var metadata28 = {
   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: {
@@ -2619,8 +2723,8 @@ async function handler({
 }
 
 // src/tools/check-feature-progress.ts
-var schema28 = tenantFeatureProgressInputSchema.shape;
-var metadata28 = {
+var schema29 = tenantFeatureProgressInputSchema.shape;
+var metadata29 = {
   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: {
@@ -2666,12 +2770,12 @@ function invalidateFieldConfigCache() {
 }
 
 // src/tools/list-configurable-fields.ts
-var schema29 = {
+var schema30 = {
   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 metadata29 = {
+var metadata30 = {
   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: {
@@ -2703,7 +2807,7 @@ async function listConfigurableFields(params) {
 
 // src/tools/update-field-config.ts
 import { z as z24 } from "zod";
-var schema30 = {
+var schema31 = {
   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."
@@ -2712,7 +2816,7 @@ var schema30 = {
     "Hide the entire collection from Admin Panel (optional). When true, individual hiddenFields are irrelevant."
   )
 };
-var metadata30 = {
+var metadata31 = {
   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: {
@@ -3181,7 +3285,7 @@ function getRecipe(goal, runtime = "both") {
 }
 
 // src/tools/sdk-get-recipe.ts
-var schema31 = {
+var schema32 = {
   goal: z25.enum([
     "fetch-list",
     "fetch-by-id",
@@ -3198,7 +3302,7 @@ var schema31 = {
   collection: z25.string().optional().describe("Specific collection name if applicable"),
   includeExample: z25.boolean().default(true).describe("Whether to include a full code example")
 };
-var metadata31 = {
+var metadata32 = {
   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: {
@@ -3379,9 +3483,16 @@ var docIndex = [
       "order",
       "orderChanged",
       "collection.orderChanged",
-      "isOrderChangedWebhookEvent"
+      "isOrderChangedWebhookEvent",
+      "commerce.notification",
+      "createCommerceNotificationWebhookHandler",
+      "createCommerceEmailWebhookHandler",
+      "orderCanceled",
+      "resolveCancelRefund",
+      "cancel refund",
+      "external PG refund"
     ],
-    summary: "Tenant webhooks deliver signed server-to-server events via WEBHOOK_SECRET, including customer password reset and semantic order changes with collection.orderChanged / isOrderChangedWebhookEvent.",
+    summary: "Tenant webhooks deliver signed server-to-server events via WEBHOOK_SECRET, including customer password reset, semantic order changes, and commerce.notification workers with createCommerceNotificationWebhookHandler for orderCanceled refund handoff.",
     resourceUri: "docs://sdk/webhook"
   },
   // Order API
@@ -3393,8 +3504,8 @@ var docIndex = [
   },
   {
     title: "Order API \u2014 Fulfillment and Shipping",
-    keywords: ["fulfillment", "shipping", "tracking", "carrier", "trackingNumber", "createFulfillment", "updateFulfillment", "shipped", "delivered"],
-    summary: "client.commerce.orders.createFulfillment({ orderNumber, items, carrier?, trackingNumber? }) creates a shipment. updateFulfillment() advances fulfillment status.",
+    keywords: ["fulfillment", "shipping", "tracking", "carrier", "trackingNumber", "prepareFulfillmentOrder", "createFulfillment", "updateFulfillment", "shipped", "delivered"],
+    summary: "client.commerce.orders.prepareFulfillmentOrder({ orderNumber }) starts fulfillment work. createFulfillment({ orderNumber, ... }) creates a shipment with optional tracking. updateFulfillment() advances shipment status or updates tracking.",
     resourceUri: "docs://sdk/server-api"
   },
   {
@@ -3427,11 +3538,11 @@ function searchDocs(query, limit = 5) {
 }
 
 // src/tools/sdk-search-docs.ts
-var schema32 = {
+var schema33 = {
   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 metadata32 = {
+var metadata33 = {
   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: {
@@ -3467,7 +3578,7 @@ function handler4({
 
 // src/tools/sdk-get-auth-setup.ts
 import { z as z27 } from "zod";
-var schema33 = {
+var schema34 = {
   scenario: z27.enum([
     "browser-client",
     "server-client",
@@ -3477,7 +3588,7 @@ var schema33 = {
     "webhook-verification"
   ]).describe("Authentication scenario")
 };
-var metadata33 = {
+var metadata34 = {
   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: {
@@ -3641,12 +3752,12 @@ function handler5({
 // src/tools/sdk-get-collection-pattern.ts
 import { z as z28 } from "zod";
 import { COLLECTIONS, SERVER_COLLECTIONS as SERVER_COLLECTIONS4 } from "@01.software/sdk";
-var schema34 = {
+var schema35 = {
   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 metadata34 = {
+var metadata35 = {
   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: {
@@ -3843,13 +3954,13 @@ function handler6({
 
 // src/prompts/sdk-usage-guide.ts
 import { z as z29 } from "zod";
-var schema35 = {
+var schema36 = {
   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 metadata35 = {
+var metadata36 = {
   name: "sdk-usage-guide",
   title: "SDK Usage Guide",
   description: "Provides guidance on how to perform a specific task using the 01.software SDK",
@@ -4023,12 +4134,12 @@ const { allAvailable } = await client.commerce.product.stockCheck({
 // src/prompts/collection-query-help.ts
 import { z as z30 } from "zod";
 import { COLLECTIONS as COLLECTIONS2, SERVER_COLLECTIONS as SERVER_COLLECTIONS5 } from "@01.software/sdk";
-var schema36 = {
+var schema37 = {
   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 metadata36 = {
+var metadata37 = {
   name: "collection-query-help",
   title: "Collection Query Help",
   description: "Provides guidance on how to write queries for a specific collection",
@@ -4126,7 +4237,7 @@ ${operation === "find" ? `- Use \`where\` option for filtering (Payload query sy
 
 // src/prompts/order-flow-guide.ts
 import { z as z31 } from "zod";
-var schema37 = {
+var schema38 = {
   scenario: z31.enum([
     "simple-order",
     "cart-checkout",
@@ -4135,7 +4246,7 @@ var schema37 = {
     "fulfillment-tracking"
   ]).describe("Order flow scenario")
 };
-var metadata37 = {
+var metadata38 = {
   name: "order-flow-guide",
   title: "Order Flow Guide",
   description: "Provides step-by-step guidance for ecommerce order flows including creation, checkout, returns, and fulfillment.",
@@ -4155,10 +4266,16 @@ var SCENARIOS = {
    - 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
-   - Partial shipment \u2192 order becomes \`preparing\`
-   - All items shipped \u2192 order becomes \`shipped\`
+3. **Prepare Fulfillment Work** \u2192 \`prepare-fulfillment-order\` tool
+   - Provide orderNumber only
+   - Starts fulfillment-order work without carrier/tracking
+   - Order display status is derived as \`preparing\`
+
+4. **Create Shipment** \u2192 \`create-fulfillment\` tool
+   - Provide orderNumber
+   - Optional: carrier + trackingNumber can be supplied now or later
+   - Shipment status starts as \`shipped\`
+   - Shipment state drives the derived order display status
 
 ### Code Example (ServerClient)
 \`\`\`typescript
@@ -4189,7 +4306,12 @@ await client.commerce.orders.confirmPayment({
   confirmationSource: 'provider_api_confirm'
 })
 
-// 3. Ship items
+// 3. Start fulfillment work without tracking
+await client.commerce.orders.prepareFulfillmentOrder({
+  orderNumber: 'ORD-240101-001'
+})
+
+// 4. Ship items; tracking can be added now or later
 await client.commerce.orders.createFulfillment({
   orderNumber: 'ORD-240101-001',
   carrier: 'cj',
@@ -4275,11 +4397,12 @@ await client.commerce.orders.returnWithRefund({
    - **PG refund is not performed by Console** \u2014 storefront/BFF calls Toss/Portone; webhook sync is a follow-up
    - \`refundedAmount\` is not incremented on local cancel; new cancels return \`providerRefunded: false\`
    - \`refundPending: true\` signals storefront PG refund is still required; idempotent retries may return it from server metadata
+   - \`in_progress\` / \`on_hold\` preparation fulfillment orders are voided during cancel when no shipment exists
    - Legacy inline-PG-cancel rows may still return \`reconciliationRequired: true\` with \`providerRefunded: true\`
    - Duplicate local success returns \`alreadyCanceled: true\`
 
 ### V1 Rejections
-- Orders with non-failed fulfillments are rejected
+- Orders with active fulfillments (not \`failed\` / \`canceled\`) are rejected
 - \`shipped\`, \`delivered\`, \`confirmed\`, and return-axis orders are rejected
 - Active returns are rejected; use \`return-with-refund\` after delivery
 - Partial line-item cancellation is not supported in v1
@@ -4327,32 +4450,45 @@ Use one idempotency key per distinct PG refund attempt/result. For PG refund fai
   "fulfillment-tracking": `## Fulfillment & Tracking
 
 ### Creating Fulfillment
-1. **Create Fulfillment** \u2192 \`create-fulfillment\` tool
-   - Order must be \`paid\` or \`preparing\`
-   - With carrier + trackingNumber \u2192 fulfillment status = \`shipped\`
-   - Without \u2192 fulfillment status = \`pending\`
+1. **Prepare Fulfillment Work** \u2192 \`prepare-fulfillment-order\` tool
+   - Order must be paid and fulfillable
+   - Provide orderNumber only
+   - No carrier/tracking is required
+   - Fulfillment order status becomes \`in_progress\`
+
+2. **Create Shipment** \u2192 \`create-fulfillment\` tool
+   - Provide orderNumber
+   - Optional: carrier and trackingNumber can be supplied now or updated later
+   - Optional: fulfillmentOrderId and item quantities for partial shipments
+   - Shipment status starts as \`shipped\`
 
 ### Updating Fulfillment
-2. **Update** \u2192 \`update-fulfillment\` tool
-   - FSM: pending \u2192 packed \u2192 shipped \u2192 delivered (terminal)
-   - Or: pending/packed/shipped \u2192 failed (terminal)
-   - Carrier/trackingNumber changeable only in pending/packed status
+3. **Update Shipment** \u2192 \`update-fulfillment\` tool
+   - Shipment lifecycle: shipped \u2192 delivered
+   - Or: shipped \u2192 failed
+   - Carrier/trackingNumber can be added or corrected after shipment creation
 
 ### Auto Timestamps
 - \`shipped\` \u2192 sets \`shippedAt\`
 - \`delivered\` \u2192 sets \`deliveredAt\`
 
-### Order Auto-sync
-- All items shipped with carrier \u2192 order \`shipped\`
-- Partial shipment \u2192 order \`preparing\`
-- All non-failed fulfillments delivered \u2192 order \`delivered\`
+### Order Display Projection
+- \`preparing\` is derived from active fulfillment-order work
+- \`shipped\` is derived from active shipment rows
+- \`delivered\` is derived only after all active shipments are delivered
+- \`confirmed\` is set through \`update-order\` after delivery
 
 ### Carriers
 cj, hanjin, lotte, epost, logen, other
 
 ### Code Example
 \`\`\`typescript
-// Create fulfillment with tracking
+// Prepare fulfillment work first
+await client.commerce.orders.prepareFulfillmentOrder({
+  orderNumber: 'ORD-240101-001'
+})
+
+// Create shipment; carrier/tracking are optional
 await client.commerce.orders.createFulfillment({
   orderNumber: 'ORD-240101-001',
   carrier: 'cj',
@@ -4360,6 +4496,13 @@ await client.commerce.orders.createFulfillment({
   items: [{ orderItem: 'oi-id', quantity: 2 }]
 })
 
+// Add or update tracking later
+await client.commerce.orders.updateFulfillment({
+  fulfillmentId: 'ful-id',
+  carrier: 'cj',
+  trackingNumber: '1234567890'
+})
+
 // Mark as delivered
 await client.commerce.orders.updateFulfillment({
   fulfillmentId: 'ful-id',
@@ -4377,7 +4520,7 @@ ${SCENARIOS[scenario] || "Unknown scenario."}
 ## Related MCP Tools
 - \`create-order\`, \`get-order\`, \`update-order\`
 - \`checkout\`
-- \`create-fulfillment\`, \`update-fulfillment\`
+- \`prepare-fulfillment-order\`, \`create-fulfillment\`, \`update-fulfillment\`
 - \`create-return\`, \`update-return\`, \`return-with-refund\`
 - \`confirm-payment\`, \`cancel-order\`, \`update-transaction\`
 - \`validate-discount\`, \`calculate-shipping\``;
@@ -4385,7 +4528,7 @@ ${SCENARIOS[scenario] || "Unknown scenario."}
 
 // src/prompts/feature-setup-guide.ts
 import { z as z32 } from "zod";
-var schema38 = {
+var schema39 = {
   feature: z32.enum([
     "ecommerce",
     "customers",
@@ -4401,7 +4544,7 @@ var schema38 = {
     "community"
   ]).describe("Feature to get setup guide for")
 };
-var metadata38 = {
+var metadata39 = {
   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.",
@@ -4609,7 +4752,7 @@ ${FEATURES[feature] || "Unknown feature."}
 }
 
 // src/resources/(config)/app.ts
-var metadata39 = {
+var metadata40 = {
   name: "app-config",
   title: "Application Config",
   description: "01.software SDK and MCP server configuration information"
@@ -4653,7 +4796,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 (33)
+## Local CLI Stdio Surface (35)
 
 For trusted local server-key workflows, start the stdio server:
 
@@ -4675,7 +4818,7 @@ Rate limits depend on your tenant plan:
 
 // src/resources/(collections)/schema.ts
 import { COLLECTIONS as COLLECTIONS3 } from "@01.software/sdk";
-var metadata40 = {
+var metadata41 = {
   name: "collections-schema",
   title: "Collection Schema Info",
   description: "Available collections and their schema information"
@@ -4812,7 +4955,7 @@ Total available collections: ${COLLECTIONS3.length}`;
 }
 
 // src/resources/(docs)/getting-started.ts
-var metadata41 = {
+var metadata42 = {
   name: "docs-getting-started",
   title: "Getting Started",
   description: "01.software SDK getting started guide"
@@ -4873,7 +5016,7 @@ const result = await client.collections.from('products').find({
 }
 
 // src/resources/(docs)/guides.ts
-var metadata42 = {
+var metadata43 = {
   name: "docs-guides",
   title: "Guides",
   description: "01.software SDK usage guides"
@@ -5086,7 +5229,7 @@ For more implementation guidance, see the [SDK Guide](/developers/sdk).`;
 }
 
 // src/resources/(docs)/api.ts
-var metadata43 = {
+var metadata44 = {
   name: "docs-api",
   title: "API Reference",
   description: "01.software SDK API reference documentation"
@@ -5369,7 +5512,7 @@ For more details, see the [API documentation](/developers/api).`;
 }
 
 // src/resources/(docs)/query-builder.ts
-var metadata44 = {
+var metadata45 = {
   name: "docs-query-builder",
   title: "Query Builder",
   description: "01.software SDK Query Builder API reference (client.collections.from)"
@@ -5522,6 +5665,33 @@ if (page1.hasNextPage) {
 }
 \`\`\`
 
+## Join fields (\`joins\`)
+
+Payload \`type: 'join'\` reverse-relations (e.g. \`products.variants\`, \`products.options\`) are **not** controlled by \`depth\`. When \`joins\` is omitted, each join field defaults to **limit 10** docs.
+
+Storefront PLPs that query \`products\` with only \`depth\` and group client-side can silently drop color swatches when a product has more than 10 option values. Prefer \`commerce.product.listingGroupsCatalog()\` + \`buildProductListingCard()\`, or spread \`PRODUCT_PLP_FIND_OPTIONS\` from \`@01.software/sdk\` into raw \`find()\` calls.
+
+\`\`\`typescript
+import { PRODUCT_PLP_FIND_OPTIONS } from '@01.software/sdk'
+
+await client.collections.from('products').find({
+  ...PRODUCT_PLP_FIND_OPTIONS,
+  where: { status: { equals: 'published' } },
+  limit: 24,
+})
+
+// Or configure joins explicitly (tune limits to your catalog size):
+await client.collections.from('products').find({
+  joins: {
+    variants: { limit: 50, sort: '_order' },
+    options: { limit: 30, sort: '_order' },
+  },
+})
+
+// Disable all join-field population for lightweight lists:
+await client.collections.from('products').find({ joins: false })
+\`\`\`
+
 ## Sorting
 
 \`\`\`typescript
@@ -5563,7 +5733,7 @@ console.log(result.hasNextPage) // true
 }
 
 // src/resources/(docs)/react-query.ts
-var metadata45 = {
+var metadata46 = {
   name: "docs-react-query",
   title: "React Query Hooks",
   description: "01.software SDK React Query hooks reference (@01.software/sdk/query)"
@@ -5795,7 +5965,7 @@ export function ProductList() {
 }
 
 // src/resources/(docs)/server-api.ts
-var metadata46 = {
+var metadata47 = {
   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"
@@ -5871,25 +6041,34 @@ const order = docs[0] ?? null
 \`\`\`
 
 ### updateOrder()
-Update order status.
+Confirm an order after delivery. Financial and shipment/display statuses are server-derived.
 
 \`\`\`typescript
 const order = await client.commerce.orders.update({
   orderNumber: 'ORD-20240101-0001',
-  status: 'paid',  // pending | paid | failed | canceled | preparing | shipped | delivered | confirmed
+  status: 'confirmed',
 })
 \`\`\`
 
 ## Fulfillment API
 
+### prepareFulfillmentOrder()
+Start fulfillment-order work without carrier or tracking.
+
+\`\`\`typescript
+const result = await client.commerce.orders.prepareFulfillmentOrder({
+  orderNumber: 'ORD-20240101-0001',
+})
+\`\`\`
+
 ### createFulfillment()
-Create a shipment record for order items.
+Create a shipment record for order items. Carrier and trackingNumber are optional and can be added later.
 
 \`\`\`typescript
 const fulfillment = await client.commerce.orders.createFulfillment({
   orderNumber: 'ORD-20240101-0001',
-  carrier?: 'cj',  // cj | hanjin | lotte | epost | logen | other
-  trackingNumber?: '123456789012',
+  carrier: 'cj',  // optional: cj | hanjin | lotte | epost | logen | other
+  trackingNumber: '123456789012', // optional
   items: [
     { orderItem: 'order-item-id', quantity: 2 }
   ],
@@ -5897,14 +6076,13 @@ const fulfillment = await client.commerce.orders.createFulfillment({
 \`\`\`
 
 ### updateFulfillment()
-Update fulfillment status and optionally carrier/tracking.
+Update fulfillment status or tracking information.
 
 \`\`\`typescript
 const fulfillment = await client.commerce.orders.updateFulfillment({
   fulfillmentId: 'fulfillment-id',
-  status: 'delivered',  // packed | shipped | delivered | failed
-  carrier?: 'cj',
-  trackingNumber?: '123456789012',
+  carrier: 'cj',
+  trackingNumber: '123456789012',
 })
 \`\`\`
 
@@ -5919,9 +6097,12 @@ const ret = await client.commerce.orders.createReturn({
   reason?: 'defective',  // change_of_mind | defective | wrong_delivery | damaged | other
   reasonDetail?: 'Screen cracked on arrival',
   returnItems: [
-    { orderItem: 'order-item-id', quantity: 1 }
+    { orderItem: 'order-item-id', quantity: 1, restockingFee?: 500 }
   ],
   refundAmount: 29900,
+  returnShippingFee?: 1500,
+  initialShippingRefundAmount?: 3000,
+  initialShippingRefundOverrideNote?: 'Policy override note',
 })
 \`\`\`
 
@@ -5948,6 +6129,8 @@ const result = await client.commerce.orders.returnWithRefund({
   ],
   refundAmount: 29900,
   returnShippingFee?: 1500,
+  initialShippingRefundAmount?: 3000,
+  initialShippingRefundOverrideNote?: 'Policy override note',
   pgPaymentId: 'provider-payment-id',  // required
   paymentKey: 'provider-payment-key',  // required for provider refund
   refundReceiptUrl?: 'https://...',
@@ -6079,7 +6262,7 @@ const result = await client.commerce.shipping.calculate({
 }
 
 // src/resources/(docs)/customer-auth.ts
-var metadata47 = {
+var metadata48 = {
   name: "docs-customer-auth",
   title: "Customer Auth API",
   description: "01.software SDK Customer Auth API reference (client.customer)"
@@ -6257,7 +6440,7 @@ async function loadProfile() {
 }
 
 // src/resources/(docs)/browser-vs-server.ts
-var metadata48 = {
+var metadata49 = {
   name: "docs-browser-vs-server",
   title: "Client vs ServerClient",
   description: "When to use Client (createClient) vs ServerClient (createServerClient) in the 01.software SDK"
@@ -6423,7 +6606,7 @@ export function ProductList() {
 }
 
 // src/resources/(docs)/file-upload.ts
-var metadata49 = {
+var metadata50 = {
   name: "docs-file-upload",
   title: "File Upload",
   description: "01.software SDK file upload patterns using the images collection"
@@ -6574,7 +6757,7 @@ The platform stores files in Cloudflare R2 and serves via CDN (\`cdn.01.software
 }
 
 // src/resources/(docs)/webhook.ts
-var metadata50 = {
+var metadata51 = {
   name: "docs-webhook",
   title: "Webhooks",
   description: "01.software SDK webhook verification and event handling"
@@ -6643,8 +6826,8 @@ export async function POST(request: Request) {
 
 \`\`\`typescript
 import {
+  createCommerceNotificationWebhookHandler,
   handleWebhook,
-  isCommerceNotificationWebhookEvent,
 } from '@01.software/sdk/webhook'
 
 function getWebhookSecret(): string {
@@ -6653,26 +6836,25 @@ function getWebhookSecret(): string {
   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)
-      }
+const commerceNotificationHandler = createCommerceNotificationWebhookHandler({
+  async orderPaid({ event, idempotencyKey }) {
+    await processOnce(idempotencyKey, async () => {
+      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)
-      }
+  async fulfillmentShipped({ event, idempotencyKey }) {
+    await processOnce(idempotencyKey, async () => {
+      const fulfillmentId =
+        event.notification.fulfillmentId ?? event.data.fulfillmentId
+      if (fulfillmentId) await updateFulfillmentWorkflow(fulfillmentId)
     })
+  },
+})
 
-    if (!processed) return
-  }, {
+export async function POST(request: Request) {
+  return handleWebhook(request, commerceNotificationHandler, {
     secret: getWebhookSecret(),
   })
 }
@@ -6680,11 +6862,11 @@ export async function POST(request: Request) {
 
 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
+## Commerce Notification 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.
+For new tenant-owned commerce side effects, use \`commerce.notification\` as the trigger and build a signed worker with \`createCommerceNotificationWebhookHandler()\`. Existing email workers may keep \`createCommerceEmailWebhookHandler()\` as a compatibility alias, but the general helper name should be used in new guidance. 01.software owns event timing, delivery retries, signing, and idempotency signals; the tenant worker owns email, external PG calls, extra order/customer fetches via \`createServerClient\`, and final side effects.
 
-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.
+Use \`getCommerceNotificationIdempotencyKey(event)\` or the \`idempotencyKey\` passed by \`createCommerceNotificationWebhookHandler()\`, then guard side effects with durable \`processOnce(idempotencyKey, ...)\` storage. \`notification.intentId + notification.dedupeKey\` is semantic idempotency. \`deliveryId\` is delivery-attempt observability only.
 
 ## Webhook Payload Structure
 
@@ -6737,9 +6919,11 @@ Canonical example (public operational identifiers only; no PII, payment/provider
 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.
 
+For CMS/Admin cancellation side effects, route \`commerce.notification/orderCanceled\` workers per the public webhooks guide (**orderCanceled external PG refund handoff**). Use \`orders/update\` only for cache refreshes and local projections. Detailed trusted refetch, PG refund classification, and refund reporting contracts live in that guide\u2014not in this generic webhook resource.
+
 V1 source subscription semantics:
 
-- \`orderPaid\` and \`orderDelivered\` are delivered through \`orders\`-scoped endpoints.
+- \`orderPaid\`, \`orderCanceled\`, 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.
@@ -6838,7 +7022,7 @@ Configure webhook URLs in the 01.software console under Tenant Settings > Webhoo
 }
 
 // src/resources/(docs)/product-detail.ts
-var metadata51 = {
+var metadata52 = {
   name: "docs-product-detail",
   title: "Product Detail Helper",
   description: "01.software SDK commerce.product.detail helper guide"
@@ -6948,7 +7132,7 @@ function runtimeAnnotationsFor(meta) {
     openWorldHint: policy.annotationPolicy.openWorld
   };
 }
-function registerTool(server, schema39, meta, handler21) {
+function registerTool(server, schema40, meta, handler21) {
   let registered = REGISTERED_TOOLS_BY_SERVER.get(server);
   if (!registered) {
     registered = /* @__PURE__ */ new Set();
@@ -6959,7 +7143,7 @@ function registerTool(server, schema39, meta, handler21) {
     meta.name,
     {
       description: meta.description,
-      inputSchema: schema39,
+      inputSchema: schema40,
       annotations: runtimeAnnotationsFor(meta)
     },
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -7009,13 +7193,13 @@ function registerTool(server, schema39, meta, handler21) {
     }
   );
 }
-function registerPrompt(server, schema39, meta, handler21) {
+function registerPrompt(server, schema40, meta, handler21) {
   server.registerPrompt(
     meta.name,
     {
       title: meta.title,
       description: meta.description,
-      argsSchema: schema39
+      argsSchema: schema40
     },
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     (params) => ({
@@ -7075,245 +7259,251 @@ function createServer(options = {}) {
       server,
       schema8,
       metadata8,
-      updateFulfillment
+      prepareFulfillmentOrder
     );
     registerTool(
       server,
       schema9,
       metadata9,
-      updateTransaction
+      updateFulfillment
     );
     registerTool(
       server,
       schema10,
       metadata10,
-      confirmPayment
+      updateTransaction
     );
-    registerTool(server, schema11, metadata11, cancelOrder);
     registerTool(
       server,
-      schema12,
-      metadata12,
-      createReturn
+      schema11,
+      metadata11,
+      confirmPayment
     );
+    registerTool(server, schema12, metadata12, cancelOrder);
     registerTool(
       server,
       schema13,
       metadata13,
-      updateReturn
+      createReturn
     );
     registerTool(
       server,
       schema14,
       metadata14,
-      returnWithRefund
+      updateReturn
     );
-    registerTool(server, schema15, metadata15, addCartItem);
     registerTool(
       server,
-      schema16,
-      metadata16,
-      updateCartItem
+      schema15,
+      metadata15,
+      returnWithRefund
     );
+    registerTool(server, schema16, metadata16, addCartItem);
     registerTool(
       server,
       schema17,
       metadata17,
-      removeCartItem
+      updateCartItem
     );
     registerTool(
       server,
       schema18,
       metadata18,
-      applyDiscount
+      removeCartItem
     );
     registerTool(
       server,
       schema19,
       metadata19,
-      removeDiscount
+      applyDiscount
     );
-    registerTool(server, schema20, metadata20, clearCart);
     registerTool(
       server,
-      schema21,
-      metadata21,
-      validateDiscount
+      schema20,
+      metadata20,
+      removeDiscount
     );
+    registerTool(server, schema21, metadata21, clearCart);
     registerTool(
       server,
       schema22,
       metadata22,
-      calculateShipping
+      validateDiscount
     );
-    registerTool(server, schema23, metadata23, stockCheck);
     registerTool(
       server,
-      schema24,
-      metadata24,
-      productDetail
+      schema23,
+      metadata23,
+      calculateShipping
     );
+    registerTool(server, schema24, metadata24, stockCheck);
     registerTool(
       server,
       schema25,
       metadata25,
+      productDetail
+    );
+    registerTool(
+      server,
+      schema26,
+      metadata26,
       productUpsert
     );
   }
-  registerTool(
-    server,
-    schema26,
-    metadata26,
-    getCollectionSchemaTool
-  );
   registerTool(
     server,
     schema27,
     metadata27,
-    handler
+    getCollectionSchemaTool
   );
   registerTool(
     server,
     schema28,
     metadata28,
-    handler2
+    handler
   );
   registerTool(
     server,
     schema29,
     metadata29,
-    listConfigurableFields
+    handler2
   );
   registerTool(
     server,
     schema30,
     metadata30,
-    updateFieldConfig
+    listConfigurableFields
   );
   registerTool(
     server,
     schema31,
     metadata31,
-    handler3
+    updateFieldConfig
   );
   registerTool(
     server,
     schema32,
     metadata32,
-    handler4
+    handler3
   );
   registerTool(
     server,
     schema33,
     metadata33,
-    handler5
+    handler4
   );
   registerTool(
     server,
     schema34,
     metadata34,
-    handler6
+    handler5
   );
-  registerPrompt(
+  registerTool(
     server,
     schema35,
     metadata35,
-    sdkUsageGuide
+    handler6
   );
   registerPrompt(
     server,
     schema36,
     metadata36,
-    collectionQueryHelp
+    sdkUsageGuide
   );
   registerPrompt(
     server,
     schema37,
     metadata37,
-    orderFlowGuide
+    collectionQueryHelp
   );
   registerPrompt(
     server,
     schema38,
     metadata38,
+    orderFlowGuide
+  );
+  registerPrompt(
+    server,
+    schema39,
+    metadata39,
     featureSetupGuide
   );
   registerStaticResource(
     server,
     mcpResourceUri("app-config"),
-    metadata39,
+    metadata40,
     handler7
   );
   registerStaticResource(
     server,
     mcpResourceUri("collections-schema"),
-    metadata40,
+    metadata41,
     handler8
   );
   registerStaticResource(
     server,
     mcpResourceUri("docs-getting-started"),
-    metadata41,
+    metadata42,
     handler9
   );
   registerStaticResource(
     server,
     mcpResourceUri("docs-guides"),
-    metadata42,
+    metadata43,
     handler10
   );
   registerStaticResource(
     server,
     mcpResourceUri("docs-api"),
-    metadata43,
+    metadata44,
     handler11
   );
   registerStaticResource(
     server,
     mcpResourceUri("docs-query-builder"),
-    metadata44,
+    metadata45,
     handler12
   );
   registerStaticResource(
     server,
     mcpResourceUri("docs-react-query"),
-    metadata45,
+    metadata46,
     handler13
   );
   registerStaticResource(
     server,
     mcpResourceUri("docs-server-api"),
-    metadata46,
+    metadata47,
     handler14
   );
   registerStaticResource(
     server,
     mcpResourceUri("docs-customer-auth"),
-    metadata47,
+    metadata48,
     handler15
   );
   registerStaticResource(
     server,
     mcpResourceUri("docs-browser-vs-server"),
-    metadata48,
+    metadata49,
     handler16
   );
   registerStaticResource(
     server,
     mcpResourceUri("docs-file-upload"),
-    metadata49,
+    metadata50,
     handler17
   );
   registerStaticResource(
     server,
     mcpResourceUri("docs-webhook"),
-    metadata50,
+    metadata51,
     handler18
   );
   registerStaticResource(
     server,
     mcpResourceUri("docs-product-detail"),
-    metadata51,
+    metadata52,
     handler19
   );
   return server;