tinywebui 0.1.4 → 0.1.5

package/src/config/config.js

@@ -2,224 +2,225 @@ import { readFileSync, existsSync, writeFileSync, chmodSync } from 'node:fs';
 import { resolve, dirname } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { FILE_ONLY, mergeAccess, keyClass, validateConfig } from '../access/policy.js';
-import { modelProblems, connectorProblems, labelFor, REASONING_REPLAY } from './models.js';
+import { modelProblems, connectorProblems, labelFor, flattenCatalog, nestCatalog, hasEndpoint, defaultModel, REASONING_REPLAY } from './models.js';
 import { logger } from '../log.js';
-
+import { applySecrets, extractSecrets, mergeSecrets, refProblems, takeSecrets } from './secrets.js';
 const log = logger('config');
-
 const CONFIG_FILE = process.env.TINYWEBUI_CONFIG
-  ? resolve(process.env.TINYWEBUI_CONFIG)
-  : resolve(process.cwd(), 'tinywebui.config.json');
-
+    ? resolve(process.env.TINYWEBUI_CONFIG)
+    : resolve(process.cwd(), 'tinywebui.config.json');
 // MCP wiring lives in its own Claude-Desktop-shaped file, next to the config.
 const MCP_FILE = process.env.TINYWEBUI_MCP
-  ? resolve(process.env.TINYWEBUI_MCP)
-  : resolve(dirname(CONFIG_FILE), 'mcp.json');
-
+    ? resolve(process.env.TINYWEBUI_MCP)
+    : resolve(dirname(CONFIG_FILE), 'mcp.json');
+// Keys and the session secret: kept out of the config file (see secrets.ts).
+const SECRETS_FILE = process.env.TINYWEBUI_SECRETS
+    ? resolve(process.env.TINYWEBUI_SECRETS)
+    : resolve(dirname(CONFIG_FILE), 'tinywebui.secrets.json');
 export const DEFAULTS = {
-  baseUrl: 'https://openrouter.ai/api/v1',
-  apiKey: '',
-  // A cheap, fast, tool-capable default that caches well on a stable prefix and
-  // needs no cache_control fields. Any OpenAI-compatible model id works.
-  model: 'deepseek/deepseek-v4.1-flash',
-  // The model catalog (see src/config/models.js). Empty: any model id goes. Listed:
-  // only these can be picked, `model` names one by id, and people see each
-  // entry's label, with its own prompt and sampling settings if it has them.
-  models: [],
-  // Named endpoints a catalog entry can point at (`connector: <id>`): each has
-  // its own baseUrl and apiKey. Entries without one use baseUrl/apiKey above.
-  connectors: [],
-  systemPrompt: [
-    'You are a direct, technically precise assistant.',
-    '',
-    'Answer the question that was asked. Lead with the answer, then the reasoning that',
-    'changes what the reader does -- no preamble, no restating the question, no summary',
-    'of what you just said. Match length to the question: a one-line question gets a',
-    'one-line answer; only go long when the task itself has that much surface area.',
-    '',
-    'Use the tools available to you rather than guessing or asking the user for something',
-    'a tool can tell you. Call a tool immediately when it can resolve the question --',
-    'don\'t ask permission to look something up or run a read-only check. If a tool',
-    'fails, say what failed and what you did instead, rather than silently retrying',
-    'or inventing a plausible-looking result. If you still need to call a tool, make',
-    'the call on its own and hold your answer until the result is back -- writing the',
-    'full answer in the same reply as a pending tool call forces a wasted extra round',
-    'just to say there is nothing left to add.',
-    '',
-    'Say plainly when you are unsure or when something is outside what you can verify.',
-    'Never invent APIs, flags, file paths, figures or citations.',
-    '',
-    'Use markdown only where it earns its keep: code in fenced blocks with a language',
-    'tag, tables for genuinely tabular data, lists for genuinely parallel items. Don\'t',
-    'reach for headers, bold, or bullets to dress up a short answer that reads fine as',
-    'plain sentences.'
-  ].join('\n'),
-  // null = let the provider decide. Setting max_tokens in particular silently
-  // truncates on models that would happily write more.
-  temperature: null,
-  maxTokens: null,
-  // How many rounds of tool calls one message may trigger before the loop is
-  // cut off. Raise it for deep research, lower it to cap spend per message.
-  maxToolRounds: 12,
-  // How long an ask_user question waits for an answer before the run carries
-  // on without one, on the model's own assumptions. 0 waits until the user
-  // answers or stops the run.
-  askUserTimeoutSeconds: 120,
-  // Merged into every completion request. Gateway-specific knobs live here.
-  // TinyWebUI adds OpenRouter session_id automatically; setting provider.order
-  // yourself takes precedence over sticky routing, so only pin providers when
-  // you deliberately want that behavior.
-  extraBody: {},
-  // Prompt caching is on by default, and for most backends -- including every
-  // local runtime -- that means nothing more than a stable request prefix,
-  // which costs nothing and needs no provider support.
-  cache: true,
-  // Which cache dialect to speak. 'auto' infers it from the endpoint and model
-  // and is right for OpenRouter and for anything local; set it explicitly when
-  // you are on a gateway TinyWebUI has not been taught about.
-  //   'auto'     infer (default)
-  //   'implicit' stable prefix only, no cache fields on the wire
-  //   'explicit' Anthropic-style cache_control breakpoints in message content
-  //   'rolling'  OpenRouter top-level automatic cache_control
-  //   'off'      no cache shaping at all
-  cacheMode: 'auto',
-  // Anthropic cache writes default to five minutes. One hour costs more to write
-  // but is useful for research chats with pauses between turns.
-  cacheTtl: '5m',
-  // Which reasoning past assistant turns send back: 'auto' picks per endpoint
-  // (OpenRouter and Anthropic-style: reasoning_details; api.deepseek.com:
-  // reasoning_content on tool-call turns; anything else: none).
-  reasoningReplay: 'auto',
-  // Where conversations live. Tool output is kept whole here and only the
-  // compacted form goes on the wire, so this file grows faster than the window.
-  dbPath: '',
-  // Context compaction. Once the conversation history (system prompt and tool
-  // definitions excluded) crosses `compactThreshold` tokens, tool results older
-  // than the last `keepTurns` user messages are demoted to stubs -- once, and
-  // then frozen, so the cost is a single cache miss rather than a rewritten
-  // prefix on every turn. Set the threshold to 0 to disable.
-  compactThreshold: 60000,
-  keepTurns: 2,
-  // An epoch is a full cache miss, so it only happens when stubbing would
-  // remove at least this many characters from the window.
-  compactMinSaved: 20000,
-  // A single result larger than this is stubbed for every LATER turn the
-  // moment it arrives; the turn that fetched it still reads it whole. High
-  // enough that an ordinary page or search result stays readable for a
-  // follow-up question without an expand_context round.
-  maxInlineChars: 30000,
-  // Hard cap: a result larger than this is stubbed even for the turn that
-  // fetched it, since it would otherwise be resent in full on every remaining
-  // round and can blow the window on its own.
-  maxTurnChars: 120000,
-  // Hard window. If the history is still larger than this many tokens after
-  // compaction -- a long plain-text chat, where there is nothing to stub --
-  // the oldest turns stop being sent (they stay in the transcript), cutting
-  // back to half this size so it moves rarely. 0 disables it.
-  maxHistoryTokens: 100000,
-  // When that window drops turns, summarise them with the chat's model first
-  // and give the model the summary in their place. Off: they are just dropped.
-  llmCompaction: true,
-  // Output cap for that summary request. Reasoning models spend part of it
-  // thinking before they write, and a reply cut off by the cap is rejected,
-  // so this is headroom; the prompt itself asks for a short summary.
-  compactionMaxTokens: 8192,
-  // IANA zone the model is told the date in (and uses for automations). Empty
-  // means the server's own zone.
-  timezone: '',
-  // Which tool calls wait for the user (see src/config/approval.js).
-  //   'writes'  ask before any call not declared read-only (default)
-  //   'all'     ask before every call
-  //   'off'     never ask
-  // Scheduled runs have no one to ask, so a call that would ask is refused.
-  toolApproval: 'writes',
-  // Per-tool overrides, by flat name: always ask / never ask.
-  confirmTools: [],
-  autoApproveTools: [],
-  // Cap on what one expand_context call may return.
-  expandCharBudget: 8000,
-  // Flat tool names switched off from the settings panel -- built-in or an
-  // MCP server's, named exactly as buildBody sends them. Filtered out of what
-  // is offered to the model; a server can still be reached by name, so this
-  // is a per-tool block, not a substitute for disabling the whole server.
-  disabledTools: [],
-  //   'none'           explicit local-only use without login
-  //   'single'         just you, behind a password (authPassword or
-  //                    $TINYWEBUI_PASSWORD; set it with `tinywebui set-password`)
-  //   'trusted-header' many users: an upstream gateway (Cloudflare Access,
-  //                    oauth2-proxy, Authelia, ...) signs people in with
-  //                    Google, Apple, SSO etc. and passes identity headers
-  authMode: 'single',
-  // Level 'single': an scrypt hash (never plaintext), from `tinywebui
-  // set-password`; never writable through /api/config.
-  authPassword: '',
-  // Signs session cookies. Auto-generated on first run when auth is enabled
-  // and this is empty; never sent to the frontend.
-  sessionSecret: '',
-  // Reserved for a native OAuth login ('multiuser'), not implemented yet --
-  // use 'trusted-header' behind a gateway for Google/Apple/SSO sign-in.
-  googleClientId: '',
-  googleClientSecret: '',
-  googleRedirectUri: '',
-  // Emails auto-approved as admin the first time they sign in -- how the
-  // first admin account is bootstrapped.
-  adminEmails: [],
-  sessionTtlDays: 30,
-  // Level 'trusted-header': an upstream gateway (Cloudflare Access, oauth2-
-  // proxy, ...) authenticates and injects identity headers on every request.
-  // Headers are believed only from peers inside trustedProxyCidrs; startup
-  // refuses an empty list. Users are provisioned on first sight.
-  trustedProxyCidrs: [],
-  trustedUserIdHeader: 'x-tinysuite-user-id',
-  trustedEmailHeader: 'x-tinysuite-email',
-  trustedNameHeader: 'x-tinysuite-name',
-  trustedRoleHeader: 'x-tinysuite-role',
-  // Where "log out" sends the browser (e.g. the Access logout URL).
-  logoutUrl: '',
-  // Extra origins allowed to send state-changing requests (e.g. an admin
-  // tool on another host). The page's own origin is always allowed.
-  allowedOrigins: [],
-  // Extra Host names answered when authMode is 'none' (e.g. a LAN name for a
-  // local-only install). Loopback names are always allowed.
-  allowedHosts: [],
-  // false: refuse to start on a database that needs migrating; run
-  // `tinywebui migrate` as its own deployment step instead.
-  autoMigrate: true,
-  // true: nothing in the control plane can change from the UI or API --
-  // settings, tools, MCP servers. Change the files and reload instead.
-  frozen: false,
-  // read_document and search_chats ranking. 'lexical' is SQLite FTS5 BM25 and
-  // needs nothing extra. 'dense' and 'hybrid' use a local ONNX embedding
-  // bundle (fetched by `npm start` / `tinywebui models ensure`, or baked into
-  // the Docker image -- never by the server) and the onnxruntime-node +
-  // @huggingface/tokenizers optional dependencies. 'auto' is hybrid when both
-  // are there and lexical, with a warning, when they are not.
-  retrieval: {
-    mode: 'auto',             // auto | lexical | dense | hybrid
-    model: 'fast',            // fast | balanced | quality (TinySearch's presets) | multilingual, or a name with modelDir
-    modelDir: '',             // bundle folder; default models/<preset> next to the config
-    modelSha256: '',          // pin model.onnx; startup refuses a different file
-    denseWeight: 0.5,         // hybrid: dense share of the fused ranking, BM25 gets the rest
-    rrfK: 60,
-    queryPrefix: '',          // e.g. bge: 'Represent this sentence for searching relevant passages: '
-    documentPrefix: '',
-    // Small-to-big: PASSAGES are what read_document returns (every mode);
-    // CHUNKS are what gets embedded -- as long as the model reads (256
-    // tokens for fast, 512 for bge), so only their overlap is set here.
-    passageSize: 1800,        // characters per passage
-    passageOverlap: 200,      // characters shared by neighbouring passages
-    chunkOverlap: 32,         // tokens shared by neighbouring chunks
-  },
+    // The endpoint of a model that names no connector. Unset: there is none,
+    // and a fresh instance is set up by adding a connector, then its models.
+    // Code and the environment ($TINYWEBUI_BASE_URL) may still set one.
+    baseUrl: '',
+    apiKey: '',
+    // The default model: a catalog id, or with an empty catalog any model id.
+    model: '',
+    // The model catalog (see src/config/models.js). Empty everywhere: any model
+    // id goes. Listed: only these can be picked, `model` names one by id, and
+    // people see each entry's label. An entry may set its own prompt, sampling
+    // and caching; the top-level values below are what it inherits.
+    models: [],
+    // Named endpoints, each with its own baseUrl, optional apiKey and `models` list.
+    connectors: [],
+    systemPrompt: [
+        'You are a direct, technically precise assistant.',
+        '',
+        'Answer the question that was asked. Lead with the answer, then the reasoning that',
+        'changes what the reader does -- no preamble, no restating the question, no summary',
+        'of what you just said. Match length to the question: a one-line question gets a',
+        'one-line answer; only go long when the task itself has that much surface area.',
+        '',
+        'Use the tools available to you rather than guessing or asking the user for something',
+        'a tool can tell you. Call a tool immediately when it can resolve the question --',
+        'don\'t ask permission to look something up or run a read-only check. If a tool',
+        'fails, say what failed and what you did instead, rather than silently retrying',
+        'or inventing a plausible-looking result. If you still need to call a tool, make',
+        'the call on its own and hold your answer until the result is back -- writing the',
+        'full answer in the same reply as a pending tool call forces a wasted extra round',
+        'just to say there is nothing left to add.',
+        '',
+        'Say plainly when you are unsure or when something is outside what you can verify.',
+        'Never invent APIs, flags, file paths, figures or citations.',
+        '',
+        'Use markdown only where it earns its keep: code in fenced blocks with a language',
+        'tag, tables for genuinely tabular data, lists for genuinely parallel items. Don\'t',
+        'reach for headers, bold, or bullets to dress up a short answer that reads fine as',
+        'plain sentences.'
+    ].join('\n'),
+    // null = let the provider decide. Setting max_tokens in particular silently
+    // truncates on models that would happily write more.
+    temperature: null,
+    maxTokens: null,
+    // How many rounds of tool calls one message may trigger before the loop is
+    // cut off. Raise it for deep research, lower it to cap spend per message.
+    maxToolRounds: 12,
+    // How long an ask_user question waits for an answer before the run carries
+    // on without one, on the model's own assumptions. 0 waits until the user
+    // answers or stops the run.
+    askUserTimeoutSeconds: 120,
+    // Merged into every completion request. Gateway-specific knobs live here.
+    // TinyWebUI adds OpenRouter session_id automatically; setting provider.order
+    // yourself takes precedence over sticky routing, so only pin providers when
+    // you deliberately want that behavior.
+    extraBody: {},
+    // Prompt caching is on by default, and for most backends -- including every
+    // local runtime -- that means nothing more than a stable request prefix,
+    // which costs nothing and needs no provider support.
+    cache: true,
+    // Which cache dialect to speak. 'auto' infers it from the endpoint and model
+    // and is right for OpenRouter and for anything local; set it explicitly when
+    // you are on a gateway TinyWebUI has not been taught about.
+    //   'auto'     infer (default)
+    //   'implicit' stable prefix only, no cache fields on the wire
+    //   'explicit' Anthropic-style cache_control breakpoints in message content
+    //   'rolling'  OpenRouter top-level automatic cache_control
+    //   'off'      no cache shaping at all
+    cacheMode: 'auto',
+    // Anthropic cache writes default to five minutes. One hour costs more to write
+    // but is useful for research chats with pauses between turns.
+    cacheTtl: '5m',
+    // Which reasoning past assistant turns send back: 'auto' picks per endpoint
+    // (OpenRouter and Anthropic-style: reasoning_details; api.deepseek.com:
+    // reasoning_content on tool-call turns; anything else: none).
+    reasoningReplay: 'auto',
+    // Where conversations live. Tool output is kept whole here and only the
+    // compacted form goes on the wire, so this file grows faster than the window.
+    dbPath: '',
+    // Context compaction. Once the conversation history (system prompt and tool
+    // definitions excluded) crosses `compactThreshold` tokens, tool results older
+    // than the last `keepTurns` user messages are demoted to stubs -- once, and
+    // then frozen, so the cost is a single cache miss rather than a rewritten
+    // prefix on every turn. Set the threshold to 0 to disable.
+    compactThreshold: 60000,
+    keepTurns: 2,
+    // An epoch is a full cache miss, so it only happens when stubbing would
+    // remove at least this many characters from the window.
+    compactMinSaved: 20000,
+    // A single result larger than this is stubbed for every LATER turn the
+    // moment it arrives; the turn that fetched it still reads it whole. High
+    // enough that an ordinary page or search result stays readable for a
+    // follow-up question without an expand_context round.
+    maxInlineChars: 30000,
+    // Hard cap: a result larger than this is stubbed even for the turn that
+    // fetched it, since it would otherwise be resent in full on every remaining
+    // round and can blow the window on its own.
+    maxTurnChars: 120000,
+    // Hard window. If the history is still larger than this many tokens after
+    // compaction -- a long plain-text chat, where there is nothing to stub --
+    // the oldest turns stop being sent (they stay in the transcript), cutting
+    // back to half this size so it moves rarely. 0 disables it.
+    maxHistoryTokens: 100000,
+    // When that window drops turns, summarise them with the chat's model first
+    // and give the model the summary in their place. Off: they are just dropped.
+    llmCompaction: true,
+    // Output cap for that summary request. Reasoning models spend part of it
+    // thinking before they write, and a reply cut off by the cap is rejected,
+    // so this is headroom; the prompt itself asks for a short summary.
+    compactionMaxTokens: 8192,
+    // IANA zone the model is told the date in (and uses for automations). Empty
+    // means the server's own zone.
+    timezone: '',
+    // Which tool calls wait for the user (see src/config/approval.js).
+    //   'writes'  ask before any call not declared read-only (default)
+    //   'all'     ask before every call
+    //   'off'     never ask
+    // Scheduled runs have no one to ask, so a call that would ask is refused.
+    toolApproval: 'writes',
+    // Per-tool overrides, by flat name: always ask / never ask.
+    confirmTools: [],
+    autoApproveTools: [],
+    // Cap on what one expand_context call may return.
+    expandCharBudget: 8000,
+    // Flat tool names switched off from the settings panel -- built-in or an
+    // MCP server's, named exactly as buildBody sends them. Filtered out of what
+    // is offered to the model; a server can still be reached by name, so this
+    // is a per-tool block, not a substitute for disabling the whole server.
+    disabledTools: [],
+    //   'local'          explicit local-only use without login
+    //   'multiuser'      local accounts: first signup is admin; later signups
+    //                    require an invitation from an admin
+    //   'trusted-header' many users: an upstream gateway (Cloudflare Access,
+    //                    oauth2-proxy, Authelia, ...) signs people in with
+    //                    Google, Apple, SSO etc. and passes identity headers
+    authMode: 'multiuser',
+    // Kept only so old password configurations can be rejected rather than
+    // silently opened without login after upgrading.
+    authPassword: '',
+    // Signs session cookies. Auto-generated on first run when auth is enabled
+    // and this is empty; never sent to the frontend.
+    sessionSecret: '',
+    // Reserved for a future native OAuth login; local multi-user accounts use
+    // email and password today.
+    googleClientId: '',
+    googleClientSecret: '',
+    googleRedirectUri: '',
+    // Emails auto-approved as admin the first time they sign in -- how the
+    // first admin account is bootstrapped.
+    adminEmails: [],
+    sessionTtlDays: 30,
+    // Level 'trusted-header': an upstream gateway (Cloudflare Access, oauth2-
+    // proxy, ...) authenticates and injects identity headers on every request.
+    // Headers are believed only from peers inside trustedProxyCidrs; startup
+    // refuses an empty list. Users are provisioned on first sight.
+    trustedProxyCidrs: [],
+    trustedUserIdHeader: 'x-tinysuite-user-id',
+    trustedEmailHeader: 'x-tinysuite-email',
+    trustedNameHeader: 'x-tinysuite-name',
+    trustedRoleHeader: 'x-tinysuite-role',
+    // Where "log out" sends the browser (e.g. the Access logout URL).
+    logoutUrl: '',
+    // Extra origins allowed to send state-changing requests (e.g. an admin
+    // tool on another host). The page's own origin is always allowed.
+    allowedOrigins: [],
+    // Extra Host names answered when authMode is 'local' (e.g. a LAN name for a
+    // local-only install). Loopback names are always allowed.
+    allowedHosts: [],
+    // false: refuse to start on a database that needs migrating; run
+    // `tinywebui migrate` as its own deployment step instead.
+    autoMigrate: true,
+    // true: nothing in the control plane can change from the UI or API --
+    // settings, tools, MCP servers. Change the files and reload instead.
+    frozen: false,
+    // read_document and search_chats ranking. 'lexical' is SQLite FTS5 BM25 and
+    // needs nothing extra. 'dense' and 'hybrid' use a local ONNX embedding
+    // bundle (fetched by `npm start` / `tinywebui models ensure`, or baked into
+    // the Docker image -- never by the server) and the onnxruntime-node +
+    // @huggingface/tokenizers optional dependencies. 'auto' is hybrid when both
+    // are there and lexical, with a warning, when they are not.
+    retrieval: {
+        mode: 'auto', // auto | lexical | dense | hybrid
+        model: 'fast', // fast | balanced | quality (TinySearch's presets) | multilingual, or a name with modelDir
+        modelDir: '', // bundle folder; default models/<preset> next to the config
+        modelSha256: '', // pin model.onnx; startup refuses a different file
+        denseWeight: 0.5, // hybrid: dense share of the fused ranking, BM25 gets the rest
+        rrfK: 60,
+        queryPrefix: '', // e.g. bge: 'Represent this sentence for searching relevant passages: '
+        documentPrefix: '',
+        // Small-to-big: PASSAGES are what read_document returns (every mode);
+        // CHUNKS are what gets embedded -- as long as the model reads (256
+        // tokens for fast, 512 for bge), so only their overlap is set here.
+        passageSize: 1800, // characters per passage
+        passageOverlap: 200, // characters shared by neighbouring passages
+        chunkOverlap: 32, // tokens shared by neighbouring chunks
+    },
 };
-
 // What an install with no mcp.json starts with: the TinySuite servers, which
 // uv fetches and launches on first use. Any mcp.json, even an empty one,
 // replaces them, so removing them is one save in the MCP panel.
 export const DEFAULT_MCP_SERVERS = Object.freeze({
-  tinysearch: { command: 'uvx', args: ['--python', '3.12', '--from', 'tinysuite-search[server]', 'tinysearch'] },
-  tinycontext: { command: 'uvx', args: ['--python', '3.12', '--from', 'tinysuite-context[server]', 'tinycontext'] },
+    tinysearch: { command: 'uvx', args: ['--python', '3.12', '--from', 'tinysuite-search[server]', 'tinysearch'] },
+    tinycontext: { command: 'uvx', args: ['--python', '3.12', '--from', 'tinysuite-context[server]', 'tinycontext'] },
 });
-
 /**
  * One instance's view of its configuration.
  *
@@ -230,163 +231,250 @@ export const DEFAULT_MCP_SERVERS = Object.freeze({
  * `mcpServers` in code likewise replaces mcp.json and locks the MCP editor.
  */
 export function createConfigSource(opts = {}) {
-  const code = opts.config || {};
-  const file = opts.configFile === false ? null
-    : opts.configFile ? resolve(opts.configFile) : CONFIG_FILE;
-  const mcpFile = opts.mcpFile ? resolve(opts.mcpFile)
-    : file && file !== CONFIG_FILE ? resolve(dirname(file), 'mcp.json') : MCP_FILE;
-  const codeServers = opts.mcpServers || null;
-  const locked = new Set(Object.keys(code));
-  let memory = {}; // stands in for the file when there is none
-
-  const readFile = () => {
-    if (!file) return { ...memory };
-    if (!existsSync(file)) return {};
-    try {
-      return JSON.parse(readFileSync(file, 'utf8'));
-    } catch (err) {
-      throw new Error(`Bad config at ${file}: ${err.message}`);
-    }
-  };
-  const writeFile = (obj) => {
-    if (!file) { memory = obj; return; }
-    if (existsSync(file) && process.platform !== 'win32') chmodSync(file, 0o600);
-    writeFileSync(file, JSON.stringify(obj, null, 2) + '\n', { mode: 0o600 });
-  };
-
-  function load({ persistSecret = true } = {}) {
-    const env = {};
-    if (process.env.TINYWEBUI_BASE_URL) env.baseUrl = process.env.TINYWEBUI_BASE_URL;
-    if (process.env.TINYWEBUI_API_KEY) env.apiKey = process.env.TINYWEBUI_API_KEY;
-    if (process.env.OPENROUTER_API_KEY) env.apiKey = process.env.OPENROUTER_API_KEY;
-    if (process.env.TINYWEBUI_MODEL) env.model = process.env.TINYWEBUI_MODEL;
-    // Secrets can come from the environment, so committed config never holds them.
-    if (process.env.TINYWEBUI_SESSION_SECRET) env.sessionSecret = process.env.TINYWEBUI_SESSION_SECRET;
-
-    const fromFile = readFile();
-    const cfg = { ...DEFAULTS, ...fromFile, ...env, ...code };
-    if (fromFile.access !== undefined || code.access !== undefined) cfg.access = mergeAccess(fromFile.access, code.access);
-    // Partial retrieval blocks fill in from the defaults rather than replace them.
-    // $TINYWEBUI_RETRIEVAL_MODE=lexical is the no-config way to opt out of hybrid.
-    const envRetrieval = process.env.TINYWEBUI_RETRIEVAL_MODE ? { mode: process.env.TINYWEBUI_RETRIEVAL_MODE } : {};
-    cfg.retrieval = { ...DEFAULTS.retrieval, ...(fromFile.retrieval || {}), ...envRetrieval, ...(code.retrieval || {}) };
-    // No silent fallbacks: a bad value is reported by configProblems() and
-    // refuses to start, rather than quietly becoming a default (a mistyped
-    // authMode used to become 'none').
-    if (typeof cfg.baseUrl === 'string') cfg.baseUrl = cfg.baseUrl.replace(/\/+$/, '');
-    // A session secret is required the moment auth is on; generate and persist
-    // one rather than signing cookies with an empty key.
-    if (cfg.authMode !== 'none' && !cfg.sessionSecret && persistSecret) {
-      cfg.sessionSecret = randomBytes(32).toString('hex');
-      try {
-        writeFile({ ...readFile(), sessionSecret: cfg.sessionSecret });
-      } catch (err) {
-        log.error(`could not persist generated sessionSecret: ${err.message}`);
-      }
+    const code = opts.config || {};
+    const file = opts.configFile === false ? null
+        : opts.configFile ? resolve(opts.configFile) : CONFIG_FILE;
+    const mcpFile = opts.mcpFile ? resolve(opts.mcpFile)
+        : file && file !== CONFIG_FILE ? resolve(dirname(file), 'mcp.json') : MCP_FILE;
+    const secretsFile = opts.secretsFile ? resolve(opts.secretsFile)
+        : !file ? null : file !== CONFIG_FILE ? resolve(dirname(file), 'tinywebui.secrets.json') : SECRETS_FILE;
+    const codeServers = opts.mcpServers || null;
+    const locked = new Set(Object.keys(code));
+    let memory = {}; // stands in for the file when there is none
+    let memorySecrets = {};
+    const readFile = () => {
+        if (!file)
+            return { ...memory };
+        if (!existsSync(file))
+            return {};
+        try {
+            return JSON.parse(readFileSync(file, 'utf8'));
+        }
+        catch (err) {
+            throw new Error(`Bad config at ${file}: ${err.message}`);
+        }
+    };
+    const writeFile = (obj) => {
+        if (!file) {
+            memory = obj;
+            return;
+        }
+        if (existsSync(file) && process.platform !== 'win32')
+            chmodSync(file, 0o600);
+        writeFileSync(file, JSON.stringify(obj, null, 2) + '\n', { mode: 0o600 });
+    };
+    const readSecrets = () => {
+        if (!secretsFile)
+            return structuredClone(memorySecrets);
+        if (!existsSync(secretsFile))
+            return {};
+        try {
+            return JSON.parse(readFileSync(secretsFile, 'utf8'));
+        }
+        catch (err) {
+            throw new Error(`Bad secrets file at ${secretsFile}: ${err.message}`);
+        }
+    };
+    const writeSecrets = (secrets) => {
+        if (!secretsFile) {
+            memorySecrets = secrets;
+            return;
+        }
+        if (existsSync(secretsFile) && process.platform !== 'win32')
+            chmodSync(secretsFile, 0o600);
+        writeFileSync(secretsFile, JSON.stringify(secrets, null, 2) + '\n', { mode: 0o600 });
+    };
+    // Not validated here: startup, reload and save check the result with configProblems().
+    function load({ persistSecret = true } = {}) {
+        const env = {};
+        if (process.env.TINYWEBUI_BASE_URL)
+            env.baseUrl = process.env.TINYWEBUI_BASE_URL;
+        if (process.env.TINYWEBUI_API_KEY)
+            env.apiKey = process.env.TINYWEBUI_API_KEY;
+        if (process.env.OPENROUTER_API_KEY)
+            env.apiKey = process.env.OPENROUTER_API_KEY;
+        if (process.env.TINYWEBUI_MODEL)
+            env.model = process.env.TINYWEBUI_MODEL;
+        // Secrets can come from the environment, so committed config never holds them.
+        if (process.env.TINYWEBUI_SESSION_SECRET)
+            env.sessionSecret = process.env.TINYWEBUI_SESSION_SECRET;
+        let fromFile = readFile();
+        // Keys written into the config file by hand, or by a version before the
+        // secrets file, move there on start. Read-only callers (the CLI) and a
+        // frozen deployment leave the files alone; the keys still apply.
+        const { shape, found, names } = extractSecrets(fromFile);
+        if (names.length && persistSecret) {
+            if (isFrozen())
+                log.warn(`${file ?? 'the config'} holds ${names.join(', ')}; move them to ${secretsFile} or the environment`);
+            else {
+                try {
+                    writeSecrets(mergeSecrets(readSecrets(), found));
+                    writeFile(shape);
+                    fromFile = shape;
+                    log.info(`moved ${names.join(', ')} from ${file} to ${secretsFile}`);
+                }
+                catch (err) {
+                    log.error(`could not move secrets out of ${file}: ${err.message}`);
+                }
+            }
+        }
+        const cfg = { ...DEFAULTS, ...applySecrets(fromFile, readSecrets()), ...env, ...code };
+        if (fromFile.access !== undefined || code.access !== undefined)
+            cfg.access = mergeAccess(fromFile.access, code.access);
+        // Partial retrieval blocks fill in from the defaults rather than replace them.
+        // $TINYWEBUI_RETRIEVAL_MODE=lexical is the no-config way to opt out of hybrid.
+        const envRetrieval = process.env.TINYWEBUI_RETRIEVAL_MODE ? { mode: process.env.TINYWEBUI_RETRIEVAL_MODE } : {};
+        cfg.retrieval = { ...DEFAULTS.retrieval, ...(fromFile.retrieval || {}), ...envRetrieval, ...(code.retrieval || {}) };
+        // A mistyped authMode must fail validation rather than disable login.
+        if (typeof cfg.baseUrl === 'string')
+            cfg.baseUrl = cfg.baseUrl.replace(/\/+$/, '');
+        Object.assign(cfg, flattenCatalog(cfg));
+        cfg.model = defaultModel(cfg);
+        // A session secret is required the moment auth is on; generate and persist
+        // one rather than signing cookies with an empty key.
+        if (['multiuser', 'trusted-header'].includes(cfg.authMode) && !cfg.sessionSecret && persistSecret) {
+            cfg.sessionSecret = randomBytes(32).toString('hex');
+            try {
+                writeSecrets({ ...readSecrets(), sessionSecret: cfg.sessionSecret });
+            }
+            catch (err) {
+                log.error(`could not persist generated sessionSecret: ${err.message}`);
+            }
+        }
+        return cfg;
     }
-    return cfg;
-  }
-
-  /** Applies the writable, unlocked part of `patch`; locked keys are an error. */
-  function save(patch) {
-    if (isFrozen()) throw new LockedError('this deployment is frozen: change its files instead');
-    const fileOnly = Object.keys(patch).filter((k) => FILE_ONLY.has(k));
-    if (fileOnly.length) throw new LockedError(`set in files only, not editable here: ${fileOnly.join(', ')}`);
-    const blocked = Object.keys(patch).filter((k) => WRITABLE.has(k) && locked.has(k));
-    if (blocked.length) throw new LockedError(`set in code, not editable here: ${blocked.join(', ')}`);
-    const current = readFile();
-    for (const [k, v] of Object.entries(mergeSecrets(patch, current))) {
-      if (WRITABLE.has(k)) current[k] = v;
+    /** Applies the writable, unlocked part of `patch`; locked keys are an error. */
+    function save(patch) {
+        if (isFrozen())
+            throw new LockedError('this deployment is frozen: change its files instead');
+        const fileOnly = Object.keys(patch).filter((k) => FILE_ONLY.has(k));
+        if (fileOnly.length)
+            throw new LockedError(`set in files only, not editable here: ${fileOnly.join(', ')}`);
+        const blocked = Object.keys(patch).filter((k) => WRITABLE.has(k) && locked.has(k));
+        if (blocked.length)
+            throw new LockedError(`set in code, not editable here: ${blocked.join(', ')}`);
+        // Edits apply to the flat catalog the page sees; the file gets it nested.
+        const current = readFile();
+        Object.assign(current, flattenCatalog(current));
+        const split = takeSecrets(patch, current, readSecrets());
+        if (split.refused.length)
+            throw new LockedError(`set from the environment, not editable here: ${split.refused.join(', ')}`);
+        for (const [k, v] of Object.entries(split.patch)) {
+            if (!WRITABLE.has(k))
+                continue;
+            if (v === undefined)
+                delete current[k];
+            else
+                current[k] = v;
+        }
+        // Validate what the files would become before writing them.
+        const problems = configProblems({ ...DEFAULTS, ...applySecrets(current, split.secrets), ...code });
+        if (problems.length)
+            throw new ConfigError(problems.join('; '));
+        // Secrets first: a key is never lost between the two writes.
+        writeSecrets(split.secrets);
+        writeFile({ ...current, ...nestCatalog(current) });
+        return load();
     }
-    // Validate what the file would become before writing it.
-    const problems = configProblems({ ...DEFAULTS, ...current, ...code });
-    if (problems.length) throw new Error(problems.join('; '));
-    writeFile(current);
-    return load();
-  }
-
-  // `frozen` may be set in code or in the file; code wins, like any key.
-  function isFrozen() {
-    if (code.frozen !== undefined) return Boolean(code.frozen);
-    try { return Boolean(readFile().frozen); } catch { return false; }
-  }
-  const lockedNow = () => (isFrozen() ? new Set([...locked, ...WRITABLE]) : locked);
-
-  const readMcp = () => {
-    if (codeServers) return JSON.stringify({ mcpServers: codeServers }, null, 2) + '\n';
-    if (!existsSync(mcpFile)) return JSON.stringify({ mcpServers: DEFAULT_MCP_SERVERS }, null, 2) + '\n';
-    return readFileSync(mcpFile, 'utf8');
-  };
-
-  return {
-    load,
-    save,
-    public: (cfg) => ({
-      ...publicConfig(cfg), lockedKeys: [...lockedNow()], mcpLocked: Boolean(codeServers) || isFrozen(),
-      keyClasses: Object.fromEntries([...WRITABLE, ...FILE_ONLY].map((k) => [k, keyClass(k, lockedNow())]))
-    }),
-    lockedKeys: () => new Set(lockedNow()),
-    /** The raw mcp.json (or code) server map, throwing on bad JSON -- for tooling that must not guess. */
-    strictMcpServers() {
-      const parsed = JSON.parse(readMcp());
-      return parsed.mcpServers || parsed;
-    },
-    /** Users pinned in code's access.users: admins cannot overrule these. */
-    codeAccessUsers: () => ({ ...(code.access?.users || {}) }),
-    /** Low-level access for the policy write-back: read and replace the JSON file. */
-    readFile,
-    writeFile,
-    path: () => file,
-    mcpPath: () => (codeServers ? null : mcpFile),
-    get mcpLocked() { return Boolean(codeServers) || isFrozen(); },
-    isFrozen,
-    dbPath: (cfg) => {
-      const set = opts.dbPath || process.env.TINYWEBUI_DB || cfg?.dbPath;
-      if (set === ':memory:') return set;
-      return set ? resolve(set) : resolve(dirname(file || CONFIG_FILE), 'tinywebui.db');
-    },
-    /** Raw text of mcp.json, so the editor round-trips comments-free but verbatim. */
-    readMcpFile: readMcp,
-    loadMcpServers() {
-      try {
-        const parsed = JSON.parse(readMcp());
-        // Accept both {"mcpServers": {...}} and a bare {...} map.
-        return parsed.mcpServers || parsed || {};
-      } catch (err) {
-        log.error(`${mcpFile} is not valid JSON: ${err.message}`);
-        return {};
-      }
-    },
-    /** Validates before writing, so a typo cannot leave an unparseable file behind. */
-    saveMcpFile(text) {
-      if (codeServers) throw new LockedError('MCP servers are set in code, not editable here');
-      if (isFrozen()) throw new LockedError('this deployment is frozen: change mcp.json instead');
-      const parsed = JSON.parse(text);
-      const servers = parsed.mcpServers || parsed;
-      for (const [name, spec] of Object.entries(servers)) {
-        if (!spec || (!spec.command && !spec.url)) {
-          throw new Error(`"${name}" needs either "command" (stdio) or "url" (http)`);
+    // `frozen` may be set in code or in the file; code wins, like any key.
+    function isFrozen() {
+        if (code.frozen !== undefined)
+            return Boolean(code.frozen);
+        try {
+            return Boolean(readFile().frozen);
         }
-      }
-      writeFileSync(mcpFile, text.endsWith('\n') ? text : text + '\n');
-      return servers;
-    },
-  };
+        catch {
+            return false;
+        }
+    }
+    const lockedNow = () => (isFrozen() ? new Set([...locked, ...WRITABLE]) : locked);
+    const readMcp = () => {
+        if (codeServers)
+            return JSON.stringify({ mcpServers: codeServers }, null, 2) + '\n';
+        if (!existsSync(mcpFile))
+            return JSON.stringify({ mcpServers: DEFAULT_MCP_SERVERS }, null, 2) + '\n';
+        return readFileSync(mcpFile, 'utf8');
+    };
+    return {
+        load,
+        save,
+        public: (cfg) => ({
+            ...publicConfig(cfg), lockedKeys: [...lockedNow()], mcpLocked: Boolean(codeServers) || isFrozen(),
+            keyClasses: Object.fromEntries([...WRITABLE, ...FILE_ONLY].map((k) => [k, keyClass(k, lockedNow())]))
+        }),
+        lockedKeys: () => new Set(lockedNow()),
+        /** The raw mcp.json (or code) server map, throwing on bad JSON -- for tooling that must not guess. */
+        strictMcpServers() {
+            const parsed = JSON.parse(readMcp());
+            return parsed.mcpServers || parsed;
+        },
+        /** Users pinned in code's access.users: admins cannot overrule these. */
+        codeAccessUsers: () => ({ ...(code.access?.users || {}) }),
+        /** Low-level access for the policy write-back: read and replace the JSON file. */
+        readFile,
+        writeFile,
+        path: () => file,
+        secretsPath: () => secretsFile,
+        /** Secret values the config file holds as written, by name (they move out on start). */
+        secretsInFile: () => extractSecrets(readFile()).names,
+        mcpPath: () => (codeServers ? null : mcpFile),
+        get mcpLocked() { return Boolean(codeServers) || isFrozen(); },
+        isFrozen,
+        dbPath: (cfg) => {
+            const set = opts.dbPath || process.env.TINYWEBUI_DB || cfg?.dbPath;
+            if (set === ':memory:')
+                return set;
+            return set ? resolve(set) : resolve(dirname(file || CONFIG_FILE), 'tinywebui.db');
+        },
+        /** Raw text of mcp.json, so the editor round-trips comments-free but verbatim. */
+        readMcpFile: readMcp,
+        loadMcpServers() {
+            try {
+                const parsed = JSON.parse(readMcp());
+                // Accept both {"mcpServers": {...}} and a bare {...} map.
+                return parsed.mcpServers || parsed || {};
+            }
+            catch (err) {
+                log.error(`${mcpFile} is not valid JSON: ${err.message}`);
+                return {};
+            }
+        },
+        /** Validates before writing, so a typo cannot leave an unparseable file behind. */
+        saveMcpFile(text) {
+            if (codeServers)
+                throw new LockedError('MCP servers are set in code, not editable here');
+            if (isFrozen())
+                throw new LockedError('this deployment is frozen: change mcp.json instead');
+            const parsed = JSON.parse(text);
+            const servers = parsed.mcpServers || parsed;
+            for (const [name, spec] of Object.entries(servers)) {
+                if (!spec || (!spec.command && !spec.url)) {
+                    throw new Error(`"${name}" needs either "command" (stdio) or "url" (http)`);
+                }
+            }
+            // Headers and env here can hold tokens: owner-only, like the config.
+            if (existsSync(mcpFile) && process.platform !== 'win32')
+                chmodSync(mcpFile, 0o600);
+            writeFileSync(mcpFile, text.endsWith('\n') ? text : text + '\n', { mode: 0o600 });
+            return servers;
+        },
+    };
+}
+export class LockedError extends Error {
+}
+/** A save that would leave the config invalid: the caller's mistake, not the server's. */
+export class ConfigError extends Error {
 }
-
-export class LockedError extends Error {}
-
 // Keys that are not in DEFAULTS but are still settings.
 const EXTRA_KEYS = new Set(['access']);
 const ENUMS = {
-  authMode: ['none', 'single', 'multiuser', 'trusted-header'],
-  cacheTtl: ['5m', '1h'],
-  cacheMode: ['auto', 'implicit', 'explicit', 'rolling', 'off'],
-  reasoningReplay: REASONING_REPLAY,
-  toolApproval: ['writes', 'all', 'off'],
+    authMode: ['local', 'multiuser', 'trusted-header'],
+    cacheTtl: ['5m', '1h'],
+    cacheMode: ['auto', 'implicit', 'explicit', 'rolling', 'off'],
+    reasoningReplay: REASONING_REPLAY,
+    toolApproval: ['writes', 'all', 'off'],
 };
 const kind = (v) => (v === null ? 'null' : Array.isArray(v) ? 'array' : typeof v);
-
 /**
  * Every problem with a loaded config: unknown keys (usually typos), values of
  * the wrong type or outside their allowed set, plus the policy checks in
@@ -394,125 +482,129 @@ const kind = (v) => (v === null ? 'null' : Array.isArray(v) ? 'array' : typeof v
  * a config with any.
  */
 function retrievalProblems(r) {
-  if (!r || typeof r !== 'object' || Array.isArray(r)) return ['retrieval must be an object'];
-  const out = [];
-  for (const k of Object.keys(r)) if (!(k in DEFAULTS.retrieval)) out.push(`unknown setting "retrieval.${k}"`);
-  if (r.mode !== undefined && !['auto', 'lexical', 'dense', 'hybrid'].includes(r.mode)) out.push('retrieval.mode must be one of auto, lexical, dense, hybrid');
-  for (const k of ['model', 'modelDir', 'modelSha256', 'queryPrefix', 'documentPrefix']) {
-    if (r[k] !== undefined && typeof r[k] !== 'string') out.push(`retrieval.${k} must be a string`);
-  }
-  if (r.modelSha256 && !/^[0-9a-fA-F]{64}$/.test(r.modelSha256)) out.push('retrieval.modelSha256 must be a 64-character hex sha256');
-  if (r.denseWeight !== undefined && !(typeof r.denseWeight === 'number' && r.denseWeight > 0 && r.denseWeight < 1)) {
-    out.push('retrieval.denseWeight must be a number between 0 and 1 (exclusive); use mode "dense" or "lexical" for the extremes');
-  }
-  if (r.rrfK !== undefined && !(Number.isInteger(r.rrfK) && r.rrfK >= 0)) out.push('retrieval.rrfK must be a whole number >= 0');
-  const size = r.passageSize ?? DEFAULTS.retrieval.passageSize;
-  if (!(Number.isInteger(size) && size >= 200 && size <= 20000)) out.push('retrieval.passageSize must be a whole number of characters from 200 to 20000');
-  if (r.passageOverlap !== undefined && !(Number.isInteger(r.passageOverlap) && r.passageOverlap >= 0 && r.passageOverlap < size / 2)) {
-    out.push('retrieval.passageOverlap must be a whole number >= 0 and under half of passageSize');
-  }
-  if (r.chunkOverlap !== undefined && !(Number.isInteger(r.chunkOverlap) && r.chunkOverlap >= 0 && r.chunkOverlap <= 128)) {
-    out.push('retrieval.chunkOverlap must be a whole number of tokens from 0 to 128');
-  }
-  return out;
-}
-
-export function configProblems(cfg) {
-  const problems = [];
-  for (const [key, value] of Object.entries(cfg)) {
-    if (!(key in DEFAULTS) && !EXTRA_KEYS.has(key)) { problems.push(`unknown setting "${key}"`); continue; }
-    if (ENUMS[key]) {
-      if (!ENUMS[key].includes(value)) problems.push(`${key} must be one of ${ENUMS[key].join(', ')} (got ${JSON.stringify(value)})`);
-      continue;
+    if (!r || typeof r !== 'object' || Array.isArray(r))
+        return ['retrieval must be an object'];
+    const out = [];
+    for (const k of Object.keys(r))
+        if (!(k in DEFAULTS.retrieval))
+            out.push(`unknown setting "retrieval.${k}"`);
+    if (r.mode !== undefined && !['auto', 'lexical', 'dense', 'hybrid'].includes(r.mode))
+        out.push('retrieval.mode must be one of auto, lexical, dense, hybrid');
+    for (const k of ['model', 'modelDir', 'modelSha256', 'queryPrefix', 'documentPrefix']) {
+        if (r[k] !== undefined && typeof r[k] !== 'string')
+            out.push(`retrieval.${k} must be a string`);
     }
-    if (key === 'models' || key === 'connectors') continue; // modelProblems/connectorProblems, below, know the shape
-    if (key === 'retrieval') {
-      problems.push(...retrievalProblems(value));
-      continue;
+    if (r.modelSha256 && !/^[0-9a-fA-F]{64}$/.test(r.modelSha256))
+        out.push('retrieval.modelSha256 must be a 64-character hex sha256');
+    if (r.denseWeight !== undefined && !(typeof r.denseWeight === 'number' && r.denseWeight > 0 && r.denseWeight < 1)) {
+        out.push('retrieval.denseWeight must be a number between 0 and 1 (exclusive); use mode "dense" or "lexical" for the extremes');
     }
-    if (key === 'frozen' || key === 'autoMigrate') {
-      if (typeof value !== 'boolean') problems.push(`${key} must be true or false`);
-      continue;
+    if (r.rrfK !== undefined && !(Number.isInteger(r.rrfK) && r.rrfK >= 0))
+        out.push('retrieval.rrfK must be a whole number >= 0');
+    const size = r.passageSize ?? DEFAULTS.retrieval.passageSize;
+    if (!(Number.isInteger(size) && size >= 200 && size <= 20000))
+        out.push('retrieval.passageSize must be a whole number of characters from 200 to 20000');
+    if (r.passageOverlap !== undefined && !(Number.isInteger(r.passageOverlap) && r.passageOverlap >= 0 && r.passageOverlap < size / 2)) {
+        out.push('retrieval.passageOverlap must be a whole number >= 0 and under half of passageSize');
     }
-    if (!(key in DEFAULTS)) continue;
-    if (key === 'compactionMaxTokens') {
-      if (!(Number.isInteger(value) && value >= 256)) problems.push('compactionMaxTokens must be a whole number >= 256');
-      continue;
+    if (r.chunkOverlap !== undefined && !(Number.isInteger(r.chunkOverlap) && r.chunkOverlap >= 0 && r.chunkOverlap <= 128)) {
+        out.push('retrieval.chunkOverlap must be a whole number of tokens from 0 to 128');
     }
-    if (key === 'askUserTimeoutSeconds') {
-      if (!(Number.isInteger(value) && value >= 0)) problems.push('askUserTimeoutSeconds must be a whole number of seconds >= 0 (0: no timeout)');
-      continue;
+    return out;
+}
+export function configProblems(raw) {
+    const cfg = { ...raw, ...flattenCatalog(raw) };
+    const problems = [];
+    for (const [key, value] of Object.entries(cfg)) {
+        if (!(key in DEFAULTS) && !EXTRA_KEYS.has(key)) {
+            problems.push(`unknown setting "${key}"`);
+            continue;
+        }
+        if (ENUMS[key]) {
+            if (!ENUMS[key].includes(value))
+                problems.push(`${key} must be one of ${ENUMS[key].join(', ')} (got ${JSON.stringify(value)})`);
+            continue;
+        }
+        if (key === 'models' || key === 'connectors')
+            continue; // modelProblems/connectorProblems, below, know the shape
+        if (key === 'retrieval') {
+            problems.push(...retrievalProblems(value));
+            continue;
+        }
+        if (key === 'frozen' || key === 'autoMigrate') {
+            if (typeof value !== 'boolean')
+                problems.push(`${key} must be true or false`);
+            continue;
+        }
+        if (!(key in DEFAULTS))
+            continue;
+        if (key === 'compactionMaxTokens') {
+            if (!(Number.isInteger(value) && value >= 256))
+                problems.push('compactionMaxTokens must be a whole number >= 256');
+            continue;
+        }
+        if (key === 'askUserTimeoutSeconds') {
+            if (!(Number.isInteger(value) && value >= 0))
+                problems.push('askUserTimeoutSeconds must be a whole number of seconds >= 0 (0: no timeout)');
+            continue;
+        }
+        const want = kind(DEFAULTS[key]);
+        const got = kind(value);
+        // A null default is an optional number (temperature, maxTokens).
+        const ok = want === 'null' ? got === 'null' || (got === 'number' && Number.isFinite(value))
+            : want === 'number' ? got === 'number' && Number.isFinite(value)
+                : got === want;
+        if (!ok)
+            problems.push(`${key} must be ${want === 'null' ? 'a number or null' : `a${want === 'array' || want === 'object' ? 'n' : ''} ${want}`} (got ${got})`);
     }
-    const want = kind(DEFAULTS[key]);
-    const got = kind(value);
-    // A null default is an optional number (temperature, maxTokens).
-    const ok = want === 'null' ? got === 'null' || (got === 'number' && Number.isFinite(value))
-      : want === 'number' ? got === 'number' && Number.isFinite(value)
-      : got === want;
-    if (!ok) problems.push(`${key} must be ${want === 'null' ? 'a number or null' : `a${want === 'array' || want === 'object' ? 'n' : ''} ${want}`} (got ${got})`);
-  }
-  return [...problems, ...connectorProblems(cfg), ...modelProblems(cfg), ...validateConfig(cfg)];
+    return [...problems, ...connectorProblems(cfg), ...modelProblems(cfg), ...validateConfig(cfg), ...refProblems(cfg)];
 }
-
 // Only the knobs the UI is allowed to change. Secrets stay server-side.
 export const WRITABLE = new Set([
-  'model', 'systemPrompt', 'temperature', 'maxTokens', 'maxToolRounds', 'askUserTimeoutSeconds',
-  'cacheTtl', 'cacheMode', 'compactThreshold', 'keepTurns', 'maxInlineChars',
-  'compactMinSaved', 'maxTurnChars', 'maxHistoryTokens', 'timezone',
-  'toolApproval', 'confirmTools', 'autoApproveTools', 'disabledTools',
-  // The deployment's endpoints and catalog: only the sole user or an admin may
-  // send these (see SECRET_PATCH_KEYS in policy.js); keys are write-only.
-  'baseUrl', 'apiKey', 'models', 'connectors',
-  'llmCompaction', 'compactionMaxTokens', 'expandCharBudget', 'cache', 'reasoningReplay', 'extraBody'
+    'model', 'systemPrompt', 'temperature', 'maxTokens', 'maxToolRounds', 'askUserTimeoutSeconds',
+    'cacheTtl', 'cacheMode', 'compactThreshold', 'keepTurns', 'maxInlineChars',
+    'compactMinSaved', 'maxTurnChars', 'maxHistoryTokens', 'timezone',
+    'toolApproval', 'confirmTools', 'autoApproveTools', 'disabledTools',
+    // The deployment's endpoints and catalog: only the sole user or an admin may
+    // send these (see SECRET_PATCH_KEYS in policy.js); keys are write-only.
+    'baseUrl', 'apiKey', 'models', 'connectors',
+    'llmCompaction', 'compactionMaxTokens', 'expandCharBudget', 'cache', 'reasoningReplay', 'extraBody'
 ]);
-
 // A short tail is enough to tell two keys apart in a list; short keys show none.
 const keyHint = (key) => (key && key.length >= 12 ? key.slice(-4) : null);
-
 /**
  * API keys are write-only: the page learns that one is set (and its last four
- * characters), never the value. On save, a connector sent without `apiKey`
- * keeps its stored key; `apiKey: null` clears it.
+ * characters), never the value. Where a save puts them is takeSecrets() in
+ * secrets.ts.
  */
-export function mergeSecrets(patch, current) {
-  const out = { ...patch };
-  if ('apiKey' in out && (out.apiKey === undefined || out.apiKey === '')) delete out.apiKey;
-  else if (out.apiKey === null) out.apiKey = '';
-  if (Array.isArray(out.connectors)) {
-    const old = new Map((Array.isArray(current.connectors) ? current.connectors : []).map((c) => [c?.id, c]));
-    out.connectors = out.connectors.map((c) => {
-      if (!c || typeof c !== 'object') return c;
-      const { apiKey, ...rest } = c;
-      if (apiKey === null) return { ...rest, apiKey: '' };
-      if (apiKey === undefined || apiKey === '') return old.get(c.id)?.apiKey ? { ...rest, apiKey: old.get(c.id).apiKey } : rest;
-      return c;
-    });
-  }
-  return out;
-}
-
 /** The patch as it may be logged: secret values replaced by whether they were set. */
 export function redactSecrets(patch) {
-  const out = { ...patch };
-  if ('apiKey' in out) out.apiKey = Boolean(out.apiKey);
-  if (Array.isArray(out.connectors)) {
-    out.connectors = out.connectors.map((c) => (c && typeof c === 'object' && 'apiKey' in c ? { ...c, apiKey: Boolean(c.apiKey) } : c));
-  }
-  return out;
+    const out = { ...patch };
+    if ('apiKey' in out)
+        out.apiKey = Boolean(out.apiKey);
+    if (Array.isArray(out.connectors)) {
+        out.connectors = out.connectors.map((c) => (c && typeof c === 'object' && 'apiKey' in c ? { ...c, apiKey: Boolean(c.apiKey) } : c));
+    }
+    return out;
 }
-
 export function publicConfig(cfg) {
-  const { apiKey, authPassword, sessionSecret, googleClientSecret, connectors, ...rest } = cfg;
-  return {
-    ...rest,
-    connectors: (Array.isArray(connectors) ? connectors : []).map(({ apiKey: key, ...c }) => ({ ...c, hasApiKey: Boolean(key), keyHint: keyHint(key) })),
-    keyHint: keyHint(apiKey),
-    modelLabel: labelFor(cfg, cfg.model),
-    hasApiKey: Boolean(apiKey),
-    hasGoogleAuth: Boolean(cfg.googleClientId),
-  };
+    const { apiKey, authPassword, sessionSecret, googleClientSecret, connectors, ...rest } = cfg;
+    return {
+        ...rest,
+        connectors: (Array.isArray(connectors) ? connectors : []).map(({ apiKey: key, ...c }) => ({ ...c, hasApiKey: Boolean(key), keyHint: keyHint(key) })),
+        keyHint: keyHint(apiKey),
+        modelLabel: labelFor(cfg, cfg.model),
+        hasApiKey: Boolean(apiKey),
+        // Whether the default model's turns have an endpoint to go to.
+        ready: hasEndpoint(cfg),
+        // Whether the top-level endpoint serves anything, so the page shows it:
+        // a URL, a key, or a model naming no connector. Otherwise the page offers
+        // connectors only.
+        usesDefaultEndpoint: Boolean(cfg.baseUrl) || Boolean(apiKey)
+            || (Array.isArray(cfg.models) && cfg.models.some((m) => !m.connector)),
+        hasGoogleAuth: Boolean(cfg.googleClientId),
+    };
 }
-
 // The file-driven instance the CLI has always used, kept as plain functions.
 const fileSource = createConfigSource();
 export const configPath = () => fileSource.path();