@squidcloud/cli 1.0.489 → 1.0.490

package/dist/index.js

@@ -32183,7 +32183,7 @@ __webpack_unused_export__ = isIntegrationModelSpec;
 /**
  * @category AI
  */
-__webpack_unused_export__ = ['cohere', 'none'];
+__webpack_unused_export__ = ['cohere', 'voyage', 'none'];
 /** List of available AI provider types. See AiProviderType. */
 exports.AI_PROVIDER_TYPES = [
     'anthropic',
@@ -32245,6 +32245,7 @@ exports.Kq = ['grok-4.6', 'grok-4-1-fast-reasoning', 'grok-4-1-fast-non-reasonin
  */
 exports.xV = [
     'claude-fable-5',
+    'claude-fable-5-1',
     'claude-haiku-4-5-20251001',
     'claude-opus-5',
     'claude-sonnet-5',
@@ -32270,7 +32271,7 @@ exports.lZ = ['text-embedding-3-small'];
 /**
  * @category AI
  */
-exports.Pq = ['voyage-3-large'];
+exports.Pq = ['voyage-3-large', 'voyage-4-large', 'voyage-4'];
 /**
  * @category AI
  */
@@ -32392,6 +32393,7 @@ exports.CONNECTOR_IDS = [
     'cotomi',
     'essentials',
     'freshdesk',
+    'generic_site_ingester',
     'github',
     'google_calendar',
     'google_drive',
@@ -32422,6 +32424,7 @@ var __webpack_unused_export__;
 
 __webpack_unused_export__ = ({ value: true });
 exports.EL = exports.y4 = exports.q7 = exports.lO = __webpack_unused_export__ = __webpack_unused_export__ = __webpack_unused_export__ = __webpack_unused_export__ = __webpack_unused_export__ = __webpack_unused_export__ = exports.INTEGRATION_TYPES = __webpack_unused_export__ = void 0;
+__webpack_unused_export__ = isIntegrationDisabled;
 __webpack_unused_export__ = isBuiltInIntegrationId;
 /** @internal */
 __webpack_unused_export__ = 'ai_agents';
@@ -32459,11 +32462,13 @@ exports.INTEGRATION_TYPES = [
     'descope',
     'documentdb',
     'azure-entra-external-id',
+    'azure-entra-id',
     'dynamodb',
     'elasticsearch',
     'firebase_auth',
     'firestore',
     'gcs',
+    'generic_site_ingester',
     'github',
     'google_calendar',
     'google_docs',
@@ -32544,6 +32549,7 @@ __webpack_unused_export__ = [
     'descope',
     'firebase_auth',
     'azure-entra-external-id',
+    'azure-entra-id',
 ];
 /**
  * Auth integration types that can OAuth-protect an MCP server (see `McpOAuthOptions` and
@@ -32570,6 +32576,10 @@ exports.q7 = 'built_in_queue';
  * @category
  */
 exports.y4 = 'built_in_storage';
+/** Returns true when the integration is explicitly disabled. An absent or null `enabled` means enabled. */
+function isIntegrationDisabled(integration) {
+    return integration.enabled === false;
+}
 /** Integration IDs used for built-in integrations by Squid. */
 exports.EL = [
     exports.lO,
@@ -33061,13 +33071,15 @@ exports.sQ = void 0;
 __webpack_unused_export__ = isKotlinPath;
 __webpack_unused_export__ = getEnvironmentPrefix;
 exports.getApplicationUrl = getApplicationUrl;
+__webpack_unused_export__ = getQueryKotlinServiceUrl;
 exports.sQ = [
     'application',
-    'auth',
     'mutation',
-    'native-query',
     'query',
     // Note: every `/ws/*` WebSocket path is served by the TypeScript core (port 8000), never Kotlin.
+    // Note: `native-query` is absent on purpose — the TypeScript core answers it and forwards the
+    // integration types it has no implementation for to Kotlin itself, via
+    // {@link getQueryKotlinServiceUrl}.
 ];
 /**
  * Returns true if the given path is served by Kotlin core in local dev (port 8001). All `/ws/*`
@@ -33113,6 +33125,26 @@ function getApplicationUrl(environmentPrefix, appId, path, appIdPlaceholder, env
     const cleanPath = path.replace(/^\/+/, '');
     return cleanPath ? `${origin}/${cleanPath}` : origin;
 }
+/**
+ * Returns the URL of [path] on the `core-query-kotlin` Service, addressed from inside the cluster.
+ *
+ * Naming the Service rather than building the public URL with {@link getApplicationUrl} keeps a
+ * purely intra-cluster call off the external load balancer, which is what the Kotlin core's own
+ * `getApplicationUrlInternal` already does for the hop in the other direction; and it makes the call
+ * independent of where ingress sends [path], so moving that route cannot turn a forward into a
+ * request back to this core.
+ *
+ * The Service is shared and not per-app, so the application is identified by the
+ * `SquidHeaders.APP_ID` header rather than by the hostname. Local development has no cluster DNS and
+ * keeps the per-app host on Kotlin's port.
+ */
+function getQueryKotlinServiceUrl(environmentPrefix, appId, path) {
+    if (isLocal(environmentPrefix)) {
+        return getApplicationUrl(environmentPrefix, appId, path, undefined, undefined, true);
+    }
+    const cleanPath = path.replace(/^\/+/, '');
+    return `http://core-query-kotlin.default.svc.cluster.local:8001/${cleanPath}`;
+}
 function isLocal(regionPrefix) {
     return /^local/.test(regionPrefix);
 }
@@ -34467,6 +34499,20 @@ const SIGINT_STAGING_WAIT_MILLIS = 10 * time_units_1.MILLIS_PER_SECOND;
 const DEFAULT_TIMEOUT_MINUTES = 120;
 /** Interval between `bulk/getJob` polls while waiting for a job to reach a terminal state. */
 const POLL_INTERVAL_MILLIS = 10 * time_units_1.MILLIS_PER_SECOND;
+/**
+ * How old the last successful poll may be for the timeout classification to trust it. A status older
+ * than this (every recent poll failed) says nothing about the job NOW, so the timeout falls back to the
+ * conservative failure exit instead of waving a stale "still draining" snapshot through.
+ */
+const STALE_STATUS_TOLERANCE_MILLIS = 3 * POLL_INTERVAL_MILLIS;
+/**
+ * How recently a poll must have observed an ACTIVE provider batch for a timeout to defer when NO work
+ * is queued: the no-pending grace for the tick-long gap between one batch's reconciliation and the
+ * next stage's submission. With `requestsPending > 0` behind an observed batch the deferral holds
+ * regardless of this window (queued work is stalled-but-alive under cluster load); a job past this
+ * window with nothing pending is wedged and takes the failure exit.
+ */
+const ACTIVE_BATCH_RECENCY_MILLIS = 5 * time_units_1.MILLIS_PER_MINUTE;
 /** Extensions ingested by default when `--extensions` is not provided. */
 const DEFAULT_EXTENSIONS = ['pdf', 'docx', 'txt', 'md', 'html', 'csv', 'xlsx', 'xls', 'xlsm', 'xlsb', 'pptx'];
 /** Job states that end a bulk-ingestion job's lifecycle (`BulkIngestionJobState` in core). */
@@ -34477,6 +34523,7 @@ const UNKNOWN_JOB_STATUS = {
     state: 'unknown',
     counts: { files: 0, finalized: 0, failed: 0, requestsPending: 0, requestsSubmitted: 0 },
     providerBatchIds: [],
+    activeProviderBatchCount: 0,
     files: [],
 };
 /**
@@ -34745,7 +34792,7 @@ onStagingStarted) {
         console.log(`${batchLabel}: ${duplicates.length} file(s) skipped as content this knowledge base already holds.`);
     }
     activeJobIds.add(jobId);
-    const { finalStatus, timedOut } = await waitForJobCompletion(client, jobId, batchLabel, timeoutMillis, isInterrupted);
+    const { finalStatus, timedOut, statusStale, lastActiveBatchAtMillis } = await waitForJobCompletion(client, jobId, batchLabel, timeoutMillis, isInterrupted);
     activeJobIds.delete(jobId);
     // A duplicate found by the deferred extraction pass (a presigned object's bytes are first hashed
     // there) reports as a failed file with `errorCode: 'DUPLICATE_CONTENT'` — the same skip a
@@ -34764,6 +34811,21 @@ onStagingStarted) {
         duplicates: [...duplicates, ...deferredDuplicates],
         finalStatus,
         timedOut,
+        // Only a FRESH status may waive the timeout, and only on OBSERVED batch activity: an active batch
+        // on the final poll; one seen within the recency window; or one seen at ANY point of this wait
+        // while queued work remains (`requestsPending > 0`) — inter-stage stalls scale with cluster load
+        // (the submit pass visits ~20 running jobs per 15s tick, and an app at its in-flight batch cap
+        // waits for a sibling to drain), so pending-work-behind-an-observed-batch is stalled-but-alive,
+        // not wedged. A job with batches long drained and NOTHING pending takes the failure exit. The
+        // job's `transport` is deliberately NOT consulted: it is 'batch' from staging for every large
+        // job, batches or none, so it cannot say whether anything is draining NOW.
+        deferredInFlight: timedOut &&
+            !statusStale &&
+            finalStatus.state === 'running' &&
+            ((finalStatus.activeProviderBatchCount ?? 0) > 0 ||
+                (lastActiveBatchAtMillis > 0 &&
+                    (Date.now() - lastActiveBatchAtMillis < ACTIVE_BATCH_RECENCY_MILLIS ||
+                        finalStatus.counts.requestsPending > 0))),
     };
 }
 /** Mints presigned upload URLs for a batch, chunking requests to the server's per-call cap. */
@@ -34822,7 +34884,10 @@ async function uploadFile(filePath, upload, stagedObjectKey) {
 async function waitForJobCompletion(client, jobId, batchLabel, timeoutMillis, isInterrupted) {
     const deadline = Date.now() + timeoutMillis;
     let status;
+    let statusAtMillis = 0;
+    let lastActiveBatchAtMillis = 0;
     let isFirstPoll = true;
+    let deferralAnnounced = false;
     while (!isInterrupted() && Date.now() < deadline && (!status || !TERMINAL_JOB_STATES.has(status.state))) {
         if (!isFirstPoll) {
             await sleep(POLL_INTERVAL_MILLIS);
@@ -34830,6 +34895,17 @@ async function waitForJobCompletion(client, jobId, batchLabel, timeoutMillis, is
         isFirstPoll = false;
         try {
             status = await client.getJob(jobId);
+            statusAtMillis = Date.now();
+            if ((status.activeProviderBatchCount ?? 0) > 0) {
+                lastActiveBatchAtMillis = statusAtMillis;
+                if (!deferralAnnounced) {
+                    deferralAnnounced = true;
+                    console.log(`\n${batchLabel}: job ${jobId} submitted a provider batch — half-price processing whose tail can ` +
+                        `reach 24 hours, possibly past --timeoutMinutes. A timed-out wait leaves the job running ` +
+                        `without failing the run; the job finishes server-side, and re-runs are idempotent ` +
+                        `(already-staged content skips as duplicate).`);
+                }
+            }
             printProgress(batchLabel, jobId, status);
         }
         catch (error) {
@@ -34839,13 +34915,18 @@ async function waitForJobCompletion(client, jobId, batchLabel, timeoutMillis, is
     process.stdout.write('\n');
     if (!status) {
         console.warn(`${batchLabel}: could not retrieve job ${jobId}'s status before the timeout.`);
-        return { finalStatus: UNKNOWN_JOB_STATUS, timedOut: true };
+        return { finalStatus: UNKNOWN_JOB_STATUS, timedOut: true, statusStale: true, lastActiveBatchAtMillis: 0 };
     }
     const timedOut = !TERMINAL_JOB_STATES.has(status.state) && !isInterrupted();
     if (timedOut) {
         console.warn(`${batchLabel}: job ${jobId} did not finish within the timeout; it may still be running server-side.`);
     }
-    return { finalStatus: status, timedOut };
+    return {
+        finalStatus: status,
+        timedOut,
+        statusStale: Date.now() - statusAtMillis > STALE_STATUS_TOLERANCE_MILLIS,
+        lastActiveBatchAtMillis,
+    };
 }
 /** Best-effort cancellation of every job still active when the process is interrupted. */
 async function cancelActiveJobs(client, activeJobIds) {
@@ -34913,6 +34994,17 @@ function printSummary(totalFiles, results) {
     if (totalStagedButFailed > 0) {
         console.log(`Staged but job failed:  ${totalStagedButFailed} (uploaded objects remain; auto-expire in 24h)`);
     }
+    const totalStillDeferred = results.reduce((sum, result) => result.deferredInFlight
+        ? sum +
+            Math.max(0, (result.finalStatus?.counts.files ?? 0) -
+                (result.finalStatus?.counts.finalized ?? 0) -
+                (result.finalStatus?.counts.failed ?? 0))
+        : sum, 0);
+    if (totalStillDeferred > 0) {
+        // Reconciles the summary the same way the duplicates line does: these files are neither finalized
+        // nor failed, and without this line they read as silently missing from a run that exits 0.
+        console.log(`Still processing:       ${totalStillDeferred} (queued or draining server-side; the job finishes there)`);
+    }
     for (const result of results) {
         const label = `batch ${result.batchIndex + 1}/${result.batchCount}`;
         if (result.stagingError) {
@@ -34928,9 +35020,11 @@ function printSummary(totalFiles, results) {
             console.log(`  ${label}: no job created (all uploads failed)`);
             continue;
         }
-        const state = result.timedOut
-            ? `${result.finalStatus?.state ?? 'unknown'} (timed out waiting)`
-            : result.finalStatus?.state;
+        const state = result.deferredInFlight
+            ? 'running — work still queued or draining server-side (batch tail can reach 24h); re-runs are idempotent'
+            : result.timedOut
+                ? `${result.finalStatus?.state ?? 'unknown'} (timed out waiting)`
+                : result.finalStatus?.state;
         // Deferred duplicates are excluded from BOTH the failed count and the per-file failure lines: they
         // are already named on the "skipped" lines below, and a clean idempotent re-run must not read as
         // "0/1 finalized, 1 failed" while exiting 0 — the CLI tells one story about a skip.
@@ -34951,14 +35045,21 @@ function printSummary(totalFiles, results) {
     }
 }
 function hasBatchFailed(result) {
-    if (result.uploadFailures.length > 0 || result.timedOut)
+    if (result.uploadFailures.length > 0)
         return true;
     if (!result.finalStatus)
         return true;
     // Deferred duplicates are skips, not failures: an idempotent re-run over an already-ingested
     // directory must exit 0, exactly as it does when staging rejects the duplicates synchronously.
     const duplicateFailures = result.finalStatus.files.filter(file => file.errorCode === 'DUPLICATE_CONTENT').length;
-    return result.finalStatus.state !== 'completed' || result.finalStatus.counts.failed > duplicateFailures;
+    const nonDuplicateFailed = result.finalStatus.counts.failed - duplicateFailures;
+    // A wait-budget expiry on a still-draining provider batch is not a failure BY ITSELF: the pending
+    // files will finish server-side, and exiting 1 would report success-in-progress as an error to every
+    // unattended corpus load. Files the job has ALREADY failed still fail the run — a deferral must never
+    // hide them behind exit 0. Every other timeout shape fails the run outright.
+    if (result.timedOut)
+        return result.deferredInFlight ? nonDuplicateFailed > 0 : true;
+    return result.finalStatus.state !== 'completed' || nonDuplicateFailed > 0;
 }
 /** Recursively walks `dir`, skipping symlinks and dotfiles/dot-directories, filtered to `extensions`. */
 async function collectFiles(dir, extensions) {
@@ -35554,6 +35655,9 @@ const process_utils_1 = __webpack_require__(8251);
 const report_utils_1 = __webpack_require__(3066);
 const version_check_1 = __webpack_require__(4827);
 const ORG = 'squid-cloud-samples';
+// Audit and fund are extra registry round-trips that tell the user nothing about a project the
+// CLI just generated, and the audit request alone can take minutes.
+const NPM_INSTALL_COMMAND = 'npm install --no-audit --no-fund';
 async function initSample(consoleRegion, isOnPremConsole, dirPath, appId, apiKey, environmentId, squidDeveloperId, region, templateName, verbose = false) {
     (0, global_utils_1.enableDebugLogs)(verbose || (0, global_utils_1.isDebugEnabled)());
     (0, logpipes_1.installConsoleOverrides)(enable_debug_decorator_utils_1.debugLogFilterPipe);
@@ -35602,18 +35706,18 @@ async function initSample(consoleRegion, isOnPremConsole, dirPath, appId, apiKey
     let monorepo = false;
     try {
         await promises_1.default.access(path_1.default.resolve(dirPath, 'package.json'));
-        await (0, shell_runner_1.runInShell)('npm install', verbose, path_1.default.resolve(dirPath));
+        await (0, shell_runner_1.runInShell)(NPM_INSTALL_COMMAND, verbose, path_1.default.resolve(dirPath));
     }
     catch { }
     try {
         await promises_1.default.access(path_1.default.resolve(dirPath, 'backend'));
-        await (0, shell_runner_1.runInShell)('npm install', verbose, path_1.default.resolve(dirPath, 'backend'));
+        await (0, shell_runner_1.runInShell)(NPM_INSTALL_COMMAND, verbose, path_1.default.resolve(dirPath, 'backend'));
         monorepo = true;
     }
     catch { }
     try {
         await promises_1.default.access(path_1.default.resolve(dirPath, 'frontend'));
-        await (0, shell_runner_1.runInShell)('npm install', verbose, path_1.default.resolve(dirPath, 'frontend'));
+        await (0, shell_runner_1.runInShell)(NPM_INSTALL_COMMAND, verbose, path_1.default.resolve(dirPath, 'frontend'));
     }
     catch { }
     const hasEnvars = appId && region && apiKey && environmentId && squidDeveloperId;
@@ -40779,7 +40883,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.489","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.489","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.490","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.490","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

@@ -22,8 +22,8 @@ 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, 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
+- **[console.md](reference/console.md)** → Squid Console, web UI, organizations, applications, AI Studio, knowledge bases, knowledge graph toggle, extraction method dropdown, 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, extraction method, preferredExtractionMethod, legacy_with_llm, mistral_ocr, amazon_textract, azure_document_intelligence, page screenshot, image description, extractImages
 - **[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(), 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

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

@@ -128,7 +128,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-5');
-await myAgent.updateGuardrails(['no-harmful-content']);
+await myAgent.updateGuardrails({ disableProfanity: true, disablePii: true });
 
 // Delete an agent
 await myAgent.delete();
@@ -393,7 +393,11 @@ const chatObs = agent.chat('What is your return policy?', {
   instructions: 'Additional instructions for this request only',
   responseFormat: 'json_object', // or 'text'
   verbosity: 'medium', // 'low' | 'medium' | 'high' (OpenAI only)
-  reasoningEffort: 'high', // 'minimal' | 'low' | 'medium' | 'high' (for reasoning models)
+  reasoningEffort: 'high', // 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'ultra'
+                           // (for reasoning models). On an `openai_compatible` integration the value
+                           // is sent to the endpoint as written, so a level outside this list reaches
+                           // it too — OpenAI's Chat Completions API, for one, serves function tools on
+                           // a gpt-5.6 model only with reasoning off outright (`'none'`).
 
   // Context & RAG
   disableContext: false,
@@ -404,7 +408,13 @@ const chatObs = agent.chat('What is your return policy?', {
   },
 
   // Guardrails & quotas
-  guardrails: ['no-harmful-content', 'no-pii'],
+  guardrails: {
+    disableProfanity: true,
+    offTopicAnswers: true,
+    professionalTone: true,
+    disablePii: true,
+    custom: 'Never reveal internal case numbers'
+  },
   quotas: {
     maxAiCallStackSize: 5
   },
@@ -530,6 +540,12 @@ await kb.upsertContexts([
   { contextId: 'doc-2', text: '...' }
 ], optionalFiles);
 
+// File contexts can pick how the document is extracted — see "Document Extraction Methods" below
+await kb.upsertContexts(
+  [{ contextId: 'report-1', type: 'file', preferredExtractionMethod: 'legacy_with_llm' }],
+  [reportPdfFile]
+);
+
 // Search with prompt
 const results = await kb.searchContextsWithPrompt({
   prompt: 'How do I reset password?',
@@ -784,6 +800,14 @@ await kb.bulkUpsertContexts(uploads.map(u => ({ type: 'file', stagedObjectKey: u
 The CLI wraps this whole flow: `squid kb-upload --dir ./docs --knowledgeBase my-kb` (see
 [backend.md](backend.md#cli-commands)).
 
+### Document Extraction Methods
+
+File contexts (and `squid.extraction()` calls) accept `preferredExtractionMethod: 'mistral_ocr' | 'legacy' | 'legacy_with_llm' | 'amazon_textract' | 'azure_document_intelligence'`. Default: the deployment's `defaultDocExtractionMethod` (usually `mistral_ocr`). The OCR providers (`mistral_ocr`, `amazon_textract`, `azure_document_intelligence`) are available only where the deployment configures them; `legacy` and `legacy_with_llm` run in-process and are always available. The same option applies to `upsertContexts`, `bulkUpsertContexts`, and the extraction client alike.
+
+- `legacy` — reads the PDF's text layer (pdfjs) and extracts embedded images; no external service, but a scanned page yields nothing (there is no text layer to read). Console label: **Basic**.
+- `legacy_with_llm` — the same text extraction, plus a screenshot of each page described by a vision model as a *complement* to the stored page text: figures, charts, layout, handwriting, and scanned regions the text layer cannot carry, without restating the page's prose. Notably, vector-drawn figures/graphs are not embedded images, so `legacy` cannot see them at all; the page screenshot (like provider OCR) is what catches them. Each description lands as its own chunk beside the page's text chunk, with page provenance; a page whose screenshot adds nothing beyond its text stores no extra chunk. Costs one vision call per page, so ingestion of long documents is slower and pricier than `legacy`. Console label: **Basic + page understanding**.
+- `extractImages` (default `true` for file contexts) gates image handling for every method, including the `legacy_with_llm` page screenshots; `imageMinSizePixels` (default 100) filters small embedded images; `imageExtractionModel` overrides the model used for image/screenshot descriptions.
+
 ### 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.

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

@@ -389,7 +389,12 @@ const extractedData = await extraction.extractDataFromDocumentFile(
         { name: 'total', type: 'number', description: 'Total amount' },
         { name: 'date', type: 'date', description: 'Invoice date' }
       ]
-    }
+    },
+    // 'mistral_ocr' | 'legacy' | 'legacy_with_llm' | 'amazon_textract' | 'azure_document_intelligence'.
+    // Default: the deployment's configured method (usually 'mistral_ocr'). Semantics: see the
+    // "Document Extraction Methods" section in ai.md.
+    preferredExtractionMethod: 'legacy_with_llm',
+    extractImages: true // default true; also gates legacy_with_llm's page screenshots
   }
 );
 

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

@@ -73,6 +73,7 @@ The AI Studio provides visual tools for building and testing AI agents:
 
 ### Managing Content
 - Upload documents (PDF, text, markdown, etc.)
+- Pick the **Extraction Method** in the add-knowledge dialog: **Basic** (`legacy`, in-process text extraction) and **Basic + page understanding** (`legacy_with_llm`, adds an LLM description of each page's screenshot) are always offered; OCR providers (**Mistral OCR**, **Amazon Textract**, **Azure AI Document Intelligence**) appear when the deployment configures them, with the deployment default marked **(Default)**
 - View and edit contexts
 - Search and preview indexed content
 - Monitor indexing status

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

@@ -194,9 +194,11 @@ const content = await squid.web().getUrlContent('https://example.com');
 // Short URLs
 const shortUrl = await squid.web().createShortUrl('https://long-url.com/path');
 
-// Data Extraction from documents
-const data = await squid.extraction().extractDataFromDocumentUrl(url, schema);
-const data = await squid.extraction().extractDataFromDocumentFile(file, schema);
+// Data Extraction from documents. Optional preferredExtractionMethod:
+// 'mistral_ocr' | 'legacy' | 'legacy_with_llm' | 'amazon_textract' | 'azure_document_intelligence'
+// (see the squid-development skill's ai.md "Document Extraction Methods")
+const data = await squid.extraction().extractDataFromDocumentUrl(url);
+const data = await squid.extraction().extractDataFromDocumentFile(file, { preferredExtractionMethod: 'legacy_with_llm' });
 
 // PDF Creation
 const pdf = await squid.extraction().createPdf(htmlContent);

package/package.json

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