diff --git a/README.md b/README.md
index f86feeb..f704676 100644
--- a/README.md
+++ b/README.md
@@ -31,4 +31,140 @@
     ·
     <a href="https://github.com/sailpoint-oss/repo-template/issueschoose">Request Feature</a> -->
   </p>
-</div>
\ No newline at end of file
+</div>
+
+## Requirements
+
+- **JDK 17.** This is not optional — see the warning below.
+- **Maven 3.9+.**
+
+### ⚠️ Make sure Maven is actually using JDK 17
+
+Maven uses `JAVA_HOME`, *not* whichever `java` is first on your `PATH`. If `JAVA_HOME` is
+unset, Maven falls back to its own bundled JDK — and a Homebrew-installed Maven pulls in
+Homebrew's `openjdk` formula, which is likely much newer than 17.
+
+Check what Maven is really using before you build:
+
+```bash
+mvn -v      # look at the "Java version:" line, not `java -version`
+```
+
+If it does not say 17, set it explicitly:
+
+```bash
+export JAVA_HOME=$(/usr/libexec/java_home -v 17)   # macOS
+# export JAVA_HOME=/usr/lib/jvm/temurin-17-jdk     # Linux, adjust to your install
+```
+
+**Why this matters:** this project pins `mockito-core` 5.2.0 and `byte-buddy` 1.14.5, which
+predate recent JDKs. On a newer JDK the code still compiles, but most tests fail with
+`Mockito cannot mock this class`. On JDK 17 all tests pass. If you see that error, you are
+on the wrong JDK — it is not a problem with your rule.
+
+## Running the tests
+
+```bash
+mvn test
+```
+
+You should get `Tests run: 13, Failures: 0, Errors: 0` and `BUILD SUCCESS`.
+
+## Updating the SailPoint class stubs
+
+The `sailpoint.*` classes your rules compile against (`IdnRuleUtil`, `Identity`, `Link`,
+`ProvisioningPlan`, …) are **not** source files in this repo. They come from a prebuilt
+`sailpoint:rule-java-docs` jar produced by the
+[rule-javadoc](https://github.com/sailpoint-oss/rule-javadoc) repo.
+
+That jar is vendored here as a committed local Maven repository:
+
+```
+lib/sailpoint/rule-java-docs/<version>/
+    rule-java-docs-<version>.jar        # the compiled stubs
+    rule-java-docs-<version>.pom
+    *.md5 / *.sha1                      # checksums Maven requires
+lib/sailpoint/rule-java-docs/maven-metadata.xml
+```
+
+`pom.xml` points at it with `<url>file://${project.basedir}/lib</url>` and depends on a
+specific version. So when the rule API changes, you rebuild the jar in `rule-javadoc` and
+deploy it into `lib/` here.
+
+### Steps
+
+```bash
+export JAVA_HOME=$(/usr/libexec/java_home -v 17)
+RDK=$(pwd)                      # run this from the root of this repo
+```
+
+**1. Bump the version in `rule-javadoc/pom.xml`.**
+
+Check what version this repo currently consumes (`grep -A2 rule-java-docs pom.xml`) and pick
+the next one. Note that `rule-javadoc`'s own `pom.xml` has historically drifted out of sync
+with the version actually shipped here, so verify rather than assume.
+
+**2. Build the jar.**
+
+```bash
+cd /path/to/rule-javadoc
+mvn package                     # produces target/rule-java-docs-<VERSION>.jar
+```
+
+**3. Deploy it into this repo's `lib/`.**
+
+```bash
+mvn deploy:deploy-file \
+  -Durl=file://$RDK/lib \
+  -DrepositoryId=data-local \
+  -Dfile=target/rule-java-docs-<VERSION>.jar \
+  -DpomFile=pom.xml
+```
+
+Use `deploy:deploy-file`, **not** `install:install-file` — only `deploy-file` writes the
+`.md5`/`.sha1` checksums and updates `maven-metadata.xml` to match the existing layout.
+
+**4. Point this repo at the new version.** Edit the dependency in `pom.xml`:
+
+```xml
+<dependency>
+    <groupId>sailpoint</groupId>
+    <artifactId>rule-java-docs</artifactId>
+    <version><!-- new version --></version>
+</dependency>
+```
+
+**5. Verify.**
+
+```bash
+cd $RDK
+mvn test        # expect 13/13 passing
+```
+
+**6. Commit** the new `lib/sailpoint/rule-java-docs/<version>/` directory, the updated
+`lib/sailpoint/rule-java-docs/maven-metadata.xml`, and `pom.xml`. The old version directory
+can be deleted once you are confident in the new one.
+
+### Checking what you built
+
+```bash
+# maven-metadata.xml should list the new version and set it as <release>
+cat lib/sailpoint/rule-java-docs/maven-metadata.xml
+
+# the jar should contain Java 8 bytecode (major version 52)
+javap -verbose -cp lib/sailpoint/rule-java-docs/<VERSION>/rule-java-docs-<VERSION>.jar \
+  sailpoint.server.IdnRuleUtil | grep major
+```
+
+Java 8 bytecode is expected and correct. `rule-javadoc` sets
+`maven.compiler.target=8`, so the jar targets Java 8 **regardless of which JDK you build
+with**, and JDK 17 reads it without issue. You do not need a JDK 8 to produce it.
+
+## Troubleshooting
+
+| Symptom | Cause |
+| --- | --- |
+| `Mockito cannot mock this class: ...` | Maven is running on a JDK newer than 17. Check `mvn -v` and set `JAVA_HOME`. |
+| `Could not resolve dependencies for ... rule-java-docs:jar:<version>` | The version in `pom.xml` does not match a directory under `lib/sailpoint/rule-java-docs/`. |
+| Dependency resolves to the old stubs after an update | Stale local cache. Run `rm -rf ~/.m2/repository/sailpoint/rule-java-docs` and rebuild. |
+| `source value 8 is obsolete` warnings when building `rule-javadoc` | Expected, harmless. It targets Java 8 on purpose. |
diff --git a/lib/sailpoint/rule-java-docs/1.1/rule-java-docs-1.1.jar.md5 b/lib/sailpoint/rule-java-docs/1.1/rule-java-docs-1.1.jar.md5
deleted file mode 100644
index 80f2564..0000000
--- a/lib/sailpoint/rule-java-docs/1.1/rule-java-docs-1.1.jar.md5
+++ /dev/null
@@ -1 +0,0 @@
-530a7adb67c575f840a30f0297220775
\ No newline at end of file
diff --git a/lib/sailpoint/rule-java-docs/1.1/rule-java-docs-1.1.jar.sha1 b/lib/sailpoint/rule-java-docs/1.1/rule-java-docs-1.1.jar.sha1
deleted file mode 100644
index 32b9d7f..0000000
--- a/lib/sailpoint/rule-java-docs/1.1/rule-java-docs-1.1.jar.sha1
+++ /dev/null
@@ -1 +0,0 @@
-f8b4467e6749b880fe4f65b026d4ee900480128f
\ No newline at end of file
diff --git a/lib/sailpoint/rule-java-docs/1.1/rule-java-docs-1.1.pom.md5 b/lib/sailpoint/rule-java-docs/1.1/rule-java-docs-1.1.pom.md5
deleted file mode 100644
index af32a74..0000000
--- a/lib/sailpoint/rule-java-docs/1.1/rule-java-docs-1.1.pom.md5
+++ /dev/null
@@ -1 +0,0 @@
-ea8eb74a7082d0bc46f83135e43b9aec
\ No newline at end of file
diff --git a/lib/sailpoint/rule-java-docs/1.1/rule-java-docs-1.1.pom.sha1 b/lib/sailpoint/rule-java-docs/1.1/rule-java-docs-1.1.pom.sha1
deleted file mode 100644
index 195e700..0000000
--- a/lib/sailpoint/rule-java-docs/1.1/rule-java-docs-1.1.pom.sha1
+++ /dev/null
@@ -1 +0,0 @@
-dc13a1e7c38e07d8b2a59b8ff98ee3a927e85aac
\ No newline at end of file
diff --git a/lib/sailpoint/rule-java-docs/1.1/rule-java-docs-1.1.jar b/lib/sailpoint/rule-java-docs/2.0/rule-java-docs-2.0.jar
similarity index 63%
rename from lib/sailpoint/rule-java-docs/1.1/rule-java-docs-1.1.jar
rename to lib/sailpoint/rule-java-docs/2.0/rule-java-docs-2.0.jar
index 1371a63..96423fc 100644
Binary files a/lib/sailpoint/rule-java-docs/1.1/rule-java-docs-1.1.jar and b/lib/sailpoint/rule-java-docs/2.0/rule-java-docs-2.0.jar differ
diff --git a/lib/sailpoint/rule-java-docs/2.0/rule-java-docs-2.0.jar.md5 b/lib/sailpoint/rule-java-docs/2.0/rule-java-docs-2.0.jar.md5
new file mode 100644
index 0000000..12d3608
--- /dev/null
+++ b/lib/sailpoint/rule-java-docs/2.0/rule-java-docs-2.0.jar.md5
@@ -0,0 +1 @@
+c29b620ff9244ec67cae77c613b1ae8c
\ No newline at end of file
diff --git a/lib/sailpoint/rule-java-docs/2.0/rule-java-docs-2.0.jar.sha1 b/lib/sailpoint/rule-java-docs/2.0/rule-java-docs-2.0.jar.sha1
new file mode 100644
index 0000000..f5ea13c
--- /dev/null
+++ b/lib/sailpoint/rule-java-docs/2.0/rule-java-docs-2.0.jar.sha1
@@ -0,0 +1 @@
+626e5b1a2e12fbc8883808bea45d98ea4b7feb59
\ No newline at end of file
diff --git a/lib/sailpoint/rule-java-docs/1.1/rule-java-docs-1.1.pom b/lib/sailpoint/rule-java-docs/2.0/rule-java-docs-2.0.pom
similarity index 96%
rename from lib/sailpoint/rule-java-docs/1.1/rule-java-docs-1.1.pom
rename to lib/sailpoint/rule-java-docs/2.0/rule-java-docs-2.0.pom
index 26436dc..29b8121 100644
--- a/lib/sailpoint/rule-java-docs/1.1/rule-java-docs-1.1.pom
+++ b/lib/sailpoint/rule-java-docs/2.0/rule-java-docs-2.0.pom
@@ -6,15 +6,15 @@
 
     <groupId>sailpoint</groupId>
     <artifactId>rule-java-docs</artifactId>
-    <version>1.1</version>
+    <version>2.0</version>
     <packaging>jar</packaging>
 
     <name>Rule Java Docs</name>
 
     <properties>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-        <maven.compiler.source>17</maven.compiler.source>
-        <maven.compiler.target>17</maven.compiler.target>
+        <maven.compiler.source>8</maven.compiler.source>
+        <maven.compiler.target>8</maven.compiler.target>
     </properties>
 
     <build>
@@ -22,7 +22,7 @@
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-compiler-plugin</artifactId>
-                <version>3.12.1</version>
+                <version>3.8.0</version>
                 <configuration>
                     <compilerArgs>
                         <arg>-parameters</arg>
diff --git a/lib/sailpoint/rule-java-docs/2.0/rule-java-docs-2.0.pom.md5 b/lib/sailpoint/rule-java-docs/2.0/rule-java-docs-2.0.pom.md5
new file mode 100644
index 0000000..37253ae
--- /dev/null
+++ b/lib/sailpoint/rule-java-docs/2.0/rule-java-docs-2.0.pom.md5
@@ -0,0 +1 @@
+4e9b804f8b59ed6fd8becd82df3c34ab
\ No newline at end of file
diff --git a/lib/sailpoint/rule-java-docs/2.0/rule-java-docs-2.0.pom.sha1 b/lib/sailpoint/rule-java-docs/2.0/rule-java-docs-2.0.pom.sha1
new file mode 100644
index 0000000..76d4718
--- /dev/null
+++ b/lib/sailpoint/rule-java-docs/2.0/rule-java-docs-2.0.pom.sha1
@@ -0,0 +1 @@
+1d8cf87048d14eebef9e819a3833cc7bcb834f73
\ No newline at end of file
diff --git a/lib/sailpoint/rule-java-docs/maven-metadata.xml b/lib/sailpoint/rule-java-docs/maven-metadata.xml
index c3589e1..0a19d77 100644
--- a/lib/sailpoint/rule-java-docs/maven-metadata.xml
+++ b/lib/sailpoint/rule-java-docs/maven-metadata.xml
@@ -3,10 +3,10 @@
   <groupId>sailpoint</groupId>
   <artifactId>rule-java-docs</artifactId>
   <versioning>
-    <release>1.1</release>
+    <release>2.0</release>
     <versions>
-      <version>1.1</version>
+      <version>2.0</version>
     </versions>
-    <lastUpdated>20240812151936</lastUpdated>
+    <lastUpdated>20260813195239</lastUpdated>
   </versioning>
 </metadata>
diff --git a/lib/sailpoint/rule-java-docs/maven-metadata.xml.md5 b/lib/sailpoint/rule-java-docs/maven-metadata.xml.md5
index db9c2ee..e394dc1 100644
--- a/lib/sailpoint/rule-java-docs/maven-metadata.xml.md5
+++ b/lib/sailpoint/rule-java-docs/maven-metadata.xml.md5
@@ -1 +1 @@
-a58148b423d068d6c3291f75c9e650b8
\ No newline at end of file
+86f8bf329e4f99e516cf1ec02a41b307
\ No newline at end of file
diff --git a/lib/sailpoint/rule-java-docs/maven-metadata.xml.sha1 b/lib/sailpoint/rule-java-docs/maven-metadata.xml.sha1
index 0dff307..a6bd3ea 100644
--- a/lib/sailpoint/rule-java-docs/maven-metadata.xml.sha1
+++ b/lib/sailpoint/rule-java-docs/maven-metadata.xml.sha1
@@ -1 +1 @@
-da9875c341b95055835542685ebe02510e2c0318
\ No newline at end of file
+0e7ec5d36a7db094f8dc6df97e471034179c4737
\ No newline at end of file
diff --git a/pom.xml b/pom.xml
index 3a61588..47f8d2d 100644
--- a/pom.xml
+++ b/pom.xml
@@ -38,7 +38,7 @@
         <dependency>
             <groupId>sailpoint</groupId>
             <artifactId>rule-java-docs</artifactId>
-            <version>1.1</version>
+            <version>2.0</version>
         </dependency>
         <dependency>
             <groupId>net.bytebuddy</groupId>