@01.software/cli 0.10.1 → 0.10.4

package/dist/mcp/vercel.js

@@ -1,7 +1,7 @@
 // src/handler.ts
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 
-// ../../packages/auth-contracts/dist/index.js
+// ../../packages/auth-contracts/src/index.ts
 var MCP_RESOURCE_AUDIENCE = "https://mcp.01.software/mcp";
 var MCP_OAUTH_ISSUER = "https://01.software";
 var MCP_PROTECTED_RESOURCE_METADATA_PATH = "/.well-known/oauth-protected-resource/mcp";
@@ -91,8 +91,9 @@ function parseJsonWhere(where) {
   }
 }
 
-// ../../packages/contracts/src/tenant/index.ts
+// ../../packages/contracts/dist/index.js
 import { z } from "zod";
+import { z as z2 } from "zod";
 var tenantFieldConfigStateSchema = z.object({
   hiddenFields: z.array(z.string()),
   isHidden: z.boolean()
@@ -241,9 +242,6 @@ var collectionSchemaResponseSchema = z.object({
     fields: z.array(collectionFieldSchema)
   }).strict()
 }).strict();
-
-// ../../packages/contracts/src/ecommerce/index.ts
-import { z as z2 } from "zod";
 var transactionStatusSchema = z2.enum([
   "pending",
   "paid",
@@ -295,7 +293,8 @@ 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"),
-  restockAction: restockActionSchema.default("return_to_stock")
+  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)")
 }).strict();
 var returnWithRefundSchema = z2.object({
   orderNumber: z2.string().min(1, "orderNumber is required").describe("Order number (required)"),
@@ -303,13 +302,12 @@ var returnWithRefundSchema = z2.object({
   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)")
 }).strict();
 var ReturnWithRefundSchema = returnWithRefundSchema;
-
-// ../../packages/contracts/src/mcp/index.ts
 var MCP_TOOL_CONTRACT = {
   "query-collection": {
     consoleRole: "tenant-viewer",
@@ -331,6 +329,16 @@ var MCP_TOOL_CONTRACT = {
     oauthScope: "mcp:read",
     readOnly: true
   },
+  "product-detail": {
+    consoleRole: "tenant-viewer",
+    oauthScope: "mcp:read",
+    readOnly: true
+  },
+  "product-upsert": {
+    consoleRole: "tenant-admin",
+    oauthScope: "mcp:write",
+    readOnly: false
+  },
   "validate-discount": {
     consoleRole: "tenant-viewer",
     oauthScope: "mcp:read",
@@ -530,6 +538,21 @@ var TOOL_POLICY_MANIFEST = {
     consoleSurface: "GET /api/products/{id}/stock",
     annotationPolicy: READ_ONLY_ANNOTATION
   },
+  "product-detail": {
+    category: "read-only-collection",
+    oauthScope: MCP_SCOPES.read,
+    consoleRole: "tenant-viewer",
+    consoleSurface: "GET /api/products/detail",
+    annotationPolicy: READ_ONLY_ANNOTATION
+  },
+  "product-upsert": {
+    category: "mutation-product",
+    oauthScope: MCP_SCOPES.write,
+    consoleRole: "tenant-admin",
+    consoleSurface: "POST /api/products/upsert",
+    annotationPolicy: DESTRUCTIVE_IDEMPOTENT_MUTATION_ANNOTATION,
+    exemptionReason: REASON_IDEMPOTENT_DESTRUCTIVE_UPDATE
+  },
   "validate-discount": {
     category: "read-only-collection",
     oauthScope: MCP_SCOPES.read,
@@ -883,9 +906,12 @@ function signMcpServiceToken(context) {
 }
 
 // src/lib/console-api.ts
-var BASE_URL = process.env.SOFTWARE_API_URL || "http://localhost:3000";
+var DEFAULT_API_URL = "https://api.01.software";
 var TIMEOUT_MS = 5e3;
 var MISSING_HTTP_AUTH_CONTEXT_ERROR = "MCP HTTP requests require a validated OAuth tenant context before tool execution.";
+function resolveConsoleApiUrl() {
+  return (process.env.SOFTWARE_API_URL || process.env.NEXT_PUBLIC_SOFTWARE_API_URL || DEFAULT_API_URL).replace(/\/$/, "");
+}
 function resolveAuthHeaderContext() {
   const oauthContext = tenantAuthContext();
   if (oauthContext) {
@@ -935,7 +961,7 @@ async function consoleGet(path, apiKey) {
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);
   try {
-    const res = await fetch(`${BASE_URL}${path}`, {
+    const res = await fetch(`${resolveConsoleApiUrl()}${path}`, {
       headers: authHeaders,
       signal: controller.signal
     });
@@ -954,7 +980,7 @@ async function consolePost(path, body, apiKey) {
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);
   try {
-    const res = await fetch(`${BASE_URL}${path}`, {
+    const res = await fetch(`${resolveConsoleApiUrl()}${path}`, {
       method: "POST",
       headers: { ...authHeaders, "Content-Type": "application/json" },
       body: JSON.stringify(body),
@@ -975,7 +1001,7 @@ async function consolePostTelemetry(path, body, apiKey) {
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);
   try {
-    const res = await fetch(`${BASE_URL}${path}`, {
+    const res = await fetch(`${resolveConsoleApiUrl()}${path}`, {
       method: "POST",
       headers: { ...authHeaders, "Content-Type": "application/json" },
       body: JSON.stringify(body),
@@ -1076,7 +1102,7 @@ async function swallow(promise) {
 import { z as z3 } from "zod";
 
 // src/lib/client.ts
-import { createServerClient } from "@01.software/sdk";
+import { createServerClient } from "@01.software/sdk/server";
 var MISSING_HTTP_AUTH_CONTEXT_ERROR2 = "MCP HTTP requests require a validated OAuth tenant context before tool execution.";
 var HTTP_OAUTH_SDK_CLIENT_ERROR = "MCP HTTP OAuth requests cannot use SDK-backed tools. Use reviewed Console service endpoints for OAuth transport.";
 function getClient() {
@@ -1873,6 +1899,122 @@ async function stockCheck({
   }
 }
 
+// src/tools/product-detail.ts
+import { z as z22 } from "zod";
+var schema22 = {
+  slug: z22.string().optional().describe("Product slug (one of slug or id required)"),
+  id: z22.string().optional().describe("Product id (one of slug or id required)")
+};
+var metadata22 = {
+  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.",
+  annotations: {
+    title: "Get product detail",
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true
+  }
+};
+async function productDetail({
+  slug,
+  id
+}) {
+  try {
+    if (Boolean(slug) === Boolean(id)) {
+      return toolError(new Error("Provide exactly one of slug or id"));
+    }
+    const client = getClient();
+    const params = slug ? { slug } : { id };
+    const result = await client.commerce.product.detail(params);
+    return toolSuccess({ data: result });
+  } catch (error) {
+    return toolError(error);
+  }
+}
+
+// src/tools/product-upsert.ts
+import { z as z23 } from "zod";
+var optionValueSchema = z23.object({
+  id: z23.string().optional().describe("Stable existing option-value ID for rename-safe updates"),
+  value: z23.string().describe("Display label (e.g. Black, S)"),
+  slug: z23.string().optional().describe(
+    "Optional compatibility value token. The server generates one from value on create when omitted; not canonical identity."
+  ),
+  swatchColor: z23.string().nullable().optional(),
+  thumbnail: z23.string().nullable().optional(),
+  images: z23.array(z23.string()).optional(),
+  metadata: z23.unknown().optional()
+});
+var optionSchema = z23.object({
+  id: z23.string().optional().describe("Stable existing option ID for rename-safe updates"),
+  title: z23.string().describe("Option name (e.g. Color, Size)"),
+  slug: z23.string().optional().describe(
+    "Optional compatibility option token. The server generates one from title on create when omitted; not canonical identity."
+  ),
+  values: z23.array(optionValueSchema).describe("Allowed option values")
+});
+var variantOptionValueSchema = z23.object({
+  valueSlug: z23.string().optional(),
+  valueId: z23.string().optional(),
+  value: z23.string().optional()
+});
+var variantSchema = z23.object({
+  id: z23.string().optional().describe("Existing variant ID for updates"),
+  optionValues: z23.union([
+    z23.record(z23.string(), z23.union([z23.string(), variantOptionValueSchema])),
+    z23.array(z23.string())
+  ]).optional().describe(
+    "Option-value selection. Prefer stable option-value IDs, either as an array or object values using { valueId }. Slug maps and exact { OptionTitle: ValueLabel } maps remain compatibility-only and fail when labels are ambiguous."
+  ),
+  sku: z23.string().nullable().optional(),
+  title: z23.string().nullable().optional(),
+  price: z23.number().nonnegative().describe("Selling price (KRW, min 0)"),
+  compareAtPrice: z23.number().nonnegative().nullable().optional(),
+  stock: z23.number().int().nonnegative().optional(),
+  isUnlimited: z23.boolean().optional(),
+  weight: z23.number().nonnegative().nullable().optional(),
+  requiresShipping: z23.boolean().optional(),
+  barcode: z23.string().nullable().optional(),
+  externalId: z23.string().nullable().optional(),
+  isActive: z23.boolean().optional(),
+  thumbnail: z23.string().nullable().optional(),
+  images: z23.array(z23.string()).optional(),
+  metadata: z23.unknown().optional()
+});
+var schema23 = {
+  product: z23.record(z23.string(), z23.unknown()).describe(
+    "Product fields. Include `id` to update an existing product; omit for create (then `title` is required)."
+  ),
+  options: z23.array(optionSchema).optional().describe(
+    "Option definitions. Include stable option/value IDs when updating or renaming existing rows. Slugs are optional compatibility metadata generated from title/value on create when omitted; omitted options on an existing product are deleted (with their values)."
+  ),
+  variants: z23.array(variantSchema).optional().describe(
+    "Variant rows. Prefer stable option-value IDs in optionValues. Slug/title maps are compatibility inputs. Omitted variants on an existing product are deleted, unless referenced by an active cart or non-terminal order \u2014 those are soft-deactivated (isActive: false)."
+  )
+};
+var metadata23 = {
+  name: "product-upsert",
+  description: "Atomically create or update a product together with its options, option-values, and variants in a single transaction. Mirrors Shopify productSet semantics. Any failure rolls back the entire write.",
+  annotations: {
+    title: "Upsert product (atomic)",
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: false
+  }
+};
+async function productUpsert(params) {
+  try {
+    const client = getClient();
+    const result = await client.commerce.product.upsert(
+      params
+    );
+    return toolSuccess({ data: result });
+  } catch (error) {
+    return toolError(error);
+  }
+}
+
 // src/tools/get-collection-schema.ts
 import { SERVER_COLLECTIONS as SERVER_COLLECTIONS3 } from "@01.software/sdk";
 
@@ -1887,8 +2029,8 @@ async function getCollectionSchema(collection) {
 }
 
 // src/tools/get-collection-schema.ts
-var schema22 = createCollectionSchemaToolInputSchema(SERVER_COLLECTIONS3).shape;
-var metadata22 = {
+var schema24 = createCollectionSchemaToolInputSchema(SERVER_COLLECTIONS3).shape;
+var metadata24 = {
   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: {
@@ -1939,8 +2081,8 @@ async function getTenantFeatureProgress(feature, includeEvidence = false) {
 }
 
 // src/tools/get-tenant-context.ts
-var schema23 = tenantContextToolInputSchema.shape;
-var metadata23 = {
+var schema25 = tenantContextToolInputSchema.shape;
+var metadata25 = {
   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: {
@@ -2017,8 +2159,8 @@ async function handler({
 }
 
 // src/tools/check-feature-progress.ts
-var schema24 = tenantFeatureProgressInputSchema.shape;
-var metadata24 = {
+var schema26 = tenantFeatureProgressInputSchema.shape;
+var metadata26 = {
   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: {
@@ -2041,7 +2183,7 @@ async function handler2({
 }
 
 // src/tools/list-configurable-fields.ts
-import { z as z22 } from "zod";
+import { z as z24 } from "zod";
 
 // src/lib/field-config.ts
 async function fetchFieldConfigs() {
@@ -2064,12 +2206,12 @@ function invalidateFieldConfigCache() {
 }
 
 // src/tools/list-configurable-fields.ts
-var schema25 = {
-  collection: z22.string().optional().describe(
+var schema27 = {
+  collection: z24.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 metadata25 = {
+var metadata27 = {
   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: {
@@ -2100,17 +2242,17 @@ async function listConfigurableFields(params) {
 }
 
 // src/tools/update-field-config.ts
-import { z as z23 } from "zod";
-var schema26 = {
-  collection: z23.string().min(1).describe("Collection slug (required)"),
-  hiddenFields: z23.array(z23.string().min(1).max(200)).max(300).describe(
+import { z as z25 } from "zod";
+var schema28 = {
+  collection: z25.string().min(1).describe("Collection slug (required)"),
+  hiddenFields: z25.array(z25.string().min(1).max(200)).max(300).describe(
     "Fields to hide (required). This is a FULL REPLACE \u2014 fields NOT in this list will be shown. Pass [] to show all fields. Use list-configurable-fields first to see available field paths."
   ),
-  isHidden: z23.boolean().optional().describe(
+  isHidden: z25.boolean().optional().describe(
     "Hide the entire collection from Admin Panel (optional). When true, individual hiddenFields are irrelevant."
   )
 };
-var metadata26 = {
+var metadata28 = {
   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: {
@@ -2138,7 +2280,7 @@ async function updateFieldConfig(params) {
 }
 
 // src/tools/sdk-get-recipe.ts
-import { z as z24 } from "zod";
+import { z as z26 } from "zod";
 
 // src/lib/sdk-recipes.ts
 var recipes = {
@@ -2148,14 +2290,16 @@ var recipes = {
       recommendedSurface: "react-query",
       runtime: "browser",
       code: `import { createClient } from '@01.software/sdk'
+import { createQueryHooks } from '@01.software/sdk/query'
 
 const client = createClient({
   publishableKey: process.env.NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY!,
 })
+const query = createQueryHooks(client)
 
 // React Query hook \u2014 handles caching and background updates
 function ProductList() {
-  const { data, isLoading, error } = client.query.useQuery({
+  const { data, isLoading, error } = query.useQuery({
     collection: 'products',
     options: {
       where: { status: { equals: 'published' } },
@@ -2187,7 +2331,7 @@ function ProductList() {
       title: "Fetch collection list (server)",
       recommendedSurface: "query-builder",
       runtime: "server",
-      code: `import { createServerClient } from '@01.software/sdk'
+      code: `import { createServerClient } from '@01.software/sdk/server'
 
 const client = createServerClient({
   publishableKey: process.env.SOFTWARE_PUBLISHABLE_KEY!,
@@ -2220,13 +2364,15 @@ const result = await client.collections.from('products').find({
       recommendedSurface: "react-query",
       runtime: "browser",
       code: `import { createClient } from '@01.software/sdk'
+import { createQueryHooks } from '@01.software/sdk/query'
 
 const client = createClient({
   publishableKey: process.env.NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY!,
 })
+const query = createQueryHooks(client)
 
 function ProductDetail({ id }: { id: string }) {
-  const { data, isLoading } = client.query.useQueryById({
+  const { data, isLoading } = query.useQueryById({
     collection: 'products',
     id,
   })
@@ -2246,7 +2392,7 @@ function ProductDetail({ id }: { id: string }) {
       title: "Fetch single item by ID (server)",
       recommendedSurface: "query-builder",
       runtime: "server",
-      code: `import { createServerClient } from '@01.software/sdk'
+      code: `import { createServerClient } from '@01.software/sdk/server'
 
 const client = createServerClient({
   publishableKey: process.env.SOFTWARE_PUBLISHABLE_KEY!,
@@ -2269,7 +2415,7 @@ console.log(product.title)`,
       title: "Create a new item (server only)",
       recommendedSurface: "server-api",
       runtime: "server",
-      code: `import { createServerClient } from '@01.software/sdk'
+      code: `import { createServerClient } from '@01.software/sdk/server'
 
 const client = createServerClient({
   publishableKey: process.env.SOFTWARE_PUBLISHABLE_KEY!,
@@ -2298,7 +2444,7 @@ const result = await client.collections.from('products').create({
       title: "Update an existing item (server only)",
       recommendedSurface: "server-api",
       runtime: "server",
-      code: `import { createServerClient } from '@01.software/sdk'
+      code: `import { createServerClient } from '@01.software/sdk/server'
 
 const client = createServerClient({
   publishableKey: process.env.SOFTWARE_PUBLISHABLE_KEY!,
@@ -2327,7 +2473,7 @@ const result = await client.collections.from('products').update('product-id', {
       title: "Delete an item (server only)",
       recommendedSurface: "server-api",
       runtime: "server",
-      code: `import { createServerClient } from '@01.software/sdk'
+      code: `import { createServerClient } from '@01.software/sdk/server'
 
 const client = createServerClient({
   publishableKey: process.env.SOFTWARE_PUBLISHABLE_KEY!,
@@ -2352,10 +2498,12 @@ console.log('Deleted:', deleted.title)`,
       recommendedSurface: "react-query",
       runtime: "browser",
       code: `import { createClient } from '@01.software/sdk'
+import { createQueryHooks } from '@01.software/sdk/query'
 
 const client = createClient({
   publishableKey: process.env.NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY!,
 })
+const query = createQueryHooks(client)
 
 function InfiniteProductList() {
   const {
@@ -2364,7 +2512,7 @@ function InfiniteProductList() {
     hasNextPage,
     isFetchingNextPage,
     isLoading,
-  } = client.query.useInfiniteQuery({
+  } = query.useInfiniteQuery({
     collection: 'products',
     options: { where: { status: { equals: 'published' } } },
     pageSize: 20,
@@ -2399,7 +2547,8 @@ function InfiniteProductList() {
       title: "SSR data prefetching (server)",
       recommendedSurface: "react-query",
       runtime: "server",
-      code: `import { createServerClient } from '@01.software/sdk'
+      code: `import { createServerClient } from '@01.software/sdk/server'
+import { createServerQueryHooks, getQueryClient } from '@01.software/sdk/query'
 import { dehydrate, HydrationBoundary } from '@tanstack/react-query'
 
 // In a Next.js Server Component or getServerSideProps:
@@ -2407,27 +2556,29 @@ const client = createServerClient({
   publishableKey: process.env.SOFTWARE_PUBLISHABLE_KEY!,
   secretKey: process.env.SOFTWARE_SECRET_KEY!,
 })
+const queryClient = getQueryClient()
+const serverQuery = createServerQueryHooks(client, queryClient)
 
 // Prefetch list \u2014 client hydrates instantly without a loading state
-await client.query.prefetchQuery({
+await serverQuery.prefetchQuery({
   collection: 'products',
   options: { limit: 20 },
 })
 
 // Prefetch single item
-await client.query.prefetchQueryById({
+await serverQuery.prefetchQueryById({
   collection: 'products',
   id: 'product-id',
 })
 
 // Prefetch infinite list
-await client.query.prefetchInfiniteQuery({
+await serverQuery.prefetchInfiniteQuery({
   collection: 'products',
   pageSize: 20,
 })
 
 // Dehydrate and pass to client
-const state = dehydrate(client.query.queryClient)
+const state = dehydrate(queryClient)
 
 export default function Page() {
   return (
@@ -2497,7 +2648,7 @@ await client.customer.resetPassword(token, 'newPassword123')`,
       title: "File upload pattern (server)",
       recommendedSurface: "server-api",
       runtime: "server",
-      code: `import { createServerClient } from '@01.software/sdk'
+      code: `import { createServerClient } from '@01.software/sdk/server'
 
 const client = createServerClient({
   publishableKey: process.env.SOFTWARE_PUBLISHABLE_KEY!,
@@ -2528,7 +2679,7 @@ const result = await client.collections.from('images').create(formData as unknow
       title: "Bulk update/delete (server only)",
       recommendedSurface: "server-api",
       runtime: "server",
-      code: `import { createServerClient } from '@01.software/sdk'
+      code: `import { createServerClient } from '@01.software/sdk/server'
 
 const client = createServerClient({
   publishableKey: process.env.SOFTWARE_PUBLISHABLE_KEY!,
@@ -2570,8 +2721,8 @@ function getRecipe(goal, runtime = "both") {
 }
 
 // src/tools/sdk-get-recipe.ts
-var schema27 = {
-  goal: z24.enum([
+var schema29 = {
+  goal: z26.enum([
     "fetch-list",
     "fetch-by-id",
     "create-item",
@@ -2583,11 +2734,11 @@ var schema27 = {
     "file-upload",
     "bulk-operations"
   ]).describe("What the user wants to accomplish"),
-  runtime: z24.enum(["browser", "server", "both"]).default("both").describe("Target runtime environment"),
-  collection: z24.string().optional().describe("Specific collection name if applicable"),
-  includeExample: z24.boolean().default(true).describe("Whether to include a full code example")
+  runtime: z26.enum(["browser", "server", "both"]).default("both").describe("Target runtime environment"),
+  collection: z26.string().optional().describe("Specific collection name if applicable"),
+  includeExample: z26.boolean().default(true).describe("Whether to include a full code example")
 };
-var metadata27 = {
+var metadata29 = {
   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: {
@@ -2630,7 +2781,7 @@ function handler3({
 }
 
 // src/tools/sdk-search-docs.ts
-import { z as z25 } from "zod";
+import { z as z27 } from "zod";
 
 // src/lib/sdk-doc-index.ts
 var docIndex = [
@@ -2680,15 +2831,15 @@ var docIndex = [
   },
   {
     title: "Query Builder \u2014 Metadata Generation",
-    keywords: ["metadata", "findMetadata", "findMetadataById", "next.js metadata", "seo", "open graph", "query builder"],
-    summary: "client.collections.from(collection).findMetadata(options, config) and findMetadataById(id, config) generate Next.js Metadata objects from collection fields.",
+    keywords: ["metadata", "generateMetadata", "extractSeo", "next.js metadata", "seo", "open graph", "query builder"],
+    summary: "Use @01.software/sdk/metadata helpers with fetched documents to generate Metadata-shaped SEO objects without pulling Next.js into the root SDK entry.",
     resourceUri: "docs://sdk/query-builder"
   },
   // React Query Hooks
   {
     title: "React Query \u2014 useQuery()",
     keywords: ["useQuery", "react query", "hook", "list", "fetch", "collection", "cache", "react"],
-    summary: "client.query.useQuery({ collection, options }) \u2014 fetches a list with caching and background updates. Use inside a React component.",
+    summary: "createQueryHooks(client).useQuery({ collection, options }) \u2014 fetches a list with caching and background updates. Use inside a React component.",
     resourceUri: "docs://sdk/react-query"
   },
   {
@@ -2700,7 +2851,7 @@ var docIndex = [
   {
     title: "React Query \u2014 useInfiniteQuery()",
     keywords: ["useInfiniteQuery", "useSuspenseInfiniteQuery", "infinite scroll", "load more", "pagination", "react query", "hook"],
-    summary: "client.query.useInfiniteQuery({ collection, options, pageSize }) \u2014 infinite scrolling. data.pages is an array of pages; flatten with flatMap for all docs.",
+    summary: "createQueryHooks(client).useInfiniteQuery({ collection, options, pageSize }) \u2014 infinite scrolling. data.pages is an array of pages; flatten with flatMap for all docs.",
     resourceUri: "docs://sdk/react-query"
   },
   {
@@ -2719,7 +2870,7 @@ var docIndex = [
   {
     title: "Cache Invalidation and Manual Cache Management",
     keywords: ["invalidateQueries", "getQueryData", "setQueryData", "cache", "invalidate", "optimistic update", "react query"],
-    summary: "client.query.invalidateQueries(collection, type) triggers refetch. getQueryData/setQueryData allow manual optimistic updates.",
+    summary: "query.invalidateQueries(collection, type) triggers refetch. getQueryData/setQueryData allow manual optimistic updates.",
     resourceUri: "docs://sdk/react-query"
   },
   // Filtering
@@ -2805,11 +2956,11 @@ function searchDocs(query, limit = 5) {
 }
 
 // src/tools/sdk-search-docs.ts
-var schema28 = {
-  query: z25.string().min(2).describe('Search keyword or phrase (e.g. "infinite scroll", "webhook", "customer login")'),
-  limit: z25.number().min(1).max(10).default(5).describe("Maximum results to return (1-10, default: 5)")
+var schema30 = {
+  query: z27.string().min(2).describe('Search keyword or phrase (e.g. "infinite scroll", "webhook", "customer login")'),
+  limit: z27.number().min(1).max(10).default(5).describe("Maximum results to return (1-10, default: 5)")
 };
-var metadata28 = {
+var metadata30 = {
   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: {
@@ -2844,9 +2995,9 @@ function handler4({
 }
 
 // src/tools/sdk-get-auth-setup.ts
-import { z as z26 } from "zod";
-var schema29 = {
-  scenario: z26.enum([
+import { z as z28 } from "zod";
+var schema31 = {
+  scenario: z28.enum([
     "browser-client",
     "server-client",
     "customer-auth",
@@ -2855,7 +3006,7 @@ var schema29 = {
     "webhook-verification"
   ]).describe("Authentication scenario")
 };
-var metadata29 = {
+var metadata31 = {
   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: {
@@ -2870,23 +3021,25 @@ var AUTH_GUIDES = {
     title: "Browser Client Setup",
     envVars: ["NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY"],
     code: `import { createClient } from '@01.software/sdk'
+import { createQueryHooks } from '@01.software/sdk/query'
 
 const client = createClient({
   publishableKey: process.env.NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY!
 })
+const query = createQueryHooks(client)
 
 // Read-only operations + React Query hooks + Customer Auth
-const { data } = client.query.useQuery({ collection: 'products' })`,
+const { data } = query.useQuery({ collection: 'products' })`,
     notes: [
       "Client is read-only \u2014 no create/update/delete operations",
       "publishableKey is safe to expose in browser (prefixed with NEXT_PUBLIC_)",
-      "Includes React Query hooks (client.query) and Customer Auth (client.customer)"
+      "Use createQueryHooks(client) for React Query hooks and client.customer for Customer Auth"
     ]
   },
   "server-client": {
     title: "Server Client Setup",
     envVars: ["SOFTWARE_PUBLISHABLE_KEY", "SOFTWARE_SECRET_KEY"],
-    code: `import { createServerClient } from '@01.software/sdk'
+    code: `import { createServerClient } from '@01.software/sdk/server'
 
 const client = createServerClient({
   publishableKey: process.env.SOFTWARE_PUBLISHABLE_KEY!,
@@ -2899,7 +3052,7 @@ const result = await client.collections.from('products').create({ title: 'New Pr
       "ServerClient has full CRUD access and must run only in trusted server code",
       "Store server credentials in environment variables and rotate them from the Console",
       "Use in API routes, server actions, or backend services only",
-      "React Query hooks available for reads (useQuery, prefetchQuery, etc.) + mutations (useCreate, useUpdate, useRemove)"
+      "Use createServerClient in API routes, server actions, or backend services; keep React Query hooks for browser-safe reads and server prefetching"
     ]
   },
   "customer-auth": {
@@ -3009,14 +3162,14 @@ function handler5({
 }
 
 // src/tools/sdk-get-collection-pattern.ts
-import { z as z27 } from "zod";
+import { z as z29 } from "zod";
 import { COLLECTIONS, SERVER_COLLECTIONS as SERVER_COLLECTIONS4 } from "@01.software/sdk";
-var schema30 = {
-  collection: z27.enum(SERVER_COLLECTIONS4).describe("Collection name"),
-  operation: z27.enum(["read", "write", "full-crud"]).default("read").describe("What operations are needed"),
-  surface: z27.enum(["query-builder", "react-query", "server-api"]).default("query-builder").describe("Preferred API surface")
+var schema32 = {
+  collection: z29.enum(SERVER_COLLECTIONS4).describe("Collection name"),
+  operation: z29.enum(["read", "write", "full-crud"]).default("read").describe("What operations are needed"),
+  surface: z29.enum(["query-builder", "react-query", "server-api"]).default("query-builder").describe("Preferred API surface")
 };
-var metadata30 = {
+var metadata32 = {
   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: {
@@ -3037,37 +3190,35 @@ function generatePattern(collection, operation, surface) {
       );
     }
     const parts2 = [];
-    if (operation === "read") {
+    if (operation === "read" || operation === "full-crud") {
       parts2.push(
         `import { createClient } from '@01.software/sdk'`,
-        ``,
-        `const client = createClient({`,
-        `  publishableKey: process.env.NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY!`,
-        `})`,
-        ``
+        `import { createQueryHooks } from '@01.software/sdk/query'`
       );
-    } else {
+    }
+    if (operation === "write" || operation === "full-crud") {
+      parts2.push(`import { createServerClient } from '@01.software/sdk/server'`);
+    }
+    parts2.push(``);
+    if (operation === "read" || operation === "full-crud") {
       parts2.push(
-        `import { createServerClient } from '@01.software/sdk'`,
-        ``,
-        `// Mutation hooks require ServerClient`,
-        `const client = createServerClient({`,
-        `  publishableKey: process.env.SOFTWARE_PUBLISHABLE_KEY!,`,
-        `  secretKey: process.env.SOFTWARE_SECRET_KEY!`,
+        `const client = createClient({`,
+        `  publishableKey: process.env.NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY!`,
         `})`,
+        `const query = createQueryHooks(client)`,
         ``
       );
     }
     if (operation === "read" || operation === "full-crud") {
       parts2.push(
         `// List query`,
-        `const { data, isLoading } = client.query.useQuery({`,
+        `const { data, isLoading } = query.useQuery({`,
         `  collection: '${collection}',`,
         `  options: { limit: 10 }`,
         `})`,
         ``,
         `// Single item`,
-        `const { data: item } = client.query.useQueryById({`,
+        `const { data: item } = query.useQueryById({`,
         `  collection: '${collection}',`,
         `  id: itemId`,
         `})`
@@ -3076,31 +3227,28 @@ function generatePattern(collection, operation, surface) {
     if (operation === "write" || operation === "full-crud") {
       parts2.push(
         ``,
-        `// Create (auto cache invalidation)`,
-        `const { mutate: create } = client.query.useCreate({ collection: '${collection}' })`,
-        `create({ title: 'New Item' })`,
-        ``,
-        `// Update`,
-        `const { mutate: update } = client.query.useUpdate({ collection: '${collection}' })`,
-        `update({ id: itemId, data: { title: 'Updated' } })`,
+        `// Writes belong in a server action or API route, not a client component.`,
+        `const server = createServerClient({`,
+        `  publishableKey: process.env.SOFTWARE_PUBLISHABLE_KEY!,`,
+        `  secretKey: process.env.SOFTWARE_SECRET_KEY!`,
+        `})`,
         ``,
-        `// Delete`,
-        `const { mutate: remove } = client.query.useRemove({ collection: '${collection}' })`,
-        `remove(itemId)`
+        `await server.collections.from('${collection}').create({ title: 'New Item' })`,
+        `await server.collections.from('${collection}').update(itemId, { title: 'Updated' })`,
+        `await server.collections.from('${collection}').remove(itemId)`
       );
     }
     return {
       code: parts2.join("\n"),
       notes: [
-        "React Query hooks provide automatic caching and background updates",
-        "Mutation hooks auto-invalidate related query caches",
-        operation === "write" || operation === "full-crud" ? "Mutation hooks (useCreate, useUpdate, useRemove) require ServerClient with SOFTWARE_PUBLISHABLE_KEY + SOFTWARE_SECRET_KEY" : "Read hooks work in browser components"
+        "React Query hooks provide automatic caching and background updates for browser-safe reads",
+        operation === "write" || operation === "full-crud" ? "Writes require trusted server code with SOFTWARE_PUBLISHABLE_KEY + SOFTWARE_SECRET_KEY; invalidate browser caches after the server action returns" : "Read hooks work in browser components"
       ]
     };
   }
   if (surface === "server-api") {
     const parts2 = [
-      `import { createServerClient } from '@01.software/sdk'`,
+      `import { createServerClient } from '@01.software/sdk/server'`,
       ``,
       `const client = createServerClient({`,
       `  publishableKey: process.env.SOFTWARE_PUBLISHABLE_KEY!,`,
@@ -3217,14 +3365,14 @@ function handler6({
 }
 
 // src/prompts/sdk-usage-guide.ts
-import { z as z28 } from "zod";
-var schema31 = {
-  goal: z28.string().describe('What the user wants to accomplish (e.g., "query product list", "create order")'),
-  runtime: z28.enum(["browser", "server"]).optional().describe("Target runtime: browser (React/Next.js client) or server (Node.js)"),
-  surface: z28.enum(["query-builder", "react-query", "customer-api", "server-api"]).optional().describe("Preferred API surface"),
-  collection: z28.string().optional().describe("Specific collection if relevant")
+import { z as z30 } from "zod";
+var schema33 = {
+  goal: z30.string().describe('What the user wants to accomplish (e.g., "query product list", "create order")'),
+  runtime: z30.enum(["browser", "server"]).optional().describe("Target runtime: browser (React/Next.js client) or server (Node.js)"),
+  surface: z30.enum(["query-builder", "react-query", "customer-api", "server-api"]).optional().describe("Preferred API surface"),
+  collection: z30.string().optional().describe("Specific collection if relevant")
 };
-var metadata31 = {
+var metadata33 = {
   name: "sdk-usage-guide",
   title: "SDK Usage Guide",
   description: "Provides guidance on how to perform a specific task using the 01.software SDK",
@@ -3267,8 +3415,12 @@ const result = await client.collections.from('products').find({
 })
 
 // Use React hooks
+import { createQueryHooks } from '@01.software/sdk/query'
+
+const query = createQueryHooks(client)
+
 function ProductList() {
-  const { data, isLoading } = client.query.useQuery({
+  const { data, isLoading } = query.useQuery({
     collection: 'products',
     options: { limit: 10 }
   })
@@ -3285,7 +3437,7 @@ function ProductList() {
 }
 \`\`\`
 
-### React Query Hooks (client.query)
+### React Query Hooks (@01.software/sdk/query)
 
 | Hook | Description |
 |------|-------------|
@@ -3320,13 +3472,17 @@ await client.collections.from('products').remove('id')
 // count() returns { totalDocs }
 const { totalDocs } = await client.collections.from('products').count()
 
-// Metadata - generate Next.js Metadata from collection fields
-// Auto-maps per-collection fields (e.g. articles: description\u2192description, thumbnail\u2192image)
-const articleMeta = await client.collections.from('articles').findMetadataById(id, { siteName: 'My Blog' })
-const productMeta = await client.collections.from('products').findMetadata(
-  { where: { slug: { equals: 'my-product' } } },
-  { siteName: 'My Store' }
-)
+// Metadata - generate Metadata-shaped SEO objects from fetched documents
+import { extractSeo, generateMetadata } from '@01.software/sdk/metadata'
+
+const productResult = await client.collections.from('products').find({
+  where: { slug: { equals: 'my-product' } },
+  limit: 1,
+  depth: 1,
+})
+const productMeta = productResult.docs[0]
+  ? generateMetadata(extractSeo(productResult.docs[0]), { siteName: 'My Store' })
+  : null
 \`\`\`
 
 ### Filtering (Payload Query Syntax)
@@ -3349,7 +3505,7 @@ For ecommerce collections, use \`products.listing.*\` for browse/search pricing
 ### Server Client (Server-side)
 
 \`\`\`typescript
-import { createServerClient } from '@01.software/sdk'
+import { createServerClient } from '@01.software/sdk/server'
 
 const client = createServerClient({
   publishableKey: process.env.SOFTWARE_PUBLISHABLE_KEY!,
@@ -3357,18 +3513,44 @@ const client = createServerClient({
 })
 \`\`\`
 
-You can perform the "${goal}" task by following the patterns above.`;
+You can perform the "${goal}" task by following the patterns above.
+
+## Common recipes
+
+### Product detail page (slug-based)
+
+\`\`\`typescript
+const product = await client.commerce.product.detail({ slug })
+if (!product) return notFound()
+// product: { product, variants, options, brand, categories, tags, images, videos, listing }
+\`\`\`
+
+For React: \`const { data } = createQueryHooks(client).useProductDetailBySlug(slug)\`.
+
+### Product listing (grouped)
+
+\`\`\`typescript
+const { docs } = await client.commerce.product.listingGroups({ productIds })
+\`\`\`
+
+### Stock check before adding to cart
+
+\`\`\`typescript
+const { allAvailable } = await client.commerce.product.stockCheck({
+  items: [{ variantId, quantity }],
+})
+\`\`\``;
 }
 
 // src/prompts/collection-query-help.ts
-import { z as z29 } from "zod";
+import { z as z31 } from "zod";
 import { COLLECTIONS as COLLECTIONS2, SERVER_COLLECTIONS as SERVER_COLLECTIONS5 } from "@01.software/sdk";
-var schema32 = {
-  collection: z29.enum(SERVER_COLLECTIONS5).describe("Collection name"),
-  operation: z29.enum(["find", "create", "update", "delete"]).describe("Operation to perform (find, create, update, delete)"),
-  filters: z29.string().optional().describe("Filter conditions (JSON string, optional)")
+var schema34 = {
+  collection: z31.enum(SERVER_COLLECTIONS5).describe("Collection name"),
+  operation: z31.enum(["find", "create", "update", "delete"]).describe("Operation to perform (find, create, update, delete)"),
+  filters: z31.string().optional().describe("Filter conditions (JSON string, optional)")
 };
-var metadata32 = {
+var metadata34 = {
   name: "collection-query-help",
   title: "Collection Query Help",
   description: "Provides guidance on how to write queries for a specific collection",
@@ -3398,7 +3580,8 @@ ${filters}
 ### ${operation === "find" ? "Query" : operation === "create" ? "Create" : operation === "update" ? "Update" : "Delete"} Example
 
 \`\`\`typescript
-import { createClient, createServerClient } from '@01.software/sdk'
+import { createClient } from '@01.software/sdk'
+import { createServerClient } from '@01.software/sdk/server'
 
 // Client (read-only public collections)
 const client = createClient({
@@ -3419,14 +3602,18 @@ const result = await ${readClientName}.collections.from('${collection}').find(${
 // result.docs - array of items
 // result.totalDocs, result.page, result.totalPages, result.hasNextPage, ...
 
-${isPublicCollection ? `// Using React Hook
-const { data, isLoading, error } = client.query.useQuery({
+${isPublicCollection ? `// Using React Query hooks
+import { createQueryHooks } from '@01.software/sdk/query'
+
+const query = createQueryHooks(client)
+
+const { data, isLoading, error } = query.useQuery({
   collection: '${collection}',
   options: { limit: 10 }
 })
 
 // With Suspense
-const { data } = client.query.useSuspenseQuery({
+const { data } = query.useSuspenseQuery({
   collection: '${collection}',
   options: { limit: 10 }
 })` : `// React hooks are browser/public only and do not support '${collection}'.`}` : operation === "create" ? `// Create ${collection} item (ServerClient only)
@@ -3460,16 +3647,16 @@ ${operation === "find" ? `- Use \`where\` option for filtering (Payload query sy
 }
 
 // src/prompts/order-flow-guide.ts
-import { z as z30 } from "zod";
-var schema33 = {
-  scenario: z30.enum([
+import { z as z32 } from "zod";
+var schema35 = {
+  scenario: z32.enum([
     "simple-order",
     "cart-checkout",
     "return-refund",
     "fulfillment-tracking"
   ]).describe("Order flow scenario")
 };
-var metadata33 = {
+var metadata35 = {
   name: "order-flow-guide",
   title: "Order Flow Guide",
   description: "Provides step-by-step guidance for ecommerce order flows including creation, checkout, returns, and fulfillment.",
@@ -3495,7 +3682,7 @@ var SCENARIOS = {
 
 ### Code Example (ServerClient)
 \`\`\`typescript
-import { createServerClient } from '@01.software/sdk'
+import { createServerClient } from '@01.software/sdk/server'
 
 const client = createServerClient({
   publishableKey: process.env.SOFTWARE_PUBLISHABLE_KEY!,
@@ -3654,9 +3841,9 @@ ${SCENARIOS[scenario] || "Unknown scenario."}
 }
 
 // src/prompts/feature-setup-guide.ts
-import { z as z31 } from "zod";
-var schema34 = {
-  feature: z31.enum([
+import { z as z33 } from "zod";
+var schema36 = {
+  feature: z33.enum([
     "ecommerce",
     "customers",
     "articles",
@@ -3671,7 +3858,7 @@ var schema34 = {
     "community"
   ]).describe("Feature to get setup guide for")
 };
-var metadata34 = {
+var metadata36 = {
   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.",
@@ -3878,7 +4065,7 @@ ${FEATURES[feature] || "Unknown feature."}
 }
 
 // src/resources/(config)/app.ts
-var metadata35 = {
+var metadata37 = {
   name: "app-config",
   title: "Application Config",
   description: "01.software SDK and MCP server configuration information"
@@ -3944,7 +4131,7 @@ Rate limits depend on your tenant plan:
 
 // src/resources/(collections)/schema.ts
 import { COLLECTIONS as COLLECTIONS3 } from "@01.software/sdk";
-var metadata36 = {
+var metadata38 = {
   name: "collections-schema",
   title: "Collection Schema Info",
   description: "Available collections and their schema information"
@@ -3968,7 +4155,12 @@ var COLLECTIONS_BY_CATEGORY = {
     "fulfillments",
     "fulfillment-items"
   ],
-  "Shipping & Returns": ["returns", "return-items", "shipping-policies"],
+  "Shipping & Returns": [
+    "returns",
+    "return-items",
+    "shipping-policies",
+    "shipping-zones"
+  ],
   Customers: [
     "customers",
     "customer-profiles",
@@ -3976,7 +4168,7 @@ var COLLECTIONS_BY_CATEGORY = {
     "customer-addresses"
   ],
   Carts: ["carts", "cart-items"],
-  "Discounts & Promotions": ["discounts", "promotions"],
+  Discounts: ["discounts"],
   Documents: ["documents", "document-categories", "document-types"],
   Articles: [
     "articles",
@@ -3990,9 +4182,7 @@ var COLLECTIONS_BY_CATEGORY = {
     "reactions",
     "reaction-types",
     "bookmarks",
-    "post-categories",
-    "reports",
-    "community-bans"
+    "post-categories"
   ],
   Playlists: [
     "playlists",
@@ -4082,7 +4272,7 @@ Total available collections: ${COLLECTIONS3.length}`;
 }
 
 // src/resources/(docs)/getting-started.ts
-var metadata37 = {
+var metadata39 = {
   name: "docs-getting-started",
   title: "Getting Started",
   description: "01.software SDK getting started guide"
@@ -4102,6 +4292,22 @@ yarn add @01.software/sdk
 pnpm add @01.software/sdk
 \`\`\`
 
+## Optional peers
+
+You do not need extra packages for the root SDK entry. Install peer
+dependencies only when you import a feature sub-path:
+
+- \`@01.software/sdk/query\` -> \`@tanstack/react-query\`, \`react\`, \`react-dom\`
+- \`@01.software/sdk/realtime\` -> \`@tanstack/react-query\`
+- \`@01.software/sdk/analytics/react\` -> \`react\`, \`react-dom\`
+- \`@01.software/sdk/ui/rich-text\` -> \`@payloadcms/richtext-lexical\`
+- \`@01.software/sdk/ui/form\` -> none
+- \`@01.software/sdk/ui/code-block\` -> \`shiki\`, \`hast-util-to-jsx-runtime\`
+- \`@01.software/sdk/ui/canvas\` -> \`@tanstack/react-query\`, \`@xyflow/react\`, \`quickjs-emscripten\`, \`postcss\`, \`sucrase\`
+- \`@01.software/sdk/ui/canvas/server\` -> none
+- \`@01.software/sdk/ui/video\` -> \`@mux/mux-player-react\`
+- \`@01.software/sdk/ui/image\` -> none
+
 ## Basic Usage
 
 \`\`\`typescript
@@ -4127,7 +4333,7 @@ const result = await client.collections.from('products').find({
 }
 
 // src/resources/(docs)/guides.ts
-var metadata38 = {
+var metadata40 = {
   name: "docs-guides",
   title: "Guides",
   description: "01.software SDK usage guides"
@@ -4139,7 +4345,7 @@ Comprehensive guides to master the 01.software SDK.
 
 ## Data Fetching
 
-Use the Query Builder or React Query hooks to fetch data efficiently.
+Use the Query Builder or opt-in React Query hooks to fetch data efficiently.
 
 ### Query Builder
 \`\`\`typescript
@@ -4167,7 +4373,10 @@ const { totalDocs } = await client.collections.from('products').count()
 
 ### React Query Hook
 \`\`\`typescript
-const { data, isLoading, error } = client.query.useQuery({
+import { createQueryHooks } from '@01.software/sdk/query'
+
+const query = createQueryHooks(client)
+const { data, isLoading, error } = query.useQuery({
   collection: 'products',
   options: {
     where: { status: { equals: 'published' } },
@@ -4178,7 +4387,7 @@ const { data, isLoading, error } = client.query.useQuery({
 
 ### Suspense Mode
 \`\`\`typescript
-const { data } = client.query.useSuspenseQuery({
+const { data } = query.useSuspenseQuery({
   collection: 'products',
   options: { limit: 10 }
 })
@@ -4187,7 +4396,7 @@ const { data } = client.query.useSuspenseQuery({
 ### Infinite Scroll
 \`\`\`typescript
 const { data, fetchNextPage, hasNextPage, isFetchingNextPage } =
-  client.query.useInfiniteQuery({
+  query.useInfiniteQuery({
     collection: 'products',
     pageSize: 20
   })
@@ -4234,19 +4443,18 @@ const result = await serverClient.from('products').removeMany(
 )
 \`\`\`
 
-### Mutation Hooks (React)
+### Server Mutations
 \`\`\`typescript
-// Create with auto cache invalidation
-const { mutate: create } = client.query.useCreate({ collection: 'products' })
-create({ title: 'New', status: 'draft' })
+import { createServerClient } from '@01.software/sdk/server'
 
-// Update with auto cache invalidation
-const { mutate: update } = client.query.useUpdate({ collection: 'products' })
-update({ id: 'product-id', data: { title: 'Updated' } })
+const server = createServerClient({
+  publishableKey: process.env.SOFTWARE_PUBLISHABLE_KEY!,
+  secretKey: process.env.SOFTWARE_SECRET_KEY!,
+})
 
-// Remove with auto cache invalidation
-const { mutate: remove } = client.query.useRemove({ collection: 'products' })
-remove('product-id')
+await server.collections.from('products').create({ title: 'New', status: 'draft' })
+await server.collections.from('products').update('product-id', { title: 'Updated' })
+await server.collections.from('products').remove('product-id')
 \`\`\`
 
 ## Caching Strategies
@@ -4256,17 +4464,17 @@ The SDK uses React Query for caching and background updates.
 ### SSR Prefetching
 \`\`\`typescript
 // Prefetch in server component for instant client hydration
-await client.query.prefetchQuery({
+await query.prefetchQuery({
   collection: 'products',
   options: { limit: 10 }
 })
 
-await client.query.prefetchQueryById({
+await query.prefetchQueryById({
   collection: 'products',
   id: 'product-id'
 })
 
-await client.query.prefetchInfiniteQuery({
+await query.prefetchInfiniteQuery({
   collection: 'products',
   pageSize: 20
 })
@@ -4275,19 +4483,19 @@ await client.query.prefetchInfiniteQuery({
 ### Cache Invalidation
 \`\`\`typescript
 // Invalidate list cache for a collection
-client.query.invalidateQueries('products', 'list')
+query.invalidateQueries('products', 'list')
 
 // Invalidate all caches for a collection
-client.query.invalidateQueries('products')
+query.invalidateQueries('products')
 \`\`\`
 
 ### Manual Cache Management
 \`\`\`typescript
 // Read cached data
-const cached = client.query.getQueryData('products', 'list')
+const cached = query.getQueryData('products', 'list')
 
 // Write to cache (optimistic updates)
-client.query.setQueryData('products', 'list', newData)
+query.setQueryData('products', 'list', newData)
 \`\`\`
 
 ## Error Handling
@@ -4338,7 +4546,7 @@ For more implementation guidance, see the [SDK Guide](/developers/sdk).`;
 }
 
 // src/resources/(docs)/api.ts
-var metadata39 = {
+var metadata41 = {
   name: "docs-api",
   title: "API Reference",
   description: "01.software SDK API reference documentation"
@@ -4365,7 +4573,7 @@ const client = createClient({
 For server-side operations (full CRUD)
 
 \`\`\`typescript
-import { createServerClient } from '@01.software/sdk'
+import { createServerClient } from '@01.software/sdk/server'
 
 const client = createServerClient({
   publishableKey: string,
@@ -4444,13 +4652,19 @@ const result = await client.collections.from('collection').removeMany(where)
 // Returns PayloadFindResponse with deleted docs
 \`\`\`
 
-## React Query Hooks (client.query)
+## React Query Hooks (\`@01.software/sdk/query\`)
+
+\`\`\`typescript
+import { createQueryHooks } from '@01.software/sdk/query'
+
+const query = createQueryHooks(client)
+\`\`\`
 
 ### useQuery()
 Query a collection list.
 
 \`\`\`typescript
-const { data, isLoading, error } = client.query.useQuery({
+const { data, isLoading, error } = query.useQuery({
   collection: 'products',
   options: { limit: 10, where: { status: { equals: 'published' } } }
 })
@@ -4460,7 +4674,7 @@ const { data, isLoading, error } = client.query.useQuery({
 Suspense mode list query.
 
 \`\`\`typescript
-const { data } = client.query.useSuspenseQuery({
+const { data } = query.useSuspenseQuery({
   collection: 'products',
   options: { limit: 10 }
 })
@@ -4470,7 +4684,7 @@ const { data } = client.query.useSuspenseQuery({
 Get a single item by ID.
 
 \`\`\`typescript
-const { data } = client.query.useQueryById({
+const { data } = query.useQueryById({
   collection: 'products',
   id: 'product-id'
 })
@@ -4480,7 +4694,7 @@ const { data } = client.query.useQueryById({
 Suspense mode single item query.
 
 \`\`\`typescript
-const { data } = client.query.useSuspenseQueryById({
+const { data } = query.useSuspenseQueryById({
   collection: 'products',
   id: 'product-id'
 })
@@ -4490,7 +4704,7 @@ const { data } = client.query.useSuspenseQueryById({
 Infinite scroll.
 
 \`\`\`typescript
-const { data, fetchNextPage, hasNextPage } = client.query.useInfiniteQuery({
+const { data, fetchNextPage, hasNextPage } = query.useInfiniteQuery({
   collection: 'products',
   options: { limit: 20 },
   pageSize: 20
@@ -4501,52 +4715,43 @@ const { data, fetchNextPage, hasNextPage } = client.query.useInfiniteQuery({
 Suspense mode infinite scroll.
 
 \`\`\`typescript
-const { data, fetchNextPage } = client.query.useSuspenseInfiniteQuery({
+const { data, fetchNextPage } = query.useSuspenseInfiniteQuery({
   collection: 'products',
   pageSize: 20
 })
 \`\`\`
 
-## Mutation Hooks (client.query)
+## Server Mutations
 
-### useCreate()
-Create a document with automatic cache invalidation.
+Writes require trusted server code with \`createServerClient\`; do not run server credentials in React client components.
 
 \`\`\`typescript
-const { mutate } = client.query.useCreate({ collection: 'products' })
-mutate({ title: 'New Product', status: 'draft' })
-\`\`\`
+import { createServerClient } from '@01.software/sdk/server'
 
-### useUpdate()
-Update a document with automatic cache invalidation.
-
-\`\`\`typescript
-const { mutate } = client.query.useUpdate({ collection: 'products' })
-mutate({ id: 'product-id', data: { title: 'Updated' } })
-\`\`\`
-
-### useRemove()
-Remove a document with automatic cache invalidation.
+const server = createServerClient({
+  publishableKey: process.env.SOFTWARE_PUBLISHABLE_KEY!,
+  secretKey: process.env.SOFTWARE_SECRET_KEY!,
+})
 
-\`\`\`typescript
-const { mutate } = client.query.useRemove({ collection: 'products' })
-mutate('product-id')
+await server.collections.from('products').create({ title: 'New Product', status: 'draft' })
+await server.collections.from('products').update('product-id', { title: 'Updated' })
+await server.collections.from('products').remove('product-id')
 \`\`\`
 
 ## Cache Utilities
 
 \`\`\`typescript
 // Invalidate cache
-client.query.invalidateQueries('products', 'list')
+query.invalidateQueries('products', 'list')
 
 // SSR prefetch
-await client.query.prefetchQuery({ collection: 'products', options: { limit: 10 } })
-await client.query.prefetchQueryById({ collection: 'products', id: 'id' })
-await client.query.prefetchInfiniteQuery({ collection: 'products', pageSize: 20 })
+await query.prefetchQuery({ collection: 'products', options: { limit: 10 } })
+await query.prefetchQueryById({ collection: 'products', id: 'id' })
+await query.prefetchInfiniteQuery({ collection: 'products', pageSize: 20 })
 
 // Get/set cached data
-const cached = client.query.getQueryData('products', 'list')
-client.query.setQueryData('products', 'list', newData)
+const cached = query.getQueryData('products', 'list')
+query.setQueryData('products', 'list', newData)
 \`\`\`
 
 For ecommerce reads, prefer \`products.listing.*\` for card/search pricing and keep authoritative sellable pricing on \`product-variants.price\`.
@@ -4624,7 +4829,7 @@ For more details, see the [API documentation](/developers/api).`;
 }
 
 // src/resources/(docs)/query-builder.ts
-var metadata40 = {
+var metadata42 = {
   name: "docs-query-builder",
   title: "Query Builder",
   description: "01.software SDK Query Builder API reference (client.collections.from)"
@@ -4793,7 +4998,7 @@ const result3 = await client.collections.from('products').find({ sort: '-isFeatu
 ## Full Example
 
 \`\`\`typescript
-import { createServerClient } from '@01.software/sdk'
+import { createServerClient } from '@01.software/sdk/server'
 
 const serverClient = createServerClient({
   publishableKey: process.env.SOFTWARE_PUBLISHABLE_KEY!,
@@ -4818,17 +5023,25 @@ console.log(result.hasNextPage) // true
 }
 
 // src/resources/(docs)/react-query.ts
-var metadata41 = {
+var metadata43 = {
   name: "docs-react-query",
   title: "React Query Hooks",
-  description: "01.software SDK React Query hooks reference (client.query)"
+  description: "01.software SDK React Query hooks reference (@01.software/sdk/query)"
 };
 function handler13() {
   return `# React Query Hooks
 
-React Query hooks are available on the browser-side \`Client\` via \`client.query\`. They provide automatic caching, background refetching, and cache invalidation.
+React Query hooks are opt-in through \`@01.software/sdk/query\`. They provide automatic caching, background refetching, and cache invalidation without making root \`createClient\` consumers install React Query.
+
+Install \`@tanstack/react-query\` and React peers only when importing this sub-path.
+
+\`\`\`typescript
+import { createClient } from '@01.software/sdk'
+import { createQueryHooks } from '@01.software/sdk/query'
 
-> React Query hooks are available on \`Client\` (createClient) only. \`ServerClient\` does not include them.
+const client = createClient({ publishableKey })
+const query = createQueryHooks(client)
+\`\`\`
 
 ## Query Hooks
 
@@ -4836,7 +5049,7 @@ React Query hooks are available on the browser-side \`Client\` via \`client.quer
 Query a collection list with automatic caching.
 
 \`\`\`typescript
-const { data, isLoading, error } = client.query.useQuery({
+const { data, isLoading, error } = query.useQuery({
   collection: 'products',
   options: {
     where: { status: { equals: 'published' } },
@@ -4854,7 +5067,7 @@ Suspense-mode list query. Throws a promise while loading (use with React Suspens
 
 \`\`\`typescript
 // Inside a Suspense boundary
-const { data } = client.query.useSuspenseQuery({
+const { data } = query.useSuspenseQuery({
   collection: 'products',
   options: { limit: 10 },
 })
@@ -4865,7 +5078,7 @@ const { data } = client.query.useSuspenseQuery({
 Get a single document by ID.
 
 \`\`\`typescript
-const { data, isLoading } = client.query.useQueryById({
+const { data, isLoading } = query.useQueryById({
   collection: 'products',
   id: 'product-id',
 })
@@ -4876,7 +5089,7 @@ const { data, isLoading } = client.query.useQueryById({
 Suspense-mode single document query.
 
 \`\`\`typescript
-const { data } = client.query.useSuspenseQueryById({
+const { data } = query.useSuspenseQueryById({
   collection: 'products',
   id: 'product-id',
 })
@@ -4892,7 +5105,7 @@ const {
   fetchNextPage,
   hasNextPage,
   isFetchingNextPage,
-} = client.query.useInfiniteQuery({
+} = query.useInfiniteQuery({
   collection: 'products',
   options: {
     where: { status: { equals: 'published' } },
@@ -4908,55 +5121,33 @@ const {
 Suspense-mode infinite scroll.
 
 \`\`\`typescript
-const { data, fetchNextPage, hasNextPage } = client.query.useSuspenseInfiniteQuery({
+const { data, fetchNextPage, hasNextPage } = query.useSuspenseInfiniteQuery({
   collection: 'products',
   pageSize: 20,
 })
 \`\`\`
 
-## Mutation Hooks
+## Writes
 
-Mutation hooks automatically invalidate relevant cache keys after success.
-
-### useCreate()
-Create a document and invalidate list cache.
+Keep writes in trusted server code. Use a server action, API route, or backend service with \`createServerClient\`, then invalidate browser React Query caches after the action completes.
 
 \`\`\`typescript
-const { mutate, mutateAsync, isPending } = client.query.useCreate({
-  collection: 'products',
-})
-
-// Fire and forget
-mutate({ title: 'New Product', status: 'draft' })
-
-// Await result
-const result = await mutateAsync({ title: 'New Product', status: 'draft' })
-// result.doc - created document
-\`\`\`
-
-For ecommerce reads, price-oriented product cards should consume \`products.listing.minPrice/maxPrice\`. Authoritative sellable pricing still lives on \`product-variants.price\`.
+// app/products/actions.ts
+'use server'
 
-### useUpdate()
-Update a document and invalidate list + detail cache.
+import { createServerClient } from '@01.software/sdk/server'
 
-\`\`\`typescript
-const { mutate, mutateAsync } = client.query.useUpdate({
-  collection: 'products',
+const server = createServerClient({
+  publishableKey: process.env.SOFTWARE_PUBLISHABLE_KEY!,
+  secretKey: process.env.SOFTWARE_SECRET_KEY!,
 })
 
-mutate({ id: 'product-id', data: { title: 'Updated Title' } })
+export async function createProduct(data: { title: string; status: 'draft' | 'published' }) {
+  return server.collections.from('products').create(data)
+}
 \`\`\`
 
-### useRemove()
-Remove a document and invalidate list cache.
-
-\`\`\`typescript
-const { mutate, mutateAsync } = client.query.useRemove({
-  collection: 'products',
-})
-
-mutate('product-id')
-\`\`\`
+For ecommerce reads, price-oriented product cards should consume \`products.listing.minPrice/maxPrice\`. Authoritative sellable pricing still lives on \`product-variants.price\`.
 
 ## Cache Utilities
 
@@ -4965,10 +5156,10 @@ Manually invalidate cached queries for a collection.
 
 \`\`\`typescript
 // Invalidate all list queries for a collection
-client.query.invalidateQueries('products', 'list')
+query.invalidateQueries('products', 'list')
 
 // Invalidate all queries for a collection (list + detail)
-client.query.invalidateQueries('products')
+query.invalidateQueries('products')
 \`\`\`
 
 ### getQueryData() / setQueryData()
@@ -4976,10 +5167,10 @@ Read and write the React Query cache directly.
 
 \`\`\`typescript
 // Read cached data
-const cached = client.query.getQueryData('products', 'list')
+const cached = query.getQueryData('products', 'list')
 
 // Write to cache (useful for optimistic updates)
-client.query.setQueryData('products', 'list', newData)
+query.setQueryData('products', 'list', newData)
 \`\`\`
 
 ## SSR Prefetching
@@ -4989,34 +5180,37 @@ Prefetch data in server components for instant hydration on the client.
 \`\`\`typescript
 // app/products/page.tsx (Next.js App Router Server Component)
 import { HydrationBoundary, dehydrate } from '@tanstack/react-query'
-import { createServerClient } from '@01.software/sdk'
+import { createServerClient } from '@01.software/sdk/server'
+import { createServerQueryHooks, getQueryClient } from '@01.software/sdk/query'
 
 export default async function ProductsPage() {
   const serverClient = createServerClient({
     publishableKey: process.env.SOFTWARE_PUBLISHABLE_KEY!,
     secretKey: process.env.SOFTWARE_SECRET_KEY!,
   })
+  const queryClient = getQueryClient()
+  const serverQuery = createServerQueryHooks(serverClient, queryClient)
 
   // Prefetch list
-  await serverClient.query.prefetchQuery({
+  await serverQuery.prefetchQuery({
     collection: 'products',
     options: { limit: 20, where: { status: { equals: 'published' } } },
   })
 
   // Prefetch single item
-  await serverClient.query.prefetchQueryById({
+  await serverQuery.prefetchQueryById({
     collection: 'products',
     id: 'product-id',
   })
 
   // Prefetch infinite query
-  await serverClient.query.prefetchInfiniteQuery({
+  await serverQuery.prefetchInfiniteQuery({
     collection: 'products',
     pageSize: 20,
   })
 
   return (
-    <HydrationBoundary state={dehydrate(serverClient.query.queryClient)}>
+    <HydrationBoundary state={dehydrate(queryClient)}>
       <ProductList />
     </HydrationBoundary>
   )
@@ -5029,13 +5223,15 @@ export default async function ProductsPage() {
 'use client'
 
 import { createClient } from '@01.software/sdk'
+import { createQueryHooks } from '@01.software/sdk/query'
 
 const client = createClient({
   publishableKey: process.env.NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY!,
 })
+const query = createQueryHooks(client)
 
 export function ProductList() {
-  const { data, isLoading, error } = client.query.useQuery({
+  const { data, isLoading, error } = query.useQuery({
     collection: 'products',
     options: {
       where: { status: { equals: 'published' } },
@@ -5044,20 +5240,13 @@ export function ProductList() {
     },
   })
 
-  const { mutate: removeProduct } = client.query.useRemove({
-    collection: 'products',
-  })
-
   if (isLoading) return <div>Loading...</div>
   if (error) return <div>Error: {error.message}</div>
 
   return (
     <ul>
       {data?.docs.map((product) => (
-        <li key={product.id}>
-          {product.title}
-          <button onClick={() => removeProduct(product.id)}>Delete</button>
-        </li>
+        <li key={product.id}>{product.title}</li>
       ))}
     </ul>
   )
@@ -5066,7 +5255,7 @@ export function ProductList() {
 }
 
 // src/resources/(docs)/server-api.ts
-var metadata42 = {
+var metadata44 = {
   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"
@@ -5077,7 +5266,7 @@ function handler14() {
 Server-side operations are available via \`client.commerce\` on \`ServerClient\`. Use \`createServerClient\` with both \`publishableKey\` and \`secretKey\`.
 
 \`\`\`typescript
-import { createServerClient } from '@01.software/sdk'
+import { createServerClient } from '@01.software/sdk/server'
 
 const client = createServerClient({
   publishableKey: process.env.SOFTWARE_PUBLISHABLE_KEY!,
@@ -5328,7 +5517,7 @@ const result = await client.commerce.shipping.calculate({
 }
 
 // src/resources/(docs)/customer-auth.ts
-var metadata43 = {
+var metadata45 = {
   name: "docs-customer-auth",
   title: "Customer Auth API",
   description: "01.software SDK Customer Auth API reference (client.customer)"
@@ -5506,7 +5695,7 @@ async function loadProfile() {
 }
 
 // src/resources/(docs)/browser-vs-server.ts
-var metadata44 = {
+var metadata46 = {
   name: "docs-browser-vs-server",
   title: "Client vs ServerClient",
   description: "When to use Client (createClient) vs ServerClient (createServerClient) in the 01.software SDK"
@@ -5526,9 +5715,9 @@ The SDK provides two client types for different execution environments.
 | Read (\`find\`, \`findById\`, \`count\`) | Yes | Yes |
 | Write (\`create\`, \`update\`, \`remove\`) | No | Yes |
 | Bulk (\`updateMany\`, \`removeMany\`) | No | Yes |
-| React Query hooks (\`client.query\`) | Yes | Yes (SSR prefetch) |
+| React Query hooks (\`@01.software/sdk/query\`) | Yes | Yes (SSR prefetch) |
 | Customer auth (\`client.customer\`) | Yes | No |
-| Server API (\`client.api\`) | No | Yes |
+| Commerce/server APIs (\`server.commerce\`, server CRUD) | No | Yes |
 
 ## Client (createClient)
 
@@ -5536,16 +5725,18 @@ Use in browser code, React client components, and anywhere the secret key must n
 
 \`\`\`typescript
 import { createClient } from '@01.software/sdk'
+import { createQueryHooks } from '@01.software/sdk/query'
 
 const client = createClient({
   publishableKey: process.env.NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY!,
 })
+const query = createQueryHooks(client)
 
 // Read data
 const products = await client.collections.from('products').find({ limit: 10 })
 
 // React Query hooks
-const { data } = client.query.useQuery({ collection: 'products' })
+const { data } = query.useQuery({ collection: 'products' })
 
 // Customer auth
 await client.customer.login({ email, password })
@@ -5558,7 +5749,7 @@ await client.customer.login({ email, password })
 Use in server components, API routes, server actions, and background jobs. Has full CRUD access.
 
 \`\`\`typescript
-import { createServerClient } from '@01.software/sdk'
+import { createServerClient } from '@01.software/sdk/server'
 
 const client = createServerClient({
   publishableKey: process.env.SOFTWARE_PUBLISHABLE_KEY!,
@@ -5579,11 +5770,14 @@ await client.collections.from('product-variants').create({
 })
 await client.collections.from('products').remove('product-id')
 
-// Server API (orders, carts, etc.)
+// Commerce API (orders, carts, etc.)
 await client.commerce.orders.create({ ... })
 await client.commerce.orders.checkout({ ... })
 \`\`\`
 
+Server-only code must import \`createServerClient\` from the \`/server\`
+sub-path.
+
 **Environment variables**:
 - \`SOFTWARE_PUBLISHABLE_KEY\` \u2014 publishable key (no NEXT_PUBLIC prefix, server-only)
 - \`SOFTWARE_SECRET_KEY\` \u2014 server credential
@@ -5613,7 +5807,7 @@ deploying again.
 
 \`\`\`typescript
 // lib/sdk.ts \u2014 server-only module
-import { createServerClient } from '@01.software/sdk'
+import { createServerClient } from '@01.software/sdk/server'
 
 export function getServerClient() {
   return createServerClient({
@@ -5626,10 +5820,12 @@ export function getServerClient() {
 \`\`\`typescript
 // lib/sdk-client.ts \u2014 browser-safe module
 import { createClient } from '@01.software/sdk'
+import { createQueryHooks } from '@01.software/sdk/query'
 
 export const browserClient = createClient({
   publishableKey: process.env.NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY!,
 })
+export const browserQuery = createQueryHooks(browserClient)
 \`\`\`
 
 \`\`\`typescript
@@ -5646,10 +5842,10 @@ export default async function ProductsPage() {
 \`\`\`typescript
 // components/product-list.tsx \u2014 Client Component
 'use client'
-import { browserClient } from '@/lib/sdk-client'
+import { browserQuery } from '@/lib/sdk-client'
 
 export function ProductList() {
-  const { data } = browserClient.query.useQuery({ collection: 'products' })
+  const { data } = browserQuery.useQuery({ collection: 'products' })
   return <ul>{data?.docs.map(p => <li key={p.id}>{p.title}</li>)}</ul>
 }
 \`\`\`
@@ -5665,7 +5861,7 @@ export function ProductList() {
 }
 
 // src/resources/(docs)/file-upload.ts
-var metadata45 = {
+var metadata47 = {
   name: "docs-file-upload",
   title: "File Upload",
   description: "01.software SDK file upload patterns using the images collection"
@@ -5680,7 +5876,7 @@ Upload files using the \`images\` collection (tenant-scoped, unified image store
 Use \`ServerClient\` with \`FormData\` to upload images server-side.
 
 \`\`\`typescript
-import { createServerClient } from '@01.software/sdk'
+import { createServerClient } from '@01.software/sdk/server'
 
 const client = createServerClient({
   publishableKey: process.env.SOFTWARE_PUBLISHABLE_KEY!,
@@ -5703,7 +5899,7 @@ async function uploadImage(file: File) {
 \`\`\`typescript
 // app/api/upload/route.ts
 import { NextRequest, NextResponse } from 'next/server'
-import { createServerClient } from '@01.software/sdk'
+import { createServerClient } from '@01.software/sdk/server'
 
 const client = createServerClient({
   publishableKey: process.env.SOFTWARE_PUBLISHABLE_KEY!,
@@ -5733,7 +5929,7 @@ export async function POST(req: NextRequest) {
 // actions/upload.ts
 'use server'
 
-import { createServerClient } from '@01.software/sdk'
+import { createServerClient } from '@01.software/sdk/server'
 
 const client = createServerClient({
   publishableKey: process.env.SOFTWARE_PUBLISHABLE_KEY!,
@@ -5816,7 +6012,7 @@ The platform stores files in Cloudflare R2 and serves via CDN (\`cdn.01.software
 }
 
 // src/resources/(docs)/webhook.ts
-var metadata46 = {
+var metadata48 = {
   name: "docs-webhook",
   title: "Webhooks",
   description: "01.software SDK webhook verification and event handling"
@@ -5929,9 +6125,100 @@ Failed webhook deliveries are queued with automatic retries. Ensure your handler
 Configure webhook URLs in the 01.software console under Tenant Settings > Webhooks. Multiple URLs can be registered; all receive every event.`;
 }
 
+// src/resources/(docs)/product-detail.ts
+var metadata49 = {
+  name: "docs-product-detail",
+  title: "Product Detail Helper",
+  description: "01.software SDK commerce.product.detail helper guide"
+};
+function handler19() {
+  return `# Product Detail Helper
+
+## When to use the helper vs the raw query builder
+
+Use \`client.commerce.product.detail({ slug | id })\` when you need a full product detail page payload in one call. The helper folds the Payload query, access policy, and response shaping (variants, options, option value slugs/media, brand, categories, tags, images, videos, listing rollup) into a single call.
+
+Use \`client.collections.from('products').find(...)\` (escape hatch) when you need bulk reads, custom filter combinations, or fields outside the helper response shape.
+
+## Single-call example
+
+\`\`\`typescript
+import { createClient, resolveProductSelection } from '@01.software/sdk'
+
+const client = createClient({
+  publishableKey: process.env.NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY!,
+})
+
+const detail = await client.commerce.product.detail({ slug: 'my-product' })
+if (!detail) return notFound()
+const selection = resolveProductSelection(detail, {
+  search: '?opt.option-color=color-black',
+})
+// selection.selectedVariant, selection.price, selection.stock, selection.media
+\`\`\`
+
+## URL round-trip
+
+Use the SDK codec for canonical selection URLs. Complete selections use
+\`variant=<variantId>\`; partial selections use
+\`opt.<optionId>=<valueId>\`. Older
+\`opt.<optionSlug>=<valueSlug>\` URLs still decode during Stage 1, but slugs are
+compatibility metadata rather than canonical identity.
+
+\`\`\`typescript
+import { createProductSelectionCodec } from '@01.software/sdk'
+
+const codec = createProductSelectionCodec(detail)
+const selection = codec.parse('?opt.option-color=color-black')
+const selectionQuery = codec.stringify(selection)
+\`\`\`
+
+Use IDs from \`detail.options[].id\` and \`detail.options[].values[].id\` when building new selection links. Slugs remain useful for display and older inbound URLs, but new outbound URLs should use the codec output.
+
+Value-slug-only URLs such as \`?black\` or \`?color=black\` are rejected because option titles and values are not stable identifiers.
+
+## React Query hook variant
+
+\`\`\`typescript
+import { createQueryHooks } from '@01.software/sdk/query'
+
+const query = createQueryHooks(client)
+const { data: detail, isLoading } = query.useProductDetailBySlug(slug)
+\`\`\`
+
+Cache invalidates automatically when any of 10 detail-relevant collections is mutated through SDK mutation hooks.
+
+## SSG / Server Component snippet
+
+\`\`\`tsx
+// app/products/[slug]/page.tsx
+import { createClient } from '@01.software/sdk'
+import { notFound } from 'next/navigation'
+
+export const revalidate = 60
+
+export default async function ProductPage({ params }: { params: { slug: string } }) {
+  const client = createClient({
+    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} />
+}
+\`\`\`
+
+## The \`null\` return contract
+
+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.
+
+## Backend correlation
+
+Log \`client.lastRequestId\` against backend logs \u2014 the endpoint records the exact 404 code alongside the request ID.`;
+}
+
 // src/server.ts
 var REGISTERED_TOOLS_BY_SERVER = /* @__PURE__ */ new WeakMap();
-function registerTool(server, schema35, meta, handler20) {
+function registerTool(server, schema37, meta, handler21) {
   let registered = REGISTERED_TOOLS_BY_SERVER.get(server);
   if (!registered) {
     registered = /* @__PURE__ */ new Set();
@@ -5942,7 +6229,7 @@ function registerTool(server, schema35, meta, handler20) {
     meta.name,
     {
       description: meta.description,
-      inputSchema: schema35,
+      inputSchema: schema37,
       annotations: meta.annotations
     },
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -5971,7 +6258,7 @@ function registerTool(server, schema35, meta, handler20) {
       const summary = activeSummary ?? ownSummary;
       let result = null;
       try {
-        result = await handler20(params);
+        result = await handler21(params);
         return { content: [{ type: "text", text: result }] };
       } finally {
         if (summary) {
@@ -5988,26 +6275,26 @@ function registerTool(server, schema35, meta, handler20) {
     }
   );
 }
-function registerPrompt(server, schema35, meta, handler20) {
+function registerPrompt(server, schema37, meta, handler21) {
   server.registerPrompt(
     meta.name,
     {
       title: meta.title,
       description: meta.description,
-      argsSchema: schema35
+      argsSchema: schema37
     },
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     (params) => ({
       messages: [
         {
           role: meta.role ?? "assistant",
-          content: { type: "text", text: handler20(params) }
+          content: { type: "text", text: handler21(params) }
         }
       ]
     })
   );
 }
-function registerStaticResource(server, uri, meta, handler20) {
+function registerStaticResource(server, uri, meta, handler21) {
   server.registerResource(
     meta.name,
     uri,
@@ -6017,7 +6304,7 @@ function registerStaticResource(server, uri, meta, handler20) {
       mimeType: meta.mimeType ?? "text/plain"
     },
     async (url) => ({
-      contents: [{ uri: url.href, text: handler20() }]
+      contents: [{ uri: url.href, text: handler21() }]
     })
   );
 }
@@ -6119,147 +6406,160 @@ function createServer(options = {}) {
       calculateShipping
     );
     registerTool(server, schema21, metadata21, stockCheck);
+    registerTool(server, schema22, metadata22, productDetail);
+    registerTool(
+      server,
+      schema23,
+      metadata23,
+      productUpsert
+    );
   }
-  registerTool(
-    server,
-    schema22,
-    metadata22,
-    getCollectionSchemaTool
-  );
-  registerTool(
-    server,
-    schema23,
-    metadata23,
-    handler
-  );
   registerTool(
     server,
     schema24,
     metadata24,
-    handler2
+    getCollectionSchemaTool
   );
   registerTool(
     server,
     schema25,
     metadata25,
-    listConfigurableFields
+    handler
   );
   registerTool(
     server,
     schema26,
     metadata26,
-    updateFieldConfig
+    handler2
   );
   registerTool(
     server,
     schema27,
     metadata27,
-    handler3
+    listConfigurableFields
   );
   registerTool(
     server,
     schema28,
     metadata28,
-    handler4
+    updateFieldConfig
   );
   registerTool(
     server,
     schema29,
     metadata29,
-    handler5
+    handler3
   );
   registerTool(
     server,
     schema30,
     metadata30,
-    handler6
+    handler4
   );
-  registerPrompt(
+  registerTool(
     server,
     schema31,
     metadata31,
-    sdkUsageGuide
+    handler5
   );
-  registerPrompt(
+  registerTool(
     server,
     schema32,
     metadata32,
-    collectionQueryHelp
+    handler6
   );
   registerPrompt(
     server,
     schema33,
     metadata33,
-    orderFlowGuide
+    sdkUsageGuide
   );
   registerPrompt(
     server,
     schema34,
     metadata34,
+    collectionQueryHelp
+  );
+  registerPrompt(
+    server,
+    schema35,
+    metadata35,
+    orderFlowGuide
+  );
+  registerPrompt(
+    server,
+    schema36,
+    metadata36,
     featureSetupGuide
   );
   registerStaticResource(
     server,
     "config://app",
-    metadata35,
+    metadata37,
     handler7
   );
   registerStaticResource(
     server,
     "collections://schema",
-    metadata36,
+    metadata38,
     handler8
   );
   registerStaticResource(
     server,
     "docs://sdk/getting-started",
-    metadata37,
+    metadata39,
     handler9
   );
-  registerStaticResource(server, "docs://sdk/guides", metadata38, handler10);
-  registerStaticResource(server, "docs://sdk/api", metadata39, handler11);
+  registerStaticResource(server, "docs://sdk/guides", metadata40, handler10);
+  registerStaticResource(server, "docs://sdk/api", metadata41, handler11);
   registerStaticResource(
     server,
     "docs://sdk/query-builder",
-    metadata40,
+    metadata42,
     handler12
   );
   registerStaticResource(
     server,
     "docs://sdk/react-query",
-    metadata41,
+    metadata43,
     handler13
   );
   registerStaticResource(
     server,
     "docs://sdk/server-api",
-    metadata42,
+    metadata44,
     handler14
   );
   registerStaticResource(
     server,
     "docs://sdk/customer-auth",
-    metadata43,
+    metadata45,
     handler15
   );
   registerStaticResource(
     server,
     "docs://sdk/browser-vs-server",
-    metadata44,
+    metadata46,
     handler16
   );
   registerStaticResource(
     server,
     "docs://sdk/file-upload",
-    metadata45,
+    metadata47,
     handler17
   );
   registerStaticResource(
     server,
     "docs://sdk/webhook",
-    metadata46,
+    metadata48,
     handler18
   );
+  registerStaticResource(
+    server,
+    "docs://sdk/product-detail",
+    metadata49,
+    handler19
+  );
   return server;
 }
 
@@ -6595,7 +6895,7 @@ function acceptsEventStream(req) {
     (entry) => entry.trim().split(";")[0]?.toLowerCase() === "text/event-stream"
   );
 }
-async function handler19(req, res) {
+async function handler20(req, res) {
   setCors(res);
   if (req.method === "OPTIONS") {
     res.writeHead(204);
@@ -6705,5 +7005,5 @@ function writeRequestError(res, err) {
   res.end(JSON.stringify({ error: "Internal server error" }));
 }
 export {
-  handler19 as default
+  handler20 as default
 };