diff --git a/crates/gpui/README.md b/crates/gpui/README.md
index 6d4a37932ff..132e5ac1e9f 100644
--- a/crates/gpui/README.md
+++ b/crates/gpui/README.md
@@ -5,17 +5,48 @@ for Rust, designed to support a wide variety of applications.
 
 ## Getting Started
 
-GPUI is still in active development as we work on the Zed code editor, and is still pre-1.0. There will often be breaking changes between versions. You'll also need to use the latest version of stable Rust and be on macOS or Linux. Add the following to your `Cargo.toml`:
+GPUI is still in active development as we work on the Zed code editor, and is still pre-1.0. There will often be breaking changes between versions. You'll also need to use the latest version of stable Rust. Add `gpui`, and optionally `gpui_platform`, to your `Cargo.toml`:
 
 ```toml
 gpui = { version = "*" }
+gpui_platform = { version = "*", features = ["font-kit", "wayland", "x11"] }
 ```
 
+Everything in a standalone GPUI app starts with an `Application`. You can create one with `gpui_platform::application()`, which picks the windowing and text backends for the host OS, and kick off your application by passing a callback to `Application::run()`. Inside this callback, you can create a new window with `App::open_window()` and register your first root view.
+
+```rust,no_run
+use gpui::*;
+
+fn main() {
+    gpui_platform::application().run(|cx: &mut App| {
+        // ..
+    });
+}
+```
+
+### `gpui_platform`
+
+The features on `gpui_platform` are platform-specific, so the list above is a safe cross-platform default. If you build for a single platform, you can trim it:
+
+- **macOS** — Rendering uses Metal and is always available, but glyph rasterization needs `font-kit`. Without it, GPUI falls back to a placeholder text system that lays text out but renders no glyphs.
+
+    ```toml
+    gpui_platform = { version = "*", features = ["font-kit"] }
+    ```
+
+- **Linux / FreeBSD** — enable at least one windowing backend for desktop windows: `wayland`, `x11`, or both. These features also compile the renderer and text system, so no separate text feature is needed.
+
+    ```toml
+    gpui_platform = { version = "*", features = ["wayland", "x11"] }
+    ```
+
+- **Windows** — no features are required. Windowing uses Win32 and text uses DirectWrite. `font-kit` has no effect here.
+
+### Additional Topics
+
 - [Ownership and data flow](_ownership_and_data_flow)
 - [Accessibility](_accessibility)
 
-Everything in GPUI starts with an `Application`. You can create one with `Application::new()`, and kick off your application by passing a callback to `Application::run()`. Inside this callback, you can create a new window with `App::open_window()`, and register your first root view. See [gpui.rs](https://www.gpui.rs/) for a complete example.
-
 ### Dependencies
 
 GPUI has various system dependencies that it needs in order to work.