diff --git a/README.md b/README.md
index c9ef62806..67cf2a36f 100644
--- a/README.md
+++ b/README.md
@@ -47,6 +47,25 @@ Additional build-time dependencies are automatically downloaded as
 part of the build process. To build and install into your local Maven
 cache, issue the command `sbt clean test publishM2`.
 
+# Domain class generation
+
+The Scala domain classes under `domainClasses/src/main/generated/` are generated from the schema defined in `schema/src/main/scala/io/shiftleft/codepropertygraph/schema/`. They are checked into the repository, so you only need to regenerate them when the schema changes.
+
+Generation is handled by the `sbt-flatgraph` plugin via the `generateDomainClasses` task in the `schema` subproject. It reads `CpgSchema.instance`, which composes all schema modules, and writes Scala source files to `domainClasses/src/main/generated/`.
+
+The task is wired as a dependency of `domainClasses/compile` and `stage`, so it runs automatically when you compile or stage:
+
+```
+sbt compile   # triggers generateDomainClasses, then compiles
+sbt stage     # triggers generateDomainClasses, then packages
+```
+
+To run generation on its own:
+
+```
+sbt schema/generateDomainClasses
+```
+
 # Code style
 
 Code style is automatically verified by [scalafmt](https://github.com/scalameta/scalafmt)
diff --git a/schema2json/build.sbt b/schema2json/build.sbt
index bfe2de18f..01b87a0cb 100644
--- a/schema2json/build.sbt
+++ b/schema2json/build.sbt
@@ -14,3 +14,5 @@ Test / fork := true
 testOptions += Tests.Argument(TestFrameworks.JUnit, "-a", "-v")
 
 enablePlugins(JavaAppPackaging)
+
+stage := stage.dependsOn(Projects.schema / Compile / generateDomainClasses).value