feat: scaffold Brain of Reese — FastAPI RAG chat over Postgres 17 + pgvector

Foundation (phase 01, verified):
- FastAPI app: /api/health, /api/suggestions, /api/chat (placeholder),
  static frontend served locally (no CDN)
- Postgres 17 + pgvector via db/Containerfile + compose.yaml
  (podman compose up -d db), Alembic initial migration (documents,
  chunks with vector(768), query_log)
- LLM client targeting https://aipi.reeseapps.com/v1 (turbo/embed);
  scripts/llm_probe.py verified models + 768-dim embeddings live
- Conditional debugpy: imported only when DEBUGPY=1 (attach on demand,
  :5678); logging config for clean single-line logs
- Frontend shell: mobile-first chat + Sources pages, tokens, a11y baselines
- Tests: 24 unit+integration (99% coverage on app/), ruff + pyright clean,
  Playwright smoke E2E (3 tests) against a deterministic mock LLM
- Planning: .agent/PLAN.md (architecture + LOCKED decisions), AGENTS.md,
  6 user stories, 7 phase files (one story / one phase / one Playwright
  suite each)

app/core/__init__.py

@@ -0,0 +1 @@
+"""Core utilities (debugging, logging)."""

app/core/debugging.py

@@ -0,0 +1,64 @@
+"""Conditional remote debugging via ``debugpy``.
+
+**Default (``DEBUGPY`` unset or ``0``):** ``debugpy`` is *never imported* —
+zero overhead, production-safe.
+
+**``DEBUGPY=1``:** imports ``debugpy`` and opens a *non-blocking* listener on
+``0.0.0.0:5678`` (override with ``DEBUGPY_PORT``). The application continues
+immediately; an IDE (VS Code / PyCharm) attaches on demand at any time.
+
+Usage: call :func:`configure_debugging` once, as early as possible in the
+entrypoint (see ``app/main.py``).
+"""
+from __future__ import annotations
+
+import contextlib
+import logging
+import os
+from typing import Any
+
+logger = logging.getLogger("app.debugging")
+
+_listener: Any = None  # debugpy.listen() result, when enabled
+
+
+def _port() -> int:
+    try:
+        return int(os.environ.get("DEBUGPY_PORT", "5678"))
+    except ValueError:
+        return 5678
+
+
+def _is_enabled() -> bool:
+    return os.environ.get("DEBUGPY", "0").strip() == "1"
+
+
+def configure_debugging() -> bool:
+    """Enable debugpy if and only if ``DEBUGPY=1``.
+
+    Returns ``True`` when the listener was started.
+    """
+    if not _is_enabled():
+        return False
+
+    global _listener
+
+    import debugpy  # imported ONLY when explicitly enabled — no overhead otherwise
+
+    port = _port()
+    _listener = debugpy.listen(("0.0.0.0", port))
+    logger.warning(
+        "debugpy: remote debugging ENABLED, listening on 0.0.0.0:%d (attach on demand)", port
+    )
+    return True
+
+
+def shutdown_debugpy() -> None:
+    """Stop the debugpy listener (used by tests and graceful shutdown)."""
+    global _listener
+    if _listener is not None:
+        sock = getattr(_listener, "local_socket", None)
+        if sock is not None:
+            with contextlib.suppress(OSError):
+                sock.close()
+        _listener = None

app/core/logging.py

@@ -0,0 +1,26 @@
+"""Logging configuration.
+
+Human-readable, timestamped, single-line records on stdout. Every
+request-critical operation (retrieval, LLM calls, imports) logs key=value
+context at INFO level so a user is never left wondering what the system is
+doing — this pairs with the UI's loading/progress feedback (see PLAN §UI/UX).
+"""
+from __future__ import annotations
+
+import logging
+import sys
+
+_FORMAT = "%(asctime)s %(levelname)-8s %(name)s :: %(message)s"
+_DATEFMT = "%Y-%m-%d %H:%M:%S"
+
+
+def configure_logging(level: str = "INFO") -> None:
+    root = logging.getLogger()
+    root.setLevel(level.upper())
+    handler = logging.StreamHandler(sys.stdout)
+    handler.setFormatter(logging.Formatter(_FORMAT, _DATEFMT))
+    root.handlers = [handler]
+
+    # Keep third-party noise down while our own loggers stay verbose.
+    for noisy in ("httpx", "httpcore", "openai", "urllib3"):
+        logging.getLogger(noisy).setLevel(logging.WARNING)