@tiens.nguyen/gu-cli 1.0.780 → 1.0.781

package/gonext_agent_chat.py

@@ -28,6 +28,7 @@ import json
 import os
 import random
 import re
+from urllib.parse import urlparse
 import sys
 import threading
 import time
@@ -7506,6 +7507,31 @@ def _prepare_image(path):
     return im
 
 
+# WHICH CODERS MAY BE SENT IMAGES (#284, #316) — the SAME list the CLI gates Ctrl+V with
+# (image-capable-coders.json, beside this file), so the two can never disagree. A server/model is
+# added there only after a real request with an image came back right.
+def _image_coders():
+    # GU_IMAGE_CODERS_FILE: tests only — a stand-in coder on 127.0.0.1 is put on the list there.
+    path = os.environ.get("GU_IMAGE_CODERS_FILE") or os.path.join(
+        os.path.dirname(os.path.abspath(__file__)), "image-capable-coders.json")
+    try:
+        with open(path, encoding="utf-8") as f:
+            return json.load(f).get("coders") or []
+    except Exception:  # noqa: BLE001
+        # No list → the one coder that has always taken images, rather than none or all.
+        return [{"host": "api.anthropic.com"}]
+
+
+def _coder_takes_images(url, model, coders=None):
+    """May the question's pasted images be sent to this coding server + model?"""
+    host = (urlparse(url or "").hostname or "").lower().rstrip(".")
+    name = str(model or "").split("::")[-1].strip()
+    for c in (coders if coders is not None else _image_coders()):
+        if c.get("host") == host and (not c.get("model") or re.search(c["model"], name, re.I)):
+            return True
+    return False
+
+
 def _load_turn_images(refs):
     """[(label, path)] → (PIL images ready for Claude, [(label, reason)] for the ones that failed)."""
     out, failed = [], []
@@ -13252,14 +13278,20 @@ def run_agent_chat(cfg):
                     _RAG_STATE["s"] = "no-index"
             except Exception:  # noqa: BLE001
                 pass
-        # The question's pasted images (task #284): a Claude coder sees them; any other coder is
-        # told they were not sent rather than left to guess from a bare "[Image #1]".
+        # The question's pasted images (task #284, #316): a coder on the shared image list (Claude,
+        # Kimi K3 on Moonshot / Ollama cloud) sees them; any other coder is told they were not sent
+        # rather than left to guess from a bare "[Image #1]".
         _turn_images = []
         if _turn_image_refs:
-            if _is_anthropic_url(coding_base_url):
+            # The Anthropic check stays first: it is THE test of "this is Claude's native API" the
+            # rest of the file uses (and the one test launchers point at a local stand-in).
+            if _is_anthropic_url(coding_base_url) or _coder_takes_images(coding_base_url, coding_model_id):
                 _turn_images, _img_failed = _load_turn_images(_turn_image_refs)
                 task_with_hint = _label_failed_images(task_with_hint, _img_failed)
-                _log(f"attached {len(_turn_images)} image(s) to the question"
+                # Content-free (#248): how many, and their sizes — never the pixels or the path.
+                _log(f"attached {len(_turn_images)} image(s) to the question for "
+                     f"{(urlparse(coding_base_url or '').hostname or '?')} / {coding_model_id}"
+                     + ("" if not _turn_images else " — " + ", ".join(f"{im.width}x{im.height}" for im in _turn_images))
                      + (f", {len(_img_failed)} could not be opened" if _img_failed else ""))
                 for _lbl, _why in _img_failed:
                     _emit({"type": "step", "text": f"⚠ {_lbl} not sent — {_why}"})

package/gu-repl.mjs

@@ -26,7 +26,7 @@
 import { readFile, mkdir, writeFile, unlink, rename } from "node:fs/promises";
 import { readStepTokens } from "./step-tokens.mjs";
 import { snapshotInput, restoreInput, replaceStoppedQuestion, stopNoteLines } from "./turn-stop.mjs";
-import { existsSync, statSync, readFileSync, writeFileSync, readdirSync, openSync, readSync, closeSync } from "node:fs";
+import { existsSync, statSync, readFileSync, writeFileSync, readdirSync, openSync, readSync, closeSync, mkdirSync } from "node:fs";
 import { spawn } from "node:child_process";
 // FIRST, before anything that could itself fail on an old runtime: npm only WARNS about
 // `engines`, so an unsupported Node installs fine and then breaks somewhere unrelated.
@@ -133,7 +133,7 @@ import { unapprovedProjectServers } from "./mcp-command.mjs";
 import { readHooks } from "./hooks-config.mjs";
 import { codingBannerLabel, isOllamaCloudUrl, SECRET_KEY_HINT } from "./coding-key-prompt.mjs";
 import { codingChoiceTags, coderDisplayName, coderWhere, whereOfActiveCoder } from "./coding-choice-tags.mjs";
-import { IMAGE_NEEDS_CLAUDE, clipboardImageToFile, fitImageNotice, imageMarkersForDisplay, createImageStore, imagePasteKey, imagePathFromPaste, isClaudeCoderUrl, isImagePasteKey, storeImageFile } from "./image-paste.mjs";
+import { IMAGE_NEEDS_CLAUDE, coderTakesImagesFor, clipboardImageToFile, fitImageNotice, imageMarkersForDisplay, createImageStore, imagePasteKey, imagePathFromPaste, isClaudeCoderUrl, isImagePasteKey, storeImageFile } from "./image-paste.mjs";
 import {
   isDoubleClick,
   clickRun,
@@ -1613,7 +1613,8 @@ function showImageNotice(text) {
   if (barPinned()) paintBar();
 }
 /** Images go to the coding model; only a Claude coder takes them for now. */
-const coderTakesImages = () => isClaudeCoderUrl(sessionCodingUrl || defaultCodingUrl);
+// #316: Claude, and Kimi K3 on a server verified to take images — one list, shared with the agent.
+const coderTakesImages = () => coderTakesImagesFor(sessionCodingUrl || defaultCodingUrl, sessionCodingModel || defaultCodingModel);
 function insertAtCaret(text) {
   dropSelectedInputText();
   const before = rl.line.slice(0, rl.cursor);
@@ -6833,12 +6834,56 @@ function withTerminalHandedOver(run) {
  * the API key by design (unlike /save-settings) — stored 0600 in the home folder, marked
  * "gu": "preset" so the two commands never offer each other's files.
  */
+/**
+ * THIS ACCOUNT'S WHOLE SETUP as a version-2 preset (#320): every coding server and its models, the
+ * default coder, the agent, the embedder — and each server's API key, read through the local API the
+ * way the worker is handed one (GET /api/worker/coding-key?backendId). The keys stay in memory and in
+ * the 0600 file; nothing prints them. → the preset, or null when the settings cannot be read.
+ */
+async function buildFullPresetNow(name) {
+  return (await import("./preset-apply.mjs")).buildFullPresetFrom(replPresetApi(), { name, host: hostname() });
+}
+
+/** The local API, as preset-apply.mjs talks to it (#320) — the same calls the rest of the REPL makes. */
+function replPresetApi() {
+  return {
+    settings: () => fetchWorkerSettings(),
+    keys: () => fetchCodingKeys(),
+    keyFor: (backendId) => fetchKeyForBackend(backendId),
+    saveSettings: async (patch) => (await import("./model-doctor.mjs")).saveWorkerSettings(apiBase, workerKey, patch),
+    addKey: (name, key, rowId) => addCodingKey(name, key, rowId),
+    setDefaultKey: (rowId, keyId) => setServerDefaultKey(rowId, keyId),
+  };
+}
+const replPresetIo = {
+  ask: (q) => ask("  " + q),
+  say: (line, tone) =>
+    console.log(GUTTER + (tone === "err" ? red : tone === "warn" ? yellow : tone === "ok" ? accent : dim)("  " + line)),
+};
+
+/** The key a server would be handed ({ apiKey, keyId }), or null. Never logged. */
+async function fetchKeyForBackend(backendId) {
+  try {
+    const r = await fetch(`${apiBase}/api/worker/coding-key?backendId=${encodeURIComponent(backendId)}`, {
+      headers: { "X-Worker-Key": workerKey },
+      signal: AbortSignal.timeout(API_CALL_TIMEOUT_MS),
+    });
+    if (!r.ok) return null;
+    const j = await r.json().catch(() => null);
+    return typeof j?.apiKey === "string" && j.apiKey ? j : null;
+  } catch {
+    return null;
+  }
+}
+
 async function runSavePresetCommand(line) {
   const pr = await import("./presets-transfer.mjs");
   const home = homedir();
   console.log("");
-  const usage = "usage: /save-preset <name>  (opens your editor)   or   /save-preset <name> {\"apiUrl\":\"…\",\"apiKey\":\"…\",\"agentModel\":\"…\",\"codingModel\":\"…\",\"embedModel\":\"…\"}";
-  let rest = line.trim().slice("/save-preset".length).trim().replace(/(^|\s)--edit(?=\s|$)/, " ").trim();
+  const usage = "usage: /save-preset <name>  (saves your whole setup)  ·  /save-preset <name> --edit  (in your editor)  ·  /save-preset <name> {json}";
+  const raw = line.trim().slice("/save-preset".length).trim();
+  const wantsEdit = /(^|\s)--edit(?=\s|$)/.test(raw);
+  let rest = raw.replace(/(^|\s)--edit(?=\s|$)/, " ").trim();
   if (!rest) {
     const typed = String((await ask("preset name: ")) ?? "").trim();
     if (!typed) {
@@ -6862,19 +6907,47 @@ async function runSavePresetCommand(line) {
     console.log(GUTTER + dim("server + api key + agent, coding and embedding models — the key is IN this file, keep it private."));
     console.log("");
   };
+  // A WHOLE-SETUP preset (#320): written as given (dated, named), then summarised — keys masked.
+  const storeFull = (doc) => {
+    const out = { ...doc, gu: "preset", version: pr.FULL_PRESET_VERSION, name, savedAt: new Date().toISOString(), savedOn: hostname(),
+      note: "The whole setup: every coding server and its models, the default coder, the agent and the embedder — and each server's API key. This file CONTAINS live API keys." };
+    writeFileSync(file, JSON.stringify(out, null, 2) + "\n", { mode: 0o600 });
+    const v = pr.validatePresetFile(JSON.stringify(out));
+    console.log(GUTTER + `Preset "${name}" saved to ${file} — your whole setup:`);
+    if (v.ok && v.full) for (const l of pr.fullPresetSummary(v.value, v.codingDefault)) console.log(GUTTER + dim(l));
+    console.log(GUTTER + dim("It CONTAINS your API keys — keep it private. /load-presets → v to view it, c to copy it for another machine."));
+    console.log("");
+  };
+  const ed = await import("./preset-editor.mjs");
   if (json) {
-    const checked = pr.validatePreset(json);
+    const checked = ed.parseEdited(json);
     if (!checked.ok) {
       console.log(GUTTER + `Preset not saved — ${checked.problem}`);
       console.log("");
       return;
     }
-    store(checked.preset);
+    if (checked.full) storeFull(checked.doc);
+    else store(checked.preset);
     return;
   }
 
-  // THE EDITOR. Filled in from the preset being edited, else from what this account runs now.
-  const ed = await import("./preset-editor.mjs");
+  // THE WHOLE SETUP, NOW (#320): every server, its models and key, the defaults — saved without an
+  // editor, because "as it is now" is what a person saving their setup means. --edit opens it first.
+  if (!wantsEdit) {
+    if (existsSync(file) && !(await askYesNo(`A preset called "${name}" exists — replace it with the setup you have now?`, false))) {
+      console.log(GUTTER + dim("Not saved.") + "\n");
+      return;
+    }
+    const doc = await withPendingStatus("reading your servers, models and keys", () => buildFullPresetNow(name));
+    if (!doc) {
+      console.log(GUTTER + red(`couldn't read your settings from ${apiBase} — nothing was saved.`) + "\n");
+      return;
+    }
+    storeFull(doc);
+    return;
+  }
+
+  // THE EDITOR. Filled in from the preset being edited, else from the whole setup this account has now.
   const editor = ed.pickEditor();
   if (!editor || !process.stdin.isTTY) {
     console.log(GUTTER + (editor ? "an editor needs a terminal — " : "no editor found (set $EDITOR, e.g. export EDITOR=nano) — ") + usage);
@@ -6890,7 +6963,7 @@ async function runSavePresetCommand(line) {
       /* unreadable — start from the current setup instead */
     }
   }
-  if (!start) start = ed.presetFromSettings((await fetchWorkerSettings()) ?? {});
+  if (!start) start = (await buildFullPresetNow(name)) ?? ed.presetFromSettings((await fetchWorkerSettings()) ?? {});
   const initial = ed.editorText(name, start);
   console.log(GUTTER + dim(`${start.gu ? "editing" : "new"} preset "${name}" in ${basename(editor.cmd)} — save and quit to store it, quit without changes to cancel.`));
   let text = initial;
@@ -6907,7 +6980,8 @@ async function runSavePresetCommand(line) {
     }
     const parsed = ed.parseEdited(r.text);
     if (parsed.ok) {
-      store(parsed.preset);
+      if (parsed.full) storeFull(parsed.doc);
+      else store(parsed.preset);
       return;
     }
     console.log(GUTTER + yellow(`Not saved yet — ${parsed.problem}`));
@@ -7070,7 +7144,11 @@ async function presetFromPaste(pr, home) {
     if (!name) return "";
     const file = pr.presetFilePath(name, home);
     if (existsSync(file) && !(await askYesNo(`A preset called "${name}" exists — replace it?`, false))) return "";
-    writeFileSync(file, JSON.stringify(pr.buildPreset({ name, preset: parsed.preset, host: hostname() }), null, 2) + "\n", { mode: 0o600 });
+    // A whole-setup preset (#320) is kept as it is — every server, key and default — named and dated.
+    const out = parsed.full
+      ? { ...parsed.doc, gu: "preset", version: pr.FULL_PRESET_VERSION, name, savedAt: new Date().toISOString(), savedOn: hostname() }
+      : pr.buildPreset({ name, preset: parsed.preset, host: hostname() });
+    writeFileSync(file, JSON.stringify(out, null, 2) + "\n", { mode: 0o600 });
     console.log(GUTTER + `Preset "${name}" saved to ${file}`);
     return file;
   } catch (e) {
@@ -7176,9 +7254,11 @@ async function runLoadPresetsCommand(line) {
           return;
         }
         const pname = shown.name || found[pick.index];
-        const command = ed.presetCopyCommand(pname, shown.preset);
+        // A whole-setup preset (#320) is shown and copied AS SAVED — every server, every key.
+        const body = shown.full ? JSON.parse(readFileSync(file, "utf8")) : shown.preset;
+        const command = ed.presetCopyCommand(pname, body);
         if (pick.action === "view") {
-          const block = ed.presetBlock(pname, shown.preset, { width: process.stdout.columns || 80, gutter: GUTTER });
+          const block = ed.presetBlock(pname, body, { width: process.stdout.columns || 80, gutter: GUTTER });
           const [top, ...restRows] = block.rows;
           const cut = block.button.from;
           console.log(dim(top.slice(0, cut)) + accent(top.slice(cut, block.button.to)) + dim(top.slice(block.button.to)));
@@ -7189,7 +7269,7 @@ async function runLoadPresetsCommand(line) {
           console.log("");
           return;
         }
-        const res = await writeClipboard(pick.action === "json" ? ed.presetCopyJson(shown.preset) : command);
+        const res = await writeClipboard(pick.action === "json" ? ed.presetCopyJson(body) : command);
         console.log(
           GUTTER +
             (res.ok
@@ -7202,6 +7282,17 @@ async function runLoadPresetsCommand(line) {
     }
   }
   const checked = pr.validatePresetFile(readFileSync(file, "utf8"));
+  if (checked.ok && checked.full) {
+    const pname = checked.name || basename(file).replace(/\.json$/i, "");
+    await applyTransferDoc(checked.value, {
+      fromLine: `preset "${pname}" from ${file}${checked.savedOn ? ` (saved on ${checked.savedOn})` : ""} — the whole setup:`,
+      summary: pr.fullPresetSummary(checked.value, checked.codingDefault),
+      codingDefault: checked.codingDefault,
+      warnings: checked.warnings,
+      backupName: pname,
+    });
+    return;
+  }
   if (!checked.ok) {
     console.log(GUTTER + `Not loaded — ${checked.problem}`);
     console.log("");
@@ -7347,58 +7438,29 @@ async function runLoadSettingsCommand(line) {
     console.log(GUTTER + dim(`  file: ${file}\n`));
     return;
   }
-  const current = await withPendingStatus("reading your model settings", fetchWorkerSettings);
-  if (!current) {
-    console.log(GUTTER + red(`  couldn't reach the API at ${apiBase} — nothing was changed.\n`));
-    return;
-  }
-  const keys = (await fetchCodingKeys()) ?? [];
-  const plan = st.planLoad(parsed.value, { ...current, keys });
-  console.log(GUTTER + dim(`  from ${file}${parsed.value.savedOn ? ` (saved on ${parsed.value.savedOn})` : ""}`));
-  for (const l of plan.lines) console.log(GUTTER + dim("  " + l));
-  if (parsed.carriesSecrets) {
-    console.log(GUTTER + yellow("  this file contains API keys in plain text — delete it when you are done."));
-  }
-  console.log("");
-  const go = (await ask("  apply this? [y/N] ")).trim().toLowerCase();
-  if (go !== "y" && go !== "yes") {
-    console.log(GUTTER + dim("  nothing changed.\n"));
-    return;
-  }
-  const md = await import("./model-doctor.mjs");
-  // `current` so a provider this account already has keeps its row id — see toSettingsPatch.
-  const patch = st.toSettingsPatch(parsed.value, current);
-  const saved = Object.keys(patch).length
-    ? await md.saveWorkerSettings(apiBase, workerKey, patch)
-    : true;
-  if (!saved) {
-    console.log(GUTTER + red("  the API refused the settings — nothing was changed.\n"));
-    return;
-  }
-  console.log(GUTTER + accent(`  applied: ${plan.adds} provider${plan.adds === 1 ? "" : "s"}${patch.ragEmbedUrl || patch.ragEmbedModel ? ", the embedding model" : ""}.`));
+  await applyTransferDoc(parsed.value, {
+    fromLine: `from ${file}${parsed.value.savedOn ? ` (saved on ${parsed.value.savedOn})` : ""}`,
+    carriesSecrets: parsed.carriesSecrets,
+  });
+}
 
-  // THE KEYS, AFTER the settings — each needs the row it belongs to, and the rows only exist
-  // once the API has minted their ids.
-  const fresh = (await fetchWorkerSettings()) ?? {};
-  const ps = await import("./coding-provider-setup.mjs");
-  const rows = ps.existingBackendRows(fresh);
-  // One server however it is spelled (task #245) — a raw compare missed "…/v1" and saved the key
-  // tied to NO server, where it can never be used.
-  const rowIdForUrl = (url) => ps.providerRowForUrl(rows, url)?.id ?? "";
-  for (const k of plan.missingKeys) {
-    const where = k.backendUrl ? ` for ${k.backendUrl}` : "";
-    const typed = k.key || (await ask(`  key "${k.name}"${k.tail ? ` (…${k.tail})` : ""}${where} — paste it, or Enter to skip: `)).trim();
-    if (!typed) {
-      console.log(GUTTER + dim(`  skipped ${k.name} — add it later with ctrl+k.`));
-      continue;
-    }
-    const rowId = k.backendUrl ? rowIdForUrl(k.backendUrl) : "";
-    const id = await addCodingKey(k.name, typed, rowId);
-    console.log(GUTTER + (id ? accent(`  added ${k.name}.`) : red(`  could not add ${k.name}.`)));
-    // The key that was its server's DEFAULT on the saving machine is the default here too.
-    if (id && rowId && k.default) await setServerDefaultKey(rowId, id);
-  }
-  console.log(GUTTER + dim("  pick a coding model with /model.\n"));
+/**
+ * APPLY A SETTINGS DOCUMENT — /load-settings, and since #320 a whole-setup preset. One path, so a
+ * preset gets exactly the guarantees the settings file earned: a server this account already has
+ * keeps its row id (keys stay bound), each key lands on its own server, and the key that was its
+ * server's default is the default here. A preset's keys carry their VALUES, so nothing is asked;
+ * a settings file's keys do not, so each missing one is asked for. `codingDefault` (a preset) is
+ * restored last, once its server's row exists.
+ */
+async function applyTransferDoc(value, opts = {}) {
+  const pa = await import("./preset-apply.mjs");
+  return pa.applyTransfer(value, {
+    ...opts,
+    api: replPresetApi(),
+    io: replPresetIo,
+    backupDir: join(homedir(), ".gonext", "preset-backups"),
+    host: hostname(),
+  });
 }
 
 /** The .json files directly in a folder, with enough of each to recognise a settings file. */

package/image-capable-coders.json

@@ -0,0 +1,9 @@
+{
+  "note": "Which coding models may be SENT pasted images (#284, #316). ONE list, read by the CLI (image-paste.mjs) and the agent (gonext_agent_chat.py) so the two can never disagree. Add a server/model ONLY after a real request with an image came back right (see #316's probe). host = the server's hostname exactly; model = a case-insensitive regular expression on the model name, or omitted for every model on that host.",
+  "coders": [
+    { "host": "api.anthropic.com", "why": "Claude — #284" },
+    { "host": "api.moonshot.ai", "model": "^kimi-k3(\\b|:|$)", "why": "Kimi K3 on Moonshot — verified 2026-09-30: answered 'Red circle' for a test PNG" },
+    { "host": "api.moonshot.cn", "model": "^kimi-k3(\\b|:|$)", "why": "Moonshot's China endpoint, same API as .ai" },
+    { "host": "ollama.com", "model": "^kimi-k3(\\b|:|$)", "why": "Kimi K3 on Ollama cloud — verified 2026-09-30: answered 'Red circle.' for a test PNG" }
+  ]
+}

package/image-paste.mjs

@@ -1,3 +1,4 @@
+import { readFileSync } from "node:fs";
 /**
  * Pasting an image into the gu input (task #284).
  *
@@ -64,7 +65,26 @@ const NOT_AN_IMAGE = "that file is not an image (png, jpg, gif or webp)";
 
 export const imagesDir = (home = homedir()) => join(home, ".gonext", "images");
 
-/** Is this coding server Claude's own API — the only one allowed images for now? */
+/**
+ * WHICH CODERS MAY BE SENT IMAGES (#284, #316): the list in image-capable-coders.json, shared with
+ * the agent (gonext_agent_chat.py reads the same file), so the CLI's gate and the agent's can never
+ * disagree. A server/model is added there only after a real request with an image came back right.
+ */
+export const IMAGE_CODERS = JSON.parse(readFileSync(new URL("./image-capable-coders.json", import.meta.url), "utf8")).coders;
+
+/** May a pasted image be sent to this coder? `model` may be a qualified id ("openai::kimi-k3"). */
+export function coderTakesImagesFor(url, model = "", coders = IMAGE_CODERS) {
+  let host = "";
+  try {
+    host = new URL(String(url ?? "")).hostname.toLowerCase().replace(/\.$/, "");
+  } catch {
+    return false;
+  }
+  const name = String(model ?? "").split("::").pop().trim();
+  return coders.some((c) => c.host === host && (!c.model || new RegExp(c.model, "i").test(name)));
+}
+
+/** Is this coding server Claude's own API? (Kept for callers that ask exactly that.) */
 export function isClaudeCoderUrl(url) {
   try {
     return new URL(String(url ?? "")).hostname.toLowerCase().replace(/\.$/, "") === "api.anthropic.com";
@@ -73,10 +93,11 @@ export function isClaudeCoderUrl(url) {
   }
 }
 
+// The name is historical (#284 was Claude-only); since #316 Kimi K3 takes images too.
 export const IMAGE_NEEDS_CLAUDE =
-  "image paste needs a Claude coding model — pick one with /model";
+  "image paste needs a coding model that takes images (Claude, or Kimi K3) — pick one with /model";
 /** The same, for a window too narrow for the full sentence: the fix (/model) must survive. */
-export const IMAGE_NEEDS_CLAUDE_SHORT = "images need a Claude coder — /model";
+export const IMAGE_NEEDS_CLAUDE_SHORT = "images need Claude or Kimi K3 — /model";
 
 /**
  * The notice as it fits `cols` columns (#54): the full sentence, else its short form, else the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gu-cli",
-  "version": "1.0.780",
+  "version": "1.0.781",
   "description": "Gu CLI — the gu terminal plus the local worker that runs agent / OCR / PDF / embedding jobs on your Mac (Ollama / MLX / OpenAI-compatible).",
   "type": "module",
   "license": "MIT",
@@ -40,6 +40,7 @@
     "test:steps": "python3 scripts/py-tap.py tests/test_read_caps.py tests/test_trim_payback.py tests/test_explore.py tests/test_and_chains.py tests/test_edit_file_primary.py tests/test_bare_code_rescue.py tests/test_batching_rule.py tests/test_no_pdf_routing.py",
     "check:image": "node scripts/image-paste-check.mjs",
     "check:image-clipboard": "node scripts/image-paste-check.mjs --clipboard",
+    "test:presets": "node --test tests/preset-safety.test.mjs tests/preset-more.test.mjs tests/preset-apply.test.mjs tests/preset-full.test.mjs tests/presets-transfer.test.mjs tests/preset-editor.test.mjs tests/load-preset-paste.test.mjs",
     "test:skills": "python3 scripts/py-tap.py tests/test_skills_mcp_turn.py tests/test_hooks_turn.py tests/test_mcp_client.py && node --test tests/skills.test.mjs tests/mcp-config.test.mjs tests/hooks-config.test.mjs tests/slash-menu.test.mjs tests/conversation-archive.test.mjs",
     "capture:turn": "GONEXT_OLLAMA1_LIVE=1 node scripts/capture-turn-fixture.mjs",
     "test:bearer": "node --test tests/bearer-routing.test.mjs tests/bearer-verify.test.mjs",
@@ -65,7 +66,9 @@
     "credential-recovery.mjs",
     "settings-transfer.mjs",
     "presets-transfer.mjs",
+    "image-capable-coders.json",
     "preset-editor.mjs",
+    "preset-apply.mjs",
     "device-login.mjs",
     "daemon-control.mjs",
     "log-policy.mjs",

package/preset-apply.mjs

@@ -0,0 +1,156 @@
+/**
+ * SAVING AND APPLYING A WHOLE SETUP — the steps themselves, with the local API, the question and the
+ * disk passed in (#320). It used to live inside gu-repl.mjs, where only "is it wired" could be tested;
+ * here the REAL code runs in tests against a fake API that records every call and can be told to
+ * fail — which is how "loading a preset cannot break the workspace" is checked rather than hoped.
+ *
+ * Used for /save-preset, /load-presets (a version-2 preset) and /load-settings — one path for all.
+ *
+ *   api = {
+ *     settings():                Promise<object|null>   GET  /api/worker/settings
+ *     keys():                    Promise<array|null>    GET  /api/worker/coding-keys   (no values)
+ *     keyFor(backendId):         Promise<{apiKey,keyId}|null>   the key a server would be handed
+ *     saveSettings(patch):       Promise<boolean>       POST /api/worker/settings
+ *     addKey(name, key, rowId):  Promise<string>        → the new key's id, or "" when refused
+ *     setDefaultKey(rowId, id):  Promise<boolean>
+ *   }
+ *   io = { ask(question) → Promise<string>, say(line, tone) }   tone: "dim" | "warn" | "ok" | "err"
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { buildFullPreset, keysToApply } from "./presets-transfer.mjs";
+import { planLoad, toSettingsPatch } from "./settings-transfer.mjs";
+import { existingBackendRows, providerRowForUrl } from "./coding-provider-setup.mjs";
+
+/**
+ * THIS ACCOUNT'S WHOLE SETUP as a version-2 preset: every server, its models and the key it would
+ * be handed, the default coder, the agent, the embedder. → the preset, or null when unreadable.
+ */
+export async function buildFullPresetFrom(api, { name, host = "", now = new Date() } = {}) {
+  const settings = await api.settings();
+  if (!settings) return null;
+  const keys = (await api.keys()) ?? [];
+  const rows = Array.isArray(settings.agentCodingBackends) ? settings.agentCodingBackends : [];
+  const keyValues = [];
+  for (const r of rows) {
+    if (!r?.id) continue;
+    const k = await api.keyFor(r.id);
+    if (k?.apiKey) keyValues.push({ backendId: r.id, keyId: k.keyId, value: k.apiKey });
+  }
+  return buildFullPreset({ name, settings, keys, keyValues, host, now });
+}
+
+/**
+ * Save the whole current setup before a preset replaces it. → { ok, file } | { ok: false, why }.
+ * Never throws: a backup that fails is a REFUSAL to apply, not a crash.
+ */
+export async function backupSetup(api, presetName, { dir, host = "", now = new Date(), fs = { mkdirSync, writeFileSync } } = {}) {
+  try {
+    const doc = await buildFullPresetFrom(api, { name: `before-${presetName}`, host, now });
+    if (!doc) return { ok: false, why: "the settings could not be read" };
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const stamp = new Date(now).toISOString().replace(/[:.]/g, "-");
+    const file = join(dir, `before-${String(presetName).replace(/[^\w.-]+/g, "_")}-${stamp}.json`);
+    fs.writeFileSync(file, JSON.stringify({ ...doc, savedAt: new Date(now).toISOString(), savedOn: host }, null, 2) + "\n", { mode: 0o600 });
+    return { ok: true, file };
+  } catch (e) {
+    return { ok: false, why: e?.message ?? String(e) };
+  }
+}
+
+/**
+ * APPLY A SETTINGS DOCUMENT — a whole-setup preset, or a /save-settings file. In order, each step only
+ * if the one before it succeeded:
+ *   1. read the account; show the plan (servers, models, masked keys, warnings);
+ *   2. ask — anything but y/yes changes NOTHING;
+ *   3. back up the current setup (when `backupName`) — no backup, no apply;
+ *   4. one settings write: the servers (rows this account has keep their ids), agent, embedder;
+ *   5. the keys: carried ones added to their server, ones already there kept (and made default when the
+ *      preset says so), a settings file's missing ones asked for;
+ *   6. the default coder, once its server's row exists.
+ * → { applied: boolean, step?: where it stopped, backup?: file, added: [names], failed: [names] }
+ */
+export async function applyTransfer(value, { api, io, fromLine = "", carriesSecrets = false, summary = null, codingDefault = null, warnings = [], backupName = "", backupDir = "", host = "", now = new Date(), fs } = {}) {
+  const say = (line, tone = "dim") => io.say(line, tone);
+  const out = { applied: false, added: [], failed: [] };
+  const current = await api.settings();
+  if (!current) {
+    say("couldn't reach the API — nothing was changed.", "err");
+    return { ...out, step: "read" };
+  }
+  const keys = (await api.keys()) ?? [];
+  const plan = planLoad(value, { ...current, keys });
+  if (fromLine) say(fromLine);
+  const lines = summary
+    ? [...summary, ...plan.lines.filter((l) => /^(agent model|embedding model|  a different embedder)/.test(l))]
+    : plan.lines;
+  for (const l of lines) say(l);
+  if (summary && plan.replaces) say(`replaces the ${plan.replaces} coding provider${plan.replaces === 1 ? "" : "s"} on this account.`);
+  for (const w of warnings) say("⚠ " + w, "warn");
+  if (carriesSecrets) say("this file contains API keys in plain text — delete it when you are done.", "warn");
+  const go = String((await io.ask("apply this? [y/N] ")) ?? "").trim().toLowerCase();
+  if (go !== "y" && go !== "yes") {
+    say("nothing changed.");
+    return { ...out, step: "declined" };
+  }
+  if (backupName) {
+    const b = await backupSetup(api, backupName, { dir: backupDir, host, now, fs });
+    if (!b.ok) {
+      say(`couldn't save a backup of your current setup (${b.why}) — nothing was changed.`, "err");
+      return { ...out, step: "backup" };
+    }
+    out.backup = b.file;
+    say(`backup of your current setup: ${b.file}`);
+    say(`to undo: /load-presets ${b.file}`);
+  }
+  const patch = toSettingsPatch(value, current);
+  const saved = Object.keys(patch).length ? await api.saveSettings(patch) : true;
+  if (!saved) {
+    say("the API refused the settings — nothing was changed.", "err");
+    return { ...out, step: "settings" };
+  }
+  out.applied = true;
+  say(`applied: ${plan.adds} provider${plan.adds === 1 ? "" : "s"}${patch.ragEmbedUrl || patch.ragEmbedModel ? ", the embedding model" : ""}.`, "ok");
+
+  const fresh = (await api.settings()) ?? {};
+  const rows = existingBackendRows(fresh);
+  const { add, kept } = keysToApply(value, { currentKeys: keys, rows, missing: plan.missingKeys });
+  for (const k of kept) {
+    say(`kept your existing key ${k.name} for ${k.backendUrl} (the preset's copy was not used).`);
+    if (k.default && k.rowId && k.existingId && !(await api.setDefaultKey(k.rowId, k.existingId))) {
+      say(`could not make ${k.name} the default for ${k.backendUrl} — pick it in /model with ctrl+k.`, "err");
+    }
+  }
+  for (const k of add) {
+    const where = k.backendUrl ? ` for ${k.backendUrl}` : "";
+    const typed = k.key || String((await io.ask(`key "${k.name}"${k.tail ? ` (…${k.tail})` : ""}${where} — paste it, or Enter to skip: `)) ?? "").trim();
+    if (!typed) {
+      say(`skipped ${k.name} — add it later with ctrl+k.`);
+      continue;
+    }
+    const id = await api.addKey(k.name, typed, k.rowId);
+    if (!id) {
+      out.failed.push(k.name);
+      say(`could not add ${k.name}${where} — add it in /model with ctrl+k.`, "err");
+      continue;
+    }
+    out.added.push(k.name);
+    say(`added ${k.name}.`, "ok");
+    if (k.rowId && k.default && !(await api.setDefaultKey(k.rowId, id))) {
+      say(`added ${k.name}, but could not make it the default for ${k.backendUrl} — pick it in /model with ctrl+k.`, "err");
+    }
+  }
+  if (codingDefault?.url && codingDefault?.model) {
+    const row = providerRowForUrl(rows, codingDefault.url)?.id ?? "";
+    const ok = await api.saveSettings({
+      agentCodingModelUrl: codingDefault.url,
+      agentCodingModelName: codingDefault.model,
+      ...(codingDefault.kind ? { agentCodingModelKind: codingDefault.kind } : {}),
+      ...(row ? { agentCodingDefaultBackendId: row } : {}),
+    });
+    say(ok ? `coding model: ${codingDefault.model} at ${codingDefault.url}.` : "could not set the coding model — pick it with /model.", ok ? "ok" : "err");
+    return { ...out, step: "done", coder: ok };
+  }
+  say("pick a coding model with /model.");
+  return { ...out, step: "done" };
+}

package/preset-editor.mjs

@@ -23,7 +23,10 @@ import { spawnSync } from "node:child_process";
 import { mkdtempSync, writeFileSync, readFileSync, rmSync, chmodSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { validatePreset } from "./presets-transfer.mjs";
+import { validatePreset, validatePresetFile, maskedFullPreset, FULL_PRESET_VERSION } from "./presets-transfer.mjs";
+
+/** A version-2 preset — the WHOLE setup (#320): every server, keys, defaults. */
+export const isFullPreset = (doc) => Boolean(doc && typeof doc === "object" && (doc.version === FULL_PRESET_VERSION || Array.isArray(doc.codingBackends)));
 
 const clean = (v) => (typeof v === "string" ? v.trim() : "");
 
@@ -80,6 +83,19 @@ const FIELDS = ["apiUrl", "apiKey", "agentModel", "codingModel", "embedModel", "
 
 /** The text the editor opens with: a few `//` lines saying what to do, then the JSON. */
 export function editorText(name, preset = {}) {
+  if (isFullPreset(preset)) {
+    const { note: _n, savedAt: _a, savedOn: _o, ...body } = preset;
+    return (
+      [
+        `// gu preset "${name}" — THE WHOLE SETUP: every coding server and its models, each server's API key,`,
+        "// the default coder, the agent and the embedder. Edit anything, then save and quit to store it.",
+        "// Lines starting with // are ignored. Quit without saving (or unchanged) to cancel. This CONTAINS your API keys.",
+      ].join("\n") +
+      "\n" +
+      JSON.stringify({ ...body, gu: "preset", version: FULL_PRESET_VERSION, name }, null, 2) +
+      "\n"
+    );
+  }
   const body = {};
   for (const f of FIELDS) body[f] = clean(preset[f]);
   return (
@@ -94,6 +110,77 @@ export function editorText(name, preset = {}) {
   );
 }
 
+/**
+ * Where JSON text first goes wrong (an index), or -1 when it is valid — a small strict parser used only
+ * to NAME the spot of a mistake when Node's own message does not.
+ */
+export function jsonErrorIndex(src) {
+  let i = 0;
+  const ws = () => { while (i < src.length && " \t\r\n".includes(src[i])) i++; };
+  const fail = () => { throw i; };
+  const lit = (w) => { if (src.startsWith(w, i)) i += w.length; else fail(); };
+  const str = () => {
+    i++;
+    while (i < src.length && src[i] !== '"') {
+      if (src[i] === "\\") {
+        // only JSON's escapes: \" \\ \/ \b \f \n \r \t and \uXXXX
+        const e = src[i + 1];
+        if (e === "u") {
+          if (!/^[0-9a-fA-F]{4}$/.test(src.slice(i + 2, i + 6))) { i += 1; fail(); }
+          i += 6;
+          continue;
+        }
+        if (!e || !'"\\/bfnrt'.includes(e)) { i += 1; fail(); }
+        i += 2;
+        continue;
+      }
+      if (src.charCodeAt(i) < 0x20) fail();
+      i++;
+    }
+    if (src[i] !== '"') fail();
+    i++;
+  };
+  const num = () => {
+    const m = /^-?(0|[1-9]\d*)(\.\d+)?([eE][+-]?\d+)?/.exec(src.slice(i));
+    if (!m) fail();
+    i += m[0].length;
+  };
+  const val = () => {
+    ws();
+    const c = src[i];
+    if (c === "{") {
+      i++; ws();
+      if (src[i] === "}") { i++; return; }
+      for (;;) {
+        ws(); if (src[i] !== '"') fail(); str(); ws();
+        if (src[i] !== ":") fail(); i++; val(); ws();
+        if (src[i] === ",") { i++; continue; }
+        if (src[i] === "}") { i++; return; }
+        fail();
+      }
+    } else if (c === "[") {
+      i++; ws();
+      if (src[i] === "]") { i++; return; }
+      for (;;) {
+        val(); ws();
+        if (src[i] === ",") { i++; continue; }
+        if (src[i] === "]") { i++; return; }
+        fail();
+      }
+    } else if (c === '"') str();
+    else if (c === "t") lit("true");
+    else if (c === "f") lit("false");
+    else if (c === "n") lit("null");
+    else num();
+  };
+  try {
+    val(); ws();
+    return i < src.length ? i : -1;
+  } catch (at) {
+    return typeof at === "number" ? at : 0;
+  }
+}
+
 /**
  * What came back from the editor → { ok, preset } | { ok: false, problem }. The // lines are
  * blanked (not removed) so a JSON error's line number is the line the person sees in the editor.
@@ -104,10 +191,25 @@ export function parseEdited(text) {
   try {
     JSON.parse(src);
   } catch (e) {
-    const at = /line (\d+) column (\d+)/.exec(String(e?.message ?? ""));
+    // Node names the line only for SOME errors ("Expected ':' …"); a stray comma comes back as just a
+    // snippet. So when it does not say, find the spot ourselves — the person fixes a LINE in an editor.
+    let at = /line (\d+) column (\d+)/.exec(String(e?.message ?? ""));
+    if (!at) {
+      const i = jsonErrorIndex(src);
+      if (i >= 0) {
+        const before = src.slice(0, i).split("\n");
+        at = [null, String(before.length), String(before[before.length - 1].length + 1)];
+      }
+    }
     const where = at ? ` (line ${at[1]}, column ${at[2]})` : "";
     return { ok: false, problem: `that is not valid JSON${where} — ${String(e?.message ?? e).replace(/\s*in JSON at position \d+.*$|\s*\(line \d+ column \d+\)/g, "")}.` };
   }
+  const obj = JSON.parse(src);
+  if (isFullPreset(obj)) {
+    const doc = { ...obj, gu: "preset", version: FULL_PRESET_VERSION };
+    const v = validatePresetFile(JSON.stringify(doc));
+    return v.ok ? { ok: true, full: true, doc, checked: v } : v;
+  }
   return validatePreset(src);
 }
 
@@ -147,14 +249,20 @@ const presetBody = (preset) => {
   return o;
 };
 
-/** What "copy" puts on the clipboard: the command that recreates the preset — WITH the key. */
+/** A whole-setup preset without its bookkeeping (note, dates) — what is copied and edited. */
+const fullBody = (doc) => {
+  const { note: _n, savedAt: _a, savedOn: _o, ...rest } = doc;
+  return rest;
+};
+
+/** What "copy" puts on the clipboard: the command that recreates the preset — WITH the key(s). */
 export function presetCopyCommand(name, preset) {
-  return `/save-preset ${clean(name)} ${JSON.stringify(presetBody(preset))}`;
+  return `/save-preset ${clean(name)} ${JSON.stringify(isFullPreset(preset) ? fullBody(preset) : presetBody(preset))}`;
 }
 
-/** …or just the JSON, pretty, WITH the key. */
+/** …or just the JSON, pretty, WITH the key(s). */
 export function presetCopyJson(preset) {
-  return JSON.stringify(presetBody(preset), null, 2);
+  return JSON.stringify(isFullPreset(preset) ? fullBody(preset) : presetBody(preset), null, 2);
 }
 
 /**
@@ -163,7 +271,7 @@ export function presetCopyJson(preset) {
  * → { rows, button: { from, to } } — the button's column span on row 0, 0-based, gutter included.
  */
 export function presetBlock(name, preset, { width = 80, gutter = "   " } = {}) {
-  const shown = { ...presetBody(preset), apiKey: maskKey(preset.apiKey) };
+  const shown = isFullPreset(preset) ? fullBody(maskedFullPreset(preset)) : { ...presetBody(preset), apiKey: maskKey(preset.apiKey) };
   const inner = JSON.stringify(shown, null, 2).split("\n");
   const room = Math.max(24, width - 1 - gutter.length);
   const innerW = Math.min(room - 4, Math.max(...inner.map((l) => [...l].length), 30));
@@ -211,7 +319,8 @@ export function parsePastedPreset(text) {
   }
   const parsed = parseEdited(src);
   if (!parsed.ok) return parsed;
-  // A whole preset file carries its name inside; the command's own name wins when both exist.
+  // A whole-setup preset (#320) or a preset file carries its name inside; the command's name wins.
+  if (parsed.full) return { ok: true, full: true, doc: parsed.doc, name: name || clean(parsed.doc.name) };
   try {
     const doc = JSON.parse(src.replace(/^[ \t]*\/\/.*$/gm, ""));
     if (!name && doc && typeof doc.name === "string" && doc.gu === "preset") name = doc.name.trim();

package/presets-transfer.mjs

@@ -20,7 +20,8 @@
  */
 
 import { basename, extname, isAbsolute, join, resolve } from "node:path";
-import { ensureV1Root, isCancelWord, MAX_MODELS_PER_SERVER } from "./coding-provider-setup.mjs";
+import { ensureV1Root, isCancelWord, MAX_MODELS_PER_SERVER, providerRowForUrl } from "./coding-provider-setup.mjs";
+import { buildTransfer, validateTransfer, FILE_VERSION as SETTINGS_FILE_VERSION } from "./settings-transfer.mjs";
 
 /** The file name used when none is given — in the default folder (the home directory). */
 export const DEFAULT_PRESET_NAME = "gu-preset.json";
@@ -150,6 +151,7 @@ export function validatePresetFile(text) {
   if (!doc || typeof doc !== "object" || Array.isArray(doc) || doc.gu !== "preset") {
     return { ok: false, problem: 'that file is not a gu preset file (no "gu": "preset" marker).' };
   }
+  if (doc.version === FULL_PRESET_VERSION) return validateFullPreset(doc);
   if (doc.version !== PRESET_FILE_VERSION) {
     return {
       ok: false,
@@ -213,3 +215,208 @@ export function presetPlanLines(name, preset, current = {}) {
   lines.push("  replaces the coding provider list with this one server.");
   return lines;
 }
+
+// ---------------------------------------------------------------------------------------------
+// THE WHOLE SETUP (#320: "save/load presets lack all the API URLs I have set up … I need to see and
+// copy all, including the API key, to another machine, so I can use it without creating the
+// providers again or choosing the models again").
+//
+// A version-2 preset is the /save-settings document (every coding server with its models, the agent
+// model, the embedder — settings-transfer.mjs) PLUS what that file refuses by design: each server's
+// API key, in `keys[].key`, and the default coding model. It is applied with the very same code as
+// /load-settings, so a server this account already has keeps its row id and each key lands on its
+// own server as that server's default. Version 1 (one server) still loads, unchanged.
+// ---------------------------------------------------------------------------------------------
+
+export const FULL_PRESET_VERSION = 2;
+
+/**
+ * Build a version-2 preset. `settings` = GET /api/worker/settings; `keys` = the masked key list
+ * (id, name, backendId, default); `keyValues` = [{ backendId, keyId?, value }] — each server's key as
+ * the worker would be handed it. A server with no readable key simply carries none.
+ */
+export function buildFullPreset({ name, settings = {}, keys = [], keyValues = [], now = new Date(), host = "" } = {}) {
+  const t = buildTransfer({ settings, keys, now, host });
+  const rows = Array.isArray(settings.agentCodingBackends) ? settings.agentCodingBackends : [];
+  const urlOf = (id) => clean(rows.find((r) => r?.id === id)?.url);
+  const list = Array.isArray(keys) ? keys : [];
+  const out = [];
+  for (const v of Array.isArray(keyValues) ? keyValues : []) {
+    const url = urlOf(v.backendId);
+    const value = clean(v.value);
+    if (!url || !value) continue;
+    // Its name: the key the server resolves to (by id), else that server's default, else the host.
+    const k = list.find((x) => x?.id && x.id === v.keyId) || list.find((x) => x?.backendId === v.backendId && x.default) ||
+      list.find((x) => x?.backendId === v.backendId);
+    const nm = clean(k?.name) || new URL(url).hostname;
+    if (out.some((o) => o.backendUrl === url)) continue; // one key per server
+    out.push({ name: nm, backendUrl: url, default: true, key: value });
+  }
+  const coder = {
+    url: clean(settings.agentCodingModelUrl),
+    model: clean(settings.agentCodingModelName),
+    kind: clean(settings.agentCodingModelKind),
+  };
+  return {
+    gu: "preset",
+    version: FULL_PRESET_VERSION,
+    note: "The whole setup: every coding server and its models, the default coder, the agent and the embedder — and each server's API key. This file CONTAINS live API keys.",
+    name: clean(name),
+    savedAt: t.savedAt,
+    ...(t.savedOn ? { savedOn: t.savedOn } : {}),
+    codingDefault: coder,
+    codingBackends: t.codingBackends,
+    agentModel: t.agentModel,
+    embedModel: t.embedModel,
+    keys: out,
+  };
+}
+
+/** How many servers a preset may carry — far above anyone's real list, low enough to refuse junk. */
+export const MAX_PRESET_SERVERS = 20;
+
+/**
+ * Is this text a usable API key? A preset someone typed or pasted can carry the MASKED form copied
+ * from the view ("sk-…abcd"), a placeholder, or a line break from a wrapped paste — each would
+ * replace a working key with one that fails every turn, which is exactly how a workspace breaks.
+ * → "" when fine, else the reason.
+ */
+export function keyProblem(value) {
+  const v = String(value ?? "");
+  if (!v.trim()) return "it is empty";
+  if (/[…]|\.\.\./.test(v)) return "it is the MASKED form (with …) — copy the preset with c, not from the view";
+  if (/^<.*>$|your[-_ ]?(api[-_ ]?)?key|^x+$|^\*+$|placeholder|changeme/i.test(v.trim())) return "it is a placeholder, not a key";
+  if (/[\s\u0000-\u001f\u007f]/.test(v.trim()) || v !== v.trim()) return "it contains spaces or line breaks";
+  if (v.trim().length < 8) return "it is too short to be a key";
+  if (v.trim().length > 400) return "it is too long to be a key";
+  return "";
+}
+
+const sameServer = (a, b) => Boolean(clean(a) && clean(b)) && ensureV1Root(clean(a)).toLowerCase() === ensureV1Root(clean(b)).toLowerCase();
+
+/**
+ * Check a version-2 preset with /load-settings' own rules — and then the ones a WHOLE-SETUP preset
+ * needs so that loading it cannot leave the workspace in a mess (#320, the user: "when I load a preset
+ * from JSON I typed, it must not break my workspace — wrong API key or anything"). Everything is
+ * checked BEFORE anything is applied; the first real problem refuses the whole preset, named.
+ * Things that are allowed but worth knowing come back as `warnings` for the plan.
+ */
+export function validateFullPreset(doc) {
+  const back = validateTransfer(JSON.stringify({ ...doc, gu: "settings", version: SETTINGS_FILE_VERSION }));
+  if (!back.ok) return back;
+  const v = back.value;
+  const warnings = [];
+  if (!v.backends.length) return { ok: false, problem: "the preset has no coding servers — nothing to load." };
+  if (v.backends.length > MAX_PRESET_SERVERS) {
+    return { ok: false, problem: `the preset has ${v.backends.length} servers — at most ${MAX_PRESET_SERVERS}.` };
+  }
+  // SERVERS: each one real, each one once — "https://ollama.com" and "…/v1" are the SAME server,
+  // and two rows for it would split its keys between twins.
+  for (const [i, b] of v.backends.entries()) {
+    const at = `codingBackends[${i}]`;
+    if (!b.url) return { ok: false, problem: `${at} has no url.` };
+    if (!b.defaultModel) return { ok: false, problem: `${at} (${b.url}) has no defaultModel.` };
+    const twin = v.backends.findIndex((o, j) => j < i && sameServer(o.url, b.url));
+    if (twin >= 0) return { ok: false, problem: `${at} (${b.url}) is the same server as codingBackends[${twin}] (${v.backends[twin].url}).` };
+  }
+  // KEYS: each bound to a server IN THE PRESET, each a usable key, one default per server.
+  const defaults = new Map();
+  for (const [i, k] of v.keys.entries()) {
+    const at = `keys[${i}] "${k.name}"`;
+    if (!k.backendUrl) return { ok: false, problem: `${at} names no server (backendUrl) — a key belongs to a server.` };
+    const b = v.backends.find((x) => sameServer(x.url, k.backendUrl));
+    if (!b) return { ok: false, problem: `${at} is for ${k.backendUrl}, which is not one of the preset's servers.` };
+    if (k.key !== undefined) {
+      const why = keyProblem(k.key);
+      if (why) return { ok: false, problem: `${at} cannot be used: ${why}.` };
+    }
+    if (k.default) {
+      const root = ensureV1Root(b.url).toLowerCase();
+      if (defaults.has(root)) return { ok: false, problem: `${b.url} has two default keys ("${defaults.get(root)}" and "${k.name}") — mark one.` };
+      defaults.set(root, k.name);
+    }
+  }
+  const noKey = v.backends.filter((b) => !v.keys.some((k) => k.key && sameServer(k.backendUrl, b.url)));
+  for (const b of noKey) warnings.push(`${b.url} has no key in the preset — it keeps whatever key this machine has for it (or none).`);
+  // THE DEFAULT CODER must be a server and model the preset itself sets up.
+  const cd = doc.codingDefault && typeof doc.codingDefault === "object" ? doc.codingDefault : {};
+  if (cd.url !== undefined && cd.url !== "" && !isHttpUrl(cd.url)) {
+    return { ok: false, problem: `codingDefault.url must be an http(s) URL — got ${JSON.stringify(cd.url)}.` };
+  }
+  if (clean(cd.url) || clean(cd.model)) {
+    const b = v.backends.find((x) => sameServer(x.url, cd.url));
+    if (!b) return { ok: false, problem: `codingDefault is on ${clean(cd.url) || "no server"}, which is not one of the preset's servers.` };
+    const models = [b.defaultModel, ...b.models];
+    if (!models.includes(clean(cd.model))) {
+      return { ok: false, problem: `codingDefault model "${clean(cd.model)}" is not a model of ${b.url} (${models.join(", ")}).` };
+    }
+  }
+  // Agent / embedder on a server the preset does not set up: allowed (a local Ollama needs no row),
+  // but said — its key then has to come from this machine.
+  for (const [role, m] of [["agent model", v.agentModel], ["embedding model", v.embedModel]]) {
+    if (m.url && !v.backends.some((b) => sameServer(b.url, m.url))) warnings.push(`the ${role} is on ${m.url}, which the preset does not set up — its key must already be on this machine.`);
+  }
+  return {
+    ok: true,
+    full: true,
+    name: clean(doc.name),
+    value: v,
+    warnings,
+    carriesSecrets: back.carriesSecrets,
+    codingDefault: { url: clean(cd.url), model: clean(cd.model), kind: clean(cd.kind) },
+    savedAt: clean(doc.savedAt),
+    savedOn: clean(doc.savedOn),
+  };
+}
+
+/**
+ * WHICH KEYS TO ADD when a preset is applied (#320) — pure, so it is tested rather than trusted.
+ * A key the preset CARRIES is added, bound to its server's row; one this machine already has by the
+ * same name on the same server is KEPT (not duplicated, not overwritten); keys without a value come
+ * from `missing` (a settings file's, asked for). → { add: [{ name, key?, rowId, default }], kept: [...] }
+ */
+export function keysToApply(value, { currentKeys = [], rows = [], missing = [] } = {}) {
+  const rowOf = (url) => providerRowForUrl(rows, url)?.id ?? "";
+  const existing = (k) => {
+    const row = rowOf(k.backendUrl);
+    return row ? currentKeys.find((c) => clean(c.name).toLowerCase() === clean(k.name).toLowerCase() && c.backendId === row) : null;
+  };
+  const have = (k) => Boolean(existing(k));
+  const carried = (value?.keys ?? []).filter((k) => k.key);
+  // KEPT keys still carry the preset's DEFAULT choice: restoring a backup after a preset made another
+  // key its server's default must make this one the default again, or the undo is incomplete.
+  const kept = carried.filter(have).map((k) => ({ ...k, rowId: rowOf(k.backendUrl), existingId: existing(k).id, default: k.default === true }));
+  const add = [...carried.filter((k) => !have(k)), ...missing].map((k) => ({
+    name: k.name,
+    ...(k.key ? { key: k.key } : {}),
+    backendUrl: k.backendUrl ?? "",
+    rowId: k.backendUrl ? rowOf(k.backendUrl) : "",
+    default: k.default === true,
+    ...(k.tail ? { tail: k.tail } : {}),
+  }));
+  return { add, kept };
+}
+
+/** A key as it may be SHOWN: its first few and last four characters. */
+const mask = (k) => {
+  const v = clean(k);
+  if (!v) return "";
+  return v.length <= 8 ? "…" + v.slice(-2) : `${v.startsWith("sk-") ? "sk-" : v.slice(0, 3)}…${v.slice(-4)}`;
+};
+
+/** The whole preset with every key MASKED — what is printed; the file / the copy keep the real keys. */
+export function maskedFullPreset(doc) {
+  return { ...doc, keys: (Array.isArray(doc?.keys) ? doc.keys : []).map((k) => ({ ...k, ...(k.key ? { key: mask(k.key) } : {}) })) };
+}
+
+/** The lines /load-presets prints before applying a version-2 preset (keys masked). */
+export function fullPresetSummary(v, codingDefault) {
+  const lines = [];
+  for (const b of v.backends) {
+    const models = [...new Set([b.defaultModel, ...(b.models ?? [])].filter(Boolean))];
+    const key = v.keys.find((k) => k.backendUrl && ensureV1Root(k.backendUrl).toLowerCase() === ensureV1Root(b.url).toLowerCase());
+    lines.push(`  ${b.url}  ${models.join(", ") || "(no models)"}${key?.key ? `  · key ${key.name} ${mask(key.key)}` : "  · no key"}`);
+  }
+  if (codingDefault?.url || codingDefault?.model) lines.push(`coding model: ${codingDefault.model || "?"} at ${codingDefault.url || "?"}`);
+  return lines;
+}