diff --git a/README.md b/README.md
new file mode 100644
index 0000000..cfcce9a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,89 @@
+# MXL Multiviewer
+
+Small Vulkan/SDL3 multiviewer for test feeds and MXL SDK video flows.
+
+## Dependencies
+
+Install:
+
+- CMake 3.20+
+- C++20 compiler
+- Vulkan loader and headers
+- Vulkan driver for the target GPU
+- SDL3 development package with `pkg-config` support
+- `glslangValidator`
+
+On Ubuntu/Debian-like systems the packages are usually similar to:
+
+```bash
+sudo apt install cmake g++ pkg-config libvulkan-dev vulkan-tools glslang-tools libsdl3-dev
+```
+
+Check that the discrete GPU is visible:
+
+```bash
+vulkaninfo --summary
+```
+
+## Build Without MXL SDK
+
+This builds synthetic feeds, SMPTE bars, and no-signal mode:
+
+```bash
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build -j
+```
+
+Run a synthetic v210 test grid:
+
+```bash
+./build/mxl_multiviewer --perf --grid 4x4 v210 v210 v210 v210 v210 v210 v210 v210 v210
+```
+
+## Build With MXL SDK
+
+Set `MXL_SDK_ROOT` to the SDK checkout/root that contains `lib/include` and `build/Linux-Clang-Release/lib`:
+
+```bash
+cmake -S . -B build-sdk \
+  -DCMAKE_BUILD_TYPE=Release \
+  -DMXL_MULTIVIEWER_ENABLE_MXL_SDK=ON \
+  -DMXL_SDK_ROOT=/path/to/mxl-sdk
+
+cmake --build build-sdk -j
+```
+
+Run with an existing feed config:
+
+```bash
+./build-sdk/mxl_multiviewer --perf --grid 4x4 --config /tmp/feeds_config.json
+```
+
+Useful probe flags:
+
+```bash
+--v210-upload-worker
+--adaptive-feed-texture
+--v210-staging-memory default|cached|device-local
+```
+
+Example:
+
+```bash
+./build-sdk/mxl_multiviewer \
+  --adaptive-feed-texture \
+  --v210-upload-worker \
+  --perf \
+  --grid 4x4 \
+  --config /tmp/feeds_config.json
+```
+
+## Notes
+
+- Run from the repository root or keep the `shaders/` directory next to the executable path expected by the app.
+- If SDL opens on the wrong GPU/session, try running from the desktop session attached to the discrete GPU and confirm with `vulkaninfo --summary`.
+- `v210_test` is a CPU-side conversion sanity check:
+
+```bash
+./build/v210_test
+```