@tiens.nguyen/gu-cli 1.0.768 → 1.0.769

package/client-expert-api.mjs

@@ -516,6 +516,23 @@ export const CLIENT_EXPERT_MODELS = {
  * is written — while Kimi is registered as "openai" so `/model` lists it and asks for the key
  * only if the user actually switches. One slot per kind, so these cannot collide.
  */
+/** The row setup writes for an agent server that differs from the coder's and has a key (#301). */
+export const AGENT_ROW_ID = "ollama-agent";
+/** The implicit id of the coder's row — setup writes it without one; the API names it by kind. */
+export const CODER_ROW_ID = "ollama";
+
+/**
+ * Which row a key typed at setup binds to (#301): the coder's row for the coder's server (or for
+ * the agent's when they share one), the agent row otherwise. "" when neither server was used.
+ */
+export function rowIdForKey(models, url) {
+  const M = models ?? {};
+  const codeUrl = M.codeUrl || M.url;
+  if (url && url === codeUrl) return CODER_ROW_ID;
+  if (url && url === M.url) return AGENT_ROW_ID;
+  return "";
+}
+
 export function codingBackendsForClientExpert(models = CLIENT_EXPERT_MODELS) {
   const M = models ?? CLIENT_EXPERT_MODELS;
   // The chat model is offered too, so `/model` can drop to the fast one for simple work, plus
@@ -525,17 +542,33 @@ export function codingBackendsForClientExpert(models = CLIENT_EXPERT_MODELS) {
   // SHARED_ALT_CODE_MODEL is the seeded default for the shared box. Deduped and stripped of the
   // primary coder, because a `/model` list that offers the model you are already on — twice —
   // is a list nobody trusts.
-  const offered = [M.chat, ...(M.altCoders ?? [SHARED_ALT_CODE_MODEL])].filter(
+  //
+  // THE CODER'S OWN SERVER (#301). Setup has asked "Coding-model server" separately since #220 and
+  // returned it as codeUrl, but this row was always built on M.url — the AGENT's server — so a
+  // coder chosen on a second box was silently configured on the first. The agent model is offered
+  // on the coder's row only when it lives on that same server; elsewhere it is not there to offer.
+  const codeUrl = M.codeUrl || M.url;
+  const sameServer = codeUrl === M.url;
+  const offered = [...(sameServer ? [M.chat] : []), ...(M.altCoders ?? [SHARED_ALT_CODE_MODEL])].filter(
     (name, i, all) => name && name !== M.code && all.indexOf(name) === i,
   );
+  // AN AGENT SERVER WITH A KEY NEEDS A ROW OF ITS OWN (#301). The API finds the agent's (and the
+  // embedder's) key by matching agentModelUrl to a row's URL — no row, no key. Only when the key
+  // exists: a keyless agent box needs no row, and one would add a server to /model for nothing.
+  // Explicit id, because two id-less ollama rows would both claim the implicit id "ollama".
+  const agentKeyed =
+    !sameServer && Array.isArray(M.keys) && M.keys.some((k) => k?.url === M.url && k?.key);
   return [
     {
       kind: "ollama",
       enabled: true,
-      url: M.url,
+      url: codeUrl,
       defaultModel: M.code,
       models: offered,
     },
+    ...(agentKeyed
+      ? [{ id: AGENT_ROW_ID, kind: "ollama", enabled: true, url: M.url, defaultModel: M.chat, models: [] }]
+      : []),
     {
       kind: "openai",
       enabled: true,
@@ -627,8 +660,14 @@ export function backfillCodingModels(existing = {}) {
  * model names to a list that already exists; see its docstring for why that is not "overwriting
  * a model the user has since chosen".
  */
-export function settingsPatch({ existing = {}, models = CLIENT_EXPERT_MODELS } = {}) {
+export function settingsPatch({ existing = {}, models = CLIENT_EXPERT_MODELS, skipModels = false } = {}) {
   const patch = {};
+  // #301: "Skip for now" (or Esc) at setup — NO model field is written: not the shared box, not a
+  // half. The bar then says what is unset and /model sets it. Only the non-model defaults below.
+  if (skipModels) {
+    if (typeof existing.agentSaveFullResponse !== "boolean") patch.agentSaveFullResponse = true;
+    return patch;
+  }
   // `models` is either the seeded shared-Ollama defaults (nobody was asked) or the box the user
   // chose at setup (task #220). Everything below is written in terms of M, so the two paths
   // cannot drift into configuring different fields.
@@ -638,7 +677,10 @@ export function settingsPatch({ existing = {}, models = CLIENT_EXPERT_MODELS } =
     Boolean(existing.agentModelUrl?.trim()) ||
     Boolean(existing.agentModel?.trim()) ||
     Boolean(existing.agentModelName?.trim());
-  if (!hasAgent) {
+  // A ROLE SKIPPED AT SETUP IS LEFT UNSET, not half-written (#301): an agent URL with no model
+  // name is the "default_model" sentinel on the wire, and a coder row with an empty model is a coder
+  // that answers nothing. Only the roles that were actually chosen are written.
+  if (!hasAgent && M.chat) {
     patch.agentModelUrl = M.url;
     const name = M.chat;
     // agentModelNAME is the field that matters. With a direct agent URL the API reads
@@ -664,17 +706,17 @@ export function settingsPatch({ existing = {}, models = CLIENT_EXPERT_MODELS } =
     (Array.isArray(existing.agentCodingBackends) && existing.agentCodingBackends.length > 0) ||
     Boolean(existing.agentCodingModelUrl?.trim()) ||
     Boolean(existing.agentCodingModelName?.trim());
-  if (!hasCoder) {
+  if (!hasCoder && M.code) {
     patch.agentCodingBackends = codingBackendsForClientExpert(M);
     patch.agentCodingDefaultKind = "ollama";
     // Legacy mirror, so an older worker resolves the same coder.
     patch.agentCodingModelKind = "ollama";
-    patch.agentCodingModelUrl = M.url;
+    patch.agentCodingModelUrl = M.codeUrl || M.url;
     patch.agentCodingModelName = M.code;
     // NO api key is stored. The default coder is kind "ollama", which the API does not require
     // one for — and a placeholder here would be SENT to Kimi the moment someone switched with
     // `/model`, failing at the provider with an auth error nobody expected.
-  } else {
+  } else if (hasCoder) {
     // Already configured — so the seed above will never run again on this machine. Add any
     // newly-offered shared-Ollama models to the list it was seeded with, without changing which
     // coder it uses. See backfillCodingModels.
@@ -752,6 +794,8 @@ export async function seedSettings({
   // question was skipped or declined. Passed straight to settingsPatch so there is exactly one
   // place that decides what a Client Expert machine is configured with.
   models = CLIENT_EXPERT_MODELS,
+  // #301: the model questions were skipped — write no model field at all.
+  skipModels = false,
 } = {}) {
   const { MongoClient } = loadMongoDriver(apiDir);
   const client = new MongoClient(mongoUri, { serverSelectionTimeoutMS: 8000 });
@@ -759,7 +803,7 @@ export async function seedSettings({
   try {
     const col = client.db(dbName).collection("settings");
     const existing = (await col.findOne({ userId })) ?? {};
-    const patch = settingsPatch({ existing, models });
+    const patch = settingsPatch({ existing, models, skipModels });
     if (Object.keys(patch).length > 0) {
       await col.updateOne(
         { userId },
@@ -773,6 +817,43 @@ export async function seedSettings({
   }
 }
 
+/**
+ * Save the API keys typed at setup (#301), each bound to its server's row, through the local API
+ * — the same POST /coding-keys the terminal uses, so the first key for a server becomes its
+ * default by the API's own rule (#245) rather than by anything written here. Runs AFTER
+ * seedSettings: the API refuses a key for a row that does not exist yet.
+ *
+ * Returns [{ host, ok }]. Never throws and never prints the key: a key that failed to save is
+ * reported by host, and can be added again with ctrl+k in /model.
+ */
+export async function saveSetupKeys({ apiBase = LOCAL_API_BASE, workerKey, models, fetchImpl = fetch } = {}) {
+  const out = [];
+  for (const { url, key } of Array.isArray(models?.keys) ? models.keys : []) {
+    let host = url;
+    try {
+      host = new URL(url).host;
+    } catch {
+      /* keep the url */
+    }
+    const backendId = rowIdForKey(models, url);
+    if (!key || !backendId) continue;
+    let ok = false;
+    try {
+      const r = await fetchImpl(`${apiBase}/api/worker/coding-keys`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "X-Worker-Key": workerKey },
+        body: JSON.stringify({ name: host, apiKey: key, backendId }),
+        signal: AbortSignal.timeout(10000),
+      });
+      ok = r.ok;
+    } catch {
+      ok = false;
+    }
+    out.push({ host, ok });
+  }
+  return out;
+}
+
 /**
  * THE NEW OLLAMA SERVER'S ROWS, MERGED INTO WHAT IS ALREADY THERE — never replacing it (#43).
  *

package/client-expert-run.mjs

@@ -29,6 +29,7 @@ import {
   probeLocalApi,
   writeWorkerEnv,
   seedSettings,
+  saveSetupKeys,
   modelsAlreadyConfigured,
   CLIENT_EXPERT_MODELS,
   LOCAL_API_PORT,
@@ -37,6 +38,9 @@ import {
   LOCAL_MONGO_URI,
 } from "./client-expert-api.mjs";
 import { askOllamaSetup, localOllamaDefault } from "./ollama-setup.mjs";
+import { SKIP_ALL, createHinter, modelSetupMenu, parseModelSetupChoice } from "./model-setup-ui.mjs";
+import { presetFilesIn } from "./presets-transfer.mjs";
+import { readdirSync, statSync, readFileSync } from "node:fs";
 import { parseOllamaTags, formatSize } from "./agent-model-command.mjs";
 import {
   planSetup,
@@ -66,15 +70,46 @@ class SkipModelQuestion extends Error {}
  * (this returns []), and those two get different messages because they need different fixes.
  * A short timeout, because a box that has not answered in eight seconds is not going to.
  */
-async function fetchOllamaTags(url) {
-  const res = await fetch(url, { signal: AbortSignal.timeout(8000) });
-  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+async function fetchOllamaTags(url, { apiKey = "" } = {}) {
+  const res = await fetch(url, {
+    signal: AbortSignal.timeout(8000),
+    // #301: a key typed for this server. Absent → the request is exactly what it always was.
+    ...(apiKey ? { headers: { Authorization: `Bearer ${apiKey}` } } : {}),
+  });
+  if (!res.ok) {
+    // The status travels with the error: 401/403 is "needs a key", which the caller asks for.
+    const err = new Error(`HTTP ${res.status}`);
+    err.status = res.status;
+    throw err;
+  }
   // parseOllamaTags is tolerant by design — HTML from a proxy, an empty body and a shape from a
   // future Ollama all become []. That is "reachable but not usable", which the caller reports as
   // such rather than as a network failure.
   return parseOllamaTags(await res.json().catch(() => null));
 }
 
+/** How many /save-preset files are in the home folder — the up-front question names the count. */
+function countSavedPresets() {
+  try {
+    const home = homedir();
+    const entries = [];
+    for (const name of readdirSync(home)) {
+      if (!name.toLowerCase().endsWith(".json")) continue;
+      const file = join(home, name);
+      try {
+        const st = statSync(file);
+        if (!st.isFile() || st.size > 64 * 1024) continue; // a preset is tiny; never slurp a big file
+        entries.push({ name, text: readFileSync(file, "utf8"), mtimeMs: st.mtimeMs });
+      } catch {
+        /* unreadable — not a preset we can offer */
+      }
+    }
+    return presetFilesIn(entries).length;
+  } catch {
+    return 0;
+  }
+}
+
 const dim = (s) => `\x1b[2m${s}\x1b[0m`;
 const bold = (s) => `\x1b[1m${s}\x1b[0m`;
 // The brand accent, shared with the REPL — see accent.mjs.
@@ -339,7 +374,7 @@ export async function checkMongoConnection(uri) {
  * Returns { uri, custom } to continue with, or { exit: true } when the user declines — the
  * caller ends setup with the `gu clear` → `gu` hint.
  */
-export async function askMongoCredentials(ask) {
+export async function askMongoCredentials(ask, askSecret = null) {
   const { host, port } = mongoHostPort(LOCAL_MONGO_URI);
   console.log(dim(`  MongoDB is answering at ${host}:${port}.`));
   console.log(dim("  If that is a MongoDB this machine already had, it may have its OWN"));
@@ -352,7 +387,12 @@ export async function askMongoCredentials(ask) {
   // continues: a typo found here costs ten seconds; found at the seed step it costs the run.
   for (let attempt = 0; attempt < 3; attempt += 1) {
     const username = String(await ask("  MongoDB username: ") ?? "").trim();
-    const password = String(await ask("  MongoDB password: ") ?? "");
+    // MASKED when a masked reader is available (#300): a password typed in the clear stays in the
+    // scrollback, and in anything copied from it.
+    const rawPw = typeof askSecret === "function"
+      ? await askSecret("  MongoDB password: ")
+      : await ask("  MongoDB password: ");
+    const password = rawPw === SKIP_ALL ? "" : String(rawPw ?? "");
     const uri = buildMongoUri({ username, password, host, port });
     process.stdout.write(dim("  checking the connection…"));
     const verdict = await checkMongoConnection(uri);
@@ -589,7 +629,14 @@ export function markInterruptedOnExit(getState, stepId) {
   };
 }
 
-export async function runClientExpertSetup({ ask }) {
+export async function runClientExpertSetup({
+  ask,
+  // #301/#300: a MASKED line reader (API keys, the MongoDB password). Absent → no key is asked.
+  askSecret = null,
+  // #301: an Esc-aware reader for the model questions — Esc resolves it with SKIP_ALL. Only the
+  // model questions use it: Esc elsewhere (the MongoDB questions) must not mean "skip models".
+  askStep = ask,
+}) {
   const machine = await probeMachine();
   const gate = clientExpertAvailable({ workerEnvExists: false, ...machine });
   if (!gate.available) {
@@ -707,7 +754,7 @@ export async function runClientExpertSetup({ ask }) {
       console.log(dim("  using the MongoDB credentials from the previous run"));
     }
   } else if (!process.env.GONEXT_LOCAL_MONGO_URI) {
-    const credsChoice = await askMongoCredentials(ask);
+    const credsChoice = await askMongoCredentials(ask, askSecret);
     if (credsChoice.exit) {
       console.log("\n  " + dim("No working MongoDB credentials — setup stops here."));
       console.log(dim("  To start over: `gu clear`, then `gu` again.\n"));
@@ -902,6 +949,27 @@ export async function runClientExpertSetup({ ask }) {
       console.log(dim("  server this machine uses."));
       throw new SkipModelQuestion();
     }
+    // ASK ONCE, UP FRONT (#301): guided / load a preset / skip. Enter = guided, so today's flow is
+    // unchanged for anyone who just presses Enter; the other two are one digit away instead of an
+    // escape hunt through four questions.
+    const presets = countSavedPresets();
+    console.log("");
+    const [title, ...rows] = modelSetupMenu({ presets });
+    console.log("  " + bold(title));
+    for (const r of rows) console.log(dim("  " + r));
+    let path = null;
+    for (let t = 0; t < 3 && !path; t++) {
+      path = parseModelSetupChoice(await askStep("  choose [1]: "));
+      if (path === "preset" && presets === 0) {
+        console.log(dim("  No presets saved yet. Save one later with /save-preset — pick 1 or 3 for now."));
+        path = null;
+      }
+    }
+    path = path ?? "guided";
+    if (path !== "guided") {
+      chosenModels = { skipped: true, keys: [], loadPreset: path === "preset" };
+      throw new SkipModelQuestion();
+    }
     console.log("");
     console.log("  " + bold("Which Ollama server should this machine use?"));
     // THIS MACHINE FIRST, when it has one. Client Expert is the mode whose whole promise is
@@ -923,10 +991,12 @@ export async function runClientExpertSetup({ ask }) {
       ),
     );
     console.log(dim("    ollama.local, http://box:11434 — and pick from what it actually has."));
-    chosenModels = await askOllamaSetup(ask, {
+    chosenModels = await askOllamaSetup(askStep, {
       defaultUrl,
       fetchTags: fetchOllamaTags,
       formatSize,
+      askSecret,
+      hint: createHinter(),
       // THE SHIPPED DEFAULT WINS WHEN THE BOX HAS IT. Without this a fresh machine falls back to
       // a size heuristic, and on a box with several similar builds that picks by size alone —
       // observed on ollama2, where gemma4-quadro:latest and gemma4-quadro-49k:latest are
@@ -939,18 +1009,38 @@ export async function runClientExpertSetup({ ask }) {
     // The skip is not a failure and says nothing extra; it has already printed its own line.
     if (!(e instanceof SkipModelQuestion)) {
       console.log(dim(`  (could not ask: ${e.message} — using the shared Ollama)`));
+      chosenModels = null;
     }
-    chosenModels = null;
+    // A SkipModelQuestion keeps whatever it set: undefined (already configured) or the skip.
+    chosenModels = chosenModels ?? null;
   }
+  // #301: skipped on purpose (up front, "s" at both servers, or Esc) → no model field is written.
+  const skipModels = Boolean(chosenModels?.skipped);
+  const loadPreset = Boolean(chosenModels?.loadPreset);
 
   try {
     const written = await seedSettings({
       apiDir,
       mongoUri,
       userId: creds.userId,
-      ...(chosenModels ? { models: chosenModels } : {}),
+      ...(chosenModels && !skipModels ? { models: chosenModels } : {}),
+      skipModels,
     });
-    if (Object.keys(written).length === 0) {
+    // #301: the keys typed for the servers, saved through the API now that their rows exist.
+    // Reported by host, never by value.
+    if (!skipModels && chosenModels?.keys?.length) {
+      for (const r of await saveSetupKeys({ workerKey: creds.workerKey, models: chosenModels })) {
+        console.log(r.ok
+          ? "  " + cyan("✓ API key stored") + dim(` for ${r.host} — the server's default key`)
+          : "  " + yellow("⚠ could not store the key") + dim(` for ${r.host} — add it in /model with ctrl+k`));
+      }
+    }
+    if (skipModels) {
+      console.log("");
+      console.log("  " + cyan("✓ Model setup skipped") + dim(loadPreset
+        ? " — the preset picker opens as soon as gu starts"
+        : " — set them any time with /model (or /load-presets)"));
+    } else if (Object.keys(written).length === 0) {
       console.log("  " + cyan("✓ Models and RAG") + dim(" — already configured, left alone"));
     } else {
       console.log(
@@ -997,5 +1087,7 @@ export async function runClientExpertSetup({ ask }) {
     dim("\n  machine. The API restarts with `gu-cli api start`; its log is") +
     dim(`\n  ${API_LOG_FILE}\n`)
   );
-  return { complete: true, stoppedAt: null };
+  // #301: the caller opens /load-presets once the terminal exists — the picker, the plan and the
+  // confirmation are that command's, not rebuilt here.
+  return { complete: true, stoppedAt: null, ...(loadPreset ? { loadPreset: true } : {}) };
 }

package/gu-repl.mjs

@@ -96,6 +96,7 @@ import {
   physicalRows,
   inputPhysicalRows,
   buildFooterRows,
+  pasteHint,
   footerDrawSeq,
   footerEraseSeq,
   clearBlockSeq,
@@ -632,6 +633,10 @@ function reloadWorkerEnv() {
 // first-run branch also runs one — without this the same walkthrough printed twice in a single
 // run, MongoDB instructions and all. Reported live on Windows 11.
 let clientExpertRanThisProcess = false;
+// #301: setup chose "Load a saved preset" — main() opens /load-presets before the first prompt.
+// Declared HERE, above the first-run block: that block runs at module top level, before any
+// declaration further down exists.
+let openPresetsAtStart = false;
 
 if (!workerKey || !apiBase) {
   if (process.stdin.isTTY && process.stdout.isTTY) {
@@ -728,7 +733,12 @@ if (!workerKey || !apiBase) {
         await saveState({ ...(await loadState()), chosenMode: mode0 ?? "client" });
         if (mode0 === "client-expert") {
           clientExpertRanThisProcess = true;
-          const setup = await runClientExpertSetup({ ask: ask0 });
+          // #301/#300: Esc-aware and masked readers on the same rl0 — the model questions offer
+          // Esc, and a key or a password must not echo.
+          const { setupPrompts } = await import("./setup-prompts.mjs");
+          const sp = setupPrompts(rl0, { style: accent });
+          const setup = await runClientExpertSetup({ ask: ask0, askStep: sp.askStep, askSecret: sp.askSecret });
+          if (setup.loadPreset) openPresetsAtStart = true;
           // STOP when setup cannot go further.
           //
           // This used to fall through to the hosted sign-in, on the theory that "this machine
@@ -2376,6 +2386,9 @@ const footerRows = () =>
     identity: identityLineText(),
     token: tokenLineText(),
     mode: modeLineText(),
+    // How to paste here (issue #67): the platform's text key, plus gu's image key when the coder
+    // can take an image.
+    modeHint: pasteHint({ images: coderTakesImages() }),
     // Its own row (#54), sized to the window so the fix it names is never the part cut off.
     notice: imageNotice
       ? orange("⚠ " + fitImageNotice(imageNotice, (process.stdout.columns || 80) - visibleLen(GUTTER) - 1))
@@ -5231,15 +5244,35 @@ async function reconfigureOllamaServer() {
 
   /** Load a box's models THROUGH THE PROXY (#160) — a bare fetch is what fails on a restricted
    *  network, and it fails as "no models", which is the wrong story entirely. */
-  const load = async (n) => {
+  const load = async (n, key = "") => {
     const res = await withPendingStatus(`loading models from ${n.host}`, () =>
-      proxyFetch(os.tagsUrlFor(n), { signal: AbortSignal.timeout(8000) })
+      proxyFetch(os.tagsUrlFor(n), {
+        signal: AbortSignal.timeout(8000),
+        // #301: the key typed for this server; absent → the request is what it always was.
+        ...(key ? { headers: { Authorization: `Bearer ${key}` } } : {}),
+      })
     );
     // The status is kept: a 404 here means "answered, but not an Ollama" (#43), not "unreachable".
     if (!res.ok) throw Object.assign(new Error(`HTTP ${res.status}`), { httpStatus: res.status });
     return am.parseOllamaTags(await res.json().catch(() => null));
   };
 
+  // #301: the way out, said under every server question (full once, short after), and the keys
+  // typed for servers, by host — saved against their rows once the settings are written.
+  const ui = await import("./model-setup-ui.mjs");
+  const hint = ui.createHinter();
+  const typedKeys = new Map();
+  const askKeyFor = async (host) => {
+    if (typedKeys.has(host)) return typedKeys.get(host); // same server for both roles → asked once
+    console.log(dim(`    ${hint()}`));
+    // askSecret: masked, kept out of history; Esc throws PromptCancelled → /model is cancelled
+    // with nothing changed, which is what "skip all" means here.
+    const k = (await askSecret(`  API key for ${host} (Enter for none): `)).trim();
+    typedKeys.set(host, k);
+    console.log(GUTTER + dim(ui.keyConfirmation(host, k)));
+    return k;
+  };
+
   /** Ask for one server and load it. Returns {normalized, models} or null (declined/failed). */
   const askServer = async (label, dflt, { require = false, short = "server", role = "coder" } = {}) => {
     for (let attempt = 0; attempt < 3; attempt++) {
@@ -5251,13 +5284,15 @@ async function reconfigureOllamaServer() {
       // — normalizeOllamaUrl adds it — and displayUrl round-trips, so what is shown can be fed
       // straight back as the default.
       console.log(dim(`  ${label} — Enter keeps ${os.displayUrl(dflt)}`));
+      console.log(dim(`    ${hint()}`));
       // THE ROW MUST SAY WHICH SERVER IT IS ASKING FOR. It said a bare "server:" — chosen to
       // fit the frozen row, which traded away the one thing the label was for. Two questions
       // in a row, both reading "server:", and the reader cannot tell which one they are
       // answering (reported: "it should say 'Agent + Embedder server' then 'Coding Server',
       // it only says 'server:'"). `short` is the role in the fewest words that still name it.
       const typed = (await ask(`  ${short}: `)).trim();
-      if (/^(no|n|skip|-)$/i.test(typed)) return null;
+      // "s" is the advertised skip (#301); the older words still work.
+      if (ui.readStepAnswer(typed).kind === "skip") return null;
       // EVERY READING OF A BARE HOSTNAME, in order. Typing "ollama2.gomarsic.cc" means
       // https://…:443 behind a proxy, while "192.168.1.40" means http://…:11434 — one guess
       // is right for one of them and produces a timeout that looks like a dead server for the
@@ -5270,15 +5305,33 @@ async function reconfigureOllamaServer() {
       let n = null;
       let models = null;
       let lastErr = null;
-      for (const cand of candidates) {
-        try {
-          models = await load(cand);
-          n = cand;
-          if (candidates.length > 1) console.log(dim(`  using ${os.displayUrl(cand.url)}`));
-          break;
-        } catch (err) {
-          lastErr = err;
+      // #301: a TYPED public address may need a key — asked before listing, so a server that
+      // needs one can list its models. A LAN box is never asked.
+      let key = "";
+      if (ui.shouldAskKey({ typed, host: candidates[0].host })) key = await askKeyFor(candidates[0].host);
+      const tryAll = async () => {
+        for (const cand of candidates) {
+          try {
+            models = await load(cand, key);
+            n = cand;
+            if (candidates.length > 1) console.log(dim(`  using ${os.displayUrl(cand.url)}`));
+            return;
+          } catch (err) {
+            lastErr = err;
+          }
         }
+      };
+      await tryAll();
+      // Refused for want of credentials: ask now, whatever the address looked like, and list again.
+      if (!n && ui.needsKeyAfterStatus(lastErr?.httpStatus) && !key) {
+        console.log(yellow(`  ${candidates[0].host} needs an API key to list its models.`));
+        typedKeys.delete(candidates[0].host);
+        key = await askKeyFor(candidates[0].host);
+        if (key) await tryAll();
+      }
+      if (!n && ui.needsKeyAfterStatus(lastErr?.httpStatus)) {
+        console.log(red(`  ${candidates[0].host} refused the request (HTTP ${lastErr.httpStatus})${key ? " — that key was not accepted" : ""}.`));
+        continue;
       }
       if (!n) {
         if (lastErr?.httpStatus === 404) {
@@ -5305,7 +5358,7 @@ async function reconfigureOllamaServer() {
         const need = os.checkRequired(models);
         if (!need.ok) {
           for (const l of os.describeNotReady(n.host, need.missing)) console.log(yellow(`  ${l}`));
-          console.log(dim("  (or type 'no' to skip — you can set it later with /model)"));
+          console.log(dim("  (or type s to skip — you can set it later with /model)"));
           continue;
         }
         console.log(dim(`  ✓ ${n.host} has the ${os.REQUIRED_AGENT_PREFIX} family and the embedder`));
@@ -5328,10 +5381,10 @@ async function reconfigureOllamaServer() {
   if (agentOnProvider) {
     const host = hostOf(String(settings.agentModelUrl ?? ""));
     console.log(dim(`  The agent model is on ${host} (OpenAI-compatible) — kept as it is; change it with /agent-model.`));
-    console.log(dim("  Enter keeps the current address; type 'no' to skip."));
+    console.log(dim("  Enter keeps the current address."));
   } else {
     console.log(dim("  TWO servers may be used: the agent + embedder on one, the coder on another."));
-    console.log(dim("  Enter keeps the current address; type 'no' to skip a role."));
+    console.log(dim("  Enter keeps the current address."));
     agent = await askServer("Agent + embedding server", curAgent, {
       require: true,
       short: "agent + embed server",
@@ -5476,6 +5529,32 @@ async function reconfigureOllamaServer() {
     console.log(GUTTER + dim("if this machine's local API is old, restart it with `gu api restart`.\n"));
     return;
   }
+  // #301: THE KEYS TYPED FOR THE SERVERS, bound to their rows now that the rows exist (the API
+  // refuses a key for a row it does not have). Before the cloud check below, so a key typed for
+  // the Ollama cloud is not asked for a second time. Reported by host, never by value.
+  {
+    const used = [agent?.normalized?.url, coder?.normalized?.url].filter(Boolean);
+    // By HOSTNAME: the key was asked for urlCandidates' host, which carries no port, while a URL's
+    // .host does — box.example.com:8443 would otherwise never match its own key.
+    const hostnameOf = (u) => { try { return new URL(u).hostname; } catch { return ""; } };
+    const pending = [...typedKeys].filter(([host, k]) => k && used.some((u) => hostnameOf(u) === host));
+    if (pending.length) {
+      const fresh = await withPendingStatus("storing the key", fetchWorkerSettings);
+      const ps = await import("./coding-provider-setup.mjs");
+      for (const [host, k] of pending) {
+        const url = used.find((u) => hostnameOf(u) === host);
+        const found = ps.providerRowForUrl(ps.existingBackendRows(fresh ?? {}), url);
+        if (!found) {
+          console.log(yellow(`  no server row holds ${host} yet — add its key with ctrl+k in /model.`));
+          continue;
+        }
+        const ok = await withPendingStatus("saving the key", () => addCodingKey(host, k, found.id));
+        console.log(ok
+          ? GUTTER + dim(`✓ key stored for ${host} — the server's default key`)
+          : red(`  couldn't store the key for ${host} — add it with ctrl+k.`));
+      }
+    }
+  }
   // THE OLLAMA CLOUD NEEDS ITS OWN KEY. Reported: choosing https://ollama.com here listed its 20 models
   // (that list is public) and saved, without a key — and the next turn failed "REJECTED the coding API
   // key", having borrowed an unrelated sk-… key. Asked for now, bound to the row just saved.
@@ -10869,8 +10948,18 @@ async function main() {
       // recorded, so once the choice was saved this block was skipped and the plan sat on disk
       // untouched. Picking it up here is what makes the sentence true.
       const { runClientExpertSetup } = await import("./client-expert-run.mjs");
-      const setup = await runClientExpertSetup({ ask });
+      const { SKIP_ALL } = await import("./model-setup-ui.mjs");
+      // #301: keys (and the MongoDB password) through the REPL's own masked prompt; a cancelled
+      // one means "skip the rest", not a crash of the setup.
+      const toSkipAll = (e) => (e instanceof PromptCancelled ? SKIP_ALL : Promise.reject(e));
+      const setup = await runClientExpertSetup({
+        ask,
+        // Esc at a model question throws PromptCancelled here; in setup it means "skip all".
+        askStep: (q) => ask(q).catch(toSkipAll),
+        askSecret: (q) => askSecret(q).catch(toSkipAll),
+      });
       if (setup?.complete) reloadWorkerEnv();
+      if (setup?.loadPreset) openPresetsAtStart = true;
     }
   } catch {
     /* never block the REPL on the mode question — the banner still shows what is configured */
@@ -11621,6 +11710,17 @@ async function main() {
   // rows it pushes up are real output rather than half-drawn setup.
   syncBarPinning();
 
+  // #301: setup's "Load a saved preset" — the picker opens now that the terminal exists. The whole
+  // /load-presets flow (the list, the plan, the confirmation, the key) is that command's own.
+  if (openPresetsAtStart) {
+    openPresetsAtStart = false;
+    try {
+      await runLoadPresetsCommand("/load-presets");
+    } catch (e) {
+      console.log(GUTTER + dim(`(could not open the presets: ${e?.message ?? e} — run /load-presets)`));
+    }
+  }
+
   for (;;) {
     stopPendingStatus(); // nothing from a previous turn may still be animating (task #140)
     // The bar and the input line live in the frozen rows at the bottom of the window (task

package/model-setup-ui.mjs

@@ -0,0 +1,114 @@
+/**
+ * THE WAY OUT OF THE MODEL QUESTIONS, and the key question that follows a typed server (#301).
+ *
+ * Reported: at "Agent + embedding server [https://ollama1.gomarsic.cc]:" there was no visible way
+ * to NOT choose. Enter takes the default server; a decline existed ("n", "no", "skip", "-") but no
+ * prompt said so, and one hint even claimed "press Enter with no address to skip", which was the
+ * opposite of what Enter does. Some people want no model setup at all and to load a saved preset.
+ *
+ * The decisions, agreed with the user (2026-09-29):
+ *   · ASK ONCE, UP FRONT — guided / load a preset / skip. Enter = guided, so today's flow is one
+ *     keypress away and unchanged.
+ *   · TWO WAYS OUT, NOT FIVE — "s" skips a step, Esc skips all model setup. The old words still
+ *     work, silently.
+ *   · FULL HINT ONCE, THEN SHORT — a hint under every prompt is noise by the fourth.
+ *   · A KEY ONLY WHEN ONE MAY BE NEEDED — a LAN Ollama box never needs one, a public https
+ *     address may, and a server that answers 401/403 certainly does.
+ *   · CONFIRM THE KEY WITHOUT SHOWING IT — a masked prompt gives no sign it took anything.
+ *
+ * PURE. Everything here is strings in, strings out, so the whole table is a test.
+ */
+import { hostLocality } from "./coding-provider-setup.mjs";
+
+/**
+ * What an Esc-aware prompt resolves to when Esc is pressed. A string no one can type (it starts
+ * with NUL), so it can travel through every `ask` that returns strings without a new type.
+ */
+export const SKIP_ALL = "\u0000skip-all";
+
+/** Esc, as readline reports it: name "escape" (meta:true on most terminals — accept either). */
+export function isEscapeKey(key) {
+  return Boolean(key) && (key.name === "escape" || (key.meta && key.sequence === "\x1b"));
+}
+
+/**
+ * One answer at a model prompt → what it means.
+ *   { kind: "all" }          Esc: skip all model setup
+ *   { kind: "skip" }         "s" (or the older n / no / skip / -): skip this step
+ *   { kind: "answer", text } anything else, including "" (= the default)
+ */
+export function readStepAnswer(raw) {
+  if (raw === SKIP_ALL) return { kind: "all" };
+  const text = String(raw ?? "").trim();
+  if (/^(s|n|no|skip|-)$/i.test(text)) return { kind: "skip" };
+  return { kind: "answer", text };
+}
+
+export const FULL_HINT = "Enter = use this · s = skip this step · Esc = skip all model setup";
+export const SHORT_HINT = "s skip · esc skip all";
+
+/** A hinter: the full hint the first time it is asked for, the short one after. */
+export function createHinter() {
+  let shown = false;
+  return () => {
+    if (shown) return SHORT_HINT;
+    shown = true;
+    return FULL_HINT;
+  };
+}
+
+/**
+ * Should typing THIS address be followed by "API key for <host>"?
+ *
+ * Only for an address that was TYPED (Enter on the default is today's path and stays one key),
+ * and only when the host is public: a LAN box (192.168.x, 10.x, *.local, a bare hostname,
+ * localhost) is an Ollama that takes no key, and asking there is a question with one answer.
+ * A server that answers 401/403 is asked regardless — see needsKeyAfterStatus.
+ */
+export function shouldAskKey({ typed, host }) {
+  if (!String(typed ?? "").trim()) return false;
+  return hostLocality(host) === "public";
+}
+
+/** The server refused to list its models without credentials. */
+export function needsKeyAfterStatus(status) {
+  return status === 401 || status === 403;
+}
+
+/** The last 4 characters, in the bar's own style — enough to tell keys apart, not to use one. */
+export function keyTail(key) {
+  const k = String(key ?? "").trim();
+  return k.length > 4 ? `····${k.slice(-4)}` : "····";
+}
+
+/** The line printed after the masked prompt, so the person knows whether it took anything. */
+export function keyConfirmation(host, key) {
+  return String(key ?? "").trim()
+    ? `✓ key saved for ${host} (${keyTail(key)})`
+    : `no key for ${host}`;
+}
+
+/**
+ * The up-front question. `presets` = how many saved presets there are: with none, option 2 still
+ * shows (so the feature is discoverable) but says how to make one instead of offering nothing.
+ */
+export function modelSetupMenu({ presets = 0 } = {}) {
+  return [
+    "How do you want to set up the models?",
+    "  1  Guided — pick the servers and models   (Enter)",
+    presets > 0
+      ? `  2  Load a saved preset   (${presets} saved)`
+      : "  2  Load a saved preset   (none saved yet — /save-preset makes one)",
+    "  3  Skip for now — set them later with /model",
+  ];
+}
+
+/** An answer to the up-front question → "guided" | "preset" | "skip", or null to ask again. */
+export function parseModelSetupChoice(raw) {
+  if (raw === SKIP_ALL) return "skip";
+  const t = String(raw ?? "").trim().toLowerCase();
+  if (t === "" || t === "1" || t === "guided" || t === "g") return "guided";
+  if (t === "2" || t === "preset" || t === "p") return "preset";
+  if (t === "3" || t === "s" || t === "skip" || t === "n" || t === "no" || t === "-") return "skip";
+  return null;
+}

package/ollama-setup.mjs

@@ -21,6 +21,14 @@
 import { isLikelyEmbedder } from "./agent-model-command.mjs";
 import { EMBED_CHOICES } from "./embed-model-command.mjs";
 import { isCancelWord } from "./coding-provider-setup.mjs";
+import {
+  SKIP_ALL,
+  createHinter,
+  keyConfirmation,
+  needsKeyAfterStatus,
+  readStepAnswer,
+  shouldAskKey,
+} from "./model-setup-ui.mjs";
 
 /** Ollama's native port, used when someone types a bare host or an IP with no port. */
 export const OLLAMA_DEFAULT_PORT = 11434;
@@ -649,21 +657,83 @@ export async function askOllamaSetup(
     // Injected so the tests can drive it; defaults to a real request with a short deadline,
     // because this runs while someone is waiting at a prompt.
     probeStatus = defaultProbeStatus,
+    // #301: the MASKED prompt for an API key. Without one no key is ever asked — a secret is
+    // never read through a prompt that echoes it.
+    askSecret = null,
+    // #301: the hint under each model prompt — full the first time, short after.
+    hint = createHinter(),
   } = {},
 ) {
+  // #301: every key typed for a server, by its HOSTNAME. "" = asked, left empty. Not by URL: the
+  // key is asked before listing, for the first reading of what was typed, and a different reading
+  // (another port or scheme) may be the one that answers.
+  const keys = new Map();
+  const SKIPPED = { skipped: true, keys: [] };
+  // #301: a step SKIPPED ON PURPOSE, as against a server that never answered. Nothing chosen
+  // because of a skip means "leave the models unset"; nothing chosen because nothing answered
+  // stays null, and the caller falls back to the shared box as it always has.
+  let declined = false;
+  // Dim, like the other guidance lines under a question; one line, above the prompt it explains.
+  const say = (h) => log(`    \x1b[2m${h}\x1b[0m`);
+
+  /**
+   * The key question for a TYPED address, before its models are listed (so a server that needs
+   * one can list them). Returns the key, "" for none, or SKIP_ALL.
+   */
+  const askKeyFor = async (host) => {
+    if (keys.has(host)) return keys.get(host); // same server for both roles → asked once
+    if (typeof askSecret !== "function") return "";
+    say(hint());
+    const raw = await askSecret(`  API key for ${host} (Enter for none): `);
+    if (raw === SKIP_ALL) return SKIP_ALL;
+    const key = String(raw ?? "").trim();
+    keys.set(host, key);
+    log(`  ${keyConfirmation(host, key)}`);
+    return key;
+  };
+
+  /**
+   * List the models of what was typed (or the default), asking for a key when the address is
+   * public or the server refuses without one. { ok, normalized, models } | { failed } | SKIP_ALL.
+   */
+  const loadServer = async (typed, fallbackUrl, reuse) => {
+    const raw = typed || fallbackUrl;
+    const first = urlCandidates(raw)[0];
+    if (reuse && first && reuse.normalized.url === first.url) return reuse;
+    let key = "";
+    if (first && shouldAskKey({ typed, host: first.host })) {
+      key = await askKeyFor(first.host);
+      if (key === SKIP_ALL) return SKIP_ALL;
+    }
+    let tried = await loadFirstThatAnswers(raw, fetchTags, log, key);
+    // A server that refused for want of credentials: ask now, whatever the address looked like,
+    // and list again with the key. Once — a second refusal is a wrong key, reported as such.
+    if (tried?.failed && needsKeyAfterStatus(tried.status) && !key && first) {
+      log(`  ${first.host} needs an API key to list its models.`);
+      keys.delete(first.host);
+      key = await askKeyFor(first.host);
+      if (key === SKIP_ALL) return SKIP_ALL;
+      if (key) tried = await loadFirstThatAnswers(raw, fetchTags, log, key);
+    }
+    return tried;
+  };
+
   // ---- SERVER 1: the agent model and the embedder -------------------------------------
   // These two are REQUIRED and not a free choice (see REQUIRED_AGENT_MODEL). A box without
   // them is "not ready" rather than "wrong": it may still be a perfectly good coder host, which
   // is why this refusal does not end the flow.
   let agent = null;
   for (let attempt = 0; attempt < attempts && !agent; attempt++) {
-    const typed = (await ask(`  Agent + embedding server [${displayUrl(defaultUrl)}]: `)).trim();
-    if (isDecline(typed)) break;
-    const tried = await loadFirstThatAnswers(typed || defaultUrl, fetchTags, log);
+    say(hint());
+    const a = readStepAnswer(await ask(`  Agent + embedding server [${displayUrl(defaultUrl)}]: `));
+    if (a.kind === "all") return SKIPPED;
+    if (a.kind === "skip") { declined = true; break; }
+    const tried = await loadServer(a.text, defaultUrl, null);
+    if (tried === SKIP_ALL) return SKIPPED;
     if (!tried || tried.failed) {
       // One explanation, the best one available: the provider message when we recognise the
       // address, otherwise the reachability advice we were going to give anyway.
-      const explained = await explainIfOpenAi(typed || defaultUrl, probeStatus, log, describeOpenAiAgent);
+      const explained = await explainIfOpenAi(a.text || defaultUrl, probeStatus, log, describeOpenAiAgent);
       if (!explained) for (const l of tried?.failed ?? []) log(`  ${l}`);
       continue;
     }
@@ -676,7 +746,9 @@ export async function askOllamaSetup(
     const need = checkRequired(models);
     if (!need.ok) {
       for (const l of describeNotReady(normalized.host, need.missing)) log(`  ${l}`);
-      log("  (or press Enter with no address to skip — you can set it later with /model)");
+      // #301: this used to tell people to press Enter to skip — but Enter takes the DEFAULT
+      // server. "s" is the skip.
+      log("  (or type s to skip — you can set it later with /model)");
       continue;
     }
     log(`  ✓ ${normalized.host} has the ${REQUIRED_AGENT_PREFIX} family and the embedder`);
@@ -690,18 +762,21 @@ export async function askOllamaSetup(
   const coderDefault = agent?.normalized?.url ?? defaultUrl;
   let coder = null;
   for (let attempt = 0; attempt < attempts && !coder; attempt++) {
-    const typed = (await ask(`  Coding-model server [${displayUrl(coderDefault)}]: `)).trim();
-    if (isDecline(typed)) break;
+    say(hint());
+    const a = readStepAnswer(await ask(`  Coding-model server [${displayUrl(coderDefault)}]: `));
+    if (a.kind === "all") return SKIPPED;
+    if (a.kind === "skip") { declined = true; break; }
     // Same box as the agent server → reuse the list we already have rather than fetching twice.
-    const same = normalizeOllamaUrl(typed || coderDefault);
+    const same = normalizeOllamaUrl(a.text || coderDefault);
     const tried =
       agent && same && same.url === agent.normalized.url
         ? { normalized: same, models: agent.models }
-        : await loadFirstThatAnswers(typed || coderDefault, fetchTags, log);
+        : await loadServer(a.text, coderDefault, agent);
+    if (tried === SKIP_ALL) return SKIPPED;
     if (!tried || tried.failed) {
       // One explanation, the best one available: the provider message when we recognise the
       // address, otherwise the reachability advice we were going to give anyway.
-      const explained = await explainIfOpenAi(typed || coderDefault, probeStatus, log, describeOpenAiCoder);
+      const explained = await explainIfOpenAi(a.text || coderDefault, probeStatus, log, describeOpenAiCoder);
       if (!explained) for (const l of tried?.failed ?? []) log(`  ${l}`);
       continue;
     }
@@ -718,7 +793,7 @@ export async function askOllamaSetup(
   // A real answer, not a failure. The machine finishes setup unconfigured, the bar shows the
   // roles as unset, and the first question says so instead of hanging — which is the entire
   // reason declining is allowed to be this easy.
-  if (!agent && !coder) return null;
+  if (!agent && !coder) return declined ? SKIPPED : null;
 
   // ---- PICK THE MODELS -----------------------------------------------------------------
   // THE AGENT IS CHOSEN, not assumed (user, 2026-09-06). The gate above proved the family is
@@ -729,7 +804,6 @@ export async function askOllamaSetup(
   // Seed the embedder the box ACTUALLY has: the shipped default when present, else whichever
   // accepted embedder passed the gate — a qwen3-embedding-only box must not be told it now
   // embeds with a model it never had.
-  const embed = agent ? defaultEmbedModel(agent.models) || REQUIRED_EMBED_MODEL : null;
   let chat = "";
   if (agent) {
     const cands = agentCandidates(agent.models);
@@ -741,13 +815,18 @@ export async function askOllamaSetup(
       log("  AGENT model — routes every turn and writes the plain replies");
       for (const row of renderModelMenu(cands, { defaultModel: agentDefault, formatSize })) log(row);
       for (let t = 0; t < attempts && !chat; t++) {
-        const answer = await ask(`  agent [${agentDefault}]: `);
-        chat = parseMenuChoice(answer, cands, agentDefault) ?? "";
+        say(hint());
+        const a = readStepAnswer(await ask(`  agent [${agentDefault}]: `));
+        if (a.kind === "all") return SKIPPED;
+        // #301: "s" here skips the AGENT role — its server was chosen, its model is not.
+        if (a.kind === "skip") { agent = null; break; }
+        chat = parseMenuChoice(a.text, cands, agentDefault) ?? "";
         if (!chat) log(`  no model called that — type its number, or Enter for ${agentDefault}`);
       }
-      chat = chat || agentDefault;
+      if (agent) chat = chat || agentDefault;
     }
   }
+  const embed = agent ? defaultEmbedModel(agent.models) || REQUIRED_EMBED_MODEL : null;
   let code = "";
   let extras = [];
   if (coder) {
@@ -756,20 +835,37 @@ export async function askOllamaSetup(
     log("  CODING model — writes the code; worth waiting for");
     for (const row of renderModelMenu(coder.models, { defaultModel: roles.code, formatSize })) log(row);
     for (let t = 0; t < attempts && !code; t++) {
-      const answer = await ask(`  code [${roles.code}]: `);
-      code = parseMenuChoice(answer, coder.models, roles.code) ?? "";
+      say(hint());
+      const a = readStepAnswer(await ask(`  code [${roles.code}]: `));
+      if (a.kind === "all") return SKIPPED;
+      if (a.kind === "skip") { coder = null; break; }
+      code = parseMenuChoice(a.text, coder.models, roles.code) ?? "";
       if (!code) log(`  no model called that — type its number, or Enter for ${roles.code}`);
     }
-    code = code || roles.code;
+    if (coder) code = code || roles.code;
 
-    const rest = coder.models.filter((m) => !isLikelyEmbedder(m) && m.model !== code);
+    const rest = coder ? coder.models.filter((m) => !isLikelyEmbedder(m) && m.model !== code) : [];
     if (rest.length) {
       log("");
       log("  Also offer in /model?  (numbers separated by commas, or Enter for none)");
       for (const row of renderModelMenu(rest, { formatSize })) log(row);
-      extras = parseMultiChoice(await ask("  also: "), rest);
+      say(hint());
+      const a = readStepAnswer(await ask("  also: "));
+      if (a.kind === "all") return SKIPPED;
+      extras = a.kind === "skip" ? [] : parseMultiChoice(a.text, rest);
     }
   }
+  // Both roles skipped at the model menus: as much a decision as skipping both servers.
+  if (!agent && !coder) return SKIPPED;
+
+  // #301: the keys typed, only for the servers actually used, never the empty ones — each under
+  // the URL that ANSWERED, which is the one the settings rows are written with.
+  const used = [agent?.normalized, coder?.normalized].filter(Boolean);
+  const keyList = [];
+  for (const [host, key] of keys) {
+    const n = key && used.find((u) => u.host === host);
+    if (n && !keyList.some((k) => k.url === n.url)) keyList.push({ url: n.url, key });
+  }
 
   // HALF-CONFIGURED IS A REAL STATE and must be representable. Someone with an agent box but no
   // coder yet, or a coder but no agent box, has made progress worth keeping — forcing both or
@@ -786,6 +882,7 @@ export async function askOllamaSetup(
     ...(embed ? { embed } : {}),
     altCoders: (extras ?? []).filter((n) => n !== code),
     ready: Boolean(agent && coder),
+    ...(keyList.length ? { keys: keyList } : {}),
   };
 }
 
@@ -848,7 +945,7 @@ async function explainIfOpenAi(raw, probeStatus, log, describe) {
   return true;
 }
 
-async function loadFirstThatAnswers(raw, fetchTags, log) {
+async function loadFirstThatAnswers(raw, fetchTags, log, apiKey = "") {
   const candidates = urlCandidates(raw);
   if (!candidates.length) {
     return { failed: ["that is not a server address — try 192.168.1.40, ollama.local, or a full URL"] };
@@ -856,7 +953,10 @@ async function loadFirstThatAnswers(raw, fetchTags, log) {
   let last = null;
   for (const normalized of candidates) {
     try {
-      const models = await fetchTags(tagsUrlFor(normalized));
+      // #301: the key goes along only when there is one — a keyless call stays byte-identical.
+      const models = apiKey
+        ? await fetchTags(tagsUrlFor(normalized), { apiKey })
+        : await fetchTags(tagsUrlFor(normalized));
       // Say WHICH reading answered, but only when we had to guess — otherwise it is noise
       // repeating what the user just typed.
       if (candidates.length > 1) log(`  using ${displayUrl(normalized.url)}`);
@@ -869,6 +969,11 @@ async function loadFirstThatAnswers(raw, fetchTags, log) {
   // NOT PRINTED HERE ANY MORE. "check that Ollama is running there" is exactly the wrong thing
   // to say about a correct address for a hosted provider, and the caller is the only one that
   // knows whether it found a better explanation. It prints one message or the other, never both.
-  return { failed: [`could not reach ${candidates[0].host}: ${networkReason(last)}`,
+  // #301: an HTTP status (401/403 = needs a key) travels with the failure so the caller can ask.
+  const status = Number(last?.status ?? last?.httpStatus) || 0;
+  if (needsKeyAfterStatus(status)) {
+    return { status, failed: [`${candidates[0].host} refused the request (HTTP ${status}) — ${apiKey ? "that key was not accepted" : "it needs an API key"}.`] };
+  }
+  return { status, failed: [`could not reach ${candidates[0].host}: ${networkReason(last)}`,
                     "check the address, or that Ollama is running there and listening on the network."] };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gu-cli",
-  "version": "1.0.768",
+  "version": "1.0.769",
   "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",
@@ -50,6 +50,8 @@
     "gu-cli.mjs",
     "gu-repl.mjs",
     "step-tokens.mjs",
+    "model-setup-ui.mjs",
+    "setup-prompts.mjs",
     "terminal-hover.mjs",
     "terminal-layout.mjs",
     "terminal-viewport.mjs",

package/setup-prompts.mjs

@@ -0,0 +1,82 @@
+/**
+ * THE FIRST-RUN PROMPTS THAT PLAIN rl.question CANNOT BE (#301, #300).
+ *
+ * First-run setup runs before the REPL exists, on its own readline (gu-repl.mjs `rl0`), and every
+ * question there was `rl0.question` — which echoes. Two things need more than that:
+ *
+ *   · ESC. The model questions offer "Esc = skip all model setup". Esc submits nothing in readline,
+ *     so the pending question is cancelled through its AbortSignal and resolved with SKIP_ALL.
+ *   · A SECRET. An API key, or the MongoDB password (#300), must never reach the screen or the
+ *     scrollback. Readline's echo and line refresh are muted for the question, one "•" per
+ *     character is drawn instead (the only proof a keystroke registered), and the answer is taken
+ *     back out of readline's history — which keeps every submitted line, so the secret would
+ *     otherwise come back in plain text on the next press of Up.
+ *
+ * The REPL has its own askSecret with the same guarantees (task #127/#191); this is the version for
+ * the one stretch of the program that runs before it.
+ */
+import { SKIP_ALL, isEscapeKey } from "./model-setup-ui.mjs";
+
+/**
+ * One question on `rl`. Options: `secret` (mask + keep out of history), `esc` (Esc → SKIP_ALL).
+ * `style` decorates the label (the accent colour). Resolves with the answer string, or SKIP_ALL.
+ */
+export function askOn(rl, q, { secret = false, esc = false, style = (s) => s, input = process.stdin, output = process.stdout } = {}) {
+  return new Promise((resolve) => {
+    const shown = style(q);
+    const ac = new AbortController();
+    const origWrite = rl._writeToOutput;
+    const origRefresh = rl._refreshLine;
+    let done = false;
+
+    const finish = (value) => {
+      if (done) return;
+      done = true;
+      input.removeListener?.("keypress", onKey);
+      if (secret) {
+        rl._writeToOutput = origWrite;
+        rl._refreshLine = origRefresh;
+        if (Array.isArray(rl.history) && value && rl.history[0] === value) rl.history.shift();
+        rl.historyIndex = -1;
+      }
+      // A muted Enter printed no newline, and an Esc left the caret on the prompt's row.
+      if (secret || value === SKIP_ALL) output.write("\n");
+      resolve(value);
+    };
+
+    // Runs AFTER readline's own keypress handler (registered when rl was created), so rl.line is
+    // already the updated text when the bullets are drawn.
+    function onKey(_s, key) {
+      if (done) return;
+      if (esc && isEscapeKey(key)) {
+        ac.abort();
+        // The cancelled question leaves what was typed in rl.line; the next question must not
+        // start with it.
+        rl.line = "";
+        rl.cursor = 0;
+        finish(SKIP_ALL);
+        return;
+      }
+      if (secret && output.isTTY) {
+        output.write(`\r\x1b[2K${shown}${"•".repeat(String(rl.line ?? "").length)}`);
+      }
+    }
+
+    input.on?.("keypress", onKey);
+    // question() draws the label synchronously — mute only AFTER, or the label is muted too.
+    rl.question(shown, { signal: ac.signal }, (a) => finish(String(a ?? "")));
+    if (secret) {
+      rl._writeToOutput = () => {};
+      rl._refreshLine = () => {};
+    }
+  });
+}
+
+/** The three readers setup takes: plain, Esc-aware (model questions), masked (keys, passwords). */
+export function setupPrompts(rl, { style = (s) => s, input = process.stdin, output = process.stdout } = {}) {
+  return {
+    ask: (q) => askOn(rl, q, { style, input, output }),
+    askStep: (q) => askOn(rl, q, { esc: true, style, input, output }),
+    askSecret: (q) => askOn(rl, q, { secret: true, esc: true, style, input, output }),
+  };
+}

package/terminal-layout.mjs

@@ -468,6 +468,27 @@ const dim = (s) => `\x1b[2m${s}\x1b[0m`;
  * `identity` is optional so callers that have nothing to put there (and the tests that predate
  * it) keep producing the same rows as before.
  */
+/**
+ * HOW TO PASTE, for this platform (issue #67). Two different things share the word: TEXT is pasted
+ * by the terminal app (gu only sees the result), an IMAGE by gu's own keys (#284).
+ *
+ *   macOS    text ⌘V            image ctrl+v — a terminal's ⌘V sends nothing for an image
+ *   Windows  text ctrl+v        image alt+v  — Windows Terminal keeps ctrl+v for itself
+ *   Linux    text ctrl+shift+v  image ctrl+v
+ *
+ * The image half only when the coder can take one (a Claude coder); offering a key that then
+ * answers "images need a Claude coder" would be a hint that leads to a warning.
+ */
+export function pasteHint({ platform = process.platform, images = false } = {}) {
+  const text = platform === "darwin" ? "⌘V" : platform === "win32" ? "ctrl+v" : "ctrl+shift+v";
+  if (!images) return `${text} to paste`;
+  const image = platform === "win32" ? "alt+v" : "ctrl+v";
+  return `${text} paste · ${image} image`;
+}
+
+/** At least this many spaces between the mode text and the hint, or the hint is left out. */
+const HINT_MIN_GAP = 3;
+
 export function buildFooterRows({
   width,
   gutter = "   ",
@@ -475,16 +496,25 @@ export function buildFooterRows({
   identity = "",
   token = "",
   mode = "",
+  // Right-aligned on the mode row (issue #67), dim. DROPPED WHOLE when it does not fit: every
+  // footer row must stay one physical row (#109/#132/#138), and half a key name is worse than none.
+  modeHint = "",
   notice = "",
   missing = "",
 }) {
   const w = Math.max(20, width || 80);
+  const modeLeft = gutter + mode;
+  const hintGap = modeHint ? w - 1 - visibleLen(modeLeft) - visibleLen(modeHint) : -1;
+  const modeRow =
+    hintGap >= HINT_MIN_GAP
+      ? modeLeft + " ".repeat(hintGap) + dim(modeHint)
+      : clipVisible(modeLeft, w - 1);
   return [
     dim("─".repeat(w)),
     ...(rag ? [clipVisible(gutter + rag, w - 1)] : []),
     ...(identity ? [clipVisible(gutter + identity, w - 1)] : []),
     clipVisible(gutter + token, w - 1),
-    clipVisible(gutter + mode, w - 1),
+    modeRow,
     // A passing notice (the image-paste warning, #54) gets its OWN row, under the mode row — it
     // used to be appended to that row and was clipped at the right edge ("…pick one with /mo").
     // Present only while it shows; paintBar re-cuts the frozen zone when the count changes.