docs(build): note the macOS Metal Toolchain requirement

[bojieli]

Problem

On Xcode 26 and newer, bun run build and bun run macos both fail on a clean checkout:

error: gpui@0.2.2: metal shader compilation failed:
error: cannot execute tool 'metal' due to missing Metal Toolchain;
       use: xcodebuild -downloadComponent MetalToolchain
error: failed to run custom build command for `gpui v0.2.2`

Xcode 26 no longer bundles the Metal compiler. xcrun -f metal still resolves to a path under XcodeDefault.xctoolchain, so the toolchain looks present, but the binary is a stub that refuses to run until the component is downloaded.

Both scripts hit it because they are the same script — scripts/macos.ts, differing only by --build-only — and gpui's build script compiles src/platform/mac/shaders.metal.

The failure is easy to misdiagnose. The System UI and all 11 applications build successfully first, so the error lands roughly 740 lines into the log, buried under cargo's rerun-if-changed output. It reads as a JavaScript or submodule dependency problem when it is neither.

Change

One paragraph in the README's Build requirements, next to the existing Xcode note:

macOS native builds also need Xcode command-line tools; Xcode 26 and newer ship the Metal compiler separately, so install it once with xcodebuild -downloadComponent MetalToolchain or the gpui shader build fails.

No code, configuration, or lockfile changes.

Verification

After xcodebuild -downloadComponent MetalToolchain (704.6 MB, Metal Toolchain 17C7003j) on Xcode 26.2:

• bun run build → exit 0, Pocket Desktop: built System UI + 11 applications + release host
• bun run macos → host booted: pocket-desktop-host: booted pocket-desktop-system-ui (394073 bytes js, 687456 bytes pak)

CI

Unaffected. The macos-latest runner image already provides the toolchain — the macOS job has been green on recent runs — so this is a local-environment prerequisite only, and no workflow change is needed.

Follow-up not included here

scripts/macos.ts could preflight metal and fail fast with this instruction rather than surfacing it deep in cargo output. Left out to keep this change minimal; happy to add it here or separately.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NeaMy5HWENMujKrgnyCPa7

[github-actions]

Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution. You can sign the CLA by just posting a Pull Request Comment same as the below format.

---

I have read the CLA Document and I hereby sign the CLA

---

_{You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.}