READMEs: model catalogue at the root, one README per directory

README.md

@@ -1,43 +1,47 @@
-# TERRA — post-trained policies (LIBERO, and real-robot arms)
+# TERRA — model checkpoints
 
-OpenVLA-7B with TERRA latent-action phase 2 (`latp2_inv` labels), post-trained with a flow-matching head and 4 query
-tokens.  One directory per policy: merged weights (`model-*.safetensors`), action/latent heads (`action_decoder.pt`),
-`dataset_statistics.json` (action un-normalisation), `ctrl_meta.json`, processor / tokenizer.
+OpenVLA-7B + TERRA latent-action phase 2 (`latp2_inv` labels), post-trained with a flow-matching action head and
+4 query tokens. **One directory = one model**, each with its own README (what it is, how to deploy it, what has been
+measured). Every deployable directory holds merged weights (`model-*.safetensors`), the action head
+(`action_decoder.pt`, required), `dataset_statistics.json` (un-normalisation), `ctrl_meta.json` and the processor.
 
-**Code:** https://github.com/DingTianxingjian/Latent_Free — branch `newton`, public, no token needed.
+**Code:** https://github.com/DingTianxingjian/Latent_Free — branch `newton` (deployment wrapper: `acdc_la/realrobot/piper_policy.py`).
 
 ```bash
 git clone -b newton https://github.com/DingTianxingjian/Latent_Free.git latent_free && cd latent_free
+huggingface-cli download Potestates/TERRA --include "<dir>/*" --local-dir .
 ```
 
-| dir | suite | demos | standard LIBERO (500 ep.) |
-|---|---|---|---|
-| `libero_10_full` | libero_10_no_noops | full | 89.0 |
-| `libero_goal_full` | libero_goal_no_noops | full | 94.4 |
-| `piper_pick_can_10k` | piper_pick_can (real robot, AgileX Piper) | 142 | n/a — real robot, see its README |
-| `press_button_terra_delta` | press_button, 4 colours (real robot, Piper) — **DELTA actions**: send `q + delta`, see its README | 95 | n/a — real robot, see its README |
-| `press_button_openvla_delta` | the matched **control** for the row above (official openvla-7b, same recipe): 1.92 vs 0.92 deg, ignores the instruction — not for deployment | 95 | n/a |
+## Which model? (快速选择)
 
-Evaluate the LIBERO ones with `acdc_la.downstream.vla.run_libero_eval_cont --pretrained_checkpoint <dir>`.
-The real-robot directory carries its own README; the deployment wrapper, the measured chunk-length and
-jitter settings, and the offline check are in `acdc_la/realrobot/` in the repo.
+| dir | role | task | action (dims 0-5) | how to run it on the Piper | status |
+|---|---|---|---|---|---|
+| `press_button_terra_delta` | **policy** | press the {blue, orange, pink, red} button | per-step **delta** `target − q` | `to_joint_targets(a, q)`, re-read `q` EVERY tick, **chunk = 1** | **pressed the button on the robot** (chunk=1; slightly off-centre). chunk ≥ 2 bends the direction — don't |
+| `piper_multi_anchored_step5500` | **policy, one model for both tasks** | press button (4 colours) + pick up the can and place it on the plate | **chunk-anchored delta** `target[s+k] − q[s]` | read `q` ONCE per chunk, `chunk_targets(chunk, q)`, execute N = 1 / 2 / 4 | experimental, latest snapshot (step 5500); not yet run on the robot |
+| `piper_multi_anchored_step2500` | same run, earlier snapshot | same | same | same | superseded by step 5500; kept for comparison |
+| `piper_pick_can_10k` | policy | `pick up the can and place it on the plate` | **absolute** joint target | send `chunk[k]` directly | offline only (3.24 deg) |
+| `press_button_openvla_delta` | **control (baseline)** | press_button | per-step delta | as `press_button_terra_delta` | official OpenVLA-7B, same recipe: 1.92 vs 0.92 deg, **ignores the colour word** — for the comparison, not for use |
+| `libero_10_full` | policy (sim) | LIBERO-10 | LIBERO EEF delta | `run_libero_eval_cont` | 89.0 % (500 episodes) |
+| `libero_goal_full` | policy (sim) | LIBERO-Goal | LIBERO EEF delta | `run_libero_eval_cont` | 94.4 % (500 episodes) |
+| `p2fft_20k` | **pretrained base**, not a policy | — | — | `INIT=./p2fft_20k` for post-training | phase 2, 20k steps on OXE |
 
-## `p2fft_20k` — the phase-2 pretrained base
+### The three action spaces on the Piper — getting this wrong drives the arm somewhere else
 
-The **base** the policies above are post-trained from, not a deployable policy: OpenVLA-7B fully fine-tuned for
-20,000 steps on OXE to predict our continuous latent action (`latp2_inv`).  `vla_full.pt` (15,081,838,026 B) is the
-VLA state dict and **`action_decoder.pt` (105,268,830 B) is required too** — `finetune_libero_ctrl.py:273`
-initialises the post-training heads from it, so a run without it starts from a random head.
+`ctrl_meta.json → action_space` says which one a directory uses, and `PiperPolicy` reads it.
 
-```bash
-huggingface-cli download Potestates/TERRA --include "p2fft_20k/*" --local-dir .
-INIT=./p2fft_20k  ...  bash acdc_la/scripts/run_vla_post2_portable.sh
-```
+* **absolute** (no `action_space` key): `chunk[k]` IS the joint target.
+* **delta** (`"delta"`): `chunk[k]` = target − measured joints *at step k*. Send `q_now + chunk[k]`, `q` re-read every
+  tick. Use **chunk = 1**: the demos were teleoperated at 30 Hz with a continuous command, so the demonstrated arm
+  runs ~0.86–2 deg/step *ahead* of where an arm that settles at each 10 Hz command would be; with chunk = N that lead
+  adds up linearly and with OPPOSITE signs on j1/j2 (−0.74 / +0.75 deg per step on pick-can) — the direction bends.
+* **delta_anchored** (`"delta_anchored"`): `chunk[k]` = target[s+k] − joints read ONCE at the chunk's start. Send
+  `q_s + chunk[k]`; the targets do not depend on how the arm tracks inside the chunk, so the tracking drift above
+  does not exist — what remains is the model's own error, which grows with k (see the directory's README).
 
-The matched control is `INIT=none`, which post-trains the official `openvla/openvla-7b` with everything else
-identical — that is how "what did phase 2 buy" is measured.
+The method ledger is `LEDGER.md` in the code repo. `HANDOFF_press_button.md` at the root of this repo is the brief
+for training a new real-robot task.
 
-`HANDOFF_press_button.md` at the root of this repo is the brief for training the next real-robot task on a
-Jetstream2 g3.xl.
+## `p2fft_20k` — the phase-2 pretrained base
 
-The method ledger for all of this is `LEDGER.md` at the repository root.
+See `p2fft_20k/README.md`. Post-training from it: `INIT=./p2fft_20k ... bash acdc_la/scripts/run_vla_post2_portable.sh`;
+the matched control is `INIT=none` (official `openvla/openvla-7b`, everything else identical).

libero_10_full/README.md

@@ -0,0 +1,11 @@
+# `libero_10_full` — LIBERO simulation policy (libero_10_no_noops)
+
+TERRA phase 2 (`p2fft_20k`) post-trained on the full `libero_10_no_noops` demonstrations, 40000 steps, flow-matching head,
+4 query tokens, chunk of 12. Merged weights; `action_decoder.pt` is the head (required).
+
+**Standard LIBERO evaluation (500 episodes): 89.0 %.**
+
+```bash
+python -m acdc_la.downstream.vla.run_libero_eval_cont --pretrained_checkpoint <this dir>
+```
+Action: the standard LIBERO 7-D end-effector delta + gripper. Simulation only — not for the Piper.

libero_goal_full/README.md

@@ -0,0 +1,11 @@
+# `libero_goal_full` — LIBERO simulation policy (libero_goal_no_noops)
+
+TERRA phase 2 (`p2fft_20k`) post-trained on the full `libero_goal_no_noops` demonstrations, 30000 steps, flow-matching head,
+4 query tokens, chunk of 12. Merged weights; `action_decoder.pt` is the head (required).
+
+**Standard LIBERO evaluation (500 episodes): 94.4 %.**
+
+```bash
+python -m acdc_la.downstream.vla.run_libero_eval_cont --pretrained_checkpoint <this dir>
+```
+Action: the standard LIBERO 7-D end-effector delta + gripper. Simulation only — not for the Piper.

p2fft_20k/README.md

@@ -0,0 +1,16 @@
+# `p2fft_20k` — the TERRA phase-2 pretrained base (NOT a deployable policy)
+
+OpenVLA-7B **fully fine-tuned for 20,000 steps on OXE** (`acdc_oxe29` mixture) to predict our continuous latent
+action (`latp2_inv`, dz 256, 4 query tokens). Every policy in this repo is post-trained from it.
+
+| file | what |
+|---|---|
+| `vla_full.pt` (15,081,838,026 B) | the VLA state dict |
+| `action_decoder.pt` (105,268,830 B) | the heads — **required**: `finetune_libero_ctrl.py` initialises the post-training heads from it; without it the head starts random |
+| the rest | processor / tokenizer / `ctrl_meta.json` |
+
+```bash
+huggingface-cli download Potestates/TERRA --include "p2fft_20k/*" --local-dir .
+INIT=./p2fft_20k DS=<your rlds dataset> ... bash acdc_la/scripts/run_vla_post2_portable.sh
+```
+The matched control (to measure what phase 2 buys) is `INIT=none`: official `openvla/openvla-7b`, same recipe.

piper_multi_anchored_step2500/README.md

@@ -1,5 +1,18 @@
 # `piper_multi_anchored_step2500` — EXPERIMENTAL, Piper press-button + pick-can, CHUNK-ANCHORED delta
 
+**Superseded by `piper_multi_anchored_step5500`** (same run, later). Kept only for comparison.
+
+**One model, two tasks** — pick the task with `unnorm_key` and the instruction:
+
+| task | `unnorm_key` | instruction |
+|---|---|---|
+| press button | `press_button_anc` | `press the {blue, orange, pink, red} button` |
+| pick can | `piper_pick_can_anc` | `pick up the can and place it on the plate` (the only instruction in the data) |
+
+**How many steps per chunk.** The per-step-delta rule "chunk = 1" (tracking drift) does NOT apply here: anchored
+targets do not depend on how the arm tracks within the chunk. What limits N is the model's own error growing with k
+(table below). Start with N = 1, then try 2 and 4 and compare. Offline numbers exist for press_button only.
+
 Same base/recipe as `press_button_terra_delta` (OpenVLA-7B + TERRA phase 2 `p2fft_20k`, LoRA r32 merged, flow head,
 4 query tokens), trained 2,500 steps on the mixture press_button (x2) + `jachansantiago/pick_can_place_plate_150_trimmed`.
 

piper_multi_anchored_step5500/README.md

@@ -1,5 +1,18 @@
 # `piper_multi_anchored_step5500` — EXPERIMENTAL, Piper press-button + pick-can, CHUNK-ANCHORED delta
 
+**Latest snapshot of this run — use this one.** Same run as `piper_multi_anchored_step2500`, 3,000 more steps.
+
+**One model, two tasks** — pick the task with `unnorm_key` and the instruction:
+
+| task | `unnorm_key` | instruction |
+|---|---|---|
+| press button | `press_button_anc` | `press the {blue, orange, pink, red} button` |
+| pick can | `piper_pick_can_anc` | `pick up the can and place it on the plate` (the only instruction in the data) |
+
+**How many steps per chunk.** The per-step-delta rule "chunk = 1" (tracking drift) does NOT apply here: anchored
+targets do not depend on how the arm tracks within the chunk. What limits N is the model's own error growing with k
+(table below). Start with N = 1, then try 2 and 4 and compare. Offline numbers exist for press_button only.
+
 Same base/recipe as `press_button_terra_delta` (OpenVLA-7B + TERRA phase 2 `p2fft_20k`, LoRA r32 merged, flow head,
 4 query tokens), trained 5,500 steps on the mixture press_button (x2) + `jachansantiago/pick_can_place_plate_150_trimmed`.
 
@@ -20,7 +33,7 @@ while True:
 ```
 Do NOT use `to_joint_targets` per tick and do not ensemble (the policy refuses / disables it).
 
-## Status — why it is experimental (step 5500 numbers: pending, see LEDGER; table below is step 2500)
+## Status — why it is experimental 
 Held-out press_button (5 episodes), open-loop target error by chunk position k (deg, mean over joints):
 
 | k | 0 | 1 | 2 | 3 | 7 | 11 |