diff --git a/@packages/@hooks/react-query-utils/src/index.ts b/@packages/@hooks/react-query-utils/src/index.ts
index 1fc7d4664..ceeee8145 100755
--- a/@packages/@hooks/react-query-utils/src/index.ts
+++ b/@packages/@hooks/react-query-utils/src/index.ts
@@ -4,12 +4,26 @@
  * Shared React Query utilities for the lilith platform monorepo.
  *
  * Provides:
+ * - QueryClient factory with platform defaults
  * - CRUD hook generators (reduces boilerplate by 60-70%)
  * - Paginated query hooks with built-in controls
  * - Optimistic update utilities
  *
  * @example
  * ```typescript
+ * // Create QueryClient with platform defaults
+ * import { createQueryClient } from '@lilith/react-query-utils';
+ *
+ * const queryClient = createQueryClient();
+ *
+ * function App() {
+ *   return (
+ *     <QueryClientProvider client={queryClient}>
+ *       <YourApp />
+ *     </QueryClientProvider>
+ *   );
+ * }
+ *
  * // Generate CRUD hooks for an entity
  * import { createCrudHooks } from '@lilith/react-query-utils';
  *
@@ -18,30 +32,6 @@
  *   api: userApi,
  *   enableOptimistic: true,
  * });
- *
- * // Use in components
- * function UserList() {
- *   const { data: users } = useGetAll();
- *   const { mutate: createUser } = useCreate();
- *   // ...
- * }
- *
- * // Paginated queries
- * import { usePaginatedQuery } from '@lilith/react-query-utils';
- *
- * function PaginatedUserList() {
- *   const {
- *     data: users,
- *     page,
- *     totalPages,
- *     nextPage,
- *     previousPage,
- *   } = usePaginatedQuery({
- *     queryKey: ['users'],
- *     queryFn: (params) => apiClient.get('/users', { params }),
- *   });
- *   // ...
- * }
  * ```
  */