feat(setup): first-boot detection + setup-mode gating + one-time token (epic 6a)

- app_state gains configured + setup_token_hash (migration 0025); existing installs (any users)
  are marked configured so they never see the wizard, a fresh DB starts in setup mode.
- On first boot the app mints a one-time setup token and logs the wizard URL (only the hash is
  stored); the token gates the setup steps (added in 6c).
- A middleware locks all /api + /auth routes (except /api/setup, /api/version, /healthz, static)
  to 503 until configured, with a DB-free cached fast-path once setup completes.
- GET /api/setup/status tells the SPA whether to show the wizard.

backend/app/state.py

@@ -1,5 +1,7 @@
-"""Global admin-controlled app state (e.g. pausing background sync)."""
+"""Global admin-controlled app state (e.g. pausing background sync, first-run setup)."""
+import hashlib
 import logging
+import secrets
 
 from sqlalchemy.orm import Session
 
@@ -12,6 +14,10 @@ log = logging.getLogger("subfeed.state")
 MAINTENANCE_BATCH_MIN = 100
 MAINTENANCE_BATCH_MAX = 100_000
 
+# Once configuration completes in this process it never reverts, so cache it to skip the per-request
+# DB hit in the setup-mode gate (see main.setup_gate). Starts False; refreshed from the DB.
+_configured_cache = False
+
 
 def _row(db: Session) -> AppState:
     row = db.get(AppState, 1)
@@ -34,6 +40,62 @@ def set_sync_paused(db: Session, paused: bool) -> None:
     log.info("Background sync %s", "paused" if paused else "resumed")
 
 
+# --- First-run install wizard ------------------------------------------------------------
+
+def is_configured(db: Session) -> bool:
+    return _row(db).configured
+
+
+def setup_complete() -> bool:
+    """Fast, DB-free check for the request gate: True once configuration finished this process."""
+    return _configured_cache
+
+
+def is_configured_cached(db: Session) -> bool:
+    """Configured check that promotes the module cache once true (configuration is one-way)."""
+    global _configured_cache
+    if _configured_cache:
+        return True
+    if is_configured(db):
+        _configured_cache = True
+    return _configured_cache
+
+
+def mark_configured(db: Session) -> None:
+    """Finish setup: flip the instance to configured and invalidate the setup token."""
+    global _configured_cache
+    row = _row(db)
+    row.configured = True
+    row.setup_token_hash = None
+    db.add(row)
+    db.commit()
+    _configured_cache = True
+    log.info("Instance marked configured; setup wizard disabled.")
+
+
+def _hash_token(raw: str) -> str:
+    return hashlib.sha256(raw.encode()).hexdigest()
+
+
+def rotate_setup_token(db: Session) -> str:
+    """Generate a fresh one-time setup token, persist only its hash, and return the raw token
+    (logged at startup so the admin can open the wizard)."""
+    raw = secrets.token_urlsafe(24)
+    row = _row(db)
+    row.setup_token_hash = _hash_token(raw)
+    db.add(row)
+    db.commit()
+    return raw
+
+
+def check_setup_token(db: Session, raw: str | None) -> bool:
+    """Whether `raw` matches the stored setup-token hash (constant-time)."""
+    if not raw:
+        return False
+    stored = _row(db).setup_token_hash
+    return stored is not None and secrets.compare_digest(stored, _hash_token(raw))
+
+
 def get_maintenance_batch(db: Session) -> int:
     """Effective maintenance re-validation batch: the admin override if set, else the
     env/config default."""