From 59c51d39b3ea48d8d3a2ccf74d2646114bfda717 Mon Sep 17 00:00:00 2001
From: rampofin <148707922+rampofin@users.noreply.github.com>
Date: Thu, 22 Jan 2026 10:15:39 +0530
Subject: [PATCH] docs: document GPU backend cuDF compatibility limitations

---
 docs/reference/gpu-backend.md | 24 ++++++++++++++++++++++++
 docs/reference/toctree.txt    |  2 ++
 2 files changed, 26 insertions(+)
 create mode 100644 docs/reference/gpu-backend.md

diff --git a/docs/reference/gpu-backend.md b/docs/reference/gpu-backend.md
new file mode 100644
index 0000000000..494da3052c
--- /dev/null
+++ b/docs/reference/gpu-backend.md
@@ -0,0 +1,24 @@
+# GPU backend and cuDF compatibility
+
+## Supported cuDF versions
+
+The GPU backend is primarily tested against the cuDF versions used in CI.
+Local installations may differ due to ABI or constructor changes between
+cuDF releases.
+
+## Known limitations
+
+- Conversion of deeply nested or jagged Awkward Arrays may fail on some cuDF versions.
+- Mask handling behavior differs across cuDF releases.
+- Some issues may only reproduce in CI environments.
+
+## CI vs local environment differences
+
+CI uses pinned RAPIDS images, while local environments may expose differences
+in cuDF constructor signatures or column initialization behavior.
+
+## Common error symptoms
+
+- `TypeError` raised during cuDF column construction
+- Mask silently dropped or ignored
+- Conversion failures that do not reproduce locally
diff --git a/docs/reference/toctree.txt b/docs/reference/toctree.txt
index 496b9ff538..beae694ffc 100644
--- a/docs/reference/toctree.txt
+++ b/docs/reference/toctree.txt
@@ -317,6 +317,7 @@
 
     generated/ak.to_backend
     generated/ak.backend
+    gpu-backend
 
 .. toctree::
     :caption: Approximation and comparison
@@ -424,3 +425,4 @@
     :maxdepth: 1
 
     generated/kernels
+