mention schema validation, and the need for @Entity etc annotations

documentation/src/main/asciidoc/introduction/Configuration.adoc

@@ -219,7 +219,7 @@ SessionFactory sessionFactory =
             .setProperty(AvailableSettings.JAKARTA_JDBC_PASSWORD, password)
             // Automatic schema export
             .setProperty(AvailableSettings.JAKARTA_HBM2DDL_DATABASE_ACTION,
-                         Action.CREATE.getExternalJpaName())
+                         Action.SPEC_ACTION_DROP_AND_CREATE)
             // SQL statement logging
             .setProperty(AvailableSettings.SHOW_SQL, TRUE.toString())
             .setProperty(AvailableSettings.FORMAT_SQL, TRUE.toString())

documentation/src/main/asciidoc/introduction/Generator.adoc

@@ -94,6 +94,11 @@ public abstract class Book_ {
 }
 ----
 
+For each attribute of the entity, the `Book_` class has:
+
+1. a `String`-valued constant like `TITLE` , and
+2. a typesafe reference like `title` to a metamodel object of type `Attribute`.
+
 We've already been using metamodel references like `Book_.authors` and `Book.AUTHORS` in the previous chapters.
 So now lets see what else the Metamodel Generator can do for us.
 
@@ -115,6 +120,13 @@ For example, you could use it to create your own criteria query API.
 Automatic generation of _finder methods_ and _query methods_ is a new feature of Hibernate's implementation of the Metamodel Generator, and an extension to the functionality defined by the JPA specification.
 In this chapter, we're going to explore these features.
 
+[CAUTION]
+====
+The functionality described in the rest of this chapter depends on the use of the annotations described in <<entities>>.
+The Metamodel Generator is not currently able to generate finder methods and query methods for entities declared completely in XML, and it's not able to validate HQL which queries such entities.
+(On the other hand, the <<object-relational-mapping,O/R mappings>> may be specified in XML, since they're not needed by the Metamodel Generator.)
+====
+
 We're going to meet three different kinds of generated method:
 
 - a _named query method_ has its signature and implementation generated directly from a `@NamedQuery` annotation,

documentation/src/main/asciidoc/introduction/Introduction.adoc

@@ -622,7 +622,7 @@ For example, if we're using `Configuration` to configure Hibernate, we could wri
 [source,java]
 ----
 configuration.setProperty(AvailableSettings.JAKARTA_HBM2DDL_DATABASE_ACTION,
-                          Action.CREATE.getExternalJpaName());
+                          Action.SPEC_ACTION_DROP_AND_CREATE);
 ----
 
 Alternatively, in Hibernate 6, we may use the new `SchemaManager` API to export the schema, just as we did <<main-hibernate,above>>.
@@ -691,6 +691,24 @@ You'll need to:
 Actually, some tests might require multiple sessions.
 But be careful not to leak a session between different tests.
 
+[TIP]
+=====
+Another important test we'll need is one which validates our <<object-relational-mapping,O/R mapping annotations>> against the actual database schema.
+This is again the job of the schema management tooling, either:
+[source,java]
+----
+configuration.setProperty(AvailableSettings.JAKARTA_HBM2DDL_DATABASE_ACTION,
+                          Action.ACTION_VALIDATE);
+
+----
+Or:
+[source,java]
+----
+sessionFactory.getSchemaManager().validateMappedObjects();
+----
+This "test" is one which many people like to run even in production, when the system starts up.
+=====
+
 [[architecture]]
 === Architecture and the persistence layer
 
@@ -757,9 +775,10 @@ At least _consider_ the possibility that it might be OK to call the `EntityManag
 
 image::images/architecture.png[API overview,pdfwidth="100%",width=1100,align="center"]
 
-> Sssssssss. Heresy!
+We can already hear you hissing at our heresy.
+But before slamming shut the lid of your laptop and heading off to fetch garlic and a pitchfork, take a couple of hours to weigh what we're proposing.
 
-OK, look, if it makes you feel better, one way to view `EntityManager` is to think of it as a single _generic_ "repository" that works for every entity in your system.
+OK, so, look, if it makes you feel better, one way to view `EntityManager` is to think of it as a single _generic_ "repository" that works for every entity in your system.
 From this point of view, JPA _is_ your persistence layer.
 And there's few good reasons to wrap this abstraction in a second abstraction that's _less_ generic.
 
@@ -810,7 +829,7 @@ This works even better in Hibernate 6 than in older versions of Hibernate, since
 // This is a much worse query language than HQL.
 // I think you can see why we didn't implement this idea in Hibernate.
 //
-OK, _phew_, let's move on.
+_Phew_, let's move on.
 
 [[overview]]
 === Overview