deeptutor-server 1.7.0__py3-none-any.whl

deeptutor/api/routers/settings.py

@@ -0,0 +1,2503 @@
+"""
+Settings API Router
+===================
+
+UI preferences, configuration catalog management, and detailed streamed tests.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Iterator
+import contextlib
+from copy import deepcopy
+import json
+import logging
+import time
+from typing import Any, List, Literal, Optional
+
+from fastapi import APIRouter, HTTPException, Query, Request, status
+from fastapi.responses import Response, StreamingResponse
+from pydantic import BaseModel, Field
+
+logger = logging.getLogger(__name__)
+
+from deeptutor.multi_user.context import get_current_user
+from deeptutor.multi_user.model_access import allowed_llm_options
+from deeptutor.services.codebuddy_auth import get_codebuddy_auth_service
+from deeptutor.services.codex_auth import (
+    CodexAuthError,
+    get_codex_oauth_service,
+    reconcile_codex_catalog_update,
+)
+from deeptutor.services.config import (
+    CATALOG_SECRET_MASK,
+    get_config_test_runner,
+    get_model_catalog_service,
+    get_runtime_settings_service,
+    redact_catalog_secrets,
+    restore_catalog_secrets,
+)
+from deeptutor.services.config.image_description import ImageDescriptionModelSelection
+from deeptutor.services.config.origins import normalize_origins
+from deeptutor.services.config.runtime_settings import (
+    CHAT_ATTACHMENT_CHARS_RANGE,
+    CHAT_ATTACHMENT_MAX_FILE_MB_RANGE,
+    CHAT_ATTACHMENT_MAX_TOTAL_MB_RANGE,
+    compute_ws_max_size,
+)
+from deeptutor.services.config.settings_draft import (
+    get_settings_draft_service,
+    is_empty_draft,
+    merge_draft_secrets,
+    redact_draft,
+)
+from deeptutor.services.config.settings_presets import (
+    SETTINGS_PRESETS_SCHEMA_VERSION,
+    get_settings_preset,
+    list_settings_presets,
+)
+from deeptutor.services.config.settings_profile import (
+    SettingsProfileError,
+    export_settings_profile,
+    review_settings_profile_import,
+)
+from deeptutor.services.llm.config import clear_llm_config_cache
+from deeptutor.services.model_selection import list_llm_options
+from deeptutor.services.path_service import get_path_service
+from deeptutor.services.session.usage_statistics import UsageStatistics
+from deeptutor.services.settings.interface_settings import (
+    DEFAULT_UI_SETTINGS as INTERFACE_DEFAULTS,
+)
+from deeptutor.services.settings.interface_settings import (
+    UiLanguage,
+    atomic_update,
+    resolve_languages,
+    sanitize_enabled_tools,
+)
+from deeptutor.services.settings.interface_settings import (
+    get_enabled_optional_tools as _get_enabled_optional_tools,
+)
+from deeptutor.services.settings.page_customization import (
+    ChatPageCustomization,
+    LearningPageCustomization,
+    PageCustomization,
+)
+from deeptutor.services.settings.starter_settings import (
+    TRACE_COUNT_RANGE as STARTER_TRACE_COUNT_RANGE,
+)
+from deeptutor.tools.builtin import USER_TOGGLEABLE_TOOL_NAMES
+
+router = APIRouter()
+# Public UI-settings router. The app shell bootstraps the interface language
+# from GET /api/settings/ui, and auth pages (/register, /login) must be
+# able to do the same *before* a session exists — so this one read endpoint
+# is intentionally mounted outside the ``_auth`` dependency (see main.py).
+# It only exposes non-sensitive UI preferences (theme/language), never the
+# model catalog, provider credentials, or runtime configuration.
+public_router = APIRouter()
+
+TOUR_CACHE = None
+
+# Reader-facing model output supports more languages than the interface.
+ResponseLanguage = Literal[
+    "en",
+    "zh",
+    "zh-tw",
+    "ja",
+    "ko",
+    "es",
+    "fr",
+    "de",
+    "ru",
+    "pt",
+    "it",
+    "ar",
+    "pl",
+    "uk",
+    "ms",
+]
+
+
+def get_enabled_optional_tools() -> list[str]:
+    """Compatibility export; the source of truth lives in the service layer."""
+
+    return _get_enabled_optional_tools()
+
+
+def _settings_file():
+    return get_path_service().get_settings_file("interface")
+
+
+def _tour_cache_file():
+    if TOUR_CACHE is not None:
+        return TOUR_CACHE
+    return get_path_service().get_settings_dir() / ".tour_cache.json"
+
+
+DEFAULT_SIDEBAR_NAV_ORDER = {
+    "start": ["/", "/history", "/knowledge-bases", "/notebooks"],
+    "learnResearch": ["/question", "/solver", "/research", "/co_writer"],
+}
+
+DEFAULT_UI_SETTINGS = {
+    # theme / language / response_language come from the module that owns
+    # interface.json, so the two readers of that file can't drift on what a
+    # fresh install defaults to.
+    **INTERFACE_DEFAULTS,
+    "sidebar_description": "✨ Data Intelligence Lab @ HKU",
+    "sidebar_nav_order": DEFAULT_SIDEBAR_NAV_ORDER,
+    # User-toggleable chat tools. Default = all on; the /settings/tools page
+    # is the single switchboard. Removed names (e.g. tools that ship later
+    # and the user hasn't seen yet) are ignored on read; missing names from a
+    # legacy file fall back to the default (all on).
+    "enabled_optional_tools": list(USER_TOGGLEABLE_TOOL_NAMES),
+    # When true, chat auto-plays each assistant reply via TTS. Per-user UI
+    # preference (not catalog); the chat surface also keeps a per-session
+    # override on top of this global default.
+    "voice_autoplay": False,
+    # When true, TTS verbalizes LaTeX into spoken math. When false, formulas
+    # are unwrapped from $ / $$ only. Default true (matches INTERFACE_DEFAULTS).
+    "voice_math_speak": True,
+    # Seconds the chat UI waits for any turn event before declaring the
+    # connection timed out. Bumped from 60 → 180 so slow tools (image/video
+    # generation) don't trip it; user-adjustable in Settings > Network.
+    "chat_response_timeout": 180,
+}
+
+# Bounds for the chat idle timeout (seconds): long enough for video renders,
+# capped so a typo can't wedge a turn open forever.
+CHAT_RESPONSE_TIMEOUT_MIN = 30
+CHAT_RESPONSE_TIMEOUT_MAX = 1800
+
+
+class SidebarNavOrder(BaseModel):
+    start: List[str]
+    learnResearch: List[str]
+
+
+class UISettings(BaseModel):
+    theme: Literal["light", "dark", "glass", "snow"] = "snow"
+    language: UiLanguage = "en"
+    response_language: ResponseLanguage = "en"
+    sidebar_description: Optional[str] = None
+    sidebar_nav_order: Optional[SidebarNavOrder] = None
+    code_block_theme: Optional[str] = None
+    code_block_show_line_numbers: Optional[bool] = None
+    code_block_wrap_long_lines: Optional[bool] = None
+
+
+class UISettingsUpdate(BaseModel):
+    """Partial UI settings for user-initiated PATCH/PUT updates via /api/settings/ui.
+
+    All fields have None defaults so `model_dump(exclude_unset=True)` naturally
+    excludes fields not provided in the frontend payload, while explicitly provided
+    defaults (e.g., `theme: "snow"`) still update the backend. This separates
+    the semantic contract: `/ui` endpoint only merges whatever explicitly arrives
+    from the frontend.
+    """
+
+    # Same Literal domains as UISettings — a None default keeps them optional
+    # for exclude_unset partial merges, but an explicit value is still validated
+    # so PUT /ui cannot persist a theme/language the app can't render.
+    theme: Literal["light", "dark", "glass", "snow"] | None = None
+    language: UiLanguage | None = None
+    response_language: ResponseLanguage | None = None
+    sidebar_description: str | None = None
+    sidebar_nav_order: SidebarNavOrder | None = None
+    code_block_theme: str | None = None
+    code_block_show_line_numbers: bool | None = None
+    code_block_wrap_long_lines: bool | None = None
+
+
+class VoiceAutoplayUpdate(BaseModel):
+    voice_autoplay: bool
+
+
+class VoiceMathSpeakUpdate(BaseModel):
+    voice_math_speak: bool
+
+
+class ChatResponseTimeoutUpdate(BaseModel):
+    chat_response_timeout: int = Field(ge=CHAT_RESPONSE_TIMEOUT_MIN, le=CHAT_RESPONSE_TIMEOUT_MAX)
+
+
+class ThemeUpdate(BaseModel):
+    theme: Literal["light", "dark", "glass", "snow"]
+
+
+class LanguageUpdate(BaseModel):
+    language: UiLanguage
+
+
+class SidebarDescriptionUpdate(BaseModel):
+    description: str
+
+
+class SidebarNavOrderUpdate(BaseModel):
+    nav_order: SidebarNavOrder
+
+
+class EnabledToolsUpdate(BaseModel):
+    enabled_tools: List[str]
+
+
+class VoicePreviewPayload(BaseModel):
+    catalog: dict[str, Any]
+    profile_id: str
+    model_id: str
+    text: str = Field(min_length=1, max_length=500)
+
+
+class VoiceDiscoveryPayload(BaseModel):
+    catalog: dict[str, Any]
+    profile_id: str
+    model_id: str
+
+
+class ServicePreviewPayload(BaseModel):
+    catalog: dict[str, Any]
+    profile_id: str
+    model_id: str | None = None
+    text: str = Field(default="", max_length=2000)
+    audio: str = Field(default="", max_length=11184812)
+    content_type: str = ""
+
+
+class CatalogPayload(BaseModel):
+    catalog: dict[str, Any]
+
+
+class ProviderEditPayload(BaseModel):
+    service: Literal["llm", "task", "embedding", "search", "tts", "stt", "imagegen", "videogen"]
+    profile: dict[str, Any]
+    connection: dict[str, Any] | None = None
+    active_model_id: str | None = None
+    activate: bool = False
+
+
+class RegistryEditPayload(BaseModel):
+    kind: Literal["provider", "model", "default", "task_choice"]
+    task: dict[str, Any] | None = None
+    ref: dict[str, Any] | None = None
+    fields: dict[str, Any] | None = None
+    service: (
+        Literal["llm", "task", "embedding", "search", "tts", "stt", "imagegen", "videogen"] | None
+    ) = None
+    profile_id: str | None = None
+    model_id: str | None = None
+    model: dict[str, Any] | None = None
+    config: dict[str, Any] | None = None
+    delete: bool = False
+
+
+class CatalogServicePayload(BaseModel):
+    """One model-catalog service to promote without touching other drafts."""
+
+    service: Literal[
+        "llm",
+        "task",
+        "embedding",
+        "search",
+        "tts",
+        "stt",
+        "imagegen",
+        "videogen",
+    ]
+    config: dict[str, Any]
+
+
+class SettingsDraftPayload(BaseModel):
+    """The unapplied settings envelope, as the settings UI holds it."""
+
+    catalog: dict[str, Any] | None = None
+    # Opaque per-page state, keyed by the string the page registers with.
+    extensions: dict[str, Any] = Field(default_factory=dict)
+
+
+class SettingsProfileImportPayload(BaseModel):
+    """An exported value-free settings profile submitted for review only."""
+
+    schema_version: str
+    profile: dict[str, Any]
+
+
+class SettingsPresetDraftRequest(SettingsDraftPayload):
+    """The current draft envelope submitted alongside a named preset."""
+
+
+class CodexReasoningEffortUpdate(BaseModel):
+    model: str = Field(min_length=1)
+    reasoning_effort: str | None = None
+
+
+class FetchModelsPayload(BaseModel):
+    binding: str = ""
+    base_url: str = ""
+    api_key: Optional[str] = None
+    profile_id: Optional[str] = None
+    # Which LLM-shaped service the profile lives in (for resolving a masked key).
+    service: Literal["llm", "task"] = "llm"
+    # The profile's API format; decides whether /models takes Anthropic headers.
+    api_format: Optional[str] = None
+
+
+class ModelCapabilitiesQuery(BaseModel):
+    binding: str = ""
+    model: str = ""
+
+
+class ProviderProbePayload(BaseModel):
+    binding: str = "openai"
+    base_url: str = ""
+    api_key: str | list[str] | None = None
+    api_format: str = "auto"
+    api_version: str = ""
+    extra_headers: dict[str, str] | str | None = None
+    proxy: str = ""
+    service: Literal["llm", "task", "embedding", "search", "tts", "stt", "imagegen", "videogen"] = (
+        "llm"
+    )
+    profile_id: str | None = None
+    connection_id: str | None = None
+
+
+class NetworkSettingsUpdate(BaseModel):
+    backend_port: int = Field(ge=1, le=65535)
+    frontend_port: int = Field(ge=1, le=65535)
+    public_api_base: str = ""
+    cors_origins: list[str] = Field(default_factory=list)
+
+
+class ChatAttachmentSettingsUpdate(BaseModel):
+    """Chat attachment policy (size caps + extraction budgets).
+
+    Bounds mirror the normalization clamps in
+    ``runtime_settings.CHAT_ATTACHMENT_*_RANGE`` so the API rejects loudly
+    what the file layer would silently clamp.
+    """
+
+    max_file_mb: int = Field(
+        ge=CHAT_ATTACHMENT_MAX_FILE_MB_RANGE[0], le=CHAT_ATTACHMENT_MAX_FILE_MB_RANGE[1]
+    )
+    max_total_mb: int = Field(
+        ge=CHAT_ATTACHMENT_MAX_TOTAL_MB_RANGE[0], le=CHAT_ATTACHMENT_MAX_TOTAL_MB_RANGE[1]
+    )
+    max_chars_per_doc: int = Field(
+        ge=CHAT_ATTACHMENT_CHARS_RANGE[0], le=CHAT_ATTACHMENT_CHARS_RANGE[1]
+    )
+    max_chars_total: int = Field(
+        ge=CHAT_ATTACHMENT_CHARS_RANGE[0], le=CHAT_ATTACHMENT_CHARS_RANGE[1]
+    )
+
+
+class ChatStarterSettingsUpdate(BaseModel):
+    """How much recent activity shapes the home screen's starting points.
+
+    Bounds mirror ``starter_settings.TRACE_COUNT_RANGE`` so the API rejects
+    loudly what the file layer would silently clamp.
+    """
+
+    trace_count: int = Field(ge=STARTER_TRACE_COUNT_RANGE[0], le=STARTER_TRACE_COUNT_RANGE[1])
+
+
+class MinerUSettingsUpdate(BaseModel):
+    """MinerU document-parsing backend settings.
+
+    ``api_token`` is tri-state: ``None`` keeps the stored token (the UI sends
+    None when the user didn't edit the secret field), ``""`` clears it, and a
+    non-empty string or string array replaces it. The GET payload never echoes
+    the raw token.
+    """
+
+    mode: Literal["local", "cloud"] = "local"
+    api_base_url: str = "https://mineru.net"
+    api_token: Optional[str | list[str]] = None
+    local_cli_path: str = ""
+    model_download_source: Literal["huggingface", "modelscope"] = "huggingface"
+    model_download_endpoint: str = ""
+    model_version: Literal["pipeline", "vlm"] = "pipeline"
+    language: str = "auto"
+    enable_formula: bool = True
+    enable_table: bool = True
+    is_ocr: bool = False
+    # Off by default → a local parse fails fast rather than silently pulling
+    # multi-GB model weights on first run.
+    allow_local_model_download: bool = False
+
+
+class MinerUModelDownloadPayload(BaseModel):
+    """One-click model download request (draft form values, like /test)."""
+
+    model_type: Literal["pipeline", "vlm", "all"] = "pipeline"
+    source: Literal["huggingface", "modelscope"] = "huggingface"
+    endpoint: str = ""
+    local_cli_path: str = ""
+
+
+class DocumentParsingUpdate(BaseModel):
+    """Document-parsing settings update (the multi-engine control panel).
+
+    ``engine`` (when provided) switches the active parse engine. ``engines``
+    carries partial per-engine updates merged over the stored slices. For the
+    MinerU engine, ``api_token`` stays tri-state: omit it (or send ``None``) to
+    keep the stored token, ``""`` clears it, a non-empty string replaces it.
+    The MinerU engine's own knobs can also be edited via the legacy
+    ``/mineru`` endpoints; both preserve the other engines' settings.
+    """
+
+    engine: Optional[str] = None
+    engines: Optional[dict[str, dict]] = None
+    # Toggle for vision-model captions of embedded images (None = keep stored).
+    image_caption: Optional[bool] = None
+    # Omit to keep the selection; null restores the main LLM.
+    image_description_model: Optional[ImageDescriptionModelSelection] = None
+
+
+class DocumentParsingTest(BaseModel):
+    """Readiness test for one engine (defaults to the active engine)."""
+
+    engine: Optional[str] = None
+
+
+class DoclingRemoteTest(BaseModel):
+    """Draft Docling remote-server test. ``api_token`` is tri-state: ``None``
+    falls back to the stored key, ``""`` clears it, a string supplies it (so
+    the user can verify an unsaved key before saving)."""
+
+    api_base_url: str = "http://localhost:5001"
+    api_token: Optional[str] = None
+
+
+class TikaRemoteTest(BaseModel):
+    """Draft Tika server test. Tests the unsaved URL so the user can verify
+    before saving."""
+
+    server_url: str = "http://localhost:9998"
+
+
+class DocumentParsingInstall(BaseModel):
+    """One-click pip install of an optional parser engine's package(s)."""
+
+    engine: str
+
+
+@contextlib.contextmanager
+def _runtime_catalog_write() -> Iterator[None]:
+    """Bracket a write to the model catalog, resetting clients if it landed.
+
+    The LLM and embedding clients are process-wide singletons that resolve
+    from this one file, so resetting them affects any user turn mid-flight on
+    another worker; admins issuing Apply during active sessions accept that,
+    and the WARNING keeps the cause in the audit trail.
+
+    An apply that saved the catalog already on disk changes nothing those
+    clients would read. That is the shape a settings visit re-applying the
+    same configuration takes, and each redundant reset flipped the backend
+    client out from under an in-flight turn and dropped it into the provider
+    retry ladder — the cold start whose first message sat in a loop until a
+    restart (#1421).
+
+    Whether the catalog changed is a property of the file, not of the caller,
+    so both sides are read here. Five endpoints each assembling their own
+    before/after pair is five chances to pair the wrong two and a sixth
+    endpoint's chance to forget; wrapping the write is the whole contract.
+
+    A write that raises leaves the block without resetting, which is what a
+    failed write should do: there is nothing new for the clients to read.
+    """
+    service = get_model_catalog_service()
+    before = service.load()
+    try:
+        yield
+    except PermissionError as exc:
+        # #1984: filesystem denial is not an authentication failure. Preserve
+        # the atomic writer's failure boundary and the unapplied draft; do not
+        # blindly retry a stale catalog over another writer's newer settings.
+        logger.exception("Filesystem access denied while saving the model catalog")
+        raise HTTPException(
+            status_code=503,
+            detail=(
+                "The server could not save model settings because filesystem access was denied. "
+                "Check the server service account's permissions on the settings folder and "
+                "whether another process or security software is holding model_catalog.json, "
+                "then retry."
+            ),
+        ) from exc
+    if service.load() == before:
+        return
+    logger.warning(
+        "Admin applied catalog; resetting global LLM/embedding clients. "
+        "In-flight user turns may flip backend client mid-call."
+    )
+    from deeptutor.services.embedding.client import reset_embedding_client
+    from deeptutor.services.llm.client import reset_llm_client
+
+    clear_llm_config_cache()
+    reset_llm_client()
+    reset_embedding_client()
+
+
+def load_ui_settings() -> dict[str, Any]:
+    settings_file = _settings_file()
+    if settings_file.exists():
+        try:
+            with open(settings_file, encoding="utf-8") as handle:
+                saved = json.load(handle)
+                # resolve_languages owns the legacy migration (a file predating
+                # the UI/response split inherits its one language into both).
+                merged = {**DEFAULT_UI_SETTINGS, **saved, **resolve_languages(saved)}
+                # Filter persisted enabled_optional_tools to current
+                # toggleable set so retired tool names can't leak into
+                # the per-turn payload.
+                merged["enabled_optional_tools"] = sanitize_enabled_tools(
+                    merged.get("enabled_optional_tools")
+                )
+                return merged
+        except Exception:
+            pass
+    return DEFAULT_UI_SETTINGS.copy()
+
+
+def save_ui_settings(settings: dict[str, Any]) -> None:
+    """Replace the whole stored UI settings document.
+
+    Writes through ``atomic_update`` rather than opening the file here, so this
+    module and the setup capability — which both write ``interface.json`` —
+    share one lock and one atomic replace. A lock held by only one of two
+    writers protects nothing: measured with the old direct write, six concurrent
+    router saves alongside six capability writes lost every one of the router's.
+
+    Prefer :func:`patch_ui_settings` for changing individual fields. This
+    replaces the whole document, so a caller that builds it from
+    ``load_ui_settings`` writes the merged defaults back as stored values and
+    stops following later changes to any of them.
+    """
+    payload = dict(settings)
+    atomic_update(_settings_file(), lambda _stored: payload)
+
+
+def patch_ui_settings(**fields: Any) -> None:
+    """Change individual UI fields without rewriting the rest of the document."""
+    atomic_update(_settings_file(), lambda stored: {**stored, **fields})
+
+
+def _require_settings_admin() -> None:
+    if not get_current_user().is_admin:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Model configuration is managed by an administrator.",
+        )
+
+
+def _require_codex_oauth_actor() -> None:
+    """Gate the Codex OAuth lifecycle: personal, not administrative.
+
+    Every one of these endpoints acts on the *caller's own* credentials —
+    ``get_codex_oauth_service()`` resolves the store, the model catalog, and
+    the callback route from owner scope — so requiring an administrator was
+    what left ordinary users unable to use Codex at all: an owner-bound
+    profile is (correctly) never grantable, and they could not sign in for
+    themselves either (#781).
+
+    A partner is refused: it is a synthetic user whose owner is a real
+    account, so letting one in would mean acting on that person's login —
+    including signing them out. Partners inherit the owner's login at call
+    time and need no lifecycle of their own.
+    """
+    from deeptutor.core.identities import is_partner_user_id
+
+    if is_partner_user_id(get_current_user().id):
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="A partner uses the Codex login of the account that owns it.",
+        )
+
+
+def _codex_http_exception(error: CodexAuthError) -> HTTPException:
+    return HTTPException(
+        status_code=error.http_status,
+        detail={
+            "code": error.code,
+            "message": error.public_message,
+        },
+    )
+
+
+def _provider_choices() -> dict[str, list[dict[str, Any]]]:
+    """Build dropdown options for provider selection, keyed by service type."""
+    from deeptutor.services.config.provider_runtime import (
+        DEPRECATED_SEARCH_PROVIDERS,
+        EMBEDDING_PROVIDERS,
+        IMAGEGEN_PROVIDERS,
+        SEARCH_PROVIDERS,
+        STT_PROVIDERS,
+        TTS_PROVIDERS,
+        VIDEOGEN_PROVIDERS,
+    )
+    from deeptutor.services.provider_registry import PROVIDERS
+
+    llm = sorted(
+        [
+            {
+                "value": s.name,
+                "label": (
+                    "Custom (OpenAI API)"
+                    if s.name == "custom"
+                    else "Custom (Anthropic API)"
+                    if s.name == "custom_anthropic"
+                    else s.label
+                ),
+                "base_url": s.default_api_base,
+                "auth_mode": s.auth_mode,
+                "supports_wire_api_selection": s.supports_wire_api_selection,
+                # Which protocols a profile on this vendor may pick, and the
+                # vendor endpoint each one lives at when that differs.
+                "api_formats": list(s.api_formats),
+                "default_api_format": s.default_api_format,
+                "base_urls": {
+                    api_format: s.default_api_base_for(api_format)
+                    for api_format in s.api_formats
+                    if s.default_api_base_for(api_format)
+                },
+                # Legacy entries stay resolvable for stored catalogs but are
+                # not offered for new profiles; the same thing is expressed
+                # today as a provider plus an API format.
+                "status": "legacy" if s.is_legacy else "supported",
+            }
+            for s in PROVIDERS
+        ],
+        key=lambda p: p["label"].lower(),
+    )
+    embedding = sorted(
+        [
+            {
+                "value": name,
+                "label": spec.label,
+                "base_url": spec.default_api_base,
+                "default_dim": str(spec.default_dim) if spec.default_dim else "",
+            }
+            for name, spec in EMBEDDING_PROVIDERS.items()
+            if name != "custom_openai_sdk"
+        ],
+        key=lambda p: p["label"].lower(),
+    )
+    # Derived from SEARCH_PROVIDERS so the dropdown, the connection-field form
+    # and the provider warnings the web app renders all follow the backend spec
+    # table. No search provider ships a default base_url — only SearXNG takes
+    # one, and it is the user's own instance.
+    search = [
+        {
+            "value": name,
+            "label": spec.label,
+            "base_url": "",
+            "requires_api_key": spec.requires_api_key,
+            "requires_base_url": spec.requires_base_url,
+            "soft_fallback": spec.soft_fallback,
+            "status": "supported",
+        }
+        for name, spec in SEARCH_PROVIDERS.items()
+    ]
+    # Retired providers ride along marked rather than offered, so a stale
+    # catalog can be told apart from a typo without a second name table in the
+    # web app. The dropdown filters them out; only the warning text uses them.
+    search += [
+        {
+            "value": name,
+            "label": name,
+            "base_url": "",
+            "requires_api_key": False,
+            "requires_base_url": False,
+            "soft_fallback": True,
+            "status": "deprecated",
+        }
+        for name in sorted(DEPRECATED_SEARCH_PROVIDERS)
+    ]
+    from deeptutor.services.voice.options import voice_options
+
+    tts = sorted(
+        [
+            {
+                "value": name,
+                "label": spec.label,
+                "base_url": spec.default_api_base,
+                "default_model": spec.default_model,
+                "default_voice": spec.default_voice,
+                "voice_options": voice_options(name, "tts"),
+            }
+            for name, spec in TTS_PROVIDERS.items()
+        ],
+        key=lambda p: p["label"].lower(),
+    )
+    stt = sorted(
+        [
+            {
+                "value": name,
+                "label": spec.label,
+                "base_url": spec.default_api_base,
+                "default_model": spec.default_model,
+                "voice_options": voice_options(name, "stt"),
+            }
+            for name, spec in STT_PROVIDERS.items()
+        ],
+        key=lambda p: p["label"].lower(),
+    )
+    imagegen = sorted(
+        [
+            {
+                "value": name,
+                "label": spec.label,
+                "base_url": spec.default_api_base,
+                "default_model": spec.default_model,
+            }
+            for name, spec in IMAGEGEN_PROVIDERS.items()
+        ],
+        key=lambda p: p["label"].lower(),
+    )
+    videogen = sorted(
+        [
+            {
+                "value": name,
+                "label": spec.label,
+                "base_url": spec.default_api_base,
+                "default_model": spec.default_model,
+            }
+            for name, spec in VIDEOGEN_PROVIDERS.items()
+        ],
+        key=lambda p: p["label"].lower(),
+    )
+    return {
+        "llm": llm,
+        # Same shape, same vendors: the task service stands in for the LLM.
+        "task": llm,
+        "embedding": embedding,
+        "search": search,
+        "tts": tts,
+        "stt": stt,
+        "imagegen": imagegen,
+        "videogen": videogen,
+    }
+
+
+def _match_service_provider(
+    provider: str,
+    table: dict[str, Any],
+) -> tuple[str, Any] | None:
+    """Find *provider*'s entry in one service's provider table.
+
+    Vendors are not named identically across tables — the LLM registry calls
+    Alibaba's endpoint ``dashscope`` while the embedding table calls it
+    ``aliyun`` — so an exact key miss falls back to the spec's own keywords
+    rather than to a second hand-maintained name map.
+    """
+    if provider in table:
+        return provider, table[provider]
+    for name, spec in table.items():
+        if provider in getattr(spec, "keywords", ()):
+            return name, spec
+    return None
+
+
+def _connection_targets() -> list[dict[str, Any]]:
+    """Which services one vendor credential can configure, and with what.
+
+    The connection UI needs to answer "if I paste an OpenRouter key here, what
+    does it get me?" — so this joins the six per-service provider tables on the
+    vendor and reports, per service, the provider value and the prefills a
+    profile created from that connection should start with. Derived rather than
+    duplicated: adding a vendor to a service table is enough to make it
+    connectable, and the web app never keeps a second copy of the tables.
+    """
+    from deeptutor.services.config.provider_runtime import (
+        EMBEDDING_PROVIDERS,
+        IMAGEGEN_PROVIDERS,
+        STT_PROVIDERS,
+        TTS_PROVIDERS,
+        VIDEOGEN_PROVIDERS,
+    )
+    from deeptutor.services.provider_registry import PROVIDERS
+
+    service_tables: dict[str, dict[str, Any]] = {
+        "embedding": {k: v for k, v in EMBEDDING_PROVIDERS.items() if k != "custom_openai_sdk"},
+        "tts": TTS_PROVIDERS,
+        "stt": STT_PROVIDERS,
+        "imagegen": IMAGEGEN_PROVIDERS,
+        "videogen": VIDEOGEN_PROVIDERS,
+    }
+
+    targets: list[dict[str, Any]] = []
+    for spec in PROVIDERS:
+        # OAuth vendors sign in through their own flow; there is no key to
+        # share, so offering them here would promise something untrue.
+        if spec.is_oauth:
+            continue
+        services: dict[str, dict[str, Any]] = {
+            "llm": {
+                "provider": spec.name,
+                "base_url": spec.default_api_base,
+                "default_model": "",
+            }
+        }
+        for service_name, table in service_tables.items():
+            match = _match_service_provider(spec.name, table)
+            if match is None:
+                continue
+            name, service_spec = match
+            entry: dict[str, Any] = {
+                "provider": name,
+                "base_url": service_spec.default_api_base,
+                "default_model": service_spec.default_model,
+            }
+            if service_name == "embedding":
+                entry["default_dim"] = (
+                    str(service_spec.default_dim) if service_spec.default_dim else ""
+                )
+            if service_name == "tts":
+                entry["default_voice"] = service_spec.default_voice
+            services[service_name] = entry
+        targets.append(
+            {
+                "provider": spec.name,
+                "label": (
+                    "Custom (OpenAI API)"
+                    if spec.name == "custom"
+                    else "Custom (Anthropic API)"
+                    if spec.name == "custom_anthropic"
+                    else spec.label
+                ),
+                "default_base_url": spec.default_api_base,
+                "services": services,
+            }
+        )
+    return sorted(targets, key=lambda item: str(item["label"]).lower())
+
+
+def _api_base_source(system: dict[str, Any]) -> str:
+    if system.get("next_public_api_base_external"):
+        return "next_public_api_base_external"
+    if system.get("next_public_api_base"):
+        return "next_public_api_base"
+    return "default_backend_url"
+
+
+def _network_settings_payload() -> dict[str, Any]:
+    service = get_runtime_settings_service()
+    file_system = service.load_system(include_process_overrides=False)
+    effective_system = service.load_system(include_process_overrides=True)
+    auth = service.load_auth(include_process_overrides=True)
+    backend_url = f"http://localhost:{effective_system['backend_port']}"
+    browser_api_base = (
+        effective_system["next_public_api_base_external"]
+        or effective_system["next_public_api_base"]
+        or backend_url
+    )
+    cors_origins = normalize_origins(
+        [effective_system["cors_origin"], effective_system["cors_origins"]]
+    )
+    auth_enabled = bool(auth["enabled"])
+    cookie_secure = bool(auth["cookie_secure"])
+    return {
+        "settings": {
+            "backend_port": file_system["backend_port"],
+            "frontend_port": file_system["frontend_port"],
+            "public_api_base": file_system["next_public_api_base_external"],
+            "cors_origins": normalize_origins(
+                [file_system["cors_origin"], file_system["cors_origins"]]
+            ),
+        },
+        "effective": {
+            "backend_url": backend_url,
+            "frontend_url": f"http://localhost:{effective_system['frontend_port']}",
+            "browser_api_base": browser_api_base,
+            "api_base_source": _api_base_source(effective_system),
+            "cors_mode": "explicit" if auth_enabled else "permissive",
+            "cors_origins": cors_origins,
+            "allow_remote_http_origins": not auth_enabled,
+        },
+        "auth": {
+            "enabled": auth_enabled,
+            "cookie_secure": cookie_secure,
+            "cookie_samesite": "none" if cookie_secure else "lax",
+            "cross_site_cookie_ready": bool(auth_enabled and cookie_secure),
+        },
+        "restart_required": True,
+    }
+
+
+@router.get("")
+async def get_settings():
+    user = get_current_user()
+    if not user.is_admin:
+        # Non-admins never see the catalog (provider URLs/keys); their model
+        # choices come from /settings/llm-options (grant-filtered).
+        return {"ui": load_ui_settings()}
+    from deeptutor.services.model_selection.tasks import task_kind_payload
+
+    return {
+        "ui": load_ui_settings(),
+        "catalog": redact_catalog_secrets(get_model_catalog_service().load()),
+        "providers": _provider_choices(),
+        "connection_targets": _connection_targets(),
+        # What actually runs on the background task model. The list comes from
+        # the call sites themselves (one TaskKind each), so the task models page
+        # cannot list a task DeepTutor no longer makes — or miss a new one.
+        "task_kinds": task_kind_payload(),
+    }
+
+
+@router.post("/providers/openai-codex/oauth/start")
+async def start_openai_codex_oauth() -> dict[str, Any]:
+    _require_codex_oauth_actor()
+    try:
+        return await get_codex_oauth_service().start_login()
+    except CodexAuthError as exc:
+        raise _codex_http_exception(exc) from None
+
+
+@router.get("/providers/openai-codex/oauth/status")
+async def get_openai_codex_oauth_status() -> dict[str, Any]:
+    _require_codex_oauth_actor()
+    try:
+        return get_codex_oauth_service().public_status()
+    except CodexAuthError as exc:
+        raise _codex_http_exception(exc) from None
+
+
+class CodexOAuthCallbackPayload(BaseModel):
+    callback_url: str
+
+
+@router.post("/providers/openai-codex/oauth/complete")
+async def complete_openai_codex_oauth(payload: CodexOAuthCallbackPayload) -> dict[str, Any]:
+    """Finish a waiting Codex login from a callback address the user pasted.
+
+    The provider redirects the browser to a loopback listener. In Docker that
+    listener lives in the container and the published ports do not include it,
+    so the browser shows a failed page while the sign-in waits forever
+    (#1252). This is the way back in without a tunnel: the address is parsed
+    for its OAuth result and discarded, and the exchange is the same one the
+    listener would have driven.
+    """
+    _require_codex_oauth_actor()
+    try:
+        return await get_codex_oauth_service().complete_login_with_callback_url(
+            payload.callback_url
+        )
+    except CodexAuthError as exc:
+        raise _codex_http_exception(exc) from None
+
+
+@router.post("/providers/openai-codex/oauth/cancel")
+async def cancel_openai_codex_oauth() -> dict[str, Any]:
+    _require_codex_oauth_actor()
+    try:
+        return await get_codex_oauth_service().cancel_login()
+    except CodexAuthError as exc:
+        raise _codex_http_exception(exc) from None
+
+
+@router.post("/providers/openai-codex/oauth/logout")
+async def logout_openai_codex_oauth() -> dict[str, Any]:
+    _require_codex_oauth_actor()
+    try:
+        return await get_codex_oauth_service().logout()
+    except CodexAuthError as exc:
+        raise _codex_http_exception(exc) from None
+
+
+@router.post("/providers/openai-codex/models/refresh")
+async def refresh_openai_codex_models() -> dict[str, Any]:
+    _require_codex_oauth_actor()
+    try:
+        return await get_codex_oauth_service().refresh_models()
+    except CodexAuthError as exc:
+        raise _codex_http_exception(exc) from None
+
+
+@router.get("/providers/codebuddy/auth/status")
+async def get_codebuddy_auth_status() -> dict[str, Any]:
+    _require_settings_admin()
+    return await get_codebuddy_auth_service().status()
+
+
+@router.post("/providers/codebuddy/auth/start")
+async def start_codebuddy_auth() -> dict[str, Any]:
+    _require_settings_admin()
+    return await get_codebuddy_auth_service().start_login()
+
+
+@router.post("/providers/codebuddy/auth/cancel")
+async def cancel_codebuddy_auth() -> dict[str, Any]:
+    _require_settings_admin()
+    return await get_codebuddy_auth_service().cancel_login()
+
+
+@router.post("/providers/codebuddy/auth/logout")
+async def logout_codebuddy_auth() -> dict[str, Any]:
+    _require_settings_admin()
+    return await get_codebuddy_auth_service().logout()
+
+
+@router.post("/providers/openai-codex/models/reasoning-effort")
+async def update_openai_codex_reasoning_effort(
+    payload: CodexReasoningEffortUpdate,
+) -> dict[str, Any]:
+    _require_codex_oauth_actor()
+    # The codex service writes the catalog the runtime resolves against, like
+    # every other catalog write here — unbracketed, the next turn would keep
+    # the old effort until something else happened to reset the clients.
+    with _runtime_catalog_write():
+        try:
+            status_payload = await get_codex_oauth_service().set_reasoning_effort(
+                payload.model,
+                payload.reasoning_effort,
+            )
+        except CodexAuthError as exc:
+            raise _codex_http_exception(exc) from None
+    return status_payload
+
+
+@router.get("/catalog")
+async def get_catalog():
+    _require_settings_admin()
+    return {"catalog": redact_catalog_secrets(get_model_catalog_service().load())}
+
+
+@router.get("/network")
+async def get_network_settings():
+    _require_settings_admin()
+    return _network_settings_payload()
+
+
+@router.put("/network")
+async def update_network_settings(payload: NetworkSettingsUpdate):
+    _require_settings_admin()
+    service = get_runtime_settings_service()
+    current = service.load_system(include_process_overrides=False)
+    service.save_system(
+        {
+            **current,
+            "backend_port": payload.backend_port,
+            "frontend_port": payload.frontend_port,
+            "next_public_api_base_external": payload.public_api_base.strip(),
+            "cors_origin": "",
+            "cors_origins": normalize_origins(payload.cors_origins),
+        }
+    )
+    return _network_settings_payload()
+
+
+def _chat_attachments_payload() -> dict[str, Any]:
+    service = get_runtime_settings_service()
+    stored = service.load_system(include_process_overrides=False)
+    effective = service.load_system(include_process_overrides=True)
+    max_total_bytes = int(effective["chat_attachment_max_total_mb"]) * 1024 * 1024
+    return {
+        "settings": {
+            "max_file_mb": stored["chat_attachment_max_file_mb"],
+            "max_total_mb": stored["chat_attachment_max_total_mb"],
+            "max_chars_per_doc": stored["chat_attachment_max_chars_per_doc"],
+            "max_chars_total": stored["chat_attachment_max_chars_total"],
+        },
+        "effective": {
+            "max_file_bytes": int(effective["chat_attachment_max_file_mb"]) * 1024 * 1024,
+            "max_total_bytes": max_total_bytes,
+            "max_chars_per_doc": effective["chat_attachment_max_chars_per_doc"],
+            "max_chars_total": effective["chat_attachment_max_chars_total"],
+            "ws_max_size": compute_ws_max_size(max_total_bytes),
+        },
+        "bounds": {
+            "max_file_mb": list(CHAT_ATTACHMENT_MAX_FILE_MB_RANGE),
+            "max_total_mb": list(CHAT_ATTACHMENT_MAX_TOTAL_MB_RANGE),
+            "chars": list(CHAT_ATTACHMENT_CHARS_RANGE),
+        },
+        # Size caps and char budgets are re-read on every message, but the WS
+        # frame ceiling is fixed at process start — uploads bigger than the
+        # old ceiling need a backend restart to actually go through.
+        "restart_required_for_larger_uploads": True,
+    }
+
+
+@router.get("/chat-attachments")
+async def get_chat_attachment_settings():
+    """Chat attachment policy. Readable by any user — the composer needs the
+    caps to gate file picks client-side; only the PUT is admin-gated."""
+    return _chat_attachments_payload()
+
+
+@router.get("/chat-starters")
+async def get_chat_starter_settings():
+    """How many recent activities shape the home screen's starting points.
+
+    Per user and not admin-gated, unlike the attachment caps next door: this
+    changes the size of one prompt built from the caller's own memory, not any
+    resource other people share.
+    """
+    from deeptutor.services.settings.starter_settings import (
+        TRACE_COUNT_RANGE,
+        get_starter_settings,
+    )
+
+    return {"settings": get_starter_settings(), "bounds": {"trace_count": TRACE_COUNT_RANGE}}
+
+
+@router.put("/chat-starters")
+async def update_chat_starter_settings(payload: ChatStarterSettingsUpdate):
+    from deeptutor.services.settings.starter_settings import (
+        TRACE_COUNT_RANGE,
+        save_starter_settings,
+    )
+
+    saved = save_starter_settings({"trace_count": payload.trace_count})
+    return {"settings": saved, "bounds": {"trace_count": TRACE_COUNT_RANGE}}
+
+
+@router.put("/chat-attachments")
+async def update_chat_attachment_settings(payload: ChatAttachmentSettingsUpdate):
+    _require_settings_admin()
+    service = get_runtime_settings_service()
+    current = service.load_system(include_process_overrides=False)
+    service.save_system(
+        {
+            **current,
+            "chat_attachment_max_file_mb": payload.max_file_mb,
+            "chat_attachment_max_total_mb": payload.max_total_mb,
+            "chat_attachment_max_chars_per_doc": payload.max_chars_per_doc,
+            "chat_attachment_max_chars_total": payload.max_chars_total,
+        }
+    )
+    return _chat_attachments_payload()
+
+
+def _mineru_settings_payload() -> dict[str, Any]:
+    """MinerU settings for the UI, with the API token redacted to a boolean.
+
+    ``local_cli`` is a fast PATH probe (no subprocess) so the page can show
+    install status at config time instead of failing at parse time; the
+    definitive ``--version`` check runs behind the explicit Test button.
+    """
+    from deeptutor.services.parsing.engines.mineru.backend import local_cli_probe
+
+    service = get_runtime_settings_service()
+    settings = service.load_mineru(include_process_overrides=True)
+    public = {key: value for key, value in settings.items() if key != "api_token"}
+    return {
+        "settings": public,
+        "api_token_set": bool(settings.get("api_token")),
+        "local_cli": local_cli_probe(str(settings.get("local_cli_path") or "")),
+    }
+
+
+def _document_parsing_payload() -> dict[str, Any]:
+    """State for the Document Parsing settings page: active engine, all engine
+    slices (MinerU token redacted), engine availability, and per-engine
+    readiness (so the UI can surface the "models not downloaded" gate)."""
+    from deeptutor.services.parsing.engines._install import (
+        installable_engines,
+        model_downloadable_engines,
+    )
+    from deeptutor.services.parsing.engines.factory import (
+        get_parser,
+        list_engines,
+    )
+    from deeptutor.services.parsing.engines.mineru.backend import local_cli_probe
+
+    service = get_runtime_settings_service()
+    full = service.load_document_parsing(include_process_overrides=True)
+    engines = full.get("engines", {})
+
+    redacted: dict[str, Any] = {}
+    for name, slice_ in engines.items():
+        clean = dict(slice_)
+        clean.pop("api_token", None)
+        redacted[name] = clean
+
+    readiness: dict[str, Any] = {}
+    available = list_engines()
+    for entry in available:
+        try:
+            parser = get_parser(entry["id"])
+            report = parser.is_ready(parser.resolve_config())
+            readiness[entry["id"]] = {
+                "ready": report.ready,
+                "reason": report.reason,
+                "message": report.message,
+            }
+        except Exception:  # pragma: no cover - defensive
+            continue
+
+    mineru_slice = engines.get("mineru", {})
+    docling_slice = engines.get("docling", {})
+    return {
+        "engine": full.get("engine"),
+        "image_caption": bool(full.get("image_caption", False)),
+        "image_description_model": full.get("image_description_model"),
+        "engines": redacted,
+        "available_engines": available,
+        "readiness": readiness,
+        # Engine ids that support one-click pip install / model download here.
+        "installable": sorted(installable_engines()),
+        "model_downloadable": sorted(model_downloadable_engines()),
+        # MinerU-specific UI state (token presence + CLI probe).
+        "mineru": {
+            "api_token_set": bool(mineru_slice.get("api_token")),
+            "local_cli": local_cli_probe(str(mineru_slice.get("local_cli_path") or "")),
+        },
+        # Docling UI state (token presence for remote mode).
+        "docling": {
+            "api_token_set": bool(docling_slice.get("api_token")),
+        },
+    }
+
+
+@router.get("/mineru")
+async def get_mineru_settings():
+    _require_settings_admin()
+    return _mineru_settings_payload()
+
+
+@router.put("/mineru")
+async def update_mineru_settings(payload: MinerUSettingsUpdate):
+    _require_settings_admin()
+    service = get_runtime_settings_service()
+    current = service.load_mineru(include_process_overrides=False)
+    # Tri-state token: None keeps the stored value, anything else replaces it.
+    token = current.get("api_token", "")
+    if payload.api_token is not None:
+        token = (
+            [value.strip() for value in payload.api_token if value.strip()]
+            if isinstance(payload.api_token, list)
+            else payload.api_token.strip()
+        )
+    service.save_mineru(
+        {
+            "mode": payload.mode,
+            "api_base_url": payload.api_base_url,
+            "api_token": token,
+            "local_cli_path": payload.local_cli_path,
+            "model_download_source": payload.model_download_source,
+            "model_download_endpoint": payload.model_download_endpoint,
+            "model_version": payload.model_version,
+            "language": payload.language,
+            "enable_formula": payload.enable_formula,
+            "enable_table": payload.enable_table,
+            "is_ocr": payload.is_ocr,
+            "max_pages_per_part": current.get("max_pages_per_part", 180),
+            "normalize_tiny_scans": current.get("normalize_tiny_scans", False),
+            "allow_local_model_download": payload.allow_local_model_download,
+        }
+    )
+    return _mineru_settings_payload()
+
+
+@router.get("/document-parsing")
+async def get_document_parsing_settings():
+    _require_settings_admin()
+    return _document_parsing_payload()
+
+
+@router.get("/readiness")
+async def get_settings_readiness():
+    """Return the value-free cross-setting capability readiness matrix."""
+
+    _require_settings_admin()
+    from deeptutor.services.config.readiness import build_settings_readiness
+
+    return await build_settings_readiness()
+
+
+@router.get("/profile")
+async def get_settings_profile():
+    """Export effective settings with credentials and deployment values removed."""
+
+    _require_settings_admin()
+    return export_settings_profile()
+
+
+@router.post("/profile/diff")
+async def diff_settings_profile(payload: SettingsProfileImportPayload):
+    """Review an imported profile without changing effective settings."""
+
+    _require_settings_admin()
+    try:
+        return review_settings_profile_import(payload.model_dump())
+    except SettingsProfileError as exc:
+        raise HTTPException(status.HTTP_422_UNPROCESSABLE_ENTITY, str(exc)) from None
+
+
+@router.get("/presets")
+async def get_settings_presets():
+    """List value-free starting points for a reviewable draft."""
+
+    _require_settings_admin()
+    return {
+        "schema_version": SETTINGS_PRESETS_SCHEMA_VERSION,
+        "presets": list_settings_presets(),
+    }
+
+
+async def _stage_settings_preset(
+    preset_id: str,
+    payload: SettingsPresetDraftRequest,
+) -> dict[str, Any]:
+    """Merge one preset into the unapplied draft; never touch live settings."""
+
+    preset = get_settings_preset(preset_id)
+    if preset is None:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, f"Unknown preset '{preset_id}'.")
+
+    draft_service = get_settings_draft_service()
+    stored = draft_service.load()
+    incoming = payload.model_dump()
+
+    # The browser sends its whole envelope, so unrelated unsaved edits survive.
+    # When a caller omits extensions, existing extension drafts must survive too.
+    extensions = deepcopy(stored.get("extensions") or {})
+    extensions.update(deepcopy(incoming.get("extensions") or {}))
+    incoming["extensions"] = extensions
+
+    merged = merge_draft_secrets(
+        incoming,
+        stored,
+        get_model_catalog_service().load(),
+    )
+    preset_draft = preset.draft_extensions()
+    tools = preset_draft["tools"]["enabled_tools"]
+    preset_draft["tools"]["enabled_tools"] = sanitize_enabled_tools(tools)
+    merged["extensions"].update(preset_draft)
+
+    return {
+        "preset": preset.public_dict(),
+        "draft": redact_draft(draft_service.save(merged)),
+    }
+
+
+@router.post("/presets/{preset_id}/draft")
+async def stage_settings_preset(
+    preset_id: str,
+    payload: SettingsPresetDraftRequest,
+) -> dict[str, Any]:
+    """Load a named preset into the existing draft for review."""
+
+    _require_settings_admin()
+    return await _stage_settings_preset(preset_id, payload)
+
+
+@router.put("/document-parsing")
+async def update_document_parsing_settings(payload: DocumentParsingUpdate):
+    _require_settings_admin()
+    service = get_runtime_settings_service()
+    full = service.load_document_parsing(include_process_overrides=False)
+    engines = {name: dict(slice_) for name, slice_ in full.get("engines", {}).items()}
+
+    for name, update in (payload.engines or {}).items():
+        if name not in engines:
+            continue
+        merged = dict(update or {})
+        # Token tri-state for engines with a secret (MinerU, Docling remote):
+        # omitted / None keeps the stored token; "" clears it; a string
+        # replaces it.
+        if "api_token" in (engines[name] or {}) and merged.get("api_token") is None:
+            merged.pop("api_token", None)
+        engines[name].update(merged)
+
+    new_engine = payload.engine or full.get("engine")
+    image_model = full.get("image_description_model")
+    if "image_description_model" in payload.model_fields_set:
+        image_model = (
+            payload.image_description_model.model_dump()
+            if payload.image_description_model is not None
+            else None
+        )
+        if image_model is not None:
+            from deeptutor.services.llm.image_description import resolve_image_description_config
+
+            try:
+                resolve_image_description_config(image_model)
+            except ValueError as exc:
+                raise HTTPException(status_code=400, detail=str(exc)) from exc
+    image_caption = (
+        payload.image_caption
+        if payload.image_caption is not None
+        else bool(full.get("image_caption", False))
+    )
+    service.save_document_parsing(
+        {
+            "engine": new_engine,
+            "image_caption": image_caption,
+            "image_description_model": image_model,
+            "engines": engines,
+        }
+    )
+    return _document_parsing_payload()
+
+
+@router.post("/document-parsing/test")
+async def test_document_parsing(payload: DocumentParsingTest):
+    """Readiness test for an engine. For MinerU's deeper checks (live cloud
+    token / CLI ``--version``) the UI uses ``/mineru/test``; this generic test
+    covers engine availability + model readiness for all engines."""
+    _require_settings_admin()
+    from deeptutor.services.parsing.engines.factory import get_parser, is_engine_available
+
+    service = get_runtime_settings_service()
+    engine = payload.engine or service.load_document_parsing().get("engine") or ""
+    if not is_engine_available(engine):
+        return {"ok": False, "message": f"The '{engine}' parsing engine isn't installed."}
+    try:
+        parser = get_parser(engine)
+        config = parser.resolve_config()
+        report = parser.is_ready(config)
+        # Remote engines get a live connectivity check (e.g. Docling Serve
+        # /health) rather than a config-only readiness gate.
+        verify = getattr(parser, "verify", None)
+        if verify is not None and report.ready and callable(verify):
+            ok, message = verify(config)
+            return {"ok": ok, "message": message or ("Ready to parse." if ok else "Not ready.")}
+    except Exception as exc:  # noqa: BLE001 - surface as a test result
+        return {"ok": False, "message": str(exc)}
+    return {
+        "ok": report.ready,
+        "message": report.message or ("Ready to parse." if report.ready else "Not ready."),
+    }
+
+
+@router.post("/document-parsing/docling/test")
+async def test_docling_remote_connection(payload: DoclingRemoteTest):
+    """Live connectivity check for the Docling remote-server draft values.
+    Pings the server health + version endpoints and returns ``ok`` + a
+    human-readable detail. Tests draft form values so the user can verify the
+    URL/key before saving; falls back to the stored key when the secret field
+    is untouched."""
+    _require_settings_admin()
+    from deeptutor.services.parsing.engines.docling.config import (
+        DoclingConfig,
+        resolve_docling_config,
+    )
+    from deeptutor.services.parsing.engines.docling.remote import verify_remote
+
+    stored = resolve_docling_config()
+    base_url = payload.api_base_url.strip().rstrip("/") or "http://localhost:5001"
+    token = stored.api_token if payload.api_token is None else payload.api_token.strip()
+    config = DoclingConfig(
+        mode="remote",
+        api_base_url=base_url,
+        api_token=token,
+        do_ocr=stored.do_ocr,
+        do_table_structure=stored.do_table_structure,
+    )
+    ok, detail = await asyncio.to_thread(verify_remote, config)
+    return {"ok": ok, "message": detail or ("Ready to parse." if ok else "Not ready.")}
+
+
+@router.post("/document-parsing/tika/test")
+async def test_tika_remote_connection(payload: TikaRemoteTest):
+    """Live connectivity check for the Tika server draft URL. Pings ``/version``
+    so the user can verify the URL before saving."""
+    _require_settings_admin()
+    from deeptutor.services.parsing.engines.tika.config import TikaConfig
+    from deeptutor.services.parsing.engines.tika.remote import verify_remote
+
+    server_url = payload.server_url.strip().rstrip("/") or "http://localhost:9998"
+    config = TikaConfig(server_url=server_url)
+    ok, detail = await asyncio.to_thread(verify_remote, config)
+    return {"ok": ok, "message": detail or ("Ready to parse." if ok else "Not ready.")}
+
+
+def _normalize_engine_name(name: str) -> str:
+    return (name or "").strip().lower().replace("-", "_").replace(" ", "_")
+
+
+@router.post("/document-parsing/install")
+async def start_document_parsing_install(payload: DocumentParsingInstall):
+    """Kick off a one-click ``pip install`` of an optional engine's package(s).
+
+    Returns ``{ok, message}`` immediately; progress is polled via the shared job
+    status endpoint. Only one job runs at a time (process-wide singleton). The
+    engine must be in the install allow-list (``ENGINE_PIP_SPECS``)."""
+    _require_settings_admin()
+    from deeptutor.services.parsing.engines._install import (
+        ENGINE_PIP_SPECS,
+        get_background_job_manager,
+    )
+
+    engine = _normalize_engine_name(payload.engine)
+    specs = ENGINE_PIP_SPECS.get(engine)
+    if not specs:
+        return {"ok": False, "message": f"No installable package for engine '{engine}'."}
+    return get_background_job_manager().start_install(engine=engine, specs=specs)
+
+
+@router.post("/document-parsing/models/download")
+async def start_document_parsing_model_download(payload: DocumentParsingInstall):
+    """Kick off a one-click model-weight download for an engine (e.g. Docling).
+
+    Runs the engine's downloader console script (``docling-tools models
+    download``) as a background subprocess; progress is polled via the shared job
+    status endpoint. The engine must be in ``ENGINE_MODEL_DOWNLOADERS`` and its
+    script reachable next to the server's python or on PATH."""
+    _require_settings_admin()
+    from deeptutor.services.parsing.engines._install import (
+        get_background_job_manager,
+        model_downloadable_engines,
+        resolve_model_downloader,
+    )
+
+    engine = _normalize_engine_name(payload.engine)
+    if engine not in model_downloadable_engines():
+        return {"ok": False, "message": f"No model download for engine '{engine}'."}
+    cmd = resolve_model_downloader(engine)
+    if not cmd:
+        return {
+            "ok": False,
+            "message": (
+                f"The {engine} model downloader wasn't found. Reinstall the engine "
+                f"(pip install deeptutor[parse-{engine}]) so its CLI is on PATH."
+            ),
+        }
+    return get_background_job_manager().start_model_download(engine=engine, cmd=cmd)
+
+
+@router.get("/document-parsing/job/status")
+async def document_parsing_job_status(cursor: int = 0):
+    _require_settings_admin()
+    from deeptutor.services.parsing.engines._install import get_background_job_manager
+
+    return get_background_job_manager().status(cursor)
+
+
+@router.post("/document-parsing/job/cancel")
+async def cancel_document_parsing_job():
+    _require_settings_admin()
+    from deeptutor.services.parsing.engines._install import get_background_job_manager
+
+    return get_background_job_manager().cancel()
+
+
+@router.post("/mineru/models/download")
+async def start_mineru_models_download(payload: MinerUModelDownloadPayload):
+    """Kick off a one-click model download via ``mineru-models-download``.
+
+    Returns ``{ok, message}`` immediately; progress is polled via the status
+    endpoint. Only one download runs at a time (process-wide singleton).
+    """
+    _require_settings_admin()
+    from deeptutor.services.parsing.engines.mineru.models import (
+        get_model_download_manager,
+        resolve_models_downloader,
+    )
+
+    resolved = resolve_models_downloader(payload.local_cli_path)
+    if not resolved["found"]:
+        if resolved["path"]:
+            message = (
+                f"mineru-models-download not found next to the configured CLI "
+                f"(expected {resolved['path']}). The configured install may be "
+                "legacy magic-pdf — upgrade to MinerU >= 3.4.5 for one-click downloads."
+            )
+        else:
+            message = (
+                "mineru-models-download not found on the server PATH. Install "
+                'current MinerU first (uv pip install -U "mineru[all]>=3.4.5") or set '
+                "the CLI path."
+            )
+        return {"ok": False, "message": message}
+
+    return get_model_download_manager().start(
+        downloader=resolved["path"],
+        model_type=payload.model_type,
+        source=payload.source,
+        endpoint=payload.endpoint,
+    )
+
+
+@router.get("/mineru/models/download/status")
+async def mineru_models_download_status(cursor: int = 0):
+    _require_settings_admin()
+    from deeptutor.services.parsing.engines.mineru.models import get_model_download_manager
+
+    return get_model_download_manager().status(cursor)
+
+
+@router.post("/mineru/models/download/cancel")
+async def cancel_mineru_models_download():
+    _require_settings_admin()
+    from deeptutor.services.parsing.engines.mineru.models import get_model_download_manager
+
+    return get_model_download_manager().cancel()
+
+
+@router.post("/mineru/test")
+async def test_mineru_connection(payload: MinerUSettingsUpdate):
+    """Validate the active backend. ``mode == "local"`` checks the CLI install
+    (PATH probe + ``--version``); cloud mode validates the token against the
+    live MinerU API (no parse quota consumed). Tests the draft form values so
+    the user can verify before saving; falls back to the stored token when the
+    secret field is untouched."""
+    _require_settings_admin()
+    from deeptutor.services.parsing.engines.mineru.cloud import verify_credentials
+    from deeptutor.services.parsing.engines.mineru.config import MinerUConfig, MinerUError
+
+    if payload.mode == "local":
+        from deeptutor.services.parsing.engines.mineru.backend import (
+            local_cli_probe,
+            local_cli_version,
+        )
+        from deeptutor.services.parsing.engines.mineru.formats import (
+            MIN_MINERU_VERSION,
+            mineru_version_is_current,
+        )
+
+        probe = local_cli_probe(payload.local_cli_path)
+        if not probe["found"]:
+            if probe.get("source") == "configured":
+                return {
+                    "ok": False,
+                    "message": (
+                        f"Configured CLI path is not an executable file: {probe['path']}. "
+                        "Fix the path or clear it to auto-detect from PATH."
+                    ),
+                }
+            return {
+                "ok": False,
+                "message": (
+                    "MinerU CLI not found on the server PATH. Install it "
+                    '(uv pip install -U "mineru[all]>=3.4.5"), set an explicit CLI path, '
+                    "or switch to cloud mode."
+                ),
+            }
+        # For a configured path, run --version against the path itself (the
+        # bare command name may not be on this process's PATH).
+        version_target = (
+            probe["path"] if probe.get("source") == "configured" else str(probe["command"])
+        )
+        version = await asyncio.to_thread(local_cli_version, version_target)
+        if not mineru_version_is_current(version):
+            detail = version or "an unknown version"
+            return {
+                "ok": False,
+                "message": (
+                    f"Local MinerU CLI reported {detail}. DeepTutor needs MinerU >= "
+                    f"{MIN_MINERU_VERSION}; upgrade with "
+                    f"`pip install -U 'mineru[all]>={MIN_MINERU_VERSION}'`."
+                ),
+            }
+        return {
+            "ok": True,
+            "message": f"Local MinerU CLI detected: {probe['command']} ({version})",
+        }
+
+    service = get_runtime_settings_service()
+    stored = service.load_mineru(include_process_overrides=False)
+    token = stored.get("api_token", "")
+    if payload.api_token is not None:
+        token = (
+            [value.strip() for value in payload.api_token if value.strip()]
+            if isinstance(payload.api_token, list)
+            else payload.api_token.strip()
+        )
+    config = MinerUConfig(
+        mode="cloud",
+        api_base_url=(payload.api_base_url or "").strip().rstrip("/") or "https://mineru.net",
+        api_token=token,
+        model_version=payload.model_version,
+        language=payload.language or "auto",
+        enable_formula=payload.enable_formula,
+        enable_table=payload.enable_table,
+        is_ocr=payload.is_ocr,
+    )
+    try:
+        await asyncio.to_thread(verify_credentials, config)
+    except MinerUError as exc:
+        return {"ok": False, "message": str(exc)}
+    except Exception as exc:  # noqa: BLE001 — report any provider error to the UI
+        logger.exception("MinerU connectivity test failed")
+        return {"ok": False, "message": f"Unexpected error: {exc}"}
+    return {"ok": True, "message": "MinerU API token is valid."}
+
+
+@router.get("/llm-options")
+async def get_llm_options():
+    if not get_current_user().is_admin:
+        return allowed_llm_options()
+    return list_llm_options(get_model_catalog_service().load())
+
+
+@router.put("/catalog")
+async def update_catalog(payload: CatalogPayload):
+    _require_settings_admin()
+    service = get_model_catalog_service()
+    current = service.load()
+    restored = restore_catalog_secrets(payload.catalog, current)
+    proposed = reconcile_codex_catalog_update(current, restored)
+    with _runtime_catalog_write():
+        catalog = service.save(proposed)
+    return {"catalog": redact_catalog_secrets(catalog)}
+
+
+@router.post("/apply/registry")
+async def apply_registry_edit(payload: RegistryEditPayload):
+    """Promote one provider, model, or default without replacing other drafts."""
+    _require_settings_admin()
+    from deeptutor.services.settings.registry_edit import merge_registry_edit
+
+    service = get_model_catalog_service()
+    draft_service = get_settings_draft_service()
+    stored = draft_service.load()
+    current = service.load()
+    edit = payload.model_dump(exclude_none=True)
+    try:
+        proposed = merge_registry_edit(current, edit, stored_draft=stored.get("catalog"))
+        proposed = reconcile_codex_catalog_update(current, proposed)
+        draft_catalog = stored.get("catalog")
+        if isinstance(draft_catalog, dict):
+            stored["catalog"] = merge_registry_edit(draft_catalog, edit, stored_draft=proposed)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    with _runtime_catalog_write():
+        service.apply(proposed)
+    catalog = service.load()
+    if stored.get("catalog") == catalog:
+        stored["catalog"] = None
+    if is_empty_draft(stored):
+        draft_service.clear()
+        public_draft = None
+    else:
+        public_draft = redact_draft(draft_service.save(stored))
+    return {"catalog": redact_catalog_secrets(catalog), "draft": public_draft}
+
+
+@router.post("/apply/provider")
+async def apply_provider_edit(payload: ProviderEditPayload):
+    """Save the provider on screen, preserving every unrelated live/draft entry."""
+    _require_settings_admin()
+    from deeptutor.services.settings.provider_edit import merge_provider_edit
+
+    service = get_model_catalog_service()
+    draft_service = get_settings_draft_service()
+    stored = draft_service.load()
+    current = service.load()
+    try:
+        proposed = merge_provider_edit(
+            current,
+            payload.service,
+            payload.profile,
+            connection=payload.connection,
+            active_model_id=payload.active_model_id,
+            activate=payload.activate,
+            stored_draft=stored.get("catalog"),
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    reconciled = reconcile_codex_catalog_update(current, proposed)
+    with _runtime_catalog_write():
+        service.apply(reconciled)
+    catalog = service.load()
+    draft_catalog = stored.get("catalog")
+    if isinstance(draft_catalog, dict):
+        # Advance only the addressed profile in a saved draft, preserving edits
+        # to its sibling providers and to all non-model settings.
+        saved_profile = next(
+            item
+            for item in catalog["services"][payload.service]["profiles"]
+            if item["id"] == payload.profile["id"]
+        )
+        saved_connection = next(
+            (
+                item
+                for item in catalog.get("connections", [])
+                if item["id"] == (payload.connection or {}).get("id")
+            ),
+            None,
+        )
+        stored["catalog"] = merge_provider_edit(
+            draft_catalog,
+            payload.service,
+            saved_profile,
+            connection=saved_connection,
+            activate=payload.activate,
+            active_model_id=payload.active_model_id,
+        )
+        if stored["catalog"] == catalog:
+            stored["catalog"] = None
+    if is_empty_draft(stored):
+        draft_service.clear()
+        public_draft = None
+    else:
+        public_draft = redact_draft(draft_service.save(stored))
+    return {"catalog": redact_catalog_secrets(catalog), "draft": public_draft}
+
+
+@router.post("/apply/service")
+async def apply_catalog_service(payload: CatalogServicePayload):
+    """Apply one model service while leaving every other draft untouched.
+
+    Provider dialogs use this narrower commit path for their Done action. A
+    user may still have unrelated edits elsewhere in Settings, and closing an
+    STT dialog must not silently promote those edits too.
+    """
+
+    _require_settings_admin()
+    service = get_model_catalog_service()
+    current = service.load()
+    draft_service = get_settings_draft_service()
+    stored_draft = draft_service.load()
+    proposed = deepcopy(current)
+    proposed.setdefault("services", {})[payload.service] = deepcopy(payload.config)
+    restored = restore_catalog_secrets(proposed, stored_draft.get("catalog") or current)
+    restored = restore_catalog_secrets(restored, current)
+    if payload.service == "task" and payload.config.get("mode") == "reference":
+        from deeptutor.services.model_selection import apply_llm_selection_to_catalog
+
+        try:
+            selection = payload.config.get("selection")
+            if not selection or not selection.get("profile_id") or not selection.get("model_id"):
+                raise ValueError("Choose a configured task model first.")
+            apply_llm_selection_to_catalog(restored, selection)
+        except (ValueError, AttributeError) as exc:
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
+    reconciled = reconcile_codex_catalog_update(current, restored)
+    with _runtime_catalog_write():
+        runtime = service.apply(reconciled)
+    catalog = service.load()
+
+    # A previously saved draft contains a full catalog. Keep it, but advance
+    # this one service to the value that is now live; otherwise reloading the
+    # page would resurrect the pre-apply STT configuration over the live one.
+    draft_catalog = stored_draft.get("catalog")
+    if isinstance(draft_catalog, dict):
+        draft_catalog.setdefault("services", {})[payload.service] = deepcopy(
+            catalog["services"][payload.service]
+        )
+        stored_draft["catalog"] = None if draft_catalog == catalog else draft_catalog
+
+    if is_empty_draft(stored_draft):
+        draft_service.clear()
+        public_draft = None
+    else:
+        public_draft = redact_draft(draft_service.save(stored_draft))
+
+    return {
+        "message": f"{payload.service} settings applied to runtime.",
+        "catalog": redact_catalog_secrets(catalog),
+        "draft": public_draft,
+        "runtime": runtime,
+    }
+
+
+@router.get("/draft")
+async def get_settings_draft():
+    """Return the unapplied draft, or nothing when there is none.
+
+    The draft is deliberately invisible to every other read path: nothing that
+    resolves runtime configuration looks here, which is the whole difference
+    between saving a draft and applying it.
+    """
+    draft = get_settings_draft_service().load()
+    if is_empty_draft(draft):
+        return {"draft": None}
+    return {"draft": redact_draft(draft)}
+
+
+@router.put("/draft")
+async def update_settings_draft(payload: SettingsDraftPayload):
+    if payload.catalog is not None:
+        _require_settings_admin()
+    service = get_settings_draft_service()
+    stored = service.load()
+    merged = merge_draft_secrets(
+        payload.model_dump(),
+        stored,
+        get_model_catalog_service().load(),
+    )
+    if is_empty_draft(merged):
+        service.clear()
+        return {"draft": None}
+    saved = service.save(merged)
+    return {"draft": redact_draft(saved)}
+
+
+@router.delete("/draft")
+async def discard_settings_draft():
+    get_settings_draft_service().clear()
+    return {"draft": None}
+
+
+@router.post("/apply")
+async def apply_catalog(payload: CatalogPayload | None = None):
+    """Move settings into the files the runtime reads, and clear the draft.
+
+    With no body this promotes the stored draft's catalog, which is how the
+    settings UI applies: credentials that only ever existed in a draft would
+    otherwise have to round-trip through the browser as placeholders and come
+    back resolving to the previous key.
+    """
+    _require_settings_admin()
+    service = get_model_catalog_service()
+    draft_service = get_settings_draft_service()
+    current = service.load()
+    if payload is not None:
+        proposed = restore_catalog_secrets(payload.catalog, current)
+    else:
+        draft_catalog = draft_service.load().get("catalog")
+        proposed = (
+            restore_catalog_secrets(draft_catalog, current)
+            if isinstance(draft_catalog, dict)
+            else current
+        )
+    catalog = reconcile_codex_catalog_update(current, proposed)
+    with _runtime_catalog_write():
+        applied = service.apply(catalog)
+    catalog_after = service.load()
+    draft_service.clear()
+    return {
+        "message": "Catalog applied to runtime settings.",
+        "catalog": redact_catalog_secrets(catalog_after),
+        "runtime": applied,
+    }
+
+
+@router.post("/test-provider")
+async def test_provider_connection(payload: ProviderProbePayload):
+    """Test current form credentials, resolving masks from draft/live settings by ID."""
+    _require_settings_admin()
+    from deeptutor.services.settings.provider_probe import probe_provider, probe_search_provider
+
+    current = get_model_catalog_service().load()
+    saved = get_settings_draft_service().load().get("catalog")
+    source = restore_catalog_secrets(saved, current) if isinstance(saved, dict) else current
+    fields = payload.model_dump()
+    if payload.connection_id:
+        fields["id"] = payload.connection_id
+        proposed = {"connections": [fields]}
+        resolved = restore_catalog_secrets(proposed, source)["connections"][0]
+    else:
+        fields["id"] = payload.profile_id
+        proposed = {"services": {payload.service: {"profiles": [fields]}}}
+        resolved = restore_catalog_secrets(proposed, source)["services"][payload.service][
+            "profiles"
+        ][0]
+    from deeptutor.services.keypool import primary_api_key
+
+    key = primary_api_key(resolved.get("api_key"))
+    headers = resolved.get("extra_headers") or {}
+    if isinstance(headers, str):
+        try:
+            headers = json.loads(headers)
+        except (ValueError, TypeError) as exc:
+            raise HTTPException(status_code=400, detail="Invalid extra headers JSON.") from exc
+    if not isinstance(headers, dict) or any(not isinstance(v, str) for v in headers.values()):
+        raise HTTPException(status_code=400, detail="Extra headers must contain text values.")
+    if (
+        (payload.api_key == CATALOG_SECRET_MASK and not key)
+        or key == CATALOG_SECRET_MASK
+        or any(v == CATALOG_SECRET_MASK for v in headers.values())
+    ):
+        raise HTTPException(
+            status_code=400, detail="Saved credentials were not found. Enter the key again."
+        )
+    if payload.service == "search":
+        return await probe_search_provider(
+            payload.binding, payload.base_url, key, proxy=payload.proxy
+        )
+    return await probe_provider(
+        payload.binding, payload.base_url, key, payload.api_format, headers, payload.api_version
+    )
+
+
+@router.post("/fetch-models")
+async def fetch_models_from_provider(payload: FetchModelsPayload):
+    """List selectable model IDs using the provider's own authentication.
+
+    Thin HTTP surface over ``factory.fetch_models`` so the settings UI can
+    populate a model picker. Copilot uses the caller's owner-private CLI login,
+    not the profile's API key or base URL.
+    """
+    _require_settings_admin()
+    from deeptutor.services.llm.factory import fetch_models as fetch_llm_models
+    from deeptutor.services.provider_registry import canonical_provider_name
+
+    base_url = (payload.base_url or "").strip()
+    binding = (payload.binding or "").strip().lower() or "openai"
+    is_copilot = canonical_provider_name(binding) == "github_copilot"
+    if not base_url and binding != "codebuddy" and not is_copilot:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="base_url is required for this provider.",
+        )
+
+    api_key = payload.api_key
+    api_format = (payload.api_format or "").strip().lower()
+    if is_copilot:
+        base_url, api_key, api_format = "", None, "auto"
+    elif payload.profile_id and (api_key == CATALOG_SECRET_MASK or not api_format):
+        service = get_model_catalog_service().load().get("services", {}).get(payload.service, {})
+        profile = next(
+            (item for item in service.get("profiles", []) if item.get("id") == payload.profile_id),
+            None,
+        )
+        if api_key == CATALOG_SECRET_MASK:
+            api_key = profile.get("api_key") if profile else None
+        if not api_format and profile:
+            api_format = str(profile.get("api_format") or "")
+
+    try:
+        model_ids = await fetch_llm_models(binding, base_url, api_key, api_format or "auto")
+    except Exception as exc:  # noqa: BLE001 — surface any provider error as 502
+        if is_copilot:
+            # OAuth exceptions can contain credential-bearing URLs or responses.
+            # Never echo or log their raw text at this public HTTP boundary.
+            raise HTTPException(
+                status_code=status.HTTP_502_BAD_GATEWAY,
+                detail=(
+                    "Could not list GitHub Copilot models. "
+                    "Run: deeptutor provider login github-copilot "
+                    "for this account in the server's DeepTutor home, "
+                    "then retry. If already logged in, check Copilot access and connectivity."
+                ),
+            ) from None
+        logger.exception("Failed to fetch models from %s", base_url)
+        raise HTTPException(
+            status_code=status.HTTP_502_BAD_GATEWAY,
+            detail=f"Provider request failed: {exc}",
+        ) from exc
+
+    return {"models": [{"id": model_id, "name": model_id} for model_id in model_ids]}
+
+
+@router.post("/model-capabilities")
+async def resolve_model_capabilities(payload: ModelCapabilitiesQuery):
+    """What the built-in capability tables assume for one provider/model pair.
+
+    The settings UI shows these as the value "Auto" resolves to next to each
+    per-model override, so a user can see what they are overriding.
+    """
+    _require_settings_admin()
+    from deeptutor.services.llm.capabilities import effective_capabilities
+
+    binding = (payload.binding or "").strip().lower() or "openai"
+    model = (payload.model or "").strip()
+    return {
+        "binding": binding,
+        "model": model,
+        "defaults": effective_capabilities(binding, model),
+    }
+
+
+@router.put("/theme")
+async def update_theme(update: ThemeUpdate):
+    patch_ui_settings(theme=update.theme)
+    return {"theme": update.theme}
+
+
+@router.put("/language")
+async def update_language(update: LanguageUpdate):
+    patch_ui_settings(language=update.language)
+    return {"language": update.language}
+
+
+@router.put("/voice-autoplay")
+async def update_voice_autoplay(update: VoiceAutoplayUpdate):
+    """Persist the global default for auto-playing chat replies via TTS.
+
+    A personal UI preference (any authenticated user); the chat surface layers
+    a per-session override on top of this value.
+    """
+    patch_ui_settings(voice_autoplay=update.voice_autoplay)
+    return {"voice_autoplay": update.voice_autoplay}
+
+
+@router.put("/voice-math-speak")
+async def update_voice_math_speak(update: VoiceMathSpeakUpdate):
+    """Persist whether TTS verbalizes LaTeX as spoken math.
+
+    A personal UI preference (any authenticated user). The voice router reads
+    this on each synthesis call; chat does not send a per-request override.
+    Dollar-sign delimiters are stripped even when this is off.
+    """
+    patch_ui_settings(voice_math_speak=update.voice_math_speak)
+    return {"voice_math_speak": update.voice_math_speak}
+
+
+@router.put("/chat-response-timeout")
+async def update_chat_response_timeout(update: ChatResponseTimeoutUpdate):
+    """Persist how long the chat UI waits for a turn event before timing out.
+
+    A personal UI preference (any authenticated user). Slow tools like image /
+    video generation can take longer than the old 60s default, so this is
+    user-adjustable; the chat surface reads it client-side.
+    """
+    patch_ui_settings(chat_response_timeout=update.chat_response_timeout)
+    return {"chat_response_timeout": update.chat_response_timeout}
+
+
+# The UI preferences a page can need before it knows who is asking. All three
+# describe the person's own presentation and output choices; none of them say
+# anything about how the deployment is configured.
+PRESESSION_UI_FIELDS = ("theme", "language", "response_language")
+
+
+@public_router.get("/ui")
+async def get_ui_settings():
+    """Return the pre-session UI preferences: theme and the two languages.
+
+    Public by design, which is why it is a narrow projection rather than the
+    saved ``ui`` blob. The app shell — and the statically prerendered auth
+    pages, which have no session at all — adopt the persisted languages here
+    during bootstrap. Theme rides along so those pages can paint in the right
+    one instead of flashing.
+
+    Everything else under ``ui`` (sidebar_nav_order, enabled_optional_tools,
+    chat_response_timeout, …) describes what the deployment has turned on, so
+    it stays behind auth: read it from the ``ui`` key of GET /settings.
+    """
+    settings = load_ui_settings()
+    return {field: settings.get(field) for field in PRESESSION_UI_FIELDS}
+
+
+# Private: user-authored starting prompts must never enter the public /ui payload.
+def _page_customization() -> PageCustomization:
+    return PageCustomization.model_validate(load_ui_settings().get("page_customization") or {})
+
+
+@router.get("/page-customization")
+async def get_page_customization():
+    return _page_customization().model_dump()
+
+
+def _save_page_section(section: str, value: BaseModel) -> dict[str, Any]:
+    def update(stored):
+        current = PageCustomization.model_validate(stored.get("page_customization") or {})
+        setattr(current, section, value)
+        return {**stored, "page_customization": current.model_dump()}
+
+    atomic_update(_settings_file(), update)
+    return _page_customization().model_dump()
+
+
+@router.put("/page-customization/chat")
+async def update_chat_page_customization(update: ChatPageCustomization):
+    return _save_page_section("chat", update)
+
+
+@router.put("/page-customization/learning")
+async def update_learning_page_customization(update: LearningPageCustomization):
+    return _save_page_section("learning", update)
+
+
+@router.put("/ui")
+async def update_ui_settings(update: UISettingsUpdate):
+    """Merge frontend partial update into current UI settings.
+
+    Uses exclude_unset=True semantics so that only fields explicitly provided
+    by the frontend override saved values. Fields not in the frontend payload
+    (even if they equal the model defaults) are omitted from the merge.
+    """
+    dump = update.model_dump(exclude_unset=True)  # Only merge explicitly provided fields
+    # Merged into the stored document, not into the defaults-merged view: saving
+    # that view back would freeze today's defaults as this user's explicit
+    # choices. The response keeps returning the merged view clients expect.
+    patch_ui_settings(**dump)
+    return load_ui_settings()
+
+
+@router.post("/reset")
+async def reset_settings():
+    save_ui_settings(DEFAULT_UI_SETTINGS)
+    return DEFAULT_UI_SETTINGS
+
+
+@router.get("/themes")
+async def get_themes():
+    return {
+        "themes": [
+            {"id": "snow", "name": "Default"},
+            {"id": "light", "name": "Cream"},
+            {"id": "dark", "name": "Dark"},
+            {"id": "glass", "name": "Glass"},
+        ]
+    }
+
+
+@router.get("/sidebar")
+async def get_sidebar_settings():
+    current_ui = load_ui_settings()
+    return {
+        "description": current_ui.get(
+            "sidebar_description", DEFAULT_UI_SETTINGS["sidebar_description"]
+        ),
+        "nav_order": current_ui.get("sidebar_nav_order", DEFAULT_UI_SETTINGS["sidebar_nav_order"]),
+    }
+
+
+@router.put("/sidebar/description")
+async def update_sidebar_description(update: SidebarDescriptionUpdate):
+    patch_ui_settings(sidebar_description=update.description)
+    return {"description": update.description}
+
+
+@router.put("/sidebar/nav-order")
+async def update_sidebar_nav_order(update: SidebarNavOrderUpdate):
+    patch_ui_settings(sidebar_nav_order=update.nav_order.model_dump())
+    return {"nav_order": update.nav_order.model_dump()}
+
+
+@router.put("/enabled-tools")
+async def update_enabled_tools(update: EnabledToolsUpdate):
+    sanitized = sanitize_enabled_tools(update.enabled_tools)
+    patch_ui_settings(enabled_optional_tools=sanitized)
+    return {"enabled_optional_tools": sanitized}
+
+
+@router.post("/voice/voices")
+async def list_voice_choices(payload: VoiceDiscoveryPayload):
+    """Read live account voices for a draft selection, without applying it."""
+    _require_settings_admin()
+    from deeptutor.services.voice.discovery import discover_voices
+
+    service = get_model_catalog_service()
+    current = service.load()
+    saved = get_settings_draft_service().load().get("catalog")
+    source = restore_catalog_secrets(saved, current) if isinstance(saved, dict) else current
+    catalog = service.resolve_connections(restore_catalog_secrets(payload.catalog, source))
+    try:
+        result = await discover_voices(catalog, payload.profile_id, payload.model_id)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    return Response(
+        json.dumps(result), media_type="application/json", headers={"Cache-Control": "no-store"}
+    )
+
+
+@router.post(
+    "/voice/preview",
+    response_class=Response,
+    responses={200: {"content": {"audio/wav": {}, "audio/mpeg": {}}}},
+)
+async def preview_voice(payload: VoicePreviewPayload) -> Response:
+    """Audition the model being edited without saving or activating its catalog."""
+    _require_settings_admin()
+    from deeptutor.services.voice.base import VoiceProviderError, VoiceProviderTimeout
+    from deeptutor.services.voice.preview import preview_failure_message, synthesize_preview
+
+    service = get_model_catalog_service()
+    current = service.load()
+    saved = get_settings_draft_service().load().get("catalog")
+    # Restore the saved draft against live first; a missing draft secret must
+    # not replace an incoming mask with None before live can resolve it.
+    source = restore_catalog_secrets(saved, current) if isinstance(saved, dict) else current
+    catalog = restore_catalog_secrets(payload.catalog, source)
+    catalog = service.resolve_connections(catalog)
+    try:
+        audio, content_type = await synthesize_preview(
+            catalog, payload.profile_id, payload.model_id, payload.text
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    except VoiceProviderTimeout as exc:
+        raise HTTPException(status_code=504, detail=str(exc)) from exc
+    except VoiceProviderError as exc:
+        raise HTTPException(
+            status_code=502,
+            detail=preview_failure_message(exc),
+        ) from exc
+    return Response(audio, media_type=content_type, headers={"Cache-Control": "no-store"})
+
+
+@router.post("/services/{service}/preview")
+async def preview_service(service: str, payload: ServicePreviewPayload):
+    """Stream a real result from the selected draft without applying it."""
+    _require_settings_admin()
+    from deeptutor.services.settings.service_preview import preview_events, validate_input
+    from deeptutor.services.voice.discovery import selected_catalog
+
+    try:
+        audio = validate_input(service, payload.text, payload.audio, payload.content_type)
+        catalog_service = get_model_catalog_service()
+        current = catalog_service.load()
+        saved = get_settings_draft_service().load().get("catalog")
+        source = restore_catalog_secrets(saved, current) if isinstance(saved, dict) else current
+        catalog = catalog_service.resolve_connections(
+            restore_catalog_secrets(payload.catalog, source)
+        )
+        selected_catalog(catalog, service, payload.profile_id, payload.model_id)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    async def stream():
+        async for event in preview_events(
+            catalog,
+            service,
+            payload.profile_id,
+            payload.model_id,
+            payload.text,
+            audio,
+            payload.content_type,
+        ):
+            yield json.dumps(event, ensure_ascii=False) + "\n"
+
+    return StreamingResponse(
+        stream(),
+        media_type="application/x-ndjson",
+        headers={"Cache-Control": "no-store", "X-Accel-Buffering": "no"},
+    )
+
+
+@router.post("/tests/{service}/start")
+async def start_service_test(service: str, payload: CatalogPayload | None = None):
+    _require_settings_admin()
+    catalog = None
+    if payload is not None:
+        catalog_service = get_model_catalog_service()
+        current = catalog_service.load()
+        saved = get_settings_draft_service().load().get("catalog")
+        catalog = (
+            restore_catalog_secrets(payload.catalog, saved)
+            if isinstance(saved, dict)
+            else payload.catalog
+        )
+        catalog = restore_catalog_secrets(catalog, current)
+        catalog = catalog_service.resolve_connections(catalog)
+    run = get_config_test_runner().start(service, catalog)
+    return {"run_id": run.id}
+
+
+@router.get("/tests/{service}/{run_id}/events")
+async def stream_service_test_events(service: str, run_id: str, request: Request):
+    _require_settings_admin()
+    runner = get_config_test_runner()
+    run = runner.get(run_id)
+
+    async def event_stream():
+        sent = 0
+        while True:
+            if await request.is_disconnected():
+                return
+            events = run.snapshot(sent)
+            if events:
+                for event in events:
+                    yield f"data: {json.dumps(event, ensure_ascii=False)}\n\n"
+                sent += len(events)
+                if events[-1]["type"] in {"completed", "failed"}:
+                    return
+            else:
+                yield "event: heartbeat\ndata: {}\n\n"
+            await asyncio.sleep(0.35)
+
+    return StreamingResponse(event_stream(), media_type="text/event-stream")
+
+
+@router.post("/tests/{service}/{run_id}/cancel")
+async def cancel_service_test(service: str, run_id: str):
+    _require_settings_admin()
+    get_config_test_runner().cancel(run_id)
+    return {"message": "Cancelled"}
+
+
+@router.get("/tour/status")
+async def tour_status():
+    tour_cache = _tour_cache_file()
+    if tour_cache.exists():
+        try:
+            cache = json.loads(tour_cache.read_text(encoding="utf-8"))
+            return {
+                "active": True,
+                "status": cache.get("status", "unknown"),
+                "launch_at": cache.get("launch_at"),
+                "redirect_at": cache.get("redirect_at"),
+            }
+        except Exception:
+            pass
+    return {"active": False, "status": "none", "launch_at": None, "redirect_at": None}
+
+
+class TourCompletePayload(BaseModel):
+    catalog: dict[str, Any] | None = None
+    test_results: dict[str, str] | None = None
+
+
+@router.post("/tour/complete")
+async def complete_tour(payload: TourCompletePayload | None = None):
+    _require_settings_admin()
+    service = get_model_catalog_service()
+    current = service.load()
+    catalog = (
+        restore_catalog_secrets(payload.catalog, current)
+        if payload and payload.catalog
+        else current
+    )
+    with _runtime_catalog_write():
+        applied = service.apply(catalog)
+    now = int(time.time())
+    launch_at = now + 3
+    redirect_at = now + 5
+
+    tour_cache = _tour_cache_file()
+    if tour_cache.exists():
+        try:
+            cache = json.loads(tour_cache.read_text(encoding="utf-8"))
+        except Exception:
+            cache = {}
+        cache["status"] = "completed"
+        cache["launch_at"] = launch_at
+        cache["redirect_at"] = redirect_at
+        if payload and payload.test_results:
+            cache["test_results"] = payload.test_results
+        tour_cache.write_text(json.dumps(cache, indent=2), encoding="utf-8")
+
+    return {
+        "status": "completed",
+        "message": "Configuration saved. DeepTutor will restart shortly.",
+        "launch_at": launch_at,
+        "redirect_at": redirect_at,
+        "runtime": applied,
+    }
+
+
+@router.post("/tour/reopen")
+async def reopen_tour():
+    return {
+        "message": "Run the terminal setup guide from the project root to re-open the guided setup.",
+        "command": "deeptutor init",
+    }
+
+
+@router.get("/usage", response_model=UsageStatistics)
+async def get_usage_statistics(
+    year: int = Query(..., ge=1970, le=9998),
+    timezone: str = Query("UTC", max_length=100),
+) -> UsageStatistics:
+    from datetime import datetime
+    from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+    from deeptutor.services.session import get_session_store
+    from deeptutor.services.session.usage_statistics import aggregate_usage
+
+    try:
+        zone = ZoneInfo(timezone)
+    except (ZoneInfoNotFoundError, ValueError) as exc:
+        raise HTTPException(status_code=400, detail="Invalid timezone") from exc
+    start = datetime(year, 1, 1, tzinfo=zone).timestamp()
+    end = datetime(year + 1, 1, 1, tzinfo=zone).timestamp()
+    from deeptutor.services.workspace import get_content_workspace_service
+    from deeptutor.services.workspace.activity import data_activity
+    from deeptutor.services.workspace.context import workspace_context
+    from deeptutor.services.workspace.models import WorkspaceError
+
+    records = []
+    with data_activity():
+        workspace_ids = [""] + [
+            row["workspace_id"]
+            for row in get_content_workspace_service()._catalog()
+            if row.get("kind") == "workspace"
+        ]
+        for workspace_id in workspace_ids:
+            try:
+                with workspace_context(workspace_id):
+                    records.extend(await get_session_store().usage_records(start, end))
+            except WorkspaceError:
+                continue
+    from deeptutor.services.llm.usage_ledger import combined_usage_records
+
+    combined = await asyncio.to_thread(combined_usage_records, records, start, end)
+    return await asyncio.to_thread(aggregate_usage, combined, year=year, timezone=timezone)