Replace the legacy Minecraft stack with verified one-command setup

.agents/skills/minecraft-server-setup/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: minecraft-server-setup
+description: Set up and verify this repository's Minecraft Docker deployment, or diagnose its startup prerequisites. Use for fresh server startup; route existing worlds to the migration guide.
+---
+
+# Minecraft server setup
+
+Read the root README for commands and distribution choices. Use the repository's `scripts/minecraft` entrypoint from its absolute path; it resolves paths independently of the current directory.
+
+Check for `.state/settings.json`, legacy deployment paths, or existing world data first. Existing deployments need [the migration guide](../../../docs/migration.md) and a backup/restore rehearsal. Preserve their data and credentials.
+
+Python 3.11+, Docker Engine 28+, Compose plugin v2 or v5, sufficient memory and disk, and Docker access must already exist. Inspect prerequisites; report the missing prerequisite if unavailable. Host package installation, firewall/DNS changes, and unrelated Docker resources are outside this setup skill.
+
+Obtain explicit EULA acceptance from the user's request before passing `--accept-eula`. Acceptance for an isolated validation run applies only to its disposable test servers. An absent response is not consent. [START.md](../../../START.md) supplies a reusable request with explicit acceptance.
+
+For fresh setup, choose the user's distribution and topology, then run `setup --accept-eula --start` with their options. Default stable Paper differs from the latest Minecraft release; current Vanilla is an explicit distribution choice. Velocity requires Paper and modern forwarding. Select optional profiles only when wanted. Reuse identical setup options on repeat runs; investigate conflicting options rather than deleting `.state/`.
+
+Completion requires `doctor`, healthy `status`, an actual `scripts/status` protocol response at the selected gameplay address, and working `command list`. If scheduled backups were requested, inspect backup logs for a completed snapshot and the next interval. Use the backup/restore procedure in [operations.md](../../../docs/operations.md) when the user requests recovery verification. Keep generated secrets out of transcripts and source control.
+
+Report the exact software/image identities, address, service health, selected profiles, persistent data and credential paths, and any failed check. A Compose configuration or a running process alone is not completion. For template development, `scripts/validate fullDocker` implements the isolated runtime contract and exports reviewable evidence; it never validates a user's arbitrary plugins.

.github/workflows/validate.yml

@@ -0,0 +1,36 @@
+name: Validate template
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+    inputs:
+      full_runtime:
+        description: Run disposable Docker servers, backups and restore
+        type: boolean
+        default: false
+permissions:
+  contents: read
+jobs:
+  local:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+      - run: ./scripts/validate local
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
+        if: always()
+        with:
+          name: local-validation
+          path: validation-output/
+  runtime:
+    if: github.event_name == 'pull_request' || (github.event_name == 'workflow_dispatch' && inputs.full_runtime)
+    runs-on: ubuntu-24.04
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+      - run: ./scripts/validate fullDocker
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
+        if: always()
+        with:
+          name: runtime-validation
+          path: validation-output/

.github/workflows/versions.yml

@@ -0,0 +1,21 @@
+name: Verify pinned versions
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '19 8 * * 1'
+  pull_request:
+    paths: [versions.env, scripts/check-versions]
+permissions:
+  contents: read
+jobs:
+  verify:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+      - run: mkdir -p validation-output && ./scripts/check-versions > validation-output/version-check.json
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
+        if: always()
+        with:
+          name: version-verification
+          path: validation-output/

.gitignore

@@ -1,18 +1,25 @@
+.state/
+data/
+backups/
+restore*/
+validation-output/
+__pycache__/
+*.pyc
 *.jar
-*.json
-eula.txt
-*.log
-
-downloads/files/
+.env
+*.secrets.env
+configs/server/
+plugins/server/
+plugins/proxy/
+web/
+node_modules/
+servers/
+worlds/
 database/
 rcon/
-worlds/
 backup/
-servers/
-schematics/
 minimal/
-web/
-secrets.env
-*.secrets.env
-.env
 ports.env
+secrets.env
+schematics/
+downloads/files/

AGENTS.md

@@ -0,0 +1,6 @@
+# Agent instructions
+
+For server setup or startup, read `.agents/skills/minecraft-server-setup/SKILL.md`.
+For existing 1.17 deployments, read `docs/migration.md` before touching data.
+Use Python/Bash and Docker Compose. Keep code simple and free of inline comments.
+Run `scripts/validate local` for CLI/config changes; run isolated `fullDocker` for runtime or version changes.

Dockerfile.backup

@@ -0,0 +1,7 @@
+ARG BACKUP_IMAGE
+FROM ${BACKUP_IMAGE}
+RUN script=/opt/backup-loop.sh; \
+    expected='    retry ${RCON_RETRIES} ${RCON_RETRY_INTERVAL} rcon-cli save-on'; \
+    test "$(grep -Fxc "$expected" "$script")" -eq 2 && \
+    awk 'previous == "    log INFO \"waiting for rcon readiness...\"" { if ($0 != "    retry ${RCON_RETRIES} ${RCON_RETRY_INTERVAL} rcon-cli save-on") exit 1; sub(/save-on$/, "list"); changed++ } { print; previous=$0 } END { if (changed != 1) exit 1 }' "$script" > /tmp/backup-loop.patched && \
+    mv /tmp/backup-loop.patched "$script" && chmod +x "$script"

Dockerfile.backup.dockerignore

@@ -0,0 +1,3 @@
+**
+!Dockerfile.backup
+!Dockerfile.backup.dockerignore