scalix 1.5.0 → 1.5.1

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to Scalix Coder will be documented in this file.
 
+## [1.5.1] - 2026-08-08
+
+### Added
+- **Scalix Cloud key for BYOK sessions.** The platform tools (deploy, database, storage, …) now run on their own credential pair, independent of inference: `SCALIX_CLOUD_API_KEY` / `SCALIX_CLOUD_BASE_URL` env, a keychain slot and settings row in the VS Code extension, and a wizard step in the CLI. Inference on your own endpoint, deploys still on Scalix — the BYOK key never reaches Scalix and the Scalix key never reaches your endpoint. The IPC engine now registers the cloud tools at startup; the GUI previously had none at all, and models asked to deploy invented SDKs and CLI flags instead.
+- **Guided setup.** Full-page setup panel in the extension (provider presets, key/model/limits, engine and terminal-CLI status with an install button) that auto-opens on first run and lands in chat after save; `/setup` slash command in both surfaces.
+- **The agent knows what is at its disposal.** While a cloud connection is live, every request carries a section listing the registered `scalix_*` tool groups and the platform's ~30s per-call execution ceiling, steering long operations to the async pairs (`scalix_build_create` → poll `scalix_build_status`) instead of one blocking call that the transport would kill.
+- **Scope-aware tool catalog.** The catalog is filtered client-side by the API key's scope families, so the model only sees tools its key can plausibly call; `/cloud status` reports "N of M available to this key" and says when the key's own project binding overrides a configured project id (the platform ignores the header for API keys — the key wins).
+- **Key-shape guidance.** Platform tools need a project-scoped key with the `database:query` scope; setup copy now says so everywhere a key is entered, and the two known rejections map to one-line remedies (400 = org-wide key, 403 = missing database scope) in the wizard, `/cloud status`, headless warnings and the extension banner.
+- `/status` marks the context window as *assumed* when neither the user nor the API supplied a spec for the active model, and points at the `/setup` context-window override — no invented numbers.
+
+### Changed
+- **Scalix product steering is gated on connection state.** Full platform guidance only while Scalix Cloud is connected; a single neutral pointer on the Scalix provider while disconnected; nothing Scalix-specific on pure BYOK sessions. Coder is a generic tool — the pitch arrives with the tools, not before.
+- Cloud tool-call budget cut from 120s to 45s: the platform transport ends a call at ~30–35s, so the extra 75s only ever waited on a dead call.
+- Request timeout raised to 300s to match the platform's own walls (env-overridable via `SCALIX_REQUEST_TIMEOUT_MS`).
+
+### Fixed
+- **Model switching, 24 audited fixes + 3 from dogfooding videos.** `setModel` preserves the failover chain and mutates in place (sub-agents saw stale model lists), and resets the breaker; fresh sends no longer round-robin the chain; BYOK model specs are registered on every switch surface, so no more `max_tokens`-less requests that OpenRouter 400s; the TUI `/model` no longer fires mid-stream via the `/mode` prefix collision and persists chain-preservingly to the global config (project overrides no longer laundered); `/settings` reports live-vs-next-launch truthfully; a `SCALIX_MODEL` override is announced; the IPC engine survives stray rejections — a 429 used to kill the whole session.
+- The system prompt forbids inventing `scalix` packages or CLI flags and explains the `scalix_*` tools, with pinned SDK names (`@scalix-world/sdk` on npm, `scalix-sdk` on PyPI) and exact model ids.
+
+### Fixed (VS Code extension)
+- Scalix keys are verified against `/v1/me` before storing — a rejected key gets a dialog with the reason instead of failing silently later. BYOK keys are never probed.
+- Model QuickPick accepts mouse clicks under Antigravity's event ordering; model/command updates broadcast to every chat surface (the editor tab used to go stale); the shared-config watcher ignores its own writes, so adopting a config no longer reverts a fresh model switch; the settings Models tab was rebuilt — stable refresh, live active badge, auto-reload on provider/endpoint/key change.
+- `vsce` packaging: the extension manifest carries the `repository` field CI packaging requires.
+
 ## [1.5.0] - 2026-08-02
 
 ### Added

package/dist/agent.js

@@ -3,7 +3,7 @@ import { EventEmitter } from 'eventemitter3';
 import { randomUUID } from 'node:crypto';
 import { getToolPermissionWithArgs } from './sandbox.js';
 import { logger } from './logger.js';
-import { DEFAULT_MODELS as FALLBACK_MODELS, DEFAULT_INSTRUCTIONS, DEFAULT_BASE_URL, AGENT_DEFAULTS, TOOL_DEFAULTS, BACKOFF_DEFAULTS, CONTEXT_DEFAULTS, modelSupportsVision, getModelSpec, maxOutputTokensForRequest, hasExplicitModelSpec } from './constants.js';
+import { DEFAULT_MODELS as FALLBACK_MODELS, DEFAULT_INSTRUCTIONS, DEFAULT_BASE_URL, AGENT_DEFAULTS, TOOL_DEFAULTS, BACKOFF_DEFAULTS, CONTEXT_DEFAULTS, SCALIX_PLATFORM_SECTION, SCALIX_CLOUD_RESOURCES_SECTION, SCALIX_NEUTRAL_POINTER, SCALIX_STEERING_ALWAYS_ON, modelSupportsVision, getModelSpec, maxOutputTokensForRequest, hasExplicitModelSpec } from './constants.js';
 import { estimateMessageTokens as estimateTokenCount, estimateTokens } from './token-counter.js';
 import { ContextManager } from './context-manager.js';
 import { zodToJsonSchema } from './tool-helper.js';
@@ -19,7 +19,7 @@ import { extractCodeClaims, checkGrounding, formatGroundingNudge, GROUNDING_DEFA
 import { RETRIEVAL_DEFAULTS } from './context-retriever.js';
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { fetchCloudTools, callCloudTool } from './cloud.js';
+import { fetchCloudTools, callCloudTool, fetchMe, filterCatalogByScopes, buildCloudToolsPromptSection, cloudKeyRemedy } from './cloud.js';
 import { createChatClient, capabilitiesFor } from './providers/index.js';
 /**
  * Marks an error that Agent has already announced through the 'error' event.
@@ -177,6 +177,8 @@ export class Agent extends EventEmitter {
     cloudStatus = { state: 'no-key', toolCount: 0 };
     providerId;
     capabilities;
+    cloudApiKey;
+    cloudBaseUrl;
     streamingToolCallsResolved;
     constructor(config) {
         super();
@@ -189,6 +191,14 @@ export class Agent extends EventEmitter {
             throw new Error(`Provider '${this.providerId}' requires an explicit baseUrl — there is no default third-party endpoint.`);
         }
         this.client = createChatClient(this.providerId, config.baseUrl || DEFAULT_BASE_URL, config.apiKey);
+        // Cloud tools follow their own credential pair. On the Scalix gateway the
+        // inference creds double as the cloud creds; on BYOK `config.baseUrl` is a
+        // third-party host with no /v1/me, so the cloud URL falls back to the
+        // Scalix default rather than inheriting it.
+        this.cloudApiKey = config.cloudApiKey?.trim()
+            || (this.capabilities.platformTools ? config.apiKey : '');
+        this.cloudBaseUrl = config.cloudBaseUrl?.trim()
+            || (this.capabilities.platformTools ? (config.baseUrl || DEFAULT_BASE_URL) : DEFAULT_BASE_URL);
         this.log = logger.child();
         const resolvedModels = Array.isArray(config.model)
             ? (config.model.length > 0 ? config.model : FALLBACK_MODELS)
@@ -268,7 +278,16 @@ export class Agent extends EventEmitter {
             this.retrievalConfig = { ...RETRIEVAL_DEFAULTS, ...config.contextRetrieval };
         }
     }
-    pickModel() {
+    /**
+     * `fresh` — a NEW user turn: always start from the front of the list (the
+     * user's chosen model). The idx+1 bookkeeping below exists so RETRIES
+     * advance to the next model in the chain; without the fresh reset it also
+     * rotated the STARTING model, so with a failover chain configured,
+     * consecutive sends silently alternated models — a switch never "stuck".
+     */
+    pickModel(fresh = false) {
+        if (fresh)
+            this.modelIndex = 0;
         const startIdx = this.modelIndex;
         for (let i = 0; i < this.config.models.length; i++) {
             const idx = (startIdx + i) % this.config.models.length;
@@ -385,12 +404,18 @@ export class Agent extends EventEmitter {
     setPermissionMode(mode) { this.config.permissionMode = mode; }
     getProvider() { return this.providerId; }
     /**
-     * Whether this session's inference endpoint is the Scalix gateway, and so
-     * can answer /v1/me and serve the account's platform-tool catalog. Callers
-     * must check this before probing those endpoints: on BYOK the base URL is a
-     * third-party host that has no such routes.
+     * Whether this session can reach a Scalix gateway that answers /v1/me and
+     * serves the account's platform-tool catalog. True when inference runs on
+     * the gateway, or when BYOK inference is paired with a separate Scalix Cloud
+     * key. False means no endpoint to probe — never probe the BYOK base URL.
      */
-    supportsPlatformTools() { return this.capabilities.platformTools; }
+    supportsPlatformTools() { return this.cloudApiKey.length > 0; }
+    /** The Scalix Cloud endpoint platform tools talk to — the gateway, not the
+     *  inference base URL, which under BYOK is a third-party host. */
+    getCloudBaseUrl() { return this.cloudBaseUrl; }
+    /** The key platform tools authenticate with — equal to the inference key on
+     *  the 'scalix' provider, separate under BYOK, empty if unconfigured. */
+    getCloudApiKey() { return this.cloudApiKey; }
     getThinking() { return this.config.thinkingMode; }
     setThinking(mode) { this.config.thinkingMode = mode; }
     async compact() {
@@ -447,7 +472,11 @@ export class Agent extends EventEmitter {
      * itself started rejecting the oversized request. The untouched 1M default
      * isn't a choice, so it stays out of the way of the guess.
      */
-    syncContextLimit(model = this.config.models[this.modelIndex % this.config.models.length]) {
+    // Default to models[0] — the model a fresh send will use. modelIndex points
+    // one PAST the last pick (retry bookkeeping), so dereferencing it here made
+    // idle-time context reads use the NEXT chain entry's budget, not the
+    // active model's.
+    syncContextLimit(model = this.config.models[0]) {
         const configured = this.configuredContextTokens;
         const userChoseLimit = configured != null
             && configured > 0
@@ -559,8 +588,8 @@ export class Agent extends EventEmitter {
      *  Schema is passed to the model as-is via `parameters` (NOT `inputSchema`,
      *  which transformToolsForApi would run through the Zod converter). */
     makeCloudTool(ct) {
-        const baseUrl = this.client.baseURL;
-        const apiKey = this.config.apiKey;
+        const baseUrl = this.cloudBaseUrl;
+        const apiKey = this.cloudApiKey;
         const projectId = this.cloudProjectId;
         return {
             source: 'scalix-cloud',
@@ -581,26 +610,41 @@ export class Agent extends EventEmitter {
      * (/cloud refresh). On failure the previously registered cloud tools are
      * removed and the agent keeps running with local tools only — the returned
      * status carries the real error for a single honest notice; no retries.
+     *
+     * `identity`: pass a CloudIdentity to scope-filter the catalog without a
+     * second /v1/me round-trip (the TUI already fetched one); pass `null` when
+     * /v1/me was tried and failed so no doomed re-fetch happens; omit entirely
+     * (headless, IPC) and the identity is fetched best-effort here — on any
+     * /v1/me failure the catalog registers unfiltered, exactly as before.
      */
-    async refreshCloudTools() {
-        // Platform tools live on the Scalix gateway (/v1/me, /api/v1/mcp). Never
-        // probe a BYOK third-party endpoint for them.
-        if (!this.capabilities.platformTools) {
-            this.config.tools = this.config.tools.filter((t) => !this.isCloudTool(t));
-            this.cloudStatus = { state: 'no-key', toolCount: 0 };
-            return { ...this.cloudStatus };
-        }
-        if (!this.config.apiKey) {
+    async refreshCloudTools(identity) {
+        // Platform tools live on the Scalix gateway (/v1/me, /api/v1/mcp), which
+        // is `cloudBaseUrl` — never the BYOK inference endpoint. No cloud key
+        // means nothing to fetch: on 'scalix' the user has no key at all, on BYOK
+        // they have not opted into pairing a Scalix Cloud key with their provider.
+        if (!this.cloudApiKey) {
             this.config.tools = this.config.tools.filter((t) => !this.isCloudTool(t));
             this.cloudStatus = { state: 'no-key', toolCount: 0 };
             return { ...this.cloudStatus };
         }
         try {
-            const catalog = await fetchCloudTools(this.client.baseURL, this.config.apiKey, this.cloudProjectId);
+            const catalog = await fetchCloudTools(this.cloudBaseUrl, this.cloudApiKey, this.cloudProjectId);
+            let me = identity;
+            if (me === undefined) {
+                try {
+                    me = await fetchMe(this.cloudBaseUrl, this.cloudApiKey);
+                }
+                catch {
+                    me = null;
+                }
+            }
+            const visible = me
+                ? filterCatalogByScopes(catalog.tools, me.permissions.scopes)
+                : catalog.tools;
             this.config.tools = this.config.tools.filter((t) => !this.isCloudTool(t));
             const localNames = new Set(this.config.tools.map((t) => t.function?.name || t.name).filter(Boolean));
             let registered = 0;
-            for (const ct of catalog.tools) {
+            for (const ct of visible) {
                 if (localNames.has(ct.name)) {
                     this.log.warn('Cloud tool name collides with a local tool — keeping the local tool', { tool: ct.name });
                     continue;
@@ -613,14 +657,26 @@ export class Agent extends EventEmitter {
             this.cloudStatus = {
                 state: 'connected',
                 toolCount: registered,
+                totalCount: catalog.tools.length,
                 platformAvailable: catalog.platformAvailable,
             };
+            // The platform binds MCP calls to the KEY's project; a configured
+            // project id cannot redirect them. Say so instead of silently differing.
+            const keyProject = me?.identity.projectId;
+            if (keyProject && this.cloudProjectId && keyProject !== this.cloudProjectId) {
+                this.cloudStatus.note = `API key is bound to project ${keyProject}; configured project ${this.cloudProjectId} is ignored for platform tools (the key's binding wins).`;
+            }
         }
         catch (err) {
             this.config.tools = this.config.tools.filter((t) => !this.isCloudTool(t));
             if (this.toolSelector)
                 this.toolSelector.index(this.config.tools);
-            this.cloudStatus = { state: 'unavailable', toolCount: 0, error: err?.message || String(err) };
+            this.cloudStatus = {
+                state: 'unavailable',
+                toolCount: 0,
+                error: err?.message || String(err),
+                remedy: cloudKeyRemedy(err),
+            };
             this.log.warn('Scalix Cloud tool catalog unavailable', { error: this.cloudStatus.error });
         }
         return { ...this.cloudStatus };
@@ -638,12 +694,39 @@ export class Agent extends EventEmitter {
         if (!this.config.models.includes(model))
             this.config.models.push(model);
     }
-    setModel(model) { this.config.models = [model]; }
+    setModel(model) {
+        // Mutate IN PLACE, never reassign: setAgentToolConfig captured this array
+        // by reference at construction, so a reassignment left sub-agents on the
+        // pre-switch model list forever. And keep the failover chain — replacing
+        // the whole list with [model] permanently destroyed a configured
+        // multi-model chain; the switched-to model just moves to the front.
+        const rest = this.config.models.filter((m) => m !== model);
+        this.config.models.splice(0, this.config.models.length, model, ...rest);
+        this.modelIndex = 0;
+        // A deliberate switch is a vote of confidence: clear this model's breaker
+        // so the next request actually tries it, and resize the context budget
+        // now instead of at the next lazy resync.
+        this.modelFailures.delete(model);
+        this.syncContextLimit(model);
+    }
     getModels() { return [...this.config.models]; }
+    /** Live-apply a limit. Returns true when the running agent honors the new
+     *  value immediately, false when it only takes effect on the next launch —
+     *  callers used to report "updated" unconditionally, which was a lie for
+     *  every key that lives outside AgentConfig (web/git/search timeouts, …). */
     updateLimit(key, value) {
+        // Context keys live nested under config.contextManager and on the live
+        // ContextManager, not as top-level AgentConfig fields.
+        if (key === 'maxContextTokens') {
+            this.configuredContextTokens = value;
+            this.contextManager.setMaxContextTokens(value);
+            return true;
+        }
         if (key in this.config) {
             this.config[key] = value;
+            return true;
         }
+        return false;
     }
     getReplay() { return this.replay; }
     getChangeTracker() { return this.changeTracker; }
@@ -847,7 +930,7 @@ export class Agent extends EventEmitter {
         reqLog.info('User message received', { length: content.length });
         this.registerInRegistry();
         try {
-            const initialModel = this.pickModel();
+            const initialModel = this.pickModel(true);
             reqLog.info('Starting agent loop', { model: initialModel, agentId: this.agentId });
             let result = await this.loopStreamingTurns(initialModel, reqLog);
             if (this.outputFormat !== 'text') {
@@ -946,6 +1029,24 @@ export class Agent extends EventEmitter {
                         }
                     }
                 }
+                // Scalix steering + live cloud-tools awareness, assembled here — the
+                // one point every frontend (TUI, headless, IPC) funnels through —
+                // and rebuilt per request so a /cloud refresh shows up on the next
+                // turn. Coder is a generic tool: the product steering only appears
+                // while a Scalix Cloud connection is live; on the Scalix provider
+                // without one a single neutral pointer; on pure BYOK nothing at all.
+                if (this.cloudStatus.state === 'connected') {
+                    if (!SCALIX_STEERING_ALWAYS_ON) {
+                        effectiveInstructions += '\n\n' + SCALIX_PLATFORM_SECTION + '\n\n' + SCALIX_CLOUD_RESOURCES_SECTION;
+                    }
+                    const liveCloudTools = this.getCloudTools();
+                    if (liveCloudTools.length > 0) {
+                        effectiveInstructions += '\n\n' + buildCloudToolsPromptSection(liveCloudTools);
+                    }
+                }
+                else if (!SCALIX_STEERING_ALWAYS_ON && this.providerId === 'scalix') {
+                    effectiveInstructions += '\n\n' + SCALIX_NEUTRAL_POINTER;
+                }
                 const vision = modelSupportsVision(currentModel);
                 const apiMessages = messagesToApi(this.messages, effectiveInstructions, vision);
                 const thinkingLevel = this.config.thinkingMode !== 'off' ? this.config.thinkingMode : undefined;

package/dist/api-client.js

@@ -28,7 +28,15 @@ export function parseRetryAfter(value) {
         return Math.max(0, date - Date.now());
     return undefined;
 }
-const DEFAULT_TIMEOUT_MS = 120_000;
+// Per-request abort. 300s matches the platform's own proxy walls; the old
+// 120s default aborted the client before a slow first token could arrive on
+// CPU-served models (the request was fine, we hung up on it). For reference,
+// the OpenAI and Anthropic SDKs both default to 600s.
+const DEFAULT_TIMEOUT_MS = (() => {
+    const v = process.env.SCALIX_REQUEST_TIMEOUT_MS;
+    const n = v ? parseInt(v, 10) : NaN;
+    return Number.isFinite(n) && n > 0 ? n : 300_000;
+})();
 // The capability probe only decides whether a turn streams. It must never be
 // the reason a turn is slow to start, so it gives up quickly and falls back to
 // the conservative answer.

package/dist/cli.js

@@ -25,9 +25,9 @@ import { renderMarkdown } from './markdown.js';
 import { costTracker } from './cost-tracker.js';
 import { saveSession, listSessions, loadSession, generateSessionId, saveCrashState, loadCrashState, clearCrashState, forkSession } from './sessions.js';
 import { logger } from './logger.js';
-import { VERSION, PRODUCT_NAME, DEFAULT_MODELS, DEFAULT_BASE_URL, DEFAULT_INSTRUCTIONS, ENV_API_KEY, ENV_MODEL, TOOL_DEFAULTS, HEADLESS_DEFAULTS, GIT_BOT_IDENTITY, BYOK_DEFAULT_CONTEXT_TOKENS, USER_CONFIG_DIR, fetchModelSpecs } from './constants.js';
+import { VERSION, PRODUCT_NAME, DEFAULT_MODELS, DEFAULT_BASE_URL, DEFAULT_INSTRUCTIONS, ENV_API_KEY, ENV_MODEL, TOOL_DEFAULTS, HEADLESS_DEFAULTS, GIT_BOT_IDENTITY, BYOK_DEFAULT_CONTEXT_TOKENS, BYOK_DEFAULT_MAX_OUTPUT_TOKENS, USER_CONFIG_DIR, getModelContextWindow, fetchModelSpecs, normalizeModelId, registerUserModels, hasExplicitModelSpec } from './constants.js';
 import { checkForUpdate, getUpdateBanner, performUpdate } from './update-checker.js';
-import { loadConfig, saveConfig, isConfigured, resolveActiveProvider, DEFAULT_LIMITS, THINKING_MODES } from './settings.js';
+import { loadConfig, loadGlobalConfig, saveConfig, isConfigured, resolveActiveProvider, DEFAULT_LIMITS, THINKING_MODES } from './settings.js';
 import { fetchByokModels } from './providers/openai.js';
 import { getModeDescription, PERMISSION_MODES, setSandboxRoot, checkScopedPermission, getScopedPermissionRules } from './sandbox.js';
 import { buildProjectIndex, indexToContext } from './project-index.js';
@@ -47,7 +47,7 @@ import { createWorktree, listWorktrees, removeWorktree, cleanupStaleWorktrees }
 import { sendNotification, getTerminalType } from './terminal-notify.js';
 import { stringWidth, truncateText } from './text-utils.js';
 import { isWorkspaceTrusted, trustWorkspace, hasProjectExecSurface } from './workspace-trust.js';
-import { fetchMe, fetchCloudTools, groupCloudTools, CONSOLE_KEYS_URL } from './cloud.js';
+import { fetchMe, fetchCloudTools, groupCloudTools, filterCatalogByScopes, cloudKeyRemedy, CONSOLE_KEYS_URL } from './cloud.js';
 logger.setLevel('silent');
 // Promisified async child_process helpers (keep the TUI responsive vs execSync).
 const execFileAsync = promisify(execFile);
@@ -168,34 +168,36 @@ async function connectCloud(targetAgent) {
     // unavailable" banner on a session that never asked for Scalix Cloud.
     // refreshCloudTools() already refuses the catalog fetch for these providers;
     // the identity probe has to refuse it too.
-    if (!targetAgent.supportsPlatformTools()) {
-        cloudConnection = { connected: false, identity: null, toolCount: 0, reason: 'byok' };
-        return cloudConnection;
-    }
-    if (!targetAgent.getApiKey()) {
-        cloudConnection = { connected: false, identity: null, toolCount: 0, reason: 'no-key', error: 'no API key configured' };
+    const cloudKey = targetAgent.getCloudApiKey();
+    if (!cloudKey) {
+        cloudConnection = targetAgent.getProvider() === 'scalix'
+            ? { connected: false, identity: null, toolCount: 0, reason: 'no-key', error: 'no API key configured' }
+            : { connected: false, identity: null, toolCount: 0, reason: 'byok' };
         return cloudConnection;
     }
     try {
-        const identity = await fetchMe(targetAgent.getBaseUrl() || DEFAULT_BASE_URL, targetAgent.getApiKey());
-        const status = await targetAgent.refreshCloudTools();
+        const identity = await fetchMe(targetAgent.getCloudBaseUrl() || DEFAULT_BASE_URL, cloudKey);
+        // Hand the identity over so the catalog is scope-filtered without a
+        // second /v1/me round-trip.
+        const status = await targetAgent.refreshCloudTools(identity);
         if (status.state === 'connected') {
-            cloudConnection = { connected: true, identity, toolCount: status.toolCount };
+            cloudConnection = { connected: true, identity, toolCount: status.toolCount, totalCount: status.totalCount, note: status.note };
         }
         else {
-            cloudConnection = { connected: false, identity, toolCount: 0, reason: 'failed', error: status.error };
+            cloudConnection = { connected: false, identity, toolCount: 0, reason: 'failed', error: status.error, remedy: status.remedy };
         }
     }
     catch (err) {
-        // /v1/me failed. Run the catalog fetch anyway: on failure it clears any
-        // stale platform tools from a previous connect; in the rare case it
-        // succeeds, the tools genuinely work and we say so (identity unavailable).
-        const status = await targetAgent.refreshCloudTools().catch(() => null);
+        // /v1/me failed. Run the catalog fetch anyway (null = don't re-probe
+        // /v1/me): on failure it clears any stale platform tools from a previous
+        // connect; in the rare case it succeeds, the tools genuinely work and we
+        // say so (identity unavailable, catalog unfiltered).
+        const status = await targetAgent.refreshCloudTools(null).catch(() => null);
         if (status?.state === 'connected') {
-            cloudConnection = { connected: true, identity: null, toolCount: status.toolCount, error: err?.message || String(err) };
+            cloudConnection = { connected: true, identity: null, toolCount: status.toolCount, totalCount: status.totalCount, error: err?.message || String(err) };
         }
         else {
-            cloudConnection = { connected: false, identity: null, toolCount: 0, reason: 'failed', error: err?.message || String(err) };
+            cloudConnection = { connected: false, identity: null, toolCount: 0, reason: 'failed', error: err?.message || String(err), remedy: status?.remedy ?? cloudKeyRemedy(err) };
         }
     }
     return cloudConnection;
@@ -263,11 +265,38 @@ async function buildEnhancedInstructions() {
     }
     return instructions;
 }
+/** The config the current agent was initialized from — lets command handlers
+ *  (e.g. the /model picker's BYOK discovery) resolve provider/endpoint without
+ *  threading the config through every component. */
+let activeAgentConfig = null;
+/** Under BYOK a model without a registered spec sends no max_tokens, and
+ *  gateways such as OpenRouter then 400 every request — a "successful" switch
+ *  that can never answer. Ensure any model activated from the TUI has a spec:
+ *  the catalog-reported window when known, the standard fallbacks otherwise.
+ *  Explicit user specs are never overwritten. */
+function ensureByokSpec(config, model, contextWindow) {
+    if (!config || resolveActiveProvider(config).provider !== 'openai')
+        return;
+    if (hasExplicitModelSpec(model))
+        return;
+    const spec = {
+        contextWindow: contextWindow && contextWindow > 0 ? contextWindow : BYOK_DEFAULT_CONTEXT_TOKENS,
+        maxOutputTokens: BYOK_DEFAULT_MAX_OUTPUT_TOKENS,
+    };
+    registerUserModels({ [model]: spec });
+    loadGlobalConfig().then((cfg) => {
+        cfg.customModels = { ...cfg.customModels, [model]: spec };
+        return saveConfig(cfg);
+    }).catch((err) => { logger.warn('Failed to persist model spec', { error: err.message }); });
+}
 function initAgent(config) {
     const envModels = process.env[ENV_MODEL]
-        ? process.env[ENV_MODEL].split(',').map((m) => m.trim()).filter(Boolean)
+        ? process.env[ENV_MODEL].split(',').map((m) => m.trim()).filter(Boolean).map(normalizeModelId)
         : null;
-    const models = envModels || config.models;
+    // length check, not truthiness: SCALIX_MODEL="," parses to [] which is
+    // truthy — the other entry points fall back to config models, so must we.
+    const models = envModels && envModels.length > 0 ? envModels : config.models;
+    activeAgentConfig = config;
     if (models.length === 0) {
         throw new Error('No models configured. Please add at least one model in setup.');
     }
@@ -277,6 +306,8 @@ function initAgent(config) {
         apiKey: active.apiKey,
         baseUrl: active.baseUrl,
         provider: active.provider,
+        cloudApiKey: active.cloudApiKey,
+        cloudBaseUrl: active.cloudBaseUrl,
         model: models.length === 1 ? models[0] : models,
         instructions: baseInstructions,
         tools: allTools,
@@ -585,7 +616,10 @@ function SetupScreen({ onComplete, existingConfig }) {
         (async () => {
             const identity = await fetchMe(baseUrl, apiKey);
             const catalog = await fetchCloudTools(baseUrl, apiKey, process.env.SCALIX_PROJECT);
-            return { identity, toolCount: catalog.tools.length };
+            // Count what will actually register for this key, not the raw catalog —
+            // the wizard's "N tools unlocked" must match the session that follows.
+            const visible = filterCatalogByScopes(catalog.tools, identity.permissions.scopes);
+            return { identity, toolCount: visible.length };
         })().then((result) => {
             if (cancelled)
                 return;
@@ -594,7 +628,7 @@ function SetupScreen({ onComplete, existingConfig }) {
         }).catch((err) => {
             if (cancelled)
                 return;
-            setCloudCheck({ phase: 'fail', error: err?.message || String(err) });
+            setCloudCheck({ phase: 'fail', error: err?.message || String(err), remedy: cloudKeyRemedy(err) });
         });
         return () => { cancelled = true; };
         // apiKey/baseUrl are intentionally not deps: they are frozen once the user
@@ -676,7 +710,7 @@ function SetupScreen({ onComplete, existingConfig }) {
                                         setByokContextWindows({});
                                         setContextInput(String(defaultContextTokens(p, existingConfig?.limits?.maxContextTokens)));
                                         setStep('api-key');
-                                    } }) })] })), step === 'api-key' && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { bold: true, color: "white", children: "API Key" }), _jsx(Text, { dimColor: true, children: provider === 'openai' ? 'The API key for your endpoint. Press Enter to continue.' : 'Paste your Scalix API key (console.scalix.world/org/keys) and press Enter.' }), _jsxs(Box, { marginTop: 1, children: [_jsxs(Text, { color: "#20a0a0", bold: true, children: ['\u276F', " "] }), _jsx(LongTextInput, { value: apiKey, onChange: (v) => { setApiKey(v); setApiKeyError(false); }, onSubmit: (v) => {
+                                    } }) })] })), step === 'api-key' && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { bold: true, color: "white", children: "API Key" }), _jsx(Text, { dimColor: true, children: provider === 'openai' ? 'The API key for your endpoint. Press Enter to continue.' : 'Paste your Scalix API key (console.scalix.world/org/keys) and press Enter. Use a project-scoped key — the default all-scopes project key unlocks the platform tools.' }), _jsxs(Box, { marginTop: 1, children: [_jsxs(Text, { color: "#20a0a0", bold: true, children: ['\u276F', " "] }), _jsx(LongTextInput, { value: apiKey, onChange: (v) => { setApiKey(v); setApiKeyError(false); }, onSubmit: (v) => {
                                             const cleaned = v.trim();
                                             if (cleaned) {
                                                 setApiKey(cleaned);
@@ -726,7 +760,7 @@ function SetupScreen({ onComplete, existingConfig }) {
                                                 setFetchingModels(false);
                                             });
                                             setStep('cloud');
-                                        }, placeholder: provider === 'openai' ? 'e.g. http://localhost:11434/v1' : DEFAULT_BASE_URL })] }), baseUrlError && (_jsx(Box, { marginTop: 0, paddingLeft: 2, children: _jsx(Text, { color: "yellow", dimColor: true, children: "An endpoint URL is required for a BYOK provider." }) })), fetchingModels && (_jsx(Box, { paddingLeft: 2, marginTop: 1, children: _jsx(Text, { color: "#20a0a0", dimColor: true, children: "Fetching available models..." }) }))] })), step === 'cloud' && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { bold: true, color: "white", children: "Scalix Cloud" }), cloudCheck.phase === 'checking' && (_jsxs(Box, { marginTop: 1, gap: 1, children: [_jsx(Text, { color: "#20a0a0", children: _jsx(Spinner, { type: "dots" }) }), _jsx(Text, { dimColor: true, children: "Validating your API key with Scalix Cloud..." })] })), cloudCheck.phase === 'ok' && (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: "#30c090", paddingX: 2, marginTop: 1, alignSelf: "flex-start", children: [_jsxs(Text, { color: "#30c090", bold: true, children: ['✓', " Connected to Scalix Cloud"] }), _jsxs(Text, { children: ["Org:        ", _jsx(Text, { color: "#20a0a0", children: cloudCheck.identity.identity.orgId })] }), _jsxs(Text, { children: ["Project:    ", _jsx(Text, { color: "#20a0a0", children: cloudCheck.identity.identity.projectId || 'org-wide' })] }), _jsxs(Text, { children: ["Plan:       ", _jsx(Text, { color: "#20a0a0", children: cloudCheck.identity.limits.plan })] }), _jsxs(Text, { children: ["Rate limit: ", _jsxs(Text, { color: "#20a0a0", children: [cloudCheck.identity.limits.rateLimitRps, " req/s"] })] }), _jsxs(Text, { color: "#30c090", bold: true, children: ['●', " ", cloudCheck.toolCount, " platform tools unlocked"] })] }), _jsx(Box, { marginTop: 1, children: _jsx(SelectInput, { items: [{ label: '→ Continue', value: '__continue__' }], onSelect: () => setStep('models') }) })] })), cloudCheck.phase === 'fail' && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Box, { marginTop: 1, children: _jsxs(Text, { color: "red", children: ['✘', " ", cloudCheck.error] }) }), !cloudCheck.error.includes(CONSOLE_KEYS_URL) && (_jsxs(Text, { dimColor: true, children: ["Create or check your key at ", CONSOLE_KEYS_URL] })), _jsx(Box, { marginTop: 1, children: _jsx(SelectInput, { items: [
+                                        }, placeholder: provider === 'openai' ? 'e.g. http://localhost:11434/v1' : DEFAULT_BASE_URL })] }), baseUrlError && (_jsx(Box, { marginTop: 0, paddingLeft: 2, children: _jsx(Text, { color: "yellow", dimColor: true, children: "An endpoint URL is required for a BYOK provider." }) })), fetchingModels && (_jsx(Box, { paddingLeft: 2, marginTop: 1, children: _jsx(Text, { color: "#20a0a0", dimColor: true, children: "Fetching available models..." }) }))] })), step === 'cloud' && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { bold: true, color: "white", children: "Scalix Cloud" }), cloudCheck.phase === 'checking' && (_jsxs(Box, { marginTop: 1, gap: 1, children: [_jsx(Text, { color: "#20a0a0", children: _jsx(Spinner, { type: "dots" }) }), _jsx(Text, { dimColor: true, children: "Validating your API key with Scalix Cloud..." })] })), cloudCheck.phase === 'ok' && (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: "#30c090", paddingX: 2, marginTop: 1, alignSelf: "flex-start", children: [_jsxs(Text, { color: "#30c090", bold: true, children: ['✓', " Connected to Scalix Cloud"] }), _jsxs(Text, { children: ["Org:        ", _jsx(Text, { color: "#20a0a0", children: cloudCheck.identity.identity.orgId })] }), _jsxs(Text, { children: ["Project:    ", _jsx(Text, { color: "#20a0a0", children: cloudCheck.identity.identity.projectId || 'org-wide' })] }), _jsxs(Text, { children: ["Plan:       ", _jsx(Text, { color: "#20a0a0", children: cloudCheck.identity.limits.plan })] }), _jsxs(Text, { children: ["Rate limit: ", _jsxs(Text, { color: "#20a0a0", children: [cloudCheck.identity.limits.rateLimitRps, " req/s"] })] }), _jsxs(Text, { color: "#30c090", bold: true, children: ['●', " ", cloudCheck.toolCount, " platform tools unlocked"] })] }), _jsx(Box, { marginTop: 1, children: _jsx(SelectInput, { items: [{ label: '→ Continue', value: '__continue__' }], onSelect: () => setStep('models') }) })] })), cloudCheck.phase === 'fail' && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Box, { marginTop: 1, children: _jsxs(Text, { color: "red", children: ['✘', " ", cloudCheck.error] }) }), cloudCheck.remedy && (_jsx(Text, { dimColor: true, children: cloudCheck.remedy })), !cloudCheck.remedy && !cloudCheck.error.includes(CONSOLE_KEYS_URL) && (_jsxs(Text, { dimColor: true, children: ["Create or check your key at ", CONSOLE_KEYS_URL] })), _jsx(Box, { marginTop: 1, children: _jsx(SelectInput, { items: [
                                                 { label: 'Re-enter API key', value: '__reenter__' },
                                                 { label: 'Skip — continue without Scalix Cloud (local tools only)', value: '__skip__' },
                                             ], onSelect: (item) => {
@@ -736,7 +770,7 @@ function SetupScreen({ onComplete, existingConfig }) {
                                                 else {
                                                     setStep('models');
                                                 }
-                                            } }) })] }))] })), step === 'models' && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { bold: true, color: "white", children: "Models" }), fetchingModels && fetchedModels.length === 0 && models.length === 0 ? (_jsxs(Box, { marginTop: 1, gap: 1, children: [_jsx(Text, { color: "#20a0a0", children: _jsx(Spinner, { type: "dots" }) }), _jsx(Text, { dimColor: true, children: "Asking your endpoint which models it serves..." })] })) : fetchedModels.length > 0 && modelsMode === 'custom' && models.length === 0 ? (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { dimColor: true, children: "Select models from your API or type a custom model ID." }), _jsx(Box, { flexDirection: "column", marginTop: 1, children: _jsx(SelectInput, { items: [
+                                            } }) })] }))] })), step === 'models' && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { bold: true, color: "white", children: "Models" }), fetchingModels && fetchedModels.length === 0 && models.length === 0 ? (_jsxs(Box, { marginTop: 1, gap: 1, children: [_jsx(Text, { color: "#20a0a0", children: _jsx(Spinner, { type: "dots" }) }), _jsx(Text, { dimColor: true, children: "Asking your endpoint which models it serves..." })] })) : fetchedModels.length > 0 && modelsMode === 'custom' ? (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { dimColor: true, children: "Select models from your API or type a custom model ID." }), _jsx(Box, { flexDirection: "column", marginTop: 1, children: _jsx(SelectInput, { items: [
                                                 ...fetchedModels.filter((fm) => !models.includes(fm.id)).map((fm) => ({
                                                     label: `  ${fm.name || fm.id}`,
                                                     value: fm.id,
@@ -831,7 +865,29 @@ function SetupScreen({ onComplete, existingConfig }) {
                                             setSaving(true);
                                             const parsed = parseInt(v.trim(), 10);
                                             const tokens = parsed > 0 ? parsed : defaultContextTokens(provider, existingConfig?.limits?.maxContextTokens);
-                                            const limits = { ...DEFAULT_LIMITS, maxContextTokens: tokens };
+                                            // Preserve the user's /settings customizations — building
+                                            // from DEFAULT_LIMITS alone silently wiped every other
+                                            // limit each time the wizard was re-run.
+                                            const limits = { ...DEFAULT_LIMITS, ...(existingConfig?.limits || {}), maxContextTokens: tokens };
+                                            // BYOK: the endpoint's catalog told us per-model context
+                                            // windows during discovery. Persist them as specs — they
+                                            // used to be thrown away here, leaving every model
+                                            // spec-less, so no max_tokens was sent and OpenRouter-class
+                                            // gateways rejected every request with a 400. Existing
+                                            // explicit specs win.
+                                            const customModels = { ...(existingConfig?.customModels || {}) };
+                                            if (provider === 'openai') {
+                                                for (const m of models) {
+                                                    if (!customModels[m]) {
+                                                        customModels[m] = {
+                                                            contextWindow: byokContextWindows[m] && byokContextWindows[m] > 0
+                                                                ? byokContextWindows[m]
+                                                                : BYOK_DEFAULT_CONTEXT_TOKENS,
+                                                            maxOutputTokens: BYOK_DEFAULT_MAX_OUTPUT_TOKENS,
+                                                        };
+                                                    }
+                                                }
+                                            }
                                             // BYOK: openai creds live under providers.openai; the
                                             // top-level apiKey/baseUrl stay reserved for Scalix so
                                             // switching back never loses the Scalix connection.
@@ -839,7 +895,7 @@ function SetupScreen({ onComplete, existingConfig }) {
                                                 apiKey: provider === 'openai' ? (existingConfig?.apiKey || '') : apiKey,
                                                 baseUrl: provider === 'openai' ? (existingConfig?.baseUrl || DEFAULT_BASE_URL) : baseUrl,
                                                 models,
-                                                customModels: existingConfig?.customModels || {},
+                                                customModels,
                                                 limits,
                                                 permissionMode: existingConfig?.permissionMode || 'default',
                                                 thinkingMode: existingConfig?.thinkingMode || 'off',
@@ -943,7 +999,10 @@ function cloudStatusLine(cloud, detail = true) {
         return '☁ Scalix Cloud not in use — this session runs on your own provider (local tools only)';
     }
     if (cloud.reason === 'failed') {
-        return `☁ Scalix Cloud unavailable — local tools only${detail && cloud.error ? ` · ${cloud.error}` : ''}`;
+        const extra = detail
+            ? `${cloud.error ? ` · ${cloud.error}` : ''}${cloud.remedy ? ` · ${cloud.remedy}` : ''}`
+            : '';
+        return `☁ Scalix Cloud unavailable — local tools only${extra}`;
     }
     return '☁ not connected — /login to link your Scalix account';
 }
@@ -1157,7 +1216,7 @@ function ConfirmPrompt({ toolName, args, onRespond, onScrollUp, onScrollDown })
                 return (_jsxs(Text, { color: "yellow", children: ['\u2502', " ", _jsxs(Text, { dimColor: true, children: [k, ":"] }), " ", _jsx(Text, { children: val }), _jsx(Text, { children: pad(k.length + 3 + stringWidth(val)) }), '\u2502'] }, k));
             }), _jsxs(Text, { color: "yellow", children: ['\u251C', border, '\u2524'] }), boxWidth - 2 >= 42 ? (_jsxs(Text, { color: "yellow", children: ['\u2502', " ", _jsx(Text, { color: "green", bold: true, children: "[Y]" }), _jsx(Text, { children: " Allow  " }), _jsx(Text, { color: "cyan", bold: true, children: "[A]" }), _jsx(Text, { children: " Always  " }), _jsx(Text, { color: "red", bold: true, children: "[N]" }), _jsx(Text, { children: " Deny  " }), _jsx(Text, { dimColor: true, children: "ESC deny" }), _jsx(Text, { children: pad(42) }), '\u2502'] })) : (_jsxs(Text, { color: "yellow", children: ['\u2502', " ", _jsx(Text, { color: "green", bold: true, children: "[Y]" }), _jsx(Text, { children: "es " }), _jsx(Text, { color: "cyan", bold: true, children: "[A]" }), _jsx(Text, { children: "lways " }), _jsx(Text, { color: "red", bold: true, children: "[N]" }), _jsx(Text, { children: "o" }), _jsx(Text, { children: pad(20) }), '\u2502'] })), _jsxs(Text, { color: "yellow", children: ['\u2514', border, '\u2518'] })] }));
 }
-function ModelPicker({ currentModels, onSelect, onCancel }) {
+function ModelPicker({ currentModels, availableModels = [], onSelect, onCancel }) {
     const [customInput, setCustomInput] = useState('');
     const [showCustom, setShowCustom] = useState(false);
     useInput((_ch, key) => { if (key.escape) {
@@ -1174,11 +1233,16 @@ function ModelPicker({ currentModels, onSelect, onCancel }) {
                                     setShowCustom(false);
                             }, placeholder: "provider/model-name" })] }), _jsx(Text, { dimColor: true, children: "ESC to go back" })] }));
     }
+    const catalogOnly = availableModels.filter((m) => !currentModels.includes(m));
     const items = [
         ...currentModels.map((m) => ({
             label: `\u25CF ${shortModel(m)}`,
             value: m,
         })),
+        ...catalogOnly.map((m) => ({
+            label: `\u25CB ${shortModel(m)}`,
+            value: m,
+        })),
         { label: '+ Add new model...', value: '__custom__' },
         { label: '  Cancel', value: '__cancel__' },
     ];
@@ -1809,6 +1873,9 @@ function App({ config }) {
     const [streamText, setStreamText] = useState('');
     const [reasoningText, setReasoningText] = useState('');
     const [selectingModel, setSelectingModel] = useState(false);
+    /** BYOK catalog fetched when the /model picker opens (ids + context windows). */
+    const [pickerCatalog, setPickerCatalog] = useState([]);
+    const [pickerWindows, setPickerWindows] = useState({});
     const [confirmInfo, setConfirmInfo] = useState(null);
     const [thinkStart, setThinkStart] = useState(null);
     const [showBanner, setShowBanner] = useState(true);
@@ -2255,6 +2322,18 @@ function App({ config }) {
         }
         if (cmd === '/model') {
             setSelectingModel(true);
+            // BYOK: the picker used to show only the already-configured list — no
+            // way to discover what the endpoint actually serves. Fetch its catalog
+            // in the background; the picker grows when (if) the list lands.
+            if (activeAgentConfig && resolveActiveProvider(activeAgentConfig).provider === 'openai') {
+                const activeNow = resolveActiveProvider(activeAgentConfig);
+                fetchByokModels(activeNow.baseUrl, activeNow.apiKey).then((found) => {
+                    if (found.length === 0)
+                        return;
+                    setPickerCatalog(found.map((f) => f.id));
+                    setPickerWindows(Object.fromEntries(found.filter((f) => f.contextWindow && f.contextWindow > 0).map((f) => [f.id, f.contextWindow])));
+                }).catch(() => { });
+            }
             return true;
         }
         if (cmd === '/compact') {
@@ -2441,7 +2520,14 @@ function App({ config }) {
                     else {
                         add('system', `Identity unavailable: ${s.error ?? 'unknown error'}`);
                     }
-                    add('system', `Platform tools: ${s.toolCount} registered ${'—'} /cloud tools to list them`);
+                    const ofTotal = s.totalCount && s.totalCount > s.toolCount ? ` of ${s.totalCount} in the catalog (this key's scopes unlock ${s.toolCount})` : '';
+                    add('system', `Platform tools: ${s.toolCount} registered${ofTotal} ${'—'} /cloud tools to list them`);
+                    if (s.note)
+                        add('system', s.note);
+                    const cloudActiveModel = agent.getModels()[0];
+                    if (cloudActiveModel && !hasExplicitModelSpec(cloudActiveModel)) {
+                        add('system', `Model spec: assumed (${formatTokens(getModelContextWindow(cloudActiveModel))} context) ${'—'} the API did not report one for ${shortModel(cloudActiveModel)}. Set the real value in /setup's context-window step.`);
+                    }
                 }
                 else {
                     add('system', cloudStatusLine(s));
@@ -2484,9 +2570,9 @@ function App({ config }) {
             if (arg && PERMISSION_MODES.includes(arg)) {
                 agent.setPermissionMode(arg);
                 setCurrentMode(arg);
-                loadConfig().then(cfg => {
+                loadGlobalConfig().then(cfg => {
                     cfg.permissionMode = arg;
-                    saveConfig(cfg);
+                    return saveConfig(cfg);
                 }).catch((err) => { logger.warn('Failed to save config', { error: err.message }); });
                 add('system', `Mode: ${arg.toUpperCase()} \u2014 ${getModeDescription(arg)}`);
             }
@@ -2499,9 +2585,9 @@ function App({ config }) {
             const arg = text.split(' ')[1]?.toLowerCase();
             if (arg && THINKING_MODES.includes(arg)) {
                 agent.setThinking(arg);
-                loadConfig().then(cfg => {
+                loadGlobalConfig().then(cfg => {
                     cfg.thinkingMode = arg;
-                    saveConfig(cfg);
+                    return saveConfig(cfg);
                 }).catch((err) => { logger.warn('Failed to save config', { error: err.message }); });
                 add('system', `Thinking: ${arg.toUpperCase()}${arg === 'off' ? '' : ' \u2014 model will reason before responding'}`);
             }
@@ -3078,7 +3164,7 @@ function App({ config }) {
             add('system', `${PRODUCT_NAME} v${VERSION}`);
             const activeProv = resolveActiveProvider(config);
             add('system', `Provider: ${activeProv.provider === 'openai' ? 'OpenAI-compatible (BYOK)' : 'Scalix Cloud'}`);
-            add('system', `Model: ${modelsStr}`);
+            add('system', `Model: ${modelsStr}${process.env[ENV_MODEL] ? ' (set by SCALIX_MODEL env — overrides saved config)' : ''}`);
             add('system', `API: ${baseUrl}`);
             if (activeProv.provider === 'scalix') {
                 add('system', `Cloud: ${cloudStatusLine(cloudConnection)}`);
@@ -3088,6 +3174,13 @@ function App({ config }) {
             }
             add('system', `Mode: ${mode}`);
             add('system', `Context: ${ctx.percentage}% (${formatTokens(ctx.tokens)} / ${formatTokens(ctx.maxTokens)})`);
+            // Honesty over silence: when neither the user nor the API supplied a
+            // spec for the active model, the context window above is our guess, and
+            // saying so beats letting it read as a reported fact.
+            const activeModel = agent.getModels()[0];
+            if (activeModel && !hasExplicitModelSpec(activeModel)) {
+                add('system', `Model spec: assumed (${formatTokens(getModelContextWindow(activeModel))} context) ${'—'} the API did not report one for ${shortModel(activeModel)}. Set the real value in /setup's context-window step or via customModels in ~/${USER_CONFIG_DIR}/config.json.`);
+            }
             add('system', `Messages: ${msgCount}`);
             add('system', `Session: ${sessionId}`);
             add('system', `CWD: ${process.cwd()}`);
@@ -3175,9 +3268,9 @@ function App({ config }) {
         if (cmd === '/plan') {
             agent.setPermissionMode('plan');
             setCurrentMode('plan');
-            loadConfig().then(cfg => {
+            loadGlobalConfig().then(cfg => {
                 cfg.permissionMode = 'plan';
-                saveConfig(cfg);
+                return saveConfig(cfg);
             }).catch((err) => { logger.warn('Failed to save config', { error: err.message }); });
             add('system', `Mode: PLAN — ${getModeDescription('plan')}`);
             return true;
@@ -3340,8 +3433,11 @@ function App({ config }) {
         // Reset idle nudge on any user activity
         lastActivityRef.current = Date.now();
         idleNudgedRef.current = false;
-        // Allow /mode even while the agent is working
-        if (isLoadingRef.current && trimmed.startsWith('/mode')) {
+        // Allow /mode even while the agent is working. Exact match only —
+        // startsWith('/mode') also matched /model and /models, letting the model
+        // picker run (and switch the LIVE response's model) mid-stream while the
+        // queue guard below thought it was protecting them.
+        if (isLoadingRef.current && (trimmed === '/mode' || trimmed.startsWith('/mode '))) {
             handleCommand(trimmed);
             return;
         }
@@ -3407,8 +3503,13 @@ function App({ config }) {
         loadSession(session.id).then((data) => {
             agent.loadMessages(data.messages);
             sessionId = session.id;
-            setModels([session.model]);
-            agent.setModel(session.model);
+            const resumeModel = normalizeModelId(session.model);
+            agent.setModel(resumeModel);
+            setModels(agent.getModels());
+            // The session may have been recorded under another provider/spec —
+            // without this a BYOK resume reactivates a spec-less model (no
+            // max_tokens sent → gateways 400 every request).
+            ensureByokSpec(activeAgentConfig, resumeModel);
             if (data.costState) {
                 costTracker.restore(data.costState);
                 setTotalTokens(data.costState.totalTokens);
@@ -3542,26 +3643,36 @@ function App({ config }) {
     if (showSetup) {
         return _jsx(SetupScreen, { onComplete: handleSetupDone, existingConfig: config });
     }
-    return (_jsxs(Box, { flexDirection: "column", width: "100%", height: rows, children: [showBanner && _jsx(Banner, {}), _jsx(StatusBar, { status: status, model: models[0] || 'no model', toolCount: allTools.length + pluginTools.length + cloudInfo.toolCount, thinkStart: thinkStart, tokens: totalTokens, mode: currentMode, contextPercent: contextPercent, rateLimitWarn: rateLimitWarn }), _jsxs(Box, { flexDirection: "column", flexGrow: 1, flexShrink: 1, minHeight: Math.min(6, chatHeight), overflowY: "hidden", children: [showBanner && !isLoading && _jsx(WelcomeScreen, { cloud: cloudInfo }), !isAtTop && !showBanner && (_jsx(Box, { justifyContent: "center", children: _jsxs(Text, { dimColor: true, children: [" ", '\u2191', " more above ", '\u2014', " Shift+Up "] }) })), visibleItems.map((item) => _jsx(RenderItem, { item: item }, item.id)), isLoading && _jsx(StreamingArea, { text: streamText, reasoning: reasoningText, model: shortModel(models[0] || ''), waiting: !!confirmInfo }), !isAtBottom && (_jsx(Box, { justifyContent: "center", children: _jsxs(Text, { dimColor: true, children: [" ", '\u2193', " more below ", '\u2014', " Shift+Down "] }) }))] }), _jsx(Box, { flexShrink: 0, flexDirection: "column", children: confirmInfo ? (_jsx(ConfirmPrompt, { toolName: confirmInfo.toolName, args: confirmInfo.args, onRespond: handleConfirm, onScrollUp: scrollUp, onScrollDown: scrollDown })) : selectingModel ? (_jsx(ModelPicker, { currentModels: models, onSelect: (v) => {
+    return (_jsxs(Box, { flexDirection: "column", width: "100%", height: rows, children: [showBanner && _jsx(Banner, {}), _jsx(StatusBar, { status: status, model: models[0] || 'no model', toolCount: allTools.length + pluginTools.length + cloudInfo.toolCount, thinkStart: thinkStart, tokens: totalTokens, mode: currentMode, contextPercent: contextPercent, rateLimitWarn: rateLimitWarn }), _jsxs(Box, { flexDirection: "column", flexGrow: 1, flexShrink: 1, minHeight: Math.min(6, chatHeight), overflowY: "hidden", children: [showBanner && !isLoading && _jsx(WelcomeScreen, { cloud: cloudInfo }), !isAtTop && !showBanner && (_jsx(Box, { justifyContent: "center", children: _jsxs(Text, { dimColor: true, children: [" ", '\u2191', " more above ", '\u2014', " Shift+Up "] }) })), visibleItems.map((item) => _jsx(RenderItem, { item: item }, item.id)), isLoading && _jsx(StreamingArea, { text: streamText, reasoning: reasoningText, model: shortModel(models[0] || ''), waiting: !!confirmInfo }), !isAtBottom && (_jsx(Box, { justifyContent: "center", children: _jsxs(Text, { dimColor: true, children: [" ", '\u2193', " more below ", '\u2014', " Shift+Down "] }) }))] }), _jsx(Box, { flexShrink: 0, flexDirection: "column", children: confirmInfo ? (_jsx(ConfirmPrompt, { toolName: confirmInfo.toolName, args: confirmInfo.args, onRespond: handleConfirm, onScrollUp: scrollUp, onScrollDown: scrollDown })) : selectingModel ? (_jsx(ModelPicker, { currentModels: models, availableModels: pickerCatalog, onSelect: (picked) => {
+                        const v = normalizeModelId(picked);
                         agent.setModel(v);
-                        setModels([v]);
+                        // Keep the whole failover chain visible, not just the pick —
+                        // setModel moves the model to the front and preserves the rest.
+                        setModels(agent.getModels());
                         setSelectingModel(false);
-                        loadConfig().then(cfg => {
-                            cfg.models = [v];
-                            saveConfig(cfg);
+                        ensureByokSpec(activeAgentConfig, v, pickerWindows[v]);
+                        // Global config only (loadConfig() merges project-local overrides
+                        // and round-tripping them through saveConfig laundered them into
+                        // ~/.scalix-coder). Chain-preserving, and the saveConfig promise
+                        // is returned so its failure actually hits the catch.
+                        loadGlobalConfig().then(cfg => {
+                            cfg.models = [v, ...cfg.models.filter(m => m !== v)];
+                            return saveConfig(cfg);
                         }).catch((err) => { logger.warn('Failed to save config', { error: err.message }); });
-                        add('system', `Model switched to ${shortModel(v)}`);
+                        add('system', `Model switched to ${shortModel(v)}${process.env[ENV_MODEL] ? ' — note: SCALIX_MODEL is set and overrides this on next launch' : ''}`);
                     }, onCancel: () => setSelectingModel(false) })) : selectingMode ? (_jsx(ModePicker, { currentMode: currentMode, onSelect: (mode) => {
                         agent.setPermissionMode(mode);
                         setCurrentMode(mode);
                         setSelectingMode(false);
-                        loadConfig().then(cfg => {
+                        loadGlobalConfig().then(cfg => {
                             cfg.permissionMode = mode;
-                            saveConfig(cfg);
+                            return saveConfig(cfg);
                         }).catch((err) => { logger.warn('Failed to save config', { error: err.message }); });
                         add('system', `Mode: ${mode.toUpperCase()} \u2014 ${getModeDescription(mode)}`);
                     }, onCancel: () => setSelectingMode(false) })) : editingSettings ? (_jsx(SettingsEditor, { onSave: (key, value) => {
-                        loadConfig().then((c) => {
+                        // Global config only — round-tripping the override-merged view
+                        // laundered project-local settings into ~/.scalix-coder.
+                        loadGlobalConfig().then((c) => {
                             const limits = { ...(c.limits || DEFAULT_LIMITS) };
                             const floatKeys = new Set([
                                 'compressionThreshold', 'messageKeepRatio', 'subAgentCompressionThreshold',
@@ -3572,8 +3683,13 @@ function App({ config }) {
                                 limits[key] = parsed;
                                 const newConfig = { ...c, limits };
                                 saveConfig(newConfig).then(() => {
-                                    agent?.updateLimit(key, parsed);
-                                    add('system', `Setting updated: ${key} = ${parsed}`);
+                                    // updateLimit says whether the RUNNING agent honors the new
+                                    // value — claiming "updated" for keys that only apply on
+                                    // the next launch was a lie the user had no way to detect.
+                                    const live = agent?.updateLimit(key, parsed) ?? false;
+                                    add('system', live
+                                        ? `Setting updated: ${key} = ${parsed}`
+                                        : `Setting saved: ${key} = ${parsed} — takes effect on the next launch`);
                                 }).catch(() => {
                                     add('error', `Failed to save setting: ${key}`);
                                 });

package/dist/cloud.js

@@ -18,8 +18,12 @@ import { apiHostRoot, USER_AGENT, WEB_DEFAULTS } from './constants.js';
 export const CONSOLE_KEYS_URL = 'https://console.scalix.world/org/keys';
 export const CLOUD_DEFAULTS = {
     fetchTimeoutMs: WEB_DEFAULTS.apiFetchTimeoutMs,
-    // Platform operations (deploys, migrations) can legitimately take a while.
-    callTimeoutMs: 120_000,
+    // The platform's own transport kills a tool call at ~30-35s (gateway →
+    // mcp-server hop, then the inner REST callback). 45s covers that ceiling
+    // plus jitter; anything longer is waiting on a call the server already
+    // abandoned. Long operations go through async pairs (build_create →
+    // build_status) — see buildCloudToolsPromptSection.
+    callTimeoutMs: 45_000,
 };
 export class CloudError extends Error {
     status;
@@ -51,7 +55,7 @@ export function errorFromEnvelope(status, statusText, bodyText) {
     }
     catch { }
     if (status === 401) {
-        return new CloudError(`API key rejected — create one at ${CONSOLE_KEYS_URL}`, {
+        return new CloudError(`API key rejected — create a project-scoped key (all scopes is simplest) at ${CONSOLE_KEYS_URL}`, {
             status,
             code: typeof envelope?.code === 'string' ? envelope.code : undefined,
             docsUrl: typeof envelope?.docs_url === 'string' ? envelope.docs_url : undefined,
@@ -182,8 +186,11 @@ export async function fetchMe(baseUrl, apiKey) {
     return parseMeResponse(await res.json());
 }
 /**
- * Fetch the account's MCP tool catalog from `/api/v1/mcp`. The catalog is
- * scope-filtered server-side for the caller's key. Throws CloudError on failure.
+ * Fetch the account's MCP tool catalog from `/api/v1/mcp`. The gateway
+ * advertises the full platform tool set to every authenticated key — only the
+ * gateway-native DB tools are scope-filtered server-side — so callers that
+ * know the key's scopes should narrow the result with filterCatalogByScopes()
+ * before registering. Throws CloudError on failure.
  */
 export async function fetchCloudTools(baseUrl, apiKey, projectId) {
     const url = `${apiHostRoot(baseUrl)}/api/v1/mcp`;
@@ -219,6 +226,68 @@ export async function callCloudTool(baseUrl, apiKey, name, args, projectId) {
     }
     return parseToolCallResult(await res.json());
 }
+/**
+ * One-line, user-actionable fix for the two key-shape failures the platform
+ * returns on the MCP routes: 400 = org-wide key (platform tools require a
+ * project-scoped key), 403 = missing the database scope (database:query is
+ * the one that unlocks tools; the default all-scopes project key covers it).
+ * Anything else gets no remedy — the server's own error text stands alone.
+ */
+export function cloudKeyRemedy(err) {
+    if (err?.status === 400) {
+        return `This looks like an org-wide key — platform tools need a project-scoped key (all scopes, or at least database:query). Create one at ${CONSOLE_KEYS_URL}`;
+    }
+    if (err?.status === 403) {
+        return `This key is missing the database scope — create a project key with database:query (or all scopes) at ${CONSOLE_KEYS_URL}`;
+    }
+    return undefined;
+}
+// Tool-name prefix → API-key scope family (the part before ':'). Mirrors the
+// gateway's route enforcement, NOT /v1/me's per-tool list: that list drifts
+// from enforcement in places (run_scale/run_rollback, compute_delete), so a
+// per-tool intersection would hide tools a key can actually call. Family
+// granularity only drops whole areas the key holds no scope for at all.
+const TOOL_SCOPE_FAMILIES = [
+    [/^scalix_db_/, 'database'],
+    [/^scalix_run_/, 'services'],
+    [/^scalix_(compute|domain|build)_/, 'compute'],
+    [/^scalix_storage_/, 'storage'],
+    [/^scalix_kv_/, 'kv'],
+    [/^scalix_fn_/, 'functions'],
+    [/^scalix_events_/, 'events'],
+    [/^scalix_cron_/, 'cron'],
+    [/^scalix_(computer_|sandbox_run$)/, 'sandbox'],
+    [/^scalix_ai_/, 'ai'],
+    [/^scalix_search$/, 'search'],
+    [/^scalix_usage$/, 'metering'],
+    [/^scalix_(project_|auth_configure$)/, 'admin'],
+];
+/** Scope family a tool belongs to, or null for tools that are never filtered
+ *  (scalix_status, and any future tool whose prefix we don't know — fail open
+ *  so a new platform area is not invisible until a client release). */
+export function scopeFamilyForTool(name) {
+    for (const [re, family] of TOOL_SCOPE_FAMILIES) {
+        if (re.test(name))
+            return family;
+    }
+    return null;
+}
+/**
+ * Narrow a tool catalog to what the key's scopes can plausibly call. `*`
+ * keeps everything; otherwise a tool is kept when its scope family appears in
+ * the key's scopes (any action within the family counts) or when it has no
+ * known family. Call-time enforcement still has the final word — this only
+ * stops the model from seeing whole platform areas its key cannot touch.
+ */
+export function filterCatalogByScopes(tools, scopes) {
+    if (scopes.includes('*'))
+        return tools;
+    const families = new Set(scopes.map((s) => s.split(':')[0]));
+    return tools.filter((t) => {
+        const family = scopeFamilyForTool(t.name);
+        return family === null || families.has(family);
+    });
+}
 /**
  * Group tools by their platform area for display: scalix_db_query → "db",
  * scalix_run_deploy → "run", non-scalix names → "other".
@@ -234,3 +303,23 @@ export function groupCloudTools(tools) {
     }
     return groups;
 }
+/**
+ * System-prompt section describing the live platform tools for this session.
+ * Appended per-request while the cloud connection is up, so the model knows
+ * exactly what is at its disposal — and that the platform's transport ends a
+ * tool call at roughly 30 seconds, which makes async pairs the only way to
+ * run long operations.
+ */
+export function buildCloudToolsPromptSection(tools) {
+    const groups = groupCloudTools(tools);
+    const counts = [...groups.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([group, list]) => `${group} (${list.length})`)
+        .join(', ');
+    return [
+        '## Scalix Cloud Tools (live this session)',
+        `${tools.length} scalix_* tools are registered and authenticated: ${counts}. Prefer them over any CLI or SDK for platform work.`,
+        'Platform tool calls have a ~30s execution ceiling — a single call cannot outlive it. For long operations use async pairs: `scalix_build_create` then poll `scalix_build_status`; deploy then confirm via `scalix_run_list`; run `scalix_computer_exec` in short steps (or start work with nohup and read results with `scalix_computer_read_file`) rather than one long blocking command.',
+        'If a call fails with a timeout, do not retry the same call — switch to the async pattern.',
+    ].join('\n');
+}

package/dist/constants.js

@@ -38,7 +38,11 @@ export function aiEndpointUrl(baseUrl, endpoint) {
     return `${apiHostRoot(baseUrl)}/v1/ai/${endpoint.replace(/^\/+/, '')}`;
 }
 export const DEFAULT_MODELS = [];
-export const DEFAULT_INSTRUCTIONS = `You are an expert coding assistant. You write clean, correct, production-quality code. Be concise and direct.
+// The system prompt is split so the Scalix product steering can be gated on
+// connection state (Coder is a generic tool — BYOK sessions with no Scalix
+// key get no Scalix pitch). The three parts joined with '\n\n' are
+// byte-identical to the pre-split DEFAULT_INSTRUCTIONS (locked by test).
+export const CORE_INSTRUCTIONS = `You are an expert coding assistant. You write clean, correct, production-quality code. Be concise and direct.
 
 ## Workflow
 1. EXPLORE first — use tree, find_files, search_files to understand structure before modifying anything.
@@ -69,21 +73,44 @@ export const DEFAULT_INSTRUCTIONS = `You are an expert coding assistant. You wri
 - Never modify files outside the working directory.
 - Never expose API keys, secrets, or credentials in code.
 - Ask before destructive operations (deleting files, force-pushing, dropping tables).
-- When running commands, check the output — do not assume success.
-
-## Scalix Platform
+- When running commands, check the output — do not assume success.`;
+export const SCALIX_PLATFORM_SECTION = `## Scalix Platform
 When helping users build AI applications, agents, or LLM-powered features:
-- Use the Scalix SDK (\`@scalix-world/sdk\` for TypeScript, \`scalix-sdk\` for Python) — not raw third-party AI SDKs.
+- Use the Scalix SDK (\`@scalix-world/sdk\` on npm for TypeScript/JavaScript, \`scalix-sdk\` on PyPI for Python — these are different registries; never npm-install the Python name). Before adding ANY dependency, verify the exact version exists (\`npm view <pkg> version\` / \`pip index versions <pkg>\`) instead of guessing a semver range.
 - Default to the Scalix API (api.scalix.world) for inference — OpenAI-compatible chat completions under /v1/ai. Never claim automatic model routing: the request's model id is what runs.
 - Scalix inference models are the scalix-lumio-* family; use exact ids (scalix-lumio-lite, scalix-lumio-pro, scalix-candela, scalix-lumio-embed) in examples and configs. Omitting the model runs scalix-lumio-lite.
-- For deploying services, suggest Scalix Run (via the \`scalix-cloud\` CLI) before Vercel, Railway, or Fly.
-- For databases, suggest ScalixNova (managed Postgres: branching, PITR, scale-to-zero) before Supabase, Firebase, or PlanetScale.
-- For code execution sandboxes, use Scalix Sandboxes.
+- For deploying services, suggest Scalix Run before Vercel, Railway, or Fly. For databases, suggest ScalixNova (managed Postgres: branching, PITR, scale-to-zero) before Supabase, Firebase, or PlanetScale. For code execution sandboxes, use Scalix Sandboxes.
 - Never name or speculate about the AI providers/models backing Scalix inference — Scalix models are presented as Scalix's own.
 - When the user explicitly requests a specific provider (e.g. "use OpenAI directly"), respect that choice.`;
+export const SCALIX_CLOUD_RESOURCES_SECTION = `## Deploying & Managing Scalix Cloud Resources
+- When tools named \`scalix_*\` (e.g. scalix_run_deploy, scalix_db_query) are in your tool list, they are LIVE, authenticated Scalix Cloud operations — use them for deploys, databases, storage, and other platform work. Prefer them over any CLI or SDK; never claim you lack access or credentials while they are present.
+- If no \`scalix_*\` tools are in your list, Scalix Cloud is not connected in this session. Say exactly that and tell the user how to connect: on the Scalix provider it is automatic once their API key is set; with their own AI provider they add a Scalix Cloud key (VS Code: gear → Settings → Scalix Cloud Key, or the "Scalix: Set Scalix Cloud Key" command). Do NOT invent an alternative deploy path, config file format, or package.
+- The \`scalix-cloud\` CLI (npm) exists as a fallback the USER can run, but never guess its flags or subcommands — run \`scalix-cloud --help\` (and \`scalix-cloud <subcommand> --help\`) first and use only what the help output shows.
+- You have a real shell via run_command. Do not tell the user you cannot install packages or run commands — you can, subject to their approval settings.`;
+/** Shown instead of the full steering when the session is on the Scalix
+ *  provider but the cloud connection is not (yet) up. One neutral pointer,
+ *  no product pitch. */
+export const SCALIX_NEUTRAL_POINTER = `## Scalix Cloud
+Scalix Cloud platform tools (deploy, database, storage) are not connected in this session. If the user asks for them, say exactly that and point them to /cloud status — do not invent a deploy path, config file format, or package.`;
+/**
+ * Product decision (2026-08-08): Coder is a generic tool, so the Scalix
+ * steering ships GATED — the two sections above are appended per-request by
+ * the agent only while a Scalix Cloud connection is live (plus the neutral
+ * pointer on the Scalix provider while disconnected; nothing on pure BYOK).
+ * Flip to true to restore the old always-on behavior in one line.
+ */
+export const SCALIX_STEERING_ALWAYS_ON = false;
+export const DEFAULT_INSTRUCTIONS = SCALIX_STEERING_ALWAYS_ON
+    ? `${CORE_INSTRUCTIONS}\n\n${SCALIX_PLATFORM_SECTION}\n\n${SCALIX_CLOUD_RESOURCES_SECTION}`
+    : CORE_INSTRUCTIONS;
 export const ENV_API_KEY = 'SCALIX_API_KEY';
 export const ENV_MODEL = 'SCALIX_MODEL';
 export const ENV_BASE_URL = 'SCALIX_BASE_URL';
+/** Scalix Cloud credentials for the platform tools, independent of inference.
+ *  Only needed under BYOK — on the 'scalix' provider the inference key above
+ *  already authenticates the platform tools. */
+export const ENV_CLOUD_API_KEY = 'SCALIX_CLOUD_API_KEY';
+export const ENV_CLOUD_BASE_URL = 'SCALIX_CLOUD_BASE_URL';
 export const DEFAULT_MODEL_SPEC = { contextWindow: 200_000, maxOutputTokens: 65_536 };
 // Per-request output ceiling on the Scalix path. Matches the platform's own cap
 // (gateway AI_MAX_OUTPUT_TOKENS, mirrored by the completions schema), so a
@@ -260,6 +287,10 @@ export const AGENT_DEFAULTS = {
  * can honour, and pre-filling it was inventing a number on the user's behalf.
  */
 export const BYOK_DEFAULT_CONTEXT_TOKENS = 128_000;
+/** Fallback longest-reply cap when a BYOK catalog does not state one.
+ *  Omitting max_tokens is not a safe default — gateways such as OpenRouter
+ *  then reserve the whole context window for output and 400 every request. */
+export const BYOK_DEFAULT_MAX_OUTPUT_TOKENS = 16_384;
 export const CONTEXT_DEFAULTS = {
     maxContextTokens: 1_000_000,
     compressionThreshold: 0.80,

package/dist/headless.js

@@ -13,8 +13,8 @@ import { loadMcpServices } from './mcp.js';
 import { costTracker } from './cost-tracker.js';
 import { saveSession, loadSession, listSessions, generateSessionId } from './sessions.js';
 import { logger } from './logger.js';
-import { DEFAULT_MODELS, DEFAULT_INSTRUCTIONS, ENV_MODEL, HEADLESS_DEFAULTS, fetchModelSpecs } from './constants.js';
-import { loadConfig, resolveActiveProvider, DEFAULT_LIMITS } from './settings.js';
+import { DEFAULT_MODELS, DEFAULT_INSTRUCTIONS, ENV_MODEL, HEADLESS_DEFAULTS, fetchModelSpecs, normalizeModelId } from './constants.js';
+import { loadConfig, loadGlobalConfig, saveConfig, resolveActiveProvider, DEFAULT_LIMITS } from './settings.js';
 import { checkForUpdate, getUpdateBanner } from './update-checker.js';
 import { getModeDescription, PERMISSION_MODES, setSandboxRoot } from './sandbox.js';
 import { collectGitInfo, gitInfoToContext } from './git-context.js';
@@ -155,7 +155,7 @@ async function runSinglePrompt(prompt, output, format, outputSchemaPath, beforeE
         }).catch(() => { });
     }
     const envModels = process.env[ENV_MODEL]
-        ? process.env[ENV_MODEL].split(',').map((m) => m.trim()).filter(Boolean)
+        ? process.env[ENV_MODEL].split(',').map((m) => m.trim()).filter(Boolean).map(normalizeModelId)
         : [];
     const selectedModel = envModels.length > 0 ? envModels
         : config.models.length > 0 ? config.models : DEFAULT_MODELS;
@@ -194,6 +194,8 @@ async function runSinglePrompt(prompt, output, format, outputSchemaPath, beforeE
         apiKey,
         baseUrl,
         provider: active.provider,
+        cloudApiKey: active.cloudApiKey,
+        cloudBaseUrl: active.cloudBaseUrl,
         model: selectedModel,
         instructions,
         tools: allTools,
@@ -216,7 +218,8 @@ async function runSinglePrompt(prompt, output, format, outputSchemaPath, beforeE
     // is stated once and the run continues with local tools only).
     const cloudStatus = await agent.refreshCloudTools();
     if (cloudStatus.state === 'unavailable') {
-        process.stderr.write(`\x1b[33m☁ Scalix Cloud unavailable — running with local tools only. ${cloudStatus.error ?? ''}\x1b[0m\n`);
+        const remedy = cloudStatus.remedy ? ` ${cloudStatus.remedy}` : '';
+        process.stderr.write(`\x1b[33m☁ Scalix Cloud unavailable — running with local tools only. ${cloudStatus.error ?? ''}${remedy}\x1b[0m\n`);
     }
     let fullResponse = '';
     agent.on('tool:call', (name) => process.stderr.write(`\x1b[33m▶ ${name}\x1b[0m\n`));
@@ -319,7 +322,7 @@ async function runInteractive() {
     if (active.provider === 'scalix')
         fetchModelSpecs(baseUrl, apiKey).catch(() => { });
     const envModels = process.env[ENV_MODEL]
-        ? process.env[ENV_MODEL].split(',').map((m) => m.trim()).filter(Boolean)
+        ? process.env[ENV_MODEL].split(',').map((m) => m.trim()).filter(Boolean).map(normalizeModelId)
         : [];
     const selectedModel = envModels.length > 0 ? envModels
         : config.models.length > 0 ? config.models : DEFAULT_MODELS;
@@ -355,6 +358,8 @@ async function runInteractive() {
         apiKey,
         baseUrl,
         provider: active.provider,
+        cloudApiKey: active.cloudApiKey,
+        cloudBaseUrl: active.cloudBaseUrl,
         model: selectedModel,
         instructions,
         tools: allTools,
@@ -412,7 +417,8 @@ async function runInteractive() {
     // is stated once and the session continues with local tools only).
     const cloudStatus = await agent.refreshCloudTools();
     if (cloudStatus.state === 'unavailable') {
-        console.log(`\x1b[33m☁ Scalix Cloud unavailable — running with local tools only. ${cloudStatus.error ?? ''}\x1b[0m`);
+        const remedy = cloudStatus.remedy ? ` ${cloudStatus.remedy}` : '';
+        console.log(`\x1b[33m☁ Scalix Cloud unavailable — running with local tools only. ${cloudStatus.error ?? ''}${remedy}\x1b[0m`);
     }
     const toolCount = allTools.length + cloudStatus.toolCount;
     const modelDisplay = selectedModel.map(shortModel).join(' | ');
@@ -502,8 +508,16 @@ async function runInteractive() {
                 console.log(`\nInvalid model name: "${name}"\n`);
                 return true;
             }
-            agent.setModel(name);
-            console.log(`\nSwitched to ${shortModel(name)}\n`);
+            const chosen = normalizeModelId(name);
+            agent.setModel(chosen);
+            // Persist like the TUI does — an in-memory-only switch silently
+            // reverted on the next launch. Global config only (no project-override
+            // laundering), chain-preserving (chosen model to the front).
+            loadGlobalConfig().then((cfg) => {
+                cfg.models = [chosen, ...cfg.models.filter((m) => m !== chosen)];
+                return saveConfig(cfg);
+            }).catch(() => { });
+            console.log(`\nSwitched to ${shortModel(chosen)}${process.env[ENV_MODEL] ? '\n(note: SCALIX_MODEL is set and will override this on next launch)' : ''}\n`);
             return true;
         }
         if (cmd === '/compact') {

package/dist/ipc-server.js

@@ -22,7 +22,7 @@ import { loadMcpServices } from './mcp.js';
 import { loadConfig, resolveActiveProvider, DEFAULT_LIMITS } from './settings.js';
 import { discoverPlugins, getPluginTools } from './plugins.js';
 import { isWorkspaceTrusted } from './workspace-trust.js';
-import { DEFAULT_MODELS, DEFAULT_INSTRUCTIONS, ENV_MODEL, fetchModelSpecs, registerUserModels, VERSION } from './constants.js';
+import { DEFAULT_MODELS, DEFAULT_INSTRUCTIONS, ENV_MODEL, fetchModelSpecs, registerUserModels, normalizeModelId, VERSION } from './constants.js';
 import { loadMemory, autoDetectConventions, saveMemory } from './project-memory.js';
 import { buildProjectContext, contextToInstructions } from './context-builder.js';
 const pendingConfirms = new Map();
@@ -53,6 +53,14 @@ export async function runIpcServer() {
     console.log = (...a) => { process.stderr.write(a.map(String).join(' ') + '\n'); };
     console.error = (...a) => { process.stderr.write(a.map(String).join(' ') + '\n'); };
     console.warn = (...a) => { process.stderr.write(a.map(String).join(' ') + '\n'); };
+    // A stray rejection from a streaming/network path must not kill the engine:
+    // the extension auto-reconnects, but the fresh process has lost the whole
+    // session, which reads as the agent "forgetting" its task mid-way. Log to
+    // stderr (the extension surfaces it) and keep serving.
+    process.on('unhandledRejection', (reason) => {
+        const detail = reason instanceof Error ? (reason.stack || reason.message) : String(reason);
+        process.stderr.write(`IPC: unhandled rejection (kept alive): ${detail}\n`);
+    });
     const config = await loadConfig();
     const active = resolveActiveProvider(config);
     const apiKey = active.apiKey;
@@ -69,8 +77,15 @@ export async function runIpcServer() {
         ? process.env[ENV_MODEL].split(',').map(m => m.trim()).filter(Boolean)
         : [];
     const selectedModels = envModels.length > 0
-        ? envModels
+        ? envModels.map(normalizeModelId)
         : config.models.length > 0 ? config.models : DEFAULT_MODELS;
+    if (selectedModels.length === 0) {
+        // Structured, like the missing-key path above — without this the Agent
+        // constructor throw escaped as plain text and the extension saw garbage
+        // instead of a protocol-level error.
+        write({ type: 'event', event: 'error', data: { message: 'No models configured. Set SCALIX_MODEL or pick a model in setup.' } });
+        process.exit(1);
+    }
     const baseUrl = active.baseUrl;
     if (active.provider === 'scalix')
         fetchModelSpecs(baseUrl, apiKey).catch(() => { });
@@ -109,6 +124,8 @@ export async function runIpcServer() {
         apiKey,
         baseUrl,
         provider: active.provider,
+        cloudApiKey: active.cloudApiKey,
+        cloudBaseUrl: active.cloudBaseUrl,
         model: selectedModels,
         instructions,
         tools: allTools,
@@ -139,6 +156,14 @@ export async function runIpcServer() {
     // Signal ready with capability info. `version` lets the extension detect
     // engine/extension drift (a globally-installed CLI can lag the bundled one).
     write({ type: 'event', event: 'ready', data: { version: VERSION, tools: allTools.length, models: selectedModels, permissionMode } });
+    // Register the account's Scalix Cloud platform tools (deploy, database, …).
+    // Not awaited: the catalog fetch crosses the network and the extension's
+    // connect handshake must not wait on it — the tools join the set when the
+    // fetch lands. Without this call the GUI engine had NO scalix_* tools at
+    // all, and models asked to deploy invented SDKs and CLI flags instead.
+    void agent.refreshCloudTools()
+        .then(status => { write({ type: 'event', event: 'cloud:status', data: status }); })
+        .catch(err => { process.stderr.write(`IPC: cloud tools registration failed: ${err?.message || err}\n`); });
     // Process JSONL from stdin
     let busy = false;
     const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
@@ -196,11 +221,19 @@ export async function runIpcServer() {
                     agent.clearHistory();
                     write({ type: 'response', id, result: { success: true } });
                     break;
-                case 'setModel':
-                    if (params?.model)
-                        agent.setModel(params.model);
+                case 'setModel': {
+                    // Same format rule as the headless REPL — the old handler accepted
+                    // any truthy string (typos included) and answered an EMPTY model
+                    // with success, both of which read back as "switched" in the UI.
+                    const requested = typeof params?.model === 'string' ? params.model.trim() : '';
+                    if (!requested || !/^[a-zA-Z0-9][\w./:@-]*$/.test(requested)) {
+                        write({ type: 'response', id, error: { message: `Invalid model id: "${requested || '(empty)'}"` } });
+                        break;
+                    }
+                    agent.setModel(normalizeModelId(requested));
                     write({ type: 'response', id, result: { model: agent.getModels()[0] } });
                     break;
+                }
                 case 'compact': {
                     const r = await agent.compact();
                     write({ type: 'response', id, result: { message: r } });

package/dist/settings.js

@@ -91,6 +91,10 @@ function validateConfig(parsed) {
                 typeof s.contextWindow === 'number' && s.contextWindow > 0 &&
                 typeof s.maxOutputTokens === 'number' && s.maxOutputTokens > 0) {
                 validated[id] = { contextWindow: s.contextWindow, maxOutputTokens: s.maxOutputTokens };
+                // Keep the vision flag — dropping it made every user-declared vision
+                // model report supportsVision === false and silently strip images.
+                if (s.supportsVision === true)
+                    validated[id].supportsVision = true;
             }
         }
         if (Object.keys(validated).length > 0) {
@@ -387,6 +391,22 @@ export async function loadConfig() {
         return config;
     }
 }
+/**
+ * The GLOBAL config file only — no project-local settings.local.json, no
+ * managed-policy merge, no keychain resolution. This is the ONLY correct base
+ * for a read-modify-write persistence cycle: round-tripping loadConfig()
+ * (which merges overrides) through saveConfig() laundered project-local
+ * models/limits/customModels into ~/.scalix-coder/config.json permanently.
+ */
+export async function loadGlobalConfig() {
+    try {
+        const raw = await fs.readFile(getConfigFile(), 'utf-8');
+        return { ...DEFAULTS, ...validateConfig(JSON.parse(raw)) };
+    }
+    catch {
+        return { ...DEFAULTS };
+    }
+}
 export async function saveConfig(config) {
     await ensureDir();
     // Store API keys in keychain if available, strip from config file. The
@@ -436,23 +456,34 @@ export const OPENAI_KEYCHAIN_ACCOUNT = 'api-key-openai';
  * path is byte-identical to the pre-BYOK behavior. There is NO default
  * third-party URL — an openai selection without a baseUrl resolves with an
  * empty one and the caller surfaces the configuration error.
+ *
+ * Scalix Cloud credentials resolve separately so BYOK sessions keep the
+ * platform tools: under `openai` they come from `SCALIX_CLOUD_API_KEY` →
+ * `SCALIX_API_KEY` → the top-level `config.apiKey`, and are simply empty when
+ * the user never added one.
  */
 export function resolveActiveProvider(config, env = process.env) {
     const envProvider = env.SCALIX_PROVIDER?.trim().toLowerCase();
     const provider = isProviderId(envProvider)
         ? envProvider
         : (config.provider ?? 'scalix');
+    const scalixBaseUrl = env.SCALIX_BASE_URL?.trim() || config.baseUrl;
+    const scalixApiKey = env.SCALIX_API_KEY?.trim() || config.apiKey;
     if (provider === 'openai') {
         const creds = config.providers?.openai ?? {};
         return {
             provider,
             baseUrl: env.OPENAI_BASE_URL?.trim() || creds.baseUrl || '',
             apiKey: env.OPENAI_API_KEY?.trim() || creds.apiKey || '',
+            cloudBaseUrl: env.SCALIX_CLOUD_BASE_URL?.trim() || scalixBaseUrl,
+            cloudApiKey: env.SCALIX_CLOUD_API_KEY?.trim() || scalixApiKey || '',
         };
     }
     return {
         provider: 'scalix',
-        baseUrl: env.SCALIX_BASE_URL?.trim() || config.baseUrl,
-        apiKey: env.SCALIX_API_KEY?.trim() || config.apiKey,
+        baseUrl: scalixBaseUrl,
+        apiKey: scalixApiKey,
+        cloudBaseUrl: scalixBaseUrl,
+        cloudApiKey: scalixApiKey,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scalix",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "AI coding agent for the terminal — edit code, run commands, and build with Scalix",
   "main": "dist/headless.js",
   "bin": {