From 63bab26536c79a4e53bca041bd76460671ba7602 Mon Sep 17 00:00:00 2001
From: Taylor Howell <taylorhowell@google.com>
Date: Mon, 16 Mar 2026 06:48:30 -0700
Subject: [PATCH] MuJoCo Warp documentation: CCD margin

PiperOrigin-RevId: 884410781
Change-Id: I61171639503ce2a08c79c0e99ed5ebc09c36bf63
---
 doc/mjwarp/index.rst | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/doc/mjwarp/index.rst b/doc/mjwarp/index.rst
index 34e1be47..d2b91fa0 100644
--- a/doc/mjwarp/index.rst
+++ b/doc/mjwarp/index.rst
@@ -988,3 +988,27 @@ is available by setting the ``NATIVECCD`` disable flag:
 
 The specialized collider generates up to 8 contact points, compared to up to 4 for the convex pipeline, and may improve
 contact stability for tasks involving box stacking or manipulation.
+
+.. TODO(taylorhowell): update this section once multiccd is on by default.
+
+CCD margin
+----------
+
+Non-zero :ref:`geom margin <body-geom-margin>` or :ref:`pair margin <contact-pair-margin>` is not supported with certain
+CCD colliders and will raise a ``NotImplementedError`` when calling :func:`mjw.put_model <mujoco_warp.put_model>`:
+
+.. list-table::
+   :width: 90%
+   :align: left
+   :widths: 3 3 4
+   :header-rows: 1
+
+   * - Geom pair
+     - Scenario
+     - Workaround
+   * - box-box, box-mesh, mesh-mesh
+     - :ref:`MULTICCD <option-flag-multiccd>` enabled
+     - Set margin to ``0`` or do not enable ``MULTICCD``
+   * - box-box
+     - :ref:`NATIVECCD <option-flag-nativeccd>` enabled (on by default)
+     - Set margin to ``0`` or disable ``NATIVECCD``