Add comprehensive GitHub Copilot instructions for SURF-API development

[Copilot]

This PR adds a comprehensive .github/copilot-instructions.md file that provides GitHub Copilot coding agents with detailed instructions for working effectively in the SURF-API codebase.

What's included

The instructions provide exhaustive guidance covering:

Working Commands & Build System:

• Validated commands that actually work in sandboxed environments
• Honest documentation of build limitations due to missing Paper MC 1.21.8-R0.1-SNAPSHOT dependency
• Proper timeout warnings (60+ minutes) with "NEVER CANCEL" directives for long-running operations
• Alternative approaches when the build system is unavailable

Project Structure & Architecture:

• Multi-module Gradle project overview (core, bukkit, velocity, standalone, gradle-plugin)
• Key source code locations and API organization
• Technology stack details (Kotlin/Java, Gradle 9.0.0, modern toolchain)
• Dependency management via version catalog

Development Workflow:

• System requirements (Java 21, though environment limitations are documented)
• Manual validation scenarios adapted to actual build capabilities
• Code quality checking approaches when traditional build validation fails
• Troubleshooting guide with specific error messages and root causes

Critical Build Limitations:
The instructions honestly document that this repository cannot be fully built in standard sandboxed environments due to:

• Missing external dependencies (Paper MC development bundles)
• Required access to private repositories (repo.slne.dev)
• Network connectivity requirements

Why this approach

Rather than providing instructions that don't work, this file gives agents realistic expectations and practical alternatives for code development, focusing on source code analysis, file system operations, and manual validation when the build system is unavailable.

The instructions follow an imperative tone throughout and prioritize validated, working approaches over aspirational build commands that fail in practice.

Fixes #128.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• repo.papermc.io
  • Triggering command: /usr/lib/jvm/temurin-17-jdk-amd64/bin/java --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.invoke=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.prefs/java.util.prefs=ALL-UNNAMED --add-exports=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED --add-exports=jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.prefs/java.util.prefs=ALL-UNNAMED --add-opens=java.base/java.nio.charset=ALL-UNNAMED --add-opens=java.base/java.net=ALL-UNNAMED --add-opens=java.base/java.util.concurrent=ALL-UNNAMED --add-opens=java.base/java.util.concurrent.atomic=ALL-UNNAMED --add-opens=java.xml/javax.xml.namespace=ALL-UNNAMED -Xmx4G -Dfile.encoding=UTF-8 -Duser.country -Duser.language=en -Duser.variant -cp /home/REDACTED/.gradle/wrapper/dists/gradle-9.0.0-bin/d6wjpkvcgsg3oed0qlfss3wgl/gradle-9.0.0/lib/gradle-daemon-main-9.0.0.jar -javaagent:/home/REDACTED/.gradle/wrapper/dists/gradle-9.0.0-bin/d6wjpkvcgsg3oed0qlfss3wgl/gradle-9.0.0/lib/agents/gradle-instrumentation-agent-9.0.0.jar org.gradle.launcher.daemon.bootstrap.GradleDaemon 9.0.0 (dns block)
• repo.slne.dev
  • Triggering command: /usr/lib/jvm/temurin-17-jdk-amd64/bin/java --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.invoke=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.prefs/java.util.prefs=ALL-UNNAMED --add-exports=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED --add-exports=jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.prefs/java.util.prefs=ALL-UNNAMED --add-opens=java.base/java.nio.charset=ALL-UNNAMED --add-opens=java.base/java.net=ALL-UNNAMED --add-opens=java.base/java.util.concurrent=ALL-UNNAMED --add-opens=java.base/java.util.concurrent.atomic=ALL-UNNAMED --add-opens=java.xml/javax.xml.namespace=ALL-UNNAMED -Xmx4G -Dfile.encoding=UTF-8 -Duser.country -Duser.language=en -Duser.variant -cp /home/REDACTED/.gradle/wrapper/dists/gradle-9.0.0-bin/d6wjpkvcgsg3oed0qlfss3wgl/gradle-9.0.0/lib/gradle-daemon-main-9.0.0.jar -javaagent:/home/REDACTED/.gradle/wrapper/dists/gradle-9.0.0-bin/d6wjpkvcgsg3oed0qlfss3wgl/gradle-9.0.0/lib/agents/gradle-instrumentation-agent-9.0.0.jar org.gradle.launcher.daemon.bootstrap.GradleDaemon 9.0.0 (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.