fix: update gradle plugin documentation to gradle convention plugin

tools/gradle-plugin/index.mdx

@@ -1,9 +1,9 @@
 ---
 title: "Overview"
 description: "Gradle plugin bundle providing standardized build configurations for Grounds projects"
 ---
 
-The `library-gradle-plugin` is a Gradle plugin bundle that provides standardized build configurations for Grounds projects. It consolidates common setup tasks, dependency management, and build configurations to ensure consistency across all Grounds projects while reducing boilerplate configuration.
+The `library-gradle-plugin` is a Gradle convention plugin bundle that provides standardized build configurations for Grounds projects. It consolidates common setup tasks, dependency management, and build configurations to ensure consistency across all Grounds projects while reducing boilerplate configuration.
 
 ## Quick Links
 
@@ -19,37 +19,67 @@
 
 ## Getting Started
 
 To get started with the Gradle plugin bundle:
 
 1. [Install the plugins](/tools/gradle-plugin/usage) in your project
-2. Choose the appropriate plugin for your project type:
-   - Use Root Plugin for shared repository configuration
-   - Use Paper Plugin for Paper server plugins
-   - Use Velocity Plugin for Velocity proxy plugins
+2. Apply the base conventions plugin with a version
+3. Add the project-specific conventions (Paper, Velocity, Minestom, gRPC) as needed
 
 ## Functionality
 
-The plugin bundle consists of three main plugins, each providing specific functionality:
+The plugin bundle consists of convention plugins, each providing specific functionality:
 
-### Root Plugin (`gg.grounds.root`)
+## Plugin Structure
 
-- Applies standard plugins (maven-publish, Kotlin JVM, Kapt, Spotless)
+The convention plugins build on each other. Base conventions sit at the bottom, Kotlin conventions add publishing, and the platform-specific conventions layer on top.
+
+```mermaid
+graph TB
+  kotlin["kotlin-conventions"] --> base["base-conventions"]
+  minestom["minestom-conventions"] --> kotlin
+  paperbase["paper-base-conventions"] --> kotlin
+  grpc["grpc-conventions"] --> kotlin
+  paper["paper-conventions"] --> paperbase
+  velocity["velocity-conventions"] --> paperbase
+```
+
+### Base Conventions (`gg.grounds.base-conventions`)
+
+- Applies standard plugins (Kotlin JVM, Kapt, Spotless)
 - Code formatting with Spotless (ktfmt, Google Style, 4-space indentation)
-- Configures Maven Central repository for all projects
-- Automatic Kotlin project configuration (Group: gg.grounds, version management, JVM Toolchain 25)
+- Configures Maven Central repository
+- Kotlin + Java toolchain configuration (JVM 25, Java 24)
+- Group/version defaults with optional `versionOverride` property
 - JUnit Platform for tests with full exception output
+
+### Kotlin Conventions (`gg.grounds.kotlin-conventions`)
+
 - Maven publishing to GitHub Packages
+- Maven publication naming for root and subprojects
 
-### Paper Plugin (`gg.grounds.paper`)
+### Paper Base Conventions (`gg.grounds.paper-base-conventions`)
 
 - Adds Paper repository
 - Shadow packaging configuration (Fat JAR)
-- Optional Paper API dependency (configurable via extension)
-- Automatic version replacement in plugin.yml
+- Disables default `jar` task and wires `shadowJar` into `build`
+- Standardized Shadow JAR naming
 
-### Velocity Plugin (`gg.grounds.velocity`)
+### Paper Conventions (`gg.grounds.paper-conventions`)
+
+- Paper API dependency (compileOnly)
+- Automatic version replacement in `plugin.yml`
+
+### Velocity Conventions (`gg.grounds.velocity-conventions`)
 
-- Adds Paper repository
-- Shadow packaging configuration (Fat JAR)
 - Optional Velocity API dependencies (compileOnly and kapt)
-- Automatic generation of BuildInfo class with version for dynamic plugin versioning
+- Automatic generation of `BuildInfo` class with version for dynamic plugin versioning
+
+### Minestom Conventions (`gg.grounds.minestom-conventions`)
+
+- Minestom dependency
+- JVM target attribute pinned to 25 for resolved configurations
+
+### gRPC Conventions (`gg.grounds.grpc-conventions`)
+
+- Protobuf + gRPC dependencies
+- Protobuf code generation with gRPC plugin

tools/gradle-plugin/usage.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Usage"
 description: "Step-by-step guide to install and configure the Gradle plugin bundle"
 ---
 
 The plugins are published to GitHub Packages. To use them, you need to configure your project to access the GitHub Packages Maven repository.
@@ -9,7 +9,7 @@
 
 Before installing the plugins, ensure you have:
 
 - Gradle 7.0 or higher
 - A GitHub account with access to the `groundsgg` organization
 - A GitHub personal access token with `read:packages` permission
 
@@ -17,7 +17,7 @@
 
 1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
 2. Click "Generate new token (classic)"
 3. Give it a descriptive name (e.g., "Gradle Packages Access")
 4. Select the `read:packages` scope
 5. Generate the token and copy it immediately
 
@@ -25,7 +25,7 @@
 Store your token securely. You won't be able to see it again after leaving the page.
 </Warning>
 
 ## Step 2: Configure Gradle Properties
 
 Add your GitHub credentials to `~/.gradle/gradle.properties`:
 
@@ -59,35 +59,65 @@
 
 ## Step 4: Apply the Plugin
 
-Apply the appropriate plugin in your `build.gradle.kts` file based on your project type:
+Apply the base conventions plugin with a version, then add the conventions that match your project type:
 
-### Root Plugin
+### Base Conventions (required)
 
-For root projects or shared configurations:
+Apply once per project (usually in the root project):
 
 ```kotlin build.gradle.kts
 plugins {
-    id("gg.grounds.root") version "0.1.1"
+    id("gg.grounds.base-conventions") version "0.3.0"
 }
 ```
 
-### Paper Plugin
+### Kotlin Conventions
+
+For Kotlin projects (typically shared/common modules):
+
+```kotlin build.gradle.kts
+plugins {
+    id("gg.grounds.kotlin-conventions")
+}
+```
+
+### Paper Conventions
 
 For Paper server plugin projects:
 
 ```kotlin build.gradle.kts
 plugins {
-    id("gg.grounds.paper") version "0.1.1"
+    id("gg.grounds.paper-conventions")
 }
 ```
 
-### Velocity Plugin
+### Velocity Conventions
 
 For Velocity proxy plugin projects:
 
 ```kotlin build.gradle.kts
 plugins {
-    id("gg.grounds.velocity") version "0.1.1"
+    id("gg.grounds.velocity-conventions")
+}
+```
+
+### Minestom Conventions
+
+For Minestom server plugin projects:
+
+```kotlin build.gradle.kts
+plugins {
+    id("gg.grounds.minestom-conventions")
+}
+```
+
+### gRPC Conventions
+
+For gRPC projects:
+
+```kotlin build.gradle.kts
+plugins {
+    id("gg.grounds.grpc-conventions")
 }
 ```
 
@@ -99,7 +129,22 @@
 ./gradlew tasks --all
 ```
 
-You should see tasks provided by the plugin in the output. For example, with the root plugin, you'll see Spotless formatting tasks.
+You should see tasks provided by the plugin in the output. For example, with base conventions, you'll see Spotless formatting tasks.
+
+## Overriding Paper, Velocity, or Minestom Versions
+
+Your project can request a higher Paper, Velocity, or Minestom version by declaring it in dependencies. Lower versions are not supported.
+
+- Current Paper version: `1.21.11-R0.1-SNAPSHOT`
+- Current Velocity version: `3.4.0-SNAPSHOT`
+- Current Minestom version: `2026.01.08-1.21.11`
+
+```kotlin
+dependencies {
+    // Overrides the Paper version with a higher one
+    compileOnly("io.papermc.paper:paper-api:1.21.12-R0.1-SNAPSHOT")
+}
+```
 
 ## Multi-Module Projects
 
@@ -123,25 +168,31 @@
 include("paper-plugin", "velocity-plugin")
 ```
 
-Then apply the root plugin in the root `build.gradle.kts`:
+Then apply the base conventions in the root `build.gradle.kts`:
 
 ```kotlin build.gradle.kts
 plugins {
-    id("gg.grounds.root") version "0.1.1"
+    id("gg.grounds.base-conventions") version "0.3.0"
 }
 ```
 
-And apply specific plugins in each subproject's `build.gradle.kts`:
+And apply specific conventions in each subproject's `build.gradle.kts`:
 
 ```kotlin paper-plugin/build.gradle.kts
 plugins {
-    id("gg.grounds.paper") version "0.1.1"
+    id("gg.grounds.paper-conventions")
 }
 ```
 
 ```kotlin velocity-plugin/build.gradle.kts
 plugins {
-    id("gg.grounds.velocity") version "0.1.1"
+    id("gg.grounds.velocity-conventions")
+}
+```
+
+```kotlin grpc-module/build.gradle.kts
+plugins {
+    id("gg.grounds.grpc-conventions")
 }
 ```
 
@@ -152,12 +203,12 @@
 If you encounter authentication errors:
 
 1. Verify your GitHub token has `read:packages` permission
 2. Check that `github.user` and `github.token` are correctly set in your Gradle properties
 3. Ensure the token hasn't expired
 
 ### Plugin Not Found
 
 If Gradle cannot find the plugin:
 
 1. Verify the repository URL is correct: `https://maven.pkg.github.com/groundsgg/*`
 2. Check that `gradlePluginPortal()` is included in the repositories list
@@ -165,11 +216,11 @@
 
 ### Version Updates
 
-To update to a newer version, change the version number in your `build.gradle.kts`:
+To update to a newer version, change the version number only on `gg.grounds.base-conventions`:
 
 ```kotlin build.gradle.kts
 plugins {
-    id("gg.grounds.root") version "0.1.1" // Update this version
+    id("gg.grounds.base-conventions") version "0.3.0" // Update this version
 }
 ```