docs: developer documentation, ADRs, CI fixes

.github/workflows/ci.yml

@@ -29,16 +29,21 @@ jobs:
       - name: Install linting tools
         run: |
           python -m pip install --upgrade pip
-          pip install ruff black isort
+          pip install ruff black
 
       - name: Lint with Ruff
         run: ruff check src/ tests/ --output-format=github
 
       - name: Check formatting with Black
         run: black --check --diff src/ tests/
 
-      - name: Check import sorting with isort
-        run: isort --check-only --diff src/ tests/ --profile black -p medex
+      # Note: import sorting is handled by ruff's "I" rule (I001).
+      # A standalone isort step was removed because ruff and isort
+      # disagree on aliased imports (e.g., `from x import Y as Z`),
+      # creating an unresolvable conflict where neither tool accepts
+      # the other's output. Ruff's isort implementation is the
+      # industry-standard replacement. See:
+      # https://docs.astral.sh/ruff/faq/#how-does-ruffs-import-sorting-compare-to-isort
 
   # =========================================================================
   # REQUIRED: Stable tests — files with 100% pass rate

CONTRIBUTING.md

@@ -7,10 +7,18 @@ Thank you for your interest in contributing to MedeX! This document provides gui
 - [Code of Conduct](#code-of-conduct)
 - [Getting Started](#getting-started)
 - [Development Setup](#development-setup)
+- [Docker Setup](#docker-setup)
+- [Environment Variables](#environment-variables)
+- [Running the UI (Reflex)](#running-the-ui-reflex)
 - [Making Changes](#making-changes)
 - [Pull Request Process](#pull-request-process)
 - [Coding Standards](#coding-standards)
 - [Testing](#testing)
+- [Troubleshooting](#troubleshooting)
+
+> **Full reference:** See [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) for the
+> complete development environment guide with API reference, project structure,
+> and advanced configuration.
 
 ## 📜 Code of Conduct
 
@@ -28,12 +36,12 @@ This project adheres to a Code of Conduct. By participating, you are expected to
 1. **Fork the repository** on GitHub
 2. **Clone your fork** locally:
    ```bash
-   git clone https://github.com/YOUR_USERNAME/Med-X-KimiK2-RAG.git
-   cd Med-X-KimiK2-RAG
+   git clone https://github.com/YOUR_USERNAME/MedX.git
+   cd MedX
    ```
 3. **Add the upstream remote**:
    ```bash
-   git remote add upstream https://github.com/DeepRatAI/Med-X-KimiK2-RAG.git
+   git remote add upstream https://github.com/DeepRatAI/MedX.git
    ```
 
 ## 💻 Development Setup
@@ -42,7 +50,8 @@ This project adheres to a Code of Conduct. By participating, you are expected to
 
 - Python 3.10+
 - Git
-- A Moonshot/Kimi API key (for testing)
+- Docker & Docker Compose (optional, for full-stack development)
+- A Moonshot/Kimi API key (optional, only needed for LLM features)
 
 ### Environment Setup
 
@@ -73,6 +82,51 @@ pytest tests/ --cov=src/medex --cov-report=html
 pytest tests/test_detection.py -v
 ```
 
+## 🐳 Docker Setup
+
+```bash
+# Full stack (API + UI + infrastructure)
+docker compose up --build -d
+
+# API only
+docker compose up api -d
+
+# Rebuild after code changes
+docker compose up --build -d
+
+# View logs
+docker compose logs -f api
+```
+
+## 🔑 Environment Variables
+
+Create a `.env` file in the project root:
+
+```env
+# Required for LLM features
+KIMI_API_KEY=your_kimi_api_key_here
+
+# Optional
+HF_TOKEN=your_huggingface_token       # For embedding models
+DATABASE_URL=postgresql+asyncpg://...  # Defaults to SQLite
+REDIS_URL=redis://localhost:6379/0     # For caching
+QDRANT_URL=http://localhost:6333       # For vector store
+MEDEX_ENV=development                  # development | test | production
+MEDEX_LOG_LEVEL=DEBUG                  # DEBUG | INFO | WARNING | ERROR
+```
+
+> **Note:** Medical tools (drug interactions, dosage calculator, lab interpreter,
+> triage) work without any API keys — they use local databases.
+
+## 🖥️ Running the UI (Reflex)
+
+```bash
+cd ui
+reflex init    # First time only
+reflex run --env dev
+# UI available at http://localhost:3000
+```
+
 ## ✏️ Making Changes
 
 ### Branch Naming
@@ -265,6 +319,35 @@ When adding medical content:
 4. **Add appropriate disclaimers**
 5. **Review with medical professionals** when possible
 
+## 🔧 Troubleshooting
+
+**Import errors after install:**
+```bash
+pip install -e . --no-deps
+pip install -r requirements.txt
+```
+
+**Port already in use:**
+```bash
+lsof -i :8000  # API
+lsof -i :3000  # UI
+kill -9 <PID>
+```
+
+**Pre-commit hook failures:**
+```bash
+black src/ tests/ && ruff check --fix src/ tests/
+git add -u && git commit
+```
+
+**Database connection errors:**
+```bash
+# Use SQLite (no setup needed):
+unset DATABASE_URL
+# Or check if Postgres is running:
+docker compose ps postgres
+```
+
 ## ❓ Questions?
 
 - Open an issue for bugs or feature requests

Dockerfile

@@ -56,8 +56,9 @@ ENV PYTHONDONTWRITEBYTECODE=1 \
     MEDEX_UI_PORT=3000
 
 # Install runtime dependencies only
+# Note: libgl1-mesa-glx was renamed to libgl1 in Debian Trixie (python:3.12-slim)
 RUN apt-get update && apt-get install -y --no-install-recommends \
-    libgl1-mesa-glx \
+    libgl1 \
     libglib2.0-0 \
     libsm6 \
     libxext6 \