docs(import): human-readable labels + hover help for the O(1) knobs

Landmarks / Exact window / Sink keys now carry a '?' tooltip explaining in
plain language what each knob does, its trade-off, and the validated default
(32 / 128 / 4), in EN + RU.

Cargo.lock

@@ -285,7 +285,7 @@ checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
 
 [[package]]
 name = "cortiq-gateway"
-version = "0.2.15"
+version = "0.2.18"
 dependencies = [
  "anyhow",
  "arc-swap",

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "cortiq-gateway"
-version = "0.2.15"
+version = "0.2.18"
 edition = "2021"
 rust-version = "1.75"
 license = "Apache-2.0"

src/admin/mod.rs

@@ -606,7 +606,10 @@ fn cmf_file_for_model(
     cmf: &crate::config::CmfCfg,
     m: &crate::config::ModelCfg,
 ) -> Option<std::path::PathBuf> {
+    // Any loopback URL counts as local — managed servers may sit on any port.
     let local = m.base_url == cmf.cortiq_server_url
+        || m.base_url.contains("//127.0.0.1:")
+        || m.base_url.contains("//localhost:")
         || m.base_url
             .contains(&format!("{}:{}", cmf.local_host, cmf.local_port));
     let stem = m.model.trim();
@@ -646,12 +649,24 @@ fn cmf_path_referenced(cfg: &crate::config::Config, path: &std::path::Path) -> b
             .any(|m| cmf_file_for_model(&cfg.cmf, m).as_deref() == Some(path))
 }
 
-async fn delete_model(State(state): State<SharedState>, Path(id): Path<String>) -> ApiResult {
+#[derive(Deserialize)]
+struct DeleteModelQuery {
+    /// Also remove the local `.cmf` from disk. Defaults to true (the historical
+    /// behaviour); the UI asks the user and passes it explicitly.
+    delete_file: Option<bool>,
+}
+
+async fn delete_model(
+    State(state): State<SharedState>,
+    Path(id): Path<String>,
+    Query(q): Query<DeleteModelQuery>,
+) -> ApiResult {
     let mut cfg = current_cfg(&state);
+    let delete_file = q.delete_file.unwrap_or(true);
 
     // Managed local models live in [cmf], not [[models]]. Deleting one stops its
-    // server, removes it from the managed config, and deletes its file — unless
-    // another model still points at the same file.
+    // server, removes it from the managed config, and (when asked) deletes its
+    // file — unless another model still points at the same file.
     let managed = cfg.cmf.effective_servers().into_iter().find(|s| s.id == id);
     if let Some(server) = managed {
         if !cfg.models.iter().any(|x| x.id == id) {
@@ -666,10 +681,10 @@ async fn delete_model(State(state): State<SharedState>, Path(id): Path<String>)
             let shared = cmf_path_referenced(&cfg, &path);
             state.cmf.stop_one(&id).await;
             state.reload(cfg)?;
-            let file_removed = if shared {
-                false
-            } else {
+            let file_removed = if delete_file && !shared {
                 remove_cmf_path(&path)
+            } else {
+                false
             };
             return ok(json!({ "ok": true, "file_removed": file_removed }));
         }
@@ -685,8 +700,8 @@ async fn delete_model(State(state): State<SharedState>, Path(id): Path<String>)
     let file = victim
         .as_ref()
         .and_then(|m| cmf_file_for_model(&cfg.cmf, m));
-    // Only remove the file if no remaining model still references it.
-    let file = file.filter(|p| !cmf_path_referenced(&cfg, p));
+    // Only remove the file if asked to AND no remaining model still references it.
+    let file = file.filter(|p| delete_file && !cmf_path_referenced(&cfg, p));
     state.reload(cfg)?;
     let file_removed = file.map(|p| remove_cmf_path(&p)).unwrap_or(false);
     ok(json!({ "ok": true, "file_removed": file_removed }))
@@ -905,12 +920,75 @@ async fn put_settings(State(state): State<SharedState>, Json(b): Json<SettingsBo
         {
             needs_restart = true;
         }
+        let old_servers = cfg.cmf.effective_servers();
         cfg.cmf = v;
+        // Replacing or renaming a managed model must not brick the save: routing
+        // may still reference the old id. Map a vanished id to its replacement
+        // (the new server on the same port), strip ids that are truly gone, and
+        // repair the default so validate() passes.
+        heal_routing_after_cmf_change(&mut cfg, &old_servers);
     }
     state.reload(cfg)?;
     ok(json!({ "ok": true, "needs_restart": needs_restart }))
 }
 
+/// After the managed-servers list changed, rewrite [routing] so it only
+/// references ids that still exist. A removed server whose port is now held by
+/// a NEW server is treated as a replacement (old id → new id); other vanished
+/// ids are stripped. An emptied default falls back to the first managed server,
+/// then the first pool model.
+fn heal_routing_after_cmf_change(cfg: &mut Config, old_servers: &[crate::config::CmfServer]) {
+    let servers = cfg.cmf.effective_servers();
+    let known: std::collections::HashSet<String> = cfg
+        .models
+        .iter()
+        .map(|m| m.id.clone())
+        .chain(servers.iter().map(|s| s.id.clone()))
+        .collect();
+    let new_by_port: HashMap<u16, String> =
+        servers.iter().map(|s| (s.port, s.id.clone())).collect();
+    let mut rename: HashMap<String, String> = HashMap::new();
+    for old in old_servers {
+        if !known.contains(&old.id) {
+            if let Some(new_id) = new_by_port.get(&old.port) {
+                rename.insert(old.id.clone(), new_id.clone());
+            }
+        }
+    }
+    let fix = |id: &str| -> Option<String> {
+        if known.contains(id) {
+            Some(id.to_string())
+        } else {
+            rename.get(id).cloned()
+        }
+    };
+    if !cfg.routing.default.is_empty() {
+        cfg.routing.default = fix(&cfg.routing.default).unwrap_or_default();
+    }
+    if cfg.routing.default.is_empty() {
+        cfg.routing.default = servers
+            .first()
+            .map(|s| s.id.clone())
+            .or_else(|| cfg.models.first().map(|m| m.id.clone()))
+            .unwrap_or_default();
+    }
+    for tt in cfg.routing.tiers.values_mut() {
+        let list = match tt {
+            TierTargets::List(v) => v.clone(),
+            TierTargets::One(s) => vec![s.clone()],
+        };
+        let mut healed: Vec<String> = Vec::new();
+        for id in &list {
+            if let Some(new_id) = fix(id) {
+                if !healed.contains(&new_id) {
+                    healed.push(new_id);
+                }
+            }
+        }
+        *tt = TierTargets::List(healed);
+    }
+}
+
 // ───────────────────────────── cmf runtime ─────────────────────────────────
 /// Status of the `cortiq` CLI (the CMF format runtime): is it installed, which
 /// version, and whether a managed server is running. Drives the "Install cortiq"
@@ -1028,6 +1106,9 @@ async fn cmf_port_check(State(state): State<SharedState>, Query(q): Query<PortQu
     ok(json!({
         "port": port,
         "available": available,
+        // true = held by this gateway's own managed server (a replaced/edited
+        // row frees it on restart) — the UI shows this as info, not an error
+        "managed": running_here,
         "detail": detail,
         "suggested": suggested,
     }))

web/js/api.js

@@ -60,7 +60,8 @@ export const api = {
   listModels: () => j("GET", "/models"),
   createModel: (b) => j("POST", "/models", b),
   updateModel: (id, b) => j("PUT", "/models/" + encodeURIComponent(id), b),
-  deleteModel: (id) => j("DELETE", "/models/" + encodeURIComponent(id)),
+  deleteModel: (id, deleteFile = true) =>
+    j("DELETE", "/models/" + encodeURIComponent(id) + "?delete_file=" + (deleteFile ? "true" : "false")),
   probeModel: (id) => j("POST", "/models/" + encodeURIComponent(id) + "/probe"),
 
   // routing

web/js/i18n/en.js

@@ -132,6 +132,8 @@ export default {
   "models.form.secretMissing": "not set",
   "models.form.secretPlaceholder": "set or replace key (write-only)",
   "models.deleteConfirm": "Delete model \"{id}\"?",
+  "models.deleteFile": "also delete the model file from disk",
+  "models.deletedWithFile": "Deleted (file removed from disk)",
   "models.form.idOrModel": "Enter an id or a model name",
   "models.form.apiKey": "API Key",
   "models.form.apiKeyPlaceholder": "paste your API key",
@@ -267,6 +269,7 @@ export default {
   "settings.cmf.checkPort": "Check port",
   "settings.cmf.portFree": "port is free",
   "settings.cmf.portBusy": "port is in use",
+  "settings.cmf.portOwn": "in use by this gateway's current server — freed on restart, replacing is fine",
   "settings.cmf.useSuggested": "use {port}",
   "settings.cmf.serving": "serving {model} on :{port}",
   "settings.cmf.intro": "Run models locally with the cortiq engine — works even offline or when the router is down.",
@@ -409,6 +412,12 @@ export default {
   "import.adv.o1DeepN": "N deep layers",
   "import.adv.o1Layers": "Layers (comma-separated)",
   "import.adv.o1mHint": "landmark budget (default 32)",
+  "import.adv.o1mLabel": "Landmarks (--o1-m)",
+  "import.adv.o1mHelp": "How many landmark tokens summarize the whole older history when attention is approximated. More = closer to exact attention but slower and more memory; fewer = faster but rougher. 32 is the validated sweet spot — change only if you know why.",
+  "import.adv.o1windowLabel": "Exact window (--o1-window)",
+  "import.adv.o1windowHelp": "The last N tokens always get exact (non-approximated) attention. This protects quality on the text the model just wrote/read. Bigger = better local quality, more memory. Default 128.",
+  "import.adv.o1sinkLabel": "Sink keys (--o1-sink)",
+  "import.adv.o1sinkHelp": "The first N tokens of the context are kept exact forever ('attention sinks'). Models lean on these anchors — keeping them exact stabilizes long generations. Default 4; rarely needs changing.",
   "import.adv.o1windowHint": "exact-window width (default 128)",
   "import.adv.o1sinkHint": "permanent exact sink keys (default 4)",
 };

web/js/i18n/ru.js

@@ -131,6 +131,8 @@ export default {
   "models.form.secretMissing": "не задан",
   "models.form.secretPlaceholder": "задать или заменить ключ (только запись)",
   "models.deleteConfirm": "Удалить модель \"{id}\"?",
+  "models.deleteFile": "также удалить файл модели с диска",
+  "models.deletedWithFile": "Удалено (файл стёрт с диска)",
   "models.form.idOrModel": "Укажите id или имя модели",
   "models.form.apiKey": "API-ключ",
   "models.form.apiKeyPlaceholder": "вставьте API-ключ",
@@ -266,6 +268,7 @@ export default {
   "settings.cmf.checkPort": "Проверить порт",
   "settings.cmf.portFree": "порт свободен",
   "settings.cmf.portBusy": "порт занят",
+  "settings.cmf.portOwn": "занят текущим сервером шлюза — освободится после перезапуска, замена допустима",
   "settings.cmf.useSuggested": "занять {port}",
   "settings.cmf.serving": "работает: {model} на :{port}",
   "settings.cmf.intro": "Запускайте модели локально движком cortiq — работает даже офлайн или когда роутер недоступен.",
@@ -408,6 +411,12 @@ export default {
   "import.adv.o1DeepN": "N глубоких слоёв",
   "import.adv.o1Layers": "Слои (через запятую)",
   "import.adv.o1mHint": "число опорных точек (по умолчанию 32)",
+  "import.adv.o1mLabel": "Опорные точки (--o1-m)",
+  "import.adv.o1mHelp": "Сколько опорных токенов представляют всю старую историю при аппроксимации внимания. Больше — ближе к точному вниманию, но медленнее и больше памяти; меньше — быстрее, но грубее. 32 — проверенное значение; меняйте, только если понимаете зачем.",
+  "import.adv.o1windowLabel": "Точное окно (--o1-window)",
+  "import.adv.o1windowHelp": "Последние N токенов всегда обрабатываются точным (не аппроксимированным) вниманием — это защищает качество на только что написанном/прочитанном тексте. Больше — лучше локальное качество, больше памяти. По умолчанию 128.",
+  "import.adv.o1sinkLabel": "Sink-ключи (--o1-sink)",
+  "import.adv.o1sinkHelp": "Первые N токенов контекста навсегда остаются точными («якоря внимания»). Модели опираются на эти якоря — их точность стабилизирует длинную генерацию. По умолчанию 4; менять почти никогда не нужно.",
   "import.adv.o1windowHint": "ширина точного окна (по умолчанию 128)",
   "import.adv.o1sinkHint": "постоянные точные sink-ключи (по умолчанию 4)",
 };

web/js/views/import.js

@@ -15,8 +15,14 @@ const QUANTS = [
   ["F32", "import.q.f32"],
 ];
 
-function field(label, control, hint) {
-  return h("label", { class: "field" }, h("span", {}, label), control,
+// A small "?" badge with a hover/focus tooltip (same style as Settings).
+function help(text) {
+  return text ? h("span", { class: "help", title: text, tabindex: "0", role: "img", "aria-label": text }, "?") : null;
+}
+function field(label, control, hint, helpText) {
+  return h("label", { class: "field" },
+    h("span", {}, label, helpText ? " " : null, help(helpText)),
+    control,
     hint ? h("div", { class: "hint" }, hint) : null);
 }
 function opt(v, label, sel) {
@@ -141,9 +147,9 @@ export function renderImport() {
       field(t("import.adv.o1DeepN"), o1DeepIn),
       field(t("import.adv.o1Layers"), o1CustomIn));
     const o1Knobs = h("div", { class: "row", style: "display:none" },
-      field("--o1-m", o1M, t("import.adv.o1mHint")),
-      field("--o1-window", o1Window, t("import.adv.o1windowHint")),
-      field("--o1-sink", o1Sink, t("import.adv.o1sinkHint")));
+      field(t("import.adv.o1mLabel"), o1M, t("import.adv.o1mHint"), t("import.adv.o1mHelp")),
+      field(t("import.adv.o1windowLabel"), o1Window, t("import.adv.o1windowHint"), t("import.adv.o1windowHelp")),
+      field(t("import.adv.o1sinkLabel"), o1Sink, t("import.adv.o1sinkHint"), t("import.adv.o1sinkHelp")));
     o1Sel.addEventListener("change", () => {
       const on = !!o1Sel.value;
       o1Knobs.style.display = on ? "" : "none";

web/js/views/models.js

@@ -1,5 +1,5 @@
 // Models — pool table with add/edit modal, probe, and per-model secret entry.
-import { h, mount, modal, toast, confirmDialog, money } from "../ui.js";
+import { h, mount, modal, toast, money } from "../ui.js";
 import { t } from "../i18n.js";
 import { api } from "../api.js";
 import { appState } from "../app.js";
@@ -280,15 +280,31 @@ function row(m, meta, reload) {
           "button",
           {
             class: "btn sm danger",
-            onClick: async () => {
-              if (!(await confirmDialog(t("models.deleteConfirm", { id: m.id })))) return;
-              try {
-                await api.deleteModel(m.id);
-                toast(t("toast.deleted"), "good");
-                await reload();
-              } catch (e) {
-                toast(String(e.message || e), "bad");
-              }
+            onClick: () => {
+              // local models may have a .cmf on disk — let the user decide its fate
+              const isLocal = m.managed || /127\.0\.0\.1|localhost/.test(m.base_url || "");
+              const fileCb = h("input", { type: "checkbox", checked: isLocal ? true : null });
+              const body = h(
+                "div",
+                {},
+                h("p", {}, t("models.deleteConfirm", { id: m.id })),
+                isLocal
+                  ? h("label", { class: "check" }, fileCb, t("models.deleteFile"))
+                  : null
+              );
+              modal(t("common.delete") + ": " + m.id, body, async () => {
+                try {
+                  const r = await api.deleteModel(m.id, isLocal && fileCb.checked);
+                  toast(
+                    r.file_removed ? t("models.deletedWithFile") : t("toast.deleted"),
+                    "good"
+                  );
+                  await reload();
+                } catch (e) {
+                  toast(String(e.message || e), "bad");
+                  return false;
+                }
+              }, t("common.delete"));
             },
           },
           t("common.delete")

web/js/views/settings.js

@@ -245,7 +245,11 @@ export async function renderSettings() {
       try {
         const r = await api.cmfPortCheck(p);
         if (r.available) mount(st, h("span", { style: "color:var(--good)" }, "✓ " + t("settings.cmf.portFree")));
-        else {
+        else if (r.managed) {
+          // held by this gateway's own managed server — replacing the model on
+          // this port is fine, it frees up on restart
+          mount(st, h("span", { style: "color:var(--accent)" }, "ℹ " + t("settings.cmf.portOwn")));
+        } else {
           const kids = [h("span", { style: "color:var(--bad)" }, "✗ " + t("settings.cmf.portBusy"))];
           if (r.suggested) { const b = h("button", { class: "btn small", type: "button" }, t("settings.cmf.useSuggested", { port: r.suggested })); b.addEventListener("click", () => { portIn.value = r.suggested; mount(st, ""); }); kids.push(b); }
           mount(st, h("span", {}, ...kids));