Updates docs.

AGENTS.md

@@ -0,0 +1,90 @@
+# Score Keeper: Shared Working Rules
+
+These rules apply to agents and human contributors. Start with
+[CONTRIBUTING.md](CONTRIBUTING.md) for setup, tasks, server safety, and release
+procedures; [README.md](README.md) is the user-facing behavior reference.
+
+## Quick orientation
+
+- Java 25, Gradle 9.8.0 wrapper, Paper 26.2/26.3 only; no Bukkit/Spigot target.
+- [ScoreKeeperPlugin.java](src/main/java/com/majinnaibu/minecraft/plugins/scorekeeper/ScoreKeeperPlugin.java)
+  owns lifecycle, buckets, UUID-keyed scores, YAML persistence, archives,
+  reporting, and scheduled high-score runs.
+- [ScoreBucket.java](src/main/java/com/majinnaibu/minecraft/plugins/scorekeeper/ScoreBucket.java)
+  validates immutable definitions; [ScoreReporting.java](src/main/java/com/majinnaibu/minecraft/plugins/scorekeeper/ScoreReporting.java)
+  defines audiences. [commands/](src/main/java/com/majinnaibu/minecraft/plugins/scorekeeper/commands/)
+  contains eight executors wired in `onEnable` and
+  [plugin.yml](src/main/resources/plugin.yml).
+- [CONTRIBUTING.md](CONTRIBUTING.md#project-overview-and-source-map) owns the source
+  map and architecture overview. Consult the [domain reference](docs/domain-score-tracking.md)
+  or [integration reference](docs/plugin-integration-and-event-wiring.md) only when
+  the task needs their detail. There are no built-in gameplay listeners or registered API service.
+
+## Change discipline
+
+- Inspect the source and current diff before editing. Preserve unrelated work;
+  make scoped, complete changes and document intentional behavior changes.
+- Use **Score Keeper** in human-facing prose/display text. Keep `ScoreKeeper`
+  for repository URLs, plugin ID/data folder, Gradle/artifact names, and Java
+  symbols. Preserve scraper identifiers exactly as currently stored in
+  [project-description.json](docs/project-description.json).
+  Ask before renaming existing files or changing these integration identifiers.
+- Follow existing Java patterns, Adventure components, UUID identity, and
+  plugin logging. Use Spotless rather than hand-formatting Java; preserve the
+  [AGPL header](config/license-header.txt). Do not add silent error recovery or
+  success messages for failed operations.
+- Keep state and Paper API calls on the main thread. Do not introduce async
+  map access; marshal asynchronous results through Paper's synchronous scheduler.
+- Wire command/API changes across executors, manifest, lifecycle, reporting,
+  persistence, and documentation as applicable. Preserve existing public overloads
+  and legacy YAML loading unless a migration is explicitly agreed.
+- Preserve documented quirks until intentionally changed: unguarded score
+  mutations, signed integer arithmetic, lazy score entries, case-sensitive bucket
+  IDs, shutdown-only saves, and run snapshot restoration. Do not "fix" these as
+  incidental cleanup.
+- Prefer existing helpers and dependencies. Do not introduce a service layer,
+  test harness, runtime dependency, or supported platform without a task need.
+- Edit source, not generated `build/`, `bin/`, or `.gradle/` files. Never read,
+  expose, or commit `.env` credentials, server player data, or publishing tokens.
+
+## Validation
+
+- With JDK 25/JAVA_HOME configured, use `./gradlew spotlessCheck build` for Java
+  changes (`.\gradlew.bat` on Windows). For macOS/Linux bootstrapping, use
+  `./tools/build-plugin.sh spotlessCheck`. Run narrower relevant tasks when enough.
+- `./gradlew spotlessApply` applies Java style; review the resulting diff and
+  avoid unrelated formatting churn.
+- There are currently **no Java test sources/dependencies**; `test` is
+  `NO-SOURCE`, and no `integrationTest` task exists. Never claim a build proves
+  behavior or claim JUnit coverage. When tests are added, keep normal tests
+  server-free; real Paper integration tests should be explicit/opt-in.
+- Use [human-tests.md](docs/human-tests.md) for affected runtime scenarios and
+  pre-release testing. Report checks actually run and any remaining unverified
+  behavior. For docs-only work, check relative links and metadata instead of building.
+
+## Documentation and operational safety
+
+- Keep [README.md](README.md), [Modrinth description](docs/modrinth-description.md),
+  [project-description.md](docs/project-description.md), and
+  [project-description.json](docs/project-description.json) aligned with source.
+  Validate the JSON as a slug-keyed object against
+  [projects.schema.json](docs/projects.schema.json). Keep manual scenarios
+  separate from automated coverage claims.
+- When updating [project-description.json](docs/project-description.json),
+  preserve the existing top-level project key, `id`, `title`, `docId`, and all
+  image URLs (`image.url` and `headerImage.url`, when present). These are fixed
+  in the consuming project; routine metadata updates must not reset them.
+  Preserve a null or absent `headerImage` as well. Image paths such as
+  `/projects/score-keeper/logo.png` are relative to the consuming project's
+  root, not this repository: do not resolve them locally, rewrite them as
+  repository URLs, or replace them with generated/remote image URLs.
+  Change these protected fields only when the user explicitly requests it.
+- New project plans belong in [docs/](docs/); use checkboxes for actionable
+  work only. [Modernize.md](docs/Modernize.md) supersedes the historical `.cursor`
+  plan/rules. Planning/documentation tasks should not opportunistically implement
+  the plan's code changes.
+- Do not run server start/stop, deploy, restore, tagging, or publishing operations
+  without explicit authorization. Bash start/stop currently match all local
+  Java `paper-*.jar` processes; restore replaces archived top-level items.
+  PowerShell start/stop can force termination. Prefer a clean console `stop`
+  and inspect exact server paths/processes on isolated test machines.