diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7435e3e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,131 @@
+# Video Shader
+
+Native video shader host with an OpenGL/DeckLink render path, Slang shader packages, and a local React control UI.
+
+The app loads shader packages from `shaders/`, compiles Slang to GLSL at runtime, renders a configurable layer stack, and exposes a browser-based control surface over a local HTTP/WebSocket server.
+
+## Repository Layout
+
+- `apps/LoopThroughWithOpenGLCompositing/`: native C++ host app.
+- `shaders/`: shader packages, each with `shader.json` and `shader.slang`.
+- `ui/`: Vite/React control UI.
+- `config/runtime-host.json`: runtime configuration.
+- `runtime/templates/`: tracked shader wrapper templates.
+- `runtime/`: ignored generated runtime cache/state output. See `runtime/README.md`.
+- `tests/`: focused native tests for pure runtime logic.
+- `.gitea/workflows/ci.yml`: Gitea Actions CI for Windows native tests and Ubuntu UI build.
+
+## Requirements
+
+- Windows with Visual Studio 2022 C++ tooling.
+- CMake 3.24 or newer.
+- Node.js and npm for the control UI.
+- Blackmagic DeckLink SDK 16.0 with the NVIDIA GPUDirect sample files available locally.
+- Slang compiler available under the repo/tooling paths expected by the runtime, or otherwise discoverable by the existing app setup.
+
+The Blackmagic/GPUDirect SDK should not be committed to this repository. `CMakeLists.txt` exposes `GPUDIRECT_DIR` as a cache path so local machines and CI runners can point at their installed SDK location.
+
+Default expected SDK path:
+
+```text
+3rdParty/Blackmagic DeckLink SDK 16.0/Win/Samples/NVIDIA_GPUDirect
+```
+
+Override example:
+
+```powershell
+cmake --preset vs2022-x64-debug -DGPUDIRECT_DIR="D:/SDKs/Blackmagic DeckLink SDK 16.0/Win/Samples/NVIDIA_GPUDirect"
+```
+
+## Build
+
+Configure and build the native app:
+
+```powershell
+cmake --preset vs2022-x64-debug
+cmake --build --preset build-debug
+```
+
+Build the React control UI:
+
+```powershell
+cd ui
+npm ci
+npm run build
+```
+
+The native app serves `ui/dist` when it exists, otherwise it falls back to the source UI directory during development.
+
+## Tests
+
+Run native tests:
+
+```powershell
+cmake --build --preset build-debug --target RUN_TESTS
+```
+
+Run the UI production build check:
+
+```powershell
+cd ui
+npm run build
+```
+
+Current native test coverage includes:
+
+- JSON parsing and serialization.
+- Parameter normalization and preset filename safety.
+- Shader manifest parsing and package registry scanning.
+
+## Runtime Configuration
+
+`config/runtime-host.json` controls host behavior:
+
+```json
+{
+  "shaderLibrary": "shaders",
+  "serverPort": 8080,
+  "autoReload": true,
+  "maxTemporalHistoryFrames": 12,
+  "enableExternalKeying": true
+}
+```
+
+The control UI is available at:
+
+```text
+http://127.0.0.1:<serverPort>
+```
+
+## Shader Packages
+
+Each shader package lives under:
+
+```text
+shaders/<id>/
+  shader.json
+  shader.slang
+```
+
+See `SHADER_CONTRACT.md` for the manifest schema, parameter types, texture assets, temporal history support, and the Slang entry point contract.
+
+## Generated Files
+
+Runtime-generated files are intentionally ignored:
+
+- `runtime/shader_cache/active_shader_wrapper.slang`
+- `runtime/shader_cache/active_shader.raw.frag`
+- `runtime/shader_cache/active_shader.frag`
+- `runtime/runtime_state.json`
+- `runtime/stack_presets/*.json`
+
+Only `runtime/templates/` and `runtime/README.md` are tracked.
+
+## CI
+
+The Gitea workflow expects two act runners:
+
+- `windows-latest`: builds the native app and runs native tests.
+- `nubuntu-latest`: installs UI dependencies and runs the Vite build.
+
+If your Windows runner stores the Blackmagic SDK outside the repo, configure `GPUDIRECT_DIR` in the runner environment or adjust the workflow configure command to pass `-DGPUDIRECT_DIR=...`.