@01.software/cli 0.10.6 → 0.11.1

package/dist/mcp/vercel.js

@@ -312,106 +312,338 @@ var collectionSchemaResponseSchema = z.object({
 }).strict();
 
 // ../../packages/contracts/src/ecommerce/index.ts
+import { z as z3 } from "zod";
+
+// ../../packages/contracts/src/ecommerce/product-upsert.ts
 import { z as z2 } from "zod";
-var transactionStatusSchema = z2.enum([
+var IdSchema = z2.union([z2.string(), z2.number()]).transform(String);
+var RemovedLegacyMediaFieldSchema = z2.unknown().optional();
+var productFieldShape = {
+  id: IdSchema.optional(),
+  title: z2.string().min(1).optional(),
+  subtitle: z2.string().optional().nullable(),
+  description: z2.string().optional().nullable(),
+  status: z2.string().optional(),
+  slug: z2.string().optional(),
+  primaryMediaItemId: IdSchema.optional().nullable(),
+  thumbnail: IdSchema.optional().nullable(),
+  images: z2.array(IdSchema).optional(),
+  mediaSets: RemovedLegacyMediaFieldSchema,
+  vendor: z2.string().optional().nullable(),
+  productType: z2.string().optional().nullable(),
+  brand: IdSchema.optional().nullable(),
+  shippingPolicy: IdSchema.optional().nullable(),
+  weight: z2.number().int().min(0).optional().nullable(),
+  minOrderQuantity: z2.number().int().min(1).optional().nullable(),
+  maxOrderQuantity: z2.number().int().min(1).optional().nullable(),
+  listingPrimaryOption: IdSchema.optional().nullable(),
+  isFeatured: z2.boolean().optional(),
+  publishedAt: z2.string().optional().nullable(),
+  categories: z2.array(IdSchema).optional(),
+  tags: z2.array(IdSchema).optional(),
+  metadata: z2.unknown().optional()
+};
+var PRODUCT_UPSERT_PRODUCT_FIELDS = Object.keys(
+  productFieldShape
+);
+var ProductFieldsSchema = z2.object(productFieldShape).passthrough();
+var OptionValueInputSchema = z2.object({
+  id: IdSchema.optional(),
+  value: z2.string().min(1, "Option value `value` is required"),
+  slug: z2.string().optional(),
+  swatch: z2.object({
+    type: z2.enum(["color", "media"]).optional().nullable(),
+    color: z2.string().optional().nullable(),
+    mediaItemId: IdSchema.optional().nullable()
+  }).optional().nullable(),
+  thumbnail: RemovedLegacyMediaFieldSchema,
+  images: RemovedLegacyMediaFieldSchema,
+  metadata: z2.unknown().optional()
+}).passthrough().superRefine((value, ctx) => {
+  if (Object.prototype.hasOwnProperty.call(value, "swatchColor")) {
+    ctx.addIssue({
+      code: "custom",
+      message: "Option value field `swatchColor` was removed. Use nested `swatch.color` instead.",
+      path: ["swatchColor"]
+    });
+  }
+});
+var OptionInputSchema = z2.object({
+  id: IdSchema.optional(),
+  title: z2.string().min(1, "Option `title` is required"),
+  slug: z2.string().optional(),
+  values: z2.array(OptionValueInputSchema).min(1, "Each option must have at least one value")
+});
+var VariantOptionValueObjectSchema = z2.object({
+  valueSlug: z2.string().optional(),
+  valueId: IdSchema.optional(),
+  value: z2.string().optional()
+}).refine((data) => Boolean(data.valueSlug ?? data.valueId ?? data.value), {
+  message: "Variant option value object requires valueSlug, valueId, or value"
+});
+var VariantInputSchema = z2.object({
+  id: IdSchema.optional(),
+  optionValues: z2.union([
+    z2.record(
+      z2.string(),
+      z2.union([z2.string(), VariantOptionValueObjectSchema])
+    ),
+    z2.array(IdSchema)
+  ]).optional(),
+  sku: z2.string().optional().nullable(),
+  title: z2.string().optional().nullable(),
+  price: z2.number().min(0),
+  compareAtPrice: z2.number().min(0).optional().nullable(),
+  stock: z2.number().int().min(0).optional(),
+  isUnlimited: z2.boolean().optional(),
+  weight: z2.number().int().min(0).optional().nullable(),
+  requiresShipping: z2.boolean().optional(),
+  barcode: z2.string().optional().nullable(),
+  externalId: z2.string().optional().nullable(),
+  isActive: z2.boolean().optional(),
+  images: z2.array(IdSchema).optional(),
+  thumbnail: RemovedLegacyMediaFieldSchema,
+  featuredMediaItemId: RemovedLegacyMediaFieldSchema,
+  metadata: z2.unknown().optional()
+});
+var ProductUpsertObjectSchema = z2.object({
+  /** Required on graph edit when the server graph is non-empty (`productId` set); optional for first seed on an empty graph. */
+  graphRevision: z2.string().optional(),
+  productId: IdSchema.optional(),
+  product: ProductFieldsSchema.optional(),
+  options: z2.array(OptionInputSchema).max(10).optional().default([]),
+  variants: z2.array(VariantInputSchema).max(500).optional().default([])
+});
+var ProductUpsertSchema = ProductUpsertObjectSchema.superRefine(
+  (data, ctx) => {
+    const nestedProductId = data.product?.id;
+    if (data.productId != null && nestedProductId != null && String(data.productId) !== String(nestedProductId)) {
+      ctx.addIssue({
+        code: "custom",
+        message: "productId must match product.id when both are set on graph upsert.",
+        path: ["productId"]
+      });
+    }
+    const productId = data.productId ?? nestedProductId;
+    const isEdit = productId != null;
+    if (!isEdit && data.productId != null) {
+      ctx.addIssue({
+        code: "custom",
+        message: "productId is not allowed when creating a product.",
+        path: ["productId"]
+      });
+    }
+    if (!isEdit && !data.product?.title) {
+      ctx.addIssue({
+        code: "custom",
+        message: "Product `title` is required when creating a new product.",
+        path: ["product", "title"]
+      });
+    }
+    if (isEdit && data.product) {
+      for (const key of Object.keys(data.product)) {
+        if (key !== "id") {
+          ctx.addIssue({
+            code: "custom",
+            message: "Existing product graph upsert accepts only product identity. Save document fields through Payload.",
+            path: ["product", key]
+          });
+        }
+      }
+    }
+  }
+);
+
+// ../../packages/contracts/src/ecommerce/index.ts
+var transactionStatusSchema = z3.enum([
   "pending",
   "paid",
   "failed",
   "canceled"
 ]);
-var entityIdSchema = z2.union([z2.string(), z2.number()]).transform(String);
-var createOrderItemSchema = z2.object({
+var orderStatusSchema = z3.enum([
+  "pending",
+  "paid",
+  "failed",
+  "canceled",
+  "refunded",
+  "preparing",
+  "shipped",
+  "delivered",
+  "confirmed",
+  "return_requested",
+  "return_processing",
+  "returned"
+]);
+var entityIdSchema = z3.union([z3.string(), z3.number()]).transform(String);
+var createOrderItemSchema = z3.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()
+  quantity: z3.number().int().positive("quantity must be a positive integer"),
+  unitPrice: z3.number().optional(),
+  totalPrice: z3.number().optional()
 });
-var createOrderSchema = z2.object({
-  pgPaymentId: z2.string().min(1).optional(),
-  orderNumber: z2.string().min(1, "orderNumber is required"),
+var createOrderSchema = z3.object({
+  pgPaymentId: z3.string().min(1).optional(),
+  orderNumber: z3.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()
+  customerSnapshot: z3.object({
+    name: z3.string().optional(),
+    email: z3.string().email("Invalid email format"),
+    phone: z3.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()
+  shippingAddress: z3.object({
+    postalCode: z3.string().optional(),
+    address: z3.string().optional(),
+    detailAddress: z3.string().optional(),
+    deliveryMessage: z3.string().optional(),
+    recipientName: z3.string().optional(),
+    phone: z3.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()
+  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()
 });
 var CreateOrderSchema = createOrderSchema;
-var updateTransactionSchema = z2.object({
-  pgPaymentId: z2.string().min(1, "pgPaymentId is required").describe("PG payment ID (required)"),
+var updateTransactionSchema = z3.object({
+  pgPaymentId: z3.string().min(1, "pgPaymentId is required").describe("PG payment ID (required)"),
   status: transactionStatusSchema.describe(
     "New transaction status (required)"
   ),
-  paymentMethod: z2.string().optional().describe("Payment method (optional)"),
-  receiptUrl: z2.string().optional().describe("Receipt URL (optional)"),
-  paymentKey: z2.string().min(1).optional().describe("Provider payment key for verified paid confirmation"),
-  amount: z2.number().int().positive().optional().describe("Provider-confirmed amount for verified paid confirmation")
+  paymentMethod: z3.string().optional().describe("Payment method (optional)"),
+  receiptUrl: z3.string().optional().describe("Receipt URL (optional)"),
+  paymentKey: z3.string().min(1).optional().describe("Provider payment key for verified paid confirmation"),
+  amount: z3.number().int().positive().optional().describe("Provider-confirmed amount for verified paid confirmation")
 }).strict();
 var UpdateTransactionSchema = updateTransactionSchema;
-var providerSlugSchema = z2.string().trim().regex(/^[a-z0-9][a-z0-9_-]{0,63}$/, "pgProvider must be lowercase slug");
-var confirmPaymentSchema = z2.object({
-  orderNumber: z2.string().min(1).optional(),
-  pgPaymentId: z2.string().min(1, "pgPaymentId is required").describe("Provider payment identifier stored on the transaction"),
+var providerSlugSchema = z3.string().trim().regex(/^[a-z0-9][a-z0-9_-]{0,63}$/, "pgProvider must be lowercase slug");
+var confirmPaymentSchema = z3.object({
+  orderNumber: z3.string().min(1).optional(),
+  pgPaymentId: z3.string().min(1, "pgPaymentId is required").describe("Provider payment identifier stored on the transaction"),
   pgProvider: providerSlugSchema.describe(
     "Payment provider slug, e.g. toss, portone, stripe"
   ),
-  pgOrderId: z2.string().min(1).optional(),
-  amount: z2.number().int().nonnegative("amount must be non-negative").describe("Provider-confirmed amount in minor units"),
-  currency: z2.string().min(1).optional(),
-  paymentMethod: z2.string().optional(),
-  receiptUrl: z2.string().url().optional(),
-  approvedAt: z2.string().optional(),
-  providerStatus: z2.string().optional(),
-  providerEventId: z2.string().min(1).optional(),
-  confirmationSource: z2.enum([
+  pgOrderId: z3.string().min(1).optional(),
+  amount: z3.number().int().nonnegative("amount must be non-negative").describe("Provider-confirmed amount in minor units"),
+  currency: z3.string().min(1).optional(),
+  paymentMethod: z3.string().optional(),
+  receiptUrl: z3.string().url().optional(),
+  approvedAt: z3.string().optional(),
+  providerStatus: z3.string().optional(),
+  providerEventId: z3.string().min(1).optional(),
+  confirmationSource: z3.enum([
     "provider_webhook",
     "provider_lookup",
     "provider_api_confirm",
     "manual_server"
   ]).optional(),
-  metadata: z2.record(z2.string(), z2.unknown()).optional()
+  metadata: z3.record(z3.string(), z3.unknown()).optional()
 }).strict();
 var ConfirmPaymentSchema = confirmPaymentSchema;
-var returnReasonSchema = z2.enum([
+var returnReasonSchema = z3.enum([
   "change_of_mind",
   "defective",
   "wrong_delivery",
   "damaged",
   "other"
 ]);
-var restockActionSchema = z2.enum(["return_to_stock", "discard"]);
-var returnWithRefundItemSchema = z2.object({
-  orderItem: z2.union([z2.string(), z2.number()]).transform(String),
-  quantity: z2.number().int().positive("quantity must be a positive integer"),
+var restockActionSchema = z3.enum(["return_to_stock", "discard"]);
+var returnWithRefundItemSchema = z3.object({
+  orderItem: z3.union([z3.string(), z3.number()]).transform(String),
+  quantity: z3.number().int().positive("quantity must be a positive integer"),
   restockAction: restockActionSchema.default("return_to_stock"),
-  restockingFee: z2.number().min(0, "restockingFee must be non-negative").optional().describe("Restocking fee charged for this line (ADR 0005 \xA7Gap 1)")
+  restockingFee: z3.number().min(0, "restockingFee must be non-negative").optional().describe("Restocking fee charged for this line (ADR 0005 \xA7Gap 1)")
 }).strict();
-var returnWithRefundSchema = z2.object({
-  orderNumber: z2.string().min(1, "orderNumber is required").describe("Order number (required)"),
+var returnWithRefundSchema = z3.object({
+  orderNumber: z3.string().min(1, "orderNumber is required").describe("Order number (required)"),
   reason: returnReasonSchema.optional().describe("Return reason (optional)"),
-  reasonDetail: z2.string().optional().describe("Detailed reason text (optional)"),
-  returnItems: z2.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: z2.number().min(0, "refundAmount must be non-negative").describe("Refund amount (required, min 0)"),
-  returnShippingFee: z2.number().min(0, "returnShippingFee must be non-negative").optional().describe("Return shipping fee charged to the customer (ADR 0005 \xA7Gap 1)"),
-  pgPaymentId: z2.string().min(1, "pgPaymentId is required").describe("PG payment ID for refund (required)"),
-  paymentKey: z2.string().min(1).optional().describe("Provider payment key for verified refund"),
-  refundReceiptUrl: z2.string().optional().describe("Refund receipt URL (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("Refund amount (required, min 0)"),
+  returnShippingFee: z3.number().min(0, "returnShippingFee must be non-negative").optional().describe(
+    "Return shipping fee charged to the customer (ADR 0005 \xA7Gap 1)"
+  ),
+  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 ReturnWithRefundSchema = returnWithRefundSchema;
+var cancelReasonCodeSchema = z3.enum([
+  "customer",
+  "inventory",
+  "fraud",
+  "declined",
+  "staff",
+  "other"
+]);
+var idempotencyKeySchema = z3.string().trim().min(1, "idempotencyKey is required").max(255, "idempotencyKey must be 255 characters or fewer").regex(
+  /^[\x21-\x7E]+$/,
+  "idempotencyKey must contain only printable header-safe characters"
+);
+var cancelOrderSchema = z3.object({
+  orderNumber: z3.string().min(1, "orderNumber is required").describe("Order number to cancel"),
+  reasonCode: cancelReasonCodeSchema.default("other").describe("Operator-selected cancel reason code"),
+  reasonDetail: z3.string().trim().max(2e3, "reasonDetail must be 2000 characters or fewer").optional().describe("Internal cancellation detail stored on the order")
+}).strict();
+var CancelOrderSchema = cancelOrderSchema;
+var cancelOrderResponseBaseSchema = {
+  orderId: z3.string().min(1)
+};
+var unpaidCancelResponseFields = {
+  refundedAmount: z3.literal(0),
+  providerRefunded: z3.literal(false)
+};
+var alreadyCanceledResponseFields = {
+  refundedAmount: z3.number().int().nonnegative(),
+  providerRefunded: z3.literal(false)
+};
+var providerRefundResponseFields = {
+  transactionId: z3.string().min(1),
+  refundedAmount: z3.number().int().positive(),
+  refundSeq: z3.number().int().positive(),
+  providerRefunded: z3.literal(true)
+};
+var cancelOrderReconciliationStatusSchema = z3.enum([
+  "paid",
+  "preparing",
+  "shipped",
+  "delivered",
+  "confirmed",
+  "return_requested",
+  "return_processing",
+  "returned",
+  "refunded"
+]);
+var cancelOrderResponseSchema = z3.union([
+  z3.object({
+    ...cancelOrderResponseBaseSchema,
+    ...unpaidCancelResponseFields,
+    status: z3.literal("canceled"),
+    cancelCommitted: z3.literal(true)
+  }).strict(),
+  z3.object({
+    ...cancelOrderResponseBaseSchema,
+    ...providerRefundResponseFields,
+    status: z3.literal("canceled"),
+    cancelCommitted: z3.literal(true)
+  }).strict(),
+  z3.object({
+    ...cancelOrderResponseBaseSchema,
+    ...alreadyCanceledResponseFields,
+    status: z3.literal("canceled"),
+    cancelCommitted: z3.literal(false),
+    alreadyCanceled: z3.literal(true)
+  }).strict(),
+  z3.object({
+    ...cancelOrderResponseBaseSchema,
+    ...providerRefundResponseFields,
+    status: cancelOrderReconciliationStatusSchema,
+    cancelCommitted: z3.literal(false),
+    reconciliationRequired: z3.literal(true)
+  }).strict()
+]);
 
 // ../../packages/contracts/src/mcp/index.ts
 var MCP_TOOL_CONTRACT = {
@@ -520,6 +752,11 @@ var MCP_TOOL_CONTRACT = {
     oauthScope: "mcp:write",
     readOnly: false
   },
+  "cancel-order": {
+    consoleRole: "tenant-admin",
+    oauthScope: "mcp:write",
+    readOnly: false
+  },
   "update-order": {
     consoleRole: "tenant-admin",
     oauthScope: "mcp:write",
@@ -760,14 +997,14 @@ 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": {
@@ -778,11 +1015,19 @@ var TOOL_POLICY_MANIFEST = {
     annotationPolicy: DESTRUCTIVE_IDEMPOTENT_MUTATION_ANNOTATION,
     exemptionReason: REASON_IDEMPOTENT_DESTRUCTIVE_UPDATE
   },
+  "cancel-order": {
+    category: "mutation-order",
+    oauthScope: MCP_SCOPES.write,
+    consoleRole: "tenant-admin",
+    consoleSurface: "POST /api/orders/cancel",
+    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
   },
@@ -791,14 +1036,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
   },
@@ -807,14 +1052,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
   },
@@ -822,7 +1067,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) ──
@@ -830,7 +1075,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) ──
@@ -1233,7 +1478,7 @@ async function swallow(promise) {
 }
 
 // src/tools/query-collection.ts
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 
 // src/lib/client.ts
 import { createServerClient } from "@01.software/sdk/server";
@@ -1269,13 +1514,13 @@ function getClient() {
 // src/tools/query-collection.ts
 import { SERVER_COLLECTIONS } from "@01.software/sdk";
 var schema = {
-  collection: z3.enum(SERVER_COLLECTIONS).describe("Collection name (required)"),
-  where: z3.string().optional().describe(
+  collection: z4.enum(SERVER_COLLECTIONS).describe("Collection name (required)"),
+  where: z4.string().optional().describe(
     `Filter conditions (JSON string, optional). Pass the Payload query condition object as a JSON string. Example: '{"title":{"equals":"Product name"}}'`
   ),
-  limit: z3.number().min(1).max(100).default(10).describe("Maximum number of items to return (1-100, default: 10)."),
-  page: z3.number().optional().describe("Page number (optional). Starts from 1. Used for pagination."),
-  sort: z3.string().regex(
+  limit: z4.number().min(1).max(100).default(10).describe("Maximum number of items to return (1-100, default: 10)."),
+  page: z4.number().optional().describe("Page number (optional). Starts from 1. Used for pagination."),
+  sort: z4.string().regex(
     /^-?[a-zA-Z0-9_.]+$/,
     'Sort must be a field name, optionally prefixed with "-" for descending'
   ).optional().describe(
@@ -1332,11 +1577,11 @@ async function queryCollection({
 }
 
 // src/tools/get-collection-by-id.ts
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 import { SERVER_COLLECTIONS as SERVER_COLLECTIONS2 } from "@01.software/sdk";
 var schema2 = {
-  collection: z4.enum(SERVER_COLLECTIONS2).describe("Collection name (required)"),
-  id: z4.string().min(1).describe("Item ID (required)")
+  collection: z5.enum(SERVER_COLLECTIONS2).describe("Collection name (required)"),
+  id: z5.string().min(1).describe("Item ID (required)")
 };
 var metadata2 = {
   name: "get-collection-by-id",
@@ -1362,9 +1607,9 @@ async function getCollectionById({
 }
 
 // src/tools/get-order.ts
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 var schema3 = {
-  orderNumber: z5.string().min(1).describe("Order number to look up (required)")
+  orderNumber: z6.string().min(1).describe("Order number to look up (required)")
 };
 var metadata3 = {
   name: "get-order",
@@ -1417,10 +1662,10 @@ async function createOrder(params) {
 }
 
 // src/tools/update-order.ts
-import { z as z6 } from "zod";
+import { z as z7 } from "zod";
 var schema5 = {
-  orderNumber: z6.string().min(1).describe("Order number (required)"),
-  status: z6.enum([
+  orderNumber: z7.string().min(1).describe("Order number (required)"),
+  status: z7.enum([
     "pending",
     "paid",
     "failed",
@@ -1430,12 +1675,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,
@@ -1457,15 +1702,15 @@ async function updateOrder({
 }
 
 // src/tools/checkout.ts
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 var schema6 = {
-  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(
+  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(
     "Customer snapshot object (required). Fields: { name?, email, phone? }"
   ),
-  discountCode: z7.string().optional().describe("Discount code to apply (optional)")
+  discountCode: z8.string().optional().describe("Discount code to apply (optional)")
 };
 var metadata6 = {
   name: "checkout",
@@ -1490,17 +1735,17 @@ async function checkout(params) {
 }
 
 // src/tools/create-fulfillment.ts
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 var schema7 = {
-  orderNumber: z8.string().min(1).describe("Order number (required)"),
-  carrier: z8.string().optional().describe("Shipping carrier name (optional)"),
-  trackingNumber: z8.string().optional().describe(
+  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'
   ),
-  items: z8.array(
-    z8.object({
-      orderItem: z8.string().min(1).describe("Order item ID"),
-      quantity: z8.number().int().positive().describe("Quantity to fulfill")
+  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)")
 };
@@ -1535,16 +1780,16 @@ async function createFulfillment({
 }
 
 // src/tools/update-fulfillment.ts
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 var schema8 = {
-  fulfillmentId: z9.string().min(1).describe("Fulfillment ID (required)"),
-  status: z9.enum(["packed", "shipped", "delivered", "failed"]).describe(
+  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: z9.string().optional().describe(
+  carrier: z10.string().optional().describe(
     "Shipping carrier (optional, changeable only in pending/packed status)"
   ),
-  trackingNumber: z9.string().optional().describe(
+  trackingNumber: z10.string().optional().describe(
     "Tracking number (optional, changeable only in pending/packed status)"
   )
 };
@@ -1638,21 +1883,54 @@ async function confirmPayment(params) {
   }
 }
 
+// src/tools/cancel-order.ts
+var CancelOrderToolSchema = CancelOrderSchema.extend({
+  idempotencyKey: idempotencyKeySchema.optional().describe(
+    "Optional X-Idempotency-Key forwarded to the Console cancel endpoint"
+  )
+}).strict();
+var schema11 = CancelOrderToolSchema.shape;
+var metadata11 = {
+  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.",
+  annotations: {
+    title: "Cancel order",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true
+  }
+};
+async function cancelOrder(params) {
+  try {
+    const parsed = CancelOrderToolSchema.parse(params);
+    const client = getClient();
+    const result = await client.commerce.orders.cancelOrder({
+      orderNumber: parsed.orderNumber,
+      reasonCode: parsed.reasonCode,
+      reasonDetail: parsed.reasonDetail,
+      idempotencyKey: parsed.idempotencyKey
+    });
+    return toolSuccess({ data: result });
+  } catch (error) {
+    return toolError(error);
+  }
+}
+
 // src/tools/create-return.ts
-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")
+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: z10.number().nonnegative().describe("Refund amount (required, min 0)")
+  refundAmount: z11.number().nonnegative().describe("Refund amount (required, min 0)")
 };
-var metadata11 = {
+var metadata12 = {
   name: "create-return",
   description: "Create a return request for an order. Only works for delivered/confirmed orders. Updates order status to return_requested.",
   annotations: {
@@ -1685,16 +1963,16 @@ async function createReturn({
 }
 
 // src/tools/update-return.ts
-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 return status (required). Valid transitions: requested\u2192processing/rejected, processing\u2192approved/rejected, approved\u2192completed"
+import { z as z12 } from "zod";
+var schema13 = {
+  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 metadata12 = {
+var metadata13 = {
   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,
@@ -1708,7 +1986,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);
@@ -1716,10 +1997,10 @@ async function updateReturn({
 }
 
 // src/tools/return-with-refund.ts
-var schema13 = ReturnWithRefundSchema.shape;
-var metadata13 = {
+var schema14 = ReturnWithRefundSchema.shape;
+var metadata14 = {
   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,
@@ -1733,6 +2014,7 @@ async function returnWithRefund({
   reasonDetail,
   returnItems,
   refundAmount,
+  returnShippingFee,
   pgPaymentId,
   paymentKey,
   refundReceiptUrl
@@ -1745,6 +2027,7 @@ async function returnWithRefund({
       reasonDetail,
       returnItems,
       refundAmount,
+      returnShippingFee,
       pgPaymentId,
       paymentKey,
       refundReceiptUrl
@@ -1757,15 +2040,15 @@ async function returnWithRefund({
 }
 
 // src/tools/add-cart-item.ts
-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)")
+import { z as z13 } from "zod";
+var schema15 = {
+  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 metadata14 = {
+var metadata15 = {
   name: "add-cart-item",
   description: "Add a product to cart. Validates stock, merges quantity if item already exists, recalculates totals.",
   annotations: {
@@ -1798,12 +2081,12 @@ async function addCartItem({
 }
 
 // src/tools/update-cart-item.ts
-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)")
+import { z as z14 } from "zod";
+var schema16 = {
+  cartItemId: z14.string().min(1).describe("Cart item ID (required)"),
+  quantity: z14.number().int().positive().describe("New quantity (required, positive integer)")
 };
-var metadata15 = {
+var metadata16 = {
   name: "update-cart-item",
   description: "Update cart item quantity. Validates stock availability, recalculates cart totals.",
   annotations: {
@@ -1827,11 +2110,11 @@ async function updateCartItem({
 }
 
 // src/tools/remove-cart-item.ts
-import { z as z14 } from "zod";
-var schema16 = {
-  cartItemId: z14.string().min(1).describe("Cart item ID to remove (required)")
+import { z as z15 } from "zod";
+var schema17 = {
+  cartItemId: z15.string().min(1).describe("Cart item ID to remove (required)")
 };
-var metadata16 = {
+var metadata17 = {
   name: "remove-cart-item",
   description: "Remove an item from cart. Recalculates cart totals after removal.",
   annotations: {
@@ -1854,12 +2137,12 @@ async function removeCartItem({
 }
 
 // src/tools/apply-discount.ts
-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)")
+import { z as z16 } from "zod";
+var schema18 = {
+  cartId: z16.string().min(1).describe("Cart ID (required)"),
+  discountCode: z16.string().describe("Discount code to apply (required)")
 };
-var metadata17 = {
+var metadata18 = {
   name: "apply-discount",
   description: "Apply a discount code to a cart. Validates the code, updates cart totals, and sets free shipping if applicable.",
   annotations: {
@@ -1883,11 +2166,11 @@ async function applyDiscount({
 }
 
 // src/tools/remove-discount.ts
-import { z as z16 } from "zod";
-var schema18 = {
-  cartId: z16.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: "remove-discount",
   description: "Remove the applied discount code from a cart and recalculate totals.",
   annotations: {
@@ -1910,11 +2193,11 @@ async function removeDiscount({
 }
 
 // src/tools/clear-cart.ts
-import { z as z17 } from "zod";
-var schema19 = {
-  cartId: z17.string().min(1).describe("Cart ID (required)")
+import { z as z18 } from "zod";
+var schema20 = {
+  cartId: z18.string().min(1).describe("Cart ID (required)")
 };
-var metadata19 = {
+var metadata20 = {
   name: "clear-cart",
   description: "Remove all items from a cart, reset discount and amounts. Shipping fee is preserved.",
   annotations: {
@@ -1937,12 +2220,12 @@ async function clearCart({
 }
 
 // src/tools/validate-discount.ts
-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)")
+import { z as z19 } from "zod";
+var schema21 = {
+  code: z19.string().describe("Discount code to validate (required)"),
+  orderAmount: z19.number().describe("Order amount for validation (required)")
 };
-var metadata20 = {
+var metadata21 = {
   name: "validate-discount",
   description: "Validate a discount code. Checks active status, date range, usage limits, minimum order amount, and calculates discount.",
   annotations: {
@@ -1969,13 +2252,13 @@ async function validateDiscount({
 }
 
 // src/tools/calculate-shipping.ts
-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)")
+import { z as z20 } from "zod";
+var schema22 = {
+  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 metadata21 = {
+var metadata22 = {
   name: "calculate-shipping",
   description: "Calculate shipping fee based on order amount and postal code. Supports free shipping threshold and Jeju surcharge.",
   annotations: {
@@ -2004,18 +2287,18 @@ async function calculateShipping({
 }
 
 // src/tools/stock-check.ts
-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")
+import { z as z21 } from "zod";
+var schema23 = {
+  items: z21.array(
+    z21.object({
+      variantId: z21.string().describe("Product variant ID"),
+      quantity: z21.number().int().positive().describe("Requested quantity")
     })
   ).describe(
     "Array of items to check stock for (required, max 100). Each: { variantId, quantity }"
   )
 };
-var metadata22 = {
+var metadata23 = {
   name: "stock-check",
   description: "Batch check product option stock availability. Returns per-item availability and an allAvailable flag.",
   annotations: {
@@ -2038,14 +2321,14 @@ async function stockCheck({
 }
 
 // src/tools/product-detail.ts
-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)")
+import { z as z22 } from "zod";
+var schema24 = {
+  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 metadata23 = {
+var metadata24 = {
   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,
@@ -2071,68 +2354,26 @@ async function productDetail({
 }
 
 // src/tools/product-upsert.ts
-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."
+var schema25 = {
+  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."
   ),
-  swatchColor: z22.string().nullable().optional(),
-  thumbnail: z22.string().nullable().optional(),
-  images: z22.array(z22.string()).optional(),
-  metadata: z22.unknown().optional()
-});
-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: z22.array(optionValueSchema).describe("Allowed option values")
-});
-var variantOptionValueSchema = z22.object({
-  valueSlug: z22.string().optional(),
-  valueId: z22.string().optional(),
-  value: z22.string().optional()
-});
-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."
+  graphRevision: ProductUpsertObjectSchema.shape.graphRevision.describe(
+    "Required when updating a product that already has options or variants on the server. Load from GET /api/products/:id/composer-draft."
   ),
-  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 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)."
+  product: ProductUpsertObjectSchema.shape.product.describe(
+    "Product document fields for create (`title` required). For existing products, save document fields through Payload/Admin and send productId for graph upsert."
   ),
-  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)."
+  options: ProductUpsertObjectSchema.shape.options.describe(
+    "Full desired option graph. On edit, omitted options are deleted. Include stable option/value IDs for rename-safe updates."
   ),
-  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)."
+  variants: ProductUpsertObjectSchema.shape.variants.describe(
+    "Full desired variant graph. On edit, omitted variants are deleted or deactivated according to server references. Prefer stable option-value IDs."
   )
 };
-var metadata24 = {
+var metadata25 = {
   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.",
+  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: {
     title: "Upsert product (atomic)",
     readOnlyHint: false,
@@ -2143,9 +2384,13 @@ var metadata24 = {
 };
 async function productUpsert(params) {
   try {
+    const parsed = ProductUpsertSchema.safeParse(params);
+    if (!parsed.success) {
+      return toolError(parsed.error);
+    }
     const client = getClient();
     const result = await client.commerce.product.upsert(
-      params
+      parsed.data
     );
     return toolSuccess({ data: result });
   } catch (error) {
@@ -2167,8 +2412,8 @@ async function getCollectionSchema(collection) {
 }
 
 // src/tools/get-collection-schema.ts
-var schema25 = createCollectionSchemaToolInputSchema(SERVER_COLLECTIONS3).shape;
-var metadata25 = {
+var schema26 = createCollectionSchemaToolInputSchema(SERVER_COLLECTIONS3).shape;
+var metadata26 = {
   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: {
@@ -2219,8 +2464,8 @@ async function getTenantFeatureProgress(feature, includeEvidence = false) {
 }
 
 // src/tools/get-tenant-context.ts
-var schema26 = tenantContextToolInputSchema.shape;
-var metadata26 = {
+var schema27 = tenantContextToolInputSchema.shape;
+var metadata27 = {
   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: {
@@ -2297,8 +2542,8 @@ async function handler({
 }
 
 // src/tools/check-feature-progress.ts
-var schema27 = tenantFeatureProgressInputSchema.shape;
-var metadata27 = {
+var schema28 = tenantFeatureProgressInputSchema.shape;
+var metadata28 = {
   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: {
@@ -2344,12 +2589,12 @@ function invalidateFieldConfigCache() {
 }
 
 // src/tools/list-configurable-fields.ts
-var schema28 = {
+var schema29 = {
   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 metadata28 = {
+var metadata29 = {
   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: {
@@ -2381,7 +2626,7 @@ async function listConfigurableFields(params) {
 
 // src/tools/update-field-config.ts
 import { z as z24 } from "zod";
-var schema29 = {
+var schema30 = {
   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."
@@ -2390,7 +2635,7 @@ var schema29 = {
     "Hide the entire collection from Admin Panel (optional). When true, individual hiddenFields are irrelevant."
   )
 };
-var metadata29 = {
+var metadata30 = {
   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: {
@@ -2859,7 +3104,7 @@ function getRecipe(goal, runtime = "both") {
 }
 
 // src/tools/sdk-get-recipe.ts
-var schema30 = {
+var schema31 = {
   goal: z25.enum([
     "fetch-list",
     "fetch-by-id",
@@ -2876,7 +3121,7 @@ var schema30 = {
   collection: z25.string().optional().describe("Specific collection name if applicable"),
   includeExample: z25.boolean().default(true).describe("Whether to include a full code example")
 };
-var metadata30 = {
+var metadata31 = {
   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: {
@@ -3105,11 +3350,11 @@ function searchDocs(query, limit = 5) {
 }
 
 // src/tools/sdk-search-docs.ts
-var schema31 = {
+var schema32 = {
   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 metadata31 = {
+var metadata32 = {
   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: {
@@ -3145,7 +3390,7 @@ function handler4({
 
 // src/tools/sdk-get-auth-setup.ts
 import { z as z27 } from "zod";
-var schema32 = {
+var schema33 = {
   scenario: z27.enum([
     "browser-client",
     "server-client",
@@ -3155,7 +3400,7 @@ var schema32 = {
     "webhook-verification"
   ]).describe("Authentication scenario")
 };
-var metadata32 = {
+var metadata33 = {
   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: {
@@ -3319,12 +3564,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 schema33 = {
+var schema34 = {
   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 metadata33 = {
+var metadata34 = {
   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: {
@@ -3521,13 +3766,13 @@ function handler6({
 
 // src/prompts/sdk-usage-guide.ts
 import { z as z29 } from "zod";
-var schema34 = {
+var schema35 = {
   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 metadata34 = {
+var metadata35 = {
   name: "sdk-usage-guide",
   title: "SDK Usage Guide",
   description: "Provides guidance on how to perform a specific task using the 01.software SDK",
@@ -3675,8 +3920,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 }
 \`\`\`
 
@@ -3700,12 +3946,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 schema35 = {
+var schema36 = {
   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 metadata35 = {
+var metadata36 = {
   name: "collection-query-help",
   title: "Collection Query Help",
   description: "Provides guidance on how to write queries for a specific collection",
@@ -3803,15 +4049,16 @@ ${operation === "find" ? `- Use \`where\` option for filtering (Payload query sy
 
 // src/prompts/order-flow-guide.ts
 import { z as z31 } from "zod";
-var schema36 = {
+var schema37 = {
   scenario: z31.enum([
     "simple-order",
     "cart-checkout",
     "return-refund",
+    "order-cancel",
     "fulfillment-tracking"
   ]).describe("Order flow scenario")
 };
-var metadata36 = {
+var metadata37 = {
   name: "order-flow-guide",
   title: "Order Flow Guide",
   description: "Provides step-by-step guidance for ecommerce order flows including creation, checkout, returns, and fulfillment.",
@@ -3912,12 +4159,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
@@ -3933,12 +4181,42 @@ 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'
 })
 \`\`\``,
+  "order-cancel": `## Provider-Verified Order Cancellation
+
+### Flow
+
+1. **Cancel Order** -> \`cancel-order\` tool
+   - Pending or failed unpaid orders cancel without a provider call
+   - Paid captured orders use the server-stored provider payment key from the captured transaction
+   - Paid captured orders are refunded through the provider-verified path before local status changes
+   - Successful paid cancellation releases reservedStock and moves the order to \`canceled\`
+   - Duplicate local success returns \`alreadyCanceled: true\`; do not issue a second refund
+   - Provider-refunded local blockers return \`reconciliationRequired: true\` on retry
+
+### V1 Rejections
+- Orders with non-failed fulfillments 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 and no-refund paid cancellation are not supported in v1
+
+### Code Example
+\`\`\`typescript
+await client.commerce.orders.cancelOrder({
+  orderNumber: 'ORD-240101-001',
+  reasonCode: 'customer',
+  reasonDetail: 'Customer emailed before shipment',
+  idempotencyKey: 'cancel-ORD-240101-001'
+})
+\`\`\`
+
+If \`reconciliationRequired\` is true, stop provider retries and hand off to an operator to reconcile fulfillment, stock, and accounting manually.`,
   "fulfillment-tracking": `## Fulfillment & Tracking
 
 ### Creating Fulfillment
@@ -3994,13 +4272,13 @@ ${SCENARIOS[scenario] || "Unknown scenario."}
 - \`checkout\`
 - \`create-fulfillment\`, \`update-fulfillment\`
 - \`create-return\`, \`update-return\`, \`return-with-refund\`
-- \`confirm-payment\`, \`update-transaction\`
+- \`confirm-payment\`, \`cancel-order\`, \`update-transaction\`
 - \`validate-discount\`, \`calculate-shipping\``;
 }
 
 // src/prompts/feature-setup-guide.ts
 import { z as z32 } from "zod";
-var schema37 = {
+var schema38 = {
   feature: z32.enum([
     "ecommerce",
     "customers",
@@ -4016,7 +4294,7 @@ var schema37 = {
     "community"
   ]).describe("Feature to get setup guide for")
 };
-var metadata37 = {
+var metadata38 = {
   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.",
@@ -4224,7 +4502,7 @@ ${FEATURES[feature] || "Unknown feature."}
 }
 
 // src/resources/(config)/app.ts
-var metadata38 = {
+var metadata39 = {
   name: "app-config",
   title: "Application Config",
   description: "01.software SDK and MCP server configuration information"
@@ -4290,7 +4568,7 @@ Rate limits depend on your tenant plan:
 
 // src/resources/(collections)/schema.ts
 import { COLLECTIONS as COLLECTIONS3 } from "@01.software/sdk";
-var metadata39 = {
+var metadata40 = {
   name: "collections-schema",
   title: "Collection Schema Info",
   description: "Available collections and their schema information"
@@ -4427,7 +4705,7 @@ Total available collections: ${COLLECTIONS3.length}`;
 }
 
 // src/resources/(docs)/getting-started.ts
-var metadata40 = {
+var metadata41 = {
   name: "docs-getting-started",
   title: "Getting Started",
   description: "01.software SDK getting started guide"
@@ -4488,7 +4766,7 @@ const result = await client.collections.from('products').find({
 }
 
 // src/resources/(docs)/guides.ts
-var metadata41 = {
+var metadata42 = {
   name: "docs-guides",
   title: "Guides",
   description: "01.software SDK usage guides"
@@ -4701,7 +4979,7 @@ For more implementation guidance, see the [SDK Guide](/developers/sdk).`;
 }
 
 // src/resources/(docs)/api.ts
-var metadata42 = {
+var metadata43 = {
   name: "docs-api",
   title: "API Reference",
   description: "01.software SDK API reference documentation"
@@ -4984,7 +5262,7 @@ For more details, see the [API documentation](/developers/api).`;
 }
 
 // src/resources/(docs)/query-builder.ts
-var metadata43 = {
+var metadata44 = {
   name: "docs-query-builder",
   title: "Query Builder",
   description: "01.software SDK Query Builder API reference (client.collections.from)"
@@ -5178,7 +5456,7 @@ console.log(result.hasNextPage) // true
 }
 
 // src/resources/(docs)/react-query.ts
-var metadata44 = {
+var metadata45 = {
   name: "docs-react-query",
   title: "React Query Hooks",
   description: "01.software SDK React Query hooks reference (@01.software/sdk/query)"
@@ -5410,7 +5688,7 @@ export function ProductList() {
 }
 
 // src/resources/(docs)/server-api.ts
-var metadata45 = {
+var metadata46 = {
   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"
@@ -5541,12 +5819,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
 })
 \`\`\`
 
@@ -5559,9 +5837,10 @@ 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,
+  returnShippingFee?: 1500,
   pgPaymentId: 'provider-payment-id',  // required
   paymentKey: 'provider-payment-key',  // required for provider refund
   refundReceiptUrl?: 'https://...',
@@ -5693,7 +5972,7 @@ const result = await client.commerce.shipping.calculate({
 }
 
 // src/resources/(docs)/customer-auth.ts
-var metadata46 = {
+var metadata47 = {
   name: "docs-customer-auth",
   title: "Customer Auth API",
   description: "01.software SDK Customer Auth API reference (client.customer)"
@@ -5871,7 +6150,7 @@ async function loadProfile() {
 }
 
 // src/resources/(docs)/browser-vs-server.ts
-var metadata47 = {
+var metadata48 = {
   name: "docs-browser-vs-server",
   title: "Client vs ServerClient",
   description: "When to use Client (createClient) vs ServerClient (createServerClient) in the 01.software SDK"
@@ -6037,7 +6316,7 @@ export function ProductList() {
 }
 
 // src/resources/(docs)/file-upload.ts
-var metadata48 = {
+var metadata49 = {
   name: "docs-file-upload",
   title: "File Upload",
   description: "01.software SDK file upload patterns using the images collection"
@@ -6188,7 +6467,7 @@ The platform stores files in Cloudflare R2 and serves via CDN (\`cdn.01.software
 }
 
 // src/resources/(docs)/webhook.ts
-var metadata49 = {
+var metadata50 = {
   name: "docs-webhook",
   title: "Webhooks",
   description: "01.software SDK webhook verification and event handling"
@@ -6196,11 +6475,11 @@ var metadata49 = {
 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'
@@ -6253,28 +6532,119 @@ export async function POST(request: Request) {
 }
 \`\`\`
 
+## 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"\`.
-- \`change.scope\` identifies collection-level ordering versus join ordering.
 - 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.
@@ -6324,8 +6694,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,
   }
 }
 \`\`\`
@@ -6340,11 +6710,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()}\`,
   })
 }
 \`\`\`
@@ -6355,11 +6727,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 metadata50 = {
+var metadata51 = {
   name: "docs-product-detail",
   title: "Product Detail Helper",
   description: "01.software SDK commerce.product.detail helper guide"
@@ -6383,8 +6755,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
@@ -6435,18 +6807,20 @@ 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
@@ -6467,7 +6841,7 @@ function runtimeAnnotationsFor(meta) {
     openWorldHint: policy.annotationPolicy.openWorld
   };
 }
-function registerTool(server, schema38, meta, handler21) {
+function registerTool(server, schema39, meta, handler21) {
   let registered = REGISTERED_TOOLS_BY_SERVER.get(server);
   if (!registered) {
     registered = /* @__PURE__ */ new Set();
@@ -6478,7 +6852,7 @@ function registerTool(server, schema38, meta, handler21) {
     meta.name,
     {
       description: meta.description,
-      inputSchema: schema38,
+      inputSchema: schema39,
       annotations: runtimeAnnotationsFor(meta)
     },
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -6528,13 +6902,13 @@ function registerTool(server, schema38, meta, handler21) {
     }
   );
 }
-function registerPrompt(server, schema38, meta, handler21) {
+function registerPrompt(server, schema39, meta, handler21) {
   server.registerPrompt(
     meta.name,
     {
       title: meta.title,
       description: meta.description,
-      argsSchema: schema38
+      argsSchema: schema39
     },
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     (params) => ({
@@ -6608,230 +6982,231 @@ function createServer(options = {}) {
       metadata10,
       confirmPayment
     );
-    registerTool(
-      server,
-      schema11,
-      metadata11,
-      createReturn
-    );
+    registerTool(server, schema11, metadata11, cancelOrder);
     registerTool(
       server,
       schema12,
       metadata12,
-      updateReturn
+      createReturn
     );
     registerTool(
       server,
       schema13,
       metadata13,
-      returnWithRefund
+      updateReturn
     );
-    registerTool(server, schema14, metadata14, addCartItem);
     registerTool(
       server,
-      schema15,
-      metadata15,
-      updateCartItem
+      schema14,
+      metadata14,
+      returnWithRefund
     );
+    registerTool(server, schema15, metadata15, addCartItem);
     registerTool(
       server,
       schema16,
       metadata16,
-      removeCartItem
+      updateCartItem
     );
     registerTool(
       server,
       schema17,
       metadata17,
-      applyDiscount
+      removeCartItem
     );
     registerTool(
       server,
       schema18,
       metadata18,
-      removeDiscount
+      applyDiscount
     );
-    registerTool(server, schema19, metadata19, clearCart);
     registerTool(
       server,
-      schema20,
-      metadata20,
-      validateDiscount
+      schema19,
+      metadata19,
+      removeDiscount
     );
+    registerTool(server, schema20, metadata20, clearCart);
     registerTool(
       server,
       schema21,
       metadata21,
-      calculateShipping
+      validateDiscount
     );
-    registerTool(server, schema22, metadata22, stockCheck);
     registerTool(
       server,
-      schema23,
-      metadata23,
-      productDetail
+      schema22,
+      metadata22,
+      calculateShipping
     );
+    registerTool(server, schema23, metadata23, stockCheck);
     registerTool(
       server,
       schema24,
       metadata24,
+      productDetail
+    );
+    registerTool(
+      server,
+      schema25,
+      metadata25,
       productUpsert
     );
   }
-  registerTool(
-    server,
-    schema25,
-    metadata25,
-    getCollectionSchemaTool
-  );
   registerTool(
     server,
     schema26,
     metadata26,
-    handler
+    getCollectionSchemaTool
   );
   registerTool(
     server,
     schema27,
     metadata27,
-    handler2
+    handler
   );
   registerTool(
     server,
     schema28,
     metadata28,
-    listConfigurableFields
+    handler2
   );
   registerTool(
     server,
     schema29,
     metadata29,
-    updateFieldConfig
+    listConfigurableFields
   );
   registerTool(
     server,
     schema30,
     metadata30,
-    handler3
+    updateFieldConfig
   );
   registerTool(
     server,
     schema31,
     metadata31,
-    handler4
+    handler3
   );
   registerTool(
     server,
     schema32,
     metadata32,
-    handler5
+    handler4
   );
   registerTool(
     server,
     schema33,
     metadata33,
-    handler6
+    handler5
   );
-  registerPrompt(
+  registerTool(
     server,
     schema34,
     metadata34,
-    sdkUsageGuide
+    handler6
   );
   registerPrompt(
     server,
     schema35,
     metadata35,
-    collectionQueryHelp
+    sdkUsageGuide
   );
   registerPrompt(
     server,
     schema36,
     metadata36,
-    orderFlowGuide
+    collectionQueryHelp
   );
   registerPrompt(
     server,
     schema37,
     metadata37,
+    orderFlowGuide
+  );
+  registerPrompt(
+    server,
+    schema38,
+    metadata38,
     featureSetupGuide
   );
   registerStaticResource(
     server,
     mcpResourceUri("app-config"),
-    metadata38,
+    metadata39,
     handler7
   );
   registerStaticResource(
     server,
     mcpResourceUri("collections-schema"),
-    metadata39,
+    metadata40,
     handler8
   );
   registerStaticResource(
     server,
     mcpResourceUri("docs-getting-started"),
-    metadata40,
+    metadata41,
     handler9
   );
   registerStaticResource(
     server,
     mcpResourceUri("docs-guides"),
-    metadata41,
+    metadata42,
     handler10
   );
   registerStaticResource(
     server,
     mcpResourceUri("docs-api"),
-    metadata42,
+    metadata43,
     handler11
   );
   registerStaticResource(
     server,
     mcpResourceUri("docs-query-builder"),
-    metadata43,
+    metadata44,
     handler12
   );
   registerStaticResource(
     server,
     mcpResourceUri("docs-react-query"),
-    metadata44,
+    metadata45,
     handler13
   );
   registerStaticResource(
     server,
     mcpResourceUri("docs-server-api"),
-    metadata45,
+    metadata46,
     handler14
   );
   registerStaticResource(
     server,
     mcpResourceUri("docs-customer-auth"),
-    metadata46,
+    metadata47,
     handler15
   );
   registerStaticResource(
     server,
     mcpResourceUri("docs-browser-vs-server"),
-    metadata47,
+    metadata48,
     handler16
   );
   registerStaticResource(
     server,
     mcpResourceUri("docs-file-upload"),
-    metadata48,
+    metadata49,
     handler17
   );
   registerStaticResource(
     server,
     mcpResourceUri("docs-webhook"),
-    metadata49,
+    metadata50,
     handler18
   );
   registerStaticResource(
     server,
     mcpResourceUri("docs-product-detail"),
-    metadata50,
+    metadata51,
     handler19
   );
   return server;