build: bundle vcpkg as a git submodule, pinned to the manifest baseline

Adds vcpkg as a submodule at vcpkg/, pinned to the exact commit vcpkg.json
already declares as builtin-baseline, so the bundled checkout and the
manifest's resolved port versions can never drift apart.

cmake/voicecat-toolchain.cmake, scripts/common.sh, and
clients/apple/scripts/build-xcframework.sh now resolve vcpkg as:
VCPKG_ROOT env var (external checkout) > bundled submodule. Docs updated
to describe the new one-time setup.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

docs/building.md

@@ -75,21 +75,32 @@ was run.
 
 ## 2. One-time setup for the real-deps presets
 
-All presets except `vcpkg-common` need `VCPKG_ROOT`
-pointing at a bootstrapped vcpkg checkout:
+vcpkg is bundled as a git submodule at [`vcpkg/`](../vcpkg), pinned to the exact commit in
+[`vcpkg.json`](../vcpkg.json)'s `builtin-baseline` — so the bundled checkout and the manifest's
+resolved port versions can never drift apart. All presets except `vcpkg-common` need it
+bootstrapped:
 
 ```bash
-# once:
-git clone https://github.com/microsoft/vcpkg
+# once, after cloning:
+git submodule update --init vcpkg
 ./vcpkg/bootstrap-vcpkg.sh        # .bat on Windows
+```
 
-# every shell session (PowerShell):
+`cmake/voicecat-toolchain.cmake` resolves the vcpkg root itself — no environment variable
+needed. If you'd rather use an external vcpkg checkout (e.g. one shared across several
+projects), set `VCPKG_ROOT` and it takes priority over the bundled submodule:
+
+```bash
+# PowerShell:
 $env:VCPKG_ROOT = "D:\path\to\vcpkg"
 
-# or on Linux/macOS:
+# Linux/macOS:
 export VCPKG_ROOT=/path/to/vcpkg
 ```
 
+An external checkout must still be bootstrapped, and should be at (or compatible with)
+`vcpkg.json`'s `builtin-baseline` commit to resolve the same port versions.
+
 `vcpkg.json` (manifest mode) pins every dependency (protobuf, mbedTLS, libsodium, asio,
 sqlite3, spdlog, opus, miniaudio) — `cmake --preset dev` resolves and builds them
 automatically on first configure. That first configure is slow (vcpkg building from source);

docs/tech-stack.md

@@ -61,7 +61,7 @@ explicit resampling (speexdsp/libsamplerate) is only needed when a device can't
 | Tool | Use |
 |------|-----|
 | **CMake** (3.25+) | One build graph for core + server + test CLI; UI projects consume the built core. |
-| **vcpkg** (manifest mode) | Pin C/C++ deps (opus, libsodium, mbedtls, protobuf, sqlite3, spdlog, asio, miniaudio — see `vcpkg.json`). `webrtc-audio-processing`/`speexdsp` are **not** in the manifest: no working vcpkg port / no working Windows/MSVC build exists upstream for the former; the latter was never actually wired up (the lightweight VAD needs no resampler). Reproducible across OSes. Triplet auto-resolved from the host platform by [`cmake/voicecat-toolchain.cmake`](../cmake/voicecat-toolchain.cmake) — `x64-mingw-static` on Windows, `x64-linux` on Linux, `arm64-osx` on Apple Silicon. Apple platform scaffolding presets (`apple-dev`/`apple-ios`/`apple-ios-sim`) produce static `libvoicecat.a` slices for XCFramework consumption. |
+| **vcpkg** (manifest mode) | Pin C/C++ deps (opus, libsodium, mbedtls, protobuf, sqlite3, spdlog, asio, miniaudio — see `vcpkg.json`). `webrtc-audio-processing`/`speexdsp` are **not** in the manifest: no working vcpkg port / no working Windows/MSVC build exists upstream for the former; the latter was never actually wired up (the lightweight VAD needs no resampler). Reproducible across OSes. Triplet auto-resolved from the host platform by [`cmake/voicecat-toolchain.cmake`](../cmake/voicecat-toolchain.cmake) — `x64-mingw-static` on Windows, `x64-linux` on Linux, `arm64-osx` on Apple Silicon. Apple platform scaffolding presets (`apple-dev`/`apple-ios`/`apple-ios-sim`) produce static `libvoicecat.a` slices for XCFramework consumption. vcpkg itself is bundled as a git submodule at `vcpkg/`, pinned to `vcpkg.json`'s `builtin-baseline` commit — `VCPKG_ROOT` overrides it for an external checkout. See [building.md §2](building.md#2-one-time-setup-for-the-real-deps-presets). |
 | **protoc** | Generate C++/C#/Swift from `core/proto/*.proto` (single source of truth). |
 | **clang-format / clang-tidy** | Style + static analysis on the core. |
 | **CTest + a fuzz target** | Unit/integration tests; fuzz the frame parser and protobuf boundary (security-sensitive). |