Implement missing model runtime polish

Co-authored-by: Codex <codex@openai.com>

.env.example

@@ -1,5 +1,6 @@
 # Tiny Narrator local configuration.
 # Copy this file to .env and fill in the values for the services you want to run live.
+# The app loads .env automatically at startup. Process environment variables still override .env values.
 
 # App server
 GRADIO_SERVER_NAME=0.0.0.0
@@ -21,4 +22,5 @@ MINICPM_VISION_TIMEOUT_SECONDS=45
 
 # Image generation: Modal-hosted FLUX.2 klein worker
 KLEIN_MODAL_ENDPOINT=
+KLEIN_MODAL_TOKEN=
 KLEIN_MODAL_TIMEOUT_SECONDS=120

FIELD_NOTES.md

@@ -106,3 +106,7 @@ Deploy the worker with `modal deploy modal_workers/klein_image.py`, then set `KL
 `KLEIN_MODAL_TIMEOUT_SECONDS` defaults to 120 seconds, which accommodates warm inference but avoids blocking local demos indefinitely during cold starts.
 
 This design keeps verification stable without requiring Modal credentials or GPU access: the verifier checks fallback behavior, and live Modal deployment is a manual step documented in the README.
+
+## Pre-Demo Validation
+
+`scripts/live_smoke.py` is an opt-in script for confirming live model inference before a demo. It calls `/api/runtime-status`, `/api/describe-image`, and `/api/generate-image`, then reports pass/skip/fail per role. Unconfigured runtimes are skipped, and the script exits non-zero only when a configured live check fails. Secrets are never printed, so the output is safe to include in demo logs or field notes.

README.md

@@ -40,7 +40,7 @@ Install dependencies:
 python -m pip install -r requirements.txt
 ```
 
-Copy the example environment file if you want a local `.env` starting point:
+Copy the example environment file to `.env` and fill in the values. The app loads `.env` automatically at startup, so no shell exports are required. Process environment variables still override `.env` values.
 
 ```powershell
 Copy-Item .env.example .env
@@ -68,7 +68,7 @@ The image generation path uses a Modal-hosted `black-forest-labs/FLUX.2-klein-4B
 modal deploy modal_workers/klein_image.py
 ```
 
-Set `KLEIN_MODAL_ENDPOINT` to the deployed worker URL. When configured, `/api/generate-image` and `/api/generate-article` call the live Modal endpoint for real Klein inference. When the endpoint is not set, unreachable, or returns invalid data, the app falls back to bundled SVG assets with explicit fallback metadata.
+Set `KLEIN_MODAL_ENDPOINT` to the deployed worker URL. Set `KLEIN_MODAL_TOKEN` to a shared secret and configure the same token in the Modal worker environment (e.g. via `modal secret create`). When the token is configured, the worker rejects unauthenticated `POST /generate` requests with HTTP 401. When no token is set on either side, requests are allowed for local compatibility.
 
 `/api/runtime-status` reports whether the Modal Klein worker is online or fallback-ready. `/api/runtime-setup` includes the deploy command and required environment variables.
 
@@ -88,6 +88,7 @@ Useful environment variables:
 | `GRADIO_SERVER_PORT` / `PORT` | `7860` | App port |
 | `PUBLIC_BASE_URL` | `http://localhost:7860` | Base URL used in generated judge API commands |
 | `KLEIN_MODAL_ENDPOINT` | *(empty)* | Base URL for the Modal Klein worker, without trailing slash. When set, `/api/generate-image` calls the live worker. |
+| `KLEIN_MODAL_TOKEN` | *(empty)* | Shared bearer token for Modal worker auth. When set, the app sends `Authorization: Bearer <token>` and the worker rejects unauthenticated requests. |
 | `KLEIN_MODAL_TIMEOUT_SECONDS` | `120` | Request timeout for Modal Klein image generation. |
 | `MINICPM_VISION_BASE_URL` | *(empty)* | OpenAI-compatible MiniCPM-V-4.6 base URL; root or `/v1` both work. |
 | `MINICPM_VISION_API_KEY` | *(empty)* | Bearer token for the MiniCPM vision endpoint. |
@@ -102,6 +103,16 @@ python scripts/verify.py
 
 The verifier checks syntax, static assets, Space metadata consistency, deterministic fallback model paths, and generated speech file behavior.
 
+## Live Model Smoke Tests
+
+After starting the app with configured model endpoints, run the opt-in smoke script to verify live inference:
+
+```powershell
+python scripts/live_smoke.py --base-url http://127.0.0.1:7860
+```
+
+The smoke script checks `/api/runtime-status`, `/api/describe-image`, and `/api/generate-image`. It skips checks for unconfigured runtimes and exits non-zero only when a configured live check fails. Secrets are never printed.
+
 `/api/model-budget` exposes numeric parameter counts for every model role and reports whether the full stack stays within the 4B Tiny Titan limit.
 
 `/api/runtime-setup` exposes the commands, environment values, and fallback paths used for the model stack so the demo can be reproduced from the same data the UI displays.

app.py

@@ -12,12 +12,14 @@ from pathlib import Path
 from typing import Any
 from uuid import uuid4
 
+from dotenv import load_dotenv
 from fastapi import Request
 from fastapi.responses import HTMLResponse, JSONResponse
 from fastapi.staticfiles import StaticFiles
 from gradio import Server
 from pydantic import BaseModel
 
+load_dotenv()
 
 ROOT = Path(__file__).parent
 STATIC_DIR = ROOT / "static"
@@ -38,6 +40,7 @@ GRADIO_SERVER_NAME = os.getenv("GRADIO_SERVER_NAME", "0.0.0.0")
 GRADIO_SERVER_PORT = int(os.getenv("PORT", os.getenv("GRADIO_SERVER_PORT", "7860")))
 PUBLIC_BASE_URL = os.getenv("PUBLIC_BASE_URL", f"http://localhost:{GRADIO_SERVER_PORT}").rstrip("/")
 KLEIN_MODAL_ENDPOINT = os.getenv("KLEIN_MODAL_ENDPOINT", "").rstrip("/")
+KLEIN_MODAL_TOKEN = os.getenv("KLEIN_MODAL_TOKEN", "")
 KLEIN_MODAL_TIMEOUT_SECONDS = _int_env("KLEIN_MODAL_TIMEOUT_SECONDS", 120)
 MINICPM_VISION_BASE_URL = os.getenv("MINICPM_VISION_BASE_URL", "").rstrip("/")
 MINICPM_VISION_API_KEY = os.getenv("MINICPM_VISION_API_KEY", "")
@@ -220,6 +223,7 @@ def runtime_setup_core() -> dict[str, Any]:
                 "command": "modal deploy modal_workers/klein_image.py",
                 "env": {
                     "KLEIN_MODAL_ENDPOINT": KLEIN_MODAL_ENDPOINT or "(set to Modal worker URL)",
+                    "KLEIN_MODAL_TOKEN": "(configured)" if KLEIN_MODAL_TOKEN else "(not set)",
                     "KLEIN_MODAL_TIMEOUT_SECONDS": str(KLEIN_MODAL_TIMEOUT_SECONDS),
                 },
                 "fallback": "bundled generated article assets",
@@ -619,8 +623,12 @@ def _runtime_status_core() -> dict[str, Any]:
     klein_status: dict[str, Any]
     if KLEIN_MODAL_ENDPOINT:
         try:
+            health_headers: dict[str, str] = {}
+            if KLEIN_MODAL_TOKEN:
+                health_headers["Authorization"] = f"Bearer {KLEIN_MODAL_TOKEN}"
             request = urllib.request.Request(
                 f"{KLEIN_MODAL_ENDPOINT}/health", method="GET",
+                headers=health_headers,
             )
             with urllib.request.urlopen(request, timeout=5) as response:
                 payload = json.loads(response.read().decode("utf-8"))
@@ -1056,10 +1064,13 @@ def _call_modal_klein(prompt: str, seed: int | None) -> dict[str, Any]:
     """Call the Modal Klein worker for live image generation."""
     start = time.perf_counter()
     body = json.dumps({"prompt": prompt, "seed": seed}).encode("utf-8")
+    headers: dict[str, str] = {"Content-Type": "application/json"}
+    if KLEIN_MODAL_TOKEN:
+        headers["Authorization"] = f"Bearer {KLEIN_MODAL_TOKEN}"
     request = urllib.request.Request(
         f"{KLEIN_MODAL_ENDPOINT}/generate",
         data=body,
-        headers={"Content-Type": "application/json"},
+        headers=headers,
         method="POST",
     )
     with urllib.request.urlopen(request, timeout=KLEIN_MODAL_TIMEOUT_SECONDS) as response:

modal_workers/klein_image.py

@@ -14,6 +14,7 @@ Tiny Narrator's app.py calls these routes through KLEIN_MODAL_ENDPOINT.
 from __future__ import annotations
 
 import io
+import os
 import time
 from pathlib import Path
 from uuid import uuid4
@@ -70,14 +71,30 @@ def _get_pipeline():
 )
 @modal.asgi_app()
 def klein_api():
-    from fastapi import FastAPI, HTTPException
+    from fastapi import FastAPI, HTTPException, Request
     from fastapi.responses import Response
     import torch
 
     api = FastAPI(title="Tiny Narrator Klein Worker")
 
+    def _check_token(request: Request) -> None:
+        """Reject the request if a token is configured but not provided or mismatched."""
+        expected = os.getenv("KLEIN_MODAL_TOKEN", "")
+        if not expected:
+            return
+        auth_header = request.headers.get("authorization", "")
+        token_header = request.headers.get("x-tiny-narrator-token", "")
+        provided = ""
+        if auth_header.startswith("Bearer "):
+            provided = auth_header[len("Bearer "):]
+        elif token_header:
+            provided = token_header
+        if provided != expected:
+            raise HTTPException(status_code=401, detail="Unauthorized")
+
     @api.get("/health")
-    async def health() -> dict:
+    async def health(request: Request) -> dict:
+        _check_token(request)
         return {
             "ok": True,
             "model": IMAGE_MODEL_ID,
@@ -85,13 +102,14 @@ def klein_api():
         }
 
     @api.post("/generate")
-    async def generate(request: dict) -> dict:
+    async def generate(request: Request, body: dict) -> dict:
+        _check_token(request)
         start = time.perf_counter()
-        prompt = str(request.get("prompt") or "").strip()
+        prompt = str(body.get("prompt") or "").strip()
         if not prompt:
             raise HTTPException(status_code=400, detail="prompt is required")
 
-        seed = request.get("seed")
+        seed = body.get("seed")
         generator = None
         if seed is not None:
             try:

requirements.txt

@@ -2,3 +2,4 @@ gradio==6.16.0
 pydantic>=2.7.0
 kokoro>=0.9.4
 soundfile>=0.12.1
+python-dotenv

scripts/live_smoke.py

@@ -0,0 +1,215 @@
+"""Live model smoke tests for Tiny Narrator.
+
+Run against a running local app to verify configured model endpoints:
+
+    python scripts/live_smoke.py --base-url http://127.0.0.1:7860
+
+Checks:
+  - /api/runtime-status: confirms reader brain, speech, vision, image generation status
+  - /api/describe-image: confirms MiniCPM-V-4.6 image description path
+  - /api/generate-image: confirms Modal Klein image generation path
+
+Exit codes:
+  0 - all configured checks passed or skipped
+  1 - one or more configured checks failed
+
+Secrets (API keys, tokens) are never printed.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+import urllib.error
+import urllib.request
+
+
+def _get_json(url: str, timeout: int = 30) -> dict:
+    """Fetch a JSON GET endpoint and return the parsed payload."""
+    request = urllib.request.Request(url, method="GET")
+    with urllib.request.urlopen(request, timeout=timeout) as response:
+        return json.loads(response.read().decode("utf-8"))
+
+
+def _post_json(url: str, payload: dict, timeout: int = 60) -> dict:
+    """POST JSON to an endpoint and return the parsed response."""
+    body = json.dumps(payload).encode("utf-8")
+    request = urllib.request.Request(
+        url,
+        data=body,
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    with urllib.request.urlopen(request, timeout=timeout) as response:
+        return json.loads(response.read().decode("utf-8"))
+
+
+def _format_elapsed(ms: float) -> str:
+    if ms < 1000:
+        return f"{round(ms)} ms"
+    return f"{ms / 1000:.2f} s"
+
+
+def _status_label(status: str) -> str:
+    return {
+        "online": "PASS",
+        "fallback-ready": "SKIP",
+        "fallback": "SKIP",
+        "placeholder-ready": "SKIP",
+        "offline": "FAIL",
+    }.get(status, "SKIP")
+
+
+def _role_status(runtime_status: dict[str, dict], role: str) -> str:
+    return str(runtime_status.get(role, {}).get("status", "unknown"))
+
+
+def _role_is_configured(runtime_status: dict[str, dict], role: str) -> bool:
+    details = runtime_status.get(role, {})
+    if details.get("configured") is True:
+        return True
+    return bool(details.get("endpoint") or details.get("base_url"))
+
+
+def check_runtime_status(base_url: str) -> dict[str, dict]:
+    """Fetch runtime status and return per-role metadata."""
+    start = time.perf_counter()
+    try:
+        payload = _get_json(f"{base_url}/api/runtime-status")
+        elapsed = (time.perf_counter() - start) * 1000
+        roles = {
+            "reader_brain": payload.get("reader_brain", {}),
+            "vision": payload.get("vision", {}),
+            "speech": payload.get("speech", {}),
+            "image_generation": payload.get("image_generation", {}),
+        }
+        labels = ", ".join(f"{role}={_role_status(roles, role)}" for role in roles)
+        print(f"  runtime-status    {_format_elapsed(elapsed):>10}  {labels}")
+        return roles
+    except (OSError, urllib.error.URLError, TimeoutError, json.JSONDecodeError) as exc:
+        elapsed = (time.perf_counter() - start) * 1000
+        print(f"  runtime-status    {_format_elapsed(elapsed):>10}  FAIL ({exc.__class__.__name__})")
+        return {}
+
+
+def check_describe_image(base_url: str, runtime_status: dict[str, dict]) -> bool:
+    """Smoke test /api/describe-image for a known article image."""
+    vision_status = _role_status(runtime_status, "vision")
+    vision_configured = _role_is_configured(runtime_status, "vision")
+    if not vision_configured and vision_status in {"fallback-ready", "unknown"}:
+        print(f"  describe-image    {'SKIP':>10}  vision not configured")
+        return True
+    if vision_configured and vision_status != "online":
+        print(f"  describe-image    {'FAIL':>10}  vision configured but status={vision_status}")
+        return False
+
+    start = time.perf_counter()
+    try:
+        payload = _post_json(
+            f"{base_url}/api/describe-image",
+            {"image_id": "desk-reader", "caption": "article reader"},
+            timeout=90,
+        )
+        elapsed = (time.perf_counter() - start) * 1000
+        runtime = payload.get("runtime", "unknown")
+        alt_text = payload.get("alt_text", "")
+        truncated = alt_text[:80] + ("..." if len(alt_text) > 80 else "") if alt_text else "(empty)"
+        if runtime == "minicpm-v4.6":
+            print(f"  describe-image    {_format_elapsed(elapsed):>10}  PASS  runtime={runtime}  alt={truncated}")
+            return True
+        elif runtime == "fallback":
+            print(f"  describe-image    {_format_elapsed(elapsed):>10}  FAIL  runtime={runtime} (expected live)")
+            return False
+        else:
+            print(f"  describe-image    {_format_elapsed(elapsed):>10}  FAIL  runtime={runtime} (unexpected)")
+            return False
+    except (OSError, urllib.error.URLError, TimeoutError, json.JSONDecodeError) as exc:
+        elapsed = (time.perf_counter() - start) * 1000
+        print(f"  describe-image    {_format_elapsed(elapsed):>10}  FAIL  ({exc.__class__.__name__})")
+        return False
+
+
+def check_generate_image(base_url: str, runtime_status: dict[str, dict]) -> bool:
+    """Smoke test /api/generate-image with a deterministic prompt."""
+    image_status = _role_status(runtime_status, "image_generation")
+    image_configured = _role_is_configured(runtime_status, "image_generation")
+    if not image_configured and image_status in {"fallback-ready", "unknown"}:
+        print(f"  generate-image    {'SKIP':>10}  Klein not configured")
+        return True
+    if image_configured and image_status != "online":
+        print(f"  generate-image    {'FAIL':>10}  Klein configured but status={image_status}")
+        return False
+
+    start = time.perf_counter()
+    try:
+        payload = _post_json(
+            f"{base_url}/api/generate-image",
+            {"prompt": "smoke test accessible article thumbnail", "seed": 42},
+            timeout=180,
+        )
+        elapsed = (time.perf_counter() - start) * 1000
+        runtime = payload.get("runtime", "unknown")
+        image_url = payload.get("image_url", "")
+        if runtime == "modal-klein":
+            print(f"  generate-image    {_format_elapsed(elapsed):>10}  PASS  runtime={runtime}  url={image_url[:60]}")
+            return True
+        elif runtime == "fallback":
+            print(f"  generate-image    {_format_elapsed(elapsed):>10}  FAIL  runtime={runtime} (expected live Klein)")
+            return False
+        else:
+            print(f"  generate-image    {_format_elapsed(elapsed):>10}  FAIL  runtime={runtime} (unexpected)")
+            return False
+    except (OSError, urllib.error.URLError, TimeoutError, json.JSONDecodeError) as exc:
+        elapsed = (time.perf_counter() - start) * 1000
+        print(f"  generate-image    {_format_elapsed(elapsed):>10}  FAIL  ({exc.__class__.__name__})")
+        return False
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Tiny Narrator live model smoke tests")
+    parser.add_argument("--base-url", default="http://127.0.0.1:7860", help="App base URL (default: http://127.0.0.1:7860)")
+    args = parser.parse_args()
+
+    base_url = args.base_url.rstrip("/")
+    overall_start = time.perf_counter()
+
+    print(f"Tiny Narrator live smoke tests — {base_url}")
+    print()
+
+    print("Checks:")
+    runtime_status = check_runtime_status(base_url)
+
+    if not runtime_status:
+        print()
+        print("Could not reach the app. Is it running?")
+        sys.exit(1)
+
+    vision_configured = _role_is_configured(runtime_status, "vision")
+    klein_configured = _role_is_configured(runtime_status, "image_generation")
+
+    describe_ok = check_describe_image(base_url, runtime_status)
+    generate_ok = check_generate_image(base_url, runtime_status)
+
+    overall_elapsed = (time.perf_counter() - overall_start) * 1000
+    print()
+
+    failures = []
+    if vision_configured and not describe_ok:
+        failures.append("describe-image")
+    if klein_configured and not generate_ok:
+        failures.append("generate-image")
+
+    if failures:
+        print(f"FAILED: {', '.join(failures)}  ({_format_elapsed(overall_elapsed)} total)")
+        sys.exit(1)
+    else:
+        configured_count = sum(1 for v in [vision_configured, klein_configured] if v)
+        skipped_count = 2 - configured_count
+        print(f"DONE: {configured_count} passed, {skipped_count} skipped  ({_format_elapsed(overall_elapsed)} total)")
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

scripts/verify.py

@@ -90,6 +90,8 @@ def verify_static_assets() -> None:
     assert_true("loadDemoScript" not in app_js, "Article frontend should not render the structured demo script")
     assert_true("loadModelBudget" in app_js, "Article frontend should render the model stack panel")
     assert_true("/api/model-budget" in app_js, "Article frontend should fetch model budget data")
+    assert_true("/api/runtime-status" in app_js, "Article frontend should fetch runtime status")
+    assert_true("status-pill" in app_js or "statusClass" in app_js, "Article frontend should render per-role status labels")
     assert_true("modelStackList.innerHTML" in app_js, "Article frontend should render model stack items")
     assert_true("Tiny Titan pass" in app_js, "Article frontend should render per-model Tiny Titan pass labels")
     assert_true("/evidence" not in index_html, "Article page should not link to a removed evidence page")
@@ -118,6 +120,12 @@ def verify_static_assets() -> None:
     assert_true("readerQueueList" not in app_js, "Frontend should not bind a visible reader queue")
     assert_true("narrate(node.index)" in app_js, "Reader mode should support click-to-read article items")
 
+    assert_true("describeGeneratedThumbnail" in generate_js, "Generate frontend should describe generated thumbnails")
+    assert_true("/api/describe-image" in generate_js, "Generate frontend should call describe-image for thumbnails")
+    assert_true("image_url" in generate_js, "Generate frontend should send image_url to describe-image")
+    assert_true("generatedThumbnail.alt" in generate_js, "Generate frontend should update thumbnail alt from descriptor")
+    assert_true("fallbackAlt" in generate_js, "Generate frontend should preserve fallback alt on descriptor failure")
+
     submission = (ROOT / "SUBMISSION.md").read_text(encoding="utf-8")
     for target in ["Tiny Titan", "Llama Champion", "Off-Brand", "Field Notes"]:
         assert_true(target in submission, f"Submission packet should mention {target}")
@@ -174,13 +182,62 @@ def verify_space_metadata() -> None:
     assert_true("Apache License" in license_text, "Repository should include the Apache license text")
     assert_true("Version 2.0" in license_text, "Repository license should match Space metadata")
     assert_true(f"gradio=={sdk_version}" in requirements, "requirements.txt should pin Gradio to sdk_version")
-    for package in ["pydantic", "kokoro", "soundfile"]:
+    for package in ["pydantic", "kokoro", "soundfile", "python-dotenv"]:
         assert_true(
-            any(line.startswith(f"{package}>=") or line.startswith(f"{package}==") for line in requirements),
+            any(
+                line.startswith(f"{package}>=") or line.startswith(f"{package}==") or line.strip() == package
+                for line in requirements
+            ),
             f"requirements.txt should include {package}",
         )
 
 
+def verify_dotenv_wiring() -> None:
+    """Verify that python-dotenv is wired in before core env constants are read."""
+    requirements = (ROOT / "requirements.txt").read_text(encoding="utf-8").splitlines()
+    assert_true(
+        any(line.strip() == "python-dotenv" or line.startswith("python-dotenv>=") for line in requirements),
+        "requirements.txt should include python-dotenv",
+    )
+
+    app_source = (ROOT / "app.py").read_text(encoding="utf-8")
+    assert_true("from dotenv import load_dotenv" in app_source, "app.py should import load_dotenv")
+    assert_true("load_dotenv()" in app_source, "app.py should call load_dotenv()")
+
+    import_pos = app_source.index("from dotenv import load_dotenv")
+    call_pos = app_source.index("load_dotenv()")
+    llama_const = app_source.index("LLAMA_CPP_BASE_URL = os.getenv")
+    assert_true(
+        import_pos < call_pos < llama_const,
+        "load_dotenv() should be called before LLAMA_CPP_BASE_URL is assigned",
+    )
+
+    env_example = ROOT / ".env.example"
+    assert_true(env_example.exists(), ".env.example should exist")
+    env_content = env_example.read_text(encoding="utf-8")
+    for secret_pattern in ["sk-", "AKIA", "ghp_", "xoxb-"]:
+        assert_true(
+            secret_pattern not in env_content,
+            f".env.example should not contain real-looking secrets ({secret_pattern})",
+        )
+
+
+def verify_live_smoke_script() -> None:
+    """Verify that the live smoke test script exists, is syntactically valid, and documents redaction."""
+    smoke_path = ROOT / "scripts" / "live_smoke.py"
+    assert_true(smoke_path.exists(), "scripts/live_smoke.py should exist")
+    py_compile.compile(str(smoke_path), doraise=True)
+    smoke_source = smoke_path.read_text(encoding="utf-8")
+    assert_true("--base-url" in smoke_source, "Smoke script should support --base-url argument")
+    assert_true("/api/runtime-status" in smoke_source, "Smoke script should check runtime status")
+    assert_true("/api/describe-image" in smoke_source, "Smoke script should check describe-image")
+    assert_true("/api/generate-image" in smoke_source, "Smoke script should check generate-image")
+    assert_true("_role_is_configured" in smoke_source, "Smoke script should fail configured live paths instead of skipping them")
+    assert_true('details.get("configured") is True' in smoke_source, "Smoke script should preserve configured metadata from runtime status")
+    assert_true("SKIP" in smoke_source or "skip" in smoke_source, "Smoke script should document skipping behavior")
+    assert_true("Secrets" in smoke_source or "secrets" in smoke_source or "never printed" in smoke_source.lower(), "Smoke script should document secret redaction")
+
+
 def verify_core_fallbacks() -> None:
     narration = app.reader_brain_core(
         node_type="heading",
@@ -337,6 +394,58 @@ def verify_modal_klein_integration() -> None:
     assert_true("404" in worker_source or "not found" in worker_source.lower(), "Modal worker should handle missing media with 404")
     assert_true("reload" in worker_source, "Modal worker should reload volume before serving")
 
+    # Test: auth wiring — app sends bearer token when configured
+    with patch.object(app, "KLEIN_MODAL_ENDPOINT", "https://example-modal.modal.run"), patch.object(app, "KLEIN_MODAL_TOKEN", "test-secret-token"):
+        with patch("urllib.request.urlopen", return_value=mock_response) as urlopen_mock:
+            app.generate_image_core("auth test", seed=1)
+            sent_request = urlopen_mock.call_args.args[0]
+            assert_true(
+                sent_request.headers.get("Authorization") == "Bearer test-secret-token",
+                "App should send Bearer token when KLEIN_MODAL_TOKEN is configured",
+            )
+
+    # Test: auth wiring — health check sends bearer token when configured
+    good_health = MagicMock()
+    good_health.read.return_value = json.dumps({"ok": True, "model": app.MODEL_MANIFEST["image_generation"]["id"], "runtime": "modal-klein"}).encode("utf-8")
+    good_health.__enter__ = lambda s: s
+    good_health.__exit__ = MagicMock(return_value=False)
+    with patch.object(app, "KLEIN_MODAL_ENDPOINT", "https://example-modal.modal.run"), patch.object(app, "KLEIN_MODAL_TOKEN", "test-secret-token"):
+        with patch("urllib.request.urlopen", return_value=good_health) as urlopen_mock:
+            app._runtime_status_core()
+            health_request = urlopen_mock.call_args.args[0]
+            assert_true(
+                health_request.headers.get("Authorization") == "Bearer test-secret-token",
+                "App should send Bearer token for health checks when KLEIN_MODAL_TOKEN is configured",
+            )
+
+    # Test: .env.example includes KLEIN_MODAL_TOKEN
+    env_example = (ROOT / ".env.example").read_text(encoding="utf-8")
+    assert_true("KLEIN_MODAL_TOKEN" in env_example, ".env.example should document KLEIN_MODAL_TOKEN")
+
+    # Test: worker validates token
+    assert_true("KLEIN_MODAL_TOKEN" in worker_source, "Modal worker should read KLEIN_MODAL_TOKEN")
+    assert_true("401" in worker_source, "Modal worker should reject unauthorized requests with 401")
+    assert_true("_check_token" in worker_source, "Modal worker should have a token validation helper")
+    assert_true(
+        "async def health(request: Request)" in worker_source,
+        "Modal worker health route should accept the request for token validation",
+    )
+
+    # Test: runtime setup does not expose the token value
+    with patch.object(app, "KLEIN_MODAL_TOKEN", "super-secret-value"):
+        setup = app.runtime_setup_core()
+        setup_json = json.dumps(setup)
+        assert_true("super-secret-value" not in setup_json, "Runtime setup must never expose the token value")
+        image_step = next(step for step in setup["steps"] if step["role"] == "image_generation")
+        assert_true(
+            "KLEIN_MODAL_TOKEN" in image_step["env"],
+            "Runtime setup should document KLEIN_MODAL_TOKEN",
+        )
+        assert_true(
+            image_step["env"]["KLEIN_MODAL_TOKEN"] == "(configured)",
+            "Runtime setup should show token as configured without exposing the value",
+        )
+
     # Test: runtime status includes Modal Klein path
     with patch.object(app, "KLEIN_MODAL_ENDPOINT", ""):
         status = app._runtime_status_core()
@@ -821,6 +930,8 @@ def main() -> None:
     py_compile.compile(str(ROOT / "modal_workers" / "klein_image.py"), doraise=True)
     verify_static_assets()
     verify_space_metadata()
+    verify_dotenv_wiring()
+    verify_live_smoke_script()
     verify_core_fallbacks()
     verify_modal_klein_integration()
     verify_minicpm_vision_integration()

static/app.css

@@ -589,6 +589,33 @@ dd {
   border: 1px solid rgba(42, 122, 110, 0.2);
 }
 
+.status-pill {
+  font-family: var(--mono);
+  font-size: 0.66rem;
+  font-weight: 700;
+  padding: 1px 6px;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+}
+
+.status-online {
+  background: rgba(34, 140, 60, 0.12);
+  color: #1d7a34;
+  border: 1px solid rgba(34, 140, 60, 0.25);
+}
+
+.status-fallback {
+  background: rgba(160, 140, 60, 0.1);
+  color: #7a6a20;
+  border: 1px solid rgba(160, 140, 60, 0.25);
+}
+
+.status-offline {
+  background: rgba(180, 50, 50, 0.1);
+  color: #a03030;
+  border: 1px solid rgba(180, 50, 50, 0.25);
+}
+
 .image-receipt-pill {
   background: rgba(180, 150, 60, 0.1);
   color: #7a6520;

static/app.js

@@ -213,24 +213,12 @@ function roleLabel(role) {
 }
 
 async function loadModelBudget() {
-  try {
-    const payload = await postJson("/api/model-budget");
-    modelBudgetStatus.textContent = payload.all_models_within_limit
-      ? `All <= ${payload.limit_billion}B`
-      : "Review needed";
-    modelStackList.innerHTML = payload.models
-      .map((model) => `
-        <li>
-          <div class="budget-row">
-            <span>${escapeHtml(roleLabel(model.role))}</span>
-            <span class="budget-pill">${escapeHtml(model.params)}</span>
-          </div>
-          <p>${escapeHtml(model.runtime)} | ${model.within_limit ? "Tiny Titan pass" : "Review parameter budget"}</p>
-          <p>${escapeHtml(model.id)}</p>
-        </li>
-      `)
-      .join("");
-  } catch {
+  const [budget, runtimeStatus] = await Promise.allSettled([
+    postJson("/api/model-budget"),
+    postJson("/api/runtime-status"),
+  ]);
+
+  if (budget.status === "rejected") {
     modelBudgetStatus.textContent = "Unavailable";
     modelStackList.innerHTML = `
       <li>
@@ -241,7 +229,35 @@ async function loadModelBudget() {
         <p>Model budget is unavailable.</p>
       </li>
     `;
+    return;
   }
+
+  const payload = budget.value;
+  const statusMap = runtimeStatus.status === "fulfilled" ? runtimeStatus.value : null;
+
+  modelBudgetStatus.textContent = payload.all_models_within_limit
+    ? `All <= ${payload.limit_billion}B`
+    : "Review needed";
+
+  modelStackList.innerHTML = payload.models
+    .map((model) => {
+      const status = statusMap?.[model.role];
+      const statusLabel = status?.status || "unknown";
+      const statusClass = statusLabel === "online" ? "status-online"
+        : statusLabel === "offline" ? "status-offline"
+        : "status-fallback";
+      return `
+        <li>
+          <div class="budget-row">
+            <span>${escapeHtml(roleLabel(model.role))}</span>
+            <span class="budget-pill">${escapeHtml(model.params)}</span>
+          </div>
+          <p>${escapeHtml(model.runtime)} | ${model.within_limit ? "Tiny Titan pass" : "Review parameter budget"} | <span class="status-pill ${statusClass}">${escapeHtml(statusLabel)}</span></p>
+          <p>${escapeHtml(model.id)}</p>
+        </li>
+      `;
+    })
+    .join("");
 }
 
 async function loadImageDescriptions() {

static/generate.js

@@ -427,6 +427,27 @@ function renderArticle(payload) {
   }
 }
 
+async function describeGeneratedThumbnail(payload) {
+  const thumbnail = payload.thumbnail;
+  const fallbackAlt = generatedThumbnail.alt;
+  try {
+    const result = await postJson("/api/describe-image", {
+      image_id: "generated-thumbnail",
+      caption: payload.article.title || payload.topic,
+      prompt: thumbnail.prompt || payload.topic,
+      image_url: thumbnail.image_url,
+    });
+    if (result.ok && result.alt_text) {
+      generatedThumbnail.alt = result.alt_text;
+      refreshReaderNodes();
+      thumbnailReceipt.textContent =
+        `${thumbnail.generation_model} | seed ${thumbnail.seed} | ${thumbnail.runtime} | described by ${result.runtime}`;
+    }
+  } catch {
+    generatedThumbnail.alt = fallbackAlt;
+  }
+}
+
 async function loadManifest() {
   try {
     const manifest = await postJson("/api/article-manifest");
@@ -464,6 +485,7 @@ form.addEventListener("submit", async (event) => {
   try {
     const payload = await postJson("/api/generate-article", { topic });
     renderArticle(payload);
+    describeGeneratedThumbnail(payload);
   } catch (error) {
     generatorStatus.textContent = `Generation failed: ${error.message}`;
   } finally {