@01.software/cli 0.10.3 → 0.10.4

package/dist/mcp/vercel.js

@@ -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",
@@ -310,8 +308,6 @@ var returnWithRefundSchema = z2.object({
   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",
@@ -1106,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() {
@@ -1939,18 +1935,22 @@ async function productDetail({
 // src/tools/product-upsert.ts
 import { z as z23 } from "zod";
 var optionValueSchema = z23.object({
-  id: z23.string().optional().describe("Existing option-value ID for updates"),
+  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("Canonical value token used in variant maps and URLs"),
+  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("Existing option ID for updates"),
+  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("Canonical option token used in variant maps and URLs"),
+  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({
@@ -1964,7 +1964,7 @@ var variantSchema = z23.object({
     z23.record(z23.string(), z23.union([z23.string(), variantOptionValueSchema])),
     z23.array(z23.string())
   ]).optional().describe(
-    "Option-value selection. Prefer canonical { optionSlug: valueSlug } maps. Object values may use { valueSlug, valueId, value }. Exact { OptionTitle: ValueLabel } maps remain compatibility-only and fail when labels are ambiguous. Arrays of option-value IDs are also accepted."
+    "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(),
@@ -1986,10 +1986,10 @@ var schema23 = {
     "Product fields. Include `id` to update an existing product; omit for create (then `title` is required)."
   ),
   options: z23.array(optionSchema).optional().describe(
-    "Option definitions. Prefer explicit option slug and value slugs. Omitted options on an existing product are deleted (with their values)."
+    "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 canonical { optionSlug: valueSlug } optionValues maps. 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)."
+    "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 = {
@@ -2290,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' } },
@@ -2329,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!,
@@ -2362,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,
   })
@@ -2388,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!,
@@ -2411,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!,
@@ -2440,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!,
@@ -2469,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!,
@@ -2494,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 {
@@ -2506,7 +2512,7 @@ function InfiniteProductList() {
     hasNextPage,
     isFetchingNextPage,
     isLoading,
-  } = client.query.useInfiniteQuery({
+  } = query.useInfiniteQuery({
     collection: 'products',
     options: { where: { status: { equals: 'published' } } },
     pageSize: 20,
@@ -2541,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:
@@ -2549,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 (
@@ -2639,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!,
@@ -2670,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!,
@@ -2822,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"
   },
   {
@@ -2842,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"
   },
   {
@@ -2861,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
@@ -3012,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!,
@@ -3041,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": {
@@ -3179,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`,
         `})`
@@ -3218,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!,`,
@@ -3409,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 }
   })
@@ -3427,7 +3437,7 @@ function ProductList() {
 }
 \`\`\`
 
-### React Query Hooks (client.query)
+### React Query Hooks (@01.software/sdk/query)
 
 | Hook | Description |
 |------|-------------|
@@ -3462,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)
@@ -3491,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!,
@@ -3511,7 +3525,7 @@ if (!product) return notFound()
 // product: { product, variants, options, brand, categories, tags, images, videos, listing }
 \`\`\`
 
-For React: \`const { data } = client.query.useProductDetailBySlug(slug)\`.
+For React: \`const { data } = createQueryHooks(client).useProductDetailBySlug(slug)\`.
 
 ### Product listing (grouped)
 
@@ -3566,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({
@@ -3587,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)
@@ -3663,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!,
@@ -4273,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
@@ -4310,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
@@ -4338,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' } },
@@ -4349,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 }
 })
@@ -4358,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
   })
@@ -4405,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
@@ -4427,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
 })
@@ -4446,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
@@ -4536,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,
@@ -4615,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' } } }
 })
@@ -4631,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 }
 })
@@ -4641,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'
 })
@@ -4651,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'
 })
@@ -4661,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
@@ -4672,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)
-
-### useCreate()
-Create a document with automatic cache invalidation.
-
-\`\`\`typescript
-const { mutate } = client.query.useCreate({ collection: 'products' })
-mutate({ title: 'New Product', status: 'draft' })
-\`\`\`
+## Server Mutations
 
-### useUpdate()
-Update 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.useUpdate({ collection: 'products' })
-mutate({ id: 'product-id', data: { title: 'Updated' } })
-\`\`\`
+import { createServerClient } from '@01.software/sdk/server'
 
-### 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\`.
@@ -4964,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!,
@@ -4992,14 +5026,22 @@ console.log(result.hasNextPage) // true
 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.
 
-> React Query hooks are available on \`Client\` (createClient) only. \`ServerClient\` does not include them.
+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'
+
+const client = createClient({ publishableKey })
+const query = createQueryHooks(client)
+\`\`\`
 
 ## Query Hooks
 
@@ -5007,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' } },
@@ -5025,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 },
 })
@@ -5036,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',
 })
@@ -5047,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',
 })
@@ -5063,7 +5105,7 @@ const {
   fetchNextPage,
   hasNextPage,
   isFetchingNextPage,
-} = client.query.useInfiniteQuery({
+} = query.useInfiniteQuery({
   collection: 'products',
   options: {
     where: { status: { equals: 'published' } },
@@ -5079,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
-
-Mutation hooks automatically invalidate relevant cache keys after success.
+## Writes
 
-### 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
 
@@ -5136,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()
@@ -5147,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
@@ -5160,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>
   )
@@ -5200,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' } },
@@ -5215,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>
   )
@@ -5248,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!,
@@ -5697,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)
 
@@ -5707,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 })
@@ -5729,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!,
@@ -5750,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
@@ -5784,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({
@@ -5797,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
@@ -5817,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>
 }
 \`\`\`
@@ -5851,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!,
@@ -5874,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!,
@@ -5904,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!,
@@ -6127,29 +6152,38 @@ const client = createClient({
 const detail = await client.commerce.product.detail({ slug: 'my-product' })
 if (!detail) return notFound()
 const selection = resolveProductSelection(detail, {
-  search: '?opt.color=black&opt.size=large',
+  search: '?opt.option-color=color-black',
 })
 // selection.selectedVariant, selection.price, selection.stock, selection.media
 \`\`\`
 
 ## URL round-trip
 
-Use the SDK codec for one canonical selection URL format: \`opt.<optionSlug>=<valueSlug>\`. Option and value slugs are the stable public tokens exposed by product detail.
+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.color=black')
-const href = codec.stringify(selection)
+const selection = codec.parse('?opt.option-color=color-black')
+const selectionQuery = codec.stringify(selection)
 \`\`\`
 
-Value-slug-only URLs such as \`?black\` or \`?color=black\` are rejected because option titles are not stable identifiers.
+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
-const { data: detail, isLoading } = client.query.useProductDetailBySlug(slug)
+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.