phase: 91_admin_theme_tab

All verification is complete — this pass needed no code changes. Final report:

**Phase 91 — Admin Theme tab: final verification pass (all 6 tasks already in `complete/`)**

- Verified pre-paint theming end-to-end: `ui_settings` store + resolver, admin `GET/PUT /api/ui-settings`, `CachingMiddleware` inline-`<style id="bor-theme">` injection before `</head>` (incl. `/shared/<token>` prefix branch, unit-pinned), CSP sha256 exemption for the inline tag, Theme tab shell + `theme.js` editor, CSS-file theming fully retired.
- No defects found; zero changes made — working tree left exactly as the task executors left it.
- Tests: `uv run pytest --cov=app` → 1841 passed, 0 failed (TOTAL coverage **99%**; theming/ui_settings/caching all 100%); `uv run pytest tests/e2e/test_admin_theme_tab.py -v --no-cov` → **5 passed** in isolation.
- Lint/types: `uv run ruff check .` → All checks passed; `uv run pyright` → 0 errors, 0 warnings.
- Criteria: (1) unset deployment byte-identical, no `#bor-theme` anywhere — ✓ (unit no-op test + E2E reset byte-compare); `rg "BOR_THEME|themes/"` → single hit is the permitted doc-history comment in `frontend/index.html`. (2) admin-only gate + 403s for anonymous and token users — ✓ (E2E test 3). (3) saved theme inline before `</head>` on every page incl. `/shared/<token>`, computed `--brand` on first paint for admin + anonymous — ✓ (E2E test 2 + unit). (4) reset → byte-identical; 5 contrast pairs warn <4.5:1, non-blocking — ✓ (E2E tests 4–5). (5) suite green, >90% coverage, lint clean — ✓. (6) commit deferred to harness per rules.
- Notable: `.agents/PLAN.md` is absent from the repo — the phase overview's Design section was used as the binding spec; no deviation resulted.
- Next pending phase: **none** — 91 is the last phase in `todo/`.

app/api/config.py

@@ -1,12 +1,27 @@
 """Public app metadata (display name + version) for the frontend brand
 layer, the phase-59 docs-push flag (the "Save as doc" gating), and the
-phase-62 UI customization strings (composer placeholder, footer line,
-theme file name)."""
+phase-62 UI customization strings (composer placeholder, footer line).
+
+Phase 91 (task 01): the three UI strings are now the EFFECTIVE values —
+the ``ui_settings`` row (admin Theme tab) over the env values (B1: DB
+wins when set, env is the fallback), resolved by the SAME
+:func:`app.core.theming.effective_settings` resolver the
+``/api/ui-settings`` API uses, so the brand layer and the tab can never
+disagree. The route opens a short-lived session (the sync-endpoint
+house pattern — the route is sync, matching the middleware world).
+
+Phase 91 (task 03): the retired CSS-file theming's ``theme`` key is
+deleted with the mechanism — the five keys below are the entire
+contract (the colors never rode this endpoint; the server injects
+them pre-paint, :mod:`app.core.theming`).
+"""
 from __future__ import annotations
 
 from fastapi import APIRouter, Depends
 
 from app.config import Settings, get_settings
+from app.core import theming
+from app.db import SessionLocal
 
 router = APIRouter(tags=["config"])
 
@@ -15,17 +30,25 @@ router = APIRouter(tags=["config"])
 def app_config(settings: Settings = Depends(get_settings)) -> dict[str, str | bool]:  # noqa: B008
     """Public app metadata for the frontend brand layer (phase 39) +
     the phase-59 ``docs_repo_configured`` flag + the phase-62 UI
-    customization keys (``input_placeholder``, ``footer_text``,
-    ``theme``) — all display strings, the SAME boot fetch (no new
-    network surface) and the same public posture as ``app_name``
-    (no secrets). Values are passed through verbatim: the frontend
-    brand layer treats an empty string as "keep the template default"
-    (the unset => byte-identical contract)."""
+    customization keys (``input_placeholder``, ``footer_text``) — all
+    display strings, the SAME boot fetch (no new network surface) and
+    the same public posture as ``app_name`` (no secrets). Phase 91:
+    ``app_name`` / ``input_placeholder`` / ``footer_text`` are the
+    EFFECTIVE values (the admin Theme tab's ``ui_settings`` row over
+    the env values — DB-over-env, B1); the frontend brand layer treats
+    an empty string as "keep the template default" (the unset =>
+    byte-identical contract). Phase 91 (task 03): the retired
+    CSS-file theming's ``theme`` key is gone — the five keys are the
+    entire response."""
+    db = SessionLocal()
+    try:
+        effective = theming.effective_settings(db, settings)
+    finally:
+        db.close()
     return {
-        "app_name": settings.app_name,
+        "app_name": effective["app_name"],
         "version": settings.app_version,
         "docs_repo_configured": settings.docs_configured,
-        "input_placeholder": settings.input_placeholder,
-        "footer_text": settings.footer_text,
-        "theme": settings.theme,
+        "input_placeholder": effective["input_placeholder"],
+        "footer_text": effective["footer_text"],
     }

app/api/ui_settings.py

@@ -0,0 +1,137 @@
+"""UI settings admin API (phase 91, task 01).
+
+The persistence surface of the admin Theme tab (the tab itself lands in
+tasks 04/05): the single ``ui_settings`` row (id 1) that stores what the
+admin sets — the app name, input placeholder, footer text, and the 8
+identity colors. The whole router sits behind
+:func:`app.core.auth.require_admin` (router-wide ``dependencies`` — the
+:mod:`app.api.tokens` pattern): anonymous callers AND token users get
+403 on every route (only the admin themes the deployment).
+
+Routes (under ``/api`` via the ``main`` registration):
+
+* ``GET /api/ui-settings`` — the EFFECTIVE values (the resolver's
+  DB-over-env / DB-over-built-in merge, B1): a missing row reports the
+  env strings + the built-in palette, so a fresh tab shows the live
+  theme. Creates nothing.
+* ``PUT /api/ui-settings`` — a FULL replacement of the row: each
+  string is trimmed (empty → NULL, >300 → 422 naming the field), each
+  color must match ``^#[0-9a-fA-F]{6}$`` (lowercased on store, else 422
+  naming the field), and — the owner-locked normalization — a color
+  equal to its built-in is stored as NULL, so "save the defaults"
+  leaves the row empty and the served HTML stays byte-identical (the
+  no-op injection contract, task 02). Upserts the id-1 row (SELECT →
+  update-or-insert); a concurrent PUT is single-admin — last writer
+  wins. Returns the new effective values.
+"""
+from __future__ import annotations
+
+import re
+
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from app.config import Settings, get_settings
+from app.core import theming
+from app.core.auth import require_admin
+from app.db import get_db
+from app.models import UiSettings
+from app.schemas import UiSettingsIn, UiSettingsOut
+
+router = APIRouter(
+    prefix="/ui-settings",
+    tags=["ui-settings"],
+    dependencies=[Depends(require_admin)],  # phase 91: the Theme tab is admin-only
+)
+
+#: The ``#rrggbb`` shape the color pickers produce (case-insensitive;
+#: lowercased on store so the stored/tagged hex is canonical).
+_HEX_COLOR = re.compile(r"^#[0-9a-fA-F]{6}$")
+#: The strings' column length (mirrors ``ui_settings`` VARCHAR(300)).
+_MAX_STRING_LEN = 300
+
+
+def _validate_strings(payload: UiSettingsIn) -> dict[str, str | None]:
+    """Trim the 3 display strings: empty after the trim → ``None``
+    (the clear operation), >300 chars after the trim → 422 naming the
+    field (the house fixed-detail style — the detail never varies by
+    value beyond naming the field)."""
+    values: dict[str, str | None] = {}
+    for field in theming.STRING_FIELDS:
+        raw = getattr(payload, field)
+        if raw is None:
+            values[field] = None
+            continue
+        value = raw.strip()
+        if len(value) > _MAX_STRING_LEN:
+            raise HTTPException(
+                status_code=422, detail=f"{field} is too long (max 300)"
+            )
+        values[field] = value or None
+    return values
+
+
+def _validate_colors(payload: UiSettingsIn) -> dict[str, str | None]:
+    """Validate + normalize the 8 identity colors: strict ``#rrggbb``
+    (else 422 naming the field), lowercased on store, and a value equal
+    to its BUILT-IN is stored as ``None`` — the owner-locked
+    normalization that keeps "save the defaults" byte-identical (the
+    row stays empty, the no-op injection contract)."""
+    values: dict[str, str | None] = {}
+    for field in theming.COLOR_FIELDS:
+        raw = getattr(payload, field)
+        if raw is None:
+            values[field] = None
+            continue
+        if _HEX_COLOR.fullmatch(raw) is None:
+            raise HTTPException(
+                status_code=422, detail=f"{field} must be a #rrggbb hex color"
+            )
+        value = raw.lower()
+        values[field] = None if value == theming.BUILTIN_COLORS[field] else value
+    return values
+
+
+@router.get("", response_model=UiSettingsOut)
+def get_ui_settings(
+    settings: Settings = Depends(get_settings),  # noqa: B008
+    db: Session = Depends(get_db),  # noqa: B008
+) -> UiSettingsOut:
+    """The effective UI settings — DB-over-env / DB-over-built-in (B1).
+
+    Reads only: a missing row means "defaults" (the env strings + the
+    built-in palette), so a fresh deployment's tab shows the live theme
+    with an empty row, and nothing is ever upserted by a read.
+    """
+    return UiSettingsOut(**theming.effective_settings(db, settings))
+
+
+@router.put("", response_model=UiSettingsOut)
+def update_ui_settings(
+    payload: UiSettingsIn,
+    settings: Settings = Depends(get_settings),  # noqa: B008
+    db: Session = Depends(get_db),  # noqa: B008
+) -> UiSettingsOut:
+    """Replace the single row with the body's 11 values (validated and
+    normalized — see the module docstring), then report the new
+    effective values.
+
+    Upsert on the id-1 row (SELECT → update-or-insert; the Python-side
+    ``default=1`` supplies the PK on the insert). Concurrency is
+    single-admin (one owner, one tab) — the last writer wins and no
+    lock is taken: a lost race just means the other admin's PUT is the
+    effective one.
+    """
+    strings = _validate_strings(payload)
+    colors = _validate_colors(payload)
+    row = db.execute(select(UiSettings).where(UiSettings.id == 1)).scalars().first()
+    if row is None:
+        row = UiSettings(id=1)
+        db.add(row)
+    for field in theming.STRING_FIELDS:
+        setattr(row, field, strings[field])
+    for field in theming.COLOR_FIELDS:
+        setattr(row, field, colors[field])
+    db.commit()
+    return UiSettingsOut(**theming.effective_settings(db, settings))