diff --git a/doc/rtd/explanation/format/mime.rst b/doc/rtd/explanation/format/mime.rst
index 829367eb964..95da17fe43d 100644
--- a/doc/rtd/explanation/format/mime.rst
+++ b/doc/rtd/explanation/format/mime.rst
@@ -77,4 +77,27 @@ Create user-data containing 3 shell scripts:
 
     $ cloud-init devel make-mime -a always.sh:x-shellscript-per-boot -a instance.sh:x-shellscript-per-instance -a once.sh:x-shellscript-per-once
 
+Per-frequency shell scripts
+---------------------------
+
+Cloud-init supports three MIME content types for controlling how often a
+shell script runs:
+
+``text/x-shellscript-per-boot``
+    The script runs on **every boot**. Useful for tasks that must be
+    repeated each time the instance starts, such as mounting ephemeral
+    storage or refreshing dynamic configuration.
+
+``text/x-shellscript-per-instance``
+    The script runs **once per instance-id** (typically on first boot
+    for that instance). Useful for one-time instance setup tasks.
+
+``text/x-shellscript-per-once``
+    The script runs **once per cloud-init state**, using the cloud-level
+    semaphore directory (:file:`/var/lib/cloud/sem`). A freshly
+    provisioned instance will normally run it once, but an instance
+    created from an image that preserves existing cloud-init state may
+    not. To allow it to run again, clean cloud-init state (for example,
+    remove :file:`/var/lib/cloud` or run :command:`cloud-init clean`).
+
 .. _make-mime: https://github.com/canonical/cloud-init/blob/main/cloudinit/cmd/devel/make_mime.py