diff --git a/CLAUDE.md b/CLAUDE.md
index 799be39..8a06cf8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -100,6 +100,14 @@ See [`../workspace/policies/spotbugs-suppressions.md`](../workspace/policies/spo
 
 See [`../workspace/policies/jqwik-prompt-injection.md`](../workspace/policies/jqwik-prompt-injection.md).
 
+## JPMS Module Descriptor
+
+This repo ships a `module-info.java` compiled in a separate `release 9` execution. Javadoc
+currently runs in **classpath mode** (javadoc `<source>` resolves to `8`), which is the *only*
+thing keeping it clear of the JPMS module-mode javadoc trap that bit BAF. **Before raising the
+Java / javadoc source level to ≥ 9, read**
+[`../workspace/policies/jpms-module-descriptor.md`](../workspace/policies/jpms-module-descriptor.md).
+
 ## Open TODOs
 
 Open TODOs for this repo live in [`TODO.md`](TODO.md). Cross-repo status