docs: document runtime platform release flow

build/gradle-plugin/setup.mdx

@@ -1,18 +1,33 @@
 ---
 title: "Setup"
 description: "Apply gg.grounds.push to your Gradle project."
 ---
 
 The `gg.grounds.push` Gradle plugin is what actually uploads your JAR to forge. The CLI's `grounds push` is a thin wrapper around its tasks.
 
 <Note>
 `gg.grounds.push` is **separate** from the convention-plugin bundle (`gg.grounds.paper-conventions`, `gg.grounds.kotlin-conventions`, …). The conventions plugins shape your build; `push` ships its output. You almost certainly want both.
 </Note>
 
+## Convention plugins
+
+Grounds plugin repositories use convention plugins from `library-gradle-plugin` to shape JVM plugin artifacts:
+
+- `gg.grounds.paper-conventions`
+- `gg.grounds.velocity-conventions`
+- `gg.grounds.paper-standalone-conventions`
+- `gg.grounds.paper-runtime-consumer-conventions`
+- `gg.grounds.paper-runtime-provider-conventions`
+- `gg.grounds.velocity-standalone-conventions`
+- `gg.grounds.velocity-runtime-consumer-conventions`
+- `gg.grounds.velocity-runtime-provider-conventions`
+
+Runtime-consumer conventions are for internal Paper and Velocity plugins that run with [`plugin-grounds-runtime`](/reference/development/gradle-plugin/runtime-libraries). Standalone conventions are for plugins that must carry their own runtime libraries.
+
 ## Prerequisites
 
 - A GitHub personal access token with `read:packages` scope (the plugin lives on GitHub Packages).
 - Gradle 8+ and JDK 21+.
 - A `shadowJar` or `jar` task that produces the artifact you want to push.
 
 ## Add the plugin repository
@@ -34,7 +49,7 @@
 }
 ```
 
 Storing creds in `~/.gradle/gradle.properties`:
 
 ```properties ~/.gradle/gradle.properties
 github.user=your-github-handle
@@ -107,7 +122,7 @@
 
 ## Project layout
 
 The plugin runs **per Gradle project** (per `build.gradle.kts`). For a multi-module repo where only one module is the deployable, apply it only there:
 
 ```mermaid
 flowchart TB

build/troubleshooting.mdx

@@ -39,7 +39,7 @@
 ✗ not a Gradle project? Run 'grounds init' to scaffold, or cd to your project root
 ```
 
 You're running `grounds push` outside a Gradle project. `cd` to the directory with `gradlew` / `build.gradle.kts`.
 
 ## Manifest
 
@@ -61,6 +61,18 @@
 
 Local mode only runs Paper and Velocity. Use `grounds push --target=dev` for `minestom` / `service` workloads.
 
+### Runtime consumer starts without `plugin-grounds-runtime`
+
+Runtime-consumer artifacts do not have a standalone fallback. Install the matching `plugin-grounds-runtime` Paper or Velocity plugin in local, dev, test, and production environments.
+
+Use `/grounds-runtime` to confirm the runtime plugin is loaded and to inspect the runtime version, platform, manifest source, and provided libraries.
+
+### Runtime consumer bundles shared libraries
+
+Runtime-consumer builds fail when the final shadow JAR includes shared runtime packages such as `io/grpc`, `com/google/protobuf`, `kotlinx/coroutines`, or `kotlin`.
+
+Remove those libraries from `implementation` and rely on the runtime-consumer compile-only baseline. Keep plugin-private dependencies, such as NATS or Jackson, as `implementation`. If tests need a shared runtime library on the test runtime classpath, add it to `testImplementation`.
+
 ### `unknown baseImage`
 
 Your manifest references a base image source key that Forge does not know, or that is not allowed for the selected `type`.
@@ -108,7 +120,7 @@
 
 - `./gradlew shadowJar` produces something at `build/libs/`.
 - The glob in `grounds.yaml` (or auto-detected) matches it.
 - The Gradle plugin successfully built before upload (look at the build output).
 
 ### Build hangs in `building` for >5 minutes
 
@@ -144,7 +156,7 @@
 
 ### `OOMKilled`
 
 Pod exceeded its memory limit. Bump `resources.memory` in `grounds.yaml` (within project quota), or shrink your heap. Check Grafana for the JVM heap usage that led up to the OOM.
 
 ### Quota exceeded at admission
 
@@ -174,7 +186,7 @@
 grounds logs deployment <name>
 ```
 
 The hostname only routes to a `ready` pod — during a redeploy or crashloop you'll see 502 from the ingress.
 
 ## Auth & Grounds Account
 
@@ -187,7 +199,7 @@
 
 If you used a service-account token, it's hard-pinned to its minting project — you cannot use it elsewhere.
 
 ### Browser opens to "invalid_redirect_uri"
 
 The CLI's redirect URI must match what's configured for Grounds Account. If you self-host the identity provider or the CLI binary is stale, this can drift. Re-install the CLI.
 

docs.json

@@ -160,7 +160,8 @@
             "group": "Convention plugins",
             "pages": [
               "reference/development/gradle-plugin/index",
-              "reference/development/gradle-plugin/usage"
+              "reference/development/gradle-plugin/usage",
+              "reference/development/gradle-plugin/runtime-libraries"
             ]
           },
           {

reference/development/gradle-plugin/runtime-libraries.mdx

@@ -0,0 +1,82 @@
+---
+title: "Runtime libraries"
+description: "Share selected JVM libraries through plugin-grounds-runtime for Paper and Velocity plugins."
+---
+
+`plugin-grounds-runtime` is an internal Paper and Velocity plugin that provides selected shared JVM libraries to Grounds plugins at runtime.
+
+Runtime-consumer conventions automatically add baseline shared runtime libraries to the compile-only classpath. Plugin modules should not declare those libraries as implementation dependencies and must not bundle them in their shadow JARs.
+
+## When to use runtime consumers
+
+Use runtime-consumer conventions for internal Paper and Velocity plugins that run on Grounds base images and can require `plugin-grounds-runtime` in local, dev, test, and production environments.
+
+Use standalone conventions when a plugin must run without `plugin-grounds-runtime`.
+
+## Provided libraries
+
+- Kotlin standard library family
+- Kotlin coroutines
+- protobuf-java
+- gRPC baseline modules
+
+## Updating runtime libraries
+
+Update shared runtime libraries in `plugin-grounds-runtime`. That repository owns the runtime platform:
+
+- Paper and Velocity runtime plugin artifacts
+- `grounds-runtime-bom`, which pins the shared library versions
+- `grounds-runtime-catalog`, which is used by base images to generate `/opt/grounds/runtime-manifest.json`
+
+Runtime-consumer Gradle conventions depend on `grounds-runtime-bom` through `groundsRuntime.runtimeVersion` or the `groundsRuntime.version` Gradle property. They keep shared libraries on the compile-only classpath without declaring versions in each plugin.
+
+When a bundled runtime library changes, release `plugin-grounds-runtime` first. Then bump `groundsRuntime.version` in consumer builds and `GROUNDS_RUNTIME_PLUGIN_VERSION` in `containers` to the same released version. Do not duplicate shared library versions in Dockerfiles or consumer plugin builds.
+
+## Adding a shared dependency
+
+Add a dependency to the shared runtime only when it is common runtime surface for multiple internal Paper or Velocity plugins. Keep plugin-private clients, app-specific libraries, and test-only libraries in the consumer plugin build.
+
+1. Add or update the dependency in `plugin-grounds-runtime` under `runtime-catalog/grounds-runtime-libraries.json`.
+2. If the dependency exposes packages that can conflict with server or plugin classpaths, update the runtime relocation policy and consumer shadow exclusions.
+3. If this is a version-only update, release `plugin-grounds-runtime` and bump consumer `groundsRuntime.version`.
+4. If this adds or removes a module, also update `library-gradle-plugin` so the runtime-consumer conventions add the versionless dependency and validate the correct package prefixes.
+5. Release `plugin-grounds-runtime` before `library-gradle-plugin`, consumer plugins, and `containers`.
+
+The split is intentional:
+
+- `plugin-grounds-runtime` owns versions through `grounds-runtime-bom`.
+- `library-gradle-plugin` owns build policy: which modules are added, what gets relocated, and what must not be bundled by runtime consumers.
+- `containers` owns installation of the released runtime plugin and matching catalog.
+
+## Not provided
+
+- Paper API
+- Velocity API
+- Minestom
+- Plugin-specific clients such as NATS
+- Jackson and other private implementation dependencies
+
+## Gradle convention IDs
+
+- `gg.grounds.paper-standalone-conventions`
+- `gg.grounds.paper-runtime-consumer-conventions`
+- `gg.grounds.paper-runtime-provider-conventions`
+- `gg.grounds.velocity-standalone-conventions`
+- `gg.grounds.velocity-runtime-consumer-conventions`
+- `gg.grounds.velocity-runtime-provider-conventions`
+
+## Migrating a plugin
+
+1. Switch Paper or Velocity modules to runtime-consumer conventions.
+2. Remove shared runtime libraries from `implementation`.
+3. Keep plugin-private dependencies as `implementation`.
+4. Keep test-only runtime requirements in `testImplementation`.
+5. Add the loader dependency on `plugin-grounds-runtime`.
+6. Build and inspect the final shadow JAR.
+7. Run the plugin locally with the matching runtime plugin installed.
+
+## Debugging
+
+Run `/grounds-runtime` in Paper or Velocity to inspect the installed runtime version, platform, manifest source, and provided libraries.
+
+Runtime-consumer artifacts do not have a standalone fallback. Local, dev, test, and production environments must install the matching `plugin-grounds-runtime` plugin.