wlgys8 · Oct 8, 2026 · Oct 7, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -11,10 +11,10 @@ MotrixLab 是构建在 MotrixSim 仿真后端之上的强化学习框架，提
 
 项目使用 UV workspace，包含以下 package：
 
-- `motrix_env_core`：backend 无关的环境框架，拥有 robot registry 与 `motrix_env_core.robots` entry-point discovery（不依赖任何 simulator 或 `motrix_robots`）
+- `motrix_env_core`：backend 无关的环境框架、配置与机器人 registry，不依赖具体 simulator
 - `motrix_env_motrixsim`：MotrixSim 仿真后端（SimBackend、scene compiler、renderer、torch frontend）
 - `motrix_env_mujoco`：仅用于编译的 MuJoCo scene 后端
-- `motrix_robots`：仿真 `RobotCfg`、模型自有关键姿态及模型 MJCF/URDF、mesh 与模型纹理资产，仅依赖 core；模型定义模块与 `assets/` 位于 package 根目录，任务场景、地面与 terrain 资产属于 `motrix_envs`。根 package 以显式 `__all__` 提供模型类和类型化 humanoid/quadruped helper 的公共 API；框架内部从定义模块导入。注册回调由首次 robot registry 查询惰性调用；导入 package 或模型类不触发 discovery、注册、资产扫描或读取，也不加载 simulator 或训练环境
+- `motrix_robots`：可复用机器人配置、默认姿态与模型资产；仅依赖 core。框架代码从定义模块导入模型类，例如 `motrix_robots.unitree`
 - `motrix_envs`：内置环境与任务资产
 - `motrix_rl`：RL 控制平面、训练编排与稳定 contracts（runner、run/checkpoint、backend 选择、`motrix_rl.frameworks` discovery、provider/trainer 接口）
 - `motrix_rl_builtin`：内置 Motrix FastSAC provider 插件

diff --git a/README.md b/README.md
@@ -178,14 +178,14 @@ MotrixLab is a [uv](https://docs.astral.sh/uv/) workspace with the following pac
 
 | Package | PyPI name | Description |
 | --- | --- | --- |
-| **motrix_deploy** | `motrix-deploy` | Framework-independent artifacts, runtime contracts, deployment registry, and CLI |
+| **motrix_deploy** | `motrix-deploy` | Artifacts, control sessions, runtime contracts, and deployment CLI |
 | **motrix_deploy_mujoco** | `motrix-deploy-mujoco` | MuJoCo deployment backend plugin |
 | **motrix_deploy_unitree** | `motrix-deploy-unitree` | Unitree SDK2 DDS hardware backend plugin |
-| **motrix_deploy_tasks** | `motrix-deploy-tasks` | Versioned deployment tasks and executable bootstrap |
-| **motrix_env_core** | `motrix-env-core` | Backend-agnostic environment framework, configuration, registry, robot entry-point discovery, lifecycle, and rendering |
+| **motrix_deploy_tasks** | `motrix-deploy-tasks` | Walking tasks, deployment scenes, and installed Hydra recipes |
+| **motrix_env_core** | `motrix-env-core` | Backend-agnostic environment framework, configuration, registry, and rendering |
 | **motrix_env_motrixsim** | `motrix-env-motrixsim` | Live MotrixSim backend, renderer, and Torch frontend |
 | **motrix_env_mujoco** | `motrix-env-mujoco` | Compile-only MuJoCo scene backend |
-| **motrix_robots** | `motrix-robots` | Simulation robot configs, model-owned poses, and model MJCF/URDF, meshes, and model textures; core-only dependency |
+| **motrix_robots** | `motrix-robots` | Reusable robot configurations, default poses, and model assets |
 | **motrix_envs** | `motrix-envs` | Built-in environments, task assets, data, and deployment-profile compilers |
 | **motrix_rl** | `motrix-rl` | RL control plane, provider/trainer contracts, run/checkpoint handling, and discovery |
 | **motrix_rl_builtin** | `motrix-rl-builtin` | Built-in Motrix FastSAC provider |

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -178,14 +178,14 @@ MotrixLab 是一个 [uv](https://docs.astral.sh/uv/) workspace，包含以下 pa
 
 | Package | PyPI 名称 | 说明 |
 | --- | --- | --- |
-| **motrix_deploy** | `motrix-deploy` | 框架无关 artifact、运行时契约、部署 registry 与 CLI |
+| **motrix_deploy** | `motrix-deploy` | artifact、控制会话、运行时契约与部署 CLI |
 | **motrix_deploy_mujoco** | `motrix-deploy-mujoco` | MuJoCo 部署 backend plugin |
 | **motrix_deploy_unitree** | `motrix-deploy-unitree` | Unitree SDK2 DDS 硬件 backend plugin |
-| **motrix_deploy_tasks** | `motrix-deploy-tasks` | 带版本的部署任务与可执行入口 bootstrap |
-| **motrix_env_core** | `motrix-env-core` | backend 无关的环境框架、配置、registry、robot entry-point discovery、生命周期与渲染 |
+| **motrix_deploy_tasks** | `motrix-deploy-tasks` | 行走任务、部署场景与安装的 Hydra 配方 |
+| **motrix_env_core** | `motrix-env-core` | backend 无关的环境框架、配置、registry 与渲染 |
 | **motrix_env_motrixsim** | `motrix-env-motrixsim` | MotrixSim 实时仿真 backend、renderer 与 Torch frontend |
 | **motrix_env_mujoco** | `motrix-env-mujoco` | 仅负责编译场景的 MuJoCo backend |
-| **motrix_robots** | `motrix-robots` | 仿真机器人配置、模型自有姿态及 模型 MJCF/URDF、mesh 与模型纹理资产；仅依赖 core |
+| **motrix_robots** | `motrix-robots` | 可复用机器人配置、默认姿态与模型资产 |
 | **motrix_envs** | `motrix-envs` | 内置环境、任务资产、数据及部署 profile 编译实现 |
 | **motrix_rl** | `motrix-rl` | RL 控制平面、provider/trainer contract、run/checkpoint 管理与 discovery |
 | **motrix_rl_builtin** | `motrix-rl-builtin` | 内置 Motrix FastSAC provider |

diff --git a/configs/deploy/sim2real/base.yaml b/configs/deploy/sim2real/base.yaml
diff --git a/configs/deploy/sim2sim/go2_walk_flat_sim2sim.yaml b/configs/deploy/sim2sim/go2_walk_flat_sim2sim.yaml
diff --git a/configs/deploy/sim2sim/go2_walk_sim2sim.yaml b/configs/deploy/sim2sim/go2_walk_sim2sim.yaml
diff --git a/docs/source/en/user_guide/tutorial/advanced/input_devices_and_bindings.md b/docs/source/en/user_guide/tutorial/advanced/input_devices_and_bindings.md
@@ -29,10 +29,9 @@ input_devices_and_bindings/extending
 Backend-neutral InputDevice, binding, and task-command pipeline
 ```
 
-The control path from `CommandBinding` through `RobotInterface` is backend-neutral. The same binding, task command,
-`PolicyContext`, task/policy contract, and `RobotCommand` semantics can control simulation and physical-robot targets. Moving
-between the two requires replacing only the concrete device provider and `RobotInterface` implementation. A physical backend
-that implements `RobotInterface` therefore reuses the same command pipeline, task, and policy.
+`ControlSession` combines a binding, task, policy, and `RobotInterface`. It reads the command, builds the task observation,
+runs the policy, and writes a `RobotCommand`. A simulation runtime advances physics and manages the viewer; a hardware
+runtime schedules control against live robot state. Both use the same task-command semantics.
 
 A simulation and a physical robot can select different concrete devices. For example, simulation can use a GLFW keyboard
 while a physical robot uses a remote controller or network input; both reuse the same binding and task-command semantics.
@@ -58,6 +57,8 @@ A high-level task command also has the opposite direction from `RobotCommand`:
 The runtime obtains a typed task command through `CommandBinding`:
 
 ```python
+from motrix_deploy.runtime.context import PolicyContext
+
 command = command_binding.read_command(batch_size=1)
 context = PolicyContext(
     step=step,
@@ -68,7 +69,7 @@ task.validate_command(context.command)
 observation = task.build_observation(state, context)
 ```
 
-For example, MuJoCo deployment obtains a `MujocoKeyboardDevice` from the backend's `KeyboardDeviceProvider` and constructs a
+For example, MuJoCo deployment obtains a `MujocoKeyboardDevice` from the runtime's `KeyboardDeviceProvider` and constructs a
 `KeyboardPlanarVelocityBinding`. Training can use a random binding for the same `PlanarVelocityCommand`. Both paths end at the
 same typed task contract.
 

diff --git a/docs/source/en/user_guide/tutorial/advanced/motrix_deploy.md b/docs/source/en/user_guide/tutorial/advanced/motrix_deploy.md
@@ -1,119 +1,109 @@
 # Go2 Flat-Terrain Walking: From Training to Physical Deployment
 
-This tutorial follows the full Go2 flat-terrain workflow: train a policy, export an artifact, check it in MuJoCo, and run
-it on a real robot. If you already have a training run, start at “Export the artifact”.
-
-## 1. Install the environment
-
-Run this command from the repository root:
+Run an exported Go2 policy in MuJoCo before attempting hardware deployment. With the task and MuJoCo plugins installed,
+a bounded headless check is:
 
 ```bash
-sh install.sh --all
+motrix-deploy task=go2-walk-flat/sim artifact=artifacts/go2-walk-flat.deploy runtime.viewer=false duration_s=2.0
 ```
 
-This installs the training, MuJoCo, ONNX Runtime, and Unitree SDK2 dependencies.
+The following steps create that artifact, explain interactive control, and cover the existing Unitree hardware workflow.
 
-## 2. Train the policy
+## 1. Install and train
 
-If you do not have a run yet, train the flat-terrain Go2 policy:
+From the repository root:
 
 ```bash
+sh install.sh --all
+source .venv/bin/activate
 python scripts/train.py task=go2-walk-flat/rslrl.ppo
 ```
 
-Training results are saved under `runs/go2-walk-flat/`.
-
-## 3. Export the artifact
+Training results are saved under `runs/go2-walk-flat/`. Skip training if you already have a metadata-backed run.
 
-Export the latest run:
+## 2. Export and inspect the artifact
 
 ```bash
 python scripts/export_deploy.py env=go2-walk-flat
+motrix-deploy inspect artifact=artifacts/go2-walk-flat.deploy
 ```
 
-The output is written to `artifacts/go2-walk-flat.deploy/`. This artifact is the only policy bundle needed for deployment;
-it contains the model and its runtime configuration.
+Export selects the latest run and creates `artifacts/go2-walk-flat.deploy/`. To select a specific run, use
+`run=<run-dir>` instead of `env`; `output=<new-artifact-dir>` changes the destination. Existing artifact directories are
+not overwritten. Confirm that inspection reports `valid: true`.
 
-## 4. Inspect the artifact
+The artifact contains the ONNX policy, robot/control settings, and task specification. Deployment also needs the installed
+`motrix_deploy_tasks` plugin, which supplies the walking implementation, deployment scenes, and Hydra recipes, plus the
+runtime plugin for the target. The recipes work outside the repository without a workspace config path.
+Task defaults select the Hydra runtime group (`sim` or `hardware`); you do not need a separate runtime override.
+Common top-level settings are `artifact`, `duration_s`, and `command`. All target-specific settings live directly under
+`runtime`. `runtime.kind` selects the simulation or hardware path; `runtime.backend` selects the plugin (`mujoco`
+for simulation or `unitree_go2` for hardware). `runtime.backend` is a scalar string selector, not a nested configuration
+mapping or Hydra group.
 
-```bash
-motrix-deploy inspect \
-  artifact=artifacts/go2-walk-flat.deploy
-```
+## 3. Check in MuJoCo
 
-Make sure the output reports `valid: true`.
-
-## 5. Run Sim2Sim first
+Use the headless command above for a bounded run, or open the viewer:
 
 ```bash
-motrix-deploy sim2sim \
-  --config-name go2_walk_flat_sim2sim \
-  artifact=artifacts/go2-walk-flat.deploy
+motrix-deploy task=go2-walk-flat/sim artifact=artifacts/go2-walk-flat.deploy
 ```
 
-This opens the MuJoCo viewer. Use `W/S` to move forward and backward, `A/D` to move sideways, and `Q/E` to turn. Close
-the window, press Esc, or press Ctrl-C to stop.
+Hold `W/S` to move forward/backward, `A/D` sideways, and `Q/E` to turn. Close the window, press Esc, or press Ctrl-C to stop.
+The recipe selects the flat scene and the `go2` robot. Headless mode uses constant zero velocity; for a moving check, add
+`'command.velocity=[0.5,0.0,0.0]'`. Set `duration_s` for a bounded run: it allows
+`ceil(duration_s / control_period_s)` control ticks, using the artifact's control period, not a wall-clock timeout.
+Startup and shutdown may take additional wall time.
 
-## 6. Run on the real robot
+Simulation-only settings are `runtime.viewer` and `runtime.realtime`.
+`runtime.realtime=null` follows `runtime.viewer`; use `runtime.realtime=true` to pace a headless run in real time,
+or `runtime.realtime=false` to run without real-time pacing.
 
-Put the robot in low-level/debug mode, connect Ethernet, and keep an emergency stop ready. Replace `enp5s0` with the
-actual network interface:
+### Assemble a runtime in Python
 
-```bash
-motrix-deploy inspect \
-  artifact=artifacts/go2-walk-flat.deploy
-
-motrix-deploy sim2real \
-  --config-name go2_walk_flat_sim2real \
-  artifact=artifacts/go2-walk-flat.deploy \
-  backend.network_interface=enp5s0 \
-  hardware.confirm=true
-```
-
-After startup, press Start on the remote. When the default-pose transition finishes, press A. Hold L1 and move the sticks
-to send motion commands. Press B to enter the lie-down sequence; Select triggers the emergency stop.
-
-You can also inspect the robot state before sending policy commands:
+The complete `examples/deploy_to_sim.py` example composes a scene, walking task, sample ONNX policy, and input binding:
 
 ```bash
-python -m motrix_deploy_unitree.read_lowstate enp5s0
+python examples/deploy_to_sim.py --headless --steps 100
 ```
 
-## Advanced usage
+It creates a MuJoCo runtime with `create_simulation_runtime`, attaches a `ControlSession` using
+`runtime.bind_control_session(control)`, and runs inside `with runtime:`. The control session handles input, observations,
+inference, and robot commands; the runtime handles physics, timing, and the viewer. A raw ONNX file needs explicit task
+preprocessing and action settings, whereas the artifact carries those settings for the CLI.
 
-### Override policy PD gains
+## 4. Run on the real robot
 
-The physical-runtime base configuration, `configs/deploy/sim2real/base.yaml`, currently sets `backend.kp=50` and
-`backend.kd=1`, overriding the gains stored in the artifact `TaskSpec.config`. Set both fields to `null` to keep the artifact
-gains, or pass 12 non-negative values on the command line:
+Suspend the robot, put it in low-level/debug mode, connect Ethernet, and keep an independent emergency stop and operator
+ready. Startup can physically stand the robot down before the remote Start gate. Inspect the artifact first, then replace
+`enp5s0` with the actual interface:
 
 ```bash
-motrix-deploy sim2real \
+motrix-deploy task=go2-walk-flat/hardware \
   artifact=artifacts/go2-walk-flat.deploy \
-  backend.network_interface=enp5s0 \
-  'backend.kp=[20,25,30,20,25,30,22,27,32,22,27,32]' \
-  'backend.kd=[0.3,0.4,0.5,0.3,0.4,0.5,0.35,0.45,0.55,0.35,0.45,0.55]' \
-  hardware.confirm=true
+  runtime.network_interface=enp5s0
 ```
 
-### Inspect LowState without sending commands
+Hardware runs are always real-time internally; the hardware runtime has no `runtime.viewer` or `runtime.realtime` fields.
+Press Start, wait for the default-pose transition, then
+press A. Hold L1 and move the sticks to command motion. B requests lie-down; Select triggers emergency stop. Stop paths
+send damping commands before closing DDS. Software tests do not replace a suspended real-robot check.
+
+The installed hardware recipe sets `runtime.kp=50` and `runtime.kd=1`. Set both to `null` to retain artifact gains, or
+supply non-negative scalars or per-joint values in canonical joint order.
 
-Run the read-only diagnostic before sending any motion command:
+For read-only diagnostics without a command publisher:
 
 ```bash
-python -m motrix_deploy_unitree.read_lowstate enp5s0
+motrix-deploy-unitree read-lowstate enp5s0
 ```
 
-### Send a single-joint motion command
-
-To bypass the policy and debug a single joint-position motion, use the bounded helper installed with
-`motrix_deploy_unitree`. By default, it builds the control contract from the current `go2-walk-flat` deployment profile and
-does not require a training run, checkpoint, policy, or deployment artifact:
+For a bounded single-joint check, with the same hardware precautions:
 
 ```bash
-python -m motrix_deploy_unitree.go2_joint_control \
-  enp5s0 \
-  FL_thigh_joint \
-  0.9 \
-  --hardware-confirm
+motrix-deploy-unitree joint-control enp5s0 FL_thigh_joint 0.9 \
+  --artifact artifacts/go2-walk-flat.deploy
 ```
+
+This helper uses the artifact's robot, gain, timing, and limit settings. It waits for Start and A, moves the joint, holds,
+returns to the default pose, and closes with damping.