diff --git a/docs/build-and-release.md b/docs/build-and-release.md
index f9fba19..cd18922 100644
--- a/docs/build-and-release.md
+++ b/docs/build-and-release.md
@@ -1,80 +1,74 @@
 # Build and Release
 
-This project uses [Wails](https://wails.io/) for desktop packaging.
+Nexus Terminal is a Rust workspace in `rust/`:
 
-## Ubuntu 24.04 prerequisites
-
-Install the Linux build toolchain and Wails runtime headers with:
-
-```bash
-sudo apt-get update
-sudo apt-get install -y \
-  build-essential \
-  libgtk-3-dev \
-  libwebkit2gtk-4.1-dev \
-  libayatana-appindicator3-dev \
-  pkg-config \
-  zip
+```
+rust/
+├── core/   nexus-core: storage, secrets, protocol clients, session manager, Service. No GUI.
+└── app/    nexus: the egui desktop app (binary `nexus-terminal`)
 ```
 
-Notes:
+The toolchain is pinned in `rust/rust-toolchain.toml`; `rustup` installs it on first build.
 
-- Ubuntu 24.04 does not ship `libwebkit2gtk-4.0-dev`.
-- Wails `v2.12.0` supports Ubuntu 24.04 by building with the `webkit2_41` tag.
-- The local build scripts detect that package layout automatically and add the tag when needed.
+## Prerequisites
 
-You will also need these tools available in `PATH`:
+- **All platforms:** [rustup](https://rustup.rs).
+- **Linux:** the X11/Wayland/GL headers eframe links against, and GTK for native file dialogs:
 
-- `go`
-- `node`
-- `npm`
-- `wails`
+  ```bash
+  sudo apt-get install -y build-essential pkg-config libxkbcommon-dev libgl1-mesa-dev \
+    libx11-dev libxcursor-dev libxrandr-dev libxi-dev libwayland-dev libgtk-3-dev zip
+  ```
 
-Install the Wails CLI with:
+- **macOS:** Xcode command-line tools (`xcode-select --install`).
+- **Windows:** the MSVC build tools (Visual Studio Build Tools, "Desktop development with C++").
+
+There are no runtime C libraries to install: SQLite is compiled in and TLS uses rustls.
+
+## Build and run
 
 ```bash
-go install github.com/wailsapp/wails/v2/cmd/wails@latest
-export PATH="$PATH:$(go env GOPATH)/bin"
+cd rust
+cargo run --release                 # the app
+cargo test --workspace              # unit and integration tests
+cargo clippy --workspace -- -D warnings
 ```
 
-## Build commands
+Useful flags (also handy for testing): `nexus-terminal [--theme pro|midnight|light]
+[--data-dir DIR] [--screenshot out.png] [--size WxH] [--run-local CMD]`. `--data-dir` points at
+another data directory; `--screenshot` renders the window, saves a PNG and exits (works under
+`xvfb-run`); `--run-local` opens a local terminal and types `CMD` into it.
 
-Build the app binary for the current host:
+The SSH integration tests start a throwaway `sshd` as the current user on a random port; they
+skip themselves when OpenSSH isn't installed.
+
+## Release packages
 
 ```bash
-./build.sh
+cd rust
+./release.sh                                            # this machine's platform
+NEXUS_RELEASE_TARGETS=linux/amd64,windows/amd64 ./release.sh
 ```
 
-Build packaged releases for every supported 64-bit desktop target:
+Artefacts land in `build/releases/<version>/` at the repo root:
 
-```bash
-./release.sh
-```
+- `NexusTerminal-<os>-<arch>.zip` — on macOS a universal-capable `.app` bundle
+  (`rust/packaging/macos/build-app.sh`), on Windows the `.exe` (icon and version info embedded,
+  GUI subsystem), on Linux the binary plus `install.sh` and a `.desktop` entry
+  (`rust/packaging/linux/install.sh` installs into `~/.local`).
+- `manifest-<os>-<arch>.json` and `version-<os>-<arch>.txt` for the update server
+  (`updates/index.php`), in the same format as before.
 
-By default, `./release.sh` builds all six OS/architecture combinations:
+The version is `<latest tag>-<short commit>` unless `NEXUS_VERSION` is set. The update manifest
+URL is compiled in from `NEXUS_UPDATE_URL` (default in `release.sh`); `{platform}` and `{arch}` use
+the old Go names (`darwin`/`linux`/`windows`, `amd64`/`arm64`).
 
-- macOS (`darwin`): `amd64` and `arm64`
-- Linux: `amd64` and `arm64`
-- Windows: `amd64` and `arm64`
+Cross-building `windows/amd64` from Linux works with `x86_64-pc-windows-gnu` and mingw-w64.
+macOS bundles must be built on a Mac. CI (`.github/workflows/release-builds.yml`) builds every
+platform natively on GitHub runners and attaches the zips to tagged releases;
+`.github/workflows/ci.yml` runs tests and clippy on Linux, macOS and Windows.
 
-Go calls the x86-64 architecture `amd64` and the AArch64 architecture `arm64`.
+## Signing
 
-On macOS, Linux builds run in architecture-matched Podman or Docker containers
-because Wails does not cross-compile Linux applications directly from macOS.
-The reusable builder images keep their `node_modules` separate from the host
-checkout.
-
-## Optional targeted builds
-
-The release scripts disable CGO and use a pure-Go SQLite driver, so Linux and Windows cross-targets do not need C cross-compilers for the application backend. To build a smaller set, override the default targets:
-
-```bash
-LINK_RELEASE_TARGETS=linux/amd64,windows/amd64 ./release.sh
-```
-
-## Platform caveats
-
-- To produce all six targets in one run, use macOS with Podman or Docker running.
-- macOS targets cannot be cross-built from Linux or Windows with Wails.
-- Cross-target support still depends on Wails and frontend packaging support for the requested platform.
-- Tested on Ubuntu 24.04 `amd64`: `linux/amd64` and `windows/amd64` build successfully.
+macOS bundles are ad-hoc signed. For distribution, sign with a Developer ID and notarize (see the
+comments in `build-app.sh`). Windows binaries are unsigned.