feat(web): Settings → LLM Providers panel + test-flow fixes (Phase 4)

Settings nav panel with per-provider add/change/delete/test, plus fixes
found in live testing.

UI: new Settings sidebar button + settingsPanel() Alpine component; per-
auth_kind rows (api_key / bedrock_bearer / ollama editable base_url). style.css.

Backend fixes (verified live via curl + Playwright MCP):
- /providers/{slug}/test: empty key from the 'Test' button now falls back to
  the STORED key — fixes minimax 'Illegal header value Bearer ' and gemini 403.
- secrets: empty-key guard in test_provider_auth.
- Ollama: test discovers installed models via /api/tags (list_ollama_models),
  skips embeddings — fixes 404 when recommended models aren't pulled. Confirmed
  live: discovers gemma4:latest, generated 5 cards.

Tests: 133 backend pass. KNOWN GAP: 6 settings-panel e2e tests have a strict-
locator issue (x-show-hidden rows in DOM); panel verified working live.

Author: NetDevAutomate

packages/studyloop/src/studyloop/provider_auth.py

@@ -136,6 +136,49 @@ def test_bedrock_bearer(token: str, region: str = "us-east-1") -> tuple[bool, st
     return True, "Bearer token verified against Bedrock."
 
 
+def list_ollama_models(base_url: str = "http://localhost:11434") -> list[str]:
+    """Return the model names actually installed on the Ollama server.
+
+    Queries ``GET /api/tags``. Returns ``[]`` if the server is unreachable or
+    returns no models. Names include the tag (e.g. ``gemma3:4b``,
+    ``gemma4:latest``).
+    """
+    import httpx
+
+    try:
+        resp = httpx.get(f"{base_url.rstrip('/')}/api/tags", timeout=2.0)
+        if resp.status_code != 200:
+            return []
+        data = resp.json()
+    except Exception:
+        return []
+
+    models = data.get("models", []) if isinstance(data, dict) else []
+    names = [m.get("name", "") for m in models if isinstance(m, dict)]
+    return [n for n in names if n]
+
+
+def _ollama_test_candidates(base_url: str, model: str) -> list[str]:
+    """Pick which models the test should try, preferring what's installed.
+
+    - explicit ``model`` → just that one.
+    - otherwise: installed models, recommended ones first (so a known-good
+      small model is tried before a random embedding model), then any other
+      installed model. Falls back to the recommended list if discovery fails
+      (so the error message still names sensible models).
+    """
+    if model:
+        return [model]
+    installed = list_ollama_models(base_url)
+    if not installed:
+        return list(OLLAMA_RECOMMENDED_MODELS)
+    # Embedding models can't generate chat/tool-use output — skip them.
+    installed = [m for m in installed if "embed" not in m.lower()]
+    preferred = [m for m in installed if m in OLLAMA_RECOMMENDED_MODELS]
+    rest = [m for m in installed if m not in OLLAMA_RECOMMENDED_MODELS]
+    return preferred + rest
+
+
 def test_ollama_generate(
     base_url: str = "http://localhost:11434", model: str = ""
 ) -> tuple[bool, str]:
@@ -146,14 +189,20 @@ def test_ollama_generate(
     can produce StudyLoop's structured tool-use output — the thing small models
     most often fail — without a second judge LLM.
 
-    When ``model`` is empty, tries :data:`OLLAMA_RECOMMENDED_MODELS` in order
-    and returns on the first success. Returns ``(True, msg)`` / ``(False, msg)``.
+    When ``model`` is empty, discovers installed models (via ``/api/tags``)
+    and tries them — recommended ones first — so the test uses a model the
+    user actually has. Returns ``(True, msg)`` / ``(False, msg)``.
     """
     from studyloop.content.generators import CardGenerationError
     from studyloop.content.generators.ollama import OllamaGenerator
     from studyloop.settings import CardGeneratorConfig, OllamaBackendConfig
 
-    candidates = [model] if model else list(OLLAMA_RECOMMENDED_MODELS)
+    candidates = _ollama_test_candidates(base_url, model)
+    if not candidates:
+        return False, (
+            f"No Ollama models installed at {base_url}. "
+            "Pull one first, e.g. `ollama pull qwen2.5:7b`."
+        )
     failures: list[str] = []
 
     for candidate in candidates:
@@ -185,6 +234,7 @@ def test_ollama_generate(
 __all__ = [
     "BEDROCK_TEST_MODEL",
     "OLLAMA_RECOMMENDED_MODELS",
+    "list_ollama_models",
     "test_bedrock_bearer",
     "test_ollama_generate",
 ]

packages/studyloop/src/studyloop/secrets.py

@@ -438,6 +438,11 @@ def test_provider_auth(provider: str, key: str = "", base_url: str = "") -> tupl
     if spec is None:
         return False, f"Unknown provider {provider!r}. Known: {', '.join(_AUTH_TEST_PROVIDERS)}"
 
+    # An empty key would build an invalid auth header (e.g. "Bearer ") that
+    # httpx rejects with "Illegal header value" — guard with a clear message.
+    if not key.strip():
+        return False, f"No API key provided for {provider}."
+
     try:
         ok, msg = _run_auth_test(provider, key, spec)
         return ok, msg

packages/studyloop/src/studyloop/web/routes/content_gen.py

@@ -468,7 +468,7 @@ async def test_provider(slug: str, body: TestProviderRequest) -> TestProviderRes
     Unknown slug → 404. The raw key is never logged or echoed.
     """
     from studyloop.content.generators.provider_profiles import PROFILES
-    from studyloop.secrets import test_provider_auth
+    from studyloop.secrets import get_secret, test_provider_auth
 
     slug = slug.lower().strip()
     if slug not in PROFILES:
@@ -478,13 +478,25 @@ async def test_provider(slug: str, body: TestProviderRequest) -> TestProviderRes
         ok, message = await asyncio.to_thread(
             test_provider_auth, "ollama", "", _ollama_base_url()
         )
-    elif slug == "bedrock" and body.key.strip():
-        # Real bearer-token Converse probe — off-thread (network + boto3).
-        ok, message = await asyncio.to_thread(test_provider_auth, "bedrock", body.key)
-    else:
-        # Cheap HTTP auth check (api-key providers) or bedrock no-key fast-path.
-        ok, message = test_provider_auth(slug, body.key)
-
+        return TestProviderResponse(ok=ok, message=message)
+
+    if slug == "bedrock":
+        # Prefer the typed token; else the stored one. With neither, fall to the
+        # AWS-SDK/profile path (test_provider_auth returns the informational msg).
+        token = body.key.strip() or (get_secret("bedrock_bearer_token") or "")
+        ok, message = await asyncio.to_thread(test_provider_auth, "bedrock", token)
+        return TestProviderResponse(ok=ok, message=message)
+
+    # API-key providers. The "Test" button sends an empty key (the browser
+    # never holds the stored secret), so fall back to the stored key. With no
+    # key anywhere there is nothing to test — say so rather than make an
+    # empty-credential HTTP call.
+    key = body.key.strip() or (get_secret(slug) or "")
+    if not key:
+        return TestProviderResponse(
+            ok=False, message=f"No stored key for {slug}. Enter a key and Test & save."
+        )
+    ok, message = test_provider_auth(slug, key)
     return TestProviderResponse(ok=ok, message=message)
 
 

packages/studyloop/src/studyloop/web/static/index.html

@@ -205,6 +205,15 @@
           </div>
         </div>
       </div>
+
+      <!-- Spacer pushes Settings to the bottom of the sidebar (gear convention) -->
+      <div class="sidebar-spacer" aria-hidden="true"></div>
+      <button class="sidebar-btn"
+              :class="{ active: $store.nav.is('settings') }"
+              @click="$store.nav.go('settings')">
+        <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="3"/><path d="M19.4 15a1.65 1.65 0 00.33 1.82l.06.06a2 2 0 11-2.83 2.83l-.06-.06a1.65 1.65 0 00-1.82-.33 1.65 1.65 0 00-1 1.51V21a2 2 0 01-4 0v-.09A1.65 1.65 0 009 19.4a1.65 1.65 0 00-1.82.33l-.06.06a2 2 0 11-2.83-2.83l.06-.06a1.65 1.65 0 00.33-1.82 1.65 1.65 0 00-1.51-1H3a2 2 0 010-4h.09A1.65 1.65 0 004.6 9a1.65 1.65 0 00-.33-1.82l-.06-.06a2 2 0 112.83-2.83l.06.06a1.65 1.65 0 001.82.33H9a1.65 1.65 0 001-1.51V3a2 2 0 014 0v.09a1.65 1.65 0 001 1.51 1.65 1.65 0 001.82-.33l.06-.06a2 2 0 112.83 2.83l-.06.06a1.65 1.65 0 00-.33 1.82V9a1.65 1.65 0 001.51 1H21a2 2 0 010 4h-.09a1.65 1.65 0 00-1.51 1z"/></svg>
+        <span>Settings</span>
+      </button>
     </nav>
 
     <!-- Content area -->
@@ -1279,6 +1288,87 @@ <h2>Start a Study Session</h2>
         </div>
       </div>
 
+      <!-- ============================================================ -->
+      <!-- SETTINGS VIEW — LLM Providers admin                          -->
+      <!-- ============================================================ -->
+      <div x-show="$store.nav.is('settings')" x-cloak
+           x-data="settingsPanel()" x-init="init()">
+        <div class="settings-panel">
+          <h2>Settings</h2>
+          <section class="settings-section">
+            <h3>LLM Providers</h3>
+            <p class="settings-blurb">
+              Manage credentials for content generation. Keys are encrypted at
+              rest in <code>~/.config/studyloop/</code> and never leave this machine.
+            </p>
+
+            <template x-for="p in providers" :key="p.slug">
+              <div class="provider-row">
+                <div class="provider-row-header">
+                  <span class="provider-label" x-text="p.label"></span>
+                  <span class="provider-status"
+                        :class="p.available ? 'status-ok' : 'status-missing'"
+                        x-text="p.available ? 'configured' : 'not configured'"></span>
+                </div>
+
+                <!-- API-key providers -->
+                <div x-show="p.auth_kind === 'api_key'" class="provider-controls">
+                  <input type="password" x-model="inputs[p.slug]"
+                         :placeholder="p.available ? '••••••••• (stored — type to replace)' : 'Paste API key'"
+                         autocomplete="off" spellcheck="false" />
+                  <button type="button" @click="saveKey(p.slug)"
+                          :disabled="busy === p.slug || !inputs[p.slug]?.trim()"
+                          x-text="busy === p.slug ? 'Testing…' : 'Test & save'"></button>
+                  <button type="button" class="danger-btn" x-show="p.available"
+                          @click="deleteKey(p.slug)">Delete</button>
+                  <button type="button" @click="testOnly(p.slug)"
+                          :disabled="busy === p.slug || !p.available">Test</button>
+                </div>
+
+                <!-- Bedrock bearer token -->
+                <div x-show="p.auth_kind === 'bedrock_bearer'" class="provider-controls">
+                  <input type="password" x-model="inputs['bedrock']"
+                         placeholder="Paste AWS bearer token (optional)"
+                         autocomplete="off" spellcheck="false" />
+                  <button type="button" @click="saveBearer()"
+                          :disabled="busy === 'bedrock' || !inputs['bedrock']?.trim()"
+                          x-text="busy === 'bedrock' ? 'Testing…' : 'Test & save'"></button>
+                  <button type="button" class="danger-btn" x-show="p.available"
+                          @click="deleteBearer()">Delete token</button>
+                  <button type="button" @click="testOnly('bedrock')"
+                          :disabled="busy === 'bedrock'">Test AWS creds</button>
+                  <small class="settings-hint">
+                    Bearer token (<code>AWS_BEARER_TOKEN_BEDROCK</code>) for accounts that
+                    use token auth. Leave empty to use your AWS profile / IAM role instead.
+                  </small>
+                </div>
+
+                <!-- Ollama (local, keyless) -->
+                <div x-show="p.auth_kind === 'local_keyless'" class="provider-controls">
+                  <input type="text" x-model="inputs['ollama']"
+                         :placeholder="p.base_url || 'http://localhost:11434'"
+                         autocomplete="off" spellcheck="false" />
+                  <button type="button" @click="saveOllamaUrl()"
+                          :disabled="busy === 'ollama' || !inputs['ollama']?.trim()">Save URL</button>
+                  <button type="button" @click="testOnly('ollama')"
+                          :disabled="busy === 'ollama'"
+                          x-text="busy === 'ollama' ? 'Testing…' : 'Test connection'"></button>
+                  <small class="settings-hint">
+                    Local &amp; keyless. Test runs a real generation against a recommended
+                    model — may take 10–30s on first call while the model loads.
+                  </small>
+                </div>
+
+                <small x-show="status[p.slug]?.error" class="key-error"
+                       x-text="status[p.slug]?.error"></small>
+                <small x-show="status[p.slug]?.ok" class="key-ok"
+                       x-text="status[p.slug]?.ok"></small>
+              </div>
+            </template>
+          </section>
+        </div>
+      </div>
+
     </div><!-- .content-area -->
   </div><!-- .app-layout -->
 
@@ -1293,7 +1383,7 @@ <h2>Start a Study Session</h2>
 
       init() {
         const hash = window.location.hash.slice(1);
-        const valid = ['flashcards', 'quizzes', 'generate', 'body-double', 'study-session'];
+        const valid = ['flashcards', 'quizzes', 'generate', 'body-double', 'study-session', 'settings'];
         if (hash && valid.includes(hash)) this.current = hash;
       },
 
@@ -1640,6 +1730,112 @@ <h2>Start a Study Session</h2>
     };
   }
 
+  /* ------------------------------------------------------------------
+   * Settings panel — LLM Providers admin (add/change/delete/test keys)
+   * ------------------------------------------------------------------ */
+  function settingsPanel() {
+    return {
+      providers: [],
+      inputs: {},          // { slug: string } live input values
+      status: {},          // { slug: { ok: string, error: string } }
+      busy: '',            // slug whose request is in flight
+
+      async init() {
+        await this.refreshProviders();
+      },
+
+      async refreshProviders() {
+        try {
+          const r = await fetch('/api/content/providers');
+          if (r.ok) this.providers = await r.json();
+        } catch { /* leave list as-is */ }
+      },
+
+      _ok(slug, msg) { this.status = { ...this.status, [slug]: { ok: msg, error: '' } }; },
+      _err(slug, msg) { this.status = { ...this.status, [slug]: { ok: '', error: msg } }; },
+      _clear(slug) { this.status = { ...this.status, [slug]: { ok: '', error: '' } }; },
+
+      async _postSecret(storeName, value, uiSlug) {
+        // Test + store via the secrets route; refresh on success.
+        this._clear(uiSlug);
+        try {
+          const r = await fetch('/api/content/secrets', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ provider: storeName, key: value }),
+          });
+          if (r.ok) {
+            this.inputs[uiSlug] = '';
+            this._ok(uiSlug, 'Verified and saved.');
+            await this.refreshProviders();
+          } else {
+            let detail = 'Could not verify the value.';
+            try { detail = (await r.json()).detail || detail; } catch {}
+            this._err(uiSlug, detail);
+          }
+        } catch { this._err(uiSlug, 'Network error.'); }
+      },
+
+      async _deleteSecret(storeName, uiSlug, okMsg) {
+        this._clear(uiSlug);
+        try {
+          const r = await fetch(`/api/content/secrets/${storeName}`, { method: 'DELETE' });
+          if (r.ok) { this._ok(uiSlug, okMsg); await this.refreshProviders(); }
+          else { this._err(uiSlug, 'Delete failed.'); }
+        } catch { this._err(uiSlug, 'Network error.'); }
+      },
+
+      async saveKey(slug) {
+        const v = this.inputs[slug]?.trim();
+        if (!v || this.busy) return;
+        this.busy = slug;
+        await this._postSecret(slug, v, slug);
+        this.busy = '';
+      },
+
+      async deleteKey(slug) { await this._deleteSecret(slug, slug, 'Key deleted.'); },
+
+      async saveBearer() {
+        const v = this.inputs['bedrock']?.trim();
+        if (!v || this.busy) return;
+        this.busy = 'bedrock';
+        await this._postSecret('bedrock_bearer_token', v, 'bedrock');
+        this.busy = '';
+      },
+
+      async deleteBearer() {
+        await this._deleteSecret('bedrock_bearer_token', 'bedrock', 'Bearer token deleted.');
+      },
+
+      async saveOllamaUrl() {
+        const v = this.inputs['ollama']?.trim();
+        if (!v || this.busy) return;
+        this.busy = 'ollama';
+        // ollama_base_url is a config value — stored without an auth-test.
+        await this._postSecret('ollama_base_url', v, 'ollama');
+        this.busy = '';
+      },
+
+      async testOnly(slug) {
+        if (this.busy) return;
+        this.busy = slug;
+        this._clear(slug);
+        try {
+          const key = slug === 'bedrock' ? (this.inputs['bedrock']?.trim() || '') : '';
+          const r = await fetch(`/api/content/providers/${slug}/test`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ key }),
+          });
+          const data = await r.json();
+          if (data.ok) this._ok(slug, data.message || 'Credentials valid.');
+          else this._err(slug, data.message || 'Test failed.');
+        } catch { this._err(slug, 'Network error.'); }
+        this.busy = '';
+      },
+    };
+  }
+
   /* ------------------------------------------------------------------
    * Session timer component (from session.html)
    * ------------------------------------------------------------------ */