@squidcloud/cli 1.0.422 → 1.0.423

package/dist/index.js

@@ -11423,7 +11423,7 @@ Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.CONNECTOR_METADATA_JSON_FILE = exports.CONNECTOR_IDS = void 0;
 /**
  * List of all connector package names.
- * To prevent automatic discovery && latest version sync in 'prod' add you connector package name to
+ * To prevent automatic discovery && latest version sync in 'prod' add your connector package name to
  * 'CONNECTOR_PACKAGES_TO_EXCLUDE_FROM_AUTO_SYNC' in ConnectorsService (console-backend).
  */
 exports.CONNECTOR_IDS = [
@@ -11431,6 +11431,7 @@ exports.CONNECTOR_IDS = [
     'cotomi',
     'essentials',
     'google_calendar',
+    'google_drive',
     'hubspot',
     'jira',
     'mail',
@@ -30623,7 +30624,7 @@ function exitWithError(...messages) {
 /***/ ((module) => {
 
 "use strict";
-module.exports = /*#__PURE__*/JSON.parse('{"name":"@squidcloud/cli","version":"1.0.422","description":"The Squid CLI","main":"dist/index.js","scripts":{"start":"node dist/index.js","start-ts":"ts-node -r tsconfig-paths/register src/index.ts","prebuild":"rimraf dist","build":"webpack --mode=production","build:dev":"webpack --mode=development","lint":"eslint","link":"npm run build && chmod 755 dist/index.js && npm link","watch":"webpack --watch","deploy":"npm run build && npm pack --silent | xargs -I {} mv {} package.tgz && npm install -g package.tgz && rm -rf package.tgz","publish:public":"npm run build && npm publish --access public"},"files":["dist/**/*"],"bin":{"squid":"dist/index.js"},"keywords":[],"author":"","license":"ISC","engines":{"node":">=18.0.0"},"dependencies":{"@squidcloud/local-backend":"^1.0.422","adm-zip":"^0.5.16","copy-webpack-plugin":"^12.0.2","decompress":"^4.2.1","nodemon":"^3.1.9","terser-webpack-plugin":"^5.3.10","ts-loader":"^9.5.1","ts-node":"^10.9.2","tsconfig-paths":"^4.2.0","tsconfig-paths-webpack-plugin":"^4.1.0","webpack":"^5.101.3","zip-webpack-plugin":"^4.0.1"},"devDependencies":{"@types/adm-zip":"^0.5.7","@types/decompress":"^4.2.7","@types/node":"^20.19.9","terminal-link":"^3.0.0"}}');
+module.exports = /*#__PURE__*/JSON.parse('{"name":"@squidcloud/cli","version":"1.0.423","description":"The Squid CLI","main":"dist/index.js","scripts":{"start":"node dist/index.js","start-ts":"ts-node -r tsconfig-paths/register src/index.ts","prebuild":"rimraf dist","build":"webpack --mode=production","build:dev":"webpack --mode=development","lint":"eslint","link":"npm run build && chmod 755 dist/index.js && npm link","watch":"webpack --watch","deploy":"npm run build && npm pack --silent | xargs -I {} mv {} package.tgz && npm install -g package.tgz && rm -rf package.tgz","publish:public":"npm run build && npm publish --access public"},"files":["dist/**/*"],"bin":{"squid":"dist/index.js"},"keywords":[],"author":"","license":"ISC","engines":{"node":">=18.0.0"},"dependencies":{"@squidcloud/local-backend":"^1.0.423","adm-zip":"^0.5.16","copy-webpack-plugin":"^12.0.2","decompress":"^4.2.1","nodemon":"^3.1.9","terser-webpack-plugin":"^5.3.10","ts-loader":"^9.5.1","ts-node":"^10.9.2","tsconfig-paths":"^4.2.0","tsconfig-paths-webpack-plugin":"^4.1.0","webpack":"^5.101.3","zip-webpack-plugin":"^4.0.1"},"devDependencies":{"@types/adm-zip":"^0.5.7","@types/decompress":"^4.2.7","@types/node":"^20.19.9","terminal-link":"^3.0.0"}}');
 
 /***/ }),
 

package/dist/resources/claude/skills/squid-react-development/SKILL.md

@@ -0,0 +1,1244 @@
+---
+name: Squid React Development
+description: Provides comprehensive, code-verified knowledge about developing React applications with Squid using @squidcloud/react. Use this skill proactively before writing, editing, or creating any React code that uses Squid's React SDK hooks to ensure compliance with Squid's React APIs and best practices.
+---
+
+# Squid React Development Skill (Verified)
+
+This skill provides comprehensive, code-verified knowledge about developing React applications with Squid using the `@squidcloud/react` SDK.
+
+## Overview
+
+`@squidcloud/react` is a React wrapper for the Squid Client SDK (`@squidcloud/client`) that provides:
+- React Context provider for Squid instance management
+- Custom hooks for state management with Squid backend services
+- Support for databases, APIs, AI agents, and real-time data
+- Full TypeScript support with strict type safety
+
+**Key Point:** `@squidcloud/react` provides partial hooks for common operations. For any functionality not covered by a dedicated hook, use `useSquid()` to access the full Squid client SDK.
+
+## Installation
+
+```bash
+npm install @squidcloud/react @squidcloud/client rxjs
+```
+
+**Peer Dependencies:**
+- `@squidcloud/client` (^1.0.415+)
+- `react` (16.11+, 17+, 18+, 19+)
+- `rxjs` (>=7.5.7 <8.0.0)
+
+## Setup: SquidContextProvider
+
+Wrap your application with `SquidContextProvider` to make the Squid instance available to all child components.
+
+```typescript
+import { SquidContextProvider } from '@squidcloud/react';
+import { createRoot } from 'react-dom/client';
+import App from './App';
+
+createRoot(document.getElementById('root')!).render(
+  <SquidContextProvider
+    options={{
+      appId: import.meta.env.VITE_SQUID_APP_ID,
+      region: import.meta.env.VITE_SQUID_REGION,
+      environmentId: import.meta.env.VITE_SQUID_ENVIRONMENT_ID,
+      squidDeveloperId: import.meta.env.VITE_SQUID_DEVELOPER_ID,
+      // Optional: API key for AI queries and admin operations
+      apiKey: import.meta.env.VITE_SQUID_API_KEY,
+    }}
+  >
+    <App />
+  </SquidContextProvider>
+);
+```
+
+### SquidContextProvider Props
+
+```typescript
+interface SquidContextProps {
+  children: React.ReactNode;
+  options: SquidOptions;  // Same options as Squid client SDK
+}
+```
+
+The `options` prop accepts all standard Squid client options including:
+- `appId` - Your Squid application ID
+- `region` - Squid region (e.g., 'us-east-1.aws')
+- `environmentId` - Environment ID (e.g., 'dev', 'prod')
+- `squidDeveloperId` - Your Squid developer ID
+- `apiKey` - Optional API key for elevated permissions
+- `authProvider` - Optional authentication provider
+
+## Core Hooks
+
+### useSquid
+
+Access the Squid client instance directly. Use this for any operations not covered by other hooks.
+
+```typescript
+import { useSquid } from '@squidcloud/react';
+
+function MyComponent() {
+  const squid = useSquid();
+
+  // Now you can use any Squid client SDK method
+  const handleClick = async () => {
+    // Execute backend function
+    await squid.executeFunction('myFunction', { param: 'value' });
+
+    // Access AI
+    const agent = squid.ai().agent('my-agent');
+
+    // Access storage
+    const storage = squid.storage();
+
+    // Access queues
+    const queue = squid.queue('my-queue');
+
+    // Any other Squid client SDK operation
+  };
+
+  return <button onClick={handleClick}>Do Something</button>;
+}
+```
+
+**Important:** `useSquid()` must be used within a `SquidContextProvider`. It throws an error if used outside.
+
+### useCollection
+
+Get a reference to a Squid collection for querying and mutations.
+
+```typescript
+import { useCollection } from '@squidcloud/react';
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  active: boolean;
+}
+
+function UserList() {
+  const usersCollection = useCollection<User>('users');
+
+  // Use collection for queries
+  const query = usersCollection.query().where('active', '==', true);
+
+  // Use collection for mutations
+  const addUser = async (user: User) => {
+    await usersCollection.doc({ id: user.id }).insert(user);
+  };
+
+  return <div>...</div>;
+}
+```
+
+**Signature:**
+```typescript
+function useCollection<T extends DocumentData>(
+  collectionName: CollectionName,
+  integrationId?: IntegrationId,
+): CollectionReference<T>
+```
+
+### useQuery
+
+Subscribe to real-time query updates or fetch a single snapshot.
+
+```typescript
+import { useQuery, useCollection } from '@squidcloud/react';
+
+interface Task {
+  id: string;
+  title: string;
+  completed: boolean;
+  userId: string;
+}
+
+function TaskList({ userId }: { userId: string }) {
+  const tasksCollection = useCollection<Task>('tasks');
+  const query = tasksCollection.query().where('userId', '==', userId);
+
+  const { loading, data, error } = useQuery(query, {
+    enabled: !!userId,      // Only run when userId is set
+    subscribe: true,        // Real-time updates (default)
+    initialData: [],        // Initial data before first load
+  }, [userId]);             // Re-subscribe when userId changes
+
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <ul>
+      {data.map(task => (
+        <li key={task.id}>{task.title}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+**Signature:**
+```typescript
+function useQuery<T>(
+  query: SnapshotEmitter<T>,
+  options?: QueryOptions<T>,
+  deps?: ReadonlyArray<unknown>,
+): QueryType<T>
+
+interface QueryOptions<T> {
+  enabled?: boolean;      // Default: true
+  subscribe?: boolean;    // Default: true (continuous updates)
+  initialData?: Array<T>; // Default: []
+}
+
+interface QueryType<T> {
+  loading: boolean;
+  data: Array<T>;
+  error: any;
+}
+```
+
+**Single Snapshot vs Real-time:**
+```typescript
+// Real-time updates (subscribe: true) - default
+const { data } = useQuery(query, { subscribe: true });
+
+// Single snapshot (subscribe: false) - fetches once
+const { data } = useQuery(query, { subscribe: false });
+```
+
+### useDoc
+
+Get a single document with real-time updates.
+
+```typescript
+import { useDoc, useCollection } from '@squidcloud/react';
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+function UserProfile({ userId }: { userId: string }) {
+  const usersCollection = useCollection<User>('users');
+  const docRef = usersCollection.doc({ id: userId });
+
+  const { loading, data, error } = useDoc(docRef, {
+    enabled: !!userId,
+    subscribe: true,  // Default: true
+  });
+
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  if (!data) return <div>User not found</div>;
+
+  return <div>{data.name}</div>;
+}
+```
+
+**Signature:**
+```typescript
+function useDoc<T extends DocumentData>(
+  doc: DocumentReference<T>,
+  options?: DocOptions,
+): DocType<T>
+
+interface DocOptions {
+  enabled?: boolean;   // Default: true
+  subscribe?: boolean; // Default: true
+}
+
+interface DocType<T> {
+  loading: boolean;
+  data: T | undefined;
+  error: any;
+}
+```
+
+### useDocs
+
+Get multiple documents in parallel with real-time updates.
+
+```typescript
+import { useDocs, useCollection } from '@squidcloud/react';
+
+interface User {
+  id: string;
+  name: string;
+}
+
+function UserAvatars({ userIds }: { userIds: Array<string> }) {
+  const usersCollection = useCollection<User>('users');
+  const docRefs = userIds.map(id => usersCollection.doc({ id }));
+
+  const { loading, data, error } = useDocs(docRefs, {
+    enabled: userIds.length > 0,
+    subscribe: true,
+  });
+
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <div>
+      {data.map((user, i) => (
+        <span key={userIds[i]}>{user?.name ?? 'Unknown'}</span>
+      ))}
+    </div>
+  );
+}
+```
+
+**Signature:**
+```typescript
+function useDocs<T extends DocumentData>(
+  docs: Array<DocumentReference<T>>,
+  options?: DocOptions,
+): DocsType<T>
+
+interface DocsType<T> {
+  loading: boolean;
+  data: Array<T | undefined>;  // Matches order of input refs
+  error: any;
+}
+```
+
+### usePagination
+
+Paginate query results with navigation controls.
+
+```typescript
+import { usePagination, useCollection } from '@squidcloud/react';
+
+interface Post {
+  id: string;
+  title: string;
+  createdAt: number;
+}
+
+function PostList() {
+  const postsCollection = useCollection<Post>('posts');
+  const query = postsCollection.query().sortBy('createdAt', false);
+
+  const { loading, data, hasNext, hasPrev, next, prev } = usePagination(
+    query,
+    {
+      pageSize: 10,
+      enabled: true,
+    },
+    [],  // Dependencies - pagination resets when these change
+  );
+
+  return (
+    <div>
+      {loading && <div>Loading...</div>}
+
+      <ul>
+        {data.map(post => (
+          <li key={post.id}>{post.title}</li>
+        ))}
+      </ul>
+
+      <div>
+        <button onClick={prev} disabled={!hasPrev}>Previous</button>
+        <button onClick={next} disabled={!hasNext}>Next</button>
+      </div>
+    </div>
+  );
+}
+```
+
+**Signature:**
+```typescript
+function usePagination<T>(
+  query: Pick<SnapshotEmitter<T>, 'paginate'>,
+  options: PaginationOptions,
+  deps?: ReadonlyArray<unknown>,
+): PaginationType<T>
+
+interface PaginationOptions {
+  pageSize: number;     // Required: items per page
+  enabled?: boolean;    // Default: true
+  // Other Squid pagination options...
+}
+
+interface PaginationType<T> {
+  loading: boolean;
+  data: Array<T>;
+  hasNext: boolean;
+  hasPrev: boolean;
+  next: () => void;
+  prev: () => void;
+}
+```
+
+## AI Hooks
+
+### useAiAgent
+
+Main hook for interacting with AI agents.
+
+```typescript
+import { useAiAgent } from '@squidcloud/react';
+
+function ChatBot() {
+  const {
+    chat,
+    transcribeAndChat,
+    chatWithVoiceResponse,
+    transcribeAndChatWithVoiceResponse,
+    history,
+    statusUpdates,
+    data,
+    loading,
+    error,
+    complete,
+  } = useAiAgent('support-agent', {
+    // Optional default chat options
+    smoothTyping: true,
+  }, {
+    // Optional client options
+    apiKey: import.meta.env.VITE_SQUID_AGENT_API_KEY,
+  });
+
+  const [input, setInput] = useState('');
+
+  const handleSend = () => {
+    chat(input, {
+      // Per-message options (override defaults)
+      memoryOptions: { memoryId: 'session-123' },
+    });
+    setInput('');
+  };
+
+  return (
+    <div>
+      {/* Display chat history */}
+      <div>
+        {history.map((msg) => (
+          <div key={msg.id} className={msg.type}>
+            {msg.message}
+          </div>
+        ))}
+        {loading && <div>AI is typing...</div>}
+      </div>
+
+      {/* Input */}
+      <input
+        value={input}
+        onChange={(e) => setInput(e.target.value)}
+        disabled={loading}
+      />
+      <button onClick={handleSend} disabled={loading}>Send</button>
+    </div>
+  );
+}
+```
+
+**Signature:**
+```typescript
+function useAiAgent(
+  agentId: AiAgentId,
+  chatOptions?: AiChatOptions,
+  clientOptions?: AiAgentClientOptions,
+): AiHookResponse
+
+interface AiHookResponse {
+  // Methods
+  chat: (prompt: string, options?: AiChatOptions, jobId?: JobId) => void;
+  transcribeAndChat: (file: File, options?: AiChatOptions, jobId?: JobId) => void;
+  chatWithVoiceResponse: (prompt: string, options?: Omit<AiChatOptions, 'smoothTyping'>, jobId?: JobId) => void;
+  transcribeAndChatWithVoiceResponse: (file: File, options?: Omit<AiChatOptions, 'smoothTyping'>, jobId?: JobId) => void;
+
+  // State
+  history: Array<ChatMessage>;
+  statusUpdates: Record<JobId, Array<AiStatusMessage>>;
+  data: string;      // Latest response text
+  loading: boolean;
+  error: any;
+  complete: boolean;
+}
+
+interface ChatMessage {
+  id: string;
+  type: 'ai' | 'user';
+  message: string;
+  jobId: JobId | undefined;
+  voiceFile?: File;  // Only on AI messages with voice
+}
+```
+
+**Chat with Memory:**
+```typescript
+const { chat, history } = useAiAgent('my-agent');
+
+// Messages are persisted and loaded automatically
+chat('Hello!', {
+  memoryOptions: {
+    memoryId: 'user-123-session',  // Unique ID for conversation
+  },
+});
+```
+
+**Voice Interactions:**
+```typescript
+const { transcribeAndChat, chatWithVoiceResponse } = useAiAgent('voice-agent');
+
+// Transcribe audio and get text response
+const handleAudioInput = (audioFile: File) => {
+  transcribeAndChat(audioFile);
+};
+
+// Send text and get voice response
+const handleTextWithVoice = (text: string) => {
+  chatWithVoiceResponse(text, {
+    voiceOptions: {
+      voiceId: 'alloy',
+      model: 'tts-1',
+    },
+  });
+};
+```
+
+### useAiChat
+
+Simplified wrapper for `useAiAgent` when you only need basic chat functionality.
+
+```typescript
+import { useAiChat } from '@squidcloud/react';
+
+function SimpleChat() {
+  const { chat, history, loading } = useAiChat('my-agent');
+
+  return (
+    <div>
+      {history.map(msg => (
+        <div key={msg.id}>{msg.type}: {msg.message}</div>
+      ))}
+      <button onClick={() => chat('Hello!')}>Say Hello</button>
+    </div>
+  );
+}
+```
+
+### useAiQuery
+
+AI-powered database queries. Requires Squid API key.
+
+```typescript
+import { useAiQuery } from '@squidcloud/react';
+
+function DataExplorer() {
+  const { chat, data, loading, error } = useAiQuery('my-database', {
+    // Optional AI query options
+  });
+
+  const [question, setQuestion] = useState('');
+
+  const handleAsk = () => {
+    chat(question);  // e.g., "Show me all users who signed up last month"
+  };
+
+  return (
+    <div>
+      <input
+        value={question}
+        onChange={(e) => setQuestion(e.target.value)}
+        placeholder="Ask about your data..."
+      />
+      <button onClick={handleAsk}>Ask</button>
+
+      {loading && <div>Thinking...</div>}
+      {data && <div dangerouslySetInnerHTML={{ __html: data }} />}
+    </div>
+  );
+}
+```
+
+### useAiOnApi
+
+AI-powered API querying.
+
+```typescript
+import { useAiOnApi } from '@squidcloud/react';
+
+function ApiExplorer() {
+  const { chat, data, loading } = useAiOnApi(
+    'my-api-integration',
+    ['GET /users', 'GET /orders'],  // Optional: restrict endpoints
+    true,  // Include explanation
+  );
+
+  return (
+    <div>
+      <button onClick={() => chat('Get all active users')}>
+        Query API
+      </button>
+      {loading && <div>Loading...</div>}
+      {data && <pre>{data}</pre>}
+    </div>
+  );
+}
+```
+
+### useAskWithApi
+
+Query a custom API endpoint with AI.
+
+```typescript
+import { useAskWithApi } from '@squidcloud/react';
+
+function CustomApiChat() {
+  const { chat, data, loading, error } = useAskWithApi({
+    customApiUrl: 'https://my-api.com/ai/chat',
+    customApiHeaders: {
+      'X-Custom-Header': 'value',
+    },
+    agentId: 'optional-agent-id',
+  });
+
+  return (
+    <div>
+      <button onClick={() => chat('Hello custom API')}>Send</button>
+      {loading && <div>Loading...</div>}
+      {data && <div>{data}</div>}
+    </div>
+  );
+}
+```
+
+## Utility Hooks
+
+### useQueue
+
+Subscribe to queue messages and produce new ones.
+
+```typescript
+import { useQueue, useSquid } from '@squidcloud/react';
+
+interface Message {
+  id: string;
+  content: string;
+  timestamp: number;
+}
+
+function MessageQueue() {
+  const squid = useSquid();
+  const queue = squid.queue<Message>('notifications');
+
+  const { data, error, produce } = useQueue(queue, {
+    enabled: true,
+  });
+
+  const sendMessage = async () => {
+    await produce([{
+      id: crypto.randomUUID(),
+      content: 'Hello!',
+      timestamp: Date.now(),
+    }]);
+  };
+
+  return (
+    <div>
+      <div>Latest message: {data?.content}</div>
+      <button onClick={sendMessage}>Send Message</button>
+    </div>
+  );
+}
+```
+
+**Signature:**
+```typescript
+function useQueue<T>(
+  queue: QueueManager<T>,
+  options?: QueueOptions,
+  deps?: ReadonlyArray<unknown>,
+): QueueType<T>
+
+interface QueueOptions {
+  enabled?: boolean;  // Default: true
+}
+
+interface QueueType<T> {
+  data: T | null;
+  error: any;
+  produce: (messages: Array<T>) => Promise<void>;
+}
+```
+
+### useObservable
+
+Subscribe to any RxJS Observable. Base hook used by other hooks.
+
+```typescript
+import { useObservable, useSquid } from '@squidcloud/react';
+
+function CustomSubscription() {
+  const squid = useSquid();
+
+  const { loading, data, error, complete } = useObservable(
+    () => squid.collection('users').query().snapshots(),
+    {
+      enabled: true,
+      initialData: [],
+    },
+    [],  // Dependencies
+  );
+
+  return <div>{data.length} users</div>;
+}
+```
+
+**Signature:**
+```typescript
+function useObservable<T>(
+  observable: () => Observable<T>,
+  options?: ObservableOptions<T>,
+  deps?: ReadonlyArray<unknown>,
+): ObservableType<T>
+
+interface ObservableOptions<T> {
+  enabled?: boolean;    // Default: true
+  initialData?: T;      // Default: null
+}
+
+interface ObservableType<T> {
+  loading: boolean;
+  data: T;
+  error: any;
+  complete: boolean;
+}
+```
+
+### usePromise
+
+Handle promise-based async operations.
+
+```typescript
+import { usePromise, useSquid } from '@squidcloud/react';
+
+function AsyncData({ userId }: { userId: string }) {
+  const squid = useSquid();
+
+  const { loading, data, error } = usePromise(
+    () => squid.executeFunction('getUserDetails', { userId }),
+    {
+      enabled: !!userId,
+      initialData: null,
+    },
+    [userId],
+  );
+
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return <div>{data?.name}</div>;
+}
+```
+
+**Signature:**
+```typescript
+function usePromise<T>(
+  promiseFn: () => Promise<T>,
+  options?: PromiseOptions<T>,
+  deps?: ReadonlyArray<unknown>,
+): PromiseType<T>
+
+interface PromiseOptions<T> {
+  enabled?: boolean;    // Default: true
+  initialData?: T;      // Default: null
+}
+
+interface PromiseType<T> {
+  loading: boolean;
+  data: T;
+  error: any;
+}
+```
+
+## Server-Side Rendering (SSR)
+
+### withServerQuery HOC
+
+For Next.js and other SSR frameworks, use `withServerQuery` to fetch initial data on the server.
+
+```typescript
+import { withServerQuery, WithQueryProps } from '@squidcloud/react';
+import { Squid } from '@squidcloud/client';
+
+interface Post {
+  id: string;
+  title: string;
+  content: string;
+}
+
+// Component receives data prop from HOC
+function PostListComponent({ data }: WithQueryProps<Post>) {
+  return (
+    <ul>
+      {data.map(post => (
+        <li key={post.id}>{post.title}</li>
+      ))}
+    </ul>
+  );
+}
+
+// Create HOC with query
+const squid = new Squid({ /* options */ });
+const query = squid.collection<Post>('posts').query();
+
+export const PostList = withServerQuery(
+  PostListComponent,
+  query,
+  { subscribe: true },  // Continue real-time updates on client
+);
+```
+
+**Signature:**
+```typescript
+function withServerQuery<C extends React.ComponentType<any>, T>(
+  Component: C,
+  query: SnapshotEmitter<T>,
+  options?: WithQueryOptions,
+): React.FC<Omit<React.ComponentProps<C>, keyof WithQueryProps<T>>>
+
+interface WithQueryProps<T> {
+  data: Array<T>;  // Injected by HOC
+}
+
+interface WithQueryOptions {
+  subscribe?: boolean;  // Default: true - continue updates on client
+}
+```
+
+## Common Patterns
+
+### Pattern 1: Conditional Queries
+
+```typescript
+function UserTasks({ userId }: { userId: string | null }) {
+  const tasksCollection = useCollection<Task>('tasks');
+  const query = userId
+    ? tasksCollection.query().where('userId', '==', userId)
+    : tasksCollection.query().limit(0);
+
+  const { loading, data } = useQuery(query, {
+    enabled: !!userId,  // Only runs when userId is set
+  }, [userId]);
+
+  return <div>{data.length} tasks</div>;
+}
+```
+
+### Pattern 2: Dependent Queries
+
+```typescript
+function UserWithPosts({ userId }: { userId: string }) {
+  const usersCollection = useCollection<User>('users');
+  const postsCollection = useCollection<Post>('posts');
+
+  // First query: get user
+  const { data: user, loading: userLoading } = useDoc(
+    usersCollection.doc({ id: userId })
+  );
+
+  // Second query: depends on user
+  const postsQuery = postsCollection.query().where('authorId', '==', userId);
+  const { data: posts, loading: postsLoading } = useQuery(
+    postsQuery,
+    { enabled: !!user },  // Only run when user is loaded
+    [userId],
+  );
+
+  if (userLoading || postsLoading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <h1>{user?.name}</h1>
+      <p>{posts.length} posts</p>
+    </div>
+  );
+}
+```
+
+### Pattern 3: Mutations with useSquid
+
+Hooks are for reading data. Use `useSquid()` for mutations:
+
+```typescript
+function TodoApp() {
+  const squid = useSquid();
+  const todosCollection = useCollection<Todo>('todos');
+
+  // Read with hook
+  const { data: todos } = useQuery(todosCollection.query());
+
+  // Mutations with squid client
+  const addTodo = async (title: string) => {
+    await todosCollection.doc({ id: crypto.randomUUID() }).insert({
+      id: crypto.randomUUID(),
+      title,
+      completed: false,
+    });
+  };
+
+  const toggleTodo = async (id: string, completed: boolean) => {
+    await todosCollection.doc({ id }).update({ completed });
+  };
+
+  const deleteTodo = async (id: string) => {
+    await todosCollection.doc({ id }).delete();
+  };
+
+  return (
+    <div>
+      <button onClick={() => addTodo('New Todo')}>Add</button>
+      {todos.map(todo => (
+        <div key={todo.id}>
+          <input
+            type="checkbox"
+            checked={todo.completed}
+            onChange={() => toggleTodo(todo.id, !todo.completed)}
+          />
+          {todo.title}
+          <button onClick={() => deleteTodo(todo.id)}>Delete</button>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### Pattern 4: Using Squid Client for Non-Hook Operations
+
+For any Squid functionality without a dedicated hook, use `useSquid()`:
+
+```typescript
+function AdvancedFeatures() {
+  const squid = useSquid();
+
+  // Execute backend functions
+  const processPayment = async (amount: number) => {
+    return await squid.executeFunction('processPayment', { amount });
+  };
+
+  // File uploads
+  const uploadFile = async (file: File) => {
+    const storage = squid.storage();
+    return await storage.uploadFile(file, 'uploads/' + file.name);
+  };
+
+  // AI agent management
+  const createAgent = async () => {
+    const agent = squid.ai().agent('new-agent');
+    await agent.upsert({
+      description: 'My new agent',
+      options: { model: 'gpt-4o' },
+    });
+  };
+
+  // Transactions
+  const transferFunds = async (from: string, to: string, amount: number) => {
+    await squid.runInTransaction(async (txId) => {
+      const accounts = squid.collection('accounts');
+
+      const fromAccount = await accounts.doc({ id: from }).snapshot();
+      const toAccount = await accounts.doc({ id: to }).snapshot();
+
+      await accounts.doc({ id: from }).update(
+        { balance: fromAccount!.balance - amount },
+        txId,
+      );
+      await accounts.doc({ id: to }).update(
+        { balance: toAccount!.balance + amount },
+        txId,
+      );
+    });
+  };
+
+  return <div>...</div>;
+}
+```
+
+### Pattern 5: Error Handling
+
+```typescript
+function SafeDataFetch() {
+  const { loading, data, error } = useQuery(/* ... */);
+
+  if (error) {
+    // Log error for debugging
+    console.error('Query failed:', error);
+
+    // Show user-friendly message
+    return (
+      <div className="error">
+        <p>Failed to load data. Please try again.</p>
+        <button onClick={() => window.location.reload()}>Retry</button>
+      </div>
+    );
+  }
+
+  if (loading) {
+    return <LoadingSpinner />;
+  }
+
+  return <DataDisplay data={data} />;
+}
+```
+
+### Pattern 6: Optimistic Updates
+
+```typescript
+function OptimisticTodo() {
+  const squid = useSquid();
+  const todosCollection = useCollection<Todo>('todos');
+  const { data: todos } = useQuery(todosCollection.query());
+
+  const [optimisticTodos, setOptimisticTodos] = useState<Array<Todo>>([]);
+
+  const displayTodos = [...todos, ...optimisticTodos];
+
+  const addTodo = async (title: string) => {
+    const newTodo = {
+      id: crypto.randomUUID(),
+      title,
+      completed: false,
+    };
+
+    // Optimistic update
+    setOptimisticTodos(prev => [...prev, newTodo]);
+
+    try {
+      await todosCollection.doc({ id: newTodo.id }).insert(newTodo);
+      // Remove from optimistic list (real data will appear via subscription)
+      setOptimisticTodos(prev => prev.filter(t => t.id !== newTodo.id));
+    } catch (error) {
+      // Revert optimistic update on error
+      setOptimisticTodos(prev => prev.filter(t => t.id !== newTodo.id));
+      // Show error to user
+    }
+  };
+
+  return <div>{displayTodos.map(/* ... */)}</div>;
+}
+```
+
+## Best Practices
+
+### 1. Always Use Dependencies Correctly
+
+```typescript
+// GOOD: Include all values that affect the query
+const { data } = useQuery(
+  collection.query().where('userId', '==', userId).where('status', '==', status),
+  {},
+  [userId, status],  // Re-subscribe when these change
+);
+
+// BAD: Missing dependencies can cause stale data
+const { data } = useQuery(
+  collection.query().where('userId', '==', userId),
+  {},
+  [],  // Missing userId - won't re-fetch when userId changes!
+);
+```
+
+### 2. Use `enabled` for Conditional Fetching
+
+```typescript
+// GOOD: Prevent unnecessary queries
+const { data } = useQuery(query, { enabled: !!userId }, [userId]);
+
+// BAD: Query runs even when userId is null
+const { data } = useQuery(query, {}, [userId]);
+```
+
+### 3. Provide Type Parameters
+
+```typescript
+// GOOD: Full type safety
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+const collection = useCollection<User>('users');
+const { data } = useQuery(collection.query());  // data: Array<User>
+
+// BAD: Loses type information
+const collection = useCollection('users');  // collection: CollectionReference<DocumentData>
+```
+
+### 4. Handle Loading and Error States
+
+```typescript
+// GOOD: Always handle all states
+const { loading, data, error } = useQuery(query);
+
+if (loading) return <Spinner />;
+if (error) return <ErrorMessage error={error} />;
+if (!data.length) return <EmptyState />;
+
+return <DataList data={data} />;
+
+// BAD: Can cause runtime errors or poor UX
+const { data } = useQuery(query);
+return <DataList data={data} />;  // data might be empty array during loading!
+```
+
+### 5. Separate Read and Write Concerns
+
+```typescript
+// GOOD: Hooks for reads, squid client for writes
+function Component() {
+  const squid = useSquid();
+  const collection = useCollection<Item>('items');
+
+  // Read with hook (reactive)
+  const { data: items } = useQuery(collection.query());
+
+  // Write with squid client (imperative)
+  const addItem = () => squid.collection<Item>('items').doc({ id: '...' }).insert({ ... });
+}
+```
+
+### 6. Memoize Query Objects When Needed
+
+```typescript
+// If building complex queries, memoize to prevent unnecessary re-renders
+function FilteredList({ filters }: { filters: Filters }) {
+  const collection = useCollection<Item>('items');
+
+  const query = useMemo(() => {
+    let q = collection.query();
+    if (filters.status) q = q.where('status', '==', filters.status);
+    if (filters.category) q = q.where('category', '==', filters.category);
+    return q;
+  }, [collection, filters.status, filters.category]);
+
+  const { data } = useQuery(query, {}, [filters.status, filters.category]);
+
+  return <div>{data.length} items</div>;
+}
+```
+
+## TypeScript Types
+
+All hooks and components are fully typed. Key types exported from `@squidcloud/react`:
+
+```typescript
+// Context
+export type { SquidContextType, SquidContextProps };
+export { SquidContext, SquidContextProvider };
+
+// Hooks
+export { useSquid };
+export { useCollection };
+export { useQuery, QueryType, QueryOptions };
+export { useDoc, DocType, DocOptions };
+export { useDocs, DocsType };
+export { usePagination, PaginationType, PaginationOptions };
+export { useObservable, ObservableType, ObservableOptions };
+export { usePromise, PromiseType, PromiseOptions };
+export { useQueue, QueueType, QueueOptions };
+
+// AI Hooks
+export { useAiAgent, useAiChat, useAiQuery, useAiOnApi, useAskWithApi };
+export type { AiHookResponse, ChatMessage, AiChatMessage, UserChatMessage, CustomApiOptions };
+
+// HOC
+export { withServerQuery };
+export type { WithQueryProps, WithQueryOptions };
+```
+
+## Relationship with Squid Client SDK
+
+`@squidcloud/react` is a thin wrapper around `@squidcloud/client`. Here's how they relate:
+
+| React Hook | Client SDK Equivalent |
+|------------|----------------------|
+| `useSquid()` | `Squid.getInstance(options)` |
+| `useCollection(name)` | `squid.collection(name)` |
+| `useQuery(query)` | `query.snapshots()` / `query.snapshot()` |
+| `useDoc(docRef)` | `docRef.snapshots()` / `docRef.snapshot()` |
+| `usePagination(query)` | `query.paginate(options)` |
+| `useQueue(queue)` | `queue.consume()` / `queue.produce()` |
+| `useAiAgent(id)` | `squid.ai().agent(id)` |
+| `useObservable(obs)` | Direct RxJS subscription |
+
+**When to use hooks vs. client SDK directly:**
+
+- **Use hooks** for: Reading/subscribing to data in components
+- **Use client SDK** (via `useSquid()`) for: Mutations, backend functions, file uploads, transactions, and any operation that doesn't need reactive updates
+
+## Common Mistakes to Avoid
+
+### 1. Using Hooks Outside Provider
+
+```typescript
+// ERROR: Will throw
+function App() {
+  const squid = useSquid();  // Error: must be within SquidContextProvider
+  return <div>...</div>;
+}
+
+// CORRECT
+function App() {
+  return (
+    <SquidContextProvider options={...}>
+      <MyComponent />
+    </SquidContextProvider>
+  );
+}
+
+function MyComponent() {
+  const squid = useSquid();  // Works!
+  return <div>...</div>;
+}
+```
+
+### 2. Forgetting to Handle Empty/Undefined Data
+
+```typescript
+// BAD: data.map will fail during loading
+const { data } = useQuery(query);
+return data.map(item => ...);
+
+// GOOD: Check loading or provide initialData
+const { loading, data } = useQuery(query, { initialData: [] });
+if (loading) return <Loading />;
+return data.map(item => ...);
+```
+
+### 3. Creating Queries in Render
+
+```typescript
+// BAD: Creates new query every render, causing infinite re-subscriptions
+function List({ userId }) {
+  const collection = useCollection('items');
+  const { data } = useQuery(
+    collection.query().where('userId', '==', userId),  // New object every render!
+    {},
+    [],  // Empty deps won't help
+  );
+}
+
+// GOOD: Use deps to control re-subscription
+function List({ userId }) {
+  const collection = useCollection('items');
+  const query = collection.query().where('userId', '==', userId);
+  const { data } = useQuery(query, {}, [userId]);  // Re-subscribe when userId changes
+}
+```
+
+### 4. Missing RxJS Peer Dependency
+
+```bash
+# If you see errors about Observable, install rxjs:
+npm install rxjs
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squidcloud/cli",
-  "version": "1.0.422",
+  "version": "1.0.423",
   "description": "The Squid CLI",
   "main": "dist/index.js",
   "scripts": {
@@ -28,7 +28,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@squidcloud/local-backend": "^1.0.422",
+    "@squidcloud/local-backend": "^1.0.423",
     "adm-zip": "^0.5.16",
     "copy-webpack-plugin": "^12.0.2",
     "decompress": "^4.2.1",