docs: Add DEVELOPMENT

docs/DEVELOPMENT.md

@@ -0,0 +1,54 @@
+# Development Guide
+
+This guide outlines how to set up the development environment for this project, prioritizing **reproducible builds**, **environment parity**, and **cross-hardware compatibility**.
+
+## Reproducibility &uv
+
+This project uses [uv](https://github.com/astral-sh/uv) to manage dependencies and virtual environments. The `uv.lock` file is the absolute source of truth for package versions and must always be committed.
+
+### Source of Truth
+
+- **Never modify `uv.lock` manually.**
+- To add a dependency, run `uv add <package>`.
+- To update dependencies, run `uv lock --upgrade`.
+- To sync your environment with the lockfile, run `uv sync --frozen`.
+
+## Devcontainer Setup (Recommended)
+
+The devcontainer provides an identical experience to local development but with all system dependencies pre-configured. It automatically detects your hardware (GPU vs CPU) and syncs the appropriate dependencies.
+
+### Prerequisites
+
+- Docker Desktop or Docker Engine.
+- [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) (for GPU support).
+
+### Setup for VS Code
+
+1. Install the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension.
+2. Open the project and click **Reopen in Container**.
+3. On first launch, the `post-create.sh` script will:
+   - Detect if an NVIDIA GPU is available via `nvidia-smi`.
+   - Run `uv sync --frozen --extra cuda` if a GPU is found.
+   - Run `uv sync --frozen` otherwise.
+4. The environment is stored in a **named volume** for `.venv` to ensure persistence and performance.
+
+### Setup for JetBrains IDEs
+
+1. The IDE will detect the `.devcontainer/devcontainer.json` file.
+2. The environment is pre-configured to point to `/workspaces/project/.venv`.
+3. The hardware-aware sync will run automatically during container creation.
+
+## Local Development (Alternative)
+
+If you prefer not to use Docker:
+1. Install [uv](https://docs.astral.sh/uv/getting-started/installation/).
+2. Run `uv sync --frozen` (CPU) or `uv sync --frozen --extra cuda` (GPU).
+
+## Hardware Acceleration (JAX)
+
+Verify your setup by running:
+
+```bash
+python -c "import jax; print(jax.devices())"
+```
+In the devcontainer, this will report a `GpuDevice` if a GPU is detected and the `cuda` extra was installed.