fix: docs formatting and snippet refactor

CONTRIBUTING.md

@@ -40,12 +40,6 @@ Most tests run in a few seconds and don't need a GPU or model weights. Tests tha
 
 If you are contributing on an Apple Silicon Mac, there are a few extra things to be aware of.
 
-**`uv.lock` drift:** Running `uv run pytest` on macOS regenerates `uv.lock` with macOS-specific dependency markers. **Do not commit this file.** Before staging your changes, always run:
-
-```bash
-git restore uv.lock
-```
-
 **Selecting the compute backend:** CorridorKey auto-detects MPS on Apple Silicon. To test with the MLX backend or force CPU, set the environment variable before running:
 
 ```bash

docs/_snippets/dev-commands.md

@@ -0,0 +1,5 @@
+```bash
+uv run pytest                # run all tests
+uv run ruff check            # check for lint errors
+uv run ruff format --check   # check formatting (no changes)
+```

docs/_snippets/dev-setup.md

@@ -0,0 +1,7 @@
+```bash
+git clone https://github.com/nikopueringer/CorridorKey.git
+cd CorridorKey
+uv sync --group dev    # installs all dependencies + dev tools (pytest, ruff)
+```
+
+No manual virtualenv creation, no `pip install` — uv handles everything.

docs/ai-assisted-development.md

@@ -59,11 +59,7 @@ with inference code, compositing math, or EXR pipeline work.
 Get a working dev environment and point your AI assistant at the
 project context — this works with any tool.
 
-```bash
-git clone https://github.com/nikopueringer/CorridorKey.git
-cd CorridorKey
-uv sync --group dev    # installs all dependencies + dev tools
-```
+--8<-- "docs/_snippets/dev-setup.md"
 
 Once the repo is cloned, open `AGENTS.md` in your AI assistant as
 the first step. It gives the assistant the project layout, key
@@ -72,11 +68,7 @@ context, also point it at `docs/LLM_HANDOVER.md`.
 
 Core dev commands to keep handy:
 
-```bash
-uv run pytest                # run all tests
-uv run ruff check            # check for lint errors
-uv run ruff format --check   # check formatting (no changes)
-```
+--8<-- "docs/_snippets/dev-commands.md"
 
 ---
 

docs/contributing.md

@@ -28,14 +28,7 @@ this codebase, including PR contributions.
 
 ## Dev Setup
 
-```bash
-git clone https://github.com/nikopueringer/CorridorKey.git
-cd CorridorKey
-uv sync --group dev    # installs all dependencies + dev tools (pytest, ruff)
-```
-
-That's it. No manual virtualenv creation, no `pip install` — uv handles
-everything.
+--8<-- "docs/_snippets/dev-setup.md"
 
 ---
 
@@ -61,16 +54,6 @@ automatically if no GPU is available.
 If you are contributing on an Apple Silicon Mac, there are a few extra things to
 be aware of.
 
-### `uv.lock` Drift
-
-Running `uv run pytest` on macOS regenerates `uv.lock` with macOS-specific
-dependency markers. **Do not commit this file.** Before staging your changes,
-always run:
-
-```bash
-git restore uv.lock
-```
-
 ### Backend Selection
 
 CorridorKey auto-detects MPS on Apple Silicon. To test with the MLX backend or

docs/index.md

@@ -9,6 +9,8 @@ these colors, and even modern "AI Roto" solutions typically output a harsh
 binary mask, destroying the delicate semi-transparent pixels needed for a
 realistic composite.
 
+![CorridorKey comparison](https://github.com/user-attachments/assets/1fb27ea8-bc91-4ebc-818f-5a3b5585af08)
+
 CorridorKey solves this *unmixing* problem. You input a raw green screen frame,
 and the neural network completely separates the foreground object from the green
 screen. For every single pixel — even highly transparent ones like motion blur

zensical.toml

@@ -54,6 +54,8 @@ scheme = "slate"
 toggle.icon = "lucide/moon"
 toggle.name = "Switch to light mode"
 
+[project.markdown_extensions.attr_list]
+[project.markdown_extensions.md_in_html]
 [project.markdown_extensions.admonition]
 [project.markdown_extensions.pymdownx.details]
 [project.markdown_extensions.pymdownx.superfences]