docs: record GLFW 3.4 Wayland drag-drop crash + patch scar tissue

Cross-ref from study-player.md drag-drop section to environment.md so the
next agent touching drag-drop finds the real root cause (GLFW/Wayland, not
the Ruby CheckFileDrop code).

2 files changed, 33 insertions, 0 deletions

diff --git a/.agents/knowledge/environment.md b/.agents/knowledge/environment.md
index f130a40..38ae92d 100644
--- a/.agents/knowledge/environment.md
+++ b/.agents/knowledge/environment.md
@@ -20,5 +20,31 @@ Expect harmless Mesa/EGL/zink warnings on stderr in this environment
 (`libEGL warning: ... zink ...`, `Wayland: The platform does not provide the
 window position`); they are not errors.
 
+## Wayland drag-and-drop crashes on GLFW 3.4 (patched)
+raylib 6.0 vendors **GLFW 3.4** (release). Its Wayland `wl_data_offer_listener`
+(`vendor/raylib/src/external/glfw/src/wl_window.c`) only sets the `offer`
+(opcode 0) handler; `source_actions` (opcode 1) and `action` (opcode 2) are
+NULL (`wl_data_offer` is v3; those events were added in v3). Modern compositors
+(labwc, GNOME, KDE) emit source_actions/action *during a drag*, and
+libwayland-client then `wl_abort("listener function for opcode N of
+wl_data_offer is NULL")` — **the app crashes the moment a file is dragged over
+the window**, before any drop registers (glfw/glfw#2835, #2562). This is why
+drag-and-drop was "unreliable" in the rewrite but reliable in the original
+`../source` app, which uses the X11/Xdnd backend (`-D_GLFW_X11`) — a separate
+code path with none of these bugs.
+
+Fix: `patches/glfw-wayland-dnd-crash.patch` backports the upstream GLFW-master
+fix (no-op source_actions/action handlers + two NULL-deref guards in the
+data-device path). `build.zig` applies it **idempotently** before `make`
+(marker = `dataOfferHandleAction` in the file; when newly applied it deletes the
+stale `libraylib.a` so `make` actually rebuilds). The vendored file is
+gitignored, so the patch file + the build.zig step ARE the committed fix — a
+fresh checkout reproduces it. **Drop the patch once raylib vendors a GLFW
+release containing the upstream fix.**
+
+Do NOT "fix" this by re-enabling X11 (`GLFW_LINUX_ENABLE_X11=TRUE`): on a real
+Wayland session GLFW 3.4 still picks Wayland (so it wouldn't help), and forcing
+X11 reintroduces the WSLg GLX segfault above.
+
 ## Toolchain versions (pinned)
 raylib 5.5, mruby 3.3.0, RmlUi 6.1, flecs v4.1.1, Zig 0.16.0, emcc 6.0.0 (emsdk).
diff --git a/.agents/knowledge/study-player.md b/.agents/knowledge/study-player.md
index a800a8c..e0d1831 100644
--- a/.agents/knowledge/study-player.md
+++ b/.agents/knowledge/study-player.md
@@ -94,6 +94,13 @@ hand-written method `path_at(index)` was added to
 drag-and-drop. This method is registered on `Rl::FilePathList` after the
 generated registrar runs.
 
+The Ruby `CheckFileDrop` system (`game/study_player/study_player.rb`) is correct
+and identical in pattern to the original C app. If drag-and-drop is unreliable,
+the cause is NOT the Ruby — it is the GLFW/Wayland backend: see
+`.agents/knowledge/environment.md` § "Wayland drag-and-drop crashes on GLFW 3.4"
+(the `wl_data_offer` NULL-listener crash + the `patches/glfw-wayland-dnd-crash.patch`
+fix). The X11 `../source` app never hits it.
+
 ## Non-blocking seek (skip_auto_update)
 After `Rl.seek_music_stream`, raylib's miniaudio stream may briefly report the
 old position. The `skip_auto_update` counter (set to 3 frames = ~50ms at 60fps)