diff --git a/documentation/src/main/asciidoc/repositories/Configuration.adoc b/documentation/src/main/asciidoc/repositories/Configuration.adoc
index 72161c9a5965..2198d5148333 100644
--- a/documentation/src/main/asciidoc/repositories/Configuration.adoc
+++ b/documentation/src/main/asciidoc/repositories/Configuration.adoc
@@ -103,10 +103,13 @@ This usually happens via dependency injection, so you'll need to make sure that
 - in a Jakarta EE environment, `HibernateProcessor` generates special code which takes care of creating and destroying the `StatelessSession`, but
 - in other environments, this is something we need to take care of ourselves.
 
+Note that a `StatelessSession` should never be shared across transactions.
+
 [CAUTION]
 ====
 Depending on the libraries in your build path, `HibernateProcessor` generates different code.
 For example, if Quarkus is on the build path, the repository implementation is generated to obtain the `StatelessSession` directly from CDI in a way which works in Quarkus but not in WildFly.
+Similarly, if Spring is in the build path, the repository implementation is generated to use `ObjectProvider<StatelessSession>`, since Spring is not capable of transparently proxying contextual objects like CDI does.
 ====
 
 If you have multiple persistence units, you'll need to disambiguate the persistence unit for a repository interface using `@Repository(dataStore="my-persistence-unit-name")`.
@@ -120,7 +123,16 @@ In principle, any implementation of `jakarta.inject` may be used to inject a rep
 @Inject Library library;
 ----
 
-However, this code will fail if the repository implementation is not able to obtain a `StatelessSession` from the bean container.
+Of course, this code will fail if the repository implementation is not able to obtain a `StatelessSession` from the bean container.
+
+[NOTE]
+====
+Unfortunately, `jakarta.inject` on its own is rather incomplete, and does not specify how injectable beans should be discovered.
+Therefore, `HibernateProcessor` adds an appropriate bean-defining annotation to the repository implementation class, either:
+
+- `@Dependent` if CDI is available, or
+- `@Component` if Spring is available.
+====
 
 It's always possible to instantiate a repository implementation directly.