add uv as a parallel option alongside pip

uv is presented as the recommended faster, standards-compliant drop-in;
pip stays the baseline/fallback. uv command syntax verified against
docs.astral.sh/uv before writing.

environments.md:
- new 'uv (optional, faster)' section: install from pyproject
  (uv pip install . / -e . / '.[dev]'), the uv sync managed-venv flow,
  and a note that uv.lock is local-only/gitignored (not committed)
- pinning subsection: pin direct deps in pyproject via == or git @ref,
  with a warning that this pins direct deps only — transitive deps still
  float at build time (documented tradeoff)
- uv equivalents added beside pip in the Local .venv and Docker tabs

deploy.md:
- 'Faster builds with uv' tip: uv-from-ghcr COPY, ENV UV_COMPILE_BYTECODE=1,
  uv pip install --system . (reads pyproject, no lock)
- layer-caching shows the uv variant beside the pip one
- checklist notes uv pip install + UV_COMPILE_BYTECODE; fix stray 'configs'
  plural -> 'config'

.gitignore: ignore uv.lock (local-only, never committed).

Verified in-browser; mkdocs build --strict clean (anchors resolve).

Signed-off-by: disqualifier <dev@disqualifier.me>

docs/environments.md

@@ -21,7 +21,14 @@ happens, depending on where the project runs:
     ```bash
     python -m venv .venv          # create it (once)
     source .venv/bin/activate     # activate for this shell
-    pip install -r requirements.txt
+    pip install -e .              # install the project from pyproject.toml
+    ```
+
+    Or with [uv](#uv-optional-faster) — same `pyproject.toml`, much faster:
+
+    ```bash
+    uv venv                       # create .venv
+    uv pip install -e .           # install from pyproject.toml
     ```
 
     Keep `.venv/` **gitignored** — it's per-machine, never committed.
@@ -55,13 +62,14 @@ happens, depending on where the project runs:
 
     ```dockerfile
     FROM python:3.12-slim
-    COPY requirements.txt .
-    RUN pip install --no-cache-dir -r requirements.txt
+    COPY pyproject.toml .
+    RUN pip install --no-cache-dir .    # or: uv pip install .
     COPY . .
     ```
 
     This is how things run in production — see the [Deploy guide](deploy.md) for the
-    full container standard (uid 1337, mounts, layer caching).
+    full container standard (uid 1337, mounts, layer caching, and the uv image
+    setup).
 
 !!! tip "Which one?"
     **Local `.venv`** for quick iteration, **Makefile** when you want repeatable
@@ -69,6 +77,51 @@ happens, depending on where the project runs:
     exclusive — a project often has a `.venv` for local dev *and* a Dockerfile for
     deploy.
 
+## uv (optional, faster)
+
+!!! tip "uv is the recommended fast path; pip stays the baseline"
+    [uv](https://docs.astral.sh/uv/) is a faster, standards-compliant drop-in for
+    pip. It reads the **same `pyproject.toml`** — no workflow change required, and
+    `pip` keeps working exactly as before. Use it wherever you'd reach for pip; the
+    rest of this handbook shows the pip command with the uv equivalent beside it.
+
+Install deps straight from `pyproject.toml` (no `requirements.txt` needed):
+
+```bash
+uv pip install .            # install the project + its deps
+uv pip install -e .         # editable (dev) install
+uv pip install '.[dev]'     # with an extras group, e.g. dev
+```
+
+If you'd rather have uv manage the venv for you, use the managed-venv flow:
+
+```bash
+uv sync                     # create/refresh .venv from pyproject.toml + uv.lock
+uv run python -m yourapp    # run inside the managed env, no manual activate
+```
+
+!!! note "`uv.lock` is local-only — never committed"
+    `uv sync` writes a `uv.lock` for your machine's resolved environment. It is
+    **gitignored**, not committed — we don't ship a lockfile. Pinning happens in
+    `pyproject.toml` (below), not the lock.
+
+### Pinning deps
+
+Pin **direct** dependencies in `pyproject.toml` with `==` or a git `@ref`:
+
+```toml
+[project]
+dependencies = [
+    "requests==2.31.0",
+    "mylib @ git+https://git.rethinkstudios.io/rethink-public/mylib.git@<sha>",
+]
+```
+
+!!! warning "This pins direct deps only — transitive deps still float"
+    `==` / `@ref` pins the packages **you** list. Their dependencies still resolve
+    fresh at build time. That's an accepted tradeoff — documented on purpose — not
+    an oversight: we pin what we depend on directly and let the rest float.
+
 ## Local dev with pyenv
 
 For local work you also need the right **Python version**, not just isolated deps.