@squidcloud/cli 1.0.488 → 1.0.490

package/dist/index.js

@@ -32174,7 +32174,8 @@ module.exports = function toBuffer(data, encoding) {
 var __webpack_unused_export__;
 
 __webpack_unused_export__ = ({ value: true });
-__webpack_unused_export__ = __webpack_unused_export__ = __webpack_unused_export__ = __webpack_unused_export__ = __webpack_unused_export__ = exports.h3 = exports.VF = __webpack_unused_export__ = exports.F3 = exports.eS = exports.Eh = exports.dH = exports.mz = exports.Pq = exports.lZ = exports.I1 = exports.xV = exports.Kq = exports.oL = exports.hp = exports.AI_PROVIDER_TYPES = __webpack_unused_export__ = void 0;
+__webpack_unused_export__ = __webpack_unused_export__ = __webpack_unused_export__ = __webpack_unused_export__ = __webpack_unused_export__ = exports.h3 = exports.VF = __webpack_unused_export__ = exports.F3 = exports.eS = exports.Eh = exports.dH = exports.mz = exports.Pq = exports.lZ = exports.I1 = exports.xV = exports.Kq = exports.oL = exports.hp = exports.MD = exports.AI_PROVIDER_TYPES = __webpack_unused_export__ = void 0;
+__webpack_unused_export__ = isFileCapableProviderType;
 __webpack_unused_export__ = isVendorAiChatModelName;
 __webpack_unused_export__ = isAiEmbeddingsModelName;
 __webpack_unused_export__ = isIntegrationEmbeddingModelSpec;
@@ -32182,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',
@@ -32204,35 +32205,47 @@ exports.AI_PROVIDER_TYPES = [
     'vertex',
     'external', // This is a technicality, referring to user-defined providers.
 ];
+/**
+ * The AI providers that support file upload operations, and so are the only ones that resolve a
+ * pre-uploaded file id. Declared as the list, with the type derived from it, so the two cannot drift:
+ * a provider added to one is added to both.
+ */
+exports.MD = [
+    'openai',
+    'gemini',
+    'anthropic',
+    'grok',
+];
+/**
+ * True when the provider resolves pre-uploaded file ids. Every other provider — the integration-backed
+ * and user-defined ones, which report no vendor identity of their own — ignores `fileIds` outright, so
+ * for them the ids are inert rather than wrong.
+ */
+function isFileCapableProviderType(type) {
+    return exports.MD.includes(type);
+}
 /**
  * Public OpenAI chat model names (active models only).
  * @category AI
  */
-exports.hp = [
-    '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',
-];
+exports.hp = ['gpt-5.5-pro', 'gpt-5.6-sol', 'gpt-5.6-terra', 'gpt-5.6-luna'];
 /**
  * Public Gemini chat model names (active models only).
  * @category AI
  */
-exports.oL = ['gemini-3.1-pro', 'gemini-3.6-flash', 'gemini-3.5-flash-lite'];
+exports.oL = ['gemini-3.1-pro', 'gemini-3.7-flash', 'gemini-3.5-flash-lite'];
 /**
  * Public Grok chat model names (active models only).
  * @category AI
  */
-exports.Kq = ['grok-4.5', 'grok-4-1-fast-reasoning', 'grok-4-1-fast-non-reasoning'];
+exports.Kq = ['grok-4.6', 'grok-4-1-fast-reasoning', 'grok-4-1-fast-non-reasoning'];
 /**
  * Public Anthropic chat model names (active models only).
  * @category AI
  */
 exports.xV = [
     'claude-fable-5',
+    'claude-fable-5-1',
     'claude-haiku-4-5-20251001',
     'claude-opus-5',
     'claude-sonnet-5',
@@ -32258,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
  */
@@ -32380,6 +32393,7 @@ exports.CONNECTOR_IDS = [
     'cotomi',
     'essentials',
     'freshdesk',
+    'generic_site_ingester',
     'github',
     'google_calendar',
     'google_drive',
@@ -32410,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';
@@ -32447,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',
@@ -32532,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
@@ -32558,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,
@@ -33049,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/*`
@@ -33101,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);
 }
@@ -34455,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). */
@@ -34465,6 +34523,7 @@ const UNKNOWN_JOB_STATUS = {
     state: 'unknown',
     counts: { files: 0, finalized: 0, failed: 0, requestsPending: 0, requestsSubmitted: 0 },
     providerBatchIds: [],
+    activeProviderBatchCount: 0,
     files: [],
 };
 /**
@@ -34733,9 +34792,41 @@ 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);
-    return { batchIndex, batchCount, jobId, uploadFailures, duplicates, finalStatus, timedOut };
+    // 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
+    // staging-time rejection is, so fold it into the duplicates the summary reconciles by name.
+    const deferredDuplicates = (finalStatus?.files ?? [])
+        .filter(file => file.errorCode === 'DUPLICATE_CONTENT')
+        .map(file => file.title);
+    if (deferredDuplicates.length > 0) {
+        console.log(`${batchLabel}: ${deferredDuplicates.length} file(s) skipped as content this knowledge base already holds.`);
+    }
+    return {
+        batchIndex,
+        batchCount,
+        jobId,
+        uploadFailures,
+        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. */
 async function createUploadUrlsForBatch(client, fileNames) {
@@ -34793,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);
@@ -34801,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) {
@@ -34810,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) {
@@ -34832,7 +34942,13 @@ async function cancelActiveJobs(client, activeJobIds) {
 }
 function printProgress(batchLabel, jobId, status) {
     const { counts, state } = status;
-    const line = `${batchLabel} job ${jobId}: ${counts.finalized}/${counts.files} finalized, ${counts.failed} failed, state=${state}`;
+    // Deferred duplicates sit inside counts.failed but are skips to the caller (see printSummary) — shown
+    // raw, the live line says "1 failed" on a job the summary then reports as 0 failed, 1 skipped.
+    const duplicateSkips = status.files.filter(file => file.errorCode === 'DUPLICATE_CONTENT').length;
+    const failed = Math.max(0, counts.failed - duplicateSkips);
+    const skippedPart = duplicateSkips > 0 ? `, ${duplicateSkips} skipped` : '';
+    const line = `${batchLabel} job ${jobId}: ${counts.finalized}/${counts.files} finalized, ` +
+        `${failed} failed${skippedPart}, state=${state}`;
     process.stdout.write(`\r${line}${' '.repeat(Math.max(0, PROGRESS_LINE_WIDTH - line.length))}`);
 }
 /** Narrows a `FileUploadResult` to one that uploaded successfully (has a `stagedObjectKey`, no `error`). */
@@ -34855,7 +34971,13 @@ async function printDryRun(dir, files, batchSize) {
 }
 function printSummary(totalFiles, results) {
     const totalFinalized = results.reduce((sum, result) => sum + (result.finalStatus?.counts.finalized ?? 0), 0);
-    const totalServerFailed = results.reduce((sum, result) => sum + (result.finalStatus?.counts.failed ?? 0), 0);
+    // Deferred duplicates sit inside counts.failed but are reported on the "Skipped as duplicate" line
+    // (runBatch folds them into `duplicates`), so subtract them here or the two lines double-count.
+    const totalServerFailed = results.reduce((sum, result) => {
+        const failed = result.finalStatus?.counts.failed ?? 0;
+        const duplicateFailures = (result.finalStatus?.files ?? []).filter(file => file.errorCode === 'DUPLICATE_CONTENT').length;
+        return sum + Math.max(0, failed - duplicateFailures);
+    }, 0);
     const totalUploadFailed = results.reduce((sum, result) => sum + result.uploadFailures.length, 0);
     const totalDuplicates = results.reduce((sum, result) => sum + result.duplicates.length, 0);
     const totalStagedButFailed = results.reduce((sum, result) => sum + (result.stagingError ? (result.stagedCount ?? 0) : 0), 0);
@@ -34872,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) {
@@ -34887,12 +35020,20 @@ 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;
-        console.log(`  ${label}: job ${result.jobId} — ${result.finalStatus?.counts.finalized ?? 0}/${result.finalStatus?.counts.files ?? 0} finalized, ${result.finalStatus?.counts.failed ?? 0} failed [${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.
+        const deferredDuplicateCount = result.finalStatus?.files.filter(file => file.errorCode === 'DUPLICATE_CONTENT').length ?? 0;
+        const failedCount = Math.max(0, (result.finalStatus?.counts.failed ?? 0) - deferredDuplicateCount);
+        console.log(`  ${label}: job ${result.jobId} — ${result.finalStatus?.counts.finalized ?? 0}/${result.finalStatus?.counts.files ?? 0} finalized, ${failedCount} failed [${state}]`);
         // Per-file failure reasons, straight from the job-status response (BulkIngestionFileStatus).
-        const failedFiles = result.finalStatus?.files.filter(file => file.status === 'failed') ?? [];
+        const failedFiles = result.finalStatus?.files.filter(file => file.status === 'failed' && file.errorCode !== 'DUPLICATE_CONTENT') ??
+            [];
         for (const failedFile of failedFiles) {
             console.log(`    - ${failedFile.title}: ${failedFile.errorMessage ?? 'unknown error'}`);
         }
@@ -34904,11 +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;
-    return result.finalStatus.state !== 'completed' || result.finalStatus.counts.failed > 0;
+    // 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;
+    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) {
@@ -35504,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);
@@ -35552,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;
@@ -40729,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.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"}}');
+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

@@ -59,10 +59,10 @@ import {
 
 | 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` |
+| OpenAI | `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` |
+| Gemini | `gemini-3.1-pro`, `gemini-3.7-flash`, `gemini-3.5-flash-lite` |
+| Grok | `grok-4.6`, `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
@@ -72,7 +72,7 @@ This list moves. **Don't hardcode a model name from this table into user code**
 **Model Categories:**
 - **Chat Models**: Used for AI Agents, AI Query, etc. (OpenAI, Anthropic, Gemini, Grok)
 - **Embedding Models**: Used for Knowledge Bases (OpenAI, Voyage)
-- **Image Generation Models**: Used for image creation (DALL-E, Stable Diffusion, Flux)
+- **Image Generation Models**: Used for image creation (OpenAI `gpt-image-*`, Stable Diffusion, Flux)
 - **Audio Models**: Transcription (Whisper, GPT-4o) and Text-to-Speech (TTS-1, GPT-4o-mini-tts)
 
 ## AI Agents
@@ -115,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.4-mini', // or 'claude-sonnet-5', 'gemini-3.6-flash' - see Supported Models
+    model: 'gpt-5.6-terra', // or 'claude-sonnet-5', 'gemini-3.7-flash' - see Supported Models
     instructions: 'You are a helpful customer support assistant. Be concise and professional.',
     temperature: 0.7
   }
@@ -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();
@@ -386,14 +386,18 @@ const chatObs = agent.chat('What is your return policy?', {
   connectedKnowledgeBases: [{ knowledgeBaseId: 'kb1', description: 'When to use this KB' }],
 
   // Model & generation
-  model: 'gpt-5.4-mini', // Override agent's default model
+  model: 'gpt-5.6-terra', // Override agent's default model
   temperature: 0.7,
   maxTokens: 4000,
   maxOutputTokens: 2000,
   instructions: 'Additional instructions for this request only',
   responseFormat: 'json_object', // or 'text'
   verbosity: 'medium', // 'low' | 'medium' | 'high' (OpenAI only)
-  reasoningEffort: 'high', // 'minimal' | 'low' | 'medium' | 'high' (for reasoning models)
+  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
   },
@@ -433,7 +443,7 @@ const chatObs = agent.chat('What is your return policy?', {
   useCodeInterpreter: 'llm', // 'none' | 'llm' (OpenAI/Gemini only)
   executionPlanOptions: {
     enabled: true,
-    model: 'gpt-5.4-mini',
+    model: 'gpt-5.6-terra',
     reasoningEffort: 'high',
     allowClarificationQuestions: false
   },
@@ -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.
@@ -818,10 +842,10 @@ REST API: [AI Image API](https://docs.getsquid.ai/reference-docs/api/#tag/AI-Ima
 ### Image Generation
 
 ```typescript
-// Generate image
+// Generate image - `modelName` is required
 const imageUrl = await squid.ai().image().generate(
   'A futuristic city',
-  { size: '1024x1024', quality: 'hd' }
+  { modelName: 'gpt-image-1', size: '1024x1024', quality: 'high' }
 );
 
 // Remove background
@@ -894,7 +918,7 @@ const settings = await aiClient.getApplicationAiSettings();
 
 // Set application AI settings
 await aiClient.setApplicationAiSettings({
-  defaultModel: 'gpt-5.4-mini',
+  defaultModel: 'gpt-5.6-terra',
   // ... other settings
 });
 

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.4-mini"
+  squid-ai-override-model="gpt-5.6-terra"
   squid-ai-temperature="0.7"
   squid-ai-max-tokens="2000"
   squid-ai-agent-chat-options='{

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

@@ -77,7 +77,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, 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) |
+| **Image Generation** | `squid.ai().image()` | Generate images with `gpt-image-*`, Stable Diffusion, or Flux | [ai.md](ai.md) |
 | **Audio** | `squid.ai().audio()` | Transcription and text-to-speech | [ai.md](ai.md) |
 | **PDF/Extraction** | `squid.extraction()` | Create PDFs, extract data from documents | [Extraction section](#extraction) |
 | **Observability** | `squid.observability` | Report and query custom metrics | [Observability section](#observability--metrics) |
@@ -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
@@ -156,7 +157,7 @@ const agent = squid.ai().agent('my-agent');
 await agent.upsert({
   description: 'Customer support agent',
   options: {
-    model: 'gpt-4o',
+    model: 'gpt-5.6-terra',
     instructions: 'You are a helpful support agent...'
   }
 });

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

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

package/dist/resources/claude/skills/squid-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/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.4-mini',
+    model: 'gpt-5.6-terra',
     instructions: 'You are a support agent that can search tickets and send messages.'
   }
 });

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squidcloud/cli",
-  "version": "1.0.488",
+  "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.488",
+    "@squidcloud/local-backend": "^1.0.490",
     "adm-zip": "^0.5.16",
     "copy-webpack-plugin": "^14.0.0",
     "decompress": "^4.2.1",