diff --git a/docs/build.md b/docs/build.md
index f5eeb3768..07478d984 100644
--- a/docs/build.md
+++ b/docs/build.md
@@ -1,392 +1,169 @@
 # Build Guide
 
-This document describes how to build Oak Video Editor from source on Windows, Linux, and macOS.
+This document describes how to build the Oak Video Editor from source on
+macOS, Linux, and Windows. For the Chinese version see
+[`zh/build.md`](zh/build.md).
 
-> **Note (2026):** Oak is now a Rust workspace; `cargo build` at the
-> repository root produces the app, the CLI and the worker
-> (`liboakengine` — the plugin/external-consumer cdylib — is not a
-> default member, M14 R4; build it explicitly with
-> `cargo build -p oakengine`). The CMake instructions below are kept for
-> historical
-> reference only. Rust dependencies are pulled from crates.io; the only
-> native libraries still needed are FFmpeg (see the next section),
-> OpenColorIO (optional; `ocio-sys` builds a stub without it) and a
-> C/C++ toolchain for the FFI shims.
->
-> ### FFmpeg for the Rust build
->
-> `ffmpeg-next` 9.x pairs with FFmpeg 8.x headers, which most distros do
-> not ship yet. Build a project-owned FFmpeg — GPL parts enabled, every
-> free-license external codec library that is installed, per-OS hardware
-> acceleration, static+PIC — with the project scripts:
->
-> ```sh
-> tooling/install-deps.sh           # Homebrew / MSYS2 UCRT64 / Debian / Fedora / Arch
-> tooling/ffmpeg/build-ffmpeg.sh    # clones release/8.0, installs into .cache/ffmpeg
-> cargo build
-> ```
->
-> `FFMPEG_DIR` no longer needs exporting: the committed
-> `.cargo/config.toml` sets it relative to the workspace root (the
-> ffmpeg-sys-next build script cannot read `.env` files — this is the
-> only machine-agnostic way).
->
-> External libraries are probed with `pkg-config` and silently skipped
-> when missing. `FFMPEG_DIR` is mandatory (the `oakffmpeg-link` build
-> script panics without it): silently binding a system FFmpeg risks
-> stale `.pc` paths after package upgrades. IDEs that cannot inject
-> environment variables into cargo (RustRover) can instead put
-> `FFMPEG_DIR=...` (and `PKG_CONFIG_PATH=...` where needed) into a
-> `.env` file at the workspace root — it is git-ignored.
-> ffmpeg-next's `build` cargo feature is deliberately not used: it
-> clones release/<crate-version>, and every such pairing is broken
-> upstream (9.0.0 → FFmpeg 9.0 removed AVCodec fields; 8.1.0 → FFmpeg
-> 8.1 added enum variants; 8.0.0 → FFmpeg 8.0 renamed FF_PROFILE_*).
-
-## Prerequisites
-
-- CMake 3.20+
-- Ninja (recommended)
-- Qt 6 (with private headers)
-- FFmpeg 6.0+ development libraries
-- OpenTimelineIO (0.16+, built from source below — no distro package on most platforms)
-- OpenImageIO
-- OpenColorIO (2.x)
-- OpenEXR
-- Expat
-- PortAudio
-- OpenGL headers
-- Vulkan SDK (optional, required for the Vulkan render backend)
-- XKB common (Linux)
+> **2026 note:** Oak is a pure Rust workspace. `cargo build` at the
+> repository root produces the app (`oak-editor`), the CLI (`oak-cli`)
+> and the render worker (`oak-worker`). The old C++/CMake tree lives on
+> the `cpp-legacy` branch; nothing in this guide uses it.
 
 ---
 
-## Windows (MSYS2)
+## Prerequisites (all platforms)
 
-This guide uses [MSYS2](https://www.msys2.org/) with the UCRT64 toolchain.
+- **git** — clone with submodules (`gpui/` is a submodule):
+  ```sh
+  git clone --recursive https://github.com/OakVideoEditorCommunity/oak.git
+  cd oak
+  # or, on an existing clone: git submodule update --init --recursive
+  ```
+- **Rust stable** (via [rustup](https://rustup.rs/); on Windows use the
+  MSYS2 toolchain instead — see the Windows section).
+- **C toolchain + cmake + pkg-config + nasm** — cmake and a C++ compiler
+  are needed by the vendored OpenColorIO build (Linux/macOS), nasm by
+  the FFmpeg assembly.
+- **FFmpeg 8.1, built by the project script.** Distro packages are too
+  old for `ffmpeg-next` 9 and are deliberately not used:
+  ```sh
+  tooling/install-deps.sh        # codec/filter libraries + build tools
+  tooling/ffmpeg/build-ffmpeg.sh # clones release/8.1, installs into .cache/ffmpeg
+  ```
+  `FFMPEG_DIR` does not need exporting: the committed
+  `.cargo/config.toml` sets it relative to the workspace root
+  (`ffmpeg-sys-next` cannot read `.env` at build-script time — the
+  config entry is the only machine-agnostic way). The `oakffmpeg-link`
+  build script panics without it; run `build-ffmpeg.sh` once before the
+  first `cargo build`.
 
-### 1. Install MSYS2
+## Quick start (macOS / Linux)
 
-Download and install MSYS2 from [https://www.msys2.org/](https://www.msys2.org/). Then open the **MSYS2 UCRT64** terminal.
-
-### 2. Install Dependencies
-
-```bash
-pacman -Syu
-pacman -S --needed \
-  mingw-w64-ucrt-x86_64-cmake \
-  mingw-w64-ucrt-x86_64-ninja \
-  mingw-w64-ucrt-x86_64-qt6-base \
-  mingw-w64-ucrt-x86_64-qt6-tools \
-  mingw-w64-ucrt-x86_64-ffmpeg \
-  mingw-w64-ucrt-x86_64-openimageio \
-  mingw-w64-ucrt-x86_64-opencolorio \
-  mingw-w64-ucrt-x86_64-openexr \
-  mingw-w64-ucrt-x86_64-fmt \
-  mingw-w64-ucrt-x86_64-expat \
-  mingw-w64-ucrt-x86_64-portaudio \
-  mingw-w64-ucrt-x86_64-vulkan-headers \
-  mingw-w64-ucrt-x86_64-vulkan-loader \
-  mingw-w64-ucrt-x86_64-gcc
-```
-
-> **Note:** Qt 6 private headers may require additional packages depending on the MSYS2 repository state. If CMake reports missing private headers, install `mingw-w64-ucrt-x86_64-qt6-base-private` if available.
-
-### 3. Build OpenTimelineIO (required)
-
-There is no MSYS2 package for OpenTimelineIO, so build it from source:
-
-```bash
-git clone --depth 1 --branch v0.16.0 https://github.com/PixarAnimationStudios/OpenTimelineIO.git
-cmake -S OpenTimelineIO -B OpenTimelineIO/build -G Ninja \
-  -DOTIO_SHARED_LIBS=ON \
-  -DOTIO_PYTHON_BINDINGS=OFF \
-  -DOTIO_FIND_IMATH=ON \
-  -DCMAKE_BUILD_TYPE=Release \
-  -DCMAKE_INSTALL_PREFIX="${PWD}/otio-install"
-cmake --build OpenTimelineIO/build
-cmake --install OpenTimelineIO/build
-```
-
-### 4. Clone and Build
-
-```bash
-# Clone the repository
-git clone --recursive https://github.com/OakVideoEditorCommunity/oak.git
-cd oak
-
-# Configure
-cmake -S . -B build -G Ninja \
-  -DCMAKE_BUILD_TYPE=Release \
-  -DOTIO_LOCATION="/path/to/otio-install" \
-  -DBUILD_QT6=ON
-
-# Build
-cmake --build build --config Release
-```
-
-### 5. Run Tests (Optional)
-
-```bash
-ctest --test-dir build --output-on-failure -C Release
-```
-
----
-
-## Linux
-
-### Debian / Ubuntu
-
-Install dependencies (Ubuntu 24.04+ ships FFmpeg 6.1, which satisfies the 6.0 minimum; on older releases build FFmpeg from source as described in Troubleshooting):
-
-```bash
-sudo apt-get update
-sudo apt-get install -y \
-  cmake ninja-build pkg-config \
-  qt6-base-dev qt6-base-dev-tools qt6-base-private-dev qt6-tools-dev qt6-tools-dev-tools \
-  libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libswresample-dev libavfilter-dev \
-  libopencolorio-dev libopenimageio-dev libopenexr-dev libexpat1-dev \
-  portaudio19-dev libgl1-mesa-dev libvulkan-dev libxkbcommon-dev
-```
-
-Build OpenTimelineIO (required, no distro package):
-
-```bash
-git clone --depth 1 --branch v0.16.0 https://github.com/PixarAnimationStudios/OpenTimelineIO.git
-cmake -S OpenTimelineIO -B OpenTimelineIO/build -G Ninja \
-  -DOTIO_SHARED_LIBS=ON \
-  -DOTIO_PYTHON_BINDINGS=OFF \
-  -DOTIO_FIND_IMATH=ON \
-  -DCMAKE_BUILD_TYPE=Release \
-  -DCMAKE_INSTALL_PREFIX="${PWD}/otio-install"
-cmake --build OpenTimelineIO/build
-cmake --install OpenTimelineIO/build
-```
-
-Configure and build:
-
-```bash
-cmake -S . -B build -G Ninja \
-  -DBUILD_TESTS=ON -DBUILD_QT6=ON \
-  -DOTIO_LOCATION="$PWD/otio-install"
-cmake --build build --config Release
-```
-
-Run tests:
-
-```bash
-ctest --test-dir build --output-on-failure -C Release
-```
-
-### Fedora
-
-Install dependencies:
-
-```bash
-sudo dnf install -y \
-  cmake ninja-build pkgconf-pkg-config \
-  qt6-qtbase-devel qt6-qtbase-private-devel qt6-qttools-devel \
-  ffmpeg-free-devel \
-  OpenImageIO-devel \
-  OpenColorIO-devel \
-  openexr-devel \
-  expat-devel \
-  portaudio-devel \
-  mesa-libGL-devel \
-  vulkan-headers \
-  vulkan-loader-devel \
-  libxkbcommon-devel \
-  gcc-c++ \
-  bzip2-devel
-```
-
-Build OpenTimelineIO (required, no distro package):
-
-```bash
-git clone --depth 1 --branch v0.16.0 https://github.com/PixarAnimationStudios/OpenTimelineIO.git
-cmake -S OpenTimelineIO -B OpenTimelineIO/build -G Ninja \
-  -DOTIO_SHARED_LIBS=ON \
-  -DOTIO_PYTHON_BINDINGS=OFF \
-  -DOTIO_FIND_IMATH=ON \
-  -DOTIO_FIND_IMATH=ON \
-  -DCMAKE_BUILD_TYPE=Release \
-  -DCMAKE_INSTALL_PREFIX="${PWD}/otio-install"
-cmake --build OpenTimelineIO/build
-cmake --install OpenTimelineIO/build
-```
-
-Configure and build:
-
-```bash
-cmake -S . -B build -G Ninja -DBUILD_TESTS=ON -DBUILD_QT6=ON \
-  -DOTIO_LOCATION="$PWD/otio-install"
-cmake --build build --config Release
-```
-
-Run tests:
-
-```bash
-ctest --test-dir build --output-on-failure -C Release
-```
-
-### Arch Linux
-
-Install dependencies:
-
-```bash
-sudo pacman -Syu
-sudo pacman -S --needed \
-  cmake ninja pkgconf \
-  qt6-base qt6-tools \
-  ffmpeg \
-  openimageio \
-  opencolorio \
-  openexr \
-  expat \
-  portaudio \
-  opentimelineio \
-  mesa \
-  vulkan-headers \
-  vulkan-icd-loader \
-  libxkbcommon \
-  fmt \
-  gcc
-```
-
-> **Note:** On Arch Linux, Qt 6 private headers are included in the `qt6-base` package.
-
-Configure and build:
-
-```bash
-cmake -S . -B build -G Ninja -DBUILD_TESTS=ON -DBUILD_QT6=ON
-cmake --build build --config Release
-```
-
-Run tests:
-
-```bash
-ctest --test-dir build --output-on-failure -C Release
+```sh
+tooling/install-deps.sh         # Homebrew / apt / dnf / pacman
+tooling/ffmpeg/build-ffmpeg.sh  # ~10–20 min, once
+cargo build --workspace
+cargo test  --workspace         # Linux: see "headless tests" below
 ```
 
 ---
 
 ## macOS
 
-macOS is now a fully supported platform. See [`build_macos.md`](build_macos.md) for a dedicated, step-by-step guide.
+- macOS 12+, Xcode Command Line Tools (`xcode-select --install`), Homebrew.
+- ```sh
+  brew install cmake pkg-config
+  tooling/install-deps.sh
+  tooling/ffmpeg/build-ffmpeg.sh
+  cargo build --workspace
+  cargo test  --workspace
+  ```
+- OpenColorIO is compiled from the vendored 2.5.2 sources and linked
+  statically — no `brew install opencolorio` needed (cmake is required).
+- The GPU-gated tests (OFX GL overlay, hardware decode) run only with
+  `OAK_GPU_TESTS=1`.
 
-Install dependencies:
+## Linux
 
-```bash
-brew update
-brew install cmake ninja pkg-config qt@6 ffmpeg openimageio opencolorio openexr portaudio expat molten-vk vulkan-headers vulkan-loader
-```
+- Debian/Ubuntu, Fedora and Arch are supported by
+  `tooling/install-deps.sh`. Additionally install:
+  ```sh
+  # Debian/Ubuntu
+  sudo apt-get install -y cmake \
+    libpipewire-0.3-dev libspa-0.2-dev libjack-jackd2-dev \
+    libasound2-dev libpulse-dev libsndfile1-dev \
+    libgl1-mesa-dev libvulkan-dev libxkbcommon-dev libxkbcommon-x11-dev
+  ```
+  (the PipeWire/JACK/ALSA/PulseAudio/sndfile dev packages are cpal's
+  audio backends; GL/Vulkan/XKB are the wgpu windowing stack).
+- **Headless tests:** several gpui/UI tests open real windows through
+  wgpu on Mesa's software Vulkan. Under a display-less session run:
+  ```sh
+  sudo apt-get install -y xvfb mesa-vulkan-drivers
+  xvfb-run -a -s "-screen 0 1920x1080x24" cargo test --workspace
+  ```
+- OpenColorIO is the vendored static build, as on macOS.
 
-Build OpenTimelineIO (required):
+## Windows (MSYS2 UCRT64)
 
-```bash
-git clone --depth 1 --branch v0.16.0 https://github.com/PixarAnimationStudios/OpenTimelineIO.git
-cmake -S OpenTimelineIO -B OpenTimelineIO/build -G Ninja \
-  -DOTIO_SHARED_LIBS=ON \
-  -DOTIO_PYTHON_BINDINGS=OFF \
-  -DOTIO_FIND_IMATH=ON \
-  -DCMAKE_BUILD_TYPE=Release \
-  -DCMAKE_INSTALL_PREFIX="${PWD}/otio-install"
-cmake --build OpenTimelineIO/build
-cmake --install OpenTimelineIO/build
-```
+The Windows build targets **x86_64-pc-windows-gnu** with MSYS2's own
+Rust; the MSVC toolchain is not supported (the build scripts emit
+Unix-style link args the MSVC linker rejects).
 
-Configure and build:
-
-```bash
-export PATH="$(brew --prefix qt@6)/bin:$PATH"
-export CMAKE_PREFIX_PATH="$(brew --prefix qt@6)"
-export OTIO_LOCATION="${PWD}/otio-install"
-export OCIO_LOCATION="$(brew --prefix opencolorio)"
-# Let CMake's FindVulkan locate the Homebrew Vulkan loader (optional,
-# enables the Vulkan render backend)
-export VULKAN_SDK="$(brew --prefix vulkan-loader)"
-
-cmake -S . -B build -G Ninja -DBUILD_TESTS=ON -DBUILD_QT6=ON \
-  -DOTIO_LOCATION="${OTIO_LOCATION}" \
-  -DOCIO_LOCATION="${OCIO_LOCATION}"
-cmake --build build --config Release
-```
-
-Run tests:
-
-```bash
-ctest --test-dir build --output-on-failure -C Release
-```
+1. Install [MSYS2](https://www.msys2.org/) and open the **UCRT64** shell.
+2. ```sh
+   pacman -Syu
+   pacman -S --needed mingw-w64-ucrt-x86_64-rust \
+     mingw-w64-ucrt-x86_64-cmake mingw-w64-ucrt-x86_64-opencolorio
+   tooling/install-deps.sh        # must run inside the UCRT64 shell
+   tooling/ffmpeg/build-ffmpeg.sh
+   ```
+3. Environment (put in your shell rc or export per session):
+   ```sh
+   # The vendored OCIO sources contain MSVC-only constructs, so Windows
+   # links MSYS2's OpenColorIO 2.5.2 dynamically instead:
+   export OCIO_RS_ENABLE_REAL=1 OCIO_INSTALL_DIR=/ucrt64 OCIO_RS_LINK=dynamic
+   # mingw-w64 (Nov 2025+) forwards _assert to __msvcrt_assert inside
+   # libmingwex.a while rustc's link order leaves -lmingwex last; the
+   # trailing -lmsvcrt re-scans the CRT import library afterwards
+   # (otherwise: undefined _fileno/_setmode/__imp___msvcrt_assert).
+   export RUSTFLAGS="-C link-args=-lmsvcrt"
+   # If your shell inherits the MSVC INCLUDE/LIB (some CI runners inject
+   # them into every step), clear them — they poison the MinGW compiles:
+   unset INCLUDE LIB
+   ```
+4. ```sh
+   cargo build --workspace
+   cargo test  --workspace
+   ```
 
 ---
 
-## Build Options
+## OpenColorIO summary
 
-| Option | Default | Description |
-|--------|---------|-------------|
-| `BUILD_TESTS` | `OFF` | Build unit tests |
-| `BUILD_DOXYGEN` | `OFF` | Build Doxygen documentation |
-| `USE_WERROR` | `OFF` | Treat warnings as errors |
-| `BUILD_QT6` | `ON` | Build with Qt 6 instead of Qt 5 |
-| `OTIO_LOCATION` | - | Path to OpenTimelineIO installation (required) |
-| `OAK_BUNDLE_OTIO` | `ON` | Install OTIO runtime libraries alongside Oak (set `OFF` for distro-native packaging where `opentimelineio` is a package dependency, e.g. Arch) |
-| `OCIO_LOCATION` | - | Path to OpenColorIO installation |
-| `OAK_ENABLE_DYNAMIC_RENDER_BACKEND` | `ON` | Build dynamic render backend libraries (`liboakgl.so` / `liboakvulkan.so`) |
+| Platform | Source | Linkage | Notes |
+|----------|--------|---------|-------|
+| Linux / macOS | vendored 2.5.2 (`ocio-sys` `bundled` feature, on by default) | static | needs cmake + C++ compiler |
+| Windows | MSYS2 `mingw-w64-ucrt-x86_64-opencolorio` | dynamic | set `OCIO_INSTALL_DIR=/ucrt64`, `OCIO_RS_LINK=dynamic` |
 
----
+Without the `bundled` feature and without `OCIO_RS_ENABLE_REAL=1`,
+`ocio-sys` builds a stub and every colour test early-returns. The
+bundled feature is enabled unconditionally by `oakrender`, so a plain
+`cargo build` always gets the real thing on Linux/macOS.
+
+## Packaging
+
+Distribution packages are built in containers (no host dependencies
+beyond Docker/Podman):
+
+```sh
+tooling/package/build-deb.sh  # Debian 12  → .deb
+tooling/package/build-rpm.sh  # Fedora 41  → .rpm
+tooling/package/build-pkg.sh  # Arch Linux → .pkg.tar.zst
+```
+
+All runtime dependencies are declared in the respective package metadata
+(`packaging/`, `tooling/package/oak.spec`, `tooling/package/PKGBUILD`) —
+the packages are self-contained except for the documented system
+libraries; see `docs/project-storage.md` for what lands where.
 
 ## Troubleshooting
 
-### Qt 6 Not Found
-
-Ensure Qt 6 is in your PATH and CMake prefix path:
-
-```bash
-# Linux / macOS
-export PATH="/path/to/qt6/bin:$PATH"
-export CMAKE_PREFIX_PATH="/path/to/qt6"
-
-# Windows (MSYS2)
-export PATH="/ucrt64/bin:$PATH"
-```
-
-### Missing Private Headers
-
-If you see errors about missing Qt private headers, install the corresponding private development package for your distribution (e.g., `qt6-base-private-dev` on Debian/Ubuntu, `qt6-qtbase-private-devel` on Fedora).
-
-### FFmpeg Not Found
-
-Make sure FFmpeg development libraries are installed and `pkg-config` can locate them:
-
-```bash
-pkg-config --exists libavcodec && echo "Found" || echo "Not found"
-```
-
-### FFmpeg Version Too Old
-
-Oak requires FFmpeg 6.0 or newer; CMake configure fails with `Could NOT find FFMPEG (missing: FFMPEG_VERSION) (Required is at least version "6.0")` on older versions. Ubuntu 24.04+ / Fedora / Arch / Homebrew / MSYS2 all ship new enough FFmpeg. If your distro is older, build from source:
-
-```bash
-git clone --branch n8.1.1 --depth 1 https://git.ffmpeg.org/ffmpeg.git ffmpeg-src
-cd ffmpeg-src
-./configure \
-  --prefix="$PWD/../ffmpeg-install" \
-  --enable-static \
-  --disable-shared \
-  --disable-doc \
-  --disable-programs \
-  --disable-avdevice \
-  --disable-network \
-  --enable-pic \
-  --enable-gpl \
-  --enable-version3
-make -j$(nproc)
-make install
-cd ..
-```
-
-Then pass `-DFFMPEG_ROOT="$PWD/ffmpeg-install"` to CMake.
-
-### OpenTimelineIO Not Found
-
-OpenTimelineIO is a required dependency. Build it from source as shown in your platform's section above and pass `-DOTIO_LOCATION=/path/to/otio-install` to CMake. On Arch Linux the `opentimelineio` package provides it directly.
+- **`oakffmpeg-link` panics about `FFMPEG_DIR`** — run
+  `tooling/ffmpeg/build-ffmpeg.sh` once; it installs into
+  `.cache/ffmpeg`, which `.cargo/config.toml` points at.
+- **IDE builds fail (RustRover etc.)** — IDEs that cannot inject
+  environment variables into cargo can read a git-ignored `.env` at the
+  workspace root with `FFMPEG_DIR=...` (and `PKG_CONFIG_PATH=...` if
+  your codec libraries live in a custom prefix).
+- **pacman stalls with "Operation too slow"** — MSYS2 mirrors hiccup;
+  `install-deps.sh` retries three times, re-running it resumes via
+  `--needed`.
+- **Windows: `undefined reference to _fileno/_setmode/__imp___msvcrt_assert`**
+  — set `RUSTFLAGS="-C link-args=-lmsvcrt"` (see the Windows section).
+- **Windows: `AddInstanceForFactory: No factory registered` / MSVC-flavoured
+  errors** — you are on the MSVC Rust toolchain; switch to MSYS2's Rust
+  (`x86_64-pc-windows-gnu`).
+- **Empty `gpui/` directory** — `git submodule update --init --recursive`.
+- **Linux tests open windows and hang/fail** — use the `xvfb-run` line
+  from the Linux section.
diff --git a/docs/build_macos.md b/docs/build_macos.md
index 03f6e19db..d4d3b164d 100644
--- a/docs/build_macos.md
+++ b/docs/build_macos.md
@@ -1,5 +1,9 @@
 # macOS Build Guide
 
+> **Deprecated (2026):** this guide describes the old C++/CMake build.
+> The current Rust workspace build is documented in
+> [`build.md`](build.md) (中文：[`zh/build.md`](zh/build.md)).
+
 This document describes how to build Oak Video Editor from source on macOS.
 
 For the Chinese version, see [`build-macos-zh.md`](zh/build_macos-zh.md).
diff --git a/docs/zh/build.md b/docs/zh/build.md
index fc9da109d..8a20db082 100644
--- a/docs/zh/build.md
+++ b/docs/zh/build.md
@@ -1,342 +1,164 @@
 # 构建指南
 
-本文档介绍如何在 Windows、Linux 和 macOS 上从源码构建 Oak Video Editor。
+本文档介绍如何在 macOS、Linux 和 Windows 上从源码构建 Oak 视频编辑器。
+英文版见 [`../build.md`](../build.md)。
 
-## 依赖
-
-- CMake 3.20+
-- Ninja（推荐）
-- Qt 6（含私有头文件）
-- FFmpeg 6.0+ 开发库
-- OpenTimelineIO（0.16+，按下文从源码构建——大多数平台没有发行版软件包）
-- OpenImageIO
-- OpenColorIO（2.x）
-- OpenEXR
-- Expat
-- PortAudio
-- OpenGL 头文件
-- Vulkan SDK（可选，Vulkan 渲染后端需要）
-- XKB common（Linux）
+> **2026 年说明：** Oak 现在是纯 Rust workspace。在仓库根目录执行
+> `cargo build` 会产出应用（`oak-editor`）、命令行工具（`oak-cli`）
+> 和渲染进程（`oak-worker`）。旧的 C++/CMake 代码保留在
+> `cpp-legacy` 分支，本指南不涉及它。
 
 ---
 
-## Windows（MSYS2）
+## 通用前置条件
 
-本指南使用 [MSYS2](https://www.msys2.org/) 的 UCRT64 工具链。
+- **git** —— 克隆时必须带子模块（`gpui/` 是子模块）：
+  ```sh
+  git clone --recursive https://github.com/OakVideoEditorCommunity/oak.git
+  cd oak
+  # 已有克隆则：git submodule update --init --recursive
+  ```
+- **Rust stable**（通过 [rustup](https://rustup.rs/) 安装；Windows
+  请改用 MSYS2 自带 Rust——见 Windows 章节）。
+- **C 工具链 + cmake + pkg-config + nasm** —— cmake 和 C++ 编译器
+  用于 vendored OpenColorIO 构建（Linux/macOS），nasm 用于 FFmpeg
+  汇编。
+- **FFmpeg 8.1，由项目脚本构建。** 发行版自带版本对 `ffmpeg-next` 9
+  来说太旧，刻意不使用：
+  ```sh
+  tooling/install-deps.sh        # 编解码/滤镜库 + 构建工具
+  tooling/ffmpeg/build-ffmpeg.sh # 克隆 release/8.1，安装到 .cache/ffmpeg
+  ```
+  `FFMPEG_DIR` 无需手动导出：仓库内提交的 `.cargo/config.toml` 已按
+  workspace 根的相对路径设置（`ffmpeg-sys-next` 的构建脚本读不了
+  `.env`，这是唯一与机器无关的方式）。缺少它时 `oakffmpeg-link` 的
+  构建脚本会直接 panic：首次 `cargo build` 前请先跑一次
+  `build-ffmpeg.sh`。
 
-### 1. 安装 MSYS2
+## 快速开始（macOS / Linux）
 
-从 [https://www.msys2.org/](https://www.msys2.org/) 下载并安装 MSYS2，然后打开 **MSYS2 UCRT64** 终端。
-
-### 2. 安装依赖
-
-```bash
-pacman -Syu
-pacman -S --needed \
-  mingw-w64-ucrt-x86_64-cmake \
-  mingw-w64-ucrt-x86_64-ninja \
-  mingw-w64-ucrt-x86_64-qt6-base \
-  mingw-w64-ucrt-x86_64-qt6-tools \
-  mingw-w64-ucrt-x86_64-ffmpeg \
-  mingw-w64-ucrt-x86_64-openimageio \
-  mingw-w64-ucrt-x86_64-opencolorio \
-  mingw-w64-ucrt-x86_64-openexr \
-  mingw-w64-ucrt-x86_64-fmt \
-  mingw-w64-ucrt-x86_64-expat \
-  mingw-w64-ucrt-x86_64-portaudio \
-  mingw-w64-ucrt-x86_64-vulkan-headers \
-  mingw-w64-ucrt-x86_64-vulkan-loader \
-  mingw-w64-ucrt-x86_64-gcc
-```
-
-> **注意：** Qt 6 私有头文件可能需要额外安装。如果 CMake 报告找不到私有头文件，请尝试安装 `mingw-w64-ucrt-x86_64-qt6-base-private`（如果仓库中有）。
-
-### 3. 构建 OpenTimelineIO（必需）
-
-MSYS2 仓库没有 OpenTimelineIO 软件包，需从源码构建：
-
-```bash
-git clone --depth 1 --branch v0.16.0 https://github.com/PixarAnimationStudios/OpenTimelineIO.git
-cmake -S OpenTimelineIO -B OpenTimelineIO/build -G Ninja \
-  -DOTIO_SHARED_LIBS=ON \
-  -DOTIO_PYTHON_BINDINGS=OFF \
-  -DOTIO_FIND_IMATH=ON \
-  -DCMAKE_BUILD_TYPE=Release \
-  -DCMAKE_INSTALL_PREFIX="${PWD}/otio-install"
-cmake --build OpenTimelineIO/build
-cmake --install OpenTimelineIO/build
-```
-
-### 4. 克隆并构建
-
-```bash
-# 克隆仓库
-git clone --recursive https://github.com/OakVideoEditorCommunity/oak.git
-cd oak
-
-# 配置
-cmake -S . -B build -G Ninja \
-  -DCMAKE_BUILD_TYPE=Release \
-  -DOTIO_LOCATION="/path/to/otio-install" \
-  -DBUILD_QT6=ON
-
-# 构建
-cmake --build build --config Release
-```
-
-### 5. 运行测试（可选）
-
-```bash
-ctest --test-dir build --output-on-failure -C Release
-```
-
----
-
-## Linux
-
-### Debian / Ubuntu
-
-安装依赖（Ubuntu 24.04+ 自带的 FFmpeg 6.1 已满足 6.0 最低要求；更旧的发行版请按"故障排除"一节从源码编译 FFmpeg）：
-
-```bash
-sudo apt-get update
-sudo apt-get install -y \
-  cmake ninja-build pkg-config \
-  qt6-base-dev qt6-base-dev-tools qt6-base-private-dev qt6-tools-dev qt6-tools-dev-tools \
-  libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libswresample-dev libavfilter-dev \
-  libopencolorio-dev libopenimageio-dev libopenexr-dev libexpat1-dev \
-  portaudio19-dev libgl1-mesa-dev libvulkan-dev libxkbcommon-dev
-```
-
-从源码构建 OpenTimelineIO（必需，无发行版软件包）：
-
-```bash
-git clone --depth 1 --branch v0.16.0 https://github.com/PixarAnimationStudios/OpenTimelineIO.git
-cmake -S OpenTimelineIO -B OpenTimelineIO/build -G Ninja \
-  -DOTIO_SHARED_LIBS=ON \
-  -DOTIO_PYTHON_BINDINGS=OFF \
-  -DOTIO_FIND_IMATH=ON \
-  -DCMAKE_BUILD_TYPE=Release \
-  -DCMAKE_INSTALL_PREFIX="${PWD}/otio-install"
-cmake --build OpenTimelineIO/build
-cmake --install OpenTimelineIO/build
-```
-
-配置并构建：
-
-```bash
-cmake -S . -B build -G Ninja \
-  -DBUILD_TESTS=ON -DBUILD_QT6=ON \
-  -DOTIO_LOCATION="$PWD/otio-install"
-cmake --build build --config Release
-```
-
-运行测试：
-
-```bash
-ctest --test-dir build --output-on-failure -C Release
-```
-
-### Fedora
-
-安装依赖：
-
-```bash
-sudo dnf install -y \
-  cmake ninja-build pkgconf-pkg-config \
-  qt6-qtbase-devel qt6-qtbase-private-devel qt6-qttools-devel \
-  ffmpeg-free-devel \
-  OpenImageIO-devel \
-  OpenColorIO-devel \
-  openexr-devel \
-  expat-devel \
-  portaudio-devel \
-  mesa-libGL-devel \
-  vulkan-headers \
-  vulkan-loader-devel \
-  libxkbcommon-devel \
-  gcc-c++ \
-  bzip2-devel
-```
-
-从源码构建 OpenTimelineIO（必需，无发行版软件包）：
-
-```bash
-git clone --depth 1 --branch v0.16.0 https://github.com/PixarAnimationStudios/OpenTimelineIO.git
-cmake -S OpenTimelineIO -B OpenTimelineIO/build -G Ninja \
-  -DOTIO_SHARED_LIBS=ON \
-  -DOTIO_PYTHON_BINDINGS=OFF \
-  -DOTIO_FIND_IMATH=ON \
-  -DCMAKE_BUILD_TYPE=Release \
-  -DCMAKE_INSTALL_PREFIX="${PWD}/otio-install"
-cmake --build OpenTimelineIO/build
-cmake --install OpenTimelineIO/build
-```
-
-配置并构建：
-
-```bash
-cmake -S . -B build -G Ninja -DBUILD_TESTS=ON -DBUILD_QT6=ON \
-  -DOTIO_LOCATION="$PWD/otio-install"
-cmake --build build --config Release
-```
-
-运行测试：
-
-```bash
-ctest --test-dir build --output-on-failure -C Release
-```
-
-### Arch Linux
-
-安装依赖：
-
-```bash
-sudo pacman -Syu
-sudo pacman -S --needed \
-  cmake ninja pkgconf \
-  qt6-base qt6-tools \
-  ffmpeg \
-  openimageio \
-  opencolorio \
-  openexr \
-  expat \
-  portaudio \
-  opentimelineio \
-  mesa \
-  vulkan-headers \
-  vulkan-icd-loader \
-  libxkbcommon \
-  fmt \
-  gcc
-```
-
-> **注意：** Arch Linux 的 `qt6-base` 包已经包含私有头文件。
-
-配置并构建：
-
-```bash
-cmake -S . -B build -G Ninja -DBUILD_TESTS=ON -DBUILD_QT6=ON
-cmake --build build --config Release
-```
-
-运行测试：
-
-```bash
-ctest --test-dir build --output-on-failure -C Release
+```sh
+tooling/install-deps.sh         # Homebrew / apt / dnf / pacman
+tooling/ffmpeg/build-ffmpeg.sh  # 约 10–20 分钟，只需一次
+cargo build --workspace
+cargo test  --workspace         # Linux：见下文"无头测试"
 ```
 
 ---
 
 ## macOS
 
-macOS 现在是正式支持的平台。更详细的逐步指南请参见 [`build_macos-zh.md`](build_macos-zh.md)。
+- macOS 12+、Xcode Command Line Tools（`xcode-select --install`）、Homebrew。
+- ```sh
+  brew install cmake pkg-config
+  tooling/install-deps.sh
+  tooling/ffmpeg/build-ffmpeg.sh
+  cargo build --workspace
+  cargo test  --workspace
+  ```
+- OpenColorIO 由 vendored 2.5.2 源码编译并静态链接——不需要
+  `brew install opencolorio`（但需要 cmake）。
+- GPU 相关测试（OFX GL 叠加层、硬件解码）仅在设置 `OAK_GPU_TESTS=1`
+  时运行。
 
-安装依赖：
+## Linux
 
-```bash
-brew update
-brew install cmake ninja pkg-config qt@6 ffmpeg openimageio opencolorio openexr portaudio expat molten-vk vulkan-headers vulkan-loader
-```
+- `tooling/install-deps.sh` 支持 Debian/Ubuntu、Fedora、Arch。
+  另外需要安装：
+  ```sh
+  # Debian/Ubuntu
+  sudo apt-get install -y cmake \
+    libpipewire-0.3-dev libspa-0.2-dev libjack-jackd2-dev \
+    libasound2-dev libpulse-dev libsndfile1-dev \
+    libgl1-mesa-dev libvulkan-dev libxkbcommon-dev libxkbcommon-x11-dev
+  ```
+  （PipeWire/JACK/ALSA/PulseAudio/sndfile 开发包是 cpal 的音频后端；
+  GL/Vulkan/XKB 是 wgpu 窗口栈。）
+- **无头测试：** 部分 gpui/UI 测试会通过 wgpu 在 Mesa 软件 Vulkan
+  （lavapipe）上打开真实窗口。无显示环境下请运行：
+  ```sh
+  sudo apt-get install -y xvfb mesa-vulkan-drivers
+  xvfb-run -a -s "-screen 0 1920x1080x24" cargo test --workspace
+  ```
+- OpenColorIO 与 macOS 相同，使用 vendored 静态构建。
 
-构建 OpenTimelineIO（必需）：
+## Windows（MSYS2 UCRT64）
 
-```bash
-git clone --depth 1 --branch v0.16.0 https://github.com/PixarAnimationStudios/OpenTimelineIO.git
-cmake -S OpenTimelineIO -B OpenTimelineIO/build -G Ninja \
-  -DOTIO_SHARED_LIBS=ON \
-  -DOTIO_PYTHON_BINDINGS=OFF \
-  -DOTIO_FIND_IMATH=ON \
-  -DCMAKE_BUILD_TYPE=Release \
-  -DCMAKE_INSTALL_PREFIX="${PWD}/otio-install"
-cmake --build OpenTimelineIO/build
-cmake --install OpenTimelineIO/build
-```
+Windows 构建目标是 **x86_64-pc-windows-gnu**，使用 MSYS2 自带 Rust；
+不支持 MSVC 工具链（构建脚本会发出 MSVC 链接器不接受的 Unix 风格
+链接参数）。
 
-配置并构建：
-
-```bash
-export PATH="$(brew --prefix qt@6)/bin:$PATH"
-export CMAKE_PREFIX_PATH="$(brew --prefix qt@6)"
-export OTIO_LOCATION="${PWD}/otio-install"
-export OCIO_LOCATION="$(brew --prefix opencolorio)"
-# 让 CMake 的 FindVulkan 找到 Homebrew 的 Vulkan loader（可选，
-# 启用 Vulkan 渲染后端）
-export VULKAN_SDK="$(brew --prefix vulkan-loader)"
-
-cmake -S . -B build -G Ninja -DBUILD_TESTS=ON -DBUILD_QT6=ON \
-  -DOTIO_LOCATION="${OTIO_LOCATION}" \
-  -DOCIO_LOCATION="${OCIO_LOCATION}"
-cmake --build build --config Release
-```
-
-运行测试：
-
-```bash
-ctest --test-dir build --output-on-failure -C Release
-```
+1. 安装 [MSYS2](https://www.msys2.org/)，打开 **UCRT64** 终端。
+2. ```sh
+   pacman -Syu
+   pacman -S --needed mingw-w64-ucrt-x86_64-rust \
+     mingw-w64-ucrt-x86_64-cmake mingw-w64-ucrt-x86_64-opencolorio
+   tooling/install-deps.sh        # 必须在 UCRT64 终端内运行
+   tooling/ffmpeg/build-ffmpeg.sh
+   ```
+3. 环境变量（写入 shell rc 或每次会话导出）：
+   ```sh
+   # vendored OCIO 源码含有仅 MSVC 可编译的构造，Windows 改为动态链接
+   # MSYS2 的 OpenColorIO 2.5.2：
+   export OCIO_RS_ENABLE_REAL=1 OCIO_INSTALL_DIR=/ucrt64 OCIO_RS_LINK=dynamic
+   # mingw-w64（2025 年 11 月后）把 _assert 转发到 libmingwex.a 里的
+   # __msvcrt_assert，而 rustc 的链接顺序把 -lmingwex 放在最后；末尾
+   # 追加 -lmsvcrt 让链接器再扫一遍 CRT 导入库
+   # （否则报 undefined _fileno/_setmode/__imp___msvcrt_assert）。
+   export RUSTFLAGS="-C link-args=-lmsvcrt"
+   # 如果 shell 继承了 MSVC 的 INCLUDE/LIB（某些 CI runner 会向每个
+   # 步骤注入），务必清除——它们会污染 MinGW 编译：
+   unset INCLUDE LIB
+   ```
+4. ```sh
+   cargo build --workspace
+   cargo test  --workspace
+   ```
 
 ---
 
-## 构建选项
+## OpenColorIO 一览
 
-| 选项 | 默认值 | 说明 |
-|------|--------|------|
-| `BUILD_TESTS` | `OFF` | 构建单元测试 |
-| `BUILD_DOXYGEN` | `OFF` | 构建 Doxygen 文档 |
-| `USE_WERROR` | `OFF` | 将警告视为错误 |
-| `BUILD_QT6` | `ON` | 使用 Qt 6 而非 Qt 5 |
-| `OTIO_LOCATION` | - | OpenTimelineIO 安装路径（必需） |
-| `OAK_BUNDLE_OTIO` | `ON` | 随 Oak 一并安装 OTIO 运行库（发行版原生打包且 `opentimelineio` 是包依赖时设 `OFF`，如 Arch） |
-| `OCIO_LOCATION` | - | OpenColorIO 安装路径 |
-| `OAK_ENABLE_DYNAMIC_RENDER_BACKEND` | `ON` | 构建动态渲染后端库（`liboakgl.so` / `liboakvulkan.so`） |
+| 平台 | 来源 | 链接方式 | 备注 |
+|------|------|----------|------|
+| Linux / macOS | vendored 2.5.2（`ocio-sys` 的 `bundled` 特性，默认开启） | 静态 | 需要 cmake + C++ 编译器 |
+| Windows | MSYS2 `mingw-w64-ucrt-x86_64-opencolorio` | 动态 | 设置 `OCIO_INSTALL_DIR=/ucrt64`、`OCIO_RS_LINK=dynamic` |
 
----
+既没有 `bundled` 特性也没有 `OCIO_RS_ENABLE_REAL=1` 时，`ocio-sys`
+构建为 stub，所有色彩测试直接跳过。`oakrender` 无条件启用 bundled
+特性，因此在 Linux/macOS 上直接 `cargo build` 就会得到真实 OCIO。
 
-## 故障排除
+## 打包
 
-### 找不到 Qt 6
+发行版包在容器中构建（宿主机只需要 Docker/Podman）：
 
-确保 Qt 6 在 PATH 和 CMake prefix path 中：
-
-```bash
-# Linux / macOS
-export PATH="/path/to/qt6/bin:$PATH"
-export CMAKE_PREFIX_PATH="/path/to/qt6"
-
-# Windows（MSYS2）
-export PATH="/ucrt64/bin:$PATH"
+```sh
+tooling/package/build-deb.sh  # Debian 12  → .deb
+tooling/package/build-rpm.sh  # Fedora 41  → .rpm
+tooling/package/build-pkg.sh  # Arch Linux → .pkg.tar.zst
 ```
 
-### 缺少私有头文件
+所有运行时依赖都声明在各自的打包元数据中（`packaging/`、
+`tooling/package/oak.spec`、`tooling/package/PKGBUILD`）——除文档
+列明的系统库外包是自包含的；文件安装位置见
+`docs/project-storage.md`。
 
-如果看到缺少 Qt 私有头文件的错误，请安装对应发行版的私有开发包（例如 Debian/Ubuntu 上的 `qt6-base-private-dev`，Fedora 上的 `qt6-qtbase-private-devel`）。
+## 故障排查
 
-### FFmpeg 版本太旧
-
-Oak 要求 FFmpeg 6.0 或更新版本；版本不足时 CMake 配置阶段会报 `Could NOT find FFMPEG ... (Required is at least version "6.0")`。Ubuntu 24.04+ / Fedora / Arch / Homebrew / MSYS2 自带的版本都足够新。如果发行版过旧，请从源码编译：
-
-```bash
-git clone --branch n8.1.1 --depth 1 https://git.ffmpeg.org/ffmpeg.git ffmpeg-src
-cd ffmpeg-src
-./configure \
-  --prefix="$PWD/../ffmpeg-install" \
-  --enable-static \
-  --disable-shared \
-  --disable-doc \
-  --disable-programs \
-  --disable-avdevice \
-  --disable-network \
-  --enable-pic \
-  --enable-gpl \
-  --enable-version3
-make -j$(nproc)
-make install
-cd ..
-```
-
-然后在 CMake 中加上 `-DFFMPEG_ROOT="$PWD/ffmpeg-install"`。
-
-### 找不到 OpenTimelineIO
-
-OpenTimelineIO 是必需依赖。按你所在平台章节的说明从源码构建，并在 CMake 中加上 `-DOTIO_LOCATION=/path/to/otio-install`。Arch Linux 可直接安装 `opentimelineio` 包。
+- **`oakffmpeg-link` 报 `FFMPEG_DIR` panic** —— 先跑一次
+  `tooling/ffmpeg/build-ffmpeg.sh`；它安装到 `.cache/ffmpeg`，
+  `.cargo/config.toml` 已指向该目录。
+- **IDE 构建失败（RustRover 等）** —— 无法向 cargo 注入环境变量的
+  IDE 可以在 workspace 根放一个 git 忽略的 `.env`，写入
+  `FFMPEG_DIR=...`（编解码库在自定义前缀时再加
+  `PKG_CONFIG_PATH=...`）。
+- **pacman 报 "Operation too slow"** —— MSYS2 镜像偶尔卡顿；
+  `install-deps.sh` 会自动重试三次，手动重跑也会借助 `--needed`
+  断点续装。
+- **Windows：`undefined reference to _fileno/_setmode/__imp___msvcrt_assert`**
+  —— 设置 `RUSTFLAGS="-C link-args=-lmsvcrt"`（见 Windows 章节）。
+- **Windows：出现 MSVC 风格的链接错误** —— 你用的是 MSVC 版 Rust；
+  请改用 MSYS2 自带 Rust（`x86_64-pc-windows-gnu`）。
+- **`gpui/` 目录为空** —— `git submodule update --init --recursive`。
+- **Linux 测试开窗口卡死/失败** —— 使用 Linux 章节的 `xvfb-run`
+  命令。
diff --git a/docs/zh/build_macos-zh.md b/docs/zh/build_macos-zh.md
index 97b209dd9..b9b3a0aaf 100644
--- a/docs/zh/build_macos-zh.md
+++ b/docs/zh/build_macos-zh.md
@@ -1,5 +1,9 @@
 # macOS 编译指南
 
+> **已过时（2026）：** 本文档描述旧的 C++/CMake 构建。当前 Rust
+> workspace 的构建方法见 [`build.md`](build.md)（英文：
+> [`../build.md`](../build.md)）。
+
 本文档介绍如何在 macOS 上从源代码构建 Oak 视频编辑器。
 
 英文版本请参见 [`build-macos.md`](../build_macos.md)。
diff --git a/tooling/install-deps.sh b/tooling/install-deps.sh
index 80bb4e655..f05ea36be 100755
--- a/tooling/install-deps.sh
+++ b/tooling/install-deps.sh
@@ -18,8 +18,8 @@
 # Installs the system dependencies of the Oak Rust workspace:
 # the free-license external codec/filter libraries FFmpeg is configured
 # with (see crates/oakcodec/Cargo.toml), plus the build tools. FFmpeg
-# itself is built from source by cargo (ffmpeg-next `build` feature) and
-# is NOT installed here.
+# itself is built from source by tooling/ffmpeg/build-ffmpeg.sh (which
+# installs into .cache/ffmpeg) and is NOT installed here.
 #
 # Supported: Homebrew (macOS), MSYS2 UCRT64 (Windows), Debian/Ubuntu,
 # Fedora, Arch. Run it yourself — nothing in the build invokes it
@@ -102,4 +102,4 @@ case "$(uname -s)" in
 		;;
 esac
 
-echo "Done. 'cargo build' now compiles FFmpeg 8.1 from source with these libraries."
+echo "Done. Now run tooling/ffmpeg/build-ffmpeg.sh once, then 'cargo build'."