diff --git a/docs/using-nocloud-compatible-images.md b/docs/using-nocloud-compatible-images.md
new file mode 100644
index 0000000..07d783c
--- /dev/null
+++ b/docs/using-nocloud-compatible-images.md
@@ -0,0 +1,39 @@
+# Using Cloud-init with NoCloud Compatible Images
+
+SmartOS release [20260306T044811Z][smartos-20260306T044811Z]
+introduced support for [cloud-init's NoCloud][nocloud]
+datasource for bhyve guests.
+
+To use this feature, a guest must be provisioned from an image tagged with
+`org.smartos:cloudinit_datasource=nocloud`.
+
+## Behavior
+
+When an instance is created, SmartOS uses instance metadata to build a 16 MiB
+FAT disk containing these files:
+
+- [user-data][user-data]: populated from
+  `customer_metadata['cloud-init:user-data']`
+- [meta-data][meta-data]: contains the instance UUID and hostname; if no
+  hostname is set, SmartOS falls back to the alias, then the UUID
+- [vendor-data][vendor-data]: reserved for SmartOS or Triton-supplied defaults
+  that users may override with `customer_metadata['cloud-init:user-data']`
+- [network-config][network-config]: generated automatically from the instance's
+  `nics` and `resolvers` metadata
+
+On instance startup, SmartOS rebuilds this filesystem if the source metadata has
+changed, for example after adding a NIC or changing the hostname.
+
+Instances created from NoCloud-compatible images do not include the mdata tools
+by default; install them separately if needed.
+
+Examples of SmartOS payloads and image build scripts are available in the
+[triton-nocloud-images][triton-nocloud-images] repository.
+
+[smartos-20260306T044811Z]: https://us-central.manta.mnx.io/Joyent_Dev/public/SmartOS/smartos.html#20260306T044811Z
+[nocloud]: https://docs.cloud-init.io/en/latest/reference/datasources/nocloud.html#nocloud
+[user-data]: https://docs.cloud-init.io/en/latest/reference/datasources/nocloud.html#user-data
+[meta-data]: https://docs.cloud-init.io/en/latest/reference/datasources/nocloud.html#meta-data
+[vendor-data]: https://docs.cloud-init.io/en/latest/reference/datasources/nocloud.html#vendor-data
+[network-config]: https://docs.cloud-init.io/en/latest/reference/datasources/nocloud.html#network-config
+[triton-nocloud-images]: https://github.com/TritonDataCenter/triton-nocloud-images/tree/main/examples
diff --git a/mkdocs.yml b/mkdocs.yml
index bd4a17d..36e2ce3 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -56,6 +56,7 @@ nav:
             - "Instance Management":
                 - "Managing Instances with vmadm": "managing-instances-with-vmamd.md"
                 - "Instance Metadata": "customer_metadata.md"
+                - "Using Cloud-init with NoCloud Compatible Images": "using-nocloud-compatible-images.md"
         - "Managing Images": "managing-images.md"
         - "Administering SmartOS Native Instances":
             - "Managing Packages": "working-with-packages.md"