Document critter runtime generation's class loader requirement

content/morphia/3.0/configuration.md

@@ -91,6 +91,7 @@ morphia.mapper=critter
 Or pass `-Dmorphia.mapper=critter` on the Maven command line when running tests.
 
 For production deployments, consider using the [critter-maven plugin](../maven-plugin/) to generate models at build time and eliminate the startup cost entirely.
+Runtime generation requires your entities to be loaded by the same class loader (or be in the same module) as Morphia; if they aren't, as in some application server or JPMS layouts, use the plugin. See [Class loaders and modules](../maven-plugin/#class-loaders-and-modules).
 
 ## User-defined Codecs
 

content/morphia/3.0/maven-plugin.md

@@ -6,7 +6,7 @@ weight: 60
 The `critter-maven` plugin generates Morphia entity models and property accessors at build time (AOT — ahead of time), so they are ready on the classpath before your application starts.
 Without the plugin, Morphia generates the same models at each JVM startup.
 
-The plugin is entirely optional; the runtime fallback produces identical results.  It is recommended to use the plugin, however.
+The plugin is optional; where runtime generation works, it produces identical results.  It is recommended to use the plugin, however, and it is required to get critter models when your entities live outside Morphia's class loader or module (see [Class loaders and modules](#class-loaders-and-modules)).
 
 ## Why use it?
 
@@ -19,6 +19,24 @@ The plugin is entirely optional; the runtime fallback produces identical results
 
 Both paths generate the bytecode necessary to manage your entities. The plugin simply moves the generation work from JVM startup to build time.
 
+## Class loaders and modules
+
+Runtime generation defines its property accessors as hidden nestmates of each entity class.
+The JVM only allows that with full privilege access to the entity, which Morphia has only when the entity is in the same module as Morphia.
+On the classpath, that means the entity must be loaded by the same class loader as Morphia.
+
+That isn't the case in layouts like these:
+
+* Morphia in an application server's shared library directory, with the entities in a web application or other deployment that has its own class loader
+* Plugin or isolated class loader setups where the entities are loaded separately from Morphia
+* Entities in a separate JPMS module from Morphia
+
+There, runtime generation fails for every entity.
+Morphia logs a warning once per entity saying it can't access the entity and falls back to the reflection-based model, so your application keeps working, but without the critter models.
+
+Pre-generated models from the `critter-maven` plugin aren't affected: they are compiled alongside your entities and loaded from the entities' own class loader.
+If your application uses one of these layouts, use the plugin to get critter models.
+
 ## Setup
 
 Add the plugin to your `pom.xml` and set `morphia.mapper=critter` in your config: