docs: bring the documentation in line with what the code does

[timlandgraf]

The repo grew a second half — the viewer, dance-level evaluation, post-processing, bee-size calibration — that was never written down, and a few documented facts have since become false. This is a documentation pass over all of it, plus two small fixes.

What was wrong

• restart_server.sh loaded ckpt/noobj_rebalance_v2/best.pth; the current run is clean_split_v1.
• combcell_annotator/README.md had nearly every config value wrong: data_path: ../data (actually ../../../data), n_videos: 2 / n_frames: 3 (actually 1 / 1), a rotation: option that no longer has any effect since rotation is fixed at 0 in the code, no mention of save_csv, and an output filename annotations_<shape>_<timestamp>.csv that never had a timestamp.
• docs.txt said the raw footage on /mnt/aglandgraf/wdd/ was readable except for the berlin files. The whole directory is now nobody:nogroup and unreadable from horus and goober — same NFS id-mapping fault as beesbook_trajectory_data (INC-20055710).
• Two files were tracked by accident: 0: (empty, mistyped redirect) and 1 (239 KB of captured server stdout, itself stale — it reports 440 base recordings and a 588/66 split, currently 160 and 582/72).

What was missing

• README.md was one line. Now covers the model and the window → average → cluster pipeline, the window-level vs dance-level distinction, repo layout, setup (including that PyPI torch is CPU-only and fails silently), the data layout and annotation schema, training, evaluation and tests.
• viewer/README.md still described a ground-truth inspector. Nothing about --checkpoint/--device/--external-videos, the Raw/Averaged/Clustered prediction modes, the /eval dashboard, re-clustering, the Optuna search, the pipeline inspector, model view, or the non-destructive GT override sidecar. Its keyboard table was correct but missing P, Z, M, I, N, Delete and Escape.
• configs/README.md (new) — there was no reference for config.yaml at all. Documents every post_process key, why eval has two levels with different threshold units, what bee_size_multiplier does and why it is one global value, how to restore post_process_baseline_tim.json, and the two keys read by nothing (logging.checkpoint_dir, data.subset_size).
• scripts/README.md (new) — five scripts, no documentation. Includes the caveats: analyze_balance.py has three absolute paths to /home/landgraf/..., and propagate_gt.py is hardcoded to one sharoni recording.

Notes

Every claim was checked against the code at 587b07e rather than carried over — that is how the wrong combcell config values and the unused config keys turned up. Two things worth a second look:

• restart_server.sh binds 0.0.0.0, which I kept, but it does expose the annotation-editing endpoints to anything that can route to the machine. Flagged in the viewer README rather than changed.
• pytest was missing from requirements.txt even though the suite imports it — now added (4th commit).
• src/tests/test_dataset.py:12 imported VideoYoloDataset from src.data.dataset_tempaug, which exports VideoYoloDatasetTemporalJitter — the class was renamed and the test never followed, with the correct import left commented out directly above. A single collection error aborts the whole pytest run, so this one line was blocking all 54 tests. Fixed in the 5th commit; the suite now runs: 53 passed, 1 failed.
• The remaining failure, test_augmentations.py::test_window_augmentations, is left alone: it reads a hardcoded /home/prajna/complete_data/annotations/fps_multires_full_data.csv and cannot pass on any other machine. Same class of problem as the absolute paths in scripts/analyze_balance.py.
• @pytest.mark.slow is used in test_eval_utils_fast.py but never registered, so every run emits PytestUnknownMarkWarning. A short pytest.ini would silence it and make -m "not slow" actually work.

Three commits, independently droppable: the documentation, the restart_server.sh fix, and the junk-file removal.

🤖 Generated with Claude Code