ryanbarlow97 · Oct 8, 2026 · Oct 8, 2026
diff --git a/PLATFORM.md b/PLATFORM.md
@@ -2,7 +2,9 @@
 
 TFMC plugins target **Java 21 / Minecraft 1.21.10**, using
 `io.papermc.paper:paper-api:1.21.10-R0.1-SNAPSHOT` with `provided` scope.
-Plugin descriptors declare API 1.21.10.
+Plugin descriptors declare API 1.21.10 except TLibs and VehicleFramework, which
+retain `api-version: '1.21.4'` loader metadata. Both still compile against Paper
+1.21.10 with Java 21; their descriptor values do not change the TFMC runtime target.
 
 ## Runtime and toolchain
 

diff --git a/README.md b/README.md
@@ -10,6 +10,12 @@ guides live here.
 
 TFMC runs **Minecraft 1.21.10 on Java 21**. The [shared platform and build baseline](PLATFORM.md) defines common runtime, toolchain and validation conventions, with the current build declarations for each plugin.
 
+## Features
+
+- **Project guides** — Setup, gameplay, configuration, architecture, and operations for each active project.
+- **Shared conventions** — Platform targets, build pipelines, and documentation rules maintained in one place.
+- **Link validation** — Automated checks for local links, section anchors, and project navigation.
+
 ## Start here
 
 | Looking for… | Go to… |
@@ -98,6 +104,23 @@ This repository is public. Private source repositories and licensed binaries
 retain their existing access restrictions. Licenses, contribution policies, and
 code/API comments remain with their source projects.
 
+## Tests
+
+Run the same checks as CI with Python 3.10 and the pinned documentation dependencies:
+
+```sh
+python -m pip install -r requirements.txt
+python -m unittest discover -s scripts -p 'test_*.py'
+python scripts/check-indexes.py
+python -m mkdocs build --strict --config-file projects/CoreProtect/mkdocs.yml --site-dir /tmp/tfmc-coreprotect-site
+```
+
+The unittest suite exercises the Markdown link checker; the index check validates
+local links and project navigation across the documentation. Results are printed
+to the terminal, and the MkDocs output goes to `/tmp/tfmc-coreprotect-site`.
+There is no coverage gate. These checks do not verify remote URLs, source-code
+behavior, or live Minecraft servers.
+
 ## License
 
 Copyright (c) 2026 TF-Minecraft contributors.

diff --git a/projects/ActivityTF/README.md b/projects/ActivityTF/README.md
@@ -10,7 +10,7 @@ TFMC runs Minecraft **1.21.10**. See the [shared platform and build baseline](..
 
 Build with JDK 21 and `mvn clean verify`. The POM uses compiler release 21 and Paper API `1.21.10-R0.1-SNAPSHOT`; the loader API is `1.21.10`.
 
-Install the shared Maven plugin dependencies selected by the POM, then supply the four private `libs/` dependencies (VotingPlugin, MMOCore, MMOItems and MythicLib). `.github/scripts/prepare-release.sh` retrieves pinned ServerAssets files and checks `.github/dependencies.sha256`; it needs read access through `GH_TOKEN` (the CI `DEPS_TOKEN` secret). Output is `target/activity-<version>.jar`; CI uses a dated development version.
+Install the shared Maven plugin dependencies selected by the POM, then supply the four private `libs/` dependencies (VotingPlugin, MMOCore, MMOItems and MythicLib). `.github/scripts/prepare-release.sh` retrieves pinned ServerAssets files and checks `.github/dependencies.sha256`; it needs read access through `GH_TOKEN` (the CI `DEPS_TOKEN` secret). Output is `target/activity-<version>.jar`; pull request builds publish a dated development version.
 
 Optional runtime integrations are declared as `softdepend` in `src/main/resources/plugin.yml`; those declarations do not remove their compile-time JAR requirements. `ActivityPlugin` registers hooks for installed plugins, `ActivityManager` owns task progress and rewards, and `/activity` opens the GUI or runs permitted admin actions.
 

diff --git a/projects/ActivityTF/REWARD-POOLS.md b/projects/ActivityTF/REWARD-POOLS.md
@@ -1,6 +1,11 @@
 # Named reward pools
 
-Configuration changes can be applied with `/activity reload`.
+Configuration reloads stage reward changes for the next weekly reset. The current
+week keeps the reward selection recorded in `reward-lock.yml`; `/activity rewards`
+shows the locked week and whether an update is pending. The lock includes reward
+pools, multipliers, milestone drops, `bar.milestones` and daily reward groups.
+To deliberately replace the current week's rewards, run `/activity rewards apply`.
+These commands require `activity.admin` (operators by default).
 
 Example (replace the sample rewards with your own):
 
@@ -42,8 +47,8 @@ Whitelist only material pools, such as `pool_prologue`, and leave skin/scroll
 pools out. At multiplier 2, this gives two independent material draws per
 material milestone while a `pool_skin` milestone still awards one scroll.
 Existing configurations must add the whitelist before extra pool draws apply;
-`/activity reload` picks up changes. Fixed-item rewards retain their existing
-amount multiplier.
+`/activity reload` stages those reward changes for the next week unless staff
+apply them immediately. Fixed-item rewards retain their existing amount multiplier.
 `drop_N` selects the Nth configured milestone, so only define drops that exist.
 
 Named pools use the `pool_` prefix and are case-insensitive. Lists directly under

diff --git a/projects/AdvancedCrafting/configuration.md b/projects/AdvancedCrafting/configuration.md
@@ -33,12 +33,34 @@ Recipe/profession permissions use the configured `permission-prefix` and namespa
 | `/ac sync recipes` | Inspect stored alloy recipe synchronisation |
 | `/ac sync recipes repair` | Repair stored alloy recipe synchronisation; back up data first |
 | `/ac give alloy <id> [player]` | Give an alloy item |
+| `/ac give equipment <recipe> <ingredient.id\|alloy.id> [player] [quality]` | Give finished equipment using the separate staff permission described below |
 | `/ac alloy info <id>` | Show alloy information |
 | `/ac craft <percent>` | Arm the player's next station craft for 30 seconds, clamping quality to 0–100 |
 | `/alloy name <name>` | Name an alloy through the existing player workflow |
 
-All `/ac` actions above require the admin permission. `/alloy name` follows its
-own alloy manager checks. Consult
+All `/ac` actions above except `give equipment` require the admin permission.
+`give equipment` uses its configured permission; `/alloy name` follows its own
+alloy manager checks. Consult
 [CommandManager](https://github.com/TF-Minecraft/AdvancedCrafting/blob/main/src/main/java/net/tfminecraft/advancedcrafting/managers/CommandManager.java)
 for parsing and player/console restrictions. Use a restart when changing plugin
 JARs; configuration reload does not replace loaded classes.
+
+## Staff equipment grants
+
+`/ac give equipment <recipe> <ingredient.id|alloy.id> [player] [quality]`
+gives one finished item using a configured recipe and compatible main material.
+For example, `/ac give equipment heavy_chestplate ingredient.steel_ingot Alex 100`.
+Tab completion lists loaded recipes, compatible ingredients/alloys and online players.
+Omit the player to give to yourself; console must specify an online player.
+Quality defaults to 100 and accepts finite values from 0 to 100 (specify the player
+before quality). Alloy IDs are the loaded discovery IDs, not display names.
+
+Secondary recipe ingredients use the lowest configured tier, then ingredient ID
+alphabetically to break ties. Their stats and appearance participate normally.
+The item retains normal stats, quality sockets, appearance, tier and crafting
+provenance; no materials are consumed and no XP or activity rewards are granted.
+Full inventories drop the item at the recipient's location.
+
+Set `give-equipment-permission` in `config.yml` and run `/ac reload` to change
+access. Missing or blank settings default to `advancedcrafting.admin` (operators).
+Grant a custom permission only to staff; it does not grant other admin commands.
diff --git a/projects/AdvancedCrafting/setup.md b/projects/AdvancedCrafting/setup.md
@@ -13,8 +13,8 @@ For a new server, while stopped, create `plugins/AdvancedCrafting/` and copy the
 `recipes/`, `colour-schemes/`, `model-schemes/` and `naming-schemes/` directories
 from the source's `src/main/resources/` into it. Adapt the examples to the server's
 MMOItems templates and item paths. The current bootstrap loads these directories
-but does not extract their contents automatically; it also does not create the
-model-schemes directory. Top-level default YAML files are copied only when missing.
+and creates them when missing, but does not extract their contents automatically.
+Top-level default YAML files are copied only when missing.
 Do not overwrite existing production configuration or data during this step.
 
 Place one AdvancedCrafting release JAR in `plugins/`, start the server, and check
@@ -28,9 +28,9 @@ ServerAssets. Build from `main`. Clone TLibs `main` next to
 the source checkout as `../tlibs`:
 
 ```sh
-python3 ../tlibs/tools/install-plugins.py --pom pom.xml --mode pinned
-GH_TOKEN="$(gh auth token)" bash .github/scripts/prepare-release.sh
-mvn clean verify
+python3 ../tlibs/tools/install-plugins.py --pom pom.xml --mode pinned &&
+  GH_TOKEN="$(gh auth token)" bash .github/scripts/prepare-release.sh &&
+  mvn clean verify
 ```
 
 Pinned mode installs the versions declared in the POM. The
@@ -42,9 +42,10 @@ in the private preparation script. Licensed JARs are not bundled with the releas
 
 ## Releases
 
-PR and main builds verify the source and upload a `DEV-YYYYMMDD-HHmm` JAR plus
-exact shared dependency metadata. Numeric tags must match the
-committed Maven version. The tag workflow creates a draft release with the JAR,
-`SHA256SUMS`, and `build.json` containing source and resolved dependency provenance.
+PRs and pushes to `main` verify the source. PRs upload a `DEV-YYYYMMDD-HHmm` JAR
+plus exact shared dependency metadata; main builds do not publish development JARs.
+The release workflow sets Maven's version from the numeric tag and creates a draft
+release with the JAR, `SHA256SUMS`, and `build.json` containing source and resolved
+dependency provenance.
 Inspect the draft before publication. Use a new version for corrections; never
 replace an existing published version's bytes.
diff --git a/projects/AdvancedCrafting/verification.md b/projects/AdvancedCrafting/verification.md
@@ -4,14 +4,20 @@
 
 ## Automated evidence
 
-The source contains no unit tests. `mvn clean verify` checks source
-compilation and packaging; a successful build must not be described as gameplay
-coverage. CI uses Java 21 and publishes test reports if tests are added later.
-
-Release checks verify that the tag matches Maven, the JAR has a plugin descriptor,
-and the release checksum matches its bytes. The descriptor receives the same
-version as the JAR through Maven resource filtering. Compile ActivityTF, TFMCCore, Thievery and Recycler and run their available
-tests against the matching API version.
+With Java 21 and the [build dependencies](setup.md#build-from-source) prepared,
+run `mvn clean verify`. JUnit 5, MockBukkit and Mockito exercise crafting, alloys,
+commands, persistence and plugin boundaries. JaCoCo checks every production class
+and requires 100% instruction, branch and line coverage without exclusions.
+Surefire reports are in `target/surefire-reports/`; coverage HTML, XML and CSV
+are in `target/site/jacoco/`. Build CI uploads test and coverage reports; release
+CI uploads coverage reports. Available reports are uploaded after failures too.
+These tests do not start a live Paper server or the external plugin set.
+
+Release CI sets Maven's version from the tag, checks the packaged plugin descriptor
+against that version, and verifies the release checksum against the JAR bytes.
+The descriptor receives the same version as the JAR through Maven resource
+filtering. Compile ActivityTF, TFMCCore, Thievery and Recycler and run their
+available tests against the matching API version.
 
 ## Server smoke checklist
 

diff --git a/projects/Archaeo/README.md b/projects/Archaeo/README.md
@@ -17,8 +17,7 @@ From the source checkout, run `mvn clean verify`. The JAR is written to
 - [Gameplay guide and default tools](docs/gameplay.md)
 - [Custom-pack player guide](docs/pack-gameplay.md)
 - [Lore catalog editing](docs/lore-catalogs.md)
-- [Original design reference (Spanish)](docs/concepto.md) — includes proposals;
-  it does not establish implemented behavior.
+- [Tests, coverage and optional API contracts](docs/testing.md)
 
 Technical guides live here. Plugin code, bundled YAML defaults, and optional
 pack assets stay in [Archaeo](https://github.com/TF-Minecraft/Archaeo). TFMC-specific
@@ -27,4 +26,4 @@ settings and lore catalogs live in private
 
 ## Builds and releases
 
-See the [shared pipeline guide](../../PIPELINES.md). Pull requests and pushes to `main` build dated development JARs; matching numeric `v*` tags create draft releases with checksums.
+See the [shared pipeline guide](../../PIPELINES.md). Pull requests and pushes to `main` verify the source; only pull requests publish dated development JARs. Numeric `v*` tags supply the release version and create draft releases with checksums.
diff --git a/projects/Archaeo/docs/testing.md b/projects/Archaeo/docs/testing.md
@@ -0,0 +1,31 @@
+# Testing
+
+[Project index](../README.md)
+
+With Java 21 and Maven installed, run `mvn clean verify`. Tests exercise domain
+rules, YAML persistence, and plugin workflows using JUnit 4, Mockito, and MockBukkit.
+Surefire test results are in `target/surefire-reports/`.
+JaCoCo measures all production classes and writes its HTML report to
+`target/site/jacoco/index.html` and machine-readable results to
+`target/site/jacoco/jacoco.xml`. No minimum coverage gate is enforced. The Build
+workflow uploads the test and coverage reports.
+
+Tests should assert gameplay behavior, data preservation, or failure handling.
+Do not add tests solely to execute a line or manufacture unreachable states to
+increase coverage. MockBukkit tests do not replace testing on a real Paper server
+with the optional ItemsAdder and MMOItems integrations installed.
+
+Adapter contract tests can also run against locally supplied plugin jars:
+
+```sh
+mvn -Ppack-api-tests clean verify \
+  -Ditemsadder.jar=/path/to/ItemsAdder.jar \
+  -Dfastnbt.jar=/path/to/FastNbt-jar.jar \
+  -Dmmoitems.jar=/path/to/MMOItems.jar \
+  -Dmythiclib.jar=/path/to/MythicLib.jar
+```
+
+These tests bind the actual API classes and mock their external operations; they
+do not start those plugins. The jars remain outside this repository and are used
+only on the test runtime classpath. Use the FastNbt version declared by your
+ItemsAdder jar. The ordinary test suite needs none of these files.
diff --git a/projects/ArmourShop/README.md b/projects/ArmourShop/README.md
@@ -20,7 +20,7 @@ Run `mvn clean verify` to build and run the available tests; use `mvn clean inst
 
 Required plugins declared by the manifest: TLibs, ItemsAdder, TFMCWeb.
 
-Startup loads `config.yml`, `categories.yml`, `base-sets.yml`, `permission-groups.yml` and `Categories/`, then starts pack pulling and catalog sync. `/armourshop` provides the shop and admin subcommands. `armourshop.admin` defaults to false, so grant it explicitly to administrators. Follow the integration guides below for the gateway, approval and ItemsAdder pack workflow.
+Startup loads `config.yml`, `categories.yml`, `base-sets.yml`, `permission-groups.yml` and `Categories/`, then starts pack pulling and catalog sync. `/armourshop` provides the shop and admin subcommands. `armourshop.admin` defaults to operators; grant it explicitly to other administrators. Follow the integration guides below for the gateway, approval and ItemsAdder pack workflow.
 
 ## Guides
 

diff --git a/projects/BarterShops/README.md b/projects/BarterShops/README.md
@@ -2,7 +2,7 @@
 
 [Source repository](https://github.com/TF-Minecraft/BarterShops) · [All projects](../../README.md)
 
-Sign-based item shops with barter, DenarEconomy payments and faction embargo checks.
+Sign-based item shops with DenarEconomy payments and faction embargo checks.
 
 TFMC runs Minecraft **1.21.10**. See the [shared platform and build baseline](../../PLATFORM.md) for runtime, build and validation conventions.
 
@@ -14,7 +14,23 @@ Install these matching Java 21 TFMC artifacts into local Maven before building:
 
 Populate `libs/` with the exact files and hashes listed in `.github/dependencies.sha256`. `.github/scripts/prepare-release.sh` downloads those pinned private assets when supplied with the approved dependency token.
 
-Run `mvn clean verify` to build and run the available tests; use `mvn clean install` when another plugin needs the result as a Maven dependency. The plugin JAR is written under `target/`. Gameplay and web integration checks on the Minecraft 1.21.10 server remain separate from build verification.
+Install the pinned shared plugin dependencies, download the private build
+inputs, then run the build with Java 21. In Bash:
+
+```bash
+python3 path/to/TLibs/tools/install-plugins.py --pom pom.xml --mode pinned &&
+  (read -rsp 'ServerAssets token: ' GH_TOKEN && echo && export GH_TOKEN &&
+    bash .github/scripts/prepare-release.sh) &&
+  mvn clean verify
+```
+
+The installer comes from a separate TLibs checkout
+(`git clone https://github.com/TF-Minecraft/TLibs.git`); point `path/to/TLibs` at it. The token needs Contents read access
+to TF-Minecraft/ServerAssets. The prompt keeps it out of shell history, the
+subshell keeps it out of your session and Maven, and Maven only runs if both
+preparation steps succeed. CI supplies it from `DEPS_TOKEN`.
+
+Use `mvn clean install` when another plugin needs the result as a Maven dependency. The plugin JAR is written under `target/`. Gameplay and web integration checks on the Minecraft 1.21.10 server remain separate from build verification.
 
 ## Runtime and configuration
 

diff --git a/projects/BirdMessenger/README.md b/projects/BirdMessenger/README.md
@@ -14,7 +14,23 @@ Install these matching Java 21 TFMC artifacts into local Maven before building:
 
 Populate `libs/` with the exact files and hashes listed in `.github/dependencies.sha256`. `.github/scripts/prepare-release.sh` downloads those pinned private assets when supplied with the approved dependency token.
 
-Run `mvn clean verify` to build and run the available tests; use `mvn clean install` when another plugin needs the result as a Maven dependency. The plugin JAR is written under `target/`. Gameplay and web integration checks on the Minecraft 1.21.10 server remain separate from build verification.
+Install the pinned shared plugin dependencies, download the private build
+inputs, then run the build with Java 21. In Bash:
+
+```bash
+python3 path/to/TLibs/tools/install-plugins.py --pom pom.xml --mode pinned &&
+  (read -rsp 'ServerAssets token: ' GH_TOKEN && echo && export GH_TOKEN &&
+    bash .github/scripts/prepare-release.sh) &&
+  mvn clean verify
+```
+
+The installer comes from a separate TLibs checkout
+(`git clone https://github.com/TF-Minecraft/TLibs.git`); point `path/to/TLibs` at it. The token needs Contents read access
+to TF-Minecraft/ServerAssets. The prompt keeps it out of shell history, the
+subshell keeps it out of your session and Maven, and Maven only runs if both
+preparation steps succeed. CI supplies it from `DEPS_TOKEN`.
+
+Use `mvn clean install` when another plugin needs the result as a Maven dependency. The plugin JAR is written under `target/`. Gameplay and web integration checks on the Minecraft 1.21.10 server remain separate from build verification.
 
 ## Runtime and configuration