@squidcloud/cli 1.0.457 → 1.0.458

package/dist/index.js

@@ -29744,7 +29744,7 @@ exports.GROK_CHAT_MODEL_NAMES = ['grok-4', 'grok-4-1-fast-reasoning', 'grok-4-1-
  */
 exports.ANTHROPIC_CHAT_MODEL_NAMES = [
     'claude-haiku-4-5-20251001',
-    'claude-opus-4-6',
+    'claude-opus-4-7',
     'claude-sonnet-4-6',
 ];
 /**
@@ -30444,14 +30444,12 @@ exports.KOTLIN_CONTROLLERS = [
     'api',
     'application',
     'auth',
-    'integration',
     'internal-storage',
     'management-secret',
     'mutation',
     'native-query',
     'query',
     'queue',
-    'quota',
     'scheduler',
     'secret',
     'storage',
@@ -37341,7 +37339,7 @@ module.exports = /*#__PURE__*/JSON.parse('{"name":"seek-bzip","version":"1.0.6",
 (module) {
 
 "use strict";
-module.exports = /*#__PURE__*/JSON.parse('{"name":"@squidcloud/cli","version":"1.0.457","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.457","adm-zip":"^0.5.16","copy-webpack-plugin":"^12.0.2","decompress":"^4.2.1","logpipes":"^1.11.0","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.458","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.458","adm-zip":"^0.5.16","copy-webpack-plugin":"^12.0.2","decompress":"^4.2.1","logpipes":"^1.11.0","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-development/SKILL.md

@@ -18,6 +18,7 @@ Squid is a backend-as-a-service platform that provides:
 - **[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
+- **[chat-widget.md](reference/chat-widget.md)** → AI chat widget, @squidcloud/react-chat-widget, squid-chat-widget, squid-chat-widget-with-fab-button, embeddable chat, custom API webhook, AI query mode, chain-of-thought, status updates, session management, agentContext, memoryOptions, squid-ai-custom-api-url, squid-ai-agent-chat-options, FAB button, theming, CSS variables, localization, RTL, menu items slots, suggested prompts, voice transcription, error formatting, authentication, squid-auth-provider, onChange events
 - **[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(), projectFields, field projection, __docId__, __id
 - **[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

package/dist/resources/claude/skills/squid-development/reference/backend.md

@@ -15,8 +15,9 @@ Docs: https://docs.getsquid.ai/reference-docs/backend/
 - Schedulers (@scheduler)
 - Rate Limiting (@limits)
 - Client Connection State (@clientConnectionStateHandler)
+- Cross-Service Communication (squidInject)
 - Using Squid Client in Backend
-- File Handling
+- File Handling``
 
 ## CLI Commands
 
@@ -418,6 +419,77 @@ export class MyService extends SquidService {
 - `'DISCONNECTED'` - Client disconnected but ID still retained
 - `'REMOVED'` - Client disconnected and ID removed
 
+## Cross-Service Communication (squidInject)
+
+`squidInject` enables one `SquidService` to call methods on another `SquidService` within the same backend. It returns a **singleton instance** of the target service.
+
+```typescript
+import { SquidService, executable, squidInject } from '@squidcloud/backend';
+```
+
+### Basic Usage
+
+```typescript
+export class OrderService extends SquidService {
+  @executable()
+  async placeOrder(items: Item[]): Promise<Order> {
+    // Get a reference to another service
+    const notificationService = squidInject(NotificationService);
+    const order = await this.createOrder(items);
+    await notificationService.sendOrderConfirmation(order);
+    return order;
+  }
+}
+```
+
+### As a Class Property
+
+```typescript
+export class OrderService extends SquidService {
+  private readonly notifications = squidInject(NotificationService);
+
+  @executable()
+  async placeOrder(items: Item[]): Promise<Order> {
+    const order = await this.createOrder(items);
+    await this.notifications.sendOrderConfirmation(order);
+    return order;
+  }
+}
+```
+
+### Function Signature
+
+```typescript
+function squidInject<T extends SquidService>(
+  ctor: new () => T,
+  moduleId?: TenantModuleId, // defaults to USER_CODE_MODULE_ID
+): T
+```
+
+- `ctor` - The service class constructor to inject
+- `moduleId` - Optional module ID for cross-module injection (e.g., connector services)
+
+### Circular Dependency Detection
+
+`squidInject` detects circular dependencies and throws a `CIRCULAR_DEPENDENCY` error:
+
+```typescript
+// BAD: Throws CIRCULAR_DEPENDENCY: ServiceA => ServiceB
+export class ServiceA extends SquidService {
+  readonly b = squidInject(ServiceB);
+}
+export class ServiceB extends SquidService {
+  readonly a = squidInject(ServiceA);
+}
+```
+
+### Notes
+
+- Returns a **singleton** — the same instance is returned on every call for a given service class
+- Can be called inside `@executable` methods, as class property initializers, or in constructors
+- **Do not call from static context** during module loading — the Squid module must be initialized first
+- Replaces the deprecated `getSquidService()` function
+
 ## Using Squid Client in Backend
 
 The pre-initialized `this.squid` client has full permissions:

package/dist/resources/claude/skills/squid-development/reference/chat-widget.md

@@ -0,0 +1,1030 @@
+# AI Chat Widget
+
+The Squid AI Chat Widget (`@squidcloud/react-chat-widget`) is an embeddable chat interface that connects to Squid AI agents, AI Query, or custom webhook APIs. It is distributed as both a React component and Web Components (custom elements).
+
+**Package:** `@squidcloud/react-chat-widget` (npm)
+**CDN:** `https://widget.squid.cloud/widget.umd.js`
+**Docs:** https://docs.getsquid.ai/docs/sdk/backend-sdk/ai/ai-chat-widget/
+
+## Contents
+- Embedding the Widget
+- Three Operation Modes
+- Required & Optional Attributes
+- Agent Chat Options & Context
+- Custom API / Webhook Mode
+- AI Query Mode
+- Session Management
+- Authentication & Access Control
+- Publishing Status Updates (Chain of Thought)
+- Events & Callbacks
+- Styling & Theming
+- Localization
+- Menu Items (Slots)
+- Suggested Prompts
+- Voice Transcription
+- Error Formatting
+- FAB (Floating Action Button) Mode
+- Framework Integration (React, Angular)
+
+## Embedding the Widget
+
+### Via CDN (any HTML page)
+
+```html
+<script async src="https://widget.squid.cloud/widget.umd.js"></script>
+
+<!-- Inline chat widget -->
+<squid-chat-widget
+  squid-app-id="YOUR_APP_ID"
+  squid-region="us-east-1.aws"
+  squid-environment-id="prod"
+  squid-developer-id="YOUR_DEV_ID"
+  squid-ai-agent-id="YOUR_AGENT_ID"
+  header-title="Chat Support"
+  style="display: block; height: 500px;"
+></squid-chat-widget>
+
+<!-- Floating action button variant (bottom-right corner) -->
+<squid-chat-widget-with-fab-button
+  squid-app-id="YOUR_APP_ID"
+  squid-region="us-east-1.aws"
+  squid-environment-id="prod"
+  squid-developer-id="YOUR_DEV_ID"
+  squid-ai-agent-id="YOUR_AGENT_ID"
+  header-title="Chat Support"
+></squid-chat-widget-with-fab-button>
+```
+
+### Via npm (React)
+
+```bash
+npm install @squidcloud/react-chat-widget @squidcloud/react @squidcloud/client rxjs
+```
+
+```tsx
+import { SquidChatWidgetEntryPoint, SquidChatWidgetWithFabButtonEntryPoint } from '@squidcloud/react-chat-widget';
+
+// Inline
+<SquidChatWidgetEntryPoint
+  squidAppId="YOUR_APP_ID"
+  squidRegion="us-east-1.aws"
+  squidAiAgentId="YOUR_AGENT_ID"
+  headerTitle="Chat Support"
+/>
+
+// FAB
+<SquidChatWidgetWithFabButtonEntryPoint
+  squidAppId="YOUR_APP_ID"
+  squidRegion="us-east-1.aws"
+  squidAiAgentId="YOUR_AGENT_ID"
+  headerTitle="Chat Support"
+/>
+```
+
+Both entry points wrap the widget in a `SquidContextProvider` automatically -- you do NOT need to provide one yourself.
+
+## Three Operation Modes
+
+The widget supports three mutually exclusive modes:
+
+### 1. Agent Mode (default)
+Connects to a Squid AI agent. Set `squid-ai-agent-id` to the agent ID.
+
+### 2. AI Query Mode
+Natural language queries against a database integration. Set `squid-ai-query="true"` and `squid-ai-integration-id` to the database integration ID.
+
+### 3. Custom API / Webhook Mode
+Send prompts to your own backend endpoint. Set `squid-ai-custom-api-url` to your webhook URL. When this is set, `squid-app-id` and `squid-region` are still required for the Squid context, but the agent ID is not needed.
+
+**Priority order in code:**
+1. If `squidAiQuery` is true → uses `useAiQuery` hook
+2. Else if `squidAiCustomApiUrl` is set → uses `useAskWithApi` hook
+3. Else → uses `useAiAgent` hook with `squidAiAgentId`
+
+## Required & Optional Attributes
+
+### Required (for Agent / AI Query modes)
+
+| HTML Attribute | React Prop | Type | Description |
+|---|---|---|---|
+| `squid-app-id` | `squidAppId` | string | Squid application ID |
+| `squid-region` | `squidRegion` | SquidRegion | Region (e.g., `us-east-1.aws`) |
+| `squid-ai-agent-id` | `squidAiAgentId` | string | AI Agent ID (agent mode) |
+| `header-title` | `headerTitle` | string | Widget header text (default: `'SquidAI Chat'`) |
+
+### Squid Cloud Configuration
+
+| HTML Attribute | React Prop | Type | Default | Description |
+|---|---|---|---|---|
+| `squid-environment-id` | `squidEnvironmentId` | EnvironmentId | `'prod'` | Environment: `'prod'`, `'dev'` |
+| `squid-developer-id` | `squidDeveloperId` | SquidDeveloperId | - | Developer ID for multi-tenant apps |
+| `squid-api-key` | `squidApiKey` | string | - | API key for authentication |
+| `squid-ai-integration-id` | `squidAiIntegrationId` | string | `'ai_agents'` | Integration ID for AI services |
+
+### AI Model & Behavior
+
+| HTML Attribute | React Prop | Type | Default | Description |
+|---|---|---|---|---|
+| `squid-ai-override-model` | `squidAiOverrideModel` | AiChatModelName | - | Override the default LLM model |
+| `squid-ai-temperature` | `squidAiTemperature` | number | - | Model temperature (0-1) |
+| `squid-ai-max-tokens` | `squidAiMaxTokens` | number | - | Max tokens in response |
+| `squid-ai-instructions` | `squidAiInstructions` | string | - | Additional instructions (appended to agent instructions) |
+| `squid-ai-context-metadata-filter` | `squidAiContextMetadataFilter` | AiContextMetadataFilter | - | Filter knowledge base context by metadata |
+| `squid-ai-enable-raw-results` | `squidAiEnableRawResults` | boolean | - | Return raw results from AI |
+| `squid-ai-enable-code-interpreter` | `squidAiEnableCodeInterpreter` | boolean | - | Enable code execution in AI response |
+
+### Functions & Connected Agents
+
+| HTML Attribute | React Prop | Type | Description |
+|---|---|---|---|
+| `squid-ai-functions` | `squidAiFunctions` | string | Comma-separated `@aiFunction` names the agent may call |
+| `squid-ai-functions-json` | `squidAiFunctionsJson` | Array\<FunctionName\> | JSON array of function names (alternative to CSV) |
+| `squid-ai-connected-agents` | `squidAiConnectedAgents` | Array\<AiConnectedAgentMetadata\> | Connected agents for multi-agent delegation |
+
+### UI & Display
+
+| HTML Attribute | React Prop | Type | Default | Description |
+|---|---|---|---|---|
+| `intro-text` | `introText` | string | - | Welcome message shown before first interaction |
+| `avatar-image-url` | `avatarImageUrl` | string | - | Chat avatar image URL |
+| `chat-icon-url` | `chatIconUrl` | string | - | FAB button icon URL |
+| `widget-width` | `widgetWidth` | string | - | Widget width (CSS units) |
+| `widget-height` | `widgetHeight` | string | - | Widget height (CSS units) |
+| `theme` | `theme` | `'light'` \| `'dark'` | `'light'` | Color theme |
+| `rtl-mode` | `rtlMode` | boolean | - | Right-to-left layout for Hebrew, Arabic |
+| `powered-by-text` | `poweredByText` | string | - | Custom "powered by" text (replaces Squid branding) |
+| `base-stylesheet-url` | `baseStylesheetUrl` | string | `'https://widget.squid.cloud/style.css'` | Base CSS URL |
+| `stylesheet-url` | `stylesheetUrl` | string | - | Additional CSS URL for custom styling |
+
+### Feature Toggles
+
+| HTML Attribute | React Prop | Type | Default | Description |
+|---|---|---|---|---|
+| `enable-transcription` | `enableTranscription` | boolean | false | Enable voice-to-text (agent mode only) |
+| `include-reference` | `includeReference` | boolean | false | Include source references in responses |
+| `disable-history` | `disableHistory` | boolean | false | Disable chat history persistence (sets memoryMode to `'none'`) |
+| `observe-status` | `observeStatus` | boolean | false | Emit status updates during processing |
+| `chain-of-thought` | `chainOfThought` | boolean | false | Show AI reasoning process (requires `observe-status`) |
+| `show-status-tags` | `showStatusTags` | boolean | false | Display JSON tags in chain-of-thought entries |
+| `enable-debug-logs` | `enableDebugLogs` | boolean | false | Enable debug logging to console |
+
+## Agent Chat Options & Context
+
+The `squid-ai-agent-chat-options` attribute accepts a JSON object of type `AllAiAgentChatOptions` for advanced agent configuration:
+
+```html
+<squid-chat-widget
+  squid-ai-agent-chat-options='{
+    "agentContext": { "userId": "user-123", "projectId": "proj-456" },
+    "instructions": "Always respond in formal English.",
+    "memoryOptions": {
+      "memoryMode": "read-write",
+      "memoryId": "custom-session-id",
+      "expirationMinutes": 1440
+    },
+    "contextMetadataFilterForKnowledgeBase": {
+      "kb-id": { "category": "documentation" }
+    }
+  }'
+  ...
+></squid-chat-widget>
+```
+
+### agentContext
+
+The `agentContext` object is passed to your backend and is accessible in `@aiFunction` methods via the `AiFunctionCallContext`:
+
+```typescript
+// Widget configuration
+squid-ai-agent-chat-options='{ "agentContext": { "userId": "u123", "role": "admin" } }'
+
+// Backend @aiFunction
+@aiFunction('Gets user data', [
+  { name: 'query', type: 'string', required: true, description: 'Query' }
+])
+async getUserData(
+  params: { query: string },
+  context: AiFunctionCallContext
+): Promise<string> {
+  const userId = context.agentContext?.userId;  // "u123"
+  const role = context.agentContext?.role;       // "admin"
+  // Use context to scope data access
+  return await fetchDataForUser(userId, query);
+}
+```
+
+### instructions
+
+The `instructions` field **appends** to the agent's console-defined instructions. It does not replace them.
+
+### memoryOptions
+
+Controls chat history persistence:
+- `memoryMode: 'read-write'` (default) - saves and reads history
+- `memoryMode: 'read-only'` - reads history but doesn't save new messages
+- `memoryMode: 'none'` - no history
+- `memoryId` - unique ID per user/session for history isolation
+- `expirationMinutes` - auto-expire history
+
+## Custom API / Webhook Mode
+
+Use `squid-ai-custom-api-url` to intercept user prompts and handle them with your own backend logic.
+
+### Widget Configuration
+
+```html
+<squid-chat-widget
+  squid-app-id="YOUR_APP_ID"
+  squid-region="us-east-1.aws"
+  squid-ai-custom-api-url="https://YOUR_APP_URL/webhooks/chat"
+  squid-ai-custom-api-headers='{ "x-api-key": "secret123" }'
+  header-title="Custom Chat"
+></squid-chat-widget>
+```
+
+When using a Squid backend webhook, you can get the webhook URL from the Squid client SDK:
+
+```typescript
+const webhookUrl = squid.getWebhookUrl('chat');
+// Use this URL as squid-ai-custom-api-url
+```
+
+### Backend Webhook Handler
+
+```typescript
+import { SquidService, webhook, WebhookRequest } from '@squidcloud/backend';
+
+interface ChatRequest {
+  prompt: string;
+}
+
+interface ChatResponse {
+  response: string;
+}
+
+export class ChatService extends SquidService {
+  @webhook('chat')
+  async handleChat(request: WebhookRequest<ChatRequest>): Promise<ChatResponse> {
+    const { prompt } = request.body;
+    const sessionId = request.headers['squid-session-id']; // Auto-injected by widget
+    const customHeaders = request.headers; // Includes squid-ai-custom-api-headers
+
+    // Option 1: Process with your own logic
+    const result = await processPrompt(prompt);
+    return { response: result };
+
+    // Option 2: Forward to an agent with custom preprocessing
+    const agent = this.squid.ai().agent('my-agent');
+    const response = await agent.ask(prompt, {
+      agentContext: { sessionId },
+      functions: ['myFunction']
+    });
+    return { response };
+  }
+}
+```
+
+### Session Tracking
+
+The widget automatically generates a unique `sessionId` per widget instance and sends it as the `squid-session-id` header with every request. This allows your webhook to maintain per-session state.
+
+Any custom headers set via `squid-ai-custom-api-headers` are also included in every request.
+
+### Query Parameters
+
+The webhook also receives query parameters from the request URL. Access them via `request.queryParams`.
+
+## AI Query Mode
+
+Use AI Query mode to let users query a database using natural language.
+
+```html
+<squid-chat-widget
+  squid-app-id="YOUR_APP_ID"
+  squid-region="us-east-1.aws"
+  squid-environment-id="prod"
+  squid-ai-query="true"
+  squid-ai-integration-id="built_in_db"
+  header-title="Data Explorer"
+></squid-chat-widget>
+```
+
+### AI Query Options
+
+For advanced control, use `squid-ai-query-options` (JSON string):
+
+```html
+<squid-chat-widget
+  squid-ai-query="true"
+  squid-ai-integration-id="built_in_db"
+  squid-ai-query-options='{
+    "enableRawResults": true,
+    "analyzeResultsOptions": { "enableCodeInterpreter": true },
+    "memoryOptions": { "memoryMode": "read-write" },
+    "selectCollectionsOptions": { "collectionsToUse": ["users", "orders"] },
+    "generateQueryOptions": { "maxErrorCorrections": 3 }
+  }'
+  ...
+></squid-chat-widget>
+```
+
+If `squid-ai-query-options` is provided, it takes precedence over individual props like `squid-ai-enable-raw-results` and `squid-ai-enable-code-interpreter`.
+
+**Note:** In AI Query mode, voice transcription is not available.
+
+## Session Management
+
+### Automatic Memory
+
+By default, the widget generates a unique `memoryId` (UUID) on mount. All messages in that session share this ID for conversation context.
+
+- To **disable history**: set `disable-history="true"` (sets `memoryMode: 'none'`)
+- To **use a custom session ID**: pass it via `squid-ai-agent-chat-options` → `memoryOptions.memoryId`
+- To **expire history**: set `memoryOptions.expirationMinutes`
+
+### Session ID for Custom APIs
+
+The widget generates a short `sessionId` on mount and sends it as `squid-session-id` header with every custom API request. This is separate from the memory ID used for agent conversation history.
+
+## Authentication & Access Control
+
+### Public Agents
+
+Toggle in Agent Studio > Agent Settings. Public agents bypass `@secureAiAgent` rules but auth credentials are still available in backend functions.
+
+### Private Agents (Auth Required)
+
+Pass an auth provider via `squid-auth-provider`:
+
+```html
+<squid-chat-widget
+  squid-auth-provider='{ "integrationId": "AUTH_INTEGRATION_ID", "token": "AUTH_TOKEN" }'
+  ...
+></squid-chat-widget>
+```
+
+```tsx
+// React
+<SquidChatWidgetEntryPoint
+  squidAuthProvider={{ integrationId: "auth0", token: authToken }}
+  ...
+/>
+```
+
+The widget calls `squid.setAuthProvider()` internally with the provided `integrationId` and token.
+
+### Backend Security
+
+```typescript
+@secureAiAgent('my-agent-id')
+allowAccessToAgent(): boolean {
+  return this.isAuthenticated();
+}
+```
+
+Auth credentials are also accessible inside `@aiFunction` methods via `this.getUserAuth()`.
+
+## Publishing Status Updates (Chain of Thought)
+
+To show the AI's reasoning process in the widget, enable chain-of-thought display:
+
+```html
+<squid-chat-widget
+  observe-status="true"
+  chain-of-thought="true"
+  show-status-tags="true"
+  ...
+></squid-chat-widget>
+```
+
+### How It Works
+
+1. Enable `observe-status` to subscribe to status updates from the agent
+2. Enable `chain-of-thought` to render those updates in the UI
+3. Optionally enable `show-status-tags` to display JSON metadata tags
+
+### Status Update Structure
+
+Each status update contains:
+- `messageId` - unique ID
+- `title` - display text (shown in the chain-of-thought UI)
+- `tags` - metadata object (shown as JSON when `show-status-tags` is enabled)
+- `body` - markdown content (rendered below the title)
+- `parentStatusUpdateId` - for nested status updates (creates tree structure)
+- `duration` - processing time in milliseconds
+
+### Publishing Status Updates from Backend
+
+Use the agent's status update mechanism to publish updates that appear in the widget:
+
+```typescript
+// In your @aiFunction or backend code
+// Status updates are published through the agent's observeStatusUpdates() stream
+// The widget subscribes to this stream when observe-status="true"
+```
+
+### Nested Status Updates
+
+Status updates support parent-child relationships via `parentStatusUpdateId`. The widget renders these as an expandable tree structure, with each parent showing its duration and collapsible children.
+
+### Timing Display
+
+When chain-of-thought is enabled and processing completes, the widget shows a "Thought for X seconds" summary. Each parent status update also shows its individual duration.
+
+## Events & Callbacks
+
+### onChange Event
+
+Listen for chat history and status changes:
+
+```html
+<!-- HTML: via DOM event -->
+<squid-chat-widget id="chat" ...></squid-chat-widget>
+<script>
+  document.getElementById('chat').addEventListener('change', (event) => {
+    const { type } = event.detail;
+    if (type === 'history') {
+      console.log('Messages:', event.detail.history);
+    }
+    if (type === 'status') {
+      console.log('Status updates:', event.detail.status);
+    }
+  });
+</script>
+```
+
+```tsx
+// React
+<SquidChatWidgetEntryPoint
+  onChange={(event: ChatChangeEvent) => {
+    if (event.detail.type === 'history') {
+      const messages: ChatMessage[] = event.detail.history;
+      // Each message: { id, type: 'user'|'ai', message: string, jobId }
+    }
+    if (event.detail.type === 'status') {
+      const updates: AiStatusMessage[] = event.detail.status;
+    }
+  }}
+  ...
+/>
+```
+
+**History events** fire when a user sends a message and when the AI response completes.
+**Status events** fire during processing when `observe-status` is enabled.
+
+### Event Types
+
+```typescript
+interface HistoryChangeEvent extends CustomEvent {
+  detail: { type: 'history'; history: ChatMessage[] };
+}
+
+interface StatusChangeEvent extends CustomEvent {
+  detail: { type: 'status'; status: AiStatusMessage[] };
+}
+
+type ChatChangeEvent = HistoryChangeEvent | StatusChangeEvent;
+```
+
+## Styling & Theming
+
+### Themes
+
+Two built-in themes: `theme="light"` (default) and `theme="dark"`.
+
+### CSS Variables
+
+Override any aspect of the widget via CSS custom properties on the element:
+
+```css
+squid-chat-widget {
+  /* Header */
+  --squid-widget-header-background-color: #1a1a2e;
+  --squid-widget-header-title-color: #ffffff;
+  --squid-widget-header-menu-button-background-color: rgba(255,255,255,0.1);
+  --squid-widget-header-menu-button-icon-url: url('/custom-menu.svg');
+  --squid-widget-header-menu-item-color: #333;
+  --squid-widget-header-menu-item-hover-background-color: #f0f0f0;
+
+  /* Body */
+  --squid-widget-body-background-color: #f8f9fc;
+  --squid-widget-ai-message-background-color: #ffffff;
+  --squid-widget-user-message-background-color: #188fff;
+  --squid-widget-user-message-color: #ffffff;
+  --squid-widget-avatar-image-url: url('/avatar.png');
+
+  /* Input area */
+  --squid-widget-textarea-background-color: #ffffff;
+  --squid-widget-textarea-border-color: #e0e0e0;
+  --squid-widget-textarea-text-color: #333;
+  --squid-widget-textarea-submit-image-url: url('/send.svg');
+
+  /* Code & links */
+  --squid-widget-inline-code-background-color: #f5f5f5;
+  --squid-widget-inline-code-border-color: #e0e0e0;
+  --squid-widget-link-color: #188fff;
+
+  /* Footer */
+  --squid-widget-powered-by-color: #888;
+
+  /* FAB button */
+  --squid-widget-fab-background-color: #188fff;
+  --squid-widget-fab-image-url: url('/chat-icon.svg');
+  --squid-widget-fab-close-image-url: url('/close.svg');
+
+  /* Dimensions */
+  --widget-width: 400px;
+}
+```
+
+### Custom Stylesheet
+
+For deeper customization, provide an additional CSS file:
+
+```html
+<squid-chat-widget
+  stylesheet-url="https://example.com/custom-widget.css"
+  ...
+></squid-chat-widget>
+```
+
+The base stylesheet loads first, then the custom stylesheet overlays it.
+
+## Localization
+
+Customize all UI text for internationalization:
+
+| HTML Attribute | React Prop | Default | Description |
+|---|---|---|---|
+| `text-placeholder` | `textPlaceholder` | `'Type here and press enter...'` | Input placeholder |
+| `text-thinking` | `textThinking` | `'Thinking...'` | Loading state text |
+| `text-thought-for` | `textThoughtFor` | `'Thought for'` | Chain-of-thought label |
+| `text-suggested-prompts` | `textSuggestedPrompts` | `'Suggested Prompts'` | Suggested prompts title |
+| `text-suggested-prompts-description` | `textSuggestedPromptsDescription` | `'Explore what this agent can do with a few examples.'` | Suggested prompts description |
+| `text-milliseconds` | `textMilliseconds` | `'milliseconds'` | Time unit |
+| `text-seconds` | `textSeconds` | `'seconds'` | Time unit |
+| `text-minutes` | `textMinutes` | `'minutes'` | Time unit |
+
+### RTL Support
+
+```html
+<squid-chat-widget rtl-mode="true" ...></squid-chat-widget>
+```
+
+## Menu Items (Slots)
+
+Add custom content pages to the widget via dropdown menu items:
+
+```html
+<squid-chat-widget
+  menu-items-json='[
+    { "title": "Documentation", "slotName": "docs" },
+    { "title": "FAQ", "slotName": "faq" }
+  ]'
+  ...
+>
+  <div slot="docs">
+    <h2>Documentation</h2>
+    <p>Your docs content here.</p>
+  </div>
+  <div slot="faq">
+    <h2>FAQ</h2>
+    <p>Frequently asked questions...</p>
+  </div>
+</squid-chat-widget>
+```
+
+```tsx
+// React
+<SquidChatWidgetEntryPoint
+  menuItemsJson={[
+    { title: "Documentation", slotName: "docs" },
+    { title: "FAQ", slotName: "faq" }
+  ]}
+  ...
+>
+  <div slot="docs"><h2>Documentation</h2></div>
+  <div slot="faq"><h2>FAQ</h2></div>
+</SquidChatWidgetEntryPoint>
+```
+
+### Programmatic Navigation
+
+To navigate back to chat from slot content:
+
+```javascript
+const widget = document.querySelector('squid-chat-widget');
+widget.backToChat(); // Returns to the main chat view
+```
+
+## Suggested Prompts
+
+Show predefined questions to guide users:
+
+```html
+<squid-chat-widget
+  predefined-prompts='["How do I reset my password?", "What are your business hours?", "Show me pricing"]'
+  ...
+></squid-chat-widget>
+```
+
+Prompts appear in two places:
+1. Below the intro message (on initial load, before any user messages)
+2. In a dropdown menu accessible from the header (always available)
+
+Clicking a prompt auto-submits it as a user message.
+
+## Voice Transcription
+
+Enable microphone input for voice-to-text:
+
+```html
+<squid-chat-widget
+  enable-transcription="true"
+  ...
+></squid-chat-widget>
+```
+
+- Only available in **agent mode** (not AI Query mode)
+- Uses browser's `MediaRecorder` API to capture audio as WAV
+- Audio is sent to Squid's transcription service, then the transcribed text is submitted as a chat message
+- The microphone button appears when the text input is empty; it's replaced by the submit button when text is typed
+
+## Error Formatting
+
+Control how errors are displayed to users:
+
+```html
+<!-- Show generic message for all errors -->
+<squid-chat-widget error-formatter="generic-error" ...></squid-chat-widget>
+
+<!-- Show detailed error (default) -->
+<squid-chat-widget error-formatter="original-error" ...></squid-chat-widget>
+```
+
+```tsx
+// React: custom error formatter function
+<SquidChatWidgetEntryPoint
+  errorFormatter={(error: unknown) => `Something went wrong: ${getMessageFromError(error)}`}
+  ...
+/>
+```
+
+Built-in options:
+- `'generic-error'` - "Oops, something went wrong with your request. Please try again."
+- `'original-error'` (default) - Shows error details from the server
+
+## FAB (Floating Action Button) Mode
+
+The `<squid-chat-widget-with-fab-button>` variant renders as a floating button in the bottom-right corner that toggles the chat panel.
+
+```html
+<squid-chat-widget-with-fab-button
+  open-on-load="true"
+  use-maximize-button="true"
+  ...
+></squid-chat-widget-with-fab-button>
+```
+
+| Attribute | React Prop | Type | Description |
+|---|---|---|---|
+| `open-on-load` | `openOnLoad` | boolean | Widget opens automatically on page load |
+| `use-maximize-button` | `useMaximizeButton` | boolean | Show maximize/minimize button |
+
+### Maximize/Minimize (React controlled)
+
+```tsx
+const [isMaximized, setIsMaximized] = useState(false);
+
+<SquidChatWidgetWithFabButtonEntryPoint
+  useMaximizeButton={true}
+  isMaximized={isMaximized}
+  onMaximizedChange={setIsMaximized}
+  ...
+/>
+```
+
+## Framework Integration
+
+### React
+
+Works out of the box with the React entry point components. No extra setup needed.
+
+### Angular
+
+Add `CUSTOM_ELEMENTS_SCHEMA` to your NgModule to use the web component:
+
+```typescript
+import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
+
+@NgModule({
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  // ...
+})
+export class AppModule {}
+```
+
+Then use the HTML custom element in templates:
+
+```html
+<squid-chat-widget
+  squid-app-id="YOUR_APP_ID"
+  squid-region="us-east-1.aws"
+  squid-ai-agent-id="YOUR_AGENT_ID"
+  header-title="Chat"
+></squid-chat-widget>
+```
+
+### TypeScript Declaration (React)
+
+If TypeScript complains about the custom elements, add a declaration file:
+
+```typescript
+// declarations.d.ts
+declare namespace JSX {
+  interface IntrinsicElements {
+    'squid-chat-widget': any;
+    'squid-chat-widget-with-fab-button': any;
+  }
+}
+```
+
+## Complete Example
+
+### Full-featured agent chat with all options
+
+```html
+<squid-chat-widget-with-fab-button
+  squid-app-id="my-app"
+  squid-region="us-east-1.aws"
+  squid-environment-id="prod"
+  squid-developer-id="dev-123"
+  squid-ai-agent-id="support-agent"
+  squid-ai-instructions="Be concise and professional."
+  squid-ai-functions="getOrderStatus,lookupAccount"
+  squid-ai-connected-agents='[{"agentId":"billing-agent","description":"Handles billing questions"}]'
+  squid-ai-override-model="gpt-5-mini"
+  squid-ai-temperature="0.7"
+  squid-ai-max-tokens="2000"
+  squid-ai-agent-chat-options='{
+    "agentContext": { "userId": "user-123" },
+    "memoryOptions": { "memoryMode": "read-write", "expirationMinutes": 60 }
+  }'
+  header-title="Customer Support"
+  intro-text="Hi! How can I help you today?"
+  predefined-prompts='["Track my order", "Billing question", "Technical support"]'
+  theme="dark"
+  rtl-mode="false"
+  observe-status="true"
+  chain-of-thought="true"
+  show-status-tags="false"
+  include-reference="true"
+  enable-transcription="true"
+  open-on-load="false"
+  use-maximize-button="true"
+  error-formatter="original-error"
+  text-placeholder="Ask me anything..."
+  text-thinking="Processing..."
+  powered-by-text="Powered by Acme Corp"
+  squid-auth-provider='{"integrationId":"auth0","token":"eyJ..."}'
+  menu-items-json='[{"title":"Help Center","slotName":"help"}]'
+>
+  <div slot="help"><h2>Help Center</h2><p>Contact us at support@example.com</p></div>
+</squid-chat-widget-with-fab-button>
+```
+
+## Real-World Patterns
+
+### Pattern 1: AI Query with Predefined SQL Prompts
+
+Use the widget as a natural language database explorer with predefined queries:
+
+```tsx
+// Frontend component
+function DataExplorer() {
+  const squid = useSquid();
+  const memoryId = useMemo(() => generateUUID(), []);
+
+  const aiQueryOptions: AiQueryOptions = {
+    memoryOptions: { memoryMode: 'read-write', memoryId },
+  };
+
+  return (
+    <squid-chat-widget
+      squid-app-id={import.meta.env.VITE_SQUID_APP_ID}
+      squid-region={import.meta.env.VITE_SQUID_REGION}
+      squid-environment-id={import.meta.env.VITE_SQUID_ENVIRONMENT_ID}
+      squid-api-key={import.meta.env.VITE_SQUID_API_KEY}
+      squid-developer-id={import.meta.env.VITE_SQUID_DEVELOPER_ID}
+      squid-ai-query="true"
+      squid-ai-integration-id="my_database"
+      squid-ai-query-options={JSON.stringify(aiQueryOptions)}
+      header-title="Data Explorer"
+      intro-text="Ask questions about your data."
+      widget-width="820px"
+      chain-of-thought="true"
+      predefined-prompts={JSON.stringify([
+        'Show sample of 10 recent orders',
+        'What is the total revenue by month?',
+        'List top customers by order count'
+      ])}
+    />
+  );
+}
+```
+
+### Pattern 2: Custom Webhook with Dynamic Instructions
+
+Two-phase pattern where Phase 1 uses built-in AI Query and Phase 2 uses a custom webhook with file-based instructions:
+
+```tsx
+// Frontend - Phase 2: Custom webhook with uploaded instructions
+function AdvancedQuery() {
+  const squid = useSquid();
+  const [webhookUrl, setWebhookUrl] = useState('');
+
+  useEffect(() => {
+    setWebhookUrl(squid.getWebhookUrl('my-custom-query'));
+  }, [squid]);
+
+  if (!webhookUrl) return null;
+
+  return (
+    <squid-chat-widget
+      squid-app-id={import.meta.env.VITE_SQUID_APP_ID}
+      squid-region={import.meta.env.VITE_SQUID_REGION}
+      squid-environment-id={import.meta.env.VITE_SQUID_ENVIRONMENT_ID}
+      squid-ai-custom-api-url={webhookUrl}
+      header-title="Advanced Query"
+      intro-text="Ask anything - I have access to custom instructions."
+      widget-width="820px"
+      chain-of-thought="true"
+    />
+  );
+}
+```
+
+```typescript
+// Backend - Webhook handler with dynamic instructions from storage
+import { SquidService, webhook, WebhookRequest } from '@squidcloud/backend';
+
+interface QueryWebhookBody {
+  prompt: string;
+}
+
+export class QueryService extends SquidService {
+  @webhook('my-custom-query')
+  async handleQuery(request: WebhookRequest<QueryWebhookBody>) {
+    const { prompt } = request.body;
+    const sessionId = request.headers['squid-session-id'];
+
+    // Load dynamic instructions from storage
+    const storage = this.squid.storage('default');
+    const files = await storage.listDirectoryContents('/instructions');
+    let instructions = '';
+    for (const file of files) {
+      const url = await storage.downloadUrl(file.path);
+      const content = await fetch(url).then(r => r.text());
+      instructions += content + '\n';
+    }
+
+    // Execute AI query with dynamic instructions and session memory
+    const result = await this.squid.ai().executeAiQuery(
+      'my_database',
+      prompt,
+      {
+        instructions,
+        memoryOptions: { memoryMode: 'read-write', memoryId: sessionId },
+      }
+    );
+
+    return { response: result };
+  }
+}
+```
+
+### Pattern 3: Authenticated Agent with AI Functions
+
+Widget connected to a secured agent that calls backend functions with user context:
+
+```tsx
+// Frontend - Auth0-authenticated chat widget
+function AuthenticatedChat() {
+  const { getAccessTokenSilently } = useAuth0();
+  const [authToken, setAuthToken] = useState<string>();
+
+  useEffect(() => {
+    getAccessTokenSilently().then(setAuthToken);
+  }, []);
+
+  if (!authToken) return null;
+
+  return (
+    <squid-chat-widget
+      squid-app-id={import.meta.env.VITE_SQUID_APP_ID}
+      squid-region={import.meta.env.VITE_SQUID_REGION}
+      squid-environment-id={import.meta.env.VITE_SQUID_ENVIRONMENT_ID}
+      squid-api-key={import.meta.env.VITE_SQUID_API_KEY}
+      squid-developer-id={import.meta.env.VITE_SQUID_DEVELOPER_ID}
+      squid-ai-agent-id="support-agent"
+      squid-auth-provider={JSON.stringify({
+        integrationId: 'auth0',
+        token: authToken,
+      })}
+      header-title="Support"
+      intro-text="How may I help you?"
+      widget-width="820px"
+      chain-of-thought="true"
+    />
+  );
+}
+```
+
+```typescript
+// Backend - Secured agent with AI functions
+export class SupportService extends SquidService {
+  private readonly agent = this.squid.ai().agent('support-agent');
+
+  @secureAiAgent('support-agent')
+  allowAccess(): boolean {
+    return this.isAuthenticated();
+  }
+
+  @aiFunction('Searches for customer or account by name', [
+    { name: 'type', type: 'string', required: true, description: 'Entity type', enum: ['customer', 'account'] },
+    { name: 'name', type: 'string', required: true, description: 'Search query' },
+  ])
+  async searchEntity({ type, name }: { type: string; name: string }): Promise<string> {
+    const results = await this.squid.collection('entities')
+      .query()
+      .eq('type', type)
+      .like('name', `%${name}%`)
+      .snapshot();
+    return JSON.stringify(results);
+  }
+
+  @aiFunction('Gets detailed customer data from database', [
+    { name: 'customerName', type: 'string', required: true, description: 'Exact customer name' },
+  ])
+  async getCustomerDetails({ customerName }: { customerName: string }): Promise<string> {
+    const customer = await this.squid.collection('customers')
+      .query()
+      .eq('name', customerName)
+      .snapshot();
+    return JSON.stringify(customer);
+  }
+}
+```
+
+### Pattern 4: Custom CSS to Hide Widget Chrome
+
+Strip the widget header and borders to embed seamlessly in your UI:
+
+```css
+/* chat-widget.css - loaded via stylesheet-url or linked in HTML */
+.squid_chat_widget_header {
+  display: none !important;
+}
+.squid_chat_widget {
+  box-shadow: none !important;
+}
+```
+
+```html
+<squid-chat-widget
+  stylesheet-url="/chat-widget.css"
+  ...
+></squid-chat-widget>
+```
+
+### Pattern 5: Exposing Squid Instance Globally for Widget URL Resolution
+
+When using the widget as a custom element (not React), you may need the Squid client to resolve webhook URLs dynamically:
+
+```tsx
+// In your React app, expose the Squid instance globally
+function Layout() {
+  const squid = useSquid();
+
+  useEffect(() => {
+    (window as any).squid = squid;
+  }, [squid]);
+
+  return <>{/* your app */}</>;
+}
+
+// Then in plain JS:
+const webhookUrl = window.squid.getWebhookUrl('my-webhook');
+document.querySelector('squid-chat-widget')
+  .setAttribute('squid-ai-custom-api-url', webhookUrl);
+```
+
+## Important Notes
+
+- The widget uses **Shadow DOM** (open mode) for style isolation
+- **Markdown rendering**: AI responses are rendered as markdown (with GFM support) including syntax-highlighted code blocks
+- **Keyboard**: Enter to submit, Shift+Enter for newline
+- **Auto-scroll**: Widget auto-scrolls to bottom on new messages; pauses when user scrolls up
+- `squid-ai-profile-id` is **deprecated** -- use `squid-ai-agent-id` instead
+- When `squid-ai-custom-api-url` is set, `squid-app-id` and `squid-region` are still needed for the SquidContextProvider but the agent ID is not required
+- The widget auto-generates a unique `memoryId` per mount -- to share history across widget instances, provide a custom `memoryId` via `squid-ai-agent-chat-options`

package/package.json

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