docs: finalize release manifest and experiment semantics

README.md

@@ -15,7 +15,7 @@ tags:
 MimicIK is a research checkpoint collection for learned robot inverse kinematics. The release contains MIP/SuDeepDiT, ChiUNet, pure-MLP, diffusion UNet, RoboTwin, FK-loss ablation, and recovery checkpoints produced by the NatureIK codebase.
 
 Source code: [RedAmancy918/NatureIK](https://github.com/RedAmancy918/NatureIK)  
-Release code revision: `fd6f8d026475b1cd0da01a1ea1aa41b015faa348`
+Executable training/evaluation revision: `fd6f8d026475b1cd0da01a1ea1aa41b015faa348`. Documentation and experiment-semantics audit: `e66b7b389cae9eba4012fabedd9c0c9534a4f8d2` (documentation plus a non-functional code-comment correction).
 
 ## Repository layout
 
@@ -29,7 +29,7 @@ Release code revision: `fd6f8d026475b1cd0da01a1ea1aa41b015faa348`
 | `models/comparison_imports/` | NoStatic joint-loss comparison checkpoint | 1 | 0.14 GB |
 | `models/main_recovery/` | Recovery runs for main MIP experiments | 15 | 2.13 GB |
 
-The release contains 185 weight files plus 67 YAML configuration/provenance files. Datasets, W&B run data, raw training logs, cached outputs, and local environments are intentionally excluded.
+The release contains 185 weight files plus 62 YAML configuration/provenance files (247 files; 48,200,787,547 logical bytes before Xet deduplication). Datasets, W&B run data, raw training logs, cached outputs, and local environments are intentionally excluded. Five W&B-generated YAML metadata copies are also excluded because the corresponding canonical run/Hydra configurations are already included.
 
 ## Model interface
 
@@ -43,17 +43,18 @@ The AIRBOT IK checkpoints are single-arm policies:
 
 The dual-arm service evaluates two single-arm observations with `batch=2`, then combines the two 6D joint outputs with two external gripper values to form a 14D robot command. The gripper dimensions are not predicted by these IK checkpoints.
 
-SudeepDiT depth (for example, 8 transformer layers) describes network architecture. MIP sampling steps describe iterative inference. These are independent settings.
+SudeepDiT depth (for example, 8 transformer layers) describes network architecture. The MIP sampler in this code performs exactly two network evaluations (zero-start coarse prediction, then refinement at `t=0.9`). Architecture depth, these two inference evaluations, and optimizer-update count are independent concepts.
 
 ## Important experiment semantics
 
 - `models/comparison_imports/joint_loss_nostatic_20260807/` is the Aug-2026 NoStatic model trained with a single joint update: `MIP loss + 0.1 * FK loss`, followed by one backward pass and one optimizer step.
-- Historical May-2026 MIP+FK checkpoints were produced by the legacy optimizer behavior: a MIP optimizer step followed by a separate FK optimizer step. Historical configs predate the `fk_update_strategy` field; use `task.fk_update_strategy=legacy_two_step` with current code when exact reproduction is required.
+- Historical May-2026 MIP+FK checkpoints were produced by the legacy optimizer behavior: a MIP step/gradient clear/EMA update, one scheduler advance, then a separate FK step at the newly scheduled learning rate. The FK step has no trailing gradient clear or EMA update, so its gradient is accumulated into the next outer step's MIP backward. Historical configs predate the `fk_update_strategy` field; use `task.fk_update_strategy=legacy_two_step` with current code when exact reproduction is required.
 - “Two-step MIP inference” and “legacy two-step optimizer updates” are different concepts.
+- A `*-final.pt` file contains final-step weights, but the `val_loss` embedded in its filename is the run's historical best and may not be the final step's own validation loss.
 
 ## Data and evaluation caveats
 
-- The historical and NoStatic models do not all share the same training dataset, split, scheduler, or normalizer. Cross-family numbers should not be interpreted as a loss-only ablation unless those factors are held fixed.
+- The historical and NoStatic models do not all share the same training dataset, split, scheduler, or normalizer. Cross-family numbers should not be interpreted as a loss-only ablation unless those factors, initialization seeds, checkpoint selection, and evaluation data are held fixed. Equal outer steps also give `legacy_two_step` twice as many AdamW updates as `joint`, so outer-step-matched and optimizer-update/compute-matched comparisons answer different questions.
 - The corrected rotation metric is the target-relative SO(3) geodesic angle. Results produced before the metric fix must not be compared as rotation error.
 - The 224-episode tok2 evaluation set used in recent comparisons is a held-out validation subset (61,317 frames), not an independent test set.
 - Datasets are not included in this model repository. YAML files preserve the original local paths for provenance; replace those paths for your machine.

UPLOAD_MANIFEST.md

@@ -9,12 +9,12 @@ Excluded assets: datasets, W&B directories, metrics JSONL, text training logs, H
 | Source category | Destination | Files | Weight files | Bytes |
 |---|---|---:|---:|---:|
 | `experiments/checkpoints/main` | `models/main` | 79 | 64 | 9,244,705,144 |
-| `experiments/checkpoints/natureik_unet` | `models/natureik_unet` | 58 | 30 | 30,565,283,733 |
+| `experiments/checkpoints/natureik_unet` | `models/natureik_unet` | 53 | 30 | 30,565,246,651 |
 | `experiments/checkpoints/pure_mlp_ik` | `models/pure_mlp_ik` | 42 | 35 | 453,871,027 |
 | `experiments/checkpoints/robotwin` | `models/robotwin` | 35 | 25 | 3,543,308,385 |
 | `experiments/checkpoints/fk_weight_ablation` | `models/fk_weight_ablation` | 18 | 15 | 2,125,959,678 |
 | `experiments/checkpoints/comparison_imports` | `models/comparison_imports` | 2 | 1 | 141,738,139 |
 | `mip/checkpoints/main_recovery` | `models/main_recovery` | 18 | 15 | 2,125,958,523 |
-| **Total** | `models/` | **252** | **185** | **48,200,824,629** |
+| **Total** | `models/` | **247** | **185** | **48,200,787,547** |
 
-The byte totals above describe the selected local files before Xet deduplication and repository-side storage accounting.
+The byte totals above describe the selected local files before Xet deduplication and repository-side storage accounting. The 62 YAML files are the canonical run/Hydra configurations adjacent to the weights; five W&B-generated `wandb/run-*/files/config.yaml` metadata copies were deliberately excluded because their canonical configurations are already present.