@tiens.nguyen/gu-cli 1.0.717 → 1.0.719

package/embed-model-command.mjs

@@ -26,6 +26,11 @@ export const EMBED_CHOICES = [
     dims: 4096,
     note: "best recall, ~18× slower to index",
   },
+  {
+    model: "qwen3-embedding:4b",
+    dims: 2560,
+    note: "strong recall, ~3× faster to index than 8b",
+  },
   {
     model: "nomic-embed-text:latest",
     dims: 768,
@@ -81,6 +86,32 @@ export function embedChoiceRows(current) {
   return rows;
 }
 
+/**
+ * THE /embed-model MENU — the agent-model parity half (#169 follow-up).
+ *
+ * Choosing WHICH embedder is only one of the decisions; the others are WHERE it runs and HOW it
+ * authenticates. A chat model swap is reversible and cheap, so /agent-model offers its server its
+ * own row; an embedder swap rewrites every vector on disk, so here the model and the server are
+ * ONE decision — but the server and its credential still deserve to be set on their own, for the
+ * same reason /agent-model lets you point at another OpenAI-compatible provider or re-key
+ * ollama.com: the embedder may live on a remote Ollama, on ollama.com, or behind an
+ * OpenAI-compatible /v1/embeddings, and each wants a key named so it stays readable.
+ *
+ * Pure, like the rest of this module: the REPL owns prompt/save; this owns the SHAPE of the menu.
+ * `host` is the host the embedder is currently configured against ("" = not yet); `keyRequired`
+ * is the REPL's read of isOllamaCloudUrl(url) || an OpenAI row — passed in, not derived, so this
+ * never re-imports the network-layer predicate.
+ */
+export function embedMenuOptions({ current = DEFAULT_EMBED_MODEL, host = "", keyRequired = false } = {}) {
+  const where = host || "this server";
+  return [
+    { action: "model", label: `switch the embedder model  (currently ${current})` },
+    { action: "ollama", label: "use an Ollama server for embedding…" },
+    { action: "provider", label: "use another OpenAI-compatible provider…" },
+    ...(keyRequired ? [{ action: "key", label: `enter a new API key for ${where}…` }] : []),
+  ];
+}
+
 /**
  * WHAT SWITCHING EMBEDDERS DOES TO WHAT IS ALREADY INDEXED — the half of this command that is
  * not a menu.

package/gonext_agent_chat.py

@@ -5316,6 +5316,39 @@ def _rag_embed_failure_hint(err) -> str:
     return f"{name}: {_clip(text, 120)}"
 
 
+# The API key for the EMBEDDING endpoint, resolved once per job from the API
+# (backend id "embed-ollama" - where /embed-model stores it, same store as coding/agent
+# keys). A module global because _embed() is a tiny hot path reached through the rag_*
+# tools - passing a key down that chain just for a header would churn every signature
+# above it for no behaviour.
+_RAG_EMBED_API_KEY = ""
+
+
+def _rag_resolve_embed_api_key(api_base: str, worker_key: str) -> str:
+    """Fetch the embedding-server API key from the shared key store, or "" when none is set.
+
+    The key was typed at /embed-model and POSTed to /api/worker/coding-keys under
+    backendId="embed-ollama" - reusing the coding-keys store means it already lands in
+    every mode (local file in Client Expert, Mongo for cloud users) with no new persistence.
+    The API masks keys in settings reads but returns the real secret here precisely so the
+    daemon that holds the worker key can authenticate to the embedder. Never raises: an
+    unreachable store means "" and the embed call goes unsigned, right for a keyless local
+    Ollama.
+    """
+    base = (api_base or "").rstrip("/")
+    if not base or not worker_key:
+        return ""
+    try:
+        from urllib.parse import urlencode
+        req = urllib.request.Request(
+            f"{base}/api/worker/coding-key?{urlencode({'backendId': 'embed-ollama'})}",
+            headers={"X-Worker-Key": worker_key}, method="GET")
+        with urllib.request.urlopen(req, timeout=8, context=_ssl_context()) as resp:
+            data = json.loads(resp.read().decode("utf-8", "replace") or "{}")
+            return (data.get("apiKey") or "").strip()
+    except Exception:  # noqa: BLE001
+        return ""
+
 def _embed(base: str, model: str, texts: list) -> list:
     """Embed a batch of texts. Auto-detects the endpoint from `base` (a bare host:port,
     an .../v1, or an Ollama host): tries OpenAI-compatible /v1/embeddings first (MLX
@@ -5328,9 +5361,15 @@ def _embed(base: str, model: str, texts: list) -> list:
     last_err = None
 
     def _post(url, payload, timeout):
+        # The embedding endpoint may be a KEYED server (cloud Ollama, a gateway) - the user
+        # typed its key at /embed-model; it rides as a Bearer token. A keyless local Ollama
+        # simply has _RAG_EMBED_API_KEY empty and the header is absent as before.
+        headers = {"Content-Type": "application/json"}
+        if _RAG_EMBED_API_KEY:
+            headers["Authorization"] = f"Bearer {_RAG_EMBED_API_KEY}"
         req = urllib.request.Request(
             url, data=json.dumps(payload).encode("utf-8"),
-            headers={"Content-Type": "application/json"}, method="POST",
+            headers=headers, method="POST",
         )
         with _proxy_urlopen(req, timeout=timeout, context=ctx) as resp:
             return json.loads(resp.read().decode("utf-8", "replace"))
@@ -6948,6 +6987,12 @@ def run_agent_chat(cfg):
     # the user never chose into the logs and the status table.
     rag_embed_model = (cfg.get("ragEmbedModel") or "").strip()
     rag_embed_url = (cfg.get("ragEmbedUrl") or "").strip()
+    # The RAG embedder may be a KEYED server (task: embed api key in /embed-model). Resolve
+    # its key once, from the shared key store (backendId "embed-ollama"), so every _embed()
+    # call this job carries the Bearer header. Empty for a keyless local Ollama - _embed()
+    # then sends no Authorization, exactly the old behaviour.
+    global _RAG_EMBED_API_KEY
+    _RAG_EMBED_API_KEY = _rag_resolve_embed_api_key(worker_api_base, worker_api_key) if rag_embed_url else ""
     try:
         rag_top_k = int(cfg.get("ragTopK") or 6)
     except (TypeError, ValueError):

package/gu-repl.mjs

@@ -132,7 +132,7 @@ import {
 import { createHoverController, applyToggleShift } from "./terminal-hover.mjs";
 // The required pair, imported rather than re-typed: the startup "no models" message names them,
 // and a second copy of these strings would drift from the check that enforces them.
-import { REQUIRED_AGENT_MODEL, REQUIRED_AGENT_PREFIX, REQUIRED_EMBED_MODEL } from "./ollama-setup.mjs";
+import { ACCEPTED_EMBED_MODELS, REQUIRED_AGENT_MODEL, REQUIRED_AGENT_PREFIX } from "./ollama-setup.mjs";
 // The brand accent — indigo, the same token the web app paints its wordmark with. It is NOT a
 // plain SGR code: terminals disagree about colour, so accent.mjs picks 24-bit, 256 or the
 // sixteen-colour magenta from what this one actually claims to support.
@@ -781,7 +781,7 @@ const COMMANDS = [
   // what made /rag confusing, and it did the same here: reported as "why do we need /provider
   // outside, it is confused". The command still works and still does the same thing.
   { name: "/agent-model", desc: "switch the AGENT model (the one that talks) — saved on this machine" },
-  { name: "/embed-model", desc: "switch the RAG EMBEDDING model — re-indexes what is already indexed" },
+  { name: "/embed-model", desc: "switch the RAG EMBEDDING model (nomic-embed-text / qwen3-embedding) and its server — re-indexes what is already indexed; supports a remote URL + API key" },
   { name: "/test-auto", desc: "toggle auto-test (verify & fix until it passes) for this folder" },
   // ONE command, three answers. /rag-local and /rag-cloud still work — they are in people's
   // fingers — but they are HIDDEN_COMMANDS now, because offering three doors into one setting
@@ -5075,7 +5075,7 @@ async function reconfigureOllamaServer() {
       agentModel: chat,
       ragEnabled: true,
       ragEmbedUrl: agent.normalized.url,
-      ragEmbedModel: os.REQUIRED_EMBED_MODEL,
+      ragEmbedModel: os.defaultEmbedModel?.(agent.models) ?? os.REQUIRED_EMBED_MODEL,
     });
   }
   if (coder) {
@@ -5161,7 +5161,7 @@ async function reconfigureOllamaServer() {
   console.log(accent("  ✓ models saved"));
   if (agent) {
     console.log(dim(`      chat   ${chat}  @ ${agent.normalized.host}`));
-    console.log(dim(`      RAG    ${os.REQUIRED_EMBED_MODEL}  @ ${agent.normalized.host}`));
+    console.log(dim(`      RAG    ${os.defaultEmbedModel?.(agent.models) ?? os.REQUIRED_EMBED_MODEL}  @ ${agent.normalized.host}`));
   } else {
     console.log(dim("      chat   — not set (agent server skipped)"));
   }
@@ -5171,7 +5171,11 @@ async function reconfigureOllamaServer() {
       : dim("      code   — not set (coding server skipped)")
   );
   if (extras.length) console.log(dim(`      also   ${extras.join(", ")}  — offered by /model`));
-  if (agent && String(settings.ragEmbedModel ?? "") !== os.REQUIRED_EMBED_MODEL) {
+  // Compare to the embedder this box was seeded with — an accepted OTHER embedder (a
+  // qwen3-embedding-only box) was written to settings above, so REQUIRED_EMBED_MODEL would
+  // falsely scream "changed" while the seeded value is exactly what settings now hold.
+  const seededEmbed = agent ? (os.defaultEmbedModel?.(agent.models) ?? os.REQUIRED_EMBED_MODEL) : "";
+  if (agent && String(settings.ragEmbedModel ?? "") !== seededEmbed) {
     console.log(dim("    the embedder changed — existing RAG indexes need rebuilding (/rag)."));
   }
   console.log(dim("    takes effect on your next question.\n"));
@@ -6270,9 +6274,8 @@ async function fetchWorkerSettings() {
     return null; // offline — callers fall back to showing what they know
   }
 }
-
 /**
- * `/embed-model` — switch the RAG embedder (task #169).
+ * `/embed-model` — switch the RAG embedder, the embed server, or the embed key (task #169).
  *
  * NOT THE SAME SHAPE AS /model, and the difference is the point. A coding model can be swapped
  * between turns with no consequences; an embedder decides the shape of every vector already on
@@ -6280,71 +6283,305 @@ async function fetchWorkerSettings() {
  * over two models returns a number, rag_search prints its top-k, and the model answers from it.
  * So this command shows what it is about to invalidate and asks, instead of just writing.
  *
+ * Same menu shape as /agent-model (#44) now that one embed setup is three decisions: WHICH model
+ * (model), WHERE it runs (ollama / an OpenAI-compatible provider) and HOW it authenticates (key).
+ * Only a model change rebuilds indexes — moving the SAME embedder to another server, or changing
+ * only its key, leaves every vector valid, so those paths save without the plan wall. The worker
+ * already speaks both dialects: gonext_agent_chat._embed() POSTs {base}/v1/embeddings first, then
+ * Ollama /api/embed and /api/embeddings, and sends the "embed-ollama" store key as a Bearer when
+ * one exists — so pointing at an OpenAI-compatible provider here needs no worker-side change.
+ *
  * The decisions live in embed-model-command.mjs; this is the terminal half only.
  */
-async function chooseEmbedModel() {
-  const ec = await import("./embed-model-command.mjs");
-  const settings = await withPendingStatus("reading your embedder", fetchWorkerSettings);
-  if (!settings) {
-    console.log(red("  couldn't reach the API to read your current embedder.\n"));
-    return;
-  }
-  const current = ec.currentEmbedModel(settings);
-  const rows = ec.embedChoiceRows(current);
-  console.log(dim(`  Embedding model  (currently ${current})`));
-  console.log(dim(`  Choose the embedder  (${PICK_HINT}):`));
-  const labels = rows.map(
-    (r) => `${r.model}${r.dims ? dim(`  · ${r.dims}d`) : ""}${dim(`  · ${r.note}`)}` +
-      (r.current ? accent("  (current)") : "")
+
+// THE SAVE, ONE WAY. Every sub-flow ends at the same write so the failure wording and the
+// red-not-dim treatment can't drift: a failed write must never look like a success, or the next
+// turn keeps using the old embedder while the user was told the index was rebuilt for a change
+// that never landed — worse than the original confusion (#169 again).
+async function saveEmbedSettings(fields) {
+  const md = await import("./model-doctor.mjs");
+  const saved = await withPendingStatus("saving your embedder", () =>
+    md.saveWorkerSettings(apiBase, workerKey, fields)
   );
-  const idx = await pickFromList(labels, Math.max(0, rows.findIndex((r) => r.current)));
-  if (idx < 0) {
-    console.log(dim("  (cancelled)\n"));
-    return;
+  if (!saved) console.log(red("  couldn't save that to your account — nothing changed.\n"));
+  return saved;
+}
+
+// WHERE TO EMBED, ASKED ONCE, SHARED. The model sub-flow and the ollama-server action both need
+// "which Ollama serves the embeddings"; it used to live inline, which meant a second copy could
+// never exist. Enter keeps the current URL; Ctrl+C/Escape returns null and the caller just stops.
+// Anything that is not an Ollama-shaped host is rejected with the reason, then asked AGAIN —
+// ollama-host-snippets' why line IS the retry message.
+async function pickEmbedServerUrl({ currentUrl }) {
+  const ohs = await import("./ollama-host-snippets.mjs");
+  for (;;) {
+    const urlIn = await ask(`  Ollama server URL for embedding  [${currentUrl}]: `);
+    if (urlIn === null) return null;
+    const typed = urlIn.trim();
+    if (!typed) return currentUrl;
+    const embedUrl = /^https?:\/\//i.test(typed) ? typed : `http://${typed}`;
+    const r = ohs.checkOllamaHostInput(embedUrl);
+    if (r.ok) return embedUrl;
+    console.log(GUTTER + dim(`  "${typed}" is ${r.why} — try host:port, e.g. 127.0.0.1:11434`));
+  }
+}
+
+// THE KEY, ASKED ONCE, SHARED. ollama.com cannot proceed without one; the OpenAI-compatible
+// provider row asks the same way (Enter skips it — a local vLLM answers anonymously). All embed
+// keys land under the fixed backendId "embed-ollama" because that is the id
+// gonext_agent_chat._rag_resolve_embed_api_key() fetches, whatever the server is; ragEmbedKeyId
+// is just the human label the settings panel shows. Returns { cancelled, keyId } — a cancelled
+// prompt writes NOTHING, and a failed store keeps the key out of the settings so the user is not
+// told they authenticated when they did not.
+async function askEmbedKey(url, { optional = false } = {}) {
+  console.log(GUTTER + dim('A name just tells keys apart — "embed", "work".'));
+  const name = (await askKeyName()).trim();
+  console.log(GUTTER + dim(SECRET_KEY_HINT));
+  const key = (await askSecret(`  API key for ${url}${name ? ` (${name})` : ""}: `)).trim();
+  if (!key) {
+    if (optional) console.log(GUTTER + dim("(no key — the provider will be called anonymously)"));
+    return { cancelled: !optional, keyId: "", key: "" };
   }
-  const chosen = rows[idx].model;
+  const id = await withPendingStatus("saving the key", () => addCodingKey(name || "embed", key, "embed-ollama"));
+  if (!id) {
+    console.log(red("  couldn't save the embed key — searching stays unauthenticated.\n"));
+    return { cancelled: true, keyId: "", key: "" };
+  }
+  console.log(GUTTER + dim(`embed key "${name || id}" saved.\n`));
+  return { cancelled: false, keyId: id, key };
+}
 
-  // READ THE MANIFESTS BEFORE ASKING. "Are you sure?" with nothing behind it is a prompt people
-  // learn to dismiss; naming the four projects that stop working is a decision they can make.
-  const md = await import("./model-doctor.mjs");
+// THE RECOGNITION STEP, ONE WAY. Switching embedders invalidates the indexes; naming the projects
+// that stop working is the decision the user is actually making, so the plan is read BEFORE the
+// "switch / keep" picker — never after, never implied. Returns { changed:false } when the user
+// keeps the current embedder or the choice is a no-op.
+async function confirmEmbedSwitch(ec, current, chosen) {
   let indexes = [];
   try {
+    const md = await import("./model-doctor.mjs");
     indexes = await md.listLocalRagIndexes();
   } catch {
-    /* unreadable store — the plan degrades to "we can't tell", handled below */
+    /* unreadable store — the plan degrades to "we can't tell", handled by embedChangePlan */
   }
   const plan = ec.embedChangePlan({ current, chosen, indexes });
   if (!plan.changed) {
     console.log(dim(`  already using ${current} — nothing changed.\n`));
-    return;
+    return { changed: false, plan: null };
   }
+  // "Are you sure?" with nothing behind it is a prompt people learn to dismiss; the four projects
+  // that stop working are a decision they can make.
   for (const l of ec.describeEmbedChange(plan)) console.log(GUTTER + dim(l));
   const go = await pickFromList([`switch to ${chosen}`, `keep ${current}`], plan.stale.length ? 1 : 0);
   if (go !== 0) {
     console.log(dim("  (kept)\n"));
-    return;
+    return { changed: false, plan: null };
   }
+  return { changed: true, plan };
+}
 
-  const saved = await md.saveWorkerSettings(apiBase, workerKey, { ragEmbedModel: chosen });
-  if (!saved) {
-    // A FAILED WRITE MUST NOT LOOK LIKE A SUCCESS. The next turn would keep using the old
-    // embedder, and the user would be told their index was rebuilt for a change that never
-    // happened — worse than the original confusion, because now they trust it.
-    console.log(red(`  couldn't save that to your account — still using ${current}.\n`));
-    return;
+// WHICH EMBEDDER, ASKED ONCE. The model sub-flow of /embed-model: the curated picker, then the
+// shared recognition step. Returns { changed, chosen, plan }.
+async function pickEmbedModel(ec, current) {
+  const rows = ec.embedChoiceRows(current);
+  console.log(dim(`  Choose the embedder (${PICK_HINT}):`));
+  const labels = rows.map(
+    (r) => `${r.model}${r.dims ? dim(` · ${r.dims}d`) : ""}${dim(` · ${r.note}`)}` + (r.current ? accent(" (current)") : "")
+  );
+  const idx = await pickFromList(labels, Math.max(0, rows.findIndex((r) => r.current)));
+  if (idx < 0) {
+    console.log(dim("  (cancelled)\n"));
+    return { changed: false, chosen: "", plan: null };
   }
-  console.log(accent(`  ✓ embedding model → ${chosen}`));
-  if (plan.stale.length) {
+  const chosen = rows[idx].model;
+  const sw = await confirmEmbedSwitch(ec, current, chosen);
+  return { changed: sw.changed, chosen: sw.changed ? chosen : "", plan: sw.plan };
+}
+
+// WHAT A SAVED CHANGE SOUNDS LIKE. Success lines used to live at the end of one long function;
+// four exit paths now say them, so they are said once here: the embedder line, the rebuild note
+// that only a REAL model change earns, and the pull hint — Ollama serves the embedder itself, so
+// a model that was never pulled fails at the first search, not here. Say it once rather than let
+// it surface as "RAG is broken".
+function announceEmbedSaved({ chosen, plan, url }) {
+  console.log(accent(`  ✓ embedding model → ${chosen}` + (url ? `  on ${hostOf(url)}` : "")));
+  if (plan?.stale.length) {
     console.log(
       dim(`    ${plan.stale.length} knowledge base${plan.stale.length === 1 ? "" : "s"} ` +
           "will rebuild on the next search — the first one will be slower.")
     );
   }
-  // Ollama serves the embedder itself, so a model that was never pulled fails at the first
-  // search rather than here. Say it once, rather than let it surface as "RAG is broken".
   console.log(dim(`    Make sure it is pulled there:  ollama pull ${chosen}\n`));
 }
 
+async function chooseEmbedModel() {
+  const ec = await import("./embed-model-command.mjs");
+  const settings = await withPendingStatus("reading your embedder", fetchWorkerSettings);
+  if (!settings) {
+    console.log(red("  couldn't reach the API to read your current embedder.\n"));
+    return;
+  }
+  const current = ec.currentEmbedModel(settings);
+  const currentUrl = String(settings.ragEmbedUrl || "").trim() || "http://127.0.0.1:11434";
+  const host = hostOf(currentUrl);
+  // WHEN TO SHOW THE KEY ROW (embedMenuOptions' keyRequired): a key is clearly the question when
+  // the server is ollama.com (it rejects anonymous calls) or already looks OpenAI-compatible (the
+  // /v1 shape), or when one is already bound — replacing the key people can no longer read is the
+  // very thing they come back for. A keyless localhost Ollama sees three rows instead.
+  const keyRequired = isOllamaCloudUrl(currentUrl) || /\/v1\/?$/i.test(currentUrl) ||
+    Boolean(String(settings.ragEmbedKeyId ?? "").trim());
+  const menu = ec.embedMenuOptions({ current, host, keyRequired });
+  console.log(dim(`  Embedding model (currently ${current} on ${host || currentUrl})`));
+  const mi = await pickFromList(menu.map((o) => o.label), 0);
+  const action = mi >= 0 ? menu[mi].action : "cancel";
+  if (action === "cancel") {
+    console.log(dim("  (cancelled)\n"));
+    return;
+  }
+
+  if (action === "model") {
+    // WHICH + WHERE, one pass: the recognition wall first (it is the expensive decision), then
+    // the server prompt, then — only on ollama.com — the key. Same addition coding and agent
+    // models already have (#127): the key is named, stored in the shared account store
+    // (settings.agentCodingApiKeys) tagged "embed-ollama", and its id recorded in ragEmbedKeyId so
+    // the embedder can name what it sends. Cancelled url/key prompts abort cleanly: the key, if
+    // typed, is already in the store and the settings write is simply skipped.
+    const { changed, chosen, plan } = await pickEmbedModel(ec, current);
+    if (!changed) return;
+    const embedUrl = await pickEmbedServerUrl({ currentUrl });
+    if (embedUrl === null) {
+      console.log(dim("  (cancelled)\n"));
+      return;
+    }
+    let embedKeyId = settings.ragEmbedKeyId ?? "";
+    if (isOllamaCloudUrl(embedUrl)) {
+      const k = await askEmbedKey(embedUrl);
+      if (k.cancelled) return;
+      embedKeyId = k.keyId;
+    }
+    // A FAILED WRITE MUST NOT LOOK LIKE A SUCCESS (#169): the next turn would keep using the old
+    // embedder while the user is told the index was rebuilt for a change that never happened.
+    if (!(await saveEmbedSettings({ ragEmbedModel: chosen, ragEmbedUrl: embedUrl, ragEmbedKeyId: embedKeyId }))) return;
+    announceEmbedSaved({ chosen, plan, url: embedUrl });
+    return;
+  }
+
+  if (action === "ollama") {
+    // SAME MODEL, NEW OLLAMA. Vectors come from the model, not the box — moving nomic-embed-text
+    // from 127.0.0.1 to another Ollama changes no numbers, so no wall and no rebuild. The
+    // ollama.com arm still collects the key; a keyless host clears the stale ragEmbedKeyId label.
+    const embedUrl = await pickEmbedServerUrl({ currentUrl });
+    if (embedUrl === null) {
+      console.log(dim("  (cancelled)\n"));
+      return;
+    }
+    let embedKeyId = "";
+    if (isOllamaCloudUrl(embedUrl)) {
+      const k = await askEmbedKey(embedUrl);
+      if (k.cancelled) return;
+      embedKeyId = k.keyId;
+    }
+    // Same box, no new key: keep the no-op honest instead of writing noise over the settings.
+    if (embedUrl === currentUrl && !embedKeyId) {
+      console.log(dim(`  already embedding on ${host || currentUrl} — nothing changed.\n`));
+      return;
+    }
+    if (!(await saveEmbedSettings({ ragEmbedUrl: embedUrl, ragEmbedKeyId: embedKeyId }))) return;
+    console.log(accent(`  ✓ embedding server → ${hostOf(embedUrl)}`));
+    console.log(dim(`    ${current} did not change, so no knowledge base rebuilds — the same model just answers from another box.\n`));
+    return;
+  }
+
+  if (action === "provider") {
+    // ANOTHER OPENAI-COMPATIBLE PROVIDER. _embed() tries {base}/v1/embeddings first, so any
+    // /v1-shaped server works — vLLM, OpenRouter, LM Studio, a hosted gateway. The key comes
+    // BEFORE the list: most providers 401 an anonymous /v1/models, and a keyless local server
+    // just answers, so Enter skips the key. The model id then comes from the provider's own
+    // /v1/models when it answers, typed EXACTLY as the provider calls it when it does not — the
+    // worker POSTs the string verbatim, so both are supported.
+    const ps = await import("./coding-provider-setup.mjs");
+    let base = "";
+    for (;;) {
+      const raw = await ask(`  provider base URL (e.g. https://openrouter.ai/api/v1): `);
+      if (raw === null || !raw.trim()) {
+        console.log(dim("  (cancelled)\n"));
+        return;
+      }
+      const typed = raw.trim();
+      base = /^https?:\/\//i.test(typed) ? typed : `https://${typed}`;
+      try {
+        new URL(base);
+        break;
+      } catch {
+        console.log(yellow("  that is not a URL — try https://host or https://host/v1"));
+      }
+    }
+    base = ps.ensureV1Root(base);
+    const providerHost = hostOf(base);
+    const k = await askEmbedKey(base, { optional: true });
+    const embedKeyId = k.keyId;
+    const { proxyFetch } = await import("./proxy-dispatcher.mjs");
+    let chosen = "";
+    let listed = [];
+    try {
+      const am = await import("./agent-model-command.mjs");
+      const r = await withPendingStatus(`asking ${providerHost} for its models`, () =>
+        proxyFetch(`${base}/models`, { headers: am.agentListHeaders(k.key || ""), signal: AbortSignal.timeout(12000) })
+      );
+      if (r.ok) listed = am.agentModelsFromBody("openai", await r.json().catch(() => null));
+    } catch { /* an unreachable list is not a dead end — typing is fully supported, below */ }
+    if (listed.length) {
+      // Embedders first, the rest after, each once: the provider's catalog is mostly chat models,
+      // and burying "text-embedding-3-large" under 200 of them is a menu nobody can use.
+      const am = await import("./agent-model-command.mjs");
+      const ordered = [...listed].sort((a, b) =>
+        Number(am.isLikelyEmbedder(b)) - Number(am.isLikelyEmbedder(a)) || a.model.localeCompare(b.model));
+      const labels = ordered.map((r) =>
+        `${r.model}${r.note ? dim(` · ${r.note}`) : ""}` + (ec.sameEmbedModel(r.model, current) ? accent(" (current)") : ""));
+      const li = await pickFromList(labels, Math.max(0, ordered.findIndex((r) => ec.sameEmbedModel(r.model, current))));
+      if (li < 0) {
+        console.log(dim("  (cancelled)\n"));
+        return;
+      }
+      chosen = ordered[li].model;
+    } else {
+      console.log(dim(`  ${providerHost} did not list its models — type the embedding model id exactly as ${providerHost} calls it.`));
+      const raw = await ask(`  embedding model id [${current}]: `);
+      if (raw === null) {
+        console.log(dim("  (cancelled)\n"));
+        return;
+      }
+      chosen = raw.trim() || current;
+    }
+    // A MODEL CHANGE THROUGH THE PROVIDER ROW IS STILL A REINDEX — same wall, same wording. Same
+    // model = a pure server/key move, and no knowledge base needs a rebuild.
+    let plan = null;
+    if (!ec.sameEmbedModel(chosen, current)) {
+      const sw = await confirmEmbedSwitch(ec, current, chosen);
+      if (!sw.changed) return;
+      plan = sw.plan;
+    }
+    const fields = { ragEmbedUrl: base, ragEmbedKeyId: embedKeyId };
+    if (chosen) fields.ragEmbedModel = chosen;
+    if (!(await saveEmbedSettings(fields))) return;
+    if (plan) announceEmbedSaved({ chosen, plan, url: base });
+    else {
+      console.log(accent(`  ✓ embedding provider → ${providerHost}`));
+      console.log(dim(`    ${chosen} did not change, so no knowledge base rebuilds — the same model just answers from ${providerHost}.\n`));
+    }
+    return;
+  }
+
+  if (action === "key") {
+    // A NEW KEY FOR THE SERVER ALREADY CHOSEN. The model and the URL stay; only the credential
+    // rotates — same three steps as everywhere else (name → secret → store under "embed-ollama").
+    const k = await askEmbedKey(host || currentUrl);
+    if (k.cancelled) return;
+    if (!(await saveEmbedSettings({ ragEmbedKeyId: k.keyId }))) return;
+    console.log(accent(`  ✓ embedding key → "${k.keyId}"`));
+    console.log(dim(`    ${current} still embeds on ${host || currentUrl} — the new key signs the next request.\n`));
+  }
+}
+
 /** Save the agent model on this machine: the URL the API sends turns to, and the model name. */
 async function saveAgentModel(agentUrl, model, host) {
   const md = await import("./model-doctor.mjs");
@@ -10472,7 +10709,8 @@ async function main() {
               "\n  Nothing can run until it knows which Ollama server to use." +
                 "\n  Start `gu`, then `/model` → change the Ollama server this machine uses." +
                 `\n  The agent server needs a ${REQUIRED_AGENT_PREFIX} model (e.g. ${REQUIRED_AGENT_MODEL})` +
-                `\n  and ${REQUIRED_EMBED_MODEL}; the agent and coding models are then yours to pick.`
+                `\n  and any ONE of these embedders: ${ACCEPTED_EMBED_MODELS.map((m) => m.replace(/:latest$/, "")).join(", ")};` +
+                "\n  the agent and coding models are then yours to pick."
             )
         );
       } else {

package/ollama-setup.mjs

@@ -19,6 +19,7 @@
  * returns null rather than a plausible-looking value it cannot stand behind.
  */
 import { isLikelyEmbedder } from "./agent-model-command.mjs";
+import { EMBED_CHOICES } from "./embed-model-command.mjs";
 
 /** Ollama's native port, used when someone types a bare host or an IP with no port. */
 export const OLLAMA_DEFAULT_PORT = 11434;
@@ -89,6 +90,30 @@ const sameModel = (a, b) => {
   return bare(a) === bare(b);
 };
 
+/**
+ * WHICH EMBEDDERS SATISFY THE REQUIREMENT — any ONE of them, not all, and no longer one exact
+ * name (user, 2026-09-23). nomic-embed-text stays the shipped default and the suggested pull;
+ * qwen3-embedding:4b (and the rest of /embed-model's known-good list) are equally valid: what
+ * must hold is that the embedder is one of ours, because anything else does not error, it
+ * returns numbers, and corrupts every vector on disk invisibly. The list comes from
+ * embed-model-command.mjs so first-run validation and the /embed-model picker can never
+ * disagree about what "supported" means. The default is named first so seeding prefers it.
+ */
+export const ACCEPTED_EMBED_MODELS = [
+  REQUIRED_EMBED_MODEL,
+  ...EMBED_CHOICES.map((c) => c.model).filter((m) => !sameModel(m, REQUIRED_EMBED_MODEL)),
+];
+
+/**
+ * Which accepted embedder to seed this box with: the shipped default when present, else the
+ * first known-good one the box actually has. Returns "" when the box has none — impossible
+ * after checkRequired has passed, but callers fall back on REQUIRED_EMBED_MODEL regardless.
+ */
+export function defaultEmbedModel(models) {
+  const list = Array.isArray(models) ? models : [];
+  return ACCEPTED_EMBED_MODELS.find((e) => list.some((m) => sameModel(m.model, e))) ?? "";
+}
+
 /**
  * Does this server have what the agent and RAG actually need?
  *
@@ -106,9 +131,12 @@ export function checkRequired(
   // `missing` is still a concrete, pullable name — `ollama pull gemma4` is not a command, so
   // reporting the prefix would produce a line that cannot be run.
   if (!agentCandidates(list, { prefix: agentPrefix }).length) missing.push(agentExample);
-  // The EMBEDDER is still exact, and deliberately: a different one does not error, it returns
-  // numbers, which corrupts every vector on disk invisibly and permanently.
-  if (!list.some((m) => sameModel(m.model, embed))) missing.push(embed);
+  // The EMBEDDER is still a closed list, and deliberately: a different one does not error, it
+  // returns numbers, which corrupts every vector on disk invisibly and permanently. But ONE
+  // accepted embedder is ENOUGH (user, 2026-09-23) — a box holding qwen3-embedding:4b and no
+  // nomic-embed-text is ready; it just embeds with qwen. Only a box with NONE of ours is told
+  // to pull, and the name pushed is the shipped default — the line that can actually be run.
+  if (!list.some((m) => ACCEPTED_EMBED_MODELS.some((e) => sameModel(m.model, e)))) missing.push(embed);
   return { ok: missing.length === 0, missing };
 }
 
@@ -123,6 +151,14 @@ export function describeNotReady(host, missing) {
   for (const m of missing ?? []) lines.push(`  ${m}`);
   lines.push("Pull them there, then load again:");
   for (const m of missing ?? []) lines.push(`  ollama pull ${String(m).replace(/:latest$/, "")}`);
+  // ONE embedder suffices, so when the embedder is the missing piece say what the OTHER
+  // acceptable ones are — telling someone who already has qwen3-embedding:4b to also pull
+  // nomic-embed-text would be asking for a model they do not need.
+  if ((missing ?? []).some((m) => sameModel(m, REQUIRED_EMBED_MODEL))) {
+    lines.push(
+      `  (any ONE embedder is enough — ${ACCEPTED_EMBED_MODELS.map((m) => m.replace(/:latest$/, "")).join(" / ")})`
+    );
+  }
   return lines;
 }
 
@@ -687,7 +723,10 @@ export async function askOllamaSetup(
   // and gemma4:12b for quality, and only the person running the machine knows which they want.
   // Not asked when there is exactly one candidate: a menu with a single row is a question with
   // one answer, and answering it is pure ceremony.
-  const embed = agent ? REQUIRED_EMBED_MODEL : null;
+  // 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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gu-cli",
-  "version": "1.0.717",
+  "version": "1.0.719",
   "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",