docs: improve Rumble client guidance

CONTRIBUTING.md

@@ -1,7 +1,34 @@
-# Contributing
+# Contributing to the Rumble Client
 
-This repository accepts changes through pull requests. Keep each pull request focused, add focused tests for behavior changes, and run `./gradlew build` before requesting review.
+There are two different ways to contribute to the Rumble:
 
-Do not add credentials, contributor tokens, replay evidence, cached bot sources, or ranked journals to Git. The client may open a result issue, but it must never receive credentials that can write repository content, branches, releases, packages, Pages, facts, or projections.
+- To donate battle results, follow [Run ranked Rumble battles](https://robocode.dev/rumble/client-guide). You do not need to change this repository.
+- To improve the client itself, open a focused pull request here.
 
-Changes to published envelope, configuration, or local-state contracts must be versioned and coordinated with the capability document that owns this contract in the Tank Royale repository: [`CAP-016-rumble-client`](https://github.com/robocode-dev/tank-royale/tree/main/docs/capabilities/CAP-016-rumble-client).
+## Develop the client
+
+Keep a compatible Tank Royale checkout beside this repository, then run:
+
+```shell
+./gradlew --no-configuration-cache -PtankRoyaleSource=../tank-royale clean build
+```
+
+On PowerShell, quote the property argument:
+
+```powershell
+.\gradlew.bat --no-configuration-cache "-PtankRoyaleSource=../tank-royale" clean build
+```
+
+Add focused tests for behavior changes and make sure the complete build passes before requesting review.
+
+## Protect user data and credentials
+
+Never commit contributor tokens, `rumble-client.json`, replay evidence, cached bot sources, ranked journals, or other files from the configured work directory.
+
+The client may create and read result issues. It must never receive credentials that can write repository contents, branches, releases, packages, Pages, facts, or projections. Keep the battle phase separate from the submission credential, and preserve the container boundary that prevents bot code from receiving external network access or tokens.
+
+## Keep published contracts compatible
+
+Configuration, submission-envelope, receipt, journal, and local-state formats are published contracts. Changes must be versioned and coordinated with the capability document that owns this contract in the Tank Royale repository: [CAP-016-rumble-client](https://github.com/robocode-dev/tank-royale/tree/main/docs/capabilities/CAP-016-rumble-client).
+
+Keep diagnostic messages actionable. A rejected configuration, snapshot, battle, or submission should tell the user what failed and what they can do next.

GOVERNANCE.md

@@ -1,3 +1,13 @@
 # Governance
 
-The Rumble Client is maintained under the Robocode Dev organization. Contributors propose changes through pull requests; maintainers review and merge them. Repository administrators maintain at least three organization owners and conduct the Rumble fork drill described in the Tank Royale Rumble design.
+The Robocode Dev organization maintains the Rumble Client. Contributors propose changes through pull requests; maintainers review and merge them.
+
+## Review authority
+
+Maintainers decide which client changes are accepted. Changes to ranked behavior, public file formats, credential handling, or the execution boundary require tests and coordinated review with the Tank Royale and `rumble-data` contracts.
+
+Repository administrators maintain at least three organization owners. No client maintainer may bypass the rule that ranked facts are written only by `rumble-data` automation.
+
+## Continuity
+
+Administrators take part in the quarterly Rumble fork drill. The drill verifies that a new maintainer can build the client and reconnect it to forked bot and data repositories using only public source and documentation.

README.md

@@ -1,9 +1,11 @@
 # Tank Royale Rumble Client
 
-The Rumble Client runs local Tank Royale battles against the published Rumble catalog. Ranked mode validates the current engine and catalog pin, journals every completed result with replay evidence, and submits batches through the Rumble data repository's issue inbox. Practice mode never creates a ranked record or submission.
+The Rumble Client lets your computer contribute ranked battles to the Tank Royale Rumble. It downloads the reviewed bot catalog, chooses an under-sampled matchup, runs the battle locally, keeps replay evidence, and submits the result through the Rumble data repository.
 
 This project is part of the [Tank Royale](https://github.com/robocode-dev/tank-royale) ecosystem; the client's public contracts (configuration, journal, and submission format) are documented there.
 
+For the complete newcomer-friendly walkthrough, including registration and token setup, read [Run ranked Rumble battles](https://robocode.dev/rumble/client-guide). This README is the technical reference for the source checkout.
+
 ## Quickstart (Docker, recommended)
 
 Docker is the recommended way to build and run the client: it supplies the complete Java, .NET, Python, and Node.js environment every ranked bot needs, and is the isolation boundary for running reviewed-but-untrusted bot code. Docker Engine or Docker Desktop is required for this path.
@@ -25,23 +27,23 @@ The client tracks posted batches locally and only drops them once their receipt
 
 ## Building `rumble-client` itself
 
-Most contributors only need the Quickstart above. If you're changing this repository's own Java code, you need to build and test it, which still needs Gradle — but not installed on your machine. Run it inside a Gradle image matching this repository's pinned wrapper version (`gradle/wrapper/gradle-wrapper.properties`, currently 9.6.1), with your checkout bind-mounted:
+Most contributors only need the Quickstart above. If you're changing this repository's own Java code, you need to build and test it, which still needs Gradle — but not installed on your machine. Run it inside a Gradle image matching this repository's pinned wrapper version (`gradle/wrapper/gradle-wrapper.properties`, currently 9.7.1), with your checkout bind-mounted:
 
 ```shell
-docker run --rm -it -v "${PWD}:/workspace" -w /workspace gradle:9.6.1-jdk17 gradle build
+docker run --rm -it -v "${PWD}:/workspace" -w /workspace gradle:9.7.1-jdk17 gradle build
 ```
 
-The same command works unchanged on PowerShell. Note this is a different Gradle version than the `gradle:8.14.3-jdk17` image the `Dockerfile`'s own build stage starts from — that stage still runs `./gradlew` inside it precisely so the wrapper's pinned 9.6.1 is what actually builds the release, regardless of the base image's bundled version. Keep the two in sync if either changes.
+The same command works unchanged on PowerShell. The Dockerfile's build stage uses the same Gradle 9.7.1 image, and its wrapper invocation keeps the build reproducible. Keep the image and wrapper versions in sync if either changes.
 
 This repository currently depends on an unreleased Tank Royale Battle Runner version, built from a local Tank Royale checkout rather than a published Maven artifact — that's why CI and the `Dockerfile`'s own build stage pass `-PtankRoyaleSource=<path>`. To build against a local Tank Royale checkout the same way, mount it alongside your `rumble-client` checkout and add that property:
 
 ```shell
-docker run --rm -it -v "${PWD}:/workspace" -v "${PWD}/../tank-royale:/tank-royale" -w /workspace gradle:9.6.1-jdk17 gradle -PtankRoyaleSource=/tank-royale build
+docker run --rm -it -v "${PWD}:/workspace" -v "${PWD}/../tank-royale:/tank-royale" -w /workspace gradle:9.7.1-jdk17 gradle -PtankRoyaleSource=/tank-royale build
 ```
 
 This dependency becomes an ordinary published Maven Central artifact once Tank Royale releases the Battle Runner version this repository pins in `gradle.properties` — at that point this source-mount step stops being necessary.
 
-If you already have JDK 17 and Gradle installed on your machine, the equivalent host commands work identically: `./gradlew build`, or `./gradlew -PtankRoyaleSource=../tank-royale build`.
+If you already have JDK 17 and Gradle installed on your machine, the equivalent host command is `./gradlew --no-configuration-cache -PtankRoyaleSource=../tank-royale clean build`.
 
 The build produces native ZIP and TAR archives under `build/distributions/`. Run `./gradlew run --args="--check-runtimes"` to verify the required native installations; the check never installs or changes them.
 
@@ -55,6 +57,8 @@ The client validates configuration and can synchronize the current ranked input
 
 Copy `rumble-client.example.json` to `rumble-client.json`. Ranked mode requires a registered `clientId` — see [`rumble-data`'s contributing guide](https://github.com/robocode-dev/rumble-data/blob/main/CONTRIBUTING.md) for the one-time registration pull request; practice mode may omit it. The optional `workDirectory` selects the local cache, journal, and replay-evidence root and defaults to `.rumble-client` beside the configuration file. Do not commit the resulting file or any token.
 
+Use one game type per configuration with the current command-line client. `--run` executes one battle using the first configured game type in contract-name order. `myBots` may list the names of active bots or teams owned by you, without version numbers; under-sampled matchups involving those entries receive priority. `battlesPerSession` is validated for the session contract, but the current one-battle command does not consume it.
+
 ## Docker and Podman development image
 
 The non-published development image can be built and run with Docker Engine, Docker Desktop, or Podman. The examples below use Docker; replace `docker` with `podman` when invoking the image directly. On Windows, Podman Desktop needs a running Linux virtual machine and can use WSL2 or Hyper-V as the provider; choose the provider when creating the machine. Podman Desktop/WSL2 on Windows and rootless Podman on Linux have both been manually verified for this image; neither is part of CI.

SECURITY.md

@@ -1,5 +1,19 @@
 # Security policy
 
-Report a vulnerability privately to the Tank Royale maintainers rather than opening a public issue. Do not include credentials, replay evidence, journal contents, or unpublished bot sources in the report.
+Report vulnerabilities privately to the Tank Royale maintainers. Do not open a public issue containing exploit details, credentials, replay evidence, journal contents, or unpublished bot source.
 
-The client treats all remote catalog, projection, and submission data as untrusted input. Tokens are supplied only to the submission phase and must have no repository-content write permission. The container battle phase receives neither external network access nor a submission token. Native execution is supported but runs reviewed bot code with the contributor's host permissions and does not provide container isolation.
+## Trust boundaries
+
+The client treats the remote bot catalog, source trees, engine pin, matchmaking projections, issue contents, and submission receipts as untrusted input. It validates schemas, repository identities, source hashes, bot identities, and the engine behavior version before ranked execution or journal changes.
+
+## Credentials
+
+The submission token belongs only to the submission phase. Use a fine-grained GitHub token limited to read and write Issues access for `robocode-dev/rumble-data`; never grant repository-content, branch, release, package, or Pages write permission. Supply it through `RUMBLE_CLIENT_TOKEN` at runtime and do not store it in configuration or scripts.
+
+## Container execution
+
+The container battle phase receives neither external network access nor a submission token. Use the read-only root filesystem, dropped capabilities, and finite resource limits provided by the launchers. Native execution is supported, but it runs reviewed bot code with the contributor's host permissions and does not provide container isolation.
+
+## Sensitive local files
+
+The work directory contains cached bot sources, the ranked journal, and replay evidence. Keep it out of Git, restrict access to it, and back it up if you may need evidence for a disputed result. Remove access tokens from the environment after submission.