From 45d87bde67ef42d3086cc2bfb2ceca2403eca2a9 Mon Sep 17 00:00:00 2001
From: Talon <talon@iamtalon.me>
Date: Wed, 17 Jun 2026 00:52:57 +0200
Subject: [PATCH] docs(M4): expand Windows client README with build guide and
 known limitations
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replaces the M4-placeholder stub with a real build/run guide covering prerequisites,
build order (server → DLL → dotnet build), DLL dependency verification, manual test
runbook, and the known limitations (focus-scoped PTT, NR passthrough, no admin UI,
TOFU-pins-leaf-cert vs Ed25519).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 clients/windows/README.md | 89 +++++++++++++++++++++++++++++++++------
 1 file changed, 75 insertions(+), 14 deletions(-)

diff --git a/clients/windows/README.md b/clients/windows/README.md
index e81ca1b..65c5f6a 100644
--- a/clients/windows/README.md
+++ b/clients/windows/README.md
@@ -1,18 +1,79 @@
-# Windows client — placeholder
+# VoiceCat — Windows client
 
-Built in **M4** (see [`docs/roadmap.md`](../../docs/roadmap.md)). C# / .NET 8+, consuming
-`libvoicecat` through the C ABI ([`core/include/voicecat.h`](../../core/include/voicecat.h)).
+WinForms (.NET 10 LTS) UI over `voicecat.dll` (MinGW-built `libvoicecat` shared library).
 
-Planned shape (see [`docs/architecture.md`](../../docs/architecture.md) §4 and
-[`docs/tech-stack.md`](../../docs/tech-stack.md) §2):
+## Prerequisites
 
-- A .NET solution with a P/Invoke interop layer over the C ABI using **`LibraryImport`**
-  (source-generated, .NET 7+). Build `libvoicecat` as a **shared library**
-  (`-DVOICECAT_BUILD_SHARED=ON`) so the DLL sits beside the app.
-- The `on_event` callback marshaled as a function pointer (`[UnmanagedCallersOnly]`) to avoid
-  delegate-lifetime issues; keep the interface "chunky" to minimize managed↔native crossings.
-- UI in **WinUI 3** (most native) or **Avalonia** (if a single C# desktop UI is wanted later).
-- Audio (capture/playback, WASAPI loopback for `SCREEN_AUDIO`) is handled inside the core; the
-  C# layer only drives device selection, meters, and the VAD/PTT + per-user NR controls.
+| Tool | Version | Notes |
+|------|---------|-------|
+| .NET SDK | 10.0.x | `dotnet --version` should report `10.0.*` |
+| CMake | 3.25+ | For building the C++ DLL |
+| MinGW-w64 / MSYS2 UCRT64 | GCC 13+ | `C:\tools\msys64\ucrt64` is the expected location |
+| vcpkg | any | `VCPKG_ROOT` env var must point to a bootstrapped clone |
 
-Nothing here yet — the core must reach M2 (working voice) before the GUI is worth building.
+## Build order
+
+### 1. Build the server (for testing)
+
+```powershell
+cmake --preset m1-dev
+cmake --build --preset m1-dev --target voicecat-server
+```
+
+### 2. Build the DLL
+
+```powershell
+cmake --preset windows-client
+cmake --build --preset windows-client
+```
+
+Output: `build/windows-client/bin/voicecat.dll`
+
+**Verify no MinGW runtime dependencies remain:**
+```powershell
+& "C:\tools\msys64\ucrt64\bin\objdump.exe" -p build/windows-client/bin/voicecat.dll |
+    Select-String "DLL Name"
+```
+Expected: only Windows system DLLs (`KERNEL32.dll`, `WS2_32.dll`, `BCRYPT.dll`, etc.).
+If `libgcc_s_seh-1.dll`, `libstdc++-6.dll`, or `libwinpthread-1.dll` appear, the
+`-static-libgcc -static-libstdc++ -static -lwinpthread` link flags in `core/CMakeLists.txt`
+are not taking effect — check the CMake log for the `VOICECAT_BUILD_SHARED+WIN32` branch.
+
+### 3. Build the C# solution
+
+```powershell
+cd clients/windows
+dotnet build VoiceCat.slnx
+```
+
+The app's `Directory.Build.props` copies `voicecat.dll` from `../../build/windows-client/bin/`
+into the output directory automatically on every build.
+
+## Running manually
+
+```powershell
+# Terminal 1 — start the server
+./build/m1-dev/bin/voicecat-server.exe --name "My Server"
+
+# Terminal 2 — launch the client
+dotnet run --project clients/windows/VoiceCat.App/VoiceCat.App.csproj
+```
+
+On first connect to a new server:
+- Enter `127.0.0.1` as the host (not `localhost` — Windows resolves `localhost` to `::1`
+  first, and while the server now dual-stacks, `127.0.0.1` is cleaner for local testing).
+- The server identity dialog will appear. The TLS leaf-cert SHA-256 fingerprint is shown;
+  accept to pin it. Subsequent connects to the same server will be silent (MATCHED).
+
+## Known limitations
+
+- **PTT is focus-scoped** — the push-to-talk key only works while the VoiceCat window has
+  focus. A system-wide `WH_KEYBOARD_LL` hook is not used in v1 (permissions + AV risk).
+- **Receive-side noise reduction** checkbox in per-user tuning is wired end-to-end but is a
+  passthrough no-op until a real APM/NS backend is built (no working Windows/MSVC port of
+  `webrtc-audio-processing` upstream — see `docs/tech-stack.md §1`).
+- **Admin/moderation UI** is not present — kick/ban/permissions/account provisioning are M5
+  scope (requires server-side dispatch first).
+- **TOFU pins the TLS leaf cert**, not the declared Ed25519 identity fingerprint. Both are
+  shown in the identity dialog, but the cert fingerprint is the value that is actually
+  verified on reconnect. See `docs/security.md §1.1`.