Revise documentation structure and workflows

Author: BotRunner64

docs/docs/getting-started/download-assets.md

@@ -2,67 +2,116 @@
 sidebar_position: 1
 ---
 
-# Installation
+# Install Teleopit
 
-Teleopit supports multiple installation profiles depending on your use case.
+Install only the parts you need. All commands below run from the repository
+root and require Python 3.10 or newer.
 
-## Prerequisites
-
-- Python 3.10+
-- [Conda](https://docs.conda.io/) (recommended)
+## 1. Get the Code
 
 ```bash
-conda create -n teleopit python=3.10
-conda activate teleopit
+git clone https://github.com/BotRunner64/Teleopit.git
+cd Teleopit
 ```
 
-## Install Profiles
+You only need Git submodules for a physical G1 or optional LinkerHand control;
+those steps appear later on this page.
+
+## 2. Create a Python Environment
+
+Choose one environment tool. Do not run all three sections.
 
-### Inference Only (sim2sim)
+### uv
 
 ```bash
-pip install -e .
+uv venv --python 3.10
+source .venv/bin/activate
 ```
 
-This is sufficient for offline BVH playback and MuJoCo simulation.
+When this page shows `pip install`, you may use `uv pip install` instead.
 
-### Training
+### pip and venv
 
 ```bash
-pip install -e '.[train]'
+python3.10 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
 ```
 
-Adds `rsl-rl-lib`, `mjlab`, `wandb`, `swanlab`, and training dependencies.
+### Conda
 
-### Sim2Real (Hardware Deployment)
+```bash
+conda create -n teleopit python=3.10
+conda activate teleopit
+```
+
+Conda creates the environment; use `pip install` inside that environment to
+install Teleopit.
+
+## 3. Install the Profile You Need
+
+Each extra includes the base Teleopit package. Start with the row matching your
+goal; you can install another extra later in the same environment.
+
+| Goal | Install command | What it adds |
+|------|-----------------|--------------|
+| Run a motion controller in MuJoCo | `pip install -e .` | Core inference, GMR, MuJoCo and ONNX Runtime |
+| Use Pico in simulation or on G1 | `pip install -e '.[pico4]'` | Pico receiver plus the sim2real runtime |
+| Replay BVH on a physical G1 without Pico | `pip install -e '.[sim2real]'` | G1 runtime and OpenCV |
+| Train a controller | `pip install -e '.[train]'` | mjlab, RSL-RL and experiment loggers |
+| Record Pico sim2real episodes | `pip install -e '.[recording]'` | Pico runtime and MP4 writing |
+| Review saved recordings | `pip install -e '.[review]'` | OpenCV and the MuJoCo/Viser reviewer |
+| Use OpenNeck with Pico | `pip install -e '.[openneck]'` | Pico runtime and the OpenNeck driver |
+| Run the test suite | `pip install -e '.[dev]'` | pytest and coverage tools |
+
+## 4. Download the Matching Assets
+
+The Python package does not contain robot meshes, policies or motion datasets.
+Install the default ModelScope downloader once:
 
 ```bash
-pip install -e '.[sim2real]'
+pip install modelscope
 ```
 
-Adds `opencv-python`. You also need to initialize submodules and build/install the C++ `g1_bridge_sdk` bridge:
+Then download the bundle for your goal:
+
+| Goal | Command |
+|------|---------|
+| Simulation, Pico VR or G1 inference | `python scripts/setup/download_assets.py --only robots gmr ckpt bvh` |
+| Training from the distributed datasets | `python scripts/setup/download_assets.py --only robots data` |
+| Everything | `python scripts/setup/download_assets.py` |
+
+Use HuggingFace instead of ModelScope when needed:
 
 ```bash
-git submodule update --init --recursive
-bash scripts/setup/setup_g1_bridge.sh
+python scripts/setup/download_assets.py \
+    --source huggingface \
+    --only robots gmr ckpt bvh
 ```
 
-See [G1 Bridge SDK](../reference/g1-bridge-sdk) for details.
+The inference bundle creates `track.onnx`, the canonical G1 model, GMR files and
+a sample BVH under their expected project paths. See
+[Asset Reference](../reference/assets) for the complete inventory and asset
+group mapping.
 
-### Pico 4 VR
+## 5. Additional Setup for a Physical G1
+
+Build the C++ DDS bridge on the computer that will run Teleopit:
 
 ```bash
-pip install -e '.[pico4]'
+git submodule update --init --recursive
+bash scripts/setup/setup_g1_bridge.sh
 ```
 
-Teleopit uses the in-process `pico_bridge.PicoBridge` receiver for Pico tracking.
-Teleopit targets pico-bridge 0.2.1 and its `pico_native` tracking semantics.
-The receiver can run on a workstation PC or the robot onboard computer.
-See [Pico Sim2Sim](../tutorials/pico-sim2sim) and
-[Pico Sim2Real](../tutorials/pico-sim2real) for the full setup guides.
+The bridge is required for both Pico and BVH control on a real G1. See
+[G1 Bridge SDK](../reference/g1-bridge-sdk) if the build or robot connection
+fails.
+
+## 6. Optional Hardware
 
-Optional LinkerHand control for Pico sim2real uses local third-party packages.
-Install those packages directly after initializing the submodules:
+### LinkerHand L6 or O6
+
+Only install these local packages when `hands.enabled=true`:
 
 ```bash
 git submodule update --init --recursive
@@ -71,54 +120,54 @@ pip install -e third_party/somehand
 bash scripts/setup/download_somehand_assets.sh
 ```
 
-These packages are only required when `hands.enabled=true`.
+### OpenNeck
 
-Optional OpenNeck active-vision control for Pico sim2real uses the latest
-OpenNeck angle-control package:
+The `openneck` extra already includes the Pico profile. Calibrate the device
+before enabling it:
 
 ```bash
 pip install -e '.[openneck]'
+openneck calibrate
 ```
 
-This extra includes the Pico stack and is only required when `neck.enabled=true`.
-OpenNeck 0.2.0 calibration files use `*_center_step`, `*_min_step`,
-`*_max_step`, and `*_step_sign`; the previous normalized configuration format
-is unsupported. Run `openneck calibrate` to create a current calibration file.
+Teleopit uses the OpenNeck angle API. Old normalized calibration fields are not
+supported.
+
+### RealSense Recording or Preview
 
-### Sim2Real Recording
+Install `pyrealsense2` separately when a RealSense camera is enabled. On Arm
+machines, use conda-forge:
 
 ```bash
-pip install -e '.[recording]'
+conda install -c conda-forge pyrealsense2
 ```
 
-Adds the Pico sim2real stack plus the video dependencies used by
-`sim2real_record.yaml`. RealSense Python bindings are platform-specific: install
-`pyrealsense2` manually in the active environment when using
-`input.video.source=realsense`. On Arm machines, use conda-forge rather than the
-pip package:
+Pico body tracking itself does not require RealSense.
+
+## 7. Verify the Environment
+
+Run the core import check:
 
 ```bash
-conda install -c conda-forge pyrealsense2
+python -c "import teleopit; print('teleopit OK')"
 ```
 
-### Recording Review
+If you installed Pico or training dependencies, run the matching check:
 
 ```bash
-pip install -e '.[review]'
+python -c "from pico_bridge import PicoBridge; print('Pico OK')"
+python -c "import train_mimic.tasks; print('training OK')"
 ```
 
-Adds the OpenCV and MuJoCo/Viser dependencies used by the read-only synchronized
-sim2real recording reviewer. The review extra does not install Pico, RealSense,
-or G1 control dependencies.
-
-## Verify Installation
+For an inference profile with the `robots gmr ckpt bvh` assets, finish with one
+sample simulation:
 
 ```bash
-python -c "import teleopit; print('teleopit OK')"
-python -c "import train_mimic.tasks; print('training OK')"  # if training installed
+python scripts/run/run_sim.py \
+    controller.policy_path=track.onnx \
+    input.bvh_file=data/sample_bvh/aiming1_subject1.bvh
 ```
 
-## Next Steps
-
-- [Download Assets](download-assets) - Download models and data
-- [Quick Start](quick-start) - Run your first simulation
+The installation is ready when a MuJoCo window opens and the simulated G1
+follows the sample motion. Close the window to stop, then continue with one of
+the four task-based tutorials.