feat(models): gate optional models behind required mistral+nomic-embed

Models page redesign: tabs (Required/Recommended/Installed) with a
multi-column card grid, required models (memory curator + embeddings)
surfaced first and gating the rest until both are installed. Adds a
qwen2.5:14b tier to the hardware-fit catalog for high-VRAM machines.
Installer and restore messaging updated to match. Also declares pytest
in requirements-base.txt so bin/check.sh's test suite is reproducible
on a fresh venv.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

interface/web/src/Models.jsx

@@ -1,14 +1,101 @@
-import { useCallback, useEffect, useState } from "react";
+import { useCallback, useEffect, useMemo, useState } from "react";
 import { API_BASE } from "./config";
 
+const FIT = {
+  gpu: { label: "🟢 fits GPU", color: "#8aff8a" },
+  ram: { label: "🟡 runs on RAM (CPU)", color: "#e8c65a" },
+  no: { label: "🔴 too big", color: "#ff8a80" },
+};
+
+const TABS = [
+  { key: "required", label: "Required" },
+  { key: "recommended", label: "Recommended" },
+  { key: "installed", label: "Installed" },
+];
+
+const GRID_STYLE = {
+  display: "grid",
+  gridTemplateColumns: "repeat(auto-fill, minmax(260px, 1fr))",
+  gap: "0.75rem",
+  alignItems: "stretch",
+};
+
+function ModelCard({ model, installed, pulling, pullingName, locked, onPull }) {
+  const fit = FIT[model.fit] || FIT.no;
+  const isPullingThis = pulling && pullingName === model.name;
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "0.5rem",
+        padding: "0.85rem",
+        background: locked ? "#131313" : "#0f0f0f",
+        border: `1px solid ${model.required ? "#3a5a3a" : "#262626"}`,
+        borderRadius: "10px",
+        opacity: locked ? 0.45 : 1,
+        transition: "opacity 0.15s ease",
+      }}
+    >
+      <div style={{ display: "flex", justifyContent: "space-between", alignItems: "flex-start", gap: "0.5rem" }}>
+        <div style={{ minWidth: 0 }}>
+          <div style={{ color: "#eee", fontSize: "0.9rem", fontWeight: 500, wordBreak: "break-word" }}>
+            {model.name}
+          </div>
+          <div style={{ color: "#666", fontSize: "0.75rem" }}>
+            {model.params} · {model.size_gb} GB · {model.role}
+          </div>
+        </div>
+        {model.required && (
+          <span style={{
+            fontSize: "0.65rem", color: "#8aff8a", border: "1px solid #3a5a3a",
+            borderRadius: "999px", padding: "0.1rem 0.5rem", whiteSpace: "nowrap",
+          }}>
+            required
+          </span>
+        )}
+      </div>
+      <div style={{ color: "#888", fontSize: "0.75rem", flexGrow: 1 }}>{model.note}</div>
+      <div style={{ display: "flex", justifyContent: "space-between", alignItems: "center", gap: "0.5rem" }}>
+        <span style={{ color: fit.color, fontSize: "0.72rem", whiteSpace: "nowrap" }}>{fit.label}</span>
+        {installed ? (
+          <span style={{ color: "#8aff8a", fontSize: "0.75rem", whiteSpace: "nowrap" }}>✓ installed</span>
+        ) : (
+          <button
+            onClick={() => onPull(model.name)}
+            disabled={pulling || locked}
+            title={locked ? "Install the required models first" : undefined}
+            style={{
+              padding: "0.3rem 0.7rem",
+              background: pulling || locked ? "#555" : "#28a745",
+              color: "#fff",
+              border: "none",
+              borderRadius: "6px",
+              cursor: pulling || locked ? "not-allowed" : "pointer",
+              fontSize: "0.75rem",
+              whiteSpace: "nowrap",
+            }}
+          >
+            {isPullingThis ? "Pulling..." : "Pull"}
+          </button>
+        )}
+      </div>
+    </div>
+  );
+}
+
 export function Models({ onPullStateChange }) {
-  const [models, setModels] = useState([]);
+  const [models, setModels] = useState([]); // installed, chat-facing (embed models hidden)
+  const [allInstalled, setAllInstalled] = useState([]); // installed, unfiltered (includes embed)
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState("");
   const [pulling, setPulling] = useState(false);
+  const [pullingName, setPullingName] = useState("");
   const [modelName, setModelName] = useState("");
   const [pullProgress, setPullProgress] = useState("");
   const [recommended, setRecommended] = useState(null); // {hardware, models}
+  const [tab, setTab] = useState("required");
+  const [manualOpen, setManualOpen] = useState(false);
 
   const checkOllamaStatus = useCallback(async () => {
     try {
@@ -28,16 +115,21 @@ export function Models({ onPullStateChange }) {
       if (!isRunning) {
         setError("Ollama service is not running");
         setModels([]);
+        setAllInstalled([]);
         return;
       }
       const response = await fetch(`${API_BASE}/models/details`);
       if (!response.ok) throw new Error("Failed to fetch models");
       const data = await response.json();
-      // Embedding models (nomic-embed-text) are infrastructure — hide them.
-      setModels((data.models || []).filter((m) => !m.name.toLowerCase().includes("embed")));
+      const all = data.models || [];
+      setAllInstalled(all);
+      // Embedding models (nomic-embed-text) are infrastructure — hide from the
+      // Installed list, but they still count via allInstalled for the Required tab.
+      setModels(all.filter((m) => !m.name.toLowerCase().includes("embed")));
     } catch (err) {
       setError(`Error loading models: ${err.message}`);
       setModels([]);
+      setAllInstalled([]);
     } finally {
       setLoading(false);
     }
@@ -51,6 +143,7 @@ export function Models({ onPullStateChange }) {
     }
 
     setPulling(true);
+    setPullingName(name);
     onPullStateChange?.(true);
     setError("");
     setPullProgress(`Pulling ${name}…`);
@@ -100,6 +193,7 @@ export function Models({ onPullStateChange }) {
       setError(`Error pulling model: ${err.message}`);
     } finally {
       setPulling(false);
+      setPullingName("");
       onPullStateChange?.(false);
     }
   };
@@ -130,12 +224,21 @@ export function Models({ onPullStateChange }) {
     return () => clearInterval(interval);
   }, [loadModels]);
 
-  const installedNames = new Set(models.map(m => m.name.toLowerCase()));
-  const FIT = {
-    gpu: { label: "🟢 fits GPU", color: "#8aff8a" },
-    ram: { label: "🟡 runs on RAM (CPU)", color: "#e8c65a" },
-    no: { label: "🔴 too big", color: "#ff8a80" },
-  };
+  const installedNames = useMemo(
+    () => new Set(allInstalled.map(m => m.name.toLowerCase())),
+    [allInstalled]
+  );
+
+  const requiredModels = useMemo(
+    () => (recommended?.models ?? []).filter(m => m.required),
+    [recommended]
+  );
+  const otherModels = useMemo(
+    () => (recommended?.models ?? []).filter(m => !m.required),
+    [recommended]
+  );
+  const requiredMissing = requiredModels.filter(m => !installedNames.has(m.name.toLowerCase()));
+  const requiredSatisfied = recommended != null && requiredMissing.length === 0;
 
   return (
     <div style={{ display: "flex", flexDirection: "column", height: "100%", flexGrow: 1 }}>
@@ -161,159 +264,238 @@ export function Models({ onPullStateChange }) {
         padding: "1rem",
         display: "flex",
         flexDirection: "column",
-        overflowY: "auto",
-        overflowX: "hidden"
+        minHeight: 0,
       }}>
-        {/* Pull Model Section */}
-        <div style={{ marginBottom: "1.5rem", paddingBottom: "1rem", borderBottom: "1px solid #333" }}>
-          <h3 style={{ margin: "0 0 0.75rem 0", fontSize: "0.95rem", color: "#bbb" }}>Pull Model from Registry</h3>
-          <div style={{ display: "flex", gap: "0.5rem" }}>
-            <input
-              type="text"
-              placeholder="e.g., llama3, mistral, gemma"
-              value={modelName}
-              onChange={(e) => setModelName(e.target.value)}
-              onKeyPress={(e) => e.key === "Enter" && !pulling && pullModel()}
-              disabled={pulling}
-              style={{
-                flex: 1,
-                padding: "0.6rem 0.75rem",
-                background: "#0a0a0a",
-                color: "#eee",
-                border: "1px solid #333",
-                borderRadius: "6px",
-                fontSize: "0.9rem"
-              }}
-            />
-            <button
-              onClick={pullModel}
-              disabled={pulling}
-              style={{
-                padding: "0.6rem 1.25rem",
-                background: pulling ? "#666" : "#28a745",
-                color: "#fff",
-                border: "none",
-                borderRadius: "6px",
-                cursor: pulling ? "not-allowed" : "pointer",
-                fontSize: "0.9rem",
-                whiteSpace: "nowrap"
-              }}
-            >
-              {pulling ? "Pulling..." : "Pull"}
-            </button>
-            <button
-              onClick={loadModels}
-              disabled={loading}
-              style={{
-                padding: "0.6rem 1.25rem",
-                background: "#007acc",
-                color: "#fff",
-                border: "none",
-                borderRadius: "6px",
-                cursor: loading ? "not-allowed" : "pointer",
-                opacity: loading ? 0.6 : 1,
-                fontSize: "0.9rem",
-                whiteSpace: "nowrap"
-              }}
-            >
-              {loading ? "Refreshing..." : "Refresh"}
-            </button>
+        {/* Header: hardware summary + tabs */}
+        <div style={{ display: "flex", justifyContent: "space-between", alignItems: "center", flexWrap: "wrap", gap: "0.5rem", marginBottom: "0.85rem" }}>
+          <div style={{ display: "flex", gap: "0.35rem" }}>
+            {TABS.map(t => {
+              const active = tab === t.key;
+              const badge = t.key === "required" && recommended
+                ? (requiredSatisfied ? "✓" : requiredMissing.length)
+                : t.key === "installed" ? models.length : null;
+              return (
+                <button
+                  key={t.key}
+                  onClick={() => setTab(t.key)}
+                  style={{
+                    padding: "0.45rem 0.9rem",
+                    background: active ? "#28a745" : "transparent",
+                    color: active ? "#fff" : "#aaa",
+                    border: `1px solid ${active ? "#28a745" : "#333"}`,
+                    borderRadius: "999px",
+                    cursor: "pointer",
+                    fontSize: "0.82rem",
+                    display: "flex",
+                    alignItems: "center",
+                    gap: "0.4rem",
+                  }}
+                >
+                  {t.label}
+                  {badge !== null && badge !== undefined && (
+                    <span style={{
+                      fontSize: "0.68rem",
+                      color: active ? "#fff" : (t.key === "required" && !requiredSatisfied ? "#ff8a80" : "#888"),
+                    }}>
+                      {badge}
+                    </span>
+                  )}
+                </button>
+              );
+            })}
           </div>
-          {pullProgress && (
-            <div style={{ marginTop: "0.75rem", fontSize: "0.85rem", color: "#999" }}>
-              {pullProgress}
-            </div>
-          )}
-        </div>
-
-        {/* Recommended for your hardware */}
-        {recommended && (
-          <div style={{ marginBottom: "1.5rem", paddingBottom: "1rem", borderBottom: "1px solid #333" }}>
-            <h3 style={{ margin: "0 0 0.25rem 0", fontSize: "0.95rem", color: "#bbb" }}>Recommended for your hardware</h3>
-            <div style={{ fontSize: "0.78rem", color: "#777", marginBottom: "0.75rem" }}>
+          {recommended && (
+            <div style={{ fontSize: "0.78rem", color: "#777" }}>
               {recommended.hardware.ram_gb ? `${recommended.hardware.ram_gb} GB RAM` : "RAM unknown"}
               {" · "}
               {recommended.hardware.vram_gb ? `${recommended.hardware.vram_gb} GB GPU` : "GPU VRAM unknown — sized by RAM"}
             </div>
-            <div style={{ display: "flex", flexDirection: "column", gap: "0.35rem" }}>
-              {recommended.models.map((m) => {
-                const installed = installedNames.has(m.name.toLowerCase());
-                const fit = FIT[m.fit] || FIT.no;
-                return (
-                  <div key={m.name} style={{ display: "flex", alignItems: "center", gap: "0.6rem", padding: "0.4rem 0.6rem", background: "#0f0f0f", border: "1px solid #262626", borderRadius: "8px" }}>
-                    <div style={{ flex: 1, minWidth: 0 }}>
-                      <span style={{ color: "#eee", fontSize: "0.85rem" }}>{m.name}</span>
-                      <span style={{ color: "#666", fontSize: "0.75rem" }}> · {m.params} · {m.size_gb} GB · {m.role}</span>
-                      <div style={{ color: "#777", fontSize: "0.72rem" }}>{m.note}</div>
-                    </div>
-                    <span style={{ color: fit.color, fontSize: "0.75rem", whiteSpace: "nowrap" }}>{fit.label}</span>
-                    {installed
-                      ? <span style={{ color: "#8aff8a", fontSize: "0.75rem", whiteSpace: "nowrap" }}>✓ installed</span>
-                      : <button onClick={() => pullModel(m.name)} disabled={pulling}
-                          style={{ padding: "0.3rem 0.7rem", background: pulling ? "#555" : "#28a745", color: "#fff", border: "none", borderRadius: "6px", cursor: pulling ? "not-allowed" : "pointer", fontSize: "0.75rem", whiteSpace: "nowrap" }}>
-                          Pull
-                        </button>}
-                  </div>
-                );
-              })}
-            </div>
+          )}
+          <button
+            onClick={loadModels}
+            disabled={loading}
+            style={{
+              padding: "0.45rem 0.9rem",
+              background: "#007acc",
+              color: "#fff",
+              border: "none",
+              borderRadius: "6px",
+              cursor: loading ? "not-allowed" : "pointer",
+              opacity: loading ? 0.6 : 1,
+              fontSize: "0.82rem",
+            }}
+          >
+            {loading ? "Refreshing..." : "Refresh"}
+          </button>
+        </div>
+
+        {pullProgress && (
+          <div style={{ marginBottom: "0.85rem", fontSize: "0.85rem", color: "#999" }}>
+            {pullProgress}
           </div>
         )}
 
-        {/* Local Models List */}
-        <div style={{ paddingRight: "0.5rem" }}>
-          <h3 style={{ margin: "0 0 1rem 0", fontSize: "0.95rem", color: "#bbb" }}>
-            Available Models ({models.length})
-          </h3>
-          {models.length === 0 ? (
-            <div style={{ padding: "2rem", textAlign: "center", color: "#666" }}>
-              {loading ? "Loading models..." : "No models available. Pull a model to get started."}
-            </div>
+        {/* Scrollable tab content */}
+        <div style={{ flexGrow: 1, overflowY: "auto", overflowX: "hidden", paddingRight: "0.25rem" }}>
+          {!recommended ? (
+            <div style={{ padding: "2rem", textAlign: "center", color: "#666" }}>Loading catalog...</div>
+          ) : tab === "required" ? (
+            <>
+              <div style={{ marginBottom: "0.85rem", fontSize: "0.85rem", color: requiredSatisfied ? "#8aff8a" : "#e8c65a" }}>
+                {requiredSatisfied
+                  ? "All required models are installed. Everything else is unlocked on the Recommended tab."
+                  : "NexusOS needs both of these to fully work (memory + recall). Install them before pulling anything else."}
+              </div>
+              <div style={GRID_STYLE}>
+                {requiredModels.map(m => (
+                  <ModelCard
+                    key={m.name}
+                    model={m}
+                    installed={installedNames.has(m.name.toLowerCase())}
+                    pulling={pulling}
+                    pullingName={pullingName}
+                    locked={false}
+                    onPull={pullModel}
+                  />
+                ))}
+              </div>
+            </>
+          ) : tab === "recommended" ? (
+            <>
+              {!requiredSatisfied && (
+                <div style={{ marginBottom: "0.85rem", fontSize: "0.85rem", color: "#e8c65a" }}>
+                  Dimmed until the Required tab is complete — install those first.
+                </div>
+              )}
+              <div style={GRID_STYLE}>
+                {otherModels.map(m => (
+                  <ModelCard
+                    key={m.name}
+                    model={m}
+                    installed={installedNames.has(m.name.toLowerCase())}
+                    pulling={pulling}
+                    pullingName={pullingName}
+                    locked={!requiredSatisfied}
+                    onPull={pullModel}
+                  />
+                ))}
+              </div>
+            </>
           ) : (
-            <div style={{ display: "grid", gap: "0.75rem" }}>
-              {models.map((model) => (
-                <div
-                  key={model.name}
+            <>
+              {models.length === 0 ? (
+                <div style={{ padding: "2rem", textAlign: "center", color: "#666" }}>
+                  {loading ? "Loading models..." : "No models installed yet. Start with the Required tab."}
+                </div>
+              ) : (
+                <div style={GRID_STYLE}>
+                  {models.map((model) => (
+                    <div
+                      key={model.name}
+                      style={{
+                        display: "flex",
+                        flexDirection: "column",
+                        gap: "0.5rem",
+                        padding: "0.85rem",
+                        background: "#1b1b1b",
+                        borderRadius: "10px",
+                        border: "1px solid #2a2a2a",
+                      }}
+                    >
+                      <div style={{ fontWeight: 500, color: "#ddd", wordBreak: "break-word" }}>{model.name}</div>
+                      <div style={{ fontSize: "0.8rem", color: "#aaa" }}>
+                        {(model.size / (1024 * 1024 * 1024)).toFixed(2)} GB
+                      </div>
+                      {model.modified_at && (
+                        <div style={{ fontSize: "0.78rem", color: "#888" }}>
+                          Modified: {new Date(model.modified_at).toLocaleDateString()}
+                        </div>
+                      )}
+                      <button
+                        onClick={() => deleteModel(model.name)}
+                        style={{
+                          alignSelf: "flex-start",
+                          padding: "0.4rem 0.9rem",
+                          background: "#d63031",
+                          color: "#fff",
+                          border: "none",
+                          borderRadius: "6px",
+                          cursor: "pointer",
+                          fontSize: "0.8rem",
+                        }}
+                      >
+                        Delete
+                      </button>
+                    </div>
+                  ))}
+                </div>
+              )}
+            </>
+          )}
+        </div>
+
+        {/* Manual pull — collapsed by default */}
+        <div style={{ marginTop: "0.85rem", paddingTop: "0.75rem", borderTop: "1px solid #333" }}>
+          {!manualOpen ? (
+            <button
+              onClick={() => setManualOpen(true)}
+              style={{
+                background: "none",
+                border: "none",
+                color: "#777",
+                fontSize: "0.82rem",
+                cursor: "pointer",
+                padding: 0,
+              }}
+            >
+              Pull a different model...
+            </button>
+          ) : (
+            <div>
+              <div style={{ display: "flex", justifyContent: "space-between", alignItems: "center", marginBottom: "0.5rem" }}>
+                <h3 style={{ margin: 0, fontSize: "0.85rem", color: "#bbb" }}>Pull model from registry</h3>
+                <button
+                  onClick={() => setManualOpen(false)}
+                  style={{ background: "none", border: "none", color: "#666", fontSize: "0.78rem", cursor: "pointer" }}
+                >
+                  Collapse
+                </button>
+              </div>
+              <div style={{ display: "flex", gap: "0.5rem" }}>
+                <input
+                  type="text"
+                  placeholder="e.g., llama3, mistral, gemma"
+                  value={modelName}
+                  onChange={(e) => setModelName(e.target.value)}
+                  onKeyPress={(e) => e.key === "Enter" && !pulling && pullModel()}
+                  disabled={pulling}
                   style={{
-                    padding: "0.9rem",
-                    background: "#1b1b1b",
-                    borderRadius: "8px",
-                    border: "1px solid #2a2a2a",
-                    display: "flex",
-                    justifyContent: "space-between",
-                    alignItems: "center"
+                    flex: 1,
+                    padding: "0.6rem 0.75rem",
+                    background: "#0a0a0a",
+                    color: "#eee",
+                    border: "1px solid #333",
+                    borderRadius: "6px",
+                    fontSize: "0.9rem"
+                  }}
+                />
+                <button
+                  onClick={() => pullModel()}
+                  disabled={pulling}
+                  style={{
+                    padding: "0.6rem 1.25rem",
+                    background: pulling ? "#666" : "#28a745",
+                    color: "#fff",
+                    border: "none",
+                    borderRadius: "6px",
+                    cursor: pulling ? "not-allowed" : "pointer",
+                    fontSize: "0.9rem",
+                    whiteSpace: "nowrap"
                   }}
                 >
-                  <div>
-                    <div style={{ fontWeight: "500", marginBottom: "0.3rem", color: "#ddd" }}>
-                      {model.name}
-                    </div>
-                    <div style={{ fontSize: "0.85rem", color: "#aaa" }}>
-                      {(model.size / (1024 * 1024 * 1024)).toFixed(2)} GB
-                    </div>
-                    {model.modified_at && (
-                      <div style={{ fontSize: "0.85rem", color: "#888" }}>
-                        Modified: {new Date(model.modified_at).toLocaleDateString()}
-                      </div>
-                    )}
-                  </div>
-                  <button
-                    onClick={() => deleteModel(model.name)}
-                    style={{
-                      padding: "0.5rem 1rem",
-                      background: "#d63031",
-                      color: "#fff",
-                      border: "none",
-                      borderRadius: "6px",
-                      cursor: "pointer",
-                      fontSize: "0.85rem",
-                      whiteSpace: "nowrap"
-                    }}
-                  >
-                    Delete
-                  </button>
-                </div>
-              ))}
+                  {pulling ? "Pulling..." : "Pull"}
+                </button>
+              </div>
             </div>
           )}
         </div>