@squidcloud/cli 1.0.486 → 1.0.488

package/dist/index.js

@@ -40729,7 +40729,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.486","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.486","adm-zip":"^0.5.16","copy-webpack-plugin":"^14.0.0","decompress":"^4.2.1","logpipes":"^1.11.0","nodemon":"^3.1.9","terser-webpack-plugin":"^5.5.0","ts-loader":"^9.5.1","ts-node":"^10.9.2","tsconfig-paths":"^4.2.0","tsconfig-paths-webpack-plugin":"^4.1.0","webpack":"^5.106.2","zip-webpack-plugin":"^4.0.1"},"devDependencies":{"@types/adm-zip":"^0.5.7","@types/decompress":"^4.2.7","terminal-link":"^3.0.0"}}');
+module.exports = /*#__PURE__*/JSON.parse('{"name":"@squidcloud/cli","version":"1.0.488","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.488","adm-zip":"^0.5.16","copy-webpack-plugin":"^14.0.0","decompress":"^4.2.1","logpipes":"^1.11.0","nodemon":"^3.1.9","terser-webpack-plugin":"^5.5.0","ts-loader":"^9.5.1","ts-node":"^10.9.2","tsconfig-paths":"^4.2.0","tsconfig-paths-webpack-plugin":"^4.1.0","webpack":"^5.106.2","zip-webpack-plugin":"^4.0.1"},"devDependencies":{"@types/adm-zip":"^0.5.7","@types/decompress":"^4.2.7","terminal-link":"^3.0.0"}}');
 
 /***/ }
 

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

@@ -21,15 +21,15 @@ Squid is a backend-as-a-service platform that provides:
 
 ## Feature-Specific Guidance
 
-- **[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
+- **[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, allowedDomains, getUrlContent, createShortUrl, jobs, getJob, awaitJob, startJob, completeJob, failJob, events, squid.events(), emit, TriggerEvent, LangGraph, squid.langGraph(), invoke, invokeAsync, resume, getState, deleteThread, observability, metrics, reportMetric, queryMetrics, setMetricAnnotations, notifications, publishNotification, observeNotifications
+- **[console.md](reference/console.md)** → Squid Console, web UI, organizations, applications, AI Studio, knowledge bases, knowledge graph toggle, 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, metricAnnotations, voiceOptions, OpenAI, Anthropic, Gemini, Grok, DALL-E, Whisper, MCP, @mcpServer, @mcpTool, agent as MCP server, updateMcpServer, generateMcpDescriptions, agent API key, executeAiQuery, executeAiApiCall, extraction, createPdf, upsert agent, listAgents, listChatModels, listFunctions, spreadsheet understanding, querySpreadsheetsWithAi, searchMode, keyword search, xlsx, csv, grep, literal scan, knowledge graph, GraphRAG, graphRag, graph search, queryGraph, getGraphStatus, rebuildGraph, exploreGraph, searchWithGraphContext, graphOptions, graphFilter, underConcept, entityTypes, queryKnowledgeGraph, bulk ingestion, bulkUpsertContexts, createBulkUploadUrls, observeBulkIngestionJob, listContextsPage, generateMetadataFieldDescriptions
 - **[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, @onQueueMessage, QueueMessageRequest, queue message handler, server-side queue consumer, CLI, squid init, squid start, squid deploy, squid build, project structure, multiple services, service architecture, squidInject, cross-service communication
-- **[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
+- **[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(), docId, docIds, query.delete(), delete by query, 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, getSquid, getPassiveSquid, this.secrets, @clientConnectionStateHandler, @onQueueMessage, QueueMessageRequest, queue message handler, server-side queue consumer, @eventHandler, event handler, workspace, CLI, squid init, squid start, squid deploy, squid build, squid kb-upload, printBundle, project structure, multiple services, service architecture, squidInject, cross-service communication
+- **[security.md](reference/security.md)** → security rules, @secureDatabase, @secureCollection, @publicCollection, public read, @secureTopic, @secureStorage, @secureApi, @secureNativeQuery, @secureAiQuery, @secureAiAgent, @secureLangGraph, @secureDistributedLock, @secureGraphQL, QueryContext, MutationContext, SecureLangGraphContext, 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, connectors admin, squid.admin().connectors(), attach connector, appConnectors, upsertIntegration, discoverDataConnectionSchema, testDataConnection, createOrganization, createApplication
+- **[api.md](reference/api.md)** → API, REST API, HTTP endpoints, API reference, Agent API, AiSettings API, AiFunction API, AI Audio API, AI Image API, KnowledgeBase API, Matchmaking API, Web Utilities API, Database API, Extraction API, apiKeyAuth, agentApiKeyAuth, x-squid-agent-api-key, memoryOptions, memoryId, memoryMode
 - **[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, @squidcloud/slack-client, @squidcloud/jira-client, @squidcloud/github-client, @squidcloud/salesforce-client, @squidcloud/freshdesk-client, @squidcloud/linear-client, @squidcloud/mail-client, @squidcloud/google-calendar-client, @squidcloud/google-drive-client, @squidcloud/teams-client, @squidcloud/sharepoint-client, @squidcloud/servicenow_csm-client, @squidcloud/jira-jsm-client, SquidSlackClient, SquidJiraClient, SquidGitHubClient, sendMail, sendMessage, searchIssues, createIssue, connector SDK
 - **Integrations** → See `squid-integrations` skill for full catalog, connector AI functions, SDK methods, and configuration

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

@@ -5,6 +5,7 @@ This document covers programmatic management of Squid organizations, application
 ## Contents
 - ManagementClient
 - Admin Integrations
+- Admin Connectors
 - Admin Secrets
 
 ## ManagementClient
@@ -204,6 +205,35 @@ const openApiSchema = await integrations.discoverOpenApiSchema('my-api', {
 const fileSchema = await integrations.discoverOpenApiSchemaFromFile('my-api');
 ```
 
+### Admin - Connectors
+
+Attach and detach **app-level (integration-less) connectors**. Unlike integrations, these carry no
+per-connector configuration record — attaching one adds it to the application's `appConnectors` list
+and (re)deploys its bundle. Any configuration the connector needs comes in out of band, e.g. via
+application secrets.
+
+```typescript
+const connectors = squid.admin().connectors();
+
+// List the connectors explicitly attached to the app
+const attached = await connectors.list();       // Array<ConnectorId>
+
+// Attach (idempotent - attaching an already-attached connector is a no-op)
+await connectors.connect('slack');
+
+// Detach
+await connectors.disconnect('slack');
+```
+
+`ConnectorId` is one of: `bitbucket`, `confluence`, `cotomi`, `essentials`, `freshdesk`, `github`,
+`google_calendar`, `google_drive`, `hubspot`, `sharepoint`, `jira`, `jira_jsm`, `linear`, `mail`,
+`onedrive`, `outlook`, `salesforce`, `servicenow_csm`, `slack`, `teams`, `ticketmind_companion`,
+`zendesk`.
+
+**Connectors vs integrations:** use `squid.admin().integrations()` when the connection needs
+configuration (credentials, a connection string, an OAuth app). Use `connectors()` for connectors the
+app just needs turned on.
+
 ### Admin - Secrets
 
 ```typescript

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

@@ -54,6 +54,21 @@ import {
 } from '@squidcloud/client';
 ```
 
+**Active chat models** (the constants above hold active models only; deprecated ones carry a
+`replacedBy` and are excluded unless asked for):
+
+| Provider | `*_CHAT_MODEL_NAMES` |
+|---|---|
+| OpenAI | `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.5`, `gpt-5.5-pro`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna` |
+| Anthropic | `claude-fable-5`, `claude-haiku-4-5-20251001`, `claude-opus-5`, `claude-sonnet-5` |
+| Gemini | `gemini-3.1-pro`, `gemini-3.6-flash`, `gemini-3.5-flash-lite` |
+| Grok | `grok-4.5`, `grok-4-1-fast-reasoning`, `grok-4-1-fast-non-reasoning` |
+
+This list moves. **Don't hardcode a model name from this table into user code** — call
+`squid.ai().listChatModels()`, which also returns the app's custom integration models
+(`openai_compatible`, Bedrock, Vertex) and flags deprecated ones. See
+[Application Settings](#application-settings).
+
 **Model Categories:**
 - **Chat Models**: Used for AI Agents, AI Query, etc. (OpenAI, Anthropic, Gemini, Grok)
 - **Embedding Models**: Used for Knowledge Bases (OpenAI, Voyage)
@@ -76,6 +91,7 @@ An AI Agent can:
 - Collaborate with other AI agents
 - Process voice input and generate voice output
 - Accept files as part of chat requests
+- Refuse prompts that contain PII before they reach the model (see Rejecting PII in prompts)
 
 ### Creating and Managing Agents
 
@@ -99,7 +115,7 @@ await myAgent.upsert({
   isPublic: false,  // Whether the agent is publicly accessible
   auditLog: true,   // Enable audit logging for compliance
   options: {
-    model: 'gpt-5-mini', // or 'claude-sonnet-4-5-20250929', 'gemini-3-flash'
+    model: 'gpt-5.4-mini', // or 'claude-sonnet-5', 'gemini-3.6-flash' - see Supported Models
     instructions: 'You are a helpful customer support assistant. Be concise and professional.',
     temperature: 0.7
   }
@@ -111,7 +127,7 @@ 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.updateModel('claude-sonnet-5');
 await myAgent.updateGuardrails(['no-harmful-content']);
 
 // Delete an agent
@@ -140,8 +156,85 @@ await myAgent.updateConnectedAgents([
 // Update or delete custom guardrails
 await myAgent.updateCustomGuardrails('Never reveal sensitive information');
 await myAgent.deleteCustomGuardrail();
+
+// Refuse prompts that contain PII (see "Rejecting PII in prompts" below)
+await myAgent.updatePii({ onDetect: 'reject' });
+
+// Expose the agent itself as an MCP server (see "Agent as an MCP server" below)
+await myAgent.updateMcpServer({ enabled: true, requireApiKey: true });
+```
+
+### Agent as an MCP Server
+
+Any agent can be published as an MCP server at `/mcp/<agentId>` with **no backend code** — the server
+exposes a single `ask` tool that calls the agent. This is the inverse of `@mcpServer`, which exposes
+*your* backend tools to agents. Transport is the official MCP **Streamable HTTP** transport.
+`updateMcpServer` requires an API key.
+
+```typescript
+// AI-generate the server + tool descriptions from the agent's instructions and connected resources.
+// Returns them WITHOUT persisting - save them with updateMcpServer.
+const generated = await myAgent.generateMcpDescriptions();
+
+await myAgent.updateMcpServer({
+  enabled: true,
+  description: generated.description,        // served as `instructions` in the MCP initialize result
+  toolDescription: generated.toolDescription, // description of the `ask` tool in the tools manifest
+  requireApiKey: true,                        // require the agent's API key as a bearer token
+  oauthIntegrationId: 'auth0'                 // or OAuth-protect it with an auth integration
+});
+```
+
+**`AiAgentMcpServerConfig`:**
+- `enabled` — whether the agent is exposed as an MCP server.
+- `description` — defaults to the agent description when omitted.
+- `toolDescription` — defaults to a generic ask-the-agent description.
+- `requireApiKey` — when true, requests must present the agent's API key as
+  `Authorization: Bearer <agent API key>` or the `x-squid-agent-api-key` header.
+- `oauthIntegrationId` — OAuth-protects the endpoint with an auth integration's bearer tokens.
+- Combining `oauthIntegrationId` and `requireApiKey` accepts **either** credential.
+- **With neither set, the MCP endpoint is public.**
+
+### Rejecting PII in prompts
+
+`pii` refuses an incoming prompt that carries personal information **before it reaches the
+agent's model**. The prompt is not answered, no quota is consumed, and nothing is written to
+chat memory. The caller gets an error whose message starts with `PII_DETECTED_IN_PROMPT`.
+
+Do not confuse it with `guardrails.disablePii`, which is the opposite direction — that one asks
+the agent's own model not to *emit* PII in its answer, and is best-effort prompt text. Use `pii`
+when the requirement is that the data must not reach the model at all.
+
+```typescript
+await squid.ai().agent('support-agent').updatePii({
+  onDetect: 'reject',                    // 'off' (default) disables screening
+  entities: ['email', 'ssn'],            // omit for every kind
+  customRules: ['internal case numbers like CASE-12345'],
+  allowList: ['support@squid.cloud'],    // literal values that never count as PII
+  classifierModel: 'gpt-5.6-luna',       // default; small and fast
+});
 ```
 
+| Field | Meaning |
+|---|---|
+| `onDetect` | `'reject'` refuses the prompt; `'off'` (default) disables screening |
+| `entities` | Kinds to screen for: `email`, `phoneNumber`, `creditCard`, `ssn`, `iban`, `passport`. Omitted means all |
+| `customRules` | App-specific PII in plain language — anything a model can recognize from a description |
+| `allowList` | Exact values that must never be flagged |
+| `classifierModel` | Model doing the screening. Defaults to `gpt-5.6-luna` |
+
+Things to know before enabling it:
+
+- **Every prompt costs one extra model call.** Screening runs ahead of the agent's own model, so
+  it adds latency and tokens to each turn.
+- **It is prompt-side only.** Tool results and knowledge-base chunks can still bring PII into the
+  model. Don't describe it to a user as an end-to-end guarantee.
+- **It is fail-closed.** If the classifier is unreachable the turn is rejected with
+  `PII_SCREENING_UNAVAILABLE` rather than admitted unscreened.
+- **It cannot be overridden per request.** Passing `pii` in `ask`/`chat` options is ignored; the
+  stored agent's value always wins, so a caller cannot opt out of its own screening.
+- **Rejections are audited with the prompt redacted** — matched kinds are recorded, never values.
+
 ### Agent Lifecycle
 
 1. **Creation** - Use `upsert()` to create a new agent with an ID
@@ -165,6 +258,8 @@ Agents become powerful when connected to resources:
 - **Backend functions** (`functions`) - Custom logic via `@aiFunction` decorators
 - **Integrations** (`connectedIntegrations`) - Database/API queries
 - **Knowledge bases** (`connectedKnowledgeBases`) - RAG (Retrieval Augmented Generation)
+- **Source repositories** (a `github`/`bitbucket` integration with code analysis enabled) - see
+  [Source-Code Analysis](#source-code-analysis)
 
 #### Connected Agents
 
@@ -258,6 +353,8 @@ const response = await agent.ask('What is our return policy?', {
 });
 ```
 
+Knowledge bases with a knowledge graph give the agent graph retrieval and a `queryKnowledgeGraph` tool automatically — see [Knowledge Graph (GraphRAG)](#knowledge-graph-graphrag).
+
 ### Agent Chat Methods
 
 ```typescript
@@ -268,13 +365,20 @@ const agent = squid.ai().agent('my-agent');
 // - 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
+  // Memory management. `memoryOptions` is the only way to name a conversation and control
+  // history: `memoryId` names it, `memoryMode` controls whether history is read and written.
   memoryOptions: {
     memoryMode: 'read-write', // 'none' | 'read-only' | 'read-write'
     memoryId: 'user-123',     // Unique per user/session
     expirationMinutes: 1440   // 24 hours
   },
 
+  // Usage tracking: reported as `annotation.<key>` tags on Squid AI usage metrics, so token
+  // usage can be filtered/grouped by them. Inherited by nested connected-agent calls.
+  // Limits: max 10 entries, keys <= 64 chars, values <= 256 chars; excess is dropped/truncated.
+  // Set app-wide defaults with squid.setMetricAnnotations({...}); per-call values merge on top.
+  metricAnnotations: { feature: 'support-bot', requestSource: 'mobile' },
+
   // Connected resources (can also be set on agent.upsert)
   connectedAgents: [{ agentId: 'specialist-agent', description: 'Handles X' }],
   functions: ['function1', 'function2'],
@@ -282,7 +386,7 @@ const chatObs = agent.chat('What is your return policy?', {
   connectedKnowledgeBases: [{ knowledgeBaseId: 'kb1', description: 'When to use this KB' }],
 
   // Model & generation
-  model: 'gpt-5-mini', // Override agent's default model
+  model: 'gpt-5.4-mini', // Override agent's default model
   temperature: 0.7,
   maxTokens: 4000,
   maxOutputTokens: 2000,
@@ -305,6 +409,15 @@ const chatObs = agent.chat('What is your return policy?', {
     maxAiCallStackSize: 5
   },
 
+  // Refuse incoming prompts that carry PII (stored on the agent; ignored if passed per request)
+  pii: {
+    onDetect: 'reject',
+    entities: ['email', 'phoneNumber', 'creditCard', 'ssn', 'iban', 'passport'],
+    customRules: ['internal case numbers like CASE-12345'],
+    allowList: ['support@squid.cloud'],
+    classifierModel: 'gpt-5.6-luna'
+  },
+
   // Files & voice
   fileUrls: [
     { id: 'file1', type: 'image', purpose: 'context', url: 'https://...', description: 'Product image' }
@@ -320,7 +433,7 @@ const chatObs = agent.chat('What is your return policy?', {
   useCodeInterpreter: 'llm', // 'none' | 'llm' (OpenAI/Gemini only)
   executionPlanOptions: {
     enabled: true,
-    model: 'gpt-5-mini',
+    model: 'gpt-5.4-mini',
     reasoningEffort: 'high',
     allowClarificationQuestions: false
   },
@@ -436,6 +549,19 @@ const searchResults = await kb.search({
   limit: 10
 });
 
+// Keyword (lexical, embedding-free) search — best for exact tokens: IDs, error codes, SKUs, file names.
+// searchMode: 'vector' | 'hybrid' | 'keyword' | 'graph'. Default: 'hybrid' ('graph' on GraphRAG-enabled
+// KBs; setting 'graph' on other KBs throws). Keyword mechanics differ by the KB's vectorDbType:
+// mongoAtlas = ranked BM25, term-optional (partial matches still rank); postgres = unranked boolean
+// filter where EVERY whitespace-separated term must appear as a literal substring — a multi-word
+// prompt returns zero chunks when any one term is absent, so pass few, specific tokens.
+// On postgres 'hybrid' degrades to dense-only (no lexical channel; hybridWeights is ignored off
+// Mongo), so exact-token retrieval there REQUIRES explicitly setting searchMode: 'keyword'.
+const keywordResults = await kb.search({
+  prompt: 'ERR_0000_4F2A',
+  searchMode: 'keyword'
+});
+
 // Get context
 const context = await kb.getContext('doc-123');
 
@@ -443,14 +569,229 @@ const context = await kb.getContext('doc-123');
 const allContexts = await kb.listContexts(1000); // truncateTextAfter
 const contextIds = await kb.listContextIds();
 
+// List a PAGE of contexts (prefer this over listContexts for large KBs)
+const page = await kb.listContextsPage({
+  offset: 0,
+  limit: 50,
+  truncateTextAfter: 500,
+  search: 'invoice'   // case-insensitive substring match on id/title only
+});
+
 // Download context
 const download = await kb.downloadContext('doc-123');
 
 // Delete contexts
 await kb.deleteContext('doc-123');
 await kb.deleteContexts(['doc-1', 'doc-2']);
+
+// AI-generate descriptions for the KB's metadata fields (helps metadata filtering quality).
+// Returns { fields } WITHOUT persisting - save them yourself via upsertKnowledgeBase.
+// By default only fields with an empty description are generated.
+const { fields } = await kb.generateMetadataFieldDescriptions({
+  fieldNames: ['category'],   // optional; omitted => all declared fields
+  overwriteExisting: false    // true regenerates fields that already have a description
+});
+```
+
+`upsertContexts` accepts an options object with an `onUploaded` callback, fired once the payload has
+been uploaded and accepted — server-side extraction and embedding continue after it, and the promise
+still resolves only when ingestion completes:
+
+```typescript
+await kb.upsertContexts(contexts, files, { onUploaded: () => setStatus('Uploaded, indexing…') });
+```
+
+### Metadata Filters
+
+A MongoDB-style grammar shared across KB context filtering, metrics tag filtering, and matchmaking
+(the types live in `@squidcloud/client`). Used by `kb.search`, `kb.grep`, and the chat option
+`contextMetadataFilterForKnowledgeBase`.
+
+```typescript
+// A bare scalar is shorthand for $eq
+{ category: 'user-guide' }
+
+// Field operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists
+{ version: { $gte: 2 }, status: { $in: ['published', 'review'] }, archivedAt: { $exists: false } }
+
+// Boolean combinators
+{ $or: [{ category: 'faq' }, { $and: [{ category: 'guide' }, { version: { $gte: 2 } }] }] }
+```
+
+**`$underPath` (knowledge bases only)** — segment-safe subtree match on a hierarchical string field
+such as `folderPath`:
+
+```typescript
+{ folderPath: { $underPath: 'reports/2023' } }
+```
+
+Matches `reports/2023` and `reports/2023/q1/deck`, but never the lexical sibling
+`reports/2023 drafts` — the `/` separator supplies the segment boundary, so subtree scoping cannot
+leak into a sibling that merely shares a prefix. Leading/trailing `/` in the operand are stripped, an
+empty operand matches every document that *has* the field, and matching is **case-sensitive**.
+
+The canonical `folderPath` form: POSIX `/` separators, no leading/trailing slash, `''` (not
+`undefined`) for the upload root, case preserved, NFC-normalized. `folderPath` is an ordinary
+metadata key, not a reserved one.
+
+`$underPath` is deliberately absent from the shared filter type that metrics and matchmaking consume
+— they reject unknown operators at runtime.
+
+### Literal Scan (grep)
+
+`grep()` scans the KB's **raw extracted text** (pre-chunking, so spreadsheet rows appear verbatim)
+for a literal string and returns every matching line with its file and locator. Use it when you need
+characters, not meaning: IDs, error codes, SKUs, exact phrases.
+
+```typescript
+const hits = await kb.grep('ERR_0000_4F2A', {
+  metadataFilter: { category: 'runbooks' },  // same grammar as chunk search, incl. $and/$or/$underPath
+  maxMatches: 100
+});
+```
+
+- The pattern is **always literal** — every regex metacharacter is escaped — and may span lines.
+- Matching is case-insensitive **for ASCII letters only**: `acme` finds `ACME`, but `café` does not
+  find `CAFÉ`. Search the exact casing for non-ASCII text.
+- `metadataFilter` selects contexts **before** any text is matched.
+
+### Knowledge Graph (GraphRAG)
+
+A graph-enabled knowledge base extracts an entity/relationship graph at ingest and layers concepts on top (document nodes, themes clustered from the entity graph, facet trees from context metadata). Retrieval can then follow links across documents — answering questions whose supporting facts are split over several files — and agents can navigate corpus structure instead of only quoting passages.
+
+Requirements: `vectorDbType: 'mongoAtlas'` (immutable after creation — a `postgres` KB can never gain a graph). `graphRag` itself is mutable: enabling it on an existing Atlas KB auto-backfills the graph; disabling only makes graph search unavailable and RETAINS the extracted graph data, so re-enabling is cheap (a structural build folds in never-indexed contexts, reusing prior extraction). To actually reclaim the graph data, call `rebuildGraph()` while `graphRag.enabled` is false — that is the explicit cleanup path; otherwise only deleting the KB drops it. Extraction runs an LLM over every chunk at ingest — budget before enabling on a large corpus, and track spend via `getGraphStatus()`.
+
+```typescript
+// Enable at creation, or later by upserting with the current config spread — upserting
+// graphRag replaces the whole object, so omitted fields are lost.
+await kb.upsertKnowledgeBase({
+  description: 'Company filings',
+  vectorDbType: 'mongoAtlas', // Required for the graph.
+  graphRag: {
+    enabled: true,
+    // Optional extraction hint; proper nouns (orgs, people, places) extract far more
+    // reliably than generic product categories.
+    entityTypes: ['ORGANIZATION', 'PRODUCT', 'LOCATION'],
+    // Other fields: extractionModel, autoBuildDebounceMs (quiet window before automatic
+    // concept builds, default 5 min), concepts: { facets: 'auto' | [fields], pathFacets:
+    // [{ field: 'folderPath', type: 'path' }] } (folder tree from a path metadata field).
+  },
+});
+
+// Graph search: seeds entities from the prompt via vector search, walks relationships,
+// maps reached entities back to chunks, fuses with hybrid search. 'graph' is the DEFAULT
+// searchMode on a graph-enabled KB, so it can be omitted. Passing it explicitly on a KB
+// without GraphRAG throws GRAPH_SEARCH_NOT_ENABLED — no silent fallback to hybrid.
+const graphChunks = await kb.search({
+  prompt: 'Which drugs does Aldous Corporation sell?',
+  searchMode: 'graph',
+  graphOptions: { seedLimit: 8, maxHops: 2 }, // Defaults shown; caps 25 and 3.
+});
+
+// Like search() but returns the full response, including the traversed subgraph
+// (entities + relationships) — for debugging retrieval or explaining results.
+const response = await kb.searchWithGraphContext({
+  prompt: 'Which drugs does Aldous Corporation sell?',
+  searchMode: 'graph',
+  graphOptions: { includeGraphContext: true },
+});
+
+// Scope ANY search mode to the documents under one theme or facet; composes with
+// contextMetadataFilter. Value: a concept name (resolved server-side) or a facet nodeId.
+// Unresolvable concepts fail with CONCEPT_NOT_FOUND plus the nearest matching names.
+await kb.search({ prompt: 'What was the purchase price?', graphFilter: { underConcept: 'Acquisitions' } });
+
+// Structure queries — one round trip each. Ops: 'overview' (themes/facets/counts map),
+// 'resolve' | 'describe' | 'subtree' | 'docsUnder' | 'neighborhood' (take ref),
+// 'conceptsOf' (takes contextId), 'pathBetween' (ref + refB -> relationship chain, or the
+// concepts both sit under when no chain exists), 'globalSummary' (takes query).
+const overview = await kb.queryGraph({ op: 'overview' });
+const path = await kb.queryGraph({ op: 'pathBetween', ref: 'Aldous Corporation', refB: 'Zalofen' });
+
+// Build state, coverage and cost: contextsIndexed/contextsTotal, entityCount,
+// relationshipCount, topics/facets, structureStale/staleDocCount, buildJob,
+// nextAutoBuildAt, ingestUsage/lastRebuildUsage (LLM tokens + estimated USD).
+const status = await kb.getGraphStatus();
+
+// Force a concept-layer build now instead of waiting for the debounced automatic build.
+// Default mode 'structural' reuses extracted entities (cheap). mode: 'full' wipes the
+// graph and re-extracts every chunk with the LLM — cost on the order of the initial
+// ingest; only needed after changing entityTypes or extractionModel.
+await kb.rebuildGraph();
+
+// Bounded entity-graph slice for visualization (highest-degree entities and their
+// relationships). nodeLimit default 200, max 1000; pass topicId to restrict to one theme.
+const subgraph = await kb.exploreGraph({ nodeLimit: 100 });
 ```
 
+Gotchas:
+- Entity extraction is triggered by ingestion but runs asynchronously off the request path: `upsertContexts()` resolving does NOT mean the graph is ready — poll `getGraphStatus()` until `contextsIndexed === contextsTotal` before relying on graph retrieval for just-ingested documents. Poll with a timeout rather than an unbounded `while` loop: that equality can legitimately never hold, because contexts past the graph chunk cap (next bullet) are never stamped, and a pod restart mid-extraction leaves the remaining contexts unstamped until the debounced auto-build sweep re-extracts them. Treat a shortfall that stops moving as one of those cases, not as work still in flight — `graphIndexingSkippedContextIds` from the upsert identifies the cap case. No rebuild is needed for extraction; what lags further is the concept layer (themes/facets read by `queryGraph`), rebuilt after a quiet window (default 5 min, `autoBuildDebounceMs`) or a manual `rebuildGraph()`. Only one rebuild runs per KB at a time (`JOB_ALREADY_EXISTS`).
+- Per-KB graph chunk cap (a deployment-level limit whose value can change — detect it via the signals, don't design around a fixed number): contexts beyond it stay fully vector/keyword-searchable but are not graph-indexed. Upsert results flag them — the batch `upsertContexts()` returns `graphIndexingSkippedContextIds`, only the singular `upsertContext()` sets the `graphIndexingSkipped` boolean — and `getGraphStatus()` shows `contextsIndexed < contextsTotal`.
+- Only facet nodeIds and document contextIds are stable handles. Theme and entity ids churn on every rebuild — resolve names each time instead of persisting ids.
+- Agents connected to a graph-enabled KB pick it up automatically: `'graph'` becomes the search tool's default mode, the tool description carries a compact graph overview, and the agent gets a `queryKnowledgeGraph` tool backed by the ops above (agent status broadcast: `'Querying Knowledge Base Graph'`). Exception: an active app/per-KB metadata visibility filter suppresses the graph navigation surface (overview block, `underConcept`, the `queryKnowledgeGraph` tool) so out-of-scope concepts/entities cannot leak; graph search mode stays available, filter-scoped.
+
+### Bulk Ingestion
+
+A durable, asynchronous lane for high-volume ingestion that runs contexts through provider batch APIs
+instead of inline. Unlike `upsertContexts`, `bulkUpsertContexts` returns as soon as the request is
+**staged** and never awaits completion.
+
+```typescript
+// 1. Stage contexts (files passed positionally for `type: 'file'` contexts)
+const { jobId, contextIds, duplicates } = await kb.bulkUpsertContexts(contexts, files);
+// contextIds is index-aligned with `contexts`. A context rejected as a content duplicate - the KB
+// already holds identical content, or an earlier context in this same call did - still occupies its
+// slot, so cross-reference `duplicates` by contextId to see what was actually staged.
+
+// 2a. Watch it
+kb.observeBulkIngestionJob(jobId).subscribe(s => console.log(s.state, s.counts, s.files));
+
+// 2b. …or poll it
+const status = await kb.getBulkIngestionJob(jobId);
+// { state, counts, providerBatchIds, files }
+
+// Cancel: already-finalized contexts are kept; the job goes to `cancelled` once in-flight work drains
+await kb.cancelBulkIngestionJob(jobId);
+```
+
+**Large file sets — upload straight to storage.** The multipart path caps at **50 files, 100 MB per
+file, and 256 MB of request body** (the body is buffered in memory server-side), so a single 150 MB
+PDF is rejected there no matter how few files accompany it. Past any of the three, mint presigned
+URLs and reference `stagedObjectKey` instead: core never holds the bytes and none of the multipart
+caps apply. Two staging limits still bound every call whatever path the files arrived by: **10,000
+contexts** and **256 MB of extracted content** — extracted, so base64 image payloads (~1.33x the raw
+image bytes) count and a body that passed the multipart check can still be rejected during staging.
+Split large corpora across jobs, which is what the CLI's `--batchSize` of 200 does:
+
+```typescript
+const { uploads } = await kb.createBulkUploadUrls(fileNames);  // max 500 names per call
+for (const u of uploads) {
+  // requiredHeaders is empty on S3, but Azure Blob rejects the PUT with 400 MissingRequiredHeader without it
+  await fetch(u.uploadUrl, { method: 'PUT', body: bytes, headers: u.requiredHeaders });
+}
+await kb.bulkUpsertContexts(uploads.map(u => ({ type: 'file', stagedObjectKey: u.stagedObjectKey, /* ... */ })));
+```
+
+**`observeBulkIngestionJob` semantics:**
+- Completes on a terminal state (`completed`, `failed`, `cancelled`). A terminal `failed`/`cancelled`
+  arrives as a **normal emitted value** — the observable only errors on transport failure.
+- Cold: each subscription registers its own server-side push. Share it (rxjs `share()`) for multiple
+  consumers.
+- Re-subscribes automatically if the client connection id changes mid-subscription.
+- If the app or KB is deleted mid-flight the job row is purged without a terminal push, so the
+  observable never completes — bound it (rxjs `timeout()`) when deletion is possible.
+
+The CLI wraps this whole flow: `squid kb-upload --dir ./docs --knowledgeBase my-kb` (see
+[backend.md](backend.md#cli-commands)).
+
+### Spreadsheet Understanding
+
+Spreadsheet files (`.csv`, `.tsv`, `.xlsx`, `.xlsm`, `.xls`, `.xlsb`) uploaded as file context take a dedicated ingestion lane: instead of chunking raw cell text, Squid extracts the workbook structure (sheets, headers, hidden sheets; charts and pivot tables where the format exposes them — absent for CSV/TSV and `.xls`, pivots also absent for `.xlsb`) and embeds a generated whole-workbook summary, so search results describe what a workbook contains.
+
+When a connected knowledge base holds spreadsheet contexts, the agent automatically gets a `querySpreadsheetsWithAi` tool that runs Python in a sandbox against the actual uploaded files — for exact values (counts, sums, lookups, filtering, sorting), joins/comparisons across several workbooks in one call, and structure/provenance questions (which sheets feed live calculations, formulas vs hardcoded cells; formula/dependency inspection is fullest for `.xlsx`/`.xlsm`, partial for `.xls`, values-only for `.xlsb`, absent for CSV/TSV). No configuration needed, but the lane and the tool depend on the retained original file: with `discardOriginalFile: true` the spreadsheet ingests as plain extracted text and gets no query tool.
+
+Spreadsheets attached to a chat via `fileUrls` similarly get a per-file Python query tool. Detection is by file extension from `fileName` (or the URL path when `fileName` is absent; query strings are stripped, so a signed URL ending in `.xlsx?sig=...` is detected) — set `fileName` only when the URL path itself lacks the extension, e.g. opaque download routes.
+
 ## AI Files
 
 Manage files stored with AI providers (OpenAI, etc.) for use with agents.
@@ -553,7 +894,7 @@ const settings = await aiClient.getApplicationAiSettings();
 
 // Set application AI settings
 await aiClient.setApplicationAiSettings({
-  defaultModel: 'gpt-5-mini',
+  defaultModel: 'gpt-5.4-mini',
   // ... other settings
 });
 
@@ -562,8 +903,20 @@ await aiClient.setAiProviderApiKeySecret(
   'openai', // providerType
   'OPENAI_API_KEY' // secret key name
 );
+
+// List the chat models available to this application (Squid vendor models + custom integration models)
+const models = await aiClient.listChatModels();
+// Deprecated models (those carrying `replacedBy`) are excluded by default:
+const withDeprecated = await aiClient.listChatModels({ includeDeprecated: true });
+
+// List the AI functions the application exposes
+const functions = await aiClient.listFunctions();
 ```
 
+**Prefer `listChatModels()` over hardcoding a model name** — it reflects what the app can actually
+use, including custom `openai_compatible`/Bedrock/Vertex integration models, and marks deprecated
+models via `replacedBy`.
+
 ## Backend Decorators
 
 ### @aiFunction
@@ -619,6 +972,36 @@ async bookHotel(args: BookingArgs): Promise<string> {
 
 For `@secureAiAgent` and `@secureAiQuery`, see [security.md](security.md#ai-security).
 
+## Source-Code Analysis
+
+An agent can answer questions about real repositories. Enable code analysis on a `github` or
+`bitbucket` integration; the agent then gets an `analyzeCode` tool that clones the selected
+repositories into an isolated workspace and runs a CLI coding agent over them.
+
+```typescript
+// 1. Discover the repositories an integration can reach (admin client - requires an API key)
+const integrations = squid.admin().integrations();
+const { repositories } = await integrations.discoverSourceRepositories('my-github');
+// repositories: { provider, providerRepositoryId, fullName, cloneUrl, webUrl, defaultBranch }[]
+
+// Or, before the integration is saved:
+const draft = await integrations.discoverSourceRepositoriesFromDraft(integrationInfo);
+
+// 2. Select repositories on the integration and configure the agent's analysis options
+//    (AiAgentSourceCodeIntegrationOptions):
+//    codeAnalysisEnabled, analyzerModel, analyzerModelId, analyzerReasoningEffort, analyzerInstructions
+```
+
+**Constants** (exported from both `@squidcloud/client` and `@squidcloud/backend`):
+- `SOURCE_CODE_ANALYZE_FUNCTION_ID` = `'analyzeCode'` — the AI function id
+- `SOURCE_CODE_ANALYZER_MODELS` = `['claude-code', 'codex']` — the CLI providers
+- `SOURCE_CONTROL_PROVIDERS` / `SOURCE_CODE_INTEGRATION_TYPES` = `['github', 'bitbucket']`
+- `SOURCE_CODE_MAX_REPOSITORIES` = 20
+- `SOURCE_CODE_MAX_SUPPLEMENTAL_INSTRUCTIONS_LENGTH` = 20,000 characters per instruction field
+
+Selecting repositories and enabling analysis is usually done in the Console — the SDK path exists for
+automation.
+
 ## MCP (Model Context Protocol)
 
 Squid supports MCP for extending agent capabilities.
@@ -766,7 +1149,7 @@ configureAiFunctions(request: AiFunctionsConfiguratorRequest): AiFunctionsConfig
 ## Best Practices
 
 1. **NEVER invoke LLMs directly** - Do NOT import `openai`, `@anthropic-ai/sdk`, or call LLM APIs directly. ALWAYS use Squid AI Agents via `squid.ai().agent()`. Squid agents provide built-in security, memory, streaming, function calling, guardrails, and model management. If you need an LLM call, create/use an AI agent.
-2. **Use memoryOptions for AI conversations** - Not deprecated chatId
+2. **Use memoryOptions for AI conversations** - `memoryOptions.memoryId` names the conversation, `memoryOptions.memoryMode` controls history
 3. **Agent IDs are permanent** - Plan naming carefully, cannot be changed after creation
 4. **Memory is enabled by default** - Set `memoryMode: 'none'` to disable conversation history
 5. **Streaming behavior differs with connected resources** - No resources: streams token-by-token; Has resources: emits once with complete response

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

@@ -13,6 +13,15 @@ All API endpoints require an API key. Include it in the request headers:
 Authorization: Bearer YOUR_API_KEY
 ```
 
+Two security schemes exist:
+
+| Scheme | Header | Scope |
+|---|---|---|
+| `apiKeyAuth` | `x-app-api-key` | The application API key. Accepted everywhere. |
+| `agentApiKeyAuth` | `x-squid-agent-api-key` | An **agent-scoped** key, accepted by the agent `ask` endpoints and by an agent's MCP endpoint when `requireApiKey` is set. |
+
+Get an agent key with `squid.ai().agent(id).getApiKey()` / `regenerateApiKey()`.
+
 ## API Categories
 
 ### [Agent API](https://docs.getsquid.ai/reference-docs/api/#tag/Agent)
@@ -26,12 +35,27 @@ Manage AI agents. SDK: [ai.md](ai.md)
 - `POST /agent/updateGuardrails` - Configure guardrails
 - `POST /agent/updateCustomGuardrails` - Set custom guardrails
 - `POST /agent/deleteCustomGuardrails` - Remove custom guardrails
+- `POST /agent/setAgentOptionInPath` - Set any agent option by path; how the SDK's `updatePii()` writes the `pii` policy (no dedicated PII endpoint)
 - `POST /agent/ask` - Send prompt, get response
 - `POST /agent/askWithAnnotations` - Get response with annotations
+- `GET /agent/listAgents` - List the application's agents
 - `GET /agent/revisions/{agentId}` - List revisions
 - `POST /agent/restoreRevision` - Restore revision
 - `POST /agent/deleteRevision` - Delete revision
 
+The `ask` / `askWithAnnotations` endpoints accept `agentApiKeyAuth` in addition to `apiKeyAuth`.
+
+Exposing an agent as an MCP server (`updateMcpServer()`) and generating its MCP descriptions
+(`generateMcpDescriptions()`) are SDK-only — they are not part of the published REST surface.
+
+### AiFunction API
+List the AI functions the application exposes. SDK: [ai.md](ai.md)
+- `GET /ai/function/listFunctions` - List AI functions
+
+### AiSettings API
+Application-level AI settings. SDK: [ai.md](ai.md)
+- `GET /ai/settings/listChatModels?includeDeprecated=false` - Chat models available to the app (Squid vendor models + custom integration models)
+
 ### [AI Audio API](https://docs.getsquid.ai/reference-docs/api/#tag/AI-Audio)
 Transcribe audio, text-to-speech. SDK: [ai.md](ai.md)
 - `POST /audio/transcribe` - Transcribe audio to text
@@ -51,7 +75,17 @@ Manage knowledge bases for RAG. SDK: [ai.md](ai.md)
 - `POST /knowledge-base/deleteContexts` - Delete contexts
 - `GET /knowledge-base/getContext/{knowledgeBaseId}/{contextId}` - Get context
 - `GET /knowledge-base/listContexts/{knowledgeBaseId}` - List contexts
-- `POST /knowledge-base/search` - Semantic search
+- `GET /knowledge-base/listContextsPage/{knowledgeBaseId}` - List a page of contexts (offset/limit/search)
+- `GET /knowledge-base/listKnowledgeBases` - List the application's knowledge bases
+- `POST /knowledge-base/search` - Search (vector/hybrid/keyword/graph via `searchMode`; graph fields in the response when requested)
+- `POST /knowledge-base/queryGraph` - Query graph structure (overview, resolve, describe, subtree, docsUnder, conceptsOf, neighborhood, pathBetween, globalSummary)
+- `GET /knowledge-base/getGraphStatus/{knowledgeBaseId}` - Graph build status, coverage, and LLM cost
+- `POST /knowledge-base/rebuildGraph` - Enqueue a graph rebuild (`structural` or `full`)
+- `POST /knowledge-base/exploreGraph` - Bounded entity-graph slice for visualization
+
+Literal scan (`kb.grep()`) and bulk ingestion (`kb.bulkUpsertContexts()` and friends) are SDK-only —
+they are not part of the published REST surface. For bulk ingestion from a machine, use the
+`squid kb-upload` CLI command.
 
 ### [Matchmaking API](https://docs.getsquid.ai/reference-docs/api/#tag/Matchmaking) *(deprecated)*
 Use `knowledgeBase().searchContextsWith*()` instead.
@@ -85,3 +119,14 @@ Create PDFs, extract data from documents. SDK: [client.md](client.md)
 | Knowledge Bases | `squid.ai().knowledgeBase()` | KnowledgeBase API |
 | Web Utilities | `squid.web()` | Web Utilities API |
 | Extraction | `squid.extraction()` | Extraction Utilities API |
+| Chat models / AI functions | `squid.ai().listChatModels()` / `listFunctions()` | AiSettings API / AiFunction API |
+| Events | `squid.events().emit()` | SDK only |
+| LangGraph | `squid.langGraph(id)` | SDK only |
+| KB literal scan, bulk ingestion | `kb.grep()`, `kb.bulkUpsertContexts()` | SDK only (bulk also via `squid kb-upload`) |
+
+## Chat Options: Naming a Conversation
+
+The agent endpoints take conversation identity and history control under `memoryOptions`:
+`memoryOptions.memoryId` names the conversation, and `memoryOptions.memoryMode`
+(`'none' | 'read-only' | 'read-write'`) controls whether history is read and written. An unrecognized
+option key is rejected with a **400** naming the option that carries it.

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.4-mini"
   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,7 +76,7 @@ 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) |
+| **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 DALL-E | [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) |
@@ -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

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/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.4-mini',
     instructions: 'You are a support agent that can search tickets and send messages.'
   }
 });

package/package.json

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