Add CPU Spaces deployment with Modal runtimes

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

.env.example

@@ -5,11 +5,15 @@
 # App server
 GRADIO_SERVER_NAME=0.0.0.0
 GRADIO_SERVER_PORT=7860
+GRADIO_SHARE=false
 PUBLIC_BASE_URL=http://localhost:7860
 
-# Reader brain: llama.cpp OpenAI-compatible server
+# Reader brain: llama.cpp OpenAI-compatible server.
+# Use http://localhost:8080/v1 for local llama.cpp, or a Modal URL ending in /v1.
 LLAMA_CPP_BASE_URL=http://localhost:8080/v1
 LLAMA_CPP_MODEL=narrator-brain
+LLAMA_CPP_TOKEN=
+LLAMA_CPP_TIMEOUT_SECONDS=90
 
 # Speech: Kokoro is loaded locally when the kokoro and soundfile packages are installed.
 # No API key is required.
@@ -23,4 +27,5 @@ MINICPM_VISION_TIMEOUT_SECONDS=45
 # Image generation: Modal-hosted FLUX.2 klein worker
 KLEIN_MODAL_ENDPOINT=
 KLEIN_MODAL_TOKEN=
+KLEIN_MODAL_HEALTH_TIMEOUT_SECONDS=30
 KLEIN_MODAL_TIMEOUT_SECONDS=120

DEPLOY_SPACES.md

@@ -0,0 +1,300 @@
+# Deploy Tiny Narrator to Hugging Face Spaces
+
+This guide deploys Tiny Narrator on Hugging Face Spaces using the **Docker SDK on free CPU**. The Space serves the custom article UI, FastAPI routes, Kokoro/browser speech path, and fallback assets. GPU inference runs outside the Space through Modal or other OpenAI-compatible endpoints.
+
+> **Why Docker SDK?** Tiny Narrator uses `gradio.Server` with custom FastAPI routes and static files. The Docker SDK preserves that app shape without rewriting the UI into `gr.Blocks`.
+>
+> **Why free CPU?** Paid HF GPU is not required when `llama.cpp` and image generation are hosted externally. The Space can stay on CPU Basic while still calling live model endpoints.
+
+---
+
+## Prerequisites
+
+- A Hugging Face account
+- Git and Git LFS installed locally
+- Python 3.11+ installed locally for testing
+- Modal CLI installed if you want live reader-brain or Klein image generation
+
+---
+
+## Step 1 - Create a New Space
+
+1. Go to [https://huggingface.co/new-space](https://huggingface.co/new-space).
+2. Fill in the form:
+   - **Space name**: `tiny-narrator`
+   - **SDK**: **Docker**
+   - **Hardware**: **CPU Basic**
+   - **Visibility**: Public or Private
+3. Click **Create Space**.
+
+Your Space README metadata should include:
+
+```yaml
+---
+title: Tiny Narrator
+emoji: book
+colorFrom: blue
+colorTo: teal
+sdk: docker
+app_port: 7860
+---
+```
+
+The `app_port: 7860` line is important because Tiny Narrator binds to port 7860 by default.
+
+---
+
+## Step 2 - Copy Project Files
+
+Clone the Space repository and copy the Tiny Narrator project files into it:
+
+```bash
+git clone https://huggingface.co/spaces/<YOUR_USERNAME>/tiny-narrator
+cd tiny-narrator
+```
+
+Include these files and directories:
+
+```text
+app.py
+requirements.txt
+Dockerfile
+start.sh
+README.md
+SUBMISSION.md
+FIELD_NOTES.md
+LICENSE
+static/
+modal_workers/
+scripts/
+```
+
+Do **not** copy `.env`; configure secrets in the Space Settings UI.
+
+---
+
+## Step 3 - Deploy Modal Reader Brain
+
+The reader-brain role uses `nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF:Q4_K_M` through `llama.cpp`. Deploy it to Modal:
+
+```bash
+pip install modal
+modal setup
+modal secret create tiny-narrator-reader-brain-token LLAMA_CPP_TOKEN=your-random-token
+modal deploy modal_workers/reader_brain.py
+```
+
+After deployment, Modal prints a URL similar to:
+
+```text
+https://your-workspace--tiny-narrator-reader-brain.modal.run
+```
+
+Set the Space variable:
+
+```text
+LLAMA_CPP_BASE_URL=https://your-workspace--tiny-narrator-reader-brain.modal.run/v1
+LLAMA_CPP_MODEL=narrator-brain
+LLAMA_CPP_TOKEN=your-random-token
+LLAMA_CPP_TIMEOUT_SECONDS=90
+```
+
+The worker starts `llama-server` with:
+
+```bash
+llama-server \
+  -hf nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF:Q4_K_M \
+  --alias narrator-brain \
+  --host 0.0.0.0 \
+  --port 8080 \
+  --ctx-size 0 \
+  --reasoning off \
+  --n-gpu-layers 999 \
+  --api-key your-random-token
+```
+
+Modal scales the worker down when idle. The first request after scale-to-zero can be slow while the container and model start.
+
+---
+
+## Step 4 - Optional Live Image Generation
+
+Tiny Narrator can use the Modal Klein worker for `black-forest-labs/FLUX.2-klein-4B` thumbnails:
+
+```bash
+modal secret create tiny-narrator-klein-token KLEIN_MODAL_TOKEN=your-random-token
+modal deploy modal_workers/klein_image.py
+```
+
+Set these Space values:
+
+```text
+KLEIN_MODAL_ENDPOINT=https://your-workspace--tiny-narrator-klein.modal.run
+KLEIN_MODAL_TOKEN=your-random-token
+KLEIN_MODAL_HEALTH_TIMEOUT_SECONDS=30
+KLEIN_MODAL_TIMEOUT_SECONDS=120
+```
+
+If the Klein worker is not configured, the app falls back to bundled SVG assets.
+
+---
+
+## Step 5 - Optional MiniCPM-V Image Descriptions
+
+If you have an OpenAI-compatible MiniCPM-V-4.6 endpoint, set:
+
+```text
+MINICPM_VISION_BASE_URL=https://your-vision-endpoint.example.com/v1
+MINICPM_VISION_API_KEY=<secret>
+MINICPM_VISION_MODEL=openbmb/MiniCPM-V-4.6
+MINICPM_VISION_TIMEOUT_SECONDS=45
+```
+
+If this endpoint is not configured, Tiny Narrator uses deterministic cached alt text.
+
+---
+
+## Step 6 - Configure Space Variables
+
+In your Space, open **Settings -> Variables and secrets**.
+
+Add these variables:
+
+| Variable | Example | Notes |
+| --- | --- | --- |
+| `PUBLIC_BASE_URL` | `https://your-username-tiny-narrator.hf.space` | Used in generated judge/demo links |
+| `GRADIO_SHARE` | `false` | Keep false on Spaces |
+| `LLAMA_CPP_BASE_URL` | `https://...modal.run/v1` | Modal reader-brain endpoint |
+| `LLAMA_CPP_MODEL` | `narrator-brain` | Alias served by llama.cpp |
+| `LLAMA_CPP_TIMEOUT_SECONDS` | `90` | Reader/article generation timeout |
+| `KLEIN_MODAL_ENDPOINT` | `https://...modal.run` | Optional image generation endpoint |
+| `KLEIN_MODAL_HEALTH_TIMEOUT_SECONDS` | `30` | Optional Klein health timeout |
+| `KLEIN_MODAL_TIMEOUT_SECONDS` | `120` | Optional Klein generation timeout |
+| `MINICPM_VISION_BASE_URL` | `https://.../v1` | Optional image descriptor endpoint |
+| `MINICPM_VISION_MODEL` | `openbmb/MiniCPM-V-4.6` | Optional descriptor model id |
+| `MINICPM_VISION_TIMEOUT_SECONDS` | `45` | Optional descriptor timeout |
+
+Add these as **Secrets**:
+
+| Secret | Notes |
+| --- | --- |
+| `LLAMA_CPP_TOKEN` | Recommended for Modal reader-brain auth |
+| `KLEIN_MODAL_TOKEN` | Only needed if Modal Klein is enabled |
+| `MINICPM_VISION_API_KEY` | Only needed if MiniCPM-V is enabled |
+
+---
+
+## Step 7 - Commit and Push
+
+```bash
+git add .
+git commit -m "Deploy Tiny Narrator to HF Spaces CPU"
+git push origin main
+```
+
+HF Spaces will:
+
+1. Detect the Dockerfile.
+2. Build a small CPU image.
+3. Run `start.sh`.
+4. Launch `python app.py` on port 7860.
+5. Expose the app at `https://<YOUR_USERNAME>-tiny-narrator.hf.space`.
+
+---
+
+## Step 8 - Verify the Deployment
+
+Open the Space URL in a browser, then check:
+
+```bash
+curl https://<YOUR_USERNAME>-tiny-narrator.hf.space/api/health
+curl https://<YOUR_USERNAME>-tiny-narrator.hf.space/api/model-budget
+curl https://<YOUR_USERNAME>-tiny-narrator.hf.space/api/runtime-status
+curl https://<YOUR_USERNAME>-tiny-narrator.hf.space/api/submission-readiness
+```
+
+`/api/runtime-status` should show:
+
+- `reader_brain`: `online` when Modal llama.cpp is reachable, `fallback-ready` otherwise
+- `speech`: Kokoro or fallback speech path
+- `vision`: MiniCPM online or fallback-ready
+- `image_generation`: Modal Klein online or fallback-ready
+
+---
+
+## Troubleshooting
+
+### Space starts but reader brain is fallback-ready
+
+- Confirm `LLAMA_CPP_BASE_URL` ends in `/v1`.
+- Confirm the Space `LLAMA_CPP_TOKEN` secret matches the Modal `tiny-narrator-reader-brain-token` secret.
+- Open the Modal logs for `tiny-narrator-reader-brain`.
+- Check that the Modal URL is reachable at `/v1/models`.
+- The first request after scale-to-zero may need extra time while Modal starts the container and loads the GGUF.
+
+### Space stuck on "Starting"
+
+- Check the Space **Container** logs.
+- Make sure `requirements.txt` installed successfully.
+- Make sure the app binds to `0.0.0.0:7860`; the defaults already do this.
+
+### Kokoro TTS not producing audio
+
+- `libsndfile1` is installed in the Docker image.
+- If Kokoro fails to load, the app falls back to browser speech synthesis and transcript output.
+
+### Modal reader-brain cold starts are slow
+
+- Keep `scaledown_window` higher in `modal_workers/reader_brain.py` if you want the container to stay warm longer.
+- Use a faster GPU by setting `READER_BRAIN_MODAL_GPU` before deploying.
+- Keep `min_containers=0` for cheapest operation; use a warm container only if you accept continuous cost.
+
+### External services unreachable
+
+- HF Spaces has outbound internet access, but private endpoints are not reachable.
+- Use public HTTPS endpoints for Modal, MiniCPM, and any tunnels.
+
+---
+
+## Architecture Overview
+
+```text
+Hugging Face Space (Docker CPU)
+  app.py
+  static HTML/CSS/JS
+  outputs WAV files
+  deterministic fallbacks
+        |
+        +--> Modal reader-brain worker
+        |     llama.cpp /v1/chat/completions
+        |
+        +--> Modal Klein image worker (optional)
+        |
+        +--> MiniCPM-V-4.6 OpenAI-compatible endpoint (optional)
+```
+
+---
+
+## Quick Reference
+
+| Item | Value |
+| --- | --- |
+| Space SDK | Docker |
+| Space hardware | CPU Basic |
+| App port | 7860 |
+| Space base image | `python:3.12-slim` |
+| Reader brain runtime | Modal-hosted llama.cpp |
+| Reader brain model | `nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF:Q4_K_M` |
+| Reader brain base URL | `https://<modal-url>/v1` |
+| Image generation | Modal Klein worker or SVG fallback |
+| Image descriptions | MiniCPM-V endpoint or cached fallback |
+
+---
+
+## Further Reading
+
+- [HF Spaces Docker SDK docs](https://huggingface.co/docs/hub/spaces-sdks-docker)
+- [HF Spaces Secrets & Variables](https://huggingface.co/docs/hub/spaces-overview#managing-secrets)
+- [Modal Web Functions](https://modal.com/docs/guide/webhooks)
+- [Modal GPU acceleration](https://modal.com/docs/guide/gpu)
+- [llama.cpp repository](https://github.com/ggml-org/llama.cpp)

Dockerfile

@@ -0,0 +1,44 @@
+# Tiny Narrator - Hugging Face Spaces Docker deployment (free CPU)
+# Serves the custom Gradio/FastAPI app. GPU model runtimes are external.
+
+FROM python:3.12-slim
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+        libsndfile1 \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN useradd -m -u 1000 user
+
+WORKDIR /home/user/app
+
+COPY --chown=user requirements.txt requirements.txt
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY --chown=user app.py app.py
+COPY --chown=user start.sh start.sh
+COPY --chown=user static/ static/
+COPY --chown=user modal_workers/ modal_workers/
+COPY --chown=user scripts/ scripts/
+COPY --chown=user README.md README.md
+COPY --chown=user SUBMISSION.md SUBMISSION.md
+COPY --chown=user FIELD_NOTES.md FIELD_NOTES.md
+COPY --chown=user LICENSE LICENSE
+
+RUN mkdir -p /home/user/app/outputs && \
+    chown user:user /home/user/app/outputs && \
+    chmod +x /home/user/app/start.sh
+
+USER user
+
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    GRADIO_SERVER_NAME=0.0.0.0 \
+    GRADIO_SERVER_PORT=7860 \
+    GRADIO_SHARE=false \
+    LLAMA_CPP_BASE_URL= \
+    LLAMA_CPP_MODEL=narrator-brain
+
+EXPOSE 7860
+
+CMD ["/home/user/app/start.sh"]

README.md

@@ -46,10 +46,10 @@ Copy the example environment file to `.env` and fill in the values. The app load
 Copy-Item .env.example .env
 ```
 
-Start the llama.cpp reader-brain server:
+Start the llama.cpp reader-brain server locally:
 
 ```powershell
-llama-server -hf nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF:Q4_K_M --alias narrator-brain --port 8080 --host 0.0.0.0
+llama-server -hf nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF:Q4_K_M --alias narrator-brain --port 8080 --host 0.0.0.0 --ctx-size 0 --reasoning off --n-gpu-layers 999
 ```
 
 Start the app:
@@ -60,15 +60,35 @@ python app.py
 
 Open the local URL printed by Gradio. The Reader route calls `/api/reader-brain`, `/api/image-descriptions`, `/api/describe-image`, `/api/speak`, and `/api/model-budget`. The Generate route calls `/api/generate-article`, which drafts an article with the reader-brain model path and attaches a Klein thumbnail receipt.
 
+## Modal Reader Brain
+
+For a free CPU Hugging Face Space, host the llama.cpp reader-brain server on Modal and point the app at its OpenAI-compatible `/v1` endpoint:
+
+```powershell
+modal secret create tiny-narrator-reader-brain-token LLAMA_CPP_TOKEN=your-random-token
+modal deploy modal_workers/reader_brain.py
+```
+
+Set `LLAMA_CPP_BASE_URL` to the deployed Modal URL with `/v1` appended, for example:
+
+```env
+LLAMA_CPP_BASE_URL=https://your-workspace--tiny-narrator-reader-brain.modal.run/v1
+LLAMA_CPP_MODEL=narrator-brain
+LLAMA_CPP_TOKEN=your-random-token
+```
+
+The Modal worker starts Nemotron with `--ctx-size 0`, `--reasoning off`, full GPU offload, and `--api-key` when `LLAMA_CPP_TOKEN` is configured. It scales down when idle, so the first request after a cold start can be slower.
+
 ## Modal Klein Image Generation
 
 The image generation path uses a Modal-hosted `black-forest-labs/FLUX.2-klein-4B` worker. Deploy the worker:
 
 ```powershell
+modal secret create tiny-narrator-klein-token KLEIN_MODAL_TOKEN=your-random-token
 modal deploy modal_workers/klein_image.py
 ```
 
-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.
+Set `KLEIN_MODAL_ENDPOINT` to the deployed worker URL. Set the same `KLEIN_MODAL_TOKEN` value in your local `.env`. The Modal worker uses the fixed `tiny-narrator-klein-token` secret name so Modal's local and remote dependency graphs stay identical.
 
 `/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.
 
@@ -82,13 +102,17 @@ Useful environment variables:
 
 | Variable | Default | Purpose |
 | --- | --- | --- |
-| `LLAMA_CPP_BASE_URL` | `http://localhost:8080/v1` | OpenAI-compatible llama.cpp server URL |
+| `LLAMA_CPP_BASE_URL` | `http://localhost:8080/v1` | OpenAI-compatible llama.cpp server URL, local or Modal |
 | `LLAMA_CPP_MODEL` | `narrator-brain` | Alias passed to llama.cpp |
+| `LLAMA_CPP_TOKEN` | *(empty)* | Optional bearer token for protected llama.cpp endpoints. When set, the app sends `Authorization: Bearer <token>`. |
 | `GRADIO_SERVER_NAME` | `0.0.0.0` | Bind address for local or Space runtime |
 | `GRADIO_SERVER_PORT` / `PORT` | `7860` | App port |
+| `GRADIO_SHARE` | `false` | Set to `true` if Gradio cannot verify localhost and needs a share URL |
 | `PUBLIC_BASE_URL` | `http://localhost:7860` | Base URL used in generated judge API commands |
+| `LLAMA_CPP_TIMEOUT_SECONDS` | `90` | Timeout for local llama.cpp reader-brain and article generation calls |
 | `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_HEALTH_TIMEOUT_SECONDS` | `30` | Timeout for Modal Klein `/health`; increase for cold-starting Modal endpoints. |
 | `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. |

app.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import importlib.util
 import json
 import os
+import sys
 import time
 import urllib.error
 import urllib.request
@@ -34,13 +35,41 @@ def _int_env(name: str, default: int) -> int:
         return default
 
 
+def _bool_env(name: str, default: bool = False) -> bool:
+    value = os.getenv(name)
+    if value is None:
+        return default
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _runtime_log(message: str) -> None:
+    print(f"[tiny-narrator] {message}", file=sys.stderr, flush=True)
+
+
+def _http_exception_detail(exc: BaseException) -> str:
+    if isinstance(exc, urllib.error.HTTPError):
+        try:
+            body = exc.read().decode("utf-8", errors="replace")
+        except Exception:
+            body = ""
+        body = _compact_text(body, 400) if body else ""
+        return f"HTTPError status={exc.code} reason={exc.reason} body={body}"
+    if isinstance(exc, urllib.error.URLError):
+        return f"URLError reason={exc.reason}"
+    return f"{exc.__class__.__name__}: {exc}"
+
+
 LLAMA_CPP_BASE_URL = os.getenv("LLAMA_CPP_BASE_URL", "http://localhost:8080/v1")
 LLAMA_CPP_MODEL = os.getenv("LLAMA_CPP_MODEL", "narrator-brain")
+LLAMA_CPP_TOKEN = os.getenv("LLAMA_CPP_TOKEN", "")
+LLAMA_CPP_TIMEOUT_SECONDS = _int_env("LLAMA_CPP_TIMEOUT_SECONDS", 90)
 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")))
+GRADIO_SHARE = _bool_env("GRADIO_SHARE")
 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_HEALTH_TIMEOUT_SECONDS = _int_env("KLEIN_MODAL_HEALTH_TIMEOUT_SECONDS", 30)
 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", "")
@@ -176,6 +205,7 @@ def runtime_setup_core() -> dict[str, Any]:
             "env": {
                 "GRADIO_SERVER_NAME": GRADIO_SERVER_NAME,
                 "GRADIO_SERVER_PORT": str(GRADIO_SERVER_PORT),
+                "GRADIO_SHARE": str(GRADIO_SHARE).lower(),
                 "PUBLIC_BASE_URL": PUBLIC_BASE_URL,
             },
         },
@@ -187,9 +217,16 @@ def runtime_setup_core() -> dict[str, Any]:
                 "runtime": "llama.cpp",
                 "command": (
                     "llama-server -hf nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF:Q4_K_M "
-                    "--alias narrator-brain --port 8080 --host 0.0.0.0"
+                    "--alias narrator-brain --port 8080 --host 0.0.0.0 "
+                    "--ctx-size 0 --reasoning off --n-gpu-layers 999"
                 ),
-                "env": {"LLAMA_CPP_BASE_URL": LLAMA_CPP_BASE_URL, "LLAMA_CPP_MODEL": LLAMA_CPP_MODEL},
+                "modal_command": "modal deploy modal_workers/reader_brain.py",
+                "env": {
+                    "LLAMA_CPP_BASE_URL": LLAMA_CPP_BASE_URL,
+                    "LLAMA_CPP_MODEL": LLAMA_CPP_MODEL,
+                    "LLAMA_CPP_TOKEN": "(configured)" if LLAMA_CPP_TOKEN else "(not set)",
+                    "LLAMA_CPP_TIMEOUT_SECONDS": str(LLAMA_CPP_TIMEOUT_SECONDS),
+                },
                 "fallback": "rule-based local narration",
             },
             {
@@ -224,6 +261,7 @@ def runtime_setup_core() -> dict[str, Any]:
                 "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_HEALTH_TIMEOUT_SECONDS": str(KLEIN_MODAL_HEALTH_TIMEOUT_SECONDS),
                     "KLEIN_MODAL_TIMEOUT_SECONDS": str(KLEIN_MODAL_TIMEOUT_SECONDS),
                 },
                 "fallback": "bundled generated article assets",
@@ -589,68 +627,113 @@ def _validate_modal_klein_health(payload: dict[str, Any]) -> None:
         raise ValueError("health check returned unexpected runtime")
 
 
+def _modal_klein_base_url() -> str:
+    normalized = KLEIN_MODAL_ENDPOINT.rstrip("/")
+    for suffix in ("/generate", "/health"):
+        if normalized.endswith(suffix):
+            return normalized[: -len(suffix)]
+    return normalized
+
+
+def _llama_cpp_headers(extra: dict[str, str] | None = None) -> dict[str, str]:
+    headers = dict(extra or {})
+    if LLAMA_CPP_TOKEN:
+        headers["Authorization"] = f"Bearer {LLAMA_CPP_TOKEN}"
+    return headers
+
+
 def _runtime_status_core() -> dict[str, Any]:
     start = time.perf_counter()
     llama_start = time.perf_counter()
     llama_status: dict[str, Any]
-    try:
-        request = urllib.request.Request(f"{LLAMA_CPP_BASE_URL}/models", method="GET")
-        with urllib.request.urlopen(request, timeout=1.5) as response:
-            payload = json.loads(response.read().decode("utf-8"))
-        model_ids = [item.get("id", "") for item in payload.get("data", []) if isinstance(item, dict)]
-        llama_status = {
-            "available": True,
-            "status": "online",
-            "base_url": LLAMA_CPP_BASE_URL,
-            "model": LLAMA_CPP_MODEL,
-            "models": model_ids,
-            "elapsed_ms": _elapsed_ms(llama_start),
-        }
-    except (OSError, urllib.error.URLError, TimeoutError, json.JSONDecodeError) as exc:
+    if not LLAMA_CPP_BASE_URL:
         llama_status = {
             "available": False,
             "status": "fallback-ready",
             "base_url": LLAMA_CPP_BASE_URL,
             "model": LLAMA_CPP_MODEL,
             "fallback": "rule-based local narration",
-            "warning": exc.__class__.__name__,
+            "warning": "LLAMA_CPP_BASE_URL is not configured",
             "elapsed_ms": _elapsed_ms(llama_start),
         }
+    else:
+        try:
+            request = urllib.request.Request(
+                f"{LLAMA_CPP_BASE_URL}/models",
+                headers=_llama_cpp_headers(),
+                method="GET",
+            )
+            with urllib.request.urlopen(request, timeout=1.5) as response:
+                payload = json.loads(response.read().decode("utf-8"))
+            model_ids = [item.get("id", "") for item in payload.get("data", []) if isinstance(item, dict)]
+            llama_status = {
+                "available": True,
+                "status": "online",
+                "base_url": LLAMA_CPP_BASE_URL,
+                "model": LLAMA_CPP_MODEL,
+                "models": model_ids,
+                "elapsed_ms": _elapsed_ms(llama_start),
+            }
+        except (OSError, urllib.error.URLError, TimeoutError, ValueError, json.JSONDecodeError) as exc:
+            llama_status = {
+                "available": False,
+                "status": "fallback-ready",
+                "base_url": LLAMA_CPP_BASE_URL,
+                "model": LLAMA_CPP_MODEL,
+                "fallback": "rule-based local narration",
+                "warning": exc.__class__.__name__,
+                "elapsed_ms": _elapsed_ms(llama_start),
+            }
 
     kokoro_available = importlib.util.find_spec("kokoro") is not None
     soundfile_available = importlib.util.find_spec("soundfile") is not None
 
     klein_status: dict[str, Any]
     if KLEIN_MODAL_ENDPOINT:
+        endpoint = _modal_klein_base_url()
+        health_url = f"{endpoint}/health"
         try:
             health_headers: dict[str, str] = {}
             if KLEIN_MODAL_TOKEN:
                 health_headers["Authorization"] = f"Bearer {KLEIN_MODAL_TOKEN}"
+            _runtime_log(
+                "Modal Klein health check "
+                f"url={health_url} token={'configured' if KLEIN_MODAL_TOKEN else 'not-set'} "
+                f"timeout={KLEIN_MODAL_HEALTH_TIMEOUT_SECONDS}s"
+            )
             request = urllib.request.Request(
-                f"{KLEIN_MODAL_ENDPOINT}/health", method="GET",
+                health_url, method="GET",
                 headers=health_headers,
             )
-            with urllib.request.urlopen(request, timeout=5) as response:
+            with urllib.request.urlopen(request, timeout=KLEIN_MODAL_HEALTH_TIMEOUT_SECONDS) as response:
                 payload = json.loads(response.read().decode("utf-8"))
+            _runtime_log(
+                "Modal Klein health response "
+                f"model={payload.get('model')} runtime={payload.get('runtime')} ok={payload.get('ok')}"
+            )
             _validate_modal_klein_health(payload)
             klein_status = {
                 "available": True,
                 "status": "online",
                 "model": MODEL_MANIFEST["image_generation"]["id"],
-                "endpoint": KLEIN_MODAL_ENDPOINT,
+                "endpoint": endpoint,
                 "elapsed_ms": _elapsed_ms(start),
             }
         except (OSError, urllib.error.URLError, TimeoutError, ValueError, json.JSONDecodeError) as exc:
+            detail = _http_exception_detail(exc)
+            _runtime_log(f"Modal Klein health failed url={health_url} error={detail}")
             klein_status = {
                 "available": False,
                 "status": "fallback-ready",
                 "model": MODEL_MANIFEST["image_generation"]["id"],
-                "endpoint": KLEIN_MODAL_ENDPOINT,
+                "endpoint": endpoint,
+                "health_url": health_url,
                 "fallback": "bundled generated article assets",
-                "warning": exc.__class__.__name__,
+                "warning": detail,
                 "elapsed_ms": _elapsed_ms(start),
             }
     else:
+        _runtime_log("Modal Klein endpoint is not configured; using image fallback")
         klein_status = {
             "available": False,
             "status": "fallback-ready",
@@ -702,21 +785,38 @@ def _fallback_article(topic: str) -> dict[str, Any]:
                 "heading": f"Why {clean_topic} matters",
                 "body": (
                     f"{clean_topic.capitalize()} is easier to understand when the page explains the main idea first, "
-                    "then moves through examples in a predictable order."
+                    "then moves through examples in a predictable order. A longer article gives the reader enough "
+                    "context to pause, repeat, and compare sections without feeling rushed."
                 ),
             },
             {
                 "heading": "How a tiny narrator helps",
                 "body": (
                     "A small reader model can turn each heading, paragraph, and image caption into concise narration "
-                    "without turning the article into a chatbot."
+                    "without turning the article into a chatbot. It keeps the experience close to the article, so "
+                    "the user stays oriented while moving through the page."
+                ),
+            },
+            {
+                "heading": "What image descriptions add",
+                "body": (
+                    "Images often carry examples, diagrams, or emotional context. A visual descriptor gives those "
+                    "details a spoken form, helping readers understand why an illustration belongs with the surrounding text."
+                ),
+            },
+            {
+                "heading": "Designing for repeated listening",
+                "body": (
+                    "Reader controls should make it easy to move backward, skip to the next heading, replay a sentence, "
+                    "or stop speech completely. Those small controls matter when someone is studying, teaching, or checking details."
                 ),
             },
             {
                 "heading": "What to try next",
                 "body": (
                     "Use the reader controls to move by heading or image, then compare the transcript with the article "
-                    "to check whether the generated structure is easy to follow."
+                    "to check whether the generated structure is easy to follow. If a section sounds confusing, rewrite it "
+                    "with simpler language and a clearer heading."
                 ),
             },
         ],
@@ -725,16 +825,84 @@ def _fallback_article(topic: str) -> dict[str, Any]:
 
 def _article_generation_prompt(topic: str) -> str:
     return (
-        "Write a short accessible article for Tiny Narrator.\n"
+        "Write a complete accessible article for Tiny Narrator.\n"
         f"Topic: {topic}\n\n"
         "Return strict JSON with keys title, dek, and sections. "
-        "sections must contain exactly three objects with heading and body. "
-        "Keep every body under 45 words. Do not include markdown."
+        "sections must contain exactly five objects with heading and body. "
+        "Each body should be 45 to 70 words, with concrete examples and practical detail. "
+        "Use clear plain language suitable for screen-reader narration. Do not include markdown."
+    )
+
+
+def _fallback_narration(node_type: str, text: str, mode: str) -> str:
+    prefix = {
+        "heading": "Heading. ",
+        "image": "Image. ",
+        "button": "Control. ",
+        "quote": "Quote. ",
+    }.get(node_type, "")
+    if mode == "summarize":
+        prefix = "Summary. "
+    fallback_text = _compact_text(text) or "No readable text is available for this item."
+    return f"{prefix}{fallback_text}".strip()
+
+
+def _chat_message_text(payload: dict[str, Any]) -> str:
+    choices = payload.get("choices", [])
+    if not choices or not isinstance(choices[0], dict):
+        return ""
+    choice = choices[0]
+    message = choice.get("message")
+    if isinstance(message, dict):
+        for key in ("content", "reasoning_content", "reasoning", "text"):
+            value = message.get(key)
+            if isinstance(value, str) and value.strip():
+                return value.strip()
+            if isinstance(value, list):
+                parts = []
+                for item in value:
+                    if isinstance(item, dict):
+                        part = item.get("text") or item.get("content")
+                        if isinstance(part, str):
+                            parts.append(part)
+                    elif isinstance(item, str):
+                        parts.append(item)
+                combined = " ".join(parts).strip()
+                if combined:
+                    return combined
+    text = choice.get("text")
+    if isinstance(text, str) and text.strip():
+        return text.strip()
+    return ""
+
+
+def _chat_response_debug(payload: dict[str, Any]) -> str:
+    choices = payload.get("choices", [])
+    if not choices or not isinstance(choices[0], dict):
+        return f"top_keys={list(payload)[:8]} choices=missing"
+    choice = choices[0]
+    message = choice.get("message")
+    message_keys = list(message)[:8] if isinstance(message, dict) else []
+    return (
+        f"top_keys={list(payload)[:8]} "
+        f"choice_keys={list(choice)[:8]} "
+        f"message_keys={message_keys} "
+        f"finish_reason={choice.get('finish_reason')}"
     )
 
 
 def reader_brain_core(node_type: str, text: str, position: str | None, mode: str) -> dict[str, Any]:
     start = time.perf_counter()
+    if not LLAMA_CPP_BASE_URL:
+        return {
+            "ok": True,
+            "runtime": "fallback",
+            "model": "rule-based local fallback",
+            "warning": "llama.cpp unavailable: LLAMA_CPP_BASE_URL is not configured",
+            "narration": _fallback_narration(node_type, text, mode),
+            "elapsed_ms": _elapsed_ms(start),
+        }
+
     if mode == "summarize":
         prompt = (
             "Summarize this article section for screen-reader navigation.\n"
@@ -742,7 +910,8 @@ def reader_brain_core(node_type: str, text: str, position: str | None, mode: str
             f"Position: {position or 'unknown'}\n"
             f"Content: {text}\n\n"
             "Rules: start with 'Summary.', use one or two short sentences, explain what the "
-            "reader can learn in this section, and never mention implementation details."
+            "reader can learn in this section, and never mention implementation details. "
+            "Return only the final spoken narration. Do not explain your reasoning."
         )
     else:
         prompt = (
@@ -752,7 +921,8 @@ def reader_brain_core(node_type: str, text: str, position: str | None, mode: str
             f"Position: {position or 'unknown'}\n"
             f"Content: {text}\n\n"
             "Rules: announce the node type only when it helps orientation, keep prose short, "
-            "and never mention implementation details."
+            "and never mention implementation details. Return only the final spoken narration. "
+            "Do not explain your reasoning."
         )
 
     try:
@@ -764,24 +934,42 @@ def reader_brain_core(node_type: str, text: str, position: str | None, mode: str
                         "role": "system",
                         "content": (
                             "You are Tiny Narrator's accessibility layer. "
-                            "Produce clear screen-reader narration for article content."
+                            "Reasoning mode: off. Do not generate a reasoning trace. "
+                            "Do not think step by step. "
+                            "Produce clear screen-reader narration for article content. "
+                            "Return only the exact text to speak. Do not include analysis, alternatives, "
+                            "markdown, labels, or explanations."
                         ),
                     },
                     {"role": "user", "content": prompt},
                 ],
                 "temperature": 0.2,
-                "max_tokens": 180,
+                "top_p": 0.9,
+                "stream": False,
+                "max_tokens": 80,
             }
         ).encode("utf-8")
         request = urllib.request.Request(
             f"{LLAMA_CPP_BASE_URL}/chat/completions",
             data=body,
-            headers={"Content-Type": "application/json"},
+            headers=_llama_cpp_headers({"Content-Type": "application/json"}),
             method="POST",
         )
-        with urllib.request.urlopen(request, timeout=45) as response:
+        with urllib.request.urlopen(request, timeout=LLAMA_CPP_TIMEOUT_SECONDS) as response:
             payload = json.loads(response.read().decode("utf-8"))
-        narration = payload["choices"][0]["message"]["content"].strip()
+        narration = _compact_text(_chat_message_text(payload), 220)
+        if not narration:
+            fallback = _fallback_narration(node_type, text, mode)
+            detail = _chat_response_debug(payload)
+            _runtime_log(f"llama.cpp returned empty narration; response_shape={detail}")
+            return {
+                "ok": True,
+                "runtime": "fallback",
+                "model": "rule-based local fallback",
+                "warning": f"llama.cpp returned empty narration ({detail})",
+                "narration": fallback,
+                "elapsed_ms": _elapsed_ms(start),
+            }
         return {
             "ok": True,
             "runtime": "llama.cpp",
@@ -789,21 +977,13 @@ def reader_brain_core(node_type: str, text: str, position: str | None, mode: str
             "narration": narration,
             "elapsed_ms": _elapsed_ms(start),
         }
-    except (OSError, urllib.error.URLError, KeyError, json.JSONDecodeError) as exc:
-        prefix = {
-            "heading": "Heading. ",
-            "image": "Image. ",
-            "button": "Control. ",
-            "quote": "Quote. ",
-        }.get(node_type, "")
-        if mode == "summarize":
-            prefix = "Summary. "
+    except (OSError, urllib.error.URLError, TimeoutError, ValueError, KeyError, json.JSONDecodeError) as exc:
         return {
             "ok": True,
             "runtime": "fallback",
             "model": "rule-based local fallback",
             "warning": f"llama.cpp unavailable: {exc.__class__.__name__}",
-            "narration": f"{prefix}{_compact_text(text)}".strip(),
+            "narration": _fallback_narration(node_type, text, mode),
             "elapsed_ms": _elapsed_ms(start),
         }
 
@@ -910,6 +1090,32 @@ def _call_minicpm_vision(image_url: str, caption: str | None, prompt: str | None
     }
 
 
+def _check_minicpm_chat_ready() -> dict[str, Any]:
+    body = json.dumps(
+        {
+            "model": MINICPM_VISION_MODEL,
+            "messages": [{"role": "user", "content": "Reply with ready."}],
+            "temperature": 0,
+            "max_tokens": 8,
+        }
+    ).encode("utf-8")
+    request = urllib.request.Request(
+        _openai_compatible_url(MINICPM_VISION_BASE_URL, "chat/completions"),
+        data=body,
+        headers={
+            "Authorization": f"Bearer {MINICPM_VISION_API_KEY}",
+            "Content-Type": "application/json",
+        },
+        method="POST",
+    )
+    with urllib.request.urlopen(request, timeout=min(MINICPM_VISION_TIMEOUT_SECONDS, 10)) as response:
+        payload = json.loads(response.read().decode("utf-8"))
+    content = payload["choices"][0]["message"]["content"]
+    if not isinstance(content, str) or not content.strip():
+        raise ValueError("MiniCPM readiness response did not include text content")
+    return payload
+
+
 def _vision_runtime_status() -> dict[str, Any]:
     if not MINICPM_VISION_BASE_URL or not MINICPM_VISION_API_KEY:
         return {
@@ -920,6 +1126,8 @@ def _vision_runtime_status() -> dict[str, Any]:
             "fallback": "cached deterministic alt text",
         }
     start = time.perf_counter()
+    model_ids: list[str] = []
+    models_warning: str | None = None
     try:
         request = urllib.request.Request(
             _openai_compatible_url(MINICPM_VISION_BASE_URL, "models"),
@@ -934,7 +1142,8 @@ def _vision_runtime_status() -> dict[str, Any]:
             if isinstance(item, dict)
         ]
         if model_ids and MINICPM_VISION_MODEL not in model_ids:
-            raise ValueError("MiniCPM vision model was not listed by /models")
+            models_warning = "MiniCPM vision model was not listed by /models"
+            _check_minicpm_chat_ready()
         return {
             "available": True,
             "status": "online",
@@ -942,9 +1151,25 @@ def _vision_runtime_status() -> dict[str, Any]:
             "configured": True,
             "base_url": MINICPM_VISION_BASE_URL,
             "models": model_ids,
+            "warning": models_warning,
             "elapsed_ms": _elapsed_ms(start),
         }
     except (OSError, urllib.error.URLError, TimeoutError, ValueError, json.JSONDecodeError) as exc:
+        models_warning = exc.__class__.__name__
+
+    try:
+        _check_minicpm_chat_ready()
+        return {
+            "available": True,
+            "status": "online",
+            "model": MINICPM_VISION_MODEL,
+            "configured": True,
+            "base_url": MINICPM_VISION_BASE_URL,
+            "models": model_ids,
+            "warning": f"/models unavailable, chat completions ready: {models_warning}",
+            "elapsed_ms": _elapsed_ms(start),
+        }
+    except (OSError, urllib.error.URLError, TimeoutError, KeyError, IndexError, TypeError, ValueError, json.JSONDecodeError) as exc:
         return {
             "available": False,
             "status": "fallback-ready",
@@ -1030,12 +1255,26 @@ def _prune_speech_outputs(keep_path: Path, max_files: int = 24) -> None:
 
 def speak_core(text: str, voice: str, speed: float) -> dict[str, Any]:
     start = time.perf_counter()
+    clean_text = _compact_text(text, 1200)
+    if not clean_text:
+        output_path = OUTPUT_DIR / f"speech-fallback-{uuid4().hex}.wav"
+        _silent_wav(output_path)
+        _prune_speech_outputs(output_path)
+        return {
+            "ok": True,
+            "runtime": "fallback",
+            "model": "hexgrad/Kokoro-82M",
+            "warning": "Kokoro skipped because transcript was empty",
+            "audio_url": f"/outputs/{output_path.name}",
+            "transcript": "",
+            "elapsed_ms": _elapsed_ms(start),
+        }
     try:
         from kokoro import KPipeline
         import soundfile as sf
 
         pipeline = KPipeline(lang_code="a")
-        generator = pipeline(text, voice=voice, speed=speed)
+        generator = pipeline(clean_text, voice=voice, speed=speed)
         _, _, audio = next(generator)
         output_path = OUTPUT_DIR / f"speech-{uuid4().hex}.wav"
         sf.write(output_path, audio, 24000)
@@ -1055,7 +1294,7 @@ def speak_core(text: str, voice: str, speed: float) -> dict[str, Any]:
         "model": "hexgrad/Kokoro-82M",
         "warning": warning,
         "audio_url": f"/outputs/{output_path.name}",
-        "transcript": text,
+        "transcript": clean_text,
         "elapsed_ms": _elapsed_ms(start),
     }
 
@@ -1067,25 +1306,41 @@ def _call_modal_klein(prompt: str, seed: int | None) -> dict[str, Any]:
     headers: dict[str, str] = {"Content-Type": "application/json"}
     if KLEIN_MODAL_TOKEN:
         headers["Authorization"] = f"Bearer {KLEIN_MODAL_TOKEN}"
+    endpoint = _modal_klein_base_url()
+    generate_url = f"{endpoint}/generate"
+    _runtime_log(
+        "Modal Klein generate request "
+        f"url={generate_url} token={'configured' if KLEIN_MODAL_TOKEN else 'not-set'} seed={seed}"
+    )
     request = urllib.request.Request(
-        f"{KLEIN_MODAL_ENDPOINT}/generate",
+        generate_url,
         data=body,
         headers=headers,
         method="POST",
     )
-    with urllib.request.urlopen(request, timeout=KLEIN_MODAL_TIMEOUT_SECONDS) as response:
-        payload = json.loads(response.read().decode("utf-8"))
+    try:
+        with urllib.request.urlopen(request, timeout=KLEIN_MODAL_TIMEOUT_SECONDS) as response:
+            payload = json.loads(response.read().decode("utf-8"))
+    except (OSError, urllib.error.URLError, TimeoutError, json.JSONDecodeError) as exc:
+        detail = _http_exception_detail(exc)
+        _runtime_log(f"Modal Klein generate failed url={generate_url} error={detail}")
+        raise
     if payload.get("ok") is not True:
+        _runtime_log(f"Modal Klein generate returned ok=false payload={_compact_text(json.dumps(payload), 400)}")
         raise ValueError(str(payload.get("error") or payload.get("detail") or "Modal Klein returned ok=false"))
     if payload.get("model") != MODEL_MANIFEST["image_generation"]["id"]:
+        _runtime_log(f"Modal Klein generate returned unexpected model={payload.get('model')}")
         raise ValueError("Modal Klein returned unexpected model")
     if payload.get("runtime") != "modal-klein":
+        _runtime_log(f"Modal Klein generate returned unexpected runtime={payload.get('runtime')}")
         raise ValueError("Modal Klein returned unexpected runtime")
     image_url = payload.get("image_url", "")
     if not isinstance(image_url, str) or not image_url:
+        _runtime_log("Modal Klein generate response did not include image_url")
         raise ValueError("Modal Klein response did not include image_url")
     if image_url and image_url.startswith("/media/"):
-        image_url = f"{KLEIN_MODAL_ENDPOINT}{image_url}"
+        image_url = f"{endpoint}{image_url}"
+    _runtime_log(f"Modal Klein generate succeeded runtime={payload.get('runtime')} image_url={image_url}")
     return {
         "ok": True,
         "runtime": payload.get("runtime", "modal-klein"),
@@ -1117,10 +1372,23 @@ def generate_image_core(prompt: str, seed: int | None) -> dict[str, Any]:
         try:
             return _call_modal_klein(prompt, seed)
         except (OSError, urllib.error.URLError, TimeoutError, ValueError, KeyError, json.JSONDecodeError) as exc:
-            return _fallback_image(prompt, seed, warning=f"Modal Klein unavailable: {exc.__class__.__name__}")
+            return _fallback_image(prompt, seed, warning=f"Modal Klein unavailable: {_http_exception_detail(exc)}")
+    _runtime_log("Modal Klein generate skipped because KLEIN_MODAL_ENDPOINT is not configured")
     return _fallback_image(prompt, seed)
 
 
+def _thumbnail_image_prompt(topic: str) -> str:
+    return (
+        f"Square image-only editorial thumbnail about {topic}. "
+        "Create one centered cohesive scene: a friendly assistive robot or small AI helper guiding a reader "
+        "through visual information with light, sound waves, image cards, and accessibility cues. "
+        "Fill most of the frame with the subject while leaving a small clean margin. "
+        "Modern polished 3D editorial illustration, soft gradients, warm blue and teal accents, clear focal point. "
+        "No words, no letters, no numbers, no captions, no title, no logo, no watermark, "
+        "no user interface, no screenshot, no document page, no poster layout, no split panels."
+    )
+
+
 def generate_article_core(topic: str) -> dict[str, Any]:
     start = time.perf_counter()
     clean_topic = _compact_text(topic, 100).strip()
@@ -1130,54 +1398,57 @@ def generate_article_core(topic: str) -> dict[str, Any]:
     article = _fallback_article(clean_topic)
     runtime = "fallback"
     warning = None
-    try:
-        body = json.dumps(
-            {
-                "model": LLAMA_CPP_MODEL,
-                "messages": [
-                    {
-                        "role": "system",
-                        "content": (
-                            "You are Tiny Narrator's article generator. "
-                            "Create concise, semantic, accessible article drafts."
-                        ),
-                    },
-                    {"role": "user", "content": _article_generation_prompt(clean_topic)},
-                ],
-                "temperature": 0.35,
-                "max_tokens": 420,
-            }
-        ).encode("utf-8")
-        request = urllib.request.Request(
-            f"{LLAMA_CPP_BASE_URL}/chat/completions",
-            data=body,
-            headers={"Content-Type": "application/json"},
-            method="POST",
-        )
-        with urllib.request.urlopen(request, timeout=45) as response:
-            payload = json.loads(response.read().decode("utf-8"))
-        generated = json.loads(payload["choices"][0]["message"]["content"].strip())
-        sections = generated.get("sections", [])
-        if (
-            isinstance(generated.get("title"), str)
-            and isinstance(generated.get("dek"), str)
-            and isinstance(sections, list)
-            and len(sections) == 3
-            and all(isinstance(item.get("heading"), str) and isinstance(item.get("body"), str) for item in sections)
-        ):
-            article = {
-                "title": _compact_text(generated["title"], 90),
-                "dek": _compact_text(generated["dek"], 180),
-                "sections": [
-                    {"heading": _compact_text(item["heading"], 80), "body": _compact_text(item["body"], 260)}
-                    for item in sections
-                ],
-            }
-            runtime = "llama.cpp"
-    except (OSError, urllib.error.URLError, TimeoutError, KeyError, json.JSONDecodeError) as exc:
-        warning = f"llama.cpp unavailable: {exc.__class__.__name__}"
+    if not LLAMA_CPP_BASE_URL:
+        warning = "llama.cpp unavailable: LLAMA_CPP_BASE_URL is not configured"
+    else:
+        try:
+            body = json.dumps(
+                {
+                    "model": LLAMA_CPP_MODEL,
+                    "messages": [
+                        {
+                            "role": "system",
+                            "content": (
+                                "You are Tiny Narrator's article generator. "
+                                "Create concise, semantic, accessible article drafts."
+                            ),
+                        },
+                        {"role": "user", "content": _article_generation_prompt(clean_topic)},
+                    ],
+                    "temperature": 0.35,
+                    "max_tokens": 650,
+                }
+            ).encode("utf-8")
+            request = urllib.request.Request(
+                f"{LLAMA_CPP_BASE_URL}/chat/completions",
+                data=body,
+                headers=_llama_cpp_headers({"Content-Type": "application/json"}),
+                method="POST",
+            )
+            with urllib.request.urlopen(request, timeout=LLAMA_CPP_TIMEOUT_SECONDS) as response:
+                payload = json.loads(response.read().decode("utf-8"))
+            generated = json.loads(payload["choices"][0]["message"]["content"].strip())
+            sections = generated.get("sections", [])
+            if (
+                isinstance(generated.get("title"), str)
+                and isinstance(generated.get("dek"), str)
+                and isinstance(sections, list)
+                and len(sections) == 5
+                and all(isinstance(item.get("heading"), str) and isinstance(item.get("body"), str) for item in sections)
+            ):
+                article = {
+                    "title": _compact_text(generated["title"], 90),
+                    "dek": _compact_text(generated["dek"], 180),
+                    "sections": [
+                        {"heading": _compact_text(item["heading"], 80), "body": _compact_text(item["body"], 720)}
+                        for item in sections
+                    ],
+                }
+                runtime = "llama.cpp"
+        except (OSError, urllib.error.URLError, TimeoutError, ValueError, KeyError, json.JSONDecodeError) as exc:
+            warning = f"llama.cpp unavailable: {exc.__class__.__name__}"
 
-    image_prompt = f"Editorial thumbnail for an accessible article about {clean_topic}."
+    image_prompt = _thumbnail_image_prompt(clean_topic)
     thumbnail = generate_image_core(image_prompt, seed=_topic_seed(clean_topic))
     return {
         "ok": True,
@@ -1360,4 +1631,4 @@ async def handle_exception(_: Request, exc: Exception) -> JSONResponse:
 
 
 if __name__ == "__main__":
-    app.launch(server_name=GRADIO_SERVER_NAME, server_port=GRADIO_SERVER_PORT)
+    app.launch(server_name=GRADIO_SERVER_NAME, server_port=GRADIO_SERVER_PORT, share=GRADIO_SHARE)

modal_workers/klein_image.py

@@ -11,71 +11,148 @@ The deployed ASGI app exposes one base URL with:
 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
 
 import modal
 
-app = modal.App("tiny-narrator-klein")
 
-output_volume = modal.Volume.from_name("tiny-narrator-klein-outputs", create_if_missing=True)
+APP_NAME = "tiny-narrator-klein"
+CACHE_DIR = Path("/cache")
 MEDIA_DIR = Path("/outputs")
-
 IMAGE_MODEL_ID = "black-forest-labs/FLUX.2-klein-4B"
-_PIPELINE = None
+
+app = modal.App(APP_NAME)
+model_cache = modal.Volume.from_name("tiny-narrator-klein-cache", create_if_missing=True)
+output_volume = modal.Volume.from_name("tiny-narrator-klein-outputs", create_if_missing=True)
 
 klein_image = (
-    modal.Image.debian_slim(python_version="3.11")
+    modal.Image.debian_slim(python_version="3.12")
+    .apt_install("git")
+    .pip_install(
+        "torch==2.9.1",
+        index_url="https://download.pytorch.org/whl/cu128",
+    )
     .pip_install(
-        "fastapi[standard]",
-        "huggingface-hub[hf-transfer]>=0.36.0",
-        "pillow",
-        "torch",
-        "transformers",
-        "git+https://github.com/huggingface/diffusers.git",
+        "accelerate==1.12.0",
+        "diffusers @ git+https://github.com/huggingface/diffusers.git",
+        "fastapi[standard]==0.136.3",
+        "huggingface-hub[hf-transfer]==0.36.0",
+        "pillow==12.2.0",
         "safetensors>=0.8.0rc0",
-        "accelerate",
-        "sentencepiece",
+        "sentencepiece==0.2.1",
+        "transformers==4.57.3",
     )
     .env({"HF_HUB_ENABLE_HF_TRANSFER": "1"})
 )
 
 
-def _get_pipeline():
-    """Load the Klein pipeline once per warm ASGI container."""
-    global _PIPELINE
-    if _PIPELINE is None:
+def _secret_names() -> list[modal.Secret]:
+    """Return the fixed secrets used by Modal deployments.
+
+    Modal requires dependencies to be identical between local deploy-time import
+    and remote container import. Keep this list static; do not derive it from
+    environment variables.
+    """
+
+    return [modal.Secret.from_name("tiny-narrator-klein-token")]
+
+
+async def _media_file_response(filename: str):
+    from fastapi import HTTPException
+    from fastapi.responses import Response
+
+    path = MEDIA_DIR / filename
+    if not path.exists() or not path.is_file():
+        try:
+            await output_volume.reload.aio()
+        except RuntimeError as exc:
+            if not path.exists() or not path.is_file():
+                raise HTTPException(status_code=503, detail=f"Media volume reload failed: {exc}") from exc
+
+    if not path.exists() or not path.is_file():
+        raise HTTPException(status_code=404, detail=f"Media file not found: {filename}")
+
+    content_type = "image/png"
+    if filename.endswith(".webp"):
+        content_type = "image/webp"
+    elif filename.endswith((".jpg", ".jpeg")):
+        content_type = "image/jpeg"
+    return Response(content=path.read_bytes(), media_type=content_type)
+
+
+@app.cls(
+    image=klein_image,
+    gpu=os.getenv("KLEIN_MODAL_GPU", "A10G"),
+    volumes={str(CACHE_DIR): model_cache, str(MEDIA_DIR): output_volume},
+    secrets=_secret_names(),
+    timeout=900,
+    scaledown_window=300,
+    max_containers=1,
+)
+class KleinImageModel:
+    @modal.enter()
+    def load(self) -> None:
         import torch
-        from diffusers import FluxPipeline
+        from diffusers import Flux2KleinPipeline
 
-        pipe = FluxPipeline.from_pretrained(
-            IMAGE_MODEL_ID,
+        self.model_id = os.environ.get("KLEIN_IMAGE_MODEL_ID", IMAGE_MODEL_ID)
+        token = os.environ.get("HF_TOKEN")
+        self.pipe = Flux2KleinPipeline.from_pretrained(
+            self.model_id,
+            cache_dir=str(CACHE_DIR / "huggingface"),
             torch_dtype=torch.bfloat16,
+            token=token,
+        )
+        self.pipe.to("cuda")
+
+    @modal.method()
+    def generate(self, prompt: str, seed: int | None = None) -> dict:
+        import torch
+
+        MEDIA_DIR.mkdir(parents=True, exist_ok=True)
+        generator = None
+        if seed is not None:
+            generator = torch.Generator(device="cuda").manual_seed(seed)
+
+        result = self.pipe(
+            prompt=prompt,
+            num_inference_steps=int(os.environ.get("KLEIN_MODAL_STEPS", "4")),
+            guidance_scale=float(os.environ.get("KLEIN_MODAL_GUIDANCE", "1.0")),
+            generator=generator,
         )
-        pipe.to("cuda")
-        _PIPELINE = pipe
-    return _PIPELINE
+        image = result.images[0]
+
+        filename = f"klein-{uuid4().hex}.png"
+        output_path = MEDIA_DIR / filename
+        buffer = io.BytesIO()
+        image.save(buffer, format="PNG")
+        output_path.write_bytes(buffer.getvalue())
+        output_volume.commit()
+
+        return {
+            "filename": filename,
+            "model": self.model_id,
+        }
 
 
 @app.function(
     image=klein_image,
-    gpu="A10G",
-    timeout=900,
-    container_idle_timeout=300,
     volumes={str(MEDIA_DIR): output_volume},
+    secrets=_secret_names(),
+    timeout=300,
 )
-@modal.asgi_app()
+@modal.concurrent(max_inputs=20)
+@modal.asgi_app(label="tiny-narrator-klein")
 def klein_api():
     from fastapi import FastAPI, HTTPException, Request
-    from fastapi.responses import Response
-    import torch
+
+    import time
 
     api = FastAPI(title="Tiny Narrator Klein Worker")
+    model = KleinImageModel()
 
     def _check_token(request: Request) -> None:
         """Reject the request if a token is configured but not provided or mismatched."""
@@ -101,64 +178,41 @@ def klein_api():
             "runtime": "modal-klein",
         }
 
+    @api.get("/media/{filename}")
+    async def media(filename: str):
+        return await _media_file_response(filename)
+
     @api.post("/generate")
-    async def generate(request: Request, body: dict) -> dict:
+    async def generate(request: Request) -> dict:
         _check_token(request)
         start = time.perf_counter()
+        body = await request.json()
         prompt = str(body.get("prompt") or "").strip()
         if not prompt:
             raise HTTPException(status_code=400, detail="prompt is required")
 
         seed = body.get("seed")
-        generator = None
         if seed is not None:
             try:
                 seed = int(seed)
             except (TypeError, ValueError) as exc:
                 raise HTTPException(status_code=400, detail="seed must be an integer") from exc
-            generator = torch.Generator(device="cuda").manual_seed(seed)
-
-        result = _get_pipeline()(
-            prompt=prompt,
-            num_inference_steps=28,
-            guidance_scale=3.5,
-            generator=generator,
-        )
-        image = result.images[0]
-
-        filename = f"klein-{uuid4().hex}.png"
-        output_path = MEDIA_DIR / filename
-        output_path.parent.mkdir(parents=True, exist_ok=True)
 
-        buffer = io.BytesIO()
-        image.save(buffer, format="PNG")
-        output_path.write_bytes(buffer.getvalue())
-        output_volume.commit()
+        result = await model.generate.remote.aio(prompt, seed)
+        model_id = result.get("model") or IMAGE_MODEL_ID
+        if model_id != IMAGE_MODEL_ID:
+            raise HTTPException(status_code=500, detail=f"unexpected model: {model_id}")
 
+        filename = result["filename"]
+        image_url = str(request.url_for("media", filename=filename))
         return {
             "ok": True,
             "runtime": "modal-klein",
             "model": IMAGE_MODEL_ID,
-            "image_url": f"/media/{filename}",
+            "image_url": image_url,
             "prompt": prompt,
             "seed": seed,
             "elapsed_ms": round((time.perf_counter() - start) * 1000),
         }
 
-    @api.get("/media/{filename}")
-    async def media(filename: str):
-        output_volume.reload()
-        media_path = MEDIA_DIR / filename
-        if not media_path.exists() or not media_path.is_file():
-            raise HTTPException(status_code=404, detail=f"Media file not found: {filename}")
-
-        data = media_path.read_bytes()
-        content_type = "image/png"
-        if filename.endswith(".webp"):
-            content_type = "image/webp"
-        elif filename.endswith(".jpg") or filename.endswith(".jpeg"):
-            content_type = "image/jpeg"
-
-        return Response(content=data, media_type=content_type)
-
     return api

modal_workers/reader_brain.py

@@ -0,0 +1,101 @@
+"""Modal worker for Tiny Narrator's llama.cpp reader brain.
+
+Deploy:
+    modal deploy modal_workers/reader_brain.py
+
+The deployed web server exposes llama.cpp's OpenAI-compatible API. Set:
+    LLAMA_CPP_BASE_URL=https://<modal-app-url>/v1
+    LLAMA_CPP_MODEL=narrator-brain
+    LLAMA_CPP_TOKEN=<same value as Modal secret>
+
+The server intentionally binds to 0.0.0.0 because Modal's web_server proxy
+routes traffic to the container port.
+"""
+
+import os
+import subprocess
+
+import modal
+
+
+APP_NAME = "tiny-narrator-reader-brain"
+MODEL_REF = "nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF:Q4_K_M"
+MODEL_ALIAS = "narrator-brain"
+SERVER_PORT = 8080
+CACHE_DIR = "/cache"
+
+app = modal.App(APP_NAME)
+model_cache = modal.Volume.from_name("tiny-narrator-reader-brain-cache", create_if_missing=True)
+
+
+def _secret_names() -> list[modal.Secret]:
+    return [modal.Secret.from_name("tiny-narrator-reader-brain-token")]
+
+reader_brain_image = (
+    modal.Image.from_registry(
+        "nvidia/cuda:12.4.1-devel-ubuntu22.04",
+        add_python="3.12",
+    )
+    .apt_install("git", "cmake", "build-essential", "curl", "ca-certificates")
+    .run_commands(
+        "git clone --depth 1 https://github.com/ggml-org/llama.cpp.git /tmp/llama.cpp",
+        "cmake -S /tmp/llama.cpp -B /tmp/llama.cpp/build "
+        "-DGGML_CUDA=ON -DCMAKE_BUILD_TYPE=Release",
+        "cmake --build /tmp/llama.cpp/build --target llama-server -j$(nproc)",
+        "cp /tmp/llama.cpp/build/bin/llama-server /usr/local/bin/llama-server",
+        "chmod +x /usr/local/bin/llama-server",
+        "rm -rf /tmp/llama.cpp",
+    )
+    .env(
+        {
+            "HF_HOME": f"{CACHE_DIR}/huggingface",
+        }
+    )
+)
+
+
+@app.function(
+    image=reader_brain_image,
+    gpu=os.getenv("READER_BRAIN_MODAL_GPU", "T4"),
+    volumes={CACHE_DIR: model_cache},
+    secrets=_secret_names(),
+    timeout=900,
+    scaledown_window=300,
+    max_containers=1,
+)
+@modal.concurrent(max_inputs=20)
+@modal.web_server(SERVER_PORT)
+def reader_brain_server():
+    model_ref = os.getenv("READER_BRAIN_MODEL_REF", MODEL_REF)
+    model_alias = os.getenv("READER_BRAIN_MODEL_ALIAS", MODEL_ALIAS)
+    context_size = os.getenv("READER_BRAIN_CTX_SIZE", "0")
+    gpu_layers = os.getenv("READER_BRAIN_GPU_LAYERS", "999")
+    api_key = os.getenv("LLAMA_CPP_TOKEN", "")
+
+    command = [
+        "llama-server",
+        "--host",
+        "0.0.0.0",
+        "--port",
+        str(SERVER_PORT),
+        "-hf",
+        model_ref,
+        "--alias",
+        model_alias,
+        "--ctx-size",
+        context_size,
+        "--reasoning",
+        "off",
+        "--n-gpu-layers",
+        gpu_layers,
+    ]
+    if api_key:
+        command.extend(["--api-key", api_key])
+
+    display_command = command.copy()
+    if "--api-key" in display_command:
+        key_index = display_command.index("--api-key") + 1
+        if key_index < len(display_command):
+            display_command[key_index] = "***"
+    print(f"[tiny-narrator-reader-brain] starting: {' '.join(display_command)}", flush=True)
+    subprocess.Popen(command)

scripts/verify.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import json
 import py_compile
 import sys
+import urllib.error
 import wave
 from pathlib import Path
 from unittest.mock import patch, MagicMock
@@ -23,6 +24,9 @@ def assert_true(condition: bool, message: str) -> None:
 def verify_static_assets() -> None:
     required = [
         ROOT / "LICENSE",
+        ROOT / "DEPLOY_SPACES.md",
+        ROOT / "Dockerfile",
+        ROOT / "start.sh",
         ROOT / "SUBMISSION.md",
         ROOT / "static" / "index.html",
         ROOT / "static" / "generate.html",
@@ -40,6 +44,17 @@ def verify_static_assets() -> None:
     generate_js = (ROOT / "static" / "generate.js").read_text(encoding="utf-8")
     index_html = (ROOT / "static" / "index.html").read_text(encoding="utf-8")
     generate_html = (ROOT / "static" / "generate.html").read_text(encoding="utf-8")
+    deploy_spaces = (ROOT / "DEPLOY_SPACES.md").read_text(encoding="utf-8")
+    dockerfile = (ROOT / "Dockerfile").read_text(encoding="utf-8")
+    start_script = (ROOT / "start.sh").read_text(encoding="utf-8")
+    assert_true("FROM python:3.12-slim" in dockerfile, "Spaces Dockerfile should use a free CPU Python base image")
+    assert_true("nvidia/cuda" not in dockerfile, "Spaces Dockerfile should not require paid HF GPU CUDA image")
+    assert_true("llama-server" not in start_script, "Spaces start script should not launch local llama.cpp")
+    assert_true("free CPU" in deploy_spaces, "Spaces deploy guide should describe free CPU deployment")
+    assert_true("modal_workers/reader_brain.py" in deploy_spaces, "Spaces deploy guide should document Modal reader-brain deployment")
+    assert_true("CPU Basic" in deploy_spaces, "Spaces deploy guide should recommend CPU Basic hardware")
+    assert_true("LLAMA_CPP_TOKEN" in deploy_spaces, "Spaces deploy guide should document reader-brain auth token")
+    assert_true("tiny-narrator-reader-brain-token" in deploy_spaces, "Spaces deploy guide should document the Modal reader token secret")
     assert_true('href="/" aria-current="page">Reader' in index_html, "Reader page should mark Reader route current")
     assert_true('href="/generate">Generate' in index_html, "Reader page should link to Generate route")
     assert_true('href="/">Reader' in generate_html, "Generate page should link back to Reader route")
@@ -52,6 +67,8 @@ def verify_static_assets() -> None:
     assert_true("/api/generate-article" in generate_js, "Generate frontend should call article generation API")
     assert_true("/api/reader-brain" in generate_js, "Generate frontend should call reader-brain narration API")
     assert_true("/api/speak" in generate_js, "Generate frontend should call speech API")
+    assert_true('node.type === "image"' in generate_js, "Generate reader should reserve reader-brain item narration for images")
+    assert_true('runtime: "raw text"' in generate_js, "Generate reader should speak text-only nodes without reader-brain")
     assert_true("refreshReaderNodes" in generate_js, "Generate frontend should build a generated article reader path")
     assert_true('data-reader-type="heading"' in generate_js, "Generated article sections should mark heading reader nodes")
     assert_true('data-reader-type="paragraph"' in generate_js, "Generated article sections should mark paragraph reader nodes")
@@ -102,6 +119,8 @@ def verify_static_assets() -> None:
     )
     assert_true("transcript-position" in app_js, "Transcript should render the narrated reader position")
     assert_true("readerItemStatus(node)" in app_js, "Narration transcript entries should include reader item position")
+    assert_true('node.type === "image"' in app_js, "Article reader should reserve reader-brain item narration for images")
+    assert_true('runtime: "raw text"' in app_js, "Article reader should speak text-only nodes without reader-brain")
     assert_true(
         "[${entry.type} / ${entry.position} / ${entry.runtime}]" in app_js,
         "Copied transcript should include type, position, and runtime",
@@ -258,6 +277,56 @@ def verify_core_fallbacks() -> None:
     assert_true(summary["ok"], "Reader-brain summary fallback did not return ok")
     assert_true(summary["narration"].startswith("Summary."), "Summary fallback should announce summary mode")
 
+    with patch.object(app, "LLAMA_CPP_BASE_URL", ""):
+        unconfigured_reader = app.reader_brain_core(
+            node_type="paragraph",
+            text="This paragraph should be narrated without a configured endpoint.",
+            position="item 1 of 1",
+            mode="narrate",
+        )
+        assert_true(unconfigured_reader["runtime"] == "fallback", "Unconfigured reader brain should use fallback")
+        assert_true(
+            "not configured" in unconfigured_reader["warning"],
+            "Unconfigured reader brain should explain the missing endpoint",
+        )
+
+        unconfigured_article = app.generate_article_core("accessible classroom tools")
+        assert_true(unconfigured_article["runtime"] == "fallback", "Unconfigured article generation should use fallback")
+        assert_true(
+            "not configured" in unconfigured_article["warning"],
+            "Unconfigured article generation should explain the missing endpoint",
+        )
+
+    empty_llama_response = MagicMock()
+    empty_llama_response.read.return_value = json.dumps({"choices": [{"message": {"content": ""}}]}).encode("utf-8")
+    empty_llama_response.__enter__ = lambda s: s
+    empty_llama_response.__exit__ = MagicMock(return_value=False)
+    with patch("urllib.request.urlopen", return_value=empty_llama_response):
+        empty_narration = app.reader_brain_core(
+            node_type="paragraph",
+            text="This paragraph still needs narration.",
+            position="item 2 of 3",
+            mode="narrate",
+        )
+        assert_true(empty_narration["runtime"] == "fallback", "Empty llama.cpp response should use fallback narration")
+        assert_true(empty_narration["narration"], "Empty llama.cpp response should not return empty narration")
+
+    reasoning_response = MagicMock()
+    reasoning_response.read.return_value = json.dumps(
+        {"choices": [{"message": {"content": "", "reasoning_content": "Heading. Live narration from llama.cpp."}}]}
+    ).encode("utf-8")
+    reasoning_response.__enter__ = lambda s: s
+    reasoning_response.__exit__ = MagicMock(return_value=False)
+    with patch("urllib.request.urlopen", return_value=reasoning_response):
+        reasoning_narration = app.reader_brain_core(
+            node_type="heading",
+            text="Live heading",
+            position="item 1 of 1",
+            mode="narrate",
+        )
+        assert_true(reasoning_narration["runtime"] == "llama.cpp", "Reader brain should use alternate llama.cpp message text fields")
+        assert_true("Live narration" in reasoning_narration["narration"], "Reader brain should extract reasoning_content when content is empty")
+
     description = app.describe_image_core("model-map", caption=None, prompt=None)
     assert_true(description["ok"], "Image description did not return ok")
     assert_true("small AI models" in description["alt_text"], "Image description fallback changed unexpectedly")
@@ -289,6 +358,10 @@ def verify_core_fallbacks() -> None:
         assert_true(wav.getframerate() == 24000, "Speech output should be 24 kHz")
         assert_true(wav.getnchannels() == 1, "Speech output should be mono")
 
+    empty_speech = app.speak_core("", voice="af_heart", speed=1.0)
+    assert_true(empty_speech["runtime"] == "fallback", "Empty speech input should use fast fallback")
+    assert_true("empty" in empty_speech["warning"].lower(), "Empty speech input should explain why Kokoro was skipped")
+
     generated = app.generate_image_core("Tiny accessibility article image.", seed=3)
     assert_true(generated["ok"], "Image generation placeholder should return ok")
     assert_true(isinstance(generated["elapsed_ms"], int), "Image generation should include elapsed_ms")
@@ -306,11 +379,14 @@ def verify_core_fallbacks() -> None:
     article = app.generate_article_core("tiny classroom robotics")
     assert_true(article["ok"], "Article generation should return ok")
     assert_true(article["model"] == app.MODEL_MANIFEST["reader_brain"]["id"], "Article generation should use reader-brain model")
-    assert_true(len(article["article"]["sections"]) == 3, "Article generation should return three sections")
+    assert_true(len(article["article"]["sections"]) == 5, "Article generation should return five sections")
     assert_true(
         article["thumbnail"]["generation_model"] == app.MODEL_MANIFEST["image_generation"]["id"],
         "Article generation should use the Klein image model for thumbnail receipt",
     )
+    assert_true("No words" in article["thumbnail"]["prompt"], "Article thumbnail prompt should forbid unreadable generated text")
+    assert_true("no user interface" in article["thumbnail"]["prompt"], "Article thumbnail prompt should avoid UI screenshots")
+    assert_true("one centered cohesive scene" in article["thumbnail"]["prompt"], "Article thumbnail prompt should avoid sparse disconnected layouts")
 
 
 def verify_modal_klein_integration() -> None:
@@ -387,12 +463,56 @@ def verify_modal_klein_integration() -> None:
     assert_true("modal.App" in worker_source, "Modal worker should create a Modal App")
     assert_true("modal.Volume" in worker_source, "Modal worker should use a Modal Volume")
     assert_true("FLUX.2-klein-4B" in worker_source, "Modal worker should reference the Klein model")
+    assert_true("Flux2KleinPipeline" in worker_source, "Modal worker should use the FLUX.2 Klein Diffusers pipeline")
     assert_true("modal.asgi_app" in worker_source, "Modal worker should expose one ASGI app")
     assert_true('@api.post("/generate")' in worker_source, "Modal worker should expose POST /generate")
     assert_true('@api.get("/health")' in worker_source, "Modal worker should expose GET /health")
     assert_true('@api.get("/media/{filename}")' in worker_source, "Modal worker should expose GET /media/{filename}")
     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")
+    assert_true("reload.aio()" in worker_source, "Modal worker should reload volume with async API before serving missing media")
+    assert_true("path.read_bytes()" in worker_source, "Modal worker should avoid streaming open files from the volume")
+
+    reader_worker_path = ROOT / "modal_workers" / "reader_brain.py"
+    assert_true(reader_worker_path.exists(), "Modal reader-brain worker file should exist")
+    reader_worker_source = reader_worker_path.read_text(encoding="utf-8")
+    assert_true("modal.web_server" in reader_worker_source, "Reader-brain worker should expose llama-server through Modal web_server")
+    assert_true("nvidia/cuda:12.4.1-devel-ubuntu22.04" in reader_worker_source, "Reader-brain worker should use a CUDA build image")
+    assert_true("GGML_CUDA=ON" in reader_worker_source, "Reader-brain worker should compile llama.cpp with CUDA")
+    assert_true("NVIDIA-Nemotron-3-Nano-4B-GGUF:Q4_K_M" in reader_worker_source, "Reader-brain worker should serve the Nemotron GGUF")
+    assert_true('"--reasoning"' in reader_worker_source and '"off"' in reader_worker_source, "Reader-brain worker should disable reasoning mode")
+    assert_true('"--ctx-size"' in reader_worker_source and '"0"' in reader_worker_source, "Reader-brain worker should use model context size")
+    assert_true('"--n-gpu-layers"' in reader_worker_source and '"999"' in reader_worker_source, "Reader-brain worker should request full GPU offload")
+    assert_true("modal.Volume" in reader_worker_source, "Reader-brain worker should cache model downloads in a Modal volume")
+    assert_true("tiny-narrator-reader-brain-token" in reader_worker_source, "Reader-brain worker should use a fixed Modal token secret")
+    assert_true('"--api-key"' in reader_worker_source, "Reader-brain worker should pass an API key to llama-server when configured")
+    assert_true('display_command[key_index] = "***"' in reader_worker_source, "Reader-brain worker should redact API keys in logs")
+
+    # Test: reader-brain auth wiring sends bearer tokens when configured
+    model_response = MagicMock()
+    model_response.read.return_value = json.dumps({"data": [{"id": "narrator-brain"}]}).encode("utf-8")
+    model_response.__enter__ = lambda s: s
+    model_response.__exit__ = MagicMock(return_value=False)
+    with patch.object(app, "LLAMA_CPP_BASE_URL", "https://reader.example/v1"), patch.object(app, "LLAMA_CPP_TOKEN", "reader-secret"):
+        with patch("urllib.request.urlopen", return_value=model_response) as urlopen_mock:
+            app._runtime_status_core()
+            status_request = urlopen_mock.call_args.args[0]
+            assert_true(
+                status_request.headers.get("Authorization") == "Bearer reader-secret",
+                "Runtime status should send reader-brain Bearer token when LLAMA_CPP_TOKEN is configured",
+            )
+
+    chat_response = MagicMock()
+    chat_response.read.return_value = json.dumps({"choices": [{"message": {"content": "Heading. Token protected narration."}}]}).encode("utf-8")
+    chat_response.__enter__ = lambda s: s
+    chat_response.__exit__ = MagicMock(return_value=False)
+    with patch.object(app, "LLAMA_CPP_BASE_URL", "https://reader.example/v1"), patch.object(app, "LLAMA_CPP_TOKEN", "reader-secret"):
+        with patch("urllib.request.urlopen", return_value=chat_response) as urlopen_mock:
+            app.reader_brain_core("heading", "Token protected narration", "item 1 of 1", "narrate")
+            chat_request = urlopen_mock.call_args.args[0]
+            assert_true(
+                chat_request.headers.get("Authorization") == "Bearer reader-secret",
+                "Reader-brain requests should send Bearer token when LLAMA_CPP_TOKEN is configured",
+            )
 
     # 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"):
@@ -421,6 +541,7 @@ def verify_modal_klein_integration() -> None:
     # 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")
+    assert_true("LLAMA_CPP_TOKEN" in env_example, ".env.example should document LLAMA_CPP_TOKEN")
 
     # Test: worker validates token
     assert_true("KLEIN_MODAL_TOKEN" in worker_source, "Modal worker should read KLEIN_MODAL_TOKEN")
@@ -446,6 +567,17 @@ def verify_modal_klein_integration() -> None:
             "Runtime setup should show token as configured without exposing the value",
         )
 
+    with patch.object(app, "LLAMA_CPP_TOKEN", "reader-super-secret"):
+        setup = app.runtime_setup_core()
+        setup_json = json.dumps(setup)
+        assert_true("reader-super-secret" not in setup_json, "Runtime setup must never expose the reader token value")
+        reader_step = next(step for step in setup["steps"] if step["role"] == "reader_brain")
+        assert_true("LLAMA_CPP_TOKEN" in reader_step["env"], "Runtime setup should document LLAMA_CPP_TOKEN")
+        assert_true(
+            reader_step["env"]["LLAMA_CPP_TOKEN"] == "(configured)",
+            "Runtime setup should show reader 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()
@@ -554,6 +686,17 @@ def verify_minicpm_vision_integration() -> None:
                 assert_true(status["status"] == "online", "MiniCPM /models response should mark vision online")
                 assert_true("secret-key" not in json.dumps(status), "Vision runtime status should not expose API key")
 
+    ready_response = MagicMock()
+    ready_response.read.return_value = json.dumps({"choices": [{"message": {"content": "ready"}}]}).encode("utf-8")
+    ready_response.__enter__ = lambda s: s
+    ready_response.__exit__ = MagicMock(return_value=False)
+    with patch.object(app, "MINICPM_VISION_BASE_URL", "https://vision.example/v1"):
+        with patch.object(app, "MINICPM_VISION_API_KEY", "secret-key"):
+            with patch("urllib.request.urlopen", side_effect=[urllib.error.HTTPError("https://vision.example/v1/models", 404, "Not Found", {}, None), ready_response]):
+                status = app._vision_runtime_status()
+                assert_true(status["status"] == "online", "MiniCPM chat completions readiness should mark vision online when /models is unavailable")
+                assert_true("chat completions ready" in status.get("warning", ""), "Vision status should explain chat-completions readiness fallback")
+
     setup = app.runtime_setup_core()
     vision_step = next(step for step in setup["steps"] if step["role"] == "vision")
     assert_true("MiniCPM-V-4.6" in vision_step["model"], "Runtime setup should document MiniCPM-V-4.6")
@@ -710,6 +853,14 @@ def verify_routes() -> None:
         "llama-server" in setup_payload["steps"][0]["command"],
         "Runtime setup should include the llama.cpp launch command",
     )
+    assert_true(
+        setup_payload["steps"][0]["modal_command"] == "modal deploy modal_workers/reader_brain.py",
+        "Runtime setup should include the Modal reader-brain deploy command",
+    )
+    assert_true(
+        "--reasoning off" in setup_payload["steps"][0]["command"],
+        "Runtime setup should document non-reasoning llama.cpp mode",
+    )
     assert_true(
         setup_payload["app"]["env"]["PUBLIC_BASE_URL"] == app.PUBLIC_BASE_URL,
         "Runtime setup should expose the public command base URL",
@@ -793,7 +944,7 @@ def verify_routes() -> None:
     assert_true(article_sample.status_code == 200, "Article generation route should return 200")
     article_sample_payload = article_sample.json()
     assert_true(article_sample_payload["ok"], "Article generation payload should return ok")
-    assert_true(len(article_sample_payload["article"]["sections"]) == 3, "Article generation payload should include three sections")
+    assert_true(len(article_sample_payload["article"]["sections"]) == 5, "Article generation payload should include five sections")
     assert_true(
         article_sample_payload["thumbnail"]["generation_model"] == app.MODEL_MANIFEST["image_generation"]["id"],
         "Article generation payload should include Klein thumbnail provenance",
@@ -928,6 +1079,7 @@ def verify_routes() -> None:
 def main() -> None:
     py_compile.compile(str(ROOT / "app.py"), doraise=True)
     py_compile.compile(str(ROOT / "modal_workers" / "klein_image.py"), doraise=True)
+    py_compile.compile(str(ROOT / "modal_workers" / "reader_brain.py"), doraise=True)
     verify_static_assets()
     verify_space_metadata()
     verify_dotenv_wiring()

start.sh

@@ -0,0 +1,15 @@
+#!/bin/sh
+# Startup script for Tiny Narrator on Hugging Face Spaces free CPU.
+# Model inference endpoints are configured through environment variables.
+
+set -eu
+
+echo "[tiny-narrator] Starting Tiny Narrator app on ${GRADIO_SERVER_NAME:-0.0.0.0}:${PORT:-${GRADIO_SERVER_PORT:-7860}}"
+
+if [ -n "${LLAMA_CPP_BASE_URL:-}" ]; then
+    echo "[tiny-narrator] Reader brain endpoint configured at ${LLAMA_CPP_BASE_URL}"
+else
+    echo "[tiny-narrator] LLAMA_CPP_BASE_URL is not configured; reader brain will use deterministic fallback."
+fi
+
+exec python app.py