@squidcloud/cli 1.0.446 → 1.0.447

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

@@ -1,2503 +1,96 @@
 ---
-name: Squid Development
-description: Provides comprehensive, code-verified knowledge about developing applications with Squid. Use this skill proactively before writing, editing, or creating any code that uses Squid's Client SDK, Backend SDK, or CLI to ensure compliance with Squid's APIs and best practices.
+name: squid-development
+description: Provides code-verified knowledge for developing Squid applications. Use proactively when writing code with @squidcloud/client, @squidcloud/backend, or using the Squid CLI.
 ---
 
-# Squid Development Skill (Verified)
-
-This skill provides comprehensive, code-verified knowledge about developing applications with Squid.
+# Squid Development Skill
 
 ## Overview
 
 Squid is a backend-as-a-service platform that provides:
-- **Client SDK** (`@squidcloud/client`) - TypeScript/JavaScript SDK for frontend
-- **Backend SDK** (`@squidcloud/backend`) - TypeScript SDK with decorators for backend
-- **CLI** (`@squidcloud/cli`) - Local development and deployment tools
-- **Built-in integrations** - Databases, queues, storage, AI, APIs
-
-## Squid Architecture: The Three Parts
-
-When developing with Squid, you work with three distinct but interconnected parts:
-
-### 1. Client (Frontend/External Services)
-
-**What it is:** Any application that needs to interact with your Squid backend - web apps, mobile apps, desktop apps, or even other servers.
-
-**How it works:**
-- Initializes the Squid Client SDK (`@squidcloud/client`)
-- Communicates with Squid functionality over HTTP/WebSocket
-- Can interact with AI agents, modify agent settings, query databases, call backend functions, etc.
-- Optionally uses authentication (OAuth2.0) for user-specific access
-- Respects security rules defined in the backend
-
-**Common use cases:**
-```typescript
-// Web/mobile application
-const squid = new Squid({
-  appId: 'your-app-id',
-  region: 'us-east-1.aws',
-  authProvider: { /* user auth */ }
-});
-
-// Interact with agents
-const agent = squid.ai().agent('support-agent');
-const response = await agent.ask('How do I reset my password?');
-
-// Query databases
-const users = await squid.collection('users').query().eq('active', true).snapshot();
-
-// Call backend functions
-const result = await squid.executeFunction('processPayment', paymentData);
-```
-
-**Key point:** Clients have limited, controlled access based on security rules you define in the backend.
-
-### 2. Squid Backend (Your Server-Side Code)
-
-**What it is:** TypeScript code that runs on Squid's infrastructure, containing your business logic, security rules, and integrations.
-
-**How it works:**
-- Contains services that extend `SquidService`
-- Uses **decorators** to define functionality:
-  - `@executable()` - Backend functions callable from clients
-  - `@webhook()` - HTTP endpoints for external services
-  - `@trigger()` - React to database changes
-  - `@scheduler()` - Run code on a schedule (cron jobs)
-  - `@secureDatabase()`, `@secureCollection()` - Define who can access data
-  - `@secureAiAgent()` - Control agent access
-  - `@aiFunction()` - Functions that AI agents can call
-  - And many more decorators for security, rate limiting, etc.
-- Has **full access** to all Squid functionality via pre-initialized `this.squid` client (with API key permissions)
-- Deployed to Squid infrastructure using `squid deploy`
-
-**Example backend service:**
-```typescript
-import { SquidService, executable, scheduler, trigger, secureCollection } from '@squidcloud/backend';
-
-export class MyService extends SquidService {
-  // Backend function callable from client
-  @executable()
-  async processPayment(amount: number, userId: string): Promise<PaymentResult> {
-    // Full access to Squid - this.squid has API key permissions
-    const user = await this.squid.collection('users').doc({ id: userId }).snapshot();
-
-    // Your business logic here
-    return { success: true, transactionId: '...' };
-  }
-
-  // React to database changes
-  @trigger({ id: 'new-user', collection: 'users', mutationTypes: ['insert'] })
-  async onNewUser(request: TriggerRequest<User>): Promise<void> {
-    await sendWelcomeEmail(request.docAfter);
-  }
-
-  // Scheduled task (cron job)
-  @scheduler({ id: 'daily-report', cron: '0 0 * * *' })
-  async generateDailyReport(): Promise<void> {
-    // Runs every day at midnight
-    const stats = await this.calculateStats();
-    await this.sendReport(stats);
-  }
-
-  // Security rule - who can read users collection
-  @secureCollection('users', 'read')
-  allowUserRead(context: QueryContext): boolean {
-    const userId = this.getUserAuth()?.userId;
-    // Only allow users to read their own data
-    return context.isSubqueryOf('id', '==', userId);
-  }
-
-  // Function that AI agents can call
-  @aiFunction('Gets order status', [
-    { name: 'orderId', type: 'string', required: true }
-  ])
-  async getOrderStatus({ orderId }: { orderId: string }): Promise<string> {
-    const order = await this.squid.collection('orders').doc({ id: orderId }).snapshot();
-    return order?.status || 'not found';
-  }
-}
-```
-
-**Key points:**
-- Backend code has **full permissions** (API key access)
-- Defines **what clients can and cannot do** through security decorators
-- Contains **business logic** that shouldn't be exposed to clients
-- Automatically deployed and scaled by Squid
-
-### 3. Squid Console (Web UI)
-
-**What it is:** A web-based management interface at https://console.getsquid.ai/ for setting up and managing your Squid applications.
-
-**What you can do in the Console:**
-- **Organizations & Applications:**
-  - Create organizations (teams/workspaces)
-  - Create applications (projects)
-  - Manage API keys and secrets
-  - View application logs and metrics
-
-- **AI Studio:**
-  - Create and configure AI agents visually
-  - Set up agent instructions, models, and guardrails
-  - Test agents in real-time
-  - Connect agents to functions and knowledge bases
-
-- **Knowledge Bases:**
-  - Create knowledge bases for RAG (Retrieval Augmented Generation)
-  - Upload documents and manage contexts
-  - Configure embedding models
-
-- **Integrations:**
-  - Connect databases (PostgreSQL, MySQL, MongoDB, etc.)
-  - Connect SaaS services (Stripe, Slack, etc.)
-  - Configure OAuth integrations
-  - Set up storage providers (AWS S3, etc.)
-  - Configure message queues (Kafka, etc.)
-
-- **Monitoring & Debugging:**
-  - View real-time logs
-  - Monitor API usage
-  - Debug agent conversations
-  - Track performance metrics
-
-**Console vs SDK:**
-- **Console is great for:** Initial setup, visual agent configuration, quick testing, monitoring
-- **SDK is more powerful for:** Programmatic control, CI/CD pipelines, dynamic configuration, complex automation
-
-**Example: Everything in Console can be done via SDK (except creating orgs/apps):**
-
-```typescript
-// Console: Click to create an agent with AI Studio
-// SDK equivalent:
-const agent = squid.ai().agent('my-agent');
-await agent.upsert({
-  description: 'Customer support agent',
-  options: {
-    model: 'gpt-4o',
-    instructions: 'You are a helpful support agent...'
-  }
-});
-
-// Console: Upload document to knowledge base
-// SDK equivalent:
-const kb = squid.ai().knowledgeBase('docs');
-await kb.upsertContext({
-  contextId: 'doc-1',
-  text: 'Product documentation...'
-}, pdfFile);
-
-// Console: Configure database integration
-// SDK equivalent:
-const integrations = squid.admin().integrations();
-await integrations.upsertIntegration({
-  integrationId: 'my-db',
-  type: 'postgres',
-  connectionString: 'postgresql://...'
-});
-```
-
-**Key point:** The Console provides a visual interface for management, and everything can be automated through the SDK for more flexibility and control. For organization and application management, use the **ManagementClient** (see below).
-
-### 4. ManagementClient (Programmatic Org/App Management)
-
-**What it is:** A specialized client for programmatically managing Squid organizations and applications using management API keys.
-
-**How it works:**
-- Uses management API keys (created in Console Profile Settings)
-- Provides methods to create organizations and applications
-- Works independently of the main Squid client
-- Authenticated via management API key (starts with `squid_mgmt_`)
-
-**Creating Management API Keys:**
-1. Go to Squid Console → Profile Settings → API Keys
-2. Click "Create API Key"
-3. Copy the key value (shown only once)
-4. Key format: `squid_mgmt_<uuid>`
-
-**Usage:**
-
-```typescript
-import { ManagementClient } from '@squidcloud/client';
-
-// Initialize with management API key
-const client = new ManagementClient({
-  apiKey: 'squid_mgmt_xxx...',  // From Console Profile Settings
-  region: 'us-east-1.aws'       // Your Squid region
-});
-
-// Create an organization
-const { organizationId } = await client.createOrganization({
-  name: 'My Organization'  // 2-50 characters
-});
-console.log('Created org:', organizationId);
-
-// Create an application in the organization
-const { appId, devApiKey, prodApiKey } = await client.createApplication({
-  organizationId,
-  name: 'My Application',
-  region: 'us-east-1.aws'  // SquidRegion (e.g., 'us-east-1.aws', 'us-central1.gcp')
-});
-console.log('Created app:', appId);
-
-// Delete an application
-await client.deleteApplication(appId);
-```
-
-**Available Methods:**
-
-| Method | Description |
-|--------|-------------|
-| `createOrganization({ name })` | Creates a new organization. User becomes admin. |
-| `createApplication({ organizationId, name, region })` | Creates an application in an organization. Returns `{ appId, devApiKey, prodApiKey }`. |
-| `deleteApplication(appId)` | Deletes an application. Requires admin role. |
-
-**TypeScript Types:**
-
-```typescript
-import {
-  ManagementClient,
-  ManagementClientOptions,
-  ManagementCreateOrganizationRequest,
-  ManagementCreateOrganizationResponse,
-  ManagementCreateApplicationRequest,
-  ManagementCreateApplicationResponse,
-} from '@squidcloud/client';
-```
-
-**Key Points:**
-- Management API keys are tied to a user account
-- The user associated with the key becomes the organization admin
-- Keys can be suspended/reactivated/deleted in Console Profile Settings
-- Different from app API keys (which bypass security rules)
-- Use for CI/CD pipelines, automation scripts, and programmatic management
-
-**Use Cases:**
-- Automated tenant provisioning (multi-tenant SaaS)
-- CI/CD pipeline integration
-- Infrastructure-as-code workflows
-- Programmatic organization management
-- Automated testing environments
-
-### How They Work Together
-
-```
-┌─────────────────────┐     ┌─────────────────────┐
-│   CLIENT (Web/      │     │  MANAGEMENT CLIENT  │
-│   Mobile/Server)    │     │  (Automation)       │
-│                     │     │                     │
-│  - Squid SDK init   │     │  - ManagementClient │
-│  - User auth        │     │  - Management API   │
-│  - Limited access   │     │    key auth         │
-└──────────┬──────────┘     │  - Create orgs/apps │
-           │                └──────────┬──────────┘
-           │                           │
-           │ HTTP/WebSocket            │ HTTP
-           │                           │
-           ▼                           ▼
-┌─────────────────────────────────────────────────┐
-│                 SQUID BACKEND                    │
-│                 (Your Code)                      │
-│                                                  │
-│  - SquidService          - Decorators           │
-│  - Full permissions      - Business logic       │
-│  - Security rules        - Webhooks             │
-└──────────────────────────┬──────────────────────┘
-                           │
-                           │ Deployed via CLI
-                           │ or managed via
-                           ▼
-┌─────────────────────────────────────────────────┐
-│                  SQUID CONSOLE                   │
-│                  (Web UI)                        │
-│                                                  │
-│  - Manage apps           - AI Studio            │
-│  - Integrations          - Monitoring           │
-│  - Management API Keys   - Profile Settings     │
-└─────────────────────────────────────────────────┘
-```
-
-**Development workflow:**
-1. Create application in **Squid Console** (or programmatically via **ManagementClient**)
-2. Develop backend services in **Squid Backend** (local development with `squid start`)
-3. Deploy backend to Squid infrastructure (`squid deploy`)
-4. Build **Client** applications that use the Squid Client SDK
-5. Use **Console** for monitoring and management, or use **SDK** for programmatic control
-6. Use **ManagementClient** for automated org/app provisioning (CI/CD, multi-tenant SaaS)
-
-## CLI Commands
-
-### Installation
-```bash
-npm install -g @squidcloud/cli
-```
-
-### `squid init <project-name>`
-Creates new backend project with `.env` and example service.
-The backend project has access to an already initialized client SDK with API key (full permissions)
-
-```bash
-squid init backend --appId YOUR_APP_ID --apiKey YOUR_API_KEY --environmentId dev --squidDeveloperId YOUR_DEV_ID --region us-east-1.aws
-```
-
-### `squid start`
-Runs backend locally with hot-reload, connects to Squid Cloud via reverse proxy.
-
-```bash
-cd backend
-squid start
-```
-
-**Extended logging in `.env`:**
-```env
-SQUID_LOG_TYPES=QUERY,MUTATION,AI,API,ERROR
-```
-
-### `squid deploy`
-Builds and deploys to Squid Cloud.
-
-```bash
-squid deploy [--apiKey KEY] [--environmentId prod] [--skipBuild]
-```
-
-### `squid build`
-Builds backend project.
-
-```bash
-squid build [--dev] [--skip-version-check]
-```
-
-## Client SDK
-
-### Where Can You Use the SDK?
-
-The Squid Client SDK can be instantiated in various environments:
-- **Web applications** (vanilla JavaScript, React, Vue, Angular, etc.)
-- **Node.js servers** (Express, Fastify, etc.)
-- **Mobile applications** (React Native, etc.)
-- **Desktop applications** (Electron, etc.)
-
-**Important:** When writing backend code that runs on Squid's infrastructure, the Squid client is **already initialized and available with API key and full permissions** for you (see Backend SDK section). You don't need to manually create a new instance.
-
-### Initialization
-
-#### Configuration Options
-
-**Required Parameters:**
-- **`appId`** (string): Your Squid application identifier. Can be found in the Squid Console.
-- **`region`** (string): The region where your Squid application is deployed:
-  - AWS regions: `'us-east-1.aws'`, `'ap-south-1.aws'`, `'eu-central-1.aws'`
-  - GCP regions: `'us-central1.gcp'`
-
-**Optional Parameters:**
-- **`apiKey`** (string): API key that bypasses security rules and provides full administrative access.
-  - **IMPORTANT**: Has **complete control over your application** and bypasses all security rules
-  - Only use in trusted environments (backend servers, admin tools, development)
-  - **Never expose in client-side code** (web browsers, mobile apps)
-- **`authProvider`** (object): Authentication provider that supplies OAuth2.0 tokens for the current user
-  - `integrationId` (string): The ID of your auth integration
-  - `getToken` (function): Returns a promise that resolves to the user's auth token (or undefined if not authenticated)
-  - Authentication details are **available in backend functions** via the execution context
-- **`environmentId`** (string): Environment identifier (dev, staging, prod). Defaults to production.
-- **`squidDeveloperId`** (string): Your developer identifier, used for local development and debugging.
-- **`consoleRegion`** (string): Console region (optional)
-
-#### Basic Setup
-
-```typescript
-import { Squid } from '@squidcloud/client';
-
-const squid = new Squid({
-  appId: 'your-app-id',
-  region: 'us-east-1.aws',
-  environmentId: 'dev' // optional
-});
-```
-
-#### Authentication: API Key vs Auth Provider
-
-**Using API Key (Server-Side Only):**
-```typescript
-const squid = new Squid({
-  appId: 'your-app-id',
-  region: 'us-east-1.aws',
-  apiKey: 'your-api-key' // Full admin access
-});
-```
-- **Use cases**: Backend servers, admin tools, scripts, development environments
-- **Security**: Has full control - bypasses all security rules
-- **Warning**: Never use in client-side code
-
-**Using Auth Provider (Client-Side):**
-```typescript
-const squid = new Squid({
-  appId: 'your-app-id',
-  region: 'us-east-1.aws',
-  authProvider: {
-    integrationId: 'auth-integration-id',
-    getToken: async () => {
-      // Return user's OAuth token
-      return await getCurrentUserToken();
-    }
-  }
-});
-```
-- **Use cases**: Web apps, mobile apps, any user-facing application
-- **Security**: Respects security rules based on authenticated user
-- **Backend access**: User authentication details are available in backend functions through the execution context
-
-**Setting Auth Provider After Initialization:**
-```typescript
-const squid = new Squid({
-  appId: 'your-app-id',
-  region: 'us-east-1.aws'
-});
-
-// Later, when user logs in
-squid.setAuthProvider({
-  integrationId: 'auth-integration-id',
-  getToken: async () => userAuthToken
-});
-```
-
-### Database & Data Management
-
-Squid provides database functionality similar to Firestore but more powerful, with collections, document references, and real-time capabilities. Squid supports multiple database types including NoSQL databases (like MongoDB) and relational databases (like PostgreSQL, MySQL).
-
-#### Security Rules
-
-Every database operation in Squid can be secured using **security rules**. Security rules are backend functions decorated with `@secureDatabase` or `@secureCollection` that contain business logic to determine whether an operation is allowed.
-
-```typescript
-// Example security rule for a collection (read operations)
-@secureCollection('users', 'read')
-async canReadUsers(context: QueryContext<User>): Promise<boolean> {
-  // Your business logic here
-  // context.collectionName, context.integrationId, context.limit, etc.
-  return true; // or false based on your logic
-}
-
-// Example security rule for mutations (insert, update, delete)
-@secureCollection('users', 'update')
-async canUpdateUsers(context: MutationContext): Promise<boolean> {
-  // Access document before and after the mutation
-  const before = context.before;
-  const after = context.after;
-
-  // Check if specific paths were affected
-  if (context.affectsPath('email')) {
-    return false; // Don't allow email changes
-  }
-
-  return true;
-}
-
-// Database-wide security rule
-@secureDatabase('insert', 'my-integration-id')
-async canInsertAnywhere(context: MutationContext): Promise<boolean> {
-  // Your business logic here
-  return context.after?.createdBy === 'admin';
-}
-```
-
-These decorated functions return a boolean (or `Promise<boolean>`) indicating whether the operation is allowed. The developer has full control to implement any business logic needed for authorization.
-
-**Context types:**
-- `QueryContext` - Used for 'read' and 'all' operations (exported from `@squidcloud/backend`)
-- `MutationContext` - Used for 'insert', 'update', 'delete' operations (exported from `@squidcloud/backend`)
-
-Security decorators (`@secureDatabase`, `@secureCollection`) are exported from `@squidcloud/backend`.
-
-#### Collection Access
-
-A collection represents a set of documents (similar to a table in relational databases or a collection in NoSQL databases).
-
-```typescript
-// Get collection reference in the built-in database
-const users = squid.collection<User>('users');
-
-// Get collection reference in a specific integration
-const orders = squid.collection<Order>('orders', 'postgres-db');
-```
-
-**Type parameter**: The generic type `<T>` defines the structure of documents in the collection.
-
-**Document References - The `doc()` method has different behaviors:**
-
-**1. No parameters - `doc()`**
-Generates a new document ID (useful for creating new documents):
-```typescript
-// For built_in_db without schema - generates a random ID
-const newDocRef = collection.doc();
-await newDocRef.insert({ name: 'John', age: 30 });
-
-// For other integrations - creates a placeholder that gets resolved on insert
-const newDocRef = collection.doc();
-```
-
-**2. String parameter - `doc(stringId)`**
-**Only supported for `built_in_db` integration without a defined schema:**
-```typescript
-// Valid only for built_in_db collections without schema
-const docRef = collection.doc('my-doc-id');
-const docRef = collection.doc('user-12345');
-```
-**Important**: For collections with defined schemas or non-built_in_db integrations, you must use object format.
-
-**3. Object parameter - `doc({id: value})`**
-Used for collections with defined primary keys. The object maps primary key field names to their values:
-```typescript
-// Single primary key field "id"
-const docRef = collection.doc({ id: 'user-123' });
-
-// Single primary key field "userId"
-const docRef = collection.doc({ userId: 42 });
-
-// Composite primary key (id1, id2)
-const docRef = collection.doc({ id1: 'part1', id2: 'part2' });
-
-// Partial primary key - missing fields generated on server if supported
-const docRef = collection.doc({ id1: 'part1' }); // id2 generated on insert
-```
-
-**Key points about document IDs:**
-- For `built_in_db` without schema: can use string IDs or object format
-- For `built_in_db` with schema: must use object format matching primary key fields
-- For other integrations: must use object format matching primary key fields
-- Partial primary keys: missing fields may be auto-generated on insert (if integration supports it)
-- Empty `doc()`: generates a placeholder ID that gets resolved when document is created
-
-```typescript
-// Examples:
-
-// Insert
-await userDoc.insert({ name: 'John', email: 'john@example.com' });
-
-// Update (partial)
-await userDoc.update({ name: 'Jane' });
-
-// Update specific path
-await userDoc.setInPath('address.street', 'Main St');
-
-// Delete specific path
-await userDoc.deleteInPath('tempData');
-
-// Delete document
-await userDoc.delete();
-
-// Get data (promise)
-const userData = await userDoc.snapshot();
-console.log(userData);
-
-// Get data (observable - realtime)
-userDoc.snapshots().subscribe(data => {
-  console.log(data);
-});
-
-// Get cached data (no server fetch)
-const cached = userDoc.peek();
-
-// Check if document has data populated
-if (userDoc.hasData) {
-  console.log('Document is loaded');
-  // Access data directly (with defensive copy)
-  console.log(userDoc.data);
-}
-
-// Bulk operations
-await users.insertMany([
-  { id: 'user-1', data: { name: 'Alice' } },
-  { id: 'user-2', data: { name: 'Bob' } }
-]);
-
-await users.deleteMany(['user-1', 'user-2']);
-```
-
-#### Real-time Subscriptions
-
-Squid provides real-time data synchronization similar to Firestore. Subscribe to document or query changes and receive updates automatically.
-
-**Document Subscriptions:**
-```typescript
-// Subscribe to document changes
-const subscription = docRef.snapshots().subscribe((userData) => {
-  if (userData) {
-    console.log('Document updated:', userData);
-  } else {
-    console.log('Document deleted or does not exist');
-  }
-});
-
-// Unsubscribe when done
-subscription.unsubscribe();
-```
-
-**Query Subscriptions:**
-```typescript
-// Subscribe to query results - ALWAYS use dereference()
-const subscription = collection
-  .query()
-  .eq('status', 'active')
-  .gte('age', 18)
-  .dereference()  // Important: Converts DocumentReferences to actual data
-  .snapshots()
-  .subscribe((users) => {
-    console.log('Active users updated:', users);
-    // users is Array<User> with actual data
-  });
-
-// Unsubscribe when done
-subscription.unsubscribe();
-```
-
-**Real-time Updates:**
-When data changes on the server (from any client or backend operation):
-- Document subscriptions receive the updated document data
-- Query subscriptions receive the updated query results
-- Updates are pushed to clients via WebSocket connections
-- Changes are automatically reflected in the local data
-
-**Important**: Always unsubscribe from subscriptions when they're no longer needed to prevent memory leaks.
-
-### Database - Queries
-
-**ALL Available Operators:**
-- Comparison: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`
-- Arrays: `in`, `nin`, `arrayIncludesSome`, `arrayIncludesAll`, `arrayNotIncludes`
-- Patterns: `like`, `notLike` (% = any chars, _ = one char)
-
-```typescript
-// Basic query
-const activeUsers = await users.query()
-  .eq('status', 'active')
-  .gt('age', 18)
-  .sortBy('name', true) // true = ascending
-  .limit(100) // max 20000, default 1000
-  .snapshot();
-
-activeUsers.data.forEach(doc => {
-  console.log(doc.data); // Document data
-});
-
-// Realtime query
-users.query()
-  .eq('status', 'active')
-  .snapshots().subscribe(snapshot => {
-    snapshot.data.forEach(doc => console.log(doc.data));
-  });
-
-// Pattern matching (CASE-INSENSITIVE by default)
-const results = await users.query()
-  .like('email', '%.com') // case-insensitive by default
-  .snapshot();
-
-// Case-sensitive pattern matching
-const caseSensitive = await users.query()
-  .like('name', 'John%', true) // third parameter: caseSensitive = true
-  .snapshot();
-
-// Array operators
-const tagged = await posts.query()
-  .in('category', ['tech', 'news'])
-  .arrayIncludesSome('tags', ['urgent', 'important'])
-  .snapshot();
-
-// Using where() method (all operators above are shortcuts for where)
-const results1 = await users.query().eq('status', 'active').snapshot();
-const results2 = await users.query().where('status', '==', 'active').snapshot();
-// These are equivalent
-
-// OR queries - combine multiple queries with OR logic
-const query1 = users.query().eq('status', 'active');
-const query2 = users.query().eq('status', 'pending');
-const orResults = await users.or(query1, query2)
-  .dereference()
-  .snapshot();
-// Returns documents matching either query
-// Note: Results are merged and deduplicated
-
-// Multiple sort
-const sorted = await users.query()
-  .sortBy('lastName', true)
-  .sortBy('firstName', true)
-  .limit(50)
-  .snapshot();
-
-// Join Queries - combine data from multiple collections
-// Start with joinQuery() and alias
-const results = await teachers
-  .joinQuery('teacher')  // Alias for teachers collection
-  .join(
-    students.query(),
-    'students',           // Alias for students collection
-    { left: 'id', right: 'teacherId' }  // Join condition
-  )
-  .dereference()  // Important: converts refs to actual data
-  .snapshot();
-// Results: Array<{ teacher: Teacher, students?: Student }>
-
-// Inner join (only matching records)
-const innerResults = await teachers
-  .joinQuery('teacher')
-  .join(
-    students.query(),
-    'students',
-    { left: 'id', right: 'teacherId' },
-    { isInner: true }  // Inner join option
-  )
-  .dereference()
-  .snapshot();
-
-// Multi-level joins
-const threeWay = await collection1
-  .joinQuery('a')
-  .join(collection2.query(), 'b', { left: 'id', right: 'parentId' })
-  .join(collection3.query(), 'c', { left: 'id', right: 'grandParentId' })
-  .dereference()
-  .snapshot();
-
-// Grouped joins (nests one-to-many as arrays)
-const grouped = await teachers
-  .joinQuery('teacher')
-  .join(students.query(), 'students', { left: 'id', right: 'teacherId' })
-  .grouped()
-  .dereference()
-  .snapshot();
-// Results: Array<{ teacher: Teacher, students: Student[] }>
-
-// Dereference - Converts DocumentReferences to actual data
-// WITHOUT dereference: returns Array<DocumentReference<User>>
-const refs = await users.query().eq('active', true).snapshot();
-// refs.data[0].data to access actual data
-
-// WITH dereference: returns Array<User> directly
-const userData = await users.query()
-  .eq('active', true)
-  .dereference()
-  .snapshot();
-// userData[0] is the actual user object
-
-// ALWAYS use dereference() for:
-// - Real-time subscriptions (makes working with data easier)
-// - When you need document data directly
-// DON'T use dereference() if:
-// - You need DocumentReference methods like .update() or .delete()
-
-// Pagination
-const pagination = users.query()
-  .sortBy('createdAt', false)
-  .dereference()
-  .paginate({
-    pageSize: 50,       // Number of items per page (default: 100)
-    subscribe: true     // Subscribe to real-time updates (default: true)
-  });
-
-const firstPage = await pagination.first();  // Jump to first page
-const nextPage = await pagination.next();    // Go to next page
-const prevPage = await pagination.prev();    // Go to previous page
-
-// Check pagination state
-console.log(firstPage.hasNext);  // boolean
-console.log(firstPage.hasPrev);  // boolean
-
-// Watch changes
-users.query()
-  .eq('status', 'active')
-  .changes()
-  .subscribe(changes => {
-    console.log('Inserts:', changes.inserts);
-    console.log('Updates:', changes.updates);
-    console.log('Deletes:', changes.deletes);
-  });
-```
-
-**Note:** `offset()` does NOT exist - use `paginate()` for pagination.
-
-### Database - Transactions
-
-```typescript
-await squid.runInTransaction(async (txId) => {
-  const userRef = squid.collection('users').doc('user-1');
-  const accountRef = squid.collection('accounts').doc('acc-1');
-
-  // Pass txId as last parameter to each operation
-  // Use incrementInPath/decrementInPath for numeric operations
-  await userRef.decrementInPath('balance', 100, txId);
-  await accountRef.incrementInPath('balance', 100, txId);
-
-  // Both commit together or rollback together
-});
-```
-
-### Database - Numeric Operations
-
-```typescript
-// Increment/decrement
-await userDoc.incrementInPath('loginCount', 1);
-await userDoc.decrementInPath('credits', 50);
-
-// For arrays/objects, use update() with full new value
-const currentData = await userDoc.snapshot();
-await userDoc.update({
-  tags: [...currentData.tags, 'newTag'],
-  notifications: [...currentData.notifications, { msg: 'Hi' }]
-});
-```
-
-### Database - Native Queries
-
-```typescript
-// SQL (PostgreSQL, MySQL, etc.) - uses ${param} syntax
-const users = await squid.executeNativeRelationalQuery<User[]>(
-  'postgres-db',
-  'SELECT * FROM users WHERE age > ${minAge}',
-  { minAge: 18 }
-);
-
-// MongoDB aggregation
-const orders = await squid.executeNativeMongoQuery<Order[]>(
-  'mongo-db',
-  'orders',
-  [
-    { $match: { status: 'completed' } },
-    { $group: { _id: '$userId', total: { $sum: '$amount' } } }
-  ]
-);
-
-// Elasticsearch
-const products = await squid.executeNativeElasticQuery(
-  'elastic-db',
-  'products',
-  { query: { match: { name: 'laptop' } } },
-  '_search', // endpoint (optional)
-  'GET' // method (optional)
-);
-
-// Pure (Finos Legend Pure Language) - uses ${param} syntax
-const items = await squid.executeNativePureQuery(
-  'my-db',
-  'from products->filter(p | $p.price < ${maxPrice})',
-  { maxPrice: 1000 }
-);
-```
-
-### Database - Security (@secureDatabase, @secureCollection)
-
-Secure your database operations with backend decorators. These are backend-only decorators that define who can access your data.
-
-**Backend - Secure entire database:**
-```typescript
-import { SquidService, secureDatabase, QueryContext, MutationContext } from '@squidcloud/backend';
-
-export class MyService extends SquidService {
-  @secureDatabase('read')
-  allowRead(context: QueryContext<User>): boolean {
-    const userId = this.getUserAuth()?.userId;
-    if (!userId) return false;
-    return context.isSubqueryOf('userId', '==', userId);
-  }
-
-  @secureDatabase('write')
-  allowWrite(context: MutationContext<User>): boolean {
-    return this.isAuthenticated();
-  }
-
-  @secureDatabase('all')
-  allowAll(): boolean {
-    return this.isAuthenticated();
-  }
-}
-```
-
-**Types:** `'read'`, `'write'`, `'update'`, `'insert'`, `'delete'`, `'all'`
-
-**Backend - Secure specific collection:**
-```typescript
-// QueryContext methods (for 'read' operations)
-@secureCollection('users', 'read')
-allowUserRead(context: QueryContext): boolean {
-  const userId = this.getUserAuth()?.userId;
-  if (!userId) return false;
-  // Check if query filters on a specific field
-  return context.isSubqueryOf('id', '==', userId);
-}
-
-// MutationContext methods (for 'insert', 'update', 'delete' operations)
-@secureCollection('users', 'update')
-allowUserUpdate(context: MutationContext<User>): boolean {
-  const userId = this.getUserAuth()?.userId;
-  if (!userId) return false;
-
-  // context.before: document state before mutation
-  // context.after: document state after mutation
-
-  // Check if specific paths were affected
-  if (context.affectsPath('email')) {
-    return false; // Don't allow email changes
-  }
-
-  // Check ownership
-  return context.after?.id === userId;
-}
-```
-
-**Context types (exported from `@squidcloud/backend`):**
-- `QueryContext<T>` - Used for 'read' and 'all' operations
-  - `isSubqueryOf(field, operator, value)` - Check if query filters on field
-  - `collectionName`, `integrationId`, `limit` properties
-- `MutationContext<T>` - Used for 'insert', 'update', 'delete' operations
-  - `affectsPath(path)` - Check if specific field path was modified
-  - `before` - Document before mutation (undefined for insert)
-  - `after` - Document after mutation (undefined for delete)
-
-### Backend Functions (@executable)
-
-Backend functions allow you to write custom server-side logic that can be called from the client.
-
-**Backend - Define the function:**
-```typescript
-import { SquidService, executable, SquidFile } from '@squidcloud/backend';
-
-export class MyService extends SquidService {
-  @executable()
-  async greetUser(name: string): Promise<string> {
-    return `Hello, ${name}`;
-  }
-
-  @executable()
-  async uploadFile(file: SquidFile): Promise<Result> {
-    console.log(file.originalName, file.size, file.data);
-    return { success: true };
-  }
-}
-```
-
-**Client - Call the function:**
-```typescript
-// Execute @executable() decorated function
-const result = await squid.executeFunction('greetUser', 'John');
-const typedResult = await squid.executeFunction<string>('greetUser', 'John');
-
-// With headers
-const result = await squid.executeFunctionWithHeaders(
-  'processPayment',
-  { 'X-Custom-Header': 'value' },
-  paymentData
-);
-```
-
-### Webhooks (@webhook)
-
-Webhooks allow you to create publicly accessible HTTP endpoints that can receive data from external services.
-
-**Backend - Define the webhook:**
-```typescript
-import { SquidService, webhook, WebhookRequest } from '@squidcloud/backend';
-
-export class MyService extends SquidService {
-  @webhook('github-events')
-  async handleGithub(request: WebhookRequest): Promise<any> {
-    console.log(request.body);
-    console.log(request.headers);
-    console.log(request.queryParams);
-    console.log(request.httpMethod); // 'post' | 'get' | 'put' | 'delete'
-    console.log(request.files);
-
-    return this.createWebhookResponse({ received: true }, 200);
-  }
-}
-```
-
-**Webhook URL:** `https://<appId>.<region>.squid.cloud/webhooks/<webhook-id>`
-
-**Client - Get webhook URL:**
-```typescript
-// Get URL for a specific webhook
-const webhookUrl = squid.getWebhookUrl('github-events');
-// Returns: https://<appId>.<region>.squid.cloud/webhooks/github-events
-
-// Get base webhooks URL (no webhook ID)
-const baseUrl = squid.getWebhookUrl();
-// Returns: https://<appId>.<region>.squid.cloud/webhooks
-```
-
-**Client - Call webhook programmatically (optional):**
-```typescript
-// Usually webhooks are called by external services, but you can also call them from client
-const result = await squid.executeWebhook<Response>('github-events', {
-  headers: { 'X-GitHub-Event': 'push' },
-  queryParams: { ref: 'main' },
-  body: { commits: [...] },
-  files: [file1, file2]
-});
-```
-
-### AI - Supported Models
-
-Squid supports multiple AI providers and models. The available models are defined as TypeScript constants in the SDK and can be imported from `@squidcloud/client`:
-
-```typescript
-import {
-  // Chat model constants (by provider)
-  OPENAI_CHAT_MODEL_NAMES,
-  ANTHROPIC_CHAT_MODEL_NAMES,
-  GEMINI_CHAT_MODEL_NAMES,
-  GROK_CHAT_MODEL_NAMES,
-  VENDOR_AI_CHAT_MODEL_NAMES,  // All chat models combined
-
-  // Embedding model constants
-  AI_EMBEDDINGS_MODEL_NAMES,
-  OPENAI_EMBEDDINGS_MODEL_NAMES,
-  VOYAGE_EMBEDDING_MODEL_NAMES,
-
-  // Image generation model constants
-  AI_IMAGE_MODEL_NAMES,
-  OPENAI_IMAGE_MODEL_NAMES,
-  STABLE_DIFFUSION_MODEL_NAMES,
-  FLUX_MODEL_NAMES,
-
-  // Audio model constants
-  AI_AUDIO_TRANSCRIPTION_MODEL_NAMES,
-  OPENAI_AUDIO_CREATE_SPEECH_MODEL_NAMES,
-
-  // Type definitions
-  AiChatModelName,
-  AiEmbeddingsModelName,
-  AiImageModelName,
-  AiAudioTranscriptionModelName,
-  AiAudioCreateSpeechModelName,
-} from '@squidcloud/client';
-```
-
-These constants are the source of truth for available models. Check your installed SDK version for the current list of supported models.
-
-**Model Categories:**
-- **Chat Models**: Used for AI Agents, AI Query, etc. (OpenAI, Anthropic, Gemini, Grok)
-- **Embedding Models**: Used for Knowledge Bases (OpenAI, Voyage)
-- **Image Generation Models**: Used for image creation (DALL-E, Stable Diffusion, Flux)
-- **Audio Models**: Transcription (Whisper, GPT-4o) and Text-to-Speech (TTS-1, GPT-4o-mini-tts)
-
-### AI - Agents
-
-AI Agents are powerful, configurable AI assistants that can interact with your data, call functions, connect to integrations, and collaborate with other agents.
-
-**An AI Agent can:**
-- Maintain conversation history (**memory is enabled by default**)
-- Call backend functions decorated with `@aiFunction`
-- Query databases and APIs through connected integrations
-- Search knowledge bases for relevant information
-- Collaborate with other AI agents
-- Process voice input and generate voice output
-- Accept files as part of chat requests
-
-**Creating and Managing Agents:**
-
-```typescript
-const aiClient = squid.ai();
-
-// Get the built-in agent (no ID required)
-const builtInAgent = aiClient.agent();
-
-// Get a custom agent by ID
-const myAgent = aiClient.agent('my-agent-id');
-
-// Get an agent with an Agent API key (allows calling without App API key, bypasses @secureAiAgent methods)
-const agentWithKey = aiClient.agent('my-agent-id', {
-  apiKey: 'your-agent-api-key'
-});
-
-// Create or update an agent
-await myAgent.upsert({
-  description: 'Customer support assistant',
-  isPublic: false,  // Whether the agent is publicly accessible
-  auditLog: true,   // Enable audit logging for compliance
-  options: {
-    model: 'gpt-4o', // or 'claude-sonnet-4-5-20250929', 'gemini-3-flash'
-    instructions: 'You are a helpful customer support assistant. Be concise and professional.',
-    temperature: 0.7
-  }
-});
-
-// Get agent details
-const agentInfo = await myAgent.get();
-console.log(agentInfo.id, agentInfo.description, agentInfo.options.model);
-
-// Update specific properties
-await myAgent.updateInstructions('You are a technical support specialist.');
-await myAgent.updateModel('claude-sonnet-4-5-20250929');
-await myAgent.updateGuardrails(['no-harmful-content']);
-
-// Delete an agent
-await myAgent.delete();
-
-// List all agents
-const agents = await squid.ai().listAgents();
-agents.forEach(agent => console.log(`${agent.id}: ${agent.description}`));
-
-// Manage agent API keys
-const apiKey = await myAgent.regenerateApiKey();
-console.log('New API key:', apiKey);
-
-const existingKey = await myAgent.getApiKey();
-console.log('Current API key:', existingKey);
-
-// Update agent options at specific path
-await myAgent.setAgentOptionInPath('temperature', 0.9);
-await myAgent.setAgentOptionInPath('options.maxTokens', 2000);
-
-// Update connected agents
-await myAgent.updateConnectedAgents([
-  { agentId: 'helper-agent', description: 'Helps with tasks' }
-]);
-
-// Update or delete custom guardrails
-await myAgent.updateCustomGuardrails('Never reveal sensitive information');
-await myAgent.deleteCustomGuardrail();
-```
-
-**Agent Lifecycle:**
-1. **Creation** - Use `upsert()` to create a new agent with an ID
-2. **Active** - Agent can process requests
-3. **Update** - Use `upsert()` or specific update methods
-4. **Deletion** - Use `delete()` to permanently remove the agent
-
-**Important Notes:**
-- Agent IDs are permanent - once created, you cannot change the ID
-- Deleting an agent does not delete associated chat history
-- The built-in agent (accessed via `agent()` with no ID) cannot be deleted
-- **Agent API Keys**: You can pass an options object with an `apiKey` when calling `agent()`:
-  - Allows calling agent methods without requiring an App API key
-  - Bypasses any `@secureAiAgent` security methods when calling agent ask functions
-  - Useful for direct agent access without app-level authentication
-
-**Connecting Resources to Agents:**
-
-Agents become powerful when connected to resources. You can connect agents to:
-- **Other AI agents** (`connectedAgents`) - Agent collaboration
-- **Backend functions** (`functions`) - Custom logic via `@aiFunction` decorators
-- **Integrations** (`connectedIntegrations`) - Database/API queries
-- **Knowledge bases** (`connectedKnowledgeBases`) - RAG (Retrieval Augmented Generation)
-
-**1. Connected Agents (`connectedAgents`):**
-
-Allow one agent to call another agent as a specialized sub-task handler.
-
-```typescript
-// Define connected agents in upsert or per-request
-const response = await agent.ask('Analyze our sales data and send report to team', {
-  connectedAgents: [
-    {
-      agentId: 'data-analyst-agent',
-      description: 'Analyzes sales data and generates reports'
-    },
-    {
-      agentId: 'email-sender-agent',
-      description: 'Sends emails to team members'
-    }
-  ]
-});
-
-// The main agent can now call these sub-agents when needed
-// Agent orchestration happens automatically based on the prompt
-```
-
-**2. Functions (`functions`):**
-
-Connect backend functions decorated with `@aiFunction` that the agent can call.
-
-```typescript
-// Backend function
-@aiFunction('Gets current inventory for a product', [
-  { name: 'productId', type: 'string', required: true, description: 'Product ID' }
-])
-async getInventory({ productId }: { productId: string }): Promise<number> {
-  return await db.inventory.get(productId);
-}
+- **Client SDK** (`@squidcloud/client`) - TypeScript/JavaScript SDK for frontend. See [client.md](reference/client.md)
+- **Backend SDK** (`@squidcloud/backend`) - TypeScript SDK with decorators for backend. See [backend.md](reference/backend.md)
+- **CLI** (`@squidcloud/cli`) - Local development and deployment tools. See [backend.md](reference/backend.md)
+- **Built-in integrations** - Databases, queues, storage, AI, APIs. See [databases.md](reference/databases.md), [ai.md](reference/ai.md), and [connectors.md](reference/connectors.md).
 
-// Client - Agent uses the function
-const response = await agent.ask('How many units of product-123 do we have?', {
-  functions: ['getInventory'] // Function name or ID
-});
-// Agent automatically calls getInventory() and includes result in response
+## Feature-Specific Guidance
 
-// With predefined parameters (hidden from AI)
-const response = await agent.ask('Send notification', {
-  functions: [
-    {
-      functionId: 'sendEmail',
-      context: { apiKey: 'secret-key' } // Passed to function but hidden from AI
-    }
-  ]
-});
-```
+- **[client.md](reference/client.md)** → client SDK, initialization, setup, auth, login, tokens, OAuth, appId, region, environmentId, apiKey, authProvider, getToken, setAuthProvider, Squid client, frontend, collection, executeFunction, executeFunctionWithHeaders, getWebhookUrl, externalAuth, saveAuthCode, getAccessToken, storage, uploadFile, downloadUrl, queues, produce, consume, distributed locks, acquireLock, withLock, web, aiSearch, getUrlContent, createShortUrl, jobs, getJob, awaitJob, observability, metrics, reportMetric, queryMetrics, notifications, publishNotification, observeNotifications
+- **[console.md](reference/console.md)** → Squid Console, web UI, organizations, applications, AI Studio, knowledge bases, integrations, monitoring, logs, API keys, secrets, testing, debugging, profile settings, management API keys
+- **[ai.md](reference/ai.md)** → AI agents, chat, ask, askWithAnnotations, askAsync, askWithVoiceResponse, transcribeAndChat, transcribeAndAsk, knowledge bases, RAG, embeddings, image generation, audio, transcription, text-to-speech, TTS, connectedAgents, connectedIntegrations, connectedKnowledgeBases, @aiFunction, @secureAiAgent, @secureAiQuery, memory, memoryOptions, voiceOptions, OpenAI, Anthropic, Gemini, Grok, DALL-E, Whisper, MCP, @mcpServer, @mcpTool, executeAiQuery, executeAiApiCall, extraction, createPdf, upsert agent, listAgents
+- **[databases.md](reference/databases.md)** → collections, documents, queries, subscriptions, snapshots, insert, update, delete, CRUD, real-time, dereference, pagination, transactions, query operators, eq, neq, gt, gte, lt, lte, like, in, nin, arrayIncludesSome, arrayIncludesAll, sortBy, limit, join queries, OR queries, @trigger, native queries, SQL, MongoDB, Elasticsearch, incrementInPath, decrementInPath, watch changes, doc()
+- **[backend.md](reference/backend.md)** → SquidService, @executable, @webhook, @trigger, TriggerRequest, @scheduler, @limits, rate limiting, quotas, decorators, backend functions, WebhookRequest, CronExpression, cron, file handling, SquidFile, getUserAuth, isAuthenticated, assertIsAuthenticated, createWebhookResponse, this.squid, this.secrets, @clientConnectionStateHandler, CLI, squid init, squid start, squid deploy, squid build, project structure
+- **[security.md](reference/security.md)** → security rules, @secureDatabase, @secureCollection, @secureTopic, @secureStorage, @secureApi, @secureNativeQuery, @secureAiQuery, @secureAiAgent, @secureDistributedLock, @secureGraphQL, QueryContext, MutationContext, isSubqueryOf, affectsPath, permissions, authorization, row-level security, role-based access
+- **[admin.md](reference/admin.md)** → ManagementClient, management API keys, organizations, applications, programmatic management, CI/CD, automation, integrations admin, secrets admin, upsertIntegration, discoverDataConnectionSchema, testDataConnection, createOrganization, createApplication
+- **[api.md](reference/api.md)** → API, REST API, HTTP endpoints, API reference, Agent API, AI Audio API, AI Image API, KnowledgeBase API, Matchmaking API, Web Utilities API, Database API, Extraction API
+- **[openai.md](reference/openai.md)** → OpenAI, code interpreter, verbosity, reasoning models, o1, o3, gpt-5, DALL-E, Whisper, TTS, voice options, structured output, file upload
+- **[connectors.md](reference/connectors.md)** → connectors, integrations, IntegrationType, postgres, mongo, auth0, s3, kafka, salesforce, essentials connector, built-in connector
+- **React Hooks** → See `squid-react-development` skill
 
-**3. Connected Integrations (`connectedIntegrations`):**
+## Architecture
 
-Connect database or API integrations so the agent can query them directly.
+### Components
 
-```typescript
-const response = await agent.ask('Show me active users from last week', {
-  connectedIntegrations: [
-    {
-      integrationId: 'postgres-db',
-      integrationType: 'database',
-      description: 'Main application database with users, orders, and products',
-      instructions: 'Only query the users table unless explicitly asked otherwise',
-      options: {
-        // Integration-specific options (varies by integration type)
-      }
-    },
-    {
-      integrationId: 'stripe-api',
-      integrationType: 'api',
-      description: 'Stripe payment API for retrieving payment information'
-    }
-  ]
-});
+- **Client SDK** (`@squidcloud/client`) - Runs in browser or Node.js. Queries, subscriptions, AI, storage.
+- **Squid Cloud** - Managed infrastructure that handles auth, routing, WebSockets, and deployment.
+- **Your Backend** (`@squidcloud/backend`) - Optional custom code. SquidService classes with decorators.
+- **Integrations** - External services (databases, AI providers, storage). Configured in Squid Console.
 
-// Agent can now query the database and API to answer questions
-```
+**Flow:** Client SDK → Squid Cloud → [Your Backend] → Integrations
 
-**4. Connected Knowledge Bases (`connectedKnowledgeBases`):**
+Squid Cloud is always in the middle. Your Backend is optional - only needed for custom logic, security rules, triggers, etc.
 
-Connect knowledge bases for RAG (Retrieval Augmented Generation) - agent retrieves relevant context before answering.
+### Data Flow
 
-```typescript
-const response = await agent.ask('What is our return policy?', {
-  connectedKnowledgeBases: [
-    {
-      knowledgeBaseId: 'company-policies-kb',
-      description: 'Use this when asked about company policies, procedures, or guidelines'
-    },
-    {
-      knowledgeBaseId: 'product-docs-kb',
-      description: 'Use this when asked about product features, specifications, or usage'
-    }
-  ]
-});
+**Direct operations (without backend):**
+- Collection queries
+- AI agent chat
+- Storage uploads
+- Real-time subscriptions
 
-// Agent searches knowledge bases for relevant information before answering
-```
+**Backend operations (requires backend code):**
 
-**Complete Agent Chat Options:**
+Client → Squid Cloud → Your Backend → Integration → Response
 
-```typescript
-const agent = squid.ai().agent('my-agent');
+- Custom functions (`@executable`)
+- Webhooks (`@webhook`)
+- Triggers (`@trigger`)
+- Scheduled jobs (`@scheduler`)
 
-// Chat (streaming) - Returns RxJS Observable
-// IMPORTANT: Streaming behavior:
-// - NO connected resources: streams token-by-token
-// - HAS connected resources: emits ONCE with complete response
-const chatObs = agent.chat('What is your return policy?', {
-  // Memory management
-  memoryOptions: {
-    memoryMode: 'read-write', // 'none' | 'read-only' | 'read-write'
-    memoryId: 'user-123',     // Unique per user/session
-    expirationMinutes: 1440   // 24 hours
-  },
+### When Backend Code is Needed
 
-  // Connected resources (can also be set on agent.upsert)
-  connectedAgents: [{ agentId: 'specialist-agent', description: 'Handles X' }],
-  functions: ['function1', 'function2'], // or with context: [{ functionId: 'fn', context: {...} }]
-  connectedIntegrations: [{ integrationId: 'db', integrationType: 'database', description: '...' }],
-  connectedKnowledgeBases: [{ knowledgeBaseId: 'kb1', description: 'When to use this KB' }],
+| Use Case | Backend Required? | Why |
+|----------|-------------------|-----|
+| Query a database | No | Client SDK queries directly via Squid Cloud |
+| Chat with AI agent | No | Client SDK calls AI directly |
+| Upload files | No | Client SDK uploads directly |
+| Real-time subscriptions | No | Client SDK uses WebSocket via Squid Cloud |
+| Custom business logic | **Yes** | Use `@executable` functions |
+| Security rules | **Yes** | Use `@secure*` decorators |
+| Database triggers | **Yes** | Use `@trigger` decorator |
+| Webhooks from external services | **Yes** | Use `@webhook` decorator |
+| Scheduled jobs | **Yes** | Use `@scheduler` decorator |
+| Server-side secrets | **Yes** | Access via `this.secrets` |
 
-  // Model & generation
-  model: 'gpt-4o', // Override agent's default model
-  temperature: 0.7,
-  maxTokens: 4000,
-  maxOutputTokens: 2000,
-  instructions: 'Additional instructions for this request only',
-  responseFormat: 'json_object', // or 'text'
-  verbosity: 'medium', // 'low' | 'medium' | 'high' (OpenAI only)
-  reasoningEffort: 'high', // 'minimal' | 'low' | 'medium' | 'high' (for reasoning models)
+### What Squid Cloud Handles
 
-  // Context & RAG
-  disableContext: false, // Disable all context
-  enablePromptRewriteForRag: false, // Rewrite prompt for better RAG results
-  includeReference: false, // Include source references in response
-  contextMetadataFilterForKnowledgeBase: {
-    'kb-id': { category: 'documentation' } // Filter KB contexts by metadata
-  },
+- **Authentication** - Validates tokens, manages sessions
+- **Request routing** - Routes client requests to backend or integrations
+- **WebSocket management** - Maintains connections for real-time subscriptions
+- **Security enforcement** - Runs `@secure*` decorators before allowing operations
+- **Deployment** - Runs your backend code in managed environment
+- **Monitoring** - Logs, metrics, observability
 
-  // Guardrails & quotas
-  guardrails: ['no-harmful-content', 'no-pii'], // Preset safety rules
-  quotas: {
-    maxAiCallStackSize: 5 // Max depth for nested agent calls
-  },
+### Development Workflow
 
-  // Files & voice
-  fileUrls: [
-    { id: 'file1', type: 'image', purpose: 'context', url: 'https://...', description: 'Product image' }
-  ],
-  voiceOptions: {
-    modelName: 'tts-1',
-    voice: 'alloy', // alloy, ash, ballad, coral, echo, fable, onyx, nova, sage, shimmer, verse
-    speed: 1.0
-  },
+1. Create app in **Squid Console** → get `appId` and `apiKey`
+2. `squid init` → creates backend project
+3. `squid start` → develop locally with hot-reload, reverse proxy to Squid Cloud
+4. `squid deploy` → deploy to Squid Cloud
+5. Build frontend with **Client SDK** → connects to your backend
 
-  // Advanced
-  smoothTyping: true, // Smooth typing effect (default: true)
-  useCodeInterpreter: 'llm', // 'none' | 'llm' (OpenAI/Gemini only)
-  executionPlanOptions: {
-    enabled: true, // Agent plans which resources to use
-    model: 'gpt-4o',
-    reasoningEffort: 'high',
-    allowClarificationQuestions: false // Allow agent to ask follow-up questions (default: false)
-  },
-  agentContext: { userId: '123', role: 'admin' }, // Global context passed to all functions
-  includeMetadata: false // Include context metadata in response
-});
-
-chatObs.subscribe(text => {
-  console.log(text);
-});
-
-// Ask (complete response - same options as chat)
-const response = await agent.ask('Question?', { /* same options */ });
-
-// Ask with annotations (includes file references, citations)
-const result = await agent.askWithAnnotations('Question?', { /* same options as ask */ });
-console.log(result.responseString);
-console.log(result.annotations); // File references, sources, etc.
-
-// Ask asynchronously (doesn't wait for response, uses job system)
-await agent.askAsync('Long running task', 'job-id-123', { /* same options */ });
-// Check job status later with squid.job().getJob('job-id-123')
-
-// Voice responses
-const voiceResult = await agent.askWithVoiceResponse('Hello', {
-  voiceOptions: { modelName: 'tts-1', voice: 'alloy', speed: 1.0 }
-});
-console.log(voiceResult.responseString);
-console.log(voiceResult.voiceResponseFile);
-
-// Transcribe audio and chat
-const transcribeResult = await agent.transcribeAndChat(audioFile);
-console.log(transcribeResult.transcribedPrompt);
-transcribeResult.responseStream.subscribe(text => console.log(text));
-
-// Transcribe audio and ask (non-streaming)
-const askResult = await agent.transcribeAndAsk(audioFile, { /* ask options */ });
-console.log(askResult.transcribedPrompt);
-console.log(askResult.response);
-
-// Transcribe audio and get voice response
-const voiceResponse = await agent.transcribeAndAskWithVoiceResponse(audioFile, {
-  voiceOptions: { modelName: 'tts-1', voice: 'alloy' }
-});
-console.log(voiceResponse.transcribedPrompt);
-console.log(voiceResponse.responseString);
-console.log(voiceResponse.voiceResponseFile);
-
-// Get chat history
-const history = await agent.getChatHistory('memory-id-123');
-
-// Semantic search across agent's knowledge
-const results = await agent.search({ prompt: 'product docs', limit: 10 });
-
-// Provide feedback on responses
-await agent.provideFeedback('thumbs_up'); // or 'thumbs_down'
-
-// Observe status updates (for long-running operations)
-agent.observeStatusUpdates().subscribe(status => {
-  console.log(status.title, status.tags);
-});
-```
-
-**Agent Security (@secureAiAgent):**
-
-Secure agent access on the backend:
-
-**Backend:**
-```typescript
-import { SquidService, secureAiAgent } from '@squidcloud/backend';
-
-export class MyService extends SquidService {
-  // Secure specific agent
-  @secureAiAgent('customer-support-agent')
-  allowCustomerAgent(): boolean {
-    return this.isAuthenticated();
-  }
-
-  // Secure all agents
-  @secureAiAgent()
-  allowAllAgents(): boolean {
-    return this.isAuthenticated();
-  }
-}
-```
-
-**Important Notes:**
-- Connected resources can be set on agent creation/update OR per-request
-- Per-request settings override agent-level settings
-- Agent automatically decides when to use connected resources based on the prompt
-- `executionPlanOptions` enables the agent to create a plan before using resources (improves accuracy)
-- `chatId` and `profileId` are deprecated - use `memoryOptions` instead
-
-### AI - Knowledge Bases
-
-```typescript
-const kb = squid.ai().knowledgeBase('product-docs');
-
-// Get knowledge base details
-const kbDetails = await kb.getKnowledgeBase();
-console.log(kbDetails);
-
-// Create or update knowledge base
-await kb.upsertKnowledgeBase({
-  description: 'Product documentation knowledge base',
-  // ...other options
-});
-
-// Delete knowledge base
-await kb.delete();
-
-// List all knowledge bases
-const allKBs = await squid.ai().listKnowledgeBases();
-
-// Upsert context (with or without file)
-await kb.upsertContext({
-  contextId: 'doc-123',
-  text: 'Product documentation...',
-  metadata: { category: 'user-guide', version: '2.0' }
-}, optionalFile);
-
-// Batch upsert
-await kb.upsertContexts([
-  { contextId: 'doc-1', text: '...' },
-  { contextId: 'doc-2', text: '...' }
-], optionalFiles);
-
-// Search with prompt
-const results = await kb.searchContextsWithPrompt({
-  prompt: 'How do I reset password?',
-  limit: 5,
-  metadata: { category: 'user-guide' }
-});
-
-// Search by context ID
-const related = await kb.searchContextsWithContextId({
-  contextId: 'doc-123',
-  limit: 10
-});
-
-// Semantic search (returns chunks)
-const searchResults = await kb.search({
-  prompt: 'authentication',
-  limit: 10
-});
-
-// Get context
-const context = await kb.getContext('doc-123');
-
-// List contexts
-const allContexts = await kb.listContexts(1000); // truncateTextAfter
-const contextIds = await kb.listContextIds();
-
-// Download context
-const download = await kb.downloadContext('doc-123');
-
-// Delete contexts
-await kb.deleteContext('doc-123');
-await kb.deleteContexts(['doc-1', 'doc-2']);
-
-// List all knowledge bases
-const allKBs = await squid.ai().listKnowledgeBases();
-```
-
-### AI - Files
-
-Manage files stored with AI providers (OpenAI, etc.) for use with agents.
-
-```typescript
-const aiFiles = squid.ai().files('openai'); // provider: 'openai' | 'anthropic' | etc.
-
-// Upload file to AI provider
-const fileId = await aiFiles.uploadFile({
-  file: myFile, // Browser File object
-  purpose: 'assistants' // Purpose for the file
-});
-console.log('Uploaded file ID:', fileId);
-
-// Delete file from AI provider
-const deleted = await aiFiles.deleteFile(fileId);
-console.log('File deleted:', deleted);
-```
-
-### AI - Image & Audio
-
-```typescript
-// Image generation
-const imageUrl = await squid.ai().image().generate(
-  'A futuristic city',
-  { size: '1024x1024', quality: 'hd' }
-);
-
-// Remove background
-const noBgBase64 = await squid.ai().image().removeBackground(imageFile);
-
-// Transcribe audio
-const text = await squid.ai().audio().transcribe(audioFile, {
-  language: 'en'
-});
-
-// Text-to-speech
-const audioFile = await squid.ai().audio().createSpeech(
-  'Hello world',
-  { modelName: 'tts-1', voice: 'alloy', speed: 1.0 }
-);
-```
-
-### AI - Query & API Call
-
-AI Query allows you to query your database using natural language prompts. Squid's AI converts your prompt into database queries and returns the results.
-
-```typescript
-// Natural language database query (basic)
-const result = await squid.ai().executeAiQuery(
-  'built_in_db',
-  'Show me all active users who registered last month'
-);
-
-// With options
-const result = await squid.ai().executeAiQuery(
-  'built_in_db',
-  'Show me all active users who registered last month',
-  {
-    instructions: 'Only query the users collection',
-    enableRawResults: true,     // Include raw query results
-    selectCollectionsOptions: {
-      collectionsToUse: ['users'] // Limit to specific collections
-    },
-    generateQueryOptions: {
-      maxErrorCorrections: 3  // Number of retry attempts
-    },
-    analyzeResultsOptions: {
-      enableCodeInterpreter: true // Enable code execution for result analysis
-    }
-  }
-);
-
-// AI-powered API call
-const apiResult = await squid.ai().executeAiApiCall(
-  'stripe-api',
-  'Create a $50 charge for customer cus_123',
-  ['create-charge'], // allowed endpoints
-  true // provide explanation
-);
-```
-
-### AI - Document Extraction & PDF Creation
-
-Extract structured data from documents and create PDFs programmatically.
-
-```typescript
-const extraction = squid.extraction();
-
-// Extract data from document file
-const extractedData = await extraction.extractDataFromDocumentFile(
-  myPdfFile, // File object
-  {
-    schema: {
-      fields: [
-        { name: 'invoiceNumber', type: 'string', description: 'Invoice number' },
-        { name: 'total', type: 'number', description: 'Total amount' },
-        { name: 'date', type: 'date', description: 'Invoice date' }
-      ]
-    }
-  }
-);
-console.log(extractedData);
-
-// Extract data from document URL
-const urlData = await extraction.extractDataFromDocumentUrl(
-  'https://example.com/document.pdf',
-  {
-    schema: {
-      fields: [
-        { name: 'title', type: 'string' },
-        { name: 'author', type: 'string' }
-      ]
-    }
-  }
-);
-
-// Create PDF from HTML or markdown
-const pdfResponse = await extraction.createPdf({
-  content: '<h1>Hello</h1><p>This is a PDF</p>',
-  contentType: 'html', // or 'markdown'
-  options: {
-    pageSize: 'A4',
-    margin: { top: '1cm', bottom: '1cm', left: '1cm', right: '1cm' }
-  }
-});
-console.log('PDF created:', pdfResponse.url);
-```
-
-**Use cases:**
-- Invoice/receipt processing
-- Form data extraction
-- PDF report generation
-- Document digitization
-- Automated data entry
-
-### AI - Application Settings
-
-Manage AI provider settings and API keys for your application.
-
-```typescript
-const aiClient = squid.ai();
-
-// Get application AI settings
-const settings = await aiClient.getApplicationAiSettings();
-console.log(settings);
-
-// Set application AI settings
-await aiClient.setApplicationAiSettings({
-  defaultModel: 'gpt-4o',
-  // ... other settings
-});
-
-// Set AI provider API key secret
-await aiClient.setAiProviderApiKeySecret(
-  'openai', // providerType: 'openai' | 'anthropic' | 'google' | etc.
-  'OPENAI_API_KEY' // secret key name from secrets manager
-);
-```
-
-### Storage
-
-```typescript
-const storage = squid.storage(); // built_in_storage
-const s3 = squid.storage('aws-s3-integration');
-
-// Upload file
-await storage.uploadFile('/documents', file, 3600); // 1 hour expiration
-
-// Get download URL
-const url = await storage.getDownloadUrl('/documents/report.pdf', 3600);
-console.log(url.url);
-
-// Get file metadata
-const metadata = await storage.getFileMetadata('/documents/report.pdf');
-console.log(metadata.filename, metadata.size, metadata.lastModified);
-
-// List directory
-const contents = await storage.listDirectoryContents('/documents');
-console.log(contents.files, contents.directories);
-
-// Delete files
-await storage.deleteFile('/documents/report.pdf');
-await storage.deleteFiles(['/docs/file1.pdf', '/docs/file2.pdf']);
-```
-
-### External OAuth Integration
-
-Manage OAuth tokens for external integrations. Squid automatically handles token refresh when tokens expire.
-
-```typescript
-const externalAuth = squid.externalAuth('google-oauth-integration');
-
-// Save authorization code (exchange for access token)
-const tokenResponse = await externalAuth.saveAuthCode(
-  'authorization-code-from-oauth-flow',
-  'user-identifier' // Unique identifier for this user
-);
-console.log('Access token:', tokenResponse.accessToken);
-console.log('Refresh token:', tokenResponse.refreshToken);
-console.log('Expires at:', tokenResponse.expiresAt);
-
-// Get access token (auto-refreshes if expired)
-const token = await externalAuth.getAccessToken('user-identifier');
-console.log('Current access token:', token.accessToken);
-```
-
-**Use cases:**
-- Google Drive/Calendar integration
-- GitHub OAuth
-- Slack OAuth
-- Any external service requiring OAuth 2.0
-- Squid handles token refresh automatically
-
-### Queues
-
-```typescript
-const queue = squid.queue<Message>('notifications');
-const kafkaQueue = squid.queue<Event>('events', 'kafka-integration');
-
-// Produce messages
-await queue.produce([
-  { type: 'email', to: 'user@example.com' },
-  { type: 'sms', to: '+1234567890' }
-]);
-
-// Consume messages (observable)
-const subscription = queue.consume<Message>().subscribe(message => {
-  console.log('Received:', message);
-});
-
-// Unsubscribe
-subscription.unsubscribe();
-```
-
-### Distributed Locks
-
-```typescript
-// Acquire and release manually
-const lock = await squid.acquireLock('payment-processing');
-try {
-  await processPayment();
-} finally {
-  lock.release(); // Note: release() is synchronous
-}
-
-// Acquire with auto-release timeout (maxHoldTimeMillis)
-const lockWithTimeout = await squid.acquireLock('my-mutex', {
-  maxHoldTimeMillis: 30000 // Auto-release after 30 seconds
-});
-
-// Access lock properties
-console.log(lock.resourceId); // The mutex name: 'payment-processing'
-console.log(lock.lockId); // Unique ID for this lock instance
-console.log(lock.isReleased()); // Check if released: true/false
-
-// Observe release (RxJS Observable)
-const sub = lock.observeRelease().subscribe(() => {
-  console.log('Lock was released');
-});
-// Don't forget to unsubscribe when done
-sub.unsubscribe();
-
-// Automatic release with withLock (recommended)
-const result = await squid.withLock('payment-processing', async (lock) => {
-  // Critical section - only one client can execute at a time
-  await processPayment();
-  return 'success';
-});
-
-// Lock is automatically released even if callback throws
-```
-
-**Important notes:**
-- Lock is automatically released if WebSocket connection is lost
-- If lock is already held by another client, `acquireLock()` will reject
-- `maxHoldTimeMillis` option automatically releases lock after specified duration
-- Use `@secureDistributedLock(mutexName?)` decorator to secure lock access
-- Without API key, you must define security rules for locks
-
-### API Integration
-
-```typescript
-const api = squid.api();
-
-// HTTP methods - All return HttpResponse<T> with status, headers, and body
-const customerResponse = await api.get<Customer>('stripe-api', 'get-customer', {
-  pathParams: { customerId: 'cus_123' },
-  queryParams: { expand: 'subscriptions' }
-});
-// Access response details
-console.log(customerResponse.status); // HTTP status code
-console.log(customerResponse.headers); // Response headers
-console.log(customerResponse.body); // Parsed response body
-
-const chargeResponse = await api.post<Charge, ChargeRequest>(
-  'stripe-api',
-  'create-charge',
-  { amount: 1000, currency: 'usd' },
-  { headers: { 'Idempotency-Key': 'unique' } }
-);
-
-// Generic request method (for custom HTTP methods or complex requests)
-const response = await api.request<ResponseType, RequestType>(
-  'integration-id',
-  'endpoint-id',
-  requestBody,
-  { headers: {}, queryParams: {} },
-  'POST' // or 'GET', 'PUT', 'PATCH', 'DELETE'
-);
-
-// Other methods: put, patch, delete
-await api.put(integrationId, endpointId, body, options);
-await api.patch(integrationId, endpointId, body, options);
-await api.delete(integrationId, endpointId, body, options);
-```
-
-### Web
-
-```typescript
-const web = squid.web();
-
-// AI-powered web search
-const results = await web.aiSearch('latest AI developments');
-console.log(results.markdownContent);
-console.log(results.citations);
-
-// Get URL content (as markdown)
-const content = await web.getUrlContent('https://example.com/article');
-
-// URL shortening
-const shortUrl = await web.createShortUrl('https://very-long-url.com', 86400);
-console.log(shortUrl.url, shortUrl.id);
-
-const shortUrls = await web.createShortUrls(['url1', 'url2'], 86400);
-
-await web.deleteShortUrl(shortUrlId);
-await web.deleteShortUrls([id1, id2]);
-```
-
-### Schedulers
-
-```typescript
-const schedulers = squid.schedulers;
-
-// List all
-const all = await schedulers.list();
-
-// Enable/disable
-await schedulers.enable('daily-cleanup');
-await schedulers.enable(['scheduler-1', 'scheduler-2']);
-
-await schedulers.disable('hourly-sync');
-await schedulers.disable(['scheduler-1', 'scheduler-2']);
-```
-
-### Observability & Metrics
-
-```typescript
-const obs = squid.observability;
-
-// Report metric
-await obs.reportMetric({
-  name: 'api_request_count',
-  value: 1,
-  tags: { endpoint: '/users', method: 'GET' },
-  timestamp: Date.now()
-});
-
-// Query metrics
-const metrics = await obs.queryMetrics({
-  metricNames: ['api_request_count'],
-  startTime: startTimestamp,
-  endTime: endTimestamp,
-  groupBy: ['endpoint'],
-  filters: { method: 'GET' },
-  aggregation: 'sum'
-});
-
-// Flush pending
-await obs.flush();
-```
-
-### Custom Notifications
-
-Send custom messages between clients for real-time coordination.
-
-```typescript
-const notifications = squid.getNotificationClient();
-
-// Observe incoming notifications
-const subscription = notifications.observeNotifications().subscribe(payload => {
-  console.log('Received notification:', payload);
-  // payload can be any serializable data
-});
-
-// Publish notification to specific clients - can be done only if Squid was initialized with API key.
-await notifications.publishNotification(
-  { type: 'update', message: 'Data changed' }, // payload
-  ['client-id-1', 'client-id-2'] // target client IDs
-);
-
-// Unsubscribe when done
-subscription.unsubscribe();
-```
-
-**Use cases:**
-- Real-time coordination between users
-- Custom event notifications
-- Client-to-client messaging
-- Broadcast updates to specific users
-
-### Jobs
-
-Jobs allow you to track the status of long-running asynchronous operations. Each job has a unique ID that can be used to query its status or wait for completion.
-
-**Important:** Job IDs must be globally unique and kept private. Anyone who knows a job ID can query its status or result.
-
-```typescript
-const jobClient = squid.job();
-
-// Get job status (returns AsyncJob with status: 'pending' | 'completed' | 'failed')
-const job = await jobClient.getJob<Result>('job-123');
-if (job) {
-  console.log('Status:', job.status);
-  if (job.status === 'completed') {
-    console.log('Result:', job.result);
-  } else if (job.status === 'failed') {
-    console.log('Error:', job.error);
-  }
-}
-
-// Wait for completion (resolves when job finishes or throws if job fails)
-const result = await jobClient.awaitJob<Result>('job-123');
-console.log('Job completed with result:', result);
-```
-
-### Admin - Integrations
-
-**Important:** Admin methods require initialization with an API key. They cannot be used with user authentication.
-
-```typescript
-// Squid must be initialized with apiKey
-const squid = new Squid({ appId: 'app-id', region: 'us-east-1.aws', apiKey: 'your-api-key' });
-
-const integrations = squid.admin().integrations();
-
-// List all or by type
-const all = await integrations.list();
-const databases = await integrations.list('database');
-
-// Get one
-const integration = await integrations.get('postgres-db');
-
-// Create/update
-await integrations.upsertIntegration({
-  integrationId: 'my-postgres',
-  type: 'postgres',
-  connectionString: 'postgresql://...'
-});
-
-// Delete
-await integrations.delete('old-integration');
-await integrations.deleteMany(['int-1', 'int-2']);
-
-// Get integration schema
-const schema = await integrations.getIntegrationSchema<MySchemaType>('postgres-db');
-console.log(schema);
-
-// Set integration schema
-await integrations.setIntegrationSchema('postgres-db', {
-  collections: [
-    {
-      name: 'users',
-      fields: [
-        { name: 'id', type: 'string', primaryKey: true },
-        { name: 'email', type: 'string' },
-        { name: 'name', type: 'string' }
-      ]
-    }
-  ]
-});
-
-// Generate AI descriptions for data schema (collections and fields)
-const schemaResult = await integrations.generateAiDescriptionsForDataSchema('postgres-db', {
-  schema: currentSchema,                    // The current schema of the integration
-  collections: ['users', 'orders'],         // Optional: specific collections to generate for
-  instructions: 'Use business terminology'  // Optional: guide the AI
-});
-console.log(schemaResult.schema); // Schema with AI-generated descriptions
-
-// Generate AI descriptions for associations (relationships between entities)
-const assocResult = await integrations.generateAiDescriptionsForAssociations('postgres-db', {
-  schema: currentSchema,
-  associations: ['User_Order'],             // Optional: specific associations to generate for
-  instructions: 'Explain the business relationship'
-});
-
-// Generate AI descriptions for stored procedures
-const spResult = await integrations.generateAiDescriptionsForStoredProcedures('postgres-db', {
-  schema: currentSchema,
-  storedProcedures: ['calculate_totals'],   // Optional: specific procedures to generate for
-  instructions: 'Describe what the procedure does'
-});
-
-// Generate AI descriptions for API endpoints
-const apiResult = await integrations.generateAiDescriptionsForEndpoints('my-api', {
-  schema: apiSchema,
-  endpoints: ['GET /users', 'POST /orders'], // Optional: specific endpoints to generate for
-  instructions: 'Use REST API terminology'
-});
-
-// Discover schema from a database connection
-const discovered = await integrations.discoverDataConnectionSchema('postgres-db');
-console.log(discovered.schema);              // Discovered tables, columns, relationships
-console.log(discovered.collectionReadiness); // Permission and replication status
-
-// Test a database connection to verify it is working (before or after saving)
-const testResult = await integrations.testDataConnection({
-  id: 'my-postgres',
-  type: 'postgres',
-  configuration: {
-    connectionOptions: {
-      host: 'localhost',
-      port: 5432,
-      database: 'mydb',
-      user: 'user',
-      secrets: { password: 'pass' }
-    }
-  }
-});
-if (testResult.success) {
-  console.log('Connection successful!');
-} else {
-  console.log('Connection failed:', testResult.errorMessage);
-}
-
-// Discover schema from a GraphQL endpoint
-const graphqlSchema = await integrations.discoverGraphQLConnectionSchema('my-graphql', {
-  connectionOptions: {
-    url: 'https://api.example.com/graphql',
-    headers: { 'Authorization': 'Bearer token' }
-  }
-});
-
-// Discover schema from an OpenAPI spec URL
-const openApiSchema = await integrations.discoverOpenApiSchema('my-api', {
-  discoveryOptions: {
-    openApiSpecUrl: 'https://api.example.com/openapi.json',
-    headers: { 'Authorization': 'Bearer token' }
-  }
-});
-
-// Discover schema from an uploaded OpenAPI spec file
-const fileSchema = await integrations.discoverOpenApiSchemaFromFile('my-api');
-```
-
-### Admin - Secrets
-
-```typescript
-const secrets = squid.admin().secrets();
-
-// Get secret
-const value = await secrets.get('STRIPE_KEY');
-
-// Get all
-const all = await secrets.getAll();
-
-// Create/update
-await secrets.upsert('API_KEY', 'secret-value');
-await secrets.upsertMany([
-  { key: 'KEY1', value: 'val1' },
-  { key: 'KEY2', value: 'val2' }
-]);
-
-// Delete
-await secrets.delete('OLD_KEY');
-await secrets.deleteMany(['KEY1', 'KEY2']);
-
-// API Keys
-const apiKeys = secrets.apiKeys;
-await apiKeys.upsert('my-key');
-const key = await apiKeys.get('my-key');
-const allApiKeys = await apiKeys.getAll(); // Get all API keys
-await apiKeys.delete('my-key');
-```
-
-## Backend SDK
-
-### SquidService Base Class
-
-All backend services extend `SquidService`:
-
-```typescript
-import { SquidService } from '@squidcloud/backend';
-
-export class MyService extends SquidService {
-  // Decorated methods
-}
-```
-
-**Important:** In backend code running on Squid's infrastructure, the Squid client is **already initialized and available** via `this.squid`. You don't need to manually create a new instance or provide configuration parameters - simply use the pre-configured client.
-
-**Available properties:**
-
-```typescript
-this.region // 'local' during dev, region in production
-this.backendBaseUrl
-this.secrets // From Squid Console
-this.apiKeys
-this.context // RunContext (appId, clientId, sourceIp, headers, openApiContext)
-this.squid // Pre-initialized Squid client instance (ready to use)
-this.assetsDirectory // Path to public/ folder
-```
-
-**Auth methods:**
-
-```typescript
-// Get user authentication (JWT token)
-this.getUserAuth() // AuthWithBearer | undefined
-  // Returns: { type: 'Bearer', userId: string, expiration: number, attributes: Record<string, any>, jwt?: string }
-
-// Get API key authentication
-this.getApiKeyAuth() // AuthWithApiKey | undefined
-  // Returns: { type: 'ApiKey', apiKey: string }
-
-this.isAuthenticated() // boolean - true if user token OR API key
-this.assertIsAuthenticated() // throws if not authenticated
-this.assertApiKeyCall() // throws if not API key auth
-```
-
-**Helper methods:**
-
-```typescript
-// Create webhook response (for @webhook decorated functions)
-this.createWebhookResponse(body?, statusCode?, headers?)
-// Throws webhook response immediately (interrupts execution)
-this.throwWebhookResponse({ body?, statusCode?, headers? })
-
-// Create OpenAPI response (for OpenAPI/tsoa decorated functions)
-this.createOpenApiResponse(body?, statusCode?, headers?)
-// Throws OpenAPI response immediately (interrupts execution)
-this.throwOpenApiResponse({ body?, statusCode?, headers? })
-
-// Convert browser File to SquidFile for OpenAPI file returns
-await this.convertToSquidFile(file: File): Promise<SquidFile>
-
-// Publish AI status update to specific client (used in @aiFunction)
-await this.publishAiStatusUpdate(update: AiStatusMessage, clientId: ClientId)
-```
-
-### Backend Decorators
-
-This section contains backend decorators that don't have corresponding client methods (triggers, schedulers, security rules, etc.).
-
-#### @trigger(options)
-Responds to database collection changes.
-
-```typescript
-@trigger({ id: 'user-created', collection: 'users', mutationTypes: ['insert'] })
-async onUserCreated(request: TriggerRequest<User>): Promise<void> {
-  console.log(request.mutationType); // 'insert' | 'update' | 'delete'
-  console.log(request.docBefore);
-  console.log(request.docAfter);
-}
-```
-
-#### @scheduler(options)
-Schedules periodic execution using cron expressions.
-
-```typescript
-import { CronExpression } from '@squidcloud/backend';
-
-// Using cron string directly
-@scheduler({ id: 'daily-cleanup', cron: '0 0 * * *' }) // Daily at midnight UTC
-async cleanup(): Promise<void> {
-  console.log('Running cleanup');
-}
-
-// Using predefined CronExpression enum
-@scheduler({ id: 'hourly-sync', cron: CronExpression.EVERY_HOUR })
-async hourlySync(): Promise<void> {
-  console.log('Running hourly sync');
-}
-
-@scheduler({ id: 'weekday-morning', cron: CronExpression.MONDAY_TO_FRIDAY_AT_9AM })
-async weekdayTask(): Promise<void> {
-  console.log('Running weekday morning task');
-}
-
-@scheduler({ id: 'frequent', cron: CronExpression.EVERY_5_MINUTES, exclusive: false })
-async frequentTask(): Promise<void> {
-  // exclusive: false allows concurrent runs
-}
-```
-
-**Common CronExpression values:**
-- `EVERY_SECOND`, `EVERY_5_SECONDS`, `EVERY_10_SECONDS`, `EVERY_30_SECONDS`
-- `EVERY_MINUTE`, `EVERY_5_MINUTES`, `EVERY_10_MINUTES`, `EVERY_30_MINUTES`
-- `EVERY_HOUR`, `EVERY_2_HOURS`, `EVERY_3_HOURS`, etc.
-- `EVERY_DAY_AT_MIDNIGHT`, `EVERY_DAY_AT_NOON`, `EVERY_DAY_AT_1AM`, etc.
-- `EVERY_WEEKDAY`, `EVERY_WEEKEND`, `EVERY_WEEK`
-- `MONDAY_TO_FRIDAY_AT_9AM`, `MONDAY_TO_FRIDAY_AT_5PM`, etc.
-- `EVERY_1ST_DAY_OF_MONTH_AT_MIDNIGHT`, `EVERY_QUARTER`, `EVERY_YEAR`
-
-#### @secureTopic(topicName, type, integrationId?)
-Secures queue topics.
-
-```typescript
-@secureTopic('notifications', 'read')
-allowRead(): boolean {
-  return this.isAuthenticated();
-}
-
-@secureTopic('notifications', 'write')
-allowWrite(context: TopicWriteContext<any>): boolean {
-  return context.messages.length <= 100;
-}
-```
-
-Types: `'read'`, `'write'`, `'all'`
-
-#### @secureStorage(type, integrationId?)
-Secures storage operations.
-
-```typescript
-@secureStorage('write')
-allowWrite(context: StorageContext): boolean {
-  return !context.pathsInBucket.some(p => p.startsWith('/admin'));
-}
-```
-
-Types: `'read'`, `'write'`, `'update'`, `'insert'`, `'delete'`, `'all'`
-
-#### @secureApi(integrationId, endpointId?)
-Secures API integrations.
-
-```typescript
-@secureApi('stripe-api', 'create-charge')
-allowCharge(context: ApiCallContext): boolean {
-  const amount = (context.body as any)?.amount;
-  return amount < 10000;
-}
-
-@secureApi('external-api') // Secures entire API
-allowApi(): boolean {
-  return this.isAuthenticated();
-}
-```
-
-#### @secureNativeQuery(integrationId)
-Secures native database queries.
-
-```typescript
-@secureNativeQuery('postgres-db')
-allowQuery(context: NativeQueryContext): boolean {
-  if (context.type === 'relational') {
-    return !context.query.toUpperCase().includes('DROP');
-  }
-  return true;
-}
-```
-
-#### @secureAiQuery(integrationId?)
-Secures AI query execution.
-
-```typescript
-@secureAiQuery()
-allowAiQuery(context: AiQueryContext): boolean {
-  return this.isAuthenticated() && context.prompt.length < 1000;
-}
-```
-
-#### @secureAiAgent(agentId?)
-Secures AI agent access.
-
-```typescript
-@secureAiAgent('customer-bot')
-allowAgent(context: SecureAiAgentContext): boolean {
-  return !context.prompt?.includes('admin');
-}
-
-@secureAiAgent() // All agents
-allowAllAgents(): boolean {
-  return this.isAuthenticated();
-}
-```
-
-#### @secureDistributedLock(mutexName?)
-Secures distributed lock access.
-
-```typescript
-// Secure specific mutex
-@secureDistributedLock('payment-processing')
-allowPaymentLock(context: DistributedLockContext): boolean {
-  // context.mutex contains the mutex name
-  return this.isAuthenticated() && context.mutex === 'payment-processing';
-}
-
-// Secure all mutexes
-@secureDistributedLock()
-allowAllLocks(context: DistributedLockContext): boolean {
-  return this.isAuthenticated();
-}
-```
-
-**Important:** Without API key, you must define `@secureDistributedLock` decorators to allow lock acquisition.
-
-#### @aiFunction(options)
-Exposes function to AI agents. Agents automatically call these functions based on user prompts.
-
-```typescript
-// Simple form: description and params array
-@aiFunction('Returns the names of the pirates crew on a given ship name', [
-  { name: 'shipName', type: 'string', required: true, description: 'The name of the ship' }
-])
-async getShipCrew({ shipName }: { shipName: string }): Promise<string[]> {
-  const crew = await getCrew(shipName);
-  return crew.map(m => m.name);
-}
-
-// Options object form with more control
-@aiFunction({
-  id: 'custom-function-id',  // Optional custom ID
-  description: 'Get user profile',
-  params: [
-    { name: 'userId', type: 'string', required: true, description: 'User ID' }
-  ],
-  attributes: {
-    integrationType: ['salesforce']  // Only available when specific integrations connected
-  }
-})
-async getUserProfile(
-  params: { userId: string },
-  context: AiFunctionCallContext
-): Promise<User> {
-  console.log('Agent ID:', context.agentId);
-  console.log('Integration ID:', context.integrationId);
-  return { userId: params.userId, name: 'John' };
-}
-
-// Parameter types: 'string' | 'number' | 'boolean' | 'date' | 'files'
-@aiFunction('Books a hotel room', [
-  { name: 'hotelName', type: 'string', required: true, description: 'Name of hotel' },
-  { name: 'checkInDate', type: 'date', required: true, description: 'Check-in date' },
-  { name: 'numberOfGuests', type: 'number', required: true, description: 'Number of guests' },
-  { name: 'breakfast', type: 'boolean', required: false, description: 'Include breakfast' },
-  { name: 'roomType', type: 'string', required: true, description: 'Type of room',
-    enum: ['single', 'double', 'suite'] }
-])
-async bookHotel(args: BookingArgs): Promise<string> {
-  return `Booked ${args.roomType} room at ${args.hotelName}`;
-}
-
-// Using predefined parameters (hidden from AI)
-// Call from client with: agent.ask(prompt, {
-//   functions: ['sendEmail'],
-//   predefinedParams: { sendEmail: { apiKey: 'secret' } }
-// })
-@aiFunction('Sends an email', [
-  { name: 'recipient', type: 'string', required: true, description: 'Email recipient' },
-  { name: 'subject', type: 'string', required: true, description: 'Email subject' },
-  { name: 'body', type: 'string', required: true, description: 'Email body' }
-])
-async sendEmail(args: { recipient: string; subject: string; body: string; apiKey?: string }): Promise<string> {
-  await emailService.send(args.apiKey, args.recipient, args.subject, args.body);
-  return 'Email sent successfully';
-}
-```
-
-**Using functions from client:**
-```typescript
-const response = await agent.ask('What is the crew of the Black Pearl?', {
-  functions: ['getShipCrew', 'getShipDetails']  // Function names or custom IDs
-});
-```
-
-#### @limits(options)
-Rate/quota limiting.
-
-```typescript
-// Simple rate limit (5 QPS globally)
-@limits({ rateLimit: 5 })
-async limited(): Promise<void> {}
-
-// Quota (100 calls/month per user)
-@limits({ quotaLimit: { value: 100, scope: 'user', renewPeriod: 'monthly' } })
-async quotaLimited(): Promise<void> {}
-
-// Multiple limits
-@limits({
-  rateLimit: [
-    { value: 100, scope: 'global' },
-    { value: 10, scope: 'user' }
-  ],
-  quotaLimit: [
-    { value: 10000, scope: 'global', renewPeriod: 'monthly' },
-    { value: 500, scope: 'user', renewPeriod: 'weekly' }
-  ]
-})
-async multiLimited(): Promise<void> {}
-```
-
-Scopes: `'global'`, `'user'`, `'ip'`
-Periods: `'hourly'`, `'daily'`, `'weekly'`, `'monthly'`, `'quarterly'`, `'annually'`
-
-## Common Patterns
-
-### Authentication
-
-Client:
-```typescript
-const squid = new Squid({
-  appId: 'YOUR_APP_ID',
-  region: 'us-east-1.aws',
-  authProvider: {
-    integrationId: 'auth0',
-    getToken: async () => await auth0.getAccessTokenSilently()
-  }
-});
-```
-
-Backend:
-
-```typescript
-@executable()
-async getUserData(): Promise<UserData> {
-  this.assertIsAuthenticated();
-  const userId = this.getUserAuth()?.userId;
-  if (!userId) throw new Error('User not authenticated');
-  return await fetchUserData(userId);
-}
-
-@secureCollection('users', 'read')
-allowRead(context: QueryContext): boolean {
-  const userId = this.getUserAuth()?.userId;
-  if (!userId) return false;
-  return context.isSubqueryOf('id', '==', userId);
-}
-```
-
-### File Upload
-
-Client:
-```typescript
-const file: File = ...; // from input
-await squid.storage().uploadFile('/uploads', file);
-// OR
-await squid.executeFunction('processFile', file);
-```
-
-Backend:
-```typescript
-@executable()
-async processFile(file: SquidFile): Promise<Result> {
-  console.log(file.originalName, file.size, file.mimetype);
-  const content = new TextDecoder().decode(file.data);
-  return { processed: true };
-}
-```
-
-### Using Squid Client in Backend
-
-```typescript
-export class MyService extends SquidService {
-  @executable()
-  async aggregateStats(userId: string): Promise<Stats> {
-    const orders = await this.squid.collection('orders')
-      .query()
-      .eq('userId', userId)
-      .snapshot();
-
-    return { totalOrders: orders.data.length };
-  }
-}
-```
-
-## Best Practices
-
-1. **Always secure collections/topics/storage** - Default deny
-2. **Validate input in executables** - Check auth and params
-3. **Use transactions for multi-doc updates** - Atomic operations
-4. **Limit query results** - Default 1000, max 20000
-5. **Use snapshots for one-time data** - Use subscriptions for realtime
-6. **Batch operations when possible** - insertMany, deleteMany
-7. **Use memoryOptions for AI conversations** - Not deprecated chatId
-8. **Test in dev before prod deployment** - `squid deploy --environmentId dev`
-
-## Documentation
+## Links
 
 - Docs: https://docs.getsquid.ai/
 - Console: https://console.getsquid.ai/
 - Samples: https://github.com/squid-cloud-samples
-
----
-
-**This skill is verified against the actual Squid source code and contains only accurate, tested APIs.**