# Repository Guidelines

## Project Structure & Module Organization
- `roboimi/` is the main package: simulation code in `roboimi/envs/`, assets/helpers in `roboimi/assets/`, VLA models/config in `roboimi/vla/`, and runnable scripts in `roboimi/demos/` plus `roboimi/demos/vla_scripts/`.
- `tests/` holds `unittest` regressions for training, rollout, dataset loading, and asset resolution.
- `docs/superpowers/` stores design specs and plans.
- `docs/experiment-guide.md` store how beginning experiment
- `runs/`, `outputs/`, `swanlog/`, `.worktrees/`, and `checkpoints/` are generated experiment artifacts, not source modules.

## Build, Test, and Development Commands
- `conda env create -f environment.yml && conda activate roboimi` — create the standard environment.
- `pip install -e .` — editable install.
- `python -m unittest discover -s tests -p 'test_*.py'` — run all tests.
- `python -m unittest tests.test_train_vla_rollout_validation -v` — run one focused test module.
- `python roboimi/vla/scripts/calculate_stats.py` — regenerate normalization stats.
- `python roboimi/demos/vla_scripts/train_vla.py train.max_steps=1000` — quick training smoke test.
- `python roboimi/demos/vla_scripts/eval_vla.py eval.ckpt_path=checkpoints/vla_model_best.pt eval.num_episodes=5` — evaluate a checkpoint.

## Coding Style & Naming Conventions
- Use Python, 4-space indentation, and PEP 8–style naming.
- Prefer `snake_case` for files, functions, variables, and Hydra keys; use `CamelCase` for classes.
- Match existing Hydra namespaces such as `train.*`, `eval.*`, and `agent.*`.
- Keep diffs focused and imports tidy. Experiment names usually encode host/GPU, e.g. `...-l20g3-...`, `...-5880g1-...`, or `...-5090-...`.

## Testing Guidelines
- Tests use `unittest` and `unittest.mock`.
- Name files `tests/test_*.py` and classes `*Test`.
- Add direct regression coverage for changes to training, rollout, config, or dataset code paths.
- No strict coverage target is defined, but changed behavior should be tested and affected suites should pass before review.

## Commit & Pull Request Guidelines
- Follow existing prefixes: `feat`, `fix`, `chore`, `docs`, `debug`, optionally with scope, e.g. `feat(eval): export rollout video timing`.
- Keep commit messages imperative and specific.
- PRs should state the goal, touched configs/scripts, exact test commands, and dataset/checkpoint assumptions. Attach visual artifacts only when outputs change.

## Experiment Host Reference
- **Local workstation (`droid-z790eagleax`)** — local shell; **1× RTX 5090 32 GB**; env: `/home/droid/.conda/envs/roboimi/bin/python`.
- **5880 node (`droid-System-Product-Name`)** — username: `droid`; IP: `100.73.14.65`; connect with `ssh droid@100.73.14.65`; **2× RTX 5880 Ada 48 GB**; env: `/home/droid/miniforge3/envs/roboimi/bin/python`; trusted tailnet host.
- **L20 node (`droid-G5500-V7`)** — username: `droid`; IP: `100.119.99.14`; connect with `ssh droid@100.119.99.14`; **8× NVIDIA L20 46 GB**; env: `/home/droid/miniforge3/envs/roboimi/bin/python`; store large experiment data under `/data`.