diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..f337ffc9
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,71 @@
+# AGENTS.md
+
+## Cursor Cloud specific instructions
+
+### What runs here
+CyberVerse is a multiplayer mod/framework for Cyberpunk 2077. Only the **server**
+(`server/`) can be built and run in this Linux cloud environment. The **client**
+(`client/`) is a Windows-only game plugin (RED4ext/redscript) that requires the actual
+Cyberpunk 2077 game, so it cannot be built or run here — CI builds it separately on Windows.
+
+The server is a self-contained, in-memory, stateful process (no database or external
+services). It has two parts compiled together:
+- `server/Native` — C++ networking layer (GameNetworkingSockets via vcpkg), built into
+  `libCyberverse.Server.Native.so`.
+- `server/Managed` — the .NET 9 game-logic server (`Cyberverse.Server`) which P/Invokes the native lib.
+
+It listens on **UDP port 1337** (GameNetworkingSockets; binds `udp6` dual-stack, so
+IPv4 `127.0.0.1` clients work).
+
+### Toolchain (pre-installed in the snapshot)
+- .NET 9 SDK at `~/.dotnet` (on `PATH` via `~/.bashrc`; `DOTNET_ROOT=~/.dotnet`).
+- vcpkg at `~/vcpkg` (`VCPKG_ROOT=~/vcpkg`), plus `ninja`, `cmake`, `g++`.
+- The vcpkg deps are cached under `~/vcpkg` and `server/Native/vcpkg_installed`.
+
+### Non-obvious gotchas
+- **`c++`/`cc` must be gcc, not clang.** The base image's `c++` alternative points to
+  `clang++`, which cannot find `libstdc++` and breaks the vcpkg compiler-detection step
+  ("cannot find -lstdc++"). This snapshot already runs
+  `update-alternatives --set c++ /usr/bin/g++` and `--set cc /usr/bin/gcc`. If you hit that
+  error again, re-apply those.
+- **Use the `x64-linux-dynamic` triplet, not the default `x64-linux`.** The default triplet
+  is static and does not export the `GameNetworkingSockets::GameNetworkingSockets` CMake
+  target that `server/Native/CMakeLists.txt` expects (only the `_s` static target). Building
+  dynamic produces the shared `.so` targets the project needs (this matches the Docker base
+  image behavior). Both are built into `server/Native/vcpkg_installed/`.
+- **Native lib name for P/Invoke:** the managed `DllImport` uses `Cyberverse.Server.Native`,
+  which .NET resolves to `libCyberverse.Server.Native.so`. Copy the freshly built `.so` into
+  the managed output dir (or put it on `LD_LIBRARY_PATH`) before running.
+- There is **no automated test suite** and **no headless client** in the repo; the game
+  client is the only real client. To smoke-test the server end-to-end without the game, write
+  a small GameNetworkingSockets client that sends an `InitAuth` (protocol version must equal
+  `PROTOCOL_VERSION_CURRENT = 0`) then `PlayerJoinWorld`, using `shared/protocol` headers +
+  `zpp_bits` so it is wire-compatible.
+
+### Build & run the server (from repo root)
+```bash
+# 1. Native C++ lib (dynamic triplet is required)
+cmake -S server/Native -B server/Native/build -G Ninja \
+  -DCMAKE_TOOLCHAIN_FILE="$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake" \
+  -DVCPKG_TARGET_TRIPLET=x64-linux-dynamic -DCMAKE_BUILD_TYPE=Debug
+cmake --build server/Native/build --config Debug
+
+# 2. Managed .NET server
+dotnet build server/Managed -c Debug
+
+# 3. Run: native .so + its vcpkg deps must be resolvable
+cp server/Native/build/src/libCyberverse.Server.Native.so server/Managed/bin/Debug/net9.0/
+LD_LIBRARY_PATH=server/Native/build/src:server/Native/build/vcpkg_installed/x64-linux-dynamic/debug/lib \
+  server/Managed/bin/Debug/net9.0/Cyberverse.Server
+```
+A successful auth+join logs `Player <name> authenticated` and `Player <name> joined the world`.
+
+### Docker (the README's sanctioned production path)
+`server/Dockerfile` builds and runs the server (needs `cp -r shared/protocol server/protocol`
+first). Docker is **not** installed in this environment by default; the local build above is
+the fast dev-iteration path.
+
+### Lint / test / build reference
+- Build/lint the managed server: `dotnet build server/Managed -c Debug` (warnings only; no
+  dedicated linter is configured — Codacy runs externally in CI).
+- No unit/integration test project exists.