diff --git a/builds/any/installer/sample-postinstall.py b/builds/any/installer/sample-postinstall.py
index 230013c9..1f5605d2 100644
--- a/builds/any/installer/sample-postinstall.py
+++ b/builds/any/installer/sample-postinstall.py
@@ -1,5 +1,53 @@
 """sample-postinstall.py
 
+Example Python script for post-install hooks.
+
+Add this as a postinstall hook to your installer via
+the 'mkinstaller.py' command line:
+
+$ mkinstaller.py ... --postinstall-plugin sample-postinstall.py ...
+
+At install time, this script will
+
+1. be extracted into a temporary working directory
+2. be imported as a module, in the same process as the installer
+   script
+
+Importing the module should not trigger any side-effects.
+
+At the appropriate time during the install (a chrooted invocation
+of the installer Python script) will
+
+1. scrape the top-level plugin's namespace for subclasses of
+   onl.install.Plugin.Plugin.
+   Implementors should declare classes here
+   (inheriting from onl.install.Plugin.Plugin) to embed the plugin
+   functionality.
+2. instantiate an instance of each class, with the installer
+   object initialized as the 'installer' attribute
+3. invoke the 'run' method (which must be overridden by implementors)
+4. invoke the 'shutdown' method (by default, a no-op)
+
+The 'run' method should return zero on success. In any other case, the
+installer terminates.
+
+The post-install plugins are invoked after the installer is complete
+and after the boot loader is updated.
+
+An exception to this is for proxy GRUB configurations. In that case, the
+post-install plugins are invoked after the install is finished, but before
+the boot loader has been updated.
+
+At the time the post-install plugin is invoked, none of the
+filesystems are mounted. If the implementor needs to manipulate the
+disk, the filesystems should be re-mounted temporarily with
+e.g. MountContext. The OnlMountContextReadWrite object and their
+siblings won't work here because the mtab.yml file is not populated
+within the loader environment.
+
+When using MountContxt, the system state in the installer object can help
+(self.installer.blkidParts in particular).
+
 """
 
 import onl.install.Plugin
diff --git a/builds/any/installer/sample-postinstall.sh b/builds/any/installer/sample-postinstall.sh
index 0bc0938c..36a0da25 100644
--- a/builds/any/installer/sample-postinstall.sh
+++ b/builds/any/installer/sample-postinstall.sh
@@ -1,4 +1,38 @@
 #!/bin/sh
+#
+######################################################################
+#
+# sample-postinstall.sh
+#
+# Example script for post-install hooks.
+#
+# Add this as a postinstall hook to your installer via
+# the 'mkinstaller.py' command line:
+#
+# $ mkinstaller.py ... --postinstall-script sample-postinstall.sh ...
+#
+# At install time, this script will
+#
+# 1. be extracted into the working directory with the other installer
+#    collateral
+# 2. have the execute bit set
+# 3. run in-place with the installer chroot directory passed
+#    as the first command line parameter
+#
+# If the script fails (returns a non-zero exit code) then
+# the install is aborted.
+#
+# This script is executed using the ONIE runtime (outside the chroot),
+# after the actual installer (chrooted Python script) has finished.
+#
+# This script is run after the postinstall actions (e.g. proxy GRUB
+# commands)
+#
+# At the time the script is run, the installer environment (chroot)
+# is fully prepared, including filesystem mount-points.
+# That is, the chroot mount points have not been unmounted yet.
+#
+######################################################################
 
 rootdir=$1; shift
 
diff --git a/builds/any/installer/sample-preinstall.py b/builds/any/installer/sample-preinstall.py
index 77148225..09b2b524 100644
--- a/builds/any/installer/sample-preinstall.py
+++ b/builds/any/installer/sample-preinstall.py
@@ -1,5 +1,43 @@
 """sample-preinstall.py
 
+Example Python script for pre-install hooks.
+
+Add this as a preinstall hook to your installer via
+the 'mkinstaller.py' command line:
+
+$ mkinstaller.py ... --preinstall-plugin sample-preinstall.py ...
+
+At install time, this script will
+
+1. be extracted into a temporary working directory
+2. be imported as a module, in the same process as the installer
+   script
+
+Importing the module should not trigger any side-effects.
+
+At the appropriate time during the install (a chrooted invocation
+of the installer Python script) will
+
+1. scrape the top-level plugin's namespace for subclasses of
+   onl.install.Plugin.Plugin.
+   Implementors should declare classes here
+   (inheriting from onl.install.Plugin.Plugin) to embed the plugin
+   functionality.
+2. instantiate an instance of each class, with the installer
+   object initialized as the 'installer' attribute
+3. invoke the 'run' method (which must be overridden by implementors)
+4. invoke the 'shutdown' method (by default, a no-op)
+
+The 'run' method should return zero on success. In any other case, the
+installer terminates.
+
+The 'installer' object has a handle onto the installer ZIP archive
+(self.installer.zf) but otherwise the install has not been
+started. That is, the install disk has not been
+prepped/initialized/scanned yet. As per the ONL installer API, the
+installer starts with *no* filesystems mounted, not even the ones from
+a prior install.
+
 """
 
 import onl.install.Plugin
diff --git a/builds/any/installer/sample-preinstall.sh b/builds/any/installer/sample-preinstall.sh
index daf128a6..13532aae 100644
--- a/builds/any/installer/sample-preinstall.sh
+++ b/builds/any/installer/sample-preinstall.sh
@@ -1,4 +1,34 @@
 #!/bin/sh
+#
+######################################################################
+#
+# sample-preinstall.sh
+#
+# Example script for pre-install hooks.
+#
+# Add this as a preinstall hook to your installer via
+# the 'mkinstaller.py' command line:
+#
+# $ mkinstaller.py ... --preinstall-script sample-preinstall.sh ...
+#
+# At install time, this script will
+#
+# 1. be extracted into the working directory with the other installer
+#    collateral
+# 2. have the execute bit set
+# 3. run in-place with the installer chroot directory passed
+#    as the first command line parameter
+#
+# If the script fails (returns a non-zero exit code) then
+# the install is aborted.
+#
+# This script is executed using the ONIE runtime (outside the chroot),
+# before the actual installer (chrooted Python script)
+#
+# At the time the script is run, the installer environment (chroot)
+# has been fully prepared, including filesystem mount-points.
+#
+######################################################################
 
 rootdir=$1; shift