@squidcloud/cli 1.0.487 → 1.0.489

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

@@ -18,6 +18,7 @@ Docs: https://docs.getsquid.ai/reference-docs/backend/
 - Schedulers (@scheduler)
 - Rate Limiting (@limits)
 - Queue Message Handlers (@onQueueMessage)
+- Events (@eventHandler)
 - Client Connection State (@clientConnectionStateHandler)
 - Cross-Service Communication (squidInject)
 - Using Squid Client in Backend
@@ -37,8 +38,10 @@ squid init backend --appId YOUR_APP_ID --apiKey YOUR_API_KEY --environmentId dev
 
 **`squid start`** - Runs backend locally with hot-reload. Connects to Squid Cloud via reverse proxy.
 ```bash
-cd backend && squid start
+cd backend && squid start [--printBundle]
 ```
+`--printBundle` makes the local dev server log the full application bundle data on startup instead of
+just the webhooks — useful when checking what the build actually registered.
 
 **`squid deploy`** - Builds and deploys to Squid Cloud.
 ```bash
@@ -50,6 +53,20 @@ squid deploy [--apiKey KEY] [--environmentId prod] [--skipBuild]
 squid build [--dev] [--skip-version-check]
 ```
 
+**`squid kb-upload`** - Bulk-ingests a local directory into a knowledge base using the durable bulk
+ingestion pipeline (presigned uploads + provider batch APIs). Walks `--dir` recursively, stages files
+in batches, and polls each job to completion.
+```bash
+squid kb-upload --dir ./docs --knowledgeBase my-kb
+```
+Options: `--dir` (required), `--knowledgeBase` (required), `--appId`/`--apiKey`/`--region`/`--environmentId`
+(fall back to `SQUID_APP_ID`, `SQUID_API_KEY`, `SQUID_REGION`, `SQUID_ENVIRONMENT_ID`),
+`--batchSize` (files per job, default 200, max 1000), `--extensions` (comma-separated allow-list;
+defaults to pdf, docx, txt, md, html, csv, xlsx, xls, xlsm, xlsb, pptx), `--dryRun` (list files and
+exit without contacting the server), `--timeoutMinutes` (per-job wait budget, default 120 — on
+timeout the CLI reports the job as still running server-side and moves on).
+Ctrl-C cancels the in-flight job. See [ai.md](ai.md#bulk-ingestion) for the SDK equivalent.
+
 **Extended logging** - Add to `.env`:
 ```env
 SQUID_LOG_TYPES=QUERY,MUTATION,AI,API,ERROR
@@ -500,6 +517,33 @@ export class MyService extends SquidService {
 - To secure the topic, use `@secureTopic` — see [security.md](security.md)
 - The handler receives each message individually (not batched)
 
+## Events (@eventHandler)
+
+`@eventHandler(type)` subscribes a backend function to events emitted with
+`squid.events().emit(...)` (see [client.md](client.md#events)). Unlike `@onQueueMessage`, **every**
+handler registered for the type receives the event, so one event can fan out to several services.
+
+```typescript
+import { SquidService, eventHandler } from '@squidcloud/backend';
+import { TriggerEvent } from '@squidcloud/client';
+
+export class OrderEventsService extends SquidService {
+  @eventHandler<{ orderId: string; total: number }>('order.created')
+  async onOrderCreated(event: TriggerEvent<{ orderId: string; total: number }>): Promise<void> {
+    console.log(event.id);            // unique event id
+    console.log(event.type);          // 'order.created'
+    console.log(event.payload.orderId);
+  }
+}
+```
+
+**Notes:**
+- Delivery is at-least-once with **no ordering guarantee** — handlers must be idempotent and
+  order-independent.
+- Emitting requires API key authentication; a user token is rejected.
+- Multiple subscribers per type are supported (that is the point — use `@onQueueMessage` when you
+  want queue semantics instead).
+
 ## Client Connection State (@clientConnectionStateHandler)
 
 Handle client connection and disconnection events.
@@ -620,6 +664,18 @@ export class MyService extends SquidService {
 }
 ```
 
+**`getSquid()` / `getPassiveSquid()`** — `getSquid()` returns the same instance backing `this.squid`.
+`getPassiveSquid()` returns a dedicated **passive-mode** instance (HTTP-only, no WebSocket), kept
+separate from the main one. Use it for one-off HTTP calls that should not open or keep a socket.
+
+```typescript
+import { getSquid, getPassiveSquid } from '@squidcloud/backend';
+```
+
+**Experimental:** `this.workspace` (a `WorkspaceClient`) gives a backend-only scratch directory
+synced across pod replicas via the shared workspace server — distinct from the tenant's shared
+storage.
+
 ## File Handling
 
 ```typescript

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

@@ -763,7 +763,7 @@ declare namespace JSX {
   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-override-model="gpt-5.6-terra"
   squid-ai-temperature="0.7"
   squid-ai-max-tokens="2000"
   squid-ai-agent-chat-options='{

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

@@ -18,6 +18,8 @@ Docs: https://docs.getsquid.ai/reference-docs/typescript-client/
 - Web
 - Extraction
 - Jobs
+- Events
+- LangGraph
 - Observability & Metrics
 - Custom Notifications
 
@@ -74,8 +76,8 @@ Every Squid application includes the **Essentials Connector** - a built-in integ
 |---------|--------|-------------|------|
 | **Web Utilities** | `squid.web()` | AI-powered web search, URL content extraction, short URLs | [Web section](#web) |
 | **AI Agents** | `squid.ai().agent()` | Chat with built-in or custom AI agents | [ai.md](ai.md) |
-| **Knowledge Bases** | `squid.ai().knowledgeBase()` | RAG with semantic search and reranking | [ai.md](ai.md) |
-| **Image Generation** | `squid.ai().image()` | Generate images with DALL-E | [ai.md](ai.md) |
+| **Knowledge Bases** | `squid.ai().knowledgeBase()` | RAG with semantic, keyword, and knowledge-graph search plus reranking | [ai.md](ai.md) |
+| **Image Generation** | `squid.ai().image()` | Generate images with `gpt-image-*`, Stable Diffusion, or Flux | [ai.md](ai.md) |
 | **Audio** | `squid.ai().audio()` | Transcription and text-to-speech | [ai.md](ai.md) |
 | **PDF/Extraction** | `squid.extraction()` | Create PDFs, extract data from documents | [Extraction section](#extraction) |
 | **Observability** | `squid.observability` | Report and query custom metrics | [Observability section](#observability--metrics) |
@@ -324,9 +326,9 @@ const result = await squid.withLock('payment-processing', async (lock) => {
 - `maxHoldTimeMillis` (number, default: no limit) - Max time in ms the lock can be held before automatic release. If not set, the lock is held until explicitly released or the connection is lost.
 
 **DistributedLock methods:**
-- `release()` - Release the lock
+- `release()` - Release the lock. The lock is considered released immediately; the message to the server is sent asynchronously.
 - `isReleased()` - Check if already released
-- `observeRelease()` - Observable that emits when lock is released (including unexpected release due to connection loss)
+- `observeRelease()` - Observable that emits when lock is released (including unexpected release due to connection loss). It emits as soon as the lock is considered released **locally**, without waiting for the server to confirm, and it replays — a subscriber that attaches after the release still learns about it.
 - `resourceId` - The mutex name
 - `lockId` - Unique lock instance ID
 
@@ -344,6 +346,12 @@ const web = squid.web();
 // AI-powered web search
 const results = await web.aiSearch('latest AI developments');
 
+// aiSearch(query, abortSignal?, allowedDomains?)
+// - abortSignal cancels the in-flight HTTP request, bounding a single call.
+// - allowedDomains restricts the search (subdomains included); every cited URL comes from that list.
+const controller = new AbortController();
+const scoped = await web.aiSearch('pricing changes', controller.signal, ['getsquid.ai', 'docs.getsquid.ai']);
+
 // Get URL content (as markdown)
 const content = await web.getUrlContent('https://example.com/article');
 
@@ -416,6 +424,69 @@ if (job?.status === 'completed') {
 const result = await jobClient.awaitJob<Result>('job-123');
 ```
 
+### Driving a job from your own code
+
+A job can also be created and resolved by the caller. Use this when a long operation runs outside
+Squid and clients should still `awaitJob` on it. These three methods require an API key.
+
+```typescript
+const jobId = crypto.randomUUID();
+
+await jobClient.startJob(jobId);                       // mark the job as running
+await jobClient.completeJob(jobId, { rows: 42 });      // resolve waiters with a result
+await jobClient.failJob(jobId, 'Upstream timed out');  // reject waiters with an error
+```
+
+## Events
+
+Emit a generic event that every backend function declared with `@eventHandler` for the same type
+receives. Delivery is durable and at-least-once with **no ordering guarantee**, so handlers must be
+idempotent and order-independent. `emit()` resolves once the event is enqueued, not once handlers ran.
+
+Requires API key authentication — calls authenticated with a user token are rejected.
+
+```typescript
+import { generateUUID } from '@squidcloud/client';
+
+await squid.events().emit({
+  id: generateUUID(),      // unique event id
+  type: 'order.created',   // selects the @eventHandler subscribers
+  payload: { orderId: 'o-1', total: 99.5 },
+});
+```
+
+Handle it in the backend — see [backend.md](backend.md#events-eventhandler).
+
+## LangGraph
+
+Invoke Python LangGraph graphs defined in a Python backend. Get a reference with
+`squid.langGraph(graphId)`.
+
+```typescript
+const graph = squid.langGraph('support-graph');
+
+// Run and wait for the result (new thread when threadId is omitted)
+const result = await graph.invoke({ input: { question: 'Where is my order?' } });
+// result: { ok, threadId, status: 'completed' | 'interrupted', state, next }
+
+// Run without holding a promise — returns a jobId to await later
+const jobId = await graph.invokeAsync({ threadId: 'thread-1', input: { question: '...' } });
+const later = await squid.job().awaitJob(jobId);
+
+// Resume a graph paused on interrupt()
+const resumed = await graph.resume('thread-1', { approved: true });
+const resumeJobId = await graph.resumeAsync('thread-1', { approved: true });
+
+// Inspect and clean up thread state
+const state = await graph.getState('thread-1');   // { ok, threadId, state, next }
+await graph.deleteThread('thread-1');             // idempotent; next run starts fresh
+```
+
+Graph execution caps at the tenant IPC timeout (currently 4 minutes) for every variant — the `Async`
+methods only free the caller from holding the promise.
+
+Secure invocations with the backend `@secureLangGraph` decorator — see [security.md](security.md#securelanggraph).
+
 ## Observability & Metrics
 
 Report and query custom metrics for monitoring application performance.

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

@@ -48,6 +48,7 @@ The AI Studio provides visual tools for building and testing AI agents:
 ### Agent Configuration
 - Create and configure AI agents visually
 - Set agent instructions, models, and guardrails
+- Refuse prompts containing PII under Guardrails → Prompt Privacy (toggle, a checkbox per kind, and custom rules)
 - Configure agent memory and conversation settings
 - Connect agents to functions, knowledge bases, and integrations
 
@@ -76,6 +77,10 @@ The AI Studio provides visual tools for building and testing AI agents:
 - Search and preview indexed content
 - Monitor indexing status
 
+### Knowledge Graph
+- Enable via the **Knowledge Graph** toggle when creating a knowledge base with **Vector Store** set to `mongoAtlas` (disabled for other stores — the store is immutable after creation), or later by editing an Atlas knowledge base
+- Knowledge base page shows a **Knowledge Graph** card: last build time, documents changed since it, next automatic build ETA, and a **Build now** button (runs a structural build)
+
 ## Integrations Setup
 
 ### Database Connections
@@ -151,7 +156,7 @@ const agent = squid.ai().agent('my-agent');
 await agent.upsert({
   description: 'Customer support agent',
   options: {
-    model: 'gpt-4o',
+    model: 'gpt-5.6-terra',
     instructions: 'You are a helpful support agent...'
   }
 });

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

@@ -8,6 +8,8 @@ Squid provides database functionality similar to Firestore but more powerful, wi
 - CRUD Operations
 - Real-time Subscriptions
 - Query Operators
+- Querying by Document ID
+- Deleting by Query
 - OR Queries
 - Join Queries
 - Dereference
@@ -231,6 +233,52 @@ const sorted = await users.query()
 
 **Note:** `offset()` does NOT exist - use `paginate()` for pagination.
 
+## Querying by Document ID
+
+Filter on the document id with the `docId()` / `docIds()` shortcuts, or with `__docId__` (the
+`DOC_ID_FIELD` constant) in `eq`/`neq`/`in`/`nin`/`where`. This works for both single- and
+composite-key collections: pass the primitive for a single-field key, or the key object for a
+composite one.
+
+```typescript
+import { DOC_ID_FIELD } from '@squidcloud/client';
+
+// Single-key collection
+const one = await users.query().docId('user-1').snapshot();
+const some = await users.query().docIds(['user-1', 'user-2']).snapshot();
+
+// Composite-key collection - pass the key object
+const line = await orderLines.query().docId({ orderId: 'o-1', lineNo: 3 }).snapshot();
+
+// Equivalent explicit forms
+await users.query().eq(DOC_ID_FIELD, 'user-1').snapshot();
+await users.query().in(DOC_ID_FIELD, ['user-1', 'user-2']).snapshot();
+await users.query().where(DOC_ID_FIELD, '==', 'user-1').snapshot();
+await users.query().where(DOC_ID_FIELD, 'in', ['user-1', 'user-2']).snapshot();
+```
+
+`docId()` is `eq(DOC_ID_FIELD, ...)` and `docIds()` is `in(DOC_ID_FIELD, ...)` — use them instead of
+fetching a page and filtering client-side.
+
+## Deleting by Query
+
+`delete()` on a query deletes every document the query selects and returns how many were selected.
+
+```typescript
+const { deletedCount } = await users.query()
+  .eq('status', 'inactive')
+  .lt('lastLoginAt', cutoff)
+  .delete();
+```
+
+`sortBy`, `limit`, and `limitBy` are rejected — `delete()` throws if the query carries any of them.
+A query whose `in` condition is an empty array selects nothing, so it deletes nothing and returns
+`{ deletedCount: 0 }`. An empty `nin` behaves the opposite way: it contributes no condition at all,
+so it does not restrict the delete — `users.query().nin('id', []).delete()` deletes everything the
+remaining conditions select, the whole collection when there are none. Narrow an empty exclusion list
+in your own code before calling `delete()`. Deletes go through the collection's `delete` security
+rules, same as `doc.delete()`.
+
 ## OR Queries
 
 Combine multiple queries with OR logic:

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

@@ -7,7 +7,7 @@ OpenAI-specific features in Squid. For general AI usage, see [ai.md](ai.md).
 ```typescript
 import {
   OPENAI_CHAT_MODEL_NAMES,                  // Chat models
-  OPENAI_IMAGE_MODEL_NAMES,                 // DALL-E
+  OPENAI_IMAGE_MODEL_NAMES,                 // gpt-image-*
   OPENAI_AUDIO_TRANSCRIPTION_MODEL_NAMES,   // Whisper
   OPENAI_AUDIO_CREATE_SPEECH_MODEL_NAMES,   // TTS
   OPENAI_EMBEDDINGS_MODEL_NAMES,            // Embeddings

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

@@ -10,7 +10,7 @@ Squid provides a comprehensive security model using backend decorators. Every op
 - Storage Security
 - API Security
 - Native Query Security
-- AI Security
+- AI Security (including @secureLangGraph)
 - Distributed Lock Security
 - GraphQL Security
 - Authentication Patterns
@@ -132,6 +132,34 @@ context.affectsPath(path) // Check if specific field path was modified
 
 Both types are exported from `@squidcloud/backend`.
 
+### @publicCollection
+
+A **class** decorator that declares reads of a collection as intentionally public. Public reads
+bypass security-rule evaluation entirely: Core serves them without calling backend code, so any
+client can read the collection, **including unauthenticated ones**. Use it only for data that is
+safe to expose to everyone; prefer a `@secureCollection` read rule when access depends on the caller.
+
+```typescript
+import { SquidService, publicCollection, secureCollection, MutationContext } from '@squidcloud/backend';
+
+// Anyone can read `articles`, but only authenticated users can write to it.
+@publicCollection('articles', 'read')
+export class ArticleService extends SquidService {
+  @secureCollection('articles', 'write')
+  async secureArticlesWrite(context: MutationContext): Promise<boolean> {
+    return this.isAuthenticated();
+  }
+}
+```
+
+- Signature: `publicCollection(collectionName, 'read', integrationId?)`. `integrationId` defaults to
+  the built-in database.
+- Only `read` is supported. Writes always go through their security rules, so a public-read
+  collection can still restrict `insert`/`update`/`delete`/`write`.
+- **Secure wins on conflict:** if a `@secureCollection` or `@secureDatabase` `read` (or `all`) rule
+  also applies to the same collection, that rule takes precedence at runtime and the public
+  declaration is ignored.
+
 ## Queue Security
 
 ### @secureTopic
@@ -270,6 +298,51 @@ allowAllAgents(): boolean {
 }
 ```
 
+### @secureLangGraph
+
+Secures LangGraph invocations made with `squid.langGraph(graphId)` (see
+[client.md](client.md#langgraph)).
+
+```typescript
+import { SquidService, secureLangGraph, SecureLangGraphContext } from '@squidcloud/backend';
+
+// Secure a specific graph
+@secureLangGraph('support-graph')
+allowSupportGraph(context: SecureLangGraphContext): boolean {
+  // context.operation: 'invoke' | 'resume' | 'getState' | 'deleteThread'
+  const userId = this.getUserAuth()?.userId;
+  if (!userId) return false;
+  // This app mints thread ids as `${userId}:${conversation}` and passes one on every call, so
+  // ownership is derived from threadId. Check it on every operation, not just deleteThread:
+  // threadId is a client-supplied field everywhere and threads carry no owner of their own, so
+  // this rule is all that stops one authenticated user from reading, extending, or deleting
+  // another's thread. An invoke that omits threadId is refused too: the runtime would mint a bare
+  // UUID, and no later call on that thread could satisfy this rule.
+  // Never derive ownership from context.input — it is populated on invoke only, so the comparison
+  // would be undefined === undefined, which passes for exactly the callers it should refuse.
+  return !!context.threadId && context.threadId.startsWith(`${userId}:`);
+}
+
+// Secure all graphs
+@secureLangGraph()
+allowAllGraphs(context: SecureLangGraphContext): boolean {
+  return this.isAuthenticated();
+}
+```
+
+`SecureLangGraphContext` carries `operation`, `graphId`, `threadId`, `input`, and `resumePayload`.
+Only the fields the triggering request itself carries are populated: `input` on `invoke` only,
+`resumePayload` on `resume` only, and `threadId` on everything except an `invoke` that starts a new
+thread. A rule that reads a field its operation does not carry sees `undefined`, so write ownership
+checks that cannot pass on `undefined` — otherwise an unauthenticated caller, whose `getUserAuth()`
+is also `undefined`, is the one the rule lets through.
+
+A thread has no owner at the storage layer and `threadId` reaches the rule straight from the client
+body on every operation, so the `@secureLangGraph` rule is the only per-thread access control there
+is. The `allowAllGraphs` shape above authenticates the caller but does not scope them to their own
+threads — enough for a single-tenant graph, not for one where users must not see each other's
+conversations.
+
 ## Distributed Lock Security
 
 ### @secureDistributedLock

package/dist/resources/claude/skills/squid-integrations/reference/connector-functions.md

@@ -12,7 +12,7 @@ Each Squid SaaS connector provides built-in AI functions that AI agents can call
 await squid.ai().agent('my-agent').upsert({
   description: 'Support agent',
   options: {
-    model: 'gpt-5-mini',
+    model: 'gpt-5.6-terra',
     instructions: 'You are a support agent that can search tickets and send messages.'
   }
 });

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

@@ -164,12 +164,13 @@ function TaskList({ userId }: { userId: string }) {
   const tasksCollection = useCollection<Task>('tasks');
   const query = tasksCollection.query().where('userId', '==', userId);
 
-  const { loading, data, error } = useQuery(query, {
+  const { loading, data, error, enabled } = useQuery(query, {
     enabled: !!userId,      // Only run when userId is set
     subscribe: true,        // Real-time updates (default)
     initialData: [],        // Initial data before first load
   }, [userId]);             // Re-subscribe when userId changes
 
+  if (!enabled) return <div>No user selected</div>;  // Check before `loading`
   if (loading) return <div>Loading...</div>;
   if (error) return <div>Error: {error.message}</div>;
 
@@ -201,9 +202,20 @@ interface QueryType<T> {
   loading: boolean;
   data: Array<T>;
   error: any;
+  enabled: boolean;       // Mirrors options.enabled
 }
 ```
 
+**`loading` stays `true` while the query is disabled.** A disabled query never subscribes, so it
+never resolves — gate on `enabled` first, or `if (loading)` renders a spinner forever:
+
+```typescript
+const { loading, data, error, enabled } = useQuery(query, { enabled: !!userId }, [userId]);
+
+if (!enabled) return <SelectUserPrompt />;  // Not "loading" - just not running
+if (loading) return <Spinner />;
+```
+
 **Single Snapshot vs Real-time:**
 ```typescript
 // Real-time updates (subscribe: true) - default
@@ -940,7 +952,7 @@ function AdvancedFeatures() {
     const agent = squid.ai().agent('new-agent');
     await agent.upsert({
       description: 'My new agent',
-      options: { model: 'gpt-4o' },
+      options: { model: 'gpt-5.6-terra' },
     });
   };
 
@@ -1054,13 +1066,18 @@ const { data } = useQuery(
 ### 2. Use `enabled` for Conditional Fetching
 
 ```typescript
-// GOOD: Prevent unnecessary queries
-const { data } = useQuery(query, { enabled: !!userId }, [userId]);
+// GOOD: Prevent unnecessary queries, and distinguish "disabled" from "loading"
+const { data, loading, enabled } = useQuery(query, { enabled: !!userId }, [userId]);
+if (!enabled) return <EmptyState />;   // `loading` is still true here
+if (loading) return <Spinner />;
 
 // BAD: Query runs even when userId is null
 const { data } = useQuery(query, {}, [userId]);
 ```
 
+Only `useQuery` returns `enabled`. For the other hooks, track the same condition yourself rather
+than relying on `loading` to go false while they are disabled.
+
 ### 3. Provide Type Parameters
 
 ```typescript

package/package.json

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