diff --git a/balena.yml b/balena.yml
index ca08467..1a530ad 100644
--- a/balena.yml
+++ b/balena.yml
@@ -2,6 +2,93 @@ name: display
 type: sw.block
 version: 0.0.2
 description: "Hardware-accelerated Weston Wayland compositor block for balenaOS"
+post-provisioning: >-
+  ## How to Use This Block
+
+  ### Option 1 — Direct image in `docker-compose.yml`
+
+  Reference the architecture-specific image directly. Best when your fleet targets a single known architecture (e.g. `aarch64` for Raspberry Pi 4/5):
+
+  ```yaml
+  version: '2.1'
+
+  services:
+    display:
+      image: bh.cr/balena_solutions/display-aarch64
+      privileged: true
+      restart: always
+      network_mode: host
+      volumes:
+        - display-socket:/run
+      labels:
+        io.balena.features.dbus: '1'
+
+    your-app:
+      build: ./your-app
+      restart: always
+      depends_on:
+        - display
+      volumes:
+        - display-socket:/run
+      devices:
+        - /dev/dri:/dev/dri
+      environment:
+        - WAYLAND_DISPLAY=wayland-0
+        - XDG_RUNTIME_DIR=/run/user/0
+
+  volumes:
+    display-socket:
+  ```
+
+  ### Option 2 — `Dockerfile.template` (multi-arch)
+
+  Use a `Dockerfile.template` so balena substitutes the correct architecture at build time. Best for fleets spanning multiple architectures (e.g. `aarch64` and `amd64`):
+
+  **`./display/Dockerfile.template`**
+  ```dockerfile
+  FROM bh.cr/balena_solutions/display-%%BALENA_ARCH%%
+  ```
+
+  **`docker-compose.yml`**
+  ```yaml
+  version: '2.1'
+
+  services:
+    display:
+      build: ./display
+      privileged: true
+      restart: always
+      network_mode: host
+      volumes:
+        - display-socket:/run
+      labels:
+        io.balena.features.dbus: '1'
+
+    your-app:
+      build: ./your-app
+      restart: always
+      depends_on:
+        - display
+      volumes:
+        - display-socket:/run
+      devices:
+        - /dev/dri:/dev/dri
+      environment:
+        - WAYLAND_DISPLAY=wayland-0
+        - XDG_RUNTIME_DIR=/run/user/0
+
+  volumes:
+    display-socket:
+  ```
+
+  In your app's entry script, wait for the socket before launching:
+  ```bash
+  SOCKET="$XDG_RUNTIME_DIR/$WAYLAND_DISPLAY"
+  while [ ! -e "$SOCKET" ]; do sleep 1; done
+  exec your-app
+  ```
+
+  For more examples, see https://github.com/balena-solutions/display/tree/main/examples
 assets:
   repository:
     type: blob.asset