feat(docs): improve CONTRIBUTING.md, point example at published app

CONTRIBUTING.md

@@ -2,14 +2,77 @@
 
 # Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/evervault/evervault-java/issues.
+Bug reports and pull requests are welcome on the [GitHub issue tracker](https://github.com/evervault/evervault-java/issues).
 
-## Commit Formatting & Releases
+## Building and testing
 
-We use [changesets](https://github.com/changesets/changesets) to version manage in this repo.
+The SDK lives in `lib/`. Use the Gradle wrapper:
 
-When creating a pr that needs to be rolled into a version release, do `npx changeset`, select the level of the version bump required and describe the changes for the change logs. DO NOT select major for releasing breaking changes without team approval.
+```sh
+./gradlew build
+./gradlew test
+```
 
-To release:
+`build` runs the test task, so the credentials note below applies to it too.
 
-Merge the version PR that the changeset bot created to bump the version numbers. This will bump the versions of the packages, create a git tag for the release, and release the new version to npm.
+### Tests that need credentials
+
+The suite has 139 unit tests plus four end-to-end classes under `com.evervault.EndToEndTests`
+that call the Evervault API. Without credentials, those four fail at initialization instead of
+being skipped, so a clean checkout reports a red build:
+
+```
+EncryptTest > initializationError FAILED
+143 tests completed, 4 failed
+```
+
+Either supply credentials:
+
+```sh
+TEST_EV_APP_ID=app_xxx TEST_EV_API_KEY=ev:key:... ./gradlew test
+```
+
+or run the unit tests alone:
+
+```sh
+./gradlew test --tests 'com.evervault.When*'
+```
+
+### Java compatibility
+
+Reproducing a specific CI Java version needs that JDK installed locally. Toolchain
+auto-provisioning is not configured, so the build fails with "No matching toolchains" if it
+is missing:
+
+```sh
+./gradlew test -PjavaToolchainVersion=8
+```
+
+### Dependency locking
+
+All configurations are locked. Adding, removing, or upgrading a dependency requires
+regenerating the lockfiles, or resolution fails:
+
+```sh
+./gradlew dependencies --write-locks
+```
+
+Commit the resulting `lib/gradle.lockfile` and `buildscript-gradle.lockfile`.
+
+## Changesets and releases
+
+We use [changesets](https://github.com/changesets/changesets) to manage versions.
+
+A PR that should land in a release needs a changeset. Run `pnpm changeset`, pick the bump
+level, and describe the change for the changelog. Do not pick major for a breaking change
+without team approval.
+
+Releasing is two steps, both on `master`:
+
+1. Merging a PR that contains changesets prompts the bot to open a "New Release" PR that
+   bumps the version in `package.json` and `lib/build.gradle`.
+2. Merging that PR tags the commit, creates the GitHub release, and stages the artifact to
+   Sonatype. Publishing to Maven Central then waits on manual approval of the `maven-central`
+   deployment environment. Until someone approves it, the release is staged but not public.
+
+After approval the artifact appears at `com.evervault:lib:<version>` on Maven Central.

examples/offline-encrypt/README.md

@@ -16,10 +16,15 @@ Evervault evervault = Evervault.withKey(appId, apiKey, key, teamUuid);
 
 `kid` is enforced when present - use `EvervaultKey.fromJwks(jwksJson)` if the JWK has no `kid`.
 
-Built against the SDK in this repository via `includeBuild('../..')`, using the
-repository's Gradle wrapper rather than carrying its own.
+The example builds against the published SDK from Maven Central (see `build.gradle` for the
+version) and uses the repository's Gradle wrapper rather than shipping its own.
 
-## 1. Download your app's keys
+For local SDK development, uncomment `includeBuild('../..')` in `settings.gradle` to
+build against the working tree instead of the published artifact. Gradle substitutes
+`com.evervault:lib` by group and module, so the version in `build.gradle` is ignored while
+it is on.
+
+## 1. Download your App's keys
 
 ```sh
 mkdir -p keys
@@ -58,5 +63,5 @@ EV_APP_ID=app_xxx EV_API_KEY=ev:key:... ../../gradlew run --args="<kid>"
 | --- | --- | --- |
 | `EV_KEY_ID` | — | `kid` to use, unless the JWKS holds a single key |
 | `EV_JWKS_PATH` | `keys/jwks.json` | JWKS to read |
-| `EV_APP_ID` | `app_offline_example` | Evervault App whose credentials decrypt the ciphertext. Must be the app the JWKS came from |
+| `EV_APP_ID` | `app_offline_example` | Evervault App whose credentials decrypt the ciphertext. Must be the App the JWKS came from |
 | `EV_API_KEY` | — | When set, the example also decrypts via HTTP call |

examples/offline-encrypt/build.gradle

@@ -7,7 +7,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.evervault:lib:4.2.0'
+    implementation 'com.evervault:lib:4.3.1'
 }
 
 java {

examples/offline-encrypt/settings.gradle

@@ -1,3 +1,4 @@
 rootProject.name = 'offline-encrypt'
 
-includeBuild('../..')
+// Uncomment this line to use a local build when testing 
+// includeBuild('../..')