Update README with action space documentation and delta_legacy usage instructions

README.md

@@ -1,3 +1,70 @@
----
-license: apache-2.0
----
+---
+license: apache-2.0
+---
+
+# MIP Checkpoints
+
+Pre-trained checkpoints for the [MIP (Minimum Iterative Policy)](https://github.com/simchowitzlabpublic/much-ado-fresh) framework.
+
+## Repository Structure
+
+```
+robomimic/
+  {task}_{env_type}_{obs_type}/
+    delta_legacy/    # Original checkpoints (rot6d repr + delta controller)
+    abs/             # Absolute action space checkpoints
+    delta/           # Delta action space checkpoints (7D, no rot6d)
+    rel/             # Relative action space checkpoints
+pusht/               # PushT environment checkpoints
+kitchen/             # Kitchen environment checkpoints
+```
+
+## Robomimic Action Spaces
+
+| Action Space | Config Suffix | `abs_action` | `action_type` | Dataset | `act_dim` (single/dual) |
+|---|---|---|---|---|---|
+| **delta_legacy** | `_delta_legacy` | `true` | `delta` | `low_dim.hdf5` | 10 / 20 |
+| **absolute** | `_abs` | `true` | `absolute` | `low_dim_abs.hdf5` | 10 / 20 |
+| **delta** | `_delta` | `false` | `delta` | `low_dim.hdf5` | 7 / 14 |
+| **relative** | `_rel` | `true` | `relative` | `low_dim_abs.hdf5` | 10 / 20 |
+
+> **Important:** The majority of released robomimic checkpoints (under `delta_legacy/`) were trained
+> with the **delta_legacy** action space. You **must** use the corresponding `_delta_legacy` task
+> config to evaluate them correctly. Using the default config (which uses absolute actions) will
+> result in 0% success rate due to normalizer and controller mismatches.
+
+## Quick Start: Evaluating a Checkpoint
+
+```bash
+# Download and evaluate a delta_legacy checkpoint
+uv run examples/train_robomimic.py \
+    mode=eval \
+    task=lift_ph_state_delta_legacy \
+    network=chiunet \
+    optimization.loss_type=mip \
+    optimization.model_path="path/to/lift_ph_state_mip_chiunet_256_seed3_success100.pt"
+```
+
+### Available Task Configs
+
+Each robomimic task has configs for all four action spaces:
+
+- `lift_ph_state_delta_legacy`, `lift_ph_state_abs`, `lift_ph_state_delta`, `lift_ph_state_rel`
+- `can_ph_state_delta_legacy`, `can_ph_state_abs`, `can_ph_state_delta`, `can_ph_state_rel`
+- `square_ph_state_delta_legacy`, `square_ph_state_abs`, `square_ph_state_delta`, `square_ph_state_rel`
+- `tool_hang_ph_state_delta_legacy`, `tool_hang_ph_state_abs`, `tool_hang_ph_state_delta`, `tool_hang_ph_state_rel`
+- `transport_ph_state_delta_legacy`, `transport_ph_state_abs`, `transport_ph_state_delta`, `transport_ph_state_rel`
+
+The `_mh` (multi-human) variants are also available (e.g., `lift_mh_state_delta_legacy`).
+
+## Checkpoint Naming Convention
+
+```
+{loss_type}_{network}_{dim}_seed{N}_success{N}.pt
+```
+
+- **loss_type**: `mip`, `flow`, `regression`, `psd`, `lsd`, `straight_flow`
+- **network**: `chiunet`, `chitransformer`, `mlp`, `sudeepdit`, `rnn`
+- **dim**: embedding dimension (e.g., `256`, `384`, `512`)
+- **seed**: random seed
+- **success**: best evaluation success rate (%)